Update src/models.py

src/models.py

@@ -1,77 +1,74 @@
-# src/models.py  —  Enterprise Lens V4
-# ════════════════════════════════════════════════════════════════════
-# 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)
-# ════════════════════════════════════════════════════════════════════
+"""
+src/models.py — AI inference pipeline: face detection + object embedding.
 
-import os
-os.environ["TF_CPP_MIN_LOG_LEVEL"] = "3"
+Two independent lanes:
+  Face lane   : InsightFace SCRFD detection → ArcFace + AdaFace → 1024-D vector
+  Object lane : YOLO segmentation crops    → SigLIP + DINOv2   → 1536-D vector
+
+Both lanes run on every image. main.py decides which results to use for search.
+
+Key design decisions:
+  - Multi-scale + horizontal-flip detection catches small/turned faces.
+  - CLAHE pre-processing recovers detail in dark / over-exposed photos.
+  - ArcFace + AdaFace fusion: identity-discriminative + quality-adaptive.
+  - SigLIP + DINOv2 fusion: semantic understanding + fine-grained texture.
+  - Results are cached by (file_hash, detect_faces) to avoid re-inference
+    on duplicate uploads or repeated queries of the same image.
+"""
 
-import asyncio
-import base64
 import functools
-import hashlib
 import io
 import threading
+import asyncio
 import traceback
+import base64
 
 import cv2
 import numpy as np
 import torch
-import torch.nn as nn
 import torch.nn.functional as F
 from PIL import Image
 from transformers import AutoImageProcessor, AutoModel, AutoProcessor
 from ultralytics import YOLO
+import insightface
+from insightface.app import FaceAnalysis
+
+from .config import (
+    # Object lane
+    MAX_IMAGE_SIZE, MAX_CROPS, YOLO_PERSON_CLASS_ID,
+    YOLO_MIN_CROP_PX, YOLO_CONF_THRESHOLD,
+    # Face lane — detection
+    DET_SIZE_PRIMARY, DET_SCALES, IOU_DEDUP_THRESHOLD,
+    MIN_FACE_SIZE, MAX_FACES_PER_IMAGE, FACE_QUALITY_GATE,
+    # Face lane — dimensions
+    FACE_DIM, ADAFACE_DIM, FUSED_FACE_DIM,
+    # Thumbnails
+    FACE_CROP_THUMB_SIZE, FACE_CROP_QUALITY,
+    FACE_CROP_PADDING, ADAFACE_CROP_PADDING,
+    # Cache
+    INFERENCE_CACHE_SIZE,
+    # AdaFace toggle
+    ENABLE_ADAFACE, HF_TOKEN,
+)
+from .utils import img_hash
+
 
-# ── InsightFace ───────────────────────────────────────────────────
-try:
-    import insightface
-    from insightface.app import FaceAnalysis
-    INSIGHTFACE_AVAILABLE = True
-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)")
-
-# ── AdaFace ──────────────────────────────────────────────────────
-# Disabled by default — enable by setting ENABLE_ADAFACE=1 env var.
-# When disabled: ArcFace(512) + zeros(512) = 1024-D (fully functional).
-ADAFACE_WEIGHTS_AVAILABLE = False  # controlled by ENABLE_ADAFACE env var
-
-# ── Constants ─────────────────────────────────────────────────────
-YOLO_PERSON_CLASS_ID  = 0
-MIN_FACE_SIZE         = 20      # lowered: 40 missed small faces in group photos
-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.35    # lowered from 0.60 — accepts sunglasses, angles, smiles
-# Multi-scale pyramid — tried in order, results merged with IoU dedup
-DET_SCALES            = [(1280, 1280), (960, 960), (640, 640)]
-IOU_DEDUP_THRESHOLD   = 0.45    # suppress duplicate detections across scales
-FACE_DIM              = 512     # ArcFace embedding dimension
-ADAFACE_DIM           = 512     # AdaFace embedding dimension
-FUSED_FACE_DIM        = 1024    # ArcFace + AdaFace concatenated
-
-
-# ════════════════════════════════════════════════════════════════
-#  Utility functions
-# ════════════════════════════════════════════════════════════════
+# ════════════════════════════════════════════════════════════════════
+#  MODULE-LEVEL UTILITY FUNCTIONS
+#  Pure functions — no model state, safe to call from anywhere.
+# ════════════════════════════════════════════════════════════════════
 
 def _resize_pil(img: Image.Image, max_side: int = MAX_IMAGE_SIZE) -> Image.Image:
+    """
+    Resize a PIL image so its longest side is at most `max_side` pixels,
+    preserving aspect ratio.
+
+    Why max-side (not fixed W×H)?  Fixed dimensions squash portrait/landscape
+    images.  Preserving aspect ratio keeps faces and objects undistorted.
+
+    Why LANCZOS?  It's a windowed sinc filter that considers more surrounding
+    pixels than bilinear/nearest, preserving fine detail on downscale.
+    """
     w, h = img.size
     if max(w, h) <= max_side:
         return img
