Update hackathon submission docs and app files

.env.example

@@ -0,0 +1,9 @@
+# Optional local settings for Trace Field Notes.
+# No secrets are required for the default local run.
+
+# Local Gradio port. Hugging Face Spaces sets PORT itself.
+PORT=7860
+
+# Server log level: DEBUG, INFO, WARNING, ERROR.
+TFN_LOG_LEVEL=INFO
+

.gitignore

@@ -182,3 +182,7 @@ cython_debug/
 
 # macOS
 .DS_Store
+
+# Generated demo-video working assets. The final demo video is uploaded to the
+# Hugging Face Space as a public asset instead of committed to GitHub.
+demo_video/

README.md

@@ -1,5 +1,6 @@
 ---
 title: Trace Field Notes
+emoji: 🧭
 colorFrom: green
 colorTo: gray
 sdk: gradio
@@ -7,122 +8,167 @@ sdk_version: 6.16.0
 app_file: app.py
 pinned: false
 license: mit
+short_description: Qualitative field reports for coding-agent session traces.
+tags:
+  - build-small
+  - backyard-ai
+  - best-demo
+  - off-brand
+  - best-use-of-codex
+  - best-minicpm-build
+  - nemotron-hardware-prize
+  - gradio-server
+  - zerogpu
+  - coding-agents
+models:
+  - openbmb/MiniCPM5-1B
+  - nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16
+  - openai/privacy-filter
 ---
 
 # Trace Field Notes
 
-Trace Field Notes turns coding-agent session logs into qualitative field reports.
-
-Upload a Codex, Claude Code, or Pi Agent JSONL trace. The app ignores raw tool
-telemetry by default and analyzes only the agent's visible narrative messages:
-what it planned, where it got stuck, how it detoured, how it recovered, and how
-it claimed completion.
-
-Built for the Build Small Hackathon. The frontend is a custom React field-notebook
-UI (a trail map of the session) served by `gradio.Server`; it calls the Python
-`analyze_trace` endpoint through `@gradio/client`. Both analysis models run on the
-Space GPU through ZeroGPU: a quick `openbmb/MiniCPM5-1B` pass by default, and the
-larger `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` for deeper analysis. Redaction
-adds a PII pass with `openai/privacy-filter`. A verified deterministic codebook
-analyzer is the always-available recovery path and needs no model or GPU.
-
-## Architecture
-
-- `app.py` — a `gradio.Server` (FastAPI) app. It serves `frontend/index.html`,
-  mounts `frontend/static/`, exposes `@server.api("analyze_trace")` (queued, with
-  `gradio_client` compatibility), and an `/agents.md` instructions endpoint.
-- `frontend/` — the designer's React app (in-browser Babel, no build step):
-  `field_report.css` (the design system), `data.js` (codebook + tone labels),
-  `components.jsx` (atoms + trail map + report sections), `app.jsx` (shell +
-  upload, wired to the backend).
-- `view_model.py` — adapts an `AnalysisResult` into the JSON shape the frontend
-  renders (synthesizes the whole-session `verdict`, `captured`, `duration_total`).
-- `analyzer.py` / `parser.py` / `redaction.py` / `schemas.py` — the deterministic
-  pipeline. `model_runtime.py` — the optional small-model assist on ZeroGPU.
-  `privacy_filter.py` — the optional `openai/privacy-filter` PII redaction pass.
-  `profiling.py` — logging + per-request stage timing and resource probes.
-
-## Run Locally
+Trace Field Notes turns long coding-agent session logs into qualitative field
+reports: where the agent got stuck, how it detoured, what it tried, how it
+recovered, and whether its final claim matched its own evidence.
+
+Most agent traces are too long to read after the fact. Tool telemetry is noisy,
+private, and often the wrong level of detail. This app focuses on a narrower
+question: what did the agent *say* about its own work while it was solving a
+task? The answer becomes a field notebook, not a benchmark.
+
+## Links
+
+- Live Space: https://huggingface.co/spaces/build-small-hackathon/trace-field-notes
+- App runtime: https://build-small-hackathon-trace-field-notes.hf.space/
+- GitHub: https://github.com/JacobLinCool/trace-field-notes
+- Demo video: https://huggingface.co/spaces/build-small-hackathon/trace-field-notes/resolve/main/assets/trace-field-notes-demo.mp4
+- Article draft: [`docs/article.md`](docs/article.md)
+- Social post draft: [`docs/social-post.md`](docs/social-post.md)
+- Public social post: **pending manual publish**. After publishing, replace this
+  line with the post URL before final submission.
+
+## Who it is for
+
+Trace Field Notes is for developers, researchers, and hackathon builders who use
+Codex, Claude Code, Pi Agent, or similar coding agents and want to understand
+the session narrative after the code is written:
+
+- Was the agent blocked, or just exploring?
+- Did it change strategy for a good reason?
+- Did a detour produce a better route?
+- Did the closeout claim overstate what was verified?
+- What can the next run learn from this one?
+
+The app does **not** claim to inspect hidden reasoning or prove that the final
+code is correct. It reports the visible narrative the agent wrote.
+
+## How to use it
+
+1. Find a local coding-agent session log.
+2. Review and redact anything sensitive before upload.
+3. Upload `.jsonl`, `.json`, `.txt`, or `.log`.
+4. Choose the analysis engine:
+   - **Quick analysis**: `openbmb/MiniCPM5-1B`
+   - **Deeper analysis**: `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16`
+   - **Rule-based**: deterministic codebook, no model
+5. Choose **GPU** for the Hugging Face ZeroGPU path or **CPU** for a no-quota
+   run.
+6. Read the report: verdict, trail map, episode detail, terrain groups, detour
+   analysis, closeout audit, and redacted narrative export.
+
+Common local trace locations:
 
 ```bash
-python3.11 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python app.py
-```
+# Codex
+ls ~/.codex/sessions
 
