Upload folder using huggingface_hub

CLAUDE.md

@@ -0,0 +1,194 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project purpose
+
+A Hugging Face Space (Gradio app) that runs an agent against the **GAIA benchmark Level 1**
+evaluation server, then submits the answers for scoring. Deployed as an HF Space
+(`sdk: gradio`, `app_file: app.py`, see `README.md` frontmatter).
+
+The scoring server is hardcoded as `https://agents-course-unit4-scoring.hf.space`:
+- `GET /questions` — returns the list of `{task_id, question, ...}` items.
+- `GET /files/{task_id}` — returns any file attached to that task (404 if none).
+- `POST /submit` — takes `{username, agent_code, answers:[{task_id, submitted_answer}]}`.
+
+Grading is **exact string match**. Formatting (capitalization, punctuation, units, surrounding
+quotes) matters as much as correctness — see `prompts.py`.
+
+## Run / develop
+
+There is no test suite, linter, or build step. The only runnable entrypoint is the Gradio app:
+
+```powershell
+pip install -r requirements.txt
+python app.py
+```
+
+Locally this opens a Gradio UI; the "Run Evaluation & Submit All Answers" button is disabled
+until the user logs in via `gr.LoginButton()` (HF OAuth — only works when deployed as a Space,
+or when `SPACE_ID` / `SPACE_HOST` env vars and an HF login flow are set up). For local
+debugging of agent logic, instantiate `BasicAgent` and call it directly:
+
+```python
+from app import BasicAgent
+agent = BasicAgent()
+print(agent("your question here"))
+```
+
+`BasicAgent.__init__` does a network call to `/questions` to prefetch the question→task_id
+index, so an internet connection is required even for local debugging.
+
+After a successful agent run, answers are cached in `.cache/answers.json`. On re-runs the
+loop in `run_and_submit_all` skips any `task_id` already in the cache, so you can iterate
+on a single broken question without re-paying for the rest. Delete the file (or specific
+entries) to force re-evaluation. See "Answer cache" section below.
+
+## Environment variables
+
+| Variable | Required for | Behaviour without it |
+|---|---|---|
+| `HF_TOKEN` | All HF Inference calls — main agent loop (Qwen2.5-72B), decomposer, image VLM (Qwen2.5-VL-7B), audio Whisper (large-v3). | Decomposer returns `None` (proceed without plan); image/audio handlers return error strings; main loop fails outright. In a deployed Space, register as a Space secret. Locally, `huggingface-cli login` writes a token that `InferenceClient()` picks up. |
+| `TAVILY_API_KEY` | Tavily search backend (optional; after SearXNG in `web_search`). | `_search_tavily` short-circuits to `None` and falls through to Brave / DDG. |
+| `BRAVE_API_KEY` | Brave search backend (optional; after Tavily when keys set). | Same fall-through as Tavily. |
+| `SPACE_ID`, `SPACE_HOST` | Set automatically when running as an HF Space; `SPACE_ID` builds the `agent_code` repo URL for `/submit`. | Locally `SPACE_ID` is unset — `run_and_submit_all` sends a Hub Spaces docs URL instead of `/spaces/None/...`. |
+
+## Architecture
+
+### Pre-decomposition step (`decomposer.py`)
+
+Before each `agent.run`, `BasicAgent.__call__` makes one LLM call (same Qwen2.5-72B
+model, via `huggingface_hub.InferenceClient`) to classify the question:
+
+- Returns `SINGLE-HOP` → no plan injected, original question runs as-is.
+- Returns a numbered plan → injected into the user message above the original question
+  with a "guidance — deviate as tool results show" framing.
+
+Reason: GAIA Level 1 has many multi-hop questions ("X of the Y of Z"). Without a plan
+the CodeAgent burns 1–2 of its 12 steps just orienting. The decomposition prompt and the
+`SINGLE-HOP` short-circuit are in `prompts.py:DECOMPOSITION_PROMPT`. Before classification,
+`decomposer.py` normalizes the model output (strip markdown fences, drop prose before the first
+numbered step). The function is best-effort: any failure (HF rate limit, malformed output)
+returns None and the agent proceeds with the original question.
+
+### The agent loop (smolagents.CodeAgent)
+
+`BasicAgent` (in `app.py`) is a thin wrapper around `smolagents.CodeAgent`. CodeAgent is a
+ReAct variant where the LLM **writes Python code** each step that calls the registered `@tool`
+functions; that code runs in a sandbox, results go back to the LLM, and the loop ends when
+the LLM calls `final_answer(...)`. Key knobs:
+
+- Model: `Qwen/Qwen2.5-72B-Instruct` via `InferenceClientModel`. The comments note an earlier
+  32B coder model was abandoned because it leaked markdown fences (`\`\`\``, `</code]`) that
+  broke smolagents' code parser. Do not switch to a coder-tuned model without re-checking
+  this.
+- `max_steps=12`. 8 was too low — search retries used up the budget. The system prompt also
+  pushes the model to commit by step 6–8 so it doesn't hit the limit (smolagents falls back
+  to returning the model's last verbose thought, which scores zero on exact-match).
+- `additional_authorized_imports`: pandas/openpyxl/json/re/math/statistics/itertools — these
+  are imports the sandbox is allowed to use, mainly so spreadsheet questions work.
+- The CodeAgent's default system prompt is **post-pended** with `GAIA_ANSWER_GUIDELINES` from
+  `prompts.py` by mutating `self.agent.prompt_templates["system_prompt"]`. Don't replace it;
+  the smolagents default contains the code-generation contract.
+
+Output post-processing in `__call__` (in this order):
+1. Strip a leading `FINAL ANSWER:` / `FINAL ANSWER -` prefix.
+2. Strip a single pair of surrounding quotes.
+3. `final_format_pass(question, answer)` from `formatter.py` — optional extra LLM pass to
+   normalize formatting for exact-match grading; on failure returns the draft unchanged.
+4. `coerce_answer(question, answer)` from `formatter.py` — applies *deterministic* format
+   coercion based on hints in the question (yes/no questions → `Yes`/`No`, "How many"
+   questions → first numeric token only, currency-pattern answers → strip `$,€,£,¥` and
+   commas). Coercion is conservative: if the answer doesn't match the expected pattern
+   it is left untouched, because over-coercing destroys correct answers more often than
+   it salvages wrong ones.
+
+These are tuned to common LLM mistakes against exact-match scoring; tighten/loosen carefully.
+
+### Tools (`tools/` package)
+
+Six tools are registered with the agent, plus three helpers used only by `BasicAgent`:
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `web_search(query)` | `@tool` | Backend priority: SearXNG (public instances, no key) → Tavily (`TAVILY_API_KEY`) → Brave (`BRAVE_API_KEY`) → DuckDuckGo. Tavily/Brave are skipped silently if their key is unset. DDG tries `ddgs` first then legacy `duckduckgo_search` (key names differ: `href`/`url`, `body`/`snippet`). |
+| `visit_webpage(url)` | `@tool` | Generic page fetch → BeautifulSoup → markdownify, truncated to ~12k chars. Sends a non-empty User-Agent because some sites block blank UAs. |
+| `wikipedia_search(query)` | `@tool` | Two-step: search API for top title, then `action=parse` for full HTML body. Tables are converted to `[TABLE]...[/TABLE]` blocks with `\|`-separated cells so the LLM can read rosters/winner lists/dates. The REST `summary` endpoint was insufficient — it only returns the lead paragraph. |
+| `youtube_info(url)` | `@tool` | YouTube videos. Metadata via oEmbed (title, channel — no API key needed). Transcript via `youtube-transcript-api` (English first → translate any translatable caption → first available language). Truncates transcript to ~14k chars. Accepts watch/youtu.be/embed/shorts URLs and bare 11-char IDs. If the video has no captions, only metadata is returned and the agent is instructed (in `GAIA_ANSWER_GUIDELINES` rule 5b) to fall back to web/wikipedia search. |
+| `exec_python_code(code)` | `@tool` | Subprocess 실행으로 첨부·인용 파이썬 코드의 stdout/stderr를 캡처해 반환(GAIA 코드 출력 질문용). |
+| `get_attached_file()` | `@tool` | **Takes no arguments** — see "task_id plumbing" below. Type-dispatches: UTF-8 text, `.xlsx` → sheet-by-sheet CSV, PDF → page-by-page text via `pypdf`, image → Qwen2.5-VL-7B analysis (with the current question as VLM prompt context), audio → Whisper-large-v3 transcription, else metadata. |
+| `prefetch_question_index()` | helper | One-shot `/questions` GET, builds `{question_text: task_id}` dict. Duplicate question strings log a warning and keep the **last** task_id. Returns `{}` on failure (degraded mode: no attachments). |
+| `set_question_index(idx)` | helper | Stores the prefetched dict in `tools.attachments._QUESTION_INDEX`. |
+| `set_current_task(question)` | helper | Sets both `_CURRENT_TASK["id"]` and `_CURRENT_TASK["question"]`. The stored question is read by the image handler to scope VLM analysis to the current question (generic captions miss details). |
+
+### task_id plumbing (important architectural quirk)
+
+`BasicAgent.__call__(question: str) -> str` has a fixed signature dictated by
+`run_and_submit_all` in `app.py` (`agent(question_text)`). The agent therefore can't be
+passed the `task_id` directly, but `get_attached_file` needs it to hit `/files/{task_id}`.
+
+The workaround uses **module-level mutable state** in `tools/attachments.py`:
+
+1. `BasicAgent.__init__` calls `prefetch_question_index()` once → builds `{question: task_id}`,
+   stores it via `set_question_index()` into `_QUESTION_INDEX`.
+2. Each call to `BasicAgent.__call__` runs `set_current_task(question)`, which looks up the
+   task_id and writes both `_CURRENT_TASK["id"]` and `_CURRENT_TASK["question"]`. The
+   stored question is read by the image handler and injected into the VLM prompt so the
+   model focuses on details relevant to the actual question.
+3. When the LLM calls `get_attached_file()` (no args), the tool reads `_CURRENT_TASK["id"]`
+   from module globals and fetches `/files/{task_id}`, then dispatches by Content-Type +
+   filename extension (Content-Disposition).
+
+If you add tools that need other per-task context, follow this same prefetch + module-global
+pattern rather than threading arguments through (the smolagents tool signature constraint
+will fight you).
+
+### Answer cache (`answer_cache.py`)
+
+`run_and_submit_all` loads `.cache/answers.json` once at start and consults it before
+calling the agent for each task. On a hit, the cached answer is reused without any LLM
+call. On a fresh agent call, `save_answer(task_id, question, answer)` is invoked
+immediately after — written atomically (temp file + `os.replace`) so a crash mid-write
+won't corrupt the cache.
+
+`AGENT_ERROR:`-prefixed answers are *never* cached: those represent recoverable failures
+(timeouts, rate limits) that should be retried on the next run, not memoized.
+
+To force a re-run from scratch, delete `.cache/answers.json` (or call `clear_cache()`).
+The cache key is `task_id`, so changing the question text alone won't invalidate an entry
+— if the scoring server changes a question while keeping the same task_id, you must
+clear manually.
+
+### Code style
+
+All inline comments and docstrings (other than the `@tool` LLM-facing docstrings) are in
+**Korean**. The `@tool` docstrings are deliberately in English because they are sent to the
+LLM as part of the tool catalog. Keep this split when editing — Korean for human-facing
+context, English for anything the LLM reads.
+
+## When editing
+
+- Touching the answer-formatting rules: edit `GAIA_ANSWER_GUIDELINES` in `prompts.py`. These
+  are appended to smolagents' system prompt at runtime; reasons for each rule (especially
+  the "no markdown fences", "commit by step 6-8", and "no fabrication" rules) are documented
+  inline.
+- Tweaking multi-hop decomposition: edit `DECOMPOSITION_PROMPT` in `prompts.py` for the
+  classifier behaviour, and `decomposer.py` if you want to change the model id or the
+  `SINGLE-HOP` short-circuit. The marker string is consumed by a regex in `decomposer.py`
+  (`SINGLE[\s\-]*HOP`); changing the marker requires updating both.
+- Tightening / loosening deterministic answer coercion: edit `formatter.py:coerce_answer`.
+  Coercions are intentionally narrow (yes/no, "how many", currency-pattern); broader
+  rewrites historically destroyed more correct answers than they salvaged.
+- Touching `__call__`'s output post-processing: any change can flip many answers between
+  pass/fail under exact-match. The current strip rules are conservative — only known LLM
+  artifacts (FINAL ANSWER prefix, single pair of surrounding quotes).
+- Adding a new tool: register it in `tools/__init__.py`, then add it to the `tools=[...]`
+  list in `BasicAgent.__init__`. Keep its `@tool` docstring in English and write the
+  argument descriptions clearly — they become the LLM's only spec for the tool.
+- The `additional_authorized_imports` list gates sandbox imports. If a tool returns CSV/JSON
+  that the agent will need to parse with a new library, add it here.
+- Image and audio handlers in `get_attached_file` call HF Inference API (Qwen2.5-VL-7B,
+  Whisper-large-v3) and require `HF_TOKEN` to be set. In a deployed Space, register it as
+  a Space secret. Locally, `huggingface-cli login` works. If `HF_TOKEN` is missing or rate
+  limits hit, the handlers return a readable error string and the agent prompt instructs
+  it to fall back to web/wikipedia search.

