adaptive-memory-multi-model-router 2.14.49 → 2.14.52

package/examples/README.md

@@ -0,0 +1,61 @@
+# A3M Router Usage Examples
+
+Practical examples showing how to use the **Adaptive Memory Multi-Model Router** in real-world scenarios.
+
+## Prerequisites
+
+```bash
+npm install adaptive-memory-multi-model-router
+```
+
+Set at least one API key in your environment:
+
+```bash
+export OPENAI_API_KEY=sk-...
+export GROQ_API_KEY=gsk_...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GEMINI_API_KEY=...
+```
+
+## Examples
+
+| #  | File                     | Description                                                                 |
+|----|--------------------------|-----------------------------------------------------------------------------|
+| 1  | `basic-route.js`         | Route a query to the best provider. Shows the routing decision with model, cost, confidence, and reasoning. |
+| 2  | `ensemble.js`            | Query multiple providers in parallel and merge results. A3M's signature capability. |
+| 3  | `classify-then-route.js` | Classify a query's domain first (code, math, creative, etc.), then route to the optimal provider for that domain. |
+| 4  | `chat-loop.js`           | Interactive terminal chat loop with auto-routing, cost tracking, and guardrails. |
+| 5  | `cost-compare.js`        | Compare estimated costs across providers for the same prompt. Find the cheapest and fastest routes. |
+| 6  | `a3m-sdk.js`             | Use the TypeScript SDK class — `route()`, `analyze()`, `recommend()`, batch routing, and the proxy server. |
+
+## Running Examples
+
+```bash
+# Route a query (dry-run — no API call)
+node examples/basic-route.js
+
+# Ensemble across multiple providers
+node examples/ensemble.js
+
+# Classify then route
+node examples/classify-then-route.js
+
+# Interactive chat loop
+node examples/chat-loop.js
+
+# Cost comparison
+node examples/cost-compare.js
+
+# SDK showcase
+node examples/a3m-sdk.js
+```
+
+## What Makes A3M Unique
+
+- **Parallel ensemble voting** — query multiple LLMs and compare results (no other router does this)
+- **RouteLLM-style routing** — learned cost-quality tradeoff based on arXiv:2404.06035
+- **47+ providers** — free, cheap, mid, premium, enterprise tiers
+- **Semantic cache** — returns cached responses for semantically similar queries
+- **Budget enforcement** — hard caps per API key with monthly reset
+- **Guardrails** — prompt injection detection, PII redaction, content filtering
+- **LangChain adapter** — drop-in replacement for ChatOpenAI

