ultralytics 8.3.143__py3-none-any.whl → 8.3.144__py3-none-any.whl

ultralytics/solutions/config.py

@@ -16,20 +16,20 @@ class SolutionConfig:
     It leverages Python `dataclass` for clear, type-safe, and maintainable parameter definitions.
 
     Attributes:
-        source (Optional[str]): Path to the input source (video, RTSP, etc.). Only usable with Solutions CLI.
-        model (Optional[str]): Path to the Ultralytics YOLO model to be used for inference.
-        classes (Optional[List[int]]): List of class indices to filter detections.
+        source (str, optional): Path to the input source (video, RTSP, etc.). Only usable with Solutions CLI.
+        model (str, optional): Path to the Ultralytics YOLO model to be used for inference.
+        classes (List[int], optional): List of class indices to filter detections.
         show_conf (bool): Whether to show confidence scores on the visual output.
         show_labels (bool): Whether to display class labels on visual output.
-        region (Optional[List[Tuple[int, int]]]): Polygonal region or line for object counting.
-        colormap (Optional[int]): OpenCV colormap constant for visual overlays (e.g., cv2.COLORMAP_JET).
+        region (List[Tuple[int, int]], optional): Polygonal region or line for object counting.
+        colormap (int, optional): OpenCV colormap constant for visual overlays (e.g., cv2.COLORMAP_JET).
         show_in (bool): Whether to display count number for objects entering the region.
         show_out (bool): Whether to display count number for objects leaving the region.
         up_angle (float): Upper angle threshold used in pose-based workouts monitoring.
         down_angle (int): Lower angle threshold used in pose-based workouts monitoring.
         kpts (List[int]): Keypoint indices to monitor, e.g., for pose analytics.
         analytics_type (str): Type of analytics to perform ("line", "area", "bar", "pie", etc.).
-        figsize (Optional[Tuple[int, int]]): Size of the matplotlib figure used for analytical plots (width, height).
+        figsize (Tuple[int, int], optional): Size of the matplotlib figure used for analytical plots (width, height).
         blur_ratio (float): Ratio used to blur objects in the video frames (0.0 to 1.0).
         vision_point (Tuple[int, int]): Reference point for directional tracking or perspective drawing.
         crop_dir (str): Directory path to save cropped detection images.
@@ -43,7 +43,7 @@ class SolutionConfig:
         show (bool): Whether to display the visual output on screen.
         iou (float): Intersection-over-Union threshold for detection filtering.
         conf (float): Confidence threshold for keeping predictions.
-        device (Optional[str]): Device to run inference on (e.g., 'cpu', '0' for CUDA GPU).
+        device (str, optional): Device to run inference on (e.g., 'cpu', '0' for CUDA GPU).
         max_det (int): Maximum number of detections allowed per video frame.
         half (bool): Whether to use FP16 precision (requires a supported CUDA device).
         tracker (str): Path to tracking configuration YAML file (e.g., 'botsort.yaml').
@@ -100,7 +100,7 @@ class SolutionConfig:
             if hasattr(self, key):
                 setattr(self, key, value)
             else:
-                raise ValueError(
-                    f"❌ {key} is not a valid solution argument, available arguments here: https://docs.ultralytics.com/solutions/#solutions-arguments"
-                )
+                url = "https://docs.ultralytics.com/solutions/#solutions-arguments"
+                raise ValueError(f"{key} is not a valid solution argument, see {url}")
+
         return self

ultralytics/solutions/distance_calculation.py

@@ -1,6 +1,7 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
 import math
+from typing import Any, Dict, List
 
 import cv2
 
@@ -21,8 +22,8 @@ class DistanceCalculation(BaseSolution):
         centroids (List[List[int]]): List to store centroids of selected bounding boxes.
 
     Methods:
-        mouse_event_for_distance: Handles mouse events for selecting objects in the video stream.
-        process: Processes video frames and calculates the distance between selected objects.
+        mouse_event_for_distance: Handle mouse events for selecting objects in the video stream.
+        process: Process video frames and calculate the distance between selected objects.
 
     Examples:
         >>> distance_calc = DistanceCalculation()
