titan-synapse 0.1.1

package/crates/synapse/src/swarm/orchestrator.rs

@@ -0,0 +1,225 @@
+use anyhow::Result;
+use futures::future::join_all;
+use crate::config::SynapseConfig;
+use crate::inference::{InferenceEngine, GenerationResult};
+use crate::learn::CloudFallback;
+use crate::memory::KnowledgeGraph;
+use crate::openai::Message;
+use super::coordinator::Coordinator;
+use super::synthesizer::Synthesizer;
+
+/// Top-level swarm orchestrator — decides single vs multi-specialist routing
+/// Uses Hebbian routing and parallel specialist execution for swarm mode
+/// Cloud fallback: when confidence is low, routes to cloud and learns from the response
+pub struct Orchestrator {
+    coordinator: Coordinator,
+    synthesizer: Synthesizer,
+    cloud_fallback: Option<CloudFallback>,
+}
+
+impl Orchestrator {
+    pub fn new(config: &SynapseConfig) -> Self {
+        Self {
+            coordinator: Coordinator::new(config),
+            synthesizer: Synthesizer::new(),
+            cloud_fallback: CloudFallback::new(&config.cloud),
+        }
+    }
+
+    /// Build context from full message history (not just last message)
+    fn build_context(messages: &[Message]) -> String {
+        if messages.len() <= 1 {
+            return messages.last().map(|m| m.content.clone()).unwrap_or_default();
+        }
+
+        // Include recent conversation context (last 4 messages max)
+        let recent: Vec<&Message> = messages.iter().rev().take(4).collect::<Vec<_>>().into_iter().rev().collect();
+        let mut context = String::new();
+        for msg in &recent[..recent.len().saturating_sub(1)] {
+            context.push_str(&format!("[{}]: {}\n", msg.role, msg.content));
+        }
+        // Last message is the actual query
+        if let Some(last) = recent.last() {
+            context.push_str(&last.content);
+        }
+        context
+    }
+
+    /// Process a chat request — route to specialist(s) and return response
+    pub async fn process(
+        &self,
+        messages: &[Message],
+        engine: &InferenceEngine,
+        max_tokens: Option<u32>,
+        temperature: Option<f32>,
+        knowledge: Option<&KnowledgeGraph>,
+    ) -> Result<GenerationResult> {
+        let last_message = messages.last()
+            .map(|m| m.content.as_str())
+            .unwrap_or("");
+
+        let context = Self::build_context(messages);
+        let max_tokens = max_tokens.unwrap_or(2048);
+        let temperature = temperature.unwrap_or(0.7);
+
+        let routing = self.coordinator.route(last_message, knowledge);
+
+        match routing {
+            RoutingDecision::Single { specialist, confidence } => {
+                tracing::info!("Routing to specialist: {specialist} (confidence: {confidence:.2})");
+
+                // Cloud fallback: if confidence is too low and cloud is available,
+                // generate locally first, then ask cloud and learn from the difference
+                let cloud_threshold = CloudFallback::confidence_threshold();
+                if confidence < cloud_threshold {
+                    if let Some(ref fallback) = self.cloud_fallback {
+                        tracing::info!(
+                            "⚡ Low confidence ({confidence:.2} < {cloud_threshold:.2}) — trying cloud fallback"
+                        );
+
+                        // Try local generation first (we still want the local attempt for DPO)
+                        let local_result = engine.generate(&context, Some(&specialist), max_tokens, temperature).await;
+                        let local_text = local_result.as_ref().ok().map(|r| r.text.as_str());
+
+                        // Ask cloud for the better answer
+                        if let Some(kg) = knowledge {
+                            match fallback.fallback(last_message, &specialist, local_text, kg).await {
+                                Ok(cloud_result) => {
+                                    tracing::info!(
+                                        "☁️ Cloud fallback used {}, learned={}",
+                                        cloud_result.model_used, cloud_result.learned
+                                    );
+                                    // Return the cloud's better response
+                                    return Ok(GenerationResult {
+                                        text: cloud_result.text,
+                                        prompt_tokens: 0,
+                                        completion_tokens: 0,
+                                        total_tokens: 0,
+                                        tok_per_sec: 0.0,
+                                        duration_ms: 0,
+                                    });
+                                }
+                                Err(e) => {
+                                    tracing::warn!("Cloud fallback failed: {e}, using local response");
+                                    // Fall through to local response
+                                }
+                            }
+                        }
+
+                        // Cloud failed, return local result if we have one
+                        if let Ok(result) = local_result {
+                            return Ok(result);
+                        }
+                    }
+                }
+
+                let result = engine.generate(&context, Some(&specialist), max_tokens, temperature).await?;
+
+                // Reinforce the pathway on successful generation
+                if let Some(kg) = knowledge {
+                    let _ = kg.reinforce_pathway(&[specialist.clone()], confidence);
+                    let _ = kg.update_specialist_stats(
+                        &specialist, "general", confidence, result.tok_per_sec,
+                    );
+                }
+
+                Ok(result)
+            }
+            RoutingDecision::Swarm { subtasks } => {
+                tracing::info!("⚡ Swarm mode: {} subtasks (PARALLEL)", subtasks.len());
+                let start = std::time::Instant::now();
+                let tokens_per_task = max_tokens / subtasks.len() as u32;
+
+                // Execute ALL subtasks in parallel
+                let futures: Vec<_> = subtasks.iter().map(|task| {
+                    let prompt = format!("Task: {}\n\nContext: {context}", task.description);
+                    let specialist = task.specialist.clone();
+                    async move {
+                        let result = engine.generate(
+                            &prompt,
+                            Some(&specialist),
+                            tokens_per_task,
+                            temperature,
+                        ).await;
+                        (specialist, result)
+                    }
+                }).collect();
+
+                let results = join_all(futures).await;
+
+                let mut texts = Vec::new();
+                let mut total_prompt = 0u32;
+                let mut total_completion = 0u32;
+                let mut specialists_used = Vec::new();
+
+                for (specialist, result) in results {
+                    match result {
+                        Ok(gen_result) => {
+                            total_prompt += gen_result.prompt_tokens;
+                            total_completion += gen_result.completion_tokens;
+                            specialists_used.push(specialist.clone());
+                            texts.push((specialist, gen_result.text));
+                        }
+                        Err(e) => {
+                            tracing::warn!("Specialist {specialist} failed: {e}");
+                            // Continue with other specialists — graceful degradation
+                        }
+                    }
+                }
+
+                if texts.is_empty() {
+                    return Err(anyhow::anyhow!("All specialists failed in swarm mode"));
+                }
+
+                let elapsed = start.elapsed();
+                let merged = self.synthesizer.merge(&texts)?;
+
+                // Reinforce the swarm pathway
+                if let Some(kg) = knowledge {
+                    let _ = kg.reinforce_pathway(&specialists_used, 4.0);
+                }
+
+                let tok_per_sec = if elapsed.as_secs_f64() > 0.0 {
+                    total_completion as f64 / elapsed.as_secs_f64()
+                } else {
+                    0.0
+                };
+
+                tracing::info!(
+                    "⚡ Swarm complete: {} specialists, {} tokens in {:.1}s ({:.1} tok/s)",
+                    specialists_used.len(), total_completion, elapsed.as_secs_f64(), tok_per_sec
+                );
+
+                Ok(GenerationResult {
+                    text: merged,
+                    prompt_tokens: total_prompt,
+                    completion_tokens: total_completion,
+                    total_tokens: total_prompt + total_completion,
+                    tok_per_sec,
+                    duration_ms: elapsed.as_millis() as u64,
+                })
+            }
+        }
+    }
+}
+
+pub enum RoutingDecision {
+    Single { specialist: String, confidence: f32 },
+    Swarm { subtasks: Vec<SubTask> },
+}
+
+pub struct SubTask {
+    pub specialist: String,
+    pub description: String,
+}
+
+impl std::fmt::Display for RoutingDecision {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            RoutingDecision::Single { specialist, confidence } => write!(f, "Single({specialist}, confidence={confidence:.2})"),
+            RoutingDecision::Swarm { subtasks } => {
+                write!(f, "Swarm({})", subtasks.iter().map(|t| t.specialist.as_str()).collect::<Vec<_>>().join(", "))
+            }
+        }
+    }
+}

