foxhunt/crates/ml-dqn/src/lib.rs

//! Deep Q-Learning Network implementation for trading
//!
//! This crate includes both the original DQN implementation and the enhanced Rainbow DQN
//! with all 6 components: Double Q-learning, Dueling Networks, Prioritized Experience Replay,
//! Multi-step Learning, Distributional RL (C51), and Noisy Networks.

#![allow(clippy::module_name_repetitions)]
#![allow(clippy::integer_division)]
#![allow(clippy::shadow_reuse, clippy::shadow_same, clippy::shadow_unrelated)] // Tensor ops: let x = x.relu() is idiomatic
#![allow(clippy::non_ascii_literal)] // Math symbols in ML documentation and error messages
#![allow(clippy::partial_pub_fields)] // ML config structs: some fields are pub API, some internal
#![allow(clippy::same_name_method)] // Intentional: inherent methods shadow trait defaults for ML-specific behavior
#![allow(clippy::indexing_slicing)] // Tensor/matrix indexing with bounds guaranteed by construction
#![allow(clippy::similar_names)] // ML naming: min_val/max_val, state/states are conventional
#![allow(clippy::type_complexity)] // Complex generic types in neural network layers
#![allow(clippy::single_char_lifetime_names)] // 'a is idiomatic Rust

// Re-export shared modules from ml-core for convenience
pub use ml_core::action_space;
pub use ml_core::order_router;
pub use ml_core::xavier_init;
pub use ml_core::portfolio_tracker;
pub use ml_core::trading_action;
pub use ml_core::trading_action::TradingAction;

// Original DQN components
pub mod count_bonus;
pub mod agent;
pub mod attention;
pub mod circuit_breaker;
pub mod curiosity;
pub mod dqn;
pub mod experience;
pub mod gae;
pub mod hindsight_replay;
pub mod logging;
pub mod network;
pub mod nstep_buffer;
pub mod regime_conditional;
pub mod replay_buffer;
pub mod residual;
pub mod reward;
pub mod softmax;
pub mod logit_clipping;
pub mod target_update;
pub mod trade_executor;

// Wave 16 Portfolio Features
pub mod entropy_regularization;
pub mod multi_asset;

// Branching DQN (Phase C+)
pub mod branching;

#[cfg(test)]
mod branching_composition_tests;
#[cfg(test)]
mod dsr_gpu_tests;
#[cfg(test)]
mod nstep_gpu_tests;

// Rainbow DQN components
pub mod distributional;
pub mod distributional_dueling;
pub mod dueling;
pub mod noisy_layers;
pub mod quantile_regression;
pub mod noisy_sigma_scheduler;
pub mod rainbow_agent;
pub mod rainbow_config;
pub mod rainbow_integration;
pub mod rainbow_network;

// Replay buffer types
pub mod prioritized_replay;
pub mod prioritized_replay_staleness;
pub mod replay_buffer_type;

pub mod experience_dataset;
pub mod iql;

pub mod noisy_exploration;

// Performance validation
pub mod performance_tests;
pub mod performance_validation;

// Wave 26 P2.3: Ensemble Q-network for uncertainty estimation
pub mod ensemble_network;

// Wave 26 P2.4: RMSNorm
pub mod rmsnorm;

// GPU-resident replay buffer (DQN-specific)
pub mod gpu_replay_buffer;

// Checkpoint (Checkpointable impl for DQNAgent)
pub mod checkpoint;

// DQN evaluation (backtesting engine, metrics, reports)
pub mod evaluation;

// Re-export core DQN types for public usage
pub use action_space::{ExposureLevel, FactoredAction, OrderType, Urgency};
pub use order_router::OrderRouter;
pub use agent::{AgentMetrics, DQNAgent, TradingState};
pub use dqn::{GradientResult, DQN, DQNConfig};
pub use experience::{Experience, ExperienceBatch};
pub use nstep_buffer::NStepBuffer;
pub use portfolio_tracker::PortfolioTracker;
pub use replay_buffer::{ReplayBuffer, ReplayBufferConfig, ReplayBufferStats};
pub use trade_executor::{
    ExecutionCostConfig, ExecutionResult, RejectionReason, RiskControlConfig, TradeExecutor,
};

// Re-export network components
pub use network::{QNetwork, QNetworkConfig};

// Re-export reward components
pub use reward::{MarketData, RewardConfig, RewardFunction, RiskMetrics};

// Re-export Rainbow DQN components
pub use distributional::{CategoricalDistribution, DistributionalConfig, DistributionalType};
pub use distributional_dueling::{DistributionalDuelingConfig, DistributionalDuelingQNetwork};
pub use branching::{BranchingConfig, BranchingDuelingQNetwork, BranchOutput};
pub use dueling::{DuelingConfig, DuelingQNetwork};
pub use quantile_regression::{QuantileConfig, QuantileNetwork, quantile_huber_loss};
pub use rainbow_agent::RainbowAgent;
pub use rainbow_config::{RainbowAgentConfig, RainbowAgentMetrics, RainbowDQNConfig};
pub use rainbow_network::{RainbowNetwork, RainbowNetworkConfig};

// Re-export prioritized replay components
pub use prioritized_replay::{PrioritizedReplayBuffer, PrioritizedReplayConfig};
pub use replay_buffer_type::{BatchSample, ReplayBufferType};

// Re-export regime-conditional DQN components
pub use regime_conditional::{RegimeClassConfig, RegimeConditionalDQN, RegimeMetrics, RegimeType};

// Re-export logit clipping utilities
pub use logit_clipping::{clip_logits, clip_logits_default, softmax_with_clipping, DEFAULT_CLIP_MAX};

// Re-export GAE components
pub use gae::{GAECalculator, GAEConfig};

// Re-export Hindsight Experience Replay components
pub use hindsight_replay::{
    HindsightReplayBuffer, HindsightReplayConfig, HindsightReplayStats, HindsightStrategy,
};

// Re-export ensemble network components
pub use ensemble_network::{EnsembleConfig, EnsembleQNetwork};

// Re-export RMSNorm components
pub use rmsnorm::{LayerNorm, NormType, RMSNorm};

// Re-export offline RL components
pub use experience_dataset::ExperienceDataset;
pub use iql::IqlConfig;