docs/field-notes.md

Field Notes

Project: Exam Panic Rescue

User Problem

Students often hit a point before an exam where they are not really studying anymore. They are rereading everything, switching topics, panicking, and losing the last useful hours.

The first target workflow is a student who has a test soon and can only describe the situation as a messy panic dump: what they half-know, what scares them, and how much time is left. The app names the panic pattern, gives one proof target, keeps the final artifact focused on stopping the spiral, provides a live coach for each study block, and produces a study receipt for the before/after.

Field Notes are judge-facing evidence only. They are intentionally not a visible app output, not part of the generated packet, and not a task for the student during panic mode.

Hackathon Fit

• Track: Backyard AI.
• Core app: Gradio Space.
• Model constraint: default model target is openbmb/MiniCPM-V-4_5, under the <=32B rule.
• Sponsor target: OpenAI Codex track through Codex-built repo history and README linkage.
• OpenBMB fit: the default small-model path uses OpenBMB MiniCPM for text and syllabus-photo understanding when hardware is available.
• NVIDIA/Nemotron honesty: nvidia/Nemotron-Mini-4B-Instruct is selectable in the UI and should only be claimed with matching smoke evidence.
• Runtime honesty: CPU-only Hugging Face Spaces use the deterministic fallback by default; the current live Space is on ZeroGPU and model notes report exactly which engine ran.

What Changed During Build

• Chose a relatable student panic workflow instead of a generic productivity assistant.
• Kept the app small: one panic dump in, one rescue packet out.
• Added a model-budget strip so judges can see that <=32B is a rule ceiling, while free CPU Space hardware still needs an honest fallback.
• Replaced the overflowing examples table with four large panic-case buttons after visual QA showed the table made the demo feel like a spreadsheet.
• Renamed the opaque reset block to Reset: pick first target.
• Upgraded the live coach from a simple countdown into a local deterministic companion with the current action, proof/stop condition, next block preview, manual advance, and a 20-second panic reset.
• Removed the old app-level reflection prompt from the student flow so the product does not ask for evidence while the student is trying to study.

Bonus Quests

• Off-Brand: custom Gradio Blocks layout and CSS.
• Off-Brand evidence: the app includes clearly labeled sample scenarios, a study receipt, collapsed claim proof, and a final-sheet artifact with first-action, proof-before-stopping, and "Do not do" guardrails.
• Field Notes: this document is the concise public report for judges.
• Sharing is Caring: public-safe app traces are published at https://huggingface.co/datasets/build-small-hackathon/exam-panic-rescue-build-trace.
• Fine-tuning runway: data/readiness_cases.jsonl is a small public eval seed, but not a fine-tune claim.
• No-cloud-API runway: the app attempts local model inference and has no required external API key.
• Optional llama.cpp runway: possible through USE_LLAMA_CPP=1; local llama-cli is installed and the app-level OpenBMB MiniCPM4 0.5B GGUF smoke passed. Claim only if final demo/materials explicitly use or show that route.

Validation Plan

• Local unit test: python -m unittest discover -s tests
• Demo case smoke: python scripts/readiness_check.py
• The same biology, physics, history, and math smoke cases are exposed in the app under "Try a sample scenario".
• The same cases are published as JSONL at data/readiness_cases.jsonl so reviewers can inspect the tiny eval seed. They are not presented as real-user outcomes.
• Local app smoke: USE_LOCAL_MODEL=0 python app.py
• Space smoke: run once and confirm the model note is truthful: either it reports model-backed OpenBMB MiniCPM output on CUDA/ZeroGPU-capable hardware or a CPU-only fallback note on free/basic hardware.

Latest verified checks on 2026-06-12:

• Unit tests: 46/46.
• Demo readiness smoke: 24/24.
• Staging readiness: 11/11.
• Codex evidence check: 10/10.
• Local Space smoke: 4/4.
• Local browser smoke: generated the physics sample, advanced the coach manually, opened panic reset, confirmed study receipt/runtime, and confirmed no field-note prompt in the UI.

Submission Checklist

• Public GitHub repo contains Codex-attributed commits.
• Space README links to the public GitHub repo.
• Demo video shows one panic dump becoming a rescue plan, drill deck, triage clock, panic-pattern readout, proof target, live coach, final sheet, and study receipt.
• Field Notes stay in public docs for judges, not in the student UI.
• Social post links to the Space and names the Backyard AI track.