foxhunt/WAVE_C_ML_INTEGRATION_DESIGN.md

Wave C: ML Model Integration Design

Date: 2025-10-17 Mission: Design integration between Wave C features (256-dim) and ML models (DQN/PPO/MAMBA-2/TFT) Status: DESIGN COMPLETE - Ready for Implementation

---

1. Executive Summary

This document specifies the integration pipeline for feeding Wave C's 256-dimensional feature vectors into Foxhunt's ML models. The design ensures:

1. Dimensional Compatibility: 256-feature input → model-specific input layers
2. Feature Validation: Range checks, correlation analysis, stationarity tests
3. Feature Selection: Importance ranking, PCA, autoencoder compression
4. Data Pipeline: Efficient transformation with zero data leakage

---

2. Feature Pipeline Architecture

2.1 High-Level Flow

OHLCV Bars (DBN/Real Data)
    ↓
ml::features::extraction::extract_ml_features()
    ↓
256-dim Feature Vector [f64; 256]
    ↓
Feature Validation Layer
    ↓
Feature Selection/Engineering Layer
    ↓
Model-Specific Input Adapter
    ↓
[DQN | PPO | MAMBA-2 | TFT] → Prediction

2.2 Feature Vector Breakdown (256 dimensions)

From /home/jgrusewski/Work/foxhunt/ml/src/features/extraction.rs:

Index Range	Count	Feature Category	Description
0-4	5	OHLCV	Normalized open/high/low/close/volume
5-14	10	Technical Indicators	RSI, MACD, Bollinger, ATR, EMA
15-74	60	Price Patterns	Returns, trends, levels, momentum
75-114	40	Volume Patterns	Volume statistics, ratios, price-volume
115-164	50	Microstructure Proxies	Roll Measure, Amihud, Corwin-Schultz, spread estimates
165-174	10	Time-Based	Hour, day, market session, month/quarter end
175-255	81	Statistical	Rolling mean/std/percentiles, correlations, volatility

Key Properties:

• All features normalized to finite ranges (mostly [0, 1] or [-1, 1])
• No NaN/Inf validation enforced in validate_features()
• Rolling window state maintained in FeatureExtractor for O(1) updates

---

3. Model-Specific Integration

3.1 DQN (Deep Q-Network)

Current Implementation: /home/jgrusewski/Work/foxhunt/ml/src/dqn/dqn.rs

// DQN Config (lines 29-52)
pub struct WorkingDQNConfig {
    pub state_dim: usize,        // 256 for Wave C
    pub num_actions: usize,      // 3 (BUY/SELL/HOLD)
    pub hidden_dims: Vec<usize>, // [256, 128, 64]
    pub learning_rate: f64,      // 1e-4
    pub gamma: f32,              // 0.99
    // ... replay buffer, epsilon-greedy params
}

Integration Design:

// DQN Input Adapter
pub struct DQNFeatureAdapter {
    feature_dim: usize,          // 256
    feature_normalizer: FeatureNormalizer,
    feature_selector: Option<FeatureSelector>,
}

impl DQNFeatureAdapter {
    pub fn transform(&self, features: &[f64; 256]) -> Result<Tensor> {
        // 1. Validate input dimensions
        assert_eq!(features.len(), 256);

        // 2. Apply feature selection if configured
        let selected_features = match &self.feature_selector {
            Some(selector) => selector.select(features)?,
            None => features.to_vec(),
        };

        // 3. Convert to Tensor for DQN forward pass
        // Shape: [batch_size=1, state_dim=256]
        let tensor = Tensor::from_vec(
            selected_features,
            (1, self.feature_dim),
            &Device::Cpu
        )?;

        Ok(tensor)
    }
}

// DQN Forward Pass
// Input: [batch_size, 256] → Hidden: [batch_size, 256] → [batch_size, 128] → [batch_size, 64]
//                          → Output: [batch_size, 3] (Q-values for BUY/SELL/HOLD)

Performance Expectations:

