README.md

metadata

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 (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)

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

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.