First commit

.gitignore

@@ -0,0 +1,10 @@
+# secrets
+.env
+# logs
+*.log
+# vscode
+.vscode/
+# Python
+__pycache__
+#files
+files/

agent.py

@@ -0,0 +1,151 @@
+import os
+from typing import Optional, TypedDict, Literal
+from langgraph.graph import MessagesState, StateGraph, START, END
+from langgraph.prebuilt import ToolNode
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import HumanMessage, SystemMessage
+from logging_config import logger
+from tools import (
+    python_tool,
+    reverse_tool,
+    excel_file_to_markdown,
+    sum_numbers,
+    web_search,
+    get_wikipedia_info,
+    ask_audio_model
+    )
+from chess_tool import chess_tool
+
+MAX_ITERATIONS = 5
+SYSTEM_PROMPT = \
+"""You are a general AI assistant. This is a GAIA problem to solve, be succinct in your answer.
+YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. 
+If you are asked for a number, don't use comma to write your number neither use units such as $ or percent sign unless 
+specified otherwise. 
+If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities), and write the digits 
+in plain text unless specified otherwise. 
+If you need to access a file, use the provided task_id as a parameter to the corresponding tool, unless a url is provided.
+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.
+"""
+
+llm_gemini = ChatGoogleGenerativeAI(
+    model="gemini-2.5-flash",
+    include_thoughts=False,
+    temperature=0,
+    max_output_tokens=256,
+    timeout=60,  # The maximum number of seconds to wait for a response.
+    max_retries=2,
+)
+
+llm_openai = ChatOpenAI(
+    model="openai/gpt-oss-120b:together",
+    temperature=0,
+    max_tokens=256, # type: ignore
+    timeout=60,
+    max_retries=2,
+    api_key=os.getenv("HF_TOKEN"),
+    base_url="https://router.huggingface.co/v1",
+)
+
+llm = llm_openai
+
+tools = [python_tool,
+    reverse_tool,
+    excel_file_to_markdown,
+    sum_numbers,
+    web_search,
+    get_wikipedia_info,
+    ask_audio_model,
+    chess_tool]
+
+llm_with_tools = llm.bind_tools(tools)
+
+class InputState(TypedDict):
+    question: str
+    task_id: str
+
+# Define the state type with annotations
+class AgentState(MessagesState):
+    system_message: str
+    question: str
+    task_id: str
+    final_answer: str
+    iterations: int
+    error: Optional[str]
+
+class OutputState(TypedDict):
+    final_answer: str
+    error: Optional[str]
+
+def input(state: InputState) -> AgentState:
+    question = state["question"]
+    messages = [
+        SystemMessage(content=SYSTEM_PROMPT),
+        HumanMessage(content=question)
+    ]
+    return {"messages": messages, # type: ignore
+            "iterations": 0} 
+
+def agent(state: AgentState) -> AgentState:
+    logger.info(f"LLM invoked: {state['question'][:50]=}{state['task_id']=}")
+    question = state["question"]
+    try:
+        result = llm_with_tools.invoke(state["messages"])
+        logger.info(f"model metadata = {result.usage_metadata}") # type: ignore
+        logger.info(f"LLM answer: {result.content}")
+        # Append the new message to the messages list
+        messages = state["messages"] + [result]
+        return {"messages": messages} # type: ignore
+    except Exception as e:
+        logger.error(f"LLM invocation failed: {e}")
+        return {"error": str(e)} # type: ignore
+
+def increment_iterations(state: AgentState) -> AgentState:
+    # Additional node to increment the iteration count
+    iterations = state.get("iterations", 0) + 1
+    return {"iterations": iterations} #type: ignore
+
+def route_tools(state: AgentState) -> Literal["tools", "final_output"]:
+    """
+    Decide if we should continue execution or stop.
+    """
+    messages = state["messages"]
+    ai_message = messages[-1]
+    iterations = state["iterations"]
+    
+    if iterations > MAX_ITERATIONS:
+        return "final_output"  # Stop execution if max iterations are reached
+    if hasattr(ai_message, "tool_calls") and len(ai_message.tool_calls) > 0: # type: ignore
+        return "tools"
+    return "final_output"  # Stop execution if no tool calls are present
+
+def final_output(state: AgentState) -> OutputState:
+    try:
+        messages = state["messages"]
+        ai_message = messages[-1]
+        return {"final_answer": ai_message.content} # type: ignore
+    except Exception as e:
+        return {"error": e} # type: ignore
+
+builder = StateGraph(AgentState)
+tool_node = ToolNode(tools=tools)
+builder.add_node("input", input)
+builder.add_node("agent", agent)
+builder.add_node("increase", increment_iterations)
+builder.add_node("tools", tool_node)
+builder.add_node("final_output", final_output)
+# Define edges for the standard flow
+builder.add_edge(START, "input")
+builder.add_edge("input", "agent")
+builder.add_conditional_edges("agent", 
+                              route_tools,
+                              {"tools": "increase",
+                               "final_output": "final_output"}
+                            )
+builder.add_edge("increase", "tools")
+builder.add_edge("tools", "agent")
+builder.add_edge("final_output", END)
+builder.compile()
+graph = builder.compile()

