feat: add demo evidence bundle

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

README.md

@@ -96,6 +96,13 @@ target badges, score seal, build plan, trace, wood map, and export-ready artifac
 advisor engine as a normal user session, so the demo state can be used immediately with JSONL, Notes, Chapter, LoRA,
 Packet, and PNG exports.
 
+## Demo Evidence Bundle
+
+`/api/demo-bundle.zip` and the `Bundle` button download a server-built ZIP for the deterministic demo session. The
+bundle includes a manifest, demo session JSON, Prize Ledger JSON, trace JSONL, Field Notes, Almanac chapter, LoRA SFT
+JSONL, Submission Packet, and a PNG export note. This gives judges or collaborators one auditable package without
+depending on browser `localStorage`.
+
 ## Prize Ledger
 
 `/api/prize-ledger` and the in-app Prize Ledger panel expose submission evidence: the documented model stack, total

app.py

@@ -5,10 +5,11 @@ import os
 from pathlib import Path
 from typing import Iterator
 
-from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
 from gradio import Server
 
 from hackathon_advisor.agent import AdvisorEngine
+from hackathon_advisor.artifact_bundle import BUNDLE_FILENAME, build_demo_bundle_zip
 from hackathon_advisor.chapter import build_chapter_markdown
 from hackathon_advisor.data import ProjectIndex
 from hackathon_advisor.demo_rehearsal import build_demo_rehearsal
@@ -98,6 +99,22 @@ def demo_session() -> dict:
     return build_demo_rehearsal(engine)
 
 
+@app.get("/api/demo-bundle.zip")
+def demo_bundle() -> Response:
+    runtime_status = engine.runtime_status()
+    ledger = prize_ledger(runtime_status)
+    metadata = {
+        **trace_metadata(index),
+        "project_count": len(index.projects),
+    }
+    content = build_demo_bundle_zip(build_demo_rehearsal(engine), metadata, ledger)
+    return Response(
+        content=content,
+        media_type="application/zip",
+        headers={"Content-Disposition": f'attachment; filename="{BUNDLE_FILENAME}"'},
+    )
+
+
 @app.api(name="tool_contract_check", concurrency_limit=8)
 def tool_contract_check(model_output: str, fallback_query: str = "") -> dict:
     return resolve_tool_call(model_output, fallback_query=fallback_query).to_dict()