package/examples/a3m-sdk.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * a3m-sdk.js — TypeScript SDK class showcase.
+ *
+ * The A3MRouter class provides a clean API: route() for model selection,
+ * analyze() for query features, recommend() for task-based suggestions,
+ * serve() for the OpenAI-compatible proxy server, and routeBatch().
+ *
+ * Usage:
+ *   node examples/a3m-sdk.js
+ */
+
+const { A3MRouter, createSDK } = require('../dist/sdk.js');
+
+function main() {
+  console.log('A3M Router — SDK Class Showcase');
+  console.log('=' .repeat(50));
+  console.log('');
+
+  // Create SDK instance
+  const router = createSDK({
+    defaultModel: 'auto',
+    maxCostPerQuery: 0.01,
+    preferSpeedOverQuality: false,
+  });
+
+  // 1. route() — get model selection for a query
+  console.log('-- route() — Model Selection --');
+  const result = router.route('Explain quantum entanglement simply');
+  console.log('  Query: Explain quantum entanglement simply');
+  console.log('  Model:     ', result.model);
+  console.log('  Tier:      ', result.tier);
+  console.log('  Cost:      $', result.cost.toFixed(6));
+  console.log('  Complexity:', result.complexity.toFixed(2));
+  console.log('  Reasoning: ', result.reasoning);
+  console.log('  Free:      ', result.isFree);
+  console.log('  Expert:    ', result.isExpert);
+  console.log('  Fallbacks: ', result.fallbackModels.join(', '));
+  console.log('');
+
+  // 2. analyze() — extract query features
+  console.log('-- analyze() — Query Features --');
+  const features = router.analyze('Write a Python script to merge two sorted arrays');
+  console.log('  Query: Write a Python script to merge two sorted arrays');
+  console.log('  Complexity:      ', features.complexity.toFixed(2));
+  console.log('  Has code:        ', features.has_code);
+  console.log('  Has math:        ', features.has_math);
+  console.log('  Multilingual:    ', features.is_multilingual);
+  console.log('  Creative:        ', features.is_creative);
+  console.log('  Reasoning:       ', features.requires_reasoning);
+  console.log('  Detected domain: ', features.detected_domain);
+  console.log('  Domain score:    ', features.domain_score.toFixed(2));
+  console.log('');
+
+  // 3. recommend() — model recommendation for a task
+  console.log('-- recommend() — Task-Based Recommendations --');
+  const tasks = [
+    'code generation',
+    'summarization',
+    'creative writing',
+    'data analysis',
+    'translation',
+  ];
+
+  for (const task of tasks) {
+    const rec = router.recommend(task);
+    console.log(`  ${task.padEnd(20)} -> ${rec.model.padEnd(36)} tier=${rec.tier}  cost=$${rec.cost.toFixed(6)}`);
+  }
+  console.log('');
+
+  // 4. routeBatch() — multiple queries at once
+  console.log('-- routeBatch() — Batch Routing --');
+  const queries = [
+    'What is 2+2?',
+    'Explain the water cycle',
+    'Write a SQL query to find duplicate emails',
+    'Translate "Hello" to French',
+    'Summarize the theory of relativity',
+  ];
+
+  const batchResults = router.routeBatch(queries);
+  for (let i = 0; i < queries.length; i++) {
+    console.log(`  [${i + 1}] ${queries[i].substring(0, 40).padEnd(42)} -> ${batchResults[i].model.substring(0, 36).padEnd(38)} tier=${batchResults[i].tier.padEnd(7)} comp=${batchResults[i].complexity.toFixed(2)}`);
+  }
+  console.log('');
+
+  // 5. Different complexity classes
+  console.log('-- Complexity Classification --');
+  const testQueries = [
+    ['Simple',    'Hello, how are you?'],
+    ['Moderate',  'Explain what a database is'],
+    ['Complex',   'Compare gradient descent vs stochastic gradient descent'],
+    ['Expert',    'Prove the Riemann-Roch theorem and explain its implications'],
+  ];
+
+  for (const [label, q] of testQueries) {
+    const r = router.route(q);
+    console.log(`  ${label.padEnd(10)} comp=${r.complexity.toFixed(2)}  tier=${r.tier.padEnd(7)}  model=${r.model}`);
+  }
+  console.log('');
+
+  // 6. Proxy server (dry-run — uncomment to start)
+  console.log('-- serve() — Proxy Server --');
+  console.log('  To start the OpenAI-compatible proxy server, uncomment:');
+  console.log('  const url = await router.serve(8787);');
+  console.log('  // Use any OpenAI SDK with baseURL = url');
+  console.log('  const client = new OpenAI({ baseURL: url });');
+  console.log('  const response = await client.chat.completions.create({');
+  console.log('    model: "auto",');
+  console.log('    messages: [{ role: "user", content: "Hello" }]');
+  console.log('  });');
+  console.log('');
+
+  // 7. Config options
+  console.log('-- SDK Configuration --');
+  const cheapRouter = createSDK({ preferSpeedOverQuality: true, maxCostPerQuery: 0.001 });
+  const r1 = cheapRouter.route('What is the meaning of life?');
+  console.log('  Speed-preferring config (maxCost=$0.001):');
+  console.log('  Model: ', r1.model);
+  console.log('  Cost:  $', r1.cost.toFixed(6));
+  console.log('  Tier:  ', r1.tier);
+}
+
+main();