answers.json

@@ -0,0 +1 @@
+[{"task_id": "8e867cd7-cff9-4e6c-867a-ff5ddc2550be", "submitted_answer": "No answer provided"}, {"task_id": "a1e91b78-d3d8-4675-bb8d-62741b4b68a6", "submitted_answer": "No answer provided"}, {"task_id": "2d83110e-a098-4ebb-9987-066c06fa42d0", "submitted_answer": "No answer provided"}, {"task_id": "cca530fc-4052-43b2-b130-b30968d8aa44", "submitted_answer": "No answer provided"}, {"task_id": "4fc2f1ae-8625-45b5-ab34-ad4433bc21f8", "submitted_answer": "No answer provided"}, {"task_id": "6f37996b-2ac7-44b0-8e68-6d28256631b4", "submitted_answer": "No answer provided"}, {"task_id": "9d191bce-651d-4746-be2d-7ef8ecadb9c2", "submitted_answer": "No answer provided"}, {"task_id": "cabe07ed-9eca-40ea-8ead-410ef5e83f91", "submitted_answer": "No answer provided"}, {"task_id": "3cef3a44-215e-4aed-8e3b-b1e3f08063b7", "submitted_answer": "No answer provided"}, {"task_id": "99c9cc74-fdc8-46c6-8f8d-3ce2d3bfeea3", "submitted_answer": "No answer provided"}, {"task_id": "305ac316-eef6-4446-960a-92d80d542f82", "submitted_answer": "No answer provided"}, {"task_id": "f918266a-b3e0-4914-865d-4faa564f1aef", "submitted_answer": "No answer provided"}, {"task_id": "3f57289b-8c60-48be-bd80-01f8099ca449", "submitted_answer": "No answer provided"}, {"task_id": "1f975693-876d-457b-a649-393859e79bf3", "submitted_answer": "No answer provided"}, {"task_id": "840bfca7-4f7b-481a-8794-c560c340185d", "submitted_answer": "No answer provided"}, {"task_id": "bda648d7-d618-4883-88f4-3466eabd860e", "submitted_answer": "No answer provided"}, {"task_id": "cf106601-ab4f-4af9-b045-5295fe67b37d", "submitted_answer": "No answer provided"}, {"task_id": "a0c07678-e491-4bbc-8f0b-07405144218f", "submitted_answer": "No answer provided"}, {"task_id": "7bd855d8-463d-4ed5-93ca-5fe35145f733", "submitted_answer": "No answer provided"}, {"task_id": "5a0c1adf-205e-4841-a666-7c3ef95def9d", "submitted_answer": "No answer provided"}]

app.py

