Upload README.md with huggingface_hub

README.md

@@ -3,37 +3,84 @@ language:
 - en
 license: apache-2.0
 tags:
-- indian-culture
-- culture
-- history
-- philosophy
+- education
+- math
+- elementary-math
+- readability
+- tutoring
+- usable-math
+- estella-explainer
+- math-word-problems
 - fine-tuned
+- gemma
+- gemma-4
 - unsloth
-- llama
 - lora
-base_model: unsloth/llama-3.2-3B-bnb-4bit
+- open-educational-resource
+base_model: unsloth/gemma-4-E4B-it
 pipeline_tag: text-generation
 ---
 
-# 🇮🇳 Indian Culture LLM
+# Estella Explainer LLM
 
-A fine-tuned language model focused on **Indian culture, history, philosophy, arts, and traditions** — built to answer questions about one of the world's oldest and richest civilizations.
+**An open-weights fine-tuned language model that generates child-friendly readability hints for elementary and middle school math word problems — trained on the pedagogical framework of [Usable Math](https://usablemath.org), an open educational resource developed at the University of Massachusetts Amherst.**
 
-## What This Model Knows
+---
+
+## Overview
+
+Understanding a math word problem is a prerequisite to solving it. Research in mathematics education — including the foundational work of George Pólya (*How to Solve It*, 1945) and the Feynman Technique for conceptual clarity — establishes that students who cannot parse the *language* of a math problem are blocked from applying the mathematical operations they otherwise know.
+
+**Estella Explainer LLM** is a domain-fine-tuned version of Google's Gemma 4 E4B model, trained to fulfill the role of *Estella Explainer* — a virtual reading and language coach from the Usable Math platform. Estella's function is precisely scoped: she helps students understand **what a math problem is asking**, without solving it. She does not compute answers. She does not show steps. She clarifies language, identifies known quantities, and names the unknown — using vocabulary accessible to children in grades 3 through 8.
+
+This model is an open-weights alternative to the existing [Estella Explainer Math Bot 2](https://chatgpt.com/g/g-69c817abf970819197e955c26eb15e3d-estella-explainer-math-bot-2), which is powered by GPT-4 and requires a ChatGPT account. This model runs entirely open — no proprietary API, no account required.
+
+---
+
+## Pedagogical Framework
+
+### Estella's Role in Usable Math
+
+Usable Math (formerly 4mality) is a Google Slides-based interactive math tutoring system for grades 3–6, developed in the College of Education at the University of Massachusetts Amherst. Each math word problem in the system is accompanied by hints from four virtual coaches:
+
+- **Estella Explainer** — *Reading and Language*: restates the problem in simple language; identifies what is known and what is being asked
+- **Chef Math Bear** — *Computation*: suggests arithmetic operations
+- **How-to-Hound** — *Strategy*: offers problem-solving approaches (rounding, elimination, estimation)
+- **Visual Vicuna** — *Visualization*: suggests diagrams, charts, or drawings
+
+This model exclusively replicates **Estella's** function.
+
+### Design Principles
 
-This model has been trained on high-quality instruction pairs covering:
+Estella hints are governed by the following rules, encoded in the model's training:
 
-- **Hindu Mythology** — Mahabharata, Ramayana, Puranas, key deities and their stories
-- **Indian Philosophy** — Vedanta, Advaita, Yoga (Patanjali's 8 limbs), Bhakti movement, Jainism, Buddhism, Sikhism
-- **Classical Arts** — Bharatanatyam, Kathak, Odissi, Kuchipudi, Manipuri, Mohiniyattam, Kathakali, Carnatic and Hindustani music, Raga system, Gharanas
-- **Festivals** — Diwali, Holi, Navratri, Durga Puja, Onam, Pongal, Kumbh Mela, Rath Yatra, Thrissur Pooram, Garba/Dandiya
-- **Indian History** — Indus Valley Civilization, Vedic period, Maurya and Gupta Empires, Mughal era, Bhakti movement, Independence movement, Partition
-- **Key Figures** — Gandhi, Ambedkar, Ashoka, Chandragupta, Akbar, Shivaji, Tagore, Vivekananda, Ramanujan, Aryabhata, Tansen, MS Subbulakshmi, Ravi Shankar, Lata Mangeshkar, Mirabai, Kabir Das, Adi Shankaracharya
-- **Ayurveda & Wellness** — Doshas, Panchakarma, Ayurvedic cooking, medicinal plants (Tulsi, Neem, Peepal)
-- **Regional Cuisine** — North vs South Indian food, Mughal culinary contributions, Ayurvedic cooking, Indian spices
-- **Traditional Art Forms** — Madhubani painting, Warli art, Pattachitra, Kolam/Rangoli, Tanjore painting
-- **Sacred Texts** — Bhagavad Gita, Upanishads, Arthashastra, Thirukkural, Panchatantra, Natya Shastra
-- **Architecture & Heritage** — Taj Mahal, Hampi, Nalanda University, Chola temples, Vastu Shastra
+1. **Give exactly one hint.** No multi-part explanations.
+2. **Do not solve the problem.** The answer is never computed or stated.
+3. **Do not show calculation steps.** The hint does not model arithmetic.
+4. **Identify what is known.** State the given information clearly.
+5. **Identify what is unknown.** Name what the student needs to find.
+6. **Use very simple language.** Target Flesch Reading Ease 90���100 (very easy; equivalent to Grade 3–4 reading level).
+7. **Use characteristic phrases.** "We know...", "We are looking for...", "Think about...", "Think: ..."
+8. **Be friendly and encouraging.** Tone is warm, not academic.
+
+### Theoretical Grounding
+
+- **Pólya's Problem-Solving Framework**: Estella operationalizes the *Understanding the Problem* phase — Pólya's first step — by separating comprehension from computation.
+- **Feynman Technique**: Complex math vocabulary is broken into simple, concrete language, reflecting the principle that true understanding means being able to explain something simply.
+- **Flesch-Kincaid Readability**: Hints are calibrated to Flesch Reading Ease 90–100, corresponding to very simple prose readable by early elementary students.
+
+---
+
+## Scope
+
+This model generates readability hints for:
+
+- **Grade levels**: 3 through 8 (elementary and middle school)
+- **Topics covered**: Area and Perimeter, Rounding, Multiplication and Division, Algebraic Thinking, Addition and Subtraction, Fractions, Decimals, Place Value, Measurement, Money, Geometry, Charts and Graphs, Estimation, Ratios, Proportions, and Percentages
+- **NOT included**: High school mathematics (Algebra II, Trigonometry, Calculus, Statistics)
+- **Language**: English only
+
+---
 
 ## How to Use
 
@@ -41,83 +88,150 @@ This model has been trained on high-quality instruction pairs covering:
 from transformers import AutoModelForCausalLM, AutoTokenizer
 import torch
 
-model_id = "sgattup/IndianCultureLLM"
+model_id = "sgattup/EstellaExplainerLLM"
 tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16, device_map="auto")
-
-ALPACA_PROMPT = """Below is a question or instruction about Indian culture.
-Write a thoughtful, accurate, and detailed response.
-
-### Instruction:
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    torch_dtype=torch.float16,
+    device_map="auto"
+)
+
+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."""
+
+PROMPT = SYSTEM_PROMPT + """
+
+### Math Problem:
 {}
 
-### Response:
+### Estella's Hint:
 """
 
-def ask(question):
-    prompt = ALPACA_PROMPT.format(question)
+def ask_estella(problem, max_tokens=150):
+    prompt = PROMPT.format(problem)
     inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
-    outputs = model.generate(**inputs, max_new_tokens=512, temperature=0.7, do_sample=True)
+    outputs = model.generate(
+        **inputs,
+        max_new_tokens=max_tokens,
+        temperature=0.7,
+        do_sample=True,
+        repetition_penalty=1.1
+    )
     response = tokenizer.decode(outputs[0], skip_special_tokens=True)
-    return response.split("### Response:")[-1].strip()
+    return response.split("### Estella's Hint:")[-1].strip()
 
-print(ask("What is the significance of Diwali in Indian culture?"))
-print(ask("Explain the eight limbs of Yoga according to Patanjali."))
-print(ask("Who was Adi Shankaracharya and what did he teach?"))
+# Example usage
+print(ask_estella("A rectangle has a length of 12 cm and a width of 5 cm. What is the area?"))
+print(ask_estella("Sam had 3/4 of a pizza. He ate 1/4. How much is left?"))
+print(ask_estella("A store sells apples for $0.75 each. Jake buys 6 apples. How much does he spend?"))
 ```
 
-## Example Outputs
+---
+
+## Illustrative Outputs
 
-**Q: What is a Raga in Indian classical music?**
+**Problem:** A rectangle has a length of 12 cm and a width of 5 cm. What is the area?
+> We know: length = 12 cm and width = 5 cm. Area means length × width. We are looking for how much space is inside the rectangle.
 
-> A Raga is the fundamental melodic framework of Indian classical music — not merely a scale but a complete musical personality with rules about which notes to use, how to ascend and descend, what mood it evokes, and what time of day it should be performed. Different ragas are associated with times of day: Bhairav at dawn, Yaman at dusk...
+**Problem:** Sam had 3/4 of a pizza. He ate 1/4. How much is left?
+> We know: Sam started with 3/4 and ate 1/4. The bottom numbers match. Think: 3/4 - 1/4. We are looking for how much pizza remains.
 
-**Q: Who was Dr. B.R. Ambedkar?**
+**Problem:** A store sells apples for $0.75 each. Jake buys 6 apples. How much does he spend?
+> We know: each apple costs $0.75 and Jake buys 6. Think: 6 groups of $0.75. We are looking for the total cost.
 
-> Dr. Bhimrao Ramji Ambedkar (1891–1956) was one of the most transformative figures in modern Indian history. Born into a Dalit family, he overcame severe discrimination to earn degrees from Columbia University and the London School of Economics. He was the principal architect of India's Constitution, which abolished untouchability and guaranteed fundamental rights to all citizens regardless of caste...
+**Problem:** Round 4,567 to the nearest hundred.
+> Look at the tens digit in 4,567. Is it 5 or more? That tells you which way to round. We are looking for the nearest hundred.
 
-## Model Details
+**Problem:** A class has 28 students. They form groups of 4. How many groups are there?
+> We know: 28 students and each group has 4. Think: 28 shared equally into groups of 4. We are looking for the number of groups.
 
-| Property | Value |
+---
+
+## Intended Users
+
+This model is designed for:
+
+- **Elementary and middle school teachers** seeking on-demand language scaffolds for math problems
+- **Math tutors and interventionists** who want to rephrase problems for struggling readers
+- **Parents** supporting math homework at home
+- **Education researchers** studying AI-generated scaffolding and readability in math instruction
+- **EdTech developers** integrating open-weights readability assistance into math learning applications
+
+---
+
+## Model Specifications
+
+| Parameter | Value |
 |---|---|
-| Base Model | LLaMA 3.2 3B (unsloth/llama-3.2-3B-bnb-4bit) |
-| Fine-tuning Method | QLoRA via Unsloth |
+| Base Model | Gemma 4 Effective 4B (`unsloth/gemma-4-E4B-it`) |
+| Fine-tuning Method | QLoRA (Quantized Low-Rank Adaptation) via Unsloth |
+| Quantization | 4-bit NF4 with double quantization |
 | LoRA Rank | 16 |
-| Training Epochs | 3 |
-| Dataset Size | 75+ high-quality instruction pairs |
+| LoRA Alpha | 32 |
+| Training Epochs | 4 |
+| Learning Rate | 2e-4 (AdamW 8-bit optimizer) |
+| Max Sequence Length | 2048 tokens |
+| Training Hardware | Google Colab T4 GPU (free tier) |
+| Dataset | 120+ curated Estella-style hint pairs (grades 3–8) |
+| Prompt Format | System role + Problem/Hint instruction template |
 | Language | English |
 | License | Apache 2.0 |
 
+---
+
+## About Usable Math
+
+Usable Math is a free, open educational resource (OER) licensed under CC-BY-NC 4.0, developed by Sharon Edwards, Robert Maloy, and Sai Gattupalli in the College of Education at the University of Massachusetts Amherst. It provides Google Slides-based interactive math problem-solving modules for grades 3–6, aligned with the Massachusetts Mathematics Curriculum Framework and the Common Core State Standards for Mathematics. Visit [usablemath.org](https://usablemath.org).
+
+### Selected Publications
+
+Maloy, R. W., Gattupalli, S., & Edwards, S. A. (2024). Students Design Problem-Solving Slideshows. *Mathematics Teacher: Learning and Teaching PK-12*, 117(8), 579–582.
+
+Gattupalli, S., Edwards, S.A, Maloy, R. W., & Rancourt, M. (2023). Designing for Learning: Key Decisions for an Open Online Math Tutor for Elementary Students. *Digital Experiences in Mathematics Education*.
+
+Gattupalli, S., Maloy, R. W., & Edwards, S. (2023). Comparing Teacher-Written and AI-Generated Math Problem Solving Strategies for Elementary School Students.
+
+---
+
 ## Limitations
 
-- This is an early version trained on a relatively small dataset — responses are informative but may lack depth on niche topics
-- Primarily covers mainstream Hindu/pan-Indian cultural topics; regional and tribal cultures are underrepresented
-- Not a substitute for academic sources on complex historical or religious topics
-- May reflect certain perspectives more than others given the training data
+- **Dataset scale:** Trained on 120+ examples — effective for common problem types, but coverage of unusual problem structures is limited. Performance improves substantially when augmented with extracted hints from Usable Math PDF modules.
+- **No computation:** The model is explicitly trained *not* to solve problems. It will decline to compute answers by design.
+- **English only:** No multilingual support in this version.
+- **Not a teacher replacement:** Estella provides language scaffolding, not instruction. Human educators remain essential for interpreting student needs and providing individualized support.
 
-## Future Plans
+---
 
-- Expand dataset to 2,000+ examples
-- Add regional language support (Tamil, Telugu, Hindi, Bengali)
-- Cover tribal and indigenous Indian cultures more deeply
-- Add a HuggingFace Space for interactive demos
-- Train a larger 7B version for improved depth
+## Companion Models
 
-## Training Code
+- **[sgattup/RagaLakshanaLLM](https://huggingface.co/sgattup/RagaLakshanaLLM)** — Indian classical music raga theory
+- **[sgattup/KonakolSwaraLLM](https://huggingface.co/sgattup/KonakolSwaraLLM)** — Carnatic rhythmic and swara composition
+- **[sgattup/IndianCultureLLM](https://huggingface.co/sgattup/IndianCultureLLM)** — Indian culture, history, and philosophy
 
-Training code and dataset are available at:
-[github.com/sai-educ/indian-culture-llm](https://github.com/sai-educ/indian-culture-llm)
+---
 
 ## Citation
 
-If you use this model in your work, please cite:
-
-```
-@misc{IndianCultureLLM2026,
-  author = {sgattup},
-  title = {Indian Culture LLM},
-  year = {2026},
-  publisher = {HuggingFace},
-  url = {https://huggingface.co/sgattup/IndianCultureLLM}
+```bibtex
+@misc{EstellaExplainerLLM2026,
+  author       = {Gattupalli, Sai and Maloy, Robert W. and Edwards, Sharon A.},
+  title        = {Estella Explainer LLM: An Open-Weights Readability Coach for Elementary Math Word Problems},
+  year         = {2026},
+  publisher    = {HuggingFace},
+  howpublished = {\url{https://huggingface.co/sgattup/EstellaExplainerLLM}},
+  note         = {Fine-tuned from Google Gemma 4 E4B; based on the Usable Math OER (usablemath.org)}
 }
 ```
+
+---
+
+*This model is part of the Usable Math AI initiative — exploring open, educator-friendly alternatives to proprietary AI tools for elementary mathematics instruction.*