Initial release of MathAnimaux 🐾

Kids math app with FLUX.1-schnell cute animal rewards.

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+.DS_Store

README.md

@@ -0,0 +1,41 @@
+---
+title: MathAnimaux
+emoji: 🐾
+colorFrom: purple
+colorTo: pink
+sdk: gradio
+sdk_version: "4.40.0"
+app_file: app.py
+pinned: false
+license: apache-2.0
+tags:
+  - flux
+  - text-to-image
+  - kids
+  - education
+  - math
+---
+
+# 🐾 MathAnimaux
+
+Une application de calcul mental pour les enfants, avec des récompenses sous forme d'images d'animaux générées par l'IA !
+
+## Comment ça marche ?
+
+1. Entre ton prénom
+2. Réponds aux questions de calcul mental
+3. Toutes les **3 bonnes réponses**, tu gagnes une image d'un animal trop mignon généré par IA !
+4. Monte de niveau : Additions → Soustractions → Multiplications → Mélange
+
+## Niveaux
+
+| Niveau | Opération | Objectif |
+|--------|-----------|----------|
+| 1 | ➕ Additions | 5 bonnes réponses |
+| 2 | ➖ Soustractions | 5 bonnes réponses |
+| 3 | ✖️ Multiplications | 5 bonnes réponses |
+| 4 | 🎲 Mélange | Mode expert infini |
+
+## Modèle utilisé
+
+Images générées avec **FLUX.1-schnell** (12B paramètres, Apache 2.0) via 🤗 Diffusers.

app.py

