Professional minimalist UI (English, no emojis); SFT model; tighter decoding + anti-hallucination prompt

README.md

@@ -1,8 +1,8 @@
 ---
 title: EduCrate — Socratic Tutor
-emoji: 🦉
-colorFrom: blue
-colorTo: indigo
+emoji: 📘
+colorFrom: gray
+colorTo: blue
 sdk: gradio
 app_file: app.py
 pinned: false
@@ -24,42 +24,42 @@ models:
   - fabrizziomcl/nanoballena-qwen3-socratic
 ---
 
-# 🦉 EduCrate — A Socratic Tutor for Peruvian Public-School Students
+# 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**.
+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.
 
 ## Links
-- 🎬 **Demo video:** _TODO: paste YouTube link here_
-- 📣 **Social post:** _TODO: paste post link here_
-- 🤖 **Model:** https://huggingface.co/fabrizziomcl/nanoballena-qwen3-socratic
+- Demo video: _TODO: paste link_
+- Social post: _TODO: paste link_
+- Model: https://huggingface.co/fabrizziomcl/nanoballena-qwen3-sft
 
 ## 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.
+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 about 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).
+- Base: Qwen/Qwen3-0.6B (596M), fine-tuned with SFT (a GRPO variant is also published)
+  on ~4,900 Spanish Socratic dialogues generated for this project. Runs on CPU.
+- Models: `fabrizziomcl/nanoballena-qwen3-sft` · `fabrizziomcl/nanoballena-qwen3-socratic`
 
 ## 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 |
+| 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.
+Click an example, or: (optional) paste a reading passage, choose what you need, and ask
+your question. The tutor replies in Spanish with a guiding question, never the answer.
+It is a 0.6B model, so guidance is sometimes imperfect.
 
-> Built for the **Build Small Hackathon** — track *Backyard AI*, **Tiny Titan** badge (≤4B).
+> 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

@@ -1,57 +1,53 @@
 # -*- coding: utf-8 -*-
 """
-EduCrate — Socratic Tutor (Gradio app)
+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).
+UI in English (international judges); the tutoring happens in Spanish.
+Model: Qwen3-0.6B fine-tuned (SFT). Runs on CPU. Gradio 6 (messages format).
 """
 import os
 import gradio as gr
 import torch
 
-MODEL_ID = os.environ.get("MODEL_ID", "fabrizziomcl/nanoballena-qwen3-socratic")
+MODEL_ID = os.environ.get("MODEL_ID", "fabrizziomcl/nanoballena-qwen3-sft")
 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).
+# Anchors the Socratic behavior (mirrors the training system prompt) + anti-hallucination.
 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 "
+    "Guía con UNA sola 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."
+    "respuesta. En matemáticas usa solo el método correcto del problema; no inventes "
+    "reglas que no apliquen. No menciones 'el texto' a menos que el estudiante haya "
+    "compartido una lectura. Sé breve, claro y amable."
 )
 
