Implement GAIA agent with multimodal tools for Unit 4 submission.

Add SmolAgents CodeAgent with web, Wikipedia, file, audio, vision, and YouTube tools; wire attachment downloads via GAIA fallback; ignore local dev artifacts.

.gitignore

@@ -0,0 +1,14 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Local dev artifacts
+task_files/
+eval_output.txt
+.env
+.env.local
+
+# Dev-only scripts (use locally; not needed on the Space)
+run_eval_local.py
+test_one_question.py

agent.py

@@ -0,0 +1,165 @@
+"""GAIA assignment agent — Wikipedia, web, files, audio, vision, YouTube."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from smolagents import CodeAgent, InferenceClientModel, VisitWebpageTool, WebSearchTool, WikipediaSearchTool
+
+from files import file_context_block
+from tools import build_custom_tools
+
+ANSWER_INSTRUCTIONS = """
+You are a precise GAIA benchmark agent. Solve the question using tools when needed.
+
+Available capabilities:
+- wikipedia_search: English Wikipedia articles
+- web_search: DuckDuckGo web search
+- visit_webpage: Read a specific URL as markdown
+- read_spreadsheet: Parse Excel/CSV attachments
+- execute_python_file: Run an attached .py file
+- transcribe_audio: Speech-to-text for .mp3 attachments
+- analyze_image: Vision Q&A for image attachments
+- get_youtube_transcript: Captions from YouTube URLs in the question
+
+Strategy:
+1. Read the question carefully — note required OUTPUT FORMAT (number, list, names only, etc.).
+2. If an attached file path is provided, use the matching file tool first.
+3. For YouTube links in the question, use get_youtube_transcript.
+4. Prefer wikipedia_search for Wikipedia-specific questions; otherwise web_search + visit_webpage.
+5. For logic/reversal/math in the question text, reason directly — no tool needed.
+6. Call final_answer(...) as soon as you are confident.
+
+final_answer rules (CRITICAL — exact match grading):
+- Return ONLY the answer string — no explanation, no preamble.
+- Do NOT write "FINAL ANSWER" or "The answer is".
+- Follow the question's format exactly (comma-separated, two decimals, last names only, etc.).
+- Use the minimal text the question asks for.
+"""
+
+
+def maybe_unreverse(question: str) -> str:
+    """Un-reverse GAIA-style reversed English prompts."""
+    stripped = question.strip()
+    if not stripped:
+        return question
+    reversed_q = stripped[::-1]
+    starters = ("if you", "what ", "how ", "who ", "when ", "where ", "which ", "give ")
+    if reversed_q.lower().startswith(starters):
+        return reversed_q
+    return question
+
+
+def normalize_answer(text) -> str:
+    """Strip common LLM formatting so exact-match grading has a better chance."""
+    if text is None:
+        return ""
+
+    answer = str(text).strip()
+    if answer.lower() in ("none", "null", "n/a", "unknown"):
+        return ""
+
+    # CodeAgent sometimes returns final_answer(...) as text instead of executing it.
+    final_call = re.search(
+        r"final_answer\s*\(\s*(['\"])(.*?)\1\s*\)",
+        answer,
+        flags=re.IGNORECASE | re.DOTALL,
+    )
+    if final_call:
+        answer = final_call.group(2).strip()
+    else:
+        final_call = re.search(
+            r"final_answer\s*\(\s*([^)]+)\s*\)",
+            answer,
+            flags=re.IGNORECASE,
+        )
+        if final_call:
+            answer = final_call.group(1).strip().strip("'\"")
+
+    # Drop leading "Thought:" blocks if a cleaner tail exists.
+    if "Thought:" in answer and "\n" in answer:
+        lines = [line.strip() for line in answer.splitlines() if line.strip()]
+        if lines:
+            answer = lines[-1]
+
+    answer = re.sub(r"^```(?:\w+)?\s*|\s*```$", "", answer, flags=re.MULTILINE).strip()
+
+    for prefix in (
+        "FINAL ANSWER:",
+        "Final answer:",
+        "Final_answer",
+        "FINAL_ANSWER",
+        "Answer:",
+        "The answer is:",
+        "The answer is",
+    ):
+        if answer.lower().startswith(prefix.lower()):
+            answer = answer[len(prefix) :].strip(" :")
+            break
+
+    if len(answer) >= 2 and answer[0] == answer[-1] and answer[0] in "\"'":
+        answer = answer[1:-1].strip()
+
+    # Reject obvious failure messages.
+    lowered = answer.lower()
+    if lowered.startswith("unfortunately") or lowered.startswith("i was unable"):
+        return ""
+
+    return answer
+
+
+class BasicAgent:
+    """Full GAIA agent with search, web, and multimodal file tools."""
+
+    def __init__(self):
+        model_id = os.getenv("HF_MODEL_ID", "Qwen/Qwen2.5-7B-Instruct")
+        token = os.getenv("HF_TOKEN")
+
+        model = InferenceClientModel(model_id=model_id, token=token)
+        wiki_tool = WikipediaSearchTool(
+            user_agent="HF-Agents-Course-Student (https://huggingface.co/agents-course)",
+            language="en",
+            content_type="text",
+        )
+
+        toolset = [
+            wiki_tool,
+            WebSearchTool(max_results=8),
+            VisitWebpageTool(max_output_length=30000),
+            *build_custom_tools(),
+        ]
+
+        self.agent = CodeAgent(
+            tools=toolset,
+            model=model,
+            max_steps=int(os.getenv("AGENT_MAX_STEPS", "25")),
+            verbosity_level=int(os.getenv("AGENT_VERBOSITY", "0")),
+            additional_authorized_imports=["re", "json", "math"],
+        )
+        tool_names = [getattr(t, "name", str(t)) for t in toolset]
+        print(f"BasicAgent initialized (model={model_id}, tools={tool_names}).")
+
+    def __call__(
+        self,
+        question: str,
+        task_id: str | None = None,
+        file_path: str | Path | None = None,
+    ) -> str:
+        print(f"Agent received question (first 50 chars): {question[:50]}...")
+        if file_path:
+            print(f"Attached file: {file_path}")
+
+        question = maybe_unreverse(question)
+        path = Path(file_path) if file_path else None
+        task = f"{ANSWER_INSTRUCTIONS.strip()}\n\nQuestion:\n{question}"
+        task += file_context_block(path)
+
+        raw = self.agent.run(task)
+        answer = normalize_answer(raw)
+        if not answer:
+            print("Agent did not produce a final answer (max steps or empty result).")
+            answer = "UNKNOWN"
+        print(f"Agent returning answer: {answer[:120]}...")
+        return answer

app.py

@@ -1,24 +1,16 @@
 import os
+
 import gradio as gr
-import requests
-import inspect
 import pandas as pd
+import requests
+
+from agent import BasicAgent
+from files import download_task_file
 
 # (Keep Constants as is)
 # --- Constants ---
 DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
 
-# --- Basic Agent Definition ---
-# ----- THIS IS WERE YOU CAN BUILD WHAT YOU WANT ------
-class BasicAgent:
-    def __init__(self):
-        print("BasicAgent initialized.")
-    def __call__(self, question: str) -> str:
-        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
-
 def run_and_submit_all( profile: gr.OAuthProfile | None):
     """
     Fetches all questions, runs the BasicAgent on them, submits all answers,
