matrice-inference 0.1.0__py3-none-manylinux_2_17_x86_64.whl

matrice_inference/deploy/optimize/frame_comparators.pyi

@@ -0,0 +1,203 @@
+"""Auto-generated stub for module: frame_comparators."""
+from typing import Any, Optional, Tuple
+
+from PIL import Image
+from imagehash import average_hash, phash, dhash
+from skimage.metrics import structural_similarity
+import cv2
+import logging
+import numpy as np
+
+# Classes
+class AbsDiffComparator(FrameComparator):
+    """
+    Compare frames using absolute difference.
+    """
+
+    def __init__(self: Any, threshold: float = 10.0) -> None: ...
+        """
+        Initialize with threshold for mean absolute difference.
+        
+                Args:
+                    threshold: Mean difference threshold (default: 10.0).
+        
+                Raises:
+                    ValueError: If threshold is negative.
+        """
+
+    def compare(self: Any, static_frame: Any, new_frame: Any, stream_key: Optional[str] = None) -> Tuple[bool, float]: ...
+        """
+        Compare frames using mean absolute difference.
+        
+                Args:
+                    static_frame: Reference frame (RGB, cv2 image as np.ndarray).
+                    new_frame: New frame to compare (RGB, cv2 image as np.ndarray).
+                    stream_key: Optional identifier for the video stream (e.g., camera ID).
+        
+                Returns:
+                    Tuple[bool, float]: (is_similar, mean_difference)
+        """
+
+class AverageHashComparator(FrameComparator):
+    """
+    Compares frames using average hashing (aHash).
+    """
+
+    def __init__(self: Any, threshold: int = 5) -> None: ...
+        """
+        Initialize with threshold for hash difference.
+        
+                Args:
+                    threshold: Hash difference threshold (default: 5).
+        
+                Raises:
+                    ValueError: If threshold is negative.
+        """
+
+    def compare(self: Any, static_frame: Any, new_frame: Any, stream_key: Optional[str] = None) -> Tuple[bool, float]: ...
+        """
+        Compare frames using average hash difference.
+        
+                Args:
+                    static_frame: Reference frame (RGB, cv2 image as np.ndarray).
+                    new_frame: New frame to compare (RGB, cv2 image as np.ndarray).
+                    stream_key: Optional identifier for the video stream (e.g., camera ID).
+        
+                Returns:
+                    Tuple[bool, float]: (is_similar, hash_difference)
+        """
+
+class DifferenceHashComparator(FrameComparator):
+    """
+    Compares frames using difference hashing (dHash).
+    """
+
+    def __init__(self: Any, threshold: int = 5) -> None: ...
+        """
+        Initialize with threshold for hash difference.
+        
+                Args:
+                    threshold: Hash difference threshold (default: 5).
+        
+                Raises:
+                    ValueError: If threshold is negative.
+        """
+
+    def compare(self: Any, static_frame: Any, new_frame: Any, stream_key: Optional[str] = None) -> Tuple[bool, float]: ...
+        """
+        Compare frames using difference hash difference.
+        
+                Args:
+                    static_frame: Reference frame (RGB, cv2 image as np.ndarray).
+                    new_frame: New frame to compare (RGB, cv2 image as np.ndarray).
+                    stream_key: Optional identifier for the video stream (e.g., camera ID).
+        
+                Returns:
+                    Tuple[bool, float]: (is_similar, hash_difference)
+        """
+
+class FrameComparator:
+    """
+    Base class for frame comparison methods.
+    """
+
+    def compare(self: Any, static_frame: Any, new_frame: Any, stream_key: Optional[str] = None) -> Tuple[bool, float]: ...
+        """
+        Compare frames and determine if they are similar.
+        
+                Args:
+                    static_frame: Reference frame (RGB, cv2 image as np.ndarray).
+                    new_frame: New frame to compare (RGB, cv2 image as np.ndarray).
+                    stream_key: Optional identifier for the video stream (e.g., camera ID).
+        
+                Returns:
+                    Tuple[bool, float]: (is_similar, similarity_score)
+        """
+
+class HistogramComparator(FrameComparator):
+    """
+    Compare frames using histogram correlation.
+    """
+
+    def __init__(self: Any, threshold: float = 0.9) -> None: ...
+        """
+        Initialize with threshold for histogram correlation.
+        
+                Args:
+                    threshold: Correlation score threshold (default: 0.9).
+        
+                Raises:
+                    ValueError: If threshold is not in [0, 1].
+        """
+
+    def compare(self: Any, static_frame: Any, new_frame: Any, stream_key: Optional[str] = None) -> Tuple[bool, float]: ...
+        """
+        Compare frames using histogram correlation.
+        
+                Args:
+                    static_frame: Reference frame (RGB, cv2 image as np.ndarray).
+                    new_frame: New frame to compare (RGB, cv2 image as np.ndarray).
+                    stream_key: Optional identifier for the video stream (e.g., camera ID).
+        
+                Returns:
+                    Tuple[bool, float]: (is_similar, correlation_score)
+        """
+
+class PerceptualHashComparator(FrameComparator):
+    """
+    Compares frames using perceptual hashing (pHash).
+    """
+
+    def __init__(self: Any, threshold: int = 6) -> None: ...
+        """
+        Initialize with threshold for hash difference.
+        
+                Args:
+                    threshold: Hash difference threshold (default: 6).
+        
+                Raises:
+                    ValueError: If threshold is negative.
+        """
+
+    def compare(self: Any, static_frame: Any, new_frame: Any, stream_key: Optional[str] = None) -> Tuple[bool, float]: ...
+        """
+        Compare frames using perceptual hash difference.
+        
+                Args:
+                    static_frame: Reference frame (RGB, cv2 image as np.ndarray).
+                    new_frame: New frame to compare (RGB, cv2 image as np.ndarray).
+                    stream_key: Optional identifier for the video stream (e.g., camera ID).
+        
+                Returns:
+                    Tuple[bool, float]: (is_similar, hash_difference)
+        """
+
+class SSIMComparator(FrameComparator):
+    """
+    Compare frames using Structural Similarity Index (SSIM).
+    """
+
+    def __init__(self: Any, threshold: float = 0.9) -> None: ...
+        """
+        Initialize with threshold for SSIM score.
+        
+                Args:
+                    threshold: SSIM score threshold (default: 0.9).
+        
+                Raises:
+                    ValueError: If threshold is not in [0, 1].
+        """
+
+    def compare(self: Any, static_frame: Any, new_frame: Any, stream_key: Optional[str] = None) -> Tuple[bool, float]: ...
+        """
+        Compare frames using SSIM.
+        
+                Args:
+                    static_frame: Reference frame (RGB, cv2 image as np.ndarray).
+                    new_frame: New frame to compare (RGB, cv2 image as np.ndarray).
+                    stream_key: Optional identifier for the video stream (e.g., camera ID).
+        
+                Returns:
+                    Tuple[bool, float]: (is_similar, ssim_score)
+        """
+

