Add GAIA agent files for certification

.gitignore

@@ -0,0 +1,30 @@
+# Environment variables
+.env
+
+# Python cache files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# Logs
+logs/
+*.log
+
+# Progress files
+gaia_progress.json
+
+# Temporary files
+.DS_Store
+.vscode/
+*.swp
+*.swo

README.md

@@ -1,14 +1,47 @@
 ---
-title: FinalSubmission
-emoji: 🌖
-colorFrom: indigo
-colorTo: red
+title: GAIA Benchmark Agent
+emoji: 🧠
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 5.29.0
+sdk_version: 5.25.2
 app_file: app.py
 pinned: false
-license: mit
-short_description: Final Submission For The CertificationAgent
+hf_oauth: true
+hf_oauth_expiration_minutes: 480
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# GAIA Benchmark Agent
+
+This Hugging Face Space hosts a GAIA (General AI Assistant) benchmark agent designed to solve certification challenges across various domains of AI and machine learning.
+
+## Features
+
+- Processes questions from the GAIA benchmark
+- Uses LangChain and OpenAI's language models
+- Analyzes questions and identifies their types
+- Retrieves relevant context when needed
+- Generates accurate, well-reasoned answers
+
+## Usage
+
+1. Log in to your Hugging Face account using the button
+2. Click 'Run Evaluation & Submit All Answers' to:
+   - Fetch questions from the GAIA benchmark
+   - Run the agent on all questions
+   - Submit answers and see your score
+
+## Implementation Details
+
+The agent uses a modular architecture with specialized handlers for different question types:
+- Factual knowledge questions
+- Technical implementation questions
+- Mathematical questions
+- Context-based analysis questions
+- Ethical/societal impact questions
+
+## Repository
+
+The code for this agent is available at: https://huggingface.co/derkaal/GAIA-agent
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""
+GAIA Benchmark Agent Interface
+
+This script integrates the modular GAIA agent with the provided interface template.
+It replaces the BasicAgent class with our GAIA agent implementation.
+"""
+
+import os
+import gradio as gr
+import requests
+import inspect
+import pandas as pd
+from typing import Dict, List, Any, Optional
+
+# Import the GAIA agent modules
+from gaiaX.config import (
+    logger, CONFIG, HF_USERNAME, OPENAI_API_KEY, 
+    TAVILY_API_KEY, API_BASE_URL, validate_env_vars
+)
+from gaiaX.agent import initialize_agent, get_agent_response
+from gaiaX.question_handlers import process_question, detect_question_type
+
+# --- Constants ---
+DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+
+# --- GAIA Agent Implementation ---
+class GAIAAgent:
+    """
+    GAIA Benchmark Agent implementation that integrates with the provided interface.
+    """
+    def __init__(self):
+        """Initialize the GAIA agent."""
+        logger.info("Initializing GAIA agent...")
+        
+        # Validate environment variables
+        try:
+            validate_env_vars()
+        except ValueError as e:
+            logger.error(f"Environment validation failed: {e}")
+            raise
+        
+        # Initialize the LangChain agent
+        self.agent = initialize_agent(OPENAI_API_KEY, "openai_functions")
+        logger.info("GAIA agent initialized successfully.")
+    
+    def __call__(self, question: str) -> str:
+        """
+        Process a question and return the answer.
+        
+        Args:
+            question: The question text
+            
+        Returns:
+            The agent's answer as a string
+        """
+        logger.info(f"Agent received question (first 50 chars): {question[:50]}...")
+        
+        # Create a question dictionary
+        question_dict = {
+            "task_id": "custom_question",
+            "question": question,
+            "has_file": False
+        }
+        
+        # Process the question
+        try:
+            # Detect question type
+            question_type = detect_question_type(question)
+            logger.info(f"Detected question type: {question_type}")
+            
+            # Process the question
+            result = process_question(self.agent, question_dict, API_BASE_URL)
+            
+            # Extract the answer
+            answer = result.get("answer", "")
+            
+            if not answer:
+                logger.warning("Agent returned an empty answer.")
+                answer = "I couldn't generate an answer for this question."
+            
+            logger.info(f"Agent returning answer (first 50 chars): {answer[:50]}...")
+            return answer
+            
+        except Exception as e:
+            logger.error(f"Error processing question: {e}")
+            return f"Error: {str(e)}"
+
+# --- Run and Submit All Function ---
+def run_and_submit_all(profile: gr.OAuthProfile | None):
+    """
+    Fetches all questions, runs the GAIA Agent 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
+    try:
+        agent = GAIAAgent()
+    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
+    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...")
+    for item in questions_data:
+        task_id = item.get("task_id")
+        question_text = item.get("question")
+        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}"})
+
+    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("# GAIA Benchmark Agent Evaluation Runner")
+    gr.Markdown(
+        """
+        **Instructions:**
+
+        1. Log in to your Hugging Face account using the button below. This uses your HF username for submission.
+        2. Click 'Run Evaluation & Submit All Answers' to fetch questions, run your agent, submit answers, and see the score.
+
+        ---
+        **Note:**
+        This interface uses the modular GAIA Benchmark Agent to process questions from the GAIA benchmark.
+        The agent uses LangChain and OpenAI's language models to analyze questions, retrieve relevant context,
+        and generate accurate answers across various domains of AI and machine learning.
+        """
+    )
+
+    gr.LoginButton()
+
+    run_button = gr.Button("Run Evaluation & Submit All Answers")
+
+    status_output = gr.Textbox(label="Run Status / Submission Result", lines=5, interactive=False)
+    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 GAIA Benchmark Agent Evaluation...")
+    demo.launch(debug=True, share=False)

config.json

@@ -0,0 +1,25 @@
+{
+  "model_parameters": {
+    "model_name": "gpt-4-turbo",
+    "temperature": 0.2,
+    "max_tokens": 1024,
+    "top_p": 1.0,
+    "frequency_penalty": 0.0,
+    "presence_penalty": 0.0
+  },
+  "paths": {
+    "progress_file": "gaia_progress.json"
+  },
+  "api": {
+    "base_url": "https://agents-course-unit4-scoring.hf.space"
+  },
+  "logging": {
+    "level": "INFO",
+    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    "file": "logs/gaia_agent.log",
+    "console": true
+  },
+  "debugging": {
+    "enable_langchain_debug": false
+  }
+}

gaiaX/README.md

