voyageai-cli 1.19.0 → 1.20.0

package/README.md

@@ -4,21 +4,130 @@
   <img src="https://raw.githubusercontent.com/mrlynn/voyageai-cli/main/demo-readme.gif" alt="voyageai-cli demo" width="800" />
 </p>
 
-[![CI](https://github.com/mrlynn/voyageai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mrlynn/voyageai-cli/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/voyageai-cli.svg)](https://www.npmjs.com/package/voyageai-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/node/v/voyageai-cli.svg)](https://nodejs.org)
+[![CI](https://github.com/mrlynn/voyageai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mrlynn/voyageai-cli/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/voyageai-cli.svg)](https://www.npmjs.com/package/voyageai-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/node/v/voyageai-cli.svg)](https://nodejs.org) [![GitHub release](https://img.shields.io/github/v/release/mrlynn/voyageai-cli?label=Desktop%20App)](https://github.com/mrlynn/voyageai-cli/releases)
 
-The fastest path from documents to semantic search. Chunk files, generate [Voyage AI](https://www.mongodb.com/docs/voyageai/) embeddings, store in [MongoDB Atlas](https://www.mongodb.com/docs/atlas/atlas-vector-search/), and query with two-stage retrieval — all from the terminal.
-
-**21 commands · 312 tests · 5 chunking strategies · End-to-end RAG pipeline**
+The fastest path from documents to semantic search. Chunk files, generate [Voyage AI](https://www.mongodb.com/docs/voyageai/) embeddings, store in [MongoDB Atlas](https://www.mongodb.com/docs/atlas/atlas-vector-search/), and query with two-stage retrieval — from the terminal, your browser, or a desktop app.
 
 > **⚠️ Disclaimer:** This is an independent, community-built tool — **not** an official product of MongoDB, Inc. or Voyage AI. See [Disclaimer](#disclaimer) for details.
 
-## Install
+---
+
+## Three Ways to Use It
+
+<table>
+<tr>
+<td align="center" width="33%">
+<h3>🖥️ CLI</h3>
+<code>vai</code><br/><br/>
+22 commands · 5 chunking strategies<br/>
+End-to-end RAG pipeline from your terminal<br/><br/>
+<code>npm install -g voyageai-cli</code>
+</td>
+<td align="center" width="33%">
+<h3>🌐 Web Playground</h3>
+<code>vai playground</code><br/><br/>
+7 interactive tabs for embedding,<br/>
+comparing, searching, and benchmarking<br/><br/>
+<em>Launches in your browser</em>
+</td>
+<td align="center" width="33%">
+<h3>💻 Desktop App</h3>
+Standalone Electron app<br/><br/>
+Secure keychain storage, dark/light themes,<br/>
+MongoDB LeafyGreen design system<br/><br/>
+<a href="https://github.com/mrlynn/voyageai-cli/releases">Download from GitHub Releases</a>
+</td>
+</tr>
+</table>
+
+---
+
+## Table of Contents
+
+- [Desktop App](#desktop-app)
+- [Web Playground](#web-playground)
+- [CLI — Quick Start](#cli--quick-start)
+  - [Install](#install)
+  - [5-Minute RAG Pipeline](#5-minute-rag-pipeline)
+  - [Project Config](#project-config)
+  - [Core Workflow](#core-workflow)
+  - [Individual Commands](#individual-commands)
+  - [Models & Benchmarks](#models--benchmarks)
+  - [Benchmarking Your Data](#benchmarking-your-data)
+  - [Learn](#learn)
+  - [Environment & Auth](#environment--auth)
+  - [Shell Completions](#shell-completions)
+  - [All Commands](#all-commands)
+- [Screenshots](#screenshots)
+- [Requirements](#requirements)
+- [Author](#author)
+- [Disclaimer](#disclaimer)
+- [License](#license)
+
+---
+
+## Desktop App
+
+A standalone desktop application built with Electron and the MongoDB LeafyGreen design system. Everything the CLI and playground can do — in a native app experience.
+
+[![Download Latest Release](https://img.shields.io/github/v/release/mrlynn/voyageai-cli?label=Download&style=for-the-badge)](https://github.com/mrlynn/voyageai-cli/releases)
+
+### Key Features
+
+- **🔐 Secure API Key Storage** — Stores your Voyage AI API key and MongoDB URI in the OS keychain (macOS Keychain, Windows Credential Vault, Linux Secret Service). No plaintext config files.
+- **🎨 Dark & Light Themes** — Full theme support with automatic system detection, built on MongoDB's LeafyGreen design tokens.
+- **🍃 MongoDB LeafyGreen UI** — Native MongoDB look & feel with LeafyGreen components and iconography throughout.
+- **📱 Sidebar Navigation** — Clean, collapsible sidebar for quick access to all features: Embed, Compare, Search, Benchmark, Explore, Settings, and more.
+- **⚡ All Playground Features** — Every tab from the web playground, plus desktop-native conveniences like system tray integration.
+
+### Installation
+
+Download the latest release for your platform from [GitHub Releases](https://github.com/mrlynn/voyageai-cli/releases):
+
+| Platform | Download |
+|----------|----------|
+| macOS (Apple Silicon) | `.dmg` |
+| macOS (Intel) | `.dmg` |
+| Windows | `.exe` installer |
+| Linux | `.AppImage` / `.deb` |
+
+---
+
+## Web Playground
+
+An interactive, browser-based interface for exploring Voyage AI embeddings without writing code. Ships with the CLI — just run:
+
+```bash
+vai playground
+```
+
+Your default browser opens with a full-featured UI organized into **7 tabs**:
+
+| Tab | What It Does |
+|-----|-------------|
+| **Embed** | Generate embeddings for any text, inspect vectors, adjust dimensions and models |
+| **Compare** | Side-by-side similarity comparison of two or more texts with cosine similarity scores |
+| **Search** | Connect to MongoDB Atlas and run vector similarity searches with filters and reranking |
+| **Benchmark** | Compare model latency, cost, and quality across the Voyage 4 family on your own data |
+| **Explore** | Visualize embedding spaces with dimensionality reduction (PCA/t-SNE) and clustering |
+| **About** | Project info, links, and version details |
+| **Settings** | Configure API keys, MongoDB URI, default model, and preferences |
+
+The playground connects to the same backend as the CLI. Any API keys or MongoDB URIs you've configured via `vai config` are available automatically.
+
+---
+
+## CLI — Quick Start
+
+**22 commands · 312 tests · 5 chunking strategies · End-to-end RAG pipeline**
+
+### Install
 
 ```bash
 npm install -g voyageai-cli
 ```
 
-## 5-Minute RAG Pipeline
+### 5-Minute RAG Pipeline
 
 Go from a folder of documents to a searchable vector database:
 
@@ -39,7 +148,7 @@ vai query "How do I configure replica sets?" --db myapp --collection knowledge
 
 That's it. Documents chunked, embedded with `voyage-4-large`, stored in Atlas with metadata, vector index created, and searchable with reranking.
 
-## Project Config
+### Project Config
 
 Stop typing `--db myapp --collection docs` on every command:
 
@@ -64,9 +173,9 @@ Creates `.vai.json` with your defaults — model, database, collection, chunking
 }
 ```
 
-## Core Workflow
+### Core Workflow
 
-### `vai pipeline` — Chunk → embed → store
+#### `vai pipeline` — Chunk → embed → store
 
 The end-to-end command. Takes files or directories, chunks them, embeds in batches, stores in MongoDB Atlas.
 
@@ -86,7 +195,7 @@ vai pipeline ./docs/ --strategy markdown --chunk-size 1024 --overlap 100
 
 Supports: `.txt`, `.md`, `.html`, `.json`, `.jsonl`, `.pdf` (optional `pdf-parse` dependency). Auto-detects markdown files for heading-aware chunking.
 
-### `vai query` — Search + rerank
+#### `vai query` — Search + rerank
 
 Two-stage retrieval in one command: embed query → vector search → rerank → results.
 
@@ -101,7 +210,7 @@ vai query "auth setup" --no-rerank
 vai query "performance tuning" --filter '{"category": "guides"}' --top-k 10
 ```
 
-### `vai chunk` — Document chunking
+#### `vai chunk` — Document chunking
 
 Standalone chunking for when you need control over the pipeline.
 
@@ -118,7 +227,7 @@ vai chunk ./docs/ --dry-run
 
 Five strategies: `fixed`, `sentence`, `paragraph`, `recursive` (default), `markdown`.
 
-### `vai estimate` — Cost estimator
+#### `vai estimate` — Cost estimator
 
 Compare symmetric vs. asymmetric embedding strategies before committing.
 
@@ -128,7 +237,7 @@ vai estimate --docs 10M --queries 100M --months 12
 
 Shows cost breakdown for every Voyage 4 model combination, including asymmetric retrieval (embed docs with `voyage-4-large`, query with `voyage-4-lite` — same quality, fraction of the cost).
 
-## Individual Commands
+### Individual Commands
 
 For when you need fine-grained control:
 
@@ -158,7 +267,7 @@ vai index create --db myapp --collection docs --field embedding
 vai index list --db myapp --collection docs
 ```
 
-## Models & Benchmarks
+### Models & Benchmarks
 
 ```bash
 # List models with architecture and shared space info
@@ -168,7 +277,7 @@ vai models --wide
 vai models --benchmarks
 ```
 
-### Voyage 4 Family
+#### Voyage 4 Family
 
 | Model | Architecture | Price/1M tokens | RTEB Score | Best For |
 |-------|-------------|----------------|------------|----------|
@@ -179,7 +288,7 @@ vai models --benchmarks
 
 **Shared embedding space:** All Voyage 4 models produce compatible embeddings. Embed docs with `voyage-4-large`, query with `voyage-4-lite` — no re-vectorization needed.
 
-### Competitive Landscape (RTEB NDCG@10)
+#### Competitive Landscape (RTEB NDCG@10)
 
 | Model | Score |
 |-------|-------|
@@ -192,7 +301,7 @@ vai models --benchmarks
 
 Also available: `voyage-code-3` (code), `voyage-finance-2` (finance), `voyage-law-2` (legal), `rerank-2.5` / `rerank-2.5-lite`.
 
-## Benchmarking Your Data
+### Benchmarking Your Data
 
 Published benchmarks measure average quality across standardized datasets. `vai benchmark` measures what matters for **your** use case:
 
@@ -213,7 +322,7 @@ vai benchmark quantization --model voyage-4-large --dtypes float,int8,ubinary
 vai benchmark cost --tokens 500 --volumes 100,1000,10000,100000
 ```
 
-## Learn
+### Learn
 
 Interactive explanations of key concepts:
 
@@ -230,7 +339,7 @@ vai explain models            # How to choose the right model
 
 17 topics covering embeddings, reranking, vector search, RAG, and more.
 
-## Environment & Auth
+### Environment & Auth
 
 | Variable | Required For | Description |
 |----------|-------------|-------------|
@@ -245,7 +354,7 @@ echo "your-key" | vai config set api-key --stdin
 vai config set mongodb-uri "mongodb+srv://..."
 ```
 
-## Shell Completions
+### Shell Completions
 
 ```bash
 # Bash
@@ -256,9 +365,9 @@ mkdir -p ~/.zsh/completions
 vai completions zsh > ~/.zsh/completions/_vai
 ```
 
-Covers all 21 commands, subcommands, flags, model names, and explain topics.
+Covers all 22 commands, subcommands, flags, model names, and explain topics.
 
-## All Commands
+### All Commands
 
 | Command | Description |
 |---------|-------------|
@@ -283,6 +392,28 @@ Covers all 21 commands, subcommands, flags, model names, and explain topics.
 | `vai demo` | Guided walkthrough |
 | `vai completions` | Shell completion scripts |
 | `vai about` | About this tool |
+| `vai version` | Print version |
+
+---
+
+## Screenshots
+
+### Desktop App — Dark Theme
+![Vai - Embed Tab (Dark)](screenshots/vai-dark-embed.png)
+
+### Desktop App — Settings
+![Vai - Settings (Dark)](screenshots/vai-dark-settings.png)
+
+### Desktop App — Light Theme
+![Vai - Embed Tab (Light)](screenshots/vai-light-embed.png)
+
+### Search & Reranking
+![Vai - Search Tab](screenshots/vai-dark-search.png)
+
+### Benchmark
+![Vai - Benchmark Tab](screenshots/vai-dark-benchmark.png)
+
+---
 
 ## Requirements
 
@@ -290,6 +421,10 @@ Covers all 21 commands, subcommands, flags, model names, and explain topics.
 - [MongoDB Atlas](https://www.mongodb.com/atlas) account (free tier works)
 - [Voyage AI model API key](https://www.mongodb.com/docs/voyageai/management/api-keys/) (created in Atlas)
 
+## Author
+
+Built by [Michael Lynn](https://github.com/mrlynn), Principal Staff Developer Advocate at [MongoDB](https://www.mongodb.com).
+
 ## Disclaimer
 
 This is a community tool and is not affiliated with, endorsed by, or supported by MongoDB, Inc. or Voyage AI. All trademarks belong to their respective owners.
@@ -300,4 +435,4 @@ For official documentation and support:
 
 ## License
 
-MIT
+[MIT](LICENSE) © [Michael Lynn](https://github.com/mrlynn)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"
@@ -19,6 +19,12 @@
   ],
   "author": "Michael Lynn",
   "license": "MIT",
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/mrlynn/voyageai-cli"

package/src/cli.js

@@ -26,6 +26,7 @@ const { registerChunk } = require('./commands/chunk');
 const { registerQuery } = require('./commands/query');
 const { registerPipeline } = require('./commands/pipeline');
 const { registerEval } = require('./commands/eval');
+const { registerApp } = require('./commands/app');
 const { registerAbout } = require('./commands/about');
 const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
 
@@ -57,6 +58,7 @@ registerChunk(program);
 registerQuery(program);
 registerPipeline(program);
 registerEval(program);
+registerApp(program);
 registerAbout(program);
 
 // Append disclaimer to all help output

package/src/commands/app.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const { execSync, spawn } = require('child_process');
+const https = require('https');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Fetch JSON from a URL (Node built-in https).
+ * Returns a Promise that resolves with the parsed JSON.
+ */
+function fetchJSON(url) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      headers: { 'User-Agent': 'voyageai-cli' },
+    };
+    https.get(url, options, (res) => {
+      // Follow redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchJSON(res.headers.location).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`GitHub API returned status ${res.statusCode}`));
+      }
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); }
+        catch (e) { reject(e); }
+      });
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Open a URL in the default browser (cross-platform, no dependencies).
+ */
+function openInBrowser(url) {
+  const plat = process.platform;
+  if (plat === 'darwin') spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+  else if (plat === 'win32') spawn('cmd', ['/c', 'start', url], { stdio: 'ignore', detached: true }).unref();
+  else spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+}
+
+/**
+ * Register the app command — launches the Electron desktop app.
+ * @param {import('commander').Command} program
+ */
+function registerApp(program) {
+  program
+    .command('app')
+    .description('Launch the Voyage AI Playground desktop app (Electron)')
+    .option('--install', 'Install Electron dependencies first')
+    .option('--dev', 'Run in development mode with DevTools')
+    .option('--download', 'Download the latest desktop app release for your platform')
+    .option('--version', 'Print the app/CLI version')
+    .action(async (opts) => {
+      // --version: print version and exit
+      if (opts.version) {
+        const pkg = require(path.join(__dirname, '..', '..', 'package.json'));
+        console.log(`voyageai-cli v${pkg.version}`);
+        return;
+      }
+
+      // --download: fetch latest GitHub release and open download URL
+      if (opts.download) {
+        const releaseUrl = 'https://api.github.com/repos/mrlynn/voyageai-cli/releases/latest';
+        try {
+          console.log('🔍 Checking for the latest desktop app release...');
+          const release = await fetchJSON(releaseUrl);
+
+          const extMap = { darwin: '.dmg', win32: '.exe', linux: '.AppImage' };
+          const ext = extMap[process.platform];
+
+          const asset = ext && release.assets
+            ? release.assets.find((a) => a.name.endsWith(ext))
+            : null;
+
+          if (asset) {
+            console.log(`\n✅ Found release: ${release.tag_name || release.name}`);
+            console.log(`📦 Asset: ${asset.name}`);
+            console.log(`🔗 ${asset.browser_download_url}\n`);
+            console.log('Opening download in your browser...');
+            openInBrowser(asset.browser_download_url);
+          } else {
+            console.log(
+              "No desktop app release found for your platform. Run 'vai playground' for the web version."
+            );
+          }
+        } catch (err) {
+          console.error(
+            "No desktop app release found. Run 'vai playground' for the web version."
+          );
+          if (process.env.DEBUG) console.error(err);
+        }
+        return;
+      }
+      const electronDir = path.join(__dirname, '..', '..', 'electron');
+      const electronPkg = path.join(electronDir, 'package.json');
+
+      if (!fs.existsSync(electronPkg)) {
+        console.error('❌ Electron app not found. Expected at:', electronDir);
+        process.exit(1);
+      }
+
+      // Check if electron is installed
+      const nodeModules = path.join(electronDir, 'node_modules', 'electron');
+      if (!fs.existsSync(nodeModules) || opts.install) {
+        console.log('📦 Installing Electron dependencies...');
+        try {
+          execSync('npm install', { cwd: electronDir, stdio: 'inherit' });
+        } catch (err) {
+          console.error('❌ Failed to install dependencies:', err.message);
+          process.exit(1);
+        }
+      }
+
+      // Find the electron binary
+      let electronBin;
+      let useNpx = false;
+      try {
+        electronBin = require(path.join(electronDir, 'node_modules', 'electron'));
+      } catch {
+        // Fallback: try npx
+        useNpx = true;
+      }
+
+      console.log('🧭 Launching Voyage AI Playground...');
+
+      let bin, args;
+      if (useNpx) {
+        bin = 'npx';
+        args = ['electron', electronDir];
+      } else {
+        bin = electronBin;
+        args = [electronDir];
+      }
+
+      if (opts.dev) args.push('--dev');
+      const child = spawn(bin, args, {
+        cwd: electronDir,
+        stdio: 'inherit',
+        env: { ...process.env },
+        detached: process.platform !== 'win32',
+      });
+
+      // Detach — don't block the terminal
+      child.unref();
+
+      // Give it a moment to start, then exit CLI
+      setTimeout(() => process.exit(0), 500);
+    });
+}
+
+module.exports = { registerApp };

package/src/commands/completions.js

@@ -19,7 +19,7 @@ _vai_completions() {
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
   # Top-level commands
-  commands="embed rerank store search index models ping config demo explain similarity ingest estimate init chunk query pipeline eval completions help"
+  commands="embed rerank store search index models ping config demo explain similarity ingest estimate init chunk query pipeline eval app completions help"
 
   # Subcommands
   local index_subs="create list delete"
@@ -91,7 +91,7 @@ _vai_completions() {
       return 0
       ;;
     explain)
-      COMPREPLY=( \$(compgen -W "embeddings reranking vector-search rag cosine-similarity two-stage-retrieval input-type models api-keys api-access batch-processing --help" -- "\$cur") )
+      COMPREPLY=( \$(compgen -W "embeddings reranking vector-search rag cosine-similarity two-stage-retrieval input-type models api-keys api-access batch-processing quantization benchmarking mixture-of-experts shared-embedding-space rteb-benchmarks voyage-4-nano rerank-eval --help" -- "\$cur") )
       return 0
       ;;
     similarity)
@@ -123,7 +123,11 @@ _vai_completions() {
       return 0
       ;;
     eval)
-      COMPREPLY=( \$(compgen -W "--test-set --db --collection --index --field --model --dimensions --limit --k-values --rerank --no-rerank --rerank-model --text-field --id-field --compare --json --quiet --help" -- "\$cur") )
+      COMPREPLY=( \$(compgen -W "--test-set --mode --db --collection --index --field --model --models --dimensions --limit --k-values --rerank --no-rerank --rerank-model --top-k --text-field --id-field --compare --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    app)
+      COMPREPLY=( \$(compgen -W "--install --dev --help" -- "\$cur") )
       return 0
       ;;
     completions)
@@ -201,7 +205,8 @@ _vai() {
     'chunk:Chunk documents for embedding'
     'query:Search + rerank in one shot'
     'pipeline:Chunk, embed, and store documents'
-    'eval:Evaluate retrieval quality (MRR, NDCG, recall)'
+    'eval:Evaluate retrieval & reranking quality (MRR, NDCG, recall)'
+    'app:Launch the desktop app (Electron)'
     'completions:Generate shell completion scripts'
     'help:Display help for command'
   )
@@ -210,7 +215,7 @@ _vai() {
   models=(voyage-4-large voyage-4 voyage-4-lite voyage-code-3 voyage-finance-2 voyage-law-2 voyage-multimodal-3.5 rerank-2.5 rerank-2.5-lite)
 
   local -a explain_topics
-  explain_topics=(embeddings reranking vector-search rag cosine-similarity two-stage-retrieval input-type models api-keys api-access batch-processing)
+  explain_topics=(embeddings reranking vector-search rag cosine-similarity two-stage-retrieval input-type models api-keys api-access batch-processing quantization benchmarking mixture-of-experts shared-embedding-space rteb-benchmarks voyage-4-nano rerank-eval)
 
   _arguments -C \\
     '(-V --version)'{-V,--version}'[output the version number]' \\
@@ -483,23 +488,31 @@ _vai() {
         eval)
           _arguments \\
             '--test-set[JSONL test set file]:file:_files' \\
+            '--mode[Evaluation mode]:mode:(retrieval rerank)' \\
             '--db[Database name]:database:' \\
             '--collection[Collection name]:collection:' \\
             '--index[Vector search index]:index:' \\
             '--field[Embedding field]:field:' \\
-            '(-m --model)'{-m,--model}'[Embedding model]:model:(\$models)' \\
+            '(-m --model)'{-m,--model}'[Embedding/rerank model]:model:(\$models)' \\
+            '--models[Compare multiple rerank models]:models:' \\
             '(-d --dimensions)'{-d,--dimensions}'[Output dimensions]:dims:' \\
             '(-l --limit)'{-l,--limit}'[Search candidates]:limit:' \\
             '(-k --k-values)'{-k,--k-values}'[K values for metrics]:values:' \\
             '--rerank[Enable reranking]' \\
             '--no-rerank[Skip reranking]' \\
             '--rerank-model[Reranking model]:model:' \\
+            '--top-k[Top-K results from reranker]:k:' \\
             '--text-field[Document text field]:field:' \\
             '--id-field[Document ID field]:field:' \\
             '--compare[Compare configs]:configs:' \\
             '--json[JSON output]' \\
             '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
           ;;
+        app)
+          _arguments \\
+            '--install[Install Electron dependencies]' \\
+            '--dev[Run in development mode]'
+          ;;
         completions)
           _arguments \\
             '1:shell:(bash zsh)'