feat: add terraphim_router and terraphim_spawner crates for unified LLM/agent routing

* feat: Add terraphim_router crate for unified LLM and Agent routing

This commit adds a new terraphim_router crate that provides capability-based
routing for both LLM models and spawned agents using the same routing logic.

Features:
- KeywordRouter: Extracts capabilities from prompts using keyword matching
- RoutingEngine: Main routing logic with fallback handling
- 4 Routing Strategies: CostOptimized, LatencyOptimized, CapabilityFirst, RoundRobin
- ProviderRegistry: Loads providers from markdown files with YAML frontmatter
- Capability Types: DeepThinking, CodeGeneration, SecurityAudit, etc.

Also adds capability module to terraphim_types with:
- Capability enum for capability types
- Provider struct for unified LLM/Agent providers
- ProviderType enum distinguishing LLM vs Agent
- CostLevel and Latency enums for optimization

All code is edition2021 compatible and includes comprehensive unit tests.

* feat: Add terraphim_spawner crate for agent process management

This crate provides functionality to spawn external AI agents as non-interactive
processes with health checking, output capture, and @mention detection.

Features:
- AgentSpawner: Spawn agents from Provider configuration
- AgentValidator: Validate CLI exists, API keys set, working directory valid
- HealthChecker: 30s interval health checks with status tracking
- OutputCapture: Capture stdout/stderr with @mention detection
- Auto-restart on failure (configurable)

Supports agents:
- Claude Code (claude)
- OpenCode (opencode)
- Codex (codex)
- Custom agents via CLI command

All code includes comprehensive unit tests.

* feat: Add unified routing example and complete integration

- Add unified_routing.rs example showing LLM + Agent routing
- Demonstrates capability-based routing with different strategies
- Shows how Router and AgentSpawner work together
- Update Cargo.toml with dev-dependencies for examples

This completes Phase 3: Integration between terraphim_router and terraphim_spawner.

* docs: Add comprehensive README for unified routing

- Architecture overview
- Quick start guide
- Provider configuration examples
- Routing strategies documentation
- Testing instructions

* feat: Add @mention routing and integration tests

- Add MentionRouter for decentralized agent coordination
- Agents can route messages via @mentions in output
- Add integration tests for unified routing
- Test LLM vs Agent provider selection
- Test capability-based routing with cost optimization

* feat: Add fallback, metrics, and knowledge graph integration

- FallbackRouter with multiple fallback strategies
  - NextBestProvider, LlmFallback, Retry, FailFast
  - Configurable max fallback attempts
  - Automatic retry with provider exclusion

- RouterMetrics for observability
  - Routing request/success/failure counts
  - Spawn attempt/success/failure counts
  - Health failure tracking
  - Structured logging with targets

- KnowledgeGraphRouter for smart routing
  - Term expansion using thesauri
  - Role-based concept lookup
  - Provider relevance scoring
  - Related concept discovery

All modules include comprehensive unit tests.

* feat: Add advanced routing example

Demonstrates:
- Fallback routing with NextBestProvider strategy
- Metrics collection and reporting
- Knowledge graph term expansion
- LLM fallback when agent fails
- Complete metrics summary output

Author: kimiko-terraphim

crates/terraphim_router/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "terraphim_router"
+version = "1.8.0"
+edition = "2021"
+authors = ["Terraphim Team"]
+description = "Unified routing engine for LLM and Agent providers"
+license = "Apache-2.0"
+repository = "https://github.com/terraphim/terraphim-ai"
+
+[dependencies]
+# Terraphim internal crates
+terraphim_types = { path = "../terraphim_types", version = "1.8.0" }
+
+# Core dependencies
+serde = { version = "1.0", features = ["derive"] }
+serde_yaml = "0.9"
+serde_json = "1.0"
+regex = "1.10"
+thiserror = "1.0"
+anyhow = "1.0"
+log = "0.4"
+chrono = { version = "0.4", features = ["serde"] }
+tokio = { version = "1.0", features = ["full"] }
+async-trait = "0.1"
+uuid = { version = "1.0", features = ["v4", "serde"] }
+dirs = "5.0"
+
+[dev-dependencies]
+tokio-test = "0.4"
+tempfile = "3.8"
+terraphim_spawner = { path = "../terraphim_spawner", version = "1.8.0" }

crates/terraphim_router/README.md

