README.md

---
title: Agents Course Final Assignment
emoji: "🤖"
colorFrom: indigo
colorTo: blue
sdk: static
app_file: index.html
pinned: false
tags:
  - agents-course
  - smolagents
  - ollama
---

# Hugging Face Agents Course final assignment

This repository contains a local-first solution for the [Hugging Face Agents
Course final assignment](https://huggingface.co/learn/agents-course/unit4/hands-on).
The public Space is a static, free code showcase; model inference and evaluation
run locally so that Ollama never needs to be exposed to the internet.

The system uses three deliberate stages:

1. A planning agent identifies the answer type, evidence, calculations, and
   attachment work required.
2. A research agent can search the web, read pages, and run bounded Python
   calculations.
3. A validation agent checks the evidence and emits one exact-match submission
   value.

Planning and validation use schema-constrained Ollama requests with no tool
interface, so they cannot attempt research tools. Only the research agent gets
`web_search`, `visit_webpage`, and `python_interpreter`. Validation rejects
unsupported or inconsistent evidence and can return concrete feedback for up to
two additional research rounds. An answer is cached only after validation
passes.

Evaluation answers, downloaded task files, transcripts, logs, and credentials
are stored below `.local/`, which is excluded from Git.

## Prerequisites

- Python 3.11 or newer
- [Ollama for Windows](https://ollama.com/download/windows)
- An NVIDIA GPU is helpful but not required

Pull the local multimodal model:

```powershell
ollama pull gemma4:e4b-it-qat
```

After installing or updating Ollama on Windows, quit and relaunch the Ollama
tray application and open a new PowerShell window before pulling models. This
refreshes both the running server version and the terminal's `PATH`.

`gemma4:e4b-it-qat` is shared by all three agents and also analyzes image and
audio attachments. MP3 and other audio files are decoded (not transcribed) into
16 kHz mono WAV chunks before Gemma 4 receives the audio. This keeps each chunk
within Gemma 4's 30-second audio limit. The current Ollama-compatible default
sends WAV data through the multimodal `images` field; set
`OLLAMA_AUDIO_TRANSPORT=audios` when the installed Ollama release documents and
supports that native field. `faster-whisper` remains an optional safety fallback
until a real audio task succeeds locally. Python and XLSX attachments are
extracted without an LLM.

## Installation

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -r requirements.txt
```

### GAIA attachment access

The course scoring service normally serves task attachments. If that endpoint
returns 404, the runner falls back to the official gated
[`gaia-benchmark/GAIA`](https://huggingface.co/datasets/gaia-benchmark/GAIA)
dataset. To enable the fallback:

1. Sign in on the dataset page, review its conditions, and request/accept access.
2. Authenticate this machine using the same personal account:

   ```powershell
   .\.venv\Scripts\hf.exe auth login
   .\.venv\Scripts\hf.exe auth whoami
   ```

The browser/device-code login stores its token in the Hugging Face user cache,
outside this repository. Never place the token in `.env`, command arguments,
source code, or the public Space. GAIA files are downloaded only below
`.local/`, which remains private and Git-ignored; do not republish them.

Copy the example configuration for reference, but set real values in your shell
instead of committing a `.env` file:

```powershell
$env:HF_USERNAME = "BmanClark"
$env:SPACE_ID = "BmanClark/Agents_Course_final"
```

Optional model settings are documented in [.env.example](.env.example).

## Running locally

First verify the Python dependencies, Ollama server, and required models:

```powershell
python app.py check
```

Try one random evaluation task:

```powershell
python app.py test
```

Run all remaining tasks. Each successful answer is saved immediately so the run
can be resumed safely:

```powershell
python app.py run
python app.py status
```

Re-run one task when tuning prompts:

```powershell
python app.py run --task-id TASK_ID --force
```

Review the local cache, then submit. Submission is a separate command and asks
for an explicit confirmation:

```powershell
python app.py submit
```

The scoring request contains the Hugging Face username, this public code URL,
and the cached `task_id`/answer pairs. It does not contain an HF access token.

## Security notes

- Never commit `.env`, `.local/`, answer JSON, task attachments, model files,
  tokens, or API keys.
- `hf auth login` stores its token outside this repository; the evaluation API
  does not need that token.
- The public Space is intentionally static and contains no runtime secrets.
- If a credential is ever committed, revoke it immediately before cleaning the
  Git history.