foxhunt/SHARED_ML_STRATEGY_QUICK_REFERENCE.md

# Shared ML Strategy - Quick Reference

**ONE SINGLE SYSTEM** for both trading and backtesting services.

---

## Quick Start

```rust
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

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

### Core Methods

```rust
// 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

```rust
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

```rust
// 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

```rust
// 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

```rust
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

```rust
// 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

```rust
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

```rust
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

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

### Performance Monitoring

```rust
// 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`