package/examples/basic-route.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * basic-route.js — Route a query to the best provider.
+ *
+ * A3M Router analyzes the query and returns a RouteDecision:
+ * which model to use, estimated cost, confidence, and reasoning.
+ * This is a dry-run — no API call is made.
+ *
+ * Usage:
+ *   node examples/basic-route.js
+ *   QUERY="Explain quantum computing" node examples/basic-route.js
+ */
+
+const { routeQuery, extractQueryFeatures } = require('../dist/index.js');
+
+const query = process.env.QUERY || 'Explain machine learning simply in 3 sentences';
+
+function main() {
+  console.log('Query:', query);
+  console.log('');
+
+  // 1. Extract query features for insight
+  const features = extractQueryFeatures(query);
+  console.log('-- Query Features --');
+  console.log('  Complexity:      ', features.complexity.toFixed(2));
+  console.log('  Has code:        ', features.has_code);
+  console.log('  Has math:        ', features.has_math);
+  console.log('  Requires reason: ', features.requires_reasoning);
+  console.log('  Is creative:     ', features.is_creative);
+  console.log('');
+
+  // 2. Route the query (no API call — pure routing decision)
+  const decision = routeQuery(query);
+
+  console.log('-- Route Decision --');
+  console.log('  Model:            ', decision.primary_model);
+  console.log('  Fallback models:  ', decision.fallback_models.join(', '));
+  console.log('  Confidence:       ', (decision.confidence * 100).toFixed(1) + '%');
+  console.log('  Est. cost:        ', '$' + decision.estimated_cost.toFixed(6));
+  console.log('  Est. latency:     ', decision.estimated_latency_ms + 'ms');
+  console.log('  Reasoning:        ', decision.reasoning);
+  console.log('');
+
+  // 3. Route with a budget multiplier (1.0 = balanced, <1 = cost-focused, >1 = quality-focused)
+  const cheap = routeQuery(query, undefined, 0.3);
+  const premium = routeQuery(query, undefined, 2.0);
+
+  console.log('-- Budget Tuning --');
+  console.log('  Cost-focused (0.3):  ', cheap.primary_model, '($' + cheap.estimated_cost.toFixed(6) + ')');
+  console.log('  Balanced (1.0):     ', decision.primary_model, '($' + decision.estimated_cost.toFixed(6) + ')');
+  console.log('  Quality (2.0):      ', premium.primary_model, '($' + premium.estimated_cost.toFixed(6) + ')');
+}
+
+main();

