Advanced Core Features¶

Advanced routing capabilities including policy enforcement, intent detection, and deterministic routing.

Policy Module¶

The Policy module (core/policy/mod.rs) provides fine-grained control over routing decisions through configurable policies that enforce cost, compliance, and performance requirements.

Overview¶

use stratarouter_core::policy::{RoutingPolicy, CostPolicy, CompliancePolicy, PerformancePolicy};

// Create a strict enterprise policy
let policy = RoutingPolicy::enterprise();

// Or customize your own
let custom_policy = RoutingPolicy {
    min_confidence: 0.90,
    allow_fallback: true,
    require_human_review: false,
    cost_policy: CostPolicy {
        max_cost_per_request: 0.05,
        max_cost_per_hour: Some(50.0),
        preferred_tier: CostTier::Standard,
    },
    compliance: CompliancePolicy {
        allowed_regions: vec!["US".to_string(), "EU".to_string()],
        required_certifications: vec!["SOC2".to_string()],
        allow_cloud: true,
        blocked_providers: vec![],
    },
    performance: PerformancePolicy {
        max_latency_ms: 3000,
        min_throughput: Some(20.0),
        optimize_for_speed: false,
    },
};

Cost Policies¶

Control routing costs with multiple enforcement levels:

#[derive(Debug, Clone, Copy)]
pub enum CostTier {
    Free,       // Free models only
    Budget,     // < $0.01 per request
    Standard,   // < $0.10 per request
    Premium,    // Unlimited
}

let cost_policy = CostPolicy {
    max_cost_per_request: 0.10,
    max_cost_per_hour: Some(100.0),
    preferred_tier: CostTier::Standard,
};

Compliance Policies¶

Enforce data residency and certification requirements:

let compliance = CompliancePolicy {
    allowed_regions: vec!["US".to_string(), "EU".to_string()],
    required_certifications: vec!["SOC2".to_string(), "HIPAA".to_string()],
    allow_cloud: true,
    blocked_providers: vec!["provider_x".to_string()],
};

Performance Policies¶

Set latency and throughput requirements:

let performance = PerformancePolicy {
    max_latency_ms: 5000,
    min_throughput: Some(10.0),
    optimize_for_speed: true,
};

Policy Validation¶

Validate routing decisions against policies:

let result = policy.validate(
    confidence: 0.92,
    cost_usd: 0.03,
    provider: "openai",
    region: "US",
    latency_ms: 1200,
);

match result {
    Ok(()) => println!("Route passes all policies"),
    Err(violations) => {
        for violation in violations {
            match violation {
                PolicyViolation::ConfidenceTooLow { actual, required } => {
                    println!("Confidence {} below required {}", actual, required);
                }
                PolicyViolation::CostExceeded { actual, limit } => {
                    println!("Cost ${} exceeds limit ${}", actual, limit);
                }
                PolicyViolation::ComplianceViolation { reason } => {
                    println!("Compliance violation: {}", reason);
                }
                _ => {}
            }
        }
    }
}

Policy Registry¶

Manage multiple named policies for different contexts:

use stratarouter_core::policy::PolicyRegistry;

let mut registry = PolicyRegistry::new(RoutingPolicy::permissive());

// Register different policies for different use cases
registry.register("production".to_string(), RoutingPolicy::enterprise());
registry.register("development".to_string(), RoutingPolicy::permissive());
registry.register("high-security".to_string(), RoutingPolicy {
    min_confidence: 0.95,
    require_human_review: true,
    // ...other strict settings
});

// Retrieve policy by name
let policy = registry.get(Some("production"));

Pre-built Policies¶

Permissive Policy (Development/Testing): - No confidence threshold - Unlimited cost - All regions allowed - No compliance requirements

Enterprise Policy (Production): - 85% minimum confidence - $0.10 max per request - $100 max per hour - US/EU regions only - SOC2 certification required - 5 second latency limit

Intent Detection Module¶

The Intent module (core/intent/mod.rs) provides formal intent definitions and classification for routing decisions.

