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

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { SemanticCache } from './cache/semanticCache';
 export { GuardrailEngine } from './security/guardrails';
 export { CostAnalytics } from './analytics/costAnalytics';
 export { createProxyServer } from './server/proxyServer';
+export { Tracer, getTracer, createTracer, MetricsCollector, getMetrics, createMetricsCollector, observabilityMiddleware, observabilityPlugin, budgetAlertMiddleware, } from './observability';
+export type { Span, Metric, RouteTrace, ObservabilityEvent } from './observability';
 import { getAvailableProviders, healthCheck } from './providers/providerConfig';
 import { MemoryTree } from './memory/memoryTree';
 export interface A3MRouterOptions {

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.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.PROVIDER_CONTEXT_LIMITS = exports.DEFAULT_PROVIDER_CONFIG = exports.DEFAULT_RETRY_CONFIG = exports.getDefaultRetryHandler = exports.createRetryHandler = exports.ProviderRetryHandler = exports.getProviderHealth = exports.updateModelProfile = exports.MODEL_PROFILES = exports.extractQueryFeatures = exports.recommendForTask = exports.routeBatch = exports.routeQuery = void 0;
+exports.budgetAlertMiddleware = exports.observabilityPlugin = exports.observabilityMiddleware = exports.createMetricsCollector = exports.getMetrics = exports.MetricsCollector = exports.createTracer = exports.getTracer = exports.Tracer = 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.PROVIDER_CONTEXT_LIMITS = exports.DEFAULT_PROVIDER_CONFIG = exports.DEFAULT_RETRY_CONFIG = exports.getDefaultRetryHandler = exports.createRetryHandler = exports.ProviderRetryHandler = exports.getProviderHealth = exports.updateModelProfile = exports.MODEL_PROFILES = exports.extractQueryFeatures = exports.recommendForTask = exports.routeBatch = exports.routeQuery = void 0;
 exports.createA3MRouter = createA3MRouter;
 // ============================================================
 // ROUTING ENGINE
@@ -74,6 +74,19 @@ Object.defineProperty(exports, "CostAnalytics", { enumerable: true, get: functio
 var proxyServer_1 = require("./server/proxyServer");
 Object.defineProperty(exports, "createProxyServer", { enumerable: true, get: function () { return proxyServer_1.createProxyServer; } });
 // ============================================================
+// OBSERVABILITY
+// ============================================================
+var observability_1 = require("./observability");
+Object.defineProperty(exports, "Tracer", { enumerable: true, get: function () { return observability_1.Tracer; } });
+Object.defineProperty(exports, "getTracer", { enumerable: true, get: function () { return observability_1.getTracer; } });
+Object.defineProperty(exports, "createTracer", { enumerable: true, get: function () { return observability_1.createTracer; } });
+Object.defineProperty(exports, "MetricsCollector", { enumerable: true, get: function () { return observability_1.MetricsCollector; } });
+Object.defineProperty(exports, "getMetrics", { enumerable: true, get: function () { return observability_1.getMetrics; } });
+Object.defineProperty(exports, "createMetricsCollector", { enumerable: true, get: function () { return observability_1.createMetricsCollector; } });
+Object.defineProperty(exports, "observabilityMiddleware", { enumerable: true, get: function () { return observability_1.observabilityMiddleware; } });
+Object.defineProperty(exports, "observabilityPlugin", { enumerable: true, get: function () { return observability_1.observabilityPlugin; } });
+Object.defineProperty(exports, "budgetAlertMiddleware", { enumerable: true, get: function () { return observability_1.budgetAlertMiddleware; } });
+// ============================================================
 // CONVENIENCE: Create a router instance
 // ============================================================
 const advancedRouter_2 = require("./routing/advancedRouter");

package/dist/observability/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export { Tracer, getTracer, createTracer } from './tracer';
+export { MetricsCollector, getMetrics, createMetricsCollector } from './metrics';
+export { observabilityMiddleware, observabilityPlugin, budgetAlertMiddleware, } from './middleware';

package/dist/observability/index.js

@@ -0,0 +1,32 @@
+"use strict";
+// Observability module exports
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.budgetAlertMiddleware = exports.observabilityPlugin = exports.observabilityMiddleware = exports.createMetricsCollector = exports.getMetrics = exports.MetricsCollector = exports.createTracer = exports.getTracer = exports.Tracer = void 0;
+__exportStar(require("./types"), exports);
+var tracer_1 = require("./tracer");
+Object.defineProperty(exports, "Tracer", { enumerable: true, get: function () { return tracer_1.Tracer; } });
+Object.defineProperty(exports, "getTracer", { enumerable: true, get: function () { return tracer_1.getTracer; } });
+Object.defineProperty(exports, "createTracer", { enumerable: true, get: function () { return tracer_1.createTracer; } });
+var metrics_1 = require("./metrics");
+Object.defineProperty(exports, "MetricsCollector", { enumerable: true, get: function () { return metrics_1.MetricsCollector; } });
+Object.defineProperty(exports, "getMetrics", { enumerable: true, get: function () { return metrics_1.getMetrics; } });
+Object.defineProperty(exports, "createMetricsCollector", { enumerable: true, get: function () { return metrics_1.createMetricsCollector; } });
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "observabilityMiddleware", { enumerable: true, get: function () { return middleware_1.observabilityMiddleware; } });
+Object.defineProperty(exports, "observabilityPlugin", { enumerable: true, get: function () { return middleware_1.observabilityPlugin; } });
+Object.defineProperty(exports, "budgetAlertMiddleware", { enumerable: true, get: function () { return middleware_1.budgetAlertMiddleware; } });
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":";AAAA,+BAA+B;;;;;;;;;;;;;;;;;AAE/B,0CAAwB;AACxB,mCAA2D;AAAlD,gGAAA,MAAM,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,sGAAA,YAAY,OAAA;AACxC,qCAAiF;AAAxE,2GAAA,gBAAgB,OAAA;AAAE,qGAAA,UAAU,OAAA;AAAE,iHAAA,sBAAsB,OAAA;AAC7D,2CAIsB;AAHpB,qHAAA,uBAAuB,OAAA;AACvB,iHAAA,mBAAmB,OAAA;AACnB,mHAAA,qBAAqB,OAAA"}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,35 @@
+import { Metric } from './types';
+declare class MetricsCollector {
+    private counters;
+    private gauges;
+    private histograms;
+    private createdAt;
+    /**
+     * Increment counter
+     */
+    incrementCounter(name: string, labels?: Record<string, string>, value?: number): void;
+    /**
+     * Set gauge
+     */
+    setGauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Record histogram value
+     */
+    recordHistogram(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Get metrics in Prometheus format
+     */
+    getPrometheusMetrics(): string;
+    /**
+     * Get all metrics as Metric objects
+     */
+    getMetrics(): Metric[];
+    private extractLabels;
+    /**
+     * Clear metrics
+     */
+    reset(): void;
+}
+export declare function getMetrics(): MetricsCollector;
+export declare function createMetricsCollector(): MetricsCollector;
+export {};

package/dist/observability/metrics.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMetrics = getMetrics;
+exports.createMetricsCollector = createMetricsCollector;
+function formatLabels(labels) {
+    const parts = [];
+    for (const [key, value] of Object.entries(labels)) {
+        parts.push(`${key}="${value}"`);
+    }
+    return parts.join(',');
+}
+function metricKey(name, labels) {
+    if (!labels)
+        return name;
+    return `${name}{${formatLabels(labels)}}`;
+}
+class MetricsCollector {
+    counters = new Map();
+    gauges = new Map();
+    histograms = new Map();
+    createdAt = Date.now();
+    /**
+     * Increment counter
+     */
+    incrementCounter(name, labels, value = 1) {
+        const key = metricKey(name, labels);
+        this.counters.set(key, (this.counters.get(key) || 0) + value);
+    }
+    /**
+     * Set gauge
+     */
+    setGauge(name, value, labels) {
+        const key = metricKey(name, labels);
+        this.gauges.set(key, value);
+    }
+    /**
+     * Record histogram value
+     */
+    recordHistogram(name, value, labels) {
+        const key = metricKey(name, labels);
+        if (!this.histograms.has(name)) {
+            this.histograms.set(name, new Map());
+        }
+        const buckets = this.histograms.get(name);
+        const bucket = buckets.get(key) || { count: 0, sum: 0, min: Infinity, max: -Infinity };
+        bucket.count++;
+        bucket.sum += value;
+        bucket.min = Math.min(bucket.min, value);
+        bucket.max = Math.max(bucket.max, value);
+        buckets.set(key, bucket);
+    }
+    /**
+     * Get metrics in Prometheus format
+     */
+    getPrometheusMetrics() {
+        const lines = [];
+        const timestamp = Date.now();
+        lines.push('# HELP a3m_router_info A3M Router info');
+        lines.push('# TYPE a3m_router_info gauge');
+        lines.push('a3m_router_info{router_version="2.0.0"} 1');
+        // Counters
+        lines.push('');
+        lines.push('# HELP a3m_router_requests_total Total number of router requests');
+        lines.push('# TYPE a3m_router_requests_total counter');
+        for (const [key, value] of this.counters) {
+            if (key.startsWith('a3m_router_') || key.startsWith('a3m_')) {
+                lines.push(`${key} ${value} ${timestamp}`);
+            }
+        }
+        // Cache counters
+        for (const [key, value] of this.counters) {
+            if (key.startsWith('cache_')) {
+                lines.push(`${key} ${value} ${timestamp}`);
+            }
+        }
+        // Gauges
+        lines.push('');
+        lines.push('# HELP a3m_active_providers Number of active providers');
+        lines.push('# TYPE a3m_active_providers gauge');
+        for (const [key, value] of this.gauges) {
+            lines.push(`${key} ${value} ${timestamp}`);
+        }
+        // Histograms
+        lines.push('');
+        lines.push('# HELP a3m_request_latency_seconds Request latency in seconds');
+        lines.push('# TYPE a3m_request_latency_seconds histogram');
+        for (const [name, buckets] of this.histograms) {
+            if (name.includes('latency')) {
+                for (const [bucketKey, bucket] of buckets) {
+                    const labelStr = bucketKey.includes('{') ? bucketKey.slice(name.length) : '';
+                    lines.push(`${name}_sum${labelStr} ${bucket.sum} ${timestamp}`);
+                    lines.push(`${name}_count${labelStr} ${bucket.count} ${timestamp}`);
+                }
+            }
+        }
+        lines.push('');
+        lines.push('# HELP a3m_request_cost_cents Request cost in cents');
+        lines.push('# TYPE a3m_request_cost_cents histogram');
+        for (const [name, buckets] of this.histograms) {
+            if (name.includes('cost')) {
+                for (const [bucketKey, bucket] of buckets) {
+                    const labelStr = bucketKey.includes('{') ? bucketKey.slice(name.length) : '';
+                    lines.push(`${name}_sum${labelStr} ${bucket.sum} ${timestamp}`);
+                    lines.push(`${name}_count${labelStr} ${bucket.count} ${timestamp}`);
+                }
+            }
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Get all metrics as Metric objects
+     */
+    getMetrics() {
+        const metrics = [];
+        const timestamp = Date.now();
+        for (const [key, value] of this.counters) {
+            metrics.push({
+                name: key,
+                value,
+                timestamp,
+                labels: this.extractLabels(key),
+                type: 'counter',
+            });
+        }
+        for (const [key, value] of this.gauges) {
+            metrics.push({
+                name: key,
+                value,
+                timestamp,
+                labels: this.extractLabels(key),
+                type: 'gauge',
+            });
+        }
+        for (const [name, buckets] of this.histograms) {
+            for (const [bucketKey, bucket] of buckets) {
+                metrics.push({
+                    name: bucketKey,
+                    value: bucket.count,
+                    timestamp,
+                    labels: this.extractLabels(bucketKey),
+                    type: 'histogram',
+                });
+            }
+        }
+        return metrics;
+    }
+    extractLabels(metricKey) {
+        const labels = {};
+        const match = metricKey.match(/\{(.+)\}/);
+        if (match) {
+            const pairs = match[1].split(',');
+            for (const pair of pairs) {
+                const [key, value] = pair.split('=');
+                labels[key] = value.replace(/"/g, '');
+            }
+        }
+        return labels;
+    }
+    /**
+     * Clear metrics
+     */
+    reset() {
+        this.counters.clear();
+        this.gauges.clear();
+        this.histograms.clear();
+        this.createdAt = Date.now();
+    }
+}
+// Singleton instance
+let metricsInstance = null;
+function getMetrics() {
+    if (!metricsInstance) {
+        metricsInstance = new MetricsCollector();
+    }
+    return metricsInstance;
+}
+function createMetricsCollector() {
+    metricsInstance = new MetricsCollector();
+    return metricsInstance;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/observability/metrics.js.map

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

package/dist/observability/middleware.d.ts

@@ -0,0 +1,16 @@
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Express middleware for observability
+ * - Adds trace ID to all requests
+ * - Records request/response metrics
+ * - Attaches span context
+ */
+export declare function observabilityMiddleware(req: Request, res: Response, next: NextFunction): void;
+/**
+ * Fastify plugin for observability middleware
+ */
+export declare function observabilityPlugin(instance: any, options: any, next: (err?: Error) => void): void;
+/**
+ * Middleware for budget warning alerts
+ */
+export declare function budgetAlertMiddleware(req: Request, res: Response, next: NextFunction): void;

package/dist/observability/middleware.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observabilityMiddleware = observabilityMiddleware;
+exports.observabilityPlugin = observabilityPlugin;
+exports.budgetAlertMiddleware = budgetAlertMiddleware;
+const tracer_1 = require("./tracer");
+const metrics_1 = require("./metrics");
+/**
+ * Express middleware for observability
+ * - Adds trace ID to all requests
+ * - Records request/response metrics
+ * - Attaches span context
+ */
+function observabilityMiddleware(req, res, next) {
+    const tracer = (0, tracer_1.getTracer)();
+    const metrics = (0, metrics_1.getMetrics)();
+    // Generate or extract trace ID
+    const traceId = req.headers['x-trace-id'] || tracer.generateTraceId();
+    // Attach to request object
+    req.traceId = traceId;
+    req.spanId = null;
+    // Add trace ID to response headers
+    res.setHeader('X-Trace-ID', traceId);
+    // Start span for this request
+    const span = tracer.startSpan(`${req.method} ${req.path}`);
+    req.spanId = span.spanId;
+    req.span = span;
+    // Record start time for latency calculation
+    const startTime = Date.now();
+    // Hook into response finish
+    res.on('finish', () => {
+        const duration = Date.now() - startTime;
+        // End the span
+        tracer.endSpan(span.spanId, {
+            method: req.method,
+            path: req.path,
+            statusCode: res.statusCode,
+            durationMs: duration,
+        });
+        // Record metrics
+        const model = req.model || 'unknown';
+        const provider = req.provider || 'unknown';
+        const cacheHit = req.cacheHit || false;
+        const tier = req.tier || 'standard';
+        // Request counter
+        metrics.incrementCounter('a3m_router_requests_total', {
+            model,
+            provider,
+            tier,
+            cache_hit: String(cacheHit),
+        });
+        // Latency histogram (convert to seconds)
+        metrics.recordHistogram('a3m_request_latency_seconds', duration / 1000, {
+            model,
+            provider,
+        });
+        // Error counter
+        if (res.statusCode >= 400) {
+            metrics.incrementCounter('a3m_router_errors_total', {
+                provider,
+                error_type: res.statusCode >= 500 ? 'server_error' : 'client_error',
+            });
+        }
+    });
+    next();
+}
+/**
+ * Fastify plugin for observability middleware
+ */
+function observabilityPlugin(instance, options, next) {
+    instance.addHook('onRequest', async (request, reply) => {
+        const tracer = (0, tracer_1.getTracer)();
+        const metrics = (0, metrics_1.getMetrics)();
+        const traceId = request.headers['x-trace-id'] || tracer.generateTraceId();
+        request.traceId = traceId;
+        reply.header('X-Trace-ID', traceId);
+        const span = tracer.startSpan(`${request.method} ${request.url}`);
+        request.spanId = span.spanId;
+        request.span = span;
+        request.startTime = Date.now();
+    });
+    instance.addHook('onResponse', async (request, reply) => {
+        const tracer = (0, tracer_1.getTracer)();
+        const metrics = (0, metrics_1.getMetrics)();
+        const duration = Date.now() - request.startTime;
+        if (request.spanId) {
+            tracer.endSpan(request.spanId, {
+                method: request.method,
+                path: request.url,
+                statusCode: reply.statusCode,
+                durationMs: duration,
+            });
+        }
+        const model = request.model || 'unknown';
+        const provider = request.provider || 'unknown';
+        const cacheHit = request.cacheHit || false;
+        const tier = request.tier || 'standard';
+        metrics.incrementCounter('a3m_router_requests_total', {
+            model,
+            provider,
+            tier,
+            cache_hit: String(cacheHit),
+        });
+        metrics.recordHistogram('a3m_request_latency_seconds', duration / 1000, {
+            model,
+            provider,
+        });
+        if (reply.statusCode >= 400) {
+            metrics.incrementCounter('a3m_router_errors_total', {
+                provider,
+                error_type: reply.statusCode >= 500 ? 'server_error' : 'client_error',
+            });
+        }
+    });
+    next();
+}
+/**
+ * Middleware for budget warning alerts
+ */
+function budgetAlertMiddleware(req, res, next) {
+    const tracer = (0, tracer_1.getTracer)();
+    // Hook into cost tracking to emit budget warnings
+    tracer.on('route_complete', (trace) => {
+        // This would be connected to budget enforcement in practice
+        // For now just a placeholder for the event hook
+    });
+    next();
+}
+//# sourceMappingURL=middleware.js.map

package/dist/observability/middleware.js.map

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

package/dist/observability/tracer.d.ts

@@ -0,0 +1,57 @@
+import { EventEmitter } from 'events';
+import { Span, RouteTrace } from './types';
+interface LangfuseConfig {
+    publicKey?: string;
+    secretKey?: string;
+    baseUrl?: string;
+}
+declare class Tracer extends EventEmitter {
+    private traces;
+    private routeTraces;
+    private langfuseClient?;
+    private langfuseConfig?;
+    constructor();
+    /**
+     * Initialize Langfuse if configured
+     */
+    initLangfuse(config: LangfuseConfig): void;
+    /**
+     * Create a new trace span
+     */
+    startSpan(operationName: string, parentSpanId?: string): Span;
+    /**
+     * End a span
+     */
+    endSpan(spanId: string, attributes?: Record<string, any>): void;
+    /**
+     * Record an error on a span
+     */
+    errorSpan(spanId: string, error: string, attributes?: Record<string, any>): void;
+    /**
+     * Record a route decision
+     */
+    recordRoute(trace: RouteTrace): void;
+    /**
+     * Generate a unique trace ID
+     */
+    generateTraceId(): string;
+    /**
+     * Get all route traces
+     */
+    getTraces(limit?: number): RouteTrace[];
+    /**
+     * Get all spans for a trace
+     */
+    getSpans(traceId: string): Span[];
+    /**
+     * Export to Langfuse (async, non-blocking)
+     */
+    flushToLangfuse(): Promise<void>;
+    /**
+     * Clear all traces (for testing)
+     */
+    reset(): void;
+}
+export declare function getTracer(): Tracer;
+export declare function createTracer(): Tracer;
+export {};