adaptive-memory-multi-model-router 1.9.1 → 1.9.3

package/dist/integrations/index.js

@@ -24,6 +24,7 @@ const GmailIntegration = require('./gmail.js').GmailIntegration;
 const DiscordIntegration = require('./discord.js').DiscordIntegration;
 const AirtableIntegration = require('./airtable.js').AirtableIntegration;
 const GoogleCalendarIntegration = require('./google-calendar.js').GoogleCalendarIntegration;
+const WhatsAppIntegration = require('./whatsapp.js').WhatsAppIntegration;
 
 /**
  * Factory to create integrations
@@ -40,6 +41,7 @@ function createIntegration(type, config) {
     case 'discord': return new DiscordIntegration(config.webhookUrl);
     case 'airtable': return new AirtableIntegration(config.apiKey, config.baseId);
     case 'google-calendar': return new GoogleCalendarIntegration(config.credentials);
+    case 'whatsapp': return new WhatsAppIntegration(config.phoneNumberId, config.accessToken);
     default: throw new Error(`Unknown integration type: ${type}`);
   }
 }
@@ -56,6 +58,7 @@ module.exports = {
   DiscordIntegration,
   AirtableIntegration,
   GoogleCalendarIntegration,
+  WhatsAppIntegration,
   // Factory
   createIntegration
 };

package/examples/whatsapp-telegram-bridge-demo.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * WhatsApp ↔ Telegram Bridge Demo
+ * 
+ * This demo shows how the bridge works without requiring real credentials.
+ * It uses mock implementations to demonstrate the flow.
+ */
+
+// Mock implementations for demo
+class MockWhatsAppIntegration {
+  constructor(phoneNumberId, accessToken) {
+    this.phoneNumberId = phoneNumberId;
+    this.accessToken = accessToken;
+    console.log(`📱 WhatsApp Integration initialized (Phone: ${phoneNumberId})`);
+  }
+
+  async sendMessage(to, body) {
+    console.log(`   📤 WhatsApp → ${to}: "${body.substring(0, 50)}..."`);
+    return { 
+      messaging_product: 'whatsapp',
+      contacts: [{ input: to, wa_id: to }],
+      messages: [{ id: `wamid.${Date.now()}` }]
+    };
+  }
+
+  async getMessages() {
+    return { messages: [] };
+  }
+}
+
+class MockTelegramIntegration {
+  constructor(botToken) {
+    this.botToken = botToken;
+    this.messageId = 1000;
+    console.log(`💬 Telegram Integration initialized (Bot: ${botToken.substring(0, 10)}...)`);
+  }
+
+  async sendMessage(chatId, text) {
+    this.messageId++;
+    console.log(`   📤 Telegram → Chat ${chatId}:`);
+    console.log(`      ${text.substring(0, 100)}...`);
+    return { 
+      message_id: this.messageId,
+      chat: { id: chatId },
+      text: text
+    };
+  }
+
+  async getUpdates() {
+    return { result: [] };
+  }
+}
+
+// Import A3M Router
+const { createA3MRouter } = require('../dist/index.js');
+
+/**
+ * WhatsApp → Telegram Bridge Demo
+ */
+class WhatsAppTelegramBridgeDemo {
+  constructor() {
+    this.whatsapp = new MockWhatsAppIntegration('1234567890', 'mock_token');
+    this.telegram = new MockTelegramIntegration('mock_bot_token_12345');
+    this.telegramChatId = '987654321';
+    
+    // A3M Router for intelligent routing
+    this.router = createA3MRouter();
+    
+    // Message tracking
+    this.pendingReplies = new Map();
+    this.demoMode = true;
+  }
+
+  async handleWhatsAppMessage(whatsappMessage) {
+    console.log('\n📩 STEP 1: Received WhatsApp Message');
+    console.log('─────────────────────────────────────────────────────────────');
+    
+    const entry = whatsappMessage.entry?.[0];
+    const change = entry?.changes?.[0];
+    const value = change?.value;
+    const message = value?.messages?.[0];
+    
+    if (!message) {
+      console.log('❌ No message in payload');
+      return;
+    }
+
+    const from = message.from;
+    const text = message.text?.body || '';
+    const messageId = message.id;
+
+    console.log(`   From: ${from}`);
+    console.log(`   Text: "${text}"`);
+    console.log(`   Message ID: ${messageId}`);
+
+    // Route the message
+    console.log('\n🔀 STEP 2: Route Message via A3M Router');
+    console.log('─────────────────────────────────────────────────────────────');
+    
+    const route = this.router.route(text);
+    console.log(`   Primary Model: ${route.primary_model}`);
+    console.log(`   Fallbacks: ${route.fallback_models.slice(0, 2).join(', ')}`);
+    console.log(`   Estimated Cost: $${route.estimated_cost.toFixed(6)}`);
+    console.log(`   Reasoning: ${route.reasoning}`);
+
+    // Forward to Telegram
+    console.log('\n📤 STEP 3: Forward to Telegram Bot');
+    console.log('─────────────────────────────────────────────────────────────');
+    
+    const telegramResult = await this.forwardToTelegram(from, text, route);
+    
+    this.pendingReplies.set(telegramResult.messageId, {
+      whatsappUser: from,
+      originalText: text,
+      timestamp: Date.now(),
+    });
+
+    console.log(`   Telegram Message ID: ${telegramResult.messageId}`);
+    console.log(`   Status: ✅ Forwarded successfully`);
+
+    // Simulate Telegram bot reply
+    console.log('\n📩 STEP 4: Telegram Bot Processes & Replies');
+    console.log('─────────────────────────────────────────────────────────────');
+    
+    await this.simulateTelegramReply(telegramResult.messageId, text);
+
+    return telegramResult;
+  }
+
+  async forwardToTelegram(whatsappUser, text, route) {
+    const formattedMessage = `
+🔄 <b>WhatsApp Bridge</b>
+📱 <b>From:</b> ${whatsappUser}
+🤖 <b>Route:</b> ${route.primary_model}
+💰 <b>Est. Cost:</b> $${route.estimated_cost.toFixed(6)}
+
+💬 <b>Message:</b>
+${text}
+
+<i>Reply to this message to respond back to WhatsApp user</i>
+    `.trim();
+
+    const result = await this.telegram.sendMessage(this.telegramChatId, formattedMessage);
+
+    return {
+      messageId: result.message_id,
+      chatId: this.telegramChatId,
+    };
+  }
+
+  async simulateTelegramReply(originalMessageId, originalText) {
+    // Simulate bot processing time
+    console.log('   🤖 Bot is processing...');
+    await new Promise(r => setTimeout(r, 1000));
+
+    // Generate contextual reply
+    let reply;
+    if (originalText.toLowerCase().includes('order')) {
+      reply = `I've checked your order. It will be shipped tomorrow! 📦`;
+    } else if (originalText.toLowerCase().includes('help')) {
+      reply = `I'm here to help! What do you need assistance with? 🤝`;
+    } else if (originalText.toLowerCase().includes('price')) {
+      reply = `Let me check the pricing for you. One moment please... 💰`;
+    } else {
+      reply = `Thanks for your message! Our team will get back to you shortly. ⏰`;
+    }
+
+    console.log(`   Bot Reply: "${reply}"`);
+
+    // Handle the reply
+    await this.handleTelegramReply({
+      message: {
+        message_id: Date.now(),
+        reply_to_message: { message_id: originalMessageId },
+        text: reply,
+        chat: { id: this.telegramChatId }
+      }
+    });
+  }
+
+  async handleTelegramReply(telegramUpdate) {
+    console.log('\n📤 STEP 5: Send Reply Back to WhatsApp');
+    console.log('─────────────────────────────────────────────────────────────');
+    
+    const message = telegramUpdate.message;
+    const replyToMessage = message.reply_to_message;
+    const originalMessageId = replyToMessage.message_id;
+    
+    const pending = this.pendingReplies.get(originalMessageId);
+    if (!pending) {
+      console.log('❌ No pending reply found');
+      return;
+    }
+
+    const replyText = message.text;
+    console.log(`   Original WhatsApp User: ${pending.whatsappUser}`);
+    console.log(`   Reply Text: "${replyText}"`);
+
+    // Send back to WhatsApp
+    await this.whatsapp.sendMessage(pending.whatsappUser, replyText);
+
+    this.pendingReplies.delete(originalMessageId);
+    
+    console.log('   Status: ✅ Reply sent successfully');
+  }
+}
+
+// Demo scenarios
+const DEMO_MESSAGES = [
+  {
+    description: 'Customer asking about order',
+    payload: {
+      entry: [{
+        changes: [{
+          value: {
+            messages: [{
+              from: '+1234567890',
+              id: 'wamid.demo1',
+              text: { body: 'Hello, I need help with my order #12345' },
+              timestamp: Date.now().toString(),
+            }],
+          },
+        }],
+      }],
+    },
+  },
+  {
+    description: 'Customer asking for pricing',
+    payload: {
+      entry: [{
+        changes: [{
+          value: {
+            messages: [{
+              from: '+9876543210',
+              id: 'wamid.demo2',
+              text: { body: 'What is the price for your premium plan?' },
+              timestamp: Date.now().toString(),
+            }],
+          },
+        }],
+      }],
+    },
+  },
+  {
+    description: 'General inquiry',
+    payload: {
+      entry: [{
+        changes: [{
+          value: {
+            messages: [{
+              from: '+5555555555',
+              id: 'wamid.demo3',
+              text: { body: 'Hi there, I have a question about your services' },
+              timestamp: Date.now().toString(),
+            }],
+          },
+        }],
+      }],
+    },
+  },
+];
+
+// Run demo
+async function main() {
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log('📱 WhatsApp ↔ Telegram Bridge Demo');
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log('');
+  console.log('This demo shows how to use a Telegram bot to process');
+  console.log('WhatsApp messages and send replies back.');
+  console.log('');
+
+  const bridge = new WhatsAppTelegramBridgeDemo();
+
+  for (const scenario of DEMO_MESSAGES) {
+    console.log('\n═══════════════════════════════════════════════════════════════');
+    console.log(`📝 Scenario: ${scenario.description}`);
+    console.log('═══════════════════════════════════════════════════════════════');
+    
+    await bridge.handleWhatsAppMessage(scenario.payload);
+    
+    // Wait between scenarios
+    await new Promise(r => setTimeout(r, 1500));
+  }
+
+  console.log('\n═══════════════════════════════════════════════════════════════');
+  console.log('✅ Demo Complete!');
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log('');
+  console.log('To use in production:');
+  console.log('  1. Get WhatsApp Business API credentials');
+  console.log('  2. Create Telegram bot via @BotFather');
+  console.log('  3. Set up webhooks for both platforms');
+  console.log('  4. Use whatsapp-telegram-bridge.js with real credentials');
+  console.log('');
+  console.log('Documentation:');
+  console.log('  - WhatsApp: https://business.whatsapp.com/products/business-platform');
+  console.log('  - Telegram: https://core.telegram.org/bots/api');
+  console.log('');
+}
+
+main().catch(console.error);