package/examples/chat-loop.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * chat-loop.js — Interactive terminal chat loop with auto-routing,
+ * cost tracking, and guardrails.
+ *
+ * A full-featured REPL that routes each message through A3M,
+ * tracks cumulative cost, and checks input/output safety.
+ *
+ * Usage:
+ *   node examples/chat-loop.js
+ *
+ * Commands in chat:
+ *   /cost     — Show current session cost
+ *   /route    — Show the route decision for the last query
+ *   /providers — List available providers
+ *   /clear    — Reset conversation and cost
+ *   /help     — Show commands
+ *   /quit     — Exit
+ */
+
+const readline = require('readline');
+const {
+  routeQuery,
+  extractQueryFeatures,
+  CostTracker,
+  GuardrailEngine,
+  getAvailableProviders,
+  findCheapestAvailableProvider,
+  findFastestAvailableProvider,
+} = require('../dist/index.js');
+
+class ChatLoop {
+  constructor() {
+    this.costTracker = new CostTracker({ daily_limit: 1.0 }); // $1/day soft limit
+    this.guardrails = new GuardrailEngine({
+      promptInjection: true,
+      piiDetection: true,
+      contentFilter: true,
+      maxLength: 4000,
+      languageDetection: false,
+      outputFilter: false,
+      outputPII: false,
+      hallucinationCheck: false,
+    });
+    this.history = [];
+    this.lastDecision = null;
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: '\x1b[36mA3M> \x1b[0m',
+    });
+  }
+
+  start() {
+    console.log('');
+    console.log('  A3M Router — Interactive Chat');
+    console.log('  ' + '-'.repeat(36));
+    console.log('  Type a message to route it through A3M.');
+    console.log('  Type /help for commands.');
+    console.log('');
+
+    this.rl.prompt();
+
+    this.rl.on('line', async (line) => {
+      const input = line.trim();
+      if (!input) { this.rl.prompt(); return; }
+
+      if (input.startsWith('/')) {
+        await this.handleCommand(input);
+      } else {
+        await this.handleMessage(input);
+      }
+
+      this.rl.prompt();
+    });
+
+    this.rl.on('close', () => {
+      console.log('\nGoodbye!');
+      this.printCostSummary();
+      process.exit(0);
+    });
+  }
+
+  async handleCommand(cmd) {
+    switch (cmd) {
+      case '/cost':
+        this.printCostSummary();
+        break;
+
+      case '/route':
+        if (this.lastDecision) {
+          console.log('  Last route decision:');
+          console.log('    Model:      ', this.lastDecision.primary_model);
+          console.log('    Confidence: ', (this.lastDecision.confidence * 100).toFixed(1) + '%');
+          console.log('    Cost:       $', this.lastDecision.estimated_cost.toFixed(6));
+          console.log('    Reasoning:  ', this.lastDecision.reasoning);
+        } else {
+          console.log('  No messages routed yet.');
+        }
+        break;
+
+      case '/providers':
+        const providers = getAvailableProviders();
+        const entries = Object.entries(providers);
+        console.log('  Available providers (' + entries.length + '):');
+        for (const [id, p] of entries.slice(0, 10)) {
+          const cheap = findCheapestAvailableProvider(id);
+          const fast = findFastestAvailableProvider();
+          console.log(`    ${id.padEnd(16)} tier=${p.tier.padEnd(10)} models=${p.models.length}`);
+        }
+        if (entries.length > 10) {
+          console.log(`    ... and ${entries.length - 10} more`);
+        }
+        break;
+
+      case '/clear':
+        this.history = [];
+        this.costTracker.reset();
+        this.lastDecision = null;
+        console.log('  Session cleared.');
+        break;
+
+      case '/help':
+        console.log('  Commands:');
+        console.log('    /cost       — Show session cost');
+        console.log('    /route      — Show last route decision');
+        console.log('    /providers  — List available providers');
+        console.log('    /clear      — Reset conversation');
+        console.log('    /help       — This message');
+        console.log('    /quit       — Exit');
+        break;
+
+      case '/quit':
+        this.rl.close();
+        break;
+
+      default:
+        console.log('  Unknown command. Type /help.');
+    }
+  }
+
+  async handleMessage(text) {
+    // 1. Guardrails — check input safety
+    const inputCheck = await this.guardrails.checkInput(text);
+    if (inputCheck.blocked) {
+      console.log(`  \x1b[31m[BLOCKED]\x1b[0m ${inputCheck.reason || 'Input rejected by guardrails'}`);
+      return;
+    }
+
+    const safeText = inputCheck.modified || text;
+
+    // 2. Extract features
+    const features = extractQueryFeatures(safeText);
+    const complexityLabel = features.complexity < 0.2 ? 'simple' :
+                            features.complexity < 0.45 ? 'moderate' :
+                            features.complexity < 0.65 ? 'complex' : 'expert';
+
+    // 3. Route the query
+    this.lastDecision = routeQuery(safeText);
+
+    console.log(`  [${complexityLabel}] -> ${this.lastDecision.primary_model} (${(this.lastDecision.confidence * 100).toFixed(0)}% conf, $${this.lastDecision.estimated_cost.toFixed(6)})`);
+
+    // 4. Record cost
+    this.costTracker.record(
+      this.lastDecision.primary_model.split('/')[0] || 'unknown',
+      this.lastDecision.primary_model,
+      Math.ceil(safeText.length / 4),
+      100 // estimated output tokens
+    );
+
+    // 5. Track history
+    this.history.push({ role: 'user', content: safeText });
+
+    // 6. Check budget
+    const summary = this.costTracker.getSummary();
+    const remaining = this.costTracker.getRemainingBudget();
+    if (remaining.daily !== null && remaining.daily < 0.05) {
+      console.log(`  \x1b[33m[WARN]\x1b[0m Daily budget nearly exhausted: $${remaining.daily.toFixed(4)} remaining`);
+    }
+  }
+
+  printCostSummary() {
+    const summary = this.costTracker.getSummary();
+    const remaining = this.costTracker.getRemainingBudget();
+    console.log('  -- Cost Summary --');
+    console.log('  Total spent:     $' + summary.total_cost.toFixed(6));
+    console.log('  Requests:        ', summary.request_count);
+    console.log('  Avg/request:     $' + summary.average_cost_per_request.toFixed(6));
+    console.log('  Daily remaining: $' + (remaining.daily !== null ? remaining.daily.toFixed(6) : 'unlimited'));
+    console.log('  Monthly remain:  $' + (remaining.monthly !== null ? remaining.monthly.toFixed(6) : 'unlimited'));
+    if (Object.keys(summary.by_provider).length > 0) {
+      console.log('  By provider:');
+      for (const [prov, cost] of Object.entries(summary.by_provider)) {
+        console.log(`    ${prov}: $${cost.toFixed(6)}`);
+      }
+    }
+  }
+}
+
+// Start the chat loop
+const chat = new ChatLoop();
+chat.start();

