Create app.py

app.py

@@ -0,0 +1,889 @@
+"""
+Personal Style Matcher — Final Project, Part 5 (Hugging Face Space application)
+==================================================================================
+
+A Gradio app that recommends fashion looks from the "Fashion Stylist
+Multimodal v2" catalog (lihicarmeli/fashion-stylist-multimodal-v2 on the
+Hugging Face Hub), using the exact same engine validated in Part 3:
+
+    * Embedding model : openai/clip-vit-base-patch32  (the model selected
+      after the multi-criteria evaluation in Part 3 — best speed/size/effort
+      trade-off, within 1.3 purity points of the larger CLIP variant).
+    * Vector search    : a FAISS flat-L2 index over the catalog's CLIP image
+      embeddings, with the same 3-tier demographic fallback filter used in
+      the notebook (strict gender+age -> gender-only -> fully open search).
+    * GenAI component  : an optional one-line AI stylist note generated by
+      a small instruction-tuned LM (Qwen/Qwen2.5-0.5B-Instruct), reusing the
+      exact prompt pattern from Part 4.
+
+Two ways in, one engine:
+    Mode A — upload a photo. A lightweight heuristic samples the face region
+             to estimate a skin tone / undertone, and the photo itself is
+             embedded with CLIP's image encoder for the catalog search.
+    Mode B — pick your features from dropdowns. A natural-language sentence
+             is built from those features and embedded with CLIP's text
+             encoder, landing in the exact same vector space as the photos.
+
+Deploy: push this file + requirements.txt to a new Hugging Face Space using
+the "Gradio" SDK. No local data or model files are needed — both the
+dataset and the embedding model are streamed directly from the Hub.
+"""
+
+import os
+import html
+import hashlib
+import colorsys
+import traceback
+import urllib.parse
+
+import numpy as np
+import torch
+
+import faiss
+from datasets import load_dataset
+from transformers import AutoModel, AutoProcessor
+
+import gradio as gr
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+DATASET_REPO = "lihicarmeli/fashion-stylist-multimodal-v2"
+EMBED_MODEL_REPO = "openai/clip-vit-base-patch32"       # winning model from Part 3
+CAPTION_MODEL_REPO = "Qwen/Qwen2.5-0.5B-Instruct"        # small LM from Part 4
+EMBED_CACHE_PATH = "catalog_image_embeddings.npy"
+
+SKIN_DEPTH_ORDER = ["fair", "light", "ivory", "porcelain", "medium",
+                    "olive", "tan", "deep", "dark", "ebony"]
+AGE_ORDER = ["teen", "young adult", "adult", "mature"]
+UNDERTONE_ORDER = ["warm", "neutral", "cool"]
+EYE_COLOR_CHOICES = ["Brown", "Dark Brown", "Hazel", "Amber", "Green", "Blue", "Gray"]
+WARM_EYES = {"brown", "dark brown", "hazel", "amber"}
+COOL_EYES = {"green", "blue", "gray", "grey"}
+
+AUTO_DETECT_LABEL = "Auto-detect from photo"
+
+COMPONENT_RETAILERS = {
+    "TOP": "zara",
+    "BOTTOM": "hm",
+    "SHOES": "asos",
+    "ACCESSORY": "mango",
+}
+
+RETAILER_SEARCH_URLS = {
+    "zara":  "https://www.zara.com/us/en/search?searchTerm={query}&section={section}",
+    "hm":    "https://www2.hm.com/en_us/search-results.html?q={query}",
+    "asos":  "https://www.asos.com/us/{dept}/search/?q={query}",
+    "mango": "https://shop.mango.com/us/en/search?kw={query}",
+    "shein": "https://us.shein.com/pdsearch/{query}/",
+}
+
+
+# =============================================================================
+# Color utilities — resolve a descriptive color phrase to a hex swatch
+# =============================================================================
+
+NAMED_COLOR_HEX = {
+    # multi-word fashion phrases (checked first, longest match wins)
+    "ice white": "#F5F5F0", "warm white": "#FAF3E8", "deep jewel": "#5B2C6F",
+    "bold blue": "#1E5AA8", "royal blue": "#4169E1", "cobalt blue": "#0047AB",
+    "powder blue": "#B0E0E6", "rich gold": "#C9A227", "warm beige": "#E8D9B5",
+    "warm brown": "#8B5A2B", "cool red": "#C8102E", "bright red": "#EE2C2C",
+    "brick red": "#9B3A2C", "deep teal": "#114B5F", "deep olive": "#4B5320",
+    "deep purple": "#4B1A6B", "forest green": "#1B4332", "bright orange": "#FF6B1A",
+    "bright pink": "#FF2D87", "dusty rose": "#C68893", "blush pink": "#F4C2C2",
+    "grass green": "#3DA35D", "slate gray": "#6E7B8B", "burnt orange": "#CB6015",
+    "golden yellow": "#F5C518", "true red": "#C8102E", "bright warm red": "#E0382D",
+    "very deep": "#3A2A22", "cool blue": "#3B6FCC",
+    # single words (fallback)
+    "white": "#FFFFFF", "black": "#1A1A1A", "ivory": "#FFFFF0", "silver": "#C0C0C0",
+    "gold": "#D4AF37", "amber": "#FFBF00", "tangerine": "#F28500", "coral": "#FF7F50",
+    "peach": "#FFCBA4", "terracotta": "#C0654D", "olive": "#708238", "beige": "#E8D9B5",
+    "tan": "#C19A6B", "khaki": "#C3B091", "emerald": "#2E8B57", "teal": "#218380",
+    "turquoise": "#30D5C8", "mint": "#98D8C8", "navy": "#1B1F3B", "blue": "#3B6FCC",
+    "lavender": "#B497D6", "plum": "#8E4585", "magenta": "#C2185B", "fuchsia": "#D6336C",
+    "purple": "#7B4397", "maroon": "#7A2E3B", "burgundy": "#6E0D25", "crimson": "#A11D33",
+    "red": "#D63447", "pink": "#E07A9E", "rose": "#D17B96", "yellow": "#F4C542",
+    "mustard": "#C9A227", "orange": "#E8722C", "brown": "#7B4B2A", "chocolate": "#5A3A22",
+    "copper": "#B6622A", "rust": "#9E4624", "green": "#3F8D5C", "grey": "#9A9A9A",
+    "gray": "#9A9A9A", "charcoal": "#3B3B3B", "cream": "#F1E8DA",
+}
+
+
+def resolve_color_hex(text):
+    """Return a hex color if any known color phrase appears in `text`, else None."""
+    if not text:
+        return None
+    t = str(text).lower()
+    for phrase in sorted(NAMED_COLOR_HEX, key=len, reverse=True):
+        if " " in phrase and phrase in t:
+            return NAMED_COLOR_HEX[phrase]
+    for word in t.replace(",", " ").split():
+        if word in NAMED_COLOR_HEX:
+            return NAMED_COLOR_HEX[word]
+    return None
+
+
+def text_to_pastel_hex(text):
+    """Deterministic fallback color: hash the text into a pleasant, distinct hue."""
+    digest = hashlib.md5(str(text).encode("utf-8")).hexdigest()
+    hue = int(digest[:4], 16) / 65535.0
+    r, g, b = colorsys.hls_to_rgb(hue, 0.55, 0.55)
+    return "#{:02X}{:02X}{:02X}".format(int(r * 255), int(g * 255), int(b * 255))
+
+
+def swatch_color_for(*texts):
+    """Pick the first resolvable color among the given text fields, or fall back
+    to a stable hashed pastel so the same item always gets the same swatch."""
+    for t in texts:
+        hexcode = resolve_color_hex(t)
+        if hexcode:
+            return hexcode
+    joined = " ".join(str(t) for t in texts if t)
+    return text_to_pastel_hex(joined or "style")
+
+
+# =============================================================================
+# Seasonal color profile (display-only "stylist" layer on top of the catalog)
+# =============================================================================
+
+SEASON_INFO = {
+    "Spring": {
+        "blurb": "Warm and light — your glow loves clear, fresh colors with a golden undertone.",
+        "palette": [("Coral", "#FF7F50"), ("Peach", "#FFCBA4"), ("Golden Yellow", "#F5C518"),
+                    ("Grass Green", "#3DA35D"), ("Turquoise", "#30D5C8"), ("Ivory", "#FFFFF0")],
+    },
+    "Autumn": {
+        "blurb": "Warm and rich — earthy, spiced tones make your natural warmth shine.",
+        "palette": [("Rust", "#9E4624"), ("Olive", "#708238"), ("Mustard", "#C9A227"),
+                    ("Chocolate Brown", "#5A3A22"), ("Burnt Orange", "#CB6015"), ("Forest Green", "#1B4332")],
+    },
+    "Summer": {
+        "blurb": "Cool and soft — muted, misty colors flatter your cool undertone beautifully.",
+        "palette": [("Powder Blue", "#B0E0E6"), ("Lavender", "#B497D6"), ("Rose Pink", "#D17B96"),
+                    ("Soft Teal", "#5F9EA0"), ("Dusty Mauve", "#A97C8A"), ("Slate Gray", "#6E7B8B")],
+    },
+    "Winter": {
+        "blurb": "Cool and deep — bold, high-contrast colors match your striking cool undertone.",
+        "palette": [("True Red", "#C8102E"), ("Royal Blue", "#4169E1"), ("Emerald", "#2E8B57"),
+                    ("Black", "#1A1A1A"), ("White", "#FFFFFF"), ("Magenta", "#C2185B")],
+    },
+    "Soft Spring": {
+        "blurb": "A gentle warm-neutral mix — soft, peachy tones suit you better than stark contrast.",
+        "palette": [("Soft Peach", "#F2C6A0"), ("Honey", "#E2B765"), ("Sage Green", "#9CAF88"),
+                    ("Camel", "#C19A6B"), ("Warm Ivory", "#F5EFE0"), ("Apricot", "#FBCEB1")],
+    },
+    "Soft Autumn": {
+        "blurb": "A muted warm-neutral mix — soft earth tones bring out your warmth without overpowering it.",
+        "palette": [("Terracotta", "#C0654D"), ("Sage", "#8A9A5B"), ("Caramel", "#AF6E4D"),
+                    ("Warm Taupe", "#9C8170"), ("Moss", "#6B7A4F"), ("Dusty Gold", "#B79766")],
+    },
+    "Soft Summer": {
+        "blurb": "A gentle cool-neutral mix — soft, dusty colors are more flattering than bright ones.",
+        "palette": [("Dusty Rose", "#C68893"), ("Soft Lilac", "#C6B4D6"), ("Sage Gray", "#A6AD9E"),
+                    ("Mauve", "#9C7A8A"), ("Soft Denim", "#7C93A8"), ("Pearl Gray", "#C9C5C0")],
+    },
+    "Soft Winter": {
+        "blurb": "A muted cool-neutral mix — clear but gentle colors balance your cool undertone.",
+        "palette": [("Plum", "#8E4585"), ("Slate Blue", "#5B6C8F"), ("Charcoal", "#3B3B3B"),
+                    ("Berry", "#7A2E4D"), ("Icy Pink", "#E7C6CE"), ("Steel Gray", "#71797E")],
+    },
+}
+
+
+def skin_depth_flag(skin_tone):
+    """Bucket a skin-tone label into 'light' or 'deep' using a best-effort ordering."""
+    s = str(skin_tone).lower().strip()
+    if s in SKIN_DEPTH_ORDER:
+        idx = SKIN_DEPTH_ORDER.index(s)
+        midpoint = len(SKIN_DEPTH_ORDER) / 2
+    else:
+        idx, midpoint = 1, 2  # unseen label -> assume mid-range
+    return "deep" if idx >= midpoint else "light"
+
+
+def derive_color_profile(skin_tone, undertone, eye_color=None):
+    """Map (skin tone, undertone, eye color) onto a simplified 4/8-season
+    color-analysis bucket. This is a styling heuristic, not a clinical tool —
+    it gives the user a friendly, explainable color story to go with their
+    matched looks."""
+    undertone = str(undertone).lower().strip()
+    depth = skin_depth_flag(skin_tone)
+    eye = str(eye_color).lower().strip() if eye_color else ""
+
+    if undertone == "warm":
+        season = "Spring" if depth == "light" else "Autumn"
+    elif undertone == "cool":
+        season = "Summer" if depth == "light" else "Winter"
+    else:
+        leans_warm = eye in WARM_EYES
+        leans_cool = eye in COOL_EYES
+        if depth == "light":
+            season = "Soft Summer" if leans_cool and not leans_warm else "Soft Spring"
+        else:
+            season = "Soft Winter" if leans_cool and not leans_warm else "Soft Autumn"
+
+    info = SEASON_INFO.get(season, SEASON_INFO["Spring"])
+    return season, info["blurb"], info["palette"]
+
+
+# =============================================================================
+# Skin tone / undertone estimation from an uploaded photo (Mode A)
+# =============================================================================
+
+def estimate_skin_tone_undertone(pil_image, available_skin_tones):
+    """A lightweight, transparent heuristic — NOT a clinical skin-tone
+    classifier. It samples a centered, face-shaped region of the photo, keeps
+    only pixels that look skin-like in YCbCr space, and buckets the resulting
+    average color by brightness (-> skin tone bucket) and red/blue balance
+    (-> warm / cool / neutral undertone)."""
+    img = pil_image.convert("RGB").resize((160, 160))
+    arr = np.asarray(img).astype(np.float32)
+
+    h, w, _ = arr.shape
+    y0, y1 = int(h * 0.15), int(h * 0.75)
+    x0, x1 = int(w * 0.30), int(w * 0.70)
+    crop = arr[y0:y1, x0:x1, :]
+
+    r, g, b = crop[..., 0], crop[..., 1], crop[..., 2]
+    y_ = 0.299 * r + 0.587 * g + 0.114 * b
+    cb = 128 - 0.168736 * r - 0.331264 * g + 0.5 * b
+    cr = 128 + 0.5 * r - 0.418688 * g - 0.081312 * b
+    skin_mask = (y_ > 60) & (cb > 85) & (cb < 135) & (cr > 135) & (cr < 180)
+
+    pixels = crop.reshape(-1, 3) if skin_mask.sum() < 50 else crop[skin_mask]
+    mean_rgb = pixels.mean(axis=0)
+    brightness = float(0.299 * mean_rgb[0] + 0.587 * mean_rgb[1] + 0.114 * mean_rgb[2])
+
+    available = {str(s).lower() for s in available_skin_tones}
+    ordered = [s for s in SKIN_DEPTH_ORDER if s in available] or list(available_skin_tones)
+    n = len(ordered)
+    frac = 1.0 - min(max(brightness / 255.0, 0.0), 1.0)   # darker photo -> higher frac
+    bucket_idx = min(int(frac * n), n - 1) if n else 0
+    skin_tone_guess = ordered[bucket_idx] if n else "medium"
+
+    diff = float(mean_rgb[0] - mean_rgb[2])  # R - B
+    if diff > 8:
+        undertone_guess = "warm"
+    elif diff < -8:
+        undertone_guess = "cool"
+    else:
+        undertone_guess = "neutral"
+
+    swatch_hex = "#{:02X}{:02X}{:02X}".format(
+        *[int(min(max(c, 0), 255)) for c in mean_rgb]
+    )
+    return skin_tone_guess, undertone_guess, swatch_hex
+
+
+# =============================================================================
+# Query building & embedding (mirrors the validated Part 3 pipeline exactly)
+# =============================================================================
+
+def build_feature_sentence(skin_tone, undertone, style_preference, gender=None,
+                            age_group=None, eye_color=None):
+    """Path B: turn typed-in features into a sentence in the same vector
+    space CLIP's text encoder was trained on, mirroring Part 3's
+    build_feature_sentence()."""
+    descriptor = " ".join(p for p in [age_group, gender] if p) or "person"
+    sentence = (
+        f"a {descriptor} with {skin_tone} skin tone and {undertone} undertone, "
+        f"wearing a {style_preference} style outfit"
+    )
+    if eye_color:
+        sentence += f", {str(eye_color).lower()} eyes"
+    return sentence
+
+
+@torch.no_grad()
+def embed_query_image(pil_image, model, processor, device):
+    """Path A: turn a user-uploaded photo into a CLIP image embedding."""
+    inputs = processor(images=pil_image.convert("RGB"), return_tensors="pt").to(device)
+    outputs = model.get_image_features(**inputs)
+    feats = outputs.pooler_output if hasattr(outputs, "pooler_output") else outputs
+    return feats.cpu().numpy().astype("float32")
+
+
+@torch.no_grad()
+def embed_query_text(sentence, model, processor, device):
+    """Path B: turn a feature sentence into a CLIP text embedding."""
+    inputs = processor(text=[sentence], return_tensors="pt", padding=True,
+                        truncation=True).to(device)
+    outputs = model.get_text_features(**inputs)
+    feats = outputs.pooler_output if hasattr(outputs, "pooler_output") else outputs
+    return feats.cpu().numpy().astype("float32")
+
+
+def faiss_filtered_search(query_emb, faiss_index, df_pool, top_k=3, exclude_idx=None,
+                           gender=None, age_group=None):
+    """Self-exclusion + graded demographic filtering fallback, identical in
+    spirit to Part 3's faiss_filtered_search: Tier 1 (gender + age) -> Tier 2
+    (gender only) -> Tier 3 (fully open). Returns (indices, rows, distances, tier)."""
+    query_emb = np.array(query_emb, dtype="float32").reshape(1, -1).copy()
+    faiss.normalize_L2(query_emb)
+    k = min(len(df_pool), faiss_index.ntotal)
+    distances, indices = faiss_index.search(query_emb, k)
+    distances, indices = distances[0], indices[0]
+
+    def collect(filter_fn):
+        kept_i, kept_d = [], []
+        for idx, dist in zip(indices, distances):
+            if idx == -1 or (exclude_idx is not None and idx == exclude_idx):
+                continue
+            row = df_pool.iloc[idx]
+            if not filter_fn(row):
+                continue
+            kept_i.append(int(idx))
+            kept_d.append(float(dist))
+            if len(kept_i) == top_k:
+                break
+        return kept_i, kept_d
+
+    def gender_match(row):
+        return gender is None or str(row["gender"]).lower() == str(gender).lower()
+
+    def age_match(row):
+        return age_group is None or str(row["age_group"]).lower() == str(age_group).lower()
+
+    kept_i, kept_d = collect(lambda row: gender_match(row) and age_match(row))
+    tier = 1
+    if len(kept_i) < top_k:
+        kept_i, kept_d = collect(gender_match)
+        tier = 2
+    if len(kept_i) < top_k:
+        kept_i, kept_d = collect(lambda row: True)
+        tier = 3
+
+    idx_arr = np.array(kept_i)
+    rows = df_pool.iloc[idx_arr] if len(idx_arr) else df_pool.iloc[0:0]
+    return idx_arr, rows, np.array(kept_d), tier
+
+
+# =============================================================================
+# Real, working shop links
+# =============================================================================
+
+def normalize_gender(gender):
+    g = str(gender).strip().lower() if gender is not None else ""
+    if g in ("male", "man", "men", "m"):
+        return "men"
+    if g in ("female", "woman", "women", "f"):
+        return "women"
+    return "women"
+
+
+def component_shop_link(retailer, item_text, gender=None):
+    """Build a real, live retailer search URL for one outfit component."""
+    dept = normalize_gender(gender)
+    text = str(item_text)
+    if retailer == "zara":
+        section = "MAN" if dept == "men" else "WOMAN"
+        query = urllib.parse.quote(text)
+        return RETAILER_SEARCH_URLS["zara"].format(query=query, section=section)
+    if retailer == "asos":
+        query = urllib.parse.quote(text)
+        return RETAILER_SEARCH_URLS["asos"].format(query=query, dept=dept)
+    gender_word = "men's" if dept == "men" else "women's"
+    query = urllib.parse.quote(f"{gender_word} {text}")
+    return RETAILER_SEARCH_URLS[retailer].format(query=query)
+
+
+# =============================================================================
+# HTML rendering — matches the required "YOUR MATCHED LOOKS" layout exactly
+# =============================================================================
+
+def render_profile_card_html(season, blurb, palette):
+    chips = "".join(
+        f'<div class="fs-chip"><span class="fs-chip-dot" style="background:{hexcode}"></span>{html.escape(name)}</div>'
+        for name, hexcode in palette
+    )
+    return f"""
+    <div class="fs-profile-card">
+      <div class="fs-profile-eyebrow">YOUR COLOR PROFILE</div>
+      <div class="fs-profile-season">{html.escape(season)}</div>
+      <div class="fs-profile-blurb">{html.escape(blurb)}</div>
+      <div class="fs-chip-row">{chips}</div>
+    </div>
+    """
+
+
+def render_caption_html(caption):
+    return (
+        '<div class="fs-caption">🪄 <span class="fs-caption-label">AI Stylist note:</span> '
+        f'“{html.escape(caption)}”</div>'
+    )
+
+
+def _component_html(label, text, retailer, gender):
+    hexcode = swatch_color_for(text)
+    link = component_shop_link(retailer, text, gender)
+    return f"""
+    <div class="fs-component">
+      <div class="fs-component-swatch"><span class="fs-swatch-dot" style="background:{hexcode}"></span></div>
+      <div class="fs-component-body">
+        <div class="fs-component-label">{label}</div>
+        <div class="fs-component-name">{html.escape(str(text))}</div>
+        <a class="fs-shop-btn" href="{link}" target="_blank" rel="noopener noreferrer">Shop ↗</a>
+      </div>
+    </div>
+    """
+
+
+def render_look_card_html(look_number, row, score_pct):
+    avatar_hex = swatch_color_for(row.get("primary_color"), row.get("secondary_color"))
+    gender = row.get("gender")
+
+    components = [
+        ("TOP", row.get("outfit_top", ""), COMPONENT_RETAILERS["TOP"]),
+        ("BOTTOM", row.get("outfit_bottom", ""), COMPONENT_RETAILERS["BOTTOM"]),
+        ("SHOES", row.get("outfit_shoes", ""), COMPONENT_RETAILERS["SHOES"]),
+        ("ACCESSORY", row.get("outfit_accessory", ""), COMPONENT_RETAILERS["ACCESSORY"]),
+    ]
+    comp_html = "".join(_component_html(label, text, retailer, gender)
+                         for label, text, retailer in components)
+
+    style_pref = html.escape(str(row.get("style_preference", "")))
+    skin_tone = html.escape(str(row.get("skin_tone", "")))
+    colors_line = html.escape(str(row.get("recommended_colors", "")))
+
+    return f"""
+    <div class="fs-look-card">
+      <div class="fs-look-head">
+        <span class="fs-look-avatar" style="background:{avatar_hex}"></span>
+        <div>
+          <div class="fs-look-title">Look #{look_number}</div>
+          <div class="fs-look-sub">{style_pref} · {skin_tone} skin · {score_pct}% match</div>
+        </div>
+      </div>
+      {comp_html}
+      <div class="fs-colors-footer">Recommended colors: {colors_line}</div>
+    </div>
+    """
+
+
+def render_results_html(profile_html, look_cards_html_list, note=None):
+    cards = "".join(look_cards_html_list)
+    note_html = f'<div class="fs-note">{html.escape(note)}</div>' if note else ""
+    return f"""
+    <div class="fs-root">
+      {profile_html}
+      <div class="fs-header">
+        <div class="fs-header-decoration"></div>
+        <div class="fs-header-eyebrow">YOUR MATCHED LOOKS</div>
+        <div class="fs-header-sub">Top 3 outfits from your personal style dataset</div>
+      </div>
+      {note_html}
+      <div class="fs-grid">{cards}</div>
+    </div>
+    """
+
+
+def render_error_html(message):
+    return f"""
+    <div class="fs-root">
+      <div class="fs-error">
+        <div class="fs-error-title">Something went wrong</div>
+        <div class="fs-error-msg">{html.escape(str(message))}</div>
+      </div>
+    </div>
+    """
+
+
+def render_placeholder_html():
+    return """
+    <div class="fs-root">
+      <div class="fs-placeholder">
+        Upload a photo or pick your features, then press
+        <strong>“Find My Looks”</strong> to see your personal color profile
+        and your top 3 matched outfits.
+      </div>
+    </div>
+    """
+
+
+# =============================================================================
+# Dataset & model loading
+# =============================================================================
+
+def order_choices(values, preferred_order):
+    """Order dropdown choices using a sensible preferred order, falling back
+    to alphabetical for anything not in that list."""
+    vals = {str(v) for v in values}
+    ordered = [p for p in preferred_order if p in vals]
+    remaining = sorted(v for v in vals if v not in ordered)
+    return ordered + remaining
+
+
+def load_catalog():
+    print(f"Loading dataset '{DATASET_REPO}' from the Hugging Face Hub...")
+    ds = load_dataset(DATASET_REPO)
+    train = ds["train"]
+    df = train.to_pandas()
+    images = [train[i]["image_improved"] for i in range(len(train))]
+    print(f"Catalog loaded: {len(df)} items, {len(df.columns)} columns.")
+    return df, images
+
+
+def load_embedding_model():
+    print(f"Loading embedding model '{EMBED_MODEL_REPO}' from the Hugging Face Hub...")
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    processor = AutoProcessor.from_pretrained(EMBED_MODEL_REPO)
+    model = AutoModel.from_pretrained(EMBED_MODEL_REPO).to(device).eval()
+    print(f"Embedding model ready on device='{device}'.")
+    return model, processor, device
+
+
+@torch.no_grad()
+def embed_catalog_images(model, processor, images, device, batch_size=32):
+    embs = []
+    for i in range(0, len(images), batch_size):
+        batch = [im.convert("RGB") for im in images[i:i + batch_size]]
+        inputs = processor(images=batch, return_tensors="pt").to(device)
+        outputs = model.get_image_features(**inputs)
+        feats = outputs.pooler_output if hasattr(outputs, "pooler_output") else outputs
+        feats = feats / feats.norm(dim=-1, keepdim=True)
+        embs.append(feats.cpu().numpy())
+        print(f"  embedded {min(i + batch_size, len(images))}/{len(images)} catalog images")
+    return np.vstack(embs).astype("float32")
+
+
+def build_faiss_index(df, images, model, processor, device):
+    image_embeddings = None
+    if os.path.exists(EMBED_CACHE_PATH):
+        try:
+            cached = np.load(EMBED_CACHE_PATH)
+            if cached.shape[0] == len(df):
+                print("Loaded cached catalog embeddings from disk.")
+                image_embeddings = cached
+        except Exception as e:
+            print(f"Ignoring unreadable embedding cache: {e}")
+
+    if image_embeddings is None:
+        image_embeddings = embed_catalog_images(model, processor, images, device)
+        try:
+            np.save(EMBED_CACHE_PATH, image_embeddings)
+        except Exception as e:
+            print(f"Could not cache embeddings to disk (non-fatal): {e}")
+
+    dim = image_embeddings.shape[1]
+    index = faiss.IndexFlatL2(dim)
+    normalized = image_embeddings.copy()
+    faiss.normalize_L2(normalized)
+    index.add(normalized)
+    print(f"FAISS index ready with {index.ntotal} items (dim={dim}).")
+    return index
+
+
+def pick_quickstarts(df, n=3):
+    """Pick `n` real catalog rows covering distinct styles, to use as
+    1-click 'Quick Starter' examples with guaranteed-valid feature values."""
+    eye_cycle = ["Brown", "Hazel", "Blue"]
+    seen_styles, starters = set(), []
+    for _, row in df.iterrows():
+        style = row["style_preference"]
+        if style in seen_styles:
+            continue
+        seen_styles.add(style)
+        starters.append({
+            "skin_tone": row["skin_tone"],
+            "undertone": row["undertone"],
+            "style": style,
+            "gender": row["gender"],
+            "age_group": row["age_group"],
+            "eye_color": eye_cycle[len(starters) % len(eye_cycle)],
+        })
+        if len(starters) == n:
+            break
+    return starters
+
+
+# =============================================================================
+# Gradio app
+# =============================================================================
+
+CUSTOM_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@600;700;800&family=Inter:wght@400;500;600&display=swap');
+
+.fs-root { max-width: 1100px; margin: 0 auto; font-family: 'Inter', system-ui, sans-serif; }
+.fs-app-title { font-family:'Outfit', system-ui, sans-serif; font-weight:800; font-size:28px; color:#1A1410; margin-bottom:2px; }
+.fs-app-tag { color:#8C8388; font-size:14px; margin-bottom:6px; }
+
+.fs-placeholder { color:#9c9396; font-size:14px; padding: 30px 6px; text-align:center; border:1px dashed #ECE3E2; border-radius:16px; }
+
+.fs-profile-card { background: linear-gradient(135deg,#1c1512 0%,#2b1c22 100%); border-radius: 18px; padding: 26px 28px; margin-bottom: 22px; color:#fff; position: relative; overflow:hidden; }
+.fs-profile-eyebrow { color:#e8638c; font-weight:700; font-size:12px; letter-spacing:.1em; text-transform:uppercase; margin-bottom:6px; }
+.fs-profile-season { font-family:'Outfit', sans-serif; font-weight:800; font-size:26px; margin-bottom:6px; }
+.fs-profile-blurb { color:#cfc6c6; font-size:14px; max-width:600px; margin-bottom:16px; line-height:1.4; }
+.fs-chip-row { display:flex; gap:10px; flex-wrap:wrap; }
+.fs-chip { display:flex; align-items:center; gap:6px; background:rgba(255,255,255,0.08); border-radius:999px; padding:6px 12px 6px 6px; font-size:12px; color:#f1ecec; }
+.fs-chip-dot { width:16px; height:16px; border-radius:50%; display:inline-block; border:2px solid rgba(255,255,255,.5); }
+
+.fs-header { position:relative; background:#16110F; border-radius:18px; padding:22px 26px; margin-bottom:22px; overflow:hidden; }
+.fs-header-decoration { position:absolute; top:-40px; right:-30px; width:130px; height:130px; border-radius:50%; background:#3d1f29; }
+.fs-header-eyebrow { color:#e0507a; font-weight:800; font-size:13px; letter-spacing:.12em; text-transform:uppercase; margin-bottom:6px; position:relative; z-index:1; }
+.fs-header-sub { color:#b9b0b2; font-size:15px; position:relative; z-index:1; }
+
+.fs-note { background:#FBEFE9; color:#8a5a3a; border-radius:12px; padding:10px 16px; font-size:13px; margin-bottom:16px; }
+.fs-caption { background:#FFF6E9; border:1px solid #F0DCB8; border-radius:14px; padding:14px 18px; margin-bottom:18px; font-size:14px; color:#5a4a30; }
+.fs-caption-label { font-weight:700; }
+
+.fs-grid { display:grid; grid-template-columns: repeat(3, 1fr); gap:18px; }
+@media (max-width: 900px) { .fs-grid { grid-template-columns: 1fr; } }
+
+.fs-look-card { background:#fff; border:1px solid #ECE3E2; border-radius:18px; padding:18px; box-shadow:0 2px 10px rgba(0,0,0,0.03); }
+.fs-look-head { display:flex; align-items:center; gap:12px; margin-bottom:16px; }
+.fs-look-avatar { width:48px; height:48px; border-radius:50%; flex-shrink:0; border:3px solid #e8638c; display:inline-block; }
+.fs-look-title { font-weight:800; font-size:17px; color:#1A1410; font-family:'Outfit',sans-serif; }
+.fs-look-sub { color:#9c9396; font-size:13px; margin-top:2px; }
+
+.fs-component { border:1px solid #ECE3E2; border-radius:14px; overflow:hidden; margin-bottom:14px; }
+.fs-component:last-child { margin-bottom:0; }
+.fs-component-swatch { background:#F1E8DA; height:64px; display:flex; align-items:center; justify-content:center; }
+.fs-swatch-dot { width:34px; height:34px; border-radius:50%; display:inline-block; box-shadow:0 0 0 1px rgba(0,0,0,0.05) inset; }
+.fs-component-body { padding:12px 16px; background:#fff; }
+.fs-component-label { color:#d6336c; font-weight:800; font-size:11px; letter-spacing:.08em; text-transform:uppercase; margin-bottom:3px; }
+.fs-component-name { font-weight:700; color:#1A1410; font-size:14.5px; margin-bottom:10px; line-height:1.3; }
+.fs-shop-btn { display:inline-flex; align-items:center; gap:6px; background:#14110F; color:#fff !important; padding:9px 18px; border-radius:999px; font-size:12.5px; font-weight:700; text-decoration:none !important; transition:transform .15s ease, background .15s ease; }
+.fs-shop-btn:hover { background:#2a2422; transform:translateY(-1px); }
+
+.fs-colors-footer { color:#9c9396; font-size:12px; margin-top:6px; padding-top:10px; border-top:1px dashed #ECE3E2; }
+
+.fs-error { background:#FBE8E8; border:1px solid #F0BABA; border-radius:14px; padding:18px 20px; }
+.fs-error-title { color:#A11D33; font-weight:800; margin-bottom:4px; }
+.fs-error-msg { color:#7a3a3a; font-size:14px; }
+"""
+
+
+def build_demo(df, model, processor, faiss_index, device):
+    skin_tone_choices = order_choices(df["skin_tone"].unique(), SKIN_DEPTH_ORDER)
+    undertone_choices = order_choices(df["undertone"].unique(), UNDERTONE_ORDER)
+    style_choices = sorted(df["style_preference"].unique().tolist())
+    gender_choices = sorted(df["gender"].unique().tolist())
+    age_choices = order_choices(df["age_group"].unique(), AGE_ORDER)
+    quickstarts = pick_quickstarts(df)
+
+    caption_pipe_holder = {"pipe": None, "failed": False}
+
+    def get_caption_pipe():
+        if caption_pipe_holder["pipe"] is None and not caption_pipe_holder["failed"]:
+            try:
+                from transformers import pipeline as hf_pipeline
+                print(f"Loading GenAI caption model '{CAPTION_MODEL_REPO}' (first use only)...")
+                caption_pipe_holder["pipe"] = hf_pipeline(
+                    "text-generation",
+                    model=CAPTION_MODEL_REPO,
+                    device=0 if device == "cuda" else -1,
+                )
+            except Exception as e:
+                print(f"Caption model unavailable, skipping AI note: {e}")
+                caption_pipe_holder["failed"] = True
+        return caption_pipe_holder["pipe"]
+
+    def generate_caption(row):
+        pipe = get_caption_pipe()
+        if pipe is None:
+            return None
+        try:
+            user_prompt = (
+                "Write one short, warm sentence (max 25 words) from a fashion stylist, "
+                f"recommending this look: a {row['style_preference']} style outfit in "
+                f"{row['primary_color']} and {row['secondary_color']}, best colors: "
+                f"{row['recommended_colors']}. Be specific and stylish, no hashtags."
+            )
+            messages = [{"role": "user", "content": user_prompt}]
+            out = pipe(messages, max_new_tokens=40, do_sample=True, temperature=0.7)
+            return out[0]["generated_text"][-1]["content"].strip()
+        except Exception as e:
+            print(f"[caption generation skipped] {e}")
+            return None
+
+    def predict(mode, photo, photo_skin_override, photo_undertone_override,
+                manual_skin, manual_undertone, style, gender, age_group,
+                eye_color, want_caption):
+        try:
+            is_photo_mode = str(mode).startswith("📷")
+
+            if is_photo_mode:
+                if photo is None:
+                    return render_error_html(
+                        "Please upload a photo, or switch to “Manual Selection”."
+                    )
+                detected_skin, detected_undertone, _ = estimate_skin_tone_undertone(
+                    photo, skin_tone_choices
+                )
+                skin_tone = (
+                    detected_skin if photo_skin_override in (None, "", AUTO_DETECT_LABEL)
+                    else photo_skin_override
+                )
+                undertone = (
+                    detected_undertone if photo_undertone_override in (None, "", AUTO_DETECT_LABEL)
+                    else photo_undertone_override
+                )
+                query_emb = embed_query_image(photo, model, processor, device)
+                if style:
+                    # Even in photo mode, let the chosen style nudge the search:
+                    # blend in a small text-embedding bias toward that style,
+                    # in the same CLIP vector space as the photo embedding.
+                    style_emb = embed_query_text(
+                        f"wearing a {style} style outfit", model, processor, device
+                    )
+                    query_emb = 0.75 * query_emb + 0.25 * style_emb
+            else:
+                skin_tone = manual_skin
+                undertone = manual_undertone
+                sentence = build_feature_sentence(
+                    skin_tone, undertone, style, gender, age_group, eye_color
+                )
+                query_emb = embed_query_text(sentence, model, processor, device)
+
+            indices, rows, distances, tier = faiss_filtered_search(
+                query_emb, faiss_index, df, top_k=3, exclude_idx=None,
+                gender=gender or None, age_group=age_group or None,
+            )
+            if len(indices) == 0:
+                return render_error_html(
+                    "No matching looks were found in the catalog for these filters — "
+                    "try a different style, gender, or age group."
+                )
+
+            season, blurb, palette = derive_color_profile(skin_tone, undertone, eye_color)
+            profile_html = render_profile_card_html(season, blurb, palette)
+
+            scores = [max(0.0, min(1.0, 1.0 - d / 2.0)) for d in distances]
+            look_cards = [
+                render_look_card_html(i + 1, rows.iloc[i], round(scores[i] * 100))
+                for i in range(len(rows))
+            ]
+
+            extra_html = ""
+            if want_caption:
+                caption = generate_caption(rows.iloc[0])
+                if caption:
+                    extra_html = render_caption_html(caption)
+
+            note = None
+            if tier == 2:
+                note = "We broadened the search beyond the exact age group to find your best matches."
+            elif tier == 3:
+                note = "We expanded the search beyond your filters so you still get great matches."
+
+            return extra_html + render_results_html(profile_html, look_cards, note=note)
+
+        except Exception as e:
+            traceback.print_exc()
+            return render_error_html(f"{type(e).__name__}: {e}")
+
+    def toggle_mode(mode):
+        is_photo = str(mode).startswith("📷")
+        return gr.update(visible=is_photo), gr.update(visible=not is_photo)
+
+    theme = gr.themes.Soft(
+        primary_hue=gr.themes.colors.pink,
+        secondary_hue=gr.themes.colors.rose,
+        neutral_hue=gr.themes.colors.gray,
+    ).set(
+        button_primary_background_fill="#14110F",
+        button_primary_background_fill_hover="#2a2422",
+        button_primary_text_color="#FFFFFF",
+    )
+
+    with gr.Blocks(css=CUSTOM_CSS, theme=theme, title="Personal Style Matcher") as demo:
+        gr.HTML(
+            '<div class="fs-app-title">✨ Personal Style Matcher</div>'
+            '<div class="fs-app-tag">Find your color profile and your top 3 matched '
+            'looks from our personal style dataset.</div>'
+        )
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                mode = gr.Radio(
+                    ["📷 Upload My Photo", "🎛️ Manual Selection"],
+                    value="🎛️ Manual Selection",
+                    label="How would you like to start?",
+                )
+
+                with gr.Group(visible=False) as photo_group:
+                    photo = gr.Image(label="Upload a clear, front-facing photo", type="pil")
+                    photo_skin_override = gr.Dropdown(
+                        [AUTO_DETECT_LABEL] + skin_tone_choices,
+                        value=AUTO_DETECT_LABEL,
+                        label="Skin tone (auto-detected — override if needed)",
+                    )
+                    photo_undertone_override = gr.Dropdown(
+                        [AUTO_DETECT_LABEL] + undertone_choices,
+                        value=AUTO_DETECT_LABEL,
+                        label="Undertone (auto-detected — override if needed)",
+                    )
+
+                with gr.Group(visible=True) as manual_group:
+                    manual_skin = gr.Dropdown(
+                        skin_tone_choices, value=skin_tone_choices[0], label="Skin Tone"
+                    )
+                    manual_undertone = gr.Dropdown(
+                        undertone_choices, value=undertone_choices[0], label="Undertone"
+                    )
+
+                style = gr.Dropdown(
+                    style_choices, value=style_choices[0], label="Clothing Style"
+                )
+                with gr.Row():
+                    gender = gr.Dropdown(
+                        gender_choices, value=gender_choices[0], label="Gender"
+                    )
+                    age_group = gr.Dropdown(
+                        age_choices, value=age_choices[0], label="Age Group"
+                    )
+                eye_color = gr.Dropdown(
+                    EYE_COLOR_CHOICES, value=EYE_COLOR_CHOICES[0], label="Eye Color"
+                )
+                want_caption = gr.Checkbox(
+                    label="✨ Add an AI stylist note (small GenAI text model)", value=False
+                )
+                submit_btn = gr.Button("Find My Looks", variant="primary", size="lg")
+
+            with gr.Column(scale=2):
+                output_html = gr.HTML(value=render_placeholder_html())
+
+        mode.change(toggle_mode, inputs=mode, outputs=[photo_group, manual_group])
+
+        predict_inputs = [
+            mode, photo, photo_skin_override, photo_undertone_override,
+            manual_skin, manual_undertone, style, gender, age_group,
+            eye_color, want_caption,
+        ]
+        submit_btn.click(predict, inputs=predict_inputs, outputs=output_html)
+
+        if quickstarts:
+            example_rows = [
+                [
+                    "🎛️ Manual Selection", None, AUTO_DETECT_LABEL, AUTO_DETECT_LABEL,
+                    qs["skin_tone"], qs["undertone"], qs["style"], qs["gender"],
+                    qs["age_group"], qs["eye_color"], False,
+                ]
+                for qs in quickstarts
+            ]
+            gr.Examples(
+                examples=example_rows,
+                inputs=predict_inputs,
+                outputs=output_html,
+                fn=predict,
+                run_on_click=True,
+                cache_examples=False,
+                label="✨ Quick Starters — click one to see it in action",
+            )
+
+    return demo
+
+
+# =============================================================================
+# Entry point
+# =============================================================================
+
+if __name__ == "__main__":
+    df, images = load_catalog()
+    clip_model, clip_processor, device = load_embedding_model()
+    faiss_index = build_faiss_index(df, images, clip_model, clip_processor, device)
+    demo = build_demo(df, clip_model, clip_processor, faiss_index, device)
+    demo.queue().launch()