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

package/dist/cost/budgetEnforcer.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * A3M Router - Budget Enforcer
+ *
+ * Hard budget enforcement for API key spend management:
+ * - Track spend per API key with monthly reset
+ * - Check budget before each request
+ * - Emit alerts at configurable thresholds (50%, 80%, 100%)
+ * - Support hard cap (reject requests) or soft cap (warn only)
+ * - In-memory storage (Redis backup can be added later)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgetExceededError = exports.BudgetEnforcer = void 0;
+exports.createBudgetEnforcer = createBudgetEnforcer;
+const events_1 = require("events");
+// ---------------------------------------------------------------------------
+// BudgetEnforcer
+// ---------------------------------------------------------------------------
+class BudgetEnforcer extends events_1.EventEmitter {
+    budgets = new Map();
+    spend = new Map();
+    // Default alert thresholds: 50%, 80%, 100%
+    static DEFAULT_THRESHOLDS = [0.5, 0.8, 1.0];
+    constructor() {
+        super();
+    }
+    // ---- Configuration ----
+    /**
+     * Set budget for an API key
+     */
+    setBudget(apiKey, monthlyLimit, options) {
+        const config = {
+            apiKey,
+            monthlyLimit,
+            alertThresholds: options?.alertThresholds ?? BudgetEnforcer.DEFAULT_THRESHOLDS,
+            hardCap: options?.hardCap ?? false,
+        };
+        this.budgets.set(apiKey, config);
+        // Initialize spend record if not exists
+        if (!this.spend.has(apiKey)) {
+            this.spend.set(apiKey, {
+                apiKey,
+                spent: 0,
+                budget: monthlyLimit,
+                remaining: monthlyLimit,
+                resetDate: this.getNextResetDate(),
+                alertEmitted: new Set(),
+            });
+        }
+    }
+    /**
+     * Get current budget config for an API key
+     */
+    getBudgetConfig(apiKey) {
+        return this.budgets.get(apiKey);
+    }
+    /**
+     * Remove budget config (stops tracking)
+     */
+    removeBudget(apiKey) {
+        this.budgets.delete(apiKey);
+        this.spend.delete(apiKey);
+    }
+    // ---- Budget Checking ----
+    /**
+     * Check if a request is allowed within budget
+     * @param apiKey - The API key making the request
+     * @param additionalCost - The cost of the request in cents
+     * @returns BudgetCheckResult with allowed status and remaining budget
+     */
+    checkBudget(apiKey, additionalCost) {
+        // Auto-initialize if no budget set (permissive default)
+        if (!this.budgets.has(apiKey)) {
+            return {
+                allowed: true,
+                remaining: Infinity,
+            };
+        }
+        // Check for reset
+        this.checkAndReset(apiKey);
+        const record = this.spend.get(apiKey);
+        const config = this.budgets.get(apiKey);
+        const projectedSpend = record.spent + additionalCost;
+        // Check if would exceed budget
+        if (projectedSpend > record.budget) {
+            if (config.hardCap) {
+                return {
+                    allowed: false,
+                    reason: `Budget exceeded. Spent: ${record.spent} cents, Budget: ${record.budget} cents, Additional: ${additionalCost} cents`,
+                    remaining: record.remaining,
+                };
+            }
+            // Soft cap: allow but warn
+            this.emit('budget:warning', {
+                apiKey,
+                threshold: 1.0,
+                spent: record.spent,
+                budget: record.budget,
+                remaining: record.remaining,
+                message: `Soft cap: Budget would be exceeded by ${projectedSpend - record.budget} cents`,
+            });
+        }
+        return {
+            allowed: true,
+            remaining: record.remaining - additionalCost,
+        };
+    }
+    // ---- Spend Recording ----
+    /**
+     * Record spend for an API key
+     * @param apiKey - The API key that incurred the cost
+     * @param cost - The cost in cents
+     */
+    recordSpend(apiKey, cost) {
+        // Auto-initialize if no budget set
+        if (!this.budgets.has(apiKey)) {
+            return; // No budget to track
+        }
+        // Check for reset
+        this.checkAndReset(apiKey);
+        const record = this.spend.get(apiKey);
+        const config = this.budgets.get(apiKey);
+        const previousSpent = record.spent;
+        record.spent += cost;
+        record.remaining = record.budget - record.spent;
+        // Check thresholds
+        const utilization = record.spent / record.budget;
+        for (const threshold of config.alertThresholds ?? BudgetEnforcer.DEFAULT_THRESHOLDS) {
+            const thresholdKey = Math.round(threshold * 1000);
+            if (!record.alertEmitted.has(thresholdKey)) {
+                const previousUtilization = previousSpent / record.budget;
+                if (utilization >= threshold && previousUtilization < threshold) {
+                    record.alertEmitted.add(thresholdKey);
+                    this.emit('budget:warning', {
+                        apiKey,
+                        threshold,
+                        spent: record.spent,
+                        budget: record.budget,
+                        remaining: record.remaining,
+                        message: `Budget ${Math.round(threshold * 100)}% threshold reached`,
+                    });
+                }
+            }
+        }
+        // Fire 100% event if budget exceeded (for hard cap tracking)
+        if (record.spent >= record.budget && previousSpent < record.budget) {
+            this.emit('budget:exceeded', {
+                apiKey,
+                spent: record.spent,
+                budget: record.budget,
+                remaining: 0,
+            });
+        }
+    }
+    // ---- Spend Queries ----
+    /**
+     * Get current spend record for an API key
+     */
+    getSpend(apiKey) {
+        if (!this.spend.has(apiKey)) {
+            return undefined;
+        }
+        const record = { ...this.spend.get(apiKey) };
+        // Convert Set to Array for serialization
+        record.alertEmitted = Array.from(record.alertEmitted);
+        return record;
+    }
+    /**
+     * Get all spend records
+     */
+    getAllSpend() {
+        return Array.from(this.spend.values()).map((record) => {
+            const copy = { ...record };
+            copy.alertEmitted = Array.from(record.alertEmitted);
+            return copy;
+        });
+    }
+    // ---- Budget Management ----
+    /**
+     * Reset budget for an API key (manual reset)
+     */
+    resetBudget(apiKey) {
+        if (!this.spend.has(apiKey)) {
+            return;
+        }
+        const record = this.spend.get(apiKey);
+        record.spent = 0;
+        record.remaining = record.budget;
+        record.resetDate = this.getNextResetDate();
+        record.alertEmitted.clear();
+    }
+    /**
+     * Reset all budgets
+     */
+    resetAll() {
+        for (const record of this.spend.values()) {
+            record.spent = 0;
+            record.remaining = record.budget;
+            record.resetDate = this.getNextResetDate();
+            record.alertEmitted.clear();
+        }
+    }
+    /**
+     * Update monthly limit for an API key
+     */
+    updateLimit(apiKey, monthlyLimit) {
+        if (!this.budgets.has(apiKey)) {
+            this.setBudget(apiKey, monthlyLimit);
+            return;
+        }
+        const config = this.budgets.get(apiKey);
+        config.monthlyLimit = monthlyLimit;
+        const record = this.spend.get(apiKey);
+        const oldBudget = record.budget;
+        record.budget = monthlyLimit;
+        record.remaining = monthlyLimit - record.spent;
+        // Re-check if any thresholds are now exceeded
+        const utilization = record.spent / record.budget;
+        for (const threshold of config.alertThresholds ?? BudgetEnforcer.DEFAULT_THRESHOLDS) {
+            const thresholdKey = Math.round(threshold * 1000);
+            if (utilization >= threshold) {
+                record.alertEmitted.add(thresholdKey);
+            }
+            else {
+                record.alertEmitted.delete(thresholdKey);
+            }
+        }
+    }
+    // ---- Internal Helpers ----
+    /**
+     * Check if reset is needed and perform it
+     */
+    checkAndReset(apiKey) {
+        const record = this.spend.get(apiKey);
+        if (this.isResetDue(record.resetDate)) {
+            record.spent = 0;
+            record.remaining = record.budget;
+            record.resetDate = this.getNextResetDate();
+            record.alertEmitted.clear();
+        }
+    }
+    /**
+     * Check if monthly reset is due
+     */
+    isResetDue(resetDate) {
+        const now = new Date();
+        return now >= resetDate;
+    }
+    /**
+     * Get next monthly reset date
+     */
+    getNextResetDate() {
+        const now = new Date();
+        const nextMonth = new Date(now.getFullYear(), now.getMonth() + 1, 1);
+        return nextMonth;
+    }
+    /**
+     * Get days until next reset
+     */
+    getDaysUntilReset(apiKey) {
+        const record = this.spend.get(apiKey);
+        if (!record)
+            return undefined;
+        const now = Date.now();
+        const resetMs = record.resetDate.getTime();
+        return Math.max(0, Math.ceil((resetMs - now) / (1000 * 60 * 60 * 24)));
+    }
+}
+exports.BudgetEnforcer = BudgetEnforcer;
+// ---------------------------------------------------------------------------
+// Convenience Factory
+// ---------------------------------------------------------------------------
+function createBudgetEnforcer() {
+    return new BudgetEnforcer();
+}
+// ---------------------------------------------------------------------------
+// Error Class for Hard Cap Violations
+// ---------------------------------------------------------------------------
+class BudgetExceededError extends Error {
+    apiKey;
+    spent;
+    budget;
+    remaining;
+    constructor(apiKey, spent, budget) {
+        const message = `Budget exceeded for API key ${apiKey}. Spent: ${spent} cents, Budget: ${budget} cents`;
+        super(message);
+        this.name = 'BudgetExceededError';
+        this.apiKey = apiKey;
+        this.spent = spent;
+        this.budget = budget;
+        this.remaining = budget - spent;
+    }
+}
+exports.BudgetExceededError = BudgetExceededError;
+//# sourceMappingURL=budgetEnforcer.js.map

