Upload 16 files

hf_agent_course_final_assignment/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

hf_agent_course_final_assignment/.gitignore

@@ -0,0 +1,10 @@
+# enviroment files
+.env
+*.jpg
+*.png
+*.mp3
+*.xlsx
+f918266a-b3e0-4914-865d-4faa564f1aef.py
+
+# pycache
+__pycache__/

hf_agent_course_final_assignment/README.md

@@ -0,0 +1,27 @@
+---
+title: Agent Course Final Assignment
+emoji: 🕵🏻‍♂️
+colorFrom: indigo
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.25.2
+app_file: app.py
+pinned: false
+hf_oauth: true
+# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
+hf_oauth_expiration_minutes: 480
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Question analysis
+
+We need following functionalities in our agent:
+- [x] General orchestrator agent: base on the question, recognize what tools are needed to answer the question, call the tools, collect the results, and generate the final answer.
+- [x] youtube video analysis
+- [x] excel manipulation
+- [x] web search (duckduckgo react agent)
+- [x] within web search, we need also to search published papers
+- [x] python exection (done, without llm, only naive code execution)
+- [x] audio analysis (api calling inference client of mp3 transcript + chat model)
+- [x] image analysis (api calling inference client of vlm model)

hf_agent_course_final_assignment/app.py

@@ -0,0 +1,192 @@
+import os
+import gradio as gr
+import requests
+import inspect
+import pandas as pd
+from gaia_agent import GaiaAgent
+from utils.fetch_files import fetch_files_gaia_validation_hub
+# (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 ------
+
+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 = GaiaAgent()
+    except Exception as e:
+        print(f"Error instantiating agent: {e}")
+        return f"Error initializing agent: {e}", None
+    # In the case of an app running as a hugging Face space, this link points toward your codebase ( 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")
+        file_name = item.get("file_name")
+        if file_name != "":
+            file_path = fetch_files_gaia_validation_hub(file_name)
+        else:
+            file_path = ""
+        if not task_id or question_text is None:
+            print(f"Skipping item with missing task_id or question: {item}")
+            continue
+        try:
+            submitted_answer = agent(question_text, file_path)
+            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)

hf_agent_course_final_assignment/audio_agent.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import os
+import base64
+import mimetypes
+import argparse
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+from dotenv import load_dotenv
+from huggingface_hub import InferenceClient
+
+# Load environment variables (e.g., HF_TOKEN) from a .env file
+load_dotenv()
+
+# This is the system prompt you provided
+AGENT_SYSTEM_PROMPT = """You are a general AI assistant. I will ask you a question. Report your thoughts, and finish your answer with the following template: FINAL ANSWER: [YOUR FINAL ANSWER]. YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, don't use comma to write your number neither use units such as $ or percent sign unless specified otherwise. If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities), and write the digits in plain text unless specified otherwise. If you are asked for a comma separated list, apply the above rules depending of whether the element to be put in the list is a number or a string."""
+
+
+class AudioAgent:
+    """
+    Encapsulated agent for answering questions about an audio file.
+
+    This agent works in two stages:
+    1. Transcribe the audio file using an ASR model.
+    2. Pass the transcription and the user's question to a chat model
+       to get the final answer.
+       
+    Usage:
+        # Assumes HF_TOKEN is in your environment
+        agent = AudioAgent()
+        
+        # Ask a question with an audio file
+        question = "What ingredients are in this recipe?"
+        audio_path = "/path/to/your/recipe.mp3"
+        answer = agent.answer(question, audio_path)
+        
+        # Or use the callable shortcut
+        answer = agent(question, audio_path)
+    """
+
+    def __init__(
+        self,
+        asr_model_id: Optional[str] = None,
+        chat_model_id: Optional[str] = None,
+        provider: Optional[str] = "novita",
+        temperature: float = 0.2,
+        api_key: Optional[str] = None,
+    ):
+        """
+        Initializes the AudioAgent.
+
+        Args:
+            asr_model_id: The repo ID of the ASR (transcription) model.
+            chat_model_id: The repo ID of the chat model.
+            provider: The provider for the chat InferenceClient.
+            temperature: The generation temperature for the chat model.
+            api_key: The API key. Defaults to os.environ["HF_TOKEN"].
+        """
+        # Model for speech-to-text
+        self.asr_model_id = asr_model_id or "openai/whisper-large-v3"
+        
+        # Model for answering the question based on the text
+        # Using a standard, high-performance chat model.
+        # You can change this to "meta-llama/Llama-4-Scout-17B-16E-Instruct"
+        # if you know it also performs well on text-only tasks.
+        self.chat_model_id = chat_model_id or "meta-llama/Llama-4-Scout-17B-16E-Instruct"
+        
+        self.temperature = temperature
+        
+        # Get API key from arg or environment
+        self.api_key = api_key or os.environ.get("HF_TOKEN")
+        if not self.api_key:
+            raise ValueError(
+                "API key not found. Please set the HF_TOKEN environment variable "
+                "or pass it as 'api_key' to the AudioAgent."
+            )
+
+        # 1. Client for ASR (using default HF provider)
+        # We pass the full model ID to use the standard HF inference API
+        self.asr_client = InferenceClient(
+            model=self.asr_model_id, 
+            api_key=self.api_key
+        )
+
+        # 2. Client for Chat (using your specified provider)
+        # We pass the provider, and specify the model in the create call
+        self.chat_client = InferenceClient(
+            provider=provider, 
+            api_key=self.api_key
+        )
+
+    # ---- Public API ----
+
+    def answer(self, question: str, audio_path: str) -> str:
+        """
+        Run the agent to answer a question about an audio file.
+
+        Args:
+            question: The text prompt to ask.
+            audio_path: The local file path to the audio file (e.g., .mp3).
+
+        Returns:
+            The parsed "Final Answer" string from the chat model.
+        """
+        # 1. Transcribe the audio
+        try:
+            transcription = self._transcribe(audio_path)
+        except FileNotFoundError:
+            return f"Error: Audio file not found at {audio_path}"
+        except Exception as e:
+            return f"Error during audio transcription: {e}"
+
+        # 2. Build the combined prompt for the chat model
+        combined_prompt = (
+            f"You will be given a user's question and the transcription of an audio file. "
+            f"Your task is to answer the question based *only* on the transcription.\n\n"
+            f"--- TRANSCRIPTION ---\n"
+            f"{transcription}\n"
+            f"--- END TRANSCRIPTION ---\n\n"
+            f"--- QUESTION ---\n"
+            f"{question}\n"
+            f"--- END QUESTION ---"
+        )
+        
+        # 3. Build the messages payload
+        messages = self._build_chat_messages(combined_prompt)
+
+        # 4. Call the Chat API
+        try:
+            completion = self.chat_client.chat.completions.create(
+                model=self.chat_model_id,
+                messages=messages,
+                temperature=self.temperature,
+            )
+            response_text = completion.choices[0].message.content
+        except Exception as e:
+            return f"Error calling Chat API: {e}"
+
+        # 5. Parse and return the final answer
+        return self._parse_answer(response_text)
+
+    def __call__(self, question: str, audio_path: str) -> str:
+        """Callable shortcut for self.answer()."""
+        return self.answer(question, audio_path)
+
+    # ---- Internals ----
+
+    def _transcribe(self, audio_path: str) -> str:
+        """Transcribes the audio file to text using the ASR client."""
+        p = Path(audio_path)
+        if not p.exists():
+            raise FileNotFoundError(f"No file found at {audio_path}")
+        
+        try:
+            # Read audio file as bytes
+            audio_bytes = p.read_bytes()
+            
+            # Call ASR API
+            # This task returns a dict, e.g., {'text': '...'}
+            response = self.asr_client.automatic_speech_recognition(audio_bytes)
+            
+            if "text" in response:
+                return response["text"]
+            else:
+                raise ValueError(f"ASR API response did not contain 'text': {response}")
+        except Exception as e:
+            # Re-raise as a more informative exception
+            raise RuntimeError(f"Error during audio transcription: {e}") from e
+
+    def _build_chat_messages(self, combined_prompt: str) -> List[Dict[str, Any]]:
+        """Constructs the message payload for the chat API."""
+        return [
+            {
+                "role": "system",
+                "content": AGENT_SYSTEM_PROMPT,
+            },
+            {
+                "role": "user",
+                "content": combined_prompt,
+            },
+        ]
+
+    def _parse_answer(self, response: str) -> str:
+        """Extracts the text after 'FINAL ANSWER: '."""
+        try:
+            # Use rpartition for robustness, splits on the *last* occurrence
+            _before, _marker, final_answer = response.rpartition("FINAL ANSWER: ")
+            
+            if _marker:
+                return final_answer.strip()
+            else:
+                # If marker isn't found, return the whole response with a warning
+                print("Warning: Could not find 'FINAL ANSWER:' marker. Returning full response.")
+                return response.strip()
+
+        except Exception as e:
+            print(f"Error parsing response: {e}")
+            return response.strip()
+
+
+# ---- CLI Entrypoint ----
+def main():
+    """
+    Allows running the agent from the command line.
+    
+    Example:
+       python audio_agent.py "What ingredients are listed?" "path/to/my_recipe.mp3"
+    """
+    parser = argparse.ArgumentParser(description="Class-based agent for audio questions.")
+    parser.add_argument("question", type=str, help="Your question (quoted).")
+    parser.add_argument("audio_path", type=str, help="Path to the audio file.")
+    args = parser.parse_args()
+
+    try:
+        audio_agent = AudioAgent()
+        answer = audio_agent.answer(args.question, args.audio_path)
+        print(answer)
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+if __name__ == "__main__":
+    main()

