voyageai-cli 1.13.0 → 1.15.0

package/package.json

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

package/src/cli.js

@@ -20,6 +20,7 @@ const { registerIngest } = require('./commands/ingest');
 const { registerCompletions } = require('./commands/completions');
 const { registerPlayground } = require('./commands/playground');
 const { registerBenchmark } = require('./commands/benchmark');
+const { registerEstimate } = require('./commands/estimate');
 const { registerAbout } = require('./commands/about');
 const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
 
@@ -45,6 +46,7 @@ registerIngest(program);
 registerCompletions(program);
 registerPlayground(program);
 registerBenchmark(program);
+registerEstimate(program);
 registerAbout(program);
 
 // Append disclaimer to all help output

package/src/commands/benchmark.js

@@ -1212,6 +1212,170 @@ function registerBenchmark(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action(benchmarkAsymmetric);
+
+  // ── benchmark space ──
+  bench
+    .command('space')
+    .description('Validate shared embedding space — embed same text with all Voyage 4 models')
+    .option('--text <text>', 'Text to embed across models')
+    .option('--texts <texts>', 'Comma-separated texts to compare')
+    .option('--models <models>', 'Comma-separated models', 'voyage-4-large,voyage-4,voyage-4-lite')
+    .option('-d, --dimensions <n>', 'Output dimensions (must be supported by all models)')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(benchmarkSpace);
+}
+
+/**
+ * benchmark space — Validate shared embedding space across Voyage 4 models.
+ * Embeds the same text(s) with multiple models, then computes pairwise cosine
+ * similarities to prove they produce compatible embeddings.
+ */
+async function benchmarkSpace(opts) {
+  const models = opts.models
+    ? parseModels(opts.models)
+    : ['voyage-4-large', 'voyage-4', 'voyage-4-lite'];
+
+  const texts = opts.texts
+    ? opts.texts.split(',').map(t => t.trim())
+    : opts.text
+      ? [opts.text]
+      : [
+        'MongoDB Atlas provides a fully managed cloud database with vector search.',
+        'Machine learning models transform raw data into semantic embeddings.',
+        'The quick brown fox jumps over the lazy dog.',
+      ];
+
+  const dimensions = opts.dimensions ? parseInt(opts.dimensions, 10) : undefined;
+
+  if (!opts.json && !opts.quiet) {
+    console.log('');
+    console.log(ui.bold('  🔮 Shared Embedding Space Validation'));
+    console.log(ui.dim(`  Models: ${models.join(', ')}`));
+    console.log(ui.dim(`  Texts: ${texts.length}${dimensions ? `, dimensions: ${dimensions}` : ''}`));
+    console.log('');
+  }
+
+  // Embed all texts with all models
+  const embeddings = {}; // { model: [[embedding for text 0], [embedding for text 1], ...] }
+
+  for (const model of models) {
+    const spin = (!opts.json && !opts.quiet) ? ui.spinner(`  Embedding with ${model}...`) : null;
+    if (spin) spin.start();
+
+    try {
+      const embedOpts = { model, inputType: 'document' };
+      if (dimensions) embedOpts.dimensions = dimensions;
+      const result = await generateEmbeddings(texts, embedOpts);
+      embeddings[model] = result.data.map(d => d.embedding);
+      if (spin) spin.stop();
+    } catch (err) {
+      if (spin) spin.stop();
+      console.error(ui.warn(`  ${model}: ${err.message} — skipping`));
+    }
+  }
+
+  const validModels = Object.keys(embeddings);
+  if (validModels.length < 2) {
+    console.error(ui.error('Need at least 2 models to compare embedding spaces.'));
+    process.exit(1);
+  }
+
+  // Compute pairwise cross-model similarities for each text
+  const results = [];
+
+  for (let t = 0; t < texts.length; t++) {
+    const textResult = {
+      text: texts[t],
+      pairs: [],
+    };
+
+    for (let i = 0; i < validModels.length; i++) {
+      for (let j = i + 1; j < validModels.length; j++) {
+        const modelA = validModels[i];
+        const modelB = validModels[j];
+        const sim = cosineSimilarity(embeddings[modelA][t], embeddings[modelB][t]);
+        textResult.pairs.push({
+          modelA,
+          modelB,
+          similarity: sim,
+        });
+      }
+    }
+
+    results.push(textResult);
+  }
+
+  // Also compute within-model similarity across different texts (baseline)
+  const withinModelSims = [];
+  if (texts.length >= 2) {
+    for (const model of validModels) {
+      const sim = cosineSimilarity(embeddings[model][0], embeddings[model][1]);
+      withinModelSims.push({ model, text0: texts[0], text1: texts[1], similarity: sim });
+    }
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ benchmark: 'space', models: validModels, texts, results, withinModelSims }, null, 2));
+    return;
+  }
+
+  // Display results
+  console.log(ui.bold('  Cross-Model Similarity (same text, different models):'));
+  console.log(ui.dim('  High similarity (>0.95) = shared embedding space confirmed'));
+  console.log('');
+
+  let allHigh = true;
+  for (const r of results) {
+    const preview = r.text.substring(0, 55) + (r.text.length > 55 ? '...' : '');
+    console.log(`  ${ui.dim('Text:')} "${preview}"`);
+
+    for (const p of r.pairs) {
+      const simStr = p.similarity.toFixed(4);
+      const quality = p.similarity >= 0.98 ? ui.green('●')
+        : p.similarity >= 0.95 ? ui.cyan('●')
+        : p.similarity >= 0.90 ? ui.yellow('●')
+        : ui.red('●');
+      if (p.similarity < 0.95) allHigh = false;
+      console.log(`    ${quality} ${rpad(p.modelA, 18)} ↔ ${rpad(p.modelB, 18)} ${ui.bold(simStr)}`);
+    }
+    console.log('');
+  }
+
+  // Show within-model cross-text similarity for context
+  if (withinModelSims.length > 0) {
+    console.log(ui.bold('  Within-Model Similarity (different texts, same model):'));
+    console.log(ui.dim('  Shows that cross-model same-text similarity is much higher'));
+    console.log('');
+
+    for (const w of withinModelSims) {
+      console.log(`    ${ui.dim(rpad(w.model, 18))} text₀ ↔ text₁  ${ui.dim(w.similarity.toFixed(4))}`);
+    }
+    console.log('');
+  }
+
+  // Summary
+  const avgCrossModel = results.flatMap(r => r.pairs).reduce((sum, p) => sum + p.similarity, 0)
+    / results.flatMap(r => r.pairs).length;
+  const avgWithin = withinModelSims.length > 0
+    ? withinModelSims.reduce((sum, w) => sum + w.similarity, 0) / withinModelSims.length
+    : null;
+
+  if (allHigh) {
+    console.log(ui.success(`Shared embedding space confirmed! Avg cross-model similarity: ${avgCrossModel.toFixed(4)}`));
+  } else {
+    console.log(ui.warn(`Cross-model similarity lower than expected. Avg: ${avgCrossModel.toFixed(4)}`));
+  }
+
+  if (avgWithin !== null) {
+    const ratio = (avgCrossModel / avgWithin).toFixed(1);
+    console.log(ui.dim(`  Cross-model same-text similarity is ${ratio}× higher than same-model different-text similarity.`));
+  }
+
+  console.log('');
+  console.log(ui.dim('  This means you can embed docs with voyage-4-large and query with voyage-4-lite'));
+  console.log(ui.dim('  — the embeddings live in the same space. See "vai explain shared-space".'));
+  console.log('');
 }
 
 module.exports = { registerBenchmark };