@@ -32,18 +33,18 @@ class DistanceCalculation(BaseSolution):
         >>> cv2.waitKey(0)
     """
 
-    def __init__(self, **kwargs):
-        """Initializes the DistanceCalculation class for measuring object distances in video streams."""
+    def __init__(self, **kwargs: Any):
+        """Initialize the DistanceCalculation class for measuring object distances in video streams."""
         super().__init__(**kwargs)
 
         # Mouse event information
         self.left_mouse_count = 0
-        self.selected_boxes = {}
-        self.centroids = []  # Store centroids of selected objects
+        self.selected_boxes: Dict[int, List[float]] = {}
+        self.centroids: List[List[int]] = []  # Store centroids of selected objects
 
-    def mouse_event_for_distance(self, event, x, y, flags, param):
+    def mouse_event_for_distance(self, event: int, x: int, y: int, flags: int, param: Any) -> None:
         """
-        Handles mouse events to select regions in a real-time video stream for distance calculation.
+        Handle mouse events to select regions in a real-time video stream for distance calculation.
 
         Args:
             event (int): Type of mouse event (e.g., cv2.EVENT_MOUSEMOVE, cv2.EVENT_LBUTTONDOWN).
@@ -67,9 +68,9 @@ class DistanceCalculation(BaseSolution):
             self.selected_boxes = {}
             self.left_mouse_count = 0
 
-    def process(self, im0):
+    def process(self, im0) -> SolutionResults:
         """
-        Processes a video frame and calculates the distance between two selected bounding boxes.
+        Process a video frame and calculate the distance between two selected bounding boxes.
 
         This method extracts tracks from the input frame, annotates bounding boxes, and calculates the distance
         between two user-selected objects if they have been chosen.

ultralytics/solutions/heatmap.py

@@ -72,7 +72,7 @@ class Heatmap(ObjectCounter):
 
     def process(self, im0):
         """
-        Generate heatmap for each frame using Ultralytics.
+        Generate heatmap for each frame using Ultralytics tracking.
 
         Args:
             im0 (np.ndarray): Input image array for processing.

ultralytics/solutions/instance_segmentation.py

@@ -18,6 +18,9 @@ class InstanceSegmentation(BaseSolution):
         clss (List[int]): List of detected class indices.
         track_ids (List[int]): List of track IDs for detected instances.
         masks (List[numpy.ndarray]): List of segmentation masks for detected instances.
+        show_conf (bool): Whether to display confidence scores.
+        show_labels (bool): Whether to display class labels.
+        show_boxes (bool): Whether to display bounding boxes.
 
     Methods:
         process: Process the input image to perform instance segmentation and annotate results.
@@ -26,8 +29,8 @@ class InstanceSegmentation(BaseSolution):
     Examples:
         >>> segmenter = InstanceSegmentation()
         >>> frame = cv2.imread("frame.jpg")
-        >>> results = segmenter.segment(frame)
-        >>> print(f"Total segmented instances: {results['total_tracks']}")
+        >>> results = segmenter.process(frame)
+        >>> print(f"Total segmented instances: {results.total_tracks}")
     """
 
     def __init__(self, **kwargs):
@@ -58,7 +61,7 @@ class InstanceSegmentation(BaseSolution):
         Examples:
             >>> segmenter = InstanceSegmentation()
             >>> frame = cv2.imread("image.jpg")
-            >>> summary = segmenter.segment(frame)
+            >>> summary = segmenter.process(frame)
             >>> print(summary)
         """
         self.extract_tracks(im0)  # Extract tracks (bounding boxes, classes, and masks)

ultralytics/solutions/object_blurrer.py

@@ -20,9 +20,9 @@ class ObjectBlurrer(BaseSolution):
         conf (float): Confidence threshold for object detection.
 
     Methods:
-        process: Applies a blurring effect to detected objects in the input image.
-        extract_tracks: Extracts tracking information from detected objects.
-        display_output: Displays the processed output image.
+        process: Apply a blurring effect to detected objects in the input image.
+        extract_tracks: Extract tracking information from detected objects.
+        display_output: Display the processed output image.
 
     Examples:
         >>> blurrer = ObjectBlurrer()

ultralytics/solutions/object_counter.py

@@ -1,6 +1,7 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
 from collections import defaultdict
+from typing import Optional, Tuple
 
 from ultralytics.solutions.solutions import BaseSolution, SolutionAnnotator, SolutionResults
 from ultralytics.utils.plotting import colors