• Inference: ~200μs (sub-millisecond requirement met)
• GPU Memory: 6MB (well below 200MB target)
• Training: 50-150MB GPU (validated in Wave 7)

3.2 PPO (Proximal Policy Optimization)

Current Implementation: /home/jgrusewski/Work/foxhunt/ml/src/ppo/ppo.rs

// PPO Config (lines 32-66)
pub struct PPOConfig {
    pub observation_dim: usize,   // 256 for Wave C
    pub action_dim: usize,        // 1 (continuous position sizing)
    pub hidden_dims: Vec<usize>,  // [256, 128]
    pub learning_rate: f64,       // 3e-4
    pub gamma: f64,               // 0.99
    pub gae_lambda: f64,          // 0.95 (Generalized Advantage Estimation)
    pub clip_epsilon: f64,        // 0.2 (PPO clipping ratio)
    // ... value network, entropy coef
}

Integration Design:

// PPO Input Adapter
pub struct PPOFeatureAdapter {
    observation_dim: usize,      // 256
    feature_extractor: Arc<FeatureExtractor>,
    state_normalizer: RunningMeanStd,
}

impl PPOFeatureAdapter {
    pub fn get_observation(&mut self, features: &[f64; 256]) -> Result<Tensor> {
        // 1. Validate dimensions
        assert_eq!(features.len(), 256);

        // 2. Normalize observations using running statistics
        let normalized = self.state_normalizer.normalize(features)?;

        // 3. Convert to Tensor for PPO actor-critic network
        // Shape: [batch_size=1, observation_dim=256]
        let tensor = Tensor::from_vec(
            normalized,
            (1, self.observation_dim),
            &Device::Cpu
        )?;

        Ok(tensor)
    }
}

// PPO Forward Pass (Actor-Critic Architecture)
// Input: [batch_size, 256] → Actor Network → [batch_size, 2] (mean, std for continuous action)
//                          → Critic Network → [batch_size, 1] (state value)
// Action Sampling: N(mean, std) → continuous position size [-1, 1]

Performance Expectations:

• Inference: 324μs (validated in Wave 7.18)
• GPU Memory: 145MB (27.5% below 200MB target)
• Training: 50-200MB GPU (validated)

3.3 MAMBA-2 (Selective State Space Model)

Current Implementation: /home/jgrusewski/Work/foxhunt/ml/src/mamba/mod.rs

// MAMBA-2 Config (lines 71-114)
pub struct Mamba2Config {
    pub d_model: usize,          // 256 (matches Wave C features)
    pub d_state: usize,          // 16 (SSM state dimension)
    pub d_conv: usize,           // 4 (1D convolution kernel size)
    pub expand: usize,           // 4 (expansion factor: d_inner = d_model * expand = 1024)
    pub n_layer: usize,          // 6 (depth)
    pub vocab_size: usize,       // 1 (regression, not classification)
    pub dropout: f64,            // 0.1
}

Integration Design:

// MAMBA-2 Input Adapter
pub struct Mamba2FeatureAdapter {
    d_model: usize,              // 256
    sequence_length: usize,      // 50 (lookback window)
    feature_buffer: VecDeque<Vec<f64>>, // Rolling sequence buffer
}

impl Mamba2FeatureAdapter {
    pub fn add_timestep(&mut self, features: &[f64; 256]) -> Result<()> {
        // 1. Validate dimensions
        assert_eq!(features.len(), 256);

        // 2. Add to rolling buffer
        self.feature_buffer.push_back(features.to_vec());
        if self.feature_buffer.len() > self.sequence_length {
            self.feature_buffer.pop_front();
        }

        Ok(())
    }

    pub fn get_sequence_tensor(&self) -> Result<Tensor> {
        // 3. Convert sequence to 3D tensor
        // Shape: [batch_size=1, sequence_length=50, d_model=256]
        let sequence_data: Vec<f64> = self.feature_buffer
            .iter()
            .flatten()
            .copied()
            .collect();

        let tensor = Tensor::from_vec(
            sequence_data,
            (1, self.sequence_length, self.d_model),
            &Device::Cpu
        )?;

        Ok(tensor)
    }
}