@@ -79,32 +76,33 @@ def _resize_pil(img: Image.Image, max_side: int = MAX_IMAGE_SIZE) -> Image.Image
     return img.resize((int(w * scale), int(h * scale)), Image.LANCZOS)
 
 
-def _img_hash(image_path: str) -> str:
-    h = hashlib.md5()
-    with open(image_path, "rb") as f:
-        h.update(f.read(65536))
-    return h.hexdigest()
-
-
 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]
+    """
+    Crop a face from a BGR image with FACE_CROP_PADDING padding,
+    resize to FACE_CROP_THUMB_SIZE × FACE_CROP_THUMB_SIZE,
+    and return as a base64-encoded JPEG string.
+
+    The 20 % padding (vs 10 % for AdaFace) ensures the UI thumbnail
+    includes hair, ears, and chin context — making it visually recognisable.
+    The thumbnail is stored in Pinecone metadata; the frontend renders it
+    as data:image/jpeg;base64,... without a Cloudinary round-trip.
+    """
+    H, W   = img_bgr.shape[:2]
+    w, h   = x2 - x1, y2 - y1
+    pad_x  = int(w * FACE_CROP_PADDING)
+    pad_y  = int(h * FACE_CROP_PADDING)
+    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 ""
-    pil = Image.fromarray(crop[:, :, ::-1])          # BGR → RGB
-    pil = pil.resize((thumb_size, thumb_size), Image.LANCZOS)
+    pil = Image.fromarray(crop[:, :, ::-1])                          # BGR → RGB
+    pil = pil.resize((FACE_CROP_THUMB_SIZE, FACE_CROP_THUMB_SIZE), Image.LANCZOS)
     buf = io.BytesIO()
     pil.save(buf, format="JPEG", quality=FACE_CROP_QUALITY)
     return base64.b64encode(buf.getvalue()).decode()
@@ -113,216 +111,315 @@ def _crop_to_b64(
 def _face_crop_for_adaface(
     img_bgr: np.ndarray,
     x1: int, y1: int, x2: int, y2: int,
-) -> np.ndarray:
+) -> np.ndarray | None:
     """
-    Crop and normalise face for AdaFace IR-50 input.
-    Returns float32 numpy array (3, 112, 112) normalised to [-1, 1].
+    Crop and preprocess a face region for AdaFace IR-50 model input.
+
+    Input contract:  BGR uint8 numpy array (H, W, 3)
+    Output contract: float32 numpy array (3, 112, 112) normalised to [-1, 1]
+
+    Why 10 % padding (not 20 %)?  AdaFace expects a tight face crop; too
+    much background degrades embedding quality.
+
+    Why [-1, 1] normalisation?  AdaFace was trained with this range.
+    Feeding [0, 1] or [0, 255] produces garbage embeddings because the
+    model's BN/weight distributions assume [-1, 1] input statistics.
+
+    Why HWC → CHW transpose?  PIL and numpy use (H, W, C); PyTorch models
+    expect (C, H, W).  The transpose bridges this convention difference.
     """
-    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]
+    H, W   = img_bgr.shape[:2]
+    w, h   = x2 - x1, y2 - y1
+    pad_x  = int(w * ADAFACE_CROP_PADDING)
+    pad_y  = int(h * ADAFACE_CROP_PADDING)
+    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
-
+    rgb    = crop[:, :, ::-1].copy()
+    pil    = Image.fromarray(rgb).resize((112, 112), Image.LANCZOS)
+    arr    = np.array(pil, dtype=np.float32) / 255.0
+    arr    = (arr - 0.5) / 0.5                        # [0,1] → [-1,1]
+    return arr.transpose(2, 0, 1)                      # HWC → CHW
 
 
 def _clahe_enhance(bgr: np.ndarray) -> np.ndarray:
-    """CLAHE on luminance — improves detection on dark/washed/low-contrast photos."""
-    lab = cv2.cvtColor(bgr, cv2.COLOR_BGR2LAB)
-    l, a, b = cv2.split(lab)
-    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
-    l_eq = clahe.apply(l)
-    return cv2.cvtColor(cv2.merge([l_eq, a, b]), cv2.COLOR_LAB2BGR)
+    """
+    Apply CLAHE (Contrast-Limited Adaptive Histogram Equalisation) to the
+    luminance channel of a BGR image.
+
+    Why CLAHE?  Face detection fails on dark, backlit, or washed-out photos.
+    CLAHE improves local contrast without globally blowing out highlights.
+
+    Why LAB colour space?  The L channel is pure luminance — enhancing it
+    leaves the colour information (A, B channels) completely untouched,
+    preventing skin-tone shifts.
+
+    clipLimit=2.0  — caps per-tile histogram bin amplification to prevent
+                     noise from being treated as real contrast.
+    tileGridSize=(8,8) — 8×8 tiles for local adaptation; smaller = more
+                         aggressive local correction.
+    """
+    lab             = cv2.cvtColor(bgr, cv2.COLOR_BGR2LAB)
+    l_ch, a_ch, b_ch = cv2.split(lab)
+    clahe           = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+    l_eq            = clahe.apply(l_ch)
+    return cv2.cvtColor(cv2.merge([l_eq, a_ch, b_ch]), cv2.COLOR_LAB2BGR)
 
 
 def _iou(box_a: list, box_b: list) -> float:
-    """IoU between two [x1,y1,x2,y2] boxes."""
-    xa = max(box_a[0], box_b[0]); ya = max(box_a[1], box_b[1])
-    xb = min(box_a[2], box_b[2]); yb = min(box_a[3], box_b[3])
+    """
+    Intersection-over-Union between two [x1, y1, x2, y2] bounding boxes.
+
+    IoU = area(intersection) / area(union)
+
+    Used by _dedup_faces to suppress duplicate face detections across
+    detection scales and the horizontal-flip pass.
+
+    Returns 0.0 if boxes don't overlap.
+    """
+    xa = max(box_a[0], box_b[0])
+    ya = max(box_a[1], box_b[1])
+    xb = min(box_a[2], box_b[2])
+    yb = min(box_a[3], box_b[3])
     inter = max(0, xb - xa) * max(0, yb - ya)
     if inter == 0:
         return 0.0
-    area_a = (box_a[2]-box_a[0]) * (box_a[3]-box_a[1])
-    area_b = (box_b[2]-box_b[0]) * (box_b[3]-box_b[1])
+    area_a = (box_a[2] - box_a[0]) * (box_a[3] - box_a[1])
+    area_b = (box_b[2] - box_b[0]) * (box_b[3] - box_b[1])
     return inter / (area_a + area_b - inter)
 
 
 def _dedup_faces(faces_list: list, iou_thresh: float = IOU_DEDUP_THRESHOLD) -> list:
-    """Remove duplicate detections across scales/flips. Keep highest det_score."""
+    """
+    Non-Maximum Suppression over face detections from multiple scales/flips.
+
+    Algorithm (greedy NMS):
+      1. Sort detections by det_score descending.
+      2. For each face, keep it only if it doesn't overlap (IoU > iou_thresh)
+         with any already-kept face.
+
+    Sorting by confidence first ensures the higher-quality detection "wins"
+    when two boxes refer to the same physical face.
+    """
     if not faces_list:
         return []
     faces_list = sorted(faces_list, key=lambda f: float(f.det_score), reverse=True)
     kept = []
     for face in faces_list:
-        b = face.bbox.astype(int)
+        b   = face.bbox.astype(int)
         box = [b[0], b[1], b[2], b[3]]
-        duplicate = any(_iou(box, [k.bbox.astype(int)[i] for i in range(4)]) > iou_thresh for k in kept)
-        if not duplicate:
+        if not any(_iou(box, [k.bbox.astype(int)[i] for i in range(4)]) > iou_thresh
+                   for k in kept):
             kept.append(face)
     return kept
 
-# ════════════════════════════════════════════════════════════════
-#  AIModelManager — V4
-# ════════════════════════════════════════════════════════════════
+
+# ══════════════════════════════════════════���═════════════════════════
+#  AIModelManager
+# ════════════════════════════════════════════════════════════════════
 
 class AIModelManager:
+    """
+    Loads and manages all AI models at server startup.
+    Thread-safe for the face lane (via _face_lock).
+    Cache-safe for all lanes (via _cache_lock).
+
+    Models loaded:
+      Object lane: SigLIP-base-patch16-224 + DINOv2-base → 1536-D fused
+      Face lane:   InsightFace buffalo_l (SCRFD-10GF + ArcFace-R100) +
+                   optionally AdaFace IR-50 → 1024-D fused
+    """
+
     def __init__(self):
         self.device = (
-            "cuda" if torch.cuda.is_available()
-            else ("mps" if torch.backends.mps.is_available() else "cpu")
+            "cuda"  if torch.cuda.is_available() else
+            "mps"   if torch.backends.mps.is_available() else
+            "cpu"
         )
         print(f"🚀 Loading models onto: {self.device.upper()}...")
 
-        # ── Object Lane: SigLIP + DINOv2 (unchanged) ─────────────
+        # ── Object lane: SigLIP ──────────────────────────────────
         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()
+        self.siglip_model = (
+            AutoModel.from_pretrained("google/siglip-base-patch16-224")
+            .to(self.device).eval()
+        )
 
+        # ── Object lane: DINOv2 ──────────────────────────────────
         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()
+        self.dinov2_model = (
+            AutoModel.from_pretrained("facebook/dinov2-base")
+            .to(self.device).eval()
+        )
 
+        # FP16 halves VRAM usage on CUDA with negligible accuracy loss at inference
         if self.device == "cuda":
             self.siglip_model = self.siglip_model.half()
             self.dinov2_model = self.dinov2_model.half()
 
-        # ── YOLO for object segmentation ─────────────────────────
+        # ── Object lane: YOLO segmentation ──────────────────────
         print("📦 Loading YOLO11n-seg...")
         self.yolo = YOLO("yolo11n-seg.pt")
 
