Create config.py

src/config.py

@@ -0,0 +1,172 @@
+"""
+src/config.py — Single source of truth for every constant and environment variable.
+
+Rules:
+  - No magic numbers anywhere else in the codebase.
+  - Every threshold, dimension, and limit is documented here with the reason it exists.
+  - Environment variables are loaded once at startup; never call os.getenv() elsewhere.
+"""
+
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+# ════════════════════════════════════════════════════════════════════
+#  ENVIRONMENT VARIABLES
+# ════════════════════════════════════════════════════════════════════
+
+DEFAULT_PINECONE_KEY   = os.getenv("DEFAULT_PINECONE_KEY",   "")
+DEFAULT_CLOUDINARY_URL = os.getenv("DEFAULT_CLOUDINARY_URL", "")
+SUPABASE_URL           = os.getenv("SUPABASE_URL",           "")
+SUPABASE_SERVICE_KEY   = os.getenv("SUPABASE_SERVICE_KEY",   "")
+HF_TOKEN               = os.getenv("HF_TOKEN",               "")
+
+# Set ENABLE_ADAFACE=1 to enable full ArcFace+AdaFace 1024-D fusion.
+# When disabled, ArcFace(512) + zeros(512) = 1024-D (fully functional,
+# zero-padding is cosine-neutral and doesn't corrupt similarity scores).
+ENABLE_ADAFACE = os.getenv("ENABLE_ADAFACE", "0").strip() == "1"
+
+# InsightFace ONNX runtime is NOT thread-safe. Keep at 1 unless you
+# switch to a thread-safe inference backend (e.g. Triton, torchserve).
+MAX_CONCURRENT_INFERENCES = int(os.getenv("MAX_CONCURRENT_INFERENCES", "1"))
+
+
+# ════════════════════════════════════════════════════════════════════
+#  PINECONE INDEX NAMES
+# ════════════════════════════════════════════════════════════════════
+
+IDX_FACES   = "enterprise-faces"
+IDX_OBJECTS = "enterprise-objects"
+
+
+# ════════════════════════════════════════════════════════════════════
+#  VECTOR DIMENSIONS
+#  These MUST match the Pinecone index dimensions.
+#  If you change a dimension you MUST reset the corresponding index.
+# ════════════════════════════════════════════════════════════════════
+
+FACE_DIM       = 512   # ArcFace-R100 raw output
+ADAFACE_DIM    = 512   # AdaFace IR-50 raw output
+FUSED_FACE_DIM = 1024  # concat(ArcFace, AdaFace) → stored in enterprise-faces
+
+SIGLIP_DIM    = 768    # google/siglip-base-patch16-224 output
+DINOV2_DIM    = 768    # facebook/dinov2-base CLS token output
+FUSED_OBJ_DIM = 1536   # concat(SigLIP, DINOv2) → stored in enterprise-objects
+
+# Allow env-var overrides in case the index was created at different dims
+IDX_FACES_DIM   = int(os.getenv("IDX_FACES_DIM",   str(FUSED_FACE_DIM)))
+IDX_OBJECTS_DIM = int(os.getenv("IDX_OBJECTS_DIM", str(FUSED_OBJ_DIM)))
+
+
+# ════════════════════════════════════════════════════════════════════
+#  OBJECT LANE — YOLO + EMBEDDING
+# ════════════════════════════════════════════════════════════════════
+
+# Longest edge of an image before embedding.
+# 640px balances accuracy vs GPU memory; SigLIP/DINOv2 were pretrained at 224px
+# so going above ~640 yields diminishing returns.
+MAX_IMAGE_SIZE = 640
+
+# Max YOLO segmentation crops per image (full image is always crop 0).
+# Beyond ~6 crops the embeddings become redundant and slow down inference.
+MAX_CROPS = 6
+
+YOLO_PERSON_CLASS_ID = 0    # COCO class 0 = "person"
+YOLO_MIN_CROP_PX     = 30   # ignore detections smaller than 30×30 px
+YOLO_CONF_THRESHOLD  = 0.5  # YOLO confidence gate
+
+
+# ════════════════════════════════════════════════════════════════════
+#  FACE LANE — DETECTION
+# ════════════════════════════════════════════════════════════════════
+
+# Multi-scale pyramid: SCRFD runs at each resolution, results are merged
+# and deduplicated by IoU. Larger scales catch smaller faces.
+# DET_SIZE_PRIMARY is the InsightFace prep() size; the others are used
+# by temporarily overriding det_model.input_size mid-pipeline.
+DET_SIZE_PRIMARY   = (1280, 1280)
+DET_SIZE_SECONDARY = (960,  960)
+DET_SIZE_FALLBACK  = (640,  640)
+DET_SCALES         = [DET_SIZE_PRIMARY, DET_SIZE_SECONDARY, DET_SIZE_FALLBACK]
+
+# Suppress duplicate detections across scales/flips.
+# IoU > 0.45 → same face detected twice; keep the higher-confidence one.
+IOU_DEDUP_THRESHOLD = 0.45
+
+
+# ════════════════════════════════════════════════════════════════════
+#  FACE LANE — QUALITY GATES (applied during detection/encoding)
+# ════════════════════════════════════════════════════════════════════
+
+# Faces smaller than this (in either dimension) carry too little information
+# for a reliable 512-D embedding.
+MIN_FACE_SIZE = 20  # px
+
+# Hard limit on faces stored per source image.
+MAX_FACES_PER_IMAGE = 12
+
+# InsightFace det_score gate. Lowered from 0.60 to accept partially
+# occluded faces, angles, sunglasses, and smiles.
+FACE_QUALITY_GATE = 0.35
+
+
+# ════════════════════════════════════════════════════════════════════
+#  FACE LANE — SEARCH THRESHOLDS (applied to Pinecone cosine scores)
+#  These are separate from FACE_QUALITY_GATE (which gates detection).
+#  These gate how similar a stored face must be to the query face.
+# ════════════════════════════════════════════════════════════════════
+
+# det_score ≥ 0.85 → high-quality frontal face → use stricter match threshold
+FACE_DET_SCORE_HQ_SPLIT = 0.85
+FACE_THRESHOLD_HIGH     = 0.40   # for high-quality faces
+FACE_THRESHOLD_LOW      = 0.32   # for lower-quality faces
+
+FACE_TOP_K_FETCH = 50  # fetch more candidates then filter; multi-face merge needs headroom
+
+
+# ════════════════════════════════════════════════════════════════════
+#  OBJECT LANE — SEARCH THRESHOLDS
+# ════════════════════════════════════════════════════════════════════
+
+OBJECT_SCORE_THRESHOLD = 0.45
+OBJECT_TOP_K           = 10
+
+
+# ════════════════════════════════════════════════════════════════════
+#  FACE CROP THUMBNAILS
+#  Stored in Pinecone metadata as base64 JPEG for UI display.
+# ════════════════════════════════════════════════════════════════════
+
+FACE_CROP_THUMB_SIZE = 112   # px — matches face model input size
+FACE_CROP_QUALITY    = 80    # JPEG quality; balances size vs clarity
+FACE_CROP_PADDING    = 0.20  # 20% padding around tight bbox for UI legibility
+ADAFACE_CROP_PADDING = 0.10  # 10% padding for model input (wants tight crop)
+
+
+# ════════════════════════════════════════════════════════════════════
+#  API LIMITS
+# ════════════════════════════════════════════════════════════════════
+
+# Hard cap on files per upload request. Each file spawns concurrent
+# Cloudinary + AI tasks; uncapped batches can exhaust RAM.
+MAX_FILES_PER_UPLOAD = 20
+
+
+# ════════════════════════════════════════════════════════════════════
+#  LRU PINECONE CLIENT POOL
+# ════════════════════════════════════════════════════════════════════
+
+# Each Pinecone() client holds open TCP connections.
+# Too many exhaust file descriptors; 64 covers typical multi-tenant load.
+PINECONE_POOL_MAX = 64
+
+
+# ════════════════════════════════════════════════════════════════════
+#  IN-MEMORY INFERENCE CACHE
+# ═══════════════════════════════════════════════════════════���════════
+
+# Cache keyed by (file_hash, detect_faces). 128 entries ≈ last ~128 unique
+# images; prevents re-running multi-second AI inference on duplicate uploads.
+INFERENCE_CACHE_SIZE = 128