answer_cache.py

@@ -0,0 +1,120 @@
+"""Per-task 답변 캐시.
+
+채점 서버에 답을 한 번 전송하더라도 점수 확인·디버깅을 위해 다시 돌려야 할 때가
+있다. 한 문제마다 LLM 호출이 비싸므로 task_id 단위로 답을 디스크에 보관해
+재실행 시 캐시된 문제는 스킵한다. 한 문제에서 죽으면 전체가 멈추던 부수 문제도
+함께 완화 — 다음 실행 때 그 문제만 다시 풀면 된다.
+
+저장 위치: .cache/answers.json (이미 디렉터리 존재).
+형식: {task_id: {"question": str, "answer": str}}
+원자적 쓰기: 임시 파일 → os.replace 로 동시쓰기/크래시 안전.
+
+캐시 무효화는 파일 직접 삭제(rm .cache/answers.json) 또는 clear_cache() 사용.
+"""
+import json
+import os
+import tempfile
+from pathlib import Path
+
+_CACHE_PATH = Path(".cache") / "answers.json"
+
+
+def load_cache() -> dict:
+    """디스크에서 캐시 로드. 파일 없거나 깨지면 빈 dict."""
+    if not _CACHE_PATH.exists():
+        return {}
+    try:
+        return json.loads(_CACHE_PATH.read_text(encoding="utf-8"))
+    except Exception as e:
+        print(f"Warning: cache load failed ({e}); starting empty.")
+        return {}
+
+
+def save_answer(task_id: str, question: str, answer: str) -> None:
+    """task_id 답을 캐시에 추가하고 원자적으로 저장.
+    AGENT_ERROR 결과는 캐시 안 함 — 재실행 시 다시 시도해야 하는 항목이라."""
+    if not task_id or is_retryable_answer(answer):
+        return
+    cache = load_cache()
+    cache[task_id] = {"question": question, "answer": answer}
+    _CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    # 같은 디렉터리에 임시 파일 → os.replace 로 OS-level atomic rename.
+    fd, tmp = tempfile.mkstemp(prefix="answers.", suffix=".tmp", dir=str(_CACHE_PATH.parent))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(cache, f, ensure_ascii=False, indent=2)
+        os.replace(tmp, _CACHE_PATH)
+    except Exception:
+        # 실패 시 임시 파일 정리 후 재발생.
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def get_cached_answer(task_id: str, cache: dict | None = None) -> str | None:
+    """캐시에서 task_id의 답을 꺼내거나 None.
+    cache 인자를 주면 매번 디스크 재로딩 안 함(루프에서 유용)."""
+    if cache is None:
+        cache = load_cache()
+    entry = cache.get(task_id)
+    if entry and isinstance(entry, dict):
+        return entry.get("answer")
+    return None
+
+
+def is_retryable_answer(answer: str | None) -> bool:
+    """다음 실행에서 다시 시도해야 할 답변인지 판별."""
+    if answer is None:
+        return True
+    a = str(answer).strip()
+    if not a:
+        return True
+    upper = a.upper()
+    return (
+        upper == "UNKNOWN"
+        or upper == "UNK"
+        or upper.startswith("AGENT_ERROR:")
+        or upper.startswith("AGENT ERROR:")
+        or "CANNOT ANSWER" in upper
+        or "NO FINAL ANSWER" in upper
+    )
+
+
+def clear_cache() -> None:
+    """수동 호출용. 자동 호출 안 함."""
+    if _CACHE_PATH.exists():
+        _CACHE_PATH.unlink()
+
+
+def invalidate_tasks(task_ids) -> int:
+    """주어진 task_id 목록만 캐시에서 제거하고 원자적으로 저장.
+
+    개선 단계마다 "오답이었던 task_id만 재시도" 하기 위한 헬퍼.
+    정답으로 캐시된 항목은 보존해 토큰을 아끼면서, 변경 효과만 깨끗이 측정.
+
+    Returns:
+        실제로 제거된 항목 수.
+    """
+    cache = load_cache()
+    removed = 0
+    for tid in task_ids:
+        if tid in cache:
+            del cache[tid]
+            removed += 1
+    if removed == 0:
+        return 0
+    _CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix="answers.", suffix=".tmp", dir=str(_CACHE_PATH.parent))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(cache, f, ensure_ascii=False, indent=2)
+        os.replace(tmp, _CACHE_PATH)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+    return removed

app.py

@@ -1,34 +1,175 @@
 import os
+import re
 import gradio as gr
 import requests
-import inspect
 import pandas as pd
 
+# smolagents: HF가 만든 에이전트 프레임워크. CodeAgent는 LLM이 매 스텝마다 파이썬
+# 코드를 생성·실행해 도구를 호출하는 ReAct 변형이다.
+from smolagents import CodeAgent, InferenceClientModel
+
+# 도구는 tools/ 패키지에 분리되어 있다. 각 파일이 하나의 @tool 함수를 담당.
+from tools import (
+    web_search,
+    visit_webpage,
+    wikipedia_search,
+    youtube_info,
+    exec_python_code,
+    get_attached_file,
+    prefetch_question_index,
+    set_question_index,
+    set_current_task,
+)
+# GAIA exact-match 채점에 맞춘 시스템 프롬프트 가이드라인.
+from prompts import GAIA_ANSWER_GUIDELINES
+# 멀티홉 질문 사전 분해(query decomposition).
+from decomposer import decompose_question
+# 답변 캐싱(재실행 시 처리한 문제 스킵, 한 문제 실패의 cascade 방지).
+from answer_cache import load_cache, save_answer, is_retryable_answer
+# 답변 포맷 후처리(exact-match 채점 보정).
+from formatter import coerce_answer, final_format_pass
+
 # (Keep Constants as is)
 # --- Constants ---
+# 채점 서버 베이스 URL. /questions 로 문제를 받고, /submit 으로 답을 제출한다.
 DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
 
+
 # --- Basic Agent Definition ---
-# ----- THIS IS WERE YOU CAN BUILD WHAT YOU WANT ------
+# ----- THIS IS WHERE YOU CAN BUILD WHAT YOU WANT ------
 class BasicAgent:
+    """GAIA Level 1 문제를 푸는 에이전트.
+
+    실제 추론은 smolagents.CodeAgent에 위임한다. CodeAgent는 매 스텝마다
+    LLM(InferenceClientModel)에 컨텍스트를 보내 파이썬 코드를 받아오고,
+    그 코드를 안전한 샌드박스에서 실행해 도구 결과를 다시 LLM에게 전달한다.
+    최종적으로 LLM이 final_answer(...)를 호출하면 그 값이 self.agent.run의 반환값이 된다.
+    """
+
     def __init__(self):
         print("BasicAgent initialized.")
+        # 모델: Qwen2.5-72B-Instruct (오픈웨이트, 32k ctx).
+        # provider="hf-inference"로 명시 — HF 네이티브 serverless 라인이라 무료 풀.
+        # 시도했던 다른 모델들의 결과:
+        # - DeepSeek-V3 + provider="auto" → Together로 라우팅 → 503/402 (크레딧 소진)
+        # - Llama-3.3-70B-Instruct + provider="hf-inference" → 400 Bad request
+        #   (hf-inference에 호스팅 안 됨, paid provider 전용)
+        # Qwen2.5-72B는 hf-inference에서 호스팅이 확인된 모델 중 추론력 가장 강함.
+        # 큐 대기 가끔 있어도 키 정책 + 무료 제약에서는 최선의 선택.
+        # 코더 모델로 바꾸지 말 것: 매 스텝 마크다운 잔재(```, </code])를 흘려
+        # smolagents 코드 파서가 깨진다(이전 32B 코더 시도에서 확인됨).
+        self.model = InferenceClientModel(
+            model_id="Qwen/Qwen2.5-72B-Instruct",
+            provider="hf-inference",
+            max_tokens=2048,  # 한 스텝당 LLM 응답 토큰 한도
+        )
+
+        # /questions 한 번 prefetch 해서 {질문본문: task_id} 인덱스 빌드.
+        # tools.attachments 모듈 전역에 등록 → __call__ 진입 시 set_current_task()가 사용.
+        idx = prefetch_question_index()
+        set_question_index(idx)
+        print(f"Prefetched question index: {len(idx)} entries")
+
+        # 도구 6종: web_search, visit_webpage, wikipedia_search, youtube_info,
+        # exec_python_code, get_attached_file.
+        # max_steps=12: 8스텝에선 검색 실패로 다른 쿼리를 시도하다 한도에 걸리는 일이 잦았다.
+        # additional_authorized_imports: 샌드박스에서 표 처리/계산이 필요할 때 import 허용.
+        self.agent = CodeAgent(
+            tools=[
+                web_search,
+                visit_webpage,
+                wikipedia_search,
+                youtube_info,
+                exec_python_code,
+                get_attached_file,
+            ],
+            model=self.model,
+            max_steps=12,
+            additional_authorized_imports=[
+                "pandas", "openpyxl", "json", "re", "math", "statistics", "itertools",
+                "datetime", "collections", "urllib.parse",
+            ],
+        )
+        # CodeAgent의 기본 시스템 프롬프트 뒤에 GAIA용 채점 규칙을 덧붙인다.
+        try:
+            current_sp = self.agent.prompt_templates.get("system_prompt", "")
+            self.agent.prompt_templates["system_prompt"] = (
+                current_sp + "\n\n" + GAIA_ANSWER_GUIDELINES
+            )
+        except Exception as e:
+            print(f"Warning: could not patch system prompt: {e}")
+
     def __call__(self, question: str) -> str:
+        # 시그니처는 (self, question: str) -> str로 고정. run_and_submit_all이
+        # `agent(question_text)` 형태로 호출하므로 인자 추가 금지.
         print(f"Agent received question (first 50 chars): {question[:50]}...")
-        fixed_answer = "This is a default answer."
-        print(f"Agent returning fixed answer: {fixed_answer}")
-        return fixed_answer
+        # 현재 문제의 task_id를 tools.attachments 전역에 세팅 → get_attached_file() 가
+        # 인자 없이 동작. 매칭 실패 시 None(첨부 없는 문제처럼 처리됨).
+        tid = set_current_task(question)
+        if tid:
+            print(f"  → matched task_id: {tid}")
+        else:
+            print("  → no matched task_id (question not in cache)")
 
-def run_and_submit_all( profile: gr.OAuthProfile | None):
+        # 멀티홉 질문은 1콜로 plan을 뽑아 prompt에 prepend 한다. 본 루프(12스텝)가
+        # 첫 스텝부터 곧장 도구 호출로 들어가도록 유도. 단일 lookup이면 None이
+        # 반환되어 원본 질문 그대로 진행. 분해 실패도 None → degrade 안전.
+        plan = decompose_question(question)
+        if plan:
+            print(f"  → decomposition plan:\n{plan}")
+            prompt_question = (
+                f"{question}\n\n"
+                f"--- Suggested decomposition plan (guidance — deviate as tool results show) ---\n"
+                f"{plan}\n"
+                f"--- end plan ---\n"
+                f"The final answer must address the ORIGINAL question above, not the plan."
+            )
+        else:
+            prompt_question = question
+
+        try:
+            raw = self.agent.run(prompt_question)
+            answer = str(raw).strip()
+            # 1) "FINAL ANSWER:" / "FINAL ANSWER -" 같은 prefix 제거(case-insensitive).
+            answer = re.sub(
+                r"^\s*FINAL\s*ANSWER\s*[:\-]?\s*",
+                "",
+                answer,
+                flags=re.IGNORECASE,
+            ).strip()
+            # 2) 양끝을 둘러싼 따옴표 제거. (LLM이 종종 "Answer" 형태로 따옴표를 붙인다.)
+            if len(answer) >= 2 and (
+                (answer[0] == '"' and answer[-1] == '"')
+                or (answer[0] == "'" and answer[-1] == "'")
+            ):
+                answer = answer[1:-1].strip()
+            # 3) Final-answer formatter pass — 별도 LLM 호출로 GAIA 포맷 강제.
+            #    내용 맞고 형식 위반인 B 카테고리 회복용. 호출 실패 시 raw 유지(graceful degrade).
+            answer = final_format_pass(question, answer)
+            # 4) 결정적 regex 후처리(yes/no, 숫자, 통화). final_format_pass가 놓친 패턴 안전망.
+            answer = coerce_answer(question, answer)
+            print(f"Agent returning answer: {answer}")
+            return answer
+        except Exception as e:
+            # 한 문제에서 raise되면 전체 채점이 멈추므로 여기서 흡수하고
+            # AGENT_ERROR 문자열을 답으로 제출한다(어차피 오답 처리됨).
+            # 제출 문자열은 타입만 노출(상세는 로그에만) — 예외 메시지 유출 완화.
+            import traceback
+            err_type = type(e).__name__
+            print(f"Agent error ({err_type}): {e}")
+            print(traceback.format_exc()[-600:])
+            return f"AGENT_ERROR: {err_type}"
+
+def run_and_submit_all(profile: gr.OAuthProfile | None):
     """
     Fetches all questions, runs the BasicAgent on them, submits all answers,
     and displays the results.
     """
     # --- Determine HF Space Runtime URL and Repo URL ---
-    space_id = os.getenv("SPACE_ID") # Get the SPACE_ID for sending link to the code
+    space_id = os.getenv("SPACE_ID")  # Space 배포 시 자동 설정; 로컬에서는 보통 없음
 
     if profile:
-        username= f"{profile.username}"
+        username = f"{profile.username}"
         print(f"User logged in: {username}")
     else:
         print("User not logged in.")
@@ -44,8 +185,12 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
     except Exception as e:
         print(f"Error instantiating agent: {e}")
         return f"Error initializing agent: {e}", None
-    # In the case of an app running as a hugging Face space, this link points toward your codebase ( usefull for others so please keep it public)
-    agent_code = f"https://huggingface.co/spaces/{space_id}/tree/main"
+    # SPACE_ID 없으면 /spaces/None/... 로 깨지지 않도록 고정 문서 URL 사용.
+    if space_id:
+        agent_code = f"https://huggingface.co/spaces/{space_id}/tree/main"
+    else:
+        agent_code = "https://huggingface.co/docs/hub/spaces"
+        print("SPACE_ID unset — using docs URL for agent_code (set when deploying to HF Spaces).")
     print(agent_code)
 
     # 2. Fetch Questions
@@ -55,16 +200,16 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
         response.raise_for_status()
         questions_data = response.json()
         if not questions_data:
-             print("Fetched questions list is empty.")
-             return "Fetched questions list is empty or invalid format.", None
+            print("Fetched questions list is empty.")
+            return "Fetched questions list is empty or invalid format.", None
         print(f"Fetched {len(questions_data)} questions.")
     except requests.exceptions.RequestException as e:
         print(f"Error fetching questions: {e}")
         return f"Error fetching questions: {e}", None
     except requests.exceptions.JSONDecodeError as e:
-         print(f"Error decoding JSON response from questions endpoint: {e}")
-         print(f"Response text: {response.text[:500]}")
-         return f"Error decoding server response for questions: {e}", None
+        print(f"Error decoding JSON response from questions endpoint: {e}")
+        print(f"Response text: {response.text[:500]}")
+        return f"Error decoding server response for questions: {e}", None
     except Exception as e:
         print(f"An unexpected error occurred fetching questions: {e}")
         return f"An unexpected error occurred fetching questions: {e}", None
@@ -72,26 +217,56 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
     # 3. Run your Agent
     results_log = []
     answers_payload = []
-    print(f"Running agent on {len(questions_data)} questions...")
+    # 캐시는 .cache/answers.json. 한 번 답을 받은 task_id는 재실행 시 LLM 호출
+    # 없이 그대로 재사용 — 전체 채점 재시도 비용 절감 + 한 문제 실패 cascade 방지.
+    cache = load_cache()
+    print(f"Running agent on {len(questions_data)} questions... (cache: {len(cache)} entries)")
     for item in questions_data:
         task_id = item.get("task_id")
         question_text = item.get("question")
         if not task_id or question_text is None:
             print(f"Skipping item with missing task_id or question: {item}")
             continue
+
+        cached = cache.get(task_id)
+        if cached and isinstance(cached, dict) and "answer" in cached:
+            submitted_answer = cached["answer"]
+            if is_retryable_answer(submitted_answer):
+                print(
+                    f"  [cache stale] task_id={task_id}: retrying "
+                    f"instead of reusing {submitted_answer!r}"
+                )
+            else:
+                print(f"  [cache hit] task_id={task_id}: {submitted_answer[:80]}")
+                answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
+                results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": submitted_answer})
+                continue
         try:
             submitted_answer = agent(question_text)
+            # AGENT_ERROR 결과는 save_answer 내부에서 캐시 안 함(다음 실행 때 재시도).
+            save_answer(task_id, question_text, submitted_answer)
+            if is_retryable_answer(submitted_answer):
+                print(f"  [skip retryable answer] task_id={task_id}: {submitted_answer!r}")
+                results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": submitted_answer})
+                continue
             answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
             results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": submitted_answer})
         except Exception as e:
-             print(f"Error running agent on task {task_id}: {e}")
-             results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": f"AGENT ERROR: {e}"})
+            err_type = type(e).__name__
+            print(f"Error running agent on task {task_id} ({err_type}): {e}")
+            results_log.append(
+                {
+                    "Task ID": task_id,
+                    "Question": question_text,
+                    "Submitted Answer": f"AGENT_ERROR: {err_type}",
+                }
+            )
 
     if not answers_payload:
         print("Agent did not produce any answers to submit.")
         return "Agent did not produce any answers to submit.", pd.DataFrame(results_log)
 
-    # 4. Prepare Submission 
+    # 4. Prepare Submission
     submission_data = {"username": username.strip(), "agent_code": agent_code, "answers": answers_payload}
     status_update = f"Agent finished. Submitting {len(answers_payload)} answers for user '{username}'..."
     print(status_update)
@@ -193,4 +368,4 @@ if __name__ == "__main__":
     print("-"*(60 + len(" App Starting ")) + "\n")
 
     print("Launching Gradio Interface for Basic Agent Evaluation...")
-    demo.launch(debug=True, share=False)
+    demo.launch(debug=True, share=False)

decomposer.py

