matrice-analytics 0.1.51__tar.gz → 0.1.52__tar.gz

{matrice_analytics-0.1.51 → matrice_analytics-0.1.52}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrice_analytics
-Version: 0.1.51
+Version: 0.1.52
 Summary: Common server utilities for Matrice.ai services
 Author-email: "Matrice.ai" <dipendra@matrice.ai>
 License-Expression: MIT

{matrice_analytics-0.1.51 → matrice_analytics-0.1.52}/matrice_analytics.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrice_analytics
-Version: 0.1.51
+Version: 0.1.52
 Summary: Common server utilities for Matrice.ai services
 Author-email: "Matrice.ai" <dipendra@matrice.ai>
 License-Expression: MIT

{matrice_analytics-0.1.51 → matrice_analytics-0.1.52}/src/matrice_analytics/post_processing/face_reg/embedding_manager.py

@@ -49,7 +49,10 @@ class EmbeddingConfig:
     
     # Background embedding refresh settings
     enable_background_refresh: bool = True
-    background_refresh_interval: int = 600  # Refresh embeddings every 10 minutes (600 seconds)
+    # Refresh embeddings every 12 hours by default
+    background_refresh_interval: int = 43200
+    # TTL for cached staff embeddings (controls on-demand refresh checks)
+    staff_embeddings_cache_ttl: int = 43200
 
 
 class EmbeddingManager:
@@ -67,7 +70,8 @@ class EmbeddingManager:
         # Staff embeddings cache for local similarity search
         self.staff_embeddings: List[StaffEmbedding] = []
         self.staff_embeddings_last_update = 0
-        self.staff_embeddings_cache_ttl = 3600  # 1 hour
+        # Use configured TTL (default: 12 hours)
+        self.staff_embeddings_cache_ttl = int(self.config.staff_embeddings_cache_ttl)
         
         # Numpy arrays for fast similarity computation
         self.embeddings_matrix = None

{matrice_analytics-0.1.51 → matrice_analytics-0.1.52}/src/matrice_analytics/post_processing/face_reg/face_recognition.py

@@ -1,18 +1,27 @@
 """
-Face Recognition with Track ID Cache Optimization
+Face Recognition with Local Embedding Search Optimization
 
-This module includes an optimization that caches face recognition results by track ID
-to reduce redundant API calls. When a face detection is processed:
+This module uses local similarity search for face recognition to achieve high performance:
 
-1. It checks the cache for existing results using track_id
-2. If track_id found in cache, uses cached result instead of API call
-3. If track_id not found, makes API call and caches the result
-4. Cache includes automatic cleanup with TTL and size limits
+Performance Optimization Strategy:
+1. EmbeddingManager loads all staff embeddings from API at startup (~1 API call)
+2. Embeddings are cached in memory as a normalized numpy matrix
+3. Face recognition uses fast local cosine similarity search (~1-5ms per face)
+4. API calls are avoided during normal operation (2000x speedup vs API calls)
+5. Background refresh updates embeddings periodically (configurable TTL)
+
+Processing Flow:
+1. TemporalIdentityManager receives face embedding from detection
+2. Uses EmbeddingManager._find_best_local_match() for fast local similarity search
+3. Returns best match if similarity >= threshold, otherwise returns "Unknown"
+4. Only falls back to API if EmbeddingManager unavailable (rare)
 
 Configuration options:
-- enable_track_id_cache: Enable/disable the optimization
-- cache_max_size: Maximum number of cached track IDs (default: 1000)
+- enable_track_id_cache: Enable/disable track-level caching
+- cache_max_size: Maximum number of cached track IDs (default: 3000)
 - cache_ttl: Cache time-to-live in seconds (default: 3600)
+ - background_refresh_interval: Embedding refresh interval (default: 43200s = 12h)
+- similarity_threshold: Minimum similarity for recognition (default: 0.45)
 """
 import subprocess
 import logging
@@ -81,13 +90,14 @@ class TemporalIdentityManager:
     """
     Maintains stable identity labels per tracker ID using temporal smoothing and embedding history.
 
-    Adaptation for production: _compute_best_identity queries the face recognition API
-    via search_similar_faces(embedding, threshold=0.01, limit=1) to obtain top-1 match and score.
+    Adaptation for production: _compute_best_identity uses EmbeddingManager for local similarity
+    search first (fast), then falls back to API only if needed (slow).
     """
 
     def __init__(
         self,
         face_client: FacialRecognitionClient,
+        embedding_manager = None,
         recognition_threshold: float = 0.35,
         history_size: int = 20,
         unknown_patience: int = 7,
@@ -96,6 +106,7 @@ class TemporalIdentityManager:
     ) -> None:
         self.logger = logging.getLogger(__name__)
         self.face_client = face_client
