//! ML Model Trainers with gRPC Integration
//!
//! Production-grade trainers for all ML models in the Foxhunt system,
//! designed to integrate seamlessly with the ML Training Service gRPC interface.
//!
//! ## Available Trainers
//!
//! - **MAMBA-2**: State space model optimized for 4GB VRAM with gradient checkpointing
//! - **TFT (Temporal Fusion Transformer)**: Time series forecasting with attention
//! - **DQN**: Deep Q-Network for reinforcement learning
//! - **PPO**: Proximal Policy Optimization
//! - **Liquid Networks**: Continuous-time neural ODEs
//! - **TLOB**: Temporal Limit Order Book transformer
//!
//! ## Features
//!
//! - Real-time training progress streaming via gRPC
//! - GPU acceleration with memory-efficient operations (4GB VRAM optimized)
//! - Checkpoint management with MinIO/S3 integration
//! - Comprehensive metrics reporting (loss, perplexity, state statistics)
//! - Resource usage monitoring (CPU, memory, GPU)
//! - Early stopping and learning rate scheduling
//! - Teacher forcing for sequence models
//!
//! ## MAMBA-2 Trainer Example
//!
//! ```rust,no_run
//! use ml::trainers::mamba2::{Mamba2Trainer, Mamba2Hyperparameters};
//! use ml_core::device::MlDevice;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Configure MAMBA-2 trainer (validated for 4GB VRAM)
//!     let hyperparameters = Mamba2Hyperparameters {
//!         learning_rate: 1e-4,
//!         batch_size: 8,       // Conservative for GPU memory
//!         d_model: 256,        // Hidden dimension
//!         n_layers: 6,         // Number of layers
//!         state_size: 32,      // SSM state dimension
//!         dropout: 0.1,
//!         epochs: 100,
//!         seq_len: 128,        // Sequence length
//!         grad_clip: 1.0,
//!         weight_decay: 1e-4,
//!         warmup_steps: 1000,
//!     };
//!
//!     // Create trainer with checkpoint path
//!     let checkpoint_path = Some("s3://foxhunt-ml-models/mamba2/my-job".to_owned());
//!     let mut trainer = Mamba2Trainer::new(hyperparameters, checkpoint_path)?;
//!
//!     // Create dummy training data (replace with real market data)
//!     let device = Device::cuda_if_available(0)?;
//!     let train_data: Vec<(Tensor, Tensor)> = vec![
//!         (
//!             Tensor::randn(0.0, 1.0, (8, 128, 256), &device)?,
//!             Tensor::randn(0.0, 1.0, (8, 1), &device)?,
//!         )
//!     ];
//!     let val_data = train_data.clone();
//!
//!     // Train with real-time progress updates
//!     let training_history = trainer.train(&train_data, &val_data).await?;
//!
//!     println!("Training complete: {} epochs", training_history.len());
//!     println!("Best validation loss: {:.6}", trainer.best_val_loss);
//!
//!     Ok(())
//! }
//! ```

pub mod curriculum;
pub mod dqn;
pub mod liquid;
pub mod mamba2;
pub mod online_learning;
pub mod ppo;
pub mod tft;
pub mod tft_parquet; // DBN/OHLCV bar training extension for TFT
pub mod tlob;

/// Target network update strategy for DQN training
#[derive(Debug, Clone, Copy)]
pub enum TargetUpdateMode {
    /// Polyak averaging (soft target updates): θ_target = (1-τ)θ_target + τθ_online
    /// Rainbow DQN standard with smoother Q-value tracking
    Soft,
    /// Hard target updates: Full copy every N steps (legacy)
    /// Causes sudden Q-value shifts but simpler implementation
    Hard,
}

impl Default for TargetUpdateMode {
    fn default() -> Self {
        TargetUpdateMode::Soft
    }
}

// Re-export commonly used types
pub use dqn::{DQNHyperparameters, DQNTrainer};
pub use mamba2::{
    Mamba2Hyperparameters, Mamba2Trainer, ProgressCallback, TrainingMetrics, TrainingProgress,
};
pub use ppo::{PpoHyperparameters, PpoTrainer, PpoTrainingMetrics};
pub use tft::{
    ResourceUsage as TFTResourceUsage, TFTTrainer, TFTTrainerConfig,
    TrainingMetrics as TFTTrainingMetrics, TrainingProgress as TFTTrainingProgress,
};
pub use liquid::{LiquidHyperparameters, LiquidTrainer, LiquidTrainingMetrics};
pub use tlob::{TLOBHyperparameters, TLOBTrainer, TLOBTrainingMetrics};
