chopped

Dockerfile

@@ -2,7 +2,7 @@ FROM python:3.11-slim
 
 # System deps for OpenCV and MediaPipe
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 wget \
+    libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 wget unzip \
     libegl1 libgles2 libgomp1 \
     g++ && \
     rm -rf /var/lib/apt/lists/*
@@ -14,13 +14,25 @@ COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
 # Pre-download MediaPipe model at build time so first request is fast.
-# All other models (FairFace, SegFormer, HSEmotion, ObstructionViT,
-# HairTypeViT) are pulled from Hugging Face on first request and cached
-# in /root/.cache/huggingface for the rest of the process lifetime.
+# Hugging Face models (Ethnicity ViT, SegFormer, HSEmotion, ObstructionViT,
+# HairTypeViT) and the InsightFace buffalo_l bundle are pulled lazily on
+# first request and cached in /root/.cache for the lifetime of the
+# container.
 RUN mkdir -p models && \
     wget -q -O models/face_landmarker.task \
     "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/latest/face_landmarker.task"
 
+# Pre-download InsightFace buffalo_l bundle (detection + recognition +
+# age + gender + landmarks) so the first /analyze call doesn't pay the
+# ~280MB download. The bundle auto-extracts under ~/.insightface/models/
+# on first use.
+RUN mkdir -p /root/.insightface/models && \
+    wget -q -O /root/.insightface/models/buffalo_l.zip \
+    "https://github.com/deepinsight/insightface/releases/download/v0.7/buffalo_l.zip" && \
+    cd /root/.insightface/models && unzip -q buffalo_l.zip -d buffalo_l && rm buffalo_l.zip
+
+# unzip wasn't in the system deps; add it via the apt block at the top.
+
 COPY . .
 
 EXPOSE 7860

README.md

@@ -10,26 +10,33 @@ pinned: false
 
 # HCP Face Analysis Microservice
 
-FastAPI service that runs seven specialized analyzers over a single photo
-and returns a merged dictionary of ~100 facial attributes.
+FastAPI service that runs ten specialised analyzers over a single
+photo and returns a merged dictionary of facial attributes plus a
+face-recognition embedding and an aesthetic "chopped score."
 
 ## Models
 
 | # | Component | Model | Task | Size |
 |---|-----------|-------|------|------|
-| 1 | MediaPipe Face Landmarker | `face_landmarker.task` (Google) | 478 3D landmarks + 52 ARKit blendshapes — geometric features, smiling, mouth-open | ~4 MB |
-| 2 | FairFace age | `dima806/fairface_age_image_detection` (ViT-B/16) | 9-bucket age → softmax-weighted continuous estimate | ~340 MB |
-| 2 | FairFace gender | `dima806/fairface_gender_image_detection` (ViT-B/16) | Binary gender (~93.4% acc) | ~340 MB |
-| 2 | Ethnicity | `cledoux42/Ethnicity_Test_v003` (ViT) | 5-class ethnicity (~79.6% acc) | ~340 MB |
-| 3 | Human parsing | `matei-dorian/segformer-b5-finetuned-human-parsing` | 18-class pixel segmentation → masks + hair length + hat | ~340 MB |
-| 4 | Emotion | HSEmotion `enet_b0_8_best_afew` (EfficientNet-B0) | 8-class emotion + valence/arousal | ~20 MB |
-| 5 | Color analysis | (no model — OpenCV LAB/HSV) | Skin tone, hair color, eye color, lip color | 0 MB |
-| 6 | Obstruction | `dima806/face_obstruction_image_detection` (ViT-B/16) | glasses / sunglasses / mask (~99% precision) | ~340 MB |
-| 7 | Hair type | `dima806/hair_type_image_detection` (ViT-B/16) | curly/dreadlocks/kinky/straight/wavy (~93% acc) | ~340 MB |
-
-All analyzers are lazy-loaded on first request. The MediaPipe weight
-file is pre-downloaded at Docker build time; all Hugging Face models
-are cached on first inference.
+| 1 | InsightFace | `buffalo_l` (SCRFD + ArcFace ResNet50, ONNX) | Detection + 512-d recognition embedding + age + gender + 106 landmarks (99.83% LFW) | ~280 MB |
+| 2 | MediaPipe Face Landmarker | `face_landmarker.task` (Google) | 478 3D landmarks + 52 ARKit blendshapes — geometric features, smiling, mouth-open | ~4 MB |
+| 3 | Ethnicity | `cledoux42/Ethnicity_Test_v003` (ViT) | 5-class ethnicity (~79.6% acc) | ~340 MB |
+| 4 | Human parsing | `matei-dorian/segformer-b5-finetuned-human-parsing` | 18-class pixel segmentation → masks + hair length + hat | ~340 MB |
+| 5 | Emotion | HSEmotion `enet_b0_8_best_afew` (EfficientNet-B0) | 8-class emotion + valence/arousal | ~20 MB |
+| 6 | Color analysis | (no model — OpenCV LAB/HSV) | Skin tone, hair color, eye color, lip color | 0 MB |
+| 7 | Obstruction | `dima806/face_obstruction_image_detection` (ViT-B/16) | glasses / sunglasses / mask (~99% precision) | ~340 MB |
+| 8 | Hair type | `dima806/hair_type_image_detection` (ViT-B/16) | curly/dreadlocks/kinky/straight/wavy (~93% acc) | ~340 MB |
+| 9 | Beauty regression | timm ResNet-50, fine-tuned on SCUT-FBP5500 | 1.0–5.0 beauty score (~Pearson r ≥ 0.85 expected) | ~100 MB |
+| 10 | Aesthetic aggregator | (no model — Python rules) | Combines learned beauty + heuristic factors → chopped_score (0–100) | 0 MB |
+
+InsightFace `buffalo_l` is pre-downloaded at Docker build time. The
+MediaPipe weight file is pre-downloaded too. All Hugging Face models
+lazy-load on first inference and cache locally for the lifetime of
+the process. The SCUT-FBP5500-trained beauty regressor must be
+produced via [`training/beauty/`](../training/beauty/) — until you
+drop weights in `models/beauty_regressor.pt` (or set
+`BEAUTY_HF_REPO_ID`), `beauty_score` returns null and the chopped
+score uses heuristics only.
 
 ## API endpoints
 
@@ -46,5 +53,5 @@ curl -X POST https://YOUR-SPACE.hf.space/analyze-base64 \
   -d '{"image": "<base64-encoded-image>"}'
 ```
 
-See [architecture.md](./architecture.md) for the pipeline diagram and the
-full per-attribute model attribution table.
+See [architecture.md](./architecture.md) for the pipeline diagram and
+the full per-attribute → source map.

analyzers/aesthetic_analyzer.py

@@ -0,0 +1,220 @@
+"""
+AestheticAnalyzer — "chopped score" aggregator.
+
+What it does
+------------
+Reads the merged result dict from every other analyzer and produces a
+single numeric "chopped score" plus a per-factor breakdown. Higher
+score = more chopped = less conventionally attractive (by the
+arbitrary rubric encoded here). The breakdown lets you tune weights
+or flip polarity client-side without rerunning inference.
+
+Score composition
+-----------------
+The final chopped_score is a weighted blend of two sources:
+
+1. **Learned beauty regressor** (from BeautyAnalyzer, trained on
+   SCUT-FBP5500): a number in [1.0, 5.0] reflecting averaged human
+   ratings. We rescale to a 0–100 unattractiveness axis. This is the
+   dominant signal when available — heavy weight (default 0.7).
+
+2. **Rule-based factor sum**: penalties for asymmetry, wrinkles,
+   uneven skin, freckles, and asymmetric smile; bonuses for defined
+   jawline, prominent cheekbones, clear skin, balanced lips, and
+   dimples. Each factor is documented in `_compute_rule_score`.
+   This is the only signal when the regressor isn't loaded
+   (BeautyAnalyzer returns None).
+
+Blend math
+----------
+    if beauty_score available:
+        chopped = 0.7 * (100 - beauty_norm) + 0.3 * rule_score
+    else:
+        chopped = rule_score
+    chopped is clamped to [0, 100].
+
+Subjectivity disclaimer
+-----------------------
+Every weight in this file is a guess. "Beauty" is subjective, culturally
+biased, and reductive. Treat the score as an in-joke metric; never
+expose it as objective truth. The UI gates the row behind a
+Settings toggle off-by-default for that reason.
+
+Note: this analyzer takes no image input — it reads the merged result
+dict produced by every other analyzer that ran ahead of it.
+"""
+
+from typing import Any
+
+
+# How much weight the learned beauty regressor gets when both signals
+# are available. The rule-based sum gets the rest (1 - this).
+LEARNED_WEIGHT = 0.7
+
+# Baseline score. Penalties push up, bonuses pull down.
+BASELINE = 50.0
+
+
+class AestheticAnalyzer:
+    def __init__(self):
+        # No model to load.
+        pass
+
+    def analyze(self, merged: dict[str, Any]) -> dict[str, Any]:
+        """Compute chopped score from the merged result dict.
+
+        Unusual signature: not (img_rgb), since this analyzer aggregates
+        prior results rather than running inference on the image.
+        app.py special-cases the call to pass `merged` here.
+        """
+        rule_score, breakdown = self._compute_rule_score(merged)
+
+        beauty_norm = merged.get("beauty_score_norm")
+        if beauty_norm is not None:
+            # Beauty regressor: 0 = ugly, 100 = beautiful (per SCUT-FBP5500
+            # scaling). Flip to unattractiveness axis: 100 - x.
+            learned_unattractive = 100.0 - float(beauty_norm)
+            chopped = (
+                LEARNED_WEIGHT * learned_unattractive
+                + (1.0 - LEARNED_WEIGHT) * rule_score
+            )
+            breakdown["learned_unattractive"] = round(
+                LEARNED_WEIGHT * learned_unattractive - LEARNED_WEIGHT * BASELINE, 2
+            )
+            breakdown["_blend_weight_learned"] = LEARNED_WEIGHT
+        else:
+            chopped = rule_score
+            breakdown["_blend_weight_learned"] = 0.0
+
+        chopped = max(0.0, min(100.0, chopped))
+
+        return {
+            "chopped_score": round(chopped, 1),
+            "chopped_breakdown": breakdown,
+            "chopped_polarity_note": (
+                "0 = least chopped, 100 = most chopped. "
+                "Subtract from 100 for an 'attractiveness' read."
+            ),
+        }
+
+    # ------------------------------------------------------------------
+    # Rule-based scoring
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _compute_rule_score(d: dict[str, Any]) -> tuple[float, dict[str, float]]:
+        """Hand-tuned weighted sum over previously-extracted attributes.
+
+        Returns (score, breakdown_dict). The breakdown gives each factor's
+        signed contribution so a UI can show *why* a score landed where
+        it did. Score starts at BASELINE (50) and moves up/down.
+        """
+        score = BASELINE
+        breakdown: dict[str, float] = {}
+
+        # ── Penalties (push score up = more chopped) ─────────────────
+
+        # Facial asymmetry: 0 = perfectly symmetric, 1 = very asymmetric.
+        # MediaPipe `facial_asymmetry_score` is already in this range.
+        asym = d.get("facial_asymmetry_score")
+        if isinstance(asym, (int, float)):
+            penalty = float(asym) * 18.0
+            score += penalty
+            breakdown["asymmetry_penalty"] = round(penalty, 2)
+
+        # Wrinkle level from SegFormer + OpenCV Laplacian classification.
+        wrinkle_penalty_map = {
+            "smooth": 0.0, "slight": 4.0, "moderate": 8.0, "prominent": 12.0,
+        }
+        wrinkle = d.get("wrinkle_level")
+        if wrinkle in wrinkle_penalty_map:
+            penalty = wrinkle_penalty_map[wrinkle]
+            score += penalty
+            breakdown["wrinkle_penalty"] = penalty
+
+        # Skin uniformity = LAB L* std-dev over the face mask. Higher
+        # std means uneven tone (shadows, blemishes). Scale up to +8.
+        uniformity = d.get("skin_uniformity")
+        if isinstance(uniformity, (int, float)) and uniformity > 0:
+            # Empirically, uniformity in clean skin is ~8-15; very uneven
+            # skin pushes into the 20-30 range.
+            penalty = min(8.0, max(0.0, (float(uniformity) - 10.0) * 0.5))
+            score += penalty
+            breakdown["skin_unevenness_penalty"] = round(penalty, 2)
+
+        # Freckles/moles bucket.
+        freckle_penalty_map = {"none": 0.0, "few": 1.0, "some": 3.0, "many": 5.0}
+        freckles = d.get("freckles_or_moles")
+        if freckles in freckle_penalty_map:
+            penalty = freckle_penalty_map[freckles]
+            score += penalty
+            breakdown["freckles_penalty"] = penalty
+
+        # Smile asymmetry: 0 = perfectly symmetric smile, larger = lopsided.
+        smile_asym = d.get("smile_asymmetry")
+        if isinstance(smile_asym, (int, float)):
+            penalty = min(6.0, float(smile_asym) * 30.0)
+            score += penalty
+            breakdown["smile_asymmetry_penalty"] = round(penalty, 2)
+
+        # Photo-quality penalty: sunglasses/mask hide features and the
+        # model is guessing more. Mild penalty, not a personal trait.
+        if d.get("wearing_sunglasses") or d.get("wearing_mask"):
+            score += 5.0
+            breakdown["obstruction_penalty"] = 5.0
+
+        # ── Bonuses (pull score down = less chopped) ─────────────────
+
+        # Defined jawline. Two signals (string bucket + numeric angle);
+        # take the stronger of the two contributions.
+        jaw_bonus = 0.0
+        jaw_type = d.get("jawline_type")
+        jaw_type_bonus_map = {"sharp": -10.0, "strong": -6.0, "soft": 0.0}
+        if jaw_type in jaw_type_bonus_map:
+            jaw_bonus = jaw_type_bonus_map[jaw_type]
+        jaw_angle = d.get("jawline_angle")
+        if isinstance(jaw_angle, (int, float)) and jaw_angle < 115:
+            # Sharp angles add more on top of the categorical signal.
+            jaw_bonus = min(jaw_bonus, -10.0)
+        if jaw_bonus:
+            score += jaw_bonus
+            breakdown["jaw_definition_bonus"] = round(jaw_bonus, 2)
+
+        # Cheekbone prominence.
+        cheek_bonus_map = {"high": -7.0, "moderate": -3.0, "flat": 0.0}
+        cheek = d.get("cheekbone_prominence")
+        if cheek in cheek_bonus_map:
+            bonus = cheek_bonus_map[cheek]
+            score += bonus
+            breakdown["cheekbone_bonus"] = bonus
+
+        # Skin clarity bonus when the texture score is low (i.e. smooth skin).
+        # skin_texture_score is the same Laplacian-density value used by
+        # wrinkle_level; ≤4 is "smooth" territory.
+        texture = d.get("skin_texture_score")
+        if isinstance(texture, (int, float)) and 0 < texture <= 4:
+            score -= 9.0
+            breakdown["skin_clarity_bonus"] = -9.0
+
+        # Lip fullness — "average" and "full" both read as healthy.
+        lip = d.get("lip_fullness")
+        if lip in {"average", "full"}:
+            score -= 5.0
+            breakdown["lip_fullness_bonus"] = -5.0
+
+        # Defined cupid's bow.
+        if d.get("cupids_bow") == "defined":
+            score -= 3.0
+            breakdown["cupids_bow_bonus"] = -3.0
+
+        # Normal eye spacing.
+        if d.get("eye_spacing") == "average":
+            score -= 4.0
+            breakdown["eye_spacing_bonus"] = -4.0
+
+        # Dimples — small bonus when the MediaPipe heuristic fires.
+        if d.get("possible_dimples"):
+            score -= 3.0
+            breakdown["dimples_bonus"] = -3.0
+
+        return score, breakdown

analyzers/beauty_analyzer.py

@@ -0,0 +1,172 @@
+"""
+BeautyAnalyzer — learned facial-beauty regression on SCUT-FBP5500.
+
+Model
+-----
+- Architecture : timm ResNet-50 with a single-output regression head
+                 (output value in the SCUT-FBP5500 1.0–5.0 score range,
+                 averaged from 60 human raters per image).
+- Dataset      : SCUT-FBP5500 (5,500 faces, gender + race balanced).
+                 https://github.com/HCIILAB/SCUT-FBP5500-Database-Release
+- Trained by   : the user, via the training kit at `training/beauty/`.
+- Expected MAE : ~0.25–0.30 on the standard test split; Pearson r ≥ 0.85.
+- License      : training data is research-only; the trained weights
+                 you produce are yours to license as you choose.
+
+Weight loading
+--------------
+Two ways the analyzer finds weights, tried in order:
+1. Local file at `models/beauty_regressor.pt` (drop in after training).
+2. Hugging Face Hub repo, controlled by `BEAUTY_HF_REPO_ID` env var
+   (e.g. `your-username/scut-fbp5500-resnet50`), loaded via
+   huggingface_hub.hf_hub_download.
+
+If neither resolves, the analyzer logs a warning and returns
+`beauty_score: None`, which AestheticAnalyzer detects and falls back
+to the pure rule-based chopped score.
+
+Inputs
+------
+img_rgb : np.ndarray (H, W, 3) uint8
+
+Outputs (dict)
+--------------
+beauty_score          : float in [1.0, 5.0] (SCUT-FBP5500 native range)
+                        or None if no model is available
+beauty_score_norm     : float in [0.0, 100.0] (linearly rescaled)
+beauty_model_source   : "local" | "huggingface" | "unavailable"
+"""
+
+import os
+from typing import Any
+
+import numpy as np
+from PIL import Image
+
+try:
+    import torch
+    import timm
+    from torchvision import transforms
+    HAS_TORCH = True
+except ImportError:
+    HAS_TORCH = False
+
+
+LOCAL_WEIGHTS_PATH = os.environ.get(
+    "BEAUTY_WEIGHTS_PATH", "models/beauty_regressor.pt"
+)
+HF_REPO_ID = os.environ.get("BEAUTY_HF_REPO_ID")  # e.g. "user/scut-fbp5500-resnet50"
+HF_FILENAME = os.environ.get("BEAUTY_HF_FILENAME", "beauty_regressor.pt")
+BACKBONE = os.environ.get("BEAUTY_BACKBONE", "resnet50")
+
+# Standard ImageNet stats — SCUT-FBP5500 fine-tunes from ImageNet-pretrained
+# backbones so we use the same normalisation at inference time.
+IMAGENET_MEAN = [0.485, 0.456, 0.406]
+IMAGENET_STD = [0.229, 0.224, 0.225]
+
+
+class BeautyAnalyzer:
+    def __init__(self):
+        self.device = (
+            torch.device("cuda" if torch.cuda.is_available() else "cpu")
+            if HAS_TORCH else None
+        )
+        self.model = None
+        self.source = "unavailable"
+        self.transform = None
+
+        if not HAS_TORCH:
+            print(
+                "[BeautyAnalyzer] torch / timm not installed — beauty_score "
+                "will be None and AestheticAnalyzer will fall back to rules."
+            )
+            return
+
+        weights_path = self._resolve_weights_path()
+        if weights_path is None:
+            print(
+                "[BeautyAnalyzer] No trained weights found at "
+                f"{LOCAL_WEIGHTS_PATH} and BEAUTY_HF_REPO_ID is unset. "
+                "Train one via `training/beauty/train.py` and drop the "
+                ".pt into face-service/models/, or set BEAUTY_HF_REPO_ID."
+            )
+            return
+
+        try:
+            # Build backbone with a single regression output. Matches the
+            # training script's architecture exactly — see
+            # training/beauty/train.py.
+            self.model = timm.create_model(BACKBONE, pretrained=False, num_classes=1)
+            state = torch.load(weights_path, map_location=self.device)
+            # Support both bare state_dicts and {"state_dict": ...} wrappers.
+            if isinstance(state, dict) and "state_dict" in state:
+                state = state["state_dict"]
+            self.model.load_state_dict(state, strict=True)
+            self.model.to(self.device).eval()
+
+            # SCUT-FBP5500 standard inference transform: 224×224, ImageNet norm.
+            self.transform = transforms.Compose([
+                transforms.Resize((224, 224)),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=IMAGENET_MEAN, std=IMAGENET_STD),
+            ])
+            print(
+                f"[BeautyAnalyzer] Loaded {BACKBONE} weights from "
+                f"{weights_path} (source={self.source})"
+            )
+        except Exception as exc:
+            print(f"[BeautyAnalyzer] Failed to load beauty model: {exc}")
+            self.model = None
+
+    @staticmethod
+    def _resolve_weights_path() -> str | None:
+        """Local file wins, HF Hub is the fallback."""
+        if os.path.exists(LOCAL_WEIGHTS_PATH):
+            return LOCAL_WEIGHTS_PATH
+        if HF_REPO_ID:
+            try:
+                from huggingface_hub import hf_hub_download
+                return hf_hub_download(repo_id=HF_REPO_ID, filename=HF_FILENAME)
+            except Exception as exc:
+                print(f"[BeautyAnalyzer] HF Hub download failed: {exc}")
+        return None
+
+    def _set_source(self, source: str) -> None:
+        self.source = source
+
+    def analyze(self, img_rgb: np.ndarray) -> dict[str, Any]:
+        if self.model is None or self.transform is None:
+            return self._empty_result()
+
+        try:
+            pil = Image.fromarray(img_rgb).convert("RGB")
+            tensor = self.transform(pil).unsqueeze(0).to(self.device)
+            # Wrap inference in no_grad to save memory; HAS_TORCH is
+            # guaranteed True here because self.model wouldn't exist
+            # otherwise.
+            with torch.no_grad():
+                raw = self.model(tensor).squeeze().item()  # scalar in ~[1, 5]
+        except Exception as exc:
+            print(f"[BeautyAnalyzer] Inference failed: {exc}")
+            return self._empty_result()
+
+        # Clamp to SCUT-FBP5500's nominal 1–5 range; out-of-range outputs
+        # mean the regressor's extrapolating beyond its training labels.
+        score = max(1.0, min(5.0, float(raw)))
+
+        # Linear rescale to 0–100 for downstream display. 1.0 → 0, 5.0 → 100.
+        norm = (score - 1.0) / 4.0 * 100.0
+
+        return {
+            "beauty_score": round(score, 3),
+            "beauty_score_norm": round(norm, 1),
+            "beauty_model_source": self.source or "local",
+        }
+
+    @staticmethod
+    def _empty_result() -> dict[str, Any]:
+        return {
+            "beauty_score": None,
+            "beauty_score_norm": None,
+            "beauty_model_source": "unavailable",
+        }

analyzers/demographic_analyzer.py

@@ -1,227 +0,0 @@
-"""
-DemographicAnalyzer — age, gender, ethnicity via three ViT classifiers.
-
-Models
-------
-- Age       : dima806/fairface_age_image_detection
-              ViT-B/16, ~59% top-1 on FairFace 9 age buckets.
-- Gender    : dima806/fairface_gender_image_detection
-              ViT-B/16, ~93.4% on FairFace.
-- Ethnicity : cledoux42/Ethnicity_Test_v003
-              ViT, 79.6% accuracy, macro-F1 0.797. 5-class output that
-              we widen into the legacy 7-bucket FairFace schema so the
-              rest of the app's distribution shape doesn't change.
-
-All three are Apache 2.0 and Hugging Face image-classification pipelines.
-
-Inputs
-------
-img_rgb : np.ndarray (H, W, 3) uint8
-
-Outputs (dict)
---------------
-age_range, age_estimate (softmax-weighted continuous), age_confidence,
-age_distribution, gender, gender_confidence, ethnicity,
-ethnicity_confidence, ethnicity_distribution.
-
-Notes
------
-The FairFace age model is a 9-bucket classifier (0-2, 3-9, …, 70+),
-which means the argmax bucket midpoint is always one of nine fixed
-numbers (24.5 for 20-29, etc.). To recover a smooth continuous estimate
-we compute the expected value across the full softmax — see
-``_weighted_age_estimate``.
-"""
-
-from typing import Any
-
-from PIL import Image
-from transformers import pipeline
-
-
-AGE_MODEL_ID = "dima806/fairface_age_image_detection"
-GENDER_MODEL_ID = "dima806/fairface_gender_image_detection"
-RACE_MODEL_ID = "cledoux42/Ethnicity_Test_v003"
-
-AGE_LABELS = ["0-2", "3-9", "10-19", "20-29", "30-39", "40-49", "50-59", "60-69", "70+"]
-GENDER_LABELS = ["Male", "Female"]
-# cledoux42 ships 5 classes (african, asian, caucasian, hispanic, indian),
-# but we keep the legacy 7-bucket FairFace label space internally so the
-# downstream distribution dict shape stays stable. Unseen buckets stay 0.
-RACE_LABELS = ["White", "Black", "Latino_Hispanic", "East Asian", "Southeast Asian", "Indian", "Middle Eastern"]
-
-
-class DemographicAnalyzer:
-    def __init__(self):
-        # Each classifier is a HF image-classification pipeline. They lazy
-        # download weights from HF on first instantiation and cache them
-        # under /root/.cache/huggingface inside the container.
-        self.age_classifier = self._load_classifier(AGE_MODEL_ID)
-        self.gender_classifier = self._load_classifier(GENDER_MODEL_ID)
-        self.race_classifier = self._load_classifier(RACE_MODEL_ID)
-
-    @staticmethod
-    def _load_classifier(model_id: str):
-        """Build one HF image-classification pipeline, logging on failure.
-
-        A failed load returns None so the rest of the service continues
-        to function and `analyze()` falls back to "unknown" demographics.
-        """
-        try:
-            return pipeline("image-classification", model=model_id)
-        except Exception as exc:
-            print(f"[DemographicAnalyzer] Failed to load '{model_id}': {exc}")
-            return None
-
-    def analyze(self, img_rgb) -> dict[str, Any]:
-        # Convert the numpy frame to a PIL Image once and reuse it for
-        # all three classifier calls.
-        pil = Image.fromarray(img_rgb)
-
-        # top_k=len(labels) so we get the full softmax for each model.
-        # We need the full age distribution to compute the weighted
-        # expected-value age estimate.
-        age_predictions = self._safe_predict(self.age_classifier, pil, top_k=len(AGE_LABELS))
-        gender_predictions = self._safe_predict(self.gender_classifier, pil, top_k=2)
-        race_predictions = self._safe_predict(self.race_classifier, pil, top_k=7)
-
-        # If every classifier failed we degrade gracefully with a stub.
-        if not age_predictions and not gender_predictions and not race_predictions:
-            return {
-                "age_range": "unknown",
-                "age_estimate": 0.0,
-                "age_confidence": 0.0,
-                "gender": "unknown",
-                "gender_confidence": 0.0,
-                "ethnicity": "unknown",
-                "ethnicity_confidence": 0.0,
-                "age_distribution": {label: 0.0 for label in AGE_LABELS},
-                "ethnicity_distribution": {label: 0.0 for label in RACE_LABELS},
-            }
-
-        # HF pipelines return predictions pre-sorted by score descending,
-        # so prediction[0] is always the argmax class.
-        age_prediction = age_predictions[0] if age_predictions else {"label": "unknown", "score": 0.0}
-        gender_prediction = gender_predictions[0] if gender_predictions else {"label": "unknown", "score": 0.0}
-        race_prediction = race_predictions[0] if race_predictions else {"label": "unknown", "score": 0.0}
-
-        # Models occasionally return label aliases ("more than 70" instead
-        # of "70+", "African" instead of "Black"). The normalisers map
-        # everything back to our canonical schema.
-        age_label = self._normalize_age_label(age_prediction["label"])
-        gender_label = self._normalize_gender_label(gender_prediction["label"])
-        race_label = self._normalize_race_label(race_prediction["label"])
-
-        return {
-            "age_range": age_label,
-            "age_estimate": self._weighted_age_estimate(age_predictions),
-            "age_confidence": round(float(age_prediction["score"]), 3),
-            "gender": gender_label.lower(),
-            "gender_confidence": round(float(gender_prediction["score"]), 3),
-            "ethnicity": race_label,
-            "ethnicity_confidence": round(float(race_prediction["score"]), 3),
-            "age_distribution": self._distribution_map(age_predictions, self._normalize_age_label, AGE_LABELS),
-            "ethnicity_distribution": self._distribution_map(race_predictions, self._normalize_race_label, RACE_LABELS),
-        }
-
-    @staticmethod
-    def _normalize_age_label(label: str) -> str:
-        """Map model output to canonical AGE_LABELS entry."""
-        normalized = label.strip().lower()
-        if normalized == "more than 70":
-            return "70+"
-        return AGE_LABELS[AGE_LABELS.index(label)] if label in AGE_LABELS else label
-
-    @staticmethod
-    def _normalize_gender_label(label: str) -> str:
-        normalized = label.strip().lower()
-        if normalized in {"male", "female"}:
-            return normalized.capitalize()
-        return label
-
-    @staticmethod
-    def _normalize_race_label(label: str) -> str:
-        """Coalesce cledoux42's 5 classes into our 7-bucket schema."""
-        normalized = label.strip().lower().replace("-", "_")
-        race_aliases = {
-            # Legacy FairFace 7-class labels
-            "white": "White",
-            "black": "Black",
-            "latino_hispanic": "Latino_Hispanic",
-            "latino hispanic": "Latino_Hispanic",
-            "east asian": "East Asian",
-            "southeast asian": "Southeast Asian",
-            "indian": "Indian",
-            "middle eastern": "Middle Eastern",
-            # cledoux42/Ethnicity_Test_v003 5-class labels
-            "african": "Black",
-            "asian": "East Asian",
-            "caucasian": "White",
-            "hispanic": "Latino_Hispanic",
-        }
-        return race_aliases.get(normalized, label)
-
-    # Midpoint of each FairFace age bucket — used as the per-bucket
-    # "value" when we marginalise over the predicted distribution.
-    _AGE_MIDPOINTS = {
-        "0-2": 1.0,
-        "3-9": 6.0,
-        "10-19": 14.5,
-        "20-29": 24.5,
-        "30-39": 34.5,
-        "40-49": 44.5,
-        "50-59": 54.5,
-        "60-69": 64.5,
-        "70+": 75.0,
-    }
-
-    @classmethod
-    def _weighted_age_estimate(cls, predictions: list[dict]) -> float:
-        """Softmax-weighted expected age across all FairFace buckets.
-
-        FairFace is a 9-bucket classifier; the argmax always snaps to one
-        of nine fixed midpoints (24.5 for 20-29, etc.). Treating its
-        softmax as a probability distribution and taking the expected
-        value gives a continuous number that moves with confidence
-        (23.1 for someone very confidently 20-29, 28.4 if some mass leaks
-        into 30-39). Still bounded by bucket midpoints — true per-year
-        accuracy would need a regression model.
-        """
-        total_weight = 0.0
-        weighted_sum = 0.0
-        for pred in predictions:
-            label = cls._normalize_age_label(pred["label"])
-            midpoint = cls._AGE_MIDPOINTS.get(label)
-            if midpoint is None:
-                continue
-            score = float(pred["score"])
-            weighted_sum += midpoint * score
-            total_weight += score
-        if total_weight == 0:
-            return 0.0
-        return round(weighted_sum / total_weight, 1)
-
-    @classmethod
-    def _distribution_map(cls, predictions, normalizer, all_labels):
-        """Flatten HF predictions into {canonical_label: score} dict.
-
-        Unseen labels stay at 0.0 so the shape is always all_labels-sized.
-        """
-        distribution = {label: 0.0 for label in all_labels}
-        for prediction in predictions:
-            normalized_label = normalizer(prediction["label"])
-            if normalized_label in distribution:
-                distribution[normalized_label] = round(float(prediction["score"]), 3)
-        return distribution
-
-    @staticmethod
-    def _safe_predict(classifier, image, top_k: int):
-        """Wrap classifier(...) so a single model failure can't bring
-        down the whole demographic block."""
-        if classifier is None:
-            return []
-        try:
-            return classifier(image, top_k=top_k)
-        except Exception as exc:
-            print(f"[DemographicAnalyzer] Prediction failed: {exc}")
-            return []

analyzers/ethnicity_analyzer.py

@@ -0,0 +1,115 @@
+"""
+EthnicityAnalyzer — single-model ethnicity classifier.
+
+Model
+-----
+- HF repo  : cledoux42/Ethnicity_Test_v003
+- Arch     : Vision Transformer
+- Classes  : african, asian, caucasian, hispanic, indian (5)
+- Reported : 79.6% accuracy, macro-F1 0.797
+- License  : Apache 2.0
+- Source   : https://huggingface.co/cledoux42/Ethnicity_Test_v003
+
+Inputs
+------
+img_rgb : np.ndarray (H, W, 3) uint8
+
+Outputs (dict)
+--------------
+ethnicity              : canonical label (legacy 7-bucket schema)
+ethnicity_confidence   : argmax softmax score
+ethnicity_distribution : full {label: prob} dict, padded to all 7 buckets
+
+Notes
+-----
+Split out from the old DemographicAnalyzer (which also handled age and
+gender via FairFace ViTs). Age and gender now live in
+InsightFaceAnalyzer; this file owns ethnicity exclusively.
+
+The model emits 5 classes but we widen to the legacy 7-bucket FairFace
+schema so the rest of the app's distribution shape stays stable.
+Unseen buckets stay at 0.0.
+"""
+
+from typing import Any
+
+from PIL import Image
+from transformers import pipeline
+
+
+MODEL_ID = "cledoux42/Ethnicity_Test_v003"
+
+# Legacy schema preserved from the old DemographicAnalyzer.
+RACE_LABELS = [
+    "White", "Black", "Latino_Hispanic", "East Asian",
+    "Southeast Asian", "Indian", "Middle Eastern",
+]
+
+
+class EthnicityAnalyzer:
+    def __init__(self):
+        self.classifier = None
+        try:
+            self.classifier = pipeline("image-classification", model=MODEL_ID)
+        except Exception as exc:
+            print(f"[EthnicityAnalyzer] Failed to load {MODEL_ID}: {exc}")
+
+    def analyze(self, img_rgb) -> dict[str, Any]:
+        if self.classifier is None:
+            return self._empty_result()
+
+        try:
+            pil = Image.fromarray(img_rgb)
+            preds = self.classifier(pil, top_k=7)
+        except Exception as exc:
+            print(f"[EthnicityAnalyzer] Prediction failed: {exc}")
+            return self._empty_result()
+
+        if not preds:
+            return self._empty_result()
+
+        # Top prediction → canonical label.
+        top = preds[0]
+        top_label = self._normalize(top["label"])
+
+        distribution = {label: 0.0 for label in RACE_LABELS}
+        for pred in preds:
+            label = self._normalize(pred["label"])
+            if label in distribution:
+                distribution[label] = round(float(pred["score"]), 3)
+
+        return {
+            "ethnicity": top_label,
+            "ethnicity_confidence": round(float(top["score"]), 3),
+            "ethnicity_distribution": distribution,
+        }
+
+    @staticmethod
+    def _normalize(label: str) -> str:
+        """Map model output (5-class) to canonical 7-bucket label."""
+        normalized = label.strip().lower().replace("-", "_")
+        aliases = {
+            # Legacy FairFace 7-class
+            "white": "White",
+            "black": "Black",
+            "latino_hispanic": "Latino_Hispanic",
+            "latino hispanic": "Latino_Hispanic",
+            "east asian": "East Asian",
+            "southeast asian": "Southeast Asian",
+            "indian": "Indian",
+            "middle eastern": "Middle Eastern",
+            # cledoux42 5-class → widen into 7-bucket schema
+            "african": "Black",
+            "asian": "East Asian",
+            "caucasian": "White",
+            "hispanic": "Latino_Hispanic",
+        }
+        return aliases.get(normalized, label)
+
+    @staticmethod
+    def _empty_result() -> dict[str, Any]:
+        return {
+            "ethnicity": "unknown",
+            "ethnicity_confidence": 0.0,
+            "ethnicity_distribution": {label: 0.0 for label in RACE_LABELS},
+        }

analyzers/insightface_analyzer.py

@@ -0,0 +1,171 @@
+"""
+InsightFaceAnalyzer — detection + age + gender + recognition embedding.
+
+Model
+-----
+- Package    : `insightface` (https://github.com/deepinsight/insightface)
+- Bundle     : buffalo_l (ResNet50@WebFace600K backbone, ONNX)
+- Components : SCRFD-10GF detector, ArcFace 512-d recognition,
+               2d106 + 3d68 landmark regressors, age + gender heads
+- Size       : ~280 MB (ONNX, mixed FP16/FP32)
+- License    : weights research-only; code Apache 2.0
+- Source     : https://github.com/deepinsight/insightface/tree/master/python-package
+
+Inputs
+------
+img_rgb : np.ndarray (H, W, 3) uint8
+
+Outputs (dict)
+--------------
+face_bbox            : [x1, y1, x2, y2] in pixel coordinates
+face_confidence      : SCRFD detection score
+face_embedding       : list[float] of length 512 (ArcFace, L2-normalised)
+age_estimate         : float years (regression head, not bucketed)
+age_range            : string bucket derived from age_estimate for
+                       backwards compatibility with the legacy UI
+gender               : "male" | "female"
+gender_confidence    : 1.0 by default (InsightFace doesn't expose a
+                       gender softmax score; the head is argmax-only)
+_insight_landmarks_2d : list of (x, y) tuples — 106 points (internal)
+
+Accuracy
+--------
+- Recognition (ArcFace via buffalo_l): 99.83% LFW, 96.21% IJB-B FAR=1e-4.
+- Age / gender heads are widely used but lack a clean published metric.
+  In practice age MAE is ~5 years and gender ~94-96%.
+
+Notes
+-----
+We run the bundle once per image and expose only the highest-confidence
+face when multiple are detected — the rest of the pipeline assumes a
+single subject.
+"""
+
+import os
+from typing import Any
+
+import numpy as np
+
+# insightface is a relatively heavy import; deferred so the module can
+# at least load when the package isn't installed.
+try:
+    from insightface.app import FaceAnalysis
+    HAS_INSIGHTFACE = True
+except ImportError:
+    HAS_INSIGHTFACE = False
+
+
+MODEL_NAME = "buffalo_l"
+
+# Age buckets used by the legacy UI. We derive these from the regression
+# output so existing screens keep working.
+AGE_BUCKETS = [
+    (0, 3, "0-2"), (3, 10, "3-9"), (10, 20, "10-19"),
+    (20, 30, "20-29"), (30, 40, "30-39"), (40, 50, "40-49"),
+    (50, 60, "50-59"), (60, 70, "60-69"), (70, 200, "70+"),
+]
+
+
+class InsightFaceAnalyzer:
+    def __init__(self):
+        self.app = None
+        if not HAS_INSIGHTFACE:
+            print(
+                "[InsightFaceAnalyzer] insightface package not installed; "
+                "detection, age, gender, and recognition will degrade to 'unknown'."
+            )
+            return
+
+        try:
+            # Buffalo_L bundle auto-resolves under ~/.insightface/models/.
+            # CPUExecutionProvider is the right default for HF Spaces;
+            # ctx_id=0 + 'CUDAExecutionProvider' would be the GPU path.
+            self.app = FaceAnalysis(
+                name=MODEL_NAME,
+                providers=["CPUExecutionProvider"],
+            )
+            # det_size=(640, 640) is the canonical SCRFD input. Smaller
+            # speeds inference but loses small faces.
+            self.app.prepare(ctx_id=-1, det_size=(640, 640))
+        except Exception as exc:
+            print(f"[InsightFaceAnalyzer] Failed to load {MODEL_NAME}: {exc}")
+            self.app = None
+
+    def analyze(self, img_rgb: np.ndarray) -> dict[str, Any]:
+        if self.app is None:
+            return self._empty_result()
+
+        try:
+            # InsightFace expects BGR, OpenCV-native order.
+            img_bgr = img_rgb[..., ::-1]
+            faces = self.app.get(img_bgr)
+        except Exception as exc:
+            print(f"[InsightFaceAnalyzer] Inference failed: {exc}")
+            return self._empty_result()
+
+        if not faces:
+            return self._empty_result()
+
+        # If multiple faces, take the highest-confidence one. The rest of
+        # the pipeline assumes a single subject.
+        face = max(faces, key=lambda f: float(f.det_score))
+
+        # Bounding box is float32 in [x1, y1, x2, y2] image-pixel space.
+        bbox = [float(v) for v in face.bbox.tolist()]
+
+        # Recognition embedding: 512-d, L2-normalised by InsightFace.
+        # Cast to plain list[float] for clean JSON.
+        embedding = (
+            [float(v) for v in face.normed_embedding.tolist()]
+            if getattr(face, "normed_embedding", None) is not None
+            else None
+        )
+
+        # Age head is a single float (years). Round for display.
+        age = float(getattr(face, "age", 0.0))
+
+        # Gender is exposed as 0 (female) / 1 (male) on Face objects.
+        # InsightFace doesn't surface a softmax probability — we report
+        # confidence 1.0 to indicate "argmax, no soft signal".
+        gender_idx = int(getattr(face, "gender", -1))
+        gender = "male" if gender_idx == 1 else "female" if gender_idx == 0 else "unknown"
+
+        return {
+            "face_bbox": bbox,
+            "face_confidence": round(float(face.det_score), 3),
+            "face_embedding": embedding,
+            "age_estimate": round(age, 1),
+            "age_range": self._bucket_age(age),
+            "age_confidence": 1.0,
+            "gender": gender,
+            "gender_confidence": 1.0,
+            # 106 2D landmarks (forehead, jaw, brows, eyes, nose, lips).
+            # Underscore-prefixed → stripped from JSON, available to
+            # downstream analyzers that want a tighter face crop.
+            "_insight_landmarks_2d": (
+                [(float(p[0]), float(p[1])) for p in face.landmark_2d_106.tolist()]
+                if getattr(face, "landmark_2d_106", None) is not None
+                else None
+            ),
+        }
+
+    @staticmethod
+    def _bucket_age(age: float) -> str:
+        for lo, hi, label in AGE_BUCKETS:
+            if lo <= age < hi:
+                return label
+        return "unknown"
+
+    @staticmethod
+    def _empty_result() -> dict[str, Any]:
+        return {
+            "face_bbox": None,
+            "face_confidence": 0.0,
+            "face_embedding": None,
+            "age_estimate": 0.0,
+            "age_range": "unknown",
+            "age_confidence": 0.0,
+            "gender": "unknown",
+            "gender_confidence": 0.0,
+            "_insight_landmarks_2d": None,
+        }

analyzers/landmark_analyzer.py

@@ -11,6 +11,9 @@ Model
 Inputs
 ------
 img_rgb : np.ndarray (H, W, 3) uint8, RGB order.
+          Always receives the full photo (not a face crop) — MediaPipe
+          has its own face detector and works best with the full
+          field of view to maintain z-coordinate consistency.
 
 Outputs (dict)
 --------------

analyzers/parsing_analyzer.py

@@ -15,7 +15,12 @@ Model
 
 Inputs
 ------
-img_rgb : np.ndarray (H, W, 3) uint8
+img_rgb : np.ndarray (H, W, 3) uint8.
+          Since `app.py` v3.0, this is typically a face-cropped image
+          (produced by `_crop_to_face` using the InsightFace bbox)
+          rather than the full photo. SegFormer behaves much more
+          consistently when the face fills most of the input — the
+          masks become tighter and skin-stat estimates less noisy.
 
 Outputs (dict)
 --------------

app.py

@@ -2,38 +2,57 @@
 HCP Face Analysis Microservice
 ==============================
 
-FastAPI service that runs seven specialized analyzers over a single photo
-and merges their outputs into one ~100-field facial-attribute dictionary.
+FastAPI service that runs nine specialized analyzers over a single photo
+and merges their outputs into one facial-attribute dictionary, including
+a face-recognition embedding for cross-photo grouping and a numeric
+"chopped score" aesthetic rating.
 
 Pipeline (in execution order)
 -----------------------------
-1.  MediaPipe Face Landmarker   478 3D landmarks + 52 ARKit blendshapes.
-                                Produces all geometric face/eye/nose/lip/
-                                jaw features plus smiling and mouth-open.
-
-2.  DemographicAnalyzer         Three ViT classifiers (FairFace age,
-                                FairFace gender, Ethnicity_Test_v003).
-                                Age is reported as a softmax-weighted
-                                continuous estimate, not a bucket midpoint.
-
-3.  ParsingAnalyzer             SegFormer-B5 human parsing. Emits face
-                                and hair pixel masks plus hair length,
-                                hat detection, and skin texture/wrinkle/
-                                freckle/uniformity stats computed via
-                                OpenCV over the face mask.
-
-4.  EmotionAnalyzer             HSEmotion EfficientNet-B0 8-class output
-                                plus derived valence, arousal, mood.
-
-5.  ColorAnalyzer               Pixel-level LAB/HSV statistics. Reads
-                                masks from step 3 and lip/iris landmarks
-                                from step 1. No ML model.
-
-6.  ObstructionAnalyzer         dima806 ViT-B/16. Glasses, sunglasses,
-                                mask flags with ~99% precision/recall.
-
-7.  HairTypeAnalyzer            dima806 ViT-B/16. Curly/dreadlocks/kinky/
-                                straight/wavy at ~93% accuracy.
+1.  InsightFaceAnalyzer        InsightFace buffalo_l (ONNX). SCRFD
+                               detection + ArcFace 512-d embedding +
+                               age regression + gender + 106 landmarks.
+                               Replaces the previous three FairFace ViTs
+                               and adds face matching as a new capability.
+
+2.  LandmarkAnalyzer           MediaPipe Face Landmarker. 478 3D
+                               landmarks + 52 ARKit blendshapes →
+                               geometric features, smiling, mouth_open.
+
+3.  EthnicityAnalyzer          cledoux42/Ethnicity_Test_v003 ViT.
+                               5-class ethnicity widened to a 7-bucket
+                               schema for legacy compatibility.
+
+4.  ParsingAnalyzer            SegFormer-B5 human parsing. Now receives
+                               a face-cropped image (smaller, cleaner).
+                               Emits face/hair masks + hair length +
+                               hat detection + OpenCV-derived skin stats.
+
+5.  EmotionAnalyzer            HSEmotion EfficientNet-B0. 8-class
+                               emotion + valence/arousal/mood.
+
+6.  ColorAnalyzer              Pure OpenCV LAB/HSV statistics. Uses
+                               SegFormer masks + MediaPipe lip/iris
+                               landmarks. No ML model.
+
+7.  ObstructionAnalyzer        dima806 ViT-B/16. Glasses, sunglasses,
+                               mask. ~99% precision on each.
+
+8.  HairTypeAnalyzer           dima806 ViT-B/16. Curly/dreadlocks/kinky/
+                               straight/wavy. ~93% accuracy.
+
+9.  BeautyAnalyzer             Optional. ResNet-50 trained on
+                               SCUT-FBP5500 (see training/beauty/).
+                               Outputs a 1.0–5.0 beauty score plus a
+                               0–100 normalised version. Falls back to
+                               None when no weights are loaded — the
+                               AestheticAnalyzer then uses rule-based
+                               scoring only.
+
+10. AestheticAnalyzer          Pure-Python aggregator. Reads the merged
+                               dict from analyzers 1–9 and produces the
+                               final `chopped_score` (0–100, higher =
+                               more chopped) and a per-factor breakdown.
 
 Endpoints
 ---------
@@ -42,15 +61,14 @@ GET  /health            liveness check
 POST /analyze           multipart file upload
 POST /analyze-base64    JSON {"image": "<base64>"}
 
-Both POST endpoints run the same pipeline. All analyzers are lazily
-instantiated on first request to keep cold-start latency manageable
-on the Hugging Face Spaces free tier.
+All analyzers are lazily instantiated on first request to keep
+cold-start latency manageable on the Hugging Face Spaces free tier.
 """
 
 import os
-# hf_transfer gives much faster model downloads from the HF Hub on first
-# inference. HF_HUB_DOWNLOAD_TIMEOUT defaults to 10s which is too short
-# for the larger ViT checkpoints on a cold start.
+# hf_transfer makes initial model downloads from the HF Hub much faster.
+# The default HF_HUB_DOWNLOAD_TIMEOUT (10 s) is too short for the larger
+# ViT checkpoints on a cold start.
 os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
 os.environ["HF_HUB_DOWNLOAD_TIMEOUT"] = "60"
 
@@ -64,34 +82,41 @@ from fastapi.middleware.cors import CORSMiddleware
 from PIL import Image
 
 from analyzers.landmark_analyzer import LandmarkAnalyzer
-from analyzers.demographic_analyzer import DemographicAnalyzer
+from analyzers.ethnicity_analyzer import EthnicityAnalyzer
 from analyzers.parsing_analyzer import ParsingAnalyzer
 from analyzers.emotion_analyzer import EmotionAnalyzer
 from analyzers.color_analyzer import ColorAnalyzer
 from analyzers.obstruction_analyzer import ObstructionAnalyzer
 from analyzers.hair_type_analyzer import HairTypeAnalyzer
+from analyzers.insightface_analyzer import InsightFaceAnalyzer
+from analyzers.beauty_analyzer import BeautyAnalyzer
+from analyzers.aesthetic_analyzer import AestheticAnalyzer
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
-app = FastAPI(title="HCP Face Analysis Service", version="2.0.0")
+app = FastAPI(title="HCP Face Analysis Service", version="3.0.0")
 
 app.add_middleware(
     CORSMiddleware,
-    allow_origins=["*"],  # Restrict to your domain in production
+    allow_origins=["*"],  # Restrict to your domain in production.
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],
 )
 
-# Analyzers are initialized lazily on first request to reduce cold-start time
+# Lazy slots, one per analyzer. The first request pays the full
+# model-load cost; subsequent requests are warm.
+insightface_analyzer: Optional[InsightFaceAnalyzer] = None
 landmark_analyzer: Optional[LandmarkAnalyzer] = None
-demographic_analyzer: Optional[DemographicAnalyzer] = None
+ethnicity_analyzer: Optional[EthnicityAnalyzer] = None
 parsing_analyzer: Optional[ParsingAnalyzer] = None
 emotion_analyzer: Optional[EmotionAnalyzer] = None
 color_analyzer: Optional[ColorAnalyzer] = None
 obstruction_analyzer: Optional[ObstructionAnalyzer] = None
 hair_type_analyzer: Optional[HairTypeAnalyzer] = None
+beauty_analyzer: Optional[BeautyAnalyzer] = None
+aesthetic_analyzer: Optional[AestheticAnalyzer] = None
 
 
 def _to_json_safe(value):
@@ -101,8 +126,6 @@ def _to_json_safe(value):
     or boolean mask logic). FastAPI's default JSON encoder doesn't
     handle those, so we normalise everything here before returning.
     """
-    # Numpy first — these checks would otherwise be caught by isinstance
-    # for dict/list because numpy.generic types are duck-typed.
     if isinstance(value, (np.ndarray,)):
         return value.tolist()
     if isinstance(value, (np.integer, np.floating)):
@@ -111,7 +134,6 @@ def _to_json_safe(value):
         return bool(value)
     if isinstance(value, np.generic):
         return value.item()
-    # Recurse into nested containers.
     if isinstance(value, dict):
         return {str(k): _to_json_safe(v) for k, v in value.items()}
     if isinstance(value, (list, tuple, set)):
@@ -126,17 +148,22 @@ def get_analyzers():
     requests. First request pays the full model-load cost; subsequent
     requests are warm.
     """
-    global landmark_analyzer, demographic_analyzer
+    global insightface_analyzer, landmark_analyzer, ethnicity_analyzer
     global parsing_analyzer, emotion_analyzer, color_analyzer
     global obstruction_analyzer, hair_type_analyzer
+    global beauty_analyzer, aesthetic_analyzer
+
+    if insightface_analyzer is None:
+        logger.info("Loading InsightFace buffalo_l bundle...")
+        insightface_analyzer = InsightFaceAnalyzer()
 
     if landmark_analyzer is None:
         logger.info("Loading MediaPipe Face Landmarker...")
         landmark_analyzer = LandmarkAnalyzer()
 
-    if demographic_analyzer is None:
-        logger.info("Loading FairFace demographics model...")
-        demographic_analyzer = DemographicAnalyzer()
+    if ethnicity_analyzer is None:
+        logger.info("Loading Ethnicity classifier...")
+        ethnicity_analyzer = EthnicityAnalyzer()
 
     if parsing_analyzer is None:
         logger.info("Loading SegFormer face parser...")
@@ -157,23 +184,156 @@ def get_analyzers():
         logger.info("Loading hair type classifier...")
         hair_type_analyzer = HairTypeAnalyzer()
 
+    if beauty_analyzer is None:
+        logger.info("Loading beauty regressor (or no-op if untrained)...")
+        beauty_analyzer = BeautyAnalyzer()
+
+    if aesthetic_analyzer is None:
+        aesthetic_analyzer = AestheticAnalyzer()
+
     return (
+        insightface_analyzer,
         landmark_analyzer,
-        demographic_analyzer,
+        ethnicity_analyzer,
         parsing_analyzer,
         emotion_analyzer,
         color_analyzer,
         obstruction_analyzer,
         hair_type_analyzer,
+        beauty_analyzer,
+        aesthetic_analyzer,
     )
 
 
+def _crop_to_face(img_rgb: np.ndarray, bbox, padding: float = 0.4) -> np.ndarray:
+    """Crop the image to a face-centred rectangle with extra context.
+
+    SegFormer and the ViT classifiers tend to do better with the face
+    occupying a large fraction of the input. We pad the InsightFace
+    bbox by `padding` (fraction of bbox size) so context like ears,
+    hair, and the top of the shoulders is preserved.
+
+    Returns the full image unchanged if bbox is None, malformed, or
+    the resulting crop would be degenerate.
+    """
+    if bbox is None or len(bbox) != 4:
+        return img_rgb
+    h, w = img_rgb.shape[:2]
+    try:
+        x1, y1, x2, y2 = bbox
+        bw = max(1.0, x2 - x1)
+        bh = max(1.0, y2 - y1)
+        pad_x = bw * padding
+        pad_y = bh * padding
+        cx1 = max(0, int(x1 - pad_x))
+        cy1 = max(0, int(y1 - pad_y))
+        cx2 = min(w, int(x2 + pad_x))
+        cy2 = min(h, int(y2 + pad_y))
+        if cx2 - cx1 < 32 or cy2 - cy1 < 32:
+            return img_rgb
+        return img_rgb[cy1:cy2, cx1:cx2]
+    except Exception:
+        return img_rgb
+
+
+def _run_pipeline(img_array: np.ndarray) -> dict:
+    """Run all ten analyzers against `img_array` and return the merged dict.
+
+    Shared by /analyze and /analyze-base64. Kept as a function rather
+    than inlined twice so the per-step ordering is the single source
+    of truth.
+    """
+    (
+        insight,
+        landmarks,
+        ethnicities,
+        parsing,
+        emotions,
+        colors,
+        obstructions,
+        hair_types,
+        beauty,
+        aesthetics,
+    ) = get_analyzers()
+
+    results: dict = {}
+
+    # Step 1: InsightFace detection + age + gender + recognition embedding.
+    logger.info("Running InsightFace analysis...")
+    insight_results = insight.analyze(img_array)
+    results.update(insight_results)
+
+    # Compute a face crop once and pass it to every downstream analyzer
+    # that benefits from it (parsing, ethnicity, obstruction, hair type,
+    # beauty regressor). Falls back to the full image when InsightFace
+    # didn't find a face.
+    face_crop = _crop_to_face(img_array, insight_results.get("face_bbox"))
+
+    # Step 2: MediaPipe landmarks (works on the full image; it has its
+    # own internal detector).
+    logger.info("Running landmark analysis...")
+    landmark_results = landmarks.analyze(img_array)
+    results.update(landmark_results)
+
+    # Step 3: ethnicity classifier — likes a tighter face crop.
+    logger.info("Running ethnicity analysis...")
+    results.update(ethnicities.analyze(face_crop))
+
+    # Step 4: SegFormer parsing on the face crop (cleaner masks).
+    logger.info("Running face parsing...")
+    parse_results = parsing.analyze(face_crop)
+    results.update(parse_results)
+
+    # Step 5: HSEmotion on the face crop.
+    logger.info("Running emotion analysis...")
+    results.update(emotions.analyze(face_crop))
+
+    # Step 6: pixel-level colour analysis. Uses the face/hair masks
+    # from step 4 (already in face-crop coordinate space) and the
+    # MediaPipe lip/iris landmarks from step 2 (still in full-image
+    # space, normalised). We pass `face_crop` so mask coordinates
+    # line up; landmarks are in normalised coordinates so they map
+    # correctly to either image.
+    logger.info("Running color analysis...")
+    color_results = colors.analyze(
+        face_crop,
+        skin_mask=parse_results.get("_skin_mask"),
+        hair_mask=parse_results.get("_hair_mask"),
+        landmarks=landmark_results.get("_raw_landmarks"),
+    )
+    results.update(color_results)
+
+    # Step 7: obstruction classifier — also benefits from a face crop.
+    logger.info("Running obstruction analysis...")
+    results.update(obstructions.analyze(face_crop))
+
+    # Step 8: hair-type classifier.
+    logger.info("Running hair-type analysis...")
+    results.update(hair_types.analyze(face_crop))
+
+    # Step 9: learned beauty regressor (no-op if no weights present).
+    logger.info("Running beauty regressor...")
+    results.update(beauty.analyze(face_crop))
+
+    # Step 10: aesthetic aggregator. Reads the merged dict; no image
+    # input. Always runs last so it can see every other analyzer's
+    # outputs.
+    logger.info("Running aesthetic aggregator...")
+    results.update(aesthetics.analyze(results))
+
+    # Drop internal/scratch fields (leading underscore) before
+    # returning. Keeps masks and raw landmark lists out of the JSON.
+    results = {k: v for k, v in results.items() if not k.startswith("_")}
+
+    return results
+
+
 @app.get("/")
 async def root():
     """Service banner — confirms the server is reachable and which version."""
     return {
         "name": "HCP Face Analysis Service",
-        "version": "2.0.0",
+        "version": "3.0.0",
         "status": "running",
         "endpoints": {
             "health": "/health",
@@ -193,72 +353,15 @@ async def health():
 async def analyze_face(file: UploadFile = File(...)):
     """Multipart endpoint for direct uploads.
 
-    Runs all seven analyzers and returns the merged attribute dict.
-    See `analyze_face_base64` for the JSON-body variant the Express
-    server calls.
+    Runs the full ten-step pipeline and returns the merged attribute
+    dict. See `analyze_face_base64` for the JSON-body variant the
+    Express server calls.
     """
     try:
-        # Decode the upload into an RGB numpy array. All analyzers
-        # work in RGB; we don't actually need BGR but keeping it as a
-        # local in case a future analyzer wants the OpenCV-native order.
         contents = await file.read()
         image = Image.open(io.BytesIO(contents)).convert("RGB")
         img_array = np.array(image)
-
-        (
-            landmarks,
-            demographics,
-            parsing,
-            emotions,
-            colors,
-            obstructions,
-            hair_types,
-        ) = get_analyzers()
-
-        results = {}
-
-        # Step 1: MediaPipe Landmarks → all geometric features + blendshapes.
-        logger.info("Running landmark analysis...")
-        landmark_results = landmarks.analyze(img_array)
-        results.update(landmark_results)
-
-        # Step 2: FairFace + Ethnicity ViT → demographics.
-        logger.info("Running demographic analysis...")
-        demo_results = demographics.analyze(img_array)
-        results.update(demo_results)
-
-        # Step 3: SegFormer-B5 human parsing → masks + hair length + skin stats.
-        logger.info("Running face parsing...")
-        parse_results = parsing.analyze(img_array)
-        results.update(parse_results)
-
-        # Step 4: HSEmotion → 8-class emotion + valence/arousal/mood.
-        logger.info("Running emotion analysis...")
-        emo_results = emotions.analyze(img_array)
-        results.update(emo_results)
-
-        # Step 5: Pixel color analysis. Uses the face/hair masks from step 3
-        # and MediaPipe lip/iris landmarks from step 1.
-        logger.info("Running color analysis...")
-        color_results = colors.analyze(
-            img_array,
-            skin_mask=parse_results.get("_skin_mask"),
-            hair_mask=parse_results.get("_hair_mask"),
-            landmarks=landmark_results.get("_raw_landmarks"),
-        )
-        results.update(color_results)
-
-        # Step 6: ObstructionViT → glasses / sunglasses / mask flags.
-        logger.info("Running obstruction analysis...")
-        results.update(obstructions.analyze(img_array))
-
-        # Step 7: HairTypeViT → curly/dreadlocks/kinky/straight/wavy.
-        logger.info("Running hair-type analysis...")
-        results.update(hair_types.analyze(img_array))
-
-        # Remove internal fields (prefixed with underscore)
-        results = {k: v for k, v in results.items() if not k.startswith("_")}
-
+        results = _run_pipeline(img_array)
         return {"success": True, "data": _to_json_safe(results)}
 
     except Exception as e:
@@ -281,56 +384,14 @@ async def analyze_face_base64(body: dict):
         if not image_b64:
             raise HTTPException(status_code=400, detail="No image data provided")
 
-        # Strip data URI prefix if present
+        # Strip a possible "data:image/...;base64," prefix.
         if "," in image_b64:
             image_b64 = image_b64.split(",", 1)[1]
 
         image_bytes = base64.b64decode(image_b64)
         image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
         img_array = np.array(image)
-
-        (
-            landmarks,
-            demographics,
-            parsing,
-            emotions,
-            colors,
-            obstructions,
-            hair_types,
-        ) = get_analyzers()
-
-        results = {}
-
-        # Same seven-step pipeline as /analyze. Kept inline (rather
-        # than factored out) so the per-step `logger.info` cadence and
-        # ordering stay obvious when reading either endpoint top-down.
-        landmark_results = landmarks.analyze(img_array)
-        results.update(landmark_results)
-
-        demo_results = demographics.analyze(img_array)
-        results.update(demo_results)
-
-        parse_results = parsing.analyze(img_array)
-        results.update(parse_results)
-
-        emo_results = emotions.analyze(img_array)
-        results.update(emo_results)
-
-        color_results = colors.analyze(
-            img_array,
-            skin_mask=parse_results.get("_skin_mask"),
-            hair_mask=parse_results.get("_hair_mask"),
-            landmarks=landmark_results.get("_raw_landmarks"),
-        )
-        results.update(color_results)
-
-        results.update(obstructions.analyze(img_array))
-        results.update(hair_types.analyze(img_array))
-
-        # Drop internal/scratch fields (leading underscore) before
-        # returning. Keeps masks and raw landmark lists out of the JSON.
-        results = {k: v for k, v in results.items() if not k.startswith("_")}
-
+        results = _run_pipeline(img_array)
         return {"success": True, "data": _to_json_safe(results)}
 
     except HTTPException:

architecture.md

@@ -2,65 +2,82 @@
 
 ## Pipeline
 
-A single photo is fed through seven analyzers. Their outputs are merged
-into one dictionary; later analyzers overwrite any colliding keys from
-earlier ones.
+A single photo runs through ten analyzers. Their outputs are merged
+into one dictionary; later analyzers can overwrite keys from earlier
+ones (only intentional in a couple of places — `_run_pipeline` in
+[app.py](app.py) is the single source of truth).
 
 ```
 Photo (RGB ndarray)
   │
-  ├─► [1] MediaPipe Face Landmarker
-  │       478 landmarks + 52 blendshapes
-  │       → all geometric features (face/eye/nose/eyebrow/lip/jaw shape),
-  │         smiling (mouthSmile blendshapes), eyes_open, possible_dimples,
-  │         possible_unibrow, facial_asymmetry_score, blendshapes dict
+  ├─► [1] InsightFaceAnalyzer  (insightface buffalo_l, ONNX)
+  │       → face_bbox, face_confidence, face_embedding (512-d ArcFace),
+  │         age_estimate, age_range, gender + confidences
   │
-  ├─► [2] FairFace + Ethnicity ViT (DemographicAnalyzer)
-  │       → age_range, age_estimate (softmax-weighted continuous), age_confidence,
-  │         gender + confidence, ethnicity + confidence, full distributions
+  ├─► Build face crop from face_bbox + padding. Downstream analyzers
+  │   that benefit from a tighter input read the crop; MediaPipe gets
+  │   the full image because it has its own detector.
   │
-  ├─► [3] SegFormer-B5 human parsing (ParsingAnalyzer)
-  │       → per-class pixel masks (face, hair, hat, …)
-  │       → hair_length, hair_present, hat_detected,
-  │         wrinkle_level, skin_texture_score, skin_uniformity, freckles_or_moles
-  │       (uses OpenCV stats over the SegFormer face mask for the skin rows)
+  ├─► [2] LandmarkAnalyzer  (MediaPipe Face Landmarker)
+  │       478 landmarks + 52 blendshapes → all geometric features,
+  │       smiling, mouth_open (via blendshapes.jawOpen), eyes_open,
+  │       facial_asymmetry_score, smile_asymmetry, possible_dimples,
+  │       possible_unibrow.
   │
-  ├─► [4] HSEmotion EfficientNet-B0 (EmotionAnalyzer)
-  │       → primary/secondary emotion, emotion_scores (8 classes),
-  │         valence, arousal, mood
+  ├─► [3] EthnicityAnalyzer  (cledoux42/Ethnicity_Test_v003 ViT)
+  │       → ethnicity, ethnicity_confidence, ethnicity_distribution
+  │       (cropped input).
   │
-  ├─► [5] ColorAnalyzer (no ML — OpenCV LAB/HSV)
-  │       inputs: SegFormer skin/hair masks + MediaPipe landmarks
+  ├─► [4] ParsingAnalyzer  (SegFormer-B5 human parsing)
+  │       → _skin_mask, _hair_mask, hat_detected, hair_length,
+  │         hair_present, wrinkle_level, skin_texture_score,
+  │         skin_uniformity, freckles_or_moles
+  │       (cropped input — cleaner masks).
+  │
+  ├─► [5] EmotionAnalyzer  (HSEmotion EfficientNet-B0)
+  │       → primary/secondary emotion, emotion_scores, valence,
+  │         arousal, mood (cropped input).
+  │
+  ├─► [6] ColorAnalyzer  (no ML — OpenCV LAB/HSV)
+  │       Reads SegFormer masks + MediaPipe lip/iris landmarks.
   │       → skin_tone (Fitzpatrick + L*/a*/b* + hex), skin_undertone,
