Upload 16 files

README.md

@@ -1,14 +1,183 @@
 ---
-title: StyleWellBackend
-emoji: 👁
-colorFrom: green
-colorTo: yellow
+title: Wardrobe Backend API
 sdk: gradio
-sdk_version: 6.12.0
-app_file: app.py
 pinned: false
-license: openrail
-short_description: Style Well Model Backend
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Wardrobe Backend API
+
+Production backend for Wardrobe Assistant, designed to run on Hugging Face Spaces.
+
+The service provides:
+- garment classification from uploaded images,
+- wardrobe item persistence,
+- AI outfit scoring and recommendation,
+- shopping suggestion and product URL extraction,
+- lightweight feedback capture for preference signals.
+
+The API is built with FastAPI, uses SQLite for persistence, and integrates external AI providers for inference.
+
+## Architecture Summary
+
+- Runtime: FastAPI + Uvicorn
+- Storage: SQLite (persistent when `/data` is mounted on Hugging Face)
+- Inference: Hugging Face-hosted fine-tuned Qwen model (primary); NVIDIA-hosted chat completions used as fallback (default fallback model: `qwen/qwen3.5-122b-a10b`)
+- Retrieval: Web scraping pipeline for product discovery (Nike and Zalando logic in code)
+
+Core modules:
+- `app.py`: API routes, orchestration, inference calls, scraper flow
+- `db.py`: SQLite schema and CRUD/caching helpers
+- `scoring.py`: deterministic fallback scoring logic
+- `fashion_ai/`: recommendation service and ranking support
+
+## Repository Contents for Deployment
+
+Upload this backend directory as your Hugging Face Space source (or sync it via Git):
+
+- `app.py`
+- `db.py`
+- `scoring.py`
+- `scraper.py`
+- `zalando_scraper.py`
+- `requirements.txt`
+- `packages.txt`
+- `fashion_ai/`
+
+## Hugging Face Deployment
+
+1. Create a new Space.
+2. Select `Gradio` SDK.
+3. Use CPU hardware (inference is delegated to external APIs).
+4. Enable Persistent Storage if you want data durability across restarts.
+5. Add the required environment variables.
+6. Deploy the backend files.
+
+### Required Environment Variables
+
+- `HF_API_KEY`: API key for the primary Hugging Face-hosted fine-tuned Qwen model.
+- `NVIDIA_API_KEY`: API key for the NVIDIA inference fallback.
+
+### Common Optional Environment Variables
+
+Inference and reliability:
+- `HF_MODEL_ID` (default: your fine-tuned Qwen model on Hugging Face)
+- `HF_INVOKE_URL` (default: Hugging Face Inference API endpoint for the fine-tuned model)
+- `NVIDIA_MODEL_ID` (fallback; default: `qwen/qwen3.5-122b-a10b`)
+- `NVIDIA_INVOKE_URL` (fallback; default: `https://integrate.api.nvidia.com/v1/chat/completions`)
+- `OPENAI_MODEL_ID` (secondary fallback; OpenAI-compatible model ID if both primary and NVIDIA fallback are unavailable)
+- `OPENAI_API_KEY` (secondary fallback; required only if OpenAI fallback is enabled)
+- `NVIDIA_MAX_TOKENS` (default: `16384`)
+- `NVIDIA_REASONING_MAX_TOKENS` (default: `16384`)
+- `NVIDIA_TEMPERATURE` (default: `0.60`)
+- `NVIDIA_TOP_P` (default: `0.95`)
+- `NVIDIA_TIMEOUT_SECONDS` (default: `180`)
+- `NVIDIA_MAX_RETRIES` (default: `3`)
+- `NVIDIA_RETRY_BACKOFF_SECONDS` (default: `0.8`)
+- `NVIDIA_ENABLE_THINKING` (default: `false`)
+- `NVIDIA_FALLBACK_MODEL_IDS` (comma-separated fallback list)
+
+Matching and cache:
+- `MATCHING_RESULT_CACHE_MAX` (default: `500`)
+- `MATCHING_RESULT_CACHE_TTL_SECONDS` (default: `86400`)
+
+Scraper and planner:
+- `SCRAPER_DEFAULT_STORE` (default: `nike`)
+- `KIMI_MODEL_ID` (default: `moonshotai/kimi-k2.5`)
+- `KIMI_MAX_TOKENS` (default: `800`)
+
+Database path:
+- `DB_PATH` (optional override)
+
+When `DB_PATH` is not provided, the app uses:
+- `/data/wardrobe.db` if `/data` exists,
+- otherwise `./wardrobe.db`.
+
+## Inference Priority
+
+The service resolves inference providers in the following order:
+
+1. **Primary** - Fine-tuned Qwen model hosted on Hugging Face (`HF_MODEL_ID`).
+2. **Fallback 1** - NVIDIA-hosted chat completions (`NVIDIA_MODEL_ID`, default: `qwen/qwen3.5-122b-a10b`). Used when the primary model is unavailable or returns an error.
+3. **Fallback 2** - OpenAI-compatible model (`OPENAI_MODEL_ID`). Used when both the primary and NVIDIA fallback are unavailable.
+
+AI-powered routes return a service-level error only when all three providers are exhausted or unconfigured.
+
+## API Endpoints
+
+Health and service metadata:
+- `GET /`
+- `GET /health`
+
+Wardrobe ingestion and CRUD:
+- `POST /classify`
+- `POST /upload`
+- `GET /items`
+- `PUT /items/{item_id}`
+- `DELETE /items/{item_id}`
+
+Outfit intelligence:
+- `POST /ai/score-outfit`
+- `POST /ai/gap-analysis`
+- `POST /ai/recommend-outfits`
+- `POST /feedback`
+
+Shopping and scraping:
+- `POST /product-urls`
+- `POST /suggestions`
+- `POST /api/suggestions`
+- `POST /scraper/recommend`
+- `GET /scraper`
+- `GET /image-proxy`
+
+## Local Development
+
+### 1. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Export environment variables
+
+Linux/macOS:
+
+```bash
+export HF_API_KEY=""
+export NVIDIA_API_KEY=""        # fallback
+export OPENAI_API_KEY=""        # secondary fallback, optional
+```
+
+Windows PowerShell:
+
+```powershell
+$env:HF_API_KEY = ""
+$env:NVIDIA_API_KEY = ""        # fallback
+$env:OPENAI_API_KEY = ""        # secondary fallback, optional
+```
+
+### 3. Run the API
+
+```bash
+python app.py
+```
+
+The service starts on `http://0.0.0.0:7860`.
+
+## Smoke Checks
+
+Health:
+
+```bash
+curl "http://127.0.0.1:7860/health"
+```
+
+Image classification:
+
+```bash
+curl -X POST "http://127.0.0.1:7860/classify" \
+   -F "image=@/path/to/garment.jpg"
+```
+
+Expected post-deploy health signal:
+- `hf_api_configured` should be `"True"` (primary model).
+- `nvidia_api_configured` should be `"True"` (fallback model).

db.py

@@ -0,0 +1,272 @@
+"""
+db.py — persistent storage for Wardrobe Assistant on HF Spaces.
+
+Setup:
+  1. HF Space → Settings → Persistent Storage → Enable  (mounts at /data)
+  2. Drop this file next to app.py
+  3. No extra pip packages needed — sqlite3 is stdlib
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import uuid
+from contextlib import contextmanager
+from datetime import datetime, timezone, timedelta
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Path resolution
+# ---------------------------------------------------------------------------
+
+def _resolve_db_path() -> str:
+    custom = os.getenv("DB_PATH")
+    if custom:
+        return custom
+    if os.path.isdir("/data"):          # HF Spaces persistent volume
+        return "/data/wardrobe.db"
+    return "./wardrobe.db"              # local dev fallback
+
+
+DB_PATH = _resolve_db_path()
+
+
+# ---------------------------------------------------------------------------
+# Connection
+# ---------------------------------------------------------------------------
+
+@contextmanager
+def _conn():
+    """WAL mode + foreign keys. Auto-commit or rollback."""
+    con = sqlite3.connect(DB_PATH, check_same_thread=False)
+    con.row_factory = sqlite3.Row
+    con.execute("PRAGMA journal_mode=WAL")
+    con.execute("PRAGMA foreign_keys=ON")
+    try:
+        yield con
+        con.commit()
+    except Exception:
+        con.rollback()
+        raise
+    finally:
+        con.close()
+
+
+# ---------------------------------------------------------------------------
+# Schema
+# ---------------------------------------------------------------------------
+
+def init_db() -> None:
+    """Idempotent — safe to call on every startup."""
+    with _conn() as con:
+        con.executescript("""
+            CREATE TABLE IF NOT EXISTS items (
+                id          TEXT PRIMARY KEY,
+                image_url   TEXT NOT NULL DEFAULT '',
+                category    TEXT NOT NULL DEFAULT 'Unknown',
+                color       TEXT NOT NULL DEFAULT 'Unknown',
+                pattern     TEXT NOT NULL DEFAULT 'Solid',
+                fabric      TEXT NOT NULL DEFAULT 'Unknown',
+                fit         TEXT NOT NULL DEFAULT 'Unknown',
+                season      TEXT NOT NULL DEFAULT 'All-Season',
+                style       TEXT NOT NULL DEFAULT 'casual',
+                type        TEXT NOT NULL DEFAULT 'unknown',
+                description TEXT NOT NULL DEFAULT '{}',
+                created_at  TEXT NOT NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS outfit_feedback (
+                id          TEXT PRIMARY KEY,
+                top_id      TEXT NOT NULL,
+                bottom_id   TEXT NOT NULL,
+                occasion    TEXT NOT NULL DEFAULT 'casual',
+                action      TEXT NOT NULL CHECK(action IN ('wear','skip','save')),
+                score       INTEGER,
+                created_at  TEXT NOT NULL,
+                FOREIGN KEY (top_id)    REFERENCES items(id) ON DELETE CASCADE,
+                FOREIGN KEY (bottom_id) REFERENCES items(id) ON DELETE CASCADE
+            );
+
+            CREATE TABLE IF NOT EXISTS search_cache (
+                cache_key  TEXT PRIMARY KEY,
+                payload    TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                expires_at TEXT NOT NULL
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_items_type    ON items(type);
+            CREATE INDEX IF NOT EXISTS idx_items_created ON items(created_at DESC);
+            CREATE INDEX IF NOT EXISTS idx_fb_top        ON outfit_feedback(top_id);
+            CREATE INDEX IF NOT EXISTS idx_fb_bot        ON outfit_feedback(bottom_id);
+        """)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _row_to_item(row: sqlite3.Row) -> dict[str, Any]:
+    d = dict(row)
+    raw = d.get("description", "{}")
+    try:
+        d["description"] = json.loads(raw) if isinstance(raw, str) else raw
+    except (json.JSONDecodeError, TypeError):
+        d["description"] = {}
+    return d
+
+
+# ---------------------------------------------------------------------------
+# Items CRUD
+# ---------------------------------------------------------------------------
+
+def item_insert(item: dict[str, Any]) -> dict[str, Any]:
+    record = {
+        "id":          item.get("id") or str(uuid.uuid4()),
+        "image_url":   str(item.get("image_url") or ""),
+        "category":    str(item.get("category") or "Unknown"),
+        "color":       str(item.get("color") or "Unknown"),
+        "pattern":     str(item.get("pattern") or "Solid"),
+        "fabric":      str(item.get("fabric") or "Unknown"),
+        "fit":         str(item.get("fit") or "Unknown"),
+        "season":      str(item.get("season") or "All-Season"),
+        "style":       str(item.get("style") or "casual"),
+        "type":        str(item.get("type") or "unknown"),
+        "description": json.dumps(item.get("description") or {}),
+        "created_at":  item.get("created_at") or _now(),
+    }
+    with _conn() as con:
+        con.execute(
+            """INSERT INTO items
+               (id,image_url,category,color,pattern,fabric,fit,
+                season,style,type,description,created_at)
+               VALUES
+               (:id,:image_url,:category,:color,:pattern,:fabric,:fit,
+                :season,:style,:type,:description,:created_at)""",
+            record,
+        )
+    record["description"] = item.get("description") or {}
+    return record
+
+
+def item_get_all() -> list[dict[str, Any]]:
+    with _conn() as con:
+        rows = con.execute(
+            "SELECT * FROM items ORDER BY created_at DESC"
+        ).fetchall()
+    return [_row_to_item(r) for r in rows]
+
+
+def item_get(item_id: str) -> dict[str, Any] | None:
+    with _conn() as con:
+        row = con.execute(
+            "SELECT * FROM items WHERE id=?", (item_id,)
+        ).fetchone()
+    return _row_to_item(row) if row else None
+
+
+def item_update(item_id: str, patch: dict[str, Any]) -> dict[str, Any] | None:
+    existing = item_get(item_id)
+    if existing is None:
+        return None
+    if isinstance(patch.get("description"), dict):
+        merged = {**existing.get("description", {}), **patch["description"]}
+    else:
+        merged = existing.get("description", {})
+    allowed = {"image_url", "category", "color", "pattern",
+               "fabric", "fit", "season", "style", "type"}
+    updates = {k: str(v) for k, v in patch.items() if k in allowed}
+    updates["description"] = json.dumps(merged)
+    set_clause = ", ".join(f"{k}=:{k}" for k in updates)
+    updates["id"] = item_id
+    with _conn() as con:
+        con.execute(f"UPDATE items SET {set_clause} WHERE id=:id", updates)
+    return item_get(item_id)
+
+
+def item_delete(item_id: str) -> bool:
+    with _conn() as con:
+        cur = con.execute("DELETE FROM items WHERE id=?", (item_id,))
+    return cur.rowcount > 0
+
+
+# ---------------------------------------------------------------------------
+# Feedback
+# ---------------------------------------------------------------------------
+
+def feedback_record(
+    top_id: str,
+    bottom_id: str,
+    action: str,
+    occasion: str = "casual",
+    score: int | None = None,
+) -> dict[str, Any]:
+    rec = {
+        "id": str(uuid.uuid4()),
+        "top_id": top_id,
+        "bottom_id": bottom_id,
+        "occasion": occasion,
+        "action": action,
+        "score": score,
+        "created_at": _now(),
+    }
+    with _conn() as con:
+        con.execute(
+            """INSERT INTO outfit_feedback
+               (id,top_id,bottom_id,occasion,action,score,created_at)
+               VALUES(:id,:top_id,:bottom_id,:occasion,:action,:score,:created_at)""",
+            rec,
+        )
+    return rec
+
+
+# ---------------------------------------------------------------------------
+# Search cache
+# ---------------------------------------------------------------------------
+
+def cache_get(key: str) -> Any | None:
+    with _conn() as con:
+        row = con.execute(
+            "SELECT payload, expires_at FROM search_cache WHERE cache_key=?",
+            (key,),
+        ).fetchone()
+    if not row:
+        return None
+    if row["expires_at"] < _now():
+        cache_delete(key)
+        return None
+    try:
+        return json.loads(row["payload"])
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+
+def cache_set(key: str, payload: Any, ttl_seconds: int = 86_400) -> None:
+    expires = (datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)).isoformat()
+    with _conn() as con:
+        con.execute(
+            """INSERT INTO search_cache(cache_key,payload,created_at,expires_at)
+               VALUES(?,?,?,?)
+               ON CONFLICT(cache_key) DO UPDATE SET
+                 payload=excluded.payload,
+                 created_at=excluded.created_at,
+                 expires_at=excluded.expires_at""",
+            (key, json.dumps(payload), _now(), expires),
+        )
+
+
+def cache_delete(key: str) -> None:
+    with _conn() as con:
+        con.execute("DELETE FROM search_cache WHERE cache_key=?", (key,))
+
+
+def cache_purge_expired() -> int:
+    with _conn() as con:
+        cur = con.execute("DELETE FROM search_cache WHERE expires_at<?", (_now(),))
+    return cur.rowcount

fashion_ai/__init__.py

@@ -0,0 +1,12 @@
+from .encoder import FashionItemEncoder
+from .ranker import OutfitCompatibilityRanker
+from .retriever import OutfitCandidateRetriever
+from .service import MultimodalOutfitRecommendationService, get_recommendation_service
+
+__all__ = [
+    "FashionItemEncoder",
+    "MultimodalOutfitRecommendationService",
+    "OutfitCandidateRetriever",
+    "OutfitCompatibilityRanker",
+    "get_recommendation_service",
+]

fashion_ai/encoder.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import os
+from collections import OrderedDict
+from typing import Any
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+import numpy as np
+import torch
+from PIL import Image
+from transformers import AutoModel, AutoProcessor
+
+from .schemas import EncodedWardrobeItem, RecommendationContext, SlotName
+
+try:
+    import open_clip
+except ImportError:
+    open_clip = None
+
+
+DEFAULT_ENCODER_MODEL_ID = os.getenv("FASHION_ENCODER_MODEL_ID", "patrickjohncyh/fashion-clip")
+DEFAULT_EMBEDDING_DIM = int(os.getenv("FASHION_EMBEDDING_DIM", "512"))
+DEFAULT_IMAGE_TIMEOUT_SECONDS = int(os.getenv("FASHION_IMAGE_TIMEOUT_SECONDS", "8"))
+DEFAULT_CACHE_SIZE = int(os.getenv("FASHION_EMBEDDING_CACHE_SIZE", "2048"))
+
+_SLOT_KEYWORDS = {
+    "top": [
+        "topwear", "shirt", "t-shirt", "tee", "blouse",
+        "hoodie", "jacket", "blazer", "sweater", "polo", "coat",
+    ],
+    "bottom": [
+        "bottomwear", "jeans", "trouser", "trousers", "pant", "pants",
+        "shorts", "skirt", "jogger", "palazzo", "leggings", "chinos",
+    ],
+    "shoes": [
+        "footwear", "shoe", "shoes", "sneaker", "boot", "loafer",
+        "sandal", "heel",
+    ],
+    "accessory": [
+        "accessory", "accessories", "bag", "belt", "watch", "cap",
+        "hat", "scarf", "sunglasses", "jewelry",
+    ],
+}
+
+_STANDALONE_OUTFIT_KEYWORDS = [
+    "others", "kurta", "dress", "jumpsuit", "romper", "gown",
+    "saree", "lehenga", "co-ord", "coord", "one-piece", "one piece",
+]
+
+
+def infer_slot_name(item: dict[str, Any]) -> SlotName:
+    description = item.get("description") if isinstance(item.get("description"), dict) else {}
+    raw = " ".join(
+        [
+            str(item.get("type") or ""),
+            str(item.get("category") or ""),
+            str(description.get("type") or ""),
+            str(description.get("category") or ""),
+        ]
+    ).lower()
+
+    if any(keyword in raw for keyword in _STANDALONE_OUTFIT_KEYWORDS):
+        return "unknown"
+
+    for slot, keywords in _SLOT_KEYWORDS.items():
+        if any(keyword in raw for keyword in keywords):
+            return slot  # type: ignore[return-value]
+    return "unknown"
+
+
+class FashionItemEncoder:
+    """
+    Multimodal garment encoder.
+
+    Output shape:
+      encode_item(...).vector -> [D]
+      encode_context(...) -> [D]
+    """
+
+    def __init__(
+        self,
+        model_id: str = DEFAULT_ENCODER_MODEL_ID,
+        embedding_dim: int = DEFAULT_EMBEDDING_DIM,
+        device: str | None = None,
+        image_timeout_seconds: int = DEFAULT_IMAGE_TIMEOUT_SECONDS,
+        cache_size: int = DEFAULT_CACHE_SIZE,
+    ) -> None:
+        self.model_id = model_id
+        self.embedding_dim = embedding_dim
+        self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        self.image_timeout_seconds = image_timeout_seconds
+        self.cache_size = cache_size
+
+        self._backend = "fallback-hash"
+        self._model = None
+        self._processor = None
+        self._preprocess = None
+        self._tokenizer = None
+        self._load_attempted = False
+        self._embedding_cache: OrderedDict[str, np.ndarray] = OrderedDict()
+
+    @property
+    def backend_name(self) -> str:
+        self._ensure_model_loaded()
+        return self._backend
+
+    def encode_item(self, item: dict[str, Any]) -> EncodedWardrobeItem:
+        metadata_text = self._build_item_prompt(item)
+        cache_key = self._cache_key(item, metadata_text)
+
+        cached = self._embedding_cache.get(cache_key)
+        if cached is not None:
+            self._embedding_cache.move_to_end(cache_key)
+            return EncodedWardrobeItem(
+                item=item,
+                vector=cached.copy(),
+                slot=infer_slot_name(item),
+                metadata_text=metadata_text,
+            )
+
+        text_vec = self.encode_text(metadata_text)
+        image_vec = self.encode_image_url(str(item.get("image_url") or ""), metadata_text)
+        vector = text_vec if image_vec is None else self._normalize_vector((text_vec + image_vec) / 2.0)
+
+        self._remember_embedding(cache_key, vector)
+        return EncodedWardrobeItem(
+            item=item,
+            vector=vector.copy(),
+            slot=infer_slot_name(item),
+            metadata_text=metadata_text,
+        )
+
+    def encode_text(self, text: str) -> np.ndarray:
+        self._ensure_model_loaded()
+
+        if self._backend == "open_clip" and self._model is not None and self._tokenizer is not None:
+            with torch.inference_mode():
+                tokens = self._tokenizer([text]).to(self.device)
+                features = self._model.encode_text(tokens)
+            return self._resize_and_normalize(features[0].detach().float().cpu().numpy())
+
+        if self._backend == "transformers" and self._model is not None and self._processor is not None:
+            with torch.inference_mode():
+                inputs = self._processor(
+                    text=[text],
+                    return_tensors="pt",
+                    padding=True,
+                    truncation=True,
+                )
+                inputs = {name: value.to(self.device) for name, value in inputs.items()}
+                if hasattr(self._model, "get_text_features"):
+                    features = self._model.get_text_features(**inputs)
+                else:
+                    outputs = self._model(**inputs)
+                    features = getattr(outputs, "pooler_output", outputs.last_hidden_state[:, 0, :])
+            return self._resize_and_normalize(features[0].detach().float().cpu().numpy())
+
+        return self._fallback_embedding(text)
+
+    def encode_image_url(self, image_url: str, fallback_text: str) -> np.ndarray | None:
+        image = self._load_image(image_url)
+        if image is None:
+            return None
+        return self.encode_image(image, fallback_text)
+
+    def encode_image(self, image: Image.Image, fallback_text: str = "") -> np.ndarray:
+        self._ensure_model_loaded()
+
+        if self._backend == "open_clip" and self._model is not None and self._preprocess is not None:
+            with torch.inference_mode():
+                tensor = self._preprocess(image).unsqueeze(0).to(self.device)
+                features = self._model.encode_image(tensor)
+            return self._resize_and_normalize(features[0].detach().float().cpu().numpy())
+
+        if self._backend == "transformers" and self._model is not None and self._processor is not None:
+            with torch.inference_mode():
+                inputs = self._processor(images=[image], return_tensors="pt")
+                inputs = {name: value.to(self.device) for name, value in inputs.items()}
+                if hasattr(self._model, "get_image_features"):
+                    features = self._model.get_image_features(**inputs)
+                else:
+                    outputs = self._model(**inputs)
+                    features = getattr(outputs, "pooler_output", outputs.last_hidden_state[:, 0, :])
+            return self._resize_and_normalize(features[0].detach().float().cpu().numpy())
+
+        return self._fallback_embedding(f"image::{fallback_text}")
+
+    def encode_context(self, context: RecommendationContext) -> np.ndarray:
+        profile = context.user_profile or {}
+        favorite_colors = profile.get("favorite_colors")
+        disliked_styles = profile.get("disliked_styles")
+        prompt_parts = [
+            f"An outfit for {context.occasion or 'casual'}",
+            f"in {context.weather.season or 'all-season'} weather",
+            f"temperature {context.weather.temperature_c}C"
+            if context.weather.temperature_c is not None
+            else "",
+            "rainy conditions" if context.weather.is_rainy else "",
+            f"region {context.region or 'global'}",
+            f"preferred style {profile.get('style_profile')}" if profile.get("style_profile") else "",
+            f"favorite colors {', '.join(favorite_colors)}"
+            if isinstance(favorite_colors, list) and favorite_colors
+            else "",
+            f"disliked styles {', '.join(disliked_styles)}"
+            if isinstance(disliked_styles, list) and disliked_styles
+            else "",
+        ]
+        return self.encode_text(" ".join(part for part in prompt_parts if part))
+
+    def _ensure_model_loaded(self) -> None:
+        if self._load_attempted:
+            return
+        self._load_attempted = True
+
+        if open_clip is not None and self.model_id.lower().startswith("marqo/"):
+            try:
+                self._model, _, self._preprocess = open_clip.create_model_and_transforms(
+                    f"hf-hub:{self.model_id}",
+                    device=self.device,
+                )
+                self._tokenizer = open_clip.get_tokenizer(f"hf-hub:{self.model_id}")
+                self._model.eval()
+                self._backend = "open_clip"
+                return
+            except Exception:
+                self._model = None
+                self._preprocess = None
+                self._tokenizer = None
+
+        try:
+            self._processor = AutoProcessor.from_pretrained(self.model_id)
+            self._model = AutoModel.from_pretrained(self.model_id).to(self.device).eval()
+            self._backend = "transformers"
+        except Exception:
+            self._model = None
+            self._processor = None
+            self._backend = "fallback-hash"
+
+    def _load_image(self, image_url: str) -> Image.Image | None:
+        if not image_url or image_url.startswith("memory://") or image_url.startswith("data:"):
+            return None
+
+        parsed = urlparse(image_url)
+        try:
+            if parsed.scheme in {"http", "https"}:
+                request = Request(
+                    image_url,
+                    headers={"User-Agent": "Mozilla/5.0", "Accept": "image/*,*/*;q=0.8"},
+                )
+                with urlopen(request, timeout=self.image_timeout_seconds) as response:
+                    raw = response.read()
+                return Image.open(io.BytesIO(raw)).convert("RGB")
+
+            if os.path.isfile(image_url):
+                return Image.open(image_url).convert("RGB")
+        except Exception:
+            return None
+        return None
+
+    def _build_item_prompt(self, item: dict[str, Any]) -> str:
+        description = item.get("description") if isinstance(item.get("description"), dict) else {}
+        category = item.get("category") or description.get("category") or description.get("type") or "garment"
+        color = item.get("color") or description.get("color") or "unknown color"
+        pattern = item.get("pattern") or description.get("pattern") or "solid"
+        fabric = item.get("fabric") or description.get("fabric") or "unknown fabric"
+        fit = item.get("fit") or description.get("fit") or "regular"
+        season = item.get("season") or description.get("season") or "all-season"
+        style = item.get("style") or description.get("occasion") or description.get("style") or "casual"
+        slot = infer_slot_name(item)
+
+        return (
+            f"Fashion product photo of a {color} {pattern} {fabric} {category}, "
+            f"{fit} fit, {style} style, suitable for {season}, worn as {slot}."
+        )
+
+    def _cache_key(self, item: dict[str, Any], metadata_text: str) -> str:
+        payload = {
+            "id": str(item.get("id") or ""),
+            "image_url": str(item.get("image_url") or ""),
+            "metadata_text": metadata_text,
+        }
+        raw = json.dumps(payload, sort_keys=True, ensure_ascii=True).encode("utf-8")
+        return hashlib.sha256(raw).hexdigest()
+
+    def _remember_embedding(self, cache_key: str, vector: np.ndarray) -> None:
+        self._embedding_cache[cache_key] = vector.copy()
+        self._embedding_cache.move_to_end(cache_key)
+        while len(self._embedding_cache) > self.cache_size:
+            self._embedding_cache.popitem(last=False)
+
+    def _fallback_embedding(self, seed_text: str) -> np.ndarray:
+        digest = hashlib.sha256(seed_text.encode("utf-8", errors="ignore")).digest()
+        seed = int.from_bytes(digest[:8], "big", signed=False)
+        rng = np.random.default_rng(seed)
+        return self._normalize_vector(rng.standard_normal(self.embedding_dim).astype(np.float32))
+
+    def _resize_and_normalize(self, vector: np.ndarray) -> np.ndarray:
+        arr = np.asarray(vector, dtype=np.float32).reshape(-1)
+        if arr.shape[0] == self.embedding_dim:
+            return self._normalize_vector(arr)
+        if arr.shape[0] < 2:
+            return self._fallback_embedding(str(arr.tolist()))
+
+        src_x = np.linspace(0.0, 1.0, num=arr.shape[0], dtype=np.float32)
+        dst_x = np.linspace(0.0, 1.0, num=self.embedding_dim, dtype=np.float32)
+        resized = np.interp(dst_x, src_x, arr).astype(np.float32)
+        return self._normalize_vector(resized)
+
+    @staticmethod
+    def _normalize_vector(vector: np.ndarray) -> np.ndarray:
+        arr = np.asarray(vector, dtype=np.float32).reshape(-1)
+        norm = float(np.linalg.norm(arr))
+        if norm < 1e-8:
+            return np.zeros_like(arr, dtype=np.float32)
+        return arr / norm

fashion_ai/ranker.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+import math
+import os
+
+import numpy as np
+import torch
+import torch.nn as nn
+
+from .schemas import OutfitCandidate, RecommendationContext
+
+
+class OutfitCompatibilityRanker(nn.Module):
+    """
+    Transformer ranker.
+
+    Input:
+      outfit_tokens  [B, 6, D] = [CONTEXT, USER, TOP, BOTTOM, SHOES, ACCESSORY]
+      attention_mask [B, 6]
+
+    Output:
+      logits [B, 1]
+    """
+
+    def __init__(
+        self,
+        d_model: int = 512,
+        n_layers: int = 4,
+        n_heads: int = 8,
+        dropout: float = 0.1,
+    ) -> None:
+        super().__init__()
+        self.d_model = d_model
+        self.cls_token = nn.Parameter(torch.zeros(1, 1, d_model))
+        self.slot_embedding = nn.Embedding(7, d_model)
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=d_model,
+            nhead=n_heads,
+            dim_feedforward=d_model * 4,
+            dropout=dropout,
+            batch_first=True,
+            activation="gelu",
+            norm_first=True,
+        )
+        self.encoder = nn.TransformerEncoder(encoder_layer, num_layers=n_layers)
+        self.head = nn.Sequential(
+            nn.LayerNorm(d_model),
+            nn.Linear(d_model, d_model // 2),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(d_model // 2, 1),
+        )
+        nn.init.trunc_normal_(self.cls_token, std=0.02)
+
+    def forward(
+        self,
+        outfit_tokens: torch.Tensor,
+        attention_mask: torch.Tensor,
+    ) -> torch.Tensor:
+        if outfit_tokens.ndim != 3:
+            raise ValueError("outfit_tokens must have shape [B, S, D]")
+        if attention_mask.ndim != 2:
+            raise ValueError("attention_mask must have shape [B, S]")
+
+        batch_size, seq_len, _ = outfit_tokens.shape
+        cls = self.cls_token.expand(batch_size, 1, self.d_model)
+        tokens = torch.cat([cls, outfit_tokens], dim=1)
+        slot_ids = torch.arange(seq_len + 1, device=tokens.device).unsqueeze(0)
+        tokens = tokens + self.slot_embedding(slot_ids)
+
+        cls_mask = torch.ones((batch_size, 1), device=attention_mask.device, dtype=attention_mask.dtype)
+        mask = torch.cat([cls_mask, attention_mask], dim=1)
+        encoded = self.encoder(tokens, src_key_padding_mask=mask == 0)
+        return self.head(encoded[:, 0, :])
+
+
+class NeuralOutfitScorer:
+    """
+    Uses a trained transformer checkpoint when available.
+    Otherwise falls back to zero-shot geometric scoring over multimodal
+    embeddings so the endpoint stays usable before fine-tuning.
+    """
+
+    def __init__(
+        self,
+        d_model: int = 512,
+        checkpoint_path: str | None = None,
+        device: str | None = None,
+    ) -> None:
+        self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        self.model = OutfitCompatibilityRanker(d_model=d_model).to(self.device).eval()
+        self.checkpoint_path = checkpoint_path or os.getenv("FASHION_RANKER_CHECKPOINT")
+        self.is_trained = False
+        self._load_checkpoint_if_available()
+
+    def score_candidates(
+        self,
+        candidates: list[OutfitCandidate],
+        context_vector: np.ndarray,
+        user_vector: np.ndarray,
+        context: RecommendationContext,
+    ) -> list[OutfitCandidate]:
+        if not candidates:
+            return []
+        if self.is_trained:
+            return self._score_with_transformer(candidates, context_vector, user_vector, context)
+        return self._score_zero_shot(candidates, context_vector, user_vector, context)
+
+    def _score_with_transformer(
+        self,
+        candidates: list[OutfitCandidate],
+        context_vector: np.ndarray,
+        user_vector: np.ndarray,
+        context: RecommendationContext,
+    ) -> list[OutfitCandidate]:
+        token_batch = []
+        mask_batch = []
+        for candidate in candidates:
+            vectors = [
+                context_vector,
+                user_vector,
+                candidate.top.vector,
+                candidate.bottom.vector,
+                candidate.shoes.vector if candidate.shoes is not None else np.zeros_like(context_vector),
+                candidate.accessory.vector if candidate.accessory is not None else np.zeros_like(context_vector),
+            ]
+            mask = [
+                1,
+                1,
+                1,
+                1,
+                1 if candidate.shoes is not None else 0,
+                1 if candidate.accessory is not None else 0,
+            ]
+            token_batch.append(np.stack(vectors, axis=0))
+            mask_batch.append(mask)
+
+        with torch.inference_mode():
+            logits = self.model(
+                torch.tensor(np.stack(token_batch), dtype=torch.float32, device=self.device),
+                torch.tensor(np.asarray(mask_batch), dtype=torch.long, device=self.device),
+            ).squeeze(-1)
+            probs = torch.sigmoid(logits).detach().cpu().numpy()
+
+        return self._finalize_candidates(candidates, probs, context_vector, user_vector, context)
+
+    def _score_zero_shot(
+        self,
+        candidates: list[OutfitCandidate],
+        context_vector: np.ndarray,
+        user_vector: np.ndarray,
+        context: RecommendationContext,
+    ) -> list[OutfitCandidate]:
+        scores = []
+        for candidate in candidates:
+            item_vectors = [slot_item.vector for slot_item in candidate.slot_items()]
+            outfit_centroid = self._normalize(np.mean(np.stack(item_vectors, axis=0), axis=0))
+            context_alignment = self._cosine(outfit_centroid, context_vector)
+            user_alignment = self._cosine(outfit_centroid, user_vector)
+            pairwise_cohesion = self._pairwise_cohesion(item_vectors)
+            slot_coverage = math.log1p(len(item_vectors)) / math.log1p(4)
+
+            score = np.mean(
+                np.asarray(
+                    [
+                        self._to_unit_interval(context_alignment),
+                        self._to_unit_interval(user_alignment),
+                        self._to_unit_interval(pairwise_cohesion),
+                        slot_coverage,
+                    ],
+                    dtype=np.float32,
+                )
+            )
+            scores.append(float(np.clip(score, 0.0, 1.0)))
+
+        return self._finalize_candidates(candidates, scores, context_vector, user_vector, context)
+
+    def _finalize_candidates(
+        self,
+        candidates: list[OutfitCandidate],
+        probs: list[float] | np.ndarray,
+        context_vector: np.ndarray,
+        user_vector: np.ndarray,
+        context: RecommendationContext,
+    ) -> list[OutfitCandidate]:
+        scored = []
+        for candidate, prob in zip(candidates, probs, strict=False):
+            candidate.score = round(float(prob) * 100.0, 2)
+            candidate.breakdown = self._build_breakdown(candidate, context_vector, user_vector, context)
+            candidate.reason = self._build_reason(candidate, context)
+            candidate.tip = self._build_tip(candidate)
+            scored.append(candidate)
+        scored.sort(key=lambda item: item.score, reverse=True)
+        return scored
+
+    def _load_checkpoint_if_available(self) -> None:
+        if not self.checkpoint_path or not os.path.isfile(self.checkpoint_path):
+            return
+        try:
+            payload = torch.load(self.checkpoint_path, map_location=self.device)
+            state_dict = payload.get("model_state_dict", payload) if isinstance(payload, dict) else payload
+            self.model.load_state_dict(state_dict, strict=False)
+            self.model.eval()
+            self.is_trained = True
+        except Exception:
+            self.is_trained = False
+
+    def _build_breakdown(
+        self,
+        candidate: OutfitCandidate,
+        context_vector: np.ndarray,
+        user_vector: np.ndarray,
+        context: RecommendationContext,
+    ) -> dict[str, float]:
+        item_vectors = [slot_item.vector for slot_item in candidate.slot_items()]
+        outfit_centroid = self._normalize(np.mean(np.stack(item_vectors, axis=0), axis=0))
+        context_alignment = self._to_score(self._cosine(outfit_centroid, context_vector))
+        user_affinity = self._to_score(self._cosine(outfit_centroid, user_vector))
+        visual_cohesion = self._to_score(self._pairwise_cohesion(item_vectors))
+        top_bottom_compat = self._to_score(self._cosine(candidate.top.vector, candidate.bottom.vector))
+        occasion_fit = self._occasion_slot_fit(candidate, context.occasion)
+
+        return {
+            "color": round((visual_cohesion + top_bottom_compat) / 2.0, 2),
+            "style": round((context_alignment + visual_cohesion) / 2.0, 2),
+            "occasion": round((occasion_fit + context_alignment) / 2.0, 2),
+            "context_alignment": round(context_alignment, 2),
+            "user_affinity": round(user_affinity, 2),
+            "visual_cohesion": round(visual_cohesion, 2),
+        }
+
+    def _build_reason(self, candidate: OutfitCandidate, context: RecommendationContext) -> str:
+        parts = [
+            f"{candidate.top.item.get('color', 'Unknown')} {candidate.top.item.get('category', 'Topwear')}",
+            f"{candidate.bottom.item.get('color', 'Unknown')} {candidate.bottom.item.get('category', 'Bottomwear')}",
+        ]
+        if candidate.shoes is not None:
+            parts.append(
+                f"{candidate.shoes.item.get('color', 'Unknown')} {candidate.shoes.item.get('category', 'Footwear')}"
+            )
+        if candidate.accessory is not None:
+            parts.append(
+                f"{candidate.accessory.item.get('color', 'Unknown')} {candidate.accessory.item.get('category', 'Accessory')}"
+            )
+        return (
+            f"Learned multimodal embeddings rate {' + '.join(parts)} as a coherent "
+            f"combination for {context.occasion or 'casual'} context."
+        )
+
+    @staticmethod
+    def _build_tip(candidate: OutfitCandidate) -> str:
+        if candidate.score >= 85:
+            return "Strong outfit match. Keep accessories minimal so the silhouette stays clean."
+        if candidate.score >= 70:
+            return "Good base outfit. Add one tonal accessory to reinforce the palette."
+        return "This outfit is acceptable, but one slot can be swapped for stronger style alignment."
+
+    @staticmethod
+    def _occasion_slot_fit(candidate: OutfitCandidate, occasion: str) -> float:
+        occ = str(occasion or "casual").lower()
+        texts = " ".join(slot.metadata_text.lower() for slot in candidate.slot_items())
+        if occ in texts:
+            return 95.0
+        if occ in {"formal", "interview", "business", "office"} and any(
+            token in texts for token in ["shirt", "blazer", "trouser", "loafer"]
+        ):
+            return 88.0
+        if occ in {"party", "festive", "wedding"} and any(
+            token in texts for token in ["silk", "embroidered", "dress", "kurta"]
+        ):
+            return 88.0
+        if occ in {"sports", "gym", "active"} and any(
+            token in texts for token in ["sneaker", "jogger", "tee", "hoodie"]
+        ):
+            return 85.0
+        return 72.0
+
+    @staticmethod
+    def _pairwise_cohesion(vectors: list[np.ndarray]) -> float:
+        if len(vectors) < 2:
+            return 0.0
+        scores = []
+        for left_index in range(len(vectors)):
+            for right_index in range(left_index + 1, len(vectors)):
+                scores.append(NeuralOutfitScorer._cosine(vectors[left_index], vectors[right_index]))
+        return float(np.mean(np.asarray(scores, dtype=np.float32)))
+
+    @staticmethod
+    def _cosine(left: np.ndarray, right: np.ndarray) -> float:
+        left_vec = NeuralOutfitScorer._normalize(left)
+        right_vec = NeuralOutfitScorer._normalize(right)
+        return float(np.dot(left_vec, right_vec))
+
+    @staticmethod
+    def _to_score(value: float) -> float:
+        return round(100.0 * NeuralOutfitScorer._to_unit_interval(value), 2)
+
+    @staticmethod
+    def _to_unit_interval(value: float) -> float:
+        return float(np.clip((value + 1.0) / 2.0, 0.0, 1.0))
+
+    @staticmethod
+    def _normalize(vector: np.ndarray) -> np.ndarray:
+        arr = np.asarray(vector, dtype=np.float32).reshape(-1)
+        norm = float(np.linalg.norm(arr))
+        if norm < 1e-8:
+            return np.zeros_like(arr, dtype=np.float32)
+        return arr / norm

fashion_ai/retriever.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .encoder import FashionItemEncoder
+from .schemas import EncodedWardrobeItem, RecommendationContext, SlotName
+
+
+class OutfitCandidateRetriever:
+    """Slot-aware embedding retrieval with MMR diversification."""
+
+    def __init__(
+        self,
+        encoder: FashionItemEncoder,
+        slot_pool_size: int = 24,
+        mmr_lambda: float = 0.72,
+    ) -> None:
+        self.encoder = encoder
+        self.slot_pool_size = slot_pool_size
+        self.mmr_lambda = mmr_lambda
+
+    def encode_wardrobe(self, wardrobe_items: list[dict[str, Any]]) -> list[EncodedWardrobeItem]:
+        return [self.encoder.encode_item(item) for item in wardrobe_items]
+
+    def split_by_slot(
+        self,
+        encoded_items: list[EncodedWardrobeItem],
+    ) -> dict[SlotName, list[EncodedWardrobeItem]]:
+        buckets: dict[SlotName, list[EncodedWardrobeItem]] = {
+            "top": [],
+            "bottom": [],
+            "shoes": [],
+            "accessory": [],
+            "unknown": [],
+        }
+        for item in encoded_items:
+            buckets[item.slot].append(item)
+        return buckets
+
+    def retrieve(
+        self,
+        encoded_items: list[EncodedWardrobeItem],
+        context: RecommendationContext,
+        locked_top: dict[str, Any] | None = None,
+        locked_bottom: dict[str, Any] | None = None,
+        locked_other: dict[str, Any] | None = None,
+        candidate_pool: int | None = None,
+    ) -> dict[SlotName, list[EncodedWardrobeItem]]:
+        buckets = self.split_by_slot(encoded_items)
+        query_vec = self.encoder.encode_context(context)
+        pool_size = candidate_pool or self.slot_pool_size
+        locked_top_vec = self.encoder.encode_item(locked_top).vector if locked_top else None
+        locked_bottom_vec = self.encoder.encode_item(locked_bottom).vector if locked_bottom else None
+        locked_other_encoded = self.encoder.encode_item(locked_other) if locked_other else None
+        accessory_bucket = buckets["accessory"] + buckets["unknown"]
+
+        return {
+            "top": [self.encoder.encode_item(locked_top)] if locked_top else self._rank_bucket(
+                buckets["top"],
+                query_vec=self._merge_query(query_vec, locked_bottom_vec),
+                top_k=pool_size,
+            ),
+            "bottom": [self.encoder.encode_item(locked_bottom)] if locked_bottom else self._rank_bucket(
+                buckets["bottom"],
+                query_vec=self._merge_query(query_vec, locked_top_vec),
+                top_k=pool_size,
+            ),
+            "shoes": self._rank_bucket(
+                buckets["shoes"],
+                query_vec=self._merge_query(
+                    query_vec,
+                    locked_top_vec,
+                    locked_bottom_vec,
+                    locked_other_encoded.vector if locked_other_encoded and locked_other_encoded.slot == "shoes" else None,
+                ),
+                top_k=min(pool_size, 12),
+            ) if not locked_other_encoded or locked_other_encoded.slot != "shoes" else [locked_other_encoded],
+            "accessory": (
+                [locked_other_encoded]
+                if locked_other_encoded and locked_other_encoded.slot != "shoes"
+                else self._rank_bucket(
+                    accessory_bucket,
+                    query_vec=self._merge_query(query_vec, locked_top_vec, locked_bottom_vec),
+                    top_k=min(pool_size, 12),
+                )
+            ),
+            "unknown": [],
+        }
+
+    def _rank_bucket(
+        self,
+        bucket: list[EncodedWardrobeItem],
+        query_vec: np.ndarray,
+        top_k: int,
+    ) -> list[EncodedWardrobeItem]:
+        if not bucket:
+            return []
+
+        ranked = sorted(
+            bucket,
+            key=lambda item: float(np.dot(item.vector, query_vec)),
+            reverse=True,
+        )
+        return self._mmr_diversify(ranked, query_vec=query_vec, top_k=top_k)
+
+    def _mmr_diversify(
+        self,
+        ranked_items: list[EncodedWardrobeItem],
+        query_vec: np.ndarray,
+        top_k: int,
+    ) -> list[EncodedWardrobeItem]:
+        selected: list[EncodedWardrobeItem] = []
+        remaining = list(ranked_items)
+
+        while remaining and len(selected) < top_k:
+            best_index = 0
+            best_score = -1e9
+            for index, item in enumerate(remaining):
+                query_score = float(np.dot(item.vector, query_vec))
+                novelty_penalty = 0.0
+                if selected:
+                    novelty_penalty = max(float(np.dot(item.vector, prev.vector)) for prev in selected)
+                mmr_score = self.mmr_lambda * query_score - (1.0 - self.mmr_lambda) * novelty_penalty
+                if mmr_score > best_score:
+                    best_index = index
+                    best_score = mmr_score
+            selected.append(remaining.pop(best_index))
+
+        return selected
+
+    @staticmethod
+    def _merge_query(*vectors: np.ndarray | None) -> np.ndarray:
+        valid = [np.asarray(vec, dtype=np.float32) for vec in vectors if vec is not None]
+        if not valid:
+            return np.zeros((1,), dtype=np.float32)
+        merged = np.mean(np.stack(valid, axis=0), axis=0)
+        norm = float(np.linalg.norm(merged))
+        if norm < 1e-8:
+            return merged
+        return merged / norm

fashion_ai/schemas.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import numpy as np
+
+SlotName = Literal["top", "bottom", "shoes", "accessory", "unknown"]
+
+
+@dataclass(slots=True)
+class WeatherContext:
+    season: str = "all-season"
+    temperature_c: float | None = None
+    is_rainy: bool | None = None
+
+
+@dataclass(slots=True)
+class RecommendationContext:
+    occasion: str = "casual"
+    weather: WeatherContext = field(default_factory=WeatherContext)
+    region: str = "global"
+    user_profile: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class EncodedWardrobeItem:
+    item: dict[str, Any]
+    vector: np.ndarray
+    slot: SlotName
+    metadata_text: str
+
+
+@dataclass(slots=True)
+class OutfitCandidate:
+    top: EncodedWardrobeItem
+    bottom: EncodedWardrobeItem
+    shoes: EncodedWardrobeItem | None = None
+    accessory: EncodedWardrobeItem | None = None
+    score: float = 0.0
+    breakdown: dict[str, float] = field(default_factory=dict)
+    reason: str = ""
+    tip: str = ""
+
+    def slot_items(self) -> list[EncodedWardrobeItem]:
+        return [
+            slot_item
+            for slot_item in [self.top, self.bottom, self.shoes, self.accessory]
+            if slot_item is not None
+        ]

fashion_ai/service.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import numpy as np
+
+from .encoder import FashionItemEncoder
+from .ranker import NeuralOutfitScorer
+from .retriever import OutfitCandidateRetriever
+from .schemas import (
+    EncodedWardrobeItem,
+    OutfitCandidate,
+    RecommendationContext,
+    WeatherContext,
+)
+
+
+DEFAULT_TOP_K = int(os.getenv("FASHION_RECOMMEND_TOP_K", "5"))
+DEFAULT_CANDIDATE_POOL = int(os.getenv("FASHION_CANDIDATE_POOL", "24"))
+DEFAULT_MAX_BEAM = int(os.getenv("FASHION_MAX_BEAM", "64"))
+DEFAULT_DIVERSITY_LAMBDA = float(os.getenv("FASHION_DIVERSITY_LAMBDA", "0.28"))
+
+_SERVICE_SINGLETON: MultimodalOutfitRecommendationService | None = None
+
+
+class MultimodalOutfitRecommendationService:
+    """Multimodal retrieval + ranking service for outfit recommendations."""
+
+    def __init__(
+        self,
+        encoder: FashionItemEncoder | None = None,
+        retriever: OutfitCandidateRetriever | None = None,
+        scorer: NeuralOutfitScorer | None = None,
+        top_k: int = DEFAULT_TOP_K,
+        candidate_pool: int = DEFAULT_CANDIDATE_POOL,
+        max_beam: int = DEFAULT_MAX_BEAM,
+        diversity_lambda: float = DEFAULT_DIVERSITY_LAMBDA,
+    ) -> None:
+        self.encoder = encoder or FashionItemEncoder()
+        self.retriever = retriever or OutfitCandidateRetriever(
+            self.encoder,
+            slot_pool_size=candidate_pool,
+        )
+        self.scorer = scorer or NeuralOutfitScorer(d_model=self.encoder.embedding_dim)
+        self.top_k = top_k
+        self.candidate_pool = candidate_pool
+        self.max_beam = max_beam
+        self.diversity_lambda = diversity_lambda
+
+    def recommend(
+        self,
+        wardrobe_items: list[dict[str, Any]],
+        occasion: str = "casual",
+        top_selected: dict[str, Any] | None = None,
+        bottom_selected: dict[str, Any] | None = None,
+        other_selected: dict[str, Any] | None = None,
+        weather: dict[str, Any] | None = None,
+        user_profile: dict[str, Any] | None = None,
+        region: str = "global",
+        top_k: int | None = None,
+        candidate_pool: int | None = None,
+        diversity_lambda: float | None = None,
+    ) -> dict[str, Any]:
+        context = self._build_context(occasion, weather, user_profile, region)
+        top_k = top_k or self.top_k
+        candidate_pool = candidate_pool or self.candidate_pool
+        diversity_lambda = self.diversity_lambda if diversity_lambda is None else diversity_lambda
+
+        encoded_items = self.retriever.encode_wardrobe(wardrobe_items)
+        slot_buckets = self.retriever.split_by_slot(encoded_items)
+        if not encoded_items:
+            return self._empty_payload(occasion, "A", "Your wardrobe is empty. Add garments to get outfit recommendations.")
+        if not slot_buckets["top"] or not slot_buckets["bottom"]:
+            return self._empty_payload(
+                occasion,
+                "A",
+                "You need at least one topwear and one bottomwear item to generate outfits.",
+            )
+
+        case_name = self._resolve_case_name(top_selected, bottom_selected)
+        retrieved = self.retriever.retrieve(
+            encoded_items=encoded_items,
+            context=context,
+            locked_top=top_selected,
+            locked_bottom=bottom_selected,
+            locked_other=other_selected,
+            candidate_pool=candidate_pool,
+        )
+        context_vector = self.encoder.encode_context(context)
+        user_vector = self._build_user_vector(context, encoded_items)
+
+        candidates = self._assemble_candidates(retrieved)
+        scored = self.scorer.score_candidates(candidates, context_vector, user_vector, context)
+        diversified = self._diversify(scored, top_k=top_k, diversity_lambda=diversity_lambda)
+        payloads = [
+            self._candidate_to_payload(candidate, rank=index + 1)
+            for index, candidate in enumerate(diversified)
+        ]
+
+        selected_outfit_score = None
+        improved_recommendations: list[dict[str, Any]] = []
+        recommendations = payloads
+
+        if case_name == "D" and top_selected and bottom_selected:
+            selected_candidates = self._assemble_candidates(
+                {
+                    "top": [self.encoder.encode_item(top_selected)],
+                    "bottom": [self.encoder.encode_item(bottom_selected)],
+                    "shoes": [],
+                    "accessory": [],
+                    "unknown": [],
+                }
+            )
+            selected_scored = self.scorer.score_candidates(
+                selected_candidates,
+                context_vector,
+                user_vector,
+                context,
+            )
+            best_selected = self._diversify(selected_scored, top_k=1, diversity_lambda=0.0)
+            selected_outfit_score = self._candidate_to_payload(best_selected[0], rank=1) if best_selected else None
+            improved_recommendations = payloads[:top_k]
+            recommendations = []
+
+        return {
+            "occasion": occasion,
+            "case": case_name,
+            "selected_outfit_score": selected_outfit_score,
+            "recommendations": recommendations,
+            "improved_recommendations": improved_recommendations,
+            "total_combinations_checked": len(candidates),
+            "notice": (
+                "Selected outfit may not be the best fit for this occasion."
+                if selected_outfit_score and selected_outfit_score.get("score", 0) < 45
+                else None
+            ),
+            "engine_version": (
+                f"fashion-mm-v1::{self.encoder.backend_name}"
+                f"::{ 'trained-transformer' if self.scorer.is_trained else 'zero-shot-ranker' }"
+            ),
+        }
+
+    def _assemble_candidates(
+        self,
+        slot_candidates: dict[str, list[EncodedWardrobeItem]],
+    ) -> list[OutfitCandidate]:
+        tops = slot_candidates.get("top") or []
+        bottoms = slot_candidates.get("bottom") or []
+
+        candidates: list[OutfitCandidate] = []
+        for top in tops[: self.candidate_pool]:
+            for bottom in bottoms[: self.candidate_pool]:
+                if top.item.get("id") == bottom.item.get("id"):
+                    continue
+
+                candidates.append(
+                    OutfitCandidate(
+                        top=top,
+                        bottom=bottom,
+                        shoes=None,
+                        accessory=None,
+                    )
+                )
+                if len(candidates) >= self.max_beam:
+                    return candidates
+        return candidates
+
+    def _diversify(
+        self,
+        scored: list[OutfitCandidate],
+        top_k: int,
+        diversity_lambda: float,
+    ) -> list[OutfitCandidate]:
+        selected: list[OutfitCandidate] = []
+        remaining = list(scored)
+        while remaining and len(selected) < top_k:
+            best_index = 0
+            best_score = -1e9
+            for index, candidate in enumerate(remaining):
+                relevance = candidate.score / 100.0
+                redundancy = 0.0
+                if selected:
+                    redundancy = max(self._candidate_similarity(candidate, prev) for prev in selected)
+                mmr_score = (1.0 - diversity_lambda) * relevance - diversity_lambda * redundancy
+                if mmr_score > best_score:
+                    best_index = index
+                    best_score = mmr_score
+            selected.append(remaining.pop(best_index))
+        return selected
+
+    def _build_user_vector(
+        self,
+        context: RecommendationContext,
+        encoded_items: list[EncodedWardrobeItem],
+    ) -> np.ndarray:
+        liked_ids = set(str(item_id) for item_id in context.user_profile.get("liked_item_ids", []) if item_id)
+        disliked_ids = set(str(item_id) for item_id in context.user_profile.get("disliked_item_ids", []) if item_id)
+
+        vectors = []
+        for encoded_item in encoded_items:
+            item_id = str(encoded_item.item.get("id") or "")
+            if item_id in liked_ids:
+                vectors.append(encoded_item.vector)
+            if item_id in disliked_ids:
+                vectors.append(-encoded_item.vector)
+
+        if vectors:
+            merged = np.mean(np.stack(vectors, axis=0), axis=0)
+            norm = float(np.linalg.norm(merged))
+            if norm > 1e-8:
+                return merged / norm
+        return self.encoder.encode_text("User prefers versatile, well coordinated, context-appropriate outfits")
+
+    @staticmethod
+    def _candidate_to_payload(candidate: OutfitCandidate, rank: int) -> dict[str, Any]:
+        payload = {
+            "rank": rank,
+            "score": candidate.score,
+            "breakdown": candidate.breakdown,
+            "reason": candidate.reason,
+            "tip": candidate.tip,
+            "top": MultimodalOutfitRecommendationService._item_payload(candidate.top),
+            "bottom": MultimodalOutfitRecommendationService._item_payload(candidate.bottom),
+        }
+        return payload
+
+    @staticmethod
+    def _item_payload(encoded_item: EncodedWardrobeItem) -> dict[str, Any]:
+        return {
+            "id": encoded_item.item.get("id"),
+            "category": encoded_item.item.get("category"),
+            "color": encoded_item.item.get("color"),
+            "image_url": encoded_item.item.get("image_url", ""),
+        }
+
+    @staticmethod
+    def _build_context(
+        occasion: str,
+        weather: dict[str, Any] | None,
+        user_profile: dict[str, Any] | None,
+        region: str,
+    ) -> RecommendationContext:
+        weather = weather or {}
+        return RecommendationContext(
+            occasion=occasion or "casual",
+            weather=WeatherContext(
+                season=str(weather.get("season") or "all-season"),
+                temperature_c=weather.get("temperature_c"),
+                is_rainy=weather.get("is_rainy"),
+            ),
+            region=region or "global",
+            user_profile=user_profile or {},
+        )
+
+    @staticmethod
+    def _resolve_case_name(
+        top_selected: dict[str, Any] | None,
+        bottom_selected: dict[str, Any] | None,
+    ) -> str:
+        if top_selected and bottom_selected:
+            return "D"
+        if top_selected:
+            return "B"
+        if bottom_selected:
+            return "C"
+        return "A"
+
+    @staticmethod
+    def _empty_payload(occasion: str, case_name: str, notice: str) -> dict[str, Any]:
+        return {
+            "occasion": occasion,
+            "case": case_name,
+            "selected_outfit_score": None,
+            "recommendations": [],
+            "improved_recommendations": [],
+            "total_combinations_checked": 0,
+            "notice": notice,
+            "engine_version": "fashion-mm-v1::empty",
+        }
+
+    def score_outfit(
+        self,
+        top: dict[str, Any],
+        bottom: dict[str, Any],
+        other: dict[str, Any] | None = None,
+        occasion: str = "casual",
+        weather: dict[str, Any] | None = None,
+        user_profile: dict[str, Any] | None = None,
+        region: str = "global",
+    ) -> dict[str, Any]:
+        context = self._build_context(occasion, weather, user_profile, region)
+        other_encoded = self.encoder.encode_item(other) if other else None
+        candidate = OutfitCandidate(
+            top=self.encoder.encode_item(top),
+            bottom=self.encoder.encode_item(bottom),
+            shoes=other_encoded if other_encoded and other_encoded.slot == "shoes" else None,
+            accessory=other_encoded if other_encoded and other_encoded.slot != "shoes" else None,
+        )
+        scored = self.scorer.score_candidates(
+            candidates=[candidate],
+            context_vector=self.encoder.encode_context(context),
+            user_vector=self._build_user_vector(context, candidate.slot_items()),
+            context=context,
+        )
+        best = scored[0]
+        return {
+            "score": best.score,
+            "breakdown": best.breakdown,
+            "reason": best.reason,
+            "tip": best.tip,
+            "engine_version": (
+                f"fashion-mm-v1::{self.encoder.backend_name}"
+                f"::{ 'trained-transformer' if self.scorer.is_trained else 'zero-shot-ranker' }"
+            ),
+        }
+
+    @staticmethod
+    def _candidate_similarity(left: OutfitCandidate, right: OutfitCandidate) -> float:
+        left_vec = np.mean(np.stack([item.vector for item in left.slot_items()], axis=0), axis=0)
+        right_vec = np.mean(np.stack([item.vector for item in right.slot_items()], axis=0), axis=0)
+        left_norm = float(np.linalg.norm(left_vec))
+        right_norm = float(np.linalg.norm(right_vec))
+        if left_norm < 1e-8 or right_norm < 1e-8:
+            return 0.0
+        return float(np.dot(left_vec / left_norm, right_vec / right_norm))
+
+
+def get_recommendation_service() -> MultimodalOutfitRecommendationService:
+    global _SERVICE_SINGLETON
+    if _SERVICE_SINGLETON is None:
+        _SERVICE_SINGLETON = MultimodalOutfitRecommendationService()
+    return _SERVICE_SINGLETON

fashion_ai/training.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import json
+import random
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from torch.utils.data import DataLoader, Dataset
+
+from .encoder import FashionItemEncoder, infer_slot_name
+from .ranker import OutfitCompatibilityRanker
+from .schemas import RecommendationContext, WeatherContext
+
+
+@dataclass(slots=True)
+class TrainingSample:
+    outfit: dict[str, Any]
+    label: float
+    occasion: str = "casual"
+    weather: dict[str, Any] | None = None
+    user_profile: dict[str, Any] | None = None
+
+
+class OutfitRankingDataset(Dataset[TrainingSample]):
+    """
+    JSONL schema per row:
+    {
+      "outfit": {"top": {...}, "bottom": {...}, "shoes": {...}, "accessory": {...}},
+      "label": 1,
+      "occasion": "formal",
+      "weather": {"season": "summer", "temperature_c": 30},
+      "user_profile": {"style_profile": "minimal", "favorite_colors": ["navy"]}
+    }
+    """
+
+    def __init__(self, path: str | Path) -> None:
+        self.samples = self._load_samples(path)
+
+    def __len__(self) -> int:
+        return len(self.samples)
+
+    def __getitem__(self, index: int) -> TrainingSample:
+        return self.samples[index]
+
+    @staticmethod
+    def _load_samples(path: str | Path) -> list[TrainingSample]:
+        rows: list[TrainingSample] = []
+        with open(path, "r", encoding="utf-8") as file_obj:
+            for line in file_obj:
+                line = line.strip()
+                if not line:
+                    continue
+                payload = json.loads(line)
+                rows.append(
+                    TrainingSample(
+                        outfit=payload.get("outfit", {}),
+                        label=float(payload.get("label", 1.0)),
+                        occasion=str(payload.get("occasion") or "casual"),
+                        weather=payload.get("weather") if isinstance(payload.get("weather"), dict) else None,
+                        user_profile=payload.get("user_profile")
+                        if isinstance(payload.get("user_profile"), dict)
+                        else None,
+                    )
+                )
+        return rows
+
+
+class NegativeSampler:
+    """Hard negative sampler using nearest same-slot replacements."""
+
+    def __init__(
+        self,
+        catalog_items: list[dict[str, Any]],
+        encoder: FashionItemEncoder,
+        hard_negative_top_k: int = 20,
+    ) -> None:
+        self.encoder = encoder
+        self.hard_negative_top_k = hard_negative_top_k
+        self.slot_catalog = {
+            "top": [],
+            "bottom": [],
+            "shoes": [],
+            "accessory": [],
+            "unknown": [],
+        }
+        for item in catalog_items:
+            encoded = self.encoder.encode_item(item)
+            self.slot_catalog[encoded.slot].append(encoded)
+
+    def sample(self, outfit: dict[str, Any], occasion: str = "casual") -> dict[str, Any]:
+        candidate = dict(outfit)
+        replaceable_slots = [
+            slot_name
+            for slot_name in ["top", "bottom", "shoes", "accessory"]
+            if isinstance(outfit.get(slot_name), dict)
+        ]
+        if not replaceable_slots:
+            return candidate
+
+        slot_to_replace = random.choice(replaceable_slots)
+        anchor = outfit[slot_to_replace]
+        pool = self.slot_catalog.get(infer_slot_name(anchor), [])
+        if not pool:
+            return candidate
+
+        anchor_vec = self.encoder.encode_item(anchor).vector
+        ranked = sorted(pool, key=lambda entry: float(np.dot(entry.vector, anchor_vec)), reverse=True)
+        hard_pool = [
+            entry.item
+            for entry in ranked[: self.hard_negative_top_k]
+            if str(entry.item.get("id")) != str(anchor.get("id"))
+        ]
+        if not hard_pool:
+            return candidate
+
+        candidate[slot_to_replace] = random.choice(hard_pool)
+        candidate["negative_source"] = {
+            "strategy": "hard_same_slot_replacement",
+            "slot": slot_to_replace,
+            "occasion": occasion,
+        }
+        return candidate
+
+
+class OutfitRankerCollator:
+    def __init__(self, encoder: FashionItemEncoder) -> None:
+        self.encoder = encoder
+
+    def __call__(self, samples: Iterable[TrainingSample]) -> dict[str, torch.Tensor]:
+        token_rows = []
+        mask_rows = []
+        labels = []
+
+        for sample in samples:
+            context = RecommendationContext(
+                occasion=sample.occasion,
+                weather=WeatherContext(
+                    season=str((sample.weather or {}).get("season") or "all-season"),
+                    temperature_c=(sample.weather or {}).get("temperature_c"),
+                    is_rainy=(sample.weather or {}).get("is_rainy"),
+                ),
+                user_profile=sample.user_profile or {},
+            )
+            row = [
+                self.encoder.encode_context(context),
+                self.encoder.encode_text(json.dumps(sample.user_profile or {"style_profile": "general"}, sort_keys=True)),
+            ]
+            mask = [1, 1]
+
+            for slot_name in ["top", "bottom", "shoes", "accessory"]:
+                slot_value = sample.outfit.get(slot_name)
+                if isinstance(slot_value, dict):
+                    row.append(self.encoder.encode_item(slot_value).vector)
+                    mask.append(1)
+                else:
+                    row.append(np.zeros(self.encoder.embedding_dim, dtype=np.float32))
+                    mask.append(0)
+
+            token_rows.append(np.stack(row, axis=0))
+            mask_rows.append(mask)
+            labels.append(sample.label)
+
+        return {
+            "outfit_tokens": torch.tensor(np.stack(token_rows), dtype=torch.float32),
+            "attention_mask": torch.tensor(np.asarray(mask_rows), dtype=torch.long),
+            "labels": torch.tensor(np.asarray(labels), dtype=torch.float32),
+        }
+
+
+def bpr_pairwise_loss(pos_logits: torch.Tensor, neg_logits: torch.Tensor) -> torch.Tensor:
+    return -F.logsigmoid(pos_logits - neg_logits).mean()
+
+
+def train_ranker(
+    train_jsonl: str | Path,
+    catalog_jsonl: str | Path,
+    output_checkpoint: str | Path,
+    encoder_model_id: str = "patrickjohncyh/fashion-clip",
+    epochs: int = 5,
+    batch_size: int = 16,
+    lr: float = 2e-4,
+    device: str | None = None,
+) -> None:
+    device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+    encoder = FashionItemEncoder(model_id=encoder_model_id, device=device)
+    dataset = OutfitRankingDataset(train_jsonl)
+    negative_sampler = NegativeSampler(_load_catalog(catalog_jsonl), encoder)
+    collator = OutfitRankerCollator(encoder)
+    model = OutfitCompatibilityRanker(d_model=encoder.embedding_dim).to(device)
+    optimizer = torch.optim.AdamW(model.parameters(), lr=lr, weight_decay=0.01)
+
+    for _epoch in range(epochs):
+        model.train()
+        augmented_samples = []
+        for sample in dataset.samples:
+            augmented_samples.append(sample)
+            augmented_samples.append(
+                TrainingSample(
+                    outfit=negative_sampler.sample(sample.outfit, sample.occasion),
+                    label=0.0,
+                    occasion=sample.occasion,
+                    weather=sample.weather,
+                    user_profile=sample.user_profile,
+                )
+            )
+
+        loader = DataLoader(
+            augmented_samples,
+            batch_size=batch_size,
+            shuffle=True,
+            collate_fn=collator,
+        )
+
+        for batch in loader:
+            logits = model(
+                batch["outfit_tokens"].to(device),
+                batch["attention_mask"].to(device),
+            ).squeeze(-1)
+            labels = batch["labels"].to(device)
+
+            bce_loss = F.binary_cross_entropy_with_logits(logits, labels)
+            pos_logits = logits[labels > 0.5]
+            neg_logits = logits[labels <= 0.5]
+            if len(pos_logits) > 0 and len(neg_logits) > 0:
+                limit = min(len(pos_logits), len(neg_logits))
+                pairwise = bpr_pairwise_loss(pos_logits[:limit], neg_logits[:limit])
+            else:
+                pairwise = torch.zeros((), device=device)
+
+            loss = bce_loss + 0.4 * pairwise
+            optimizer.zero_grad(set_to_none=True)
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
+            optimizer.step()
+
+    Path(output_checkpoint).parent.mkdir(parents=True, exist_ok=True)
+    torch.save(
+        {
+            "model_state_dict": model.state_dict(),
+            "encoder_model_id": encoder_model_id,
+            "embedding_dim": encoder.embedding_dim,
+        },
+        output_checkpoint,
+    )
+
+
+def _load_catalog(path: str | Path) -> list[dict[str, Any]]:
+    records = []
+    with open(path, "r", encoding="utf-8") as file_obj:
+        for line in file_obj:
+            line = line.strip()
+            if line:
+                records.append(json.loads(line))
+    return records

requirements.txt

@@ -0,0 +1,16 @@
+fastapi
+uvicorn[standard]
+python-multipart
+numpy
+pillow
+requests
+beautifulsoup4
+lxml
+playwright
+torch
+torchvision
+transformers
+accelerate
+gradio
+open_clip_torch
+apify-client

scoring.py

@@ -0,0 +1,553 @@
+"""
+scoring.py — strategic outfit scoring model.
+
+Replaces all scoring logic previously inline in app.py.
+Import compute_score() and recommend_outfits() from here.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Weights
+# ---------------------------------------------------------------------------
+
+WEIGHTS: dict[str, float] = {
+    "color":    0.30,
+    "style":    0.25,
+    "occasion": 0.20,
+    "fit":      0.13,
+    "pattern":  0.12,
+}
+
+TOP_K = 5
+
+
+# ---------------------------------------------------------------------------
+# Normalisation helpers
+# ---------------------------------------------------------------------------
+
+_BASE_COLORS = [
+    "black", "white", "grey", "gray", "beige", "cream", "tan",
+    "navy", "blue", "olive", "green", "brown", "maroon", "burgundy",
+    "red", "pink", "purple", "orange", "yellow", "gold", "silver",
+    "khaki", "coral", "teal", "indigo", "lavender", "mustard",
+]
+
+
+def _norm(value: Any) -> str:
+    return str(value or "").strip().lower()
+
+
+def extract_base_color(raw: Any) -> str:
+    """'Navy Blue' -> 'navy', 'Olive Green' -> 'olive', etc."""
+    n = _norm(raw)
+    for base in _BASE_COLORS:
+        if base in n:
+            return base
+    return n
+
+
+def extract_style(item: dict[str, Any]) -> str:
+    """Classifier writes 'occasion'; normaliser copies to 'style'. Accept both."""
+    raw = _norm(item.get("style") or item.get("occasion") or "")
+    if raw in {"work", "business", "office"}:
+        return "formal"
+    if raw in {"party", "festive", "ethnic"}:
+        return "party"
+    if raw in {"sports", "sport", "gym", "active"}:
+        return "sports"
+    if raw in {"casual", "formal", "streetwear", "party", "sports"}:
+        return raw
+    return "casual"   # safe default
+
+
+def extract_fit(item: dict[str, Any]) -> str:
+    n = _norm(item.get("fit") or "")
+    if "slim" in n or "fitted" in n:
+        return "slim"
+    if "over" in n or "baggy" in n or "loose" in n:
+        return "oversized"
+    if "regular" in n or "relaxed" in n:
+        return "regular"
+    return "regular"
+
+
+def extract_pattern(item: dict[str, Any]) -> str:
+    n = _norm(item.get("pattern") or "")
+    return "solid" if n in {"solid", "plain", ""} else "pattern"
+
+
+def extract_season(item: dict[str, Any]) -> str:
+    n = _norm(item.get("season") or "")
+    if "summer" in n:
+        return "summer"
+    if "winter" in n:
+        return "winter"
+    if "monsoon" in n or "rainy" in n:
+        return "monsoon"
+    return "all"   # "All-Season" or unknown -> no restriction
+
+
+def extract_fabric(item: dict[str, Any]) -> str:
+    return _norm(item.get("fabric") or "")
+
+
+# ---------------------------------------------------------------------------
+# Color scoring
+# ---------------------------------------------------------------------------
+
+_COMPLEMENTARY: set[frozenset] = {
+    frozenset(["blue",     "beige"]),
+    frozenset(["blue",     "khaki"]),
+    frozenset(["black",    "white"]),
+    frozenset(["navy",     "khaki"]),
+    frozenset(["navy",     "beige"]),
+    frozenset(["navy",     "white"]),
+    frozenset(["green",    "brown"]),
+    frozenset(["olive",    "tan"]),
+    frozenset(["olive",    "cream"]),
+    frozenset(["burgundy", "grey"]),
+    frozenset(["maroon",   "white"]),
+    frozenset(["grey",     "navy"]),
+    frozenset(["teal",     "white"]),
+    frozenset(["coral",    "navy"]),
+    frozenset(["black",    "beige"]),
+    frozenset(["black",    "khaki"]),
+    frozenset(["white",    "navy"]),
+    frozenset(["brown",    "cream"]),
+    frozenset(["mustard",  "navy"]),
+    frozenset(["mustard",  "black"]),
+}
+
+_NEUTRALS: set[str] = {
+    "black", "white", "grey", "gray", "beige",
+    "cream", "tan", "navy", "khaki",
+}
+
+_ANALOGOUS: set[frozenset] = {
+    frozenset(["blue",   "green"]),
+    frozenset(["blue",   "teal"]),
+    frozenset(["red",    "orange"]),
+    frozenset(["yellow", "orange"]),
+    frozenset(["red",    "maroon"]),
+    frozenset(["purple", "pink"]),
+    frozenset(["green",  "teal"]),
+    frozenset(["orange", "coral"]),
+}
+
+
+def _color_score(top: dict[str, Any], bottom: dict[str, Any]) -> int:
+    c1 = extract_base_color(top.get("color") or "")
+    c2 = extract_base_color(bottom.get("color") or "")
+    if not c1 or not c2:
+        return 60
+    pair = frozenset([c1, c2])
+    if pair in _COMPLEMENTARY:
+        return 90
+    if c1 in _NEUTRALS and c2 in _NEUTRALS:
+        return 50 if c1 == c2 else 82
+    if c1 in _NEUTRALS or c2 in _NEUTRALS:
+        return 80
+    if pair in _ANALOGOUS:
+        return 60
+    if c1 == c2:
+        return 45
+    return 60
+
+
+# ---------------------------------------------------------------------------
+# Style scoring
+# ---------------------------------------------------------------------------
+
+_STYLE_MATRIX: dict[tuple[str, str], int] = {
+    ("casual",     "casual"):     85,
+    ("formal",     "formal"):     90,
+    ("streetwear", "streetwear"): 88,
+    ("party",      "party"):      85,
+    ("sports",     "sports"):     88,
+    ("casual",     "streetwear"): 80,
+    ("streetwear", "casual"):     80,
+    ("casual",     "party"):      72,
+    ("party",      "casual"):     72,
+    ("casual",     "formal"):     62,
+    ("formal",     "casual"):     62,
+    ("formal",     "party"):      70,
+    ("party",      "formal"):     70,
+    ("formal",     "streetwear"): 48,
+    ("streetwear", "formal"):     48,
+    ("sports",     "casual"):     72,
+    ("casual",     "sports"):     72,
+    ("sports",     "formal"):     28,
+    ("formal",     "sports"):     28,
+    ("sports",     "party"):      40,
+    ("party",      "sports"):     40,
+}
+
+
+def _style_score(top: dict[str, Any], bottom: dict[str, Any]) -> int:
+    s1 = extract_style(top)
+    s2 = extract_style(bottom)
+    return _STYLE_MATRIX.get((s1, s2), 68)
+
+
+# ---------------------------------------------------------------------------
+# Occasion scoring
+# ---------------------------------------------------------------------------
+
+_STYLE_TO_OCCASIONS: dict[str, set[str]] = {
+    "casual":     {"casual", "everyday", "weekend", "college", "brunch"},
+    "formal":     {"formal", "work", "interview", "business", "office", "wedding", "meeting"},
+    "party":      {"party", "festive", "ethnic", "diwali", "celebration", "date"},
+    "sports":     {"sports", "gym", "active", "outdoor", "trekking"},
+    "streetwear": {"casual", "streetwear", "everyday", "college"},
+}
+
+
+def _occasion_score(occasion: str, top: dict[str, Any], bottom: dict[str, Any]) -> int:
+    occ = _norm(occasion)
+    if not occ:
+        return 70
+    t_occ = _STYLE_TO_OCCASIONS.get(extract_style(top), set())
+    b_occ = _STYLE_TO_OCCASIONS.get(extract_style(bottom), set())
+    top_fits    = occ in t_occ
+    bottom_fits = occ in b_occ
+    if top_fits and bottom_fits:
+        return 90
+    if top_fits or bottom_fits:
+        return 70
+    return 35
+
+
+# ---------------------------------------------------------------------------
+# Fit scoring
+# ---------------------------------------------------------------------------
+
+_FIT_MATRIX: dict[tuple[str, str], int] = {
+    ("slim",      "slim"):      82,
+    ("oversized", "slim"):      92,
+    ("slim",      "oversized"): 78,
+    ("oversized", "oversized"): 55,
+    ("regular",   "regular"):   80,
+    ("slim",      "regular"):   82,
+    ("regular",   "slim"):      82,
+    ("oversized", "regular"):   85,
+    ("regular",   "oversized"): 75,
+}
+
+
+def _fit_score(top: dict[str, Any], bottom: dict[str, Any]) -> int:
+    f1 = extract_fit(top)
+    f2 = extract_fit(bottom)
+    return _FIT_MATRIX.get((f1, f2), 70)
+
+
+# ---------------------------------------------------------------------------
+# Pattern scoring
+# ---------------------------------------------------------------------------
+
+def _pattern_score(top: dict[str, Any], bottom: dict[str, Any]) -> int:
+    p1 = extract_pattern(top)
+    p2 = extract_pattern(bottom)
+    if p1 == "pattern" and p2 == "pattern":
+        return 55
+    if p1 == "pattern" or p2 == "pattern":
+        return 88
+    return 75
+
+
+# ---------------------------------------------------------------------------
+# Season / fabric penalty
+# ---------------------------------------------------------------------------
+
+_HEAVY_FABRICS  = {"wool", "leather", "velvet", "tweed", "corduroy", "fleece"}
+_LIGHT_FABRICS  = {"linen", "cotton", "silk", "chiffon", "georgette"}
+_SUMMER_PENALTY = 18   # heavy fabric in summer
+_WINTER_PENALTY = 12   # very light fabric in winter
+
+
+def _season_penalty(top: dict[str, Any], bottom: dict[str, Any]) -> int:
+    """Returns a positive integer to subtract from the final score."""
+    penalty = 0
+    for item in (top, bottom):
+        season  = extract_season(item)
+        fabric  = extract_fabric(item)
+        if season == "summer" and any(f in fabric for f in _HEAVY_FABRICS):
+            penalty += _SUMMER_PENALTY
+        if season == "winter" and any(f in fabric for f in _LIGHT_FABRICS):
+            penalty += _WINTER_PENALTY
+    return penalty
+
+
+def _blend_breakdowns(primary: dict[str, int], extras: list[dict[str, int]]) -> dict[str, int]:
+    if not extras:
+        return dict(primary)
+
+    blended: dict[str, int] = {}
+    for key, value in primary.items():
+        extra_avg = sum(extra.get(key, value) for extra in extras) / len(extras)
+        blended[key] = round((value * 0.65) + (extra_avg * 0.35))
+    return blended
+
+
+def _other_item_label(other: dict[str, Any] | None) -> str:
+    if not other:
+        return "other item"
+    color = extract_base_color(other.get("color") or "") or _norm(other.get("color") or "") or "neutral"
+    category = str(other.get("category") or other.get("type") or "other item").strip() or "other item"
+    return f"{color} {category}".strip()
+
+
+# ---------------------------------------------------------------------------
+# Human-readable explanation
+# ---------------------------------------------------------------------------
+
+def build_reason(
+    breakdown: dict[str, int],
+    top: dict[str, Any],
+    bottom: dict[str, Any],
+    occasion: str,
+    season_pen: int,
+    other: dict[str, Any] | None = None,
+) -> str:
+    lines: list[str] = []
+
+    c = breakdown["color"]
+    c1 = extract_base_color(top.get("color") or "")
+    c2 = extract_base_color(bottom.get("color") or "")
+    if c >= 88:
+        lines.append(f"Great color contrast — {c1} and {c2} complement each other well.")
+    elif c >= 78:
+        lines.append(f"Clean color pairing — one neutral ({c1 if c1 in _NEUTRALS else c2}) anchors the look.")
+    elif c <= 60:
+        lines.append(f"Weak color pairing — {c1} and {c2} lack contrast or clash.")
+
+    s = breakdown["style"]
+    s1, s2 = extract_style(top), extract_style(bottom)
+    if s >= 85:
+        lines.append(f"Consistent style ({s1}).")
+    elif s <= 55:
+        lines.append(f"Style mismatch: {s1} top with {s2} bottom doesn't work for most occasions.")
+
+    o = breakdown["occasion"]
+    if occasion:
+        if o >= 88:
+            lines.append(f"Both pieces suit {occasion}.")
+        elif o >= 68:
+            lines.append(f"One piece suits {occasion}, the other is borderline.")
+        else:
+            lines.append(f"Neither piece is suited to {occasion}.")
+
+    f = breakdown["fit"]
+    f1, f2 = extract_fit(top), extract_fit(bottom)
+    if f >= 90:
+        lines.append(f"Excellent fit contrast — {f1} top with {f2} bottom is a strong silhouette.")
+    elif f <= 58:
+        lines.append(f"Both pieces are {f1} — too much volume in one direction.")
+
+    if season_pen > 0:
+        lines.append(f"Season/fabric mismatch reduced the score by {season_pen} pts.")
+
+    if other:
+        other_label = _other_item_label(other)
+        if breakdown["style"] >= 72 and breakdown["color"] >= 72:
+            lines.append(f"The {other_label} strengthens the finishing-layer/accessory coordination.")
+        else:
+            lines.append(f"The {other_label} was included in scoring, but it is not the strongest finishing piece here.")
+
+    return " ".join(lines) if lines else "Decent pairing overall."
+
+
+def build_tip(
+    score: int,
+    top: dict[str, Any],
+    bottom: dict[str, Any],
+    other: dict[str, Any] | None = None,
+) -> str:
+    if score >= 85:
+        if other:
+            return f"Strong outfit. Keep the {_other_item_label(other)} as the main finishing accent."
+        return "Solid outfit. Add a belt or watch to sharpen the look."
+    if score >= 70:
+        s1, s2 = extract_style(top), extract_style(bottom)
+        if s1 != s2:
+            return f"Swap the {s2} bottom for something more {s1} to improve cohesion."
+        c1 = extract_base_color(top.get("color") or "")
+        if c1 not in _NEUTRALS:
+            return "Add a neutral layer (jacket or shoes) to tie the colours together."
+        if other:
+            return f"If possible, swap the {_other_item_label(other)} for a cleaner neutral accent."
+        return "Try a different bottom colour for more visual interest."
+    return "This combination needs work — consider changing at least one piece."
+
+
+# ---------------------------------------------------------------------------
+# Main scoring entry point
+# ---------------------------------------------------------------------------
+
+def compute_score(
+    top: dict[str, Any],
+    bottom: dict[str, Any],
+    occasion: str = "casual",
+    other: dict[str, Any] | None = None,
+) -> tuple[int, dict[str, int]]:
+    """
+    Returns (final_score, breakdown_dict).
+    breakdown keys: color, style, occasion, fit, pattern
+
+    Veto caps:
+      - color  <= 50  → final capped at 68  (monochrome / clash)
+      - style  <= 48  → final capped at 58  (hard style mismatch)
+      - pattern == 55 (both patterned) AND color <= 80 → cap at 72
+    """
+    raw_scores: dict[str, int] = {
+        "color":    _color_score(top, bottom),
+        "style":    _style_score(top, bottom),
+        "occasion": _occasion_score(occasion, top, bottom),
+        "fit":      _fit_score(top, bottom),
+        "pattern":  _pattern_score(top, bottom),
+    }
+
+    extra_penalty = 0
+    if other:
+        raw_scores = _blend_breakdowns(
+            raw_scores,
+            [
+                {
+                    "color": _color_score(top, other),
+                    "style": _style_score(top, other),
+                    "occasion": _occasion_score(occasion, top, other),
+                    "fit": _fit_score(top, other),
+                    "pattern": _pattern_score(top, other),
+                },
+                {
+                    "color": _color_score(bottom, other),
+                    "style": _style_score(bottom, other),
+                    "occasion": _occasion_score(occasion, bottom, other),
+                    "fit": _fit_score(bottom, other),
+                    "pattern": _pattern_score(bottom, other),
+                },
+            ],
+        )
+        extra_penalty = round(
+            (_season_penalty(top, other) + _season_penalty(bottom, other)) / 2
+        )
+
+    weighted = sum(raw_scores[k] * WEIGHTS[k] for k in WEIGHTS)
+    penalty  = (
+        round((_season_penalty(top, bottom) * 0.65) + (extra_penalty * 0.35))
+        if other
+        else _season_penalty(top, bottom)
+    )
+    final    = max(0, min(100, round(weighted - penalty)))
+
+    # Veto caps — a fatal flaw in one dimension overrides a good weighted average
+    if raw_scores["color"] <= 50:
+        final = min(final, 68)
+    if raw_scores["style"] <= 48:
+        final = min(final, 58)
+    if raw_scores["pattern"] == 55 and raw_scores["color"] <= 80:
+        final = min(final, 72)
+
+    return final, raw_scores
+
+
+def score_pair_full(
+    top: dict[str, Any],
+    bottom: dict[str, Any],
+    occasion: str = "casual",
+    other: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Returns the full scoring dict that all endpoints expect:
+    score, breakdown, reason, tip, engine_version
+    """
+    score, breakdown = compute_score(top, bottom, occasion, other=other)
+    penalty = _season_penalty(top, bottom)
+    if other:
+        other_penalty = round(
+            (_season_penalty(top, other) + _season_penalty(bottom, other)) / 2
+        )
+        penalty = round((penalty * 0.65) + (other_penalty * 0.35))
+    return {
+        "score":          score,
+        "breakdown":      breakdown,
+        "reason":         build_reason(breakdown, top, bottom, occasion, penalty, other=other),
+        "tip":            build_tip(score, top, bottom, other=other),
+        "engine_version": "scoring-v2",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Diversity penalty (non-mutating)
+# ---------------------------------------------------------------------------
+
+def _is_similar(a: dict[str, Any], b: dict[str, Any]) -> bool:
+    return (
+        extract_base_color(a["top"].get("color") or "")
+        == extract_base_color(b["top"].get("color") or "")
+        and extract_base_color(a["bottom"].get("color") or "")
+        == extract_base_color(b["bottom"].get("color") or "")
+        and extract_base_color((a.get("other") or {}).get("color") or "")
+        == extract_base_color((b.get("other") or {}).get("color") or "")
+    )
+
+
+def _apply_diversity_penalty(pairs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    result: list[dict[str, Any]] = []
+    for pair in pairs:
+        penalty = sum(10 for sel in result if _is_similar(pair, sel))
+        adjusted = copy.copy(pair)
+        adjusted["score"] = max(0, pair["score"] - penalty)
+        result.append(adjusted)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Recommender
+# ---------------------------------------------------------------------------
+
+def recommend_outfits(
+    tops: list[dict[str, Any]],
+    bottoms: list[dict[str, Any]],
+    occasion: str = "casual",
+    others: list[dict[str, Any]] | None = None,
+    locked_top: dict[str, Any] | None = None,
+    locked_bottom: dict[str, Any] | None = None,
+    locked_other: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    """
+    Returns up to TOP_K scored pairs, sorted best-first.
+    Each entry: {top, bottom, score, breakdown, reason, tip}
+    """
+    other_options = [locked_other] if locked_other else ([None] + list(others or []))
+
+    if locked_top and locked_bottom:
+        candidates = [(locked_top, locked_bottom, other) for other in other_options]
+    elif locked_top:
+        candidates = [(locked_top, b, other) for b in bottoms for other in other_options]
+    elif locked_bottom:
+        candidates = [(t, locked_bottom, other) for t in tops for other in other_options]
+    else:
+        candidates = [(t, b, other) for t in tops for b in bottoms for other in other_options]
+
+    scored: list[dict[str, Any]] = []
+    for top, bottom, other in candidates:
+        result = score_pair_full(top, bottom, occasion, other=other)
+        scored.append({
+            "top":       top,
+            "bottom":    bottom,
+            "other":     other,
+            "score":     result["score"],
+            "breakdown": result["breakdown"],
+            "reason":    result["reason"],
+            "tip":       result["tip"],
+        })
+
+    scored.sort(key=lambda x: x["score"], reverse=True)
+    scored = _apply_diversity_penalty(scored)
+    scored.sort(key=lambda x: x["score"], reverse=True)
+    return scored[:TOP_K]

scraped_json/product_urls_20260413T214331Z.json

@@ -0,0 +1,174 @@
+{
+  "product_urls": [
+    "https://www.nike.com/t/sportswear-club-mens-fleece-hoodie-cjm38J/HV1216-893",
+    "https://www.nike.com/t/247-impossiblysoft-mens-dri-fit-1-2-zip-top-s9Hx9b/HQ6953-010",
+    "https://www.nike.com/t/caitlin-clark-basketball-fleece-pullover-hoodie-tRRBDb6P/IQ5572-133",
+    "https://www.nike.com/t/club-mens-pullover-fleece-hoodie-00eeWNwD/FN3859-010",
+    "https://www.nike.com/t/club-mens-fleece-crew-RU1Il4yl/FN3886-010",
+    "https://www.nike.com/t/sportswear-club-fleece-pullover-hoodie-Gw4Nwq/BV2654-010",
+    "https://www.nike.com/t/sportswear-club-fleece-mens-full-zip-hoodie-nR8tst/BV2645-010",
+    "https://www.nike.com/t/club-fleece-mens-football-pullover-hoodie-wklPOsTs/M31233FB25-BLK",
+    "https://www.nike.com/t/therma-mens-therma-fit-hooded-fitness-pullover-X9fVm2/DQ4834-010",
+    "https://www.nike.com/t/solo-swoosh-mens-pullover-hoodie-bDPPFV/HV1082-010",
+    "https://www.nike.com/t/tech-mens-fleece-pullover-hoodie-2eYhFKJ7/IO9941-010",
+    "https://www.nike.com/t/club-fleece-mens-baseball-pullover-hoodie-gvB0EgFc/M31233BS25-ANT",
+    "https://www.nike.com/t/standard-issue-mens-therma-fit-brushed-basketball-pullover-hoodie-88aWq9IL/IM5918-010",
+    "https://www.nike.com/t/acg-tuff-fleece-pullover-hoodie-njCV8f/DZ3392-011",
+    "https://www.nike.com/t/tech-mens-fleece-windrunner-full-zip-jacket-HqUykgjE/HV0949-010",
+    "https://www.nike.com/t/mens-therma-fit-fleece-hoodie-nMuSUUk1/HV4062-010",
+    "https://www.nike.com/t/therma-mens-therma-fit-full-zip-fitness-top-vsR4Rm/DQ4830-010",
+    "https://www.nike.com/t/jordan-brooklyn-mens-oversized-pullover-hoodie-kkkKymFl/IM7943-010",
+    "https://www.nike.com/t/nocta-fleece-cs-hoodie-2-5DG03b/HM5762-010",
+    "https://www.nike.com/t/nikecourt-heritage-mens-dri-fit-french-terry-tennis-pullover-hoodie-Y9kjc6iO/HM6759-010",
+    "https://www.nike.com/t/jordan-brooklyn-fleece-mens-crew-neck-sweatshirt-X93KLz/FV7293-010",
+    "https://www.nike.com/t/jordan-brooklyn-mens-hike-mike-full-zip-hoodie-11ir96Q1/IF1887-010",
+    "https://www.nike.com/t/jordan-sport-crossover-mens-fleece-pullover-hoodie-VXzVnjEL/HQ8694-010",
+    "https://www.nike.com/t/primary-fleece-mens-dri-fit-uv-pullover-performance-hoodie-B10qz3/FZ0969-010"
+  ],
+  "products": [
+    {
+      "item_link": "https://www.nike.com/t/sportswear-club-mens-fleece-hoodie-cjm38J/HV1216-893",
+      "name": "Nike Sportswear Club Men's Fleece Hoodie",
+      "price": "$54.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/92557b1d-2396-4844-aac2-bdb1b09962ef/M+NK+CLUB+BB+HDY+RUN+REISSUE.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/247-impossiblysoft-mens-dri-fit-1-2-zip-top-s9Hx9b/HQ6953-010",
+      "name": "Nike 24.7 ImpossiblySoft Men's Dri-FIT 1/2-Zip Top",
+      "price": "$125.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/692f9518-fc3b-4270-8f4a-d072e74ca17e/M+NK+DF+24.7+IS+HZ.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/caitlin-clark-basketball-fleece-pullover-hoodie-tRRBDb6P/IQ5572-133",
+      "name": "Caitlin Clark Nike Basketball Fleece Pullover Hoodie",
+      "price": "$80.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/a0b5441e-9126-49f4-9210-6f00b25cd673/CC+U+NK+FLC+PO+HOODIE+PREM.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/club-mens-pullover-fleece-hoodie-00eeWNwD/FN3859-010",
+      "name": "Nike Club Men's Pullover Fleece Hoodie",
+      "price": "$70.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/058ea263-4c74-41f8-b9dc-83a9e03fa569/M+NK+CLUB+BB+PO+HOODIE.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/club-mens-fleece-crew-RU1Il4yl/FN3886-010",
+      "name": "Nike Club Men's Fleece Crew",
+      "price": "$60.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/2bc7f3c9-8dbe-4016-8705-0ebfd5695b51/M+NK+CLUB+BB+CREW.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/sportswear-club-fleece-pullover-hoodie-Gw4Nwq/BV2654-010",
+      "name": "Nike Sportswear Club Fleece Pullover Hoodie",
+      "price": "$65.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/136c17a4-16c0-47ce-b922-679098771a7d/M+NSW+CLUB+HOODIE+PO+BB.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/sportswear-club-fleece-mens-full-zip-hoodie-nR8tst/BV2645-010",
+      "name": "Nike Sportswear Club Fleece Men's Full-Zip Hoodie",
+      "price": "$70.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/0133bce8-1d47-45f0-98af-bffd2738641b/M+NSW+CLUB+HOODIE+FZ+BB.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/club-fleece-mens-football-pullover-hoodie-wklPOsTs/M31233FB25-BLK",
+      "name": "Nike Club Fleece Men's Football Pullover Hoodie",
+      "price": "$48.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/7da73ac3-1373-4ce6-a60f-94931a5feb1b/FA25+SWH+SPT+FB+CLUB+FLC+POH.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/therma-mens-therma-fit-hooded-fitness-pullover-X9fVm2/DQ4834-010",
+      "name": "Nike Therma Men's Therma-FIT Hooded Fitness Pullover",
+      "price": "$47.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/5d0316e2-55c8-45fe-a164-c1c59575679b/M+NK+TF+HD+PO.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/solo-swoosh-mens-pullover-hoodie-bDPPFV/HV1082-010",
+      "name": "Nike Solo Swoosh Men's Pullover Hoodie",
+      "price": "$90.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/b222e3d0-d44a-488e-9723-519d1526ae54/M+NL+SOLO+SWSH+BB+PO+HOODIE.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/tech-mens-fleece-pullover-hoodie-2eYhFKJ7/IO9941-010",
+      "name": "Nike Tech Men's Fleece Pullover Hoodie",
+      "price": "$145.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/14e6e662-674d-41f7-a28d-41ff10580723/M+NK+TCH+ERGO+PO+HOODIE.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/club-fleece-mens-baseball-pullover-hoodie-gvB0EgFc/M31233BS25-ANT",
+      "name": "Nike Club Fleece Men's Baseball Pullover Hoodie",
+      "price": "$52.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/535f8f32-b453-4d4e-9b96-d316f628cca7/FA25+SWH+SPT+BSBL+CLUB+FLC+POH.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/standard-issue-mens-therma-fit-brushed-basketball-pullover-hoodie-88aWq9IL/IM5918-010",
+      "name": "Nike Standard Issue Men's Therma-FIT Brushed Basketball Pullover Hoodie",
+      "price": "$59.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/d26703fe-117e-438b-8174-4e7d69a71aa9/M+NK+TF+SI+BRSH+PO+HD.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/acg-tuff-fleece-pullover-hoodie-njCV8f/DZ3392-011",
+      "name": "Nike ACG \"Tuff Fleece\" Pullover Hoodie",
+      "price": "$115.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/0cc08282-0c99-4e7d-a714-c6541eab9204/U+ACG+TUFF+FLC+HOODIE+PO.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/tech-mens-fleece-windrunner-full-zip-jacket-HqUykgjE/HV0949-010",
+      "name": "Nike Tech Men's Fleece Windrunner Full-Zip Jacket",
+      "price": "$140.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/58bf6658-12e4-4407-8427-b6f9f5c5e20f/M+NK+TCH+FLC+FZ+WR+HOODIE.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/mens-therma-fit-fleece-hoodie-nMuSUUk1/HV4062-010",
+      "name": "Nike Men's Therma-FIT Fleece Hoodie",
+      "price": "$54.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/34bc662d-f272-4cd5-a738-bc718228947d/M+NK+TF+FLEECE+PO+HD+GFX.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/therma-mens-therma-fit-full-zip-fitness-top-vsR4Rm/DQ4830-010",
+      "name": "Nike Therma Men's Therma-FIT Full-Zip Fitness Top",
+      "price": "$75.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/b75e28b1-1acd-4756-bb8a-c3af777a080e/M+NK+TF+HD+FZ.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/jordan-brooklyn-mens-oversized-pullover-hoodie-kkkKymFl/IM7943-010",
+      "name": "Jordan Brooklyn Men's Oversized Pullover Hoodie",
+      "price": "$75.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_126ab356-44d8-4a06-89b4-fcdcc8df0245,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/dbd2c4e6-3aea-41a0-926e-5e75e7e80664/M+J+BRK+OVS+PO+HD+CLD.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/nocta-fleece-cs-hoodie-2-5DG03b/HM5762-010",
+      "name": "NOCTA Fleece CS Hoodie 2",
+      "price": "$120.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/f7e7b317-22c1-4c77-9231-73086563141f/M+NRG+CS+NOCTA+HOODIE+FLC+2.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/nikecourt-heritage-mens-dri-fit-french-terry-tennis-pullover-hoodie-Y9kjc6iO/HM6759-010",
+      "name": "NikeCourt Heritage Men's Dri-FIT French Terry Tennis Pullover Hoodie",
+      "price": "$100.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_9ddf04c7-2a9a-4d76-add1-d15af8f0263d,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/4bc4896e-fbec-4be9-b2ec-8f7c19bfc6e5/M+NKCT+DF+HRTGE+FLC+PO+HD.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/jordan-brooklyn-fleece-mens-crew-neck-sweatshirt-X93KLz/FV7293-010",
+      "name": "Jordan Brooklyn Fleece Men's Crew-Neck Sweatshirt",
+      "price": "$60.00",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_126ab356-44d8-4a06-89b4-fcdcc8df0245,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/79b185ef-79d4-463c-b12b-92a1b355c1be/M+J+BRK+FLC+CREW.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/jordan-brooklyn-mens-hike-mike-full-zip-hoodie-11ir96Q1/IF1887-010",
+      "name": "Jordan Brooklyn Men's Hike Mike Full-Zip Hoodie",
+      "price": "$60.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_126ab356-44d8-4a06-89b4-fcdcc8df0245,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/8c8e63b0-1530-4c4e-94d0-be7d27f982b0/M+J+BRK+HIKE+MIKE+ZIP+HD.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/jordan-sport-crossover-mens-fleece-pullover-hoodie-VXzVnjEL/HQ8694-010",
+      "name": "Jordan Sport Crossover Men's Fleece Pullover Hoodie",
+      "price": "$50.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/u_126ab356-44d8-4a06-89b4-fcdcc8df0245,c_scale,fl_relative,w_1.0,h_1.0,fl_layer_apply/27619f5d-c9c4-4f07-96b2-fa7ca6274663/M+J+SPRT+CSVR+GFX+FLC+PO.png"
+    },
+    {
+      "item_link": "https://www.nike.com/t/primary-fleece-mens-dri-fit-uv-pullover-performance-hoodie-B10qz3/FZ0969-010",
+      "name": "Nike Primary Fleece Men's Dri-FIT UV Pullover Performance Hoodie",
+      "price": "$55.97",
+      "image_url": "https://static.nike.com/a/images/t_web_pw_592_v2/f_auto/9bff5b2c-7b9c-4a22-9d63-eaca3808c540/M+NK+DF+UV+PRIMARY+PO+HOODIE.png"
+    }
+  ]
+}

scraper.py

@@ -0,0 +1,512 @@
+from __future__ import annotations
+
+from io import StringIO
+import csv
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import requests
+from bs4 import BeautifulSoup
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+from urllib.parse import urlencode
+
+
+app = FastAPI(title="Nike Scraper API", version="1.0.0")
+
+NIKE_BASE_SEARCH = "https://www.nike.com/w"
+NIKE_BASE_URL = "https://www.nike.com"
+
+CATEGORY_ALIASES = {
+    "t-shirt": "t-shirt",
+    "tee": "t-shirt",
+    "shirt": "shirt",
+    "hoodie": "hoodie",
+    "sweatshirt": "sweatshirt",
+    "jacket": "jacket",
+    "gilet": "gilet",
+    "top": "top",
+    "tank": "tank top",
+    "polo": "polo",
+    "jersey": "jersey",
+    "bra": "sports bra",
+    "pant": "pants",
+    "pants": "pants",
+    "trousers": "trousers",
+    "shorts": "shorts",
+    "short": "shorts",
+    "leggings": "leggings",
+    "tights": "tights",
+    "joggers": "joggers",
+    "sweatpants": "sweatpants",
+    "skirt": "skirt",
+    "dress": "dress",
+    "tracksuit": "tracksuit",
+    "jumpsuit": "jumpsuit",
+    "socks": "socks",
+    "sock": "socks",
+    "hat": "hat",
+    "cap": "cap",
+    "bag": "bag",
+    "backpack": "backpack",
+}
+
+HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/123.0.0.0 Safari/537.36"
+    )
+}
+
+CATEGORIES = [
+    "sweaters",
+    "hoodies",
+    "t-shirts",
+    "jackets",
+    "shirts",
+    "crews",
+    "jerseys",
+    "tops",
+    "polos",
+    "tanks",
+    "compression",
+    "baselayer",
+    "jeans",
+    "shorts",
+    "skirts",
+    "tights",
+    "parkas",
+    "gilets",
+    "pants",
+    "leggings",
+    "trousers",
+    "joggers",
+    "sweatpants",
+    "dresses",
+    "rompers",
+    "jumpsuits",
+    "onesies",
+    "overalls",
+    "tracksuits",
+    "sneakers",
+    "slippers",
+    "sunglasses",
+    "bras",
+    "socks",
+    "hats",
+    "bags",
+    "backpacks",
+]
+
+SCRAPE_OUTPUT_DIR = Path(__file__).resolve().parent / "scraped_json"
+
+
+class Recommendation(BaseModel):
+    color: str = Field(..., min_length=1)
+    category: str = Field(..., min_length=1)
+    gender: Optional[str] = Field(default=None, description="men or women")
+
+
+class ScrapeRequest(BaseModel):
+    recommendation: Recommendation
+    max_products: int = Field(default=30, ge=1, le=300)
+
+
+def _ensure_full_url(href: str) -> str:
+    if href.startswith("/"):
+        return f"{NIKE_BASE_URL}{href}"
+    return href
+
+
+def build_nike_search_url(color: str, category: str, gender: Optional[str] = None) -> str:
+    category_normalized = CATEGORY_ALIASES.get(category.lower(), category.lower())
+    parts: list[str] = []
+    if gender:
+        parts.append(gender.lower() + "s")
+    parts.append(color.lower())
+    parts.append(category_normalized)
+    query = " ".join(parts)
+    params = urlencode({"q": query, "vst": query})
+    return f"{NIKE_BASE_SEARCH}?{params}"
+
+
+def build_nike_urls_from_recommendation(recommendation: Recommendation) -> list[str]:
+    color = recommendation.color
+    category = recommendation.category
+    gender = recommendation.gender
+    if gender:
+        return [build_nike_search_url(color, category, gender)]
+    return [
+        build_nike_search_url(color, category, "men"),
+        build_nike_search_url(color, category, "women"),
+        build_nike_search_url(color, category),
+    ]
+
+
+def build_search_urls_from_recommendation(recommendation: Recommendation, store: str = "nike") -> list[str]:
+    return build_nike_urls_from_recommendation(recommendation)
+
+
+def build_search_urls_from_query(query: str, store: str = "nike", gender: Optional[str] = None) -> list[str]:
+    normalized_query = str(query or "").strip()
+    if not normalized_query:
+        return []
+
+    def _normalize_prefixed_query(prefix: str, value: str) -> str:
+        lowered = value.strip().lower()
+        p = prefix.strip().lower()
+        if lowered.startswith(f"{p} "):
+            return value.strip()
+        return f"{prefix} {value}".strip()
+
+    if gender:
+        q = _normalize_prefixed_query(gender, normalized_query)
+        return [f"{NIKE_BASE_SEARCH}?{urlencode({'q': q, 'vst': q})}"]
+
+    return [
+        f"{NIKE_BASE_SEARCH}?{urlencode({'q': f'men {normalized_query}'.strip(), 'vst': f'men {normalized_query}'.strip()})}",
+        f"{NIKE_BASE_SEARCH}?{urlencode({'q': f'women {normalized_query}'.strip(), 'vst': f'women {normalized_query}'.strip()})}",
+        f"{NIKE_BASE_SEARCH}?{urlencode({'q': normalized_query, 'vst': normalized_query})}",
+    ]
+
+
+def _get_soup(url: str) -> BeautifulSoup:
+    response = requests.get(url, headers=HEADERS, timeout=20)
+    response.raise_for_status()
+    return BeautifulSoup(response.content, "lxml")
+
+
+def _ensure_store_url(href: str, base_url: str) -> str:
+    if not href:
+        return ""
+    if href.startswith("//"):
+        return f"https:{href}"
+    if href.startswith("/"):
+        return f"{base_url}{href}"
+    return href
+
+
+def extract_product_urls(search_url: str) -> list[str]:
+    soup = _get_soup(search_url)
+    product_links: list[str] = []
+
+    anchors = soup.find_all("a", {"class": "product-card__link-overlay"})
+    for anchor in anchors:
+        href = anchor.get("href")
+        if href:
+            full = _ensure_full_url(href)
+            if full not in product_links:
+                product_links.append(full)
+
+    if not product_links:
+        all_anchors = soup.find_all("a", href=True)
+        for anchor in all_anchors:
+            href = anchor.get("href")
+            if href and "/t/" in href:
+                full = _ensure_full_url(href)
+                if full not in product_links:
+                    product_links.append(full)
+
+    return product_links
+
+
+def _extract_image_from_container(container: BeautifulSoup) -> str:
+    img = container.find("img")
+    if not img:
+        return ""
+    return str(img.get("src") or img.get("data-src") or img.get("srcset") or "").strip()
+
+
+def extract_product_summaries(search_url: str, store: str = "nike") -> list[dict[str, str]]:
+    soup = _get_soup(search_url)
+    summaries: list[dict[str, str]] = []
+    seen_links: set[str] = set()
+
+    containers = soup.find_all("div", {"class": "product-card__body"})
+    for container in containers:
+        anchor = container.find("a", {"class": "product-card__link-overlay"})
+        if not anchor:
+            continue
+
+        href = anchor.get("href")
+        if not href:
+            continue
+
+        item_link = _ensure_full_url(href)
+        if item_link in seen_links:
+            continue
+        seen_links.add(item_link)
+
+        title = get_title(container)
+        current_price, _ = get_prices(container)
+        image_url = _extract_image_from_container(container.parent if container.parent else container)
+
+        summaries.append(
+            {
+                "item_link": item_link,
+                "name": title,
+                "price": current_price,
+                "image_url": image_url,
+            }
+        )
+
+    if summaries:
+        return summaries
+
+    # Fallback path when Nike card markup changes.
+    for item_link in extract_product_urls(search_url):
+        if item_link in seen_links:
+            continue
+        seen_links.add(item_link)
+        summaries.append(
+            {
+                "item_link": item_link,
+                "name": "N/A",
+                "price": "N/A",
+                "image_url": "",
+            }
+        )
+    return summaries
+
+
+def get_title(container: BeautifulSoup) -> str:
+    try:
+        title = container.find_all("div", {"class": "product-card__title"})[0].text
+        subtitle = container.find_all("div", {"class": "product-card__subtitle"})[0].text
+        return f"{title} {subtitle}".strip()
+    except (IndexError, AttributeError):
+        return "N/A"
+
+
+def get_target_gender(title: str) -> str:
+    if "Men's" in title:
+        return "Men"
+    if "Women's" in title:
+        return "Women"
+    return "Unisex"
+
+
+def get_subcategory(title: str) -> str:
+    for word in title.split(" "):
+        candidate = word.lower().strip(",.")
+        if candidate in CATEGORIES or (candidate + "s") in CATEGORIES:
+            return word
+    return ""
+
+
+def get_prices(container: BeautifulSoup) -> tuple[str, str]:
+    try:
+        price_container = container.find_all("div", {"class": "product-price__wrapper"})
+        current_price = price_container[0].text
+        old_price = "N/A"
+
+        if current_price.count("$") == 2:
+            prices = current_price.split("$")
+            current_price = "$" + prices[1] if "." in prices[1] else "$" + prices[1] + ".00"
+            old_price = "$" + prices[2] if "." in prices[2] else "$" + prices[2] + ".00"
+        elif "." not in current_price:
+            current_price = current_price + ".00"
+    except (IndexError, AttributeError):
+        current_price, old_price = "N/A", "N/A"
+
+    return current_price, old_price
+
+
+def get_item_image_link(item_soup: BeautifulSoup) -> str:
+    try:
+        img = item_soup.find("img", {"class": "css-viwop1 u-full-width u-full-height css-m5dkrx"})
+        return img.get("src") if img else "Click on item link for pictures."
+    except (IndexError, AttributeError):
+        return "Click on item link for pictures."
+
+
+def get_colors(item_soup: BeautifulSoup) -> str:
+    try:
+        current = item_soup.find_all(
+            "div",
+            {
+                "class": "colorway-product-overlay colorway-product-overlay--active "
+                "colorway-product-overlay--selected css-sa2cc9"
+            },
+        )
+        if current:
+            colors = current[0].find_all("img", alt=True)[0].get("alt")
+            for color in item_soup.find_all("div", {"class": "colorway-product-overlay css-sa2cc9"}):
+                alt = color.find_all("img", alt=True)[0].get("alt")
+                if alt != "Design your own Nike By You product":
+                    colors += " || " + alt
+        else:
+            color_li = item_soup.find_all("li", {"class": "description-preview__color-description ncss-li"})
+            colors = str(color_li).split(": ")[1].replace("</li>]", "")
+    except (IndexError, AttributeError):
+        colors = "Click on item link for available colors."
+    return colors
+
+
+def scrape_products(search_urls: list[str], max_products: int) -> list[dict[str, str]]:
+    items: list[dict[str, str]] = []
+    seen_links: set[str] = set()
+
+    for link in search_urls:
+        soup = _get_soup(link)
+        containers = soup.find_all("div", {"class": "product-card__body"})
+
+        for container in containers:
+            if len(items) >= max_products:
+                return items
+
+            anchor = container.find("a", {"class": "product-card__link-overlay"})
+            if not anchor:
+                continue
+            href = anchor.get("href")
+            if not href:
+                continue
+
+            item_link = _ensure_full_url(href)
+            if item_link in seen_links:
+                continue
+            seen_links.add(item_link)
+
+            title = get_title(container)
+            gender = get_target_gender(title)
+            current_price, old_price = get_prices(container)
+            subcategory = get_subcategory(title)
+
+            image_link = "Click on item link for pictures."
+            colors = "Click on item link for available colors."
+            try:
+                item_soup = _get_soup(item_link)
+                image_link = get_item_image_link(item_soup)
+                colors = get_colors(item_soup)
+            except requests.RequestException:
+                pass
+
+            items.append(
+                {
+                    "name": title,
+                    "gender": gender,
+                    "price": current_price,
+                    "sale_price": old_price,
+                    "colors": colors,
+                    "item_link": item_link,
+                    "image_link": image_link,
+                    "subcategory": subcategory,
+                    "brand": "Nike",
+                }
+            )
+
+    return items
+
+
+def _build_csv(products: list[dict[str, str]]) -> str:
+    output = StringIO()
+    writer = csv.DictWriter(
+        output,
+        fieldnames=[
+            "name",
+            "gender",
+            "price",
+            "sale_price",
+            "colors",
+            "item_link",
+            "image_link",
+            "subcategory",
+            "brand",
+        ],
+    )
+    writer.writeheader()
+    writer.writerows(products)
+    return output.getvalue()
+
+
+def _save_json_payload(prefix: str, payload: dict[str, object]) -> str:
+    SCRAPE_OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    filename = f"{prefix}_{ts}.json"
+    file_path = SCRAPE_OUTPUT_DIR / filename
+    with file_path.open("w", encoding="utf-8") as f:
+        json.dump(payload, f, ensure_ascii=True, indent=2)
+    return str(file_path)
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/")
+def root() -> dict[str, str]:
+    return {
+        "message": "Nike Scraper API is running.",
+        "docs": "/docs",
+        "health": "/health",
+    }
+
+
+@app.post("/search-urls")
+def search_urls(payload: Recommendation) -> dict[str, list[str]]:
+    return {"search_urls": build_nike_urls_from_recommendation(payload)}
+
+
+@app.post("/product-urls")
+def product_urls(payload: Recommendation) -> dict[str, object]:
+    try:
+        urls = build_nike_urls_from_recommendation(payload)
+        all_products: list[dict[str, str]] = []
+        seen_links: set[str] = set()
+        for url in urls:
+            for product in extract_product_summaries(url):
+                link = product.get("item_link", "")
+                if not link or link in seen_links:
+                    continue
+                seen_links.add(link)
+                all_products.append(product)
+
+        response_payload: dict[str, object] = {
+            "product_urls": [item["item_link"] for item in all_products],
+            "products": all_products,
+        }
+        response_payload["saved_json_path"] = _save_json_payload("product_urls", response_payload)
+        return response_payload
+    except requests.RequestException as exc:
+        raise HTTPException(status_code=502, detail=f"Failed to fetch Nike pages: {exc}") from exc
+
+
+@app.post("/scrape")
+def scrape(payload: ScrapeRequest) -> dict[str, object]:
+    try:
+        search_urls = build_nike_urls_from_recommendation(payload.recommendation)
+        products = scrape_products(search_urls, max_products=payload.max_products)
+    except requests.RequestException as exc:
+        raise HTTPException(status_code=502, detail=f"Failed to fetch Nike pages: {exc}") from exc
+
+    response_payload: dict[str, object] = {
+        "search_urls": search_urls,
+        "count": len(products),
+        "products": products,
+    }
+    return response_payload
+
+
+@app.post("/scrape.csv")
+def scrape_csv(payload: ScrapeRequest) -> StreamingResponse:
+    try:
+        search_urls = build_nike_urls_from_recommendation(payload.recommendation)
+        products = scrape_products(search_urls, max_products=payload.max_products)
+    except requests.RequestException as exc:
+        raise HTTPException(status_code=502, detail=f"Failed to fetch Nike pages: {exc}") from exc
+
+    csv_content = _build_csv(products)
+    filename = (
+        f"nike_{payload.recommendation.gender or 'unisex'}_"
+        f"{payload.recommendation.color}_{payload.recommendation.category}.csv"
+    )
+    return StreamingResponse(
+        iter([csv_content]),
+        media_type="text/csv",
+        headers={"Content-Disposition": f"attachment; filename={filename}"},
+    )

zalando_scraper.py

@@ -0,0 +1,1073 @@
+from __future__ import annotations
+
+import logging
+import json
+import os
+import re
+from typing import Any, Callable, Optional
+from urllib.parse import urlencode, urlparse
+
+import requests
+from bs4 import BeautifulSoup
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None or str(raw).strip() == "":
+        return default
+    try:
+        return int(str(raw).strip())
+    except (TypeError, ValueError):
+        return default
+
+
+ZALANDO_BASE_URL = "https://www.zalando.co.uk"
+APIFY_ACTOR_ENDPOINT = os.getenv(
+    "APIFY_ACTOR_ENDPOINT",
+    "https://api.apify.com/v2/acts/vistics~zalando-scraper/run-sync-get-dataset-items",
+)
+APIFY_TOKEN = os.getenv("APIFY_API_TOKEN", "").strip()
+APIFY_MAX_RESULTS = 20
+APIFY_MIN_TIMEOUT_SECONDS = max(60, _env_int("APIFY_MIN_TIMEOUT_SECONDS", 180))
+APIFY_WAIT_FOR_FINISH_SECONDS = max(60, _env_int("APIFY_WAIT_FOR_FINISH_SECONDS", 300))
+HTML_FALLBACK_TIMEOUT_SECONDS = max(20, _env_int("ZALANDO_HTML_TIMEOUT_SECONDS", 45))
+
+REQUEST_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/124.0.0.0 Safari/537.36"
+    )
+}
+
+if not logging.getLogger().handlers:
+    logging.basicConfig(
+        level=os.getenv("LOG_LEVEL", "INFO").upper(),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+logger = logging.getLogger(__name__)
+logger.setLevel(getattr(logging, os.getenv("LOG_LEVEL", "INFO").upper(), logging.INFO))
+
+CATEGORY_PATH_MAP = {
+    "topwear": {"women": "womens-clothing", "men": "mens-clothing", "unisex": "clothing"},
+    "bottomwear": {"women": "womens-clothing", "men": "mens-clothing", "unisex": "clothing"},
+    "layers": {"women": "womens-clothing", "men": "mens-clothing", "unisex": "clothing"},
+    "dress": {"women": "womens-clothing-dresses", "men": "mens-clothing", "unisex": "clothing"},
+    "dresses": {"women": "womens-clothing-dresses", "men": "mens-clothing", "unisex": "clothing"},
+    "shoes": {"women": "womens-shoes", "men": "mens-shoes", "unisex": "shoes"},
+    "footwear": {"women": "womens-shoes", "men": "mens-shoes", "unisex": "shoes"},
+    "sportswear": {"women": "womens-sports", "men": "mens-sports", "unisex": "sports"},
+}
+
+_COLOR_TERMS = [
+    "black",
+    "white",
+    "navy",
+    "blue",
+    "grey",
+    "gray",
+    "beige",
+    "olive",
+    "green",
+    "brown",
+    "khaki",
+    "cream",
+    "maroon",
+    "charcoal",
+    "tan",
+    "red",
+    "pink",
+    "purple",
+    "yellow",
+    "orange",
+]
+
+
+ScrapePostprocessFn = Callable[[list[dict[str, str]]], list[dict[str, str]]]
+WardrobeSummary = dict[str, Any]
+TextCompletionFn = Callable[[str, int], str]
+
+
+def _norm(value: Any) -> str:
+    return str(value or "").strip().lower()
+
+
+def _normalize_target_category(value: Any) -> str:
+    normalized = _norm(value)
+    if normalized in {"topwear", "top", "upper", "tops"}:
+        return "topwear"
+    if normalized in {"bottomwear", "bottom", "lower", "bottoms"}:
+        return "bottomwear"
+    return "both"
+
+
+def _extract_price_text(value: Any) -> str:
+    text = str(value or "").strip()
+    if not text:
+        return "N/A"
+    match = re.search(r"([\u00a3$€]\s?\d+[\d,]*(?:\.\d{2})?)", text)
+    if match:
+        return match.group(1).replace(" ", "")
+    return text
+
+
+def _extract_src_from_srcset(srcset: str) -> str:
+    if not srcset:
+        return ""
+    first = srcset.split(",")[0].strip()
+    return first.split(" ")[0].strip()
+
+
+def _ensure_zalando_url(value: str) -> str:
+    href = str(value or "").strip()
+    if not href:
+        return ""
+    if href.startswith("//"):
+        return f"https:{href}"
+    if href.startswith("/"):
+        return f"{ZALANDO_BASE_URL}{href}"
+    return href
+
+
+def _format_apify_money(raw_value: Any, currency_symbol: str) -> str:
+    text = str(raw_value or "").strip()
+    if not text:
+        return ""
+
+    normalized = text.replace(",", "")
+    # Apify commonly returns minor units like 5999 => 59.99
+    if re.fullmatch(r"\d+", normalized):
+        major = int(normalized) // 100
+        minor = int(normalized) % 100
+        return f"{currency_symbol}{major}.{minor:02d}" if currency_symbol else f"{major}.{minor:02d}"
+
+    match = re.search(r"\d+(?:\.\d{1,2})?", normalized)
+    if not match:
+        return ""
+    return f"{currency_symbol}{match.group(0)}" if currency_symbol else match.group(0)
+
+
+def summarize_wardrobe_metadata(wardrobe_items: list[dict[str, Any]]) -> WardrobeSummary:
+    items = [item for item in wardrobe_items if isinstance(item, dict)]
+    colors: dict[str, int] = {}
+    types: dict[str, int] = {}
+    categories: dict[str, int] = {}
+    fabrics: dict[str, int] = {}
+    fits: dict[str, int] = {}
+    occasions: dict[str, int] = {}
+
+    for item in items:
+        description = item.get("description") if isinstance(item.get("description"), dict) else {}
+        color = str(item.get("color") or description.get("color") or "").strip().lower()
+        garment_type = str(item.get("type") or description.get("type") or "").strip().lower()
+        category = str(item.get("category") or description.get("category") or "").strip().lower()
+        fabric = str(item.get("fabric") or description.get("fabric") or "").strip().lower()
+        fit = str(item.get("fit") or description.get("fit") or "").strip().lower()
+        occasion = str(item.get("occasion") or description.get("occasion") or description.get("style") or "").strip().lower()
+
+        if color:
+            colors[color] = colors.get(color, 0) + 1
+        if garment_type:
+            types[garment_type] = types.get(garment_type, 0) + 1
+        if category:
+            categories[category] = categories.get(category, 0) + 1
+        if fabric:
+            fabrics[fabric] = fabrics.get(fabric, 0) + 1
+        if fit:
+            fits[fit] = fits.get(fit, 0) + 1
+        if occasion:
+            occasions[occasion] = occasions.get(occasion, 0) + 1
+
+    def top_values(counter: dict[str, int], limit: int = 8) -> list[dict[str, Any]]:
+        return [
+            {"value": key, "count": count}
+            for key, count in sorted(counter.items(), key=lambda pair: pair[1], reverse=True)[:limit]
+        ]
+
+    return {
+        "total_items": len(items),
+        "colors": top_values(colors),
+        "types": top_values(types),
+        "categories": top_values(categories),
+        "fabrics": top_values(fabrics),
+        "fits": top_values(fits),
+        "occasions": top_values(occasions),
+    }
+
+
+def _count_query_signals(query: str, requested_category: str | None = None) -> dict[str, bool]:
+    normalized = _norm(query)
+    has_color = any(color in normalized for color in _COLOR_TERMS)
+    requested = _norm(requested_category)
+    has_type = bool(requested and requested not in {"both", "all"}) or any(
+        token in normalized for token in [
+            "trouser", "trousers", "pants", "jeans", "shorts", "joggers", "skirt", "dress",
+            "topwear", "bottomwear", "shirt", "tee", "blouse", "polo", "hoodie", "jacket",
+            "sweater", "blazer", "t-shirt", "tank", "leggings",
+        ]
+    )
+    has_style = any(token in normalized for token in [
+        "slim", "regular", "relaxed", "oversized", "tailored", "smart", "casual", "formal",
+        "party", "work", "interview", "weekend", "minimal", "structured", "clean",
+    ])
+    has_fit = any(token in normalized for token in ["slim-fit", "slim fit", "regular-fit", "regular fit", "relaxed-fit", "relaxed fit"])
+    return {
+        "has_color": has_color,
+        "has_type": has_type,
+        "has_style": has_style or has_fit,
+    }
+
+
+def is_underspecified_query(query: str, requested_category: str | None = None) -> bool:
+    signals = _count_query_signals(query, requested_category=requested_category)
+    explicit_signal_count = sum(1 for value in signals.values() if value)
+    vague_tokens = {
+        "some",
+        "something",
+        "stuff",
+        "nice",
+        "good",
+        "recommend",
+        "suggest",
+        "maybe",
+        "outfit",
+        "look",
+    }
+    normalized = _norm(query)
+    has_vague_language = any(token in normalized for token in vague_tokens)
+    return explicit_signal_count < 3 or has_vague_language
+
+
+def _build_enrichment_prompt(
+    query: str,
+    wardrobe_summary: WardrobeSummary,
+    requested_category: str | None,
+    gender: str | None,
+) -> str:
+    return (
+        "You are helping enrich an underspecified Zalando shopping request. "
+        "Return ONLY valid JSON and no prose.\n\n"
+        "Output schema:\n"
+        '{"suggested_types":[],"suggested_colours":[],"occasion":"","style_notes":""}\n\n'
+        f"User query: {query}\n"
+        f"Requested category: {requested_category or ''}\n"
+        f"Gender: {gender or ''}\n"
+        f"Wardrobe metadata summary: {json.dumps(wardrobe_summary, ensure_ascii=True)}\n\n"
+        "Rules:\n"
+        "- Keep suggested_types to product/search terms that fit the requested category.\n"
+        "- Keep suggested_colours complementary to the wardrobe summary.\n"
+        "- Occasion must be a single short lowercase label when possible.\n"
+        "- style_notes must be concise and search-friendly.\n"
+    )
+
+
+def _parse_json_object(text: str) -> dict[str, Any]:
+    raw = str(text or "").strip()
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        start = raw.find("{")
+        end = raw.rfind("}")
+        if start == -1 or end == -1 or end <= start:
+            return {}
+        try:
+            parsed = json.loads(raw[start : end + 1])
+            return parsed if isinstance(parsed, dict) else {}
+        except json.JSONDecodeError:
+            return {}
+
+
+def _normalize_enrichment_payload(payload: dict[str, Any], requested_category: str | None) -> dict[str, Any]:
+    def to_list(value: Any) -> list[str]:
+        if not isinstance(value, list):
+            return []
+        cleaned: list[str] = []
+        for entry in value:
+            text = str(entry or "").strip()
+            if text and text not in cleaned:
+                cleaned.append(text)
+        return cleaned
+
+    suggested_types = to_list(payload.get("suggested_types"))
+    suggested_colours = to_list(payload.get("suggested_colours") or payload.get("suggested_colors"))
+    occasion = str(payload.get("occasion") or "").strip().lower()
+    style_notes = str(payload.get("style_notes") or "").strip()
+
+    requested = _norm(requested_category)
+    if requested and requested not in {"both", "all"} and requested not in {"topwear", "bottomwear"}:
+        requested = "bottomwear" if any(token in requested for token in ["bottom", "trouser", "pant", "jean", "skirt", "short"]) else "topwear"
+
+    if requested in {"topwear", "bottomwear"} and not suggested_types:
+        suggested_types = [requested]
+
+    if not suggested_colours:
+        suggested_colours = ["black"]
+
+    return {
+        "suggested_types": suggested_types,
+        "suggested_colours": suggested_colours,
+        "occasion": occasion,
+        "style_notes": style_notes,
+    }
+
+
+def enrich_underspecified_query(
+    query: str,
+    wardrobe_items: list[dict[str, Any]] | None = None,
+    requested_category: str | None = None,
+    gender: str | None = None,
+    completion_fn: TextCompletionFn | None = None,
+    max_tokens: int = 500,
+) -> dict[str, Any]:
+    wardrobe_summary = summarize_wardrobe_metadata(wardrobe_items or [])
+    if not is_underspecified_query(query, requested_category=requested_category):
+        return {
+            "used": False,
+            "query": str(query or "").strip(),
+            "wardrobe_summary": wardrobe_summary,
+            "enrichment": {
+                "suggested_types": [],
+                "suggested_colours": [],
+                "occasion": "",
+                "style_notes": "",
+            },
+        }
+
+    if not completion_fn:
+        return {
+            "used": True,
+            "query": str(query or "").strip(),
+            "wardrobe_summary": wardrobe_summary,
+            "enrichment": {
+                "suggested_types": [],
+                "suggested_colours": [],
+                "occasion": "",
+                "style_notes": "",
+            },
+        }
+
+    prompt = _build_enrichment_prompt(query, wardrobe_summary, requested_category, gender)
+    model_text = completion_fn(prompt, max_tokens)
+    parsed = _parse_json_object(model_text)
+    enrichment = _normalize_enrichment_payload(parsed, requested_category=requested_category)
+    return {
+        "used": True,
+        "query": str(query or "").strip(),
+        "wardrobe_summary": wardrobe_summary,
+        "enrichment": enrichment,
+    }
+
+
+def compose_search_query_from_enrichment(
+    query: str,
+    enrichment: dict[str, Any] | None,
+    gender: str | None = None,
+    requested_category: str | None = None,
+) -> str:
+    base_query = str(query or "").strip()
+    enrichment = enrichment or {}
+    target_category = _normalize_target_category(requested_category)
+
+    suggested_types = [str(value).strip() for value in (enrichment.get("suggested_types") or []) if str(value).strip()]
+    suggested_colours = [str(value).strip() for value in (enrichment.get("suggested_colours") or []) if str(value).strip()]
+    style_notes = str(enrichment.get("style_notes") or "").strip()
+    occasion = str(enrichment.get("occasion") or "").strip()
+
+    tokens: list[str] = []
+    if base_query:
+        tokens.extend([piece for piece in re.split(r"\s+", base_query) if piece])
+    elif gender:
+        tokens.append(_normalize_gender(gender, base_query))
+
+    def append_unique(token: str) -> None:
+        cleaned = str(token or "").strip()
+        if cleaned and cleaned not in tokens:
+            tokens.append(cleaned)
+
+    if gender:
+        append_unique(_normalize_gender(gender, base_query))
+
+    if suggested_colours:
+        append_unique(suggested_colours[0])
+
+    if suggested_types:
+        append_unique(suggested_types[0])
+    elif requested_category:
+        requested = _norm(requested_category)
+        if requested in {"topwear", "bottomwear"}:
+            append_unique(requested)
+        elif any(token in requested for token in ["bottom", "trouser", "pant", "jean", "skirt", "short"]):
+            append_unique("bottomwear")
+        elif any(token in requested for token in ["top", "shirt", "tee", "blouse", "polo", "jacket"]):
+            append_unique("topwear")
+
+    if occasion:
+        append_unique(occasion)
+
+    if style_notes:
+        style_tokens = [piece for piece in re.split(r"[^a-zA-Z0-9-]+", style_notes.lower()) if piece]
+        for token in style_tokens[:3]:
+            append_unique(token)
+
+    if not tokens:
+        tokens = [base_query or _normalize_gender(gender, base_query)]
+
+    topwear_terms = {"shirt", "shirts", "tee", "t-shirt", "tshirt", "topwear", "blazer", "jacket", "polo", "hoodie", "kurta"}
+    bottomwear_terms = {"trouser", "trousers", "pants", "jeans", "shorts", "joggers", "bottomwear"}
+
+    normalized_tokens = [str(token).strip().lower() for token in tokens]
+    has_topwear_term = any(token in topwear_terms for token in normalized_tokens)
+    has_bottomwear_term = any(token in bottomwear_terms for token in normalized_tokens)
+
+    if target_category == "bottomwear" and has_topwear_term and not has_bottomwear_term:
+        replacement = "trousers"
+        for index, token in enumerate(normalized_tokens):
+            if token in topwear_terms:
+                tokens[index] = replacement
+                normalized_tokens[index] = replacement
+                break
+        else:
+            append_unique(replacement)
+    elif target_category == "topwear" and has_bottomwear_term and not has_topwear_term:
+        replacement = "shirt"
+        for index, token in enumerate(normalized_tokens):
+            if token in bottomwear_terms:
+                tokens[index] = replacement
+                normalized_tokens[index] = replacement
+                break
+        else:
+            append_unique(replacement)
+
+    return " ".join(part for part in tokens if part).strip()
+
+
+def _normalize_gender(gender: str | None, query: str) -> str:
+    g = _norm(gender)
+    if g in {"men", "male", "man", "mens"}:
+        return "men"
+    if g in {"women", "female", "woman", "womens"}:
+        return "women"
+    if g == "unisex":
+        return "unisex"
+
+    query_hint = _norm(query)
+    if any(token in query_hint for token in [" men ", "male", "man", "mens"]):
+        return "men"
+    if any(token in query_hint for token in [" women ", "female", "woman", "womens"]):
+        return "women"
+    return "unisex"
+
+
+def _pick_category_path(query: str, audience: str) -> str:
+    haystack = _norm(query)
+    selected = ""
+    for token, path_map in CATEGORY_PATH_MAP.items():
+        if token in haystack:
+            selected = path_map.get(audience) or path_map.get("unisex") or ""
+            break
+
+    if not selected:
+        if audience == "men":
+            selected = "mens-clothing"
+        elif audience == "women":
+            selected = "womens-clothing"
+        else:
+            selected = "clothing"
+
+    if audience == "men" and selected.startswith("womens-"):
+        selected = selected.replace("womens-", "mens-", 1)
+    if audience == "women" and selected.startswith("mens-"):
+        selected = selected.replace("mens-", "womens-", 1)
+    if audience == "unisex" and selected.startswith(("mens-", "womens-")):
+        selected = selected.split("-", 1)[1]
+
+    return selected or "clothing"
+
+
+def build_zalando_search_url(query: str, gender: str | None = None) -> str:
+    normalized_query = str(query or "").strip()
+    if not normalized_query:
+        raise ValueError("query is required")
+
+    audience = _normalize_gender(gender, normalized_query)
+    path = _pick_category_path(normalized_query, audience)
+    params = urlencode({"q": normalized_query})
+    return f"{ZALANDO_BASE_URL}/{path}?{params}"
+
+
+def build_zalando_search_urls_from_query(query: str, gender: str | None = None) -> list[str]:
+    normalized_query = str(query or "").strip()
+    if not normalized_query:
+        return []
+
+    if gender:
+        return [build_zalando_search_url(normalized_query, gender=gender)]
+
+    urls: list[str] = []
+    for audience in ["women", "men", "unisex"]:
+        url = build_zalando_search_url(normalized_query, gender=audience)
+        if url not in urls:
+            urls.append(url)
+    return urls
+
+
+def build_zalando_search_urls_from_request(
+    query: str,
+    gender: str | None = None,
+    wardrobe_items: list[dict[str, Any]] | None = None,
+    requested_category: str | None = None,
+    completion_fn: TextCompletionFn | None = None,
+    max_tokens: int = 500,
+) -> tuple[list[str], dict[str, Any]]:
+    enrichment_result = enrich_underspecified_query(
+        query=query,
+        wardrobe_items=wardrobe_items,
+        requested_category=requested_category,
+        gender=gender,
+        completion_fn=completion_fn,
+        max_tokens=max_tokens,
+    )
+    final_query = compose_search_query_from_enrichment(
+        query=enrichment_result.get("query") or query,
+        enrichment=enrichment_result.get("enrichment") if isinstance(enrichment_result.get("enrichment"), dict) else None,
+        gender=gender,
+        requested_category=requested_category,
+    )
+    search_urls = build_zalando_search_urls_from_query(final_query, gender=gender)
+    return search_urls, {**enrichment_result, "final_query": final_query}
+
+
+def _apify_request_url() -> str:
+    if APIFY_TOKEN:
+        return f"{APIFY_ACTOR_ENDPOINT}?token={APIFY_TOKEN}"
+    return APIFY_ACTOR_ENDPOINT
+
+
+def _apify_actor_id_from_endpoint(endpoint: str) -> str:
+    parsed = urlparse(str(endpoint or "").strip())
+    segments = [segment for segment in parsed.path.split("/") if segment]
+    if "acts" in segments:
+        index = segments.index("acts")
+        if index + 1 < len(segments):
+            return segments[index + 1]
+    return "vistics~zalando-scraper"
+
+
+def _build_apify_payload(search_url: str, max_results: int, start_urls_as_objects: bool) -> dict[str, Any]:
+    start_urls: list[Any]
+    if start_urls_as_objects:
+        start_urls = [{"url": search_url}]
+    else:
+        start_urls = [search_url]
+
+    return {
+        "startUrls": start_urls,
+        "maxResults": int(max_results),
+    }
+
+
+def _http_error_detail(exc: requests.RequestException, limit: int = 800) -> str:
+    response = getattr(exc, "response", None)
+    if response is None:
+        return ""
+
+    status = getattr(response, "status_code", None)
+    body = ""
+    try:
+        body = str(response.text or "").strip().replace("\n", " ")
+    except Exception:
+        body = ""
+    if body:
+        body = body[:limit]
+    if status is None and not body:
+        return ""
+    return f"status={status} body={body}".strip()
+
+
+def _extract_apify_items(raw_payload: Any) -> list[dict[str, Any]]:
+    if isinstance(raw_payload, list):
+        return [item for item in raw_payload if isinstance(item, dict)]
+
+    if isinstance(raw_payload, dict):
+        for key in ("items", "data"):
+            value = raw_payload.get(key)
+            if isinstance(value, list):
+                return [item for item in value if isinstance(item, dict)]
+
+    return []
+
+
+def _normalize_apify_items(raw_items: list[dict[str, Any]], effective_limit: int) -> list[dict[str, str]]:
+    items: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for raw in raw_items:
+        normalized = _normalize_product(raw)
+        if not normalized["item_link"] or normalized["item_link"] in seen:
+            continue
+        seen.add(normalized["item_link"])
+        items.append(normalized)
+        if len(items) >= effective_limit:
+            break
+    return items
+
+
+def _scrape_with_apify_run_dataset_fallback(
+    search_url: str,
+    effective_limit: int,
+    timeout_seconds: int,
+) -> list[dict[str, str]]:
+    actor_id = _apify_actor_id_from_endpoint(APIFY_ACTOR_ENDPOINT)
+    run_url = f"https://api.apify.com/v2/acts/{actor_id}/runs"
+    wait_for_finish = min(max(60, APIFY_WAIT_FOR_FINISH_SECONDS), 300)
+    variant_errors: list[str] = []
+
+    logger.info(
+        "zalando crawl retry source=apify-run search_url=%s actor_id=%s wait_for_finish=%s",
+        search_url,
+        actor_id,
+        wait_for_finish,
+    )
+
+    variants = [
+        ("string", False),
+        ("object", True),
+    ]
+
+    for variant_name, use_object_start_urls in variants:
+        run_payload = _build_apify_payload(search_url, effective_limit, start_urls_as_objects=use_object_start_urls)
+        run_id = ""
+        run_status = ""
+        dataset_id = ""
+        try:
+            run_response = requests.post(
+                run_url,
+                params={"token": APIFY_TOKEN, "waitForFinish": wait_for_finish},
+                json=run_payload,
+                timeout=timeout_seconds,
+            )
+            run_response.raise_for_status()
+            run_json = run_response.json()
+
+            run_data = run_json.get("data") if isinstance(run_json, dict) else None
+            if not isinstance(run_data, dict):
+                variant_errors.append(f"{variant_name}: invalid run payload")
+                continue
+
+            run_id = str(run_data.get("id") or "").strip()
+            run_status = str(run_data.get("status") or "").strip()
+            dataset_id = str(run_data.get("defaultDatasetId") or "").strip()
+            logger.info(
+                "zalando crawl retry source=apify-run completed variant=%s run_id=%s status=%s dataset_id=%s",
+                variant_name,
+                run_id,
+                run_status,
+                dataset_id,
+            )
+        except requests.RequestException as exc:
+            detail = _http_error_detail(exc)
+            variant_errors.append(f"{variant_name}: {exc} {detail}".strip())
+            logger.warning(
+                "zalando crawl failed source=apify-run variant=%s search_url=%s error=%s detail=%s",
+                variant_name,
+                search_url,
+                exc,
+                detail,
+            )
+            continue
+
+        if not dataset_id:
+            variant_errors.append(f"{variant_name}: missing defaultDatasetId")
+            continue
+
+        try:
+            dataset_response = requests.get(
+                f"https://api.apify.com/v2/datasets/{dataset_id}/items",
+                params={
+                    "token": APIFY_TOKEN,
+                    "clean": "true",
+                    "format": "json",
+                    "limit": effective_limit,
+                },
+                timeout=timeout_seconds,
+            )
+            dataset_response.raise_for_status()
+            dataset_items = _extract_apify_items(dataset_response.json())
+            items = _normalize_apify_items(dataset_items, effective_limit)
+            logger.info(
+                "zalando crawl retry source=apify-dataset variant=%s run_id=%s dataset_id=%s raw_items=%s items=%s",
+                variant_name,
+                run_id,
+                dataset_id,
+                len(dataset_items),
+                len(items),
+            )
+            if items:
+                return items
+            variant_errors.append(f"{variant_name}: empty dataset")
+        except requests.RequestException as exc:
+            detail = _http_error_detail(exc)
+            variant_errors.append(f"{variant_name}: {exc} {detail}".strip())
+            logger.warning(
+                "zalando crawl failed source=apify-dataset variant=%s run_id=%s dataset_id=%s error=%s detail=%s",
+                variant_name,
+                run_id,
+                dataset_id,
+                exc,
+                detail,
+            )
+
+    if variant_errors:
+        logger.warning(
+            "zalando crawl retry source=apify-run exhausted search_url=%s errors=%s",
+            search_url,
+            "; ".join(variant_errors),
+        )
+    return []
+
+
+def _normalize_product(item: dict[str, Any]) -> dict[str, str]:
+    name = str(
+        item.get("name")
+        or item.get("title")
+        or item.get("productName")
+        or item.get("product_name")
+        or "N/A"
+    ).strip()
+    fallback_price = _extract_price_text(
+        item.get("price")
+        or item.get("currentPrice")
+        or item.get("displayPrice")
+        or item.get("priceLabel")
+        or "N/A"
+    )
+    currency_symbol = str(item.get("currencySymbol") or "").strip()
+    promotional_price = _format_apify_money(item.get("promotionalPrice"), currency_symbol)
+    original_price = _format_apify_money(item.get("originalPrice"), currency_symbol)
+    discount_percent = str(item.get("discountPercent") or "").strip()
+    brand = str(item.get("brand") or item.get("brandName") or "").strip()
+
+    if promotional_price:
+        price = promotional_price if not discount_percent else f"{promotional_price} ({discount_percent})"
+    elif original_price:
+        price = original_price
+    else:
+        price = fallback_price
+
+    image_url = _ensure_zalando_url(
+        str(
+            item.get("image")
+            or item.get("imageUrl")
+            or item.get("image_url")
+            or item.get("thumbnail")
+            or ""
+        )
+    )
+
+    url_value = _ensure_zalando_url(
+        str(
+            item.get("url")
+            or item.get("productUrl")
+            or item.get("item_link")
+            or item.get("link")
+            or ""
+        )
+    )
+
+    return {
+        "name": name or "N/A",
+        "price": price or "N/A",
+        "brand": brand,
+        "currency_symbol": currency_symbol,
+        "promotional_price": promotional_price,
+        "original_price": original_price,
+        "discount_percent": discount_percent,
+        "image_url": image_url,
+        "item_link": url_value,
+    }
+
+
+def _scrape_with_apify(search_url: str, max_products: int | None, timeout_seconds: int) -> list[dict[str, str]]:
+    requested_limit = int(max_products) if isinstance(max_products, int) and max_products > 0 else APIFY_MAX_RESULTS
+    effective_limit = min(requested_limit, APIFY_MAX_RESULTS)
+    apify_timeout = max(int(timeout_seconds), APIFY_MIN_TIMEOUT_SECONDS)
+    actor_id = _apify_actor_id_from_endpoint(APIFY_ACTOR_ENDPOINT)
+    logger.info(
+        "zalando crawl start source=apify search_url=%s requested_max=%s effective_max=%s timeout=%s actor_id=%s",
+        search_url,
+        max_products,
+        effective_limit,
+        apify_timeout,
+        actor_id,
+    )
+
+    variants = [
+        ("string", False),
+        ("object", True),
+    ]
+    variant_errors: list[str] = []
+    for variant_name, use_object_start_urls in variants:
+        try:
+            payload = _build_apify_payload(search_url, effective_limit, start_urls_as_objects=use_object_start_urls)
+            response = requests.post(_apify_request_url(), json=payload, timeout=apify_timeout)
+            response.raise_for_status()
+
+            raw_items = _extract_apify_items(response.json())
+            items = _normalize_apify_items(raw_items, effective_limit)
+            logger.info(
+                "zalando crawl end source=apify variant=%s search_url=%s crawled=%s raw_items=%s items=%s",
+                variant_name,
+                search_url,
+                bool(items),
+                len(raw_items),
+                len(items),
+            )
+            if items:
+                return items
+            variant_errors.append(f"{variant_name}: empty result")
+        except requests.RequestException as exc:
+            detail = _http_error_detail(exc)
+            variant_errors.append(f"{variant_name}: {exc} {detail}".strip())
+            logger.warning(
+                "zalando crawl failed source=apify variant=%s search_url=%s error=%s detail=%s",
+                variant_name,
+                search_url,
+                exc,
+                detail,
+            )
+            continue
+
+    try:
+        fallback_items = _scrape_with_apify_run_dataset_fallback(
+            search_url=search_url,
+            effective_limit=effective_limit,
+            timeout_seconds=apify_timeout,
+        )
+        logger.info(
+            "zalando crawl end source=apify-run search_url=%s crawled=%s items=%s",
+            search_url,
+            bool(fallback_items),
+            len(fallback_items),
+        )
+        if fallback_items:
+            return fallback_items
+    except requests.RequestException as exc:
+        detail = _http_error_detail(exc)
+        variant_errors.append(f"run_dataset: {exc} {detail}".strip())
+        logger.warning("zalando crawl failed source=apify-run search_url=%s error=%s detail=%s", search_url, exc, detail)
+
+    if variant_errors:
+        logger.warning(
+            "zalando crawl source=apify exhausted search_url=%s errors=%s",
+            search_url,
+            "; ".join(variant_errors),
+        )
+
+    logger.warning(
+        "zalando crawl end source=apify search_url=%s crawled=False items=0 reason=no_items_from_sync_or_run_dataset",
+        search_url,
+    )
+    return []
+
+
+def _scrape_with_html(search_url: str, max_products: int | None, timeout_seconds: int) -> list[dict[str, str]]:
+    html_timeout = max(int(timeout_seconds), HTML_FALLBACK_TIMEOUT_SECONDS)
+    logger.info("zalando crawl start source=html search_url=%s max_products=%s timeout=%s", search_url, max_products, html_timeout)
+    response = requests.get(search_url, headers=REQUEST_HEADERS, timeout=html_timeout)
+    response.raise_for_status()
+    soup = BeautifulSoup(response.content, "lxml")
+
+    items: list[dict[str, str]] = []
+    seen: set[str] = set()
+
+    cards = soup.select('article, div[data-testid*="product"], li[data-testid*="product"]')
+    for card in cards:
+        link_tag = card.select_one('a[href*="/p/"]') or card.find("a", href=True)
+        if not link_tag:
+            continue
+
+        item_link = _ensure_zalando_url(str(link_tag.get("href") or ""))
+        if not item_link or item_link in seen or "zalando" not in item_link:
+            continue
+
+        name_tag = (
+            card.select_one('[data-testid*="product-name"]')
+            or card.select_one('[data-testid*="name"]')
+            or card.find("h3")
+            or card.find("h2")
+            or link_tag
+        )
+        name = str(name_tag.get_text(" ", strip=True) if name_tag else "N/A").strip() or "N/A"
+
+        price_tag = (
+            card.select_one('[data-testid*="price"]')
+            or card.find(attrs={"class": re.compile(r"price|money|amount", re.I)})
+        )
+        price_text = str(price_tag.get_text(" ", strip=True) if price_tag else "")
+        price = _extract_price_text(price_text)
+
+        img_tag = card.find("img")
+        image_url = ""
+        if img_tag:
+            image_url = _ensure_zalando_url(
+                str(
+                    img_tag.get("src")
+                    or img_tag.get("data-src")
+                    or _extract_src_from_srcset(str(img_tag.get("srcset") or ""))
+                )
+            )
+
+        seen.add(item_link)
+        items.append(
+            {
+                "name": name,
+                "price": price,
+                "image_url": image_url,
+                "item_link": item_link,
+            }
+        )
+        if isinstance(max_products, int) and max_products > 0 and len(items) >= max_products:
+            break
+
+    logger.info("zalando crawl end source=html search_url=%s crawled=%s items=%s", search_url, bool(items), len(items))
+    return items
+
+
+def _requires_postprocess(items: list[dict[str, str]]) -> bool:
+    if not items:
+        return False
+    missing = 0
+    for item in items:
+        if item.get("name") in {"", "N/A"} or item.get("price") in {"", "N/A"}:
+            missing += 1
+    return missing > 0
+
+
+def extract_product_summaries(
+    search_url: str,
+    max_products: int | None = None,
+    request_timeout_seconds: int = 35,
+    use_apify: bool = True,
+    postprocess: Optional[ScrapePostprocessFn] = None,
+) -> list[dict[str, str]]:
+    if not str(search_url or "").strip():
+        raise ValueError("search_url is required")
+
+    max_count = int(max_products) if isinstance(max_products, int) and max_products > 0 else None
+    logger.info(
+        "zalando crawl requested search_url=%s max_products=%s capped_to=%s use_apify=%s actor_id=%s",
+        search_url,
+        max_products,
+        max_count,
+        bool(use_apify and APIFY_TOKEN),
+        _apify_actor_id_from_endpoint(APIFY_ACTOR_ENDPOINT),
+    )
+    products: list[dict[str, str]] = []
+    errors: list[str] = []
+
+    if use_apify and APIFY_TOKEN:
+        try:
+            products = _scrape_with_apify(search_url, max_count, request_timeout_seconds)
+            if not products:
+                errors.append("apify: empty result set")
+                logger.warning("zalando crawl source=apify returned zero items search_url=%s", search_url)
+        except requests.RequestException as exc:
+            errors.append(f"apify: {exc}")
+            logger.warning("zalando crawl failed source=apify search_url=%s error=%s", search_url, exc)
+
+    if not products:
+        try:
+            if use_apify and APIFY_TOKEN:
+                logger.info("zalando crawl fallback source=html search_url=%s", search_url)
+            products = _scrape_with_html(search_url, max_count, request_timeout_seconds)
+        except requests.RequestException as exc:
+            errors.append(f"html: {exc}")
+            logger.warning("zalando crawl failed source=html search_url=%s error=%s", search_url, exc)
+
+    if postprocess and _requires_postprocess(products):
+        try:
+            products = postprocess(products)
+        except Exception:
+            # Never fail scraping because post-processing failed.
+            pass
+
+    if not products and errors:
+        logger.warning("zalando crawl completed with no results search_url=%s errors=%s", search_url, "; ".join(errors))
+        raise requests.RequestException("; ".join(errors))
+
+    logger.info("zalando crawl completed search_url=%s crawled=%s items=%s", search_url, bool(products), len(products))
+    if isinstance(max_count, int) and max_count > 0:
+        return products[:max_count]
+    return products
+
+
+def search_products(
+    query: str,
+    gender: str | None = None,
+    max_products: int | None = None,
+    use_apify: bool = True,
+    request_timeout_seconds: int = 35,
+    postprocess: Optional[ScrapePostprocessFn] = None,
+    wardrobe_items: list[dict[str, Any]] | None = None,
+    requested_category: str | None = None,
+    completion_fn: TextCompletionFn | None = None,
+    enrichment_max_tokens: int = 500,
+) -> dict[str, Any]:
+    max_count = int(max_products) if isinstance(max_products, int) and max_products > 0 else None
+    search_urls, enrichment_result = build_zalando_search_urls_from_request(
+        query=query,
+        gender=gender,
+        wardrobe_items=wardrobe_items,
+        requested_category=requested_category,
+        completion_fn=completion_fn,
+        max_tokens=enrichment_max_tokens,
+    )
+    if not search_urls:
+        raise ValueError("query is required")
+
+    logger.info(
+        "zalando search plan query=%s search_urls=%s max_products=%s",
+        query,
+        len(search_urls),
+        max_count,
+    )
+
+    products: list[dict[str, str]] = []
+    seen: set[str] = set()
+
+    for search_url in search_urls:
+        summaries = extract_product_summaries(
+            search_url=search_url,
+            max_products=max_count,
+            request_timeout_seconds=request_timeout_seconds,
+            use_apify=use_apify,
+            postprocess=postprocess,
+        )
+        for item in summaries:
+            item_link = str(item.get("item_link") or "").strip()
+            if not item_link or item_link in seen:
+                continue
+            seen.add(item_link)
+            products.append(item)
+            if isinstance(max_count, int) and max_count > 0 and len(products) >= max_count:
+                break
+        if isinstance(max_count, int) and max_count > 0 and len(products) >= max_count:
+            break
+
+    logger.info(
+        "zalando search completed query=%s crawled=%s items=%s search_urls=%s",
+        query,
+        bool(products),
+        len(products),
+        len(search_urls),
+    )
+
+    return {
+        "search_urls": search_urls,
+        "products": products,
+        "count": len(products),
+        "enrichment": enrichment_result,
+    }