package/src/commands/completions.js

@@ -19,7 +19,7 @@ _vai_completions() {
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
   # Top-level commands
-  commands="embed rerank store search index models ping config demo explain similarity ingest completions help"
+  commands="embed rerank store search index models ping config demo explain similarity ingest estimate completions help"
 
   # Subcommands
   local index_subs="create list delete"
@@ -102,6 +102,10 @@ _vai_completions() {
       COMPREPLY=( \$(compgen -W "--file --db --collection --field --model --input-type --dimensions --batch-size --text-field --text-column --strict --dry-run --json --quiet --help" -- "\$cur") )
       return 0
       ;;
+    estimate)
+      COMPREPLY=( \$(compgen -W "--docs --queries --doc-tokens --query-tokens --doc-model --query-model --months --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
     completions)
       COMPREPLY=( \$(compgen -W "bash zsh --help" -- "\$cur") )
       return 0
@@ -172,6 +176,7 @@ _vai() {
     'explain:Learn about AI and vector search concepts'
     'similarity:Compute cosine similarity between texts'
     'ingest:Bulk import documents with progress'
+    'estimate:Estimate embedding costs — symmetric vs asymmetric'
     'completions:Generate shell completion scripts'
     'help:Display help for command'
   )
@@ -375,6 +380,18 @@ _vai() {
             '--json[Machine-readable JSON output]' \\
             '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
           ;;
+        estimate)
+          _arguments \\
+            '--docs[Number of documents]:count:' \\
+            '--queries[Queries per month]:count:' \\
+            '--doc-tokens[Avg tokens per document]:tokens:' \\
+            '--query-tokens[Avg tokens per query]:tokens:' \\
+            '--doc-model[Document embedding model]:model:(\$models)' \\
+            '--query-model[Query embedding model]:model:(\$models)' \\
+            '--months[Months to project]:months:' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+          ;;
         completions)
           _arguments \\
             '1:shell:(bash zsh)'

package/src/commands/estimate.js

@@ -0,0 +1,209 @@
+'use strict';
+
+const { MODEL_CATALOG } = require('../lib/catalog');
+const ui = require('../lib/ui');
+
+// Average tokens per document/query (rough industry estimates)
+const DEFAULT_DOC_TOKENS = 500;
+const DEFAULT_QUERY_TOKENS = 30;
+
+/**
+ * Parse a shorthand number: "1M" → 1000000, "500K" → 500000, "1B" → 1000000000.
+ * @param {string} val
+ * @returns {number}
+ */
+function parseShorthand(val) {
+  if (!val) return NaN;
+  const str = String(val).trim().toUpperCase();
+  const multipliers = { K: 1e3, M: 1e6, B: 1e9, T: 1e12 };
+  const match = str.match(/^([\d.]+)\s*([KMBT])?$/);
+  if (!match) return parseFloat(str);
+  const num = parseFloat(match[1]);
+  const suffix = match[2];
+  return suffix ? num * multipliers[suffix] : num;
+}
+
+/**
+ * Format a number with commas: 1234567 → "1,234,567".
+ */
+function formatNum(n) {
+  return n.toLocaleString('en-US');
+}
+
+/**
+ * Format dollars: 0.50 → "$0.50", 1234.56 → "$1,234.56".
+ */
+function formatDollars(n) {
+  if (n < 0.01 && n > 0) return `$${n.toFixed(4)}`;
+  if (n < 1) return `$${n.toFixed(2)}`;
+  return '$' + n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+
+/**
+ * Format a large number in short form: 1000000 → "1M".
+ */
+function shortNum(n) {
+  if (n >= 1e9) return (n / 1e9).toFixed(n % 1e9 === 0 ? 0 : 1) + 'B';
+  if (n >= 1e6) return (n / 1e6).toFixed(n % 1e6 === 0 ? 0 : 1) + 'M';
+  if (n >= 1e3) return (n / 1e3).toFixed(n % 1e3 === 0 ? 0 : 1) + 'K';
+  return String(n);
+}
+
+/**
+ * Register the estimate command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerEstimate(program) {
+  program
+    .command('estimate')
+    .description('Estimate embedding costs — symmetric vs asymmetric strategies')
+    .option('--docs <n>', 'Number of documents to embed (supports K/M/B shorthand)', '100K')
+    .option('--queries <n>', 'Number of queries per month (supports K/M/B shorthand)', '1M')
+    .option('--doc-tokens <n>', 'Average tokens per document', String(DEFAULT_DOC_TOKENS))
+    .option('--query-tokens <n>', 'Average tokens per query', String(DEFAULT_QUERY_TOKENS))
+    .option('--doc-model <model>', 'Model for document embedding (asymmetric)', 'voyage-4-large')
+    .option('--query-model <model>', 'Model for query embedding (asymmetric)', 'voyage-4-lite')
+    .option('--months <n>', 'Months to project', '12')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action((opts) => {
+      const numDocs = parseShorthand(opts.docs);
+      const numQueries = parseShorthand(opts.queries);
+      const docTokens = parseInt(opts.docTokens, 10) || DEFAULT_DOC_TOKENS;
+      const queryTokens = parseInt(opts.queryTokens, 10) || DEFAULT_QUERY_TOKENS;
+      const months = parseInt(opts.months, 10) || 12;
+
+      if (isNaN(numDocs) || isNaN(numQueries)) {
+        console.error(ui.error('Invalid --docs or --queries value. Use numbers or shorthand (e.g., 1M, 500K).'));
+        process.exit(1);
+      }
+
+      // Get model prices
+      const v4Models = MODEL_CATALOG.filter(m => m.sharedSpace === 'voyage-4' && m.pricePerMToken != null);
+      const docModel = MODEL_CATALOG.find(m => m.name === opts.docModel);
+      const queryModel = MODEL_CATALOG.find(m => m.name === opts.queryModel);
+
+      if (!docModel || docModel.pricePerMToken == null) {
+        console.error(ui.error(`Unknown or unpriced model: ${opts.docModel}`));
+        process.exit(1);
+      }
+      if (!queryModel || queryModel.pricePerMToken == null) {
+        console.error(ui.error(`Unknown or unpriced model: ${opts.queryModel}`));
+        process.exit(1);
+      }
+
+      const docTotalTokens = numDocs * docTokens;
+      const queryTotalTokensPerMonth = numQueries * queryTokens;
+
+      // Calculate costs for different strategies
+      const strategies = [];
+
+      // Strategy 1: Symmetric with each V4 model
+      for (const model of v4Models) {
+        if (model.pricePerMToken === 0) continue; // skip free models for symmetric
+        const docCost = (docTotalTokens / 1e6) * model.pricePerMToken;
+        const queryCostPerMonth = (queryTotalTokensPerMonth / 1e6) * model.pricePerMToken;
+        const totalCost = docCost + (queryCostPerMonth * months);
+        strategies.push({
+          name: `Symmetric: ${model.name}`,
+          type: 'symmetric',
+          docModel: model.name,
+          queryModel: model.name,
+          docCost,
+          queryCostPerMonth,
+          totalCost,
+          months,
+        });
+      }
+
+      // Strategy 2: Asymmetric — user-specified doc+query combo
+      const asymDocCost = (docTotalTokens / 1e6) * docModel.pricePerMToken;
+      const asymQueryCostPerMonth = (queryTotalTokensPerMonth / 1e6) * queryModel.pricePerMToken;
+      const asymTotalCost = asymDocCost + (asymQueryCostPerMonth * months);
+      strategies.push({
+        name: `Asymmetric: ${docModel.name} docs + ${queryModel.name} queries`,
+        type: 'asymmetric',
+        docModel: docModel.name,
+        queryModel: queryModel.name,
+        docCost: asymDocCost,
+        queryCostPerMonth: asymQueryCostPerMonth,
+        totalCost: asymTotalCost,
+        months,
+        recommended: true,
+      });
+
+      // Strategy 3: Asymmetric with nano queries (if doc model isn't nano)
+      if (opts.queryModel !== 'voyage-4-nano') {
+        const nanoModel = MODEL_CATALOG.find(m => m.name === 'voyage-4-nano');
+        if (nanoModel) {
+          strategies.push({
+            name: `Asymmetric: ${docModel.name} docs + voyage-4-nano queries (local)`,
+            type: 'asymmetric-local',
+            docModel: docModel.name,
+            queryModel: 'voyage-4-nano',
+            docCost: asymDocCost,
+            queryCostPerMonth: 0,
+            totalCost: asymDocCost,
+            months,
+          });
+        }
+      }
+
+      // Sort by total cost
+      strategies.sort((a, b) => a.totalCost - b.totalCost);
+
+      if (opts.json) {
+        console.log(JSON.stringify({
+          params: { docs: numDocs, queries: numQueries, docTokens, queryTokens, months },
+          strategies,
+        }, null, 2));
+        return;
+      }
+
+      // Find the most expensive for savings comparison
+      const maxCost = Math.max(...strategies.map(s => s.totalCost));
+
+      if (!opts.quiet) {
+        console.log(ui.bold('💰 Voyage AI Cost Estimator'));
+        console.log('');
+        console.log(ui.label('Documents', `${shortNum(numDocs)} × ${formatNum(docTokens)} tokens = ${shortNum(docTotalTokens)} tokens (one-time)`));
+        console.log(ui.label('Queries', `${shortNum(numQueries)}/mo × ${formatNum(queryTokens)} tokens = ${shortNum(queryTotalTokensPerMonth)} tokens/mo`));
+        console.log(ui.label('Projection', `${months} months`));
+        console.log('');
+      }
+
+      console.log(ui.bold('Strategy Comparison:'));
+      console.log('');
+
+      for (const s of strategies) {
+        const savings = maxCost > 0 ? ((1 - s.totalCost / maxCost) * 100) : 0;
+        const savingsStr = savings > 0 ? ui.green(` (${savings.toFixed(0)}% savings)`) : '';
+        const marker = s.recommended ? ui.cyan(' ★ recommended') : '';
+        const localNote = s.type === 'asymmetric-local' ? ui.dim(' (query cost = $0, runs locally)') : '';
+
+        console.log(`  ${s.recommended ? ui.cyan('►') : ' '} ${ui.bold(s.name)}${marker}`);
+        console.log(`    Doc embedding:  ${formatDollars(s.docCost)} ${ui.dim('(one-time)')}`);
+        console.log(`    Query cost:     ${formatDollars(s.queryCostPerMonth)}/mo${localNote}`);
+        console.log(`    ${months}-mo total:    ${ui.bold(formatDollars(s.totalCost))}${savingsStr}`);
+        console.log('');
+      }
+
+      // Show the asymmetric advantage
+      const symmetricLarge = strategies.find(s => s.type === 'symmetric' && s.docModel === 'voyage-4-large');
+      const asymmetric = strategies.find(s => s.recommended);
+      if (symmetricLarge && asymmetric && symmetricLarge.totalCost > asymmetric.totalCost) {
+        const saved = symmetricLarge.totalCost - asymmetric.totalCost;
+        const pct = ((saved / symmetricLarge.totalCost) * 100).toFixed(0);
+        console.log(ui.success(`Asymmetric retrieval saves ${formatDollars(saved)} (${pct}%) over symmetric voyage-4-large`));
+        console.log(ui.dim('  Same document quality — lower query costs. Shared embedding space makes this possible.'));
+        console.log('');
+      }
+
+      if (!opts.quiet) {
+        console.log(ui.dim('Tip: Use --doc-model and --query-model to compare any combination.'));
+        console.log(ui.dim('     Use "vai explain shared-space" to learn about asymmetric retrieval.'));
+      }
+    });
+}
+
+module.exports = { registerEstimate };

package/src/commands/models.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { MODEL_CATALOG } = require('../lib/catalog');
+const { MODEL_CATALOG, BENCHMARK_SCORES } = require('../lib/catalog');
 const { getApiBase } = require('../lib/api');
 const { formatTable } = require('../lib/format');
 const ui = require('../lib/ui');
@@ -42,6 +42,7 @@ function registerModels(program) {
     .option('-t, --type <type>', 'Filter by type: embedding, reranking, or all', 'all')
     .option('-a, --all', 'Show all models including legacy')
     .option('-w, --wide', 'Wide output (show all columns untruncated)')
+    .option('-b, --benchmarks', 'Show RTEB benchmark scores')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action((opts) => {
@@ -86,7 +87,9 @@ function registerModels(program) {
         const name = ui.cyan(m.name);
         const type = m.type.startsWith('embedding') ? ui.green(m.type) : ui.yellow(m.type);
         const price = ui.dim(m.price);
-        return [name, type, m.context, m.dimensions, price, m.bestFor];
+        const arch = m.architecture ? (m.architecture === 'moe' ? ui.cyan('MoE') : m.architecture) : '—';
+        const space = m.sharedSpace ? ui.green('✓ ' + m.sharedSpace) : '—';
+        return [name, type, m.context, m.dimensions, arch, space, price, m.bestFor];
       };
 
       const formatCompactRow = (m) => {
@@ -98,7 +101,7 @@ function registerModels(program) {
       };
 
       if (opts.wide) {
-        const headers = ['Model', 'Type', 'Context', 'Dimensions', 'Price', 'Best For'];
+        const headers = ['Model', 'Type', 'Context', 'Dimensions', 'Arch', 'Space', 'Price', 'Best For'];
         const boldHeaders = headers.map(h => ui.bold(h));
         const rows = displayCurrent.map(formatWideRow);
         console.log(formatTable(boldHeaders, rows));
@@ -123,6 +126,29 @@ function registerModels(program) {
         }
       }
 
+      // Show benchmark scores if requested
+      if (opts.benchmarks) {
+        console.log('');
+        console.log(ui.bold('RTEB Benchmark Scores (NDCG@10, avg 29 datasets)'));
+        console.log(ui.dim('Source: Voyage AI, January 2026'));
+        console.log('');
+
+        const maxScore = Math.max(...BENCHMARK_SCORES.map(b => b.score));
+        const barWidth = 30;
+
+        for (const b of BENCHMARK_SCORES) {
+          const barLen = Math.round((b.score / maxScore) * barWidth);
+          const bar = '█'.repeat(barLen) + '░'.repeat(barWidth - barLen);
+          const isVoyage = b.provider === 'Voyage AI';
+          const name = isVoyage ? ui.cyan(b.model.padEnd(22)) : ui.dim(b.model.padEnd(22));
+          const score = isVoyage ? ui.bold(b.score.toFixed(2)) : b.score.toFixed(2);
+          const colorBar = isVoyage ? ui.cyan(bar) : ui.dim(bar);
+          console.log(`  ${name} ${colorBar} ${score}`);
+        }
+        console.log('');
+        console.log(ui.dim('  Run "vai explain rteb" for details.'));
+      }
+
       if (!opts.quiet) {
         console.log('');
         if (!opts.wide) {
@@ -130,7 +156,9 @@ function registerModels(program) {
         }
         console.log(ui.dim('Free tier: 200M tokens (most models), 50M (domain-specific)'));
         console.log(ui.dim('All 4-series models share the same embedding space.'));
-        if (!opts.wide) {
+        if (!opts.wide && !opts.benchmarks) {
+          console.log(ui.dim('Use --wide for full details, --benchmarks for RTEB scores.'));
+        } else if (!opts.wide) {
           console.log(ui.dim('Use --wide for full details.'));
         }
       }

package/src/lib/catalog.js

@@ -24,29 +24,51 @@ function getDefaultDimensions() {
 
 // The model catalog: like a wine list (I don't drink :-P), except every choice
 // leads to vectors instead of regret.
-/** @type {Array<{name: string, type: string, context: string, dimensions: string, price: string, bestFor: string}>} */
+/** @type {Array<{name: string, type: string, context: string, dimensions: string, price: string, bestFor: string, family?: string, architecture?: string, sharedSpace?: string, huggingface?: string, pricePerMToken?: number, rtebScore?: number}>} */
 const MODEL_CATALOG = [
-  { name: 'voyage-4-large', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/1M tokens', bestFor: 'Best quality, multilingual', shortFor: 'Best quality' },
-  { name: 'voyage-4', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.06/1M tokens', bestFor: 'Balanced quality/perf', shortFor: 'Balanced' },
-  { name: 'voyage-4-lite', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.02/1M tokens', bestFor: 'Lowest cost', shortFor: 'Budget' },
-  { name: 'voyage-code-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Code retrieval', shortFor: 'Code' },
-  { name: 'voyage-finance-2', type: 'embedding', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Finance', shortFor: 'Finance' },
-  { name: 'voyage-law-2', type: 'embedding', context: '16K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Legal', shortFor: 'Legal' },
-  { name: 'voyage-context-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Contextualized chunks', shortFor: 'Context chunks', unreleased: true },
+  { name: 'voyage-4-large', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/1M tokens', pricePerMToken: 0.12, bestFor: 'Best quality, multilingual, MoE', shortFor: 'Best quality', family: 'voyage-4', architecture: 'moe', sharedSpace: 'voyage-4', rtebScore: 71.41 },
+  { name: 'voyage-4', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.06/1M tokens', pricePerMToken: 0.06, bestFor: 'Balanced quality/perf', shortFor: 'Balanced', family: 'voyage-4', architecture: 'dense', sharedSpace: 'voyage-4', rtebScore: 70.07 },
+  { name: 'voyage-4-lite', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.02/1M tokens', pricePerMToken: 0.02, bestFor: 'Lowest cost', shortFor: 'Budget', family: 'voyage-4', architecture: 'dense', sharedSpace: 'voyage-4', rtebScore: 68.10 },
+  { name: 'voyage-code-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', pricePerMToken: 0.18, bestFor: 'Code retrieval', shortFor: 'Code' },
+  { name: 'voyage-finance-2', type: 'embedding', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', pricePerMToken: 0.12, bestFor: 'Finance', shortFor: 'Finance' },
+  { name: 'voyage-law-2', type: 'embedding', context: '16K', dimensions: '1024', price: '$0.12/1M tokens', pricePerMToken: 0.12, bestFor: 'Legal', shortFor: 'Legal' },
+  { name: 'voyage-context-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', pricePerMToken: 0.18, bestFor: 'Contextualized chunks', shortFor: 'Context chunks', unreleased: true },
   { name: 'voyage-multimodal-3.5', type: 'embedding-multimodal', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/M + $0.60/B px', bestFor: 'Text + images + video', shortFor: 'Multimodal', multimodal: true },
-  { name: 'rerank-2.5', type: 'reranking', context: '32K', dimensions: '—', price: '$0.05/1M tokens', bestFor: 'Best quality reranking', shortFor: 'Best reranker' },
-  { name: 'rerank-2.5-lite', type: 'reranking', context: '32K', dimensions: '—', price: '$0.02/1M tokens', bestFor: 'Fast reranking', shortFor: 'Fast reranker' },
-  { name: 'voyage-4-nano', type: 'embedding', context: '32K', dimensions: '512 (default), 128, 256', price: 'Open-weight', bestFor: 'Open-weight / edge', shortFor: 'Open / edge', local: true },
+  { name: 'rerank-2.5', type: 'reranking', context: '32K', dimensions: '—', price: '$0.05/1M tokens', pricePerMToken: 0.05, bestFor: 'Best quality reranking', shortFor: 'Best reranker' },
+  { name: 'rerank-2.5-lite', type: 'reranking', context: '32K', dimensions: '—', price: '$0.02/1M tokens', pricePerMToken: 0.02, bestFor: 'Fast reranking', shortFor: 'Fast reranker' },
+  { name: 'voyage-4-nano', type: 'embedding', context: '32K', dimensions: '512 (default), 128, 256', price: 'Open-weight (free)', pricePerMToken: 0, bestFor: 'Open-weight / edge / local', shortFor: 'Open / edge', local: true, family: 'voyage-4', architecture: 'dense', sharedSpace: 'voyage-4', huggingface: 'https://huggingface.co/voyageai/voyage-4-nano', rtebScore: null },
   // Legacy models
-  { name: 'voyage-3-large', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Previous gen quality', shortFor: 'Previous gen quality', legacy: true },
-  { name: 'voyage-3.5', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.06/1M tokens', bestFor: 'Previous gen balanced', shortFor: 'Previous gen balanced', legacy: true },
-  { name: 'voyage-3.5-lite', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.02/1M tokens', bestFor: 'Previous gen budget', shortFor: 'Previous gen budget', legacy: true },
-  { name: 'voyage-code-2', type: 'embedding', context: '16K', dimensions: '1536', price: '$0.12/1M tokens', bestFor: 'Legacy code', shortFor: 'Legacy code', legacy: true },
-  { name: 'voyage-multimodal-3', type: 'embedding-multimodal', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Legacy multimodal', shortFor: 'Legacy multimodal', legacy: true, multimodal: true },
-  { name: 'rerank-2', type: 'reranking', context: '16K', dimensions: '—', price: '$0.05/1M tokens', bestFor: 'Legacy reranker', shortFor: 'Legacy reranker', legacy: true },
-  { name: 'rerank-2-lite', type: 'reranking', context: '8K', dimensions: '—', price: '$0.02/1M tokens', bestFor: 'Legacy fast reranker', shortFor: 'Legacy fast reranker', legacy: true },
+  { name: 'voyage-3-large', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', pricePerMToken: 0.18, bestFor: 'Previous gen quality', shortFor: 'Previous gen quality', legacy: true, rtebScore: null },
+  { name: 'voyage-3.5', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.06/1M tokens', pricePerMToken: 0.06, bestFor: 'Previous gen balanced', shortFor: 'Previous gen balanced', legacy: true, rtebScore: null },
+  { name: 'voyage-3.5-lite', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.02/1M tokens', pricePerMToken: 0.02, bestFor: 'Previous gen budget', shortFor: 'Previous gen budget', legacy: true, rtebScore: null },
+  { name: 'voyage-code-2', type: 'embedding', context: '16K', dimensions: '1536', price: '$0.12/1M tokens', pricePerMToken: 0.12, bestFor: 'Legacy code', shortFor: 'Legacy code', legacy: true },
+  { name: 'voyage-multimodal-3', type: 'embedding-multimodal', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', pricePerMToken: 0.12, bestFor: 'Legacy multimodal', shortFor: 'Legacy multimodal', legacy: true, multimodal: true },
+  { name: 'rerank-2', type: 'reranking', context: '16K', dimensions: '—', price: '$0.05/1M tokens', pricePerMToken: 0.05, bestFor: 'Legacy reranker', shortFor: 'Legacy reranker', legacy: true },
+  { name: 'rerank-2-lite', type: 'reranking', context: '8K', dimensions: '—', price: '$0.02/1M tokens', pricePerMToken: 0.02, bestFor: 'Legacy fast reranker', shortFor: 'Legacy fast reranker', legacy: true },
 ];
 
+/**
+ * RTEB benchmark scores for competitive models (NDCG@10 average across 29 datasets).
+ * Source: Voyage AI blog, January 15 2026.
+ */
+const BENCHMARK_SCORES = [
+  { model: 'voyage-4-large', provider: 'Voyage AI', score: 71.41 },
+  { model: 'voyage-4', provider: 'Voyage AI', score: 70.07 },
+  { model: 'voyage-4-lite', provider: 'Voyage AI', score: 68.10 },
+  { model: 'Gemini Embedding 001', provider: 'Google', score: 68.66 },
+  { model: 'Cohere Embed v4', provider: 'Cohere', score: 65.75 },
+  { model: 'OpenAI v3 Large', provider: 'OpenAI', score: 62.57 },
+];
+
+/**
+ * Get models that share an embedding space.
+ * @param {string} space - e.g. 'voyage-4'
+ * @returns {Array}
+ */
+function getSharedSpaceModels(space) {
+  return MODEL_CATALOG.filter(m => m.sharedSpace === space);
+}
+
 module.exports = {
   DEFAULT_EMBED_MODEL,
   DEFAULT_RERANK_MODEL,
@@ -54,4 +76,6 @@ module.exports = {
   getDefaultModel,
   getDefaultDimensions,
   MODEL_CATALOG,
+  BENCHMARK_SCORES,
+  getSharedSpaceModels,
 };

package/src/lib/explanations.js

@@ -513,6 +513,169 @@ const concepts = {
       'vai benchmark similarity --query "your search query" --file your-docs.txt',
     ],
   },
+  'mixture-of-experts': {
+    title: 'Mixture-of-Experts (MoE) Architecture',
+    summary: 'How voyage-4-large achieves SOTA quality at 40% lower cost',
+    content: [
+      `${pc.cyan('Mixture-of-Experts (MoE)')} is a neural network architecture where multiple`,
+      `specialized sub-networks ("experts") share a single model. A learned ${pc.cyan('router')}`,
+      `selects which experts activate for each input — typically 2-4 out of 8-64 total.`,
+      ``,
+      `${pc.bold('Why MoE matters for embeddings:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('Higher capacity, lower cost')} — the model has more total parameters`,
+      `    (knowledge) but only activates a fraction per input, keeping inference fast`,
+      `  ${pc.dim('•')} ${pc.cyan('Specialization')} — different experts learn different domains (code,`,
+      `    legal, medical) without interfering with each other`,
+      `  ${pc.dim('•')} ${pc.cyan('State-of-the-art quality')} — voyage-4-large beats all competitors on`,
+      `    RTEB benchmarks while costing 40% less than comparable dense models`,
+      ``,
+      `${pc.bold('voyage-4-large')} is the ${pc.cyan('first production-grade embedding model')} to use MoE.`,
+      `Previous MoE successes (Mixtral, Switch Transformer) were language models —`,
+      `applying MoE to embedding models required solving alignment across the shared`,
+      `embedding space, which is what makes the Voyage 4 family unique.`,
+      ``,
+      `${pc.bold('Dense vs MoE:')}`,
+      `  ${pc.dim('Dense (voyage-4, voyage-4-lite):')} Every parameter is used for every input.`,
+      `    Simpler, predictable latency, lower total parameter count.`,
+      `  ${pc.dim('MoE (voyage-4-large):')} Sparse activation — more total parameters, but each`,
+      `    input only uses a subset. Higher quality ceiling, similar serving cost.`,
+      ``,
+      `${pc.bold('In practice:')} You don't need to do anything special to use MoE — the API`,
+      `interface is identical. The architecture difference shows up in quality and cost:`,
+      `  ${pc.dim('•')} voyage-4-large: $0.12/1M tokens — better quality than voyage-3-large ($0.18/1M)`,
+      `  ${pc.dim('•')} 40% cheaper than comparable dense models at the same quality tier`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+      'https://www.mongodb.com/docs/voyageai/models/text-embeddings/',
+    ],
+    tryIt: [
+      'vai embed "test MoE quality" --model voyage-4-large',
+      'vai benchmark embed --models voyage-4-large,voyage-4,voyage-4-lite',
+      'vai models --wide',
+    ],
+  },
+
+  'shared-embedding-space': {
+    title: 'Shared Embedding Space',
+    summary: 'How Voyage 4 models produce compatible, interchangeable embeddings',
+    content: [
+      `The Voyage 4 series introduces an ${pc.cyan('industry-first capability')}: all four models`,
+      `(voyage-4-large, voyage-4, voyage-4-lite, voyage-4-nano) produce embeddings in`,
+      `the ${pc.cyan('same vector space')}. Embeddings from different models are directly comparable.`,
+      ``,
+      `${pc.bold('What this means:')}`,
+      `  ${pc.dim('•')} Embed documents with ${pc.cyan('voyage-4-large')} (best quality, one-time cost)`,
+      `  ${pc.dim('•')} Query with ${pc.cyan('voyage-4-lite')} or ${pc.cyan('voyage-4-nano')} (low cost, high volume)`,
+      `  ${pc.dim('•')} Cosine similarity works across model boundaries`,
+      `  ${pc.dim('•')} Upgrade query model later ${pc.cyan('without re-vectorizing documents')}`,
+      ``,
+      `${pc.bold('Why this is new:')} Previously, embeddings from different models lived in`,
+      `incompatible vector spaces. Switching models meant re-embedding your entire`,
+      `corpus — expensive and slow. The shared space eliminates this constraint.`,
+      ``,
+      `${pc.bold('Recommended workflow:')}`,
+      `  ${pc.dim('1.')} Vectorize your document corpus once with ${pc.cyan('voyage-4-large')}`,
+      `  ${pc.dim('2.')} Start with ${pc.cyan('voyage-4-lite')} for queries in development / early production`,
+      `  ${pc.dim('3.')} Upgrade to ${pc.cyan('voyage-4')} or ${pc.cyan('voyage-4-large')} as accuracy needs grow`,
+      `  ${pc.dim('4.')} No re-vectorization needed at any step`,
+      ``,
+      `${pc.bold('Validate it yourself:')} Use ${pc.cyan('vai benchmark space')} to embed identical text`,
+      `with all Voyage 4 models and see the cross-model cosine similarities.`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+    ],
+    tryIt: [
+      'vai benchmark space',
+      'vai benchmark asymmetric --query "your search" --file corpus.txt',
+      'vai estimate --docs 1M --queries 10M',
+    ],
+  },
+
+  'rteb-benchmarks': {
+    title: 'RTEB Benchmark Scores',
+    summary: 'Retrieval quality scores across embedding providers',
+    content: [
+      `The ${pc.cyan('Retrieval Embedding Benchmark (RTEB)')} evaluates general-purpose retrieval`,
+      `quality across 29 diverse datasets. Scores are ${pc.cyan('NDCG@10')} (normalized discounted`,
+      `cumulative gain at top 10 results) — higher is better.`,
+      ``,
+      `${pc.bold('Current standings (Jan 2026):')}`,
+      `  ${pc.cyan('voyage-4-large')}       ${pc.bold('71.41')}  ${pc.dim('— SOTA, MoE architecture')}`,
+      `  ${pc.cyan('voyage-4')}             ${pc.bold('70.07')}  ${pc.dim('— near voyage-3-large quality')}`,
+      `  ${pc.cyan('Gemini Embedding 001')} ${pc.bold('68.66')}  ${pc.dim('— Google')}`,
+      `  ${pc.cyan('voyage-4-lite')}        ${pc.bold('68.10')}  ${pc.dim('— near voyage-3.5 quality')}`,
+      `  ${pc.cyan('Cohere Embed v4')}      ${pc.bold('65.75')}  ${pc.dim('— Cohere')}`,
+      `  ${pc.cyan('OpenAI v3 Large')}      ${pc.bold('62.57')}  ${pc.dim('— OpenAI')}`,
+      ``,
+      `${pc.bold('What the numbers mean:')}`,
+      `  ${pc.dim('•')} voyage-4-large beats Gemini by ${pc.cyan('3.87%')}, Cohere by ${pc.cyan('8.20%')}, OpenAI by ${pc.cyan('14.05%')}`,
+      `  ${pc.dim('•')} voyage-4 (mid-tier pricing) outperforms all non-Voyage models`,
+      `  ${pc.dim('•')} Even voyage-4-lite ($0.02/1M) is competitive with Gemini Embedding`,
+      ``,
+      `${pc.bold('Asymmetric retrieval bonus:')} When documents are embedded with voyage-4-large`,
+      `and queries with a smaller Voyage 4 model, retrieval quality ${pc.cyan('improves')} over`,
+      `using the smaller model alone — you get the benefit of the larger model's`,
+      `document representations.`,
+      ``,
+      `${pc.bold('Note:')} These scores are from Voyage AI's evaluation. Independent benchmarks`,
+      `may differ. Always test on your own data with ${pc.cyan('vai benchmark similarity')}.`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+      'https://docs.google.com/spreadsheets/d/1GfPkqCAjPKaGS9f66IDhMRxVpd2bMuqL2wXjj-kNS7E/',
+    ],
+    tryIt: [
+      'vai models --benchmarks',
+      'vai benchmark similarity --query "your query" --file your-docs.txt',
+      'vai estimate --docs 1M --queries 10M',
+    ],
+  },
+
+  'voyage-4-nano': {
+    title: 'voyage-4-nano — Open-Weight Local Model',
+    summary: 'Free, local-first embeddings with shared space compatibility',
+    content: [
+      `${pc.cyan('voyage-4-nano')} is Voyage AI's first ${pc.cyan('open-weight')} embedding model, freely`,
+      `available on Hugging Face under the ${pc.bold('Apache 2.0')} license.`,
+      ``,
+      `${pc.bold('Key specs:')}`,
+      `  ${pc.dim('•')} Dimensions: 512 (default), 128, 256`,
+      `  ${pc.dim('•')} Context: 32K tokens`,
+      `  ${pc.dim('•')} License: Apache 2.0 (fully open)`,
+      `  ${pc.dim('•')} Shared space: Compatible with voyage-4-large/4/4-lite embeddings`,
+      ``,
+      `${pc.bold('Use cases:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('Local development')} — no API key, no network, no cost`,
+      `  ${pc.dim('•')} ${pc.cyan('Prototyping')} — fast iteration before committing to API models`,
+      `  ${pc.dim('•')} ${pc.cyan('Edge/on-device')} — run inference on your own hardware`,
+      `  ${pc.dim('•')} ${pc.cyan('Asymmetric queries')} — use nano for queries against voyage-4-large docs`,
+      ``,
+      `${pc.bold('Getting started with Hugging Face:')}`,
+      `  ${pc.dim('pip install sentence-transformers')}`,
+      `  ${pc.dim('from sentence_transformers import SentenceTransformer')}`,
+      `  ${pc.dim('model = SentenceTransformer("voyageai/voyage-4-nano")')}`,
+      `  ${pc.dim('embeddings = model.encode(["your text here"])')}`,
+      ``,
+      `${pc.bold('With the Voyage API:')} voyage-4-nano is also available via the standard API`,
+      `endpoint, so you can use ${pc.cyan('vai embed --model voyage-4-nano')} for testing before`,
+      `switching to local inference.`,
+      ``,
+      `${pc.bold('Shared space advantage:')} Since nano shares the same embedding space as the`,
+      `larger Voyage 4 models, you can prototype locally with nano, then seamlessly`,
+      `use the same document embeddings with voyage-4 or voyage-4-large in production.`,
+    ].join('\n'),
+    links: [
+      'https://huggingface.co/voyageai/voyage-4-nano',
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+    ],
+    tryIt: [
+      'vai embed "test nano" --model voyage-4-nano',
+      'vai benchmark space',
+      'vai benchmark asymmetric --doc-model voyage-4-large --query-models voyage-4-nano',
+    ],
+  },
 };
 
 /**
@@ -567,6 +730,26 @@ const aliases = {
   'model-selection': 'benchmarking',
   choosing: 'benchmarking',
   compare: 'benchmarking',
+  moe: 'mixture-of-experts',
+  'mixture-of-experts': 'mixture-of-experts',
+  'moe-architecture': 'mixture-of-experts',
+  experts: 'mixture-of-experts',
+  sparse: 'mixture-of-experts',
+  'shared-space': 'shared-embedding-space',
+  'shared-embedding-space': 'shared-embedding-space',
+  'embedding-space': 'shared-embedding-space',
+  interchangeable: 'shared-embedding-space',
+  compatible: 'shared-embedding-space',
+  rteb: 'rteb-benchmarks',
+  'rteb-benchmarks': 'rteb-benchmarks',
+  ndcg: 'rteb-benchmarks',
+  scores: 'rteb-benchmarks',
+  leaderboard: 'rteb-benchmarks',
+  nano: 'voyage-4-nano',
+  'voyage-4-nano': 'voyage-4-nano',
+  'open-weight': 'voyage-4-nano',
+  huggingface: 'voyage-4-nano',
+  local: 'voyage-4-nano',
 };
 
 /**