+        self.embedding_manager = embedding_manager
         self.threshold = float(recognition_threshold)
         self.history_size = int(history_size)
         self.unknown_patience = int(unknown_patience)
@@ -119,14 +130,70 @@ class TemporalIdentityManager:
 
     async def _compute_best_identity(self, emb: List[float], location: str = "", timestamp: str = "") -> Tuple[Optional[str], str, float, Optional[str], Dict[str, Any], str]:
         """
-        Query backend for top-1 match for the given embedding.
+        Find best identity match using local similarity search (fast) with optional API fallback.
         Returns (staff_id, person_name, score, employee_id, staff_details, detection_type).
-        Robust to varying response shapes.
+        
+        Performance optimization: Uses EmbeddingManager for local similarity search to avoid
+        slow API calls (~2000ms). Only falls back to API if local search is unavailable.
         """
         if not emb or not isinstance(emb, list):
             return None, "Unknown", 0.0, None, {}, "unknown"
+        
+        st10 = time.time()
+        
+        # PRIMARY PATH: Local similarity search using EmbeddingManager (FAST - ~1-5ms)
+        if self.embedding_manager:
+            try:
+                local_match = self.embedding_manager._find_best_local_match(emb)
+                
+                if local_match:
+                    staff_embedding, similarity_score = local_match
+                    
+                    # Extract person name from staff details
+                    person_name = "Unknown"
+                    staff_details = staff_embedding.staff_details if isinstance(staff_embedding.staff_details, dict) else {}
+                    
+                    if staff_details:
+                        first_name = staff_details.get("firstName")
+                        last_name = staff_details.get("lastName")
+                        name = staff_details.get("name")
+                        if name:
+                            person_name = str(name)
+                        elif first_name or last_name:
+                            person_name = f"{first_name or ''} {last_name or ''}".strip() or "Unknown"
+                    
+                    print("------------------FACE RECOG TEMPORAL IDENTITY MANAGER UPDATE - COMPUTE BEST IDENTITY (LOCAL)----------------------------")
+                    print("LATENCY:",(time.time() - st10)*1000,"| Throughput fps:",(1.0 / (time.time() - st10)) if (time.time() - st10) > 0 else None)
+                    print(f"LOCAL MATCH: staff_id={staff_embedding.staff_id}, similarity={similarity_score:.3f}")
+                    print("------------------FACE RECOG TEMPORAL IDENTITY MANAGER UPDATE - COMPUTE BEST IDENTITY (LOCAL)----------------------------")
+                    
+                    self.logger.info(f"Local embedding match - staff_id={staff_embedding.staff_id}, person_name={person_name}, score={similarity_score:.3f}")
+                    
+                    return (
+                        str(staff_embedding.staff_id),
+                        person_name,
+                        float(similarity_score),
+                        str(staff_embedding.employee_id),
+                        staff_details,
+                        "known"
+                    )
+                else:
+                    # No local match found
+                    self.logger.debug("No local match found - returning unknown")
+                    print("------------------FACE RECOG TEMPORAL IDENTITY MANAGER UPDATE - COMPUTE BEST IDENTITY (LOCAL - NO MATCH)----------------------------")
+                    print("LATENCY:",(time.time() - st10)*1000,"| Throughput fps:",(1.0 / (time.time() - st10)) if (time.time() - st10) > 0 else None)
+                    print("------------------FACE RECOG TEMPORAL IDENTITY MANAGER UPDATE - COMPUTE BEST IDENTITY (LOCAL - NO MATCH)----------------------------")
+                    
+                    return None, "Unknown", 0.0, None, {}, "unknown"
+                    
+            except Exception as e:
+                self.logger.warning(f"Local similarity search failed, falling back to API: {e}")
+                # Fall through to API call below
+        
+        # FALLBACK PATH: API call (SLOW - ~2000ms) - only if embedding manager not available
+        # This path should rarely be used in production
         try:
-            st10=time.time()
+            self.logger.warning("Using slow API fallback for identity search - consider checking embedding manager initialization")
             resp = await self.face_client.search_similar_faces(
                 face_embedding=emb,
                 threshold=0.01,  # low threshold to always get top-1
@@ -135,9 +202,10 @@ class TemporalIdentityManager:
                 location=location,
                 timestamp=timestamp,
             )
