Fix audioop-lts for Python 3.13 + add CLAUDE.md agent guidelines

CLAUDE.md

@@ -0,0 +1,73 @@
+# 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 — follow for EVERY change
+
+```
+1. CODE   → edit files
+2. SYNTAX → ~/miniforge3/bin/python3 -c "import ast; [ast.parse(open(f).read()) for f in ['app.py','image_generator.py','math_engine.py']]"
+3. RUN    → kill previous instance, start fresh:
+             pkill -f "python3 app.py"; ~/miniforge3/bin/python3 app.py > /tmp/numzoo.log 2>&1 &
+             sleep 10 && cat /tmp/numzoo.log   # must show no errors
+4. TEST   → run Puppeteer (arm64 Node):
+             arch -arm64 /bin/zsh -c "source ~/.nvm/nvm.sh && nvm use 20 && cd /Users/uplab/projects/puppeteer && node test_lovemath.mjs"
+             → take screenshots, read them, verify visually
+5. FIX    → if any step fails, fix and restart from step 1
+6. PUSH   → only when all steps pass:
+             git add -A && git commit -m "..." && git push origin main
+```
+
+**Never push broken code.** If Puppeteer tests fail, do not proceed to push.
+
+## 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 (HF Spaces uses Python 3.13) |
+| `README.md` | HF Spaces config (frontmatter) + user docs |
+
+## 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`,
+`future` (ThreadPoolExecutor Future), `awaiting_reward`
+
+**Reward trigger:** every `REWARD_EVERY = 3` correct answers.
+Image generation starts in background (ThreadPoolExecutor) as soon as quiz begins.
+
+## Gradio rules
+- Use `gr.update(visible=True/False)` — never return bare `True/False` for component visibility
+- Theme and CSS go in `demo.launch(css=..., theme=...)`, NOT in `gr.Blocks()`
+- `gr.Group` has no `.change()` event — use explicit output returns from handlers
+- HF Spaces runs Python 3.13 — watch for removed stdlib modules (`audioop` → add `audioop-lts`)
+
+## Python runtime
+- **Local:** `~/miniforge3/bin/python3` (arm64, Python 3.13, torch 2.12, MPS)
+- **HF Spaces:** Python 3.13, ZeroGPU (A100 on demand via `@spaces.GPU`)
+- **DO NOT use** `/usr/local/bin/python3` — it's x64 Rosetta, torch 2.2, incompatible with latest diffusers
+
+## Image generation
+- Model: `black-forest-labs/FLUX.1-schnell` (gated — must accept license on HF)
+- Local speed: ~5 min on MPS · HF ZeroGPU: ~5 sec
+- Always wrap generation 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`
+- Remote: `https://huggingface.co/spaces/Goumsss/numzoo` (already set)
+- Push = redeploy. Space rebuilds automatically on every push.
+- ZeroGPU requires HF Pro or hackathon grant (set in Space Settings → Hardware)
+
+## UI/UX principles
+- Text: English, minimal — **words not sentences** (kids with limited English)
+- Feedback: emoji-heavy, short (`✅ Great! 🔥🔥` not `Congratulations, your answer was correct!`)
+- Never crash visibly — all handlers wrapped in try/except with safe fallback returns

requirements.txt

@@ -1,4 +1,5 @@
 gradio>=4.40.0
+audioop-lts
 diffusers>=0.30.0
 transformers>=4.44.0
 accelerate>=0.33.0