@@ -0,0 +1,79 @@
+"""멀티홉 질문 분해 (query decomposition).
+
+GAIA 문제는 종종 "X가 태어난 도시의 인구" 처럼 여러 단계 lookup이 필요하다.
+원본 질문을 그대로 CodeAgent에 던지면 첫 1-2 스텝을 "어떻게 풀지" 고민하는 데
+쓰는데, 사전에 1콜로 plan을 뽑아 prompt에 박아주면 본 루프가 곧장 실행
+단계(검색/방문/위키)로 넘어간다.
+
+비용/이득:
+- 단일 lookup 문제는 SINGLE-HOP으로 분기 → 토큰 ~500 낭비(스텝 절약은 0).
+- 멀티홉 문제에서는 1-2 스텝 절약(스텝당 ~1k+ 토큰) + 검색 쿼리 품질 향상.
+
+이 함수는 best-effort 보조 단계라 실패하면 항상 None을 반환해 호출자가
+원본 질문 그대로 진행하도록 한다(degrade 안전).
+"""
+import re
+from huggingface_hub import InferenceClient
+
+from prompts import DECOMPOSITION_PROMPT
+
+
+def _normalize_decomposition_text(raw: str) -> str:
+    """분해 모델 출력에서 마크다운 펜스·머리말을 걷어내 번호 플랜 본문만 남긴다.
+
+    SINGLE-HOP 한 줄 응답은 그대로 두고, 1. 2. … 번호 플랜은 첫 번호 줄부터만
+    잘라 넣어 CodeAgent 프롬프트 노이즈를 줄인다.
+    """
+    t = (raw or "").strip()
+    if not t:
+        return t
+    if t.startswith("```"):
+        t = re.sub(r"^```[a-zA-Z]*\n?", "", t)
+        if "```" in t:
+            t = t.split("```", 1)[0]
+        t = t.strip()
+    if re.match(r"^\s*SINGLE[\s\-]*HOP\s*$", t, re.IGNORECASE):
+        return t
+    m = re.search(r"(?m)^\s*\d+[\.\)]\s+", t)
+    if m:
+        return t[m.start() :].strip()
+    return t
+
+
+def decompose_question(
+    question: str,
+    model_id: str = "Qwen/Qwen2.5-72B-Instruct",
+) -> str | None:
+    """질문을 분석해 멀티홉이면 plan 텍스트, 단일 lookup이면 None을 반환.
+
+    Args:
+        question: GAIA 질문 본문.
+        model_id: 분해에 쓸 LLM. 기본값은 BasicAgent의 본 모델과 동일하게 두어
+            품질을 일치시킴(작은 모델은 SINGLE-HOP 형식을 자주 어김).
+
+    Returns:
+        멀티홉 plan(numbered list 텍스트) 또는 None(단일 lookup/실패).
+    """
+    try:
+        # provider="hf-inference": HF Inference Providers 중 가용한 곳으로 라우팅.
+        client = InferenceClient(provider="hf-inference")  # HF_TOKEN 환경변수 사용
+        resp = client.chat_completion(
+            model=model_id,
+            messages=[
+                {"role": "system", "content": DECOMPOSITION_PROMPT},
+                {"role": "user", "content": question},
+            ],
+            max_tokens=512,  # plan은 보통 5단계 미만 → 넉넉
+        )
+        text = _normalize_decomposition_text(resp.choices[0].message.content or "")
+
+        # "SINGLE-HOP" / "SINGLE HOP" / "SINGLEHOP" 등 변형 모두 처리.
+        if re.match(r"^\s*SINGLE[\s\-]*HOP", text, re.IGNORECASE):
+            return None
+        if not text:
+            return None
+        return text
+    except Exception as e:
+        # 분해 실패는 채점을 막지 않는다. 원본 질문으로 그대로 진행.
+        print(f"Decomposition failed (proceeding without plan): {e}")
+        return None

formatter.py

@@ -0,0 +1,154 @@
+"""GAIA exact-match 채점에 맞춘 답변 포맷 후처리.
+
+두 단계로 구성:
+1. final_format_pass(question, raw): LLM 한 번 더 호출해서 GAIA 포맷으로만 변환.
+   B 카테고리(내용 맞고 형식 위반) 회복용. 짧은 reformat 전용 시스템 프롬프트.
+2. coerce_answer(question, ans): 결정적 regex 후처리. yes/no, 숫자, 통화 등
+   확실한 패턴만 강제. 매칭 실패 시 원본 유지(잘못 강제하면 더 망침).
+
+순서: __call__에서 raw → strip prefixes/quotes → final_format_pass → coerce_answer.
+"""
+import re
+import unicodedata
+
+
+# yes/no 질문 시작 후보 키워드. 영어 의문문이 이 보조동사로 시작하고 ?로 끝나면
+# 대개 yes/no 답을 기대하는 형태.
+_YES_NO_STARTS = (
+    "is ", "are ", "was ", "were ", "do ", "does ", "did ",
+    "has ", "have ", "had ", "can ", "could ", "should ",
+    "will ", "would ", "may ", "might ",
+)
+
+
+def _looks_yes_no(question: str) -> bool:
+    q = question.strip().lower()
+    if "yes or no" in q or "yes/no" in q:
+        return True
+    if not q.endswith("?"):
+        return False
+    return any(q.startswith(s) for s in _YES_NO_STARTS)
+
+
+def _looks_numeric(question: str) -> bool:
+    q = question.lower()
+    return (
+        "how many" in q
+        or "what number" in q
+        or "what is the number of" in q
+        # "how much" 는 단위 포함 답을 원할 수도 있어 제외(예: "how much money" → "$1.5M").
+    )
+
+
+def coerce_answer(question: str, answer: str) -> str:
+    """질문 형식 힌트에 맞춰 LLM 답을 보정. 힌트가 없거나 매칭 실패 시 원본 반환."""
+    a = answer.strip()
+    if not a:
+        return a
+
+    # 1) Yes/No 질문 — 첫 단어로 결정.
+    if _looks_yes_no(question):
+        first = a.split(None, 1)[0].rstrip(",.").lower() if a.split() else ""
+        if first == "yes":
+            return "Yes"
+        if first == "no":
+            return "No"
+        # 매칭 실패 시 원본 유지(잘못 강제하면 더 망침).
+        return a
+
+    # 2) 순수 숫자 질문 — 답 안의 첫 정수/실수만 추출.
+    if _looks_numeric(question):
+        m = re.search(r"-?\d+(?:\.\d+)?", a.replace(",", ""))
+        if m:
+            num = m.group(0)
+            try:
+                f = float(num)
+                if f.is_integer():
+                    return str(int(f))
+                return num
+            except ValueError:
+                pass
+        return a
+
+    # 3) 답이 통화기호+숫자 패턴이면 기호/콤마/공백만 제거.
+    # "$1,234" → "1234", "1,234.5" → "1234.5"
+    if re.fullmatch(r"\s*[\$€£¥]?\s*-?[\d,]+(?:\.\d+)?\s*", a):
+        cleaned = re.sub(r"[\$€£¥,\s]", "", a)
+        if cleaned:
+            return cleaned
+
+    return a
+
+
+# Final-answer formatter pass용 시스템 프롬프트. 짧고 부정형 최소화.
+_FORMAT_SYSTEM_PROMPT = """You reformat agent answers to match the GAIA benchmark
+exact-match grading rules. You receive a question and a draft answer, and output the
+final answer string ONLY (no explanation, no preamble).
+
+Rules:
+- Numbers: plain digits, no commas, no currency/units unless the question asks for them.
+- Strings: minimal exact form. No articles ("the", "a"), no abbreviations unless
+  abbreviation is the expected form. No surrounding quotes.
+- Lists: comma + single space ("apple, banana, cherry"), in the order requested.
+- Yes/no questions: exactly "Yes" or "No".
+- "Give only the first name" → output only the first name, no surname.
+- "Give only the city name" → only the city, no country/state.
+- If the draft already matches all applicable rules, output it unchanged.
+- If the draft is "UNKNOWN" or admits inability, output "UNKNOWN".
+
+Output only the answer string, nothing else.
+"""
+
+
+def final_format_pass(
+    question: str,
+    raw_answer: str,
+    model_id: str = "Qwen/Qwen2.5-72B-Instruct",
+) -> str:
+    """LLM 한 번 더 호출해 raw 답을 GAIA 포맷으로만 변환.
+
+    호출 실패(rate-limit, 타임아웃 등) 시 raw_answer를 그대로 반환 — graceful
+    degrade. coerce_answer가 마지막 안전망이므로 이 단계가 실패해도 큰 손해는 없음.
+
+    유니코드 정규화(NFC)도 같이 수행해서 보이지 않는 변형 글자(예: 결합 글자
+    분해된 형태)로 인한 mismatch 방지.
+
+    Args:
+        question: 원본 질문 본문.
+        raw_answer: 에이전트가 final_answer로 넘긴 raw 답.
+        model_id: 포맷 변환에 쓸 모델 (기본은 메인 모델과 동일).
+
+    Returns:
+        포맷 정리된 답 또는 raw_answer (호출 실패 시).
+    """
+    if not raw_answer or raw_answer.strip().upper() == "UNKNOWN":
+        return raw_answer
+    try:
+        from huggingface_hub import InferenceClient
+        client = InferenceClient(provider="hf-inference")
+        resp = client.chat_completion(
+            model=model_id,
+            messages=[
+                {"role": "system", "content": _FORMAT_SYSTEM_PROMPT},
+                {
+                    "role": "user",
+                    "content": f"Question: {question}\n\nDraft answer: {raw_answer}\n\nFinal answer:",
+                },
+            ],
+            max_tokens=200,  # 답변 자체는 짧음
+        )
+        formatted = (resp.choices[0].message.content or "").strip()
+        if not formatted:
+            return raw_answer
+        # 양끝 따옴표 한 쌍 제거 (모델이 종종 "X" 형태로 둘러쌈)
+        if len(formatted) >= 2 and (
+            (formatted[0] == '"' and formatted[-1] == '"')
+            or (formatted[0] == "'" and formatted[-1] == "'")
+        ):
+            formatted = formatted[1:-1].strip()
+        # NFC 정규화: 결합 글자(예: ł, é) 변형 통일
+        formatted = unicodedata.normalize("NFC", formatted)
+        return formatted
+    except Exception as e:
+        print(f"final_format_pass failed (using raw): {e}")
+        return raw_answer

prompts.py

