Added comments

app.py

@@ -1,3 +1,4 @@
+# Importing necessary libraries and modules
 import os
 import gradio as gr
 import requests
@@ -41,6 +42,7 @@ from tools.fetch_web_page import FetchWebPageTool
 load_dotenv(".env", override=True)
 BRAVE_API_KEY = os.getenv("BRAVE_API")
 
+# Defining the State class which will hold various parameters related to the agent's state
 class State(TypedDict):
     file_path : str
     file: Optional[str]
@@ -55,8 +57,10 @@ class State(TypedDict):
 DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
 
 # --- Basic Agent Definition ---
+# Defining the BasicAgent class which contains the logic for the AI agent
 class BasicAgent:
-    def __init__(self):        
+    def __init__(self):
+        # Initializing the BasicAgent with tools and an LLM (Large Language Model)
         tools = [CodeGenTool(), PythonExecutionTool(temp_dir="./"), YoutubeTranscriptTool(), 
                  AnswerQuestionFromFileTool(), AnswerQuestionTool(), DownloadFile(), 
                  ReverseString(), WebSearchTool(), WikipediaTool(), AnswerExcelTool(), ChessTool(), AudioTool(), FetchWebPageTool()]
@@ -64,12 +68,12 @@ class BasicAgent:
         #llm = ChatGoogleGenerativeAI(
         #    model="gemini-2.0-flash",
         #    temperature=0)
-        llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0)
+        llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0)  # Configuring the LLM
         self.llm_with_tools = llm.bind_tools(tools)
 
-        builder = StateGraph(State)
+        builder = StateGraph(State)  # Building a state graph for handling agent's state transitions
 
-        builder.add_node("assistant", self.assistant)
+        builder.add_node("assistant", self.assistant)  # Adding nodes to the state graph
         builder.add_node("tools", ToolNode(tools))
         builder.add_node("final_answer", BasicAgent.final_answer)
         #builder.add_node("download_file", BasicAgent.download_file_node)
@@ -84,8 +88,8 @@ class BasicAgent:
         #builder.add_edge("parse_img", "assistant")
         #builder.add_edge("parse_pdf", "assistant")
         #builder.add_edge("parse_audio", "assistant")
-        builder.add_conditional_edges(
-            "assistant",
+        builder.add_conditional_edges(  # Adding conditional edges to manage state transitions based on tools' availability
+            "assistant",  # Starting with the assistant node
             tools_condition,
             path_map={
                 "tools":   "tools",
@@ -93,29 +97,31 @@ class BasicAgent:
             }   
         )
 
-        builder.add_edge("tools", "assistant")
+        builder.add_edge("tools", "assistant")  # Defining edges for state transitions
         builder.add_edge("final_answer", END)
 
-        self.react_graph = builder.compile()
+        self.react_graph = builder.compile()  # Compiling the state graph into a reactive graph
 
 
     def __call__(self, question: str, task_id: str, file_name: Optional[str]) -> str:
+        # Handling the agent's main call
         print(f"Agent received question (first 50 chars): {question[:50]}...")
         
-        messages = [HumanMessage(question)]
-        messages = self.react_graph.invoke({"messages": messages, "file_path": file_name, "question": question})
+        messages = [HumanMessage(question)]  # Creating a list of human messages
+        messages = self.react_graph.invoke({"messages": messages, "file_path": file_name, "question": question})  # Invoking the reactive graph with the current state
 
-        with open(f'messages_{task_id}.txt', 'w', encoding='utf-8') as out:
+        with open(f'messages_{task_id}.txt', 'w', encoding='utf-8') as out:  # Writing the messages to a file
             with redirect_stdout(out):
                 for m in messages['messages']:
                     m.pretty_print()
 
-        final_answer = messages["messages"][-1].content.strip()
+        final_answer = messages["messages"][-1].content.strip()  # Extracting the final answer from the messages
         print(f"Final answer is {final_answer}")
         return final_answer
 
 
     def assistant(self, state: State):
+        # Defining the assistant node which processes the state
         if state["file_path"]:
             file_name = state["file_path"].split(".")[0]
             file_extension = state["file_path"].split(".")[1]
@@ -123,7 +129,7 @@ class BasicAgent:
             file_extension = None
             file_name = None
         
-        prompt = f"""
+        prompt = f"""  # Constructing the prompt for the language model
         You are a general AI assistant. When I ask you a question:
 
         Share your reasoning process clearly.
@@ -158,12 +164,13 @@ class BasicAgent:
         Do **NOT** include the file extension in the URL and send WITHOUT MODIFICATION.
         """
 
-        sys_msg = SystemMessage(content=prompt)
+        sys_msg = SystemMessage(content=prompt)  # Creating a system message with the prompt
         
-        time.sleep(40)
+        time.sleep(40)  # Simulating a delay for processing
         return {"messages": [self.llm_with_tools.invoke([sys_msg] + state["messages"])]}
 
     def final_answer(state: State):
+        # Defining the final answer node which processes the state and returns an answer
         system_prompt = f"""
         You will be given an answer and a question. You MUST remove EVERYTHING not needed from the answer and answer the question exactly without reporting "FINAL ANSWER". 
         That is if you are being asked the number of something, you must not return the thought process, but just the number X.
@@ -245,7 +252,7 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
         print(f"An unexpected error occurred fetching questions: {e}")
         return f"An unexpected error occurred fetching questions: {e}", None
 
-    # 3. Run your Agent
+    # Running the agent on the fetched questions
     results_log = []
     answers_payload = []
     print(f"Running agent on {len(questions_data)} questions...")
@@ -270,12 +277,13 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
         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}
