# NumZoo — Agent Guidelines

## What this project is
Kids mental math app. Correct answers earn AI-generated cute animal images (FLUX.1-schnell).
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.1-schnell pipeline, 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`, `generate_now`

**Reward trigger:** every `REWARD_EVERY = 3` correct answers.
Image generated via `.then()` chaining on the Check button — synchronous, within Gradio request context (required for ZeroGPU).

## 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
- 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.1-schnell` (gated — accept license on HF before first run)
- Local: ~5 min on MPS · HF ZeroGPU: ~5 sec
- Always wrap in try/except → return `(None, "")` on failure
- `IS_HF_SPACE = os.environ.get("SPACE_ID") is not None` controls ZeroGPU decorator

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