README.md

---
title: Math Adventure
emoji: 🧮
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.17.3
app_file: app.py
pinned: false
license: mit
---

# 🧮 Math Adventure

A talking, tap-to-play math game for an advanced 5–6 year old. Built with
[Gradio](https://gradio.app) (by Hugging Face). Each problem is **read aloud** by a
Hugging Face text-to-speech model (`facebook/mms-tts-eng`), so a child who can't yet
read fluently can still play. The difficulty **adapts automatically** — it gets harder
as the child answers correctly and eases off after a couple of misses.

## What it covers
- **Addition & subtraction** — within 5 → 10 → 20 → 100, plus missing-number problems (`7 + ? = 15`).
- **Counting & comparing** — count objects, "which is bigger?", and missing numbers / skip-counting.
- **Simple multiplication** — equal groups, then ×2, ×5, ×10 and small times tables.
- **Shapes & patterns** — name shapes, complete ABAB / AABB patterns, count sides.

## How it adapts
Held in game state: `level` (1–10), `score`, and streaks.
- **Level up** after **3 correct in a row**.
- **Level down** after **2 wrong in a row** (it never punishes — just eases off).

## Run it locally (Windows)
```powershell
py -m pip install -r requirements.txt
py app.py
```
Then open <http://localhost:7860>. The first launch downloads the TTS model (~145 MB) once.

## Run the logic tests
```powershell
py -m pip install pytest
py -m pytest test_game_logic.py
```

## Deploy to Hugging Face Spaces (free)
1. Create a free account at <https://huggingface.co>.
2. **New Space** → name it → **SDK: Gradio** → Hardware: **CPU basic (free)**.
3. Upload `app.py`, `game_logic.py`, `tts.py`, `requirements.txt`, and this `README.md`
   (drag-and-drop in the Space's **Files** tab, or `git push` to the Space repo).
4. The Space builds automatically and gives you a public URL — open it on a tablet and play.

## Files
| File | Purpose |
|------|---------|
| `app.py` | Gradio UI, game loop, audio, rewards. |
| `game_logic.py` | Problem generation + adaptive difficulty (pure Python, unit-tested). |
| `tts.py` | Hugging Face text-to-speech, with a silent fallback if audio can't load. |
| `test_game_logic.py` | Tests for problem generation and the difficulty engine. |