Add comprehensive tests for pricing engine and API endpoints

- Introduced `test_pricing_engine.py` to validate pricing logic and guardrails for synthetic and Kaggle pricing requests.
- Created `test_api.py` to ensure API endpoints function correctly, including health checks and price recommendations.
- Added `smoke_test.py` to verify that the project compiles without errors.
- Implemented dummy settings and tracker classes to facilitate testing.
- Enhanced test coverage for flash sale detection and competitor price adjustments.

.dockerignore

@@ -0,0 +1,14 @@
+.git
+.gitignore
+.pytest_cache
+.venv
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.log
+.env
+.env.*
+!.env.example
+tests/
+deploy/

.env.example

@@ -0,0 +1,16 @@
+APP_NAME=dynamic-pricing-engine
+MODEL_PATH=models/best_pricing_model.joblib
+METRICS_PATH=models/training_metrics.json
+RAW_DATA_PATH=data/raw/pricing_events.csv
+PRICE_HISTORY_PATH=data/processed/price_history.csv
+COMPETITOR_API_URL=
+COMPETITOR_WEIGHT=0.30
+MODEL_WEIGHT=0.70
+MIN_MARGIN=0.08
+MAX_PRICE_MULTIPLIER=1.35
+REDIS_URL=
+KAFKA_BOOTSTRAP_SERVERS=localhost:9092
+KAFKA_TOPIC_ORDERS=pricing.orders
+KAFKA_TOPIC_CLICKS=pricing.clicks
+FLASH_SALE_ORDER_THRESHOLD=20
+FLASH_SALE_LOOKBACK_MINUTES=5

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.13-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --upgrade pip && pip install -r requirements.txt
+
+COPY app ./app
+COPY scripts ./scripts
+COPY data ./data
+COPY models ./models
+COPY .env.example ./.env.example
+COPY README.md ./README.md
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"
+
+CMD ["uvicorn", "app.api:app", "--host", "0.0.0.0", "--port", "8000"]

Dockerfile.streamlit

@@ -0,0 +1,21 @@
+FROM python:3.13-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --upgrade pip && pip install -r requirements.txt
+
+COPY app ./app
+COPY scripts ./scripts
+COPY data ./data
+COPY models ./models
+COPY .env.example ./.env.example
+COPY README.md ./README.md
+
+EXPOSE 8501
+
+CMD ["streamlit", "run", "app/dashboard.py", "--server.address=0.0.0.0", "--server.port=8501", "--server.headless=true"]

app/__init__.py

@@ -0,0 +1 @@
+"""Dynamic pricing engine package."""

app/api.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import json
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+
+import pandas as pd
+from fastapi import FastAPI, HTTPException
+
+from app.config import get_settings
+from app.pricing_engine import PricingEngine
+from app.schemas import (
+    KagglePricingRequest,
+    KagglePricingResponse,
+    MonitoringSummary,
+    OrderEvent,
+    PricingRequest,
+    PricingResponse,
+)
+
+
+engine: PricingEngine | None = None
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    global engine
+    settings = get_settings()
+    if settings.model_path.exists():
+        engine = PricingEngine(settings)
+    else:
+        engine = None
+    yield
+
+
+app = FastAPI(title="Dynamic Pricing Engine", version="1.0.0", lifespan=lifespan)
+
+
+@app.get("/health")
+def health() -> dict[str, object]:
+    settings = get_settings()
+    return {
+        "status": "ok",
+        "model_loaded": engine is not None,
+        "dataset_profile": getattr(engine, "dataset_profile", None),
+        "supported_endpoints": {
+            "synthetic": "/price/recommend",
+            "kaggle_retail": "/price/recommend/kaggle",
+        },
+        "model_path": str(settings.model_path),
+        "metrics_path": str(settings.metrics_path),
+    }
+
+
+@app.post("/price/recommend", response_model=PricingResponse)
+def recommend_price(request: PricingRequest) -> PricingResponse:
+    if engine is None:
+        raise HTTPException(status_code=503, detail="Model is not loaded. Train the model first.")
+    try:
+        recommendation = engine.recommend_price(request)
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    return recommendation.response
+
+
+@app.post("/price/recommend/kaggle", response_model=KagglePricingResponse)
+def recommend_kaggle_price(request: KagglePricingRequest) -> KagglePricingResponse:
+    if engine is None:
+        raise HTTPException(status_code=503, detail="Model is not loaded. Train the model first.")
+    try:
+        recommendation = engine.recommend_kaggle_price(request)
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    return recommendation.response
+
+
+@app.post("/events/order")
+def register_order(event: OrderEvent) -> dict[str, object]:
+    if engine is None:
+        raise HTTPException(status_code=503, detail="Model is not loaded. Train the model first.")
+    is_flash_sale = engine.register_order_event(event)
+    return {
+        "sku_id": event.sku_id,
+        "flash_sale_active": is_flash_sale,
+        "registered_at": datetime.now(UTC).isoformat(),
+    }
+
+
+@app.get("/monitoring/summary", response_model=MonitoringSummary)
+def monitoring_summary() -> MonitoringSummary:
+    if engine is None:
+        raise HTTPException(status_code=503, detail="Model is not loaded. Train the model first.")
+    settings = get_settings()
+    average_recommended_price = None
+    last_price_update = None
+
+    if settings.price_history_path.exists():
+        history = pd.read_csv(settings.price_history_path)
+        if not history.empty:
+            average_recommended_price = float(history["recommended_price"].mean())
+            last_price_update = pd.to_datetime(history["generated_at"].iloc[-1]).to_pydatetime()
+
+    return MonitoringSummary(
+        tracked_skus=len(engine.flash_sale_tracker.events),
+        recent_order_events=engine.flash_sale_tracker.recent_event_count(),
+        flash_sale_skus=engine.flash_sale_tracker.flash_sale_skus(),
+        average_recommended_price=average_recommended_price,
+        last_price_update=last_price_update,
+    )
+
+
+@app.get("/metrics")
+def metrics() -> dict[str, object]:
+    settings = get_settings()
+    if not settings.metrics_path.exists():
+        raise HTTPException(status_code=404, detail="Metrics file not found.")
+    return json.loads(settings.metrics_path.read_text(encoding="utf-8"))

app/cache.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+import redis
+
+
+class RedisCache:
+    def __init__(self, redis_url: str):
+        self.redis_url = redis_url
+        self.client = redis.from_url(redis_url, decode_responses=True) if redis_url else None
+
+    def is_enabled(self) -> bool:
+        return self.client is not None
+
+    def set_json(self, key: str, payload: dict[str, Any], ttl_seconds: int = 300) -> None:
+        if self.client is None:
+            return
+        serialized = json.dumps(
+            {
+                "payload": payload,
+                "cached_at": datetime.now(UTC).isoformat(),
+            }
+        )
+        self.client.setex(key, ttl_seconds, serialized)
+
+    def get_json(self, key: str) -> dict[str, Any] | None:
+        if self.client is None:
+            return None
+        value = self.client.get(key)
+        return json.loads(value) if value else None

app/config.py

@@ -0,0 +1,42 @@
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+
+class Settings(BaseSettings):
+    app_name: str = "dynamic-pricing-engine"
+    model_path: Path = BASE_DIR / "models" / "best_pricing_model.joblib"
+    metrics_path: Path = BASE_DIR / "models" / "training_metrics.json"
+    raw_data_path: Path = BASE_DIR / "data" / "raw" / "pricing_events.csv"
+    price_history_path: Path = BASE_DIR / "data" / "processed" / "price_history.csv"
+    competitor_api_url: str = ""
+    competitor_weight: float = 0.30
+    model_weight: float = 0.70
+    min_margin: float = 0.08
+    max_price_multiplier: float = 1.35
+    redis_url: str = ""
+    kafka_bootstrap_servers: str = "localhost:9092"
+    kafka_topic_orders: str = "pricing.orders"
+    kafka_topic_clicks: str = "pricing.clicks"
+    flash_sale_order_threshold: int = 20
+    flash_sale_lookback_minutes: int = 5
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        protected_namespaces=("settings_",),
+    )
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    settings = Settings()
+    settings.model_path.parent.mkdir(parents=True, exist_ok=True)
+    settings.raw_data_path.parent.mkdir(parents=True, exist_ok=True)
+    settings.price_history_path.parent.mkdir(parents=True, exist_ok=True)
+    return settings

app/dashboard.py

@@ -0,0 +1,554 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import sys
+
+import pandas as pd
+import plotly.express as px
+import plotly.graph_objects as go
+import streamlit as st
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from app.feature_engineering import load_kaggle_retail_training_data
+from app.modeling import load_model_bundle
+
+
+st.set_page_config(
+    page_title="Retail Pricing Studio",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+
+def inject_styles() -> None:
+    st.markdown(
+        """
+        <style>
+        /* ── Base ─────────────────────────────────────────── */
+        .stApp { background: var(--background-color); }
+
+        /* ── Metric card ──────────────────────────────────── */
+        .mcard {
+            background: var(--secondary-background-color);
+            border: 1px solid rgba(148,163,184,0.15);
+            border-radius: 12px;
+            padding: 14px 16px;
+        }
+        .mcard-label {
+            font-size: 11px;
+            font-weight: 600;
+            letter-spacing: 0.07em;
+            text-transform: uppercase;
+            color: var(--text-color);
+            opacity: 0.5;
+            margin-bottom: 4px;
+        }
+        .mcard-value {
+            font-size: 22px;
+            font-weight: 700;
+            color: var(--text-color);
+            line-height: 1.2;
+        }
+        .mcard-sub {
+            font-size: 12px;
+            color: var(--text-color);
+            opacity: 0.45;
+            margin-top: 3px;
+        }
+
+        /* ── Signal banner ────────────────────────────────── */
+        .signal-banner {
+            border-radius: 10px;
+            padding: 12px 16px;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            margin-bottom: 0;
+        }
+        .signal-banner.green  { background: rgba( 16,185,129,0.10); border: 1px solid rgba( 16,185,129,0.25); }
+        .signal-banner.orange { background: rgba(234, 88, 12,0.10); border: 1px solid rgba(234, 88, 12,0.25); }
+        .signal-banner.gray   { background: rgba(100,116,139,0.10); border: 1px solid rgba(100,116,139,0.22); }
+
+        .signal-title { font-size: 14px; font-weight: 700; }
+        .signal-banner.green  .signal-title  { color: #10b981; }
+        .signal-banner.orange .signal-title  { color: #ea580c; }
+        .signal-banner.gray   .signal-title  { color: #64748b; }
+
+        .signal-text { font-size: 13px; color: var(--text-color); opacity: 0.7; margin-top: 2px; }
+
+        .signal-badge {
+            font-size: 11px;
+            font-weight: 600;
+            letter-spacing: 0.04em;
+            padding: 4px 10px;
+            border-radius: 999px;
+            white-space: nowrap;
+        }
+        .signal-banner.green  .signal-badge { background: rgba(16,185,129,0.18); color:#10b981; }
+        .signal-banner.orange .signal-badge { background: rgba(234,88,12,0.18);  color:#ea580c; }
+        .signal-banner.gray   .signal-badge { background: rgba(100,116,139,0.18);color:#64748b; }
+
+        /* ── Section divider label ────────────────────────── */
+        .section-sep {
+            font-size: 10px;
+            font-weight: 700;
+            letter-spacing: 0.1em;
+            text-transform: uppercase;
+            color: var(--text-color);
+            opacity: 0.35;
+            margin: 20px 0 6px;
+        }
+
+        /* ── KV table in right panel ──────────────────────── */
+        .kv-table { width: 100%; border-collapse: collapse; }
+        .kv-table td {
+            font-size: 13px;
+            padding: 7px 0;
+            border-bottom: 1px solid rgba(148,163,184,0.12);
+            vertical-align: middle;
+        }
+        .kv-table tr:last-child td { border-bottom: none; }
+        .kv-table .kv-key   { color: var(--text-color); opacity: 0.55; width: 55%; }
+        .kv-table .kv-val   { color: var(--text-color); font-weight: 600; text-align: right; }
+
+        /* ── Page header ──────────────────────────────────── */
+        .page-header {
+            display: flex;
+            align-items: baseline;
+            justify-content: space-between;
+            margin-bottom: 20px;
+        }
+        .page-title {
+            font-size: 20px;
+            font-weight: 700;
+            color: var(--text-color);
+        }
+        .page-context {
+            font-size: 12px;
+            color: var(--text-color);
+            opacity: 0.45;
+        }
+        </style>
+        """,
+        unsafe_allow_html=True,
+    )
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def candidate_kaggle_paths() -> list[Path]:
+    return [
+        ROOT_DIR / "data" / "raw" / "kaggle" / "retail_price.csv",
+        ROOT_DIR / "data" / "raw" / "retail_price.csv",
+    ]
+
+
+@st.cache_resource
+def load_bundle() -> dict[str, object] | None:
+    model_path = ROOT_DIR / "models" / "best_pricing_model.joblib"
+    if not model_path.exists():
+        return None
+    return load_model_bundle(model_path)
+
+
+@st.cache_data
+def load_metrics() -> dict[str, object]:
+    metrics_path = ROOT_DIR / "models" / "training_metrics.json"
+    if not metrics_path.exists():
+        return {}
+    return json.loads(metrics_path.read_text(encoding="utf-8"))
+
+
+@st.cache_data
+def load_kaggle_data() -> tuple[pd.DataFrame, Path | None]:
+    for path in candidate_kaggle_paths():
+        if path.exists():
+            return load_kaggle_retail_training_data(path), path
+    return pd.DataFrame(), None
+
+
+def fmt_inr(value: float) -> str:
+    if pd.isna(value):
+        return "—"
+    return f"₹ {value:,.2f}"
+
+
+def safe_float(value: object, fallback: float = 0.0) -> float:
+    return fallback if pd.isna(value) else float(value)
+
+
+def safe_int(value: object, fallback: int = 0) -> int:
+    return fallback if pd.isna(value) else int(value)
+
+
+def price_signal(predicted: float, actual: float) -> tuple[str, str, str]:
+    """Returns (title, text, color_class) where color_class is green/orange/gray."""
+    if actual == 0:
+        return "Hold Price", "Insufficient data to compute signal.", "gray"
+    delta_pct = ((predicted - actual) / actual) * 100
+    if delta_pct >= 5:
+        return (
+            "Increase Opportunity",
+            f"Model suggests a {delta_pct:.1f}% upward repricing opportunity.",
+            "green",
+        )
+    if delta_pct <= -5:
+        return (
+            "Defensive Discount",
+            f"Model suggests a {abs(delta_pct):.1f}% lower price to stay competitive.",
+            "orange",
+        )
+    return "Hold Price", "Current price is already close to the model recommendation.", "gray"
+
+
+def render_metric(label: str, value: str, sub: str) -> None:
+    st.markdown(
+        f'<div class="mcard">'
+        f'  <div class="mcard-label">{label}</div>'
+        f'  <div class="mcard-value">{value}</div>'
+        f'  <div class="mcard-sub">{sub}</div>'
+        f'</div>',
+        unsafe_allow_html=True,
+    )
+
+
+def render_signal(title: str, text: str, color: str) -> None:
+    st.markdown(
+        f'<div class="signal-banner {color}">'
+        f'  <div>'
+        f'    <div class="signal-title">{title}</div>'
+        f'    <div class="signal-text">{text}</div>'
+        f'  </div>'
+        f'  <span class="signal-badge">{title}</span>'
+        f'</div>',
+        unsafe_allow_html=True,
+    )
+
+
+def section_label(text: str) -> None:
+    st.markdown(f'<div class="section-sep">{text}</div>', unsafe_allow_html=True)
+
+
+# ── Plotly theme helpers ───────────────────────────────────────────────────────
+
+CHART_LAYOUT = dict(
+    paper_bgcolor="rgba(0,0,0,0)",
+    plot_bgcolor="rgba(0,0,0,0)",
+    font_color="#94a3b8",
+    margin=dict(l=8, r=8, t=36, b=8),
+    legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+    xaxis=dict(showgrid=False, linecolor="rgba(148,163,184,0.15)"),
+    yaxis=dict(gridcolor="rgba(148,163,184,0.10)", linecolor="rgba(148,163,184,0.15)"),
+)
+
+
+# ── Bootstrap ─────────────────────────────────────────────────────────────────
+
+inject_styles()
+bundle  = load_bundle()
+metrics = load_metrics()
+data, kaggle_path = load_kaggle_data()
+
+# ── Guards ─────────────────────────────────────────────────────────────────────
+
+if bundle is None:
+    st.error("No trained model artifact found. Train the Kaggle model first.")
+    st.code(
+        "python scripts/train_model.py --profile kaggle_retail "
+        "--data-path data/raw/kaggle/retail_price.csv"
+    )
+    st.stop()
+
+if bundle.get("dataset_profile") != "kaggle_retail":
+    st.warning(
+        "The loaded model is not the Kaggle retail profile. "
+        "Retrain with `--profile kaggle_retail` to use this dashboard."
+    )
+    st.code(
+        "python scripts/train_model.py --profile kaggle_retail "
+        "--data-path data/raw/kaggle/retail_price.csv"
+    )
+    st.stop()
+
+if data.empty or kaggle_path is None:
+    st.error(
+        "Kaggle retail dataset not found. "
+        "Place `retail_price.csv` in `data/raw/kaggle/` or `data/raw/`."
+    )
+    st.stop()
+
+pipeline            = bundle["pipeline"]
+numeric_features    = bundle["numeric_features"]
+categorical_features = bundle["categorical_features"]
+target_column       = bundle["target_column"]
+
+
+# ── Sidebar ────────────────────────────────────────────────────────────────────
+
+with st.sidebar:
+    st.markdown("### Scenario Builder")
+
+    category_options  = sorted(data["product_category_name"].dropna().unique())
+    selected_category = st.selectbox("Category", category_options)
+
+    category_frame  = data[data["product_category_name"] == selected_category].copy()
+    product_options = sorted(category_frame["product_id"].dropna().unique())
+    selected_product = st.selectbox("Product", product_options)
+
+    product_frame = category_frame[category_frame["product_id"] == selected_product].copy()
+    if "month_year" in product_frame.columns:
+        product_frame["_label"] = product_frame["month_year"].astype(str)
+        month_options       = product_frame["_label"].tolist()
+        selected_month_label = st.selectbox("Period", month_options, index=len(month_options) - 1)
+        selected_row = product_frame[product_frame["_label"] == selected_month_label].iloc[-1].copy()
+    else:
+        selected_month_label = ""
+        selected_row = product_frame.iloc[-1].copy()
+
+    st.divider()
+    st.caption("COMMERCIAL")
+    qty = st.slider(
+        "Units sold", 0, int(max(data["qty"].max(), 20)), safe_int(selected_row["qty"], 1)
+    )
+    customers = st.slider(
+        "Customers", 0, int(max(data["customers"].max(), 20)), safe_int(selected_row["customers"], 1)
+    )
+    freight_price = st.number_input(
+        "Freight price", min_value=0.0, value=safe_float(selected_row["freight_price"]), step=0.5
+    )
+    lag_price = st.number_input(
+        "Previous price", min_value=0.0, value=safe_float(selected_row["lag_price"]), step=0.5
+    )
+    product_score = st.slider(
+        "Product rating", 0.0, 5.0, safe_float(selected_row["product_score"]), 0.1
+    )
+
+    st.divider()
+    st.caption("COMPETITIVE")
+    comp_1 = st.number_input("Competitor 1", min_value=0.0, value=safe_float(selected_row["comp_1"]), step=0.5)
+    comp_2 = st.number_input("Competitor 2", min_value=0.0, value=safe_float(selected_row["comp_2"]), step=0.5)
+    comp_3 = st.number_input("Competitor 3", min_value=0.0, value=safe_float(selected_row["comp_3"]), step=0.5)
+    ps1 = st.slider("Competitor 1 rating", 0.0, 5.0, safe_float(selected_row["ps1"]), 0.1)
+    ps2 = st.slider("Competitor 2 rating", 0.0, 5.0, safe_float(selected_row["ps2"]), 0.1)
+    ps3 = st.slider("Competitor 3 rating", 0.0, 5.0, safe_float(selected_row["ps3"]), 0.1)
+
+    st.divider()
+    st.caption("PRODUCT")
+    product_name_lenght = st.slider(
+        "Name length", 0, int(max(data["product_name_lenght"].max(), 50)),
+        safe_int(selected_row["product_name_lenght"])
+    )
+    product_description_lenght = st.slider(
+        "Description length", 0, int(max(data["product_description_lenght"].max(), 200)),
+        safe_int(selected_row["product_description_lenght"])
+    )
+    product_photos_qty = st.slider(
+        "Photos", 0, int(max(data["product_photos_qty"].max(), 10)),
+        safe_int(selected_row["product_photos_qty"])
+    )
+    product_weight_g = st.slider(
+        "Weight (g)", 0, int(max(data["product_weight_g"].max(), 5000)),
+        safe_int(selected_row["product_weight_g"])
+    )
+
+
+# ── Compute scenario ───────────────────────────────────────────────────────────
+
+scenario = selected_row.copy()
+scenario.update({
+    "qty": qty, "customers": customers, "freight_price": freight_price,
+    "lag_price": lag_price, "product_score": product_score,
+    "comp_1": comp_1, "comp_2": comp_2, "comp_3": comp_3,
+    "ps1": ps1, "ps2": ps2, "ps3": ps3,
+    "product_name_lenght": product_name_lenght,
+    "product_description_lenght": product_description_lenght,
+    "product_photos_qty": product_photos_qty,
+    "product_weight_g": product_weight_g,
+})
+
+feature_frame   = pd.DataFrame([scenario])[numeric_features + categorical_features]
+predicted_price = float(pipeline.predict(feature_frame)[0])
+actual_price    = float(selected_row[target_column])
+price_gap       = predicted_price - actual_price
+
+comp_series          = pd.Series([comp_1, comp_2, comp_3]).replace(0, pd.NA).dropna()
+avg_competitor_price = float(comp_series.mean()) if not comp_series.empty else float("nan")
+
+sig_title, sig_text, sig_color = price_signal(predicted_price, actual_price)
+
+
+# ── Page header ────────────────────────────────────────────────────────────────
+
+context_parts = [c for c in [selected_category, selected_product, selected_month_label] if c]
+st.markdown(
+    f'<div class="page-header">'
+    f'  <span class="page-title">Retail Pricing Studio</span>'
+    f'  <span class="page-context">{" · ".join(context_parts)}</span>'
+    f'</div>',
+    unsafe_allow_html=True,
+)
+
+render_signal(sig_title, sig_text, sig_color)
+st.write("")  # spacing
+
+
+# ── KPI row ────────────────────────────────────────────────────────────────────
+
+c1, c2, c3, c4 = st.columns(4)
+with c1:
+    render_metric("Recommendation", fmt_inr(predicted_price), "Predicted unit price")
+with c2:
+    render_metric("Current price", fmt_inr(actual_price), "Reference record")
+with c3:
+    delta_sign = "+" if price_gap >= 0 else ""
+    render_metric("Delta", f"{delta_sign}{fmt_inr(price_gap)}", "Predicted vs current")
+with c4:
+    render_metric("Avg competitor", fmt_inr(avg_competitor_price), "Across 3 references")
+
+st.write("")
+
+
+# ── Main content ───────────────────────────────────────────────────────────────
+
+left_col, right_col = st.columns([1.5, 1], gap="medium")
+
+# ── Left: charts ───────────────────────────────────────────────────────────────
+
+with left_col:
+    # Price history
+    if "month_year" in product_frame.columns:
+        hist = product_frame[["month_year", target_column]].copy()
+        hist["month_year"] = pd.to_datetime(hist["month_year"], dayfirst=True, errors="coerce")
+        hist = hist.sort_values("month_year")
+
+        if not hist.empty:
+            scenario_date = hist["month_year"].max() + pd.offsets.MonthBegin(1)
+            combined = pd.concat(
+                [
+                    hist.rename(columns={target_column: "unit_price"}).assign(series="Historical"),
+                    pd.DataFrame({
+                        "month_year": [scenario_date],
+                        "unit_price": [predicted_price],
+                        "series": ["Scenario"],
+                    }),
+                ],
+                ignore_index=True,
+            )
+            fig_line = px.line(
+                combined, x="month_year", y="unit_price", color="series", markers=True,
+                color_discrete_map={"Historical": "#0ea5e9", "Scenario": "#f97316"},
+                title="Price history",
+            )
+            fig_line.update_layout(height=260, **CHART_LAYOUT)
+            fig_line.update_traces(line_width=2)
+            st.plotly_chart(fig_line, use_container_width=True)
+
+    # Competitive comparison
+    comp_df = pd.DataFrame({
+        "label": ["Current", "Predicted", "Comp 1", "Comp 2", "Comp 3"],
+        "price": [actual_price, predicted_price, comp_1, comp_2, comp_3],
+        "color": ["#0ea5e9", "#f97316", "#94a3b8", "#94a3b8", "#94a3b8"],
+    })
+    fig_bar = go.Figure(
+        go.Bar(
+            x=comp_df["label"],
+            y=comp_df["price"],
+            marker_color=comp_df["color"],
+            text=[fmt_inr(v) for v in comp_df["price"]],
+            textposition="outside",
+            textfont_size=11,
+        )
+    )
+    fig_bar.update_layout(height=260, title="Market comparison", **CHART_LAYOUT)
+    st.plotly_chart(fig_bar, use_container_width=True)
+
+    # Category distribution
+    cat_data = data[data["product_category_name"] == selected_category]
+    fig_hist = px.histogram(
+        cat_data, x=target_column, nbins=24,
+        title=f"{selected_category.replace('_', ' ').title()} — price distribution",
+        color_discrete_sequence=["#0ea5e9"],
+    )
+    fig_hist.add_vline(
+        x=predicted_price, line_dash="dash", line_color="#f97316",
+        annotation_text="Predicted", annotation_position="top right",
+        annotation_font_size=11,
+    )
+    fig_hist.update_layout(height=240, **CHART_LAYOUT)
+    st.plotly_chart(fig_hist, use_container_width=True)
+
+
+# ── Right: panels ──────────────────────────────────────────────────────────────
+
+with right_col:
+
+    # Scenario summary
+    section_label("Scenario")
+    summary_rows = [
+        ("Units sold",      qty),
+        ("Customers",       customers),
+        ("Freight price",   fmt_inr(freight_price)),
+        ("Previous price",  fmt_inr(lag_price)),
+        ("Product rating",  f"{product_score:.1f}"),
+    ]
+    rows_html = "".join(
+        f'<tr><td class="kv-key">{k}</td><td class="kv-val">{v}</td></tr>'
+        for k, v in summary_rows
+    )
+    st.markdown(
+        f'<table class="kv-table">{rows_html}</table>',
+        unsafe_allow_html=True,
+    )
+
+    # Competitive pressure
+    section_label("Competitive pressure")
+    comp_rows = [
+        ("Competitor 1", fmt_inr(comp_1), f"{ps1:.1f} ★"),
+        ("Competitor 2", fmt_inr(comp_2), f"{ps2:.1f} ★"),
+        ("Competitor 3", fmt_inr(comp_3), f"{ps3:.1f} ★"),
+    ]
+    comp_html = "".join(
+        f'<tr>'
+        f'  <td class="kv-key">{name}</td>'
+        f'  <td class="kv-val">{price}</td>'
+        f'  <td class="kv-val" style="opacity:0.5;font-weight:400">{rating}</td>'
+        f'</tr>'
+        for name, price, rating in comp_rows
+    )
+    st.markdown(f'<table class="kv-table">{comp_html}</table>', unsafe_allow_html=True)
+
+    if not pd.isna(avg_competitor_price):
+        pressure = "below" if predicted_price < avg_competitor_price else "above"
+        gap_abs  = abs(predicted_price - avg_competitor_price)
+        st.caption(
+            f"Predicted price is {fmt_inr(gap_abs)} {pressure} the average competitor price."
+        )
+
+    # Repricing opportunities
+    section_label("Top repricing opportunities")
+    sample_n     = min(len(data), 250)
+    sample_df    = data.sample(sample_n, random_state=42).copy()
+    sample_feats = sample_df[numeric_features + categorical_features]
+    sample_df["predicted_unit_price"] = pipeline.predict(sample_feats)
+    sample_df["opportunity_gap"]      = sample_df["predicted_unit_price"] - sample_df[target_column]
+
+    top_ops = (
+        sample_df.sort_values("opportunity_gap", ascending=False)
+        .head(8)[["product_id", "product_category_name", target_column, "predicted_unit_price", "opportunity_gap"]]
+        .rename(columns={
+            "product_id":             "Product",
+            "product_category_name":  "Category",
+            target_column:            "Current",
+            "predicted_unit_price":   "Predicted",
+            "opportunity_gap":        "Upside",
+        })
+    )
+    top_ops["Current"]   = top_ops["Current"].map(fmt_inr)
+    top_ops["Predicted"] = top_ops["Predicted"].map(fmt_inr)
+    top_ops["Upside"]    = top_ops["Upside"].map(lambda x: f"+{fmt_inr(x)}" if x >= 0 else fmt_inr(x))
+
+    st.dataframe(top_ops, use_container_width=True, hide_index=True, height=260)

app/feature_engineering.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import numpy as np
+import pandas as pd
+
+
+NUMERIC_FEATURES = [
+    "hour_of_day",
+    "day_of_week",
+    "is_weekend",
+    "is_festival",
+    "inventory_level",
+    "inventory_days_cover",
+    "competitor_price",
+    "click_through_rate",
+    "conversion_rate",
+    "units_sold_last_5m",
+    "units_sold_last_1h",
+    "base_cost",
+    "current_price",
+    "demand_index",
+    "inventory_pressure",
+    "competitor_gap",
+]
+
+CATEGORICAL_FEATURES = ["category", "brand", "customer_segment"]
+TARGET_COLUMN = "optimal_price"
+
+KAGGLE_RETAIL_NUMERIC_FEATURES = [
+    "qty",
+    "freight_price",
+    "product_name_lenght",
+    "product_description_lenght",
+    "product_photos_qty",
+    "product_weight_g",
+    "product_score",
+    "customers",
+    "weekday",
+    "weekend",
+    "holiday",
+    "volume",
+    "comp_1",
+    "ps1",
+    "fp1",
+    "comp_2",
+    "ps2",
+    "fp2",
+    "comp_3",
+    "ps3",
+    "fp3",
+    "lag_price",
+    "month",
+    "year",
+]
+KAGGLE_RETAIL_CATEGORICAL_FEATURES = ["product_id", "product_category_name"]
+KAGGLE_RETAIL_TARGET_COLUMN = "unit_price"
+
+
+def add_derived_features(frame: pd.DataFrame) -> pd.DataFrame:
+    enriched = frame.copy()
+    enriched["demand_index"] = (
+        enriched["units_sold_last_1h"] * 0.55
+        + enriched["units_sold_last_5m"] * 0.35
+        + enriched["conversion_rate"] * 100 * 0.10
+    )
+    enriched["inventory_pressure"] = np.where(
+        enriched["inventory_level"] <= 20,
+        1.25,
+        np.where(enriched["inventory_level"] <= 60, 1.05, 0.92),
+    )
+    enriched["competitor_gap"] = (
+        enriched["current_price"] - enriched["competitor_price"]
+    ) / enriched["competitor_price"].clip(lower=1.0)
+    return enriched
+
+
+def load_training_data(path: Path) -> pd.DataFrame:
+    frame = pd.read_csv(path)
+    return add_derived_features(frame)
+
+
+def load_kaggle_retail_training_data(path: Path) -> pd.DataFrame:
+    frame = pd.read_csv(path)
+
+    if "month_year" in frame.columns:
+        parsed_month_year = pd.to_datetime(frame["month_year"], dayfirst=True, errors="coerce")
+        if "month" not in frame.columns:
+            frame["month"] = parsed_month_year.dt.month
+        if "year" not in frame.columns:
+            frame["year"] = parsed_month_year.dt.year
+
+    numeric_defaults = [
+        "comp_1",
+        "ps1",
+        "fp1",
+        "comp_2",
+        "ps2",
+        "fp2",
+        "comp_3",
+        "ps3",
+        "fp3",
+        "lag_price",
+    ]
+    for column in numeric_defaults:
+        if column not in frame.columns:
+            frame[column] = np.nan
+
+    if "volume" not in frame.columns:
+        frame["volume"] = (
+            frame.get("product_name_lenght", 0).fillna(0)
+            * frame.get("product_description_lenght", 0).fillna(0)
+            * frame.get("product_photos_qty", 0).fillna(0).clip(lower=1)
+        )
+
+    if "weekday" not in frame.columns:
+        frame["weekday"] = 0
+    if "weekend" not in frame.columns:
+        frame["weekend"] = 0
+    if "holiday" not in frame.columns:
+        frame["holiday"] = 0
+
+    ensure_columns(
+        frame,
+        KAGGLE_RETAIL_NUMERIC_FEATURES
+        + KAGGLE_RETAIL_CATEGORICAL_FEATURES
+        + [KAGGLE_RETAIL_TARGET_COLUMN],
+    )
+    return frame
+
+
+def split_xy(
+    frame: pd.DataFrame,
+    numeric_features: list[str] | None = None,
+    categorical_features: list[str] | None = None,
+    target_column: str = TARGET_COLUMN,
+) -> tuple[pd.DataFrame, pd.Series]:
+    selected_numeric = numeric_features or NUMERIC_FEATURES
+    selected_categorical = categorical_features or CATEGORICAL_FEATURES
+    features = frame[selected_numeric + selected_categorical].copy()
+    target = frame[target_column].copy()
+    return features, target
+
+
+def ensure_columns(frame: pd.DataFrame, required_columns: Iterable[str]) -> None:
+    missing = [column for column in required_columns if column not in frame.columns]
+    if missing:
+        raise ValueError(f"Missing required columns: {missing}")

app/modeling.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import joblib
+import numpy as np
+from sklearn.compose import ColumnTransformer
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.impute import SimpleImputer
+from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score
+from sklearn.model_selection import train_test_split
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import OneHotEncoder, StandardScaler
+from xgboost import XGBRegressor
+
+from app.feature_engineering import (
+    CATEGORICAL_FEATURES,
+    KAGGLE_RETAIL_CATEGORICAL_FEATURES,
+    KAGGLE_RETAIL_NUMERIC_FEATURES,
+    KAGGLE_RETAIL_TARGET_COLUMN,
+    NUMERIC_FEATURES,
+    TARGET_COLUMN,
+    load_kaggle_retail_training_data,
+    load_training_data,
+    split_xy,
+)
+
+
+@dataclass
+class TrainingResult:
+    model_name: str
+    mae: float
+    rmse: float
+    r2: float
+    artifact_path: Path
+    dataset_profile: str
+
+
+def build_preprocessor(
+    numeric_features: list[str], categorical_features: list[str]
+) -> ColumnTransformer:
+    numeric_pipeline = Pipeline(
+        steps=[
+            ("imputer", SimpleImputer(strategy="median")),
+            ("scaler", StandardScaler()),
+        ]
+    )
+    categorical_pipeline = Pipeline(
+        steps=[
+            ("imputer", SimpleImputer(strategy="most_frequent")),
+            ("encoder", OneHotEncoder(handle_unknown="ignore")),
+        ]
+    )
+    return ColumnTransformer(
+        transformers=[
+            ("numeric", numeric_pipeline, numeric_features),
+            ("categorical", categorical_pipeline, categorical_features),
+        ]
+    )
+
+
+def build_models() -> dict[str, object]:
+    return {
+        "random_forest": RandomForestRegressor(
+            n_estimators=250,
+            max_depth=16,
+            min_samples_leaf=2,
+            random_state=42,
+            n_jobs=-1,
+        ),
+        "xgboost": XGBRegressor(
+            n_estimators=350,
+            max_depth=8,
+            learning_rate=0.05,
+            subsample=0.9,
+            colsample_bytree=0.9,
+            objective="reg:squarederror",
+            random_state=42,
+        ),
+    }
+
+
+def get_dataset_profile(dataset_profile: str) -> dict[str, object]:
+    profiles = {
+        "synthetic": {
+            "loader": load_training_data,
+            "numeric_features": NUMERIC_FEATURES,
+            "categorical_features": CATEGORICAL_FEATURES,
+            "target_column": TARGET_COLUMN,
+        },
+        "kaggle_retail": {
+            "loader": load_kaggle_retail_training_data,
+            "numeric_features": KAGGLE_RETAIL_NUMERIC_FEATURES,
+            "categorical_features": KAGGLE_RETAIL_CATEGORICAL_FEATURES,
+            "target_column": KAGGLE_RETAIL_TARGET_COLUMN,
+        },
+    }
+    if dataset_profile not in profiles:
+        raise ValueError(
+            f"Unsupported dataset profile '{dataset_profile}'. "
+            f"Expected one of: {', '.join(profiles)}"
+        )
+    return profiles[dataset_profile]
+
+
+def train_best_model(
+    data_path: Path,
+    artifact_path: Path,
+    metrics_path: Path,
+    dataset_profile: str = "synthetic",
+) -> TrainingResult:
+    profile = get_dataset_profile(dataset_profile)
+    frame = profile["loader"](data_path)
+    numeric_features = profile["numeric_features"]
+    categorical_features = profile["categorical_features"]
+    target_column = profile["target_column"]
+    x, y = split_xy(
+        frame,
+        numeric_features=numeric_features,
+        categorical_features=categorical_features,
+        target_column=target_column,
+    )
+    x_train, x_test, y_train, y_test = train_test_split(
+        x, y, test_size=0.2, random_state=42
+    )
+
+    preprocessor = build_preprocessor(
+        numeric_features=numeric_features,
+        categorical_features=categorical_features,
+    )
+    candidates = build_models()
+    best_result: TrainingResult | None = None
+    serialized_bundle = None
+    metrics_summary: dict[str, dict[str, float]] = {}
+
+    for model_name, estimator in candidates.items():
+        pipeline = Pipeline(
+            steps=[
+                ("preprocessor", preprocessor),
+                ("model", estimator),
+            ]
+        )
+        pipeline.fit(x_train, y_train)
+        predictions = pipeline.predict(x_test)
+        mae = float(mean_absolute_error(y_test, predictions))
+        rmse = float(np.sqrt(mean_squared_error(y_test, predictions)))
+        r2 = float(r2_score(y_test, predictions))
+        metrics_summary[model_name] = {"mae": mae, "rmse": rmse, "r2": r2}
+
+        if best_result is None or mae < best_result.mae:
+            best_result = TrainingResult(
+                model_name=model_name,
+                mae=mae,
+                rmse=rmse,
+                r2=r2,
+                artifact_path=artifact_path,
+                dataset_profile=dataset_profile,
+            )
+            serialized_bundle = {
+                "pipeline": pipeline,
+                "model_name": model_name,
+                "dataset_profile": dataset_profile,
+                "numeric_features": numeric_features,
+                "categorical_features": categorical_features,
+                "target_column": target_column,
+                "features": numeric_features + categorical_features,
+            }
+
+    if best_result is None or serialized_bundle is None:
+        raise RuntimeError("No model was trained.")
+
+    artifact_path.parent.mkdir(parents=True, exist_ok=True)
+    metrics_path.parent.mkdir(parents=True, exist_ok=True)
+    joblib.dump(serialized_bundle, artifact_path)
+
+    metrics_payload = {
+        "dataset_profile": dataset_profile,
+        "data_path": str(data_path),
+        "best_model": best_result.model_name,
+        "best_model_metrics": {
+            "mae": best_result.mae,
+            "rmse": best_result.rmse,
+            "r2": best_result.r2,
+        },
+        "all_models": metrics_summary,
+    }
+    metrics_path.write_text(json.dumps(metrics_payload, indent=2), encoding="utf-8")
+    return best_result
+
+
+def load_model_bundle(artifact_path: Path) -> dict[str, object]:
+    return joblib.load(artifact_path)

app/pricing_engine.py

@@ -0,0 +1,358 @@
+from __future__ import annotations
+
+import csv
+from collections import defaultdict, deque
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+from app.cache import RedisCache
+from app.config import Settings
+from app.feature_engineering import KAGGLE_RETAIL_CATEGORICAL_FEATURES, KAGGLE_RETAIL_NUMERIC_FEATURES
+from app.feature_engineering import add_derived_features
+from app.modeling import load_model_bundle
+from app.schemas import (
+    KagglePricingRequest,
+    KagglePricingResponse,
+    OrderEvent,
+    PricingRequest,
+    PricingResponse,
+)
+
+
+@dataclass
+class PricingRecommendation:
+    response: PricingResponse
+    ml_price: float
+    blended_price: float
+
+
+@dataclass
+class KagglePricingRecommendation:
+    response: KagglePricingResponse
+    ml_price: float
+
+
+class FlashSaleTracker:
+    def __init__(self, threshold: int, lookback_minutes: int):
+        self.threshold = threshold
+        self.lookback = timedelta(minutes=lookback_minutes)
+        self.events: dict[str, deque[datetime]] = defaultdict(deque)
+
+    def register(self, event: OrderEvent) -> bool:
+        queue = self.events[event.sku_id]
+        queue.append(event.event_time)
+        self._trim(event.sku_id, event.event_time)
+        return len(queue) >= self.threshold
+
+    def is_flash_sale(self, sku_id: str, now: datetime | None = None) -> bool:
+        reference_time = now or datetime.now(UTC)
+        self._trim(sku_id, reference_time)
+        return len(self.events[sku_id]) >= self.threshold
+
+    def recent_event_count(self) -> int:
+        now = datetime.now(UTC)
+        total = 0
+        for sku_id in list(self.events.keys()):
+            self._trim(sku_id, now)
+            total += len(self.events[sku_id])
+        return total
+
+    def flash_sale_skus(self) -> list[str]:
+        now = datetime.now(UTC)
+        active = []
+        for sku_id in list(self.events.keys()):
+            self._trim(sku_id, now)
+            if len(self.events[sku_id]) >= self.threshold:
+                active.append(sku_id)
+        return active
+
+    def _trim(self, sku_id: str, reference_time: datetime) -> None:
+        queue = self.events[sku_id]
+        while queue and reference_time - queue[0] > self.lookback:
+            queue.popleft()
+
+
+class CompetitorPriceClient:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+
+    def get_price(self, sku_id: str, fallback_price: float) -> float:
+        if not self.settings.competitor_api_url:
+            return fallback_price
+        try:
+            response = requests.get(
+                self.settings.competitor_api_url,
+                params={"sku_id": sku_id},
+                timeout=0.7,
+            )
+            response.raise_for_status()
+            payload = response.json()
+            return float(payload.get("competitor_price", fallback_price))
+        except Exception:
+            return fallback_price
+
+
+class PricingEngine:
+    def __init__(self, settings: Settings):
+        if not settings.model_path.exists():
+            raise FileNotFoundError(
+                f"Model artifact not found at {settings.model_path}. Train the model first."
+            )
+        self.settings = settings
+        self.bundle = load_model_bundle(settings.model_path)
+        self.dataset_profile = str(self.bundle.get("dataset_profile", "synthetic"))
+        self.pipeline = self.bundle["pipeline"]
+        self.flash_sale_tracker = FlashSaleTracker(
+            threshold=settings.flash_sale_order_threshold,
+            lookback_minutes=settings.flash_sale_lookback_minutes,
+        )
+        self.competitor_client = CompetitorPriceClient(settings)
+        self.cache = RedisCache(settings.redis_url)
+
+    def recommend_price(self, request: PricingRequest) -> PricingRecommendation:
+        if self.dataset_profile != "synthetic":
+            raise ValueError(
+                "The loaded model is not compatible with the synthetic pricing request schema."
+            )
+        frame = pd.DataFrame([request.model_dump()])
+        live_competitor_price = self.competitor_client.get_price(
+            request.sku_id, request.competitor_price
+        )
+        frame["competitor_price"] = live_competitor_price
+        enriched = add_derived_features(frame)
+        ml_price = float(self.pipeline.predict(enriched)[0])
+
+        blended_price = (
+            ml_price * self.settings.model_weight
+            + live_competitor_price * self.settings.competitor_weight
+        )
+
+        inventory_adjustment = self._inventory_adjustment(
+            inventory_level=request.inventory_level,
+            inventory_days_cover=request.inventory_days_cover,
+        )
+        demand_adjustment = self._demand_adjustment(
+            units_sold_last_5m=request.units_sold_last_5m,
+            units_sold_last_1h=request.units_sold_last_1h,
+            conversion_rate=request.conversion_rate,
+            is_festival=request.is_festival,
+        )
+        detected_flash_sale = self.flash_sale_tracker.is_flash_sale(request.sku_id)
+        flash_sale_multiplier = 1.12 if detected_flash_sale else 1.0
+
+        candidate_price = blended_price * inventory_adjustment * demand_adjustment
+        candidate_price *= flash_sale_multiplier
+        guardrailed_price = self._apply_guardrails(
+            candidate_price=candidate_price,
+            base_cost=request.base_cost,
+            current_price=request.current_price,
+        )
+        confidence = self._confidence_score(request, live_competitor_price)
+        reason = self._build_reason(
+            inventory_adjustment=inventory_adjustment,
+            demand_adjustment=demand_adjustment,
+            detected_flash_sale=detected_flash_sale,
+        )
+
+        response = PricingResponse(
+            sku_id=request.sku_id,
+            recommended_price=round(guardrailed_price, 2),
+            ml_price=round(ml_price, 2),
+            blended_price=round(blended_price, 2),
+            inventory_adjustment=round(inventory_adjustment, 3),
+            demand_adjustment=round(demand_adjustment, 3),
+            flash_sale_multiplier=round(flash_sale_multiplier, 3),
+            confidence=round(confidence, 3),
+            detected_flash_sale=detected_flash_sale,
+            reason=reason,
+            generated_at=datetime.now(UTC),
+        )
+        self._append_price_history(response, request.base_cost)
+        return PricingRecommendation(
+            response=response,
+            ml_price=ml_price,
+            blended_price=blended_price,
+        )
+
+    def recommend_kaggle_price(
+        self, request: KagglePricingRequest
+    ) -> KagglePricingRecommendation:
+        if self.dataset_profile != "kaggle_retail":
+            raise ValueError(
+                "The loaded model is not compatible with the Kaggle retail pricing request schema."
+            )
+
+        payload = request.model_dump()
+        current_price = payload.pop("current_price")
+        feature_frame = pd.DataFrame([payload])[
+            KAGGLE_RETAIL_NUMERIC_FEATURES + KAGGLE_RETAIL_CATEGORICAL_FEATURES
+        ]
+        ml_price = float(self.pipeline.predict(feature_frame)[0])
+
+        competitor_values = [
+            payload["comp_1"] or 0.0,
+            payload["comp_2"] or 0.0,
+            payload["comp_3"] or 0.0,
+        ]
+        non_zero_competitors = [value for value in competitor_values if value > 0]
+        competitor_anchor = (
+            sum(non_zero_competitors) / len(non_zero_competitors)
+            if non_zero_competitors
+            else None
+        )
+        confidence = self._kaggle_confidence_score(request, competitor_anchor)
+        reason = self._build_kaggle_reason(current_price, ml_price, competitor_anchor)
+
+        response = KagglePricingResponse(
+            product_id=request.product_id,
+            product_category_name=request.product_category_name,
+            recommended_price=round(ml_price, 2),
+            current_price=round(current_price, 2),
+            gap_to_current_price=round(ml_price - current_price, 2),
+            competitor_anchor_price=(
+                round(competitor_anchor, 2) if competitor_anchor is not None else None
+            ),
+            confidence=round(confidence, 3),
+            reason=reason,
+            generated_at=datetime.now(UTC),
+        )
+        return KagglePricingRecommendation(response=response, ml_price=ml_price)
+
+    def register_order_event(self, event: OrderEvent) -> bool:
+        if event.event_time.tzinfo is None:
+            event = OrderEvent(
+                sku_id=event.sku_id,
+                quantity=event.quantity,
+                event_time=event.event_time.replace(tzinfo=UTC),
+            )
+        return self.flash_sale_tracker.register(event)
+
+    def get_cached_recommendation(self, sku_id: str) -> dict[str, object] | None:
+        return self.cache.get_json(f"price:{sku_id}")
+
+    def _inventory_adjustment(self, inventory_level: int, inventory_days_cover: float) -> float:
+        if inventory_level <= 15 or inventory_days_cover < 3:
+            return 1.10
+        if inventory_level >= 120 or inventory_days_cover > 21:
+            return 0.93
+        return 1.0
+
+    def _demand_adjustment(
+        self,
+        units_sold_last_5m: int,
+        units_sold_last_1h: int,
+        conversion_rate: float,
+        is_festival: int,
+    ) -> float:
+        rapid_demand = units_sold_last_5m >= 8 or units_sold_last_1h >= 40
+        strong_conversion = conversion_rate >= 0.045
+        if rapid_demand and strong_conversion:
+            return 1.08 + (0.03 if is_festival else 0.0)
+        if units_sold_last_1h <= 8 and conversion_rate < 0.02:
+            return 0.94
+        return 1.0
+
+    def _apply_guardrails(self, candidate_price: float, base_cost: float, current_price: float) -> float:
+        min_price = base_cost * (1.0 + self.settings.min_margin)
+        max_price = current_price * self.settings.max_price_multiplier
+        return max(min(candidate_price, max_price), min_price)
+
+    def _confidence_score(self, request: PricingRequest, competitor_price: float) -> float:
+        signal_score = min(request.conversion_rate * 12 + request.click_through_rate * 4, 0.45)
+        inventory_score = 0.25 if request.inventory_level > 10 else 0.12
+        competitor_score = 0.20 if competitor_price > 0 else 0.08
+        recency_score = 0.10 if request.units_sold_last_1h > 0 else 0.04
+        return min(signal_score + inventory_score + competitor_score + recency_score, 0.98)
+
+    def _build_reason(
+        self,
+        inventory_adjustment: float,
+        demand_adjustment: float,
+        detected_flash_sale: bool,
+    ) -> str:
+        reasons = ["ML baseline with competitor blending"]
+        if inventory_adjustment > 1.0:
+            reasons.append("low inventory pressure")
+        elif inventory_adjustment < 1.0:
+            reasons.append("overstock discount")
+        if demand_adjustment > 1.0:
+            reasons.append("strong short-term demand")
+        elif demand_adjustment < 1.0:
+            reasons.append("soft demand correction")
+        if detected_flash_sale:
+            reasons.append("flash sale multiplier active")
+        return ", ".join(reasons)
+
+    def _kaggle_confidence_score(
+        self,
+        request: KagglePricingRequest,
+        competitor_anchor: float | None,
+    ) -> float:
+        demand_score = min((request.qty / 40) + (request.customers / 80), 0.40)
+        rating_score = min(request.product_score / 10, 0.20)
+        competitor_score = 0.20 if competitor_anchor is not None else 0.08
+        recency_score = 0.10 if request.lag_price > 0 else 0.04
+        seasonal_score = 0.10 if request.holiday or request.weekend else 0.05
+        return min(
+            demand_score + rating_score + competitor_score + recency_score + seasonal_score,
+            0.97,
+        )
+
+    def _build_kaggle_reason(
+        self,
+        current_price: float,
+        ml_price: float,
+        competitor_anchor: float | None,
+    ) -> str:
+        reasons = ["Kaggle retail model baseline"]
+        if competitor_anchor is not None:
+            if ml_price > competitor_anchor:
+                reasons.append("positioned above competitor average")
+            elif ml_price < competitor_anchor:
+                reasons.append("positioned below competitor average")
+            else:
+                reasons.append("aligned with competitor average")
+        if ml_price > current_price:
+            reasons.append("upside versus current price")
+        elif ml_price < current_price:
+            reasons.append("defensive move versus current price")
+        else:
+            reasons.append("flat versus current price")
+        return ", ".join(reasons)
+
+    def _append_price_history(self, response: PricingResponse, base_cost: float) -> None:
+        path = self.settings.price_history_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        file_exists = path.exists()
+        with path.open("a", newline="", encoding="utf-8") as handle:
+            writer = csv.writer(handle)
+            if not file_exists:
+                writer.writerow(
+                    [
+                        "generated_at",
+                        "sku_id",
+                        "recommended_price",
+                        "ml_price",
+                        "blended_price",
+                        "confidence",
+                        "detected_flash_sale",
+                        "base_cost",
+                    ]
+                )
+            writer.writerow(
+                [
+                    response.generated_at.isoformat(),
+                    response.sku_id,
+                    response.recommended_price,
+                    response.ml_price,
+                    response.blended_price,
+                    response.confidence,
+                    int(response.detected_flash_sale),
+                    round(base_cost, 2),
+                ]
+            )
+        self.cache.set_json(f"price:{response.sku_id}", response.model_dump(mode="json"))

app/schemas.py

@@ -0,0 +1,94 @@
+from datetime import UTC, datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class PricingRequest(BaseModel):
+    sku_id: str = Field(..., examples=["SKU-1001"])
+    category: str
+    brand: str
+    customer_segment: str
+    hour_of_day: int = Field(..., ge=0, le=23)
+    day_of_week: int = Field(..., ge=0, le=6)
+    is_weekend: int = Field(..., ge=0, le=1)
+    is_festival: int = Field(..., ge=0, le=1)
+    inventory_level: int = Field(..., ge=0)
+    inventory_days_cover: float = Field(..., ge=0)
+    competitor_price: float = Field(..., gt=0)
+    click_through_rate: float = Field(..., ge=0)
+    conversion_rate: float = Field(..., ge=0)
+    units_sold_last_5m: int = Field(..., ge=0)
+    units_sold_last_1h: int = Field(..., ge=0)
+    base_cost: float = Field(..., gt=0)
+    current_price: float = Field(..., gt=0)
+
+
+class PricingResponse(BaseModel):
+    sku_id: str
+    recommended_price: float
+    ml_price: float
+    blended_price: float
+    inventory_adjustment: float
+    demand_adjustment: float
+    flash_sale_multiplier: float
+    confidence: float
+    detected_flash_sale: bool
+    reason: str
+    generated_at: datetime
+
+
+class KagglePricingRequest(BaseModel):
+    product_id: str
+    product_category_name: str
+    qty: int = Field(..., ge=0)
+    freight_price: float = Field(..., ge=0)
+    product_name_lenght: int = Field(..., ge=0)
+    product_description_lenght: int = Field(..., ge=0)
+    product_photos_qty: int = Field(..., ge=0)
+    product_weight_g: int = Field(..., ge=0)
+    product_score: float = Field(..., ge=0)
+    customers: int = Field(..., ge=0)
+    weekday: int = Field(..., ge=0)
+    weekend: int = Field(..., ge=0, le=1)
+    holiday: int = Field(..., ge=0, le=1)
+    volume: float = Field(..., ge=0)
+    comp_1: float = Field(..., ge=0)
+    ps1: float = Field(..., ge=0)
+    fp1: float = Field(..., ge=0)
+    comp_2: float = Field(..., ge=0)
+    ps2: float = Field(..., ge=0)
+    fp2: float = Field(..., ge=0)
+    comp_3: float = Field(..., ge=0)
+    ps3: float = Field(..., ge=0)
+    fp3: float = Field(..., ge=0)
+    lag_price: float = Field(..., ge=0)
+    month: int = Field(..., ge=1, le=12)
+    year: int = Field(..., ge=2000)
+    current_price: float = Field(..., gt=0)
+
+
+class KagglePricingResponse(BaseModel):
+    product_id: str
+    product_category_name: str
+    recommended_price: float
+    current_price: float
+    gap_to_current_price: float
+    competitor_anchor_price: Optional[float] = None
+    confidence: float
+    reason: str
+    generated_at: datetime
+
+
+class OrderEvent(BaseModel):
+    sku_id: str
+    quantity: int = Field(..., ge=1)
+    event_time: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class MonitoringSummary(BaseModel):
+    tracked_skus: int
+    recent_order_events: int
+    flash_sale_skus: list[str]
+    average_recommended_price: Optional[float] = None
+    last_price_update: Optional[datetime] = None

app/streaming.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from kafka import KafkaConsumer, KafkaProducer
+
+from app.config import Settings
+
+
+class PricingEventProducer:
+    def __init__(self, settings: Settings):
+        self.producer = KafkaProducer(
+            bootstrap_servers=settings.kafka_bootstrap_servers,
+            value_serializer=lambda value: json.dumps(value).encode("utf-8"),
+        )
+        self.order_topic = settings.kafka_topic_orders
+        self.click_topic = settings.kafka_topic_clicks
+
+    def publish_order(self, payload: dict[str, Any]) -> None:
+        self.producer.send(self.order_topic, payload)
+        self.producer.flush()
+
+    def publish_click(self, payload: dict[str, Any]) -> None:
+        self.producer.send(self.click_topic, payload)
+        self.producer.flush()
+
+
+class PricingEventConsumer:
+    def __init__(self, settings: Settings, topic: str):
+        self.consumer = KafkaConsumer(
+            topic,
+            bootstrap_servers=settings.kafka_bootstrap_servers,
+            value_deserializer=lambda value: json.loads(value.decode("utf-8")),
+            auto_offset_reset="latest",
+            enable_auto_commit=True,
+            group_id="dynamic-pricing-engine",
+        )
+
+    def poll_forever(self):
+        for message in self.consumer:
+            yield message.value

data/processed/price_history.csv

@@ -0,0 +1,70 @@
+generated_at,sku_id,recommended_price,ml_price,blended_price,confidence,detected_flash_sale,base_cost
+2026-04-21T16:35:56.869147+00:00,SKU-1001,1846.47,1952.53,1846.47,0.98,0,1099.0
+2026-04-21T16:36:06.169412+00:00,SKU-1001,1824.11,1920.58,1824.11,0.98,0,1099.0
+2026-04-21T16:36:09.061906+00:00,SKU-1001,1830.16,1929.23,1830.16,0.98,0,1099.0
+2026-04-21T16:36:12.102664+00:00,SKU-1001,1726.65,1781.35,1726.65,0.98,0,1099.0
+2026-04-21T16:36:16.456700+00:00,SKU-1001,1809.18,1899.25,1809.18,0.98,0,1099.0
+2026-04-21T16:36:19.487604+00:00,SKU-1001,1683.61,1900.91,1810.33,0.98,0,1099.0
+2026-04-21T16:36:21.447530+00:00,SKU-1001,1683.22,1900.31,1809.91,0.98,0,1099.0
+2026-04-21T16:36:21.965440+00:00,SKU-1001,1617.1,1798.74,1738.82,0.98,0,1099.0
+2026-04-21T16:36:22.727797+00:00,SKU-1001,1617.1,1798.74,1738.82,0.98,0,1099.0
+2026-04-21T16:36:25.535797+00:00,SKU-1001,1688.4,1908.26,1815.48,0.98,0,1099.0
+2026-04-21T16:36:27.590880+00:00,SKU-1001,1688.87,1908.98,1815.99,0.98,0,1099.0
+2026-04-21T16:36:28.254023+00:00,SKU-1001,1830.86,1918.78,1822.84,0.98,0,1099.0
+2026-04-21T16:36:34.377046+00:00,SKU-1001,118692.0,2235.42,2044.5,0.98,0,109900.0
+2026-04-21T16:36:46.348417+00:00,SKU-1001,118702.8,2235.42,2044.5,0.98,0,109910.0
+2026-04-21T16:44:11.552598+00:00,SKU-1001,1846.47,1952.53,1846.47,0.98,0,1099.0
+2026-04-21T16:44:21.857252+00:00,SKU-1001,1720.19,1772.13,1720.19,0.98,0,1099.0
+2026-04-21T16:44:24.992938+00:00,SKU-1001,1721.57,1774.09,1721.57,0.98,0,1099.0
+2026-04-21T16:44:28.848864+00:00,SKU-1001,1773.28,1847.97,1773.28,0.98,0,1099.0
+2026-04-21T16:44:32.162255+00:00,SKU-1001,1796.95,1881.79,1796.95,0.98,0,1099.0
+2026-04-21T16:44:34.207941+00:00,SKU-1001,1798.55,1884.07,1798.55,0.98,0,1109.0
+2026-04-21T16:44:34.739059+00:00,SKU-1001,1804.9,1893.15,1804.9,0.98,0,1129.0
+2026-04-21T16:44:35.259757+00:00,SKU-1001,1813.52,1905.46,1813.52,0.98,0,1149.0
+2026-04-21T16:44:35.850007+00:00,SKU-1001,1811.27,1902.24,1811.27,0.98,0,1169.0
+2026-04-21T16:44:53.610970+00:00,SKU-1001,1806.22,1895.02,1806.22,0.98,0,1169.0
+2026-04-21T16:48:43.383478+00:00,SKU-1001,1846.47,1952.53,1846.47,0.98,0,1099.0
+2026-04-21T16:48:45.430289+00:00,SKU-1001,1846.47,1952.53,1846.47,0.98,0,1099.0
+2026-04-21T16:48:50.348704+00:00,SKU-1001,1843.94,1948.91,1843.94,0.98,0,1099.0
+2026-04-21T16:48:55.262242+00:00,SKU-1001,1936.2,2080.72,1936.2,0.98,0,1099.0
+2026-04-21T16:49:01.321018+00:00,SKU-1001,1940.43,2086.75,1940.43,0.98,0,1099.0
+2026-04-21T16:49:02.387350+00:00,SKU-1001,1964.07,2120.52,1964.07,0.98,0,1099.0
+2026-04-21T16:49:09.054868+00:00,SKU-1005,1964.07,2120.52,1964.07,0.98,0,1099.0
+2026-04-21T16:49:12.592472+00:00,SKU-1005,1962.94,2118.91,1962.94,0.98,0,1099.0
+2026-04-21T16:49:13.194465+00:00,SKU-1005,1981.43,2145.32,1981.43,0.98,0,1099.0
+2026-04-21T16:49:17.226819+00:00,SKU-1005,1974.93,2136.04,1974.93,0.98,0,1099.0
+2026-04-21T16:49:20.262071+00:00,SKU-1005,2023.65,2163.3,1994.01,0.98,0,1099.0
+2026-04-21T16:49:20.651755+00:00,SKU-1005,2023.65,2163.3,1994.01,0.98,0,1099.0
+2026-04-21T16:49:23.217861+00:00,SKU-1005,2023.65,2163.3,1994.01,0.98,0,1109.0
+2026-04-21T16:49:23.517370+00:00,SKU-1005,2023.65,2173.31,2001.01,0.98,0,1119.0
+2026-04-21T16:49:23.690003+00:00,SKU-1005,2023.65,2173.31,2001.01,0.98,0,1129.0
+2026-04-21T16:49:24.026589+00:00,SKU-1005,2023.65,2194.31,2015.72,0.98,0,1149.0
+2026-04-21T16:49:24.508323+00:00,SKU-1005,2023.65,2205.4,2023.48,0.98,0,1179.0
+2026-04-21T16:49:24.699328+00:00,SKU-1005,2023.65,2209.74,2026.52,0.98,0,1189.0
+2026-04-21T16:49:24.944724+00:00,SKU-1005,2023.65,2214.01,2029.5,0.98,0,1199.0
+2026-04-21T16:49:25.126635+00:00,SKU-1005,2023.65,2225.49,2037.54,0.98,0,1209.0
+2026-04-21T16:49:25.301081+00:00,SKU-1005,2023.65,2228.17,2039.42,0.98,0,1219.0
+2026-04-21T16:49:27.441434+00:00,SKU-1005,2037.15,2228.17,2039.42,0.98,0,1219.0
+2026-04-21T16:49:27.887462+00:00,SKU-1005,2064.15,2234.03,2043.52,0.98,0,1219.0
+2026-04-21T16:49:28.140492+00:00,SKU-1005,2077.65,2239.74,2047.52,0.98,0,1219.0
+2026-04-21T16:49:28.616463+00:00,SKU-1005,2118.15,2274.12,2071.58,0.98,0,1219.0
+2026-04-21T16:49:29.118558+00:00,SKU-1005,2158.65,2301.54,2090.78,0.98,0,1219.0
+2026-04-21T16:49:29.550719+00:00,SKU-1005,2185.65,2319.45,2103.31,0.98,0,1219.0
+2026-04-21T16:49:57.818086+00:00,SKU-1005,2019.39,2199.55,2019.39,0.98,0,1219.0
+2026-04-21T16:50:01.947178+00:00,SKU-1005,2035.79,2222.99,2035.79,0.98,0,1219.0
+2026-04-21T16:50:02.383211+00:00,SKU-1005,2033.13,2219.19,2033.13,0.98,0,1219.0
+2026-04-21T16:50:04.637259+00:00,SKU-1005,1930.52,2072.6,1930.52,0.98,0,1219.0
+2026-04-21T16:50:08.002970+00:00,SKU-1005,1611.32,1616.6,1611.32,0.98,0,100.0
+2026-04-21T16:50:13.499079+00:00,SKU-1005,202.5,1352.2,1426.24,0.98,0,100.0
+2026-04-21T16:50:16.797317+00:00,SKU-1005,229.5,1352.2,1426.24,0.98,0,100.0
+2026-04-21T16:50:17.456294+00:00,SKU-1005,229.5,1362.9,1433.73,0.83,0,100.0
+2026-04-21T16:50:24.212795+00:00,SKU-1005,229.5,271.31,249.92,0.83,0,100.0
+2026-04-21T16:50:27.827508+00:00,SKU-1005,229.5,272.15,250.5,0.83,0,100.0
+2026-04-21T16:50:29.384452+00:00,SKU-1005,229.5,272.75,250.93,0.83,0,100.0
+2026-04-21T16:50:30.105410+00:00,SKU-1005,229.5,268.04,247.63,0.83,0,100.0
+2026-04-21T16:50:32.755645+00:00,SKU-1005,229.5,269.37,248.56,0.83,0,100.0
+2026-04-21T16:50:34.454427+00:00,SKU-1005,229.5,269.05,248.33,0.83,0,100.0
+2026-04-21T16:50:37.080575+00:00,SKU-1005,229.5,258.19,240.73,0.83,0,100.0
+2026-04-21T16:50:41.376678+00:00,SKU-1005,229.5,255.08,238.56,0.83,0,100.0
+2026-04-21T16:50:44.174612+00:00,SKU-1005,229.5,250.01,235.01,0.83,0,100.0
+2026-04-21T16:50:46.691114+00:00,SKU-1005,229.5,238.24,226.77,0.83,0,100.0

deploy/ec2/dynamic-pricing-api.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=Dynamic Pricing Engine FastAPI Service
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+WorkingDirectory=/opt/dynamic-pricing-engine
+EnvironmentFile=/opt/dynamic-pricing-engine/.env
+Environment=PROJECT_DIR=/opt/dynamic-pricing-engine
+Environment=VENV_DIR=/opt/dynamic-pricing-engine/.venv
+ExecStart=/opt/dynamic-pricing-engine/deploy/ec2/start_api.sh
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

deploy/ec2/dynamic-pricing-dashboard.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=Dynamic Pricing Engine Streamlit Dashboard
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+WorkingDirectory=/opt/dynamic-pricing-engine
+EnvironmentFile=/opt/dynamic-pricing-engine/.env
+Environment=PROJECT_DIR=/opt/dynamic-pricing-engine
+Environment=VENV_DIR=/opt/dynamic-pricing-engine/.venv
+ExecStart=/opt/dynamic-pricing-engine/deploy/ec2/start_dashboard.sh
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

deploy/ec2/start_api.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_DIR="${PROJECT_DIR:-/opt/dynamic-pricing-engine}"
+VENV_DIR="${VENV_DIR:-$PROJECT_DIR/.venv}"
+HOST="${HOST:-0.0.0.0}"
+PORT="${PORT:-8000}"
+WORKERS="${WORKERS:-1}"
+
+cd "$PROJECT_DIR"
+source "$VENV_DIR/bin/activate"
+
+exec uvicorn app.api:app --host "$HOST" --port "$PORT" --workers "$WORKERS"

deploy/ec2/start_dashboard.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_DIR="${PROJECT_DIR:-/opt/dynamic-pricing-engine}"
+VENV_DIR="${VENV_DIR:-$PROJECT_DIR/.venv}"
+HOST="${HOST:-0.0.0.0}"
+PORT="${PORT:-8501}"
+
+cd "$PROJECT_DIR"
+source "$VENV_DIR/bin/activate"
+
+exec streamlit run app/dashboard.py \
+  --server.address "$HOST" \
+  --server.port "$PORT" \
+  --server.headless true

docker-compose.yml

@@ -0,0 +1,29 @@
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: dynamic-pricing-api
+    env_file:
+      - .env.example
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./data:/app/data
+      - ./models:/app/models
+    restart: unless-stopped
+  dashboard:
+    build:
+      context: .
+      dockerfile: Dockerfile.streamlit
+    container_name: dynamic-pricing-dashboard
+    env_file:
+      - .env.example
+    ports:
+      - "8501:8501"
+    volumes:
+      - ./data:/app/data
+      - ./models:/app/models
+    depends_on:
+      - api
+    restart: unless-stopped

models/training_metrics.json

@@ -0,0 +1,22 @@
+{
+  "dataset_profile": "kaggle_retail",
+  "data_path": "data\\raw\\kaggle\\retail_price.csv",
+  "best_model": "random_forest",
+  "best_model_metrics": {
+    "mae": 3.105130602318404,
+    "rmse": 6.731112904256394,
+    "r2": 0.9916132145995052
+  },
+  "all_models": {
+    "random_forest": {
+      "mae": 3.105130602318404,
+      "rmse": 6.731112904256394,
+      "r2": 0.9916132145995052
+    },
+    "xgboost": {
+      "mae": 3.311133864318597,
+      "rmse": 6.585257755436754,
+      "r2": 0.9919727398685239
+    }
+  }
+}

requirements.txt

@@ -0,0 +1,17 @@
+fastapi==0.115.0
+uvicorn==0.30.6
+streamlit==1.39.0
+pandas==2.2.3
+numpy==2.1.1
+scikit-learn==1.5.2
+xgboost==2.1.1
+joblib==1.4.2
+pydantic==2.9.2
+pydantic-settings==2.5.2
+requests==2.32.3
+redis==5.1.1
+kafka-python==2.0.2
+python-dotenv==1.0.1
+plotly==5.24.1
+pytest==8.3.3
+httpx==0.27.2

scripts/generate_sample_data.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+import numpy as np
+import pandas as pd
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from app.config import get_settings
+
+
+def generate_dataset(rows: int, seed: int = 42) -> pd.DataFrame:
+    rng = np.random.default_rng(seed)
+    categories = np.array(["electronics", "fashion", "home", "beauty", "grocery"])
+    brands = np.array(["brand_a", "brand_b", "brand_c", "brand_d"])
+    segments = np.array(["budget", "standard", "premium", "loyal"])
+
+    category = rng.choice(categories, size=rows, p=[0.24, 0.22, 0.18, 0.16, 0.20])
+    brand = rng.choice(brands, size=rows)
+    customer_segment = rng.choice(segments, size=rows, p=[0.25, 0.40, 0.20, 0.15])
+    hour_of_day = rng.integers(0, 24, size=rows)
+    day_of_week = rng.integers(0, 7, size=rows)
+    is_weekend = (day_of_week >= 5).astype(int)
+    is_festival = rng.binomial(1, 0.12, size=rows)
+    inventory_level = rng.integers(5, 180, size=rows)
+    inventory_days_cover = np.round(rng.uniform(1.0, 28.0, size=rows), 2)
+    base_cost = np.round(rng.uniform(150.0, 2200.0, size=rows), 2)
+
+    category_factor = {
+        "electronics": 1.55,
+        "fashion": 1.35,
+        "home": 1.25,
+        "beauty": 1.48,
+        "grocery": 1.18,
+    }
+    segment_factor = {
+        "budget": 0.95,
+        "standard": 1.0,
+        "premium": 1.16,
+        "loyal": 1.08,
+    }
+
+    base_markup = np.array([category_factor[item] for item in category]) * np.array(
+        [segment_factor[item] for item in customer_segment]
+    )
+    competitor_price = np.round(base_cost * base_markup * rng.uniform(0.92, 1.08, size=rows), 2)
+    current_price = np.round(competitor_price * rng.uniform(0.96, 1.08, size=rows), 2)
+    click_through_rate = np.round(rng.uniform(0.01, 0.15, size=rows), 4)
+    conversion_rate = np.round(rng.uniform(0.008, 0.08, size=rows), 4)
+    units_sold_last_5m = rng.poisson(4 + is_festival * 2 + is_weekend, size=rows)
+    units_sold_last_1h = rng.poisson(18 + is_festival * 10 + is_weekend * 4, size=rows)
+
+    demand_multiplier = (
+        1
+        + is_festival * 0.10
+        + is_weekend * 0.04
+        + (hour_of_day >= 18).astype(int) * 0.05
+        + (conversion_rate * 2.5)
+        + (units_sold_last_1h / 300)
+    )
+    inventory_multiplier = np.where(
+        inventory_level < 20,
+        1.11,
+        np.where(inventory_level > 120, 0.93, 1.0),
+    )
+    optimal_price = (
+        base_cost
+        * base_markup
+        * demand_multiplier
+        * inventory_multiplier
+        * rng.uniform(0.97, 1.03, size=rows)
+    )
+    optimal_price = np.minimum(optimal_price, current_price * 1.30)
+    optimal_price = np.maximum(optimal_price, base_cost * 1.08)
+
+    frame = pd.DataFrame(
+        {
+            "sku_id": [f"SKU-{1000 + idx}" for idx in range(rows)],
+            "category": category,
+            "brand": brand,
+            "customer_segment": customer_segment,
+            "hour_of_day": hour_of_day,
+            "day_of_week": day_of_week,
+            "is_weekend": is_weekend,
+            "is_festival": is_festival,
+            "inventory_level": inventory_level,
+            "inventory_days_cover": inventory_days_cover,
+            "competitor_price": competitor_price,
+            "click_through_rate": click_through_rate,
+            "conversion_rate": conversion_rate,
+            "units_sold_last_5m": units_sold_last_5m,
+            "units_sold_last_1h": units_sold_last_1h,
+            "base_cost": base_cost,
+            "current_price": current_price,
+            "optimal_price": np.round(optimal_price, 2),
+        }
+    )
+    return frame
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate synthetic pricing events data.")
+    parser.add_argument("--rows", type=int, default=25000, help="Number of rows to generate")
+    parser.add_argument("--seed", type=int, default=42, help="Random seed")
+    args = parser.parse_args()
+
+    settings = get_settings()
+    frame = generate_dataset(rows=args.rows, seed=args.seed)
+    settings.raw_data_path.parent.mkdir(parents=True, exist_ok=True)
+    frame.to_csv(settings.raw_data_path, index=False)
+    print(f"Saved {len(frame)} rows to {settings.raw_data_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/train_model.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from app.config import get_settings
+from app.modeling import train_best_model
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Train pricing model on synthetic or Kaggle data.")
+    parser.add_argument(
+        "--profile",
+        default="synthetic",
+        choices=["synthetic", "kaggle_retail"],
+        help="Dataset profile to train on.",
+    )
+    parser.add_argument(
+        "--data-path",
+        default=None,
+        help="Optional override for the CSV file path.",
+    )
+    args = parser.parse_args()
+
+    settings = get_settings()
+    data_path = Path(args.data_path) if args.data_path else settings.raw_data_path
+    result = train_best_model(
+        data_path=data_path,
+        artifact_path=settings.model_path,
+        metrics_path=settings.metrics_path,
+        dataset_profile=args.profile,
+    )
+    print(
+        f"Profile: {result.dataset_profile} | Best model: {result.model_name} | "
+        f"MAE={result.mae:.2f} | RMSE={result.rmse:.2f} | R2={result.r2:.3f}"
+    )
+
+
+if __name__ == "__main__":
+    main()

tests/smoke_test.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+import compileall
+
+
+def test_project_compiles() -> None:
+    root = Path(__file__).resolve().parent.parent
+    assert compileall.compile_dir(root / "app", quiet=1)
+    assert compileall.compile_dir(root / "scripts", quiet=1)

tests/test_api.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from fastapi.testclient import TestClient
+
+from app import api
+from app.schemas import KagglePricingResponse, MonitoringSummary, PricingResponse
+
+
+@dataclass
+class _DummySettings:
+    model_path: Path
+    metrics_path: Path
+    price_history_path: Path
+
+
+class _DummyTracker:
+    def __init__(self) -> None:
+        self.events = {"SKU-1": []}
+
+    def recent_event_count(self) -> int:
+        return 3
+
+    def flash_sale_skus(self) -> list[str]:
+        return ["SKU-1"]
+
+
+class _SyntheticEngine:
+    dataset_profile = "synthetic"
+
+    def __init__(self) -> None:
+        self.flash_sale_tracker = _DummyTracker()
+
+    def recommend_price(self, _request):
+        response = PricingResponse(
+            sku_id="SKU-1",
+            recommended_price=125.0,
+            ml_price=120.0,
+            blended_price=123.0,
+            inventory_adjustment=1.0,
+            demand_adjustment=1.0,
+            flash_sale_multiplier=1.0,
+            confidence=0.81,
+            detected_flash_sale=False,
+            reason="test synthetic response",
+            generated_at=datetime.now(UTC),
+        )
+        return type("SyntheticResult", (), {"response": response})()
+
+    def register_order_event(self, _event) -> bool:
+        return False
+
+
+class _KaggleEngine:
+    dataset_profile = "kaggle_retail"
+
+    def __init__(self) -> None:
+        self.flash_sale_tracker = _DummyTracker()
+
+    def recommend_price(self, _request):
+        raise ValueError("The loaded model is not compatible with the synthetic pricing request schema.")
+
+    def recommend_kaggle_price(self, _request):
+        response = KagglePricingResponse(
+            product_id="P-1",
+            product_category_name="electronics",
+            recommended_price=199.0,
+            current_price=189.0,
+            gap_to_current_price=10.0,
+            competitor_anchor_price=193.0,
+            confidence=0.76,
+            reason="test kaggle response",
+            generated_at=datetime.now(UTC),
+        )
+        return type("KaggleResult", (), {"response": response})()
+
+    def register_order_event(self, _event) -> bool:
+        return False
+
+
+def _build_client(monkeypatch, tmp_path: Path, engine_instance):
+    model_path = tmp_path / "model.joblib"
+    metrics_path = tmp_path / "metrics.json"
+    history_path = tmp_path / "history.csv"
+    model_path.write_text("stub", encoding="utf-8")
+    metrics_path.write_text('{"ok": true}', encoding="utf-8")
+    history_path.write_text(
+        "generated_at,recommended_price\n2026-04-22T10:00:00+00:00,150.0\n",
+        encoding="utf-8",
+    )
+
+    settings = _DummySettings(
+        model_path=model_path,
+        metrics_path=metrics_path,
+        price_history_path=history_path,
+    )
+
+    monkeypatch.setattr(api, "get_settings", lambda: settings)
+    monkeypatch.setattr(api, "PricingEngine", lambda _settings: engine_instance)
+    return TestClient(api.app)
+
+
+def test_health_reports_active_profile(monkeypatch, tmp_path: Path) -> None:
+    with _build_client(monkeypatch, tmp_path, _SyntheticEngine()) as client:
+        response = client.get("/health")
+        assert response.status_code == 200
+        payload = response.json()
+        assert payload["model_loaded"] is True
+        assert payload["dataset_profile"] == "synthetic"
+        assert payload["supported_endpoints"]["kaggle_retail"] == "/price/recommend/kaggle"
+
+
+def test_synthetic_recommendation_endpoint(monkeypatch, tmp_path: Path) -> None:
+    with _build_client(monkeypatch, tmp_path, _SyntheticEngine()) as client:
+        response = client.post(
+            "/price/recommend",
+            json={
+                "sku_id": "SKU-1",
+                "category": "electronics",
+                "brand": "brand_a",
+                "customer_segment": "premium",
+                "hour_of_day": 12,
+                "day_of_week": 2,
+                "is_weekend": 0,
+                "is_festival": 0,
+                "inventory_level": 30,
+                "inventory_days_cover": 10,
+                "competitor_price": 100,
+                "click_through_rate": 0.05,
+                "conversion_rate": 0.03,
+                "units_sold_last_5m": 4,
+                "units_sold_last_1h": 18,
+                "base_cost": 70,
+                "current_price": 115,
+            },
+        )
+        assert response.status_code == 200
+        assert response.json()["recommended_price"] == 125.0
+
+
+def test_kaggle_recommendation_endpoint(monkeypatch, tmp_path: Path) -> None:
+    with _build_client(monkeypatch, tmp_path, _KaggleEngine()) as client:
+        response = client.post(
+            "/price/recommend/kaggle",
+            json={
+                "product_id": "P-1",
+                "product_category_name": "electronics",
+                "qty": 10,
+                "freight_price": 5,
+                "product_name_lenght": 20,
+                "product_description_lenght": 80,
+                "product_photos_qty": 2,
+                "product_weight_g": 800,
+                "product_score": 4.2,
+                "customers": 7,
+                "weekday": 3,
+                "weekend": 0,
+                "holiday": 0,
+                "volume": 3200,
+                "comp_1": 195,
+                "ps1": 4.0,
+                "fp1": 5,
+                "comp_2": 193,
+                "ps2": 4.1,
+                "fp2": 4,
+                "comp_3": 191,
+                "ps3": 4.3,
+                "fp3": 6,
+                "lag_price": 188,
+                "month": 4,
+                "year": 2026,
+                "current_price": 189,
+            },
+        )
+        assert response.status_code == 200
+        assert response.json()["gap_to_current_price"] == 10.0
+
+
+def test_profile_mismatch_returns_conflict(monkeypatch, tmp_path: Path) -> None:
+    with _build_client(monkeypatch, tmp_path, _KaggleEngine()) as client:
+        response = client.post(
+            "/price/recommend",
+            json={
+                "sku_id": "SKU-1",
+                "category": "electronics",
+                "brand": "brand_a",
+                "customer_segment": "premium",
+                "hour_of_day": 12,
+                "day_of_week": 2,
+                "is_weekend": 0,
+                "is_festival": 0,
+                "inventory_level": 30,
+                "inventory_days_cover": 10,
+                "competitor_price": 100,
+                "click_through_rate": 0.05,
+                "conversion_rate": 0.03,
+                "units_sold_last_5m": 4,
+                "units_sold_last_1h": 18,
+                "base_cost": 70,
+                "current_price": 115,
+            },
+        )
+        assert response.status_code == 409
+
+
+def test_monitoring_summary_uses_history_file(monkeypatch, tmp_path: Path) -> None:
+    with _build_client(monkeypatch, tmp_path, _SyntheticEngine()) as client:
+        response = client.get("/monitoring/summary")
+        assert response.status_code == 200
+        payload = MonitoringSummary.model_validate(response.json())
+        assert payload.average_recommended_price == 150.0
+        assert payload.flash_sale_skus == ["SKU-1"]

tests/test_pricing_engine.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from app.config import Settings
+from app.pricing_engine import PricingEngine
+from app.schemas import KagglePricingRequest, OrderEvent, PricingRequest
+
+
+class _StaticSyntheticPipeline:
+    def predict(self, _frame):
+        return [200.0]
+
+
+class _StaticKagglePipeline:
+    def predict(self, _frame):
+        return [212.5]
+
+
+def _build_settings(tmp_path: Path) -> Settings:
+    model_path = tmp_path / "model.joblib"
+    metrics_path = tmp_path / "metrics.json"
+    raw_data_path = tmp_path / "raw.csv"
+    price_history_path = tmp_path / "history.csv"
+    model_path.write_text("stub", encoding="utf-8")
+    metrics_path.write_text("{}", encoding="utf-8")
+    raw_data_path.write_text("", encoding="utf-8")
+    return Settings(
+        model_path=model_path,
+        metrics_path=metrics_path,
+        raw_data_path=raw_data_path,
+        price_history_path=price_history_path,
+        redis_url="",
+    )
+
+
+def test_synthetic_recommendation_applies_guardrails(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(
+        "app.pricing_engine.load_model_bundle",
+        lambda _path: {"dataset_profile": "synthetic", "pipeline": _StaticSyntheticPipeline()},
+    )
+    engine = PricingEngine(_build_settings(tmp_path))
+    engine.competitor_client.get_price = lambda _sku_id, fallback_price: fallback_price
+
+    result = engine.recommend_price(
+        PricingRequest(
+            sku_id="SKU-9",
+            category="electronics",
+            brand="brand_a",
+            customer_segment="premium",
+            hour_of_day=20,
+            day_of_week=5,
+            is_weekend=1,
+            is_festival=1,
+            inventory_level=10,
+            inventory_days_cover=2.0,
+            competitor_price=195.0,
+            click_through_rate=0.08,
+            conversion_rate=0.05,
+            units_sold_last_5m=10,
+            units_sold_last_1h=60,
+            base_cost=100.0,
+            current_price=130.0,
+        )
+    )
+
+    assert result.response.recommended_price == 175.5
+    assert result.response.flash_sale_multiplier == 1.0
+    assert result.response.inventory_adjustment == 1.1
+    assert result.response.demand_adjustment == 1.11
+
+
+def test_flash_sale_detection_activates_multiplier(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(
+        "app.pricing_engine.load_model_bundle",
+        lambda _path: {"dataset_profile": "synthetic", "pipeline": _StaticSyntheticPipeline()},
+    )
+    engine = PricingEngine(_build_settings(tmp_path))
+    engine.competitor_client.get_price = lambda _sku_id, fallback_price: fallback_price
+
+    now = datetime.now(UTC)
+    for _ in range(engine.settings.flash_sale_order_threshold):
+        engine.register_order_event(OrderEvent(sku_id="SKU-1", quantity=1, event_time=now))
+
+    result = engine.recommend_price(
+        PricingRequest(
+            sku_id="SKU-1",
+            category="electronics",
+            brand="brand_a",
+            customer_segment="premium",
+            hour_of_day=20,
+            day_of_week=5,
+            is_weekend=1,
+            is_festival=0,
+            inventory_level=50,
+            inventory_days_cover=8.0,
+            competitor_price=200.0,
+            click_through_rate=0.06,
+            conversion_rate=0.05,
+            units_sold_last_5m=8,
+            units_sold_last_1h=50,
+            base_cost=100.0,
+            current_price=150.0,
+        )
+    )
+
+    assert result.response.detected_flash_sale is True
+    assert result.response.flash_sale_multiplier == 1.12
+
+
+def test_kaggle_recommendation_uses_current_and_competitor_context(
+    monkeypatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(
+        "app.pricing_engine.load_model_bundle",
+        lambda _path: {"dataset_profile": "kaggle_retail", "pipeline": _StaticKagglePipeline()},
+    )
+    engine = PricingEngine(_build_settings(tmp_path))
+
+    result = engine.recommend_kaggle_price(
+        KagglePricingRequest(
+            product_id="P-55",
+            product_category_name="home",
+            qty=12,
+            freight_price=4.5,
+            product_name_lenght=24,
+            product_description_lenght=90,
+            product_photos_qty=3,
+            product_weight_g=700,
+            product_score=4.4,
+            customers=8,
+            weekday=2,
+            weekend=0,
+            holiday=0,
+            volume=6480,
+            comp_1=208.0,
+            ps1=4.0,
+            fp1=5.0,
+            comp_2=210.0,
+            ps2=4.1,
+            fp2=5.0,
+            comp_3=206.0,
+            ps3=4.2,
+            fp3=6.0,
+            lag_price=198.0,
+            month=4,
+            year=2026,
+            current_price=199.0,
+        )
+    )
+
+    assert result.response.recommended_price == 212.5
+    assert result.response.gap_to_current_price == 13.5
+    assert result.response.competitor_anchor_price == 208.0
+    assert "current price" in result.response.reason