@@ -21,11 +22,12 @@ class ObjectCounter(BaseSolution):
         region_initialized (bool): Flag indicating whether the counting region has been initialized.
         show_in (bool): Flag to control display of inward count.
         show_out (bool): Flag to control display of outward count.
+        margin (int): Margin for background rectangle size to display counts properly.
 
     Methods:
-        count_objects: Counts objects within a polygonal or linear region.
-        display_counts: Displays object counts on the frame.
-        process: Processes input data (frames or object tracks) and updates counts.
+        count_objects: Count objects within a polygonal or linear region based on their tracks.
+        display_counts: Display object counts on the frame.
+        process: Process input data and update counts.
 
     Examples:
         >>> counter = ObjectCounter()
@@ -35,7 +37,7 @@ class ObjectCounter(BaseSolution):
     """
 
     def __init__(self, **kwargs):
-        """Initializes the ObjectCounter class for real-time object counting in video streams."""
+        """Initialize the ObjectCounter class for real-time object counting in video streams."""
         super().__init__(**kwargs)
 
         self.in_count = 0  # Counter for objects moving inward
@@ -48,14 +50,20 @@ class ObjectCounter(BaseSolution):
         self.show_out = self.CFG["show_out"]
         self.margin = self.line_width * 2  # Scales the background rectangle size to display counts properly
 
-    def count_objects(self, current_centroid, track_id, prev_position, cls):
+    def count_objects(
+        self,
+        current_centroid: Tuple[float, float],
+        track_id: int,
+        prev_position: Optional[Tuple[float, float]],
+        cls: int,
+    ):
         """
-        Counts objects within a polygonal or linear region based on their tracks.
+        Count objects within a polygonal or linear region based on their tracks.
 
         Args:
             current_centroid (Tuple[float, float]): Current centroid coordinates (x, y) in the current frame.
             track_id (int): Unique identifier for the tracked object.
-            prev_position (Tuple[float, float]): Last frame position coordinates (x, y) of the track.
+            prev_position (Tuple[float, float], optional): Last frame position coordinates (x, y) of the track.
             cls (int): Class index for classwise count updates.
 
         Examples:

ultralytics/solutions/object_cropper.py

@@ -21,7 +21,7 @@ class ObjectCropper(BaseSolution):
         conf (float): Confidence threshold for filtering detections.
 
     Methods:
-        process: Crops detected objects from the input image and saves them to the output directory.
+        process: Crop detected objects from the input image and save them to the output directory.
 
     Examples:
         >>> cropper = ObjectCropper()
@@ -59,7 +59,8 @@ class ObjectCropper(BaseSolution):
             im0 (numpy.ndarray): The input image containing detected objects.
 
         Returns:
-            (SolutionResults): A SolutionResults object containing the total number of cropped objects and processed image.
+            (SolutionResults): A SolutionResults object containing the total number of cropped objects and processed
+                image.
 
         Examples:
             >>> cropper = ObjectCropper()

ultralytics/solutions/parking_management.py

@@ -1,6 +1,7 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
 import json
+from typing import Any, List, Tuple
 
 import cv2
 import numpy as np
@@ -33,13 +34,13 @@ class ParkingPtsSelection:
         canvas_max_height (int): Maximum height of the canvas.
 
     Methods:
-        initialize_properties: Initializes the necessary properties.
-        upload_image: Uploads an image, resizes it to fit the canvas, and displays it.
-        on_canvas_click: Handles mouse clicks to add points for bounding boxes.
-        draw_box: Draws a bounding box on the canvas.
-        remove_last_bounding_box: Removes the last bounding box and redraws the canvas.
-        redraw_canvas: Redraws the canvas with the image and all bounding boxes.
-        save_to_json: Saves the bounding boxes to a JSON file.
+        initialize_properties: Initialize properties for image, canvas, bounding boxes, and dimensions.
+        upload_image: Upload and display an image on the canvas, resizing it to fit within specified dimensions.
+        on_canvas_click: Handle mouse clicks to add points for bounding boxes on the canvas.
+        draw_box: Draw a bounding box on the canvas using the provided coordinates.
+        remove_last_bounding_box: Remove the last bounding box from the list and redraw the canvas.
+        redraw_canvas: Redraw the canvas with the image and all bounding boxes.
+        save_to_json: Save the selected parking zone points to a JSON file with scaled coordinates.
 
     Examples:
         >>> parking_selector = ParkingPtsSelection()
@@ -48,7 +49,7 @@ class ParkingPtsSelection:
 
     def __init__(self):
         """Initialize the ParkingPtsSelection class, setting up UI and properties for parking zone point selection."""
-        try:  # check if tkinter installed
+        try:  # Check if tkinter is installed
             import tkinter as tk
             from tkinter import filedialog, messagebox
         except ImportError:  # Display error with recommendations
@@ -68,19 +69,19 @@ class ParkingPtsSelection:
             return
 
         self.tk, self.filedialog, self.messagebox = tk, filedialog, messagebox
-        self.master = self.tk.Tk()  # Reference to the main application window or parent widget
+        self.master = self.tk.Tk()  # Reference to the main application window
         self.master.title("Ultralytics Parking Zones Points Selector")
         self.master.resizable(False, False)
 
-        self.canvas = self.tk.Canvas(self.master, bg="white")  # Canvas widget for displaying images or graphics
+        self.canvas = self.tk.Canvas(self.master, bg="white")  # Canvas widget for displaying images
         self.canvas.pack(side=self.tk.BOTTOM)
 
         self.image = None  # Variable to store the loaded image
         self.canvas_image = None  # Reference to the image displayed on the canvas
         self.canvas_max_width = None  # Maximum allowed width for the canvas
         self.canvas_max_height = None  # Maximum allowed height for the canvas
-        self.rg_data = None  # Data related to region or annotation management
-        self.current_box = None  # Stores the currently selected or active bounding box
+        self.rg_data = None  # Data for region annotation management
+        self.current_box = None  # Stores the currently selected bounding box
         self.imgh = None  # Height of the current image
         self.imgw = None  # Width of the current image
 
@@ -107,7 +108,7 @@ class ParkingPtsSelection:
 
     def upload_image(self):
         """Upload and display an image on the canvas, resizing it to fit within specified dimensions."""
-        from PIL import Image, ImageTk  # scope because ImageTk requires tkinter package
+        from PIL import Image, ImageTk  # Scoped import because ImageTk requires tkinter package
 
         self.image = Image.open(self.filedialog.askopenfilename(filetypes=[("Image Files", "*.png *.jpg *.jpeg")]))
         if not self.image:
@@ -138,7 +139,7 @@ class ParkingPtsSelection:
             self.draw_box(self.current_box)
             self.current_box.clear()
 
-    def draw_box(self, box):
+    def draw_box(self, box: List[Tuple[int, int]]):
         """Draw a bounding box on the canvas using the provided coordinates."""
         for i in range(4):
             self.canvas.create_line(box[i], box[(i + 1) % 4], fill="blue", width=2)
@@ -163,7 +164,7 @@ class ParkingPtsSelection:
         scale_w, scale_h = self.imgw / self.canvas.winfo_width(), self.imgh / self.canvas.winfo_height()
         data = [{"points": [(int(x * scale_w), int(y * scale_h)) for x, y in box]} for box in self.rg_data]
 
-        from io import StringIO  # Function level import, as it's only required to store coordinates, not every frame
+        from io import StringIO  # Function level import, as it's only required to store coordinates
 
         write_buffer = StringIO()
         json.dump(data, write_buffer, indent=4)
@@ -188,7 +189,7 @@ class ParkingManagement(BaseSolution):
         dc (Tuple[int, int, int]): RGB color tuple for centroid visualization of detected objects.
 
     Methods:
-        process: Processes the input image for parking lot management and visualization.
+        process: Process the input image for parking lot management and visualization.
 
     Examples:
         >>> from ultralytics.solutions import ParkingManagement
@@ -197,7 +198,7 @@ class ParkingManagement(BaseSolution):
         >>> print(f"Available spaces: {parking_manager.pr_info['Available']}")
     """
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any):
         """Initialize the parking management system with a YOLO model and visualization settings."""
         super().__init__(**kwargs)
 
@@ -209,13 +210,13 @@ class ParkingManagement(BaseSolution):
         with open(self.json_file) as f:
             self.json = json.load(f)
 
-        self.pr_info = {"Occupancy": 0, "Available": 0}  # dictionary for parking information
+        self.pr_info = {"Occupancy": 0, "Available": 0}  # Dictionary for parking information
 
-        self.arc = (0, 0, 255)  # available region color
-        self.occ = (0, 255, 0)  # occupied region color
-        self.dc = (255, 0, 189)  # centroid color for each box
+        self.arc = (0, 0, 255)  # Available region color
+        self.occ = (0, 255, 0)  # Occupied region color
+        self.dc = (255, 0, 189)  # Centroid color for each box
 
-    def process(self, im0):
+    def process(self, im0: np.ndarray) -> SolutionResults:
         """
         Process the input image for parking lot management and visualization.
 