-            print("------------------FACE RECOG TEMPORAL IDENTITY MANAGER UPDATE - COMPUTE BEST IDENTITY_0G----------------------------")
+            print("------------------FACE RECOG TEMPORAL IDENTITY MANAGER UPDATE - COMPUTE BEST IDENTITY (API FALLBACK)----------------------------")
             print("LATENCY:",(time.time() - st10)*1000,"| Throughput fps:",(1.0 / (time.time() - st10)) if (time.time() - st10) > 0 else None)
-            print("------------------FACE RECOG TEMPORAL IDENTITY MANAGER UPDATE - COMPUTE BEST IDENTITY_0G----------------------------")
+            print("WARNING: Using slow API fallback!")
+            print("------------------FACE RECOG TEMPORAL IDENTITY MANAGER UPDATE - COMPUTE BEST IDENTITY (API FALLBACK)----------------------------")
 
         except Exception as e:
             self.logger.error(f"API ERROR: Failed to search similar faces in _compute_best_identity: {e}", exc_info=True)
@@ -492,7 +560,7 @@ class FaceRecognitionEmbeddingUseCase(BaseProcessor):
             # Initialize People activity logging if enabled
             if init_config.enable_people_activity_logging:
                 self.people_activity_logging = PeopleActivityLogging(self.face_client)
-                self.people_activity_logging.start_background_processing()
+                # PeopleActivityLogging starts its background thread in __init__
                 self.logger.info("People activity logging enabled and started")
             
             # Initialize EmbeddingManager
@@ -502,21 +570,31 @@ class FaceRecognitionEmbeddingUseCase(BaseProcessor):
                     confidence_threshold=init_config.confidence_threshold,
                     enable_track_id_cache=init_config.enable_track_id_cache,
                     cache_max_size=init_config.cache_max_size,
-                    cache_ttl=3600
+                    cache_ttl=3600,
+                    background_refresh_interval=43200,
+                    staff_embeddings_cache_ttl=43200,
                 )
             self.embedding_manager = EmbeddingManager(init_config.embedding_config, self.face_client)
             self.logger.info("Embedding manager initialized")
             
-            # Initialize TemporalIdentityManager
+            # Load staff embeddings immediately for fast startup (avoid race conditions)
+            embeddings_loaded = await self.embedding_manager._load_staff_embeddings()
+            if embeddings_loaded:
+                self.logger.info(f"Loaded {len(self.embedding_manager.staff_embeddings)} staff embeddings at initialization")
+            else:
+                self.logger.warning("Failed to load staff embeddings at initialization - will retry in background")
+            
+            # Initialize TemporalIdentityManager with EmbeddingManager for fast local search
             self.temporal_identity_manager = TemporalIdentityManager(
                 face_client=self.face_client,
+                embedding_manager=self.embedding_manager,
                 recognition_threshold=float(init_config.similarity_threshold),
                 history_size=20,
                 unknown_patience=7,
                 switch_patience=5,
                 fallback_margin=0.05,
             )
-            self.logger.info("Temporal identity manager initialized")
+            self.logger.info("Temporal identity manager initialized with embedding manager for local similarity search")
             
             self._initialized = True
             self.logger.info("Face recognition use case fully initialized")
@@ -591,12 +669,20 @@ class FaceRecognitionEmbeddingUseCase(BaseProcessor):
             )
             context = ProcessingContext()
 
-        # Ensure use case is initialized (should be done in _get_use_case_instance, not lazy loaded)
+        # Lazy initialization on first process() call (similar to tracker initialization pattern)
         if not self._initialized:
-            raise RuntimeError(
-                "Face recognition use case not initialized. "
-                "This should be initialized eagerly in PostProcessor._get_use_case_instance()"
-            )
+            self.logger.info("Initializing face recognition use case on first process() call...")
+            try:
+                await self.initialize(config)
+                self.logger.info("Face recognition use case initialized successfully")
+            except Exception as e:
+                self.logger.error(f"Failed to initialize face recognition use case: {e}", exc_info=True)
+                return self.create_error_result(
+                    f"Initialization failed: {e}",
+                    usecase=self.name,
+                    category=self.category,
+                    context=context,
+                )
 
         # Ensure confidence threshold is set
         if not config.confidence_threshold:
@@ -901,7 +987,7 @@ class FaceRecognitionEmbeddingUseCase(BaseProcessor):
     ) -> List[Dict]:
         """Process face recognition for each detection with embeddings"""
 
-        # Initialize face client only when needed and if credentials are available
+        # Expect client to be initialized in initialize(); fail fast if not
         st0=time.time()
         if not self.face_client:
             try: