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

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 {};

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":"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"}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adaptive-memory-multi-model-router",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "shortName": "A3M Router",
   "displayName": "A3M Router - Adaptive Memory Multi-Model Router",
   "description": "LLM router & AI gateway — 99.5% routing accuracy, 47 providers (DeepSeek, Kimi/Moonshot, Qwen, Zhipu GLM, Yi + more). Semantic cache, guardrails, cost analytics. Built on 30+ arXiv papers (SGLang, Medusa, MemoRAG). Zero ML, 19.5KB. TypeScript + Python SDK. MIT.",

package/src/index.ts

@@ -84,6 +84,22 @@ export { GuardrailEngine } from './security/guardrails';
 export { CostAnalytics } from './analytics/costAnalytics';
 export { createProxyServer } from './server/proxyServer';
 
+// ============================================================
+// OBSERVABILITY
+// ============================================================
+export {
+  Tracer,
+  getTracer,
+  createTracer,
+  MetricsCollector,
+  getMetrics,
+  createMetricsCollector,
+  observabilityMiddleware,
+  observabilityPlugin,
+  budgetAlertMiddleware,
+} from './observability';
+export type { Span, Metric, RouteTrace, ObservabilityEvent } from './observability';
+
 // ============================================================
 // CONVENIENCE: Create a router instance
 // ============================================================

package/src/observability/index.ts

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

package/src/observability/metrics.ts

@@ -0,0 +1,215 @@
+import { Metric } from './types';
+
+interface HistogramBucket {
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+}
+
+function formatLabels(labels: Record<string, string>): string {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(labels)) {
+    parts.push(`${key}="${value}"`);
+  }
+  return parts.join(',');
+}
+
+function metricKey(name: string, labels?: Record<string, string>): string {
+  if (!labels) return name;
+  return `${name}{${formatLabels(labels)}}`;
+}
+
+class MetricsCollector {
+  private counters: Map<string, number> = new Map();
+  private gauges: Map<string, number> = new Map();
+  private histograms: Map<string, Map<string, HistogramBucket>> = new Map();
+  private createdAt: number = Date.now();
+
+  /**
+   * Increment counter
+   */
+  incrementCounter(name: string, labels?: Record<string, string>, value: number = 1): void {
+    const key = metricKey(name, labels);
+    this.counters.set(key, (this.counters.get(key) || 0) + value);
+  }
+
+  /**
+   * Set gauge
+   */
+  setGauge(name: string, value: number, labels?: Record<string, string>): void {
+    const key = metricKey(name, labels);
+    this.gauges.set(key, value);
+  }
+
+  /**
+   * Record histogram value
+   */
+  recordHistogram(name: string, value: number, labels?: Record<string, string>): void {
+    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(): string {
+    const lines: string[] = [];
+    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(): Metric[] {
+    const metrics: Metric[] = [];
+    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;
+  }
+
+  private extractLabels(metricKey: string): Record<string, string> {
+    const labels: Record<string, string> = {};
+    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(): void {
+    this.counters.clear();
+    this.gauges.clear();
+    this.histograms.clear();
+    this.createdAt = Date.now();
+  }
+}
+
+// Singleton instance
+let metricsInstance: MetricsCollector | null = null;
+
+export function getMetrics(): MetricsCollector {
+  if (!metricsInstance) {
+    metricsInstance = new MetricsCollector();
+  }
+  return metricsInstance;
+}
+
+export function createMetricsCollector(): MetricsCollector {
+  metricsInstance = new MetricsCollector();
+  return metricsInstance;
+}