---
title: GAIA Final Assignment Agent
emoji: 🕵🏻‍♂️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480
---

# GAIA Final Assignment Agent

This project is a Hugging Face Agents Course final-assignment Space. It fetches the filtered GAIA questions from the course scoring API, runs a `smolagents` CodeAgent, submits exact-match answers, and creates a downloadable `gaia_submission.jsonl` file with `model_answer` and `reasoning_trace` records.

## What It Does

- Fetches tasks from `GET /questions`.
- Downloads task attachments from `GET /files/{task_id}` when present.
- Extracts text from common file types: text, CSV, TSV, Excel, PDF, and Word files.
- Uses web search, webpage visiting, Wikipedia search, and Python execution through `smolagents`.
- Removes `FINAL ANSWER:` from model output before submitting, as required by the course API.
- Submits results to `POST /submit` using your Hugging Face username from Gradio login.

## Hugging Face Space Setup

Duplicate the official template or upload this project to a public Hugging Face Space with Gradio enabled. In the Space settings, add these secrets or variables:

| Name | Required | Example | Notes |
| --- | --- | --- | --- |
| `HF_TOKEN` | Recommended | `hf_...` | Raises Hugging Face inference limits. |
| `MODEL_PROVIDER` | Optional | `hf` | Use `hf` or `litellm`. Defaults to `hf`. |
| `MODEL_ID` | Optional | `Qwen/Qwen2.5-Coder-32B-Instruct` | Any model supported by your provider. |
| `HF_INFERENCE_PROVIDER` | Optional | `together` | For routed Hugging Face inference providers. |
| `LITELLM_API_KEY` | Only for LiteLLM | `sk-...` | Also accepts `OPENAI_API_KEY`. |
| `MAX_AGENT_STEPS` | Optional | `10` | Increase for harder questions. |

Keep the Space public if you want leaderboard verification to work cleanly.

## Run Locally

Install Python 3.11 or newer, then run:

```bash
pip install -r requirements.txt
python app.py
```

Open the local Gradio URL printed in the terminal. Local runs can fetch questions and exercise the app, but the final submission flow expects Hugging Face OAuth login, which works best inside a Hugging Face Space.

## Project Files

- `app.py`: Gradio app, GAIA API client, model setup, attachment extraction, answer normalization, and submission logic.
- `requirements.txt`: Python dependencies for the Space runtime.
- `gaia_submission.jsonl`: Generated after a run and exposed as a download in the UI.

## Notes For Improving Score

- Use a strong instruction-following model through `MODEL_ID`.
- Keep answers short because the scorer uses exact match.
- Increase `MAX_AGENT_STEPS` if the agent stops too early, but expect slower runs.
- Inspect the generated JSONL when debugging repeated wrong answers.