Upload 5 files

README.md

@@ -1,12 +1,49 @@
----
-title: Gaia Agent
-emoji: 🏃
-colorFrom: purple
-colorTo: gray
-sdk: gradio
-sdk_version: 5.36.2
-app_file: app.py
-pinned: false
+# GAIA Benchmark Agent
+
+This project is an AI agent designed to tackle the GAIA benchmark, featuring multi-step reasoning, tool use (web search, Wikipedia, data analysis, file handling), and a Gradio web interface for evaluation and submission.
+
+## Features
+- LangGraph-based agent with robust tool integration
+- Wikipedia, Tavily (web search), data analysis, and file handling tools
+- Automatic file download for file-based questions
+- Gradio interface for user interaction and answer submission
+- Error handling and graceful fallback for recursion/tool loops
+
+## Setup & Deployment
+
+### 1. Install Dependencies
+```
+pip install -r requirements.txt
+```
+
+### 2. Environment Variables
+Create a `.env` file (not committed) or set these variables in your Hugging Face Space:
+- `OPENAI_API_KEY` (for OpenAI LLM and transcription)
+- `TAVILY_API_KEY` (for Tavily web search)
+- (Optional) `SPACE_ID` (for Hugging Face Space integration)
+
+### 3. Run Locally
+```
+python app_safe.py
+```
+Or launch the Gradio interface as your main app file.
+
+### 4. Deploy to Hugging Face Spaces
+- Push your code to a public Hugging Face Space repository.
+- Set your API keys as secrets in the Space settings.
+- The Gradio app will launch automatically.
+
+## Project Structure
+- `app_safe.py` — Main Gradio app for full agent evaluation
+- `agent.py` — Agent logic and tool orchestration
+- `tools.py` — Tool definitions (Tavily, Wikipedia, data analysis, etc.)
+- `requirements.txt` — All dependencies
+- `README.md` — This file
+
+## Notes
+- The agent will return a fallback answer if it cannot answer within the recursion/tool call limits.
+- For best results, ensure all environment variables are set and dependencies are installed.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+**Good luck on the GAIA benchmark!** 

agent.py

