README.md

metadata

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. 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
• An NVIDIA GPU is helpful but not required

Pull the local multimodal model:

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

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

   .\.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:

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

Optional model settings are documented in .env.example.

Running locally

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

python app.py check

Try one random evaluation task:

python app.py test

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

python app.py run
python app.py status

Re-run one task when tuning prompts:

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:

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.