+    submission_data = {"username": username.strip(), "agent_code": agent_code, "answers": answers_payload}  # Preparing the data for submission
     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}")
+    # Submitting the answers
     try:
         response = requests.post(submit_url, json=submission_data, timeout=60)
         response.raise_for_status()
@@ -318,12 +326,12 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
         return status_message, results_df
 
 
-# --- Build Gradio Interface using Blocks ---
+# Building the Gradio interface using Blocks
 with gr.Blocks() as demo:
-    gr.Markdown("# Basic Agent Evaluation Runner")
+    gr.Markdown("# Basic Agent Evaluation Runner")  # Title of the interface
     gr.Markdown(
         """
-        **Instructions:**
+        # Instructions for the interface usage
 
         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.
@@ -336,7 +344,7 @@ with gr.Blocks() as demo:
         """
     )
 
-    gr.LoginButton()
+    gr.LoginButton()  # Login button for Hugging Face account
 
     run_button = gr.Button("Run Evaluation & Submit All Answers")
 
@@ -350,6 +358,7 @@ with gr.Blocks() as demo:
     )
 
 if __name__ == "__main__":
+    # Launching Gradio interface for the application
     print("\n" + "-"*30 + " App Starting " + "-"*30)
     # Check for SPACE_HOST and SPACE_ID at startup for information
     space_host_startup = os.getenv("SPACE_HOST")

tools/answer_excel.py

@@ -1,24 +1,28 @@
+# Importing necessary libraries and modules
 from langchain_core.tools.base import BaseTool
 from langchain_experimental.agents.agent_toolkits import create_pandas_dataframe_agent
 import pandas as pd
 from langchain_google_genai import ChatGoogleGenerativeAI
 from langchain.agents.agent_types import AgentType
 
+# Defining the AnswerExcelTool class which extends BaseTool
 class AnswerExcelTool(BaseTool):
     name : str = "answer_excel_tool"
     description: str = "Given the path to a file containing an excel file and a query, this tool tries to get an answer by querying the excel file. Provide the whole question in input. Another agent will later break down the task."
 
     def _run(self, query: str, file_path: str) -> str:
-        df = pd.read_excel(file_path)
+        # Method to run the tool, using a query and the file path to an Excel file
+        df = pd.read_excel(file_path)  # Reading the Excel file into a DataFrame
 
