Upload 5 files

README.md

@@ -12,4 +12,53 @@ hf_oauth: true
 hf_oauth_expiration_minutes: 480
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Agent
+
+`agent.py` defines `GaiaAgent`, a LangGraph agent (explicit `StateGraph` with an
+`assistant` node and a `ToolNode`, routed by `tools_condition`) used to answer the
+GAIA benchmark questions for [Unit 4's hands-on assignment](https://huggingface.co/learn/agents-course/unit4/hands-on).
+Structure and prompt are adapted from the [fisherman611/gaia-agent](https://huggingface.co/spaces/fisherman611/gaia-agent)
+Space, trimmed to tools that need no extra paid API keys and no arbitrary code
+execution (that Space's Supabase RAG retriever, Tavily/Groq providers, and
+multi-language code interpreter were left out for that reason).
+
+It calls an LLM through the Hugging Face Inference API and has access to:
+web search (DuckDuckGo), Wikipedia search, arXiv search, arithmetic tools
+(add/subtract/multiply/divide/modulus/power/square_root), a tool to download a
+GAIA task's attached file, a generic URL downloader, and CSV/Excel analysis
+tools. The system prompt (`system_prompt.txt`) asks the model to end its reply
+with `FINAL ANSWER: ...`, which `agent.py` parses out before submission — per
+the assignment's rule that submitted answers must contain only the answer
+itself.
+
+To run it (locally or as a Space), set the `HF_TOKEN` secret/env var to a
+Hugging Face access token with Inference API permission. Optionally set
+`HF_AGENT_MODEL` to override the default model
+(`meta-llama/Llama-3.1-8B-Instruct`), and `HF_AGENT_PROVIDER` to override the
+default Inference Provider (`deepinfra`) — pinned explicitly because the
+router's `auto` selection can land on a provider that doesn't support tool
+calling for a given model (HTTP 422 `UNSUPPORTED_OPENAI_PARAMS`), and not every
+provider hosts every model (HTTP 4xx "Model ... is not supported by provider
+..."). Check `https://router.huggingface.co/v1/models/<repo_id>` to see which
+providers host a given model and whether they support tools before changing
+either variable.
+
+The default 8B model was chosen for cost, not accuracy: the HF free tier only
+includes $0.10/month of Inference Provider credits, and a 70B model burns
+through that almost instantly across a full GAIA run. If you have more budget
+(pre-paid credits or PRO), switch to a larger model such as
+`meta-llama/Llama-3.3-70B-Instruct` on the `together` provider for more
+reliable reasoning on harder questions.
+
+### Using Claude instead
+
+Set `LLM_PROVIDER=anthropic` and `ANTHROPIC_API_KEY` (from
+[console.anthropic.com](https://console.anthropic.com), pay-as-you-go billing —
+no fixed free monthly allowance like HF's) to run the agent on Claude instead.
+Optionally set `ANTHROPIC_MODEL` to override the default (`claude-haiku-4-5`,
+picked for its low cost across many tool-calling round trips per question);
+`claude-sonnet-5` trades cost for stronger reasoning on harder questions.
+Claude's native tool calling is also more reliable than the HF router, which
+can silently route to a provider that doesn't support the `tools` param.

agent.py

@@ -1,163 +1,319 @@
-"""LangGraph Agent"""
+"""LangGraph agent that answers GAIA benchmark questions (Hugging Face Agents Course, Unit 4).
+
+The agent is a LangGraph ReAct-style graph: an LLM served through the Hugging Face
+Inference API, bound to a toolset (web/Wikipedia/arXiv search, arithmetic, GAIA
+task-file download, and CSV/Excel analysis). Structure and prompt are adapted from
+https://huggingface.co/spaces/fisherman611/gaia-agent, trimmed to tools that need no
+extra paid API keys and no arbitrary code execution. See
+https://huggingface.co/learn/agents-course/unit4/hands-on for the assignment.
+"""
+
 import os
 import re
-from dotenv import load_dotenv
-from langgraph.graph import START, StateGraph, MessagesState
-from langgraph.prebuilt import tools_condition
-from langgraph.prebuilt import ToolNode
-from langchain_google_genai import ChatGoogleGenerativeAI
-from langchain_groq import ChatGroq
-from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+import pandas as pd
+import requests
+from langchain_community.document_loaders import ArxivLoader, WikipediaLoader
 from langchain_community.tools import DuckDuckGoSearchRun
-from langchain_community.document_loaders import WikipediaLoader
-from langchain_community.document_loaders import ArxivLoader
-from langchain_core.messages import SystemMessage
+from langchain_core.messages import HumanMessage, SystemMessage
 from langchain_core.tools import tool
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+from langgraph.graph import START, MessagesState, StateGraph
+from langgraph.prebuilt import ToolNode, tools_condition
+
+DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+
+# "huggingface" (default, needs only HF_TOKEN) or "anthropic" (needs ANTHROPIC_API_KEY,
+# paid - https://console.anthropic.com). Anthropic's native tool calling is more reliable
+# than the HF router's per-provider variance, at the cost of no free tier.
+LLM_PROVIDER = os.getenv("LLM_PROVIDER", "huggingface")
 
-load_dotenv()
+# Any HF Inference API model that supports tool calling works here. Override via the
+# HF_AGENT_MODEL env var without touching code. Llama-3.1-8B-Instruct is ~15x cheaper per
+# token than the 70B default it replaced - picked to fit the free tier's tiny $0.10/month
+# Inference Provider credit allowance; swap to a larger model (e.g.
+# meta-llama/Llama-3.3-70B-Instruct on the "together" provider) once you have more budget
+# for better reasoning on harder GAIA questions.
+HF_MODEL_REPO_ID = os.getenv("HF_AGENT_MODEL", "meta-llama/Llama-3.1-8B-Instruct")
+
+# Left unset ("auto"), the HF router picks whichever provider is cheapest/fastest for the
+# model, and some of those don't support the `tools` param at all (HTTP 422
+# UNSUPPORTED_OPENAI_PARAMS). Pin one that reliably supports tool calling; override via
+# HF_AGENT_PROVIDER if it doesn't happen to host HF_AGENT_MODEL.
+HF_MODEL_PROVIDER = os.getenv("HF_AGENT_PROVIDER", "deepinfra")
+
+# Cheapest current Claude model - a good fit for an agent that makes many tool-calling
+# round trips per question. Override via ANTHROPIC_MODEL (e.g. "claude-sonnet-5" for
+# stronger reasoning on harder questions, at higher cost).
+ANTHROPIC_MODEL = os.getenv("ANTHROPIC_MODEL", "claude-haiku-4-5")
+
+with open(Path(__file__).parent / "system_prompt.txt", "r", encoding="utf-8") as f:
+    SYSTEM_PROMPT = f.read()
 
 _FINAL_ANSWER_RE = re.compile(r"final answer\s*:\s*", re.IGNORECASE)
 
 
-def extract_final_answer(text: str) -> str:
-    """Strip the `FINAL ANSWER:` prefix the system prompt asks the model for."""
-    match = _FINAL_ANSWER_RE.search(text)
-    answer = text[match.end():] if match else text
-    return answer.strip()
+### =============== SEARCH TOOLS =============== ###
 
 
 @tool
-def multiply(a: int, b: int) -> int:
-    """Multiply two numbers.
+def web_search(query: str) -> str:
+    """Search the web (DuckDuckGo) for a query and return a few results.
+
     Args:
-        a: first int
-        b: second int
+        query: The search query.
     """
-    return a * b
+    return DuckDuckGoSearchRun().invoke(query)
+
+
+@tool
+def wiki_search(query: str) -> str:
+    """Search Wikipedia for a query and return up to 2 results.
+
+    Args:
+        query: The search query.
+    """
+    docs = WikipediaLoader(query=query, load_max_docs=2).load()
+    return "\n\n---\n\n".join(
+        f'<Document source="{d.metadata.get("source", "")}"/>\n{d.page_content}\n</Document>'
+        for d in docs
+    )
+
 
 @tool
-def add(a: int, b: int) -> int:
+def arxiv_search(query: str) -> str:
+    """Search arXiv for a query and return up to 2 results (abstracts truncated).
+
+    Args:
+        query: The search query.
+    """
+    docs = ArxivLoader(query=query, load_max_docs=2).load()
+    return "\n\n---\n\n".join(
+        f'<Document source="{d.metadata.get("source", "")}"/>\n{d.page_content[:1000]}\n</Document>'
+        for d in docs
+    )
+
+
+### =============== MATH TOOLS =============== ###
+
+
+@tool
+def add(a: float, b: float) -> float:
     """Add two numbers.
 
     Args:
-        a: first int
-        b: second int
+        a: the first number
+        b: the second number
     """
     return a + b
 
+
 @tool
-def subtract(a: int, b: int) -> int:
+def subtract(a: float, b: float) -> float:
     """Subtract two numbers.
 
     Args:
-        a: first int
-        b: second int
+        a: the first number
+        b: the second number
     """
     return a - b
 
+
 @tool
-def divide(a: int, b: int) -> float:
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers.
+
+    Args:
+        a: the first number
+        b: the second number
+    """
+    return a * b
+
+
+@tool
+def divide(a: float, b: float) -> float:
     """Divide two numbers.
 
     Args:
-        a: first int
-        b: second int
+        a: the numerator
+        b: the denominator
     """
     if b == 0:
         raise ValueError("Cannot divide by zero.")
     return a / b
 
+
 @tool
 def modulus(a: int, b: int) -> int:
-    """Get the modulus of two numbers.
+    """Get the remainder of a divided by b.
 
     Args:
-        a: first int
-        b: second int
+        a: the first number
+        b: the second number
     """
     return a % b
 
+
 @tool
-def wiki_search(query: str) -> str:
-    """Search Wikipedia for a query and return maximum 2 results.
+def power(a: float, b: float) -> float:
+    """Raise a to the power of b.
 
     Args:
-        query: The search query."""
-    search_docs = WikipediaLoader(query=query, load_max_docs=2).load()
-    return "\n\n---\n\n".join(
-        f'<Document source="{doc.metadata.get("source", "")}"/>\n{doc.page_content}\n</Document>'
-        for doc in search_docs
-    )
+        a: the base
+        b: the exponent
+    """
+    return a**b
+
 
 @tool
-def web_search(query: str) -> str:
-    """Search the web (DuckDuckGo) for a query and return a few results.
+def square_root(a: float) -> float:
+    """Get the square root of a non-negative number.
 
     Args:
-        query: The search query."""
-    return DuckDuckGoSearchRun().invoke(query)
+        a: the number to get the square root of
+    """
+    if a < 0:
+        raise ValueError("Cannot take the square root of a negative number.")
+    return a**0.5
+
+
+### =============== FILE TOOLS =============== ###
+
+
+@tool
+def download_task_file(task_id: str) -> str:
+    """Download the file attached to a GAIA task (if any) and return its text content.
+
+    Only useful when the question references an attached file. Pass the task's task_id.
+    Returns decoded text (truncated to 4000 characters) for text-like files, or a short
+    description (content type and size) for files that can't be decoded as text.
+    """
+    try:
+        response = requests.get(f"{DEFAULT_API_URL}/files/{task_id}", timeout=30)
+        response.raise_for_status()
+    except requests.exceptions.RequestException as e:
+        return f"Error downloading file for task {task_id}: {e}"
+
+    try:
+        return response.content.decode("utf-8")[:4000]
+    except UnicodeDecodeError:
+        content_type = response.headers.get("content-type", "unknown")
+        return (
+            f"File for task {task_id} is binary (content-type: {content_type}, "
+            f"{len(response.content)} bytes) and cannot be read as text."
+        )
+
 
 @tool
-def arvix_search(query: str) -> str:
-    """Search Arxiv for a query and return maximum 3 result.
+def download_file_from_url(url: str, filename: Optional[str] = None) -> str:
+    """Download a file from a URL to a temporary path, for later analysis.
 
     Args:
-        query: The search query."""
-    search_docs = ArxivLoader(query=query, load_max_docs=3).load()
-    return "\n\n---\n\n".join(
-        f'<Document source="{doc.metadata.get("source", "")}"/>\n{doc.page_content[:1000]}\n</Document>'
-        for doc in search_docs
-    )
+        url: the URL of the file to download.
+        filename: optional filename to save as; a random one is used if omitted.
+    """
+    try:
+        if not filename:
+            filename = os.path.basename(urlparse(url).path) or f"downloaded_{uuid.uuid4().hex[:8]}"
+        filepath = os.path.join(tempfile.gettempdir(), filename)
+        response = requests.get(url, stream=True, timeout=30)
+        response.raise_for_status()
+        with open(filepath, "wb") as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                f.write(chunk)
+        return f"File downloaded to {filepath}."
+    except Exception as e:
+        return f"Error downloading file: {e}"
 
 
-# load the system prompt from the file
-with open("system_prompt.txt", "r", encoding="utf-8") as f:
-    system_prompt = f.read()
-
-# System message
-sys_msg = SystemMessage(content=system_prompt)
-
-tools = [
-    multiply,
-    add,
-    subtract,
-    divide,
-    modulus,
-    wiki_search,
-    web_search,
-    arvix_search,
-]
-
-# Build graph function
-def build_graph(provider: str = "google"):
-    """Build the graph"""
-    if provider == "google":
-        # Google Gemini - needs GOOGLE_API_KEY
-        llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash", temperature=0)
-    elif provider == "groq":
-        # Groq https://console.groq.com/docs/models - needs GROQ_API_KEY
-        llm = ChatGroq(model="llama-3.3-70b-versatile", temperature=0)
-    elif provider == "huggingface":
-        # HF Inference Providers - needs HF_TOKEN. "auto" provider selection can land on a
-        # backend that doesn't support tool calling, so pin one that does (override via
-        # HF_AGENT_PROVIDER if it doesn't happen to host HF_AGENT_MODEL).
-        llm = ChatHuggingFace(
-            llm=HuggingFaceEndpoint(
-                repo_id=os.getenv("HF_AGENT_MODEL", "meta-llama/Llama-3.1-8B-Instruct"),
-                provider=os.getenv("HF_AGENT_PROVIDER", "deepinfra"),
-                huggingfacehub_api_token=os.getenv("HF_TOKEN"),
-                temperature=0,
-                max_new_tokens=1024,
-            ),
+@tool
+def analyze_csv_file(file_path: str) -> str:
+    """Load a CSV file and return its shape, columns, and summary statistics.
+
+    Args:
+        file_path: path to the CSV file (e.g. from download_file_from_url).
+    """
+    try:
+        df = pd.read_csv(file_path)
+        return (
+            f"{len(df)} rows, {len(df.columns)} columns.\n"
+            f"Columns: {', '.join(df.columns)}\n\n"
+            f"Summary statistics:\n{df.describe(include='all')}"
         )
-    else:
-        raise ValueError("Invalid provider. Choose 'google', 'groq' or 'huggingface'.")
-    # Bind tools to LLM
-    llm_with_tools = llm.bind_tools(tools)
+    except Exception as e:
+        return f"Error analyzing CSV file: {e}"
+
+
+@tool
+def analyze_excel_file(file_path: str) -> str:
+    """Load an Excel file and return its shape, columns, and summary statistics.
+
+    Args:
+        file_path: path to the .xlsx/.xls file (e.g. from download_file_from_url).
+    """
+    try:
+        df = pd.read_excel(file_path)
+        return (
+            f"{len(df)} rows, {len(df.columns)} columns.\n"
+            f"Columns: {', '.join(df.columns)}\n\n"
+            f"Summary statistics:\n{df.describe(include='all')}"
+        )
+    except Exception as e:
+        return f"Error analyzing Excel file: {e}"
+
+
+def _build_tools():
+    return [
+        web_search,
+        wiki_search,
+        arxiv_search,
+        add,
+        subtract,
+        multiply,
+        divide,
+        modulus,
+        power,
+        square_root,
+        download_task_file,
+        download_file_from_url,
+        analyze_csv_file,
+        analyze_excel_file,
+    ]
+
+
+def _build_llm():
+    if LLM_PROVIDER == "anthropic":
+        from langchain_anthropic import ChatAnthropic
+
+        return ChatAnthropic(
+            model=ANTHROPIC_MODEL,
+            api_key=os.getenv("ANTHROPIC_API_KEY"),
+            temperature=0,
+            max_tokens=1024,
+        )
+    if LLM_PROVIDER == "huggingface":
+        endpoint = HuggingFaceEndpoint(
+            repo_id=HF_MODEL_REPO_ID,
+            provider=HF_MODEL_PROVIDER,
+            huggingfacehub_api_token=os.getenv("HF_TOKEN"),
+            temperature=0,
+            max_new_tokens=1024,
+        )
+        return ChatHuggingFace(llm=endpoint)
+    raise ValueError(f"Unknown LLM_PROVIDER: {LLM_PROVIDER!r}. Use 'huggingface' or 'anthropic'.")
+
+
+def build_graph():
+    """Build the compiled LangGraph agent graph."""
+    tools = _build_tools()
+    llm_with_tools = _build_llm().bind_tools(tools)
 
-    # Node
     def assistant(state: MessagesState):
-        """Assistant node"""
         return {"messages": [llm_with_tools.invoke(state["messages"])]}
 
     builder = StateGraph(MessagesState)
@@ -167,5 +323,47 @@ def build_graph(provider: str = "google"):
     builder.add_conditional_edges("assistant", tools_condition)
     builder.add_edge("tools", "assistant")
 
-    # Compile graph
     return builder.compile()
+
+
+def _extract_final_answer(text: str) -> str:
+    match = _FINAL_ANSWER_RE.search(text)
+    answer = text[match.end():] if match else text
+    answer = answer.strip()
+    if len(answer) >= 2 and answer[0] == answer[-1] and answer[0] in "\"'":
+        answer = answer[1:-1].strip()
+    return answer
+
+
+class GaiaAgent:
+    """A LangGraph ReAct agent (HF Inference API LLM + tools) for GAIA questions."""
+
+    def __init__(self):
+        self._graph = build_graph()
+        print("GaiaAgent initialized.")
+
+    def __call__(self, question: str, task_id: Optional[str] = None) -> str:
+        print(f"Agent received question (first 80 chars): {question[:80]}...")
+
+        user_content = question
+        if task_id:
+            user_content += (
+                f"\n\n(task_id: {task_id} - use download_task_file if a file is attached)"
+            )
+
+        try:
+            result = self._graph.invoke(
+                {
+                    "messages": [
+                        SystemMessage(content=SYSTEM_PROMPT),
+                        HumanMessage(content=user_content),
+                    ]
+                }
+            )
+            answer = _extract_final_answer(result["messages"][-1].content)
+        except Exception as e:
+            print(f"Agent error: {e}")
+            answer = f"AGENT ERROR: {e}"
+
+        print(f"Agent returning answer (first 80 chars): {answer[:80]}...")
+        return answer

app.py

@@ -1,40 +1,24 @@
-""" Basic Agent Evaluation Runner"""
 import os
-import inspect
 import gradio as gr
 import requests
+import inspect
 import pandas as pd
-from langchain_core.messages import HumanMessage
-from agent import build_graph, sys_msg, extract_final_answer
-
-
-
-# (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 ------
-
+import spaces
 
-class BasicAgent:
-    """A langgraph agent."""
-    def __init__(self):
-        print("BasicAgent initialized.")
-        self.graph = build_graph()
+from agent import GaiaAgent, DEFAULT_API_URL
 
-    def __call__(self, question: str) -> str:
-        print(f"Agent received question (first 50 chars): {question[:50]}...")
-        messages = [sys_msg, HumanMessage(content=question)]
-        result = self.graph.invoke({"messages": messages})
-        answer = extract_final_answer(result['messages'][-1].content)
-        return answer
 
+@spaces.GPU
+def _zerogpu_probe():
+    """Unused - satisfies this Space's ZeroGPU hardware requirement for a @spaces.GPU
+    function to exist at startup. The agent itself only calls the HF Inference API and
+    never needs a local GPU, so this is never invoked."""
+    return True
 
 
 def run_and_submit_all( profile: gr.OAuthProfile | None):
     """
-    Fetches all questions, runs the BasicAgent on them, submits all answers,
+    Fetches all questions, runs the GaiaAgent on them, submits all answers,
     and displays the results.
     """
     # --- Determine HF Space Runtime URL and Repo URL ---
@@ -53,7 +37,7 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
 
     # 1. Instantiate Agent ( modify this part to create your agent)
     try:
-        agent = BasicAgent()
+        agent = GaiaAgent()
     except Exception as e:
         print(f"Error instantiating agent: {e}")
         return f"Error initializing agent: {e}", None
@@ -93,7 +77,7 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
             print(f"Skipping item with missing task_id or question: {item}")
             continue
         try:
-            submitted_answer = agent(question_text)
+            submitted_answer = agent(question_text, task_id=task_id)
             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:
@@ -192,7 +176,7 @@ if __name__ == "__main__":
 
     if space_host_startup:
         print(f"✅ SPACE_HOST found: {space_host_startup}")
-        print(f"   Runtime URL should be: https://{space_host_startup}.hf.space")
+        print(f"   Runtime URL should be: https://{space_host_startup}")
     else:
         print("ℹ️  SPACE_HOST environment variable not found (running locally?).")
 
@@ -206,4 +190,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(ssr_mode=False, debug=True, share=False)

requirements.txt

@@ -1,14 +1,14 @@
 gradio
+itsdangerous
 requests
+spaces
 pandas
-langchain-community
+langgraph
 langchain-core
-langchain-google-genai
 langchain-huggingface
-langchain-groq
-langgraph
-huggingface_hub
+langchain-community
+langchain-anthropic
 duckduckgo-search
-arxiv
 wikipedia
-python-dotenv
+arxiv
+openpyxl

system_prompt.txt

@@ -1,15 +1,5 @@
 You are a helpful assistant tasked with answering questions using a set of tools.
-
-Your final answer must strictly follow this format:
-FINAL ANSWER: [ANSWER]
-
-Only write the answer in that exact format. Do not explain anything. Do not include any other text.
-
-Use the available tools whenever you need external information or computation to answer.
-
-Examples:
-- FINAL ANSWER: FunkMonk
-- FINAL ANSWER: Paris
-- FINAL ANSWER: 128
-
-If you do not follow this format exactly, your response will be considered incorrect.
+Now, I will ask you a question. Report your thoughts, and finish your answer with the following template:
+FINAL ANSWER: [YOUR FINAL ANSWER].
+YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, don't use comma to write your number neither use units such as $ or percent sign unless specified otherwise. If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities), and write the digits in plain text unless specified otherwise. If you are asked for a comma separated list, apply the rules above for each element (number or string), and ensure there is exactly one space after each comma.
+Your answer should only start with "FINAL ANSWER: ", then follows with the answer.