hf_agent_course_final_assignment/evaluation_questions.json

@@ -0,0 +1,122 @@
+[
+    {
+      "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.",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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?",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "task_id": "2d83110e-a098-4ebb-9987-066c06fa42d0",
+      "question": ".rewsna eht sa \"tfel\" drow eht fo etisoppo eht etirw ,ecnetnes siht dnatsrednu uoy fI",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": "cca530fc-4052-43b2-b130-b30968d8aa44.png"
+    },
+    {
+      "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?",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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?\"",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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?",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": "99c9cc74-fdc8-46c6-8f8d-3ce2d3bfeea3.mp3"
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "task_id": "f918266a-b3e0-4914-865d-4faa564f1aef",
+      "question": "What is the final numeric output from the attached Python code?",
+      "Level": "1",
+      "file_name": "f918266a-b3e0-4914-865d-4faa564f1aef.py"
+    },
+    {
+      "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?",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": "1f975693-876d-457b-a649-393859e79bf3.mp3"
+    },
+    {
+      "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?",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": ""
+    },
+    {
+      "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.",
+      "Level": "1",
+      "file_name": "7bd855d8-463d-4ed5-93ca-5fe35145f733.xlsx"
+    },
+    {
+      "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?",
+      "Level": "1",
+      "file_name": ""
+    }
+  ]

hf_agent_course_final_assignment/excel_agent.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import os
+import argparse
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+from dotenv import load_dotenv
+from huggingface_hub import InferenceClient
+
+# Import pandas for Excel/CSV handling
+try:
+    import pandas as pd
+except ImportError:
+    print("Error: 'pandas' and 'openpyxl' libraries are required for ExcelAgent.")
+    print("Please install them with: pip install pandas openpyxl")
+    exit(1)
+
+
+# Load environment variables (e.g., HF_TOKEN) from a .env file
+load_dotenv()
+
+# This is the system prompt you provided
+AGENT_SYSTEM_PROMPT = """You are a general AI assistant. I will ask you a question. Report your thoughts, and finish your answer with the following template: FINAL ANSWER: [YOUR FINAL ANSWER]. YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, don't use comma to write your number neither use units such as $ or percent sign unless specified otherwise. If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities), and write the digits in plain text unless specified otherwise. If you are asked for a comma separated list, apply the above rules depending of whether the element to be put in the list is a number or a string."""
+
+
+class ExcelAgent:
+    """
+    Encapsulated agent for answering questions about an Excel file.
+
+    This agent works in two stages:
+    1. Read the Excel file and convert its content to a text (CSV) format.
+    2. Pass the user's question and the text-based data to a chat model
+       to get the final answer.
+       
+    Usage:
+        # Assumes HF_TOKEN is in your environment
+        agent = ExcelAgent()
+        
+        # Ask a question with an Excel file
+        question = "What are the total sales?"
+        excel_path = "/path/to/your/data.xlsx"
+        answer = agent.answer(question, excel_path)
+        
+        # Or use the callable shortcut
+        answer = agent(question, excel_path)
+    """
+
+    def __init__(
+        self,
+        chat_model_id: Optional[str] = None,
+        provider: Optional[str] = "novita",
+        temperature: float = 0.1,
+        api_key: Optional[str] = None,
+    ):
+        """
+        Initializes the ExcelAgent.
+
+        Args:
+            chat_model_id: The repo ID of the chat model.
+            provider: The provider for the chat InferenceClient.
+            temperature: The generation temperature for the chat model.
+            api_key: The API key. Defaults to os.environ["HF_TOKEN"].
+        """
+        # We use the same powerful model as the ImageAgent
+        self.chat_model_id = chat_model_id or "meta-llama/Llama-4-Scout-17B-16E-Instruct"
+        self.temperature = temperature
+        
+        # Get API key from arg or environment
+        self.api_key = api_key or os.environ.get("HF_TOKEN")
+        if not self.api_key:
+            raise ValueError(
+                "API key not found. Please set the HF_TOKEN environment variable "
+                "or pass it as 'api_key' to the ExcelAgent."
+            )
+
+        # Client for Chat
+        self.chat_client = InferenceClient(
+            provider=provider, 
+            api_key=self.api_key
+        )
+
+    # ---- Public API ----
+
+    def answer(self, question: str, excel_path: str) -> str:
+        """
+        Run the agent to answer a question about an Excel file.
+
+        Args:
+            question: The text prompt to ask.
+            excel_path: The local file path to the Excel file (.xlsx).
+
+        Returns:
+            The parsed "Final Answer" string from the chat model.
+        """
+        # 1. Read Excel and convert to text
+        try:
+            data_as_text = self._excel_to_text(excel_path)
+        except FileNotFoundError:
+            return f"Error: Excel file not found at {excel_path}"
+        except Exception as e:
+            return f"Error during Excel processing: {e}"
+
+        # 2. Build the combined prompt for the chat model
+        combined_prompt = (
+            f"You will be given a user's question and the content of an Excel file. "
+            f"The Excel data is represented in CSV format. "
+            f"Your task is to answer the question based *only* on the provided data.\n\n"
+            f"--- DATA (CSV format) ---\n"
+            f"{data_as_text}\n"
+            f"--- END DATA ---\n\n"
+            f"--- QUESTION ---\n"
+            f"{question}\n"
+            f"--- END QUESTION ---"
+        )
+        
+        # 3. Build the messages payload
+        messages = self._build_chat_messages(combined_prompt)
+
+        # 4. Call the Chat API
+        try:
+            completion = self.chat_client.chat.completions.create(
+                model=self.chat_model_id,
+                messages=messages,
+                temperature=self.temperature,
+            )
+            response_text = completion.choices[0].message.content
+        except Exception as e:
+            return f"Error calling Chat API: {e}"
+
+        # 5. Parse and return the final answer
+        return self._parse_answer(response_text)
+
+    def __call__(self, question: str, excel_path: str) -> str:
+        """Callable shortcut for self.answer()."""
+        return self.answer(question, excel_path)
+
+    # ---- Internals ----
+
+    def _excel_to_text(self, excel_path: str) -> str:
+        """Reads an Excel file and converts it to a CSV string."""
+        p = Path(excel_path)
+        if not p.exists():
+            raise FileNotFoundError(f"No file found at {excel_path}")
+        
+        try:
+            # Read the Excel file
+            # By default, reads the first sheet
+            df = pd.read_excel(str(p))
+            
+            # Convert DataFrame to a CSV string
+            # index=False to avoid writing row numbers
+            csv_string = df.to_csv(index=False)
+            
+            return csv_string
+        except Exception as e:
+            # Re-raise as a more informative exception
+            raise RuntimeError(f"Error reading/converting Excel file: {e}") from e
+
+    def _build_chat_messages(self, combined_prompt: str) -> List[Dict[str, Any]]:
+        """Constructs the message payload for the chat API."""
+        return [
+            {
+                "role": "system",
+                "content": AGENT_SYSTEM_PROMPT,
+            },
+            {
+                "role": "user",
+                "content": combined_prompt,
+            },
+        ]
+
+    def _parse_answer(self, response: str) -> str:
+        """Extracts the text after 'FINAL ANSWER: '."""
+        try:
+            # Use rpartition for robustness, splits on the *last* occurrence
+            _before, _marker, final_answer = response.rpartition("FINAL ANSWER: ")
+            
+            if _marker:
+                return final_answer.strip()
+            else:
+                # If marker isn't found, return the whole response with a warning
+                print("Warning: Could not find 'FINAL ANSWER:' marker. Returning full response.")
+                return response.strip()
+
+        except Exception as e:
+            print(f"Error parsing response: {e}")
+            return response.strip()
+
+
+# ---- CLI Entrypoint ----
+def main():
+    """
+    Allows running the agent from the command line.
+    
+    Example:
+       python excel_agent.py "What are the total sales?" "path/to/my_data.xlsx"
+    """
+    parser = argparse.ArgumentParser(description="Class-based agent for Excel questions.")
+    parser.add_argument("question", type=str, help="Your question (quoted).")
+    parser.add_argument("excel_path", type=str, help="Path to the Excel file.")
+    args = parser.parse_args()
+
+    try:
+        excel_agent = ExcelAgent()
+        answer = excel_agent.answer(args.question, args.excel_path)
+        print(answer)
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+if __name__ == "__main__":
+    main()

