Getting Started - ruvnet/ruv-FANN GitHub Wiki
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.
ruv-FANN is a revolutionary neural intelligence framework that consists of three integrated components:
- ruv-FANN Core - Fast neural network library with zero unsafe code
- Neuro-Divergent - 27+ forecasting models with Python compatibility
- ruv-swarm - Distributed swarm intelligence achieving 84.8% SWE-Bench solve rate
- 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
# 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
# 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
# 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
Let's create your first neural network that actually works:
// 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(())
}
# 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
Now let's create ephemeral intelligence that solves problems:
# Create a new swarm project
npx ruv-swarm init my-swarm --template basic
# Navigate to the project
cd my-swarm
// 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);
node swarm_example.js
Let's create a time series forecasting model:
// 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)
}
ruv-FANN works seamlessly with Claude Code through MCP (Model Context Protocol):
# Add ruv-swarm MCP server to Claude Code
claude mcp add ruv-swarm npx ruv-swarm@latest mcp start
# 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
- 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
- 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)
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 |
Focus on the working components first. Many advanced features are research prototypes.
This system is designed to work efficiently on CPU-only systems.
Check the examples and tests to see what actually works before using APIs.
Begin with basic examples and gradually add complexity.
Test your setup with simple examples before building complex applications.
Choose your learning path:
- Code Examples - Jump straight into working code
- Integration Guides - Connect with your stack
- Neural Networks - Understanding neural architectures
- Swarm Intelligence - Distributed problem solving
- System Architecture - How it all fits together
- API Reference - Complete API documentation
- Production Deployment - Deploy at scale
- Performance Benchmarks - Optimization guide
-
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
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