@@ -76,11 +68,23 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
     for item in questions_data:
         task_id = item.get("task_id")
         question_text = item.get("question")
+        file_name = item.get("file_name") or ""
         if not task_id or question_text is None:
             print(f"Skipping item with missing task_id or question: {item}")
             continue
+        file_path = None
+        if file_name:
+            try:
+                file_path = download_task_file(task_id, file_name, api_url=api_url)
+                print(f"Downloaded attachment for {task_id}: {file_path}")
+            except Exception as e:
+                print(f"Error downloading file for task {task_id}: {e}")
         try:
-            submitted_answer = agent(question_text)
+            submitted_answer = agent(
+                question_text,
+                task_id=task_id,
+                file_path=file_path,
+            )
             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:

files.py

@@ -0,0 +1,134 @@
+"""Download and manage GAIA task attachments."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from functools import lru_cache
+from pathlib import Path
+
+import requests
+from huggingface_hub import hf_hub_download
+from huggingface_hub.errors import GatedRepoError, HfHubHTTPError
+
+DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+GAIA_REPO = "gaia-benchmark/GAIA"
+ATTACHMENTS_DIR = Path(os.getenv("GAIA_ATTACHMENTS_DIR", "task_files"))
+
+
+def ensure_attachments_dir() -> Path:
+    ATTACHMENTS_DIR.mkdir(parents=True, exist_ok=True)
+    return ATTACHMENTS_DIR
+
+
+def _copy_to_workspace(source: str | Path, file_name: str) -> Path:
+    dest_dir = ensure_attachments_dir()
+    dest_path = dest_dir / file_name
+    if Path(source).resolve() == dest_path.resolve():
+        return dest_path
+    shutil.copy2(source, dest_path)
+    return dest_path
+
+
+def _download_from_scoring_api(task_id: str, file_name: str, api_url: str) -> Path | None:
+    url = f"{api_url.rstrip('/')}/files/{task_id}"
+    response = requests.get(url, timeout=60)
+    if response.status_code == 404:
+        return None
+    response.raise_for_status()
+    dest_path = ensure_attachments_dir() / file_name
+    dest_path.write_bytes(response.content)
+    return dest_path
+
+
+@lru_cache(maxsize=256)
+def _gaia_relative_candidates(file_name: str) -> tuple[str, ...]:
+    """Common GAIA repo-relative paths for a given attachment name."""
+    return tuple(
+        {
+            f"2023/validation/{file_name}",
+            f"2023/test/{file_name}",
+            f"2023/level1/{file_name}",
+            file_name,
+        }
+    )
+
+
+def _download_from_gaia(file_name: str) -> Path | None:
+    token = os.getenv("HF_TOKEN")
+    last_error: Exception | None = None
+
+    for relative_path in _gaia_relative_candidates(file_name):
+        try:
+            cached = hf_hub_download(
+                repo_id=GAIA_REPO,
+                filename=relative_path,
+                repo_type="dataset",
+                token=token,
+            )
+            return _copy_to_workspace(cached, file_name)
+        except GatedRepoError as exc:
+            raise RuntimeError(
+                "GAIA dataset access required for file attachments. "
+                "Accept the terms at https://huggingface.co/datasets/gaia-benchmark/GAIA "
+                "and ensure HF_TOKEN is set on your Space."
+            ) from exc
+        except HfHubHTTPError as exc:
+            last_error = exc
+            continue
+
+    if last_error:
+        print(f"GAIA download failed for {file_name}: {last_error}")
+    return None
+
+
+def download_task_file(
+    task_id: str,
+    file_name: str,
+    api_url: str = DEFAULT_API_URL,
+) -> Path:
+    """Download a task attachment via scoring API or GAIA dataset fallback."""
+    if not file_name:
+        raise ValueError("file_name is required")
+
+    dest_path = ensure_attachments_dir() / file_name
+    if dest_path.exists() and dest_path.stat().st_size > 0:
+        return dest_path
+
+    from_api = _download_from_scoring_api(task_id, file_name, api_url)
+    if from_api is not None:
+        return from_api
+
+    from_gaia = _download_from_gaia(file_name)
+    if from_gaia is not None:
+        return from_gaia
+
+    raise FileNotFoundError(
+        f"Could not download attachment '{file_name}' for task {task_id}. "
+        "Scoring API returned 404; GAIA fallback also failed."
+    )
+
+
+def file_context_block(file_path: Path | None) -> str:
+    if file_path is None:
+        return ""
+    suffix = file_path.suffix.lower()
+    hints = {
+        ".png": "PNG image — use analyze_image.",
+        ".jpg": "JPEG image — use analyze_image.",
+        ".jpeg": "JPEG image — use analyze_image.",
+        ".webp": "WebP image — use analyze_image.",
+        ".mp3": "MP3 audio — use transcribe_audio.",
+        ".wav": "WAV audio — use transcribe_audio.",
+        ".xlsx": "Excel spreadsheet — use read_spreadsheet.",
+        ".xls": "Excel spreadsheet — use read_spreadsheet.",
+        ".csv": "CSV file — use read_spreadsheet.",
+        ".py": "Python script — use execute_python_file.",
+    }
+    hint = hints.get(suffix, "Use the appropriate file tool.")
+    return (
+        f"\n\nAttached file:\n"
+        f"- path: {file_path.resolve()}\n"
+        f"- name: {file_path.name}\n"
+        f"- hint: {hint}\n"
+    )

requirements.txt

@@ -1,2 +1,10 @@
-gradio
-requests
+gradio[oauth]
+requests
+pandas
+smolagents
+wikipedia-api
+markdownify
+openpyxl
+youtube-transcript-api
+Pillow
+datasets

tools.py

@@ -0,0 +1,182 @@
+"""Custom smolagents tools for GAIA multimodal and file tasks."""
+
+from __future__ import annotations
+
+import base64
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import pandas as pd
+from huggingface_hub import InferenceClient
+from smolagents import tool
+from youtube_transcript_api import YouTubeTranscriptApi
+
+
+def _hf_client() -> InferenceClient:
+    token = os.getenv("HF_TOKEN")
+    return InferenceClient(token=token)
+
+
+def _vision_model() -> str:
+    return os.getenv("HF_VISION_MODEL", "Qwen/Qwen2-VL-7B-Instruct")
+
+
+def _asr_model() -> str:
+    return os.getenv("HF_ASR_MODEL", "openai/whisper-large-v3")
+
+
+@tool
+def read_spreadsheet(file_path: str) -> str:
+    """Read an Excel or CSV file and return its contents as text for analysis.
+
+    Args:
+        file_path: Absolute or relative path to .xlsx, .xls, or .csv file.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return f"File not found: {file_path}"
+
+    suffix = path.suffix.lower()
+    if suffix == ".csv":
+        df = pd.read_csv(path)
+    elif suffix in {".xlsx", ".xls"}:
+        df = pd.read_excel(path)
+    else:
+        return f"Unsupported spreadsheet type: {suffix}"
+
+    buffer = []
+    buffer.append(f"Shape: {df.shape[0]} rows x {df.shape[1]} columns")
+    buffer.append(f"Columns: {', '.join(str(c) for c in df.columns)}")
+    buffer.append("\n--- data ---")
+    buffer.append(df.to_string(index=False))
+    text = "\n".join(buffer)
+    return text[:50000]
+
+
+@tool
+def execute_python_file(file_path: str) -> str:
+    """Execute a Python file in a subprocess and return stdout/stderr.
+
+    Args:
+        file_path: Path to a .py file to run.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return f"File not found: {file_path}"
+    if path.suffix.lower() != ".py":
+        return f"Not a Python file: {file_path}"
+
+    try:
+        completed = subprocess.run(
+            [sys.executable, str(path.resolve())],
+            capture_output=True,
+            text=True,
+            timeout=45,
+            cwd=str(path.parent.resolve()),
+        )
+    except subprocess.TimeoutExpired:
+        return "Execution timed out after 45 seconds."
+
+    parts = []
+    if completed.stdout:
+        parts.append(f"STDOUT:\n{completed.stdout}")
+    if completed.stderr:
+        parts.append(f"STDERR:\n{completed.stderr}")
+    parts.append(f"Exit code: {completed.returncode}")
+    return "\n".join(parts)[:20000]
+
+
+@tool
+def transcribe_audio(file_path: str) -> str:
+    """Transcribe speech from an audio file (mp3/wav) to text.
+
+    Args:
+        file_path: Path to the audio file.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return f"File not found: {file_path}"
+
+    client = _hf_client()
+    with path.open("rb") as audio_file:
+        result = client.automatic_speech_recognition(
+            audio=audio_file.read(),
+            model=_asr_model(),
+        )
+
+    if isinstance(result, dict):
+        return str(result.get("text", result))[:20000]
+    return str(getattr(result, "text", result))[:20000]
+
+
+@tool
+def analyze_image(file_path: str, question: str) -> str:
+    """Analyze an image file to answer a specific question about it.
+
+    Args:
+        file_path: Path to png/jpg/jpeg/webp image.
+        question: What to determine from the image.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return f"File not found: {file_path}"
+
+    mime = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp",
+    }.get(path.suffix.lower(), "image/png")
+
+    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
+    client = _hf_client()
+    response = client.chat_completion(
+        model=_vision_model(),
+        messages=[
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image_url", "image_url": {"url": f"data:{mime};base64,{encoded}"}},
+                    {"type": "text", "text": question},
+                ],
+            }
+        ],
+        max_tokens=1024,
+    )
+    return response.choices[0].message.content.strip()[:10000]
+
+
+@tool
+def get_youtube_transcript(video_url: str) -> str:
+    """Fetch the transcript/captions of a YouTube video.
+
+    Args:
+        video_url: Full YouTube URL or 11-character video ID.
+    """
+    match = re.search(
+        r"(?:youtube\.com/watch\?v=|youtu\.be/|youtube\.com/embed/)([A-Za-z0-9_-]{11})",
+        video_url,
+    )
+    video_id = match.group(1) if match else video_url.strip()
+
+    try:
+        api = YouTubeTranscriptApi()
+        fetched = api.fetch(video_id)
+        lines = [snippet.text for snippet in fetched.snippets]
+    except Exception as exc:
+        return f"Could not fetch transcript: {exc}"
+
+    return " ".join(lines)[:30000]
+
+
+def build_custom_tools() -> list:
+    return [
+        read_spreadsheet,
+        execute_python_file,
+        transcribe_audio,
+        analyze_image,
+        get_youtube_transcript,
+    ]