voyageai-cli 1.3.0 → 1.5.0

package/src/commands/similarity.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const fs = require('fs');
+const { generateEmbeddings } = require('../lib/api');
+const { cosineSimilarity } = require('../lib/math');
+const { getDefaultModel } = require('../lib/catalog');
+const ui = require('../lib/ui');
+
+/**
+ * Register the similarity command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerSimilarity(program) {
+  program
+    .command('similarity')
+    .description('Compute cosine similarity between texts')
+    .argument('[texts...]', 'Two texts to compare')
+    .option('--against <texts...>', 'Compare first text against multiple texts')
+    .option('--file1 <path>', 'Read text A from file')
+    .option('--file2 <path>', 'Read text B from file')
+    .option('-m, --model <model>', 'Embedding model', getDefaultModel())
+    .option('--dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (texts, opts) => {
+      try {
+        let textA = null;
+        let compareTexts = [];
+        let isOneVsMany = false;
+
+        // Resolve text A
+        if (opts.file1) {
+          textA = fs.readFileSync(opts.file1, 'utf-8').trim();
+        } else if (texts.length > 0) {
+          textA = texts[0];
+        }
+
+        // Resolve comparison targets
+        if (opts.against && opts.against.length > 0) {
+          // One-vs-many mode
+          isOneVsMany = true;
+          compareTexts = opts.against;
+        } else if (opts.file2) {
+          compareTexts = [fs.readFileSync(opts.file2, 'utf-8').trim()];
+        } else if (texts.length >= 2) {
+          compareTexts = [texts[1]];
+        }
+
+        // Validate inputs
+        if (!textA) {
+          console.error(ui.error('No input text provided. Provide two texts, use --file1/--file2, or use --against.'));
+          process.exit(1);
+        }
+
+        if (compareTexts.length === 0) {
+          console.error(ui.error('Need at least two texts to compare. Provide a second text, --file2, or --against.'));
+          process.exit(1);
+        }
+
+        // Batch all texts into one API call
+        const allTexts = [textA, ...compareTexts];
+
+        const useSpinner = !opts.json && !opts.quiet;
+        let spin;
+        if (useSpinner) {
+          spin = ui.spinner('Computing similarity...');
+          spin.start();
+        }
+
+        const embeddingOpts = {
+          model: opts.model,
+        };
+        if (opts.dimensions) {
+          embeddingOpts.dimensions = opts.dimensions;
+        }
+        // Don't set inputType — we're comparing directly, not query/document
+
+        const result = await generateEmbeddings(allTexts, embeddingOpts);
+
+        if (spin) spin.stop();
+
+        const embeddings = result.data.map(d => d.embedding);
+        const tokens = result.usage?.total_tokens || 0;
+        const model = result.model || opts.model;
+
+        const refEmbedding = embeddings[0];
+
+        if (!isOneVsMany && compareTexts.length === 1) {
+          // Two-text comparison
+          const sim = cosineSimilarity(refEmbedding, embeddings[1]);
+
+          if (opts.json) {
+            console.log(JSON.stringify({
+              similarity: sim,
+              metric: 'cosine',
+              textA,
+              textB: compareTexts[0],
+              model,
+              tokens,
+            }, null, 2));
+            return;
+          }
+
+          if (opts.quiet) {
+            console.log(sim.toFixed(6));
+            return;
+          }
+
+          console.log('');
+          console.log(`  Similarity: ${ui.score(sim)} (cosine)`);
+          console.log('');
+          console.log(ui.label('Text A', `"${truncate(textA, 70)}"`));
+          console.log(ui.label('Text B', `"${truncate(compareTexts[0], 70)}"`));
+          console.log(ui.label('Model', ui.cyan(model)));
+          console.log(ui.label('Tokens', ui.dim(String(tokens))));
+          console.log('');
+        } else {
+          // One-vs-many comparison
+          const results = compareTexts.map((text, i) => ({
+            text,
+            similarity: cosineSimilarity(refEmbedding, embeddings[i + 1]),
+          }));
+
+          // Sort by similarity descending
+          results.sort((a, b) => b.similarity - a.similarity);
+
+          if (opts.json) {
+            console.log(JSON.stringify({
+              query: textA,
+              results,
+              model,
+              tokens,
+            }, null, 2));
+            return;
+          }
+
+          if (opts.quiet) {
+            for (const r of results) {
+              console.log(`${r.similarity.toFixed(6)}\t"${truncate(r.text, 60)}"`);
+            }
+            return;
+          }
+
+          console.log('');
+          console.log(`  Query: ${ui.cyan(`"${truncate(textA, 60)}"`)}`);
+          console.log(`  Model: ${ui.cyan(model)}`);
+          console.log('');
+
+          for (const r of results) {
+            console.log(`  ${ui.score(r.similarity)}  "${truncate(r.text, 60)}"`);
+          }
+
+          console.log('');
+          console.log(`  ${ui.dim(`${results.length} comparisons, ${tokens} tokens`)}`);
+          console.log('');
+        }
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Truncate a string to maxLen, appending '...' if truncated.
+ * @param {string} str
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.substring(0, maxLen) + '...';
+}
+
+module.exports = { registerSimilarity };

package/src/lib/api.js

@@ -1,8 +1,32 @@
 'use strict';
 
-const API_BASE = 'https://ai.mongodb.com/v1';
+const ATLAS_API_BASE = 'https://ai.mongodb.com/v1';
+const VOYAGE_API_BASE = 'https://api.voyageai.com/v1';
 const MAX_RETRIES = 3;
 
+/**
+ * Resolve the API base URL.
+ * Priority: VOYAGE_API_BASE env → config baseUrl → auto-detect from key prefix.
+ * Keys starting with 'pa-' that work on Voyage platform use VOYAGE_API_BASE.
+ * @returns {string}
+ */
+function getApiBase() {
+  const { getConfigValue } = require('./config');
+
+  // Explicit override wins
+  const envBase = process.env.VOYAGE_API_BASE;
+  if (envBase) return envBase.replace(/\/+$/, '');
+
+  const configBase = getConfigValue('baseUrl');
+  if (configBase) return configBase.replace(/\/+$/, '');
+
+  // Default to Atlas endpoint
+  return ATLAS_API_BASE;
+}
+
+// Legacy export for backward compat
+const API_BASE = ATLAS_API_BASE;
+
 /**
  * Get the Voyage API key or exit with a helpful error.
  * Checks: env var → config file.
@@ -18,6 +42,7 @@ function requireApiKey() {
     console.error('Option 2: vai config set api-key <your-key>');
     console.error('');
     console.error('Get one from MongoDB Atlas → AI Models → Create model API key');
+    console.error('       or Voyage AI platform → Dashboard → API Keys');
     process.exit(1);
   }
   return key;
@@ -40,7 +65,8 @@ function sleep(ms) {
  */
 async function apiRequest(endpoint, body) {
   const apiKey = requireApiKey();
-  const url = `${API_BASE}${endpoint}`;
+  const base = getApiBase();
+  const url = `${base}${endpoint}`;
 
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
     const response = await fetch(url, {
@@ -69,6 +95,23 @@ async function apiRequest(endpoint, body) {
         errorDetail = await response.text();
       }
       console.error(`API Error (${response.status}): ${errorDetail}`);
+
+      // Help users diagnose endpoint mismatch
+      if (response.status === 403 && base === ATLAS_API_BASE) {
+        console.error('');
+        console.error('Hint: 403 on ai.mongodb.com often means your key is for the Voyage AI');
+        console.error('platform, not MongoDB Atlas. Try switching the base URL:');
+        console.error('');
+        console.error('  vai config set base-url https://api.voyageai.com/v1/');
+        console.error('');
+        console.error('Or set VOYAGE_API_BASE=https://api.voyageai.com/v1/ in your environment.');
+      } else if (response.status === 401 && base === VOYAGE_API_BASE) {
+        console.error('');
+        console.error('Hint: 401 on api.voyageai.com may mean your key is an Atlas AI key.');
+        console.error('Try switching back:');
+        console.error('');
+        console.error('  vai config set base-url https://ai.mongodb.com/v1/');
+      }
       process.exit(1);
     }
 
@@ -105,6 +148,9 @@ async function generateEmbeddings(texts, options = {}) {
 
 module.exports = {
   API_BASE,
+  ATLAS_API_BASE,
+  VOYAGE_API_BASE,
+  getApiBase,
   requireApiKey,
   apiRequest,
   generateEmbeddings,

package/src/lib/banner.js

@@ -35,6 +35,7 @@ function showBanner() {
   console.log(titleLine);
   console.log(taglineLine);
   console.log(bot);
+  console.log(pc.dim('  Community tool — not an official MongoDB or Voyage AI product'));
   console.log('');
 }
 

package/src/lib/catalog.js

@@ -24,16 +24,16 @@ function getDefaultDimensions() {
 
 /** @type {Array<{name: string, type: string, context: string, dimensions: string, price: string, bestFor: string}>} */
 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' },
-  { name: 'voyage-4', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.06/1M tokens', bestFor: 'Balanced quality/perf' },
-  { name: 'voyage-4-lite', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.02/1M tokens', bestFor: 'Lowest cost' },
-  { name: 'voyage-code-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Code retrieval' },
-  { name: 'voyage-finance-2', type: 'embedding', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Finance' },
-  { name: 'voyage-law-2', type: 'embedding', context: '16K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Legal' },
-  { name: 'voyage-context-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Contextualized chunks' },
-  { name: 'voyage-multimodal-3.5', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/M + $0.60/B px', bestFor: 'Text + images + video' },
-  { name: 'rerank-2.5', type: 'reranking', context: '32K', dimensions: '—', price: '$0.05/1M tokens', bestFor: 'Best quality reranking' },
-  { name: 'rerank-2.5-lite', type: 'reranking', context: '32K', dimensions: '—', price: '$0.02/1M tokens', bestFor: 'Fast reranking' },
+  { 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' },
+  { name: 'voyage-multimodal-3.5', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/M + $0.60/B px', bestFor: 'Text + images + video', shortFor: 'Multimodal' },
+  { 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' },
 ];
 
 module.exports = {

package/src/lib/config.js

@@ -13,6 +13,7 @@ const KEY_MAP = {
   'mongodb-uri': 'mongodbUri',
   'default-model': 'defaultModel',
   'default-dimensions': 'defaultDimensions',
+  'base-url': 'baseUrl',
 };
 
 // Keys whose values should be masked in output