Update README.md

README.md

@@ -1,3 +1,85 @@
----
-license: mit
----
+---
+license: mit
+---
+# AI Math Tutor for Early Learners
+
+**Numeracy-tuned small language model** for short, child-friendly math explanations.  
+This repository contains the **merged float16** checkpoint (all weights in one folder: `model.safetensors` + config + tokenizer files).
+
+| | |
+|---|---|
+| **Model page** | [https://huggingface.co/AddisuSeteye/AI_Math_Tutor_for_Early_Learners](https://huggingface.co/AddisuSeteye/AI_Math_Tutor_for_Early_Learners) |
+| **Source code** | [https://github.com/AdaSeteye/AI_Math_Tutor_for_Early_Learners](https://github.com/AdaSeteye/AI_Math_Tutor_for_Early_Learners) |
+| **License** | MIT |
+
+## Model details
+
+- **Architecture:** `GPT2LMHeadModel` (6 layers, 768 hidden size, 12 attention heads) — same family as [distilgpt2](https://huggingface.co/distilgpt2) used as the base for the training pipeline in this project.
+- **Format:** Merged full model in **FP16** (`model.safetensors`), with `config.json`, `generation_config.json`, and tokenizer files.
+- **Training:** Supervised fine-tuning with **LoRA** (QLoRA when 4-bit is available), then **merge** into a single Hugging Face–compatible directory (`merged_f16`).  
+- **Training data:** `numeracy_instruct.jsonl` — short user/assistant **chat-style** turns (counting, addition, subtraction, simple word problems) for early numeracy.
+- **Intended use:** Prototype / teaching demo for an **AI Math Tutor** context; not a production safety-critical system for unsupervised use with children without human oversight.
+
+## Files in this repo (upload from `merged_f16`)
+
+| File | Role |
+|------|------|
+| `model.safetensors` | Merged model weights (FP16) |
+| `config.json` | Model configuration |
+| `generation_config.json` | Default generation settings |
+| `tokenizer.json` | Tokenizer (JSON) |
+| `tokenizer_config.json` | Tokenizer config |
+
+## How to use
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+import torch
+
+model_id = "AddisuSeteye/AI_Math_Tutor_for_Early_Learners"
+
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    torch_dtype=torch.float16,
+    device_map="auto",
+)
+
+# Example: single-turn style prompt (match your training format in practice)
+text = "You are a math helper. How many is 2 + 1?"
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
+out = model.generate(**inputs, max_new_tokens=80, do_sample=True, top_p=0.9)
+print(tokenizer.decode(out[0], skip_special_tokens=True))
+```
+
+### Requirements
+
+- `transformers` (version compatible with your `config.json`, e.g. 4.36+)
+- `torch`
+- `safetensors` (for loading `.safetensors`)
+
+## Limitations
+
+- Trained for **short** numeracy-style responses; may **hallucinate** or be incorrect on out-of-distribution questions.
+- **Not** a replacement for a teacher or parent; early-learner products should add safety, privacy, and pedagogy review.
+- If you re-train on a different base (e.g. a larger chat model) and re-upload, update this card to match the new `config.json`.
+
+## Citation
+
+If you use this model, please cite the project repository and the Hugging Face model page. Example:
+
+```bibtex
+@misc{aimathtutor2026,
+  title   = {AI Math Tutor for Early Learners},
+  author  = {Addisu Seteye},
+  year    = {2026},
+  howpublished = {\url{https://huggingface.co/AddisuSeteye/AI_Math_Tutor_for_Early_Learners}}
+}
+```
+
+## Project context
+
+This checkpoint is one deliverable of the **S2.T3.1** numeracy tutor work: instruction data in `data/T3.1_Math_Tutor/`, training script `tutor/llm_qlora.py` (see the GitHub repo for the full app, curriculum, and on-device tutor pipeline). The **Gradio child demo** in that repo does not load this merged checkpoint by default; the main product loop uses a separate pipeline (TTS, ASR, curriculum) described in the GitHub `README.md`.
+
+---
+