Update README.md

README.md

@@ -12,9 +12,131 @@ short_description: Educational Agent
 license: cc
 ---
 
-# Welcome to Streamlit!
+# 🎓 EduAgent — Educational AI Agent
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+A minimal but complete **agentic AI tutor** built with Groq + Streamlit.  
+Demonstrates: tool calling, multi-step agent loops, multi-turn memory, and clean UI.
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+---
+
+## What it does
+
+| Tool | Triggered when you ask… |
+|------|--------------------------|
+| `explain_concept` | "What is X?", "Explain Y for a beginner" |
+| `generate_quiz` | "Quiz me on Z", "Give me 3 questions about…" |
+| `solve_problem` | "Solve:", "Calculate:", "Find the derivative…" |
+| `create_study_plan` | "Make a study plan for…", "How to learn X in 4 weeks" |
+
+You can chain them: *"Explain recursion, then quiz me on it"* calls two tools in one turn.
+
+---
+
+## Groq API — why Groq?
+
+- **Free tier** at [console.groq.com](https://console.groq.com) — no credit card needed  
+- Extremely fast inference (useful for agentic loops with multiple LLM calls)  
+- Supports Llama 3.3 70B, Gemma 2, Mixtral, and more
+
+Get your key: **console.groq.com → API Keys → Create**
+
+---
+
+## 🚀 Platform setup
+
+### Streamlit Cloud (recommended)
+1. Fork / push this repo to GitHub  
+2. Go to [share.streamlit.io](https://share.streamlit.io) → New app  
+3. Set **main file** to `app.py`  
+4. Under **Secrets**, add:
+   ```toml
+   GROQ_API_KEY = "gsk_your_key_here"
+   ```
+5. Deploy ✓
+
+### Hugging Face Spaces
+1. Create a new Space → SDK: **Streamlit**  
+2. Upload `app.py` and `requirements.txt`  
+3. Go to **Settings → Repository secrets** → Add `GROQ_API_KEY`  
+4. The app reads `st.secrets["GROQ_API_KEY"]` automatically ✓
+
+### Kaggle Notebook
+```python
+# Cell 1 — install
+!pip install streamlit groq pyngrok -q
+
+# Cell 2 — set key (use Kaggle Secrets: Add-ons → Secrets)
+import os
+from kaggle_secrets import UserSecretsClient
+os.environ["GROQ_API_KEY"] = UserSecretsClient().get_secret("GROQ_API_KEY")
+
+# Cell 3 — run with tunnel
+from pyngrok import ngrok
+ngrok.set_auth_token("YOUR_NGROK_TOKEN")  # free at ngrok.com
+public_url = ngrok.connect(8501)
+print("App URL:", public_url)
+!streamlit run app.py --server.port 8501 --server.headless true
+```
+
+### Local
+```bash
+pip install -r requirements.txt
+export GROQ_API_KEY="gsk_..."   # or set in .env
+streamlit run app.py
+```
+
+---
+
+## Architecture
+
+```
+User input
+    │
+    ▼
+┌─────────────────────────────────┐
+│  System prompt + chat history   │
+│  + TOOLS schema (4 tools)       │
+└──────────────┬──────────────────┘
+               │
+               ▼
+         Groq LLM call
+               │
+       ┌───────┴────────┐
+       │ tool_calls?    │ No → final answer
+       │ Yes            │
+       ▼                │
+  execute_tool()        │
+  (second LLM call      │
+   with focused prompt) │
+       │                │
+       └──► feed result back to LLM
+            (loop up to 5 iterations)
+```
+
+---
+
+## Extending the agent
+
+**Add a real calculator tool** (no LLM needed):
+```python
+# In execute_tool(), add:
+if tool_name == "calculate":
+    import math
+    return str(eval(tool_args["expression"]))  # use safer eval in prod
+```
+
+**Add web search** (using DuckDuckGo, free):
+```python
+from duckduckgo_search import DDGS
+def web_search(query):
+    with DDGS() as ddgs:
+        return "\n".join(r["body"] for r in ddgs.text(query, max_results=3))
+```
+
+**Swap Groq for OpenAI-compatible APIs** (same code, change base_url):
+```python
+client = Groq(api_key=key)                        # Groq (default)
+# client = OpenAI(api_key=key)                    # OpenAI
+# client = OpenAI(api_key=key,                    # Together.ai / any OpenAI-compatible
+#     base_url="https://api.together.xyz/v1")
+```