package/examples/whatsapp-telegram-bridge.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * WhatsApp ↔ Telegram Bridge Example
+ * 
+ * This example shows how to use a Telegram bot to process
+ * WhatsApp messages and send replies back.
+ * 
+ * Prerequisites:
+ * 1. WhatsApp Business API credentials (phoneNumberId, accessToken)
+ * 2. Telegram Bot Token (from @BotFather)
+ * 3. Webhook endpoint to receive WhatsApp messages
+ * 
+ * Usage:
+ *   node whatsapp-telegram-bridge.js
+ */
+
+const { 
+  createIntegration,
+  WhatsAppIntegration,
+  TelegramIntegration,
+  createA3MRouter 
+} = require('../dist/index.js');
+
+// Configuration
+const CONFIG = {
+  whatsapp: {
+    phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,
+    accessToken: process.env.WHATSAPP_ACCESS_TOKEN,
+  },
+  telegram: {
+    botToken: process.env.TELEGRAM_BOT_TOKEN,
+    // The chat ID where your bot will process messages
+    // This could be your personal chat with the bot
+    chatId: process.env.TELEGRAM_CHAT_ID,
+  },
+};
+
+// Validate config
+function validateConfig() {
+  const missing = [];
+  if (!CONFIG.whatsapp.phoneNumberId) missing.push('WHATSAPP_PHONE_NUMBER_ID');
+  if (!CONFIG.whatsapp.accessToken) missing.push('WHATSAPP_ACCESS_TOKEN');
+  if (!CONFIG.telegram.botToken) missing.push('TELEGRAM_BOT_TOKEN');
+  if (!CONFIG.telegram.chatId) missing.push('TELEGRAM_CHAT_ID');
+  
+  if (missing.length > 0) {
+    console.error('❌ Missing environment variables:');
+    missing.forEach(v => console.error(`   - ${v}`));
+    console.error('\nSet these variables and try again.');
+    process.exit(1);
+  }
+}
+
+/**
+ * WhatsApp → Telegram Bridge
+ * 
+ * Flow:
+ * 1. Receive message from WhatsApp (via webhook)
+ * 2. Forward message to Telegram bot
+ * 3. Get reply from Telegram (bot processes it)
+ * 4. Send reply back to WhatsApp user
+ */
+class WhatsAppTelegramBridge {
+  constructor(config) {
+    this.whatsapp = new WhatsAppIntegration(
+      config.whatsapp.phoneNumberId,
+      config.whatsapp.accessToken
+    );
+    this.telegram = new TelegramIntegration(config.telegram.botToken);
+    this.telegramChatId = config.telegram.chatId;
+    
+    // A3M Router for intelligent routing
+    this.router = createA3MRouter();
+    
+    // Message tracking
+    this.pendingReplies = new Map(); // messageId -> { whatsappUser, timestamp }
+  }
+
+  /**
+   * Handle incoming WhatsApp message
+   * @param {Object} whatsappMessage - WhatsApp webhook payload
+   */
+  async handleWhatsAppMessage(whatsappMessage) {
+    try {
+      // Extract message details
+      const entry = whatsappMessage.entry?.[0];
+      const change = entry?.changes?.[0];
+      const value = change?.value;
+      const message = value?.messages?.[0];
+      
+      if (!message) {
+        console.log('No message in webhook payload');
+        return;
+      }
+
+      const from = message.from; // WhatsApp user phone number
+      const text = message.text?.body || '';
+      const messageId = message.id;
+
+      console.log(`📩 WhatsApp message from ${from}: "${text.substring(0, 50)}..."`);
+
+      // Route the message to get best processing strategy
+      const route = this.router.route(text);
+      console.log(`🔀 Routed to: ${route.primary_model} (${route.reasoning})`);
+
+      // Forward to Telegram bot with context
+      const telegramMessage = await this.forwardToTelegram(from, text, route);
+      
+      // Track pending reply
+      this.pendingReplies.set(telegramMessage.messageId, {
+        whatsappUser: from,
+        originalText: text,
+        timestamp: Date.now(),
+      });
+
+      console.log(`📤 Forwarded to Telegram (message ID: ${telegramMessage.messageId})`);
+
+    } catch (error) {
+      console.error('❌ Error handling WhatsApp message:', error.message);
+    }
+  }
+
+  /**
+   * Forward WhatsApp message to Telegram
+   */
+  async forwardToTelegram(whatsappUser, text, route) {
+    // Format message for Telegram bot
+    const formattedMessage = `
+🔄 <b>WhatsApp Bridge</b>
+📱 <b>From:</b> ${whatsappUser}
+🤖 <b>Route:</b> ${route.primary_model}
+
+💬 <b>Message:</b>
+${text}
+
+<i>Reply to this message to respond back to WhatsApp user</i>
+    `.trim();
+
+    // Send to Telegram
+    const result = await this.telegram.sendMessage(
+      this.telegramChatId,
+      formattedMessage
+    );
+
+    return {
+      messageId: result.message_id || `msg_${Date.now()}`,
+      chatId: this.telegramChatId,
+    };
+  }
+
+  /**
+   * Handle Telegram reply
+   * @param {Object} telegramUpdate - Telegram webhook/update payload
+   */
+  async handleTelegramReply(telegramUpdate) {
+    try {
+      const message = telegramUpdate.message || telegramUpdate.callback_query?.message;
+      if (!message) return;
+
+      const replyToMessage = message.reply_to_message;
+      if (!replyToMessage) {
+        console.log('Not a reply message, ignoring');
+        return;
+      }
+
+      // Extract original message ID from reply
+      const originalMessageId = replyToMessage.message_id;
+      const pending = this.pendingReplies.get(originalMessageId);
+
+      if (!pending) {
+        console.log('No pending WhatsApp reply found for this message');
+        return;
+      }
+
+      const replyText = message.text || message.caption || '';
+      console.log(`📩 Telegram reply: "${replyText.substring(0, 50)}..."`);
+
+      // Send reply back to WhatsApp
+      await this.sendWhatsAppReply(pending.whatsappUser, replyText);
+
+      // Clean up pending reply
+      this.pendingReplies.delete(originalMessageId);
+
+    } catch (error) {
+      console.error('❌ Error handling Telegram reply:', error.message);
+    }
+  }
+
+  /**
+   * Send reply back to WhatsApp user
+   */
+  async sendWhatsAppReply(to, text) {
+    const result = await this.whatsapp.sendMessage(to, text);
+    console.log(`📤 Sent WhatsApp reply to ${to}: "${text.substring(0, 50)}..."`);
+    return result;
+  }
+
+  /**
+   * Clean up old pending replies (older than 1 hour)
+   */
+  cleanupPendingReplies() {
+    const now = Date.now();
+    const oneHour = 60 * 60 * 1000;
+    
+    for (const [messageId, pending] of this.pendingReplies) {
+      if (now - pending.timestamp > oneHour) {
+        this.pendingReplies.delete(messageId);
+        console.log(`🧹 Cleaned up expired pending reply: ${messageId}`);
+      }
+    }
+  }
+
+  /**
+   * Start cleanup interval
+   */
+  startCleanup() {
+    setInterval(() => this.cleanupPendingReplies(), 5 * 60 * 1000); // Every 5 minutes
+  }
+}
+
+// Example usage
+async function main() {
+  validateConfig();
+
+  console.log('🚀 Starting WhatsApp ↔ Telegram Bridge\n');
+
+  const bridge = new WhatsAppTelegramBridge(CONFIG);
+  bridge.startCleanup();
+
+  console.log('✅ Bridge initialized');
+  console.log(`   WhatsApp Phone Number ID: ${CONFIG.whatsapp.phoneNumberId}`);
+  console.log(`   Telegram Chat ID: ${CONFIG.telegram.chatId}`);
+  console.log('');
+
+  // Example: Simulate receiving a WhatsApp message
+  console.log('📋 Example: Simulating WhatsApp webhook payload\n');
+  
+  const exampleWhatsAppMessage = {
+    entry: [{
+      changes: [{
+        value: {
+          messages: [{
+            from: '1234567890',
+            id: 'wamid.example123',
+            text: { body: 'Hello, I need help with my order #12345' },
+            timestamp: Date.now().toString(),
+          }],
+        },
+      }],
+    }],
+  };
+
+  await bridge.handleWhatsAppMessage(exampleWhatsAppMessage);
+
+  console.log('\n📋 To use this in production:');
+  console.log('   1. Set up WhatsApp Business API webhook');
+  console.log('   2. Set up Telegram bot webhook');
+  console.log('   3. Route webhooks to handleWhatsAppMessage() and handleTelegramReply()');
+  console.log('');
+  console.log('📖 See: https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks');
+  console.log('📖 See: https://core.telegram.org/bots/webhooks');
+}
+
+// Run if executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+module.exports = { WhatsAppTelegramBridge };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adaptive-memory-multi-model-router",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "shortName": "A3M Router",
   "displayName": "A3M Router - Adaptive Memory Multi-Model Router",
   "description": "A3M Router - Adaptive Memory Multi-Model Router with learned routing (RouteLLM), prefix caching (RadixAttention), speculative decoding (Medusa), TokenJuice-style compression. 14 LLM providers, 10 integrations, Python bindings. 20x more adaptable for ML/AI developers.",
