Route AI tasks to the optimal model based on cost, latency, quality, or a balanced strategy.
SmartRouter
The SmartRouter selects the optimal AI model for each task based on configurable strategy weights (cost, latency, quality), budget constraints, capability requirements, and circuit breaker health. It maintains per-model circuit breakers to automatically exclude failing models.
import { SmartRouter } from '@codmir/cortex';Constructor
new SmartRouter(models: ModelProfile[], config?: Partial<SmartRouterConfig>)| Parameter | Type | Description |
|---|---|---|
models | ModelProfile[] | Available AI models |
config | Partial<SmartRouterConfig> | Router configuration |
SmartRouterConfig
interface SmartRouterConfig {
defaultStrategy: RoutingStrategy; // default: 'balanced'
costWeight: number; // default: 0.3
latencyWeight: number; // default: 0.3
qualityWeight: number; // default: 0.4
healthCheckIntervalMs: number; // default: 30000
circuitBreakerThreshold: number; // default: 5
circuitBreakerResetMs: number; // default: 60000
}Methods
route()
Selects the optimal model for a task, filtering by health, capabilities, budget, and latency constraints, then scoring by the chosen strategy.
route(ctx: RoutingContext): RoutingDecisionconst decision = router.route({
task: { id: 'task_1', type: 'code-review' },
strategy: 'quality',
budgetRemainingUsd: 0.50,
maxLatencyMs: 5000,
requiredCapabilities: ['code', 'reasoning'],
});
console.log(decision.model.id); // 'claude-sonnet'
console.log(decision.reason); // 'claude-sonnet (anthropic) — highest quality, tier=standard'
console.log(decision.fallbacks.length); // up to 3 fallback models
console.log(decision.estimatedCostUsd); // 0.009
console.log(decision.estimatedLatencyMs); // 1200recordSuccess()
Records a successful request for a model. Decrements circuit breaker failure count. If failures reach zero, the circuit is closed and the model is marked healthy.
recordSuccess(modelId: string): voidrecordFailure()
Records a failed request for a model. Increments circuit breaker failure count. When failures reach circuitBreakerThreshold, the circuit opens and the model is excluded from routing.
recordFailure(modelId: string): voidaddModel()
Adds a new model or replaces an existing one with the same ID.
addModel(model: ModelProfile): voidrouter.addModel({
id: 'gemini-flash',
provider: 'gemini',
tier: 'fast',
costPer1kInput: 0.000075,
costPer1kOutput: 0.0003,
avgLatencyMs: 300,
qualityScore: 65,
capabilities: ['code', 'chat'],
maxTokens: 1_000_000,
healthy: true,
circuitOpen: false,
});removeModel()
Removes a model by ID and clears its circuit breaker state.
removeModel(modelId: string): voidgetModels()
Returns the current list of registered models.
getModels(): readonly ModelProfile[]getHealthReport()
Returns a per-model health report including circuit breaker state.
getHealthReport(): Array<{
id: string;
provider: string;
healthy: boolean;
circuitOpen: boolean;
failures: number;
}>Types
RoutingStrategy
type RoutingStrategy = 'cost' | 'latency' | 'quality' | 'balanced';Strategy weight distribution:
| Strategy | Cost | Latency | Quality |
|---|---|---|---|
cost | 0.7 | 0.1 | 0.2 |
latency | 0.1 | 0.7 | 0.2 |
quality | 0.1 | 0.1 | 0.8 |
balanced | costWeight | latencyWeight | qualityWeight |
ModelProfile
interface ModelProfile {
id: string;
provider: 'anthropic' | 'openai' | 'gemini' | 'openrouter';
tier: ModelTier;
costPer1kInput: number;
costPer1kOutput: number;
avgLatencyMs: number;
qualityScore: number;
capabilities: string[];
maxTokens: number;
healthy: boolean;
circuitOpen: boolean;
}
type ModelTier = 'fast' | 'standard' | 'premium';RoutingContext
interface RoutingContext {
task: MeshTask;
strategy?: RoutingStrategy;
budgetRemainingUsd?: number;
maxLatencyMs?: number;
requiredCapabilities?: string[];
}RoutingDecision
interface RoutingDecision {
model: ModelProfile;
reason: string;
fallbacks: ModelProfile[];
estimatedCostUsd: number;
estimatedLatencyMs: number;
}Example
import { SmartRouter } from '@codmir/cortex';
import type { ModelProfile } from '@codmir/cortex';
const models: ModelProfile[] = [
{
id: 'claude-opus',
provider: 'anthropic',
tier: 'premium',
costPer1kInput: 0.015,
costPer1kOutput: 0.075,
avgLatencyMs: 3000,
qualityScore: 98,
capabilities: ['code', 'reasoning', 'analysis', 'vision'],
maxTokens: 200_000,
healthy: true,
circuitOpen: false,
},
{
id: 'claude-sonnet',
provider: 'anthropic',
tier: 'standard',
costPer1kInput: 0.003,
costPer1kOutput: 0.015,
avgLatencyMs: 1200,
qualityScore: 90,
capabilities: ['code', 'reasoning', 'analysis'],
maxTokens: 200_000,
healthy: true,
circuitOpen: false,
},
{
id: 'gpt-4o-mini',
provider: 'openai',
tier: 'fast',
costPer1kInput: 0.00015,
costPer1kOutput: 0.0006,
avgLatencyMs: 400,
qualityScore: 70,
capabilities: ['code', 'chat'],
maxTokens: 128_000,
healthy: true,
circuitOpen: false,
},
];
const router = new SmartRouter(models, {
defaultStrategy: 'balanced',
circuitBreakerThreshold: 3,
});
// Route a complex task — quality strategy picks the best model
const decision = router.route({
task: { id: 'task_1', type: 'architecture-review' },
strategy: 'quality',
requiredCapabilities: ['reasoning'],
});
console.log(decision.model.id); // 'claude-opus'
// Route a simple task — cost strategy picks the cheapest
const cheapDecision = router.route({
task: { id: 'task_2', type: 'chat' },
strategy: 'cost',
});
console.log(cheapDecision.model.id); // 'gpt-4o-mini'
// Simulate failures — circuit breaker opens after threshold
router.recordFailure('claude-opus');
router.recordFailure('claude-opus');
router.recordFailure('claude-opus');
const report = router.getHealthReport();
const opus = report.find((m) => m.id === 'claude-opus');
console.log(opus?.circuitOpen); // true — opus is now excluded from routing