@@ -0,0 +1,98 @@
+"""GAIA 채점 형식에 맞춘 답변 가이드라인.
+
+CodeAgent의 기본 시스템 프롬프트 뒤에 append 된다. exact-match 채점이라 형식
+위반 한 글자만으로 오답이 되므로 강하게 박아둔다.
+
+룰 변경 이력:
+- 과거 "코드 출력에 <code> 태그 사용 금지" 룰이 있었음. 32B 코더 모델이 매 스텝
+  `</code]` 같은 깨진 태그를 흘려 파서가 깨진 데서 출발한 방어 코드지만, smolagents가
+  정상적인 <code>...</code> 태그를 *요구*하는 구조라 우리 룰이 정상 태그까지 금지
+  → 다른 모델(DeepSeek-V3, Llama 등)에서 파서가 깨짐. 모델 선택(코더 모델 회피)으로만
+  다루기로 하고 룰에서 제거. LLM-facing 문자열에 메타 설명 절대 넣지 말 것
+  (토큰 낭비 + 다국어 메타 텍스트가 모델을 혼란시킬 수 있음).
+"""
+
+GAIA_ANSWER_GUIDELINES = """
+You are answering questions from the GAIA benchmark. Your final answer will be graded
+by EXACT STRING MATCH, so formatting matters as much as correctness.
+
+CRITICAL — never violate these:
+1. NEVER fabricate data. If a tool returns "No file attached", "No results", or an error,
+   try a DIFFERENT query or DIFFERENT tool. Do NOT invent placeholder data and do NOT write
+   "Since I can't actually read the file, I'll simulate..." — that produces wrong answers.
+   If after multiple genuine attempts (different queries, Wikipedia + web_search + visit_webpage)
+   you still cannot find the answer, call final_answer("UNKNOWN").
+2. Always verify a fact against an authoritative source (Wikipedia article body, official site)
+   before committing — do not commit based on a search-result snippet alone.
+3. For questions about lists/tables (winners, rosters, dates, etc.), call wikipedia_search
+   first; it returns the full article body including [TABLE]...[/TABLE] blocks.
+4. If the question mentions an attached file, spreadsheet, image, audio, PDF, code listing,
+   or "the file I gave you", IMMEDIATELY call get_attached_file() with NO arguments.
+   It auto-resolves the current task — never pass a placeholder task_id, never simulate
+   the file's contents.
+4b. If the question contains a YouTube URL or asks about a YouTube video's contents,
+   call youtube_info(url) with the URL. It returns the video's title, channel, and full
+   transcript text. If the transcript is unavailable, fall back to web_search/wikipedia
+   for the question's specific facts — never simulate transcript content.
+5. DECIDE AND COMMIT EARLY. As soon as you have enough evidence (typically by step 6-8 out
+   of the 12-step budget), call final_answer(...) immediately. Do NOT spend more steps
+   re-verifying after you already have a confident answer. Running out of steps means
+   smolagents returns your last verbose thought as the answer — verbose prose scores ZERO
+   on exact-match grading.
+
+Answer formatting rules (apply only to the value passed to final_answer):
+- Return ONLY the final answer — no explanations, no preamble, no trailing punctuation.
+- Numbers: plain digits, no commas, no currency symbols, no units (unless the question asks for them).
+  Use an integer if the answer is a whole number.
+- Strings: minimal exact form, no surrounding quotes, no "The answer is...".
+- Lists: comma-separated with a single space after each comma (e.g., "apple, banana, cherry"),
+  in the order the question requests.
+- Yes/no questions: answer exactly "Yes" or "No".
+- Match capitalization, abbreviations, and spelling exactly as the question implies.
+
+When you call final_answer(...), pass the bare answer string (or number) only —
+do not wrap it in a sentence and do not prefix it with "FINAL ANSWER:".
+"""
+
+
+# 멀티홉 질문 분해용 시스템 프롬프트. decomposer.py 가 사용한다.
+# 출력은 numbered plan 또는 정확히 "SINGLE-HOP" 둘 중 하나만 허용.
+DECOMPOSITION_PROMPT = """You are a planner for a GAIA benchmark agent. Your job is to decide whether a question requires multiple sequential lookups, and if so, lay out the minimal sequence.
+
+OUTPUT FORMAT:
+- If the question can be answered with ONE lookup or fact, respond with exactly:
+  SINGLE-HOP
+- Otherwise, respond with a numbered plan. Each step is a self-contained sub-question answerable by one Wikipedia/web/file lookup. Use placeholders like [step1_answer] when later steps depend on earlier results.
+
+GUIDELINES:
+- Prefer fewer steps. Don't pad with verification.
+- A question mentioning an attached file/spreadsheet/image/audio/PDF is usually multi-hop: step 1 = read the file, then combine with question logic.
+- A question asking for a list, count, sum, or aggregation is usually multi-hop.
+- DO NOT answer the question yourself. Output ONLY the plan or SINGLE-HOP — no preamble, no trailing text.
+
+EXAMPLES:
+
+Q: Who directed the 2003 film "Lost in Translation"?
+A: SINGLE-HOP
+
+Q: In what year was the author of "The Old Man and the Sea" born?
+A: SINGLE-HOP
+
+Q: What is the population of the birthplace of the actor who played Captain Jack Sparrow?
+A:
+1. Who played Captain Jack Sparrow?
+2. Where was [step1_answer] born?
+3. What is the current population of [step2_answer]?
+
+Q: How many studio albums did Pink Floyd release before The Dark Side of the Moon?
+A:
+1. List Pink Floyd's studio albums chronologically.
+2. Count how many were released before The Dark Side of the Moon (1973).
+
+Q: The attached spreadsheet contains 2023 sales by region. What was the total for the South region?
+A:
+1. Read the attached spreadsheet.
+2. Filter rows where region = "South" and sum the sales column.
+
+Now decompose the user's question. Output ONLY the plan or "SINGLE-HOP".
+"""

requirements.txt

@@ -1,2 +1,12 @@
-gradio
-requests
+gradio[oauth]>=4.44
+requests
+pandas
+openpyxl
+smolagents>=1.10
+ddgs
+duckduckgo-search
+markdownify
+beautifulsoup4
+pypdf>=4.0
+huggingface_hub>=0.28
+youtube-transcript-api>=0.6

tools/__init__.py

@@ -0,0 +1,30 @@
+"""에이전트 도구 묶음.
+
+`from tools import web_search, visit_webpage, ...` 한 번으로 모두 import 가능.
+세부 구현은 각 모듈 파일에 분리되어 있다.
+"""
+from .search import web_search
+from .webpage import visit_webpage
+from .wikipedia import wikipedia_search
+from .youtube import youtube_info
+from .exec_code import exec_python_code
+from .attachments import (
+    get_attached_file,
+    prefetch_question_index,
+    set_question_index,
+    set_current_task,
+)
+
+__all__ = [
+    # @tool 함수 (CodeAgent에 직접 등록)
+    "web_search",
+    "visit_webpage",
+    "wikipedia_search",
+    "youtube_info",
+    "exec_python_code",
+    "get_attached_file",
+    # 일반 헬퍼 (BasicAgent의 init/__call__에서 사용)
+    "prefetch_question_index",
+    "set_question_index",
+    "set_current_task",
+]

tools/attachments.py