hf_agent_course_final_assignment/gaia_agent.py

@@ -0,0 +1,334 @@
+# gaia_agent.py
+#
+# High-level GAIA orchestrator with LLM-based routing.
+#
+# Usage:
+#   from gaia_agent import GaiaAgent
+#   from utils.fetch_files import fetch_files_gaia_validation_hub
+#
+#   gaia_agent = GaiaAgent()
+#
+#   # Q without file
+#   ans1 = gaia_agent(
+#       "How many studio albums were published by Mercedes Sosa between 2000 and 2009 (included)? You can use the latest 2022 version of english wikipedia.",
+#       ""
+#   )
+#
+#   # Q with file (image)
+#   img_path = fetch_files_gaia_validation_hub("cca530fc-4052-43b2-b130-b30968d8aa44.png")
+#   ans2 = gaia_agent(
+#       "Review the chess position provided in the image. It is black's turn...",
+#       img_path
+#   )
+#
+#   # Q with YouTube link
+#   ans3 = gaia_agent(
+#       "In the video https://www.youtube.com/watch?v=L1vXCYZAYYM, what is the highest number of bird species to be on camera simultaneously?",
+#       ""
+#   )
+#
+#   print(ans1, ans2, ans3)
+
+from __future__ import annotations
+
+import os
+import re
+import mimetypes
+from typing import Optional, Dict, Any, List
+from urllib.parse import urlparse, parse_qs
+
+from dotenv import load_dotenv
+from huggingface_hub import InferenceClient
+
+from web_agent import WebAgent
+from image_agent import ImageAgent
+from audio_agent import AudioAgent
+from python_agent import PythonAgent
+from excel_agent import ExcelAgent
+from youtube_agent import YouTubeSubsAgent  # YouTubeSubsAgent(question, video_url)
+
+load_dotenv()
+
+#########################################################
+# 1. Routing model prompt / helper
+#########################################################
+
+ROUTER_SYSTEM_PROMPT = """You are a routing controller for a GAIA QA system.
+Your job is to look at a task and decide which specialized tool should answer it.
+
+TOOLS:
+- "web": For questions that need factual info from the internet, Wikipedia, sports stats, award numbers, historical rosters, etc. Use this if the answer relies on public info not contained in an attached file or transcript.
+- "youtube": For questions that refer to a YouTube video URL and ask about what was said/heard in that video. The YouTube agent only has access to the video's subtitles.
+- "image": For questions that require analyzing an image file (ex: chessboard, screenshot, diagram). File extensions like .png/.jpg/.jpeg.
+- "audio": For questions that require transcribing or extracting info from an audio file (ex: .mp3, .wav, "listen to the recording and list ingredients").
+- "excel": For questions that require reading a spreadsheet (.xls, .xlsx, .csv) and doing numeric reasoning or lookup in that sheet.
+- "python": For questions that say "What is the final numeric output from the attached Python code?" or otherwise require running code from a .py file.
+- "internal_reasoning": For pure logic, math, text manipulation, categorization, set theory, etc. No web. No external file beyond the text in the question.
+
+RESTRICTIONS AND NOTES:
+1. If there is a YouTube link in the question (youtube.com or youtu.be) and the user is asking about what someone says or does in that video, choose "youtube".
+2. If there is an attached file_path and it's an image, choose "image".
+3. If there is an attached file_path and it's audio, choose "audio".
+4. If there is an attached file_path and it's Excel/CSV, choose "excel".
+5. If there is an attached file_path and it's Python code (.py), choose "python".
+6. Otherwise, if answering requires up-to-date or external factual knowledge (e.g. Wikipedia, sports stats, award numbers, who played in some show, etc.), choose "web".
+7. Otherwise choose "internal_reasoning".
+
+OUTPUT FORMAT:
+Return ONLY one of the following exact strings:
+web
+youtube
+image
+audio
+excel
+python
+internal_reasoning
+"""
+
+INTERNAL_REASONING_SYSTEM_PROMPT = """You are a general AI assistant. I will ask you a question. Report your thoughts, and finish your answer with the following template: FINAL ANSWER: [YOUR FINAL ANSWER]. YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, don't use comma to write your number neither use units such as $ or percent sign unless specified otherwise. If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities), and write the digits in plain text unless specified otherwise. If you are asked for a comma separated list, apply the above rules depending of whether the element to be put in the list is a number or a string."""
+
+class RoutingLLM:
+    """
+    A tiny wrapper around the HF InferenceClient that decides the tool name.
+    """
+
+    def __init__(
+        self,
+        model_id: Optional[str] = None,
+        provider: str = "novita",
+        temperature: float = 0.0,
+        api_key: Optional[str] = None,
+    ):
+        self.model_id = model_id or "meta-llama/Llama-4-Scout-17B-16E-Instruct"
+        self.temperature = temperature
+
+        self.api_key = api_key or os.environ.get("HF_TOKEN")
+        if not self.api_key:
+            raise ValueError("RoutingLLM: HF_TOKEN not found and api_key not provided.")
+
+        self.client = InferenceClient(provider=provider, api_key=self.api_key)
+
+    def route(self, question: str, file_path: Optional[str]) -> str:
+        """
+        Ask the LLM which tool to use.
+        We also inject lightweight hints (file extension, presence of YT link),
+        so the LLM has explicit signals.
+        """
+        file_path = file_path or ""
+        ext = os.path.splitext(file_path)[1].lower() if file_path else ""
+        mime, _ = mimetypes.guess_type(file_path) if file_path else (None, None)
+        has_youtube = "youtube.com" in question.lower() or "youtu.be" in question.lower()
+
+        user_prompt = (
+            "Question:\n"
+            f"{question}\n\n"
+            "file_path:\n"
+            f"{file_path}\n"
+            f"(extension='{ext}', mime='{mime}', has_youtube={has_youtube})\n\n"
+            "Which tool should handle this? Remember: output ONLY one of:\n"
+            "web | youtube | image | audio | excel | python | internal_reasoning"
+        )
+
+        messages = [
+            {"role": "system", "content": ROUTER_SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        completion = self.client.chat.completions.create(
+            model=self.model_id,
+            messages=messages,
+            temperature=self.temperature,
+        )
+
+        raw = completion.choices[0].message.content.strip().lower()
+
+        # clean it to a known label
+        return self._normalize_route_label(raw)
+
+    def _normalize_route_label(self, raw: str) -> str:
+        """
+        Normalize whatever the model said into one of the 7 valid labels,
+        with a safe fallback.
+        """
+        allowed = {
+            "web",
+            "youtube",
+            "image",
+            "audio",
+            "excel",
+            "python",
+            "internal_reasoning",
+        }
+
+        # grab the first token-like word that matches any allowed label
+        for word in re.findall(r"[a-z_]+", raw):
+            if word in allowed:
+                return word
+
+        # fallback: default to "web" because GAIA often needs retrieval
+        return "web"
+
+
+#########################################################
+# 2. GaiaAgent Orchestrator
+#########################################################
+
+class GaiaAgent:
+    """
+    High-level GAIA orchestrator with an LLM router.
+
+    Init:
+        gaia_agent = GaiaAgent()
+
+    Call:
+        ans = gaia_agent(question, file_path)
+
+    where:
+        - question: str
+        - file_path: str or "" (path to local file if provided for that task)
+    """
+
+    def __init__(
+        self,
+        chat_model_id: Optional[str] = None,
+        router_model_id: Optional[str] = None,
+        provider: str = "novita",
+        temperature: float = 0.2,
+        router_temperature: float = 0.0,
+        api_key: Optional[str] = None,
+    ):
+        self.chat_model_id = chat_model_id or "meta-llama/Llama-4-Scout-17B-16E-Instruct"
+        self.temperature = temperature
+
+        # shared key/client
+        self.api_key = api_key or os.environ.get("HF_TOKEN")
+        if not self.api_key:
+            raise ValueError("GaiaAgent: HF_TOKEN not found and api_key not provided.")
+
+        # core reasoning client (for internal_reasoning branch)
+        self.reasoning_client = InferenceClient(
+            provider=provider,
+            api_key=self.api_key,
+        )
+
+        # router (LLM-based intent classifier)
+        self.router = RoutingLLM(
+            model_id=router_model_id or self.chat_model_id,
+            provider=provider,
+            temperature=router_temperature,
+            api_key=self.api_key,
+        )
+
+        # instantiate sub-agents once
+        self.web_agent = WebAgent()  # expects question
+        self.youtube_agent = YouTubeSubsAgent(
+            api_key=self.api_key,
+        )  # expects (question, video_url)
+        self.image_agent = ImageAgent(
+            api_key=self.api_key,
+        )  # expects (question, file_path)
+        self.audio_agent = AudioAgent(
+            api_key=self.api_key,
+        )  # expects (question, file_path)
+        self.python_agent = PythonAgent()  # expects (file_path)
+        self.excel_agent = ExcelAgent(
+            api_key=self.api_key,
+        )  # expects (question, file_path)
+
+    def __call__(self, question: str, file_path: Optional[str] = "") -> str:
+        return self.answer(question, file_path)
+
+    def answer(self, question: str, file_path: Optional[str] = "") -> str:
+        """
+        1. Ask router LLM which tool to use.
+        2. Dispatch to that tool.
+        3. Return the tool's final answer.
+        """
+        route = self.router.route(question, file_path)
+
+        if route == "youtube":
+            print("[GaiaAgent] Routing to YouTube agent.")
+            video_url = self._extract_youtube_url(question)
+            return self.youtube_agent(question, video_url if video_url else "")
+
+        if route == "image":
+            print("[GaiaAgent] Routing to Image agent.")
+            return self.image_agent(question, file_path)
+
+        if route == "audio":
+            print("[GaiaAgent] Routing to Audio agent.")
+            return self.audio_agent(question, file_path)
+
+        if route == "excel":
+            print("[GaiaAgent] Routing to Excel agent.")
+            return self.excel_agent(question, file_path)
+
+        if route == "python":
+            print("[GaiaAgent] Routing to Python agent.")
+            return self._run_python_agent(file_path)
+
+        if route == "web":
+            print("[GaiaAgent] Routing to Web agent.")
+            return self.web_agent(question)
+
+        # internal_reasoning or fallback
+        print("[GaiaAgent] Routing to Internal Reasoning.")
+        return self._internal_reasoning(question)
+
+    #########################################################
+    # internal helpers
+    #########################################################
+
+    def _extract_youtube_url(self, text: str) -> Optional[str]:
+        """
+        Pull first YouTube URL from question.
+        """
+        m = re.search(r"(https?://[^\s]+youtu[^\s]+)", text)
+        if m:
+            return m.group(1).strip().rstrip(').,]')
+        return None
+
+    def _run_python_agent(self, file_path: str) -> str:
+        """
+        PythonAgent currently is called like python_agent_instance(file_path)
+        and returns output as string.
+        """
+        return self.python_agent(file_path)
+
+    def _internal_reasoning(self, question: str) -> str:
+        """
+        Use the same GAIA-style 'FINAL ANSWER:' contract,
+        but do pure reasoning, no web.
+        """
+        reasoning_prompt = (
+            "You will be given a question that can be answered using reasoning, "
+            "math, logic, text manipulation, categorization, or other internal thinking. "
+            "Do not use any outside knowledge beyond what a normal educated human would know; "
+            "do not fabricate web data.\n\n"
+            "Question:\n"
+            f"{question}\n\n"
+            "Remember to follow the FINAL ANSWER format exactly."
+        )
+
+        messages = [
+            {"role": "system", "content": INTERNAL_REASONING_SYSTEM_PROMPT},
+            {"role": "user", "content": reasoning_prompt},
+        ]
+
+        completion = self.reasoning_client.chat.completions.create(
+            model=self.chat_model_id,
+            messages=messages,
+            temperature=self.temperature,
+        )
+
+        raw = completion.choices[0].message.content
+        return self._parse_final_answer(raw)
+
+    def _parse_final_answer(self, response: str) -> str:
+        """
+        Extract text after 'FINAL ANSWER:' to stay consistent with other agents.
+        """
+        _before, _marker, final_answer = response.rpartition("FINAL ANSWER: ")
+        if _marker:
+            return final_answer.strip()
+        return response.strip()

hf_agent_course_final_assignment/image_agent.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import os
+import base64
+import mimetypes
+import argparse
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+from dotenv import load_dotenv
+from huggingface_hub import InferenceClient
+
+# Load environment variables (e.g., HF_TOKEN) from a .env file
+load_dotenv()
+
+# This is the system prompt you provided
+AGENT_SYSTEM_PROMPT = """You are a general AI assistant. I will ask you a question. Report your thoughts, and finish your answer with the following template: FINAL ANSWER: [YOUR FINAL ANSWER]. YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, don't use comma to write your number neither use units such as $ or percent sign unless specified otherwise. If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities), and write the digits in plain text unless specified otherwise. If you are asked for a comma separated list, apply the above rules depending of whether the element to be put in the list is a number or a string."""
+
+
+class ImageAgent:
+    """
+    Encapsulated agent for answering questions about an image.
+
+    Usage:
+        # Assumes HF_TOKEN is in your environment
+        agent = ImageAgent()
+        
+        # Ask a question with an image
+        question = "What is in this image?"
+        image_path = "/path/to/your/image.png"
+        answer = agent.answer(question, image_path)
+        
+        # Or use the callable shortcut
+        answer = agent(question, image_path)
+    """
+
+    def __init__(
+        self,
+        model_id: Optional[str] = None,
+        provider: Optional[str] = "novita",
+        temperature: float = 0.2,
+        api_key: Optional[str] = None,
+    ):
+        """
+        Initializes the ImageAgent.
+
+        Args:
+            model_id: The repository ID of the model to use.
+            provider: The provider for the InferenceClient.
+            temperature: The generation temperature.
+            api_key: The API key. Defaults to os.environ["HF_TOKEN"].
+        """
+        self.model_id = model_id or "meta-llama/Llama-4-Scout-17B-16E-Instruct"
+        self.temperature = temperature
+        
+        # Get API key from arg or environment, raising an error if missing
+        self.api_key = api_key or os.environ.get("HF_TOKEN")
+        if not self.api_key:
+            raise ValueError(
+                "API key not found. Please set the HF_TOKEN environment variable "
+                "or pass it as 'api_key' to the ImageAgent."
+            )
+
+        # Initialize the client
+        self.client = InferenceClient(
+            provider=provider,
+            api_key=self.api_key,
+        )
+
+    # ---- Public API ----
+
+    def answer(self, question: str, image_path: str) -> str:
+        """
+        Run the agent to answer a question about an image.
+
+        Args:
+            question: The text prompt to ask the model.
+            image_path: The local file path to the image.
+
+        Returns:
+            The parsed "Final Answer" string from the model.
+        """
+        # 1. Convert image to data URL
+        try:
+            image_data_url = self._to_data_url(image_path)
+        except FileNotFoundError:
+            return f"Error: Image file not found at {image_path}"
+        except Exception as e:
+            return f"Error processing image: {e}"
+
+        # 2. Build the messages payload
+        messages = self._build_messages(question, image_data_url)
+
+        # 3. Call the API
+        try:
+            completion = self.client.chat.completions.create(
+                model=self.model_id,
+                messages=messages,
+                temperature=self.temperature,
+            )
+            response_text = completion.choices[0].message.content
+        except Exception as e:
+            return f"Error calling API: {e}"
+
+        # 4. Parse and return the final answer
+        return self._parse_answer(response_text)
+
+    def __call__(self, question: str, image_path: str) -> str:
+        """Callable shortcut for self.answer()."""
+        return self.answer(question, image_path)
+
+    # ---- Internals ----
+
+    def _to_data_url(self, path: str) -> str:
+        """Converts a local file path to a base64 data URL."""
+        p = Path(path)
+        if not p.exists():
+            raise FileNotFoundError(f"No file found at {path}")
+            
+        mime = mimetypes.guess_type(str(p))[0] or "image/png"
+        b64 = base64.b64encode(p.read_bytes()).decode("utf-8")
+        return f"data:{mime};base64,{b64}"
+
+    def _build_messages(self, question: str, image_data_url: str) -> List[Dict[str, Any]]:
+        """Constructs the message payload for the API."""
+        return [
+            {
+                "role": "system",
+                "content": [
+                    {"type": "text", "text": AGENT_SYSTEM_PROMPT},
+                ],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": question},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": image_data_url},
+                    },
+                ],
+            },
+        ]
+
+    def _parse_answer(self, response: str) -> str:
+        """Extracts the text after 'FINAL ANSWER: '."""
+        try:
+            # Use rpartition for robustness, splits on the *last* occurrence
+            _before, _marker, final_answer = response.rpartition("FINAL ANSWER: ")
+            
+            if _marker:
+                return final_answer.strip()
+            else:
+                # If marker isn't found, return the whole response with a warning
+                print("Warning: Could not find 'FINAL ANSWER:' marker. Returning full response.")
+                return response.strip()
+
+        except Exception as e:
+            print(f"Error parsing response: {e}")
+            return response.strip()
+
+
+# ---- CLI Entrypoint ----
+def main():
+    """
+    Allows running the agent from the command line.
+    
+    Example:
+       python image_agent.py "What move is this?" "path/to/my_image.png"
+    """
+    parser = argparse.ArgumentParser(description="Class-based agent for image questions.")
+    parser.add_argument("question", type=str, help="Your question (quoted).")
+    parser.add_argument("image_path", type=str, help="Path to the image file.")
+    args = parser.parse_args()
+
+    try:
+        image_agent = ImageAgent()
+        answer = image_agent.answer(args.question, args.image_path)
+        print(answer)
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+if __name__ == "__main__":
+    main()

