micro_routing

Dynamic routing and context management for micro-neural networks

The micro_routing crate provides intelligent routing mechanisms for directing inputs to the most appropriate micro-networks in the Semantic Cartan Matrix system. It implements context-aware decision making and adaptive routing strategies.

🚀 Features

• 4 Routing Strategies: Rule-based, learned, context-aware, and hybrid routing
• Context Management: Stateful routing with historical success tracking
• Gating Networks: Neural network-based routing decisions
• Execution Planning: Parallel and sequential micro-net coordination
• Performance Optimization: Sub-millisecond routing decisions
• no_std Compatible: Works in embedded and WebAssembly environments

📦 Installation

Add this to your Cargo.toml:

[dependencies]
micro_routing = "0.1.0"
micro_core = "0.1.0"

# Optional features
micro_routing = { version = "0.1.0", features = ["std", "neural-gating"] }

🏗️ Architecture

Router System

The core Router provides multiple routing strategies:

use micro_routing::{Router, RoutingStrategy, ExecutionPlan};
use micro_core::{RootVector, MicroNet};

// Create a router with hybrid strategy
let mut router = Router::new(RoutingStrategy::Hybrid);

// Add micro-nets to the routing table
router.register_agent("reasoning", Box::new(reasoning_agent));
router.register_agent("feature_extract", Box::new(feature_agent));
router.register_agent("classifier", Box::new(classifier_agent));

// Route input to appropriate agents
let input = RootVector::from_slice(&[0.1, 0.2, /* ... */]);
let plan = router.route(&input, &context);

match plan {
    ExecutionPlan::Single(agent_id) => {
        // Route to single best agent
        println!("Routing to: {}", agent_id);
    }
    ExecutionPlan::Parallel(agent_ids) => {
        // Execute multiple agents in parallel
        println!("Parallel execution: {:?}", agent_ids);
    }
    ExecutionPlan::Sequential(sequence) => {
        // Pipeline through multiple agents
        println!("Sequential: {:?}", sequence);
    }
}

🧠 Routing Strategies

1. Rule-Based Routing

Uses predefined rules and pattern matching:

use micro_routing::{RuleBasedRouter, Rule};

let mut router = RuleBasedRouter::new();

// Add routing rules
router.add_rule(Rule::new()
    .condition(|input| input[0] > 0.5)  // Check first dimension
    .route_to("mathematical_reasoning"));

router.add_rule(Rule::new()
    .condition(|input| input.norm() < 0.1)  // Low activation
    .route_to("context_manager"));

// Default fallback
router.set_default("general_reasoning");

2. Learned Gating Network

Neural network-based routing decisions:

use micro_routing::{GatingNetwork, GatingConfig};

let config = GatingConfig {
    input_dim: 32,
    hidden_dim: 64,
    num_agents: 8,
    temperature: 2.0,
};

let mut gating_net = GatingNetwork::new(config);

// Train the gating network (optional)
gating_net.train(&training_data, &labels);

// Get routing probabilities
let input = RootVector::from_slice(&[/* ... */]);
let probabilities = gating_net.forward(&input);

// Route to highest probability agent
let best_agent = probabilities.argmax();

3. Context-Aware Routing

Incorporates historical context and success tracking:

use micro_routing::{ContextAwareRouter, Context};

let mut router = ContextAwareRouter::new();
let mut context = Context::new();

// Update context with recent interactions
context.add_interaction("reasoning", 0.85);  // Success score
context.add_interaction("feature_extract", 0.92);

// Route considering context
let plan = router.route_with_context(&input, &context);

// Context influences future routing decisions
// Successful agents get higher probability

4. Hybrid Routing

Combines multiple strategies with adaptive weighting:

use micro_routing::{HybridRouter, StrategyWeight};

let mut router = HybridRouter::new();

// Configure strategy weights
router.set_weights(vec![
    StrategyWeight::RuleBased(0.3),
    StrategyWeight::Learned(0.4),
    StrategyWeight::ContextAware(0.3),
]);

// Adaptive weighting based on performance
router.enable_adaptive_weighting(true);

// Router automatically adjusts strategy weights
// based on routing success rates

⚡ Execution Planning

Execution Modes

The router generates different execution plans:

use micro_routing::ExecutionPlan;

// Single agent execution
let plan = ExecutionPlan::Single("best_agent".to_string());

