Add tools for files, math, multimodal and video

New tools in tools.py (all exposed via ALL_TOOLS):
- fetch_url, wikipedia_lookup: web/knowledge lookups
- download_task_file: pulls the file attached to a GAIA task_id
- read_pdf, read_excel, read_csv: parse attached documents
- python_exec, calculator: computation
- analyze_image: Llama 4 Scout VLM on local paths or URLs
- transcribe_audio: Whisper Turbo via Groq
- analyze_video: yt-dlp + ffmpeg frame sampling + VLM
- youtube_transcript: captions without downloading

app.py: BasicAgent binds ALL_TOOLS instead of just search_tool.
requirements.txt: add groq, pypdf, openpyxl, Wikipedia-API,
youtube-transcript-api, trafilatura, yt-dlp, imageio-ffmpeg;
drop unused langchain-community.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ryPUj8AtsFopnufGRSc4L

app.py

@@ -9,7 +9,7 @@ from typing import TypedDict, Annotated
 from langgraph.graph.message import add_messages
 from langgraph.graph import START, StateGraph
 from langchain_core.messages import AnyMessage, HumanMessage
-from tools import search_tool
+from tools import ALL_TOOLS
 from langgraph.prebuilt import tools_condition
 from langgraph.prebuilt import ToolNode
 
@@ -37,7 +37,7 @@ class BasicAgent:
         print("BasicAgent initialized.")
 
         # Requires GROQ_API_KEY in the environment (set as a Space secret on HF).