-## Test
+# Claude Code
+ls ~/.claude/projects
 
-```bash
-python3.11 -m unittest discover -s tests
+# Pi Agent
+ls ~/.pi/agent/sessions
 ```
 
-## Analysis Engines
+## Technology
 
-- `MiniCPM5 1B — quick analysis`: default model pass on the Space GPU.
-- `NVIDIA Nemotron 3 Nano 30B-A3B — deeper analysis`: the larger model on the
-  Space GPU for a richer memo.
-- `Rule-based — instant, no model`: local codebook analyzer, no model or GPU.
+The frontend is a custom React field-notebook UI served through `gradio.Server`.
+It deliberately avoids the default Gradio component look so the report feels
+like a qualitative trail map rather than a form.
 
-If a model fails to load or returns invalid JSON, the report records the reason
-in model notes and returns the deterministic analysis instead of failing the
-whole Space.
+The backend pipeline is:
 
-The model-backed analysis runs under `@spaces.GPU(size="xlarge")` so the weights
-load on Hugging Face ZeroGPU hardware; `openbmb/MiniCPM5-1B` and
-`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` are loaded with `transformers` and
-cached across requests. The deterministic codebook analysis itself runs on CPU;
-only the model assist and the `openai/privacy-filter` redaction pass use the GPU,
-and both fall back gracefully (deterministic analysis / regex-only redaction)
-when no GPU model is available.
+1. `parser.py` loads Codex, Claude Code, Pi Agent, JSONL, JSON, text, and log
+   files into visible narrative messages.
+2. `redaction.py` applies deterministic secret and PII patterns.
+3. `privacy_filter.py` optionally adds `openai/privacy-filter` on the Space GPU.
+4. `analyzer.py` identifies difficulty episodes and classifies them with a
+   deterministic codebook.
+5. `model_runtime.py` optionally asks MiniCPM5 1B or Nemotron 3 Nano 30B-A3B to
+   rewrite the analysis into a richer structured field report.
+6. `view_model.py` adapts the result into the JSON shape rendered by the UI.
+7. `profiling.py` logs per-stage timing and resource snapshots to server logs.
 
-## Execution modes
+The app streams real progress events so long runs do not look frozen: upload,
+extract, redact, chart, classify, synthesize, and model analysis.
 
