claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
256 lines • 7.97 kB
TypeScript
/**
* Intelligent Model Router using Tiny Dancer
*
* Dynamically routes requests to optimal Claude model (haiku/sonnet/opus)
* based on task complexity, confidence scores, and historical performance.
*
* Features:
* - FastGRNN-based routing decisions (<100μs)
* - Uncertainty quantification for model escalation
* - Circuit breaker for failover
* - Online learning from routing outcomes
* - Complexity scoring via embeddings
*
* Routing Strategy:
* - Haiku: High confidence, low complexity (fast, cheap)
* - Sonnet: Medium confidence, moderate complexity (balanced)
* - Opus: Low confidence, high complexity (most capable)
*
* @module model-router
*/
/**
* Available Claude models for routing
*/
export type ClaudeModel = 'haiku' | 'sonnet' | 'opus' | 'inherit';
/**
* Model capabilities and characteristics
*/
export declare const MODEL_CAPABILITIES: Record<ClaudeModel, {
maxComplexity: number;
costMultiplier: number;
speedMultiplier: number;
description: string;
}>;
/**
* Complexity indicators for task classification
*/
export declare const COMPLEXITY_INDICATORS: {
high: string[];
medium: string[];
low: string[];
};
/**
* Model router configuration
*/
export interface ModelRouterConfig {
/** Confidence threshold for model selection (default: 0.85) */
confidenceThreshold: number;
/** Maximum uncertainty before escalating (default: 0.15) */
maxUncertainty: number;
/** Enable circuit breaker (default: true) */
enableCircuitBreaker: boolean;
/** Failures before circuit opens (default: 5) */
circuitBreakerThreshold: number;
/** Path for router state persistence */
statePath: string;
/** Auto-save interval in decisions (default: 20) */
autoSaveInterval: number;
/** Enable cost optimization (default: true) */
enableCostOptimization: boolean;
/** Prefer faster models when confidence is high (default: true) */
preferSpeed: boolean;
}
/**
* Routing decision result
*/
export interface ModelRoutingResult {
/** Selected model */
model: ClaudeModel;
/** Confidence in the decision (0-1) */
confidence: number;
/** Uncertainty estimate (0-1) */
uncertainty: number;
/** Computed complexity score (0-1) */
complexity: number;
/** Reasoning for the selection */
reasoning: string;
/** Alternative models considered */
alternatives: Array<{
model: ClaudeModel;
score: number;
}>;
/** Inference time in microseconds */
inferenceTimeUs: number;
/** Estimated cost multiplier */
costMultiplier: number;
}
/**
* Complexity analysis result
*/
export interface ComplexityAnalysis {
/** Overall complexity score (0-1) */
score: number;
/** Indicators found */
indicators: {
high: string[];
medium: string[];
low: string[];
};
/** Feature breakdown */
features: {
lexicalComplexity: number;
semanticDepth: number;
taskScope: number;
uncertaintyLevel: number;
};
}
/**
* Beta(α, β) prior for Thompson sampling. Each model carries one of these;
* outcomes update α (successes) and β (failures) so the router auto-balances
* cost/quality without manual threshold tuning. See ADR-101.
*/
export interface BetaPrior {
alpha: number;
beta: number;
}
/**
* Router state for persistence
*/
/**
* Complexity bucket for per-task bandit priors. Bands mirror
* MODEL_CAPABILITIES.maxComplexity (haiku 0.4, sonnet 0.7) so the taxonomy
* isn't arbitrary. Keying priors by bucket fixes the global-bandit defect where
* failures on one task type suppressed a model for ALL task types (audit
* docs/reviews/intelligence-system-audit-2026-05-29.md; see ADR-142).
*/
export type ComplexityBucket = 'low' | 'med' | 'high';
type BucketedPriors = Record<ComplexityBucket, Record<ClaudeModel, BetaPrior>>;
/**
* Intelligent Model Router using complexity-based routing
*/
export declare class ModelRouter {
private config;
private state;
private decisionCount;
private consecutiveFailures;
constructor(config?: Partial<ModelRouterConfig>);
/**
* Route a task to the optimal model
*/
route(task: string, embedding?: number[]): Promise<ModelRoutingResult>;
/**
* Analyze task complexity
*/
analyzeComplexity(task: string, embedding?: number[]): ComplexityAnalysis;
/**
* Compute lexical complexity from text features
*/
private computeLexicalComplexity;
/**
* Compute semantic depth from indicators and embedding
*/
private computeSemanticDepth;
/**
* Compute task scope from content analysis
*/
private computeTaskScope;
/**
* Compute uncertainty level from task phrasing
*/
private computeUncertaintyLevel;
/**
* Compute scores for each model
*/
private computeModelScores;
/**
* Apply circuit breaker adjustments
*/
private applyCircuitBreaker;
/**
* Select the best model from scores. Uses Thompson sampling (#1772):
* each model's deterministic complexity score is multiplied by a draw
* θ_m ~ Beta(α_m, β_m) from its bandit prior. Models with strong empirical
* track records get sampled higher; models with poor outcomes get sampled
* lower; the system auto-corrects against tier overuse without manual
* threshold tuning. Beta(1,1) = uniform on cold start so behavior matches
* the prior deterministic router until outcomes accumulate.
*/
private selectModel;
/**
* Build human-readable reasoning
*/
private buildReasoning;
/**
* Track routing decision for learning
*/
private trackDecision;
/**
* Record outcome for learning
*/
recordOutcome(task: string, model: ClaudeModel, outcome: 'success' | 'failure' | 'escalated'): void;
/**
* Get router statistics
*/
getStats(): {
totalDecisions: number;
modelDistribution: Record<ClaudeModel, number>;
avgComplexity: number;
avgConfidence: number;
circuitBreakerTrips: number;
consecutiveFailures: Record<ClaudeModel, number>;
};
/**
* Load state from disk
*/
private loadState;
/**
* Save state to disk
*/
private saveState;
/**
* Reset router state
*/
reset(): void;
/**
* Public read-only accessor for the bandit priors. Useful for tests,
* dashboards, and the pending hooks_intelligence_stats integration that
* surfaces convergence in the dashboard. Returns a copy.
*/
getBanditPriors(bucket?: ComplexityBucket): Record<ClaudeModel, BetaPrior>;
/** All bucketed priors (copy) — for dashboards/tests. */
getBucketedPriors(): BucketedPriors;
}
/**
* Get or create the singleton ModelRouter instance
*/
export declare function getModelRouter(config?: Partial<ModelRouterConfig>): ModelRouter;
/**
* Reset the singleton instance
*/
export declare function resetModelRouter(): void;
/**
* Create a new ModelRouter instance (non-singleton)
*/
export declare function createModelRouter(config?: Partial<ModelRouterConfig>): ModelRouter;
/**
* Quick route function for common use case
*/
export declare function routeToModel(task: string): Promise<ClaudeModel>;
/**
* Route with full result
*/
export declare function routeToModelFull(task: string, embedding?: number[]): Promise<ModelRoutingResult>;
/**
* Analyze task complexity without routing
*/
export declare function analyzeTaskComplexity(task: string): ComplexityAnalysis;
/**
* Get model router statistics
*/
export declare function getModelRouterStats(): ReturnType<ModelRouter['getStats']>;
/**
* Record routing outcome for learning
*/
export declare function recordModelOutcome(task: string, model: ClaudeModel, outcome: 'success' | 'failure' | 'escalated'): void;
export {};
//# sourceMappingURL=model-router.d.ts.map