ykumar2020/gaia-final-assignment

1---2title: Modular GAIA Level-1 Agent Source3colorFrom: indigo4colorTo: blue5sdk: static6app_file: index.html7pinned: false8---9 10> This free static Space publishes the complete inspectable agent source. Run `python app.py` locally for the Gradio evaluation UI; no paid hosted hardware is required.11 12# Modular GAIA Level-1 Agent13 14Production-oriented Hugging Face Agents Course final assignment. It preserves the15official OAuth username and submission payload while separating checkpointed dry-run16evaluation, review/reruns, and explicit submission.17 18## Space configuration19 20Set `HF_TOKEN` as a Space secret. No credentials are stored in source code.21 22Supported variables:23 24- `MODEL_ID` or `GAIA_MODEL_ID`25- `HF_PROVIDER` or `HF_INFERENCE_PROVIDER`26- `FALLBACK_MODEL_ID` (defaults to `openai/gpt-oss-20b`) and `HF_FALLBACK_PROVIDER`27- `GAIA_VISION_MODEL_ID` and `GAIA_ASR_MODEL_ID`28- `GAIA_API_URL`, `GAIA_CACHE_DIR`, `GAIA_RESULTS_PATH`, `GAIA_USE_CACHE`29- `GAIA_RETRIES`, `GAIA_BACKOFF_SECONDS`, `GAIA_REQUEST_TIMEOUT`, `GAIA_MAX_STEPS`30- `GAIA_WORKERS`, `GAIA_MODEL_REQUESTS_PER_MINUTE`, `GAIA_SEARCH_REQUESTS_PER_MINUTE`31- `STOCKFISH_PATH` when Stockfish is not on `PATH`32- `GAIA_AGENT_CODE_URL` for local submission with a public GitHub/Hugging Face code URL33- `GAIA_ALLOW_INLINE_AGENT_CODE=1` to explicitly send a local source bundle instead34- `GAIA_LOCAL_MODEL_ID` for an optional OpenAI-compatible local/Ollama fallback35- `GAIA_LOCAL_MODEL_URL` (defaults to `http://127.0.0.1:11434/v1`)36- `GAIA_PREFER_LOCAL_MODEL=1` to avoid hosted inference calls for text tasks37 38`packages.txt` installs Stockfish in the Space. Chess evaluation fails closed if an39engine is unavailable. Keep the Space public so its submitted `agent_code` is visible.40 41## Local validation and dry-run42 43```bash44python -m pip install -r requirements-dev.txt45python -m pytest -q46python run_local_eval.py47python run_local_eval.py --force --task-id TASK_ID48```49 50## Run and submit locally without paid Space hardware51 52The scoring API is public, so evaluation and explicit submission can run locally.53Authenticate and expose the CLI token to the process (PowerShell example):54 55```powershell56hf auth login57$env:HF_TOKEN = hf auth token --quiet58$env:GAIA_AGENT_CODE_URL = "https://github.com/YOUR_NAME/YOUR_PUBLIC_REPO"59python app.py60```61 62`GAIA_AGENT_CODE_URL` is recommended: it satisfies the course's inspectable-code intent63without running a hosted Space. If no public repository is available, the current API64schema also accepts Python source in `agent_code`; opt into that behavior explicitly:65 66```powershell67$env:GAIA_ALLOW_INLINE_AGENT_CODE = "1"68python app.py69```70 71Inline mode bundles only the declared implementation `.py` files. It never reads `.env`,72cached attachments, results, or credentials. In either mode, the app still requires a73successful 20-question dry run and a separate click on the submission button.74 75The dry-run CLI cannot submit. The only `/submit` POST is encapsulated by76`GaiaClient.submit_answers()` and reached from **Submit Reviewed Complete Run**.77Submission requires exactly 20 unique, successful, non-empty answers.78 79## Architecture80 81- `GaiaClient` exposes `get_questions`, `get_random_question`,82  `download_task_file`, and `submit_answers`, with typed errors and attachment metadata.83- `TaskRouter` selects deterministic file/media/logic/text specialists before inference.84- A managed `ToolCallingAgent` performs web, Wikipedia, HTML, and PDF research under a85  planning `CodeAgent`; only candidate answers leave the evidence record.86- YouTube supports captions and scene/interval frame sampling. Audio uses Whisper ASR.87- Excel arithmetic, Python stdout, Markdown algebra, text transforms, and Stockfish move88  selection are deterministic.89- `results/results.json` is keyed by task ID and records status, task type, duration,90  evidence, confidence, and errors after every task. Independent tasks run concurrently;91  shared model calls are rate-limited and serialized safely.92