Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

examples/ruvLLM/esp32-flash/src/benchmark.rs

@@ -0,0 +1,288 @@
+//! Benchmark Suite for RuvLLM ESP32
+//!
+//! Automated performance measurement across different configurations.
+//!
+//! # Metrics
+//! - Tokens per second
+//! - Memory usage
+//! - Latency percentiles
+//! - Power consumption (estimated)
+
+use core::fmt;
+
+/// Benchmark result
+#[derive(Clone, Default)]
+pub struct BenchmarkResult {
+    /// Test name
+    pub name: heapless::String<32>,
+    /// Tokens per second
+    pub tokens_per_sec: f32,
+    /// Time to first token (ms)
+    pub ttft_ms: u32,
+    /// Average latency per token (ms)
+    pub avg_latency_ms: f32,
+    /// P50 latency (ms)
+    pub p50_latency_ms: f32,
+    /// P99 latency (ms)
+    pub p99_latency_ms: f32,
+    /// Peak memory usage (bytes)
+    pub peak_memory: u32,
+    /// Total tokens generated
+    pub total_tokens: u32,
+    /// Total time (ms)
+    pub total_time_ms: u32,
+}
+
+impl fmt::Display for BenchmarkResult {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "{}: {:.1} tok/s, TTFT: {}ms, avg: {:.1}ms, mem: {}KB",
+            self.name,
+            self.tokens_per_sec,
+            self.ttft_ms,
+            self.avg_latency_ms,
+            self.peak_memory / 1024
+        )
+    }
+}
+
+/// Benchmark configuration
+#[derive(Clone)]
+pub struct BenchmarkConfig {
+    /// Number of warmup iterations
+    pub warmup_iters: u32,
+    /// Number of benchmark iterations
+    pub bench_iters: u32,
+    /// Tokens to generate per iteration
+    pub tokens_per_iter: u32,
+    /// Input prompt
+    pub prompt: heapless::String<128>,
+}
+
+impl Default for BenchmarkConfig {
+    fn default() -> Self {
+        Self {
+            warmup_iters: 3,
+            bench_iters: 10,
+            tokens_per_iter: 32,
+            prompt: heapless::String::try_from("Once upon a time").unwrap_or_default(),
+        }
+    }
+}
+
+/// Benchmark suite
+pub struct BenchmarkSuite {
+    results: heapless::Vec<BenchmarkResult, 16>,
+    config: BenchmarkConfig,
+}
+
+impl BenchmarkSuite {
+    /// Create new benchmark suite
+    pub fn new(config: BenchmarkConfig) -> Self {
+        Self {
+            results: heapless::Vec::new(),
+            config,
+        }
+    }
+
+    /// Run inference benchmark
+    pub fn run_inference_benchmark(&mut self) -> BenchmarkResult {
+        let mut result = BenchmarkResult::default();
+        let _ = result.name.push_str("inference");
+
+        // Simulated benchmark (in real impl, would use actual inference)
+        let mut latencies: heapless::Vec<f32, 64> = heapless::Vec::new();
+
+        // Simulate token generation timing
+        for i in 0..self.config.tokens_per_iter {
+            // First token is slower (model loading/prefill)
+            let latency = if i == 0 { 50.0 } else { 20.0 + (i as f32 * 0.1) };
+            let _ = latencies.push(latency);
+        }
+
+        // Calculate statistics
+        result.ttft_ms = latencies.first().map(|&l| l as u32).unwrap_or(0);
+        result.total_tokens = self.config.tokens_per_iter;
+        result.total_time_ms = latencies.iter().sum::<f32>() as u32;
+        result.tokens_per_sec = if result.total_time_ms > 0 {
+            (result.total_tokens as f32 * 1000.0) / result.total_time_ms as f32
+        } else {
+            0.0
+        };
+        result.avg_latency_ms = result.total_time_ms as f32 / result.total_tokens as f32;
+
+        // Sort for percentiles
+        latencies.sort_by(|a, b| a.partial_cmp(b).unwrap_or(core::cmp::Ordering::Equal));
+        let len = latencies.len();
+        result.p50_latency_ms = latencies.get(len / 2).copied().unwrap_or(0.0);
+        result.p99_latency_ms = latencies.get(len * 99 / 100).copied().unwrap_or(0.0);
+
+        // Simulated memory
+        result.peak_memory = 32 * 1024; // 32KB
+
+        let _ = self.results.push(result.clone());
+        result
+    }
+
+    /// Run HNSW search benchmark
+    pub fn run_hnsw_benchmark(&mut self, num_vectors: usize) -> BenchmarkResult {
+        let mut result = BenchmarkResult::default();
+        let _ = result.name.push_str("hnsw_search");
+
+        // Simulated HNSW performance
+        // Real implementation would measure actual search times
+        let base_latency = 0.5; // 0.5ms base
+        let log_factor = (num_vectors as f32).ln() * 0.1;
+
+        result.avg_latency_ms = base_latency + log_factor;
+        result.p50_latency_ms = result.avg_latency_ms * 0.9;
+        result.p99_latency_ms = result.avg_latency_ms * 2.5;
+        result.tokens_per_sec = 1000.0 / result.avg_latency_ms; // Queries per second
+        result.peak_memory = (num_vectors * 48) as u32; // ~48 bytes per vector
+
+        let _ = self.results.push(result.clone());
+        result
+    }
+
+    /// Run quantization benchmark
+    pub fn run_quantization_benchmark(&mut self) -> BenchmarkResult {
+        let mut result = BenchmarkResult::default();
+        let _ = result.name.push_str("quantization");
+
+        // Measure INT8 vs FP32 speedup
+        result.tokens_per_sec = 45.0; // Typical INT8 performance
+        result.avg_latency_ms = 22.0;
+        result.peak_memory = 16 * 1024; // 16KB for quantized weights
+
+        let _ = self.results.push(result.clone());
+        result
+    }
+
+    /// Run RAG benchmark
+    pub fn run_rag_benchmark(&mut self) -> BenchmarkResult {
+        let mut result = BenchmarkResult::default();
+        let _ = result.name.push_str("rag_pipeline");
+
+        // RAG = embedding + search + generation
+        let embed_time = 5.0; // 5ms embedding
+        let search_time = 1.0; // 1ms HNSW search
+        let gen_time = 640.0; // 32 tokens * 20ms
+
+        result.ttft_ms = (embed_time + search_time + 50.0) as u32; // First token includes retrieval
+        result.total_time_ms = (embed_time + search_time + gen_time) as u32;
+        result.total_tokens = 32;
+        result.tokens_per_sec = (result.total_tokens as f32 * 1000.0) / result.total_time_ms as f32;
+        result.avg_latency_ms = gen_time / 32.0;
+        result.peak_memory = 48 * 1024; // 48KB
+
+        let _ = self.results.push(result.clone());
+        result
+    }
+
+    /// Get all results
+    pub fn results(&self) -> &[BenchmarkResult] {
+        &self.results
+    }
+
+    /// Generate benchmark report
+    pub fn generate_report(&self) -> heapless::String<2048> {
+        let mut report = heapless::String::new();
+
+        let _ = report.push_str("\n");
+        let _ = report.push_str("═══════════════════════════════════════════════════════════════\n");
+        let _ = report.push_str("                    RuvLLM ESP32 Benchmark Report              \n");
+        let _ = report.push_str("═══════════════════════════════════════════════════════════════\n\n");
+
+        let _ = report.push_str("Test              Tok/s    TTFT    Avg Lat   P99 Lat   Memory\n");
+        let _ = report.push_str("───────────────────────────────────────────────────────────────\n");
+
+        for result in &self.results {
+            let _ = core::fmt::write(
+                &mut report,
+                format_args!(
+                    "{:<16} {:>6.1}   {:>4}ms   {:>6.1}ms  {:>6.1}ms  {:>5}KB\n",
+                    result.name,
+                    result.tokens_per_sec,
+                    result.ttft_ms,
+                    result.avg_latency_ms,
+                    result.p99_latency_ms,
+                    result.peak_memory / 1024
+                )
+            );
+        }
+
+        let _ = report.push_str("───────────────────────────────────────────────────────────────\n");
+
+        // Summary statistics
+        if !self.results.is_empty() {
+            let avg_tps: f32 = self.results.iter().map(|r| r.tokens_per_sec).sum::<f32>()
+                / self.results.len() as f32;
+            let total_mem: u32 = self.results.iter().map(|r| r.peak_memory).max().unwrap_or(0);
+
+            let _ = core::fmt::write(
+                &mut report,
+                format_args!("\nSummary: Avg {:.1} tok/s, Peak memory: {}KB\n", avg_tps, total_mem / 1024)
+            );
+        }
+
+        report
+    }
+
+    /// Run all benchmarks
+    pub fn run_all(&mut self) {
+        self.run_inference_benchmark();
+        self.run_hnsw_benchmark(1000);
+        self.run_quantization_benchmark();
+        self.run_rag_benchmark();
+    }
+}
+
+/// Chip-specific benchmarks
+pub fn benchmark_chip(chip: &str) -> heapless::String<512> {
+    let mut output = heapless::String::new();
+
+    let (cpu, mhz, simd) = match chip {
+        "esp32" => ("Xtensa LX6", 240, false),
+        "esp32s2" => ("Xtensa LX7", 240, false),
+        "esp32s3" => ("Xtensa LX7", 240, true),
+        "esp32c3" => ("RISC-V", 160, false),
+        "esp32c6" => ("RISC-V", 160, false),
+        _ => ("Unknown", 0, false),
+    };
+
+    let base_tps = if simd { 60.0 } else { 40.0 };
+    let scaled_tps = base_tps * (mhz as f32 / 240.0);
+
+    let _ = core::fmt::write(
+        &mut output,
+        format_args!(
+            "Chip: {}\nCPU: {} @ {}MHz\nSIMD: {}\nEstimated: {:.0} tok/s\n",
+            chip, cpu, mhz, if simd { "Yes" } else { "No" }, scaled_tps
+        )
+    );
+
+    output
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_benchmark_suite() {
+        let config = BenchmarkConfig::default();
+        let mut suite = BenchmarkSuite::new(config);
+
+        suite.run_all();
+
+        assert_eq!(suite.results().len(), 4);
+        assert!(suite.results()[0].tokens_per_sec > 0.0);
+    }
+
+    #[test]
+    fn test_chip_benchmark() {
+        let output = benchmark_chip("esp32s3");
+        assert!(output.contains("SIMD: Yes"));
+    }
+}

examples/ruvLLM/esp32-flash/src/diagnostics.rs

@@ -0,0 +1,326 @@
+//! Error Diagnostics with Fix Suggestions
+//!
+//! Provides helpful error messages and automated fix suggestions
+//! for common issues encountered during build, flash, and runtime.
+
+use core::fmt;
+use heapless::String;
+
+/// Diagnostic severity
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Severity {
+    /// Informational message
+    Info,
+    /// Warning - may cause issues
+    Warning,
+    /// Error - operation failed
+    Error,
+    /// Fatal - cannot continue
+    Fatal,
+}
+
+impl fmt::Display for Severity {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Severity::Info => write!(f, "INFO"),
+            Severity::Warning => write!(f, "WARN"),
+            Severity::Error => write!(f, "ERROR"),
+            Severity::Fatal => write!(f, "FATAL"),
+        }
+    }
+}
+
+/// Error category
+#[derive(Debug, Clone, Copy)]
+pub enum ErrorCategory {
+    /// Build/compilation errors
+    Build,
+    /// Toolchain issues
+    Toolchain,
+    /// Flash/upload errors
+    Flash,
+    /// Runtime errors
+    Runtime,
+    /// Memory issues
+    Memory,
+    /// Network/WiFi errors
+    Network,
+    /// Hardware issues
+    Hardware,
+}
+
+/// Diagnostic result with fix suggestions
+#[derive(Clone)]
+pub struct Diagnostic {
+    /// Error code (e.g., "E0001")
+    pub code: String<8>,
+    /// Severity level
+    pub severity: Severity,
+    /// Error category
+    pub category: ErrorCategory,
+    /// Short description
+    pub message: String<128>,
+    /// Detailed explanation
+    pub explanation: String<256>,
+    /// Suggested fixes
+    pub fixes: heapless::Vec<String<128>, 4>,
+    /// Related documentation link
+    pub docs_url: Option<String<128>>,
+}
+
+impl Diagnostic {
+    /// Create new diagnostic
+    pub fn new(code: &str, severity: Severity, category: ErrorCategory, message: &str) -> Self {
+        Self {
+            code: String::try_from(code).unwrap_or_default(),
+            severity,
+            category,
+            message: String::try_from(message).unwrap_or_default(),
+            explanation: String::new(),
+            fixes: heapless::Vec::new(),
+            docs_url: None,
+        }
+    }
+
+    /// Add explanation
+    pub fn with_explanation(mut self, explanation: &str) -> Self {
+        self.explanation = String::try_from(explanation).unwrap_or_default();
+        self
+    }
+
+    /// Add fix suggestion
+    pub fn with_fix(mut self, fix: &str) -> Self {
+        let _ = self.fixes.push(String::try_from(fix).unwrap_or_default());
+        self
+    }
+
+    /// Add documentation URL
+    pub fn with_docs(mut self, url: &str) -> Self {
+        self.docs_url = Some(String::try_from(url).unwrap_or_default());
+        self
+    }
+}
+
+impl fmt::Display for Diagnostic {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        writeln!(f, "\n[{}] {}: {}", self.code, self.severity, self.message)?;
+
+        if !self.explanation.is_empty() {
+            writeln!(f, "\n  {}", self.explanation)?;
+        }
+
+        if !self.fixes.is_empty() {
+            writeln!(f, "\n  Suggested fixes:")?;
+            for (i, fix) in self.fixes.iter().enumerate() {
+                writeln!(f, "    {}. {}", i + 1, fix)?;
+            }
+        }
+
+        if let Some(url) = &self.docs_url {
+            writeln!(f, "\n  Documentation: {}", url)?;
+        }
+
+        Ok(())
+    }
+}
+
+/// Known error patterns and their diagnostics
+pub fn diagnose_error(error_text: &str) -> Option<Diagnostic> {
+    // Toolchain errors
+    if error_text.contains("espup") && error_text.contains("not found") {
+        return Some(
+            Diagnostic::new("T0001", Severity::Error, ErrorCategory::Toolchain, "ESP toolchain not installed")
+                .with_explanation("The ESP32 Rust toolchain (espup) is not installed or not in PATH.")
+                .with_fix("Run: npx ruvllm-esp32 install")
+                .with_fix("Or manually: cargo install espup && espup install")
+                .with_fix("Then restart your terminal or run: source ~/export-esp.sh")
+                .with_docs("https://esp-rs.github.io/book/installation/")
+        );
+    }
+
+    if error_text.contains("LIBCLANG_PATH") {
+        return Some(
+            Diagnostic::new("T0002", Severity::Error, ErrorCategory::Toolchain, "LIBCLANG_PATH not set")
+                .with_explanation("The LIBCLANG_PATH environment variable is not set or points to an invalid location.")
+                .with_fix("Windows: Run .\\scripts\\windows\\env.ps1")
+                .with_fix("Linux/Mac: source ~/export-esp.sh")
+                .with_fix("Or set manually: export LIBCLANG_PATH=/path/to/libclang")
+        );
+    }
+
+    if error_text.contains("ldproxy") && error_text.contains("not found") {
+        return Some(
+            Diagnostic::new("T0003", Severity::Error, ErrorCategory::Toolchain, "ldproxy not installed")
+                .with_explanation("The ldproxy linker wrapper is required for ESP32 builds.")
+                .with_fix("Run: cargo install ldproxy")
+        );
+    }
+
+    // Flash errors
+    if error_text.contains("Permission denied") && error_text.contains("/dev/tty") {
+        return Some(
+            Diagnostic::new("F0001", Severity::Error, ErrorCategory::Flash, "Serial port permission denied")
+                .with_explanation("Your user does not have permission to access the serial port.")
+                .with_fix("Add user to dialout group: sudo usermod -a -G dialout $USER")
+                .with_fix("Then log out and log back in")
+                .with_fix("Or use sudo (not recommended): sudo espflash flash ...")
+        );
+    }
+
+    if error_text.contains("No such file or directory") && error_text.contains("/dev/tty") {
+        return Some(
+            Diagnostic::new("F0002", Severity::Error, ErrorCategory::Flash, "Serial port not found")
+                .with_explanation("The specified serial port does not exist. The ESP32 may not be connected.")
+                .with_fix("Check USB connection")
+                .with_fix("Try a different USB cable (data cable, not charge-only)")
+                .with_fix("Install USB-to-serial drivers if needed")
+                .with_fix("Run 'ls /dev/tty*' to find available ports")
+        );
+    }
+
+    if error_text.contains("A]fatal error occurred: Failed to connect") {
+        return Some(
+            Diagnostic::new("F0003", Severity::Error, ErrorCategory::Flash, "Failed to connect to ESP32")
+                .with_explanation("Could not establish connection with the ESP32 bootloader.")
+                .with_fix("Hold BOOT button while connecting")
+                .with_fix("Try pressing RESET while holding BOOT")
+                .with_fix("Check that the correct port is selected")
+                .with_fix("Try a lower baud rate: --baud 115200")
+        );
+    }
+
+    // Memory errors
+    if error_text.contains("out of memory") || error_text.contains("alloc") {
+        return Some(
+            Diagnostic::new("M0001", Severity::Error, ErrorCategory::Memory, "Out of memory")
+                .with_explanation("The device ran out of RAM during operation.")
+                .with_fix("Use a smaller model (e.g., nanoembed-500k)")
+                .with_fix("Reduce max_seq_len in config")
+                .with_fix("Enable binary quantization for 32x compression")
+                .with_fix("Use ESP32-S3 for more SRAM (512KB)")
+        );
+    }
+
+    if error_text.contains("stack overflow") {
+        return Some(
+            Diagnostic::new("M0002", Severity::Fatal, ErrorCategory::Memory, "Stack overflow")
+                .with_explanation("The call stack exceeded its allocated size.")
+                .with_fix("Increase stack size in sdkconfig")
+                .with_fix("Reduce recursion depth in your code")
+                .with_fix("Move large arrays to heap allocation")
+        );
+    }
+
+    // Build errors
+    if error_text.contains("error[E0433]") && error_text.contains("esp_idf") {
+        return Some(
+            Diagnostic::new("B0001", Severity::Error, ErrorCategory::Build, "ESP-IDF crate not found")
+                .with_explanation("The esp-idf-* crates are not available for your target.")
+                .with_fix("Ensure you're using the ESP toolchain: rustup default esp")
+                .with_fix("Check that esp feature is enabled in Cargo.toml")
+                .with_fix("Run: source ~/export-esp.sh")
+        );
+    }
+
+    if error_text.contains("target may not be installed") {
+        return Some(
+            Diagnostic::new("B0002", Severity::Error, ErrorCategory::Build, "Target not installed")
+                .with_explanation("The Rust target for your ESP32 variant is not installed.")
+                .with_fix("Run: espup install")
+                .with_fix("Or: rustup target add <target>")
+        );
+    }
+
+    // Network errors
+    if error_text.contains("WiFi") && error_text.contains("connect") {
+        return Some(
+            Diagnostic::new("N0001", Severity::Error, ErrorCategory::Network, "WiFi connection failed")
+                .with_explanation("Could not connect to the WiFi network.")
+                .with_fix("Check SSID and password")
+                .with_fix("Ensure the network is 2.4GHz (ESP32 doesn't support 5GHz)")
+                .with_fix("Move closer to the access point")
+                .with_fix("Check that the network is not hidden")
+        );
+    }
+
+    None
+}
+
+/// Check system for common issues
+pub fn run_diagnostics() -> heapless::Vec<Diagnostic, 8> {
+    let mut issues = heapless::Vec::new();
+
+    // These would be actual checks in a real implementation
+    // Here we just show the structure
+
+    // Check available memory
+    // In real impl: check heap_caps_get_free_size()
+
+    // Check flash size
+    // In real impl: check partition table
+
+    // Check WiFi status
+    // In real impl: check esp_wifi_get_mode()
+
+    issues
+}
+
+/// Print diagnostic in colored format (for terminals)
+pub fn format_diagnostic_colored(diag: &Diagnostic) -> String<512> {
+    let mut output = String::new();
+
+    let color = match diag.severity {
+        Severity::Info => "\x1b[36m",    // Cyan
+        Severity::Warning => "\x1b[33m", // Yellow
+        Severity::Error => "\x1b[31m",   // Red
+        Severity::Fatal => "\x1b[35m",   // Magenta
+    };
+    let reset = "\x1b[0m";
+
+    let _ = core::fmt::write(
+        &mut output,
+        format_args!("\n{}[{}]{} {}: {}\n", color, diag.code, reset, diag.severity, diag.message)
+    );
+
+    if !diag.explanation.is_empty() {
+        let _ = core::fmt::write(&mut output, format_args!("\n  {}\n", diag.explanation));
+    }
+
+    if !diag.fixes.is_empty() {
+        let _ = output.push_str("\n  \x1b[32mSuggested fixes:\x1b[0m\n");
+        for (i, fix) in diag.fixes.iter().enumerate() {
+            let _ = core::fmt::write(&mut output, format_args!("    {}. {}\n", i + 1, fix));
+        }
+    }
+
+    output
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_diagnose_toolchain_error() {
+        let error = "error: espup: command not found";
+        let diag = diagnose_error(error);
+        assert!(diag.is_some());
+        assert_eq!(diag.unwrap().code.as_str(), "T0001");
+    }
+
+    #[test]
+    fn test_diagnose_flash_error() {
+        let error = "Permission denied: /dev/ttyUSB0";
+        let diag = diagnose_error(error);
+        assert!(diag.is_some());
+        assert_eq!(diag.unwrap().code.as_str(), "F0001");
+    }
+
+    #[test]
+    fn test_diagnose_memory_error() {
+        let error = "panicked at 'alloc error'";
+        let diag = diagnose_error(error);
+        assert!(diag.is_some());
+        assert_eq!(diag.unwrap().code.as_str(), "M0001");
+    }
+}

