Upload folder using huggingface_hub

app.py

@@ -83,6 +83,74 @@ def embed_texts(model_id: str, texts: list[str]) -> dict:
     return {"embeddings": emb.tolist(), "dim": int(emb.shape[1])}
 
 
+# --- Skin-tone lane (M4): face-parse → CIELAB → MST, runs the vendored pipeline -
+@lru_cache(maxsize=1)
+def _skin_estimator():
+    """The real face-parsing skin-tone estimator (vendored under skintone/)."""
+    from skintone import FaceParsingSkinToneEstimator
+
+    return FaceParsingSkinToneEstimator()
+
+
+@spaces.GPU
+def estimate_skin_tone(image_b64: str) -> dict:
+    """One photo → {'skin_tone': 'mstN', 'undertone': str, 'field_confidence': {...},
+    'model_version': str}. Abstains ('unknown') honestly when no face/skin is found."""
+    from skintone import estimate_skin_tone as _run
+
+    est = _run(_decode_image(image_b64), _skin_estimator())
+    return {
+        "skin_tone": est.skin_tone,
+        "undertone": est.undertone,
+        "field_confidence": dict(est.field_confidence),
+        "model_version": est.model_version,
+    }
+
+
+# --- Body-type lane (M3): SAM 3D Body → MHR mesh, GPU-only -------------------
+# Gated (request access to facebook/sam-3d-body-dinov3 + accept the SAM License)
+# and heavy (PyTorch3D + hydra, installed from facebookresearch/sam-3d-body). The
+# Space does only the GPU mesh fit; the caller's CPU runs the mesh→measurements→
+# silhouette taxonomy (usermodel.body.estimate), so no SAM deps touch the API host.
+_BODY_HF_REPO = "facebook/sam-3d-body-dinov3"
+
+
+@lru_cache(maxsize=1)
+def _load_body():
+    """Set up the SAM 3D Body estimator once (checkpoints downloaded on first call)."""
+    from notebook.utils import setup_sam_3d_body  # provided by the sam-3d-body repo
+
+    return setup_sam_3d_body(hf_repo_id=_BODY_HF_REPO)
+
+
+@spaces.GPU
+def estimate_body(image_b64: str) -> dict:
+    """One photo → MHR mesh of the largest detected person.
+
+    Returns ``{'vertices': [[x,y,z],...], 'region_quality': {}, 'model_confidence':
+    float, 'model_version': str}``. An empty/zero-confidence result is an honest
+    "no body found" the caller turns into an abstention (unknown body type).
+    """
+    image = _decode_image(image_b64)
+    rgb = np.ascontiguousarray(np.asarray(image))
+    people = _load_body().process_one_image(rgb)
+    if not people:
+        return {"vertices": [], "region_quality": {}, "model_confidence": 0.0,
+                "model_version": "sam3dbody-mhr-v1"}
+    person = max(people, key=lambda p: float(p.get("score", p.get("confidence", 1.0)) or 0.0))
+    verts = np.asarray(person.get("pred_vertices"), dtype=np.float32)
+    if verts.ndim != 2 or verts.shape[0] == 0:
+        return {"vertices": [], "region_quality": {}, "model_confidence": 0.0,
+                "model_version": "sam3dbody-mhr-v1"}
+    score = float(person.get("score", person.get("confidence", 1.0)) or 1.0)
+    return {
+        "vertices": verts.tolist(),
+        "region_quality": {},
+        "model_confidence": max(0.0, min(1.0, score)),
+        "model_version": "sam3dbody-mhr-v1",
+    }
+
+
 with gr.Blocks(title="GYF GPU lane") as demo:
     gr.Markdown(
         "# GYF GPU serving lane\n"
@@ -102,6 +170,18 @@ with gr.Blocks(title="GYF GPU lane") as demo:
         gr.Button("embed_texts").click(
             embed_texts, [model_in, txt_in], txt_out, api_name="embed_texts"
         )
+    with gr.Tab("skintone"):
+        skin_in = gr.Textbox(label="image_b64 (base64 PNG)")
+        skin_out = gr.JSON(label="skin tone")
+        gr.Button("estimate_skin_tone").click(
+            estimate_skin_tone, skin_in, skin_out, api_name="estimate_skin_tone"
+        )
+    with gr.Tab("body"):
+        body_in = gr.Textbox(label="image_b64 (base64 PNG)")
+        body_out = gr.JSON(label="mesh")
+        gr.Button("estimate_body").click(
+            estimate_body, body_in, body_out, api_name="estimate_body"
+        )
 
 
 if __name__ == "__main__":

gyf_contracts/usermodel.py

@@ -0,0 +1,11 @@
+"""Vendored subset of gyf_contracts.usermodel for the GPU Space.
+
+The Space runs the real skin-tone pipeline (usermodel.skintone, copied into this
+repo) which only needs these two sentinels. Kept in lockstep with the canonical
+packages/contracts/gyf_contracts/usermodel.py in the GYF monorepo.
+"""
+
+from __future__ import annotations
+
+UNKNOWN_SKIN_TONE = "unknown"
+UNKNOWN_UNDERTONE = "unknown"

requirements.txt

@@ -9,3 +9,6 @@ numpy
 transformers>=4.40
 sentencepiece
 protobuf
+# Skin-tone lane (M4): RetinaFace face detect + FaRL face-parsing (MIT) for the
+# real CIELAB->MST pipeline vendored under skintone/. CPU-capable; torch already present.
+pyfacer>=0.0.5

skintone/__init__.py

@@ -0,0 +1,34 @@
+"""Skin-tone user-model module (P1-B Cycle 3, ⚠ fairness-gated).
+
+Photo → true-skin pixels (face detect + parse) → white-balance → CIELAB → Monk
+Skin Tone bucket + undertone, with honest per-field confidence. The pure colour
+science (``color``, ``whitebalance``, ``classify``) imports weightless; the real
+segmentation model (``estimator``) lazy-loads its heavy deps only on first use,
+so orchestration and tests run with an injected fake readout.
+
+Surfaced in production only behind the fairness gate (``fairness_eval``); until it
+passes, the module runs in shadow (computed, not shown) — see
+docs/plans/p1b-cycle3-photo-skin-tone.md.
+"""
+
+from __future__ import annotations
+
+from .classify import lab_to_mst, lab_to_undertone
+from .estimate import SkinToneEstimate, estimate_skin_tone
+from .estimator import (
+    DEFAULT_MODEL_VERSION,
+    FaceParsingSkinToneEstimator,
+    SkinReadout,
+    SkinToneEstimator,
+)
+
+__all__ = [
+    "DEFAULT_MODEL_VERSION",
+    "FaceParsingSkinToneEstimator",
+    "SkinReadout",
+    "SkinToneEstimate",
+    "SkinToneEstimator",
+    "estimate_skin_tone",
+    "lab_to_mst",
+    "lab_to_undertone",
+]

skintone/classify.py

@@ -0,0 +1,67 @@
+"""Map a CIELAB skin readout to a Monk Skin Tone bucket + undertone (pure).
+
+Deliberately explainable (no black-box CNN): tone comes from ``L*`` against
+per-bucket anchors, undertone from the ``a*``/``b*`` balance. Explainability is a
+fairness feature — we can audit *why* a tone was assigned, and the anchors are a
+single, reviewable table rather than opaque weights.
+
+⚠ The ``L*`` anchors below are **provisional**, pending calibration against a
+balanced full-MST image set (``fairness_eval.py``). Until that gate passes, the
+module runs in shadow (computed, not surfaced) — see
+docs/plans/p1b-cycle3-photo-skin-tone.md.
+"""
+
+from __future__ import annotations
+
+from gyf_contracts.usermodel import UNKNOWN_SKIN_TONE, UNKNOWN_UNDERTONE
+
+# Provisional L* anchor per MST bucket (lightest mst1 → deepest mst10). Roughly
+# even perceptual spacing across the lightness range observed for facial skin.
+_MST_ANCHORS: list[tuple[str, float]] = [
+    ("mst1", 90.0),
+    ("mst2", 82.0),
+    ("mst3", 74.0),
+    ("mst4", 66.0),
+    ("mst5", 58.0),
+    ("mst6", 50.0),
+    ("mst7", 42.0),
+    ("mst8", 34.0),
+    ("mst9", 27.0),
+    ("mst10", 20.0),
+]
+
+# Half the spacing between adjacent anchors (~4 L*): a reading this far from its
+# nearest anchor sits exactly between two buckets → confidence 0.5.
+_ANCHOR_HALF_STEP = 4.0
+
+# Below this, abstain to "unknown" rather than present a guessed tone (D6 honesty).
+MIN_TONE_CONFIDENCE = 0.45
+
+
+def lab_to_mst(L: float, a: float, b: float) -> tuple[str, float]:
+    """Nearest MST bucket by ``L*`` + a distance-based confidence in [0, 1]."""
+    bucket, anchor_L = min(_MST_ANCHORS, key=lambda kv: abs(kv[1] - L))
+    distance = abs(anchor_L - L)
+    confidence = max(0.0, 1.0 - distance / (2 * _ANCHOR_HALF_STEP))
+    if confidence < MIN_TONE_CONFIDENCE:
+        return UNKNOWN_SKIN_TONE, confidence
+    return bucket, confidence
+
+
+def lab_to_undertone(a: float, b: float) -> tuple[str, float]:
+    """Warm / cool / neutral / olive from the ``a*``/``b*`` balance.
+
+    Warm skin skews yellow (high ``b*``), cool skews pink/blue (``b*`` low
+    relative to ``a*``), olive carries a green-yellow cast (``b*`` high, ``a*``
+    low). Confidence grows with the margin between the leading signal and neutral.
+    """
+    # Neutral band: small chroma in both axes.
+    if abs(b) < 6.0 and abs(a) < 6.0:
+        return "neutral", 0.6
+    if b >= 12.0 and a < 8.0:
+        return "olive", min(1.0, (b - 12.0) / 12.0 + 0.5)
+    if b > a:
+        return "warm", min(1.0, (b - a) / 20.0 + 0.5)
+    if a >= b:
+        return "cool", min(1.0, (a - b) / 20.0 + 0.5)
+    return UNKNOWN_UNDERTONE, 0.4

skintone/color.py

@@ -0,0 +1,53 @@
+"""sRGB → CIELAB conversion (pure numpy, D65).
+
+Perceptually-uniform Lab is the space the skin-tone module reasons in: ``L*`` is
+lightness (drives the Monk Skin Tone bucket) and ``a*``/``b*`` carry undertone
+(warm/cool). Kept dependency-free (no skimage/opencv) so the pure logic imports
+and unit-tests without any heavy runtime.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# D65 reference white (2° observer), the standard for sRGB content.
+_D65 = np.array([95.047, 100.0, 108.883], dtype=np.float64)
+
+# Linear-sRGB → XYZ (sRGB primaries, D65).
+_RGB_TO_XYZ = np.array(
+    [
+        [0.4124564, 0.3575761, 0.1804375],
+        [0.2126729, 0.7151522, 0.0721750],
+        [0.0193339, 0.1191920, 0.9503041],
+    ],
+    dtype=np.float64,
+)
+
+
+def _srgb_to_linear(rgb: np.ndarray) -> np.ndarray:
+    """Undo the sRGB gamma curve. ``rgb`` in [0, 1]."""
+    return np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
+
+
+def _f(t: np.ndarray) -> np.ndarray:
+    delta = 6.0 / 29.0
+    return np.where(t > delta**3, np.cbrt(t), t / (3 * delta**2) + 4.0 / 29.0)
+
+
+def srgb_to_lab(rgb: np.ndarray) -> np.ndarray:
+    """Convert sRGB pixels to CIELAB.
+
+    ``rgb``: array of shape (..., 3) with values in [0, 255] or [0, 1] (auto-
+    detected). Returns the same leading shape with the last axis = (L*, a*, b*).
+    """
+    arr = np.asarray(rgb, dtype=np.float64)
+    if arr.max() > 1.0:
+        arr = arr / 255.0
+    linear = _srgb_to_linear(arr)
+    xyz = linear @ _RGB_TO_XYZ.T
+    xyz_n = xyz / _D65 * 100.0
+    fx, fy, fz = (_f(xyz_n[..., i]) for i in range(3))
+    L = 116.0 * fy - 16.0
+    a = 500.0 * (fx - fy)
+    b = 200.0 * (fy - fz)
+    return np.stack([L, a, b], axis=-1)

skintone/estimate.py

@@ -0,0 +1,49 @@
+"""Skin-tone estimation orchestration.
+
+Ties the real segmentation model (``SkinToneEstimator`` → skin pixels) to the pure
+colour-science classifier (white-balance → CIELAB → MST + undertone), producing a
+:class:`SkinToneEstimate` with honest per-field confidence. The estimator is
+injected, so this orchestration is unit-tested with a fake readout (no model).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .classify import lab_to_mst, lab_to_undertone
+from .estimator import SkinReadout, SkinToneEstimator
+
+
+@dataclass(frozen=True)
+class SkinToneEstimate:
+    """The user-model output for the skin-tone field of a photo profile."""
+
+    skin_tone: str
+    undertone: str
+    field_confidence: dict[str, float] = field(default_factory=dict)
+    model_version: str = ""
+
+
+def estimate_skin_tone(image: object, estimator: SkinToneEstimator) -> SkinToneEstimate:
+    """Estimate skin tone + undertone from a PIL image via ``estimator``.
+
+    Confidence is the product of the classifier's own confidence and the readout's
+    quality (face-detection confidence × skin-pixel coverage) — so a low-quality
+    capture honestly lowers confidence rather than masquerading as certain.
+    """
+    readout: SkinReadout = estimator.estimate(image)
+    L, a, b = readout.lab
+
+    tone, tone_conf = lab_to_mst(L, a, b)
+    undertone, under_conf = lab_to_undertone(a, b)
+
+    quality = readout.face_confidence * readout.coverage
+    return SkinToneEstimate(
+        skin_tone=tone,
+        undertone=undertone,
+        field_confidence={
+            "skin_tone": round(tone_conf * quality, 4),
+            "undertone": round(under_conf * quality, 4),
+        },
+        model_version=readout.model_version,
+    )

skintone/estimator.py

@@ -0,0 +1,152 @@
+"""The face-parsing segmentation model behind the skin-tone module (production).
+
+:class:`SkinToneEstimator` is the abstraction the orchestration depends on; it
+turns a photo into a :class:`SkinReadout` (white-balanced mean CIELAB of true skin
+pixels + quality signals).
+
+:class:`FaceParsingSkinToneEstimator` is the **production** implementation:
+robust in-the-wild **face detection (RetinaFace)** + **neural face-parsing**
+(FaRL, a BiSeNet-class per-pixel segmenter) via ``pyfacer`` (MIT). Per-pixel
+segmentation — not landmark patches — is what makes the tone read robust to pose,
+occlusion, and faces that don't fill the frame, and lets us select *exactly* the
+skin classes (face skin + nose, excluding eyes/brows/lips/hair/glasses) before the
+colour read. Heavy deps (``torch``, ``pyfacer``) are imported lazily inside
+``_load`` so this module — and the whole skin-tone path under a fake — imports and
+unit-tests with no weights. GPU-served on the ML platform; CPU works (slower).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol
+
+import numpy as np
+
+from .color import srgb_to_lab
+from .whitebalance import shades_of_gray
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+
+DEFAULT_MODEL_VERSION = "retinaface-farl-celebm-cielab-mst-v1"
+
+# Face-parsing label names that count as skin for the colour read. FaRL/CelebM and
+# LaPa name classes; we match by name so the estimator is robust to label-index
+# drift across parser checkpoints. Eyes/brows/lips/hair/glasses are excluded.
+_SKIN_LABELS: frozenset[str] = frozenset({"face", "skin", "nose"})
+
+# Drop the brightest/darkest decile of skin luminance (specular highlights, deep
+# shadow) before the colour read so the median Lab reflects diffuse skin.
+_TRIM_PCT = (10.0, 90.0)
+
+
+@dataclass(frozen=True)
+class SkinReadout:
+    """White-balanced mean CIELAB of skin pixels + quality signals."""
+
+    lab: tuple[float, float, float]
+    coverage: float  # fraction of the detected face box segmented as skin
+    face_confidence: float  # detector score for the chosen face, 0.0 if none
+    skin_pixels: int
+    model_version: str = DEFAULT_MODEL_VERSION
+
+
+class SkinToneEstimator(Protocol):
+    """Turns a PIL image into a :class:`SkinReadout`."""
+
+    def estimate(self, image: Image) -> SkinReadout: ...
+
+
+def _select_device() -> str:
+    """Most capable accelerator, excluding Apple MPS (repo device convention)."""
+    import torch
+
+    if torch.cuda.is_available():
+        return "cuda"
+    if hasattr(torch, "xpu") and torch.xpu.is_available():
+        return "xpu"
+    return "cpu"
+
+
+class FaceParsingSkinToneEstimator:
+    """Production estimator: RetinaFace detect → FaRL parse → white-balanced Lab."""
+
+    def __init__(self, device: str | None = None) -> None:
+        self._device = device or os.environ.get("GYF_SKINTONE_DEVICE") or None
+        self._detector: object | None = None
+        self._parser: object | None = None
+        self._torch: object | None = None
+        self._facer: object | None = None
+
+    def _load(self) -> None:
+        if self._parser is not None:
+            return
+        import facer  # lazy: heavy, optional `skintone` extra
+        import torch
+
+        self._torch = torch
+        self._facer = facer
+        if self._device is None:
+            self._device = _select_device()
+        # RetinaFace handles in-the-wild / small / non-frontal faces; FaRL on the
+        # CelebM label set is a strong, commercial-clean per-pixel face parser.
+        self._detector = facer.face_detector("retinaface/mobilenet", device=self._device)
+        self._parser = facer.face_parser("farl/celebm/448", device=self._device)
+
+    def estimate(self, image: Image) -> SkinReadout:
+        self._load()
+        torch = self._torch
+        rgb = np.ascontiguousarray(np.asarray(image.convert("RGB")))
+
+        # facer expects an (1, 3, H, W) uint8 tensor (BCHW, RGB).
+        img_t = torch.from_numpy(rgb).permute(2, 0, 1).unsqueeze(0).to(self._device)
+
+        with torch.inference_mode():
+            faces = self._detector(img_t)
+            if faces is None or len(faces.get("scores", [])) == 0:
+                return SkinReadout((0.0, 0.0, 0.0), coverage=0.0, face_confidence=0.0, skin_pixels=0)
+            faces = self._parser(img_t, faces)
+
+        # Pick the highest-scoring detected face.
+        scores = faces["scores"].detach().cpu().numpy()
+        best = int(np.argmax(scores))
+        seg = faces["seg"]
+        label_names: list[str] = seg["label_names"]
+        # logits: (n_faces, n_classes, H, W) → per-pixel argmax class for our face.
+        logits = seg["logits"][best].detach().cpu().numpy()
+        class_map = logits.argmax(axis=0)
+
+        skin_idx = [i for i, name in enumerate(label_names) if name.lower() in _SKIN_LABELS]
+        if not skin_idx:
+            skin_idx = [i for i, name in enumerate(label_names) if "skin" in name.lower()]
+        skin_mask = np.isin(class_map, skin_idx)
+
+        face_area = float((class_map != _bg_index(label_names)).sum()) or 1.0
+        skin_px = rgb[skin_mask]
+        if skin_px.shape[0] < 50:  # too little skin to read honestly → abstain
+            return SkinReadout((0.0, 0.0, 0.0), coverage=0.0, face_confidence=float(scores[best]), skin_pixels=int(skin_px.shape[0]))
+
+        # White-balance using the skin pixels as the illuminant estimate, then trim
+        # specular highlights / deep shadow before the colour read.
+        balanced = shades_of_gray(skin_px.reshape(1, -1, 3).astype(np.float64)).reshape(-1, 3)
+        lum = balanced.mean(axis=1)
+        lo, hi = np.percentile(lum, _TRIM_PCT)
+        keep = balanced[(lum >= lo) & (lum <= hi)]
+        if keep.size == 0:
+            keep = balanced
+
+        median_lab = np.median(srgb_to_lab(keep), axis=0)
+        return SkinReadout(
+            lab=(float(median_lab[0]), float(median_lab[1]), float(median_lab[2])),
+            coverage=float(skin_mask.sum()) / face_area,
+            face_confidence=float(scores[best]),
+            skin_pixels=int(keep.shape[0]),
+        )
+
+
+def _bg_index(label_names: list[str]) -> int:
+    for i, name in enumerate(label_names):
+        if name.lower() in {"background", "bg"}:
+            return i
+    return -1

skintone/whitebalance.py

@@ -0,0 +1,33 @@
+"""Illumination normalization (pure numpy).
+
+The single biggest fairness lever in skin-tone estimation: an uncorrected colour
+cast (warm indoor light, cool shade) shifts the measured tone and does so
+*unevenly* across the spectrum, which is exactly how naive tone estimators end up
+biased. We white-balance before reading colour so the Lab value reflects skin,
+not the lamp. Shades-of-Gray (Finlayson & Trezzi 2004) generalizes Gray-World and
+is robust and cheap — no model, no GPU.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def shades_of_gray(rgb: np.ndarray, power: float = 6.0, mask: np.ndarray | None = None) -> np.ndarray:
+    """Return ``rgb`` white-balanced via the Shades-of-Gray assumption.
+
+    ``rgb``: (H, W, 3) in [0, 255]. ``power`` = the Minkowski norm order (1 ==
+    Gray-World, ∞ == max-RGB; 6 is a robust default). ``mask``: optional bool
+    (H, W) selecting the pixels used to estimate the illuminant (e.g. skin only),
+    while the gains are applied to the whole image.
+    """
+    arr = np.asarray(rgb, dtype=np.float64)
+    pixels = arr[mask] if mask is not None else arr.reshape(-1, 3)
+    if pixels.size == 0:
+        return arr
+    # Per-channel Minkowski mean = illuminant estimate.
+    illum = np.power(np.mean(np.power(pixels, power), axis=0), 1.0 / power)
+    illum = np.where(illum <= 1e-6, 1.0, illum)
+    gray = float(np.mean(illum))
+    gains = gray / illum
+    return np.clip(arr * gains, 0, 255)