EduCrate — Spanish Socratic tutor (Qwen3-0.6B SFT+GRPO), runs on CPU

README.md

@@ -1,13 +1,53 @@
 ---
-title: Educrate
-emoji: 📈
-colorFrom: red
-colorTo: gray
+title: EduCrate — Socratic Tutor
+emoji: 🦉
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
 app_file: app.py
 pinned: false
+license: apache-2.0
+short_description: Spanish Socratic tutor on CPU; never gives the answer.
+tags:
+  - build-small-hackathon
+  - backyard-ai
+  - tiny-titan
+models:
+  - fabrizziomcl/nanoballena-qwen3-sft
+  - fabrizziomcl/nanoballena-qwen3-socratic
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🦉 EduCrate — A Socratic Tutor for Peruvian Public-School Students
+
+**EduCrate never gives the final answer.** It guides students with one question at a
+time, detects their mistake, and offers progressive hints (the *maieutic* method) so they
+discover the answer themselves. Spanish-language tutoring focused on **mathematical
+reasoning** and **reading comprehension**, small enough to **run on CPU**.
+
+## The problem
+Peru's public secondary schools face a learning crisis. In **PISA 2022 (OECD)**, only
+**34%** of Peruvian 15-year-olds reached basic proficiency in **math** (66% below) and
+**50%** in **reading**. Peru's national assessment (**ECE / MINEDU, grade 8, 2022**) found
+only **~12.7%** *Satisfactory* in math, with public (state) schools far behind private
+ones. Most chatbots just hand over the answer — which does not build reasoning.
+
+## The model
+- Base: **Qwen/Qwen3-0.6B** (596M), fine-tuned with **SFT + GRPO** on **~4,900 Spanish
+  Socratic dialogues** generated for this project. Runs on **CPU** → no GPU, no paid API.
+- Models: `fabrizziomcl/nanoballena-qwen3-socratic` (SFT+GRPO) · `…-qwen3-sft` (SFT).
+
+## Measured behavior (held-out mGSM-es)
+| Model | Answer-withholding | Asks a question | Avg words |
+|---|---|---|---|
+| Qwen3-0.6B base | 84% | 100% | 66.5 |
+| **EduCrate (fine-tuned)** | **100%** | 100% | ~11 |
+
+Evidence of real behavioral change on unseen problems — not memorization.
+
+## How to use
+Click an **example card**, or: (optional) paste a reading passage → choose what you need
+(*understand my mistake* / *need a fact* / *just chat*) → ask your question. The tutor
+replies **in Spanish** with a guiding question, never the answer.
+
+> Built for the **Build Small Hackathon** — track *Backyard AI*, **Tiny Titan** badge (≤4B).
+> Made with generative AI; validate any pedagogical use with a teacher.

app.py