@@ -174,7 +174,10 @@
   },
   "homepage": "https://github.com/Das-rebel/adaptive-memory-multi-model-router#readme",
   "scripts": {
-    "test": "node test.js"
+    "test": "node test.js && node test/provider-test.js",
+    "test:providers": "node test/provider-test.js",
+    "benchmark": "node test/benchmark.js",
+    "benchmark:verbose": "node test/benchmark.js --verbose"
   },
   "engines": {
     "node": ">=16.0.0"

package/test/benchmark.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * A3M Router - Provider Benchmark
+ * 
+ * Benchmarks all available providers across:
+ * - Latency (response time)
+ * - Cost (per 1K tokens)
+ * - Quality (simple factual questions)
+ * - Cost-effectiveness (quality per dollar)
+ */
+
+const { execSync } = require('child_process');
+const {
+  getAvailableProviders,
+  providerConfig,
+  countTokens,
+  estimateCost,
+} = require('../dist/index.js');
+
+// Benchmark configuration
+const CONFIG = {
+  timeout: 60000,
+  maxTokens: 50,
+  verbose: process.argv.includes('--verbose') || process.argv.includes('-v'),
+  json: process.argv.includes('--json'),
+  provider: process.argv.find(arg => arg.startsWith('--provider='))?.split('=')[1],
+};
+
+// Test queries for different scenarios
+const QUERIES = {
+  simple: 'What is 2+2?',
+  code: 'Write a Python function to reverse a string.',
+  math: 'Calculate the square root of 144.',
+  creative: 'Write a haiku about programming.',
+  reasoning: 'Explain why the sky is blue.',
+};
+
+// Results storage
+const results = [];
+
+// Helper: Call a provider
+async function callProvider(id, provider, query) {
+  const model = provider.models[0];
+  const startTime = Date.now();
+  
+  try {
+    if (provider.type === 'cli') {
+      // CLI provider
+      if (id === 'commandcode') {
+        const raw = execSync(`commandcode -p "${query.replace(/"/g, '\\"')}" --skip-onboarding 2>&1`, { 
+          timeout: CONFIG.timeout, 
+          encoding: 'utf-8' 
+        });
+        const content = raw.replace(/\x1b\[[0-9;]*m/g, '').trim();
+        const latency = Date.now() - startTime;
+        const tokens = Math.ceil(content.length / 4);
+        return {
+          content: content.substring(0, 200),
+          tokens,
+          cost: 0,
+          latency,
+          success: true,
+        };
+      } else {
+        // Generic CLI
+        const raw = execSync(`${provider.cliCommand} run "${query.replace(/"/g, '\\"')}" 2>&1`, { 
+          timeout: CONFIG.timeout, 
+          encoding: 'utf-8' 
+        });
+        const lines = raw.replace(/\x1b\[[0-9;]*m/g, '').split('\n').filter(l => l.trim() && !l.startsWith('>'));
+        const content = lines.join(' ').trim();
+        const latency = Date.now() - startTime;
+        const tokens = Math.ceil(content.length / 4);
+        return {
+          content: content.substring(0, 200),
+          tokens,
+          cost: 0,
+          latency,
+          success: true,
+        };
+      }
+    }
+    
+    // API provider
+    if (!provider.apiKey) {
+      return { error: 'No API key', success: false };
+    }
+    
+    const resp = await fetch(provider.baseUrl, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${provider.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: 'user', content: query }],
+        max_tokens: CONFIG.maxTokens,
+      }),
+    });
+    
+    const latency = Date.now() - startTime;
+    const data = await resp.json();
+    
+    if (data.error) {
+      return { error: data.error.message, success: false };
+    }
+    
+    const content = data.choices?.[0]?.message?.content || '';
+    const promptTokens = data.usage?.prompt_tokens || countTokens(query);
+    const completionTokens = data.usage?.completion_tokens || countTokens(content);
+    const cost = (promptTokens / 1000 * provider.costPerK.input) + 
+                 (completionTokens / 1000 * provider.costPerK.output);
+    
+    return {
+      content: content.substring(0, 200),
+      tokens: promptTokens + completionTokens,
+      cost,
+      latency,
+      success: true,
+    };
+    
+  } catch (e) {
+    return { error: e.message, success: false };
+  }
+}
+
+// Helper: Check answer quality (simple heuristic)
+function checkQuality(query, response) {
+  const lower = response.toLowerCase();
+  
+  if (query.includes('2+2')) {
+    return lower.includes('4') ? 1 : 0;
+  }
+  if (query.includes('square root of 144')) {
+    return lower.includes('12') ? 1 : 0;
+  }
+  if (query.includes('reverse a string')) {
+    return lower.includes('def') || lower.includes('function') ? 1 : 0;
+  }
+  if (query.includes('haiku')) {
+    // Check for 3 lines (rough haiku check)
+    const lines = response.split('\n').filter(l => l.trim());
+    return lines.length >= 2 ? 1 : 0;
+  }
+  
+  // Default: check for reasonable length
+  return response.length > 20 ? 0.8 : 0.5;
+}
+
+// Main benchmark
+async function runBenchmark() {
+  console.log('\n═══════════════════════════════════════════════════════════════');
+  console.log('📊 A3M Router - Provider Benchmark');
+  console.log('═══════════════════════════════════════════════════════════════\n');
+  
+  const providers = getAvailableProviders();
+  const providerList = CONFIG.provider 
+    ? [[CONFIG.provider, providers[CONFIG.provider]]].filter(([_, p]) => p)
+    : Object.entries(providers);
+  
+  if (providerList.length === 0) {
+    console.log('❌ No providers available. Configure API keys in ~/.config/a3m-router/providers.json');
+    process.exit(1);
+  }
+  
+  console.log(`Testing ${providerList.length} provider(s)...\n`);
+  
+  for (const [id, provider] of providerList) {
+    if (CONFIG.verbose) {
+      console.log(`Testing ${provider.name}...`);
+    }
+    
+    const providerResults = {
+      id,
+      name: provider.name,
+      type: provider.type,
+      model: provider.models[0],
+      queries: {},
+    };
+    
+    for (const [queryType, query] of Object.entries(QUERIES)) {
+      if (CONFIG.verbose) {
+        console.log(`  ${queryType}: "${query.substring(0, 40)}..."`);
+      }
+      
+      const result = await callProvider(id, provider, query);
+      
+      if (result.success) {
+        result.quality = checkQuality(query, result.content);
+        result.costEffectiveness = result.cost > 0 
+          ? result.quality / result.cost 
+          : result.quality * 1000; // Free providers get high score
+      }
+      
+      providerResults.queries[queryType] = result;
+    }
+    
+    // Calculate averages
+    const successful = Object.values(providerResults.queries).filter(r => r.success);
+    if (successful.length > 0) {
+      providerResults.avgLatency = successful.reduce((a, r) => a + r.latency, 0) / successful.length;
+      providerResults.avgCost = successful.reduce((a, r) => a + r.cost, 0) / successful.length;
+      providerResults.avgQuality = successful.reduce((a, r) => a + r.quality, 0) / successful.length;
+      providerResults.avgCostEffectiveness = successful.reduce((a, r) => a + r.costEffectiveness, 0) / successful.length;
+    }
+    
+    results.push(providerResults);
+  }
+  
+  // Output results
+  if (CONFIG.json) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    printResults(results);
+  }
+}
+
+function printResults(results) {
+  // Summary table
+  console.log('┌─────────────────────────────────────────────────────────────────────────────┐');
+  console.log('│ Provider          Type    Model                    Latency  Cost    Quality │');
+  console.log('├─────────────────────────────────────────────────────────────────────────────┤');
+  
+  // Sort by cost-effectiveness
+  const sorted = [...results].sort((a, b) => (b.avgCostEffectiveness || 0) - (a.avgCostEffectiveness || 0));
+  
+  for (const r of sorted) {
+    const name = r.name.substring(0, 17).padEnd(17);
+    const type = r.type.padEnd(7);
+    const model = (r.model || 'N/A').substring(0, 22).padEnd(22);
+    const latency = r.avgLatency ? `${Math.round(r.avgLatency)}ms`.padEnd(8) : 'N/A     ';
+    const cost = r.avgCost !== undefined ? `$${r.avgCost.toFixed(4)}`.padEnd(7) : 'N/A    ';
+    const quality = r.avgQuality ? `${(r.avgQuality * 100).toFixed(0)}%`.padEnd(7) : 'N/A    ';
+    
+    console.log(`│ ${name} ${type} ${model} ${latency} ${cost} ${quality} │`);
+  }
+  
+  console.log('└─────────────────────────────────────────────────────────────────────────────┘');
+  console.log('');
+  
+  // Rankings
+  console.log('🏆 Rankings:');
+  console.log('─────────────────────────────────────────────────────────────');
+  
+  // Fastest
+  const fastest = [...results].filter(r => r.avgLatency).sort((a, b) => a.avgLatency - b.avgLatency)[0];
+  if (fastest) {
+    console.log(`  ⚡ Fastest:      ${fastest.name} (${Math.round(fastest.avgLatency)}ms avg)`);
+  }
+  
+  // Cheapest
+  const cheapest = [...results].filter(r => r.avgCost !== undefined).sort((a, b) => a.avgCost - b.avgCost)[0];
+  if (cheapest) {
+    console.log(`  💰 Cheapest:     ${cheapest.name} ($${cheapest.avgCost.toFixed(6)} avg)`);
+  }
+  
+  // Best quality
+  const bestQuality = [...results].filter(r => r.avgQuality).sort((a, b) => b.avgQuality - a.avgQuality)[0];
+  if (bestQuality) {
+    console.log(`  🎯 Best Quality: ${bestQuality.name} (${(bestQuality.avgQuality * 100).toFixed(0)}% correct)`);
+  }
+  
+  // Best cost-effectiveness
+  const bestValue = sorted[0];
+  if (bestValue) {
+    console.log(`  ⭐ Best Value:   ${bestValue.name} (quality/$)`);
+  }
+  
+  console.log('');
+  
+  // Detailed results
+  if (CONFIG.verbose) {
+    console.log('📋 Detailed Results:');
+    console.log('─────────────────────────────────────────────────────────────');
+    
+    for (const r of results) {
+      console.log(`\n${r.name} (${r.type}):`);
+      
+      for (const [queryType, result] of Object.entries(r.queries)) {
+        if (result.success) {
+          console.log(`  ${queryType.padEnd(10)} ${result.latency}ms  $${result.cost.toFixed(6)}  Q:${(result.quality * 100).toFixed(0)}%  "${result.content.substring(0, 50)}..."`);
+        } else {
+          console.log(`  ${queryType.padEnd(10)} ❌ ${result.error || 'Failed'}`);
+        }
+      }
+    }
+  }
+  
+  console.log('');
+}
+
+// Run benchmark
+runBenchmark().catch(e => {
+  console.error('Benchmark failed:', e.message);
+  process.exit(1);
+});