@@ -0,0 +1,265 @@
+# agent.py
+import os
+import logging
+from typing import TypedDict, Annotated, Any
+from langgraph.graph import StateGraph, END, START
+from langgraph.graph.message import add_messages
+from dotenv import load_dotenv
+from langgraph.prebuilt import ToolNode
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import AnyMessage, HumanMessage, AIMessage, ToolMessage, SystemMessage
+from tools import TOOLS  # Your tools list should be defined here
+import requests
+import re
+import json
+
+# --- Logging Setup ---
+load_dotenv()
+LOG_FILE = os.path.join(os.path.dirname(__file__), "agent.log")
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    handlers=[
+        logging.StreamHandler(),
+        logging.FileHandler(LOG_FILE, mode="w", encoding="utf-8"),
+    ],
+)
+logger = logging.getLogger("agent_logger")
+
+# --- Token Counting Helper ---
+def count_tokens(messages):
+    try:
+        import tiktoken
+        enc = tiktoken.encoding_for_model("gpt-3.5-turbo")
+        total = 0
+        for msg in messages:
+            if hasattr(msg, "content") and msg.content:
+                total += len(enc.encode(str(msg.content)))
+        return total
+    except ImportError:
+        logger.warning("tiktoken not installed, skipping token count.")
+        return -1
+    except Exception as e:
+        logger.warning(f"Token counting error: {e}")
+        return -1
+
+# LLM definition using GPT‑o3
+system_prompt = (
+    "You are a helpful assistant. When answering, output ONLY the answer to the question, with no extra text, explanation, or formatting. "
+    "If you call a tool and receive its output, use the tool output as the main source for your answer. "
+    "You may analyze, summarize, or combine tool outputs if needed to answer the question, but do not ignore tool outputs or say you cannot access files or images. "
+    "Do not include phrases like 'Final answer', 'The answer is', or any commentary. Output only the answer string. "
+    "If a question involves a file, audio, or image, use the appropriate tool to access or process the file. Do not say you cannot access files—always attempt a tool call first. "
+    "When you output your answer, use the least possible amount of words. If a single word or number suffices, output only that."
+)
+chat = ChatOpenAI(
+    model="o3",  # GPT‑o3 model
+    temperature=1,
+    openai_api_key=os.getenv("OPENAI_API_KEY"),
+)
+
+# Bind tools with the LLM
+chat_with_tools = chat.bind_tools(TOOLS)
+
+# Agent state: tracks conversation history
+class AgentState(TypedDict):
+    messages: Annotated[list[AnyMessage], add_messages]
+
+# Assistant node: single chat invocation
+def assistant(state: AgentState) -> dict[str, list[AnyMessage]]:
+    logger.info("[Agent] Thinking...")
+    logger.info(f"[Agent] Messages so far: {[str(m) for m in state['messages']]}")
+    next_msg = chat_with_tools.invoke(state["messages"])
+    logger.info(f"[Agent] LLM response: {next_msg.content}")
+    if getattr(next_msg, "tool_calls", None):
+        logger.info(f"[Agent] Tool calls: {next_msg.tool_calls}")
+    return {"messages": [next_msg]}
+
+# Condition: check if the assistant wants to use a tool again
+def needs_tool(state: AgentState) -> str:
+    last = state["messages"][-1]
+    # If the LLM called a tool, we route to the tool node
+    if getattr(last, "tool_calls", None):
+        return "tools"
+    # Else, stop at END
+    return "end"
+
+# Build the graph
+def build_langgraph():
+    builder = StateGraph(AgentState)
+    builder.add_node("assistant", assistant)
+    builder.add_node("tools", ToolNode(TOOLS))
+    builder.set_entry_point("assistant")
+    builder.add_conditional_edges(
+        "assistant",
+        needs_tool,
+        {"tools": "tools", "end": END}
+    )
+    builder.add_edge("tools", "assistant")
+    return builder.compile()
+
+# High-level solve function with logging and token counting
+def solve(question: str) -> str:
+    logger.info(f"[User] {question}")
+    graph = build_langgraph()
+    state = {"messages": [SystemMessage(content=system_prompt), HumanMessage(content=question)]}
+    step = 0
+    all_messages = list(state["messages"])
+    # --- Track google_search_tool calls per question ---
+    google_search_calls = 0
+    MAX_GOOGLE_SEARCH_CALLS = 10
+    # --- Track repeated tool calls for 'give up' condition ---
+    tool_call_counts = {}
+    GIVE_UP_THRESHOLD = 5
+    fallback_answer = "Unable to determine from available data."
+    recursion_fallback = "Unable to find the answer with the given data."
+    try:
+        while True:
+            step += 1
+            logger.info(f"--- Step {step} ---")
+            # Run one step of the graph with recursion_limit set to 25
+            result = graph.invoke(state, {"recursion_limit": 25})
+            new_msgs = result["messages"][len(state["messages"]):]
+            for msg in new_msgs:
+                if isinstance(msg, AIMessage):
+                    logger.info(f"[Agent] {msg.content}")
+                elif isinstance(msg, ToolMessage):
+                    logger.info(f"[ToolMessage] {msg.content}")
+                # Intercept tool calls and block google_search_tool after limit
+                if hasattr(msg, "tool_call_id") and hasattr(msg, "name") and msg.name == "google_search_tool":
+                    google_search_calls += 1
+                    if google_search_calls > MAX_GOOGLE_SEARCH_CALLS:
+                        # Replace tool output with refusal message
+                        refusal = ToolMessage(
+                            content="Google search tool call refused: limit of 10 calls per question reached.",
+                            tool_call_id=msg.tool_call_id
+                        )
+                        result["messages"][result["messages"].index(msg)] = refusal
+                        logger.info("[ToolMessage] Google search tool call refused: limit reached.")
+                # --- Improved give up logic: track by tool name and arguments/query ---
+                if hasattr(msg, "name") and hasattr(msg, "tool_call_id"):
+                    tool_args = ""
+                    if hasattr(msg, "additional_kwargs") and msg.additional_kwargs and "tool_calls" in msg.additional_kwargs:
+                        tool_calls = msg.additional_kwargs["tool_calls"]
+                        if tool_calls and isinstance(tool_calls, list):
+                            # Get the first tool call's arguments (as string)
+                            tool_args = tool_calls[0].get("function", {}).get("arguments", "")
+                    tool_key = (msg.name, tool_args.strip().lower())
+                    tool_call_counts[tool_key] = tool_call_counts.get(tool_key, 0) + 1
+                    if tool_call_counts[tool_key] > GIVE_UP_THRESHOLD:
+                        logger.info(f"[Agent] Give up condition met for tool {msg.name} with similar arguments: {tool_args}")
+                        return fallback_answer
+            all_messages.extend(new_msgs)
+            state["messages"] = result["messages"]
+            # Check if done
+            if not getattr(state["messages"][-1], "tool_calls", None):
+                break
+        logger.info(f"[Agent] Final answer: {state['messages'][-1].content}")
+        token_count = count_tokens(all_messages)
+        if token_count >= 0:
+            logger.info(f"[Stats] Total tokens used: {token_count}")
+        return state["messages"][-1].content
+    except Exception as e:
+        # Catch GraphRecursionError and return a fallback answer
+        import langgraph.errors
+        if isinstance(e, langgraph.errors.GraphRecursionError):
+            logger.info("[Agent] Recursion limit reached, returning fallback answer.")
+            return recursion_fallback
+        else:
+            logger.error(f"[Agent] Unexpected error: {e}")
+            raise
+
+def download_file(url, dest_path):
+    response = requests.get(url, stream=True)
+    response.raise_for_status()
+    with open(dest_path, 'wb') as f:
+        for chunk in response.iter_content(chunk_size=8192):
+            f.write(chunk)
+    print(f"Downloaded {url} to {dest_path}")
+
+# Example usage with logging
+
+def web_search_example():
+    q = "Tell me about the recent injury of Jamal Musiala"
+    logger.info("\n" + "-"*20 + " Running Web Search Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+
+def audio_transcription_example():
+    q = "Transcribe the audio in the file 'sample_audio.wav'."
+    logger.info("\n" + "-"*20 + " Running Audio Transcription Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+
+def image_captioning_example():
+    q = "Describe the image in the file 'sample_image.jpg'."
+    logger.info("\n" + "-"*20 + " Running Image Captioning Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+
+def python_file_reader_example():
+    q = "Read the first 10 lines of the file 'project/agent.py'."
+    logger.info("\n" + "-"*20 + " Running Python File Reader Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+
+def image_captioning_real_example():
+    import os
+    file_path = 'project/sample_image.jpg'
+    if not os.path.exists(file_path):
+        print(f"Test image file '{file_path}' not found. Please add a real image file to the project directory.")
+        return
+    q = f"Describe the image in the file '{file_path}'."
+    logger.info("\n" + "-"*20 + " Running Image Captioning Real Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+    print(f"[Image Captioning Real Example] Q: {q}\nA: {answer}")
+
+def python_file_reader_real_example():
+    file_path = 'project/agent.py'
+    q = f"Read the first 10 lines of the file '{file_path}'."
+    logger.info("\n" + "-"*20 + " Running Python File Reader Real Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+    print(f"[Python File Reader Real Example] Q: {q}\nA: {answer}")
+
+def python_file_execution_example():
+    file_path = 'project/exercise.py'
+    q = f"What is the output of running the file '{file_path}'?"
+    logger.info("\n" + "-"*20 + " Running Python File Execution Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+    print(f"[Python File Execution Example] Q: {q}\nA: {answer}")
+
+def audio_transcription_real_example():
+    import os
+    file_path = 'project/sample_audio.wav'
+    if not os.path.exists(file_path):
+        print(f"Test audio file '{file_path}' not found. Please add a real audio file to the project directory.")
+        return
+    q = f"Transcribe the audio in the file '{file_path}'."
+    logger.info("\n" + "-"*20 + " Running Audio Transcription Real Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+    print(f"[Audio Transcription Real Example] Q: {q}\nA: {answer}")
+
+def react_single_word_example():
+    q = "What is the capital of France?"
+    logger.info("\n" + "-"*20 + " Running ReAct Single Word Example " + "-"*20)
+    answer = solve(q)
+    logger.info(f"[Result] Q: {q}\nA: {answer}")
+    logger.info("\n" + "-"*50 + "\n")
+    print(f"[ReAct Single Word Example] Q: {q}\nA: {answer}")
+
+
+
+if __name__ == "__main__":
+    web_search_example()

app_safe.py

@@ -0,0 +1,217 @@
+import os
+import gradio as gr
+import requests
+import inspect
+import pandas as pd
+from agent import solve, download_file
+
+# (Keep Constants as is)
+# --- Constants ---
+DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+
+# --- Agent Wrapper ---
+class LangGraphAgent:
+    def __init__(self):
+        print("LangGraphAgent initialized.")
+    def __call__(self, question: str) -> str:
+        print(f"LangGraphAgent received question (first 50 chars): {question[:50]}...")
+        try:
+            answer = solve(question)
+        except Exception as e:
+            print(f"LangGraphAgent error: {e}")
+            answer = f"AGENT ERROR: {e}"
+        print(f"LangGraphAgent returning answer: {answer}")
+        return answer
+
+def run_and_submit_all( profile: gr.OAuthProfile | None):
+    """
+    Fetches all questions, runs the LangGraphAgent on them, submits all answers,
+    and displays the results.
+    """
+    # --- Determine HF Space Runtime URL and Repo URL ---
+    space_id = os.getenv("SPACE_ID") # Get the SPACE_ID for sending link to the code
+
+    if profile:
+        username= f"{profile.username}"
+        print(f"User logged in: {username}")
+    else:
+        print("User not logged in.")
+        return "Please Login to Hugging Face with the button.", None
+
+    api_url = DEFAULT_API_URL
+    questions_url = f"{api_url}/questions"
+    submit_url = f"{api_url}/submit"
+
+    # 1. Instantiate Agent ( modify this part to create your agent)
+    try:
+        agent = LangGraphAgent()
+    except Exception as e:
+        print(f"Error instantiating agent: {e}")
+        return f"Error initializing agent: {e}", None
+    # In the case of an app running as a hugging Face space, this link points toward your codebase ( usefull for others so please keep it public)
+    agent_code = f"https://huggingface.co/spaces/{space_id}/tree/main"
+    print(agent_code)
+
+    # 2. Fetch Questions
+    print(f"Fetching questions from: {questions_url}")
+    try:
+        response = requests.get(questions_url, timeout=15)
+        response.raise_for_status()
+        questions_data = response.json()
+        if not questions_data:
+             print("Fetched questions list is empty.")
+             return "Fetched questions list is empty or invalid format.", None
+        print(f"Fetched {len(questions_data)} questions.")
+    except requests.exceptions.RequestException as e:
+        print(f"Error fetching questions: {e}")
+        return f"Error fetching questions: {e}", None
+    except requests.exceptions.JSONDecodeError as e:
+         print(f"Error decoding JSON response from questions endpoint: {e}")
+         print(f"Response text: {response.text[:500]}")
+         return f"Error decoding server response for questions: {e}", None
+    except Exception as e:
+        print(f"An unexpected error occurred fetching questions: {e}")
+        return f"An unexpected error occurred fetching questions: {e}", None
+
+    # 3. Run your Agent
+    results_log = []
+    answers_payload = []
+    print(f"Running agent on {len(questions_data)} questions...")
+    answered_count = 0
+    total_questions = len(questions_data)
+    for item in questions_data:
+        task_id = item.get("task_id")
+        question_text = item.get("question")
+        file_name = item.get("file_name")
+        # --- File Handling: Download using /files/{task_id} endpoint if file_name is present ---
+        if file_name:
+            local_path = os.path.join(".", file_name)
+            if not os.path.exists(local_path):
+                file_api_url = f"{api_url}/files/{task_id}"
+                print(f"Downloading file for task {task_id}: {file_api_url} -> {local_path}")
+                try:
+                    download_file(file_api_url, local_path)
+                except Exception as e:
+                    print(f"Failed to download file for task {task_id}: {e}")
+            else:
+                print(f"File already exists locally: {local_path}")
+            # Append file name to the question prompt
+            question_text = f"{question_text} (File: {file_name})"
+        if not task_id or question_text is None:
+            print(f"Skipping item with missing task_id or question: {item}")
+            continue
+        try:
+            submitted_answer = agent(question_text)
+            answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
+            results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": submitted_answer})
+        except Exception as e:
+            print(f"Error running agent on task {task_id}: {e}")
+            results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": f"AGENT ERROR: {e}"})
+        answered_count += 1
+        print(f"Answered {answered_count}/{total_questions} questions...")
+
+    if not answers_payload:
+        print("Agent did not produce any answers to submit.")
+        return "Agent did not produce any answers to submit.", pd.DataFrame(results_log)
+
+    # 4. Prepare Submission 
+    submission_data = {"username": username.strip(), "agent_code": agent_code, "answers": answers_payload}
+    status_update = f"Agent finished. Submitting {len(answers_payload)} answers for user '{username}'..."
+    print(status_update)
+
+    # 5. Submit
+    print(f"Submitting {len(answers_payload)} answers to: {submit_url}")
+    try:
+        response = requests.post(submit_url, json=submission_data, timeout=60)
+        response.raise_for_status()
+        result_data = response.json()
+        final_status = (
+            f"Submission Successful!\n"
+            f"User: {result_data.get('username')}\n"
+            f"Overall Score: {result_data.get('score', 'N/A')}% "
+            f"({result_data.get('correct_count', '?')}/{result_data.get('total_attempted', '?')} correct)\n"
+            f"Message: {result_data.get('message', 'No message received.')}"
+        )
+        print("Submission successful.")
+        results_df = pd.DataFrame(results_log)
+        return final_status, results_df
+    except requests.exceptions.HTTPError as e:
+        error_detail = f"Server responded with status {e.response.status_code}."
+        try:
+            error_json = e.response.json()
+            error_detail += f" Detail: {error_json.get('detail', e.response.text)}"
+        except requests.exceptions.JSONDecodeError:
+            error_detail += f" Response: {e.response.text[:500]}"
+        status_message = f"Submission Failed: {error_detail}"
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
+    except requests.exceptions.Timeout:
+        status_message = "Submission Failed: The request timed out."
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
+    except requests.exceptions.RequestException as e:
+        status_message = f"Submission Failed: Network error - {e}"
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
+    except Exception as e:
+        status_message = f"An unexpected error occurred during submission: {e}"
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
+
+
+# --- Build Gradio Interface using Blocks ---
+with gr.Blocks() as demo:
+    gr.Markdown("# Basic Agent Evaluation Runner")
+    gr.Markdown(
+        """
+        **Instructions:**
+        1.  Please clone this space, then modify the code to define your agent's logic, the tools, the necessary packages, etc ...
+        2.  Log in to your Hugging Face account using the button below. This uses your HF username for submission.
+        3.  Click 'Run Evaluation & Submit All Answers' to fetch questions, run your agent, submit answers, and see the score.
+        ---
+        **Disclaimers:**
+        Once clicking on the "submit button, it can take quite some time ( this is the time for the agent to go through all the questions).
+        This space provides a basic setup and is intentionally sub-optimal to encourage you to develop your own, more robust solution. For instance for the delay process of the submit button, a solution could be to cache the answers and submit in a seperate action or even to answer the questions in async.
+        """
+    )
+
+    gr.LoginButton()
+
+    run_button = gr.Button("Run Evaluation & Submit All Answers")
+
+    status_output = gr.Textbox(label="Run Status / Submission Result", lines=5, interactive=False)
+    # Removed max_rows=10 from DataFrame constructor
+    results_table = gr.DataFrame(label="Questions and Agent Answers", wrap=True)
+
+    run_button.click(
+        fn=run_and_submit_all,
+        outputs=[status_output, results_table]
+    )
+
+if __name__ == "__main__":
+    print("\n" + "-"*30 + " App Starting " + "-"*30)
+    # Check for SPACE_HOST and SPACE_ID at startup for information
+    space_host_startup = os.getenv("SPACE_HOST")
+    space_id_startup = os.getenv("SPACE_ID") # Get SPACE_ID at startup
+
+    if space_host_startup:
+        print(f"✅ SPACE_HOST found: {space_host_startup}")
+        print(f"   Runtime URL should be: https://{space_host_startup}.hf.space")
+    else:
+        print("ℹ️  SPACE_HOST environment variable not found (running locally?).")
+
+    if space_id_startup: # Print repo URLs if SPACE_ID is found
+        print(f"✅ SPACE_ID found: {space_id_startup}")
+        print(f"   Repo URL: https://huggingface.co/spaces/{space_id_startup}")
+        print(f"   Repo Tree URL: https://huggingface.co/spaces/{space_id_startup}/tree/main")
+    else:
+        print("ℹ️  SPACE_ID environment variable not found (running locally?). Repo URL cannot be determined.")
+
+    print("-"*(60 + len(" App Starting ")) + "\n")
+
+    print("Launching Gradio Interface for Basic Agent Evaluation...")
+    demo.launch(debug=True, share=False)

requirements.txt

@@ -0,0 +1,13 @@
+gradio
+openai
+tavily
+pandas
+requests
+python-dotenv
+langgraph
+langchain
+wikipedia
+sumy
+transformers
+torch
+Pillow 

tools.py

@@ -0,0 +1,280 @@
+from pydantic import BaseModel, Field
+from typing import Optional
+import math
+import requests
+from langchain_core.tools import tool
+import os
+
+# --- Calculator Tool ---
+class CalculatorInput(BaseModel):
+    expression: str = Field(..., description="A mathematical expression to evaluate, e.g. '2 + 2 * 3'.")
+
+@tool(args_schema=CalculatorInput, return_direct=True)
+def calculator_tool(expression: str) -> str:
+    """Evaluate a mathematical expression, e.g. '2 + 2 * 3'."""
+    try:
+        # WARNING: eval is dangerous in production! Here we use it for simplicity, but in real apps use a safe parser.
+        result = eval(expression, {"__builtins__": None, "math": math}, {})
+        return str(result)
+    except Exception as e:
+        return f"Error: {e}"
+
+# --- Wikipedia Search Tool ---
+class WikipediaSearchInput(BaseModel):
+    query: str = Field(..., description="The search query for Wikipedia.")
+    sentences: Optional[int] = Field(3, description="Number of sentences to return from the summary.")
+
+# We'll use the wikipedia library for this tool
+try:
+    import wikipedia
+except ImportError:
+    wikipedia = None
+
+@tool(args_schema=WikipediaSearchInput, return_direct=True)
+def wikipedia_search_tool(query: str, sentences: int = 3) -> str:
+    """Search Wikipedia for a summary of a topic."""
+    if wikipedia is None:
+        return "Wikipedia library not installed. Please install it with 'pip install wikipedia'."
+    try:
+        summary = wikipedia.summary(query, sentences=sentences)
+        return summary
+    except Exception as e:
+        return f"Wikipedia search error: {e}"
+
+# --- Python Interpreter Tool ---
+class PythonInterpreterInput(BaseModel):
+    code: str = Field(..., description="Python code to execute. Should print or return the answer.")
+
+@tool(args_schema=PythonInterpreterInput, return_direct=True)
+def python_interpreter_tool(code: str) -> str:
+    """Execute Python code and return the result. Use variable 'result' or print output."""
+    import io
+    import contextlib
+    local_vars = {}
+    output = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(output):
+            exec(code, {"__builtins__": {}}, local_vars)
+        # If code defines a variable 'result', return it; else return stdout
+        if 'result' in local_vars:
+            return str(local_vars['result'])
+        result_output = output.getvalue().strip()
+        return result_output if result_output else "(No output)"
+    except Exception as e:
+        return f"Python execution error: {e}"
+
+# --- Unit Conversion Tool ---
+class UnitConversionInput(BaseModel):
+    value: float = Field(..., description="The numeric value to convert.")
+    from_unit: str = Field(..., description="The unit to convert from, e.g. 'meters'.")
+    to_unit: str = Field(..., description="The unit to convert to, e.g. 'feet'.")
+
+# Simple conversion table for demonstration
+CONVERSION_FACTORS = {
+    ("meters", "feet"): 3.28084,
+    ("feet", "meters"): 0.3048,
+    ("kilograms", "pounds"): 2.20462,
+    ("pounds", "kilograms"): 0.453592,
+    ("celsius", "fahrenheit"): lambda c: c * 9/5 + 32,
+    ("fahrenheit", "celsius"): lambda f: (f - 32) * 5/9,
+}
+
+@tool(args_schema=UnitConversionInput, return_direct=True)
+def unit_conversion_tool(value: float, from_unit: str, to_unit: str) -> str:
+    """Convert between units (e.g., meters to feet, celsius to fahrenheit)."""
+    key = (from_unit.lower(), to_unit.lower())
+    try:
+        factor = CONVERSION_FACTORS[key]
+        if callable(factor):
+            result = factor(value)
+        else:
+            result = value * factor
+        return f"{value} {from_unit} = {result} {to_unit}"
+    except Exception:
+        return f"Conversion from {from_unit} to {to_unit} not supported."
+
+# --- Date/Time Calculation Tool ---
+from datetime import datetime, timedelta
+class DateTimeCalcInput(BaseModel):
+    base_date: str = Field(..., description="The starting date in YYYY-MM-DD format. If blank, use today.")
+    delta_days: int = Field(..., description="Number of days to add (positive) or subtract (negative).")
+
+@tool(args_schema=DateTimeCalcInput, return_direct=True)
+def date_time_calc_tool(base_date: str, delta_days: int) -> str:
+    """Add or subtract days from a date (YYYY-MM-DD)."""
+    try:
+        base = datetime.strptime(base_date, "%Y-%m-%d") if base_date else datetime.now()
+        new_date = base + timedelta(days=delta_days)
+        return new_date.strftime("%Y-%m-%d")
+    except Exception as e:
+        return f"Date calculation error: {e}"
+
+# --- Text Summarization Tool ---
+class SummarizationInput(BaseModel):
+    text: str = Field(..., description="Text to summarize.")
+    max_sentences: int = Field(3, description="Maximum number of sentences in the summary.")
+
+try:
+    from sumy.parsers.plaintext import PlaintextParser
+    from sumy.nlp.tokenizers import Tokenizer
+    from sumy.summarizers.lsa import LsaSummarizer
+except ImportError:
+    PlaintextParser = Tokenizer = LsaSummarizer = None
+
+@tool(args_schema=SummarizationInput, return_direct=True)
+def summarization_tool(text: str, max_sentences: int = 3) -> str:
+    """Summarize a long text into a few sentences."""
+    if not (PlaintextParser and Tokenizer and LsaSummarizer):
+        return "Summarization library not installed. Please install it with 'pip install sumy'."
+    try:
+        parser = PlaintextParser.from_string(text, Tokenizer("english"))
+        summarizer = LsaSummarizer()
+        summary = summarizer(parser.document, max_sentences)
+        return " ".join(str(sentence) for sentence in summary)
+    except Exception as e:
+        return f"Summarization error: {e}"
+
+# --- Tavily Search Tool ---
+try:
+    from tavily import TavilyClient
+except ImportError:
+    TavilyClient = None
+
+class TavilySearchInput(BaseModel):
+    query: str = Field(..., description="The search query to look up on the web.")
+    num_results: int = Field(3, description="Number of results to return.")
+
+@tool(args_schema=TavilySearchInput, return_direct=True)
+def tavily_search_tool(query: str, num_results: int = 3) -> str:
+    """Search the web for up-to-date information using Tavily API (official client)."""
+    api_key = os.getenv("TAVILY_API_KEY")
+    if not api_key:
+        return "Tavily API key not set. Please set TAVILY_API_KEY in your environment."
+    if TavilyClient is None:
+        return "Tavily Python client not installed. Please install it with 'pip install tavily'."
+    try:
+        tavily_client = TavilyClient(api_key=api_key)
+        response = tavily_client.search(query, max_results=num_results)
+        # response is a dict; try to return the 'answer' or the full response
+        if isinstance(response, dict):
+            if response.get("answer"):
+                return response["answer"]
+            elif response.get("results"):
+                snippets = [r.get("snippet", "") for r in response["results"][:num_results]]
+                return "\n".join(snippets) if snippets else str(response)
+            else:
+                return str(response)
+        else:
+            return str(response)
+    except Exception as e:
+        return f"Tavily search error: {e}"
+
+# --- Audio Transcription Tool ---
+class AudioTranscriptionInput(BaseModel):
+    file_path: str = Field(..., description="Path to the audio file to transcribe.")
+
+@tool(args_schema=AudioTranscriptionInput, return_direct=True)
+def audio_transcription_tool(file_path: str) -> str:
+    """Transcribe an audio file using OpenAI's new API (>=1.0.0, gpt-4o-transcribe)."""
+    try:
+        import openai
+        import os
+        api_key = os.getenv("OPENAI_API_KEY")
+        client = openai.OpenAI(api_key=api_key)
+        with open(file_path, "rb") as audio_file:
+            transcript = client.audio.transcriptions.create(
+                file=audio_file,
+                model="gpt-4o-transcribe",
+                response_format="text"
+            )
+        return transcript
+    except Exception as e:
+        return f"Audio transcription error: {e}"
+
+# --- Image Captioning Tool ---
+class ImageCaptioningInput(BaseModel):
+    file_path: str = Field(..., description="Path to the image file to caption.")
+
+@tool(args_schema=ImageCaptioningInput, return_direct=True)
+def image_captioning_tool(file_path: str) -> str:
+    """Generate a caption for an image using BLIP from transformers (requires transformers and torch)."""
+    try:
+        from PIL import Image
+        from transformers import BlipProcessor, BlipForConditionalGeneration
+        import torch
+        processor = BlipProcessor.from_pretrained("Salesforce/blip-image-captioning-base")
+        model = BlipForConditionalGeneration.from_pretrained("Salesforce/blip-image-captioning-base")
+        image = Image.open(file_path).convert("RGB")
+        inputs = processor(image, return_tensors="pt")
+        with torch.no_grad():
+            out = model.generate(**inputs)
+        caption = processor.decode(out[0], skip_special_tokens=True)
+        return caption
+    except Exception as e:
+        return f"Image captioning error: {e}"
+
+# --- Python File Reader Tool ---
+class PythonFileReaderInput(BaseModel):
+    file_path: str = Field(..., description="Path to the Python file to read.")
+    max_lines: Optional[int] = Field(None, description="Maximum number of lines to read from the file.")
+
+@tool(args_schema=PythonFileReaderInput, return_direct=True)
+def python_file_reader_tool(file_path: str, max_lines: Optional[int] = None) -> str:
+    """Read and return the content of a Python file (optionally limited to max_lines)."""
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            if max_lines is not None:
+                lines = [next(f) for _ in range(max_lines)]
+                return "".join(lines)
+            else:
+                return f.read()
+    except Exception as e:
+        return f"Python file read error: {e}"
+
+# --- Data Analysis Tool ---
+class DataAnalysisInput(BaseModel):
+    file_path: str = Field(..., description="Path to the Excel or CSV file to analyze.")
+    instruction: str = Field(..., description="Analysis instruction, e.g. 'summary', 'head', 'describe', or a column name.")
+
+@tool(args_schema=DataAnalysisInput, return_direct=True)
+def data_analysis_tool(file_path: str, instruction: str) -> str:
+    """Analyze an Excel or CSV file using pandas. Instruction can be 'summary', 'head', 'describe', or a column name."""
+    import pandas as pd
+    import os
+    try:
+        if not os.path.exists(file_path):
+            return f"File not found: {file_path}"
+        if file_path.endswith('.csv'):
+            df = pd.read_csv(file_path)
+        elif file_path.endswith('.xlsx') or file_path.endswith('.xls'):
+            df = pd.read_excel(file_path)
+        else:
+            return "Unsupported file type. Only .csv, .xlsx, and .xls are supported."
+        instruction_lower = instruction.strip().lower()
+        if instruction_lower == 'summary':
+            return str(df.info())
+        elif instruction_lower == 'head':
+            return df.head().to_string()
+        elif instruction_lower == 'describe':
+            return df.describe().to_string()
+        elif instruction in df.columns:
+            return df[instruction].to_string()
+        else:
+            return f"Unknown instruction or column: {instruction}"
+    except Exception as e:
+        return f"Data analysis error: {e}"
+
+# --- Tool List for LangGraph/LangChain ---
+TOOLS = [
+    calculator_tool,
+    tavily_search_tool,
+    wikipedia_search_tool,
+    python_interpreter_tool,
+    unit_conversion_tool,
+    date_time_calc_tool,
+    summarization_tool,
+    audio_transcription_tool,
+    image_captioning_tool,
+    python_file_reader_tool,
+    data_analysis_tool,
+]