@@ -0,0 +1,119 @@
+# GAIA Benchmark Agent
+
+A LangChain-based agent for solving Hugging Face certification challenges in the GAIA benchmark.
+
+## Overview
+
+The GAIA Benchmark Agent is designed to process and answer questions from the Hugging Face GAIA benchmark. It uses LangChain and OpenAI's language models to analyze questions, retrieve relevant context, and generate accurate answers across various domains of AI and machine learning.
+
+## Features
+
+- Question type detection and specialized handling
+- Context-aware processing for questions with associated files
+- Batch processing with progress tracking
+- Performance analysis and reporting
+- Support for different agent types (OpenAI Functions, ReAct)
+
+## Project Structure
+
+The project has been modularized for better maintainability and to address token limit issues:
+
+```
+gaiaX/
+├── __init__.py        # Package initialization
+├── config.py          # Configuration handling
+├── api.py             # API interaction functions
+├── tools.py           # LangChain tools
+├── agent.py           # Agent initialization and response handling
+├── question_handlers.py # Question type detection and handling
+├── utils.py           # Utility functions
+└── README.md          # This file
+```
+
+## Setup
+
+1. Clone the repository
+2. Install dependencies:
+   ```
+   pip install -r requirements.txt
+   ```
+3. Create a `.env` file with the following variables:
+   ```
+   HF_USERNAME=your_huggingface_username
+   OPENAI_API_KEY=your_openai_api_key
+   TAVILY_API_KEY=your_tavily_api_key  # Optional, for search functionality
+   ```
+4. Create a `config.json` file with your configuration:
+   ```json
+   {
+     "model_parameters": {
+       "model_name": "gpt-4-turbo",
+       "temperature": 0.2
+     },
+     "paths": {
+       "progress_file": "gaia_progress.json"
+     },
+     "api": {
+       "base_url": "https://api.example.com/gaia"
+     },
+     "logging": {
+       "level": "INFO",
+       "file": "logs/gaia_agent.log",
+       "console": true
+     }
+   }
+   ```
+
+## Usage
+
+The GAIA Benchmark Agent can be used in several modes:
+
+### Test Mode
+
+Test the agent with a sample question or a custom question:
+
+```bash
+python gaia_agent_new.py test --agent-type openai_functions --question "What is deep learning?"
+```
+
+With a context file:
+
+```bash
+python gaia_agent_new.py test --agent-type openai_functions --question "Explain the concepts in this paper." --file path/to/paper.txt
+```
+
+### Random Question Mode
+
+Process a random question from the GAIA benchmark:
+
+```bash
+python gaia_agent_new.py random --agent-type openai_functions
+```
+
+### Batch Processing Mode
+
+Process a batch of questions from the GAIA benchmark:
+
+```bash
+python gaia_agent_new.py batch --agent-type openai_functions --batch-size 10 --progress-file progress.json --limit 50
+```
+
+### Submit Answers
+
+Submit processed answers to the GAIA benchmark:
+
+```bash
+python gaia_agent_new.py submit --progress-file progress.json --agent-code-link https://github.com/yourusername/gaia-agent
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+python test_gaia_agent_new.py
+```
+
+## License
+
+[MIT License](LICENSE)

gaiaX/__init__.py

@@ -0,0 +1,9 @@
+"""
+GAIA Benchmark Agent - Hugging Face Certification Challenge Solver
+
+This package provides a LangChain agent to solve Hugging Face certification
+challenges for the GAIA benchmark. It includes batch processing capabilities,
+progress tracking, and performance analysis.
+"""
+
+__version__ = "1.0.0"

