Spaces:
Running on Zero
Running on Zero
File size: 3,283 Bytes
441e897 849ee7b 441e897 bd351d2 441e897 849ee7b 441e897 849ee7b bd351d2 849ee7b c8055f7 bd351d2 c8055f7 bd351d2 c8055f7 bd351d2 6ac8ef6 849ee7b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | ---
title: Trace Field Notes
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 6.16.0
app_file: app.py
pinned: false
license: mit
---
# 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 models run on the Space
GPU through ZeroGPU: a quick `Qwen/Qwen3.5-9B` pass by default, and the larger
`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` for deeper analysis. 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.
## Run Locally
```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py
```
## Test
```bash
python3.11 -m unittest discover -s tests
```
## Analysis Engines
- `Qwen3.5 9B — 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.
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 model-backed analysis runs under `@spaces.GPU(size="xlarge")` so the weights
load on Hugging Face ZeroGPU hardware; `Qwen/Qwen3.5-9B` and
`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` are loaded with `transformers` and
cached across requests. The rule-based engine runs on CPU and never requests a
GPU slot, so it returns instantly.
## Agent Session Locations
```bash
# Codex
ls ~/.codex/sessions
# Claude Code
ls ~/.claude/projects
# Pi Agent
ls ~/.pi/agent/sessions
```
## Privacy
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. The app defaults to basic regex redaction
and exports only a redacted narrative text file.
|