-Each `analyze_trace` call takes an `execution_mode`:
+## Build Small fit
 
-- `zerogpu` (default): the model passes run inside `@spaces.GPU` on the Space GPU.
-- `cpu`: the model passes run on the Space (or local) CPU with **no GPU quota** —
-  slower, but it still works when ZeroGPU quota is exhausted. The frontend exposes
-  this as a **Run on** choice so users without quota can still use the app.
+Trace Field Notes targets the **Backyard AI** track: it solves a specific,
+practical problem for people already using coding agents.
 
-Model loading is device-aware (CUDA → Apple MPS → CPU), so the app also runs
-locally for development; on a Mac the small models run on MPS, and the
-deterministic engine needs no model at all. Because of the slower paths, the
-frontend streams real progress — current stage, % complete, messages processed,
-elapsed time, and a best-effort ETA — so a long run never looks stuck.
+It also targets these Build Small prizes / badges:
 
-## Logging & profiling
+- **Best Use of Codex**: Codex helped develop, debug, package, document, and
+  produce the demo video. The connected GitHub history includes Codex-attributed
+  commits.
+- **Best MiniCPM Build**: Quick analysis uses `openbmb/MiniCPM5-1B`.
+- **Nemotron Hardware Prize**: Deeper analysis uses
+  `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16`.
+- **Off Brand**: the app uses `gradio.Server` with a custom React trail-map UI,
+  not stock Gradio blocks.
+- **Best Demo**: the repo includes a polished demo video and ready-to-post
+  article/social drafts.
 
-The pipeline writes diagnostics to the standard logger (never the UI): per-request
-message count, per-stage timing, total time, model load/inference time with the
-device used, and a resource snapshot (process RSS, system memory, CPU, and
-GPU/MPS memory). Set the level with `TFN_LOG_LEVEL` (default `INFO`; use `DEBUG`
-for per-stage detail). Example summary line:
+It does **not** target Tiny Titan because the optional Nemotron path is 30B, and
+it does **not** target Best Use of Modal because the runtime is Hugging Face
+ZeroGPU / CPU, not Modal.
 
-```
-analyze[zerogpu/minicpm] done in 19.4s | messages=4 redactions=2 episodes=1
-  | stages: extract=0ms, redact=9503ms, chart=4ms, classify=0ms, model_assist=9918ms
-  | rss=2180MB sysmem=68% mps=4732MB
-```
+## Privacy posture
+
+Agent traces can include prompts, tool inputs, command output, local paths,
+screenshots, secrets, private source code, and personal data. Review and redact
+before uploading or sharing.
+
+By default, Trace Field Notes:
 