-        self.tools = [search_tool]
+        self.tools = ALL_TOOLS
         self.chat = ChatGroq(
             model="openai/gpt-oss-120b",
             temperature=0.1,

requirements.txt

@@ -3,8 +3,15 @@ requests
 pandas
 spaces
 tavily-python
+groq
+pypdf
+openpyxl
+Wikipedia-API
+youtube-transcript-api
+trafilatura
+yt-dlp
+imageio-ffmpeg
 langgraph
 langchain
 langchain-core
 langchain-groq
-langchain-community

tools.py

@@ -1,11 +1,23 @@
+import base64
+import math
 import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
 
+import requests
+from langchain_core.messages import HumanMessage
 from langchain_core.tools import tool
+from langchain_groq import ChatGroq
+from tavily import TavilyClient
 
 from agents import ResearchAgent
-from tavily import TavilyClient
 
-client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
+DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+
+tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
 
 
 @tool
@@ -16,20 +28,346 @@ def search_tool(query: str) -> str:
     Args:
         query: Search query.
     """
-    results = client.search(query=query, max_results=5, search_depth="basic")
+    results = tavily_client.search(query=query, max_results=5, search_depth="basic")
 
     output = []
-
     for r in results["results"]:
         output.append(f"""
 Title: {r['title']}
 URL: {r['url']}
 Content: {r['content']}
 """)
-
     return "\n".join(output)
 
 
+@tool
+def fetch_url(url: str) -> str:
+    """Fetch a web page and extract its main readable text.
+
+    Use this when a search snippet is not enough and you need the full page
+    content.
+
+    Args:
+        url: HTTP(S) URL.
+    """
+    import trafilatura
+
+    downloaded = trafilatura.fetch_url(url)
+    if not downloaded:
+        return f"Failed to fetch {url}"
+    text = trafilatura.extract(downloaded)
+    return text or "(no extractable content)"
+
+
+@tool
+def wikipedia_lookup(title: str) -> str:
+    """Fetch the summary of an English Wikipedia article.
+
+    More reliable than web search for historical facts, dates, and biographies.
+
+    Args:
+        title: Article title, e.g. "Marie Curie".
+    """
+    import wikipediaapi
+
+    wiki = wikipediaapi.Wikipedia(
+        user_agent="hf-agents-course-final/1.0 (batberni@gmail.com)",
+        language="en",
+    )
+    page = wiki.page(title)
+    if not page.exists():
+        return f"No Wikipedia page found for '{title}'"
+    return f"{page.summary}\n\nURL: {page.fullurl}"
+
+
+@tool
+def download_task_file(task_id: str) -> str:
+    """Download the file attached to a task from the HF agents course API.
+
+    Many evaluation questions come with an attached file (image, audio, pdf,
+    xlsx, csv, ...). Call this first to get a local path, then pass that path
+    to read_pdf / read_excel / analyze_image / transcribe_audio, etc.
+
+    Args:
+        task_id: The task_id from the questions endpoint.
+
+    Returns:
+        The local file path where the file was saved.
+    """
+    url = f"{DEFAULT_API_URL}/files/{task_id}"
+    resp = requests.get(url, timeout=30)
+    resp.raise_for_status()
+
+    cd = resp.headers.get("Content-Disposition", "")
+    m = re.search(r'filename="?([^"]+)"?', cd)
+    filename = m.group(1) if m else task_id
+
+    path = Path(tempfile.gettempdir()) / filename
+    path.write_bytes(resp.content)
+    return str(path)
+
+
+@tool
+def read_pdf(path: str) -> str:
+    """Extract text content from a PDF file.
+
+    Args:
+        path: Local file path to the PDF.
+    """
+    from pypdf import PdfReader
+
+    reader = PdfReader(path)
+    return "\n".join(page.extract_text() or "" for page in reader.pages)
+
+
+@tool
+def read_excel(path: str, sheet: str | None = None) -> str:
+    """Read an Excel workbook and return its contents as text.
+
+    Args:
+        path: Local path to .xlsx / .xls file.
+        sheet: Optional sheet name. Omit to dump every sheet.
+    """
+    import pandas as pd
+
+    if sheet:
+        return pd.read_excel(path, sheet_name=sheet).to_string()
+    sheets = pd.read_excel(path, sheet_name=None)
+    return "\n\n".join(
+        f"=== {name} ===\n{df.to_string()}" for name, df in sheets.items()
+    )
+
+
+@tool
+def read_csv(path: str) -> str:
+    """Read a CSV file and return its contents as text.
+
+    Args:
+        path: Local path to .csv file.
+    """
+    import pandas as pd
+
+    return pd.read_csv(path).to_string()
+
+
+@tool
+def python_exec(code: str) -> str:
+    """Execute Python code in a subprocess and return stdout (and stderr).
+
+    Use this for arithmetic on lists, date math, pandas manipulations, parsing,
+    or anything that is easier to *compute* than to reason about. You must
+    `print(...)` any value you want to see back.
+
+    Available: the standard library plus pandas, numpy (if installed in the env).
+
+    Args:
+        code: Python source to execute.
+    """
+    try:
+        result = subprocess.run(
+            [sys.executable, "-c", code],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        out = result.stdout
+        if result.stderr:
+            out += f"\n[stderr]\n{result.stderr}"
+        return out.strip() or "(no output)"
+    except subprocess.TimeoutExpired:
+        return "(timeout after 30s)"
+
+
+_CALC_ENV = {
+    name: getattr(math, name) for name in dir(math) if not name.startswith("_")
+}
+_CALC_ENV.update({"abs": abs, "round": round, "min": min, "max": max, "sum": sum})
+
+
+@tool
+def calculator(expression: str) -> str:
+    """Evaluate a math expression.
+
+    Supports +, -, *, /, //, %, **, parentheses, and the math module
+    (sin, cos, sqrt, log, pi, e, ...). No variables, no assignment.
+
+    Args:
+        expression: e.g. "2 * (3 + 4) ** 0.5" or "sqrt(2) + log(10)".
+    """
+    try:
+        return str(eval(expression, {"__builtins__": {}}, _CALC_ENV))
+    except Exception as e:
+        return f"Error: {e}"
+
+
+_IMAGE_MIME = {
+    "jpg": "jpeg",
+    "jpeg": "jpeg",
+    "png": "png",
+    "gif": "gif",
+    "webp": "webp",
+    "bmp": "bmp",
+}
+
+
+@tool
+def analyze_image(image_path_or_url: str, question: str) -> str:
+    """Answer a question about an image using a vision-language model.
+
+    Handles both local files and http(s) URLs. Use this for chess positions,
+    charts, screenshots, photos, diagrams, etc.
+
+    Args:
+        image_path_or_url: Local file path or HTTP(S) URL.
+        question: What you want to know about the image.
+    """
+    if image_path_or_url.startswith(("http://", "https://")):
+        image_url = image_path_or_url
+    else:
+        with open(image_path_or_url, "rb") as f:
+            b64 = base64.b64encode(f.read()).decode()
+        ext = image_path_or_url.rsplit(".", 1)[-1].lower()
+        mime = _IMAGE_MIME.get(ext, "jpeg")
+        image_url = f"data:image/{mime};base64,{b64}"
+
+    vlm = ChatGroq(
+        model="meta-llama/llama-4-scout-17b-16e-instruct",
+        temperature=0.1,
+        api_key=os.getenv("GROQ_API_KEY"),
+    )
+    msg = HumanMessage(
+        content=[
+            {"type": "text", "text": question},
+            {"type": "image_url", "image_url": {"url": image_url}},
+        ]
+    )
+    return vlm.invoke([msg]).content
+
+
+@tool
+def transcribe_audio(audio_path: str) -> str:
+    """Transcribe an audio file to text with Whisper (Groq).
+
+    Args:
+        audio_path: Local file path to the audio (mp3, wav, m4a, flac, ...).
+    """
+    from groq import Groq
+
+    client = Groq(api_key=os.getenv("GROQ_API_KEY"))
+    with open(audio_path, "rb") as f:
+        transcription = client.audio.transcriptions.create(
+            file=(os.path.basename(audio_path), f.read()),
+            model="whisper-large-v3-turbo",
+        )
+    return transcription.text
+
+
+@tool
+def analyze_video(url_or_path: str, question: str, num_frames: int = 5) -> str:
+    """Answer a question about a video by sampling frames and asking a VLM.
+
+    Downloads the video if a URL is given (YouTube supported), samples frames
+    evenly along its duration, and asks the vision model. Pair with
+    ``youtube_transcript`` for full audio+visual understanding.
+
+    Args:
+        url_or_path: YouTube URL, other video URL, or local file path.
+        question: What you want to know about the video.
+        num_frames: How many frames to sample (default 5, max 5).
+    """
+    from imageio_ffmpeg import get_ffmpeg_exe
+
+    num_frames = max(1, min(num_frames, 5))
+    tmpdir = Path(tempfile.mkdtemp())
+
+    if url_or_path.startswith(("http://", "https://")):
+        import yt_dlp
+
+        video_path = str(tmpdir / "video.mp4")
+        ydl_opts = {
+            "outtmpl": video_path,
+            "format": "worst[ext=mp4]/worst",
+            "quiet": True,
+            "no_warnings": True,
+        }
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            ydl.download([url_or_path])
+    else:
+        video_path = url_or_path
+
+    ffmpeg = get_ffmpeg_exe()
+    probe = subprocess.run([ffmpeg, "-i", video_path], capture_output=True, text=True)
+    dur_match = re.search(r"Duration: (\d+):(\d+):(\d+)", probe.stderr)
+    if dur_match:
+        h, m, s = map(int, dur_match.groups())
+        duration = max(1, h * 3600 + m * 60 + s)
+    else:
+        duration = 30
+
+    frames_b64 = []
+    for i in range(num_frames):
+        t = duration * (i + 0.5) / num_frames
+        frame_path = tmpdir / f"frame_{i}.jpg"
+        subprocess.run(
+            [
+                ffmpeg,
+                "-y",
+                "-ss",
+                str(t),
+                "-i",
+                video_path,
+                "-vframes",
+                "1",
+                "-q:v",
+                "3",
+                str(frame_path),
+            ],
+            capture_output=True,
+        )
+        if frame_path.exists():
+            b64 = base64.b64encode(frame_path.read_bytes()).decode()
+            frames_b64.append(f"data:image/jpeg;base64,{b64}")
+
+    if not frames_b64:
+        return "Failed to extract any frames from the video."
+
+    vlm = ChatGroq(
+        model="meta-llama/llama-4-scout-17b-16e-instruct",
+        temperature=0.1,
+        api_key=os.getenv("GROQ_API_KEY"),
+    )
+    content = [
+        {
+            "type": "text",
+            "text": f"Below are {len(frames_b64)} frames sampled evenly from a "
+            f"video (duration ~{duration}s). {question}",
+        }
+    ]
+    for url in frames_b64:
+        content.append({"type": "image_url", "image_url": {"url": url}})
+    return vlm.invoke([HumanMessage(content=content)]).content
+
+
+@tool
+def youtube_transcript(url_or_id: str) -> str:
+    """Fetch the transcript of a YouTube video.
+
+    Falls back gracefully when captions are unavailable.
+
+    Args:
+        url_or_id: Full YouTube URL or the 11-char video id.
+    """
+    from youtube_transcript_api import YouTubeTranscriptApi
+
+    m = re.search(r"(?:v=|youtu\.be/|/shorts/|/embed/)([0-9A-Za-z_-]{11})", url_or_id)
+    video_id = m.group(1) if m else url_or_id
+    try:
+        entries = YouTubeTranscriptApi.get_transcript(video_id)
+    except Exception as e:
+        return f"No transcript available for {video_id}: {e}"
+    return " ".join(e["text"] for e in entries)
+
+
 research_agent = ResearchAgent()
 
 
@@ -46,3 +384,21 @@ def research(request: str) -> str:
     Prize in Physics?')
     """
     return research_agent(request)
+
+
+ALL_TOOLS = [
+    search_tool,
+    fetch_url,
+    wikipedia_lookup,
+    download_task_file,
+    read_pdf,
+    read_excel,
+    read_csv,
+    python_exec,
+    calculator,
+    analyze_image,
+    analyze_video,
+    transcribe_audio,
+    youtube_transcript,
+    search_tool,
+]