@@ -0,0 +1,301 @@
+"""GAIA 첨부 파일 처리 + 질문↔task_id 인덱스.
+
+CodeAgent의 시그니처 제약(__call__이 question만 받음) 때문에 task_id를 직접
+주입할 수 없어, 모듈 전역 mutable 컨테이너 + prefetch 인덱스로 우회한다.
+
+흐름:
+    1) BasicAgent.__init__ 단계에 prefetch_question_index() → /questions 1회 호출
+       해서 {질문본문: task_id} 사전을 만들고 set_question_index() 로 등록.
+    2) BasicAgent.__call__ 진입 시 set_current_task(question) 으로 현재 문제의
+       task_id와 질문 본문을 _CURRENT_TASK 에 세팅.
+    3) 에이전트가 get_attached_file() 을 인자 없이 호출하면 _CURRENT_TASK 의
+       task_id로 채점 서버에서 파일을 받아오고, 타입별로 처리:
+       - 텍스트/CSV/JSON/code: UTF-8 디코딩
+       - Excel(.xlsx): 시트별 CSV
+       - PDF: 페이지별 텍스트 추출 (pypdf)
+       - 이미지: VLM(Qwen2.5-VL-7B)으로 현재 질문 컨텍스트에 맞춰 분석
+       - 오디오: Whisper(large-v3) 전사
+"""
+import io
+import re
+import requests
+from smolagents import tool
+
+# 채점 서버 URL을 여기서도 한 번 정의 (app.py와 동일 값).
+# tools 모듈을 독립적으로 사용하더라도 의미가 통하도록 분리해 둔다.
+_DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+
+# BasicAgent.__call__ 진입 시 갱신되는 mutable 컨테이너.
+# question은 이미지 VLM 호출 시 컨텍스트(prompt)로 사용된다.
+_CURRENT_TASK = {"id": None, "question": None}
+# question.strip() -> task_id 사전.
+_QUESTION_INDEX: dict = {}
+
+
+def prefetch_question_index() -> dict:
+    """채점 서버 /questions 를 한 번 호출해 {질문본문: task_id} 사전을 빌드한다.
+    실패해도 빈 dict를 반환해 에이전트가 첨부 없는 문제만이라도 풀 수 있게 한다."""
+    try:
+        r = requests.get(f"{_DEFAULT_API_URL}/questions", timeout=15)
+        r.raise_for_status()
+        idx = {}
+        for item in r.json():
+            qt = (item.get("question") or "").strip()
+            tid = item.get("task_id")
+            if qt and tid:
+                if qt in idx and idx[qt] != tid:
+                    print(
+                        "Warning: duplicate question text in prefetch index — "
+                        f"task_id {idx[qt]!r} will be overwritten by {tid!r}"
+                    )
+                idx[qt] = tid
+        return idx
+    except Exception as e:
+        print(f"Warning: could not prefetch question index: {e}")
+        return {}
+
+
+def set_question_index(idx: dict) -> None:
+    """BasicAgent.__init__에서 prefetch 결과를 모듈 전역에 박아주는 세터."""
+    global _QUESTION_INDEX
+    _QUESTION_INDEX = idx
+
+
+def set_current_task(question: str):
+    """BasicAgent.__call__ 진입 시 현재 문제의 task_id와 질문 본문을 모듈 전역에 세팅.
+    질문 본문은 이미지 첨부의 VLM 호출에 prompt 컨텍스트로 전달된다.
+    매칭 실패 시 task_id로 None이 들어가지만 question은 그대로 저장된다."""
+    tid = _QUESTION_INDEX.get(question.strip())
+    _CURRENT_TASK["id"] = tid
+    _CURRENT_TASK["question"] = question
+    return tid
+
+
+# --- 파일 타입 분기 헬퍼 ---
+
+def _extract_filename(headers, url: str) -> str:
+    """Content-Disposition 헤더에서 filename을 뽑거나, URL 끝부분으로 폴백.
+    채점 서버가 Content-Type을 octet-stream으로 줄 때 확장자로 보강하기 위함."""
+    cd = headers.get("Content-Disposition", "")
+    # filename* (RFC 5987) 와 filename= 양쪽 다 처리.
+    m = re.search(r'filename\*?=(?:UTF-8\'\')?"?([^";\r\n]+)"?', cd)
+    if m:
+        return m.group(1).strip().strip('"')
+    return url.rsplit("/", 1)[-1]
+
+
+def _is_excel(content_type: str, ext: str) -> bool:
+    if ext in ("xlsx", "xls"):
+        return True
+    ct = content_type.lower()
+    return "spreadsheet" in ct or ct.endswith("xlsx") or ct.endswith("xls") or "excel" in ct
+
+
+def _is_pdf(content_type: str, ext: str) -> bool:
+    return ext == "pdf" or "pdf" in content_type.lower()
+
+
+def _is_image(content_type: str, ext: str) -> bool:
+    return ext in ("png", "jpg", "jpeg", "webp", "gif", "bmp") \
+        or content_type.lower().startswith("image/")
+
+
+def _is_audio(content_type: str, ext: str) -> bool:
+    return ext in ("mp3", "wav", "m4a", "ogg", "flac") \
+        or content_type.lower().startswith("audio/")
+
+
+# --- 타입별 핸들러 ---
+
+def _handle_excel(content: bytes, content_type: str) -> str:
+    """xlsx → 시트별 CSV로 직렬화. GAIA에 매출/판매 데이터 문제가 자주 나온다."""
+    try:
+        import pandas as _pd
+        bio = io.BytesIO(content)
+        sheets = _pd.read_excel(bio, sheet_name=None)
+        parts = []
+        for name, df in sheets.items():
+            parts.append(f"--- Sheet: {name} ---\n{df.to_csv(index=False)}")
+        combined = "\n\n".join(parts)
+        if len(combined) > 12000:
+            combined = combined[:12000] + "\n...[truncated]"
+        return f"[Content-Type: {content_type}]\n{combined}"
+    except Exception as e:
+        return f"Excel parse error: {e}"
+
+
+def _handle_pdf(content: bytes, content_type: str) -> str:
+    """pypdf로 PDF 본문 텍스트 추출. 페이지별로 구분해서 반환.
+    스캔 PDF(이미지로 된)는 텍스트가 비거나 깨질 수 있는데, 그 경우는
+    LLM이 위키/웹검색으로 폴백하도록 시스템 프롬프트가 유도한다."""
+    try:
+        from pypdf import PdfReader
+        bio = io.BytesIO(content)
+        reader = PdfReader(bio)
+        parts = []
+        for i, page in enumerate(reader.pages):
+            try:
+                txt = page.extract_text() or ""
+            except Exception as pe:
+                txt = f"(extraction failed: {pe})"
+            parts.append(f"--- Page {i+1} ---\n{txt}")
+        combined = "\n\n".join(parts)
+        if len(combined) > 12000:
+            combined = combined[:12000] + "\n...[truncated]"
+        return f"[PDF, {len(reader.pages)} pages, Content-Type: {content_type}]\n{combined}"
+    except Exception as e:
+        return f"PDF parse error: {e}"
+
+
+def _handle_image(content: bytes, content_type: str) -> str:
+    """VLM(Qwen2.5-VL-7B)으로 현재 질문 컨텍스트에 맞춰 이미지를 분석한다.
+
+    HF Inference API의 OpenAI 호환 chat_completion으로 base64 data URL을 전송한다.
+    질문 컨텍스트가 있으면 그걸 그대로 prompt에 박아 정답에 직접 도움이 되는
+    부분만 뽑아내도록 유도(generic 캡션은 디테일을 놓침). 호출 실패 시 에러
+    문자열을 반환해 에이전트가 다른 전략으로 폴백할 수 있게 한다.
+
+    HF_TOKEN 환경변수가 필요하다. Space 배포 시에는 Space secrets에 등록해야 함.
+    """
+    try:
+        import base64
+        from huggingface_hub import InferenceClient
+
+        question = (_CURRENT_TASK.get("question") or "").strip()
+        # 데이터 URL 구성. content_type이 image/* 가 아닐 수도 있어 안전하게 폴백.
+        mime = content_type.split(";")[0].strip()
+        if not mime.startswith("image/"):
+            mime = "image/png"
+        b64 = base64.b64encode(content).decode("utf-8")
+        data_url = f"data:{mime};base64,{b64}"
+
+        if question:
+            prompt = (
+                "Analyze the attached image and answer the following question. "
+                "Read any text, numbers, or labels visible in the image. "
+                "If it is a chart or table, extract the relevant data values precisely.\n\n"
+                f"Question: {question}"
+            )
+        else:
+            prompt = (
+                "Describe the attached image in detail, including any visible text, "
+                "numbers, or labels."
+            )
+
+        client = InferenceClient(provider="hf-inference")  # HF_TOKEN 환경변수 사용
+        resp = client.chat_completion(
+            model="Qwen/Qwen2.5-VL-7B-Instruct",
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": prompt},
+                        {"type": "image_url", "image_url": {"url": data_url}},
+                    ],
+                }
+            ],
+            max_tokens=1024,
+        )
+        analysis = resp.choices[0].message.content
+        return (
+            f"[Image analysis (Content-Type: {content_type}, {len(content)} bytes)]\n"
+            f"{analysis}"
+        )
+    except Exception as e:
+        return (
+            f"Image attached (Content-Type: {content_type}, {len(content)} bytes). "
+            f"VLM analysis failed: {e}"
+        )
+
+
+def _handle_audio(content: bytes, content_type: str) -> str:
+    """Whisper(large-v3)로 오디오 전사. GAIA 오디오는 보통 짧은 발화라 한 번 호출로 충분.
+
+    HF_TOKEN 환경변수가 필요하다. Space 배포 시에는 Space secrets에 등록해야 함.
+    """
+    try:
+        from huggingface_hub import InferenceClient
+        client = InferenceClient(provider="hf-inference")
+        result = client.automatic_speech_recognition(
+            audio=content,
+            model="openai/whisper-large-v3",
+        )
+        # huggingface_hub 버전에 따라 dict 또는 dataclass-like 객체로 반환되므로
+        # 양쪽 모두 처리한다.
+        if hasattr(result, "text"):
+            transcription = result.text
+        elif isinstance(result, dict):
+            transcription = result.get("text", str(result))
+        else:
+            transcription = str(result)
+        return (
+            f"[Audio transcription (Content-Type: {content_type}, {len(content)} bytes)]\n"
+            f"{transcription}"
+        )
+    except Exception as e:
+        return (
+            f"Audio attached (Content-Type: {content_type}, {len(content)} bytes). "
+            f"Transcription failed: {e}"
+        )
+
+
+@tool
+def get_attached_file() -> str:
+    """Download the file attached to the CURRENT GAIA task and return its content.
+    Takes no arguments — the current task_id is auto-resolved from the question.
+
+    Use this whenever the question references a file, spreadsheet, image, audio, PDF, code listing,
+    CSV, or any external resource. Returns:
+      - Text/CSV/JSON/code: the decoded text (truncated to ~12k chars).
+      - Excel (.xlsx): each sheet rendered as CSV (truncated).
+      - PDF: extracted text per page (truncated).
+      - Image (PNG/JPEG/WEBP/GIF/BMP): a vision-language model analysis focused on the current question.
+      - Audio (MP3/WAV/M4A/OGG/FLAC): a Whisper transcription.
+      - Other binary: a metadata description (size + content-type).
+    """
+    # 시그니처 제약 때문에 task_id 인자를 받지 않고, 모듈 전역 _CURRENT_TASK 에서 가져온다.
+    # 이 값은 BasicAgent.__call__ 진입 시 set_current_task()로 세팅된다.
+    task_id = _CURRENT_TASK.get("id")
+    if not task_id:
+        return "No task context available — likely no file attached for this question."
+    try:
+        url = f"{_DEFAULT_API_URL}/files/{task_id}"
+        r = requests.get(url, timeout=30)
+        if r.status_code == 404:
+            return "No file attached to this task."
+        r.raise_for_status()
+        content_type = r.headers.get("Content-Type", "")
+        filename = _extract_filename(r.headers, url)
+        ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+
+        # 1) 명확한 바이너리 타입은 먼저 처리.
+        # 일부 PDF/SVG는 UTF-8 decode가 되어도 원시 텍스트로 반환하면 품질이 크게 떨어진다.
+        if _is_excel(content_type, ext):
+            return _handle_excel(r.content, content_type)
+
+        if _is_pdf(content_type, ext):
+            return _handle_pdf(r.content, content_type)
+
+        if _is_image(content_type, ext):
+            return _handle_image(r.content, content_type)
+
+        if _is_audio(content_type, ext):
+            return _handle_audio(r.content, content_type)
+
+        # 2) 텍스트 계열이면 UTF-8로 반환.
+        try:
+            text = r.content.decode("utf-8")
+            if len(text) > 12000:
+                text = text[:12000] + "\n...[truncated]"
+            return f"[Content-Type: {content_type}]\n{text}"
+        except UnicodeDecodeError:
+            pass
+
+        # 3) 알 수 없는 바이너리 — 메타데이터만 반환.
+        return (
+            f"Binary file (Content-Type: {content_type}, "
+            f"size: {len(r.content)} bytes). Cannot display as text. "
+            f"URL: {url}"
+        )
+    except Exception as e:
+        return f"get_attached_file error: {e}"

tools/exec_code.py

@@ -0,0 +1,57 @@
+"""파이썬 코드 실행 도구.
+
+GAIA에 "attached Python code"의 출력을 묻는 질문(예: f918266a)이 등장.
+첨부 파일은 텍스트로 받지만 출력을 알려면 실제 실행이 필요. smolagents의 자체
+코드 sandbox로 처리할 수도 있지만 명시 도구로 분리하면 (a) LLM이 의도를 명확히
+표현 (b) stdout 캡처를 단순화한다.
+
+안전: 첨부된 코드를 직접 실행하므로 신뢰되지 않은 입력에 노출. GAIA 채점
+컨텍스트 한정으로 사용. 실서비스에는 sandbox 강화 필요.
+"""
+import os
+import subprocess
+import sys
+import tempfile
+from smolagents import tool
+
+
+@tool
+def exec_python_code(code: str) -> str:
+    """Execute Python source code and return its captured stdout.
+    Use this when the question asks for the output of a piece of attached or referenced
+    Python code (e.g., "What is the final numeric output of the code?"). Pass the code
+    body verbatim. Captures both stdout and stderr; returns up to ~12k characters.
+
+    Args:
+        code: The Python source code to execute.
+    """
+    if len(code) > 50000:
+        return "exec_python_code error: code is too large to execute safely"
+
+    try:
+        with tempfile.TemporaryDirectory(prefix="gaia_exec_") as tmpdir:
+            script_path = os.path.join(tmpdir, "snippet.py")
+            with open(script_path, "w", encoding="utf-8") as f:
+                f.write(code)
+            result = subprocess.run(
+                [sys.executable, "-I", script_path],
+                cwd=tmpdir,
+                capture_output=True,
+                text=True,
+                timeout=8,
+            )
+        out = (result.stdout or "") + (result.stderr or "")
+        if result.returncode != 0:
+            out = f"exec_python_code exited with status {result.returncode}\n{out}"
+    except subprocess.TimeoutExpired as e:
+        partial = ((e.stdout or "") + (e.stderr or ""))[:4000]
+        return f"exec_python_code error: TimeoutExpired after 8s\n--- partial output ---\n{partial}"
+    except Exception as e:
+        return (
+            f"exec_python_code error: {type(e).__name__}: {e}\n"
+            f"--- partial output ---\n"
+        )
+
+    if len(out) > 12000:
+        out = out[:12000] + "\n...[truncated]"
+    return out or "(no stdout output)"

tools/search.py