@@ -0,0 +1,138 @@
+# Unified Routing for Terraphim
+
+This directory contains the unified routing system for Terraphim AI, providing capability-based routing for both LLM providers and spawned agents.
+
+## Crates
+
+### terraphim_router
+Capability-based routing engine that routes tasks to the best provider based on:
+- Keyword extraction from prompts
+- Provider capabilities
+- Routing strategies (cost, latency, capability match)
+
+### terraphim_spawner
+Agent process spawner with:
+- CLI validation
+- API key checking
+- Health monitoring (30s heartbeat)
+- Output capture with @mention detection
+- Auto-restart on failure
+
+### terraphim_types (updated)
+Added capability types:
+- `Capability` enum (DeepThinking, CodeGeneration, etc.)
+- `Provider` struct (unified LLM/Agent)
+- `ProviderType` enum (Llm vs Agent)
+- `CostLevel` and `Latency` enums
+
+## Quick Start
+
+```rust
+use terraphim_router::{Router, RoutingContext};
+use terraphim_types::capability::{
+    Capability, Provider, ProviderType, CostLevel, Latency
+};
+use std::path::PathBuf;
+
+// Create router
+let mut router = Router::new();
+
+// Register LLM provider
+router.add_provider(Provider::new(
+    "claude-opus",
+    "Claude Opus",
+    ProviderType::Llm {
+        model_id: "claude-3-opus-20240229".to_string(),
+        api_endpoint: "https://api.anthropic.com/v1".to_string(),
+    },
+    vec![Capability::DeepThinking, Capability::CodeGeneration],
+));
+
+// Register agent provider
+router.add_provider(Provider::new(
+    "@codex",
+    "Codex Agent",
+    ProviderType::Agent {
+        agent_id: "@codex".to_string(),
+        cli_command: "opencode".to_string(),
+        working_dir: PathBuf::from("/workspace"),
+    },
+    vec![Capability::CodeGeneration],
+));
+
+// Route a task
+let decision = router.route(
+    "Implement a function to parse JSON",
+    &RoutingContext::default(),
+)?;
+
+println!("Routed to: {}", decision.provider.name);
+```
+
+## Provider Configuration
+
+Providers can be configured via markdown files with YAML frontmatter:
+
+```markdown
+---
+id: "claude-opus"
+name: "Claude Opus"
+type: "llm"
+model_id: "claude-3-opus-20240229"
+api_endpoint: "https://api.anthropic.com/v1"
+capabilities:
+  - deep-thinking
+  - code-generation
+cost: expensive
+latency: slow
+keywords:
+  - think
+  - reason
+---
+
+# Claude Opus
+
+Anthropic's most capable model.
+```
+
+## Routing Strategies
+
+- **CostOptimized**: Select cheapest provider
+- **LatencyOptimized**: Select fastest provider
+- **CapabilityFirst**: Select provider with most capabilities
+- **RoundRobin**: Distribute load evenly
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   User Prompt   │────▶│  KeywordRouter   │────▶│  Capabilities   │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                                                          │
+                                                          ▼
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  LLM Provider   │◀────│  RoutingEngine   │◀────│  ProviderRegistry│
+│  (API call)     │     │  (Strategy)      │     │  (Filtered)      │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                              │
+                              ▼
+┌─────────────────┐     ┌──────────────────┐
+│  Agent Process  │◀────│  AgentSpawner    │
+│  (Spawned)      │     │  (Health + I/O)  │
+└─────────────────┘     └──────────────────┘
+```
+
+## Testing
+
+```bash
+cargo test -p terraphim_router
+cargo test -p terraphim_spawner
+```
+
+## Examples
+
+See `terraphim_router/examples/unified_routing.rs` for a complete example.
+
+## License
+
+Apache-2.0

crates/terraphim_router/examples/advanced_routing.rs

@@ -0,0 +1,149 @@
+//! Example: Advanced routing with fallback, metrics, and knowledge graph
+//!
+//! This example demonstrates:
+//! - Fallback routing when providers fail
+//! - Metrics collection
+//! - Knowledge graph integration for term expansion
+
+use std::path::PathBuf;
+use terraphim_router::{
+    FallbackRouter, FallbackStrategy, KnowledgeGraphRouter,
+    Router, RouterMetrics, RoutingContext, Timer,
+};
+use terraphim_types::capability::{
+    Capability, CostLevel, Latency, Provider, ProviderType,
+};
+use terraphim_types::{NormalizedTerm, NormalizedTermValue, RoleName, Thesaurus};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    println!("=== Advanced Unified Routing Example ===\n");
+
+    // Create metrics collector
+    let metrics = RouterMetrics::new();
+
+    // Create base router
+    let mut router = Router::new();
+
+    // Register providers
+    router.add_provider(Provider::new(
+        "gpt-4",
+        "GPT-4",
+        ProviderType::Llm {
+            model_id: "gpt-4".to_string(),
+            api_endpoint: "https://api.openai.com".to_string(),
+        },
+        vec![Capability::DeepThinking, Capability::CodeGeneration],
+    ).with_cost(CostLevel::Expensive));
+
+    router.add_provider(Provider::new(
+        "@codex",
+        "Codex Agent",
+        ProviderType::Agent {
+            agent_id: "@codex".to_string(),
+            cli_command: "opencode".to_string(),
+            working_dir: PathBuf::from("/workspace"),
+        },
+        vec![Capability::CodeGeneration],
+    ).with_cost(CostLevel::Cheap));
+
+    // Example 1: Fallback routing
+    println!("=== Example 1: Fallback Routing ===");
+    let fallback_router = FallbackRouter::new(router.clone())
+        .with_strategy(FallbackStrategy::NextBestProvider)
+        .with_max_fallbacks(3);
+
+    let timer = Timer::start();
+    let result = fallback_router
+        .route_with_fallback(
+            "Implement a function",
+            &RoutingContext::default(),
+            |provider| async move {
+                println!("  Trying provider: {}", provider.id);
+                // Simulate failure for first provider
+                if provider.id == "gpt-4" {
+                    Err("API rate limited".to_string())
+                } else {
+                    Ok(())
+                }
+            },
+        )
+        .await;
+
+    match result {
+        Ok(decision) => {
+            println!("  ✓ Successfully routed to: {}", decision.provider.id);
+            metrics.record_routing_request(&decision.provider,
+                timer.elapsed_ms()
+            );
+        }
+        Err(e) => {
+            println!("  ✗ Routing failed: {}", e);
+            metrics.record_routing_failure("all_providers_failed");
+        }
+    }
+
+    // Example 2: Knowledge graph term expansion
+    println!("\n=== Example 2: Knowledge Graph Integration ===");
+    let mut kg_router = KnowledgeGraphRouter::new()
+        .with_default_role(RoleName::new("engineer"));
+
+    // Create a thesaurus with synonyms
+    let mut thesaurus = Thesaurus::new("programming".to_string());
+    let mut term = NormalizedTerm::new(
+        1,
+        NormalizedTermValue::from("rust"),
+    );
+    term.synonyms.push(NormalizedTermValue::from("rustlang"));
+    term.synonyms.push(NormalizedTermValue::from("rust-lang"));
+    thesaurus.insert(
+        NormalizedTermValue::from("rust"),
+        term,
+    );
+
+    kg_router.add_thesaurus(RoleName::new("engineer"), thesaurus);
+
+    let terms = vec![NormalizedTermValue::from("rust")];
+    let expanded = kg_router.expand_terms(
+        &terms,
+        Some(&RoleName::new("engineer")),
+    );
+
+    println!("  Original terms: {:?}", terms);
+    println!("  Expanded terms: {:?}", expanded);
+
+    // Example 3: LLM fallback when agent fails
+    println!("\n=== Example 3: LLM Fallback Strategy ===");
+    let llm_fallback_router = FallbackRouter::new(router.clone())
+        .with_strategy(FallbackStrategy::LlmFallback);
+
+    let result = llm_fallback_router
+        .route_with_fallback(
+            "Think deeply about system design",
+            &RoutingContext::default(),
+            |provider| async move {
+                match &provider.provider_type {
+                    ProviderType::Agent { .. } => {
+                        println!("  Agent {} failed to spawn", provider.id);
+                        Err("Spawn failed".to_string())
+                    }
+                    ProviderType::Llm { model_id, .. } => {
+                        println!("  LLM {} succeeded", model_id);
+                        Ok(())
+                    }
+                }
+            },
+        )
+        .await;
+
+    if let Ok(decision) = result {
+        println!("  ✓ Fallback to LLM: {}", decision.provider.id);
+    }
+
+    // Print metrics summary
+    println!("\n=== Metrics Summary ===");
+    println!("{}", metrics);
+
+    println!("\n=== All Examples Complete ===");
+    Ok(())
+}