| # 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. |
|
|