examples/ruvLLM/esp32-flash/src/federation/mod.rs

@@ -0,0 +1,176 @@
+//! Federation Module for Multi-Chip Distributed Inference
+//!
+//! Supports:
+//! - Pipeline parallelism (layers across chips)
+//! - Tensor parallelism (attention heads across chips)
+//! - Speculative decoding (draft/verify)
+//! - SPI/I2C/UART/ESP-NOW communication
+
+pub mod protocol;
+pub mod pipeline;
+pub mod speculative;
+
+pub use protocol::{
+    ChipId, MessageType, MessageHeader, FederationMessage, CommStats,
+    MAX_ACTIVATION_SIZE, MAX_PAYLOAD_SIZE,
+};
+pub use pipeline::{
+    PipelineNode, PipelineConfig, PipelineRole, PipelineState, PipelineStats,
+    InFlightToken, calculate_pipeline_efficiency,
+    MAX_LAYERS_PER_CHIP, MAX_PIPELINE_DEPTH,
+};
+pub use speculative::{
+    SpeculativeDecoder, DraftVerifyConfig, DraftResult, VerifyResult, SpecStats,
+    MAX_DRAFT_TOKENS,
+};
+
+/// Maximum chips in federation
+pub const MAX_FEDERATION_SIZE: usize = 8;
+
+/// Federation mode
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum FederationMode {
+    Standalone,
+    Pipeline,
+    TensorParallel,
+    Hybrid,
+    Speculative,
+    MixtureOfExperts,
+}
+
+/// Communication bus type
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum CommunicationBus {
+    Spi,
+    I2c,
+    Uart,
+    EspNow,
+    Parallel,
+}
+
+impl CommunicationBus {
+    pub const fn bandwidth_bytes_per_sec(&self) -> usize {
+        match self {
+            Self::Spi => 10_000_000,
+            Self::I2c => 100_000,
+            Self::Uart => 500_000,
+            Self::EspNow => 125_000,
+            Self::Parallel => 20_000_000,
+        }
+    }
+
+    pub const fn latency_us(&self) -> usize {
+        match self {
+            Self::Spi => 10,
+            Self::I2c => 50,
+            Self::Uart => 20,
+            Self::EspNow => 500,
+            Self::Parallel => 5,
+        }
+    }
+}
+
+/// Federation configuration
+#[derive(Debug, Clone)]
+pub struct FederationConfig {
+    pub num_chips: usize,
+    pub chip_id: ChipId,
+    pub mode: FederationMode,
+    pub bus: CommunicationBus,
+    pub layers_per_chip: usize,
+    pub heads_per_chip: usize,
+    pub enable_pipelining: bool,
+}
+
+impl Default for FederationConfig {
+    fn default() -> Self {
+        Self {
+            num_chips: 5,
+            chip_id: ChipId(0),
+            mode: FederationMode::Pipeline,
+            bus: CommunicationBus::Spi,
+            layers_per_chip: 2,
+            heads_per_chip: 1,
+            enable_pipelining: true,
+        }
+    }
+}
+
+/// Calculate optimal federation config
+pub fn calculate_optimal_config(
+    model_size: usize,
+    num_layers: usize,
+    num_heads: usize,
+    num_chips: usize,
+    per_chip_ram: usize,
+) -> FederationConfig {
+    let model_per_chip = model_size / num_chips;
+
+    if model_per_chip <= per_chip_ram {
+        let layers_per_chip = (num_layers + num_chips - 1) / num_chips;
+        FederationConfig {
+            num_chips,
+            chip_id: ChipId(0),
+            mode: FederationMode::Pipeline,
+            bus: CommunicationBus::Spi,
+            layers_per_chip,
+            heads_per_chip: num_heads,
+            enable_pipelining: true,
+        }
+    } else {
+        let heads_per_chip = (num_heads + num_chips - 1) / num_chips;
+        FederationConfig {
+            num_chips,
+            chip_id: ChipId(0),
+            mode: FederationMode::TensorParallel,
+            bus: CommunicationBus::Spi,
+            layers_per_chip: num_layers,
+            heads_per_chip,
+            enable_pipelining: false,
+        }
+    }
+}
+
+/// Federation speedup estimates
+#[derive(Debug, Clone)]
+pub struct FederationSpeedup {
+    pub throughput_multiplier: f32,
+    pub latency_reduction: f32,
+    pub memory_per_chip_reduction: f32,
+}
+
+pub fn estimate_speedup(config: &FederationConfig) -> FederationSpeedup {
+    let n = config.num_chips as f32;
+    match config.mode {
+        FederationMode::Standalone => FederationSpeedup {
+            throughput_multiplier: 1.0,
+            latency_reduction: 1.0,
+            memory_per_chip_reduction: 1.0,
+        },
+        FederationMode::Pipeline => FederationSpeedup {
+            throughput_multiplier: n * 0.85,
+            latency_reduction: 1.0 / (1.0 + 0.1 * (n - 1.0)),
+            memory_per_chip_reduction: n,
+        },
+        FederationMode::TensorParallel => FederationSpeedup {
+            throughput_multiplier: n * 0.7,
+            latency_reduction: n * 0.7,
+            memory_per_chip_reduction: n * 0.8,
+        },
+        FederationMode::Hybrid => FederationSpeedup {
+            throughput_multiplier: n * 0.75,
+            latency_reduction: (n / 2.0) * 0.8,
+            memory_per_chip_reduction: n * 0.9,
+        },
+        FederationMode::Speculative => FederationSpeedup {
+            throughput_multiplier: 2.5,
+            latency_reduction: 2.0,
+            memory_per_chip_reduction: 1.0,
+        },
+        FederationMode::MixtureOfExperts => FederationSpeedup {
+            throughput_multiplier: n * 0.9,
+            latency_reduction: 1.5,
+            memory_per_chip_reduction: n,
+        },
+    }
+}

examples/ruvLLM/esp32-flash/src/federation/pipeline.rs

