Add FastAPI Docker backend for know-your-skin demo

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.10-slim
+
+# Install basic system dependencies (you may extend this if builds fail)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Hugging Face Spaces route traffic to port 7860 by default
+EXPOSE 7860
+
+# Start FastAPI via Uvicorn
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+
+

api/__init__.py

@@ -0,0 +1,5 @@
+"""
+API package exposing HTTP endpoints for the skin analysis pipeline.
+"""
+
+

api/server.py

@@ -0,0 +1,127 @@
+from tempfile import NamedTemporaryFile
+from typing import Any, Dict, List
+import os
+import shutil
+
+from fastapi import FastAPI, File, UploadFile, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+
+from lib.full_analysis import analyze_full_image, analyze_full_session
+
+
+app = FastAPI(
+    title="Hudson Skin Analysis API",
+    description=(
+        "Local API for running Derm Foundation + SCIN-based cosmetic attributes "
+        "and concern analysis, returning a combined narrative report with Hudson "
+        "product recommendations."
+    ),
+    version="0.2.0",
+)
+
+# For prototype purposes, allow all origins. You can tighten this later.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+def health() -> Dict[str, str]:
+    """Simple health check endpoint."""
+    return {"status": "ok"}
+
+
+@app.post("/analyze")
+async def analyze(image: UploadFile = File(...)) -> Dict[str, Any]:
+    """
+    Analyze a single skin image and return a combined JSON structure:
+
+    {
+      "cosmetic": { ... },  # tone / type education
+      "concerns": { ... }   # concern sections + routine + disclaimer
+    }
+
+    Expected request (multipart/form-data):
+        - field name: 'image'
+        - value: image file (JPEG/PNG)
+    """
+    if not image.filename:
+        raise HTTPException(status_code=400, detail="Uploaded file must have a filename.")
+
+    # Basic content-type check (relaxed for prototype)
+    if image.content_type and not image.content_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail="Uploaded file must be an image.")
+
+    suffix = os.path.splitext(image.filename)[1] or ".jpg"
+
+    with NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
+        tmp_path = tmp.name
+        shutil.copyfileobj(image.file, tmp)
+
+    try:
+        # cosmetic + concerns in one call so the mobile app can show both layers
+        result = analyze_full_image(tmp_path)
+    except Exception as exc:  # pragma: no cover - thin wrapper
+        raise HTTPException(status_code=500, detail=f"Analysis failed: {exc}") from exc
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+
+    return result
+
+
+@app.post("/analyze_session")
+async def analyze_session(images: List[UploadFile] = File(...)) -> Dict[str, Any]:
+    """
+    Analyze multiple images from the same person and return a single
+    session-level combined JSON structure (cosmetic + concerns).
+
+    Expected request (multipart/form-data):
+        - field name: 'images'
+        - value: one or more image files (JPEG/PNG)
+
+    This uses the same report shape as /analyze, but aggregates
+    probabilities across all provided images before building the report.
+    """
+    if not images:
+        raise HTTPException(status_code=400, detail="At least one image must be provided.")
+
+    tmp_paths: List[str] = []
+
+    try:
+        for image in images:
+            if not image.filename:
+                raise HTTPException(status_code=400, detail="Each uploaded file must have a filename.")
+
+            if image.content_type and not image.content_type.startswith("image/"):
+                raise HTTPException(status_code=400, detail="All uploaded files must be images.")
+
+            suffix = os.path.splitext(image.filename)[1] or ".jpg"
+            with NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
+                tmp_path = tmp.name
+                shutil.copyfileobj(image.file, tmp)
+            tmp_paths.append(tmp_path)
+
+        result = analyze_full_session(tmp_paths)
+    except HTTPException:
+        # Re-raise FastAPI HTTP errors unchanged
+        raise
+    except Exception as exc:  # pragma: no cover - thin wrapper
+        raise HTTPException(status_code=500, detail=f"Session analysis failed: {exc}") from exc
+    finally:
+        for path in tmp_paths:
+            try:
+                os.remove(path)
+            except OSError:
+                pass
+
+    return result
+
+
+

app.py

@@ -0,0 +1,3 @@
+from api.server import app
+
+

config/__init__.py

@@ -0,0 +1,5 @@
+"""
+Configuration package for concern tags, mappings, and product recommendations.
+"""
+
+

config/concerns.py