-        llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash", temperature=0)
+        llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash", temperature=0)  # Configuring the LLM
 
         agent_executor = create_pandas_dataframe_agent(
+            # Creating a Pandas DataFrame agent with the LLM and DataFrame
             llm,
             df,
             agent_type=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
             verbose=True,
-            allow_dangerous_code=True # IMPORTANT: Understand the risks
+            allow_dangerous_code=True  # IMPORTANT: Understand the risks
         )
 
-        return agent_executor(query)
+        return agent_executor(query)  # Executing the query using the agent

tools/answer_question.py

@@ -1,3 +1,4 @@
+# Importing necessary libraries and modules
 from langchain_google_genai import ChatGoogleGenerativeAI
 from pydantic import PrivateAttr
 from langchain_core.tools.base import BaseTool
@@ -6,6 +7,7 @@ from langchain_openai import ChatOpenAI
 import time
 from openai import OpenAI
 
+# Defining the AnswerQuestionTool class which extends BaseTool
 class AnswerQuestionTool(BaseTool):
     name : str = "answer_question_tool"
     description: str = "Use this tool to answer any elementary question that you can solve without needing access to any external tool. Simply provide the question in input, reporting the whole question including desired output format. You can use this tool for example for vegetable classification."
@@ -13,6 +15,7 @@ class AnswerQuestionTool(BaseTool):
     _system_prompt = PrivateAttr()
 
     def __init__(self):
+        # Initializing the AnswerQuestionTool
         super().__init__()
         #self._llm = ChatGoogleGenerativeAI(
         #    model="gemini-2.0-flash",
@@ -30,15 +33,18 @@ class AnswerQuestionTool(BaseTool):
                                             """)
         
     def _run(self, question: str) -> str:
+        # Method to run the tool and get an answer for the given question
         human_message = HumanMessage(
+            # Creating a human message with the question content
             content=[
                 {"type": "text", "text": question},
             ]
         )
 
-        time.sleep(5)
-        client = OpenAI()
+        time.sleep(5)  # Adding a delay for rate limits
+        client = OpenAI()  # Initializing the OpenAI client
         response = client.responses.create(
+            # Creating a response using OpenAI's API
             model="o4-mini",
             messages = [
                 {
@@ -50,4 +56,4 @@ class AnswerQuestionTool(BaseTool):
             )
         #response = self._llm.invoke([self._system_prompt, human_message])
 
-        return response
+        return response  # Returning the response from the OpenAI API

tools/answer_question_from_file.py

@@ -1,3 +1,4 @@
+# Importing necessary libraries and modules
 from langchain_core.tools.base import BaseTool
 from langchain_core.messages import AnyMessage, SystemMessage, HumanMessage
 from langchain_google_genai import ChatGoogleGenerativeAI
@@ -7,15 +8,16 @@ from dotenv import load_dotenv
 import whisper
 import base64
 
-load_dotenv(".env", override=True)
+load_dotenv(".env", override=True)  # Loading environment variables
 
-AZURE_OPENAI_ENDPOINT = os.getenv("AZURE_OPENAI_ENDPOINT")
+AZURE_OPENAI_ENDPOINT = os.getenv("AZURE_OPENAI_ENDPOINT")  # Fetching Azure OpenAI endpoint from environment
 AZURE_OPENAI_API_KEY = os.getenv("AZURE_OPENAI_API_KEY")
 OPENAI_API_VERSION = os.getenv("OPENAI_API_VERSION_GEN", "2023-12-01-preview") # Default API version
 # AZURE_OPENAI_DEPLOYMENT_NAME will be used as the 'model' for API calls
 AZURE_OPENAI_DEPLOYMENT_NAME = "gpt-4.1"
 
 
+# Defining the AnswerQuestionFromFileTool class which extends BaseTool
 class AnswerQuestionFromFileTool(BaseTool):
     name: str = "answer_question_from_file_tool"
     description: str = """
@@ -29,8 +31,9 @@ class AnswerQuestionFromFileTool(BaseTool):
     _llm = PrivateAttr()
 
     def __init__(self):
