voyageai-cli 1.13.0 → 1.16.0

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/init.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { MODEL_CATALOG } = require('../lib/catalog');
+const { STRATEGIES } = require('../lib/chunker');
+const { defaultProjectConfig, saveProject, findProjectFile, PROJECT_FILE } = require('../lib/project');
+const ui = require('../lib/ui');
+
+/**
+ * Prompt the user for input with a default value.
+ * @param {readline.Interface} rl
+ * @param {string} question
+ * @param {string} [defaultVal]
+ * @returns {Promise<string>}
+ */
+function ask(rl, question, defaultVal) {
+  const suffix = defaultVal ? ` ${ui.dim(`(${defaultVal})`)}` : '';
+  return new Promise((resolve) => {
+    rl.question(`  ${question}${suffix}: `, (answer) => {
+      resolve(answer.trim() || defaultVal || '');
+    });
+  });
+}
+
+/**
+ * Prompt for a choice from a list.
+ * @param {readline.Interface} rl
+ * @param {string} question
+ * @param {string[]} choices
+ * @param {string} defaultVal
+ * @returns {Promise<string>}
+ */
+async function askChoice(rl, question, choices, defaultVal) {
+  console.log('');
+  for (let i = 0; i < choices.length; i++) {
+    const marker = choices[i] === defaultVal ? ui.cyan('→') : ' ';
+    console.log(`  ${marker} ${i + 1}. ${choices[i]}`);
+  }
+  const answer = await ask(rl, question, defaultVal);
+  // Accept number or value
+  const num = parseInt(answer, 10);
+  if (num >= 1 && num <= choices.length) return choices[num - 1];
+  if (choices.includes(answer)) return answer;
+  return defaultVal;
+}
+
+/**
+ * Register the init command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerInit(program) {
+  program
+    .command('init')
+    .description('Initialize a project with .vai.json configuration')
+    .option('-y, --yes', 'Accept all defaults (non-interactive)')
+    .option('--force', 'Overwrite existing .vai.json')
+    .option('--json', 'Output created config as JSON (non-interactive)')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (opts) => {
+      // Check for existing config
+      const existing = findProjectFile();
+      if (existing && !opts.force) {
+        const relPath = path.relative(process.cwd(), existing);
+        console.error(ui.warn(`Project already initialized: ${relPath}`));
+        console.error(ui.dim('  Use --force to overwrite.'));
+        process.exit(1);
+      }
+
+      const defaults = defaultProjectConfig();
+
+      // Non-interactive mode
+      if (opts.yes || opts.json) {
+        const filePath = saveProject(defaults);
+        if (opts.json) {
+          console.log(JSON.stringify(defaults, null, 2));
+        } else if (!opts.quiet) {
+          console.log(ui.success(`Created ${PROJECT_FILE}`));
+        }
+        return;
+      }
+
+      // Interactive mode
+      console.log('');
+      console.log(ui.bold('  🚀 Initialize Voyage AI Project'));
+      console.log(ui.dim('  Creates .vai.json in the current directory.'));
+      console.log(ui.dim('  Press Enter to accept defaults.'));
+      console.log('');
+
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+
+      try {
+        // Embedding model
+        const embeddingModels = MODEL_CATALOG
+          .filter(m => m.type === 'embedding' && !m.legacy && !m.unreleased)
+          .map(m => m.name);
+        const model = await askChoice(rl, 'Embedding model', embeddingModels, defaults.model);
+
+        // MongoDB settings
+        console.log('');
+        console.log(ui.bold('  MongoDB Atlas'));
+        const db = await ask(rl, 'Database name', defaults.db || 'myapp');
+        const collection = await ask(rl, 'Collection name', defaults.collection || 'documents');
+        const field = await ask(rl, 'Embedding field', defaults.field);
+        const index = await ask(rl, 'Vector index name', defaults.index);
+
+        // Dimensions
+        const modelInfo = MODEL_CATALOG.find(m => m.name === model);
+        const defaultDims = modelInfo && modelInfo.dimensions.includes('1024') ? '1024' : '512';
+        const dimensions = parseInt(await ask(rl, 'Dimensions', defaultDims), 10) || parseInt(defaultDims, 10);
+
+        // Chunking
+        console.log('');
+        console.log(ui.bold('  Chunking'));
+        const strategy = await askChoice(rl, 'Chunk strategy', STRATEGIES, defaults.chunk.strategy);
+        const chunkSize = parseInt(await ask(rl, 'Chunk size (chars)', String(defaults.chunk.size)), 10);
+        const chunkOverlap = parseInt(await ask(rl, 'Chunk overlap (chars)', String(defaults.chunk.overlap)), 10);
+
+        const config = {
+          model,
+          db,
+          collection,
+          field,
+          inputType: 'document',
+          dimensions,
+          index,
+          chunk: {
+            strategy,
+            size: chunkSize,
+            overlap: chunkOverlap,
+          },
+        };
+
+        const filePath = saveProject(config);
+        console.log('');
+        console.log(ui.success(`Created ${path.relative(process.cwd(), filePath)}`));
+        console.log('');
+        console.log(ui.dim('  Next steps:'));
+        console.log(ui.dim('    vai chunk ./docs/           # Chunk your documents'));
+        console.log(ui.dim('    vai pipeline ./docs/        # Chunk → embed → store (coming soon)'));
+        console.log(ui.dim('    vai search --query "..."    # Search your collection'));
+        console.log('');
+      } finally {
+        rl.close();
+      }
+    });
+}
+
+module.exports = { registerInit };

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,
 };