-  │         eye_color, hair_color (name + hex), hair_texture (pixel-Laplacian, coarse),
-  │         lip_color (shade + hex)  ← lip mask built from MediaPipe outer-minus-inner lip
+  │         eye_color, hair_color (name + hex), hair_texture
+  │         (coarse, fallback), lip_color (shade + hex)
   │
-  ├─► [6] ObstructionViT — dima806/face_obstruction_image_detection
+  ├─► [7] ObstructionAnalyzer  (dima806/face_obstruction ViT-B/16)
   │       → wearing_glasses, wearing_sunglasses, wearing_mask,
-  │         obstruction_top, obstruction_scores
+  │         obstruction_scores (cropped input).
+  │
+  ├─► [8] HairTypeAnalyzer  (dima806/hair_type ViT-B/16)
+  │       → hair_type (curly/dreadlocks/kinky/straight/wavy),
+  │         hair_type_confidence (cropped input).
   │
-  └─► [7] HairTypeViT — dima806/hair_type_image_detection
-          → hair_type (curly/dreadlocks/kinky/straight/wavy),
-            hair_type_confidence, hair_type_scores
+  ├─► [9] BeautyAnalyzer  (ResNet-50 trained on SCUT-FBP5500)
+  │       Optional. Loads local weights or HF Hub; if absent, output
+  │       is None and AestheticAnalyzer falls back to rules.
+  │       → beauty_score (1.0–5.0), beauty_score_norm (0–100),
+  │         beauty_model_source.
+  │
+  └─► [10] AestheticAnalyzer  (no model)
+          Reads the merged dict from steps 1–9 and produces the
+          final chopped_score (0–100) plus chopped_breakdown
+          showing each factor's signed contribution.
 ```
 
-All masks and other internal fields use a leading underscore in the key
-(e.g. `_skin_mask`). `app.py` strips those before returning JSON so the
-client never sees them.
+Internal/scratch keys use a leading underscore (`_skin_mask`,
+`_hair_mask`, `_raw_landmarks`, `_insight_landmarks_2d`). `app.py`
+strips them before returning JSON.
 
 ## Attribute → source map
 
-The EditProfileScreen renders only fields backed by one of these
-analyzers. Anything previously fed by the FaRL zero-shot classifier
-has been removed because its outputs were too noisy to trust.
-
 | Section | Field(s) | Source |
 |---|---|---|
-| Demographics | gender, age (continuous), age_range, ethnicity, distributions | FairFace + Ethnicity ViT |
-| Emotion | primary/secondary emotion, scores, valence, arousal, mood | HSEmotion |
-| Face Structure | face_shape (+ 4 ratios), jawline_type/angle, chin_type, cheekbone_prominence, cheek_fullness, forehead_width, facial_asymmetry_score | MediaPipe |
-| Hair | hair_length, hair_present | SegFormer |
-| Hair | hair_type (+ confidence) | HairTypeViT |
+| Demographics | face_bbox, face_confidence, face_embedding (512-d), age_estimate, age_range, age_confidence, gender, gender_confidence | InsightFace buffalo_l |
+| Demographics | ethnicity, ethnicity_confidence, ethnicity_distribution | EthnicityAnalyzer (cledoux42 ViT) |
+| Emotion | primary/secondary emotion, emotion_scores, valence, arousal, mood | HSEmotion EffNet-B0 |
+| Face Structure | face_shape (+ 4 ratios), jawline_type/angle, chin_type, cheekbone_prominence, cheek_fullness, forehead_width, facial_asymmetry_score | MediaPipe Face Landmarker |
+| Hair | hair_length, hair_present | SegFormer-B5 |
+| Hair | hair_type (+ confidence) | HairTypeViT (dima806) |
 | Hair | hair_color, hair hex | ColorAnalyzer |
 | Eyes | eye_shape, eye_depth, eye_spacing, eye_size, eyes_open | MediaPipe |
 | Eyes | eye_color | ColorAnalyzer |
@@ -70,30 +87,58 @@ has been removed because its outputs were too noisy to trust.
 | Lips & Mouth | lip_color (shade + hex) | ColorAnalyzer (mask from MediaPipe) |
 | Skin | skin_tone (Fitzpatrick, L*/a*/b*, hex), skin_undertone | ColorAnalyzer |
 | Skin | wrinkle_level, skin_texture_score, skin_uniformity, freckles_or_moles | SegFormer mask + OpenCV stats |
-| Accessories | wearing_glasses, wearing_sunglasses, wearing_mask | ObstructionViT |
+| Accessories | wearing_glasses, wearing_sunglasses, wearing_mask | ObstructionViT (dima806) |
 | Accessories | wearing_hat | SegFormer (hat class coverage) |
+| Aesthetics | beauty_score (1–5), beauty_score_norm (0–100) | BeautyAnalyzer (SCUT-FBP5500 ResNet-50) |
+| Aesthetics | chopped_score (0–100), chopped_breakdown | AestheticAnalyzer (rule + learned blend) |
+
+## Face matching
+
+InsightFace's ArcFace head emits a 512-d L2-normalised recognition
+embedding. We store it alongside each contact in
+`people.face_embedding` (pgvector). On a new photo save, the client
+queries Supabase for any contact with cosine similarity ≥ 0.55 to the
+new embedding and prompts the user *"this looks like {name}, add to
+that profile?"* before creating a new contact.
+
+LFW accuracy is 99.83%; IJB-B at FAR=1e-4 is 96.21%. For grouping
+photos in a personal collection (similar lighting, same camera) this
+is excellent. Identical twins and close family members can match — the
+0.55 threshold makes the prompt opt-in rather than auto-merge.
+
+## Training the beauty regressor
+
+Live source in [training/beauty/](../training/beauty/). The script
+fine-tunes a timm ResNet-50 on SCUT-FBP5500. After training, drop the
+resulting `beauty_regressor.pt` into `face-service/models/` (or push
+to HF Hub and set `BEAUTY_HF_REPO_ID`). `BeautyAnalyzer` picks it up
+automatically on the next process boot.
+
+Until weights exist, `beauty_score` returns None and the AestheticAnalyzer
+gracefully falls back to a pure rule-based chopped score.
 
 ## Deployment
 
-The service is built as a Docker image targeting Hugging Face Spaces
-free tier (2GB RAM, shared CPU). The MediaPipe `.task` is pulled at
-build time; all Hugging Face models lazy-download on first inference
-and cache under `/root/.cache/huggingface` inside the container.
+The service builds as a Docker image targeting Hugging Face Spaces
+free tier (2 GB RAM, shared CPU). MediaPipe `.task` and the
+InsightFace buffalo_l bundle are pulled at build time; all other
+Hugging Face models lazy-download on first inference and cache under
+`/root/.cache/huggingface`.
 
 The Node/Express server forwards `/analyze-face` requests to
-`FACE_SERVICE_URL/analyze-base64`. The React Native client never talks
-to this service directly.
+`FACE_SERVICE_URL/analyze-base64`. The React Native client never
+talks to this service directly.
 
 ## Adding a new analyzer
 
-1. Drop a new module under `analyzers/` exposing a class with
-   `__init__()` and `analyze(img_rgb) -> dict`.
-2. Import it in `app.py`, add a global slot and a lazy-load block in
-   `get_analyzers()`, and append a `results.update(...)` call to both
-   `/analyze` and `/analyze-base64`.
-3. Surface the new keys in `client/src/screens/EditProfileScreen.js`
-   and add a legend row in the "Analysis Method Details" section.
+1. Drop a new module under `analyzers/` with a class exposing
+   `__init__()` and `analyze(...) -> dict`.
+2. Import + add a lazy-load block in `app.py`'s `get_analyzers()`.
+3. Add a `results.update(...)` call inside `_run_pipeline` at the
+   right pipeline position.
+4. Surface the new keys in
+   [client/src/screens/EditProfileScreen.js](../client/src/screens/EditProfileScreen.js)
+   and add a legend row.
 
 Order matters: later analyzers overwrite earlier keys on collision.
-The specialized ViT classifiers run last so they win over any coarser
-signal.
+The aesthetic aggregator runs last so it can see everything.

requirements.txt

@@ -13,3 +13,5 @@ timm==1.0.3
 safetensors>=0.6.0
 transformers==4.45.2
 hsemotion>=0.2.2
+insightface>=0.7.3
+onnxruntime>=1.18.0