package/crates/synapse/src/swarm/pool.rs

@@ -0,0 +1,64 @@
+use std::collections::HashMap;
+
+/// Manages the pool of active specialists and their LoRA adapters
+pub struct SpecialistPool {
+    /// Currently loaded specialists
+    loaded: HashMap<String, SpecialistState>,
+    /// Max specialists to keep loaded
+    max_loaded: usize,
+}
+
+pub struct SpecialistState {
+    pub name: String,
+    pub adapter_loaded: bool,
+    pub last_used: std::time::Instant,
+    pub request_count: u64,
+}
+
+impl SpecialistPool {
+    pub fn new(max_loaded: usize) -> Self {
+        Self {
+            loaded: HashMap::new(),
+            max_loaded,
+        }
+    }
+
+    /// Ensure a specialist is loaded, evicting LRU if necessary
+    pub fn ensure_loaded(&mut self, name: &str) -> bool {
+        if self.loaded.contains_key(name) {
+            if let Some(state) = self.loaded.get_mut(name) {
+                state.last_used = std::time::Instant::now();
+                state.request_count += 1;
+            }
+            return true;
+        }
+
+        // Need to load — evict LRU if at capacity
+        if self.loaded.len() >= self.max_loaded {
+            self.evict_lru();
+        }
+
+        self.loaded.insert(name.to_string(), SpecialistState {
+            name: name.to_string(),
+            adapter_loaded: false,
+            last_used: std::time::Instant::now(),
+            request_count: 1,
+        });
+
+        false // Was not loaded, needs adapter swap
+    }
+
+    fn evict_lru(&mut self) {
+        if let Some(oldest) = self.loaded.values()
+            .min_by_key(|s| s.last_used)
+            .map(|s| s.name.clone())
+        {
+            tracing::info!("Evicting LRU specialist: {oldest}");
+            self.loaded.remove(&oldest);
+        }
+    }
+
+    pub fn loaded_count(&self) -> usize {
+        self.loaded.len()
+    }
+}

