voyageai-cli 1.20.4 → 1.20.6

package/README.md

@@ -12,6 +12,28 @@ The fastest path from documents to semantic search. Chunk files, generate [Voyag
 
 ---
 
+## Why Voyage AI?
+
+Voyage AI provides **state-of-the-art embedding models** with the best quality-to-cost ratio in the industry. Here's why developers choose Voyage AI:
+
+| Advantage | What It Means |
+|-----------|---------------|
+| **🎯 #1 on MTEB** | Voyage-3 ranks first on retrieval benchmarks, outperforming OpenAI, Cohere, and other providers |
+| **💰 Up to 83% Cost Savings** | Asymmetric retrieval: embed docs with `voyage-3-lite`, query with `voyage-3-large` — same quality, fraction of the cost |
+| **🔗 Shared Embedding Space** | All Voyage-3 models produce compatible embeddings — mix and match for optimal cost-quality tradeoffs |
+| **🏢 Domain-Specific Models** | Specialized models for code, finance, law, and multilingual content that beat general-purpose alternatives |
+| **⚡ Two-Stage Retrieval** | Rerank-2 boosts search precision by re-scoring candidates with a powerful cross-encoder |
+
+**Get started:**
+```bash
+# Get a free API key at https://dash.voyageai.com
+vai quickstart    # Interactive tutorial — zero to semantic search in 2 minutes
+```
+
+**Learn more:** [Voyage AI Docs](https://docs.voyageai.com) · [Pricing](https://voyageai.com/pricing) · [Blog](https://blog.voyageai.com)
+
+---
+
 ## Three Ways to Use It
 
 <table>
@@ -44,6 +66,7 @@ MongoDB LeafyGreen design system<br/><br/>
 
 ## Table of Contents
 
+- [Why Voyage AI?](#why-voyage-ai)
 - [Desktop App](#desktop-app)
 - [Web Playground](#web-playground)
 - [CLI — Quick Start](#cli--quick-start)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.20.4",
+  "version": "1.20.6",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"

package/src/cli.js

@@ -28,6 +28,8 @@ const { registerPipeline } = require('./commands/pipeline');
 const { registerEval } = require('./commands/eval');
 const { registerApp } = require('./commands/app');
 const { registerAbout } = require('./commands/about');
+const { register: registerDoctor } = require('./commands/doctor');
+const { register: registerQuickstart } = require('./commands/quickstart');
 const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
 
 const version = getVersion();
@@ -60,6 +62,8 @@ registerPipeline(program);
 registerEval(program);
 registerApp(program);
 registerAbout(program);
+registerDoctor(program);
+registerQuickstart(program);
 
 // Append disclaimer to all help output
 program.addHelpText('after', `

package/src/commands/about.js

@@ -20,6 +20,7 @@ function registerAbout(program) {
             name: 'Michael Lynn',
             role: 'Principal Staff Developer Advocate, MongoDB',
             github: 'https://github.com/mrlynn',
+            vai_website: 'https://vai.mlynn.org',
             website: 'https://mlynn.org',
           },
           links: {
@@ -52,23 +53,58 @@ function registerAbout(program) {
       console.log(`  into their applications — right from the terminal.`);
       console.log('');
 
+      // Why Voyage AI?
+      console.log(`  ${pc.bold(pc.green('Why Voyage AI?'))}`);
+      console.log(`  Voyage AI provides state-of-the-art embedding models with`);
+      console.log(`  the best quality-to-cost ratio in the industry.`);
+      console.log('');
+      console.log(`  ${pc.cyan('🎯 SOTA Quality')}`);
+      console.log(`     Voyage-3 ranks #1 on MTEB retrieval benchmarks, outperforming`);
+      console.log(`     OpenAI, Cohere, and other providers on real-world tasks.`);
+      console.log('');
+      console.log(`  ${pc.cyan('💰 Best Value')}`);
+      console.log(`     Up to 83% cost reduction with asymmetric retrieval: embed`);
+      console.log(`     documents with voyage-3-lite, query with voyage-3-large.`);
+      console.log('');
+      console.log(`  ${pc.cyan('🔗 Shared Embedding Space')}`);
+      console.log(`     All Voyage-3 models share the same embedding space — mix`);
+      console.log(`     and match models for optimal cost-quality tradeoffs.`);
+      console.log('');
+      console.log(`  ${pc.cyan('🏢 Domain-Specific Models')}`);
+      console.log(`     Specialized models for code, finance, law, and multilingual`);
+      console.log(`     content that outperform general-purpose alternatives.`);
+      console.log('');
+      console.log(`  ${pc.cyan('⚡ Reranking')}`);
+      console.log(`     Two-stage retrieval with rerank-2 boosts precision by`);
+      console.log(`     re-scoring candidates with a powerful cross-encoder.`);
+      console.log('');
+
       // Features
       console.log(`  ${pc.bold('What You Can Do')}`);
+      console.log(`  ${pc.cyan('vai quickstart')}   Zero-to-search tutorial (start here!)`);
       console.log(`  ${pc.cyan('vai embed')}        Generate vector embeddings for text`);
       console.log(`  ${pc.cyan('vai similarity')}   Compare texts with cosine similarity`);
       console.log(`  ${pc.cyan('vai rerank')}       Rerank documents against a query`);
       console.log(`  ${pc.cyan('vai search')}       Vector search against Atlas collections`);
       console.log(`  ${pc.cyan('vai store')}        Embed and store documents in Atlas`);
       console.log(`  ${pc.cyan('vai benchmark')}    Compare model latency, ranking & costs`);
+      console.log(`  ${pc.cyan('vai doctor')}       Health-check your setup`);
       console.log(`  ${pc.cyan('vai explain')}      Learn about embeddings, vector search & more`);
       console.log(`  ${pc.cyan('vai playground')}   Launch interactive web playground`);
       console.log('');
 
-      // Links
-      console.log(`  ${pc.bold('Links')}`);
+      // Voyage AI Links
+      console.log(`  ${pc.bold('Voyage AI Resources')}`);
+      console.log(`  ${pc.dim('Docs:')}      https://docs.voyageai.com`);
+      console.log(`  ${pc.dim('Dashboard:')} https://dash.voyageai.com`);
+      console.log(`  ${pc.dim('Pricing:')}   https://voyageai.com/pricing`);
+      console.log(`  ${pc.dim('Blog:')}      https://blog.voyageai.com`);
+      console.log('');
+
+      // Tool Links
+      console.log(`  ${pc.bold('This Tool')}`);
       console.log(`  ${pc.dim('npm:')}     https://www.npmjs.com/package/voyageai-cli`);
       console.log(`  ${pc.dim('GitHub:')}  https://github.com/mrlynn/voyageai-cli`);
-      console.log(`  ${pc.dim('Docs:')}    https://www.mongodb.com/docs/voyageai/`);
       console.log(`  ${pc.dim('Author:')}  https://mlynn.org`);
       console.log('');
 

package/src/commands/doctor.js

@@ -0,0 +1,325 @@
+'use strict';
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const pc = require('picocolors');
+const { getConfigValue } = require('../lib/config');
+const { getApiBase } = require('../lib/api');
+
+/**
+ * vai doctor — Health check command
+ * Validates the entire setup chain: Node version, API key, MongoDB connectivity,
+ * peer dependencies, and configuration.
+ */
+
+const CHECKS = {
+  node: { name: 'Node.js Version', required: true },
+  apiKey: { name: 'Voyage AI API Key', required: true },
+  apiConnection: { name: 'Voyage AI API Connection', required: true },
+  mongodb: { name: 'MongoDB Connection', required: false },
+  pdfParse: { name: 'PDF Support (pdf-parse)', required: false },
+  config: { name: 'Configuration Files', required: false },
+};
+
+function checkMark(ok) {
+  return ok ? pc.green('✓') : pc.red('✗');
+}
+
+function warnMark() {
+  return pc.yellow('⚠');
+}
+
+async function checkNodeVersion() {
+  const version = process.version;
+  const major = parseInt(version.slice(1).split('.')[0], 10);
+  const minVersion = 18;
+  const ok = major >= minVersion;
+  
+  return {
+    ok,
+    message: ok 
+      ? `${version} (meets minimum v${minVersion})`
+      : `${version} — ${pc.red(`requires v${minVersion}+`)}`,
+    hint: ok ? null : 'Upgrade Node.js: https://nodejs.org/',
+  };
+}
+
+async function checkApiKey() {
+  const key = process.env.VOYAGE_API_KEY || getConfigValue('apiKey');
+  const masked = key ? `${key.slice(0, 8)}...${key.slice(-4)}` : null;
+  
+  if (!key) {
+    return {
+      ok: false,
+      message: 'Not configured',
+      hint: 'Set via: vai config set api-key YOUR_KEY\n         or: export VOYAGE_API_KEY=YOUR_KEY\n         Get a key: https://dash.voyageai.com/api-keys',
+    };
+  }
+  
+  // Check key format (Voyage keys typically start with pa- or similar)
+  const validFormat = key.length > 20;
+  
+  return {
+    ok: true,
+    message: masked,
+    hint: validFormat ? null : 'Key format looks unusual — verify at dash.voyageai.com',
+  };
+}
+
+async function checkApiConnection() {
+  const key = process.env.VOYAGE_API_KEY || getConfigValue('apiKey');
+  if (!key) {
+    return {
+      ok: false,
+      message: 'Skipped (no API key)',
+      hint: null,
+    };
+  }
+
+  const baseUrl = getApiBase();
+  
+  try {
+    const https = require('https');
+    const url = require('url');
+    
+    const parsed = new URL(`${baseUrl}/embeddings`);
+    
+    const result = await new Promise((resolve, reject) => {
+      const req = https.request({
+        hostname: parsed.hostname,
+        port: parsed.port || 443,
+        path: parsed.pathname,
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${key}`,
+          'Content-Type': 'application/json',
+        },
+        timeout: 10000,
+      }, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          // 200 = success, 400 = bad request (but server reachable), 401 = bad key
+          if (res.statusCode === 401) {
+            resolve({ ok: false, status: 401, message: 'Invalid API key' });
+          } else if (res.statusCode === 400) {
+            // Bad request means server is reachable, key is valid
+            resolve({ ok: true, status: 400, message: 'Connected' });
+          } else if (res.statusCode === 200) {
+            resolve({ ok: true, status: 200, message: 'Connected' });
+          } else {
+            resolve({ ok: false, status: res.statusCode, message: `HTTP ${res.statusCode}` });
+          }
+        });
+      });
+      
+      req.on('error', (err) => reject(err));
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error('Connection timeout'));
+      });
+      
+      // Send minimal request body
+      req.write(JSON.stringify({ model: 'voyage-3-lite', input: ['test'] }));
+      req.end();
+    });
+    
+    return {
+      ok: result.ok,
+      message: result.ok ? `${result.message} (${baseUrl})` : result.message,
+      hint: result.ok ? null : 
+        result.status === 401 ? 'API key is invalid — get a new one at dash.voyageai.com' :
+        'Check your network connection and API base URL',
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      message: `Connection failed: ${err.message}`,
+      hint: 'Check your network connection or firewall settings',
+    };
+  }
+}
+
+async function checkMongoDB() {
+  const uri = process.env.MONGODB_URI || getConfigValue('mongoUri');
+  
+  if (!uri) {
+    return {
+      ok: null, // null = not configured (optional)
+      message: 'Not configured (optional)',
+      hint: 'Set via: vai config set mongo-uri YOUR_URI\n         Required for vai store, vai search, vai query',
+    };
+  }
+
+  try {
+    const { MongoClient } = require('mongodb');
+    const client = new MongoClient(uri, {
+      serverSelectionTimeoutMS: 5000,
+      connectTimeoutMS: 5000,
+    });
+    
+    await client.connect();
+    await client.db().command({ ping: 1 });
+    await client.close();
+    
+    // Mask the URI
+    const masked = uri.replace(/:\/\/[^@]+@/, '://***@').replace(/\?.*$/, '');
+    
+    return {
+      ok: true,
+      message: `Connected (${masked})`,
+      hint: null,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      message: `Connection failed: ${err.message}`,
+      hint: 'Verify your connection string and network access',
+    };
+  }
+}
+
+async function checkPdfParse() {
+  try {
+    require.resolve('pdf-parse');
+    return {
+      ok: true,
+      message: 'Installed',
+      hint: null,
+    };
+  } catch {
+    return {
+      ok: null, // null = not installed (optional)
+      message: 'Not installed (optional)',
+      hint: 'Install for PDF support: npm install pdf-parse',
+    };
+  }
+}
+
+async function checkConfig() {
+  const homeConfig = path.join(os.homedir(), '.vai', 'config.json');
+  const projectConfig = path.join(process.cwd(), '.vai.json');
+  
+  const results = [];
+  
+  // Check home config
+  if (fs.existsSync(homeConfig)) {
+    try {
+      const stat = fs.statSync(homeConfig);
+      const mode = (stat.mode & 0o777).toString(8);
+      const secure = mode === '600';
+      results.push(`~/.vai/config.json: ${secure ? 'OK' : pc.yellow(`permissions ${mode} (should be 600)`)}`);
+    } catch {
+      results.push('~/.vai/config.json: exists');
+    }
+  }
+  
+  // Check project config
+  if (fs.existsSync(projectConfig)) {
+    try {
+      JSON.parse(fs.readFileSync(projectConfig, 'utf8'));
+      results.push('.vai.json: OK');
+    } catch {
+      results.push(`.vai.json: ${pc.red('invalid JSON')}`);
+    }
+  }
+  
+  if (results.length === 0) {
+    return {
+      ok: null,
+      message: 'No config files found',
+      hint: 'Run: vai init (for project config) or vai config set (for user config)',
+    };
+  }
+  
+  return {
+    ok: true,
+    message: results.join(', '),
+    hint: null,
+  };
+}
+
+async function runDoctor(options = {}) {
+  const { json, verbose } = options;
+  
+  console.log(pc.bold('\n🩺 Voyage AI CLI Health Check\n'));
+  
+  const results = {};
+  let hasError = false;
+  let hasWarning = false;
+  
+  // Run all checks
+  const checks = [
+    { key: 'node', fn: checkNodeVersion },
+    { key: 'apiKey', fn: checkApiKey },
+    { key: 'apiConnection', fn: checkApiConnection },
+    { key: 'mongodb', fn: checkMongoDB },
+    { key: 'pdfParse', fn: checkPdfParse },
+    { key: 'config', fn: checkConfig },
+  ];
+  
+  for (const { key, fn } of checks) {
+    const check = CHECKS[key];
+    const result = await fn();
+    results[key] = result;
+    
+    // Determine status icon
+    let icon;
+    if (result.ok === true) {
+      icon = checkMark(true);
+    } else if (result.ok === false) {
+      icon = checkMark(false);
+      if (check.required) hasError = true;
+      else hasWarning = true;
+    } else {
+      icon = warnMark();
+      hasWarning = true;
+    }
+    
+    // Print result
+    console.log(`  ${icon} ${pc.bold(check.name)}: ${result.message}`);
+    
+    if (result.hint && (verbose || result.ok === false)) {
+      console.log(`      ${pc.dim(result.hint)}`);
+    }
+  }
+  
+  // Summary
+  console.log('');
+  if (hasError) {
+    console.log(pc.red('  ✗ Some required checks failed. Fix the issues above to use vai.\n'));
+  } else if (hasWarning) {
+    console.log(pc.yellow('  ⚠ Some optional features are not configured.\n'));
+  } else {
+    console.log(pc.green('  ✓ All checks passed. vai is ready to use!\n'));
+  }
+  
+  // Suggest next steps
+  if (!hasError) {
+    console.log(pc.dim('  Next steps:'));
+    console.log(pc.dim('    vai demo        — Interactive walkthrough'));
+    console.log(pc.dim('    vai quickstart  — Zero-to-search tutorial'));
+    console.log(pc.dim('    vai explain     — Learn key concepts\n'));
+  }
+  
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+  }
+  
+  return hasError ? 1 : 0;
+}
+
+function register(program) {
+  program
+    .command('doctor')
+    .description('Run health checks on your vai setup')
+    .option('--json', 'Output results as JSON')
+    .option('-v, --verbose', 'Show hints for all checks')
+    .action(async (options) => {
+      const exitCode = await runDoctor(options);
+      if (exitCode !== 0) process.exit(exitCode);
+    });
+}
+
+module.exports = { register, runDoctor };

package/src/commands/quickstart.js

@@ -0,0 +1,203 @@
+'use strict';
+
+const pc = require('picocolors');
+const readline = require('readline');
+const { getConfigValue } = require('../lib/config');
+const { embed } = require('../lib/api');
+
+/**
+ * vai quickstart — Zero-to-search interactive tutorial
+ * Gets developers from nothing to their first semantic search in minutes.
+ */
+
+const SAMPLE_DOCS = [
+  "MongoDB Atlas Vector Search enables semantic search on your data using machine learning embeddings.",
+  "Voyage AI provides state-of-the-art embedding models with the best quality-to-cost ratio.",
+  "RAG (Retrieval-Augmented Generation) combines vector search with LLMs for accurate AI responses.",
+  "The shared embedding space in Voyage 4 models lets you embed queries and documents with different models.",
+  "Reranking improves search precision by re-scoring results with a cross-encoder model.",
+];
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function createPrompt() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  
+  return {
+    ask: (question) => new Promise((resolve) => {
+      rl.question(question, (answer) => resolve(answer));
+    }),
+    close: () => rl.close(),
+  };
+}
+
+async function runQuickstart(options = {}) {
+  const { skip } = options;
+  
+  console.log(pc.bold('\n🚀 Voyage AI CLI Quickstart\n'));
+  console.log(pc.dim('This tutorial will get you from zero to semantic search in 2 minutes.\n'));
+  
+  // Check for API key
+  const apiKey = process.env.VOYAGE_API_KEY || getConfigValue('apiKey');
+  if (!apiKey) {
+    console.log(pc.red('✗ No API key found.\n'));
+    console.log('  First, get a free API key:');
+    console.log(pc.cyan('  → https://dash.voyageai.com/api-keys\n'));
+    console.log('  Then configure it:');
+    console.log(pc.cyan('  → vai config set api-key YOUR_KEY\n'));
+    console.log('  Or set the environment variable:');
+    console.log(pc.cyan('  → export VOYAGE_API_KEY=YOUR_KEY\n'));
+    return 1;
+  }
+  
+  console.log(pc.green('✓') + ' API key configured\n');
+  
+  // Step 1: Explain what we're doing
+  console.log(pc.bold('Step 1: Understanding Embeddings'));
+  console.log(pc.dim('─'.repeat(40)));
+  console.log(`
+Embeddings turn text into ${pc.cyan('vectors')} (arrays of numbers) that capture
+meaning. Similar texts have similar vectors, enabling semantic search.
+
+We'll embed these ${SAMPLE_DOCS.length} sample documents:
+`);
+  
+  SAMPLE_DOCS.forEach((doc, i) => {
+    const preview = doc.length > 70 ? doc.slice(0, 70) + '...' : doc;
+    console.log(`  ${i + 1}. ${pc.dim(preview)}`);
+  });
+  console.log('');
+  
+  if (!skip) {
+    const prompt = createPrompt();
+    await prompt.ask(pc.dim('Press Enter to continue...'));
+    prompt.close();
+  }
+  
+  // Step 2: Embed the documents
+  console.log(pc.bold('\nStep 2: Embedding Documents'));
+  console.log(pc.dim('─'.repeat(40)));
+  console.log(`
+Running: ${pc.cyan('vai embed --model voyage-3-lite')}
+`);
+  
+  let embeddings;
+  try {
+    process.stdout.write('  Embedding documents... ');
+    const result = await embed({
+      texts: SAMPLE_DOCS,
+      model: 'voyage-3-lite',
+      inputType: 'document',
+    });
+    embeddings = result.embeddings;
+    console.log(pc.green('✓'));
+    console.log(`
+  ${pc.green('✓')} Created ${embeddings.length} embeddings
+  ${pc.dim(`  Dimensions: ${embeddings[0].length}`)}
+  ${pc.dim(`  Model: voyage-3-lite`)}
+`);
+  } catch (err) {
+    console.log(pc.red('✗'));
+    console.log(pc.red(`\n  Error: ${err.message}\n`));
+    console.log('  Check your API key with: vai doctor\n');
+    return 1;
+  }
+  
+  // Step 3: Search
+  console.log(pc.bold('Step 3: Semantic Search'));
+  console.log(pc.dim('─'.repeat(40)));
+  
+  const query = 'How do I improve search accuracy?';
+  console.log(`
+Now let's search! We'll embed a query and find the most similar documents.
+
+Query: "${pc.cyan(query)}"
+`);
+  
+  try {
+    process.stdout.write('  Embedding query... ');
+    const queryResult = await embed({
+      texts: [query],
+      model: 'voyage-3-lite',
+      inputType: 'query',
+    });
+    const queryEmbedding = queryResult.embeddings[0];
+    console.log(pc.green('✓'));
+    
+    // Calculate similarities
+    const similarities = embeddings.map((docEmb, i) => {
+      const dotProduct = docEmb.reduce((sum, val, j) => sum + val * queryEmbedding[j], 0);
+      const normA = Math.sqrt(docEmb.reduce((sum, val) => sum + val * val, 0));
+      const normB = Math.sqrt(queryEmbedding.reduce((sum, val) => sum + val * val, 0));
+      return {
+        index: i,
+        score: dotProduct / (normA * normB),
+        text: SAMPLE_DOCS[i],
+      };
+    });
+    
+    // Sort by similarity
+    similarities.sort((a, b) => b.score - a.score);
+    
+    console.log(`
+  ${pc.bold('Results (ranked by similarity):')}
+`);
+    
+    similarities.forEach((item, rank) => {
+      const scoreColor = item.score > 0.5 ? pc.green : item.score > 0.3 ? pc.yellow : pc.dim;
+      const preview = item.text.length > 60 ? item.text.slice(0, 60) + '...' : item.text;
+      console.log(`  ${rank + 1}. ${scoreColor(item.score.toFixed(3))} ${preview}`);
+    });
+    
+  } catch (err) {
+    console.log(pc.red('✗'));
+    console.log(pc.red(`\n  Error: ${err.message}\n`));
+    return 1;
+  }
+  
+  // Success!
+  console.log(pc.bold('\n✨ Congratulations!'));
+  console.log(pc.dim('─'.repeat(40)));
+  console.log(`
+You just performed your first semantic search with Voyage AI!
+
+The top result about ${pc.cyan('reranking')} is relevant because it discusses
+improving search ${pc.cyan('precision')} — even though it doesn't contain the
+exact words "improve" or "accuracy". That's the power of embeddings!
+
+${pc.bold('Why Voyage AI?')}
+  • ${pc.cyan('Best quality-to-cost ratio')} — SOTA quality at lower prices
+  • ${pc.cyan('Shared embedding space')} — mix models for cost optimization
+  • ${pc.cyan('Domain-specific models')} — code, finance, law, multilingual
+  • ${pc.cyan('Reranking')} — boost precision with two-stage retrieval
+
+${pc.bold('Next Steps:')}
+  ${pc.cyan('vai explain embeddings')}  — Learn more about how embeddings work
+  ${pc.cyan('vai explain reranking')}   — Understand two-stage retrieval
+  ${pc.cyan('vai demo')}                — Full interactive walkthrough
+  ${pc.cyan('vai pipeline')}            — Build a complete RAG pipeline
+  ${pc.cyan('vai playground')}          — Visual exploration in your browser
+
+${pc.dim('Docs: https://docs.voyageai.com | Dashboard: https://dash.voyageai.com')}
+`);
+  
+  return 0;
+}
+
+function register(program) {
+  program
+    .command('quickstart')
+    .description('Zero-to-search tutorial — learn semantic search in 2 minutes')
+    .option('--skip', 'Skip interactive prompts')
+    .action(async (options) => {
+      const exitCode = await runQuickstart(options);
+      process.exit(exitCode);
+    });
+}
+
+module.exports = { register, runQuickstart };

package/src/lib/explanations.js

@@ -1,6 +1,13 @@
 'use strict';
 
-const pc = require('picocolors');
+// Gracefully handle missing picocolors (e.g., in packaged Electron app)
+let pc;
+try {
+  pc = require('picocolors');
+} catch {
+  // Fallback: no-op functions that return input unchanged
+  pc = new Proxy({}, { get: () => (s) => s });
+}
 
 /**
  * Map of concept key → explanation object.
@@ -871,6 +878,147 @@ const concepts = {
     ],
   },
 
+  'provider-comparison': {
+    title: 'Voyage AI vs OpenAI vs Anthropic',
+    summary: 'Understanding the differences between AI providers for embeddings and search',
+    content: [
+      `Developers often ask: "Should I use Voyage AI, OpenAI, or Anthropic for my vector`,
+      `search application?" The answer depends on what you're building — these companies`,
+      `serve ${pc.cyan('fundamentally different purposes')}.`,
+      ``,
+      `${pc.bold('TL;DR:')}`,
+      `  ${pc.cyan('Voyage AI')}   → ${pc.bold('Embeddings & Reranking')} (specialized, best-in-class)`,
+      `  ${pc.cyan('OpenAI')}      → ${pc.bold('Embeddings + Generation')} (general-purpose, convenient)`,
+      `  ${pc.cyan('Anthropic')}   → ${pc.bold('Generation only')} (Claude LLM, no embedding API)`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold(pc.cyan('VOYAGE AI'))} — The Embedding Specialist`,
+      ``,
+      `Voyage AI is ${pc.cyan('100% focused on embeddings and reranking')}. That's it. No chatbots,`,
+      `no image generation — just the best vector representations for retrieval.`,
+      ``,
+      `${pc.dim('Models:')}`,
+      `  • ${pc.cyan('voyage-4-large')}      71.41 RTEB score (SOTA), MoE architecture`,
+      `  • ${pc.cyan('voyage-4')}            70.07 RTEB, balanced quality/cost`,
+      `  • ${pc.cyan('voyage-4-lite')}       68.10 RTEB, lowest cost`,
+      `  • ${pc.cyan('voyage-code-3')}       Optimized for code retrieval`,
+      `  • ${pc.cyan('voyage-finance-2')}    Financial documents`,
+      `  • ${pc.cyan('voyage-law-2')}        Legal text`,
+      `  • ${pc.cyan('voyage-multimodal-3.5')} Images + text in same space`,
+      `  • ${pc.cyan('rerank-2.5')}          Best-in-class reranking`,
+      ``,
+      `${pc.dim('Unique strengths:')}`,
+      `  • ${pc.cyan('Shared embedding space')} — mix models freely (embed docs with -large, query with -lite)`,
+      `  • ${pc.cyan('Matryoshka dimensions')} — truncate 1024→256 dims without re-embedding`,
+      `  • ${pc.cyan('Domain-specific models')} — code, finance, law tuned for their domains`,
+      `  • ${pc.cyan('No modality gap')} — multimodal model uses unified backbone, not CLIP`,
+      `  • ${pc.cyan('Quantization support')} — int8, binary output for 4-32× storage savings`,
+      ``,
+      `${pc.dim('Pricing:')} $0.02-$0.12 per million tokens (embedding), $2/M (reranking)`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold(pc.cyan('OPENAI'))} — The General-Purpose Platform`,
+      ``,
+      `OpenAI offers embeddings as ${pc.cyan('one product among many')}. They're convenient if you're`,
+      `already using GPT, but embeddings aren't their core focus.`,
+      ``,
+      `${pc.dim('Embedding models:')}`,
+      `  • ${pc.cyan('text-embedding-3-large')}  62.57 RTEB, 3072 dims, $0.13/M tokens`,
+      `  • ${pc.cyan('text-embedding-3-small')}  62.26 RTEB, 1536 dims, $0.02/M tokens`,
+      `  • ${pc.cyan('text-embedding-ada-002')}  Legacy, 1536 dims, $0.10/M tokens`,
+      ``,
+      `${pc.dim('Strengths:')}`,
+      `  • ${pc.cyan('One platform')} — embeddings + GPT generation in same account`,
+      `  • ${pc.cyan('Familiar API')} — if you use ChatGPT API, embeddings are similar`,
+      `  • ${pc.cyan('Broad ecosystem')} — many tutorials and integrations assume OpenAI`,
+      ``,
+      `${pc.dim('Limitations:')}`,
+      `  • ${pc.cyan('Lower quality')} — voyage-4-large beats text-embedding-3-large by 14% on RTEB`,
+      `  • ${pc.cyan('No reranking')} — you need a separate provider for two-stage retrieval`,
+      `  • ${pc.cyan('No domain models')} — same model for code, legal, finance (suboptimal)`,
+      `  • ${pc.cyan('No shared space')} — can't mix models or truncate dimensions freely`,
+      `  • ${pc.cyan('No multimodal')} — text-only (CLIP is separate and limited)`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold(pc.cyan('ANTHROPIC'))} — The LLM Company (No Embeddings!)`,
+      ``,
+      `${pc.yellow('Important:')} Anthropic ${pc.bold('does not offer embedding models')}. They make Claude,`,
+      `an LLM for text generation, reasoning, and analysis — not vectorization.`,
+      ``,
+      `${pc.dim('What Anthropic offers:')}`,
+      `  • ${pc.cyan('Claude 3.5 Sonnet/Haiku')}  — Text generation, coding, analysis`,
+      `  • ${pc.cyan('Claude 3 Opus')}            — Most capable reasoning model`,
+      `  • ${pc.cyan('Tool use & function calling')} — Structured outputs`,
+      ``,
+      `${pc.dim('What Anthropic does NOT offer:')}`,
+      `  • ${pc.red('❌ Embedding models')}`,
+      `  • ${pc.red('❌ Reranking models')}`,
+      `  • ${pc.red('❌ Vector search APIs')}`,
+      ``,
+      `${pc.dim('How to use Claude with embeddings:')}`,
+      `Claude is the ${pc.cyan('"G" in RAG')} — the generation model. You still need an embedding`,
+      `provider (Voyage AI, OpenAI, Cohere) for the retrieval step:`,
+      `  1. Embed your documents with Voyage AI → store in vector DB`,
+      `  2. Embed user query → search vector DB → retrieve context`,
+      `  3. Pass context + query to Claude → generate response`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold('HEAD-TO-HEAD: Voyage AI vs OpenAI Embeddings')}`,
+      ``,
+      `${pc.dim('                        Voyage AI           OpenAI')}`,
+      `${pc.dim('─────────────────────────────────────────────────────────────────')}`,
+      `Best RTEB score         ${pc.cyan('71.41')} (v4-large)   ${pc.dim('62.57')} (v3-large)`,
+      `Reranking               ${pc.cyan('Yes')} (rerank-2.5)   ${pc.dim('No')}`,
+      `Domain models           ${pc.cyan('Yes')} (code/law/fin) ${pc.dim('No')}`,
+      `Multimodal              ${pc.cyan('Yes')} (unified)      ${pc.dim('Limited')} (CLIP)`,
+      `Shared embedding space  ${pc.cyan('Yes')}                ${pc.dim('No')}`,
+      `Flexible dimensions     ${pc.cyan('Yes')} (Matryoshka)   ${pc.dim('No')}`,
+      `Quantized output        ${pc.cyan('Yes')} (int8/binary)  ${pc.dim('No')}`,
+      `MongoDB integration     ${pc.cyan('Native')} (Atlas)     ${pc.dim('Manual')}`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold('WHEN TO USE EACH:')}`,
+      ``,
+      `${pc.cyan('Choose Voyage AI when:')}`,
+      `  • Retrieval quality is critical (RAG, search, recommendations)`,
+      `  • You need domain-specific embeddings (code, legal, finance)`,
+      `  • You want two-stage retrieval (embed → search → rerank)`,
+      `  • You're using MongoDB Atlas Vector Search`,
+      `  • You need multimodal search (images + text)`,
+      `  • Storage cost matters (quantization, flexible dims)`,
+      ``,
+      `${pc.cyan('Choose OpenAI embeddings when:')}`,
+      `  • You're already deep in the OpenAI ecosystem`,
+      `  • Convenience matters more than retrieval quality`,
+      `  • You don't need reranking or domain models`,
+      `  • Your use case is simple (not mission-critical search)`,
+      ``,
+      `${pc.cyan('Choose Anthropic (Claude) when:')}`,
+      `  • You need ${pc.bold('generation')}, not embeddings`,
+      `  • You want the best reasoning/coding LLM`,
+      `  • You're building the "G" in RAG (pair with Voyage for "R")`,
+      ``,
+      `${pc.bold('The winning combination:')} Use ${pc.cyan('Voyage AI for retrieval')} (embeddings +`,
+      `reranking) and ${pc.cyan('Claude for generation')}. Best of both worlds.`,
+    ].join('\n'),
+    links: [
+      'https://www.mongodb.com/docs/voyageai/models/',
+      'https://platform.openai.com/docs/guides/embeddings',
+      'https://docs.anthropic.com/',
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+    ],
+    tryIt: [
+      'vai models --wide',
+      'vai benchmark embed --models voyage-4-large,voyage-4,voyage-4-lite',
+      'vai explain rteb-benchmarks',
+    ],
+  },
+
   'rerank-eval': {
     title: 'Reranking Evaluation — nDCG, Recall, MRR for Rerankers',
     summary: 'Measure how well a reranker surfaces relevant documents',
@@ -1017,6 +1165,24 @@ const aliases = {
   recall: 'rerank-eval',
   mrr: 'rerank-eval',
   'eval-rerank': 'rerank-eval',
+  // Provider comparison aliases
+  'provider-comparison': 'provider-comparison',
+  providers: 'provider-comparison',
+  'voyage-vs-openai': 'provider-comparison',
+  'openai-vs-voyage': 'provider-comparison',
+  'voyage-vs-anthropic': 'provider-comparison',
+  'anthropic-vs-voyage': 'provider-comparison',
+  'openai-vs-anthropic': 'provider-comparison',
+  'anthropic-vs-openai': 'provider-comparison',
+  'voyage-openai-anthropic': 'provider-comparison',
+  differences: 'provider-comparison',
+  'which-provider': 'provider-comparison',
+  'compare-providers': 'provider-comparison',
+  'embedding-providers': 'provider-comparison',
+  'vs-openai': 'provider-comparison',
+  'vs-anthropic': 'provider-comparison',
+  competitors: 'provider-comparison',
+  alternatives: 'provider-comparison',
 };
 
 /**

package/src/playground/index.html

@@ -2309,19 +2309,19 @@ select:focus { outline: none; border-color: var(--accent); }
     <button class="sidebar-settings-btn" data-tab="settings" title="Settings"><svg width="16" height="16" viewBox="0 0 16 16"><use href="#lg-config"/></svg></button>
   </div>
   <nav class="sidebar-nav">
-    <div class="sidebar-nav-group">
-      <div class="sidebar-nav-label">Tools</div>
-      <button class="tab-btn active" data-tab="embed"><span class="tab-btn-icon"><svg><use href="#lg-lightning"/></svg></span><span>Embed</span></button>
-      <button class="tab-btn" data-tab="compare"><span class="tab-btn-icon"><svg><use href="#lg-arrows"/></svg></span><span>Compare</span></button>
-      <button class="tab-btn" data-tab="search"><span class="tab-btn-icon"><svg><use href="#lg-search"/></svg></span><span>Search</span></button>
-      <button class="tab-btn" data-tab="multimodal"><span class="tab-btn-icon"><svg><use href="#lg-image"/></svg></span><span>Multimodal</span></button>
+    <div class="sidebar-nav-group" role="tablist" aria-label="Tools">
+      <div class="sidebar-nav-label" id="nav-tools-label">Tools</div>
+      <button class="tab-btn active" data-tab="embed" role="tab" aria-selected="true" aria-controls="tab-embed" id="tab-btn-embed"><span class="tab-btn-icon" aria-hidden="true"><svg><use href="#lg-lightning"/></svg></span><span>Embed</span></button>
+      <button class="tab-btn" data-tab="compare" role="tab" aria-selected="false" aria-controls="tab-compare" id="tab-btn-compare"><span class="tab-btn-icon" aria-hidden="true"><svg><use href="#lg-arrows"/></svg></span><span>Compare</span></button>
+      <button class="tab-btn" data-tab="search" role="tab" aria-selected="false" aria-controls="tab-search" id="tab-btn-search"><span class="tab-btn-icon" aria-hidden="true"><svg><use href="#lg-search"/></svg></span><span>Search</span></button>
+      <button class="tab-btn" data-tab="multimodal" role="tab" aria-selected="false" aria-controls="tab-multimodal" id="tab-btn-multimodal"><span class="tab-btn-icon" aria-hidden="true"><svg><use href="#lg-image"/></svg></span><span>Multimodal</span></button>
     </div>
     <div class="sidebar-nav-divider"></div>
-    <div class="sidebar-nav-group">
-      <div class="sidebar-nav-label">Resources</div>
-      <button class="tab-btn" data-tab="benchmark"><span class="tab-btn-icon"><svg><use href="#lg-gauge"/></svg></span><span>Benchmark</span></button>
-      <button class="tab-btn" data-tab="explore"><span class="tab-btn-icon"><svg><use href="#lg-bulb"/></svg></span><span>Explore</span></button>
-      <button class="tab-btn" data-tab="about"><span class="tab-btn-icon"><svg><use href="#lg-info"/></svg></span><span>About</span></button>
+    <div class="sidebar-nav-group" role="tablist" aria-label="Resources">
+      <div class="sidebar-nav-label" id="nav-resources-label">Resources</div>
+      <button class="tab-btn" data-tab="benchmark" role="tab" aria-selected="false" aria-controls="tab-benchmark" id="tab-btn-benchmark"><span class="tab-btn-icon" aria-hidden="true"><svg><use href="#lg-gauge"/></svg></span><span>Benchmark</span></button>
+      <button class="tab-btn" data-tab="explore" role="tab" aria-selected="false" aria-controls="tab-explore" id="tab-btn-explore"><span class="tab-btn-icon" aria-hidden="true"><svg><use href="#lg-bulb"/></svg></span><span>Explore</span></button>
+      <button class="tab-btn" data-tab="about" role="tab" aria-selected="false" aria-controls="tab-about" id="tab-btn-about"><span class="tab-btn-icon" aria-hidden="true"><svg><use href="#lg-info"/></svg></span><span>About</span></button>
     </div>
   </nav>
   <div class="sidebar-footer">
@@ -2356,7 +2356,7 @@ select:focus { outline: none; border-color: var(--accent); }
   <div class="main">
 
 <!-- ========== EMBED TAB ========== -->
-<div class="tab-panel active" id="tab-embed">
+<div class="tab-panel active" id="tab-embed" role="tabpanel" aria-labelledby="tab-btn-embed" tabindex="0">
   <div class="page-header">
     <h2 class="page-header-title">Embed</h2>
     <p class="page-header-subtitle">Generate vector embeddings for text</p>
@@ -2364,7 +2364,7 @@ select:focus { outline: none; border-color: var(--accent); }
   </div>
   <div class="card">
     <div class="card-title">Input Text</div>
-    <textarea id="embedInput" rows="5" placeholder="Enter text to embed...">MongoDB Atlas provides powerful vector search capabilities for AI applications.</textarea>
+    <textarea id="embedInput" rows="5" placeholder="Enter text to embed..." aria-label="Text to embed">MongoDB Atlas provides powerful vector search capabilities for AI applications.</textarea>
   </div>
 
   <div class="options-row">
@@ -2420,7 +2420,7 @@ select:focus { outline: none; border-color: var(--accent); }
 </div>
 
 <!-- ========== COMPARE TAB ========== -->
-<div class="tab-panel" id="tab-compare">
+<div class="tab-panel" id="tab-compare" role="tabpanel" aria-labelledby="tab-btn-compare" tabindex="0">
   <div class="page-header">
     <h2 class="page-header-title">Compare</h2>
     <p class="page-header-subtitle">Visualize similarity between text pairs</p>
@@ -2474,7 +2474,7 @@ select:focus { outline: none; border-color: var(--accent); }
 </div>
 
 <!-- ========== SEARCH TAB ========== -->
-<div class="tab-panel" id="tab-search">
+<div class="tab-panel" id="tab-search" role="tabpanel" aria-labelledby="tab-btn-search" tabindex="0">
   <div class="page-header">
     <h2 class="page-header-title">Rerank</h2>
     <p class="page-header-subtitle">Re-order documents by relevance to a query</p>
@@ -2482,7 +2482,7 @@ select:focus { outline: none; border-color: var(--accent); }
   </div>
   <div class="card">
     <div class="card-title">Query</div>
-    <input type="text" id="searchQuery" placeholder="Enter your search query..." value="How do I build AI-powered search?">
+    <input type="text" id="searchQuery" placeholder="Enter your search query..." value="How do I build AI-powered search?" aria-label="Search query">
   </div>
 
   <div class="card">
@@ -2525,7 +2525,7 @@ Semantic search understands meaning beyond keyword matching</textarea>
 </div>
 
 <!-- ========== MULTIMODAL TAB ========== -->
-<div class="tab-panel" id="tab-multimodal">
+<div class="tab-panel" id="tab-multimodal" role="tabpanel" aria-labelledby="tab-btn-multimodal" tabindex="0">
   <div class="page-header">
     <h2 class="page-header-title">Multimodal</h2>
     <p class="page-header-subtitle">Compare images and text in the same vector space</p>
@@ -2640,7 +2640,7 @@ Semantic search understands meaning beyond keyword matching</textarea>
 </div>
 
 <!-- ========== BENCHMARK TAB ========== -->
-<div class="tab-panel" id="tab-benchmark">
+<div class="tab-panel" id="tab-benchmark" role="tabpanel" aria-labelledby="tab-btn-benchmark" tabindex="0">
   <div class="page-header">
     <h2 class="page-header-title">Benchmark</h2>
     <p class="page-header-subtitle">Compare model speed, cost, and quality</p>
@@ -2651,6 +2651,7 @@ Semantic search understands meaning beyond keyword matching</textarea>
   <div class="bench-panels">
     <button class="bench-panel-btn active" data-bench="latency">⚡ Latency</button>
     <button class="bench-panel-btn" data-bench="ranking">🏆 Ranking</button>
+    <button class="bench-panel-btn" data-bench="competitors">⚔️ vs Competitors</button>
     <button class="bench-panel-btn" data-bench="quantization">⚗️ Quantization</button>
     <button class="bench-panel-btn" data-bench="cost">💰 Cost</button>
     <button class="bench-panel-btn" data-bench="history">📊 History</button>
@@ -2744,6 +2745,168 @@ Reranking models rescore initial search results to improve relevance ordering.</
     </div>
   </div>
 
+  <!-- ── Competitors Panel ── -->
+  <div class="bench-view" id="bench-competitors">
+    <div class="card">
+      <div class="card-title">Why Voyage AI? — Competitive Comparison</div>
+      <p style="color:var(--text-dim);font-size:13px;margin-bottom:16px;">
+        See how Voyage AI compares to other embedding providers on quality, cost, and features.
+      </p>
+    </div>
+
+    <!-- MTEB Retrieval Benchmark -->
+    <div class="card" style="margin-top:16px;">
+      <div class="card-title">🏆 MTEB Retrieval Benchmark (nDCG@10)</div>
+      <p style="color:var(--text-dim);font-size:13px;margin-bottom:16px;">
+        Industry-standard benchmark for retrieval quality. Higher is better.
+      </p>
+      <div id="mtebChart" style="display:flex;flex-direction:column;gap:8px;">
+        <!-- Voyage AI -->
+        <div style="display:flex;align-items:center;gap:12px;">
+          <span style="min-width:140px;font-weight:600;color:var(--accent);">Voyage-3</span>
+          <div style="flex:1;height:24px;background:var(--surface);border-radius:4px;overflow:hidden;">
+            <div style="width:67.4%;height:100%;background:var(--accent);border-radius:4px;"></div>
+          </div>
+          <span style="min-width:50px;text-align:right;font-family:var(--mono);color:var(--accent);font-weight:600;">67.4</span>
+        </div>
+        <div style="display:flex;align-items:center;gap:12px;">
+          <span style="min-width:140px;font-weight:600;color:var(--accent);">Voyage-3-lite</span>
+          <div style="flex:1;height:24px;background:var(--surface);border-radius:4px;overflow:hidden;">
+            <div style="width:64.3%;height:100%;background:var(--accent);opacity:0.7;border-radius:4px;"></div>
+          </div>
+          <span style="min-width:50px;text-align:right;font-family:var(--mono);color:var(--accent);">64.3</span>
+        </div>
+        <!-- Competitors -->
+        <div style="display:flex;align-items:center;gap:12px;">
+          <span style="min-width:140px;color:var(--text-dim);">OpenAI text-3-large</span>
+          <div style="flex:1;height:24px;background:var(--surface);border-radius:4px;overflow:hidden;">
+            <div style="width:64.6%;height:100%;background:#666;border-radius:4px;"></div>
+          </div>
+          <span style="min-width:50px;text-align:right;font-family:var(--mono);color:var(--text-dim);">64.6</span>
+        </div>
+        <div style="display:flex;align-items:center;gap:12px;">
+          <span style="min-width:140px;color:var(--text-dim);">OpenAI text-3-small</span>
+          <div style="flex:1;height:24px;background:var(--surface);border-radius:4px;overflow:hidden;">
+            <div style="width:62.3%;height:100%;background:#666;border-radius:4px;"></div>
+          </div>
+          <span style="min-width:50px;text-align:right;font-family:var(--mono);color:var(--text-dim);">62.3</span>
+        </div>
+        <div style="display:flex;align-items:center;gap:12px;">
+          <span style="min-width:140px;color:var(--text-dim);">Cohere embed-v3</span>
+          <div style="flex:1;height:24px;background:var(--surface);border-radius:4px;overflow:hidden;">
+            <div style="width:64.1%;height:100%;background:#666;border-radius:4px;"></div>
+          </div>
+          <span style="min-width:50px;text-align:right;font-family:var(--mono);color:var(--text-dim);">64.1</span>
+        </div>
+      </div>
+      <p style="color:var(--text-dim);font-size:11px;margin-top:12px;">
+        Source: <a href="https://huggingface.co/spaces/mteb/leaderboard" target="_blank" style="color:var(--accent);">MTEB Leaderboard</a> (Retrieval Average, Jan 2025)
+      </p>
+    </div>
+
+    <!-- Cost Comparison -->
+    <div class="card" style="margin-top:16px;">
+      <div class="card-title">💰 Cost per Million Tokens</div>
+      <p style="color:var(--text-dim);font-size:13px;margin-bottom:16px;">
+        Voyage AI offers significant cost savings, especially with asymmetric retrieval strategies.
+      </p>
+      <table style="width:100%;border-collapse:collapse;font-size:13px;">
+        <thead>
+          <tr style="border-bottom:1px solid var(--border);">
+            <th style="text-align:left;padding:8px 12px;color:var(--text-dim);">Provider / Model</th>
+            <th style="text-align:right;padding:8px 12px;color:var(--text-dim);">Price</th>
+            <th style="text-align:right;padding:8px 12px;color:var(--text-dim);">vs Voyage-3</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr style="border-bottom:1px solid var(--border);">
+            <td style="padding:8px 12px;font-weight:600;color:var(--accent);">Voyage-3-lite</td>
+            <td style="text-align:right;padding:8px 12px;font-family:var(--mono);color:var(--accent);">$0.02</td>
+            <td style="text-align:right;padding:8px 12px;color:var(--success);font-weight:600;">83% cheaper</td>
+          </tr>
+          <tr style="border-bottom:1px solid var(--border);">
+            <td style="padding:8px 12px;font-weight:600;color:var(--accent);">Voyage-3</td>
+            <td style="text-align:right;padding:8px 12px;font-family:var(--mono);color:var(--accent);">$0.06</td>
+            <td style="text-align:right;padding:8px 12px;color:var(--text-dim);">baseline</td>
+          </tr>
+          <tr style="border-bottom:1px solid var(--border);">
+            <td style="padding:8px 12px;color:var(--text-dim);">OpenAI text-3-large</td>
+            <td style="text-align:right;padding:8px 12px;font-family:var(--mono);">$0.13</td>
+            <td style="text-align:right;padding:8px 12px;color:var(--error);">2.2x more</td>
+          </tr>
+          <tr style="border-bottom:1px solid var(--border);">
+            <td style="padding:8px 12px;color:var(--text-dim);">OpenAI text-3-small</td>
+            <td style="text-align:right;padding:8px 12px;font-family:var(--mono);">$0.02</td>
+            <td style="text-align:right;padding:8px 12px;color:var(--text-dim);">same</td>
+          </tr>
+          <tr>
+            <td style="padding:8px 12px;color:var(--text-dim);">Cohere embed-v3</td>
+            <td style="text-align:right;padding:8px 12px;font-family:var(--mono);">$0.10</td>
+            <td style="text-align:right;padding:8px 12px;color:var(--error);">1.7x more</td>
+          </tr>
+        </tbody>
+      </table>
+      <div style="margin-top:16px;padding:12px;background:var(--accent-glow);border-radius:8px;border-left:3px solid var(--accent);">
+        <strong style="color:var(--accent);">💡 Pro Tip: Asymmetric Retrieval</strong>
+        <p style="margin:8px 0 0 0;font-size:13px;color:var(--text);">
+          Embed your document corpus with <code style="background:var(--surface);padding:2px 6px;border-radius:4px;">voyage-3-lite</code> ($0.02/M) and 
+          query with <code style="background:var(--surface);padding:2px 6px;border-radius:4px;">voyage-3</code> ($0.06/M). 
+          Because all Voyage-3 models share the same embedding space, you get top-tier retrieval quality at a fraction of the cost.
+        </p>
+      </div>
+    </div>
+
+    <!-- Key Differentiators -->
+    <div class="card" style="margin-top:16px;">
+      <div class="card-title">🚀 Voyage AI Advantages</div>
+      <div style="display:grid;grid-template-columns:repeat(auto-fit, minmax(280px, 1fr));gap:16px;margin-top:12px;">
+        <div style="padding:16px;background:var(--surface);border-radius:8px;border:1px solid var(--border);">
+          <div style="font-size:20px;margin-bottom:8px;">🔗</div>
+          <div style="font-weight:600;margin-bottom:4px;">Shared Embedding Space</div>
+          <div style="font-size:13px;color:var(--text-dim);">
+            All Voyage-3 models produce compatible embeddings. Mix <code>voyage-3-large</code> for queries 
+            with <code>voyage-3-lite</code> for documents — they work together seamlessly.
+          </div>
+        </div>
+        <div style="padding:16px;background:var(--surface);border-radius:8px;border:1px solid var(--border);">
+          <div style="font-size:20px;margin-bottom:8px;">🏢</div>
+          <div style="font-weight:600;margin-bottom:4px;">Domain-Specific Models</div>
+          <div style="font-size:13px;color:var(--text-dim);">
+            Specialized models for code (<code>voyage-code-3</code>), finance, law, and multilingual content 
+            that outperform general-purpose alternatives.
+          </div>
+        </div>
+        <div style="padding:16px;background:var(--surface);border-radius:8px;border:1px solid var(--border);">
+          <div style="font-size:20px;margin-bottom:8px;">⚡</div>
+          <div style="font-weight:600;margin-bottom:4px;">Two-Stage Retrieval</div>
+          <div style="font-size:13px;color:var(--text-dim);">
+            Combine embedding search with <code>rerank-2</code> to dramatically boost precision. 
+            The cross-encoder re-scores candidates for better relevance.
+          </div>
+        </div>
+        <div style="padding:16px;background:var(--surface);border-radius:8px;border:1px solid var(--border);">
+          <div style="font-size:20px;margin-bottom:8px;">🖼️</div>
+          <div style="font-weight:600;margin-bottom:4px;">Multimodal Embeddings</div>
+          <div style="font-size:13px;color:var(--text-dim);">
+            <code>voyage-multimodal-3</code> embeds both text and images in the same space, 
+            enabling cross-modal search (find images with text queries and vice versa).
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- CTA -->
+    <div class="card" style="margin-top:16px;text-align:center;padding:24px;">
+      <div style="font-size:18px;font-weight:600;margin-bottom:8px;">Ready to try Voyage AI?</div>
+      <p style="color:var(--text-dim);margin-bottom:16px;">Get a free API key and start building in minutes.</p>
+      <a href="https://dash.voyageai.com" target="_blank" class="btn" style="display:inline-block;text-decoration:none;">
+        Get API Key →
+      </a>
+      <span style="margin:0 12px;color:var(--text-dim);">or</span>
+      <a href="https://docs.voyageai.com" target="_blank" style="color:var(--accent);">Read the Docs</a>
+    </div>
+  </div>
+
   <!-- ── Quantization Panel ── -->
   <div class="bench-view" id="bench-quantization">
     <div class="card">
@@ -2961,7 +3124,7 @@ Reranking models rescore initial search results to improve relevance ordering.</
 </div>
 
 <!-- ========== ABOUT TAB ========== -->
-<div class="tab-panel" id="tab-about">
+<div class="tab-panel" id="tab-about" role="tabpanel" aria-labelledby="tab-btn-about" tabindex="0">
   <div class="about-container">
     <div class="card">
       <div class="about-header">
@@ -3052,24 +3215,24 @@ Reranking models rescore initial search results to improve relevance ordering.</
 </div>
 
 <!-- ========== EXPLORE TAB ========== -->
-<div class="tab-panel" id="tab-explore">
+<div class="tab-panel" id="tab-explore" role="tabpanel" aria-labelledby="tab-btn-explore" tabindex="0">
   <div class="page-header">
     <h2 class="page-header-title">Explore</h2>
     <p class="page-header-subtitle">Learn embedding and vector search concepts</p>
     <p class="page-header-hint">Browse interactive explanations of key topics — from cosine similarity to quantization to RAG pipelines.</p>
   </div>
   <div style="margin-bottom:16px;">
-    <input type="text" id="exploreSearch" placeholder="🔍 Search concepts..." oninput="filterExplore()" style="max-width:400px;">
+    <input type="text" id="exploreSearch" placeholder="🔍 Search concepts..." oninput="filterExplore()" style="max-width:400px;" aria-label="Search concepts">
   </div>
   <div class="explore-grid" id="exploreGrid"></div>
 </div>
 
 <!-- Explore Concept Modal -->
-<div class="explore-modal-overlay" id="exploreModal">
+<div class="explore-modal-overlay" id="exploreModal" role="dialog" aria-modal="true" aria-labelledby="exploreModalTitle" aria-describedby="exploreModalSummary">
   <div class="explore-modal">
-    <button class="explore-modal-close" id="exploreModalClose">&times;</button>
+    <button class="explore-modal-close" id="exploreModalClose" aria-label="Close modal">&times;</button>
     <div class="explore-modal-header">
-      <div class="explore-modal-icon" id="exploreModalIcon"></div>
+      <div class="explore-modal-icon" id="exploreModalIcon" aria-hidden="true"></div>
       <div>
         <div class="explore-modal-title" id="exploreModalTitle"></div>
         <div class="explore-modal-summary" id="exploreModalSummary"></div>
@@ -3450,10 +3613,38 @@ async function init() {
 
 // ── Tabs ──
 function setupTabs() {
-  document.querySelectorAll('.tab-btn').forEach(btn => {
+  const tabBtns = document.querySelectorAll('.tab-btn');
+  const tabList = Array.from(tabBtns);
+  
+  tabBtns.forEach(btn => {
     btn.addEventListener('click', () => {
       switchTab(btn.dataset.tab);
     });
+    
+    // Keyboard navigation for accessibility
+    btn.addEventListener('keydown', (e) => {
+      const currentIndex = tabList.indexOf(btn);
+      let nextIndex = -1;
+      
+      if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
+        e.preventDefault();
+        nextIndex = (currentIndex + 1) % tabList.length;
+      } else if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
+        e.preventDefault();
+        nextIndex = (currentIndex - 1 + tabList.length) % tabList.length;
+      } else if (e.key === 'Home') {
+        e.preventDefault();
+        nextIndex = 0;
+      } else if (e.key === 'End') {
+        e.preventDefault();
+        nextIndex = tabList.length - 1;
+      }
+      
+      if (nextIndex >= 0) {
+        tabList[nextIndex].focus();
+        switchTab(tabList[nextIndex].dataset.tab);
+      }
+    });
   });
 
   // Settings cog in header
@@ -3467,10 +3658,17 @@ function setupTabs() {
 
 function switchTab(tab) {
   document.querySelectorAll('.tab-btn').forEach(b => {
-    b.classList.toggle('active', b.dataset.tab === tab);
+    const isActive = b.dataset.tab === tab;
+    b.classList.toggle('active', isActive);
+    // Update ARIA attributes for accessibility
+    b.setAttribute('aria-selected', isActive ? 'true' : 'false');
+    b.setAttribute('tabindex', isActive ? '0' : '-1');
   });
   document.querySelectorAll('.tab-panel').forEach(p => {
-    p.classList.toggle('active', p.id === 'tab-' + tab);
+    const isActive = p.id === 'tab-' + tab;
+    p.classList.toggle('active', isActive);
+    // Hide inactive panels from screen readers
+    p.setAttribute('aria-hidden', isActive ? 'false' : 'true');
   });
   // Sync settings cog highlight
   const settingsBtn = document.querySelector('.sidebar-settings-btn');
@@ -3940,6 +4138,7 @@ const CONCEPT_META = {
   'cross-modal-search':    { icon: '🔀', tab: 'multimodal' },
   'modality-gap':          { icon: '🕳️', tab: 'multimodal' },
   'multimodal-rag':        { icon: '📄', tab: 'multimodal' },
+  'provider-comparison':   { icon: '⚖️', tab: 'explore' },
 };
 
 let exploreConcepts = {};
@@ -3981,13 +4180,26 @@ function buildExploreCards() {
   const modal = document.getElementById('exploreModal');
   document.getElementById('exploreModalClose').addEventListener('click', closeExploreModal);
   modal.addEventListener('click', (e) => { if (e.target === modal) closeExploreModal(); });
+  
+  // Close modal on Escape key for accessibility
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && modal.classList.contains('open')) {
+      closeExploreModal();
+    }
+  });
 }
 
+// Store previously focused element for modal focus management
+let exploreModalPreviousFocus = null;
+
 function openExploreModal(key) {
   const concept = exploreConcepts[key];
   if (!concept) return;
   const meta = CONCEPT_META[key] || { icon: '📚', tab: 'embed' };
 
+  // Save the currently focused element to restore when modal closes
+  exploreModalPreviousFocus = document.activeElement;
+
   document.getElementById('exploreModalIcon').textContent = meta.icon;
   document.getElementById('exploreModalTitle').textContent = concept.title;
   document.getElementById('exploreModalSummary').textContent = concept.summary;
@@ -4021,11 +4233,23 @@ function openExploreModal(key) {
     if (meta.tab) switchTab(meta.tab);
   });
 
-  document.getElementById('exploreModal').classList.add('open');
+  const modal = document.getElementById('exploreModal');
+  modal.classList.add('open');
+  
+  // Focus the close button for accessibility
+  setTimeout(() => {
+    document.getElementById('exploreModalClose').focus();
+  }, 100);
 }
 
 function closeExploreModal() {
   document.getElementById('exploreModal').classList.remove('open');
+  
+  // Restore focus to the previously focused element
+  if (exploreModalPreviousFocus && typeof exploreModalPreviousFocus.focus === 'function') {
+    exploreModalPreviousFocus.focus();
+    exploreModalPreviousFocus = null;
+  }
 }
 
 window.tryTopic = function(key) {
@@ -5935,13 +6159,12 @@ init = async function() {
   initMultimodal();
   checkForAppUpdate();
   initOnboarding();
-};
+};  
 
 // ── Start ──
 init();
-
-// ── 🕹️ Vector Space Invaders (Easter Egg) ──
-// Trigger: Konami code (↑↑↓↓←→←→BA) or 7 rapid clicks on sidebar logo
+ 
+// ──  Vector Space Invaders (Easter Egg) ──    
 (function initEasterEgg() {
   const KONAMI = ['ArrowUp','ArrowUp','ArrowDown','ArrowDown','ArrowLeft','ArrowRight','ArrowLeft','ArrowRight','b','a'];
   let konamiIdx = 0;