hf_agent_course_final_assignment/packages.txt

@@ -0,0 +1 @@
+stockfish

hf_agent_course_final_assignment/python_agent.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+import base64
+import mimetypes
+import argparse
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+from dotenv import load_dotenv
+from huggingface_hub import InferenceClient
+import io
+from contextlib import redirect_stdout
+
+load_dotenv()
+
+class PythonAgent:
+    def __init__(self):
+        # print("Python code execution agent initialized.")
+        pass
+    
+    def __call__(self, file_path: str) -> str:
+        return self.execute_python_file(file_path)
+
+
+    def execute_python_file(self, file_path: str) -> str:
+        import io
+        from contextlib import redirect_stdout
+
+        with open(file_path, "r") as f_in:
+            code_to_exec = f_in.read()
+
+        # important: real module-like globals with __name__="__main__"
+        sandbox_globals = {
+            "__name__": "__main__",
+            "__file__": file_path,
+        }
+
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            try:
+                exec(code_to_exec, sandbox_globals)
+            except Exception as e:
+                print(f"An error occurred: {e}")
+
+        raw_response = buf.getvalue()
+        # the response is the last line
+        response = raw_response.strip().splitlines()[-1]
+        return response
+
+# path_python_file = r"downloaded\f918266a-b3e0-4914-865d-4faa564f1aef.py"
+# response = execute_python_file(path_python_file)
+# print(response)

hf_agent_course_final_assignment/requirements.txt

@@ -0,0 +1,29 @@
+gradio>=4.44.0
+requests>=2.32.0
+pandas>=2.2.2
+
+# LangChain stack
+langchain==0.3.27 
+langchain-core==0.3.79
+langchain-community==0.3.31
+langchain-huggingface>=0.1.0
+huggingface_hub==0.35.3
+transformers==4.57.1
+pytorch
+
+pillow==11.3.0 
+ddgs==9.6.1 
+beautifulsoup4>=4.12.3
+duckduckgo-search>=6.2.5
+wikipedia>=1.4.0
+youtube-transcript-api==1.2.3
+faster-whisper>=1.0.3
+openpyxl>=3.1.5
+python-dotenv==1.1.1
+bs4>=0.0.2
+lxml>=5.3.0
+
+openpyxl==3.1.5 
+
+
+# accelerate

hf_agent_course_final_assignment/test_agents.py

@@ -0,0 +1,93 @@
+from web_agent import WebAgent
+from utils.fetch_files import fetch_files_gaia_validation_hub
+from image_agent import ImageAgent
+from audio_agent import AudioAgent
+from python_agent import PythonAgent
+from excel_agent import ExcelAgent
+from youtube_agent import YouTubeSubsAgent
+from gaia_agent import GaiaAgent
+
+# ## testing the web agent alone
+# test_question_web = "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?"
+# webagent_instance = WebAgent()
+# webagent_answer = webagent_instance(test_question_web)
+
+## testing the image agent
+# test_question_image = "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."
+# file_name = "cca530fc-4052-43b2-b130-b30968d8aa44.png"
+# img_path = fetch_files_gaia_validation_hub(file_name)
+# print(img_path)
+# print("------- Image Agent ------------------")
+# imageagent_instance = ImageAgent()
+# imageagent_answer = imageagent_instance(test_question_image, img_path)
+# print(imageagent_answer)
+
+## testing the audio agent
+# test_question_audio = "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."
+# file_name = "99c9cc74-fdc8-46c6-8f8d-3ce2d3bfeea3.mp3"
+# video_path = fetch_files_gaia_validation_hub(file_name)
+# print(video_path)
+
+# audioagent_instance = AudioAgent()
+# audioagent_answer = audioagent_instance(test_question_audio, video_path)
+# print(audioagent_answer)
+
+
+## Testing the python code execution agent
+# test_question_python = "What is the final numeric output from the attached Python code?"
+# file_name = "f918266a-b3e0-4914-865d-4faa564f1aef.py"
+# script_path = fetch_files_gaia_validation_hub(file_name)
+# print(script_path)
+# pythonagent_instance = PythonAgent()
+# pythonagent_answer = pythonagent_instance(script_path)
+# print(pythonagent_answer)
+
+## Testing the excel agent
+# test_question_excel = "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."
+# file_name = "7bd855d8-463d-4ed5-93ca-5fe35145f733.xlsx"
+# excel_path = fetch_files_gaia_validation_hub(file_name)
+# print(excel_path)
+# excelagent_instance = ExcelAgent()
+# excelagent_answer = excelagent_instance(test_question_excel, excel_path)
+# print(excelagent_answer)
+
+## Testing youtube agent
+# youtube_agent = YouTubeSubsAgent()
+# ans = youtube_agent(
+#     "What does Teal'c say in response to the question \"Isn't that hot?\"",
+#     "https://www.youtube.com/watch?v=1htKBjuUWec"
+# )
+# print(ans)
+
+
+gaia_agent = GaiaAgent()
+
+# q = "How many studio albums were published by Mercedes Sosa between 2000 and 2009 (included)? You can use the latest 2022 version of english wikipedia."
+# ans = gaia_agent(q, "")
+
+# q = "Examine the video at https://www.youtube.com/watch?v=1htKBjuUWec. What does Teal'c say in response to the question \"Isn't that hot?\""
+# ans = gaia_agent(q, "")
+
+# file_img = fetch_files_gaia_validation_hub("cca530fc-4052-43b2-b130-b30968d8aa44.png")
+# q = "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."
+# ans = gaia_agent(q, file_img)
+
+# file_audio = fetch_files_gaia_validation_hub("1f975693-876d-457b-a649-393859e79bf3.mp3")
+# q = "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."
+# ans = gaia_agent(q, file_audio)
+
+# file_xlsx = fetch_files_gaia_validation_hub("7bd855d8-463d-4ed5-93ca-5fe35145f733.xlsx")
+# q = "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."
+# ans = gaia_agent(q, file_xlsx)
+
+# file_py = fetch_files_gaia_validation_hub("f918266a-b3e0-4914-865d-4faa564f1aef.py")
+# q = "What is the final numeric output from the attached Python code?"
+# ans = gaia_agent(q, file_py)
+
+q = ".rewsna eht sa \"tfel\" drow eht fo etisoppo eht etirw ,ecnetnes siht dnatsrednu uoy fI"
+ans = gaia_agent(q, "")
+
+print(ans)
+
+# from huggingface_hub import whoami
+# whoami()

