---
title: Bestdive Research Agent
emoji: 🔎
colorFrom: blue
colorTo: green
sdk: static
app_file: index.html
python_version: '3.12'
---

# Bestdive Research Agent

An original tool-calling research agent for the Hugging Face Agents Course final assignment.
It generates answers at runtime; it contains no benchmark answer key or task-specific answer mapping.

Tools: web search, HTTPS page/PDF reading, bounded arithmetic, and official text/Excel attachments.
Audio/video transcription is not implemented. Unsupported attachments are reported to the model.
Web content is untrusted data. No shell or arbitrary Python execution is exposed.

## Free local setup

`PUBLIC_DEMO=1` uses the official public `Qwen/Qwen3-Demo` through its documented
Gradio endpoints. Calls are sequential and depend on the demo's availability and limits.
No private inference token is transmitted to this demo. Retrieved material and questions are public course data.
Use `PUBLIC_DEMO=1 RESEARCH_MODE=1 python local_run.py --text-only --limit 13` for bounded multi-hop research.
Each question has at most 10 search/read/finish steps. To revisit selected questions, use `--retry TASK_ID_PREFIX` and an appropriate `--limit`.
Optional `RESEARCH_SOURCES=/path/to/urls.json` supplies a JSON array of supplemental public source URLs.
These are retrieved as evidence, not stored answer mappings. The final evaluation included assisted source selection for one multi-hop question.
For an attachment-free first run, add `--text-only`.

On Apple Silicon, install `requirements-local.txt` and set
`LOCAL_MODEL=mlx-community/Qwen3-4B-Instruct-2507-4bit` to run all model inference on your Mac.
This downloads roughly 2.5 GB of public model weights and uses no inference API credits.
The HF token is used only to verify the submitting account when this local model is selected.

This static Space publishes the source for course verification. Evaluation runs on the owner's computer;
it does not need a paid Space. Use `python local_run.py --limit 1` for a first test, then increase the limit.
Run `python local_run.py --submit` only after reviewing the local generated results.
Free inference credits are limited; no paid balance or automatic recharge should be enabled.
The runner stops on an inference failure so a quota error does not trigger repeated calls.

## Optional Gradio deployment

Set `HF_TOKEN` as a Space **Secret** with inference permission. Alternatively set `OPENAI_API_KEY`
as a Secret, `OPENAI_BASE_URL`, and `MODEL_ID` for an OpenAI-compatible provider.
The default HF model is `openai/gpt-oss-120b` via Groq routed through Hugging Face; availability and cost depend on the provider.
Set `OWNER_USERNAME=bestdive`. Only this authenticated account can run or submit.

Run a smoke test first. Run evaluation, inspect the generated answers, then submit to the official grader.
The Space must be public so the course can verify its code. Never upload secrets or local run artifacts.
Provider fees and limits are controlled by the provider account; the app limits each question to 8 steps.
Local proxy users with synthetic 198.18/15 DNS may set `ALLOW_LOCAL_FAKE_IP=1`;
this verifies public DNS before accepting the local proxy mapping. This option trusts the local proxy's routing.

Install: `pip install -r requirements.txt`. The optional Gradio app requires HF login locally,
or `hf_oauth: true` when deployed as a Gradio Space.

## Verified evaluation

Official grader result: **40% (8/20)**, 2026-09-09 18:31:53 UTC.
The submission included 13 generated text answers and empty entries for 7 unsupported tasks.
Official Certificate of Excellence issued to Kay Zheng on 2026-09-10.

[View official certificate](https://huggingface.co/datasets/agents-course/final-certificates/resolve/main/certificates/bestdive/2026-09-10.png)