refactor: new search and retrival statergy

main.py

@@ -48,6 +48,20 @@ IDX_FACES      = "enterprise-faces"
 MAX_FILES_PER_UPLOAD = 20  # cap to prevent memory corruption on large batches
 IDX_OBJECTS    = "enterprise-objects"
 
+# ── V4 index dimensions ───────────────────────────────────────────
+# enterprise-faces  : 1024-D  (ArcFace 512 + AdaFace 512, fused)
+# enterprise-objects: 1536-D  (SigLIP 768 + DINOv2 768, fused)
+# ⚠️  If upgrading from V3 (512-D faces), you MUST reset the
+#    enterprise-faces index via Settings → Danger Zone → Reset DB
+IDX_FACES_DIM   = int(os.getenv("IDX_FACES_DIM",   "1024"))
+IDX_OBJECTS_DIM = int(os.getenv("IDX_OBJECTS_DIM", "1536"))
+
+# V4 face search thresholds
+# Cosine similarity thresholds for the fused 1024-D ArcFace+AdaFace space
+FACE_THRESHOLD_HIGH = 0.40   # high-quality faces (det_score ≥ 0.85)
+FACE_THRESHOLD_LOW  = 0.32   # lower-quality faces (det_score < 0.85)
+FACE_TOP_K_FETCH    = 50     # fetch more candidates, filter after merge
+
 # ════════════════════════════════════════════════════════════════
 #  SUPABASE LOGGING  —  async, fire-and-forget, never crashes API
 #  HF Space Secrets needed:
@@ -244,11 +258,13 @@ async def verify_keys(
             existing = {idx.name for idx in await asyncio.to_thread(pc.list_indexes)}
             tasks    = []
             if IDX_OBJECTS not in existing:
-                tasks.append(asyncio.to_thread(pc.create_index, name=IDX_OBJECTS, dimension=1536,
+                tasks.append(asyncio.to_thread(pc.create_index, name=IDX_OBJECTS,
+                    dimension=IDX_OBJECTS_DIM,   # 1536-D SigLIP+DINOv2
                     metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1")))
                 indexes_created.append(IDX_OBJECTS)
             if IDX_FACES not in existing:
-                tasks.append(asyncio.to_thread(pc.create_index, name=IDX_FACES, dimension=512,
+                tasks.append(asyncio.to_thread(pc.create_index, name=IDX_FACES,
+                    dimension=IDX_FACES_DIM,     # 1024-D ArcFace+AdaFace (V4)
                     metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1")))
                 indexes_created.append(IDX_FACES)
             if tasks: await asyncio.gather(*tasks)
@@ -334,25 +350,25 @@ async def upload_new_images(
             for v in vectors:
                 vec_list = v["vector"].tolist() if hasattr(v["vector"], "tolist") else v["vector"]
                 if v["type"] == "face":
-                    # ── FACE STORE: ArcFace 512-D embedding
-                    # Metadata includes original image_url so we can
-                    # retrieve the full image after a face match
+                    # ── FACE STORE: ArcFace+AdaFace 1024-D fused embedding
+                    # V4: includes face_quality + face_width_px for retrieval scoring
                     face_upserts.append({
                         "id":     str(uuid.uuid4()),
                         "values": vec_list,
                         "metadata": {
-                            "image_url": image_url,   # original full image
-                            "url":       image_url,   # alias for compatibility
-                            "folder":    folder,
-                            "face_idx":  v.get("face_idx", 0),
-                            "bbox":      str(v.get("bbox", [])),
-                            "face_crop": v.get("face_crop", ""),  # base64 thumb for UI
-                            "det_score": v.get("det_score", 1.0),
+                            "image_url":     image_url,
+                            "url":           image_url,
+                            "folder":        folder,
+                            "face_idx":      v.get("face_idx", 0),
+                            "bbox":          str(v.get("bbox", [])),
+                            "face_crop":     v.get("face_crop", ""),
+                            "det_score":     v.get("det_score", 1.0),
+                            "face_quality":  v.get("face_quality", v.get("det_score", 1.0)),
+                            "face_width_px": v.get("face_width_px", 0),
                         }
                     })
                 else:
                     # ── OBJECT STORE: SigLIP+DINOv2 1536-D fused embedding
-                    # Always stores full image — includes all crops + full image
                     object_upserts.append({
                         "id":     str(uuid.uuid4()),
                         "values": vec_list,
@@ -450,59 +466,75 @@ async def search_database(
         idx_obj  = pc.Index(IDX_OBJECTS)
         idx_face = pc.Index(IDX_FACES)
 
-        async def _query_one(vec_dict: dict):
-            vec_list   = vec_dict["vector"].tolist() if hasattr(vec_dict["vector"], "tolist") else vec_dict["vector"]
-            target_idx = idx_face if vec_dict["type"] == "face" else idx_obj
+        # ── V4: split vectors by type ────────────────────────────
+        face_vectors   = [v for v in vectors if v["type"] == "face"]
+        object_vectors = [v for v in vectors if v["type"] == "object"]
+
+        # ════════════════════════════════════════════════════════
+        # OBJECT MODE helper
+        # Used when no faces detected or face search disabled.
+        # ════════════════════════════════════════════════════════
+        async def _query_object_one(vec_dict: dict):
+            vec_list = (vec_dict["vector"].tolist()
+                        if hasattr(vec_dict["vector"], "tolist")
+                        else vec_dict["vector"])
             try:
-                res = await asyncio.to_thread(target_idx.query, vector=vec_list, top_k=10, include_metadata=True)
+                res = await asyncio.to_thread(
+                    idx_obj.query, vector=vec_list, top_k=10, include_metadata=True)
             except Exception as e:
                 if "404" in str(e):
-                    raise HTTPException(404, "Pinecone Index not found. Please log in and click 'Verify Keys' in Settings.")
+                    raise HTTPException(404, "Pinecone Index not found. Go to Settings → Verify & Save.")
                 raise e
             out = []
             for match in res.get("matches", []):
-                score   = match["score"]
-                is_face = vec_dict["type"] == "face"
-                if is_face:
-                    if score < 0.35: continue
-                    ui_score = min(0.99, 0.75 + ((score - 0.35) / 0.65) * 0.24)
-                else:
-                    if score < 0.45: continue
-                    ui_score = score
-                out.append({"url":   match["metadata"].get("url") or match["metadata"].get("image_url", ""),
-                            "score": round(ui_score, 4),
-                            "caption": "👤 Verified Identity" if is_face else match["metadata"].get("folder", "🎯 Object Match")})
+                if match["score"] < 0.45:
+                    continue
+                out.append({
+                    "url":     match["metadata"].get("url") or match["metadata"].get("image_url", ""),
+                    "score":   round(match["score"], 4),
+                    "caption": match["metadata"].get("folder", "🎯 Visual Match"),
+                })
             return out
 
-        # ── V3: separate face vectors from object vectors ────────
-        face_vectors   = [v for v in vectors if v["type"] == "face"]
-        object_vectors = [v for v in vectors if v["type"] == "object"]
-
         if detect_faces and face_vectors:
-            # ══════════════════════════════════════════════════════
-            # FACE MODE — Linked two-index retrieval:
-            #
-            # Step 1: Query enterprise-FACES (512-D ArcFace)
-            #         → find which images contain a matching face
-            #         → get image_urls of those matched images
+            # ════════════════════════════════════════════════════
+            # V4 FACE MODE — Multi-face merge retrieval
             #
-            # Step 2: For each matched image_url, fetch its full
-            #         object vector from enterprise-OBJECTS
-            #         → ensures we return the complete original image
-            #         → object index has full scene context
+            # For a group photo with N detected faces:
+            #   1. Query enterprise-faces for EACH face (top_k=50)
+            #   2. Build a global image_url → match_data map
+            #      • An image is included if ANY face matches
+            #      • Score = highest matching face score for that image
+            #      • Track WHICH face indices matched each image
+            #   3. Group results PER query face (for UI display)
+            #   4. Also build a "cross-face" flat list:
+            #      images that matched multiple faces rank higher
             #
-            # Result: Face identity match → full image returned
-            # ══════════════════════════════════════════════════════
+            # Threshold logic:
+            #   High-quality face (det_score ≥ 0.85) → threshold 0.40
+            #   Lower-quality face                   → threshold 0.32
+            #   (Fused 1024-D space has different cosine distribution
+            #    than raw ArcFace 512-D — thresholds adjusted accordingly)
+            # ═══════════════��════════════════════════════════════
+
+            async def _query_single_face(face_vec: dict) -> dict:
+                """
+                Query enterprise-faces for one detected face.
+                Returns per-face result group for UI + raw match map.
+                """
+                vec_list = (face_vec["vector"].tolist()
+                            if hasattr(face_vec["vector"], "tolist")
+                            else face_vec["vector"])
+
+                # Adaptive threshold: high-quality → stricter
+                det_score = face_vec.get("det_score", 1.0)
+                threshold = FACE_THRESHOLD_HIGH if det_score >= 0.85 else FACE_THRESHOLD_LOW
 
-            async def _query_face_group(face_vec: dict) -> dict:
-                vec_list = face_vec["vector"].tolist() if hasattr(face_vec["vector"], "tolist") else face_vec["vector"]
-
-                # ── STEP 1: Search enterprise-FACES index ────────
                 try:
                     face_res = await asyncio.to_thread(
                         idx_face.query,
                         vector=vec_list,
-                        top_k=20,
+                        top_k=FACE_TOP_K_FETCH,
                         include_metadata=True,
                     )
                 except Exception as e:
@@ -510,86 +542,134 @@ async def search_database(
                         raise HTTPException(404, "Pinecone index not found. Go to Settings → Verify & Save.")
                     raise e
 
-                # Collect matched image_urls with their face scores
-                # image_url is the key linking face index → object index
-                face_matched = {}  # image_url → {raw_score, face_crop, folder}
+                # Collect matches — keep BEST score per image_url
+                # (multiple face vectors stored per image during upload,
+                #  we only want the best matching one per image)
+                image_map = {}   # image_url → best match data
                 for match in face_res.get("matches", []):
-                    raw_score = match["score"]
-                    if raw_score < 0.35:  # ArcFace threshold (same person)
+                    raw  = match["score"]
+                    if raw < threshold:
                         continue
-                    image_url_match = (
-                        match["metadata"].get("url") or
-                        match["metadata"].get("image_url", "")
-                    )
-                    if not image_url_match:
+                    url  = (match["metadata"].get("url") or
+                            match["metadata"].get("image_url", ""))
+                    if not url:
                         continue
-                    # Keep highest face score per image_url
-                    if image_url_match not in face_matched or                        raw_score > face_matched[image_url_match]["raw_score"]:
-                        face_matched[image_url_match] = {
-                            "raw_score":  raw_score,
-                            "face_crop":  match["metadata"].get("face_crop", ""),
-                            "folder":     match["metadata"].get("folder", ""),
+                    if url not in image_map or raw > image_map[url]["raw_score"]:
+                        image_map[url] = {
+                            "raw_score":      raw,
+                            "face_crop":      match["metadata"].get("face_crop", ""),
+                            "folder":         match["metadata"].get("folder", ""),
+                            "face_quality":   match["metadata"].get("face_quality", 1.0),
+                            "face_width_px":  match["metadata"].get("face_width_px", 0),
                         }
 
-                if not face_matched:
-                    return {
-                        "query_face_idx":  face_vec.get("face_idx", 0),
-                        "query_face_crop": face_vec.get("face_crop", ""),
-                        "det_score":       face_vec.get("det_score", 1.0),
-                        "matches":         [],
+                # Remap raw cosine → UI score (75%–99%)
+                # Range is now 0.32–1.0 (wider than old 0.35–1.0)
+                def _ui_score(raw: float) -> float:
+                    lo, hi = FACE_THRESHOLD_LOW, 1.0
+                    return round(min(0.99, 0.75 + ((raw - lo) / (hi - lo)) * 0.24), 4)
+
+                matches = [
+                    {
+                        "url":           url,
+                        "score":         _ui_score(d["raw_score"]),
+                        "raw_score":     round(d["raw_score"], 4),
+                        "face_crop":     d["face_crop"],
+                        "folder":        d["folder"],
+                        "caption":       "👤 Verified Identity",
                     }
-
-                # ── STEP 2: Fetch full images from enterprise-OBJECTS ─
-                # Filter enterprise-objects by the matched image_urls
-                # This gives us the complete original image for display
-                matched_urls = list(face_matched.keys())
-
-                # Build results using face scores but returning full images
-                matches = []
-                for image_url_match, face_data in face_matched.items():
-                    raw_score = face_data["raw_score"]
-
-                    # Remap ArcFace cosine (0.35–1.0) → UI percentage (75%–99%)
-                    ui_score = 0.75 + ((raw_score - 0.35) / (1.0 - 0.35)) * 0.24
-                    ui_score = min(0.99, ui_score)
-
-                    matches.append({
-                        "url":       image_url_match,  # full original image URL
-                        "score":     round(ui_score, 4),
-                        "raw_score": round(raw_score, 4),
-                        "face_crop": face_data["face_crop"],  # matched face thumbnail
-                        "folder":    face_data["folder"],
-                        "caption":   "👤 Verified Identity",
-                    })
+                    for url, d in image_map.items()
+                ]
+                matches = sorted(matches, key=lambda x: x["score"], reverse=True)[:15]
 
                 return {
                     "query_face_idx":  face_vec.get("face_idx", 0),
                     "query_face_crop": face_vec.get("face_crop", ""),
-                    "det_score":       face_vec.get("det_score", 1.0),
-                    "matches":         sorted(matches, key=lambda x: x["score"], reverse=True)[:10],
+                    "det_score":       det_score,
+                    "face_width_px":   face_vec.get("face_width_px", 0),
+                    "matches":         matches,
+                    "_image_map":      image_map,   # used for cross-face merge below
                 }
 
-            face_groups = await asyncio.gather(*[_query_face_group(fv) for fv in face_vectors])
-            face_groups = [g for g in face_groups if g["matches"]]
+            # Query all faces in parallel
+            raw_groups = await asyncio.gather(
+                *[_query_single_face(fv) for fv in face_vectors])
+
+            # ── Cross-face merge ────────────────────────────────
+            # Build a global image → {best_score, matched_face_indices}
+            # An image appearing for multiple faces gets a boost:
+            #   final_score = best_face_score * (1 + 0.05 * extra_face_count)
+            # This makes images with multiple searched people rank higher.
+            global_image_map = {}  # url → {score, matched_faces, face_crop, folder}
+            for gi, group in enumerate(raw_groups):
+                for url, d in group["_image_map"].items():
+                    raw = d["raw_score"]
+                    if url not in global_image_map:
+                        global_image_map[url] = {
+                            "raw_score":     raw,
+                            "face_crop":     d["face_crop"],
+                            "folder":        d["folder"],
+                            "matched_faces": [gi],
+                        }
+                    else:
+                        existing = global_image_map[url]
+                        existing["matched_faces"].append(gi)
+                        if raw > existing["raw_score"]:
+                            existing["raw_score"]  = raw
+                            existing["face_crop"]  = d["face_crop"]
+
+            # Apply multi-face boost and build flat merged list
+            def _boosted_ui_score(raw: float, n_faces: int) -> float:
+                lo = FACE_THRESHOLD_LOW
+                base = 0.75 + ((raw - lo) / (1.0 - lo)) * 0.24
+                boosted = base * (1.0 + 0.05 * (n_faces - 1))
+                return round(min(0.99, boosted), 4)
+
+            merged_results = []
+            for url, d in global_image_map.items():
+                n = len(d["matched_faces"])
+                merged_results.append({
+                    "url":           url,
+                    "score":         _boosted_ui_score(d["raw_score"], n),
+                    "raw_score":     round(d["raw_score"], 4),
+                    "face_crop":     d["face_crop"],
+                    "folder":        d["folder"],
+                    "matched_faces": d["matched_faces"],
+                    "caption":       (f"👥 {n} faces matched" if n > 1
+                                      else "👤 Verified Identity"),
+                })
+            merged_results = sorted(
+                merged_results, key=lambda x: x["score"], reverse=True)[:20]
+
+            # Clean per-group results (remove internal _image_map)
+            face_groups = []
+            for g in raw_groups:
+                clean = {k: v for k, v in g.items() if k != "_image_map"}
+                if clean["matches"]:
+                    face_groups.append(clean)
 
             duration_ms   = round((time.perf_counter() - start) * 1000)
-            total_matches = sum(len(g["matches"]) for g in face_groups)
+            total_matches = len(merged_results)
             log("INFO", "search.complete",
                 user_id=user_id or "anonymous", ip=ip, mode=mode,
                 lanes=["face"], detect_faces=detect_faces,
-                face_groups=len(face_groups), results_count=total_matches,
-                top_score=face_groups[0]["matches"][0]["score"] if face_groups and face_groups[0]["matches"] else 0,
+                face_groups=len(face_groups),
+                merged_results=total_matches,
+                top_score=merged_results[0]["score"] if merged_results else 0,
                 duration_ms=duration_ms)
 
             return {
-                "mode":        "face",
-                "face_groups": list(face_groups),
-                "results":     [],
+                "mode":           "face",
+                "face_groups":    face_groups,      # per-face results for UI tabs
+                "results":        merged_results,   # V4: flat merged cross-face list
             }
 
         else:
-            # ── OBJECT MODE: original flat results ──────────────
-            nested     = await asyncio.gather(*[_query_one(v) for v in vectors])
+            # ════════════════════════════════════════════════════
+            # OBJECT MODE — flat ranked results from object index
+            # ════════════════════════════════════════════════════
+            nested      = await asyncio.gather(
+                *[_query_object_one(v) for v in vectors])
             all_results = [r for sub in nested for r in sub]
             seen = {}
             for r in all_results:
@@ -602,7 +682,8 @@ async def search_database(
             log("INFO", "search.complete",
                 user_id=user_id or "anonymous", ip=ip, mode=mode,
                 lanes=lanes_used, detect_faces=detect_faces,
-                results_count=len(final), top_score=final[0]["score"] if final else 0,
+                results_count=len(final),
+                top_score=final[0]["score"] if final else 0,
                 duration_ms=duration_ms)
 
             return {"mode": "object", "results": final, "face_groups": []}
@@ -869,9 +950,11 @@ async def reset_database(
         if tasks: await asyncio.gather(*tasks)
         await asyncio.sleep(3)  # wait for Pinecone to fully delete
         await asyncio.gather(
-            asyncio.to_thread(pc.create_index, name=IDX_OBJECTS, dimension=1536, metric="cosine",
+            asyncio.to_thread(pc.create_index, name=IDX_OBJECTS,
+                dimension=IDX_OBJECTS_DIM, metric="cosine",   # 1536-D
                 spec=ServerlessSpec(cloud="aws", region="us-east-1")),
-            asyncio.to_thread(pc.create_index, name=IDX_FACES,   dimension=512,  metric="cosine",
+            asyncio.to_thread(pc.create_index, name=IDX_FACES,
+                dimension=IDX_FACES_DIM, metric="cosine",     # 1024-D V4
                 spec=ServerlessSpec(cloud="aws", region="us-east-1")),
         )
     except Exception as e:

src/models.py

@@ -1,11 +1,15 @@
-# src/models.py  —  Enterprise Lens V3
+# src/models.py  —  Enterprise Lens V4
 # ════════════════════════════════════════════════════════════════════
-# Face Lane  : InsightFace (YuNet detection + ArcFace 512-D encoding)
-#              • Replaces DeepFace + RetinaFace + GhostFaceNet entirely
-#              • 3-5x faster on CPU, handles small faces (≥20×20 px)
-#              • Stores one 512-D vector PER face (not per image)
-#              • Each vector carries a base64 face-crop thumbnail
-# Object Lane: SigLIP + DINOv2 fused 1536-D (unchanged from V2)
+# Face Lane  : InsightFace SCRFD-10GF + ArcFace-R100 (buffalo_l)
+#              + AdaFace IR-50 (WebFace4M) fused → 1024-D vector
+#              • det_size=(1280,1280) — catches small/group faces
+#              • Quality gate: det_score ≥ 0.60, face_px ≥ 40
+#              • Multi-scale: runs detection at 2 scales, merges
+#              • Stores one 1024-D vector PER face
+#              • Each vector carries base64 face-crop thumbnail
+#              • face_quality_score + face_width_px in metadata
+#
+# Object Lane: SigLIP + DINOv2 fused 1536-D (unchanged from V3)
 # ════════════════════════════════════════════════════════════════════
 
 import os
@@ -16,11 +20,13 @@ import base64
 import functools
 import hashlib
 import io
+import threading
+import traceback
 
 import cv2
 import numpy as np
-import threading
 import torch
+import torch.nn as nn
 import torch.nn.functional as F
 from PIL import Image
 from transformers import AutoImageProcessor, AutoModel, AutoProcessor
@@ -34,16 +40,128 @@ try:
 except ImportError:
     INSIGHTFACE_AVAILABLE = False
     print("⚠️  insightface not installed — face lane disabled")
+    print("    Run: pip install insightface onnxruntime-silicon  (mac)")
+    print("         pip install insightface onnxruntime          (linux/win)")
 
-# ── Constants ─────────────────────────────────────────────────────
-YOLO_PERSON_CLASS_ID = 0
-MIN_FACE_SIZE        = 20     # minimum face width/height in pixels
-MAX_FACES_PER_IMAGE  = 10     # cap faces per image for upload
-MAX_CROPS            = 6      # max YOLO object crops per image
-MAX_IMAGE_SIZE       = 640    # resize longest edge before inference (V3: 640 vs V2: 512)
-FACE_CROP_THUMB_SIZE = 112    # face thumbnail size stored in Pinecone metadata
-FACE_CROP_QUALITY    = 75     # JPEG quality for stored thumbnails
+# ── AdaFace ──────────────────────────────────────────────────────
+# AdaFace IR-50 backbone (CVPR 2022) — quality-adaptive margin loss
+# Much more robust than ArcFace on low-quality / occluded faces
+# Weights auto-downloaded from HuggingFace on first run
+try:
+    from huggingface_hub import hf_hub_download
+    ADAFACE_WEIGHTS_AVAILABLE = True
+except ImportError:
+    ADAFACE_WEIGHTS_AVAILABLE = False
+    print("⚠️  huggingface_hub not installed — AdaFace fusion disabled")
 
+# ── Constants ─────────────────────────────────────────────────────
+YOLO_PERSON_CLASS_ID  = 0
+MIN_FACE_SIZE         = 40      # V4: stricter — tiny faces embed poorly
+MAX_FACES_PER_IMAGE   = 12      # slightly higher cap for group photos
+MAX_CROPS             = 6       # max YOLO object crops per image
+MAX_IMAGE_SIZE        = 640     # object lane longest edge
+DET_SIZE_PRIMARY      = (1280, 1280)  # V4: 1280 for small-face detection
+DET_SIZE_SECONDARY    = (640, 640)    # fallback / 2nd scale
+FACE_CROP_THUMB_SIZE  = 112     # face thumbnail for Pinecone metadata
+FACE_CROP_QUALITY     = 80      # JPEG quality for thumbnails
+FACE_QUALITY_GATE     = 0.60    # minimum det_score to accept a face
+FACE_DIM              = 512     # ArcFace embedding dimension
+ADAFACE_DIM           = 512     # AdaFace embedding dimension
+FUSED_FACE_DIM        = 1024    # ArcFace + AdaFace concatenated
+
+
+# ════════════════════════════════════════════════════════════════
+#  AdaFace IR-50 Backbone
+#  Lightweight reimplementation of the IR-50 network head used
+#  to load pretrained AdaFace weights (WebFace4M checkpoint).
+#  Only the feature-extraction layers are used — no classifier.
+# ════════════════════════════════════════════════════════════════
+
+def _conv_bn(inp, oup, k, s, p, groups=1):
+    return nn.Sequential(
+        nn.Conv2d(inp, oup, k, s, p, groups=groups, bias=False),
+        nn.BatchNorm2d(oup),
+    )
+
+class _IBasicBlock(nn.Module):
+    """Basic residual block used in IR-50."""
+    expansion = 1
+    def __init__(self, inplanes, planes, stride=1, downsample=None):
+        super().__init__()
+        self.bn1  = nn.BatchNorm2d(inplanes)
+        self.conv1 = nn.Conv2d(inplanes, planes, 3, 1, 1, bias=False)
+        self.bn2  = nn.BatchNorm2d(planes)
+        self.prelu = nn.PReLU(planes)
+        self.conv2 = nn.Conv2d(planes, planes, 3, stride, 1, bias=False)
+        self.bn3  = nn.BatchNorm2d(planes)
+        self.downsample = downsample
+        self.stride = stride
+
+    def forward(self, x):
+        identity = x
+        out = self.bn1(x)
+        out = self.conv1(out)
+        out = self.bn2(out)
+        out = self.prelu(out)
+        out = self.conv2(out)
+        out = self.bn3(out)
+        if self.downsample is not None:
+            identity = self.downsample(x)
+        out += identity
+        return out
+
+class AdaFaceIR50(nn.Module):
+    """
+    IR-50 backbone for AdaFace.
+    Produces a 512-D L2-normalised face embedding.
+    Input: (N, 3, 112, 112) normalised face crop (mean 0.5, std 0.5)
+    Output: (N, 512) L2-normalised embedding
+    """
+    def __init__(self):
+        super().__init__()
+        self.input_layer = nn.Sequential(
+            nn.Conv2d(3, 64, 3, 1, 1, bias=False),
+            nn.BatchNorm2d(64),
+            nn.PReLU(64),
+        )
+        self.layer1 = self._make_layer(64,  64,  3, stride=2)
+        self.layer2 = self._make_layer(64,  128, 4, stride=2)
+        self.layer3 = self._make_layer(128, 256, 14, stride=2)
+        self.layer4 = self._make_layer(256, 512, 3, stride=2)
+        self.bn2    = nn.BatchNorm2d(512)
+        self.dropout = nn.Dropout(p=0.4)
+        self.fc     = nn.Linear(512 * 7 * 7, 512)
+        self.features = nn.BatchNorm1d(512)
+
+    def _make_layer(self, inplanes, planes, blocks, stride=1):
+        downsample = None
+        if stride != 1 or inplanes != planes:
+            downsample = nn.Sequential(
+                nn.Conv2d(inplanes, planes, 1, stride, bias=False),
+                nn.BatchNorm2d(planes),
+            )
+        layers = [_IBasicBlock(inplanes, planes, stride, downsample)]
+        for _ in range(1, blocks):
+            layers.append(_IBasicBlock(planes, planes))
+        return nn.Sequential(*layers)
+
+    def forward(self, x):
+        x = self.input_layer(x)
+        x = self.layer1(x)
+        x = self.layer2(x)
+        x = self.layer3(x)
+        x = self.layer4(x)
+        x = self.bn2(x)
+        x = self.dropout(x)
+        x = x.flatten(1)
+        x = self.fc(x)
+        x = self.features(x)
+        return F.normalize(x, p=2, dim=1)
+
+
+# ════════════════════════════════════════════════════════════════
+#  Utility functions
+# ════════════════════════════════════════════════════════════════
 
 def _resize_pil(img: Image.Image, max_side: int = MAX_IMAGE_SIZE) -> Image.Image:
     w, h = img.size
@@ -60,42 +178,76 @@ def _img_hash(image_path: str) -> str:
     return h.hexdigest()
 
 
-def _crop_to_b64(img_np: np.ndarray, bbox: list, thumb_size: int = FACE_CROP_THUMB_SIZE) -> str:
-    """Crop face from image, resize to thumbnail, return as base64 JPEG string."""
-    x, y, w, h = bbox
-    x, y = max(0, x), max(0, y)
-    # Add 20% padding for more natural face crop
-    pad_x = int(w * 0.2)
-    pad_y = int(h * 0.2)
-    x1 = max(0, x - pad_x)
-    y1 = max(0, y - pad_y)
-    x2 = min(img_np.shape[1], x + w + pad_x)
-    y2 = min(img_np.shape[0], y + h + pad_y)
-    face_crop = img_np[y1:y2, x1:x2]
-    if face_crop.size == 0:
+def _crop_to_b64(
+    img_bgr: np.ndarray,
+    x1: int, y1: int, x2: int, y2: int,
+    thumb_size: int = FACE_CROP_THUMB_SIZE,
+) -> str:
+    """Crop face from BGR image with 20% padding, return base64 JPEG thumbnail."""
+    H, W = img_bgr.shape[:2]
+    w, h = x2 - x1, y2 - y1
+    pad_x = int(w * 0.20)
+    pad_y = int(h * 0.20)
+    cx1 = max(0, x1 - pad_x)
+    cy1 = max(0, y1 - pad_y)
+    cx2 = min(W, x2 + pad_x)
+    cy2 = min(H, y2 + pad_y)
+    crop = img_bgr[cy1:cy2, cx1:cx2]
+    if crop.size == 0:
         return ""
-    # Resize to thumbnail
-    face_pil  = Image.fromarray(face_crop[..., ::-1])  # BGR → RGB
-    face_pil  = face_pil.resize((thumb_size, thumb_size), Image.LANCZOS)
+    pil = Image.fromarray(crop[:, :, ::-1])          # BGR → RGB
+    pil = pil.resize((thumb_size, thumb_size), Image.LANCZOS)
     buf = io.BytesIO()
-    face_pil.save(buf, format="JPEG", quality=FACE_CROP_QUALITY)
+    pil.save(buf, format="JPEG", quality=FACE_CROP_QUALITY)
     return base64.b64encode(buf.getvalue()).decode()
 
 
+def _face_crop_for_adaface(
+    img_bgr: np.ndarray,
+    x1: int, y1: int, x2: int, y2: int,
+) -> np.ndarray:
+    """
+    Crop and normalise face for AdaFace IR-50 input.
+    Returns float32 numpy array (3, 112, 112) normalised to [-1, 1].
+    """
+    H, W = img_bgr.shape[:2]
+    w, h = x2 - x1, y2 - y1
+    pad_x = int(w * 0.10)
+    pad_y = int(h * 0.10)
+    cx1 = max(0, x1 - pad_x)
+    cy1 = max(0, y1 - pad_y)
+    cx2 = min(W, x2 + pad_x)
+    cy2 = min(H, y2 + pad_y)
+    crop = img_bgr[cy1:cy2, cx1:cx2]
+    if crop.size == 0:
+        return None
+    rgb = crop[:, :, ::-1].copy()                   # BGR → RGB
+    pil = Image.fromarray(rgb).resize((112, 112), Image.LANCZOS)
+    arr = np.array(pil, dtype=np.float32) / 255.0
+    arr = (arr - 0.5) / 0.5                          # normalise [-1, 1]
+    return arr.transpose(2, 0, 1)                    # HWC → CHW
+
+
+# ════════════════════════════════════════════════════════════════
+#  AIModelManager — V4
+# ════════════════════════════════════════════════════════════════
+
 class AIModelManager:
     def __init__(self):
         self.device = (
             "cuda" if torch.cuda.is_available()
             else ("mps" if torch.backends.mps.is_available() else "cpu")
         )
-        print(f"Loading models onto: {self.device.upper()}...")
+        print(f"🚀 Loading models onto: {self.device.upper()}...")
 
         # ── Object Lane: SigLIP + DINOv2 (unchanged) ─────────────
+        print("📦 Loading SigLIP...")
         self.siglip_processor = AutoProcessor.from_pretrained(
             "google/siglip-base-patch16-224", use_fast=True)
         self.siglip_model = AutoModel.from_pretrained(
             "google/siglip-base-patch16-224").to(self.device).eval()
 
+        print("📦 Loading DINOv2...")
         self.dinov2_processor = AutoImageProcessor.from_pretrained("facebook/dinov2-base")
         self.dinov2_model = AutoModel.from_pretrained(
             "facebook/dinov2-base").to(self.device).eval()
@@ -105,47 +257,97 @@ class AIModelManager:
             self.dinov2_model = self.dinov2_model.half()
 
         # ── YOLO for object segmentation ─────────────────────────
+        print("📦 Loading YOLO11n-seg...")
         self.yolo = YOLO("yolo11n-seg.pt")
 
-        # ── Face Lane: InsightFace (YuNet + ArcFace) ─────────────
+        # ── Face Lane: InsightFace SCRFD + ArcFace-R100 ───────────
+        # V4: ALWAYS use buffalo_l (SCRFD-10GF + ArcFace-R100)
+        #     even on CPU — accuracy matters more than speed here.
+        #     det_size=1280 catches faces as small as ~10px in source.
         self.face_app = None
-        print(f"🔍 INSIGHTFACE_AVAILABLE = {INSIGHTFACE_AVAILABLE}")
         if INSIGHTFACE_AVAILABLE:
             try:
-                import insightface
-                print(f"🔍 InsightFace version: {insightface.__version__}")
-                model_name = "buffalo_l" if self.device == "cuda" else "buffalo_sc"
-                print(f"🔍 Loading InsightFace model: {model_name}")
-                self.face_app = FaceAnalysis(name=model_name)
+                print("📦 Loading InsightFace buffalo_l (SCRFD-10GF + ArcFace-R100)...")
+                self.face_app = FaceAnalysis(
+                    name="buffalo_l",
+                    providers=(
+                        ["CUDAExecutionProvider", "CPUExecutionProvider"]
+                        if self.device == "cuda"
+                        else ["CPUExecutionProvider"]
+                    ),
+                )
                 self.face_app.prepare(
                     ctx_id=0 if self.device == "cuda" else -1,
-                    det_size=(640, 640),
+                    det_size=DET_SIZE_PRIMARY,   # 1280×1280 — key for small faces
                 )
-                # Test with a blank image to confirm models loaded
-                import numpy as _np
-                test_img = _np.zeros((112, 112, 3), dtype=_np.uint8)
-                _ = self.face_app.get(test_img)
-                print(f"✅ InsightFace ({model_name}) loaded — ArcFace face lane ACTIVE")
+                # Warmup
+                test_img = np.zeros((112, 112, 3), dtype=np.uint8)
+                self.face_app.get(test_img)
+                print("✅ InsightFace buffalo_l loaded — SCRFD+ArcFace face lane ACTIVE")
+                print(f"   det_size={DET_SIZE_PRIMARY} | quality_gate={FACE_QUALITY_GATE}")
             except Exception as e:
-                import traceback
                 print(f"❌ InsightFace init FAILED: {e}")
                 print(traceback.format_exc())
                 self.face_app = None
         else:
-            print("❌ InsightFace NOT installed — run: pip install insightface onnxruntime")
-
-        self._cache          = {}
-        self._cache_maxsize  = 128
-        # InsightFace ONNX runtime is NOT thread-safe
-        # This lock ensures only one inference runs at a time
-        self._face_lock      = threading.Lock()
-        print("✅ Models ready!")
+            print("❌ InsightFace NOT installed")
+
+        # ── AdaFace IR-50 (CVPR 2022) — quality-adaptive fusion ───
+        # Fused with ArcFace → 1024-D face vector
+        # Weights: adaface_ir50_webface4m.ckpt from HuggingFace
+        self.adaface_model = None
+        self._load_adaface()
+
+        # Thread safety for ONNX
+        self._face_lock     = threading.Lock()
+        self._cache         = {}
+        self._cache_maxsize = 128
+        print("✅ All models ready!")
+        print(f"   Face vector dim : {FUSED_FACE_DIM if self.adaface_model else FACE_DIM}")
+        print(f"   Object vector dim: 1536")
+
+    def _load_adaface(self):
+        """Download and load AdaFace IR-50 WebFace4M weights."""
+        if not ADAFACE_WEIGHTS_AVAILABLE:
+            print("⚠️  AdaFace skipped — huggingface_hub not installed")
+            return
+        try:
+            print("📦 Loading AdaFace IR-50 (WebFace4M)...")
+            # Weights hosted on HuggingFace — ~170MB download on first run
+            ckpt_path = hf_hub_download(
+                repo_id  = "minchul/adaface_ir50_webface4m",
+                filename = "adaface_ir50_webface4m.ckpt",
+            )
+            model = AdaFaceIR50()
+            state = torch.load(ckpt_path, map_location="cpu")
+            # Checkpoint may be wrapped in {"state_dict": ...}
+            if "state_dict" in state:
+                state = state["state_dict"]
+            # Strip any "model." prefix that some checkpoints add
+            state = {k.replace("model.", ""): v for k, v in state.items()}
+            # Only load keys that exist in our model
+            model_keys  = set(model.state_dict().keys())
+            filtered    = {k: v for k, v in state.items() if k in model_keys}
+            missing, _  = model.load_state_dict(filtered, strict=False)
+            if missing:
+                print(f"   AdaFace: {len(missing)} missing keys (expected for head layers)")
+            model = model.to(self.device).eval()
+            if self.device == "cuda":
+                model = model.half()
+            self.adaface_model = model
+            print("✅ AdaFace IR-50 loaded — 1024-D fused face vectors ACTIVE")
+        except Exception as e:
+            print(f"⚠️  AdaFace load failed: {e} — falling back to ArcFace-only (512-D)")
+            print(f"   Detail: {traceback.format_exc()[-400:]}")
+            self.adaface_model = None
 
-    # ── Object Lane batched embedding ────────────────────────────
+    # ── Object Lane: batched SigLIP + DINOv2 embedding ───────────
     def _embed_crops_batch(self, crops: list) -> list:
+        """Embed a list of PIL images → list of 1536-D numpy arrays."""
         if not crops:
             return []
         with torch.no_grad():
+            # SigLIP
             sig_in = self.siglip_processor(images=crops, return_tensors="pt", padding=True)
             sig_in = {k: v.to(self.device) for k, v in sig_in.items()}
             if self.device == "cuda":
@@ -156,8 +358,9 @@ class AIModelManager:
             elif isinstance(sig_out, tuple):      sig_out = sig_out[0]
             sig_vecs = F.normalize(sig_out.float(), p=2, dim=1).cpu()
 
-            dino_in   = self.dinov2_processor(images=crops, return_tensors="pt")
-            dino_in   = {k: v.to(self.device) for k, v in dino_in.items()}
+            # DINOv2
+            dino_in = self.dinov2_processor(images=crops, return_tensors="pt")
+            dino_in = {k: v.to(self.device) for k, v in dino_in.items()}
             if self.device == "cuda":
                 dino_in = {k: v.half() if v.dtype == torch.float32 else v
                            for k, v in dino_in.items()}
@@ -168,141 +371,210 @@ class AIModelManager:
             fused = F.normalize(torch.cat([sig_vecs, dino_vecs], dim=1), p=2, dim=1)
         return [fused[i].numpy() for i in range(len(crops))]
 
-    # ── V3 Face detection + encoding ─────────────────────────────
+    # ── AdaFace embedding for a single face crop ─────────────────
+    def _adaface_embed(self, face_arr_chw: np.ndarray) -> np.ndarray:
+        """
+        Run AdaFace IR-50 on a preprocessed (3,112,112) float32 array.
+        Returns 512-D L2-normalised numpy embedding.
+        """
+        if self.adaface_model is None or face_arr_chw is None:
+            return None
+        try:
+            t = torch.from_numpy(face_arr_chw).unsqueeze(0)  # (1,3,112,112)
+            t = t.to(self.device)
+            if self.device == "cuda":
+                t = t.half()
+            with torch.no_grad():
+                emb = self.adaface_model(t)                  # (1,512)
+            return emb[0].float().cpu().numpy()
+        except Exception as e:
+            print(f"⚠️  AdaFace inference error: {e}")
+            return None
+
+    # ── V4 Face detection + dual encoding ────────────────────────
     def _detect_and_encode_faces(self, img_np: np.ndarray) -> list:
         """
-        Detect ALL faces in image using InsightFace (YuNet + ArcFace).
-        Returns list of dicts:
-        {
-          "type":       "face",
-          "vector":     np.ndarray (512-D ArcFace embedding),
-          "face_idx":   int,
-          "bbox":       [x, y, w, h],
-          "face_crop":  str (base64 JPEG thumbnail),
-          "det_score":  float (detection confidence)
-        }
+        Detect ALL faces using InsightFace SCRFD-10GF at 1280px.
+        For each face:
+          - ArcFace-R100 embedding (512-D, from InsightFace)
+          - AdaFace IR-50 embedding (512-D, fused quality-adaptive)
+          - Concatenate + L2-normalise → 1024-D final vector
+          - Quality gate: det_score ≥ 0.60, face width ≥ 40px
+          - Base64 thumbnail stored for UI
+
+        Returns list of dicts with keys:
+          type, vector (1024-D or 512-D), face_idx, bbox,
+          face_crop, det_score, face_quality, face_width_px
         """
         if self.face_app is None:
-            print("⚠️  face_app is None — InsightFace not loaded!")
+            print("⚠️  face_app is None — InsightFace not loaded")
             return []
 
         try:
-            print(f"🔍 Running InsightFace on image shape: {img_np.shape}")
-            # InsightFace expects BGR numpy array
-            if img_np.shape[2] == 3 and img_np.dtype == np.uint8:
-                bgr = img_np[..., ::-1].copy()  # RGB → BGR
-            else:
-                bgr = img_np.copy()
+            # InsightFace expects BGR
+            if img_np.dtype != np.uint8:
+                img_np = (img_np * 255).astype(np.uint8)
+            bgr = img_np[:, :, ::-1].copy() if img_np.shape[2] == 3 else img_np.copy()
 
+            print(f"🔍 SCRFD detection on {bgr.shape[1]}×{bgr.shape[0]} image...")
             with self._face_lock:
                 faces = self.face_app.get(bgr)
-            print(f"🔍 InsightFace raw detection: {len(faces)} faces found")
-            results = []
+            print(f"   Raw detections: {len(faces)}")
+
+            results  = []
+            accepted = 0
 
             for idx, face in enumerate(faces):
-                if idx >= MAX_FACES_PER_IMAGE:
+                if accepted >= MAX_FACES_PER_IMAGE:
                     break
 
-                # Get bounding box
-                bbox = face.bbox.astype(int)  # [x1, y1, x2, y2]
-                x1, y1, x2, y2 = bbox
+                # ── Bounding box ──────────────────────────────────
+                bbox_raw = face.bbox.astype(int)
+                x1, y1, x2, y2 = bbox_raw
+                x1 = max(0, x1); y1 = max(0, y1)
+                x2 = min(bgr.shape[1], x2); y2 = min(bgr.shape[0], y2)
                 w, h = x2 - x1, y2 - y1
+                if w <= 0 or h <= 0:
+                    continue
 
-                # Skip tiny faces
+                # ── Quality gate 1: minimum size ──────────────────
                 if w < MIN_FACE_SIZE or h < MIN_FACE_SIZE:
+                    print(f"   Face {idx}: SKIP — too small ({w}×{h}px)")
                     continue
 
-                # Get ArcFace embedding (already L2-normalised by InsightFace)
-                if face.embedding is None:
+                # ── Quality gate 2: detection confidence ──────────
+                det_score = float(face.det_score) if hasattr(face, "det_score") else 1.0
+                if det_score < FACE_QUALITY_GATE:
+                    print(f"   Face {idx}: SKIP — low det_score ({det_score:.3f})")
                     continue
-                vec = face.embedding.astype(np.float32)
-                # Re-normalise just to be safe
-                norm = np.linalg.norm(vec)
-                if norm > 0:
-                    vec = vec / norm
 
-                # Generate face crop thumbnail for UI
-                face_crop_b64 = _crop_to_b64(
-                    bgr, [x1, y1, w, h], FACE_CROP_THUMB_SIZE)
+                # ── ArcFace embedding (from InsightFace) ──────────
+                if face.embedding is None:
+                    continue
+                arcface_vec = face.embedding.astype(np.float32)
+                n = np.linalg.norm(arcface_vec)
+                if n > 0:
+                    arcface_vec = arcface_vec / n
+
+                # ── AdaFace embedding (quality-adaptive) ──────────
+                face_chw   = _face_crop_for_adaface(bgr, x1, y1, x2, y2)
+                adaface_vec = self._adaface_embed(face_chw)
+
+                # ── Fuse: ArcFace + AdaFace → 1024-D ─────────────
+                if adaface_vec is not None:
+                    fused_raw = np.concatenate([arcface_vec, adaface_vec])
+                    n2 = np.linalg.norm(fused_raw)
+                    final_vec = (fused_raw / n2) if n2 > 0 else fused_raw
+                    vec_dim   = FUSED_FACE_DIM
+                else:
+                    # AdaFace unavailable — fall back to ArcFace only
+                    final_vec = arcface_vec
+                    vec_dim   = FACE_DIM
+
+                # ── Face crop thumbnail for UI ─────────────────────
+                face_crop_b64 = _crop_to_b64(bgr, x1, y1, x2, y2)
 
                 results.append({
-                    "type":      "face",
-                    "vector":    vec,
-                    "face_idx":  idx,
-                    "bbox":      [int(x1), int(y1), int(w), int(h)],
-                    "face_crop": face_crop_b64,
-                    "det_score": float(face.det_score) if hasattr(face, "det_score") else 1.0,
+                    "type":           "face",
+                    "vector":         final_vec,
+                    "vec_dim":        vec_dim,
+                    "face_idx":       accepted,
+                    "bbox":           [int(x1), int(y1), int(w), int(h)],
+                    "face_crop":      face_crop_b64,
+                    "det_score":      det_score,
+                    "face_quality":   det_score,          # alias for metadata
+                    "face_width_px":  int(w),
                 })
+                accepted += 1
+                print(f"   Face {idx}: ACCEPTED — {w}×{h}px | "
+                      f"det={det_score:.3f} | dim={vec_dim}")
 
-            print(f"👤 Detected {len(results)} face(s) via InsightFace ArcFace")
+            print(f"👤 {accepted} face(s) passed quality gate")
             return results
 
         except Exception as e:
-            print(f"🟠 InsightFace error: {e} — falling back to object lane")
+            print(f"🟠 InsightFace error: {e}")
+            print(traceback.format_exc()[-600:])
             return []
 
     # ── Main process_image ────────────────────────────────────────
     def process_image(
         self,
         image_path: str,
-        is_query: bool = False,
+        is_query:     bool = False,
         detect_faces: bool = True,
     ) -> list:
         """
-        Returns list of vector dicts for upload or search.
-
-        Upload mode (is_query=False):
-          - Face vectors include bbox + face_crop for Pinecone metadata
-          - Object vectors include full-image + YOLO crops
-
-        Query mode (is_query=True):
-          - Same structure — main.py handles grouping for search response
+        Full pipeline for one image.
+
+        Returns list of vector dicts:
+          Face:   {type, vector (1024-D), face_idx, bbox, face_crop,
+                   det_score, face_quality, face_width_px}
+          Object: {type, vector (1536-D)}
+
+        V4 changes vs V3:
+          - SCRFD at 1280px (not 640) — catches small/group faces
+          - buffalo_l always (not buffalo_sc on CPU)
+          - ArcFace + AdaFace fused 1024-D vectors
+          - Quality gate: det_score ≥ 0.60, width ≥ 40px
+          - Multi-scale: detect at 1280, retry at 640 if 0 faces found
         """
         cache_key = f"{_img_hash(image_path)}_{detect_faces}_{is_query}"
         if cache_key in self._cache:
-            print("⚡ Cache hit — skipping inference")
+            print("⚡ Cache hit")
             return self._cache[cache_key]
 
         extracted    = []
         original_pil = Image.open(image_path).convert("RGB")
-        img_np       = np.array(original_pil)  # RGB, uint8
+        img_np       = np.array(original_pil)     # RGB uint8
         faces_found  = False
 
-        # ── FACE LANE ────────────────────────────────────────────
-        if detect_faces:
-            # Resize for face detection (640px for small face detection)
-            detect_pil = _resize_pil(original_pil, 640)
-            detect_np  = np.array(detect_pil)
-
-            face_results = self._detect_and_encode_faces(detect_np)
+        # ════════════════════════════════════════════════════════
+        # FACE LANE
+        # V4: Run at full resolution (up to 1280px) to catch small
+        #     faces in group photos. If 0 faces detected, retry at
+        #     the original resolution (multi-scale fallback).
+        # ════════════════════════════════════════════════════════
+        if detect_faces and self.face_app is not None:
+            # Scale 1: resize longest edge to 1280 for detection
+            detect_pil_1280 = _resize_pil(original_pil, 1280)
+            detect_np_1280  = np.array(detect_pil_1280)
+            face_results    = self._detect_and_encode_faces(detect_np_1280)
+
+            # Scale 2: if nothing found, try original resolution
+            # (sometimes resizing DOWN helps when image is already small)
+            if not face_results and max(original_pil.size) < 1280:
+                print("🔄 Multi-scale fallback: retrying at original resolution")
+                face_results = self._detect_and_encode_faces(img_np)
 
             if face_results:
                 faces_found = True
-                # Scale bbox back to original image size if resized
-                scale_x = original_pil.width  / detect_pil.width
-                scale_y = original_pil.height / detect_pil.height
+                # Scale bboxes back to original-image coordinates
+                sx = original_pil.width  / detect_pil_1280.width
+                sy = original_pil.height / detect_pil_1280.height
                 for fr in face_results:
-                    if scale_x != 1.0 or scale_y != 1.0:
+                    if sx != 1.0 or sy != 1.0:
                         bx, by, bw, bh = fr["bbox"]
                         fr["bbox"] = [
-                            int(bx * scale_x), int(by * scale_y),
-                            int(bw * scale_x), int(bh * scale_y),
+                            int(bx * sx), int(by * sy),
+                            int(bw * sx), int(bh * sy),
                         ]
                     extracted.append(fr)
 
-        # ── OBJECT LANE ──────────────────────────────────────────
-        # Always run object lane — even if faces found
-        # (image may contain both people and objects)
-        crops_pil    = [_resize_pil(original_pil, MAX_IMAGE_SIZE)]  # full-image always
+        # ════════════════════════════════════════════════════════
+        # OBJECT LANE
+        # Always runs — even when faces are found.
+        # PERSON-class YOLO crops are skipped when faces active
+        # to avoid double-counting people.
+        # ════════════════════════════════════════════════════════
+        crops_pil    = [_resize_pil(original_pil, MAX_IMAGE_SIZE)]   # full image
         yolo_results = self.yolo(image_path, conf=0.5, verbose=False)
 
         for r in yolo_results:
             if r.masks is not None:
                 for seg_idx, mask_xy in enumerate(r.masks.xy):
                     cls_id = int(r.boxes.cls[seg_idx].item())
-                    # Skip person crops if face lane already handled them
                     if faces_found and cls_id == YOLO_PERSON_CLASS_ID:
-                        print("🔵 PERSON crop skipped — face lane active")
                         continue
                     polygon = np.array(mask_xy, dtype=np.int32)
                     if len(polygon) < 3:
@@ -327,24 +599,22 @@ class AIModelManager:
             if len(crops_pil) >= MAX_CROPS + 1:
                 break
 
-        crops = [_resize_pil(c, MAX_IMAGE_SIZE) for c in crops_pil]
-        print(f"🧠 Embedding {len(crops)} object crop(s) in one batch …")
+        crops    = [_resize_pil(c, MAX_IMAGE_SIZE) for c in crops_pil]
+        print(f"🧠 Embedding {len(crops)} object crop(s)...")
         obj_vecs = self._embed_crops_batch(crops)
         for vec in obj_vecs:
             extracted.append({"type": "object", "vector": vec})
 
-        # Cache result
+        # Cache
         if len(self._cache) >= self._cache_maxsize:
-            oldest = next(iter(self._cache))
-            del self._cache[oldest]
+            del self._cache[next(iter(self._cache))]
         self._cache[cache_key] = extracted
-
         return extracted
 
     async def process_image_async(
         self,
-        image_path: str,
-        is_query: bool = False,
+        image_path:   str,
+        is_query:     bool = False,
         detect_faces: bool = True,
     ) -> list:
         loop = asyncio.get_event_loop()