Create youtube_video_analysis

tools/youtube_video_analysis

@@ -0,0 +1,192 @@
+"""
+YouTube video analysis tool for smolagents.
+
+Uses Google's Gemini API directly because Gemini supports public YouTube
+URLs as native video inputs.
+
+Requirements:
+    pip install google-genai smolagents
+
+Environment:
+    GEMINI_API_KEY=your_api_key
+"""
+
+import os
+import re
+from typing import Any
+
+from smolagents import Tool
+from google import genai
+
+
+class YouTubeVideoAnalysisTool(Tool):
+    name = "youtube_video_analysis"
+
+    description = """
+    Analyze a public YouTube video using Gemini's native video understanding.
+
+    Use this tool when a question requires actually watching or visually
+    inspecting a YouTube video, especially questions about:
+    - objects or people visible in the video
+    - animals or species visible
+    - events happening at particular times
+    - counts of objects/people/species on screen
+    - visual comparisons
+    - what appears simultaneously on camera
+    - visual details that cannot be reliably answered from a transcript
+
+    This tool accepts a public YouTube URL and a natural-language question.
+    Gemini analyzes the video and returns a detailed answer with timestamps
+    when possible.
+    """
+
+    inputs = {
+        "url": {
+            "type": "string",
+            "description": "Public YouTube video URL.",
+        },
+        "question": {
+            "type": "string",
+            "description": "The specific question to answer from the video.",
+        },
+    }
+
+    output_type = "string"
+
+    def __init__(
+        self,
+        model: str = "gemini-2.5-flash",
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+
+        api_key = os.getenv("GEMINI_API_KEY")
+
+        if not api_key:
+            raise RuntimeError(
+                "GEMINI_API_KEY environment variable is not set."
+            )
+
+        self.model = model
+        self.client = genai.Client(api_key=api_key)
+
+    def forward(self, url: str, question: str) -> str:
+        """
+        Analyze a YouTube video and answer the supplied question.
+        """
+
+        # Basic URL validation.
+        if not self._is_youtube_url(url):
+            return (
+                "ERROR: The supplied URL does not appear to be a valid "
+                "YouTube URL."
+            )
+
+        if not question.strip():
+            return "ERROR: The question cannot be empty."
+
+        prompt = f"""
+You are analyzing a YouTube video to answer a factual research question.
+
+VIDEO:
+{url}
+
+QUESTION:
+{question}
+
+Instructions:
+
+1. Actually inspect the video content.
+2. Do not rely solely on the title, description, comments, or external
+   webpages.
+3. For questions involving things visible on camera, inspect the visual
+   content carefully.
+4. If the question asks for a maximum or minimum, examine the relevant
+   portions of the video rather than giving an estimate.
+5. Distinguish different species, people, objects, etc. when the question
+   requires it.
+6. When useful, provide timestamps showing the evidence.
+7. Give the final answer clearly at the end.
+8. If something cannot be determined reliably, explicitly say so rather
+   than guessing.
+
+Return a concise but evidence-based answer.
+"""
+
+        try:
+            response = self.client.interactions.create(
+                model=self.model,
+                input=[
+                    {
+                        "type": "text",
+                        "text": prompt,
+                    },
+                    {
+                        "type": "video",
+                        "uri": url,
+                    },
+                ],
+            )
+
+            answer = getattr(response, "output_text", None)
+
+            if answer:
+                return answer.strip()
+
+            # Fallback for SDK versions where output_text is unavailable.
+            return self._extract_output(response)
+
+        except Exception as exc:
+            return (
+                "VIDEO_ANALYSIS_ERROR: "
+                f"{type(exc).__name__}: {exc}"
+            )
+
+    @staticmethod
+    def _is_youtube_url(url: str) -> bool:
+        """Check whether the URL is a normal YouTube URL."""
+
+        pattern = re.compile(
+            r"^https?://"
+            r"(www\.)?"
+            r"(youtube\.com/watch\?v=|youtu\.be/)"
+            r"[A-Za-z0-9_-]+",
+            re.IGNORECASE,
+        )
+
+        return bool(pattern.search(url.strip()))
+
+    @staticmethod
+    def _extract_output(response: Any) -> str:
+        """
+        Fallback response extraction.
+
+        Different google-genai versions can expose interaction output
+        slightly differently, so this attempts several common forms.
+        """
+
+        # Try dictionary-style response.
+        if isinstance(response, dict):
+            if response.get("output_text"):
+                return str(response["output_text"]).strip()
+
+            output = response.get("output")
+
+            if output:
+                return str(output).strip()
+
+        # Try normal object attributes.
+        output_text = getattr(response, "output_text", None)
+
+        if output_text:
+            return str(output_text).strip()
+
+        output = getattr(response, "output", None)
+
+        if output:
+            return str(output).strip()
+
+        return (
+            "VIDEO_ANALYSIS_ERROR: Gemini returned a response, "
+            "but no text output could be extracted."
+        )