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