@@ -235,14 +236,14 @@ class ParkingManagement(BaseSolution):
             >>> image = cv2.imread("parking_lot.jpg")
             >>> results = parking_manager.process(image)
         """
-        self.extract_tracks(im0)  # extract tracks from im0
-        es, fs = len(self.json), 0  # empty slots, filled slots
-        annotator = SolutionAnnotator(im0, self.line_width)  # init annotator
+        self.extract_tracks(im0)  # Extract tracks from im0
+        es, fs = len(self.json), 0  # Empty slots, filled slots
+        annotator = SolutionAnnotator(im0, self.line_width)  # Initialize annotator
 
         for region in self.json:
             # Convert points to a NumPy array with the correct dtype and reshape properly
             pts_array = np.array(region["points"], dtype=np.int32).reshape((-1, 1, 2))
-            rg_occupied = False  # occupied region initialization
+            rg_occupied = False  # Occupied region initialization
             for box, cls in zip(self.boxes, self.clss):
                 xc, yc = int((box[0] + box[2]) / 2), int((box[1] + box[3]) / 2)
                 dist = cv2.pointPolygonTest(pts_array, (xc, yc), False)
@@ -254,7 +255,7 @@ class ParkingManagement(BaseSolution):
                     rg_occupied = True
                     break
             fs, es = (fs + 1, es - 1) if rg_occupied else (fs, es)
-            # Plotting regions
+            # Plot regions
             cv2.polylines(im0, [pts_array], isClosed=True, color=self.occ if rg_occupied else self.arc, thickness=2)
 
         self.pr_info["Occupancy"], self.pr_info["Available"] = fs, es
@@ -262,7 +263,7 @@ class ParkingManagement(BaseSolution):
         annotator.display_analytics(im0, self.pr_info, (104, 31, 17), (255, 255, 255), 10)
 
         plot_im = annotator.result()
-        self.display_output(plot_im)  # display output with base class function
+        self.display_output(plot_im)  # Display output with base class function
 
         # Return SolutionResults
         return SolutionResults(

ultralytics/solutions/queue_management.py

@@ -19,11 +19,11 @@ class QueueManager(BaseSolution):
         track_history (Dict[int, List[Tuple[int, int]]]): Dictionary storing tracking history for each object.
 
     Methods:
-        initialize_region: Initializes the queue region.
-        process: Processes a single frame for queue management.
-        extract_tracks: Extracts object tracks from the current frame.
-        store_tracking_history: Stores the tracking history for an object.
-        display_output: Displays the processed output.
+        initialize_region: Initialize the queue region.
+        process: Process a single frame for queue management.
+        extract_tracks: Extract object tracks from the current frame.
+        store_tracking_history: Store the tracking history for an object.
+        display_output: Display the processed output.
 
     Examples:
         >>> cap = cv2.VideoCapture("path/to/video.mp4")
@@ -36,7 +36,7 @@ class QueueManager(BaseSolution):
     """
 
     def __init__(self, **kwargs):
-        """Initializes the QueueManager with parameters for tracking and counting objects in a video stream."""
+        """Initialize the QueueManager with parameters for tracking and counting objects in a video stream."""
         super().__init__(**kwargs)
         self.initialize_region()
         self.counts = 0  # Queue counts information

ultralytics/solutions/region_counter.py

@@ -22,12 +22,19 @@ class RegionCounter(BaseSolution):
         region_counts (dict): Dictionary storing the count of objects for each named region.
 
     Methods:
-        add_region: Adds a new counting region with specified attributes.
-        process: Processes video frames to count objects in each region.
+        add_region: Add a new counting region with specified attributes.
+        process: Process video frames to count objects in each region.
+
+    Examples:
+        Initialize a RegionCounter and add a counting region
+        >>> counter = RegionCounter()
+        >>> counter.add_region("Zone1", [(100, 100), (200, 100), (200, 200), (100, 200)], (255, 0, 0), (255, 255, 255))
+        >>> results = counter.process(frame)
+        >>> print(f"Total tracks: {results.total_tracks}")
     """
 
     def __init__(self, **kwargs):
-        """Initializes the RegionCounter class for real-time counting in different regions of video streams."""
+        """Initialize the RegionCounter for real-time object counting in user-defined regions."""
         super().__init__(**kwargs)
         self.region_template = {
             "name": "Default Region",

ultralytics/solutions/security_alarm.py

@@ -46,7 +46,7 @@ class SecurityAlarm(BaseSolution):
         self.to_email = ""
         self.from_email = ""
 
-    def authenticate(self, from_email, password, to_email):
+    def authenticate(self, from_email: str, password: str, to_email: str):
         """
         Authenticate the email server for sending alert notifications.
 
@@ -69,13 +69,13 @@ class SecurityAlarm(BaseSolution):
         self.to_email = to_email
         self.from_email = from_email
 
-    def send_email(self, im0, records=5):
+    def send_email(self, im0, records: int = 5):
         """
         Send an email notification with an image attachment indicating the number of objects detected.
 
         Args:
             im0 (numpy.ndarray): The input image or frame to be attached to the email.
-            records (int): The number of detected objects to be included in the email message.
+            records (int, optional): The number of detected objects to be included in the email message.
 
         This method encodes the input image, composes the email message with details about the detection, and sends it
         to the specified recipient.

ultralytics/solutions/similarity_search.py

@@ -2,6 +2,7 @@
 
 import os
 from pathlib import Path
+from typing import List
 
 import numpy as np
 import torch
@@ -17,17 +18,38 @@ os.environ["KMP_DUPLICATE_LIB_OK"] = "TRUE"  # Avoid OpenMP conflict on some sys
 
 class VisualAISearch(BaseSolution):
     """
-    VisualAISearch leverages OpenCLIP to generate high-quality image and text embeddings, aligning them in a shared
-    semantic space. It then uses FAISS to perform fast and scalable similarity-based retrieval, allowing users to search
-    large collections of images using natural language queries with high accuracy and speed.
+    A semantic image search system that leverages OpenCLIP for generating high-quality image and text embeddings and
+    FAISS for fast similarity-based retrieval.
+
+    This class aligns image and text embeddings in a shared semantic space, enabling users to search large collections
+    of images using natural language queries with high accuracy and speed.
 
     Attributes:
         data (str): Directory containing images.
         device (str): Computation device, e.g., 'cpu' or 'cuda'.