@@ -0,0 +1,197 @@
+"""웹 검색 툴. 백엔드 우선순위: SearXNG → Tavily → Brave → DuckDuckGo.
+
+SearXNG 는 키 없이 동작하는 메타검색(공개 인스턴스 폴백). Tavily/Brave 는 환경변수로
+API 키가 설정된 경우에만 사용. 둘 다 무료 티어가 있다 (Tavily 1k/월, Brave 2k/월
+가량). DDG는 마지막 안전망이지만 종종 차단/디코딩 에러가 나므로 우선 백엔드들을
+앞에 두는 게 안정적이다.
+
+각 백엔드는 결과가 있으면 포맷된 문자열, 없으면 None 을 반환. 호출자(web_search)는
+None 을 만나면 다음 백엔드로 폴백한다. DDG 는 마지막 폴백이라 None 대신 항상
+문자열(에러 메시지 또는 "No results found.")을 반환한다.
+
+환경변수:
+    TAVILY_API_KEY  Tavily Search API 키 (옵션)
+    BRAVE_API_KEY   Brave Search API 키 (옵션)
+"""
+import os
+import random
+import requests
+from smolagents import tool
+
+_TAVILY_URL = "https://api.tavily.com/search"
+_BRAVE_URL = "https://api.search.brave.com/res/v1/web/search"
+
+# SearXNG 공개 인스턴스 풀. 키 불필요. 호출마다 일부만 무작위로 골라 시도해서
+# (a) 한 인스턴스가 IP 차단 가속되는 걸 분산하고 (b) 누적 timeout 상한을 통제한다.
+# searx.space 가용 목록을 주기적으로 갱신할 것.
+_SEARXNG_INSTANCES = (
+    "https://searx.be",
+    "https://searx.tiekoetter.com",
+    "https://search.inetol.net",
+    "https://searxng.online",
+    "https://priv.au",
+)
+_SEARXNG_TRY_COUNT = 3        # 호출당 시도할 인스턴스 수
+_SEARXNG_TIMEOUT = 5          # 인스턴스당 타임아웃(초) — 누적 상한 ~15s
+
+
+def _format_results(items) -> str:
+    """공통 포매터: (title, url, snippet) 튜플 리스트를 LLM-friendly 텍스트로."""
+    lines = [f"- {t}\n  {u}\n  {b}" for t, u, b in items if (t or u or b)]
+    return "\n".join(lines) if lines else ""
+
+
+def _search_searxng(query: str) -> str | None:
+    """SearXNG 메타검색. Google/Bing/DDG 등 70+ 엔진을 묶어 반환. 키 불필요.
+    공개 인스턴스 폴백 — 한 곳 죽으면 다음으로. 모두 실패하면 None 반환해
+    호출자가 다음 백엔드(Tavily/Brave/DDG)로 폴백하게 한다.
+
+    일부 인스턴스는 빈 UA 또는 봇처럼 보이는 요청을 차단하므로 브라우저 UA를 명시.
+    """
+    headers = {
+        "User-Agent": (
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+            "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+        ),
+        "Accept": "application/json",
+    }
+    # 호출마다 무작위 부분집합 → 부하 분산 + 누적 timeout 통제.
+    candidates = random.sample(_SEARXNG_INSTANCES, _SEARXNG_TRY_COUNT)
+    for base in candidates:
+        try:
+            r = requests.get(
+                f"{base}/search",
+                params={"q": query, "format": "json", "language": "en"},
+                headers=headers,
+                timeout=_SEARXNG_TIMEOUT,
+            )
+            if r.status_code != 200:
+                continue
+            results = r.json().get("results", [])
+            if not results:
+                continue
+            items = [
+                (x.get("title", ""), x.get("url", ""), x.get("content", ""))
+                for x in results[:8]  # 토큰 제어, DDG와 동일한 max_results=8
+            ]
+            formatted = _format_results(items)
+            if formatted:
+                return formatted
+        except Exception as e:
+            print(f"SearXNG ({base}) failed: {e}")
+            continue
+    return None
+
+
+def _search_tavily(query: str) -> str | None:
+    """Tavily Search API. TAVILY_API_KEY 가 있어야 호출."""
+    api_key = os.getenv("TAVILY_API_KEY")
+    if not api_key:
+        return None
+    try:
+        r = requests.post(
+            _TAVILY_URL,
+            json={"api_key": api_key, "query": query, "max_results": 8},
+            timeout=15,
+        )
+        r.raise_for_status()
+        results = r.json().get("results", [])
+        if not results:
+            return None
+        items = [
+            (x.get("title", ""), x.get("url", ""), x.get("content", ""))
+            for x in results
+        ]
+        formatted = _format_results(items)
+        return formatted or None
+    except Exception as e:
+        print(f"Tavily search failed (falling back): {e}")
+        return None
+
+
+def _search_brave(query: str) -> str | None:
+    """Brave Search API. BRAVE_API_KEY 가 있어야 호출."""
+    api_key = os.getenv("BRAVE_API_KEY")
+    if not api_key:
+        return None
+    try:
+        r = requests.get(
+            _BRAVE_URL,
+            params={"q": query, "count": 8},
+            headers={
+                "X-Subscription-Token": api_key,
+                "Accept": "application/json",
+            },
+            timeout=15,
+        )
+        r.raise_for_status()
+        results = r.json().get("web", {}).get("results", [])
+        if not results:
+            return None
+        items = [
+            (x.get("title", ""), x.get("url", ""), x.get("description", ""))
+            for x in results
+        ]
+        formatted = _format_results(items)
+        return formatted or None
+    except Exception as e:
+        print(f"Brave search failed (falling back): {e}")
+        return None
+
+
+def _search_ddg(query: str) -> str:
+    """DuckDuckGo. ddgs 패키지 우선, 실패 시 구 duckduckgo_search 폴백.
+    마지막 폴백이라 None 대신 항상 문자열을 반환한다(에러 메시지 또는 "No results found.")."""
+    # DDG 클라이언트 패키지 이름이 `duckduckgo_search` → `ddgs`로 바뀌었고
+    # 구 패키지에서는 "Body collection error: ..." 같은 디코딩 에러가 빈번했다.
+    last_err = None
+    for module_name in ("ddgs", "duckduckgo_search"):
+        try:
+            mod = __import__(module_name, fromlist=["DDGS"])
+            DDGS = getattr(mod, "DDGS")
+            with DDGS() as ddgs:
+                # max_results=8: 너무 적으면 정답 사이트 누락, 너무 많으면 컨텍스트 낭비.
+                results = list(ddgs.text(query, max_results=8))
+            if not results:
+                continue
+            # 두 패키지가 키 이름이 미묘하게 다르므로 양쪽 모두 처리.
+            items = [
+                (
+                    r.get("title", ""),
+                    r.get("href", "") or r.get("url", ""),
+                    r.get("body", "") or r.get("snippet", ""),
+                )
+                for r in results
+            ]
+            formatted = _format_results(items)
+            if formatted:
+                return formatted
+        except Exception as e:
+            last_err = e
+            continue
+    if last_err:
+        return f"web_search error: {last_err}"
+    return "No results found."
+
+
+@tool
+def web_search(query: str) -> str:
+    """Search the web and return a list of titles, URLs, and snippets.
+    Backend priority: SearXNG public instances (no key) -> Tavily/Brave (only if their
+    API keys are set in environment variables TAVILY_API_KEY, BRAVE_API_KEY) ->
+    DuckDuckGo fallback.
+
+    Args:
+        query: The search query string.
+    """
+    # SearXNG가 1순위: 키 없이 가장 양질의 결과를 주는 백엔드.
+    # Tavily/Brave는 키가 환경변수에 있을 때만 시도(없으면 None 반환하고 통과).
+    # DDG는 마지막 안전망.
+    out = _search_searxng(query)
+    if out:
+        return out
+    for backend in (_search_tavily, _search_brave):
+        out = backend(query)
+        if out:
+            return out
+    return _search_ddg(query)

tools/webpage.py

@@ -0,0 +1,67 @@
+"""일반 웹페이지 fetch + 마크다운 변환 툴.
+
+Content-Type 분기:
+- text/html → BeautifulSoup → markdownify
+- application/pdf → pypdf로 페이지별 텍스트 추출 (arxiv·NASA TR 등 외부 PDF용)
+"""
+import io
+import re
+import requests
+from bs4 import BeautifulSoup
+from markdownify import markdownify as md
+from smolagents import tool
+
+
+def _handle_pdf_url(content: bytes) -> str:
+    """외부 PDF URL 본문을 페이지별 텍스트로 변환. attachments._handle_pdf와 동일 패턴."""
+    try:
+        from pypdf import PdfReader
+        reader = PdfReader(io.BytesIO(content))
+        parts = []
+        for i, page in enumerate(reader.pages):
+            try:
+                txt = page.extract_text() or ""
+            except Exception as pe:
+                txt = f"(extraction failed: {pe})"
+            parts.append(f"--- Page {i+1} ---\n{txt}")
+        combined = "\n\n".join(parts)
+        if len(combined) > 12000:
+            combined = combined[:12000] + "\n...[truncated]"
+        return f"[PDF, {len(reader.pages)} pages]\n{combined}"
+    except Exception as e:
+        return f"PDF parse error: {e}"
+
+
+@tool
+def visit_webpage(url: str) -> str:
+    """Fetch a web page (HTML or PDF) and return its readable text (truncated to ~12k chars).
+
+    HTML pages are converted to markdown. PDF URLs are parsed page-by-page via pypdf —
+    useful for arxiv papers, NASA technical reports, and other linked PDF documents.
+
+    Args:
+        url: The full URL of the webpage or PDF to fetch.
+    """
+    try:
+        # 일부 사이트(특히 위키미디어 외)가 빈 User-Agent를 차단하므로 헤더를 명시한다.
+        headers = {"User-Agent": "Mozilla/5.0 (compatible; GAIA-Agent/1.0)"}
+        resp = requests.get(url, headers=headers, timeout=20)
+        resp.raise_for_status()
+        content_type = resp.headers.get("Content-Type", "").lower()
+        # PDF: pypdf로 텍스트 추출. arxiv 논문 등 GAIA에 자주 등장.
+        if "application/pdf" in content_type or url.lower().endswith(".pdf"):
+            return _handle_pdf_url(resp.content)
+        # HTML: 기존 흐름.
+        soup = BeautifulSoup(resp.text, "html.parser")
+        # 본문과 무관한 노이즈 제거: 스크립트/스타일/noscript 블록.
+        for tag in soup(["script", "style", "noscript"]):
+            tag.decompose()
+        markdown = md(str(soup))
+        # markdownify가 종종 빈 줄을 줄줄이 만들어내므로 압축해서 토큰을 절약한다.
+        markdown = re.sub(r"\n{3,}", "\n\n", markdown).strip()
+        # LLM 컨텍스트 보호: 너무 큰 페이지는 잘라서 반환한다.
+        if len(markdown) > 12000:
+            markdown = markdown[:12000] + "\n...[truncated]"
+        return markdown
+    except Exception as e:
+        return f"visit_webpage error: {e}"

tools/wikipedia.py

@@ -0,0 +1,117 @@
+"""위키피디아 본문(표 포함) 추출 툴.
+
+REST `summary` 엔드포인트는 lead paragraph만 반환해서 표 기반 사실(수상자 명단,
+선수 명부 등)을 못 본다. action=parse 로 풀 HTML을 받아 표를 [TABLE]/[/TABLE]
+블록으로 텍스트화한다.
+"""
+import re
+import requests
+from bs4 import BeautifulSoup
+from smolagents import tool
+
+# Wikipedia User-Agent 정책: 빈 UA / "python-requests/..." 같은 기본 UA 는 403 차단됨.
+# https://meta.wikimedia.org/wiki/User-Agent_policy 참고. 이름 + 용도가 식별되면 충분.
+_HEADERS = {
+    "User-Agent": "GAIA-Agent/1.0 (HF agents course unit 4; https://huggingface.co/spaces)"
+}
+
+
+@tool
+def wikipedia_search(query: str) -> str:
+    """Search English Wikipedia and return the FULL article body (text + tables) of the top matching
+    article, rendered as readable text and truncated to ~14k chars. Includes section headers and
+    table rows so factual lookups (winners lists, rosters, dates, etc.) are answerable.
+
+    Args:
+        query: The search term or article title.
+    """
+    try:
+        # 1단계: 검색 API로 가장 매칭 가능성이 높은 문서 제목을 찾는다.
+        s = requests.get(
+            "https://en.wikipedia.org/w/api.php",
+            params={
+                "action": "query",
+                "format": "json",
+                "list": "search",
+                "srsearch": query,
+                "srlimit": 3,
+            },
+            headers=_HEADERS,
+            timeout=15,
+        )
+        s.raise_for_status()
+        hits = s.json().get("query", {}).get("search", [])
+        if not hits:
+            return "No Wikipedia results."
+        title = hits[0]["title"]
+        # 동음이의 disambiguation: 상위 3개 후보를 헤더에 노출. 1위가 정답 페이지가
+        # 아닌 경우(예: "Mercury" 행성 vs 신 vs 회사) 에이전트가 다른 후보 제목으로
+        # 재검색하거나 visit_webpage로 직접 접근할 수 있도록 신호.
+        candidates = [h.get("title", "") for h in hits[:3]]
+
+        # 2단계: parse API로 본문 HTML을 받는다(표·인포박스 포함).
+        page = requests.get(
+            "https://en.wikipedia.org/w/api.php",
+            params={
+                "action": "parse",
+                "format": "json",
+                "page": title,
+                "prop": "text",
+                "redirects": True,
+            },
+            headers=_HEADERS,
+            timeout=20,
+        )
+        page.raise_for_status()
+        html = page.json().get("parse", {}).get("text", {}).get("*", "")
+        if not html:
+            return f"Top hit: {title} (no body available)."
+
+        soup = BeautifulSoup(html, "html.parser")
+        # 각주, 편집 링크, 네비게이션 박스 등 정답과 무관한 노이즈를 제거한다.
+        for tag in soup.select(
+            "sup.reference, .mw-editsection, .reference, .navbox, "
+            ".infobox.metadata, .hatnote, .printfooter, script, style"
+        ):
+            tag.decompose()
+
+        # 표를 Markdown 표 형식으로 변환. LLM이 학습 데이터에서 markdown 표를
+        # 압도적으로 많이 봐서 헤더/데이터 분리가 자연스러움. 헤더 후보(th-only
+        # 행)가 있으면 `| --- |` 구분 행을 끼워 데이터와 시각·구조적으로 분리한다.
+        # [TABLE]/[/TABLE] 마커는 LLM이 "여기 구조화 데이터" 라고 인식하도록 유지.
+        for tbl in soup.find_all("table"):
+            rows_text = []
+            header_emitted = False
+            for tr in tbl.find_all("tr"):
+                ths = tr.find_all("th")
+                tds = tr.find_all("td")
+                cells = [c.get_text(" ", strip=True) for c in tr.find_all(["th", "td"])]
+                if not cells:
+                    continue
+                # 첫 'th 만으로 구성된 다중-셀 행' 을 markdown 헤더로 취급.
+                # 단일 th 행은 보통 인포박스 라벨이라 헤더가 아님.
+                if not header_emitted and ths and not tds and len(ths) >= 2:
+                    rows_text.append("| " + " | ".join(cells) + " |")
+                    rows_text.append("| " + " | ".join(["---"] * len(cells)) + " |")
+                    header_emitted = True
+                else:
+                    rows_text.append("| " + " | ".join(cells) + " |")
+            if rows_text:
+                tbl.replace_with("\n[TABLE]\n" + "\n".join(rows_text) + "\n[/TABLE]\n")
+            else:
+                tbl.replace_with("")
+
+        text = soup.get_text("\n", strip=True)
+        text = re.sub(r"\n{3,}", "\n\n", text).strip()
+        if len(text) > 14000:
+            text = text[:14000] + "\n...[truncated]"
+        url = f"https://en.wikipedia.org/wiki/{requests.utils.quote(title.replace(' ', '_'))}"
+        candidates_str = ", ".join(candidates) if len(candidates) > 1 else title
+        return (
+            f"Title: {title}\n"
+            f"URL: {url}\n"
+            f"Candidates (top 3): {candidates_str}\n\n"
+            f"{text}"
+        )
+    except Exception as e:
+        return f"wikipedia_search error: {e}"

tools/youtube.py

@@ -0,0 +1,124 @@
+"""YouTube 영상 메타데이터 + 자막 추출 툴.
+
+GAIA 문제에 유튜브 링크가 등장하는 케이스(영상 내용/제목/채널/연도 등을 묻는
+질문)에 활용. 영상 자체를 다운로드하지 않고 자막 텍스트만 수집해 LLM에 전달.
+
+수집 방법:
+- 메타데이터: YouTube oEmbed (API 키 불필요) — title, author 만 추출.
+- 자막: youtube-transcript-api 패키지 — 자동 생성 자막도 가져옴. 영어를 우선
+  시도하고, 안 되면 번역 가능한 자막을 영어로 번역, 그것도 없으면 첫 가용 언어.
+- 자막 없는 영상(음악 비디오, 캡션 비활성 등)은 "Transcript unavailable" 반환
+  하고 메타데이터는 그대로 노출 → 에이전트가 다른 도구로 폴백 가능.
+"""
+import re
+import requests
+from smolagents import tool
+
+
+def _extract_video_id(url_or_id: str) -> str | None:
+    """다양한 YouTube URL 형식 또는 raw 11자 ID 에서 video ID 추출.
+    None 이면 LLM이 다시 시도하거나 다른 도구로 넘어가도록 함."""
+    s = url_or_id.strip()
+    # Raw ID (영상 ID는 정확히 11자: [A-Za-z0-9_-]).
+    if re.fullmatch(r"[A-Za-z0-9_-]{11}", s):
+        return s
+    # 표준 watch / youtu.be 단축 / embed / shorts URL.
+    m = re.search(
+        r"(?:youtube\.com/watch\?v=|youtu\.be/|youtube\.com/embed/|youtube\.com/shorts/)([A-Za-z0-9_-]{11})",
+        s,
+    )
+    if m:
+        return m.group(1)
+    # ?v=... or &v=... 가 다른 위치에 있을 때.
+    m = re.search(r"[?&]v=([A-Za-z0-9_-]{11})", s)
+    if m:
+        return m.group(1)
+    return None
+
+
+def _fetch_metadata(video_id: str) -> str:
+    """oEmbed 로 title/author 를 받아 텍스트로 반환. 실패해도 안전."""
+    try:
+        r = requests.get(
+            "https://www.youtube.com/oembed",
+            params={
+                "url": f"https://www.youtube.com/watch?v={video_id}",
+                "format": "json",
+            },
+            timeout=15,
+        )
+        r.raise_for_status()
+        meta = r.json()
+        title = meta.get("title", "")
+        author = meta.get("author_name", "")
+        return f"Title: {title}\nChannel: {author}"
+    except Exception as e:
+        return f"Metadata fetch failed: {e}"
+
+
+def _fetch_transcript(video_id: str) -> str:
+    """youtube-transcript-api 로 자막 텍스트를 결합해 반환.
+    영어 → 영어 번역 → 첫 가용 자막 순으로 폴백. 자막 전혀 없으면 안내 문자열.
+    """
+    try:
+        from youtube_transcript_api import YouTubeTranscriptApi
+        # 1) 영어 자막 직접 시도(자동 생성도 포함).
+        try:
+            segments = YouTubeTranscriptApi.get_transcript(video_id, languages=["en"])
+        except Exception:
+            # 2) 어떤 언어든 가능한 것을 가져오기. 가능하면 영어로 번역.
+            transcript_list = YouTubeTranscriptApi.list_transcripts(video_id)
+            chosen = None
+            for t in transcript_list:
+                try:
+                    if getattr(t, "is_translatable", False):
+                        chosen = t.translate("en").fetch()
+                        break
+                except Exception:
+                    continue
+            if chosen is None:
+                # 3) 번역 불가 시 첫 번째 가용 자막을 그대로 사용.
+                first = next(iter(transcript_list))
+                chosen = first.fetch()
+            segments = chosen
+
+        # 라이브러리 버전에 따라 dict 또는 객체로 반환 → 양쪽 처리.
+        texts = []
+        for seg in segments:
+            if isinstance(seg, dict):
+                texts.append(seg.get("text", ""))
+            else:
+                texts.append(getattr(seg, "text", ""))
+        text = " ".join(t for t in texts if t).strip()
+        if not text:
+            return "Transcript unavailable (empty)."
+        if len(text) > 14000:
+            text = text[:14000] + "\n...[truncated]"
+        return text
+    except Exception as e:
+        return f"Transcript unavailable: {e}"
+
+
+@tool
+def youtube_info(url: str) -> str:
+    """Fetch a YouTube video's title, channel, and transcript text.
+    Use this whenever a question references a YouTube link, video, or asks about its contents.
+    The transcript covers spoken content (auto-generated if no manual captions exist) and is
+    truncated to ~14k chars. If the video has no captions, only metadata is returned and you
+    should fall back to web/wikipedia searches for the question's specific facts.
+
+    Args:
+        url: A full YouTube URL (watch, youtu.be, embed, shorts) or a bare 11-character video ID.
+    """
+    video_id = _extract_video_id(url)
+    if not video_id:
+        return f"Could not parse YouTube video ID from: {url}"
+    metadata = _fetch_metadata(video_id)
+    transcript = _fetch_transcript(video_id)
+    return (
+        f"Video ID: {video_id}\n"
+        f"URL: https://www.youtube.com/watch?v={video_id}\n"
+        f"{metadata}\n\n"
+        f"--- Transcript ---\n"
+        f"{transcript}"
+    )