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

package/dist/observability/tracer.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTracer = getTracer;
+exports.createTracer = createTracer;
+const events_1 = require("events");
+function generateId() {
+    return Math.random().toString(36).substring(2, 15) +
+        Math.random().toString(36).substring(2, 15);
+}
+class Tracer extends events_1.EventEmitter {
+    traces = new Map();
+    routeTraces = [];
+    langfuseClient;
+    langfuseConfig;
+    constructor() {
+        super();
+    }
+    /**
+     * Initialize Langfuse if configured
+     */
+    initLangfuse(config) {
+        if (!config.publicKey || !config.secretKey) {
+            console.warn('[Tracer] Langfuse keys not provided, running without Langfuse');
+            return;
+        }
+        this.langfuseConfig = config;
+        // Simple Langfuse REST client
+        this.langfuseClient = {
+            trace: async (data) => {
+                try {
+                    const response = await fetch(`${config.baseUrl || 'https://cloud.langfuse.com'}/api/public/ingestion`, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'Authorization': `Bearer ${config.publicKey}`,
+                        },
+                        body: JSON.stringify(data),
+                    });
+                    if (!response.ok) {
+                        console.warn('[Tracer] Langfuse ingestion failed:', response.status);
+                    }
+                }
+                catch (err) {
+                    console.warn('[Tracer] Langfuse error:', err);
+                }
+            },
+            flush: async () => {
+                // Langfuse uses async ingestion, noop here
+            },
+        };
+        console.log('[Tracer] Langfuse initialized');
+    }
+    /**
+     * Create a new trace span
+     */
+    startSpan(operationName, parentSpanId) {
+        const traceId = parentSpanId
+            ? this.traces.get(parentSpanId)?.traceId || this.generateTraceId()
+            : this.generateTraceId();
+        const span = {
+            traceId,
+            spanId: this.generateTraceId(),
+            parentSpanId,
+            operationName,
+            startTime: Date.now(),
+            attributes: {},
+            status: 'started',
+        };
+        this.traces.set(span.spanId, span);
+        this.emit('span_started', span);
+        this.emit('observability_event', { type: 'span_started', span });
+        return span;
+    }
+    /**
+     * End a span
+     */
+    endSpan(spanId, attributes) {
+        const span = this.traces.get(spanId);
+        if (!span) {
+            console.warn(`[Tracer] span ${spanId} not found`);
+            return;
+        }
+        span.endTime = Date.now();
+        span.duration = span.endTime - span.startTime;
+        span.status = 'completed';
+        if (attributes) {
+            span.attributes = { ...span.attributes, ...attributes };
+        }
+        this.emit('span_completed', span);
+        this.emit('observability_event', { type: 'span_completed', span });
+    }
+    /**
+     * Record an error on a span
+     */
+    errorSpan(spanId, error, attributes) {
+        const span = this.traces.get(spanId);
+        if (!span) {
+            console.warn(`[Tracer] span ${spanId} not found`);
+            return;
+        }
+        span.endTime = Date.now();
+        span.duration = span.endTime - span.startTime;
+        span.status = 'error';
+        span.error = error;
+        if (attributes) {
+            span.attributes = { ...span.attributes, ...attributes };
+        }
+        this.emit('error', spanId, error);
+        this.emit('observability_event', { type: 'error', spanId, error });
+    }
+    /**
+     * Record a route decision
+     */
+    recordRoute(trace) {
+        this.routeTraces.push(trace);
+        // Emit event
+        this.emit('route_complete', trace);
+        this.emit('observability_event', { type: 'route_complete', trace });
+        // Export to Langfuse async
+        if (this.langfuseClient) {
+            this.langfuseClient.trace({
+                name: 'route_decision',
+                traceId: trace.traceId,
+                timestamp: new Date(trace.timestamp).toISOString(),
+                input: { query: trace.query },
+                output: {
+                    model: trace.model,
+                    provider: trace.provider,
+                    tokens: trace.queryTokens + trace.responseTokens,
+                    latencyMs: trace.latencyMs,
+                    cost: trace.cost,
+                },
+                metadata: {
+                    queryTokens: trace.queryTokens,
+                    responseTokens: trace.responseTokens,
+                    cacheHit: trace.cacheHit,
+                    complexity: trace.complexity,
+                    tier: trace.tier,
+                },
+            }).catch(() => { }); // Fire and forget
+        }
+    }
+    /**
+     * Generate a unique trace ID
+     */
+    generateTraceId() {
+        return generateId();
+    }
+    /**
+     * Get all route traces
+     */
+    getTraces(limit) {
+        if (limit) {
+            return this.routeTraces.slice(-limit);
+        }
+        return [...this.routeTraces];
+    }
+    /**
+     * Get all spans for a trace
+     */
+    getSpans(traceId) {
+        return Array.from(this.traces.values()).filter(s => s.traceId === traceId);
+    }
+    /**
+     * Export to Langfuse (async, non-blocking)
+     */
+    async flushToLangfuse() {
+        if (this.langfuseClient) {
+            await this.langfuseClient.flush();
+        }
+    }
+    /**
+     * Clear all traces (for testing)
+     */
+    reset() {
+        this.traces.clear();
+        this.routeTraces = [];
+    }
+}
+// Singleton instance
+let tracerInstance = null;
+function getTracer() {
+    if (!tracerInstance) {
+        tracerInstance = new Tracer();
+    }
+    return tracerInstance;
+}
+function createTracer() {
+    tracerInstance = new Tracer();
+    return tracerInstance;
+}
+//# sourceMappingURL=tracer.js.map

