Deploy IBKR Workbench with Hugging Face daily data

Dockerfile

@@ -0,0 +1,33 @@
+# Hugging Face Docker Space: build the React UI, then serve it with FastAPI.
+FROM node:22-alpine AS frontend-builder
+
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
+
+FROM python:3.12-slim AS runtime
+
+WORKDIR /app
+RUN useradd -m -u 1000 user
+
+COPY requirements-space.txt ./
+RUN pip install --no-cache-dir -r requirements-space.txt
+
+COPY api/ ./api/
+COPY db/ ./db/
+COPY etl/__init__.py etl/chat_engine.py ./etl/
+COPY scripts/ ./scripts/
+COPY --from=frontend-builder /app/frontend/dist ./frontend/dist
+
+RUN mkdir -p /app/data && chown -R user:user /app
+
+ENV DB_PATH=/app/data/equity.duckdb \
+    HF_DATASET_REPO=egoh33/ibkr-daily-stock-data \
+    PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+USER user
+
+CMD ["sh", "-c", "python -m scripts.bootstrap_hf_data && exec uvicorn api.app:app --host 0.0.0.0 --port 7860"]

README.md

@@ -1,10 +1,373 @@
 ---
 title: IBKR Workbench
-emoji: 📊
-colorFrom: blue
+emoji: 📈
+colorFrom: yellow
 colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Equity Workbench
+
+A full-stack quantitative research platform — live market data from **Interactive Brokers**, historical **OHLCV + options bars from Polygon.io**, **SEC EDGAR financials**, and an **AI chat interface** to query it all in plain English.
+
+---
+
+## What it does
+
+| Layer | What's built |
+|---|---|
+| **Data ingestion** | ETL pipeline pulling from IBKR TWS, Polygon.io, SEC EDGAR, Finviz, and **CFTC COT** |
+| **Storage** | DuckDB (`equity.duckdb`) — 14 tables covering equities, options, forex, futures, indices, and COT |
+| **Vector search** | DuckDB VSS (`vectors.duckdb`) — HNSW index on 384-dim ticker embeddings |
+| **Dashboard** | Streamlit + Plotly — 8 pages including candlestick charts, options chain, and COT positioning |
+| **AI chat** | Text-to-SQL (**DeepSeek / Xiaomi MiMo**) + RAG over EDGAR financials |
+| **Deployment** | Docker Compose — separate dashboard and ETL containers |
+
+---
+
+## Architecture
+
+```
+Data Sources            ETL Pipeline              Storage
+────────────            ────────────              ───────
+IBKR TWS API  ────────► extract_stocks.py  ─────► equity.duckdb
+               ────────► extract_options.py ────►   stock_quotes
+Polygon.io    ────────► extract_polygon.py ─────►   option_quotes / option_chains
+               ────────►   bars, snapshots  ─────►   polygon_bars
+               ────────►   options bars     ─────►   polygon_option_bars
+               ────────►   option snapshots ─────►   polygon_option_snapshots
+               ────────►   reference        ─────►   polygon_tickers / snapshots
+SEC EDGAR     ────────► extract_edgar.py   ─────►   edgar_filings / edgar_facts
+CFTC COT      ────────► extract_cot.py     ─────►   cot_reports
+Finviz        ────────► update_tickers.py  ─────► config/tickers.yaml (11k+ tickers)
+                                                 ┌────────────────────────────────┐
+                                                 │  vectors.duckdb                │
+embed_tickers.py ──────────────────────────────► │  ticker_embeddings (HNSW)      │
+                                                 └────────────────────────────────┘
+
+Interfaces
+──────────
+equity.duckdb ──► Streamlit Dashboard (8 pages, Plotly charts)
+             ──► chat_engine.py  (Text-to-SQL via DeepSeek / Xiaomi MiMo)
+vectors.duckdb ► rag_engine.py  (LangChain RAG — EDGAR + descriptions)
+query.py    ──► Python API (latest_stock_quotes, stock_history, etl_run_log…)
+```
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|---|---|
+| Python 3.11+ | |
+| TWS or IB Gateway | For live IBKR data only — all other jobs work without it |
+| Polygon.io API key | Free tier: 5 req/min; Starter $29/mo for full speed |
+| DeepSeek / Xiaomi key | For the AI chat interface |
+| Docker (optional) | For containerised deployment |
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install dependencies
+pip install -r requirements.txt
+
+# 2. Configure
+cp .env.example .env
+# Fill in: POLYGON_API_KEY, DEEPSEEK_API_KEY (or set CHAT_PROVIDER=mimo for Xiaomi)
+
+# 3. Fetch 11,000+ US tickers from Finviz
+python -m config.update_tickers
+
+# 4. Download full history from Polygon (stocks + options)
+python main.py --job polygon-ref       # ticker metadata
+python main.py --job polygon-bars      # OHLCV + VWAP daily bars (max history)
+python main.py --job polygon-option-bars  # historical options bars
+
+# 5. Pull SEC EDGAR financials
+python main.py --job edgar-filings
+python main.py --job edgar-facts
+
+# 6. Build vector index for AI chat
+python main.py --job embed-tickers
+
+# 7. Launch the dashboard
+streamlit run dashboard/app.py
+```
+
+Or with Docker:
+```bash
+docker compose up --build
+# Dashboard → http://localhost:8501
+```
+
+---
+
+## Configuration (`.env`)
+
+### IBKR
+| Variable | Default | Description |
+|---|---|---|
+| `TWS_HOST` | `127.0.0.1` | TWS/Gateway host |
+| `TWS_PORT` | `7497` | 7497 = paper, 7496 = live, 4002 = Gateway |
+| `TWS_CLIENT_ID` | `1` | Unique client ID |
+| `OPTIONS_EXPIRY_CYCLES` | `2` | Nearest N expiries to quote |
+
+### Polygon.io
+| Variable | Default | Description |
+|---|---|---|
+| `POLYGON_API_KEY` | *(required)* | From polygon.io/dashboard/api-keys |
+| `POLYGON_BARS_TIMESPAN` | `day` | `second` / `minute` / `hour` / `day` |
+| `POLYGON_BARS_LOOKBACK` | `9500` | Days of history (~26 years max) |
+| `POLYGON_RATE_DELAY` | `13` | Seconds between calls (free=13, paid=0.1) |
+| `POLYGON_OPTION_BARS_TICKERS` | 12 liquid names | Comma-separated underlyings for options history |
+| `POLYGON_OPTION_BARS_MAX_CONTRACTS` | `250` | Max contracts per underlying |
+
+### AI Chat
+| Variable | Default | Description |
+|---|---|---|
+| `CHAT_PROVIDER` | `deepseek` | `deepseek` / `mimo` |
+| `CHAT_MODEL` | *(provider default)* | Override model name |
+| `DEEPSEEK_API_KEY` | | platform.deepseek.com |
+| `OLLAMA_BASE_URL` | `http://localhost:11434/v1` | Local Ollama endpoint for Xiaomi MiMo |
+| `OLLAMA_MODEL` | `xiaomi/MiMo-7B-RL` | Xiaomi model pulled via `ollama pull` |
+
+### Storage
+| Variable | Default | Description |
+|---|---|---|
+| `DB_PATH` | `./data/equity.duckdb` | Main DuckDB database |
+| `DUCKDB_PATH` | `./data/vectors.duckdb` | Vector store |
+| `TICKERS_YAML` | `config/tickers.yaml` | Ticker universe |
+
+---
+
+## ETL Jobs
+
+```bash
+# ── Polygon.io (no TWS needed) ────────────────────────────────────────────────
+python main.py --job polygon-ref          # ticker metadata (name, exchange, description)
+python main.py --job polygon-bars         # OHLCV + VWAP daily bars (full history)
+python main.py --job polygon-quotes       # delayed stock snapshots (bid/ask/last)
+python main.py --job polygon-options      # options chain snapshots + Greeks
+python main.py --job polygon-option-bars  # historical OHLCV bars per options contract
+python main.py --job polygon              # all polygon jobs
+
+# ── SEC EDGAR (no API key needed) ─────────────────────────────────────────────
+python main.py --job edgar-filings        # 10-K / 10-Q / 8-K filing history
+python main.py --job edgar-facts          # XBRL financials (revenue, EPS, assets…)
+
+# ── CFTC COT (no API key needed) ──────────────────────────────────────────────
+python main.py --job cot                  # Commitments of Traders (Legacy Futures)
+
+# ── AI / Vector search ────────────────────────────────────────────────────────
+python main.py --job embed-tickers        # embed ticker descriptions → HNSW index
+
+# ── IBKR live data (requires TWS running) ────────────────────────────────────
+python main.py --job stocks               # live stock quotes
+python main.py --job options              # live option quotes
+python main.py --job chain                # refresh option chain metadata
+python main.py --schedule                 # continuous mode
+
+# ── Ticker universe ───────────────────────────────────────────────────────────
+python -m config.update_tickers           # fetch all ~11,000 US stocks from Finviz
+python -m config.update_tickers --sectors Technology Healthcare
+python -m config.update_tickers --dry-run
+```
+
+---
+
+## Dashboard
+
+```bash
+streamlit run dashboard/app.py
+```
+
+| Page | Description |
+|---|---|
+| 💬 **Chat** | Natural language queries — SQL mode (Text-to-SQL) or RAG mode (knowledge base) |
+| 📊 **Stock Quotes** | Live IBKR prices, bid-ask spreads, volume |
+| 📉 **Price History** | Candlestick / OHLC / line chart with bid-ask band and volume |
+| 📦 **Polygon OHLCV** | Full-history daily bars with VWAP overlay and period return stats |
+| 🔗 **Options Chain** | IV smile, Greeks heatmap, OI/volume charts, full chain table |
+| 💸 **Cost Calculator** | Round-trip slippage model — spread + IBKR commission + market impact |
+| 🩺 **ETL Health** | Job run log, row counts per table, data freshness per ticker (including COT) |
+| ℹ️ **About** | Platform overview, data source status, quick reference |
+
+---
+
+## AI Chat
+
+Two modes available on the Chat page:
+
+**SQL mode** — converts your question to DuckDB SQL, executes it, and summarises the result:
+> *"Show AAPL closing prices for the last 30 days"*
+> *"Which 10 tickers had the highest average volume last month?"*
+> *"What was NVDA's revenue for the last 4 quarters?"*
+
+**RAG mode** — searches the vector index and EDGAR facts, then answers from context:
+> *"What does Nvidia actually do as a business?"*
+> *"Compare Apple and Microsoft's balance sheets"*
+> *"Which companies in the semiconductor sector have the most cash?"*
+
+Switch providers with one line in `.env`:
+```
+CHAT_PROVIDER=deepseek   # or: mimo
+```
+
+---
+
+## Asset Coverage
+
+| Asset class | Tickers | Source |
+|---|---|---|
+| US equities | ~11,200 (NYSE + NASDAQ + AMEX) | Finviz |
+| Forex majors + minors | 17 pairs (EUR/USD, GBP/USD…) | IBKR IDEALPRO |
+| Equity index futures | ES, NQ, RTY, YM + micro | CME |
+| Energy futures | CL, NG, RB, HO, BZ | NYMEX |
+| Metals futures | GC, SI, HG, PL, PA | COMEX |
+| Rate futures | ZB, ZN, ZF, ZT | CBOT |
+| Agricultural futures | ZC, ZS, ZW + 5 more | CBOT |
+| FX futures | 6E, 6B, 6J, 6C, 6A, 6S, 6N | CME |
+| Crypto futures | BTC, ETH, MBT, MET | CME |
+| Cash indices | SPX, VIX, NDX, RUT, DJX + global | CBOE |
+| **COT Positioning** | All major futures above (Legacy) | CFTC |
+
+---
+
+## Database Schema
+
+All data in `data/equity.duckdb` (14 tables):
+
+| Table | Rows (approx) | Description |
+|---|---|---|
+| `stock_quotes` | live | IBKR snapshots — bid/ask/last/OHLCV/VWAP |
+| `option_quotes` | live | IBKR option quotes — bid/ask/Greeks/IV/OI |
+| `option_chains` | live | Chain metadata (expiry × strike × right) |
+| `polygon_bars` | ~5,800/ticker | Daily OHLCV + VWAP, full history |
+| `polygon_option_bars` | varies | Historical OHLCV bars per contract |
+| `polygon_option_snapshots` | point-in-time | Options chain snapshots with Greeks |
+| `polygon_snapshots` | point-in-time | Stock delayed snapshots |
+| `polygon_tickers` | ~11k | Reference — name, exchange, description |
+| `edgar_filings` | varies | 10-K / 10-Q / 8-K filing history |
+| `edgar_facts` | varies | XBRL facts — revenue, EPS, assets, equity |
+| `cot_reports` | weekly | CFTC Commitments of Traders (Legacy Futures Only) |
+| `ticker_embeddings` | ~11k | 384-dim sentence embeddings (HNSW) |
+| `edgar_embeddings` | optional | EDGAR filing text embeddings |
+| `etl_runs` | grows | Audit log of every ETL job |
+
+Vector store in `data/vectors.duckdb`.
+
+---
+
+## Docker
+
+```bash
+# Build and start both services
+docker compose up --build
+
+# Dashboard only (read-only)
+docker compose up dashboard
+
+# ETL only (scheduled)
+docker compose up etl
+```
+
+- **dashboard** → `http://localhost:8501`
+- **etl** → runs `polygon-bars` on `POLL_INTERVAL_SECONDS` schedule
+
+Both containers mount `./data/` as a shared volume.
+
+---
+
+## Python API
+
+```python
+import duckdb
+conn = duckdb.connect("data/equity.duckdb", read_only=True)
+
+# Full price history for one ticker
+conn.execute("""
+    SELECT ts, open, high, low, close, volume, vwap
+    FROM polygon_bars WHERE ticker = 'AAPL' AND timespan = 'day'
+    ORDER BY ts
+""").df()
+
+# Historical options bars
+conn.execute("""
+    SELECT option_ticker, ts, open, high, low, close, volume, vwap
+    FROM polygon_option_bars
+    WHERE underlying = 'SPY' AND right = 'call' AND expiry >= '2024-01-01'
+    ORDER BY option_ticker, ts
+""").df()
+
+# Latest EDGAR revenue
+conn.execute("""
+    SELECT ticker, period_end, value AS revenue
+    FROM edgar_facts
+    WHERE concept = 'Revenues' AND form_type = '10-K'
+    ORDER BY ticker, period_end DESC
+""").df()
+```
+
+Query helpers:
+```python
+from query import latest_stock_quotes, stock_history, latest_option_quotes, etl_run_log
+from etl.embed_tickers import search_similar_tickers
+
+search_similar_tickers("semiconductor AI chip manufacturer", top_k=10)
+```
+
+---
+
+## Project Structure
+
+```
+equity_workbench/
+├── main.py                       # Entry point — all ETL jobs + scheduler
+├── query.py                      # Query helpers + CLI summary
+├── rag_engine.py                 # LangChain RAG pipeline
+├── requirements.txt
+├── Dockerfile.dashboard          # Streamlit container
+├── Dockerfile.etl                # ETL container
+├── docker-compose.yml
+│
+├── config/
+│   ├── tickers.yaml              # 11k+ tickers across all asset classes
+│   ├── tickers.py                # Loader — get_all_tickers()
+│   └── update_tickers.py         # Finviz scraper with checkpoint/resume
+│
+├── db/
+│   ├── database.py               # DuckDB schema + connection (equity.duckdb)
+│   └── vector_store.py           # VSS setup reference (now in database.py)
+│
+├── etl/
+│   ├── ibkr_client.py            # TWS API wrapper — EWrapper + EClient
+│   ├── extract_stocks.py         # IBKR stock snapshot ETL
+│   ├── extract_options.py        # IBKR option chain + quote ETL
+│   ├── polygon_client.py         # Polygon REST client factory
+│   ├── extract_polygon.py        # Polygon bars / snapshots / options / reference
+│   ├── extract_edgar.py          # SEC EDGAR filings + XBRL facts
+│   ├── embed_tickers.py          # Sentence-transformer embeddings → vector store
+│   ├── chat_engine.py            # Text-to-SQL with read-only SQL validation
+│   └── slippage.py               # Transaction cost model
+│
+├── dashboard/
+│   └── app.py                    # Streamlit + Plotly (8 pages)
+│
+├── data/                         # Auto-created — DuckDB files live here
+└── logs/                         # Daily rotating ETL logs
+```
+
+---
+
+## Tips
+
+- **Paid Polygon plan** — set `POLYGON_RATE_DELAY=0.1` to cut full-history download from days to ~40 minutes
+- **First IBKR run** — always pass `--refresh-chain` to populate option chain metadata first
+- **Options bars scale** — each contract = 1 API call; use `POLYGON_OPTION_BARS_TICKERS` to limit scope
+- **DuckDB concurrency** — dashboard connects `read_only=True`; only the ETL process writes
+- **EDGAR rate limit** — SEC allows 10 req/s; the ETL sleeps 0.12s automatically
+- **MiMo locally** — `ollama pull xiaomi/MiMo-7B-RL` then set `CHAT_PROVIDER=mimo` for free local AI

api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API package for Equity Workbench."""

api/app.py

@@ -0,0 +1,682 @@
+"""FastAPI visualization API for the React dashboard."""
+from __future__ import annotations
+
+import math
+import os
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+import duckdb
+import polars as pl
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+
+from etl.chat_engine import chat
+
+
+DB_PATH = os.getenv("DB_PATH", "./data/equity.duckdb")
+TS_EXACT_DUPLICATE_LIMIT = int(os.getenv("TS_EXACT_DUPLICATE_LIMIT", "1000000"))
+
+app = FastAPI(title="Equity Workbench API", version="0.1.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=os.getenv("API_CORS_ORIGINS", "http://localhost:5173,http://127.0.0.1:5173").split(","),
+    allow_methods=["GET", "POST"],
+    allow_headers=["*"],
+)
+
+
+def _connect() -> duckdb.DuckDBPyConnection:
+    return duckdb.connect(DB_PATH, read_only=True)
+
+
+def _frame(sql: str, params: tuple[Any, ...] = ()) -> pl.DataFrame:
+    with _connect() as conn:
+        rows = conn.execute(sql, params).fetchall()
+        columns = [col[0] for col in conn.description or []]
+    return pl.DataFrame(rows, schema=columns, orient="row") if columns else pl.DataFrame()
+
+
+def _scalar(sql: str, params: tuple[Any, ...] = (), default: Any = None) -> Any:
+    try:
+        with _connect() as conn:
+            row = conn.execute(sql, params).fetchone()
+        return row[0] if row else default
+    except duckdb.Error:
+        return default
+
+
+def _table_exists(name: str) -> bool:
+    return bool(
+        _scalar(
+            """
+            SELECT COUNT(*)
+            FROM information_schema.tables
+            WHERE table_schema = 'main' AND table_name = ?
+            """,
+            (name,),
+            0,
+        )
+    )
+
+
+def _column_exists(table: str, column: str) -> bool:
+    return bool(
+        _scalar(
+            """
+            SELECT COUNT(*)
+            FROM information_schema.columns
+            WHERE table_schema = 'main' AND table_name = ? AND column_name = ?
+            """,
+            (table, column),
+            0,
+        )
+    )
+
+
+def _table_columns(table: str) -> set[str]:
+    if not _table_exists(table):
+        return set()
+    df = _frame(
+        """
+        SELECT column_name
+        FROM information_schema.columns
+        WHERE table_schema = 'main' AND table_name = ?
+        """,
+        (table,),
+    )
+    return set(df.get_column("column_name").to_list()) if not df.is_empty() else set()
+
+
+def _json_value(value: Any) -> Any:
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, float) and (math.isnan(value) or math.isinf(value)):
+        return None
+    return value
+
+
+def _records(df: pl.DataFrame) -> list[dict[str, Any]]:
+    return [{key: _json_value(value) for key, value in row.items()} for row in df.to_dicts()]
+
+
+def _period_limit(period: str) -> int:
+    return {
+        "1m": 23,
+        "3m": 66,
+        "6m": 132,
+        "1y": 252,
+        "2y": 504,
+        "5y": 1260,
+    }.get(period, 252)
+
+
+TIME_SERIES_TABLES = (
+    {"name": "polygon_bars", "stage": "bronze", "symbol": "ticker", "time": "ts"},
+    {"name": "polygon_option_bars", "stage": "bronze", "symbol": "underlying", "time": "ts"},
+    {"name": "silver_stock_features", "stage": "silver", "symbol": "ticker", "time": "trade_date"},
+    {"name": "silver_option_greeks", "stage": "silver", "symbol": "underlying", "time": "trade_date"},
+    {"name": "silver_option_positioning", "stage": "silver", "symbol": "underlying", "time": "trade_date"},
+    {"name": "silver_cot_features", "stage": "silver", "symbol": "ticker", "time": "report_date"},
+    {"name": "gold_portfolio", "stage": "gold", "symbol": None, "time": "trade_date"},
+    {"name": "gold_trades", "stage": "gold", "symbol": "ticker", "time": "trade_date"},
+)
+
+
+def _series_profile(
+    spec: dict[str, Any],
+    include_coverage: bool = False,
+    conn: duckdb.DuckDBPyConnection | None = None,
+) -> dict[str, Any]:
+    if conn is None:
+        with _connect() as opened:
+            return _series_profile(spec, include_coverage=include_coverage, conn=opened)
+
+    def scalar(sql: str, params: tuple[Any, ...] = (), default: Any = None) -> Any:
+        row = conn.execute(sql, params).fetchone()
+        return row[0] if row else default
+
+    table = spec["name"]
+    columns = {
+        row[0]
+        for row in conn.execute(
+            """
+            SELECT column_name FROM information_schema.columns
+            WHERE table_schema = 'main' AND table_name = ?
+            """,
+            (table,),
+        ).fetchall()
+    }
+    time_col = spec["time"] if spec["time"] in columns else None
+    symbol_col = spec["symbol"] if spec.get("symbol") in columns else None
+    if not columns:
+        return {**spec, "available": False, "status": "missing", "rows": 0, "coverage": []}
+
+    rows = int(scalar(f"SELECT COUNT(*) FROM {table}", default=0) or 0)
+    detailed = rows <= TS_EXACT_DUPLICATE_LIMIT
+    profile: dict[str, Any] = {
+        **spec,
+        "available": True,
+        "status": "empty" if rows == 0 else "ready",
+        "rows": rows,
+        "profile_scope": "exact" if detailed else "inventory_only",
+        "symbols": int(scalar(f"SELECT COUNT(DISTINCT {symbol_col}) FROM {table}", default=0) or 0)
+        if symbol_col and detailed
+        else None,
+        "first_timestamp": _json_value(scalar(f"SELECT MIN({time_col}) FROM {table}")) if time_col and detailed else None,
+        "last_timestamp": _json_value(scalar(f"SELECT MAX({time_col}) FROM {table}")) if time_col and detailed else None,
+        "null_timestamps": int(scalar(f"SELECT COUNT(*) FROM {table} WHERE {time_col} IS NULL", default=0) or 0)
+        if time_col and detailed
+        else None,
+        "duplicate_points": None,
+        "duplicate_check": "not_applicable",
+        "coverage_check": "not_applicable",
+        "coverage": [],
+    }
+    key_columns = [column for column in (symbol_col, time_col) if column]
+    if time_col and detailed:
+        keys = ", ".join(key_columns)
+        profile["duplicate_points"] = int(
+            scalar(
+                f"SELECT COALESCE(SUM(n - 1), 0) FROM (SELECT COUNT(*) AS n FROM {table} GROUP BY {keys} HAVING COUNT(*) > 1)",
+                default=0,
+            )
+            or 0
+        )
+        profile["duplicate_check"] = "exact"
+    elif time_col:
+        profile["duplicate_check"] = "skipped_large_table"
+    if include_coverage and time_col and rows and detailed:
+        coverage_rows = conn.execute(
+            f"""
+            SELECT CAST(DATE_TRUNC('month', TRY_CAST({time_col} AS TIMESTAMP)) AS DATE) AS period,
+                   COUNT(*) AS rows
+            FROM {table}
+            WHERE TRY_CAST({time_col} AS TIMESTAMP) IS NOT NULL
+            GROUP BY period
+            ORDER BY period DESC
+            LIMIT 120
+            """
+        ).fetchall()
+        coverage = pl.DataFrame(coverage_rows, schema=["period", "rows"], orient="row") if coverage_rows else pl.DataFrame()
+        profile["coverage"] = _records(coverage.sort("period")) if not coverage.is_empty() else []
+        profile["coverage_check"] = "exact"
+    elif include_coverage and time_col and rows:
+        profile["coverage_check"] = "skipped_large_table"
+    return profile
+
+
+def _series_profiles(include_coverage: bool = False) -> list[dict[str, Any]]:
+    with _connect() as conn:
+        return [_series_profile(spec, include_coverage=include_coverage, conn=conn) for spec in TIME_SERIES_TABLES]
+
+
+@app.get("/api/health")
+def health() -> dict[str, Any]:
+    db_exists = os.path.exists(DB_PATH)
+    return {
+        "ok": db_exists,
+        "db_path": DB_PATH,
+        "tables": _scalar("SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'main'", default=0)
+        if db_exists
+        else 0,
+    }
+
+
+@app.get("/api/visualizations/overview")
+def overview() -> dict[str, Any]:
+    tables = [
+        "polygon_bars",
+        "silver_stock_features",
+        "silver_option_greeks",
+        "silver_option_positioning",
+        "cot_reports",
+        "edgar_facts",
+        "ticker_embeddings",
+    ]
+    counts = [
+        {"table": table, "rows": int(_scalar(f"SELECT COUNT(*) FROM {table}", default=0) or 0)}
+        for table in tables
+        if _table_exists(table)
+    ]
+    ret_z = "zscore_ret_20" if _column_exists("silver_stock_features", "zscore_ret_20") else "NULL::DOUBLE"
+    movers = _frame(
+        f"""
+        SELECT ticker, trade_date, close, daily_return, {ret_z} AS zscore_ret_20, zscore_20
+        FROM silver_stock_features
+        QUALIFY ROW_NUMBER() OVER (PARTITION BY ticker ORDER BY trade_date DESC) = 1
+        ORDER BY ABS(COALESCE({ret_z}, zscore_20, 0)) DESC
+        LIMIT 12
+        """
+    )
+    return {
+        "counts": counts,
+        "movers": _records(movers),
+        "freshness": {
+            "stocks": _json_value(_scalar("SELECT MAX(trade_date) FROM silver_stock_features")),
+            "options": _json_value(_scalar("SELECT MAX(trade_date) FROM silver_option_positioning")),
+            "polygon": _json_value(_scalar("SELECT MAX(ts) FROM polygon_bars WHERE timespan = 'day'")),
+        },
+    }
+
+
+@app.get("/api/visualizations/tickers")
+def tickers() -> dict[str, Any]:
+    df = _frame(
+        """
+        SELECT ticker, COUNT(*) AS rows, MIN(trade_date) AS first_date, MAX(trade_date) AS last_date
+        FROM silver_stock_features
+        GROUP BY ticker
+        ORDER BY ticker
+        """
+    )
+    return {"tickers": _records(df)}
+
+
+@app.get("/api/visualizations/stock-history")
+def stock_history(
+    ticker: str = Query("NVDA", min_length=1, max_length=12),
+    period: str = Query("1y", pattern="^(1m|3m|6m|1y|2y|5y|all)$"),
+) -> dict[str, Any]:
+    symbol = ticker.upper()
+    limit = 5000 if period == "all" else _period_limit(period)
+    df = _frame(
+        f"""
+        WITH bars AS (
+            SELECT ticker, ts, open, high, low, close, volume, vwap
+            FROM polygon_bars
+            WHERE ticker = ? AND timespan = 'day'
+            ORDER BY ts DESC
+            LIMIT ?
+        )
+        SELECT
+            b.ticker,
+            TRY_CAST(b.ts AS TIMESTAMPTZ)::DATE AS trade_date,
+            b.open,
+            b.high,
+            b.low,
+            b.close,
+            b.volume,
+            b.vwap,
+            s.daily_return,
+            s.zscore_20,
+            {"s.zscore_ret_20" if _column_exists("silver_stock_features", "zscore_ret_20") else "NULL::DOUBLE"} AS zscore_ret_20,
+            s.ma_20,
+            s.ma_50,
+            s.vwap_20
+        FROM bars b
+        LEFT JOIN silver_stock_features s
+          ON s.ticker = b.ticker
+         AND s.trade_date = TRY_CAST(b.ts AS TIMESTAMPTZ)::DATE
+        ORDER BY trade_date
+        """,
+        (symbol, limit),
+    )
+    if df.is_empty():
+        raise HTTPException(status_code=404, detail=f"No daily bars found for {symbol}.")
+
+    latest = df.tail(1).to_dicts()[0]
+    first_close = df.select(pl.col("close").drop_nulls().first()).item()
+    last_close = latest.get("close")
+    period_return = ((last_close / first_close) - 1) if first_close and last_close else None
+    return {
+        "ticker": symbol,
+        "period": period,
+        "latest": {key: _json_value(value) for key, value in latest.items()},
+        "metrics": {
+            "period_return": period_return,
+            "high": df.select(pl.col("high").max()).item(),
+            "low": df.select(pl.col("low").min()).item(),
+            "avg_volume": df.select(pl.col("volume").mean()).item(),
+        },
+        "series": _records(df),
+    }
+
+
+@app.get("/api/visualizations/zscore-alerts")
+def zscore_alerts(limit: int = Query(25, ge=1, le=100)) -> dict[str, Any]:
+    pct_change = (
+        "pct_change"
+        if _column_exists("silver_stock_features", "pct_change")
+        else "daily_return * 100"
+        if _column_exists("silver_stock_features", "daily_return")
+        else "NULL::DOUBLE"
+    )
+    zret20 = "zscore_ret_20" if _column_exists("silver_stock_features", "zscore_ret_20") else "NULL::DOUBLE"
+    zret50 = "zscore_ret_50" if _column_exists("silver_stock_features", "zscore_ret_50") else "NULL::DOUBLE"
+    zret100 = "zscore_ret_100" if _column_exists("silver_stock_features", "zscore_ret_100") else "NULL::DOUBLE"
+    sql = f"""
+        WITH latest AS (
+            SELECT *,
+                   ROW_NUMBER() OVER (PARTITION BY ticker ORDER BY trade_date DESC) AS rn
+            FROM silver_stock_features
+        )
+        SELECT ticker, trade_date, close, {pct_change} AS pct_change,
+               zscore_20, zscore_50, zscore_100,
+               {zret20} AS zscore_ret_20, {zret50} AS zscore_ret_50, {zret100} AS zscore_ret_100,
+               GREATEST(
+                   ABS(COALESCE(zscore_20, 0)),
+                   ABS(COALESCE(zscore_50, 0)),
+                   ABS(COALESCE(zscore_100, 0)),
+                   ABS(COALESCE({zret20}, 0)),
+                   ABS(COALESCE({zret50}, 0)),
+                   ABS(COALESCE({zret100}, 0))
+               ) AS max_abs_zscore,
+               false AS any_breach
+        FROM latest
+        WHERE rn = 1
+        ORDER BY max_abs_zscore DESC
+        LIMIT ?
+        """
+    df = _frame(sql, (limit,))
+    return {"alerts": _records(df)}
+
+
+@app.get("/api/visualizations/options-positioning")
+def options_positioning(
+    underlying: str = Query("NVDA", min_length=1, max_length=12),
+    period: str = Query("1y", pattern="^(1m|3m|6m|1y|2y|all)$"),
+) -> dict[str, Any]:
+    symbol = underlying.upper()
+    limit = 5000 if period == "all" else _period_limit(period)
+    df = _frame(
+        """
+        SELECT underlying, trade_date, total_volume, call_volume, put_volume, put_call_ratio,
+               atm_iv, call_iv_25d, put_iv_25d, iv_skew_25d, n_contracts
+        FROM silver_option_positioning
+        WHERE underlying = ?
+        ORDER BY trade_date DESC
+        LIMIT ?
+        """,
+        (symbol, limit),
+    )
+    if df.is_empty():
+        return {"underlying": symbol, "period": period, "series": []}
+    df = df.sort("trade_date")
+    return {"underlying": symbol, "period": period, "series": _records(df)}
+
+
+@app.get("/api/visualizations/backtests")
+def backtests() -> dict[str, Any]:
+    if not _table_exists("gold_backtest_runs"):
+        return {"runs": [], "portfolio": [], "metrics": []}
+    runs = _frame(
+        """
+        SELECT run_id, start_date, end_date, created_at, fold_id
+        FROM gold_backtest_runs
+        ORDER BY created_at DESC
+        LIMIT 20
+        """
+    )
+    latest_run = runs["run_id"][0] if not runs.is_empty() else None
+    portfolio = (
+        _frame(
+            """
+            SELECT trade_date, nav, cash, drawdown_pct, n_positions
+            FROM gold_portfolio
+            WHERE run_id = ?
+            ORDER BY trade_date
+            """,
+            (latest_run,),
+        )
+        if latest_run and _table_exists("gold_portfolio")
+        else pl.DataFrame()
+    )
+    metrics = (
+        _frame("SELECT * FROM gold_metrics WHERE run_id = ?", (latest_run,))
+        if latest_run and _table_exists("gold_metrics")
+        else pl.DataFrame()
+    )
+    return {"runs": _records(runs), "portfolio": _records(portfolio), "metrics": _records(metrics)}
+
+
+@app.get("/api/research/methodology")
+def research_methodology() -> dict[str, Any]:
+    return {
+        "title": "Point-in-time market research methodology",
+        "principles": [
+            {
+                "id": "clock",
+                "title": "Event time before ingestion time",
+                "body": "Bars, features, signals, and fills are aligned on the market event timestamp. Ingestion and computation timestamps are retained for freshness and replay audits, but never substitute for event time in a backtest.",
+                "controls": ["Normalize timestamps to UTC", "Declare exchange session and calendar", "Reject future-dated observations"],
+            },
+            {
+                "id": "alignment",
+                "title": "Point-in-time alignment",
+                "body": "A decision at time t may only use values published and observable at or before t. Lower-frequency releases are joined backward from their release timestamp, never from the period they describe.",
+                "controls": ["Backward as-of joins", "Publication-lag fields", "No forward fill across unknown releases"],
+            },
+            {
+                "id": "features",
+                "title": "Windows, resampling, and warmup",
+                "body": "OHLCV resampling uses explicit session boundaries. Rolling features require a complete minimum window and remain null during warmup; signals are shifted to the next executable bar.",
+                "controls": ["Closed-bar inputs", "Minimum observations", "Signal-to-fill lag"],
+            },
+            {
+                "id": "adjustments",
+                "title": "Corporate actions and universe history",
+                "body": "Price-return studies must declare split and dividend treatment. Delisted names and historical membership are retained so the tested universe is the universe known at that date.",
+                "controls": ["Adjustment policy per run", "Point-in-time membership", "Delisting outcome handling"],
+            },
+            {
+                "id": "validation",
+                "title": "Walk-forward validation",
+                "body": "Model selection occurs only inside each training window. Validation and out-of-sample windows are chronological, non-overlapping, and separated by an embargo at least as long as the maximum label horizon.",
+                "controls": ["Expanding or rolling splits", "Embargo recorded per fold", "Untouched final holdout"],
+            },
+            {
+                "id": "costs",
+                "title": "Execution and slippage",
+                "body": "Reported performance is net of spread, commission, and configured market impact. Costs are calculated per fill from information available at execution and are preserved beside gross and net P&L.",
+                "controls": ["Half-spread per leg", "IBKR commission schedule", "Square-root participation impact", "Cost toggles stored per run"],
+            },
+        ],
+        "slippage_model": {
+            "spread": "round-trip half-spread x quantity x multiplier x 2",
+            "commission": "asset-specific IBKR schedule with minimums and caps",
+            "market_impact": "volatility x sqrt(quantity / ADV) x notional x 2",
+            "cost_bps": "total execution cost / entry notional x 10,000",
+            "net_pnl": "gross_pnl - slippage_cost - commission_cost",
+        },
+        "required_run_metadata": [
+            "data snapshot and event-time range",
+            "universe and corporate-action policy",
+            "feature windows and signal lag",
+            "walk-forward folds and embargo",
+            "slippage toggles and parameters",
+            "code version and creation timestamp",
+        ],
+    }
+
+
+@app.get("/api/research/analytics/summary")
+def research_analytics_summary() -> dict[str, Any]:
+    profiles = _series_profiles(include_coverage=True)
+    return {
+        "tables": profiles,
+        "totals": {
+            "rows": sum(item["rows"] for item in profiles),
+            "available_tables": sum(1 for item in profiles if item["available"]),
+            "tables_with_duplicates": sum(1 for item in profiles if (item.get("duplicate_points") or 0) > 0),
+            "tables_with_null_time": sum(1 for item in profiles if (item.get("null_timestamps") or 0) > 0),
+        },
+    }
+
+
+def _quality_checks() -> list[dict[str, Any]]:
+    checks: list[dict[str, Any]] = []
+    for profile in _series_profiles():
+        spec = profile
+        if not profile["available"]:
+            checks.append({"table": spec["name"], "check": "table_available", "status": "not_applicable", "value": None})
+            continue
+        for field, check in (("null_timestamps", "event_time_not_null"), ("duplicate_points", "unique_series_key")):
+            value = profile.get(field)
+            checks.append(
+                {
+                    "table": spec["name"],
+                    "check": check,
+                    "status": "pass" if value == 0 else "fail" if value is not None else "not_applicable",
+                    "value": value,
+                }
+            )
+    return checks
+
+
+@app.get("/api/research/audit")
+def research_audit(limit: int = Query(100, ge=1, le=500)) -> dict[str, Any]:
+    runs = (
+        _frame(
+            """
+            SELECT id, run_type, status, rows_written, started_at, finished_at, message
+            FROM etl_runs
+            ORDER BY TRY_CAST(started_at AS TIMESTAMP) DESC NULLS LAST, id DESC
+            LIMIT ?
+            """,
+            (limit,),
+        )
+        if _table_exists("etl_runs")
+        else pl.DataFrame()
+    )
+    return {"runs": _records(runs), "checks": _quality_checks()}
+
+
+@app.get("/api/research/audit/summary")
+def research_audit_summary() -> dict[str, Any]:
+    checks = _quality_checks()
+    status_rows = (
+        _frame("SELECT status, COUNT(*) AS runs FROM etl_runs GROUP BY status ORDER BY runs DESC")
+        if _table_exists("etl_runs")
+        else pl.DataFrame()
+    )
+    return {
+        "etl_status": _records(status_rows),
+        "checks": {
+            "passed": sum(1 for item in checks if item["status"] == "pass"),
+            "failed": sum(1 for item in checks if item["status"] == "fail"),
+            "not_applicable": sum(1 for item in checks if item["status"] == "not_applicable"),
+        },
+    }
+
+
+@app.get("/api/research/system")
+def research_system() -> dict[str, Any]:
+    profiles = _series_profiles()
+    stages = []
+    for stage in ("bronze", "silver", "gold"):
+        members = [item for item in profiles if item["stage"] == stage]
+        available = sum(1 for item in members if item["available"] and item["rows"] > 0)
+        stages.append(
+            {
+                "stage": stage,
+                "status": "ready" if available == len(members) else "partial" if available else "missing",
+                "available": available,
+                "expected": len(members),
+                "latest_timestamp": max(
+                    (str(item["last_timestamp"]) for item in members if item.get("last_timestamp")),
+                    default=None,
+                ),
+            }
+        )
+    return {"database": health(), "stages": stages, "tables": profiles}
+
+
+def _slippage_available() -> bool:
+    required = {"run_id", "ticker", "gross_pnl", "slippage_cost", "commission_cost", "net_pnl"}
+    return required.issubset(_table_columns("gold_trades"))
+
+
+@app.get("/api/research/slippage/summary")
+def slippage_summary() -> dict[str, Any]:
+    if not _slippage_available():
+        return {"available": False, "reason": "gold_trades with cost fields is not available", "summary": None}
+    df = _frame(
+        """
+        SELECT COUNT(*) AS trades,
+               COUNT(DISTINCT run_id) AS runs,
+               SUM(COALESCE(gross_pnl, 0)) AS gross_pnl,
+               SUM(COALESCE(slippage_cost, 0)) AS slippage_cost,
+               SUM(COALESCE(commission_cost, 0)) AS commission_cost,
+               SUM(COALESCE(slippage_cost, 0) + COALESCE(commission_cost, 0)) AS total_cost,
+               SUM(COALESCE(net_pnl, 0)) AS net_pnl,
+               CASE WHEN ABS(SUM(COALESCE(gross_pnl, 0))) > 0
+                    THEN SUM(COALESCE(slippage_cost, 0) + COALESCE(commission_cost, 0))
+                         / ABS(SUM(COALESCE(gross_pnl, 0))) END AS cost_drag
+        FROM gold_trades
+        """
+    )
+    return {"available": True, "summary": _records(df)[0] if not df.is_empty() else None}
+
+
+@app.get("/api/research/slippage/by-ticker")
+def slippage_by_ticker(run_id: str | None = None) -> dict[str, Any]:
+    if not _slippage_available():
+        return {"available": False, "reason": "gold_trades with cost fields is not available", "tickers": []}
+    where = "WHERE run_id = ?" if run_id else ""
+    params: tuple[Any, ...] = (run_id,) if run_id else ()
+    df = _frame(
+        f"""
+        SELECT ticker, COUNT(*) AS trades,
+               SUM(COALESCE(gross_pnl, 0)) AS gross_pnl,
+               SUM(COALESCE(slippage_cost, 0)) AS slippage_cost,
+               SUM(COALESCE(commission_cost, 0)) AS commission_cost,
+               SUM(COALESCE(slippage_cost, 0) + COALESCE(commission_cost, 0)) AS total_cost,
+               SUM(COALESCE(net_pnl, 0)) AS net_pnl
+        FROM gold_trades
+        {where}
+        GROUP BY ticker
+        ORDER BY total_cost DESC, ticker
+        """,
+        params,
+    )
+    return {"available": True, "tickers": _records(df)}
+
+
+@app.get("/api/backtests/{run_id}/costs")
+def backtest_costs(run_id: str) -> dict[str, Any]:
+    if not _slippage_available():
+        return {"available": False, "run_id": run_id, "reason": "gold_trades with cost fields is not available", "trades": []}
+    columns = _table_columns("gold_trades")
+    order_col = "trade_date" if "trade_date" in columns else "ticker"
+    selected = ["ticker", "gross_pnl", "slippage_cost", "commission_cost", "net_pnl"]
+    for optional in ("trade_date", "asset_type", "quantity", "price", "cost_bps"):
+        if optional in columns:
+            selected.append(optional)
+    df = _frame(
+        f"SELECT {', '.join(selected)} FROM gold_trades WHERE run_id = ? ORDER BY {order_col}",
+        (run_id,),
+    )
+    totals = slippage_by_ticker(run_id=run_id)
+    return {"available": True, "run_id": run_id, "by_ticker": totals["tickers"], "trades": _records(df)}
+
+
+@app.post("/api/chat")
+def chat_endpoint(payload: dict[str, Any]) -> dict[str, Any]:
+    message = str(payload.get("message", "")).strip()
+    if not message:
+        raise HTTPException(status_code=400, detail="message is required")
+    result = chat(message, history=payload.get("history") or [], max_rows=int(payload.get("max_rows", 100)))
+    data = result.get("data")
+    if hasattr(data, "to_dict"):
+        data = data.to_dict(orient="records")
+    return {
+        "type": result.get("type"),
+        "response": result.get("answer"),
+        "sql": result.get("sql"),
+        "data": data,
+    }
+
+
+# The Docker Space builds the Vite app into frontend/dist. Keep this route last
+# so every /api endpoint wins before the single-page-app fallback.
+FRONTEND_DIST = Path(__file__).resolve().parent.parent / "frontend" / "dist"
+if FRONTEND_DIST.is_dir():
+    @app.get("/{full_path:path}", include_in_schema=False)
+    def serve_frontend(full_path: str) -> FileResponse:
+        requested = (FRONTEND_DIST / full_path).resolve()
+        if requested.is_file() and FRONTEND_DIST.resolve() in requested.parents:
+            return FileResponse(requested)
+        return FileResponse(FRONTEND_DIST / "index.html")

api/services/__init__.py

@@ -0,0 +1 @@
+"""Service integrations used by the API and development workflows."""

api/services/agent_review.py

@@ -0,0 +1,70 @@
+"""Explicit MiMo implementation and DeepSeek review handoff.
+
+Prompts, source diffs, responses, and credentials are deliberately not logged.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+load_dotenv()
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    provider: str
+    model: str
+    content: str
+
+
+def _completion(*, provider: str, base_url: str, api_key: str, model: str, system: str, prompt: str) -> AgentResult:
+    if not api_key:
+        raise ValueError(f"{provider} API key is not configured")
+    if not base_url.startswith("https://") and not base_url.startswith("http://localhost"):
+        raise ValueError(f"{provider} base URL must use HTTPS or localhost")
+    client = OpenAI(api_key=api_key, base_url=base_url, timeout=120.0, max_retries=1)
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "system", "content": system}, {"role": "user", "content": prompt}],
+        temperature=0.1,
+        max_completion_tokens=8000,
+    )
+    content = (response.choices[0].message.content or "").strip()
+    if not content:
+        raise RuntimeError(f"{provider} returned an empty response")
+    return AgentResult(provider=provider, model=model, content=content)
+
+
+def run_mimo_implementation(prompt: str) -> AgentResult:
+    xiaomi_key = os.getenv("XIAOMI_OPENAI_API_KEY", "")
+    base_url = (
+        os.getenv("XIAOMI_OPENAI_BASE_URL", "https://token-plan-sgp.xiaomimimo.com/v1")
+        if xiaomi_key
+        else os.getenv("MIMO_BASE_URL", "http://localhost:11434/v1")
+    )
+    return _completion(
+        provider="mimo",
+        base_url=base_url.rstrip("/"),
+        api_key=xiaomi_key or os.getenv("MIMO_API_KEY", ""),
+        model=os.getenv("MIMO_MODEL", "mimo-v2.5-pro"),
+        system="You are a senior implementation engineer. Return a scoped patch and its focused tests.",
+        prompt=prompt,
+    )
+
+
+def run_deepseek_review(diff_or_files: str) -> AgentResult:
+    return _completion(
+        provider="deepseek",
+        base_url=os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com").rstrip("/"),
+        api_key=os.getenv("DEEPSEEK_OPENAI_API_KEY") or os.getenv("DEEPSEEK_API_KEY", ""),
+        model=os.getenv("DEEPSEEK_MODEL", "deepseek-v4-flash"),
+        system=(
+            "Review the supplied implementation for correctness, security, time-series leakage, "
+            "DuckDB compatibility, API contract stability, responsive UI behavior, and missing tests. "
+            "Lead with actionable findings and file references; say APPROVED only when no blocker remains."
+        ),
+        prompt=diff_or_files,
+    )

db/database.py

@@ -0,0 +1,745 @@
+"""
+db/database.py
+DuckDB schema + connection manager for Equity Workbench ETL.
+"""
+import duckdb
+import os
+from pathlib import Path
+from loguru import logger
+
+
+DB_PATH = os.getenv("DB_PATH", "./data/equity.duckdb")
+
+
+def get_connection() -> duckdb.DuckDBPyConnection:
+    Path(DB_PATH).parent.mkdir(parents=True, exist_ok=True)
+    conn = duckdb.connect(DB_PATH)
+    # ── Extension Setup ───────────────────────────────────────────
+    try:
+        conn.execute("INSTALL vss;")
+        conn.execute("LOAD vss;")
+        conn.execute("SET hnsw_enable_experimental_persistence = true;")
+    except Exception as e:
+        logger.warning(f"Failed to load VSS extension: {e}")
+    return conn
+
+
+def init_db():
+    """Create all tables if they don't exist."""
+    conn = get_connection()
+    try:
+        # ── Stocks ────────────────────────────────────────────────────────────────
+        conn.execute("""
+            CREATE SEQUENCE IF NOT EXISTS stock_quotes_id_seq;
+            CREATE TABLE IF NOT EXISTS stock_quotes (
+                id          INTEGER PRIMARY KEY DEFAULT nextval('stock_quotes_id_seq'),
+                ticker      TEXT    NOT NULL,
+                ts          TEXT    NOT NULL,          -- ISO-8601 UTC
+                bid         REAL,
+                ask         REAL,
+                last        REAL,
+                "close"     REAL,
+                volume      INTEGER,
+                "open"      REAL,
+                high        REAL,
+                low         REAL,
+                vwap        REAL,
+                created_at  TIMESTAMP DEFAULT now()
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_sq_ticker_ts
+                ON stock_quotes(ticker, ts)
+        """)
+
+        # ── Options ───────────────────────────────────────────────────────────────
+        conn.execute("""
+            CREATE SEQUENCE IF NOT EXISTS option_quotes_id_seq;
+            CREATE TABLE IF NOT EXISTS option_quotes (
+                id              INTEGER PRIMARY KEY DEFAULT nextval('option_quotes_id_seq'),
+                ticker          TEXT    NOT NULL,   -- underlying
+                expiry          TEXT    NOT NULL,   -- YYYYMMDD
+                strike          REAL    NOT NULL,
+                "right"         TEXT    NOT NULL,   -- 'C' or 'P'
+                ts              TEXT    NOT NULL,
+                bid             REAL,
+                ask             REAL,
+                last            REAL,
+                volume          INTEGER,
+                open_interest   INTEGER,
+                implied_vol     REAL,
+                delta           REAL,
+                gamma           REAL,
+                theta           REAL,
+                vega            REAL,
+                und_price       REAL,
+                pv_dividend     REAL,
+                created_at      TIMESTAMP DEFAULT now()
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_oq_ticker_expiry
+                ON option_quotes(ticker, expiry, strike, "right")
+        """)
+
+        # ── Option Chains (metadata) ───────────────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS option_chains (
+                ticker      TEXT    NOT NULL,
+                expiry      TEXT    NOT NULL,
+                strike      REAL    NOT NULL,
+                "right"     TEXT    NOT NULL,
+                exchange    TEXT,
+                fetched_at  TIMESTAMP DEFAULT now(),
+                UNIQUE(ticker, expiry, strike, "right")
+            )
+        """)
+
+        # ── ETL Run Log ────────────────────────────────────────────────────────
+        conn.execute("""
+            CREATE SEQUENCE IF NOT EXISTS etl_runs_id_seq;
+            CREATE TABLE IF NOT EXISTS etl_runs (
+                id          INTEGER PRIMARY KEY DEFAULT nextval('etl_runs_id_seq'),
+                run_type    TEXT    NOT NULL,   -- 'stocks' | 'options' | 'chain' | 'polygon_bars_bronze' | ...
+                status      TEXT    NOT NULL,   -- 'ok' | 'error'
+                message     TEXT,
+                rows_written INTEGER DEFAULT 0,
+                started_at  TEXT    NOT NULL,
+                finished_at TEXT
+            )
+        """)
+
+        # ── Polygon: OHLCV bars ───────────────────────────────────────────��───────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS polygon_bars (
+                ticker          TEXT    NOT NULL,
+                ts              TEXT    NOT NULL,   -- bar open time, ISO-8601 UTC
+                timespan        TEXT    NOT NULL,   -- 'day' | 'minute' | 'hour'
+                open            REAL,
+                high            REAL,
+                low             REAL,
+                close           REAL,
+                volume          REAL,
+                vwap            REAL,
+                transactions    INTEGER,
+                created_at      TIMESTAMP DEFAULT now(),
+                UNIQUE(ticker, ts, timespan)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_pb_ticker_ts
+                ON polygon_bars(ticker, ts, timespan)
+        """)
+
+        # ── Polygon: real-time / delayed snapshots ────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS polygon_snapshots (
+                ticker      TEXT    NOT NULL,
+                ts          TEXT    NOT NULL,
+                bid         REAL,
+                ask         REAL,
+                last        REAL,
+                prev_close  REAL,
+                day_volume  REAL,
+                created_at  TIMESTAMP DEFAULT now()
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_ps_ticker_ts
+                ON polygon_snapshots(ticker, ts)
+        """)
+
+        # ── Polygon: options chain snapshots ──────────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS polygon_option_snapshots (
+                underlying      TEXT    NOT NULL,
+                expiry          TEXT    NOT NULL,   -- YYYY-MM-DD
+                strike          REAL    NOT NULL,
+                "right"         TEXT    NOT NULL,   -- 'call' | 'put'
+                ts              TEXT    NOT NULL,
+                day_open        REAL,
+                day_close       REAL,
+                day_volume      INTEGER,
+                open_interest   INTEGER,
+                implied_vol     REAL,
+                delta           REAL,
+                gamma           REAL,
+                theta           REAL,
+                vega            REAL,
+                created_at      TIMESTAMP DEFAULT now()
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_pos_underlying
+                ON polygon_option_snapshots(underlying, expiry, strike, "right")
+        """)
+
+        # ── Polygon: ticker reference / metadata ──────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS polygon_tickers (
+                ticker           TEXT    NOT NULL UNIQUE,
+                name             TEXT,
+                market           TEXT,
+                primary_exchange TEXT,
+                type             TEXT,
+                active           INTEGER,
+                currency         TEXT,
+                description      TEXT,
+                updated_at       TEXT    NOT NULL
+            )
+        """)
+
+        # ── Polygon: historical options OHLCV bars ───────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS polygon_option_bars (
+                option_ticker   TEXT    NOT NULL,   -- e.g. O:AAPL240119C00150000
+                underlying      TEXT    NOT NULL,
+                expiry          TEXT,               -- YYYY-MM-DD
+                strike          REAL,
+                "right"         TEXT,               -- 'call' | 'put'
+                ts              TEXT    NOT NULL,   -- bar open time, ISO-8601 UTC
+                timespan        TEXT    NOT NULL,   -- 'day' | 'minute'
+                open            REAL,
+                high            REAL,
+                low             REAL,
+                close           REAL,
+                volume          REAL,
+                vwap            REAL,
+                transactions    INTEGER,
+                created_at      TIMESTAMP DEFAULT now(),
+                UNIQUE(option_ticker, ts, timespan)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_pob_underlying
+                ON polygon_option_bars(underlying, expiry, strike, "right")
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_pob_ticker_ts
+                ON polygon_option_bars(option_ticker, ts)
+        """)
+
+        # ── Polygon: individual trade ticks ──────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS polygon_trades (
+                ticker      TEXT    NOT NULL,
+                ts          TEXT    NOT NULL,   -- SIP timestamp, ISO-8601 microsecond UTC
+                price       REAL,
+                size        REAL,
+                conditions  TEXT,               -- comma-separated condition codes
+                exchange    INTEGER,
+                tape        TEXT,
+                created_at  TIMESTAMP DEFAULT now(),
+                UNIQUE(ticker, ts, exchange)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_ptrades_ticker_ts
+                ON polygon_trades(ticker, ts)
+        """)
+
+        # ── EDGAR: filing metadata ────────────────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS edgar_filings (
+                ticker           TEXT    NOT NULL,
+                cik              TEXT    NOT NULL,
+                form_type        TEXT    NOT NULL,
+                filed_date       TEXT,
+                accession_number TEXT    NOT NULL,
+                primary_doc      TEXT,
+                created_at       TIMESTAMP DEFAULT now(),
+                UNIQUE(accession_number)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_ef_ticker_form
+                ON edgar_filings(ticker, form_type, filed_date)
+        """)
+
+        # ── EDGAR: XBRL financial facts ───────────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS edgar_facts (
+                ticker           TEXT    NOT NULL,
+                cik              TEXT    NOT NULL,
+                taxonomy         TEXT    NOT NULL,
+                concept          TEXT    NOT NULL,
+                label            TEXT,
+                unit             TEXT,
+                value            REAL,
+                period_start     TEXT,
+                period_end       TEXT,
+                form_type        TEXT,
+                filed_date       TEXT,
+                accession_number TEXT,
+                created_at       TIMESTAMP DEFAULT now(),
+                UNIQUE(ticker, concept, unit, period_end, form_type)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_edgar_facts_ticker
+                ON edgar_facts(ticker, concept, period_end)
+        """)
+
+        # ── COT: Commitments of Traders (CFTC) ────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS cot_reports (
+                market_name     TEXT    NOT NULL,
+                ticker          TEXT,               -- Optional mapping to IBKR ticker
+                report_date     TEXT    NOT NULL,   -- ISO-8601
+                noncomm_long    INTEGER,
+                noncomm_short   INTEGER,
+                comm_long       INTEGER,
+                comm_short      INTEGER,
+                total_long      INTEGER,
+                total_short     INTEGER,
+                noncomm_spreads INTEGER,
+                open_interest   INTEGER,
+                created_at      TIMESTAMP DEFAULT now(),
+                UNIQUE(market_name, report_date)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_cot_market_date
+                ON cot_reports(market_name, report_date)
+        """)
+
+        # ── Vector Storage ────────────────────────────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS ticker_embeddings (
+                ticker      TEXT PRIMARY KEY,
+                industry    TEXT,
+                source      TEXT,
+                text        TEXT,
+                embedding   FLOAT[384],    -- all-MiniLM-L6-v2 dimension
+                updated_at  TIMESTAMP DEFAULT now()
+            )
+        """)
+        try:
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_ticker_emb
+                ON ticker_embeddings USING HNSW (embedding)
+                WITH (metric = 'cosine')
+            """)
+        except Exception as e:
+            logger.warning(f"Failed to create HNSW index on ticker_embeddings: {e}")
+
+        conn.execute("""
+            CREATE SEQUENCE IF NOT EXISTS edgar_embeddings_id_seq;
+            CREATE TABLE IF NOT EXISTS edgar_embeddings (
+                id          INTEGER PRIMARY KEY DEFAULT nextval('edgar_embeddings_id_seq'),
+                ticker      TEXT,
+                accession   TEXT,
+                text        TEXT,
+                embedding   FLOAT[384],
+                updated_at  TIMESTAMP DEFAULT now()
+            )
+        """)
+        try:
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_edgar_emb
+                ON edgar_embeddings USING HNSW (embedding)
+                WITH (metric = 'cosine')
+            """)
+        except Exception as e:
+            logger.warning(f"Failed to create HNSW index on edgar_embeddings: {e}")
+
+        # ══ SILVER LAYER ═══════════════════════════════════════════════════════
+        # Derived, recomputable feature tables built from bronze bars.
+        # Grain: one row per entity per trading day. Rebuilt with INSERT OR REPLACE.
+
+        # ── Silver: per-stock daily technical features ─────────────────────────
+        # Source: polygon_bars WHERE timespan='day'. Windows are trailing N days.
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS silver_stock_features (
+                ticker        TEXT    NOT NULL,
+                ts            TEXT    NOT NULL,   -- trading day, ISO-8601 (bronze join key)
+                trade_date    DATE,              -- typed date for window ordering
+                close         DOUBLE,            -- from bronze polygon_bars (day)
+                volume        DOUBLE,
+                daily_return  DOUBLE,            -- close / prev_close - 1
+                -- simple moving averages of close
+                ma_20         DOUBLE,
+                ma_50         DOUBLE,
+                ma_100        DOUBLE,
+                -- rolling sample standard deviation of close
+                std_20        DOUBLE,
+                std_50        DOUBLE,
+                std_100       DOUBLE,
+                pct_change    DOUBLE,            -- daily_return * 100 (percent)
+                -- price z-score = (close - ma_N) / std_N
+                zscore_20     DOUBLE,
+                zscore_50     DOUBLE,
+                zscore_100    DOUBLE,
+                -- sigma band flag on price: '+3s' | 'normal' | '-3s' | NULL
+                sigma_flag_20  TEXT,
+                sigma_flag_50  TEXT,
+                sigma_flag_100 TEXT,
+                -- return z-score = (pct_change - mean_ret_N) / std_ret_N
+                zscore_ret_20  DOUBLE,
+                zscore_ret_50  DOUBLE,
+                zscore_ret_100 DOUBLE,
+                -- sigma band flag on returns
+                sigma_flag_ret_20  TEXT,
+                sigma_flag_ret_50  TEXT,
+                sigma_flag_ret_100 TEXT,
+                -- rolling VWAP = sum(typical_price*volume)/sum(volume), typical=(h+l+c)/3
+                vwap_20       DOUBLE,
+                vwap_50       DOUBLE,
+                vwap_100      DOUBLE,
+                computed_at   TIMESTAMP DEFAULT now(),
+                UNIQUE(ticker, ts)
+            )
+        """)
+        # ── Migrate: add sigma_flag columns if they don't exist yet ───────────
+        for col in ("sigma_flag_20", "sigma_flag_50", "sigma_flag_100"):
+            try:
+                conn.execute(f"ALTER TABLE silver_stock_features ADD COLUMN {col} TEXT")
+                logger.info(f"Migrated silver_stock_features: added {col}")
+            except Exception:
+                pass  # column already exists
+        for col in ("pct_change",):
+            try:
+                conn.execute(f"ALTER TABLE silver_stock_features ADD COLUMN {col} DOUBLE")
+                logger.info(f"Migrated silver_stock_features: added {col}")
+            except Exception:
+                pass
+        for col in ("zscore_ret_20", "zscore_ret_50", "zscore_ret_100"):
+            try:
+                conn.execute(f"ALTER TABLE silver_stock_features ADD COLUMN {col} DOUBLE")
+                logger.info(f"Migrated silver_stock_features: added {col}")
+            except Exception:
+                pass
+        for col in ("sigma_flag_ret_20", "sigma_flag_ret_50", "sigma_flag_ret_100"):
+            try:
+                conn.execute(f"ALTER TABLE silver_stock_features ADD COLUMN {col} TEXT")
+                logger.info(f"Migrated silver_stock_features: added {col}")
+            except Exception:
+                pass
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_ssf_ticker_date
+                ON silver_stock_features(ticker, trade_date)
+        """)
+
+        # ── View: latest z-score alerts per ticker ─────────────────────────────
+        # Query this view to see which tickers are currently outside +-3 std devs.
+        # sigma_flag values: '+3s' (above), '-3s' (below), 'normal', NULL (warm-up)
+        conn.execute("DROP VIEW IF EXISTS v_zscore_alerts")
+        conn.execute("""
+            CREATE VIEW v_zscore_alerts AS
+            WITH latest AS (
+                SELECT *,
+                       ROW_NUMBER() OVER (PARTITION BY ticker ORDER BY trade_date DESC) AS rn
+                FROM silver_stock_features
+            )
+            SELECT
+                ticker,
+                trade_date,
+                close,
+                pct_change,
+                zscore_20,   sigma_flag_20,
+                zscore_50,   sigma_flag_50,
+                zscore_100,  sigma_flag_100,
+                zscore_ret_20,  sigma_flag_ret_20,
+                zscore_ret_50,  sigma_flag_ret_50,
+                zscore_ret_100, sigma_flag_ret_100,
+                CASE
+                    WHEN sigma_flag_20      IN ('+3s', '-3s')
+                      OR sigma_flag_50      IN ('+3s', '-3s')
+                      OR sigma_flag_100     IN ('+3s', '-3s')
+                      OR sigma_flag_ret_20  IN ('+3s', '-3s')
+                      OR sigma_flag_ret_50  IN ('+3s', '-3s')
+                      OR sigma_flag_ret_100 IN ('+3s', '-3s')
+                    THEN true ELSE false
+                END AS any_breach,
+                GREATEST(
+                    ABS(COALESCE(zscore_20,      0)),
+                    ABS(COALESCE(zscore_50,      0)),
+                    ABS(COALESCE(zscore_100,     0)),
+                    ABS(COALESCE(zscore_ret_20,  0)),
+                    ABS(COALESCE(zscore_ret_50,  0)),
+                    ABS(COALESCE(zscore_ret_100, 0))
+                ) AS max_abs_zscore
+            FROM latest
+            WHERE rn = 1
+            ORDER BY max_abs_zscore DESC
+        """)
+
+        # ── Silver: per-contract daily option greeks (Black-Scholes-Merton) ────
+        # Source: polygon_option_bars (option price) JOIN polygon_bars (underlying
+        # close). implied_vol solved from the option's market close; greeks analytic.
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS silver_option_greeks (
+                option_ticker   TEXT    NOT NULL,   -- OPRA symbol
+                underlying      TEXT    NOT NULL,
+                expiry          TEXT,               -- YYYY-MM-DD
+                strike          DOUBLE,
+                "right"         TEXT,               -- 'call' | 'put'
+                ts              TEXT    NOT NULL,   -- trading day, ISO-8601
+                trade_date      DATE,
+                option_close    DOUBLE,             -- option price from bronze bar
+                und_close       DOUBLE,             -- underlying close (S)
+                time_to_expiry  DOUBLE,             -- years to expiry (ACT/365)
+                moneyness       DOUBLE,             -- und_close / strike
+                risk_free_rate  DOUBLE,             -- r assumption used
+                dividend_yield  DOUBLE,             -- q assumption used (default 0)
+                implied_vol     DOUBLE,             -- sigma solved from option_close
+                delta           DOUBLE,
+                gamma           DOUBLE,
+                theta           DOUBLE,             -- per calendar day
+                vega            DOUBLE,             -- per 1 vol point
+                rho             DOUBLE,
+                computed_at     TIMESTAMP DEFAULT now(),
+                UNIQUE(option_ticker, ts)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_sog_underlying_date
+                
+                ON silver_option_greeks(underlying, trade_date)
+        """)
+
+        # -- Silver: per-underlying daily options POSITIONING --
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS silver_option_positioning (
+                underlying      TEXT    NOT NULL,
+                ts              TEXT    NOT NULL,
+                trade_date      DATE,
+                total_volume    DOUBLE,
+                call_volume     DOUBLE,
+                put_volume      DOUBLE,
+                put_call_ratio  DOUBLE,
+                atm_iv          DOUBLE,
+                call_iv_25d     DOUBLE,
+                put_iv_25d      DOUBLE,
+                iv_skew_25d     DOUBLE,
+                n_contracts     INTEGER,
+                computed_at     TIMESTAMP DEFAULT now(),
+                UNIQUE(underlying, ts)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_sop_underlying_date
+                ON silver_option_positioning(underlying, trade_date)
+        """)
+
+        # ── Silver: COT (Commitments of Traders) positioning features ─────────
+        # Source: cot_reports (Bronze, weekly). Grain: one row per (ticker, report_date).
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS silver_cot_features (
+                report_date          DATE    NOT NULL,
+                ticker               TEXT    NOT NULL,
+                noncomm_long         BIGINT,
+                noncomm_short        BIGINT,
+                noncomm_net          BIGINT,
+                comm_long            BIGINT,
+                comm_short           BIGINT,
+                comm_net             BIGINT,
+                n_weeks              INTEGER,
+                net_pos_mean_52w     DOUBLE,
+                net_pos_std_52w      DOUBLE,
+                net_pos_zscore_52w   DOUBLE,
+                comm_net_mean_52w    DOUBLE,
+                comm_net_std_52w     DOUBLE,
+                comm_net_zscore_52w  DOUBLE,
+                spec_comm_divergence DOUBLE,
+                crowd_flag           TEXT,
+                computed_at          TIMESTAMP DEFAULT now(),
+                PRIMARY KEY (report_date, ticker)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_scf_ticker_date
+                ON silver_cot_features(ticker, report_date)
+        """)
+
+        # ── Silver: futures continuous-contract price features ────────────────
+        # Source: polygon_bars (Bronze, day bars) for continuous futures tickers
+        # like 'ES1:COM'. Grain: one row per (ticker, trade_date).
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS silver_futures_features (
+                trade_date      DATE    NOT NULL,
+                ticker          TEXT    NOT NULL,
+                open_price      DOUBLE,
+                high_price      DOUBLE,
+                low_price       DOUBLE,
+                close_price     DOUBLE,
+                volume          BIGINT,
+                n20             INTEGER,
+                ma_20           DOUBLE,
+                std_20          DOUBLE,
+                zscore_20       DOUBLE,
+                n_ret20         INTEGER,
+                ret             DOUBLE,
+                mean_ret_20     DOUBLE,
+                std_ret_20      DOUBLE,
+                zscore_ret_20   DOUBLE,
+                vx_term_slope   DOUBLE,
+                regime_flag     TEXT,
+                computed_at     TIMESTAMP DEFAULT now(),
+                PRIMARY KEY (trade_date, ticker)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_sff_ticker_date
+                ON silver_futures_features(ticker, trade_date)
+        """)
+
+        # ── View: latest COT positioning + futures price context per ticker ───
+        conn.execute("DROP VIEW IF EXISTS v_cot_positioning")
+        conn.execute("""
+            CREATE VIEW v_cot_positioning AS
+            WITH latest_cot AS (
+                SELECT *, ROW_NUMBER() OVER (PARTITION BY ticker ORDER BY report_date DESC) AS rn
+                FROM silver_cot_features
+            ),
+            latest_fut AS (
+                SELECT *, ROW_NUMBER() OVER (PARTITION BY ticker ORDER BY trade_date DESC) AS rn
+                FROM silver_futures_features
+            )
+            SELECT
+                c.ticker,
+                c.report_date,
+                c.noncomm_net,
+                c.net_pos_zscore_52w,
+                c.comm_net_zscore_52w,
+                c.spec_comm_divergence,
+                c.crowd_flag,
+                f.trade_date AS futures_date,
+                f.close_price AS futures_close,
+                f.zscore_20 AS futures_zscore_20,
+                f.vx_term_slope,
+                f.regime_flag
+            FROM latest_cot c
+            LEFT JOIN latest_fut f ON f.ticker = c.ticker || '1:COM' AND f.rn = 1
+            WHERE c.rn = 1
+            ORDER BY ABS(COALESCE(c.net_pos_zscore_52w, 0)) DESC
+        """)
+
+        # ══ GOLD LAYER ════════════════════
+        # Backtest results: runs, trades, portfolio snapshots, metrics, signals.
+
+        # ── Gold: backtest run metadata ───────────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS gold_backtest_runs (
+                run_id      TEXT NOT NULL PRIMARY KEY,
+                config      TEXT,
+                universe    TEXT,
+                start_date  DATE NOT NULL,
+                end_date    DATE NOT NULL,
+                created_at  TIMESTAMP DEFAULT now(),
+                fold_id     INTEGER,           -- walk-forward OOS fold (NULL = plain run)
+                wf_run_id   TEXT               -- parent walk-forward run (NULL = plain run)
+            )
+        """)
+        # ── Migrate: add fold_id / wf_run_id if the table predates walk-forward
+        try:
+            conn.execute("ALTER TABLE gold_backtest_runs ADD COLUMN fold_id INTEGER")
+            logger.info("Migrated gold_backtest_runs: added fold_id")
+        except Exception:
+            pass  # column already exists
+        try:
+            conn.execute("ALTER TABLE gold_backtest_runs ADD COLUMN wf_run_id TEXT")
+            logger.info("Migrated gold_backtest_runs: added wf_run_id")
+        except Exception:
+            pass  # column already exists
+
+        # ── Gold: individual simulated trades ─────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS gold_trades (
+                trade_id        TEXT    NOT NULL PRIMARY KEY,
+                run_id          TEXT    NOT NULL,
+                ticker          TEXT    NOT NULL,
+                entry_date      DATE    NOT NULL,
+                exit_date       DATE,
+                direction       INTEGER NOT NULL,
+                shares          DOUBLE,
+                entry_price     DOUBLE,
+                exit_price      DOUBLE,
+                gross_pnl       DOUBLE,
+                slippage_cost   DOUBLE,
+                commission_cost DOUBLE,
+                net_pnl         DOUBLE,
+                entry_regime    TEXT,
+                exit_regime     TEXT,
+                signal_type     TEXT
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_gt_run_ticker
+                ON gold_trades(run_id, ticker, entry_date)
+        """)
+
+        # ── Gold: daily portfolio snapshots ───────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS gold_portfolio (
+                run_id       TEXT NOT NULL,
+                trade_date   DATE NOT NULL,
+                nav          DOUBLE,
+                cash         DOUBLE,
+                drawdown_pct DOUBLE,
+                n_positions  INTEGER,
+                UNIQUE(run_id, trade_date)
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_gp_run_date
+                ON gold_portfolio(run_id, trade_date)
+        """)
+
+        # ── Gold: aggregated metrics per run ──────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS gold_metrics (
+                run_id            TEXT    NOT NULL PRIMARY KEY,
+                sharpe            DOUBLE,
+                sortino           DOUBLE,
+                mdd_pct           DOUBLE,
+                mdd_duration_days INTEGER,
+                mdd_recovery_days INTEGER,
+                calmar            DOUBLE,
+                win_rate          DOUBLE,
+                profit_factor     DOUBLE,
+                expectancy        DOUBLE,
+                cost_drag         DOUBLE,
+                ann_return        DOUBLE,
+                ann_vol           DOUBLE
+            )
+        """)
+
+        # ── Gold: walk-forward OOS aggregate summary per walk-forward run ─────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS gold_oos_summary (
+                run_id TEXT NOT NULL,
+                run_ts TIMESTAMPTZ DEFAULT current_timestamp,
+                n_folds INTEGER,
+                mean_sharpe DOUBLE,
+                consistency_ratio DOUBLE,
+                combined_sharpe DOUBLE,
+                worst_fold_mdd DOUBLE,
+                split_type TEXT,
+                embargo_days INTEGER,
+                PRIMARY KEY (run_id)
+            )
+        """)
+
+        # ── Gold: immutable signal audit log ──────────────────────────────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS gold_signals (
+                signal_id   TEXT    NOT NULL PRIMARY KEY,
+                run_id      TEXT    NOT NULL,
+                ticker      TEXT    NOT NULL,
+                signal_date DATE    NOT NULL,
+                direction   INTEGER NOT NULL,
+                strength    DOUBLE,
+                signal_type TEXT,
+                computed_at TIMESTAMP DEFAULT now()
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_gs_run_date
+                ON gold_signals(run_id, signal_date, ticker)
+        """)
+
+    finally:
+        conn.close()
+
+    logger.info(f"Database initialised at {DB_PATH}")

etl/chat_engine.py

@@ -0,0 +1,332 @@
+"""
+Natural-language chat interface over the Equity Workbench/Polygon/EDGAR DuckDB database.
+
+Supported providers:
+  CHAT_PROVIDER = deepseek | mimo | openai | anthropic | ollama
+  CHAT_MODEL    = optional model override
+"""
+import os
+import re
+from typing import Optional
+
+import anthropic
+import duckdb
+import pandas as pd
+from loguru import logger
+from openai import OpenAI
+from dotenv import load_dotenv
+
+load_dotenv()
+
+DB_PATH = os.getenv("DB_PATH", "./data/equity.duckdb")
+_XIAOMI_OPENAI_KEY = os.getenv("XIAOMI_OPENAI_API_KEY", "")
+_MIMO_BASE_URL = (
+    os.getenv("XIAOMI_OPENAI_BASE_URL", "https://token-plan-sgp.xiaomimimo.com/v1")
+    if _XIAOMI_OPENAI_KEY
+    else os.getenv("MIMO_BASE_URL", "http://localhost:11434/v1")
+)
+
+_PROVIDERS = {
+    # Pipeline stage 1 - Xiaomi MiMo via its OpenAI-compatible endpoint.
+    "mimo": {
+        "sdk": "openai",
+        "base_url": _MIMO_BASE_URL,
+        "model": os.getenv("MIMO_MODEL", "mimo-v2.5-pro"),
+        "api_key_env": "XIAOMI_OPENAI_API_KEY",
+        "allow_blank_key": False,
+    },
+    # Pipeline stage 2 - DeepSeek via its OpenAI-compatible endpoint.
+    "deepseek": {
+        "sdk": "openai",
+        "base_url": os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com"),
+        "model": os.getenv("DEEPSEEK_MODEL", "deepseek-v4-flash"),
+        "api_key_env": "DEEPSEEK_OPENAI_API_KEY",
+        "allow_blank_key": False,
+    },
+    # Pipeline stage 3 / single-provider default — final review (Claude Sonnet)
+    "anthropic": {
+        "sdk": "anthropic",
+        "base_url": "https://api.anthropic.com",
+        "model": "claude-sonnet-4-6",
+        "api_key_env": "ANTHROPIC_API_KEY",
+        "allow_blank_key": False,
+    },
+    # Native OpenAI (unchanged)
+    "openai": {
+        "sdk": "openai",
+        "base_url": "https://api.openai.com/v1",
+        "model": "gpt-4o",
+        "api_key_env": "OPENAI_API_KEY",
+        "allow_blank_key": False,
+    },
+    # Local Ollama (unchanged)
+    "ollama": {
+        "sdk": "openai",
+        "base_url": os.getenv("OLLAMA_BASE_URL", "http://localhost:11434/v1"),
+        "model": os.getenv("OLLAMA_MODEL", "llama3.2"),
+        "api_key_env": "OLLAMA_API_KEY",
+        "allow_blank_key": True,
+    },
+}
+
+_PROVIDER = os.getenv("CHAT_PROVIDER", "deepseek").lower()
+_CFG = _PROVIDERS.get(_PROVIDER, _PROVIDERS["deepseek"])
+_MODEL = os.getenv("CHAT_MODEL") or _CFG["model"]  # CHAT_MODEL env overrides provider default
+
+SCHEMA = """
+You have access to a DuckDB financial database with these tables:
+
+IBKR live data:
+- stock_quotes(ticker, ts, bid, ask, last, close, open, high, low, volume, vwap, created_at)
+- option_quotes(ticker, expiry, strike, right, ts, bid, ask, last, volume, open_interest, implied_vol, delta, gamma, theta, vega, und_price, pv_dividend)
+- option_chains(ticker, expiry, strike, right, exchange, fetched_at)
+- etl_runs(id, run_type, status, rows_written, started_at, finished_at, message)
+
+Polygon historical data:
+- polygon_bars(ticker, ts, timespan, open, high, low, close, volume, vwap, transactions)
+- polygon_snapshots(ticker, ts, bid, ask, last, prev_close, day_volume)
+- polygon_option_snapshots(underlying, expiry, strike, right, ts, day_open, day_close, day_volume, open_interest, implied_vol, delta, gamma, theta, vega)
+- polygon_tickers(ticker, name, market, primary_exchange, type, active, currency, description)
+
+SEC EDGAR financials:
+- edgar_filings(ticker, cik, form_type, filed_date, accession_number, primary_doc)
+- edgar_facts(ticker, cik, taxonomy, concept, label, unit, value, period_start, period_end, form_type, filed_date)
+
+Notes:
+- Use DuckDB SQL syntax.
+- Dates are stored as TEXT in ISO-8601 format. Cast with ::TIMESTAMP or ::DATE as needed.
+- Always LIMIT results to 100 rows unless the user asks for more.
+- For latest queries use QUALIFY ROW_NUMBER() OVER (PARTITION BY ticker ORDER BY ts DESC) = 1.
+"""
+
+SYSTEM_PROMPT = f"""You are a financial data analyst assistant. The user will ask questions about their market data.
+
+{SCHEMA}
+
+Rules:
+1. If the question requires data, respond with ONLY a valid DuckDB SQL query. No markdown, no explanation.
+2. If the question is conversational or cannot be answered with SQL, respond with a plain English answer starting with "ANSWER:".
+3. Never make up data. Only query what exists in the schema above.
+4. Keep SQL readable and add brief inline comments for complex logic.
+5. Only generate read-only SELECT or WITH queries.
+"""
+
+
+def _call_provider(provider: str, messages: list, max_tokens: int = 1024, model: Optional[str] = None) -> str:
+    """Call a specific provider by name and return the text reply."""
+    cfg = _PROVIDERS.get(provider, _PROVIDERS["anthropic"])
+    model = model or cfg["model"]
+    api_key = os.getenv(cfg["api_key_env"], "")
+    if not api_key and not cfg["allow_blank_key"]:
+        raise ValueError(f"{cfg['api_key_env']} is not set in .env (provider={provider}).")
+
+    if cfg.get("sdk", "openai") == "anthropic":
+        client = anthropic.Anthropic(api_key=api_key)
+        system = next((m["content"] for m in messages if m["role"] == "system"), "")
+        user_msgs = [m for m in messages if m["role"] != "system"]
+        resp = client.messages.create(
+            model=model, max_tokens=max_tokens, system=system, messages=user_msgs,
+        )
+        text_block = next(b for b in resp.content if b.type == "text")
+        return text_block.text
+    else:
+        client = OpenAI(api_key=api_key or "local", base_url=cfg["base_url"])
+        resp = client.chat.completions.create(
+            model=model, messages=messages, temperature=0.1, max_tokens=max_tokens,
+        )
+        return (resp.choices[0].message.content or "").strip()
+
+
+def _call_llm(messages: list, max_tokens: int = 1024) -> str:
+    """Send messages to the configured provider, respecting CHAT_MODEL override."""
+    return _call_provider(_PROVIDER, messages, max_tokens, model=_MODEL)
+
+
+_REVIEW_PROMPT = """You are reviewing a DuckDB SQL query generated by another model.
+Check for:
+1. Correctness — does it answer the user's question?
+2. Safety — read-only SELECT/WITH only, no data mutation.
+3. DuckDB syntax — valid functions, correct quoting.
+
+Respond with one of:
+- APPROVED: <brief reason>
+- CORRECTED: <brief reason>
+```sql
+<corrected query>
+```
+"""
+
+
+def chat_pipeline(question: str, history: Optional[list] = None, max_rows: int = 100) -> dict:
+    """
+    3-stage pipeline: MiMo generates SQL → DeepSeek reviews → Claude approves.
+
+    Each stage can correct the SQL before passing it forward.
+    Falls back gracefully if a review stage fails.
+    """
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    if history:
+        messages.extend(history)
+    messages.append({"role": "user", "content": question})
+
+    # Stage 1: MiMo generates SQL
+    try:
+        raw = _call_provider("mimo", messages, max_tokens=1024)
+    except Exception as e:
+        logger.error(f"MiMo generation failed: {e}")
+        return {"type": "error", "sql": None, "data": None, "answer": f"Generation error: {e}"}
+
+    if raw.startswith("ANSWER:"):
+        return {"type": "text", "sql": None, "data": None, "answer": raw[len("ANSWER:"):].strip()}
+
+    sql = _clean_sql(raw)
+
+    def _extract_corrected(review: str) -> Optional[str]:
+        m = re.search(r"```sql\n(.*?)\n```", review, re.DOTALL)
+        return m.group(1).strip() if m else None
+
+    # Stage 2: DeepSeek first review
+    try:
+        ds_review = _call_provider("deepseek", [
+            {"role": "system", "content": _REVIEW_PROMPT},
+            {"role": "user", "content": f"Question: {question}\n\nSQL:\n```sql\n{sql}\n```"},
+        ], max_tokens=512)
+        logger.info(f"DeepSeek review: {ds_review[:80]}")
+        if ds_review.startswith("CORRECTED:"):
+            corrected = _extract_corrected(ds_review)
+            if corrected:
+                sql = corrected
+    except Exception as e:
+        logger.warning(f"DeepSeek review skipped: {e}")
+
+    # Stage 3: Claude final review
+    try:
+        claude_review = _call_provider("anthropic", [
+            {"role": "system", "content": _REVIEW_PROMPT},
+            {"role": "user", "content": f"Question: {question}\n\nSQL:\n```sql\n{sql}\n```"},
+        ], max_tokens=512)
+        logger.info(f"Claude review: {claude_review[:80]}")
+        if claude_review.startswith("CORRECTED:"):
+            corrected = _extract_corrected(claude_review)
+            if corrected:
+                sql = corrected
+        elif not claude_review.startswith("APPROVED"):
+            return {"type": "error", "sql": sql, "data": None, "answer": f"Review rejected: {claude_review}"}
+    except Exception as e:
+        logger.warning(f"Claude review skipped: {e}")
+
+    validation_error = _validate_read_only_sql(sql)
+    if validation_error:
+        return {"type": "error", "sql": sql, "data": None, "answer": validation_error}
+
+    try:
+        with duckdb.connect(DB_PATH, read_only=True) as conn:
+            try:
+                conn.execute("SET enable_external_access=false")
+            except Exception as _e:
+                logger.debug(f"Could not set enable_external_access=false: {_e}")
+            df = conn.sql(sql).limit(max_rows).df()
+    except Exception as e:
+        logger.warning(f"SQL execution failed: {e}\nSQL: {sql}")
+        return {"type": "error", "sql": sql, "data": None, "answer": f"SQL error: {e}"}
+
+    answer = "The query returned no results." if df.empty else _summarise(question, df)
+    return {"type": "table", "sql": sql, "data": df.head(max_rows), "answer": answer}
+
+
+def chat(question: str, history: Optional[list] = None, max_rows: int = 100) -> dict:
+    """
+    Ask a natural-language question about the database.
+
+    Returns a dict with type, sql, data, and answer fields.
+    """
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    if history:
+        messages.extend(history)
+    messages.append({"role": "user", "content": question})
+
+    try:
+        reply = _call_llm(messages, max_tokens=1024)
+    except Exception as e:
+        logger.error(f"{_PROVIDER} API error: {e}")
+        return {"type": "error", "sql": None, "data": None, "answer": f"API error: {e}"}
+
+    if reply.startswith("ANSWER:"):
+        return {
+            "type": "text",
+            "sql": None,
+            "data": None,
+            "answer": reply[len("ANSWER:"):].strip(),
+        }
+
+    sql = _clean_sql(reply)
+    validation_error = _validate_read_only_sql(sql)
+    if validation_error:
+        return {"type": "error", "sql": sql, "data": None, "answer": validation_error}
+
+    try:
+        with duckdb.connect(DB_PATH, read_only=True) as conn:
+            try:
+                conn.execute("SET enable_external_access=false")
+            except Exception as _e:
+                logger.debug(f"Could not set enable_external_access=false: {_e}")
+            df = conn.sql(sql).limit(max_rows).df()
+    except Exception as e:
+        logger.warning(f"SQL execution failed: {e}\nSQL: {sql}")
+        return {"type": "error", "sql": sql, "data": None, "answer": f"SQL error: {e}"}
+
+    answer = "The query returned no results." if df.empty else _summarise(question, df)
+    return {"type": "table", "sql": sql, "data": df.head(max_rows), "answer": answer}
+
+
+def _clean_sql(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
+    return text.strip()
+
+
+def _strip_sql_comments(sql: str) -> str:
+    sql = re.sub(r"/\*.*?\*/", " ", sql, flags=re.DOTALL)
+    sql = re.sub(r"--[^\n\r]*", " ", sql)
+    return sql.strip()
+
+
+def _validate_read_only_sql(sql: str) -> Optional[str]:
+    compact = _strip_sql_comments(sql)
+    if not compact:
+        return "The model did not return a SQL query."
+    if ";" in compact:
+        return "Rejected SQL with semicolons or multiple statements."
+
+    first = compact.lstrip().split(None, 1)[0].lower()
+    if first not in {"select", "with"}:
+        return "Rejected SQL because only SELECT and WITH queries are allowed."
+
+    blocked = {
+        "attach", "call", "copy", "create", "delete", "detach", "drop",
+        "export", "from_csv", "glob", "httpfs", "import", "insert",
+        "install", "load", "pragma", "read_blob", "read_csv", "read_json",
+        "read_parquet", "read_text", "set", "update",
+    }
+    tokens = set(re.findall(r"\b[a-z_][a-z0-9_]*\b", compact.lower()))
+    found = sorted(tokens & blocked)
+    if found:
+        return f"Rejected SQL containing blocked keyword/function: {', '.join(found)}."
+    return None
+
+
+def _summarise(question: str, df: pd.DataFrame) -> str:
+    preview = df.head(5).to_markdown(index=False)
+    try:
+        return _call_llm([{
+            "role": "user",
+            "content": (
+                f'The user asked: "{question}"\n\n'
+                f"Query returned {len(df)} rows. Here are the first 5:\n{preview}\n\n"
+                "Write a concise 1-2 sentence plain-English answer. No markdown."
+            ),
+        }], max_tokens=200)
+    except Exception:
+        return f"Query returned {len(df)} rows."

frontend/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#0A0C10" />
+    <meta name="description" content="Evidence-first market research and execution analytics workbench." />
+    <title>IBKR Workbench</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "oxlint",
+    "test": "vitest run",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "axios": "^1.18.1",
+    "echarts": "^6.1.0",
+    "echarts-for-react": "^3.0.6",
+    "lucide-react": "^1.23.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.18.1",
+    "remark-gfm": "^4.0.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.13.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "jsdom": "^29.1.1",
+    "oxlint": "^1.71.0",
+    "tailwindcss": "^4.3.2",
+    "typescript": "~6.0.2",
+    "vite": "^8.1.1",
+    "vitest": "^4.1.10"
+  }
+}

frontend/src/App.css

@@ -0,0 +1,184 @@
+.counter {
+  font-size: 16px;
+  padding: 5px 10px;
+  border-radius: 5px;
+  color: var(--accent);
+  background: var(--accent-bg);
+  border: 2px solid transparent;
+  transition: border-color 0.3s;
+  margin-bottom: 24px;
+
+  &:hover {
+    border-color: var(--accent-border);
+  }
+  &:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+  }
+}
+
+.hero {
+  position: relative;
+
+  .base,
+  .framework,
+  .vite {
+    inset-inline: 0;
+    margin: 0 auto;
+  }
+
+  .base {
+    width: 170px;
+    position: relative;
+    z-index: 0;
+  }
+
+  .framework,
+  .vite {
+    position: absolute;
+  }
+
+  .framework {
+    z-index: 1;
+    top: 34px;
+    height: 28px;
+    transform: perspective(2000px) rotateZ(300deg) rotateX(44deg) rotateY(39deg)
+      scale(1.4);
+  }
+
+  .vite {
+    z-index: 0;
+    top: 107px;
+    height: 26px;
+    width: auto;
+    transform: perspective(2000px) rotateZ(300deg) rotateX(40deg) rotateY(39deg)
+      scale(0.8);
+  }
+}
+
+#center {
+  display: flex;
+  flex-direction: column;
+  gap: 25px;
+  place-content: center;
+  place-items: center;
+  flex-grow: 1;
+
+  @media (max-width: 1024px) {
+    padding: 32px 20px 24px;
+    gap: 18px;
+  }
+}
+
+#next-steps {
+  display: flex;
+  border-top: 1px solid var(--border);
+  text-align: left;
+
+  & > div {
+    flex: 1 1 0;
+    padding: 32px;
+    @media (max-width: 1024px) {
+      padding: 24px 20px;
+    }
+  }
+
+  .icon {
+    margin-bottom: 16px;
+    width: 22px;
+    height: 22px;
+  }
+
+  @media (max-width: 1024px) {
+    flex-direction: column;
+    text-align: center;
+  }
+}
+
+#docs {
+  border-right: 1px solid var(--border);
+
+  @media (max-width: 1024px) {
+    border-right: none;
+    border-bottom: 1px solid var(--border);
+  }
+}
+
+#next-steps ul {
+  list-style: none;
+  padding: 0;
+  display: flex;
+  gap: 8px;
+  margin: 32px 0 0;
+
+  .logo {
+    height: 18px;
+  }
+
+  a {
+    color: var(--text-h);
+    font-size: 16px;
+    border-radius: 6px;
+    background: var(--social-bg);
+    display: flex;
+    padding: 6px 12px;
+    align-items: center;
+    gap: 8px;
+    text-decoration: none;
+    transition: box-shadow 0.3s;
+
+    &:hover {
+      box-shadow: var(--shadow);
+    }
+    .button-icon {
+      height: 18px;
+      width: 18px;
+    }
+  }
+
+  @media (max-width: 1024px) {
+    margin-top: 20px;
+    flex-wrap: wrap;
+    justify-content: center;
+
+    li {
+      flex: 1 1 calc(50% - 8px);
+    }
+
+    a {
+      width: 100%;
+      justify-content: center;
+      box-sizing: border-box;
+    }
+  }
+}
+
+#spacer {
+  height: 88px;
+  border-top: 1px solid var(--border);
+  @media (max-width: 1024px) {
+    height: 48px;
+  }
+}
+
+.ticks {
+  position: relative;
+  width: 100%;
+
+  &::before,
+  &::after {
+    content: '';
+    position: absolute;
+    top: -4.5px;
+    border: 5px solid transparent;
+  }
+
+  &::before {
+    left: 0;
+    border-left-color: var(--border);
+  }
+  &::after {
+    right: 0;
+    border-right-color: var(--border);
+  }
+}

frontend/src/App.test.tsx

@@ -0,0 +1,29 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import App from './App';
+
+afterEach(() => {
+  cleanup();
+  window.history.pushState({}, '', '/');
+});
+
+describe('Workbench accessibility', () => {
+  it('provides skip navigation and a labeled chat composer', async () => {
+    window.history.pushState({}, '', '/chat');
+    render(<App />);
+
+    expect(screen.getByRole('link', { name: 'Skip to main content' })).toHaveAttribute('href', '#main-content');
+    expect(screen.getByRole('main')).toHaveAttribute('id', 'main-content');
+    expect(screen.getByRole('textbox', { name: 'Ask about portfolio data' })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Chat' })).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('exposes the selected history period to assistive technology', async () => {
+    window.history.pushState({}, '', '/history');
+    render(<App />);
+
+    expect(screen.getByRole('button', { name: '1Y history period' })).toHaveAttribute('aria-pressed', 'true');
+    expect(screen.getByRole('button', { name: '1M history period' })).toHaveAttribute('aria-pressed', 'false');
+    expect(screen.getByRole('combobox', { name: 'Ticker' })).toBeInTheDocument();
+  });
+});

frontend/src/App.tsx

@@ -0,0 +1,967 @@
+import { useState, useRef, useEffect, useMemo } from 'react';
+import type { ReactNode } from 'react';
+import { BrowserRouter as Router, Routes, Route, Navigate, NavLink } from 'react-router-dom';
+import {
+  MessageSquare, TrendingUp, BarChart2, Package, Link2,
+  Calculator as CalculatorIcon, Activity, Send, RefreshCw, ChevronUp, ChevronDown,
+  Minus, Database, CheckCircle, XCircle,
+  AlertCircle, Search, Zap, Cpu, Menu, X,
+  BookOpen, LineChart, ScrollText, Server
+} from 'lucide-react';
+import axios from 'axios';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { Analytics, AuditLog, Methodology, SystemOverview } from './ResearchOps';
+import { ChartPanel } from './components/ChartPanel';
+import type { ChartOption } from './components/ChartPanel';
+
+const API = axios.create({ baseURL: '/api', timeout: 60000 });
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const fmt = (n: number | null | undefined, dec = 2) =>
+  n == null ? '-' : n.toLocaleString('en-US', { minimumFractionDigits: dec, maximumFractionDigits: dec });
+const fmtPct = (n: number | null | undefined) =>
+  n == null ? '-' : `${n >= 0 ? '+' : ''}${(n * 100).toFixed(2)}%`;
+const clsPnl = (n: number | null | undefined) =>
+  n == null ? '' : n > 0 ? 'text-[var(--color-bullish)]' : n < 0 ? 'text-[var(--color-bearish)]' : 'text-[var(--color-secondary)]';
+
+// ── Reusable components ───────────────────────────────────────────────────────
+
+const StatCard = ({ label, value, sub, up }: { label: string; value: string; sub?: string; up?: boolean | null }) => (
+  <div className="stat-card min-w-0">
+    <p className="text-[0.7rem] font-semibold uppercase tracking-widest text-[var(--color-secondary)] mb-1">{label}</p>
+    <p className={`text-xl font-semibold tabular-nums truncate ${up == null ? '' : up ? 'text-[var(--color-bullish)]' : 'text-[var(--color-bearish)]'}`} title={value}>
+      {value}
+    </p>
+    {sub && <p className="text-xs text-[var(--color-muted)] mt-0.5">{sub}</p>}
+  </div>
+);
+
+const PnlArrow = ({ v }: { v: number }) =>
+  v > 0 ? <ChevronUp size={14} className="text-[var(--color-bullish)]" />
+  : v < 0 ? <ChevronDown size={14} className="text-[var(--color-bearish)]" />
+  : <Minus size={14} className="text-[var(--color-secondary)]" />;
+
+const chartText = '#B8BDC5';
+const chartGrid = 'rgba(199,203,209,0.10)';
+
+// ── Layout ────────────────────────────────────────────────────────────────────
+
+const MARKET_NAV = [
+  { to: '/chat',       icon: MessageSquare, label: 'Chat' },
+  { to: '/quotes',     icon: TrendingUp,    label: 'Quotes' },
+  { to: '/history',    icon: BarChart2,     label: 'History' },
+  { to: '/polygon',    icon: Package,       label: 'Polygon' },
+  { to: '/options',    icon: Link2,         label: 'Options' },
+  { to: '/calculator', icon: CalculatorIcon, label: 'Calculator' },
+  { to: '/health',     icon: Activity,      label: 'Health' },
+];
+
+const RESEARCH_NAV = [
+  { to: '/methodology', icon: BookOpen, label: 'Methodology' },
+  { to: '/analytics', icon: LineChart, label: 'Analytics' },
+  { to: '/audit', icon: ScrollText, label: 'Audit Log' },
+  { to: '/system', icon: Server, label: 'System Overview' },
+];
+
+const Layout = ({ children }: { children: ReactNode }) => {
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+  const [isDesktop, setIsDesktop] = useState(() =>
+    typeof window.matchMedia === 'function' ? window.matchMedia('(min-width: 1024px)').matches : true
+  );
+
+  useEffect(() => {
+    if (typeof window.matchMedia !== 'function') return;
+    const media = window.matchMedia('(min-width: 1024px)');
+    const updateViewport = (event: MediaQueryListEvent) => setIsDesktop(event.matches);
+    media.addEventListener('change', updateViewport);
+    return () => media.removeEventListener('change', updateViewport);
+  }, []);
+
+  useEffect(() => {
+    if (!sidebarOpen || isDesktop) return;
+    const closeOnEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setSidebarOpen(false);
+    };
+    document.addEventListener('keydown', closeOnEscape);
+    return () => document.removeEventListener('keydown', closeOnEscape);
+  }, [sidebarOpen, isDesktop]);
+
+  return (
+  <div className="flex min-h-dvh" style={{ background: 'var(--color-background)' }}>
+    <a href="#main-content" className="skip-link">Skip to main content</a>
+    {sidebarOpen && (
+      <button
+        type="button"
+        aria-label="Close navigation overlay"
+        className="fixed inset-0 bg-black/60 backdrop-blur-sm z-30 lg:hidden"
+        onClick={() => setSidebarOpen(false)}
+      />
+    )}
+
+    <aside
+      aria-label="IBKR Workbench"
+      {...(!isDesktop && !sidebarOpen ? { inert: true, 'aria-hidden': true } : {})}
+      className={`glass-sidebar w-72 lg:w-[248px] flex flex-col px-4 py-5 gap-1 fixed lg:sticky inset-y-0 left-0 top-0 h-screen z-40 shrink-0 transition-transform duration-300 ease-out ${sidebarOpen ? 'translate-x-0' : '-translate-x-full lg:translate-x-0'}`}
+    >
+      <div className="px-1 pb-6">
+        <div className="flex items-center justify-between gap-2">
+          <div className="flex items-center gap-3">
+          <div className="w-9 h-9 rounded-lg flex items-center justify-center bg-[var(--color-accent-fill)]">
+            <Search size={18} className="text-[var(--color-accent-ink)]" />
+          </div>
+          <p className="text-lg font-semibold leading-none tracking-tight">IBKR Workbench</p>
+          </div>
+          <button
+            type="button"
+            className="lg:hidden btn-ghost !p-2"
+            onClick={() => setSidebarOpen(false)}
+            aria-label="Close navigation"
+          >
+            <X size={16} />
+          </button>
+        </div>
+      </div>
+
+      <p className="text-[0.625rem] font-semibold uppercase tracking-[0.12em] text-[var(--color-muted)] px-2 mb-2">For Users</p>
+
+      {MARKET_NAV.map(({ to, icon: Icon, label }) => (
+        <NavLink key={to} to={to}
+          onClick={() => setSidebarOpen(false)}
+          className={({ isActive }) => `nav-item ${isActive ? 'active' : ''}`}>
+          <Icon size={15} strokeWidth={1.8} />
+          {label}
+        </NavLink>
+      ))}
+
+      <p className="text-[0.625rem] font-semibold uppercase tracking-[0.12em] text-[var(--color-muted)] px-2 mb-2 mt-5">Research &amp; Diagnostics</p>
+
+      {RESEARCH_NAV.map(({ to, icon: Icon, label }) => (
+        <NavLink key={to} to={to}
+          onClick={() => setSidebarOpen(false)}
+          className={({ isActive }) => `nav-item ${isActive ? 'active' : ''}`}>
+          <Icon size={15} strokeWidth={1.8} />
+          {label}
+        </NavLink>
+      ))}
+
+      <div className="mt-auto pt-4 border-t border-[var(--color-border)]">
+        <div className="flex items-center gap-2 px-2 py-1">
+          <div className="w-1.5 h-1.5 rounded-full bg-[var(--color-bullish)] status-pulse" />
+          <span className="text-xs text-[var(--color-secondary)]">DB connected</span>
+        </div>
+      </div>
+    </aside>
+
+    <main
+      id="main-content"
+      tabIndex={-1}
+      {...(!isDesktop && sidebarOpen ? { inert: true, 'aria-hidden': true } : {})}
+      className="flex-1 flex flex-col min-w-0 relative z-10"
+    >
+      <header className="glass-header h-14 flex items-center px-6 gap-3 sticky top-0 z-10">
+        <button
+          type="button"
+          className="lg:hidden btn-ghost !p-2"
+          onClick={() => setSidebarOpen(true)}
+          aria-label="Open navigation"
+        >
+          <Menu size={16} />
+        </button>
+        <div className="flex-1" />
+        <div className="glass-input flex items-center gap-2 px-3 py-1.5 text-xs text-[var(--color-secondary)]">
+          <Search size={13} />
+          <span>Search tickers...</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <div className="w-1.5 h-1.5 rounded-full bg-[var(--color-bullish)] status-pulse" />
+          <span className="text-xs text-[var(--color-secondary)]">Live</span>
+        </div>
+      </header>
+      <div className="flex-1 overflow-auto p-4 sm:p-6">{children}</div>
+    </main>
+  </div>
+  );
+};
+
+// ── Page: Chat ────────────────────────────────────────────────────────────────
+
+interface Msg { id: number; role: 'user' | 'assistant'; content: string; sql?: string; }
+let _msgId = 0;
+const nextId = () => ++_msgId;
+
+const SUGGESTED = [
+  'Show me the top 5 semiconductors by 30-day return',
+  "What is NVDA's average daily volume this year?",
+  'List all options with IV > 80% expiring in July',
+  'Compare MU and AMD price performance year-to-date',
+];
+
+const Chat = () => {
+  const [msgs, setMsgs] = useState<Msg[]>([]);
+  const [input, setInput] = useState('');
+  const [loading, setLoading] = useState(false);
+  const bottomRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => { bottomRef.current?.scrollIntoView({ behavior: 'smooth' }); }, [msgs]);
+
+  const send = async (text: string) => {
+    if (!text.trim() || loading) return;
+    setMsgs(m => [...m, { id: nextId(), role: 'user', content: text }]);
+    setInput('');
+    setLoading(true);
+    try {
+      const { data } = await API.post('/chat', { message: text });
+      setMsgs(m => [...m, { id: nextId(), role: 'assistant', content: data.response || data.message || '(no response)', sql: data.sql }]);
+    } catch {
+      setMsgs(m => [...m, { id: nextId(), role: 'assistant', content: 'Could not reach the chat API. Ensure the backend is running.' }]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="max-w-3xl mx-auto flex flex-col min-h-[calc(100dvh-7.5rem)] gap-4">
+      <div>
+        <h1 className="section-heading">Ask anything</h1>
+        <p className="text-xs text-[var(--color-secondary)] mt-1">Text-to-SQL over your DuckDB: stocks, options, EDGAR, COT</p>
+      </div>
+
+      <div className="flex-1 overflow-y-auto flex flex-col gap-3 pr-1">
+        {msgs.length === 0 && (
+          <div className="grid grid-cols-1 sm:grid-cols-2 gap-2 mt-4">
+            {SUGGESTED.map(s => (
+              <button key={s} onClick={() => send(s)}
+                className="glass-card text-left p-3 text-xs text-[var(--color-secondary)] hover:text-[var(--color-primary)] transition-colors">
+                {s}
+              </button>
+            ))}
+          </div>
+        )}
+        {msgs.map((m) => (
+          <div key={m.id} className={`flex ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}>
+            <div className={`max-w-[85%] px-4 py-3 text-sm ${m.role === 'user' ? 'msg-user' : 'msg-assistant'}`}>
+              <div className="prose-refined">
+                <ReactMarkdown remarkPlugins={[remarkGfm]}>{m.content}</ReactMarkdown>
+              </div>
+              {m.sql && (
+                <details className="mt-2">
+                  <summary className="text-[0.7rem] text-[var(--color-secondary)] cursor-pointer">SQL</summary>
+                  <pre className="text-[0.7rem] mt-1 overflow-x-auto">{m.sql}</pre>
+                </details>
+              )}
+            </div>
+          </div>
+        ))}
+        {loading && (
+          <div className="flex justify-start">
+            <div className="msg-assistant px-4 py-3">
+              <div className="flex gap-1">
+                {[0,1,2].map(i => (
+                  <div key={i} className="w-1.5 h-1.5 rounded-full bg-[var(--color-accent)]"
+                    style={{ animation: `pulse 1.2s ${i * 0.2}s infinite` }} />
+                ))}
+              </div>
+            </div>
+          </div>
+        )}
+        <div ref={bottomRef} />
+      </div>
+
+      <div className="glass-input flex items-end gap-2 p-3">
+        <label htmlFor="workbench-question" className="sr-only">Ask about portfolio data</label>
+        <textarea
+          id="workbench-question"
+          className="flex-1 bg-transparent text-sm text-[var(--color-primary)] placeholder-[var(--color-muted)] resize-none outline-none min-h-[2.5rem] max-h-32"
+          placeholder="Ask about your portfolio data..."
+          value={input}
+          onChange={e => setInput(e.target.value)}
+          onKeyDown={e => { if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); send(input); } }}
+          rows={1}
+        />
+        <button onClick={() => send(input)} disabled={loading || !input.trim()}
+          className="btn-primary py-2 px-3 disabled:opacity-40 disabled:cursor-not-allowed">
+          <Send size={14} />
+        </button>
+      </div>
+    </div>
+  );
+};
+
+// ── Page: Quotes ──────────────────────────────────────────────────────────────
+
+const MOCK_QUOTES = [
+  { ticker:'NVDA', last:131.20, chg: 0.0312, vol:42_183_000, high:133.50, low:129.10 },
+  { ticker:'AMD',  last:168.45, chg: 0.0187, vol:28_441_000, high:170.00, low:166.20 },
+  { ticker:'AVGO', last:210.30, chg:-0.0093, vol:12_002_000, high:213.80, low:209.50 },
+  { ticker:'MU',   last: 98.72, chg: 0.0421, vol:19_837_000, high:100.10, low: 97.30 },
+  { ticker:'INTC', last: 22.58, chg:-0.0215, vol:45_992_000, high: 23.20, low: 22.30 },
+  { ticker:'QCOM', last:156.80, chg: 0.0068, vol: 8_774_000, high:157.90, low:155.10 },
+  { ticker:'AMAT', last:178.50, chg: 0.0143, vol:10_209_000, high:180.00, low:177.20 },
+  { ticker:'KLAC', last:625.40, chg:-0.0055, vol: 1_437_000, high:630.10, low:622.50 },
+  { ticker:'LRCX', last:685.90, chg: 0.0212, vol: 1_882_000, high:690.00, low:680.10 },
+  { ticker:'TSM',  last:178.65, chg: 0.0337, vol:14_553_000, high:180.00, low:177.00 },
+];
+
+const Quotes = () => {
+  const [q, setQ] = useState(MOCK_QUOTES);
+  const [loading, setLoading] = useState(false);
+
+  const refresh = async () => {
+    setLoading(true);
+    try {
+      const { data } = await API.get('/quotes');
+      if (Array.isArray(data)) setQ(data);
+    } catch { /* use mock */ }
+    finally { setLoading(false); }
+  };
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="section-heading">Stock Quotes</h1>
+          <p className="text-xs text-[var(--color-secondary)] mt-1">Semiconductor universe / Last update: just now</p>
+        </div>
+        <button onClick={refresh} disabled={loading} className="btn-ghost text-xs gap-1.5">
+          <RefreshCw size={13} className={loading ? 'animate-spin' : ''} />
+          Refresh
+        </button>
+      </div>
+
+      <div className="grid grid-cols-2 xl:grid-cols-4 gap-3">
+        <StatCard label="Universe" value={String(q.length)} sub="tickers" />
+        <StatCard label="Gainers" value={String(q.filter(r=>r.chg>0).length)} up={true} />
+        <StatCard label="Losers"  value={String(q.filter(r=>r.chg<0).length)} up={false} />
+        <StatCard label="Avg Chg" value={fmtPct(q.reduce((s,r)=>s+r.chg,0)/q.length)}
+          up={q.reduce((s,r)=>s+r.chg,0)>0} />
+      </div>
+
+      <div className="glass-card overflow-hidden">
+        <table className="data-table">
+          <thead>
+            <tr>
+              <th>Ticker</th>
+              <th className="text-right">Last</th>
+              <th className="text-right">Chg %</th>
+              <th className="text-right">High</th>
+              <th className="text-right">Low</th>
+              <th className="text-right">Volume</th>
+            </tr>
+          </thead>
+          <tbody>
+            {q.map(row => (
+              <tr key={row.ticker}>
+                <td>
+                  <span className="font-semibold text-[var(--color-accent-bright)]">{row.ticker}</span>
+                </td>
+                <td className="text-right font-semibold">${fmt(row.last)}</td>
+                <td className={`text-right font-semibold ${clsPnl(row.chg)}`}>
+                  <span className="flex items-center justify-end gap-0.5">
+                    <PnlArrow v={row.chg} />
+                    {fmtPct(row.chg)}
+                  </span>
+                </td>
+                <td className="text-right text-[var(--color-secondary)]">${fmt(row.high)}</td>
+                <td className="text-right text-[var(--color-secondary)]">${fmt(row.low)}</td>
+                <td className="text-right text-[var(--color-secondary)]">{(row.vol/1e6).toFixed(1)}M</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+};
+
+// ── Page: History ─────────────────────────────────────────────────────────────
+
+const TICKERS_LIST = ['NVDA','AMD','MU','AVGO','INTC','QCOM','AMAT','KLAC','LRCX','TSM'];
+
+function genHistory(ticker: string) {
+  // Deterministic seed-ish price per ticker
+  const seeds: Record<string, number> = { NVDA:80, AMD:120, MU:60, AVGO:180, INTC:35,
+    QCOM:140, AMAT:160, KLAC:560, LRCX:610, TSM:140 };
+  let price = seeds[ticker] ?? 80;
+  return Array.from({ length: 90 }, (_, i) => {
+    price = price * (1 + (Math.random() - 0.47) * 0.025);
+    const d = new Date(Date.now() - (89 - i) * 86400000);
+    return {
+      date: `${d.getMonth()+1}/${d.getDate()}`,
+      close: +price.toFixed(2),
+      volume: Math.round(Math.random() * 30e6 + 5e6),
+    };
+  });
+}
+
+type StockBar = {
+  trade_date: string;
+  open: number | null;
+  high: number | null;
+  low: number | null;
+  close: number | null;
+  volume: number | null;
+  vwap: number | null;
+  daily_return: number | null;
+  zscore_20: number | null;
+  zscore_ret_20: number | null;
+  ma_20: number | null;
+  ma_50: number | null;
+  vwap_20: number | null;
+};
+
+type StockHistoryResponse = {
+  ticker: string;
+  period: string;
+  latest: StockBar;
+  metrics: {
+    period_return: number | null;
+    high: number | null;
+    low: number | null;
+    avg_volume: number | null;
+  };
+  series: StockBar[];
+};
+
+type TickerMeta = { ticker: string; rows: number; first_date: string; last_date: string };
+
+const PERIODS = [
+  { label: '1M', value: '1m' },
+  { label: '3M', value: '3m' },
+  { label: '6M', value: '6m' },
+  { label: '1Y', value: '1y' },
+  { label: '2Y', value: '2y' },
+];
+
+const History = () => {
+  const [ticker, setTicker] = useState('NVDA');
+  const [period, setPeriod] = useState('1y');
+  const [tickers, setTickers] = useState<TickerMeta[]>([]);
+  const [history, setHistory] = useState<StockHistoryResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    API.get('/visualizations/tickers')
+      .then(({ data }) => {
+        if (Array.isArray(data.tickers)) setTickers(data.tickers);
+      })
+      .catch(() => setTickers([]));
+  }, []);
+
+  useEffect(() => {
+    setLoading(true);
+    setError(null);
+    API.get('/visualizations/stock-history', { params: { ticker, period } })
+      .then(({ data }) => setHistory(data))
+      .catch(() => {
+        setHistory(null);
+        setError('Could not load daily bars from the visualization API.');
+      })
+      .finally(() => setLoading(false));
+  }, [ticker, period]);
+
+  const data = history?.series ?? [];
+  const latest = history?.latest;
+  const ret = history?.metrics.period_return ?? null;
+  const isUp = (ret ?? 0) >= 0;
+  const accentColor = isUp ? '#34D399' : '#F87171';
+  const axisDates = data.map(d => d.trade_date);
+
+  const tooltip = {
+    trigger: 'axis',
+    backgroundColor: 'rgba(24,27,32,0.98)',
+    borderColor: '#32363D',
+    textStyle: { color: '#F3F1EA', fontSize: 12 },
+  } as const;
+
+  const priceOption: ChartOption = {
+    animation: false,
+    color: ['#43D19E', '#FF727F', '#D6B65A', '#C7CBD1'],
+    tooltip: { ...tooltip, axisPointer: { type: 'cross' } },
+    grid: { top: 24, right: 28, bottom: 38, left: 54 },
+    xAxis: {
+      type: 'category',
+      data: axisDates,
+      axisLine: { lineStyle: { color: chartGrid } },
+      axisLabel: { color: chartText, fontSize: 10 },
+    },
+    yAxis: {
+      type: 'value',
+      scale: true,
+      axisLabel: { color: chartText, formatter: '${value}' },
+      splitLine: { lineStyle: { color: chartGrid } },
+    },
+    dataZoom: [{ type: 'inside' }, { type: 'slider', height: 18, bottom: 6, borderColor: 'rgba(214,182,90,0.24)' }],
+    series: [
+      {
+        name: 'OHLC',
+        type: 'candlestick',
+        data: data.map(d => [d.open, d.close, d.low, d.high]),
+        itemStyle: {
+          color: '#34D399',
+          color0: '#F87171',
+          borderColor: '#34D399',
+          borderColor0: '#F87171',
+        },
+      },
+      {
+        name: 'MA 20',
+        type: 'line',
+        data: data.map(d => d.ma_20),
+        smooth: true,
+        showSymbol: false,
+        lineStyle: { width: 1.3, color: '#D6B65A' },
+      },
+      {
+        name: 'VWAP 20',
+        type: 'line',
+        data: data.map(d => d.vwap_20),
+        smooth: true,
+        showSymbol: false,
+        lineStyle: { width: 1.2, color: '#C7CBD1' },
+      },
+    ],
+  };
+
+  const volumeOption: ChartOption = {
+    animation: false,
+    tooltip,
+    grid: { top: 12, right: 24, bottom: 24, left: 54 },
+    xAxis: { type: 'category', data: axisDates, axisLabel: { show: false }, axisLine: { lineStyle: { color: chartGrid } } },
+    yAxis: {
+      type: 'value',
+      axisLabel: { color: chartText, formatter: (v: number) => `${(v / 1_000_000).toFixed(0)}M` },
+      splitLine: { lineStyle: { color: chartGrid } },
+    },
+    series: [{
+      name: 'Volume',
+      type: 'bar',
+      data: data.map(d => d.volume),
+      itemStyle: { color: 'rgba(214,182,90,0.42)', borderRadius: [2, 2, 0, 0] },
+    }],
+  };
+
+  const zscoreOption: ChartOption = {
+    animation: false,
+    tooltip,
+    grid: { top: 18, right: 24, bottom: 28, left: 44 },
+    xAxis: { type: 'category', data: axisDates, axisLabel: { color: chartText, fontSize: 10 }, axisLine: { lineStyle: { color: chartGrid } } },
+    yAxis: { type: 'value', axisLabel: { color: chartText }, splitLine: { lineStyle: { color: chartGrid } } },
+    series: [{
+      name: 'Price Z 20',
+      type: 'line',
+      data: data.map(d => d.zscore_20),
+      showSymbol: false,
+      lineStyle: { width: 1.4, color: accentColor },
+      markLine: {
+        symbol: 'none',
+        label: { color: chartText },
+        lineStyle: { color: 'rgba(248,113,113,0.5)', type: 'dashed' },
+        data: [{ yAxis: 3 }, { yAxis: -3 }],
+      },
+    }],
+  };
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-between flex-wrap gap-3">
+        <div>
+          <h1 className="section-heading">Price History</h1>
+          <p className="text-xs text-[var(--color-secondary)] mt-1">Daily OHLCV, VWAP and silver-layer z-scores from DuckDB</p>
+        </div>
+        <div className="flex items-center gap-2">
+          <label htmlFor="history-ticker" className="sr-only">Ticker</label>
+          <select id="history-ticker" value={ticker} onChange={e=>setTicker(e.target.value)}
+            className="glass-input px-3 py-1.5 text-sm text-[var(--color-primary)] outline-none cursor-pointer">
+            {(tickers.length ? tickers.map(t => t.ticker) : TICKERS_LIST).map(t=><option key={t} value={t}>{t}</option>)}
+          </select>
+          {PERIODS.map(p=>(
+            <button key={p.value} onClick={()=>setPeriod(p.value)}
+              aria-label={`${p.label} history period`}
+              aria-pressed={period === p.value}
+              className={`px-3 py-1.5 text-xs rounded-md transition-all ${period===p.value
+                ? 'bg-[var(--color-accent)] text-white'
+                : 'btn-ghost'}`}>{p.label}</button>
+          ))}
+        </div>
+      </div>
+
+      <div className="grid grid-cols-2 xl:grid-cols-4 gap-3">
+        <StatCard label="Current" value={loading ? 'Loading' : `$${fmt(latest?.close)}`} />
+        <StatCard label={`${period.toUpperCase()} Return`} value={fmtPct(ret)} up={ret == null ? null : isUp} />
+        <StatCard label="Period High" value={`$${fmt(history?.metrics.high)}`} />
+        <StatCard label="Avg Volume"  value={history?.metrics.avg_volume == null ? '-' : `${(history.metrics.avg_volume/1e6).toFixed(1)}M`} />
+      </div>
+
+      {error && <div className="glass-card p-4 text-sm text-[var(--color-bearish)]">{error}</div>}
+
+      <div className="glass-card p-4">
+        <p className="text-sm font-semibold mb-4">{ticker} · {period.toUpperCase()} OHLC</p>
+        <ChartPanel option={priceOption} height={340} label={`${ticker} ${period.toUpperCase()} OHLC price chart`} />
+      </div>
+
+      <div className="glass-card p-4">
+        <p className="text-sm font-semibold mb-4">Volume</p>
+        <ChartPanel option={volumeOption} height={120} label={`${ticker} trading volume chart`} />
+      </div>
+
+      <div className="glass-card p-4">
+        <p className="text-sm font-semibold mb-4">20D Price Z-Score</p>
+        <ChartPanel option={zscoreOption} height={180} label={`${ticker} 20-day price z-score chart`} />
+      </div>
+    </div>
+  );
+};
+
+// ── Page: Polygon OHLCV ───────────────────────────────────────────────────────
+
+const Polygon = () => {
+  const [ticker, setTicker] = useState('NVDA');
+  // Memoize so OHLC values don't re-randomize on every render
+  const rows = useMemo(() => genHistory(ticker).slice(-20).reverse().map(row => {
+    const o = row.close * (1 - Math.random()*0.01);
+    const h = row.close * (1 + Math.random()*0.015);
+    const l = row.close * (1 - Math.random()*0.015);
+    return { ...row, open: o, high: h, low: l, up: row.close > o };
+  }), [ticker]);
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="section-heading">Polygon OHLCV</h1>
+          <p className="text-xs text-[var(--color-secondary)] mt-1">Bronze-layer daily bars / equity.duckdb to polygon_bars</p>
+        </div>
+        <label htmlFor="polygon-ticker" className="sr-only">Polygon ticker</label>
+        <select id="polygon-ticker" value={ticker} onChange={e=>setTicker(e.target.value)}
+          className="glass-input px-3 py-1.5 text-sm text-[var(--color-primary)] outline-none">
+          {TICKERS_LIST.map(t=><option key={t} value={t}>{t}</option>)}
+        </select>
+      </div>
+
+      <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
+        <StatCard label="Bronze Rows" value="2,996,665" sub="polygon_bars total" />
+        <StatCard label="Day Bars" value="2021 - Jul 2026" sub="45 tickers" />
+        <StatCard label="Minute Bars" value="5wk stale" sub="92 tickers / needs refresh" up={false} />
+      </div>
+
+      <div className="glass-card overflow-hidden">
+        <table className="data-table">
+          <thead>
+            <tr>
+              <th>Date</th>
+              <th className="text-right">Open</th>
+              <th className="text-right">High</th>
+              <th className="text-right">Low</th>
+              <th className="text-right">Close</th>
+              <th className="text-right">Volume</th>
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((row, i) => (
+              <tr key={i}>
+                <td className="text-[var(--color-secondary)]">{row.date}</td>
+                <td className="text-right">${fmt(row.open)}</td>
+                <td className="text-right text-[var(--color-bullish)]">${fmt(row.high)}</td>
+                <td className="text-right text-[var(--color-bearish)]">${fmt(row.low)}</td>
+                <td className={`text-right font-semibold ${row.up ? 'text-[var(--color-bullish)]' : 'text-[var(--color-bearish)]'}`}>
+                  ${fmt(row.close)}
+                </td>
+                <td className="text-right text-[var(--color-secondary)]">{(row.volume/1e6).toFixed(1)}M</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+};
+
+// ── Page: Options Chain ───────────────────────────────────────────────────────
+
+function genOptions(underlying: number) {
+  const strikes = [-15,-10,-5,0,5,10,15].map(d => Math.round(underlying + d));
+  return strikes.map(K => {
+    const iv_c = 0.25 + (K < underlying ? 0.05 : 0) + Math.random()*0.05;
+    const iv_p = iv_c + 0.02 + Math.random()*0.03;
+    return {
+      strike: K,
+      call_iv: iv_c, call_delta: +(0.45 + (underlying - K) * 0.02).toFixed(3),
+      call_gamma: +(0.02 + Math.random()*0.01).toFixed(4),
+      call_theta: +(-0.04 - Math.random()*0.02).toFixed(4),
+      call_vol: Math.round(Math.random()*5000),
+      put_iv: iv_p, put_delta: +(-(0.55 - (underlying - K) * 0.02)).toFixed(3),
+      put_gamma: +(0.02 + Math.random()*0.01).toFixed(4),
+      put_theta: +(-0.04 - Math.random()*0.02).toFixed(4),
+      put_vol: Math.round(Math.random()*5000),
+      atm: Math.abs(K - underlying) < 6,
+    };
+  });
+}
+
+const Options = () => {
+  const [ticker, setTicker] = useState('NVDA');
+  const PRICES: Record<string,number> = { NVDA:131.20, AMD:168.45, MU:98.72, AVGO:210.30 };
+  const underlying = PRICES[ticker] ?? 100;
+  const rows = useMemo(() => genOptions(underlying), [underlying]);
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="section-heading">Options Chain</h1>
+          <p className="text-xs text-[var(--color-secondary)] mt-1">Silver-layer greeks / BSM IV / 7.1M rows</p>
+        </div>
+        <label htmlFor="options-ticker" className="sr-only">Options ticker</label>
+        <select id="options-ticker" value={ticker} onChange={e=>setTicker(e.target.value)}
+          className="glass-input px-3 py-1.5 text-sm text-[var(--color-primary)] outline-none">
+          {['NVDA','AMD','MU','AVGO'].map(t=><option key={t}>{t}</option>)}
+        </select>
+      </div>
+
+      <div className="grid grid-cols-2 xl:grid-cols-4 gap-3">
+        <StatCard label="Underlying" value={`$${fmt(underlying)}`} />
+        <StatCard label="Option Bars" value="7,100,137" sub="Jul 2024 - Jul 2026" />
+        <StatCard label="Contracts" value="303,076" sub="unique" />
+        <StatCard label="Silver Rows" value="7.1M greeks" up={true} />
+      </div>
+
+      <div className="glass-card overflow-x-auto">
+        <div className="px-4 py-2 border-b border-[var(--color-border)] flex gap-8 text-xs font-semibold text-[var(--color-secondary)]">
+          <span className="flex-1 text-center">CALLS</span>
+          <span className="w-20 text-center">STRIKE</span>
+          <span className="flex-1 text-center">PUTS</span>
+        </div>
+        <table className="data-table">
+          <thead>
+            <tr>
+              <th>IV</th><th><abbr title="Delta">Δ</abbr></th><th><abbr title="Gamma">Γ</abbr></th><th><abbr title="Theta">Θ</abbr></th><th className="text-right">Vol</th>
+              <th className="text-center w-20">Strike</th>
+              <th>IV</th><th><abbr title="Delta">Δ</abbr></th><th><abbr title="Gamma">Γ</abbr></th><th><abbr title="Theta">Θ</abbr></th><th className="text-right">Vol</th>
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map(r => (
+              <tr key={r.strike} className={r.atm ? 'bg-[rgba(214,182,90,0.08)]' : ''}>
+                <td className="text-[var(--color-accent-bright)]">{(r.call_iv*100).toFixed(1)}%</td>
+                <td>{r.call_delta}</td>
+                <td className="text-[var(--color-secondary)]">{r.call_gamma}</td>
+                <td className="text-[var(--color-bearish)]">{r.call_theta}</td>
+                <td className="text-right text-[var(--color-secondary)]">{r.call_vol.toLocaleString()}</td>
+                <td className="text-center font-bold text-[var(--color-primary)]">
+                  {r.atm && <span className="badge badge-purple mr-1 text-[0.6rem]">ATM</span>}
+                  ${r.strike}
+                </td>
+                <td className="text-[var(--color-accent-bright)]">{(r.put_iv*100).toFixed(1)}%</td>
+                <td>{r.put_delta}</td>
+                <td className="text-[var(--color-secondary)]">{r.put_gamma}</td>
+                <td className="text-[var(--color-bearish)]">{r.put_theta}</td>
+                <td className="text-right text-[var(--color-secondary)]">{r.put_vol.toLocaleString()}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+};
+
+// ── Page: Calculator ──────────────────────────────────────────────────────────
+
+type CalcForm = { shares: number; price: number; spread: number; impact: number; fee_per_share: number; rounds: number; };
+type CalcFormKey = keyof CalcForm;
+
+// Extracted to module scope — avoids remounting on every Calculator render
+const CalcField = ({ label, k, step = 1, prefix = '', form, setForm }: {
+  label: string; k: CalcFormKey; step?: number; prefix?: string;
+  form: CalcForm; setForm: React.Dispatch<React.SetStateAction<CalcForm>>;
+}) => (
+  <div>
+    <label htmlFor={`calc-${k}`} className="block text-xs text-[var(--color-secondary)] mb-1">{label}</label>
+    <div className="glass-input flex items-center px-3 py-2">
+      {prefix && <span className="text-[var(--color-muted)] mr-1 text-sm">{prefix}</span>}
+      <input id={`calc-${k}`} type="number" step={step} value={form[k]}
+        onChange={e => setForm(f => ({ ...f, [k]: parseFloat(e.target.value) || 0 }))}
+        className="flex-1 bg-transparent text-sm text-[var(--color-primary)] outline-none w-full" />
+    </div>
+  </div>
+);
+
+const Calculator = () => {
+  const [form, setForm] = useState<CalcForm>({
+    shares: 10000, price: 131.20, spread: 0.02,
+    impact: 0.1, fee_per_share: 0.005, rounds: 1,
+  });
+  const notional    = form.shares * form.price;
+  const spread_cost = form.shares * form.spread * 0.5;
+  const impact_cost = notional * (form.impact / 100);
+  const fees        = form.shares * form.fee_per_share;
+  const one_way     = spread_cost + impact_cost + fees;
+  const round_trip  = one_way * 2 * form.rounds;
+  const bps         = (round_trip / notional) * 10000;
+
+  return (
+    <div className="max-w-2xl space-y-6">
+      <div>
+        <h1 className="section-heading">Cost Calculator</h1>
+        <p className="text-xs text-[var(--color-secondary)] mt-1">Round-trip slippage model / market impact + spread + fees</p>
+      </div>
+
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4 glass-card p-5">
+        <CalcField label="Shares" k="shares" form={form} setForm={setForm} />
+        <CalcField label="Price per Share" k="price" step={0.01} prefix="$" form={form} setForm={setForm} />
+        <CalcField label="Bid-Ask Spread" k="spread" step={0.001} prefix="$" form={form} setForm={setForm} />
+        <CalcField label="Market Impact (%)" k="impact" step={0.01} form={form} setForm={setForm} />
+        <CalcField label="Fee per Share" k="fee_per_share" step={0.001} prefix="$" form={form} setForm={setForm} />
+        <CalcField label="Round Trips" k="rounds" form={form} setForm={setForm} />
+      </div>
+
+      <div className="grid grid-cols-2 gap-3">
+        <StatCard label="Notional"      value={`$${fmt(notional,0)}`} />
+        <StatCard label="Spread Cost"   value={`$${fmt(spread_cost)}`} />
+        <StatCard label="Market Impact" value={`$${fmt(impact_cost)}`} />
+        <StatCard label="Fees"          value={`$${fmt(fees)}`} />
+      </div>
+
+      <div className="glass-card p-5 accent-glow">
+        <p className="text-xs text-[var(--color-secondary)] mb-2">Total Round-Trip Cost</p>
+        <p className="text-3xl font-bold text-[var(--color-accent-bright)]">${fmt(round_trip)}</p>
+        <p className="text-sm text-[var(--color-secondary)] mt-1">
+          {fmt(bps, 1)} bps / {((round_trip/notional)*100).toFixed(4)}% of notional
+        </p>
+      </div>
+    </div>
+  );
+};
+
+// ── Page: ETL Health ────────────���─────────────────────────────────────────────
+
+// Hoisted — avoids recreation on every Health render
+const PIPELINE_STATUS = [
+  { label:'Bronze / day bars',       ok:true  as true  },
+  { label:'Bronze / option bars',    ok:true  as true  },
+  { label:'Bronze / minute bars',    ok:null  as null  },
+  { label:'Silver / stock features', ok:true  as true  },
+  { label:'Silver / option greeks',  ok:true  as true  },
+  { label:'Silver / positioning',    ok:true  as true  },
+  { label:'EDGAR',                   ok:false as false },
+  { label:'Embeddings',              ok:false as false },
+  { label:'Gold layer',              ok:false as false },
+];
+
+const NEXT_ACTIONS = [
+  { icon: RefreshCw, label: 'Sync minute bars',  cmd: 'python main.py --job polygon-bars' },
+  { icon: Database,  label: 'Load EDGAR data',   cmd: 'docker compose run --rm edgar_sync' },
+  { icon: Cpu,       label: 'Run embeddings',    cmd: 'python main.py --job embed-tickers' },
+  { icon: Zap,       label: 'Build gold layer',  cmd: 'etl/gold_*.py (not built yet)' },
+];
+
+const TABLE_COUNTS = [
+  { name:'polygon_bars',              rows: 2_996_665, ok: true,  note:'Day bars current through Jul 2' },
+  { name:'polygon_option_bars',       rows: 7_100_137, ok: true,  note:'Options current through Jul 2' },
+  { name:'silver_stock_features',     rows:    42_573, ok: true,  note:'All 32 semi tickers' },
+  { name:'silver_option_greeks',      rows: 7_100_137, ok: true,  note:'BSM IV computed' },
+  { name:'silver_option_positioning', rows:    16_452, ok: true,  note:'Put/call ratios' },
+  { name:'polygon_tickers',           rows:    12_311, ok: true,  note:'Reference data' },
+  { name:'cot_reports',               rows:     2_009, ok: true,  note:'CFTC COT' },
+  { name:'edgar_facts',               rows:         0, ok: false, note:'Pending edgar_sync run' },
+  { name:'edgar_filings',             rows:         0, ok: false, note:'Run edgar-filings job' },
+  { name:'edgar_embeddings',          rows:         0, ok: false, note:'Pending edgar_sync run' },
+  { name:'ticker_embeddings',         rows:         0, ok: false, note:'Run embed-tickers job' },
+  { name:'stock_quotes',              rows:         0, ok: null,  note:'Live IBKR feed (optional)' },
+];
+
+const Health = () => (
+  <div className="space-y-6">
+    <div>
+      <h1 className="section-heading">ETL Health</h1>
+      <p className="text-xs text-[var(--color-secondary)] mt-1">Data freshness / row counts / pipeline status</p>
+    </div>
+
+    <div className="grid grid-cols-2 xl:grid-cols-4 gap-3">
+      <StatCard label="DB Size"    value="3.2 GB"  sub="equity.duckdb" />
+      <StatCard label="Total Rows" value="17.3M"   sub="across all tables" />
+      <StatCard label="Healthy"    value={String(TABLE_COUNTS.filter(t=>t.ok===true).length)}  up={true} />
+      <StatCard label="Missing"    value={String(TABLE_COUNTS.filter(t=>t.ok===false).length)} up={false} />
+    </div>
+
+    <div className="glass-card p-5">
+      <p className="text-sm font-semibold mb-4">Medallion Pipeline</p>
+      <div className="flex items-center gap-2 flex-wrap">
+        {PIPELINE_STATUS.map(s => (
+          <div key={s.label} className="flex items-center gap-1.5 glass-card px-3 py-1.5">
+            {s.ok === true  && <CheckCircle size={12} className="text-[var(--color-bullish)]" />}
+            {s.ok === false && <XCircle     size={12} className="text-[var(--color-bearish)]" />}
+            {s.ok === null  && <AlertCircle size={12} className="text-yellow-400" />}
+            <span className="text-xs">{s.label}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+
+    <div className="glass-card overflow-hidden">
+      <table className="data-table">
+        <thead>
+          <tr>
+            <th>Table</th>
+            <th className="text-right">Rows</th>
+            <th>Status</th>
+            <th>Note</th>
+          </tr>
+        </thead>
+        <tbody>
+          {TABLE_COUNTS.map(t => (
+            <tr key={t.name}>
+              <td className="font-mono text-xs text-[var(--color-accent-bright)]">{t.name}</td>
+              <td className="text-right">{t.rows.toLocaleString()}</td>
+              <td>
+                {t.ok === true  && <span className="badge badge-green">OK</span>}
+                {t.ok === false && <span className="badge badge-red">Missing</span>}
+                {t.ok === null  && <span className="badge badge-muted">Optional</span>}
+              </td>
+              <td className="text-[var(--color-secondary)] text-xs">{t.note}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+
+    <div className="glass-card p-5 space-y-2">
+      <p className="text-sm font-semibold mb-3">Next actions</p>
+      {NEXT_ACTIONS.map(a => (
+        <div key={a.label} className="flex items-center gap-3 py-2 border-b border-[var(--color-border)] last:border-0">
+          <a.icon size={14} className="text-[var(--color-accent)] shrink-0" />
+          <span className="text-sm">{a.label}</span>
+          <code className="ml-auto text-xs font-mono text-[var(--color-secondary)] glass-card px-2 py-0.5">{a.cmd}</code>
+        </div>
+      ))}
+    </div>
+  </div>
+);
+
+// ── App root ──────────────────────────────────────────────────────────────────
+
+export default function App() {
+  return (
+    <Router>
+      <Layout>
+        <Routes>
+          <Route path="/"            element={<Navigate to="/chat" replace />} />
+          <Route path="/chat"        element={<Chat />} />
+          <Route path="/quotes"      element={<Quotes />} />
+          <Route path="/history"     element={<History />} />
+          <Route path="/polygon"     element={<Polygon />} />
+          <Route path="/options"     element={<Options />} />
+          <Route path="/calculator"  element={<Calculator />} />
+          <Route path="/health"      element={<Health />} />
+          <Route path="/methodology" element={<Methodology />} />
+          <Route path="/analytics"   element={<Analytics />} />
+          <Route path="/audit"       element={<AuditLog />} />
+          <Route path="/system"      element={<SystemOverview />} />
+        </Routes>
+      </Layout>
+    </Router>
+  );
+}

frontend/src/ResearchOps.tsx

@@ -0,0 +1,277 @@
+import { useEffect, useMemo, useState } from 'react';
+import axios from 'axios';
+import { AlertCircle, CheckCircle, Clock3, Database, ShieldCheck, XCircle } from 'lucide-react';
+import { ChartPanel } from './components/ChartPanel';
+import type { ChartOption } from './components/ChartPanel';
+
+const API = axios.create({ baseURL: '/api', timeout: 60000 });
+const chartText = '#B8BDC5';
+const chartGrid = 'rgba(199,203,209,0.10)';
+
+type SeriesProfile = {
+  name: string;
+  stage: string;
+  available: boolean;
+  status: string;
+  rows: number;
+  symbols: number | null;
+  first_timestamp: string | null;
+  last_timestamp: string | null;
+  null_timestamps: number | null;
+  duplicate_points: number | null;
+  coverage: { period: string; rows: number }[];
+};
+
+type SlippageTicker = {
+  ticker: string;
+  trades: number;
+  gross_pnl: number;
+  slippage_cost: number;
+  commission_cost: number;
+  total_cost: number;
+  net_pnl: number;
+};
+
+const fmt = (value: number | null | undefined, digits = 0) =>
+  value == null ? '-' : value.toLocaleString('en-US', { maximumFractionDigits: digits });
+
+const money = (value: number | null | undefined) =>
+  value == null ? '-' : value.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 2 });
+
+const PageTitle = ({ title, subtitle }: { title: string; subtitle: string }) => (
+  <div>
+    <h1 className="section-heading">{title}</h1>
+    <p className="text-xs text-[var(--color-secondary)] mt-1">{subtitle}</p>
+  </div>
+);
+
+const Stat = ({ label, value, sub }: { label: string; value: string; sub?: string }) => (
+  <div className="stat-card min-w-0">
+    <p className="text-[0.7rem] font-semibold uppercase text-[var(--color-secondary)] mb-1">{label}</p>
+    <p className="text-xl font-semibold tabular-nums truncate">{value}</p>
+    {sub && <p className="text-xs text-[var(--color-muted)] mt-1 truncate">{sub}</p>}
+  </div>
+);
+
+const Loading = () => <div className="glass-card p-6 text-sm text-[var(--color-secondary)]">Loading research data...</div>;
+
+const ErrorState = ({ message }: { message: string }) => (
+  <div className="glass-card p-5 flex items-center gap-3 text-sm text-[var(--color-bearish)]">
+    <AlertCircle size={16} /> {message}
+  </div>
+);
+
+export function Methodology() {
+  const [data, setData] = useState<any>(null);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    API.get('/research/methodology').then(response => setData(response.data)).catch(error => setError(error.message));
+  }, []);
+  if (error) return <ErrorState message={error} />;
+  if (!data) return <Loading />;
+
+  return (
+    <div className="space-y-6">
+      <PageTitle title="Methodology" subtitle="Point-in-time controls for market data, research, and execution costs" />
+      <div className="grid grid-cols-1 xl:grid-cols-2 gap-3">
+        {data.principles.map((item: any, index: number) => (
+          <section key={item.id} className="glass-card p-5">
+            <div className="flex items-start gap-3">
+              <span className="w-7 h-7 shrink-0 rounded-md bg-[var(--color-accent-dim)] text-[var(--color-accent-bright)] flex items-center justify-center text-xs font-semibold">
+                {index + 1}
+              </span>
+              <div className="min-w-0">
+                <h2 className="text-sm font-semibold">{item.title}</h2>
+                <p className="text-sm leading-6 text-[var(--color-secondary)] mt-2">{item.body}</p>
+                <div className="flex flex-wrap gap-2 mt-4">
+                  {item.controls.map((control: string) => <span key={control} className="badge badge-muted">{control}</span>)}
+                </div>
+              </div>
+            </div>
+          </section>
+        ))}
+      </div>
+      <section className="glass-card p-5">
+        <h2 className="text-sm font-semibold mb-4">Slippage cost contract</h2>
+        <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-5 gap-3">
+          {Object.entries(data.slippage_model).map(([label, value]) => (
+            <div key={label} className="glass-sm p-3 min-w-0">
+              <p className="text-[0.68rem] uppercase font-semibold text-[var(--color-secondary)]">{label.replaceAll('_', ' ')}</p>
+              <p className="text-xs leading-5 mt-2">{String(value)}</p>
+            </div>
+          ))}
+        </div>
+      </section>
+    </div>
+  );
+}
+
+export function Analytics() {
+  const [analytics, setAnalytics] = useState<any>(null);
+  const [slippage, setSlippage] = useState<any>(null);
+  const [byTicker, setByTicker] = useState<SlippageTicker[]>([]);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    Promise.all([
+      API.get('/research/analytics/summary'),
+      API.get('/research/slippage/summary'),
+      API.get('/research/slippage/by-ticker'),
+    ]).then(([a, s, t]) => {
+      setAnalytics(a.data);
+      setSlippage(s.data);
+      setByTicker(t.data.tickers || []);
+    }).catch(error => setError(error.message));
+  }, []);
+
+  const coverageOption = useMemo<ChartOption>(() => ({
+    color: ['#D6B65A', '#C7CBD1', '#43D19E', '#E7C96C', '#FF727F', '#8D949E'],
+    tooltip: { trigger: 'axis', backgroundColor: '#181B20', borderColor: '#32363D', textStyle: { color: '#F3F1EA' } },
+    legend: { type: 'scroll', textStyle: { color: chartText }, top: 0 },
+    grid: { left: 58, right: 20, top: 48, bottom: 42 },
+    xAxis: { type: 'time', axisLabel: { color: chartText }, axisLine: { lineStyle: { color: chartGrid } } },
+    yAxis: { type: 'value', name: 'rows / month', nameTextStyle: { color: chartText }, axisLabel: { color: chartText }, splitLine: { lineStyle: { color: chartGrid } } },
+    series: (analytics?.tables || []).filter((table: SeriesProfile) => table.coverage.length).map((table: SeriesProfile) => ({
+      name: table.name,
+      type: 'line',
+      showSymbol: false,
+      smooth: false,
+      data: table.coverage.map(point => [point.period, point.rows]),
+    })),
+  }), [analytics]);
+
+  const costOption = useMemo<ChartOption>(() => ({
+    color: ['#D6B65A', '#C7CBD1'],
+    tooltip: { trigger: 'axis', axisPointer: { type: 'shadow' }, backgroundColor: '#181B20', borderColor: '#32363D', textStyle: { color: '#F3F1EA' } },
+    legend: { textStyle: { color: chartText } },
+    grid: { left: 58, right: 20, top: 42, bottom: 42 },
+    xAxis: { type: 'category', data: byTicker.slice(0, 16).map(row => row.ticker), axisLabel: { color: chartText }, axisLine: { lineStyle: { color: chartGrid } } },
+    yAxis: { type: 'value', name: 'USD', nameTextStyle: { color: chartText }, axisLabel: { color: chartText }, splitLine: { lineStyle: { color: chartGrid } } },
+    series: [
+      { name: 'Slippage', type: 'bar', stack: 'cost', data: byTicker.slice(0, 16).map(row => row.slippage_cost) },
+      { name: 'Commission', type: 'bar', stack: 'cost', data: byTicker.slice(0, 16).map(row => row.commission_cost) },
+    ],
+  }), [byTicker]);
+
+  if (error) return <ErrorState message={error} />;
+  if (!analytics || !slippage) return <Loading />;
+  const cost = slippage.summary;
+  return (
+    <div className="space-y-6">
+      <PageTitle title="Research Analytics" subtitle="Coverage, quality, freshness, and execution cost across time-series datasets" />
+      <div className="grid grid-cols-2 xl:grid-cols-4 gap-3">
+        <Stat label="Observed rows" value={fmt(analytics.totals.rows)} />
+        <Stat label="Available tables" value={fmt(analytics.totals.available_tables)} sub={`${analytics.tables.length} tracked`} />
+        <Stat label="Duplicate keys" value={fmt(analytics.totals.tables_with_duplicates)} sub="tables affected" />
+        <Stat label="Null event time" value={fmt(analytics.totals.tables_with_null_time)} sub="tables affected" />
+      </div>
+      <section className="glass-card p-4">
+        <h2 className="text-sm font-semibold mb-2">Monthly data coverage</h2>
+        <ChartPanel option={coverageOption} height={340} label="Monthly data coverage by research table" />
+      </section>
+      <div className="grid grid-cols-1 xl:grid-cols-[1fr_2fr] gap-3">
+        <section className="glass-card p-5">
+          <h2 className="text-sm font-semibold">Execution cost</h2>
+          {slippage.available && cost ? (
+            <div className="grid grid-cols-2 gap-3 mt-4">
+              <Stat label="Gross P&L" value={money(cost.gross_pnl)} />
+              <Stat label="Net P&L" value={money(cost.net_pnl)} />
+              <Stat label="Slippage" value={money(cost.slippage_cost)} />
+              <Stat label="Commission" value={money(cost.commission_cost)} />
+              <Stat label="Total cost" value={money(cost.total_cost)} />
+              <Stat label="Cost drag" value={cost.cost_drag == null ? '-' : `${(cost.cost_drag * 100).toFixed(2)}%`} />
+            </div>
+          ) : <p className="text-sm text-[var(--color-secondary)] mt-4">Gold trade costs are not available yet. This is distinct from a measured zero cost.</p>}
+        </section>
+        <section className="glass-card p-4">
+          <h2 className="text-sm font-semibold mb-2">Cost by ticker</h2>
+          {byTicker.length ? <ChartPanel option={costOption} height={340} label="Slippage and commission costs by ticker" /> : <div className="h-[340px] flex items-center justify-center text-sm text-[var(--color-secondary)]">No cost observations</div>}
+        </section>
+      </div>
+      <section className="glass-card overflow-x-auto">
+        <table className="data-table min-w-[840px]">
+          <thead><tr><th>Dataset</th><th>Stage</th><th className="text-right">Rows</th><th className="text-right">Symbols</th><th>First event</th><th>Latest event</th><th className="text-right">Duplicates</th></tr></thead>
+          <tbody>{analytics.tables.map((table: SeriesProfile) => (
+            <tr key={table.name}>
+              <td className="font-mono text-xs text-[var(--color-accent-bright)]">{table.name}</td><td><span className="badge badge-muted">{table.stage}</span></td>
+              <td className="text-right">{fmt(table.rows)}</td><td className="text-right">{fmt(table.symbols)}</td><td>{table.first_timestamp || '-'}</td><td>{table.last_timestamp || '-'}</td><td className="text-right">{fmt(table.duplicate_points)}</td>
+            </tr>
+          ))}</tbody>
+        </table>
+      </section>
+    </div>
+  );
+}
+
+export function AuditLog() {
+  const [data, setData] = useState<any>(null);
+  const [summary, setSummary] = useState<any>(null);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    Promise.all([API.get('/research/audit'), API.get('/research/audit/summary')])
+      .then(([detail, totals]) => { setData(detail.data); setSummary(totals.data); })
+      .catch(error => setError(error.message));
+  }, []);
+  if (error) return <ErrorState message={error} />;
+  if (!data || !summary) return <Loading />;
+  return (
+    <div className="space-y-6">
+      <PageTitle title="Audit Log" subtitle="ETL run lineage and derived time-series integrity checks" />
+      <div className="grid grid-cols-3 gap-3">
+        <Stat label="Checks passed" value={fmt(summary.checks.passed)} />
+        <Stat label="Checks failed" value={fmt(summary.checks.failed)} />
+        <Stat label="Not applicable" value={fmt(summary.checks.not_applicable)} />
+      </div>
+      <section className="glass-card p-5">
+        <h2 className="text-sm font-semibold mb-4">Data controls</h2>
+        <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-2">
+          {data.checks.map((check: any) => (
+            <div key={`${check.table}-${check.check}`} className="glass-sm p-3 flex items-center gap-3 min-w-0">
+              {check.status === 'pass' ? <CheckCircle size={15} className="text-[var(--color-bullish)] shrink-0" /> : check.status === 'fail' ? <XCircle size={15} className="text-[var(--color-bearish)] shrink-0" /> : <Clock3 size={15} className="text-[var(--color-muted)] shrink-0" />}
+              <div className="min-w-0"><p className="text-xs font-mono truncate">{check.table}</p><p className="text-xs text-[var(--color-secondary)] truncate">{check.check}: {check.value ?? check.status}</p></div>
+            </div>
+          ))}
+        </div>
+      </section>
+      <section className="glass-card overflow-x-auto">
+        <table className="data-table min-w-[900px]">
+          <thead><tr><th>ID</th><th>Run</th><th>Status</th><th className="text-right">Rows</th><th>Started</th><th>Finished</th><th>Message</th></tr></thead>
+          <tbody>{data.runs.map((run: any) => <tr key={run.id}><td>{run.id}</td><td>{run.run_type}</td><td><span className={`badge ${String(run.status).toLowerCase().includes('success') ? 'badge-green' : 'badge-muted'}`}>{run.status}</span></td><td className="text-right">{fmt(run.rows_written)}</td><td>{run.started_at || '-'}</td><td>{run.finished_at || '-'}</td><td className="max-w-[22rem] truncate text-[var(--color-secondary)]">{run.message || '-'}</td></tr>)}</tbody>
+        </table>
+      </section>
+    </div>
+  );
+}
+
+export function SystemOverview() {
+  const [data, setData] = useState<any>(null);
+  const [error, setError] = useState('');
+  useEffect(() => { API.get('/research/system').then(response => setData(response.data)).catch(error => setError(error.message)); }, []);
+  if (error) return <ErrorState message={error} />;
+  if (!data) return <Loading />;
+  return (
+    <div className="space-y-6">
+      <PageTitle title="System Overview" subtitle="Live database inventory and medallion-stage readiness" />
+      <div className="grid grid-cols-2 xl:grid-cols-4 gap-3">
+        <Stat label="Database" value={data.database.ok ? 'Connected' : 'Unavailable'} />
+        <Stat label="Tables" value={fmt(data.database.tables)} />
+        <Stat label="Tracked series" value={fmt(data.tables.length)} />
+        <Stat label="Ready series" value={fmt(data.tables.filter((table: SeriesProfile) => table.status === 'ready').length)} />
+      </div>
+      <section className="grid grid-cols-1 md:grid-cols-3 gap-3">
+        {data.stages.map((stage: any) => (
+          <div key={stage.stage} className="glass-card p-5">
+            <div className="flex items-center justify-between"><div className="flex items-center gap-2"><Database size={16} className="text-[var(--color-accent-bright)]" /><h2 className="text-sm font-semibold capitalize">{stage.stage}</h2></div><span className={`badge ${stage.status === 'ready' ? 'badge-green' : stage.status === 'missing' ? 'badge-red' : 'badge-muted'}`}>{stage.status}</span></div>
+            <p className="text-2xl font-semibold mt-5">{stage.available}<span className="text-sm text-[var(--color-secondary)]"> / {stage.expected}</span></p>
+            <p className="text-xs text-[var(--color-secondary)] mt-2 truncate">Latest: {stage.latest_timestamp || '-'}</p>
+          </div>
+        ))}
+      </section>
+      <section className="glass-card p-5">
+        <div className="flex items-center gap-2 mb-4"><ShieldCheck size={16} className="text-[var(--color-accent-bright)]" /><h2 className="text-sm font-semibold">Tracked datasets</h2></div>
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-2">
+          {data.tables.map((table: SeriesProfile) => <div key={table.name} className="glass-sm p-3 flex items-center justify-between gap-3"><div className="min-w-0"><p className="font-mono text-xs truncate">{table.name}</p><p className="text-xs text-[var(--color-secondary)] mt-1 truncate">{table.last_timestamp || 'No observations'}</p></div><span className={`badge ${table.status === 'ready' ? 'badge-green' : table.status === 'missing' ? 'badge-red' : 'badge-muted'}`}>{table.status}</span></div>)}
+        </div>
+      </section>
+    </div>
+  );
+}

frontend/src/components/ChartPanel.tsx

@@ -0,0 +1,45 @@
+import ReactEChartsCore from 'echarts-for-react/lib/core';
+import { BarChart, CandlestickChart, LineChart } from 'echarts/charts';
+import {
+  DataZoomComponent,
+  GridComponent,
+  LegendComponent,
+  MarkLineComponent,
+  TooltipComponent,
+} from 'echarts/components';
+import * as echarts from 'echarts/core';
+import type { EChartsCoreOption } from 'echarts/core';
+import { CanvasRenderer } from 'echarts/renderers';
+
+echarts.use([
+  BarChart,
+  CandlestickChart,
+  LineChart,
+  CanvasRenderer,
+  DataZoomComponent,
+  GridComponent,
+  LegendComponent,
+  MarkLineComponent,
+  TooltipComponent,
+]);
+
+export type ChartOption = EChartsCoreOption;
+
+export function ChartPanel({ option, height = 320, label = 'Financial data chart' }: {
+  option: ChartOption;
+  height?: number;
+  label?: string;
+}) {
+  return (
+    <div role="img" aria-label={label}>
+      <ReactEChartsCore
+        echarts={echarts}
+        option={option}
+        notMerge
+        lazyUpdate
+        style={{ height, width: '100%' }}
+        opts={{ renderer: 'canvas' }}
+      />
+    </div>
+  );
+}

frontend/src/index.css

@@ -0,0 +1,336 @@
+@import "tailwindcss";
+
+@theme {
+  /* ── Origin-inspired dark purple palette ─────────────────────── */
+  --color-background:        #090A0C;
+  --color-surface:           #111317;
+  --color-surface-elevated:  #181B20;
+  --color-primary:           #F3F1EA;
+  --color-secondary:         #B8BDC5;
+  --color-muted:             #818791;
+  --color-border:            #32363D;
+  --color-border-subtle:     #22262C;
+
+  /* Accent — violet/purple */
+  --color-accent:            #D6B65A;
+  --color-accent-bright:     #F1D77A;
+  --color-accent-fill:       #C9A227;
+  --color-accent-fill-hover: #DEBA3E;
+  --color-accent-ink:        #171205;
+  --color-accent-dim:        rgba(214, 182, 90, 0.14);
+  --color-accent-glow:       rgba(214, 182, 90, 0.2);
+  --color-silver:            #C7CBD1;
+  --color-silver-dim:        #8D949E;
+
+  /* Financial */
+  --color-bullish:           #43D19E;
+  --color-bearish:           #FF727F;
+  --color-neutral:           #A8B0BC;
+
+  --font-sans: "Geist", "Segoe UI Variable", "SF Pro Display", system-ui, -apple-system, sans-serif;
+  --font-serif: "Georgia", "Times New Roman", serif;
+  --font-mono: "JetBrains Mono", "SF Mono", "Geist Mono", "Fira Code", ui-monospace, monospace;
+
+  --radius-xl:  12px;
+  --radius-lg:  12px;
+  --radius-md:  8px;
+  --radius-sm:  6px;
+}
+
+@layer base {
+  html {
+    background-color: var(--color-background);
+    color: var(--color-primary);
+    color-scheme: dark;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  body {
+    font-family: var(--font-sans);
+    letter-spacing: 0;
+    background: var(--color-background);
+  }
+
+  body::before {
+    content: "";
+    position: fixed;
+    inset: 0;
+    z-index: -1;
+    pointer-events: none;
+    opacity: 0.18;
+    background-image:
+      linear-gradient(rgba(255,255,255,0.018) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(255,255,255,0.014) 1px, transparent 1px);
+    background-size: 48px 48px;
+    mask-image: linear-gradient(to bottom, rgba(0,0,0,0.8), transparent 78%);
+  }
+
+  table, .tabular-nums, [class*="price"], [class*="amount"], [class*="value"] { font-variant-numeric: tabular-nums; }
+
+  ::-webkit-scrollbar { width: 5px; height: 5px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: rgba(214,182,90,0.28); border-radius: 3px; }
+  ::-webkit-scrollbar-thumb:hover { background: rgba(214,182,90,0.46); }
+  ::selection { background: var(--color-accent); color: var(--color-background); }
+
+  :where(button, a, input, select, textarea, summary, [role="button"]):focus-visible {
+    outline: 2px solid var(--color-accent);
+    outline-offset: 2px;
+  }
+
+  @media (max-width: 767px) {
+    html { font-size: 16px; }
+    body { -webkit-tap-highlight-color: transparent; }
+    button, [role="button"], a[role="button"] { min-height: 44px; min-width: 44px; }
+    input { font-size: 16px; }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,*::before,*::after { animation-duration:0.01ms !important; animation-iteration-count:1 !important; transition-duration:0.01ms !important; }
+  }
+}
+
+@layer components {
+
+  .skip-link {
+    position: fixed;
+    top: 0.75rem;
+    left: 0.75rem;
+    z-index: 1000;
+    transform: translateY(-160%);
+    border: 1px solid var(--color-accent);
+    border-radius: var(--radius-md);
+    background: var(--color-surface-elevated);
+    color: var(--color-primary);
+    padding: 0.65rem 0.9rem;
+    font-size: 0.875rem;
+    font-weight: 600;
+    transition: transform 0.15s ease;
+  }
+
+  .skip-link:focus { transform: translateY(0); }
+
+  .glass {
+    background: var(--color-surface-elevated);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-lg);
+  }
+
+  .glass-sm {
+    background: var(--color-surface);
+    border: 1px solid var(--color-border-subtle);
+    border-radius: var(--radius-md);
+  }
+
+  .fintech-card,
+  .glass-card {
+    background: var(--color-surface-elevated);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-lg);
+    transition: border-color 0.16s ease, background-color 0.16s ease;
+  }
+  .fintech-card:hover,
+  .glass-card:hover {
+    background: #1A1F28;
+    border-color: #3A4250;
+  }
+
+  .glass-sidebar {
+    background: var(--color-surface);
+    border-right: 1px solid var(--color-border);
+  }
+
+  .glass-header {
+    background: var(--color-surface);
+    border-bottom: 1px solid var(--color-border);
+  }
+
+  .glass-input {
+    background: var(--color-surface-elevated);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    transition: border-color 0.16s ease, box-shadow 0.16s ease;
+  }
+  .glass-input:focus-within {
+    border-color: var(--color-accent);
+    box-shadow: 0 0 0 1px rgba(214,182,90,0.16);
+  }
+
+  .fintech-button,
+  .btn-primary {
+    background: var(--color-accent-fill);
+    color: var(--color-accent-ink);
+    border-radius: var(--radius-lg);
+    font-weight: 600;
+    font-size: 0.875rem;
+    padding: 0.5rem 1.25rem;
+    border: 1px solid var(--color-accent-fill);
+    transition: background-color 0.15s ease, border-color 0.15s ease, box-shadow 0.15s ease, transform 0.15s ease;
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+  }
+  .fintech-button:not(:disabled):hover,
+  .btn-primary:not(:disabled):hover {
+    background: var(--color-accent-fill-hover);
+    border-color: var(--color-accent-fill-hover);
+  }
+  .fintech-button:not(:disabled):active,
+  .btn-primary:not(:disabled):active { transform: translateY(1px) scale(0.98); }
+
+  .fintech-button:disabled,
+  .btn-primary:disabled {
+    background: #242A34;
+    border-color: #353D49;
+    color: #9BA4B1;
+    opacity: 1;
+    cursor: not-allowed;
+  }
+
+  .glass-button,
+  .btn-ghost {
+    background: var(--color-surface-elevated);
+    color: var(--color-secondary);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    font-size: 0.875rem;
+    font-weight: 500;
+    padding: 0.4rem 0.9rem;
+    transition: background-color 0.15s ease, border-color 0.15s ease, color 0.15s ease, transform 0.15s ease;
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+  }
+  .glass-button:hover,
+  .btn-ghost:hover { background: #1D222C; border-color: #3A4250; color: var(--color-primary); }
+  .glass-button:active,
+  .btn-ghost:active { transform: scale(0.98); }
+
+  .nav-item {
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    min-height: 2.5rem;
+    padding: 0.55rem 0.75rem 0.55rem 0.875rem;
+    border-radius: var(--radius-md);
+    font-size: 0.8375rem;
+    font-weight: 500;
+    color: var(--color-secondary);
+    border: 1px solid transparent;
+    transition: color 0.15s ease, background-color 0.15s ease, border-color 0.15s ease;
+    cursor: pointer;
+    background: transparent;
+    width: 100%;
+    text-align: left;
+    text-decoration: none;
+    white-space: nowrap;
+  }
+  .nav-item:hover { color: var(--color-primary); background: #1D222C; }
+  .nav-item.active {
+    background: var(--color-accent-dim);
+    border-color: color-mix(in srgb, var(--color-accent) 22%, transparent);
+    color: var(--color-accent-bright);
+  }
+  .nav-item.active::before {
+    content: "";
+    position: absolute;
+    left: -0.25rem;
+    top: 0.5rem;
+    bottom: 0.5rem;
+    width: 2px;
+    border-radius: 2px;
+    background: var(--color-accent);
+  }
+
+  .stat-card {
+    background: linear-gradient(135deg,rgba(214,182,90,0.08) 0%,rgba(17,19,23,0.96) 70%);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-lg);
+    padding: 1rem 1.25rem;
+    transition: border-color 0.2s;
+  }
+  .stat-card:hover { border-color: rgba(214,182,90,0.3); }
+
+  .data-table { width: 100%; border-collapse: collapse; font-size: 0.84rem; font-variant-numeric: tabular-nums; }
+  .data-table thead th {
+    text-align: left; font-weight: 600; color: var(--color-secondary);
+    text-transform: uppercase; font-size: 0.7rem; letter-spacing: 0.06em;
+    padding: 0.55rem 0.75rem; background: var(--color-surface);
+    border-bottom: 1px solid var(--color-border); white-space: nowrap;
+  }
+  .data-table tbody td {
+    padding: 0.5rem 0.75rem;
+    border-bottom: 1px solid rgba(255,255,255,0.04);
+    color: var(--color-primary); vertical-align: middle;
+  }
+  .data-table tbody tr:hover { background: #1D222C; }
+  .data-table .text-right { text-align: right; }
+
+  .msg-user {
+    background: var(--color-accent-fill);
+    color: var(--color-accent-ink); border-radius: 16px 16px 4px 16px;
+  }
+  .msg-assistant {
+    background: var(--color-surface-elevated);
+    border: 1px solid var(--color-border);
+    border-radius: 16px 16px 16px 4px;
+  }
+
+  .badge {
+    display: inline-flex; align-items: center; gap: 0.3rem;
+    padding: 0.15rem 0.5rem; border-radius: 999px;
+    font-size: 0.7rem; font-weight: 600; letter-spacing: 0.02em;
+  }
+  .badge-green  { background: rgba(52,211,153,0.12);  color: #34D399; border: 1px solid rgba(52,211,153,0.2); }
+  .badge-red    { background: rgba(248,113,113,0.12); color: #F87171; border: 1px solid rgba(248,113,113,0.2); }
+  .badge-purple { background: var(--color-accent-dim); color: var(--color-accent-bright); border: 1px solid rgba(214,182,90,0.25); }
+  .badge-muted  { background: rgba(255,255,255,0.06); color: var(--color-secondary); border: 1px solid var(--color-border-subtle); }
+
+  .section-heading {
+    font-family: var(--font-serif);
+    font-style: italic;
+    font-weight: 400;
+    font-size: 1.5rem;
+    letter-spacing: -0.02em;
+    background: linear-gradient(135deg,#F8F6EF 0%,var(--color-accent-bright) 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+  }
+
+  .prose-refined { font-size: 0.9rem; line-height: 1.65; }
+  .prose-refined code {
+    font-family: var(--font-mono); font-size: 0.83em;
+    padding: 0.15em 0.4em;
+    background: rgba(214,182,90,0.1); border-radius: 4px;
+    border: 1px solid rgba(214,182,90,0.18);
+  }
+  .prose-refined pre {
+    font-family: var(--font-mono); font-size: 0.8rem; line-height: 1.6;
+    background: rgba(15,15,26,0.8); border: 1px solid var(--color-border);
+    border-radius: var(--radius-md); padding: 0.75rem 1rem; overflow-x: auto;
+  }
+  .prose-refined strong { font-weight: 600; color: var(--color-primary); }
+  .prose-refined a { color: var(--color-accent-bright); }
+  .prose-refined table { width: 100%; border-collapse: collapse; font-size: 0.85em; }
+  .prose-refined thead th {
+    text-align: left; padding: 0.4em 0.6em; color: var(--color-secondary);
+    font-size: 0.78em; text-transform: uppercase; border-bottom: 1px solid var(--color-border);
+  }
+  .prose-refined tbody td { padding: 0.45em 0.6em; border-bottom: 1px solid rgba(255,255,255,0.04); }
+  .prose-refined h1,.prose-refined h2,.prose-refined h3 {
+    font-weight: 600; color: var(--color-primary); margin: 1em 0 0.4em;
+  }
+  .prose-refined ul { list-style: disc; padding-left: 1.4em; margin: 0.5em 0; }
+  .prose-refined li { margin: 0.2em 0; }
+  .prose-refined li::marker { color: var(--color-accent); }
+
+  .status-pulse { animation: pulse 2s cubic-bezier(0.4,0,0.6,1) infinite; }
+  @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:0.4} }
+
+  .accent-glow { box-shadow: 0 0 20px rgba(214,182,90,0.2),0 0 60px rgba(214,182,90,0.08); }
+}

frontend/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

frontend/src/test/setup.ts

@@ -0,0 +1,10 @@
+import '@testing-library/jest-dom/vitest';
+
+class ResizeObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+globalThis.ResizeObserver = ResizeObserverStub;
+HTMLElement.prototype.scrollIntoView = () => {};

frontend/tsconfig.app.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "allowArbitraryExtensions": true,
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

frontend/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

frontend/tsconfig.node.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

frontend/vite.config.ts

@@ -0,0 +1,45 @@
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'vitest/config'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  test: {
+    environment: 'jsdom',
+    setupFiles: './src/test/setup.ts',
+    css: false,
+  },
+  envDir: '../',
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://127.0.0.1:8000',
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks(id: string) {
+          if (id.includes('node_modules/echarts') || id.includes('node_modules/zrender')) {
+            return 'charts';
+          }
+          if (id.includes('node_modules/react') || id.includes('node_modules/react-dom')) {
+            return 'react-vendor';
+          }
+          if (id.includes('node_modules/react-markdown') || id.includes('node_modules/remark') || id.includes('node_modules/unified') || id.includes('node_modules/mdast')) {
+            return 'markdown';
+          }
+          if (id.includes('node_modules/lucide-react')) {
+            return 'icons';
+          }
+          if (id.includes('node_modules/axios')) {
+            return 'vendor-core';
+          }
+        },
+      },
+    },
+  },
+})

requirements-space.txt

@@ -0,0 +1,10 @@
+anthropic>=0.40.0,<1
+duckdb>=1.1.0,<2
+fastapi>=0.115.0,<1
+huggingface-hub>=0.30.0,<2
+loguru>=0.7.0,<1
+openai>=1.0.0,<2
+pandas>=2.2.0,<3
+polars>=1.0.0,<2
+python-dotenv>=1.0.0,<2
+uvicorn>=0.30.0,<1

scripts/__init__.py

@@ -0,0 +1 @@
+"""Deployment and data-publication helpers."""

scripts/bootstrap_hf_data.py

@@ -0,0 +1,60 @@
+"""Build the Space's read-only DuckDB from the published daily Parquet files."""
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import duckdb
+from huggingface_hub import hf_hub_download
+
+
+DEFAULT_REPO = "egoh33/ibkr-daily-stock-data"
+FILES = ("polygon_bars.parquet", "silver_stock_features.parquet")
+
+
+def materialize_database(files: dict[str, Path], db_path: Path) -> None:
+    """Atomically create a DuckDB containing the two public daily-stock tables."""
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = db_path.with_suffix(db_path.suffix + ".tmp")
+    temp_path.unlink(missing_ok=True)
+    with duckdb.connect(str(temp_path)) as conn:
+        for filename, source in files.items():
+            table = Path(filename).stem
+            safe_source = source.as_posix().replace("'", "''")
+            conn.execute(f"CREATE TABLE {table} AS SELECT * FROM read_parquet('{safe_source}')")
+        conn.execute("CHECKPOINT")
+    db_path.unlink(missing_ok=True)
+    temp_path.replace(db_path)
+
+
+def download_files(repo_id: str, token: str | None = None) -> dict[str, Path]:
+    return {
+        filename: Path(
+            hf_hub_download(repo_id=repo_id, repo_type="dataset", filename=filename, token=token)
+        )
+        for filename in FILES
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", default=os.getenv("HF_DATASET_REPO", DEFAULT_REPO))
+    parser.add_argument("--db-path", default=os.getenv("DB_PATH", "./data/equity.duckdb"))
+    parser.add_argument("--source-dir", help="Use local Parquet files instead of downloading")
+    args = parser.parse_args()
+
+    if args.source_dir:
+        source_dir = Path(args.source_dir)
+        files = {filename: source_dir / filename for filename in FILES}
+    else:
+        files = download_files(args.repo, token=os.getenv("HF_TOKEN"))
+    missing = [str(path) for path in files.values() if not path.is_file()]
+    if missing:
+        raise FileNotFoundError(f"Missing required daily-stock files: {', '.join(missing)}")
+    materialize_database(files, Path(args.db_path))
+    print(f"Materialized {args.db_path} from {args.repo}")
+
+
+if __name__ == "__main__":
+    main()