ruv-swarm-ml

Advanced Machine Learning and Neural Forecasting for RUV Swarm

ruv-swarm-ml is a high-performance machine learning crate designed for intelligent swarm orchestration and neural forecasting. It provides agent-specific time series prediction, ensemble methods, and swarm-level forecasting coordination with support for 27+ state-of-the-art forecasting models.

🚀 Key Features

🧠 27+ Forecasting Models

• Basic Models: MLP, DLinear, NLinear, MLPMultivariate
• Recurrent Models: RNN, LSTM, GRU with memory optimization
• Advanced Models: NBEATS, NBEATSx, NHITS, TiDE with interpretability
• Transformer Models: TFT, Informer, AutoFormer, FedFormer, PatchTST, ITransformer
• Specialized Models: DeepAR, DeepNPTS, TCN, BiTCN, TimesNet, StemGNN, TSMixer, TSMixerx, PatchMixer, SegRNN, DishTS

🎯 Agent-Specific Intelligence

• Adaptive Model Selection: Automatic model assignment based on agent type (researcher, coder, analyst, optimizer, coordinator)
• Forecast Domain Specialization: Task completion, resource utilization, agent performance, swarm dynamics, anomaly detection
• Online Learning: Real-time model adaptation and performance tracking
• Performance Monitoring: Comprehensive metrics tracking with model switching capabilities

🔀 Ensemble Methods

• 7 Ensemble Strategies: Simple Average, Weighted Average, Median, Trimmed Mean, Voting, Stacking, Bayesian Model Averaging
• Prediction Intervals: 50%, 80%, and 95% confidence intervals
• Diversity Metrics: Model correlation analysis and effective model counting
• Automatic Weight Optimization: Performance-based ensemble weight tuning

📊 Time Series Processing

• 7 Transformation Types: Normalize, Standardize, Log, Difference, Box-Cox, Moving Average, Exponential Smoothing
• Seasonality Detection: Automated trend and seasonal pattern identification
• Feature Engineering: Lag features, rolling statistics, datetime features
• Data Quality: Missing value handling and outlier detection

🌐 WebAssembly Support

• WASM Bindings: Deploy models directly in web browsers
• Cross-Platform: Native performance on desktop, server, and web
• Memory Efficient: Optimized for resource-constrained environments

📦 Installation

Add to your Cargo.toml:

[dependencies]
ruv-swarm-ml = "0.1.0"

# For WebAssembly support
ruv-swarm-ml = { version = "0.1.0", features = ["wasm"] }

🔧 Usage Examples

Basic Agent Forecasting

use ruv_swarm_ml::{
    agent_forecasting::{AgentForecastingManager, ForecastRequirements},
    models::ModelFactory,
};

// Create forecasting manager
let mut manager = AgentForecastingManager::new(100.0); // 100MB memory limit

// Configure forecasting requirements
let requirements = ForecastRequirements {
    horizon: 24,                    // 24-hour forecast
    frequency: "H".to_string(),     // Hourly data
    accuracy_target: 0.9,           // 90% accuracy target
    latency_requirement_ms: 200.0,  // 200ms latency limit
    interpretability_needed: true,  // Require interpretable model
    online_learning: true,          // Enable adaptive learning
};

// Assign model to analyst agent
let agent_id = manager.assign_model(
    "analyst_001".to_string(),
    "analyst".to_string(),
    requirements,
)?;

// Update performance metrics
manager.update_performance(
    &agent_id,
    150.0,  // latency_ms
    0.92,   // accuracy
    0.85,   // confidence
)?;

// Get agent's forecasting state
let state = manager.get_agent_state(&agent_id).unwrap();
println!("Agent {} using model: {:?}", agent_id, state.primary_model);

Ensemble Forecasting

use ruv_swarm_ml::{
    ensemble::{EnsembleForecaster, EnsembleConfig, EnsembleStrategy, OptimizationMetric},
    models::ModelType,
};

// Configure ensemble
let config = EnsembleConfig {
    strategy: EnsembleStrategy::WeightedAverage,
    models: vec!["LSTM".to_string(), "TFT".to_string(), "NBEATS".to_string()],
    weights: Some(vec![0.4, 0.4, 0.2]),
    meta_learner: None,
    optimization_metric: OptimizationMetric::MAE,
};

let forecaster = EnsembleForecaster::new(config)?;

// Generate ensemble predictions
let model_predictions = vec![
    vec![100.0, 105.0, 110.0, 108.0, 112.0], // LSTM predictions
    vec![102.0, 107.0, 109.0, 111.0, 115.0], // TFT predictions
    vec![98.0, 103.0, 108.0, 106.0, 110.0],  // NBEATS predictions
];

