add smolagents docstrings

src/file_processing_tool.py

@@ -5,6 +5,10 @@ import os
 import mimetypes
 
 class FileIdentifier:
+    """
+    Identifies file types and maps them to the appropriate processing tool based on file extension.
+    Useful for routing files to specialized tools such as speech-to-text, spreadsheet parser, image processor, etc.
+    """
     def __init__(self):
         mimetypes.init()
         # Mapping from simple type to action and common extensions

src/image_processing_tool.py

@@ -20,6 +20,11 @@ vision_pipeline = pipeline(
 )
 
 class ImageProcessor:
+    """
+    Processes image files, including OCR, vision reasoning, and chessboard analysis.
+    Integrates computer vision and chess engines for advanced image-based tasks.
+    Useful for extracting text, analyzing chess positions, and general image understanding.
+    """
     def __init__(self):
         self.vision_pipeline = vision_pipeline
         

src/markdown_table_parser.py

@@ -6,6 +6,7 @@ def parse_markdown_table(markdown_text: str) -> dict[str, list[str]] | None:
     Parses the first valid Markdown table found in a string.
     Returns a dictionary (headers as keys, lists of cell content as values)
     or None if no valid table is found.
+    Useful for converting markdown tables into Python data structures for further analysis.
     """
     lines = [line.rstrip() for line in markdown_text.split('\n') if line.strip()]
     n = len(lines)

src/python_tool.py

@@ -7,7 +7,10 @@ import traceback
 from typing import Dict, Any, Optional, Union, List
 
 class CodeExecutionTool:
-    """Tool to safely execute Python code files and extract numeric outputs."""
+    """
+    Executes Python code in a controlled environment for safe code interpretation.
+    Useful for evaluating code snippets and returning their output or errors.
+    """
     
     def __init__(self, timeout: int = 5, max_output_size: int = 10000):
         self.timeout = timeout  # Maximum execution time in seconds

src/speech_to_text.py

@@ -11,7 +11,11 @@ asr_pipeline = pipeline(
 
 def transcribe_audio(audio_filepath):
     """
