feat: export submission packet

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

README.md

@@ -82,6 +82,13 @@ turns. Each included turn yields a tool-call example and an advisor-response exa
 selected targets, parsed XML tool call, tool observations, and score context preserved. This prepares the Well-Tuned
 path without claiming that the adapter has already been trained or published.
 
+## Submission Packet
+
+The `submission_packet` Gradio API endpoint and `Packet` button export a Markdown submission bundle for the current
+session: live links, snapshot provenance, a timed demo script, artifact checklist, Prize Ledger evidence, model budget,
+session trace summary, social post draft, and open badge gaps. This keeps the final submission story tied to the same
+auditable state as the app instead of a separate hand-curated checklist.
+
 ## Prize Ledger
 
 `/api/prize-ledger` and the in-app Prize Ledger panel expose submission evidence: the documented model stack, total

app.py

@@ -14,6 +14,7 @@ from hackathon_advisor.data import ProjectIndex
 from hackathon_advisor.field_notes import build_field_notes_markdown
 from hackathon_advisor.lora_dataset import build_lora_dataset_jsonl
 from hackathon_advisor.prize_ledger import prize_ledger
+from hackathon_advisor.submission_packet import build_submission_packet_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
@@ -150,6 +151,23 @@ def lora_dataset_artifact(session_json: str = "{}") -> str:
     )
 
 
+@app.api(name="submission_packet", concurrency_limit=8)
+def submission_packet_artifact(session_json: str = "{}") -> str:
+    try:
+        session = json.loads(session_json or "{}")
+    except json.JSONDecodeError:
+        session = {}
+    runtime_status = engine.runtime_status()
+    return build_submission_packet_markdown(
+        session,
+        {
+            **trace_metadata(index),
+            "project_count": len(index.projects),
+        },
+        prize_ledger(runtime_status),
+    )
+
+
 @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/submission_packet.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+SPACE_URL = "https://huggingface.co/spaces/build-small-hackathon/hackathon-advisor"
