voyageai-cli 1.20.3 → 1.20.5

package/package.json

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

package/src/lib/explanations.js

@@ -871,6 +871,147 @@ const concepts = {
     ],
   },
 
+  'provider-comparison': {
+    title: 'Voyage AI vs OpenAI vs Anthropic',
+    summary: 'Understanding the differences between AI providers for embeddings and search',
+    content: [
+      `Developers often ask: "Should I use Voyage AI, OpenAI, or Anthropic for my vector`,
+      `search application?" The answer depends on what you're building — these companies`,
+      `serve ${pc.cyan('fundamentally different purposes')}.`,
+      ``,
+      `${pc.bold('TL;DR:')}`,
+      `  ${pc.cyan('Voyage AI')}   → ${pc.bold('Embeddings & Reranking')} (specialized, best-in-class)`,
+      `  ${pc.cyan('OpenAI')}      → ${pc.bold('Embeddings + Generation')} (general-purpose, convenient)`,
+      `  ${pc.cyan('Anthropic')}   → ${pc.bold('Generation only')} (Claude LLM, no embedding API)`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold(pc.cyan('VOYAGE AI'))} — The Embedding Specialist`,
+      ``,
+      `Voyage AI is ${pc.cyan('100% focused on embeddings and reranking')}. That's it. No chatbots,`,
+      `no image generation — just the best vector representations for retrieval.`,
+      ``,
+      `${pc.dim('Models:')}`,
+      `  • ${pc.cyan('voyage-4-large')}      71.41 RTEB score (SOTA), MoE architecture`,
+      `  • ${pc.cyan('voyage-4')}            70.07 RTEB, balanced quality/cost`,
+      `  • ${pc.cyan('voyage-4-lite')}       68.10 RTEB, lowest cost`,
+      `  • ${pc.cyan('voyage-code-3')}       Optimized for code retrieval`,
+      `  • ${pc.cyan('voyage-finance-2')}    Financial documents`,
+      `  • ${pc.cyan('voyage-law-2')}        Legal text`,
+      `  • ${pc.cyan('voyage-multimodal-3.5')} Images + text in same space`,
+      `  • ${pc.cyan('rerank-2.5')}          Best-in-class reranking`,
+      ``,
+      `${pc.dim('Unique strengths:')}`,
+      `  • ${pc.cyan('Shared embedding space')} — mix models freely (embed docs with -large, query with -lite)`,
+      `  • ${pc.cyan('Matryoshka dimensions')} — truncate 1024→256 dims without re-embedding`,
+      `  • ${pc.cyan('Domain-specific models')} — code, finance, law tuned for their domains`,
+      `  • ${pc.cyan('No modality gap')} — multimodal model uses unified backbone, not CLIP`,
+      `  • ${pc.cyan('Quantization support')} — int8, binary output for 4-32× storage savings`,
+      ``,
+      `${pc.dim('Pricing:')} $0.02-$0.12 per million tokens (embedding), $2/M (reranking)`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold(pc.cyan('OPENAI'))} — The General-Purpose Platform`,
+      ``,
+      `OpenAI offers embeddings as ${pc.cyan('one product among many')}. They're convenient if you're`,
+      `already using GPT, but embeddings aren't their core focus.`,
+      ``,
+      `${pc.dim('Embedding models:')}`,
+      `  • ${pc.cyan('text-embedding-3-large')}  62.57 RTEB, 3072 dims, $0.13/M tokens`,
+      `  • ${pc.cyan('text-embedding-3-small')}  62.26 RTEB, 1536 dims, $0.02/M tokens`,
+      `  • ${pc.cyan('text-embedding-ada-002')}  Legacy, 1536 dims, $0.10/M tokens`,
+      ``,
+      `${pc.dim('Strengths:')}`,
+      `  • ${pc.cyan('One platform')} — embeddings + GPT generation in same account`,
+      `  • ${pc.cyan('Familiar API')} — if you use ChatGPT API, embeddings are similar`,
+      `  • ${pc.cyan('Broad ecosystem')} — many tutorials and integrations assume OpenAI`,
+      ``,
+      `${pc.dim('Limitations:')}`,
+      `  • ${pc.cyan('Lower quality')} — voyage-4-large beats text-embedding-3-large by 14% on RTEB`,
+      `  • ${pc.cyan('No reranking')} — you need a separate provider for two-stage retrieval`,
+      `  • ${pc.cyan('No domain models')} — same model for code, legal, finance (suboptimal)`,
+      `  • ${pc.cyan('No shared space')} — can't mix models or truncate dimensions freely`,
+      `  • ${pc.cyan('No multimodal')} — text-only (CLIP is separate and limited)`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold(pc.cyan('ANTHROPIC'))} — The LLM Company (No Embeddings!)`,
+      ``,
+      `${pc.yellow('Important:')} Anthropic ${pc.bold('does not offer embedding models')}. They make Claude,`,
+      `an LLM for text generation, reasoning, and analysis — not vectorization.`,
+      ``,
+      `${pc.dim('What Anthropic offers:')}`,
+      `  • ${pc.cyan('Claude 3.5 Sonnet/Haiku')}  — Text generation, coding, analysis`,
+      `  • ${pc.cyan('Claude 3 Opus')}            — Most capable reasoning model`,
+      `  • ${pc.cyan('Tool use & function calling')} — Structured outputs`,
+      ``,
+      `${pc.dim('What Anthropic does NOT offer:')}`,
+      `  • ${pc.red('❌ Embedding models')}`,
+      `  • ${pc.red('❌ Reranking models')}`,
+      `  • ${pc.red('❌ Vector search APIs')}`,
+      ``,
+      `${pc.dim('How to use Claude with embeddings:')}`,
+      `Claude is the ${pc.cyan('"G" in RAG')} — the generation model. You still need an embedding`,
+      `provider (Voyage AI, OpenAI, Cohere) for the retrieval step:`,
+      `  1. Embed your documents with Voyage AI → store in vector DB`,
+      `  2. Embed user query → search vector DB → retrieve context`,
+      `  3. Pass context + query to Claude → generate response`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold('HEAD-TO-HEAD: Voyage AI vs OpenAI Embeddings')}`,
+      ``,
+      `${pc.dim('                        Voyage AI           OpenAI')}`,
+      `${pc.dim('─────────────────────────────────────────────────────────────────')}`,
+      `Best RTEB score         ${pc.cyan('71.41')} (v4-large)   ${pc.dim('62.57')} (v3-large)`,
+      `Reranking               ${pc.cyan('Yes')} (rerank-2.5)   ${pc.dim('No')}`,
+      `Domain models           ${pc.cyan('Yes')} (code/law/fin) ${pc.dim('No')}`,
+      `Multimodal              ${pc.cyan('Yes')} (unified)      ${pc.dim('Limited')} (CLIP)`,
+      `Shared embedding space  ${pc.cyan('Yes')}                ${pc.dim('No')}`,
+      `Flexible dimensions     ${pc.cyan('Yes')} (Matryoshka)   ${pc.dim('No')}`,
+      `Quantized output        ${pc.cyan('Yes')} (int8/binary)  ${pc.dim('No')}`,
+      `MongoDB integration     ${pc.cyan('Native')} (Atlas)     ${pc.dim('Manual')}`,
+      ``,
+      `${pc.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`,
+      ``,
+      `${pc.bold('WHEN TO USE EACH:')}`,
+      ``,
+      `${pc.cyan('Choose Voyage AI when:')}`,
+      `  • Retrieval quality is critical (RAG, search, recommendations)`,
+      `  • You need domain-specific embeddings (code, legal, finance)`,
+      `  • You want two-stage retrieval (embed → search → rerank)`,
+      `  • You're using MongoDB Atlas Vector Search`,
+      `  • You need multimodal search (images + text)`,
+      `  • Storage cost matters (quantization, flexible dims)`,
+      ``,
+      `${pc.cyan('Choose OpenAI embeddings when:')}`,
+      `  • You're already deep in the OpenAI ecosystem`,
+      `  • Convenience matters more than retrieval quality`,
+      `  • You don't need reranking or domain models`,
+      `  • Your use case is simple (not mission-critical search)`,
+      ``,
+      `${pc.cyan('Choose Anthropic (Claude) when:')}`,
+      `  • You need ${pc.bold('generation')}, not embeddings`,
+      `  • You want the best reasoning/coding LLM`,
+      `  • You're building the "G" in RAG (pair with Voyage for "R")`,
+      ``,
+      `${pc.bold('The winning combination:')} Use ${pc.cyan('Voyage AI for retrieval')} (embeddings +`,
+      `reranking) and ${pc.cyan('Claude for generation')}. Best of both worlds.`,
+    ].join('\n'),
+    links: [
+      'https://www.mongodb.com/docs/voyageai/models/',
+      'https://platform.openai.com/docs/guides/embeddings',
+      'https://docs.anthropic.com/',
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+    ],
+    tryIt: [
+      'vai models --wide',
+      'vai benchmark embed --models voyage-4-large,voyage-4,voyage-4-lite',
+      'vai explain rteb-benchmarks',
+    ],
+  },
+
   'rerank-eval': {
     title: 'Reranking Evaluation — nDCG, Recall, MRR for Rerankers',
     summary: 'Measure how well a reranker surfaces relevant documents',
@@ -1017,6 +1158,24 @@ const aliases = {
   recall: 'rerank-eval',
   mrr: 'rerank-eval',
   'eval-rerank': 'rerank-eval',
+  // Provider comparison aliases
+  'provider-comparison': 'provider-comparison',
+  providers: 'provider-comparison',
+  'voyage-vs-openai': 'provider-comparison',
+  'openai-vs-voyage': 'provider-comparison',
+  'voyage-vs-anthropic': 'provider-comparison',
+  'anthropic-vs-voyage': 'provider-comparison',
+  'openai-vs-anthropic': 'provider-comparison',
+  'anthropic-vs-openai': 'provider-comparison',
+  'voyage-openai-anthropic': 'provider-comparison',
+  differences: 'provider-comparison',
+  'which-provider': 'provider-comparison',
+  'compare-providers': 'provider-comparison',
+  'embedding-providers': 'provider-comparison',
+  'vs-openai': 'provider-comparison',
+  'vs-anthropic': 'provider-comparison',
+  competitors: 'provider-comparison',
+  alternatives: 'provider-comparison',
 };
 
 /**