Update README.md

README.md

@@ -10,4 +10,146 @@ pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: 🎓 Educational Tutor
+emoji: 🎯
+colorFrom: indigo
+colorTo: yellow
+sdk: gradio
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# 🎓 Educational Text Tutor — Hugging Face Space
+
+Turn any educational text into targeted practice: **extract subtopics → generate questions → simulate students → grade & analyze → prescribe homework → personalized study summaries**.
+
+This Space is built with **Gradio** and **OpenAI**. It works out of the box on Spaces, and you can also run it locally.
+
+---
+
+## ✨ What it does
+
+- **Subtopic extraction** from your pasted learning material  
+- **Question generation** per selected subtopic (MCQ or Short Answer)  
+- **Student simulation** from brief persona prompts  
+- **Auto-grading** with per-subtopic accuracy tables  
+- **Homework prescription** (weak areas & concrete tasks)  
+- **Personalized Study Summary** for each student (strengths, weak spots, 3 goals, 7‑day micro‑plan)
+
+---
+
+## 🚀 Using this Space
+
+1. Paste your **OpenAI API key** on the **Setup** tab (format: `sk-...`), or store it as a Space **Secret** named `OPENAI_API_KEY` (recommended, see below).  
+2. Paste the **educational text** and **extract subtopics**.  
+3. **Select** subtopics to include and **generate questions** (choose MCQ/Short Answer, counts, difficulty).  
+4. Enter short **profiles** for Student 1 and Student 2 and **simulate** answers (you can edit).  
+5. Click **Grade & Analyze** to see per-subtopic accuracy, homework plans, and each student’s **personalized summary**.
+
+> The app supports both the classic Chat Completions and the newer Responses API with an automatic fallback.
+
+---
+
+## 🧰 Files you should have in this Space
+
+```
+app.py                     # Entry point (rename your main file to app.py)
+requirements.txt           # Python deps
+README.md                  # This file
+```
+
+- If your current file is `gradio_edu_app_fixed.py`, **rename it to `app.py`**.  
+- Spaces automatically runs `app.py` when `sdk: gradio` is set in the front‑matter above.
+
+**Minimal `requirements.txt`:**
+```
+gradio>=4.0.0
+openai>=1.0.0
+```
+
+(Optional) If you want to pin Python, add a `runtime.txt` (e.g., `python-3.10`).
+
+---
+
+## 🔐 Secrets & configuration (recommended)
+
+To avoid pasting keys in the UI on every run:
+
+1. Go to your Space **Settings → Variables and secrets**.  
+2. Add a **Secret** with key `OPENAI_API_KEY` and your value `sk-...`.  
+3. (Optional) Add a **Variable** `MODEL_NAME` to override the default model (e.g., `gpt-4o`).
+
+### Optional code tweak to auto-use the secret
+If your UI shows a textbox for the key, you can prefill it from the environment:
+
+```python
+import os
+api_key_in = gr.Textbox(
+    label="OpenAI API Key",
+    type="password",
+    value=os.getenv("OPENAI_API_KEY", ""),
+    placeholder="sk-..."
+)
+```
+
+The rest of the app can keep using the saved key from state.
+
+---
+
+## 🧭 App flow at a glance
+
+1) **Setup** → Save API key & model  
+2) **Subtopics** → Paste text → Extract & select subtopics  
+3) **Generate Questions** → Choose type/count/difficulty → Edit if needed  
+4) **Simulate Students** → Provide two short profiles → Auto-fill and/or edit answers  
+5) **Analysis & Homework** → Grade, per-subtopic tables, homework JSON, and **personalized summaries**
+
+The **Personalized Study Summary** contains:
+- Strengths (2–3 bullets)  
+- Weak spots (2–3 bullets)  
+- 3 measurable study goals  
+- A 7‑day micro‑plan (one action per day)  
+- A short motivation tip
+
+---
+
+## 🛠️ Notes for maintainers
+
+- Default model is `gpt-4o-mini` (changeable in the UI or via env var `MODEL_NAME`).  
+- If responses get long or time out, try reducing **questions per subtopic** or switching to a larger model.  
+- All prompts are near the top of the file for easy editing (`*_PROMPT` constants).  
+- The grading step aggregates by subtopic and feeds that into homework and the personalized summaries.
+
+---
+
+## 🧪 Run locally (optional)
+
+```bash
+pip install -U gradio openai
+python app.py
+# then open the local URL printed by Gradio
+```
+
+---
+
+## 🩺 Troubleshooting
+
+- **Build errors on Spaces**: Ensure `requirements.txt` is present; optionally add `runtime.txt` with a supported Python.  
+- **OpenAI auth errors**: Save your key as `OPENAI_API_KEY` in Space secrets, or paste it on the Setup tab.  
+- **“Invalid JSON from the model”**: Reduce the number of generated questions, shorten the source text, or use a more robust model.  
+- **MCQ parsing**: Keep `options` a valid JSON dict with exactly `A`, `B`, `C`, `D` and set a single `correct_key`.
+
+---
+
+## 🧾 License
+
+MIT — reuse and adapt freely.
+
+---
+
+## 🙋 Acknowledgements
+
+Built using **Gradio** + **OpenAI**. Contributions welcome!
+