Spaces:
Runtime error
Runtime error
| title: NumZoo | |
| emoji: 🦁 | |
| colorFrom: purple | |
| colorTo: pink | |
| sdk: gradio | |
| sdk_version: "6.17.3" | |
| app_file: app.py | |
| pinned: false | |
| license: apache-2.0 | |
| tags: | |
| - flux | |
| - text-to-image | |
| - kids | |
| - education | |
| - math | |
| - track:backyard | |
| - sponsor:modal | |
| - achievement:offgrid | |
| - achievement:welltuned | |
| - achievement:offbrand | |
| - achievement:fieldnotes | |
| # 🦁 NumZoo | |
| A mental math app for kids — answer questions, earn cute AI-generated animal images as rewards! | |
| > 🏆 **Built for the [🤗 Hugging Face "Small Models, Big Adventures" hackathon](https://huggingface.co/build-small-hackathon).** | |
| > A small (4B) image model, fine-tuned with a custom LoRA, turned into a delightful kids' reward loop. | |
| ## How it works | |
| 1. Enter your name | |
| 2. Pick your favourite animals 🐾 and places 🌍 (used to personalise reward images) | |
| 3. Answer math questions — every **3 correct answers** earns a reward image | |
| 4. Level up: **Additions → Subtractions → Multiplications → Mix** | |
| ### See it in action | |
| ▶️ **[Demo video (Loom)](https://www.loom.com/share/c565cba49f2c4ad1bfb428e38ff4b629)** · 📣 **[Launch post](https://x.com/goooums/status/2066500943676399814)** | |
| | 1 · Pick animals & places | 2 · Solve math | 3 · Earn cute reward | | |
| | :----------------------------: | :------------------------: | :----------------------------: | | |
| |  |  |  | | |
| ## Levels | |
| | Level | Operation | Goal | | |
| | ----- | ----------------- | --------- | | |
| | 1 | ➕ Additions | 5 correct | | |
| | 2 | ➖ Subtractions | 5 correct | | |
| | 3 | ✖️ Multiplications | 5 correct | | |
| | 4 | 🎲 Mix | Endless | | |
| ## Image model | |
| Rewards are generated with **FLUX.2-klein-4B** (4B params, Apache 2.0) via 🤗 Diffusers, | |
| plus a **custom NumZoo style LoRA** (below). Images start generating in the background as | |
| soon as the quiz begins, so a reward is usually ready the moment it's earned. | |
| ## ✨ Custom AI art: the NumZoo LoRA | |
| Out of the box, FLUX.2-klein renders the same prompt in wildly different styles — often | |
| photorealistic — which doesn't fit a soft, cozy kids' app. So we fine-tuned a **style | |
| LoRA** that pins every reward to the same kawaii children's-book look. | |
| **Before → after** (same prompt: *"a cute baby panda on a snowy mountain top"*): | |
| | Base FLUX.2-klein-4B | + NumZoo LoRA | | |
| | :------------------------------: | :----------------------------: | | |
| |  |  | | |
| | photorealistic, inconsistent | cozy, on-brand, every time | | |
| More rewards from the LoRA: | |
| | | | | | |
| | :---------------------------: | :-------------------------------: | :-----------------------: | | |
| |  |  |  | | |
| ### How we made it | |
| 1. **Dataset** — 54 cozy scenes generated with **Qwen-Image** (12 animals × 10 places, | |
| incl. multi-animal/multi-place combos), captioned `NUMZOO. <content>` with the style | |
| left *undescribed* so the trigger word carries it. See | |
| [`scripts/generate_dataset.py`](scripts/generate_dataset.py) and | |
| [`training/`](training/) for the images + captions. | |
| 2. **Training** — LoRA (rank 32, 1500 steps) on `FLUX.2-klein-base-4B` via | |
| [ostris/ai-toolkit](https://github.com/ostris/ai-toolkit), running on a **[Modal](https://modal.com) A100** (~45 min, serverless GPU). | |
| Reproducible setup in [`training/lora_trainer/`](training/lora_trainer/). | |
| 3. **Inference** — the LoRA loads on the distilled 4-step klein in `image_generator.py`; | |
| the app simply prepends the `NUMZOO` trigger to every prompt. | |
| **Published LoRA:** 🤗 [goumsss/numzoo-flux2-klein-lora](https://huggingface.co/goumsss/numzoo-flux2-klein-lora) | |
| ## Run locally | |
| > Requires Python on Apple Silicon (arm64). Recommended: [Miniforge](https://github.com/conda-forge/miniforge). | |
| ```bash | |
| # 1. Install dependencies | |
| ~/miniforge3/bin/pip install -r requirements.txt | |
| # 2. Accept FLUX.2-klein-4B license on HuggingFace | |
| # → https://huggingface.co/black-forest-labs/FLUX.2-klein-4B | |
| # Then log in: | |
| hf auth login | |
| # 3. Run | |
| ~/miniforge3/bin/python3 app.py | |
| # Opens at http://localhost:7860 | |
| # First run downloads ~23GB of model weights (cached after that) | |
| ``` | |
| > On standard Python/pip (non-Apple Silicon): | |
| > ```bash | |
| > pip install -r requirements.txt | |
| > python app.py | |
| > ``` | |