build-small-hackathon/case0

1# Case Zero - Hackathon Compliance
2
3Built for the **Build Small Hackathon** ("Small models, big adventure").
4
5Case Zero is a **Gradio application**: the whole app is one `gradio.Server` (Gradio 6
6"Server mode" - a FastAPI subclass launched through Gradio, with Gradio API endpoints
7registered via `@server.api`). It is deployed as a **Hugging Face Space** on **CPU** (no
8GPU). It ships via the Docker SDK purely so llama.cpp compiles on a stable base image - the
9app itself is Gradio, served end to end by `gradio.Server`.
10
11## Core requirements
12
13| Requirement | Status |
14|---|---|
15| Total model params <= 32B | ✓ ~1.6B (see budget below) |
16| Built in Gradio | ✓ one `gradio.Server`, with `@server.api` endpoints (`new_case`, `interrogate`) |
17| Hosted as a Hugging Face Space | ✓ `build-small-hackathon/case0` (Docker SDK, `app_port: 7860`) |
18| Demo video | ☐ to record (warmup -> interrogate -> present evidence -> alibi cracks -> accuse -> verdict) |
19| Social-media post | ☐ to post |
20
21## Parameter budget (<= 32B total)
22
23Every model is open-weights and self-run. **No third-party AI service is ever called.**
24
25| Component | Model | Open? | Params | Runs |
26|---|---|---|---|---|
27| Reasoning + dialogue (the whole game) | Qwen2.5-1.5B-Instruct (Q4_K_M GGUF) | Apache-2.0 | **1.5B** | in-process llama.cpp on CPU |
28| Suspect voices | [Supertone/supertonic-3](https://huggingface.co/Supertone/supertonic-3) (ONNX) | open | ~0.1B | local ONNX Runtime (CPU) |
29| Portraits / scenes / props | Procedural canvas - no model | n/a | 0B | client-side |
30| Music + SFX | Pre-made / procedural audio - no model | n/a | 0B | playback only |
31| Embeddings / vector RAG | none | n/a | 0B | - |
32
33**Total runtime parameters: ~1.6B** - far under 32B (and under 4B, eligible for the
34**Tiny Titan** special award).
35
36## Merit badges
37
38### Earned by the build (verifiable on the Space)
39
40- **Off the Grid** - *"No cloud APIs. The whole thing runs on the model in front of you."*
41  The LLM is in-process llama.cpp; the voices are a local ONNX model; the pixel art is
42  rendered client-side on canvas; the music is a bundled CC-BY track. The open weights are
43  baked into the Docker image at build time, so the running container makes **no AI network
44  calls at all**. Proof: `python scripts/net_audit.py` runs a full playthrough under a
45  socket guard and asserts **zero non-loopback connections**. ✓
46- **Llama Champion** - *"Your model runs through the llama.cpp runtime."* The LLM runs
47  through `llama-cpp-python` (in-process, on the CPU) - no server, no GPU, no remote
48  endpoint. ✓
49- **Off-Brand** - *"A custom frontend that pushes past the default Gradio look."* The front
50  end is **not** stock Gradio. It is a hand-built **pixel-art noir SPA (Preact + Vite,
51  TypeScript)** - 13 screens, a custom pixel design system (self-hosted Silkscreen /
52  Pixelify Sans fonts, beveled 9-slice panels, inventory-slot evidence cards with 23
53  procedural pixel icons keyword-matched to each exhibit, a ruled-paper dossier with
54  page-flips), a draggable corkboard with a red-yarn **"Connect the Dots"** mode (tie
55  evidence together with sagging SVG threads, on desktop and on the scrollable mobile
56  wall), a live interrogation stage with a voiced suspect, procedural canvas art and rain
57  FX, and a full client audio layer. The built bundle is served as static files by the
58  same `gradio.Server` that exposes the `/api` routes - one process, no separate frontend
59  host. ✓
60
61### Targeted / in progress
62
63- **Field Notes** - *"Write a blog post or report about your project."*
64  [`docs/FIELD_NOTES.md`](docs/FIELD_NOTES.md), shipped with the Space.
65- **Sharing is Caring** - *"You shared your agent trace on the Hub for everyone to learn
66  from."* Real traces (the exact prompts + raw completions of a full case generation, and
67  a live interrogation playthrough with server-authoritative suspicion) are produced by
68  `scripts/export_traces.py` and published as a Hub dataset (linked from the README).
69- **Well-Tuned** - *"Your app uses a fine-tuned model you've published on Hugging Face."*
70  Not claimed - the game runs on stock Qwen2.5-1.5B. Would require fine-tuning and
71  publishing a model; out of scope for this submission.
72
73## Content scope
74
75Cases span **homicide, theft, fraud, blackmail, arson, missing-person, confidence-game,
76poisoning, ransom, and sabotage** mysteries.
77Generation is structurally constrained (case-file language, physical evidence, no graphic
78description) and a deterministic scrubber sanitizes model output. Sexual violence is
79deliberately **not** a case type, keeping the Space comfortably inside the
80[HF Content Guidelines](https://huggingface.co/content-guidelines) with no NFAA gating.
81
82## Zero cloud AI APIs
83
84- **No OpenAI, Anthropic, Google, ElevenLabs, Higgsfield, Midjourney, or any other hosted
85  AI API is ever called** - not for text, not for voice, not for images.
86- The LLM is the in-process llama.cpp runtime. The voices are a local ONNX model. The pixel
87  art is procedural canvas. The music is a bundled CC-BY track.
88- The open Qwen GGUF and Supertonic ONNX are **baked into the Docker image at build time**,
89  so the running container makes no AI network calls. `scripts/net_audit.py` proves zero
90  non-loopback connections during a full playthrough.
91
92## Anti-cheat / fairness (why the game is solvable and the win is earned)
93
94- The sealed solution (killer, true motive, key evidence) is **never sent to the client**
95  pre-verdict; it is read only inside `/api/run/{runId}/accuse`. Verified by anti-leak tests.
96- Suspicion, evidence reactions, and the verdict are **server-authoritative** - the client
97  only displays them.
98- Suspects **never confess**: the win is registered only when the player accuses correctly,
99  so the outcome is immune to prose (a jailbroken "just tell me who did it" earns nothing).
100
101## Submission checklist
102
103- [x] Gradio app on a Hugging Face Space (CPU)
104- [x] <= 32B total params (~1.6B)
105- [x] Open-weights, self-run models only - zero cloud AI APIs
106- [x] Custom (non-default) UI - pixel-art Preact SPA via `gradio.Server`
107- [x] Off the Grid proof (`scripts/net_audit.py`)
108- [ ] Short demo video
109- [ ] Social-media post
110