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): RoutingDecision

const 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); // 1200

recordSuccess()

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): void

recordFailure()

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): void

addModel()

Adds a new model or replaces an existing one with the same ID.

addModel(model: ModelProfile): void

router.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): void

getModels()

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