hf_agent_course_final_assignment/utils/fetch_files.py

@@ -0,0 +1,37 @@
+""" Function to fetch files from the GAIA (validation set) in huggingface repo. """
+import os, requests, huggingface_hub
+from huggingface_hub import hf_hub_download
+
+def fetch_files_gaia_validation_hub(filename: str):
+    """
+    Fetch a file from the GAIA validation set hosted on Hugging Face Hub.
+    Args:
+        filename (str): The name of the file to fetch (e.g., 'question_1.json').
+    Returns:
+        str: Local path to the downloaded file.
+    """
+    if not filename:
+        raise ValueError("Please provide a valid filename.")
+
+    repo_id = "gaia-benchmark/GAIA"
+    repo_type = "dataset"
+    path_in_repo = f"2023/validation/{filename}"
+
+    # If you need a private token: set HF_TOKEN env var or pass token=...
+    downloaded_path = hf_hub_download(
+        repo_id=repo_id,
+        repo_type=repo_type,
+        filename=path_in_repo,
+        # token=os.getenv("HF_TOKEN"),  # uncomment if needed
+        force_download=False
+    )
+
+    # Copy into ./downloaded to keep a consistent local layout
+    os.makedirs("downloaded", exist_ok=True)
+    local_path = os.path.join("downloaded", filename)
+    if os.path.abspath(downloaded_path) != os.path.abspath(local_path):
+        # Lightweight copy
+        with open(downloaded_path, "rb") as src, open(local_path, "wb") as dst:
+            dst.write(src.read())
+
+    return local_path

