adaptive-memory-multi-model-router 2.6.0 → 2.8.0

package/dist/routing/providerRetry.js

@@ -0,0 +1,460 @@
+"use strict";
+/**
+ * A3M Router - Per-Provider Retry Logic
+ *
+ * Implements exponential backoff with jitter for transient errors,
+ * rate limit (429) handling with Retry-After header support,
+ * and context window validation before sending requests.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_CONTEXT_LIMITS = exports.DEFAULT_RETRY_CONFIG = exports.ProviderRetryHandler = exports.DEFAULT_PROVIDER_CONFIG = void 0;
+exports.createRetryHandler = createRetryHandler;
+exports.getDefaultRetryHandler = getDefaultRetryHandler;
+const tokenUtils_1 = require("../utils/tokenUtils");
+// ============================================================
+// DEFAULT CONFIGURATION
+// ============================================================
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 2,
+    retryableErrors: [
+        'ECONNRESET',
+        'ETIMEDOUT',
+        'ECONNREFUSED',
+        '503',
+        '429',
+        '500',
+        '502',
+        '504',
+        'NETWORK_ERROR',
+        'TIMEOUT',
+        'SOCKET_HANG_UP',
+        'EAI_AGAIN',
+    ],
+};
+exports.DEFAULT_RETRY_CONFIG = DEFAULT_RETRY_CONFIG;
+exports.DEFAULT_PROVIDER_CONFIG = {
+    // Chinese providers need longer timeouts and more retries
+    'deepseek': {
+        timeout: 30000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 5,
+            initialDelayMs: 2000,
+        },
+        rateLimitRetries: 3,
+    },
+    'zhipu': {
+        timeout: 25000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 4,
+            initialDelayMs: 1500,
+        },
+        rateLimitRetries: 3,
+    },
+    'qwen': {
+        timeout: 25000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 4,
+        },
+        rateLimitRetries: 3,
+    },
+    'moonshot': {
+        timeout: 25000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 4,
+        },
+        rateLimitRetries: 3,
+    },
+    'minimax': {
+        timeout: 20000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 3,
+        },
+        rateLimitRetries: 2,
+    },
+    'yi': {
+        timeout: 20000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 3,
+        },
+        rateLimitRetries: 2,
+    },
+    // US providers are faster
+    'openai': {
+        timeout: 15000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 3,
+        },
+        rateLimitRetries: 2,
+    },
+    'anthropic': {
+        timeout: 15000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 3,
+        },
+        rateLimitRetries: 2,
+    },
+    'groq': {
+        timeout: 10000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 2,
+        },
+        rateLimitRetries: 1,
+    },
+    'cerebras': {
+        timeout: 10000,
+        retry: {
+            ...DEFAULT_RETRY_CONFIG,
+            maxRetries: 2,
+        },
+        rateLimitRetries: 1,
+    },
+    // Default fallback for unknown providers
+    'default': {
+        timeout: 15000,
+        retry: { ...DEFAULT_RETRY_CONFIG },
+        rateLimitRetries: 2,
+    },
+};
+// Provider context window limits (approximate)
+const PROVIDER_CONTEXT_LIMITS = {
+    'openai': 128000,
+    'anthropic': 200000,
+    'deepseek': 64000,
+    'qwen': 32000,
+    'zhipu': 128000,
+    'moonshot': 128000,
+    'minimax': 1000000,
+    'yi': 16000,
+    'groq': 32000,
+    'cerebras': 8000,
+    'default': 8192,
+};
+exports.PROVIDER_CONTEXT_LIMITS = PROVIDER_CONTEXT_LIMITS;
+// ============================================================
+// PROVIDER RETRY HANDLER
+// ============================================================
+class ProviderRetryHandler {
+    configs;
+    stats;
+    customProviders;
+    constructor(customConfigs) {
+        this.configs = new Map();
+        this.stats = new Map();
+        this.customProviders = new Set();
+        // Initialize with defaults
+        for (const [provider, config] of Object.entries(exports.DEFAULT_PROVIDER_CONFIG)) {
+            this.configs.set(provider, {
+                timeout: config.timeout,
+                retry: { ...config.retry },
+                rateLimitRetries: config.rateLimitRetries ?? 2,
+            });
+            this.initStats(provider);
+        }
+        // Apply custom configs
+        if (customConfigs) {
+            for (const [provider, config] of Object.entries(customConfigs)) {
+                this.configureProvider(provider, config);
+            }
+        }
+    }
+    initStats(provider) {
+        this.stats.set(provider, {
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            totalRetries: 0,
+            rateLimitRetries: 0,
+            averageLatencyMs: 0,
+        });
+    }
+    /**
+     * Configure or update a provider's retry settings
+     */
+    configureProvider(provider, config) {
+        const existing = this.configs.get(provider) || {
+            timeout: 15000,
+            retry: { ...DEFAULT_RETRY_CONFIG },
+            rateLimitRetries: 2,
+        };
+        this.configs.set(provider, {
+            timeout: config.timeout ?? existing.timeout,
+            retry: {
+                ...existing.retry,
+                ...config.retry,
+                retryableErrors: config.retry?.retryableErrors ?? existing.retry.retryableErrors,
+            },
+            rateLimitRetries: config.rateLimitRetries ?? existing.rateLimitRetries,
+        });
+        if (!this.stats.has(provider)) {
+            this.initStats(provider);
+        }
+        this.customProviders.add(provider);
+    }
+    /**
+     * Get current config for a provider
+     */
+    getConfig(provider) {
+        return (this.configs.get(provider) ||
+            this.configs.get('default'));
+    }
+    /**
+     * Execute a function with retry logic
+     */
+    async executeWithRetry(provider, fn, options) {
+        const config = this.getConfig(provider);
+        const timeout = options?.timeout ?? config.timeout;
+        let lastError;
+        let attempts = 0;
+        for (let retryAttempt = 0; retryAttempt <= config.retry.maxRetries; retryAttempt++) {
+            attempts++;
+            try {
+                const result = await this.executeWithTimeout(fn, timeout);
+                // Success - update stats
+                this.recordSuccess(provider, 0);
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                // Check if we've exhausted retries
+                if (retryAttempt >= config.retry.maxRetries) {
+                    break;
+                }
+                // Check if error is retryable
+                if (!this.isRetryableError(error)) {
+                    this.recordFailure(provider, attempts - 1);
+                    throw error;
+                }
+                // Handle rate limiting (429)
+                const isRateLimit = this.isRateLimitError(error);
+                const rateLimitRetries = isRateLimit ? config.rateLimitRetries : 0;
+                if (isRateLimit && retryAttempt >= rateLimitRetries) {
+                    // Exceeded rate limit retries
+                    this.recordFailure(provider, attempts - 1);
+                    throw error;
+                }
+                // Calculate delay
+                const delayMs = this.calculateBackoffDelay(retryAttempt, config.retry, error);
+                // Notify callback if provided
+                if (options?.onRetry) {
+                    options.onRetry(retryAttempt + 1, error, delayMs);
+                }
+                // Wait before retry
+                await this.sleep(delayMs);
+                this.recordRetry(provider, isRateLimit);
+            }
+        }
+        this.recordFailure(provider, attempts - 1);
+        throw lastError;
+    }
+    /**
+     * Execute with custom timeout wrapper
+     */
+    async executeWithTimeout(fn, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(this.createTimeoutError(timeoutMs));
+            }, timeoutMs);
+            fn()
+                .then((result) => {
+                clearTimeout(timer);
+                resolve(result);
+            })
+                .catch((error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Check if an error should trigger a retry
+     */
+    isRetryableError(error) {
+        if (!error)
+            return false;
+        const config = this.configs.get('default').retry;
+        const retryableErrors = config.retryableErrors || DEFAULT_RETRY_CONFIG.retryableErrors;
+        // Check error code/message
+        const errorCode = error.code || error.status || error.statusCode || '';
+        const errorMessage = error.message || '';
+        const errorString = String(errorCode).toUpperCase();
+        for (const retryable of retryableErrors) {
+            if (errorString.includes(retryable) ||
+                errorMessage.includes(retryable)) {
+                return true;
+            }
+        }
+        // Check for specific error patterns
+        if (error.status === 429)
+            return true;
+        if (error.status >= 500 && error.status < 600)
+            return true;
+        if (error.errno === 'ETIMEDOUT' || error.errno === 'ECONNRESET')
+            return true;
+        return false;
+    }
+    /**
+     * Check if error is a rate limit (429)
+     */
+    isRateLimitError(error) {
+        return error?.status === 429 || error?.statusCode === 429;
+    }
+    /**
+     * Calculate backoff delay with exponential increase and jitter
+     */
+    calculateBackoffDelay(attempt, config, error) {
+        // Check for Retry-After header on 429
+        if (error && this.isRateLimitError(error)) {
+            const retryAfter = error.headers?.['retry-after'] || error.headers?.['Retry-After'];
+            if (retryAfter) {
+                const retryAfterMs = parseInt(String(retryAfter), 10) * 1000;
+                if (!isNaN(retryAfterMs) && retryAfterMs > 0) {
+                    return Math.min(retryAfterMs, config.maxDelayMs);
+                }
+                // Could also be a date string - handle that case too
+                const retryAfterDate = new Date(retryAfter);
+                if (!isNaN(retryAfterDate.getTime())) {
+                    const diffMs = retryAfterDate.getTime() - Date.now();
+                    if (diffMs > 0) {
+                        return Math.min(diffMs, config.maxDelayMs);
+                    }
+                }
+            }
+        }
+        // Exponential backoff: initialDelay * (multiplier ^ attempt)
+        const baseDelay = config.initialDelayMs * Math.pow(config.backoffMultiplier, attempt);
+        // Cap at max delay
+        const cappedDelay = Math.min(baseDelay, config.maxDelayMs);
+        // Add jitter: delay *= (0.5 + random * 0.5) = delay * [0.5, 1.0]
+        const jitter = 0.5 + Math.random() * 0.5;
+        return Math.floor(cappedDelay * jitter);
+    }
+    /**
+     * Validate context window size before sending request
+     */
+    validateContextWindow(provider, prompt, expectedTokens) {
+        // Use actual token count or estimate
+        const actualTokens = expectedTokens || (0, tokenUtils_1.estimateTokens)(prompt);
+        // Get provider's context limit
+        const contextLimit = PROVIDER_CONTEXT_LIMITS[provider] || PROVIDER_CONTEXT_LIMITS['default'];
+        // Estimate output tokens (rough guess: 25% of input for responses)
+        const estimatedOutputTokens = Math.floor(actualTokens * 0.25);
+        const totalTokens = actualTokens + estimatedOutputTokens;
+        if (totalTokens > contextLimit) {
+            // Find alternative providers with larger context
+            const largerProviders = Object.entries(PROVIDER_CONTEXT_LIMITS)
+                .filter(([name, limit]) => name !== provider && limit > contextLimit)
+                .sort(([, a], [, b]) => b - a);
+            const suggested = largerProviders.length > 0 ? largerProviders[0][0] : undefined;
+            return {
+                valid: false,
+                reason: `Context window exceeded: ${totalTokens} tokens (estimated) > ${contextLimit} limit for ${provider}`,
+                suggestedProvider: suggested,
+            };
+        }
+        return { valid: true };
+    }
+    /**
+     * Get retry statistics for a provider
+     */
+    getStats(provider) {
+        return this.stats.get(provider) || this.initStats(provider);
+    }
+    /**
+     * Get all provider stats
+     */
+    getAllStats() {
+        const result = {};
+        for (const [provider, stats] of this.stats.entries()) {
+            result[provider] = stats;
+        }
+        return result;
+    }
+    /**
+     * Reset stats for a provider
+     */
+    resetStats(provider) {
+        if (provider) {
+            this.initStats(provider);
+        }
+        else {
+            for (const provider of this.configs.keys()) {
+                this.initStats(provider);
+            }
+        }
+    }
+    // ============================================================
+    // PRIVATE HELPERS
+    // ============================================================
+    createTimeoutError(timeoutMs) {
+        const error = new Error(`Request timed out after ${timeoutMs}ms`);
+        error.code = 'ETIMEDOUT';
+        error.status = 408;
+        error.statusCode = 408;
+        return error;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    recordSuccess(provider, latencyMs) {
+        const stats = this.stats.get(provider);
+        if (!stats)
+            return;
+        stats.totalRequests++;
+        stats.successfulRequests++;
+        // Running average for latency
+        if (latencyMs > 0) {
+            const totalLatency = stats.averageLatencyMs * (stats.totalRequests - 1) + latencyMs;
+            stats.averageLatencyMs = totalLatency / stats.totalRequests;
+        }
+    }
+    recordFailure(provider, retryCount) {
+        const stats = this.stats.get(provider);
+        if (!stats)
+            return;
+        stats.totalRequests++;
+        stats.failedRequests++;
+        stats.totalRetries += retryCount;
+    }
+    recordRetry(provider, isRateLimit) {
+        const stats = this.stats.get(provider);
+        if (!stats)
+            return;
+        stats.totalRetries++;
+        if (isRateLimit) {
+            stats.rateLimitRetries++;
+        }
+    }
+}
+exports.ProviderRetryHandler = ProviderRetryHandler;
+// ============================================================
+// CONVENIENCE FUNCTIONS
+// ============================================================
+/**
+ * Create a retry handler with optional custom configs
+ */
+function createRetryHandler(customConfigs) {
+    return new ProviderRetryHandler(customConfigs);
+}
+/**
+ * Default retry handler instance (singleton)
+ */
+let defaultHandler = null;
+function getDefaultRetryHandler() {
+    if (!defaultHandler) {
+        defaultHandler = new ProviderRetryHandler();
+    }
+    return defaultHandler;
+}
+//# sourceMappingURL=providerRetry.js.map

package/dist/routing/providerRetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providerRetry.js","sourceRoot":"","sources":["../../src/routing/providerRetry.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;