let result = forecaster.ensemble_predict(&model_predictions)?;

println!("Ensemble forecast: {:?}", result.point_forecast);
println!("95% confidence interval: {:?}", result.prediction_intervals.level_95);
println!("Ensemble diversity: {:.3}", result.ensemble_metrics.diversity_score);

Time Series Processing

use ruv_swarm_ml::{
    time_series::{TimeSeriesData, TimeSeriesProcessor, TransformationType},
};

// Create time series data
let data = TimeSeriesData {
    values: vec![100.0, 102.0, 98.0, 105.0, 103.0, 107.0, 104.0],
    timestamps: (0..7).map(|i| i as f64 * 3600.0).collect(), // Hourly timestamps
    frequency: "H".to_string(),
    unique_id: "sensor_001".to_string(),
};

// Initialize processor
let mut processor = TimeSeriesProcessor::new();

// Apply transformations
let processed_data = processor.fit_transform(
    data,
    vec![
        TransformationType::Normalize,      // Scale to [0,1]
        TransformationType::Difference,     // Remove trend
        TransformationType::Standardize,    // Zero mean, unit variance
    ],
)?;

// Detect seasonality patterns
let seasonality = processor.detect_seasonality(&processed_data);
println!("Has seasonality: {}", seasonality.has_seasonality);
println!("Seasonal periods: {:?}", seasonality.seasonal_periods);

Model Selection and Requirements

use ruv_swarm_ml::models::{ModelFactory, ModelType, ModelCategory};

// Get all available models
let models = ModelFactory::get_available_models();
println!("Available models: {}", models.len());

// Filter models by category
let transformer_models: Vec<_> = models
    .iter()
    .filter(|m| m.category == ModelCategory::Transformer)
    .collect();

println!("Transformer models: {}", transformer_models.len());

// Get model requirements
let lstm_requirements = ModelFactory::get_model_requirements(ModelType::LSTM);
println!("LSTM min samples: {}", lstm_requirements.min_samples);
println!("LSTM required params: {:?}", lstm_requirements.required_params);

// Get model information
if let Some(info) = ModelFactory::get_model_info(ModelType::TFT) {
    println!("TFT supports probabilistic forecasting: {}", info.supports_probabilistic);
    println!("TFT typical memory usage: {:.1} MB", info.typical_memory_mb);
    println!("TFT interpretability score: {:.2}", info.interpretability_score);
}

WebAssembly Integration

// WASM-specific usage
#[cfg(target_arch = "wasm32")]
use ruv_swarm_ml::wasm_bindings::*;

#[cfg(target_arch = "wasm32")]
pub fn wasm_forecast_example() -> Result<(), String> {
    // Create time series data in WASM context
    let data = TimeSeriesData::new(
        vec![1.0, 2.0, 3.0, 4.0, 5.0],
        vec![0.0, 1.0, 2.0, 3.0, 4.0],
        "D".to_string(),
        "wasm_series".to_string(),
    );
    
    let mean = data.mean_wasm();
    let std_dev = data.std_dev_wasm();
    
    web_sys::console::log_1(&format!("Mean: {}, Std Dev: {}", mean, std_dev).into());
    
    Ok(())
}

📈 Performance Benchmarks

Model Performance Comparison

Ensemble Performance

Agent Specialization Benefits

🔗 Integration with RUV Swarm

ruv-swarm-ml integrates seamlessly with the broader RUV ecosystem:

• ruv-swarm-core: Core swarm orchestration primitives
• ruv-swarm-agents: Intelligent agent implementations
• ruv-swarm-mcp: Model Context Protocol integration
• ruv-swarm-wasm: WebAssembly deployment support

🧪 Testing

Run the test suite:

# Run all tests
cargo test

# Run with features
cargo test --features wasm

# Run integration tests
cargo test --test forecasting_tests

# Run benchmarks
cargo bench

📚 Documentation

• API Documentation
• Usage Examples
• Model Comparison Guide
• Performance Tuning

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🔗 Links

• Main Repository: https://github.com/ruvnet/ruv-FANN
• RUV Swarm Framework: https://github.com/ruvnet/ruv-FANN/tree/main/ruv-swarm
• Documentation: https://docs.rs/ruv-swarm-ml
• Issues: https://github.com/ruvnet/ruv-FANN/issues

Created by rUv - Advancing the future of neural network swarm intelligence with cutting-edge machine learning and forecasting capabilities.