+        # Initializing the AnswerQuestionFromFileTool
         super().__init__()
-        self._llm = ChatGoogleGenerativeAI(
+        self._llm = ChatGoogleGenerativeAI(  # Setting up the LLM with specific parameters
             model="gemini-2.0-flash",
             temperature=0)
 

tools/audio_tool.py

@@ -1,3 +1,4 @@
+# Importing necessary libraries and modules
 from langchain_core.tools.base import BaseTool
 import whisper
 from langchain_google_genai import ChatGoogleGenerativeAI
@@ -9,11 +10,13 @@ import torch
 from langchain_openai import ChatOpenAI
 import time
 
+# Defining the AudioTool class which extends BaseTool
 class AudioTool(BaseTool):
     name : str = "answer_question_audio_tool"
     description: str = "This tool will reply to a query based on the audio given the path of a locally stored file. This file DOES NOT DOWNLOAD the file from the web. Run the download_file_tool first" 
 
     def _run(self, query: str, file_path: str) -> str:
+        # Method to transcribe the provided audio file and answer the query using LLM
         try:
             #pipe = pipeline(
             #    task="automatic-speech-recognition",
@@ -24,7 +27,7 @@ class AudioTool(BaseTool):
             #)         
             #result = pipe(str(Path("./") / Path(file_path)), return_timestamps=True)
             model = whisper.load_model("base")
-            result = model.transcribe(audio=str(Path("./") / Path(file_path)), language='en')
+            result = model.transcribe(audio=str(Path("./") / Path(file_path)), language='en')  # Transcribing the audio using Whisper model
         except Exception as e:
             print("Exception", e)
 
@@ -48,9 +51,9 @@ Always prioritize accuracy and strict adherence to the user's stated needs befor
         time.sleep(5)
         llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0)
         
-        response = llm.invoke([system_message, human_message])
+        response = llm.invoke([system_message, human_message])  # Getting the response from the LLM
 
-        return response
+        return response  # Returning the response from the LLM
 
 
 

tools/chess_tool.py

@@ -1,16 +1,21 @@
+# Importing necessary libraries and modules
 from langchain_core.tools.base import BaseTool
 from chessimg2pos import predict_fen
 from stockfish import Stockfish
 import chess
 
+# Defining the ChessTool class which extends BaseTool
 class ChessTool(BaseTool):
     name : str = "chess_tool"
     description : str = "Given the path of an image, this tool returns the best next move that can be done on the chessboard. You must give ONLY the PATH of the image here! Pass in input b or w as color_turn based on whose turn is it. Use w if unspecified."
 
     def _run(self, img_path: str, color_turn: str) -> str:
+        # Method to analyze the chessboard image and return the best move
         # Get the FEN string
-        fen = predict_fen("./downloaded_files/image.png")
+        fen = predict_fen("./downloaded_files/image.png")  # Predicting the FEN string from the chessboard image
 
+        # The fen predicted is always with a1 at the bottom left.
+        # If it's black turn than the bottom left is h8, you need to reverse the positions retrieved.
         if color_turn == "b":
             ranks = fen.split('/')
             rotated_matrix = []
@@ -25,17 +30,18 @@ class ChessTool(BaseTool):
         fen = f"{final_fen} {color_turn} - - 0 1"
 
         try:
+            # Initializing Stockfish chess engine
             stockfish = Stockfish(path="C:/Users/FORMAGGA/Documents/personal/stockfish-windows-x86-64-avx2/stockfish/stockfish-windows-x86-64-avx2.exe")
 
             stockfish.set_fen_position(fen)
 
-            next_move = str(stockfish.get_best_move())
+            next_move = str(stockfish.get_best_move())  # Getting the best move from Stockfish
         except Exception as e:
             print("Exception", e)
             raise e
         
-        piece = stockfish.get_what_is_on_square(next_move[:2])
+        piece = stockfish.get_what_is_on_square(next_move[:2])  # Getting the piece on the starting square of the move
 
-        next_move_fen = piece.name + next_move[2:]
+        next_move_fen = piece.name + next_move[2:]  # Constructing the FEN representation of the move
 
-        return next_move_fen
+        return next_move_fen  # Returning the best move in FEN format

tools/code_exec.py

@@ -1,3 +1,4 @@
+# Importing necessary libraries and modules
 from langchain_core.tools.base import BaseTool, ToolException
 from typing import Optional
 import subprocess
@@ -5,12 +6,11 @@ import tempfile
 import os
 from pydantic import PrivateAttr
 
+# Defining the PythonExecutionTool class which extends BaseTool
 class PythonExecutionTool(BaseTool):
-    """
-    A LangChain “tool” that takes a string of Python code,
-    writes it to a temporary .py file, executes it in a fresh
-    Python subprocess, captures stdout/stderr, and returns the result.
-    """
+    # A LangChain “tool” that takes a string of Python code,
+    # writes it to a temporary .py file, executes it in a fresh
+    # Python subprocess, captures stdout/stderr, and returns the result.
 
     name : str = "python_execution"
     description : str = (
@@ -28,6 +28,7 @@ class PythonExecutionTool(BaseTool):
         *,
         temp_dir: Optional[str] = None
     ):
+        
         """
         :param python_executable: Path to the Python interpreter to invoke.
         :param timeout: Maximum seconds to allow the code to run.

tools/download_file.py

@@ -64,8 +64,6 @@ class DownloadFile(BaseTool):
                 return "The file extension is not valid."
         else:
             msg = "There was an error downloading the file."
-            file = None
-            b64_file = None
 
             return msg
 

tools/fetch_web_page.py

@@ -1,12 +1,15 @@
+# Importing necessary libraries and modules
 from langchain_core.tools.base import BaseTool
 from typing import List
 import requests
 
+# Defining the FetchWebPageTool class which extends BaseTool
 class FetchWebPageTool(BaseTool):
     name : str = "fetch_web_page_tool"
     description: str = "Provided the urls of 1 or more web pages, this tool returns the full content of the web page. This tool needs to be called AFTER calling the web_page_tool. It's important to fetch only pages which are useful to your task!"
 
     def _run(self, urls: List[str]) -> List[str]:
-        pages = [requests.get(url).text for url in urls]
+        # Method to fetch the full content of the provided web pages
+        pages = [requests.get(url).text for url in urls]  # Fetching the content of each URL
 
-        return pages
+        return pages  # Returning the fetched content of the web pages

tools/web_search.py

@@ -1,3 +1,4 @@
+# Importing necessary libraries and modules
 from langchain_core.tools.base import BaseTool
 from dotenv import load_dotenv
 from langchain_community.utilities import DuckDuckGoSearchAPIWrapper
@@ -9,44 +10,22 @@ from langchain_community.document_loaders import WebBaseLoader
 import json
 import requests
 
-load_dotenv(".env", override=True)
-
+load_dotenv(".env", override=True)  # Loading environment variables
 
+# Defining the WebSearchTool class which extends BaseTool
 class WebSearchTool(BaseTool):
     name: str = "web_search_tool"
     description: str = "Perform a web search and extract concise factual answers. The query should be concise, below 400 characters. Use for online facts not in GAIA/Wikipedia—e.g. sports stats, Olympic participation, published papers, museum specimen locations, competition winners, and other up-to-date info."
-    #_search: BraveSearch = PrivateAttr()
     _search: TavilySearch = PrivateAttr()
 
     def __init__(self):
+        # Initializing the WebSearchTool
         super().__init__()
-        #wrapper = DuckDuckGoSearchAPIWrapper(region="en", max_results=2)
-        #self._search = DuckDuckGoSearchResults(api_wrapper=wrapper, output_format="json")
-
-        self._search = TavilySearch(max_results=3, topic="general")
-
-    def _run_old(self, query: str) -> str:
-        json_str = self._search.run(query)          # list[Document]
-        docs = json.loads(json_str)
-        urls = [doc["link"] for doc in docs]
-        print(urls)
-        pages = [requests.get(url) for url in urls]
-
-        res = "\n\n---\n\n".join(
-            page.text for page in pages
-        )
-
-        try:
-            with open("./web_search.txt", "wt", encoding="utf-8") as f:
-                f.write(str(res))
-        except Exception as e:
-            print(e)
-
-        return res
+        self._search = TavilySearch(max_results=3, topic="general")  # Setting up the TavilySearch with specific parameters
     
     def _run(self, query: str) -> dict:
-        # import pdb;pdb.set_trace()
-        search_results = []
-        search_results.append(self._search.run(query))
+        # Method to run the web search tool with the given query
+        search_results = []  # Initializing the list for search results
+        search_results.append(self._search.run(query))  # Performing the search and adding the results to the list
 
-        return search_results
+        return search_results  # Returning the search results

tools/wikipedia.py

@@ -1,3 +1,4 @@
+# Importing necessary libraries and modules
 from langchain_community.tools import WikipediaQueryRun
 from langchain_community.utilities import WikipediaAPIWrapper
 from pydantic import PrivateAttr
@@ -7,33 +8,32 @@ import requests
 from bs4 import BeautifulSoup
 import wikipedia
 
-
+# Defining the WikipediaTool class which extends BaseTool
 class WikipediaTool(BaseTool):
     name: str = "wikipedia_tool"
     description: str = "Search Wikipedia for a given query, retrieving the corresponding page's HTML content. The query should not contain any noise and ask for something specific."
-    #_wikipedia = PrivateAttr()
 
     def __init__(self):
+        # Initializing the WikipediaTool
         super().__init__()
-        #self._wikipedia = WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper(lang="en", doc_content_chars_max=100000, top_k_results=1))
-
 
     def _run(self, query: str):
-        print(f"wikipedia_search_html called with query='{query}'")
+        # Method to run the Wikipedia tool with the given query
+        print(f"wikipedia_search_html called with query='{query}'")  # Logging the query
         # Step 1: Get Wikipedia HTML
-        page = wikipedia.page(query)
-        html = page.html()
+        page = wikipedia.page(query)  # Fetching the Wikipedia page for the query
+        html = page.html()  # Extracting the HTML content of the page
 
         # Step 2: Parse HTML
-        soup = BeautifulSoup(html, "html.parser")
-        content_div = soup.find("div", class_="mw-parser-output")
+        soup = BeautifulSoup(html, "html.parser")  # Parsing the HTML content
+        content_div = soup.find("div", class_="mw-parser-output")  # Finding the content division
         # content_div = soup.find("table", class_="wikitable")
         if not content_div:
             return ""
 
         # Step 3: Find all tags to remove (style, script, sup, infobox, etc.)
-        to_decompose = []
-        for tag in content_div.find_all():
+        to_decompose = []  # Collecting tags to be removed
+        for tag in content_div.find_all():  # Looping through all tags in the content division
             tag_classes = tag.get("class", [])
             if (
                 tag.name in ["style", "script", "sup"]
@@ -42,7 +42,7 @@ class WikipediaTool(BaseTool):
                 to_decompose.append(tag)
 
         # Remove them after collecting
-        for tag in to_decompose:
+        for tag in to_decompose:  # Decompose and remove the collected tags
             tag.decompose()
         
-        return str(content_div)
+        return str(content_div)  # Returning the cleaned content division as string

tools/youtube_transcript.py

@@ -15,10 +15,13 @@ class YoutubeTranscriptTool(BaseTool):
         Returns:
             The transcript as a single string.
         """
+        # Get the video ID from the youtube URL
         re_match = re.search(r"watch\?v=([^&]+)", youtube_link)
         if not re_match:
             raise ValueError(f"Invalid YouTube URL: {youtube_link}")
         video_id = re_match.group(1)
+
+        # Initialize the transcriptAPI and retrieve the transcript for the given videoID
         ytt_api = YouTubeTranscriptApi()
         fetched_transcript = ytt_api.fetch(video_id)