voyageai-cli 1.12.1 → 1.15.0

package/src/lib/explanations.js

@@ -513,6 +513,169 @@ const concepts = {
       'vai benchmark similarity --query "your search query" --file your-docs.txt',
     ],
   },
+  'mixture-of-experts': {
+    title: 'Mixture-of-Experts (MoE) Architecture',
+    summary: 'How voyage-4-large achieves SOTA quality at 40% lower cost',
+    content: [
+      `${pc.cyan('Mixture-of-Experts (MoE)')} is a neural network architecture where multiple`,
+      `specialized sub-networks ("experts") share a single model. A learned ${pc.cyan('router')}`,
+      `selects which experts activate for each input — typically 2-4 out of 8-64 total.`,
+      ``,
+      `${pc.bold('Why MoE matters for embeddings:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('Higher capacity, lower cost')} — the model has more total parameters`,
+      `    (knowledge) but only activates a fraction per input, keeping inference fast`,
+      `  ${pc.dim('•')} ${pc.cyan('Specialization')} — different experts learn different domains (code,`,
+      `    legal, medical) without interfering with each other`,
+      `  ${pc.dim('•')} ${pc.cyan('State-of-the-art quality')} — voyage-4-large beats all competitors on`,
+      `    RTEB benchmarks while costing 40% less than comparable dense models`,
+      ``,
+      `${pc.bold('voyage-4-large')} is the ${pc.cyan('first production-grade embedding model')} to use MoE.`,
+      `Previous MoE successes (Mixtral, Switch Transformer) were language models —`,
+      `applying MoE to embedding models required solving alignment across the shared`,
+      `embedding space, which is what makes the Voyage 4 family unique.`,
+      ``,
+      `${pc.bold('Dense vs MoE:')}`,
+      `  ${pc.dim('Dense (voyage-4, voyage-4-lite):')} Every parameter is used for every input.`,
+      `    Simpler, predictable latency, lower total parameter count.`,
+      `  ${pc.dim('MoE (voyage-4-large):')} Sparse activation — more total parameters, but each`,
+      `    input only uses a subset. Higher quality ceiling, similar serving cost.`,
+      ``,
+      `${pc.bold('In practice:')} You don't need to do anything special to use MoE — the API`,
+      `interface is identical. The architecture difference shows up in quality and cost:`,
+      `  ${pc.dim('•')} voyage-4-large: $0.12/1M tokens — better quality than voyage-3-large ($0.18/1M)`,
+      `  ${pc.dim('•')} 40% cheaper than comparable dense models at the same quality tier`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+      'https://www.mongodb.com/docs/voyageai/models/text-embeddings/',
+    ],
+    tryIt: [
+      'vai embed "test MoE quality" --model voyage-4-large',
+      'vai benchmark embed --models voyage-4-large,voyage-4,voyage-4-lite',
+      'vai models --wide',
+    ],
+  },
+
+  'shared-embedding-space': {
+    title: 'Shared Embedding Space',
+    summary: 'How Voyage 4 models produce compatible, interchangeable embeddings',
+    content: [
+      `The Voyage 4 series introduces an ${pc.cyan('industry-first capability')}: all four models`,
+      `(voyage-4-large, voyage-4, voyage-4-lite, voyage-4-nano) produce embeddings in`,
+      `the ${pc.cyan('same vector space')}. Embeddings from different models are directly comparable.`,
+      ``,
+      `${pc.bold('What this means:')}`,
+      `  ${pc.dim('•')} Embed documents with ${pc.cyan('voyage-4-large')} (best quality, one-time cost)`,
+      `  ${pc.dim('•')} Query with ${pc.cyan('voyage-4-lite')} or ${pc.cyan('voyage-4-nano')} (low cost, high volume)`,
+      `  ${pc.dim('•')} Cosine similarity works across model boundaries`,
+      `  ${pc.dim('•')} Upgrade query model later ${pc.cyan('without re-vectorizing documents')}`,
+      ``,
+      `${pc.bold('Why this is new:')} Previously, embeddings from different models lived in`,
+      `incompatible vector spaces. Switching models meant re-embedding your entire`,
+      `corpus — expensive and slow. The shared space eliminates this constraint.`,
+      ``,
+      `${pc.bold('Recommended workflow:')}`,
+      `  ${pc.dim('1.')} Vectorize your document corpus once with ${pc.cyan('voyage-4-large')}`,
+      `  ${pc.dim('2.')} Start with ${pc.cyan('voyage-4-lite')} for queries in development / early production`,
+      `  ${pc.dim('3.')} Upgrade to ${pc.cyan('voyage-4')} or ${pc.cyan('voyage-4-large')} as accuracy needs grow`,
+      `  ${pc.dim('4.')} No re-vectorization needed at any step`,
+      ``,
+      `${pc.bold('Validate it yourself:')} Use ${pc.cyan('vai benchmark space')} to embed identical text`,
+      `with all Voyage 4 models and see the cross-model cosine similarities.`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+    ],
+    tryIt: [
+      'vai benchmark space',
+      'vai benchmark asymmetric --query "your search" --file corpus.txt',
+      'vai estimate --docs 1M --queries 10M',
+    ],
+  },
+
+  'rteb-benchmarks': {
+    title: 'RTEB Benchmark Scores',
+    summary: 'Retrieval quality scores across embedding providers',
+    content: [
+      `The ${pc.cyan('Retrieval Embedding Benchmark (RTEB)')} evaluates general-purpose retrieval`,
+      `quality across 29 diverse datasets. Scores are ${pc.cyan('NDCG@10')} (normalized discounted`,
+      `cumulative gain at top 10 results) — higher is better.`,
+      ``,
+      `${pc.bold('Current standings (Jan 2026):')}`,
+      `  ${pc.cyan('voyage-4-large')}       ${pc.bold('71.41')}  ${pc.dim('— SOTA, MoE architecture')}`,
+      `  ${pc.cyan('voyage-4')}             ${pc.bold('70.07')}  ${pc.dim('— near voyage-3-large quality')}`,
+      `  ${pc.cyan('Gemini Embedding 001')} ${pc.bold('68.66')}  ${pc.dim('— Google')}`,
+      `  ${pc.cyan('voyage-4-lite')}        ${pc.bold('68.10')}  ${pc.dim('— near voyage-3.5 quality')}`,
+      `  ${pc.cyan('Cohere Embed v4')}      ${pc.bold('65.75')}  ${pc.dim('— Cohere')}`,
+      `  ${pc.cyan('OpenAI v3 Large')}      ${pc.bold('62.57')}  ${pc.dim('— OpenAI')}`,
+      ``,
+      `${pc.bold('What the numbers mean:')}`,
+      `  ${pc.dim('•')} voyage-4-large beats Gemini by ${pc.cyan('3.87%')}, Cohere by ${pc.cyan('8.20%')}, OpenAI by ${pc.cyan('14.05%')}`,
+      `  ${pc.dim('•')} voyage-4 (mid-tier pricing) outperforms all non-Voyage models`,
+      `  ${pc.dim('•')} Even voyage-4-lite ($0.02/1M) is competitive with Gemini Embedding`,
+      ``,
+      `${pc.bold('Asymmetric retrieval bonus:')} When documents are embedded with voyage-4-large`,
+      `and queries with a smaller Voyage 4 model, retrieval quality ${pc.cyan('improves')} over`,
+      `using the smaller model alone — you get the benefit of the larger model's`,
+      `document representations.`,
+      ``,
+      `${pc.bold('Note:')} These scores are from Voyage AI's evaluation. Independent benchmarks`,
+      `may differ. Always test on your own data with ${pc.cyan('vai benchmark similarity')}.`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+      'https://docs.google.com/spreadsheets/d/1GfPkqCAjPKaGS9f66IDhMRxVpd2bMuqL2wXjj-kNS7E/',
+    ],
+    tryIt: [
+      'vai models --benchmarks',
+      'vai benchmark similarity --query "your query" --file your-docs.txt',
+      'vai estimate --docs 1M --queries 10M',
+    ],
+  },
+
+  'voyage-4-nano': {
+    title: 'voyage-4-nano — Open-Weight Local Model',
+    summary: 'Free, local-first embeddings with shared space compatibility',
+    content: [
+      `${pc.cyan('voyage-4-nano')} is Voyage AI's first ${pc.cyan('open-weight')} embedding model, freely`,
+      `available on Hugging Face under the ${pc.bold('Apache 2.0')} license.`,
+      ``,
+      `${pc.bold('Key specs:')}`,
+      `  ${pc.dim('•')} Dimensions: 512 (default), 128, 256`,
+      `  ${pc.dim('•')} Context: 32K tokens`,
+      `  ${pc.dim('•')} License: Apache 2.0 (fully open)`,
+      `  ${pc.dim('•')} Shared space: Compatible with voyage-4-large/4/4-lite embeddings`,
+      ``,
+      `${pc.bold('Use cases:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('Local development')} — no API key, no network, no cost`,
+      `  ${pc.dim('•')} ${pc.cyan('Prototyping')} — fast iteration before committing to API models`,
+      `  ${pc.dim('•')} ${pc.cyan('Edge/on-device')} — run inference on your own hardware`,
+      `  ${pc.dim('•')} ${pc.cyan('Asymmetric queries')} — use nano for queries against voyage-4-large docs`,
+      ``,
+      `${pc.bold('Getting started with Hugging Face:')}`,
+      `  ${pc.dim('pip install sentence-transformers')}`,
+      `  ${pc.dim('from sentence_transformers import SentenceTransformer')}`,
+      `  ${pc.dim('model = SentenceTransformer("voyageai/voyage-4-nano")')}`,
+      `  ${pc.dim('embeddings = model.encode(["your text here"])')}`,
+      ``,
+      `${pc.bold('With the Voyage API:')} voyage-4-nano is also available via the standard API`,
+      `endpoint, so you can use ${pc.cyan('vai embed --model voyage-4-nano')} for testing before`,
+      `switching to local inference.`,
+      ``,
+      `${pc.bold('Shared space advantage:')} Since nano shares the same embedding space as the`,
+      `larger Voyage 4 models, you can prototype locally with nano, then seamlessly`,
+      `use the same document embeddings with voyage-4 or voyage-4-large in production.`,
+    ].join('\n'),
+    links: [
+      'https://huggingface.co/voyageai/voyage-4-nano',
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+    ],
+    tryIt: [
+      'vai embed "test nano" --model voyage-4-nano',
+      'vai benchmark space',
+      'vai benchmark asymmetric --doc-model voyage-4-large --query-models voyage-4-nano',
+    ],
+  },
 };
 
 /**
@@ -567,6 +730,26 @@ const aliases = {
   'model-selection': 'benchmarking',
   choosing: 'benchmarking',
   compare: 'benchmarking',
+  moe: 'mixture-of-experts',
+  'mixture-of-experts': 'mixture-of-experts',
+  'moe-architecture': 'mixture-of-experts',
+  experts: 'mixture-of-experts',
+  sparse: 'mixture-of-experts',
+  'shared-space': 'shared-embedding-space',
+  'shared-embedding-space': 'shared-embedding-space',
+  'embedding-space': 'shared-embedding-space',
+  interchangeable: 'shared-embedding-space',
+  compatible: 'shared-embedding-space',
+  rteb: 'rteb-benchmarks',
+  'rteb-benchmarks': 'rteb-benchmarks',
+  ndcg: 'rteb-benchmarks',
+  scores: 'rteb-benchmarks',
+  leaderboard: 'rteb-benchmarks',
+  nano: 'voyage-4-nano',
+  'voyage-4-nano': 'voyage-4-nano',
+  'open-weight': 'voyage-4-nano',
+  huggingface: 'voyage-4-nano',
+  local: 'voyage-4-nano',
 };
 
 /**

package/.github/workflows/ci.yml

@@ -1,22 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-  workflow_dispatch:
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18, 20, 22]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm ci
-      - run: npm test

package/CONTRIBUTING.md

@@ -1,81 +0,0 @@
-# Contributing to voyageai-cli
-
-Thanks for your interest in contributing! Here's how to get started.
-
-## Development Setup
-
-```bash
-git clone https://github.com/mrlynn/voyageai-cli.git
-cd voyageai-cli
-npm install
-npm link  # makes `vai` available globally for testing
-```
-
-## Running Tests
-
-```bash
-npm test
-```
-
-Tests use Node.js built-in test runner (`node:test`). No external test framework needed.
-
-## Project Structure
-
-```
-src/
-├── cli.js              # Entry point
-├── commands/           # One file per command
-│   ├── embed.js
-│   ├── rerank.js
-│   ├── store.js
-│   ├── search.js
-│   ├── index.js
-│   ├── models.js
-│   ├── ping.js
-│   ├── config.js
-│   └── demo.js
-└── lib/                # Shared utilities
-    ├── api.js          # Voyage AI API client
-    ├── mongo.js        # MongoDB connection
-    ├── catalog.js      # Model catalog
-    ├── config.js       # Config file management
-    ├── format.js       # Table formatting
-    ├── input.js        # Text input resolution
-    ├── ui.js           # Colors, spinners, output helpers
-    └── banner.js       # ASCII banner
-test/
-├── commands/           # Command tests
-└── lib/                # Library tests
-```
-
-## Adding a New Command
-
-1. Create `src/commands/mycommand.js` exporting a `registerMyCommand(program)` function
-2. Register it in `src/cli.js`
-3. Add tests in `test/commands/mycommand.test.js`
-4. Update README.md with usage examples
-
-## Code Style
-
-- CommonJS (`require`/`module.exports`)
-- `'use strict';` at the top of every file
-- JSDoc comments on exported functions
-- `parseInt(x, 10)` — always include radix
-- Errors go to stderr (`console.error`)
-- Support `--json` and `--quiet` flags on all commands
-- No colors or spinners in `--json` mode
-
-## Pull Requests
-
-- Create a feature branch from `main`
-- Include tests for new functionality
-- Run `npm test` before submitting
-- Write clear commit messages
-
-## Reporting Issues
-
-Open an issue at https://github.com/mrlynn/voyageai-cli/issues with:
-- Node.js version (`node --version`)
-- OS and version
-- Steps to reproduce
-- Expected vs actual behavior

package/demo.tape

@@ -1,39 +0,0 @@
-# VHS demo tape for voyageai-cli
-# Run: vhs demo.tape
-# Requires: VOYAGE_API_KEY set in environment
-
-Output demo.gif
-
-Set FontSize 16
-Set Width 900
-Set Height 600
-Set Theme "Catppuccin Mocha"
-Set Padding 20
-
-# Show version
-Type "vai --version"
-Enter
-Sleep 1.5s
-
-# List embedding models
-Type "vai models --type embedding"
-Enter
-Sleep 3s
-
-# Generate an embedding
-Type 'vai embed "What is MongoDB Atlas?"'
-Enter
-Sleep 4s
-
-# Explain embeddings (first few lines)
-Type "vai explain embeddings"
-Enter
-Sleep 4s
-
-# Compare similarity
-Type 'vai similarity "MongoDB is great" "MongoDB Atlas is amazing"'
-Enter
-Sleep 4s
-
-# Pause at end to show results
-Sleep 2s

package/scripts/record-demo.sh

@@ -1,63 +0,0 @@
-#!/usr/bin/env bash
-# Record a demo GIF for voyageai-cli
-# Requires: VOYAGE_API_KEY environment variable
-#
-# Usage:
-#   ./scripts/record-demo.sh          # Uses vhs (preferred)
-#   ./scripts/record-demo.sh asciinema # Uses asciinema instead
-#
-# Output:
-#   demo.gif (vhs) or demo.cast (asciinema)
-
-set -euo pipefail
-cd "$(dirname "$0")/.."
-
-METHOD="${1:-vhs}"
-
-if [ "$METHOD" = "vhs" ]; then
-  if ! command -v vhs &>/dev/null; then
-    echo "❌ vhs not found. Install: brew install charmbracelet/tap/vhs"
-    echo "   Or run: ./scripts/record-demo.sh asciinema"
-    exit 1
-  fi
-
-  if [ -z "${VOYAGE_API_KEY:-}" ]; then
-    echo "⚠️  VOYAGE_API_KEY not set. Commands that call the API will fail."
-    echo "   Set it: export VOYAGE_API_KEY=your-key"
-    exit 1
-  fi
-
-  echo "🎬 Recording demo with vhs..."
-  vhs demo.tape
-  echo "✅ Demo GIF saved to demo.gif"
-
-elif [ "$METHOD" = "asciinema" ]; then
-  if ! command -v asciinema &>/dev/null; then
-    echo "❌ asciinema not found. Install: brew install asciinema"
-    exit 1
-  fi
-
-  CAST_FILE="demo.cast"
-  echo "🎬 Recording demo with asciinema..."
-  echo "   Run the following commands, then press Ctrl-D when done:"
-  echo ""
-  echo "   vai --version"
-  echo "   vai models --type embedding"
-  echo '   vai embed "What is MongoDB Atlas?"'
-  echo "   vai explain embeddings"
-  echo '   vai similarity "MongoDB is great" "MongoDB Atlas is amazing"'
-  echo ""
-
-  asciinema rec "$CAST_FILE"
-  echo "✅ Recording saved to $CAST_FILE"
-  echo ""
-  echo "Convert to GIF with agg or svg-term-cli:"
-  echo "  agg $CAST_FILE demo.gif"
-  echo "  # or"
-  echo "  npx svg-term-cli --in $CAST_FILE --out demo.svg --window"
-
-else
-  echo "Unknown method: $METHOD"
-  echo "Usage: $0 [vhs|asciinema]"
-  exit 1
-fi

package/test/commands/about.test.js

@@ -1,23 +0,0 @@
-'use strict';
-
-const { describe, it } = require('node:test');
-const assert = require('node:assert/strict');
-const { Command } = require('commander');
-const { registerAbout } = require('../../src/commands/about');
-
-describe('about command', () => {
-  it('registers correctly on a program', () => {
-    const program = new Command();
-    registerAbout(program);
-    const aboutCmd = program.commands.find(c => c.name() === 'about');
-    assert.ok(aboutCmd, 'about command should be registered');
-  });
-
-  it('has --json option', () => {
-    const program = new Command();
-    registerAbout(program);
-    const aboutCmd = program.commands.find(c => c.name() === 'about');
-    const optionNames = aboutCmd.options.map(o => o.long);
-    assert.ok(optionNames.includes('--json'), 'should have --json option');
-  });
-});