foxhunt/crates/ml/src/microstructure/mod.rs

//! # Advanced Microstructure ML Module
//!
//! Comprehensive machine learning enhanced market microstructure analysis for
//! high-frequency trading alpha generation. All components target <25μs latency
//! with advanced ML models for superior prediction accuracy.
//!
//! ## Core ML Models (7 Advanced Models)
//!
//! - **Order Flow Imbalance Predictor**: LSTM-Transformer hybrid for OFI prediction
//! - **Liquidity Provision Optimizer**: Multi-output neural network for optimal liquidity provision
//! - **Spread Predictor**: Time series transformer for bid-ask spread forecasting
//! - **Market Impact Estimator**: Temporal CNN for price impact estimation
//! - **Adverse Selection Detector**: Deep learning model for toxicity detection
//! - **Price Discovery Model**: Information flow analysis and efficiency measurement
//! - **Hidden Liquidity Detector**: Pattern recognition for dark pools and icebergs
//!
//! ## Integration Components
//!
//! - **ML Ensemble**: Unified ensemble combining all 7 models for robust predictions
//! - **Training Pipeline**: Comprehensive training system with unified data providers
//! - **Portfolio Integration**: Seamless integration with Portfolio Transformer
//! - **Performance Optimization**: Sub-25μs inference with real-time deployment
//!
//! ## Classical Microstructure Analytics
//!
//! - **VPIN Calculator**: Volume-synchronized probability of informed trading
//! - **Kyle's Lambda**: Price impact measurement and information asymmetry detection
//! - **Amihud Illiquidity**: Liquidity measurement via price impact per volume
//! - **Roll Spread Estimator**: Bid-ask spread estimation from price autocovariance
//! - **Hasbrouck Information Share**: Price discovery attribution analysis
//!
//! ## Performance Targets
//!
//! - ML Inference latency: <25μs for ensemble predictions
//! - Classical calculation latency: <25μs for all metrics
//! - Throughput: 100K+ calculations/second
//! - Memory efficiency: Zero-allocation hot paths
//! - Integer arithmetic: 10,000x scaling for financial precision

// VPIN Implementation Module
pub mod vpin_implementation;

// Re-export VPIN types for public API
// DO NOT RE-EXPORT - Use explicit imports at usage sites

#[cfg(test)]
mod tests {
    use crate::microstructure::vpin_implementation::{RingBuffer, TradeDirection};

    #[test]
    fn test_trade_direction_classification() {
        // Test Lee-Ready algorithm
        let direction = TradeDirection::classify_lee_ready(
            105000, // trade price (10.50)
            104000, // bid (10.40)
            106000, // ask (10.60)
            104500, // prev price (10.45)
        );
        assert_eq!(direction, TradeDirection::Buy);

        // Test tick rule
        let direction = TradeDirection::classify_tick_rule(105000, 104000);
        assert_eq!(direction, TradeDirection::Buy);
    }

    // Disabled: test_volume_bucket requires a VolumeBucket::process() method
    // that accepts a MarketDataUpdate. MarketDataUpdate is defined in three
    // separate crates (adaptive-strategy, ml::stress_testing, ml::microstructure::
    // vpin_implementation) with incompatible field sets. VolumeBucket::process()
    // currently expects vpin_implementation::MarketDataUpdate, but the test
    // needs a simplified constructor. Re-enable after consolidating
    // MarketDataUpdate into a single shared type in common/ and adding a
    // VolumeBucket::new() + process() public API.
    /*
    #[test]
    fn test_volume_bucket() {
        let mut bucket = VolumeBucket::new(0, 1000, 1000000);
        // Test implementation needed after MarketDataUpdate is defined
    }
    */

    #[test]
    fn test_ring_buffer() {
        let mut buffer = RingBuffer::new(3);

        buffer.push(1);
        buffer.push(2);
        buffer.push(3);

        assert_eq!(buffer.len(), 3);
        assert_eq!(buffer.get(0), Some(&1));
        assert_eq!(buffer.get(1), Some(&2));
        assert_eq!(buffer.get(2), Some(&3));

        buffer.push(4);
        assert_eq!(buffer.len(), 3);
        assert_eq!(buffer.get(0), Some(&2));
        assert_eq!(buffer.get(1), Some(&3));
        assert_eq!(buffer.get(2), Some(&4));
    }

    // Disabled: references ml::microstructure::utils module which does not
    // exist. The planned utils module would provide integer-arithmetic helpers
    // (calculate_returns, moving_average, autocovariance, fast_sqrt) operating
    // on i64 scaled prices (10,000x precision). Re-enable after creating
    // ml/src/microstructure/utils.rs with these functions and adding
    // `pub mod utils;` to this file.
    // #[test]
    // fn test_utils_functions() {
    //     let prices = vec![100000, 101000, 99000, 102000];
    //     let returns = utils::calculate_returns(&prices);
    //     assert_eq!(returns.len(), 3);
    //
    //     let values = vec![1000, 2000, 3000, 4000, 5000];
    //     let ma = utils::moving_average(&values, 3);
    //     assert_eq!(ma.len(), 3);
    //     assert_eq!(ma[0], 2000); // (1000 + 2000 + 3000) / 3
    //
    //     let cov = utils::autocovariance(&values, 1);
    //     assert!(cov > 0); // Should be positive for trending series
    //
    //     let sqrt_val = utils::fast_sqrt(10000);
    //     assert_eq!(sqrt_val, 100);
    // }
} // end tests module