matrice_inference/deploy/optimize/frame_difference.pyi

@@ -0,0 +1,165 @@
+"""Auto-generated stub for module: frame_difference."""
+from typing import Any, Dict, Optional, Tuple, Union
+
+from PIL import Image
+import base64
+import cv2
+import logging
+import numpy as np
+
+# Constants
+logger: Any
+
+# Classes
+class FrameDifferenceProcessor:
+    """
+    Handles frame difference calculation and reconstruction for intelligent caching.
+    """
+
+    def __init__(self: Any) -> None: ...
+        """
+        Initialize frame difference processor.
+        """
+
+    def calculate_frame_difference(self: Any, reference_frame: Any, current_frame: Any) -> Tuple[np.ndarray, Dict[str, Any]]: ...
+        """
+        Calculate difference between reference and current frame.
+        
+                Args:
+                    reference_frame: Reference frame (RGB, cv2 image as np.ndarray)
+                    current_frame: Current frame to compare (RGB, cv2 image as np.ndarray)
+        
+                Returns:
+                    Tuple of (difference_data, metadata)
+        """
+
+    def decode_base64_to_frame(self: Any, encoded_frame: str) -> Optional[np.ndarray]: ...
+        """
+        Decode base64 string to frame.
+        
+                Args:
+                    encoded_frame: Base64 encoded frame
+        
+                Returns:
+                    Decoded frame as numpy array or None if failed
+        """
+
+    def decode_frame_difference(self: Any, encoded_diff: str) -> Optional[np.ndarray]: ...
+        """
+        Decode base64 frame difference data.
+        
+                Args:
+                    encoded_diff: Base64 encoded difference data
+        
+                Returns:
+                    Decoded difference as numpy array or None if failed
+        """
+
+    def encode_frame_difference(self: Any, difference_data: Any, metadata: Dict[str, Any], compression_quality: int = 85) -> str: ...
+        """
+        Encode frame difference data to base64.
+        
+                Args:
+                    difference_data: Frame difference as numpy array
+                    metadata: Difference metadata
+                    compression_quality: JPEG compression quality (1-100)
+        
+                Returns:
+                    Base64 encoded difference data
+        """
+
+    def encode_frame_to_base64(self: Any, frame: Any, quality: int = 95) -> str: ...
+        """
+        Encode frame to base64 string.
+        
+                Args:
+                    frame: Frame as numpy array
+                    quality: JPEG quality (1-100)
+        
+                Returns:
+                    Base64 encoded frame
+        """
+
+    def reconstruct_frame(self: Any, reference_frame: Any, difference_data: Any, metadata: Dict[str, Any]) -> Optional[np.ndarray]: ...
+        """
+        Reconstruct frame from reference frame and difference data.
+        
+                Args:
+                    reference_frame: Reference frame (RGB, cv2 image as np.ndarray)
+                    difference_data: Frame difference data
+                    metadata: Difference metadata
+        
+                Returns:
+                    Reconstructed frame or None if failed
+        """
+
+class IntelligentFrameCache:
+    """
+    Intelligent frame cache with two-threshold logic.
+    """
+
+    def __init__(self: Any, threshold_a: float = 0.95, threshold_b: float = 0.85, max_cache_size: int = 50) -> None: ...
+        """
+        Initialize intelligent frame cache.
+        
+                Args:
+                    threshold_a: High similarity threshold for cache reuse
+                    threshold_b: Medium similarity threshold for difference-based reconstruction
+                    max_cache_size: Maximum number of cached frames per stream
+        """
+
+    def cache_frame_result(self: Any, stream_key: str, frame: Any, model_result: Any, input_hash: Optional[str] = None) -> None: ...
+        """
+        Cache frame and its model result.
+        
+                Args:
+                    stream_key: Stream identifier
+                    frame: Frame that was processed
+                    model_result: Result from model inference
+                    input_hash: Optional input hash for additional indexing
+        """
+
+    def clear_cache(self: Any, stream_key: Optional[str] = None) -> None: ...
+        """
+        Clear cache for specific stream or all streams.
+        
+                Args:
+                    stream_key: Stream to clear, or None to clear all
+        """
+
+    def get_cache_stats(self: Any) -> Dict[str, Any]: ...
+        """
+        Get cache statistics.
+        
+                Returns:
+                    Dictionary with cache statistics
+        """
+
+    def get_cached_result(self: Any, stream_key: str, action_data: Dict[str, Any]) -> Any: ...
+        """
+        Get cached result based on action data.
+        
+                Args:
+                    stream_key: Stream identifier
+                    action_data: Data from should_use_cache decision
+        
+                Returns:
+                    Cached model result or None
+        """
+
+    def should_use_cache(self: Any, current_frame: Any, stream_key: str, ssim_comparator: Any) -> Tuple[str, Dict[str, Any]]: ...
+        """
+        Determine caching strategy based on frame similarity.
+        
+                Args:
+                    current_frame: Current frame to analyze
+                    stream_key: Stream identifier
+                    ssim_comparator: SSIM comparator for similarity calculation
+        
+                Returns:
+                    Tuple of (action, data) where action is:
+                    - "use_cache": Use cached result (Threshold A)
+                    - "use_difference": Use difference-based reconstruction (Threshold B)
+                    - "process_new": Process as new frame (exceeds both thresholds)
+        """
+