-# maieutic-inspired modes: reference (give a fact) vs reasoning (counter-question).
 MODES = {
-    "💬 Just chat": "",
-    "🤔 Understand my mistake": (
+    "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, "
+    "I need a fact or formula": (
+        "\n\nEl estudiante pide un dato o fórmula puntual: puedes darlo 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).
+# Example cards: (button label in English, reading passage, Spanish student message).
 EXAMPLES = [
-    ("➗ Linear equation",
-     "Solve 3x + 6 = 15 — guided, no answer",
+    ("Linear equation",
      "", "Ayúdame a resolver 3x + 6 = 15, pero no me des la respuesta."),
-    ("🍕 Adding fractions",
-     "Understand 1/2 + 1/3 step by step",
+    ("Adding fractions",
      "", "No entiendo cómo sumar 1/2 + 1/3. ¿Me ayudas a pensarlo?"),
-    ("％ Percentages",
-     "What is 20% of 50? — guide me",
+    ("Percentages",
      "", "¿Cómo calculo el 20% de 50? No me lo resuelvas, guíame paso a paso."),
-    ("📖 Reading comprehension",
-     "Main idea of a short passage",
+    ("Reading comprehension",
      "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."),
@@ -88,7 +84,7 @@ def _generate(messages, max_new_tokens):
     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,
+            temperature=0.45, top_p=0.9, repetition_penalty=1.15,
             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>"):
@@ -103,7 +99,7 @@ def respond(user_msg, history, reading_text, mode, hint_mode):
     if model is None:
         return history + [
             {"role": "user", "content": user_msg},
-            {"role": "assistant", "content": f"⚠️ Model failed to load ({_load_error})."},
+            {"role": "assistant", "content": f"Model failed to load ({_load_error})."},
         ], ""
     system = SYSTEM_PROMPT + MODES.get(mode, "")
     if reading_text and reading_text.strip():
@@ -114,7 +110,7 @@ def respond(user_msg, history, reading_text, mode, hint_mode):
     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)
+    reply = _generate(messages, max_new_tokens=160 if hint_mode else 220)
     return history + [
         {"role": "user", "content": user_msg},
         {"role": "assistant", "content": reply},
@@ -122,88 +118,79 @@ def respond(user_msg, history, reading_text, mode, hint_mode):
 
 
 CSS = """
-.educrate-hero {text-align:center; padding: 6px 0 2px 0;}
-.ex-card {border:1px solid #e5e7eb; border-radius:12px; padding:6px 10px;}
+.gradio-container {max-width: 1024px !important; margin: 0 auto;}
+#title {text-align:center; margin-bottom: 0;}
+#subtitle {text-align:center; color:#6b7280; margin-top:2px; font-size:0.95rem;}
+.example-btn button {font-weight:500;}
 footer {visibility:hidden}
 """
 
-with gr.Blocks(title="EduCrate — Socratic Tutor", theme=gr.themes.Soft(), css=CSS) as demo:
+with gr.Blocks(title="EduCrate - Socratic Tutor", theme=gr.themes.Soft(
+        primary_hue="slate", neutral_hue="slate"), css=CSS) as demo:
+    gr.Markdown("# EduCrate", elem_id="title")
     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>
-        """
-    )
+        "A Socratic tutor that never gives the answer — it guides with questions. "
+        "Spanish-language, for Peruvian public-school students. Math reasoning and "
+        "reading comprehension. Runs on CPU.", elem_id="subtitle")
     if _load_error:
-        gr.Markdown(f"> ⚠️ *Model `{MODEL_ID}` failed to load: {_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")
+    gr.Markdown("**Try an example** (the tutor replies in Spanish):")
     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))
+        for label, reading, message in EXAMPLES:
+            b = gr.Button(label, size="sm", elem_classes="example-btn", scale=1)
+            ex_buttons.append((b, reading, message))
 
-    with gr.Row():
+    with gr.Row(equal_height=False):
         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")
+                label="Reading passage (optional)",
+                placeholder="Paste a short text to practice reading comprehension.",
+                lines=6)
+            mode = gr.Radio(choices=list(MODES.keys()), value="Just chat",
+                            label="What do you need?")
+            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)
+            chatbot = gr.Chatbot(label="Conversation", height=460)
             user_input = gr.Textbox(
-                label="💬 Your question · tu pregunta", lines=2,
-                placeholder="Escribe aquí y presiona Enviar / Type here and press Send...",
-            )
+                label="Your question", lines=2,
+                placeholder="Type your question in Spanish and press Send.")
             with gr.Row():
-                submit_btn = gr.Button("Send / Enviar", variant="primary")
-                clear_btn = gr.Button("🗑️ New topic")
+                submit_btn = gr.Button("Send", variant="primary")
+                clear_btn = gr.Button("New topic", variant="secondary")
 
     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):
+    with gr.Accordion("About this project", 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.
+**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 about **12.7%** *Satisfactory* in math,
+with public (state) schools far behind private ones.
 
-**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.
+**The approach.** Most chatbots hand over the answer, which does not 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).
 
-**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.
+**The model.** Qwen3-0.6B fine-tuned (SFT, with a GRPO variant) on ~4,900 Spanish
+Socratic dialogues. It runs on CPU, so it works on low-resource laptops common in
+public schools — no GPU and no paid API required.
 
-**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.
+**Measured behavior (held-out mGSM-es).** The fine-tune raised the answer-withholding
+rate from 84% (base) to 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.*
+*It is a 0.6B model: guidance is sometimes imperfect. Built for the Build Small
+Hackathon (Backyard AI). Made with generative AI; validate pedagogical use with a teacher.*
             """
         )