hf_agent_course_final_assignment/web_agent.py

@@ -0,0 +1,180 @@
+# web_agent.py
+# Minimal web-searching LangChain agent for GAIA-style questions.
+# - Tools: DuckDuckGo search + HTTP GET
+# - Model: defaults to a lightweight reasoning-ready open model (Hugging Face), but you can
+#          swap to any chat model supported by LangChain. If you don't set HF token, we'll
+#          fall back to a simple reasoning prompt with the same interface.
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import List, Optional, Dict, Any
+
+# LangChain core (v0.2+ / v0.3)
+from langchain.agents import AgentExecutor, create_react_agent
+from langchain_core.prompts import PromptTemplate
+from langchain_core.runnables import RunnableConfig
+from langchain_community.utilities import RequestsWrapper
+from langchain.tools import Tool
+
+# Chat model: Hugging Face Endpoint (no key required to run, but highly recommended)
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+
+# Community tools
+from langchain_community.tools import DuckDuckGoSearchRun, RequestsGetTool
+
+# ---- Prompt (self-contained: no hub dependency) ----
+REACT_PROMPT = """You are a meticulous research assistant for GAIA-style fact questions.
+
+You have access to these tools:
+{tools}
+
+Use this format:
+
+Question: the input question to answer
+Thought: think about what to search or read next
+Action: one of [{tool_names}]
+Action Input: the input to the action
+Observation: the result of the action
+... (repeat Thought/Action/Observation as needed)
+Thought: I can now answer.
+Final Answer: <the shortest exact answer>
+
+Follow the rules:
+- Prefer precise quotes from primary/official sources when possible.
+- Keep the final answer SHORT (a few words if possible)
+- If you need multiple pages, open them sequentially.
+- Never repeat the exact same Action Input twice. If an Action returns a login, auth, or error page, change strategy (use search with site: filters, try a different public page, or a cached/mirrored source).
+- If a URL contains "login", "@app/auth", or "returnto=", do NOT open it; search for a public page instead.
+
+Question: {input}
+{agent_scratchpad}"""
+
+# Final Answer: <the shortest exact answer> — <single best source URL>
+# - Keep the final answer SHORT (a few words if possible) plus one URL.
+class WebAgent:
+    """Encapsulated GAIA-style web agent.
+
+    Usage:
+        web_agent = WebAgent()
+        result = web_agent("Who is the CEO of ...?")
+        # or
+        result = web_agent.answer("...")
+
+    You can also run as a script:
+        python web_agent.py "Your question here"
+    """
+
+    def __init__(
+        self,
+        hf_repo_id: Optional[str] = None,
+        max_new_tokens: int = 2048,
+        do_sample: bool = False,
+        repetition_penalty: float = 1.05,
+        max_iterations: int = 20,
+        verbose: bool = True,
+        user_agent: str = "Mozilla/5.0 (compatible; GAIA/1.0; +https://example.org/bot)",
+    ):
+        self.hf_repo_id = hf_repo_id or os.environ.get("HF_REPO_ID", "Qwen/Qwen2.5-7B-Instruct")
+        self.max_new_tokens = max_new_tokens
+        self.do_sample = do_sample
+        self.repetition_penalty = repetition_penalty
+        self.max_iterations = max_iterations
+        self.verbose = verbose
+        self.user_agent = user_agent
+
+        # Built lazily so each call gets a fresh per-run "seen URL" set for the guarded GET.
+        self._executor: Optional[AgentExecutor] = None
+        self._tools: Optional[List[Tool]] = None
+
+    # ---- Public API ----
+    def answer(self, question: str) -> str:
+        """Run the agent and return the model's 'Final Answer' string."""
+        executor = self._build_agent()  # build fresh each time to reset guarded state
+        result: Dict[str, Any] = executor.invoke({"input": question})
+        return result["output"]
+
+    def __call__(self, question: str) -> str:
+        return self.answer(question)
+
+    # ---- Internals ----
+    def _build_model(self) -> ChatHuggingFace:
+        llm = HuggingFaceEndpoint(
+            repo_id=self.hf_repo_id,
+            task="text-generation",
+            max_new_tokens=self.max_new_tokens,
+            do_sample=self.do_sample,
+            repetition_penalty=self.repetition_penalty,
+        )
+        return ChatHuggingFace(llm=llm)
+
+    def _build_tools(self) -> List[Tool]:
+        wrapper = RequestsWrapper(headers={"User-Agent": self.user_agent})
+        raw_get = RequestsGetTool(
+            name="Requests Get (raw)",
+            requests_wrapper=wrapper,
+            allow_dangerous_requests=True,
+        )
+
+        seen: set[str] = set()
+
+        def guarded_get(url: str) -> str:
+            low = url.lower()
+            if any(x in low for x in ["@app/auth", "login?returnto=", "/login"]):
+                return ("BLOCKED: This looks like a login/auth wall. "
+                        "Use search to find a public or cached page instead.")
+            if url in seen:
+                return (f"BLOCKED: Already fetched {url}. "
+                        "Choose a different URL or try a different query.")
+            seen.add(url)
+            return raw_get.run(url)
+
+        return [
+            DuckDuckGoSearchRun(name="DuckDuckGo Search"),
+            Tool.from_function(
+                name="Requests Get",
+                func=guarded_get,
+                description="HTTP GET for public pages; prevents repeats and login walls.",
+            ),
+        ]
+
+    def _build_agent(self) -> AgentExecutor:
+        model = self._build_model()
+        tools = self._build_tools()
+        prompt = PromptTemplate.from_template(REACT_PROMPT)
+
+        agent = create_react_agent(model, tools, prompt)
+        executor = AgentExecutor(
+            agent=agent,
+            tools=tools,
+            max_iterations=self.max_iterations,
+            handle_parsing_errors=True,
+            verbose=self.verbose,
+        )
+        return executor
+
+
+# def main():
+#     parser = argparse.ArgumentParser(description="Simple LangChain web agent for GAIA-style questions.")
+#     parser.add_argument("question", type=str, help="Your question (quoted).")
+#     args = parser.parse_args()
+
+#     print(answer(args.question))
+
+
+# if __name__ == "__main__":
+#     main()
+
+# ---- CLI Entrypoint ----
+def main():
+    parser = argparse.ArgumentParser(description="Class-based LangChain web agent for GAIA-style questions.")
+    parser.add_argument("question", type=str, help="Your question (quoted).")
+    args = parser.parse_args()
+
+    web_agent = WebAgent()
+    print(web_agent.answer(args.question))
+
+
+if __name__ == "__main__":
+    main()

hf_agent_course_final_assignment/youtube_agent.py