matrice_inference/deploy/optimize/transmission.pyi

@@ -0,0 +1,97 @@
+"""Auto-generated stub for module: transmission."""
+from typing import Any, Dict, Optional, Tuple
+
+from datetime import datetime, timezone
+from frame_comparators import SSIMComparator
+from frame_difference import FrameDifferenceProcessor
+import base64
+import cv2
+import hashlib
+import logging
+import numpy as np
+
+# Constants
+logger: Any
+
+# Classes
+class ClientTransmissionHandler:
+    """
+    Client-side transmission handler implementing two-threshold logic.
+    
+        Responsibilities:
+        - Maintain last frame per stream for SSIM reference
+        - Decide strategy: full, difference, or skip
+        - Produce difference payload (base64-encoded JPEG) and metadata
+        - Track last full-frame input hash for server cache linking
+    """
+
+    def __init__(self: Any, threshold_a: float = 0.95, threshold_b: float = 0.85) -> None: ...
+
+    def compute_and_store_full_frame_hash(self: Any, stream_key: str, full_jpeg_bytes: Any) -> str: ...
+        """
+        Compute deterministic MD5 (non-security) and store it for reference.
+        """
+
+    def decide_transmission(self: Any, frame: Any, stream_key: str) -> Tuple[str, Dict[str, Any]]: ...
+        """
+        Determine transmission strategy for a frame.
+        
+                Returns: (strategy, data)
+                  strategy in {"full", "difference", "skip"}
+                  data contains similarity and optional diff payload metadata
+        """
+
+    def encode_difference(self: Any, difference_data: Any, difference_metadata: Dict[str, Any], quality: int) -> Any: ...
+        """
+        Encode difference np.ndarray to raw bytes suitable for transport.
+        """
+
+    def prepare_transmission(self: Any, frame: Any) -> Tuple[bytes, Dict[str, Any], str]: ...
+        """
+        Prepare bytes payload and metadata for transport.
+        
+                Returns (input_bytes, metadata, strategy)
+        """
+
+class ServerTransmissionHandler:
+    """
+    Server-side transmission handler for intelligent input handling.
+    
+        Responsibilities:
+        - Interpret transmission_strategy from client (skip/difference/full)
+        - Resolve cache hits for skip signals
+        - Reconstruct frames for difference payloads
+        - Perform SSIM similarity checks for optional skipping
+    """
+
+    def __init__(self: Any, ssim_threshold: float = 0.95) -> None: ...
+
+    def decide_action(self: Any, message: Dict[str, Any], cache_manager: Any, frame_cache: Dict[str, np.ndarray]) -> Tuple[str, Optional[Dict[str, Any]]]: ...
+        """
+        Decide how to handle an incoming message.
+        
+                Returns (action, payload):
+                  - ("cached", cached_result)
+                  - ("similar", None)
+                  - ("process_difference", None) -> call reconstruct() then process
+                  - ("process", None)
+        """
+
+    def process_input_message(self: Any, raw_message_value: Dict[str, Any], message_key: Optional[str], consumer_worker_id: str) -> Dict[str, Any]: ...
+        """
+        Normalize raw Kafka message 'value' into a processed message structure.
+        
+                Handles transmission_strategy: 'skip', 'difference', 'full'.
+                Decodes content accordingly and carries through strategy metadata.
+        """
+
+    def reconstruct_from_difference(self: Any, message: Dict[str, Any], frame_cache: Dict[str, np.ndarray]) -> Tuple[Optional[bytes], Optional[str]]: ...
+        """
+        Reconstruct full frame from difference; returns (jpeg_bytes, effective_hash).
+        """
+
+    def update_frame_cache_from_message(self: Any, message: Dict[str, Any], frame_cache: Dict[str, np.ndarray]) -> None: ...
+        """
+        If message has image bytes, decode and store for SSIM reference.
+        """
+

