PRD.md

⚖️ WitnessBox — PRD

Cross-examine a hostile AI witness. A courtroom interrogation game where the witness reacts to how you deliver, the AI is the irreplaceable mechanic, and a Modal Sandbox executing model-written code is the game's referee.

Track: 🍄 Thousand Token Wood · Primary prize: Best Use of Modal (1st-caliber, Axis A: Sandbox-runs-model-generated-code) · Status: built, compiles clean (see existing hf-hackathon/witnessbox/).

1. Vision & why it wins

Interrogate Marcus Reid, CFO of Halcyon Dynamics. He's evasive and reads your delivery stance (vocal confidence) — sound confident and he clams up; sound hesitant and he gets cocky and overshares. Catch him in 3 contradictions and his voice cracks as he breaks.

Three independent win mechanisms, three judge pools:

1. Best Use of Modal (#1 target): the core mechanic IS Modal's documented flagship pattern — an LLM writes code, a Sandbox safely executes it. Modal's own GRPO example: the "Best Use of Modal prize showcased the use of sandboxes for securely evaluating model-generated code." No rival in the field centers on this; most use Modal as plain inference hosting.
2. OpenBMB Best MiniCPM Build (Wood): MiniCPM-o is the character, VoxCPM2's style-tags are the game state — "model is the product," which beats "model is a component."
3. Wood track podium (4 paid slots): delight + load-bearing AI + originality + polish; a voiced, interactive game with a win condition and an audiovisual climax stands out vs watch-only demos.

2. Target prizes

Primary: Best Use of Modal (1st). Secondary (awards stack): OpenBMB-Wood · Wood podium · Community Choice (Wood) · Nemotron Hardware (ASR) · Best Agent · Best Demo · Off-Brand (only if a real gr.Server custom UI is built — not earned by CSS alone).

3. Users & core experience

Player = anyone who wants the fantasy of breaking a witness on the stand. Turn-based push-to-talk:

player records a question (mic)
  → Nemotron ASR transcribes  +  librosa reads DELIVERY STANCE (perceived confidence; NOT lie detection)
  → stance steers the witness system prompt (Hesitant → he overshares a thread toward an uncaught lie)
  → ONE MiniCPM-o call returns {in-character reply, contradiction-check Python}
  → modal.Sandbox executes the MODEL-WRITTEN code; its JSON verdict DECIDES the catch
    (keyword matching is only a silent fallback; on Sandbox error, the model self-corrects its code)
  → VoxCPM2 voices the reply; style escalates with pressure
catch #3 → win; the witness's voice cracks (pre-generated best take)

4. Functional requirements

• 3 planted lies injected into the system prompt (timeline, authorization, relationship), each with a concrete contradiction cue the player must surface. Detection fires against THESE, not on emergent model inconsistency (reliable > magical).
• Delivery stance from a parallel librosa pass (pause-rate + speaking-rate dominant per the prosody literature; pitch minor). Framed as perceived delivery, never "lie detector."
• Stance is load-bearing: Hesitant delivery makes the witness leak a cue toward one uncaught lie.
• Win at 3 catches, ≤ ~12 turns; the climactic break line is pre-generated and cached.
• The model-written code + Sandbox verdict are shown live in an open panel (the Modal evidence).

5. Technical architecture (all ≤32B; ≈12B combined)

Component	Model / lib	Notes (verified)
Witness brain	openbmb/MiniCPM-o-4_5 (9.4B)	AutoModel, trust_remote_code; chat(msgs=, use_tts_template=False, enable_thinking=False, generate_audio=False); init_vision/audio/tts=False (text-only).
Witness voice	openbmb/VoxCPM2 (2B)	from_pretrained(load_denoiser=False); Voice-Design CFO once → Controllable-Clone per line generate(text="(style)...", reference_wav_path=ref); 48kHz; torch≥2.5.0.
Player ASR	nvidia/nemotron-speech-streaming-en-0.6b (or -3.5-asr-streaming-)	whisper-small local fallback.
Delivery stance	librosa	parallel waveform pass; pause/rate → tier.
Contradiction engine	MiniCPM-o generates networkx code → modal.Sandbox	the verdict authority.

6. Best Use of Modal — five load-bearing primitives (the #1-prize section)

The core mechanic is Modal's flagship Sandbox pattern (docs/examples/agent, safe_code_execution).

1. ⭐ Sandbox executes model-written code — the game's referee (network-blocked; its JSON decides catches).
2. 🔧 Agentic self-correction — on Sandbox error, the error feeds back to MiniCPM-o, which repairs its own code and reruns (max 2) — Modal's devlooper generate→execute→fix loop.
3. GPU inference via @app.cls, scale-to-zero — MiniCPM-o (A100) + VoxCPM2 (A10G) + Nemotron ASR (A10G), idle → $0.
4. Parallel .map() — pre-generates the scripted voice beats (incl. the voice-crack) at load.
5. Memory snapshot + Volume — snapshot cuts cold start (measured); a Volume persists the designed CFO voice clip + model cache. Measured cost: quote real container-seconds → "$0.0X / match" (read from the Modal dashboard). Map this verbatim into the README's "Best Use of Modal" section (REQ-06 requires noting Modal).

7. UX / UI requirements

Courtroom aesthetic (parchment, serif). CFO portrait. "Delivery Stance" bar (labeled not a lie detector). X/3 contradiction counter. Autoplay witness audio. Contradiction Engine accordion defaults OPEN (the #1-prize evidence must be on camera). Latency (~20–35s warm) masked diegetically ("the witness considers…"). For Off-Brand, a real gr.Server custom courtroom UI would be required.

8. Demo video (the judged artifact)

60–90s, controlled, ~20 dry runs first: stance steers witness → ask hesitantly, he overshares → catch #1 → the Sandbox panel shows model-written code + verdict → catch #3 → voice cracks → cost readout. Show the Sandbox executing the model's code as the dramatic beat.

9. Success metrics

Five consecutive clean end-to-end turns from the deployed Space · win-at-3 reliable · Sandbox verdict authoritative (codegen broken <~30% of turns, self-correction covers the rest) · voice-crack lands · measured Modal cost + snapshot seconds captured.

10. Risks & mitigations

• End-to-end turn never run (highest risk) → deploy + prove 5 turns before anything downstream.
• Modal secrets unset → Space boots (lookup is lazy/try-excepted) but the Sandbox is dead; set MODAL_TOKEN_ID/MODAL_TOKEN_SECRET as Space secrets.
• Codegen unreliable → self-correction loop + a networkx skeleton in the prompt; never show repeated score=0.00.
• Voice-crack variance → pre-generate ≥30 takes of the win line, cache the best.
• Nemotron ASR install friction → bounded attempt, else pivot to parakeet or whisper fallback (never blocks the critical path).

11. Build plan (by dependency — no calendar)

1. Set Space secrets · generate CFO portrait · (done in scaffold: lazy lookup, warmup sandbox prebuild, accordion open, torch≥2.5, generate_audio/init_audio).
2. Deploy + smoke-test run_in_sandbox() and the voxcpm image standalone.
3. Five consecutive end-to-end turns from the deployed Space + measured latencies/cost (the gate).
4. ≥30 win-line takes cached · codegen reliability hardened.
5. Nemotron ASR pivot-gate (stop-loss) · optional real gr.Server UI for Off-Brand.
6. Demo video (after dry runs) → README measured numbers → social → submit.

12. Integrity rules

Claims follow code — no "only entry that…" claims about a moving field; cost/latency are measured, never fabricated. Pre-submit grep: TODO | YOUR_HF_USER | NotImplementedError | <!--.