foxhunt/SHARED_ML_STRATEGY_QUICK_REFERENCE.md

Shared ML Strategy - Quick Reference

ONE SINGLE SYSTEM for both trading and backtesting services.

---

Quick Start

use common::ml_strategy::SharedMLStrategy;
use std::sync::Arc;

// Create strategy (once per service)
let strategy = Arc::new(SharedMLStrategy::new(
    20,   // lookback_periods
    0.7   // min_confidence_threshold
));

// Get predictions
let predictions = strategy
    .get_ensemble_prediction(price, volume, timestamp)
    .await?;

// Calculate ensemble vote
if let Some((vote, confidence)) = strategy.calculate_ensemble_vote(&predictions) {
    // vote: -1.0 (sell) to 1.0 (buy)
    // confidence: 0.0 to 1.0
}

// Validate after outcome known
strategy.validate_predictions(&predictions, actual_return).await;

---

API Reference

Creation

SharedMLStrategy::new(lookback_periods: usize, min_confidence_threshold: f64) -> Self

Core Methods

// Get ensemble predictions
async fn get_ensemble_prediction(
    &self,
    price: f64,
    volume: f64,
    timestamp: DateTime<Utc>
) -> Result<Vec<MLPrediction>>

// Calculate weighted vote
fn calculate_ensemble_vote(
    &self,
    predictions: &[MLPrediction]
) -> Option<(f64, f64)>  // (vote, confidence)

// Validate predictions
async fn validate_predictions(
    &self,
    predictions: &[MLPrediction],
    actual_return: f64
)

// Get performance metrics
async fn get_performance_summary(
    &self
) -> HashMap<String, MLModelPerformance>

// Add custom model
async fn add_model(
    &self,
    model_id: String,
    model: Box<dyn MLModelAdapter>
)

---

Key Types

pub struct MLPrediction {
    pub model_id: String,
    pub prediction_value: f64,    // -1.0 to 1.0
    pub confidence: f64,           // 0.0 to 1.0
    pub features: Vec<f64>,
    pub timestamp: DateTime<Utc>,
    pub inference_latency_us: u64,
}

pub struct MLModelPerformance {
    pub model_id: String,
    pub total_predictions: u64,
    pub correct_predictions: u64,
    pub accuracy_percentage: f64,
    pub avg_latency_us: f64,
    pub avg_confidence: f64,
}

---

Feature Extraction (Automatic)

7 features extracted automatically from price/volume:

1. Price Return - Short-term momentum
2. MA Ratio - Deviation from 5-period MA
3. Volatility - Rolling std dev
4. Volume Ratio - Volume change rate
5. Volume MA Ratio - Volume vs MA
6. Hour - Time of day (normalized)
7. Day of Week - Day (normalized)

All normalized to [-1, 1] range.

---

Usage Examples

Trading Service

// Initialize
let ml_strategy = Arc::new(SharedMLStrategy::new(20, 0.7));

// Trading loop
loop {
    let predictions = ml_strategy
        .get_ensemble_prediction(price, volume, Utc::now())
        .await?;

    if let Some((vote, confidence)) = ml_strategy.calculate_ensemble_vote(&predictions) {
        if vote > 0.5 && confidence > 0.7 {
            // BUY signal
        } else if vote < -0.5 && confidence > 0.7 {
            // SELL signal
        }
    }

    // After trade execution
    ml_strategy.validate_predictions(&predictions, actual_return).await;
}

Backtesting Service

// Initialize
let ml_strategy = Arc::new(SharedMLStrategy::new(20, 0.7));

// Backtest loop
for bar in historical_bars {
    let predictions = ml_strategy
        .get_ensemble_prediction(bar.close, bar.volume, bar.timestamp)
        .await?;

    if let Some((vote, confidence)) = ml_strategy.calculate_ensemble_vote(&predictions) {
        // Simulate trading decision
    }

    // After bar completes
    ml_strategy.validate_predictions(&predictions, actual_return).await;
}

// Get performance summary
let performance = ml_strategy.get_performance_summary().await;

---

Custom Models

use common::ml_strategy::{MLModelAdapter, MLPrediction};

struct MyModel {
    model_id: String,
}

impl MLModelAdapter for MyModel {
    fn predict(&self, features: &[f64]) -> Result<MLPrediction> {
        // Your inference logic
        Ok(MLPrediction {
            model_id: self.model_id.clone(),
            prediction_value: /* ... */,
            confidence: /* ... */,
            features: features.to_vec(),
            timestamp: Utc::now(),
            inference_latency_us: 50,
        })
    }

    fn model_id(&self) -> &str {
        &self.model_id
    }

    fn validate_prediction(&mut self, prediction: &MLPrediction, actual_outcome: bool) {
        // Update metrics
    }
}

// Add to strategy
strategy.add_model("my_model".to_string(), Box::new(MyModel { /* ... */ })).await;

---

Configuration

// Conservative (high confidence threshold)
let strategy = SharedMLStrategy::new(20, 0.85);

// Moderate (balanced)
let strategy = SharedMLStrategy::new(20, 0.70);

// Aggressive (low confidence threshold)
let strategy = SharedMLStrategy::new(20, 0.50);

// Custom lookback
let strategy = SharedMLStrategy::new(30, 0.70);  // Longer history

---

Performance Metrics

let performance = strategy.get_performance_summary().await;

for (model_id, perf) in performance.iter() {
    println!("Model: {}", model_id);
    println!("  Total Predictions: {}", perf.total_predictions);
    println!("  Accuracy: {:.2}%", perf.accuracy_percentage);
    println!("  Avg Latency: {:.0}μs", perf.avg_latency_us);
    println!("  Avg Confidence: {:.3}", perf.avg_confidence);
}

---

Thread Safety

• ✅ Thread-safe: Uses Arc<RwLock<>>
• ✅ Concurrent access from multiple services
• ✅ No data races or corruption
• ✅ Tested with 10+ concurrent tasks

---

Test Coverage

• Unit Tests: 4/4 passing
• Integration Tests: 8/8 passing
• Total: 12/12 tests passing ✅

---

Common Patterns

Signal Generation

let (vote, confidence) = strategy.calculate_ensemble_vote(&predictions)?;

match (vote, confidence) {
    (v, c) if v > 0.5 && c > 0.7 => Signal::Buy,
    (v, c) if v < -0.5 && c > 0.7 => Signal::Sell,
    _ => Signal::Hold,
}

Confidence-Weighted Position Sizing

let (vote, confidence) = strategy.calculate_ensemble_vote(&predictions)?;
let position_size = base_size * confidence * vote.abs();

Performance Monitoring

// Check accuracy
let performance = strategy.get_performance_summary().await;
for (model_id, perf) in performance.iter() {
    if perf.accuracy_percentage < 50.0 {
        warn!("Model {} underperforming: {:.2}%", model_id, perf.accuracy_percentage);
    }
}

---

Key Benefits

1. NO Duplication - ONE implementation for both services
2. Consistent - Same features, same logic
3. Thread-Safe - Concurrent access safe
4. Tested - 12 tests covering all scenarios
5. Extensible - Easy to add custom models

---

Files

• Implementation: common/src/ml_strategy.rs
• Tests: common/tests/shared_ml_strategy_integration_test.rs
• Docs: AGENT_11.5_SHARED_ML_STRATEGY.md

---

Support

See full documentation: AGENT_11.5_SHARED_ML_STRATEGY.md