package/dist/cost/budgetEnforcer.js.map

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

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { routeQuery, routeBatch, recommendForTask, extractQueryFeatures, MODEL_P
 export { DEFAULT_PROVIDERS, getAvailableProviders, registerProvider, deregisterProvider, updateProvider, healthCheck, checkAllProviders, findCheapestAvailableProvider, findFastestAvailableProvider, loadConfig, saveConfig, } from './providers/providerConfig';
 export type { ProviderTier, ProviderFormat, ProviderType, ProviderCost, ProviderDefinition, } from './providers/providerConfig';
 export { CostTracker } from './cost/costTracker';
+export { BudgetEnforcer, BudgetExceededError, createBudgetEnforcer } from './cost/budgetEnforcer';
+export type { BudgetConfig, SpendRecord, BudgetCheckResult } from './cost/budgetEnforcer';
 export { MemoryTree } from './memory/memoryTree';
 export type { MemoryChunk, TreeNode } from './memory/memoryTree';
 export { countTokens, estimateTokens } from './utils/tokenUtils';

package/dist/index.js

@@ -2,7 +2,7 @@
 // A3M Router - Main Entry Point
 // Version: 2.0.0
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createProxyServer = exports.CostAnalytics = exports.GuardrailEngine = exports.SemanticCache = exports.MODEL_COSTS = exports.estimateTokens = exports.countTokens = exports.MemoryTree = exports.CostTracker = exports.saveConfig = exports.loadConfig = exports.findFastestAvailableProvider = exports.findCheapestAvailableProvider = exports.checkAllProviders = exports.healthCheck = exports.updateProvider = exports.deregisterProvider = exports.registerProvider = exports.getAvailableProviders = exports.DEFAULT_PROVIDERS = exports.getProviderHealth = exports.updateModelProfile = exports.MODEL_PROFILES = exports.extractQueryFeatures = exports.recommendForTask = exports.routeBatch = exports.routeQuery = void 0;
+exports.createProxyServer = exports.CostAnalytics = exports.GuardrailEngine = exports.SemanticCache = exports.MODEL_COSTS = exports.estimateTokens = exports.countTokens = exports.MemoryTree = exports.createBudgetEnforcer = exports.BudgetExceededError = exports.BudgetEnforcer = exports.CostTracker = exports.saveConfig = exports.loadConfig = exports.findFastestAvailableProvider = exports.findCheapestAvailableProvider = exports.checkAllProviders = exports.healthCheck = exports.updateProvider = exports.deregisterProvider = exports.registerProvider = exports.getAvailableProviders = exports.DEFAULT_PROVIDERS = exports.getProviderHealth = exports.updateModelProfile = exports.MODEL_PROFILES = exports.extractQueryFeatures = exports.recommendForTask = exports.routeBatch = exports.routeQuery = void 0;
 exports.createA3MRouter = createA3MRouter;
 // ============================================================
 // ROUTING ENGINE
@@ -35,6 +35,10 @@ Object.defineProperty(exports, "saveConfig", { enumerable: true, get: function (
 // ============================================================
 var costTracker_1 = require("./cost/costTracker");
 Object.defineProperty(exports, "CostTracker", { enumerable: true, get: function () { return costTracker_1.CostTracker; } });
+var budgetEnforcer_1 = require("./cost/budgetEnforcer");
+Object.defineProperty(exports, "BudgetEnforcer", { enumerable: true, get: function () { return budgetEnforcer_1.BudgetEnforcer; } });
+Object.defineProperty(exports, "BudgetExceededError", { enumerable: true, get: function () { return budgetEnforcer_1.BudgetExceededError; } });
+Object.defineProperty(exports, "createBudgetEnforcer", { enumerable: true, get: function () { return budgetEnforcer_1.createBudgetEnforcer; } });
 // ============================================================
 // MEMORY
 // ============================================================

package/dist/routing/providerHealth.d.ts

@@ -0,0 +1,154 @@
+/**
+ * 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']);
+ */
+import { EventEmitter } from 'events';
+export interface ProviderHealth {
+    /** Provider name (e.g., "openai/gpt-4o") */
+    name: string;
+    /** Rolling average latency in ms */
+    latency: number;
+    /** Error rate 0-1 */
+    errorRate: number;
+    /** Timestamp of last successful request */
+    lastSuccess: number;
+    /** Timestamp of last failed request */
+    lastError: number;
+    /** Consecutive error count */
+    consecutiveErrors: number;
+    /** Whether provider is healthy (not in cooldown) */
+    isHealthy: boolean;
+    /** Timestamp when cooldown ends (0 if not in cooldown) */
+    cooldownUntil: number;
+    /** Health score 0-1 (higher is better) */
+    healthScore: number;
+}
+export interface ProviderMetrics {
+    /** Provider name */
+    name: string;
+    /** Total requests sent */
+    totalRequests: number;
+    /** Successful requests */
+    successfulRequests: number;
+    /** Failed requests */
+    failedRequests: number;
+    /** Sum of latencies for averaging */
+    totalLatency: number;
+    /** Last measured latency */
+    lastLatency: number;
+}
+export interface HealthManagerConfig {
+    /** Window size for rolling metrics (default: 100 requests) */
+    windowSize?: number;
+    /** Consecutive errors before circuit break (default: 3) */
+    circuitBreakerThreshold?: number;
+    /** Cooldown duration in ms (default: 60000 = 60s) */
+    cooldownMs?: number;
+    /** Latency percentile for health scoring (default: 95) */
+    latencyPercentile?: number;
+    /** Weights for health score components */
+    weights?: {
+        latency: number;
+        errorRate: number;
+        consecutiveErrors: number;
+    };
+}
+export declare enum HealthEvent {
+    HEALTH_CHANGED = "healthChanged",
+    CIRCUIT_OPENED = "circuitOpened",
+    CIRCUIT_CLOSED = "circuitClosed",
+    COOLDOWN_STARTED = "cooldownStarted",
+    COOLDOWN_ENDED = "cooldownEnded",
+    PROVIDER_DISABLED = "providerDisabled",
+    PROVIDER_ENABLED = "providerEnabled",
+    PROBE_ALLOWED = "probeAllowed"
+}
+export declare class ProviderHealthManager extends EventEmitter {
+    private metrics;
+    private health;
+    private disabled;
+    private config;
+    constructor(config?: HealthManagerConfig);
+    /**
+     * Record a successful request
+     */
+    recordSuccess(provider: string, latencyMs: number): void;
+    /**
+     * Record a failed request
+     */
+    recordFailure(provider: string, error: string): void;
+    /**
+     * Get current health for a provider
+     */
+    getHealth(provider: string): ProviderHealth | undefined;
+    /**
+     * Get all provider health statuses
+     */
+    getAllHealth(): Map<string, ProviderHealth>;
+    /**
+     * Check if a provider is available (healthy and not in cooldown/manual disable)
+     */
+    isAvailable(provider: string): boolean;
+    /**
+     * Check if cooldown has expired and probe is allowed
+     */
+    isProbeAllowed(provider: string): boolean;
+    /**
+     * Get the best provider from a list based on health scores
+     */
+    getBestProvider(providers: string[]): string | null;
+    /**
+     * Get sorted fallback chain based on health scores
+     * Returns providers sorted by health score (descending)
+     */
+    getFallbackChain(providers: string[]): string[];
+    /**
+     * Mark provider as disabled (manual circuit breaker)
+     */
+    disableProvider(provider: string, reason: string): void;
+    /**
+     * Enable a previously disabled provider
+     */
+    enableProvider(provider: string): void;
+    /**
+     * Clear cooldown and reset circuit breaker for a provider
+     */
+    resetCircuitBreaker(provider: string): void;
+    /**
+     * Get health stats for monitoring
+     */
+    getStats(): {
+        totalProviders: number;
+        healthyProviders: number;
+        cooldownProviders: number;
+        disabledProviders: number;
+        avgHealthScore: number;
+    };
+    private ensureProviderExists;
+    private getMetricsWindow;
+    private recalculateHealthScore;
+    private calculateLatencyScore;
+}
+export { ProviderHealthManager };
+export default ProviderHealthManager;