-        # ── 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
-        if INSIGHTFACE_AVAILABLE:
-            try:
-                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=DET_SIZE_PRIMARY,   # 1280×1280 — key for small faces
-                )
-                # 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:
-                print(f"❌ InsightFace init FAILED: {e}")
-                print(traceback.format_exc())
-                self.face_app = None
-        else:
-            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
+        # ── Face lane: InsightFace SCRFD + ArcFace ───────────────
+        # buffalo_l = SCRFD-10GF detector + ArcFace-R100 recogniser.
+        # Always use buffalo_l (not buffalo_sc) — accuracy matters here.
+        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=DET_SIZE_PRIMARY,
+        )
+        # Warmup — pre-allocates ONNX buffers so first real call isn't slow
+        self.face_app.get(np.zeros((112, 112, 3), dtype=np.uint8))
+        print(f"✅ InsightFace loaded | det_size={DET_SIZE_PRIMARY} | gate={FACE_QUALITY_GATE}")
+
+        # ── Face lane: AdaFace (optional) ────────────────────────
         self.adaface_model = None
         self._load_adaface()
 
-        # Thread safety for ONNX
-        self._face_lock     = threading.Lock()
-        self._cache         = {}
-        self._cache_maxsize = 128
-        adaface_status = "FULL FUSION u2705" if self.adaface_model else "ZERO-PADDED u26a0ufe0f  (AdaFace weights missing)"
-        print("")
-        print("u2705 Enterprise Lens V4 u2014 Models Ready")
-        print(f"   Device            : {self.device.upper()}")
-        print(f"   InsightFace       : buffalo_l (SCRFD-10GF + ArcFace-R100)")
-        print(f"   AdaFace           : {adaface_status}")
-        print(f"   Face vector dim   : {FUSED_FACE_DIM}  <- enterprise-faces MUST be {FUSED_FACE_DIM}-D")
-        print(f"   Object vector dim : 1536  <- enterprise-objects MUST be 1536-D")
-        print(f"   Quality gate      : det_score >= {FACE_QUALITY_GATE}, face_px >= {MIN_FACE_SIZE}")
-        print(f"   Detection size    : {DET_SIZE_PRIMARY}")
-        print("")
+        # ── Thread safety ────────────────────────────────────────
+        # _face_lock  : InsightFace ONNX runtime is NOT thread-safe
+        # _cache_lock : protects _cache dict from concurrent read-write-evict
+        self._face_lock  = threading.Lock()
+        self._cache_lock = threading.Lock()
+        self._cache: dict[str, list] = {}
+
+        adaface_status = "FULL FUSION ✅" if self.adaface_model else "ZERO-PADDED ⚠️ (weights missing)"
+        print(
+            f"\n✅ Enterprise Lens V4 — Models Ready\n"
+            f"   Device       : {self.device.upper()}\n"
+            f"   Face vectors : {FUSED_FACE_DIM}-D ({adaface_status})\n"
+            f"   Object vectors: 1536-D (SigLIP+DINOv2)\n"
+            f"   Quality gate : det_score ≥ {FACE_QUALITY_GATE}, face_px ≥ {MIN_FACE_SIZE}\n"
+        )
 
+    # ── AdaFace loader ───────────────────────────────────────────────
     def _load_adaface(self):
         """
-        AdaFace IR-50 MS1MV2 — disabled for now.
-        Face vectors use ArcFace(512) + zeros(512) = 1024-D.
-        This is fully functional — cosine similarity works correctly.
-        Re-enable by setting ENABLE_ADAFACE=1 env var when HF token
-        injection into Docker build is confirmed working.
+        Load AdaFace IR-50 MS1MV2 from HuggingFace.
+        Controlled by ENABLE_ADAFACE env var (default off).
+
+        When disabled: ArcFace(512) + zeros(512) → 1024-D output.
+        Zero-padding is cosine-neutral — the ArcFace half still carries
+        full identity signal; padded zeros don't pull any direction.
+
+        When enabled: ArcFace(512) + AdaFace(512) → 1024-D.
+        AdaFace is quality-adaptive: blurry/low-quality face crops receive
+        downweighted embeddings, improving retrieval precision.
         """
-        enable = os.getenv("ENABLE_ADAFACE", "0").strip() == "1"
-        hf_token_present = bool(os.getenv("HF_TOKEN", "").strip())
-        print(f"   ENABLE_ADAFACE={os.getenv('ENABLE_ADAFACE', 'NOT SET')}")
-        print(f"   HF_TOKEN present={'YES' if hf_token_present else 'NO (not set or empty)'}")
-        if not enable:
-            print("⚠️  AdaFace disabled (ENABLE_ADAFACE != 1) — using ArcFace zero-padded 1024-D")
-            self.adaface_model = None
+        if not ENABLE_ADAFACE:
+            print("⚠️  AdaFace disabled (ENABLE_ADAFACE != 1) — using zero-padded 1024-D")
             return
 
-        # Full loading code kept here for when AdaFace is re-enabled
-        import sys
-        HF_TOKEN   = os.getenv("HF_TOKEN", None)
+        import os, sys
         REPO_ID    = "minchul/cvlface_adaface_ir50_ms1mv2"
         CACHE_PATH = os.path.expanduser("~/.cvlface_cache/minchul/cvlface_adaface_ir50_ms1mv2")
         try:
             from huggingface_hub import hf_hub_download
+            from transformers import AutoModel as _HFAutoModel
+
             print("📦 Loading AdaFace IR-50 MS1MV2...")
             os.makedirs(CACHE_PATH, exist_ok=True)
+
             hf_hub_download(repo_id=REPO_ID, filename="files.txt",
-                token=HF_TOKEN, local_dir=CACHE_PATH, local_dir_use_symlinks=False)
+                            token=HF_TOKEN, local_dir=CACHE_PATH,
+                            local_dir_use_symlinks=False)
             with open(os.path.join(CACHE_PATH, "files.txt")) as f:
                 extra = [x.strip() for x in f.read().split("\n") if x.strip()]
             for fname in extra + ["config.json", "wrapper.py", "model.safetensors"]:
                 fpath = os.path.join(CACHE_PATH, fname)
                 if not os.path.exists(fpath):
                     hf_hub_download(repo_id=REPO_ID, filename=fname,
-                        token=HF_TOKEN, local_dir=CACHE_PATH, local_dir_use_symlinks=False)
+                                    token=HF_TOKEN, local_dir=CACHE_PATH,
+                                    local_dir_use_symlinks=False)
+
             cwd = os.getcwd()
             os.chdir(CACHE_PATH)
             sys.path.insert(0, CACHE_PATH)
             try:
-                from transformers import AutoModel as _HF_AutoModel
-                model = _HF_AutoModel.from_pretrained(
+                model = _HFAutoModel.from_pretrained(
                     CACHE_PATH, trust_remote_code=True, token=HF_TOKEN)
             finally:
                 os.chdir(cwd)
-                if CACHE_PATH in sys.path: sys.path.remove(CACHE_PATH)
+                if CACHE_PATH in sys.path:
+                    sys.path.remove(CACHE_PATH)
+
             model = model.to(self.device).eval()
             with torch.no_grad():
                 out = model(torch.zeros(1, 3, 112, 112).to(self.device))
             emb = out if isinstance(out, torch.Tensor) else out.embedding
-            assert emb.shape[-1] == ADAFACE_DIM
+            assert emb.shape[-1] == ADAFACE_DIM, f"Expected {ADAFACE_DIM}-D, got {emb.shape[-1]}"
+
             self.adaface_model = model
-            print(f"✅ AdaFace IR-50 loaded — 1024-D FULL FUSION active")
+            print("✅ AdaFace IR-50 loaded — 1024-D FULL FUSION active")
+
         except Exception as e:
             print(f"⚠️  AdaFace load failed: {e} — falling back to zero-padded 1024-D")
             self.adaface_model = None
 
-        # ── 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."""
+    # ── AdaFace inference ────────────────────────────────────────────
+    def _adaface_embed(self, face_arr_chw: np.ndarray | None) -> np.ndarray | None:
+        """
+        Run AdaFace on a preprocessed (3, 112, 112) float32 CHW array.
+        Returns a 512-D L2-normalised numpy embedding, or None on failure.
+
+        The cvlface model may return a raw tensor or an object with .embedding —
+        both output formats are handled here.
+        """
+        if self.adaface_model is None or face_arr_chw is None:
+            return None
+        try:
+            t = torch.from_numpy(face_arr_chw).unsqueeze(0).to(self.device)
+            if self.device == "cuda":
+                t = t.half()
+            with torch.no_grad():
+                out = self.adaface_model(t)
+            emb = out if isinstance(out, torch.Tensor) else out.embedding
+            return F.normalize(emb.float(), p=2, dim=1)[0].cpu().numpy()
+        except Exception as e:
+            print(f"⚠️  AdaFace inference error: {e}")
+            return None
+
+    # ── Object lane: batched embedding ──────────────────────────────
+    def _embed_crops_batch(self, crops: list[Image.Image]) -> list[np.ndarray]:
+        """
+        Embed a batch of PIL images through SigLIP and DINOv2, fuse results.
+
+        SigLIP captures semantic/language-aligned meaning ("a red sports car").
+        DINOv2 captures fine-grained visual texture and structure (self-supervised).
+        Fusing both gives vectors that are sensitive to BOTH what something IS
+        and what it LOOKS LIKE — better retrieval than either model alone.
+
+        Why batch?  GPUs process many inputs in parallel almost as fast as one.
+        Why torch.no_grad()?  Skips gradient graph construction — ~30 % faster,
+                              significant memory saving at inference time.
+        Why F.normalize (L2)?  Projects embeddings onto unit sphere.
+                               On the unit sphere: cosine_similarity = dot_product
+                               (cheaper and numerically stable).
+                               Also ensures neither SigLIP nor DINOv2 dominates
+                               the fused vector due to scale differences.
+        """
         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()}
+            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":
                 sig_in = {k: v.half() if v.dtype == torch.float32 else v
                           for k, v in sig_in.items()}
@@ -336,14 +433,12 @@ class AIModelManager:
                 sig_out = sig_out.last_hidden_state[:, 0, :]
             elif isinstance(sig_out, tuple):
                 sig_out = sig_out[0]
-            # sig_out is now a tensor
-            if not isinstance(sig_out, torch.Tensor):
-                sig_out = sig_out[0]
             sig_vecs = F.normalize(sig_out.float(), p=2, dim=1).cpu()
 
-            # 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()}
+            # DINOv2 — [:, 0, :] extracts the [CLS] token which aggregates
+            # the global image representation across the entire sequence
+            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()}
@@ -352,114 +447,88 @@ class AIModelManager:
                 dino_out.last_hidden_state[:, 0, :].float(), p=2, dim=1).cpu()
 
             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))]
 
-    # ── AdaFace embedding for a single face crop ─────────────────
-    def _adaface_embed(self, face_arr_chw: np.ndarray) -> np.ndarray:
-        """
-        Run AdaFace IR-50 MS1MV2 on a preprocessed (3,112,112) float32 array.
-        Input : CHW float32, normalised to [-1, 1]
-        Output: 512-D L2-normalised numpy embedding, or None on failure.
-
-        The cvlface model may return a tensor directly or an object
-        with an .embedding attribute — both cases handled.
-        """
-        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():
-                out = self.adaface_model(t)
-            # Handle both raw tensor and object-with-embedding outputs
-            emb = out if isinstance(out, torch.Tensor) else out.embedding
-            emb = F.normalize(emb.float(), p=2, dim=1)
-            return emb[0].cpu().numpy()
-        except Exception as e:
-            print(f"⚠️  AdaFace inference error: {e}")
-            return None
+        return [fused[i].numpy() for i in range(len(crops))]
 
-    # ── V4 Face detection + dual encoding ────────────────────────
-    def _detect_and_encode_faces(self, img_np: np.ndarray) -> list:
+    # ── Face lane: detection + dual encoding ─────────────────────────
+    def _detect_and_encode_faces(self, img_np: np.ndarray) -> list[dict]:
         """
-        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
+        Detect all faces using InsightFace SCRFD-10GF at multiple scales,
+        encode each face with ArcFace-R100 + AdaFace IR-50, and return
+        1024-D fused vectors.
+
+        Pipeline per face:
+          1. ArcFace-R100 (512-D) from InsightFace's built-in recognition
+          2. AdaFace IR-50 (512-D) from separately loaded model
+          3. Concatenate + L2-normalise → 1024-D final vector
+          4. Quality gates: det_score ≥ FACE_QUALITY_GATE, width ≥ MIN_FACE_SIZE
+
+        Multi-scale strategy:
+          - Run SCRFD at 1280, 960, and 640 px.
+          - Run once more on horizontally flipped image (catches turned faces).
+          - Merge all detections and deduplicate by IoU.
+          Rationale: a face that's 15 px at 640 becomes 30 px at 1280;
+          the detector finds it at the larger scale.
+
+        AdaFace unavailable:
+          Zero-pad to maintain 1024-D. The ArcFace half carries full identity
+          signal; zero padding is cosine-neutral (no direction bias).
+
+        Returns list of dicts:
+          { type, vector (1024-D), face_idx, bbox, face_crop, det_score, face_width_px }
         """
         if self.face_app is None:
-            print("⚠️  face_app is None — InsightFace not loaded")
             return []
 
         try:
-            # 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()
 
-            # ── Preprocessing: CLAHE contrast enhancement ─────────
-            # Helps with dark/overexposed/low-contrast photos
+            # CLAHE: boost contrast on dark/backlit/low-contrast photos
             bgr_enhanced = _clahe_enhance(bgr)
 
-            # ── Multi-scale + flip detection ──────────────────────
-            # Run SCRFD at multiple resolutions AND on horizontally
-            # flipped image. Catches faces that one scale/orientation misses.
-            # Results are merged and deduplicated by IoU.
+            # Multi-scale detection — bboxes are scaled back to original coords
             all_raw_faces = []
             H, W = bgr.shape[:2]
 
             for scale in DET_SCALES:
-                # Resize to this scale for detection
                 scale_w = min(W, scale[0])
                 scale_h = min(H, scale[1])
-                if scale_w == W and scale_h == H:
-                    bgr_scaled = bgr_enhanced
-                else:
-                    bgr_scaled = cv2.resize(bgr_enhanced, (scale_w, scale_h))
-
-                print(f"🔍 SCRFD detection at {scale_w}×{scale_h}...")
-                # Temporarily set det_size for this scale
+                bgr_scaled = (
+                    bgr_enhanced if scale_w == W and scale_h == H
+                    else cv2.resize(bgr_enhanced, (scale_w, scale_h))
+                )
                 try:
                     self.face_app.det_model.input_size = scale
                     with self._face_lock:
                         faces_at_scale = self.face_app.get(bgr_scaled)
-                    # Scale bboxes back to original dimensions
-                    sx = W / scale_w; sy = H / scale_h
+                    sx, sy = W / scale_w, H / scale_h
                     for f in faces_at_scale:
                         if sx != 1.0 or sy != 1.0:
                             f.bbox[0] *= sx; f.bbox[1] *= sy
                             f.bbox[2] *= sx; f.bbox[3] *= sy
                     all_raw_faces.extend(faces_at_scale)
                 except Exception:
-                    pass  # scale failed, continue
+                    pass
 
-            # Horizontal flip pass — catches profile/turned faces
+            # Horizontal-flip pass — catches profile/turned faces
             bgr_flip = cv2.flip(bgr_enhanced, 1)
             try:
                 self.face_app.det_model.input_size = DET_SIZE_PRIMARY
                 with self._face_lock:
                     faces_flip = self.face_app.get(bgr_flip)
-                # Mirror bboxes back to original orientation
                 for f in faces_flip:
                     x1, y1, x2, y2 = f.bbox
-                    f.bbox[0] = W - x2; f.bbox[2] = W - x1
+                    f.bbox[0] = W - x2
+                    f.bbox[2] = W - x1
                 all_raw_faces.extend(faces_flip)
             except Exception:
                 pass
 
-            # Restore primary det_size
+            # Restore primary size
             self.face_app.det_model.input_size = DET_SIZE_PRIMARY
 
-            # Deduplicate across scales and flip
             faces = _dedup_faces(all_raw_faces)
             print(f"   Raw detections: {len(all_raw_faces)} → after dedup: {len(faces)}")
 
@@ -470,7 +539,6 @@ class AIModelManager:
                 if accepted >= MAX_FACES_PER_IMAGE:
                     break
 
-                # ── Bounding box ──────────────────────────────────
                 bbox_raw = face.bbox.astype(int)
                 x1, y1, x2, y2 = bbox_raw
                 x1 = max(0, x1); y1 = max(0, y1)
@@ -479,128 +547,116 @@ class AIModelManager:
                 if w <= 0 or h <= 0:
                     continue
 
-                # ── Quality gate 1: minimum size ──────────────────
+                # Quality gate 1: minimum pixel size
                 if w < MIN_FACE_SIZE or h < MIN_FACE_SIZE:
                     print(f"   Face {idx}: SKIP — too small ({w}×{h}px)")
                     continue
 
-                # ── Quality gate 2: detection confidence ──────────
+                # Quality gate 2: detector 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
 
-                # ── ArcFace embedding (from InsightFace) ──────────
                 if face.embedding is None:
                     continue
+
+                # ArcFace embedding (built into InsightFace buffalo_l)
                 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 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 ─────────────
-                # ALWAYS output FUSED_FACE_DIM (1024) so Pinecone index
-                # dimension never mismatches, regardless of AdaFace status.
+                # Fuse to 1024-D — always output FUSED_FACE_DIM regardless of AdaFace status
                 if adaface_vec is not None:
-                    # Full fusion: ArcFace(512) + AdaFace(512) → 1024-D
                     fused_raw = np.concatenate([arcface_vec, adaface_vec])
                 else:
-                    # AdaFace unavailable — pad with zeros to maintain 1024-D
-                    # The ArcFace half still carries full identity signal;
-                    # zero padding is neutral and doesn't corrupt similarity.
-                    print("   ⚠️  AdaFace unavailable — padding to 1024-D")
                     fused_raw = np.concatenate([arcface_vec,
                                                 np.zeros(ADAFACE_DIM, dtype=np.float32)])
-                n2 = np.linalg.norm(fused_raw)
+                n2        = np.linalg.norm(fused_raw)
                 final_vec = (fused_raw / n2) if n2 > 0 else fused_raw
-                vec_dim   = FUSED_FACE_DIM   # always 1024
 