@@ -0,0 +1,216 @@
+import os
+import gradio as gr
+import requests
+import inspect
+import pandas as pd
+import json
+from logging_config import logger  # Import the shared logger
+
+# (Keep Constants as is)
+# --- Constants ---
+DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+
+# --- Basic Agent Definition ---
+# ----- THIS IS WERE YOU CAN BUILD WHAT YOU WANT ------
+# --- Basic Agent Definition ---
+# ----- THIS IS WERE YOU CAN BUILD WHAT YOU WANT ------
+class BasicAgent:
+    def __init__(self):
+        from agent import graph  # Importing here to avoid circular imports
+        print("BasicAgent initialized.")
+        self.graph = graph
+    def __call__(self, item: dict) -> str:
+        """Process the input item and return a response.
+        Args:
+            item (dict): Input dictionary containing the question.
+        """
+        question = item.get("question", "")
+        task_id = item.get("task_id", "")
+        file_name = item.get("file_name", "")
+        if file_name:
+            # file_name provided, adding task_id to question for context
+            question += f"\nTask ID: {task_id}"
+        logger.info(f"Agent received question (first 50 chars): {question[:50]}...")
+        # fixed_answer = "This is a default answer."
+        # print(f"Agent returning fixed answer: {fixed_answer}")
+        answer = self.graph.invoke({"question": question, "task_id": task_id})
+        return answer.get("final_answer", "No answer generated.") # type: ignore
+
+def run_all(profile: gr.OAuthProfile | None):
+    """
+    Fetches all questions, runs the BasicAgent on them caching 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 = BasicAgent()
+    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: # type: ignore
+         print(f"Error decoding JSON response from questions endpoint: {e}")
+         print(f"Response text: {response.text[:500]}") # type: ignore
+         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
+def submit_all(profile: gr.OAuthProfile | None):
+    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=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)

chess_tool.py

@@ -0,0 +1,43 @@
+from chessimg2pos import predict_fen
+from stockfish import Stockfish
+from langchain_core.tools import tool
+from logging_config import logger  # Import the shared logger
+
+# Adapted from Alberto Formaggio's GAIA agents
+# https://github.com/AlbertoFormaggio1/gaia-ai-agents/blob/main/tools/chess_tool.py
+
+@tool
+def chess_tool(task_id: str, color_to_move: str) -> str:
+    """
+    Given an image of a chessboard, and the color to move, 
+    predict the FEN notation and suggest the best move.
+    
+    Args:
+        task_id (str): The identifier for the chessboard image.
+        color_to_move (str): 'w' or 'b', the color to move ('white' or 'black').
+        
+    Returns:
+        str: Best move suggestion.
+    """
+    logger.info(f"Invoking chess tool with task_id: {task_id!r} and color_to_move: {color_to_move!r}")
+
+    if color_to_move not in ['w', 'b']:
+        return "Error: color_to_move must be 'w' or 'b'."
+    
+    predicted_fen = predict_fen(f'./files/{task_id}.png', output_type='simple')
+
+    if color_to_move == 'b':
+        rows = reversed(predicted_fen.split('/'))
+        board = '/'.join([row[::-1] for row in rows])
+    elif color_to_move == 'w':
+        board = predicted_fen
+
+    fen = f"{board} {color_to_move} -- 0 1"
+
+    # Initialize Stockfish engine (ensure the path to executable is correct)
+    stockfish = Stockfish(path="/home/jmlv/engines/stockfish/stockfish")
+    stockfish.set_fen_position(fen)
+    best_move = stockfish.get_best_move()
+    logger.info(f"Best move determined: {best_move!r}")
+
+    return best_move

logging_config.py

@@ -0,0 +1,15 @@
+import logging
+from logging.handlers import RotatingFileHandler
+
+# Set up logging
+#logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+if not logger.hasHandlers():
+    rotation_handler = RotatingFileHandler("app.log", maxBytes=1048576, backupCount=1)
+    console_handler = logging.StreamHandler()
+    formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    rotation_handler.setFormatter(formatter)
+    console_handler.setFormatter(formatter)
+    logger.addHandler(rotation_handler)
+    logger.addHandler(console_handler)

requirements.txt

@@ -0,0 +1,15 @@
+beautifulsoup4==4.13.5
+chessimg2pos==0.1.4
+gradio==5.47.0
+langchain_community==0.3.29
+langchain_core==0.3.76
+langchain_experimental==0.3.4
+langchain_google_genai==2.1.12
+langchain_openai==0.3.33
+langchain_tavily==0.2.11
+langgraph==0.6.7
+pandas==2.3.2
+python-dotenv==1.1.1
+Requests==2.32.5
+stockfish==3.28.0
+wikipedia==1.4.0

tools.py

@@ -0,0 +1,245 @@
+import os
+from io import StringIO
+import re
+import base64
+from langchain_core.tools import tool
+from langchain_tavily import TavilySearch
+from langchain_experimental.utilities import PythonREPL
+from langchain_community.retrievers import WikipediaRetriever
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_core.messages import HumanMessage
+from typing import List
+import wikipedia
+from bs4 import BeautifulSoup, Tag
+import json
+import pandas as pd
+from logging_config import logger  # Import the shared logger
+from dotenv import load_dotenv
+load_dotenv()
+
+@tool
+def python_tool(code: str) -> str:
+    """A Python shell. Use this to execute python commands. 
+    Input should be an str with a valid python script. 
+    If you want to see the output of a value, 
+    you should print it out with `print(...)`."""
+
+    logger.info(f"Invoking Python REPL tool{code!r}")
+    repl = PythonREPL()
+    try:
+        # print("Running the Python REPL tool")
+        # print(code)
+        result = repl.run(code)
+    except BaseException as e:
+        return f"Failed to execute. Error: {e!r}"
+    return f"Result of code execution: {result}"
+
+@tool
+def reverse_tool(question: str) -> str:
+    """Reverses the input string."""
+    logger.info(f"Invoking reverse tool with question: {question!r}")
+    return question[::-1]
+
+@tool
+def excel_file_to_markdown(task_id):
+    """Given a task_id corresponding to an Excel file,
+    fetch the file and convert its content to markdown format."""
+    import pandas as pd
+
+    path = f"./files/{task_id}.xlsx"
+    df = pd.read_excel(path)
+    logger.info(f"Converted Excel file {path} to markdown")
+    return df.to_markdown()
+
+@tool
+def sum_numbers(all_numbers: List[float]) -> float:
+    """
+    Sums a list of numbers and returns the result.
+
+    Args:
+        all_numbers ('list' of float): A list of numbers.
+
+    """
+    logger.info(f"Summing numbers: {all_numbers}")
+    numbers_list = [float(x) for x in all_numbers]
+    result = sum(numbers_list)
+    return result
+
+@tool
+def web_search(question: str) -> str: # Tool expects arguments, not the whole state
+    """Perform a web search using TavilySearch and return relevant documents.
+    Args:
+        question (str): The query for the web search.
+    Returns:
+        web_search_result (str): The result of the web search.
+    """
+    logger.info(f"Performing web search for query: {question}")
+
+    web_tool = TavilySearch(chunks_per_source=3,
+                            max_results=3, 
+                            include_answer=True,
+                            include_raw_content="markdown",
+                            search_depth="advanced"
+                            )
+    try:
+        search_results = web_tool.invoke(question)
+        logger.info(f"Web search completed with {len(search_results.get('results', []))} results")
+        if search_results.get('answer'):
+            logger.info(f"Web search answer length: {len(search_results['answer'])}")
+            return search_results['answer'] # type: ignore       
+        retrieved_docs = [{"url": sr.get('url', ""), "content": sr.get('content', "")} \
+                          for sr in search_results.get('results', [])]
+        web_search_result = json.dumps(retrieved_docs, indent=2)
+        return web_search_result # type: ignore
+    
+    except Exception as e:
+        logger.error(f"Web search failed: {e}")
+        # Return an empty list or specific error document if the search fails
+        return f"Web search failed: {e}"
+
+# This tool is not needed for the assignment???
+@tool
+def wiki_search(query: str) -> str:
+    """Search Wikipedia for query and return maximum 2 results
+    
+    Args:
+        query (str): query to search on Wikipedia
+    Returns:
+        wiki_result (str): result of search
+    """
+    try:
+        retriever = WikipediaRetriever(top_k_results=2, doc_content_chars_max=20000) # type: ignore
+        docs = retriever.invoke(query)
+        wiki_result = "\n".join([f"- {doc.page_content} (source: {doc.metadata.get('source', 'unknown')})" for doc in docs])
+        url = docs[0].metadata.get('source', 'unknown') if docs else 'unknown'
+
+        logger.info(f"Wikipedia search completed for query: {query} with length {len(wiki_result)}")
+        return wiki_result # type: ignore
+    except Exception as e:
+        return f"wiki_search failed {e}"
+
+@tool
+def get_wikipedia_info(query: str) -> str:
+    """
+    Fetches and parses all HTML tables and their preceding Hx headers
+    from a given Wikipedia page. 
+    Use this to get structured data from Wikipedia pages, such as lists of items, 
+    tables of statistics, discographies, etc.
+    Args:
+        query (str): The query to search on Wikipedia.    
+    Returns:
+        formatted_output (str): a string representation of the structured data,
+        formatted in a Markdown-like style.
+    """
+    logger.info(f"Tool get_wikipedia_info invoked with query: {query!r}")
+    try:
+        page_title = wikipedia.search(query, results=1)[0]
+        page_content = wikipedia.page(page_title, auto_suggest=False).html()
+        logger.info(f"Fetching Wikipedia page for title: {page_title!r}")
+        soup = BeautifulSoup(page_content, 'html.parser')
+
+        # main_content = soup.find('div', {'id': 'mw-content-text'})
+        # if not main_content:
+        #     return "Could not find the main content area on the page."
+
+        # Compile a regular expression for h1 to h6 tags
+        heading_pattern = re.compile('^h[1-6]$')
+        
+        # Find all headings and tables in one pass
+        elements = soup.find_all([heading_pattern, 'table'])
+        
+        extracted_data = []
+        current_headers = {} # Using a dictionary for flexibility
+        
+        for element in elements:
+            if isinstance(element, Tag):
+                if re.match(heading_pattern, element.name):
+                    current_headers[element.name] = element.get_text().strip()
+                    # Reset lower-level headers when a higher-level one is found
+                    for i in range(int(element.name[1]) + 1, 7):
+                        current_headers.pop(f'h{i}', None)
+                elif element.name == 'table' and 'wikitable' in element.get('class', []): # type: ignore
+                    try:
+                        df = pd.read_html(StringIO(str(element)))[0] # type: ignore
+                        table_info = {
+                            'headers': current_headers.copy(),
+                            'table_data': df.to_markdown()
+                        }
+                        extracted_data.append(table_info)
+                    except ValueError:
+                        continue
+        
+        if not extracted_data:
+            return "No 'wikitable' found on the specified page."
+        
+        # Format the extracted data into a readable, markdown string
+        formatted_output = "### Extracted Tables with Headers\n\n"
+        
+        for i, item in enumerate(extracted_data):
+            formatted_output += f"--- Table {i+1} ---\n"
+            
+            # Sort headers by level (h1, h2, h3...) to ensure correct order
+            sorted_headers = sorted(item['headers'].items(), key=lambda x: int(x[0][1]))
+            
+            for header_tag, header_text in sorted_headers:
+                header_level = len(header_tag)
+                formatted_output += f"{'#' * (header_level + 2)} {header_text}\n"
+            
+            formatted_output += f"```\n{item['table_data']}\n```\n\n"
+            
+        return formatted_output
+
+    except wikipedia.exceptions.PageError:
+        return "Wikipedia page not found."
+    except Exception as e:
+        return f"An error occurred: {e}"
+
+
+@tool
+def ask_audio_model(query: str, task_id: str) -> str:
+    """
+    Processes an audio query by sending both a text prompt and an task_id 
+    (associated with an audio file)
+    to a generative AI model, and returns the model's response.
+
+    Args:
+        query (str): The text prompt or question for the model.
+        task_id (str): The identifier used to load the audio file (MP3) in the downloaded files directory.
+
+    Returns:
+        str: The response generated by the AI model based on the provided text and audio.
+    """
+
+    logger.info(f"audio_model called with query='{query[:30]}...'")
+
+    if "GOOGLE_API_KEY" not in os.environ:
+        os.environ["GOOGLE_API_KEY"] = os.environ["GEMINI_API_KEY"]
+
+    llm = ChatGoogleGenerativeAI(
+        model="gemini-2.5-flash-lite-preview-06-17",
+        temperature=0,
+        max_tokens=None,
+        timeout=60,  # Added a timeout
+        max_retries=2,
+    )
+
+    audio_file_path = f"./files/{task_id}.mp3" # Assuming MP3 for a general use case
+
+    audio_mime_type = "audio/mpeg"
+
+    with open(audio_file_path, "rb") as audio_file:
+        encoded_audio = base64.b64encode(audio_file.read()).decode("utf-8")
+
+    message = HumanMessage(
+        content=[
+            {"type": "text", "text": query},
+            {
+                "type": "media",
+                "data": encoded_audio,  # Use base64 string directly
+                "mime_type": audio_mime_type,
+            },
+        ]
+    )
+    response = llm.invoke([message])  
+    logger.info(f"ask_audio_model metadata = {response.usage_metadata}") # type: ignore
+    return response.content # type: ignore