README.md

---
title: Template Final Assignment
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
---

# Final Assignment Template

A Gradio-based agent evaluation runner for the [Hugging Face Agents Course](https://huggingface.co/learn/agents-course) final assignment.
The app fetches evaluation questions from a scoring API, runs them through your custom agent, submits the answers, and displays your score.

## Prerequisites

- **Python 3.10+**
- **pip** (or another package manager such as uv or conda)
- **git**
- A **Hugging Face account** (required for OAuth login when submitting answers)

## Installation

1. **Clone the repository**

```bash
git clone https://huggingface.co/spaces/dawalina/Final_Assignment_Template
cd Final_Assignment_Template
```

2. **Create and activate a virtual environment**

```bash
python3 -m venv .venv
source .venv/bin/activate        # macOS / Linux
```

3. **Install dependencies**

```bash
pip install -r requirements.txt
```

## Running Locally

Start the Gradio app:

```bash
python3 app.py
```

Gradio will print a local URL (typically `http://127.0.0.1:7860`) — open it in your browser.

> **Note:** The Hugging Face OAuth login button requires the app to be running on Hugging Face Spaces.
> When running locally the login flow will not work, so you will not be able to submit answers unless you deploy the app to a Space.

## Environment Variables

| Variable     | Required     | Description                                                                                                                 |
|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------|
| `HF_TOKEN`   | Yes          | Your Hugging Face API token. Used by the LangGraph agent to access the HF Inference API (LLM and image identification). You can also set `HUGGING_FACE_HUB_TOKEN`, or use `huggingface-cli login` locally. |
| `SPACE_ID`   | On HF Spaces | Set automatically by Hugging Face Spaces. Used to build the link to your code repository that is sent with each submission. |
| `SPACE_HOST` | On HF Spaces | Set automatically by Hugging Face Spaces. Contains the hostname used to derive your Space's public URL.                     |

When running locally, set `HF_TOKEN` in your shell before starting the app:

```bash
export HF_TOKEN="hf_your_token_here"
```

The scoring API URL is defined as `DEFAULT_API_URL` in `app.py` and defaults to `https://agents-course-unit4-scoring.hf.space`.
Change it there if you need to point to a different endpoint.

## Customizing the Agent

Open `app.py` and find the `BasicAgent` class.
Replace the default implementation with your own agent logic, tools, and packages.

Add any extra Python packages your agent needs to `requirements.txt`.

## Deploying to Hugging Face Spaces

1. **Duplicate this Space** — click *Duplicate this Space* on the Hugging Face page (or fork the repo).
2. **Add `HF_TOKEN` as a repository secret** — in your Space, open **Settings**, then **Repository secrets**, and add a secret named `HF_TOKEN` with a [user access token](https://huggingface.co/settings/tokens) that has at least **read** permission. The app does not receive a token automatically; without this secret, inference (LLM and image tool) will fail at startup.
3. **Push your changes** — commit your modified `app.py` (and any other files) and push to the Space repository.
4. **Automatic deployment** — Hugging Face reads the YAML frontmatter in this README and deploys the app using the Gradio SDK.
5. **Run the evaluation** — open your Space, log in with Hugging Face, and click *Run Evaluation & Submit All Answers*.

## Configuration Reference

See the [Hugging Face Spaces configuration reference](https://huggingface.co/docs/hub/spaces-config-reference) for details on the YAML frontmatter options used in this README.