@@ -0,0 +1,211 @@
+# -*- coding: utf-8 -*-
+"""
+EduCrate — Socratic Tutor (Gradio app)
+A Spanish-language Socratic tutor for Peruvian public secondary-school students.
+
+UI in English (international judges); the tutoring itself happens in Spanish.
+Model: Qwen3-0.6B fine-tuned (SFT + GRPO). Runs on CPU.
+Gradio 6 (Chatbot uses the messages format).
+"""
+import os
+import gradio as gr
+import torch
+
+MODEL_ID = os.environ.get("MODEL_ID", "fabrizziomcl/nanoballena-qwen3-socratic")
+MAX_TURNS = int(os.environ.get("MAX_TURNS", "8"))
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+DTYPE = torch.bfloat16 if DEVICE == "cuda" else torch.float32
+
+# Anchors the Socratic behavior (mirrors the training system prompt).
+SYSTEM_PROMPT = (
+    "Eres EduCrate, un tutor socrático en español para estudiantes de secundaria "
+    "de colegios públicos del Perú (comprensión lectora y razonamiento matemático). "
+    "REGLA ABSOLUTA: NUNCA des la respuesta final ni el resultado directamente. "
+    "Guía con UNA pregunta a la vez, detecta el error del estudiante y da pistas "
+    "progresivas (primero suave, luego más concreta) hasta que él mismo descubra la "
+    "respuesta. Sé breve, amable y claro."
+)
+
+# maieutic-inspired modes: reference (give a fact) vs reasoning (counter-question).
+MODES = {
+    "💬 Just chat": "",
+    "🤔 Understand my mistake": (
+        "\n\nEl estudiante quiere entender su razonamiento: NO le des datos ni la "
+        "respuesta; respóndele con una contrapregunta que lo haga revisar su propio paso."
+    ),
+    "💡 I need a fact/formula": (
+        "\n\nEl estudiante pide un DATO o fórmula puntual: puedes dárselo de forma breve, "
+        "pero NUNCA lo apliques hasta la respuesta final por él; devuélvele la pregunta."
+    ),
+}
+
+# Example cards (Spanish prompts = real student use). Each: (title, desc, reading, message).
+EXAMPLES = [
+    ("➗ Linear equation",
+     "Solve 3x + 6 = 15 — guided, no answer",
+     "", "Ayúdame a resolver 3x + 6 = 15, pero no me des la respuesta."),
+    ("🍕 Adding fractions",
+     "Understand 1/2 + 1/3 step by step",
+     "", "No entiendo cómo sumar 1/2 + 1/3. ¿Me ayudas a pensarlo?"),
+    ("％ Percentages",
+     "What is 20% of 50? — guide me",
+     "", "¿Cómo calculo el 20% de 50? No me lo resuelvas, guíame paso a paso."),
+    ("📖 Reading comprehension",
+     "Main idea of a short passage",
+     "El reciclaje ayuda a reducir la basura en las ciudades. Si separamos los "
+     "plásticos y el papel, menos residuos llegan a los ríos.",
+     "¿Cuál es la idea principal de este texto? Guíame, no me des la respuesta."),
+]
+
+_load_error = None
+model = tokenizer = None
+try:
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+    print(f"Loading {MODEL_ID} on {DEVICE} ...")
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+    model = AutoModelForCausalLM.from_pretrained(MODEL_ID, dtype=DTYPE).to(DEVICE)
+    model.eval()
+    if DEVICE == "cpu":
+        torch.set_num_threads(int(os.environ.get("OMP_NUM_THREADS", "4")))
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+    print("Model loaded.")
+except Exception as e:  # noqa: BLE001
+    _load_error = str(e)
+    print(f"[WARN] Could not load model: {e}")
+
+
+def _render(messages):
+    try:
+        return tokenizer.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True, enable_thinking=False)
+    except TypeError:
+        return tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+
+
+def _generate(messages, max_new_tokens):
+    inputs = tokenizer(_render(messages), return_tensors="pt").to(DEVICE)
+    with torch.no_grad():
+        out = model.generate(
+            **inputs, max_new_tokens=max_new_tokens, do_sample=True,
+            temperature=0.7, top_p=0.9, repetition_penalty=1.1,
+            pad_token_id=tokenizer.pad_token_id or tokenizer.eos_token_id)
+    text = tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
+    for junk in ("<think>", "</think>"):
+        text = text.replace(junk, "")
+    return text.strip()
+
+
+def respond(user_msg, history, reading_text, mode, hint_mode):
+    history = history or []
+    if not user_msg or not user_msg.strip():
+        return history, ""
+    if model is None:
+        return history + [
+            {"role": "user", "content": user_msg},
+            {"role": "assistant", "content": f"⚠️ Model failed to load ({_load_error})."},
+        ], ""
+    system = SYSTEM_PROMPT + MODES.get(mode, "")
+    if reading_text and reading_text.strip():
+        system += f"\n\nTexto de lectura del estudiante:\n{reading_text.strip()}"
+    if hint_mode:
+        system += ("\n\nEl estudiante pidió una PISTA: da UNA sola pista corta que lo "
+                   "acerque, sin revelar la respuesta.")
+    messages = [{"role": "system", "content": system}]
+    messages += history[-2 * MAX_TURNS:]
+    messages.append({"role": "user", "content": user_msg})
+    reply = _generate(messages, max_new_tokens=180 if hint_mode else 256)
+    return history + [
+        {"role": "user", "content": user_msg},
+        {"role": "assistant", "content": reply},
+    ], ""
+
+
+CSS = """
+.educrate-hero {text-align:center; padding: 6px 0 2px 0;}
+.ex-card {border:1px solid #e5e7eb; border-radius:12px; padding:6px 10px;}
+footer {visibility:hidden}
+"""
+
+with gr.Blocks(title="EduCrate — Socratic Tutor", theme=gr.themes.Soft(), css=CSS) as demo:
+    gr.Markdown(
+        """
+        <div class="educrate-hero">
+
+        # 🦉 EduCrate — A Socratic Tutor that **never gives the answer**
+        **For Peruvian public secondary-school students** · Math reasoning & reading comprehension
+        · Runs **on CPU** (0.6B) · `Build Small` · *Backyard AI* · **Tiny Titan**
+
+        </div>
+        """
+    )
+    if _load_error:
+        gr.Markdown(f"> ⚠️ *Model `{MODEL_ID}` failed to load: {_load_error}*")
+
+    gr.Markdown("### ✨ Try an example — click a card to start a guided dialogue")
+    ex_buttons = []
+    with gr.Row():
+        for title, desc, reading, message in EXAMPLES:
+            with gr.Column(scale=1, min_width=150):
+                b = gr.Button(f"{title}\n{desc}", elem_classes="ex-card", size="md")
+                ex_buttons.append((b, reading, message))
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            reading_text = gr.Textbox(
+                label="📖 Reading passage (optional) · pega una lectura",
+                placeholder="Paste a short text to practice reading comprehension...",
+                lines=7,
+            )
+            mode = gr.Radio(choices=list(MODES.keys()), value="💬 Just chat",
+                            label="What do you need? (cambia el estilo del tutor)")
+            hint_mode = gr.Checkbox(label="💡 Give me a single short hint")
+        with gr.Column(scale=2):
+            chatbot = gr.Chatbot(label="Chat with EduCrate (responde en español)", height=440)
+            user_input = gr.Textbox(
+                label="💬 Your question · tu pregunta", lines=2,
+                placeholder="Escribe aquí y presiona Enviar / Type here and press Send...",
+            )
+            with gr.Row():
+                submit_btn = gr.Button("Send / Enviar", variant="primary")
+                clear_btn = gr.Button("🗑️ New topic")
+
+    inp = [user_input, chatbot, reading_text, mode, hint_mode]
+    submit_btn.click(respond, inp, [chatbot, user_input])
+    user_input.submit(respond, inp, [chatbot, user_input])
+    clear_btn.click(lambda: ([], "", ""), outputs=[chatbot, user_input, reading_text])
+
+    # Example cards: fill inputs (clearing chat), then auto-run one Socratic turn.
+    for b, reading, message in ex_buttons:
+        b.click(lambda r=reading, m=message: (r, m, []),
+                outputs=[reading_text, user_input, chatbot]).then(
+                respond, inp, [chatbot, user_input])
+
+    with gr.Accordion("ℹ️ About this project — why it matters", open=False):
+        gr.Markdown(
+            """
+**The problem.** Peru's public secondary schools face a deep learning crisis. In
+**PISA 2022 (OECD)**, only **34%** of Peruvian 15-year-olds reached basic proficiency in
+**mathematics** (66% below) and **50%** in **reading**. Peru's national assessment
+(**ECE / MINEDU, grade 8, 2022**) found only **~12.7%** *Satisfactory* in math — with
+public (state) schools far behind private ones and a large socioeconomic gap.
+
+**Why Socratic.** Most chatbots hand over the answer, which doesn't build reasoning.
+**EduCrate never gives the final answer** — it asks one guiding question at a time, detects
+the student's mistake, and offers progressive hints (the *maieutic* method) so the student
+discovers the answer themselves.
+
+**Why small.** A **Qwen3-0.6B** model fine-tuned (SFT + GRPO) on ~4,900 Spanish Socratic
+dialogues. It **runs on CPU**, so it works on the low-resource laptops common in public
+schools — no GPU, no paid API.
+
+**Measured behavior (held-out mGSM-es).** The fine-tune raised the *answer-withholding rate*
+from **84% (base) → 100%**, turning verbose solutions into concise guiding questions.
+
+*Built for the Build Small Hackathon (Backyard AI track). Made with generative AI; validate
+any pedagogical use with a teacher.*
+            """
+        )
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=4.44
+torch
+transformers>=4.51
+tokenizers
+accelerate