// MAMBA-2 Forward Pass (Sequence Modeling)
// Input: [batch, seq_len=50, d_model=256] → Embedding → SSM Layers (6x) → Output Head
//                                         → [batch, seq_len, d_model] → [batch, 1] (regression)
// SSM Internal: B/C matrices use d_inner=1024 (fixed in Wave 206)

Performance Expectations:

• Inference: ~500μs (estimated)
• GPU Memory: ~164MB (validated in production readiness)
• Training: 150-500MB GPU (validated in Wave 152 benchmark plan)

3.4 TFT (Temporal Fusion Transformer)

Current Implementation: Not directly found, but referenced in Wave 9 INT8 quantization

// TFT Config (inferred from Wave 9 docs)
pub struct TFTConfig {
    pub input_dim: usize,         // 256 (Wave C features)
    pub num_encoder_steps: usize, // Historical sequence length
    pub num_decoder_steps: usize, // Future prediction horizon
    pub hidden_dim: usize,        // 256
    pub num_heads: usize,         // 8 (multi-head attention)
    pub num_quantiles: usize,     // 9 (quantile regression for uncertainty)
    pub dropout: f64,             // 0.1
}

Integration Design:

// TFT Input Adapter
pub struct TFTFeatureAdapter {
    input_dim: usize,            // 256
    encoder_steps: usize,        // 50 (historical window)
    decoder_steps: usize,        // 10 (future prediction steps)
    historical_buffer: VecDeque<Vec<f64>>,
    time_covariates: Vec<TimeCovariate>,
}

impl TFTFeatureAdapter {
    pub fn prepare_input(&mut self, features: &[f64; 256]) -> Result<TFTInput> {
        // 1. Historical features (encoder input)
        let historical_tensor = Tensor::from_vec(
            self.historical_buffer.iter().flatten().copied().collect(),
            (1, self.encoder_steps, self.input_dim),
            &Device::Cpu
        )?;

        // 2. Known future covariates (decoder input)
        // Time features: hour, day, month, etc. (indices 165-174 from Wave C)
        let future_covariates = self.extract_time_covariates(features)?;

        // 3. Static covariates (symbol metadata, regime indicators)
        let static_covariates = self.get_static_metadata()?;

        Ok(TFTInput {
            historical: historical_tensor,
            future_covariates,
            static_covariates,
        })
    }
}

// TFT Forward Pass (Quantile Regression for Uncertainty)
// Encoder: [batch, enc_steps=50, input_dim=256] → VSN → LSTM → Context Vector
// Decoder: [batch, dec_steps=10, cov_dim] + Context → Attention → GRN
//       → Output: [batch, dec_steps, num_quantiles=9] (P10, P20, ..., P90)

Performance Expectations:

• Inference: P95 3.2ms (4x speedup via INT8, validated Wave 9)
• GPU Memory: 738MB (75% reduction via INT8, below 500MB per-component target)
• Training: 1.5-2.5GB GPU (validated in Wave 152 benchmark plan)

---

4. Feature Validation Pipeline

4.1 Data Quality Checks

pub struct FeatureValidator {
    range_validator: RangeValidator,
    correlation_detector: CorrelationDetector,
    stationarity_tester: StationarityTester,
    leakage_detector: LeakageDetector,
}

impl FeatureValidator {
    pub fn validate(&self, features: &[f64; 256]) -> Result<ValidationReport> {
        let mut report = ValidationReport::default();

        // 1. Range Validation: Ensure no NaN/Inf, values in expected bounds
        report.add_check("range", self.range_validator.check(features)?);

        // 2. Correlation Analysis: Detect multicollinearity (r > 0.95)
        report.add_check("correlation", self.correlation_detector.check(features)?);

        // 3. Stationarity Test: ADF test for time series stability
        report.add_check("stationarity", self.stationarity_tester.check(features)?);

        // 4. Leakage Detection: No future information in features
        report.add_check("leakage", self.leakage_detector.check(features)?);

        Ok(report)
    }
}

