CLAUDE.md

# NumZoo — Agent Guidelines

## What this project is
Kids mental math app. Correct answers earn AI-generated cute animal images (FLUX.2-klein-4B).
Stack: Python · Gradio · diffusers · HuggingFace Spaces (ZeroGPU).

## Mandatory dev loop
Run these scripts in order before every push. Fix failures before proceeding.

| Step | Command | Must pass |
|------|---------|-----------|
| Syntax | `bash scripts/syntax.sh` | No syntax errors |
| Imports | `bash scripts/check_imports.sh` | No import errors |
| SDK version | `bash scripts/check_sdk.sh` | README sdk_version == local gradio |
| Run | `bash scripts/run.sh` | App starts, no errors in logs |
| Test | `bash scripts/test.sh` | All Puppeteer checks pass, screenshots look correct |

Full loop shortcut: `bash scripts/dev.sh` (runs steps 1–4, then run test.sh manually).

**Never push if any step fails.**

## Key files

| File | Role |
|------|------|
| `app.py` | Gradio UI, game logic, panel visibility, event wiring |
| `image_generator.py` | FLUX.2-klein-4B pipeline, persistent cache setup, emoji→text prompt builder |
| `math_engine.py` | Question generation, level names & thresholds |
| `requirements.txt` | Python dependencies — never include `gradio` here |
| `README.md` | HF Spaces config (frontmatter `sdk_version`) + user docs |
| `scripts/` | Dev loop automation scripts |

## Architecture

**3-panel flow:** Welcome → Emoji Picker → Quiz

**Game state dict keys:**
`name`, `level`, `score`, `streak`, `correct_since_reward`, `level_correct`,
`question`, `answer`, `selected_animals`, `selected_places`,
`reward_count`, `pregenerate_next`, `generate_now`, `pending_reward_id`

**Reward trigger:** every `REWARD_EVERY = 3` correct answers.

**Pre-generation flow (async image UX):**
1. "Let's go!" → `start_game()` → adds locked placeholder for reward #1 in collection →
   `.then(pregenerate_image)` starts background generation immediately
2. `pregenerate_image` stores PIL image in `hidden_image` (gr.Image) and base64 data URL in
   `hidden_data_url` (gr.Textbox), sets `state["pending_reward_id"]`
3. When user earns a reward: `check_answer` receives `hidden_image` + `hidden_data_url` as inputs.
   - If pre-image matches reward_id → show immediately + unlock in collection + kick off next pregenerate
   - If not ready → show LOADER_HTML + set `generate_now=True`
4. `.then(generate_on_demand)` → generates on-demand if `generate_now`, unlocks collection
5. `.then(pregenerate_image)` → generates next reward in background

**Collection system:**
- `collection_trigger = gr.HTML("")` receives JSON-encoded action payloads
- JS polls `#numzoo-coll-data` element every 200ms for `{ts, actions:[{action,id,src}]}`
- Actions: `add-locked` (locked placeholder), `unlock` (reveal image), `failed` (remove)
- Images stored in localStorage as base64 JPEGs (key: `numzoo_collection_v2`)

**Loader fix:** Use value-swapping (`""` = hidden, `LOADER_HTML` = shown) instead of `visible` flag.
This is more reliable in Gradio 6 than toggling visibility on gr.HTML components.

## Gradio rules
- Use `gr.update(visible=True/False)` for visibility — never return bare booleans
- Theme and CSS go in `demo.launch(css=..., theme=...)`, NOT in `gr.Blocks()`
- `gr.Group` has no `.change()` event
- Never put `gradio` in `requirements.txt` — HF Spaces pins it via `sdk_version` in README
- Never put `audioop-lts` in `requirements.txt` — HF Spaces runs Python 3.10 where `audioop` is stdlib; `audioop-lts` requires >=3.13 and will break the build
- Keep `sdk_version` in README in sync with local gradio (run `scripts/check_sdk.sh`)

## Python runtime
- **Local:** `~/miniforge3/bin/python3` (arm64, Python 3.13, torch 2.12, MPS)
- **HF Spaces:** Python 3.13, ZeroGPU (A100 via `@spaces.GPU`)
- Do not use system Python (`/usr/local/bin/python3`) — it's x64 Rosetta, incompatible

## Image generation
- Model: `black-forest-labs/FLUX.2-klein-4B` (Apache 2.0 — accept license on HF before first run)
- Same model local + HF Spaces. 4 steps, `guidance_scale=1.0`, 512×512
- Local: float16 on MPS (needs ~13GB, fits in 32GB unified mem) · HF ZeroGPU: ~fast on A100
- Pipeline class: `Flux2KleinPipeline` (diffusers ≥ 0.38)
- Always wrap in try/except → return `(None, "")` on failure
- `IS_HF_SPACE = os.environ.get("SPACE_ID") is not None` controls ZeroGPU decorator
- Logs generation time (`✅ Generated in Xs`)

## Persistent model cache (HF Spaces)
- `/data/hf_cache_v4` mount caches the model across restarts (set in Space Settings → Storage)
- Setup is **bulletproof**: poisoned/partial cache is auto-wiped & re-downloaded;
  any `/data` failure falls back to ephemeral container cache; import never crashes
- If the cache tree gets poisoned again (`[Errno 20] Not a directory`), bump the
  path suffix (`_v4` → `_v5`) to escape it — established repo pattern
- `NUMZOO_STYLE` constant in `image_generator.py` is the single source of truth for
  the art style; `scripts/generate_dataset.py` imports it so training captions match

## HuggingFace deployment
- Space: `https://huggingface.co/spaces/Goumsss/numzoo`
- Push = redeploy. Rebuilds automatically.
- ZeroGPU: set in Space Settings → Hardware (requires HF Pro or hackathon grant)

## UI/UX principles
- English only, minimal text — words not sentences (kids with limited English)
- Emoji-heavy feedback (`✅ Great! 🔥🔥` not full sentences)
- Never crash visibly — all handlers wrapped in try/except with safe fallbacks