ai.matey.core 0.2.0

package/dist/cjs/router.js

@@ -0,0 +1,1388 @@
+"use strict";
+/**
+ * Router Implementation
+ *
+ * The Router manages multiple backend adapters with intelligent routing,
+ * fallback strategies, circuit breaker pattern, and health checking.
+ * It implements the BackendAdapter interface so it can be used as a backend.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Router = void 0;
+exports.createRouter = createRouter;
+const ai_matey_errors_1 = require("ai.matey.errors");
+const capability_matcher_js_1 = require("./capability-matcher.js");
+const capability_inference_js_1 = require("./capability-inference.js");
+// ============================================================================
+// Router Implementation
+// ============================================================================
+/**
+ * Router manages multiple backend adapters with intelligent routing.
+ */
+class Router {
+    metadata;
+    config;
+    backends = new Map();
+    modelMapping = new Map(); // model -> backend (for routing)
+    modelTranslationMapping = new Map(); // model -> model (for translation)
+    backendTranslationMappings = new Map(); // backend -> (model -> model)
+    modelPatterns = [];
+    fallbackChain = [];
+    roundRobinIndex = 0;
+    healthCheckInterval;
+    // Stats
+    stats = {
+        totalRequests: 0,
+        successfulRequests: 0,
+        failedRequests: 0,
+        totalFallbacks: 0,
+        parallelRequests: 0,
+        sinceTimestamp: Date.now(),
+    };
+    constructor(config = {}) {
+        this.config = {
+            routingStrategy: config.routingStrategy ?? 'explicit',
+            fallbackStrategy: config.fallbackStrategy ?? 'sequential',
+            defaultBackend: config.defaultBackend,
+            healthCheckInterval: config.healthCheckInterval ?? 0,
+            enableCircuitBreaker: config.enableCircuitBreaker ?? false,
+            circuitBreakerThreshold: config.circuitBreakerThreshold ?? 5,
+            circuitBreakerTimeout: config.circuitBreakerTimeout ?? 60000,
+            trackLatency: config.trackLatency ?? true,
+            trackCost: config.trackCost ?? false,
+            capabilityBasedRouting: config.capabilityBasedRouting ?? false,
+            optimization: config.optimization ?? 'balanced',
+            optimizationWeights: config.optimizationWeights,
+            capabilityCacheDuration: config.capabilityCacheDuration ?? 3600000, // 1 hour
+            customRouter: config.customRouter,
+            customFallback: config.customFallback,
+            modelTranslation: config.modelTranslation ?? {
+                strategy: 'hybrid',
+                warnOnDefault: true,
+                strictMode: false,
+            },
+        };
+        this.metadata = {
+            name: 'router',
+            version: '1.0.0',
+            provider: 'Universal Router',
+            capabilities: {
+                streaming: true,
+                multiModal: true,
+                tools: true,
+                systemMessageStrategy: 'in-messages',
+                supportsMultipleSystemMessages: true,
+            },
+            config: this.config,
+        };
+        // Start health checking if enabled
+        if (this.config.healthCheckInterval && this.config.healthCheckInterval > 0) {
+            this.startHealthChecking();
+        }
+    }
+    // ==========================================================================
+    // Format Conversion (Not Applicable for Router)
+    // ==========================================================================
+    /**
+     * Convert IR request to provider format.
+     * Not applicable for Router - use the specific backend adapter instead.
+     */
+    fromIR(_request) {
+        throw new Error('fromIR() not applicable for Router - route to a specific backend first');
+    }
+    /**
+     * Convert provider response to IR format.
+     * Not applicable for Router - use the specific backend adapter instead.
+     */
+    toIR(_response, _originalRequest, _latencyMs) {
+        throw new Error('toIR() not applicable for Router - route to a specific backend first');
+    }
+    // ==========================================================================
+    // Backend Management
+    // ==========================================================================
+    /**
+     * Register a backend adapter.
+     */
+    register(name, adapter) {
+        if (this.backends.has(name)) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Backend '${name}' is already registered`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        this.backends.set(name, {
+            adapter,
+            isHealthy: true,
+            circuitBreakerState: 'closed',
+            consecutiveFailures: 0,
+            latencies: [],
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            totalCost: 0,
+        });
+        return this;
+    }
+    /**
+     * Unregister a backend adapter.
+     */
+    unregister(name) {
+        if (!this.backends.has(name)) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Backend '${name}' is not registered`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        // Check if it's the default backend
+        if (this.config.defaultBackend === name) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Cannot unregister default backend '${name}'`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        // Check if it's the last backend
+        if (this.backends.size === 1) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Cannot unregister last backend '${name}'`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        this.backends.delete(name);
+        return this;
+    }
+    /**
+     * Get a registered backend adapter.
+     */
+    get(name) {
+        return this.backends.get(name)?.adapter;
+    }
+    /**
+     * Check if backend is registered.
+     */
+    has(name) {
+        return this.backends.has(name);
+    }
+    /**
+     * List all registered backend names.
+     */
+    listBackends() {
+        return Array.from(this.backends.keys());
+    }
+    getBackendInfo(name) {
+        if (name !== undefined) {
+            const state = this.backends.get(name);
+            if (!state) {
+                return undefined;
+            }
+            return this.createBackendInfo(name, state);
+        }
+        const infos = [];
+        for (const [backendName, state] of this.backends.entries()) {
+            infos.push(this.createBackendInfo(backendName, state));
+        }
+        return infos;
+    }
+    // ==========================================================================
+    // Routing Configuration
+    // ==========================================================================
+    /**
+     * Set fallback chain for sequential failover.
+     */
+    setFallbackChain(chain) {
+        // Validate all backends exist
+        for (const name of chain) {
+            if (!this.backends.has(name)) {
+                throw new ai_matey_errors_1.AdapterError({
+                    code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                    message: `Backend '${name}' in fallback chain is not registered`,
+                    isRetryable: false,
+                    provenance: { router: this.metadata.name },
+                });
+            }
+        }
+        this.fallbackChain = [...chain];
+        return this;
+    }
+    /**
+     * Get current fallback chain.
+     */
+    getFallbackChain() {
+        return this.fallbackChain;
+    }
+    /**
+     * Set model to backend mapping.
+     */
+    setModelMapping(mapping) {
+        this.modelMapping.clear();
+        for (const [model, backend] of Object.entries(mapping)) {
+            if (!this.backends.has(backend)) {
+                throw new ai_matey_errors_1.AdapterError({
+                    code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                    message: `Backend '${String(backend)}' in model mapping is not registered`,
+                    isRetryable: false,
+                    provenance: { router: this.metadata.name },
+                });
+            }
+            this.modelMapping.set(model, backend);
+        }
+        return this;
+    }
+    /**
+     * Get current model mapping.
+     */
+    getModelMapping() {
+        const mapping = {};
+        for (const [model, backend] of this.modelMapping.entries()) {
+            mapping[model] = backend;
+        }
+        return mapping;
+    }
+    /**
+     * Set model name translation mapping (for fallback scenarios).
+     * Maps source model names to target model names.
+     *
+     * @example
+     * ```typescript
+     * router.setModelTranslationMapping({
+     *   'gpt-4': 'claude-3-5-sonnet-20241022',
+     *   'gpt-3.5-turbo': 'claude-3-5-haiku-20241022'
+     * });
+     * ```
+     */
+    setModelTranslationMapping(mapping) {
+        this.modelTranslationMapping.clear();
+        for (const [sourceModel, targetModel] of Object.entries(mapping)) {
+            this.modelTranslationMapping.set(sourceModel, targetModel);
+        }
+        return this;
+    }
+    /**
+     * Get current model translation mapping.
+     */
+    getModelTranslationMapping() {
+        const mapping = {};
+        for (const [source, target] of this.modelTranslationMapping.entries()) {
+            mapping[source] = target;
+        }
+        return mapping;
+    }
+    /**
+     * Set backend-specific model translation mapping.
+     * This takes priority over global model translation mapping.
+     *
+     * @example
+     * ```typescript
+     * router.setBackendTranslationMapping('anthropic', {
+     *   'gpt-4': 'claude-3-5-sonnet-20241022',
+     *   'gpt-3.5-turbo': 'claude-3-5-haiku-20241022'
+     * });
+     * ```
+     */
+    setBackendTranslationMapping(backendName, mapping) {
+        // Validate backend exists
+        if (!this.backends.has(backendName)) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Backend '${backendName}' is not registered`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        // Create or get existing backend mapping
+        let backendMapping = this.backendTranslationMappings.get(backendName);
+        if (!backendMapping) {
+            backendMapping = new Map();
+            this.backendTranslationMappings.set(backendName, backendMapping);
+        }
+        // Clear and populate mapping
+        backendMapping.clear();
+        for (const [sourceModel, targetModel] of Object.entries(mapping)) {
+            backendMapping.set(sourceModel, targetModel);
+        }
+        return this;
+    }
+    /**
+     * Get backend-specific model translation mapping.
+     */
+    getBackendTranslationMapping(backendName) {
+        const backendMapping = this.backendTranslationMappings.get(backendName);
+        if (!backendMapping) {
+            return {};
+        }
+        const mapping = {};
+        for (const [source, target] of backendMapping.entries()) {
+            mapping[source] = target;
+        }
+        return mapping;
+    }
+    /**
+     * Clear all model translation mappings.
+     *
+     * @returns This router for chaining
+     */
+    clearModelTranslationMapping() {
+        this.modelTranslationMapping.clear();
+        return this;
+    }
+    /**
+     * Clear backend-specific model translation mappings.
+     *
+     * @param backendName Optional backend name to clear. If not provided, clears all.
+     * @returns This router for chaining
+     */
+    clearBackendTranslationMapping(backendName) {
+        if (backendName) {
+            const backendMapping = this.backendTranslationMappings.get(backendName);
+            if (backendMapping) {
+                backendMapping.clear();
+            }
+        }
+        else {
+            for (const mapping of this.backendTranslationMappings.values()) {
+                mapping.clear();
+            }
+        }
+        return this;
+    }
+    /**
+     * Set model pattern mappings.
+     */
+    setModelPatterns(patterns) {
+        // Validate all backends exist
+        for (const pattern of patterns) {
+            if (!this.backends.has(pattern.backend)) {
+                throw new ai_matey_errors_1.AdapterError({
+                    code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                    message: `Backend '${pattern.backend}' in model pattern is not registered`,
+                    isRetryable: false,
+                    provenance: { router: this.metadata.name },
+                });
+            }
+        }
+        this.modelPatterns = [...patterns];
+        return this;
+    }
+    /**
+     * Get current model patterns.
+     */
+    getModelPatterns() {
+        return this.modelPatterns;
+    }
+    // ==========================================================================
+    // Routing Operations
+    // ==========================================================================
+    /**
+     * Select backend for a request.
+     */
+    async selectBackend(request, preferredBackend) {
+        const context = {
+            stats: this.getStats(),
+            metadata: request.metadata?.custom ?? {},
+            preferredBackend,
+        };
+        // Try explicit preference first
+        if (preferredBackend && this.isBackendAvailable(preferredBackend)) {
+            return preferredBackend;
+        }
+        // Try capability-based routing if enabled
+        if (this.config.capabilityBasedRouting) {
+            const capabilityBackend = await this.selectBackendByCapabilities(request);
+            if (capabilityBackend) {
+                return capabilityBackend;
+            }
+        }
+        // Apply routing strategy
+        const strategy = this.config.routingStrategy ?? 'explicit';
+        let selectedBackend = null;
+        switch (strategy) {
+            case 'explicit':
+                selectedBackend = this.routeExplicit(preferredBackend);
+                break;
+            case 'model-based':
+                selectedBackend = this.routeByModel(request);
+                break;
+            case 'cost-optimized':
+                selectedBackend = this.routeByCost(request);
+                break;
+            case 'latency-optimized':
+                selectedBackend = this.routeByLatency();
+                break;
+            case 'round-robin':
+                selectedBackend = this.routeRoundRobin();
+                break;
+            case 'random':
+                selectedBackend = this.routeRandom();
+                break;
+            case 'custom':
+                if (this.config.customRouter) {
+                    selectedBackend = await this.config.customRouter(request, this.getAvailableBackends(), context);
+                }
+                break;
+        }
+        // Fallback to default backend
+        if (!selectedBackend && this.config.defaultBackend) {
+            selectedBackend = this.config.defaultBackend;
+        }
+        // Final fallback: first available backend
+        if (!selectedBackend) {
+            const available = this.getAvailableBackends();
+            selectedBackend = available[0] ?? null;
+        }
+        if (!selectedBackend) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.NO_BACKEND_AVAILABLE,
+                message: 'No available backend for routing',
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        return selectedBackend;
+    }
+    /**
+     * Execute request with automatic backend selection and fallback.
+     */
+    async execute(request, signal) {
+        this.stats.totalRequests++;
+        const preferredBackend = request.metadata?.custom?.backend;
+        const attemptedBackends = [];
+        try {
+            // Select primary backend
+            const primaryBackend = await this.selectBackend(request, preferredBackend);
+            attemptedBackends.push(primaryBackend);
+            // Translate model for this backend
+            const originalModel = request.parameters?.model ?? '';
+            const translationResult = this.translateModelForBackend(originalModel, primaryBackend);
+            // Create request with translated model
+            const translatedRequest = {
+                ...request,
+                parameters: {
+                    ...request.parameters,
+                    model: translationResult.translated,
+                },
+            };
+            // Try primary backend
+            const response = await this.executeOnBackend(primaryBackend, translatedRequest, signal);
+            this.stats.successfulRequests++;
+            return response;
+        }
+        catch (primaryError) {
+            // Handle fallback
+            if (this.config.fallbackStrategy === 'none') {
+                this.stats.failedRequests++;
+                throw primaryError;
+            }
+            try {
+                const response = await this.executeFallback(request, attemptedBackends, primaryError, signal);
+                this.stats.successfulRequests++;
+                this.stats.totalFallbacks++;
+                return response;
+            }
+            catch (fallbackError) {
+                this.stats.failedRequests++;
+                throw fallbackError;
+            }
+        }
+    }
+    /**
+     * Execute streaming request with automatic backend selection and fallback.
+     */
+    async *executeStream(request, signal) {
+        this.stats.totalRequests++;
+        const preferredBackend = request.metadata?.custom?.backend;
+        const attemptedBackends = [];
+        try {
+            // Select primary backend
+            const primaryBackend = await this.selectBackend(request, preferredBackend);
+            attemptedBackends.push(primaryBackend);
+            // Translate model for this backend
+            const originalModel = request.parameters?.model ?? '';
+            const translationResult = this.translateModelForBackend(originalModel, primaryBackend);
+            // Create request with translated model
+            const translatedRequest = {
+                ...request,
+                parameters: {
+                    ...request.parameters,
+                    model: translationResult.translated,
+                },
+            };
+            // Try primary backend streaming
+            const stream = this.executeStreamOnBackend(primaryBackend, translatedRequest, signal);
+            for await (const chunk of stream) {
+                yield chunk;
+            }
+            this.stats.successfulRequests++;
+        }
+        catch (primaryError) {
+            // For streaming, fallback is more complex - yield error chunk
+            this.stats.failedRequests++;
+            yield {
+                type: 'error',
+                sequence: 0,
+                error: {
+                    code: primaryError instanceof ai_matey_errors_1.AdapterError ? primaryError.code : 'UNKNOWN_ERROR',
+                    message: primaryError instanceof Error ? primaryError.message : String(primaryError),
+                },
+            };
+        }
+    }
+    /**
+     * Dispatch request to multiple backends in parallel.
+     */
+    async dispatchParallel(request, options = {}, signal) {
+        this.stats.totalRequests++;
+        this.stats.parallelRequests++;
+        const { backends: targetBackends, strategy = 'first', timeout, cancelOnFirstSuccess = true, } = options;
+        // Determine which backends to use
+        const backendsToUse = targetBackends && targetBackends.length > 0
+            ? targetBackends.filter((name) => this.isBackendAvailable(name))
+            : this.getAvailableBackends();
+        if (backendsToUse.length === 0) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.NO_BACKEND_AVAILABLE,
+                message: 'No available backends for parallel dispatch',
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        const startTime = Date.now();
+        const abortController = new AbortController();
+        const combinedSignal = signal
+            ? this.combineSignals([signal, abortController.signal])
+            : abortController.signal;
+        // Create timeout if specified
+        let timeoutId;
+        if (timeout) {
+            timeoutId = setTimeout(() => abortController.abort(), timeout);
+        }
+        try {
+            const promises = backendsToUse.map(async (backendName) => {
+                const backendStartTime = Date.now();
+                try {
+                    const response = await this.executeOnBackend(backendName, request, combinedSignal);
+                    return {
+                        backend: backendName,
+                        response,
+                        latencyMs: Date.now() - backendStartTime,
+                        success: true,
+                    };
+                }
+                catch (error) {
+                    return {
+                        backend: backendName,
+                        error: error instanceof ai_matey_errors_1.AdapterError ? error : this.wrapError(error),
+                        success: false,
+                    };
+                }
+            });
+            let results;
+            if (strategy === 'first') {
+                // Return first successful response
+                const firstSuccess = await Promise.race(promises);
+                if (cancelOnFirstSuccess) {
+                    abortController.abort();
+                }
+                results = [firstSuccess];
+            }
+            else {
+                // Wait for all responses
+                results = await Promise.all(promises);
+            }
+            // Process results
+            const successful = results.filter((r) => r.success);
+            const failed = results
+                .filter((r) => !r.success)
+                .map((r) => ({
+                backend: r.backend,
+                error: r.error,
+            }));
+            if (successful.length === 0) {
+                throw new ai_matey_errors_1.AdapterError({
+                    code: ai_matey_errors_1.ErrorCode.ALL_BACKENDS_FAILED,
+                    message: `All parallel backends failed: ${failed.map((f) => f.backend).join(', ')}`,
+                    isRetryable: true,
+                    provenance: { router: this.metadata.name },
+                });
+            }
+            const firstSuccess = successful[0];
+            if (!firstSuccess?.response) {
+                throw new ai_matey_errors_1.AdapterError({
+                    code: ai_matey_errors_1.ErrorCode.INTERNAL_ERROR,
+                    message: 'No successful response in parallel dispatch',
+                    isRetryable: false,
+                    provenance: { router: this.metadata.name },
+                });
+            }
+            return {
+                response: firstSuccess.response,
+                allResponses: strategy === 'all'
+                    ? successful.map((s) => ({
+                        backend: s.backend,
+                        response: s.response,
+                        latencyMs: s.latencyMs,
+                    }))
+                    : undefined,
+                successfulBackends: successful.map((s) => s.backend),
+                failedBackends: failed,
+                totalTimeMs: Date.now() - startTime,
+            };
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    async checkHealth(name) {
+        if (name !== undefined) {
+            const state = this.backends.get(name);
+            if (!state) {
+                return false;
+            }
+            try {
+                const healthy = state.adapter.healthCheck ? await state.adapter.healthCheck() : true;
+                state.isHealthy = healthy;
+                state.lastHealthCheck = Date.now();
+                return healthy;
+            }
+            catch {
+                state.isHealthy = false;
+                state.lastHealthCheck = Date.now();
+                return false;
+            }
+        }
+        // Check all backends
+        const results = {};
+        const promises = Array.from(this.backends.entries()).map(async ([backendName, state]) => {
+            try {
+                const healthy = state.adapter.healthCheck ? await state.adapter.healthCheck() : true;
+                state.isHealthy = healthy;
+                state.lastHealthCheck = Date.now();
+                results[backendName] = healthy;
+            }
+            catch {
+                state.isHealthy = false;
+                state.lastHealthCheck = Date.now();
+                results[backendName] = false;
+            }
+        });
+        await Promise.all(promises);
+        return results;
+    }
+    /**
+     * Manually open circuit breaker for a backend.
+     */
+    openCircuitBreaker(name, timeoutMs) {
+        const state = this.backends.get(name);
+        if (!state) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Backend '${name}' not found`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        state.circuitBreakerState = 'open';
+        state.circuitOpenedAt = Date.now();
+        // Auto-close after timeout
+        if (timeoutMs ?? this.config.circuitBreakerTimeout) {
+            setTimeout(() => {
+                if (state.circuitBreakerState === 'open') {
+                    state.circuitBreakerState = 'half-open';
+                }
+            }, timeoutMs ?? this.config.circuitBreakerTimeout);
+        }
+    }
+    /**
+     * Manually close circuit breaker for a backend.
+     */
+    closeCircuitBreaker(name) {
+        const state = this.backends.get(name);
+        if (!state) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Backend '${name}' not found`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        state.circuitBreakerState = 'closed';
+        state.consecutiveFailures = 0;
+        state.circuitOpenedAt = undefined;
+    }
+    /**
+     * Reset circuit breaker statistics.
+     */
+    resetCircuitBreaker(name) {
+        if (name) {
+            const state = this.backends.get(name);
+            if (state) {
+                state.consecutiveFailures = 0;
+                state.circuitBreakerState = 'closed';
+                state.circuitOpenedAt = undefined;
+            }
+        }
+        else {
+            for (const state of this.backends.values()) {
+                state.consecutiveFailures = 0;
+                state.circuitBreakerState = 'closed';
+                state.circuitOpenedAt = undefined;
+            }
+        }
+    }
+    /**
+     * Check if circuit breaker is open for a backend.
+     *
+     * @param name Backend name
+     * @returns true if circuit breaker is open, false otherwise
+     */
+    isCircuitBreakerOpen(name) {
+        const state = this.backends.get(name);
+        if (!state) {
+            return false;
+        }
+        return state.circuitBreakerState === 'open';
+    }
+    // ==========================================================================
+    // Statistics & Monitoring
+    // ==========================================================================
+    /**
+     * Get router statistics.
+     */
+    getStats() {
+        const backendStats = {};
+        for (const [name, state] of this.backends.entries()) {
+            backendStats[name] = this.calculateBackendStats(state);
+        }
+        return {
+            totalRequests: this.stats.totalRequests,
+            successfulRequests: this.stats.successfulRequests,
+            failedRequests: this.stats.failedRequests,
+            totalFallbacks: this.stats.totalFallbacks,
+            parallelRequests: this.stats.parallelRequests,
+            backendStats,
+            sinceTimestamp: this.stats.sinceTimestamp,
+        };
+    }
+    /**
+     * Reset router statistics.
+     */
+    resetStats() {
+        this.stats = {
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            totalFallbacks: 0,
+            parallelRequests: 0,
+            sinceTimestamp: Date.now(),
+        };
+        for (const state of this.backends.values()) {
+            state.totalRequests = 0;
+            state.successfulRequests = 0;
+            state.failedRequests = 0;
+            state.latencies = [];
+            state.totalCost = 0;
+        }
+    }
+    /**
+     * Get statistics for specific backend.
+     */
+    getBackendStats(name) {
+        const state = this.backends.get(name);
+        if (!state) {
+            return undefined;
+        }
+        return this.calculateBackendStats(state);
+    }
+    // ==========================================================================
+    // Utility Methods
+    // ==========================================================================
+    /**
+     * Clone router with new configuration.
+     */
+    clone(config) {
+        const newRouter = new Router({ ...this.config, ...config });
+        // Copy backend registrations
+        for (const [name, state] of this.backends.entries()) {
+            newRouter.register(name, state.adapter);
+        }
+        // Copy model mappings
+        newRouter.modelMapping = new Map(this.modelMapping);
+        newRouter.modelPatterns = [...this.modelPatterns];
+        newRouter.fallbackChain = [...this.fallbackChain];
+        return newRouter;
+    }
+    /**
+     * Clean up resources.
+     */
+    dispose() {
+        if (this.healthCheckInterval) {
+            clearInterval(this.healthCheckInterval);
+            this.healthCheckInterval = undefined;
+        }
+    }
+    // ==========================================================================
+    // Private Helper Methods
+    // ==========================================================================
+    /**
+     * Execute request on specific backend.
+     */
+    async executeOnBackend(name, request, signal) {
+        const state = this.backends.get(name);
+        if (!state) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Backend '${name}' not found`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        // Check circuit breaker
+        if (this.config.enableCircuitBreaker) {
+            this.checkCircuitBreaker(name, state);
+        }
+        state.totalRequests++;
+        const startTime = Date.now();
+        try {
+            const response = await state.adapter.execute(request, signal);
+            // Track success
+            state.successfulRequests++;
+            state.consecutiveFailures = 0;
+            if (this.config.trackLatency) {
+                const latency = Date.now() - startTime;
+                state.latencies.push(latency);
+                // Keep only last 100 latencies
+                if (state.latencies.length > 100) {
+                    state.latencies.shift();
+                }
+            }
+            // Track cost
+            if (this.config.trackCost && state.adapter.estimateCost) {
+                const cost = await state.adapter.estimateCost(request);
+                if (cost !== null) {
+                    state.totalCost += cost;
+                }
+            }
+            // Update circuit breaker
+            if (state.circuitBreakerState === 'half-open') {
+                state.circuitBreakerState = 'closed';
+            }
+            return response;
+        }
+        catch (error) {
+            // Track failure
+            state.failedRequests++;
+            state.consecutiveFailures++;
+            // Update circuit breaker
+            if (this.config.enableCircuitBreaker &&
+                state.consecutiveFailures >= (this.config.circuitBreakerThreshold ?? 5)) {
+                this.openCircuitBreaker(name);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Execute streaming request on specific backend.
+     */
+    executeStreamOnBackend(name, request, signal) {
+        const state = this.backends.get(name);
+        if (!state) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `Backend '${name}' not found`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        // Check circuit breaker
+        if (this.config.enableCircuitBreaker) {
+            this.checkCircuitBreaker(name, state);
+        }
+        state.totalRequests++;
+        return state.adapter.executeStream(request, signal);
+    }
+    /**
+     * Execute fallback strategy.
+     */
+    async executeFallback(request, attemptedBackends, error, signal) {
+        const strategy = this.config.fallbackStrategy ?? 'sequential';
+        if (strategy === 'sequential') {
+            return this.fallbackSequential(request, attemptedBackends, signal);
+        }
+        else if (strategy === 'parallel') {
+            return this.fallbackParallel(request, attemptedBackends, signal);
+        }
+        else if (strategy === 'custom' && this.config.customFallback) {
+            const available = this.getAvailableBackends().filter((name) => !attemptedBackends.includes(name));
+            const nextBackend = await this.config.customFallback(request, attemptedBackends[attemptedBackends.length - 1], error, attemptedBackends, available);
+            if (nextBackend && !attemptedBackends.includes(nextBackend)) {
+                attemptedBackends.push(nextBackend);
+                return this.executeOnBackend(nextBackend, request, signal);
+            }
+        }
+        throw error;
+    }
+    /**
+     * Translate model name for a specific backend.
+     *
+     * Applies translation strategy: backend-specific exact → global exact → pattern → default → passthrough
+     */
+    translateModelForBackend(modelName, backendName) {
+        const strategy = this.config.modelTranslation?.strategy ?? 'hybrid';
+        const strictMode = this.config.modelTranslation?.strictMode ?? false;
+        // 0. Try backend-specific exact match (highest priority)
+        if (strategy !== 'none') {
+            const backendMapping = this.backendTranslationMappings.get(backendName);
+            if (backendMapping) {
+                const backendExactMatch = backendMapping.get(modelName);
+                if (backendExactMatch) {
+                    return {
+                        translated: backendExactMatch,
+                        source: 'exact',
+                        wasTranslated: true,
+                    };
+                }
+            }
+        }
+        // 1. Try global exact match (all strategies except 'none')
+        if (strategy !== 'none') {
+            const exactMatch = this.modelTranslationMapping.get(modelName);
+            if (exactMatch) {
+                return {
+                    translated: exactMatch,
+                    source: 'exact',
+                    wasTranslated: true,
+                };
+            }
+        }
+        // 2. Try pattern match (pattern and hybrid strategies)
+        if (strategy === 'pattern' || strategy === 'hybrid') {
+            // Sort patterns by priority (higher priority first)
+            const sortedPatterns = [...this.modelPatterns].sort((a, b) => {
+                const priorityA = a.priority ?? 0;
+                const priorityB = b.priority ?? 0;
+                return priorityB - priorityA;
+            });
+            for (const patternMapping of sortedPatterns) {
+                if (patternMapping.pattern.test(modelName)) {
+                    // Use targetModel if specified, otherwise original model
+                    const translated = patternMapping.targetModel ?? modelName;
+                    return {
+                        translated,
+                        source: 'pattern',
+                        wasTranslated: patternMapping.targetModel !== undefined,
+                    };
+                }
+            }
+        }
+        // 3. Try backend default (hybrid strategy only)
+        if (strategy === 'hybrid') {
+            const backendState = this.backends.get(backendName);
+            const adapter = backendState?.adapter;
+            const defaultModel = adapter?.config?.defaultModel;
+            if (defaultModel) {
+                // TODO: Emit warning event when warnOnDefault is true
+                // For now, the translation result indicates wasTranslated=true
+                return {
+                    translated: defaultModel,
+                    source: 'default',
+                    wasTranslated: true,
+                };
+            }
+        }
+        // 4. No translation found
+        if (strictMode) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ROUTING_FAILED,
+                message: `No translation found for model: ${modelName}`,
+                isRetryable: false,
+                provenance: { router: this.metadata.name, backend: backendName },
+            });
+        }
+        // Return original model (passthrough)
+        return {
+            translated: modelName,
+            source: 'none',
+            wasTranslated: false,
+        };
+    }
+    /**
+     * Sequential fallback: try backends one by one.
+     */
+    async fallbackSequential(request, attemptedBackends, signal) {
+        const available = this.getAvailableBackends().filter((name) => !attemptedBackends.includes(name));
+        // Use fallback chain if configured
+        const candidates = this.fallbackChain.length > 0
+            ? this.fallbackChain.filter((name) => available.includes(name))
+            : available;
+        let lastError;
+        for (const backendName of candidates) {
+            try {
+                attemptedBackends.push(backendName);
+                // Translate model for this backend
+                const originalModel = request.parameters?.model ?? '';
+                const translationResult = this.translateModelForBackend(originalModel, backendName);
+                // Create request with translated model
+                const translatedRequest = {
+                    ...request,
+                    parameters: {
+                        ...request.parameters,
+                        model: translationResult.translated,
+                    },
+                };
+                return await this.executeOnBackend(backendName, translatedRequest, signal);
+            }
+            catch (error) {
+                lastError = error;
+                continue;
+            }
+        }
+        throw (lastError ??
+            new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.ALL_BACKENDS_FAILED,
+                message: 'All fallback backends failed',
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            }));
+    }
+    /**
+     * Parallel fallback: try all remaining backends at once.
+     */
+    async fallbackParallel(request, attemptedBackends, signal) {
+        const available = this.getAvailableBackends().filter((name) => !attemptedBackends.includes(name));
+        if (available.length === 0) {
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.NO_BACKEND_AVAILABLE,
+                message: 'No available fallback backends',
+                isRetryable: false,
+                provenance: { router: this.metadata.name },
+            });
+        }
+        // Create promises with model translation for each backend
+        const originalModel = request.parameters?.model ?? '';
+        const promises = available.map((backendName) => {
+            // Translate model for this backend
+            const translationResult = this.translateModelForBackend(originalModel, backendName);
+            // Create request with translated model
+            const translatedRequest = {
+                ...request,
+                parameters: {
+                    ...request.parameters,
+                    model: translationResult.translated,
+                },
+            };
+            return this.executeOnBackend(backendName, translatedRequest, signal);
+        });
+        return Promise.race(promises);
+    }
+    /**
+     * Check circuit breaker state.
+     */
+    checkCircuitBreaker(name, state) {
+        if (state.circuitBreakerState === 'open') {
+            // Check if timeout has passed
+            const timeout = this.config.circuitBreakerTimeout ?? 60000;
+            if (state.circuitOpenedAt && Date.now() - state.circuitOpenedAt > timeout) {
+                state.circuitBreakerState = 'half-open';
+            }
+            else {
+                throw new ai_matey_errors_1.AdapterError({
+                    code: ai_matey_errors_1.ErrorCode.PROVIDER_UNAVAILABLE,
+                    message: `Circuit breaker is open for backend '${name}'`,
+                    isRetryable: true,
+                    provenance: { router: this.metadata.name, backend: name },
+                });
+            }
+        }
+    }
+    /**
+     * Get list of available backends.
+     */
+    getAvailableBackends() {
+        const available = [];
+        for (const [name, state] of this.backends.entries()) {
+            if (state.isHealthy && state.circuitBreakerState !== 'open') {
+                available.push(name);
+            }
+        }
+        return available;
+    }
+    /**
+     * Check if backend is available.
+     */
+    isBackendAvailable(name) {
+        const state = this.backends.get(name);
+        if (!state) {
+            return false;
+        }
+        return state.isHealthy && state.circuitBreakerState !== 'open';
+    }
+    /**
+     * Routing: explicit backend selection.
+     */
+    routeExplicit(preferredBackend) {
+        if (preferredBackend && this.isBackendAvailable(preferredBackend)) {
+            return preferredBackend;
+        }
+        return null;
+    }
+    /**
+     * Routing: model-based selection.
+     */
+    routeByModel(request) {
+        const model = request.parameters?.model;
+        if (!model) {
+            return null;
+        }
+        // Check exact mapping
+        const exactMatch = this.modelMapping.get(model);
+        if (exactMatch && this.isBackendAvailable(exactMatch)) {
+            return exactMatch;
+        }
+        // Check pattern matching
+        for (const pattern of this.modelPatterns) {
+            if (pattern.pattern.test(model) && this.isBackendAvailable(pattern.backend)) {
+                return pattern.backend;
+            }
+        }
+        return null;
+    }
+    /**
+     * Routing: cost-optimized selection.
+     */
+    routeByCost(_request) {
+        if (!this.config.trackCost) {
+            return null;
+        }
+        let bestBackend = null;
+        let lowestAvgCost = Infinity;
+        for (const [name, state] of this.backends.entries()) {
+            if (!this.isBackendAvailable(name)) {
+                continue;
+            }
+            const stats = this.calculateBackendStats(state);
+            const avgCost = stats.averageCost ?? 0;
+            if (avgCost < lowestAvgCost) {
+                lowestAvgCost = avgCost;
+                bestBackend = name;
+            }
+        }
+        return bestBackend;
+    }
+    /**
+     * Routing: latency-optimized selection.
+     */
+    routeByLatency() {
+        if (!this.config.trackLatency) {
+            return null;
+        }
+        let bestBackend = null;
+        let lowestLatency = Infinity;
+        for (const [name, state] of this.backends.entries()) {
+            if (!this.isBackendAvailable(name)) {
+                continue;
+            }
+            const stats = this.calculateBackendStats(state);
+            const avgLatency = stats.averageLatencyMs;
+            if (avgLatency < lowestLatency) {
+                lowestLatency = avgLatency;
+                bestBackend = name;
+            }
+        }
+        return bestBackend;
+    }
+    /**
+     * Routing: round-robin selection.
+     */
+    routeRoundRobin() {
+        const available = this.getAvailableBackends();
+        if (available.length === 0) {
+            return null;
+        }
+        const backend = available[this.roundRobinIndex % available.length];
+        this.roundRobinIndex++;
+        return backend ?? null;
+    }
+    /**
+     * Routing: random selection.
+     */
+    routeRandom() {
+        const available = this.getAvailableBackends();
+        if (available.length === 0) {
+            return null;
+        }
+        const index = Math.floor(Math.random() * available.length);
+        return available[index] ?? null;
+    }
+    /**
+     * Select backend based on capability requirements.
+     * Returns the backend name with the best matching model, or null if none match.
+     */
+    async selectBackendByCapabilities(request) {
+        // Extract capability requirements from request metadata
+        const capabilityRequirements = request.metadata?.custom?.capabilityRequirements;
+        // Build requirements from config if not provided
+        const requirements = {
+            required: capabilityRequirements?.required,
+            preferred: capabilityRequirements?.preferred,
+            optimization: capabilityRequirements?.optimization ?? this.config.optimization ?? 'balanced',
+            weights: capabilityRequirements?.weights ?? this.config.optimizationWeights,
+        };
+        // Collect available models from all backends
+        const availableModels = [];
+        for (const backendName of this.getAvailableBackends()) {
+            const backend = this.backends.get(backendName)?.adapter;
+            if (!backend) {
+                continue;
+            }
+            // Try to get models from backend's listModels()
+            if (typeof backend.listModels === 'function') {
+                try {
+                    const result = await backend.listModels();
+                    for (const model of result.models) {
+                        availableModels.push({ model, backend: backendName });
+                    }
+                }
+                catch {
+                    // If listModels fails, try to infer from requested model
+                    const requestedModel = request.parameters?.model;
+                    if (requestedModel) {
+                        const inferredModel = {
+                            id: requestedModel,
+                            name: requestedModel,
+                            capabilities: (0, capability_inference_js_1.inferCapabilities)(requestedModel),
+                        };
+                        availableModels.push({ model: inferredModel, backend: backendName });
+                    }
+                }
+            }
+            else {
+                // Backend doesn't support listModels, try to infer from requested model
+                const requestedModel = request.parameters?.model;
+                if (requestedModel) {
+                    const inferredModel = {
+                        id: requestedModel,
+                        name: requestedModel,
+                        capabilities: (0, capability_inference_js_1.inferCapabilities)(requestedModel),
+                    };
+                    availableModels.push({ model: inferredModel, backend: backendName });
+                }
+            }
+        }
+        if (availableModels.length === 0) {
+            return null;
+        }
+        // Find best match
+        const bestMatch = (0, capability_matcher_js_1.findBestModel)(requirements, availableModels);
+        if (!bestMatch?.meetsRequirements) {
+            return null;
+        }
+        return bestMatch.backend;
+    }
+    /**
+     * Calculate backend statistics.
+     */
+    calculateBackendStats(state) {
+        const successRate = state.totalRequests > 0 ? (state.successfulRequests / state.totalRequests) * 100 : 0;
+        const sortedLatencies = [...state.latencies].sort((a, b) => a - b);
+        const avgLatency = sortedLatencies.length > 0
+            ? sortedLatencies.reduce((a, b) => a + b, 0) / sortedLatencies.length
+            : 0;
+        const p50 = sortedLatencies[Math.floor(sortedLatencies.length * 0.5)] ?? 0;
+        const p95 = sortedLatencies[Math.floor(sortedLatencies.length * 0.95)] ?? 0;
+        const p99 = sortedLatencies[Math.floor(sortedLatencies.length * 0.99)] ?? 0;
+        const avgCost = state.totalRequests > 0 ? state.totalCost / state.totalRequests : 0;
+        return {
+            totalRequests: state.totalRequests,
+            successfulRequests: state.successfulRequests,
+            failedRequests: state.failedRequests,
+            successRate,
+            averageLatencyMs: avgLatency,
+            p50LatencyMs: p50,
+            p95LatencyMs: p95,
+            p99LatencyMs: p99,
+            totalCost: this.config.trackCost ? state.totalCost : undefined,
+            averageCost: this.config.trackCost ? avgCost : undefined,
+        };
+    }
+    /**
+     * Create backend info from state.
+     */
+    createBackendInfo(name, state) {
+        return {
+            name,
+            adapter: state.adapter,
+            metadata: state.adapter.metadata,
+            isHealthy: state.isHealthy,
+            lastHealthCheck: state.lastHealthCheck,
+            circuitBreakerState: state.circuitBreakerState,
+            consecutiveFailures: state.consecutiveFailures,
+            stats: this.calculateBackendStats(state),
+        };
+    }
+    /**
+     * Start periodic health checking.
+     */
+    startHealthChecking() {
+        if (this.healthCheckInterval) {
+            return;
+        }
+        const interval = this.config.healthCheckInterval ?? 0;
+        if (interval <= 0) {
+            return;
+        }
+        this.healthCheckInterval = setInterval(() => {
+            this.checkHealth().catch(() => {
+                // Ignore errors in background health checks
+            });
+        }, interval);
+    }
+    /**
+     * Combine multiple abort signals.
+     */
+    combineSignals(signals) {
+        const controller = new AbortController();
+        for (const signal of signals) {
+            if (signal.aborted) {
+                controller.abort();
+                break;
+            }
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+        return controller.signal;
+    }
+    /**
+     * Wrap unknown error as AdapterError.
+     */
+    wrapError(error) {
+        if (error instanceof ai_matey_errors_1.AdapterError) {
+            return error;
+        }
+        return new ai_matey_errors_1.AdapterError({
+            code: ai_matey_errors_1.ErrorCode.INTERNAL_ERROR,
+            message: error instanceof Error ? error.message : String(error),
+            isRetryable: false,
+            provenance: { router: this.metadata.name },
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+}
+exports.Router = Router;
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new Router instance.
+ */
+function createRouter(config) {
+    return new Router(config);
+}
+//# sourceMappingURL=router.js.map