package/dist/observability/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../src/observability/tracer.ts"],"names":[],"mappings":";;AA0NA,8BAKC;AAED,oCAGC;AApOD,mCAAsC;AAetC,SAAS,UAAU;IACjB,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,MAAO,SAAQ,qBAAY;IACvB,MAAM,GAAsB,IAAI,GAAG,EAAE,CAAC;IACtC,WAAW,GAAiB,EAAE,CAAC;IAC/B,cAAc,CAAkB;IAChC,cAAc,CAAkB;IAExC;QACE,KAAK,EAAE,CAAC;IACV,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAsB;QACjC,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC3C,OAAO,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;YAC9E,OAAO;QACT,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC;QAE7B,8BAA8B;QAC9B,IAAI,CAAC,cAAc,GAAG;YACpB,KAAK,EAAE,KAAK,EAAE,IAAS,EAAE,EAAE;gBACzB,IAAI,CAAC;oBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,CAAC,OAAO,IAAI,4BAA4B,uBAAuB,EAAE;wBACrG,MAAM,EAAE,MAAM;wBACd,OAAO,EAAE;4BACP,cAAc,EAAE,kBAAkB;4BAClC,eAAe,EAAE,UAAU,MAAM,CAAC,SAAS,EAAE;yBAC9C;wBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;qBAC3B,CAAC,CAAC;oBACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;wBACjB,OAAO,CAAC,IAAI,CAAC,qCAAqC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;oBACvE,CAAC;gBACH,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,IAAI,CAAC,0BAA0B,EAAE,GAAG,CAAC,CAAC;gBAChD,CAAC;YACH,CAAC;YACD,KAAK,EAAE,KAAK,IAAI,EAAE;gBAChB,2CAA2C;YAC7C,CAAC;SACF,CAAC;QAEF,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,aAAqB,EAAE,YAAqB;QACpD,MAAM,OAAO,GAAG,YAAY;YAC1B,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,eAAe,EAAE;YAClE,CAAC,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;QAE3B,MAAM,IAAI,GAAS;YACjB,OAAO;YACP,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE;YAC9B,YAAY;YACZ,aAAa;YACb,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,UAAU,EAAE,EAAE;YACd,MAAM,EAAE,SAAS;SAClB,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAwB,CAAC,CAAC;QAEvF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,MAAc,EAAE,UAAgC;QACtD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,iBAAiB,MAAM,YAAY,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC;QAE1B,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,CAAC,UAAU,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,GAAG,UAAU,EAAE,CAAC;QAC1D,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAwB,CAAC,CAAC;IAC3F,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,MAAc,EAAE,KAAa,EAAE,UAAgC;QACvE,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,iBAAiB,MAAM,YAAY,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAEnB,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,CAAC,UAAU,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,GAAG,UAAU,EAAE,CAAC;QAC1D,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAwB,CAAC,CAAC;IAC3F,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,KAAiB;QAC3B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE7B,aAAa;QACb,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAwB,CAAC,CAAC;QAE1F,2BAA2B;QAC3B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC;gBACxB,IAAI,EAAE,gBAAgB;gBACtB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;gBAClD,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;gBAC7B,MAAM,EAAE;oBACN,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,MAAM,EAAE,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,cAAc;oBAChD,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;iBACjB;gBACD,QAAQ,EAAE;oBACR,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,cAAc,EAAE,KAAK,CAAC,cAAc;oBACpC,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,UAAU,EAAE,KAAK,CAAC,UAAU;oBAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;iBACjB;aACF,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,kBAAkB;QACxC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,UAAU,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,KAAc;QACtB,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,OAAe;QACtB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC7E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe;QACnB,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QACpC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;IACxB,CAAC;CACF;AAED,qBAAqB;AACrB,IAAI,cAAc,GAAkB,IAAI,CAAC;AAEzC,SAAgB,SAAS;IACvB,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,cAAc,GAAG,IAAI,MAAM,EAAE,CAAC;IAChC,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAgB,YAAY;IAC1B,cAAc,GAAG,IAAI,MAAM,EAAE,CAAC;IAC9B,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/observability/types.d.ts

