docs: add comprehensive OpenAPI docs for ReDoc/Swagger

- Rich markdown description with data coverage, quick start
- Tag descriptions for all endpoint groups
- Contact info, license metadata
- API_REFERENCE.txt with full endpoint docs

API_REFERENCE.txt

@@ -0,0 +1,591 @@
+================================================================================
+                    ForexDataLake API — Complete Reference
+================================================================================
+
+BASE URL (HuggingFace Space):  https://omchoksi108-forexdatalake.hf.space
+DOCS (Swagger UI):             https://omchoksi108-forexdatalake.hf.space/docs
+REDOC:                         https://omchoksi108-forexdatalake.hf.space/redoc
+
+LOCAL BASE URL:                http://localhost:7860
+
+================================================================================
+                              AUTHENTICATION
+================================================================================
+
+All endpoints (except /health) require an API key.
+
+Header:   X-API-Key: <your-api-key>
+Current:  X-API-Key: OJGHKJOAOFIERHOISSIGHERSGIOERSHGOESGIHESGHIE
+
+Example:
+  curl -H "X-API-Key: OJGHKJOAOFIERHOISSIGHERSGIOERSHGOESGIHESGHIE" \
+       https://omchoksi108-forexdatalake.hf.space/api/v1/symbols
+
+
+================================================================================
+                           VALID ENUM VALUES
+================================================================================
+
+TIMEFRAMES:
+  1min, 5min, 15min, 30min, 1hr, 4hr, 1day
+
+ASSET CLASSES:
+  forex_major, forex_cross, crypto_major, crypto_alt, crypto_cross,
+  commodities, stocks
+
+SOURCES:
+  ALL_TIME_DATA   (full historical data — default)
+  data            (recent data)
+  reports         (equity/trade reports)
+
+SUPPORTED INDICATORS:
+  sma      Simple Moving Average
+  ema      Exponential Moving Average
+  rsi      Relative Strength Index
+  macd     Moving Average Convergence Divergence
+  atr      Average True Range
+  vwap     Volume Weighted Average Price
+  bbands   Bollinger Bands (middle band)
+
+
+================================================================================
+  1. HEALTH CHECK
+================================================================================
+
+GET /api/v1/health
+
+  Auth:       NO (public)
+  Parameters: None
+
+  Response:
+    {
+      "status": "healthy",
+      "version": "1.0.0",
+      "timestamp": "2026-02-15T19:15:46.000000",
+      "total_files": 793,
+      "total_symbols": 110,
+      "total_timeframes": 7,
+      "cache_entries": 0
+    }
+
+  Example:
+    curl https://omchoksi108-forexdatalake.hf.space/api/v1/health
+
+
+================================================================================
+  2. LIST ALL SYMBOLS
+================================================================================
+
+GET /api/v1/symbols
+
+  Auth:       YES
+  Parameters:
+    asset_class   (optional)  Filter by asset class
+                              Values: forex_major, forex_cross, crypto_major,
+                                      crypto_alt, crypto_cross, commodities, stocks
+
+  Response: Array of SymbolInfo
+    [
+      {
+        "symbol": "EURUSD",
+        "asset_class": "forex_major",
+        "available_timeframes": ["1min", "5min", "15min", "30min", "1hr", "4hr", "1day"],
+        "description": "Euro / US Dollar"
+      }
+    ]
+
+  Examples:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/symbols"
+
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/symbols?asset_class=forex_major"
+
+
+================================================================================
+  3. SEARCH SYMBOLS
+================================================================================
+
+GET /api/v1/symbols/search
+
+  Auth:       YES
+  Parameters:
+    q             (REQUIRED)  Search query, 1-50 characters
+    asset_class   (optional)  Filter by asset class
+    limit         (optional)  Max results, default=20, range 1-100
+
+  Response: SymbolSearchResult
+    {
+      "total": 5,
+      "results": [
+        {
+          "symbol": "EURUSD",
+          "asset_class": "forex_major",
+          "available_timeframes": ["1hr", "4hr", "1day"],
+          "description": "Euro / US Dollar"
+        }
+      ]
+    }
+
+  Examples:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/symbols/search?q=EUR"
+
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/symbols/search?q=BTC&asset_class=crypto_major&limit=5"
+
+
+================================================================================
+  4. GET SYMBOL DETAIL
+================================================================================
+
+GET /api/v1/symbols/{symbol}
+
+  Auth:       YES
+  Parameters:
+    symbol        (REQUIRED)  Path parameter, auto-uppercased
+
+  Response: SymbolDetail
+    {
+      "symbol": "EURUSD",
+      "asset_class": "forex_major",
+      "description": "Euro / US Dollar",
+      "timeframes": [
+        {
+          "timeframe": "1hr",
+          "source": "ALL_TIME_DATA",
+          "row_count": 0,
+          "file_path": "ALL_TIME_DATA/1hr_time/EURUSD_1hr.parquet"
+        }
+      ]
+    }
+
+  Example:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/symbols/EURUSD"
+
+
+================================================================================
+  5. LIST TIMEFRAMES FOR A SYMBOL
+================================================================================
+
+GET /api/v1/symbols/{symbol}/timeframes
+
+  Auth:       YES
+  Parameters:
+    symbol        (REQUIRED)  Path parameter, auto-uppercased
+
+  Response: Array of TimeframeDetail
+    [
+      {
+        "timeframe": "1hr",
+        "source": "ALL_TIME_DATA",
+        "row_count": 0,
+        "file_path": "ALL_TIME_DATA/1hr_time/EURUSD_1hr.parquet"
+      }
+    ]
+
+  Example:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/symbols/EURUSD/timeframes"
+
+
+================================================================================
+  6. QUERY OHLCV DATA
+================================================================================
+
+GET /api/v1/data
+
+  Auth:       YES
+  Parameters:
+    symbol        (REQUIRED)  Trading symbol, e.g. EURUSD
+    timeframe     (REQUIRED)  Values: 1min, 5min, 15min, 30min, 1hr, 4hr, 1day
+    start         (optional)  Start timestamp, ISO 8601 format
+    end           (optional)  End timestamp, ISO 8601 format
+    source        (optional)  Default: "ALL_TIME_DATA"
+    limit         (optional)  Max rows, default=500, range 1-10000
+    offset        (optional)  Pagination offset, default=0
+
+  Response: OHLCVResponse
+    {
+      "symbol": "EURUSD",
+      "timeframe": "1hr",
+      "source": "ALL_TIME_DATA",
+      "total_rows": 389327,
+      "returned": 500,
+      "limit": 500,
+      "offset": 0,
+      "data": [
+        {
+          "ts": "1971-01-04 00:00:00",
+          "open": 1.2345,
+          "high": 1.2400,
+          "low": 1.2300,
+          "close": 1.2380,
+          "volume": 1500.0
+        }
+      ]
+    }
+
+  Examples:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/data?symbol=EURUSD&timeframe=1hr"
+
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/data?symbol=EURUSD&timeframe=1hr&start=2020-01-01&end=2025-12-31&limit=1000"
+
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/data?symbol=BTCUSD&timeframe=1day&source=data&limit=100"
+
+
+================================================================================
+  7. GET DATE RANGE
+================================================================================
+
+GET /api/v1/data/range
+
+  Auth:       YES
+  Parameters:
+    symbol        (REQUIRED)  Trading symbol
+    timeframe     (REQUIRED)  Values: 1min, 5min, 15min, 30min, 1hr, 4hr, 1day
+    source        (optional)  Default: "ALL_TIME_DATA"
+
+  Response: DateRangeInfo
+    {
+      "symbol": "EURUSD",
+      "timeframe": "1hr",
+      "source": "ALL_TIME_DATA",
+      "start_date": "1971-01-04 00:00:00",
+      "end_date": "2026-01-13 11:00:00",
+      "total_rows": 389327
+    }
+
+  Example:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/data/range?symbol=EURUSD&timeframe=1hr"
+
+
+================================================================================
+  8. GET LATEST BARS
+================================================================================
+
+GET /api/v1/data/latest
+
+  Auth:       YES
+  Parameters:
+    symbol        (REQUIRED)  Trading symbol
+    timeframe     (REQUIRED)  Values: 1min, 5min, 15min, 30min, 1hr, 4hr, 1day
+    count         (optional)  Number of most recent bars, default=1, range 1-100
+    source        (optional)  Default: "ALL_TIME_DATA"
+
+  Response: LatestBar
+    {
+      "symbol": "EURUSD",
+      "timeframe": "1hr",
+      "count": 5,
+      "data": [
+        {
+          "ts": "2026-01-13 07:00:00",
+          "open": 1.0250,
+          "high": 1.0265,
+          "low": 1.0240,
+          "close": 1.0258,
+          "volume": 2500.0
+        }
+      ]
+    }
+
+  Example:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/data/latest?symbol=EURUSD&timeframe=1day&count=10"
+
+
+================================================================================
+  9. GET EQUITY CURVE
+================================================================================
+
+GET /api/v1/reports/equity
+
+  Auth:       YES
+  Parameters:
+    limit         (optional)  Max rows, default=500, range 1-10000
+    offset        (optional)  Pagination offset, default=0
+
+  Response: EquityResponse
+    {
+      "total": 5000,
+      "returned": 500,
+      "limit": 500,
+      "offset": 0,
+      "data": [
+        {
+          "step": 0,
+          "equity": 10000.0
+        }
+      ]
+    }
+
+  Example:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/reports/equity?limit=1000"
+
+
+================================================================================
+  10. GET TRADE RECORDS
+================================================================================
+
+GET /api/v1/reports/trades
+
+  Auth:       YES
+  Parameters:
+    pair          (optional)  Filter by trading pair
+    side          (optional)  Filter by side: "buy" or "sell"
+    limit         (optional)  Max rows, default=500, range 1-10000
+    offset        (optional)  Pagination offset, default=0
+
+  Response: TradesResponse
+    {
+      "total": 320,
+      "returned": 100,
+      "limit": 100,
+      "offset": 0,
+      "data": [
+        {
+          "pair": "EURUSD",
+          "type": "market",
+          "side": "buy",
+          "price": 1.0250,
+          "size": 100000.0,
+          "time": "2025-06-15 14:30:00",
+          "score": 0.85,
+          "pnl": 250.0
+        }
+      ]
+    }
+
+  Examples:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/reports/trades"
+
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/reports/trades?pair=EURUSD&side=buy&limit=50"
+
+
+================================================================================
+  11. LIST SUPPORTED INDICATORS
+================================================================================
+
+GET /api/v1/indicators
+
+  Auth:       YES
+  Parameters: None
+
+  Response:
+    {
+      "indicators": {
+        "sma": "Simple Moving Average",
+        "ema": "Exponential Moving Average",
+        "rsi": "Relative Strength Index",
+        "macd": "Moving Average Convergence Divergence",
+        "atr": "Average True Range",
+        "vwap": "Volume Weighted Average Price",
+        "bbands": "Bollinger Bands (middle)"
+      }
+    }
+
+  Example:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/indicators"
+
+
+================================================================================
+  12. COMPUTE INDICATOR
+================================================================================
+
+GET /api/v1/indicators/{symbol}
+
+  Auth:       YES
+  Parameters:
+    symbol        (REQUIRED)  Path parameter, auto-uppercased
+    indicator     (REQUIRED)  Values: sma, ema, rsi, macd, atr, vwap, bbands
+    timeframe     (REQUIRED)  Values: 1min, 5min, 15min, 30min, 1hr, 4hr, 1day
+    period        (optional)  Indicator lookback period, default=14, range 1-500
+    start         (optional)  Start timestamp, ISO 8601
+    end           (optional)  End timestamp, ISO 8601
+    source        (optional)  Default: "ALL_TIME_DATA"
+    limit         (optional)  Max rows, default=500, range 1-10000
+    offset        (optional)  Pagination offset, default=0
+
+  Response: IndicatorResponse
+    {
+      "symbol": "EURUSD",
+      "timeframe": "1hr",
+      "indicator": "sma",
+      "period": 14,
+      "total_rows": 500,
+      "returned": 500,
+      "data": [
+        {
+          "ts": "2025-01-01 00:00:00",
+          "open": 1.0250,
+          "high": 1.0265,
+          "low": 1.0240,
+          "close": 1.0258,
+          "volume": 2500.0,
+          "indicator_value": 1.0255
+        }
+      ]
+    }
+
+  Examples:
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/indicators/EURUSD?indicator=sma&timeframe=1hr&period=20"
+
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/indicators/BTCUSD?indicator=rsi&timeframe=1day&period=14"
+
+    curl -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/indicators/EURUSD?indicator=macd&timeframe=4hr"
+
+
+================================================================================
+  13. REFRESH METADATA INDEX (SYNC)
+================================================================================
+
+POST /api/v1/sync
+
+  Auth:       YES
+  Parameters: None
+
+  Description:
+    Re-scans the remote HuggingFace repo and rebuilds the parquet file
+    metadata index. No data is downloaded — everything stays remote.
+
+  Response:
+    {
+      "status": "refreshed",
+      "total_files": 793,
+      "total_symbols": 110
+    }
+
+  Example:
+    curl -X POST -H "X-API-Key: <key>" \
+         "https://omchoksi108-forexdatalake.hf.space/api/v1/sync"
+
+
+================================================================================
+  14. WEBSOCKET STREAM
+================================================================================
+
+WS /api/v1/ws/stream?api_key=<your-api-key>
+
+  Auth:       Via query parameter "api_key"
+  Connection: ws://host/api/v1/ws/stream?api_key=<key>
+
+  CLIENT SENDS (JSON):
+
+    Subscribe to a symbol:
+    {
+      "symbol": "EURUSD",       // REQUIRED
+      "timeframe": "1hr",       // optional, default "1h"
+      "source": "ALL_TIME_DATA",// optional, default "ALL_TIME_DATA"
+      "limit": 100              // optional, default 100, max 1000
+    }
+
+    Unsubscribe:
+    { "action": "unsubscribe" }
+
+    Ping:
+    { "action": "ping" }
+
+  SERVER RESPONDS (JSON):
+
+    On subscribe — stream header:
+    { "status": "streaming", "symbol": "EURUSD", "timeframe": "1hr", "total": 100 }
+
+    Each bar:
+    {
+      "type": "bar",
+      "data": {
+        "ts": "2025-01-01 00:00:00",
+        "open": 1.0250,
+        "high": 1.0265,
+        "low": 1.0240,
+        "close": 1.0258,
+        "volume": 2500.0
+      }
+    }
+
+    End of stream:
+    { "type": "end", "symbol": "EURUSD" }
+
+    On ping:
+    { "status": "pong" }
+
+    On unsubscribe:
+    { "status": "unsubscribed" }
+
+    On error:
+    { "error": "Symbol 'XYZ' not found" }
+
+
+================================================================================
+                           ERROR RESPONSES
+================================================================================
+
+All errors return JSON:
+
+  {
+    "error": "ERROR_CODE",
+    "detail": "Human-readable message",
+    "path": "/api/v1/..."
+  }
+
+Error codes:
+  SYMBOL_NOT_FOUND        Symbol does not exist in the data lake
+  TIMEFRAME_NOT_FOUND     Timeframe not available for this symbol
+  INVALID_DATE_RANGE      Start date is after end date
+  DATA_NOT_AVAILABLE      No data found for this query
+  AUTHENTICATION_FAILED   Missing or invalid API key
+  RATE_LIMIT_EXCEEDED     Too many requests
+  VALIDATION_ERROR        Invalid parameter value
+  DATABASE_ERROR          DuckDB query failed
+  INTERNAL_ERROR          Unexpected server error
+
+HTTP Status Codes:
+  200   Success
+  401   Authentication failed
+  404   Symbol/timeframe/data not found
+  422   Validation error (missing/invalid params)
+  429   Rate limit exceeded
+  500   Internal server error
+
+
+================================================================================
+                        QUICK START EXAMPLES
+================================================================================
+
+# 1. Check API health
+curl https://omchoksi108-forexdatalake.hf.space/api/v1/health
+
+# 2. List all forex major symbols
+curl -H "X-API-Key: OJGHKJOAOFIERHOISSIGHERSGIOERSHGOESGIHESGHIE" \
+     "https://omchoksi108-forexdatalake.hf.space/api/v1/symbols?asset_class=forex_major"
+
+# 3. Get EURUSD date range
+curl -H "X-API-Key: OJGHKJOAOFIERHOISSIGHERSGIOERSHGOESGIHESGHIE" \
+     "https://omchoksi108-forexdatalake.hf.space/api/v1/data/range?symbol=EURUSD&timeframe=1hr"
+
+# 4. Get last 10 daily bars for BTCUSD
+curl -H "X-API-Key: OJGHKJOAOFIERHOISSIGHERSGIOERSHGOESGIHESGHIE" \
+     "https://omchoksi108-forexdatalake.hf.space/api/v1/data/latest?symbol=BTCUSD&timeframe=1day&count=10"
+
+# 5. Get OHLCV data with date filter
+curl -H "X-API-Key: OJGHKJOAOFIERHOISSIGHERSGIOERSHGOESGIHESGHIE" \
+     "https://omchoksi108-forexdatalake.hf.space/api/v1/data?symbol=EURUSD&timeframe=1hr&start=2024-01-01&end=2024-12-31&limit=1000"
+
+# 6. Compute RSI(14) on EURUSD hourly
+curl -H "X-API-Key: OJGHKJOAOFIERHOISSIGHERSGIOERSHGOESGIHESGHIE" \
+     "https://omchoksi108-forexdatalake.hf.space/api/v1/indicators/EURUSD?indicator=rsi&timeframe=1hr&period=14"
+
+================================================================================

app/main.py

@@ -65,18 +65,142 @@ async def lifespan(app: FastAPI):
 
 def create_app() -> FastAPI:
     """Build and configure the FastAPI application."""
+
+    DESCRIPTION = """
+## ForexDataLake API 📈
+
+**High-performance market data API** serving OHLCV data directly from a
+HuggingFace-hosted parquet data lake — **zero local storage required**.
+
+---
+
+### 📊 Data Coverage
+
+| Category | Count |
+|----------|-------|
+| **Instruments** | 111 symbols |
+| **Timeframes** | 7 (1min → 1day) |
+| **Total Rows** | 276M+ |
+| **Data Size** | 4.65 GB |
+| **Asset Classes** | Forex, Crypto, Commodities, Stocks |
+
+### 🔑 Authentication
+
+All endpoints (except `/health`) require an API key via the `X-API-Key` header.
+
+```
+curl -H "X-API-Key: YOUR_KEY" https://host/api/v1/symbols
+```
+
+### ⏱️ Supported Timeframes
+
+`1min` · `5min` · `15min` · `30min` · `1hr` · `4hr` · `1day`
+
+### 📈 Supported Indicators
+
+`sma` · `ema` · `rsi` · `macd` · `atr` · `vwap` · `bbands`
+
+### 🗂️ Data Sources
+
+| Source | Description |
+|--------|-------------|
+| `ALL_TIME_DATA` | Full historical data (default) |
+| `data` | Recent/live data |
+| `reports` | Equity curves & trade logs |
+
+### ⚡ Quick Start
+
+1. **Health check** — `GET /api/v1/health` (no auth)
+2. **List symbols** — `GET /api/v1/symbols`
+3. **Get date range** — `GET /api/v1/data/range?symbol=EURUSD&timeframe=1hr`
+4. **Fetch OHLCV** — `GET /api/v1/data?symbol=EURUSD&timeframe=1hr&limit=100`
+5. **Compute RSI** — `GET /api/v1/indicators/EURUSD?indicator=rsi&timeframe=1hr`
+6. **Stream via WS** — `WS /api/v1/ws/stream?api_key=KEY`
+
+---
+
+### ❌ Error Format
+
+All errors return:
+```json
+{
+  "error": "SYMBOL_NOT_FOUND",
+  "detail": "Symbol 'XYZ' not found",
+  "path": "/api/v1/symbols/XYZ"
+}
+```
+"""
+
+    tags_metadata = [
+        {
+            "name": "Health",
+            "description": "Server health and status. **No authentication required.**",
+        },
+        {
+            "name": "Symbols",
+            "description": (
+                "Discover and search available trading instruments. "
+                "List all symbols, filter by asset class, search by name, "
+                "and get detailed symbol info including available timeframes."
+            ),
+        },
+        {
+            "name": "Market Data",
+            "description": (
+                "Query historical OHLCV (Open, High, Low, Close, Volume) candlestick data. "
+                "Supports date filtering, pagination, date range discovery, "
+                "and fetching the latest N bars."
+            ),
+        },
+        {
+            "name": "Indicators",
+            "description": (
+                "Compute technical indicators on OHLCV data on-the-fly. "
+                "Supported: **SMA**, **EMA**, **RSI**, **MACD**, **ATR**, **VWAP**, **Bollinger Bands**. "
+                "Specify the indicator name, timeframe, and lookback period."
+            ),
+        },
+        {
+            "name": "Reports",
+            "description": (
+                "Access trading reports including equity curves (cumulative P&L) "
+                "and individual trade records with pair/side filtering."
+            ),
+        },
+        {
+            "name": "Sync",
+            "description": (
+                "Refresh the internal metadata index by re-scanning the remote "
+                "HuggingFace repository. No data is downloaded — everything is read remotely."
+            ),
+        },
+        {
+            "name": "WebSocket",
+            "description": (
+                "Stream OHLCV bars over a persistent WebSocket connection. "
+                "Authenticate via `?api_key=KEY` query parameter. "
+                "Send JSON subscription messages to receive bars."
+            ),
+        },
+    ]
+
     application = FastAPI(
         title="ForexDataLake API",
-        description=(
-            "High-performance market data API serving OHLCV data from a "
-            "HuggingFace-hosted parquet data lake. Supports 111 instruments, "
-            "7 timeframes, technical indicators, equity/trade reports, and WebSocket streaming."
-        ),
+        description=DESCRIPTION,
         version="1.0.0",
         lifespan=lifespan,
         docs_url="/docs",
         redoc_url="/redoc",
         openapi_url="/openapi.json",
+        openapi_tags=tags_metadata,
+        contact={
+            "name": "OMCHOKSI108",
+            "url": "https://huggingface.co/OMCHOKSI108",
+        },
+        license_info={
+            "name": "MIT",
+        },
+        root_path_in_servers=False,
     )
 
     # -- Exception handlers ---------------------------------------------------
@@ -109,6 +233,11 @@ def create_app() -> FastAPI:
         response_model=HealthResponse,
         tags=["Health"],
         summary="Health check",
+        description=(
+            "Returns the current health status of the API including version, "
+            "number of indexed parquet files, unique symbols, timeframes, "
+            "and cache statistics. **No authentication required.**"
+        ),
     )
     def health() -> HealthResponse:
         from app.core.cache import cache