---
title: Eduagent
emoji: 🚀
colorFrom: red
colorTo: red
sdk: docker
app_port: 8501
tags:
- streamlit
pinned: false
short_description: Educational Agent
license: cc
---

# 🎓 EduAgent — Educational AI Agent

A minimal but complete **agentic AI tutor** built with Groq + Streamlit.  
Demonstrates: tool calling, multi-step agent loops, multi-turn memory, and clean UI.

---

## 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")
```