Getting Started - ruvnet/ruv-FANN GitHub Wiki

Getting Started with ruv-FANN

Welcome to ruv-FANN, the comprehensive neural intelligence framework that makes AI ephemeral, accessible, and precise. This guide will get you up and running in just a few minutes.

What is ruv-FANN?

ruv-FANN is a revolutionary neural intelligence framework that consists of three integrated components:

🧠 Core Components

  1. ruv-FANN Core - Fast neural network library with zero unsafe code
  2. Neuro-Divergent - 27+ forecasting models with Python compatibility
  3. ruv-swarm - Distributed swarm intelligence achieving 84.8% SWE-Bench solve rate

🎯 Key Philosophy

  • Ephemeral: Spin up intelligence when needed, dissolve when done
  • Accessible: CPU-native, GPU-optional - built for the GPU-poor
  • Composable: Mix and match neural architectures like LEGO blocks
  • Precise: Purpose-built brains for specific tasks

Quick Installation

Method 1: NPX (Recommended - No Installation)

# Get started immediately with ruv-swarm
npx ruv-swarm@latest init --claude

# This creates a ready-to-use environment with:
# - MCP server configuration
# - Claude Code integration
# - Example projects

Method 2: Global Installation

# NPM global install
npm install -g ruv-swarm

# Cargo install (for Rust developers)
cargo install ruv-swarm-cli

# Initialize your project
ruv-swarm init --template neural

Method 3: From Source

# Clone the repository
git clone https://github.com/ruvnet/ruv-FANN.git
cd ruv-FANN

# Quick build test
cargo build --release

# Run examples
cargo run --example basic_usage

Your First Neural Network (2 minutes)

Let's create your first neural network that actually works:

Step 1: Create the Example

// first_network.rs
use ruv_fann::{ActivationFunction, NetworkBuilder};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🧠 My First Neural Network");
    
    // Create a 2-3-1 network (XOR problem)
    let mut network = NetworkBuilder::<f32>::new()
        .input_layer(2)
        .hidden_layer_with_activation(3, ActivationFunction::Sigmoid, 1.0)
        .output_layer_with_activation(1, ActivationFunction::Sigmoid, 1.0)
        .build();
    
    // XOR test data
    let test_cases = [
        (vec![0.0, 0.0], 0.0), // 0 XOR 0 = 0
        (vec![0.0, 1.0], 1.0), // 0 XOR 1 = 1
        (vec![1.0, 0.0], 1.0), // 1 XOR 0 = 1
        (vec![1.0, 1.0], 0.0), // 1 XOR 1 = 0
    ];
    
    println!("\nTesting untrained network:");
    for (input, expected) in &test_cases {
        let output = network.run(input);
        println!("Input: {:?} → Expected: {:.1}, Got: {:.3}", 
                 input, expected, output[0]);
    }
    
    // Network properties
    println!("\nNetwork Info:");
    println!("  Layers: {}", network.num_layers());
    println!("  Total neurons: {}", network.total_neurons());
    println!("  Total connections: {}", network.total_connections());
    
    Ok(())
}

Step 2: Run It

# Add to Cargo.toml
[[bin]]
name = "first_network"
path = "first_network.rs"

# Run the example
cargo run --bin first_network

Expected Output:

🧠 My First Neural Network

Testing untrained network:
Input: [0.0, 0.0] → Expected: 0.0, Got: 0.547
Input: [0.0, 1.0] → Expected: 1.0, Got: 0.623
Input: [1.0, 0.0] → Expected: 1.0, Got: 0.612
Input: [1.0, 1.0] → Expected: 0.0, Got: 0.701

Network Info:
  Layers: 3
  Total neurons: 6
  Total connections: 9

Your First Swarm Intelligence (3 minutes)

Now let's create ephemeral intelligence that solves problems:

Step 1: Initialize Swarm

# Create a new swarm project
npx ruv-swarm init my-swarm --template basic

# Navigate to the project
cd my-swarm

Step 2: Create Swarm Example

// swarm_example.js
const { Swarm, Agent } = require('ruv-swarm');

async function main() {
    console.log('🐝 My First Swarm Intelligence');
    
    // Create swarm with mesh topology
    const swarm = new Swarm({
        topology: 'mesh',
        maxAgents: 5
    });
    
    // Spawn specialized agents
    const agents = await Promise.all([
        swarm.spawn('researcher', { 
            task: 'Analyze problem requirements',
            cognitive_pattern: 'divergent'
        }),
        swarm.spawn('coder', { 
            task: 'Generate solution code',
            cognitive_pattern: 'convergent'
        }),
        swarm.spawn('tester', { 
            task: 'Validate and verify',
            cognitive_pattern: 'critical'
        })
    ]);
    
    console.log(`✅ Spawned ${agents.length} agents`);
    
    // Submit a task for distributed processing
    const task = {
        id: 'solve-fibonacci',
        description: 'Create optimized Fibonacci function',
        priority: 'high'
    };
    
    const result = await swarm.solve(task);
    
    console.log('📊 Solution:', result);
    
    // Agents dissolve automatically after task completion
    console.log('🌟 Swarm dissolved - ephemeral intelligence complete');
}

main().catch(console.error);

Step 3: Run Swarm

node swarm_example.js

Your First Forecasting Model (4 minutes)

Let's create a time series forecasting model:

Step 1: Generate Sample Data