@@ -0,0 +1,52 @@
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    operationName: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    attributes: Record<string, string | number | boolean>;
+    status: 'started' | 'completed' | 'error';
+    error?: string;
+}
+export interface Metric {
+    name: string;
+    value: number;
+    timestamp: number;
+    labels: Record<string, string>;
+    type: 'counter' | 'gauge' | 'histogram';
+}
+export interface RouteTrace {
+    traceId: string;
+    timestamp: number;
+    query: string;
+    queryTokens: number;
+    model: string;
+    provider: string;
+    responseTokens: number;
+    latencyMs: number;
+    cost: number;
+    cacheHit: boolean;
+    complexity: number;
+    tier: 'budget' | 'standard' | 'premium';
+}
+export type ObservabilityEvent = {
+    type: 'route_complete';
+    trace: RouteTrace;
+} | {
+    type: 'span_started';
+    span: Span;
+} | {
+    type: 'span_completed';
+    span: Span;
+} | {
+    type: 'budget_warning';
+    apiKey: string;
+    usedCents: number;
+    thresholdCents: number;
+} | {
+    type: 'error';
+    spanId: string;
+    error: string;
+};

package/dist/observability/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// Observability types for A3M Router
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/observability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":";AAAA,qCAAqC"}

package/dist/routing/providerRetry.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+export interface RetryConfig {
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+    retryableErrors?: string[];
+}
+export interface ProviderRetryConfig {
+    [providerName: string]: {
+        timeout: number;
+        retry: RetryConfig;
+        rateLimitRetries?: number;
+    };
+}
+export interface RetryStats {
+    totalRequests: number;
+    successfulRequests: number;
+    failedRequests: number;
+    totalRetries: number;
+    rateLimitRetries: number;
+    averageLatencyMs: number;
+}
+export interface ContextWindowValidation {
+    valid: boolean;
+    reason?: string;
+    suggestedProvider?: string;
+}
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+export declare const DEFAULT_PROVIDER_CONFIG: ProviderRetryConfig;
+declare const PROVIDER_CONTEXT_LIMITS: Record<string, number>;
+export declare class ProviderRetryHandler {
+    private configs;
+    private stats;
+    private customProviders;
+    constructor(customConfigs?: ProviderRetryConfig);
+    private initStats;
+    /**
+     * Configure or update a provider's retry settings
+     */
+    configureProvider(provider: string, config: Partial<{
+        timeout: number;
+        retry: Partial<RetryConfig>;
+        rateLimitRetries: number;
+    }>): void;
+    /**
+     * Get current config for a provider
+     */
+    getConfig(provider: string): {
+        timeout: number;
+        retry: RetryConfig;
+        rateLimitRetries: number;
+    };
+    /**
+     * Execute a function with retry logic
+     */
+    executeWithRetry<T>(provider: string, fn: () => Promise<T>, options?: {
+        timeout?: number;
+        onRetry?: (attempt: number, error: any, delayMs: number) => void;
+    }): Promise<T>;
+    /**
+     * Execute with custom timeout wrapper
+     */
+    private executeWithTimeout;
+    /**
+     * Check if an error should trigger a retry
+     */
+    isRetryableError(error: any): boolean;
+    /**
+     * Check if error is a rate limit (429)
+     */
+    isRateLimitError(error: any): boolean;
+    /**
+     * Calculate backoff delay with exponential increase and jitter
+     */
+    calculateBackoffDelay(attempt: number, config: RetryConfig, error?: any): number;
+    /**
+     * Validate context window size before sending request
+     */
+    validateContextWindow(provider: string, prompt: string, expectedTokens?: number): ContextWindowValidation;
+    /**
+     * Get retry statistics for a provider
+     */
+    getStats(provider: string): RetryStats;
+    /**
+     * Get all provider stats
+     */
+    getAllStats(): Record<string, RetryStats>;
+    /**
+     * Reset stats for a provider
+     */
+    resetStats(provider?: string): void;
+    private createTimeoutError;
+    private sleep;
+    private recordSuccess;
+    private recordFailure;
+    private recordRetry;
+}
+/**
+ * Create a retry handler with optional custom configs
+ */
+export declare function createRetryHandler(customConfigs?: ProviderRetryConfig): ProviderRetryHandler;
+export declare function getDefaultRetryHandler(): ProviderRetryHandler;
+export { DEFAULT_RETRY_CONFIG, PROVIDER_CONTEXT_LIMITS, };