package/crates/synapse/src/swarm/spawner.rs

@@ -0,0 +1,199 @@
+use anyhow::Result;
+use crate::memory::KnowledgeGraph;
+use crate::config::SpecialistConfig;
+
+/// Specialist Auto-Spawner — the system that creates new brain regions.
+///
+/// When the coordinator repeatedly routes to "general" for a domain,
+/// and the confidence is low, the spawner:
+/// 1. Detects the pattern ("many Python questions going to general")
+/// 2. Creates a new specialist config for that domain
+/// 3. Queues training data collection
+/// 4. Once enough data: triggers QLoRA training
+/// 5. New specialist joins the swarm automatically
+///
+/// The system literally grows new specialists as needed.
+/// A music producer will end up with audio_expert, midi_expert, mixing_expert.
+/// A data scientist will get pandas_expert, sklearn_expert, visualization_expert.
+/// No configuration needed. The system figures it out.
+pub struct SpecialistSpawner {
+    /// Minimum requests in a domain before considering spawning
+    min_requests: u32,
+    /// Maximum confidence score that triggers spawning (below this = specialist needed)
+    confidence_threshold: f32,
+    /// Domains that already have specialists (don't spawn duplicates)
+    covered_domains: Vec<String>,
+}
+
+/// A proposal for a new specialist
+#[derive(Debug, Clone)]
+pub struct SpawnProposal {
+    pub name: String,
+    pub domain: String,
+    pub capabilities: Vec<String>,
+    pub reason: String,
+    pub requests_in_domain: u32,
+    pub current_avg_score: f64,
+}
+
+impl SpecialistSpawner {
+    pub fn new(covered_domains: Vec<String>) -> Self {
+        Self {
+            min_requests: 5,
+            confidence_threshold: 3.0,
+            covered_domains,
+        }
+    }
+
+    /// Analyze the knowledge graph for domains that need specialists
+    pub fn detect_spawn_candidates(&self, kg: &KnowledgeGraph) -> Result<Vec<SpawnProposal>> {
+        let mut proposals = Vec::new();
+
+        // Get all specialist stats
+        let stats = kg.specialist_confidence_report().unwrap_or_default();
+
+        // Look for domains where "general" is handling too many requests with low scores
+        for stat in &stats {
+            let specialist = stat["specialist"].as_str().unwrap_or("");
+            let domain = stat["domain"].as_str().unwrap_or("");
+            let requests = stat["requests"].as_u64().unwrap_or(0) as u32;
+            let avg_score = stat["avg_score"].as_f64().unwrap_or(0.0);
+
+            // If general specialist is handling many requests in a specific domain
+            // with below-threshold scores, propose a new specialist
+            if specialist == "general"
+                && requests >= self.min_requests
+                && avg_score < self.confidence_threshold as f64
+                && !self.is_domain_covered(domain)
+            {
+                let capabilities = Self::infer_capabilities(domain);
+                let name = format!("{}_expert", domain.replace(' ', "_"));
+
+                proposals.push(SpawnProposal {
+                    name,
+                    domain: domain.to_string(),
+                    capabilities,
+                    reason: format!(
+                        "General specialist handling {} requests in '{}' domain with avg score {:.1} (below threshold {:.1})",
+                        requests, domain, avg_score, self.confidence_threshold
+                    ),
+                    requests_in_domain: requests,
+                    current_avg_score: avg_score,
+                });
+            }
+        }
+
+        // Also analyze conversation patterns for undetected domains
+        if let Ok(top_pathways) = kg.top_pathways(20) {
+            for (pathway, strength, avg_score) in &top_pathways {
+                if *strength > 3 && *avg_score < self.confidence_threshold as f64 {
+                    // This pathway is used often but scoring low
+                    if !self.is_domain_covered(pathway) {
+                        proposals.push(SpawnProposal {
+                            name: format!("{}_expert", pathway.replace('+', "_")),
+                            domain: pathway.clone(),
+                            capabilities: vec![pathway.clone()],
+                            reason: format!(
+                                "Pathway '{}' reinforced {} times but avg score only {:.1}",
+                                pathway, strength, avg_score
+                            ),
+                            requests_in_domain: *strength as u32,
+                            current_avg_score: *avg_score,
+                        });
+                    }
+                }
+            }
+        }
+
+        Ok(proposals)
+    }
+
+    /// Convert a spawn proposal into a specialist config
+    pub fn create_specialist_config(proposal: &SpawnProposal) -> SpecialistConfig {
+        SpecialistConfig {
+            name: proposal.name.clone(),
+            capabilities: proposal.capabilities.clone(),
+            base_model: None, // Use default base model
+            adapter: None,    // Will be trained
+            system_prompt: Some(format!(
+                "You are an expert in {}. Provide detailed, accurate answers in your domain of expertise.",
+                proposal.domain
+            )),
+            priority: 70, // Higher than general (50) but lower than existing experts
+        }
+    }
+
+    fn is_domain_covered(&self, domain: &str) -> bool {
+        self.covered_domains.iter().any(|d| {
+            d.to_lowercase().contains(&domain.to_lowercase())
+                || domain.to_lowercase().contains(&d.to_lowercase())
+        })
+    }
+
+    fn infer_capabilities(domain: &str) -> Vec<String> {
+        let domain_lower = domain.to_lowercase();
+        let mut caps = vec![domain.to_string()];
+
+        // Add related capabilities based on domain
+        let related: Vec<(&str, &[&str])> = vec![
+            ("python", &["debugging", "testing", "django", "flask", "fastapi"]),
+            ("javascript", &["react", "node", "typescript", "frontend"]),
+            ("sql", &["database", "query", "postgres", "mysql"]),
+            ("rust", &["systems", "memory", "concurrency", "cargo"]),
+            ("math", &["algebra", "calculus", "statistics", "probability"]),
+            ("science", &["physics", "chemistry", "biology"]),
+            ("writing", &["grammar", "style", "creative", "editing"]),
+            ("music", &["audio", "production", "mixing", "midi"]),
+            ("business", &["finance", "marketing", "strategy", "management"]),
+        ];
+
+        for (key, related_caps) in &related {
+            if domain_lower.contains(key) {
+                caps.extend(related_caps.iter().map(|s| s.to_string()));
+                break;
+            }
+        }
+
+        caps
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_infer_capabilities() {
+        let caps = SpecialistSpawner::infer_capabilities("python");
+        assert!(caps.contains(&"python".to_string()));
+        assert!(caps.contains(&"debugging".to_string()));
+    }
+
+    #[test]
+    fn test_is_domain_covered() {
+        let spawner = SpecialistSpawner::new(vec![
+            "python_expert".into(),
+            "sql_expert".into(),
+        ]);
+        assert!(spawner.is_domain_covered("python"));
+        assert!(spawner.is_domain_covered("sql"));
+        assert!(!spawner.is_domain_covered("music"));
+    }
+
+    #[test]
+    fn test_create_specialist_config() {
+        let proposal = SpawnProposal {
+            name: "music_expert".into(),
+            domain: "music production".into(),
+            capabilities: vec!["music".into(), "audio".into()],
+            reason: "test".into(),
+            requests_in_domain: 10,
+            current_avg_score: 2.5,
+        };
+
+        let config = SpecialistSpawner::create_specialist_config(&proposal);
+        assert_eq!(config.name, "music_expert");
+        assert_eq!(config.priority, 70);
+        assert!(config.system_prompt.unwrap().contains("music production"));
+    }
+}

package/crates/synapse/src/swarm/synthesizer.rs

@@ -0,0 +1,26 @@
+/// Merges outputs from multiple specialists into a coherent response
+pub struct Synthesizer;
+
+impl Synthesizer {
+    pub fn new() -> Self { Self }
+
+    /// Merge multiple specialist responses into one
+    pub fn merge(&self, results: &[(String, String)]) -> anyhow::Result<String> {
+        if results.is_empty() {
+            return Ok("No specialist responses to merge.".into());
+        }
+
+        if results.len() == 1 {
+            return Ok(results[0].1.clone());
+        }
+
+        // For now, concatenate with specialist attribution
+        // In production, this will use the coordinator model to synthesize
+        let mut output = String::new();
+        for (specialist, response) in results {
+            output.push_str(&format!("**[{specialist}]**\n{response}\n\n"));
+        }
+
+        Ok(output.trim().to_string())
+    }
+}

package/crates/synapse/src/vram/manager.rs

@@ -0,0 +1,67 @@
+use anyhow::Result;
+use serde::Serialize;
+
+#[derive(Debug, Serialize)]
+pub struct GpuInfo {
+    pub name: String,
+    pub vram_total_mb: u64,
+    pub vram_used_mb: u64,
+    pub vram_free_mb: u64,
+    pub utilization_percent: f32,
+    pub temperature_c: Option<u32>,
+}
+
+pub struct VramManager {
+    pub budget_mb: u64,
+}
+
+impl VramManager {
+    pub fn new(max_vram_mb: u64) -> Self {
+        Self {
+            budget_mb: if max_vram_mb > 0 { max_vram_mb } else { 32768 }, // Default 32GB
+        }
+    }
+
+    /// Get GPU info via nvidia-smi (works on both local and remote)
+    pub async fn gpu_info() -> Result<GpuInfo> {
+        // Try nvidia-smi first
+        let output = tokio::process::Command::new("nvidia-smi")
+            .args(["--query-gpu=name,memory.total,memory.used,memory.free,utilization.gpu,temperature.gpu", "--format=csv,noheader,nounits"])
+            .output()
+            .await;
+
+        match output {
+            Ok(out) if out.status.success() => {
+                let stdout = String::from_utf8_lossy(&out.stdout);
+                let parts: Vec<&str> = stdout.trim().split(", ").collect();
+                if parts.len() >= 6 {
+                    return Ok(GpuInfo {
+                        name: parts[0].to_string(),
+                        vram_total_mb: parts[1].parse().unwrap_or(0),
+                        vram_used_mb: parts[2].parse().unwrap_or(0),
+                        vram_free_mb: parts[3].parse().unwrap_or(0),
+                        utilization_percent: parts[4].parse().unwrap_or(0.0),
+                        temperature_c: parts[5].parse().ok(),
+                    });
+                }
+            }
+            _ => {}
+        }
+
+        // No GPU available
+        Ok(GpuInfo {
+            name: "No GPU detected".into(),
+            vram_total_mb: 0,
+            vram_used_mb: 0,
+            vram_free_mb: 0,
+            utilization_percent: 0.0,
+            temperature_c: None,
+        })
+    }
+
+    /// Calculate how much VRAM is available for Synapse
+    pub async fn available_vram(&self) -> Result<u64> {
+        let info = Self::gpu_info().await?;
+        Ok(info.vram_free_mb.min(self.budget_mb))
+    }
+}

package/crates/synapse/src/vram/mod.rs

@@ -0,0 +1,3 @@
+pub mod manager;
+
+pub use manager::VramManager;

package/docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  synapse-learn:
+    build:
+      context: ./python
+      dockerfile: Dockerfile.learn
+    ports:
+      - "8090:8090"
+    volumes:
+      - ~/.synapse:/root/.synapse
+    environment:
+      - SYNAPSE_DATA_DIR=/root/.synapse
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    restart: unless-stopped