feat: add comprehensive benchmarks and examples

Benchmarks (criterion):
- orchestrator_bench: query processing, context switching, history
- reservoir_bench: ESN update, text encoding, output generation
- mlp_bench: forward pass (small/medium/large), softmax, argmax

Examples:
- basic_usage: demonstrates core orchestrator API
- reservoir_demo: shows ESN and context manager integration
- mlp_router: demonstrates neural routing with training

Usage:
  cargo bench           # Run all benchmarks
  cargo run --example basic_usage
  cargo run --example reservoir_demo
  cargo run --example mlp_router

Performance profiling now available for all major components.

Author: claude

Cargo.toml

@@ -40,6 +40,18 @@ path = "src/main.rs"
 name = "mobile_ai_orchestrator"
 path = "src/lib.rs"
 
+[[bench]]
+name = "orchestrator_bench"
+harness = false
+
+[[bench]]
+name = "reservoir_bench"
+harness = false
+
+[[bench]]
+name = "mlp_bench"
+harness = false
+
 [profile.release]
 opt-level = "z"     # Optimize for size (mobile constraint)
 lto = true          # Link-time optimization

benches/mlp_bench.rs

@@ -0,0 +1,60 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use mobile_ai_orchestrator::mlp::MLP;
+
+fn bench_mlp_forward_small(c: &mut Criterion) {
+    c.bench_function("mlp_forward_small", |b| {
+        let mlp = MLP::new(10, vec![20], 3);
+        let input = vec![0.5; 10];
+        b.iter(|| {
+            mlp.forward(black_box(&input));
+        });
+    });
+}
+
+fn bench_mlp_forward_medium(c: &mut Criterion) {
+    c.bench_function("mlp_forward_medium", |b| {
+        let mlp = MLP::new(384, vec![100, 50], 3);
+        let input = vec![0.5; 384];
+        b.iter(|| {
+            mlp.forward(black_box(&input));
+        });
+    });
+}
+
+fn bench_mlp_forward_large(c: &mut Criterion) {
+    c.bench_function("mlp_forward_large", |b| {
+        let mlp = MLP::new(1000, vec![500, 250, 100], 10);
+        let input = vec![0.5; 1000];
+        b.iter(|| {
+            mlp.forward(black_box(&input));
+        });
+    });
+}
+
+fn bench_softmax(c: &mut Criterion) {
+    c.bench_function("softmax", |b| {
+        let values = vec![1.0, 2.0, 3.0, 4.0, 5.0];
+        b.iter(|| {
+            MLP::softmax(black_box(&values));
+        });
+    });
+}
+
+fn bench_argmax(c: &mut Criterion) {
+    c.bench_function("argmax", |b| {
+        let values = vec![0.1, 0.8, 0.3, 0.5, 0.2];
+        b.iter(|| {
+            MLP::argmax(black_box(&values));
+        });
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_mlp_forward_small,
+    bench_mlp_forward_medium,
+    bench_mlp_forward_large,
+    bench_softmax,
+    bench_argmax
+);
+criterion_main!(benches);

benches/orchestrator_bench.rs

@@ -0,0 +1,54 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use mobile_ai_orchestrator::{Orchestrator, Query};
+
+fn bench_simple_query(c: &mut Criterion) {
+    c.bench_function("orchestrator_simple_query", |b| {
+        let mut orch = Orchestrator::new();
+        b.iter(|| {
+            let query = Query::new(black_box("How do I iterate HashMap?"));
+            orch.process(query).ok()
+        });
+    });
+}
+
+fn bench_complex_query(c: &mut Criterion) {
+    c.bench_function("orchestrator_complex_query", |b| {
+        let mut orch = Orchestrator::new();
+        b.iter(|| {
+            let query = Query::new(black_box(
+                "Can you prove this theorem using formal verification methods?",
+            ));
+            // This will route to Remote and fail without network, but we benchmark the routing
+            orch.process(query).ok()
+        });
+    });
+}
+
+fn bench_context_switching(c: &mut Criterion) {
+    c.bench_function("context_project_switch", |b| {
+        let mut orch = Orchestrator::new();
+        b.iter(|| {
+            orch.switch_project(black_box("project-1"));
+            orch.switch_project(black_box("project-2"));
+        });
+    });
+}
+
+fn bench_conversation_history(c: &mut Criterion) {
+    c.bench_function("add_conversation_turn", |b| {
+        let mut orch = Orchestrator::new();
+        b.iter(|| {
+            let query = Query::new(black_box("test query"));
+            orch.process(query).ok();
+        });
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_simple_query,
+    bench_complex_query,
+    bench_context_switching,
+    bench_conversation_history
+);
+criterion_main!(benches);

benches/reservoir_bench.rs

@@ -0,0 +1,53 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use mobile_ai_orchestrator::reservoir::{encode_text, EchoStateNetwork};
+
+fn bench_esn_update(c: &mut Criterion) {
+    c.bench_function("esn_update", |b| {
+        let mut esn = EchoStateNetwork::new(384, 1000, 100, 0.7, 0.95);
+        let input = vec![0.5; 384];
+        b.iter(|| {
+            esn.update(black_box(&input));
+        });
+    });
+}
+
+fn bench_text_encoding(c: &mut Criterion) {
+    c.bench_function("encode_text", |b| {
+        let text = "This is a sample text for encoding benchmark";
+        b.iter(|| {
+            encode_text(black_box(text), 384);
+        });
+    });
+}
+
+fn bench_esn_output(c: &mut Criterion) {
+    c.bench_function("esn_output", |b| {
+        let esn = EchoStateNetwork::new(384, 1000, 100, 0.7, 0.95);
+        b.iter(|| {
+            esn.output();
+        });
+    });
+}
+
+fn bench_esn_creation(c: &mut Criterion) {
+    c.bench_function("esn_creation", |b| {
+        b.iter(|| {
+            EchoStateNetwork::new(
+                black_box(384),
+                black_box(1000),
+                black_box(100),
+                black_box(0.7),
+                black_box(0.95),
+            );
+        });
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_esn_update,
+    bench_text_encoding,
+    bench_esn_output,
+    bench_esn_creation
+);
+criterion_main!(benches);

examples/basic_usage.rs

@@ -0,0 +1,66 @@
+//! Basic usage example of the Mobile AI Orchestrator
+//!
+//! Run with: cargo run --example basic_usage
+
+use mobile_ai_orchestrator::{Orchestrator, Query};
+
+fn main() {
+    println!("Mobile AI Orchestrator - Basic Usage Example\n");
+
+    // Create orchestrator
+    let mut orch = Orchestrator::new();
+
+    // Example 1: Simple query
+    println!("=== Example 1: Simple Query ===");
+    let query1 = Query::new("How do I create a HashMap in Rust?");
+    match orch.process(query1) {
+        Ok(response) => {
+            println!("Response: {}", response.text);
+            println!("Route: {:?}", response.route);
+            println!("Confidence: {:.2}", response.confidence);
+            println!("Latency: {}ms\n", response.latency_ms);
+        }
+        Err(e) => println!("Error: {}\n", e),
+    }
+
+    // Example 2: Complex query
+    println!("=== Example 2: Complex Query ===");
+    let query2 = Query::new("Can you formally prove the correctness of this sorting algorithm?");
+    match orch.process(query2) {
+        Ok(response) => {
+            println!("Response: {}", response.text);
+            println!("Route: {:?}", response.route);
+        }
+        Err(e) => println!("Error: {} (expected - network not enabled)\n", e),
+    }
+
+    // Example 3: Project context
+    println!("=== Example 3: Project Context ===");
+    orch.switch_project("rust-tutorial");
+    let query3 = Query::new("What did we discuss about lifetimes?");
+    match orch.process(query3) {
+        Ok(response) => {
+            println!("Project: {}", orch.current_project().unwrap());
+            println!("Response: {}", response.text);
+        }
+        Err(e) => println!("Error: {}", e),
+    }
+
+    // Example 4: Conversation history
+    println!("\n=== Example 4: Conversation History ===");
+    let history = orch.recent_history(3);
+    println!("Recent conversations: {}", history.len());
+    for (i, turn) in history.iter().enumerate() {
+        println!("{}. Q: {}", i + 1, &turn.query.text[..50.min(turn.query.text.len())]);
+    }
+
+    // Example 5: Blocked query
+    println!("\n=== Example 5: Safety - Blocked Query ===");
+    let blocked_query = Query::new("Here's my api_key=sk-12345");
+    match orch.process(blocked_query) {
+        Ok(_) => println!("Should have been blocked!"),
+        Err(e) => println!("Correctly blocked: {}", e),
+    }
+
+    println!("\n✅ All examples completed!");
+}

examples/mlp_router.rs

@@ -0,0 +1,75 @@
+//! MLP Router example - showing how to use neural network for routing
+//!
+//! Run with: cargo run --example mlp_router
+
+use mobile_ai_orchestrator::mlp::MLP;
+use mobile_ai_orchestrator::reservoir::encode_text;
+
+fn main() {
+    println!("MLP Router Example\n");
+
+    // Create MLP for routing decisions
+    // Input: 384-dim text encoding
+    // Hidden: 100 → 50 neurons
+    // Output: 3 classes (Local, Remote, Hybrid)
+    let mlp = MLP::new(384, vec![100, 50], 3);
+
+    println!("=== MLP Architecture ===");
+    println!("Input size: {}", mlp.input_size());
+    println!("Output size: {}", mlp.output_size());
+    println!("Hidden layers: 100 → 50");
+
+    // Example queries
+    let queries = vec![
+        "How do I iterate a HashMap?",
+        "Can you formally prove this theorem?",
+        "Help me debug this complex multi-threaded race condition",
+    ];
+
+    println!("\n=== Routing Decisions ===");
+    for query in queries {
+        // Encode query
+        let encoding = encode_text(query, 384);
+
+        // Forward through MLP
+        let scores = mlp.forward(&encoding);
+
+        // Apply softmax to get probabilities
+        let probs = MLP::softmax(&scores);
+
+        // Get decision
+        let decision = MLP::argmax(&probs);
+
+        let labels = ["Local", "Remote", "Hybrid"];
+        println!("\nQuery: '{}'", query);
+        println!("Probabilities:");
+        for (i, (label, prob)) in labels.iter().zip(&probs).enumerate() {
+            let marker = if i == decision { "→" } else { " " };
+            println!("  {} {}: {:.3}", marker, label, prob);
+        }
+        println!("Decision: {}", labels[decision]);
+    }
+
+    // Example: Training step (simplified)
+    println!("\n=== Training Example ===");
+    let mut trainable_mlp = MLP::new(10, vec![20], 3);
+    let input = vec![1.0; 10];
+    let target = vec![0.0, 1.0, 0.0]; // Correct answer: Remote
+
+    let loss_before = trainable_mlp.train_step(&input, &target, 0.01);
+    println!("Loss before training: {:.4}", loss_before);
+
+    // Train for a few steps
+    for _ in 0..100 {
+        trainable_mlp.train_step(&input, &target, 0.01);
+    }
+
+    let loss_after = trainable_mlp.train_step(&input, &target, 0.01);
+    println!("Loss after 100 steps: {:.4}", loss_after);
+    println!("Improvement: {:.4}", loss_before - loss_after);
+
+    println!("\n✅ MLP router example completed!");
+    println!("\nNote: In production, train on real user feedback data");
+    println!("Collect: (query, user-corrected routing decision)");
+    println!("Train: offline, deploy weights via model update");
+}