@@ -0,0 +1,224 @@
+"""
+Definitions for high-level skin concerns, mappings from SCIN condition labels,
+and user-facing messaging + product hooks for the prototype.
+"""
+
+from typing import Dict, List
+
+
+# Six customer-facing concern tags
+CONCERN_TAGS: List[str] = [
+    "Dry_Sensitive",
+    "Breakouts_Bumps",
+    "Itchy_Hives",
+    "Red_Scaly_Patches",
+    "Pigment_Tone_Issues",
+    "Possible_Infection",
+]
+
+
+# Minimum dermatologist confidence (1–5) for using a SCIN label
+MIN_DERM_CONFIDENCE: int = 3
+
+
+# Mapping from SCIN condition label (exact string) to one or more concern tags.
+# This is not exhaustive; we only map the most common / relevant conditions for
+# this prototype. Unmapped conditions are ignored when building concern labels.
+CONCERN_MAP: Dict[str, List[str]] = {
+    # Dry / sensitive / eczematous patterns
+    "Eczema": ["Dry_Sensitive"],
+    "Acute dermatitis, NOS": ["Dry_Sensitive"],
+    "Acute and chronic dermatitis": ["Dry_Sensitive"],
+    "Seborrheic Dermatitis": ["Dry_Sensitive", "Red_Scaly_Patches"],
+    "Irritant Contact Dermatitis": ["Dry_Sensitive"],
+    "Allergic Contact Dermatitis": ["Dry_Sensitive", "Itchy_Hives"],
+    "CD - Contact dermatitis": ["Dry_Sensitive"],
+    "Stasis Dermatitis": ["Dry_Sensitive", "Red_Scaly_Patches"],
+    "Lichen Simplex Chronicus": ["Dry_Sensitive"],
+
+    # Breakouts / bumps
+    "Acne": ["Breakouts_Bumps"],
+    "Folliculitis": ["Breakouts_Bumps"],
+    "Molluscum Contagiosum": ["Breakouts_Bumps"],
+    "Prurigo nodularis": ["Breakouts_Bumps", "Dry_Sensitive"],
+
+    # Itchy / hives / bites / hypersensitivity
+    "Insect Bite": ["Itchy_Hives"],
+    "Urticaria": ["Itchy_Hives"],
+    "Hypersensitivity": ["Itchy_Hives"],
+    "Viral Exanthem": ["Itchy_Hives", "Possible_Infection"],
+
+    # Red, scaly patches / inflammatory plaques
+    "Psoriasis": ["Red_Scaly_Patches"],
+    "Pityriasis rosea": ["Red_Scaly_Patches"],
+    "Lichen planus/lichenoid eruption": ["Red_Scaly_Patches"],
+    "Pityriasis lichenoides": ["Red_Scaly_Patches"],
+    "Cutaneous lupus": ["Red_Scaly_Patches"],
+
+    # Pigmentation / tone issues
+    "Post-Inflammatory hyperpigmentation": ["Pigment_Tone_Issues"],
+    "Pigmented purpuric eruption": ["Pigment_Tone_Issues"],
+    "Keratosis pilaris": ["Pigment_Tone_Issues", "Breakouts_Bumps"],
+    "O/E - ecchymoses present": ["Pigment_Tone_Issues"],
+
+    # Possible infections (use carefully, non-diagnostic wording)
+    "Tinea": ["Possible_Infection"],
+    "Tinea Versicolor": ["Possible_Infection", "Pigment_Tone_Issues"],
+    "Impetigo": ["Possible_Infection"],
+    "Herpes Zoster": ["Possible_Infection"],
+    "Herpes Simplex": ["Possible_Infection"],
+    "Cellulitis": ["Possible_Infection"],
+    "Abscess": ["Possible_Infection"],
+    "Scabies": ["Possible_Infection", "Itchy_Hives"],
+}
+
+
+# User-facing messaging and product hooks per concern tag.
+# Product IDs are placeholders for now – replace with real SKUs from your catalog.
+CONCERN_CONFIG: Dict[str, Dict[str, object]] = {
+    "Dry_Sensitive": {
+        "title": "Dry or Sensitive Skin Tendencies",
+        "description": (
+            "Your photo shows patterns often associated with dry or easily irritated skin. "
+            "This may include visible flaking, redness, or rough patches."
+        ),
+        "what_it_means": (
+            "These features suggest that your skin barrier may be a bit fragile or dehydrated, "
+            "so it can lose moisture more quickly and react to harsh products or weather changes."
+        ),
+        "care_focus": (
+            "Focus on gentle cleansing, replenishing moisture, and protecting the skin barrier with "
+            "soothing, fragrance-free products."
+        ),
+        "disclaimer": (
+            "This is an AI-based cosmetic skin analysis, not a medical diagnosis. "
+            "If you have pain, rapid changes, or health concerns, please see a dermatologist."
+        ),
+        "recommended_products": [
+            "hydrating_cleanser",
+            "barrier_repair_moisturizer",
+            "gentle_spf",
+        ],
+    },
+    "Breakouts_Bumps": {
+        "title": "Breakouts and Bumps",
+        "description": (
+            "We detect patterns often seen with clogged pores, breakouts, or follicle-related bumps."
+        ),
+        "what_it_means": (
+            "This can happen when excess oil, dead skin, or bacteria build up in pores or around hair follicles, "
+            "leading to blemishes or tiny bumps on the skin."
+        ),
+        "care_focus": (
+            "Focus on balancing oil, gently exfoliating to keep pores clear, and avoiding products that clog pores."
+        ),
+        "disclaimer": (
+            "This is not a medical diagnosis. For severe, painful, or persistent acne, "
+            "consult a dermatologist."
+        ),
+        "recommended_products": [
+            "clarifying_cleanser",
+            "lightweight_noncomedogenic_moisturizer",
+            "targeted_bha_serum",
+        ],
+    },
+    "Itchy_Hives": {
+        "title": "Itch, Hives, or Bite-like Areas",
+        "description": (
+            "Your image shows patterns that can be seen with itchy, hive-like, or bite-like areas."
+        ),
+        "what_it_means": (
+            "These patterns may reflect irritation or a reactive response in the skin, which can be triggered by "
+            "many factors such as friction, bites, or contact with allergens."
+        ),
+        "care_focus": (
+            "Focus on calming and protecting the skin, avoiding harsh products, and keeping the area moisturized "
+            "without over-scrubbing."
+        ),
+        "disclaimer": (
+            "Only a clinician can diagnose allergic reactions or bites. "
+            "If symptoms are severe, spreading, or accompanied by other signs, seek medical care."
+        ),
+        "recommended_products": [
+            "soothing_lotion",
+            "fragrance_free_moisturizer",
+        ],
+    },
+    "Red_Scaly_Patches": {
+        "title": "Red or Scaly Patches",
+        "description": (
+            "We see features that may correspond to red, scaly, or plaque-like areas on the skin."
+        ),
+        "what_it_means": (
+            "Red and scaly areas can appear when the skin is inflamed and turning over more quickly, "
+            "which is seen in several common skin conditions."
+        ),
+        "care_focus": (
+            "Focus on very gentle cleansing, rich but non-irritating moisturizers, and daily sun protection "
+            "to support the skin while you discuss any persistent patches with a professional."
+        ),
+        "disclaimer": (
+            "Conditions like psoriasis or dermatitis require professional diagnosis. "
+            "This analysis is cosmetic only and may miss important findings."
+        ),
+        "recommended_products": [
+            "rich_emollient_cream",
+            "gentle_scalp_or_body_wash",
+        ],
+    },
+    "Pigment_Tone_Issues": {
+        "title": "Pigment and Tone Irregularities",
+        "description": (
+            "Your photo shows patterns that can be associated with uneven skin tone or spots, "
+            "such as post-blemish marks or areas of darker or lighter pigmentation."
+        ),
+        "what_it_means": (
+            "These findings suggest that your skin may be developing or holding onto areas of extra or reduced pigment, "
+            "often after breakouts, sun exposure, or previous irritation."
+        ),
+        "care_focus": (
+            "Focus on consistent sun protection and targeted brightening steps, while keeping the skin barrier healthy "
+            "and avoiding aggressive at-home treatments."
+        ),
+        "disclaimer": (
+            "This is not a diagnosis of any pigment disorder. "
+            "If you notice rapidly changing spots or moles, see a dermatologist."
+        ),
+        "recommended_products": [
+            "brightening_serum",
+            "daily_spf",
+            "gentle_exfoliant",
+        ],
+    },
+    "Possible_Infection": {
+        "title": "Patterns Sometimes Seen in Infections",
+        "description": (
+            "Some features in the image can be seen in skin infections or overgrowth of microbes. "
+            "Only a medical professional can confirm this."
+        ),
+        "what_it_means": (
+            "This may reflect areas where the skin barrier is disrupted and microbes can more easily grow, "
+            "but many look-alike conditions exist, so only a clinician can tell what is really going on."
+        ),
+        "care_focus": (
+            "Focus on gentle cleansing, supporting the skin barrier, and seeking in-person medical advice for "
+            "painful, spreading, or worrying areas."
+        ),
+        "disclaimer": (
+            "This tool cannot rule out serious conditions. If you have pain, fever, "
+            "rapid spreading, or feel unwell, please seek urgent medical advice."
+        ),
+        "recommended_products": [
+            "gentle_cleanser",
+            "barrier_support_moisturizer",
+        ],
+    },
+}
+
+
+def get_concern_index_map() -> Dict[str, int]:
+    """Return a mapping from concern tag name to column index."""
+    return {name: idx for idx, name in enumerate(CONCERN_TAGS)}
+
+
+

config/cosmetic_copy.py

@@ -0,0 +1,147 @@
+"""
+Copy and educational content for cosmetic attributes.
+
+This is used by the cosmetic reporting layer to turn predictions into
+user-friendly text. All wording here is cosmetic/non-medical.
+"""
+
+from typing import Dict, Any
+
+
+# Fitzpatrick skin type copy
+FST_COPY: Dict[str, Dict[str, Any]] = {
+    "FST1": {
+        "title": "Fitzpatrick Type I (very fair, always burns)",
+        "overview": (
+            "This type of skin is very fair and tends to burn easily with minimal sun exposure "
+            "and rarely tans. It often needs extra gentle care and diligent daily sun protection."
+        ),
+        "care_focus": (
+            "Prioritize broad-spectrum sunscreen every day, seek shade where possible, and build up active "
+            "ingredients gradually to avoid irritation. Hydrating, barrier-supporting products are usually helpful."
+        ),
+    },
+    "FST2": {
+        "title": "Fitzpatrick Type II (fair, usually burns, may tan lightly)",
+        "overview": (
+            "This type of skin is fair and can burn with sun exposure, sometimes followed by a light tan. "
+            "It has moderate sensitivity to the sun."
+        ),
+        "care_focus": (
+            "Daily SPF and gentle hydrators are key. Introduce exfoliants and brightening ingredients slowly and "
+            "watch for dryness or redness."
+        ),
+    },
+    "FST3": {
+        "title": "Fitzpatrick Type III (medium, sometimes burns, gradually tans)",
+        "overview": (
+            "This type of skin has a light-to-medium tone, may burn with strong sun at first, and then gradually tans. "
+            "It can be somewhat prone to uneven tone or post-blemish marks."
+        ),
+        "care_focus": (
+            "Consistent SPF helps prevent dark spots. Balanced routines with gentle exfoliation and brightening products "
+            "can support an even, healthy-looking tone."
+        ),
+    },
+    "FST4": {
+        "title": "Fitzpatrick Type IV (olive to brown, rarely burns, tans easily)",
+        "overview": (
+            "This type of skin is naturally deeper in color and tends to tan easily while rarely burning. "
+            "It may be more prone to pigmentation changes after irritation or breakouts."
+        ),
+        "care_focus": (
+            "Daily sunscreen is still important to protect against long-term damage and uneven tone. "
+            "Focus on gentle, non-irritating actives and hydrating care to support a smooth, radiant complexion."
+        ),
+    },
+    "FST5": {
+        "id": "FST5",
+        "title": "Fitzpatrick Type V (brown, rarely burns, tans deeply)",
+        "overview": (
+            "This type of skin has a deeper brown tone, usually tans deeply and rarely burns. "
+            "It can be more prone to dark marks lingering after inflammation."
+        ),
+        "care_focus": (
+            "Gentle daily cleansing, consistent SPF, and pigment-safe brightening ingredients can help manage "
+            "uneven tone while maintaining the skin's natural richness."
+        ),
+    },
+    "FST6": {
+        "title": "Fitzpatrick Type VI (very dark, deeply pigmented)",
+        "overview": (
+            "This type of skin is very richly pigmented and typically does not burn, but can still experience sun damage "
+            "and is often prone to visible dark marks after irritation."
+        ),
+        "care_focus": (
+            "Broad-spectrum sunscreen is still valuable to protect skin health and tone. Focus on barrier support, "
+            "hydration, and gentle brightening where needed, avoiding harsh or stripping products."
+        ),
+    },
+}
+
+
+# Monk tone copy grouped into simple ranges for education.
+MONK_TONE_RANGES = [
+    {"name": "lighter tones", "range": range(1, 4)},
+    {"name": "medium tones", "range": range(4, 8)},
+    {"name": "deeper tones", "range": range(8, 11)},
+]
+
+MONK_COPY: Dict[str, str] = {
+    "lighter tones": (
+        "On lighter skin tones, redness and sunburn often show up quickly, while dark marks may appear tan or pink. "
+        "Consistent sunscreen and gentle barrier care help prevent irritation and long-term discoloration."
+    ),
+    "medium tones": (
+        "On medium skin tones, both redness and dark marks can appear, especially after breakouts or sun exposure. "
+        "Daily SPF and balanced routines with hydrating and brightening ingredients support an even complexion."
+    ),
+    "deeper tones": (
+        "On deeper skin tones, dark spots and uneven patches may linger longer, even if redness is less visible. "
+        "Sun protection plus pigment-safe brightening products can help maintain a smooth, radiant tone."
+    ),
+}
+
+
+# Texture copy per tag.
+TEXTURE_COPY: Dict[str, Dict[str, str]] = {
+    "Texture_Smooth": {
+        "title": "Mostly smooth texture",
+        "body": (
+            "Your skin texture looks mostly smooth and even in this photo. That’s a great foundation. "
+            "A gentle cleanser, consistent moisturizer, and daily sunscreen can help keep it that way."
+        ),
+    },
+    "Texture_Bumpy": {
+        "title": "Uneven or bumpy texture",
+        "body": (
+            "We see some raised or bumpy areas that can happen with clogged pores or small textural changes. "
+            "Gentle exfoliation, non-comedogenic hydrators, and balanced oil control can help smooth the look over time."
+        ),
+    },
+    "Texture_Rough_Flakey": {
+        "title": "Dry or flaky texture",
+        "body": (
+            "Your skin shows some rough or flaky areas, which often indicate dryness or a compromised barrier. "
+            "Hydrating cleansers, richer moisturizers, and barrier-supporting ingredients can help restore softness."
+        ),
+    },
+    "Texture_Fluid_Filled": {
+        "title": "Fluid-filled or very raised areas",
+        "body": (
+            "We notice some fluid-filled or very raised areas. While some bumps can be part of normal skin, "
+            "sudden or painful changes are best reviewed with a dermatologist. In the meantime, focus on gentle care "
+            "and avoid picking or harsh scrubs."
+        ),
+    },
+}
+
+
+COSMETIC_DISCLAIMER = (
+    "The information above describes cosmetic characteristics such as skin tone and texture based on this single photo. "
+    "It is not a medical diagnosis and may not capture the full picture of your skin. For any concerns, persistent "
+    "changes, or symptoms like pain or bleeding, please consult a dermatologist or healthcare professional."
+)
+
+
+