matrice_inference/deploy/server/inference/batch_manager.pyi

@@ -0,0 +1,50 @@
+"""Auto-generated stub for module: batch_manager."""
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from dataclasses import dataclass, field
+from matrice_inference.deploy.utils.post_processing.core.config import BaseConfig
+import asyncio
+import logging
+import time
+
+# Classes
+class BatchRequest:
+    """
+    Represents a single inference request in a batch
+    """
+
+    pass
+class DynamicBatchManager:
+    """
+    Manages dynamic batching for inference requests
+    """
+
+    def __init__(self: Any, batch_size: int, max_batch_wait_time: float, model_manager: Any, post_processing_fn: Any) -> None: ...
+        """
+        Initialize the dynamic batch manager.
+        
+        Args:
+            batch_size: Maximum batch size for processing
+            max_batch_wait_time: Maximum wait time for batching
+            model_manager: Model manager for inference
+            post_processing_fn: Function to apply post-processing
+        """
+
+    async def add_request(self: Any, batch_request: Any) -> Tuple[Any, Optional[Dict[str, Any]]]: ...
+        """
+        Add a request to the batch queue and process if needed
+        """
+
+    async def flush_queue(self: Any) -> int: ...
+        """
+        Force process all remaining items in the batch queue.
+        
+                Returns:
+                    Number of items processed
+        """
+
+    def get_stats(self: Any) -> Dict[str, Any]: ...
+        """
+        Get statistics about the current batching state.
+        """
+

matrice_inference/deploy/server/inference/inference_interface.pyi

