Create app.py

app.py

@@ -0,0 +1,125 @@
+"""
+Estella Explainer — HuggingFace Spaces Demo
+A math reading coach for grades 3–8, based on Usable Math (usablemath.org)
+Model: sgattup/EstellaExplainerLLM (Gemma 4 E4B fine-tuned)
+
+Deploy to a ZeroGPU Space for free GPU inference.
+"""
+
+import gradio as gr
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+MODEL_ID = "sgattup/EstellaExplainerLLM"
+
+SYSTEM_PROMPT = """You are Estella Explainer, a math reading and language coach for young learners in grades 3 through 8. Your motto is: "My job is to explain math questions clearly so you know what you are supposed to do to solve the problem."
+
+Your rules:
+- Give only ONE hint per problem.
+- Do NOT solve the problem or show the answer.
+- Do NOT show calculation steps or compute anything.
+- Help the student understand what the problem is ASKING.
+- Use very simple words and short sentences (Flesch Reading Ease 90-100).
+- Identify what is known and what is being asked.
+- Use phrases like "We know...", "We are looking for...", or "Think about...".
+- Be friendly and encouraging."""
+
+EXAMPLES = [
+    "A rectangle has a length of 12 cm and a width of 5 cm. What is the area?",
+    "Sam had 3/4 of a pizza. He ate 1/4. How much is left?",
+    "A store sells apples for $0.75 each. Jake buys 6 apples. How much does he spend?",
+    "Round 4,567 to the nearest hundred.",
+    "There are 48 students put into equal groups of 6. How many groups are there?",
+    "A bag has 5 red marbles and 3 blue marbles. What fraction of the marbles are red?",
+    "A train leaves at 10:15 AM and arrives at 1:45 PM. How long is the trip?",
+    "The perimeter of a square is 36 inches. What is the length of one side?",
+]
+
+# Load model once at startup
+print(f"Loading {MODEL_ID}...")
+tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+model = AutoModelForCausalLM.from_pretrained(
+    MODEL_ID,
+    torch_dtype=torch.float16,
+    device_map="auto"
+)
+model.eval()
+print("Model ready.")
+
+
+def ask_estella(problem: str) -> str:
+    if not problem.strip():
+        return "Please type a math word problem above."
+
+    messages = [
+        {"role": "user", "content": SYSTEM_PROMPT + f"\n\n### Math Problem:\n{problem.strip()}\n\n### Estella's Hint:"}
+    ]
+    text = tokenizer.apply_chat_template(
+        messages,
+        add_generation_prompt=True,
+        tokenize=False
+    )
+    inputs = tokenizer(text=[text], return_tensors="pt")
+    inputs = {k: v.to(model.device) for k, v in inputs.items()}
+    input_len = inputs["input_ids"].shape[1]
+
+    with torch.no_grad():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens=150,
+            temperature=0.7,
+            do_sample=True,
+            repetition_penalty=1.1,
+        )
+
+    hint = tokenizer.decode(outputs[0][input_len:], skip_special_tokens=True).strip()
+    return hint
+
+
+# Gradio UI
+with gr.Blocks(title="Estella Explainer — Math Reading Coach") as demo:
+    gr.Markdown("""
+# 📚 Estella Explainer
+### A Math Reading Coach for Grades 3–8
+
+*"My job is to explain math questions clearly so you know what you are supposed to do to solve the problem."*
+
+Estella helps students **understand** what a math problem is asking — without solving it.
+Based on [Usable Math](https://usablemath.org), an open educational resource from UMass Amherst.
+
+---
+    """)
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            problem_input = gr.Textbox(
+                label="Math Word Problem",
+                placeholder="Type or paste a math problem here...",
+                lines=4
+            )
+            submit_btn = gr.Button("Ask Estella", variant="primary")
+
+        with gr.Column(scale=2):
+            hint_output = gr.Textbox(
+                label="Estella's Hint",
+                lines=4,
+                interactive=False
+            )
+
+    gr.Examples(
+        examples=EXAMPLES,
+        inputs=problem_input,
+        label="Try these examples"
+    )
+
+    gr.Markdown("""
+---
+**Model:** [sgattup/EstellaExplainerLLM](https://huggingface.co/sgattup/EstellaExplainerLLM) · Fine-tuned Gemma 4 E4B via QLoRA
+**Project:** [Usable Math](https://usablemath.org) · UMass Amherst College of Education
+**Note:** Estella explains problems — she does not solve them or show answers.
+    """)
+
+    submit_btn.click(fn=ask_estella, inputs=problem_input, outputs=hint_output)
+    problem_input.submit(fn=ask_estella, inputs=problem_input, outputs=hint_output)
+
+demo.launch()