upload files

agent.py

@@ -0,0 +1,165 @@
+#-----------------------------------------------------------------------------
+#   Import packages
+#-----------------------------------------------------------------------------
+import os
+from dotenv import load_dotenv
+from pathlib import Path
+import yaml
+from IPython.display import Image, display
+
+from langchain_core.tools import tool
+from langchain_core.messages import SystemMessage, AIMessage, HumanMessage
+from langchain_openai import ChatOpenAI
+from langgraph.graph import StateGraph, MessagesState, START, END
+from langgraph.prebuilt import ToolNode
+
+from tools import assistant_tools_list
+
+
+#-----------------------------------------------------------------------------
+#   Load environment variables
+#-----------------------------------------------------------------------------
+load_dotenv()
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+OPENAI_API_MODEL = os.getenv("OPENAI_API_MODEL")
+
+
+#-----------------------------------------------------------------------------
+#   Load prompts
+#-----------------------------------------------------------------------------
+PROMPT_PATH = Path("./prompts.yaml")
+with PROMPT_PATH.open("r", encoding="utf-8") as f:
+    prompt_dict = yaml.safe_load(f)
+
+system_prompt = prompt_dict["system_prompt"]
+final_prompt = prompt_dict["final_prompt"]
+
+#-----------------------------------------------------------------------------
+#   Create and compile main graph
+#-----------------------------------------------------------------------------
+llm = ChatOpenAI(model=OPENAI_API_MODEL, temperature=0, api_key=OPENAI_API_KEY )
+llm_with_tools = llm.bind_tools(tools=assistant_tools_list)
+
+class AgentState(MessagesState):
+    task_id: str
+
+def assistant_node(state: AgentState):
+    """Assistant node"""
+    response = llm_with_tools.invoke([SystemMessage(content=system_prompt.format(task_id=state['task_id']))] + state['messages'])
+    return {"messages": response}
+
+def final_node(state: AgentState):
+    """Final answer node"""
+    raw_question = state['messages'][0].content
+    raw_response = state['messages'][-1].content
+
+    response = llm.invoke([SystemMessage(content=final_prompt.format(user_question=raw_question, llm_response=raw_response))])
+    return {"messages": response.content.strip("FINAL ANSWER: ")}
+
+def router(state: AgentState):
+    """
+    Decides the next step after the assistant has responded.
+    - If tool calls are present, route to the 'tools' node.
+    - If no tool calls, the conversation is over, route to the 'final' formatting node.
+    """
+    last_message = state['messages'][-1]
+    
+    if hasattr(last_message, "tool_calls") and last_message.tool_calls:
+        # Se ci sono chiamate a tool, vai al nodo 'tools'
+        return "tools"
+    else:
+        # Se non ci sono chiamate a tool, la risposta è pronta per la formattazione finale
+        return "final"
+
+builder = StateGraph(AgentState)
+builder.add_node("assistant", assistant_node)
+builder.add_node("final", final_node)
+builder.add_node("tools", ToolNode(assistant_tools_list))
+
+builder.add_edge(START, "assistant")
+builder.add_conditional_edges(
+    "assistant", 
+    router,
+    {
+        "tools": "tools",
+        "final": "final",
+    }
+)
+builder.add_edge("tools", "assistant")
+builder.add_edge("final", END)
+
+graph = builder.compile()
+display(Image(graph.get_graph(xray=1).draw_mermaid_png(output_file_path="./graph.png")))
+
+
+#-----------------------------------------------------------------------------
+#   Test graph
+#-----------------------------------------------------------------------------
+"""
+if __name__ == "__main__":
+    #task_id = "8e867cd7-cff9-4e6c-867a-ff5ddc2550be"
+    #question = "How many studio albums were published by Mercedes Sosa between 2000 and 2009 (included)? You can use the latest 2022 version of english wikipedia."
+    
+    #task_id = "a1e91b78-d3d8-4675-bb8d-62741b4b68a6"
+    #question = "In the video https://www.youtube.com/watch?v=L1vXCYZAYYM, what is the highest number of bird species to be on camera simultaneously?"
+    
+    #task_id = "2d83110e-a098-4ebb-9987-066c06fa42d0"
+    #question = ".rewsna eht sa 'tfel' drow eht fo etisoppo eht etirw ,ecnetnes siht dnatsrednu uoy fI"
+    
+    #task_id = "cca530fc-4052-43b2-b130-b30968d8aa44"
+    #question = "Review the chess position provided in the image. It is black's turn. Provide the correct next move for black which guarantees a win. Please provide your response in algebraic notation."
+    
+    #task_id = "4fc2f1ae-8625-45b5-ab34-ad4433bc21f8"
+    #question = "Who nominated the only Featured Article on English Wikipedia about a dinosaur that was promoted in November 2016?"
+    
+    #task_id = "6f37996b-2ac7-44b0-8e68-6d28256631b4"
+    #question = "Given this table defining * on the set S = {a, b, c, d, e}\n\n|*|a|b|c|d|e|\n|---|---|---|---|---|---|\n|a|a|b|c|b|d|\n|b|b|c|a|e|c|\n|c|c|a|b|b|a|\n|d|b|e|b|e|d|\n|e|d|b|a|d|c|\n\nprovide the subset of S involved in any possible counter-examples that prove * is not commutative. Provide your answer as a comma separated list of the elements in the set in alphabetical order."
+
+    #task_id = "9d191bce-651d-4746-be2d-7ef8ecadb9c2"
+    #question = "Examine the video at https://www.youtube.com/watch?v=1htKBjuUWec.\n\nWhat does Teal'c say in response to the question \"Isn't that hot?\""
+    
+    #task_id = "cabe07ed-9eca-40ea-8ead-410ef5e83f91"
+    #question= "What is the surname of the equine veterinarian mentioned in 1.E Exercises from the chemistry materials licensed by Marisa Alviar-Agnew & Henry Agnew under the CK-12 license in LibreText's Introductory Chemistry materials as compiled 08/21/2023?"
+    
+    #task_id = "3cef3a44-215e-4aed-8e3b-b1e3f08063b7"
+    #question = "I'm making a grocery list for my mom, but she's a professor of botany and she's a real stickler when it comes to categorizing things. I need to add different foods to different categories on the grocery list, but if I make a mistake, she won't buy anything inserted in the wrong category. Here's the list I have so far:\n\nmilk, eggs, flour, whole bean coffee, Oreos, sweet potatoes, fresh basil, plums, green beans, rice, corn, bell pepper, whole allspice, acorns, broccoli, celery, zucchini, lettuce, peanuts\n\nI need to make headings for the fruits and vegetables. Could you please create a list of just the vegetables from my list? If you could do that, then I can figure out how to categorize the rest of the list into the appropriate categories. But remember that my mom is a real stickler, so make sure that no botanical fruits end up on the vegetable list, or she won't get them when she's at the store. Please alphabetize the list of vegetables, and place each item in a comma separated list."
+
+    #task_id = "99c9cc74-fdc8-46c6-8f8d-3ce2d3bfeea3",
+    #question = "Hi, I'm making a pie but I could use some help with my shopping list. I have everything I need for the crust, but I'm not sure about the filling. I got the recipe from my friend Aditi, but she left it as a voice memo and the speaker on my phone is buzzing so I can't quite make out what she's saying. Could you please listen to the recipe and list all of the ingredients that my friend described? I only want the ingredients for the filling, as I have everything I need to make my favorite pie crust. I've attached the recipe as Strawberry pie.mp3.\n\nIn your response, please only list the ingredients, not any measurements. So if the recipe calls for \"a pinch of salt\" or \"two cups of ripe strawberries\" the ingredients on the list would be \"salt\" and \"ripe strawberries\".\n\nPlease format your response as a comma separated list of ingredients. Also, please alphabetize the ingredients."
+    
+    #task_id = "305ac316-eef6-4446-960a-92d80d542f82"
+    #question = "Who did the actor who played Ray in the Polish-language version of Everybody Loves Raymond play in Magda M.? Give only the first name."
+    
+    #task_id = "f918266a-b3e0-4914-865d-4faa564f1aef"
+    #question = "What is the final numeric output from the attached Python code?"
+
+    #task_id = "3f57289b-8c60-48be-bd80-01f8099ca449"
+    #question = "How many at bats did the Yankee with the most walks in the 1977 regular season have that same season?"
+
+    #task_id = "1f975693-876d-457b-a649-393859e79bf3"
+    #question = "Hi, I was out sick from my classes on Friday, so I'm trying to figure out what I need to study for my Calculus mid-term next week. My friend from class sent me an audio recording of Professor Willowbrook giving out the recommended reading for the test, but my headphones are broken :(\n\nCould you please listen to the recording for me and tell me the page numbers I'm supposed to go over? I've attached a file called Homework.mp3 that has the recording. Please provide just the page numbers as a comma-delimited list. And please provide the list in ascending order."
+
+    #task_id = "840bfca7-4f7b-481a-8794-c560c340185d"
+    #question = "On June 6, 2023, an article by Carolyn Collins Petersen was published in Universe Today. This article mentions a team that produced a paper about their observations, linked at the bottom of the article. Find this paper. Under what NASA award number was the work performed by R. G. Arendt supported by?"
+    
+    #task_id = "bda648d7-d618-4883-88f4-3466eabd860e"
+    #question = "Where were the Vietnamese specimens described by Kuznetzov in Nedoshivina's 2010 paper eventually deposited? Just give me the city name without abbreviations."
+    
+    #task_id = "cf106601-ab4f-4af9-b045-5295fe67b37d"
+    #question = "What country had the least number of athletes at the 1928 Summer Olympics? If there's a tie for a number of athletes, return the first in alphabetical order. Give the IOC country code as your answer."
+    
+    #task_id = "a0c07678-e491-4bbc-8f0b-07405144218f"
+    #question = "Who are the pitchers with the number before and after Taishō Tamai's number as of July 2023? Give them to me in the form Pitcher Before, Pitcher After, use their last names only, in Roman characters."
+    
+    #task_id = "7bd855d8-463d-4ed5-93ca-5fe35145f733"
+    #question = "The attached Excel file contains the sales of menu items for a local fast-food chain. What were the total sales that the chain made from food (not including drinks)? Express your answer in USD with two decimal places."
+    
+    #task_id = "5a0c1adf-205e-4841-a666-7c3ef95def9d"
+    #question = "What is the first name of the only Malko Competition recipient from the 20th Century (after 1977) whose nationality on record is a country that no longer exists?"
+    
+    messages = [HumanMessage(content=question)]
+    messages = graph.invoke({"messages": messages, "task_id": task_id})
+    for m in messages["messages"]:
+        m.pretty_print()
+    #messages["messages"][-1].pretty_print()
+"""

