initial

.gitignore

@@ -0,0 +1,176 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+.DS_Store

agent.py

@@ -0,0 +1,146 @@
+from typing import TypedDict, Annotated
+import os
+from langgraph.graph.message import add_messages
+from langchain_core.messages import AnyMessage, HumanMessage, AIMessage, SystemMessage
+from langgraph.prebuilt import ToolNode
+from langgraph.graph import START, StateGraph
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.prebuilt import tools_condition
+from langchain_huggingface import HuggingFaceEndpoint, ChatHuggingFace
+from tools import agent_tools
+from utils import format_gaia_answer, analyze_question_type, create_execution_plan, log_agent_step
+
+# Initialize LLM (same as unit3)
+llm = HuggingFaceEndpoint(
+    repo_id="Qwen/Qwen2.5-Coder-32B-Instruct",
+    huggingfacehub_api_token=os.environ.get("HUGGINGFACE_API_TOKEN"),
+    temperature=0.1,
+    max_new_tokens=1024,
+)
+
+chat = ChatHuggingFace(llm=llm, verbose=True)
+chat_with_tools = chat.bind_tools(agent_tools)
+
+# System prompt for intelligent question answering
+SYSTEM_PROMPT = """You are a highly capable AI assistant designed to answer questions accurately and helpfully.
+
+Your approach should include:
+- Multi-step reasoning and planning for complex questions
+- Intelligent tool usage when needed for web search, file processing, calculations, and analysis
+- Precise, factual answers based on reliable information
+- Breaking down complex questions into manageable steps
+
+IMPORTANT GUIDELINES:
+1. Think step-by-step and use available tools when they can help provide better answers
+2. For current information: Search the web for up-to-date facts
+3. For files: Process associated files when task_id is provided
+4. For visual content: Analyze images carefully when present
+5. For calculations: Use computational tools for accuracy
+6. Provide concise, direct answers without unnecessary prefixes
+7. Focus on accuracy and helpfulness
+8. Be factual and avoid speculation
+
+Your goal is to be as helpful and accurate as possible while using the right tools for each task."""
+
+# Generate the AgentState
+class AgentState(TypedDict):
+    messages: Annotated[list[AnyMessage], add_messages]
+    task_id: str
+    question_analysis: dict
+
+def assistant(state: AgentState):
+    """Main assistant function that processes messages and calls tools."""
+    messages = state["messages"]
+    
+    # Add system prompt if not already present
+    if not any(isinstance(msg, SystemMessage) for msg in messages):
+        messages = [SystemMessage(content=SYSTEM_PROMPT)] + messages
+    
+    # Get the response from the LLM
+    response = chat_with_tools.invoke(messages)
+    
+    return {
+        "messages": [response],
+    }
+
+def create_smart_agent():
+    """Create and return the smart agent graph."""
+    # Build the graph
+    builder = StateGraph(AgentState)
+    
+    # Define nodes
+    builder.add_node("assistant", assistant)
+    builder.add_node("tools", ToolNode(agent_tools))
+    
+    # Define edges
+    builder.add_edge(START, "assistant")
+    builder.add_conditional_edges(
+        "assistant",
+        tools_condition,
+    )
+    builder.add_edge("tools", "assistant")
+    
+    # Add memory
+    memory = MemorySaver()
+    agent = builder.compile(checkpointer=memory)
+    
+    return agent
+
+class SmartAgent:
+    """High-level intelligent agent class that wraps the LangGraph agent."""
+    
+    def __init__(self):
+        self.agent = create_smart_agent()
+        print("🤖 Smart Agent initialized with LangGraph and tools")
+    
+    def __call__(self, question: str, task_id: str = None) -> str:
+        """Process a question and return the formatted answer."""
+        try:
+            print(f"\n🎯 Processing question: {question[:100]}...")
+            
+            # Analyze the question
+            analysis = analyze_question_type(question)
+            print(f"📊 Question analysis: {analysis}")
+            
+            # Create execution plan
+            plan = create_execution_plan(question, task_id)
+            print(f"📋 Execution plan: {plan}")
+            
+            # Prepare the question with task_id context if available
+            enhanced_question = question
+            if task_id:
+                enhanced_question = f"Task ID: {task_id}\n\nQuestion: {question}\n\nNote: If this question involves files, use the file_download tool with task_id '{task_id}' to access associated files."
+            
+            # Invoke the agent
+            thread_id = f"task-{task_id}" if task_id else "general"
+            config = {"configurable": {"thread_id": thread_id}}
+            
+            initial_state = {
+                "messages": [HumanMessage(content=enhanced_question)],
+                "task_id": task_id or "",
+                "question_analysis": analysis
+            }
+            
+            result = self.agent.invoke(initial_state, config=config)
+            
+            # Extract the final answer
+            if result and 'messages' in result and result['messages']:
+                final_message = result['messages'][-1]
+                raw_answer = final_message.content
+            else:
+                raw_answer = "No response generated"
+            
+            # Format the answer for submission
+            formatted_answer = format_gaia_answer(raw_answer)
+            
+            print(f"✅ Raw answer: {raw_answer}")
+            print(f"🎯 Formatted answer: {formatted_answer}")
+            
+            return formatted_answer
+            
+        except Exception as e:
+            error_msg = f"Error processing question: {str(e)}"
+            print(f"❌ {error_msg}")
+            return error_msg
+
+smart_agent = SmartAgent()

app.py

@@ -3,22 +3,12 @@ import gradio as gr
 import requests
 import inspect
 import pandas as pd
+from agent import smart_agent
 
 # (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,
@@ -38,12 +28,13 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
     questions_url = f"{api_url}/questions"
     submit_url = f"{api_url}/submit"
 
-    # 1. Instantiate Agent ( modify this part to create your agent)
+    # 1. Use Smart Agent (imported from agent.py)
     try:
-        agent = BasicAgent()
+        agent = smart_agent
+        print("Smart Agent loaded successfully.")
     except Exception as e:
-        print(f"Error instantiating agent: {e}")
-        return f"Error initializing agent: {e}", None
+        print(f"Error loading smart agent: {e}")
+        return f"Error initializing smart 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"
     print(agent_code)
@@ -80,7 +71,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)
             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:
@@ -193,4 +184,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)

docs/additional-readings.mdx

@@ -0,0 +1,30 @@
+# And now? What topics I should learn?
+
+Agentic AI is a rapidly evolving field, and understanding foundational protocols is essential for building intelligent, autonomous systems. 
+
+Two important standards you should get familiar with are:
+
+- The **Model Context Protocol (MCP)**  
+- The **Agent-to-Agent Protocol (A2A)**
+
+## 🔌 Model Context Protocol (MCP)
+
+The **Model Context Protocol (MCP)** by Anthropic is an open standard that enables AI models to securely and seamlessly **connect with external tools, data sources, and applications**, making agents more capable and autonomous.
+
+Think of MCP as a **universal adapter**, like a USB-C port, that allows AI models to plug into various digital environments **without needing custom integration for each one**.
+
+MCP is quickly gaining traction across the industry, with major companies like OpenAI and Google beginning to adopt it. 
+
+📚 Learn more:
+- [Anthropic's official announcement and documentation](https://www.anthropic.com/news/model-context-protocol)
+- [MCP on Wikipedia](https://en.wikipedia.org/wiki/Model_Context_Protocol)
+- [Blog on MCP](https://huggingface.co/blog/Kseniase/mcp)
+
+## 🤝 Agent-to-Agent (A2A) Protocol
+
+Google has developed the **Agent-to-Agent (A2A) protocol** as a complementary counterpart to Anthropic's Model Context Protocol (MCP).
+
+While MCP connects agents to external tools, **A2A connects agents to each other**, paving the way for cooperative, multi-agent systems that can work together to solve complex problems.
+
+📚 Dive deeper into A2A:  
+- [Google’s A2A announcement](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/)

docs/conclusion.mdx

@@ -0,0 +1,11 @@
+# Conclusion
+
+**Congratulations on finishing the Agents Course!** 
+
+Through perseverance and dedication, you’ve built a solid foundation in the world of AI Agents.
+
+But finishing this course is **not the end of your journey**. It’s just the beginning: don’t hesitate to explore the next section where we share curated resources to help you continue learning, including advanced topics like **MCPs** and beyond.
+
+**Thank you** for being part of this course. **We hope you liked this course as much as we loved writing it**.
+
+And don’t forget: **Keep Learning, Stay Awesome 🤗**

docs/get-your-certificate.mdx

@@ -0,0 +1,24 @@
+# Claim Your Certificate 🎓
+
+If you scored **above 30%, congratulations! 👏 You're now eligible to claim your official certificate.**
+
+Follow the steps below to receive it:
+
+1. Visit the [certificate page](https://huggingface.co/spaces/agents-course/Unit4-Final-Certificate).
+2. **Sign in** with your Hugging Face account using the button provided.
+3. **Enter your full name**. This is the name that will appear on your certificate.
+4. Click **“Get My Certificate”** to verify your score and download your certificate.
+
+<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit4/congrats.png" alt="Congrats!" />
+
+Once you’ve got your certificate, feel free to:
+- Add it to your **LinkedIn profile** 🧑‍💼  
+- Share it on **X**, **Bluesky**, etc. 🎉
+
+**Don’t forget to tag [@huggingface](https://huggingface.co/huggingface). We’d be super proud and we’d love to cheer you on! 🤗**
+
+<Tip>
+
+If you have any issues with submission please open a discussion item on [The certification community tab](https://huggingface.co/spaces/agents-course/Unit4-Final-Certificate/discussions).
+
+</Tip>

docs/hands-on.mdx

@@ -0,0 +1,52 @@
+# Hands-On
+
+Now that you’re ready to dive deeper into the creation of your final agent, let’s see how you can submit it for review.
+
+## The Dataset 
+
+The Dataset used in this leaderboard consist of 20 questions extracted from the level 1 questions of the **validation** set from GAIA. 
+
+The chosen question were filtered based on the number of tools and steps needed to answer a question.
+
+Based on the current look of the GAIA benchmark, we think that getting you to try to aim for 30% on level 1 question is a fair test.
+
+<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit4/leaderboard%20GAIA%2024%3A04%3A2025.png" alt="GAIA current status!" />
+
+## The process 
+
+Now the big question in your mind is probably : "How do I start submitting ?"
+
+For this Unit, we created an API that will allow you to get the questions, and send your answers for scoring.
+Here is a summary of the routes (see the [live documentation](https://agents-course-unit4-scoring.hf.space/docs) for interactive details):
+
+* **`GET /questions`**: Retrieve the full list of filtered evaluation questions.
+* **`GET /random-question`**: Fetch a single random question from the list.
+* **`GET /files/{task_id}`**: Download a specific file associated with a given task ID.
+* **`POST /submit`**: Submit agent answers, calculate the score, and update the leaderboard.
+
+The submit function will compare the answer to the ground truth in an **EXACT MATCH** manner, hence prompt it well ! The GAIA team shared a prompting example for your agent [here](https://huggingface.co/spaces/gaia-benchmark/leaderboard) (for the sake of this course, make sure you don't include the text "FINAL ANSWER" in your submission, just make your agent reply with the answer and nothing else).
+
+🎨 **Make the Template Your Own!**
+
+To demonstrate the process of interacting with the API, we've included a [basic template](https://huggingface.co/spaces/agents-course/Final_Assignment_Template) as a starting point.
+
+Please feel free—and **actively encouraged**—to change, add to, or completely restructure it! Modify it in any way that best suits your approach and creativity.
+
+In order to submit this templates compute 3 things needed by the API :
+
+* **Username:** Your Hugging Face username (here obtained via Gradio login), which is used to identify your submission.
+* **Code Link (`agent_code`):** the URL linking to your Hugging Face Space code (`.../tree/main`) for verification purposes, so please keep your space public.
+* **Answers (`answers`):** The list of responses (`{"task_id": ..., "submitted_answer": ...}`) generated by your Agent for scoring.
+
+Hence we encourage you to start by duplicating this [template](https://huggingface.co/spaces/agents-course/Final_Assignment_Template) on your own huggingface profile.
+
+🏆 Check out the leaderboard [here](https://huggingface.co/spaces/agents-course/Students_leaderboard)
+
+*A friendly note: This leaderboard is meant for fun! We know it's possible to submit scores without full verification. If we see too many high scores posted without a public link to back them up, we might need to review, adjust, or remove some entries to keep the leaderboard useful.*
+The leaderboard will show the link to your space code-base, since this leaderboard is for students only, please keep your space public if you get a score you're proud of.
+<iframe
+	src="https://agents-course-students-leaderboard.hf.space"
+	frameborder="0"
+	width="850"
+	height="450"
+></iframe>

docs/introduction.mdx

@@ -0,0 +1,23 @@
+# Welcome to the final Unit [[introduction]]
+
+<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit4/thumbnail.jpg" alt="AI Agents Course thumbnail" width="100%"/>
+
+Welcome to the final unit of the course! 🎉
+
+So far, you’ve **built a strong foundation in AI Agents**, from understanding their components to creating your own. With this knowledge, you’re now ready to **build powerful agents** and stay up-to-date with the latest advancements in this fast-evolving field.
+
+This unit is all about applying what you’ve learned. It’s your **final hands-on project**, and completing it is your ticket to earning the **course certificate**.
+
+## What’s the challenge?
+
+You’ll create your own agent and **evaluate its performance using a subset of the [GAIA benchmark](https://huggingface.co/spaces/gaia-benchmark/leaderboard)**.
+
+To successfully complete the course, your agent needs to score **30% or higher** on the benchmark. Achieve that, and you’ll earn your **Certificate of Completion**, officially recognizing your expertise. 🏅
+
+Additionally, see how you stack up against your peers! A dedicated **[Student Leaderboard](https://huggingface.co/spaces/agents-course/Students_leaderboard)** is available for you to submit your scores and see the community's progress.
+
+> ** 🚨 Heads Up: Advanced & Hands-On Unit**
+>
+> Please be aware that this unit shifts towards a more practical, hands-on approach. Success in this section will require **more advanced coding knowledge** and relies on you navigating tasks with **less explicit guidance** compared to earlier parts of the course.
+
+Sounds exciting? Let’s get started! 🚀

docs/what-is-gaia.mdx

@@ -0,0 +1,70 @@
+# What is GAIA?
+
+[GAIA](https://huggingface.co/papers/2311.12983) is a **benchmark designed to evaluate AI assistants on real-world tasks** that require a combination of core capabilities—such as reasoning, multimodal understanding, web browsing, and proficient tool use.
+
+It was introduced in the paper _"[GAIA: A Benchmark for General AI Assistants](https://huggingface.co/papers/2311.12983)"_.
+
+The benchmark features **466 carefully curated questions** that are **conceptually simple for humans**, yet **remarkably challenging for current AI systems**. 
+
+To illustrate the gap:
+- **Humans**: ~92% success rate  
+- **GPT-4 with plugins**: ~15%  
+- **Deep Research (OpenAI)**: 67.36% on the validation set
+
+GAIA highlights the current limitations of AI models and provides a rigorous benchmark to evaluate progress toward truly general-purpose AI assistants.
+
+## 🌱 GAIA’s Core Principles
+
+GAIA is carefully designed around the following pillars:
+
+- 🔍 **Real-world difficulty**: Tasks require multi-step reasoning, multimodal understanding, and tool interaction.
+- 🧾 **Human interpretability**: Despite their difficulty for AI, tasks remain conceptually simple and easy to follow for humans.
+- 🛡️ **Non-gameability**: Correct answers demand full task execution, making brute-forcing ineffective.
+- 🧰 **Simplicity of evaluation**: Answers are concise, factual, and unambiguous—ideal for benchmarking.
+
+## Difficulty Levels
+
+GAIA tasks are organized into **three levels of increasing complexity**, each testing specific skills:
+
+- **Level 1**: Requires less than 5 steps and minimal tool usage.
+- **Level 2**: Involves more complex reasoning and coordination between multiple tools and 5-10 steps.
+- **Level 3**: Demands long-term planning and advanced integration of various tools.
+
+![GAIA levels](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit4/gaia_levels.png)
+
+## Example of a Hard GAIA Question
+
+> Which of the fruits shown in the 2008 painting "Embroidery from Uzbekistan" were served as part of the October 1949 breakfast menu for the ocean liner that was later used as a floating prop for the film "The Last Voyage"? Give the items as a comma-separated list, ordering them in clockwise order based on their arrangement in the painting starting from the 12 o'clock position. Use the plural form of each fruit.
+
+As you can see, this question challenges AI systems in several ways:
+
+- Requires a **structured response format**
+- Involves **multimodal reasoning** (e.g., analyzing images)
+- Demands **multi-hop retrieval** of interdependent facts:
+  - Identifying the fruits in the painting
+  - Discovering which ocean liner was used in *The Last Voyage*
+  - Looking up the breakfast menu from October 1949 for that ship
+- Needs **correct sequencing** and high-level planning to solve in the right order
+
+This kind of task highlights where standalone LLMs often fall short, making GAIA an ideal benchmark for **agent-based systems** that can reason, retrieve, and execute over multiple steps and modalities.
+
+![GAIA capabilities plot](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit4/gaia_capabilities.png)
+
+## Live Evaluation
+
+To encourage continuous benchmarking, **GAIA provides a public leaderboard hosted on Hugging Face**, where you can test your models against **300 testing questions**.
+
+👉 Check out the leaderboard [here](https://huggingface.co/spaces/gaia-benchmark/leaderboard)
+
+<iframe
+	src="https://gaia-benchmark-leaderboard.hf.space"
+	frameborder="0"
+	width="850"
+	height="450"
+></iframe>
+
+Want to dive deeper into GAIA?
+
+- 📄 [Read the full paper](https://huggingface.co/papers/2311.12983)
+- 📄 [Deep Research release post by OpenAI](https://openai.com/index/introducing-deep-research/)
+- 📄 [Open-source DeepResearch – Freeing our search agents](https://huggingface.co/blog/open-deep-research)

requirements.txt

@@ -1,2 +1,18 @@
+# Core dependencies from unit3
+langchain
+langchain-community
+langchain-huggingface
+langgraph
+huggingface_hub
+
+# Additional dependencies for GAIA
 gradio
-requests
+requests
+pillow
+PyPDF2
+duckduckgo-search
+python-dotenv
+
+# For image processing and multimodal capabilities
+transformers
+torch

test_local.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Local testing script for the GAIA agent.
+Run this to test the agent before deploying to HF Spaces.
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Add current directory to path for imports
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+from utils import fetch_random_question, analyze_question_type
+from agent import smart_agent
+
+def test_question_analysis():
+    """Test the question analysis functionality."""
+    print("🧪 Testing question analysis...")
+    
+    test_questions = [
+        "What is the current population of Tokyo?",
+        "Calculate 15 * 23 + 45",
+        "Analyze the image shown in the document",
+        "Extract all dates from the provided text file"
+    ]
+    
+    for question in test_questions:
+        analysis = analyze_question_type(question)
+        print(f"Question: {question}")
+        print(f"Analysis: {analysis}")
+        print()
+
+def test_tools():
+    """Test individual tools."""
+    print("🔧 Testing individual tools...")
+    
+    # Test calculator
+    from tools import calculator_tool
+    calc_result = calculator_tool.func("15 + 27")
+    print(f"Calculator test: {calc_result}")
+    
+    # Test web search (if available)
+    try:
+        from tools import web_search_tool
+        search_result = web_search_tool.func("Python programming language")
+        print(f"Web search test: {search_result[:100]}...")
+    except Exception as e:
+        print(f"Web search test failed: {e}")
+    
+    print()
+
+def test_agent_simple():
+    """Test the agent with a simple question."""
+    print("🤖 Testing Smart agent with simple question...")
+    
+    test_question = "What is 25 + 17?"
+    try:
+        result = smart_agent(test_question)
+        print(f"Question: {test_question}")
+        print(f"Answer: {result}")
+        print("✅ Simple test passed!")
+    except Exception as e:
+        print(f"❌ Simple test failed: {e}")
+    
+    print()
+
+def test_agent_with_api():
+    """Test the agent with a real GAIA question from the API."""
+    print("🌐 Testing with real GAIA question from API...")
+    
+    try:
+        question_data = fetch_random_question()
+        if not question_data:
+            print("❌ Failed to fetch question from API")
+            return
+        
+        task_id = question_data.get("task_id")
+        question = question_data.get("question")
+        
+        print(f"Task ID: {task_id}")
+        print(f"Question: {question}")
+        
+        # Run the agent
+        answer = smart_agent(question, task_id)
+        print(f"Agent Answer: {answer}")
+        print("✅ API test completed!")
+        
+    except Exception as e:
+        print(f"❌ API test failed: {e}")
+    
+    print()
+
+def check_environment():
+    """Check if all required environment variables are set."""
+    print("🔍 Checking environment...")
+    
+    required_vars = ["HUGGINGFACE_API_TOKEN"]
+    missing_vars = []
+    
+    for var in required_vars:
+        if not os.getenv(var):
+            missing_vars.append(var)
+        else:
+            print(f"✅ {var} is set")
+    
+    if missing_vars:
+        print(f"❌ Missing environment variables: {missing_vars}")
+        print("Please set these in your .env file or environment")
+        return False
+    
+    print("✅ All required environment variables are set")
+    return True
+
+def main():
+    """Run all tests."""
+    print("🚀 Starting GAIA Agent Local Tests")
+    print("=" * 50)
+    
+    # Check environment first
+    if not check_environment():
+        print("❌ Environment check failed. Please fix and try again.")
+        return
+    
+    print()
+    
+    # Run tests
+    # test_question_analysis()
+    # test_tools()
+    # test_agent_simple()
+    test_agent_with_api()
+
+if __name__ == "__main__":
+    main()

tools.py

@@ -0,0 +1,180 @@
+from langchain.tools import Tool
+import requests
+import os
+from PIL import Image
+import io
+import base64
+from langchain_community.tools import DuckDuckGoSearchRun
+from typing import Optional
+import json
+import PyPDF2
+import tempfile
+
+# Initialize web search tool
+search_tool = DuckDuckGoSearchRun()
+
+def web_search_tool_func(query: str) -> str:
+    """Searches the web for information using DuckDuckGo."""
+    try:
+        results = search_tool.run(query)
+        return results
+    except Exception as e:
+        return f"Web search failed: {str(e)}"
+
+web_search_tool = Tool(
+    name="web_search",
+    func=web_search_tool_func,
+    description="Searches the web for current information. Use this for factual questions, recent events, or when you need to find information not in your training data."
+)
+
+def file_download_tool_func(task_id: str) -> str:
+    """Downloads a file associated with a GAIA task ID."""
+    try:
+        api_url = "https://agents-course-unit4-scoring.hf.space"
+        file_url = f"{api_url}/files/{task_id}"
+        
+        response = requests.get(file_url, timeout=30)
+        response.raise_for_status()
+        
+        # Save to temporary file
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".tmp") as temp_file:
+            temp_file.write(response.content)
+            temp_path = temp_file.name
+        
+        # Try to determine file type and process accordingly
+        content_type = response.headers.get('content-type', '').lower()
+        
+        if 'image' in content_type:
+            return f"Image file downloaded to {temp_path}. Use image_analysis_tool to analyze it."
+        elif 'pdf' in content_type:
+            return process_pdf_file(temp_path)
+        elif 'text' in content_type:
+            with open(temp_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+            os.unlink(temp_path)  # Clean up
+            return f"Text file content:\n{content}"
+        else:
+            return f"File downloaded to {temp_path}. Content type: {content_type}"
+            
+    except Exception as e:
+        return f"Failed to download file for task {task_id}: {str(e)}"
+
+def process_pdf_file(file_path: str) -> str:
+    """Process a PDF file and extract text content."""
+    try:
+        with open(file_path, 'rb') as file:
+            pdf_reader = PyPDF2.PdfReader(file)
+            text_content = ""
+            
+            for page_num in range(len(pdf_reader.pages)):
+                page = pdf_reader.pages[page_num]
+                text_content += f"\n--- Page {page_num + 1} ---\n"
+                text_content += page.extract_text()
+        
+        os.unlink(file_path)  # Clean up
+        return f"PDF content extracted:\n{text_content}"
+    except Exception as e:
+        return f"Failed to process PDF: {str(e)}"
+
+file_download_tool = Tool(
+    name="file_download",
+    func=file_download_tool_func,
+    description="Downloads and processes files associated with GAIA task IDs. Can handle images, PDFs, and text files."
+)
+
+def image_analysis_tool_func(image_path_or_description: str) -> str:
+    """Analyzes images for GAIA questions. For now, returns a placeholder."""
+    # This is a simplified version - in a full implementation, you'd use a vision model
+    try:
+        if os.path.exists(image_path_or_description):
+            # Try to open and get basic info about the image
+            with Image.open(image_path_or_description) as img:
+                width, height = img.size
+                mode = img.mode
+                format_info = img.format
+                
+                # Clean up the temporary file
+                os.unlink(image_path_or_description)
+                
+                return f"Image analyzed: {width}x{height} pixels, mode: {mode}, format: {format_info}. Note: This is a basic analysis. For detailed image content analysis, a vision model would be needed."
+        else:
+            return f"Image analysis requested for: {image_path_or_description}. Note: Full image analysis requires a vision model integration."
+    except Exception as e:
+        return f"Image analysis failed: {str(e)}"
+
+image_analysis_tool = Tool(
+    name="image_analysis",
+    func=image_analysis_tool_func,
+    description="Analyzes images to extract information. Use this for questions involving visual content."
+)
+
+def calculator_tool_func(expression: str) -> str:
+    """Performs mathematical calculations safely."""
+    try:
+        # Basic safety check - only allow certain characters
+        allowed_chars = set('0123456789+-*/().= ')
+        if not all(c in allowed_chars for c in expression):
+            return f"Invalid characters in expression: {expression}"
+        
+        # Use eval safely for basic math
+        result = eval(expression)
+        return f"Calculation result: {expression} = {result}"
+    except Exception as e:
+        return f"Calculation failed for '{expression}': {str(e)}"
+
+calculator_tool = Tool(
+    name="calculator",
+    func=calculator_tool_func,
+    description="Performs mathematical calculations. Use this for numerical computations and math problems."
+)
+
+def text_processor_tool_func(text: str, operation: str = "summarize") -> str:
+    """Processes text for various operations like summarization, extraction, etc."""
+    try:
+        if operation == "summarize":
+            # Simple summarization - take first and last sentences if long
+            sentences = text.split('.')
+            if len(sentences) > 5:
+                summary = '. '.join(sentences[:2] + sentences[-2:])
+                return f"Text summary: {summary}"
+            else:
+                return f"Text (short enough to not need summarization): {text}"
+        
+        elif operation == "extract_numbers":
+            import re
+            numbers = re.findall(r'\d+(?:\.\d+)?', text)
+            return f"Numbers found in text: {numbers}"
+        
+        elif operation == "extract_dates":
+            import re
+            # Simple date pattern matching
+            date_patterns = [
+                r'\d{1,2}/\d{1,2}/\d{4}',  # MM/DD/YYYY
+                r'\d{4}-\d{1,2}-\d{1,2}',  # YYYY-MM-DD
+                r'\b\w+ \d{1,2}, \d{4}\b'  # Month DD, YYYY
+            ]
+            dates = []
+            for pattern in date_patterns:
+                dates.extend(re.findall(pattern, text))
+            return f"Dates found in text: {dates}"
+        
+        else:
+            return f"Text processing operation '{operation}' not supported. Available: summarize, extract_numbers, extract_dates"
+            
+    except Exception as e:
+        return f"Text processing failed: {str(e)}"
+
+text_processor_tool = Tool(
+    name="text_processor",
+    func=text_processor_tool_func,
+    description="Processes text for various operations like summarization, number extraction, date extraction. Specify operation as second parameter."
+)
+
+# List of all tools for easy import
+agent_tools = [
+    web_search_tool,
+    file_download_tool,
+    image_analysis_tool,
+    calculator_tool,
+    text_processor_tool
+]

utils.py

@@ -0,0 +1,124 @@
+import requests
+import json
+from typing import List, Dict, Any
+
+def fetch_questions(api_url: str = "https://agents-course-unit4-scoring.hf.space") -> List[Dict[str, Any]]:
+    """Fetch all questions from the GAIA API."""
+    try:
+        response = requests.get(f"{api_url}/questions", timeout=15)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        print(f"Error fetching questions: {e}")
+        return []
+
+def fetch_random_question(api_url: str = "https://agents-course-unit4-scoring.hf.space") -> Dict[str, Any]:
+    """Fetch a random question from the GAIA API."""
+    try:
+        response = requests.get(f"{api_url}/random-question", timeout=15)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        print(f"Error fetching random question: {e}")
+        return {}
+
+def submit_answers(username: str, agent_code: str, answers: List[Dict[str, str]], 
+                  api_url: str = "https://agents-course-unit4-scoring.hf.space") -> Dict[str, Any]:
+    """Submit answers to the GAIA API for scoring."""
+    try:
+        submission_data = {
+            "username": username.strip(),
+            "agent_code": agent_code,
+            "answers": answers
+        }
+        
+        response = requests.post(f"{api_url}/submit", json=submission_data, timeout=60)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        print(f"Error submitting answers: {e}")
+        return {"error": str(e)}
+
+def format_gaia_answer(raw_answer: str) -> str:
+    """Format the agent's raw answer for GAIA submission (exact match)."""
+    # Remove common prefixes that might interfere with exact matching
+    prefixes_to_remove = [
+        "FINAL ANSWER:",
+        "Final Answer:",
+        "Answer:",
+        "The answer is:",
+        "The final answer is:",
+    ]
+    
+    answer = raw_answer.strip()
+    
+    for prefix in prefixes_to_remove:
+        if answer.startswith(prefix):
+            answer = answer[len(prefix):].strip()
+    
+    # Remove trailing punctuation that might not be in ground truth
+    while answer and answer[-1] in '.!?':
+        answer = answer[:-1].strip()
+    
+    return answer
+
+def analyze_question_type(question: str) -> Dict[str, bool]:
+    """Analyze what capabilities a question might need."""
+    question_lower = question.lower()
+    
+    analysis = {
+        "needs_web_search": any(keyword in question_lower for keyword in [
+            "current", "recent", "latest", "today", "now", "2024", "2023"
+        ]),
+        "needs_file_processing": "file" in question_lower or "document" in question_lower,
+        "needs_calculation": any(keyword in question_lower for keyword in [
+            "calculate", "compute", "sum", "total", "average", "percentage", "multiply", "divide"
+        ]),
+        "needs_image_analysis": any(keyword in question_lower for keyword in [
+            "image", "picture", "photo", "visual", "shown", "displayed"
+        ]),
+        "needs_text_processing": any(keyword in question_lower for keyword in [
+            "extract", "find in", "search for", "list", "count"
+        ])
+    }
+    
+    return analysis
+
+def create_execution_plan(question: str, task_id: str = None) -> List[str]:
+    """Create a step-by-step execution plan for a GAIA question."""
+    analysis = analyze_question_type(question)
+    plan = []
+    
+    # Always start with understanding the question
+    plan.append("Analyze the question to understand what information is needed")
+    
+    # Add file processing if needed
+    if task_id and analysis["needs_file_processing"]:
+        plan.append(f"Download and process any files associated with task {task_id}")
+    
+    # Add web search if needed
+    if analysis["needs_web_search"]:
+        plan.append("Search the web for current/recent information")
+    
+    # Add image analysis if needed
+    if analysis["needs_image_analysis"]:
+        plan.append("Analyze any images for visual information")
+    
+    # Add calculation if needed
+    if analysis["needs_calculation"]:
+        plan.append("Perform necessary calculations")
+    
+    # Add text processing if needed
+    if analysis["needs_text_processing"]:
+        plan.append("Process and extract specific information from text")
+    
+    # Always end with synthesis
+    plan.append("Synthesize all information to provide the final answer")
+    
+    return plan
+
+def log_agent_step(step: str, result: str, step_number: int = None):
+    """Log agent execution steps for debugging."""
+    prefix = f"Step {step_number}: " if step_number else ""
+    print(f"\n🤖 {prefix}{step}")
+    print(f"📝 Result: {result[:200]}{'...' if len(result) > 200 else ''}")