# Architecture & Judging Coverage — Midnight Mystery with Detective Shawn

This document does two jobs:
1. Explains how the system is built (for technical judges and future contributors).
2. Maps the build to the **Build Small** judging surface so the submission collects as many "ways to win" as possible.

---

## 1. System overview

```
                          main.py (FastAPI)
        ┌───────────────────────┼───────────────────────────┐
        │                       │                            │
  Gradio: onboarding      Gradio: game               Gradio: case-closed
   (custom noir form)   (HUD + iframe map)            (reveal + debrief)
        │                       │                            │
        ▼                       ▼                            ▼
  case_generator        Phaser 3 (game.html)         debrief service
   (5-pass pipeline)     ⇅ postMessage / fetch              │
        │                       │                            │
        ▼                       ▼                            ▼
        └──────── backend/routers (case · interrogation · forensic) ───────┘
                                │
                    inference_client (HF Serverless / Ollama)
                                │
              Qwen3.5-9B (text)        FLUX.2-klein-4B (portraits)
```

- **Three Gradio apps, one FastAPI host.** Each page is its own `gr.Blocks` mounted via `gr.mount_gradio_app`, so onboarding, the game, and the reveal are independent and each fully custom-styled.
- **Phaser ⇄ backend bridge.** The map is a self-contained Phaser scene in an iframe. It talks to FastAPI with `fetch` and `postMessage` — movement, clue discovery, and interrogation all flow over HTTP.
- **State.** A Pydantic `CaseFile` holds the entire game; an in-memory store keyed by `case_id` carries it across requests. A complete hardcoded `SEED_CASE` is the guaranteed fallback.

---

## 2. The generation pipeline (the centerpiece)

A single small text model is driven through five narrow passes. Splitting the work keeps a 9B model reliable: each prompt is small, each output is validated, each failure is recoverable.

| Pass | Input | Output | Guarantee |
|------|-------|--------|-----------|
| **0 · Roster** | victim, scene, count, difficulty | cast (name, occupation, archetype, role) | exactly one culprit; fixed cast for later passes |
| **1 · Story Bible** | roster + setting | the hidden ground truth (how/why/when, motive) | the truth is written once and never sent to suspects |
| **2 · Souls** | story + one cast member | per-suspect "soul": voice, alibi, reveal rules, crack progression | runs **in parallel** (`asyncio`); each has a validator + fallback |
| **3 · Evidence** | story + soul summaries + map rooms | clues anchored to real locations + soul write-backs | **≥2 solvable paths**; clues land on real `clue_anchors` |
| **4 · Briefing** | **public fields only** | police dossier lines | structurally cannot leak the culprit |

**Why this wins points:** it's a concrete, defensible answer to "can a small model do something hard?" — yes, if you decompose the task, validate each step, and constrain it to a real world (the map manifest). It's not prompt-and-pray.

### Live systems layered on top
- **Emotional state machine** (`state_mutator`, `interrogation_pipeline`): trust / anxiety / defensiveness per suspect; crack thresholds scale with `lying_skill` (1–10). State is rendered into natural-language instructions so the model *enacts* pressure instead of describing it.
- **Knowledge gate** (`knowledge_gate`): suspects can only reveal authorized facts; everything else is forbidden context.
- **Prompt-injection defense**: known injection patterns are caught and deflected *in character* by archetype.
- **Reactive world** (`patrol`, alertness): suspects patrol their zones; a stealth/alertness layer escalates suspects and can warn the culprit.
- **Forensics** (`forensic_lab`): clue analysis that can detect contradictions against interrogation transcripts.
- **Debrief** (`debrief`): the model grades the playthrough and narrates the resolution.

---

## 3. Small-model compliance (the hard requirement)

| Component | Model | Params | < 32B? |
|-----------|-------|--------|--------|
| Case generation | `Qwen/Qwen3.5-9B` | ~9B | ✅ |
| Interrogation / debrief / forensics | `Qwen/Qwen3.5-9B` | ~9B | ✅ |
| Portraits | `black-forest-labs/FLUX.2-klein` | ~4B | ✅ |

Rule check: *"each model's parameter count must stay below 32B."* Largest single model here is **~9B**. Comfortably compliant — and the *narrative* of the project is precisely "look how much one small model can carry."

> ⚠️ **Consistency fix before submitting:** model names are stated inconsistently across the repo. `inference_client.py` (the source of truth) defaults to **Qwen3.5-9B** + **FLUX.2-klein-4B**, but `DEPLOYMENT.md` lists Qwen3-14B + Mistral-Small-24B + FLUX, and the onboarding CTA still says "Qwen-2.5-7B". Pick the real set, then make README, DEPLOYMENT.md, the onboarding CTA, and the demo VO all agree. Judges will notice a mismatch.

---

## 4. Judging-surface coverage

The field guide describes ~29 ways to win across track placements, Community Choice, sponsor prizes, the Custom-UI category, and stackable bonus badges. This project is strongest where it leans into being *AI-native* and *visually distinct*.

| Target | Why this build qualifies | Action to lock it in |
|--------|--------------------------|----------------------|
| **Thousand Token Wood** (track placement) | Couldn't exist without AI; the model *is* the game | Lead the README + video with this framing ✅ |
| **Custom UI badge** | Zero default-Gradio surfaces — bespoke noir CSS, Phaser map, custom loader | Show the UI prominently in the video; tag `custom-ui` |
| **OpenBMB / small-model sponsor** | Whole pitch is "one 9B model runs a game" | State param counts everywhere; confirm sponsor tag slug |
| **Community Choice** | Shareable, novel hook ("name a victim, AI writes the murder") | Strong social clip; post early for votes |
| **"Most badges stacked"** | Genuinely spans creativity + UI + small-model + agentic | Add every *honestly applicable* badge tag |
| **Full-package** | App + demo video + social post all exist and align | Ship all three; keep them consistent |

### Submission checklist (hard requirements)
- [ ] Deployed as a **Gradio app in the official `build-small-hackathon` HF org**
- [ ] **Demo video** showing the app working (see `DEMO_VIDEO_SCRIPT.md`)
- [ ] **Social post** created and **linked from the README** (see `SOCIAL_POST.md`)
- [ ] README **YAML tags** for the track + every badge being claimed
- [ ] All models verified **< 32B** and named consistently everywhere
- [ ] Submitted before **June 15, 23:59 UTC**

---

## 5. Pre-submission risk list

1. **Theme consistency.** The game is now *Detective Shawn* (human noir). Sweep for leftover pet/animal copy in user-facing strings (onboarding hints reference "animals in the neighbourhood"; portrait assets are animal placeholders). Anything a judge sees must match the shipped theme.
2. **Model-name drift.** See §3 warning — unify before recording the video.
3. **Inference reliability during judging.** The seed-case fallback covers a hard outage, but verify the Space's `HF_TOKEN`/provider and that portraits degrade gracefully. The demo video is your insurance — record it on a known-good run.
4. **First-paint impression.** Onboarding is the most-judged screen after the video. It's already strong; make sure fonts load on the Space (Google Fonts CDN reachable) so the noir look survives deployment.