@@ -0,0 +1,114 @@
+"""Auto-generated stub for module: inference_interface."""
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from datetime import datetime, timezone
+from matrice.action_tracker import ActionTracker
+from matrice_inference.deploy.optimize.cache_manager import CacheManager
+from matrice_inference.deploy.optimize.frame_comparators import SSIMComparator
+from matrice_inference.deploy.optimize.frame_difference import IntelligentFrameCache
+from matrice_inference.deploy.server.inference.batch_manager import DynamicBatchManager, BatchRequest
+from matrice_inference.deploy.server.inference.model_manager import ModelManager
+from matrice_inference.deploy.utils.post_processing import PostProcessor, create_config_from_template
+from matrice_inference.deploy.utils.post_processing.config import get_usecase_from_app_name, get_category_from_app_name
+from matrice_inference.deploy.utils.post_processing.core.config import BaseConfig
+import base64
+import cv2
+import logging
+import numpy as np
+
+# Classes
+class InferenceInterface:
+    """
+    Interface for proxying requests to model servers with optional post-processing.
+    """
+
+    def __init__(self: Any, action_tracker: Any, model_manager: Any, batch_size: int = 1, dynamic_batching: bool = False, post_processing_config: Optional[Union[Dict[str, Any], BaseConfig, str]] = None, custom_post_processing_fn: Optional[Callable] = None, max_batch_wait_time: float = 0.05, app_name: str = '') -> None: ...
+        """
+        Initialize the inference interface.
+        
+        Args:
+            action_tracker: Action tracker for category mapping
+            model_manager: Model manager for inference
+            batch_size: Batch size for processing
+            dynamic_batching: Whether to enable dynamic batching
+            post_processing_config: Default post-processing configuration
+                Can be a dict, BaseConfig object, or use case name string
+            custom_post_processing_fn: Custom post-processing function
+            max_batch_wait_time: Maximum wait time for batching
+            app_name: Application name for automatic config loading
+        """
+
+    async def batch_inference(self: Any, batch_input1: List[Any], batch_input2: Optional[List[Any]] = None, batch_extra_params: Optional[List[Dict[str, Any]]] = None, apply_post_processing: bool = False, post_processing_configs: Optional[List[Union[Dict[str, Any], BaseConfig, str]]] = None, stream_key: Optional[str] = None, stream_info: Optional[Dict[str, Any]] = None, input_hash: Optional[str] = None, camera_info: Optional[Dict[str, Any]] = None) -> List[Tuple[Any, Optional[Dict[str, Any]]]]: ...
+        """
+        Perform batch inference directly without dynamic batching.
+        
+                Args:
+                    batch_input1: List of primary input data
+                    batch_input2: List of secondary input data (optional)
+                    batch_extra_params: List of additional parameters for each inference (optional)
+                    apply_post_processing: Whether to apply post-processing
+                    post_processing_configs: List of post-processing configurations for each input
+                    stream_key: Stream key for the inference
+                    stream_info: Stream info for the inference (optional)
+                Returns:
+                    List of tuples containing (inference_result, post_processing_result) for each input.
+        
+                Raises:
+                    ValueError: If input data is invalid
+                    RuntimeError: If inference fails
+        """
+
+    def clear_post_processing_cache(self: Any) -> None: ...
+        """
+        Clear the post-processing cache in the underlying processor.
+        """
+
+    async def flush_batch_queue(self: Any) -> int: ...
+        """
+        Force process all remaining items in the batch queue.
+        
+                Returns:
+                    Number of items processed
+        """
+
+    def get_batch_stats(self: Any) -> Dict[str, Any]: ...
+        """
+        Get statistics about the current batching state.
+        """
+
+    def get_latest_inference_time(self: Any) -> Any: ...
+        """
+        Get the latest inference time.
+        """
+
+    def get_post_processing_cache_stats(self: Any) -> Dict[str, Any]: ...
+        """
+        Get post-processing cache statistics from the underlying processor.
+        
+                Returns:
+                    Dict[str, Any]: Cache statistics including cached instances and keys
+        """
+
+    async def inference(self: Any, input1: Any, input2: Any = None, extra_params: Any = None, apply_post_processing: bool = False, post_processing_config: Optional[Union[Dict[str, Any], BaseConfig, str]] = None, stream_key: Optional[str] = None, stream_info: Optional[Dict[str, Any]] = None, input_hash: Optional[str] = None, camera_info: Optional[Dict[str, Any]] = None) -> Tuple[Any, Optional[Dict[str, Any]]]: ...
+        """
+        Perform inference using the appropriate client with optional post-processing.
+        
+                Args:
+                    input1: Primary input data
+                    input2: Secondary input data (optional)
+                    extra_params: Additional parameters for inference (optional)
+                    apply_post_processing: Whether to apply post-processing
+                    post_processing_config: Post-processing configuration (overrides default)
+                    stream_key: Stream key for the inference
+                    stream_info: Stream info for the inference (optional)
+                    input_hash: Input hash for the inference
+                Returns:
+                    Tuple containing (inference_result, post_processing_result).
+                    If post-processing is not applied, post_processing_result will be None.
+                    If post-processing is applied, post_processing_result contains the full post-processing metadata.
+        
+                Raises:
+                    ValueError: If client is not set up
+                    RuntimeError: If inference fails
+        """
+