foxhunt/adaptive-strategy/README.md

# Adaptive Strategy Library

A comprehensive Rust library for adaptive trading strategies that combines ensemble machine learning models, market microstructure analysis, and dynamic risk management.

## Features

### 🧠 Ensemble Learning
- **Multi-Model Coordination**: Combines LSTM, GRU, Transformer, and traditional ML models
- **Dynamic Weight Optimization**: Automatically adjusts model weights based on performance
- **Performance Tracking**: Real-time monitoring of model accuracy and Sharpe ratios

### 📊 Market Microstructure Analysis
- **Order Book Analysis**: Real-time bid-ask spread and imbalance calculations
- **Trade Flow Classification**: Buyer/seller pressure detection using Lee-Ready algorithm
- **Price Impact Modeling**: Linear and square-root impact estimation
- **VWAP Calculations**: Volume-weighted average price with configurable windows

### ⚖️ Risk Management
- **Position Sizing**: Kelly Criterion, Risk Parity, and Volatility Targeting
- **Portfolio Monitoring**: Real-time VaR, drawdown, and leverage tracking
- **Dynamic Risk Adjustment**: Regime-based risk scaling
- **Limit Enforcement**: Automated position and portfolio limit checks

### 🚀 Trade Execution
- **Smart Order Routing**: Multi-venue execution with latency optimization
- **Execution Algorithms**: TWAP, VWAP, Implementation Shortfall
- **Performance Tracking**: Slippage, market impact, and fill rate monitoring
- **Dark Pool Integration**: Configurable dark pool preferences

### 🔄 Regime Detection
- **Multiple Methods**: HMM, GMM, Threshold-based, and ML classifiers
- **Regime Tracking**: Automatic transition detection and duration monitoring
- **Feature Engineering**: Volatility, momentum, and microstructure features
- **Performance Analysis**: Regime-specific return and risk metrics

## Architecture

```
adaptive-strategy/
├── src/
│   ├── lib.rs              # Main library interface
│   ├── config.rs           # Configuration management
│   ├── ensemble/           # Model coordination
│   ├── models/             # ML model interfaces
│   ├── microstructure/     # Market analysis
│   ├── risk/               # Risk management
│   ├── execution/          # Trade execution
│   └── regime/             # Regime detection
└── Cargo.toml
```

## Quick Start

```rust
use adaptive_strategy::{AdaptiveStrategy, StrategyConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize strategy with default configuration
    let config = StrategyConfig::default();
    let mut strategy = AdaptiveStrategy::new(config).await?;
    
    // Start the adaptive strategy
    strategy.start().await?;
    
    Ok(())
}
```

## Configuration

The library uses a comprehensive configuration system:

```rust
use adaptive_strategy::config::*;

let config = StrategyConfig {
    general: GeneralConfig {
        name: "my_strategy".to_string(),
        symbols: vec!["BTC-USD".to_string(), "ETH-USD".to_string()],
        execution_interval: Duration::from_millis(100),
        live_trading_enabled: false,
        ..Default::default()
    },
    ensemble: EnsembleConfig {
        models: vec![
            ModelConfig {
                model_type: "lstm".to_string(),
                name: "primary_lstm".to_string(),
                initial_weight: 0.4,
                enabled: true,
                ..Default::default()
            },
            // Add more models...
        ],
        min_confidence_threshold: 0.6,
        ..Default::default()
    },
    risk: RiskConfig {
        max_portfolio_var: 0.02,
        position_sizing_method: PositionSizingMethod::Kelly,
        kelly_fraction: 0.25,
        max_leverage: 2.0,
        ..Default::default()
    },
    // Configure other modules...
    ..Default::default()
};
```

## Model Integration

### Adding Custom Models

Implement the `ModelTrait` for custom models:

```rust
use adaptive_strategy::models::{ModelTrait, ModelPrediction, TrainingData};
use async_trait::async_trait;

#[derive(Debug)]
pub struct MyCustomModel {
    name: String,
    // Model-specific fields...
}

#[async_trait]
impl ModelTrait for MyCustomModel {
    fn name(&self) -> &str {
        &self.name
    }
    
    fn model_type(&self) -> &str {
        "custom"
    }
    
    async fn predict(&self, features: &[f64]) -> Result<ModelPrediction> {
        // Custom prediction logic
        Ok(ModelPrediction {
            value: 0.0,
            confidence: 0.8,
            features_used: vec!["feature1".to_string()],
            metadata: None,
        })
    }
    
    // Implement other required methods...
}
```

### Custom Execution Algorithms

Implement the `ExecutionAlgorithm` trait:

```rust
use adaptive_strategy::execution::{ExecutionAlgorithm, Order, ExecutionRequest};

#[derive(Debug)]
pub struct MyExecutionAlgo {
    name: String,
    // Algorithm-specific fields...
}

impl ExecutionAlgorithm for MyExecutionAlgo {
    fn name(&self) -> &str {
        &self.name
    }
    
    fn execute(
        &mut self,
        request: &ExecutionRequest,
        order_manager: &mut OrderManager,
        microstructure: &MicrostructureAnalyzer,
    ) -> Result<Vec<Order>> {
        // Custom execution logic
        Ok(vec![])
    }
    
    // Implement other required methods...
}
```

## Performance Features

- **Sub-millisecond Latency**: Optimized for high-frequency trading
- **Memory Efficient**: Bounded memory usage with configurable limits
- **Scalable**: Supports multiple symbols and models simultaneously
- **Production Ready**: Comprehensive error handling and logging

## Testing

```bash
# Run all tests
cargo test

# Run with specific features
cargo test --features gpu

# Run benchmarks
cargo bench
```

## Dependencies

- **Core**: tokio, anyhow, tracing, serde
- **ML/Stats**: ndarray, candle-core, linfa, statrs
- **Time Series**: chrono, ta
- **Optional GPU**: candle-cuda (with "gpu" feature)

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Roadmap

- [ ] Additional ML models (XGBoost, Random Forest)
- [ ] Real broker integrations (Interactive Brokers, Alpaca)
- [ ] Advanced regime detection (Change Point Detection)
- [ ] Portfolio optimization (Mean-Variance, Black-Litterman)
- [ ] Risk factor models (Fama-French, PCA)
- [ ] Options strategies support
- [ ] Backtesting framework integration

## Examples

See the `examples/` directory for complete working examples including:

- Basic strategy setup
- Custom model implementation
- Multi-asset trading
- Risk management configuration
- Execution algorithm customization