package/examples/classify-then-route.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * classify-then-route.js — Classify a query's domain first, then route to optimal provider.
+ *
+ * A3M Router's extractQueryFeatures() analyzes the query for code, math,
+ * creativity, reasoning needs, and more. Use this to make smarter routing
+ * decisions or to surface domain info to the user.
+ *
+ * Usage:
+ *   node examples/classify-then-route.js
+ *   QUERY="Write a Python function to sort a list" node examples/classify-then-route.js
+ */
+
+const { routeQuery, extractQueryFeatures, MODEL_PROFILES, getAvailableProviders } = require('../dist/index.js');
+
+const query = process.env.QUERY || 'Write a poem about artificial intelligence in the style of Shakespeare';
+
+function classifyAndRoute(query) {
+  // 1. Extract features
+  const features = extractQueryFeatures(query);
+
+  // 2. Determine domain
+  const domain = features.has_code ? 'code' :
+                 features.has_math ? 'math' :
+                 features.is_creative ? 'creative' :
+                 features.requires_reasoning ? 'reasoning' :
+                 'general';
+
+  // 3. Find the best model for this domain using MODEL_PROFILES
+  const profiles = Object.entries(MODEL_PROFILES)
+    .filter(([_, p]) => p.strengths?.length > 0)
+    .map(([name, p]) => ({
+      name,
+      provider: p.provider,
+      cost: p.cost_per_1k_input + p.cost_per_1k_output,
+      quality: p.quality_score,
+      strengths: p.strengths,
+      domainMatch: p.strengths.some(s => s.toLowerCase().includes(domain)),
+    }))
+    .sort((a, b) => {
+      // Prefer domain-matched, then higher quality, then lower cost
+      if (a.domainMatch !== b.domainMatch) return a.domainMatch ? -1 : 1;
+      if (a.quality !== b.quality) return b.quality - a.quality;
+      return a.cost - b.cost;
+    });
+
+  // 4. Get A3M's route decision
+  const decision = routeQuery(query);
+
+  return { features, domain, bestProfiles: profiles.slice(0, 5), decision };
+}
+
+function printResult(result) {
+  console.log('Query:', query);
+  console.log('');
+
+  console.log('-- Classification --');
+  console.log('  Domain:           ', result.domain);
+  console.log('  Complexity:       ', result.features.complexity.toFixed(2));
+  console.log('  Has code:         ', result.features.has_code);
+  console.log('  Has math:         ', result.features.has_math);
+  console.log('  Creative:         ', result.features.is_creative);
+  console.log('  Needs reasoning:  ', result.features.requires_reasoning);
+  console.log('  Multilingual:     ', result.features.is_multilingual);
+  console.log('');
+
+  console.log('-- Top Domain-Matched Models --');
+  for (const p of result.bestProfiles) {
+    const matchStar = p.domainMatch ? ' *' : '  ';
+    console.log(`  ${matchStar} ${p.name.padEnd(36)} quality=${p.quality.toFixed(2)}  cost=$${p.cost.toFixed(6)}  [${p.strengths.slice(0, 3).join(', ')}]`);
+  }
+  console.log('');
+
+  console.log('-- A3M Route Decision --');
+  console.log('  Selected model:   ', result.decision.primary_model);
+  console.log('  Confidence:       ', (result.decision.confidence * 100).toFixed(1) + '%');
+  console.log('  Est. cost:        ', '$' + result.decision.estimated_cost.toFixed(6));
+  console.log('  Reasoning:        ', result.decision.reasoning);
+}
+
+function main() {
+  const result = classifyAndRoute(query);
+  printResult(result);
+
+  // Demo: show how routing differs per domain
+  console.log('');
+  console.log('-- Domain Routing Comparison --');
+  const testQueries = [
+    ['code',      'Write a binary search tree in Python'],
+    ['math',      'Solve for x: 3x^2 + 5x - 2 = 0'],
+    ['creative',  'Write a haiku about the ocean'],
+    ['reasoning', 'If all A are B and some B are C, can we conclude some A are C?'],
+    ['general',   'What is the weather like today?'],
+  ];
+
+  for (const [domain, q] of testQueries) {
+    const r = classifyAndRoute(q);
+    console.log(`  ${domain.padEnd(12)} -> ${r.decision.primary_model.padEnd(36)} cost=$${r.decision.estimated_cost.toFixed(6)}  conf=${(r.decision.confidence * 100).toFixed(0)}%`);
+  }
+}
+
+main();

