┌─────────────────────────────────────────────────────────────────────────────┐
│                    E-COMMERCE PRODUCT DISCOVERY ARCHITECTURE                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ USER INPUT                                                          │    │
│  │   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │    │
│  │   │ Search Query │  │ Image Upload │  │Browse History│              │    │
│  │   └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │    │
│  └──────────┼─────────────────┼─────────────────┼──────────────────────┘    │
│             │                 │                 │                           │
│             ▼                 │                 │                           │
│  ┌──────────────────────┐     │                 │                           │
│  │ QUERY UNDERSTANDING  │     │                 │                           │
│  │ Intent Classification│     │                 │                           │
│  │        │             │     │                 │                           │
│  │        ▼             │     │                 │                           │
│  │ Query Expansion      │     │                 │                           │
│  │        │             │     │                 │                           │
│  │        ▼             │     │                 │                           │
│  │ Filter Extraction    │     │                 │                           │
│  └──────────┬───────────┘     │                 │                           │
│             │                 │                 │                           │
│             ▼                 ▼                 ▼                           │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ MULTI-MODAL RETRIEVAL                                               │    │
│  │   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │    │
│  │   │    Text      │  │    Image     │  │  Behavioral  │              │    │
│  │   │  Embeddings  │  │  Embeddings  │  │   Signals    │              │    │
│  │   └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │    │
│  └──────────┴─────────────────┴─────────────────┴──────────────────────┘    │
│                           │                                                 │
│                           ▼                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ RANKING PIPELINE                                                    │    │
│  │   ┌────────────┐ ┌────────────┐ ┌────────────┐                      │    │
│  │   │ Semantic   │ │ Popularity │ │Personalizat│                      │    │
│  │   │   Score    │ │   Score    │ │ion Score   │                      │    │
│  │   └─────┬──────┘ └─────┬──────┘ └─────┬──────┘                      │    │
│  │         └──────────────┴──────────────┘                             │    │
│  │                        │                                            │    │
│  │                        ▼                                            │    │
│  │                 Business Rules                                      │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                           │                                                 │
│                           ▼                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ RESULTS                                                             │    │
│  │   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │    │
│  │   │   Product    │  │   Dynamic    │  │Recommendation│              │    │
│  │   │   Results    │  │   Filters    │  │      s       │              │    │
│  │   └──────────────┘  └──────────────┘  └──────────────┘              │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

ecommerce-discovery/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── embeddings/
│   │   ├── __init__.py
│   │   ├── text_embedder.py     # Product text embeddings
│   │   ├── image_embedder.py    # Product image embeddings
│   │   └── multimodal.py        # Combined embeddings
│   ├── indexing/
│   │   ├── __init__.py
│   │   ├── product_indexer.py   # Product indexing pipeline
│   │   └── incremental.py       # Real-time updates
│   ├── search/
│   │   ├── __init__.py
│   │   ├── semantic_search.py   # Vector similarity search
│   │   ├── hybrid_search.py     # Combined search strategies
│   │   └── filters.py           # Dynamic filtering
│   ├── ranking/
│   │   ├── __init__.py
│   │   ├── scorer.py            # Multi-signal scoring
│   │   └── personalization.py   # User-based ranking
│   ├── recommendations/
│   │   ├── __init__.py
│   │   ├── collaborative.py     # Collaborative filtering
│   │   ├── content_based.py     # Content similarity
│   │   └── hybrid.py            # Hybrid recommendations
│   └── api/
│       ├── __init__.py
│       └── main.py              # FastAPI endpoints
├── scripts/
│   └── index_products.py        # Batch indexing script
├── tests/
└── requirements.txt

# src/config.py
from pydantic_settings import BaseSettings
from typing import Optional

class Settings(BaseSettings):
    # Embedding Models
    openai_api_key: str
    text_embedding_model: str = "text-embedding-3-large"
    text_embedding_dim: int = 3072

    # Image Embeddings
    clip_model: str = "ViT-L-14"
    image_embedding_dim: int = 768

    # Vector Database
    pinecone_api_key: str
    pinecone_environment: str = "us-east-1"
    pinecone_index_name: str = "products"

    # Redis
    redis_url: str = "redis://localhost:6379"

    # Search Settings
    default_limit: int = 20
    max_limit: int = 100
    similarity_threshold: float = 0.7

    # Personalization
    history_weight: float = 0.3
    popularity_weight: float = 0.2
    semantic_weight: float = 0.5

    class Config:
        env_file = ".env"

