# ================================================================
# Auteur  : Simon-Pierre Boucher
# Contact : contact@spboucher.ai
# Projet  : Prévision de volatilité réalisée multi-actifs
#           (HAR-RV vs GARCH vs Machine Learning)
# Fichier : config.yaml
# Description : Configuration centrale du pipeline — univers d'actifs,
#               fenêtres d'estimation, horizons, seeds, chemins.
# ================================================================

api:
  base_url: "https://www.hfmarketdata.io"
  rate_limit_per_sec: 4          # requests per second (polite default)
  max_retries: 5
  backoff_base_sec: 1.0          # exponential backoff: base * 2**attempt
  timeout_sec: 60
  page_limit: 100000             # max rows per request page (validated live)
  cache_dir: "data/raw"          # parquet cache, one file per (asset, ticker, timeframe)

# ---------------------------------------------------------------- universe
# Validated against /v1/{asset}/tickers on 2026-08-10.
# NOTE: BNB is NOT available in the API -> replaced by ADA.
universe:
  equity:                        # asset class in API: stock / etf
    - {ticker: SPY,  asset: etf}
    - {ticker: QQQ,  asset: etf}
    - {ticker: IWM,  asset: etf}
    - {ticker: GLD,  asset: etf}
    - {ticker: TLT,  asset: etf}
    - {ticker: AAPL, asset: stock}
    - {ticker: MSFT, asset: stock}
    - {ticker: NVDA, asset: stock}
    - {ticker: JPM,  asset: stock}
    - {ticker: XOM,  asset: stock}
  fx:
    - {ticker: EURUSD, asset: fx}
    - {ticker: USDJPY, asset: fx}
    - {ticker: GBPUSD, asset: fx}
    - {ticker: USDCAD, asset: fx}
    - {ticker: AUDUSD, asset: fx}
  crypto:
    - {ticker: BTC, asset: crypto}
    - {ticker: ETH, asset: crypto}
    - {ticker: SOL, asset: crypto}
    - {ticker: ADA, asset: crypto}   # BNB unavailable in API
    - {ticker: XRP, asset: crypto}
  futures:                       # continuous, back-adjusted (ratio)
    - {ticker: ES, asset: futures}
    - {ticker: NQ, asset: futures}
    - {ticker: CL, asset: futures}
    - {ticker: GC, asset: futures}
    - {ticker: ZN, asset: futures}

predictors:                      # used as features only, not forecast targets
  index:
    - {ticker: VIX, asset: index}

adjustment:                      # per asset class
  stock: adj_splitdiv
  etf: adj_splitdiv
  futures: contin_adj_ratio
  crypto: none
  index: none
  fx: none

sample:
  start: "2013-01-01"            # common start (BTC begins 2013-04)
  end: "2026-07-31"
  timeframes: ["1min", "5min"]   # intraday inputs for RV
  trading_hours:                 # local exchange time as served by the API
    equity: {open: "09:30", close: "16:00"}   # RTH only for RV
    futures: {open: "00:00", close: "23:59"}  # near-24h; sessions handled in code
    fx: {open: "00:00", close: "23:59"}       # Sun 17:00 -> Fri 17:00 ET
    crypto: {open: "00:00", close: "23:59"}   # 24/7, day = calendar day UTC
  min_intraday_bars: 30          # drop days with fewer valid 1-min bars (equity RTH)

realized_vol:
  base_frequency_min: 5          # headline RV: 5-min subsampled
  subsample_offsets: 5           # number of 1-min offset grids averaged
  kernel: parzen                 # realized kernel (BNHLS 2008)
  jump_test_alpha: 0.001         # BNS test size for jump detection
  annualization_days: 252

models:
  har_lags: [1, 5, 22]
  garch:
    dists: ["normal"]
    rescale: true
  ml:
    seed: 20260810
    tuning: walk_forward         # strict temporal CV
    n_splits: 4
    feature_sets: ["har", "extended"]
    lstm: {seq_len: 22, hidden: 64, layers: 1, epochs: 50, patience: 8}
    transformer: {seq_len: 22, d_model: 32, heads: 4, blocks: 2, epochs: 50, patience: 8}

evaluation:
  estimation_window_days: 1000
  reestimation_freq_days: 22     # monthly
  horizons: [1, 5, 22]
  losses: ["qlike", "mse"]
  mcs_alpha: 0.10
  mcs_bootstrap: 5000

robustness:
  subperiods:
    pre2020: ["2013-01-01", "2019-12-31"]
    covid: ["2020-01-01", "2020-12-31"]
    inflation: ["2021-01-01", "2022-12-31"]
    recent: ["2024-01-01", "2026-07-31"]
  window_sizes: [500, 1000, 2000]
  frequencies: ["rv1min", "rv5min_ss", "rkernel"]

backtest:
  vol_target_ann: 0.10
  leverage_cap: 3.0
  tc_bps: 5.0
  tc_grid_bps: [0, 5, 10, 20]
  var_levels: [0.01, 0.05]
  risk_aversion: 5.0

paths:
  raw: "data/raw"
  processed: "data/processed"
  figures: "figures"
  tables: "results/tables"
  reproduced: "results/reproduced"

seed: 20260810