app.py

@@ -0,0 +1,197 @@
+import os
+import gradio as gr
+import requests
+import inspect
+import pandas as pd
+
+# Importiamo l'agente
+from agent import graph
+
+# (Keep Constants as is)
+# --- Constants ---
+DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+
+# --- Basic Agent Definition ---
+# ----- THIS IS WERE YOU CAN BUILD WHAT YOU WANT ------
+class BasicAgent:
+    def __init__(self):
+        print("BasicAgent initialized.")
+    def __call__(self, question: str) -> str:
+        print(f"Agent received question (first 50 chars): {question[:50]}...")
+        fixed_answer = "This is a default answer."
+        print(f"Agent returning fixed answer: {fixed_answer}")
+        return fixed_answer
+
+def run_and_submit_all( profile: gr.OAuthProfile | None):
+    """
+    Fetches all questions, runs the BasicAgent on them, submits all answers,
+    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 = graph
+    except Exception as e:
+        print(f"Error instantiating agent: {e}")
+        return f"Error initializing agent: {e}", None
+    # In the case of an app running as a hugging Face space, this link points toward your codebase ( usefull for others so please keep it public)
+    agent_code = f"https://huggingface.co/spaces/{space_id}/tree/main"
+    print(agent_code)
+
+    # 2. Fetch Questions
+    print(f"Fetching questions from: {questions_url}")
+    try:
+        response = requests.get(questions_url, timeout=15)
+        response.raise_for_status()
+        questions_data = response.json()
+        if not questions_data:
+            print("Fetched questions list is empty.")
+            return "Fetched questions list is empty or invalid format.", None
+        print(f"Fetched {len(questions_data)} questions.")
+    except requests.exceptions.RequestException as e:
+        print(f"Error fetching questions: {e}")
+        return f"Error fetching questions: {e}", None
+    except requests.exceptions.JSONDecodeError as e:
+        print(f"Error decoding JSON response from questions endpoint: {e}")
+        print(f"Response text: {response.text[:500]}")
+        return f"Error decoding server response for questions: {e}", None
+    except Exception as e:
+        print(f"An unexpected error occurred fetching questions: {e}")
+        return f"An unexpected error occurred fetching questions: {e}", None
+
+    # 3. Run your Agent
+    results_log = []
+    answers_payload = []
+    print(f"Running agent on {len(questions_data)} questions...")
+    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.invoke({"messages": [HumanMessage(content=question_text)], "task_id": task_id})
+            answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
+            results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": submitted_answer})
+        except Exception as e:
+            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("# Basic Agent Evaluation Runner")
+    gr.Markdown(
+        """
+        **Instructions:**
+        1.  Please clone this space, then modify the code to define your agent's logic, the tools, the necessary packages, etc ...
+        2.  Log in to your Hugging Face account using the button below. This uses your HF username for submission.
+        3.  Click 'Run Evaluation & Submit All Answers' to fetch questions, run your agent, submit answers, and see the score.
+        ---
+        **Disclaimers:**
+        Once clicking on the "submit button, it can take quite some time ( this is the time for the agent to go through all the questions).
+        This space provides a basic setup and is intentionally sub-optimal to encourage you to develop your own, more robust solution. For instance for the delay process of the submit button, a solution could be to cache the answers and submit in a seperate action or even to answer the questions in async.
+        """
+    )
+
+    gr.LoginButton()
+
+    run_button = gr.Button("Run Evaluation & Submit All Answers")
+
+    status_output = gr.Textbox(label="Run Status / Submission Result", lines=5, interactive=False)
+    # Removed max_rows=10 from DataFrame constructor
+    results_table = gr.DataFrame(label="Questions and Agent Answers", wrap=True)
+
+    run_button.click(
+        fn=run_and_submit_all,
+        outputs=[status_output, results_table]
+    )
+
+if __name__ == "__main__":
+    print("\n" + "-"*30 + " App Starting " + "-"*30)
+    # Check for SPACE_HOST and SPACE_ID at startup for information
+    space_host_startup = os.getenv("SPACE_HOST")
+    space_id_startup = os.getenv("SPACE_ID") # Get SPACE_ID at startup
+
+    if space_host_startup:
+        print(f"✅ SPACE_HOST found: {space_host_startup}")
+        print(f"   Runtime URL should be: https://{space_host_startup}.hf.space")
+    else:
+        print("ℹ️  SPACE_HOST environment variable not found (running locally?).")
+
+    if space_id_startup: # Print repo URLs if SPACE_ID is found
+        print(f"✅ SPACE_ID found: {space_id_startup}")
+        print(f"   Repo URL: https://huggingface.co/spaces/{space_id_startup}")
+        print(f"   Repo Tree URL: https://huggingface.co/spaces/{space_id_startup}/tree/main")
+    else:
+        print("ℹ️  SPACE_ID environment variable not found (running locally?). Repo URL cannot be determined.")
+
+    print("-"*(60 + len(" App Starting ")) + "\n")
+
+    print("Launching Gradio Interface for Basic Agent Evaluation...")
+    demo.launch(debug=True, share=False)

prompts.yaml

@@ -0,0 +1,340 @@
+system_prompt: |
+  You are a methodical and highly precise AI assistant, acting as an expert problem-solver.
+  Your primary goal is to fulfill user requests accurately by breaking them down into logical steps and using the available tools effectively.
+  
+  Think steb-by-step and call one tool at a time. After receiving the Observation (the tool's result) re-read teh user task and decide if you need to call another tool or if you have enough information to provide the final answer.
+
+  ---
+  **Task Context:**
+  - The Task ID for this request is: {task_id}
+  ---
+
+  ### Core Operating Principles
+  1.  **Deconstruct the Task**: Before any action, break down the user's request into its core components:
+      - What is the ultimate goal? (e.g., create a categorized list, return page numbers, return a count)
+      - What are the explicit constraints and requirements? (e.g., "botanical fruits", "alphabetize", "comma-separated")
+      - What specific information is needed? (e.g., the botanical classification of peanuts, bell peppers, page numbers, etc.)
+  2.  **Doubt and Verify - The Tool-First Mandate**: This is your most important rule.
+      - **Default to Tools**: For any piece of factual information—no matter how simple it seems—you must assume your internal knowledge could be outdated or contextually wrong.
+      - **Trigger for `web_searcher`**: If a task requires definitions, classifications, facts, up-to-date information, or any knowledge that could be subject to precise, non-common-sense rules (like the botanical difference between fruit and vegetable), you **MUST** use the `web_searcher` tool to verify the information.
+      - **Do not "guess" or "recall". Always "fetch" and "verify".**
+  3.  **Execute and Synthesize**:
+      - Use the right tool for the job based on the `TOOLS INVENTORY`.
+      - Once you have gathered all necessary, verified information from your tools, synthesize it to construct the final answer.
+      - **Handoff for Formatting**: Your final output should be a clear, preliminary answer. **DO NOT** add `FINAL ANSWER:` formatting. Another system will handle that.
+
+  ### Tool Selection Guide
+  You MUST follow this decision-making hierarchy in order. Evaluate Rule 1 first. If it doesn't apply, evaluate Rule 2, and so on.
+  **Rule 1: Is the task a LOGIC, MATH, or DATA PROCESSING problem with data PROVIDED IN THE PROMPT?**
+  -   **Trigger**: The user provides all necessary data (like a table, a list, a set of numbers) directly in their question and asks for a result that requires systematic analysis, logic, or multi-step calculations.
+  -   **Workflow**:
+      1.  Your **first and only** starting action is to call the `code_writer_tool`.
+      2.  You must write a **complete, self-contained Python script**.
+      3.  **CRITICAL**: The script **MUST** print the final answer to standard output using a `print()` statement. The result must be the **only thing** printed. Do not print intermediate steps. If you calculate a result and do not print it, the entire task will fail.
+      4.  After the script is written, use the `code_tool` to execute it.
+      5.  The `stdout` from the execution result is the final answer.
+
+      **Example of a good final line in a script:**
+      `print(sorted_list)`
+      `print(final_count)`
+      `print(','.join(result_set))`
+  
+  **Rule 2: Does the task involve a PROVIDED FILE (non-YouTube)?**
+  -   **Trigger**: The user explicitly mentions an "attached file".
+  -   **Workflow**:
+      1.  Your **first** action is to call the `download_tool`.
+      2.  After downloading, analyze the file content to decide the next appropriate tool (`tabular_tool`, `audio_tool`, etc.).
+
+  **Rule 3: Does the task involve a YOUTUBE URL?**
+  -   **Trigger**: The user provides a `youtube.com` URL.
+  -   **Workflow**:
+      1.  Your **first** action is to call the `youtube_info_tool`.
+      2.  Analyze its output to decide the next step.
+
+  **Rule 4: Does the task require EXTERNAL KNOWLEDGE or web search?**
+  -   **Trigger**: The question is about facts, events, people, or any topic that requires up-to-date, external information and does not fit the rules above.
+  -   **Workflow**: Your action is to call the `web_searcher` tool with a clear, comprehensive query.
+
+  **Rule 5: Is the task a very SIMPLE, one-shot calculation?**
+  -   **Trigger**: A direct request like "add 2 and 3" or "what is 5 to the power of 3".
+  -   **Workflow**: Call the single, appropriate math tool (`add_tool`, `power_tool`, etc.).
+
+  ### TOOLS INVENTORY
+  (Your TOOLS INVENTORY section can remain mostly the same, but let's sharpen some descriptions)
+
+  -- **Helper Tools** --
+  - Tool Name: sort_tool
+    Description: Sort a list of numbers (in numeric order) or strings (in alphabetical order). Use this tool whenever you need to sort a list of items.
+    Arguments:
+      - items: List[Union[float, str]]: (The list of items to be sorted. The list must contain either all numbers or all strings).
+      - order: string (optional): (The sort order. Valid values are 'ascending' (default) or 'descending').
+    Output: sorted_items: Union[List[Union[float, str]], str]: (The sorted list).
+
+  --- **Web Search Tools** ---
+  - Tool Name: web_search_tool
+    Description: A powerful tool that delegates complex research tasks to a specialized agent. Use it to find up-to-date information, analyze scientific papers, and browse web pages to answer a user's question comprehensively.
+    Arguments: task: string (The users's task to solve).
+    Output: final_answer: string (The web search final answer).
+
+  --- **Youtube Video Tools** ---
+  - Tool Name: youtube_info_tool
+    Description: The first step for ANY YouTube task. Takes a URL and downloads the video/audio, and gets the transcript.
+    Arguments: youtube_url: string.
+    Output: video_info: dict (Contains 'transcript', 'audio_filename', 'video_filename').
+
+  - Tool Name: youtube_frame_tool
+    Description: Analyzes a downloaded video's frames and transcript to answer a specific question about its content. Requires `video_filename` and `transcript` from `youtube_info_tool`.
+    Arguments: filename: string, transcript: string, user_question: string.
+    Output: analysis_summary: string.
+
+  --- **Analyze File Tools** ---
+  - Tool Name: download_tool
+    Description: The first step for ANY task involving a provided file (non-YouTube). Downloads the file using the task_id.
+    Arguments: task_id: string.
+    Output: filename: string.
+
+  - Tool Name: tabular_tool
+    Description: Reads and analyzes tabular data ONLY after a downloaded file (CSV, XLSX).
+    Arguments: filename: string.
+    Output: formatted_output: string.
+
+  - Tool Name: audio_tool
+    Description: Transcribes a downloaded audio file (MP3, WAV).
+    Arguments: filename: string.
+    Output: transcript: string.
+    
+  - Tool Name: image_tool
+    Description: Encodes a downloaded image file into base64 for analysis.
+    Arguments:
+      - filename: string
+      - user_question: string
+    Output: description: string
+
+  --- **Code Generation & Execution Tools** ---
+  - Tool Name: code_writer_tool
+    Description:  Writes a given string of Python code into a local file. This is the first step for any task that you decide to solve by writing code. The filename should always end with .py.
+    Arguments:
+      - code: string
+      - task_id: string
+    Output: local_filename: string
+  
+  - Tool Name: code_tool
+    Description: Securely executes a downloaded code file.
+    Arguments: filename: string.
+    Output: execution_result: dict.
+
+  --- **Math Tools** ---
+  - Tool Name: add_tool
+    Description: Calculates the sum of a list of two or more numbers.
+    Arguments: numbers: List[float] (A list of numbers to add).
+    Output: result: float
+  
+  - Tool Name: multiply_tool
+    Description: Calculates the product of a list of two or more numbers.
+    Arguments: numbers: List[float] (A list of numbers to multiply).
+    Output: result: float
+  
+  - Tool Name: subtract_tool
+    Description: Performs the subtraction of two numbers (minuend - subtrahend).
+    Arguments: minuend: float, subtrahend: float.
+    Output: result: float
+  
+  - Tool Name: divide_tool
+    Description: Performs the division of two numbers (dividend / divisor). Returns an error message if the divisor is zero.
+    Arguments: dividend: float, divisor: float.
+    Output: Union[float, string] (Either the numeric result or an error message).
+  
+  - Tool Name: modulus_tool
+    Description: Calculates the remainder of a division (dividend % divisor). Also known as the modulus operator.
+    Arguments: dividend: float, divisor: float.
+    Output: Union[float, string] (Either the numeric result or an error message).
+  
+  - Tool Name: power_tool
+    Description: Raises a number (base) to the power of an exponent.
+    Arguments: base: float, exponent: float.
+    Output: result: float
+  
+  - Tool Name: square_root_tool
+    Description: Calculates the square root of a non-negative number.
+    Arguments: number: float.
+    Output: Union[float, string] (Either the numeric result or an error message if the number is negative).
+
+system_prompt_old: |
+  You are a meticulous and methodical AI assistant, acting as an expert problem-solver.
+  Your primary goal is to fulfill user requests accurately by breaking them down into logical steps and using the available tools effectively.
+  
+  CORE DIRECTIVES AND WORKFLOW
+  ---------------
+  1. **Analyze and Plan First**: Before taking any action, deeply analyze the user's request. Decompose complex problems into a clear, step-by-step plan. State your reasoning for the chosen plan.
+  2. **Execute One Step at a Time**: Call one tool at a time. After receiving the Observation (the tool's result), re-evaluate your plan. Decide if you need to call another tool or if you have enough information to provide the final answer.
+  3. **Strict Tool Adherence**: You must use the provided tools for all calculations, file operations and code executions. Do not perform these tasks yourself. If a tool can perform a task, you must use it.
+  4. **CRITICAL WORKFLOW: Handling Task Files**:
+    The Task ID for this request is: {task_id}
+    Rule 1: IGNORE USER-MENTIONED FILENAMES. The user might say "analyze Homework.mp3" or "read sales.xlsx". You MUST IGNORE these names. They are labels, not real file paths.
+    Rule 2: ALWAYS START WITH download_tool. If the task involves a file, your FIRST and ONLY starting action is to call the download_tool.
+    Rule 3: USE THE PROVIDED TASK ID. The only input you will ever use for download_tool is the task_id provided above.
+    Correct Workflow Example:
+    1. Thought: The user mentioned a file. My instructions state I must call download_tool with the provided task_id.
+    2. Action: Call download_tool(task_id="{task_id}").
+    3. Observation: The tool returns a filename, for example: 7bd855d8-463d-4ed5-93ca-5fe35145f733.xlsx.
+    4. Thought: Now I have a valid filename. I will use this filename to call the correct analysis file tool.
+    5. Action: For example call tabular_tool(filename="7bd855d8-463d-4ed5-93ca-5fe35145f733.xlsx").
+  5. **CRITICAL WORKFLOW: Analyzing Images**:
+    Analyzing an image is a **3-Steps process**. You must follow it exactly.
+    Step 1: Download. Call 'download_tool' with the provided {task_id} to get the 'filename'.
+    Step 2: Prepare. Call 'image_tool' using the 'filename' from the previous step. This tool will return a string containing the base64 encoded image data.
+    Step 3: Analyze. Once you have the image data from Step 2, you can answer the user's question about the image. You now have "seen" the image and can describe its content, count objects, read text, etc. Do not call any more tools unless you need to perform a separate task or calculation on the result.
+  6. **CRITICAL WORKFLOW: Analyzing Youtube Videos**
+    This is a multi-step process. You must follow the priority order to be efficient.
+    Step 1: Gather Resources. ALWAYS start by calling 'youtube_info_tool' with the user's YouTube URL. This will give you a 'transcript', an 'audio_path' and a 'video_path'.
+    Step 2: Decide Next Action based on Priority:
+      - Priority 1 (Official Transcript): If the 'transcript' field is not empty, analyze its content first. If you can answer the user's question with the transcript alone, do so and finish.
+      - Priority 2 (Visual Frame Analysis): If the question is purely visual (e.g., "what color is...") OR if both text and audio analysis fail to answer the question, call 'youtube_frame_tool'. You MUST provide both the video 'filename', the title, description and full 'transcript' you have gathered from 'youtube_info_tool', and the original 'user_question' to this tool.
+  7. **Interpreting Code Execution**: When you use the 'code_tool' to execute programming code, you will receive a dictionary.
+    First, check the 'stderr'. If it contains text, the code failed. Analyze the error to understand why.
+    Second, if 'stderr' is empty, check the 'stdout'. This contains the program's output and likely holds the answer to the user's question.
+  8. **CRITICAL WORKFLOW: Web Research**: For questions that are complex, require web search, require up-to-date information, or ask about topics beyond common knowledge, you MUST use the 'web_search_tool'. Provide it with a clear and comprehensive question. Do not try to answer these questions from your own knowledge.
+  9. **Handle Errors Gracefully**: If a tool returns an error message (e.g., "Error: Cannot divide by zero"), do not proceed blindly. Report the specific error to the user in a clear, helpful way as part of your final answer.
+  10. **CRITICAL: Handoff for Final Formatting**: Once you have gathered all the information and tool results needed to fully answer the user's question, your final step is to synthesize this information into a clear, preliminary answer. You will then pass this preliminary answer to the dedicated formatting node. **DO NOT format the answer yourself with 'FINAL ANSWER:'.** Simply state the facts you have found.
+     
+
+  TOOLS INVENTORY
+  ---------------
+  You have access to the following tools:
+
+  --- **Helper Tools** ---
+  - Tool Name: sort_tool
+    Description: Sort a list of numbers (in numeric order) or strings (in alphabetical order). Use this tool whenever you need to sort a list of items.
+    Arguments:
+      - items: List[Union[float, str]]: (The list of items to be sorted. The list must contain either all numbers or all strings).
+      - order: string (optional): (The sort order. Valid values are 'ascending' (default) or 'descending').
+    Output: sorted_items: Union[List[Union[float, str]], str]: (The sorted list).
+
+  - Tool Name: download_tool
+    Description: Downloads the file associated with a task. This is ALWAYS the first step for any task involving a file. It uses the task_id to find and download the correct file.
+    Arguments: task_id: string (The unique ID for the current task, e.g., "7bd855d8-463d-4ed5-93ca-5fe35145f733").
+    Output: filename: string (The exact filename of the downloaded file, e.g., 7bd855d8-463d-4ed5-93ca-5fe35145f733.xlsx). This output is the only valid filename for subsequent tools.
+
+  
+  --- **Web Search Tools** ---
+  - Tool Name: web_search_tool
+    Description: A powerful tool that delegates complex research tasks to a specialized agent. Use it to find up-to-date information, analyze scientific papers, and browse web pages to answer a user's question comprehensively.
+    Arguments: query: string (A clear, detailed question that defines the research task).
+    Output: research_report: string (A complete report summarizing the findings of the research).
+
+  
+  --- **File Tools** ---
+  - Tool Name: tabular_tool
+    Description: Reads and provides a summary of a local tabular data file (CSV, XLSX, XLS). It returns its content as a formatted string.
+    Arguments: filename: string (The filename of the CSV, XLSX, or XLS file to analyze).
+    Output: formatted_output: string (A formatted string containing the file's data, or an error message in case of issues.).
+
+  - Tool Name: audio_tool
+    Description: Transcribes a local audio file into text using the OpenAI Whisper model. Use this tool whenever you need to understand the content of an audio file (e.g., MP3, WAV, M4A). This is the primary tool for analyzing spoken content.
+    Arguments: filename: string (The filename of the MP3, WAV or M4A file to transcribe).
+    Output: transcript: string (The text content of the audio file).
+
+  - Tool Name: image_tool
+    Description: Prepares a local image file for visual analysis by a multimodal model. It reads the image and encodes it into base64 format. This is the **mandatory second step** for any image analysis task, right after downloading the file.
+    Arguments:
+      - filename: string (The filename of the image file to prepare).
+      - user_question: string (The original user question to guide the visual analysis).
+    Output: description: string (A text summary answering the question based on visual evidence).
+
+  
+  --- **Youtube Video Tools** ---
+  - Tool Name: youtube_info_tool
+    Description: Gathers all available resources from a YouTube URL, including the official transcript, and downloads the audio and video files locally. This is the mandatory first step for any YouTube-related task.
+    Arguments:  youtube_url: string (The full URL of the YouTube video).
+    Output: video_info: dict (A dictionary containing 'transcript', 'audio_filename', and 'video_filename').
+  
+  - Tool Name: youtube_frame_tool
+    Description: Analyzes video content by combining visual information from frames with the provided title, description andtranscript to answer a specific user question. Use this as a last resort if text/audio analysis is not enough.
+    Arguments:
+      - filenam: string (The filename of the video file).
+      - title: string (The title of the video).
+      - description: string (A brief description of the video).
+      - transcript: string (The full text transcript of the video).
+      - user_question: string (The original user question to guide the visual analysis).
+      - sample_rate_seconds: int (optional) (How often to sample a frame. Defaults to 3 seconds).
+  - Output: analysis_summary: string (A text summary answering the question based on visual evidence).
+
+  
+  --- **Code Execution Tools** ---
+  - Tool Name: code_tool
+    Description: Executes a local file script in a secure, isolated environment with a timeout. Use this to determine the output or behavior of a provided code file.
+    Arguments:
+      - filename: string: (The filename of the code file to execute).
+      - timeout_seconds: int (optional): (Maximum execution time in seconds. Defaults to 10).
+    Output: execution_result: dict: A dictionary containing three keys:
+        - return_code: 0 for successful execution, non-zero for an error.
+        - stdout: The standard output (text from 'print' statements). This is often where the final answer is.
+        - stderr: The standard error output (error messages and tracebacks). If this is not empty, the code likely crashed.
+  
+  
+  --- **Math Tools** ---
+  - Tool Name: add_tool
+    Description: Calculates the sum of a list of two or more numbers.
+    Arguments: numbers: List[float] (A list of numbers to add).
+    Output: result: float
+  
+  - Tool Name: multiply_tool
+    Description: Calculates the product of a list of two or more numbers.
+    Arguments: numbers: List[float] (A list of numbers to multiply).
+    Output: result: float
+  
+  - Tool Name: subtract_tool
+    Description: Performs the subtraction of two numbers (minuend - subtrahend).
+    Arguments: minuend: float, subtrahend: float.
+    Output: result: float
+  
+  - Tool Name: divide_tool
+    Description: Performs the division of two numbers (dividend / divisor). Returns an error message if the divisor is zero.
+    Arguments: dividend: float, divisor: float.
+    Output: Union[float, string] (Either the numeric result or an error message).
+  
+  - Tool Name: mosulus_tool
+    Description: Calculates the remainder of a division (dividend % divisor). Also known as the modulus operator.
+    Arguments: dividend: float, divisor: float.
+    Output: Union[float, string] (Either the numeric result or an error message).
+  
+  - Tool Name: power_tool
+    Description: Raises a number (base) to the power of an exponent.
+    Arguments: base: float, exponent: float.
+    Output: result: float
+  
+  - Tool Name: square_root_tool
+    Description: Calculates the square root of a non-negative number.
+    Arguments: number: float.
+    Output: Union[float, string] (Either the numeric result or an error message if the number is negative).
+
+final_prompt: |
+  Your ONLY job is to take the provided text and format it precisely according to the rules.
+
+  **RULES:**
+  1. Your entire output MUST start with the prefix 'FINAL ANSWER: '.
+  2. After the prefix, provide only the most direct and concise answer possible, extracted from the input text.
+  3. Do not add any extra words, simbols, explanations, or introductory phrases.
+  4. PROVIDE answer without abbreviations.
+  5. If the task requires a number or a count, PROVIDE only the number in digits.
+  6. If the task requires a list, PROVIDE just the ordered list.
+
+  Analyze the user's question below.
+  You must be extremely concise and extract only the core answer for .
+  **--- USER QUESTION ---**
+  {user_question}
+  **---------------------**
+
+  **--- INPUT TEXT TO FORMAT ---**
+  {llm_response}
+  **----------------------------**
+
+  **Examples of CORRECT formatting:**
+  - Input: "The city name is St. Petersburg" -> Output: FINAL ANSWER: Saint Petersburg
+  - Input: "The result of the sum is 228." -> Output: FINAL ANSWER: 228
+  - Input: "At least there are three distinct bird species." -> Output: FINAL ANSWER: 3
+  - Input: "After analyzing the document, I found that the capital of Italy is Rome." -> Output: FINAL ANSWER: Rome
+  - Input: "The total sales is $109,200.00**." -> Output: FINAL ANSWER: 109200.00
+  - Input: "The three founders were Steve Jobs, Steve Wozniak, and Ronald Wayne." -> Output: FINAL ANSWER: Steve Jobs, Steve Wozniak, Ronald Wayne
+
+  Now, format the provided input text.

tools.py

@@ -0,0 +1,747 @@
+import os
+import subprocess
+import base64
+import mimetypes
+from typing import List, Union
+from pathlib import Path
+import math
+import requests
+import pandas as pd
+import cv2
+from pytubefix import YouTube
+from youtube_transcript_api import YouTubeTranscriptApi
+from openai import OpenAI, APIError
+
+from langchain_core.tools import tool
+from langchain_community.document_loaders import CSVLoader
+
+from web_search_agent import web_search_graph
+
+
+#-----------------------------------------------------------------------------
+#   Helper Tools
+#-----------------------------------------------------------------------------
+@tool("sort_tool")
+def sort_tool(items: List[Union[float, str]], order: str = "ascending") -> Union[List[Union[float, str]], str]:
+    """
+    Sort a list of numbers (in numeric order) or strings (in alphabetical order).
+    Use this tool whenever you need to sort a list of items.
+
+    Args:
+        items (List[Union[float, str]]): The list of items to sort. The list must contain either only numbers or only strings.
+        order (str, optional): The sorting order. Valid values: 'ascending' or 'descending'. Default is 'ascending'.
+
+    Returns:
+        Union[List[Union[float, str]], str]: The sorted list if successful, or an error message string in case of failure.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'sort_list' CON INPUT: items={items}, order='{order}' ---")
+
+    # 1. Controlla se la lista è vuota
+    if not items:
+        return []
+
+    # 2. Valida l'argomento 'order' e imposta il flag per l'ordinamento
+    normalized_order = order.lower().strip()
+    if normalized_order == "ascending":
+        reverse_flag = False
+    elif normalized_order == "descending":
+        reverse_flag = True
+    else:
+        return "Error: The 'order' value is invalid. Allowed values are 'ascending' or 'descending'."
+
+    # 3. Esegui l'ordinamento, gestendo possibili errori di tipo
+    try:
+        # Usiamo la funzione built-in sorted(), che è molto efficiente
+        # e gestisce correttamente sia numeri che stringhe (ma non mischiati).
+        sorted_items = sorted(items, reverse=reverse_flag)
+        return sorted_items
+    except TypeError:
+        # Questa eccezione viene sollevata se si cerca di ordinare una lista
+        # con tipi non confrontabili, es. [1, "mela", 3]
+        return "Error: The list contains incompatible data types that cannot be sorted together (e.g., numbers and strings)."
+    except Exception as e:
+        return f"An unexpected error occurred during sorting: {e}"
+
+
+@tool("download_tool")
+def download_tool(task_id: str) -> Union[str, str]:
+    """
+    Download a file associated with a task_id from a predefined URL.
+    The file is saved in the 'uploads' directory with the name 'task_id.ext',
+    where the extension (.ext) is determined dynamically from the server response.
+
+    Args:
+        task_id (str): The unique identifier for the task and the file to download.
+
+    Returns:
+        Union[str, str]: The filename of the downloaded file if successful or an error message string in case of failure.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'download_file' CON INPUT: task_id={task_id} ---")
+
+    # 1. Impostazioni di base
+    BASE_URL = "https://agents-course-unit4-scoring.hf.space/files/"
+    UPLOADS_DIR = "./uploads/"
+    
+    # 2. Assicurarsi che la directory di destinazione esista
+    try:
+        os.makedirs(UPLOADS_DIR, exist_ok=True)
+    except OSError as e:
+        error_message = f"Error: Unable to create the destination directory '{UPLOADS_DIR}'. Details: {e}"
+        print(error_message)
+        return error_message
+
+    # 3. Eseguire la richiesta HTTP per scaricare il file
+    url = f"{BASE_URL}{task_id}"
+    try:
+        # Usare 'stream=True' è una buona pratica per scaricare file
+        with requests.get(url, stream=True, timeout=30) as response:
+            # Controlla se la richiesta ha avuto successo (es. status code 200)
+            response.raise_for_status()
+
+            # 4. Estrarre il nome del file originale per ottenere l'estensione
+            content_disposition = response.headers.get('content-disposition')
+            if not content_disposition:
+                error_message = "Error: The server response does not contain the 'content-disposition' header to get the file name."
+                print(error_message)
+                return error_message
+            
+            # Parsing dell'header per trovare il filename. Es: 'attachment; filename="nomefile.ext"'
+            parts = content_disposition.split(';')
+            filename_part = next((part for part in parts if 'filename=' in part), None)
+            
+            if not filename_part:
+                error_message = "Error: Unable to find 'filename' in the 'content-disposition' header."
+                print(error_message)
+                return error_message
+
+            original_filename = filename_part.split('=')[1].strip().strip('"')
+            _, extension = os.path.splitext(original_filename)
+
+            if not extension:
+                error_message = f"Error: Unable to get the file extension from '{original_filename}'."
+                print(error_message)
+                return error_message
+
+            # 5. Costruire il percorso di salvataggio e salvare il file
+            local_filename = f"{task_id}{extension}"
+            local_filepath = os.path.join(UPLOADS_DIR, local_filename)
+
+            with open(local_filepath, 'wb') as f:
+                # Scrive il contenuto a pezzi per gestire file di grandi dimensioni
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+            
+            success_message = f"File scaricato con successo e salvato in: {local_filepath}"
+            print(success_message)
+            return local_filename
+
+    except requests.exceptions.RequestException as e:
+        # Gestisce errori di rete, timeout, DNS, etc.
+        error_message = f"Network error occurred while downloading the file: {e}"
+        print(error_message)
+        return error_message
+    except Exception as e:
+        # Cattura qualsiasi altra eccezione imprevista
+        error_message = f"An unexpected error occurred: {e}"
+        print(error_message)
+        return error_message
+    
+
+#-----------------------------------------------------------------------------
+#   Math Tools
+#-----------------------------------------------------------------------------
+@tool("add_tool")
+def add_tool(numbers: List[float]) -> float:
+    """
+    Calculate the sum of a list of numbers.
+    Use this tool when you need to perform a sum operation on multiple numbers.
+
+    Args:
+        numbers (List[float]): The list of numbers to be summed.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'sum_numbers' CON INPUT: {numbers} ---")
+    return sum(numbers)
+
+
+@tool("multiply_tool")
+def multiply_tool(numbers: List[float]) -> float:
+    """
+    Calculate the product of a list of numbers.
+    Use this tool when you need to multiply two or more numbers together.
+
+    Args:
+        numbers (List[float]): The list of numbers to be multiplied.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'multiply_numbers' CON INPUT: {numbers} ---")
+    if not numbers:
+        return 0
+    return math.prod(numbers)
+
+
+@tool("subtract_tool")
+def subtract_tool(minuend: float, subtrahend: float) -> float:
+    """
+    Calculate the subtraction between two numbers (minuend - subtrahend).
+    Use this tool to subtract one number from another.
+
+    Args:
+        minuend (float): The number from which to subtract (the first number).
+        subtrahend (float): The number to subtract (the second number).
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'subtract_numbers' CON INPUT: minuend={minuend}, subtrahend={subtrahend} ---")
+    return minuend - subtrahend
+
+
+@tool("divide_tool")
+def divide_tool(dividend: float, divisor: float) -> Union[float, str]:
+    """
+    Calculate the division between two numbers (dividend / divisor).
+    Also handles the case of division by zero.
+
+    Args:
+        dividend (float): The number to be divided (the numerator).
+        divisor (float): The number to divide by (the denominator).
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'divide_numbers' CON INPUT: dividend={dividend}, divisor={divisor} ---")
+    if divisor == 0:
+        return "Error: Division by zero is not allowed."
+    return dividend / divisor
+
+
+@tool("modulus_tool")
+def modulus_tool(dividend: float, divisor: float) -> Union[float, str]:
+    """
+    Calculate the remainder of the division between two numbers (dividend % divisor).
+    Use this tool when asked for the 'remainder' or the 'modulus' of a division.
+
+    Args:
+        dividend (float): The number being divided (the numerator).
+        divisor (float): The number by which to divide (the denominator).
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'calculate_remainder' CON INPUT: dividend={dividend}, divisor={divisor} ---")
+    if divisor == 0:
+        return "Error: The divisor cannot be zero for the modulus operation."
+    return dividend % divisor
+
+
+@tool("power_tool")
+def power_tool(base: float, exponent: float) -> Union[float, str]:
+    """
+    Calculate a number raised to a power (base^exponent).
+    Use this tool for exponentiation operations.
+
+    Args:
+        base (float): The base of the operation.
+        exponent (float): The exponent to which the base is raised.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'calculate_power' CON INPUT: base={base}, exponent={exponent} ---")
+    try:
+        # Usiamo math.pow per coerenza e una migliore gestione degli errori
+        result = math.pow(base, exponent)
+        return result
+    except ValueError:
+        # Si verifica se, ad esempio, si cerca di calcolare (-4)^(0.5), che produce un numero complesso.
+        return "Error: Invalid operation. Ensure that the base and exponent do not result in a complex number (e.g., even root of a negative number)."
+
+
+@tool("square_root_tool")
+def square_root_tool(number: float) -> Union[float, str]:
+    """
+    Calculate the square root of a non-negative number.
+    Use this tool specifically to compute the square root.
+
+    Args:
+        number (float): The number for which to calculate the square root. Must be >= 0.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'square_root' CON INPUT: number={number} ---")
+    if number < 0:
+        return "Error: Cannot calculate the square root of a negative number."
+    return math.sqrt(number)
+
+
+#-----------------------------------------------------------------------------
+#   File Tools
+#-----------------------------------------------------------------------------
+@tool("tabular_tool")
+def tabular_tool(filename: str) -> Union[str, str]:
+    """
+    Analyze a local tabular data file (CSV, XLSX, XLS) and return its content
+    as a formatted string. For Excel files, each worksheet is processed individually.
+
+    Args:
+        filename (str): The filename of the CSV, XLSX, or XLS file to analyze.
+
+    Returns:
+        Union[str, str]: A formatted string containing the file's data, or an error message in case of issues.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'analyze_tabular_data' CON INPUT: filename='{filename}' ---")
+    UPLOADS_DIR = "./uploads/"
+    file_path = os.path.join(UPLOADS_DIR, filename)
+
+    # 1. Validazione dell'input: controlla se il file esiste
+    if not os.path.exists(file_path):
+        return f"Error: The file '{file_path}' was not found. Make sure it has been downloaded first."
+
+    try:
+        # 2. Determina il tipo di file e prepara la lista dei CSV da processare
+        file_extension = Path(file_path).suffix.lower()
+        csv_files_to_process = []
+        
+        # --- CASO 1: Il file è un Excel ---
+        if file_extension in ['.xlsx', '.xls']:
+            print(f"Rilevato file Excel. Inizio la conversione dei fogli in CSV temporanei...")
+            
+            # Legge tutti i fogli in un dizionario di DataFrame
+            excel_sheets = pd.read_excel(file_path, sheet_name=None)
+            
+            if not excel_sheets:
+                return f"Error: The Excel file '{file_path}' is empty or contains no worksheets."
+            
+            # Ottiene il nome base del file per i file temporanei
+            base_name = Path(file_path).stem
+            uploads_dir = Path(file_path).parent
+
+            for sheet_name, df in excel_sheets.items():
+                # Crea un nome di file sicuro per il CSV temporaneo
+                safe_sheet_name = "".join(c for c in sheet_name if c.isalnum() or c in (' ', '_')).rstrip()
+                temp_csv_path = uploads_dir / f"{base_name}_sheet_{safe_sheet_name}.csv"
+                
+                # Salva il DataFrame del foglio in un file CSV
+                df.to_csv(temp_csv_path, index=False)
+                print(f" - Foglio '{sheet_name}' convertito e salvato in: {temp_csv_path}")
+                csv_files_to_process.append(str(temp_csv_path))
+
+        # --- CASO 2: Il file è già un CSV ---
+        elif file_extension == '.csv':
+            print(f"Rilevato file CSV. Verrà processato direttamente.")
+            csv_files_to_process.append(file_path)
+
+        # --- CASO 3: Formato non supportato ---
+        else:
+            return f"Error: Unsupported file format '{file_extension}'. This tool supports only CSV, XLSX, and XLS."
+
+        # 3. Usa CSVLoader su tutti i file CSV identificati (originali o convertiti)
+        if not csv_files_to_process:
+            return "Error: No file to process was found."
+            
+        all_docs = []
+        for csv_path in csv_files_to_process:
+            loader = CSVLoader(file_path=csv_path)
+            docs = loader.load()
+            all_docs.extend(docs)
+        
+        # 4. Formatta l'output come richiesto
+        # Aumentiamo il limite di caratteri per dare più contesto all'LLM
+        formatted_output = "\n\n---\n\n".join(
+            [
+                f'<Document source="{Path(doc.metadata["source"]).name}" page="{doc.metadata.get("page", 0)}">\n{doc.page_content[:2500]}\n</Document>'
+                for doc in all_docs
+            ]
+        )
+        
+        print("Analisi completata con successo.")
+        return formatted_output
+
+    except Exception as e:
+        error_message = f"An unexpected error occurred while analyzing the file '{file_path}': {e}"
+        print(error_message)
+        return error_message
+
+
+@tool("audio_tool")
+def audio_tool(filename: str) -> Union[str, str]:
+    """
+    Transcribes a local audio file into text using OpenAI's Whisper model.
+    Use this tool when you need to extract the textual content from an audio file.
+    Supports common formats such as MP3, MP4, MPEG, MPGA, M4A, WAV, and WEBM.
+
+    Args:
+        filename (str): The filename of the audio file to transcribe.
+
+    Returns:
+        Union[str, str]: The transcribed text if successful, or an error message string in case of failure.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'transcribe_audio' CON INPUT: file_path='{filename}' ---")
+    UPLOADS_DIR = "./uploads/"
+    file_path = os.path.join(UPLOADS_DIR, filename)
+    client = OpenAI()
+
+    # 1. Controlla se il client è stato inizializzato correttamente
+    if client is None:
+        return "Error: The OpenAI client is not configured. Please check your API key."
+
+    # 2. Controlla se il file esiste prima di tentare di aprirlo
+    if not os.path.exists(file_path):
+        return f"Error: The file '{file_path}' was not found. Make sure it has been downloaded first."
+
+    try:
+        # 3. Apri il file in modalità binaria e invialo all'API di OpenAI
+        with open(file_path, "rb") as audio_file:
+            transcription = client.audio.transcriptions.create(
+                model="whisper-1",
+                file=audio_file
+            )
+        
+        print("Trascrizione completata con successo.")
+        # La risposta dell'API contiene il testo nel campo 'text'
+        return transcription.text
+
+    except APIError as e:
+        # Gestisce errori specifici dell'API di OpenAI (es. file non valido, auth error)
+        error_message = f"Error from the OpenAI API during transcription: {e}"
+        print(error_message)
+        return error_message
+        
+    except Exception as e:
+        # Gestisce altri errori imprevisti (es. problemi di lettura del file)
+        error_message = f"An unexpected error occurred while transcribing the file '{file_path}': {e}"
+        print(error_message)
+        return error_message
+    
+
+@tool("image_tool")
+def image_tool(filename: str, user_question: str) -> Union[str, str]:
+    """
+    Reads a local image file and encodes it in base64 format, ready to be analyzed by a multimodal model (such as GPT-4o).
+    Use this tool to prepare any image (JPG, PNG, WEBP, etc.) before asking questions about its content.
+
+    Args:
+        filename (str): The filename of the image file to prepare.
+        user_question (str): The user's original question to guide the analysis.
+
+    Returns:
+        Union[str, str]: A textual analysis based on the base64 encoded image data, or an error message string.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'prepare_image_for_analysis' CON INPUT: file_path='{filename}' ---")
+    UPLOADS_DIR = "./uploads/"
+    file_path = os.path.join(UPLOADS_DIR, filename)
+    client = OpenAI()
+
+    # 1. Controlla se il file esiste
+    if not os.path.exists(file_path):
+        return f"Error: The image file '{file_path}' was not found."
+
+    try:
+        # 2. Determina il tipo MIME dell'immagine (es. 'image/jpeg', 'image/png')
+        mime_type, _ = mimetypes.guess_type(file_path)
+        if not mime_type or not mime_type.startswith('image/'):
+            return f"Error: The file '{file_path}' is not a supported image format."
+
+        # 3. Leggi il file in modalità binaria e codificalo in base64
+        with open(file_path, "rb") as image_file:
+            encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
+
+        # 4. Formatta l'output come un data URI, il formato standard per passare immagini
+        #    a modelli multimodali.
+        image_data = f"data:{mime_type};base64,{encoded_string}"
+        # Crea il prompt per l'analisi
+        analysis_prompt = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"""
+                            You are an expert visual analyst. Your task is to describe the provided image in extreme detail to help answer the user's question.
+                            Focus on the elements relevant to the question. Be objective and precise.
+
+                            **User's Question:** '{user_question}'
+
+                            Analyze the image and provide a detailed description.
+                        """
+                    },
+                    {
+                        "type": "image_url",
+                        "image_url": {
+                            "url": image_data,
+                            "detail": "high" # Usa alta risoluzione per la massima precisione
+                        }
+                    }
+                ]
+            }
+        ]
+        
+
+        # 5. Restituisce la risposta in base all'immagine analizzata.
+        # Chiama l'API di OpenAI
+        response = client.chat.completions.create(
+            model="gpt-4o-mini",  # o "gpt-4-vision-preview"
+            messages=analysis_prompt,
+            max_tokens=1000,
+            temperature=0
+        )
+        
+        description = response.choices[0].message.content
+        print("--- Image analysis complete. ---")
+        return description
+    except Exception as e:
+        return f"An error occurred during the visual analysis: {e}"    
+
+
+#-----------------------------------------------------------------------------
+#   Code Execution Tools
+#-----------------------------------------------------------------------------
+@tool("code_writer_tool")
+def code_writer_tool(code: str, task_id: str) -> str:
+    """
+    Writes a string of Python code to a local file. This is the first step
+    for any task that requires writing and then executing code. The task_id is the name for the file.
+
+    Args:
+        code (str): A string containing the complete, valid Python code to be written to the file.
+        task_id (str): The name for the file.
+
+    Returns:
+        local_filename (str): The local filename of python file to execute.
+    """
+    print(f"--- TOOL: Writing code to file: {task_id}.py ---")
+    UPLOADS_DIR = "./uploads/"
+    local_filename = f"{task_id}.py"
+    file_path = os.path.join(UPLOADS_DIR, local_filename)    
+
+    try:
+        # Scrive il codice nel file
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(code)
+        
+        success_message = f"Successfully wrote code to {file_path}."
+        print(success_message)
+        
+        # Restituisce il percorso del file, che servirà al tool di esecuzione
+        return local_filename
+    except Exception as e:
+        error_message = f"An error occurred while writing the file: {e}"
+        print(error_message)
+        return error_message
+    
+
+@tool("code_tool")
+def code_tool(filename: str, timeout_seconds: int = 100) -> Union[str, dict]:
+    """
+    Executes a programming code file in an isolated and secure environment, capturing its standard output and errors.
+    Use this tool to run programming code when you need to analyze its behavior or output.
+
+    Args:
+        filename (str): The filename of the code file to execute.
+        timeout_seconds (int, optional): The maximum number of seconds the execution is allowed to run before forcibly terminating the process. Default is 10.
+
+    Returns:
+        Union[str, dict]: A dictionary containing 'stdout', 'stderr', and 'return_code' if successful, or an error message string if the tool itself fails.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'execute_python_file' SU: {filename} ---")
+    UPLOADS_DIR = "./uploads/"
+    file_path = os.path.join(UPLOADS_DIR, filename)
+
+    # 1. Controlla di sicurezza: il file esiste?
+    if not os.path.exists(file_path):
+        return f"Error: The code file '{file_path}' was not found."
+
+    # 2. Usa subprocess.run per eseguire il codice in modo sicuro
+    try:
+        # 'subprocess.run' è il modo moderno e raccomandato per eseguire processi
+        process = subprocess.run(
+            ['python', file_path],     # Il comando da eseguire (es. 'python nomefile.py')
+            capture_output=True,       # Cattura stdout e stderr
+            text=True,                 # Decodifica stdout/stderr come testo (UTF-8)
+            timeout=timeout_seconds    # Imposta un timeout
+        )
+
+        execution_result = {
+            "return_code": process.returncode,
+            "stdout": process.stdout.strip(),
+            "stderr": process.stderr.strip()
+        }
+
+        # 3. Ritorna un dizionario strutturato con i risultati
+        return execution_result
+
+    except FileNotFoundError:
+        # Questo errore si verifica se l'interprete 'python' non è nel PATH del sistema
+        return "Error: The 'python' interpreter was not found on the system. Unable to execute the code."
+    except subprocess.TimeoutExpired as e:
+        # Gestisce il caso in cui il codice va in timeout
+        return {
+            "return_code": -1, # Codice di ritorno personalizzato per timeout
+            "stdout": e.stdout.strip() if e.stdout else "",
+            "stderr": f"Error: Execution terminated after {timeout_seconds} seconds (Timeout)."
+        }
+    except Exception as e:
+        # Cattura qualsiasi altro errore imprevisto durante l'esecuzione del tool
+        return f"An unexpected error occurred while executing the tool: {e}"
+    
+
+#-----------------------------------------------------------------------------
+#   Youtube Video Tools
+#-----------------------------------------------------------------------------
+@tool("youtube_info_tool")
+def youtube_info_tool(youtube_url: str) -> Union[str, dict]:
+    """
+    Collects information and resources from a YouTube video. Downloads both audio and video, and retrieves the official transcript if available.
+    This is ALWAYS the first tool to call when working with a YouTube video.
+
+    Args:
+        youtube_url (str): The full URL of the YouTube video.
+
+    Returns:
+        Union[str, dict]: A dictionary with the collected resources (transcript, audio_filename, video_filename) or an error message.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'get_youtube_video_info' CON URL: {youtube_url} ---")
+    UPLOADS_DIR = "./uploads/"
+
+    try:
+        yt = YouTube(youtube_url)
+        video_id = yt.video_id
+        
+        # 1. Recupera la trascrizione ufficiale
+        transcript_text = None
+        try:
+            transcript_list = YouTubeTranscriptApi.get_transcript(video_id)
+            transcript_text = " ".join([d['text'] for d in transcript_list])
+            print("Trascrizione ufficiale trovata.")
+        except Exception:
+            print("Nessuna trascrizione ufficiale disponibile.")
+
+        # 2. Scarica l'audio
+        audio_stream = yt.streams.get_audio_only()
+        audio_path = audio_stream.download(output_path=UPLOADS_DIR, filename=f"{video_id}.m4a")
+        if transcript_text is None:
+            transcript_text = audio_tool.invoke({"filename":f"{video_id}.m4a"})
+        print(f"Audio scaricato in: {audio_path}")
+
+        # 3. Scarica il video
+        video_stream = yt.streams.get_highest_resolution()
+        video_path = video_stream.download(output_path=UPLOADS_DIR, filename=f"{video_id}.mp4")
+        print(f"Video scaricato in: {video_path}")
+
+        video_info = {
+            "title": yt.title,
+            "description": yt.description,
+            "transcript": transcript_text,
+            "audio_filename": f"{video_id}.m4a",
+            "video_filename": f"{video_id}.mp4"
+        }
+        
+        return video_info
+    except Exception as e:
+        return f"Error while retrieving information from the YouTube video: {e}"
+    
+
+@tool("youtube_frame_tool")
+def youtube_frame_tool(filename: str, title: str, description: str, transcript: str, user_question: str, sample_rate_seconds: int = 5) -> Union[str, str]:
+    """
+    Analyzes video content by combining visual information from frames with the provided transcript to answer a specific user question.
+    To be used as a last resort, when the transcript and audio are not sufficient, or for purely visual questions.
+
+    Args:
+        filename (str): The filename of the video file.
+        title (str): The title of the video.
+        description (str): A brief description of the video.
+        transcript (str): The full text transcript of the video (either official or from audio).
+        user_question (str): The user's original question to guide the analysis.
+        sample_rate_seconds (int): Interval in seconds between frames to analyze. Default is 3.
+
+    Returns:
+        Union[str, str]: A textual analysis based on the video frames or an error message.
+    """
+    print(f"--- ESECUZIONE DEL TOOL 'analyze_video_frames' SU: {filename} ---")
+    UPLOADS_DIR = "./uploads/"
+    video_path = os.path.join(UPLOADS_DIR, filename)
+    client = OpenAI()
+    
+    if not os.path.exists(video_path):
+        return f"Error: Video file not found at '{video_path}'."
+    if client is None:
+        return "Error: The OpenAI client is not configured."
+
+    video = cv2.VideoCapture(video_path)
+    fps = video.get(cv2.CAP_PROP_FPS)
+    frame_interval = int(fps * sample_rate_seconds)
+    
+    base64_frames = []
+    frame_count = 0
+    
+    while video.isOpened():
+        success, frame = video.read()
+        if not success:
+            break
+        
+        if frame_count % frame_interval == 0:
+            _, buffer = cv2.imencode(".jpg", frame)
+            base64_frames.append(base64.b64encode(buffer).decode("utf-8"))
+        
+        frame_count += 1
+
+    video.release()
+    print(f"Campionati {len(base64_frames)} frame dal video.")
+
+    if not base64_frames:
+        return "Error: Unable to extract frames from the video."
+
+    prompt_messages = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "text",
+                    "text": f"""
+                        You are a video content analyst.
+                        Your task is to answer the user's question by combining information from different sources: 
+                        - the title
+                        - the description
+                        - the transcript
+                        - a series of sampled frames
+                        **IMPORTANT**: Analyze the all sources of the video in great detail, because there may be important information to solve the task.
+                        
+                        **User Question**: {user_question}
+                        **Video Title**: {title}
+                        **Video Description**: {description}
+                        **Video Transcript**: {transcript if transcript else "No transcript available."}
+                        
+                        Begin your rigorous analysis now. Here are the frames:
+                    """
+                },
+                # Inserimento dei Frame
+                *map(lambda x: {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{x}", "detail": "low"}}, base64_frames),
+            ],
+        }
+    ]
+
+    try:
+        response = client.chat.completions.create(
+            model="gpt-4o-mini",
+            temperature=0,
+            messages=prompt_messages,
+            max_tokens=1000,
+        )
+        analysis_summary = response.choices[0].message.content
+        return analysis_summary
+    except Exception as e:
+        return f"Error while analyzing frames with the OpenAI API: {e}"
+    
+
+#-----------------------------------------------------------------------------
+#   Web Search Tools
+#-----------------------------------------------------------------------------
+@tool("web_search_tool")
+def web_search_tool(task: str) -> str:
+    """
+    Delegates complex research tasks to a specialized, cyclic research agent.
+    Use this for any question that requires external, up-to-date, or detailed knowledge.
+    """
+    print(f"--- MAIN AGENT: DELEGATING RESEARCH FOR: '{task}' ---")
+    
+    # Lo stato iniziale ora contiene il task e un primo messaggio umano vuoto per avviare il ciclo.
+    # L'agente di ricerca leggerà il task dallo stato e ignorerà questo messaggio.
+    initial_state = {"task": task, "context_summary": ""}
+    
+    # Esegui il sub-grafo
+    final_state = web_search_graph.invoke(initial_state)
+    
+    # Il risultato finale è l'ultimo messaggio nella cronologia, che sarà la risposta del writer.
+    final_answer = final_state["messages"][-1].content
+    return final_answer
+
+
+assistant_tools_list = [
+    sort_tool, download_tool, add_tool, multiply_tool, subtract_tool, divide_tool, modulus_tool, tabular_tool, audio_tool, image_tool, code_writer_tool, code_tool, youtube_info_tool, youtube_frame_tool, web_search_tool
+]

web_search_agent.py

@@ -0,0 +1,282 @@
+import os
+from dotenv import load_dotenv
+import operator
+from typing import List, TypedDict, Annotated, Dict
+from pydantic import BaseModel, Field
+from IPython.display import Image, display
+
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import SystemMessage, AIMessage, HumanMessage, ToolMessage
+from langgraph.graph import MessagesState, StateGraph, END, START
+from langgraph.prebuilt import ToolNode, tools_condition
+
+# Importiamo i web tools
+from web_search_tools import google_search_tool, wikipedia_search_tool, browse_web_page_tool, text_analyzer_tool
+
+
+# Carica le variabili d'ambiente
+load_dotenv()
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+OPENAI_API_MODEL = os.getenv("OPENAI_API_WEB_MODEL")
+
+
+# --- 1. Strutture e Stato ---
+class ResearchPlan(BaseModel):
+    """A step-by-step research plan."""
+    steps: List[str] = Field(description="A list of concise, sequential steps for the research task.")
+
+class ResearchState(MessagesState):
+    task: str
+    plan: ResearchPlan
+    current_plan_step: int
+    context_summary: str
+    step_results: Annotated[List[str], operator.add] # Memoria a lungo termine per i risultati di ogni passo
+
+
+# --- 2. Tool e Modelli ---
+llm = ChatOpenAI(model=OPENAI_API_MODEL, api_key=OPENAI_API_KEY, temperature=0)
+llm_with_tools = llm.bind_tools([wikipedia_search_tool, browse_web_page_tool])
+
+
+# --- 3. Nodi del Grafo a Pipeline ---
+def planning_node(state: ResearchState):
+    """Node 1: Generate the initial research plan."""
+    print("--- 📝 PLANNING NODE ---")
+    
+    task = state.get('task')
+    structured_llm = llm.with_structured_output(ResearchPlan)
+    planning_prompt = f"""
+        You are an expert and efficient research planner. Your goal is to create the SHORTEST POSSIBLE, logical, step-by-step plan to solve a user's research task.
+
+        **Core Principles:**
+        1.  **Analyze Complexity**: First, determine if the task is simple or complex.
+            -   A **simple task** can be solved with a single, well-formulated search and analysis (e.g., "Who won the 1998 World Cup?").
+            -   A **complex task** requires finding one piece of information to unlock the next (e.g., "Who is the manager of the team that won the 1998 World Cup?").
+        2.  **Create the Plan**:
+            -   For a **simple task**, create a plan with ONLY ONE step: a clear instruction to find the final answer.
+            -   For a **complex task**, break it down into the minimum number of sequential steps required. Each step must build upon the previous one.
+        3.  **Focus on Actions**: Each step should describe an action to find a specific piece of information.
+
+        ---
+        **Example 1: Simple Task**
+        *   **User Task:** "How many studio albums were published by Mercedes Sosa between 2000 and 2009 (included)? You can use the latest 2022 version of english wikipedia."
+        *   **Your Output (Plan):**
+            "steps": [
+                "Search Wikipedia for the discography of Mercedes Sosa, find all studio albums released between 2000 and 2009, and count them."
+            ]
+
+        **Example 2: Complex Task**
+        *   **User Task:** "Who did the actor who played Ray in the Polish-language version of Everybody Loves Raymond play in Magda M.? Give only the first name."
+        *   **Your Output (Plan):**
+            "steps": [
+                "Find the name of the actor who played Ray in the Polish version of 'Everybody Loves Raymond'.",
+                "Using the actor's name, find their role in the show 'Magda M.' and extract the character's first name."
+            ]
+        ---
+
+        Now, analyze the following user task and generate the most efficient, step-by-step research plan.
+        **User Task:** {task}
+        **Your Output (Plan):**
+    """
+    
+    response_plan = structured_llm.invoke([SystemMessage(content=planning_prompt)])
+    print("--- ✅ PLANNING COMPLETE ---")
+    print("Generated Plan:", response_plan.steps)
+    return {"plan": response_plan, "current_plan_step": 0}
+
+
+def search_node(state: ResearchState):
+    """Node 2: Performs a web search for a single step of the plan."""
+    step_index = state["current_plan_step"]
+    plan_steps = state["plan"].steps
+    current_step_instruction = plan_steps[step_index]
+    context_summary = state["step_results"]
+    
+    print(f"--- 🔎 SEARCH NODE (Executing step: '{current_step_instruction}') ---")
+    query_prompt = f"""
+        You are an expert at generating search engine queries.
+        Your goal is to create a single, concise, and effective Google search query to accomplish the given plan step, using the context from previous steps.
+
+        **Current Plan Step to Execute:** "{current_step_instruction}"
+        **Context from Previous Steps' Findings:**
+        ---
+        {context_summary}
+        ---
+
+        Based on the **Current Plan Step** and the **Context**, generate the single best possible search query to find the next piece of information.
+        For example, if the context is "The actor is Bartek Kasprzykowski" and the step is "Find his role in Magda M.", a good query would be "Bartek Kasprzykowski role in Magda M.".
+    """
+    
+    # Genera la query
+    query = llm.invoke([SystemMessage(content=query_prompt)]).content.strip('"')
+    print(f"--- Generated Context-Aware Query: '{query}' ---")
+    
+    # Eseguiamo il tool di ricerca su Google
+    search_results = google_search_tool.invoke(query)
+    
+    # Aggiorniamo lo stato 
+    return {"messages": [AIMessage(content=search_results)]}
+
+
+def browse_node(state: ResearchState):
+    """Node 3: Analyzes search results and decides which URL to browse, prioritizing Wikipedia."""
+    # L'ultimo messaggio contiene i risultati della ricerca Google
+    search_results = state["messages"][-1].content
+    
+    print(f"--- 📖 BROWSE NODE (Analyzing search results) ---")
+    
+    # Prompt per scegliere l'URL e il tool corretto
+    browse_prompt = f"""
+        You are an expert at selecting the best information source.
+        Given a list of Google search results, your goal is to choose the SINGLE best URL to browse to accomplish the current research step.
+
+        **Current Research Step:** "{state['plan'].steps[state['current_plan_step']]}"
+
+        **Decision Hierarchy (Strict):**
+        1.  **Wikipedia First**: If a reliable `wikipedia.org` link is present and seems highly relevant to the current step, you **MUST** choose it and call the `wikipedia_search_tool`.
+        2.  **Browse Other Sources**: If there are no good Wikipedia links, choose the single most promising URL from another reputable source and call the `browse_web_page_tool`.
+
+        **Search Results:**
+        ---
+        {search_results}
+        ---
+
+        Based on the hierarchy and the current research step, which single tool call should you make?
+    """
+    
+    # Invoca l'LLM per ottenere la decisione sulla chiamata al tool
+    message = llm_with_tools.invoke([SystemMessage(content=browse_prompt)])
+    
+    # Controlla se l'LLM ha effettivamente deciso di chiamare un tool
+    if not hasattr(message, "tool_calls") or not message.tool_calls:
+        # Fallback: se l'LLM non riesce a decidere, lo segnaliamo per passare avanti
+        print("--- ⚠️ BROWSE NODE: LLM failed to choose a tool. Skipping browse step. ---")
+        return {"messages": [AIMessage(content="No relevant page found to browse.")]}
+
+    print(f"--- Browse Node decision: Call '{message.tool_calls[0]['name']}' on '{message.tool_calls[0]['args']}' ---")
+    return {"messages": message}
+
+
+def step_synthesis_node(state: ResearchState):
+    """Node 4: Summarize the information from the current step and prepare for the next one."""
+    print("  --- 🔄 STEP SYNTHESIS NODE ---")
+    
+    current_step_instruction = state["plan"].steps[state["current_plan_step"]]
+    browsed_content = state["messages"][-1].content
+    
+    summary_prompt = f"""
+        You are a factual extractor and research analyst.
+        Your goal is to extract key pieces of information from the provided content to satisfy a specific sub-task and prepare for the next step.
+
+        **Sub-Task (Instruction to accomplish):** "{current_step_instruction}"
+
+        **Content Gathered in this Step:**
+        ---
+        {browsed_content}
+        ---
+
+        **Analysis:**
+        1.  **Extract Key Facts**: From the "Content Gathered", pull out the specific names, dates, numbers, or links that directly answer the "Sub-Task".
+        2.  **Assess Step Completion**: Was the sub-task successfully completed with this information?
+        3.  **Synthesize for Next Step**: Create a very concise summary of your findings. This summary will be used as context for the next step in the plan. If the sub-task was not completed, state what is still missing.
+
+        **Your Output:**
+        Provide a concise summary of your findings. For example:
+        "Successfully found the actor's name: Bartek Kasprzykowski."
+        or
+        "Failed to find the specific NASA award number on this page, but confirmed the paper was written by the correct team."
+    """
+    
+    step_summary = llm.invoke([SystemMessage(content=summary_prompt)]).content
+    print(f"--- ✅ STEP {state['current_plan_step'] + 1} COMPLETE. Summary: '{step_summary}' ---")
+    
+    # Aggiunge il riassunto ai risultati a lungo termine e avanza il contatore
+    return {"step_results": [step_summary], "current_plan_step": state["current_plan_step"] + 1}
+
+
+def final_synthesis_node(state: ResearchState):
+    """Node 5: Takes all the summarized results from each step and combines them into a complete and final answer for the original task."""
+    print("--- ✍️ FINAL SYNTHESIS NODE ---")
+    
+    # Raccoglie i riassunti di ogni passo dalla memoria a lungo termine dello stato
+    step_summaries = state.get("step_results", [])
+    
+    # Controlla se abbiamo effettivamente dei risultati da sintetizzare
+    if not step_summaries:
+        final_report = "The research process concluded, but no conclusive information was gathered to answer the task."
+        return {"messages": [AIMessage(content=final_report)]}
+    
+    # Crea un contesto pulito per l'LLM finale
+    full_context = "\n\n".join(
+        [f"Finding from Step {i+1}: {summary}" for i, summary in enumerate(step_summaries)]
+    )
+    
+    # Prompt per la sintesi finale
+    final_prompt = f"""
+        You are an expert data analyst and report writer.
+        Your final and most important task is to synthesize the provided research findings to answer the user's original task with extreme precision.
+
+        **User's Original Task:**
+        ---
+        "{state['task']}"
+        ---
+
+        **Summary of Findings from Each Research Step:**
+        ---
+        {full_context}
+        ---
+
+        **Your Analytical Process (You MUST follow this):**
+        1.  **Re-read the Original Task**: Pay extremely close attention to all constraints, especially dates, numbers, and specific conditions (e.g., "between 2000 and 2009, included", "first name only").
+        2.  **Verify Information**: Scan the "Summary of Findings" and ensure you have all the necessary pieces to construct the answer. Do not invent or infer information that is not present.
+        3.  **Construct the Final Answer**: Write a clear, direct, and accurate answer based solely on the verified findings. Address every part of the user's original task.
+
+        Based on this rigorous process, generate the final answer.
+    """
+    
+    # Usa un LLM (può essere lo stesso o uno diverso) per generare il report finale
+    final_report = llm.invoke([SystemMessage(content=final_prompt)])
+    print("--- ✅ FINAL REPORT GENERATED ---")
+    
+    # Aggiunge il report finale ai messaggi, che sarà l'output finale del grafo
+    return {"messages": final_report}
+
+
+# --- 4. Costruzione del Grafo a Pipeline ---
+def router(state: ResearchState):
+    """Decides whether to proceed to the next step or move on to the final summary."""
+    print("--- 🔍 ROUTER ---")
+    if state["current_plan_step"] < len(state["plan"].steps):
+        print("  - Decision: Continue to next pipeline cycle.")
+        return "continue_pipeline"
+    else:
+        print("  - Decision: Plan complete. Proceed to final synthesis.")
+        return "end_pipeline"
+    
+
+builder = StateGraph(ResearchState)
+builder.add_node("planning", planning_node)
+builder.add_node("search", search_node)
+builder.add_node("browse", browse_node)
+builder.add_node("tools", ToolNode([wikipedia_search_tool, browse_web_page_tool]))
+builder.add_node("synthesis", step_synthesis_node)
+builder.add_node("final_synthesizer", final_synthesis_node)
+
+builder.add_edge(START, "planning")
+builder.add_edge("planning", "search")
+builder.add_edge("search", "browse")
+builder.add_edge("browse", "tools")
+builder.add_edge("tools", "synthesis")
+# Dopo la sintesi di un passo, il router decide se ricominciare o finire
+builder.add_conditional_edges(
+    "synthesis",
+    router,
+    {
+        "continue_pipeline": "search",
+        "end_pipeline": "final_synthesizer"
+    }
+)
+builder.add_edge("final_synthesizer", END)
+
+web_search_graph = builder.compile()
+display(Image(web_search_graph.get_graph(xray=1).draw_mermaid_png(output_file_path="./web_search_graph.png")))

web_search_tools.py

@@ -0,0 +1,190 @@
+import os
+from dotenv import load_dotenv
+from urllib.parse import unquote
+import tempfile
+import wikipedia
+from playwright.sync_api import sync_playwright, TimeoutError
+import bs4
+import pandas as pd
+
+from langchain_openai import ChatOpenAI
+from langchain_community.document_loaders import UnstructuredHTMLLoader
+from langchain_google_community import GoogleSearchAPIWrapper
+from langchain_community.utilities import ArxivAPIWrapper
+from langchain_core.tools import tool
+
+
+# Carica le variabili d'ambiente per i tool
+load_dotenv()
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+OPENAI_API_MODEL = os.getenv("OPENAI_API_MODEL")
+GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
+GOOGLE_CSE_ID = os.getenv("GOOGLE_CSE_ID")
+
+# --- Tool di Ricerca Google ---
+@tool("google_search_tool")
+def google_search_tool(query: str) -> str:
+    """
+    Performs a Google search and returns the top results.
+    Use this for general web searches, finding articles, or recent information.
+    """
+    print(f"--- TOOL: Executing Google Search for: '{query}' ---")
+    google_search = GoogleSearchAPIWrapper(google_api_key=GOOGLE_API_KEY, google_cse_id=GOOGLE_CSE_ID)
+    return google_search.results(query, num_results=3)
+
+
+# --- Tool di Ricerca Wikipedia ---
+@tool("wikipedia_search_tool")
+def wikipedia_search_tool(query_or_url: str, max_results: int = 1) -> str:
+    """
+    Fetches content from a Wikipedia page. This tool is dual-purpose:
+    1. If the input is a search query, it finds the most relevant Wikipedia page and returns its full content.
+    2. If the input is a full Wikipedia URL, it directly fetches and returns the content of that page.
+    
+    This is the preferred tool for all interactions with Wikipedia.
+
+    Args:
+        query_or_url (str): A search query (e.g., "Mercedes Sosa discography") or a full Wikipedia URL.
+    """
+    print(f"--- WIKIPEDIA TOOL (Dual-Purpose): Input is '{query_or_url}' ---")
+    
+    wikipedia.set_lang("en")
+    
+    page_title = ""
+
+    try:
+        # --- LOGICA DI DECISIONE E DECODIFICA ---
+        if query_or_url.startswith("http://") or query_or_url.startswith("https://"):
+            # Caso 1: L'input è un URL
+            # Estraiamo l'ultima parte dell'URL
+            raw_title = query_or_url.split('/')[-1]
+            
+            # CORREZIONE: Decodifica i caratteri speciali (es. %C4%85 -> ą)
+            # e sostituisci gli underscore con spazi.
+            page_title = unquote(raw_title).replace('_', ' ')
+            
+            print(f"Input is a URL. Decoded page title: '{page_title}'")
+            page = wikipedia.page(page_title, auto_suggest=False, redirect=True)
+        else:
+            # Caso 2: L'input è una query di ricerca
+            print("Input is a search query. Finding best page...")
+            search_results = wikipedia.search(query_or_url, results=1)
+            if not search_results:
+                return f"Error: No Wikipedia page found for query '{query_or_url}'."
+            page_title = search_results[0]
+            page = wikipedia.page(page_title, auto_suggest=False, redirect=True)
+            
+        # --- ESTRAZIONE HTML E PARSING (invariato) ---
+        print(f"Fetching HTML for page: '{page.title}'")
+        html_content_str = page.html()
+
+        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix=".html", encoding='utf-8') as temp_file:
+            temp_file.write(html_content_str)
+            temp_filepath = temp_file.name
+
+        try:
+            loader = UnstructuredHTMLLoader(temp_filepath, strategy="fast")
+            docs = loader.load()
+        finally:
+            os.remove(temp_filepath)
+
+        if not docs:
+            return f"Content from Wikipedia page '{page.title}': Could not extract any content."
+
+        page_content = docs[0].page_content
+        formatted_output = f"Content from Wikipedia page: '{page.title}'\nURL: {page.url}\n\n{page_content[:20000]}"
+        return formatted_output
+
+    except wikipedia.exceptions.DisambiguationError as e:
+        return f"Error: Your query '{query_or_url}' is ambiguous. Options: {e.options[:5]}"
+    except wikipedia.exceptions.PageError:
+        return f"Error: Could not find or load the Wikipedia page for title derived from '{query_or_url}'."
+    except Exception as e:
+        return f"An unexpected error occurred in the Wikipedia tool: {e}"
+    
+
+# --- Tool di Navigazione ---
+@tool("browse_web_page_tool")
+def browse_web_page_tool(url: str) -> str:
+    """
+    Navigates a web page using a headless browser, then uses Unstructured to extract
+    the full, clean content, including text and tables.
+
+    Args:
+        url (str): The full URL of the page to browse and extract content from.
+    """
+    print(f"--- TOOL: Browsing and extracting from: {url} ---")
+    
+    try:
+        # 1. Usa Playwright per ottenere l'HTML completo
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(url, timeout=30000, wait_until="domcontentloaded")
+            html_content = page.content()
+            browser.close()
+
+        # 2. Usa un file temporaneo IN MEMORIA per passare l'HTML a Unstructured
+        # Questo evita di scrivere su disco, è veloce e pulito.
+        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix=".html", encoding='utf-8') as temp_file:
+            temp_file.write(html_content)
+            temp_filepath = temp_file.name
+
+        try:
+            # 3. Carica e parsa l'HTML con UnstructuredFileLoader
+            loader = UnstructuredHTMLLoader(temp_filepath, strategy="fast")
+            docs = loader.load()
+        finally:
+            # Assicurati di cancellare sempre il file temporaneo
+            os.remove(temp_filepath)
+
+        # 4. Formatta l'output
+        if not docs:
+            return f"Content from URL '{url}': Could not extract any content using Unstructured."
+
+        # Unstructured di solito mette tutto in un unico documento
+        page_content = docs[0].page_content
+        
+        formatted_output = f"Content from URL: '{url}'\n\n{page_content[:20000]}"
+                
+        return formatted_output
+
+    except TimeoutError:
+        return f"Error browsing '{url}': The page took too long to load and timed out."
+    except Exception as e:
+        return f"An unexpected error occurred while browsing '{url}': {e}"
+    
+
+# --- Tool di analisi del contenuto web ---
+@tool("text_analyzer_tool")
+def text_analyzer_tool(text_to_analyze: str, question: str) -> str:
+    """
+    Analyzes a given text to answer a specific question or extract information.
+    Use this tool when you have already gathered content (e.g., from browsing a page)
+    and need to find a specific answer within that text.
+
+    Args:
+        text_to_analyze (str): The text content to be analyzed.
+        question (str): The specific question to answer based on the text.
+    """
+    print(f"--- TOOL: Analyzing text to answer: '{question}' ---")
+    
+    # Usiamo un LLM per fare l'analisi
+    analyzer_llm = ChatOpenAI(model=OPENAI_API_MODEL, temperature=0)
+    
+    prompt = f"""
+        You are a text analysis expert. Your task is to carefully read the provided text and answer the user's question based ONLY on that text.
+        Provide a concise and direct answer.
+
+        **Text to Analyze:**
+        ---
+        {text_to_analyze}
+        ---
+
+        **Question to Answer:**
+        "{question}"
+
+        Your concise answer:
+    """
+    response = analyzer_llm.invoke(prompt)
+    return response.content