-    Transcribes an audio file using the Hugging Face ASR pipeline.
+    Converts speech in an audio file (e.g., .mp3) to text using speech recognition.
+    Args:
+        audio_filepath (str): Path to the audio file.
+    Returns:
+        str: Transcribed text from the audio.
     """
     try:
         transcription = asr_pipeline(audio_filepath, return_timestamps=True)

src/spreadsheet_tool.py

@@ -5,7 +5,10 @@ import numpy as np
 
 
 class SpreadsheetTool:
-    """Tool for parsing and extracting data from Excel (.xlsx) files."""
+    """
+    Parses spreadsheet files (e.g., .xlsx) and extracts tabular data for analysis.
+    Useful for reading, processing, and converting spreadsheet content to Python data structures.
+    """
     
     def __init__(self):
         """Initialize the SpreadsheetTool."""

src/text_reversal_tool.py

@@ -1,5 +1,7 @@
 def reverse_text(text: str) -> str:
-    """Reverses the input string."""
+    """
+    Reverses or processes reversed text, useful for decoding or analyzing reversed strings.
+    """
     return text[::-1]
 
 if __name__ == '__main__':

src/video_processing_tool.py

@@ -0,0 +1,433 @@
+import os
+import yt_dlp
+import cv2
+import numpy as np
+from youtube_transcript_api import YouTubeTranscriptApi, TranscriptsDisabled, NoTranscriptFound
+import tempfile
+import re
+import shutil
+import time # Added for retry logic
+
+class VideoProcessingTool:
+    """
+    Analyzes video content, extracting information such as frames, audio, or metadata.
+    Useful for tasks like video summarization, frame extraction, transcript analysis, or content analysis.
+    """
+
+    def __init__(self, model_cfg_path=None, model_weights_path=None, class_names_path=None, temp_dir_base=None):
+        """
+        Initializes the VideoProcessingTool.
+
+        Args:
+            model_cfg_path (str, optional): Path to the object detection model's configuration file.
+            model_weights_path (str, optional): Path to the object detection model's weights file.
+            class_names_path (str, optional): Path to the file containing class names for the model.
+            temp_dir_base (str, optional): Base directory for temporary files. Defaults to system temp.
+        """
+        if temp_dir_base:
+            self.temp_dir = tempfile.mkdtemp(dir=temp_dir_base)
+        else:
+            self.temp_dir = tempfile.mkdtemp()
+        
+        self.object_detection_model = None
+        self.class_names = []
+
+        if model_cfg_path and model_weights_path and class_names_path:
+            if os.path.exists(model_cfg_path) and os.path.exists(model_weights_path) and os.path.exists(class_names_path):
+                try:
+                    self.object_detection_model = cv2.dnn.readNetFromDarknet(model_cfg_path, model_weights_path)
+                    # Set preferable backend and target
+                    self.object_detection_model.setPreferableBackend(cv2.dnn.DNN_BACKEND_OPENCV)
+                    self.object_detection_model.setPreferableTarget(cv2.dnn.DNN_TARGET_CPU)
+                    with open(class_names_path, "r") as f:
+                        self.class_names = [line.strip() for line in f.readlines()]
+                except Exception as e:
+                    print(f"Error loading CV model: {e}. Object detection will not be available.")
+                    self.object_detection_model = None
+            else:
+                print("Warning: One or more CV model paths are invalid. Object detection will not be available.")
+
+    def _extract_video_id(self, youtube_url):
+        """Extract the YouTube video ID from a URL."""
+        match = re.search(r"(?:v=|\/|embed\/|watch\?v=|youtu\.be\/)([0-9A-Za-z_-]{11})", youtube_url)
+        if match:
+            return match.group(1)
+        return None
+
+    def download_video(self, youtube_url, resolution="360p"):
+        """Download YouTube video for processing."""
+        video_id = self._extract_video_id(youtube_url)
+        if not video_id:
+            return {"error": "Invalid YouTube URL or could not extract video ID."}
+
+        output_file_name = f"{video_id}.mp4"
+        output_file_path = os.path.join(self.temp_dir, output_file_name)
+
+        if os.path.exists(output_file_path): # Avoid re-downloading
+            return {"success": True, "file_path": output_file_path, "message": "Video already downloaded."}
+
+        try:
+            ydl_opts = {
+                'format': f'bestvideo[height<={resolution[:-1]}][ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best',
+                'outtmpl': output_file_path,
+                'noplaylist': True,
+                'quiet': True,
+                'no_warnings': True,
+            }
+            with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+                ydl.download([youtube_url])
+            
+            if not os.path.exists(output_file_path): # Check if download actually created the file
+                 # Fallback for some formats if mp4 direct is not available
+                ydl_opts['format'] = f'best[height<={resolution[:-1]}]' # more generic
+                with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+                    info_dict = ydl.extract_info(youtube_url, download=True)
+                    # yt-dlp might save with a different extension, find the downloaded file
+                    downloaded_files = [f for f in os.listdir(self.temp_dir) if f.startswith(video_id)]
+                    if downloaded_files:
+                        actual_file_path = os.path.join(self.temp_dir, downloaded_files[0])
+                        if actual_file_path != output_file_path and actual_file_path.endswith(('.mkv', '.webm', '.flv')):
+                            # Minimal conversion to mp4 if needed, or just use the downloaded format if cv2 supports it
+                            # For simplicity, we'll assume cv2 can handle common formats or user ensures mp4 compatible download
+                            output_file_path = actual_file_path # Use the actual downloaded file
+                        elif not actual_file_path.endswith('.mp4'): # if it's not mp4 and not handled above
+                             return {"error": f"Downloaded video is not in a directly usable format: {downloaded_files[0]}"}
+
+
+            if os.path.exists(output_file_path):
+                return {"success": True, "file_path": output_file_path}
+            else:
+                return {"error": "Video download failed, file not found after attempt."}
+
+        except yt_dlp.utils.DownloadError as e:
+            return {"error": f"yt-dlp download error: {str(e)}"}
+        except Exception as e:
+            return {"error": f"Failed to download video: {str(e)}"}
+
+    def get_video_transcript(self, youtube_url, languages=None):
+        """Get the transcript/captions of a YouTube video."""
+        if languages is None:
+            languages = ['en', 'en-US'] # Default to English
+        video_id = self._extract_video_id(youtube_url)
+        if not video_id:
+            return {"error": "Invalid YouTube URL or could not extract video ID."}
+        
+        try:
+            # Reverting to list_transcripts due to issues with list() in the current env
+            transcript_list_obj = YouTubeTranscriptApi.list_transcripts(video_id)
+            
+            transcript = None
+            # Try to find a manual transcript first in the specified languages
+            try:
+                transcript = transcript_list_obj.find_manually_created_transcript(languages)
+            except NoTranscriptFound:
+                # If no manual transcript, try to find a generated one
+                # This will raise NoTranscriptFound if it also fails, which is caught below.
+                transcript = transcript_list_obj.find_generated_transcript(languages)
+            
+            # Retry logic for transcript.fetch()
+            fetched_transcript_entries = None
+            max_attempts = 3  # Total attempts
+            last_fetch_exception = None
+
+            for attempt in range(max_attempts):
+                try:
+                    fetched_transcript_entries = transcript.fetch()
+                    last_fetch_exception = None # Clear exception on success
+                    break  # Successful fetch
+                except Exception as e_fetch:
+                    last_fetch_exception = e_fetch
+                    if attempt < max_attempts - 1:
+                        time.sleep(1) # Wait 1 second before retrying
+                    # If it's the last attempt, the loop will end, and last_fetch_exception will be set.
+            
+            if last_fetch_exception: # If all attempts failed
+                raise last_fetch_exception # Re-raise the last exception from fetch()
+
+            # Correctly access the 'text' attribute
+            full_transcript_text = " ".join([entry.text for entry in fetched_transcript_entries])
+            
+            return {
+                "success": True, 
+                "transcript": full_transcript_text, 
+                "transcript_entries": fetched_transcript_entries
+            }
+        except TranscriptsDisabled:
+            return {"error": "Transcripts are disabled for this video."}
+        except NoTranscriptFound: # This will catch if neither manual nor generated is found for the languages
+            return {"error": f"No transcript found for the video in languages: {languages}."}
+        except Exception as e:
+            # Catches other exceptions from YouTubeTranscriptApi calls or re-raised from fetch
+            return {"error": f"Failed to get transcript: {str(e)}"}
+
+    def count_objects_in_video(self, video_path, target_classes=None, confidence_threshold=0.5, frame_skip=5):
+        """
+        Counts specified objects appearing in the video using the loaded DNN model.
+        Determines the maximum number of target objects appearing simultaneously in any single frame.
+        Args:
+            video_path (str): Path to the video file.
+            target_classes (list, optional): A list of object classes (strings) to count (e.g., ["bird", "cat"]).
+                                            If None, counts all detected objects.
+            confidence_threshold (float): Minimum confidence for an object to be counted.
+            frame_skip (int): Process every Nth frame to speed up analysis.
+        Returns:
+            dict: A dictionary with counts or an error message.
+                  e.g., {"success": True, "max_simultaneous_birds": 3, "max_simultaneous_cats": 1}
+                  or {"error": "Object detection model not loaded."}
+        """
+        if not self.object_detection_model or not self.class_names:
+            return {"error": "Object detection model not loaded or class names missing."}
+        if not os.path.exists(video_path):
+            return {"error": f"Video file not found: {video_path}"}
+
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            return {"error": "Could not open video file."}
+
+        max_counts_per_class = {cls: 0 for cls in target_classes} if target_classes else {}
+        # If target_classes is None, we'd need to initialize for all detected classes,
+        # but for simplicity, let's require target_classes for now or adjust later.
+        if not target_classes:
+            # Defaulting to a common class if none specified, e.g. 'person'
+            # Or, one could count all unique classes detected. For GAIA, specific targets are better.
+            return {"error": "target_classes must be specified for counting."}
+
+
+        frame_count = 0
+        while cap.isOpened():
+            ret, frame = cap.read()
+            if not ret:
+                break
+
+            frame_count += 1
+            if frame_count % frame_skip != 0:
+                continue
+
+            height, width = frame.shape[:2]
+            blob = cv2.dnn.blobFromImage(frame, 1/255.0, (416, 416), swapRB=True, crop=False)
+            self.object_detection_model.setInput(blob)
+            
+            layer_names = self.object_detection_model.getLayerNames()
+            # Handle potential differences in getUnconnectedOutLayers() return value
+            unconnected_out_layers_indices = self.object_detection_model.getUnconnectedOutLayers()
+            if isinstance(unconnected_out_layers_indices, np.ndarray) and unconnected_out_layers_indices.ndim > 1 : # For some OpenCV versions
+                 output_layer_names = [layer_names[i[0] - 1] for i in unconnected_out_layers_indices]
+            else: # For typical cases
+                 output_layer_names = [layer_names[i - 1] for i in unconnected_out_layers_indices]
+
+            detections = self.object_detection_model.forward(output_layer_names)
+
+            current_frame_counts = {cls: 0 for cls in target_classes}
+
+            for detection_set in detections: # Detections can come from multiple output layers
+                for detection in detection_set:
+                    scores = detection[5:]
+                    class_id = np.argmax(scores)
+                    confidence = scores[class_id]
+
+                    if confidence > confidence_threshold:
+                        detected_class_name = self.class_names[class_id]
+                        if detected_class_name in target_classes:
+                            current_frame_counts[detected_class_name] += 1
+            
+            for cls in target_classes:
+                if current_frame_counts[cls] > max_counts_per_class[cls]:
+                    max_counts_per_class[cls] = current_frame_counts[cls]
+        
+        cap.release()
+        result = {"success": True}
+        for cls, count in max_counts_per_class.items():
+            result[f"max_simultaneous_{cls.replace(' ', '_')}"] = count # e.g. "max_simultaneous_bird"
+        return result
+
+    def find_dialogue_response(self, transcript_entries, query_phrase, max_entries_gap=2, max_time_gap_s=5.0):
+        """
+        Finds what is said in response to a given query phrase in transcript entries.
+        Looks for the query phrase and then captures the text from subsequent entries.
+
+        Args:
+            transcript_entries (list): List of transcript dictionaries (from get_video_transcript).
+            query_phrase (str): The phrase to find (e.g., a question).
+            max_entries_gap (int): How many transcript entries to look ahead for a response.
+            max_time_gap_s (float): Maximum time in seconds after the query phrase to consider for a response.
+
+        Returns:
+            dict: {"success": True, "response_text": "...", "found_at_entry": {...}} or {"error": "..."}
+        """
+        if not transcript_entries:
+            return {"error": "Transcript entries are empty."}
+
+        query_phrase_lower = query_phrase.lower().rstrip('?.!,;') # Strip common trailing punctuation
+        
+        for i, entry in enumerate(transcript_entries):
+            # Correctly access attributes: .text, .start, .duration
+            if query_phrase_lower in entry.text.lower():
+                # Found the query phrase, now look for the response
+                response_parts = []
+                start_time_of_query = entry.start + entry.duration # End time of query entry
+
+                for j in range(i + 1, min(i + 1 + max_entries_gap + 1, len(transcript_entries))):
+                    next_entry = transcript_entries[j]
+                    # Check if the next entry is within the time gap
+                    if next_entry.start - start_time_of_query > max_time_gap_s:
+                        break # Too much time has passed
+
+                    # Add text if it's not just noise or very short (heuristic)
+                    if next_entry.text.strip() and len(next_entry.text.strip()) > 1:
+                         response_parts.append(next_entry.text)
+                    
+                    # If we have collected some response, and the next entry is significantly later, stop.
+                    if response_parts and (j + 1 < len(transcript_entries)):
+                        if transcript_entries[j+1].start - (next_entry.start + next_entry.duration) > 1.0: # If gap > 1s
+                            break
+
+                if response_parts:
+                    return {
+                        "success": True, 
+                        "response_text": " ".join(response_parts),
+                        "query_entry": entry,
+                        "response_start_entry_index": i + 1
+                    }
+                # If no response found immediately after, but query was found
+                return {"error": f"Query phrase '{query_phrase}' found, but no subsequent dialogue captured as response within gap."}
+
+        return {"error": f"Query phrase '{query_phrase}' not found in transcript."}
+
+
+    def process_video(self, youtube_url, query_type, query_params=None):
+        """
+        Main method to process a video based on the type of query.
+        
+        Args:
+            youtube_url (str): URL of the YouTube video.
+            query_type (str): Type of processing: "transcript", "object_count", "dialogue_response".
+            query_params (dict, optional): Additional parameters for the specific query type.
+                For "object_count": {"target_classes": ["bird"], "confidence_threshold": 0.5, "resolution": "360p"}
+                For "dialogue_response": {"query_phrase": "Isn't that hot?", "languages": ['en']}
+        """
+        if query_params is None:
+            query_params = {}
+
+        if query_type == "transcript":
+            return self.get_video_transcript(youtube_url, languages=query_params.get("languages"))
+            
+        elif query_type == "object_count":
+            if not self.object_detection_model:
+                return {"error": "Object detection model not initialized. Cannot count objects."}
+            
+            resolution = query_params.get("resolution", "360p")
+            download_result = self.download_video(youtube_url, resolution=resolution)
+            if "error" in download_result:
+                return download_result
+            
+            video_path = download_result["file_path"]
+            target_classes = query_params.get("target_classes")
+            if not target_classes or not isinstance(target_classes, list):
+                return {"error": "query_params must include 'target_classes' as a list for object_count."}
+            
+            confidence = query_params.get("confidence_threshold", 0.5)
+            frame_skip = query_params.get("frame_skip", 5)
+            return self.count_objects_in_video(video_path, target_classes, confidence, frame_skip)
+            
+        elif query_type == "dialogue_response":
+            transcript_result = self.get_video_transcript(youtube_url, languages=query_params.get("languages"))
+            if "error" in transcript_result:
+                return transcript_result
+            
+            query_phrase = query_params.get("query_phrase")
+            if not query_phrase:
+                return {"error": "query_params must include 'query_phrase' for dialogue_response."}
+            
+            return self.find_dialogue_response(
+                transcript_result["transcript_entries"],
+                query_phrase,
+                max_entries_gap=query_params.get("max_entries_gap", 2),
+                max_time_gap_s=query_params.get("max_time_gap_s", 5.0)
+            )
+            
+        return {"error": f"Unsupported query type: {query_type}"}
+
+    def cleanup(self):
+        """Remove temporary files and directory."""
+        if os.path.exists(self.temp_dir):
+            shutil.rmtree(self.temp_dir, ignore_errors=True)
+            # print(f"Cleaned up temp directory: {self.temp_dir}")
+
+# Example Usage (for testing purposes, assuming model files are in ./models/cv/):
+if __name__ == '__main__':
+    # Create dummy model files for local testing if they don't exist
+    os.makedirs("./models/cv", exist_ok=True)
+    dummy_cfg = "./models/cv/dummy-yolov3-tiny.cfg"
+    dummy_weights = "./models/cv/dummy-yolov3-tiny.weights"
+    dummy_names = "./models/cv/dummy-coco.names"
+
+    if not os.path.exists(dummy_cfg): open(dummy_cfg, 'w').write("# Dummy YOLOv3 tiny config")
+    if not os.path.exists(dummy_weights): open(dummy_weights, 'w').write("dummy weights") # Actual weights file is binary
+    if not os.path.exists(dummy_names): open(dummy_names, 'w').write("bird\\ncat\\ndog\\nperson")
+    
+    # Initialize tool
+    # Note: For real object detection, provide paths to actual .cfg, .weights, and .names files.
+    # For example, from: https://pjreddie.com/darknet/yolo/
+    video_tool = VideoProcessingTool(
+        model_cfg_path=dummy_cfg, # Replace with actual path to YOLOv3-tiny.cfg or similar
+        model_weights_path=dummy_weights, # Replace with actual path to YOLOv3-tiny.weights
+        class_names_path=dummy_names # Replace with actual path to coco.names
+    )
+
+    # Test 1: Get Transcript
+    # Replace with a video that has transcripts
+    transcript_test_url = "https://www.youtube.com/watch?v=1htKBjuUWec" # Stargate SG-1 clip
+    print(f"--- Testing Transcript for: {transcript_test_url} ---")
+    transcript_info = video_tool.process_video(transcript_test_url, "transcript")
+    if transcript_info.get("success"):
+        print("Transcript (first 100 chars):", transcript_info.get("transcript", "")[:100])
+    else:
+        print("Transcript Error:", transcript_info.get("error"))
+    print("\\n")
+
+    # Test 2: Find Dialogue Response
+    dialogue_test_url = "https://www.youtube.com/watch?v=1htKBjuUWec" # Stargate SG-1 clip
+    print(f"--- Testing Dialogue Response for: {dialogue_test_url} ---")
+    dialogue_info = video_tool.process_video(
+        dialogue_test_url, 
+        "dialogue_response", 
+        query_params={"query_phrase": "Isn't that hot?"}
+    )
+    if dialogue_info.get("success"):
+        print(f"Query: 'Isn't that hot?', Response: '{dialogue_info.get('response_text')}'")
+    else:
+        print("Dialogue Error:", dialogue_info.get("error"))
+    print("\\n")
+
+    # Test 3: Object Counting (will likely use dummy model and might not detect much without real video/model)
+    # Replace with a video URL that you want to test object counting on.
+    # This example will download a short video.
+    object_count_test_url = "https://www.youtube.com/watch?v=L1vXCYZAYYM" # Birds video
+    print(f"--- Testing Object Counting for: {object_count_test_url} ---")
+    # Ensure you have actual model files for this to work meaningfully.
+    # The dummy model files will likely result in zero counts or errors if OpenCV can't parse them.
+    # For this example, we expect it to run through, but actual detection depends on valid models.
+    if video_tool.object_detection_model:
+        count_info = video_tool.process_video(
+            object_count_test_url,
+            "object_count",
+            query_params={"target_classes": ["bird"], "resolution": "360p"}
+        )
+        if count_info.get("success"):
+            print("Object Counts:", count_info)
+        else:
+            print("Object Counting Error:", count_info.get("error"))
+    else:
+        print("Object detection model not loaded, skipping object count test.")
+    
+    # Cleanup
+    video_tool.cleanup()
+    # Clean up dummy model files if they were created by this script
+    # (Be careful if you have real files with these names)
+    # if os.path.exists(dummy_cfg) and "dummy-yolov3-tiny.cfg" in dummy_cfg : os.remove(dummy_cfg)
+    # if os.path.exists(dummy_weights) and "dummy-yolov3-tiny.weights" in dummy_weights: os.remove(dummy_weights)
+    # if os.path.exists(dummy_names) and "dummy-coco.names" in dummy_names: os.remove(dummy_names)
+    # if os.path.exists("./models/cv") and not os.listdir("./models/cv"): os.rmdir("./models/cv")
+    # if os.path.exists("./models") and not os.listdir("./models"): os.rmdir("./models")
+
+    print("\\nAll tests finished.")

src/web_browsing_tool.py

@@ -3,7 +3,8 @@ from bs4 import BeautifulSoup
 
 class WebBrowser:
     """