-                # ── Face crop thumbnail for UI ─────────────────────
                 face_crop_b64 = _crop_to_b64(bgr, x1, y1, x2, y2)
 
                 results.append({
-                    "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),
+                    "type":          "face",
+                    "vector":        final_vec,
+                    "face_idx":      accepted,
+                    # bbox exposed so the frontend can draw boxes on the query image
+                    "bbox":          [int(x1), int(y1), int(w), int(h)],
+                    "face_crop":     face_crop_b64,
+                    "det_score":     det_score,
+                    "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"   Face {idx}: ✅ ACCEPTED — {w}×{h}px | det={det_score:.3f}")
 
             print(f"👤 {accepted} face(s) passed quality gate")
             return results
 
         except Exception as e:
-            print(f"🟠 InsightFace error: {e}")
-            print(traceback.format_exc()[-600:])
+            print(f"🟠 InsightFace error: {e}\n{traceback.format_exc()[-600:]}")
             return []
 
-    # ── Main process_image ────────────────────────────────────────
+    # ── Main pipeline ────────────────────────────────────────────────
     def process_image(
         self,
-        image_path: str,
-        is_query:     bool = False,
+        image_path:   str,
         detect_faces: bool = True,
-    ) -> list:
+    ) -> list[dict]:
         """
-        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
+        Full inference pipeline for a single image.
+
+        Always runs both lanes:
+          Face   → list of { type:"face",   vector(1024-D), face_idx, bbox,
+                              face_crop, det_score, face_width_px }
+          Object → list of { type:"object", vector(1536-D) }
+
+        main.py decides which lane's results to use for Pinecone operations
+        based on the endpoint context (upload stores both; search can use both).
+
+        Cache strategy:
+          Key = (md5_of_first_64KB, detect_faces)
+          Hit  → return cached result immediately (skips all model inference)
+          Miss → run pipeline, cache result, evict LRU entry if over capacity
+
+          Cache is protected by _cache_lock (threading.Lock) to prevent race
+          conditions when MAX_CONCURRENT_INFERENCES > 1.
         """
-        cache_key = f"{_img_hash(image_path)}_{detect_faces}_{is_query}"
-        if cache_key in self._cache:
-            print("⚡ Cache hit")
-            return self._cache[cache_key]
+        cache_key = f"{img_hash(image_path)}_{detect_faces}"
+
+        with self._cache_lock:
+            if cache_key in self._cache:
+                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, full resolution
         faces_found  = False
 
-        # ════════════════════════════════════════════════════════
-        # 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).
-        # ════════════════════════════════════════════════════════
+        # ── Face lane ────────────────────────────────────────────
         if detect_faces and self.face_app is not None:
-            # Multi-scale + CLAHE + flip all handled inside _detect_and_encode_faces
-            # Pass the full-resolution image — internal scaling handles the rest
             face_results = self._detect_and_encode_faces(img_np)
-
             if face_results:
                 faces_found = True
-                for fr in face_results:
-                    extracted.append(fr)
-
-        # ════════════════════════════════════════════════════════
-        # 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)
+                extracted.extend(face_results)
+
+        # ── Object lane ──────────────────────────────────────────
+        # Always runs, even when faces are found.
+        # Person-class YOLO crops are skipped when face lane is active
+        # to avoid embedding the same person twice.
+        #
+        # Crop 0 is always the full (resized) image — ensures we always
+        # have at least one embedding even if YOLO finds nothing.
+        # YOLO is given the already-loaded PIL image to avoid re-reading
+        # the file from disk.
+        crops: list[Image.Image] = []
+        yolo_results = self.yolo(original_pil, conf=YOLO_CONF_THRESHOLD, verbose=False)
 
         for r in yolo_results:
             if r.masks is not None:
@@ -612,11 +668,10 @@ class AIModelManager:
                     if len(polygon) < 3:
                         continue
                     x, y, w, h = cv2.boundingRect(polygon)
-                    if w < 30 or h < 30:
+                    if w < YOLO_MIN_CROP_PX or h < YOLO_MIN_CROP_PX:
                         continue
-                    crop = original_pil.crop((x, y, x + w, y + h))
-                    crops_pil.append(crop)
-                    if len(crops_pil) >= MAX_CROPS + 1:
+                    crops.append(original_pil.crop((x, y, x + w, y + h)))
+                    if len(crops) >= MAX_CROPS:
                         break
             elif r.boxes is not None:
                 for box in r.boxes:
@@ -624,33 +679,46 @@ class AIModelManager:
                     if faces_found and cls_id == YOLO_PERSON_CLASS_ID:
                         continue
                     x1, y1, x2, y2 = box.xyxy[0].tolist()
-                    if (x2 - x1) < 30 or (y2 - y1) < 30:
+                    if (x2 - x1) < YOLO_MIN_CROP_PX or (y2 - y1) < YOLO_MIN_CROP_PX:
                         continue
-                    crop = original_pil.crop((x1, y1, x2, y2))
-                    crops_pil.append(crop)
-            if len(crops_pil) >= MAX_CROPS + 1:
+                    crops.append(original_pil.crop((x1, y1, x2, y2)))
+            if len(crops) >= MAX_CROPS:
                 break
 
-        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})
+        # Prepend the full image as crop 0, then resize ALL crops uniformly.
+        # (Previously the full image was pre-resized before appending, causing
+        # _resize_pil to be called on it twice. Now we resize everything once.)
+        all_crops = [original_pil] + crops
+        all_crops = [_resize_pil(c, MAX_IMAGE_SIZE) for c in all_crops]
+
+        print(f"🧠 Embedding {len(all_crops)} object crop(s)...")
+        obj_vecs = self._embed_crops_batch(all_crops)
+        extracted.extend({"type": "object", "vector": v} for v in obj_vecs)
+
+        # Cache with lock — prevents concurrent writes from corrupting eviction
+        with self._cache_lock:
+            if len(self._cache) >= INFERENCE_CACHE_SIZE:
+                # Evict LRU entry (first inserted key in plain dict = oldest)
+                oldest = next(iter(self._cache))
+                del self._cache[oldest]
+            self._cache[cache_key] = extracted
 
-        # Cache
-        if len(self._cache) >= self._cache_maxsize:
-            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,
         detect_faces: bool = True,
-    ) -> list:
+    ) -> list[dict]:
+        """
+        Async wrapper for process_image — offloads blocking inference to a
+        thread-pool executor so FastAPI's event loop remains responsive.
+
+        functools.partial is used instead of a lambda to make the call
+        picklable, which some executor backends require.
+        """
         loop = asyncio.get_event_loop()
         return await loop.run_in_executor(
             None,
-            functools.partial(self.process_image, image_path, is_query, detect_faces),
+            functools.partial(self.process_image, image_path, detect_faces),
         )