# Project Status & Hackathon Alignment

_Hugging Face "Build Small" hackathon submission. Last updated: 2026-06-14._

## Hackathon rules we're targeting

- Model **under 32B** params, open weights ✅ (Qwen2.5-7B-Instruct)
- **Gradio app** Space ✅
- Demo video ❌ (TODO)
- Social-media link in README ❌ (TODO)
- Zero GPU limit ✅ (all inference via HF Inference API — no local GPU)
- README track/badge tags ✅ (added)
- ~~Sponsor prize for MiniCPM builds~~ — **dropped** (see decision below)

## Key decisions (2026-06-14)

1. **Model: Qwen2.5-7B-Instruct, not MiniCPM.** MiniCPM4.1-8B is not reliably
   served on the HF serverless Inference API, and we chose not to run it locally
   on a ZeroGPU Space. We therefore **drop the MiniCPM sponsor-prize claim** and
   compete on the core Build Small tracks. Qwen2.5-7B is open weights and well
   under the 32B cap, so the submission stays valid.
2. **Gradio 5 (pinned `>=5,<6`).** The original Gradio 4.44 pin broke against the
   current dependency stack; Gradio 5.50 is verified working. README `sdk_version`
   pinned to `5.50.0` to match.
3. **Dropped generated-image artifacts; render HTML cards instead.** Diffusion
   models render gibberish "text" inside newspaper/document artifacts, which looked
   broken. Both tabs now render the structured JSON the model already returns as
   legible HTML timeline/world cards. `image_client.py` is retained but unused.

## Architecture

- One shared text client (`model_client.py`, HF `chat_completion`) with per-tab
  prompt shaping (`prompts.py`).
- Image artifacts via HF `text_to_image` (`image_client.py`), FLUX.1-schnell →
  SDXL fallback.
- Graceful fallbacks everywhere — the app never crashes without a token.

## Track mapping

| Tab | Track | What it does |
|---|---|---|
| 🪞 Elsewhere | Backyard AI | Personal counterfactual + safety gate + return-to-reality |
| 🌍 Reality Divergence | Thousand Token Wood | Speculative alternate history, ripple reasoning |

## Phase status

| Phase | Status |
|---|---|
| 1 Foundation | ✅ Done & verified (boots, HTTP 200) |
| 2 Model integration | ✅ Done (Qwen via InferenceClient) |
| 3 UI & flow | ✅ Done & verified |
| 4 Safety & guardrails | ✅ Present (risk gate + strengths/return) |
| 5 Robust fallback | ✅ Verified (401 → graceful fallback) |
| 6 Testing & optimization | ❌ Not started (timings, cold start, concurrency) |
| 7 Submission prep | ⏳ README done; demo video + social link + deploy TODO |
| VoxCPM2 narration (optional) | ❌ `ENABLE_NARRATION=False`, not implemented |

## Remaining work

- [ ] Test live inference end-to-end with a real HF token
- [ ] Phase 6: measure startup/inference times, cold start, concurrency
- [ ] Record demo video (both tabs, model responses, safety gate)
- [ ] Add demo video + social-media links to README
- [ ] Deploy to HF Space and confirm clean build