+        faiss_index (str): Path to the FAISS index file.
+        data_path_npy (str): Path to the numpy file storing image paths.
+        model_name (str): Name of the CLIP model to use.
+        data_dir (Path): Path object for the data directory.
+        model: Loaded CLIP model.
+        preprocess: CLIP preprocessing function.
+        index: FAISS index for similarity search.
+        image_paths (List[str]): List of image file paths.
+
+    Methods:
+        extract_image_feature: Extract CLIP embedding from an image.
+        extract_text_feature: Extract CLIP embedding from text.
+        load_or_build_index: Load existing FAISS index or build new one.
+        search: Perform semantic search for similar images.
+
+    Examples:
+        Initialize and search for images
+        >>> searcher = VisualAISearch(data="path/to/images", device="cuda")
+        >>> results = searcher.search("a cat sitting on a chair", k=10)
     """
 
     def __init__(self, **kwargs):
-        """Initializes the VisualAISearch class with the FAISS index file and CLIP model."""
+        """Initialize the VisualAISearch class with FAISS index and CLIP model."""
         super().__init__(**kwargs)
         check_requirements(["git+https://github.com/ultralytics/CLIP.git", "faiss-cpu"])
 
@@ -55,21 +77,27 @@ class VisualAISearch(BaseSolution):
 
         self.load_or_build_index()
 
-    def extract_image_feature(self, path):
-        """Extract CLIP image embedding."""
+    def extract_image_feature(self, path: Path) -> np.ndarray:
+        """Extract CLIP image embedding from the given image path."""
         image = Image.open(path)
         tensor = self.preprocess(image).unsqueeze(0).to(self.device)
         with torch.no_grad():
             return self.model.encode_image(tensor).cpu().numpy()
 
-    def extract_text_feature(self, text):
-        """Extract CLIP text embedding."""
+    def extract_text_feature(self, text: str) -> np.ndarray:
+        """Extract CLIP text embedding from the given text query."""
         tokens = self.clip.tokenize([text]).to(self.device)
         with torch.no_grad():
             return self.model.encode_text(tokens).cpu().numpy()
 
     def load_or_build_index(self):
-        """Loads FAISS index or builds a new one from image features."""
+        """
+        Load existing FAISS index or build a new one from image features.
+
+        Checks if FAISS index and image paths exist on disk. If found, loads them directly. Otherwise, builds a new
+        index by extracting features from all images in the data directory, normalizes the features, and saves both the
+        index and image paths for future use.
+        """
         # Check if the FAISS index and corresponding image paths already exist
         if Path(self.faiss_index).exists() and Path(self.data_path_npy).exists():
             self.LOGGER.info("Loading existing FAISS index...")
@@ -107,8 +135,23 @@ class VisualAISearch(BaseSolution):
 
         self.LOGGER.info(f"Indexed {len(self.image_paths)} images.")
 
-    def search(self, query, k=30, similarity_thresh=0.1):
-        """Returns top-k semantically similar images to the given query."""
+    def search(self, query: str, k: int = 30, similarity_thresh: float = 0.1) -> List[str]:
+        """
+        Return top-k semantically similar images to the given query.
+
+        Args:
+            query (str): Natural language text query to search for.
+            k (int, optional): Maximum number of results to return.
+            similarity_thresh (float, optional): Minimum similarity threshold for filtering results.
+
+        Returns:
+            (List[str]): List of image filenames ranked by similarity score.
+
+        Examples:
+            Search for images matching a query
+            >>> searcher = VisualAISearch(data="images")
+            >>> results = searcher.search("red car", k=5, similarity_thresh=0.2)
+        """
         text_feat = self.extract_text_feature(query).astype("float32")
         self.faiss.normalize_L2(text_feat)
 
@@ -124,24 +167,42 @@ class VisualAISearch(BaseSolution):
 
         return [r[0] for r in results]
 
-    def __call__(self, query):
-        """Direct call for search function."""
+    def __call__(self, query: str) -> List[str]:
+        """Direct call interface for the search function."""
         return self.search(query)
 
 
 class SearchApp:
     """
-    A Flask-based web interface powers the semantic image search experience, enabling users to input natural language
-    queries and instantly view the most relevant images retrieved from the indexed database—all through a clean,
-    responsive, and easily customizable frontend.
+    A Flask-based web interface for semantic image search with natural language queries.
+
+    This class provides a clean, responsive frontend that enables users to input natural language queries and
+    instantly view the most relevant images retrieved from the indexed database.
 
-    Args:
-        data (str): Path to images to index and search.
-        device (str): Device to run inference on (e.g. 'cpu', 'cuda').
+    Attributes:
+        render_template: Flask template rendering function.
+        request: Flask request object.
+        searcher (VisualAISearch): Instance of the VisualAISearch class.
+        app (Flask): Flask application instance.
+
+    Methods:
+        index: Process user queries and display search results.
+        run: Start the Flask web application.
+
+    Examples:
+        Start a search application
+        >>> app = SearchApp(data="path/to/images", device="cuda")
+        >>> app.run(debug=True)
     """
 
-    def __init__(self, data="images", device=None):
-        """Initialization of the VisualAISearch class for performing semantic image search."""
+    def __init__(self, data: str = "images", device: str = None):
+        """
+        Initialize the SearchApp with VisualAISearch backend.
+
+        Args:
+            data (str, optional): Path to directory containing images to index and search.
+            device (str, optional): Device to run inference on (e.g. 'cpu', 'cuda').
+        """
         check_requirements("flask")
         from flask import Flask, render_template, request
 
@@ -157,13 +218,13 @@ class SearchApp:
         self.app.add_url_rule("/", view_func=self.index, methods=["GET", "POST"])
 
     def index(self):
-        """Function to process the user query and display output."""
+        """Process user query and display search results in the web interface."""
         results = []
         if self.request.method == "POST":
             query = self.request.form.get("query", "").strip()
             results = self.searcher(query)
         return self.render_template("similarity-search.html", results=results)
 
-    def run(self, debug=False):
-        """Runs the Flask web app."""
+    def run(self, debug: bool = False):
+        """Start the Flask web application server."""
         self.app.run(debug=debug)