-    A simple web browser tool to fetch and parse content from URLs.
+    Retrieves information from online sources by browsing web pages or performing web searches.
+    Useful for extracting or summarizing web content.
     """
 
     def __init__(self, user_agent="GAIA-Agent/1.0"):

tests/test_video_processing_tool.py

@@ -0,0 +1,198 @@
+import pytest
+import os
+import shutil
+
+import os
+import sys
+
+# Add the parent directory to sys.path to find the src module
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from src.video_processing_tool import VideoProcessingTool
+
+
+
+# --- Test Configuration ---
+# URLs for testing different functionalities
+# Ensure these videos are publicly accessible and have expected features (transcripts, specific objects)
+# Using videos from the common_questions.json for relevance
+VIDEO_URL_TRANSCRIPT_DIALOGUE = "https://www.youtube.com/watch?v=1htKBjuUWec" # Stargate SG-1 "Isn't that hot?"
+VIDEO_URL_OBJECT_COUNT = "https://www.youtube.com/watch?v=L1vXCYZAYYM"      # Birds video
+VIDEO_URL_NO_TRANSCRIPT = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" # Rick Astley (often no official transcript)
+VIDEO_URL_SHORT_GENERAL = "https://www.youtube.com/watch?v=jNQXAC9IVRw" # Short Creative Commons video (Big Buck Bunny)
+
+# --- Fixtures ---
+@pytest.fixture(scope="session")
+def model_files():
+    """Creates dummy model files for testing CV functionality if real ones aren't provided."""
+    # Using a sub-directory within the test directory for these files
+    test_model_dir = os.path.join(os.path.dirname(__file__), "test_cv_models")
+    os.makedirs(test_model_dir, exist_ok=True)
+    
+    cfg_path = os.path.join(test_model_dir, "dummy-yolov3-tiny.cfg")
+    weights_path = os.path.join(test_model_dir, "dummy-yolov3-tiny.weights")
+    names_path = os.path.join(test_model_dir, "dummy-coco.names")
+
+    # Create minimal dummy files if they don't exist
+    # These won't make OpenCV's DNN module load a functional model but allow testing the file handling logic.
+    # For actual DNN model loading, valid model files are required.
+    if not os.path.exists(cfg_path): open(cfg_path, 'w').write("[net]\nwidth=416\nheight=416")
+    if not os.path.exists(weights_path): open(weights_path, 'wb').write(b'dummyweights')
+    if not os.path.exists(names_path): open(names_path, 'w').write("bird\ncat\ndog\nperson\n")
+    
+    yield {
+        "cfg": cfg_path,
+        "weights": weights_path,
+        "names": names_path,
+        "dir": test_model_dir
+    }
+    # Cleanup: remove the dummy model directory after tests
+    # shutil.rmtree(test_model_dir, ignore_errors=True) # Keep for inspection if tests fail
+
+@pytest.fixture
+def video_tool(model_files):
+    """Initializes VideoProcessingTool with dummy model paths for testing."""
+    # Using a specific temp directory for test artifacts
+    test_temp_dir_base = os.path.join(os.path.dirname(__file__), "test_temp_videos")
+    os.makedirs(test_temp_dir_base, exist_ok=True)
+
+    tool = VideoProcessingTool(
+        model_cfg_path=model_files["cfg"],
+        model_weights_path=model_files["weights"],
+        class_names_path=model_files["names"],
+        temp_dir_base=test_temp_dir_base
+    )
+    yield tool
+    tool.cleanup() # Ensure temp files for this tool instance are removed
+    # Optional: Clean up the base test_temp_dir if it's empty or after all tests
+    # if os.path.exists(test_temp_dir_base) and not os.listdir(test_temp_dir_base):
+    #     shutil.rmtree(test_temp_dir_base)
+
+# --- Test Cases ---
+
+def test_extract_video_id(video_tool):
+    assert video_tool._extract_video_id("https://www.youtube.com/watch?v=1htKBjuUWec") == "1htKBjuUWec"
+    assert video_tool._extract_video_id("https://youtu.be/1htKBjuUWec") == "1htKBjuUWec"
+    assert video_tool._extract_video_id("https://www.youtube.com/embed/1htKBjuUWec") == "1htKBjuUWec"
+    assert video_tool._extract_video_id("https://www.youtube.com/watch?v=1htKBjuUWec&t=10s") == "1htKBjuUWec"
+    assert video_tool._extract_video_id("invalid_url") is None
+
+@pytest.mark.integration # Marks as integration test (requires network)
+def test_download_video(video_tool):
+    result = video_tool.download_video(VIDEO_URL_SHORT_GENERAL, resolution="240p")
+    assert result.get("success"), f"Download failed: {result.get('error')}"
+    assert "file_path" in result
+    assert os.path.exists(result["file_path"])
+    assert result["file_path"].endswith(".mp4") or result["file_path"].startswith(video_tool._extract_video_id(VIDEO_URL_SHORT_GENERAL))
+
+@pytest.mark.integration
+def test_get_video_transcript_success(video_tool):
+    result = video_tool.get_video_transcript(VIDEO_URL_TRANSCRIPT_DIALOGUE)
+    assert result.get("success"), f"Transcript fetch failed: {result.get('error')}"
+    assert "transcript" in result and len(result["transcript"]) > 0
+    assert "transcript_entries" in result and len(result["transcript_entries"]) > 0
+    # Making the check case-insensitive and more flexible
+    assert "isn't that hot" in result["transcript"].lower() # Check for expected content (removed ?)
+
+@pytest.mark.integration
+def test_get_video_transcript_no_transcript(video_tool):
+    # This video is unlikely to have official transcripts in many languages
+    # However, YouTube might auto-generate. The API should handle it gracefully.
+    result = video_tool.get_video_transcript(VIDEO_URL_NO_TRANSCRIPT, languages=['xx-YY']) # Non-existent language
+    assert not result.get("success")
+    assert "error" in result
+    assert "No transcript found" in result["error"] or "Transcripts are disabled" in result["error"]
+
+@pytest.mark.integration
+def test_find_dialogue_response_success(video_tool):
+    transcript_data = video_tool.get_video_transcript(VIDEO_URL_TRANSCRIPT_DIALOGUE)
+    assert transcript_data.get("success"), f"Transcript fetch failed for dialogue test: {transcript_data.get('error')}"
+    
+    result = video_tool.find_dialogue_response(transcript_data["transcript_entries"], "Isn't that hot?")
+    assert result.get("success"), f"Dialogue search failed: {result.get('error')}"
+    assert "response_text" in result
+    # The expected response is "Extremely" but can vary slightly with transcript generation
+    assert "Extremely".lower() in result["response_text"].lower() 
+
+@pytest.mark.integration
+def test_find_dialogue_response_not_found(video_tool):
+    transcript_data = video_tool.get_video_transcript(VIDEO_URL_TRANSCRIPT_DIALOGUE)
+    assert transcript_data.get("success")
+    
+    result = video_tool.find_dialogue_response(transcript_data["transcript_entries"], "This phrase is not in the video")
+    assert not result.get("success")
+    assert "not found in transcript" in result.get("error", "")
+
+@pytest.mark.integration
+@pytest.mark.cv_dependent # Marks tests that rely on (even dummy) CV model setup
+def test_object_counting_interface(video_tool):
+    """Tests the object counting call, expecting it to run with dummy models even if counts are zero."""
+    if not video_tool.object_detection_model:
+        pytest.skip("CV model not loaded, skipping object count test.")
+
+    download_result = video_tool.download_video(VIDEO_URL_OBJECT_COUNT, resolution="240p") # Use a short video
+    assert download_result.get("success"), f"Video download failed for object counting: {download_result.get('error')}"
+    video_path = download_result["file_path"]
+
+    result = video_tool.count_objects_in_video(video_path, target_classes=["bird"], confidence_threshold=0.1, frame_skip=30)
+    
+    # With dummy models, we don't expect actual detections, but the function should complete.
+    assert result.get("success"), f"Object counting failed: {result.get('error')}"
+    assert "max_simultaneous_bird" in result # Even if it's 0
+    # If using real models and a video with birds, you would assert result["max_simultaneous_bird"] > 0
+
+@pytest.mark.integration
+@pytest.mark.cv_dependent
+def test_process_video_object_count_flow(video_tool):
+    if not video_tool.object_detection_model:
+        pytest.skip("CV model not loaded, skipping process_video object count test.")
+
+    query_params = {
+        "target_classes": ["bird"], 
+        "resolution": "240p", 
+        "confidence_threshold": 0.1,
+        "frame_skip": 30 # Process fewer frames for faster test
+    }
+    result = video_tool.process_video(VIDEO_URL_OBJECT_COUNT, "object_count", query_params=query_params)
+    assert result.get("success"), f"process_video for object_count failed: {result.get('error')}"
+    assert "max_simultaneous_bird" in result
+
+@pytest.mark.integration
+def test_process_video_dialogue_flow(video_tool):
+    query_params = {"query_phrase": "Isn't that hot?"}
+    result = video_tool.process_video(VIDEO_URL_TRANSCRIPT_DIALOGUE, "dialogue_response", query_params=query_params)
+    assert result.get("success"), f"process_video for dialogue_response failed: {result.get('error')}"
+    assert "extremely" in result.get("response_text", "").lower()
+
+@pytest.mark.integration
+def test_process_video_transcript_flow(video_tool):
+    result = video_tool.process_video(VIDEO_URL_TRANSCRIPT_DIALOGUE, "transcript")
+    assert result.get("success"), f"process_video for transcript failed: {result.get('error')}"
+    assert "transcript" in result and len(result["transcript"]) > 0
+
+def test_cleanup_removes_temp_dir(model_files): # Test cleanup more directly
+    test_temp_dir_base = os.path.join(os.path.dirname(__file__), "test_temp_cleanup")
+    os.makedirs(test_temp_dir_base, exist_ok=True)
+    tool = VideoProcessingTool(
+        model_cfg_path=model_files["cfg"],
+        model_weights_path=model_files["weights"],
+        class_names_path=model_files["names"],
+        temp_dir_base=test_temp_dir_base
+    )
+    # Create a dummy file in its temp dir
+    temp_file_in_tool_dir = os.path.join(tool.temp_dir, "dummy.txt")
+    open(temp_file_in_tool_dir, 'w').write("test")
+    assert os.path.exists(tool.temp_dir)
+    assert os.path.exists(temp_file_in_tool_dir)
+    
+    tool_temp_dir_path = tool.temp_dir # Store path before cleanup
+    tool.cleanup()
+    assert not os.path.exists(tool_temp_dir_path), f"Temp directory {tool_temp_dir_path} was not removed."
+    # shutil.rmtree(test_temp_dir_base, ignore_errors=True) # Clean up the base for this specific test
+
+# To run these tests:
+# 1. Ensure you have pytest installed (`pip install pytest`).
+# 2. Ensure required libraries for VideoProcessingTool are installed (yt_dlp, youtube_transcript_api, opencv-python).
+# 3. Navigate to the directory containing this test file and `src` directory.
+# 4. Run `pytest` or `python -m pytest` in your terminal.
+# 5. For tests requiring network (integration), ensure you have an internet connection.
+# 6. For CV dependent tests to be meaningful beyond interface checks, replace dummy model files with actual ones.