+LIVE_URL = "https://build-small-hackathon-hackathon-advisor.hf.space"
+GITHUB_URL = "https://github.com/JacobLinCool/hackathon-advisor"
+
+
+def build_submission_packet_markdown(
+    session: dict[str, Any],
+    metadata: dict[str, Any],
+    ledger: dict[str, Any],
+) -> str:
+    ideas = _list_of_dicts(session.get("ideas"))
+    trace = _list_of_dicts(session.get("trace"))
+    targets = [str(target) for target in session.get("targets") or []]
+    last_plan = [str(step) for step in session.get("last_plan") or []]
+    current = _current_idea(session, ideas)
+    score = current.get("score") if isinstance(current.get("score"), dict) else {}
+    verdict = _clean(score.get("verdict")) if score else "DRAFT"
+    overall = _clean(score.get("overall")) if score else "0.0"
+    title = _clean(current.get("title") or "Unwritten Page")
+
+    lines = [
+        "# Hackathon Advisor Submission Packet",
+        "",
+        f"Generated: {datetime.now(timezone.utc).isoformat(timespec='seconds')}",
+        "",
+        "## Links",
+        "",
+        f"- Live Space: {LIVE_URL}",
+        f"- Hugging Face repository: {SPACE_URL}",
+        f"- GitHub repository: {GITHUB_URL}",
+        "",
+        "## 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'))}`",
+        "",
+        "## Current Demo Page",
+        "",
+        f"- Title: {title}",
+        f"- Verdict: {verdict} {overall}/10",
+        f"- Targets: {', '.join(targets) if targets else 'No specific targets'}",
+        f"- Pitch: {_clean(current.get('pitch')) or 'No pitch recorded.'}",
+        "",
+    ]
+
+    lines.extend(_demo_script(title, verdict, overall, current, trace, last_plan))
+    lines.extend(_artifact_checklist(trace, ideas, session))
+    lines.extend(_prize_evidence(ledger))
+    lines.extend(_model_budget(ledger))
+    lines.extend(_session_summary(ideas, trace, last_plan))
+    lines.extend(_social_post(title, verdict, ledger))
+    lines.extend(_open_gaps(ledger))
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _demo_script(
+    title: str,
+    verdict: str,
+    overall: str,
+    idea: dict[str, Any],
+    trace: list[dict[str, Any]],
+    last_plan: list[str],
+) -> list[str]:
+    echoes = _echoes(idea)
+    first_echo = echoes[0] if echoes else {}
+    project = first_echo.get("project") if isinstance(first_echo.get("project"), dict) else {}
+    echo_title = _clean(project.get("title") or project.get("id") or "a cited Space")
+    page = _clean(first_echo.get("page_number")) or "?"
+    plan_step = _clean(last_plan[0]) if last_plan else "Press Plan to show the build path."
+    turn_count = len(trace)
+    return [
+        "## Demo Script",
+        "",
+        "| Time | Beat | On-screen proof |",
+        "| --- | --- | --- |",
+        f"| 0:00 | Open The Unwritten Almanac and point to the local snapshot count. | Snapshot metadata and Prize Ledger are visible. |",
+        f"| 0:10 | Type the project instinct for `{title}`. | Streaming response starts, then the seal reads {verdict} at {overall}/10. |",
+        f"| 0:30 | Show the nearest echo. | Page {page}: {echo_title}. |",
+        f"| 0:45 | Press Gap or Plan to move from diagnosis to build path. | {plan_step} |",
+        f"| 1:05 | Export evidence artifacts. | JSONL, Notes, Chapter, LoRA, Packet, and PNG buttons are available after {turn_count} recorded turns. |",
+        "| 1:20 | Close with prize honesty. | Ready badges and planned badges are separated in the Prize Ledger. |",
+        "",
+    ]
+
+
+def _artifact_checklist(trace: list[dict[str, Any]], ideas: list[dict[str, Any]], session: dict[str, Any]) -> list[str]:
+    has_trace = bool(trace)
+    has_ideas = bool(ideas)
+    has_artifact = isinstance(session.get("last_artifact"), dict) and bool(session["last_artifact"].get("title"))
+    rows = [
+        ("Tool trace JSONL", has_trace, "trace_artifact"),
+        ("Field Notes markdown", has_trace, "field_notes"),
+        ("Almanac chapter markdown", has_ideas, "chapter"),
+        ("MiniCPM5 LoRA SFT JSONL", has_trace, "lora_dataset"),
+        ("Submission packet markdown", True, "submission_packet"),
+        ("Fate page PNG", has_artifact, "client-side canvas export"),
+    ]
+    lines = ["## Artifact Checklist", "", "| Artifact | Status | Source |", "| --- | --- | --- |"]
+    for name, ready, source in rows:
+        lines.append(f"| {name} | {'ready' if ready else 'needs session'} | {source} |")
+    lines.append("")
+    return lines
+
+
+def _prize_evidence(ledger: dict[str, Any]) -> list[str]:
+    lines = ["## Prize Evidence", "", "| Prize path | Status | Evidence |", "| --- | --- | --- |"]
+    for badge in _list_of_dicts(ledger.get("badges")):
+        lines.append(
+            "| "
+            + " | ".join(
+                [
+                    _clean(badge.get("name")),
+                    _clean(badge.get("status")),
+                    _clean(badge.get("evidence")),
+                ]
+            )
+            + " |"
+        )
+    lines.append("")
+    return lines
+
+
+def _model_budget(ledger: dict[str, Any]) -> list[str]:
+    total = _clean(ledger.get("total_params_b"))
+    limit = _clean(ledger.get("tiny_titan_limit_b"))
+    eligible = "yes" if ledger.get("tiny_titan_eligible") else "no"
+    lines = [
+        "## Model Budget",
+        "",
+        f"- Total documented stack: {total}B params",
+        f"- Tiny Titan limit: {limit}B params",
+        f"- Tiny Titan eligible: {eligible}",
+        "",
+        "| Role | Model | Params | Status | Runtime |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for item in _list_of_dicts(ledger.get("model_stack")):
+        lines.append(
+            "| "
+            + " | ".join(
+                [
+                    _clean(item.get("role")),
+                    _clean(item.get("model")),
+                    f"{_clean(item.get('params_b'))}B",
+                    _clean(item.get("status")),
+                    _clean(item.get("runtime")),
+                ]
+            )
+            + " |"
+        )
+    lines.append("")
+    return lines
+
+
+def _session_summary(ideas: list[dict[str, Any]], trace: list[dict[str, Any]], last_plan: list[str]) -> list[str]:
+    lines = ["## Session Evidence", ""]
+    if ideas:
+        lines.extend(["### Idea Board", ""])
+        for index, idea in enumerate(ideas[-4:], start=max(1, len(ideas) - 3)):
+            score = idea.get("score") if isinstance(idea.get("score"), dict) else {}
+            verdict = _clean(score.get("verdict")) if score else "DRAFT"
+            overall = _clean(score.get("overall")) if score else "0.0"
+            lines.append(f"- {index}. {_clean(idea.get('title'))}: {verdict} {overall}/10")
+    else:
+        lines.append("- No ideas recorded yet.")
+
+    lines.extend(["", "### Latest 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 recorded yet.")
+
+    lines.extend(["", "### Tool Trace", ""])
+    if trace:
+        for index, event in enumerate(trace[-5:], start=max(1, len(trace) - 4)):
+            tools = " -> ".join(
+                _clean(tool.get("name")) for tool in _list_of_dicts(event.get("tools")) if tool.get("name")
+            )
+            lines.append(f"- Turn {index}: {_clean(event.get('input'))} [{tools or 'reply'}]")
+    else:
+        lines.append("- No tool trace recorded yet.")
+    lines.append("")
+    return lines
+
+
+def _social_post(title: str, verdict: str, ledger: dict[str, Any]) -> list[str]:
+    ready = sum(1 for badge in _list_of_dicts(ledger.get("badges")) if badge.get("status") == "ready")
+    total = len(_list_of_dicts(ledger.get("badges")))
+    return [
+        "## Social Post Draft",
+        "",
+        (
+            "I built Hackathon Advisor, a small-model originality coach for Build Small. "
+            f"The Unwritten Almanac checks `{title}` against a local snapshot of real Spaces, cites overlap, "
+            f"and exports the evidence trail. Latest seal: {verdict}. Prize ledger: {ready}/{total} ready."
+        ),
+        "",
+        f"Live: {LIVE_URL}",
+        "",
+    ]
+
+
+def _open_gaps(ledger: dict[str, Any]) -> list[str]:
+    pending = [
+        badge
+        for badge in _list_of_dicts(ledger.get("badges"))
+        if badge.get("status") not in {"ready", "eligible"}
+    ]
+    lines = ["## Open Gaps", ""]
+    if pending:
+        for badge in pending:
+            lines.append(f"- {_clean(badge.get('name'))}: {_clean(badge.get('status'))} - {_clean(badge.get('evidence'))}")
+    else:
+        lines.append("- No non-ready badge states reported by the current ledger.")
+    lines.append("")
+    return lines
+
+
+def _current_idea(session: dict[str, Any], ideas: list[dict[str, Any]]) -> dict[str, Any]:
+    current_id = _clean(session.get("current_idea_id"))
+    if current_id:
+        for idea in ideas:
+            if _clean(idea.get("id")) == current_id:
+                return idea
+    if ideas:
+        return ideas[-1]
+    return {}
+
+
+def _echoes(idea: dict[str, Any]) -> list[dict[str, Any]]:
+    score = idea.get("score") if isinstance(idea.get("score"), dict) else {}
+    return _list_of_dicts(score.get("echoes"))
+
+
+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

@@ -23,6 +23,7 @@ const exportTraceButton = document.querySelector("#export-trace");
 const exportNotesButton = document.querySelector("#export-notes");
 const exportChapterButton = document.querySelector("#export-chapter");
 const exportLoraButton = document.querySelector("#export-lora");
+const exportPacketButton = document.querySelector("#export-packet");
 const resetButton = document.querySelector("#reset-session");
 
 const SESSION_STORAGE_KEY = "hackathon-advisor-session-v1";
@@ -71,6 +72,10 @@ exportLoraButton.addEventListener("click", async () => {
   await exportLoraDataset();
 });
 
+exportPacketButton.addEventListener("click", async () => {
+  await exportSubmissionPacket();
+});
+
 resetButton.addEventListener("click", () => {
   clearSavedSession();
   window.location.reload();
@@ -189,6 +194,7 @@ function renderRestoredSession(data) {
   exportNotesButton.disabled = !(session.trace?.length);
   exportChapterButton.disabled = !(session.ideas?.length);
   exportLoraButton.disabled = !(session.trace?.length);
+  exportPacketButton.disabled = !(session.trace?.length);
 }
 
 function readSavedSession() {
@@ -372,6 +378,7 @@ function handleEvent(event) {
     exportNotesButton.disabled = !(session.trace?.length);
     exportChapterButton.disabled = !(session.ideas?.length);
     exportLoraButton.disabled = !(session.trace?.length);
+    exportPacketButton.disabled = !(session.trace?.length);
     saveSession();
   }
 }
@@ -548,13 +555,15 @@ function setCommandDisabled(disabled) {
     const isNotes = button.id === "export-notes";
     const isChapter = button.id === "export-chapter";
     const isLora = button.id === "export-lora";
+    const isPacket = button.id === "export-packet";
     button.disabled =
       disabled ||
       (isArtifact && !currentArtifact) ||
       (isTrace && !session.trace?.length) ||
       (isNotes && !session.trace?.length) ||
       (isChapter && !session.ideas?.length) ||
-      (isLora && !session.trace?.length);
+      (isLora && !session.trace?.length) ||
+      (isPacket && !session.trace?.length);
   });
 }
 
@@ -627,6 +636,15 @@ async function exportLoraDataset() {
   downloadText("hackathon-advisor-lora-sft.jsonl", String(data || ""));
 }
 
+async function exportSubmissionPacket() {
+  const client = await clientPromise;
+  const result = await client.predict("/submission_packet", {
+    session_json: JSON.stringify(session),
+  });
+  const data = Array.isArray(result.data) ? result.data[0] : result.data;
+  downloadText("hackathon-advisor-submission-packet.md", String(data || ""), "text/markdown;charset=utf-8");
+}
+
 function exportArtifact(artifact) {
   const canvas = document.createElement("canvas");
   canvas.width = 1200;

static/index.html

@@ -36,6 +36,7 @@
               <button type="button" id="export-notes" title="Export Field Notes" disabled>Notes</button>
               <button type="button" id="export-chapter" title="Export the Almanac chapter" disabled>Chapter</button>
               <button type="button" id="export-lora" title="Export the LoRA SFT dataset" disabled>LoRA</button>
+              <button type="button" id="export-packet" title="Export the submission packet" disabled>Packet</button>
               <button type="button" id="export-artifact" title="Export the current fate page" disabled>PNG</button>
               <button type="button" id="reset-session" title="Clear the saved session">Reset</button>
             </div>

tests/test_app.py

@@ -10,6 +10,7 @@ from app import (
     lora_dataset_artifact,
     prize_ledger_endpoint,
     runtime,
+    submission_packet_artifact,
     tool_contract_check,
     tool_contracts,
     trace_artifact,
@@ -94,6 +95,21 @@ def test_lora_dataset_endpoint_exports_sft_jsonl() -> None:
     assert lines[2]["example_kind"] == "advisor_response"
 
 
+def test_submission_packet_endpoint_exports_markdown() -> None:
+    state = engine.turn(
+        "A local-first archive cartographer for family photos",
+        {"targets": ["Field Notes"]},
+    ).state
+    state = engine.turn("make a build plan", state).state
+
+    payload = submission_packet_artifact(json.dumps(state))
+
+    assert payload.startswith("# Hackathon Advisor Submission Packet")
+    assert "## Demo Script" in payload
+    assert "## Prize Evidence" in payload
+    assert "Live Space:" in payload
+
+
 def test_tool_contracts_endpoint_exposes_schemas() -> None:
     payload = tool_contracts()
 

tests/test_submission_packet.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+from hackathon_advisor.agent import AdvisorEngine
+from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.prize_ledger import prize_ledger
+from hackathon_advisor.submission_packet import build_submission_packet_markdown
+from hackathon_advisor.trace_export import trace_metadata
+
+
+def test_submission_packet_contains_demo_and_prize_evidence() -> None:
+    index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
+    engine = AdvisorEngine(index)
+    state = {"targets": ["Well-Tuned", "Field Notes"]}
+    state = engine.turn("A local-first archive cartographer for family photos", state).state
+    state = engine.turn("make a build plan", state).state
+
+    markdown = build_submission_packet_markdown(
+        state,
+        {
+            **trace_metadata(index),
+            "project_count": len(index.projects),
+        },
+        prize_ledger(engine.runtime_status()),
+    )
+
+    assert markdown.startswith("# Hackathon Advisor Submission Packet")
+    assert "## Demo Script" in markdown
+    assert "## Artifact Checklist" in markdown
+    assert "## Prize Evidence" in markdown
+    assert "## Model Budget" in markdown
+    assert "## Social Post Draft" in markdown
+    assert "Hackathon Advisor" in markdown
+    assert "Well-Tuned | dataset-ready" in markdown
+    assert "MiniCPM5 LoRA SFT JSONL | ready | lora_dataset" in markdown
+    assert "Ready badges and planned badges are separated" in markdown
+    assert "A local-first archive cartographer for family photos" in markdown
+
+
+def test_empty_submission_packet_is_honest_about_missing_session_artifacts() -> None:
+    markdown = build_submission_packet_markdown(
+        {},
+        {
+            "snapshot_generated_at": "2026-06-06T00:00:00+00:00",
+            "project_count": 100,
+            "index_algorithm": "tfidf-sparse-v1",
+            "index_generated_at": "2026-06-06T01:00:00+00:00",
+            "snapshot_digest": "abc",
+        },
+        prize_ledger({"backend": "rules", "model_id": "deterministic-tool-router"}),
+    )
+
+    assert "Title: Unwritten Page" in markdown
+    assert "Tool trace JSONL | needs session" in markdown
+    assert "Submission packet markdown | ready" in markdown
+    assert "No ideas recorded yet." in markdown