Intent Definition¶

use stratarouter_core::intent::{Intent, IntentConstraints, SensitivityLevel};

let intent = Intent {
    id: "classify_document".to_string(),
    description: "Classify documents into categories".to_string(),
    examples: vec![
        "Is this email spam?".to_string(),
        "What category is this document?".to_string(),
    ],
    constraints: Some(IntentConstraints {
        min_confidence: 0.85,
        sensitivity: SensitivityLevel::Internal,
        requires_human_review: false,
        max_cost_usd: Some(0.05),
    }),
    tags: vec!["nlp".to_string(), "classification".to_string()],
};

Sensitivity Levels¶

Control data handling based on intent sensitivity:

pub enum SensitivityLevel {
    Public,        // Can use any provider
    Internal,      // Must use private models
    Confidential,  // Requires on-premises deployment
    Restricted,    // HIPAA/PCI compliance needed
}

Intent Registry¶

Manage and classify intents:

use stratarouter_core::intent::IntentRegistry;

let mut registry = IntentRegistry::new();

// Register intents
registry.register(Intent {
    id: "customer_support".to_string(),
    description: "Answer customer support questions".to_string(),
    examples: vec!["How do I reset my password?".to_string()],
    constraints: Some(IntentConstraints {
        min_confidence: 0.80,
        sensitivity: SensitivityLevel::Public,
        requires_human_review: false,
        max_cost_usd: Some(0.02),
    }),
    tags: vec!["support".to_string()],
}).unwrap();

// Classify user input
let input = "How do I reset my password?";
if let Some(intent) = registry.classify(input) {
    println!("Detected intent: {}", intent.id);
    println!("Sensitivity: {:?}", intent.constraints.unwrap().sensitivity);
}

// Find intents by tag
let nlp_intents = registry.by_tag("nlp");

Built-in Intents¶

The registry comes with common intents pre-registered:

classify_text: Text classification and categorization
generate_code: Source code generation
answer_question: Question answering
summarize: Text summarization
translate: Language translation

Determinism Module¶

The Determinism module (core/determinism/mod.rs) enables reproducible routing decisions for testing, debugging, and compliance.

Routing Snapshots¶

Capture complete routing state for reproducibility:

use stratarouter_core::determinism::{RoutingSnapshot, RouteSnapshot, PerformanceSnapshot};

// Create snapshot of current state
let snapshot = RoutingSnapshot::create(
    core_version: "1.0.0".to_string(),
    intents: vec![/* intent snapshots */],
    policies: HashMap::new(),
    routes: vec![
        RouteSnapshot {
            route_id: "billing".to_string(),
            provider: "openai".to_string(),
            model: "gpt-4".to_string(),
            confidence_baseline: 0.92,
            cost_baseline: 0.03,
        },
    ],
    performance: HashMap::new(),
);

// Verify snapshot integrity
assert!(snapshot.verify());

// Export for storage
let json = snapshot.export_json().unwrap();

// Import later for replay
let restored = RoutingSnapshot::import_json(&json).unwrap();

Deterministic Routing¶

Route with reproducibility guarantees:

use stratarouter_core::determinism::{DeterministicRouter, DeterministicConfig};

// Option 1: Use fixed seed for reproducible randomness
let config = DeterministicConfig::with_seed(42);
let router = DeterministicRouter::new(config);

let result1 = router.route_deterministic("test input", "intent_id");
let result2 = router.route_deterministic("test input", "intent_id");

assert_eq!(result1.confidence, result2.confidence); // Identical

// Option 2: Use frozen snapshot
let config = DeterministicConfig::with_snapshot(snapshot);
let router = DeterministicRouter::new(config);

let result = router.route_deterministic("input", "intent_id");
// Uses baseline values from snapshot

Configuration Options¶

pub struct DeterministicConfig {
    /// Random seed for reproducible routing
    pub seed: Option<u64>,

    /// Use specific snapshot for frozen state
    pub snapshot: Option<RoutingSnapshot>,

