adaptive-memory-multi-model-router 2.5.5 → 2.7.0

package/dist/routing/providerHealth.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * Provider Health Manager with Circuit Breaker
+ *
+ * Intelligent failover system for A3M Router providing:
+ * - Rolling window metrics tracking (latency, error rate)
+ * - Health scoring based on latency percentile + error rate
+ * - Circuit breaker: 3 consecutive errors → 60s cooldown
+ * - Probe mode after cooldown for recovery
+ * - Sorted fallback chain based on health scores
+ *
+ * Usage:
+ *   import { ProviderHealthManager, ProviderHealth } from './routing/providerHealth';
+ *
+ *   const healthManager = new ProviderHealthManager();
+ *
+ *   // Record outcomes
+ *   healthManager.recordSuccess('openai/gpt-4o', 150);
+ *   healthManager.recordFailure('anthropic/claude-3-5-sonnet', 'rate_limit');
+ *
+ *   // Get health status
+ *   const health = healthManager.getHealth('openai/gpt-4o');
+ *
+ *   // Get sorted fallback chain
+ *   const chain = healthManager.getFallbackChain(['openai/gpt-4o', 'anthropic/claude-3-5-sonnet']);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderHealthManager = exports.HealthEvent = void 0;
+const events_1 = require("events");
+// ============================================================
+// Events
+// ============================================================
+var HealthEvent;
+(function (HealthEvent) {
+    HealthEvent["HEALTH_CHANGED"] = "healthChanged";
+    HealthEvent["CIRCUIT_OPENED"] = "circuitOpened";
+    HealthEvent["CIRCUIT_CLOSED"] = "circuitClosed";
+    HealthEvent["COOLDOWN_STARTED"] = "cooldownStarted";
+    HealthEvent["COOLDOWN_ENDED"] = "cooldownEnded";
+    HealthEvent["PROVIDER_DISABLED"] = "providerDisabled";
+    HealthEvent["PROVIDER_ENABLED"] = "providerEnabled";
+    HealthEvent["PROBE_ALLOWED"] = "probeAllowed";
+})(HealthEvent || (exports.HealthEvent = HealthEvent = {}));
+// ============================================================
+// ProviderHealthManager
+// ============================================================
+class ProviderHealthManager extends events_1.EventEmitter {
+    // Rolling window metrics per provider
+    metrics = new Map();
+    // Current health state per provider
+    health = new Map();
+    // Disabled providers (manual disable)
+    disabled = new Map();
+    // Config
+    config;
+    constructor(config = {}) {
+        super();
+        this.config = {
+            windowSize: config.windowSize ?? 100,
+            circuitBreakerThreshold: config.circuitBreakerThreshold ?? 3,
+            cooldownMs: config.cooldownMs ?? 60000,
+            latencyPercentile: config.latencyPercentile ?? 95,
+            weights: {
+                latency: config.weights?.latency ?? 0.3,
+                errorRate: config.weights?.errorRate ?? 0.5,
+                consecutiveErrors: config.weights?.consecutiveErrors ?? 0.2,
+            },
+        };
+    }
+    /**
+     * Record a successful request
+     */
+    recordSuccess(provider, latencyMs) {
+        this.ensureProviderExists(provider);
+        const now = Date.now();
+        const window = this.getMetricsWindow(provider);
+        window.push({
+            name: provider,
+            totalRequests: 1,
+            successfulRequests: 1,
+            failedRequests: 0,
+            totalLatency: latencyMs,
+            lastLatency: latencyMs,
+        });
+        // Trim to window size
+        while (window.length > this.config.windowSize) {
+            window.shift();
+        }
+        // Update health state
+        const health = this.health.get(provider);
+        health.lastSuccess = now;
+        health.consecutiveErrors = 0;
+        health.cooldownUntil = 0;
+        health.isHealthy = true;
+        // Recalculate health score
+        this.recalculateHealthScore(provider);
+        this.emit(HealthEvent.HEALTH_CHANGED, health);
+    }
+    /**
+     * Record a failed request
+     */
+    recordFailure(provider, error) {
+        this.ensureProviderExists(provider);
+        const now = Date.now();
+        const window = this.getMetricsWindow(provider);
+        window.push({
+            name: provider,
+            totalRequests: 1,
+            successfulRequests: 0,
+            failedRequests: 1,
+            totalLatency: 0,
+            lastLatency: 0,
+        });
+        // Trim to window size
+        while (window.length > this.config.windowSize) {
+            window.shift();
+        }
+        // Update health state
+        const health = this.health.get(provider);
+        health.lastError = now;
+        health.consecutiveErrors++;
+        // Check circuit breaker
+        if (health.consecutiveErrors >= this.config.circuitBreakerThreshold) {
+            health.cooldownUntil = now + this.config.cooldownMs;
+            health.isHealthy = false;
+            this.emit(HealthEvent.CIRCUIT_OPENED, {
+                provider,
+                consecutiveErrors: health.consecutiveErrors,
+                cooldownUntil: health.cooldownUntil,
+                reason: error,
+            });
+            this.emit(HealthEvent.COOLDOWN_STARTED, {
+                provider,
+                duration: this.config.cooldownMs,
+                reason: error,
+            });
+        }
+        this.recalculateHealthScore(provider);
+        this.emit(HealthEvent.HEALTH_CHANGED, health);
+    }
+    /**
+     * Get current health for a provider
+     */
+    getHealth(provider) {
+        this.ensureProviderExists(provider);
+        return { ...this.health.get(provider) };
+    }
+    /**
+     * Get all provider health statuses
+     */
+    getAllHealth() {
+        const result = new Map();
+        for (const [name, health] of this.health.entries()) {
+            result.set(name, { ...health });
+        }
+        return result;
+    }
+    /**
+     * Check if a provider is available (healthy and not in cooldown/manual disable)
+     */
+    isAvailable(provider) {
+        const health = this.health.get(provider);
+        if (!health)
+            return false;
+        // Check manual disable
+        const disabled = this.disabled.get(provider);
+        if (disabled && disabled.until > Date.now()) {
+            return false;
+        }
+        // Check cooldown
+        if (health.cooldownUntil > Date.now()) {
+            return false;
+        }
+        return health.isHealthy;
+    }
+    /**
+     * Check if cooldown has expired and probe is allowed
+     */
+    isProbeAllowed(provider) {
+        const health = this.health.get(provider);
+        if (!health)
+            return false;
+        // If not in cooldown, no probe needed
+        if (health.cooldownUntil === 0)
+            return true;
+        // If cooldown has expired
+        if (health.cooldownUntil <= Date.now()) {
+            // Only allow one probe request per cooldown period
+            // After probe (marked by consecutiveErrors reset), normal requests allowed
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get the best provider from a list based on health scores
+     */
+    getBestProvider(providers) {
+        const available = providers.filter(p => this.isAvailable(p));
+        if (available.length === 0)
+            return null;
+        return available.reduce((best, current) => {
+            const health = this.health.get(current);
+            const bestHealth = this.health.get(best);
+            if (!health || !bestHealth)
+                return current;
+            return health.healthScore >= bestHealth.healthScore ? current : best;
+        });
+    }
+    /**
+     * Get sorted fallback chain based on health scores
+     * Returns providers sorted by health score (descending)
+     */
+    getFallbackChain(providers) {
+        // Score each provider
+        const scored = providers.map(p => ({
+            provider: p,
+            score: this.isAvailable(p) ? (this.health.get(p)?.healthScore ?? 0) : -1,
+        }));
+        // Sort by health score (descending), unavailable at end
+        scored.sort((a, b) => {
+            if (a.score === -1 && b.score === -1)
+                return 0;
+            if (a.score === -1)
+                return 1;
+            if (b.score === -1)
+                return -1;
+            return b.score - a.score;
+        });
+        return scored.map(s => s.provider);
+    }
+    /**
+     * Mark provider as disabled (manual circuit breaker)
+     */
+    disableProvider(provider, reason) {
+        const until = Number.MAX_SAFE_INTEGER; // Manual disable until explicitly enabled
+        this.disabled.set(provider, { reason, until });
+        const health = this.health.get(provider);
+        if (health) {
+            health.isHealthy = false;
+        }
+        this.emit(HealthEvent.PROVIDER_DISABLED, { provider, reason });
+    }
+    /**
+     * Enable a previously disabled provider
+     */
+    enableProvider(provider) {
+        this.disabled.delete(provider);
+        const health = this.health.get(provider);
+        if (health) {
+            health.isHealthy = true;
+            health.consecutiveErrors = 0;
+            health.cooldownUntil = 0;
+        }
+        this.emit(HealthEvent.PROVIDER_ENABLED, { provider });
+    }
+    /**
+     * Clear cooldown and reset circuit breaker for a provider
+     */
+    resetCircuitBreaker(provider) {
+        const health = this.health.get(provider);
+        if (health) {
+            health.consecutiveErrors = 0;
+            health.cooldownUntil = 0;
+            health.isHealthy = true;
+            this.emit(HealthEvent.CIRCUIT_CLOSED, { provider });
+        }
+    }
+    /**
+     * Get health stats for monitoring
+     */
+    getStats() {
+        let healthyCount = 0;
+        let cooldownCount = 0;
+        let disabledCount = 0;
+        let totalScore = 0;
+        for (const [name, health] of this.health.entries()) {
+            totalScore += health.healthScore;
+            if (!health.isHealthy && health.cooldownUntil > Date.now()) {
+                cooldownCount++;
+            }
+            else if (health.isHealthy) {
+                healthyCount++;
+            }
+            if (this.disabled.has(name)) {
+                disabledCount++;
+            }
+        }
+        const total = this.health.size;
+        return {
+            totalProviders: total,
+            healthyProviders: healthyCount,
+            cooldownProviders: cooldownCount,
+            disabledProviders: disabledCount,
+            avgHealthScore: total > 0 ? totalScore / total : 0,
+        };
+    }
+    // ============================================================
+    // Private Methods
+    // ============================================================
+    ensureProviderExists(provider) {
+        if (!this.health.has(provider)) {
+            const now = Date.now();
+            this.health.set(provider, {
+                name: provider,
+                latency: 0,
+                errorRate: 0,
+                lastSuccess: 0,
+                lastError: 0,
+                consecutiveErrors: 0,
+                isHealthy: true,
+                cooldownUntil: 0,
+                healthScore: 1.0,
+            });
+            this.metrics.set(provider, []);
+        }
+    }
+    getMetricsWindow(provider) {
+        return this.metrics.get(provider) ?? [];
+    }
+    recalculateHealthScore(provider) {
+        const window = this.getMetricsWindow(provider);
+        const health = this.health.get(provider);
+        if (!health || window.length === 0)
+            return;
+        // Calculate error rate
+        const totalRequests = window.reduce((sum, m) => sum + m.totalRequests, 0);
+        const failedRequests = window.reduce((sum, m) => sum + m.failedRequests, 0);
+        const errorRate = totalRequests > 0 ? failedRequests / totalRequests : 0;
+        health.errorRate = errorRate;
+        // Calculate latency metrics
+        const latencies = window.filter(m => m.totalLatency > 0).map(m => m.lastLatency);
+        const avgLatency = latencies.length > 0
+            ? latencies.reduce((a, b) => a + b, 0) / latencies.length
+            : 0;
+        health.latency = avgLatency;
+        // Percentile latency (simplified: use avg latency as proxy)
+        // For true percentile, we'd need raw data points
+        const latencyScore = this.calculateLatencyScore(avgLatency);
+        // Health score: weighted combination
+        // Higher error rate = lower score, higher latency = lower score
+        const errorScore = 1 - errorRate;
+        const consecutiveScore = Math.max(0, 1 - (health.consecutiveErrors / this.config.circuitBreakerThreshold));
+        const score = this.config.weights.latency * latencyScore +
+            this.config.weights.errorRate * errorScore +
+            this.config.weights.consecutiveErrors * consecutiveScore;
+        health.healthScore = Math.max(0, Math.min(1, score));
+    }
+    calculateLatencyScore(avgLatency) {
+        // Latency score: 1 at 0ms, 0 at 10000ms+, with exponential decay
+        // Configurable thresholds could be passed in
+        const latencyThresholds = {
+            excellent: 100, // 100ms - score 1.0
+            good: 500, // 500ms - score 0.8
+            acceptable: 1000, // 1s - score 0.6
+            poor: 3000, // 3s - score 0.3
+            terrible: 10000, // 10s+ - score 0.0
+        };
+        if (avgLatency <= 0)
+            return 1.0;
+        if (avgLatency <= latencyThresholds.excellent)
+            return 1.0;
+        if (avgLatency >= latencyThresholds.terrible)
+            return 0.0;
+        // Exponential interpolation
+        const k = 0.003; // decay constant
+        return Math.exp(-k * avgLatency);
+    }
+}
+exports.ProviderHealthManager = ProviderHealthManager;
+exports.default = ProviderHealthManager;
+//# sourceMappingURL=providerHealth.js.map

package/dist/routing/providerHealth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providerHealth.js","sourceRoot":"","sources":["../../src/routing/providerHealth.ts"],"names":[],"mappings":"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"}

package/dist/sdk.d.ts

@@ -0,0 +1,124 @@
+/**
+ * A3M Router TypeScript SDK
+ *
+ * Clean wrapper class providing a better DX than raw exports.
+ *
+ * Usage:
+ *   import { A3MRouter } from 'adaptive-memory-multi-model-router/sdk';
+ *
+ *   const router = new A3MRouter();
+ *
+ *   // Route a query (no execution, just model selection)
+ *   const decision = router.route("What is 2+2?");
+ *   console.log(decision.model, decision.tier, decision.cost);
+ *
+ *   // Start the OpenAI-compatible proxy server
+ *   const proxyURL = await router.serve(8787);
+ *
+ *   // Use with any OpenAI SDK
+ *   import OpenAI from 'openai';
+ *   const client = new OpenAI({ baseURL: router.proxyURL });
+ *   const response = await client.chat.completions.create({
+ *     model: 'auto',
+ *     messages: [{ role: 'user', content: 'Hello' }]
+ *   });
+ */
+export interface RoutingResult {
+    /** Selected model identifier (e.g. "groq/llama-3.3-70b-versatile") */
+    model: string;
+    /** Cost tier classification */
+    tier: 'free' | 'cheap' | 'mid' | 'premium';
+    /** Estimated cost in USD */
+    cost: number;
+    /** Complexity score 0.0–1.0 */
+    complexity: number;
+    /** Human-readable reasoning for the selection */
+    reasoning: string;
+    /** Alternative models in priority order */
+    fallbackModels: string[];
+    /** Whether the selected model is free */
+    isFree: boolean;
+    /** Whether this is classified as an expert-level query */
+    isExpert: boolean;
+}
+export interface QueryFeatures {
+    complexity: number;
+    length: number;
+    has_code: boolean;
+    has_math: boolean;
+    is_multilingual: boolean;
+    is_translation: boolean;
+    is_creative: boolean;
+    requires_reasoning: boolean;
+    is_security: boolean;
+    is_devops: boolean;
+    is_data: boolean;
+    detected_domain: string;
+    domain_score: number;
+}
+export interface A3MRouterConfig {
+    /** Default model to use when routing is ambiguous */
+    defaultModel?: string;
+    /** Maximum cost per query in USD (routes to cheaper models if exceeded) */
+    maxCostPerQuery?: number;
+    /** Prefer fast responses over higher quality */
+    preferSpeedOverQuality?: boolean;
+    /** Restrict routing to these provider IDs */
+    providers?: string[];
+}
+export declare class A3MRouter {
+    private config;
+    private _proxyURL;
+    constructor(config?: A3MRouterConfig);
+    /**
+     * Route a query — returns model selection without executing it.
+     *
+     * @param query - The user prompt to route
+     * @returns Routing decision with model, tier, cost, complexity
+     */
+    route(query: string): RoutingResult;
+    /**
+     * Route multiple queries in batch.
+     *
+     * @param queries - Array of user prompts
+     * @returns Array of routing decisions
+     */
+    routeBatch(queries: string[]): RoutingResult[];
+    /**
+     * Get model recommendation for a task description.
+     *
+     * @param task - Task description (e.g. "code generation", "summarization")
+     * @returns Routing decision
+     */
+    recommend(task: string): RoutingResult;
+    /**
+     * Start the OpenAI-compatible proxy server.
+     *
+     * @param port - Port to listen on (default: 8787)
+     * @returns The proxy base URL (e.g. "http://localhost:8787/v1")
+     */
+    serve(port?: number): Promise<string>;
+    /**
+     * Get the proxy URL. Available after serve() is called,
+     * otherwise returns the default.
+     */
+    get proxyURL(): string;
+    /**
+     * Extract features from a query for debugging or analysis.
+     *
+     * @param query - The user prompt to analyze
+     * @returns Detailed feature breakdown
+     */
+    analyze(query: string): QueryFeatures;
+    /**
+     * Classify a complexity score into a named tier.
+     */
+    private classifyTier;
+}
+/**
+ * Convenience: create an A3MRouter instance.
+ *
+ * @param config - Optional configuration
+ * @returns Configured A3MRouter instance
+ */
+export declare function createSDK(config?: A3MRouterConfig): A3MRouter;