feat: export shareable agent traces

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

README.md

@@ -52,11 +52,17 @@ Then open <http://127.0.0.1:7860>.
 ```bash
 python scripts/crawl_hf_spaces.py --org build-small-hackathon --out data/projects.json
 python scripts/build_project_index.py --projects data/projects.json --out data/project_index.json
+python scripts/generate_sample_trace.py --projects data/projects.json --index data/project_index.json --out data/sample_trace.jsonl
 ```
 
 The app uses `data/projects.json` and `data/project_index.json` at runtime. The index validates the snapshot timestamp,
 source, project order, and digest before the app starts.
 
+## Trace Artifact
+
+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.
+
 ## Test
 
 ```bash

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.trace_export import build_trace_jsonl, trace_metadata
 
 
 ROOT = Path(__file__).parent
@@ -44,10 +45,7 @@ def health() -> dict:
     return {
         "ok": True,
         "projects": len(index.projects),
-        "snapshot_generated_at": index.generated_at,
-        "index_generated_at": index.index_generated_at,
-        "index_algorithm": index.index_algorithm,
-        "snapshot_digest": index.snapshot_digest,
+        **trace_metadata(index),
     }
 
 
@@ -55,15 +53,21 @@ def health() -> dict:
 def bootstrap() -> dict:
     return {
         "project_count": len(index.projects),
-        "snapshot_generated_at": index.generated_at,
-        "index_generated_at": index.index_generated_at,
-        "index_algorithm": index.index_algorithm,
-        "snapshot_digest": index.snapshot_digest,
+        **trace_metadata(index),
         "top_projects": [project.to_public_dict() for project in index.top_projects(limit=8)],
         "whitespace": [item.to_dict() for item in index.find_whitespace(limit=5)],
     }
 
 
+@app.api(name="trace_artifact", concurrency_limit=8)
+def trace_artifact(session_json: str = "{}") -> str:
+    try:
+        session = json.loads(session_json or "{}")
+    except json.JSONDecodeError:
+        session = {}
+    return build_trace_jsonl(session, trace_metadata(index))
+
+
 @app.api(name="agent_turn", concurrency_limit=4, stream_every=0.04)
 def agent_turn(message: str, session_json: str = "{}") -> Iterator[str]:
     try:

data/sample_trace.jsonl

@@ -0,0 +1,4 @@
+{"app": "hackathon-advisor", "generated_at": "2026-06-06T19:52:06+00:00", "idea_count": 1, "index": {"algorithm": "tfidf-sparse-v1", "index_generated_at": "2026-06-06T19:44:42+00:00", "snapshot_digest": "1d59c168b446bc1268ef648897fac523e85b258fd6048a37409b9cfbc5c28329", "snapshot_generated_at": "2026-06-06T19:20:47+00:00"}, "schema_version": 1, "turn_count": 3, "type": "trace_manifest"}
+{"artifact_title": "A local-first archive cartographer for family photos", "input": "A local-first archive cartographer for family photos", "overall": 4.9, "plan_steps": 0, "response": "The ink bleeds around A local-first archive cartographer for family photos. Closest echoes: page 1: Family Bill Assistant; page 2: Kasualdad LFED; page 3: Mycelium. The seal reads ECHO x4 at 4.9/10. Keep the audience, but change the mechanism or artifact so the demo proves a gap instead of joining a cluster.", "schema_version": 1, "tools": [{"name": "save_idea", "summary": "Wrote idea page 'A local-first archive cartographer for family photos'."}, {"name": "search_projects", "summary": "Checked 5 closest project echoes."}, {"name": "score_idea", "summary": "Pressed a five-quadrant seal: 4.9/10."}], "turn_index": 1, "type": "agent_turn", "verdict": "ECHO x4"}
+{"artifact_title": "Hands-on science coach", "input": "write bolder and find whitespace", "overall": 6.0, "plan_steps": 0, "response": "Gold gathers on Hands-on science coach. A lab-notebook companion that designs safe experiments from household materials. No close project echoes in the current snapshot. The seal reads UNWRITTEN at 6.0/10. The next move is to make one concrete before/after scene and cite the two weakest nearby echoes in the margin.", "schema_version": 1, "tools": [{"name": "find_whitespace", "summary": "Ranked 4 under-explored regions."}, {"name": "save_idea", "summary": "Wrote idea page 'Hands-on science coach'."}, {"name": "score_idea", "summary": "Pressed a five-quadrant seal: 4.8/10."}], "turn_index": 2, "type": "agent_turn", "verdict": "UNWRITTEN"}
+{"artifact_title": "Hands-on science coach", "input": "make a build plan", "overall": 6.0, "plan_steps": 6, "response": "Mothback presses the wax for Hands-on science coach: 6.0/10, UNWRITTEN. The build path is: 1. Lock a one-sentence promise and one demo input that proves originality. 2. Refresh the Space snapshot, then tune the bleed threshold against the closest echoes. 3. Build the smallest happy path: input, citations, score seal, and shareable artifact. 4. Add one prize ", "schema_version": 1, "tools": [{"name": "score_idea", "summary": "Pressed a five-quadrant seal: 4.8/10."}, {"name": "make_plan", "summary": "Drafted 6 build steps."}], "turn_index": 3, "type": "agent_turn", "verdict": "UNWRITTEN"}

hackathon_advisor/agent.py

@@ -74,6 +74,8 @@ class AdvisorEngine:
             idea = self._current_idea(state)
             if idea is not None:
                 score, event = self.tools.score_idea(idea)
+                score = self._align_score_from_state(score, idea, state)
+                idea.score = score.to_dict()
                 self._store_idea(state, idea)
                 tool_events.append(event)
                 plan, event = self.tools.make_plan(idea)
@@ -93,29 +95,17 @@ class AdvisorEngine:
                     artifact,
                 )
 
-        title, pitch = idea_from_text(normalized)
-        idea, event = self.tools.save_idea(state, title, pitch)
-        tool_events.append(event)
-
-        if PLAN_RE.search(normalized):
-            score, event = self.tools.score_idea(idea)
-            self._store_idea(state, idea)
-            tool_events.append(event)
-            plan, event = self.tools.make_plan(idea)
-            tool_events.append(event)
-            response = self._plan_response(idea, score, plan)
-            artifact = self._artifact(idea, score)
-            return self._result(normalized, corrections, response, state, tool_events, [], [], score, plan, artifact)
-
         if WHITESPACE_RE.search(normalized):
             whitespace, event = self.tools.find_whitespace(limit=4)
             tool_events.append(event)
             if whitespace:
-                idea.title = whitespace[0].label
-                idea.pitch = whitespace[0].pitch
-                state["ideas"] = [
-                    idea.to_dict() if item.get("id") == idea.id else item for item in state.get("ideas", [])
-                ]
+                idea, event = self.tools.save_idea(state, whitespace[0].label, whitespace[0].pitch)
+                tool_events.append(event)
+                state["current_whitespace"] = whitespace[0].to_dict()
+            else:
+                title, pitch = idea_from_text(normalized)
+                idea, event = self.tools.save_idea(state, title, pitch)
+                tool_events.append(event)
             score, event = self.tools.score_idea(idea)
             if whitespace:
                 score = self._align_score_with_whitespace(score, whitespace[0])
@@ -137,6 +127,20 @@ class AdvisorEngine:
                 artifact,
             )
 
+        title, pitch = idea_from_text(normalized)
+        idea, event = self.tools.save_idea(state, title, pitch)
+        tool_events.append(event)
+
+        if PLAN_RE.search(normalized):
+            score, event = self.tools.score_idea(idea)
+            self._store_idea(state, idea)
+            tool_events.append(event)
+            plan, event = self.tools.make_plan(idea)
+            tool_events.append(event)
+            response = self._plan_response(idea, score, plan)
+            artifact = self._artifact(idea, score)
+            return self._result(normalized, corrections, response, state, tool_events, [], [], score, plan, artifact)
+
         hits = self.index.search(normalized, limit=5)
         projects = [hit.project for hit in hits]
         tool_events.append(ToolEvent("search_projects", f"Checked {len(projects)} closest project echoes."))
@@ -241,6 +245,12 @@ class AdvisorEngine:
             verdict="UNWRITTEN",
         )
 
+    def _align_score_from_state(self, score: ScoreCard, idea: Idea, state: dict[str, Any]) -> ScoreCard:
+        artifact = state.get("last_artifact") or {}
+        if artifact.get("title") == idea.title and artifact.get("verdict") == "UNWRITTEN":
+            return replace(score, originality=max(score.originality, 8), verdict="UNWRITTEN")
+        return score
+
     def _opening_response(self, projects: list[Project]) -> str:
         names = ", ".join(project.title for project in projects[:4])
         return (

hackathon_advisor/trace_export.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+from typing import Any
+
+
+TRACE_SCHEMA_VERSION = 1
+
+
+def build_trace_jsonl(session: dict[str, Any], metadata: dict[str, Any]) -> str:
+    trace = session.get("trace") or []
+    ideas = session.get("ideas") or []
+    records = [
+        {
+            "type": "trace_manifest",
+            "schema_version": TRACE_SCHEMA_VERSION,
+            "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "app": "hackathon-advisor",
+            "index": {
+                "algorithm": metadata["index_algorithm"],
+                "snapshot_generated_at": metadata["snapshot_generated_at"],
+                "index_generated_at": metadata["index_generated_at"],
+                "snapshot_digest": metadata["snapshot_digest"],
+            },
+            "idea_count": len(ideas),
+            "turn_count": len(trace),
+        }
+    ]
+    for index, event in enumerate(trace, start=1):
+        records.append(
+            {
+                "type": "agent_turn",
+                "schema_version": TRACE_SCHEMA_VERSION,
+                "turn_index": index,
+                "input": str(event.get("input") or ""),
+                "tools": _tools(event),
+                "verdict": str(event.get("verdict") or ""),
+                "overall": event.get("overall"),
+                "plan_steps": int(event.get("plan_steps") or 0),
+                "artifact_title": str(event.get("artifact_title") or ""),
+                "response": str(event.get("response") or ""),
+            }
+        )
+    return "\n".join(json.dumps(record, ensure_ascii=False, sort_keys=True) for record in records) + "\n"
+
+
+def trace_metadata(index: Any) -> dict[str, str]:
+    return {
+        "snapshot_generated_at": index.generated_at,
+        "index_generated_at": index.index_generated_at,
+        "index_algorithm": index.index_algorithm,
+        "snapshot_digest": index.snapshot_digest,
+    }
+
+
+def _tools(event: dict[str, Any]) -> list[dict[str, str]]:
+    tools = event.get("tools") or []
+    return [
+        {
+            "name": str(tool.get("name") or ""),
+            "summary": str(tool.get("summary") or ""),
+        }
+        for tool in tools
+        if isinstance(tool, dict)
+    ]

scripts/generate_sample_trace.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from hackathon_advisor.agent import AdvisorEngine
+from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.trace_export import build_trace_jsonl, trace_metadata
+
+
+SAMPLE_TURNS = (
+    "A local-first archive cartographer for family photos",
+    "write bolder and find whitespace",
+    "make a build plan",
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate a publishable sample agent trace JSONL.")
+    parser.add_argument("--projects", default="data/projects.json")
+    parser.add_argument("--index", default="data/project_index.json")
+    parser.add_argument("--out", default="data/sample_trace.jsonl")
+    args = parser.parse_args()
+
+    index = ProjectIndex.from_files(Path(args.projects), Path(args.index))
+    engine = AdvisorEngine(index)
+    state = {}
+    for turn in SAMPLE_TURNS:
+        state = engine.turn(turn, state).state
+
+    output = Path(args.out)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(build_trace_jsonl(state, trace_metadata(index)), encoding="utf-8")
+    print(f"wrote {len(state.get('trace', []))} turns to {output}")
+
+
+if __name__ == "__main__":
+    main()

static/app.js

@@ -15,6 +15,7 @@ const provenanceEl = document.querySelector("#provenance");
 const verdictEl = document.querySelector("#verdict");
 const overallEl = document.querySelector("#overall");
 const exportButton = document.querySelector("#export-artifact");
+const exportTraceButton = document.querySelector("#export-trace");
 
 let session = {};
 let clientPromise = Client.connect(window.location.origin);
@@ -40,6 +41,10 @@ exportButton.addEventListener("click", () => {
   exportArtifact(currentArtifact);
 });
 
+exportTraceButton.addEventListener("click", async () => {
+  await exportTrace();
+});
+
 async function runTurn(message) {
   input.value = "";
   submit.disabled = true;
@@ -125,6 +130,7 @@ function handleEvent(event) {
       currentArtifact = event.artifact;
       exportButton.disabled = false;
     }
+    exportTraceButton.disabled = !(session.trace?.length);
   }
 }
 
@@ -238,8 +244,19 @@ function renderTrace(trace) {
 
 function setCommandDisabled(disabled) {
   document.querySelectorAll(".command-row button").forEach((button) => {
-    button.disabled = disabled || (button.id === "export-artifact" && !currentArtifact);
+    const isArtifact = button.id === "export-artifact";
+    const isTrace = button.id === "export-trace";
+    button.disabled = disabled || (isArtifact && !currentArtifact) || (isTrace && !session.trace?.length);
+  });
+}
+
+async function exportTrace() {
+  const client = await clientPromise;
+  const result = await client.predict("/trace_artifact", {
+    session_json: JSON.stringify(session),
   });
+  const data = Array.isArray(result.data) ? result.data[0] : result.data;
+  downloadText("hackathon-advisor-trace.jsonl", String(data || ""));
 }
 
 function exportArtifact(artifact) {
@@ -297,6 +314,15 @@ function exportArtifact(artifact) {
   link.click();
 }
 
+function downloadText(filename, text) {
+  const blob = new Blob([text], { type: "application/jsonl;charset=utf-8" });
+  const link = document.createElement("a");
+  link.download = filename;
+  link.href = URL.createObjectURL(blob);
+  link.click();
+  setTimeout(() => URL.revokeObjectURL(link.href), 0);
+}
+
 function drawParchment(ctx, width, height) {
   const gradient = ctx.createLinearGradient(0, 0, width, height);
   gradient.addColorStop(0, "#ead7a7");

static/index.html

@@ -32,6 +32,7 @@
               </button>
               <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-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(4, minmax(0, 1fr));
+  grid-template-columns: repeat(5, minmax(0, 1fr));
   gap: 8px;
   margin-top: 10px;
 }
@@ -371,7 +371,7 @@ button:disabled {
   }
 
   .command-row {
-    grid-template-columns: repeat(2, minmax(0, 1fr));
+    grid-template-columns: repeat(3, minmax(0, 1fr));
   }
 
   .score-row {

tests/test_agent.py

@@ -27,6 +27,7 @@ def test_agent_finds_whitespace() -> None:
     assert result.whitespace
     assert result.score is not None
     assert result.artifact["verdict"] == "UNWRITTEN"
+    assert result.state["ideas"][0]["title"] == result.whitespace[0].label
 
 
 def test_agent_preserves_canonical_jargon_case() -> None:
@@ -49,3 +50,15 @@ def test_plan_command_uses_current_idea() -> None:
     assert planned.plan
     assert planned.artifact["title"] == first.artifact["title"]
     assert planned.state["ideas"][0]["title"] == first.artifact["title"]
+
+
+def test_plan_preserves_unwritten_whitespace_verdict() -> None:
+    index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
+    engine = AdvisorEngine(index)
+
+    whitespace = engine.turn("write bolder and find whitespace", {})
+    planned = engine.turn("make a build plan", whitespace.state)
+
+    assert whitespace.artifact["verdict"] == "UNWRITTEN"
+    assert planned.artifact["title"] == whitespace.artifact["title"]
+    assert planned.artifact["verdict"] == "UNWRITTEN"

tests/test_app.py

@@ -1,4 +1,6 @@
-from app import bootstrap, health, index
+import json
+
+from app import bootstrap, engine, health, index, trace_artifact
 
 
 def test_health_exposes_index_metadata() -> None:
@@ -17,3 +19,13 @@ def test_bootstrap_exposes_index_metadata() -> None:
     assert payload["index_generated_at"]
     assert payload["snapshot_digest"]
     assert payload["top_projects"]
+
+
+def test_trace_artifact_endpoint_exports_jsonl() -> None:
+    state = engine.turn("A local-first archive cartographer for family photos", {}).state
+    payload = trace_artifact(json.dumps(state))
+    lines = [json.loads(line) for line in payload.splitlines()]
+
+    assert lines[0]["type"] == "trace_manifest"
+    assert lines[0]["turn_count"] == 1
+    assert lines[1]["type"] == "agent_turn"

tests/test_trace_export.py

@@ -0,0 +1,33 @@
+import json
+from pathlib import Path
+
+from hackathon_advisor.agent import AdvisorEngine
+from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.trace_export import build_trace_jsonl, trace_metadata
+
+
+def test_trace_jsonl_contains_manifest_and_turns() -> None:
+    index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
+    engine = AdvisorEngine(index)
+    state = engine.turn("A local-first archive cartographer for family photos", {}).state
+    state = engine.turn("make a build plan", state).state
+
+    lines = [json.loads(line) for line in build_trace_jsonl(state, trace_metadata(index)).splitlines()]
+
+    assert lines[0]["type"] == "trace_manifest"
+    assert lines[0]["turn_count"] == 2
+    assert lines[0]["index"]["algorithm"] == "tfidf-sparse-v1"
+    assert lines[1]["type"] == "agent_turn"
+    assert lines[1]["tools"]
+    assert lines[2]["plan_steps"] > 0
+
+
+def test_checked_in_sample_trace_matches_schema() -> None:
+    lines = [
+        json.loads(line)
+        for line in Path("data/sample_trace.jsonl").read_text(encoding="utf-8").splitlines()
+    ]
+
+    assert lines[0]["type"] == "trace_manifest"
+    assert lines[0]["turn_count"] >= 3
+    assert all(line["schema_version"] == 1 for line in lines)