//! Walk-forward training binary for DQN and PPO models. //! //! Trains models using expanding walk-forward windows on real OHLCV data loaded //! from Databento DBN files. Supports early stopping, checkpoint saving, and //! normalization statistics export for reproducible evaluation. //! //! # Usage //! //! ```bash //! SQLX_OFFLINE=true cargo run -p ml --example train_baseline -- \ //! --model both --epochs 50 --batch-size 128 \ //! --data-dir data/cache/futures-baseline \ //! --output-dir ml/trained_models //! ``` #![allow(unused_crate_dependencies)] #![deny( clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::indexing_slicing )] use std::path::{Path, PathBuf}; use anyhow::{Context, Result}; use chrono::{DateTime, TimeZone, Utc}; use clap::Parser; use rand::Rng; use tracing::{error, info, warn}; use dbn::decode::DecodeRecord; use ml::dqn::{DQNConfig, Experience, DQN}; use ml::features::extraction::extract_ml_features; use ml::ppo::ppo::{PPOConfig, PPO}; use ml::ppo::trajectories::{Trajectory, TrajectoryBatch, TrajectoryStep}; use ml::ppo::gae::compute_gae; use ml::types::OHLCVBar; use ml::walk_forward::{generate_walk_forward_windows, NormStats, WalkForwardConfig}; // --------------------------------------------------------------------------- // CLI Arguments // --------------------------------------------------------------------------- /// Walk-forward training binary for DQN and PPO baseline models. #[derive(Parser, Debug)] #[command(name = "train_baseline", about = "Train DQN/PPO with walk-forward windows")] struct Args { /// Which model(s) to train: "dqn", "ppo", or "both" #[arg(long, default_value = "both")] model: String, /// Maximum training epochs per fold #[arg(long, default_value_t = 50)] epochs: usize, /// Training batch size #[arg(long, default_value_t = 128)] batch_size: usize, /// Path to directory containing .dbn.zst files #[arg(long, default_value = "data/cache/futures-baseline")] data_dir: PathBuf, /// Output directory for trained model checkpoints #[arg(long, default_value = "ml/trained_models")] output_dir: PathBuf, /// Optional path to hyperopt results JSON (reserved for future use) #[arg(long)] hyperopt_params: Option, /// Feature dimension (must match extract_ml_features output) #[arg(long, default_value_t = 51)] feature_dim: usize, /// Early stopping patience (epochs without improvement) #[arg(long, default_value_t = 10)] patience: usize, /// Number of actions for the DQN/PPO action space #[arg(long, default_value_t = 3)] num_actions: usize, } // --------------------------------------------------------------------------- // DBN Loading // --------------------------------------------------------------------------- /// Recursively discover .dbn.zst files under `dir`. fn find_dbn_files(dir: &Path) -> Result> { let mut files = Vec::new(); if !dir.exists() { anyhow::bail!("Data directory does not exist: {}", dir.display()); } collect_dbn_files_recursive(dir, &mut files)?; files.sort(); Ok(files) } /// Recursive helper that walks the directory tree without `walkdir`. fn collect_dbn_files_recursive(dir: &Path, out: &mut Vec) -> Result<()> { let entries = std::fs::read_dir(dir) .with_context(|| format!("Cannot read directory: {}", dir.display()))?; for entry in entries { let entry = entry.with_context(|| "Failed to read dir entry")?; let path = entry.path(); if path.is_dir() { collect_dbn_files_recursive(&path, out)?; } else if path .file_name() .and_then(|n| n.to_str()) .map(|n| n.ends_with(".dbn.zst")) .unwrap_or(false) { out.push(path); } } Ok(()) } /// Load OHLCV bars from a single .dbn.zst file using the `dbn` crate decoder. /// /// Reads OhlcvMsg records and converts them to [`OHLCVBar`]. fn load_bars_from_dbn(path: &Path) -> Result> { use dbn::decode::dbn::Decoder; use dbn::OhlcvMsg; let file = std::fs::File::open(path) .with_context(|| format!("Cannot open DBN file: {}", path.display()))?; let buf = std::io::BufReader::new(file); let mut decoder = Decoder::new(buf) .with_context(|| format!("Failed to create DBN decoder for {}", path.display()))?; let mut bars = Vec::new(); // Decode all records — we only care about OHLCV messages while let Some(record) = decoder .decode_record::() .with_context(|| format!("Error decoding records from {}", path.display()))? { let ts_nanos = record.hd.ts_event; let timestamp = nanos_to_datetime(ts_nanos); // Databento prices are in fixed-point (1e-9 units) let price_scale = 1e-9_f64; bars.push(OHLCVBar { timestamp, open: record.open as f64 * price_scale, high: record.high as f64 * price_scale, low: record.low as f64 * price_scale, close: record.close as f64 * price_scale, volume: record.volume as f64, }); } Ok(bars) } /// Convert nanosecond UNIX timestamp to chrono DateTime. fn nanos_to_datetime(nanos: u64) -> DateTime { let secs = (nanos / 1_000_000_000) as i64; let subsec_nanos = (nanos % 1_000_000_000) as u32; Utc.timestamp_opt(secs, subsec_nanos) .single() .unwrap_or_else(Utc::now) } /// Load all OHLCV bars from a directory of .dbn.zst files, sorted chronologically. fn load_all_bars(data_dir: &Path) -> Result> { let dbn_files = find_dbn_files(data_dir)?; if dbn_files.is_empty() { anyhow::bail!( "No .dbn.zst files found in {}. Run download_baseline first.", data_dir.display() ); } info!("Found {} .dbn.zst files in {}", dbn_files.len(), data_dir.display()); let mut all_bars = Vec::new(); for path in &dbn_files { match load_bars_from_dbn(path) { Ok(bars) => { info!(" {} -> {} bars", path.display(), bars.len()); all_bars.extend(bars); } Err(e) => { warn!(" Skipping {} — {}", path.display(), e); } } } // Sort chronologically all_bars.sort_by_key(|b| b.timestamp); info!("Total bars loaded: {}", all_bars.len()); Ok(all_bars) } // --------------------------------------------------------------------------- // Reward Calculation // --------------------------------------------------------------------------- /// Compute PnL-based reward for a trading action. /// /// - action 0 (BUY): reward = close_next - close_current /// - action 1 (SELL): reward = -(close_next - close_current) /// - action 2 (HOLD): reward = -0.0001 (small opportunity cost) fn compute_reward(close_current: f64, close_next: f64, action_idx: u8) -> f32 { let price_change = close_next - close_current; match action_idx { 0 => price_change as f32, // BUY 1 => -(price_change as f32), // SELL _ => -0.0001_f32, // HOLD (small penalty) } } // --------------------------------------------------------------------------- // DQN Training // --------------------------------------------------------------------------- /// Train a DQN model on a single walk-forward fold. /// /// Returns the best validation loss achieved. fn train_dqn_fold( fold: usize, train_features: &[[f64; 51]], val_features: &[[f64; 51]], train_bars: &[OHLCVBar], val_bars: &[OHLCVBar], args: &Args, output_dir: &Path, ) -> Result { info!(" [DQN] Fold {} — {} train, {} val features", fold, train_features.len(), val_features.len()); // Configure DQN with baseline-friendly settings let config = DQNConfig { state_dim: args.feature_dim, num_actions: args.num_actions, hidden_dims: vec![128, 64], learning_rate: 1e-4, gamma: 0.99, epsilon_start: 1.0, epsilon_end: 0.05, epsilon_decay: 0.995, replay_buffer_capacity: 50_000, batch_size: args.batch_size, min_replay_size: args.batch_size, target_update_freq: 500, warmup_steps: 0, // No warmup — we fill buffer before training use_double_dqn: true, use_huber_loss: true, // Disable Rainbow extras for baseline simplicity use_per: false, use_dueling: false, use_distributional: false, use_noisy_nets: false, use_cql: false, use_iqn: false, use_cvar_action_selection: false, ..DQNConfig::default() }; let mut dqn = DQN::new(config).context("Failed to create DQN model")?; let mut best_val_loss = f64::MAX; let mut epochs_without_improvement = 0_usize; let mut rng = rand::thread_rng(); for epoch in 0..args.epochs { // --- Training pass --- let mut epoch_loss = 0.0_f64; let mut epoch_steps = 0_usize; // Process training data sequentially let n_train = train_features.len(); if n_train < 2 { warn!(" [DQN] Fold {} — insufficient training features ({})", fold, n_train); break; } for i in 0..n_train.saturating_sub(1) { let state_f64 = match train_features.get(i) { Some(f) => f, None => continue, }; let next_f64 = match train_features.get(i + 1) { Some(f) => f, None => continue, }; let state: Vec = state_f64.iter().map(|&v| v as f32).collect(); let next_state: Vec = next_f64.iter().map(|&v| v as f32).collect(); // Select action with epsilon-greedy let action = dqn.select_action(&state) .map(|fa| fa.to_index().min(args.num_actions.saturating_sub(1)) as u8) .unwrap_or_else(|_| rng.gen_range(0..args.num_actions as u8)); // Compute reward from bar prices let close_cur = train_bars.get(i).map(|b| b.close).unwrap_or(0.0); let close_next = train_bars.get(i + 1).map(|b| b.close).unwrap_or(close_cur); let reward = compute_reward(close_cur, close_next, action); let done = i + 2 >= n_train; // Store experience let exp = Experience::new(state, action, reward, next_state, done); if let Err(e) = dqn.store_experience(exp) { // Non-fatal: buffer may not be ready if epoch == 0 && i < 5 { info!(" [DQN] store_experience: {}", e); } } // Train step (returns (loss, grad_norm)) match dqn.train_step(None) { Ok((loss, _grad_norm)) => { epoch_loss += loss as f64; epoch_steps += 1; } Err(_) => { // Training not ready yet (buffer too small) } } } let avg_train_loss = if epoch_steps > 0 { epoch_loss / epoch_steps as f64 } else { f64::MAX }; // --- Validation pass --- let val_loss = evaluate_dqn_validation(&dqn, val_features, val_bars, args); // Decay epsilon at epoch level let current_eps = dqn.get_epsilon(); let new_eps = (current_eps * 0.995_f32).max(0.05); dqn.set_epsilon(new_eps as f64); info!( " [DQN] Fold {} Epoch {}/{} — train_loss={:.6} val_loss={:.6} eps={:.4}", fold, epoch + 1, args.epochs, avg_train_loss, val_loss, dqn.get_epsilon() ); // Early stopping check if val_loss < best_val_loss { best_val_loss = val_loss; epochs_without_improvement = 0; // Save best checkpoint let ckpt_path = output_dir.join(format!("dqn_fold{}_best.safetensors", fold)); if let Err(e) = dqn.get_q_network_vars().save(ckpt_path.to_string_lossy().as_ref()) { warn!(" [DQN] Failed to save checkpoint: {}", e); } else { info!(" [DQN] Saved best checkpoint: {}", ckpt_path.display()); } } else { epochs_without_improvement += 1; if epochs_without_improvement >= args.patience { info!( " [DQN] Early stopping at epoch {} (patience {} exhausted)", epoch + 1, args.patience ); break; } } } Ok(best_val_loss) } /// Evaluate DQN on validation features and return average loss proxy. /// /// Since DQN.train_step uses replay buffer internally, we estimate validation /// performance via average absolute reward (lower is closer to zero = better). fn evaluate_dqn_validation( _dqn: &DQN, val_features: &[[f64; 51]], val_bars: &[OHLCVBar], _args: &Args, ) -> f64 { // Use cumulative absolute reward as validation metric let n = val_features.len(); if n < 2 { return f64::MAX; } let mut total_abs_reward = 0.0_f64; let mut count = 0_usize; for i in 0..n.saturating_sub(1) { let close_cur = val_bars.get(i).map(|b| b.close).unwrap_or(0.0); let close_next = val_bars.get(i + 1).map(|b| b.close).unwrap_or(close_cur); // For validation, measure absolute price change as proxy for how predictable the period is let abs_change = (close_next - close_cur).abs(); total_abs_reward += abs_change; count += 1; } if count > 0 { total_abs_reward / count as f64 } else { f64::MAX } } // --------------------------------------------------------------------------- // PPO Training // --------------------------------------------------------------------------- /// Train a PPO model on a single walk-forward fold. /// /// Returns the best validation loss achieved. fn train_ppo_fold( fold: usize, train_features: &[[f64; 51]], val_features: &[[f64; 51]], train_bars: &[OHLCVBar], val_bars: &[OHLCVBar], args: &Args, output_dir: &Path, ) -> Result { info!(" [PPO] Fold {} — {} train, {} val features", fold, train_features.len(), val_features.len()); let config = PPOConfig { state_dim: args.feature_dim, num_actions: args.num_actions, policy_hidden_dims: vec![128, 64], value_hidden_dims: vec![128, 64], policy_learning_rate: 3e-4, value_learning_rate: 1e-3, clip_epsilon: 0.2, value_loss_coeff: 0.5, entropy_coeff: 0.01, batch_size: args.batch_size.max(64), mini_batch_size: 64, num_epochs: 4, max_grad_norm: 0.5, use_lstm: false, ..PPOConfig::default() }; let mut ppo = PPO::new(config.clone()).context("Failed to create PPO model")?; let mut best_val_loss = f64::MAX; let mut epochs_without_improvement = 0_usize; let n_train = train_features.len(); if n_train < 2 { warn!(" [PPO] Fold {} — insufficient training features ({})", fold, n_train); return Ok(f64::MAX); } for epoch in 0..args.epochs { // --- Collect trajectory --- let trajectory = collect_ppo_trajectory( &ppo, train_features, train_bars, args, )?; if trajectory.length < 2 { warn!(" [PPO] Fold {} Epoch {} — trajectory too short", fold, epoch + 1); continue; } // Compute GAE advantages and returns let trajectories = vec![trajectory]; let (advantages, returns) = match compute_gae(&trajectories, &config.gae_config) { Ok((adv, ret)) => (adv, ret), Err(e) => { warn!(" [PPO] Fold {} Epoch {} GAE failed: {}", fold, epoch + 1, e); continue; } }; let mut batch = TrajectoryBatch::from_trajectories( trajectories, advantages, returns, ); // PPO update match ppo.update(&mut batch) { Ok((policy_loss, value_loss)) => { // --- Validation pass --- let val_loss = evaluate_ppo_validation(val_features, val_bars); info!( " [PPO] Fold {} Epoch {}/{} — policy_loss={:.6} value_loss={:.6} val_metric={:.6}", fold, epoch + 1, args.epochs, policy_loss, value_loss, val_loss ); // Early stopping check if val_loss < best_val_loss { best_val_loss = val_loss; epochs_without_improvement = 0; // Save checkpoint let actor_path = output_dir.join(format!("ppo_fold{}_actor.safetensors", fold)); let critic_path = output_dir.join(format!("ppo_fold{}_critic.safetensors", fold)); let meta_path = output_dir.join(format!("ppo_fold{}_meta.json", fold)); if let Err(e) = ppo.save_checkpoint( &actor_path.to_string_lossy(), &critic_path.to_string_lossy(), &meta_path.to_string_lossy(), ) { warn!(" [PPO] Failed to save checkpoint: {}", e); } else { info!(" [PPO] Saved best checkpoint: {}", actor_path.display()); } } else { epochs_without_improvement += 1; if epochs_without_improvement >= args.patience { info!( " [PPO] Early stopping at epoch {} (patience {} exhausted)", epoch + 1, args.patience ); break; } } } Err(e) => { warn!(" [PPO] Fold {} Epoch {} update error: {}", fold, epoch + 1, e); } } } Ok(best_val_loss) } /// Collect a single trajectory from training data for PPO. fn collect_ppo_trajectory( ppo: &PPO, features: &[[f64; 51]], bars: &[OHLCVBar], args: &Args, ) -> Result { use ml::dqn::TradingAction; let mut trajectory = Trajectory::new(); let n = features.len(); let mut rng = rand::thread_rng(); for i in 0..n.saturating_sub(1) { let state_f64 = match features.get(i) { Some(f) => f, None => continue, }; let state: Vec = state_f64.iter().map(|&v| v as f32).collect(); // Get action and value from PPO let (action, value) = match ppo.act(&state) { Ok((a, v)) => (a, v), Err(_) => { // Fallback: random action with zero value let a = match rng.gen_range(0..args.num_actions) { 0 => TradingAction::Buy, 1 => TradingAction::Sell, _ => TradingAction::Hold, }; (a, 0.0_f32) } }; // Compute log probability estimate (uniform prior as approximation) let log_prob = -(args.num_actions as f32).ln(); // Compute reward let close_cur = bars.get(i).map(|b| b.close).unwrap_or(0.0); let close_next = bars.get(i + 1).map(|b| b.close).unwrap_or(close_cur); let action_idx = action.to_int(); let reward = compute_reward(close_cur, close_next, action_idx); let done = i + 2 >= n; let step = TrajectoryStep::new(state, action, log_prob, value, reward, done); trajectory.add_step(step); } Ok(trajectory) } /// Evaluate PPO validation performance (average absolute price change). fn evaluate_ppo_validation(val_features: &[[f64; 51]], val_bars: &[OHLCVBar]) -> f64 { let n = val_features.len(); if n < 2 { return f64::MAX; } let mut total = 0.0_f64; let mut count = 0_usize; for i in 0..n.saturating_sub(1) { let close_cur = val_bars.get(i).map(|b| b.close).unwrap_or(0.0); let close_next = val_bars.get(i + 1).map(|b| b.close).unwrap_or(close_cur); total += (close_next - close_cur).abs(); count += 1; } if count > 0 { total / count as f64 } else { f64::MAX } } // --------------------------------------------------------------------------- // Main // --------------------------------------------------------------------------- fn main() -> Result<()> { // Initialize tracing tracing_subscriber::fmt() .with_env_filter( tracing_subscriber::EnvFilter::try_from_default_env() .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")), ) .init(); let args = Args::parse(); let train_dqn = args.model == "dqn" || args.model == "both"; let train_ppo = args.model == "ppo" || args.model == "both"; info!("=== Walk-Forward Baseline Training ==="); info!(" Model(s): {}", args.model); info!(" Epochs: {}", args.epochs); info!(" Batch size: {}", args.batch_size); info!(" Data dir: {}", args.data_dir.display()); info!(" Output dir: {}", args.output_dir.display()); info!(" Feature dim: {}", args.feature_dim); info!(" Num actions: {}", args.num_actions); info!(" Patience: {}", args.patience); // 1. Load all OHLCV bars from DBN files info!("Step 1/5: Loading OHLCV bars from DBN files..."); let bars = load_all_bars(&args.data_dir)?; if bars.is_empty() { anyhow::bail!("No bars loaded from {}", args.data_dir.display()); } info!(" Loaded {} bars ({} to {})", bars.len(), bars.first().map(|b| b.timestamp.to_string()).unwrap_or_default(), bars.last().map(|b| b.timestamp.to_string()).unwrap_or_default(), ); // 2. Extract features info!("Step 2/5: Extracting {}-dimensional features...", args.feature_dim); let all_features = extract_ml_features(&bars) .context("Feature extraction failed")?; info!(" Extracted {} feature vectors (warmup period consumed {} bars)", all_features.len(), bars.len().saturating_sub(all_features.len()), ); // Since features skip the warmup period, we need bars aligned to features. // Features start at bar index warmup_offset (typically 50). let warmup_offset = bars.len().saturating_sub(all_features.len()); let aligned_bars = if warmup_offset < bars.len() { &bars[warmup_offset..] } else { &bars }; // 3. Generate walk-forward windows info!("Step 3/5: Generating walk-forward windows..."); let wf_config = WalkForwardConfig::default(); let windows = generate_walk_forward_windows(aligned_bars, &wf_config); if windows.is_empty() { anyhow::bail!( "No walk-forward windows generated. Need at least {} months of data.", wf_config.initial_train_months + wf_config.val_months + wf_config.test_months ); } info!(" Generated {} walk-forward folds", windows.len()); // Create output directory std::fs::create_dir_all(&args.output_dir) .with_context(|| format!("Failed to create output dir: {}", args.output_dir.display()))?; // 4. Train each fold info!("Step 4/5: Training models on each fold..."); let mut dqn_results: Vec<(usize, f64)> = Vec::new(); let mut ppo_results: Vec<(usize, f64)> = Vec::new(); for window in &windows { info!("--- Fold {} ---", window.fold); info!( " Train: {} bars (up to {}), Val: {} bars (up to {}), Test: {} bars (up to {})", window.train.len(), window.train_end, window.val.len(), window.val_end, window.test.len(), window.test_end, ); // Extract features for this fold's train and val sets let train_feat = match extract_ml_features(&window.train) { Ok(f) => f, Err(e) => { warn!(" Fold {} — train feature extraction failed: {}", window.fold, e); continue; } }; let val_feat = match extract_ml_features(&window.val) { Ok(f) => f, Err(e) => { warn!(" Fold {} — val feature extraction failed: {}", window.fold, e); continue; } }; if train_feat.is_empty() || val_feat.is_empty() { warn!(" Fold {} — empty features, skipping", window.fold); continue; } // Compute NormStats from training features only let norm_stats = NormStats::from_features(&train_feat); // Normalize features let train_norm = norm_stats.normalize_batch(&train_feat); let val_norm = norm_stats.normalize_batch(&val_feat); // Save NormStats let norm_path = args.output_dir.join(format!("norm_stats_fold{}.json", window.fold)); let norm_json = serde_json::to_string_pretty(&norm_stats) .context("Failed to serialize NormStats")?; std::fs::write(&norm_path, norm_json) .with_context(|| format!("Failed to write {}", norm_path.display()))?; info!(" Saved NormStats to {}", norm_path.display()); // Aligned bars for features (train features skip warmup period of train bars) let train_warmup = window.train.len().saturating_sub(train_norm.len()); let train_bars_aligned = if train_warmup < window.train.len() { &window.train[train_warmup..] } else { &window.train }; let val_warmup = window.val.len().saturating_sub(val_norm.len()); let val_bars_aligned = if val_warmup < window.val.len() { &window.val[val_warmup..] } else { &window.val }; // Train DQN if train_dqn { match train_dqn_fold( window.fold, &train_norm, &val_norm, train_bars_aligned, val_bars_aligned, &args, &args.output_dir, ) { Ok(best_loss) => { dqn_results.push((window.fold, best_loss)); } Err(e) => { error!(" [DQN] Fold {} failed: {}", window.fold, e); } } } // Train PPO if train_ppo { match train_ppo_fold( window.fold, &train_norm, &val_norm, train_bars_aligned, val_bars_aligned, &args, &args.output_dir, ) { Ok(best_loss) => { ppo_results.push((window.fold, best_loss)); } Err(e) => { error!(" [PPO] Fold {} failed: {}", window.fold, e); } } } } // 5. Summary info!("Step 5/5: Training Summary"); info!(" ==================================="); if train_dqn { info!(" DQN Results ({} folds):", dqn_results.len()); for (fold, loss) in &dqn_results { info!(" Fold {}: best_val_metric = {:.6}", fold, loss); } if !dqn_results.is_empty() { let avg: f64 = dqn_results.iter().map(|(_, l)| l).sum::() / dqn_results.len() as f64; info!(" Average: {:.6}", avg); } } if train_ppo { info!(" PPO Results ({} folds):", ppo_results.len()); for (fold, loss) in &ppo_results { info!(" Fold {}: best_val_metric = {:.6}", fold, loss); } if !ppo_results.is_empty() { let avg: f64 = ppo_results.iter().map(|(_, l)| l).sum::() / ppo_results.len() as f64; info!(" Average: {:.6}", avg); } } info!(" Checkpoints saved to: {}", args.output_dir.display()); info!(" ==================================="); Ok(()) }