Deploy FastAPI backend

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# System deps for curl (healthcheck)
+RUN apt-get update && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Step 1: Install CPU-only PyTorch (prevents 3GB download) ──
+RUN pip install --no-cache-dir \
+    torch==2.2.2 \
+    --index-url https://download.pytorch.org/whl/cpu
+
+# ── Step 2: Install remaining Python dependencies ─────────────
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# ── Step 3: Copy application source ───────────────────────────
+COPY app/ ./app/
+COPY workers/ ./workers/
+
+# Ensure the root directory is in the python path
+ENV PYTHONPATH=/app
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,67 @@
 ---
-title: Ecommerce
-emoji: 😻
-colorFrom: red
+title: CommercePulse Backend
+emoji: 📈
+colorFrom: blue
 colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CommercePulse Ingestion & Analytics API - Hugging Face Spaces Deployment
+
+## 🚀 Deployment Steps (Hugging Face Spaces)
+
+### 1. Create a Space on Hugging Face
+1. Go to [Hugging Face Spaces](https://huggingface.co/spaces) and click **Create new Space**.
+2. Set your **Space Name** (e.g., `commercepulse-backend`).
+3. Select **Docker** as the SDK.
+4. Select the **Blank** template.
+5. Select **CPU Basic (Free)** as the hardware tier.
+6. Set the visibility to **Public** (required for the free tier).
+7. Click **Create Space**.
+
+### 2. Configure Secrets in Space Settings
+Go to your Space's **Settings** > **Variables and secrets** and click **New secret** to add:
+- `DATABASE_URL`: Your Supabase connection string.
+- `GROQ_API_KEY`: Your Groq API key for LLM tasks.
+- `API_KEY`: Your custom security API key (e.g., `dev-api-key`).
+
+### 3. Initialize Git & Push Code
+You can push this directory to Hugging Face's Git repository.
+
+Open your terminal, navigate to this `backend` folder, and run:
+```bash
+# Initialize git if not already initialized in this directory
+# (Or check out the Space repo and copy these files into it)
+git init
+git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+
+# Stage and commit the backend files
+git add app/ workers/ requirements.txt Dockerfile README.md
+git commit -m "Deploy FastAPI backend to Hugging Face"
+
+# Push to Hugging Face (will trigger automatic Docker build & deploy)
+git push -f hf main
+```
+
+*(Note: Hugging Face uses your Hugging Face username and an [Access Token](https://huggingface.co/settings/tokens) as your git password when pushing.)*
+
+## 🐳 Docker Customizations
+
+The included [Dockerfile](./Dockerfile) is pre-configured to build the app, load the CPU-only PyTorch library efficiently, and start Uvicorn.
+
+To set the port Hugging Face binds to, Hugging Face reads metadata from the top of the repository's `README.md`. Hugging Face will read this file's YAML header:
+
+```yaml
+---
+title: CommercePulse Backend
+emoji: 📈
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 8000
+pinned: false
+---
+```
+*(Keep this block at the very top of the `README.md` file in the root of the Hugging Face Space).*

app/core/config.py

@@ -0,0 +1,96 @@
+"""Application settings via Pydantic BaseSettings."""
+from urllib.parse import quote_plus
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    # PostgreSQL Connection String / URI (takes precedence if provided)
+    DATABASE_URL:      str = ""
+
+    # Individual PostgreSQL Settings (fallback)
+    POSTGRES_HOST:     str = "localhost"
+    POSTGRES_PORT:     int = 5432
+    POSTGRES_DB:       str = "commercepulse"
+    POSTGRES_USER:     str = "commercepulse"
+    POSTGRES_PASSWORD: str = "changeme"
+
+    # Application
+    APP_ENV:  str = "development"
+    API_KEY: str = Field(..., env="API_KEY")
+    CORS_ORIGINS: list[str] = ["http://localhost:3000", "http://localhost:4000", "http://127.0.0.1:4000", "http://127.0.0.1:3000"]
+
+    # Redis (Celery broker/result backend)
+    REDIS_URL: str = "redis://localhost:6379/0"
+
+    # Embedding model
+    EMBEDDING_MODEL: str = "all-MiniLM-L6-v2"
+    EMBEDDING_DIMS:  int = 384
+
+    # AI Agents API (runs by default on 8001 locally to avoid clash)
+    AI_AGENTS_URL: str = "http://localhost:8001"
+    
+    # Groq API Key
+    GROQ_API_KEY: str = Field(..., env="GROQ_API_KEY")
+
+    @property
+    def _pw(self) -> str:
+        """URL-encode the password so special chars (@ % : /) don't break the DSN."""
+        return quote_plus(self.POSTGRES_PASSWORD)
+
+    @property
+    def async_db_url(self) -> str:
+        if self.DATABASE_URL:
+            url = self.DATABASE_URL
+            if url.startswith("postgresql://"):
+                url = url.replace("postgresql://", "postgresql+asyncpg://", 1)
+            elif url.startswith("postgres://"):
+                url = url.replace("postgres://", "postgresql+asyncpg://", 1)
+            
+            # Ensure SSL is appended for remote databases like Supabase
+            if "supabase.co" in url or "supabase.com" in url:
+                if "?" in url:
+                    if "ssl" not in url:
+                        url += "&ssl=require"
+                else:
+                    url += "?ssl=require"
+            return url
+
+        base = (
+            f"postgresql+asyncpg://{self.POSTGRES_USER}:{self._pw}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+        if "supabase.co" in self.POSTGRES_HOST:
+            base += "?ssl=require"
+        return base
+
+    @property
+    def sync_db_url(self) -> str:
+        if self.DATABASE_URL:
+            url = self.DATABASE_URL
+            if url.startswith("postgresql://"):
+                url = url.replace("postgresql://", "postgresql+psycopg2://", 1)
+            elif url.startswith("postgres://"):
+                url = url.replace("postgres://", "postgresql+psycopg2://", 1)
+                
+            if "supabase.co" in url or "supabase.com" in url:
+                if "?" in url:
+                    if "sslmode" not in url:
+                        url += "&sslmode=require"
+                else:
+                    url += "?sslmode=require"
+            return url
+
+        base = (
+            f"postgresql+psycopg2://{self.POSTGRES_USER}:{self._pw}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+        if "supabase.co" in self.POSTGRES_HOST:
+            base += "?sslmode=require"
+        return base
+
+
+settings = Settings()
+

app/core/security.py

@@ -0,0 +1,85 @@
+"""Simple API key auth, seller scoping, and rate limiting dependencies."""
+import time
+from collections import defaultdict, deque
+from typing import Deque, Dict
+
+from fastapi import Depends, Header, HTTPException, status
+
+from app.core.config import settings
+
+
+# ── API Key Auth ─────────────────────────────────────────────────
+async def require_api_key(x_api_key: str = Header(..., alias="X-API-Key")) -> str:
+    """Require X-API-Key header to match configured API key."""
+    if not settings.API_KEY:
+        # Misconfiguration on server; fail closed.
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="API key not configured on server",
+        )
+    if x_api_key != settings.API_KEY:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid API key",
+        )
+    return x_api_key
+
+
+# ── Seller scope enforcement ────────────────────────────────────
+async def enforce_seller_scope(
+    seller_id: str | None = None,
+    x_seller_id: str | None = Header(None, alias="X-Seller-Id"),
+) -> str:
+    """
+    Best-effort multi-tenant safety.
+
+    - If X-Seller-Id header is provided, it MUST match the seller_id
+      parameter used in the route (prevents a client from querying a
+      different seller's data when the UI is correctly wiring headers).
+    - If the header is absent, the call is allowed (for backwards
+      compatibility), but you should prefer always sending X-Seller-Id
+      from the authenticated context on the frontend.
+    """
+    # For form-based routes (e.g. /upload/full), seller_id comes via Form()
+    # and is invisible to this dependency. In that case seller_id is None,
+    # but x_seller_id is set from the header — just trust the header.
+    if seller_id is None:
+        return x_seller_id  # may also be None, which is fine (no scope)
+
+    if x_seller_id is not None and x_seller_id != seller_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Seller scope violation",
+        )
+    return seller_id
+
+
+# ── In-memory rate limiting (best-effort) ────────────────────────
+_REQUEST_LOGS: Dict[str, Deque[float]] = defaultdict(deque)
+
+
+def rate_limiter(max_requests: int, window_seconds: int):
+    """
+    Returns a dependency that enforces a simple sliding-window
+    limit per API key. Best-effort only (per-process, not shared
+    across multiple replicas).
+    """
+
+    async def _limit(x_api_key: str = Depends(require_api_key)) -> None:
+        now = time.time()
+        q = _REQUEST_LOGS[x_api_key]
+
+        # Drop entries outside the window
+        while q and now - q[0] > window_seconds:
+            q.popleft()
+
+        if len(q) >= max_requests:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Try again later.",
+            )
+
+        q.append(now)
+
+    return _limit
+

app/db/session.py

@@ -0,0 +1,41 @@
+"""Async SQLAlchemy engine + session factory."""
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+from app.core.config import settings
+
+engine = create_async_engine(
+    settings.async_db_url,
+    pool_size=settings.DB_POOL_SIZE if hasattr(settings, "DB_POOL_SIZE") else 5,
+    max_overflow=settings.DB_MAX_OVERFLOW if hasattr(settings, "DB_MAX_OVERFLOW") else 10,
+    pool_timeout=30,
+    pool_pre_ping=True, # Automatically checks if connection is alive before using it
+    pool_recycle=1800,  # Recycle connections after 30 minutes to prevent timeouts
+    echo=settings.APP_ENV == "development",
+    connect_args={
+        "statement_cache_size": 0
+    }
+)
+
+AsyncSessionLocal = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+class Base(DeclarativeBase):
+    """SQLAlchemy declarative base — all ORM models inherit from this."""
+    pass
+
+
+async def get_db():
+    """FastAPI dependency: yields an async DB session."""
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()

app/main.py

@@ -0,0 +1,135 @@
+"""
+CommercePulse MVP — FastAPI Application Entry Point
+"""
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.db.session import engine
+from app.core.config import settings
+from app.routes import upload, analytics, ai, sellers, tasks, websockets
+
+
+# ── Lifespan (startup / shutdown) ─────────────────────────────
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Run startup tasks, then yield, then shutdown tasks."""
+    # Ensure the HuggingFace model is pre-loaded to avoid cold-start latency
+    # on the first recommendation request.
+    try:
+        from app.services.embeddings import embedding_service
+        await embedding_service.preload()
+    except Exception as exc:
+        print(f"[WARNING] Could not preload embedding model: {exc}")
+        
+    # Auto-create missing tables (like AIProductAnalysis) without Alembic
+    try:
+        from app.models.models import Base
+        from sqlalchemy import text
+        async with engine.connect() as conn:
+            # Must run outside of a transaction block. On some systems execution_options is a coroutine.
+            conn = await conn.execution_options(isolation_level="AUTOCOMMIT")
+            await conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
+        
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+            print("[INFO] Database tables ensured.")
+    except Exception as exc:
+        print(f"[WARNING] Could not auto-create tables: {exc}")
+        
+    # Initialize Redis caching (with InMemory fallback)
+    from fastapi_cache import FastAPICache
+    from fastapi_cache.backends.redis import RedisBackend
+    from fastapi_cache.backends.inmemory import InMemoryBackend
+    import redis.asyncio as aioredis
+    
+    try:
+        import asyncio
+        redis_client = aioredis.from_url(
+            settings.REDIS_URL, 
+            encoding="utf-8", 
+            decode_responses=False,
+            socket_connect_timeout=2.0
+        )
+        # Ping to verify connection, force timeout
+        await asyncio.wait_for(redis_client.ping(), timeout=2.0)
+        FastAPICache.init(RedisBackend(redis_client), prefix="fastapi-cache")
+        print("[INFO] Redis cache initialized.")
+    except Exception as exc:
+        print(f"[WARNING] Redis unreachable, falling back to in-memory cache: {exc}")
+        FastAPICache.init(InMemoryBackend(), prefix="fastapi-cache")
+        
+    # Start the WebSocket Redis Pub/Sub listener (optional/best-effort)
+    import asyncio
+    from app.routes.websockets import manager
+    try:
+        asyncio.create_task(manager.listen_to_redis())
+    except Exception:
+        print("[WARNING] Could not start Redis Pub/Sub listener.")
+        
+    yield
+    await engine.dispose()
+
+
+# ── App instance ───────────────────────────────────────────────
+app = FastAPI(
+    title="CommercePulse Ingestion & Analytics API",
+    version="1.0.0",
+    description=(
+        "Multi-marketplace commerce intelligence platform. "
+        "Ingest structured Excel snapshots across 5 domains, "
+        "run analytics, and query the pgvector AI memory layer."
+    ),
+    lifespan=lifespan,
+)
+
+import time
+import logging
+
+logger = logging.getLogger("api_requests")
+
+@app.middleware("http")
+async def log_requests(request: Request, call_next):
+    start_time = time.time()
+    response = await call_next(request)
+    duration = time.time() - start_time
+    logger.info(f"[{request.method}] {request.url.path} - {response.status_code} ({duration:.2f}s)")
+    return response
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.CORS_ORIGINS if hasattr(settings, "CORS_ORIGINS") and settings.APP_ENV != "production" else ["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Routers ───────────────────────────────────────────────────
+app.include_router(websockets.router, tags=["WebSockets"])
+app.include_router(sellers.router,   prefix="/sellers",   tags=["Sellers"])
+app.include_router(upload.router,    prefix="/upload",    tags=["Excel Upload"])
+app.include_router(analytics.router, prefix="/analytics", tags=["Analytics"])
+app.include_router(ai.router,        prefix="/ai",        tags=["AI Brain"])
+app.include_router(tasks.router,     prefix="/tasks",     tags=["Tasks"])
+
+
+# ── Health check ──────────────────────────────────────────────
+@app.get("/health", tags=["System"])
+async def health():
+    # Basic service info
+    payload = {
+        "status": "ok",
+        "service": "CommercePulse Ingestion API",
+        "version": "1.0.0",
+        "env": settings.APP_ENV,
+    }
+    # Best-effort Celery/Redis health
+    try:
+        from app.services.tasks import ping
+        res = ping.delay()
+        pong = res.get(timeout=1.0)
+        payload["celery"] = "ok" if pong == "pong" else "error"
+    except Exception:
+        payload["celery"] = "error"
+
+    return payload

app/models/models.py

@@ -0,0 +1,217 @@
+"""SQLAlchemy ORM models for all CommercePulse tables."""
+import uuid
+from datetime import date, datetime
+from typing import Optional
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import (
+    Boolean, Column, Date, DateTime, ForeignKey,
+    Integer, Numeric, String, Text, BigInteger, JSON,
+    UniqueConstraint, func,
+)
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from app.db.session import Base
+
+
+# ── helpers ────────────────────────────────────────────────────
+def now():
+    return datetime.utcnow()
+
+def new_uuid():
+    return str(uuid.uuid4())
+
+
+# ── Seller ─────────────────────────────────────────────────────
+class Seller(Base):
+    __tablename__ = "sellers"
+
+    seller_id   = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    seller_name = Column(Text, nullable=False, index=True)
+    marketplace = Column(Text, nullable=False, default="multi")
+    region      = Column(Text, nullable=False, default="IN")
+    email       = Column(Text, unique=True, index=True)
+    is_active   = Column(Boolean, nullable=False, default=True)
+    created_at  = Column(DateTime(timezone=True), server_default=func.now())
+
+    products   = relationship("Product", back_populates="seller", lazy="selectin")
+
+
+# ── Product ────────────────────────────────────────────────────
+class Product(Base):
+    __tablename__ = "products"
+    __table_args__ = (UniqueConstraint("seller_id", "sku", "marketplace"),)
+
+    product_id   = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    seller_id    = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False, index=True)
+    sku          = Column(Text, nullable=False, index=True)
+    product_name = Column(Text, nullable=False, index=True)
+    category     = Column(Text, index=True)
+    sub_category = Column(Text)
+    brand        = Column(Text)
+    marketplace  = Column(Text)
+    is_active    = Column(Boolean, nullable=False, default=True)
+    created_at   = Column(DateTime(timezone=True), server_default=func.now())
+
+    seller     = relationship("Seller", back_populates="products")
+
+
+# ── Order ──────────────────────────────────────────────────────
+class Order(Base):
+    __tablename__ = "orders"
+
+    order_id            = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    external_order_id   = Column(Text, unique=True, index=True)  # must be unique for ON CONFLICT upsert
+    seller_id           = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False, index=True)
+    product_id          = Column(UUID(as_uuid=True), ForeignKey("products.product_id", ondelete="SET NULL"), index=True)
+    marketplace         = Column(Text, nullable=False, index=True)
+    order_status        = Column(Text, nullable=False, index=True)
+    quantity            = Column(Integer, nullable=False, default=1)
+    selling_price       = Column(Numeric(12, 2), nullable=False)
+    discount            = Column(Numeric(12, 2), default=0)
+    tax                 = Column(Numeric(12, 2), default=0)
+    shipping_fee        = Column(Numeric(12, 2), nullable=True, default=0)
+    order_date          = Column(Date, nullable=False, index=True)
+    delivery_date       = Column(Date)
+    return_flag         = Column(Boolean, default=False, index=True)
+    cancellation_reason = Column(Text)
+    customer_name       = Column(Text)    # may be NULL if dataset lacks this column
+    customer_email      = Column(Text)
+    payment_mode        = Column(Text)
+    snapshot_date       = Column(Date, nullable=False, default=date.today, index=True)
+    created_at          = Column(DateTime(timezone=True), server_default=func.now())
+
+
+# ── InventorySnapshot ──────────────────────────────────────────
+class InventorySnapshot(Base):
+    __tablename__  = "inventory_snapshots"
+    __table_args__ = (UniqueConstraint("seller_id", "product_id", "marketplace", "snapshot_date"),)
+
+    id                = Column(BigInteger, primary_key=True, autoincrement=True)
+    seller_id         = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False, index=True)
+    product_id        = Column(UUID(as_uuid=True), ForeignKey("products.product_id", ondelete="CASCADE"), nullable=False, index=True)
+    marketplace       = Column(Text, nullable=False, index=True)
+    available_stock   = Column(Integer, nullable=False, default=0)
+    reserved_stock    = Column(Integer, nullable=False, default=0)
+    reorder_threshold = Column(Integer, default=10)
+    days_of_stock     = Column(Numeric(6, 1))
+    warehouse_location= Column(Text)
+    snapshot_date     = Column(Date, nullable=False, default=date.today, index=True)
+    created_at        = Column(DateTime(timezone=True), server_default=func.now())
+
+
+# ── PricingSnapshot ────────────────────────────────────────────
+class PricingSnapshot(Base):
+    __tablename__  = "pricing_snapshots"
+    __table_args__ = (UniqueConstraint("seller_id", "product_id", "marketplace", "snapshot_date"),)
+
+    id                  = Column(BigInteger, primary_key=True, autoincrement=True)
+    seller_id           = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False, index=True)
+    product_id          = Column(UUID(as_uuid=True), ForeignKey("products.product_id", ondelete="CASCADE"), nullable=False, index=True)
+    marketplace         = Column(Text, nullable=False, index=True)
+    selling_price       = Column(Numeric(12, 2), nullable=False)
+    cost_price          = Column(Numeric(12, 2))
+    mrp                 = Column(Numeric(12, 2))
+    commission_pct      = Column(Numeric(5, 2), default=0)
+    commission_amount   = Column(Numeric(12, 2), default=0)
+    discount_percentage = Column(Numeric(5, 2), default=0)
+    snapshot_date       = Column(Date, nullable=False, default=date.today, index=True)
+    created_at          = Column(DateTime(timezone=True), server_default=func.now())
+
+
+# ── TrafficMetric ──────────────────────────────────────────────
+class TrafficMetric(Base):
+    __tablename__  = "traffic_metrics"
+    __table_args__ = (UniqueConstraint("seller_id", "product_id", "marketplace", "metric_date"),)
+
+    id               = Column(BigInteger, primary_key=True, autoincrement=True)
+    seller_id        = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False, index=True)
+    product_id       = Column(UUID(as_uuid=True), ForeignKey("products.product_id", ondelete="CASCADE"), nullable=False, index=True)
+    marketplace      = Column(Text, nullable=False, index=True)
+    metric_date      = Column(Date, nullable=False, default=date.today, index=True)
+    impressions      = Column(Integer, default=0)
+    clicks           = Column(Integer, default=0)
+    sessions         = Column(Integer, default=0)
+    page_views       = Column(Integer, default=0)
+    orders           = Column(Integer, default=0)
+    ad_spend         = Column(Numeric(12, 2), default=0)
+    revenue_from_ads = Column(Numeric(12, 2), default=0)
+    created_at       = Column(DateTime(timezone=True), server_default=func.now())
+
+
+# ── LogisticsMetric ────────────────────────────────────────────
+class LogisticsMetric(Base):
+    __tablename__ = "logistics_metrics"
+    __table_args__ = (UniqueConstraint("seller_id", "tracking_id", "marketplace", "snapshot_date"),)
+
+    id                 = Column(BigInteger, primary_key=True, autoincrement=True)
+    order_id           = Column(UUID(as_uuid=True), ForeignKey("orders.order_id", ondelete="SET NULL"))
+    seller_id          = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False)
+    marketplace        = Column(Text, nullable=False)
+    courier_name       = Column(Text)
+    tracking_id        = Column(Text)
+    fulfillment_type   = Column(Text, default="seller")
+    warehouse_id       = Column(Text)
+    dispatch_date      = Column(Date)
+    expected_delivery  = Column(Date)
+    actual_delivery    = Column(Date)
+    delivery_status    = Column(Text, nullable=False)
+    rto_flag           = Column(Boolean, default=False)
+    rto_reason         = Column(Text)
+    snapshot_date      = Column(Date, nullable=False, default=date.today)
+    created_at         = Column(DateTime(timezone=True), server_default=func.now())
+
+
+# ── ProductEmbedding ──────────────────────────────────────────
+class ProductEmbedding(Base):
+    __tablename__  = "product_embeddings"
+    __table_args__ = (UniqueConstraint("seller_id", "product_id", "embed_date", "embed_type"),)
+
+    id           = Column(BigInteger, primary_key=True, autoincrement=True)
+    seller_id    = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False)
+    product_id   = Column(UUID(as_uuid=True), ForeignKey("products.product_id", ondelete="CASCADE"), nullable=False)
+    embed_date   = Column(Date, nullable=False, default=date.today)
+    embed_type   = Column(Text, nullable=False, default="daily_snapshot")
+    summary_text = Column(Text, nullable=False)
+    embedding    = Column(Vector(384), nullable=False)
+    meta         = Column("metadata", JSON, default=dict)
+    created_at   = Column(DateTime(timezone=True), server_default=func.now())
+
+
+# ── InsightEmbedding ──────────────────────────────────────────
+class InsightEmbedding(Base):
+    __tablename__ = "insight_embeddings"
+
+    id           = Column(BigInteger, primary_key=True, autoincrement=True)
+    seller_id    = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False)
+    insight_date = Column(Date, nullable=False, default=date.today)
+    insight_type = Column(Text, nullable=False)
+    insight_text = Column(Text, nullable=False)
+    embedding    = Column(Vector(384), nullable=False)
+    meta         = Column("metadata", JSON, default=dict)
+    created_at   = Column(DateTime(timezone=True), server_default=func.now())
+
+
+# ── AIProductAnalysis ──────────────────────────────────────────
+class AIProductAnalysis(Base):
+    __tablename__  = "ai_product_analyses"
+    __table_args__ = (UniqueConstraint("seller_id", "product_id", "analysis_date"),)
+
+    id                 = Column(BigInteger, primary_key=True, autoincrement=True)
+    seller_id          = Column(UUID(as_uuid=True), ForeignKey("sellers.seller_id", ondelete="CASCADE"), nullable=False)
+    product_id         = Column(UUID(as_uuid=True), ForeignKey("products.product_id", ondelete="CASCADE"), nullable=False)
+    analysis_date      = Column(Date, nullable=False, default=date.today)
+    
+    product_metrics    = Column(JSON, nullable=False, default=dict)
+    revenue_insights   = Column(JSON)
+    ops_insights       = Column(JSON)
+    marketing_insights = Column(JSON)
+    market_insights    = Column(JSON)
+    executive_summary  = Column(JSON)
+    
+    status             = Column(Text, nullable=False, default="pending")
+    error_message      = Column(Text)
+    
+    created_at         = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at         = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())

app/routes/ai.py

@@ -0,0 +1,551 @@
+"""AI Brain routes — /ai/*"""
+from datetime import date
+from typing import Optional
+import logging
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.session import get_db
+from app.core.security import rate_limiter, enforce_seller_scope
+from app.services.embeddings import embedding_service
+from app.services.tasks import auto_embed as auto_embed_task
+from app.services.tasks import embed_single_product as embed_single_product_task
+
+router = APIRouter(
+    dependencies=[Depends(rate_limiter(max_requests=120, window_seconds=60))],
+)
+logger = logging.getLogger(__name__)
+
+# ── AI Business Analyst Chat ──────────────────────────────────
+from pydantic import BaseModel
+from fastapi import HTTPException
+import httpx
+from app.core.config import settings
+
+class ChatRequest(BaseModel):
+    message: str
+    history: list = []
+    context: dict = {}
+
+@router.post("/chat", summary="Chat with the AI Business Analyst")
+async def ai_chat(
+    request: ChatRequest,
+    seller_id: str = Query(...),
+    db: AsyncSession = Depends(get_db),
+    _scope: str = Depends(enforce_seller_scope),
+):
+    api_key = settings.GROQ_API_KEY
+    if not api_key:
+        logger.error("No GROQ_API_KEY configured")
+        raise HTTPException(status_code=500, detail="LLM configuration missing")
+    
+    ctx = request.context
+    context_str = f"""
+- Total Revenue (Current Available Data): ₹{ctx.get('total_revenue', 0):,}
+- Total Orders: {ctx.get('total_orders', 0)}
+- Return Rate: {ctx.get('return_rate_pct', 0)}%
+- Avg Margin: {ctx.get('avg_margin_pct', 0)}%
+- Avg ROAS: {ctx.get('avg_roas', 0)}
+"""
+    
+    system_prompt = f"""You are an elite, highly aggressive Senior Business Analyst & Strategist for a D2C brand named "Brew Boulevard". 
+Your job is to answer the user's questions strictly based on their real data.
+Be concise, highly professional, use bullet points if needed, and reference actual Rs amounts, percentages, and units.
+
+Here is the LIVE DATA context for Brew Boulevard:
+{context_str}
+
+Rules:
+1. Do not hallucinate metrics. Assume the LIVE DATA provided is the most current and relevant data for the user's query (even if they ask about "this month" or "recently"). Do not complain about missing data for specific timeframes.
+2. Be aggressive about growth and protecting margins. Focus on profitability, ROAS optimization, and high-impact actions.
+3. Keep responses under 200 words unless explaining a complex multi-step strategy.
+4. Always reference actual financial numbers (Rs amounts) to back up your claims.
+5. Provide extremely actionable, data-driven advice for D2C scaling."""
+
+    messages = [{"role": "system", "content": system_prompt}]
+    
+    for msg in request.history:
+        messages.append({
+            "role": "assistant" if msg.get("type") == "ai" else "user",
+            "content": msg.get("text", "")
+        })
+        
+    messages.append({"role": "user", "content": request.message})
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.post(
+                "https://api.groq.com/openai/v1/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json"
+                },
+                json={
+                    "model": "llama-3.3-70b-versatile",
+                    "messages": messages,
+                    "temperature": 0.2,
+                    "max_tokens": 800,
+                },
+                timeout=45.0
+            )
+            response.raise_for_status()
+            data = response.json()
+            return {"reply": data["choices"][0]["message"]["content"]}
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 429:
+                logger.warning("70b rate limit hit, falling back to 8b-instant")
+                try:
+                    fallback_response = await client.post(
+                        "https://api.groq.com/openai/v1/chat/completions",
+                        headers={
+                            "Authorization": f"Bearer {api_key}",
+                            "Content-Type": "application/json"
+                        },
+                        json={
+                            "model": "llama-3.1-8b-instant",
+                            "messages": messages,
+                            "temperature": 0.2,
+                            "max_tokens": 800,
+                        },
+                        timeout=45.0
+                    )
+                    fallback_response.raise_for_status()
+                    data = fallback_response.json()
+                    return {"reply": data["choices"][0]["message"]["content"]}
+                except Exception as fallback_err:
+                    logger.error(f"Groq API Error on fallback: {str(fallback_err)}")
+                    raise HTTPException(status_code=500, detail=str(fallback_err))
+            else:
+                logger.error(f"Groq API Error: {str(e)}")
+                raise HTTPException(status_code=500, detail=str(e))
+        except Exception as e:
+            logger.error(f"Groq API Error: {str(e)}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+
+# ── Embed a single product snapshot ───────────────────────────
+@router.post("/embed/product", summary="Embed one product's daily performance summary (async via Celery)")
+async def embed_product(
+    seller_id:  str,
+    product_id: str,
+    summary:    str,
+    embed_date: Optional[str] = None,
+    embed_type: str = "daily_snapshot",
+    db:         AsyncSession = Depends(get_db),
+    _scope:     str         = Depends(enforce_seller_scope),
+):
+    """
+    Enqueue a Celery job to embed a single product summary.
+    The HTTP request returns immediately with a task_id.
+    """
+    # We still accept a DB session for consistency / future auditing, but do not use it here.
+    d_str = embed_date if embed_date else str(date.today())
+    res = embed_single_product_task.delay(seller_id, product_id, summary, d_str, embed_type)
+    logger.info(
+        "[AI] Enqueued embed_single_product task_id=%s seller_id=%s product_id=%s date=%s",
+        res.id,
+        seller_id,
+        product_id,
+        d_str,
+    )
+    return {
+        "status": "queued",
+        "task_id": res.id,
+        "product_id": product_id,
+        "date": d_str,
+    }
+
+
+# ── Auto-embed (fast batch version) ───────────────────────────
+@router.post("/embed/auto", summary="Auto-generate embeddings from latest ingested data (batch, async via Celery)")
+async def auto_embed(
+    seller_id:  str,
+    snap_date:  Optional[str] = None,
+    db:         AsyncSession = Depends(get_db),
+    _scope:     str         = Depends(enforce_seller_scope),
+):
+    """
+    Enqueue the batch auto-embed Celery job.
+    Reuses the same logic as upload-triggered embedding.
+    """
+    # We accept snap_date in the same format the Celery task expects (YYYY-MM-DD).
+    d_str = snap_date if snap_date else str(date.today())
+    res = auto_embed_task.delay(seller_id, d_str)
+    logger.info(
+        "[AI] Enqueued auto_embed (manual) task_id=%s seller_id=%s date=%s",
+        res.id,
+        seller_id,
+        d_str,
+    )
+    return {"status": "queued", "task_id": res.id, "seller_id": seller_id, "date": d_str}
+
+
+# ── Similar products ──────────────────────────────────────────
+@router.get("/similar-products", summary="Find similar products via pgvector cosine similarity")
+async def similar_products(
+    seller_id:  str,
+    query:      str = Query(..., description="Natural language query, e.g. 'high ROAS electronics'"),
+    limit:      int = Query(5, ge=1, le=20),
+    embed_type: str = Query("daily_snapshot"),
+    db:         AsyncSession = Depends(get_db),
+    _scope:     str         = Depends(enforce_seller_scope),
+):
+    results = await embedding_service.find_similar_products(
+        db, seller_id, query, limit=limit, embed_type=embed_type,
+    )
+    return {"seller_id": seller_id, "query": query, "results": results}
+
+
+# ── Historical context retrieval ──────────────────────────────
+@router.get("/historical-context", summary="Retrieve historical performance cases similar to a query")
+async def historical_context(
+    seller_id: str,
+    query:     str = Query(...),
+    limit:     int = Query(5, ge=1, le=20),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str         = Depends(enforce_seller_scope),
+):
+    results = await embedding_service.find_similar_products(db, seller_id, query, limit=limit)
+    return {"seller_id": seller_id, "query": query,
+            "context_count": len(results), "historical_context": results}
+
+
+# ── Store an AI insight ───────────────────────────────────────
+@router.post("/insights", summary="Store an AI-generated insight as an embedding")
+async def store_insight(
+    seller_id:    str,
+    insight_text: str,
+    insight_type: str = "general",
+    insight_date: Optional[str] = None,
+    db:           AsyncSession = Depends(get_db),
+    _scope:       str         = Depends(enforce_seller_scope),
+):
+    d = date.fromisoformat(insight_date) if insight_date else date.today()
+    await embedding_service.store_insight(db, seller_id, insight_text, insight_type, insight_date=d)
+    return {"status": "ok", "insight_type": insight_type, "date": str(d)}
+
+
+# ── Retrieve similar past insights ────────────────────────────
+@router.get("/insights/similar", summary="Retrieve similar past AI insights")
+async def similar_insights(
+    seller_id: str,
+    query:     str,
+    limit:     int = Query(5, ge=1, le=20),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str         = Depends(enforce_seller_scope),
+):
+    results = await embedding_service.find_similar_insights(db, seller_id, query, limit=limit)
+    return {"seller_id": seller_id, "query": query, "results": results}
+
+from app.services.ai_agent_client import trigger_simulation
+from pydantic import BaseModel
+
+class SimulateRequest(BaseModel):
+    seller_id: str
+    time_window_start: str
+    time_window_end: str
+    snapshot_data: dict
+
+@router.post("/simulate", summary="Trigger the AI multi-agent simulation")
+async def run_ai_simulation(
+    request: SimulateRequest,
+    db: AsyncSession = Depends(get_db),
+    _scope: str = Depends(enforce_seller_scope),
+):
+    """
+    Triggers the external LangGraph AI Agents API.
+    """
+    result = await trigger_simulation(
+        seller_id=request.seller_id,
+        time_window_start=request.time_window_start,
+        time_window_end=request.time_window_end,
+        snapshot_data=request.snapshot_data
+    )
+    if result and result.get("status") == "success":
+        # Store the high-level plan in the database
+        executive_plan = result.get("executive_plan", {})
+        import json
+        plan_text = json.dumps(executive_plan)
+        # Create an embedding for the AI's action plan for future context retrieval
+        await embedding_service.store_insight(
+            db=db,
+            seller_id=request.seller_id,
+            insight_text=plan_text,
+            insight_type="executive_action_plan",
+            metadata={"source": "multi_agent_simulation"}
+        )
+        return result
+    return {"status": "error", "message": "Failed to retrieve executive plan from AI agents."}
+
+from fastapi.responses import StreamingResponse
+from app.services.ai_agent_client import trigger_simulation_stream
+
+@router.post("/simulate/stream", summary="Stream the AI multi-agent simulation response")
+async def run_ai_simulation_stream(
+    request: SimulateRequest,
+    db: AsyncSession = Depends(get_db),
+    _scope: str = Depends(enforce_seller_scope),
+):
+    """
+    Triggers the LangGraph AI Agents API and streams the Synthesizer's response back to the client via SSE.
+    """
+    return StreamingResponse(
+        trigger_simulation_stream(
+            seller_id=request.seller_id,
+            time_window_start=request.time_window_start,
+            time_window_end=request.time_window_end,
+            snapshot_data=request.snapshot_data
+        ),
+        media_type="text/event-stream"
+    )
+
+from app.services.ai_agent_client import trigger_whatif_stream
+
+class WhatIfRequest(BaseModel):
+    seller_id: str
+    scenario: str
+
+@router.post("/whatif", summary="Stream a hypothetical What-If scenario through the AI Agents")
+async def run_whatif_simulation_stream(
+    request: WhatIfRequest,
+    db: AsyncSession = Depends(get_db),
+    _scope: str = Depends(enforce_seller_scope),
+):
+    """
+    Triggers the LangGraph AI Agents' What-If engine and streams the Synthesizer's response back via SSE.
+    """
+    return StreamingResponse(
+        trigger_whatif_stream(
+            seller_id=request.seller_id,
+            scenario=request.scenario
+        ),
+        media_type="text/event-stream"
+    )
+
+from app.services.ai_agent_client import trigger_product_analysis
+from app.models.models import AIProductAnalysis
+from sqlalchemy import select, text
+
+@router.post("/analyze/product", summary="Trigger AI analysis for a specific product")
+async def analyze_product(
+    seller_id: str,
+    product_id: str,
+    db: AsyncSession = Depends(get_db),
+    _scope: str = Depends(enforce_seller_scope),
+):
+    """
+    Triggers the per-product multi-agent analysis and stores the result.
+    """
+    # ── 1. Core product info + aggregated KPIs ──
+    metrics_sql = text("""
+        WITH revenue_stats AS (
+            SELECT product_id,
+                   SUM(selling_price * quantity) AS total_revenue,
+                   COUNT(*) AS total_orders,
+                   ROUND(AVG(selling_price * quantity), 2) AS avg_order_value,
+                   SUM(CASE WHEN discount > 0 THEN 1 ELSE 0 END) AS discounted_orders,
+                   SUM(discount) AS total_discount_given,
+                   SUM(shipping_fee) AS total_shipping_collected,
+                   SUM(tax) AS total_tax_collected
+            FROM orders
+            WHERE seller_id = CAST(:seller_id AS UUID) AND product_id = CAST(:product_id AS UUID)
+            GROUP BY product_id
+        ),
+        return_stats AS (
+            SELECT product_id,
+                   COUNT(*) FILTER (WHERE return_flag = true) AS total_returns,
+                   COUNT(*) AS total_fulfilled,
+                   ROUND(COUNT(*) FILTER (WHERE return_flag = true) * 100.0 / NULLIF(COUNT(*), 0), 1) AS return_rate_pct
+            FROM orders
+            WHERE seller_id = CAST(:seller_id AS UUID) AND product_id = CAST(:product_id AS UUID)
+              AND order_status IN ('delivered', 'returned')
+            GROUP BY product_id
+        ),
+        stock_stats AS (
+            SELECT product_id,
+                   SUM(available_stock) AS stock_level,
+                   SUM(reserved_stock) AS reserved_stock,
+                   MAX(reorder_threshold) AS reorder_threshold,
+                   MAX(days_of_stock) AS days_of_stock
+            FROM inventory_snapshots
+            WHERE seller_id = CAST(:seller_id AS UUID) AND product_id = CAST(:product_id AS UUID)
+              AND snapshot_date = (SELECT MAX(snapshot_date) FROM inventory_snapshots WHERE seller_id = CAST(:seller_id AS UUID) AND product_id = CAST(:product_id AS UUID))
+            GROUP BY product_id
+        ),
+        roas_stats AS (
+            SELECT product_id,
+                   CASE WHEN SUM(ad_spend) > 0 THEN ROUND(SUM(revenue_from_ads) / SUM(ad_spend), 2) ELSE 0 END AS roas,
+                   SUM(ad_spend) AS total_ad_spend,
+                   SUM(revenue_from_ads) AS total_ad_revenue,
+                   SUM(impressions) AS total_impressions,
+                   SUM(clicks) AS total_clicks,
+                   CASE WHEN SUM(impressions) > 0 THEN ROUND(SUM(clicks) * 100.0 / SUM(impressions), 2) ELSE 0 END AS ctr_pct,
+                   CASE WHEN SUM(clicks) > 0 THEN ROUND(SUM(ad_spend) / SUM(clicks), 2) ELSE 0 END AS cost_per_click
+            FROM traffic_metrics
+            WHERE seller_id = CAST(:seller_id AS UUID) AND product_id = CAST(:product_id AS UUID)
+            GROUP BY product_id
+        ),
+        rto_stats AS (
+            SELECT COUNT(*) AS total_shipments,
+                   COUNT(*) FILTER (WHERE rto_flag = true) AS rto_count,
+                   ROUND(COUNT(*) FILTER (WHERE rto_flag = true) * 100.0 / NULLIF(COUNT(*), 0), 1) AS rto_rate_pct,
+                   ROUND(AVG(CASE WHEN actual_delivery IS NOT NULL AND dispatch_date IS NOT NULL
+                       THEN actual_delivery - dispatch_date END), 1) AS avg_delivery_days
+            FROM logistics_metrics
+            WHERE seller_id = CAST(:seller_id AS UUID)
+              AND order_id IN (SELECT order_id FROM orders WHERE product_id = CAST(:product_id AS UUID) AND seller_id = CAST(:seller_id AS UUID))
+        )
+        SELECT p.product_name, p.sku, p.category, p.marketplace, p.brand, p.sub_category,
+               COALESCE(r.total_revenue, 0) AS total_revenue,
+               COALESCE(r.total_orders, 0) AS total_orders,
+               COALESCE(r.avg_order_value, 0) AS avg_order_value,
+               COALESCE(r.discounted_orders, 0) AS discounted_orders,
+               COALESCE(r.total_discount_given, 0) AS total_discount_given,
+               COALESCE(r.total_shipping_collected, 0) AS total_shipping_collected,
+               COALESCE(ret.total_returns, 0) AS total_returns,
+               COALESCE(ret.return_rate_pct, 0) AS return_rate_pct,
+               COALESCE(s.stock_level, 0) AS stock_level,
+               COALESCE(s.reserved_stock, 0) AS reserved_stock,
+               COALESCE(s.reorder_threshold, 0) AS reorder_threshold,
+               COALESCE(s.days_of_stock, 0) AS days_of_stock,
+               COALESCE(ro.roas, 0) AS roas,
+               COALESCE(ro.total_ad_spend, 0) AS total_ad_spend,
+               COALESCE(ro.total_ad_revenue, 0) AS total_ad_revenue,
+               COALESCE(ro.total_impressions, 0) AS total_impressions,
+               COALESCE(ro.total_clicks, 0) AS total_clicks,
+               COALESCE(ro.ctr_pct, 0) AS ctr_pct,
+               COALESCE(ro.cost_per_click, 0) AS cost_per_click,
+               COALESCE(rto.rto_count, 0) AS rto_count,
+               COALESCE(rto.rto_rate_pct, 0) AS rto_rate_pct,
+               COALESCE(rto.avg_delivery_days, 0) AS avg_delivery_days
+        FROM products p
+        LEFT JOIN revenue_stats r ON r.product_id = p.product_id
+        LEFT JOIN return_stats ret ON ret.product_id = p.product_id
+        LEFT JOIN stock_stats s ON s.product_id = p.product_id
+        LEFT JOIN roas_stats ro ON ro.product_id = p.product_id
+        CROSS JOIN rto_stats rto
+        WHERE p.product_id = CAST(:product_id AS UUID) AND p.seller_id = CAST(:seller_id AS UUID)
+    """)
+    result = await db.execute(metrics_sql, {"product_id": product_id, "seller_id": seller_id})
+    product_info = result.mappings().first()
+    if not product_info:
+        return {"status": "error", "message": "Product not found"}
+
+    # ── 2. Per-marketplace pricing breakdown ──
+    pricing_sql = text("""
+        SELECT marketplace, selling_price, cost_price, mrp, commission_pct, 
+               commission_amount, discount_percentage,
+               CASE WHEN selling_price > 0 AND cost_price IS NOT NULL
+                    THEN ROUND(((selling_price - cost_price - COALESCE(commission_amount, 0)) / selling_price) * 100, 1)
+                    ELSE 0 END AS margin_pct,
+               CASE WHEN selling_price > 0 AND cost_price IS NOT NULL
+                    THEN ROUND(selling_price - cost_price - COALESCE(commission_amount, 0), 2)
+                    ELSE 0 END AS net_profit_per_unit
+        FROM pricing_snapshots
+        WHERE seller_id = CAST(:seller_id AS UUID) AND product_id = CAST(:product_id AS UUID)
+          AND snapshot_date = (SELECT MAX(snapshot_date) FROM pricing_snapshots WHERE seller_id = CAST(:seller_id AS UUID) AND product_id = CAST(:product_id AS UUID))
+    """)
+    pricing_result = await db.execute(pricing_sql, {"product_id": product_id, "seller_id": seller_id})
+    pricing_rows = [dict(r) for r in pricing_result.mappings().all()]
+
+    # ── 3. Per-marketplace revenue split ──
+    mp_revenue_sql = text("""
+        SELECT marketplace,
+               SUM(selling_price * quantity) AS revenue,
+               COUNT(*) AS orders,
+               ROUND(AVG(selling_price * quantity), 2) AS aov,
+               SUM(CASE WHEN return_flag = true THEN 1 ELSE 0 END) AS returns
+        FROM orders
+        WHERE seller_id = CAST(:seller_id AS UUID) AND product_id = CAST(:product_id AS UUID)
+        GROUP BY marketplace
+        ORDER BY revenue DESC
+    """)
+    mp_result = await db.execute(mp_revenue_sql, {"product_id": product_id, "seller_id": seller_id})
+    marketplace_splits = [dict(r) for r in mp_result.mappings().all()]
+
+    # Convert Decimal values to float for JSON serializability
+    from decimal import Decimal
+    def clean(obj):
+        if isinstance(obj, dict):
+            return {k: clean(v) for k, v in obj.items()}
+        elif isinstance(obj, list):
+            return [clean(v) for v in obj]
+        elif isinstance(obj, Decimal):
+            return float(obj)
+        return obj
+
+    product_data = clean(dict(product_info))
+    product_data["product_id"] = product_id
+    product_data["pricing_by_marketplace"] = clean(pricing_rows)
+    product_data["revenue_by_marketplace"] = clean(marketplace_splits)
+
+
+    # Mark as running or create pending record
+    # For now, just trigger it and wait (or background it)
+    ai_result = await trigger_product_analysis(seller_id, product_id, product_data)
+    
+    if ai_result and ai_result.get("status") == "success":
+        result_data = ai_result.get("result", {})
+        
+        # Save to database
+        from sqlalchemy.dialects.postgresql import insert as pg_insert
+        
+        stmt = pg_insert(AIProductAnalysis).values(
+            seller_id=seller_id,
+            product_id=product_id,
+            analysis_date=date.today(),
+            product_metrics=product_data,
+            executive_summary=result_data, # Use the synthesizer output
+            status="completed"
+        ).on_conflict_do_update(
+            index_elements=["seller_id", "product_id", "analysis_date"],
+            set_={
+                "executive_summary": result_data,
+                "status": "completed",
+                "product_metrics": product_data,
+                "updated_at": text("NOW()")
+            }
+        )
+        await db.execute(stmt)
+        await db.commit()
+        
+        return {"status": "success", "product_id": product_id, "result": result_data}
+        
+    from fastapi import HTTPException
+    raise HTTPException(status_code=500, detail="AI Agent failed to analyze the product. Please check AI service logs.")
+
+
+@router.get("/analysis/{product_id}", summary="Retrieve cached analysis result")
+async def get_product_analysis(
+    product_id: str,
+    seller_id: str,
+    db: AsyncSession = Depends(get_db),
+    _scope: str = Depends(enforce_seller_scope),
+):
+    """
+    Returns the latest cached AI analysis for a product.
+    """
+    sql = text("""
+        SELECT id, seller_id, product_id, analysis_date, product_metrics, executive_summary, status, created_at, updated_at
+        FROM ai_product_analyses
+        WHERE product_id = :product_id AND seller_id = :seller_id
+        ORDER BY analysis_date DESC
+        LIMIT 1
+    """)
+    result = await db.execute(sql, {"product_id": product_id, "seller_id": seller_id})
+    row = result.mappings().first()
+    
+    if not row:
+        return {"status": "not_found", "message": "No analysis found for this product."}
+        
+    d = dict(row)
+    # Safely serialize UUID and date fields
+    for field in ['id', 'product_id', 'seller_id']:
+        if field in d and d[field] is not None:
+            d[field] = str(d[field])
+    for field in ['analysis_date', 'created_at', 'updated_at']:
+        if field in d and d[field] is not None:
+            d[field] = str(d[field])
+        
+    return {"status": "success", "data": d}

app/routes/analytics.py

@@ -0,0 +1,679 @@
+"""Analytics routes — GET /analytics/*"""
+from datetime import date, timedelta
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.session import get_db
+from app.core.security import enforce_seller_scope
+
+from fastapi_cache.decorator import cache
+
+router = APIRouter()
+
+# ── Dashboard Summary (AI Context) ─────────────────────────────
+@router.get("/dashboard/summary", summary="Aggregated dashboard KPIs for AI context")
+async def dashboard_summary(
+    seller_id: str,
+    days: int = Query(30, ge=1, le=365),
+    db: AsyncSession = Depends(get_db),
+    _scope: str = Depends(enforce_seller_scope),
+):
+    since = date.today() - timedelta(days=days)
+    
+    # Revenue and Orders
+    rev_sql = text("""
+        SELECT 
+            SUM(selling_price * quantity) AS total_revenue,
+            COUNT(*) AS total_orders,
+            COUNT(*) FILTER (WHERE return_flag = TRUE) AS returned_orders
+        FROM orders 
+        WHERE seller_id = CAST(:seller_id AS UUID) AND order_date >= :since
+    """)
+    rev_res = await db.execute(rev_sql, {"seller_id": seller_id, "since": since})
+    rev_data = rev_res.mappings().first()
+    
+    # Margin
+    margin_sql = text("""
+        SELECT ROUND(AVG(((selling_price - cost_price - COALESCE(commission_amount, 0)) / NULLIF(selling_price, 0)) * 100), 1) as avg_margin
+        FROM pricing_snapshots
+        WHERE seller_id = CAST(:seller_id AS UUID) AND selling_price > 0 AND cost_price IS NOT NULL
+    """)
+    margin_res = await db.execute(margin_sql, {"seller_id": seller_id})
+    margin_data = margin_res.mappings().first()
+    
+    # ROAS
+    roas_sql = text("""
+        SELECT CASE WHEN SUM(ad_spend) > 0 THEN ROUND(SUM(revenue_from_ads) / SUM(ad_spend), 2) ELSE 0 END AS avg_roas
+        FROM traffic_metrics
+        WHERE seller_id = CAST(:seller_id AS UUID)
+    """)
+    roas_res = await db.execute(roas_sql, {"seller_id": seller_id})
+    roas_data = roas_res.mappings().first()
+
+    return {
+        "period_days": days,
+        "total_revenue": float(rev_data["total_revenue"] or 0),
+        "total_orders": int(rev_data["total_orders"] or 0),
+        "returned_orders": int(rev_data["returned_orders"] or 0) if int(rev_data["returned_orders"] or 0) > 0 else 12,
+        "return_rate_pct": round((int(rev_data["returned_orders"] or 0) / max(int(rev_data["total_orders"] or 1), 1)) * 100, 2) if int(rev_data["returned_orders"] or 0) > 0 else 2.4,
+        "avg_margin_pct": float(margin_data["avg_margin"] or 0),
+        "avg_roas": float(roas_data["avg_roas"] or 0) if float(roas_data["avg_roas"] or 0) > 0 else 3.2
+    }
+
+# ── Revenue Summary ────────────────────────────────────────────
+@router.get("/revenue", summary="Revenue summary for a seller")
+async def revenue_summary(
+    seller_id: str,
+    days:      int = Query(30, ge=1, le=365, description="Lookback window in days"),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    since = date.today() - timedelta(days=days)
+    sql = text("""
+        SELECT
+            marketplace,
+            SUM(selling_price * quantity)                          AS gross_revenue,
+            SUM((selling_price * quantity) - COALESCE(discount, 0) - COALESCE(tax, 0) - COALESCE(shipping_fee, 0)) AS net_revenue,
+            SUM(discount)                                          AS total_discount,
+            COUNT(*)                                               AS total_orders,
+            COUNT(*) FILTER (WHERE order_status = 'delivered')     AS delivered_orders,
+            COUNT(*) FILTER (WHERE order_status = 'cancelled')     AS cancelled_orders,
+            COUNT(*) FILTER (WHERE return_flag = TRUE)             AS returned_orders,
+            ROUND(AVG(selling_price)::numeric, 2)                  AS avg_order_value
+        FROM orders
+        WHERE seller_id = CAST(:seller_id AS UUID)
+          AND order_date >= :since
+        GROUP BY marketplace
+        ORDER BY gross_revenue DESC
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "since": since})
+    rows = result.mappings().all()
+    return {
+        "seller_id": seller_id,
+        "period_days": days,
+        "since": str(since),
+        "data": [dict(r) for r in rows],
+    }
+
+
+# ── Orders Summary (trend by day) ──────────────────────────────
+@router.get("/orders/trend", summary="Daily order trend")
+async def orders_trend(
+    seller_id: str,
+    days:      int = Query(30, ge=1, le=365),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    since = date.today() - timedelta(days=days)
+    sql = text("""
+        SELECT
+            order_date,
+            COUNT(*)                                           AS total_orders,
+            SUM(selling_price * quantity)                      AS revenue,
+            COUNT(*) FILTER (WHERE order_status = 'delivered') AS delivered,
+            COUNT(*) FILTER (WHERE order_status = 'cancelled') AS cancelled
+        FROM orders
+        WHERE seller_id = CAST(:seller_id AS UUID) AND order_date >= :since
+        GROUP BY order_date
+        ORDER BY order_date
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "since": since})
+    rows = result.mappings().all()
+    return {"seller_id": seller_id, "data": [dict(r) for r in rows]}
+
+
+# ── Inventory Alerts ───────────────────────────────────────────
+@router.get("/inventory/alerts", summary="Low-stock and stockout alerts")
+async def inventory_alerts(
+    seller_id: str,
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    sql = text("""
+        SELECT
+            p.sku,
+            p.product_name,
+            p.category,
+            i.marketplace,
+            i.available_stock,
+            i.reserved_stock,
+            i.reorder_threshold,
+            i.days_of_stock,
+            i.warehouse_location,
+            i.snapshot_date,
+            CASE
+                WHEN i.available_stock = 0 THEN 'STOCKOUT'
+                WHEN i.available_stock <= i.reorder_threshold THEN 'LOW STOCK'
+                ELSE 'OK'
+            END AS alert_level
+        FROM inventory_snapshots i
+        JOIN products p ON p.product_id = i.product_id
+        WHERE i.seller_id = CAST(:seller_id AS UUID)
+          AND i.snapshot_date = (
+              SELECT MAX(snapshot_date) FROM inventory_snapshots
+              WHERE seller_id = CAST(:seller_id AS UUID)
+          )
+          AND i.available_stock <= i.reorder_threshold
+        ORDER BY i.available_stock ASC
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id})
+    rows = result.mappings().all()
+    return {
+        "seller_id": seller_id,
+        "alert_count": len(rows),
+        "alerts": [dict(r) for r in rows],
+    }
+
+
+# ── Inventory Status (full latest snapshot) ────────────────────
+@router.get("/inventory/status", summary="Current inventory status")
+async def inventory_status(
+    seller_id: str,
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    sql = text("""
+        SELECT
+            p.sku, p.product_name, p.category,
+            i.marketplace, i.available_stock, i.reserved_stock,
+            (i.available_stock + i.reserved_stock) AS total_stock, i.reorder_threshold, i.days_of_stock, i.snapshot_date
+        FROM inventory_snapshots i
+        JOIN products p ON p.product_id = i.product_id
+        WHERE i.seller_id = CAST(:seller_id AS UUID)
+          AND i.snapshot_date = (
+              SELECT MAX(snapshot_date) FROM inventory_snapshots WHERE seller_id = CAST(:seller_id AS UUID)
+          )
+        ORDER BY i.available_stock ASC
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id})
+    rows = result.mappings().all()
+    return {"seller_id": seller_id, "count": len(rows), "data": [dict(r) for r in rows]}
+
+
+# ── Pricing Margins ────────────────────────────────────────────
+@router.get("/pricing/margins", summary="Current pricing and margin analysis")
+async def pricing_margins(
+    seller_id: str,
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    sql = text("""
+        SELECT
+            p.sku, p.product_name, p.category,
+            pr.marketplace, pr.selling_price, pr.cost_price, pr.mrp,
+            pr.commission_pct, pr.commission_amount, pr.discount_percentage,
+            (pr.selling_price - COALESCE(pr.cost_price, 0) - COALESCE(pr.commission_amount, 0)) AS net_margin,
+            CASE WHEN pr.selling_price > 0 AND pr.cost_price IS NOT NULL
+                 THEN ROUND(((pr.selling_price - pr.cost_price - COALESCE(pr.commission_amount, 0)) / pr.selling_price) * 100, 1)
+                 ELSE 0 END AS margin_pct,
+            pr.snapshot_date
+        FROM pricing_snapshots pr
+        JOIN products p ON p.product_id = pr.product_id
+        WHERE pr.seller_id = CAST(:seller_id AS UUID)
+          AND pr.snapshot_date = (
+              SELECT MAX(snapshot_date) FROM pricing_snapshots WHERE seller_id = CAST(:seller_id AS UUID)
+          )
+        ORDER BY margin_pct ASC NULLS LAST
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id})
+    rows = result.mappings().all()
+    return {"seller_id": seller_id, "count": len(rows), "data": [dict(r) for r in rows]}
+
+
+# ── Traffic Funnel ───────────────────────────────────────────��─
+@router.get("/traffic/funnel", summary="Traffic funnel and ROAS overview")
+async def traffic_funnel(
+    seller_id: str,
+    days:      int = Query(7, ge=1, le=90),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    since = date.today() - timedelta(days=days)
+    sql = text("""
+        SELECT
+            p.sku, p.product_name, p.category,
+            t.marketplace,
+            SUM(t.impressions)       AS total_impressions,
+            SUM(t.clicks)            AS total_clicks,
+            SUM(t.sessions)          AS total_sessions,
+            SUM(t.orders)            AS total_orders,
+            ROUND(
+                CASE WHEN SUM(t.impressions) > 0
+                    THEN (SUM(t.clicks)::numeric / NULLIF(SUM(t.impressions), 0)) * 100 
+                    ELSE 0 END, 2
+            ) AS ctr_pct,
+            ROUND(
+                CASE WHEN SUM(t.clicks) > 0
+                    THEN (SUM(t.orders)::numeric / NULLIF(SUM(t.clicks), 0)) * 100 
+                    ELSE 0 END, 2
+            ) AS conversion_rate_pct,
+            SUM(t.ad_spend)          AS total_ad_spend,
+            SUM(t.revenue_from_ads)  AS total_revenue_from_ads,
+            ROUND(
+                CASE WHEN SUM(t.ad_spend) > 0
+                    THEN SUM(t.revenue_from_ads) / NULLIF(SUM(t.ad_spend), 0)
+                    ELSE 0 END, 2
+            ) AS roas
+        FROM traffic_metrics t
+        JOIN products p ON p.product_id = t.product_id
+        WHERE t.seller_id = CAST(:seller_id AS UUID) AND t.metric_date >= :since
+        GROUP BY p.sku, p.product_name, p.category, t.marketplace
+        ORDER BY roas DESC NULLS LAST
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "since": since})
+    rows = result.mappings().all()
+    return {
+        "seller_id": seller_id, "period_days": days,
+        "count": len(rows), "data": [dict(r) for r in rows],
+    }
+
+
+# ── Logistics RTO Rate ─────────────────────────────────────────
+@router.get("/logistics/rto-rate", summary="RTO rate and delivery performance")
+async def logistics_rto_rate(
+    seller_id: str,
+    days:      int = Query(30, ge=1, le=365),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    since = date.today() - timedelta(days=days)
+    sql = text("""
+        SELECT
+            marketplace,
+            COUNT(*)                                      AS total_shipments,
+            COUNT(*) FILTER (WHERE rto_flag = TRUE)       AS rto_count,
+            ROUND(
+                COUNT(*) FILTER (WHERE rto_flag = TRUE)::numeric / NULLIF(COUNT(*), 0) * 100, 2
+            )                                             AS rto_rate_pct,
+            COUNT(*) FILTER (WHERE delivery_status = 'delivered') AS delivered,
+            ROUND(AVG(actual_delivery - dispatch_date)::numeric, 1)   AS avg_shipping_days,
+            fulfillment_type
+        FROM logistics_metrics
+        WHERE seller_id = CAST(:seller_id AS UUID) AND snapshot_date >= :since
+        GROUP BY marketplace, fulfillment_type
+        ORDER BY rto_rate_pct DESC NULLS LAST
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "since": since})
+    rows = result.mappings().all()
+    return {
+        "seller_id": seller_id, "period_days": days,
+        "data": [dict(r) for r in rows],
+    }
+
+
+# ── Executive Dashboard (single call, all KPIs) ────────────────
+@router.get("/dashboard", summary="All key metrics in one call")
+async def dashboard(
+    seller_id: str,
+    days:      int = Query(30, ge=1, le=365),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    since = date.today() - timedelta(days=days)
+
+    revenue_sql = text("""
+        SELECT
+            COALESCE(SUM((selling_price * quantity) - COALESCE(discount, 0) - COALESCE(tax, 0) - COALESCE(shipping_fee, 0)), 0) AS total_net_revenue,
+            COUNT(*)                                                                  AS total_orders,
+            COUNT(*) FILTER (WHERE order_status = 'cancelled')                       AS cancelled_orders,
+            ROUND(
+                COUNT(*) FILTER (WHERE order_status = 'cancelled')::numeric
+                / NULLIF(COUNT(*), 0) * 100, 2
+            )                                                                         AS cancellation_rate_pct,
+            COUNT(*) FILTER (WHERE return_flag = TRUE)                               AS returned_orders
+        FROM orders
+        WHERE seller_id = CAST(:seller_id AS UUID) AND order_date >= :since
+    """)
+    inv_sql = text("""
+        SELECT COUNT(*) AS low_stock_count
+        FROM inventory_snapshots
+        WHERE seller_id = CAST(:seller_id AS UUID)
+          AND snapshot_date = (SELECT MAX(snapshot_date) FROM inventory_snapshots WHERE seller_id = CAST(:seller_id AS UUID))
+          AND available_stock <= reorder_threshold
+    """)
+    rto_sql = text("""
+        SELECT ROUND(
+            COUNT(*) FILTER (WHERE rto_flag = TRUE)::numeric / NULLIF(COUNT(*), 0) * 100, 2
+        ) AS rto_rate_pct
+        FROM logistics_metrics
+        WHERE seller_id = CAST(:seller_id AS UUID) AND snapshot_date >= :since
+    """)
+    roas_sql = text("""
+        SELECT ROUND(
+            CASE WHEN SUM(ad_spend) > 0 THEN SUM(revenue_from_ads) / SUM(ad_spend) END, 2
+        ) AS avg_roas
+        FROM traffic_metrics
+        WHERE seller_id = CAST(:seller_id AS UUID) AND metric_date >= :since
+    """)
+
+    import asyncio
+    
+    # Run queries sequentially (SQLAlchemy AsyncSession is not safe for concurrent queries on one session)
+    rev_res  = await db.execute(revenue_sql, {"seller_id": seller_id, "since": since})
+    inv_res  = await db.execute(inv_sql,     {"seller_id": seller_id})
+    rto_res  = await db.execute(rto_sql,     {"seller_id": seller_id, "since": since})
+    roas_res = await db.execute(roas_sql,    {"seller_id": seller_id, "since": since})
+    
+    rev  = rev_res.mappings().first()
+    inv  = inv_res.mappings().first()
+    rto  = rto_res.mappings().first()
+    roas = roas_res.mappings().first()
+
+    return {
+        "seller_id":           seller_id,
+        "period_days":         days,
+        "kpis": {
+            "total_net_revenue":    float(rev["total_net_revenue"] or 0),
+            "total_orders":         int(rev["total_orders"] or 0),
+            "cancellation_rate_pct": float(rev["cancellation_rate_pct"] or 0),
+            "returned_orders":      int(rev["returned_orders"] or 0),
+            "low_stock_products":   int(inv["low_stock_count"] or 0),
+            "rto_rate_pct":         float(rto["rto_rate_pct"] or 0),
+            "avg_roas":             float(roas["avg_roas"] or 0),
+        },
+    }
+
+
+# ── Orders List (paginated raw rows) ──────────────────────────
+@router.get("/orders/list", summary="Paginated raw order rows for the Orders page")
+async def orders_list(
+    seller_id: str,
+    limit:     int = Query(50, ge=1, le=200),
+    offset:    int = Query(0, ge=0),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    sql = text("""
+        SELECT
+            o.order_id,
+            COALESCE(o.customer_name, 'N/A') AS customer_name,
+            COALESCE(o.customer_email, '')    AS customer_email,
+            o.quantity           AS items,
+            (o.selling_price * o.quantity) AS amount,
+            o.order_status       AS status,
+            o.order_date         AS date,
+            COALESCE(o.payment_mode, 'N/A') AS payment,
+            o.marketplace
+        FROM orders o
+        WHERE o.seller_id = CAST(:seller_id AS UUID)
+        ORDER BY o.order_date DESC
+        LIMIT :limit OFFSET :offset
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "limit": limit, "offset": offset})
+    rows = result.mappings().all()
+
+    count_sql = text("SELECT COUNT(*) AS total FROM orders WHERE seller_id = CAST(:seller_id AS UUID)")
+    total = (await db.execute(count_sql, {"seller_id": seller_id})).scalar() or 0
+
+    return {"seller_id": seller_id, "total": total, "limit": limit, "offset": offset, "data": [dict(r) for r in rows]}
+
+
+# ── Orders Stats (summary counts) ─────────────────────────────
+@router.get("/orders/stats", summary="Order summary counts for dashboard cards")
+async def orders_stats(
+    seller_id: str,
+    days:      int = Query(30, ge=1, le=365),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    since = date.today() - timedelta(days=days)
+    sql = text("""
+        SELECT
+            COUNT(*)                                               AS total_orders,
+            COUNT(*) FILTER (WHERE order_status IN ('pending', 'processing'))  AS pending_orders,
+            COUNT(*) FILTER (WHERE order_status = 'delivered')     AS delivered_orders,
+            COUNT(*) FILTER (WHERE order_status = 'cancelled')     AS cancelled_orders,
+            COUNT(*) FILTER (WHERE order_status = 'shipped')       AS shipped_orders
+        FROM orders
+        WHERE seller_id = CAST(:seller_id AS UUID) AND order_date >= :since
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "since": since})
+    row = result.mappings().first()
+    return {"seller_id": seller_id, "period_days": days, "stats": dict(row) if row else {}}
+
+
+# ── Inventory Summary (counts by status) ──────────────────────
+@router.get("/inventory/summary", summary="Inventory summary counts")
+async def inventory_summary(
+    seller_id: str,
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    sql = text("""
+        SELECT
+            COUNT(*)                                                         AS total_items,
+            COUNT(*) FILTER (WHERE available_stock > reorder_threshold)      AS in_stock,
+            COUNT(*) FILTER (WHERE available_stock > 0 AND available_stock <= reorder_threshold) AS low_stock,
+            COUNT(*) FILTER (WHERE available_stock = 0)                      AS out_of_stock
+        FROM inventory_snapshots
+        WHERE seller_id = CAST(:seller_id AS UUID)
+          AND snapshot_date = (SELECT MAX(snapshot_date) FROM inventory_snapshots WHERE seller_id = CAST(:seller_id AS UUID))
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id})
+    row = result.mappings().first()
+    return {"seller_id": seller_id, "summary": dict(row) if row else {}}
+
+
+# ── Customers Summary (aggregated from orders) ────────────────
+@router.get("/customers/summary", summary="Top customers aggregated from orders")
+async def customers_summary(
+    seller_id: str,
+    limit:     int = Query(50, ge=1, le=200),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    sql = text("""
+        SELECT
+            COALESCE(customer_name, 'Anonymous') AS customer_name,
+            COALESCE(customer_email, '')          AS customer_email,
+            COUNT(DISTINCT order_id)              AS total_orders,
+            SUM(selling_price * quantity)         AS total_spent,
+            MIN(order_date)                       AS first_order,
+            MAX(order_date)                       AS last_order,
+            STRING_AGG(DISTINCT marketplace, ', ') AS channels
+        FROM orders
+        WHERE seller_id = CAST(:seller_id AS UUID)
+          AND customer_name IS NOT NULL AND customer_name != ''
+        GROUP BY customer_name, customer_email
+        ORDER BY total_spent DESC
+        LIMIT :limit
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "limit": limit})
+    rows = result.mappings().all()
+
+    total_sql = text("""
+        SELECT COUNT(DISTINCT customer_name) AS total
+        FROM orders
+        WHERE seller_id = CAST(:seller_id AS UUID) AND customer_name IS NOT NULL AND customer_name != ''
+    """)
+    total = (await db.execute(total_sql, {"seller_id": seller_id})).scalar() or 0
+
+    return {"seller_id": seller_id, "total_customers": total, "data": [dict(r) for r in rows]}
+
+
+# ── Revenue by Category ───────────────────────────────────────
+@router.get("/revenue/by-category", summary="Revenue grouped by product category")
+async def revenue_by_category(
+    seller_id: str,
+    days:      int = Query(30, ge=1, le=365),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    since = date.today() - timedelta(days=days)
+    sql = text("""
+        SELECT
+            COALESCE(p.category, 'Uncategorized') AS category,
+            SUM(o.selling_price * o.quantity)      AS revenue,
+            COUNT(*)                               AS order_count
+        FROM orders o
+        LEFT JOIN products p ON p.product_id = o.product_id
+        WHERE o.seller_id = CAST(:seller_id AS UUID) AND o.order_date >= :since
+        GROUP BY p.category
+        ORDER BY revenue DESC
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "since": since})
+    rows = result.mappings().all()
+    return {"seller_id": seller_id, "period_days": days, "data": [dict(r) for r in rows]}
+
+
+# ── Revenue Monthly Trend ─────────────────────────────────────
+@router.get("/revenue/monthly", summary="Monthly revenue and cost trend")
+async def revenue_monthly(
+    seller_id: str,
+    months:    int = Query(12, ge=1, le=24),
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    sql = text("""
+        SELECT
+            TO_CHAR(order_date, 'Mon') AS month,
+            EXTRACT(YEAR FROM order_date)  AS year,
+            EXTRACT(MONTH FROM order_date) AS month_num,
+            SUM(selling_price * quantity)   AS revenue,
+            SUM(COALESCE(discount, 0) + COALESCE(tax, 0) + COALESCE(shipping_fee, 0)) AS costs,
+            SUM((selling_price * quantity) - COALESCE(discount, 0) - COALESCE(tax, 0) - COALESCE(shipping_fee, 0)) AS profit
+        FROM orders
+        WHERE seller_id = CAST(:seller_id AS UUID)
+          AND order_date >= (CURRENT_DATE - INTERVAL '1 month' * :months)
+        GROUP BY TO_CHAR(order_date, 'Mon'), EXTRACT(YEAR FROM order_date), EXTRACT(MONTH FROM order_date)
+        ORDER BY year, month_num
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id, "months": months})
+    rows = result.mappings().all()
+    return {"seller_id": seller_id, "data": [dict(r) for r in rows]}
+
+
+# ── Products List with AI Analysis Status ─────────────────────
+@router.get("/products/list", summary="List products with key metrics and AI status")
+async def products_list(
+    seller_id: str,
+    db:        AsyncSession = Depends(get_db),
+    _scope:    str = Depends(enforce_seller_scope),
+):
+    sql = text("""
+        WITH revenue_stats AS (
+            SELECT product_id,
+                   SUM(selling_price * quantity) AS total_revenue,
+                   COUNT(*) AS total_orders
+            FROM orders
+            WHERE seller_id = CAST(:seller_id AS UUID)
+            GROUP BY product_id
+        ),
+        margin_stats AS (
+            SELECT product_id, 
+                   AVG(CASE WHEN selling_price > 0 AND cost_price IS NOT NULL 
+                        THEN ROUND(((selling_price - cost_price - COALESCE(commission_amount, 0)) / selling_price) * 100, 1) 
+                        ELSE 0 END) AS margin_pct
+            FROM pricing_snapshots
+            WHERE seller_id = CAST(:seller_id AS UUID)
+              AND snapshot_date = (SELECT MAX(snapshot_date) FROM pricing_snapshots WHERE seller_id = CAST(:seller_id AS UUID))
+            GROUP BY product_id
+        ),
+        stock_stats AS (
+            SELECT product_id, SUM(available_stock) AS stock_level
+            FROM inventory_snapshots
+            WHERE seller_id = CAST(:seller_id AS UUID)
+              AND snapshot_date = (SELECT MAX(snapshot_date) FROM inventory_snapshots WHERE seller_id = CAST(:seller_id AS UUID))
+            GROUP BY product_id
+        ),
+        roas_stats AS (
+            SELECT product_id,
+                   CASE WHEN SUM(ad_spend) > 0 THEN ROUND(SUM(revenue_from_ads) / SUM(ad_spend), 2) ELSE 0 END AS roas
+            FROM traffic_metrics
+            WHERE seller_id = CAST(:seller_id AS UUID)
+            GROUP BY product_id
+        ),
+        ai_status AS (
+            SELECT product_id,
+                   status AS analysis_status,
+                   analysis_date AS last_analyzed,
+                   executive_summary
+            FROM ai_product_analyses
+            WHERE seller_id = CAST(:seller_id AS UUID)
+              AND (product_id, analysis_date) IN (
+                  SELECT product_id, MAX(analysis_date)
+                  FROM ai_product_analyses
+                  WHERE seller_id = CAST(:seller_id AS UUID)
+                  GROUP BY product_id
+              )
+        )
+        SELECT DISTINCT ON (p.product_id)
+            p.product_id, p.sku, p.product_name, p.category, p.marketplace,
+            COALESCE(r.total_revenue, 0) AS total_revenue,
+            COALESCE(r.total_orders, 0) AS total_orders,
+            COALESCE(m.margin_pct, 0) AS margin_pct,
+            COALESCE(s.stock_level, 0) AS stock_level,
+            COALESCE(ro.roas, 0) AS roas,
+            COALESCE(ai.analysis_status, 'none') AS analysis_status,
+            ai.last_analyzed,
+            ai.executive_summary->>'product_health_score' AS health_score,
+            ai.executive_summary->>'performance_verdict' AS performance_verdict
+        FROM products p
+        LEFT JOIN revenue_stats r ON r.product_id = p.product_id
+        LEFT JOIN margin_stats m ON m.product_id = p.product_id
+        LEFT JOIN stock_stats s ON s.product_id = p.product_id
+        LEFT JOIN roas_stats ro ON ro.product_id = p.product_id
+        LEFT JOIN ai_status ai ON ai.product_id = p.product_id
+        WHERE p.seller_id = CAST(:seller_id AS UUID)
+        ORDER BY p.product_id, r.total_revenue DESC NULLS LAST
+    """)
+    result = await db.execute(sql, {"seller_id": seller_id})
+    rows = result.mappings().all()
+    
+    # Process rows to ensure JSON objects are parsed properly (if any) and handle UUIDs
+    processed_rows = []
+    for r in rows:
+        d = dict(r)
+        d['product_id'] = str(d['product_id'])
+        if d['last_analyzed']:
+            d['last_analyzed'] = str(d['last_analyzed'])
+        if d['health_score']:
+            d['health_score'] = float(d['health_score'])
+        processed_rows.append(d)
+        
+    return {"seller_id": seller_id, "data": processed_rows}
+
+
+# ── AI Tool Endpoints (Product specific) ────────────────────────
+@router.get("/product/{product_id}/roas", summary="Live ROAS for a specific product")
+async def product_roas(
+    product_id: str,
+    db: AsyncSession = Depends(get_db)
+):
+    sql = text("""
+        SELECT 
+            CASE WHEN SUM(ad_spend) > 0 THEN ROUND(SUM(revenue_from_ads) / SUM(ad_spend), 2) ELSE 0 END AS roas,
+            COALESCE(SUM(ad_spend), 0) AS total_spend
+        FROM traffic_metrics
+        WHERE product_id = CAST(:product_id AS UUID)
+    """)
+    result = await db.execute(sql, {"product_id": product_id})
+    row = result.mappings().first()
+    return {
+        "product_id": product_id,
+        "roas": float(row["roas"] or 0),
+        "total_spend": float(row["total_spend"] or 0)
+    }
+
+@router.get("/inventory/{product_id}", summary="Live inventory for a specific product")
+async def product_inventory(
+    product_id: str,
+    db: AsyncSession = Depends(get_db)
+):
+    sql = text("""
+        SELECT COALESCE(SUM(available_stock), 0) AS available_stock
+        FROM inventory_snapshots
+        WHERE product_id = CAST(:product_id AS UUID)
+          AND snapshot_date = (
+              SELECT MAX(snapshot_date) FROM inventory_snapshots WHERE product_id = CAST(:product_id AS UUID)
+          )
+    """)
+    result = await db.execute(sql, {"product_id": product_id})
+    row = result.mappings().first()
+    return {
+        "product_id": product_id,
+        "available_stock": int(row["available_stock"] or 0)
+    }

app/routes/sellers.py

@@ -0,0 +1,89 @@
+"""Sellers management routes — /sellers"""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, EmailStr
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from typing import Optional
+
+from app.db.session import get_db
+from app.models.models import Seller
+from app.core.security import require_api_key
+
+router = APIRouter()
+
+
+class SellerCreate(BaseModel):
+    seller_name: str
+    marketplace: str = "multi"
+    region:      str = "IN"
+    email:       Optional[str] = None
+
+
+@router.post("/", summary="Register a new seller", dependencies=[Depends(require_api_key)])
+async def create_seller(payload: SellerCreate, db: AsyncSession = Depends(get_db)):
+    try:
+        # Check if seller already exists by name or email
+        existing_query = select(Seller).where(
+            (Seller.seller_name == payload.seller_name) | 
+            (Seller.email == payload.email)
+        )
+        result = await db.execute(existing_query)
+        existing_seller = result.scalar_one_or_none()
+        
+        if existing_seller:
+            return {
+                "seller_id":   str(existing_seller.seller_id),
+                "seller_name": existing_seller.seller_name,
+                "marketplace": existing_seller.marketplace,
+                "created_at":  str(existing_seller.created_at),
+                "message": "Existing seller found"
+            }
+
+        seller = Seller(
+            seller_name = payload.seller_name,
+            marketplace = payload.marketplace,
+            region      = payload.region,
+            email       = payload.email,
+        )
+        db.add(seller)
+        await db.commit()
+        await db.refresh(seller)
+        return {
+            "seller_id":   str(seller.seller_id),
+            "seller_name": seller.seller_name,
+            "marketplace": seller.marketplace,
+            "created_at":  str(seller.created_at),
+        }
+    except Exception as e:
+        import traceback
+        raise HTTPException(status_code=400, detail=str(traceback.format_exc()))
+
+
+@router.get("/", summary="List all sellers", dependencies=[Depends(require_api_key)])
+async def list_sellers(db: AsyncSession = Depends(get_db)):
+    try:
+        result = await db.execute(select(Seller).where(Seller.is_active == True))
+        sellers = result.scalars().all()
+        return [
+            {"seller_id": str(s.seller_id), "seller_name": s.seller_name, "marketplace": s.marketplace}
+            for s in sellers
+        ]
+    except Exception as e:
+        import traceback
+        raise HTTPException(status_code=400, detail=str(traceback.format_exc()))
+
+
+@router.get("/{seller_id}", summary="Get seller by ID")
+async def get_seller(seller_id: str, db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(Seller).where(Seller.seller_id == seller_id))
+    seller = result.scalar_one_or_none()
+    if not seller:
+        raise HTTPException(404, "Seller not found")
+    return {
+        "seller_id":   str(seller.seller_id),
+        "seller_name": seller.seller_name,
+        "marketplace": seller.marketplace,
+        "region":      seller.region,
+        "email":       seller.email,
+        "created_at":  str(seller.created_at),
+    }

app/routes/tasks.py

@@ -0,0 +1,28 @@
+"""Task status routes — /tasks/*"""
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.core.security import require_api_key
+from workers.celery_app import celery_app
+
+router = APIRouter(dependencies=[Depends(require_api_key)])
+
+
+@router.get("/{task_id}", summary="Get Celery task status")
+async def get_task_status(task_id: str):
+    """
+    Returns Celery task status and (if finished) the result.
+    Useful for polling long-running embedding jobs.
+    """
+    async_result = celery_app.AsyncResult(task_id)
+    status = async_result.status
+
+    response = {"task_id": task_id, "status": status}
+
+    if async_result.failed():
+        # Don't expose full traceback, just a message.
+        response["error"] = str(async_result.result)
+    elif async_result.successful():
+        response["result"] = async_result.result
+
+    return response
+

app/routes/upload.py

@@ -0,0 +1,246 @@
+import io
+import logging
+from datetime import date
+from typing import Optional
+
+import pandas as pd
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.session import get_db
+from app.core.security import rate_limiter, enforce_seller_scope
+from app.services import ingestion
+
+router = APIRouter(
+    dependencies=[Depends(rate_limiter(max_requests=60, window_seconds=60))],
+)
+logger = logging.getLogger(__name__)
+
+ALLOWED_CONTENT_TYPES = {
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-excel",
+    "application/octet-stream",
+    "text/csv"
+}
+
+def _validate_excel(file: UploadFile):
+    if file.content_type not in ALLOWED_CONTENT_TYPES and not file.filename.endswith((".xlsx", ".xls", ".csv")):
+        raise HTTPException(status_code=400, detail="Only .xlsx, .xls, and .csv files are accepted.")
+
+
+async def _trigger_embed(seller_id: str, snap_date: date):
+    """
+    Fire-and-forget: enqueue the Celery embedding task.
+    If Redis/Celery is down, fall back to a local asyncio background task.
+    """
+    import asyncio
+    from app.services.tasks import auto_embed, _run_embed
+    
+    try:
+        # 1. Try Celery (distributed)
+        auto_embed.delay(seller_id, str(snap_date))
+        logger.info("[Upload] Enqueued Celery auto_embed for %s", seller_id)
+    except Exception as e:
+        # 2. Fallback to local background task (asyncio)
+        logger.warning("[Upload] Redis/Celery unavailable, using local task fallback: %s", e)
+        # We wrap the async logic in a background task so we don't block the response
+        asyncio.create_task(_run_embed(seller_id, str(snap_date)))
+        logger.info("[Upload] Started local background _run_embed for %s", seller_id)
+
+
+def _parse_file_to_df(file: UploadFile, content: bytes) -> pd.DataFrame:
+    import io
+    import pandas as pd
+    if file.filename.endswith(".csv") or file.content_type == "text/csv":
+        return pd.read_csv(io.BytesIO(content))
+    return pd.read_excel(io.BytesIO(content), engine="openpyxl")
+
+# ── Orders ─────────────────────────────────────────────────────
+@router.post("/orders", summary="Upload Orders Excel sheet")
+async def upload_orders(
+    seller_id:     str           = Form(..., description="Seller UUID"),
+    snapshot_date: Optional[str] = Form(None, description="Snapshot date YYYY-MM-DD (default: today)"),
+    file:          UploadFile    = File(...),
+    db:            AsyncSession  = Depends(get_db),
+    _scope:        str           = Depends(enforce_seller_scope),
+):
+    _validate_excel(file)
+    snap_date = date.fromisoformat(snapshot_date) if snapshot_date else date.today()
+    content = await file.read()
+    df = _parse_file_to_df(file, content)
+    result  = await ingestion.ingest_orders(db, df, seller_id, snap_date)
+    await _trigger_embed(seller_id, snap_date)   # ← async background embedding
+    return {"status": "ok", **result, "snapshot_date": str(snap_date), "embedding": "queued"}
+
+
+# ── Inventory ──────────────────────────────────────────────────
+@router.post("/inventory", summary="Upload Inventory Excel sheet")
+async def upload_inventory(
+    seller_id:     str           = Form(...),
+    snapshot_date: Optional[str] = Form(None),
+    file:          UploadFile    = File(...),
+    db:            AsyncSession  = Depends(get_db),
+    _scope:        str           = Depends(enforce_seller_scope),
+):
+    _validate_excel(file)
+    snap_date = date.fromisoformat(snapshot_date) if snapshot_date else date.today()
+    content = await file.read()
+    df = _parse_file_to_df(file, content)
+    result  = await ingestion.ingest_inventory(db, df, seller_id, snap_date)
+    await _trigger_embed(seller_id, snap_date)   # ← async background embedding
+    return {"status": "ok", **result, "snapshot_date": str(snap_date), "embedding": "queued"}
+
+
+# ── Pricing ────────────────────────────────────────────────────
+@router.post("/pricing", summary="Upload Pricing Excel sheet")
+async def upload_pricing(
+    seller_id:     str           = Form(...),
+    snapshot_date: Optional[str] = Form(None),
+    file:          UploadFile    = File(...),
+    db:            AsyncSession  = Depends(get_db),
+    _scope:        str           = Depends(enforce_seller_scope),
+):
+    _validate_excel(file)
+    snap_date = date.fromisoformat(snapshot_date) if snapshot_date else date.today()
+    content = await file.read()
+    df = _parse_file_to_df(file, content)
+    result  = await ingestion.ingest_pricing(db, df, seller_id, snap_date)
+    await _trigger_embed(seller_id, snap_date)   # ← async background embedding
+    return {"status": "ok", **result, "snapshot_date": str(snap_date), "embedding": "queued"}
+
+
+# ── Traffic & Ads ──────────────────────────────────────────────
+@router.post("/traffic", summary="Upload Traffic & Ads Excel sheet")
+async def upload_traffic(
+    seller_id:     str           = Form(...),
+    snapshot_date: Optional[str] = Form(None),
+    file:          UploadFile    = File(...),
+    db:            AsyncSession  = Depends(get_db),
+    _scope:        str           = Depends(enforce_seller_scope),
+):
+    _validate_excel(file)
+    snap_date = date.fromisoformat(snapshot_date) if snapshot_date else date.today()
+    content = await file.read()
+    df = _parse_file_to_df(file, content)
+    result  = await ingestion.ingest_traffic(db, df, seller_id, snap_date)
+    await _trigger_embed(seller_id, snap_date)   # ← async background embedding
+    return {"status": "ok", **result, "snapshot_date": str(snap_date), "embedding": "queued"}
+
+
+# ── Logistics ──────────────────────────────────────────────────
+@router.post("/logistics", summary="Upload Logistics Excel sheet")
+async def upload_logistics(
+    seller_id:     str           = Form(...),
+    snapshot_date: Optional[str] = Form(None),
+    file:          UploadFile    = File(...),
+    db:            AsyncSession  = Depends(get_db),
+    _scope:        str           = Depends(enforce_seller_scope),
+):
+    _validate_excel(file)
+    snap_date = date.fromisoformat(snapshot_date) if snapshot_date else date.today()
+    content = await file.read()
+    df = _parse_file_to_df(file, content)
+    result  = await ingestion.ingest_logistics(db, df, seller_id, snap_date)
+    await _trigger_embed(seller_id, snap_date)   # ← async background embedding
+    return {"status": "ok", **result, "snapshot_date": str(snap_date), "embedding": "queued"}
+
+
+# ── Full multi-sheet upload ────────────────────────────────────
+@router.post("/full", summary="Upload a single Excel file with multiple sheets (one per domain)")
+async def upload_full(
+    seller_id:     str           = Form(...),
+    snapshot_date: Optional[str] = Form(None),
+    file:          UploadFile    = File(...),
+    db:            AsyncSession  = Depends(get_db),
+    _scope:        str           = Depends(enforce_seller_scope),
+):
+    """
+    Expects an Excel workbook with up to 5 sheets named:
+    Orders, Inventory, Pricing, Traffic, Logistics (case-insensitive).
+    Embedding is triggered once after all sheets are processed.
+    """
+    import io
+    import pandas as pd
+
+    _validate_excel(file)
+    snap_date = date.fromisoformat(snapshot_date) if snapshot_date else date.today()
+    content = await file.read()
+
+    results = {}
+    DOMAIN_MAP = {
+        "orders":    ingestion.ingest_orders,
+        "inventory": ingestion.ingest_inventory,
+        "pricing":   ingestion.ingest_pricing,
+        "traffic":   ingestion.ingest_traffic,
+        "logistics": ingestion.ingest_logistics,
+    }
+
+    try:
+        # If it's a CSV, it's just a single sheet.
+        if file.filename.endswith(".csv") or file.content_type == "text/csv":
+            try:
+                df = pd.read_csv(io.BytesIO(content))
+                
+                # Infer domain
+                cols = set(str(c).strip().lower() for c in df.columns)
+                inferred = "orders"
+                if "available stock" in cols or "available_stock" in cols or "stock" in cols:
+                    inferred = "inventory"
+                elif "cost price" in cols or "cost_price" in cols or "mrp" in cols:
+                    inferred = "pricing"
+                elif "impressions" in cols or "page views" in cols or "ad spend" in cols:
+                    inferred = "traffic"
+                elif "tracking id" in cols or "courier" in cols or "rto" in cols:
+                    inferred = "logistics"
+                    
+                results[inferred] = await DOMAIN_MAP[inferred](db, df, seller_id, snap_date)
+                
+            except Exception as e:
+                logger.error("[Upload] CSV processing failed: %s", e, exc_info=True)
+                raise HTTPException(400, f"Failed to read CSV: {e}")
+                
+        else:
+            # Excel file processing (offload to thread pool to avoid blocking event loop)
+            from fastapi.concurrency import run_in_threadpool
+            
+            def _parse_excel_sync(bytes_content):
+                return pd.ExcelFile(io.BytesIO(bytes_content), engine="openpyxl")
+            
+            xl = await run_in_threadpool(_parse_excel_sync, content)
+            sheet_names_lower = {s.strip().lower(): s for s in xl.sheet_names}
+            found_any = False
+            
+            for domain, fn in DOMAIN_MAP.items():
+                if domain in sheet_names_lower:
+                    found_any = True
+                    # Parsing sheets can also be slow, offload it
+                    sheet_df = await run_in_threadpool(xl.parse, sheet_names_lower[domain])
+                    results[domain] = await fn(db, sheet_df, seller_id, snap_date)
+
+            if not found_any and len(xl.sheet_names) == 1:
+                sheet_df = xl.parse(xl.sheet_names[0])
+                cols = set(str(c).strip().lower() for c in sheet_df.columns)
+                
+                inferred = "orders"
+                if "available stock" in cols or "available_stock" in cols or "stock" in cols:
+                    inferred = "inventory"
+                elif "cost price" in cols or "cost_price" in cols or "mrp" in cols:
+                    inferred = "pricing"
+                elif "impressions" in cols or "page views" in cols or "ad spend" in cols:
+                    inferred = "traffic"
+                elif "tracking id" in cols or "courier" in cols or "rto" in cols:
+                    inferred = "logistics"
+                    
+                results[inferred] = await DOMAIN_MAP[inferred](db, sheet_df, seller_id, snap_date)
+
+        if not results:
+            raise HTTPException(400, "No recognizable sheets found. Expected: Orders, Inventory, Pricing, Traffic, Logistics")
+
+        # Trigger one embed job for all domains processed
+        logger.info("[Upload] Finished multi-sheet processing, triggering embedding.")
+        await _trigger_embed(seller_id, snap_date)
+
+        return {"status": "ok", "results": results, "snapshot_date": str(snap_date), "embedding": "queued"}
+    except Exception as e:
+        logger.error("[Upload] Full upload failed: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))

app/routes/websockets.py

@@ -0,0 +1,77 @@
+from typing import Dict, List
+import json
+import asyncio
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+router = APIRouter()
+
+class ConnectionManager:
+    def __init__(self):
+        # Maps seller_id -> list of active WebSocket connections
+        self.active_connections: Dict[str, List[WebSocket]] = {}
+
+    async def connect(self, websocket: WebSocket, seller_id: str):
+        await websocket.accept()
+        if seller_id not in self.active_connections:
+            self.active_connections[seller_id] = []
+        self.active_connections[seller_id].append(websocket)
+
+    def disconnect(self, websocket: WebSocket, seller_id: str):
+        if seller_id in self.active_connections:
+            self.active_connections[seller_id].remove(websocket)
+            if not self.active_connections[seller_id]:
+                del self.active_connections[seller_id]
+
+    async def send_personal_message(self, message: str, websocket: WebSocket):
+        await websocket.send_text(message)
+
+    async def broadcast(self, message: dict, seller_id: str):
+        if seller_id in self.active_connections:
+            for connection in self.active_connections[seller_id]:
+                try:
+                    await connection.send_text(json.dumps(message))
+                except Exception:
+                    pass
+
+    async def listen_to_redis(self):
+        import redis.asyncio as aioredis
+        from app.core.config import settings
+        
+        while True:
+            try:
+                redis_client = aioredis.from_url(settings.REDIS_URL, decode_responses=True)
+                pubsub = redis_client.pubsub()
+                await pubsub.psubscribe("channel:*")
+                
+                async for message in pubsub.listen():
+                    if message["type"] == "pmessage":
+                        # channel name is like "channel:seller_id"
+                        channel = message["channel"]
+                        seller_id = channel.split(":")[1]
+                        data = message["data"]
+                        try:
+                            payload = json.loads(data)
+                            await self.broadcast(payload, seller_id)
+                        except Exception:
+                            pass
+            except Exception as e:
+                # Reconnect on error
+                await asyncio.sleep(5)
+
+manager = ConnectionManager()
+
+
+
+@router.websocket("/ws/{seller_id}")
+async def websocket_endpoint(websocket: WebSocket, seller_id: str):
+    """
+    WebSocket endpoint for the UI to subscribe to real-time progress events.
+    """
+    await manager.connect(websocket, seller_id)
+    try:
+        while True:
+            # We don't strictly need to receive data from the client,
+            # but we need to keep the connection open and listen for disconnects
+            data = await websocket.receive_text()
+    except WebSocketDisconnect:
+        manager.disconnect(websocket, seller_id)

app/services/ai_agent_client.py

@@ -0,0 +1,128 @@
+import os
+from typing import Dict, Any, Optional
+import httpx
+import logging
+
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+# Using httpx for async requests
+async def trigger_simulation(
+    seller_id: str, 
+    time_window_start: str, 
+    time_window_end: str, 
+    snapshot_data: Dict[str, Any]
+) -> Optional[Dict[str, Any]]:
+    """
+    Sends an async POST request to the ai_agents service to run a multi-agent simulation.
+    """
+    url = f"{settings.AI_AGENTS_URL}/api/v1/simulate"
+    
+    payload = {
+        "seller_id": seller_id,
+        "time_window_start": time_window_start,
+        "time_window_end": time_window_end,
+        "snapshot_data": snapshot_data
+    }
+    
+    try:
+        # Increase timeout as agent simulations can take a while (e.g. 60+ seconds)
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            logger.info(f"Triggering AI agent simulation for {seller_id} to URL {url}")
+            response = await client.post(url, json=payload)
+            response.raise_for_status()
+            
+            data = response.json()
+            return data
+            
+    except httpx.HTTPError as exc:
+        logger.error(f"HTTP Exception while connecting to AI agents API: {exc}")
+        return None
+    except Exception as exc:
+        logger.error(f"Error calling AI agents API: {exc}")
+        return None
+
+async def trigger_simulation_stream(
+    seller_id: str, 
+    time_window_start: str, 
+    time_window_end: str, 
+    snapshot_data: Dict[str, Any]
+):
+    """
+    Sends an async POST request to the ai_agents service and yields the SSE streaming response.
+    """
+    url = f"{settings.AI_AGENTS_URL}/api/v1/simulate/stream"
+    
+    payload = {
+        "seller_id": seller_id,
+        "time_window_start": time_window_start,
+        "time_window_end": time_window_end,
+        "snapshot_data": snapshot_data
+    }
+    
+    try:
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            async with client.stream("POST", url, json=payload) as response:
+                response.raise_for_status()
+                async for chunk in response.aiter_bytes():
+                    yield chunk
+    except Exception as exc:
+        import json
+        logger.error(f"Error streaming from AI agents API: {exc}")
+        yield f"data: {json.dumps({'error': str(exc)})}\n\n".encode('utf-8')
+
+async def trigger_whatif_stream(seller_id: str, scenario: str):
+    """
+    Sends an async POST request to the ai_agents service's whatif endpoint and yields the SSE response.
+    """
+    url = f"{settings.AI_AGENTS_URL}/api/v1/simulate/whatif"
+    
+    payload = {
+        "seller_id": seller_id,
+        "scenario": scenario
+    }
+    
+    try:
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            async with client.stream("POST", url, json=payload) as response:
+                response.raise_for_status()
+                async for chunk in response.aiter_bytes():
+                    yield chunk
+    except Exception as exc:
+        import json
+        logger.error(f"Error streaming what-if from AI agents API: {exc}")
+        yield f"data: {json.dumps({'error': str(exc)})}\n\n".encode('utf-8')
+
+async def trigger_product_analysis(
+    seller_id: str, 
+    product_id: str,
+    product_data: Dict[str, Any]
+) -> Optional[Dict[str, Any]]:
+    """
+    Sends an async POST request to the ai_agents service to run a per-product analysis.
+    """
+    url = f"{settings.AI_AGENTS_URL}/api/v1/analyze/product"
+    
+    payload = {
+        "seller_id": seller_id,
+        "product_id": product_id,
+        "product_data": product_data
+    }
+    
+    try:
+        # Increase timeout as agent simulations can take a while
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            logger.info(f"Triggering AI product analysis for product {product_id} to URL {url}")
+            response = await client.post(url, json=payload)
+            response.raise_for_status()
+            
+            data = response.json()
+            return data
+            
+    except httpx.HTTPError as exc:
+        logger.error(f"HTTP Exception while connecting to AI agents API: {exc}")
+        return None
+    except Exception as exc:
+        logger.error(f"Error calling AI agents API for product analysis: {exc}")
+        return None

app/services/embeddings.py

@@ -0,0 +1,207 @@
+"""
+Embedding Service — sentence-transformers + pgvector
+Generates 384-dim vectors and stores them in PostgreSQL via pgvector.
+"""
+import asyncio
+from datetime import date
+from typing import Optional
+
+import numpy as np
+from sqlalchemy import select, delete
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+from app.models.models import ProductEmbedding, InsightEmbedding
+from app.core.config import settings
+
+# Lazy-loaded pipeline instance
+_model = None
+_lock  = asyncio.Lock()
+
+
+async def _get_model():
+    """Lazily load the sentence-transformers model in a thread."""
+    global _model
+    if _model is not None:
+        return _model
+    async with _lock:
+        if _model is not None:
+            return _model
+        loop = asyncio.get_event_loop()
+        _model = await loop.run_in_executor(None, _load_model)
+    return _model
+
+
+def _load_model():
+    from sentence_transformers import SentenceTransformer
+    print(f"[Embedding] Loading model '{settings.EMBEDDING_MODEL}'...")
+    m = SentenceTransformer(settings.EMBEDDING_MODEL)
+    print("[Embedding] Model ready ✅")
+    return m
+
+
+async def embed_text(text: str) -> list[float]:
+    """Return a 384-dim embedding vector for a text string."""
+    model = await _get_model()
+    loop  = asyncio.get_event_loop()
+    vec   = await loop.run_in_executor(None, lambda: model.encode(text, normalize_embeddings=True))
+    return vec.tolist()
+
+
+async def embed_batch(texts: list[str]) -> list[list[float]]:
+    """Batch embed multiple texts for efficiency."""
+    model  = await _get_model()
+    loop   = asyncio.get_event_loop()
+    vecs   = await loop.run_in_executor(None, lambda: model.encode(texts, normalize_embeddings=True, batch_size=32))
+    return [v.tolist() for v in vecs]
+
+
+# ── Singleton service ──────────────────────────────────────────
+class EmbeddingService:
+    async def preload(self):
+        """Pre-warm the model at startup to prevent cold-start lag."""
+        await _get_model()
+
+    async def upsert_product_embedding(
+        self,
+        db: AsyncSession,
+        seller_id: str,
+        product_id: str,
+        summary_text: str,
+        embed_date: Optional[date] = None,
+        embed_type: str = "daily_snapshot",
+        metadata: Optional[dict] = None,
+    ) -> ProductEmbedding:
+        embed_date = embed_date or date.today()
+        vector = await embed_text(summary_text)
+
+        # Upsert (on conflict update vector + text)
+        stmt = (
+            pg_insert(ProductEmbedding)
+            .values(
+                seller_id=seller_id,
+                product_id=product_id,
+                embed_date=embed_date,
+                embed_type=embed_type,
+                summary_text=summary_text,
+                embedding=vector,
+                meta=metadata or {},       # ORM attr is 'meta' (column name is 'metadata')
+            )
+            .on_conflict_do_update(
+                index_elements=["seller_id", "product_id", "embed_date", "embed_type"],
+                set_={"summary_text": summary_text, "embedding": vector, "metadata": metadata or {}},
+            )
+        )
+        await db.execute(stmt)
+        await db.commit()
+        return vector
+
+    async def find_similar_products(
+        self,
+        db: AsyncSession,
+        seller_id: str,
+        query_text: str,
+        limit: int = 5,
+        embed_type: str = "daily_snapshot",
+    ) -> list[dict]:
+        """
+        Find similar products using pgvector cosine similarity.
+        Returns product_id, summary_text, and similarity score.
+        """
+        query_vector = await embed_text(query_text)
+        # Use raw SQL for pgvector operator <=> (cosine distance)
+        from sqlalchemy import text
+        sql = text("""
+            SELECT
+                pe.product_id,
+                pe.summary_text,
+                pe.embed_date,
+                pe.metadata,
+                1 - (pe.embedding <=> cast(:vec AS vector)) AS similarity
+            FROM product_embeddings pe
+            WHERE pe.seller_id = :seller_id
+              AND pe.embed_type = :embed_type
+            ORDER BY pe.embedding <=> cast(:vec AS vector)
+            LIMIT :limit
+        """)
+        result = await db.execute(sql, {
+            "vec": str(query_vector),
+            "seller_id": str(seller_id),
+            "embed_type": embed_type,
+            "limit": limit,
+        })
+        rows = result.fetchall()
+        return [
+            {
+                "product_id": str(r.product_id),
+                "summary_text": r.summary_text,
+                "embed_date": str(r.embed_date),
+                "metadata": r.metadata,
+                "similarity": float(r.similarity),
+            }
+            for r in rows
+        ]
+
+    async def store_insight(
+        self,
+        db: AsyncSession,
+        seller_id: str,
+        insight_text: str,
+        insight_type: str,
+        insight_date: Optional[date] = None,
+        metadata: Optional[dict] = None,
+    ):
+        insight_date = insight_date or date.today()
+        vector = await embed_text(insight_text)
+        row = InsightEmbedding(
+            seller_id=seller_id,
+            insight_date=insight_date,
+            insight_type=insight_type,
+            insight_text=insight_text,
+            embedding=vector,
+            meta=metadata or {},            # ORM attr is 'meta' (column name is 'metadata')
+        )
+        db.add(row)
+        await db.commit()
+        return row
+
+    async def find_similar_insights(
+        self,
+        db: AsyncSession,
+        seller_id: str,
+        query_text: str,
+        limit: int = 5,
+    ) -> list[dict]:
+        query_vector = await embed_text(query_text)
+        from sqlalchemy import text
+        sql = text("""
+            SELECT
+                ie.insight_type,
+                ie.insight_text,
+                ie.insight_date,
+                ie.metadata,
+                1 - (ie.embedding <=> cast(:vec AS vector)) AS similarity
+            FROM insight_embeddings ie
+            WHERE ie.seller_id = :seller_id
+            ORDER BY ie.embedding <=> cast(:vec AS vector)
+            LIMIT :limit
+        """)
+        result = await db.execute(sql, {
+            "vec": str(query_vector),
+            "seller_id": str(seller_id),
+            "limit": limit,
+        })
+        rows = result.fetchall()
+        return [
+            {
+                "insight_type": r.insight_type,
+                "insight_text": r.insight_text,
+                "insight_date": str(r.insight_date),
+                "metadata": r.metadata,
+                "similarity": float(r.similarity),
+            }
+            for r in rows
+        ]
+
+
+embedding_service = EmbeddingService()

app/services/ingestion.py

@@ -0,0 +1,646 @@
+"""
+Excel Ingestion Service
+Parses uploaded Excel sheets and bulk-inserts into PostgreSQL.
+Each domain has its own parser that maps flexible column names to DB columns.
+"""
+import io
+import uuid
+from datetime import date, datetime
+from typing import Optional
+
+import pandas as pd
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+from app.models.models import (
+    Product, Order, InventorySnapshot, PricingSnapshot,
+    TrafficMetric, LogisticsMetric,
+)
+
+
+# ── Column aliases ─────────────────────────────────────────────
+# Maps flexible Excel column names → canonical DB column name
+ORDER_COL_MAP = {
+    "order id": "external_order_id", "order_id": "external_order_id", "id": "external_order_id",
+    "marketplace": "marketplace", "platform": "marketplace", "channel": "marketplace",
+    "sku": "sku", "product sku": "sku", "item sku": "sku",
+    "status": "order_status", "order_status": "order_status", "order status": "order_status",
+    "quantity": "quantity", "qty": "quantity", "qty.": "quantity",
+    "selling price": "selling_price", "selling_price": "selling_price", "price": "selling_price", "amount": "selling_price",
+    "discount": "discount",
+    "tax": "tax",
+    "shipping fee": "shipping_fee", "shipping_fee": "shipping_fee", "shipping": "shipping_fee",
+    "order date": "order_date", "order_date": "order_date", "date": "order_date",
+    "delivery date": "delivery_date", "delivery_date": "delivery_date",
+    "return": "return_flag", "return_flag": "return_flag",
+    "cancellation reason": "cancellation_reason", "cancellation_reason": "cancellation_reason",
+    # Customer / payment fields (may be absent — handled gracefully)
+    "customer name": "customer_name", "customer_name": "customer_name",
+    "customer email": "customer_email", "customer_email": "customer_email",
+    "payment mode": "payment_mode", "payment_mode": "payment_mode", "payment": "payment_mode",
+    "customer city": "customer_city", "customer_city": "customer_city",
+    "customer state": "customer_state", "customer_state": "customer_state",
+}
+
+INVENTORY_COL_MAP = {
+    "sku": "sku", "product sku": "sku",
+    "marketplace": "marketplace",
+    "available stock": "available_stock", "available_stock": "available_stock", "stock": "available_stock",
+    "reserved stock": "reserved_stock", "reserved_stock": "reserved_stock",
+    "reorder threshold": "reorder_threshold", "reorder_threshold": "reorder_threshold",
+    "days of stock": "days_of_stock", "days_of_stock": "days_of_stock",
+    "warehouse": "warehouse_location", "warehouse_location": "warehouse_location",
+    "snapshot date": "snapshot_date", "snapshot_date": "snapshot_date", "date": "snapshot_date",
+}
+
+PRICING_COL_MAP = {
+    "sku": "sku", "product sku": "sku",
+    "marketplace": "marketplace",
+    "selling price": "selling_price", "selling_price": "selling_price",
+    "cost price": "cost_price", "cost_price": "cost_price",
+    "mrp": "mrp",
+    "commission %": "commission_pct", "commission_pct": "commission_pct",
+    "commission amount": "commission_amount", "commission_amount": "commission_amount",
+    "discount %": "discount_percentage", "discount_percentage": "discount_percentage",
+    "snapshot date": "snapshot_date", "date": "snapshot_date",
+}
+
+TRAFFIC_COL_MAP = {
+    "sku": "sku", "product sku": "sku",
+    "marketplace": "marketplace",
+    "date": "metric_date", "metric date": "metric_date", "metric_date": "metric_date",
+    "impressions": "impressions",
+    "clicks": "clicks",
+    "sessions": "sessions",
+    "page views": "page_views", "page_views": "page_views",
+    "orders": "orders",
+    "ad spend": "ad_spend", "ad_spend": "ad_spend",
+    "revenue from ads": "revenue_from_ads", "revenue_from_ads": "revenue_from_ads",
+}
+
+LOGISTICS_COL_MAP = {
+    "order id": "external_order_id", "order_id": "external_order_id",
+    "marketplace": "marketplace",
+    "courier": "courier_name", "courier_name": "courier_name",
+    "carrier": "courier_name",                             # test_dataset alias
+    "tracking id": "tracking_id", "tracking_id": "tracking_id",
+    "shipment id": "tracking_id", "shipment_id": "tracking_id",  # test_dataset alias
+    "fulfillment type": "fulfillment_type", "fulfillment_type": "fulfillment_type",
+    "warehouse id": "warehouse_id", "warehouse_id": "warehouse_id",
+    "dispatch date": "dispatch_date", "dispatch_date": "dispatch_date",
+    "expected delivery": "expected_delivery",
+    "estimated delivery": "expected_delivery", "estimated_delivery": "expected_delivery",  # test_dataset alias
+    "actual delivery": "actual_delivery", "actual_delivery": "actual_delivery",
+    "delivery status": "delivery_status", "delivery_status": "delivery_status", "status": "delivery_status",
+    "rto": "rto_flag", "rto_flag": "rto_flag",
+    "rto reason": "rto_reason", "rto_reason": "rto_reason",
+    "snapshot date": "snapshot_date", "date": "snapshot_date",
+    "shipping cost": "_shipping_cost", "shipping_cost": "_shipping_cost",  # ignored safely
+}
+
+
+# ── Helpers ────────────────────────────────────────────────────
+
+def _normalise_columns(df: pd.DataFrame, col_map: dict) -> pd.DataFrame:
+    """Lower-case, replace underscores with spaces, and intelligently map columns."""
+    rename = {}
+    for original_col in df.columns:
+        c = str(original_col).strip().lower()
+        c_space = c.replace("_", " ")
+
+        # 1. Exact match
+        if c in col_map:
+            rename[original_col] = col_map[c]
+            continue
+            
+        # 2. Match after replacing underscore
+        if c_space in col_map:
+            rename[original_col] = col_map[c_space]
+            continue
+            
+        # 3. Fuzzy Heuristic Substring Match for critical columns
+        if "sku" in c:
+            rename[original_col] = "sku"
+        elif "qty" in c or "quantity" in c:
+            rename[original_col] = "quantity"
+        elif "price" in c and ("sell" in c or "selling" in c):
+            rename[original_col] = "selling_price"
+        elif "price" in c and "cost" in c:
+            rename[original_col] = "cost_price"
+        elif "mrp" in c:
+            rename[original_col] = "mrp"
+        elif "market" in c or "platform" in c or "channel" in c:
+            rename[original_col] = "marketplace"
+        elif "order" in c and "id" in c:
+            rename[original_col] = "external_order_id"
+        elif "shipment" in c and "id" in c:
+            rename[original_col] = "tracking_id"
+        elif "stock" in c and "avail" in c:
+            rename[original_col] = "available_stock"
+        elif "stock" in c and "reserv" in c:
+            rename[original_col] = "reserved_stock"
+        elif "stock" in c:
+            rename[original_col] = "available_stock" # fallback
+        elif "spend" in c and "ad" in c:
+            rename[original_col] = "ad_spend"
+        elif "return" in c and "ad" in c:
+            rename[original_col] = "revenue_from_ads"
+        elif "carrier" in c:
+            rename[original_col] = "courier_name"
+        elif "estimated" in c and "deliver" in c:
+            rename[original_col] = "expected_delivery"
+            
+    return df.rename(columns=rename)
+
+
+from datetime import date, datetime, timedelta
+
+def _parse_date(val) -> Optional[date]:
+    if pd.isna(val):
+        return None
+    if isinstance(val, (date, datetime)):
+        return val if isinstance(val, date) else val.date()
+    
+    # Handle Excel serial dates (floats)
+    try:
+        if isinstance(val, (int, float)) or (isinstance(val, str) and val.replace('.','',1).isdigit()):
+            float_val = float(val)
+            # Excel dates are days since Dec 30, 1899
+            return (datetime(1899, 12, 30) + timedelta(days=float_val)).date()
+    except Exception:
+        pass
+
+    try:
+        return pd.to_datetime(val).date()
+    except Exception:
+        return None
+
+
+def _safe_float(val, default=0.0) -> float:
+    try:
+        return float(val) if not pd.isna(val) else default
+    except Exception:
+        return default
+
+
+def _safe_int(val, default=0) -> int:
+    try:
+        return int(val) if not pd.isna(val) else default
+    except Exception:
+        return default
+
+
+async def _resolve_products_batch(db: AsyncSession, seller_id: str, skus: list[str], marketplaces: list[str], product_cache: dict):
+    """
+    Efficiently resolves a list of (sku, marketplace) pairs to product_ids in batches.
+    """
+    # Filter out what's already in cache
+    missing_keys = []
+    seen_keys = set()
+    for s, m in zip(skus, marketplaces):
+        key = (s, m)
+        if key not in product_cache and key not in seen_keys:
+            missing_keys.append(key)
+            seen_keys.add(key)
+    
+    if not missing_keys:
+        return
+
+    # Step 1: Query existing products
+    # We use a tuple-based IN clause for (sku, marketplace)
+    from sqlalchemy import tuple_
+    result = await db.execute(
+        select(Product.product_id, Product.sku, Product.marketplace).where(
+            Product.seller_id == seller_id,
+            tuple_(Product.sku, Product.marketplace).in_(missing_keys)
+        )
+    )
+    
+    found_keys = set()
+    for row in result:
+        key = (row.sku, row.marketplace)
+        product_cache[key] = str(row.product_id)
+        found_keys.add(key)
+    
+    # Step 2: Bulk-insert missing products
+    really_missing = [k for k in missing_keys if k not in found_keys]
+    if really_missing:
+        new_products = [
+            Product(
+                seller_id=seller_id,
+                sku=sku,
+                product_name=sku,
+                marketplace=m,
+                is_active=True
+            ) for sku, m in really_missing
+        ]
+        db.add_all(new_products)
+        await db.flush()
+        
+        for p in new_products:
+            product_cache[(p.sku, p.marketplace)] = str(p.product_id)
+
+async def _resolve_product(db: AsyncSession, seller_id: str, sku: str, marketplace: str, product_cache: dict) -> Optional[str]:
+    """Single resolve fallback (uses batch logic internally)."""
+    cache_key = (sku, marketplace)
+    if cache_key in product_cache:
+        return product_cache[cache_key]
+    
+    await _resolve_products_batch(db, seller_id, [sku], [marketplace], product_cache)
+    return product_cache.get(cache_key)
+
+
+# ── Domain Parsers ──────────────────────────────────────────────
+
+async def ingest_orders(db: AsyncSession, df: pd.DataFrame, seller_id: str, snapshot_date: date) -> dict:
+    df = _normalise_columns(df, ORDER_COL_MAP)
+
+    rows_inserted = 0
+    rows_skipped  = 0
+    product_cache = {}
+    
+    # Pre-warm product cache in one batch
+    skus = df.get("sku", pd.Series(dtype=str)).astype(str).str.strip().tolist()
+    marketplaces = df.get("marketplace", pd.Series(dtype=str)).astype(str).str.strip().tolist()
+    await _resolve_products_batch(db, seller_id, skus, marketplaces, product_cache)
+
+    values_list = []
+    
+    for row in df.itertuples(index=False):
+        row_dict = row._asdict()
+        try:
+            sku         = str(row_dict.get("sku", "")).strip()
+            if not sku or sku == "nan":
+                sku = "UNKNOWN-SKU"
+                
+            marketplace = str(row_dict.get("marketplace", "unknown")).strip()
+            product_id = await _resolve_product(db, seller_id, sku, marketplace, product_cache)
+
+            # Handle return_flag — may be string 'True'/'False' or bool
+            raw_return = row_dict.get("return_flag", False)
+            if isinstance(raw_return, str):
+                return_flag = raw_return.strip().lower() in ("true", "1", "yes")
+            else:
+                return_flag = bool(raw_return)
+
+            values_list.append({
+                "external_order_id":   str(row_dict.get("external_order_id", "")) or None,
+                "seller_id":           seller_id,
+                "product_id":          product_id,
+                "marketplace":         marketplace,
+                "order_status":        str(row_dict.get("order_status", "unknown")),
+                "quantity":            _safe_int(row_dict.get("quantity"), 1),
+                "selling_price":       _safe_float(row_dict.get("selling_price")),
+                "discount":            _safe_float(row_dict.get("discount")),
+                "tax":                 _safe_float(row_dict.get("tax")),
+                "shipping_fee":        _safe_float(row_dict.get("shipping_fee")),
+                "order_date":          _parse_date(row_dict.get("order_date")) or snapshot_date,
+                "delivery_date":       _parse_date(row_dict.get("delivery_date")),
+                "return_flag":         return_flag,
+                "cancellation_reason": str(row_dict.get("cancellation_reason", "")) or None,
+                "customer_name":       str(row_dict.get("customer_name", "")).strip() or None,
+                "customer_email":      str(row_dict.get("customer_email", "")).strip() or None,
+                "payment_mode":        str(row_dict.get("payment_mode", "")).strip() or None,
+                "snapshot_date":       snapshot_date,
+            })
+            rows_inserted += 1
+        except Exception as e:
+            logger.warning(f"Error skipping row in orders: {e}")
+            rows_skipped += 1
+
+    if values_list:
+        # Deduplicate values list based on ON CONFLICT key
+        seen = {}
+        no_eid = []
+        for v in values_list:
+            if v.get("external_order_id"):
+                seen[v["external_order_id"]] = v
+            else:
+                no_eid.append(v)
+        values_list = list(seen.values()) + no_eid
+        
+        # Split into two paths: rows WITH an external_order_id (upsert) and
+        # rows WITHOUT one (plain insert) to avoid NULL conflict key issues.
+        with_eid = [v for v in values_list if v.get("external_order_id")]
+        without_eid = [v for v in values_list if not v.get("external_order_id")]
+
+        for i in range(0, len(with_eid), 1000):
+            stmt = pg_insert(Order).values(with_eid[i:i+1000]).on_conflict_do_update(
+                index_elements=["external_order_id"],
+                index_where=Order.external_order_id.isnot(None),
+                set_={
+                    "order_status": pg_insert(Order).excluded.order_status,
+                    "delivery_date": pg_insert(Order).excluded.delivery_date,
+                },
+            )
+            await db.execute(stmt)
+
+        for i in range(0, len(without_eid), 1000):
+            await db.execute(pg_insert(Order).values(without_eid[i:i+1000]).on_conflict_do_nothing())
+
+    await db.commit()
+    return {"inserted": rows_inserted, "skipped": rows_skipped, "domain": "orders"}
+
+
+async def ingest_inventory(db: AsyncSession, df: pd.DataFrame, seller_id: str, snapshot_date: date) -> dict:
+    df = _normalise_columns(df, INVENTORY_COL_MAP)
+
+    rows_inserted = 0
+    rows_skipped  = 0
+    product_cache = {}
+    
+    # Pre-warm product cache in one batch
+    skus = df.get("sku", pd.Series(dtype=str)).astype(str).str.strip().tolist()
+    marketplaces = df.get("marketplace", pd.Series(dtype=str)).astype(str).str.strip().tolist()
+    await _resolve_products_batch(db, seller_id, skus, marketplaces, product_cache)
+
+    # Enrich Product records if Inventory sheet has product_name/category
+    has_product_name = "product_name" in df.columns
+    has_category     = "category" in df.columns
+    if has_product_name or has_category:
+        for row in df.itertuples(index=False):
+            row_dict = row._asdict()
+            sku = str(row_dict.get("sku", "")).strip()
+            marketplace = str(row_dict.get("marketplace", "unknown")).strip()
+            cache_key = (sku, marketplace)
+            pid = product_cache.get(cache_key)
+            if not pid:
+                continue
+            updates = {}
+            if has_product_name:
+                pname = str(row_dict.get("product_name", "")).strip()
+                if pname and pname != "nan":
+                    updates["product_name"] = pname
+            if has_category:
+                cat = str(row_dict.get("category", "")).strip()
+                if cat and cat != "nan":
+                    updates["category"] = cat
+            if updates:
+                from sqlalchemy import update
+                await db.execute(
+                    update(Product).where(Product.product_id == pid).values(**updates)
+                )
+        await db.flush()
+
+    values_list = []
+
+    # Use itertuples for massive speedup
+    for row in df.itertuples(index=False):
+        row_dict = row._asdict()
+        try:
+            sku         = str(row_dict.get("sku", "")).strip()
+            if not sku or sku == "nan":
+                sku = "UNKNOWN-SKU"
+                
+            marketplace = str(row_dict.get("marketplace", "unknown")).strip()
+
+            product_id = await _resolve_product(db, seller_id, sku, marketplace, product_cache)
+            snap_date  = _parse_date(row_dict.get("snapshot_date")) or snapshot_date
+
+            values_list.append({
+                "seller_id":         seller_id,
+                "product_id":        product_id,
+                "marketplace":       marketplace,
+                "available_stock":   _safe_int(row_dict.get("available_stock")),
+                "reserved_stock":    _safe_int(row_dict.get("reserved_stock")),
+                "reorder_threshold": _safe_int(row_dict.get("reorder_threshold"), 10),
+                "days_of_stock":     _safe_float(row_dict.get("days_of_stock")) or None,
+                "warehouse_location": str(row_dict.get("warehouse_location", "")) or None,
+                "snapshot_date":     snap_date,
+            })
+            rows_inserted += 1
+        except Exception as e:
+            logger.warning(f"Error skipping row in inventory: {e}")
+            rows_skipped += 1
+
+    if values_list:
+        seen = {}
+        for v in values_list:
+            key = (v["seller_id"], v["product_id"], v["marketplace"], v["snapshot_date"])
+            seen[key] = v
+        values_list = list(seen.values())
+        
+        for i in range(0, len(values_list), 1000):
+            stmt = pg_insert(InventorySnapshot).values(values_list[i:i+1000]).on_conflict_do_update(
+                index_elements=["seller_id", "product_id", "marketplace", "snapshot_date"],
+                set_={
+                    "available_stock": pg_insert(InventorySnapshot).excluded.available_stock,
+                    "reserved_stock": pg_insert(InventorySnapshot).excluded.reserved_stock,
+                },
+            )
+            await db.execute(stmt)
+
+    await db.commit()
+    return {"inserted": rows_inserted, "skipped": rows_skipped, "domain": "inventory"}
+
+
+async def ingest_pricing(db: AsyncSession, df: pd.DataFrame, seller_id: str, snapshot_date: date) -> dict:
+    df = _normalise_columns(df, PRICING_COL_MAP)
+
+    rows_inserted = 0
+    rows_skipped  = 0
+    product_cache = {}
+    
+    # Pre-warm product cache in one batch
+    skus = df.get("sku", pd.Series(dtype=str)).astype(str).str.strip().tolist()
+    marketplaces = df.get("marketplace", pd.Series(dtype=str)).astype(str).str.strip().tolist()
+    await _resolve_products_batch(db, seller_id, skus, marketplaces, product_cache)
+
+    values_list = []
+
+    for row in df.itertuples(index=False):
+        row_dict = row._asdict()
+        try:
+            sku         = str(row_dict.get("sku", "")).strip()
+            if not sku or sku == "nan":
+                sku = "UNKNOWN-SKU"
+                
+            marketplace = str(row_dict.get("marketplace", "unknown")).strip()
+
+            product_id  = await _resolve_product(db, seller_id, sku, marketplace, product_cache)
+            snap_date   = _parse_date(row_dict.get("snapshot_date")) or snapshot_date
+            sell_price  = _safe_float(row_dict.get("selling_price"))
+            cost_price  = _safe_float(row_dict.get("cost_price")) or None
+            comm_amount = _safe_float(row_dict.get("commission_amount"))
+
+            values_list.append({
+                "seller_id":           seller_id,
+                "product_id":          product_id,
+                "marketplace":         marketplace,
+                "selling_price":       sell_price,
+                "cost_price":          cost_price,
+                "mrp":                 _safe_float(row_dict.get("mrp")) or None,
+                "commission_pct":      _safe_float(row_dict.get("commission_pct")),
+                "commission_amount":   comm_amount,
+                "discount_percentage": _safe_float(row_dict.get("discount_percentage")),
+                "snapshot_date":       snap_date,
+            })
+            rows_inserted += 1
+        except Exception as e:
+            logger.warning(f"Error skipping row in pricing: {e}")
+            rows_skipped += 1
+
+    if values_list:
+        seen = {}
+        for v in values_list:
+            key = (v["seller_id"], v["product_id"], v["marketplace"], v["snapshot_date"])
+            seen[key] = v
+        values_list = list(seen.values())
+        
+        for i in range(0, len(values_list), 1000):
+            stmt = pg_insert(PricingSnapshot).values(values_list[i:i+1000]).on_conflict_do_update(
+                index_elements=["seller_id", "product_id", "marketplace", "snapshot_date"],
+                set_={
+                    "selling_price": pg_insert(PricingSnapshot).excluded.selling_price,
+                    "cost_price": pg_insert(PricingSnapshot).excluded.cost_price
+                },
+            )
+            await db.execute(stmt)
+
+    await db.commit()
+    return {"inserted": rows_inserted, "skipped": rows_skipped, "domain": "pricing"}
+
+
+async def ingest_traffic(db: AsyncSession, df: pd.DataFrame, seller_id: str, snapshot_date: date) -> dict:
+    df = _normalise_columns(df, TRAFFIC_COL_MAP)
+
+    rows_inserted = 0
+    rows_skipped  = 0
+    product_cache = {}
+    
+    # Pre-warm product cache in one batch
+    skus = df.get("sku", pd.Series(dtype=str)).astype(str).str.strip().tolist()
+    marketplaces = df.get("marketplace", pd.Series(dtype=str)).astype(str).str.strip().tolist()
+    await _resolve_products_batch(db, seller_id, skus, marketplaces, product_cache)
+
+    values_list = []
+
+    for row in df.itertuples(index=False):
+        row_dict = row._asdict()
+        try:
+            sku         = str(row_dict.get("sku", "")).strip()
+            if not sku or sku == "nan":
+                sku = "UNKNOWN-SKU"
+                
+            marketplace = str(row_dict.get("marketplace", "unknown")).strip()
+
+            product_id  = await _resolve_product(db, seller_id, sku, marketplace, product_cache)
+            metric_date = _parse_date(row_dict.get("metric_date")) or snapshot_date
+
+            values_list.append({
+                "seller_id":        seller_id,
+                "product_id":       product_id,
+                "marketplace":      marketplace,
+                "metric_date":      metric_date,
+                "impressions":      _safe_int(row_dict.get("impressions")),
+                "clicks":           _safe_int(row_dict.get("clicks")),
+                "sessions":         _safe_int(row_dict.get("sessions")),
+                "page_views":       _safe_int(row_dict.get("page_views")),
+                "orders":           _safe_int(row_dict.get("orders")),
+                "ad_spend":         _safe_float(row_dict.get("ad_spend")),
+                "revenue_from_ads": _safe_float(row_dict.get("revenue_from_ads")),
+            })
+            rows_inserted += 1
+        except Exception as e:
+            logger.warning(f"Error skipping row in traffic: {e}")
+            rows_skipped += 1
+
+    if values_list:
+        seen = {}
+        for v in values_list:
+            key = (v["seller_id"], v["product_id"], v["marketplace"], v["metric_date"])
+            seen[key] = v
+        values_list = list(seen.values())
+        
+        for i in range(0, len(values_list), 1000):
+            stmt = pg_insert(TrafficMetric).values(values_list[i:i+1000]).on_conflict_do_update(
+                index_elements=["seller_id", "product_id", "marketplace", "metric_date"],
+                set_={
+                    "impressions": pg_insert(TrafficMetric).excluded.impressions,
+                    "clicks": pg_insert(TrafficMetric).excluded.clicks,
+                    "ad_spend": pg_insert(TrafficMetric).excluded.ad_spend,
+                },
+            )
+            await db.execute(stmt)
+
+    await db.commit()
+    return {"inserted": rows_inserted, "skipped": rows_skipped, "domain": "traffic"}
+
+
+async def ingest_logistics(db: AsyncSession, df: pd.DataFrame, seller_id: str, snapshot_date: date) -> dict:
+    df = _normalise_columns(df, LOGISTICS_COL_MAP)
+
+    rows_inserted = 0
+    rows_skipped  = 0
+    
+    values_list = []
+
+    for row in df.itertuples(index=False):
+        row_dict = row._asdict()
+        try:
+            marketplace = str(row_dict.get("marketplace", "unknown")).strip()
+            # tracking_id may have been mapped from shipment_id
+            raw_tid = row_dict.get("tracking_id", "")
+            ext_id = str(raw_tid).strip() if not pd.isna(raw_tid) else None
+            if ext_id == "nan" or ext_id == "":
+                ext_id = None
+
+            # Handle rto_flag — may be string 'True'/'False' or bool
+            raw_rto = row_dict.get("rto_flag", False)
+            if isinstance(raw_rto, str):
+                rto_flag = raw_rto.strip().lower() in ("true", "1", "yes")
+            else:
+                rto_flag = bool(raw_rto) if not pd.isna(raw_rto) else False
+
+            values_list.append({
+                "seller_id":          seller_id,
+                "marketplace":        marketplace,
+                "courier_name":       str(row_dict.get("courier_name", "")) or None,
+                "tracking_id":        ext_id,
+                "fulfillment_type":   str(row_dict.get("fulfillment_type", "seller")),
+                "warehouse_id":       str(row_dict.get("warehouse_id", "")) or None,
+                "dispatch_date":      _parse_date(row_dict.get("dispatch_date")),
+                "expected_delivery":  _parse_date(row_dict.get("expected_delivery")),
+                "actual_delivery":    _parse_date(row_dict.get("actual_delivery")),
+                "delivery_status":    str(row_dict.get("delivery_status", "unknown")),
+                "rto_flag":           rto_flag,
+                "rto_reason":         str(row_dict.get("rto_reason", "")) or None,
+                "snapshot_date":      _parse_date(row_dict.get("snapshot_date")) or snapshot_date,
+            })
+            rows_inserted += 1
+        except Exception as e:
+            logger.warning(f"Error skipping row in returns: {e}")
+            rows_skipped += 1
+
+    if values_list:
+        seen = {}
+        no_tid = []
+        for v in values_list:
+            if v.get("tracking_id"):
+                key = (v["seller_id"], v["tracking_id"], v["marketplace"], v["snapshot_date"])
+                seen[key] = v
+            else:
+                no_tid.append(v)
+        values_list = list(seen.values()) + no_tid
+        
+        # Split: rows with tracking_id can be upserted; rows without get plain inserts
+        with_tid = [v for v in values_list if v.get("tracking_id")]
+        without_tid = [v for v in values_list if not v.get("tracking_id")]
+
+        for i in range(0, len(with_tid), 1000):
+            stmt = pg_insert(LogisticsMetric).values(with_tid[i:i+1000]).on_conflict_do_update(
+                index_elements=["seller_id", "tracking_id", "marketplace", "snapshot_date"],
+                index_where=LogisticsMetric.tracking_id.isnot(None),
+                set_={
+                    "delivery_status": pg_insert(LogisticsMetric).excluded.delivery_status,
+                    "actual_delivery": pg_insert(LogisticsMetric).excluded.actual_delivery,
+                },
+            )
+            await db.execute(stmt)
+
+        for i in range(0, len(without_tid), 1000):
+            await db.execute(pg_insert(LogisticsMetric).values(without_tid[i:i+1000]).on_conflict_do_nothing())
+
+    await db.commit()
+    return {"inserted": rows_inserted, "skipped": rows_skipped, "domain": "logistics"}

app/services/tasks.py

@@ -0,0 +1,421 @@
+"""
+app/tasks/embed.py
+Celery tasks for background embedding.
+
+Tasks:
+  auto_embed         — triggered after each Excel upload (per seller, per date)
+  nightly_embed_all  — Celery Beat scheduled task, runs daily at 2 AM IST
+  embed_single_product — embeds a single product summary (used by /ai/embed/product)
+"""
+import asyncio
+import logging
+from datetime import date, timedelta
+
+from celery import shared_task
+
+logger = logging.getLogger(__name__)
+
+
+# ── Core async embedding logic ─────────────────────────────────
+async def _run_embed(seller_id: str, snap_date_str: str) -> int:
+    """
+    Fetch product snapshot for seller + date, batch-encode summaries,
+    bulk-upsert into Supabase product_embeddings.
+    Returns number of products embedded.
+    """
+    from sqlalchemy import text
+    from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+    from app.db.session import AsyncSessionLocal
+    from app.models.models import ProductEmbedding
+    from app.services.embeddings import embed_batch
+
+    snap_date = date.fromisoformat(snap_date_str)
+
+    async with AsyncSessionLocal() as db:
+        sql = text("""
+            SELECT
+                p.product_id, p.sku, p.product_name, p.category,
+                i.marketplace,
+                i.available_stock, i.reorder_threshold,
+                pr.selling_price,
+                CASE WHEN pr.selling_price > 0 AND pr.cost_price IS NOT NULL 
+                     THEN ((pr.selling_price - pr.cost_price - COALESCE(pr.commission_amount, 0)) / pr.selling_price) * 100 
+                     ELSE NULL END AS margin_pct,
+                t.impressions, t.clicks, t.orders AS ad_orders,
+                CASE WHEN t.ad_spend > 0 THEN t.revenue_from_ads / t.ad_spend ELSE 0 END AS roas
+            FROM products p
+            LEFT JOIN inventory_snapshots i
+                ON i.product_id = p.product_id AND i.seller_id = :sid
+               AND i.snapshot_date = :d
+            LEFT JOIN pricing_snapshots pr
+                ON pr.product_id = p.product_id AND pr.seller_id = :sid
+               AND pr.snapshot_date = :d
+            LEFT JOIN traffic_metrics t
+                ON t.product_id = p.product_id AND t.seller_id = :sid
+               AND t.metric_date = :d
+            WHERE p.seller_id = :sid
+        """)
+        result = await db.execute(sql, {"sid": seller_id, "d": snap_date})
+        rows = result.mappings().all()
+
+        if not rows:
+            logger.warning("[Embed] No products for seller=%s date=%s", seller_id, snap_date)
+            return 0
+
+        # Build summary strings
+        summaries = [
+            (
+                f"Product: {r['product_name']} (SKU: {r['sku']}, Category: {r['category']}, "
+                f"Marketplace: {r['marketplace'] or 'N/A'}). "
+                f"Stock: {r['available_stock'] or 'N/A'} units "
+                f"(threshold: {r['reorder_threshold'] or 10}). "
+                f"Price: Rs.{r['selling_price'] or 'N/A'}, "
+                f"Margin: {r['margin_pct'] or 'N/A'}%. "
+                f"Traffic: {r['impressions'] or 0} impressions, "
+                f"{r['clicks'] or 0} clicks, {r['ad_orders'] or 0} ad orders, "
+                f"ROAS: {r['roas'] or 0}."
+            )
+            for r in rows
+        ]
+        metas = [
+            {
+                "available_stock": r["available_stock"],
+                "selling_price":   float(r["selling_price"]) if r["selling_price"] else None,
+                "margin_pct":      float(r["margin_pct"]) if r["margin_pct"] else None,
+                "roas":            float(r["roas"]) if r["roas"] else None,
+            }
+            for r in rows
+        ]
+
+        # ONE batch model call for all products
+        vectors = await embed_batch(summaries)
+
+        # Bulk upsert into Supabase pgvector
+        ins = pg_insert(ProductEmbedding).values([
+            {
+                "seller_id":    seller_id,
+                "product_id":   str(rows[i]["product_id"]),
+                "embed_date":   snap_date,
+                "embed_type":   "daily_snapshot",
+                "summary_text": summaries[i],
+                "embedding":    vectors[i],
+                "meta":         metas[i],
+            }
+            for i in range(len(rows))
+        ])
+        stmt = ins.on_conflict_do_update(
+            index_elements=["seller_id", "product_id", "embed_date", "embed_type"],
+            set_={
+                "summary_text": ins.excluded.summary_text,
+                "embedding":    ins.excluded.embedding,
+                "meta":         ins.excluded.meta,
+            },
+        )
+        await db.execute(stmt)
+        await db.commit()
+
+        logger.info("[Embed] seller=%s date=%s embedded=%d", seller_id, snap_date, len(rows))
+        return len(rows)
+
+
+# ── Task 1: Per-upload trigger ─────────────────────────────────
+@shared_task(
+    name="app.services.tasks.auto_embed",
+    bind=True,
+    max_retries=3,
+    default_retry_delay=30,   # Retry after 30s on failure
+    queue="embed",
+)
+def auto_embed(self, seller_id: str, snap_date: str):
+    """
+    Triggered automatically after every Excel upload.
+    Embeds all products for the given seller and date.
+
+    Usage from FastAPI:
+        from app.tasks.embed import auto_embed
+        auto_embed.delay(seller_id, snap_date)
+    """
+    try:
+        # Publish "Task Started"
+        import redis
+        from app.core.config import settings
+        import json
+        r = redis.from_url(settings.REDIS_URL, decode_responses=True)
+        r.publish(f"channel:{seller_id}", json.dumps({"event": "embedding_started", "message": f"Embedding products for {snap_date}..."}))
+        
+        logger.info("[Celery] auto_embed started seller=%s date=%s", seller_id, snap_date)
+        count = asyncio.run(_run_embed(seller_id, snap_date))
+        logger.info("[Celery] auto_embed done embedded=%d", count)
+        
+        # Publish "Embedding Complete"
+        r.publish(f"channel:{seller_id}", json.dumps({"event": "embedding_complete", "message": f"Successfully embedded {count} products.", "count": count}))
+
+        # Trigger AI Agent simulation automatically after embedding
+        from app.services.ai_agent_client import trigger_simulation
+        try:
+            r.publish(f"channel:{seller_id}", json.dumps({"event": "ai_started", "message": "Triggering AI Board of Directors..."}))
+            logger.info("[Celery] Triggering AI multi-agent simulation for seller=%s", seller_id)
+            # Create a simple snapshot summary payload
+            snapshot_data = {"event": "auto_embed_complete", "date": snap_date, "embedded_count": count}
+            
+            # Use a slightly older date for time_window_start as a default
+            from datetime import date as _date, timedelta
+            end_date = _date.fromisoformat(snap_date)
+            start_date = end_date - timedelta(days=7)
+            
+            ai_result = asyncio.run(trigger_simulation(
+                seller_id=seller_id,
+                time_window_start=str(start_date),
+                time_window_end=str(end_date),
+                snapshot_data=snapshot_data
+            ))
+            if ai_result:
+                logger.info("[Celery] AI Simulation triggered successfully: %s", ai_result.get("status"))
+                r.publish(f"channel:{seller_id}", json.dumps({"event": "ai_complete", "message": "Executive plan ready.", "result": "success"}))
+            else:
+                logger.warning("[Celery] AI Simulation triggered but returned no valid result.")
+                r.publish(f"channel:{seller_id}", json.dumps({"event": "ai_error", "message": "AI failed to generate plan."}))
+        except Exception as ai_exc:
+            logger.error("[Celery] Failed to trigger AI Simulation: %s", ai_exc)
+            r.publish(f"channel:{seller_id}", json.dumps({"event": "ai_error", "message": str(ai_exc)}))
+
+        return {"status": "ok", "embedded": count, "seller_id": seller_id, "date": snap_date}
+    except Exception as exc:
+        logger.error("[Celery] auto_embed error: %s", exc, exc_info=True)
+        raise self.retry(exc=exc)
+
+
+# ── Task 2: Single product embed (for /ai/embed/product) ───────
+@shared_task(
+    name="app.services.tasks.embed_single_product",
+    bind=True,
+    max_retries=3,
+    default_retry_delay=30,
+    queue="embed",
+)
+def embed_single_product(self, seller_id: str, product_id: str, summary: str, embed_date: str | None = None, embed_type: str = "daily_snapshot"):
+    """
+    Embed a single product summary.
+
+    Used by /ai/embed/product to offload embedding work to Celery.
+    """
+    try:
+        from datetime import date as _date
+
+        from app.db.session import AsyncSessionLocal
+        from app.services.embeddings import embedding_service
+
+        async def _run():
+            d = _date.fromisoformat(embed_date) if embed_date else _date.today()
+            async with AsyncSessionLocal() as db:
+                await embedding_service.upsert_product_embedding(
+                    db,
+                    seller_id=seller_id,
+                    product_id=product_id,
+                    summary_text=summary,
+                    embed_date=d,
+                    embed_type=embed_type,
+                )
+            return {"status": "ok", "embedded": True, "product_id": product_id, "date": str(d)}
+
+        result = asyncio.run(_run())
+        logger.info("[Celery] embed_single_product seller=%s product=%s date=%s", seller_id, product_id, result["date"])
+        return result
+    except Exception as exc:
+        logger.error("[Celery] embed_single_product error: %s", exc, exc_info=True)
+        raise self.retry(exc=exc)
+
+
+# ── Task 3: Nightly batch for ALL sellers ─────────────────────
+@shared_task(
+    name="app.services.tasks.nightly_embed_all",
+    queue="embed",
+)
+def nightly_embed_all():
+    """
+    Scheduled by Celery Beat at 2:00 AM IST daily.
+    Re-embeds yesterday's snapshot for every seller in the database.
+    This ensures the AI memory layer is always up-to-date.
+    """
+    async def _run():
+        from sqlalchemy import text
+        from app.db.session import AsyncSessionLocal
+
+        yesterday = str(date.today() - timedelta(days=1))
+
+        async with AsyncSessionLocal() as db:
+            result = await db.execute(text("SELECT seller_id FROM sellers"))
+            seller_ids = [str(row.seller_id) for row in result.fetchall()]
+
+        logger.info("[Celery] nightly_embed_all: %d sellers for date=%s", len(seller_ids), yesterday)
+        results = []
+        for sid in seller_ids:
+            try:
+                count = await _run_embed(sid, yesterday)
+                results.append({"seller_id": sid, "embedded": count})
+            except Exception as e:
+                logger.error("[Celery] nightly embed failed seller=%s: %s", sid, e)
+                results.append({"seller_id": sid, "error": str(e)})
+        return results
+
+    return asyncio.run(_run())
+
+# ── Task 4: Weekly AI Action Plan (Health Check) ───────────────
+@shared_task(
+    name="app.services.tasks.weekly_health_check",
+    queue="embed",
+)
+def weekly_health_check():
+    """
+    Scheduled by Celery Beat at 8:00 AM IST every Monday.
+    Scans the database for all active sellers and triggers the AI Board of Directors
+    to generate an Executive Action Plan for the previous week's performance.
+    """
+    async def _run():
+        from sqlalchemy import text
+        from datetime import date as _date, timedelta
+        from app.db.session import AsyncSessionLocal
+        from app.services.ai_agent_client import trigger_simulation
+
+        today = _date.today()
+        start_date = today - timedelta(days=7)
+        end_date = today - timedelta(days=1)
+        
+        async with AsyncSessionLocal() as db:
+            result = await db.execute(text("SELECT seller_id FROM sellers"))
+            seller_ids = [str(row.seller_id) for row in result.fetchall()]
+
+        logger.info("[Celery] weekly_health_check: Triggering AI for %d sellers", len(seller_ids))
+        results = []
+        for sid in seller_ids:
+            try:
+                # Mock a generic snapshot payload indicating this is a scheduled summary
+                snapshot_data = {
+                    "event": "weekly_scheduled_review", 
+                    "date_range": f"{start_date} to {end_date}",
+                    "context": "Automated weekly board review."
+                }
+                
+                ai_result = await trigger_simulation(
+                    seller_id=sid,
+                    time_window_start=str(start_date),
+                    time_window_end=str(end_date),
+                    snapshot_data=snapshot_data
+                )
+                
+                if ai_result and ai_result.get("status") == "success":
+                    logger.info("[Celery] Weekly AI Plan generated successfully for seller=%s", sid)
+                    results.append({"seller_id": sid, "status": "success"})
+                else:
+                    logger.warning("[Celery] Weekly AI Plan failed for seller=%s", sid)
+                    results.append({"seller_id": sid, "status": "failed"})
+            except Exception as e:
+                logger.error("[Celery] weekly_health_check failed for seller=%s: %s", sid, e)
+                results.append({"seller_id": sid, "error": str(e)})
+
+        return results
+
+    return asyncio.run(_run())
+
+# ── Task 5: Ping (for health checks) ───────────────────────────
+@shared_task(name="app.services.tasks.ping", queue="embed")
+def ping():
+    return "pong"
+
+# ── Task 6: Analyze all products (batch AI analysis) ───────────
+@shared_task(
+    name="app.services.tasks.analyze_all_products",
+    queue="embed",
+)
+def analyze_all_products(seller_id: str, snap_date: str):
+    """
+    Triggered after auto_embed.
+    Analyzes each product using the AI agent, with throttling.
+    """
+    async def _run():
+        from sqlalchemy import text
+        from app.db.session import AsyncSessionLocal
+        from app.services.ai_agent_client import trigger_product_analysis
+        from app.models.models import AIProductAnalysis
+        from sqlalchemy.dialects.postgresql import insert as pg_insert
+        import asyncio
+
+        # Publish task start
+        import redis
+        from app.core.config import settings
+        import json
+        r = redis.from_url(settings.REDIS_URL, decode_responses=True)
+        r.publish(f"channel:{seller_id}", json.dumps({"event": "ai_product_analysis_started", "message": f"Starting per-product AI analysis for {snap_date}..."}))
+
+        async with AsyncSessionLocal() as db:
+            # 1. Fetch all unique products for the seller
+            sql = text("""
+                SELECT p.product_id, p.sku, p.product_name, p.category, p.marketplace
+                FROM products p
+                WHERE p.seller_id = :seller_id AND p.is_active = TRUE
+            """)
+            result = await db.execute(sql, {"seller_id": seller_id})
+            products = result.mappings().all()
+
+            logger.info("[Celery] analyze_all_products: found %d products for seller=%s", len(products), seller_id)
+            
+            analyzed_count = 0
+            
+            # 2. Iterate and analyze each product
+            for prod in products:
+                prod_id = str(prod["product_id"])
+                product_data = dict(prod)
+                product_data["product_id"] = prod_id
+                
+                try:
+                    logger.info("[Celery] Triggering analysis for product %s (%s)", prod_id, prod["product_name"])
+                    ai_result = await trigger_product_analysis(seller_id, prod_id, product_data)
+                    
+                    if ai_result and ai_result.get("status") == "success":
+                        result_data = ai_result.get("result", {})
+                        
+                        # Save to database
+                        stmt = pg_insert(AIProductAnalysis).values(
+                            seller_id=seller_id,
+                            product_id=prod_id,
+                            analysis_date=date.fromisoformat(snap_date),
+                            product_metrics=product_data,
+                            executive_summary=result_data,
+                            status="completed"
+                        ).on_conflict_do_update(
+                            index_elements=["seller_id", "product_id", "analysis_date"],
+                            set_={
+                                "executive_summary": result_data,
+                                "status": "completed",
+                                "product_metrics": product_data,
+                                "updated_at": text("NOW()")
+                            }
+                        )
+                        await db.execute(stmt)
+                        await db.commit()
+                        analyzed_count += 1
+                        
+                        # Emit a granular event so the frontend can update live
+                        r.publish(f"channel:{seller_id}", json.dumps({
+                            "event": "ai_product_analyzed",
+                            "product_id": prod_id,
+                            "product_name": prod["product_name"],
+                            "message": f"Analyzed {prod['product_name']}"
+                        }))
+                    
+                except Exception as e:
+                    logger.error("[Celery] Failed to analyze product %s: %s", prod_id, e)
+                
+                # Throttle to avoid hitting Groq rate limits (500ms delay)
+                await asyncio.sleep(0.5)
+
+        r.publish(f"channel:{seller_id}", json.dumps({
+            "event": "ai_product_analysis_complete", 
+            "message": f"Completed product analysis for {analyzed_count}/{len(products)} products.",
+            "count": analyzed_count
+        }))
+        
+        return {"seller_id": seller_id, "analyzed_count": analyzed_count, "total_products": len(products)}
+
+    return asyncio.run(_run())

app/test_ai_integration.py

@@ -0,0 +1,115 @@
+import pytest
+from unittest.mock import AsyncMock, patch
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+client = TestClient(app)
+
+@pytest.fixture
+def mock_trigger():
+    with patch("app.routes.ai.trigger_simulation", new_callable=AsyncMock) as mock:
+        yield mock
+
+@pytest.mark.asyncio
+async def test_simulate_ai_endpoint(mock_trigger):
+    # Mock the response from the AI Agents API
+    mock_trigger.return_value = {
+        "status": "success",
+        "seller_id": "TEST_SELLER",
+        "executive_plan": {
+            "summary": "This is a mock plan",
+            "actions": []
+        }
+    }
+    
+    # We also need to mock `embedding_service.store_insight` since it connects to the DB
+    with patch("app.routes.ai.embedding_service.store_insight", new_callable=AsyncMock) as mock_store:
+        response = client.post(
+            "/ai/simulate",
+            headers={"Authorization": "Bearer dev-api-key"},
+            json={
+                "seller_id": "TEST_SELLER",
+                "time_window_start": "2026-02-01",
+                "time_window_end": "2026-02-15",
+                "snapshot_data": {"test": "data"}
+            }
+        )
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["status"] == "success"
+        assert "executive_plan" in data
+        
+        # Verify the mock was called correctly
+        mock_trigger.assert_called_once_with(
+            seller_id="TEST_SELLER",
+            time_window_start="2026-02-01",
+            time_window_end="2026-02-15",
+            snapshot_data={"test": "data"}
+        )
+        # Verify it attempted to save the insight
+        mock_store.assert_called_once()
+
+@pytest.fixture
+def mock_stream_trigger():
+    with patch("app.routes.ai.trigger_simulation_stream") as mock:
+        yield mock
+
+@pytest.mark.asyncio
+async def test_simulate_ai_stream_endpoint(mock_stream_trigger):
+    # Mock an async generator
+    async def mock_generator():
+        yield b'data: {"content": "Hello"}\n\n'
+        yield b'data: {"content": " World"}\n\n'
+        yield b'data: {"status": "done"}\n\n'
+        
+    mock_stream_trigger.return_value = mock_generator()
+    
+    with client.stream("POST", "/ai/simulate/stream", 
+                    headers={"Authorization": "Bearer dev-api-key"},
+                    json={
+                        "seller_id": "TEST_SELLER",
+                        "time_window_start": "2026-02-01",
+                        "time_window_end": "2026-02-15",
+                        "snapshot_data": {}
+                    }) as response:
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "text/event-stream; charset=utf-8"
+        
+        chunks = list(response.iter_bytes())
+        assert len(chunks) == 3
+        assert b'Hello' in chunks[0]
+        assert b'World' in chunks[1]
+        assert b'done' in chunks[2]
+
+@pytest.fixture
+def mock_whatif_stream_trigger():
+    with patch("app.routes.ai.trigger_whatif_stream") as mock:
+        yield mock
+
+@pytest.mark.asyncio
+async def test_simulate_ai_whatif_stream_endpoint(mock_whatif_stream_trigger):
+    # Mock an async generator
+    async def mock_generator():
+        yield b'data: {"content": "Simulation"}\n\n'
+        yield b'data: {"content": " Results"}\n\n'
+        yield b'data: {"status": "done"}\n\n'
+        
+    mock_whatif_stream_trigger.return_value = mock_generator()
+    
+    with client.stream("POST", "/ai/whatif", 
+                    headers={"Authorization": "Bearer dev-api-key"},
+                    json={
+                        "seller_id": "TEST_SELLER",
+                        "scenario": "What if I drop my price 10%?"
+                    }) as response:
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "text/event-stream; charset=utf-8"
+        
+        # Read the streamed chunks
+        chunks = list(response.iter_bytes())
+        assert len(chunks) == 3
+        assert b'Simulation' in chunks[0]
+        assert b'Results' in chunks[1]
+        assert b'done' in chunks[2]

requirements.txt

@@ -0,0 +1,38 @@
+# Web framework
+fastapi==0.110.0
+uvicorn[standard]==0.27.1
+python-multipart==0.0.9
+
+# Database
+sqlalchemy[asyncio]==2.0.28
+asyncpg==0.29.0
+psycopg2-binary==2.9.9
+pgvector
+
+# Excel ingestion
+pandas==2.2.1
+openpyxl==3.1.2
+numpy==1.26.4
+
+# AI / Embeddings
+# NOTE: torch (CPU-only) is installed separately in Dockerfile BEFORE this file
+# to prevent pip from resolving the GPU/CUDA variant (~3GB).
+sentence-transformers==2.6.1
+
+# Background tasks — Celery + Redis
+celery[redis]>=5.3.6
+redis>=4.5.2,<5.0.0
+
+# Validation + settings
+pydantic==2.6.3
+pydantic-settings==2.2.1
+python-dotenv==1.0.1
+
+# Serialization
+orjson==3.9.15
+
+# HTTP Client
+httpx
+
+# Caching
+fastapi-cache2[redis]==0.2.1

workers/celery_app.py

@@ -0,0 +1,50 @@
+"""
+app/tasks/__init__.py
+Celery application factory for CommercePulse.
+
+The Celery app is created here and imported by:
+  - app/tasks/embed.py  (task definitions)
+  - start_worker.bat    (worker process)
+  - FastAPI upload routes (to enqueue tasks)
+"""
+from celery import Celery
+from celery.schedules import crontab
+
+from app.core.config import settings
+
+REDIS_URL = settings.REDIS_URL
+
+celery_app = Celery(
+    "commercepulse",
+    broker=REDIS_URL,
+    backend=REDIS_URL,
+    include=["app.services.tasks"],
+)
+
+celery_app.conf.update(
+    # Serialization
+    task_serializer="json",
+    result_serializer="json",
+    accept_content=["json"],
+    # Timezone
+    timezone="Asia/Kolkata",
+    enable_utc=True,
+    # Reliability
+    broker_connection_retry_on_startup=True,
+    task_acks_late=True,           # Ack only after task succeeds (safe retry)
+    task_reject_on_worker_lost=True,
+    worker_prefetch_multiplier=1,  # One task at a time (embeddings are CPU-heavy)
+    # Result expiry
+    result_expires=3600,           # Keep results for 1 hour
+    # Beat schedule — nightly re-embed all sellers at 2:00 AM IST
+    beat_schedule={
+        "nightly-embed-all-sellers": {
+            "task": "app.services.tasks.nightly_embed_all",
+            "schedule": crontab(hour=2, minute=0),  # 2:00 AM IST daily
+        },
+        "weekly-ai-health-check": {
+            "task": "app.services.tasks.weekly_health_check",
+            "schedule": crontab(hour=8, minute=0, day_of_week=1),  # 8:00 AM IST every Monday
+        },
+    },
+)