feat: export field notes

Co-authored-by: Codex <noreply@openai.com>

README.md

@@ -63,6 +63,12 @@ source, project order, and digest before the app starts.
 The app exposes a `trace_artifact` Gradio API endpoint and a `JSONL` button in the UI. Both emit the same JSONL schema:
 a manifest row followed by one row per agent turn. `data/sample_trace.jsonl` is a checked-in, Hub-published sample trace.
 
+## Field Notes Artifact
+
+The `field_notes` Gradio API endpoint and `Notes` button export a Markdown build note from the exact session state:
+builder profile, target badges, idea board, cited Spaces, latest build plan, planner calls, and the share caption. This
+keeps the Field Notes badge path tied to auditable app evidence instead of a separate hand-written summary.
+
 ## Tool-Call Contract
 
 `/api/tool-contracts` exposes the JSON schemas intended for MiniCPM-style tool calling. `tool_contract_check` accepts a

app.py

@@ -10,6 +10,7 @@ from gradio import Server
 
 from hackathon_advisor.agent import AdvisorEngine
 from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.field_notes import build_field_notes_markdown
 from hackathon_advisor.tool_contracts import resolve_tool_call, tool_schemas
 from hackathon_advisor.tools import TARGETS
 from hackathon_advisor.trace_export import build_trace_jsonl, trace_metadata
@@ -94,6 +95,21 @@ def trace_artifact(session_json: str = "{}") -> str:
     return build_trace_jsonl(session, trace_metadata(index))
 
 
+@app.api(name="field_notes", concurrency_limit=8)
+def field_notes_artifact(session_json: str = "{}") -> str:
+    try:
+        session = json.loads(session_json or "{}")
+    except json.JSONDecodeError:
+        session = {}
+    return build_field_notes_markdown(
+        session,
+        {
+            **trace_metadata(index),
+            "project_count": len(index.projects),
+        },
+    )
+
+
 @app.api(name="agent_turn", concurrency_limit=4, stream_every=0.04)
 def agent_turn(message: str, session_json: str = "{}") -> Iterator[str]:
     try:

hackathon_advisor/agent.py

@@ -353,6 +353,8 @@ class AdvisorEngine:
             }
         )
         state["trace"] = trace[-12:]
+        if plan:
+            state["last_plan"] = list(plan)
         if artifact:
             state["last_artifact"] = artifact
 

hackathon_advisor/field_notes.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def build_field_notes_markdown(session: dict[str, Any], metadata: dict[str, Any]) -> str:
+    ideas = _list_of_dicts(session.get("ideas"))
+    trace = _list_of_dicts(session.get("trace"))
+    profile = session.get("profile") if isinstance(session.get("profile"), dict) else {}
+    targets = [str(target) for target in session.get("targets") or []]
+    last_plan = [str(step) for step in session.get("last_plan") or []]
+    last_artifact = session.get("last_artifact") if isinstance(session.get("last_artifact"), dict) else {}
+
+    lines = [
+        "# Hackathon Advisor Field Notes",
+        "",
+        f"Generated: {datetime.now(timezone.utc).isoformat(timespec='seconds')}",
+        "",
+        "## Snapshot",
+        "",
+        f"- Project snapshot: {_clean(metadata.get('snapshot_generated_at'))}",
+        f"- Project count: {_clean(metadata.get('project_count', 'unknown'))}",
+        f"- Index: {_clean(metadata.get('index_algorithm'))} at {_clean(metadata.get('index_generated_at'))}",
+        f"- Digest: `{_clean(metadata.get('snapshot_digest'))}`",
+        "",
+        "## Builder Context",
+        "",
+    ]
+
+    if profile:
+        for field in ("skills", "time", "preferences", "constraints"):
+            value = _clean(profile.get(field))
+            if value:
+                lines.append(f"- {field.title()}: {value}")
+    else:
+        lines.append("- No profile notes recorded.")
+    lines.append(f"- Targets: {', '.join(targets) if targets else 'No specific targets'}")
+
+    lines.extend(["", "## Idea Board", ""])
+    if ideas:
+        for index, idea in enumerate(ideas, start=1):
+            lines.extend(_idea_section(index, idea))
+    else:
+        lines.append("No ideas were written.")
+
+    lines.extend(["", "## Build Plan", ""])
+    if last_plan:
+        for index, step in enumerate(last_plan, start=1):
+            lines.append(f"{index}. {_clean(step)}")
+    else:
+        lines.append("No build plan was pressed yet.")
+
+    lines.extend(["", "## Turn Trace", ""])
+    if trace:
+        for index, event in enumerate(trace, start=1):
+            lines.extend(_trace_section(index, event))
+    else:
+        lines.append("No tool trace was recorded.")
+
+    if last_artifact:
+        lines.extend(
+            [
+                "",
+                "## Share Caption",
+                "",
+                _clean(last_artifact.get("caption") or ""),
+            ]
+        )
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _idea_section(index: int, idea: dict[str, Any]) -> list[str]:
+    title = _clean(idea.get("title") or f"Idea {index}")
+    pitch = _clean(idea.get("pitch"))
+    targets = [str(target) for target in idea.get("targets") or []]
+    score = idea.get("score") if isinstance(idea.get("score"), dict) else {}
+    lines = [
+        f"### {index}. {title}",
+        "",
+        f"- Pitch: {pitch or 'No pitch recorded.'}",
+        f"- Targets: {', '.join(targets) if targets else 'No specific targets'}",
+    ]
+    if score:
+        lines.append(f"- Seal: {_clean(score.get('overall'))}/10 - {_clean(score.get('verdict'))}")
+        echoes = _list_of_dicts(score.get("echoes"))
+        if echoes:
+            lines.append("- Closest cited Spaces:")
+            for echo in echoes[:4]:
+                project = echo.get("project") if isinstance(echo.get("project"), dict) else {}
+                title = _clean(project.get("title") or project.get("id") or "Untitled Space")
+                url = _clean(project.get("url") or project.get("host") or "")
+                matched = ", ".join(str(term) for term in echo.get("matched_terms") or [])
+                score_text = _clean(echo.get("score"))
+                if url:
+                    lines.append(f"  - [{title}]({url}) - score {score_text}; matched {matched or 'no shared terms'}")
+                else:
+                    lines.append(f"  - {title} - score {score_text}; matched {matched or 'no shared terms'}")
+    lines.append("")
+    return lines
+
+
+def _trace_section(index: int, event: dict[str, Any]) -> list[str]:
+    tools = _list_of_dicts(event.get("tools"))
+    tool_names = " -> ".join(_clean(tool.get("name")) for tool in tools if tool.get("name")) or "reply"
+    lines = [
+        f"### Turn {index}",
+        "",
+        f"- Input: {_clean(event.get('input'))}",
+        f"- Tools: {tool_names}",
+    ]
+    verdict = _clean(event.get("verdict"))
+    overall = event.get("overall")
+    if verdict or overall is not None:
+        lines.append(f"- Verdict: {verdict or 'n/a'} {overall if overall is not None else ''}".rstrip())
+    response = _clean(event.get("response"))
+    if response:
+        lines.append(f"- Advisor note: {response}")
+    resolution = event.get("tool_resolution") if isinstance(event.get("tool_resolution"), dict) else {}
+    call = resolution.get("call") if isinstance(resolution.get("call"), dict) else {}
+    if call:
+        lines.append(f"- Planner call: `{_clean(call.get('name'))}`")
+    lines.append("")
+    return lines
+
+
+def _list_of_dicts(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, dict)]
+
+
+def _clean(value: Any) -> str:
+    if value is None:
+        return ""
+    return " ".join(str(value).split())

static/app.js

@@ -18,6 +18,7 @@ const verdictEl = document.querySelector("#verdict");
 const overallEl = document.querySelector("#overall");
 const exportButton = document.querySelector("#export-artifact");
 const exportTraceButton = document.querySelector("#export-trace");
+const exportNotesButton = document.querySelector("#export-notes");
 
 let session = {};
 let clientPromise = Client.connect(window.location.origin);
@@ -49,6 +50,10 @@ exportTraceButton.addEventListener("click", async () => {
   await exportTrace();
 });
 
+exportNotesButton.addEventListener("click", async () => {
+  await exportNotes();
+});
+
 targetsEl.addEventListener("change", (event) => {
   const target = event.target;
   if (!(target instanceof HTMLInputElement) || !target.dataset.target) return;
@@ -210,6 +215,7 @@ function handleEvent(event) {
       exportButton.disabled = false;
     }
     exportTraceButton.disabled = !(session.trace?.length);
+    exportNotesButton.disabled = !(session.trace?.length);
   }
 }
 
@@ -327,7 +333,12 @@ function setCommandDisabled(disabled) {
   document.querySelectorAll(".command-row button").forEach((button) => {
     const isArtifact = button.id === "export-artifact";
     const isTrace = button.id === "export-trace";
-    button.disabled = disabled || (isArtifact && !currentArtifact) || (isTrace && !session.trace?.length);
+    const isNotes = button.id === "export-notes";
+    button.disabled =
+      disabled ||
+      (isArtifact && !currentArtifact) ||
+      (isTrace && !session.trace?.length) ||
+      (isNotes && !session.trace?.length);
   });
 }
 
@@ -347,6 +358,15 @@ async function exportTrace() {
   downloadText("hackathon-advisor-trace.jsonl", String(data || ""));
 }
 
+async function exportNotes() {
+  const client = await clientPromise;
+  const result = await client.predict("/field_notes", {
+    session_json: JSON.stringify(session),
+  });
+  const data = Array.isArray(result.data) ? result.data[0] : result.data;
+  downloadText("hackathon-advisor-field-notes.md", String(data || ""), "text/markdown;charset=utf-8");
+}
+
 function exportArtifact(artifact) {
   const canvas = document.createElement("canvas");
   canvas.width = 1200;
@@ -402,8 +422,8 @@ function exportArtifact(artifact) {
   link.click();
 }
 
-function downloadText(filename, text) {
-  const blob = new Blob([text], { type: "application/jsonl;charset=utf-8" });
+function downloadText(filename, text, type = "application/jsonl;charset=utf-8") {
+  const blob = new Blob([text], { type });
   const link = document.createElement("a");
   link.download = filename;
   link.href = URL.createObjectURL(blob);

static/index.html

@@ -33,6 +33,7 @@
               <button type="button" data-command="make a build plan" title="Draft a build plan">Plan</button>
               <button type="button" data-command="compare ideas" title="Compare the idea board">Rank</button>
               <button type="button" id="export-trace" title="Export the tool trace" disabled>JSONL</button>
+              <button type="button" id="export-notes" title="Export Field Notes" disabled>Notes</button>
               <button type="button" id="export-artifact" title="Export the current fate page" disabled>PNG</button>
             </div>
             <div id="corrections" class="corrections" aria-live="polite"></div>

static/styles.css

@@ -167,7 +167,7 @@ button:disabled {
 
 .command-row {
   display: grid;
-  grid-template-columns: repeat(5, minmax(0, 1fr));
+  grid-template-columns: repeat(6, minmax(0, 1fr));
   gap: 8px;
   margin-top: 10px;
 }

tests/test_app.py

@@ -1,6 +1,16 @@
 import json
 
-from app import bootstrap, engine, health, index, runtime, tool_contract_check, tool_contracts, trace_artifact
+from app import (
+    bootstrap,
+    engine,
+    field_notes_artifact,
+    health,
+    index,
+    runtime,
+    tool_contract_check,
+    tool_contracts,
+    trace_artifact,
+)
 
 
 def test_health_exposes_index_metadata() -> None:
@@ -35,6 +45,22 @@ def test_trace_artifact_endpoint_exports_jsonl() -> None:
     assert lines[1]["type"] == "agent_turn"
 
 
+def test_field_notes_endpoint_exports_markdown() -> None:
+    state = engine.turn(
+        "A local-first archive cartographer for family photos",
+        {"profile": {"skills": "frontend"}, "targets": ["Field Notes"]},
+    ).state
+    state = engine.turn("make a build plan", state).state
+
+    payload = field_notes_artifact(json.dumps(state))
+
+    assert payload.startswith("# Hackathon Advisor Field Notes")
+    assert "Skills: frontend" in payload
+    assert "Targets: Field Notes" in payload
+    assert "## Turn Trace" in payload
+    assert "Record the trace and write Field Notes" in payload
+
+
 def test_tool_contracts_endpoint_exposes_schemas() -> None:
     payload = tool_contracts()
 

tests/test_field_notes.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+from hackathon_advisor.agent import AdvisorEngine
+from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.field_notes import build_field_notes_markdown
+from hackathon_advisor.trace_export import trace_metadata
+
+
+def test_field_notes_markdown_contains_session_decisions() -> None:
+    index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
+    engine = AdvisorEngine(index)
+    state = {
+        "profile": {"skills": "frontend prototyping"},
+        "targets": ["Field Notes"],
+    }
+    first = engine.turn("A local-first archive cartographer for family photos", state)
+    planned = engine.turn("make a build plan", first.state)
+
+    markdown = build_field_notes_markdown(
+        planned.state,
+        {
+            **trace_metadata(index),
+            "project_count": len(index.projects),
+        },
+    )
+
+    assert "# Hackathon Advisor Field Notes" in markdown
+    assert "frontend prototyping" in markdown
+    assert "Targets: Field Notes" in markdown
+    assert "A local-first archive cartographer for family photos" in markdown
+    assert "## Build Plan" in markdown
+    assert "Record the trace and write Field Notes" in markdown
+    assert "Closest cited Spaces" in markdown
+    assert "Planner call: `make_plan`" in markdown