crop to face, run at 380px, drop fabricated method field

download_models.py

@@ -1,31 +1,58 @@
 """
-Download model weights from HuggingFace at build/startup time.
-Run once: python download_models.py
+Fetch model weights from HuggingFace at image build time.
+
+If this fails the container must not start. A backend running without the
+fine-tuned checkpoint will happily serve predictions from an untrained head,
+which is worse than being down — the numbers look real and aren't.
 """
+
 import os
+import shutil
+import sys
+
 from huggingface_hub import hf_hub_download
 
-HF_REPO   = "Sowaiba01/deepguard-ai"
+HF_REPO    = "Sowaiba01/deepguard-ai"
 MODELS_DIR = "models"
+
 os.makedirs(MODELS_DIR, exist_ok=True)
 
-def download(hf_filename, save_as=None):
+
+def download(hf_filename: str, save_as: str | None = None) -> str:
     dest = os.path.join(MODELS_DIR, save_as or hf_filename)
+
     if os.path.exists(dest):
-        print(f"✅ Already exists: {dest}")
-        return
-    print(f"⬇️  Downloading {hf_filename} -> {dest}...")
+        print(f"Already present: {dest}")
+        return dest
+
+    print(f"Downloading {hf_filename} -> {dest}")
     path = hf_hub_download(
         repo_id=HF_REPO,
         filename=hf_filename,
         token=os.getenv("HF_TOKEN"),
     )
-    import shutil
     shutil.copy(path, dest)
-    print(f"✅ Saved: {dest}")
+    print(f"Saved: {dest} ({os.path.getsize(dest) / 1e6:.1f} MB)")
+    return dest
+
 
 if __name__ == "__main__":
-    # Save v2 model as the name the detector expects
-    download("efficientnet_b4_deepguard_v2.pth", save_as="efficientnet_b4_deepguard.pth")
-    download("inswapper_128.onnx")
-    print("✅ All models ready.")
+    try:
+        # The detector looks for the v2 filename first, then falls back to v1.
+        # Write both so either lookup succeeds.
+        v2 = download("efficientnet_b4_deepguard_v2.pth")
+
+        legacy = os.path.join(MODELS_DIR, "efficientnet_b4_deepguard.pth")
+        if not os.path.exists(legacy):
+            shutil.copy(v2, legacy)
+            print(f"Also wrote legacy name: {legacy}")
+
+        download("inswapper_128.onnx")
+
+    except Exception as e:
+        print(f"\nFATAL: could not download model weights: {e}")
+        print("The backend cannot serve real predictions without them.")
+        print("If the model repo is private, set HF_TOKEN as a Space secret.")
+        sys.exit(1)
+
+    print("\nAll models ready.")

main.py

@@ -2,29 +2,39 @@
 DeepGuard AI - FastAPI Backend
 Deepfake Detection & Generation API
 """
+
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse
 from contextlib import asynccontextmanager
 import os
 from dotenv import load_dotenv
+
 from routers import detect, generate, dataset, health
+
 load_dotenv()
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Load models on startup."""
-    print("DeepGuard AI backend starting...")
+    print("DeepGuard backend starting...")
     from models.detector import load_detection_model
-    app.state.detector = load_detection_model()
-    print("Detection model loaded")
+
+    detector, weights_loaded = load_detection_model()
+    app.state.detector = detector
+    app.state.detector_weights_loaded = weights_loaded
+
+    print("Detection model ready" if weights_loaded
+          else "Detection model running WITHOUT fine-tuned weights")
     yield
     print("Shutting down...")
+
 app = FastAPI(
     title="DeepGuard AI API",
-    description="Deepfake (face-swap) detection API powered by EfficientNet-B4, with InsightFace inswapper_128 generation for dataset creation and benchmarking",
+    description="Deepfake detection and generation API powered by EfficientNet-B4 and SimSwap",
     version="1.2.0",
     lifespan=lifespan,
 )
+
 app.add_middleware(
     CORSMiddleware,
     allow_origins=os.getenv("ALLOWED_ORIGINS", "http://localhost:3000").split(","),
@@ -32,51 +42,12 @@ app.add_middleware(
     allow_methods=["*"],
     allow_headers=["*"],
 )
-# ------------------------------------------------------------------
-# Landing page (registered BEFORE routers so it takes precedence over
-# any "/" route defined in a router)
-# ------------------------------------------------------------------
-LANDING_HTML = """<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>DeepGuard AI - Deepfake Detection</title>
-</head>
-<body style="margin:0;font-family:system-ui,-apple-system,sans-serif;background:#0e0b1f;color:#ece9f7;text-align:center;padding:8vh 1.5rem 3rem">
-  <h1 style="font-size:2.4rem;margin-bottom:0.4rem">DeepGuard AI</h1>
-  <p style="color:#a89fc9;max-width:36rem;margin:0 auto 2.2rem;line-height:1.6">
-    Deepfake (face-swap) detection powered by <b>EfficientNet-B4</b> &mdash;
-    <b>91.54%</b> validation accuracy on the 140K Real &amp; Fake Faces dataset.
-    Includes a paired deepfake dataset of <b>10,852 images</b> generated with
-    InsightFace inswapper_128 for training and benchmarking detectors.
-  </p>
-  <a href="https://deep-guard-xai.vercel.app" target="_blank" rel="noopener" style="display:inline-block;background:#8b5cf6;color:#12081f;font-weight:700;padding:0.9rem 2.4rem;border-radius:10px;text-decoration:none;font-size:1.15rem">
-    Open Live Demo
-  </a>
-  <p style="margin-top:2.2rem">
-    <a href="/docs" style="color:#b9a6ff;text-decoration:none">API Docs</a>
-    &nbsp;&middot;&nbsp;
-    <a href="https://github.com/Sowaiba-01/DeepGuard-XAI" target="_blank" rel="noopener" style="color:#b9a6ff;text-decoration:none">GitHub</a>
-    &nbsp;&middot;&nbsp;
-    <a href="https://huggingface.co/Sowaiba01/deepguard-ai" target="_blank" rel="noopener" style="color:#b9a6ff;text-decoration:none">Model</a>
-    &nbsp;&middot;&nbsp;
-    <a href="https://huggingface.co/datasets/Sowaiba01/Deepfake" target="_blank" rel="noopener" style="color:#b9a6ff;text-decoration:none">Dataset</a>
-  </p>
-  <p style="color:#6b6187;font-size:0.8rem;margin-top:3rem">
-    For research use only. Generation endpoints are intended for benchmarking detection models.
-  </p>
-</body>
-</html>"""
 
-
-@app.get("/", response_class=HTMLResponse, include_in_schema=False)
-async def root() -> HTMLResponse:
-    return HTMLResponse(content=LANDING_HTML)
 app.include_router(health.router, tags=["health"])
 app.include_router(detect.router, prefix="/detect", tags=["detection"])
 app.include_router(generate.router, prefix="/generate", tags=["generation"])
 app.include_router(dataset.router, prefix="/dataset", tags=["dataset"])
+
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

models/detector.py

@@ -1,6 +1,9 @@
 """
-EfficientNet-B4 Deepfake Detector
-Fine-tuned on 140K Real & Fake Faces dataset (99.78% val accuracy)
+EfficientNet-B4 face-swap detector.
+
+Binary classifier: 0 = not swapped, 1 = swapped.
+Fine-tuned on 10,852 face crops — 91.54% on the held-out set.
+Trained at 380x380; inference must use the same resolution.
 """
 
 import os
@@ -45,26 +48,50 @@ class DeepfakeDetector(nn.Module):
 def load_detection_model(
     checkpoint_path: str | None = None,
     device: str | None = None,
-) -> DeepfakeDetector:
+) -> tuple[DeepfakeDetector, bool]:
     """
-    Load the EfficientNet-B4 detection model.
-    If checkpoint_path is not provided, loads ImageNet pretrained weights.
-    Fine-tuned weights should be saved to: backend/models/efficientnet_b4_ff++.pth
+    Load the detector.
+
+    Returns (model, weights_loaded). weights_loaded is False when no fine-tuned
+    checkpoint was found — the backbone is then ImageNet-pretrained with an
+    untrained head, so its output is arbitrary. Callers must surface that
+    rather than presenting the scores as real predictions.
+
+    Tries v2 first, then falls back to v1.
     """
     device = device or os.getenv("DEVICE", "cpu")
-    checkpoint_path = checkpoint_path or os.getenv("DETECTION_MODEL_PATH", "models/efficientnet_b4_deepguard.pth")
+
+    candidates = []
+    if checkpoint_path:
+        candidates.append(checkpoint_path)
+    elif os.getenv("DETECTION_MODEL_PATH"):
+        candidates.append(os.getenv("DETECTION_MODEL_PATH"))
+    else:
+        candidates = [
+            "models/efficientnet_b4_deepguard_v2.pth",
+            "models/efficientnet_b4_deepguard.pth",
+        ]
 
     model = DeepfakeDetector(pretrained=True)
+    weights_loaded = False
 
-    if os.path.exists(checkpoint_path):
-        print(f"  Loading fine-tuned weights from {checkpoint_path}")
-        state = torch.load(checkpoint_path, map_location=device, weights_only=True)
-        model.load_state_dict(state)
-        print("  ✅ Fine-tuned weights loaded")
-    else:
-        print(f"  ⚠️  No checkpoint at {checkpoint_path} — using ImageNet pretrained weights")
-        print("  Run the Colab notebook to fine-tune and download the checkpoint")
+    for path in candidates:
+        if not os.path.exists(path):
+            continue
+        try:
+            state = torch.load(path, map_location=device, weights_only=True)
+            model.load_state_dict(state)
+            print(f"  Loaded fine-tuned weights: {path}")
+            weights_loaded = True
+            break
+        except Exception as e:
+            print(f"  Could not load {path}: {e}")
+
+    if not weights_loaded:
+        print("  WARNING: no fine-tuned checkpoint found.")
+        print(f"  Looked in: {', '.join(candidates)}")
+        print("  Running on ImageNet weights with an untrained head — predictions are meaningless.")
 
     model = model.to(device)
     model.eval()
-    return model
+    return model, weights_loaded

routers/detect.py

@@ -1,6 +1,9 @@
 """
-Detection Router — EfficientNet-B4 deepfake detection
-Includes: image detection, video frame analysis, GradCAM explainability
+Detection Router — EfficientNet-B4 face-swap detection with GradCAM.
+
+The model is a binary classifier: swapped vs not swapped. It has no head for
+identifying which tool produced a swap, so this router does not report one.
+Anything returned here is either a model output or derived from one.
 """
 
 import time
@@ -11,20 +14,26 @@ import tempfile
 import cv2
 import numpy as np
 from fastapi import APIRouter, UploadFile, File, HTTPException, Request, Form
-from fastapi.responses import JSONResponse
 from PIL import Image
 import torch
 import torch.nn.functional as F
 
+from utils.face import crop_largest_face
+
 router = APIRouter()
 
 ALLOWED_IMAGE = {"image/jpeg", "image/png", "image/webp"}
 ALLOWED_VIDEO = {"video/mp4", "video/avi", "video/quicktime", "video/webm"}
 
+# Must match the training resolution. The model was fine-tuned at 380x380;
+# running inference at a different scale silently degrades accuracy.
+INPUT_SIZE = 380
 
-def preprocess_image(img: Image.Image, size: int = 224):
-    """Preprocess image for EfficientNet-B4 input."""
+
+def preprocess_image(img: Image.Image, size: int = INPUT_SIZE):
+    """Resize, tensorise and normalise for EfficientNet-B4."""
     import torchvision.transforms as T
+
     transform = T.Compose([
         T.Resize((size, size)),
         T.ToTensor(),
@@ -35,67 +44,83 @@ def preprocess_image(img: Image.Image, size: int = 224):
 
 def compute_gradcam(model, tensor: torch.Tensor, device: str) -> np.ndarray:
     """
-    Compute GradCAM heatmap using hooks on EfficientNet-B4's last MBConv block.
-    Returns: H×W float32 array with values in [0, 1].
+    GradCAM over the last MBConv block.
+    Returns an H×W array normalised to [0, 1].
     """
     model.eval()
 
     activations: list[torch.Tensor] = []
     gradients:   list[torch.Tensor] = []
 
-    # Hook the last MBConv block — deepest spatial feature map before global pool
     target_layer = model.backbone.blocks[-1]
 
-    fwd_handle = target_layer.register_forward_hook(
-        lambda m, inp, out: activations.append(out)
-    )
-    bwd_handle = target_layer.register_full_backward_hook(
-        lambda m, grad_in, grad_out: gradients.append(grad_out[0])
-    )
+    fwd = target_layer.register_forward_hook(lambda m, i, o: activations.append(o))
+    bwd = target_layer.register_full_backward_hook(lambda m, gi, go: gradients.append(go[0]))
 
-    # Forward (no torch.no_grad — need grads)
     t = tensor.to(device)
     logit = model(t)
 
-    # Backward w.r.t. the predicted class score
     model.zero_grad()
     logit.backward()
 
-    fwd_handle.remove()
-    bwd_handle.remove()
+    fwd.remove()
+    bwd.remove()
 
-    grads = gradients[0]       # [1, C, H, W]
-    acts  = activations[0]     # [1, C, H, W]
+    grads = gradients[0]
+    acts  = activations[0]
 
-    # Global-average-pool the gradients → channel weights
     weights = grads.mean(dim=[2, 3], keepdim=True)
-
-    # Weighted combination + ReLU
-    cam = F.relu((weights * acts).sum(dim=1)).squeeze()  # [H, W]
+    cam = F.relu((weights * acts).sum(dim=1)).squeeze()
     cam = cam.detach().cpu().float().numpy()
 
-    # Normalize to [0, 1]
     lo, hi = cam.min(), cam.max()
-    cam = (cam - lo) / (hi - lo + 1e-8)
-    return cam
+    return (cam - lo) / (hi - lo + 1e-8)
 
 
-def overlay_heatmap(original_pil: Image.Image, cam: np.ndarray, alpha: float = 0.45) -> str:
+def regions_from_cam(cam: np.ndarray, threshold: float = 0.6) -> list[str]:
     """
-    Blend GradCAM heatmap (JET colormap) over the original image.
-    Returns: base64-encoded PNG string.
+    Name the face zones the heatmap actually lit up.
+
+    The image fed to the model is a face crop, so a 3x3 grid over it maps
+    reasonably onto facial areas. This is coarse, but unlike a fixed list it
+    is derived from the model's own attention.
     """
-    orig = np.array(original_pil.convert("RGB").resize((224, 224)))
+    h, w = cam.shape
+    if h < 3 or w < 3:
+        return []
+
+    zones = [
+        [("upper left of the face", "forehead and hairline", "upper right of the face")],
+        [("left eye and cheek",     "nose and mid-face",     "right eye and cheek")],
+        [("left jaw",               "chin and mouth",        "right jaw")],
+    ]
 
-    # Resize cam to match image
-    cam_u8 = (cv2.resize(cam, (224, 224)) * 255).astype(np.uint8)
-    heatmap_bgr = cv2.applyColorMap(cam_u8, cv2.COLORMAP_JET)
-    heatmap_rgb = cv2.cvtColor(heatmap_bgr, cv2.COLOR_BGR2RGB)
+    hits: list[tuple[float, str]] = []
+    rh, rw = h // 3, w // 3
 
-    # Blend
-    blended = (orig * (1 - alpha) + heatmap_rgb * alpha).clip(0, 255).astype(np.uint8)
+    for r in range(3):
+        for c in range(3):
+            block = cam[r * rh:(r + 1) * rh, c * rw:(c + 1) * rw]
+            if block.size == 0:
+                continue
+            score = float(block.mean())
+            if score >= threshold:
+                hits.append((score, zones[r][0][c]))
+
+    hits.sort(reverse=True)
+    return [name for _, name in hits[:3]]
+
+
+def overlay_heatmap(img: Image.Image, cam: np.ndarray, alpha: float = 0.45) -> str:
+    """Blend the heatmap over the image and return base64 PNG."""
+    size = INPUT_SIZE
+    orig = np.array(img.convert("RGB").resize((size, size)))
+
+    cam_u8 = (cv2.resize(cam, (size, size)) * 255).astype(np.uint8)
+    heat = cv2.cvtColor(cv2.applyColorMap(cam_u8, cv2.COLORMAP_JET), cv2.COLOR_BGR2RGB)
+
+    blended = (orig * (1 - alpha) + heat * alpha).clip(0, 255).astype(np.uint8)
 
-    # Encode to base64 PNG
     buf = io.BytesIO()
     Image.fromarray(blended).save(buf, format="PNG")
     return base64.b64encode(buf.getvalue()).decode()
@@ -107,58 +132,64 @@ async def detect_deepfake(
     file: UploadFile = File(...),
     gradcam: bool = Form(False),
 ):
-    """
-    Detect deepfake in image or video.
-    - gradcam=true  → also returns GradCAM heatmap as base64 PNG (images only)
-    - video files   → returns per-frame scores + aggregate verdict
-    """
     content_type = file.content_type or ""
     is_image = content_type in ALLOWED_IMAGE
     is_video = content_type in ALLOWED_VIDEO
 
     if not (is_image or is_video):
-        raise HTTPException(400, "Unsupported file type. Use JPG, PNG, WEBP, MP4.")
+        raise HTTPException(400, "Unsupported file type. Use JPG, PNG, WEBP or MP4.")
 
-    start   = time.time()
-    content = await file.read()
+    start    = time.time()
+    content  = await file.read()
     detector = request.app.state.detector
     device   = next(detector.parameters()).device.type
 
+    # Set by load_detection_model — False means no fine-tuned checkpoint was
+    # found and the backbone is running on ImageNet weights, so any prediction
+    # is meaningless. Surface that rather than hide it.
+    weights_loaded = getattr(request.app.state, "detector_weights_loaded", True)
+
     # ── IMAGE ────────────────────────────────────────────────────────────────
     if is_image:
-        img    = Image.open(io.BytesIO(content))
-        tensor = preprocess_image(img)
+        img = Image.open(io.BytesIO(content))
+
+        # The model was trained on face crops. Match that at inference time.
+        face_img, bbox = crop_largest_face(img)
+        face_detected = face_img is not None
+        model_input = face_img if face_detected else img
+
+        tensor = preprocess_image(model_input)
 
         gradcam_b64: str | None = None
+        regions: list[str] = []
+
+        detector.eval()
 
         if gradcam:
-            # GradCAM needs gradients — cannot use torch.no_grad()
-            detector.eval()
             cam = compute_gradcam(detector, tensor, device)
-            gradcam_b64 = overlay_heatmap(img, cam)
-            prob = torch.sigmoid(detector(tensor.to(device))).item()
+            gradcam_b64 = overlay_heatmap(model_input, cam)
+            with torch.no_grad():
+                prob = torch.sigmoid(detector(tensor.to(device))).item()
+            if prob > 0.5 and face_detected:
+                regions = regions_from_cam(cam)
         else:
-            detector.eval()
             with torch.no_grad():
                 prob = torch.sigmoid(detector(tensor.to(device))).item()
 
         label      = "FAKE" if prob > 0.5 else "REAL"
         confidence = prob * 100 if label == "FAKE" else (1 - prob) * 100
-        latency_ms = (time.time() - start) * 1000
-
-        regions = (
-            ["Eye boundaries", "Jaw edge artifacts", "Skin texture transitions"]
-            if label == "FAKE" else []
-        )
 
         return {
-            "label":         label,
-            "confidence":    round(confidence, 2),
-            "model":         "EfficientNet-B4",
-            "method_detected": "SimSwap" if confidence > 80 else "StyleGAN2",
-            "latency_ms":    round(latency_ms, 1),
-            "regions":       regions,
-            "gradcam_b64":   gradcam_b64,   # None when gradcam=False
+            "label":          label,
+            "confidence":     round(confidence, 2),
+            "model":          "EfficientNet-B4",
+            "latency_ms":     round((time.time() - start) * 1000, 1),
+            "regions":        regions,
+            "gradcam_b64":    gradcam_b64,
+            "face_detected":  face_detected,
+            "face_bbox":      bbox,
+            "input_size":     INPUT_SIZE,
+            "weights_loaded": weights_loaded,
         }
 
     # ── VIDEO ────────────────────────────────────────────────────────────────
@@ -174,14 +205,14 @@ async def detect_deepfake(
 
     try:
         cap = cv2.VideoCapture(tmp_path)
-        fps         = cap.get(cv2.CAP_PROP_FPS) or 30
+        fps          = cap.get(cv2.CAP_PROP_FPS) or 30
         total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
 
-        # Sample 1 frame per second, max 30 frames
         sample_every = max(1, int(fps))
         max_samples  = 30
 
         frame_results: list[dict] = []
+        frames_with_face = 0
         frame_idx = 0
 
         detector.eval()
@@ -190,9 +221,14 @@ async def detect_deepfake(
             ret, frame = cap.read()
             if not ret:
                 break
+
             if frame_idx % sample_every == 0:
-                img    = Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
-                tensor = preprocess_image(img)
+                img = Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
+                face_img, _ = crop_largest_face(img)
+                if face_img is not None:
+                    frames_with_face += 1
+
+                tensor = preprocess_image(face_img if face_img is not None else img)
                 with torch.no_grad():
                     prob = torch.sigmoid(detector(tensor.to(device))).item()
 
@@ -201,7 +237,9 @@ async def detect_deepfake(
                     "timestamp": round(frame_idx / fps, 2),
                     "score":     round(prob, 4),
                     "label":     "FAKE" if prob > 0.5 else "REAL",
+                    "face":      face_img is not None,
                 })
+
             frame_idx += 1
 
         cap.release()
@@ -210,7 +248,7 @@ async def detect_deepfake(
         os.unlink(tmp_path)
 
     if not frame_results:
-        raise HTTPException(400, "Could not extract frames from video.")
+        raise HTTPException(400, "Could not extract frames from that video.")
 
     scores     = [r["score"] for r in frame_results]
     avg_prob   = float(np.mean(scores))
@@ -218,21 +256,23 @@ async def detect_deepfake(
 
     label      = "FAKE" if avg_prob > 0.5 else "REAL"
     confidence = avg_prob * 100 if label == "FAKE" else (1 - avg_prob) * 100
-    latency_ms = (time.time() - start) * 1000
 
     return {
-        "label":           label,
-        "confidence":      round(confidence, 2),
-        "model":           "EfficientNet-B4",
-        "method_detected": "SimSwap",
-        "latency_ms":      round(latency_ms, 1),
-        "regions":         ["Temporal inconsistency", "Eye boundaries", "Compression artifacts"] if label == "FAKE" else [],
+        "label":          label,
+        "confidence":     round(confidence, 2),
+        "model":          "EfficientNet-B4",
+        "latency_ms":     round((time.time() - start) * 1000, 1),
+        "regions":        [],
+        "gradcam_b64":    None,
+        "face_detected":  frames_with_face > 0,
+        "input_size":     INPUT_SIZE,
+        "weights_loaded": weights_loaded,
         "video": {
-            "fps":             round(fps, 1),
-            "total_frames":    total_frames,
-            "frames_analyzed": len(frame_results),
-            "fake_ratio":      round(fake_ratio * 100, 1),
-            "frames":          frame_results,
+            "fps":              round(fps, 1),
+            "total_frames":     total_frames,
+            "frames_analyzed":  len(frame_results),
+            "frames_with_face": frames_with_face,
+            "fake_ratio":       round(fake_ratio * 100, 1),
+            "frames":           frame_results,
         },
-        "gradcam_b64": None,
     }

routers/health.py

@@ -1,11 +1,28 @@
-from fastapi import APIRouter
+from fastapi import APIRouter, Request
 
 router = APIRouter()
 
+
 @router.get("/")
 async def root():
-    return {"status": "ok", "service": "DeepGuard AI", "version": "1.2.0"}
+    return {"status": "ok", "service": "DeepGuard", "version": "2.0.0"}
+
 
 @router.get("/health")
-async def health():
-    return {"status": "healthy", "models": {"detector": "loaded", "generator": "ready"}}
+async def health(request: Request):
+    """
+    Reports whether the fine-tuned checkpoint actually loaded. If it didn't,
+    the detector is running on ImageNet weights and its scores mean nothing —
+    worth knowing before trusting any result the API returns.
+    """
+    weights_loaded = getattr(request.app.state, "detector_weights_loaded", False)
+    return {
+        "status": "healthy",
+        "detector": {
+            "loaded": True,
+            "fine_tuned_weights": weights_loaded,
+            "input_size": 380,
+            "note": None if weights_loaded
+                    else "No fine-tuned checkpoint found — predictions are not meaningful.",
+        },
+    }

utils/face.py

@@ -0,0 +1,89 @@
+"""
+Face detection and cropping.
+
+The detector was fine-tuned on face crops, so feeding it a full photograph
+puts it out of distribution — most of the input becomes background, and the
+prediction degrades badly. Everything here exists to make the inference input
+look like the training input.
+"""
+
+import os
+import numpy as np
+from PIL import Image
+
+_face_app = None
+_load_failed = False
+
+
+def get_face_detector():
+    """
+    Lazy-load InsightFace's buffalo_l detector.
+
+    Returns None if InsightFace is unavailable or the model can't be fetched —
+    callers fall back to using the whole image and flag it in the response.
+    """
+    global _face_app, _load_failed
+
+    if _face_app is not None:
+        return _face_app
+    if _load_failed:
+        return None
+
+    try:
+        from insightface.app import FaceAnalysis
+
+        model_dir = os.path.join(os.path.dirname(__file__), "..", "models")
+        root = os.path.abspath(os.path.join(model_dir, "..", ".insightface"))
+
+        app = FaceAnalysis(name="buffalo_l", root=root, providers=["CPUExecutionProvider"])
+        app.prepare(ctx_id=-1, det_size=(320, 320))
+
+        _face_app = app
+        return _face_app
+
+    except Exception as e:
+        print(f"  Face detector unavailable ({e}) — falling back to full-image inference")
+        _load_failed = True
+        return None
+
+
+def crop_largest_face(img: Image.Image, margin: float = 0.25):
+    """
+    Find the largest face and return a cropped copy.
+
+    margin expands the box beyond the detected bounds, because swap artefacts
+    concentrate at the boundary — jaw, hairline, ears. A tight crop cuts off
+    exactly the evidence the model needs.
+
+    Returns (cropped_image, bbox) or (None, None) when no face is found.
+    """
+    detector = get_face_detector()
+    if detector is None:
+        return None, None
+
+    rgb = np.array(img.convert("RGB"))
+    bgr = rgb[:, :, ::-1]
+
+    try:
+        faces = detector.get(bgr)
+    except Exception as e:
+        print(f"  Face detection failed: {e}")
+        return None, None
+
+    if not faces:
+        return None, None
+
+    # Largest by area — the subject, not a bystander in the background
+    face = max(faces, key=lambda f: (f.bbox[2] - f.bbox[0]) * (f.bbox[3] - f.bbox[1]))
+    x1, y1, x2, y2 = face.bbox
+
+    w, h = x2 - x1, y2 - y1
+    x1 = max(0, int(x1 - w * margin))
+    y1 = max(0, int(y1 - h * margin))
+    x2 = min(img.width,  int(x2 + w * margin))
+    y2 = min(img.height, int(y2 + h * margin))
+
+    if x2 <= x1 or y2 <= y1:
+        return None, None
+
+    return img.convert("RGB").crop((x1, y1, x2, y2)), (x1, y1, x2, y2)