Validation Rules:

Check	Method	Threshold	Action
Range	Min/Max bounds	All features finite	Reject invalid samples
Correlation	Pearson correlation	r < 0.95	Log warning, continue
Stationarity	ADF test (Augmented Dickey-Fuller)	p-value < 0.05	Log warning, continue
Leakage	Temporal dependency analysis	No future data	Hard failure

4.2 Range Validator Implementation

pub struct RangeValidator {
    expected_ranges: HashMap<FeatureIndex, (f64, f64)>,
}

impl RangeValidator {
    pub fn check(&self, features: &[f64; 256]) -> Result<bool> {
        for (idx, &value) in features.iter().enumerate() {
            // 1. Check for NaN/Inf
            if !value.is_finite() {
                return Err(anyhow::anyhow!(
                    "Feature {} is not finite: {}", idx, value
                ));
            }

            // 2. Check against expected range
            if let Some(&(min, max)) = self.expected_ranges.get(&idx) {
                if value < min || value > max {
                    tracing::warn!(
                        "Feature {} out of range: {} not in [{}, {}]",
                        idx, value, min, max
                    );
                }
            }
        }

        Ok(true)
    }
}

4.3 Leakage Detector

Critical for Time Series: Ensure no future information leaks into features.

pub struct LeakageDetector {
    lookback_window: usize, // 50 bars
}

impl LeakageDetector {
    pub fn check(&self, features: &[f64; 256]) -> Result<bool> {
        // 1. Verify time-based features use only past data
        // Example: Indices 165-174 (time features) should be current timestamp only

        // 2. Check rolling window features don't access future bars
        // Example: Indices 175-255 (statistical) use only past N bars

        // 3. Validate forward-looking features are NOT present
        // RED FLAG: Features derived from t+1, t+2, ... future prices

        // Implementation: Track feature dependency graph
        // If any feature depends on future timesteps → FAIL

        Ok(true)
    }
}

---

5. Feature Selection & Engineering

5.1 Feature Importance Analysis

Method 1: SHAP (SHapley Additive exPlanations) Values

pub struct SHAPAnalyzer {
    model: Arc<dyn MLModel>,
    baseline_features: Vec<f64>,
}

impl SHAPAnalyzer {
    pub fn compute_feature_importance(&self, features: &[f64; 256]) -> Result<Vec<f64>> {
        let mut importance = vec![0.0; 256];

        // 1. For each feature i:
        for i in 0..256 {
            // 2. Compute model output with feature i = baseline
            let mut masked_features = features.clone();
            masked_features[i] = self.baseline_features[i];
            let baseline_pred = self.model.predict(&masked_features)?;

            // 3. Compute model output with feature i = actual
            let actual_pred = self.model.predict(features)?;

            // 4. SHAP value = difference in predictions
            importance[i] = (actual_pred - baseline_pred).abs();
        }

        Ok(importance)
    }
}

Method 2: Permutation Importance

pub struct PermutationImportance {
    model: Arc<dyn MLModel>,
    validation_data: Vec<([f64; 256], f64)>, // (features, target)
}

impl PermutationImportance {
    pub fn compute(&self) -> Result<Vec<f64>> {
        let mut importance = vec![0.0; 256];

        // 1. Compute baseline performance
        let baseline_loss = self.compute_loss(&self.validation_data)?;

        // 2. For each feature i:
        for i in 0..256 {
            // 3. Shuffle feature i across all samples
            let mut permuted_data = self.validation_data.clone();
            self.shuffle_feature(&mut permuted_data, i);

            // 4. Compute performance with permuted feature
            let permuted_loss = self.compute_loss(&permuted_data)?;

            // 5. Importance = increase in loss
            importance[i] = permuted_loss - baseline_loss;
        }

        Ok(importance)
    }
}

5.2 Feature Selection Strategies

Strategy 1: Top-K Selection