config/cosmetic_targets.py

@@ -0,0 +1,52 @@
+"""
+Canonical label mappings for cosmetic skin attributes derived from SCIN:
+
+- Fitzpatrick Skin Type (FST I–VI)
+- Monk Skin Tone (1–10)
+- Texture tags (smooth / bumpy / rough/flaky / optional fluid-filled)
+
+These mappings are used by the cosmetic attribute training and inference code.
+"""
+
+from typing import Dict, List
+
+
+# Canonical Fitzpatrick labels we expose in our cosmetic layer.
+# SCIN stores values such as "FST1" .. "FST6" or "NONE_SELECTED".
+FST_LABELS: List[str] = ["FST1", "FST2", "FST3", "FST4", "FST5", "FST6"]
+
+# Values in the SCIN CSV for Fitzpatrick skin type from users / dermatologists
+# are expected to match these strings. Any value not in this set (e.g.
+# "NONE_SELECTED" or missing) will be treated as unknown and skipped for
+# training.
+VALID_FST_VALUES = set(FST_LABELS)
+
+
+# Monk skin tone labels (1–10). SCIN stores these as integers 1..10.
+MONK_TONE_VALUES: List[int] = list(range(1, 11))
+
+
+# Cosmetic texture tags we expose in our report.
+TEXTURE_TAGS: List[str] = [
+    "Texture_Smooth",
+    "Texture_Bumpy",
+    "Texture_Rough_Flakey",
+    "Texture_Fluid_Filled",
+]
+
+# Mapping from SCIN textures_* column suffix to our cosmetic texture tags.
+# SCIN schema describes textures_* booleans with suffixes such as:
+#   - TEXTURE_UNSPECIFIED
+#   - RAISED_OR_BUMPY
+#   - FLAT
+#   - ROUGH_OR_FLAKY
+#   - FLUID_FILLED
+TEXTURE_FIELD_TO_TAG: Dict[str, str] = {
+    "RAISED_OR_BUMPY": "Texture_Bumpy",
+    "ROUGH_OR_FLAKY": "Texture_Rough_Flakey",
+    "FLAT": "Texture_Smooth",
+    "FLUID_FILLED": "Texture_Fluid_Filled",
+}
+
+
+

config/hudson_products.py

@@ -0,0 +1,209 @@
+"""
+Product configuration for Hudson skincare products, normalized for recommendations.
+
+We derive a compact schema from `hudson-product-portfolio/hudson_skincare_products.json`
+and add:
+  - a stable `id` for each product
+  - a primary routine `step` (cleanser / treatment / moisturizer / sunscreen / other)
+  - which concern tags each product is suitable for
+
+Concern tags must match those defined in `config.concerns.CONCERN_TAGS`.
+"""
+
+from typing import Dict, List, TypedDict
+
+
+class ProductConfig(TypedDict):
+    id: str
+    name: str
+    step: str
+    supported_concerns: List[str]
+    portfolio: str | None
+    why_template: str | None
+    # Optional image filename (e.g. "daily_moisturizer.png") relative to a
+    # known product-images directory. The API will surface this so the client
+    # can display product images when available.
+    image_name: str | None
+
+
+# Normalized configuration for the current Hudson product list.
+# Keys are stable product IDs; values include step and concern mapping.
+PRODUCT_CONFIG: Dict[str, ProductConfig] = {
+    # Hydration / Dry & Sensitive focused
+    "b5_serum": {
+        "id": "b5_serum",
+        "name": "B5 Serum",
+        "step": "treatment",
+        "supported_concerns": ["Dry_Sensitive", "Pigment_Tone_Issues"],
+        "portfolio": "Hydration/Moisturising",
+        "why_template": (
+            "Because your skin shows signs of dryness or tone irregularities, "
+            "we suggest {name}, a lightweight hydrating serum that helps plump and support the skin barrier."
+        ),
+        "image_name": None,
+    },
+    "body_clarifying_cleanser": {
+        "id": "body_clarifying_cleanser",
+        "name": "Body Clarifying Cleanser",
+        "step": "cleanser",
+        "supported_concerns": ["Dry_Sensitive", "Itchy_Hives", "Possible_Infection", "Red_Scaly_Patches"],
+        "portfolio": "Hydration/Moisturising",
+        "why_template": (
+            "We recommend {name}, a gentle body cleanser designed to cleanse and moisturize dry or reactive skin "
+            "without harsh surfactants."
+        ),
+        "image_name": "body_clarifying_cleanser.png",
+    },
+    "daily_moisturizer": {
+        "id": "daily_moisturizer",
+        "name": "Daily Moisturizer",
+        "step": "moisturizer",
+        "supported_concerns": ["Dry_Sensitive", "Red_Scaly_Patches", "Itchy_Hives"],
+        "portfolio": "Hydration/Moisturising",
+        "why_template": (
+            "{name} is a everyday moisturizer formulated for sensitive, dry, or redness-prone skin, "
+            "to help keep the barrier comfortable and hydrated."
+        ),
+        "image_name": "daily_moisturizer.png",
+    },
+    "facial_moisture_balancing_cleanser": {
+        "id": "facial_moisture_balancing_cleanser",
+        "name": "Facial Moisture Balancing Cleanser",
+        "step": "cleanser",
+        "supported_concerns": ["Dry_Sensitive", "Red_Scaly_Patches", "Itchy_Hives"],
+        "portfolio": "Hydration/Moisturising",
+        "why_template": (
+            "{name} is a gentle facial cleanser that helps remove impurities while respecting a dry or sensitive skin barrier."
+        ),
+        "image_name": None,
+    },
+    "moisture_balancing_cleanser": {
+        "id": "moisture_balancing_cleanser",
+        "name": "Moisture Balancing Cleanser",
+        "step": "cleanser",
+        "supported_concerns": ["Dry_Sensitive", "Itchy_Hives", "Red_Scaly_Patches", "Breakouts_Bumps"],
+        "portfolio": "Hydration+Anti Acne",
+        "why_template": (
+            "{name} gently cleanses while supporting dry, sensitive, or acne-prone areas with a hypochlorous-based formula."
+        ),
+        # Map the generic "hudson-cleanser.png" image to this cleanser.
+        "image_name": "hudson-cleanser.png",
+    },
+
+    # Anti-acne portfolio / breakouts
+    "blemish_age_defense_serum": {
+        "id": "blemish_age_defense_serum",
+        "name": "Blemish + Age Defense Serum",
+        "step": "treatment",
+        "supported_concerns": ["Breakouts_Bumps", "Pigment_Tone_Issues"],
+        "portfolio": "Anti Acne Portfolio",
+        "why_template": (
+            "Since we see features linked to breakouts or post-blemish marks, {name} can help clarify pores, "
+            "balance oil, and improve the look of blemishes over time."
+        ),
+        "image_name": "blemish_plus_age_defense_serum.png",
+    },
+    "salicylic_acid_cleanser": {
+        "id": "salicylic_acid_cleanser",
+        "name": "Salicylic Acid Cleanser",
+        "step": "cleanser",
+        "supported_concerns": ["Breakouts_Bumps", "Possible_Infection"],
+        "portfolio": "Anti Acne Portfolio",
+        "why_template": (
+            "{name} combines salicylic acid with a hypochlorous base to help reduce excess oil, clear pores, "
+            "and support skin that is prone to acne breakouts."
+        ),
+        "image_name": "salicylic_acid_cleanser.png",
+    },
+    "silymarin_c15_serum": {
+        "id": "silymarin_c15_serum",
+        "name": "Silymarin C15 Serum",
+        "step": "treatment",
+        "supported_concerns": ["Breakouts_Bumps", "Pigment_Tone_Issues"],
+        "portfolio": "Anti Acne Portfolio",
+        "why_template": (
+            "{name} pairs vitamin C with targeted actives to help reduce blemishes, refine texture, "
+            "and support a more even-looking tone."
+        ),
+        "image_name": "silymarin_c15_serum.png",
+    },
+
+    # Pigment / anti-discoloration / antioxidant
+    "brightening_cream": {
+        "id": "brightening_cream",
+        "name": "Brightening Cream",
+        "step": "treatment",
+        "supported_concerns": ["Pigment_Tone_Issues"],
+        "portfolio": "Anti Ageing/ Anti Discoloration Portfolio",
+        "why_template": (
+            "Because your skin shows tone irregularities or dark spots, {name} is a night treatment designed to "
+            "gradually fade discoloration and brighten overall radiance."
+        ),
+        "image_name": None,
+    },
+    "discoloration_defense_serum": {
+        "id": "discoloration_defense_serum",
+        "name": "Discoloration Defense Serum",
+        "step": "treatment",
+        "supported_concerns": ["Pigment_Tone_Issues"],
+        "portfolio": "Anti Ageing/ Anti Discoloration Portfolio",
+        "why_template": (
+            "{name} targets stubborn discoloration and uneven tone, making it a good fit when we detect pigment-related concerns."
+        ),
+        "image_name": "discoloartion-defense_serum.png",
+    },
+    "c15_antioxidant_serum": {
+        "id": "c15_antioxidant_serum",
+        "name": "C15 Antioxidant Serum",
+        "step": "treatment",
+        "supported_concerns": ["Pigment_Tone_Issues", "Breakouts_Bumps"],
+        "portfolio": "Anti Ageing/ Anti Discoloration Portfolio",
+        "why_template": (
+            "{name} delivers antioxidant vitamin C to help soften the look of fine lines and uneven tone, "
+            "while supporting blemish-prone skin."
+        ),
+        "image_name": "c15_anti_oxidant_serum.png",
+    },
+
+    # Sunscreens (recommended across many concerns, especially pigment)
+    "facial_gel_sunscreen": {
+        "id": "facial_gel_sunscreen",
+        "name": "Facial Gel Sunscreen",
+        "step": "sunscreen",
+        "supported_concerns": ["Pigment_Tone_Issues", "Dry_Sensitive", "Red_Scaly_Patches", "Breakouts_Bumps", "Itchy_Hives", "Possible_Infection"],
+        "portfolio": "Sunscreen",
+        "why_template": (
+            "Daily SPF is essential when any skin concern is present. {name} offers broad-spectrum protection in a "
+            "lightweight, no-white-cast gel formula that fits easily into most routines."
+        ),
+        "image_name": None,
+    },
+    "facial_sunscreen_gel": {
+        "id": "facial_sunscreen_gel",
+        "name": "Facial Sunscreen Gel",
+        "step": "sunscreen",
+        "supported_concerns": ["Pigment_Tone_Issues", "Dry_Sensitive", "Red_Scaly_Patches", "Breakouts_Bumps", "Itchy_Hives", "Possible_Infection"],
+        "portfolio": "Sunscreen",
+        "why_template": (
+            "Because consistent sun protection helps with nearly all skin goals, {name} is recommended as a "
+            "broad-spectrum gel sunscreen that layers well over your routine."
+        ),
+        "image_name": None,
+    },
+}
+
+
+ROUTINE_STEPS: List[str] = ["cleanser", "treatment", "moisturizer", "sunscreen"]
+
+
+def load_product_config() -> Dict[str, ProductConfig]:
+    """
+    Return the normalized product configuration.
+
+    For now we keep this static and do not dynamically parse the JSON file,
+    since the set of products is small and stable for the prototype.
+    """
+    return PRODUCT_CONFIG
+
+
+

lib/concern_inference.py

@@ -0,0 +1,135 @@
+import functools
+from pathlib import Path
+from typing import Dict, List, Any
+
+import joblib
+import numpy as np
+
+from config.concerns import CONCERN_CONFIG, CONCERN_TAGS
+from config.hudson_products import load_product_config
+from lib.derm_local import embed_image_path
+from lib.recommendations import build_routine
+from lib.reporting import build_report
+
+
+@functools.lru_cache(maxsize=1)
+def _load_models(models_dir: str = "models") -> Dict[str, Any]:
+    """Load scaler and concern classifier from disk (cached)."""
+    models_path = Path(models_dir)
+    scaler_path = models_path / "scin_concerns_scaler.joblib"
+    model_path = models_path / "scin_concerns_logreg.joblib"
+
+    if not scaler_path.exists() or not model_path.exists():
+        raise FileNotFoundError(
+            f"Expected concern models not found in {models_path}. "
+            "Run `python scripts/train_scins_concerns.py` first."
+        )
+
+    scaler = joblib.load(scaler_path)
+    clf = joblib.load(model_path)
+    return {"scaler": scaler, "clf": clf}
+
+
+def _proba_to_binary(proba_list: List[np.ndarray], threshold: float = 0.5) -> np.ndarray:
+    cols = []
+    for p in proba_list:
+        if p.shape[1] == 2:
+            cols.append((p[:, 1] >= threshold).astype(int))
+        else:
+            cols.append((p[:, -1] >= threshold).astype(int))
+    return np.column_stack(cols)
+
+
+def analyze_embedding(
+    embedding: np.ndarray,
+    models_dir: str = "models",
+    threshold: float = 0.5,
+) -> Dict[str, Any]:
+    """
+    Run the trained concern classifier on a single Derm Foundation embedding.
+
+    Returns a dict keyed by concern tag with probability, active flag, and
+    user-facing metadata from CONCERN_CONFIG.
+    """
+    if embedding.ndim == 1:
+        embedding = embedding.reshape(1, -1)
+
+    models = _load_models(models_dir)
+    scaler = models["scaler"]
+    clf = models["clf"]
+
+    emb_std = scaler.transform(embedding)
+    proba_list = clf.predict_proba(emb_std)
+
+    probs = []
+    for p in proba_list:
+        if p.shape[1] == 2:
+            probs.append(float(p[0, 1]))
+        else:
+            probs.append(float(p[0, -1]))
+
+    preds = _proba_to_binary(proba_list, threshold=threshold)[0]
+
+    result: Dict[str, Any] = {}
+    for idx, tag in enumerate(CONCERN_TAGS):
+        cfg = CONCERN_CONFIG.get(tag, {})
+        result[tag] = {
+            "prob": probs[idx],
+            "active": bool(preds[idx]),
+            "title": cfg.get("title", tag),
+            "description": cfg.get("description", ""),
+            "disclaimer": cfg.get("disclaimer", ""),
+            "recommended_products": cfg.get("recommended_products", []),
+        }
+    return result
+
+
+def analyze_image(
+    image_path: str,
+    models_dir: str = "models",
+    threshold: float = 0.5,
+) -> Dict[str, Any]:
+    """
+    High-level helper: embed a local image with Derm Foundation and run the
+    concern classifier.
+    """
+    emb = embed_image_path(image_path)
+    return analyze_embedding(emb, models_dir=models_dir, threshold=threshold)
+
+
+def analyze_image_with_routine(
+    image_path: str,
+    models_dir: str = "models",
+    threshold: float = 0.5,
+) -> Dict[str, Any]:
+    """
+    Extended helper: run concern analysis and build a product routine
+    using the Hudson product configuration.
+    """
+    concerns = analyze_image(image_path, models_dir=models_dir, threshold=threshold)
+    product_cfg = load_product_config()
+    routine = build_routine(concerns, product_cfg)
+    return {
+        "concerns": concerns,
+        "routine": routine,
+    }
+
+
+def analyze_image_report(
+    image_path: str,
+    models_dir: str = "models",
+    threshold: float = 0.5,
+) -> Dict[str, Any]:
+    """
+    Full pipeline: embed image, get concerns, build routine, and assemble
+    a user-friendly report structure.
+    """
+    concerns_only = analyze_image(image_path, models_dir=models_dir, threshold=threshold)
+    product_cfg = load_product_config()
+    routine = build_routine(concerns_only, product_cfg)
+    report = build_report(concerns_only, routine)
+    return report
+
+
+
+