package/test/provider-test.js

@@ -0,0 +1,472 @@
+#!/usr/bin/env node
+/**
+ * A3M Router - Provider Test Framework
+ * 
+ * Comprehensive tests for the generic provider system.
+ * Tests work with whatever providers the user has configured.
+ */
+
+const {
+  createA3MRouter,
+  getAvailableProviders,
+  registerProvider,
+  deregisterProvider,
+  DEFAULT_PROVIDERS,
+  providerConfig,
+  routeQuery,
+  routeBatch,
+  recommendForTask,
+  extractQueryFeatures,
+  MODEL_PROFILES,
+  countTokens,
+  estimateCost,
+  MemoryTree,
+  CostTracker,
+  ResponseCache,
+  ProviderRegistry,
+  compressText,
+  isonEncode,
+  isonDecode,
+} = require('../dist/index.js');
+
+// Test configuration
+const TEST_CONFIG = {
+  verbose: process.argv.includes('--verbose') || process.argv.includes('-v'),
+  skipLive: process.argv.includes('--skip-live'),
+  timeout: 30000,
+};
+
+// Test state
+let passed = 0;
+let failed = 0;
+let skipped = 0;
+
+// Test utilities
+function log(message, level = 'info') {
+  if (level === 'error') console.error(message);
+  else if (TEST_CONFIG.verbose || level !== 'debug') console.log(message);
+}
+
+function test(name, fn) {
+  try {
+    fn();
+    log(`  ✅ ${name}`, 'success');
+    passed++;
+  } catch (e) {
+    log(`  ❌ ${name}: ${e.message}`, 'error');
+    failed++;
+  }
+}
+
+async function asyncTest(name, fn) {
+  try {
+    await fn();
+    log(`  ✅ ${name}`, 'success');
+    passed++;
+  } catch (e) {
+    log(`  ❌ ${name}: ${e.message}`, 'error');
+    failed++;
+  }
+}
+
+function skip(name, reason) {
+  log(`  ⏭️  ${name} (skipped: ${reason})`, 'warn');
+  skipped++;
+}
+
+// ============================================================
+// TEST SUITE
+// ============================================================
+
+console.log('\n═══════════════════════════════════════════════════════════════');
+console.log('🧪 A3M Router - Provider Test Framework');
+console.log('═══════════════════════════════════════════════════════════════\n');
+
+// 1. Provider Configuration Tests
+console.log('📦 1. Provider Configuration');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('providerConfig module loads', () => {
+  if (!providerConfig) throw new Error('providerConfig not exported');
+  if (typeof providerConfig.loadConfig !== 'function') throw new Error('loadConfig not a function');
+  if (typeof providerConfig.getAvailableProviders !== 'function') throw new Error('getAvailableProviders not a function');
+});
+
+test('DEFAULT_PROVIDERS has expected structure', () => {
+  if (!DEFAULT_PROVIDERS) throw new Error('DEFAULT_PROVIDERS not defined');
+  
+  // Check at least some providers exist
+  const providerCount = Object.keys(DEFAULT_PROVIDERS).length;
+  if (providerCount < 5) throw new Error(`Expected at least 5 providers, got ${providerCount}`);
+  
+  // Check provider structure
+  for (const [id, provider] of Object.entries(DEFAULT_PROVIDERS)) {
+    if (!provider.id) throw new Error(`${id}: missing id`);
+    if (!provider.name) throw new Error(`${id}: missing name`);
+    if (!provider.type) throw new Error(`${id}: missing type`);
+    if (!['api', 'cli', 'local'].includes(provider.type)) throw new Error(`${id}: invalid type ${provider.type}`);
+    if (typeof provider.priority !== 'number') throw new Error(`${id}: missing priority`);
+  }
+});
+
+test('getAvailableProviders returns configured providers', () => {
+  const available = getAvailableProviders();
+  if (!available) throw new Error('getAvailableProviders returned null');
+  
+  // Should return object with providers that have API keys
+  for (const [id, provider] of Object.entries(available)) {
+    if (!provider.id) throw new Error(`${id}: missing id`);
+    if (!provider.name) throw new Error(`${id}: missing name`);
+    if (!provider.models) throw new Error(`${id}: missing models`);
+    if (!Array.isArray(provider.models)) throw new Error(`${id}: models not an array`);
+  }
+});
+
+test('Provider types are correct', () => {
+  const available = getAvailableProviders();
+  
+  for (const [id, provider] of Object.entries(available)) {
+    if (!['api', 'cli', 'local'].includes(provider.type)) {
+      throw new Error(`${id}: invalid type ${provider.type}`);
+    }
+    
+    // API providers should have baseUrl and apiKeyEnv
+    if (provider.type === 'api') {
+      if (!provider.baseUrl) throw new Error(`${id}: API provider missing baseUrl`);
+      if (!provider.apiKeyEnv) throw new Error(`${id}: API provider missing apiKeyEnv`);
+    }
+    
+    // CLI providers should have cliCommand
+    if (provider.type === 'cli') {
+      if (!provider.cliCommand) throw new Error(`${id}: CLI provider missing cliCommand`);
+    }
+  }
+});
+
+// 2. Routing Tests
+console.log('\n🔀 2. Routing');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('routeQuery returns valid result', () => {
+  const result = routeQuery('What is 2+2?');
+  if (!result) throw new Error('routeQuery returned null');
+  if (!result.primary_model) throw new Error('missing primary_model');
+  if (!Array.isArray(result.fallback_models)) throw new Error('fallback_models not an array');
+  if (typeof result.estimated_cost !== 'number') throw new Error('estimated_cost not a number');
+  if (typeof result.confidence !== 'number') throw new Error('confidence not a number');
+});
+
+test('routeQuery selects appropriate provider for code', () => {
+  const result = routeQuery('Write a Python function to sort an array');
+  if (!result.primary_model) throw new Error('missing primary_model');
+  if (!result.reasoning) throw new Error('missing reasoning');
+  
+  // Should detect code
+  const features = extractQueryFeatures('Write a Python function to sort an array');
+  if (!features.has_code) throw new Error('should detect code');
+});
+
+test('routeQuery selects appropriate provider for math', () => {
+  const result = routeQuery('Calculate the integral of x^2');
+  if (!result.primary_model) throw new Error('missing primary_model');
+  
+  const features = extractQueryFeatures('Calculate the integral of x^2');
+  if (!features.has_math) throw new Error('should detect math');
+});
+
+test('routeQuery selects appropriate provider for translation', () => {
+  const result = routeQuery('Translate hello to French');
+  if (!result.primary_model) throw new Error('missing primary_model');
+  
+  const features = extractQueryFeatures('Translate hello to French');
+  if (!features.is_translation) throw new Error('should detect translation');
+});
+
+test('routeBatch returns array of results', () => {
+  const queries = ['Hello', 'What is 2+2?', 'Write Python code'];
+  const results = routeBatch(queries);
+  
+  if (!Array.isArray(results)) throw new Error('routeBatch should return array');
+  if (results.length !== queries.length) throw new Error(`Expected ${queries.length} results, got ${results.length}`);
+  
+  results.forEach((r, i) => {
+    if (!r.primary_model) throw new Error(`result ${i}: missing primary_model`);
+  });
+});
+
+test('recommendForTask returns recommendation', () => {
+  const rec = recommendForTask('coding');
+  if (!rec) throw new Error('recommendForTask returned null');
+  if (!rec.primary) throw new Error('missing primary');
+  if (!Array.isArray(rec.fallbacks)) throw new Error('fallbacks not an array');
+  if (!rec.reason) throw new Error('missing reason');
+});
+
+// 3. Model Profile Tests
+console.log('\n📊 3. Model Profiles');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('MODEL_PROFILES is populated', () => {
+  if (!MODEL_PROFILES) throw new Error('MODEL_PROFILES not defined');
+  if (Object.keys(MODEL_PROFILES).length === 0) throw new Error('MODEL_PROFILES is empty');
+});
+
+test('Model profiles have required fields', () => {
+  for (const [name, profile] of Object.entries(MODEL_PROFILES)) {
+    if (!profile.name) throw new Error(`${name}: missing name`);
+    if (!profile.provider) throw new Error(`${name}: missing provider`);
+    if (typeof profile.cost_per_1k_input !== 'number') throw new Error(`${name}: missing cost_per_1k_input`);
+    if (typeof profile.cost_per_1k_output !== 'number') throw new Error(`${name}: missing cost_per_1k_output`);
+    if (typeof profile.quality_score !== 'number') throw new Error(`${name}: missing quality_score`);
+    if (!Array.isArray(profile.strengths)) throw new Error(`${name}: strengths not an array`);
+  }
+});
+
+// 4. Token Utility Tests
+console.log('\n🔢 4. Token Utilities');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('countTokens returns number', () => {
+  const tokens = countTokens('Hello world');
+  if (typeof tokens !== 'number') throw new Error('should return number');
+  if (tokens <= 0) throw new Error('should return positive number');
+});
+
+test('countTokens counts correctly', () => {
+  const tokens = countTokens('Hello world');
+  if (tokens < 2) throw new Error('should count at least 2 tokens for 2 words');
+});
+
+test('estimateCost returns number', () => {
+  const cost = estimateCost(100, 50, 'gpt-4o');
+  if (typeof cost !== 'number') throw new Error('should return number');
+  if (cost < 0) throw new Error('should return non-negative');
+});
+
+// 5. A3M Router Factory Tests
+console.log('\n🏭 5. A3M Router Factory');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('createA3MRouter returns router object', () => {
+  const router = createA3MRouter({});
+  if (!router) throw new Error('createA3MRouter returned null');
+  if (typeof router.route !== 'function') throw new Error('missing route function');
+  if (typeof router.routeBatch !== 'function') throw new Error('missing routeBatch function');
+  if (typeof router.recommend !== 'function') throw new Error('missing recommend function');
+});
+
+test('createA3MRouter has memory', () => {
+  const router = createA3MRouter({});
+  if (!router.memory) throw new Error('missing memory');
+  if (typeof router.memory.add !== 'function') throw new Error('memory missing add');
+  if (typeof router.memory.search !== 'function') throw new Error('memory missing search');
+});
+
+test('createA3MRouter has cache', () => {
+  const router = createA3MRouter({});
+  if (!router.cache) throw new Error('missing cache');
+});
+
+test('createA3MRouter has costTracker', () => {
+  const router = createA3MRouter({});
+  if (!router.costTracker) throw new Error('missing costTracker');
+});
+
+test('createA3MRouter has providers registry', () => {
+  const router = createA3MRouter({});
+  if (!router.providers) throw new Error('missing providers');
+});
+
+test('createA3MRouter has compression', () => {
+  const router = createA3MRouter({});
+  if (!router.compression) throw new Error('missing compression');
+});
+
+test('createA3MRouter has vault', () => {
+  const router = createA3MRouter({});
+  if (!router.vault) throw new Error('missing vault');
+});
+
+test('createA3MRouter has autoFetch', () => {
+  const router = createA3MRouter({});
+  if (!router.autoFetch) throw new Error('missing autoFetch');
+});
+
+test('createA3MRouter has oauth', () => {
+  const router = createA3MRouter({});
+  if (!router.oauth) throw new Error('missing oauth');
+});
+
+// 6. Memory Tree Tests
+console.log('\n🧠 6. Memory Tree');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('MemoryTree can add and search', () => {
+  const memory = new MemoryTree({ maxSize: 100 });
+  memory.add('Python is great for data science', { tags: ['python', 'data'] });
+  memory.add('JavaScript is great for web', { tags: ['js', 'web'] });
+  
+  const results = memory.search('python data');
+  if (!Array.isArray(results)) throw new Error('search should return array');
+});
+
+test('MemoryTree getStats returns stats', () => {
+  const memory = new MemoryTree({ maxSize: 100 });
+  memory.add('Test entry', { tags: ['test'] });
+  
+  const stats = memory.getStats();
+  if (!stats) throw new Error('getStats returned null');
+  if (typeof stats.totalChunks !== 'number') throw new Error('missing totalChunks');
+});
+
+// 7. Provider Registry Tests
+console.log('\n📋 7. Provider Registry');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('ProviderRegistry can be instantiated', () => {
+  const registry = new ProviderRegistry();
+  if (!registry) throw new Error('failed to create registry');
+  if (typeof registry.getReadyProviders !== 'function') throw new Error('missing getReadyProviders');
+  if (typeof registry.selectModel !== 'function') throw new Error('missing selectModel');
+});
+
+test('ProviderRegistry getStatus returns status', () => {
+  const registry = new ProviderRegistry();
+  const status = registry.getStatus();
+  if (!status) throw new Error('getStatus returned null');
+  if (!Array.isArray(status.providers)) throw new Error('providers not an array');
+});
+
+// 8. Dynamic Provider Registration Tests
+console.log('\n🔧 8. Dynamic Provider Registration');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('registerProvider adds new provider', () => {
+  const testProvider = {
+    name: 'TestProvider',
+    type: 'api',
+    baseUrl: 'https://test.example.com',
+    models: ['test-model'],
+    priority: 99,
+  };
+  
+  registerProvider('test-provider', testProvider);
+  
+  // Check it was added
+  if (!providerConfig._providers['test-provider']) throw new Error('provider not added');
+  if (providerConfig._providers['test-provider'].name !== 'TestProvider') {
+    throw new Error('provider name mismatch');
+  }
+  
+  // Clean up
+  deregisterProvider('test-provider');
+});
+
+test('deregisterProvider removes provider', () => {
+  // First add
+  registerProvider('temp-provider', { name: 'Temp', type: 'api', models: [] });
+  if (!providerConfig._providers['temp-provider']) throw new Error('provider not added');
+  
+  // Then remove
+  deregisterProvider('temp-provider');
+  if (providerConfig._providers['temp-provider']) throw new Error('provider not removed');
+});
+
+// 9. Compression Tests
+console.log('\n🗜️  9. Compression');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('compressText reduces size', () => {
+  const text = 'This is a test message that should be compressed to save tokens.';
+  const compressed = compressText(text, 0.5);
+  if (!compressed) throw new Error('compressText returned null');
+  if (compressed.length >= text.length) throw new Error('compression did not reduce size');
+});
+
+test('isonEncode/Decode roundtrip', () => {
+  const text = 'function test() { return "hello world"; }';
+  const encoded = isonEncode(text);
+  if (!encoded) throw new Error('isonEncode returned null');
+  if (typeof encoded !== 'string') throw new Error('isonEncode should return string');
+  
+  const decoded = isonDecode(encoded);
+  if (!decoded) throw new Error('isonDecode returned null');
+  if (typeof decoded !== 'string') throw new Error('isonDecode should return string');
+  // Decoded might not be identical due to compression, but should be similar
+  if (decoded.length < 5) throw new Error('decoded text too short');
+});
+
+// 10. End-to-End Pipeline Test
+console.log('\n🔄 10. End-to-End Pipeline');
+console.log('─────────────────────────────────────────────────────────────');
+
+test('Full pipeline: route → track → remember', () => {
+  const router = createA3MRouter({ memory: { maxSize: 100 } });
+  
+  // Route
+  const route = router.route('Test query');
+  if (!route.primary_model) throw new Error('routing failed');
+  
+  // Track (via costTracker)
+  if (!router.costTracker) throw new Error('costTracker not available');
+  
+  // Remember
+  router.memory.add('Test query result', { route: route.primary_model });
+  const search = router.memory.search('test');
+  if (!Array.isArray(search)) throw new Error('memory search failed');
+});
+
+// ============================================================
+// LIVE PROVIDER TESTS (if not skipped)
+// ============================================================
+
+if (!TEST_CONFIG.skipLive) {
+  console.log('\n🌐 Live Provider Tests');
+  console.log('─────────────────────────────────────────────────────────────');
+  
+  const available = getAvailableProviders();
+  
+  if (Object.keys(available).length === 0) {
+    skip('No providers configured', 'No API keys found in environment');
+  } else {
+    for (const [id, provider] of Object.entries(available)) {
+      asyncTest(`Health check: ${provider.name}`, async () => {
+        const health = await providerConfig.healthCheck(id);
+        if (!health) throw new Error('healthCheck returned null');
+        
+        // CLI providers may not have traditional health checks
+        if (provider.type === 'cli') {
+          log(`    ${id}: CLI provider (type: ${health.type || 'unknown'})`, 'debug');
+          return;
+        }
+        
+        if (!health.healthy) {
+          throw new Error(`unhealthy: ${health.error || 'unknown error'}`);
+        }
+        
+        log(`    ${id}: healthy (${health.latency}ms)`, 'debug');
+      });
+    }
+  }
+}
+
+// ============================================================
+// SUMMARY
+// ============================================================
+
+console.log('\n═══════════════════════════════════════════════════════════════');
+console.log('📊 Test Summary');
+console.log('═══════════════════════════════════════════════════════════════');
+console.log(`  Total:   ${passed + failed + skipped}`);
+console.log(`  Passed:  ${passed} ✅`);
+console.log(`  Failed:  ${failed}${failed > 0 ? ' ❌' : ''}`);
+console.log(`  Skipped: ${skipped}${skipped > 0 ? ' ⏭️' : ''}`);
+console.log('');
+
+if (failed > 0) {
+  console.log('❌ Some tests failed');
+  process.exit(1);
+} else {
+  console.log('✅ All tests passed!');
+  process.exit(0);
+}