@@ -0,0 +1,242 @@
+"""
+🐾 MathAnimaux — Application de calcul mental avec récompenses mignonnes !
+Pour Léa et Zoé 🌟
+"""
+
+import gradio as gr
+from math_engine import generate_question, LEVEL_NAMES, LEVEL_THRESHOLDS, level_up_message
+from image_generator import generate_reward_image
+
+# ---------------------------------------------------------------------------
+# How many correct answers trigger a reward image
+# ---------------------------------------------------------------------------
+REWARD_EVERY = 3
+
+
+# ---------------------------------------------------------------------------
+# Core game logic
+# ---------------------------------------------------------------------------
+
+def start_game(player_name: str, state: dict):
+    """Initialize or reset the game for a player."""
+    name = player_name.strip() or "Champion(ne)"
+    state = {
+        "name": name,
+        "level": 1,
+        "score": 0,
+        "streak": 0,
+        "correct_since_reward": 0,
+        "level_correct": 0,
+        "question": "",
+        "answer": 0,
+        "waiting_next": False,
+    }
+    question, answer = generate_question(state["level"])
+    state["question"] = question
+    state["answer"] = answer
+
+    status = _status_text(state)
+    return (
+        state,
+        gr.update(visible=False),          # hide welcome panel
+        gr.update(visible=True),           # show game panel
+        f"Bonjour **{name}** ! C'est parti 🚀",
+        status,
+        f"## {question} = ?",
+        "",                                # clear input
+        "",                                # clear feedback
+        None,                              # clear image
+        gr.update(visible=False),          # hide reward panel
+    )
+
+
+def check_answer(user_input: str, state: dict):
+    """Validate the answer and update game state."""
+    if not state or state.get("waiting_next"):
+        return (state,) + _no_change_outputs(state)
+
+    try:
+        user_answer = int(user_input.strip())
+    except ValueError:
+        return (
+            state,
+            _status_text(state),
+            f"## {state['question']} = ?",
+            "",
+            "⚠️ Écris un nombre entier !",
+            None,
+            gr.update(visible=False),
+        )
+
+    correct = user_answer == state["answer"]
+
+    if correct:
+        state["score"] += 1
+        state["streak"] += 1
+        state["correct_since_reward"] += 1
+        state["level_correct"] += 1
+
+        # Check level-up
+        level_msg = ""
+        leveled_up = False
+        threshold = LEVEL_THRESHOLDS.get(state["level"], 999)
+        if state["level_correct"] >= threshold and state["level"] < 4:
+            state["level"] += 1
+            state["level_correct"] = 0
+            level_msg = level_up_message(state["level"])
+            leveled_up = True
+
+        # Check reward
+        reward_image = None
+        reward_visible = False
+        if state["correct_since_reward"] >= REWARD_EVERY:
+            state["correct_since_reward"] = 0
+            reward_image, _ = generate_reward_image(state["streak"])
+            reward_visible = True
+
+        # Next question
+        question, answer = generate_question(state["level"])
+        state["question"] = question
+        state["answer"] = answer
+
+        streak_emoji = "🔥" * min(state["streak"], 5)
+        if leveled_up:
+            feedback = f"✅ Correct ! {level_msg}"
+        else:
+            feedback = f"✅ Bravo ! {streak_emoji}" if state["streak"] > 1 else "✅ Correct !"
+
+        return (
+            state,
+            _status_text(state),
+            f"## {question} = ?",
+            "",
+            feedback,
+            reward_image,
+            gr.update(visible=reward_visible),
+        )
+
+    else:
+        state["streak"] = 0
+        feedback = f"❌ Raté ! La réponse était **{state['answer']}**. Essaie encore !"
+        # New question after wrong answer
+        question, answer = generate_question(state["level"])
+        state["question"] = question
+        state["answer"] = answer
+        return (
+            state,
+            _status_text(state),
+            f"## {question} = ?",
+            "",
+            feedback,
+            None,
+            gr.update(visible=False),
+        )
+
+
+def _status_text(state: dict) -> str:
+    if not state:
+        return ""
+    level_name = LEVEL_NAMES.get(state["level"], "")
+    return (
+        f"👤 {state['name']}  |  "
+        f"⭐ Score : {state['score']}  |  "
+        f"📚 Niveau : {level_name}"
+    )
+
+
+def _no_change_outputs(state):
+    return (
+        _status_text(state),
+        f"## {state.get('question', '')} = ?",
+        "",
+        "",
+        None,
+        gr.update(visible=False),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Gradio UI
+# ---------------------------------------------------------------------------
+
+CSS = """
+#title { text-align: center; font-size: 2em; margin-bottom: 0.2em; }
+#subtitle { text-align: center; color: #888; margin-bottom: 1em; }
+#question-box { text-align: center; font-size: 2.5em; font-weight: bold; padding: 0.5em; }
+#feedback-box { text-align: center; font-size: 1.3em; min-height: 2em; }
+#status-box { text-align: center; padding: 0.4em; background: #f9f0ff; border-radius: 8px; }
+#reward-img { border-radius: 16px; }
+.answer-input input { font-size: 2em !important; text-align: center !important; }
+"""
+
+with gr.Blocks(title="🐾 MathAnimaux", theme=gr.themes.Soft(primary_hue="purple", secondary_hue="pink")) as demo:
+
+    state = gr.State({})
+
+    # ---- Header ----
+    gr.Markdown("# 🐾 MathAnimaux", elem_id="title")
+    gr.Markdown("*Calcule bien et gagne des images d'animaux trop mignons !*", elem_id="subtitle")
+
+    # ---- Welcome panel ----
+    with gr.Group(visible=True) as welcome_panel:
+        gr.Markdown("### 👋 Qui es-tu ?")
+        player_name = gr.Textbox(
+            placeholder="Écris ton prénom…",
+            label="Ton prénom",
+            max_lines=1,
+        )
+        start_btn = gr.Button("🚀 Commencer !", variant="primary", size="lg")
+
+    # ---- Game panel ----
+    with gr.Group(visible=False) as game_panel:
+        hello_msg = gr.Markdown("")
+        status_md = gr.Markdown("", elem_id="status-box", container=True)
+
+        question_md = gr.Markdown("", elem_id="question-box")
+
+        answer_input = gr.Textbox(
+            placeholder="Ta réponse…",
+            label="Ta réponse",
+            max_lines=1,
+            elem_classes=["answer-input"],
+        )
+        submit_btn = gr.Button("✔️ Valider", variant="primary")
+
+        feedback_md = gr.Markdown("", elem_id="feedback-box")
+
+        # ---- Reward panel ----
+        with gr.Group(visible=False) as reward_panel:
+            gr.Markdown("### 🎁 Bravo ! Voici ta récompense !")
+            reward_image = gr.Image(
+                label="",
+                show_label=False,
+                elem_id="reward-img",
+                height=400,
+            )
+
+    # ---- Restart button (always visible once game started) ----
+    restart_btn = gr.Button("🔄 Recommencer", variant="secondary", size="sm")
+
+    # ---- Wiring ----
+    start_outputs = [
+        state, welcome_panel, game_panel,
+        hello_msg, status_md, question_md,
+        answer_input, feedback_md, reward_image, reward_panel,
+    ]
+    start_btn.click(start_game, inputs=[player_name, state], outputs=start_outputs)
+    player_name.submit(start_game, inputs=[player_name, state], outputs=start_outputs)
+
+    check_outputs = [
+        state, status_md, question_md, answer_input, feedback_md, reward_image, reward_panel,
+    ]
+    submit_btn.click(check_answer, inputs=[answer_input, state], outputs=check_outputs)
+    answer_input.submit(check_answer, inputs=[answer_input, state], outputs=check_outputs)
+
+    restart_btn.click(
+        lambda: (gr.update(visible=True), gr.update(visible=False), {}, "", ""),
+        outputs=[welcome_panel, game_panel, state, player_name, hello_msg],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch(css=CSS)

image_generator.py

@@ -0,0 +1,127 @@
+import random
+import os
+import torch
+
+# Patch for torch < 2.4 which lacks torch.xpu (required by diffusers >= 0.30)
+if not hasattr(torch, "xpu"):
+    class _MockXPU:
+        is_available = staticmethod(lambda: False)
+        device_count = staticmethod(lambda: 0)
+        empty_cache = staticmethod(lambda: None)
+        manual_seed = staticmethod(lambda seed: None)
+        reset_peak_memory_stats = staticmethod(lambda: None)
+        max_memory_allocated = staticmethod(lambda: 0)
+        synchronize = staticmethod(lambda: None)
+    torch.xpu = _MockXPU()
+
+# ---------------------------------------------------------------------------
+# Detect if running on HuggingFace Spaces with ZeroGPU
+# ---------------------------------------------------------------------------
+
+IS_HF_SPACE = os.environ.get("SPACE_ID") is not None
+
+if IS_HF_SPACE:
+    import spaces
+
+# ---------------------------------------------------------------------------
+# Animal reward prompts — escalate with streak
+# ---------------------------------------------------------------------------
+
+ANIMALS = [
+    "bunny", "kitten", "puppy", "baby panda", "duckling",
+    "baby fox", "hedgehog", "baby penguin", "baby koala",
+    "baby deer", "hamster", "baby owl", "baby elephant",
+]
+
+STYLES = [
+    "kawaii digital art",
+    "soft watercolor illustration",
+    "cute cartoon style",
+    "pastel chibi illustration",
+]
+
+def build_prompt(streak: int) -> str:
+    animal = random.choice(ANIMALS)
+    style = random.choice(STYLES)
+
+    if streak <= 2:
+        mood = "cute"
+        extras = "with big sparkling eyes, soft pastel colors"
+    elif streak <= 5:
+        mood = "super cute and happy"
+        extras = "with big sparkling eyes, glitter, pastel rainbow colors, smiling"
+    else:
+        mood = "magically adorable, ultra fluffy"
+        extras = (
+            "with big sparkling eyes, magical sparkles, rainbow aura, "
+            "tiny crown, pastel colors, looking amazed"
+        )
+
+    prompt = (
+        f"A {mood} {animal}, {style}, {extras}, "
+        "white background, children's book illustration style, "
+        "high quality, detailed"
+    )
+    return prompt
+
+
+# ---------------------------------------------------------------------------
+# Pipeline loader (cached so we only load once)
+# ---------------------------------------------------------------------------
+
+_pipe = None
+
+def get_pipeline():
+    global _pipe
+    if _pipe is not None:
+        return _pipe
+
+    from diffusers import FluxPipeline
+
+    print("Loading FLUX.1-schnell pipeline...")
+    _pipe = FluxPipeline.from_pretrained(
+        "black-forest-labs/FLUX.1-schnell",
+        torch_dtype=torch.bfloat16,
+    )
+
+    # Device selection: CUDA > MPS (Apple Silicon) > CPU
+    if torch.cuda.is_available():
+        _pipe = _pipe.to("cuda")
+    elif torch.backends.mps.is_available():
+        _pipe = _pipe.to("mps")
+    else:
+        # CPU fallback — slow but works
+        _pipe.enable_model_cpu_offload()
+
+    print("Pipeline ready.")
+    return _pipe
+
+
+# ---------------------------------------------------------------------------
+# Main generation function
+# Two versions: one with @spaces.GPU for HF, one plain for local
+# ---------------------------------------------------------------------------
+
+def _generate(streak: int):
+    pipe = get_pipeline()
+    prompt = build_prompt(streak)
+    print(f"Generating image | streak={streak} | prompt: {prompt}")
+    result = pipe(
+        prompt=prompt,
+        num_inference_steps=4,   # schnell is optimised for 1-4 steps
+        guidance_scale=0.0,      # schnell doesn't use CFG
+        height=512,
+        width=512,
+    )
+    return result.images[0], prompt
+
+
+if IS_HF_SPACE:
+    @spaces.GPU(duration=60)
+    def generate_reward_image(streak: int):
+        """Generate a cute animal image as a reward (HF Spaces / ZeroGPU)."""
+        return _generate(streak)
+else:
+    def generate_reward_image(streak: int):
+        """Generate a cute animal image as a reward (local)."""
+        return _generate(streak)

math_engine.py

@@ -0,0 +1,61 @@
+import random
+
+# Levels definition: (operation_label, generator_function)
+# Targeting ages 9-10 (French CE2/CM1 curriculum)
+
+def generate_question(level: int) -> tuple[str, int]:
+    """
+    Returns (question_string, correct_answer) for the given level.
+    Levels:
+      1 - Addition  (numbers 1-30)
+      2 - Subtraction (result always positive, numbers 1-30)
+      3 - Multiplication tables (2 to 9)
+      4 - Mixed bag (all of the above)
+    """
+    if level == 1:
+        a = random.randint(1, 30)
+        b = random.randint(1, 30)
+        return f"{a} + {b}", a + b
+
+    elif level == 2:
+        a = random.randint(1, 30)
+        b = random.randint(1, a)  # ensure positive result
+        return f"{a} - {b}", a - b
+
+    elif level == 3:
+        a = random.randint(2, 9)
+        b = random.randint(2, 9)
+        return f"{a} × {b}", a * b
+
+    else:  # level 4 — mixed
+        op = random.choice(["add", "sub", "mul"])
+        if op == "add":
+            a = random.randint(10, 50)
+            b = random.randint(10, 50)
+            return f"{a} + {b}", a + b
+        elif op == "sub":
+            a = random.randint(10, 50)
+            b = random.randint(1, a)
+            return f"{a} - {b}", a - b
+        else:
+            a = random.randint(2, 12)
+            b = random.randint(2, 12)
+            return f"{a} × {b}", a * b
+
+
+LEVEL_NAMES = {
+    1: "➕ Additions",
+    2: "➖ Soustractions",
+    3: "✖️ Multiplications",
+    4: "🎲 Mélange",
+}
+
+LEVEL_THRESHOLDS = {1: 5, 2: 5, 3: 5, 4: 999}  # correct answers needed to level up
+
+def level_up_message(level: int) -> str:
+    messages = {
+        2: "🎉 Bravo ! Tu passes aux soustractions !",
+        3: "🌟 Incroyable ! Place aux multiplications !",
+        4: "🏆 Tu es un(e) champion(ne) ! Mode expert activé !",
+    }
+    return messages.get(level, "")

requirements.txt

@@ -0,0 +1,9 @@
+gradio>=4.40.0
+diffusers>=0.30.0
+transformers>=4.44.0
+accelerate>=0.33.0
+torch>=2.2.0
+numpy<2
+sentencepiece
+protobuf
+spaces