    /// Disable any non-deterministic features
    pub strict_mode: bool,
}

// Disabled (production mode)
let config = DeterministicConfig::disabled();

// With seed (testing)
let config = DeterministicConfig::with_seed(12345);

// With snapshot (compliance/debugging)
let config = DeterministicConfig::with_snapshot(my_snapshot);

Use Cases¶

Testing:

// Same seed = same routing decisions
let config = DeterministicConfig::with_seed(42);
let router = DeterministicRouter::new(config);

// All tests use identical routing logic
#[test]
fn test_routing_behavior() {
    let result = router.route_deterministic("input", "intent");
    assert_eq!(result.confidence, 0.87); // Reproducible
}

Debugging:

// Capture state when bug occurred
let snapshot = capture_state_at_incident();
let config = DeterministicConfig::with_snapshot(snapshot);
let router = DeterministicRouter::new(config);

// Replay exact routing decisions
let result = router.route_deterministic(incident_input, incident_intent);
// Debugging with exact historical state

Compliance:

// Save snapshot for audit trail
let snapshot = RoutingSnapshot::create(/* ... */);
snapshot.export_json().unwrap();

// Later: prove routing behavior was compliant
let historical_snapshot = RoutingSnapshot::import_json(&audit_data).unwrap();
assert!(historical_snapshot.verify()); // Cryptographic integrity

Snapshot Integrity¶

Snapshots use SHA-256 hashing for tamper detection:

let snapshot = RoutingSnapshot::create(/* ... */);

// Hash is computed on creation
println!("Snapshot hash: {}", snapshot.snapshot_hash);

// Verify integrity
if snapshot.verify() {
    println!("Snapshot is authentic");
} else {
    println!("WARNING: Snapshot has been modified!");
}

// Modification detection
let mut modified = snapshot.clone();
modified.core_version = "2.0.0".to_string();
assert!(!modified.verify()); // Hash mismatch

AVX2 Hardware Detection¶

Check CPU capabilities for SIMD optimization:

use stratarouter_core::has_avx2;

if has_avx2() {
    println!("AVX2 acceleration available");
    println!("Similarity computations will be 2-4x faster");
} else {
    println!("Using scalar fallback (still fast!)");
}

// Automatically handled internally
let similarity = cosine_similarity(&vec1, &vec2);
// Uses AVX2 if available, scalar otherwise

This function is implemented in src/lib.rs:

#[cfg(target_arch = "x86_64")]
pub fn has_avx2() -> bool {
    is_x86_feature_detected!("avx2")
}

#[cfg(not(target_arch = "x86_64"))]
pub const fn has_avx2() -> bool {
    false
}

Integration Example¶

Combining all advanced features:

use stratarouter_core::*;
use policy::{RoutingPolicy, PolicyRegistry};
use intent::{IntentRegistry, Intent};
use determinism::{DeterministicConfig, DeterministicRouter};

// 1. Set up policy registry
let mut policies = PolicyRegistry::new(RoutingPolicy::permissive());
policies.register("production".to_string(), RoutingPolicy::enterprise());

// 2. Set up intent registry
let mut intents = IntentRegistry::default();
intents.register(Intent {
    id: "billing".to_string(),
    // ... intent configuration
}).unwrap();

// 3. Configure deterministic routing for testing
let config = DeterministicConfig::with_seed(42);
let router = DeterministicRouter::new(config);

// 4. Route with policy validation
let input = "Where is my invoice?";
let intent = intents.classify(input).unwrap();
let policy = policies.get(Some("production"));

let result = router.route_deterministic(input, &intent.id);

// Validate against policy
match policy.validate(
    result.confidence,
    result.estimated_cost,
    "openai",
    "US",
    100,
) {
    Ok(()) => {
        println!("✓ Route passes all policies");
        println!("  Route: {}", result.primary_route);
        println!("  Confidence: {}", result.confidence);
    }
    Err(violations) => {
        println!("✗ Policy violations detected");
        for v in violations {
            println!("  - {:?}", v);
        }
    }
}