voyageai-cli 1.11.0 → 1.12.0

package/README.md

@@ -312,6 +312,29 @@ All commands support:
 
 Free tier: 200M tokens for most models. All Voyage 4 series models share the same embedding space.
 
+## Benchmarks: vai vs. Voyage AI's Published Results
+
+Voyage AI publishes [retrieval quality benchmarks](https://blog.voyageai.com/2026/01/15/voyage-4/) — NDCG@10 scores across 29 RTEB datasets measuring how *accurate* each model's embeddings are. Their results show voyage-4-large outperforms Gemini Embedding 001 by 3.87%, Cohere Embed v4 by 8.20%, and OpenAI v3 Large by 14.05%.
+
+**`vai benchmark` measures something different:** real-world latency, cost, and whether models agree on ranking *your specific data*. The two are complementary:
+
+| | Voyage AI Benchmarks | vai benchmark |
+|---|---|---|
+| **Measures** | Retrieval quality (NDCG@10) | Latency, cost, ranking agreement |
+| **Data** | 29 standardized datasets | Your actual data |
+| **Answers** | "Which model produces the best embeddings?" | "For my data and budget, which model should I use?" |
+
+Voyage AI's key insight — [asymmetric retrieval](https://blog.voyageai.com/2026/01/15/voyage-4/) (embed docs with voyage-4-large, query with voyage-4-lite) — is directly testable with `vai`:
+
+```bash
+# Does the cheap query model find the same results as the expensive one?
+vai benchmark asymmetric --doc-model voyage-4-large \
+  --query-models voyage-4-large,voyage-4,voyage-4-lite \
+  --file your-corpus.txt --query "your actual query"
+```
+
+If rankings agree, you can embed documents once with voyage-4-large and query with voyage-4-lite — **6x cheaper** at query time with no re-indexing.
+
 ## Requirements
 
 - Node.js 18+

package/package.json

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

package/src/commands/benchmark.js

@@ -719,6 +719,393 @@ async function benchmarkBatch(opts) {
   console.log('');
 }
 
+/**
+ * benchmark asymmetric — Test Voyage 4's asymmetric retrieval
+ * (embed docs with one model, query with another).
+ */
+async function benchmarkAsymmetric(opts) {
+  const docModel = opts.docModel || 'voyage-4-large';
+  const queryModels = opts.queryModels
+    ? parseModels(opts.queryModels)
+    : ['voyage-4-large', 'voyage-4', 'voyage-4-lite'];
+  const query = opts.query || SAMPLE_QUERY;
+  const showK = opts.topK ? parseInt(opts.topK, 10) : 5;
+
+  let corpus;
+  if (opts.file) {
+    corpus = loadTexts(opts.file);
+  } else {
+    corpus = SAMPLE_RERANK_DOCS;
+  }
+
+  if (!opts.json && !opts.quiet) {
+    console.log('');
+    console.log(ui.bold('  Asymmetric Retrieval Benchmark'));
+    console.log(ui.dim(`  Documents embedded with: ${docModel}`));
+    console.log(ui.dim(`  Query models: ${queryModels.join(', ')}`));
+    console.log(ui.dim(`  Query: "${query.substring(0, 60)}${query.length > 60 ? '...' : ''}"`));
+    console.log(ui.dim(`  ${corpus.length} documents`));
+    console.log('');
+  }
+
+  // Step 1: Embed documents with the doc model
+  const spin1 = (!opts.json && !opts.quiet) ? ui.spinner(`  Embedding ${corpus.length} docs with ${docModel}...`) : null;
+  if (spin1) spin1.start();
+
+  let docEmbeddings;
+  try {
+    const docResult = await generateEmbeddings(corpus, { model: docModel, inputType: 'document' });
+    docEmbeddings = docResult.data.map(d => d.embedding);
+    if (spin1) spin1.stop();
+  } catch (err) {
+    if (spin1) spin1.stop();
+    console.error(ui.error(`Failed to embed documents with ${docModel}: ${err.message}`));
+    process.exit(1);
+  }
+
+  // Step 2: For each query model, embed the query and rank
+  const allResults = [];
+
+  for (const qModel of queryModels) {
+    const spin = (!opts.json && !opts.quiet) ? ui.spinner(`  Querying with ${qModel}...`) : null;
+    if (spin) spin.start();
+
+    try {
+      const start = performance.now();
+      const qResult = await generateEmbeddings([query], { model: qModel, inputType: 'query' });
+      const elapsed = performance.now() - start;
+      const queryEmbed = qResult.data[0].embedding;
+
+      const ranked = corpus.map((text, i) => ({
+        index: i,
+        text,
+        similarity: cosineSimilarity(queryEmbed, docEmbeddings[i]),
+      })).sort((a, b) => b.similarity - a.similarity);
+
+      allResults.push({
+        queryModel: qModel,
+        docModel,
+        latency: elapsed,
+        tokens: qResult.usage?.total_tokens || 0,
+        ranked,
+      });
+
+      if (spin) spin.stop();
+    } catch (err) {
+      if (spin) spin.stop();
+      console.error(ui.warn(`  ${qModel}: ${err.message} — skipping`));
+    }
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ benchmark: 'asymmetric', docModel, query, corpus: corpus.length, results: allResults }, null, 2));
+    return;
+  }
+
+  if (allResults.length === 0) {
+    console.error(ui.error('No query models completed successfully.'));
+    process.exit(1);
+  }
+
+  // Show latency comparison
+  if (!opts.quiet) {
+    console.log(ui.dim(`  ${rpad('Query Model', 22)} ${lpad('Latency', 8)} ${lpad('Tokens', 7)}`));
+    console.log(ui.dim('  ' + '─'.repeat(40)));
+    const minLat = Math.min(...allResults.map(r => r.latency));
+    for (const r of allResults) {
+      const badge = r.latency === minLat ? ui.green(' ⚡') : '   ';
+      console.log(`  ${rpad(r.queryModel, 22)} ${lpad(fmtMs(r.latency), 8)} ${lpad(String(r.tokens), 7)}${badge}`);
+    }
+    console.log('');
+  }
+
+  // Show ranking comparison
+  console.log(ui.bold(`  Top ${showK} results (docs embedded with ${ui.cyan(docModel)})`));
+  console.log('');
+
+  // Use the full-model result as baseline
+  const baseline = allResults[0];
+
+  for (let rank = 0; rank < showK && rank < corpus.length; rank++) {
+    console.log(ui.dim(`  #${rank + 1}`));
+    for (const r of allResults) {
+      const item = r.ranked[rank];
+      const preview = item.text.substring(0, 50) + (item.text.length > 50 ? '...' : '');
+      const match = baseline.ranked[rank].index === item.index ? ui.green('=') : ui.yellow('≠');
+      console.log(`    ${match} ${ui.cyan(rpad(r.queryModel, 20))} ${ui.score(item.similarity)}  [${item.index}] ${ui.dim(preview)}`);
+    }
+  }
+
+  console.log('');
+
+  // Agreement analysis
+  const baseOrder = baseline.ranked.slice(0, showK).map(x => x.index);
+  for (const r of allResults.slice(1)) {
+    const rOrder = r.ranked.slice(0, showK).map(x => x.index);
+    const overlap = baseOrder.filter(idx => rOrder.includes(idx)).length;
+    const exactMatch = baseOrder.filter((idx, i) => rOrder[i] === idx).length;
+    const overlapPct = ((overlap / showK) * 100).toFixed(0);
+    const exactPct = ((exactMatch / showK) * 100).toFixed(0);
+
+    const price = getPrice(r.queryModel);
+    const basePrice = getPrice(baseline.queryModel);
+    const savings = (price && basePrice && price < basePrice)
+      ? ` (${((1 - price / basePrice) * 100).toFixed(0)}% cheaper)`
+      : '';
+
+    if (exactMatch === showK) {
+      console.log(ui.success(`${r.queryModel}: Identical ranking to ${docModel}${savings} — asymmetric retrieval works perfectly.`));
+    } else if (overlap === showK) {
+      console.log(ui.info(`${r.queryModel}: Same ${showK} docs, ${exactPct}% exact order match${savings}.`));
+    } else {
+      console.log(ui.warn(`${r.queryModel}: ${overlapPct}% overlap in top-${showK}${savings}.`));
+    }
+  }
+  console.log('');
+}
+
+/**
+ * benchmark quantization — Compare output dtypes for quality vs storage tradeoff.
+ */
+async function benchmarkQuantization(opts) {
+  const model = opts.model || getDefaultModel();
+  const dtypes = opts.dtypes
+    ? opts.dtypes.split(',').map(d => d.trim())
+    : ['float', 'int8', 'ubinary'];
+  const query = opts.query || SAMPLE_QUERY;
+  const dimensions = opts.dimensions ? parseInt(opts.dimensions, 10) : undefined;
+  const showK = opts.topK ? parseInt(opts.topK, 10) : 5;
+
+  let corpus;
+  if (opts.file) {
+    corpus = loadTexts(opts.file);
+  } else {
+    corpus = SAMPLE_RERANK_DOCS;
+  }
+
+  if (!opts.json && !opts.quiet) {
+    console.log('');
+    console.log(ui.bold('  Quantization Benchmark'));
+    console.log(ui.dim(`  Model: ${model}`));
+    console.log(ui.dim(`  Data types: ${dtypes.join(', ')}`));
+    console.log(ui.dim(`  ${corpus.length} documents, top-${showK} comparison`));
+    if (dimensions) console.log(ui.dim(`  Dimensions: ${dimensions}`));
+    console.log('');
+  }
+
+  // Step 1: Get float baseline embeddings (query + corpus)
+  const allTexts = [query, ...corpus];
+  const resultsByDtype = {};
+
+  for (const dtype of dtypes) {
+    const spin = (!opts.json && !opts.quiet) ? ui.spinner(`  Embedding with ${dtype}...`) : null;
+    if (spin) spin.start();
+
+    try {
+      const embedOpts = { model, inputType: 'document' };
+      if (dimensions) embedOpts.dimensions = dimensions;
+      if (dtype !== 'float') embedOpts.outputDtype = dtype;
+
+      const start = performance.now();
+      const result = await generateEmbeddings(allTexts, embedOpts);
+      const elapsed = performance.now() - start;
+
+      if (spin) spin.stop();
+
+      const embeddings = result.data.map(d => d.embedding);
+      const queryEmbed = embeddings[0];
+      const dims = embeddings[0].length;
+
+      // For binary/ubinary, we can't directly cosine-similarity the packed ints
+      // against float embeddings meaningfully. Instead we compare the ranking
+      // each dtype produces independently.
+      const ranked = corpus.map((text, i) => {
+        const docEmbed = embeddings[i + 1];
+        let sim;
+        if (dtype === 'binary' || dtype === 'ubinary') {
+          // Hamming-style: compute dot product of packed int arrays
+          // (higher = more bits agree = more similar)
+          sim = hammingSimilarity(queryEmbed, docEmbed);
+        } else {
+          sim = cosineSimilarity(queryEmbed, docEmbed);
+        }
+        return { index: i, text, similarity: sim };
+      }).sort((a, b) => b.similarity - a.similarity);
+
+      // Calculate storage per vector
+      let bytesPerVec;
+      const actualDims = (dtype === 'binary' || dtype === 'ubinary') ? dims * 8 : dims;
+      if (dtype === 'float') {
+        bytesPerVec = dims * 4;
+      } else if (dtype === 'int8' || dtype === 'uint8') {
+        bytesPerVec = dims * 1;
+      } else {
+        // binary/ubinary: dims is already 1/8th of actual dimensions
+        bytesPerVec = dims;
+      }
+
+      resultsByDtype[dtype] = {
+        dtype,
+        latency: elapsed,
+        dims,
+        actualDims,
+        bytesPerVec,
+        tokens: result.usage?.total_tokens || 0,
+        ranked,
+      };
+    } catch (err) {
+      if (spin) spin.stop();
+      console.error(ui.warn(`  ${dtype}: ${err.message} — skipping`));
+    }
+  }
+
+  const completed = Object.values(resultsByDtype);
+
+  if (opts.json) {
+    const jsonResults = completed.map(r => ({
+      dtype: r.dtype,
+      latency: r.latency,
+      dimensions: r.actualDims,
+      bytesPerVector: r.bytesPerVec,
+      ranking: r.ranked.slice(0, showK).map(x => ({ index: x.index, similarity: x.similarity })),
+    }));
+    console.log(JSON.stringify({ benchmark: 'quantization', model, results: jsonResults }, null, 2));
+    return;
+  }
+
+  if (completed.length === 0) {
+    console.error(ui.error('No data types completed successfully.'));
+    process.exit(1);
+  }
+
+  // Storage comparison table
+  console.log(ui.bold('  Storage Comparison'));
+  console.log('');
+
+  const sHeader = `  ${rpad('dtype', 10)} ${lpad('Dims', 8)} ${lpad('Bytes/vec', 12)} ${lpad('1M docs', 10)} ${lpad('Savings', 10)} ${lpad('Latency', 10)}`;
+  console.log(ui.dim(sHeader));
+  console.log(ui.dim('  ' + '─'.repeat(stripAnsi(sHeader).length - 2)));
+
+  const baseline = completed.find(r => r.dtype === 'float') || completed[0];
+  const baselineBytes = baseline.bytesPerVec;
+
+  for (const r of completed) {
+    const savings = r.bytesPerVec < baselineBytes
+      ? ui.green(`${(baselineBytes / r.bytesPerVec).toFixed(0)}×`)
+      : ui.dim('baseline');
+
+    const totalMB = (r.bytesPerVec * 1_000_000) / (1024 * 1024);
+    let sizeStr;
+    if (totalMB >= 1024) sizeStr = `${(totalMB / 1024).toFixed(1)} GB`;
+    else sizeStr = `${totalMB.toFixed(0)} MB`;
+
+    console.log(
+      `  ${rpad(r.dtype, 10)} ${lpad(String(r.actualDims), 8)} ${lpad(formatBytes(r.bytesPerVec), 12)} ${lpad(sizeStr, 10)} ${lpad(savings, 10)} ${lpad(fmtMs(r.latency), 10)}`
+    );
+  }
+
+  console.log('');
+
+  // Ranking comparison
+  console.log(ui.bold(`  Ranking Comparison (top ${showK})`));
+  console.log('');
+
+  const baselineRanked = baseline.ranked;
+  const baselineOrder = baselineRanked.slice(0, showK).map(x => x.index);
+
+  for (let rank = 0; rank < showK && rank < corpus.length; rank++) {
+    console.log(ui.dim(`  #${rank + 1}`));
+    for (const r of completed) {
+      const item = r.ranked[rank];
+      const preview = item.text.substring(0, 45) + (item.text.length > 45 ? '...' : '');
+      const matchesBaseline = (r === baseline) ? ' ' :
+        (item.index === baselineRanked[rank].index ? ui.green('=') : ui.yellow('≠'));
+      const simStr = (r.dtype === 'binary' || r.dtype === 'ubinary')
+        ? `${(item.similarity * 100).toFixed(1)}%`
+        : item.similarity.toFixed(4);
+      console.log(`    ${matchesBaseline} ${ui.cyan(rpad(r.dtype, 10))} ${lpad(simStr, 8)}  [${item.index}] ${ui.dim(preview)}`);
+    }
+  }
+
+  console.log('');
+
+  // Agreement summary
+  if (completed.length > 1) {
+    for (const r of completed) {
+      if (r === baseline) continue;
+      const rOrder = r.ranked.slice(0, showK).map(x => x.index);
+      const overlap = baselineOrder.filter(idx => rOrder.includes(idx)).length;
+      const exactMatch = baselineOrder.filter((idx, i) => rOrder[i] === idx).length;
+      const overlapPct = ((overlap / showK) * 100).toFixed(0);
+      const exactPct = ((exactMatch / showK) * 100).toFixed(0);
+      const savingsX = (baselineBytes / r.bytesPerVec).toFixed(0);
+
+      if (exactMatch === showK) {
+        console.log(ui.success(`${r.dtype}: Identical ranking to float — ${savingsX}× storage savings with zero quality loss.`));
+      } else if (overlap === showK) {
+        console.log(ui.info(`${r.dtype}: Same top-${showK} docs, ${exactPct}% exact order — ${savingsX}× smaller.`));
+      } else {
+        console.log(ui.warn(`${r.dtype}: ${overlapPct}% overlap in top-${showK} — ${savingsX}× smaller. Consider using a reranker.`));
+      }
+    }
+    console.log('');
+  }
+
+  // Save results
+  if (opts.save) {
+    const outData = {
+      benchmark: 'quantization',
+      timestamp: new Date().toISOString(),
+      model,
+      results: completed.map(r => ({
+        dtype: r.dtype,
+        latency: r.latency,
+        dimensions: r.actualDims,
+        bytesPerVector: r.bytesPerVec,
+        topRanking: r.ranked.slice(0, showK),
+      })),
+    };
+    const outPath = typeof opts.save === 'string' ? opts.save : `benchmark-quantization-${Date.now()}.json`;
+    fs.writeFileSync(outPath, JSON.stringify(outData, null, 2));
+    console.log(ui.info(`Results saved to ${outPath}`));
+    console.log('');
+  }
+}
+
+/**
+ * Compute Hamming similarity between two packed binary vectors.
+ * Returns a value between 0 and 1 (fraction of bits that agree).
+ */
+function hammingSimilarity(a, b) {
+  const len = Math.min(a.length, b.length);
+  let agreeBits = 0;
+  const totalBits = len * 8;
+  for (let i = 0; i < len; i++) {
+    // XOR to find differing bits, then count matching bits
+    const xor = (a[i] & 0xFF) ^ (b[i] & 0xFF);
+    // popcount via bit tricks
+    agreeBits += 8 - popcount8(xor);
+  }
+  return agreeBits / totalBits;
+}
+
+/**
+ * Count set bits in an 8-bit value.
+ */
+function popcount8(v) {
+  v = v - ((v >> 1) & 0x55);
+  v = (v & 0x33) + ((v >> 2) & 0x33);
+  return (v + (v >> 4)) & 0x0F;
+}
+
+/**
+ * Format bytes into a human-readable string.
+ */
+function formatBytes(bytes) {
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${bytes} B`;
+}
+
 // ── Registration ──
 
 /**
@@ -796,6 +1183,35 @@ function registerBenchmark(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action(benchmarkBatch);
+
+  // ── benchmark quantization ──
+  bench
+    .command('quantization')
+    .alias('quant')
+    .description('Compare output dtypes (float/int8/binary) for quality vs storage')
+    .option('-m, --model <model>', 'Embedding model to benchmark')
+    .option('--dtypes <types>', 'Comma-separated output dtypes', 'float,int8,ubinary')
+    .option('--query <text>', 'Search query')
+    .option('-f, --file <path>', 'Corpus file (JSON array or newline-delimited)')
+    .option('-k, --top-k <n>', 'Show top K results', '5')
+    .option('-d, --dimensions <n>', 'Output dimensions')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .option('-s, --save [path]', 'Save results to JSON file')
+    .action(benchmarkQuantization);
+
+  // ── benchmark asymmetric ──
+  bench
+    .command('asymmetric')
+    .description('Test asymmetric retrieval (docs with large model, queries with smaller)')
+    .option('--doc-model <model>', 'Model to embed documents with', 'voyage-4-large')
+    .option('--query-models <models>', 'Comma-separated query models', 'voyage-4-large,voyage-4,voyage-4-lite')
+    .option('--query <text>', 'Search query')
+    .option('-f, --file <path>', 'Corpus file (JSON array or newline-delimited)')
+    .option('-k, --top-k <n>', 'Show top K results', '5')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(benchmarkAsymmetric);
 }
 
 module.exports = { registerBenchmark };

package/src/commands/embed.js

@@ -19,6 +19,7 @@ function registerEmbed(program) {
     .option('-f, --file <path>', 'Read text from file')
     .option('--truncation', 'Enable truncation for long inputs')
     .option('--no-truncation', 'Disable truncation')
+    .option('--output-dtype <type>', 'Output data type: float, int8, uint8, binary, ubinary', 'float')
     .option('-o, --output-format <format>', 'Output format: json or array', 'json')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
@@ -49,6 +50,10 @@ function registerEmbed(program) {
         if (opts.truncation !== undefined) {
           embedOpts.truncation = opts.truncation;
         }
+        // Only pass output_dtype when not the default float
+        if (opts.outputDtype && opts.outputDtype !== 'float') {
+          embedOpts.outputDtype = opts.outputDtype;
+        }
 
         const result = await generateEmbeddings(texts, embedOpts);
 

package/src/commands/playground.js

@@ -137,17 +137,21 @@ function createPlaygroundServer() {
 
         // API: Embed
         if (req.url === '/api/embed') {
-          const { texts, model, inputType, dimensions } = parsed;
+          const { texts, model, inputType, dimensions, output_dtype } = parsed;
           if (!texts || !Array.isArray(texts) || texts.length === 0) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'texts must be a non-empty array' }));
             return;
           }
-          const result = await generateEmbeddings(texts, {
+          const embedOpts = {
             model: model || undefined,
             inputType: inputType || undefined,
             dimensions: dimensions || undefined,
-          });
+          };
+          if (output_dtype && output_dtype !== 'float') {
+            embedOpts.outputDtype = output_dtype;
+          }
+          const result = await generateEmbeddings(texts, embedOpts);
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify(result));
           return;

package/src/commands/store.js

@@ -23,6 +23,7 @@ function registerStore(program) {
     .option('-m, --model <model>', 'Embedding model', getDefaultModel())
     .option('--input-type <type>', 'Input type: query or document', 'document')
     .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
+    .option('--output-dtype <type>', 'Output data type: float, int8, uint8, binary, ubinary', 'float')
     .option('--metadata <json>', 'Additional metadata as JSON')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
@@ -46,11 +47,15 @@ function registerStore(program) {
           spin.start();
         }
 
-        const embedResult = await generateEmbeddings([textContent], {
+        const embedOpts = {
           model: opts.model,
           inputType: opts.inputType,
           dimensions: opts.dimensions,
-        });
+        };
+        if (opts.outputDtype && opts.outputDtype !== 'float') {
+          embedOpts.outputDtype = opts.outputDtype;
+        }
+        const embedResult = await generateEmbeddings([textContent], embedOpts);
 
         const embedding = embedResult.data[0].embedding;
 
@@ -147,11 +152,15 @@ async function handleBatchStore(opts) {
       spin.start();
     }
 
-    const embedResult = await generateEmbeddings(texts, {
+    const batchEmbedOpts = {
       model: opts.model,
       inputType: opts.inputType,
       dimensions: opts.dimensions,
-    });
+    };
+    if (opts.outputDtype && opts.outputDtype !== 'float') {
+      batchEmbedOpts.outputDtype = opts.outputDtype;
+    }
+    const embedResult = await generateEmbeddings(texts, batchEmbedOpts);
 
     const docs = records.map((record, i) => {
       const embedding = embedResult.data[i].embedding;

package/src/lib/api.js

@@ -129,6 +129,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 +149,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/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',

package/src/playground/index.html

@@ -551,6 +551,83 @@ select:focus { outline: none; border-color: var(--accent); }
 .rank-differ { border-left-color: var(--yellow); }
 .rank-arrow { text-align: center; color: var(--text-muted); font-size: 18px; padding-top: 4px; }
 
+/* Quantization charts */
+.quant-charts { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 16px; }
+@media (max-width: 768px) { .quant-charts { grid-template-columns: 1fr; } }
+
+.quant-bar-group { margin-bottom: 14px; }
+.quant-bar-label {
+  display: flex; justify-content: space-between; align-items: baseline;
+  margin-bottom: 4px; font-size: 13px;
+}
+.quant-bar-label .dtype-name { color: var(--accent); font-weight: 600; font-family: var(--mono); }
+.quant-bar-label .dtype-value { color: var(--text-dim); font-family: var(--mono); font-size: 12px; }
+.quant-bar-track {
+  height: 32px; background: var(--bg-input); border-radius: 6px;
+  overflow: hidden; position: relative;
+}
+.quant-bar-fill {
+  height: 100%; border-radius: 6px;
+  transition: width 0.8s cubic-bezier(0.22, 1, 0.36, 1);
+  display: flex; align-items: center; padding: 0 10px;
+  font-family: var(--mono); font-size: 12px; font-weight: 600;
+  color: #0a0a1a; white-space: nowrap; min-width: fit-content;
+}
+.quant-bar-fill.storage { background: linear-gradient(90deg, #00d4aa, #4ecdc4); }
+.quant-bar-fill.latency { background: linear-gradient(90deg, #45b7d1, #82aaff); }
+.quant-bar-badge {
+  position: absolute; right: 10px; top: 50%; transform: translateY(-50%);
+  font-size: 12px; color: var(--text-dim); font-family: var(--mono);
+}
+
+.quant-quality-meter { margin-bottom: 14px; }
+.quant-meter-header {
+  display: flex; justify-content: space-between; align-items: center;
+  margin-bottom: 6px;
+}
+.quant-meter-header .dtype-name { color: var(--accent); font-weight: 600; font-family: var(--mono); font-size: 13px; }
+.quant-meter-header .verdict-badge {
+  font-size: 12px; padding: 2px 8px; border-radius: 10px; font-weight: 600;
+}
+.quant-meter-header .verdict-badge.perfect { background: rgba(0,212,170,0.15); color: var(--green); }
+.quant-meter-header .verdict-badge.good { background: rgba(255,217,61,0.15); color: var(--yellow); }
+.quant-meter-header .verdict-badge.degraded { background: rgba(255,107,107,0.15); color: var(--red); }
+.quant-meter-track {
+  height: 10px; background: var(--bg-input); border-radius: 5px; overflow: hidden;
+}
+.quant-meter-fill {
+  height: 100%; border-radius: 5px;
+  transition: width 0.8s cubic-bezier(0.22, 1, 0.36, 1);
+}
+.quant-meter-fill.perfect { background: linear-gradient(90deg, #00d4aa, #00e4ba); }
+.quant-meter-fill.good { background: linear-gradient(90deg, #ffd93d, #ffe066); }
+.quant-meter-fill.degraded { background: linear-gradient(90deg, #ff6b6b, #ff8e8e); }
+.quant-meter-detail { font-size: 11px; color: var(--text-muted); margin-top: 4px; font-family: var(--mono); }
+
+.quant-rank-cols {
+  display: grid; gap: 12px;
+}
+.quant-rank-col-header {
+  font-weight: 600; color: var(--accent); font-size: 13px; font-family: var(--mono);
+  margin-bottom: 8px; padding-bottom: 6px; border-bottom: 1px solid var(--border);
+}
+.quant-rank-item {
+  padding: 8px 10px; margin-bottom: 4px; border-radius: 6px;
+  font-size: 12px; position: relative; border-left: 3px solid transparent;
+  transition: background 0.2s;
+}
+.quant-rank-item:hover { background: rgba(255,255,255,0.03); }
+.quant-rank-item.match { border-left-color: var(--green); background: rgba(0,212,170,0.06); }
+.quant-rank-item.differ { border-left-color: var(--red); background: rgba(255,107,107,0.06); }
+.quant-rank-item.baseline { border-left-color: var(--border); background: var(--bg-input); }
+.quant-rank-pos {
+  display: inline-block; width: 22px; height: 22px; line-height: 22px;
+  text-align: center; border-radius: 50%; background: var(--bg-surface);
+  color: var(--accent); font-weight: 700; font-size: 11px; font-family: var(--mono);
+  margin-right: 8px;
+}
+.quant-rank-score { color: var(--text-muted); font-size: 11px; font-family: var(--mono); margin-top: 3px; }
+
 /* Cost calculator */
 .cost-slider-row {
   display: flex;
@@ -797,6 +874,16 @@ select:focus { outline: none; border-color: var(--accent); }
         <option value="2048">2048</option>
       </select>
     </div>
+    <div class="option-group">
+      <span class="option-label">Output Type</span>
+      <select id="embedOutputDtype">
+        <option value="float">float (32-bit)</option>
+        <option value="int8">int8 (4× smaller)</option>
+        <option value="uint8">uint8 (4× smaller)</option>
+        <option value="binary">binary (32× smaller)</option>
+        <option value="ubinary">ubinary (32× smaller)</option>
+      </select>
+    </div>
     <button class="btn" id="embedBtn" onclick="doEmbed()">⚡ Embed</button>
   </div>
 
@@ -916,6 +1003,7 @@ Semantic search understands meaning beyond keyword matching</textarea>
   <div class="bench-panels">
     <button class="bench-panel-btn active" data-bench="latency">⚡ Latency</button>
     <button class="bench-panel-btn" data-bench="ranking">🏆 Ranking</button>
+    <button class="bench-panel-btn" data-bench="quantization">⚗️ Quantization</button>
     <button class="bench-panel-btn" data-bench="cost">💰 Cost</button>
     <button class="bench-panel-btn" data-bench="history">📊 History</button>
   </div>
@@ -1008,6 +1096,91 @@ Reranking models rescore initial search results to improve relevance ordering.</
     </div>
   </div>
 
+  <!-- ── Quantization Panel ── -->
+  <div class="bench-view" id="bench-quantization">
+    <div class="card">
+      <div class="card-title">Quantization Benchmark</div>
+      <p style="color:var(--text-dim);font-size:13px;margin-bottom:12px;">
+        Compare how different output data types (float, int8, binary) affect storage size and ranking quality.
+        Embeds the same corpus with each dtype and measures the tradeoff.
+      </p>
+      <div class="options-row" style="flex-wrap:wrap;">
+        <div class="option-group">
+          <span class="option-label">Model</span>
+          <select id="quantModel"></select>
+        </div>
+        <div class="option-group">
+          <span class="option-label">Dimensions</span>
+          <select id="quantDimensions">
+            <option value="">Default</option>
+            <option value="256">256</option>
+            <option value="512">512</option>
+            <option value="1024">1024</option>
+            <option value="2048">2048</option>
+          </select>
+        </div>
+        <div class="option-group">
+          <span class="option-label">Data Types</span>
+          <div id="quantDtypeChecks" style="display:flex;gap:8px;flex-wrap:wrap;">
+            <label style="display:flex;align-items:center;gap:4px;font-size:13px;cursor:pointer;color:var(--text);">
+              <input type="checkbox" value="float" checked style="accent-color:var(--accent);">float
+            </label>
+            <label style="display:flex;align-items:center;gap:4px;font-size:13px;cursor:pointer;color:var(--text);">
+              <input type="checkbox" value="int8" checked style="accent-color:var(--accent);">int8
+            </label>
+            <label style="display:flex;align-items:center;gap:4px;font-size:13px;cursor:pointer;color:var(--text);">
+              <input type="checkbox" value="uint8" style="accent-color:var(--accent);">uint8
+            </label>
+            <label style="display:flex;align-items:center;gap:4px;font-size:13px;cursor:pointer;color:var(--text);">
+              <input type="checkbox" value="ubinary" checked style="accent-color:var(--accent);">ubinary
+            </label>
+            <label style="display:flex;align-items:center;gap:4px;font-size:13px;cursor:pointer;color:var(--text);">
+              <input type="checkbox" value="binary" style="accent-color:var(--accent);">binary
+            </label>
+          </div>
+        </div>
+      </div>
+      <div style="margin-top:12px;">
+        <span class="option-label">Query</span>
+        <input type="text" id="quantQuery" placeholder="Search query..." value="How do I search for similar documents using embeddings?" style="width:100%;margin-bottom:8px;">
+      </div>
+      <div>
+        <span class="option-label">Corpus (one document per line)</span>
+        <textarea id="quantCorpus" rows="5" placeholder="Documents to embed...">Vector search finds documents by computing similarity between embedding vectors in high-dimensional space.
+MongoDB Atlas Vector Search lets you index and query vector embeddings alongside your operational data.
+Traditional full-text search uses inverted indexes to match keyword terms in documents.
+Cosine similarity measures the angle between two vectors, commonly used for semantic search.
+Database sharding distributes data across multiple servers for horizontal scalability.
+Embedding models convert text into dense numerical vectors that capture meaning.
+Approximate nearest neighbor algorithms like HNSW enable fast similarity search at scale.
+Reranking models rescore initial search results to improve relevance ordering.</textarea>
+      </div>
+      <div style="margin-top:12px;">
+        <button class="btn" id="quantBtn" onclick="doBenchQuantization()">⚗️ Run Quantization Benchmark</button>
+      </div>
+    </div>
+
+    <div class="error-msg" id="quantError"></div>
+
+    <div class="result-section" id="quantResult">
+      <div class="quant-charts">
+        <div class="card">
+          <div class="card-title">📦 Storage per Vector</div>
+          <div id="quantStorageChart"></div>
+        </div>
+        <div class="card">
+          <div class="card-title">⏱ API Latency</div>
+          <div id="quantLatencyChart"></div>
+        </div>
+      </div>
+      <div class="card">
+        <div class="card-title">🎯 Ranking Quality vs Float Baseline</div>
+        <div id="quantQualityMeters" style="margin-bottom:16px;"></div>
+        <div id="quantRankGrid"></div>
+      </div>
+    </div>
+  </div>
+
   <!-- ── Cost Panel ── -->
   <div class="bench-view" id="bench-cost">
     <div class="card">
@@ -1238,6 +1411,12 @@ function populateModelSelects() {
 }
 
 // ── API Helpers ──
+function formatBytesUI(bytes) {
+  if (bytes >= 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+  if (bytes >= 1024) return (bytes / 1024).toFixed(1) + ' KB';
+  return bytes + ' B';
+}
+
 async function apiPost(url, body) {
   const res = await fetch(url, {
     method: 'POST',
@@ -1284,16 +1463,29 @@ window.doEmbed = async function() {
     const dims = document.getElementById('embedDimensions').value;
     const dimensions = dims ? parseInt(dims, 10) : undefined;
 
-    const data = await apiPost('/api/embed', { texts: [text], model, inputType, dimensions });
+    const outputDtype = document.getElementById('embedOutputDtype').value;
+    const body = { texts: [text], model, inputType, dimensions };
+    if (outputDtype && outputDtype !== 'float') body.output_dtype = outputDtype;
+
+    const data = await apiPost('/api/embed', body);
     const emb = data.data[0].embedding;
     lastEmbedding = emb;
 
     // Stats
+    const dtype = outputDtype || 'float';
+    const bytesPerDim = (dtype === 'binary' || dtype === 'ubinary') ? 0.125 : (dtype === 'int8' || dtype === 'uint8') ? 1 : 4;
+    const totalBytes = emb.length * bytesPerDim;
+    const storageLine = dtype !== 'float'
+      ? `<br><span style="color:var(--success)">📦 ${dtype}: ${formatBytesUI(totalBytes)}/vector (${(4 * emb.length / totalBytes).toFixed(0)}× smaller than float)</span>`
+      : '';
+
     const statsEl = document.getElementById('embedStats');
     statsEl.innerHTML = `
       <span class="stat"><span class="stat-label">Model</span><span class="stat-value">${data.model}</span></span>
       <span class="stat"><span class="stat-label">Dimensions</span><span class="stat-value">${emb.length}</span></span>
       <span class="stat"><span class="stat-label">Tokens</span><span class="stat-value">${data.usage?.total_tokens || '—'}</span></span>
+      <span class="stat"><span class="stat-label">Type</span><span class="stat-value">${dtype}</span></span>
+      ${storageLine}
     `;
 
     // Vector preview
@@ -1529,6 +1721,7 @@ const CONCEPT_META = {
   'api-access':        { icon: '🌐', tab: 'embed' },
   'batch-processing':  { icon: '📦', tab: 'embed' },
   benchmarking:        { icon: '⏱', tab: 'benchmark' },
+  quantization:        { icon: '⚗️', tab: 'benchmark' },
 };
 
 let exploreConcepts = {};
@@ -1916,6 +2109,222 @@ function renderRankComparison(modelA, modelB, rankedA, rankedB, topK) {
   }
 }
 
+// ── Benchmark: Quantization ──
+function populateQuantModelSelect() {
+  const sel = document.getElementById('quantModel');
+  sel.innerHTML = '';
+  embedModels.forEach(m => {
+    const opt = document.createElement('option');
+    opt.value = m.name;
+    opt.textContent = m.name;
+    sel.appendChild(opt);
+  });
+  // Default to voyage-4-large if available
+  const preferred = embedModels.find(m => m.name === 'voyage-4-large');
+  if (preferred) sel.value = preferred.name;
+}
+
+function hammingSimUI(a, b) {
+  // For binary/ubinary packed embeddings, compute agreement via dot product
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
+  return dot;
+}
+
+window.doBenchQuantization = async function() {
+  hideError('quantError');
+  const model = document.getElementById('quantModel').value;
+  const dimsVal = document.getElementById('quantDimensions').value;
+  const dimensions = dimsVal ? parseInt(dimsVal, 10) : undefined;
+  const query = document.getElementById('quantQuery').value.trim();
+  const corpusText = document.getElementById('quantCorpus').value.trim();
+
+  if (!query) { showError('quantError', 'Enter a query'); return; }
+  if (!corpusText) { showError('quantError', 'Enter at least 2 documents'); return; }
+
+  const corpus = corpusText.split('\n').map(d => d.trim()).filter(Boolean);
+  if (corpus.length < 2) { showError('quantError', 'Enter at least 2 documents'); return; }
+
+  const checks = document.querySelectorAll('#quantDtypeChecks input:checked');
+  const dtypes = Array.from(checks).map(c => c.value);
+  if (dtypes.length === 0) { showError('quantError', 'Select at least one data type'); return; }
+
+  setLoading('quantBtn', true);
+
+  try {
+    const allTexts = [query, ...corpus];
+    const resultsByDtype = {};
+
+    for (const dtype of dtypes) {
+      const body = { texts: allTexts, model, inputType: 'document' };
+      if (dimensions) body.dimensions = dimensions;
+      if (dtype !== 'float') body.output_dtype = dtype;
+
+      const start = performance.now();
+      const data = await apiPost('/api/embed', body);
+      const elapsed = performance.now() - start;
+
+      const embeddings = data.data.map(d => d.embedding);
+      const queryEmbed = embeddings[0];
+      const dims = embeddings[0].length;
+      const isBinary = (dtype === 'binary' || dtype === 'ubinary');
+
+      // Rank corpus documents by similarity
+      const ranked = corpus.map((text, i) => {
+        const docEmbed = embeddings[i + 1];
+        let sim;
+        if (isBinary) {
+          sim = hammingSimUI(queryEmbed, docEmbed);
+        } else {
+          sim = cosineSim(queryEmbed, docEmbed);
+        }
+        return { index: i, text, similarity: sim };
+      }).sort((a, b) => b.similarity - a.similarity);
+
+      // Calculate storage
+      const actualDims = isBinary ? dims * 8 : dims;
+      let bytesPerVec;
+      if (dtype === 'float') bytesPerVec = dims * 4;
+      else if (dtype === 'int8' || dtype === 'uint8') bytesPerVec = dims * 1;
+      else bytesPerVec = dims; // binary/ubinary: dims is already 1/8th
+
+      resultsByDtype[dtype] = {
+        dtype, latency: elapsed, dims, actualDims, bytesPerVec,
+        tokens: data.usage?.total_tokens || 0, ranked,
+      };
+    }
+
+    const completed = Object.values(resultsByDtype);
+    if (completed.length === 0) {
+      showError('quantError', 'No data types completed successfully');
+      return;
+    }
+
+    // ── Render Charts ──
+    const baseline = completed.find(r => r.dtype === 'float') || completed[0];
+    const maxBytes = Math.max(...completed.map(r => r.bytesPerVec));
+    const maxLatency = Math.max(...completed.map(r => r.latency));
+    const DTYPE_COLORS = { float: '#00d4aa', int8: '#4ecdc4', uint8: '#45b7d1', ubinary: '#ffd93d', binary: '#ff6b6b' };
+
+    // ── Storage Bar Chart ──
+    let storageHTML = '';
+    for (const r of completed) {
+      const pct = Math.max(8, (r.bytesPerVec / maxBytes) * 100);
+      const totalMB = (r.bytesPerVec * 1_000_000) / (1024 * 1024);
+      const sizeStr = totalMB >= 1024 ? `${(totalMB / 1024).toFixed(1)} GB` : `${totalMB.toFixed(0)} MB`;
+      const savings = r.bytesPerVec < baseline.bytesPerVec
+        ? `${(baseline.bytesPerVec / r.bytesPerVec).toFixed(0)}× smaller`
+        : 'baseline';
+      const color = DTYPE_COLORS[r.dtype] || '#82aaff';
+      storageHTML += `<div class="quant-bar-group">
+        <div class="quant-bar-label">
+          <span class="dtype-name">${r.dtype}</span>
+          <span class="dtype-value">${formatBytesUI(r.bytesPerVec)}/vec · ${sizeStr} @ 1M</span>
+        </div>
+        <div class="quant-bar-track">
+          <div class="quant-bar-fill storage" style="width:${pct}%;background:linear-gradient(90deg, ${color}, ${color}cc);">${savings}</div>
+        </div>
+      </div>`;
+    }
+    document.getElementById('quantStorageChart').innerHTML = storageHTML;
+
+    // ── Latency Bar Chart ──
+    let latencyHTML = '';
+    const minLatency = Math.min(...completed.map(r => r.latency));
+    for (const r of completed) {
+      const pct = Math.max(8, (r.latency / maxLatency) * 100);
+      const color = DTYPE_COLORS[r.dtype] || '#82aaff';
+      const badge = r.latency === minLatency ? ' ⚡' : '';
+      latencyHTML += `<div class="quant-bar-group">
+        <div class="quant-bar-label">
+          <span class="dtype-name">${r.dtype}</span>
+          <span class="dtype-value">${r.latency.toFixed(0)}ms${badge}</span>
+        </div>
+        <div class="quant-bar-track">
+          <div class="quant-bar-fill latency" style="width:${pct}%;background:linear-gradient(90deg, ${color}, ${color}cc);">${r.latency.toFixed(0)}ms</div>
+        </div>
+      </div>`;
+    }
+    document.getElementById('quantLatencyChart').innerHTML = latencyHTML;
+
+    // ── Quality Meters + Ranking Grid ──
+    const topK = Math.min(5, corpus.length);
+    const metersEl = document.getElementById('quantQualityMeters');
+    const gridEl = document.getElementById('quantRankGrid');
+    gridEl.innerHTML = '';
+    metersEl.innerHTML = '';
+
+    if (completed.length >= 2 && baseline) {
+      const baselineRanking = baseline.ranked.slice(0, topK).map(r => r.index);
+
+      // Quality meters for each non-baseline dtype
+      let metersHTML = '';
+      for (const r of completed) {
+        if (r.dtype === baseline.dtype) continue;
+        const otherRanking = r.ranked.slice(0, topK).map(x => x.index);
+        const overlap = baselineRanking.filter(idx => otherRanking.includes(idx)).length;
+        const overlapPct = (overlap / topK) * 100;
+        const exactMatch = baselineRanking.every((idx, pos) => otherRanking[pos] === idx);
+        const positionMatches = baselineRanking.filter((idx, pos) => otherRanking[pos] === idx).length;
+        const posMatchPct = (positionMatches / topK) * 100;
+
+        let grade, gradeLabel, detail;
+        if (exactMatch) {
+          grade = 'perfect'; gradeLabel = '✓ Perfect';
+          detail = `Identical ranking — all ${topK} positions match float baseline`;
+        } else if (overlap === topK) {
+          grade = 'good'; gradeLabel = '≈ Reordered';
+          detail = `Same ${topK} documents, ${positionMatches}/${topK} in same position`;
+        } else {
+          grade = overlap >= topK * 0.6 ? 'good' : 'degraded';
+          gradeLabel = `${overlapPct.toFixed(0)}% overlap`;
+          detail = `${overlap}/${topK} documents match, ${positionMatches}/${topK} positions match`;
+        }
+
+        metersHTML += `<div class="quant-quality-meter">
+          <div class="quant-meter-header">
+            <span class="dtype-name">${r.dtype}</span>
+            <span class="verdict-badge ${grade}">${gradeLabel}</span>
+          </div>
+          <div class="quant-meter-track">
+            <div class="quant-meter-fill ${grade}" style="width:${exactMatch ? 100 : posMatchPct}%"></div>
+          </div>
+          <div class="quant-meter-detail">${detail}</div>
+        </div>`;
+      }
+      metersEl.innerHTML = metersHTML;
+
+      // Side-by-side ranking columns
+      let rankHTML = `<div class="quant-rank-cols" style="grid-template-columns:repeat(${completed.length},1fr);">`;
+      for (const r of completed) {
+        rankHTML += `<div><div class="quant-rank-col-header">${r.dtype}${r === baseline ? ' (baseline)' : ''}</div>`;
+        r.ranked.slice(0, topK).forEach((item, pos) => {
+          const trunc = item.text.length > 55 ? item.text.slice(0, 52) + '…' : item.text;
+          let cls = 'baseline';
+          if (r !== baseline) {
+            cls = (baseline.ranked[pos] && item.index === baseline.ranked[pos].index) ? 'match' : 'differ';
+          }
+          rankHTML += `<div class="quant-rank-item ${cls}" title="${item.text.replace(/"/g, '&quot;')}">
+            <span class="quant-rank-pos">${pos + 1}</span>${trunc}
+            <div class="quant-rank-score">${item.similarity.toFixed(4)} · doc ${item.index}</div>
+          </div>`;
+        });
+        rankHTML += '</div>';
+      }
+      rankHTML += '</div>';
+      gridEl.innerHTML = rankHTML;
+    } else {
+      metersEl.innerHTML = '<span style="color:var(--text-dim)">Select multiple data types (including float) to compare rankings.</span>';
+    }
+
+    document.getElementById('quantResult').classList.add('visible');
+  } catch (err) {
+    showError('quantError', err.message);
+  } finally {
+    setLoading('quantBtn', false);
+  }
+};
+
 // ── Benchmark: Cost Calculator ──
 function initCostCalculator() {
   const tokSlider = document.getElementById('costTokens');
@@ -2055,6 +2464,7 @@ init = async function() {
   await _origInit();
   buildModelCheckboxes();
   populateBenchRankSelects();
+  populateQuantModelSelect();
   initCostCalculator();
   renderHistory();
 };

package/test/commands/benchmark.test.js

@@ -241,6 +241,73 @@ describe('benchmark command', () => {
     assert.ok(optionNames.includes('--save'), 'should have --save option');
   });
 
+  it('has asymmetric subcommand', () => {
+    const program = new Command();
+    registerBenchmark(program);
+    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
+    const asymSub = benchCmd.commands.find(c => c.name() === 'asymmetric');
+    assert.ok(asymSub, 'asymmetric subcommand should be registered');
+  });
+
+  it('asymmetric has --doc-model and --query-models options', () => {
+    const program = new Command();
+    registerBenchmark(program);
+    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
+    const asymSub = benchCmd.commands.find(c => c.name() === 'asymmetric');
+    const optionNames = asymSub.options.map(o => o.long);
+    assert.ok(optionNames.includes('--doc-model'), 'should have --doc-model');
+    assert.ok(optionNames.includes('--query-models'), 'should have --query-models');
+  });
+
+  it('asymmetric defaults doc-model to voyage-4-large', () => {
+    const program = new Command();
+    registerBenchmark(program);
+    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
+    const asymSub = benchCmd.commands.find(c => c.name() === 'asymmetric');
+    const opt = asymSub.options.find(o => o.long === '--doc-model');
+    assert.equal(opt.defaultValue, 'voyage-4-large');
+  });
+
+  it('has quantization subcommand with quant alias', () => {
+    const program = new Command();
+    registerBenchmark(program);
+    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
+    const quantSub = benchCmd.commands.find(c => c.name() === 'quantization');
+    assert.ok(quantSub, 'quantization subcommand should be registered');
+    assert.ok(quantSub.aliases().includes('quant'), 'should have "quant" alias');
+  });
+
+  it('quantization has --model, --dtypes, --query options', () => {
+    const program = new Command();
+    registerBenchmark(program);
+    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
+    const quantSub = benchCmd.commands.find(c => c.name() === 'quantization');
+    const optionNames = quantSub.options.map(o => o.long);
+    assert.ok(optionNames.includes('--model'), 'should have --model');
+    assert.ok(optionNames.includes('--dtypes'), 'should have --dtypes');
+    assert.ok(optionNames.includes('--query'), 'should have --query');
+  });
+
+  it('quantization defaults dtypes to float,int8,ubinary', () => {
+    const program = new Command();
+    registerBenchmark(program);
+    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
+    const quantSub = benchCmd.commands.find(c => c.name() === 'quantization');
+    const dtypesOpt = quantSub.options.find(o => o.long === '--dtypes');
+    assert.equal(dtypesOpt.defaultValue, 'float,int8,ubinary');
+  });
+
+  it('quantization has --dimensions, --save, --file options', () => {
+    const program = new Command();
+    registerBenchmark(program);
+    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
+    const quantSub = benchCmd.commands.find(c => c.name() === 'quantization');
+    const optionNames = quantSub.options.map(o => o.long);
+    assert.ok(optionNames.includes('--dimensions'), 'should have --dimensions');
+    assert.ok(optionNames.includes('--save'), 'should have --save');
+    assert.ok(optionNames.includes('--file'), 'should have --file');
+  });
+
   it('batch defaults batch-sizes to 1,5,10,25,50', () => {
     const program = new Command();
     registerBenchmark(program);

package/test/commands/embed.test.js

@@ -29,4 +29,14 @@ describe('embed command', () => {
     const optionNames = embedCmd.options.map(o => o.long);
     assert.ok(optionNames.includes('--input-type'), 'should have --input-type option');
   });
+
+  it('has --output-dtype flag with float default', () => {
+    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('--output-dtype'), 'should have --output-dtype option');
+    const opt = embedCmd.options.find(o => o.long === '--output-dtype');
+    assert.equal(opt.defaultValue, 'float');
+  });
 });

package/test/lib/explanations.test.js

@@ -17,6 +17,7 @@ describe('explanations', () => {
     'api-keys',
     'api-access',
     'batch-processing',
+    'quantization',
     'benchmarking',
   ];
 
@@ -90,6 +91,11 @@ describe('explanations', () => {
       batch: 'batch-processing',
       model: 'models',
       batching: 'batch-processing',
+      quantize: 'quantization',
+      int8: 'quantization',
+      binary: 'quantization',
+      matryoshka: 'quantization',
+      dtype: 'quantization',
     };
 
     it('alias map covers expected aliases', () => {