voyageai-cli 1.22.0 → 1.22.1

package/package.json

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

package/src/lib/explanations.js

@@ -1151,6 +1151,175 @@ const concepts = {
     ],
   },
 
+  'auto-embedding': {
+    title: 'MongoDB Auto-Embedding',
+    summary: 'Automatic vector embedding generation in Atlas Vector Search',
+    content: [
+      `${pc.bold('What is Auto-Embedding?')}`,
+      `${pc.cyan('Auto-Embedding')} is a MongoDB Atlas Vector Search feature (currently in Preview)`,
+      `that automatically generates vector embeddings for text fields using Voyage AI`,
+      `models — no embedding code required.`,
+      ``,
+      `${pc.bold('How it works:')}`,
+      `  ${pc.dim('1.')} Configure your vector search index with ${pc.cyan('autoEmbed')} type`,
+      `  ${pc.dim('2.')} Specify which text field to embed and which Voyage AI model to use`,
+      `  ${pc.dim('3.')} MongoDB automatically generates embeddings when documents are inserted/updated`,
+      `  ${pc.dim('4.')} At query time, pass natural language text — MongoDB embeds it automatically`,
+      ``,
+      `${pc.bold('Supported models:')}`,
+      `  ${pc.cyan('voyage-4-lite')}   — High-volume, cost-sensitive applications`,
+      `  ${pc.cyan('voyage-4')}        — Balanced performance (recommended)`,
+      `  ${pc.cyan('voyage-4-large')}  — Maximum accuracy for complex relationships`,
+      `  ${pc.cyan('voyage-code-3')}   — Code search and technical documentation`,
+      ``,
+      `${pc.bold('Index definition example:')}`,
+      `  ${pc.dim('{')}`,
+      `    ${pc.dim('"mappings": {')}`,
+      `      ${pc.dim('"fields": {')}`,
+      `        ${pc.cyan('"summary"')}: ${pc.dim('{')}`,
+      `          ${pc.dim('"type": "')}${pc.cyan('autoEmbed')}${pc.dim('",')}`,
+      `          ${pc.dim('"model": "voyage-4"')}`,
+      `        ${pc.dim('}')}`,
+      `      ${pc.dim('}')}`,
+      `    ${pc.dim('}')}`,
+      `  ${pc.dim('}')}`,
+      ``,
+      `${pc.bold('Query syntax:')} Use ${pc.cyan('query.text')} in $vectorSearch instead of ${pc.cyan('queryVector')}:`,
+      `  ${pc.dim('$vectorSearch: {')}`,
+      `    ${pc.dim('index: "myIndex",')}`,
+      `    ${pc.dim('path: "summary",')}`,
+      `    ${pc.cyan('query: { text: "properties near amusement parks" }')},`,
+      `    ${pc.dim('numCandidates: 100,')}`,
+      `    ${pc.dim('limit: 10')}`,
+      `  ${pc.dim('}')}`,
+      ``,
+      `${pc.bold('API keys:')}`,
+      `Auto-Embedding uses Voyage AI API keys configured during mongot deployment.`,
+      `Best practice: use separate keys for indexing vs. querying to avoid rate limit`,
+      `conflicts. Keys can be created from Atlas (AI Models section) or Voyage AI directly.`,
+      ``,
+      `${pc.bold('Current limitations (Preview):')}`,
+      `  ${pc.dim('•')} ${pc.yellow('Not yet available')} on Atlas clusters (only self-managed Community Edition)`,
+      `  ${pc.dim('•')} Not available on local Atlas deployments via Atlas CLI`,
+      `  ${pc.dim('•')} Not available on MongoDB Enterprise Edition`,
+      `  ${pc.dim('•')} Available via Docker, tarball, package manager, or Kubernetes with 8.2+ CE`,
+      ``,
+      `${pc.bold('When to use Auto-Embedding:')}`,
+      `  ${pc.dim('•')} Simple use cases where you want zero embedding code`,
+      `  ${pc.dim('•')} Single-field text embedding scenarios`,
+      `  ${pc.dim('•')} When your data changes frequently and you want automatic sync`,
+      `  ${pc.dim('•')} Self-managed MongoDB deployments`,
+      ``,
+      `${pc.bold('When to use vai (manual embedding) instead:')}`,
+      `  ${pc.dim('•')} Atlas clusters (auto-embedding not yet available)`,
+      `  ${pc.dim('•')} Custom chunking strategies needed`,
+      `  ${pc.dim('•')} Multi-field or multi-collection embeddings`,
+      `  ${pc.dim('•')} Reranking pipelines (auto-embedding doesn't include reranking)`,
+      `  ${pc.dim('•')} Quantization (int8/binary) for storage optimization`,
+      `  ${pc.dim('•')} Multimodal embeddings (images + text)`,
+    ].join('\n'),
+    links: [
+      'https://www.mongodb.com/docs/atlas/atlas-vector-search/crud-embeddings/create-embeddings-automatic/',
+      'https://www.mongodb.com/docs/voyageai/management/api-keys/',
+    ],
+    tryIt: [
+      'vai explain vai-vs-auto-embedding',
+      'vai explain vector-search',
+      'vai models --type embedding',
+    ],
+  },
+
+  'vai-vs-auto-embedding': {
+    title: 'VAI vs Auto-Embedding — When to Use Each',
+    summary: 'Choosing between manual embedding pipelines and MongoDB auto-embedding',
+    content: [
+      `Both ${pc.cyan('vai')} (manual embedding) and ${pc.cyan('MongoDB Auto-Embedding')} use the same`,
+      `Voyage AI models, but they serve different use cases and deployment scenarios.`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold(pc.cyan('VAI (Manual Embedding Pipeline)'))}`,
+      ``,
+      `You embed text explicitly using ${pc.cyan('vai embed')}, ${pc.cyan('vai pipeline')}, or ${pc.cyan('vai store')},`,
+      `then store the vectors in any database. Full control over every step.`,
+      ``,
+      `${pc.bold('Use vai when:')}`,
+      `  ${pc.green('✓')} Using ${pc.cyan('MongoDB Atlas clusters')} (auto-embedding not available yet)`,
+      `  ${pc.green('✓')} Using ${pc.cyan('any vector database')} (Pinecone, Weaviate, Qdrant, etc.)`,
+      `  ${pc.green('✓')} You need ${pc.cyan('custom chunking')} (sentence, paragraph, semantic, sliding window)`,
+      `  ${pc.green('✓')} You need ${pc.cyan('reranking')} (vai supports two-stage retrieval pipelines)`,
+      `  ${pc.green('✓')} You want ${pc.cyan('quantization')} (int8, binary) for storage optimization`,
+      `  ${pc.green('✓')} You need ${pc.cyan('multimodal embeddings')} (images + text)`,
+      `  ${pc.green('✓')} You need ${pc.cyan('flexible dimensions')} (256, 512, 1024, 2048)`,
+      `  ${pc.green('✓')} You want to ${pc.cyan('mix models')} (embed docs with -large, query with -lite)`,
+      `  ${pc.green('✓')} You need ${pc.cyan('batch processing')} with custom concurrency/rate limiting`,
+      `  ${pc.green('✓')} You're building ${pc.cyan('RAG pipelines')} with custom retrieval logic`,
+      ``,
+      `${pc.dim('Workflow:')}`,
+      `  ${pc.cyan('vai chunk')} → ${pc.cyan('vai embed')} → ${pc.cyan('vai store')} → ${pc.cyan('vai search')} → ${pc.cyan('vai rerank')}`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold(pc.cyan('MongoDB Auto-Embedding'))}`,
+      ``,
+      `MongoDB automatically generates embeddings when you insert/update documents.`,
+      `No embedding code needed — just configure your index and insert data.`,
+      ``,
+      `${pc.bold('Use Auto-Embedding when:')}`,
+      `  ${pc.green('✓')} Using ${pc.cyan('self-managed MongoDB Community Edition')} (8.2+)`,
+      `  ${pc.green('✓')} You want ${pc.cyan('zero embedding code')} — simplest possible setup`,
+      `  ${pc.green('✓')} You're embedding a ${pc.cyan('single text field')} per collection`,
+      `  ${pc.green('✓')} Your data ${pc.cyan('changes frequently')} and you want automatic sync`,
+      `  ${pc.green('✓')} You don't need reranking, quantization, or multimodal`,
+      `  ${pc.green('✓')} Standard chunking is sufficient (or you pre-chunk your data)`,
+      ``,
+      `${pc.dim('Workflow:')}`,
+      `  ${pc.cyan('db.collection.insertOne({text: "..."})')} → embeddings auto-generated`,
+      `  ${pc.cyan('$vectorSearch: {query: {text: "..."}}')} → query auto-embedded`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold('FEATURE COMPARISON')}`,
+      ``,
+      `${pc.dim('Feature                    vai           Auto-Embedding')}`,
+      `${pc.dim('─────────────────────────────────────────────────────────────────')}`,
+      `Atlas clusters             ${pc.green('Yes')}           ${pc.yellow('Not yet')}`,
+      `Self-managed CE 8.2+       ${pc.green('Yes')}           ${pc.green('Yes')}`,
+      `Other vector DBs           ${pc.green('Yes')}           ${pc.dim('No')}`,
+      `Custom chunking            ${pc.green('Yes')}           ${pc.dim('No')}`,
+      `Reranking                  ${pc.green('Yes')}           ${pc.dim('No')}`,
+      `Quantization               ${pc.green('Yes')}           ${pc.dim('No')}`,
+      `Multimodal                 ${pc.green('Yes')}           ${pc.dim('No')}`,
+      `Flexible dimensions        ${pc.green('Yes')}           ${pc.dim('No')}`,
+      `Mix query/doc models       ${pc.green('Yes')}           ${pc.dim('No')}`,
+      `Auto-sync on update        ${pc.dim('Manual')}        ${pc.green('Yes')}`,
+      `Zero code setup            ${pc.dim('No')}            ${pc.green('Yes')}`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold('RECOMMENDATION')}`,
+      ``,
+      `${pc.dim('•')} For ${pc.cyan('Atlas users')}: Use vai — auto-embedding isn't available yet`,
+      `${pc.dim('•')} For ${pc.cyan('production RAG')}: Use vai — you'll want reranking and custom chunking`,
+      `${pc.dim('•')} For ${pc.cyan('quick prototypes')} on self-managed CE: Auto-embedding is faster to set up`,
+      `${pc.dim('•')} For ${pc.cyan('complex pipelines')}: vai gives you full control over every step`,
+      ``,
+      `${pc.bold('Migration path:')} Start with auto-embedding for simplicity, then migrate to`,
+      `vai when you need advanced features. The models are the same — your embeddings`,
+      `will be compatible.`,
+    ].join('\n'),
+    links: [
+      'https://www.mongodb.com/docs/atlas/atlas-vector-search/crud-embeddings/create-embeddings-automatic/',
+      'https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/',
+    ],
+    tryIt: [
+      'vai explain auto-embedding',
+      'vai pipeline --help',
+      'vai chunk --help',
+      'vai rerank --help',
+    ],
+  },
+
   'eval-comparison': {
     title: 'Evaluation Comparison — vai eval compare',
     summary: 'Compare configurations and track quality over time',
@@ -1320,6 +1489,23 @@ const aliases = {
   'save-results': 'eval-comparison',
   'a-b-test': 'eval-comparison',
   regression: 'eval-comparison',
+  // Auto-embedding aliases
+  'auto-embedding': 'auto-embedding',
+  'auto-embed': 'auto-embedding',
+  autoembed: 'auto-embedding',
+  'autoEmbed': 'auto-embedding',
+  'automatic-embedding': 'auto-embedding',
+  'automatic-embeddings': 'auto-embedding',
+  'atlas-auto-embed': 'auto-embedding',
+  'mongodb-auto-embedding': 'auto-embedding',
+  'zero-code': 'auto-embedding',
+  // VAI vs Auto-embedding aliases
+  'vai-vs-auto-embedding': 'vai-vs-auto-embedding',
+  'vai-vs-autoembedding': 'vai-vs-auto-embedding',
+  'manual-vs-auto': 'vai-vs-auto-embedding',
+  'auto-vs-manual': 'vai-vs-auto-embedding',
+  'which-approach': 'vai-vs-auto-embedding',
+  'embedding-approach': 'vai-vs-auto-embedding',
   // Provider comparison aliases
   'provider-comparison': 'provider-comparison',
   providers: 'provider-comparison',