gaiaX/agent.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""
+Agent module for GAIA Benchmark Agent.
+
+This module handles the initialization of LangChain agents and
+processing of responses for different question types.
+"""
+
+import tempfile
+import json
+from typing import Dict, List, Any, Optional, Union, Tuple
+
+from langchain.agents import AgentExecutor, create_openai_functions_agent, create_react_agent
+from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder, PromptTemplate
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+from langchain_openai import ChatOpenAI
+from langchain.memory import ConversationBufferMemory
+from langchain.globals import set_debug
+
+from gaiaX.config import logger, CONFIG, OPENAI_API_KEY, TAVILY_API_KEY
+from gaiaX.tools import get_tools
+from gaiaX.api import download_file_for_task
+
+def initialize_agent(api_key: str = OPENAI_API_KEY, agent_type: str = "openai_functions") -> Any:
+    """
+    Initialize a LangChain agent with appropriate tools and configuration.
+    
+    Args:
+        api_key: OpenAI API key or other LLM provider key
+        agent_type: Type of agent to initialize ("openai_functions" or "react")
+        
+    Returns:
+        Initialized LangChain agent
+    """
+    # Enable LangChain debugging if configured
+    debug_enabled = CONFIG.get("debugging", {}).get("enable_langchain_debug", False)
+    if debug_enabled:
+        set_debug(True)
+        logger.info("LangChain debugging enabled")
+    
+    # Get model parameters from config
+    model_params = CONFIG.get("model_parameters", {})
+    model_name = model_params.get("model_name", "gpt-4-turbo")
+    temperature = model_params.get("temperature", 0.2)
+    max_tokens = model_params.get("max_tokens", None)
+    top_p = model_params.get("top_p", 1.0)
+    frequency_penalty = model_params.get("frequency_penalty", 0.0)
+    presence_penalty = model_params.get("presence_penalty", 0.0)
+    
+    logger.info(f"Initializing agent with model: {model_name}, temperature: {temperature}, type: {agent_type}")
+    
+    # Initialize the language model
+    llm = ChatOpenAI(
+        model=model_name,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        top_p=top_p,
+        frequency_penalty=frequency_penalty,
+        presence_penalty=presence_penalty,
+        api_key=api_key
+    )
+    
+    # Get tools for the agent
+    tools = get_tools(include_search=True, tavily_api_key=TAVILY_API_KEY)
+    
+    if agent_type == "react":
+        # Create a ReAct agent with a specialized prompt for GAIA benchmark
+        react_template = """
+        You are a general AI assistant. I will ask you a question.
+        You have access to the following tools:
+        {tools}
+
+        Use the following format:
+
+        Question: the input question you must answer
+        Thought: you should always think about what to do
+        Action: the action to take, should be one of [{tool_names}]
+        Action Input: the input to the action
+        Observation: the result of the action
+        ... (this Thought/Action/Action Input/Observation can repeat N times)
+        Thought: I now know the final answer.
+        Final Answer: [The final answer to the original input question. 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 above rules depending of whether the element to be put in the list is a number or a string. Output *only* the final answer value here, without any other surrounding text or prefixes.]
+
+        Begin!
+
+        Question: {input}
+        Thought: {agent_scratchpad}
+        """
+        
+        # Create the prompt template
+        react_prompt = PromptTemplate.from_template(react_template)
+        
+        # Create the ReAct agent
+        agent = create_react_agent(llm, tools, react_prompt)
+        
+        # Create the agent executor
+        agent_executor = AgentExecutor(
+            agent=agent,
+            tools=tools,
+            verbose=True,
+            handle_parsing_errors=True
+        )
+        
+        logger.info("ReAct agent initialized successfully")
+        
+    else:  # Default to OpenAI Functions agent
+        # Create a detailed system prompt with instructions for different question types
+        system_prompt = """
+        You are an expert AI assistant specialized in solving Hugging Face certification challenges for the GAIA benchmark.
+        Your goal is to provide accurate, well-reasoned answers to questions across various domains of AI and machine learning.
+        
+        When given a question:
+        1. Carefully analyze what is being asked and identify the question type
+        2. Determine if you need additional context from any provided files
+        3. If context files are available, request them using the fetch_context_file tool
+        4. Formulate a comprehensive, accurate answer based on your knowledge and the provided context
+        5. Ensure your answer is clear, concise, and directly addresses the question
+        
+        QUESTION TYPES AND STRATEGIES:
+        
+        1. FACTUAL KNOWLEDGE QUESTIONS:
+           - These test your knowledge of AI/ML concepts, techniques, or history
+           - Provide precise definitions and explanations
+           - Include relevant examples to illustrate concepts
+           - Cite important research papers or developments when applicable
+        
+        2. TECHNICAL IMPLEMENTATION QUESTIONS:
+           - These ask about code, algorithms, or implementation details
+           - Provide step-by-step explanations of algorithms or processes
+           - Include pseudocode or code snippets when helpful
+           - Explain trade-offs between different approaches
+        
+        3. MATHEMATICAL QUESTIONS:
+           - These involve equations, proofs, or statistical concepts
+           - Show your work step-by-step
+           - Explain the intuition behind mathematical concepts
+           - Use clear notation and define all variables
+        
+        4. CONTEXT-BASED ANALYSIS QUESTIONS:
+           - These require analyzing provided context files
+           - Thoroughly read and understand the context before answering
+           - Reference specific parts of the context in your answer
+           - Connect the context to broader AI/ML concepts when relevant
+        
+        5. ETHICAL/SOCIETAL IMPACT QUESTIONS:
+           - These address ethical considerations or societal impacts of AI
+           - Present balanced perspectives on controversial topics
+           - Consider multiple stakeholders and viewpoints
+           - Discuss both benefits and potential risks
+        
+        6. PROBLEM-SOLVING QUESTIONS:
+           - These present novel problems requiring creative solutions
+           - Break down the problem into manageable components
+           - Consider multiple approaches before selecting the best one
+           - Explain why your solution is optimal given constraints
+        
+        7. CODING QUESTIONS:
+           - These require implementing or debugging code
+           - Provide clean, efficient, and well-commented code
+           - Explain your implementation choices
+           - Consider edge cases and potential optimizations
+        
+        IMPORTANT FORMATTING GUIDELINES:
+        
+        1. For numerical answers:
+           - Provide only the number without units unless specifically requested
+           - Use standard notation (avoid scientific notation unless appropriate)
+           - Round to the specified number of decimal places if indicated
+        
+        2. For multiple-choice questions:
+           - Clearly indicate your selected option (A, B, C, D, etc.)
+           - Briefly explain your reasoning for the selection
+        
+        3. For short answer questions:
+           - Be concise and direct
+           - Focus on the key points without unnecessary elaboration
+        
+        4. For coding questions:
+           - Provide complete, runnable code unless a snippet is requested
+           - Include comments explaining complex logic
+           - Follow standard coding conventions for the language
+        
+        Remember, your goal is to provide accurate, helpful answers that demonstrate deep understanding of AI and machine learning concepts.
+        """
+        
+        # Create the prompt template
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", system_prompt),
+            MessagesPlaceholder(variable_name="chat_history"),
+            ("human", "{input}"),
+            MessagesPlaceholder(variable_name="agent_scratchpad"),
+        ])
+        
+        # Create memory for conversation history
+        memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)
+        
+        # Create the OpenAI Functions agent
+        agent = create_openai_functions_agent(llm, tools, prompt)
+        
+        # Create the agent executor
+        agent_executor = AgentExecutor(
+            agent=agent,
+            tools=tools,
+            verbose=True,
+            memory=memory,
+            handle_parsing_errors=True
+        )
+        
+        logger.info("OpenAI Functions agent initialized successfully")
+    
+    return agent_executor
+
+
+def get_agent_response(agent_executor: AgentExecutor, question_data: dict) -> str:
+    """
+    Get a response from the agent for a specific question.
+    
+    Args:
+        agent_executor: Initialized LangChain agent executor
+        question_data: Dictionary containing question data
+        
+    Returns:
+        Agent's response as a string
+    """
+    try:
+        # Extract question details
+        question_text = question_data.get("question", "")
+        task_id = question_data.get("task_id", "")
+        has_file = question_data.get("has_file", False)
+        
+        # Prepare the input for the agent
+        agent_input = {
+            "input": question_text
+        }
+        
+        # If the question has an associated file, try to download it
+        context_content = None
+        if has_file and task_id:
+            logger.info(f"Question has an associated file. Attempting to download for task {task_id}")
+            try:
+                # Create a temporary directory to store the file
+                with tempfile.TemporaryDirectory() as temp_dir:
+                    # Download the file
+                    file_path = download_file_for_task(CONFIG.get("api", {}).get("base_url"), task_id, temp_dir)
+                    
+                    # Try to read the file as text
+                    try:
+                        with open(file_path, 'r', encoding='utf-8') as f:
+                            context_content = f.read()
+                            
+                        # Add context to the agent input
+                        agent_input["context"] = context_content
+                        agent_input["input"] = f"Question: {question_text}\n\nContext: {context_content}"
+                    except UnicodeDecodeError:
+                        # If it's not a text file, provide info about the binary file
+                        file_size = Path(file_path).stat().st_size
+                        file_ext = Path(file_path).suffix
+                        binary_info = f"Binary file detected ({file_ext}, {file_size} bytes). This file cannot be displayed as text."
+                        agent_input["input"] = f"Question: {question_text}\n\nContext: {binary_info}"
+            except Exception as e:
+                logger.error(f"Error handling context file: {str(e)}")
+                agent_input["input"] = f"Question: {question_text}\n\nNote: There was an error retrieving the context file: {str(e)}"
+        
+        # Get response from the agent
+        logger.info(f"Sending question to agent: {question_text[:100]}...")
+        response = agent_executor.invoke(agent_input)
+        
+        # Extract the output from the response
+        output = response.get("output", "")
+        
+        return output
+    
+    except Exception as e:
+        logger.error(f"Error getting agent response: {str(e)}")
+        return f"Error: {str(e)}"

gaiaX/api.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""
+API interaction module for GAIA Benchmark Agent.
+
+This module handles all interactions with the GAIA benchmark API,
+including fetching questions, downloading files, and submitting answers.
+"""
+
+import json
+import requests
+from typing import Dict, List, Any, Optional
+from pathlib import Path
+
+from gaiaX.config import logger, API_BASE_URL
+
+def get_all_questions(api_base_url: str = API_BASE_URL) -> List[Dict[str, Any]]:
+    """
+    Retrieve all available questions from the GAIA benchmark.
+    
+    Args:
+        api_base_url: Base URL for the GAIA API
+        
+    Returns:
+        List of question dictionaries
+        
+    Raises:
+        requests.RequestException: If the API request fails
+        ValueError: If the response is not valid JSON or doesn't contain expected data
+    """
+    try:
+        response = requests.get(f"{api_base_url}/questions")
+        response.raise_for_status()  # Raise exception for 4XX/5XX responses
+        
+        questions = response.json()
+        
+        if not isinstance(questions, list):
+            raise ValueError("Expected a list of questions but received a different format")
+            
+        return questions
+    
+    except requests.RequestException as e:
+        logger.error(f"Error fetching questions: {e}")
+        raise
+    
+    except json.JSONDecodeError:
+        logger.error("Error decoding response as JSON")
+        raise ValueError("Invalid JSON response from the API")
+
+
+def get_random_question(api_base_url: str = API_BASE_URL) -> Dict[str, Any]:
+    """
+    Retrieve a random question from the GAIA benchmark.
+    
+    Args:
+        api_base_url: Base URL for the GAIA API
+        
+    Returns:
+        A single question dictionary
+        
+    Raises:
+        requests.RequestException: If the API request fails
+        ValueError: If the response is not valid JSON or doesn't contain expected data
+    """
+    try:
+        response = requests.get(f"{api_base_url}/questions/random")
+        response.raise_for_status()
+        
+        question = response.json()
+        
+        if not isinstance(question, dict):
+            raise ValueError("Expected a question dictionary but received a different format")
+            
+        return question
+    
+    except requests.RequestException as e:
+        logger.error(f"Error fetching random question: {e}")
+        raise
+    
+    except json.JSONDecodeError:
+        logger.error("Error decoding response as JSON")
+        raise ValueError("Invalid JSON response from the API")
+
+
+def download_file_for_task(api_base_url: str, task_id: str, download_path: str) -> str:
+    """
+    Download a file associated with a specific task.
+    
+    Args:
+        api_base_url: Base URL for the GAIA API
+        task_id: ID of the task to download files for
+        download_path: Directory path where the file should be saved
+        
+    Returns:
+        Path to the downloaded file
+        
+    Raises:
+        requests.RequestException: If the API request fails
+        IOError: If there's an error writing the file
+        ValueError: If the task_id is invalid or the response is unexpected
+    """
+    if not task_id:
+        raise ValueError("Task ID cannot be empty")
+    
+    # Ensure download directory exists
+    download_dir = Path(download_path)
+    download_dir.mkdir(parents=True, exist_ok=True)
+    
+    try:
+        response = requests.get(
+            f"{api_base_url}/tasks/{task_id}/file",
+            stream=True  # Stream the response for large files
+        )
+        response.raise_for_status()
+        
+        # Get filename from Content-Disposition header or use task_id as fallback
+        content_disposition = response.headers.get('Content-Disposition', '')
+        filename = None
+        
+        if 'filename=' in content_disposition:
+            filename = content_disposition.split('filename=')[1].strip('"\'')
+        
+        if not filename:
+            filename = f"{task_id}_file.txt"
+        
+        file_path = download_dir / filename
+        
+        # Write the file
+        with open(file_path, 'wb') as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                f.write(chunk)
+        
+        return str(file_path)
+    
+    except requests.RequestException as e:
+        logger.error(f"Error downloading file for task {task_id}: {e}")
+        raise
+    
+    except IOError as e:
+        logger.error(f"Error writing file to {download_path}: {e}")
+        raise
+
+
+def submit_answers(
+    api_base_url: str, 
+    username: str, 
+    agent_code_link: str, 
+    answers: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Submit answers to the GAIA benchmark.
+    
+    Args:
+        api_base_url: Base URL for the GAIA API
+        username: Hugging Face username
+        agent_code_link: Link to the agent code (e.g., GitHub repository)
+        answers: Dictionary of answers to submit
+        
+    Returns:
+        Response from the API containing submission results
+        
+    Raises:
+        requests.RequestException: If the API request fails
+        ValueError: If the response is not valid JSON or contains an error message
+    """
+    if not username:
+        raise ValueError("Username cannot be empty")
+    
+    if not agent_code_link:
+        raise ValueError("Agent code link cannot be empty")
+    
+    if not answers or not isinstance(answers, dict):
+        raise ValueError("Answers must be a non-empty dictionary")
+    
+    payload = {
+        "username": username,
+        "agent_code_link": agent_code_link,
+        "answers": answers
+    }
+    
+    try:
+        response = requests.post(
+            f"{api_base_url}/submit",
+            json=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        response.raise_for_status()
+        
+        result = response.json()
+        
+        # Check if the response contains an error message
+        if isinstance(result, dict) and result.get("error"):
+            raise ValueError(f"API returned an error: {result['error']}")
+            
+        return result
+    
+    except requests.RequestException as e:
+        logger.error(f"Error submitting answers: {e}")
+        raise
+    
+    except json.JSONDecodeError:
+        logger.error("Error decoding response as JSON")
+        raise ValueError("Invalid JSON response from the API")
+
+
+def get_question_details(task_id: str, api_base_url: str = API_BASE_URL) -> Dict[str, Any]:
+    """
+    Get detailed information about a specific question/task.
+    
+    Args:
+        task_id: The ID of the task to get details for
+        api_base_url: Base URL for the GAIA API
+        
+    Returns:
+        Dictionary containing question details
+    """
+    try:
+        response = requests.get(f"{api_base_url}/questions/{task_id}")
+        response.raise_for_status()
+        return response.json()
+    except requests.RequestException as e:
+        logger.error(f"Failed to get question details: {str(e)}")
+        return {"error": f"Failed to get question details: {str(e)}"}
+    except json.JSONDecodeError:
+        logger.error("Invalid JSON response from the API")
+        return {"error": "Invalid JSON response from the API"}

gaiaX/config.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Configuration module for GAIA Benchmark Agent.
+
+This module handles loading and managing configuration settings from JSON files
+and environment variables.
+"""
+
+import os
+import json
+import logging
+from typing import Dict, Any
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+def load_config(config_path: str = "config.json") -> Dict[str, Any]:
+    """
+    Load configuration from a JSON file.
+    
+    Args:
+        config_path: Path to the configuration file
+        
+    Returns:
+        Dictionary containing configuration settings
+    """
+    try:
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+        return config
+    except Exception as e:
+        print(f"Error loading configuration from {config_path}: {e}")
+        print("Using default configuration.")
+        return {
+            "model_parameters": {
+                "model_name": "gpt-4-turbo",
+                "temperature": 0.2
+            },
+            "paths": {
+                "progress_file": "gaia_progress.json"
+            },
+            "api": {
+                "base_url": "https://api.example.com/gaia"
+            }
+        }
+
+# Load configuration
+CONFIG = load_config()
+
+# Setup logging
+def setup_logging():
+    """Configure logging based on settings in CONFIG."""
+    logging_config = CONFIG.get("logging", {})
+    log_level = getattr(logging, logging_config.get("level", "INFO"))
+    log_format = logging_config.get("format", "%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    log_file = logging_config.get("file", "logs/gaia_agent.log")
+    
+    # Create logs directory if it doesn't exist
+    if log_file:
+        log_dir = os.path.dirname(log_file)
+        if log_dir and not os.path.exists(log_dir):
+            os.makedirs(log_dir, exist_ok=True)
+    
+    # Configure logging
+    logging.basicConfig(
+        level=log_level,
+        format=log_format,
+        handlers=[
+            logging.FileHandler(log_file) if log_file else logging.NullHandler(),
+            logging.StreamHandler() if logging_config.get("console", True) else logging.NullHandler()
+        ]
+    )
+    
+    return logging.getLogger("gaia_agent")
+
+# Initialize logger
+logger = setup_logging()
+
+# Environment variables
+HF_USERNAME = os.getenv("HF_USERNAME")
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+TAVILY_API_KEY = os.getenv("TAVILY_API_KEY")
+
+# API configuration
+API_BASE_URL = CONFIG.get("api", {}).get("base_url", "https://api.example.com/gaia")
+
+# Validate required environment variables
+def validate_env_vars():
+    """Validate that required environment variables are set."""
+    if not HF_USERNAME:
+        logger.error("HF_USERNAME environment variable is not set. Please check your .env file.")
+        raise ValueError("HF_USERNAME environment variable is not set. Please check your .env file.")
+    
+    if not OPENAI_API_KEY:
+        logger.error("OPENAI_API_KEY environment variable is not set. Please check your .env file.")
+        raise ValueError("OPENAI_API_KEY environment variable is not set. Please check your .env file.")
+    
+    # Tavily API key is optional but recommended for search functionality
+    if not TAVILY_API_KEY:
+        logger.warning("TAVILY_API_KEY environment variable is not set. Search functionality will be limited.")

gaiaX/question_handlers.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""
+Question handlers module for GAIA Benchmark Agent.
+
+This module provides specialized handlers for different types of questions
+in the GAIA benchmark, including question type detection and processing.
+"""
+
+import re
+import tempfile
+from typing import Dict, Any, Optional
+
+from gaiaX.config import logger, CONFIG, API_BASE_URL
+from gaiaX.api import download_file_for_task
+from gaiaX.agent import get_agent_response
+
+def detect_question_type(question_text: str) -> str:
+    """
+    Detect the type of question based on its content.
+    
+    Args:
+        question_text: The text of the question
+        
+    Returns:
+        String indicating the question type
+    """
+    # Convert to lowercase for case-insensitive matching
+    text = question_text.lower()
+    
+    # Check for mathematical questions
+    if any(keyword in text for keyword in ["calculate", "compute", "equation", "formula", "derivative", 
+                                          "integral", "probability", "statistics", "math"]):
+        return "mathematical"
+    
+    # Check for technical implementation questions
+    if any(keyword in text for keyword in ["implement", "code", "algorithm", "function", "class", 
+                                          "method", "programming", "pseudocode", "complexity"]):
+        return "technical"
+    
+    # Check for context-based questions
+    if any(keyword in text for keyword in ["context", "file", "document", "text", "analyze", 
+                                          "based on", "according to", "refer to"]):
+        return "context_based"
+    
+    # Check for ethical/societal questions
+    if any(keyword in text for keyword in ["ethics", "ethical", "society", "impact", "bias", 
+                                          "fairness", "responsible", "governance"]):
+        return "ethical"
+    
+    # Check for factual knowledge questions
+    if any(keyword in text for keyword in ["define", "explain", "describe", "what is", "who is", 
+                                          "when was", "history", "concept"]):
+        return "factual"
+    
+    # Default to general if no specific type is detected
+    return "general"
+
+
+def handle_factual_question(agent: Any, question: dict, context: str = None) -> str:
+    """
+    Handle factual knowledge questions.
+    
+    Args:
+        agent: Initialized LangChain agent
+        question: Dictionary containing question data
+        context: Optional context text
+        
+    Returns:
+        Agent's response as a string
+    """
+    logger.info("Handling factual knowledge question")
+    
+    # Enhance the question with specific instructions for factual questions
+    enhanced_question = question.copy()
+    
+    question_text = question.get("question", "")
+    enhanced_text = f"""
+    [FACTUAL KNOWLEDGE QUESTION]
+    
+    {question_text}
+    
+    Please provide a precise, accurate answer based on established facts and knowledge.
+    Include relevant examples and cite important research or developments when applicable.
+    """
+    
+    enhanced_question["question"] = enhanced_text
+    
+    # Get response from the agent
+    return get_agent_response(agent, enhanced_question)
+
+
+def handle_technical_question(agent: Any, question: dict, context: str = None) -> str:
+    """
+    Handle technical implementation questions.
+    
+    Args:
+        agent: Initialized LangChain agent
+        question: Dictionary containing question data
+        context: Optional context text
+        
+    Returns:
+        Agent's response as a string
+    """
+    logger.info("Handling technical implementation question")
+    
+    # Enhance the question with specific instructions for technical questions
+    enhanced_question = question.copy()
+    
+    question_text = question.get("question", "")
+    enhanced_text = f"""
+    [TECHNICAL IMPLEMENTATION QUESTION]
+    
+    {question_text}
+    
+    Please provide a detailed technical explanation, including:
+    - Step-by-step explanation of algorithms or processes
+    - Pseudocode or code snippets when helpful
+    - Analysis of trade-offs between different approaches
+    - Complexity analysis (time and space) if relevant
+    """
+    
+    enhanced_question["question"] = enhanced_text
+    
+    # Get response from the agent
+    return get_agent_response(agent, enhanced_question)
+
+
+def handle_mathematical_question(agent: Any, question: dict, context: str = None) -> str:
+    """
+    Handle mathematical questions.
+    
+    Args:
+        agent: Initialized LangChain agent
+        question: Dictionary containing question data
+        context: Optional context text
+        
+    Returns:
+        Agent's response as a string
+    """
+    logger.info("Handling mathematical question")
+    
+    # Enhance the question with specific instructions for mathematical questions
+    enhanced_question = question.copy()
+    
+    question_text = question.get("question", "")
+    enhanced_text = f"""
+    [MATHEMATICAL QUESTION]
+    
+    {question_text}
+    
+    Please provide a clear mathematical solution, including:
+    - Step-by-step working of the solution
+    - Clear explanation of the mathematical concepts involved
+    - Proper notation with defined variables
+    - Final answer in the simplest form
+    
+    If the question asks for a specific numerical value, provide only that value as your final answer.
+    """
+    
+    enhanced_question["question"] = enhanced_text
+    
+    # Get response from the agent
+    return get_agent_response(agent, enhanced_question)
+
+
+def handle_context_based_question(agent: Any, question: dict, context: str = None) -> str:
+    """
+    Handle context-based analysis questions.
+    
+    Args:
+        agent: Initialized LangChain agent
+        question: Dictionary containing question data
+        context: Optional context text
+        
+    Returns:
+        Agent's response as a string
+    """
+    logger.info("Handling context-based question")
+    
+    # If context is not provided but the question has a file, try to download it
+    if not context and question.get("has_file", False):
+        task_id = question.get("task_id", "")
+        if task_id:
+            try:
+                with tempfile.TemporaryDirectory() as temp_dir:
+                    file_path = download_file_for_task(API_BASE_URL, task_id, temp_dir)
+                    with open(file_path, 'r', encoding='utf-8') as f:
+                        context = f.read()
+            except Exception as e:
+                logger.error(f"Error downloading context file: {str(e)}")
+    
+    # Enhance the question with specific instructions for context-based questions
+    enhanced_question = question.copy()
+    
+    question_text = question.get("question", "")
+    enhanced_text = f"""
+    [CONTEXT-BASED ANALYSIS QUESTION]
+    
+    {question_text}
+    
+    Please analyze the provided context carefully and provide an answer that:
+    - Directly references relevant parts of the context
+    - Connects the context to broader AI/ML concepts when relevant
+    - Provides a comprehensive analysis based on the context
+    """
+    
+    if context:
+        enhanced_text += f"\n\nContext:\n{context}"
+    
+    enhanced_question["question"] = enhanced_text
+    
+    # Get response from the agent
+    return get_agent_response(agent, enhanced_question)
+
+
+def handle_general_question(agent: Any, question: dict, context: str = None) -> str:
+    """
+    Handle general questions that don't fit into specific categories.
+    
+    Args:
+        agent: Initialized LangChain agent
+        question: Dictionary containing question data
+        context: Optional context text
+        
+    Returns:
+        Agent's response as a string
+    """
+    logger.info("Handling general question")
+    
+    # Enhance the question with general instructions
+    enhanced_question = question.copy()
+    
+    question_text = question.get("question", "")
+    enhanced_text = f"""
+    [GENERAL QUESTION]
+    
+    {question_text}
+    
+    Please provide a comprehensive, accurate answer that:
+    - Directly addresses all aspects of the question
+    - Is well-structured and easy to understand
+    - Includes relevant examples or illustrations when helpful
+    - Cites sources or references when appropriate
+    """
+    
+    if context:
+        enhanced_text += f"\n\nContext:\n{context}"
+    
+    enhanced_question["question"] = enhanced_text
+    
+    # Get response from the agent
+    return get_agent_response(agent, enhanced_question)
+
+
+def process_question(agent: Any, question: dict, api_base_url: str = API_BASE_URL) -> dict:
+    """
+    Process a single question using the appropriate handler.
+    
+    Args:
+        agent: Initialized LangChain agent
+        question: Dictionary containing question data
+        api_base_url: Base URL for the GAIA API
+        
+    Returns:
+        Dictionary containing the question, answer, and metadata
+    """
+    try:
+        # Extract question details
+        question_text = question.get("question", "")
+        task_id = question.get("task_id", "")
+        has_file = question.get("has_file", False)
+        
+        logger.info(f"Processing question: {task_id} - {question_text[:50]}...")
+        
+        # Detect question type
+        question_type = detect_question_type(question_text)
+        logger.info(f"Detected question type: {question_type}")
+        
+        # Download context file if available
+        context = None
+        if has_file and task_id:
+            try:
+                with tempfile.TemporaryDirectory() as temp_dir:
+                    file_path = download_file_for_task(api_base_url, task_id, temp_dir)
+                    with open(file_path, 'r', encoding='utf-8') as f:
+                        context = f.read()
+            except Exception as e:
+                logger.error(f"Error downloading context file: {str(e)}")
+        
+        # Handle question based on its type
+        if question_type == "factual":
+            answer = handle_factual_question(agent, question, context)
+        elif question_type == "technical":
+            answer = handle_technical_question(agent, question, context)
+        elif question_type == "mathematical":
+            answer = handle_mathematical_question(agent, question, context)
+        elif question_type == "context_based":
+            answer = handle_context_based_question(agent, question, context)
+        else:
+            answer = handle_general_question(agent, question, context)
+        
+        # Create result dictionary
+        result = {
+            "task_id": task_id,
+            "question": question_text,
+            "answer": answer,
+            "question_type": question_type,
+            "has_context": context is not None
+        }
+        
+        return result
+    
+    except Exception as e:
+        logger.error(f"Error processing question: {str(e)}")
+        return {
+            "task_id": question.get("task_id", ""),
+            "question": question.get("question", ""),
+            "answer": f"Error: {str(e)}",
+            "error": str(e)
+        }

gaiaX/tools.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+LangChain tools module for GAIA Benchmark Agent.
+
+This module defines the custom tools used by the LangChain agent
+to interact with the GAIA benchmark API and process questions.
+"""
+
+import json
+import tempfile
+from typing import Dict, Any
+from pathlib import Path
+
+from langchain.tools import BaseTool, tool
+
+from gaiaX.config import logger, API_BASE_URL
+from gaiaX.api import download_file_for_task, get_question_details
+
+@tool
+def fetch_question_details(task_id: str, api_base_url: str = API_BASE_URL) -> Dict[str, Any]:
+    """
+    Get detailed information about a specific question/task.
+    
+    Args:
+        task_id: The ID of the task to get details for
+        api_base_url: Base URL for the GAIA API
+        
+    Returns:
+        Dictionary containing question details
+    """
+    return get_question_details(task_id, api_base_url)
+
+@tool
+def fetch_context_file(task_id: str, api_base_url: str = API_BASE_URL) -> str:
+    """
+    Download and read the context file for a specific task.
+    
+    Args:
+        task_id: The ID of the task to download the file for
+        api_base_url: Base URL for the GAIA API
+        
+    Returns:
+        String containing the file contents or error message
+    """
+    try:
+        # Create a temporary directory to store the file
+        with tempfile.TemporaryDirectory() as temp_dir:
+            file_path = download_file_for_task(api_base_url, task_id, temp_dir)
+            
+            # Try to read the file as text
+            try:
+                with open(file_path, 'r', encoding='utf-8') as f:
+                    return f.read()
+            except UnicodeDecodeError:
+                # If it's not a text file, try to read it as binary and provide info
+                file_size = Path(file_path).stat().st_size
+                file_ext = Path(file_path).suffix
+                return f"Binary file detected ({file_ext}, {file_size} bytes). This file cannot be displayed as text. Please use specialized tools to analyze this type of file."
+    except Exception as e:
+        logger.error(f"Error fetching context file: {str(e)}")
+        return f"Error fetching context file: {str(e)}"
+
+# Define a class for each tool to make them more configurable
+class QuestionDetailsTool(BaseTool):
+    """Tool for fetching question details from the GAIA API."""
+    
+    name = "get_question_details"
+    description = "Get detailed information about a specific question/task"
+    
+    def _run(self, task_id: str, api_base_url: str = API_BASE_URL) -> Dict[str, Any]:
+        """Execute the tool."""
+        return get_question_details(task_id, api_base_url)
+    
+    def _arun(self, task_id: str, api_base_url: str = API_BASE_URL):
+        """Execute the tool asynchronously."""
+        raise NotImplementedError("Async version not implemented")
+
+class ContextFileTool(BaseTool):
+    """Tool for fetching and reading context files for tasks."""
+    
+    name = "fetch_context_file"
+    description = "Download and read the context file for a specific task"
+    
+    def _run(self, task_id: str, api_base_url: str = API_BASE_URL) -> str:
+        """Execute the tool."""
+        return fetch_context_file(task_id, api_base_url)
+    
+    def _arun(self, task_id: str, api_base_url: str = API_BASE_URL):
+        """Execute the tool asynchronously."""
+        raise NotImplementedError("Async version not implemented")
+
+# Function to get all available tools
+def get_tools(include_search: bool = True, tavily_api_key: str = None):
+    """
+    Get all available tools for the agent.
+    
+    Args:
+        include_search: Whether to include the search tool
+        tavily_api_key: Tavily API key for search functionality
+        
+    Returns:
+        List of tools
+    """
+    tools = [
+        fetch_question_details,
+        fetch_context_file
+    ]
+    
+    # Add search tool if Tavily API key is available and search is enabled
+    if include_search and tavily_api_key:
+        try:
+            from langchain_community.tools.tavily_search import TavilySearchResults
+            
+            search_tool = TavilySearchResults(
+                max_results=3,
+                api_key=tavily_api_key
+            )
+            tools.append(search_tool)
+            logger.info("Search tool added to agent tools")
+        except ImportError:
+            logger.warning("Could not import TavilySearchResults. Search functionality will be disabled.")
+        except Exception as e:
+            logger.warning(f"Error initializing search tool: {e}")
+    
+    return tools

gaiaX/utils.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""
+Utility functions for GAIA Benchmark Agent.
+
+This module provides utility functions for progress tracking,
+performance analysis, and other helper functions.
+"""
+
+import os
+import json
+import datetime
+from typing import Dict, List, Any, Optional
+
+from gaiaX.config import logger, CONFIG
+
+def load_progress(progress_file: str = None) -> dict:
+    """
+    Load progress from a JSON file.
+    
+    Args:
+        progress_file: Path to the progress file
+        
+    Returns:
+        Dictionary containing progress data
+    """
+    if not progress_file:
+        progress_file = CONFIG.get("paths", {}).get("progress_file", "gaia_progress.json")
+    
+    try:
+        if os.path.exists(progress_file):
+            with open(progress_file, 'r') as f:
+                progress = json.load(f)
+            return progress
+        else:
+            return {"processed_questions": [], "answers": {}}
+    except Exception as e:
+        logger.error(f"Error loading progress from {progress_file}: {e}")
+        return {"processed_questions": [], "answers": {}}
+
+
+def save_progress(progress_data: dict, progress_file: str = None) -> bool:
+    """
+    Save progress to a JSON file.
+    
+    Args:
+        progress_data: Dictionary containing progress data
+        progress_file: Path to the progress file
+        
+    Returns:
+        True if successful, False otherwise
+    """
+    if not progress_file:
+        progress_file = CONFIG.get("paths", {}).get("progress_file", "gaia_progress.json")
+    
+    try:
+        with open(progress_file, 'w') as f:
+            json.dump(progress_data, f, indent=2)
+        return True
+    except Exception as e:
+        logger.error(f"Error saving progress to {progress_file}: {e}")
+        return False
+
+
+def analyze_performance(answers: list, expected_answers: list = None) -> dict:
+    """
+    Analyze the performance of the agent based on answers.
+    
+    Args:
+        answers: List of answer dictionaries
+        expected_answers: Optional list of expected answers for evaluation
+        
+    Returns:
+        Dictionary containing performance metrics
+    """
+    total_questions = len(answers)
+    successful_answers = sum(1 for a in answers if "error" not in a)
+    error_count = total_questions - successful_answers
+    
+    # Calculate average response time if available
+    response_times = [a.get("response_time", 0) for a in answers if "response_time" in a]
+    avg_response_time = sum(response_times) / len(response_times) if response_times else 0
+    
+    # Count question types
+    question_types = {}
+    for answer in answers:
+        q_type = answer.get("question_type", "unknown")
+        question_types[q_type] = question_types.get(q_type, 0) + 1
+    
+    # Calculate accuracy if expected answers are provided
+    accuracy = None
+    correct_answers = 0
+    if expected_answers:
+        answer_dict = {a.get("task_id"): a.get("answer") for a in answers}
+        expected_dict = {e.get("task_id"): e.get("answer") for e in expected_answers}
+        
+        common_ids = set(answer_dict.keys()) & set(expected_dict.keys())
+        if common_ids:
+            for task_id in common_ids:
+                if answer_dict[task_id] == expected_dict[task_id]:
+                    correct_answers += 1
+            accuracy = correct_answers / len(common_ids)
+    
+    # Compile metrics
+    metrics = {
+        "total_questions": total_questions,
+        "successful_answers": successful_answers,
+        "error_count": error_count,
+        "success_rate": successful_answers / total_questions if total_questions > 0 else 0,
+        "average_response_time": avg_response_time,
+        "question_types": question_types
+    }
+    
+    if accuracy is not None:
+        metrics["accuracy"] = accuracy
+        metrics["correct_answers"] = correct_answers
+    
+    return metrics
+
+
+def format_performance_report(metrics: dict) -> str:
+    """
+    Format performance metrics into a readable report.
+    
+    Args:
+        metrics: Dictionary containing performance metrics
+        
+    Returns:
+        Formatted performance report as a string
+    """
+    report = [
+        "=== GAIA Benchmark Agent Performance Report ===",
+        f"Generated: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        "",
+        f"Total Questions Processed: {metrics['total_questions']}",
+        f"Successful Answers: {metrics['successful_answers']} ({metrics['success_rate']:.2%})",
+        f"Errors: {metrics['error_count']}",
+        f"Average Response Time: {metrics['average_response_time']:.2f} seconds",
+        "",
+        "Question Type Distribution:"
+    ]
+    
+    # Add question type distribution
+    for q_type, count in metrics.get("question_types", {}).items():
+        percentage = count / metrics["total_questions"] if metrics["total_questions"] > 0 else 0
+        report.append(f"  - {q_type}: {count} ({percentage:.2%})")
+    
+    # Add accuracy information if available
+    if "accuracy" in metrics:
+        report.extend([
+            "",
+            f"Accuracy: {metrics['accuracy']:.2%}",
+            f"Correct Answers: {metrics['correct_answers']} out of {metrics['total_questions']}"
+        ])
+    
+    return "\n".join(report)
+
+
+def process_questions_batch(agent: Any, questions: list, api_base_url: str,
+                           progress_file: str = None, batch_size: int = 10) -> dict:
+    """
+    Process a batch of questions and track progress.
+    
+    Args:
+        agent: Initialized LangChain agent
+        questions: List of question dictionaries
+        api_base_url: Base URL for the GAIA API
+        progress_file: Path to the progress file
+        batch_size: Number of questions to process in each batch
+        
+    Returns:
+        Dictionary containing processed questions and answers
+    """
+    from gaiaX.question_handlers import process_question
+    
+    # Load existing progress if available
+    if not progress_file:
+        progress_file = CONFIG.get("paths", {}).get("progress_file", "gaia_progress.json")
+    
+    progress = {}
+    try:
+        if os.path.exists(progress_file):
+            with open(progress_file, 'r') as f:
+                progress = json.load(f)
+        else:
+            progress = {"processed_questions": [], "answers": {}}
+    except Exception as e:
+        logger.error(f"Error loading progress from {progress_file}: {e}")
+        progress = {"processed_questions": [], "answers": {}}
+    
+    # Get list of already processed questions
+    processed_ids = set(progress.get("processed_questions", []))
+    
+    # Filter out already processed questions
+    remaining_questions = [q for q in questions if q.get("task_id") not in processed_ids]
+    logger.info(f"Found {len(remaining_questions)} questions to process out of {len(questions)} total")
+    
+    # Process questions in batches
+    results = []
+    for i, question in enumerate(remaining_questions):
+        if i > 0 and i % batch_size == 0:
+            logger.info(f"Processed {i}/{len(remaining_questions)} questions. Saving progress...")
+            save_progress(progress, progress_file)
+        
+        try:
+            task_id = question.get("task_id")
+            logger.info(f"Processing question {i+1}/{len(remaining_questions)}: {task_id}")
+            
+            # Process the question
+            start_time = datetime.datetime.now()
+            result = process_question(agent, question, api_base_url)
+            end_time = datetime.datetime.now()
+            
+            # Calculate response time
+            response_time = (end_time - start_time).total_seconds()
+            result["response_time"] = response_time
+            
+            # Add to results and update progress
+            results.append(result)
+            progress["processed_questions"].append(task_id)
+            progress["answers"][task_id] = result.get("answer")
+            
+            logger.info(f"Completed question {task_id} in {response_time:.2f} seconds")
+            
+        except Exception as e:
+            logger.error(f"Error processing question: {str(e)}")
+            results.append({
+                "task_id": question.get("task_id", ""),
+                "question": question.get("question", ""),
+                "answer": f"Error: {str(e)}",
+                "error": str(e)
+            })
+    
+    # Save final progress
+    save_progress(progress, progress_file)
+    
+    return {
+        "results": results,
+        "progress": progress
+    }

requirements.txt

@@ -0,0 +1,18 @@
+# GAIA Benchmark Agent Dependencies
+
+# Core dependencies
+langchain>=0.1.0
+langchain-openai>=0.0.2
+langchain-community>=0.0.1
+openai>=1.3.0
+python-dotenv>=1.0.0
+requests>=2.31.0
+
+# Interface dependencies
+gradio>=3.50.0
+pandas>=2.0.0
+
+# Utility dependencies
+tqdm>=4.66.1
+pydantic>=2.4.0
+tenacity>=8.2.3