voyageai-cli 1.11.0 → 1.12.1

package/src/lib/api.js

@@ -96,25 +96,29 @@ async function apiRequest(endpoint, body) {
       } catch {
         errorDetail = await response.text();
       }
-      console.error(`API Error (${response.status}): ${errorDetail}`);
+      const errMsg = `API Error (${response.status}): ${errorDetail}`;
 
       // Help users diagnose endpoint mismatch
+      let hint = '';
       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.');
+        hint = '\n\nHint: 403 on ai.mongodb.com often means your key is for the Voyage AI' +
+          '\nplatform, not MongoDB Atlas. Try switching the base URL:' +
+          '\n\n  vai config set base-url https://api.voyageai.com/v1/' +
+          '\n\nOr 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/');
+        hint = '\n\nHint: 401 on api.voyageai.com may mean your key is an Atlas AI key.' +
+          '\nTry switching back:' +
+          '\n\n  vai config set base-url https://ai.mongodb.com/v1/';
       }
-      process.exit(1);
+
+      // Log the error + hint to stderr for CLI users
+      console.error(errMsg);
+      if (hint) console.error(hint);
+
+      // Throw instead of process.exit so callers (like playground) can catch gracefully
+      const err = new Error(errMsg);
+      err.statusCode = response.status;
+      throw err;
     }
 
     return response.json();
@@ -129,6 +133,7 @@ async function apiRequest(endpoint, body) {
  * @param {string} [options.inputType] - Input type (query|document)
  * @param {number} [options.dimensions] - Output dimensions
  * @param {boolean} [options.truncation] - Enable/disable truncation
+ * @param {string} [options.outputDtype] - Output data type: float, int8, uint8, binary, ubinary
  * @returns {Promise<object>} API response with embeddings
  */
 async function generateEmbeddings(texts, options = {}) {
@@ -148,6 +153,9 @@ async function generateEmbeddings(texts, options = {}) {
   if (options.truncation !== undefined) {
     body.truncation = options.truncation;
   }
+  if (options.outputDtype && options.outputDtype !== 'float') {
+    body.output_dtype = options.outputDtype;
+  }
 
   return apiRequest('/embeddings', body);
 }

package/src/lib/catalog.js

@@ -32,8 +32,8 @@ const MODEL_CATALOG = [
   { 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: '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-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 },
@@ -42,7 +42,7 @@ const MODEL_CATALOG = [
   { 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: '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 },
 ];

package/src/lib/explanations.js

@@ -406,6 +406,65 @@ const concepts = {
       'vai embed --file document.txt --input-type document',
     ],
   },
+  quantization: {
+    title: 'Quantization & Flexible Dimensions',
+    summary: 'Reduce storage costs with lower-precision embeddings',
+    content: [
+      `${pc.cyan('Quantization')} reduces embedding precision from 32-bit floats to smaller`,
+      `representations, dramatically cutting storage and search costs with minimal`,
+      `quality loss. Combined with ${pc.cyan('Matryoshka dimensions')}, you can shrink vectors`,
+      `by up to ${pc.bold('128×')} (32× from binary × 4× from fewer dimensions).`,
+      ``,
+      `${pc.bold('Output data types (--output-dtype):')}`,
+      ``,
+      `  ${pc.cyan('float')}    32 bits/dim   4 bytes/dim   Baseline (default)`,
+      `  ${pc.cyan('int8')}     8 bits/dim    1 byte/dim    ${pc.green('4× smaller')}   Signed: -128 to 127`,
+      `  ${pc.cyan('uint8')}    8 bits/dim    1 byte/dim    ${pc.green('4× smaller')}   Unsigned: 0 to 255`,
+      `  ${pc.cyan('binary')}   1 bit/dim     1/8 byte/dim  ${pc.green('32× smaller')}  Bit-packed int8 (offset binary)`,
+      `  ${pc.cyan('ubinary')}  1 bit/dim     1/8 byte/dim  ${pc.green('32× smaller')}  Bit-packed uint8`,
+      ``,
+      `${pc.bold('Storage math for 1M documents at 1024 dims:')}`,
+      `  float:   ${pc.dim('1M × 1024 × 4B')}  = ${pc.cyan('4.0 GB')}`,
+      `  int8:    ${pc.dim('1M × 1024 × 1B')}  = ${pc.cyan('1.0 GB')}   (4× savings)`,
+      `  binary:  ${pc.dim('1M × 1024 / 8B')}  = ${pc.cyan('128 MB')}   (32× savings)`,
+      `  ${pc.dim('+ reduced dimensions:')} 256-dim binary = ${pc.cyan('32 MB')}   (128× savings)`,
+      ``,
+      `${pc.bold('How binary quantization works:')} Each float value is converted to a single bit:`,
+      `positive values become 1, zero/negative become 0. Eight bits are packed into`,
+      `one byte. ${pc.cyan('binary')} uses offset binary (subtract 128) for signed int8 output;`,
+      `${pc.cyan('ubinary')} stores the raw unsigned uint8 value.`,
+      ``,
+      `${pc.bold('Quality impact:')} Quantization-aware training minimizes degradation:`,
+      `  ${pc.dim('•')} ${pc.cyan('int8/uint8')} — Typically <1% retrieval quality loss vs float`,
+      `  ${pc.dim('•')} ${pc.cyan('binary/ubinary')} — ~2-5% quality loss; best paired with a reranker`,
+      `  ${pc.dim('•')} Combining lower dimensions + quantization compounds the quality loss`,
+      ``,
+      `${pc.bold('Matryoshka dimensions:')} Voyage 4 models produce ${pc.cyan('nested embeddings')} — the`,
+      `first 256 entries of a 1024-dim vector are themselves a valid 256-dim embedding.`,
+      `You can embed once at full dimension and truncate later without re-embedding.`,
+      `Supported values: 256, 512, 1024 (default), 2048.`,
+      ``,
+      `${pc.bold('Which vector databases support quantized storage?')}`,
+      `  ${pc.dim('•')} MongoDB Atlas Vector Search — float and int8`,
+      `  ${pc.dim('•')} Milvus, Qdrant, Weaviate, Elasticsearch, Vespa — float, int8, binary`,
+      ``,
+      `${pc.bold('Decision framework:')}`,
+      `  1. Start with ${pc.cyan('float')} at default dimensions — measure your baseline`,
+      `  2. Try ${pc.cyan('int8')} — if quality holds, you get 4× storage savings for free`,
+      `  3. If storage is critical, try ${pc.cyan('binary')} + reranker for 32× savings`,
+      `  4. Reduce dimensions (1024→256) for another 4× on top of quantization`,
+      `  5. Use ${pc.cyan('vai benchmark quantization')} to measure the tradeoffs on your data`,
+    ].join('\n'),
+    links: [
+      'https://docs.voyageai.com/docs/flexible-dimensions-and-quantization',
+      'https://www.mongodb.com/docs/voyageai/models/text-embeddings/',
+    ],
+    tryIt: [
+      'vai embed "hello world" --output-dtype int8',
+      'vai embed "hello world" --output-dtype binary --dimensions 256',
+      'vai benchmark quantization --model voyage-4-large',
+    ],
+  },
   benchmarking: {
     title: 'Benchmarking & Model Selection',
     summary: 'How to choose the right model for your use case',
@@ -434,12 +493,18 @@ const concepts = {
       `  Measures throughput (texts/sec) at different batch sizes.`,
       `  ${pc.dim('vai benchmark batch --batch-sizes 1,5,10,25,50 --rounds 3')}`,
       ``,
+      `${pc.bold('vai benchmark quantization')} — Compare output dtypes for storage savings:`,
+      `  Embeds the same corpus with float, int8, and binary, measures ranking quality`,
+      `  degradation vs storage savings. Helps you decide if quantization works for your data.`,
+      `  ${pc.dim('vai benchmark quantization --model voyage-4-large --dtypes float,int8,ubinary')}`,
+      ``,
       `${pc.bold('Decision framework:')}`,
       `  1. Run ${pc.cyan('benchmark cost')} to eliminate models outside your budget`,
       `  2. Run ${pc.cyan('benchmark embed')} to compare latency of affordable models`,
       `  3. Run ${pc.cyan('benchmark similarity')} with your actual data to compare quality`,
-      `  4. If quality is similar, pick the cheaper/faster model`,
-      `  5. Use ${pc.cyan('--save')} to track results over time as your data evolves`,
+      `  4. Run ${pc.cyan('benchmark quantization')} to see if int8/binary preserves your ranking`,
+      `  5. If quality is similar, pick the cheaper/faster model + smallest viable dtype`,
+      `  6. Use ${pc.cyan('--save')} to track results over time as your data evolves`,
     ].join('\n'),
     links: ['https://www.mongodb.com/docs/voyageai/models/text-embeddings/'],
     tryIt: [
@@ -488,6 +553,15 @@ const aliases = {
   batch: 'batch-processing',
   'batch-processing': 'batch-processing',
   batching: 'batch-processing',
+  quantization: 'quantization',
+  quantize: 'quantization',
+  'output-dtype': 'quantization',
+  dtype: 'quantization',
+  int8: 'quantization',
+  binary: 'quantization',
+  ubinary: 'quantization',
+  matryoshka: 'quantization',
+  'flexible-dimensions': 'quantization',
   benchmark: 'benchmarking',
   benchmarking: 'benchmarking',
   'model-selection': 'benchmarking',