// Parallel execution for consensus
let plan = ExecutionPlan::Parallel(vec![
    "agent_1".to_string(),
    "agent_2".to_string(),
    "agent_3".to_string(),
]);

// Sequential pipeline
let plan = ExecutionPlan::Sequential(vec![
    "preprocessor".to_string(),
    "feature_extractor".to_string(),
    "classifier".to_string(),
    "postprocessor".to_string(),
]);

// Execute the plan
let results = executor.execute_plan(&plan, &input);

Load Balancing

Automatic load balancing across agents:

use micro_routing::{LoadBalancer, LoadMetrics};

let mut balancer = LoadBalancer::new();

// Monitor agent loads
let metrics = LoadMetrics {
    agent_id: "reasoning".to_string(),
    cpu_usage: 0.85,
    queue_length: 12,
    response_time: 15.2, // milliseconds
};

balancer.update_metrics("reasoning", metrics);

// Route considering load
let plan = balancer.route_with_load_balancing(&input, &available_agents);

📊 Context Management

Context State

Track interaction history and agent performance:

use micro_routing::{Context, InteractionRecord};

let mut context = Context::new();

// Record successful interaction
let record = InteractionRecord {
    agent_id: "reasoning".to_string(),
    input_hash: input.hash(),
    success_score: 0.92,
    latency_ms: 8.5,
    timestamp: std::time::Instant::now(),
};

context.add_record(record);

// Get agent success rate
let success_rate = context.get_success_rate("reasoning");

// Get contextual similarity
let similarity = context.similarity_to_previous(&input);

Memory Management

Efficient context storage with LRU eviction:

use micro_routing::{ContextMemory, MemoryConfig};

let config = MemoryConfig {
    max_entries: 1000,
    eviction_policy: EvictionPolicy::LRU,
    compression: true,
};

let mut memory = ContextMemory::new(config);

// Automatically manages memory usage
// Evicts old entries when capacity reached

🎯 Performance

Benchmarks

Memory Usage

• Context Entry: 64 bytes per interaction record
• Gating Network: ~50KB for 8 agents, 64 hidden units
• Rule Table: ~1KB per 100 rules

🔧 Configuration

Feature Flags

[features]
default = ["rule-based"]
std = ["dep:std"]
neural-gating = ["dep:candle-core"]
context-compression = ["dep:lz4"]
metrics = ["dep:prometheus"]

Routing Configuration

use micro_routing::{RouterConfig, RoutingStrategy};

let config = RouterConfig {
    strategy: RoutingStrategy::Hybrid,
    max_context_size: 1000,
    enable_load_balancing: true,
    gating_network_config: Some(GatingConfig {
        hidden_dim: 64,
        temperature: 2.0,
        dropout: 0.1,
    }),
    adaptive_weights: true,
};

let router = Router::from_config(config);

🧪 Testing

Run the comprehensive test suite:

# Unit tests
cargo test

# Integration tests with micro_core
cargo test --features integration-tests

# Benchmarks
cargo bench

# Test all routing strategies
cargo test --features neural-gating

📚 Examples

See the examples/ directory for:

• Basic Routing: Simple agent selection
• Context Management: Stateful routing examples
• Neural Gating: Training and using gating networks
• Load Balancing: Distributed routing strategies
• Hybrid Systems: Combining multiple approaches

🤝 Integration

With micro_core

use micro_core::{MicroNet, RootVector};
use micro_routing::{Router, RoutingStrategy};

// Seamless integration with micro_core agents
let router = Router::new(RoutingStrategy::ContextAware);
// Router automatically works with any MicroNet implementation

With micro_swarm

use micro_swarm::SwarmOrchestrator;
use micro_routing::Router;

// Router is used by orchestrator for agent selection
let orchestrator = SwarmOrchestrator::with_router(router);

🛠️ Development

Building

# Standard build
cargo build

# With all features
cargo build --all-features

# For WebAssembly
wasm-pack build --target web

Testing Neural Gating

# Requires neural-gating feature
cargo test --features neural-gating test_gating_network

📄 License

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.

🔗 Related Crates

• micro_core: Core types and neural network traits
• micro_cartan_attn: Attention mechanisms for agent coordination
• micro_metrics: Performance monitoring and analytics
• micro_swarm: High-level orchestration and coordination

Part of the rUv-FANN Semantic Cartan Matrix system 🧠🔀