test(ppo): add checkpoint roundtrip and hyperopt validation tests

- ppo_checkpoint_roundtrip_test: save/load PPO model, verify predictions
  match within 1e-6 tolerance (validated: max diff 3.73e-8)
- ppo_hyperopt_validation_test: 5-trial PSO optimization with 11
  assertions covering convergence, param bounds, and result structure

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ml/tests/ppo_hyperopt_validation_test.rs

@@ -0,0 +1,228 @@
+//! PPO Hyperopt Validation Test
+//!
+//! Validates PPO hyperparameter optimization pipeline end-to-end.
+//! Runs 5 trials of PSO optimization and verifies convergence,
+//! result structure, and parameter bounds.
+//!
+//! Run manually:
+//!   SQLX_OFFLINE=true cargo test -p ml --test ppo_hyperopt_validation_test -- --ignored --nocapture
+//!
+//! Expected runtime: 15-30 minutes (GPU), 45-90 minutes (CPU)
+
+#![allow(unused_crate_dependencies)]
+
+use anyhow::{Context, Result};
+use std::path::PathBuf;
+
+use ml::hyperopt::adapters::ppo::PPOTrainer;
+use ml::hyperopt::ArgminOptimizer;
+
+/// Locate the real training data directory.
+///
+/// Returns `Ok(path)` if the directory exists, `Err` otherwise so the test
+/// can skip gracefully without marking as failed.
+fn get_data_dir() -> Result<PathBuf> {
+    let workspace_root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .context("Failed to resolve workspace root")?
+        .to_path_buf();
+
+    let data_dir = workspace_root.join("test_data/real/databento/ml_training_small");
+    if !data_dir.exists() {
+        anyhow::bail!(
+            "Training data not found at {}. \
+             This test requires real Databento data to run.",
+            data_dir.display()
+        );
+    }
+    Ok(data_dir)
+}
+
+#[test]
+#[ignore]
+fn test_ppo_hyperopt_5_trials() -> Result<()> {
+    // --- Setup ---
+    let data_dir = match get_data_dir() {
+        Ok(dir) => dir,
+        Err(e) => {
+            eprintln!("Skipping test: {e}");
+            return Ok(());
+        }
+    };
+
+    let start = std::time::Instant::now();
+    let num_trials: usize = 5;
+    let n_initial: usize = 2;
+    let episodes_per_trial: usize = 10;
+
+    // --- Create trainer and optimizer ---
+    let trainer = PPOTrainer::new(&data_dir, episodes_per_trial)
+        .context("Failed to create PPOTrainer")?;
+
+    let optimizer = ArgminOptimizer::builder()
+        .max_trials(num_trials)
+        .n_initial(n_initial)
+        .n_particles(3) // small swarm for test speed
+        .seed(42)
+        .build();
+
+    // --- Run optimization ---
+    let result = optimizer
+        .optimize(trainer)
+        .context("Hyperopt optimization failed")?;
+
+    let elapsed = start.elapsed();
+
+    // --- Assertions ---
+
+    // 1. All trials should have completed (at least n_initial; PSO may add more)
+    let trials_completed = result.all_trials.len();
+    assert!(
+        trials_completed >= n_initial,
+        "Expected at least {n_initial} trials, got {trials_completed}"
+    );
+
+    // 2. Best objective should be finite (not NaN or Inf)
+    assert!(
+        result.best_objective.is_finite(),
+        "Best objective is not finite: {}",
+        result.best_objective
+    );
+
+    // 3. Every trial objective should be finite with positive duration
+    for trial in &result.all_trials {
+        assert!(
+            trial.objective.is_finite(),
+            "Trial {} has non-finite objective: {}",
+            trial.trial_num,
+            trial.objective
+        );
+        assert!(
+            trial.duration_secs > 0.0,
+            "Trial {} has non-positive duration: {}",
+            trial.trial_num,
+            trial.duration_secs
+        );
+    }
+
+    // 4. Best objective should be <= first trial (optimizer should not regress)
+    if let Some(first_trial) = result.all_trials.first() {
+        assert!(
+            result.best_objective <= first_trial.objective,
+            "Optimizer regressed: best={} > first={}",
+            result.best_objective,
+            first_trial.objective
+        );
+    }
+
+    // 5. Convergence plot should have entries matching trial count
+    assert_eq!(
+        result.convergence_plot_data.len(),
+        trials_completed,
+        "Convergence plot entries ({}) should match trial count ({trials_completed})",
+        result.convergence_plot_data.len()
+    );
+
+    // 6. Convergence plot should be monotonically non-increasing
+    for window in result.convergence_plot_data.windows(2) {
+        let (_, prev_best) = window[0];
+        let (_, curr_best) = window[1];
+        assert!(
+            curr_best <= prev_best + f64::EPSILON,
+            "Convergence plot is not monotonically non-increasing: {prev_best} -> {curr_best}"
+        );
+    }
+
+    // 7. Best policy learning rate should be in sane range
+    let best_policy_lr = result.best_params.policy_learning_rate;
+    assert!(
+        best_policy_lr > 1e-7 && best_policy_lr < 1.0,
+        "Best policy learning rate out of sane range: {best_policy_lr}"
+    );
+
+    // 8. Best value learning rate should be in sane range
+    let best_value_lr = result.best_params.value_learning_rate;
+    assert!(
+        best_value_lr > 1e-7 && best_value_lr < 1.0,
+        "Best value learning rate out of sane range: {best_value_lr}"
+    );
+
+    // 9. Clip epsilon should be within configured bounds
+    let best_clip = result.best_params.clip_epsilon;
+    assert!(
+        best_clip >= 0.1 && best_clip <= 0.3,
+        "Best clip epsilon out of bounds [0.1, 0.3]: {best_clip}"
+    );
+
+    // 10. Value loss coefficient should be within configured bounds
+    let best_vlc = result.best_params.value_loss_coeff;
+    assert!(
+        best_vlc >= 0.5 && best_vlc <= 2.0,
+        "Best value loss coeff out of bounds [0.5, 2.0]: {best_vlc}"
+    );
+
+    // 11. Entropy coefficient should be in sane range
+    let best_entropy = result.best_params.entropy_coeff;
+    assert!(
+        best_entropy > 1e-5 && best_entropy < 1.0,
+        "Best entropy coeff out of sane range: {best_entropy}"
+    );
+
+    // --- Report ---
+    println!("\n{}", "=".repeat(70));
+    println!("  PPO HYPEROPT REPORT");
+    println!("{}", "=".repeat(70));
+    println!("  Trials completed : {trials_completed}");
+    println!("  Best objective   : {:.6}", result.best_objective);
+    println!(
+        "  Best policy LR   : {:.2e}",
+        result.best_params.policy_learning_rate
+    );
+    println!(
+        "  Best value LR    : {:.2e}",
+        result.best_params.value_learning_rate
+    );
+    println!(
+        "  Best clip eps     : {:.4}",
+        result.best_params.clip_epsilon
+    );
+    println!(
+        "  Best value coeff  : {:.4}",
+        result.best_params.value_loss_coeff
+    );
+    println!(
+        "  Best entropy coeff: {:.6}",
+        result.best_params.entropy_coeff
+    );
+    println!("  Total time       : {:.1}s", elapsed.as_secs_f64());
+    println!(
+        "  Avg time/trial   : {:.1}s",
+        elapsed.as_secs_f64() / trials_completed as f64
+    );
+    println!("{}", "-".repeat(70));
+    println!("  TRIAL HISTORY");
+    println!("{}", "-".repeat(70));
+    for trial in &result.all_trials {
+        println!(
+            "    Trial {:>2} | obj: {:>10.4} | time: {:>6.1}s | plr: {:.2e} | vlr: {:.2e} | clip: {:.3}",
+            trial.trial_num,
+            trial.objective,
+            trial.duration_secs,
+            trial.params.policy_learning_rate,
+            trial.params.value_learning_rate,
+            trial.params.clip_epsilon,
+        );
+    }
+    println!("{}", "-".repeat(70));
+    println!("  CONVERGENCE");
+    println!("{}", "-".repeat(70));
+    for (trial_num, best_so_far) in &result.convergence_plot_data {
+        println!(
+            "    Trial {:>2} | best so far: {:>10.4}",
+            trial_num, best_so_far
+        );
+    }
+    println!("{}", "=".repeat(70));
+
+    Ok(())
+}