README.md

metadata

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 — 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 → New app
3. Set main file to app.py
4. Under Secrets, add:

   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

# 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

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):

# 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):

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):

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