// forecasting_example.rs
use neuro_divergent::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("📈 My First Forecasting Model");
    
    // Generate synthetic time series data
    let data = generate_sales_data(365)?; // 1 year of daily sales
    println!("✅ Generated {} data points", data.len());
    
    // Create LSTM model
    let model = LSTM::builder()
        .horizon(7)        // Predict 7 days ahead
        .input_size(14)    // Use 14 days of history
        .hidden_size(64)   // 64 hidden neurons
        .num_layers(2)     // 2 LSTM layers
        .learning_rate(0.001)
        .build()?;
    
    println!("✅ Created LSTM model");
    
    // Split data (80% train, 20% test)
    let split_point = (data.len() as f64 * 0.8) as usize;
    let (train_data, test_data) = data.split_at(split_point);
    
    // Create forecasting pipeline
    let mut neural_forecast = NeuralForecast::builder()
        .with_model(Box::new(model))
        .with_frequency(Frequency::Daily)
        .build()?;
    
    // Train the model
    println!("🎯 Training model...");
    let start = std::time::Instant::now();
    neural_forecast.fit(train_data.to_vec())?;
    let duration = start.elapsed();
    
    println!("✅ Training completed in {:.2}s", duration.as_secs_f64());
    
    // Generate forecasts
    let forecasts = neural_forecast.predict(7)?; // 7-day forecast
    
    println!("📊 7-Day Forecast:");
    for (day, value) in forecasts.iter().enumerate() {
        println!("  Day {}: {:.2}", day + 1, value);
    }
    
    Ok(())
}

fn generate_sales_data(days: usize) -> Result<Vec<f32>, Box<dyn std::error::Error>> {
    let mut data = Vec::with_capacity(days);
    let mut rng = rand::thread_rng();
    
    for day in 0..days {
        // Realistic sales pattern with trend, seasonality, and noise
        let trend = day as f32 * 0.5;
        let weekly_pattern = 200.0 * (2.0 * std::f32::consts::PI * day as f32 / 7.0).sin();
        let noise = rng.gen_range(-50.0..50.0);
        let base_sales = 1000.0;
        
        let sales = base_sales + trend + weekly_pattern + noise;
        data.push(sales.max(0.0));
    }
    
    Ok(data)
}

Integration with Claude Code

ruv-FANN works seamlessly with Claude Code through MCP (Model Context Protocol):

Step 1: Configure MCP Server

# Add ruv-swarm MCP server to Claude Code
claude mcp add ruv-swarm npx ruv-swarm@latest mcp start

Step 2: Use in Claude Code

# In Claude Code, you can now use swarm coordination:
# 1. Initialize swarm topology
# 2. Spawn specialized agents
# 3. Orchestrate complex tasks
# 4. Get intelligent solutions

# Example: Ask Claude Code to "solve the traveling salesman problem using swarm intelligence"
# It will automatically use ruv-swarm for distributed problem-solving

What's Working vs. What's Documented

✅ Production-Ready Components

  • ruv-FANN Core: Full neural network implementation
  • Basic Swarm Orchestration: Agent spawning and task distribution
  • WASM Integration: Cross-platform deployment
  • MCP Protocol: Claude Code integration
  • Time Series Forecasting: Basic LSTM and MLP models

🚧 Research/Prototype Components

  • Semantic Cartan Matrix: Mathematical research prototype
  • Advanced Swarm Topologies: Complex multi-agent coordination
  • GPU Acceleration: CUDA-WASM integration (experimental)
  • Advanced Forecasting: N-BEATS, Transformers (in development)

Performance Expectations

For typical usage:

Component Performance Memory Notes
Neural Network (Basic) ~1ms inference ~1MB 2-3 hidden layers
Swarm (5 agents) ~100ms coordination ~10MB Mesh topology
Forecasting (LSTM) ~10ms/prediction ~50MB 64 hidden units
WASM Runtime ~2-5x native ~2MB Browser/server

Common Pitfalls

❌ Don't Expect All Features

Focus on the working components first. Many advanced features are research prototypes.

❌ Don't Assume GPU Required

This system is designed to work efficiently on CPU-only systems.

❌ Don't Use Unverified APIs

Check the examples and tests to see what actually works before using APIs.

✅ Do Start Simple

Begin with basic examples and gradually add complexity.

✅ Do Verify Integration

Test your setup with simple examples before building complex applications.

Next Steps

Choose your learning path:

🏃 Quick Start

📚 Deep Learning

🔧 Development

🚀 Production

Getting Help

  • Examples: Check /examples directory for working code
  • Tests: Run cargo test to see expected behavior
  • Documentation: Browse the wiki for detailed guides
  • Issues: Report problems on GitHub
  • Community: Join our Discord for real-time help

Summary

You've learned:

  • ✅ How to install ruv-FANN in multiple ways
  • ✅ Created your first neural network
  • ✅ Spawned your first swarm intelligence
  • ✅ Built your first forecasting model
  • ✅ Integrated with Claude Code
  • ✅ Understanding of what works vs. what's experimental

Time invested: 10 minutes
Knowledge gained: Foundation in ephemeral neural intelligence

Ready to build something amazing? Head to Code Examples for complete working projects!


Built with ❤️ and 🦀 by the rUv team - Making intelligence ephemeral, accessible, and precise

⚠️ **GitHub.com Fallback** ⚠️