@@ -0,0 +1,180 @@
+//! Pipeline Parallelism for Multi-ESP32 Inference
+
+use heapless::Vec as HVec;
+use super::protocol::{ChipId, FederationMessage};
+
+pub const MAX_LAYERS_PER_CHIP: usize = 4;
+pub const MAX_PIPELINE_DEPTH: usize = 8;
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum PipelineRole { Head, Middle, Tail, Standalone }
+
+#[derive(Debug, Clone)]
+pub struct PipelineConfig {
+    pub num_chips: usize,
+    pub position: usize,
+    pub layer_start: usize,
+    pub layer_count: usize,
+    pub total_layers: usize,
+    pub embed_dim: usize,
+    pub micro_batch_size: usize,
+}
+
+impl PipelineConfig {
+    pub fn for_chip(chip_pos: usize, num_chips: usize, total_layers: usize, embed_dim: usize) -> Self {
+        let layers_per_chip = (total_layers + num_chips - 1) / num_chips;
+        let layer_start = chip_pos * layers_per_chip;
+        let layer_count = layers_per_chip.min(total_layers - layer_start);
+        Self { num_chips, position: chip_pos, layer_start, layer_count, total_layers, embed_dim, micro_batch_size: 1 }
+    }
+
+    pub fn role(&self) -> PipelineRole {
+        if self.num_chips == 1 { PipelineRole::Standalone }
+        else if self.position == 0 { PipelineRole::Head }
+        else if self.position == self.num_chips - 1 { PipelineRole::Tail }
+        else { PipelineRole::Middle }
+    }
+
+    pub fn prev_chip(&self) -> Option<ChipId> {
+        if self.position > 0 { Some(ChipId((self.position - 1) as u8)) } else { None }
+    }
+
+    pub fn next_chip(&self) -> Option<ChipId> {
+        if self.position + 1 < self.num_chips { Some(ChipId((self.position + 1) as u8)) } else { None }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum PipelineState { WaitingInput, Processing, WaitingSend, Idle }
+
+#[derive(Debug, Clone)]
+pub struct InFlightToken {
+    pub seq_pos: u16,
+    pub token_id: u16,
+    pub current_layer: u8,
+    pub activation: HVec<i8, 128>,
+}
+
+pub struct PipelineNode {
+    config: PipelineConfig,
+    state: PipelineState,
+    chip_id: ChipId,
+    seq_counter: u16,
+    in_flight: HVec<InFlightToken, MAX_PIPELINE_DEPTH>,
+    output_queue: HVec<InFlightToken, MAX_PIPELINE_DEPTH>,
+    barrier_counter: u16,
+}
+
+impl PipelineNode {
+    pub fn new(config: PipelineConfig) -> Self {
+        Self {
+            chip_id: ChipId(config.position as u8),
+            config,
+            state: PipelineState::Idle,
+            seq_counter: 0,
+            in_flight: HVec::new(),
+            output_queue: HVec::new(),
+            barrier_counter: 0,
+        }
+    }
+
+    pub fn state(&self) -> PipelineState { self.state }
+    pub fn handles_embedding(&self) -> bool { matches!(self.config.role(), PipelineRole::Head | PipelineRole::Standalone) }
+    pub fn handles_output(&self) -> bool { matches!(self.config.role(), PipelineRole::Tail | PipelineRole::Standalone) }
+
+    pub fn start_token(&mut self, token_id: u16) -> crate::Result<()> {
+        if !self.handles_embedding() { return Err(crate::Error::UnsupportedFeature("Not head chip")); }
+        if self.in_flight.len() >= MAX_PIPELINE_DEPTH { return Err(crate::Error::BufferOverflow); }
+
+        let token = InFlightToken { seq_pos: self.seq_counter, token_id, current_layer: 0, activation: HVec::new() };
+        self.in_flight.push(token).map_err(|_| crate::Error::BufferOverflow)?;
+        self.seq_counter += 1;
+        self.state = PipelineState::Processing;
+        Ok(())
+    }
+
+    pub fn receive_activation(&mut self, msg: &FederationMessage) -> crate::Result<()> {
+        let (layer_idx, position, data) = msg.get_activation_data()
+            .ok_or(crate::Error::InvalidModel("Invalid activation"))?;
+
+        let mut activation = HVec::new();
+        for &d in data { activation.push(d as i8).map_err(|_| crate::Error::BufferOverflow)?; }
+
+        let token = InFlightToken { seq_pos: position, token_id: 0, current_layer: layer_idx, activation };
+        self.in_flight.push(token).map_err(|_| crate::Error::BufferOverflow)?;
+        self.state = PipelineState::Processing;
+        Ok(())
+    }
+
+    pub fn process_step<F>(&mut self, mut layer_fn: F) -> crate::Result<bool>
+    where F: FnMut(usize, &mut [i8]) -> crate::Result<()>
+    {
+        if self.in_flight.is_empty() {
+            self.state = PipelineState::WaitingInput;
+            return Ok(false);
+        }
+
+        let token = &mut self.in_flight[0];
+        let relative_layer = token.current_layer as usize - self.config.layer_start;
+
+        if relative_layer < self.config.layer_count {
+            let layer_idx = self.config.layer_start + relative_layer;
+            layer_fn(layer_idx, &mut token.activation)?;
+            token.current_layer += 1;
+        }
+
+        let next = token.current_layer as usize;
+        if next >= self.config.layer_start + self.config.layer_count {
+            if let Some(completed) = self.in_flight.pop() {
+                self.output_queue.push(completed).map_err(|_| crate::Error::BufferOverflow)?;
+            }
+            self.state = PipelineState::WaitingSend;
+        }
+        Ok(true)
+    }
+
+    pub fn get_output(&mut self) -> Option<FederationMessage> {
+        if self.output_queue.is_empty() { return None; }
+        let token = self.output_queue.pop()?;
+        let next_chip = self.config.next_chip()?;
+        let data: heapless::Vec<i8, 128> = token.activation.iter().cloned().collect();
+        FederationMessage::activation(self.chip_id, next_chip, token.seq_pos, token.current_layer, token.seq_pos, &data).ok()
+    }
+
+    pub fn has_final_output(&self) -> bool { self.handles_output() && !self.output_queue.is_empty() }
+
+    pub fn get_final_output(&mut self) -> Option<HVec<i8, 128>> {
+        if !self.handles_output() { return None; }
+        self.output_queue.pop().map(|t| t.activation)
+    }
+
+    pub fn stats(&self) -> PipelineStats {
+        PipelineStats {
+            in_flight_count: self.in_flight.len(),
+            output_queue_len: self.output_queue.len(),
+            tokens_processed: self.seq_counter as usize,
+            current_state: self.state,
+        }
+    }
+
+    pub fn create_barrier(&mut self) -> FederationMessage {
+        self.barrier_counter += 1;
+        FederationMessage::barrier(self.chip_id, self.barrier_counter)
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct PipelineStats {
+    pub in_flight_count: usize,
+    pub output_queue_len: usize,
+    pub tokens_processed: usize,
+    pub current_state: PipelineState,
+}
+
+pub fn calculate_pipeline_efficiency(num_chips: usize, tokens: usize) -> f32 {
+    if tokens <= num_chips {
+        tokens as f32 / (num_chips as f32 * tokens as f32)
+    } else {
+        tokens as f32 / (tokens as f32 + (num_chips - 1) as f32)
+    }
+}

examples/ruvLLM/esp32-flash/src/federation/protocol.rs

@@ -0,0 +1,187 @@
+//! Inter-Chip Communication Protocol
+
+use heapless::Vec as HVec;
+
+pub const MAX_ACTIVATION_SIZE: usize = 256;
+pub const MAX_PAYLOAD_SIZE: usize = 512;
+pub const PROTOCOL_VERSION: u8 = 1;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub struct ChipId(pub u8);
+
+impl ChipId {
+    pub const BROADCAST: ChipId = ChipId(0xFF);
+    pub fn is_broadcast(&self) -> bool { self.0 == 0xFF }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+#[repr(u8)]
+pub enum MessageType {
+    Heartbeat = 0x00,
+    Discovery = 0x01,
+    Ready = 0x02,
+    Activation = 0x10,
+    KVCache = 0x11,
+    Gradient = 0x12,
+    EmbedRequest = 0x20,
+    EmbedResponse = 0x21,
+    Logits = 0x22,
+    Token = 0x23,
+    DraftTokens = 0x30,
+    VerifyResult = 0x31,
+    Barrier = 0x40,
+    Ack = 0x41,
+    Error = 0xFF,
+}
+
+impl From<u8> for MessageType {
+    fn from(v: u8) -> Self {
+        match v {
+            0x00 => Self::Heartbeat, 0x01 => Self::Discovery, 0x02 => Self::Ready,
+            0x10 => Self::Activation, 0x11 => Self::KVCache, 0x12 => Self::Gradient,
+            0x20 => Self::EmbedRequest, 0x21 => Self::EmbedResponse,
+            0x22 => Self::Logits, 0x23 => Self::Token,
+            0x30 => Self::DraftTokens, 0x31 => Self::VerifyResult,
+            0x40 => Self::Barrier, 0x41 => Self::Ack,
+            _ => Self::Error,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+#[repr(C, packed)]
+pub struct MessageHeader {
+    pub version: u8,
+    pub msg_type: u8,
+    pub src: u8,
+    pub dst: u8,
+    pub seq: u16,
+    pub payload_len: u16,
+}
+
+impl MessageHeader {
+    pub const SIZE: usize = 8;
+
+    pub fn new(msg_type: MessageType, src: ChipId, dst: ChipId, seq: u16, payload_len: u16) -> Self {
+        Self { version: PROTOCOL_VERSION, msg_type: msg_type as u8, src: src.0, dst: dst.0, seq, payload_len }
+    }
+
+    pub fn to_bytes(&self) -> [u8; 8] {
+        [self.version, self.msg_type, self.src, self.dst,
+         (self.seq & 0xFF) as u8, (self.seq >> 8) as u8,
+         (self.payload_len & 0xFF) as u8, (self.payload_len >> 8) as u8]
+    }
+
+    pub fn from_bytes(b: &[u8]) -> Option<Self> {
+        if b.len() < 8 { return None; }
+        Some(Self {
+            version: b[0], msg_type: b[1], src: b[2], dst: b[3],
+            seq: (b[4] as u16) | ((b[5] as u16) << 8),
+            payload_len: (b[6] as u16) | ((b[7] as u16) << 8),
+        })
+    }
+
+    pub fn checksum(&self) -> u8 {
+        self.to_bytes().iter().fold(0u8, |acc, &b| acc.wrapping_add(b))
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct FederationMessage {
+    pub header: MessageHeader,
+    pub payload: HVec<u8, MAX_PAYLOAD_SIZE>,
+    pub checksum: u8,
+}
+
+impl FederationMessage {
+    pub fn new(msg_type: MessageType, src: ChipId, dst: ChipId, seq: u16) -> Self {
+        Self {
+            header: MessageHeader::new(msg_type, src, dst, seq, 0),
+            payload: HVec::new(),
+            checksum: 0,
+        }
+    }
+
+    pub fn activation(src: ChipId, dst: ChipId, seq: u16, layer: u8, pos: u16, data: &[i8]) -> crate::Result<Self> {
+        let mut msg = Self::new(MessageType::Activation, src, dst, seq);
+        msg.payload.push(layer).map_err(|_| crate::Error::BufferOverflow)?;
+        msg.payload.push((pos & 0xFF) as u8).map_err(|_| crate::Error::BufferOverflow)?;
+        msg.payload.push((pos >> 8) as u8).map_err(|_| crate::Error::BufferOverflow)?;
+        for &d in data {
+            msg.payload.push(d as u8).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+        msg.header.payload_len = msg.payload.len() as u16;
+        msg.update_checksum();
+        Ok(msg)
+    }
+
+    pub fn token(src: ChipId, dst: ChipId, seq: u16, token_id: u16) -> Self {
+        let mut msg = Self::new(MessageType::Token, src, dst, seq);
+        let _ = msg.payload.push((token_id & 0xFF) as u8);
+        let _ = msg.payload.push((token_id >> 8) as u8);
+        msg.header.payload_len = 2;
+        msg.update_checksum();
+        msg
+    }
+
+    pub fn draft_tokens(src: ChipId, dst: ChipId, seq: u16, tokens: &[u16]) -> crate::Result<Self> {
+        let mut msg = Self::new(MessageType::DraftTokens, src, dst, seq);
+        msg.payload.push(tokens.len() as u8).map_err(|_| crate::Error::BufferOverflow)?;
+        for &t in tokens {
+            msg.payload.push((t & 0xFF) as u8).map_err(|_| crate::Error::BufferOverflow)?;
+            msg.payload.push((t >> 8) as u8).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+        msg.header.payload_len = msg.payload.len() as u16;
+        msg.update_checksum();
+        Ok(msg)
+    }
+
+    pub fn barrier(src: ChipId, barrier_id: u16) -> Self {
+        let mut msg = Self::new(MessageType::Barrier, src, ChipId::BROADCAST, 0);
+        let _ = msg.payload.push((barrier_id & 0xFF) as u8);
+        let _ = msg.payload.push((barrier_id >> 8) as u8);
+        msg.header.payload_len = 2;
+        msg.update_checksum();
+        msg
+    }
+
+    pub fn update_checksum(&mut self) {
+        let mut sum = self.header.checksum();
+        for &b in &self.payload { sum = sum.wrapping_add(b); }
+        self.checksum = sum;
+    }
+
+    pub fn verify_checksum(&self) -> bool {
+        let mut sum = self.header.checksum();
+        for &b in &self.payload { sum = sum.wrapping_add(b); }
+        sum == self.checksum
+    }
+
+    pub fn to_bytes(&self) -> HVec<u8, { MAX_PAYLOAD_SIZE + 16 }> {
+        let mut bytes = HVec::new();
+        for b in self.header.to_bytes() { let _ = bytes.push(b); }
+        for &b in &self.payload { let _ = bytes.push(b); }
+        let _ = bytes.push(self.checksum);
+        bytes
+    }
+
+    pub fn get_activation_data(&self) -> Option<(u8, u16, &[u8])> {
+        if self.header.msg_type != MessageType::Activation as u8 || self.payload.len() < 3 { return None; }
+        Some((self.payload[0], (self.payload[1] as u16) | ((self.payload[2] as u16) << 8), &self.payload[3..]))
+    }
+
+    pub fn get_token(&self) -> Option<u16> {
+        if self.header.msg_type != MessageType::Token as u8 || self.payload.len() < 2 { return None; }
+        Some((self.payload[0] as u16) | ((self.payload[1] as u16) << 8))
+    }
+}
+
+#[derive(Debug, Default, Clone)]
+pub struct CommStats {
+    pub messages_sent: u32,
+    pub messages_received: u32,
+    pub bytes_sent: u32,
+    pub bytes_received: u32,
+    pub checksum_errors: u32,
+    pub timeouts: u32,
+}

examples/ruvLLM/esp32-flash/src/federation/speculative.rs

@@ -0,0 +1,146 @@
+//! Speculative Decoding - Draft and Verify
+
+use heapless::Vec as HVec;
+use super::protocol::{ChipId, FederationMessage};
+
+pub const MAX_DRAFT_TOKENS: usize = 8;
+
+#[derive(Debug, Clone)]
+pub struct DraftVerifyConfig {
+    pub draft_length: usize,
+    pub acceptance_threshold: f32,
+    pub draft_chip: ChipId,
+    pub verify_chips: HVec<ChipId, 4>,
+    pub adaptive: bool,
+}
+
+impl Default for DraftVerifyConfig {
+    fn default() -> Self {
+        Self { draft_length: 4, acceptance_threshold: 0.9, draft_chip: ChipId(0), verify_chips: HVec::new(), adaptive: true }
+    }
+}
+
+impl DraftVerifyConfig {
+    pub fn for_five_chips() -> Self {
+        let mut verify_chips = HVec::new();
+        for i in 1..5 { let _ = verify_chips.push(ChipId(i)); }
+        Self { draft_length: 4, acceptance_threshold: 0.9, draft_chip: ChipId(0), verify_chips, adaptive: true }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct DraftResult {
+    pub tokens: HVec<u16, MAX_DRAFT_TOKENS>,
+    pub probs: HVec<u8, MAX_DRAFT_TOKENS>,
+    pub start_pos: u16,
+}
+
+#[derive(Debug, Clone)]
+pub struct VerifyResult {
+    pub accepted_count: usize,
+    pub correction: Option<u16>,
+    pub verify_probs: HVec<u8, MAX_DRAFT_TOKENS>,
+}
+
+pub struct SpeculativeDecoder {
+    config: DraftVerifyConfig,
+    is_draft_chip: bool,
+    acceptance_rate: f32,
+    pending_draft: Option<DraftResult>,
+    stats: SpecStats,
+}
+
+impl SpeculativeDecoder {
+    pub fn new(config: DraftVerifyConfig, chip_id: ChipId) -> Self {
+        let is_draft = chip_id == config.draft_chip;
+        Self { config, is_draft_chip: is_draft, acceptance_rate: 0.9, pending_draft: None, stats: SpecStats::default() }
+    }
+
+    pub fn is_drafter(&self) -> bool { self.is_draft_chip }
+
+    pub fn submit_draft(&mut self, draft: DraftResult) -> crate::Result<FederationMessage> {
+        if !self.is_draft_chip { return Err(crate::Error::UnsupportedFeature("Not draft chip")); }
+        let tokens: heapless::Vec<u16, MAX_DRAFT_TOKENS> = draft.tokens.iter().cloned().collect();
+        let msg = FederationMessage::draft_tokens(self.config.draft_chip, ChipId::BROADCAST, draft.start_pos, &tokens)?;
+        self.pending_draft = Some(draft);
+        self.stats.drafts_sent += 1;
+        Ok(msg)
+    }
+
+    pub fn verify_draft<F>(&mut self, draft: &DraftResult, mut get_prob: F) -> VerifyResult
+    where F: FnMut(u16, u16) -> u8
+    {
+        let mut accepted = 0;
+        let mut correction = None;
+        let mut verify_probs = HVec::new();
+
+        for (i, &token) in draft.tokens.iter().enumerate() {
+            let pos = draft.start_pos + i as u16;
+            let verify_prob = get_prob(pos, token);
+            let _ = verify_probs.push(verify_prob);
+            let draft_prob = draft.probs.get(i).copied().unwrap_or(128);
+            let threshold = (draft_prob as f32 * self.config.acceptance_threshold) as u8;
+
+            if verify_prob >= threshold {
+                accepted += 1;
+            } else {
+                correction = Some(token.wrapping_add(1));
+                break;
+            }
+        }
+
+        VerifyResult { accepted_count: accepted, correction, verify_probs }
+    }
+
+    pub fn process_verification(&mut self, result: &VerifyResult) -> HVec<u16, MAX_DRAFT_TOKENS> {
+        let mut accepted_tokens = HVec::new();
+
+        if let Some(ref draft) = self.pending_draft {
+            for i in 0..result.accepted_count {
+                if let Some(&token) = draft.tokens.get(i) {
+                    let _ = accepted_tokens.push(token);
+                }
+            }
+            if let Some(correct) = result.correction {
+                let _ = accepted_tokens.push(correct);
+            }
+
+            self.stats.tokens_accepted += result.accepted_count;
+            self.stats.tokens_rejected += draft.tokens.len() - result.accepted_count;
+            let rate = result.accepted_count as f32 / draft.tokens.len() as f32;
+            self.acceptance_rate = 0.9 * self.acceptance_rate + 0.1 * rate;
+        }
+
+        self.pending_draft = None;
+        accepted_tokens
+    }
+
+    pub fn adaptive_draft_length(&self) -> usize {
+        if !self.config.adaptive { return self.config.draft_length; }
+        if self.acceptance_rate > 0.95 { (self.config.draft_length + 2).min(MAX_DRAFT_TOKENS) }
+        else if self.acceptance_rate > 0.8 { self.config.draft_length }
+        else if self.acceptance_rate > 0.5 { (self.config.draft_length - 1).max(1) }
+        else { 1 }
+    }
+
+    pub fn estimated_speedup(&self) -> f32 {
+        let avg = self.acceptance_rate * self.adaptive_draft_length() as f32;
+        avg / 1.2
+    }
+
+    pub fn stats(&self) -> &SpecStats { &self.stats }
+}
+
+#[derive(Debug, Default, Clone)]
+pub struct SpecStats {
+    pub drafts_sent: usize,
+    pub tokens_accepted: usize,
+    pub tokens_rejected: usize,
+}
+
+impl SpecStats {
+    pub fn acceptance_rate(&self) -> f32 {
+        let total = self.tokens_accepted + self.tokens_rejected;
+        if total == 0 { 0.0 } else { self.tokens_accepted as f32 / total as f32 }
+    }
+}

examples/ruvLLM/esp32-flash/src/lib.rs

@@ -0,0 +1,150 @@
+//! RuvLLM ESP32 Flash - Complete Flashable Implementation
+//!
+//! Full-featured LLM inference engine for ESP32 with:
+//! - INT8/Binary quantized inference
+//! - Product quantization (8-32x compression)
+//! - MicroLoRA on-device adaptation
+//! - Sparse attention patterns
+//! - HNSW vector search (1000+ vectors)
+//! - Semantic memory with context
+//! - RAG (Retrieval-Augmented Generation)
+//! - Anomaly detection
+//! - Multi-chip federation
+//! - Pipeline/tensor parallelism
+//! - Speculative decoding
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+#[cfg(not(feature = "std"))]
+extern crate alloc;
+
+// Core modules
+pub mod optimizations;
+pub mod federation;
+pub mod ruvector;
+
+// Re-exports for convenience
+pub use optimizations::{
+    BinaryVector, BinaryEmbedding, hamming_distance, hamming_similarity,
+    ProductQuantizer, PQCode, PQConfig,
+    SoftmaxLUT, ExpLUT, DistanceLUT, SOFTMAX_LUT, DISTANCE_LUT,
+    MicroLoRA, LoRAConfig, LoRAStack,
+    SparseAttention, AttentionPattern,
+    LayerPruner, PruningConfig, PruningMask,
+};
+
+pub use federation::{
+    PipelineNode, PipelineConfig, PipelineRole, PipelineState,
+    FederationMessage, MessageType, ChipId, MessageHeader,
+    SpeculativeDecoder, DraftVerifyConfig, DraftResult, VerifyResult,
+    FederationConfig, FederationMode, CommunicationBus,
+};
+
+pub use ruvector::{
+    MicroHNSW, HNSWConfig, SearchResult,
+    SemanticMemory, Memory, MemoryType,
+    MicroRAG, RAGConfig, RAGResult,
+    AnomalyDetector, AnomalyConfig, AnomalyResult,
+    MicroVector, DistanceMetric,
+    euclidean_distance_i8, cosine_distance_i8, dot_product_i8,
+};
+
+/// ESP32 variant configuration
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum Esp32Variant {
+    /// Original ESP32: 520KB SRAM
+    Esp32,
+    /// ESP32-S2: 320KB SRAM
+    Esp32S2,
+    /// ESP32-S3: 512KB SRAM + vector instructions
+    Esp32S3,
+    /// ESP32-C3: 400KB SRAM, RISC-V
+    Esp32C3,
+    /// ESP32-C6: 512KB SRAM, RISC-V + WiFi 6
+    Esp32C6,
+}
+
+impl Esp32Variant {
+    /// Available SRAM in bytes
+    pub const fn sram_bytes(&self) -> usize {
+        match self {
+            Self::Esp32 => 520 * 1024,
+            Self::Esp32S2 => 320 * 1024,
+            Self::Esp32S3 => 512 * 1024,
+            Self::Esp32C3 => 400 * 1024,
+            Self::Esp32C6 => 512 * 1024,
+        }
+    }
+
+    /// Whether variant has hardware floating point
+    pub const fn has_fpu(&self) -> bool {
+        matches!(self, Self::Esp32S3)
+    }
+
+    /// Whether variant has vector/SIMD extensions
+    pub const fn has_simd(&self) -> bool {
+        matches!(self, Self::Esp32S3)
+    }
+
+    /// Recommended max model size (leaving ~200KB for runtime)
+    pub const fn max_model_ram(&self) -> usize {
+        self.sram_bytes().saturating_sub(200 * 1024)
+    }
+}
+
+/// Error types
+#[derive(Debug, Clone)]
+pub enum Error {
+    /// Model too large for available memory
+    ModelTooLarge { required: usize, available: usize },
+    /// Invalid model format
+    InvalidModel(&'static str),
+    /// Quantization error
+    QuantizationError(&'static str),
+    /// Buffer overflow
+    BufferOverflow,
+    /// Inference failed
+    InferenceFailed(&'static str),
+    /// Feature not supported
+    UnsupportedFeature(&'static str),
+    /// Communication error
+    CommunicationError(&'static str),
+}
+
+impl core::fmt::Display for Error {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Error::ModelTooLarge { required, available } => {
+                write!(f, "Model requires {} bytes, only {} available", required, available)
+            }
+            Error::InvalidModel(msg) => write!(f, "Invalid model: {}", msg),
+            Error::QuantizationError(msg) => write!(f, "Quantization error: {}", msg),
+            Error::BufferOverflow => write!(f, "Buffer overflow"),
+            Error::InferenceFailed(msg) => write!(f, "Inference failed: {}", msg),
+            Error::UnsupportedFeature(msg) => write!(f, "Unsupported: {}", msg),
+            Error::CommunicationError(msg) => write!(f, "Communication error: {}", msg),
+        }
+    }
+}
+
+pub type Result<T> = core::result::Result<T, Error>;
+
+/// Quantization parameters
+#[derive(Debug, Clone, Copy, Default)]
+pub struct QuantParams {
+    pub scale: i32,
+    pub zero_point: i8,
+}
+
+/// Prelude for common imports
+pub mod prelude {
+    pub use crate::{
+        Error, Result, Esp32Variant, QuantParams,
+        // Optimizations
+        BinaryVector, ProductQuantizer, MicroLoRA, SparseAttention, LayerPruner,
+        // Federation
+        PipelineNode, FederationMessage, SpeculativeDecoder, ChipId,
+        // RuVector
+        MicroHNSW, SemanticMemory, MicroRAG, AnomalyDetector, MicroVector,
+    };
+}

examples/ruvLLM/esp32-flash/src/main.rs

@@ -0,0 +1,778 @@
+//! RuvLLM ESP32 - Complete Flashable Implementation
+//!
+//! Full-featured LLM inference engine for ESP32 with:
+//! - INT8/Binary quantized transformer inference
+//! - Product quantization (8-32x compression)
+//! - MicroLoRA on-device adaptation
+//! - Sparse attention patterns
+//! - HNSW vector search (1000+ vectors)
+//! - Semantic memory with context
+//! - RAG (Retrieval-Augmented Generation)
+//! - Anomaly detection
+//! - Multi-chip federation
+//! - Pipeline/tensor parallelism
+//! - Speculative decoding
+//!
+//! Flash with: espflash flash --monitor --port COM6
+
+#[cfg(feature = "esp32")]
+use esp_idf_svc::hal::prelude::*;
+#[cfg(feature = "esp32")]
+use esp_idf_svc::hal::uart::{self, UartDriver};
+#[cfg(feature = "esp32")]
+use esp_idf_svc::hal::gpio;
+#[cfg(feature = "esp32")]
+use esp_idf_svc::sys::link_patches;
+
+use heapless::Vec as HVec;
+use heapless::String as HString;
+use log::*;
+
+// Import library modules
+use ruvllm_esp32::prelude::*;
+use ruvllm_esp32::{
+    HNSWConfig, RAGConfig, MemoryType, DraftVerifyConfig,
+    PipelineConfig, PipelineRole, AnomalyConfig, PQConfig, LoRAConfig, PruningConfig,
+    AttentionPattern, DistanceMetric, euclidean_distance_i8,
+};
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const VOCAB_SIZE: usize = 256;
+const EMBED_DIM: usize = 64;
+const NUM_LAYERS: usize = 2;
+const NUM_HEADS: usize = 4;
+const MAX_SEQ_LEN: usize = 32;
+const MAX_KNOWLEDGE: usize = 64;
+const HNSW_CAPACITY: usize = 256;
+
+// ============================================================================
+// QUANTIZED TYPES
+// ============================================================================
+
+#[derive(Clone)]
+struct QuantizedWeights {
+    data: HVec<i8, 4096>,
+    scale: i32,
+    zero_point: i8,
+}
+
+impl QuantizedWeights {
+    fn new(size: usize) -> Self {
+        let mut data = HVec::new();
+        for i in 0..size.min(4096) {
+            let val = ((i * 17 + 31) % 256) as i8 - 64;
+            let _ = data.push(val);
+        }
+        Self { data, scale: 128, zero_point: 0 }
+    }
+}
+
+// ============================================================================
+// EMBEDDING TABLE
+// ============================================================================
+
+struct EmbeddingTable {
+    embeddings: [[i8; EMBED_DIM]; VOCAB_SIZE],
+}
+
+impl EmbeddingTable {
+    fn new() -> Self {
+        let mut embeddings = [[0i8; EMBED_DIM]; VOCAB_SIZE];
+        for (token, embed) in embeddings.iter_mut().enumerate() {
+            for (i, val) in embed.iter_mut().enumerate() {
+                *val = (((token * 31 + i * 17) % 256) as i8).wrapping_sub(64);
+            }
+        }
+        Self { embeddings }
+    }
+
+    fn lookup(&self, token: u16) -> &[i8; EMBED_DIM] {
+        &self.embeddings[(token as usize) % VOCAB_SIZE]
+    }
+}
+
+// ============================================================================
+// ATTENTION WITH SPARSE PATTERNS
+// ============================================================================
+
+struct MicroAttention {
+    wq: QuantizedWeights,
+    wk: QuantizedWeights,
+    wv: QuantizedWeights,
+    wo: QuantizedWeights,
+    sparse: SparseAttention,
+    head_dim: usize,
+}
+
+impl MicroAttention {
+    fn new(pattern: AttentionPattern) -> Self {
+        let head_dim = EMBED_DIM / NUM_HEADS;
+        Self {
+            wq: QuantizedWeights::new(EMBED_DIM * EMBED_DIM),
+            wk: QuantizedWeights::new(EMBED_DIM * EMBED_DIM),
+            wv: QuantizedWeights::new(EMBED_DIM * EMBED_DIM),
+            wo: QuantizedWeights::new(EMBED_DIM * EMBED_DIM),
+            sparse: SparseAttention::new(pattern, MAX_SEQ_LEN, 8),
+            head_dim,
+        }
+    }
+
+    fn forward(&self, input: &[i8], output: &mut [i8], seq_pos: usize) {
+        // Get sparse mask for current position
+        let mask = self.sparse.get_mask(seq_pos);
+
+        for (i, val) in input.iter().enumerate() {
+            if i < output.len() {
+                let w_idx = i % self.wq.data.len();
+                // Apply sparse attention - only attend to allowed positions
+                let attended = if i < mask.len() && mask[i] {
+                    (*val as i32 * self.wq.data[w_idx] as i32) >> 7
+                } else {
+                    0
+                };
+                output[i] = attended.clamp(-127, 127) as i8;
+            }
+        }
+    }
+}
+
+// ============================================================================
+// FEED-FORWARD WITH PRUNING
+// ============================================================================
+
+struct FeedForward {
+    w1: QuantizedWeights,
+    w2: QuantizedWeights,
+    pruner: LayerPruner,
+}
+
+impl FeedForward {
+    fn new(config: PruningConfig) -> Self {
+        Self {
+            w1: QuantizedWeights::new(EMBED_DIM * 4 * EMBED_DIM),
+            w2: QuantizedWeights::new(4 * EMBED_DIM * EMBED_DIM),
+            pruner: LayerPruner::new(config),
+        }
+    }
+
+    fn forward(&self, input: &[i8], output: &mut [i8]) {
+        for (i, val) in input.iter().enumerate() {
+            if i < output.len() {
+                let w_idx = i % self.w1.data.len();
+                // Check if weight is pruned
+                let weight = if !self.pruner.is_pruned(w_idx) {
+                    self.w1.data[w_idx] as i32
+                } else {
+                    0
+                };
+                let hidden = (*val as i32 * weight) >> 7;
+                let activated = hidden.max(0);
+                output[i] = activated.clamp(-127, 127) as i8;
+            }
+        }
+    }
+}
+
+// ============================================================================
+// TRANSFORMER LAYER WITH LORA
+// ============================================================================
+
+struct TransformerLayer {
+    attention: MicroAttention,
+    ffn: FeedForward,
+    lora: Option<MicroLoRA>,
+}
+
+impl TransformerLayer {
+    fn new(lora_config: Option<LoRAConfig>) -> Self {
+        let attn_pattern = AttentionPattern::SlidingWindow { window_size: 8 };
+        let prune_config = PruningConfig::default();
+
+        Self {
+            attention: MicroAttention::new(attn_pattern),
+            ffn: FeedForward::new(prune_config),
+            lora: lora_config.map(|c| MicroLoRA::new(c)),
+        }
+    }
+
+    fn forward(&self, input: &[i8], output: &mut [i8], seq_pos: usize) {
+        let mut attn_out = [0i8; EMBED_DIM];
+        self.attention.forward(input, &mut attn_out, seq_pos);
+
+        // Apply LoRA adaptation if enabled
+        if let Some(ref lora) = self.lora {
+            let adapted = lora.forward(&attn_out);
+            for (i, v) in adapted.iter().enumerate().take(EMBED_DIM) {
+                attn_out[i] = attn_out[i].saturating_add(*v);
+            }
+        }
+
+        // Residual connection
+        for i in 0..EMBED_DIM {
+            attn_out[i] = attn_out[i].saturating_add(input[i] / 2);
+        }
+
+        self.ffn.forward(&attn_out, output);
+
+        // Residual connection
+        for i in 0..EMBED_DIM {
+            output[i] = output[i].saturating_add(attn_out[i] / 2);
+        }
+    }
+}
+
+// ============================================================================
+// TINY MODEL WITH FULL FEATURES
+// ============================================================================
+
+struct TinyModel {
+    embeddings: EmbeddingTable,
+    layers: [TransformerLayer; NUM_LAYERS],
+    lm_head: QuantizedWeights,
+    binary_embed: Option<BinaryVector>,
+    pq: Option<ProductQuantizer>,
+}
+
+impl TinyModel {
+    fn new(use_lora: bool, use_pq: bool) -> Self {
+        let lora_config = if use_lora {
+            Some(LoRAConfig { rank: 2, alpha: 4, input_dim: EMBED_DIM, output_dim: EMBED_DIM })
+        } else {
+            None
+        };
+
+        let pq = if use_pq {
+            Some(ProductQuantizer::new(PQConfig {
+                dim: EMBED_DIM,
+                num_subspaces: 8,
+                num_centroids: 16,
+            }))
+        } else {
+            None
+        };
+
+        Self {
+            embeddings: EmbeddingTable::new(),
+            layers: [
+                TransformerLayer::new(lora_config.clone()),
+                TransformerLayer::new(lora_config),
+            ],
+            lm_head: QuantizedWeights::new(EMBED_DIM * VOCAB_SIZE),
+            binary_embed: Some(BinaryVector::new()),
+            pq,
+        }
+    }
+
+    fn forward(&self, token: u16, seq_pos: usize) -> u16 {
+        let embed = self.embeddings.lookup(token);
+        let mut hidden = *embed;
+
+        // Pass through layers
+        for layer in &self.layers {
+            let mut output = [0i8; EMBED_DIM];
+            layer.forward(&hidden, &mut output, seq_pos);
+            hidden = output;
+        }
+
+        // Project to vocabulary
+        let mut max_logit = i32::MIN;
+        let mut max_token = 0u16;
+
+        for t in 0..VOCAB_SIZE {
+            let mut logit = 0i32;
+            for i in 0..EMBED_DIM {
+                let w_idx = t * EMBED_DIM + i;
+                if w_idx < self.lm_head.data.len() {
+                    logit += hidden[i] as i32 * self.lm_head.data[w_idx] as i32;
+                }
+            }
+            if logit > max_logit {
+                max_logit = logit;
+                max_token = t as u16;
+            }
+        }
+
+        max_token
+    }
+}
+
+// ============================================================================
+// FULL INFERENCE ENGINE
+// ============================================================================
+
+struct MicroEngine {
+    model: TinyModel,
+    hnsw: MicroHNSW<EMBED_DIM, HNSW_CAPACITY>,
+    rag: MicroRAG<EMBED_DIM, MAX_KNOWLEDGE>,
+    memory: SemanticMemory<EMBED_DIM, 32>,
+    anomaly: AnomalyDetector,
+    speculative: Option<SpeculativeDecoder>,
+    tokens_generated: u32,
+    variant: Esp32Variant,
+}
+
+impl MicroEngine {
+    fn new(variant: Esp32Variant, enable_speculative: bool) -> Self {
+        info!("Initializing MicroEngine for {:?}...", variant);
+        info!("  Available SRAM: {} KB", variant.sram_bytes() / 1024);
+        info!("  Max model RAM: {} KB", variant.max_model_ram() / 1024);
+
+        let use_lora = variant.sram_bytes() >= 400 * 1024;
+        let use_pq = variant.sram_bytes() >= 320 * 1024;
+
+        let hnsw_config = HNSWConfig {
+            m: if variant.has_simd() { 8 } else { 4 },
+            m_max0: if variant.has_simd() { 16 } else { 8 },
+            ef_construction: 32,
+            ef_search: 16,
+            metric: DistanceMetric::Euclidean,
+            binary_mode: !variant.has_fpu(),
+        };
+
+        let rag_config = RAGConfig::default();
+        let anomaly_config = AnomalyConfig::default();
+
+        let speculative = if enable_speculative && variant.sram_bytes() >= 512 * 1024 {
+            Some(SpeculativeDecoder::new(DraftVerifyConfig {
+                draft_length: 4,
+                max_rejections: 2,
+                temperature: 100,
+                verify_all: false,
+            }))
+        } else {
+            None
+        };
+
+        Self {
+            model: TinyModel::new(use_lora, use_pq),
+            hnsw: MicroHNSW::new(hnsw_config),
+            rag: MicroRAG::new(rag_config),
+            memory: SemanticMemory::new(),
+            anomaly: AnomalyDetector::new(anomaly_config),
+            speculative,
+            tokens_generated: 0,
+            variant,
+        }
+    }
+
+    fn generate(&mut self, input: &[u16], max_tokens: usize) -> HVec<u16, 64> {
+        let mut output = HVec::new();
+        let mut current = *input.last().unwrap_or(&1);
+        let mut seq_pos = input.len();
+
+        if let Some(ref mut spec) = self.speculative {
+            // Speculative decoding: generate drafts and verify
+            while output.len() < max_tokens {
+                // Draft phase
+                let mut drafts = HVec::<u16, 8>::new();
+                for _ in 0..4 {
+                    let next = self.model.forward(current, seq_pos);
+                    let _ = drafts.push(next);
+                    current = next;
+                    seq_pos += 1;
+                }
+
+                // Verify phase (simplified)
+                for &token in drafts.iter() {
+                    if output.len() < max_tokens {
+                        let _ = output.push(token);
+                        self.tokens_generated += 1;
+                    }
+                    if token == 0 { return output; }
+                }
+            }
+        } else {
+            // Standard decoding
+            for _ in 0..max_tokens {
+                let next = self.model.forward(current, seq_pos);
+                let _ = output.push(next);
+                self.tokens_generated += 1;
+                current = next;
+                seq_pos += 1;
+                if next == 0 { break; }
+            }
+        }
+
+        output
+    }
+
+    fn add_knowledge(&mut self, text: &str) -> Result<u32, &'static str> {
+        let embedding = embed_text(text);
+
+        // Add to HNSW index
+        let mut vec_data = HVec::new();
+        for &v in embedding.iter() {
+            let _ = vec_data.push(v);
+        }
+        let vec = MicroVector { data: vec_data, id: self.hnsw.len() as u32 };
+        self.hnsw.insert(&vec)?;
+
+        // Add to RAG
+        self.rag.add_knowledge(text, &embedding)?;
+
+        // Add to semantic memory
+        self.memory.add_memory(&embedding, &[], MemoryType::Factual)?;
+
+        Ok(vec.id)
+    }
+
+    fn query_rag(&self, query: &str, k: usize) -> HVec<HString<64>, 4> {
+        let embedding = embed_text(query);
+
+        // Search HNSW
+        let results = self.hnsw.search(&embedding, k);
+
+        // Also query RAG
+        let rag_results = self.rag.retrieve(&embedding, k);
+
+        let mut texts = HVec::new();
+        for result in rag_results.iter().take(k) {
+            let mut s = HString::new();
+            for c in result.content.iter() {
+                let _ = s.push(*c);
+            }
+            let _ = texts.push(s);
+        }
+        texts
+    }
+
+    fn check_anomaly(&mut self, text: &str) -> AnomalyResult {
+        let embedding = embed_text(text);
+        self.anomaly.check(&embedding)
+    }
+
+    fn stats(&self) -> EngineStats {
+        EngineStats {
+            tokens_generated: self.tokens_generated,
+            knowledge_entries: self.rag.len(),
+            hnsw_vectors: self.hnsw.len(),
+            memory_entries: self.memory.len(),
+            variant: self.variant,
+            has_speculative: self.speculative.is_some(),
+        }
+    }
+}
+
+#[derive(Debug)]
+struct EngineStats {
+    tokens_generated: u32,
+    knowledge_entries: usize,
+    hnsw_vectors: usize,
+    memory_entries: usize,
+    variant: Esp32Variant,
+    has_speculative: bool,
+}
+
+// ============================================================================
+// TEXT EMBEDDING
+// ============================================================================
+
+fn embed_text(text: &str) -> [i8; EMBED_DIM] {
+    let mut embedding = [0i8; EMBED_DIM];
+
+    for (i, byte) in text.bytes().enumerate() {
+        let idx = i % EMBED_DIM;
+        embedding[idx] = embedding[idx].saturating_add(
+            ((byte as i32 * 31 + i as i32 * 17) % 256 - 128) as i8 / 4
+        );
+    }
+
+    // Normalize
+    let mut max_val = 1i8;
+    for v in &embedding {
+        max_val = max_val.max(v.abs());
+    }
+    if max_val > 1 {
+        for v in &mut embedding {
+            *v = (*v as i32 * 64 / max_val as i32) as i8;
+        }
+    }
+
+    embedding
+}
+
+// ============================================================================
+// UART COMMAND PARSER
+// ============================================================================
+
+fn process_command(cmd: &str, engine: &mut MicroEngine) -> HString<512> {
+    let mut response = HString::new();
+    let cmd = cmd.trim();
+
+    if cmd.starts_with("gen ") {
+        let prompt = &cmd[4..];
+        let tokens: HVec<u16, 8> = prompt.bytes().take(8).map(|b| b as u16).collect();
+        let output = engine.generate(&tokens, 10);
+
+        let _ = response.push_str("Generated: ");
+        for (i, t) in output.iter().enumerate() {
+            if i > 0 { let _ = response.push_str(", "); }
+            let c = (*t as u8) as char;
+            if c.is_ascii_alphanumeric() || c == ' ' {
+                let _ = response.push(c);
+            } else {
+                let _ = response.push('?');
+            }
+        }
+    } else if cmd.starts_with("add ") {
+        let knowledge = &cmd[4..];
+        match engine.add_knowledge(knowledge) {
+            Ok(id) => {
+                let _ = response.push_str("Added knowledge #");
+                let _ = response.push_str(&format_u32(id));
+            }
+            Err(e) => {
+                let _ = response.push_str("Error: ");
+                let _ = response.push_str(e);
+            }
+        }
+    } else if cmd.starts_with("ask ") {
+        let query = &cmd[4..];
+        let results = engine.query_rag(query, 2);
+
+        if results.is_empty() {
+            let _ = response.push_str("No results found");
+        } else {
+            let _ = response.push_str("Found: ");
+            for (i, text) in results.iter().enumerate() {
+                if i > 0 { let _ = response.push_str(" | "); }
+                let _ = response.push_str(text.as_str());
+            }
+        }
+    } else if cmd.starts_with("anomaly ") {
+        let text = &cmd[8..];
+        let result = engine.check_anomaly(text);
+        let _ = response.push_str(if result.is_anomaly { "ANOMALY" } else { "NORMAL" });
+        let _ = response.push_str(" (score: ");
+        let _ = response.push_str(&format_i32(result.score));
+        let _ = response.push_str(", threshold: ");
+        let _ = response.push_str(&format_i32(result.threshold));
+        let _ = response.push_str(")");
+    } else if cmd == "stats" {
+        let stats = engine.stats();
+        let _ = response.push_str("Tokens: ");
+        let _ = response.push_str(&format_u32(stats.tokens_generated));
+        let _ = response.push_str(", Knowledge: ");
+        let _ = response.push_str(&format_u32(stats.knowledge_entries as u32));
+        let _ = response.push_str(", HNSW: ");
+        let _ = response.push_str(&format_u32(stats.hnsw_vectors as u32));
+        let _ = response.push_str(", Memory: ");
+        let _ = response.push_str(&format_u32(stats.memory_entries as u32));
+        let _ = response.push_str(", Spec: ");
+        let _ = response.push_str(if stats.has_speculative { "yes" } else { "no" });
+    } else if cmd == "features" {
+        let _ = response.push_str("Features:\n");
+        let _ = response.push_str("  - Binary quantization (32x compress)\n");
+        let _ = response.push_str("  - Product quantization (8-32x)\n");
+        let _ = response.push_str("  - MicroLoRA adaptation\n");
+        let _ = response.push_str("  - Sparse attention\n");
+        let _ = response.push_str("  - HNSW vector search\n");
+        let _ = response.push_str("  - Semantic memory\n");
+        let _ = response.push_str("  - RAG retrieval\n");
+        let _ = response.push_str("  - Anomaly detection\n");
+        if engine.speculative.is_some() {
+            let _ = response.push_str("  - Speculative decoding\n");
+        }
+    } else if cmd == "help" {
+        let _ = response.push_str("Commands:\n");
+        let _ = response.push_str("  gen <text>    - Generate tokens\n");
+        let _ = response.push_str("  add <text>    - Add to knowledge base\n");
+        let _ = response.push_str("  ask <query>   - Query knowledge\n");
+        let _ = response.push_str("  anomaly <txt> - Check for anomaly\n");
+        let _ = response.push_str("  stats         - Show statistics\n");
+        let _ = response.push_str("  features      - List features\n");
+        let _ = response.push_str("  help          - This help");
+    } else {
+        let _ = response.push_str("Unknown command. Type 'help'");
+    }
+
+    response
+}
+
+fn format_u32(n: u32) -> HString<16> {
+    let mut s = HString::new();
+    if n == 0 {
+        let _ = s.push('0');
+        return s;
+    }
+
+    let mut digits = [0u8; 10];
+    let mut i = 0;
+    let mut num = n;
+    while num > 0 {
+        digits[i] = (num % 10) as u8;
+        num /= 10;
+        i += 1;
+    }
+
+    while i > 0 {
+        i -= 1;
+        let _ = s.push((b'0' + digits[i]) as char);
+    }
+    s
+}
+
+fn format_i32(n: i32) -> HString<16> {
+    let mut s = HString::new();
+    if n < 0 {
+        let _ = s.push('-');
+        return s;
+    }
+    format_u32(n as u32)
+}
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+#[cfg(feature = "esp32")]
+fn main() -> anyhow::Result<()> {
+    link_patches();
+    esp_idf_svc::log::EspLogger::initialize_default();
+
+    info!("╔══════════════════════════════════════════╗");
+    info!("║  RuvLLM ESP32 - Full Feature LLM v0.2    ║");
+    info!("╚══════════════════════════════════════════╝");
+
+    // Detect ESP32 variant (default to ESP32-S3 for demo)
+    let variant = Esp32Variant::Esp32S3;
+    info!("Detected: {:?} ({} KB SRAM)", variant, variant.sram_bytes() / 1024);
+
+    let peripherals = Peripherals::take()?;
+    let tx = peripherals.pins.gpio1;
+    let rx = peripherals.pins.gpio3;
+
+    let config = uart::config::Config::default()
+        .baudrate(Hertz(115200));
+
+    let uart = UartDriver::new(
+        peripherals.uart0,
+        tx,
+        rx,
+        Option::<gpio::Gpio0>::None,
+        Option::<gpio::Gpio0>::None,
+        &config
+    )?;
+
+    info!("UART initialized at 115200 baud");
+
+    // Initialize full-featured engine
+    let enable_speculative = variant.sram_bytes() >= 512 * 1024;
+    let mut engine = MicroEngine::new(variant, enable_speculative);
+    info!("Engine ready with all features");
+
+    // Pre-load knowledge
+    let default_knowledge = [
+        "The ESP32-S3 has 512KB SRAM and vector instructions",
+        "RuvLLM uses INT8 and binary quantization for efficiency",
+        "HNSW provides fast approximate nearest neighbor search",
+        "MicroLoRA enables on-device model adaptation",
+        "Speculative decoding achieves 2-4x speedup",
+        "RAG combines retrieval with generation",
+    ];
+
+    for knowledge in &default_knowledge {
+        let _ = engine.add_knowledge(knowledge);
+    }
+    info!("Loaded {} default knowledge entries", engine.stats().knowledge_entries);
+
+    let startup = "\r\n\
+        ════════════════════════════════════════════\r\n\
+        RuvLLM ESP32 Full-Feature v0.2\r\n\
+        ════════════════════════════════════════════\r\n\
+        Features: Binary Quant, PQ, LoRA, HNSW, RAG\r\n\
+                  Semantic Memory, Anomaly Detection\r\n\
+                  Speculative Decoding, Federation\r\n\
+        ════════════════════════════════════════════\r\n\
+        Type 'help' for commands\r\n\
+        > ";
+    uart.write(startup.as_bytes())?;
+
+    let mut cmd_buffer: HVec<u8, 256> = HVec::new();
+
+    loop {
+        let mut byte = [0u8; 1];
+
+        if uart.read(&mut byte, 10).is_ok() && byte[0] != 0 {
+            let c = byte[0];
+
+            if c == b'\r' || c == b'\n' {
+                if !cmd_buffer.is_empty() {
+                    let cmd_str: HString<256> = cmd_buffer.iter()
+                        .map(|&b| b as char)
+                        .collect();
+
+                    uart.write(b"\r\n")?;
+
+                    let response = process_command(cmd_str.as_str(), &mut engine);
+                    uart.write(response.as_bytes())?;
+                    uart.write(b"\r\n> ")?;
+
+                    cmd_buffer.clear();
+                }
+            } else if c == 127 || c == 8 {
+                if !cmd_buffer.is_empty() {
+                    cmd_buffer.pop();
+                    uart.write(b"\x08 \x08")?;
+                }
+            } else if c >= 32 && c < 127 {
+                if cmd_buffer.len() < 255 {
+                    let _ = cmd_buffer.push(c);
+                    uart.write(&[c])?;
+                }
+            }
+        }
+    }
+}
+
+// Host testing main (for development)
+#[cfg(all(not(feature = "esp32"), feature = "host-test"))]
+fn main() {
+    println!("RuvLLM ESP32 Host Test Mode");
+    println!("This is for development testing only.");
+
+    let variant = Esp32Variant::Esp32S3;
+    println!("Simulating: {:?} ({} KB SRAM)", variant, variant.sram_bytes() / 1024);
+
+    let mut engine = MicroEngine::new(variant, true);
+
+    // Add some knowledge
+    let _ = engine.add_knowledge("Test knowledge entry 1");
+    let _ = engine.add_knowledge("Another test entry");
+
+    // Generate tokens
+    let tokens: HVec<u16, 8> = [b'H' as u16, b'e' as u16, b'l' as u16, b'l' as u16, b'o' as u16]
+        .iter().copied().collect();
+    let output = engine.generate(&tokens, 5);
+
+    println!("Generated {} tokens", output.len());
+    println!("Stats: {:?}", engine.stats());
+}
+
+// WASM entry point
+#[cfg(feature = "wasm")]
+use wasm_bindgen::prelude::*;
+
+#[cfg(feature = "wasm")]
+#[wasm_bindgen]
+pub fn wasm_init() -> String {
+    "RuvLLM ESP32 WASM Module Initialized".to_string()
+}
+
+#[cfg(feature = "wasm")]
+#[wasm_bindgen]
+pub fn wasm_generate(prompt: &str) -> String {
+    format!("Generated from: {}", prompt)
+}
+
+// Default main for other builds
+#[cfg(all(not(feature = "esp32"), not(feature = "host-test"), not(feature = "wasm")))]
+fn main() {
+    println!("RuvLLM ESP32 Flash");
+    println!("Build with --features esp32 for ESP32 target");
+    println!("Build with --features host-test for development");
+    println!("Build with --features wasm for WebAssembly");
+}

examples/ruvLLM/esp32-flash/src/models/mod.rs

@@ -0,0 +1,238 @@
+//! Model Zoo - Pre-quantized Models for RuvLLM ESP32
+//!
+//! Ready-to-use language models optimized for ESP32 microcontrollers.
+//!
+//! # Available Models
+//!
+//! | Model | Size | RAM | Tokens/sec | Use Case |
+//! |-------|------|-----|------------|----------|
+//! | TinyStories | 8KB | 20KB | ~50 | Story generation |
+//! | MicroChat | 16KB | 32KB | ~30 | Simple chatbot |
+//! | NanoEmbed | 4KB | 8KB | ~100 | Embeddings only |
+//! | TinyQA | 12KB | 24KB | ~40 | Question answering |
+
+use heapless::Vec;
+
+/// Model metadata
+#[derive(Clone)]
+pub struct ModelInfo {
+    /// Model name
+    pub name: &'static str,
+    /// Model version
+    pub version: &'static str,
+    /// Model size in bytes
+    pub size_bytes: u32,
+    /// Required RAM in bytes
+    pub ram_bytes: u32,
+    /// Vocabulary size
+    pub vocab_size: u16,
+    /// Hidden dimension
+    pub hidden_dim: u16,
+    /// Number of layers
+    pub num_layers: u8,
+    /// Number of attention heads
+    pub num_heads: u8,
+    /// Maximum sequence length
+    pub max_seq_len: u16,
+    /// Quantization bits (8 = INT8, 4 = INT4, 1 = binary)
+    pub quant_bits: u8,
+    /// Description
+    pub description: &'static str,
+}
+
+/// Available pre-quantized models
+pub const MODELS: &[ModelInfo] = &[
+    ModelInfo {
+        name: "tinystories-1m",
+        version: "1.0.0",
+        size_bytes: 8 * 1024,      // 8KB
+        ram_bytes: 20 * 1024,      // 20KB
+        vocab_size: 256,
+        hidden_dim: 64,
+        num_layers: 2,
+        num_heads: 2,
+        max_seq_len: 64,
+        quant_bits: 8,
+        description: "Tiny model for simple story generation",
+    },
+    ModelInfo {
+        name: "microchat-2m",
+        version: "1.0.0",
+        size_bytes: 16 * 1024,     // 16KB
+        ram_bytes: 32 * 1024,      // 32KB
+        vocab_size: 512,
+        hidden_dim: 96,
+        num_layers: 3,
+        num_heads: 3,
+        max_seq_len: 128,
+        quant_bits: 8,
+        description: "Simple chatbot for basic conversations",
+    },
+    ModelInfo {
+        name: "nanoembed-500k",
+        version: "1.0.0",
+        size_bytes: 4 * 1024,      // 4KB
+        ram_bytes: 8 * 1024,       // 8KB
+        vocab_size: 256,
+        hidden_dim: 32,
+        num_layers: 1,
+        num_heads: 1,
+        max_seq_len: 32,
+        quant_bits: 8,
+        description: "Ultra-light embedding model for semantic search",
+    },
+    ModelInfo {
+        name: "tinyqa-1.5m",
+        version: "1.0.0",
+        size_bytes: 12 * 1024,     // 12KB
+        ram_bytes: 24 * 1024,      // 24KB
+        vocab_size: 384,
+        hidden_dim: 80,
+        num_layers: 2,
+        num_heads: 2,
+        max_seq_len: 96,
+        quant_bits: 8,
+        description: "Question-answering model for simple queries",
+    },
+    ModelInfo {
+        name: "binary-embed-250k",
+        version: "1.0.0",
+        size_bytes: 2 * 1024,      // 2KB
+        ram_bytes: 4 * 1024,       // 4KB
+        vocab_size: 128,
+        hidden_dim: 64,
+        num_layers: 1,
+        num_heads: 1,
+        max_seq_len: 16,
+        quant_bits: 1,             // Binary quantization
+        description: "Binary quantized embeddings (32x compression)",
+    },
+];
+
+/// Model selection by use case
+#[derive(Debug, Clone, Copy)]
+pub enum UseCase {
+    /// Story/text generation
+    Generation,
+    /// Conversational AI
+    Chat,
+    /// Semantic embeddings
+    Embedding,
+    /// Question answering
+    QA,
+    /// Minimum memory footprint
+    MinMemory,
+}
+
+/// Get recommended model for use case
+pub fn recommend_model(use_case: UseCase, max_ram_kb: u32) -> Option<&'static ModelInfo> {
+    let max_ram = max_ram_kb * 1024;
+
+    let candidates: Vec<&ModelInfo, 8> = MODELS
+        .iter()
+        .filter(|m| m.ram_bytes <= max_ram)
+        .collect();
+
+    match use_case {
+        UseCase::Generation => candidates
+            .iter()
+            .find(|m| m.name.contains("stories"))
+            .copied(),
+        UseCase::Chat => candidates
+            .iter()
+            .find(|m| m.name.contains("chat"))
+            .copied(),
+        UseCase::Embedding => candidates
+            .iter()
+            .find(|m| m.name.contains("embed"))
+            .copied(),
+        UseCase::QA => candidates
+            .iter()
+            .find(|m| m.name.contains("qa"))
+            .copied(),
+        UseCase::MinMemory => candidates
+            .iter()
+            .min_by_key(|m| m.ram_bytes)
+            .copied(),
+    }
+}
+
+/// Get model by name
+pub fn get_model(name: &str) -> Option<&'static ModelInfo> {
+    MODELS.iter().find(|m| m.name == name)
+}
+
+/// List all models
+pub fn list_models() -> &'static [ModelInfo] {
+    MODELS
+}
+
+/// Calculate tokens per second estimate for model on given chip
+pub fn estimate_performance(model: &ModelInfo, chip: &str) -> u32 {
+    let base_speed = match chip {
+        "esp32s3" => 60,  // SIMD acceleration
+        "esp32" => 40,
+        "esp32s2" => 35,
+        "esp32c3" => 30,
+        "esp32c6" => 35,
+        _ => 30,
+    };
+
+    // Adjust for model complexity
+    let complexity_factor = 1.0 / (model.num_layers as f32 * 0.3 + 1.0);
+    let quant_factor = if model.quant_bits == 1 { 2.0 } else { 1.0 };
+
+    (base_speed as f32 * complexity_factor * quant_factor) as u32
+}
+
+/// Print model info table
+pub fn print_model_table() -> heapless::String<1024> {
+    let mut output = heapless::String::new();
+
+    let _ = output.push_str("Available Models:\n");
+    let _ = output.push_str("─────────────────────────────────────────────────\n");
+    let _ = output.push_str("Name              Size    RAM     Quant  Use Case\n");
+    let _ = output.push_str("─────────────────────────────────────────────────\n");
+
+    for model in MODELS {
+        let _ = core::fmt::write(
+            &mut output,
+            format_args!(
+                "{:<17} {:>4}KB  {:>4}KB  INT{:<2}  {}\n",
+                model.name,
+                model.size_bytes / 1024,
+                model.ram_bytes / 1024,
+                model.quant_bits,
+                model.description.chars().take(20).collect::<heapless::String<20>>()
+            )
+        );
+    }
+
+    output
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_model_lookup() {
+        let model = get_model("tinystories-1m");
+        assert!(model.is_some());
+        assert_eq!(model.unwrap().vocab_size, 256);
+    }
+
+    #[test]
+    fn test_recommend_model() {
+        let model = recommend_model(UseCase::MinMemory, 10);
+        assert!(model.is_some());
+        assert_eq!(model.unwrap().name, "binary-embed-250k");
+    }
+
+    #[test]
+    fn test_performance_estimate() {
+        let model = get_model("nanoembed-500k").unwrap();
+        let speed = estimate_performance(model, "esp32s3");
+        assert!(speed > 0);
+    }
+}

examples/ruvLLM/esp32-flash/src/optimizations/binary_quant.rs

@@ -0,0 +1,130 @@
+//! Binary Quantization - 32x Memory Compression
+
+use heapless::Vec as HVec;
+
+pub const MAX_BINARY_SIZE: usize = 64;
+
+/// Binary quantized vector - 1 bit per dimension
+#[derive(Debug, Clone)]
+pub struct BinaryVector<const N: usize> {
+    pub data: HVec<u8, N>,
+    pub dim: usize,
+    pub threshold: i8,
+}
+
+impl<const N: usize> BinaryVector<N> {
+    pub fn from_i8(values: &[i8], threshold: i8) -> crate::Result<Self> {
+        let dim = values.len();
+        let num_bytes = (dim + 7) / 8;
+        if num_bytes > N {
+            return Err(crate::Error::BufferOverflow);
+        }
+
+        let mut data = HVec::new();
+        for chunk_idx in 0..num_bytes {
+            let mut byte = 0u8;
+            for bit_idx in 0..8 {
+                let val_idx = chunk_idx * 8 + bit_idx;
+                if val_idx < dim && values[val_idx] >= threshold {
+                    byte |= 1 << bit_idx;
+                }
+            }
+            data.push(byte).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+
+        Ok(Self { data, dim, threshold })
+    }
+
+    pub fn num_bytes(&self) -> usize { self.data.len() }
+    pub fn compression_ratio(&self) -> f32 { self.dim as f32 / self.data.len() as f32 }
+}
+
+/// Binary embedding table (32x smaller than INT8)
+pub struct BinaryEmbedding<const VOCAB: usize, const DIM_BYTES: usize> {
+    data: HVec<u8, { 32 * 1024 }>,
+    vocab_size: usize,
+    dim: usize,
+    bytes_per_embed: usize,
+}
+
+impl<const VOCAB: usize, const DIM_BYTES: usize> BinaryEmbedding<VOCAB, DIM_BYTES> {
+    pub fn random(vocab_size: usize, dim: usize, seed: u32) -> crate::Result<Self> {
+        let bytes_per_embed = (dim + 7) / 8;
+        let total_bytes = vocab_size * bytes_per_embed;
+
+        let mut data = HVec::new();
+        let mut rng_state = seed;
+
+        for _ in 0..total_bytes {
+            rng_state = rng_state.wrapping_mul(1103515245).wrapping_add(12345);
+            let byte = ((rng_state >> 16) & 0xFF) as u8;
+            data.push(byte).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+
+        Ok(Self { data, vocab_size, dim, bytes_per_embed })
+    }
+
+    pub fn lookup(&self, token_id: u16, output: &mut [u8]) -> crate::Result<()> {
+        let id = token_id as usize;
+        if id >= self.vocab_size {
+            return Err(crate::Error::InvalidModel("Token ID out of range"));
+        }
+        let start = id * self.bytes_per_embed;
+        let end = start + self.bytes_per_embed;
+        if output.len() < self.bytes_per_embed {
+            return Err(crate::Error::BufferOverflow);
+        }
+        output[..self.bytes_per_embed].copy_from_slice(&self.data[start..end]);
+        Ok(())
+    }
+
+    pub fn memory_size(&self) -> usize { self.data.len() }
+}
+
+/// Hamming distance between binary vectors (POPCNT)
+#[inline]
+pub fn hamming_distance(a: &[u8], b: &[u8]) -> u32 {
+    let mut distance: u32 = 0;
+    let chunks = a.len() / 4;
+    for i in 0..chunks {
+        let idx = i * 4;
+        distance += popcount8(a[idx] ^ b[idx]) + popcount8(a[idx + 1] ^ b[idx + 1])
+                  + popcount8(a[idx + 2] ^ b[idx + 2]) + popcount8(a[idx + 3] ^ b[idx + 3]);
+    }
+    for i in (chunks * 4)..a.len() {
+        distance += popcount8(a[i] ^ b[i]);
+    }
+    distance
+}
+
+#[inline]
+pub fn hamming_similarity(a: &[u8], b: &[u8]) -> f32 {
+    let total_bits = (a.len() * 8) as f32;
+    1.0 - (hamming_distance(a, b) as f32 / total_bits)
+}
+
+#[inline]
+pub fn popcount8(x: u8) -> u32 {
+    const TABLE: [u8; 256] = [
+        0,1,1,2,1,2,2,3,1,2,2,3,2,3,3,4,1,2,2,3,2,3,3,4,2,3,3,4,3,4,4,5,
+        1,2,2,3,2,3,3,4,2,3,3,4,3,4,4,5,2,3,3,4,3,4,4,5,3,4,4,5,4,5,5,6,
+        1,2,2,3,2,3,3,4,2,3,3,4,3,4,4,5,2,3,3,4,3,4,4,5,3,4,4,5,4,5,5,6,
+        2,3,3,4,3,4,4,5,3,4,4,5,4,5,5,6,3,4,4,5,4,5,5,6,4,5,5,6,5,6,6,7,
+        1,2,2,3,2,3,3,4,2,3,3,4,3,4,4,5,2,3,3,4,3,4,4,5,3,4,4,5,4,5,5,6,
+        2,3,3,4,3,4,4,5,3,4,4,5,4,5,5,6,3,4,4,5,4,5,5,6,4,5,5,6,5,6,6,7,
+        2,3,3,4,3,4,4,5,3,4,4,5,4,5,5,6,3,4,4,5,4,5,5,6,4,5,5,6,5,6,6,7,
+        3,4,4,5,4,5,5,6,4,5,5,6,5,6,6,7,4,5,5,6,5,6,6,7,5,6,6,7,6,7,7,8,
+    ];
+    TABLE[x as usize] as u32
+}
+
+/// XNOR-popcount for binary neural network inference
+#[inline]
+pub fn xnor_popcount(a: &[u8], b: &[u8]) -> i32 {
+    let total_bits = (a.len() * 8) as i32;
+    let mut matching: i32 = 0;
+    for (&x, &y) in a.iter().zip(b.iter()) {
+        matching += popcount8(!(x ^ y)) as i32;
+    }
+    2 * matching - total_bits
+}

examples/ruvLLM/esp32-flash/src/optimizations/lookup_tables.rs

@@ -0,0 +1,124 @@
+//! Lookup Tables for Fast Fixed-Point Operations
+
+/// Softmax lookup table
+pub struct SoftmaxLUT {
+    exp_table: [u8; 256],
+    pub input_scale: i32,
+}
+
+impl SoftmaxLUT {
+    pub const fn new() -> Self {
+        let mut exp_table = [0u8; 256];
+        let mut i = 0;
+        while i < 256 {
+            let x_scaled = i as i32 - 255;
+            let mut exp_approx = 255 + x_scaled;
+            if exp_approx < 1 { exp_approx = 1; }
+            if exp_approx > 255 { exp_approx = 255; }
+            exp_table[i] = exp_approx as u8;
+            i += 1;
+        }
+        Self { exp_table, input_scale: 32 }
+    }
+
+    #[inline]
+    pub fn exp(&self, x: i32) -> u8 {
+        let x_clamped = x.max(-255).min(0);
+        self.exp_table[(x_clamped + 255) as usize]
+    }
+
+    pub fn softmax(&self, logits: &[i32], output: &mut [u16]) {
+        if logits.is_empty() { return; }
+        let max_logit = logits.iter().cloned().max().unwrap_or(0);
+        let mut sum: u32 = 0;
+        for (&logit, out) in logits.iter().zip(output.iter_mut()) {
+            let exp_val = self.exp(logit - max_logit) as u16;
+            *out = exp_val;
+            sum += exp_val as u32;
+        }
+        if sum > 0 {
+            for out in output.iter_mut() {
+                *out = ((*out as u32 * 256) / sum) as u16;
+            }
+        }
+    }
+
+    pub fn softmax_inplace(&self, logits: &mut [i32]) {
+        if logits.is_empty() { return; }
+        let max = logits.iter().cloned().max().unwrap_or(0);
+        let mut sum: i32 = 0;
+        for logit in logits.iter_mut() {
+            let x = (*logit - max).max(-255);
+            *logit = self.exp_table[(x + 255) as usize] as i32;
+            sum += *logit;
+        }
+        if sum > 0 {
+            for logit in logits.iter_mut() {
+                *logit = (*logit << 8) / sum;
+            }
+        }
+    }
+}
+
+impl Default for SoftmaxLUT {
+    fn default() -> Self { Self::new() }
+}
+
+/// Exponential lookup table
+pub struct ExpLUT {
+    table: [u16; 256],
+}
+
+impl ExpLUT {
+    pub const fn new() -> Self {
+        let mut table = [0u16; 256];
+        let mut i = 0;
+        while i < 256 {
+            let x = i as i32;
+            let x_scaled = x * 256 / 64;
+            let x2 = (x_scaled * x_scaled) >> 9;
+            let mut exp_val = 256 + x_scaled + (x2 >> 1);
+            if exp_val > 65535 { exp_val = 65535; }
+            table[i] = exp_val as u16;
+            i += 1;
+        }
+        Self { table }
+    }
+
+    #[inline]
+    pub fn exp(&self, x: u8) -> u16 { self.table[x as usize] }
+}
+
+/// Distance lookup table for L2 distance
+pub struct DistanceLUT<const SIZE: usize> {
+    sq_diff_table: [u16; 512],
+}
+
+impl<const SIZE: usize> DistanceLUT<SIZE> {
+    pub const fn new() -> Self {
+        let mut sq_diff_table = [0u16; 512];
+        let mut i = 0i32;
+        while i < 512 {
+            let diff = i - 256;
+            let mut sq = diff * diff;
+            if sq > 65535 { sq = 65535; }
+            sq_diff_table[i as usize] = sq as u16;
+            i += 1;
+        }
+        Self { sq_diff_table }
+    }
+
+    #[inline]
+    pub fn squared_diff(&self, a: i8, b: i8) -> u16 {
+        let idx = (a as i32 - b as i32 + 256) as usize;
+        self.sq_diff_table[idx]
+    }
+
+    pub fn l2_squared(&self, a: &[i8], b: &[i8]) -> u32 {
+        a.iter().zip(b.iter()).map(|(&x, &y)| self.squared_diff(x, y) as u32).sum()
+    }
+}
+
+pub static SOFTMAX_LUT: SoftmaxLUT = SoftmaxLUT::new();
+pub static EXP_LUT: ExpLUT = ExpLUT::new();
+pub static DISTANCE_LUT: DistanceLUT<256> = DistanceLUT::new();

examples/ruvLLM/esp32-flash/src/optimizations/micro_lora.rs

@@ -0,0 +1,113 @@
+//! MicroLoRA - Tiny Low-Rank Adaptation for ESP32
+
+use heapless::Vec as HVec;
+use crate::QuantParams;
+
+pub const MAX_LORA_RANK: usize = 2;
+pub const MAX_LORA_DIM: usize = 64;
+
+#[derive(Debug, Clone, Copy)]
+pub struct LoRAConfig {
+    pub rank: usize,
+    pub dim: usize,
+    pub scale: i8,
+    pub frozen: bool,
+}
+
+impl Default for LoRAConfig {
+    fn default() -> Self {
+        Self { rank: 1, dim: 32, scale: 8, frozen: true }
+    }
+}
+
+pub struct MicroLoRA {
+    a_weights: HVec<i8, { MAX_LORA_DIM * MAX_LORA_RANK }>,
+    b_weights: HVec<i8, { MAX_LORA_RANK * MAX_LORA_DIM }>,
+    config: LoRAConfig,
+    intermediate: [i32; MAX_LORA_RANK],
+}
+
+impl MicroLoRA {
+    pub fn new(config: LoRAConfig, seed: u32) -> crate::Result<Self> {
+        if config.rank > MAX_LORA_RANK || config.dim > MAX_LORA_DIM {
+            return Err(crate::Error::InvalidModel("LoRA dimensions too large"));
+        }
+
+        let mut a_weights = HVec::new();
+        let mut b_weights = HVec::new();
+        let mut rng = seed;
+
+        for _ in 0..(config.dim * config.rank) {
+            rng = rng.wrapping_mul(1103515245).wrapping_add(12345);
+            a_weights.push((((rng >> 16) & 0x3F) as i16 - 32) as i8)
+                .map_err(|_| crate::Error::BufferOverflow)?;
+        }
+
+        for _ in 0..(config.rank * config.dim) {
+            b_weights.push(0).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+
+        Ok(Self { a_weights, b_weights, config, intermediate: [0; MAX_LORA_RANK] })
+    }
+
+    pub fn from_weights(config: LoRAConfig, a: &[i8], b: &[i8]) -> crate::Result<Self> {
+        let mut a_vec = HVec::new();
+        let mut b_vec = HVec::new();
+        for &w in a { a_vec.push(w).map_err(|_| crate::Error::BufferOverflow)?; }
+        for &w in b { b_vec.push(w).map_err(|_| crate::Error::BufferOverflow)?; }
+        Ok(Self { a_weights: a_vec, b_weights: b_vec, config, intermediate: [0; MAX_LORA_RANK] })
+    }
+
+    #[inline]
+    pub fn apply(&mut self, input: &[i8], output: &mut [i32]) {
+        let (dim, rank, scale) = (self.config.dim, self.config.rank, self.config.scale as i32);
+
+        for r in 0..rank {
+            let mut sum: i32 = 0;
+            for d in 0..dim {
+                sum += input[d] as i32 * self.a_weights[d * rank + r] as i32;
+            }
+            self.intermediate[r] = sum >> 4;
+        }
+
+        for d in 0..dim {
+            let mut sum: i32 = 0;
+            for r in 0..rank {
+                sum += self.intermediate[r] * self.b_weights[r * dim + d] as i32;
+            }
+            output[d] += (sum * scale) >> 8;
+        }
+    }
+
+    pub fn memory_size(&self) -> usize { self.a_weights.len() + self.b_weights.len() }
+}
+
+pub struct LoRAStack<const NUM_LAYERS: usize> {
+    adapters: [Option<MicroLoRA>; NUM_LAYERS],
+    active_count: usize,
+}
+
+impl<const NUM_LAYERS: usize> LoRAStack<NUM_LAYERS> {
+    pub fn new() -> Self {
+        Self { adapters: core::array::from_fn(|_| None), active_count: 0 }
+    }
+
+    pub fn add_adapter(&mut self, layer: usize, adapter: MicroLoRA) -> crate::Result<()> {
+        if layer >= NUM_LAYERS { return Err(crate::Error::InvalidModel("Layer out of range")); }
+        self.adapters[layer] = Some(adapter);
+        self.active_count += 1;
+        Ok(())
+    }
+
+    pub fn get(&mut self, layer: usize) -> Option<&mut MicroLoRA> {
+        self.adapters.get_mut(layer).and_then(|a| a.as_mut())
+    }
+
+    pub fn total_memory(&self) -> usize {
+        self.adapters.iter().filter_map(|a| a.as_ref()).map(|a| a.memory_size()).sum()
+    }
+}
+
+impl<const N: usize> Default for LoRAStack<N> {
+    fn default() -> Self { Self::new() }
+}

examples/ruvLLM/esp32-flash/src/optimizations/mod.rs

@@ -0,0 +1,22 @@
+//! Advanced Optimizations for ESP32
+//!
+//! - Binary quantization (32x compression)
+//! - Product quantization (8-32x compression)
+//! - Lookup tables (fixed-point softmax)
+//! - MicroLoRA (on-device adaptation)
+//! - Sparse attention patterns
+//! - MinCut-inspired pruning
+
+pub mod binary_quant;
+pub mod product_quant;
+pub mod lookup_tables;
+pub mod micro_lora;
+pub mod sparse_attention;
+pub mod pruning;
+
+pub use binary_quant::{BinaryVector, BinaryEmbedding, hamming_distance, hamming_similarity, popcount8};
+pub use product_quant::{ProductQuantizer, PQCode, PQConfig, PQDistanceTable};
+pub use lookup_tables::{SoftmaxLUT, ExpLUT, DistanceLUT, SOFTMAX_LUT, EXP_LUT, DISTANCE_LUT};
+pub use micro_lora::{MicroLoRA, LoRAConfig, LoRAStack};
+pub use sparse_attention::{SparseAttention, AttentionPattern, AttentionPatternCache};
+pub use pruning::{LayerPruner, PruningConfig, PruningMask, PruningStats, MinCutScorer};

examples/ruvLLM/esp32-flash/src/optimizations/product_quant.rs

@@ -0,0 +1,149 @@
+//! Product Quantization - 8-32x Memory Compression
+
+use heapless::Vec as HVec;
+
+pub const MAX_SUBQUANTIZERS: usize = 8;
+pub const MAX_CODEBOOK_SIZE: usize = 16;
+
+#[derive(Debug, Clone, Copy, Default)]
+pub struct PQConfig {
+    pub num_subquantizers: usize,
+    pub codebook_size: usize,
+    pub subvec_dim: usize,
+    pub dim: usize,
+}
+
+impl PQConfig {
+    pub fn new(dim: usize, num_sub: usize) -> Self {
+        Self {
+            num_subquantizers: num_sub,
+            codebook_size: 16,
+            subvec_dim: dim / num_sub,
+            dim,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct PQCode<const M: usize> {
+    pub codes: HVec<u8, M>,
+}
+
+impl<const M: usize> PQCode<M> {
+    pub fn from_codes(codes: &[u8]) -> crate::Result<Self> {
+        let mut code_vec = HVec::new();
+        for &c in codes {
+            code_vec.push(c).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+        Ok(Self { codes: code_vec })
+    }
+
+    #[inline]
+    pub fn get_code(&self, i: usize) -> u8 {
+        self.codes.get(i).copied().unwrap_or(0)
+    }
+}
+
+pub struct ProductQuantizer<const M: usize, const K: usize, const D: usize> {
+    codebooks: HVec<i8, { 8 * 16 * 8 }>,
+    config: PQConfig,
+}
+
+impl<const M: usize, const K: usize, const D: usize> ProductQuantizer<M, K, D> {
+    pub fn random(config: PQConfig, seed: u32) -> crate::Result<Self> {
+        let total = config.num_subquantizers * config.codebook_size * config.subvec_dim;
+        let mut codebooks = HVec::new();
+        let mut rng = seed;
+
+        for _ in 0..total {
+            rng = rng.wrapping_mul(1103515245).wrapping_add(12345);
+            let val = (((rng >> 16) & 0xFF) as i16 - 128) as i8;
+            codebooks.push(val).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+        Ok(Self { codebooks, config })
+    }
+
+    #[inline]
+    fn get_centroid(&self, m: usize, k: usize) -> &[i8] {
+        let d = self.config.subvec_dim;
+        let kk = self.config.codebook_size;
+        let start = m * kk * d + k * d;
+        &self.codebooks[start..start + d]
+    }
+
+    pub fn encode(&self, vector: &[i8]) -> crate::Result<PQCode<M>> {
+        if vector.len() != self.config.dim {
+            return Err(crate::Error::InvalidModel("Dimension mismatch"));
+        }
+        let mut codes = HVec::new();
+        let d = self.config.subvec_dim;
+
+        for m in 0..self.config.num_subquantizers {
+            let subvec = &vector[m * d..(m + 1) * d];
+            let mut best_code = 0u8;
+            let mut best_dist = i32::MAX;
+
+            for k in 0..self.config.codebook_size {
+                let dist = Self::l2_squared(subvec, self.get_centroid(m, k));
+                if dist < best_dist {
+                    best_dist = dist;
+                    best_code = k as u8;
+                }
+            }
+            codes.push(best_code).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+        Ok(PQCode { codes })
+    }
+
+    pub fn asymmetric_distance(&self, query: &[i8], code: &PQCode<M>) -> i32 {
+        let d = self.config.subvec_dim;
+        let mut total: i32 = 0;
+        for m in 0..self.config.num_subquantizers {
+            let query_sub = &query[m * d..(m + 1) * d];
+            let k = code.get_code(m) as usize;
+            total += Self::l2_squared(query_sub, self.get_centroid(m, k));
+        }
+        total
+    }
+
+    pub fn build_distance_table(&self, query: &[i8]) -> PQDistanceTable<M, K> {
+        let mut table = PQDistanceTable::new();
+        let d = self.config.subvec_dim;
+        for m in 0..self.config.num_subquantizers {
+            let query_sub = &query[m * d..(m + 1) * d];
+            for k in 0..self.config.codebook_size {
+                let dist = Self::l2_squared(query_sub, self.get_centroid(m, k));
+                table.set(m, k, dist);
+            }
+        }
+        table
+    }
+
+    #[inline]
+    fn l2_squared(a: &[i8], b: &[i8]) -> i32 {
+        a.iter().zip(b.iter()).map(|(&x, &y)| {
+            let diff = x as i32 - y as i32;
+            diff * diff
+        }).sum()
+    }
+
+    pub fn compression_ratio(&self) -> f32 {
+        self.config.dim as f32 / self.config.num_subquantizers as f32
+    }
+}
+
+pub struct PQDistanceTable<const M: usize, const K: usize> {
+    distances: [i32; 128],
+}
+
+impl<const M: usize, const K: usize> PQDistanceTable<M, K> {
+    pub fn new() -> Self { Self { distances: [0; 128] } }
+    #[inline]
+    pub fn get(&self, m: usize, k: usize) -> i32 { self.distances[m * K + k] }
+    #[inline]
+    pub fn set(&mut self, m: usize, k: usize, dist: i32) { self.distances[m * K + k] = dist; }
+}
+
+impl<const M: usize, const K: usize> Default for PQDistanceTable<M, K> {
+    fn default() -> Self { Self::new() }
+}

examples/ruvLLM/esp32-flash/src/optimizations/pruning.rs

@@ -0,0 +1,167 @@
+//! MinCut-Inspired Layer Pruning
+
+use heapless::Vec as HVec;
+
+pub const MAX_PRUNING_UNITS: usize = 64;
+pub const MAX_MASK_WORDS: usize = 64;
+
+#[derive(Debug, Clone, Copy)]
+pub struct PruningConfig {
+    pub target_sparsity: f32,
+    pub importance_threshold: i8,
+    pub structured: bool,
+}
+
+impl Default for PruningConfig {
+    fn default() -> Self {
+        Self { target_sparsity: 0.5, importance_threshold: 8, structured: true }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct PruningMask<const N: usize> {
+    pub mask: HVec<u32, MAX_MASK_WORDS>,
+    pub size: usize,
+    pub pruned_count: usize,
+}
+
+impl<const N: usize> PruningMask<N> {
+    pub fn new(size: usize) -> crate::Result<Self> {
+        let num_words = (size + 31) / 32;
+        let mut mask = HVec::new();
+        for i in 0..num_words {
+            let bits = if i == num_words - 1 && size % 32 != 0 {
+                (1u32 << (size % 32)) - 1
+            } else {
+                u32::MAX
+            };
+            mask.push(bits).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+        Ok(Self { mask, size, pruned_count: 0 })
+    }
+
+    #[inline]
+    pub fn is_kept(&self, idx: usize) -> bool {
+        let word = idx / 32;
+        let bit = idx % 32;
+        (self.mask.get(word).copied().unwrap_or(0) >> bit) & 1 == 1
+    }
+
+    pub fn prune(&mut self, idx: usize) {
+        if idx < self.size && self.is_kept(idx) {
+            let word = idx / 32;
+            let bit = idx % 32;
+            if let Some(w) = self.mask.get_mut(word) {
+                *w &= !(1 << bit);
+                self.pruned_count += 1;
+            }
+        }
+    }
+
+    pub fn sparsity(&self) -> f32 { self.pruned_count as f32 / self.size as f32 }
+}
+
+pub struct LayerPruner {
+    config: PruningConfig,
+    importance_scores: HVec<i16, MAX_PRUNING_UNITS>,
+}
+
+impl LayerPruner {
+    pub fn new(config: PruningConfig) -> Self {
+        Self { config, importance_scores: HVec::new() }
+    }
+
+    pub fn compute_magnitude_importance(&mut self, weights: &[i8]) {
+        self.importance_scores.clear();
+        for &w in weights.iter().take(MAX_PRUNING_UNITS) {
+            let _ = self.importance_scores.push((w as i16).abs());
+        }
+    }
+
+    pub fn create_mask<const N: usize>(&self, size: usize) -> crate::Result<PruningMask<N>> {
+        let mut mask = PruningMask::new(size)?;
+        let threshold = self.compute_threshold(size);
+        for (idx, &score) in self.importance_scores.iter().enumerate() {
+            if score < threshold { mask.prune(idx); }
+        }
+        Ok(mask)
+    }
+
+    fn compute_threshold(&self, size: usize) -> i16 {
+        let target = (size as f32 * self.config.target_sparsity) as usize;
+        if target == 0 || self.importance_scores.is_empty() { return 0; }
+
+        let mut sorted: HVec<i16, MAX_PRUNING_UNITS> = self.importance_scores.clone();
+        for i in 0..sorted.len() {
+            for j in 0..sorted.len() - 1 - i {
+                if sorted[j] > sorted[j + 1] { sorted.swap(j, j + 1); }
+            }
+        }
+        sorted.get(target.min(sorted.len() - 1)).copied().unwrap_or(0)
+    }
+
+    pub fn apply_mask<const N: usize>(&self, weights: &mut [i8], mask: &PruningMask<N>) {
+        for (idx, weight) in weights.iter_mut().enumerate() {
+            if !mask.is_kept(idx) { *weight = 0; }
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct PruningStats {
+    pub total_weights: usize,
+    pub pruned_weights: usize,
+    pub sparsity: f32,
+    pub memory_saved: usize,
+}
+
+pub struct MinCutScorer {
+    input_flow: HVec<i32, MAX_PRUNING_UNITS>,
+    output_flow: HVec<i32, MAX_PRUNING_UNITS>,
+}
+
+impl MinCutScorer {
+    pub fn new() -> Self {
+        Self { input_flow: HVec::new(), output_flow: HVec::new() }
+    }
+
+    pub fn compute_edge_importance(&mut self, weights: &[i8], input_dim: usize, output_dim: usize)
+        -> HVec<i16, MAX_PRUNING_UNITS>
+    {
+        self.input_flow.clear();
+        self.output_flow.clear();
+
+        for in_idx in 0..input_dim.min(MAX_PRUNING_UNITS) {
+            let flow: i32 = (0..output_dim).map(|out_idx| {
+                let w_idx = out_idx * input_dim + in_idx;
+                if w_idx < weights.len() { (weights[w_idx] as i32).abs() } else { 0 }
+            }).sum();
+            let _ = self.input_flow.push(flow);
+        }
+
+        for out_idx in 0..output_dim.min(MAX_PRUNING_UNITS) {
+            let flow: i32 = (0..input_dim).map(|in_idx| {
+                let w_idx = out_idx * input_dim + in_idx;
+                if w_idx < weights.len() { (weights[w_idx] as i32).abs() } else { 0 }
+            }).sum();
+            let _ = self.output_flow.push(flow);
+        }
+
+        let mut importance: HVec<i16, MAX_PRUNING_UNITS> = HVec::new();
+        for out_idx in 0..output_dim.min(self.output_flow.len()) {
+            for in_idx in 0..input_dim.min(self.input_flow.len()) {
+                let w_idx = out_idx * input_dim + in_idx;
+                if w_idx < weights.len() && importance.len() < MAX_PRUNING_UNITS {
+                    let w = (weights[w_idx] as i32).abs();
+                    let bottleneck = self.input_flow[in_idx].min(self.output_flow[out_idx]);
+                    let _ = importance.push(((w * bottleneck) >> 10) as i16);
+                }
+            }
+        }
+        importance
+    }
+}
+
+impl Default for MinCutScorer {
+    fn default() -> Self { Self::new() }
+}

examples/ruvLLM/esp32-flash/src/optimizations/sparse_attention.rs

@@ -0,0 +1,120 @@
+//! Sparse Attention Patterns for ESP32
+
+use heapless::Vec as HVec;
+
+pub const MAX_SPARSE_SEQ: usize = 32;
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum AttentionPattern {
+    Full,
+    SlidingWindow { window_size: usize },
+    Strided { stride: usize },
+    Longformer { window_size: usize, stride: usize },
+    BlockDiagonal { block_size: usize },
+    BigBird { window_size: usize, global_tokens: usize },
+}
+
+impl Default for AttentionPattern {
+    fn default() -> Self { Self::SlidingWindow { window_size: 4 } }
+}
+
+pub struct SparseAttention {
+    pattern: AttentionPattern,
+    mask_data: HVec<u32, MAX_SPARSE_SEQ>,
+    seq_len: usize,
+}
+
+impl SparseAttention {
+    pub fn new(pattern: AttentionPattern, seq_len: usize) -> crate::Result<Self> {
+        if seq_len > MAX_SPARSE_SEQ { return Err(crate::Error::BufferOverflow); }
+        let mut sa = Self { pattern, mask_data: HVec::new(), seq_len };
+        sa.build_mask()?;
+        Ok(sa)
+    }
+
+    fn build_mask(&mut self) -> crate::Result<()> {
+        self.mask_data.clear();
+        for i in 0..self.seq_len {
+            let mut row_mask: u32 = 0;
+            for j in 0..self.seq_len {
+                if j <= i && self.should_attend(i, j) {
+                    row_mask |= 1 << j;
+                }
+            }
+            self.mask_data.push(row_mask).map_err(|_| crate::Error::BufferOverflow)?;
+        }
+        Ok(())
+    }
+
+    fn should_attend(&self, i: usize, j: usize) -> bool {
+        match self.pattern {
+            AttentionPattern::Full => true,
+            AttentionPattern::SlidingWindow { window_size } => i.saturating_sub(window_size) <= j,
+            AttentionPattern::Strided { stride } => j % stride == 0 || i.saturating_sub(1) <= j,
+            AttentionPattern::Longformer { window_size, stride } =>
+                i.saturating_sub(window_size) <= j || j % stride == 0,
+            AttentionPattern::BlockDiagonal { block_size } => i / block_size == j / block_size,
+            AttentionPattern::BigBird { window_size, global_tokens } =>
+                i.saturating_sub(window_size) <= j || j < global_tokens,
+        }
+    }
+
+    #[inline]
+    pub fn should_attend_at(&self, i: usize, j: usize) -> bool {
+        if i >= self.seq_len || j >= self.seq_len { return false; }
+        (self.mask_data[i] >> j) & 1 == 1
+    }
+
+    #[inline]
+    pub fn get_mask_row(&self, i: usize) -> u32 {
+        self.mask_data.get(i).copied().unwrap_or(0)
+    }
+
+    pub fn sparse_qk(&self, query: &[i8], keys: &[&[i8]], scores: &mut [i32], query_pos: usize) {
+        let mask = self.get_mask_row(query_pos);
+        for (j, key) in keys.iter().enumerate() {
+            if (mask >> j) & 1 == 1 {
+                scores[j] = query.iter().zip(key.iter()).map(|(&q, &k)| q as i32 * k as i32).sum();
+            } else {
+                scores[j] = i32::MIN;
+            }
+        }
+    }
+
+    pub fn active_positions(&self) -> usize {
+        self.mask_data.iter().map(|m| m.count_ones() as usize).sum()
+    }
+
+    pub fn sparsity_ratio(&self) -> f32 {
+        let full = self.seq_len * (self.seq_len + 1) / 2;
+        self.active_positions() as f32 / full as f32
+    }
+}
+
+pub struct AttentionPatternCache {
+    patterns: [Option<SparseAttention>; 4],
+}
+
+impl AttentionPatternCache {
+    pub fn new_sliding(window: usize) -> Self {
+        let p = AttentionPattern::SlidingWindow { window_size: window };
+        Self {
+            patterns: [
+                SparseAttention::new(p, 8).ok(),
+                SparseAttention::new(p, 16).ok(),
+                SparseAttention::new(p, 24).ok(),
+                SparseAttention::new(p, 32).ok(),
+            ],
+        }
+    }
+
+    pub fn get(&self, seq_len: usize) -> Option<&SparseAttention> {
+        match seq_len {
+            1..=8 => self.patterns[0].as_ref(),
+            9..=16 => self.patterns[1].as_ref(),
+            17..=24 => self.patterns[2].as_ref(),
+            25..=32 => self.patterns[3].as_ref(),
+            _ => None,
+        }
+    }
+}

examples/ruvLLM/esp32-flash/src/ota.rs

@@ -0,0 +1,418 @@
+//! Over-the-Air (OTA) Update System for RuvLLM ESP32
+//!
+//! Enables wireless firmware updates via WiFi without physical access to the device.
+//!
+//! # Features
+//! - HTTPS firmware download with verification
+//! - SHA256 checksum validation
+//! - Rollback on failed update
+//! - Progress callbacks
+//! - Minimal RAM footprint (streaming update)
+
+use core::fmt;
+
+/// OTA update configuration
+#[derive(Clone)]
+pub struct OtaConfig {
+    /// Firmware server URL
+    pub server_url: heapless::String<128>,
+    /// Current firmware version
+    pub current_version: heapless::String<16>,
+    /// WiFi SSID
+    pub wifi_ssid: heapless::String<32>,
+    /// WiFi password
+    pub wifi_password: heapless::String<64>,
+    /// Check interval in seconds (0 = manual only)
+    pub check_interval_secs: u32,
+    /// Enable automatic updates
+    pub auto_update: bool,
+}
+
+impl Default for OtaConfig {
+    fn default() -> Self {
+        Self {
+            server_url: heapless::String::new(),
+            current_version: heapless::String::try_from("0.2.1").unwrap_or_default(),
+            wifi_ssid: heapless::String::new(),
+            wifi_password: heapless::String::new(),
+            check_interval_secs: 3600, // 1 hour
+            auto_update: false,
+        }
+    }
+}
+
+/// OTA update state
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OtaState {
+    /// Idle, waiting for update check
+    Idle,
+    /// Checking for updates
+    Checking,
+    /// Update available
+    UpdateAvailable,
+    /// Downloading firmware
+    Downloading,
+    /// Verifying firmware
+    Verifying,
+    /// Applying update
+    Applying,
+    /// Update complete, pending reboot
+    Complete,
+    /// Update failed
+    Failed,
+}
+
+impl fmt::Display for OtaState {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            OtaState::Idle => write!(f, "Idle"),
+            OtaState::Checking => write!(f, "Checking"),
+            OtaState::UpdateAvailable => write!(f, "Update Available"),
+            OtaState::Downloading => write!(f, "Downloading"),
+            OtaState::Verifying => write!(f, "Verifying"),
+            OtaState::Applying => write!(f, "Applying"),
+            OtaState::Complete => write!(f, "Complete"),
+            OtaState::Failed => write!(f, "Failed"),
+        }
+    }
+}
+
+/// Update information
+#[derive(Clone)]
+pub struct UpdateInfo {
+    /// New version string
+    pub version: heapless::String<16>,
+    /// Firmware size in bytes
+    pub size: u32,
+    /// SHA256 checksum (hex string)
+    pub checksum: heapless::String<64>,
+    /// Release notes
+    pub notes: heapless::String<256>,
+    /// Download URL
+    pub download_url: heapless::String<256>,
+}
+
+/// OTA update error
+#[derive(Debug, Clone, Copy)]
+pub enum OtaError {
+    /// WiFi connection failed
+    WifiError,
+    /// HTTP request failed
+    HttpError,
+    /// Invalid response from server
+    InvalidResponse,
+    /// Checksum mismatch
+    ChecksumMismatch,
+    /// Not enough storage space
+    InsufficientSpace,
+    /// Flash write failed
+    FlashError,
+    /// Update verification failed
+    VerificationFailed,
+    /// No update available
+    NoUpdate,
+    /// Already up to date
+    AlreadyUpToDate,
+}
+
+impl fmt::Display for OtaError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            OtaError::WifiError => write!(f, "WiFi connection failed"),
+            OtaError::HttpError => write!(f, "HTTP request failed"),
+            OtaError::InvalidResponse => write!(f, "Invalid server response"),
+            OtaError::ChecksumMismatch => write!(f, "Checksum verification failed"),
+            OtaError::InsufficientSpace => write!(f, "Not enough storage space"),
+            OtaError::FlashError => write!(f, "Flash write error"),
+            OtaError::VerificationFailed => write!(f, "Update verification failed"),
+            OtaError::NoUpdate => write!(f, "No update available"),
+            OtaError::AlreadyUpToDate => write!(f, "Already up to date"),
+        }
+    }
+}
+
+/// Progress callback type
+pub type ProgressCallback = fn(downloaded: u32, total: u32);
+
+/// OTA Update Manager
+pub struct OtaManager {
+    config: OtaConfig,
+    state: OtaState,
+    progress: u32,
+    last_error: Option<OtaError>,
+    update_info: Option<UpdateInfo>,
+}
+
+impl OtaManager {
+    /// Create new OTA manager with config
+    pub fn new(config: OtaConfig) -> Self {
+        Self {
+            config,
+            state: OtaState::Idle,
+            progress: 0,
+            last_error: None,
+            update_info: None,
+        }
+    }
+
+    /// Get current state
+    pub fn state(&self) -> OtaState {
+        self.state
+    }
+
+    /// Get download progress (0-100)
+    pub fn progress(&self) -> u32 {
+        self.progress
+    }
+
+    /// Get last error
+    pub fn last_error(&self) -> Option<OtaError> {
+        self.last_error
+    }
+
+    /// Get available update info
+    pub fn update_info(&self) -> Option<&UpdateInfo> {
+        self.update_info.as_ref()
+    }
+
+    /// Check for updates (simulation for no_std)
+    ///
+    /// In a real implementation, this would:
+    /// 1. Connect to WiFi
+    /// 2. Query the update server
+    /// 3. Parse the response
+    /// 4. Compare versions
+    pub fn check_for_update(&mut self) -> Result<bool, OtaError> {
+        self.state = OtaState::Checking;
+        self.last_error = None;
+
+        // Simulated version check
+        // In real impl: HTTP GET to {server_url}/version.json
+        let server_version = "0.2.2"; // Would come from server
+
+        if self.is_newer_version(server_version) {
+            self.update_info = Some(UpdateInfo {
+                version: heapless::String::try_from(server_version).unwrap_or_default(),
+                size: 512 * 1024, // 512KB
+                checksum: heapless::String::try_from(
+                    "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+                ).unwrap_or_default(),
+                notes: heapless::String::try_from("Performance improvements and bug fixes").unwrap_or_default(),
+                download_url: heapless::String::try_from(
+                    "https://github.com/ruvnet/ruvector/releases/latest/download/ruvllm-esp32"
+                ).unwrap_or_default(),
+            });
+            self.state = OtaState::UpdateAvailable;
+            Ok(true)
+        } else {
+            self.state = OtaState::Idle;
+            self.last_error = Some(OtaError::AlreadyUpToDate);
+            Ok(false)
+        }
+    }
+
+    /// Compare version strings (simple semver comparison)
+    fn is_newer_version(&self, server_version: &str) -> bool {
+        let current = self.parse_version(self.config.current_version.as_str());
+        let server = self.parse_version(server_version);
+
+        server > current
+    }
+
+    /// Parse version string to tuple
+    fn parse_version(&self, version: &str) -> (u32, u32, u32) {
+        let mut parts = version.split('.');
+        let major = parts.next().and_then(|s| s.parse().ok()).unwrap_or(0);
+        let minor = parts.next().and_then(|s| s.parse().ok()).unwrap_or(0);
+        let patch = parts.next().and_then(|s| s.parse().ok()).unwrap_or(0);
+        (major, minor, patch)
+    }
+
+    /// Start firmware download
+    ///
+    /// In real implementation:
+    /// 1. Stream download to flash partition
+    /// 2. Verify checksum incrementally
+    /// 3. Call progress callback
+    pub fn download_update(&mut self, _progress_cb: Option<ProgressCallback>) -> Result<(), OtaError> {
+        if self.state != OtaState::UpdateAvailable {
+            return Err(OtaError::NoUpdate);
+        }
+
+        self.state = OtaState::Downloading;
+        self.progress = 0;
+
+        // Simulated download
+        // In real impl: HTTP GET with streaming to flash
+        let total_size = self.update_info.as_ref().map(|i| i.size).unwrap_or(0);
+
+        // Simulate progress
+        for i in 0..=100 {
+            self.progress = i;
+            if let Some(cb) = _progress_cb {
+                cb(i * total_size / 100, total_size);
+            }
+        }
+
+        self.state = OtaState::Verifying;
+        Ok(())
+    }
+
+    /// Verify downloaded firmware
+    pub fn verify_update(&mut self) -> Result<(), OtaError> {
+        if self.state != OtaState::Verifying {
+            return Err(OtaError::VerificationFailed);
+        }
+
+        // In real impl: Calculate SHA256 of downloaded partition
+        // Compare with expected checksum
+
+        // Simulated verification
+        self.state = OtaState::Complete;
+        Ok(())
+    }
+
+    /// Apply update and reboot
+    ///
+    /// In real implementation:
+    /// 1. Set boot partition to new firmware
+    /// 2. Reboot device
+    pub fn apply_update(&mut self) -> Result<(), OtaError> {
+        if self.state != OtaState::Complete {
+            return Err(OtaError::VerificationFailed);
+        }
+
+        self.state = OtaState::Applying;
+
+        // In real impl:
+        // esp_ota_set_boot_partition(...)
+        // esp_restart()
+
+        Ok(())
+    }
+
+    /// Rollback to previous firmware
+    pub fn rollback(&mut self) -> Result<(), OtaError> {
+        // In real impl:
+        // esp_ota_mark_app_invalid_rollback_and_reboot()
+        self.state = OtaState::Idle;
+        Ok(())
+    }
+
+    /// Get human-readable status
+    pub fn status_string(&self) -> &'static str {
+        match self.state {
+            OtaState::Idle => "Ready",
+            OtaState::Checking => "Checking for updates...",
+            OtaState::UpdateAvailable => "Update available!",
+            OtaState::Downloading => "Downloading update...",
+            OtaState::Verifying => "Verifying firmware...",
+            OtaState::Applying => "Applying update...",
+            OtaState::Complete => "Update complete! Reboot to apply.",
+            OtaState::Failed => "Update failed",
+        }
+    }
+}
+
+/// OTA serial command handler
+pub fn handle_ota_command(manager: &mut OtaManager, command: &str) -> heapless::String<256> {
+    let mut response = heapless::String::new();
+
+    let parts: heapless::Vec<&str, 4> = command.split_whitespace().collect();
+    let cmd = parts.first().copied().unwrap_or("");
+
+    match cmd {
+        "status" => {
+            let _ = core::fmt::write(
+                &mut response,
+                format_args!("OTA Status: {} ({}%)", manager.status_string(), manager.progress())
+            );
+        }
+        "check" => {
+            match manager.check_for_update() {
+                Ok(true) => {
+                    if let Some(info) = manager.update_info() {
+                        let _ = core::fmt::write(
+                            &mut response,
+                            format_args!("Update available: v{} ({}KB)", info.version, info.size / 1024)
+                        );
+                    }
+                }
+                Ok(false) => {
+                    let _ = response.push_str("Already up to date");
+                }
+                Err(e) => {
+                    let _ = core::fmt::write(&mut response, format_args!("Check failed: {}", e));
+                }
+            }
+        }
+        "download" => {
+            match manager.download_update(None) {
+                Ok(()) => {
+                    let _ = response.push_str("Download complete");
+                }
+                Err(e) => {
+                    let _ = core::fmt::write(&mut response, format_args!("Download failed: {}", e));
+                }
+            }
+        }
+        "apply" => {
+            let _ = manager.verify_update();
+            match manager.apply_update() {
+                Ok(()) => {
+                    let _ = response.push_str("Rebooting to apply update...");
+                }
+                Err(e) => {
+                    let _ = core::fmt::write(&mut response, format_args!("Apply failed: {}", e));
+                }
+            }
+        }
+        "rollback" => {
+            match manager.rollback() {
+                Ok(()) => {
+                    let _ = response.push_str("Rolling back to previous firmware...");
+                }
+                Err(e) => {
+                    let _ = core::fmt::write(&mut response, format_args!("Rollback failed: {}", e));
+                }
+            }
+        }
+        _ => {
+            let _ = response.push_str("OTA commands: status, check, download, apply, rollback");
+        }
+    }
+
+    response
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_version_comparison() {
+        let config = OtaConfig {
+            current_version: heapless::String::try_from("0.2.1").unwrap(),
+            ..Default::default()
+        };
+        let manager = OtaManager::new(config);
+
+        assert!(manager.is_newer_version("0.2.2"));
+        assert!(manager.is_newer_version("0.3.0"));
+        assert!(manager.is_newer_version("1.0.0"));
+        assert!(!manager.is_newer_version("0.2.1"));
+        assert!(!manager.is_newer_version("0.2.0"));
+        assert!(!manager.is_newer_version("0.1.0"));
+    }
+
+    #[test]
+    fn test_state_transitions() {
+        let config = OtaConfig::default();
+        let mut manager = OtaManager::new(config);
+
+        assert_eq!(manager.state(), OtaState::Idle);
+
+        let _ = manager.check_for_update();
+        assert!(matches!(manager.state(), OtaState::UpdateAvailable | OtaState::Idle));
+    }
+}

examples/ruvLLM/esp32-flash/src/ruvector/anomaly.rs

@@ -0,0 +1,142 @@
+//! Anomaly Detection via Embedding Distance
+
+use heapless::Vec as HVec;
+use super::{MicroHNSW, HNSWConfig, MicroVector, DistanceMetric};
+
+const ANOMALY_DIM: usize = 32;
+const HISTORY_SIZE: usize = 64;
+
+#[derive(Debug, Clone)]
+pub struct AnomalyConfig {
+    pub threshold_multiplier: f32,
+    pub min_samples: usize,
+    pub window_size: usize,
+    pub adapt_rate: f32,
+}
+
+impl Default for AnomalyConfig {
+    fn default() -> Self {
+        Self { threshold_multiplier: 2.0, min_samples: 10, window_size: 32, adapt_rate: 0.1 }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct AnomalyResult {
+    pub is_anomaly: bool,
+    pub score: i32,
+    pub threshold: i32,
+    pub confidence: u8,
+    pub nearest_distance: i32,
+}
+
+pub struct AnomalyDetector {
+    config: AnomalyConfig,
+    index: MicroHNSW<ANOMALY_DIM, HISTORY_SIZE>,
+    distance_history: HVec<i32, HISTORY_SIZE>,
+    mean_distance: i32,
+    std_distance: i32,
+    next_id: u32,
+}
+
+impl AnomalyDetector {
+    pub fn new(config: AnomalyConfig) -> Self {
+        let hnsw_config = HNSWConfig { m: 4, m_max0: 8, ef_construction: 16, ef_search: 8, metric: DistanceMetric::Euclidean, binary_mode: false };
+        Self { config, index: MicroHNSW::new(hnsw_config), distance_history: HVec::new(), mean_distance: 0, std_distance: 100, next_id: 0 }
+    }
+
+    pub fn len(&self) -> usize { self.index.len() }
+
+    pub fn add_sample(&mut self, embedding: &[i8]) -> Result<AnomalyResult, &'static str> {
+        let result = self.check(embedding);
+
+        let id = self.next_id;
+        self.next_id += 1;
+
+        let mut data = HVec::new();
+        for &v in embedding.iter().take(ANOMALY_DIM) { data.push(v).map_err(|_| "Embedding too large")?; }
+        let vec = MicroVector { data, id };
+        self.index.insert(&vec)?;
+
+        if result.nearest_distance > 0 {
+            if self.distance_history.len() >= HISTORY_SIZE { self.distance_history.remove(0); }
+            let _ = self.distance_history.push(result.nearest_distance);
+            self.update_stats();
+        }
+
+        Ok(result)
+    }
+
+    pub fn check(&self, embedding: &[i8]) -> AnomalyResult {
+        if self.index.len() < self.config.min_samples {
+            return AnomalyResult { is_anomaly: false, score: 0, threshold: 0, confidence: 0, nearest_distance: 0 };
+        }
+
+        let results = self.index.search(embedding, 1);
+        let nearest_distance = results.first().map(|r| r.distance).unwrap_or(i32::MAX);
+        let threshold = self.compute_threshold();
+        let is_anomaly = nearest_distance > threshold;
+        let score = nearest_distance - self.mean_distance;
+        let confidence = self.compute_confidence(nearest_distance, threshold);
+
+        AnomalyResult { is_anomaly, score, threshold, confidence, nearest_distance }
+    }
+
+    fn compute_threshold(&self) -> i32 {
+        let multiplier = (self.config.threshold_multiplier * 100.0) as i32;
+        self.mean_distance + (self.std_distance * multiplier) / 100
+    }
+
+    fn compute_confidence(&self, distance: i32, threshold: i32) -> u8 {
+        if threshold == 0 { return 0; }
+        let diff = (distance - threshold).abs();
+        let conf = if distance > threshold {
+            50 + ((diff * 50) / threshold.max(1)).min(50)
+        } else {
+            50 - ((diff * 50) / threshold.max(1)).min(50)
+        };
+        conf.clamp(0, 100) as u8
+    }
+
+    fn update_stats(&mut self) {
+        if self.distance_history.is_empty() { return; }
+
+        let sum: i32 = self.distance_history.iter().sum();
+        self.mean_distance = sum / self.distance_history.len() as i32;
+
+        let variance: i32 = self.distance_history.iter()
+            .map(|&d| { let diff = d - self.mean_distance; diff * diff })
+            .sum::<i32>() / self.distance_history.len() as i32;
+
+        self.std_distance = isqrt(variance as u64) as i32;
+    }
+
+    pub fn reset(&mut self) {
+        self.index = MicroHNSW::new(HNSWConfig::default());
+        self.distance_history.clear();
+        self.mean_distance = 0;
+        self.std_distance = 100;
+        self.next_id = 0;
+    }
+
+    pub fn stats(&self) -> AnomalyStats {
+        AnomalyStats { samples: self.index.len(), mean_distance: self.mean_distance, std_distance: self.std_distance, threshold: self.compute_threshold() }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct AnomalyStats {
+    pub samples: usize,
+    pub mean_distance: i32,
+    pub std_distance: i32,
+    pub threshold: i32,
+}
+
+fn isqrt(n: u64) -> u64 {
+    if n == 0 { return 0; }
+    let mut x = n;
+    let mut y = (x + 1) / 2;
+    while y < x { x = y; y = (x + n / x) / 2; }
+    x
+}
+
+impl Default for AnomalyDetector { fn default() -> Self { Self::new(AnomalyConfig::default()) } }

examples/ruvLLM/esp32-flash/src/ruvector/micro_hnsw.rs

@@ -0,0 +1,226 @@
+//! Micro HNSW - Approximate Nearest Neighbor for ESP32
+
+use heapless::Vec as HVec;
+use heapless::BinaryHeap;
+use heapless::binary_heap::Min;
+use super::{MicroVector, DistanceMetric, euclidean_distance_i8, MAX_NEIGHBORS};
+
+pub const INDEX_CAPACITY: usize = 256;
+pub const MAX_LAYERS: usize = 4;
+pub const DEFAULT_M: usize = 8;
+pub const EF_SEARCH: usize = 16;
+
+#[derive(Debug, Clone)]
+pub struct HNSWConfig {
+    pub m: usize,
+    pub m_max0: usize,
+    pub ef_construction: usize,
+    pub ef_search: usize,
+    pub metric: DistanceMetric,
+    pub binary_mode: bool,
+}
+
+impl Default for HNSWConfig {
+    fn default() -> Self {
+        Self { m: 8, m_max0: 16, ef_construction: 32, ef_search: 16, metric: DistanceMetric::Euclidean, binary_mode: false }
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct SearchResult {
+    pub id: u32,
+    pub distance: i32,
+    pub index: usize,
+}
+
+impl PartialEq for SearchResult { fn eq(&self, other: &Self) -> bool { self.distance == other.distance } }
+impl Eq for SearchResult {}
+impl PartialOrd for SearchResult { fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> { Some(self.cmp(other)) } }
+impl Ord for SearchResult { fn cmp(&self, other: &Self) -> core::cmp::Ordering { self.distance.cmp(&other.distance) } }
+
+#[derive(Debug, Clone)]
+struct HNSWNode<const DIM: usize> {
+    vector: HVec<i8, DIM>,
+    id: u32,
+    neighbors: [HVec<u16, MAX_NEIGHBORS>; MAX_LAYERS],
+    max_layer: u8,
+}
+
+impl<const DIM: usize> Default for HNSWNode<DIM> {
+    fn default() -> Self {
+        Self { vector: HVec::new(), id: 0, neighbors: Default::default(), max_layer: 0 }
+    }
+}
+
+pub struct MicroHNSW<const DIM: usize, const CAPACITY: usize> {
+    config: HNSWConfig,
+    nodes: HVec<HNSWNode<DIM>, CAPACITY>,
+    entry_point: Option<usize>,
+    max_layer: u8,
+    rng_state: u32,
+}
+
+impl<const DIM: usize, const CAPACITY: usize> MicroHNSW<DIM, CAPACITY> {
+    pub fn new(config: HNSWConfig) -> Self {
+        Self { config, nodes: HVec::new(), entry_point: None, max_layer: 0, rng_state: 12345 }
+    }
+
+    pub fn with_seed(mut self, seed: u32) -> Self { self.rng_state = seed; self }
+    pub fn len(&self) -> usize { self.nodes.len() }
+    pub fn is_empty(&self) -> bool { self.nodes.is_empty() }
+    pub fn memory_bytes(&self) -> usize { self.nodes.len() * (DIM + MAX_LAYERS * MAX_NEIGHBORS * 2 + 8) }
+
+    pub fn insert(&mut self, vector: &MicroVector<DIM>) -> Result<usize, &'static str> {
+        if self.nodes.len() >= CAPACITY { return Err("Index full"); }
+
+        let new_idx = self.nodes.len();
+        let new_layer = self.random_layer();
+
+        let mut node = HNSWNode::<DIM>::default();
+        node.vector = vector.data.clone();
+        node.id = vector.id;
+        node.max_layer = new_layer;
+
+        if self.entry_point.is_none() {
+            self.nodes.push(node).map_err(|_| "Push failed")?;
+            self.entry_point = Some(new_idx);
+            self.max_layer = new_layer;
+            return Ok(new_idx);
+        }
+
+        let entry = self.entry_point.unwrap();
+        self.nodes.push(node).map_err(|_| "Push failed")?;
+
+        let mut current = entry;
+        for layer in (new_layer as usize + 1..=self.max_layer as usize).rev() {
+            current = self.greedy_search_layer(current, &vector.data, layer);
+        }
+
+        for layer in (0..=(new_layer as usize).min(self.max_layer as usize)).rev() {
+            let neighbors = self.search_layer(current, &vector.data, layer, self.config.ef_construction);
+            let max_n = if layer == 0 { self.config.m_max0 } else { self.config.m };
+            let mut added = 0;
+
+            for result in neighbors.iter().take(max_n) {
+                if added >= MAX_NEIGHBORS { break; }
+                if let Some(new_node) = self.nodes.get_mut(new_idx) {
+                    let _ = new_node.neighbors[layer].push(result.index as u16);
+                }
+                if let Some(neighbor) = self.nodes.get_mut(result.index) {
+                    if neighbor.neighbors[layer].len() < MAX_NEIGHBORS {
+                        let _ = neighbor.neighbors[layer].push(new_idx as u16);
+                    }
+                }
+                added += 1;
+            }
+            if !neighbors.is_empty() { current = neighbors[0].index; }
+        }
+
+        if new_layer > self.max_layer {
+            self.entry_point = Some(new_idx);
+            self.max_layer = new_layer;
+        }
+        Ok(new_idx)
+    }
+
+    pub fn search(&self, query: &[i8], k: usize) -> HVec<SearchResult, 32> {
+        let mut results = HVec::new();
+        if self.entry_point.is_none() || k == 0 { return results; }
+
+        let entry = self.entry_point.unwrap();
+        let mut current = entry;
+        for layer in (1..=self.max_layer as usize).rev() {
+            current = self.greedy_search_layer(current, query, layer);
+        }
+
+        let candidates = self.search_layer(current, query, 0, self.config.ef_search);
+        for result in candidates.into_iter().take(k) {
+            let _ = results.push(result);
+        }
+        results
+    }
+
+    fn search_layer(&self, entry: usize, query: &[i8], layer: usize, ef: usize) -> HVec<SearchResult, 64> {
+        let mut visited = [false; CAPACITY];
+        let mut candidates: BinaryHeap<SearchResult, Min, 64> = BinaryHeap::new();
+        let mut results: HVec<SearchResult, 64> = HVec::new();
+
+        visited[entry] = true;
+        let entry_dist = self.distance(query, entry);
+        let _ = candidates.push(SearchResult { id: self.nodes[entry].id, distance: entry_dist, index: entry });
+        let _ = results.push(SearchResult { id: self.nodes[entry].id, distance: entry_dist, index: entry });
+
+        while let Some(current) = candidates.pop() {
+            if results.len() >= ef {
+                if let Some(worst) = results.iter().max_by_key(|r| r.distance) {
+                    if current.distance > worst.distance { break; }
+                }
+            }
+
+            if let Some(node) = self.nodes.get(current.index) {
+                if layer < node.neighbors.len() {
+                    for &neighbor_idx in node.neighbors[layer].iter() {
+                        let idx = neighbor_idx as usize;
+                        if idx < CAPACITY && !visited[idx] {
+                            visited[idx] = true;
+                            let dist = self.distance(query, idx);
+                            let should_add = results.len() < ef || results.iter().any(|r| dist < r.distance);
+
+                            if should_add {
+                                let r = SearchResult { id: self.nodes[idx].id, distance: dist, index: idx };
+                                let _ = candidates.push(r);
+                                let _ = results.push(r);
+                                if results.len() > ef * 2 {
+                                    results.sort_by_key(|r| r.distance);
+                                    results.truncate(ef);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        results.sort_by_key(|r| r.distance);
+        results
+    }
+
+    fn greedy_search_layer(&self, entry: usize, query: &[i8], layer: usize) -> usize {
+        let mut current = entry;
+        let mut current_dist = self.distance(query, current);
+
+        loop {
+            let mut improved = false;
+            if let Some(node) = self.nodes.get(current) {
+                if layer < node.neighbors.len() {
+                    for &neighbor_idx in node.neighbors[layer].iter() {
+                        let idx = neighbor_idx as usize;
+                        if idx < self.nodes.len() {
+                            let dist = self.distance(query, idx);
+                            if dist < current_dist {
+                                current = idx;
+                                current_dist = dist;
+                                improved = true;
+                            }
+                        }
+                    }
+                }
+            }
+            if !improved { break; }
+        }
+        current
+    }
+
+    fn distance(&self, query: &[i8], idx: usize) -> i32 {
+        self.nodes.get(idx).map(|n| self.config.metric.distance(query, &n.vector)).unwrap_or(i32::MAX)
+    }
+
+    fn random_layer(&mut self) -> u8 {
+        self.rng_state = self.rng_state.wrapping_mul(1103515245).wrapping_add(12345);
+        let layer = (self.rng_state.leading_zeros() / 4) as u8;
+        layer.min(MAX_LAYERS as u8 - 1)
+    }
+
+    pub fn get(&self, idx: usize) -> Option<&[i8]> { self.nodes.get(idx).map(|n| n.vector.as_slice()) }
+    pub fn get_id(&self, idx: usize) -> Option<u32> { self.nodes.get(idx).map(|n| n.id) }
+}

examples/ruvLLM/esp32-flash/src/ruvector/mod.rs

@@ -0,0 +1,121 @@
+//! RuVector Integration for ESP32
+//!
+//! Vector database capabilities:
+//! - Micro HNSW (1000+ vectors)
+//! - Semantic memory with context
+//! - RAG (Retrieval-Augmented Generation)
+//! - Anomaly detection
+//! - Federated search across chips
+
+pub mod micro_hnsw;
+pub mod semantic_memory;
+pub mod rag;
+pub mod anomaly;
+
+pub use micro_hnsw::{MicroHNSW, HNSWConfig, SearchResult, INDEX_CAPACITY, MAX_LAYERS, DEFAULT_M};
+pub use semantic_memory::{SemanticMemory, Memory, MemoryType, MAX_MEMORIES, MEMORY_DIM};
+pub use rag::{MicroRAG, RAGConfig, RAGResult, MAX_KNOWLEDGE_ENTRIES};
+pub use anomaly::{AnomalyDetector, AnomalyConfig, AnomalyResult};
+
+use heapless::Vec as HVec;
+
+pub const MAX_DIMENSIONS: usize = 128;
+pub const MAX_VECTORS: usize = 1000;
+pub const MAX_NEIGHBORS: usize = 16;
+
+/// Quantized vector for ESP32
+#[derive(Debug, Clone)]
+pub struct MicroVector<const DIM: usize> {
+    pub data: HVec<i8, DIM>,
+    pub id: u32,
+}
+
+impl<const DIM: usize> MicroVector<DIM> {
+    pub fn from_i8(data: &[i8], id: u32) -> Option<Self> {
+        if data.len() > DIM { return None; }
+        let mut vec = HVec::new();
+        for &v in data { vec.push(v).ok()?; }
+        Some(Self { data: vec, id })
+    }
+
+    pub fn from_f32(data: &[f32], id: u32) -> Option<Self> {
+        if data.len() > DIM { return None; }
+        let mut vec = HVec::new();
+        for &v in data {
+            let q = (v * 127.0).clamp(-128.0, 127.0) as i8;
+            vec.push(q).ok()?;
+        }
+        Some(Self { data: vec, id })
+    }
+
+    pub fn dim(&self) -> usize { self.data.len() }
+}
+
+/// Distance metrics
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum DistanceMetric {
+    Euclidean,
+    Cosine,
+    Manhattan,
+    Hamming,
+    DotProduct,
+}
+
+impl DistanceMetric {
+    pub fn distance(&self, a: &[i8], b: &[i8]) -> i32 {
+        match self {
+            Self::Euclidean => euclidean_distance_i8(a, b),
+            Self::Cosine => cosine_distance_i8(a, b),
+            Self::Manhattan => manhattan_distance_i8(a, b),
+            Self::Hamming => hamming_distance_i8(a, b),
+            Self::DotProduct => -dot_product_i8(a, b),
+        }
+    }
+}
+
+pub fn euclidean_distance_i8(a: &[i8], b: &[i8]) -> i32 {
+    a.iter().zip(b.iter()).map(|(&x, &y)| {
+        let d = x as i32 - y as i32;
+        d * d
+    }).sum()
+}
+
+pub fn cosine_distance_i8(a: &[i8], b: &[i8]) -> i32 {
+    let mut dot: i32 = 0;
+    let mut norm_a: i32 = 0;
+    let mut norm_b: i32 = 0;
+
+    for (&x, &y) in a.iter().zip(b.iter()) {
+        let xi = x as i32;
+        let yi = y as i32;
+        dot += xi * yi;
+        norm_a += xi * xi;
+        norm_b += yi * yi;
+    }
+
+    if norm_a == 0 || norm_b == 0 { return i32::MAX; }
+    let norm_product = ((norm_a as i64) * (norm_b as i64)).min(i64::MAX);
+    let norm_sqrt = isqrt(norm_product as u64) as i32;
+    if norm_sqrt == 0 { return i32::MAX; }
+    1000 - ((dot * 1000) / norm_sqrt)
+}
+
+pub fn manhattan_distance_i8(a: &[i8], b: &[i8]) -> i32 {
+    a.iter().zip(b.iter()).map(|(&x, &y)| ((x as i32) - (y as i32)).abs()).sum()
+}
+
+pub fn hamming_distance_i8(a: &[i8], b: &[i8]) -> i32 {
+    a.iter().zip(b.iter()).map(|(&x, &y)| (x ^ y).count_ones() as i32).sum()
+}
+
+pub fn dot_product_i8(a: &[i8], b: &[i8]) -> i32 {
+    a.iter().zip(b.iter()).map(|(&x, &y)| (x as i32) * (y as i32)).sum()
+}
+
+fn isqrt(n: u64) -> u64 {
+    if n == 0 { return 0; }
+    let mut x = n;
+    let mut y = (x + 1) / 2;
+    while y < x { x = y; y = (x + n / x) / 2; }
+    x
+}

examples/ruvLLM/esp32-flash/src/ruvector/rag.rs

@@ -0,0 +1,142 @@
+//! Micro RAG - Retrieval-Augmented Generation for ESP32
+
+use heapless::Vec as HVec;
+use heapless::String as HString;
+use super::{MicroHNSW, HNSWConfig, MicroVector, DistanceMetric, SearchResult};
+
+pub const MAX_KNOWLEDGE_ENTRIES: usize = 64;
+pub const MAX_DOC_LEN: usize = 128;
+pub const RAG_DIM: usize = 32;
+
+#[derive(Debug, Clone)]
+pub struct RAGConfig {
+    pub top_k: usize,
+    pub relevance_threshold: i32,
+    pub max_context_tokens: usize,
+    pub rerank: bool,
+}
+
+impl Default for RAGConfig {
+    fn default() -> Self {
+        Self { top_k: 3, relevance_threshold: 500, max_context_tokens: 256, rerank: true }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct KnowledgeEntry {
+    pub id: u32,
+    pub text: HString<MAX_DOC_LEN>,
+    pub embedding: HVec<i8, RAG_DIM>,
+    pub source: HString<32>,
+    pub importance: u8,
+}
+
+#[derive(Debug, Clone)]
+pub struct RAGResult {
+    pub entries: HVec<(KnowledgeEntry, i32), 8>,
+    pub context: HString<256>,
+    pub confidence: u8,
+}
+
+pub struct MicroRAG {
+    config: RAGConfig,
+    index: MicroHNSW<RAG_DIM, MAX_KNOWLEDGE_ENTRIES>,
+    entries: HVec<KnowledgeEntry, MAX_KNOWLEDGE_ENTRIES>,
+    next_id: u32,
+}
+
+impl MicroRAG {
+    pub fn new(config: RAGConfig) -> Self {
+        let hnsw_config = HNSWConfig { m: 4, m_max0: 8, ef_construction: 16, ef_search: 8, metric: DistanceMetric::Euclidean, binary_mode: false };
+        Self { config, index: MicroHNSW::new(hnsw_config), entries: HVec::new(), next_id: 0 }
+    }
+
+    pub fn len(&self) -> usize { self.entries.len() }
+    pub fn is_empty(&self) -> bool { self.entries.is_empty() }
+
+    pub fn add_knowledge(&mut self, text: &str, embedding: &[i8], source: &str, importance: u8) -> Result<u32, &'static str> {
+        if self.entries.len() >= MAX_KNOWLEDGE_ENTRIES { return Err("Knowledge base full"); }
+
+        let id = self.next_id;
+        self.next_id += 1;
+
+        let mut text_str = HString::new();
+        for c in text.chars().take(MAX_DOC_LEN) { text_str.push(c).ok().ok_or("Text too long")?; }
+
+        let mut embed_vec = HVec::new();
+        for &v in embedding.iter().take(RAG_DIM) { embed_vec.push(v).ok().ok_or("Embedding too large")?; }
+
+        let mut source_str = HString::new();
+        for c in source.chars().take(32) { source_str.push(c).ok().ok_or("Source too long")?; }
+
+        let entry = KnowledgeEntry { id, text: text_str, embedding: embed_vec.clone(), source: source_str, importance };
+        let vec = MicroVector { data: embed_vec, id };
+        self.index.insert(&vec)?;
+        self.entries.push(entry).map_err(|_| "Entries full")?;
+        Ok(id)
+    }
+
+    pub fn retrieve(&self, query_embedding: &[i8]) -> RAGResult {
+        let results = self.index.search(query_embedding, self.config.top_k * 2);
+        let mut entries: HVec<(KnowledgeEntry, i32), 8> = HVec::new();
+
+        for result in results.iter() {
+            if result.distance > self.config.relevance_threshold { continue; }
+            if let Some(entry) = self.entries.iter().find(|e| e.id == result.id) {
+                let score = self.compute_score(result.distance, entry.importance);
+                let _ = entries.push((entry.clone(), score));
+            }
+        }
+
+        if self.config.rerank {
+            entries.sort_by(|a, b| b.1.cmp(&a.1));
+        }
+        while entries.len() > self.config.top_k { entries.pop(); }
+
+        let context = self.build_context(&entries);
+        let confidence = self.compute_confidence(&entries);
+
+        RAGResult { entries, context, confidence }
+    }
+
+    pub fn query(&self, query_embedding: &[i8]) -> Option<&str> {
+        let results = self.index.search(query_embedding, 1);
+        if let Some(result) = results.first() {
+            if result.distance <= self.config.relevance_threshold {
+                return self.entries.iter().find(|e| e.id == result.id).map(|e| e.text.as_str());
+            }
+        }
+        None
+    }
+
+    fn compute_score(&self, distance: i32, importance: u8) -> i32 {
+        let dist_score = 1000 - distance.min(1000);
+        let imp_score = importance as i32 * 4;
+        (dist_score * 3 + imp_score) / 4
+    }
+
+    fn build_context(&self, entries: &HVec<(KnowledgeEntry, i32), 8>) -> HString<256> {
+        let mut ctx = HString::new();
+        for (entry, _) in entries.iter().take(3) {
+            if ctx.len() + entry.text.len() + 2 > 256 { break; }
+            for c in entry.text.chars() { let _ = ctx.push(c); }
+            let _ = ctx.push(' ');
+        }
+        ctx
+    }
+
+    fn compute_confidence(&self, entries: &HVec<(KnowledgeEntry, i32), 8>) -> u8 {
+        if entries.is_empty() { return 0; }
+        let avg_score: i32 = entries.iter().map(|(_, s)| *s).sum::<i32>() / entries.len() as i32;
+        ((avg_score * 255) / 1000).clamp(0, 255) as u8
+    }
+
+    pub fn remove(&mut self, id: u32) -> bool {
+        if let Some(pos) = self.entries.iter().position(|e| e.id == id) {
+            self.entries.swap_remove(pos);
+            true
+        } else { false }
+    }
+}
+
+impl Default for MicroRAG { fn default() -> Self { Self::new(RAGConfig::default()) } }

examples/ruvLLM/esp32-flash/src/ruvector/semantic_memory.rs

@@ -0,0 +1,156 @@
+//! Semantic Memory - Context-Aware AI Memory for ESP32
+
+use heapless::Vec as HVec;
+use heapless::String as HString;
+use super::{MicroHNSW, HNSWConfig, MicroVector, DistanceMetric};
+
+pub const MAX_MEMORIES: usize = 128;
+pub const MAX_TEXT_LEN: usize = 64;
+pub const MEMORY_DIM: usize = 32;
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum MemoryType {
+    Preference,
+    Fact,
+    Event,
+    Procedure,
+    Entity,
+    Emotion,
+    Context,
+    State,
+}
+
+impl MemoryType {
+    pub fn priority(&self) -> i32 {
+        match self {
+            Self::State => 100, Self::Context => 90, Self::Preference => 80, Self::Emotion => 70,
+            Self::Procedure => 60, Self::Fact => 50, Self::Event => 40, Self::Entity => 30,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct Memory {
+    pub id: u32,
+    pub memory_type: MemoryType,
+    pub timestamp: u32,
+    pub text: HString<MAX_TEXT_LEN>,
+    pub importance: u8,
+    pub access_count: u16,
+    pub embedding: HVec<i8, MEMORY_DIM>,
+}
+
+impl Memory {
+    pub fn new(id: u32, memory_type: MemoryType, text: &str, embedding: &[i8], timestamp: u32) -> Option<Self> {
+        let mut text_str = HString::new();
+        for c in text.chars().take(MAX_TEXT_LEN) { text_str.push(c).ok()?; }
+        let mut embed_vec = HVec::new();
+        for &v in embedding.iter().take(MEMORY_DIM) { embed_vec.push(v).ok()?; }
+        Some(Self { id, memory_type, timestamp, text: text_str, importance: 50, access_count: 0, embedding: embed_vec })
+    }
+
+    pub fn relevance_score(&self, distance: i32, current_time: u32) -> i32 {
+        let type_weight = self.memory_type.priority();
+        let importance_weight = self.importance as i32;
+        let age = current_time.saturating_sub(self.timestamp);
+        let recency = 100 - (age / 3600).min(100) as i32;
+        let frequency = (self.access_count as i32).min(50);
+        let distance_score = 1000 - distance.min(1000);
+        (distance_score * 3 + type_weight * 2 + importance_weight + recency + frequency) / 7
+    }
+}
+
+pub struct SemanticMemory {
+    index: MicroHNSW<MEMORY_DIM, MAX_MEMORIES>,
+    memories: HVec<Memory, MAX_MEMORIES>,
+    next_id: u32,
+    current_time: u32,
+}
+
+impl SemanticMemory {
+    pub fn new() -> Self {
+        let config = HNSWConfig { m: 4, m_max0: 8, ef_construction: 16, ef_search: 8, metric: DistanceMetric::Euclidean, binary_mode: false };
+        Self { index: MicroHNSW::new(config), memories: HVec::new(), next_id: 0, current_time: 0 }
+    }
+
+    pub fn set_time(&mut self, time: u32) { self.current_time = time; }
+    pub fn len(&self) -> usize { self.memories.len() }
+    pub fn is_empty(&self) -> bool { self.memories.is_empty() }
+    pub fn memory_bytes(&self) -> usize { self.index.memory_bytes() + self.memories.len() * core::mem::size_of::<Memory>() }
+
+    pub fn remember(&mut self, memory_type: MemoryType, text: &str, embedding: &[i8]) -> Result<u32, &'static str> {
+        if self.memories.len() >= MAX_MEMORIES { self.evict_least_important()?; }
+
+        let id = self.next_id;
+        self.next_id += 1;
+
+        let memory = Memory::new(id, memory_type, text, embedding, self.current_time).ok_or("Failed to create memory")?;
+        let vec = MicroVector { data: memory.embedding.clone(), id };
+        self.index.insert(&vec)?;
+        self.memories.push(memory).map_err(|_| "Memory full")?;
+        Ok(id)
+    }
+
+    pub fn recall(&mut self, query: &[i8], k: usize) -> HVec<(Memory, i32), 16> {
+        let mut results = HVec::new();
+        let search_results = self.index.search(query, k * 2);
+
+        for result in search_results.iter() {
+            if let Some(memory) = self.find_by_id(result.id) {
+                let score = memory.relevance_score(result.distance, self.current_time);
+                let _ = results.push((memory.clone(), score));
+            }
+        }
+
+        results.sort_by(|a, b| b.1.cmp(&a.1));
+        for (mem, _) in results.iter() { self.increment_access(mem.id); }
+        while results.len() > k { results.pop(); }
+        results
+    }
+
+    pub fn recall_by_type(&mut self, query: &[i8], memory_type: MemoryType, k: usize) -> HVec<Memory, 16> {
+        let all = self.recall(query, k * 3);
+        let mut filtered = HVec::new();
+        for (mem, _) in all {
+            if mem.memory_type == memory_type && filtered.len() < k { let _ = filtered.push(mem); }
+        }
+        filtered
+    }
+
+    pub fn recent(&self, k: usize) -> HVec<&Memory, 16> {
+        let mut sorted: HVec<&Memory, MAX_MEMORIES> = self.memories.iter().collect();
+        sorted.sort_by(|a, b| b.timestamp.cmp(&a.timestamp));
+        let mut result = HVec::new();
+        for mem in sorted.iter().take(k) { let _ = result.push(*mem); }
+        result
+    }
+
+    pub fn forget(&mut self, id: u32) -> bool {
+        if let Some(pos) = self.memories.iter().position(|m| m.id == id) {
+            self.memories.swap_remove(pos);
+            true
+        } else { false }
+    }
+
+    fn find_by_id(&self, id: u32) -> Option<&Memory> { self.memories.iter().find(|m| m.id == id) }
+
+    fn increment_access(&mut self, id: u32) {
+        if let Some(m) = self.memories.iter_mut().find(|m| m.id == id) {
+            m.access_count = m.access_count.saturating_add(1);
+        }
+    }
+
+    fn evict_least_important(&mut self) -> Result<(), &'static str> {
+        if self.memories.is_empty() { return Ok(()); }
+        let mut min_score = i32::MAX;
+        let mut min_idx = 0;
+        for (i, mem) in self.memories.iter().enumerate() {
+            let score = mem.relevance_score(0, self.current_time);
+            if score < min_score { min_score = score; min_idx = i; }
+        }
+        self.memories.swap_remove(min_idx);
+        Ok(())
+    }
+}
+
+impl Default for SemanticMemory { fn default() -> Self { Self::new() } }