README.md

---
title: GAIA Agent (LangGraph + Groq)
emoji: 🕵🏻‍♂️
colorFrom: indigo
colorTo: indigo
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
hf_oauth: true
# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
hf_oauth_expiration_minutes: 480
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

---

## GAIA Agent (LangGraph + Groq)

This Space answers GAIA Level-1 questions with a LangGraph multi-node agent:

```
planner → [ingest_file] → research ⇄ tools → evidence → solver → judge ⇄ (loop) → formatter
```

- **LLM:** Groq (`langchain-groq`) — text/reasoning + Llama-4 vision + Whisper audio.
- **Search:** Tavily (`langchain-tavily`) with a Wikipedia fallback.
- **Eval loop:** an LLM-as-judge node loops wrong/ill-formatted answers back to research
  (up to `MAX_JUDGE_RETRIES`).
- **Structured handoffs:** every node-to-node transfer is a Pydantic model
  (`gaia_agent/schemas.py`), so context stays precise.

### Secrets (required)

Set these as **Space secrets** (Settings → Variables and secrets) — locally use a `.env`
(copy `.env.example`):

| Name | Purpose |
|------|---------|
| `GROQ_API_KEY` | Groq LLM access |
| `TAVILY_API_KEY` | Tavily web search |

Optional overrides: `GROQ_TEXT_MODEL`, `GROQ_VISION_MODEL`, `GROQ_WHISPER_MODEL`,
`MAX_JUDGE_RETRIES`, `RECURSION_LIMIT`. See `.env.example`.

### Local development

```bash
uv venv --python 3.11
uv pip install -e ".[dev]"
cp .env.example .env          # then fill in your keys
uv run pytest -q              # unit + graph/judge-loop tests
uv run langgraph dev          # LangGraph Studio: visualise the graph
python scripts/dry_run.py 3   # run the agent on 3 questions (no submit)
```