voyageai-cli 1.5.0 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"
@@ -39,6 +39,7 @@
     "mongodb": "^6.0.0",
     "ora": "^9.1.0",
     "picocolors": "^1.1.1",
-    "update-notifier": "^7.3.1"
+    "update-notifier": "^7.3.1",
+    "voyageai-cli": "^1.6.0"
   }
 }

package/src/commands/embed.js

@@ -17,6 +17,8 @@ function registerEmbed(program) {
     .option('-t, --input-type <type>', 'Input type: query or document')
     .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
     .option('-f, --file <path>', 'Read text from file')
+    .option('--truncation', 'Enable truncation for long inputs')
+    .option('--no-truncation', 'Disable truncation')
     .option('-o, --output-format <format>', 'Output format: json or array', 'json')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
@@ -26,17 +28,29 @@ function registerEmbed(program) {
 
         const useColor = !opts.json;
         const useSpinner = useColor && !opts.quiet;
+
+        // Show hint when --input-type is not provided and output is interactive
+        if (!opts.inputType && !opts.json && !opts.quiet && process.stdout.isTTY) {
+          console.error(ui.dim('ℹ Tip: Use --input-type query or --input-type document for better retrieval accuracy.'));
+        }
+
         let spin;
         if (useSpinner) {
           spin = ui.spinner('Generating embeddings...');
           spin.start();
         }
 
-        const result = await generateEmbeddings(texts, {
+        const embedOpts = {
           model: opts.model,
           inputType: opts.inputType,
           dimensions: opts.dimensions,
-        });
+        };
+        // Only pass truncation when explicitly set via --truncation or --no-truncation
+        if (opts.truncation !== undefined) {
+          embedOpts.truncation = opts.truncation;
+        }
+
+        const result = await generateEmbeddings(texts, embedOpts);
 
         if (spin) spin.stop();
 

package/src/commands/models.js

@@ -40,16 +40,26 @@ function registerModels(program) {
     .command('models')
     .description('List available Voyage AI models')
     .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('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action((opts) => {
       let models = MODEL_CATALOG;
 
+      // Separate current and legacy models
+      const showLegacy = opts.all;
+      const currentModels = models.filter(m => !m.legacy);
+      const legacyModels = models.filter(m => m.legacy);
+
       if (opts.type !== 'all') {
         models = models.filter(m => m.type === opts.type);
       }
 
+      if (!showLegacy) {
+        models = models.filter(m => !m.legacy);
+      }
+
       if (opts.json) {
         console.log(JSON.stringify(models, null, 2));
         return;
@@ -68,29 +78,49 @@ function registerModels(program) {
         console.log('');
       }
 
+      // Split models for display
+      const displayCurrent = models.filter(m => !m.legacy);
+      const displayLegacy = models.filter(m => m.legacy);
+
+      const formatWideRow = (m) => {
+        const name = ui.cyan(m.name);
+        const type = m.type === '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 formatCompactRow = (m) => {
+        const name = ui.cyan(m.name);
+        const type = m.type === 'embedding' ? ui.green('embed') : ui.yellow('rerank');
+        const dims = compactDimensions(m.dimensions);
+        const price = ui.dim(compactPrice(m.price));
+        return [name, type, dims, price, m.shortFor || m.bestFor];
+      };
+
       if (opts.wide) {
-        // Full table with all details
         const headers = ['Model', 'Type', 'Context', 'Dimensions', 'Price', 'Best For'];
-        const rows = models.map(m => {
-          const name = ui.cyan(m.name);
-          const type = m.type === '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 boldHeaders = headers.map(h => ui.bold(h));
+        const rows = displayCurrent.map(formatWideRow);
         console.log(formatTable(boldHeaders, rows));
+
+        if (showLegacy && displayLegacy.length > 0) {
+          console.log('');
+          console.log(ui.dim('Legacy Models (use latest for better quality)'));
+          const legacyRows = displayLegacy.map(formatWideRow);
+          console.log(formatTable(boldHeaders, legacyRows));
+        }
       } else {
-        // Compact table — fits in 80 cols
         const headers = ['Model', 'Type', 'Dims', 'Price', 'Use Case'];
-        const rows = models.map(m => {
-          const name = ui.cyan(m.name);
-          const type = m.type === 'embedding' ? ui.green('embed') : ui.yellow('rerank');
-          const dims = compactDimensions(m.dimensions);
-          const price = ui.dim(compactPrice(m.price));
-          return [name, type, dims, price, m.shortFor || m.bestFor];
-        });
         const boldHeaders = headers.map(h => ui.bold(h));
+        const rows = displayCurrent.map(formatCompactRow);
         console.log(formatTable(boldHeaders, rows));
+
+        if (showLegacy && displayLegacy.length > 0) {
+          console.log('');
+          console.log(ui.dim('Legacy Models (use latest for better quality)'));
+          const legacyRows = displayLegacy.map(formatCompactRow);
+          console.log(formatTable(boldHeaders, legacyRows));
+        }
       }
 
       if (!opts.quiet) {

package/src/commands/rerank.js

@@ -18,6 +18,9 @@ function registerRerank(program) {
     .option('--documents-file <path>', 'File with documents (JSON array or newline-delimited)')
     .option('-m, --model <model>', 'Reranking model', DEFAULT_RERANK_MODEL)
     .option('-k, --top-k <n>', 'Return top K results', (v) => parseInt(v, 10))
+    .option('--truncation', 'Enable truncation for long inputs')
+    .option('--no-truncation', 'Disable truncation')
+    .option('--return-documents', 'Return document text in results')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action(async (opts) => {
@@ -76,6 +79,12 @@ function registerRerank(program) {
         if (opts.topK) {
           body.top_k = opts.topK;
         }
+        if (opts.truncation !== undefined) {
+          body.truncation = opts.truncation;
+        }
+        if (opts.returnDocuments) {
+          body.return_documents = true;
+        }
 
         const useColor = !opts.json;
         const useSpinner = useColor && !opts.quiet;
@@ -106,8 +115,9 @@ function registerRerank(program) {
 
         if (result.data) {
           for (const item of result.data) {
-            const docPreview = documents[item.index].substring(0, 80);
-            const ellipsis = documents[item.index].length > 80 ? '...' : '';
+            const docText = item.document || documents[item.index];
+            const docPreview = docText.substring(0, 80);
+            const ellipsis = docText.length > 80 ? '...' : '';
             console.log(`${ui.dim('[' + item.index + ']')} Score: ${ui.score(item.relevance_score)}  ${ui.dim('"' + docPreview + ellipsis + '"')}`);
           }
         }

package/src/lib/api.js

@@ -126,6 +126,7 @@ async function apiRequest(endpoint, body) {
  * @param {string} [options.model] - Model name
  * @param {string} [options.inputType] - Input type (query|document)
  * @param {number} [options.dimensions] - Output dimensions
+ * @param {boolean} [options.truncation] - Enable/disable truncation
  * @returns {Promise<object>} API response with embeddings
  */
 async function generateEmbeddings(texts, options = {}) {
@@ -142,6 +143,9 @@ async function generateEmbeddings(texts, options = {}) {
   if (options.dimensions) {
     body.output_dimension = options.dimensions;
   }
+  if (options.truncation !== undefined) {
+    body.truncation = options.truncation;
+  }
 
   return apiRequest('/embeddings', body);
 }

package/src/lib/catalog.js

@@ -34,6 +34,15 @@ const MODEL_CATALOG = [
   { 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' },
+  { name: 'voyage-4-nano', type: 'embedding', context: '32K', dimensions: '512 (default), 128, 256', price: 'Open-weight', bestFor: 'Open-weight / edge', shortFor: 'Open / edge' },
+  // 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', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Legacy multimodal', shortFor: 'Legacy multimodal', legacy: 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 },
 ];
 
 module.exports = {

package/src/lib/explanations.js

@@ -210,12 +210,15 @@ const concepts = {
       `The ${pc.cyan('input_type')} parameter tells the embedding model whether the text is a`,
       `${pc.cyan('search query')} or a ${pc.cyan('document')} being indexed. This matters for retrieval quality.`,
       ``,
-      `${pc.bold('How it works:')} Voyage AI models internally prepend a short prompt to your text`,
-      `based on input_type:`,
-      `  ${pc.dim('• query →')}    "Represent the query for retrieving relevant documents: "`,
-      `  ${pc.dim('• document →')} "Represent the document for retrieval: "`,
+      `${pc.bold('⚠ Do not omit this parameter for retrieval tasks.')} The official docs emphasize`,
+      `that omitting input_type degrades retrieval accuracy.`,
       ``,
-      `These prompts bias the embedding to be ${pc.cyan('asymmetric')} — query embeddings are`,
+      `${pc.bold('How it works:')} Voyage AI models internally prepend a specific prompt prefix`,
+      `to your text based on input_type:`,
+      `  ${pc.dim('• query →')}    ${pc.cyan('"Represent the query for retrieving supporting documents: "')}`,
+      `  ${pc.dim('• document →')} ${pc.cyan('"Represent the document for retrieval: "')}`,
+      ``,
+      `These prefixes bias the embedding to be ${pc.cyan('asymmetric')} — query embeddings are`,
       `optimized to find relevant documents, and document embeddings are optimized`,
       `to be found by relevant queries.`,
       ``,
@@ -226,10 +229,10 @@ const concepts = {
       `${pc.bold('When to use each:')}`,
       `  ${pc.cyan('query')}    — When embedding a search query or question`,
       `  ${pc.cyan('document')} — When embedding text to be stored and searched later`,
-      `  ${pc.dim('(omit)')}   — For clustering, classification, or symmetric similarity`,
+      `  ${pc.dim('(omit)')}   — Only for clustering, classification, or symmetric similarity`,
       ``,
-      `${pc.bold('Tip:')} Always use ${pc.cyan('--input-type document')} when running ${pc.cyan('vai store')}, and`,
-      `${pc.cyan('--input-type query')} is the default for ${pc.cyan('vai search')}.`,
+      `${pc.bold('Tip:')} Always use ${pc.cyan('--input-type document')} when running ${pc.cyan('vai store')} or`,
+      `${pc.cyan('vai ingest')}, and ${pc.cyan('--input-type query')} when running ${pc.cyan('vai search')}.`,
     ].join('\n'),
     links: ['https://www.mongodb.com/docs/voyageai/models/text-embeddings/'],
     tryIt: [

package/test/commands/embed.test.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { describe, it, beforeEach, afterEach, mock } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+const { registerEmbed } = require('../../src/commands/embed');
+
+describe('embed command', () => {
+  it('registers correctly on a program', () => {
+    const program = new Command();
+    registerEmbed(program);
+    const embedCmd = program.commands.find(c => c.name() === 'embed');
+    assert.ok(embedCmd, 'embed command should be registered');
+  });
+
+  it('has --truncation flag', () => {
+    const program = new Command();
+    registerEmbed(program);
+    const embedCmd = program.commands.find(c => c.name() === 'embed');
+    const optionNames = embedCmd.options.map(o => o.long);
+    assert.ok(optionNames.includes('--truncation'), 'should have --truncation option');
+    assert.ok(optionNames.includes('--no-truncation'), 'should have --no-truncation option');
+  });
+
+  it('has --input-type flag', () => {
+    const program = new Command();
+    registerEmbed(program);
+    const embedCmd = program.commands.find(c => c.name() === 'embed');
+    const optionNames = embedCmd.options.map(o => o.long);
+    assert.ok(optionNames.includes('--input-type'), 'should have --input-type option');
+  });
+});

package/test/commands/ingest.test.js

@@ -243,6 +243,19 @@ describe('ingest', () => {
       assert.ok(optionNames.includes('--json'), 'should have --json option');
       assert.ok(optionNames.includes('--quiet'), 'should have --quiet option');
       assert.ok(optionNames.includes('--strict'), 'should have --strict option');
+      assert.ok(optionNames.includes('--input-type'), 'should have --input-type option');
+    });
+
+    it('--input-type defaults to document', () => {
+      delete require.cache[require.resolve('../../src/commands/ingest')];
+      const { registerIngest } = require('../../src/commands/ingest');
+      const { Command } = require('commander');
+      const program = new Command();
+      registerIngest(program);
+
+      const ingestCmd = program.commands.find(c => c.name() === 'ingest');
+      const inputTypeOpt = ingestCmd.options.find(o => o.long === '--input-type');
+      assert.equal(inputTypeOpt.defaultValue, 'document', '--input-type should default to document');
     });
   });
 });

package/test/commands/models.test.js

@@ -86,4 +86,47 @@ describe('models command', () => {
     assert.ok(parsed[0].name);
     assert.ok(parsed[0].type);
   });
+
+  it('hides legacy models by default', async () => {
+    const program = new Command();
+    program.exitOverride();
+    registerModels(program);
+
+    await program.parseAsync(['node', 'test', 'models', '--quiet']);
+
+    const combined = output.join('\n');
+    assert.ok(combined.includes('voyage-4-large'), 'Should include current models');
+    assert.ok(!combined.includes('voyage-3-large'), 'Should hide legacy voyage-3-large');
+    assert.ok(!combined.includes('rerank-2-lite'), 'Should hide legacy rerank-2-lite');
+    assert.ok(!combined.includes('voyage-code-2'), 'Should hide legacy voyage-code-2');
+  });
+
+  it('shows legacy models when --all is used', async () => {
+    const program = new Command();
+    program.exitOverride();
+    registerModels(program);
+
+    await program.parseAsync(['node', 'test', 'models', '--all', '--quiet']);
+
+    const combined = output.join('\n');
+    assert.ok(combined.includes('voyage-4-large'), 'Should include current models');
+    assert.ok(combined.includes('voyage-3-large'), 'Should include legacy voyage-3-large');
+    assert.ok(combined.includes('rerank-2'), 'Should include legacy rerank-2');
+    assert.ok(combined.includes('Legacy Models'), 'Should show legacy header');
+  });
+
+  it('--all with --json shows legacy models in JSON', async () => {
+    const program = new Command();
+    program.exitOverride();
+    registerModels(program);
+
+    await program.parseAsync(['node', 'test', 'models', '--all', '--json']);
+
+    const combined = output.join('\n');
+    const parsed = JSON.parse(combined);
+    assert.ok(Array.isArray(parsed));
+    const legacyNames = parsed.filter(m => m.legacy).map(m => m.name);
+    assert.ok(legacyNames.includes('voyage-3-large'), 'JSON should include legacy models');
+    assert.ok(legacyNames.includes('rerank-2'), 'JSON should include legacy rerankers');
+  });
 });

package/test/commands/rerank.test.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+const { registerRerank } = require('../../src/commands/rerank');
+
+describe('rerank command', () => {
+  it('registers correctly on a program', () => {
+    const program = new Command();
+    registerRerank(program);
+    const rerankCmd = program.commands.find(c => c.name() === 'rerank');
+    assert.ok(rerankCmd, 'rerank command should be registered');
+  });
+
+  it('has --truncation flag', () => {
+    const program = new Command();
+    registerRerank(program);
+    const rerankCmd = program.commands.find(c => c.name() === 'rerank');
+    const optionNames = rerankCmd.options.map(o => o.long);
+    assert.ok(optionNames.includes('--truncation'), 'should have --truncation option');
+    assert.ok(optionNames.includes('--no-truncation'), 'should have --no-truncation option');
+  });
+
+  it('has --return-documents flag', () => {
+    const program = new Command();
+    registerRerank(program);
+    const rerankCmd = program.commands.find(c => c.name() === 'rerank');
+    const optionNames = rerankCmd.options.map(o => o.long);
+    assert.ok(optionNames.includes('--return-documents'), 'should have --return-documents option');
+  });
+});

package/test/commands/store.test.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+const { registerStore } = require('../../src/commands/store');
+
+describe('store command', () => {
+  it('registers correctly on a program', () => {
+    const program = new Command();
+    registerStore(program);
+    const storeCmd = program.commands.find(c => c.name() === 'store');
+    assert.ok(storeCmd, 'store command should be registered');
+  });
+
+  it('has --input-type flag defaulting to document', () => {
+    const program = new Command();
+    registerStore(program);
+    const storeCmd = program.commands.find(c => c.name() === 'store');
+    const optionNames = storeCmd.options.map(o => o.long);
+    assert.ok(optionNames.includes('--input-type'), 'should have --input-type option');
+    // Check the default value
+    const inputTypeOpt = storeCmd.options.find(o => o.long === '--input-type');
+    assert.equal(inputTypeOpt.defaultValue, 'document', '--input-type should default to document');
+  });
+});

package/test/lib/catalog.test.js

@@ -64,4 +64,36 @@ describe('catalog', () => {
     const rerankCount = MODEL_CATALOG.filter(m => m.type === 'reranking').length;
     assert.ok(embedCount > rerankCount);
   });
+
+  it('contains voyage-4-nano as current model', () => {
+    const nano = MODEL_CATALOG.find(m => m.name === 'voyage-4-nano');
+    assert.ok(nano, 'Should have voyage-4-nano');
+    assert.equal(nano.type, 'embedding');
+    assert.ok(!nano.legacy, 'voyage-4-nano should not be legacy');
+  });
+
+  it('contains legacy models with legacy flag', () => {
+    const legacyModels = MODEL_CATALOG.filter(m => m.legacy);
+    assert.ok(legacyModels.length > 0, 'Should have legacy models');
+
+    const legacyNames = legacyModels.map(m => m.name);
+    assert.ok(legacyNames.includes('voyage-3-large'), 'Should have voyage-3-large');
+    assert.ok(legacyNames.includes('voyage-3.5'), 'Should have voyage-3.5');
+    assert.ok(legacyNames.includes('voyage-3.5-lite'), 'Should have voyage-3.5-lite');
+    assert.ok(legacyNames.includes('voyage-code-2'), 'Should have voyage-code-2');
+    assert.ok(legacyNames.includes('voyage-multimodal-3'), 'Should have voyage-multimodal-3');
+    assert.ok(legacyNames.includes('rerank-2'), 'Should have rerank-2');
+    assert.ok(legacyNames.includes('rerank-2-lite'), 'Should have rerank-2-lite');
+  });
+
+  it('legacy models have required fields', () => {
+    const legacyModels = MODEL_CATALOG.filter(m => m.legacy);
+    for (const model of legacyModels) {
+      assert.ok(model.name, `Legacy model missing name`);
+      assert.ok(model.type, `Legacy model ${model.name} missing type`);
+      assert.ok(model.context, `Legacy model ${model.name} missing context`);
+      assert.ok(model.price, `Legacy model ${model.name} missing price`);
+      assert.ok(model.bestFor, `Legacy model ${model.name} missing bestFor`);
+    }
+  });
 });