hackathon_advisor/artifact_bundle.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from io import BytesIO
+import json
+from typing import Any
+from zipfile import ZIP_DEFLATED, ZipFile
+
+from hackathon_advisor.chapter import build_chapter_markdown
+from hackathon_advisor.field_notes import build_field_notes_markdown
+from hackathon_advisor.lora_dataset import build_lora_dataset_jsonl
+from hackathon_advisor.submission_packet import build_submission_packet_markdown
+from hackathon_advisor.trace_export import build_trace_jsonl
+
+
+BUNDLE_SCHEMA_VERSION = 1
+BUNDLE_FILENAME = "hackathon-advisor-demo-bundle.zip"
+
+
+def build_demo_bundle_zip(
+    demo: dict[str, Any],
+    metadata: dict[str, Any],
+    ledger: dict[str, Any],
+) -> bytes:
+    session = demo.get("session") if isinstance(demo.get("session"), dict) else {}
+    files = _bundle_files(session, metadata, ledger, demo)
+    manifest = _manifest(files, metadata, ledger, demo)
+
+    buffer = BytesIO()
+    with ZipFile(buffer, "w", compression=ZIP_DEFLATED) as archive:
+        archive.writestr("manifest.json", json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True) + "\n")
+        for filename, content in files.items():
+            archive.writestr(filename, content)
+    return buffer.getvalue()
+
+
+def _bundle_files(
+    session: dict[str, Any],
+    metadata: dict[str, Any],
+    ledger: dict[str, Any],
+    demo: dict[str, Any],
+) -> dict[str, str]:
+    return {
+        "demo-session.json": json.dumps(demo, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        "prize-ledger.json": json.dumps(ledger, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        "trace.jsonl": build_trace_jsonl(session, metadata),
+        "field-notes.md": build_field_notes_markdown(session, metadata),
+        "almanac-chapter.md": build_chapter_markdown(session, metadata),
+        "lora-sft.jsonl": build_lora_dataset_jsonl(session, metadata),
+        "submission-packet.md": build_submission_packet_markdown(session, metadata, ledger),
+        "png-export-note.md": _png_note(demo),
+    }
+
+
+def _manifest(
+    files: dict[str, str],
+    metadata: dict[str, Any],
+    ledger: dict[str, Any],
+    demo: dict[str, Any],
+) -> dict[str, Any]:
+    badges = ledger.get("badges") if isinstance(ledger.get("badges"), list) else []
+    return {
+        "type": "demo_bundle_manifest",
+        "schema_version": BUNDLE_SCHEMA_VERSION,
+        "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "app": "hackathon-advisor",
+        "turn_count": int(demo.get("turn_count") or 0),
+        "file_count": len(files),
+        "files": list(files),
+        "runtime": ledger.get("runtime") if isinstance(ledger.get("runtime"), dict) else {},
+        "badge_status": {
+            str(badge.get("name")): str(badge.get("status"))
+            for badge in badges
+            if isinstance(badge, dict)
+        },
+        "index": {
+            "algorithm": _clean(metadata.get("index_algorithm")),
+            "snapshot_generated_at": _clean(metadata.get("snapshot_generated_at")),
+            "index_generated_at": _clean(metadata.get("index_generated_at")),
+            "snapshot_digest": _clean(metadata.get("snapshot_digest")),
+        },
+    }
+
+
+def _png_note(demo: dict[str, Any]) -> str:
+    artifact = demo.get("artifact") if isinstance(demo.get("artifact"), dict) else {}
+    title = _clean(artifact.get("title")) or "current fate page"
+    return (
+        "# PNG Export Note\n\n"
+        "The visual fate-page PNG is rendered client-side from the same session artifact so the browser can draw the "
+        "canvas with the deployed CSS and fonts. Load the Demo session in the Space, then press `PNG` to export it.\n\n"
+        f"Demo artifact title: {title}\n"
+    )
+
+
+def _clean(value: Any) -> str:
+    if value is None:
+        return ""
+    return " ".join(str(value).split())

static/app.js

@@ -25,6 +25,7 @@ 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 exportBundleButton = document.querySelector("#export-bundle");
 const resetButton = document.querySelector("#reset-session");
 
 const SESSION_STORAGE_KEY = "hackathon-advisor-session-v1";
@@ -81,6 +82,10 @@ exportPacketButton.addEventListener("click", async () => {
   await exportSubmissionPacket();
 });
 
+exportBundleButton.addEventListener("click", () => {
+  window.location.assign("/api/demo-bundle.zip");
+});
+
 resetButton.addEventListener("click", () => {
   clearSavedSession();
   window.location.reload();
@@ -613,6 +618,7 @@ function renderTrace(trace) {
 
 function setCommandDisabled(disabled) {
   document.querySelectorAll(".command-row button").forEach((button) => {
+    if (button.id === "export-bundle") return;
     const isArtifact = button.id === "export-artifact";
     const isTrace = button.id === "export-trace";
     const isNotes = button.id === "export-notes";

static/index.html

@@ -38,6 +38,7 @@
               <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-bundle" title="Download the demo evidence bundle">Bundle</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

@@ -1,8 +1,11 @@
 import json
+from io import BytesIO
+from zipfile import ZipFile
 
 from app import (
     bootstrap,
     chapter_artifact,
+    demo_bundle,
     demo_session,
     engine,
     field_notes_artifact,
@@ -129,6 +132,20 @@ def test_demo_session_endpoint_returns_export_ready_state() -> None:
     assert payload["export_ready"]["submission_packet"] is True
 
 
+def test_demo_bundle_endpoint_returns_zip_attachment() -> None:
+    response = demo_bundle()
+
+    assert response.media_type == "application/zip"
+    assert "hackathon-advisor-demo-bundle.zip" in response.headers["content-disposition"]
+    with ZipFile(BytesIO(response.body)) as archive:
+        names = set(archive.namelist())
+        manifest = json.loads(archive.read("manifest.json"))
+
+    assert "submission-packet.md" in names
+    assert "lora-sft.jsonl" in names
+    assert manifest["turn_count"] == 2
+
+
 def test_tool_contract_check_endpoint_defaults_safely() -> None:
     payload = tool_contract_check("broken", "family archive")
 

tests/test_artifact_bundle.py

@@ -0,0 +1,44 @@
+import json
+from io import BytesIO
+from pathlib import Path
+from zipfile import ZipFile
+
+from hackathon_advisor.agent import AdvisorEngine
+from hackathon_advisor.artifact_bundle import build_demo_bundle_zip
+from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.demo_rehearsal import build_demo_rehearsal
+from hackathon_advisor.prize_ledger import prize_ledger
+from hackathon_advisor.trace_export import trace_metadata
+
+
+def test_demo_bundle_contains_submission_evidence_files() -> None:
+    index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
+    engine = AdvisorEngine(index)
+    metadata = {
+        **trace_metadata(index),
+        "project_count": len(index.projects),
+    }
+    content = build_demo_bundle_zip(build_demo_rehearsal(engine), metadata, prize_ledger(engine.runtime_status()))
+
+    with ZipFile(BytesIO(content)) as archive:
+        names = set(archive.namelist())
+        manifest = json.loads(archive.read("manifest.json"))
+        trace = archive.read("trace.jsonl").decode("utf-8")
+        packet = archive.read("submission-packet.md").decode("utf-8")
+
+    assert names == {
+        "manifest.json",
+        "demo-session.json",
+        "prize-ledger.json",
+        "trace.jsonl",
+        "field-notes.md",
+        "almanac-chapter.md",
+        "lora-sft.jsonl",
+        "submission-packet.md",
+        "png-export-note.md",
+    }
+    assert manifest["type"] == "demo_bundle_manifest"
+    assert manifest["turn_count"] == 2
+    assert manifest["badge_status"]["Well-Tuned"] == "dataset-ready"
+    assert "agent_turn" in trace
+    assert "## Prize Evidence" in packet