@@ -0,0 +1,216 @@
+# youtube_subs_agent.py
+# GAIA-style YouTube subtitle-based agent using youtube-transcript-api.
+#
+# Usage:
+#   pip install youtube-transcript-api python-dotenv huggingface_hub
+#
+# Example:
+#   from youtube_subs_agent import YouTubeSubsAgent
+#
+#   agent = YouTubeSubsAgent()
+#   answer = agent(
+#       "What does Teal'c say in response to the question 'Isn't that hot?'",
+#       "https://www.youtube.com/watch?v=1htKBjuUWec"
+#   )
+#   print(answer)
+
+from __future__ import annotations
+
+import os
+from typing import Optional, List, Dict, Any
+from urllib.parse import urlparse, parse_qs
+
+from dotenv import load_dotenv
+from youtube_transcript_api import (
+    YouTubeTranscriptApi,
+    TranscriptsDisabled,
+    NoTranscriptFound,
+    VideoUnavailable,
+)
+from huggingface_hub import InferenceClient
+
+load_dotenv()
+
+AGENT_SYSTEM_PROMPT = """You are a general AI assistant. I will ask you a question. Report your thoughts, and finish your answer with the following template: FINAL ANSWER: [YOUR FINAL ANSWER]. YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, don't use comma to write your number neither use units such as $ or percent sign unless specified otherwise. If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities), and write the digits in plain text unless specified otherwise. If you are asked for a comma separated list, apply the above rules depending of whether the element to be put in the list is a number or a string."""
+
+
+class YouTubeSubsAgent:
+    """
+    GAIA-style agent for answering questions about YouTube videos using subtitles.
+
+    Usage:
+        agent = YouTubeSubsAgent()
+        answer = agent(
+            "What does Teal'c say in response to the question 'Isn't that hot?'",
+            "https://www.youtube.com/watch?v=1htKBjuUWec"
+        )
+    """
+
+    def __init__(
+        self,
+        chat_model_id: Optional[str] = None,
+        provider: str = "novita",
+        temperature: float = 0.2,
+        api_key: Optional[str] = None,
+        transcript_char_limit: int = 12000,
+        languages: Optional[List[str]] = None,
+    ):
+        """
+        languages: priority list for transcript languages.
+                   default = English-first fallback.
+        """
+        self.chat_model_id = chat_model_id or "meta-llama/Llama-4-Scout-17B-16E-Instruct"
+        self.temperature = temperature
+        self.transcript_char_limit = transcript_char_limit
+        self.languages = languages or ["en", "en-US", "en-GB"]
+
+        self.api_key = api_key or os.environ.get("HF_TOKEN")
+        if not self.api_key:
+            raise ValueError(
+                "API key not found. Please set the HF_TOKEN environment variable or pass api_key=."
+            )
+
+        self.client = InferenceClient(provider=provider, api_key=self.api_key)
+
+    # ---- Public API ----
+
+    def answer(self, question: str, video_url: str) -> str:
+        """Main call method: question + YouTube URL."""
+        transcript_text = self._fetch_transcript_text(video_url)
+        prompt = self._build_reasoning_prompt(question, transcript_text)
+        response = self._run_chat(prompt)
+        return self._parse_final_answer(response)
+
+    def __call__(self, question: str, video_url: str) -> str:
+        """Shortcut for answer()."""
+        return self.answer(question, video_url)
+
+    # ---- Internals ----
+
+    def _extract_video_id(self, url: str) -> str:
+        """
+        Extracts the video ID from common YouTube URL formats.
+        Falls back to returning the input if it looks like a bare ID already.
+        """
+        parsed = urlparse(url)
+
+        # Short link: https://youtu.be/VIDEOID
+        if parsed.hostname in ("youtu.be",):
+            # path is like "/VIDEOID"
+            return parsed.path.strip("/")
+
+        # Standard watch link: https://www.youtube.com/watch?v=VIDEOID
+        if parsed.hostname in ("www.youtube.com", "youtube.com", "m.youtube.com"):
+            qs = parse_qs(parsed.query)
+            if "v" in qs:
+                return qs["v"][0]
+
+        # Fallback: assume caller already passed just the ID
+        return url
+
+    def _fetch_transcript_text(self, video_url: str) -> str:
+        """
+        Fetch transcript with youtube-transcript-api, format it as
+        MM:SS text
+        one line per snippet, and truncate if needed.
+        """
+        video_id = self._extract_video_id(video_url)
+
+        try:
+            fetched = YouTubeTranscriptApi().fetch(
+                video_id,
+                languages=self.languages,
+            )
+        except (TranscriptsDisabled, NoTranscriptFound, VideoUnavailable) as e:
+            print(f"Warning: no transcript available for this video ({e}).")
+            return ""
+
+        # IMPORTANT FIX:
+        # 'fetched' is a FetchedTranscript, which is iterable, but each element
+        # is a FetchedTranscriptSnippet (attributes, not dicts).
+        # Easiest: convert to raw dicts first.
+        raw_snippets = fetched.to_raw_data()
+
+        def format_ts(seconds_float: float) -> str:
+            seconds_int = int(seconds_float)
+            mm = seconds_int // 60
+            ss = seconds_int % 60
+            return f"{mm:02d}:{ss:02d}"
+
+        lines: List[str] = []
+        for snip in raw_snippets:
+            start_ts = format_ts(snip["start"])
+            text = snip["text"]
+            # Collapse internal newlines that YouTube sometimes puts in a single snippet
+            text = text.replace("\n", " ").strip()
+            if text:
+                lines.append(f"{start_ts} {text}")
+
+        transcript_text = "\n".join(lines)
+
+        if len(transcript_text) > self.transcript_char_limit:
+            transcript_text = transcript_text[: self.transcript_char_limit] + "\n[truncated]"
+
+        return transcript_text
+
+    def _build_reasoning_prompt(self, question: str, transcript_text: str) -> str:
+        """
+        Create the reasoning prompt for the LLM.
+        """
+        return (
+            "You will be given a question about a YouTube video's dialogue and its transcript.\n"
+            "Answer ONLY using what is said in the transcript. If the user asks for an exact quote, "
+            "repeat the line(s) exactly as spoken.\n\n"
+            "----- QUESTION -----\n"
+            f"{question}\n"
+            "----- END QUESTION -----\n\n"
+            "----- TRANSCRIPT -----\n"
+            f"{transcript_text if transcript_text else '[no transcript available]'}\n"
+            "----- END TRANSCRIPT -----\n"
+        )
+
+    def _run_chat(self, prompt: str) -> str:
+        """
+        Send the reasoning prompt to the chat model.
+        """
+        messages: List[Dict[str, Any]] = [
+            {"role": "system", "content": AGENT_SYSTEM_PROMPT},
+            {"role": "user", "content": prompt},
+        ]
+
+        completion = self.client.chat.completions.create(
+            model=self.chat_model_id,
+            messages=messages,
+            temperature=self.temperature,
+        )
+
+        return completion.choices[0].message.content
+
+    def _parse_final_answer(self, response: str) -> str:
+        """
+        Extract 'FINAL ANSWER: ...' just like in your other agents.
+        """
+        _before, _marker, final_answer = response.rpartition("FINAL ANSWER: ")
+        if _marker:
+            return final_answer.strip()
+        else:
+            return response.strip()
+
+# ---- CLI Entrypoint ----
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="GAIA-style YouTube subtitles agent (youtube-transcript-api).")
+    parser.add_argument("question", type=str, help='Your question (quoted).')
+    parser.add_argument("video_url", type=str, help="YouTube video URL.")
+    args = parser.parse_args()
+
+    try:
+        agent = YouTubeSubsAgent()
+        answer = agent(args.question, args.video_url)
+        print(answer)
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+
+if __name__ == "__main__":
+    main()