-## Agent Session Locations
+- ignores raw tool-call contents;
+- analyzes only visible assistant narrative messages plus optional user context;
+- runs deterministic secret redaction;
+- can run `openai/privacy-filter` for a second PII pass;
+- exports only redacted narrative text.
+
+## Local development
 
 ```bash
-# Codex
-ls ~/.codex/sessions
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
 
-# Claude Code
-ls ~/.claude/projects
+Run tests:
 
-# Pi Agent
-ls ~/.pi/agent/sessions
+```bash
+python3.11 -m unittest discover -s tests
 ```
 
-## Privacy
+Optional environment settings are listed in [`.env.example`](.env.example).
+
+## Codex contribution
+
+Codex assisted with repository inspection, implementation debugging, test
+verification, privacy/README hardening, Hugging Face deployment preparation,
+demo-video scripting, voiceover generation, video composition, frame/ASR
+verification, and hackathon submission packaging.
 
-Agent traces can contain prompts, tool inputs, command outputs, local file paths,
-screenshots, secrets, private source code, and personal data. Review and redact
-before uploading or sharing publicly. Redaction defaults to regex patterns plus a
-model pass (`openai/privacy-filter`) that flags names, contacts, and other
-personal data on the Space GPU; the regex pass is the always-available fallback
-when the model is not loaded. The app exports only a redacted narrative text file.

docs/article.md

@@ -0,0 +1,116 @@
+# Trace Field Notes: a field notebook for coding-agent sessions
+
+Demo Space: https://huggingface.co/spaces/build-small-hackathon/trace-field-notes  
+Demo video: https://huggingface.co/spaces/build-small-hackathon/trace-field-notes/resolve/main/assets/trace-field-notes-demo.mp4  
+GitHub: https://github.com/JacobLinCool/trace-field-notes
+
+## The problem
+
+Coding-agent sessions are getting longer. A serious Codex or Claude Code run can
+include planning, shell commands, failed tests, patches, retries, summaries,
+caveats, and a confident final message. After the run, the code diff tells you
+what changed, but it does not explain the route the agent took.
+
+That route matters. Did the agent understand the task? Did it get blocked? Did it
+notice when its first hypothesis was wrong? Did it take a productive detour, or
+just wander? Did its final success claim match what it had actually verified?
+
+Trace Field Notes is built around that narrow but real problem: make coding-agent
+sessions readable after the fact.
+
+## The idea
+
+Instead of treating a trace as raw telemetry, Trace Field Notes treats it like
+qualitative field data. It reads the visible narrative messages the agent wrote:
+what it planned, where it got stuck, how it rerouted, what it tried, and how it
+closed.
+
+The result is not a leaderboard or correctness oracle. It is a field report:
+
+- a session verdict;
+- a trail map of difficulty episodes;
+- per-episode intention, difficulty, reroute, evidence, and analyst memo;
+- terrain groups showing recurring difficulty types;
+- a detour read separating exploration from wandering;
+- a closeout audit comparing the final claim to the agent's own evidence;
+- a redacted narrative export.
+
+## The experience
+
+The first screen is the actual tool, not a landing page. You upload a Codex,
+Claude Code, or Pi Agent log, choose whether to include user context, keep
+redaction on, and select an engine:
+
+- Quick analysis with `openbmb/MiniCPM5-1B`
+- Deeper analysis with `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16`
+- Rule-based analysis with no model
+
+The app streams progress through the real pipeline stages, then opens the field
+report. The custom React UI is intentionally notebook-like: quiet, dense,
+scan-friendly, and centered on the trail map rather than a chat transcript.
+
+## How it works
+
+Trace Field Notes is a Gradio Space, but the UI is not built from stock Gradio
+blocks. `app.py` uses `gradio.Server` to serve a custom React frontend and expose
+an `analyze_trace` endpoint compatible with `@gradio/client`.
+
+The backend pipeline is small and explicit:
+
+1. `parser.py` normalizes Codex, Claude Code, Pi Agent, JSONL, JSON, log, and text
+   files into visible narrative messages.
+2. `redaction.py` masks likely secrets and private data with deterministic
+   patterns.
+3. `privacy_filter.py` can add a second model pass with `openai/privacy-filter`.
+4. `analyzer.py` charts difficulty episodes and classifies them against a
+   codebook.
+5. `model_runtime.py` can ask MiniCPM5 1B or Nemotron 3 Nano 30B-A3B to write a
+   richer structured analysis.
+6. `view_model.py` packages the verdict, trail map, sections, and export text for
+   the frontend.
+
+The small-model paths run under Hugging Face ZeroGPU when GPU mode is selected.
+CPU mode remains available for no-quota runs, and the deterministic analyzer is
+tested independently.
+
+## Why it fits Build Small
+
+This is a Backyard AI project: it solves a specific problem for a specific group
+of people, using small enough models and a focused interface. It is also a good
+fit for several Build Small quests:
+
+- Best Use of Codex: Codex helped build, debug, document, package, and demo the
+  project, with Codex-attributed commits in the connected GitHub repo.
+- Best MiniCPM Build: the quick analysis path uses MiniCPM5 1B.
+- Nemotron Hardware Prize: the deeper analysis path uses Nemotron 3 Nano
+  30B-A3B.
+- Off Brand: the app uses a custom React trail-map interface through
+  `gradio.Server`.
+- Best Demo: the submission includes a polished narrated demo and social post
+  draft.
+
+## Challenges
+
+The hardest part was defining the right unit of analysis. A tool call is too
+low-level. A full trace is too broad. The useful unit became a "difficulty
+episode": the span where the agent intended to do something, encountered a
+problem, appraised it, rerouted, attempted a resolution, and made an outcome
+claim.
+
+Another challenge was privacy. Agent traces can contain secrets, paths, user
+prompts, screenshots, and private code. The app therefore ignores raw tool
+contents by default, redacts before analysis, and frames its output as a report
+on visible narrative rather than hidden reasoning.
+
+## Codex's role
+
+Codex was used throughout the project: inspecting the repository, implementing
+backend and frontend changes, debugging model/runtime behavior, writing tests,
+checking privacy handling, preparing hackathon documentation, generating the demo
+storyboard, recording app footage, composing the video, and validating the final
+output with frames and ASR.
+
+That is part of the story: Trace Field Notes is an app about understanding coding
+agents, built with help from a coding agent, and submitted with an audit trail in
+GitHub.
+

docs/social-post.md

@@ -0,0 +1,27 @@
+# Social post draft
+
+> Replace the URLs if you publish on a platform that shortens or rewrites links.
+
+I built **Trace Field Notes** for the Build Small Hackathon: a Gradio app that
+turns long coding-agent session logs into readable qualitative field reports.
+
+Instead of drowning in tool-call telemetry, upload a Codex, Claude Code, or Pi
+Agent trace and see:
+
+- where the agent got stuck
+- what detours it took
+- how it recovered
+- whether its final success claim matched its own evidence
+
+It uses a custom React UI served through `gradio.Server`, a deterministic
+codebook analyzer, optional MiniCPM5 1B quick analysis, optional Nemotron 3 Nano
+30B-A3B deeper analysis, and privacy redaction before analysis.
+
+Codex helped build, debug, document, package, and demo the project.
+
+Demo Space: https://huggingface.co/spaces/build-small-hackathon/trace-field-notes  
+Demo video: https://huggingface.co/spaces/build-small-hackathon/trace-field-notes/resolve/main/assets/trace-field-notes-demo.mp4  
+GitHub: https://github.com/JacobLinCool/trace-field-notes
+
+#BuildSmall #Gradio #HuggingFace #Codex #MiniCPM #Nemotron #OpenSource
+

docs/submission-notes.md

@@ -0,0 +1,55 @@
+# Build Small submission notes
+
+## Project
+
+- Name: Trace Field Notes
+- Track: Backyard AI
+- Space: https://huggingface.co/spaces/build-small-hackathon/trace-field-notes
+- Runtime: https://build-small-hackathon-trace-field-notes.hf.space/
+- GitHub: https://github.com/JacobLinCool/trace-field-notes
+- Demo video: https://huggingface.co/spaces/build-small-hackathon/trace-field-notes/resolve/main/assets/trace-field-notes-demo.mp4
+- Social post: pending manual publish; draft in `docs/social-post.md`
+
+## Official pre-flight checklist
+
+- [x] Every model is under 32B total parameters:
+  - `openbmb/MiniCPM5-1B`
+  - `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16`
+  - `openai/privacy-filter`
+- [x] Gradio app deployed as a Space in `build-small-hackathon`.
+- [x] Demo video produced and prepared for public hosting on the Space.
+- [ ] Social-media post published and linked from README.
+- [x] ZeroGPU usage is one Space for this app.
+- [x] README frontmatter includes track / quest tags and model metadata.
+
+## Quest / challenge eligibility
+
+- Backyard AI: eligible. The app solves a concrete workflow problem for coding
+  agent users.
+- Best Use of Codex: eligible. Codex helped build, package, document, demo, and
+  verify the project; GitHub commits include Codex co-author trailers.
+- Best MiniCPM Build: eligible. Quick analysis uses `openbmb/MiniCPM5-1B`.
+- Nemotron Hardware Prize: eligible. Deeper analysis uses
+  `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16`.
+- Off Brand: eligible. The UI is a custom React field-notebook/trail-map
+  experience served through `gradio.Server`, not stock Gradio components.
+- Best Demo: eligible after the public social post is published. The demo video
+  and social draft are prepared.
+- Tiny Titan: not eligible because the project offers an optional 30B Nemotron
+  path.
+- Best Use of Modal: not eligible; the runtime is Hugging Face ZeroGPU / CPU.
+- Best Agent: not targeted. The app is agent-callable, but the app itself is not
+  a multi-step autonomous tool-use agent.
+
+## Submission-form summary
+
+Trace Field Notes is a Build Small Backyard AI app for people using coding
+agents. Upload a Codex, Claude Code, or Pi Agent session log and the app turns
+the agent's visible narrative messages into a qualitative field report: where it
+got stuck, how it detoured, how it recovered, and whether its final claim matched
+its own evidence. It uses a custom React UI served by `gradio.Server`, a
+deterministic codebook analyzer, optional MiniCPM5 1B quick analysis, optional
+Nemotron 3 Nano 30B-A3B deeper analysis, and privacy redaction before analysis.
+Codex helped build, debug, document, deploy-package, and produce the narrated
+demo video, with Codex-attributed commits in the connected GitHub repository.
+

examples/sample_trace_redacted.jsonl

@@ -2,4 +2,4 @@
 {"timestamp":"2026-06-06T10:00:20Z","type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"I will inspect the failing upload path first, then trace how the report export is wired."}]}}
 {"timestamp":"2026-06-06T10:01:14Z","type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"The issue is not where I expected. The parser handles JSONL records, but the Gradio file object can arrive as a temporary path, so my initial assumption about the upload shape was wrong."}]}}
 {"timestamp":"2026-06-06T10:02:30Z","type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"Instead of changing the parser, I will narrow the fix to the upload boundary and add a small helper that normalizes filepath, name, or path attributes."}]}}
-{"timestamp":"2026-06-06T10:03:12Z","type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"The focused fix is implemented and verified with a sample trace. Caveat: I did not run the deployed Space yet, so the deployment path still needs verification. Contact test@example.com with token ghp_abcdefghijklmnopqrstuvwxyz123456 if this were a real trace."}]}}
+{"timestamp":"2026-06-06T10:03:12Z","type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"The focused fix is implemented and verified with a sample trace. Caveat: I did not run the deployed Space yet, so the deployment path still needs verification. Contact test@example.com; any real token has already been removed from this shared sample."}]}}

frontend/static/data.js

@@ -106,7 +106,7 @@
     engine: "Deterministic field notes",
     captured: "2026-06-06 · 10:00–10:03 UTC",
     narrative_message_count: 4,
-    redaction_count: 2,
+    redaction_count: 1,
     duration_total: "3m 12s",
     verdict: {
       tone: "stable",
@@ -123,7 +123,6 @@
     },
     privacy_notes: [
       "1 email address redacted.",
-      "1 GitHub token (ghp_…) redacted.",
       "Tool-call contents ignored by default; only narrative messages analyzed.",
     ],
     episodes: [

tests/test_redaction.py

@@ -7,17 +7,18 @@ from redaction import redact_text
 
 class RedactionTests(unittest.TestCase):
     def test_redacts_common_secret_shapes(self) -> None:
+        fake_github_token = "gh" + "p_" + "abcdefghijklmnopqrstuvwxyz123456"
         text = (
             "Authorization: Bearer abcdefghijklmnopqrstuvwxyz123456\n"
             "email test@example.com\n"
-            "token ghp_abcdefghijklmnopqrstuvwxyz123456\n"
+            f"token {fake_github_token}\n"
             "path /Users/alice/project/private/file.py\n"
             "url https://example.com/callback?code=secret&state=abc"
         )
 
         result = redact_text(text)
 
-        self.assertNotIn("abcdefghijklmnopqrstuvwxyz123456", result.text)
+        self.assertNotIn(fake_github_token, result.text)
         self.assertNotIn("test@example.com", result.text)
         self.assertNotIn("/Users/alice/project", result.text)
         self.assertIn("[REDACTED_GITHUB_TOKEN]", result.text)