pub struct TopKSelector {
    k: usize,                     // 128 features (50% reduction)
    importance_scores: Vec<f64>,  // From SHAP/permutation
}

impl TopKSelector {
    pub fn select(&self, features: &[f64; 256]) -> Result<Vec<f64>> {
        // 1. Sort features by importance (descending)
        let mut ranked_indices: Vec<usize> = (0..256).collect();
        ranked_indices.sort_by(|&a, &b| {
            self.importance_scores[b].partial_cmp(&self.importance_scores[a])
                .unwrap_or(std::cmp::Ordering::Equal)
        });

        // 2. Select top K features
        let selected: Vec<f64> = ranked_indices
            .iter()
            .take(self.k)
            .map(|&idx| features[idx])
            .collect();

        Ok(selected)
    }
}

Strategy 2: PCA (Principal Component Analysis)

pub struct PCASelector {
    num_components: usize,        // 128 (50% variance retained)
    projection_matrix: Array2<f64>, // [256, 128]
    mean: Array1<f64>,            // [256]
}

impl PCASelector {
    pub fn transform(&self, features: &[f64; 256]) -> Result<Vec<f64>> {
        // 1. Center features
        let centered = Array1::from_vec(features.to_vec()) - &self.mean;

        // 2. Project onto principal components
        let projected = centered.dot(&self.projection_matrix);

        // 3. Return transformed features
        Ok(projected.to_vec())
    }
}

Strategy 3: Autoencoder Compression

pub struct AutoencoderSelector {
    encoder: Arc<EncoderNetwork>,
    latent_dim: usize,            // 128 (compressed representation)
}

impl AutoencoderSelector {
    pub fn encode(&self, features: &[f64; 256]) -> Result<Vec<f64>> {
        // 1. Convert to Tensor
        let input = Tensor::from_vec(
            features.to_vec(),
            (1, 256),
            &Device::Cpu
        )?;

        // 2. Forward pass through encoder
        // Architecture: [256] → [192] → [128] (latent)
        let latent = self.encoder.forward(&input)?;

        // 3. Return compressed features
        Ok(latent.to_vec1()?)
    }
}

---

6. Implementation Roadmap

Phase 1: Core Adapters (Week 1)

Tasks:

1. Implement DQNFeatureAdapter with Tensor conversion
2. Implement PPOFeatureAdapter with running normalization
3. Implement Mamba2FeatureAdapter with sequence buffering
4. Implement TFTFeatureAdapter with covariate extraction

Testing:

• Unit tests for each adapter (dimension validation, Tensor shapes)
• Integration tests with real DBN data (ES.FUT, NQ.FUT)
• Performance benchmarks (inference latency < 1ms target)

Phase 2: Validation Pipeline (Week 2)

Tasks:

1. Implement RangeValidator with finite value checks
2. Implement CorrelationDetector with Pearson correlation
3. Implement StationarityTester with ADF test
4. Implement LeakageDetector with temporal dependency tracking

Testing:

• Validation tests with synthetic edge cases (NaN, Inf, out-of-range)
• Leakage tests with intentional future data injection
• Performance profiling (validation latency < 100μs)

Phase 3: Feature Selection (Week 3)

Tasks:

1. Implement SHAPAnalyzer for DQN/PPO models
2. Implement PermutationImportance for all models
3. Implement TopKSelector with configurable K
4. Implement PCASelector with sklearn integration
5. Implement AutoencoderSelector (optional, if time permits)

Testing:

• Feature importance tests with known redundant features
• Selection tests with varying K values (64, 128, 192)
• Comparison tests (Top-K vs PCA vs Autoencoder)

Phase 4: End-to-End Integration (Week 4)

Tasks:

1. Integrate adapters into SharedMLStrategy (common/src/ml_strategy.rs)
2. Add feature validation to prediction loop
3. Add feature selection to training pipeline
4. Update TLI commands for feature analysis (tli analyze features)

Testing:

• E2E test: DBN data → 256 features → validation → selection → model prediction
• Performance test: Full pipeline latency (target: <5ms)
• Backtest validation: Ensure no data leakage in historical simulations

---

7. Performance Targets

Component	Metric	Target	Validation Method
Feature Extraction	Latency	<1ms per bar	Benchmark with 1000 bars
Feature Validation	Latency	<100μs	Benchmark with edge cases
Feature Selection (Top-K)	Latency	<50μs	Benchmark with 256 features
Feature Selection (PCA)	Latency	<200μs	Benchmark with matrix multiplication
DQN Adapter	Latency	<50μs	Tensor conversion benchmark
PPO Adapter	Latency	<100μs	Normalization + Tensor benchmark
MAMBA-2 Adapter	Latency	<200μs	Sequence buffer benchmark
TFT Adapter	Latency	<500μs	Covariate extraction benchmark
Total Pipeline	Latency	<5ms	E2E benchmark

---

8. Security & Compliance

Data Leakage Prevention

Critical Controls:

1. Temporal Isolation:

   • Features use only t-N to t data (no future information)
   • Rolling windows strictly enforce lookback constraints
   • Time-based features (indices 165-174) use current timestamp only

2. Validation Checkpoints:

   • Pre-training: Verify no leakage in feature engineering
   • Post-training: Test with intentional future data injection (should fail)
   • Production: Real-time monitoring for feature distribution drift

3. Audit Trail:

   • Log feature extraction timestamps
   • Track feature dependency graph
   • Alert on suspicious temporal patterns

Regulatory Compliance

MiFID II / SOX Requirements:

• Model Explainability: SHAP values provide per-feature attribution
• Data Lineage: Track feature provenance from raw OHLCV to 256-dim vector
• Audit Logs: Record all feature transformations and validation results
• Change Management: Version control for feature engineering code

---

9. Appendix: Feature Index Reference

Quick Lookup Table

Category	Start	End	Count	Key Features
OHLCV	0	4	5	Raw price/volume (normalized)
Technical Indicators	5	14	10	RSI, MACD, Bollinger, ATR, EMA
Price Patterns	15	74	60	Returns, MA ratios, trend quality
Volume Patterns	75	114	40	OBV, MFI, VWAP, volume momentum
Microstructure	115	164	50	Roll, Amihud, Corwin-Schultz
Time Features	165	174	10	Hour, day, market session
Statistical	175	255	81	Rolling stats, correlations, volatility

High-Priority Features (for Top-K Selection)

Recommended Top-128 Candidates (based on domain knowledge):

1. Technical Indicators (indices 5-14): All 10 features (proven alpha signals)
2. Price Patterns (indices 15-74):
   • Returns (15-17): Intraday, overnight, simple returns
   • MA ratios (18-22): Trend following signals
   • Momentum (23-26): Trend strength
3. Volume Patterns (indices 75-114):
   • OBV (75): Volume flow indicator
   • MFI (76): Money flow strength
   • VWAP (77): Institutional trading benchmark
4. Microstructure (indices 115-164):
   • Roll Measure (115): Effective spread
   • Amihud (116): Liquidity proxy
   • Corwin-Schultz (117): High-low spread
5. Statistical (indices 175-255):
   • Realized volatility (175-177): Risk metrics
   • Autocorrelations (178-180): Momentum persistence

Total: 128 features (50% reduction from 256)

---

10. Next Steps

Immediate Actions (Week 1)

1. ✅ Design document completed
2. ⏳ Review with team (architecture validation)
3. ⏳ Create feature branch: wave-c/ml-integration
4. ⏳ Implement DQN/PPO adapters (Phase 1)

Medium-Term (Weeks 2-4)

• Phase 2: Validation pipeline
• Phase 3: Feature selection
• Phase 4: E2E integration

Long-Term (Month 2+)

• SHAP-based feature importance analysis
• PCA/Autoencoder compression
• Production deployment with monitoring

---

Document Status: ✅ COMPLETE Review Date: 2025-10-17 Next Review: After Phase 1 implementation (Week 1)