settings = Settings()

# src/embeddings/text_embedder.py
from typing import List, Dict
import numpy as np
from openai import OpenAI
from ..config import settings

class TextEmbedder:
    """Generates text embeddings for products."""

    def __init__(self):
        self.client = OpenAI(api_key=settings.openai_api_key)
        self.model = settings.text_embedding_model
        self.dim = settings.text_embedding_dim

    def embed(self, text: str) -> List[float]:
        """Embed a single text."""
        response = self.client.embeddings.create(
            input=text,
            model=self.model
        )
        return response.data[0].embedding

    def embed_batch(self, texts: List[str]) -> List[List[float]]:
        """Embed multiple texts in batch."""
        response = self.client.embeddings.create(
            input=texts,
            model=self.model
        )
        return [item.embedding for item in response.data]

    def embed_product(self, product: Dict) -> List[float]:
        """Create embedding for a product."""
        # Combine product fields with weights
        text_parts = [
            product.get("name", "") * 3,  # Name weighted higher
            product.get("brand", "") * 2,
            product.get("category", ""),
            product.get("description", ""),
            " ".join(product.get("attributes", []))
        ]
        combined_text = " ".join(text_parts)

        # Truncate if too long
        if len(combined_text) > 8000:
            combined_text = combined_text[:8000]

        return self.embed(combined_text)


class QueryEmbedder:
    """Specialized embedder for search queries."""

    def __init__(self):
        self.embedder = TextEmbedder()

    def embed_query(self, query: str, context: Dict = None) -> List[float]:
        """Embed a search query with optional context."""
        # Expand query with context if available
        expanded_query = query

        if context:
            if context.get("category"):
                expanded_query = f"{context['category']}: {query}"
            if context.get("brand_preference"):
                expanded_query += f" {context['brand_preference']}"

        return self.embedder.embed(expanded_query)

┌─────────────────────────────────────────────────────────────┐
│ PRODUCT EMBEDDING CONSTRUCTION                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Product:                                                   │
│  • name: "Nike Air Max 90 Running Shoes"                    │
│  • brand: "Nike"                                            │
│  • category: "Running Shoes"                                │
│  • description: "Classic silhouette with Air cushioning..." │
│  • attributes: ["breathable mesh", "rubber sole"]           │
│        │                                                    │
│        ▼                                                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Weighted Concatenation:                             │   │
│  │                                                     │   │
│  │ name × 3    = "Nike Air Max 90... Nike Air Max..."  │   │
│  │ brand × 2   = "Nike Nike"                           │   │
│  │ category × 1 = "Running Shoes"                      │   │
│  │ description = "Classic silhouette..."               │   │
│  │ attributes  = "breathable mesh rubber sole"         │   │
│  │                                                     │   │
│  │ Combined: "Nike Air Max 90... Nike Nike..."         │   │
│  └─────────────────────────────────────────────────────┘   │
│        │                                                    │
│        ▼                                                    │
│  OpenAI text-embedding-3-large → 3072-dim vector            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/embeddings/image_embedder.py
from typing import List, Union
import numpy as np
import torch
from PIL import Image
import open_clip
from io import BytesIO
import requests
from ..config import settings

class ImageEmbedder:
    """Generates image embeddings using CLIP."""

    def __init__(self):
        self.device = "cuda" if torch.cuda.is_available() else "cpu"
        self.model, _, self.preprocess = open_clip.create_model_and_transforms(
            settings.clip_model,
            pretrained='openai'
        )
        self.model = self.model.to(self.device)
        self.model.eval()

    def load_image(self, source: Union[str, bytes]) -> Image.Image:
        """Load image from URL or bytes."""
        if isinstance(source, str):
            if source.startswith("http"):
                response = requests.get(source)
                return Image.open(BytesIO(response.content))
            else:
                return Image.open(source)
        else:
            return Image.open(BytesIO(source))

    def embed(self, image: Union[str, bytes, Image.Image]) -> List[float]:
        """Generate embedding for a single image."""
        if not isinstance(image, Image.Image):
            image = self.load_image(image)

        # Preprocess and embed
        image_input = self.preprocess(image).unsqueeze(0).to(self.device)

        with torch.no_grad():
            embedding = self.model.encode_image(image_input)
            embedding = embedding / embedding.norm(dim=-1, keepdim=True)

        return embedding.cpu().numpy().flatten().tolist()

    def embed_batch(
        self,
        images: List[Union[str, bytes, Image.Image]]
    ) -> List[List[float]]:
        """Embed multiple images in batch."""
        processed = []
        for img in images:
            if not isinstance(img, Image.Image):
                img = self.load_image(img)
            processed.append(self.preprocess(img))

        batch = torch.stack(processed).to(self.device)

        with torch.no_grad():
            embeddings = self.model.encode_image(batch)
            embeddings = embeddings / embeddings.norm(dim=-1, keepdim=True)

        return embeddings.cpu().numpy().tolist()


class MultiModalEmbedder:
    """Combines text and image embeddings."""

    def __init__(self):
        self.text_embedder = TextEmbedder()
        self.image_embedder = ImageEmbedder()

    def embed_product(
        self,
        product: Dict,
        image_url: str = None
    ) -> Dict[str, List[float]]:
        """Create both text and image embeddings for a product."""
        embeddings = {
            "text": self.text_embedder.embed_product(product)
        }

        if image_url:
            try:
                embeddings["image"] = self.image_embedder.embed(image_url)
            except Exception as e:
                print(f"Failed to embed image: {e}")

        return embeddings

┌─────────────────────────────────────────────────────────────┐
│ DUAL EMBEDDING APPROACH                                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Product: Nike Air Max 90                                   │
│        │                                                    │
│        ├───────────────────┬───────────────────┐            │
│        ▼                   ▼                                │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │ TEXT EMBEDDING  │  │ IMAGE EMBEDDING │                  │
│  │                 │  │                 │                  │
│  │ OpenAI         │  │ OpenCLIP        │                  │
│  │ text-embedding │  │ ViT-L-14        │                  │
│  │ 3-large        │  │                 │                  │
│  │                 │  │                 │                  │
│  │ Captures:      │  │ Captures:       │                  │
│  │ • Product name │  │ • Visual style  │                  │
│  │ • Description  │  │ • Color pattern │                  │
│  │ • Attributes   │  │ • Shape/form    │                  │
│  │ • Brand        │  │ • Texture       │                  │
│  │                 │  │                 │                  │
│  │ Dim: 3072      │  │ Dim: 768        │                  │
│  └────────┬────────┘  └────────┬────────┘                  │
│           │                    │                            │
│           ▼                    ▼                            │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Pinecone Namespaces                                 │   │
│  │ • namespace="text"  → text queries                  │   │
│  │ • namespace="image" → image queries                 │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/search/semantic_search.py
from typing import List, Dict, Optional
from pinecone import Pinecone
from ..embeddings.text_embedder import QueryEmbedder
from ..embeddings.image_embedder import ImageEmbedder
from ..config import settings