lib/cosmetic_inference.py

@@ -0,0 +1,143 @@
+import functools
+from pathlib import Path
+from typing import Any, Dict, List
+
+import joblib
+import numpy as np
+
+from config.cosmetic_targets import FST_LABELS, MONK_TONE_VALUES, TEXTURE_TAGS
+from lib.derm_local import embed_image_path
+
+
+COSMETIC_MODELS_DIR_DEFAULT = "models/cosmetic"
+
+
+# Filenames for Fitzpatrick models. We default to the MLP version when present,
+# but keep the original logistic regression as a fallback.
+FST_MLP_SCALER_NAME = "fst_mlp_scaler.joblib"
+FST_MLP_MODEL_NAME = "fst_mlp_model.joblib"
+FST_LR_SCALER_NAME = "fst_scaler.joblib"
+FST_LR_MODEL_NAME = "fst_logreg.joblib"
+
+
+@functools.lru_cache(maxsize=1)
+def _load_cosmetic_models(models_dir: str = COSMETIC_MODELS_DIR_DEFAULT) -> Dict[str, Any]:
+    """Load all cosmetic scalers and models from disk (cached)."""
+    base = Path(models_dir)
+
+    models: Dict[str, Any] = {}
+
+    # Fitzpatrick: prefer MLP, fall back to logistic regression if needed.
+    fst_mlp_scaler_path = base / FST_MLP_SCALER_NAME
+    fst_mlp_model_path = base / FST_MLP_MODEL_NAME
+    if fst_mlp_scaler_path.exists() and fst_mlp_model_path.exists():
+        models["fst_scaler"] = joblib.load(fst_mlp_scaler_path)
+        models["fst_model"] = joblib.load(fst_mlp_model_path)
+        models["fst_model_type"] = "mlp"
+    else:
+        fst_scaler_path = base / FST_LR_SCALER_NAME
+        fst_model_path = base / FST_LR_MODEL_NAME
+        if fst_scaler_path.exists() and fst_model_path.exists():
+            models["fst_scaler"] = joblib.load(fst_scaler_path)
+            models["fst_model"] = joblib.load(fst_model_path)
+            models["fst_model_type"] = "logreg"
+
+    # Monk tone
+    monk_scaler_path = base / "monk_scaler.joblib"
+    monk_model_path = base / "monk_logreg.joblib"
+    if monk_scaler_path.exists() and monk_model_path.exists():
+        models["monk_scaler"] = joblib.load(monk_scaler_path)
+        models["monk_model"] = joblib.load(monk_model_path)
+
+    # Texture
+    texture_scaler_path = base / "texture_scaler.joblib"
+    texture_model_path = base / "texture_logreg.joblib"
+    if texture_scaler_path.exists() and texture_model_path.exists():
+        models["texture_scaler"] = joblib.load(texture_scaler_path)
+        models["texture_model"] = joblib.load(texture_model_path)
+
+    if not models:
+        raise FileNotFoundError(
+            f"No cosmetic models found in {base}. "
+            "Run `python scripts/train_cosmetic_attributes.py` first."
+        )
+
+    return models
+
+
+def _ensure_2d(emb: np.ndarray) -> np.ndarray:
+    if emb.ndim == 1:
+        return emb.reshape(1, -1)
+    return emb
+
+
+def predict_cosmetic_from_embedding(
+    embedding: np.ndarray,
+    models_dir: str = COSMETIC_MODELS_DIR_DEFAULT,
+) -> Dict[str, Any]:
+    """
+    Run Fitzpatrick, Monk tone, and texture classifiers on a Derm embedding.
+    Returns a nested dict suitable for cosmetic reporting.
+    """
+    emb = _ensure_2d(embedding.astype(np.float32))
+    models = _load_cosmetic_models(models_dir)
+    result: Dict[str, Any] = {}
+
+    # Fitzpatrick
+    fst_scaler = models.get("fst_scaler")
+    fst_model = models.get("fst_model")
+    if fst_scaler is not None and fst_model is not None:
+        X_std = fst_scaler.transform(emb)
+        proba = fst_model.predict_proba(X_std)[0]
+        label_idx = int(np.argmax(proba))
+        result["fitzpatrick"] = {
+            "label": FST_LABELS[label_idx],
+            "probs": {FST_LABELS[i]: float(p) for i, p in enumerate(proba)},
+        }
+
+    # Monk tone
+    monk_scaler = models.get("monk_scaler")
+    monk_model = models.get("monk_model")
+    if monk_scaler is not None and monk_model is not None:
+        X_std = monk_scaler.transform(emb)
+        proba = monk_model.predict_proba(X_std)[0]
+        label_idx = int(np.argmax(proba))
+        result["monk_tone"] = {
+            "label": MONK_TONE_VALUES[label_idx],
+            "probs": {str(MONK_TONE_VALUES[i]): float(p) for i, p in enumerate(proba)},
+        }
+
+    # Texture (multi-label)
+    texture_scaler = models.get("texture_scaler")
+    texture_model = models.get("texture_model")
+    if texture_scaler is not None and texture_model is not None:
+        X_std = texture_scaler.transform(emb)
+        proba_list: List[np.ndarray] = texture_model.predict_proba(X_std)
+        texture_info: Dict[str, Any] = {}
+        for tag, p in zip(TEXTURE_TAGS, proba_list):
+            # p shape: (n_samples, 2); probability of positive class is column 1
+            if p.shape[1] >= 2:
+                prob_pos = float(p[0, 1])
+            else:
+                prob_pos = float(p[0, -1])
+            texture_info[tag] = {
+                "prob": prob_pos,
+                "active": bool(prob_pos >= 0.5),
+            }
+        result["texture"] = texture_info
+
+    return result
+
+
+def analyze_cosmetic_image(
+    image_path: str,
+    models_dir: str = COSMETIC_MODELS_DIR_DEFAULT,
+) -> Dict[str, Any]:
+    """
+    High-level helper: embed image with Derm Foundation and run cosmetic attribute classifiers.
+    """
+    emb = embed_image_path(image_path)
+    return predict_cosmetic_from_embedding(emb, models_dir=models_dir)
+
+
+

lib/cosmetic_reporting.py

@@ -0,0 +1,185 @@
+"""
+Turn cosmetic predictions (Fitzpatrick, Monk tone, texture) into a
+user-facing educational report.
+"""
+
+from typing import Any, Dict, List, Tuple
+
+from config.cosmetic_copy import (
+    FST_COPY,
+    MONK_TONE_RANGES,
+    MONK_COPY,
+    TEXTURE_COPY,
+    COSMETIC_DISCLAIMER,
+)
+
+
+def _pick_monk_range_label(tone_label: int) -> str:
+    for entry in MONK_TONE_RANGES:
+        if tone_label in entry["range"]:
+            return entry["name"]
+    # Fallback
+    return "medium tones"
+
+
+def _active_textures(texture_pred: Dict[str, Dict[str, Any]]) -> List[Tuple[str, Dict[str, str]]]:
+    active: List[Tuple[str, Dict[str, str]]] = []
+    for tag, info in texture_pred.items():
+        if info.get("active"):
+            copy = TEXTURE_COPY.get(tag)
+            if copy:
+                active.append((tag, copy))
+    # If none are above threshold, still show the highest-prob one as a soft hint.
+    if not active and texture_pred:
+        best_tag = max(texture_pred.items(), key=lambda kv: kv[1].get("prob", 0.0))[0]
+        copy = TEXTURE_COPY.get(best_tag)
+        if copy:
+            active.append((best_tag, copy))
+    return active
+
+
+def _pick_fitzpatrick_labels(probs: Dict[str, float]) -> Dict[str, Any]:
+    """
+    Decide whether to present a single Fitzpatrick type or a 2-type range
+    based on class probabilities.
+    """
+    if not probs:
+        return {
+            "label_mode": "unknown",
+            "labels": [],
+            "primary_label": None,
+        }
+
+    # Sort labels by probability descending
+    items = sorted(probs.items(), key=lambda kv: kv[1], reverse=True)
+    (top1_label, top1_prob) = items[0]
+    if len(items) > 1:
+        (top2_label, top2_prob) = items[1]
+    else:
+        top2_label, top2_prob = None, 0.0
+
+    # Single label if confident and well separated from the second best.
+    if top1_prob >= 0.6 and (top1_prob - top2_prob) >= 0.15:
+        return {
+            "label_mode": "single",
+            "labels": [top1_label],
+            "primary_label": top1_label,
+        }
+
+    # Otherwise present a range over the top two labels.
+    labels = [top1_label]
+    if top2_label is not None:
+        labels.append(top2_label)
+
+    return {
+        "label_mode": "range",
+        "labels": labels,
+        "primary_label": top1_label,
+    }
+
+
+def build_cosmetic_report(cosmetic_predictions: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Build a structured cosmetic report from predictions:
+
+    {
+      "summary": str,
+      "tone_section": { ... },
+      "texture_section": { ... },
+      "disclaimer": str,
+    }
+    """
+    fst = cosmetic_predictions.get("fitzpatrick")
+    monk = cosmetic_predictions.get("monk_tone")
+    texture = cosmetic_predictions.get("texture", {})
+
+    summary_parts: List[str] = []
+    if fst:
+        fst_probs = fst.get("probs", {})
+        fst_labels_info = _pick_fitzpatrick_labels(fst_probs)
+        labels = fst_labels_info.get("labels", [])
+        primary_label = fst_labels_info.get("primary_label")
+
+        if primary_label:
+            fst_copy = FST_COPY.get(primary_label, {})
+            if fst_copy:
+                if fst_labels_info.get("label_mode") == "range" and len(labels) == 2:
+                    label_titles = [
+                        FST_COPY.get(lbl, {}).get("title", lbl) for lbl in labels
+                    ]
+                    range_text = "–".join(label_titles)
+                    summary_parts.append(
+                        f"We see features that place your skin between {range_text}, "
+                        "which gives us a sense of how your skin may respond to sun and active ingredients."
+                    )
+                else:
+                    summary_parts.append(
+                        f"We see features that align with {fst_copy.get('title', 'your skin type')}, "
+                        "which gives us a sense of how your skin may respond to sun and active ingredients."
+                    )
+    if monk:
+        tone_label = int(monk.get("label"))
+        tone_name = _pick_monk_range_label(tone_label)
+        monk_text = MONK_COPY.get(tone_name)
+        if monk_text:
+            summary_parts.append(
+                f"Your overall tone appears to sit in the range of {tone_name}, which influences how marks and color "
+                "changes show up on your skin."
+            )
+
+    if not summary_parts:
+        summary = (
+            "We used an AI-based model to estimate a few cosmetic characteristics of your skin from this photo, "
+            "such as overall tone and visible texture. These insights can guide gentle daily care and product choices."
+        )
+    else:
+        summary = " ".join(summary_parts)
+
+    tone_section: Dict[str, Any] = {}
+    if fst:
+        fst_probs = fst.get("probs", {})
+        fst_labels_info = _pick_fitzpatrick_labels(fst_probs)
+        labels = fst_labels_info.get("labels", [])
+        primary_label = fst_labels_info.get("primary_label")
+        label_mode = fst_labels_info.get("label_mode")
+
+        if primary_label:
+            fst_copy = FST_COPY.get(primary_label, {})
+            if fst_copy:
+                tone_section["fitzpatrick"] = {
+                    "label": primary_label,
+                    "label_mode": label_mode,
+                    "labels": labels,
+                    "title": fst_copy.get("title"),
+                    "overview": fst_copy.get("overview"),
+                    "care_focus": fst_copy.get("care_focus"),
+                    "probs": fst_probs,
+                }
+    if monk:
+        tone_label = int(monk.get("label"))
+        tone_name = _pick_monk_range_label(tone_label)
+        tone_section["monk_tone"] = {
+            "label": tone_label,
+            "group_name": tone_name,
+            "education": MONK_COPY.get(tone_name),
+            "probs": monk.get("probs", {}),
+        }
+
+    texture_section: Dict[str, Any] = {}
+    if texture:
+        active = _active_textures(texture)
+        if active:
+            texture_section["items"] = [
+                {"tag": tag, "title": copy["title"], "body": copy["body"], "prob": float(texture[tag]["prob"])}
+                for tag, copy in active
+            ]
+
+    return {
+        "summary": summary,
+        "tone_section": tone_section,
+        "texture_section": texture_section,
+        "disclaimer": COSMETIC_DISCLAIMER,
+    }
+
+
+

lib/derm_local.py

@@ -0,0 +1,47 @@
+import io
+from functools import lru_cache
+from typing import Tuple
+
+import numpy as np
+import tensorflow as tf
+from PIL import Image
+from huggingface_hub import snapshot_download
+
+
+@lru_cache(maxsize=1)
+def _load_model() -> tf.types.experimental.GenericFunction:
+    model_dir = snapshot_download("google/derm-foundation")
+    loaded = tf.saved_model.load(model_dir)
+    return loaded.signatures["serving_default"]
+
+
+def _encode_png_bytes(img: Image.Image) -> bytes:
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def _make_example(png_bytes: bytes) -> bytes:
+    example = tf.train.Example(
+        features=tf.train.Features(
+            feature={
+                "image/encoded": tf.train.Feature(
+                    bytes_list=tf.train.BytesList(value=[png_bytes])
+                )
+            }
+        )
+    )
+    return example.SerializeToString()
+
+
+def embed_image_path(path: str) -> np.ndarray:
+    """Return 1D embedding vector (float32) for an image file path."""
+    infer = _load_model()
+    with Image.open(path) as im:
+        im = im.convert("RGB")
+        png_bytes = _encode_png_bytes(im)
+    example_bytes = _make_example(png_bytes)
+    outputs = infer(inputs=tf.constant([example_bytes]))
+    emb = outputs["embedding"].numpy().flatten().astype(np.float32)
+    return emb
+

lib/full_analysis.py

@@ -0,0 +1,113 @@
+"""
+Top-level orchestrator to run both cosmetic and concern analysis.
+
+Exposes helpers for analyzing a single image (current API) and for aggregating
+results across multiple images from the same person/session.
+"""
+
+from typing import Any, Dict, List
+
+from config.hudson_products import load_product_config
+from lib.cosmetic_inference import analyze_cosmetic_image
+from lib.cosmetic_reporting import build_cosmetic_report
+from lib.concern_inference import analyze_image, analyze_image_report
+from lib.recommendations import build_routine
+from lib.reporting import build_report
+from lib.session_aggregation import aggregate_concern_probs, aggregate_fitzpatrick_probs
+
+
+def analyze_full_image(
+    image_path: str,
+    cosmetic_models_dir: str = "models/cosmetic",
+    concern_models_dir: str = "models",
+) -> Dict[str, Any]:
+    """
+    Run cosmetic attribute analysis and concern+routine analysis on the same image
+    and return a combined JSON structure:
+
+    {
+      "cosmetic": { ... },
+      "concerns": { ... }
+    }
+
+    The cosmetic and concern layers remain logically separate so they can be
+    used together or independently.
+    """
+    cosmetic_pred = analyze_cosmetic_image(image_path, models_dir=cosmetic_models_dir)
+    cosmetic_report = build_cosmetic_report(cosmetic_pred)
+
+    concern_report = analyze_image_report(image_path, models_dir=concern_models_dir)
+
+    return {
+        "cosmetic": cosmetic_report,
+        "concerns": concern_report,
+    }
+
+
+def analyze_full_session(
+    image_paths: List[str],
+    cosmetic_models_dir: str = "models/cosmetic",
+    concern_models_dir: str = "models",
+) -> Dict[str, Any]:
+    """
+    Run cosmetic and concern analysis on multiple images from the same person
+    and aggregate probabilities into a single session-level report.
+
+    This does not change the external API yet, but can be used by future
+    endpoints or CLI helpers to support 2–3 photos per analysis.
+    """
+    if not image_paths:
+        raise ValueError("analyze_full_session requires at least one image path")
+
+    # Per-image cosmetic and concern predictions
+    cosmetic_preds = [
+        analyze_cosmetic_image(path, models_dir=cosmetic_models_dir)
+        for path in image_paths
+    ]
+    concern_preds = [
+        analyze_image(path, models_dir=concern_models_dir) for path in image_paths
+    ]
+
+    # Aggregate Fitzpatrick probabilities across images.
+    fst_mean_probs = aggregate_fitzpatrick_probs(cosmetic_preds)
+    if fst_mean_probs:
+        fst_items = sorted(fst_mean_probs.items(), key=lambda kv: kv[1], reverse=True)
+        fst_primary_label = fst_items[0][0]
+        agg_fst = {
+            "label": fst_primary_label,
+            "probs": fst_mean_probs,
+        }
+    else:
+        agg_fst = None
+
+    # Start from the first image's cosmetic prediction and override FST with
+    # the aggregated probabilities.
+    cosmetic_base = dict(cosmetic_preds[0]) if cosmetic_preds else {}
+    if agg_fst is not None:
+        cosmetic_base["fitzpatrick"] = agg_fst
+
+    cosmetic_report = build_cosmetic_report(cosmetic_base)
+
+    # Aggregate concern probabilities and build routine + report using them.
+    concern_mean_probs = aggregate_concern_probs(concern_preds)
+    if concern_mean_probs:
+        base_concerns = dict(concern_preds[0])
+        for tag, prob in concern_mean_probs.items():
+            info = base_concerns.get(tag, {})
+            info["prob"] = float(prob)
+            info["active"] = bool(prob >= 0.5)
+            base_concerns[tag] = info
+    else:
+        base_concerns = concern_preds[0] if concern_preds else {}
+
+    product_cfg = load_product_config()
+    routine = build_routine(base_concerns, product_cfg)
+    concern_report = build_report(base_concerns, routine)
+
+    return {
+        "cosmetic": cosmetic_report,
+        "concerns": concern_report,
+    }
+
+
+

lib/recommendations.py

@@ -0,0 +1,93 @@
+"""
+Rule-based product recommendation module.
+
+Takes concern classifier output and Hudson product config, and builds a
+simple skincare routine (cleanser, treatment, moisturizer, sunscreen).
+"""
+
+from typing import Any, Dict, List, Tuple
+
+from config.hudson_products import PRODUCT_CONFIG, ROUTINE_STEPS, ProductConfig
+
+
+# Business-tunable parameters
+MIN_PROB_FOR_CONCERN: float = 0.4
+MAX_PRODUCTS_PER_STEP: int = 1
+
+
+def _get_active_concerns(concern_results: Dict[str, Dict[str, Any]]) -> List[Tuple[str, float]]:
+    """Return list of (tag, prob) for active concerns, sorted by prob desc."""
+    items: List[Tuple[str, float]] = []
+    for tag, info in concern_results.items():
+        prob = float(info.get("prob", 0.0))
+        if prob >= MIN_PROB_FOR_CONCERN:
+            items.append((tag, prob))
+    # If nothing passes the threshold, fall back to the single highest-prob concern
+    if not items and concern_results:
+        tag, info = max(concern_results.items(), key=lambda kv: float(kv[1].get("prob", 0.0)))
+        items.append((tag, float(info.get("prob", 0.0))))
+    # Sort by probability descending
+    items.sort(key=lambda tp: tp[1], reverse=True)
+    return items
+
+
+def build_routine(
+    concern_results: Dict[str, Dict[str, Any]],
+    product_config: Dict[str, ProductConfig] | None = None,
+) -> Dict[str, Any]:
+    """
+    Build a simple routine from concern results and product config.
+
+    concern_results: output from analyze_embedding/analyze_image
+        {concern_tag: {"prob": float, "active": bool, ...}}
+
+    Returns:
+        {
+          "concerns": [("Dry_Sensitive", 0.82), ...],
+          "steps": {
+            "cleanser": ["moisture_balancing_cleanser"],
+            "treatment": ["blemish_age_defense_serum"],
+            "moisturizer": ["daily_moisturizer"],
+            "sunscreen": ["facial_gel_sunscreen"],
+          }
+        }
+    """
+    if product_config is None:
+        product_config = PRODUCT_CONFIG
+
+    active_concerns = _get_active_concerns(concern_results)
+    concern_prob_map = {tag: prob for tag, prob in active_concerns}
+
+    # Score products by how well they match active concerns
+    candidates_by_step: Dict[str, List[Tuple[str, float]]] = {step: [] for step in ROUTINE_STEPS}
+
+    for pid, cfg in product_config.items():
+        step = cfg["step"]
+        if step not in ROUTINE_STEPS:
+            continue
+        supported = cfg.get("supported_concerns", [])
+        score = 0.0
+        for tag in supported:
+            if tag in concern_prob_map:
+                score += concern_prob_map[tag]
+        if score > 0.0:
+            candidates_by_step[step].append((pid, score))
+
+    # Pick top products per step
+    chosen_steps: Dict[str, List[str]] = {}
+    for step in ROUTINE_STEPS:
+        cands = candidates_by_step.get(step, [])
+        if not cands:
+            continue
+        # Sort by score desc, then by product id for determinism
+        cands.sort(key=lambda x: (x[1], x[0]), reverse=True)
+        chosen_steps[step] = [pid for pid, _ in cands[:MAX_PRODUCTS_PER_STEP]]
+
+    routine = {
+        "concerns": active_concerns,
+        "steps": chosen_steps,
+    }
+    return routine
+
+
+

lib/reporting.py

@@ -0,0 +1,215 @@
+"""
+Reporting utilities to turn model outputs into a user-friendly skin report.
+"""
+
+from typing import Any, Dict, List, Tuple
+
+from config.concerns import CONCERN_CONFIG
+from config.hudson_products import PRODUCT_CONFIG, ProductConfig
+
+
+# Tunable parameters
+MAX_CONCERNS_IN_SUMMARY = 3
+# Minimum probability for including a concern section at all.
+MIN_PROB_FOR_SECTION = 0.4
+# Thresholds for primary / secondary concern logic.
+PRIMARY_MIN_PROB = 0.6
+SECONDARY_MIN_PROB = 0.45
+SECONDARY_MAX_GAP = 0.15
+
+
+def _describe_probability(prob: float) -> str:
+    """Map numeric probability to friendly language."""
+    if prob >= 0.8:
+        return "strong patterns"
+    if prob >= 0.6:
+        return "clear patterns"
+    if prob >= 0.4:
+        return "some features"
+    return "subtle hints"
+
+
+def _format_concern_body(tag: str, prob: float) -> str:
+    cfg = CONCERN_CONFIG.get(tag, {})
+    description = cfg.get("description", "")
+    what_it_means = cfg.get("what_it_means", "")
+    care_focus = cfg.get("care_focus", "")
+    intensity = _describe_probability(prob)
+
+    parts: List[str] = []
+    if description:
+        parts.append(description)
+    if what_it_means:
+        parts.append(what_it_means)
+    if care_focus:
+        parts.append(f"In terms of care, a good focus is: {care_focus}")
+
+    # Prepend intensity phrase if we have any text
+    if parts:
+        intro = f"We see {intensity} that can be seen with this type of skin pattern."
+        return " ".join([intro] + parts)
+    return ""
+
+
+def _split_primary_secondary(
+    active_concerns: List[Tuple[str, float]]
+) -> Tuple[List[Tuple[str, float]], List[Tuple[str, float]]]:
+    """
+    Given (tag, prob) pairs sorted by prob desc, split into primary and secondary
+    concerns using configurable thresholds.
+    """
+    if not active_concerns:
+        return [], []
+
+    # active_concerns are already sorted by prob desc (see recommendations.build_routine)
+    primary_tag, primary_prob = active_concerns[0]
+    if primary_prob < PRIMARY_MIN_PROB:
+        # No strong primary concern; treat all as secondary
+        return [], active_concerns
+
+    primary = [(primary_tag, primary_prob)]
+    secondary: List[Tuple[str, float]] = []
+
+    for tag, prob in active_concerns[1:]:
+        if prob >= SECONDARY_MIN_PROB and (primary_prob - prob) <= SECONDARY_MAX_GAP:
+            secondary.append((tag, prob))
+
+    return primary, secondary
+
+
+def _build_summary(active_concerns: List[Tuple[str, float]]) -> str:
+    if not active_concerns:
+        return (
+            "We analyzed this photo but did not find any strong, consistent patterns. "
+            "Your skin may still benefit from gentle daily care and sunscreen, and for any worries "
+            "it's always best to speak with a skin professional."
+        )
+
+    max_prob = max(prob for _, prob in active_concerns)
+
+    # If no concern stands out strongly, lean into a reassuring, maintenance-focused message.
+    if max_prob < 0.45:
+        return (
+            "We used an AI-based cosmetic model to review the image you shared and did not see strong patterns "
+            "of common skin concerns. That is generally reassuring. "
+            "Gentle cleansing, a suitable moisturizer, and daily sunscreen are usually enough to maintain healthy-looking skin. "
+            "If anything about your skin is worrying or changing quickly, it's still a good idea to check in with a skin professional."
+        )
+
+    top = active_concerns[:MAX_CONCERNS_IN_SUMMARY]
+    concern_phrases = []
+    for tag, prob in top:
+        cfg = CONCERN_CONFIG.get(tag, {})
+        title = cfg.get("title", tag.replace("_", " "))
+        intensity = _describe_probability(prob)
+        concern_phrases.append(f"{intensity} associated with {title.lower()}")
+
+    if len(concern_phrases) == 1:
+        concerns_text = concern_phrases[0]
+    elif len(concern_phrases) == 2:
+        concerns_text = " and ".join(concern_phrases)
+    else:
+        concerns_text = ", ".join(concern_phrases[:-1]) + f", and {concern_phrases[-1]}"
+
+    return (
+        "We used an AI-based cosmetic model to review the image you shared. "
+        f"In this photo we see {concerns_text}. "
+        "Different skin patterns can overlap, so this is not a diagnosis, but a guide to the kinds of care "
+        "that may support your skin."
+    )
+
+
+def _enrich_routine(
+    routine: Dict[str, Any],
+    active_concerns: List[Tuple[str, float]],
+) -> Dict[str, Any]:
+    """Attach per-product rationales to the routine steps."""
+    active_tags = [tag for tag, _ in active_concerns]
+    enriched_steps: Dict[str, List[Dict[str, Any]]] = {}
+
+    for step, product_ids in routine.get("steps", {}).items():
+        enriched_steps[step] = []
+        for pid in product_ids:
+            cfg: ProductConfig | None = PRODUCT_CONFIG.get(pid)  # type: ignore[assignment]
+            if not cfg:
+                continue
+
+            name = cfg["name"]
+            portfolio = cfg.get("portfolio") or ""
+            supported = cfg.get("supported_concerns", [])
+            matched = [t for t in supported if t in active_tags]
+            concern_titles = [
+                CONCERN_CONFIG.get(t, {}).get("title", t.replace("_", " ")) for t in matched
+            ]
+            concern_text = ", ".join(concern_titles) if concern_titles else "your overall skin goals"
+
+            template = cfg.get("why_template")
+            if template:
+                why = template.format(name=name, concerns=concern_text, step=step, portfolio=portfolio)
+            else:
+                why = (
+                    f"Because your photo suggests {concern_text}, we recommend {name}, a {step} "
+                    f"from our {portfolio} range to support this area."
+                ).strip()
+
+            enriched_steps[step].append(
+                {
+                    "id": cfg["id"],
+                    "name": name,
+                    "step": step,
+                    # Optional product image filename (e.g. \"daily_moisturizer.png\").
+                    # The client can map this to an actual asset or URL.
+                    "image_name": cfg.get("image_name"),
+                    "why": why,
+                }
+            )
+
+    enriched = dict(routine)
+    enriched["steps"] = enriched_steps
+    return enriched
+
+
+def build_report(
+    concern_results: Dict[str, Dict[str, Any]],
+    routine: Dict[str, Any],
+) -> Dict[str, Any]:
+    """
+    Assemble a full user-facing report from concerns and routine.
+    """
+    # Active concerns list is already computed by the recommendation module
+    active_concerns: List[Tuple[str, float]] = routine.get("concerns", [])
+
+    summary = _build_summary(active_concerns)
+
+    concern_sections: List[Dict[str, Any]] = []
+    for tag, prob in active_concerns:
+        if prob < MIN_PROB_FOR_SECTION:
+            continue
+        cfg = CONCERN_CONFIG.get(tag, {})
+        body = _format_concern_body(tag, prob)
+        concern_sections.append(
+            {
+                "tag": tag,
+                "title": cfg.get("title", tag.replace("_", " ")),
+                "body": body,
+                "prob": prob,
+            }
+        )
+
+    enriched_routine = _enrich_routine(routine, active_concerns)
+
+    disclaimer = (
+        "This experience is powered by an AI-based cosmetic skin analysis and is not a medical diagnosis. "
+        "It cannot rule out skin disease or serious conditions. If you notice pain, bleeding, rapidly changing areas, "
+        "or anything that worries you, please consult a dermatologist or healthcare professional."
+    )
+
+    return {
+        "summary": summary,
+        "concern_sections": concern_sections,
+        "routine": enriched_routine,
+        "disclaimer": disclaimer,
+    }
+
+
+

lib/session_aggregation.py

@@ -0,0 +1,61 @@
+"""
+Utilities for aggregating per-image predictions into a session-level summary.
+
+We keep this separate so both cosmetic and concern reporting can reuse it
+without changing the external API shape.
+"""
+
+from typing import Any, Dict, Iterable, List, Tuple
+
+import numpy as np
+
+
+def aggregate_fitzpatrick_probs(predictions: Iterable[Dict[str, Any]]) -> Dict[str, float]:
+    """
+    Average Fitzpatrick class probabilities across multiple images.
+
+    Each element in `predictions` is expected to be a dict with a
+    `\"fitzpatrick\"` key containing a `\"probs\"` mapping from label to prob.
+    """
+    probs_list: List[Dict[str, float]] = []
+    for pred in predictions:
+        fst = pred.get("fitzpatrick")
+        if not fst:
+            continue
+        probs = fst.get("probs")
+        if isinstance(probs, dict):
+            probs_list.append({str(k): float(v) for k, v in probs.items()})
+
+    if not probs_list:
+        return {}
+
+    # Ensure all dicts share the same keys
+    labels = sorted(probs_list[0].keys())
+    arr = np.array([[p.get(label, 0.0) for label in labels] for p in probs_list], dtype=float)
+    mean = arr.mean(axis=0)
+    return {label: float(prob) for label, prob in zip(labels, mean)}
+
+
+def aggregate_concern_probs(
+    per_image_concerns: Iterable[Dict[str, Dict[str, Any]]]
+) -> Dict[str, float]:
+    """
+    Average concern probabilities across multiple images.
+
+    Each element is expected to be a dict mapping concern tag -> {\"prob\": float, ...}.
+    """
+    sums: Dict[str, float] = {}
+    counts: Dict[str, int] = {}
+
+    for concerns in per_image_concerns:
+        for tag, info in concerns.items():
+            prob = float(info.get("prob", 0.0))
+            sums[tag] = sums.get(tag, 0.0) + prob
+            counts[tag] = counts.get(tag, 0) + 1
+
+    if not sums:
+        return {}
+
+    return {tag: sums[tag] / counts[tag] for tag in sums}
+
+

models/cosmetic/fst_logreg.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:24dbc8e52b44abd36a265dda6cbd9a7912c6abfaebd9e33436121833a3d6f68b
+size 295863

models/cosmetic/fst_mlp_model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0b5d723106668c44839e96fc8ae916d4939bae29ff54a45cf7e2c4f6b40a51b5
+size 19290165

models/cosmetic/fst_mlp_scaler.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:12b2dc0edd9d73b3dfb350e0bc84bddb8a49884206619b5dc228c6271f32d980
+size 148071

models/cosmetic/fst_scaler.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:12b2dc0edd9d73b3dfb350e0bc84bddb8a49884206619b5dc228c6271f32d980
+size 148071

models/cosmetic/monk_logreg.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e2c8b614d672f458d9c04da0d53cdee13c5071351d641316723fa8f97e8cd840
+size 492535

models/cosmetic/monk_scaler.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:32630e298800bda3afeac3fdb9b06a6551d125660521928f48add653506e42e0
+size 148071

models/logreg.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd74e16ed27584bb8434594497f7e7fa366b23995b8f4e7d247164952cf25885
+size 148367

models/scaler.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ca49b11510cd10cb49ce19495b4f336844806b1d5759c12c1d27ae16d94611ce
+size 148071

models/scin_concerns_logreg.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:20413c36ac4eb49951dca32dc8a4cedbbaa9484d898b7c6e6974775f2c213bbd
+size 298209

models/scin_concerns_scaler.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:708aec9bd47579e8192c0944336b86210c65de4143607928fa21ad0536e22491
+size 148071

requirements.txt

@@ -0,0 +1,13 @@
+fastapi
+uvicorn[standard]
+python-multipart
+Pillow
+numpy
+scikit-learn
+joblib
+tensorflow
+huggingface_hub
+requests
+python-dotenv
+
+