package/examples/cost-compare.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * cost-compare.js — Compare costs across providers for the same prompt.
+ *
+ * A3M Router provides MODEL_PROFILES with cost-per-token data for every model.
+ * Use CostTracker to estimate real costs, and findCheapestAvailableProvider /
+ * findFastestAvailableProvider to make data-driven decisions.
+ *
+ * Usage:
+ *   node examples/cost-compare.js
+ *   INPUT_TOKENS=500 OUTPUT_TOKENS=200 node examples/cost-compare.js
+ */
+
+const {
+  routeQuery,
+  CostTracker,
+  MODEL_PROFILES,
+  findCheapestAvailableProvider,
+  findFastestAvailableProvider,
+  MODEL_COSTS,
+  countTokens,
+  extractQueryFeatures,
+} = require('../dist/index.js');
+
+const INPUT_TOKENS = parseInt(process.env.INPUT_TOKENS || '150', 10);
+const OUTPUT_TOKENS = parseInt(process.env.OUTPUT_TOKENS || '100', 10);
+
+function main() {
+  console.log('A3M Router — Cost Comparison');
+  console.log('=' .repeat(50));
+  console.log('Input tokens: ', INPUT_TOKENS);
+  console.log('Output tokens:', OUTPUT_TOKENS);
+  console.log('');
+
+  // 1. Find cheapest and fastest available providers
+  const cheapest = findCheapestAvailableProvider();
+  const fastest = findFastestAvailableProvider();
+
+  console.log('-- Provider Recommendations --');
+  if (cheapest) {
+    const cost = new CostTracker().calculateCost(cheapest.models[0] || 'unknown', INPUT_TOKENS, OUTPUT_TOKENS);
+    console.log(`  Cheapest:  ${cheapest.id.padEnd(16)} ${cheapest.models[0] || 'N/A'.padEnd(30)} $${cost.total.toFixed(6)}/req  (tier: ${cheapest.tier})`);
+  }
+  if (fastest) {
+    const cost = new CostTracker().calculateCost(fastest.models[0] || 'unknown', INPUT_TOKENS, OUTPUT_TOKENS);
+    console.log(`  Fastest:   ${fastest.id.padEnd(16)} ${fastest.models[0] || 'N/A'.padEnd(30)} $${cost.total.toFixed(6)}/req  (tier: ${fastest.tier})`);
+  }
+  console.log('');
+
+  // 2. Compare costs across all major model profiles
+  console.log('-- All Model Profiles --');
+  console.log('  Model'.padEnd(38) + 'Provider'.padEnd(14) + 'Input/1K'.padEnd(12) + 'Output/1K'.padEnd(12) + 'Est. Cost'.padEnd(12) + 'Quality');
+  console.log('  ' + '-'.repeat(90));
+
+  const profiles = Object.entries(MODEL_PROFILES)
+    .map(([name, p]) => ({
+      name,
+      provider: p.provider,
+      cost_input: p.cost_per_1k_input,
+      cost_output: p.cost_per_1k_output,
+      estimated: (p.cost_per_1k_input * INPUT_TOKENS / 1000) + (p.cost_per_1k_output * OUTPUT_TOKENS / 1000),
+      quality: p.quality_score,
+      latency: p.latency_ms,
+      context: p.context_window,
+    }))
+    .sort((a, b) => a.estimated - b.estimated);
+
+  for (const p of profiles) {
+    console.log(`  ${p.name.padEnd(36)} ${p.provider.padEnd(12)} $${p.cost_input.toFixed(6).padEnd(8)} $${p.cost_output.toFixed(6).padEnd(8)} $${p.estimated.toFixed(6).padEnd(8)} ${p.quality.toFixed(2)}`);
+  }
+  console.log('');
+
+  // 3. Compare A3M routing at different budget multipliers
+  console.log('-- A3M Routing Cost Comparison --');
+  const testQuery = process.env.QUERY || 'Write a short story about a robot learning to paint';
+  const features = extractQueryFeatures(testQuery);
+  console.log('  Query:', testQuery);
+  console.log('  Complexity:', features.complexity.toFixed(2));
+  console.log('');
+
+  const budgets = [
+    { label: 'Cost-Focused',  multiplier: 0.2 },
+    { label: 'Budget',        multiplier: 0.5 },
+    { label: 'Balanced',      multiplier: 1.0 },
+    { label: 'Quality',       multiplier: 1.5 },
+    { label: 'Max Quality',   multiplier: 2.0 },
+  ];
+
+  console.log('  ' + 'Strategy'.padEnd(16) + 'Model'.padEnd(36) + 'Cost'.padEnd(14) + 'Latency'.padEnd(12) + 'Confidence');
+  console.log('  ' + '-'.repeat(80));
+
+  for (const b of budgets) {
+    const decision = routeQuery(testQuery, undefined, b.multiplier);
+    console.log(`  ${b.label.padEnd(14)} ${decision.primary_model.padEnd(34)} $${decision.estimated_cost.toFixed(6).padEnd(10)} ${decision.estimated_latency_ms}ms  ${(decision.confidence * 100).toFixed(0)}%`);
+  }
+
+  // 4. CostTracker usage example
+  console.log('');
+  console.log('-- CostTracker Session Example --');
+  const tracker = new CostTracker({ daily_limit: 5.0 });
+
+  // Simulate 3 requests
+  tracker.record('openai', 'gpt-4o-mini', 150, 100);
+  tracker.record('groq', 'llama-3.3-70b-versatile', 200, 150);
+  tracker.record('anthropic', 'claude-3-5-sonnet-latest', 180, 120);
+
+  const summary = tracker.getSummary();
+  console.log('  Requests tracked:    ', summary.request_count);
+  console.log('  Total cost:          $' + summary.total_cost.toFixed(6));
+  console.log('  Avg cost/request:    $' + summary.average_cost_per_request.toFixed(6));
+  console.log('  Total tokens:        ', summary.token_count.input + summary.token_count.output);
+  console.log('  Daily remaining:     $' + (tracker.getRemainingBudget().daily !== null ? tracker.getRemainingBudget().daily.toFixed(6) : 'unlimited'));
+  console.log('');
+  console.log('  By provider:');
+  for (const [prov, cost] of Object.entries(summary.by_provider)) {
+    console.log(`    ${prov}: $${cost.toFixed(6)}`);
+  }
+}
+
+main();