class SemanticSearch:
    """Vector similarity search for products."""

    def __init__(self):
        self.pc = Pinecone(api_key=settings.pinecone_api_key)
        self.index = self.pc.Index(settings.pinecone_index_name)
        self.query_embedder = QueryEmbedder()
        self.image_embedder = ImageEmbedder()

    def search_by_text(
        self,
        query: str,
        filters: Dict = None,
        limit: int = 20,
        context: Dict = None
    ) -> List[Dict]:
        """Search products by text query."""
        # Generate query embedding
        query_embedding = self.query_embedder.embed_query(query, context)

        # Build filter
        pinecone_filter = self._build_filter(filters) if filters else None

        # Query Pinecone
        results = self.index.query(
            vector=query_embedding,
            filter=pinecone_filter,
            top_k=limit,
            include_metadata=True,
            namespace="text"
        )

        return self._format_results(results)

    def search_by_image(
        self,
        image: bytes,
        filters: Dict = None,
        limit: int = 20
    ) -> List[Dict]:
        """Search products by image similarity."""
        # Generate image embedding
        image_embedding = self.image_embedder.embed(image)

        # Build filter
        pinecone_filter = self._build_filter(filters) if filters else None

        # Query Pinecone
        results = self.index.query(
            vector=image_embedding,
            filter=pinecone_filter,
            top_k=limit,
            include_metadata=True,
            namespace="image"
        )

        return self._format_results(results)

    def search_similar_products(
        self,
        product_id: str,
        limit: int = 10
    ) -> List[Dict]:
        """Find products similar to a given product."""
        # Fetch the product's embedding
        product_data = self.index.fetch(ids=[product_id], namespace="text")

        if not product_data.vectors:
            return []

        embedding = product_data.vectors[product_id].values

        # Search for similar (excluding the product itself)
        results = self.index.query(
            vector=embedding,
            filter={"product_id": {"$ne": product_id}},
            top_k=limit,
            include_metadata=True,
            namespace="text"
        )

        return self._format_results(results)

    def _build_filter(self, filters: Dict) -> Dict:
        """Convert API filters to Pinecone filter format."""
        pinecone_filter = {}

        if "category" in filters:
            pinecone_filter["category"] = {"$eq": filters["category"]}
        if "brand" in filters:
            pinecone_filter["brand"] = {"$in": filters["brand"]}
        if "price_min" in filters:
            pinecone_filter["price"] = {"$gte": filters["price_min"]}
        if "price_max" in filters:
            if "price" in pinecone_filter:
                pinecone_filter["price"]["$lte"] = filters["price_max"]
            else:
                pinecone_filter["price"] = {"$lte": filters["price_max"]}
        if "in_stock" in filters and filters["in_stock"]:
            pinecone_filter["in_stock"] = {"$eq": True}

        return pinecone_filter if pinecone_filter else None

    def _format_results(self, results) -> List[Dict]:
        """Format Pinecone results."""
        return [
            {
                "product_id": match.id,
                "score": match.score,
                "metadata": match.metadata
            }
            for match in results.matches
        ]

┌─────────────────────────────────────────────────────────────┐
│ VECTOR SEARCH WITH FILTERS                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Query: "running shoes"                                     │
│  Filters: { category: "Running", price_max: 150 }           │
│        │                                                    │
│        ▼                                                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 1. Convert filters to Pinecone format               │   │
│  │    {                                                │   │
│  │      "category": {"$eq": "Running"},                │   │
│  │      "price": {"$lte": 150}                         │   │
│  │    }                                                │   │
│  └─────────────────────────────────────────────────────┘   │
│        │                                                    │
│        ▼                                                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 2. Query Pinecone                                   │   │
│  │    • Embedding vector: [0.12, -0.34, ...]           │   │
│  │    • Filter: {"category": "Running", "price":...}   │   │
│  │    • namespace: "text"                              │   │
│  │    • top_k: 20                                      │   │
│  └─────────────────────────────────────────────────────┘   │
│        │                                                    │
│        ▼                                                    │
│  Results: Only products matching category + price           │
│  + sorted by semantic similarity                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/ranking/scorer.py
from typing import List, Dict
import numpy as np
from dataclasses import dataclass
from ..config import settings

@dataclass
class ScoredProduct:
    product_id: str
    semantic_score: float
    popularity_score: float
    personalization_score: float
    business_score: float
    final_score: float
    metadata: Dict

class HybridScorer:
    """Combines multiple signals for final ranking."""

    def __init__(self):
        self.semantic_weight = settings.semantic_weight
        self.popularity_weight = settings.popularity_weight
        self.personalization_weight = settings.history_weight

    def score_results(
        self,
        semantic_results: List[Dict],
        user_history: List[str] = None,
        popularity_data: Dict = None,
        business_rules: Dict = None
    ) -> List[ScoredProduct]:
        """Score and rank search results."""
        scored = []

        for result in semantic_results:
            product_id = result["product_id"]
            metadata = result.get("metadata", {})

            # Semantic score (from vector search)
            semantic_score = result.get("score", 0)

            # Popularity score
            popularity_score = self._calculate_popularity(
                product_id, popularity_data
            )

            # Personalization score
            personalization_score = self._calculate_personalization(
                product_id, metadata, user_history
            )

            # Business rules score (promotions, margins, etc.)
            business_score = self._apply_business_rules(
                product_id, metadata, business_rules
            )

            # Combined final score
            final_score = (
                semantic_score * self.semantic_weight +
                popularity_score * self.popularity_weight +
                personalization_score * self.personalization_weight +
                business_score * 0.1  # Business rules as small boost
            )

            scored.append(ScoredProduct(
                product_id=product_id,
                semantic_score=semantic_score,
                popularity_score=popularity_score,
                personalization_score=personalization_score,
                business_score=business_score,
                final_score=final_score,
                metadata=metadata
            ))

        # Sort by final score
        scored.sort(key=lambda x: x.final_score, reverse=True)
        return scored

    def _calculate_popularity(
        self,
        product_id: str,
        popularity_data: Dict = None
    ) -> float:
        """Calculate popularity score based on sales/views."""
        if not popularity_data:
            return 0.5

        data = popularity_data.get(product_id, {})
        views = data.get("views", 0)
        purchases = data.get("purchases", 0)
        rating = data.get("rating", 3.0)

        # Normalize and combine signals
        view_score = min(views / 10000, 1.0)
        purchase_score = min(purchases / 1000, 1.0)
        rating_score = rating / 5.0

        return (view_score * 0.3 + purchase_score * 0.4 + rating_score * 0.3)

    def _calculate_personalization(
        self,
        product_id: str,
        metadata: Dict,
        user_history: List[str] = None
    ) -> float:
        """Calculate personalization score based on user history."""
        if not user_history:
            return 0.5

        # Check category affinity
        product_category = metadata.get("category", "")
        category_matches = sum(
            1 for h in user_history
            if h.get("category") == product_category
        )
        category_affinity = min(category_matches / 5, 1.0)

        # Check brand affinity
        product_brand = metadata.get("brand", "")
        brand_matches = sum(
            1 for h in user_history
            if h.get("brand") == product_brand
        )
        brand_affinity = min(brand_matches / 3, 1.0)

        return (category_affinity * 0.6 + brand_affinity * 0.4)

    def _apply_business_rules(
        self,
        product_id: str,
        metadata: Dict,
        business_rules: Dict = None
    ) -> float:
        """Apply business rules for boosting/demoting."""
        if not business_rules:
            return 0

        score = 0

        # Promotional boost
        if product_id in business_rules.get("promoted_products", []):
            score += 0.5

        # New arrivals boost
        if metadata.get("is_new_arrival"):
            score += 0.2

        # Low stock urgency
        stock = metadata.get("stock_quantity", 100)
        if stock < 10:
            score += 0.1

        # Margin optimization
        if metadata.get("high_margin"):
            score += 0.15

        return min(score, 1.0)

┌─────────────────────────────────────────────────────────────┐
│ MULTI-SIGNAL RANKING                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Query: "running shoes"                                     │
│        │                                                    │
│        ▼                                                    │
│  Semantic results (top 40 for reranking):                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Product A: semantic=0.92, popular=0.3, personal=0.2 │   │
│  │ Product B: semantic=0.85, popular=0.9, personal=0.8 │   │
│  │ Product C: semantic=0.88, popular=0.5, personal=0.6 │   │
│  └─────────────────────────────────────────────────────┘   │
│        │                                                    │
│        ▼                                                    │
│  Weighted combination (default weights):                    │
│  • semantic_weight: 0.5                                     │
│  • popularity_weight: 0.2                                   │
│  • personalization_weight: 0.3                              │
│                                                             │
│  Product A: 0.92×0.5 + 0.3×0.2 + 0.2×0.3 = 0.58            │
│  Product B: 0.85×0.5 + 0.9×0.2 + 0.8×0.3 = 0.85 ← WINNER  │
│  Product C: 0.88×0.5 + 0.5×0.2 + 0.6×0.3 = 0.72            │
│                                                             │
│  Pure semantic ranking: A > C > B                           │
│  Hybrid ranking: B > C > A                                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/recommendations/hybrid.py
from typing import List, Dict, Set
import numpy as np
from ..search.semantic_search import SemanticSearch
from ..config import settings

class HybridRecommender:
    """Hybrid recommendation combining content and collaborative signals."""

    def __init__(self):
        self.search = SemanticSearch()

    def get_recommendations(
        self,
        user_id: str,
        user_history: List[Dict],
        current_product: str = None,
        limit: int = 10
    ) -> List[Dict]:
        """Get personalized recommendations."""
        recommendations = []
        seen_products: Set[str] = set()

        # Add products from history to seen set
        for item in user_history:
            seen_products.add(item.get("product_id", ""))

        # Strategy 1: Similar to current product
        if current_product:
            similar = self.search.search_similar_products(
                current_product,
                limit=limit
            )
            for product in similar:
                if product["product_id"] not in seen_products:
                    product["recommendation_reason"] = "similar_to_current"
                    recommendations.append(product)
                    seen_products.add(product["product_id"])

        # Strategy 2: Based on recent views
        if user_history:
            recent_products = user_history[-5:]  # Last 5 viewed
            for recent in recent_products:
                similar = self.search.search_similar_products(
                    recent["product_id"],
                    limit=3
                )
                for product in similar:
                    if product["product_id"] not in seen_products:
                        product["recommendation_reason"] = "based_on_history"
                        recommendations.append(product)
                        seen_products.add(product["product_id"])

        # Strategy 3: Category exploration
        if user_history:
            # Find underexplored categories
            viewed_categories = [h.get("category") for h in user_history]
            category_counts = {}
            for cat in viewed_categories:
                category_counts[cat] = category_counts.get(cat, 0) + 1

            # Get popular items from less-viewed categories
            # (simplified - in production would query category stats)

        # Deduplicate and limit
        unique_recs = []
        seen_ids = set()
        for rec in recommendations:
            if rec["product_id"] not in seen_ids:
                unique_recs.append(rec)
                seen_ids.add(rec["product_id"])
            if len(unique_recs) >= limit:
                break

        return unique_recs

    def get_frequently_bought_together(
        self,
        product_id: str,
        co_purchase_data: Dict,
        limit: int = 5
    ) -> List[Dict]:
        """Get products frequently bought together."""
        co_purchases = co_purchase_data.get(product_id, [])

        # Sort by frequency
        sorted_products = sorted(
            co_purchases,
            key=lambda x: x["frequency"],
            reverse=True
        )

        return sorted_products[:limit]

    def get_trending_in_category(
        self,
        category: str,
        trending_data: Dict,
        limit: int = 10
    ) -> List[Dict]:
        """Get trending products in a category."""
        category_trending = trending_data.get(category, [])
        return category_trending[:limit]

┌─────────────────────────────────────────────────────────────┐
│ HYBRID RECOMMENDATION ENGINE                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  User viewing: Nike Air Max 90                              │
│  History: [Adidas Ultraboost, Nike Zoom, Brooks Ghost]      │
│        │                                                    │
│        ├───────── Strategy 1 ─────────┐                    │
│        │  Similar to Current          │                    │
│        │  • Find products similar to  │                    │
│        │    Air Max 90 via embeddings │                    │
│        │  • Reason: "similar_to_current"│                  │
│        │                              │                    │
│        ├───────── Strategy 2 ─────────┤                    │
│        │  Based on History            │                    │
│        │  • For each of last 5 viewed │                    │
│        │  • Find 3 similar products   │                    │
│        │  • Reason: "based_on_history"│                    │
│        │                              │                    │
│        └───────── Strategy 3 ─────────┘                    │
│           Category Exploration                              │
│           • Find underexplored categories                   │
│           • Surface trending items there                    │
│           • Prevents filter bubbles                         │
│                                                             │
│  Deduplication:                                             │
│  • Track seen_products set                                  │
│  • Skip products already viewed                             │
│  • Return unique recommendations                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# src/api/main.py
from fastapi import FastAPI, HTTPException, Query, UploadFile, File
from pydantic import BaseModel
from typing import Optional, List
import redis.asyncio as redis

from ..search.semantic_search import SemanticSearch
from ..ranking.scorer import HybridScorer
from ..recommendations.hybrid import HybridRecommender
from ..config import settings

app = FastAPI(
    title="Product Discovery API",
    description="Semantic search and recommendations for e-commerce"
)

# Initialize components
search = SemanticSearch()
scorer = HybridScorer()
recommender = HybridRecommender()
redis_client = redis.from_url(settings.redis_url)

class SearchRequest(BaseModel):
    query: str
    filters: Optional[dict] = None
    limit: int = 20
    user_id: Optional[str] = None

class SearchResult(BaseModel):
    product_id: str
    score: float
    name: str
    brand: str
    price: float
    image_url: str
    category: str

class SearchResponse(BaseModel):
    results: List[SearchResult]
    total: int
    query: str

@app.post("/search", response_model=SearchResponse)
async def search_products(request: SearchRequest):
    """Search products by text query."""
    # Get user history if available
    user_history = None
    if request.user_id:
        history_key = f"user_history:{request.user_id}"
        history_data = await redis_client.get(history_key)
        if history_data:
            import json
            user_history = json.loads(history_data)

    # Semantic search
    semantic_results = search.search_by_text(
        query=request.query,
        filters=request.filters,
        limit=request.limit * 2  # Get more for reranking
    )

    # Hybrid scoring
    scored_results = scorer.score_results(
        semantic_results,
        user_history=user_history
    )

    # Format response
    results = [
        SearchResult(
            product_id=r.product_id,
            score=r.final_score,
            name=r.metadata.get("name", ""),
            brand=r.metadata.get("brand", ""),
            price=r.metadata.get("price", 0),
            image_url=r.metadata.get("image_url", ""),
            category=r.metadata.get("category", "")
        )
        for r in scored_results[:request.limit]
    ]

    return SearchResponse(
        results=results,
        total=len(results),
        query=request.query
    )

@app.post("/search/image")
async def search_by_image(
    image: UploadFile = File(...),
    limit: int = Query(default=20, le=100)
):
    """Search products by image similarity."""
    image_bytes = await image.read()

    results = search.search_by_image(
        image=image_bytes,
        limit=limit
    )

    return {"results": results}

@app.get("/recommendations/{user_id}")
async def get_recommendations(
    user_id: str,
    current_product: Optional[str] = None,
    limit: int = 10
):
    """Get personalized recommendations."""
    # Get user history
    history_key = f"user_history:{user_id}"
    history_data = await redis_client.get(history_key)
    user_history = []
    if history_data:
        import json
        user_history = json.loads(history_data)

    recommendations = recommender.get_recommendations(
        user_id=user_id,
        user_history=user_history,
        current_product=current_product,
        limit=limit
    )

    return {"recommendations": recommendations}

@app.get("/similar/{product_id}")
async def get_similar_products(
    product_id: str,
    limit: int = 10
):
    """Get products similar to a given product."""
    results = search.search_similar_products(product_id, limit)
    return {"similar_products": results}

@app.post("/track/view")
async def track_product_view(user_id: str, product_id: str, category: str):
    """Track product view for personalization."""
    history_key = f"user_history:{user_id}"

    # Get existing history
    history_data = await redis_client.get(history_key)
    history = []
    if history_data:
        import json
        history = json.loads(history_data)

    # Add new view
    history.append({
        "product_id": product_id,
        "category": category,
        "timestamp": "now"
    })

    # Keep last 100 views
    history = history[-100:]

    # Save back
    import json
    await redis_client.set(history_key, json.dumps(history), ex=86400 * 30)

    return {"status": "tracked"}

@app.get("/health")
async def health():
    return {"status": "healthy"}

# docker-compose.yml
version: '3.8'

services:
  discovery-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - PINECONE_API_KEY=${PINECONE_API_KEY}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  indexer:
    build: .
    command: python scripts/index_products.py
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - PINECONE_API_KEY=${PINECONE_API_KEY}

volumes:
  redis_data: