adaptive-memory-multi-model-router 1.9.5 → 2.0.1

package/scripts/update-npm-badges.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * NPM Stats Badge Updater
+ * 
+ * Updates README.md with current NPM download statistics
+ * Run: node scripts/update-npm-badges.js
+ */
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_NAME = 'adaptive-memory-multi-model-router';
+
+function fetchNPMStats(period) {
+  return new Promise((resolve, reject) => {
+    const url = `https://api.npmjs.org/downloads/point/${period}/${PACKAGE_NAME}`;
+    https.get(url, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          resolve(parsed);
+        } catch (e) {
+          reject(e);
+        }
+      });
+    }).on('error', reject);
+  });
+}
+
+function generateBadge(label, value, color) {
+  // Use shields.io for dynamic badges
+  const encodedLabel = encodeURIComponent(label);
+  const encodedValue = encodeURIComponent(value.toString());
+  return `https://img.shields.io/badge/${encodedLabel}-${encodedValue}-${color}?logo=npm`;
+}
+
+function formatNumber(num) {
+  if (num >= 1000000) return (num / 1000000).toFixed(1) + 'M';
+  if (num >= 1000) return (num / 1000).toFixed(1) + 'k';
+  return num.toString();
+}
+
+async function updateBadges() {
+  console.log('📊 Fetching NPM Statistics...\n');
+  
+  try {
+    // Fetch stats
+    const [day, week, month] = await Promise.all([
+      fetchNPMStats('last-day'),
+      fetchNPMStats('last-week'),
+      fetchNPMStats('last-month'),
+    ]);
+    
+    console.log('Current Statistics:');
+    console.log('─────────────────────────────────────────────────────────────');
+    console.log(`  Daily:   ${day.downloads.toLocaleString().padStart(6)} downloads`);
+    console.log(`  Weekly:  ${week.downloads.toLocaleString().padStart(6)} downloads`);
+    console.log(`  Monthly: ${month.downloads.toLocaleString().padStart(6)} downloads`);
+    console.log();
+    
+    // Generate badge URLs
+    const badges = {
+      daily: generateBadge('downloads/day', formatNumber(day.downloads), 'blue'),
+      weekly: generateBadge('downloads/week', formatNumber(week.downloads), 'green'),
+      monthly: generateBadge('downloads/month', formatNumber(month.downloads), 'orange'),
+      version: `https://img.shields.io/npm/v/${PACKAGE_NAME}?logo=npm`,
+      license: `https://img.shields.io/npm/l/${PACKAGE_NAME}?color=blue`,
+      tests: `https://img.shields.io/badge/tests-33%20passing-brightgreen`,
+    };
+    
+    // Read README
+    const readmePath = path.join(__dirname, '..', 'README.md');
+    let readme = fs.readFileSync(readmePath, 'utf8');
+    
+    // Update badges section
+    const badgeSection = `<!-- BADGES_START -->
+<p align="center">
+  <a href="https://www.npmjs.com/package/${PACKAGE_NAME}">
+    <img src="${badges.version}" alt="NPM Version">
+  </a>
+  <a href="https://www.npmjs.com/package/${PACKAGE_NAME}">
+    <img src="${badges.daily}" alt="Daily Downloads">
+  </a>
+  <a href="https://www.npmjs.com/package/${PACKAGE_NAME}">
+    <img src="${badges.weekly}" alt="Weekly Downloads">
+  </a>
+  <a href="https://www.npmjs.com/package/${PACKAGE_NAME}">
+    <img src="${badges.monthly}" alt="Monthly Downloads">
+  </a>
+  <a href="https://github.com/Das-rebel/${PACKAGE_NAME}/blob/main/LICENSE">
+    <img src="${badges.license}" alt="License">
+  </a>
+  <img src="${badges.tests}" alt="Tests">
+</p>
+<!-- BADGES_END -->`;
+    
+    // Replace existing badge section or add at top
+    if (readme.includes('<!-- BADGES_START -->')) {
+      readme = readme.replace(
+        /<!-- BADGES_START -->[\s\S]*?<!-- BADGES_END -->/,
+        badgeSection
+      );
+    } else {
+      // Add after title
+      readme = readme.replace(
+        /^(# .*$)/m,
+        `$1\n\n${badgeSection}`
+      );
+    }
+    
+    // Update stats section in README
+    const statsSection = `<!-- STATS_START -->
+## 📊 Download Statistics
+
+| Period | Downloads | Trend |
+|--------|-----------|-------|
+| Daily | ${day.downloads.toLocaleString()} | 📈 |
+| Weekly | ${week.downloads.toLocaleString()} | 📈 |
+| Monthly | ${month.downloads.toLocaleString()} | 📈 |
+
+*Last updated: ${new Date().toISOString().split('T')[0]}*
+<!-- STATS_END -->`;
+    
+    if (readme.includes('<!-- STATS_START -->')) {
+      readme = readme.replace(
+        /<!-- STATS_START -->[\s\S]*?<!-- STATS_END -->/,
+        statsSection
+      );
+    }
+    
+    // Write updated README
+    fs.writeFileSync(readmePath, readme);
+    
+    console.log('✅ README badges updated successfully!');
+    console.log();
+    console.log('Generated Badges:');
+    console.log('─────────────────────────────────────────────────────────────');
+    console.log(`  Version: ${badges.version}`);
+    console.log(`  Daily:   ${badges.daily}`);
+    console.log(`  Weekly:  ${badges.weekly}`);
+    console.log(`  Monthly: ${badges.monthly}`);
+    console.log();
+    
+  } catch (error) {
+    console.error('❌ Error updating badges:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  updateBadges();
+}
+
+module.exports = { updateBadges, fetchNPMStats };

package/src/analytics/costAnalytics.ts

@@ -0,0 +1,304 @@
+/**
+ * A3M Router - Cost Analytics
+ *
+ * Advanced cost tracking and analytics:
+ * - Record every request with full metadata
+ * - Real-time savings vs single premium provider
+ * - Monthly/yearly projections
+ * - Breakdown by provider and query type
+ * - Export to JSON or CSV
+ * - In-memory storage with auto-rotation
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CostRecord {
+  timestamp: Date;
+  provider: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cost: number;
+  latency: number;
+  queryType: 'simple' | 'code' | 'summary' | 'complex';
+  cached: boolean;
+}
+
+export interface CostSummary {
+  totalCost: number;
+  totalRequests: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  avgLatency: number;
+  cacheHitRate: number;
+  period: { start: Date; end: Date };
+}
+
+export interface ProviderStats {
+  totalCost: number;
+  totalRequests: number;
+  avgLatency: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  models: Record<string, { cost: number; requests: number }>;
+}
+
+export interface QueryTypeStats {
+  totalCost: number;
+  totalRequests: number;
+  avgLatency: number;
+  cachedCount: number;
+  cacheHitRate: number;
+}
+
+export interface SavingsReport {
+  totalSaved: number;
+  percentageSaved: number;
+  byQueryType: Record<string, { saved: number; percentage: number }>;
+  projectedMonthlySavings: number;
+  projectedYearlySavings: number;
+}
+
+// Model costs per 1M tokens (USD) for baseline comparison
+const BASELINE_COSTS: Record<string, { input: number; output: number }> = {
+  'gpt-4o': { input: 2.50, output: 10.00 },
+  'gpt-4-turbo': { input: 10.00, output: 30.00 },
+  'claude-3.5-sonnet': { input: 3.00, output: 15.00 },
+  'claude-3-opus': { input: 15.00, output: 75.00 },
+  'claude-3-haiku': { input: 0.25, output: 1.25 },
+  'gpt-3.5-turbo': { input: 0.50, output: 1.50 },
+  'gemini-1.5-pro': { input: 1.25, output: 5.00 },
+  'gemini-1.5-flash': { input: 0.075, output: 0.30 },
+  'groq/llama-3.3-70b': { input: 0.59, output: 0.79 },
+  'groq/llama-3.1-8b': { input: 0.05, output: 0.08 },
+  'cerebras/llama-3.3-70b': { input: 0.10, output: 0.10 },
+  'mistral-large': { input: 2.00, output: 6.00 },
+  'mistral-small': { input: 0.20, output: 0.60 },
+};
+
+// ---------------------------------------------------------------------------
+// CostAnalytics
+// ---------------------------------------------------------------------------
+
+export class CostAnalytics {
+  private records: CostRecord[] = [];
+  private maxRecords: number;
+
+  constructor(maxRecords: number = 10000) {
+    this.maxRecords = maxRecords;
+  }
+
+  // ---- Record ----
+
+  record(data: Omit<CostRecord, 'timestamp'>): void {
+    const entry: CostRecord = { ...data, timestamp: new Date() };
+    this.records.push(entry);
+
+    // Auto-rotate
+    if (this.records.length > this.maxRecords) {
+      this.records = this.records.slice(-this.maxRecords);
+    }
+  }
+
+  // ---- Summary ----
+
+  getSummary(period: 'hour' | 'day' | 'week' | 'month' = 'day'): CostSummary {
+    const filtered = this.filterByPeriod(period);
+    if (filtered.length === 0) {
+      const now = new Date();
+      return {
+        totalCost: 0, totalRequests: 0, totalInputTokens: 0, totalOutputTokens: 0,
+        avgLatency: 0, cacheHitRate: 0,
+        period: { start: now, end: now },
+      };
+    }
+
+    const totalCost = sum(filtered, (r) => r.cost);
+    const cached = filtered.filter((r) => r.cached).length;
+    const start = filtered[0].timestamp;
+    const end = filtered[filtered.length - 1].timestamp;
+
+    return {
+      totalCost: round(totalCost),
+      totalRequests: filtered.length,
+      totalInputTokens: sum(filtered, (r) => r.inputTokens),
+      totalOutputTokens: sum(filtered, (r) => r.outputTokens),
+      avgLatency: round(sum(filtered, (r) => r.latency) / filtered.length),
+      cacheHitRate: round(cached / filtered.length),
+      period: { start, end },
+    };
+  }
+
+  // ---- By provider ----
+
+  getByProvider(): Record<string, ProviderStats> {
+    const result: Record<string, ProviderStats> = {};
+    for (const r of this.records) {
+      if (!result[r.provider]) {
+        result[r.provider] = {
+          totalCost: 0, totalRequests: 0, avgLatency: 0,
+          totalInputTokens: 0, totalOutputTokens: 0, models: {},
+        };
+      }
+      const p = result[r.provider];
+      p.totalCost += r.cost;
+      p.totalRequests++;
+      p.avgLatency += r.latency;
+      p.totalInputTokens += r.inputTokens;
+      p.totalOutputTokens += r.outputTokens;
+
+      if (!p.models[r.model]) {
+        p.models[r.model] = { cost: 0, requests: 0 };
+      }
+      p.models[r.model].cost += r.cost;
+      p.models[r.model].requests++;
+    }
+
+    for (const p of Object.values(result)) {
+      if (p.totalRequests > 0) {
+        p.avgLatency = round(p.avgLatency / p.totalRequests);
+      }
+      p.totalCost = round(p.totalCost);
+    }
+    return result;
+  }
+
+  // ---- By query type ----
+
+  getByQueryType(): Record<string, QueryTypeStats> {
+    const result: Record<string, QueryTypeStats> = {};
+    for (const r of this.records) {
+      if (!result[r.queryType]) {
+        result[r.queryType] = {
+          totalCost: 0, totalRequests: 0, avgLatency: 0, cachedCount: 0, cacheHitRate: 0,
+        };
+      }
+      const q = result[r.queryType];
+      q.totalCost += r.cost;
+      q.totalRequests++;
+      q.avgLatency += r.latency;
+      if (r.cached) q.cachedCount++;
+    }
+
+    for (const q of Object.values(result)) {
+      if (q.totalRequests > 0) {
+        q.avgLatency = round(q.avgLatency / q.totalRequests);
+        q.cacheHitRate = round(q.cachedCount / q.totalRequests);
+      }
+      q.totalCost = round(q.totalCost);
+    }
+    return result;
+  }
+
+  // ---- Savings ----
+
+  getSavings(baselineProvider: string = 'gpt-4o'): SavingsReport {
+    const baseline = BASELINE_COSTS[baselineProvider] || { input: 2.50, output: 10.00 };
+    let totalActual = 0;
+    let totalBaseline = 0;
+    const byQueryType: Record<string, { actual: number; baseline: number }> = {};
+
+    for (const r of this.records) {
+      const actualCost = r.cost;
+      const baselineCost =
+        (r.inputTokens / 1_000_000) * baseline.input +
+        (r.outputTokens / 1_000_000) * baseline.output;
+
+      totalActual += actualCost;
+      totalBaseline += baselineCost;
+
+      if (!byQueryType[r.queryType]) {
+        byQueryType[r.queryType] = { actual: 0, baseline: 0 };
+      }
+      byQueryType[r.queryType].actual += actualCost;
+      byQueryType[r.queryType].baseline += baselineCost;
+    }
+
+    const totalSaved = totalBaseline - totalActual;
+    const percentageSaved = totalBaseline > 0 ? (totalSaved / totalBaseline) * 100 : 0;
+
+    // Project based on days of data we have
+    const daysCovered = this.getDaysCovered();
+    const dailySavings = daysCovered > 0 ? totalSaved / daysCovered : 0;
+
+    const queryTypeSavings: Record<string, { saved: number; percentage: number }> = {};
+    for (const [qt, data] of Object.entries(byQueryType)) {
+      const saved = data.baseline - data.actual;
+      queryTypeSavings[qt] = {
+        saved: round(saved),
+        percentage: data.baseline > 0 ? round((saved / data.baseline) * 100) : 0,
+      };
+    }
+
+    return {
+      totalSaved: round(totalSaved),
+      percentageSaved: round(percentageSaved),
+      byQueryType: queryTypeSavings,
+      projectedMonthlySavings: round(dailySavings * 30),
+      projectedYearlySavings: round(dailySavings * 365),
+    };
+  }
+
+  // ---- Export ----
+
+  export(format: 'json' | 'csv' = 'json'): string {
+    if (format === 'csv') {
+      const header = 'timestamp,provider,model,inputTokens,outputTokens,cost,latency,queryType,cached';
+      const rows = this.records.map((r) =>
+        `${r.timestamp.toISOString()},${r.provider},${r.model},${r.inputTokens},${r.outputTokens},${r.cost},${r.latency},${r.queryType},${r.cached}`
+      );
+      return [header, ...rows].join('\n');
+    }
+    return JSON.stringify(this.records, null, 2);
+  }
+
+  // ---- Reset ----
+
+  reset(): void {
+    this.records = [];
+  }
+
+  // ---- Internals ----
+
+  private filterByPeriod(period: 'hour' | 'day' | 'week' | 'month'): CostRecord[] {
+    const now = Date.now();
+    const ms: Record<string, number> = {
+      hour: 3600_000,
+      day: 86400_000,
+      week: 604800_000,
+      month: 2592000_000,
+    };
+    const cutoff = now - (ms[period] || ms.day);
+    return this.records.filter((r) => r.timestamp.getTime() >= cutoff);
+  }
+
+  private getDaysCovered(): number {
+    if (this.records.length < 2) return 1;
+    const first = this.records[0].timestamp.getTime();
+    const last = this.records[this.records.length - 1].timestamp.getTime();
+    return Math.max(1, (last - first) / 86400_000);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sum(arr: CostRecord[], fn: (r: CostRecord) => number): number {
+  return arr.reduce((acc, r) => acc + fn(r), 0);
+}
+
+function round(n: number, decimals: number = 4): number {
+  const factor = Math.pow(10, decimals);
+  return Math.round(n * factor) / factor;
+}
+
+// ---------------------------------------------------------------------------
+// Convenience factory
+// ---------------------------------------------------------------------------
+
+export function createCostAnalytics(maxRecords?: number): CostAnalytics {
+  return new CostAnalytics(maxRecords);
+}

package/src/cache/semanticCache.ts

@@ -0,0 +1,221 @@
+/**
+ * A3M Router - Semantic Cache
+ *
+ * Stores previous query->response pairs and returns cached responses
+ * for semantically similar queries using character n-gram Jaccard similarity.
+ *
+ * No external embedding API needed. Trigram overlap catches paraphrases like:
+ *   "What is Python?"    ≈ "Tell me about Python" ≈ "Explain Python"
+ *   "Write a sort fn"    ≈ "Create a sorting fn"  ≈ "How to sort an array"
+ */
+
+// ============================================================
+// Types
+// ============================================================
+
+export interface CachedResponse {
+  query: string;
+  response: string;
+  metadata?: any;
+  cachedAt: number;
+  hitCount: number;
+}
+
+export interface SemanticCacheOptions {
+  maxSize?: number;             // Max entries (default: 1000)
+  similarityThreshold?: number; // 0-1, min similarity for hit (default: 0.92)
+  ttl?: number;                 // TTL in ms (default: 3600000 = 1 hour)
+}
+
+interface CacheEntry extends CachedResponse {
+  trigrams: Set<string>;
+  expiresAt: number;
+}
+
+export interface SemanticCacheStats {
+  hits: number;
+  misses: number;
+  hitRate: number;
+  size: number;
+}
+
+// ============================================================
+// N-gram utilities
+// ============================================================
+
+/**
+ * Normalize text: lowercase, collapse whitespace, strip punctuation edges.
+ */
+function normalize(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Extract character trigrams from text.
+ * Pads with spaces so short words still produce trigrams.
+ */
+function extractTrigrams(text: string): Set<string> {
+  const normalized = " " + normalize(text) + " ";
+  const trigrams = new Set<string>();
+  for (let i = 0; i <= normalized.length - 3; i++) {
+    trigrams.add(normalized.substring(i, i + 3));
+  }
+  return trigrams;
+}
+
+/**
+ * Compute Jaccard similarity between two sets.
+ * |A ∩ B| / |A ∪ B|
+ */
+function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 1.0;
+  let intersection = 0;
+  for (const item of a) {
+    if (b.has(item)) intersection++;
+  }
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+// ============================================================
+// Semantic Cache
+// ============================================================
+
+export class SemanticCache {
+  private entries: CacheEntry[] = [];
+  private maxSize: number;
+  private similarityThreshold: number;
+  private ttl: number;
+  private hits = 0;
+  private misses = 0;
+
+  constructor(options?: SemanticCacheOptions) {
+    this.maxSize = options?.maxSize ?? 1000;
+    this.similarityThreshold = options?.similarityThreshold ?? 0.92;
+    this.ttl = options?.ttl ?? 3600000; // 1 hour
+  }
+
+  /**
+   * Get cached response for a semantically similar query.
+   * Returns the best match above the similarity threshold, or null.
+   */
+  async get(query: string): Promise<CachedResponse | null> {
+    const now = Date.now();
+    const queryTrigrams = extractTrigrams(query);
+
+    let bestEntry: CacheEntry | null = null;
+    let bestScore = 0;
+
+    for (const entry of this.entries) {
+      // Skip expired
+      if (now > entry.expiresAt) continue;
+
+      const score = jaccard(queryTrigrams, entry.trigrams);
+      if (score > bestScore) {
+        bestScore = score;
+        bestEntry = entry;
+      }
+    }
+
+    if (bestEntry && bestScore >= this.similarityThreshold) {
+      this.hits++;
+      bestEntry.hitCount++;
+      return {
+        query: bestEntry.query,
+        response: bestEntry.response,
+        metadata: bestEntry.metadata,
+        cachedAt: bestEntry.cachedAt,
+        hitCount: bestEntry.hitCount,
+      };
+    }
+
+    this.misses++;
+    return null;
+  }
+
+  /**
+   * Store a query->response pair in the cache.
+   */
+  async set(query: string, response: string, metadata?: any): Promise<void> {
+    const now = Date.now();
+
+    // Evict expired entries first
+    this.evictExpired();
+
+    // Evict oldest if at capacity
+    if (this.entries.length >= this.maxSize) {
+      this.evictOldest();
+    }
+
+    // Check if an exact-match entry already exists and update it
+    const normalized = normalize(query);
+    const existing = this.entries.find(
+      (e) => normalize(e.query) === normalized && now <= e.expiresAt
+    );
+    if (existing) {
+      existing.response = response;
+      existing.metadata = metadata;
+      existing.cachedAt = now;
+      existing.expiresAt = now + this.ttl;
+      existing.trigrams = extractTrigrams(query);
+      return;
+    }
+
+    this.entries.push({
+      query,
+      response,
+      metadata,
+      cachedAt: now,
+      expiresAt: now + this.ttl,
+      hitCount: 0,
+      trigrams: extractTrigrams(query),
+    });
+  }
+
+  /**
+   * Clear all cache entries.
+   */
+  clear(): void {
+    this.entries = [];
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  getStats(): SemanticCacheStats {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+      size: this.entries.length,
+    };
+  }
+
+  /**
+   * Purge expired entries.
+   */
+  private evictExpired(): void {
+    const now = Date.now();
+    this.entries = this.entries.filter((e) => now <= e.expiresAt);
+  }
+
+  /**
+   * Evict the oldest (by cachedAt) entry.
+   */
+  private evictOldest(): void {
+    if (this.entries.length === 0) return;
+    let oldestIdx = 0;
+    let oldestTime = Infinity;
+    for (let i = 0; i < this.entries.length; i++) {
+      if (this.entries[i].cachedAt < oldestTime) {
+        oldestTime = this.entries[i].cachedAt;
+        oldestIdx = i;
+      }
+    }
+    this.entries.splice(oldestIdx, 1);
+  }
+}