voyageai-cli 1.10.0 → 1.11.0

package/package.json

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

package/src/cli.js

@@ -20,6 +20,7 @@ const { registerIngest } = require('./commands/ingest');
 const { registerCompletions } = require('./commands/completions');
 const { registerPlayground } = require('./commands/playground');
 const { registerBenchmark } = require('./commands/benchmark');
+const { registerAbout } = require('./commands/about');
 const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
 
 const version = getVersion();
@@ -44,6 +45,7 @@ registerIngest(program);
 registerCompletions(program);
 registerPlayground(program);
 registerBenchmark(program);
+registerAbout(program);
 
 // Append disclaimer to all help output
 program.addHelpText('after', `

package/src/commands/about.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const pc = require('picocolors');
+
+/**
+ * Register the about command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerAbout(program) {
+  program
+    .command('about')
+    .description('About this tool and its author')
+    .option('--json', 'Machine-readable JSON output')
+    .action((opts) => {
+      if (opts.json) {
+        console.log(JSON.stringify({
+          tool: 'voyageai-cli',
+          binary: 'vai',
+          author: {
+            name: 'Michael Lynn',
+            role: 'Principal Staff Developer Advocate, MongoDB',
+            github: 'https://github.com/mrlynn',
+            website: 'https://mlynn.org',
+          },
+          links: {
+            npm: 'https://www.npmjs.com/package/voyageai-cli',
+            github: 'https://github.com/mrlynn/voyageai-cli',
+            docs: 'https://www.mongodb.com/docs/voyageai/',
+          },
+          disclaimer: 'Community tool — not an official MongoDB or Voyage AI product.',
+        }, null, 2));
+        return;
+      }
+
+      console.log('');
+      console.log(`  ${pc.bold(pc.cyan('voyageai-cli'))} ${pc.dim('(vai)')}`);
+      console.log(`  ${pc.dim('Voyage AI embeddings, reranking & Atlas Vector Search CLI')}`);
+      console.log('');
+
+      // Author
+      console.log(`  ${pc.bold('Author')}`);
+      console.log(`  Michael Lynn`);
+      console.log(`  ${pc.dim('Principal Staff Developer Advocate · MongoDB')}`);
+      console.log(`  ${pc.dim('25+ years enterprise infrastructure · 10+ years at MongoDB')}`);
+      console.log('');
+
+      // About
+      console.log(`  ${pc.bold('About This Project')}`);
+      console.log(`  A community-built CLI for working with Voyage AI embeddings,`);
+      console.log(`  reranking, and MongoDB Atlas Vector Search. Created to help`);
+      console.log(`  developers explore, benchmark, and integrate Voyage AI models`);
+      console.log(`  into their applications — right from the terminal.`);
+      console.log('');
+
+      // Features
+      console.log(`  ${pc.bold('What You Can Do')}`);
+      console.log(`  ${pc.cyan('vai embed')}        Generate vector embeddings for text`);
+      console.log(`  ${pc.cyan('vai similarity')}   Compare texts with cosine similarity`);
+      console.log(`  ${pc.cyan('vai rerank')}       Rerank documents against a query`);
+      console.log(`  ${pc.cyan('vai search')}       Vector search against Atlas collections`);
+      console.log(`  ${pc.cyan('vai store')}        Embed and store documents in Atlas`);
+      console.log(`  ${pc.cyan('vai benchmark')}    Compare model latency, ranking & costs`);
+      console.log(`  ${pc.cyan('vai explain')}      Learn about embeddings, vector search & more`);
+      console.log(`  ${pc.cyan('vai playground')}   Launch interactive web playground`);
+      console.log('');
+
+      // Links
+      console.log(`  ${pc.bold('Links')}`);
+      console.log(`  ${pc.dim('npm:')}     https://www.npmjs.com/package/voyageai-cli`);
+      console.log(`  ${pc.dim('GitHub:')}  https://github.com/mrlynn/voyageai-cli`);
+      console.log(`  ${pc.dim('Docs:')}    https://www.mongodb.com/docs/voyageai/`);
+      console.log(`  ${pc.dim('Author:')}  https://mlynn.org`);
+      console.log('');
+
+      // Disclaimer
+      console.log(`  ${pc.yellow('⚠ Community Tool Disclaimer')}`);
+      console.log(`  ${pc.dim('This tool is not an official product of MongoDB, Inc. or')}`);
+      console.log(`  ${pc.dim('Voyage AI. It is independently built and maintained by')}`);
+      console.log(`  ${pc.dim('Michael Lynn as a community resource. Not supported,')}`);
+      console.log(`  ${pc.dim('endorsed, or guaranteed by either company.')}`);
+      console.log('');
+    });
+}
+
+module.exports = { registerAbout };

package/src/commands/benchmark.js

@@ -21,6 +21,8 @@ const SAMPLE_TEXTS = [
   'GraphQL provides a flexible query language that lets clients request exactly the data they need.',
 ];
 
+// If you're reading this, you're either benchmarking or procrastinating.
+// Either way, we respect the hustle.
 const SAMPLE_QUERY = 'How do I search for similar documents using embeddings?';
 
 const SAMPLE_RERANK_DOCS = [

package/src/commands/store.js

@@ -170,6 +170,8 @@ async function handleBatchStore(opts) {
 
     const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
     client = c;
+    // insertMany: because life's too short for one document at a time.
+    // This is the MongoDB equivalent of "I'll have what everyone's having."
     const result = await collection.insertMany(docs);
 
     if (spin) spin.stop();

package/src/lib/api.js

@@ -78,6 +78,8 @@ async function apiRequest(endpoint, body) {
       body: JSON.stringify(body),
     });
 
+    // 429: The API said "slow down monkey" — respect the rate limit
+    // like you'd respect a $merge that's already running on your replica set.
     if (response.status === 429 && attempt < MAX_RETRIES) {
       const retryAfter = response.headers.get('Retry-After');
       const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt) * 1000;

package/src/lib/catalog.js

@@ -22,6 +22,8 @@ function getDefaultDimensions() {
   return getConfigValue('defaultDimensions') || DEFAULT_DIMENSIONS;
 }
 
+// The model catalog: like a wine list (I don't drink :-P), except every choice
+// leads to vectors instead of regret.
 /** @type {Array<{name: string, type: string, context: string, dimensions: string, price: string, bestFor: string}>} */
 const MODEL_CATALOG = [
   { name: 'voyage-4-large', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/1M tokens', bestFor: 'Best quality, multilingual', shortFor: 'Best quality' },

package/src/lib/math.js

@@ -3,6 +3,11 @@
 /**
  * Compute cosine similarity between two vectors.
  * cosine_sim(a, b) = dot(a, b) / (||a|| * ||b||)
+ *
+ * Fun fact: this is basically asking "how much do these two vectors
+ * vibe?" — 1.0 means soulmates, 0.0 means strangers at a party,
+ * -1.0 means they're in a Twitter argument.
+ *
  * @param {number[]} a
  * @param {number[]} b
  * @returns {number} Similarity score in [-1, 1]

package/src/playground/index.html

@@ -680,6 +680,57 @@ select:focus { outline: none; border-color: var(--accent); }
   margin-top: 4px;
 }
 
+/* About page */
+.about-container { max-width: 680px; margin: 0 auto; }
+.about-header { display: flex; gap: 24px; align-items: center; margin-bottom: 24px; }
+.about-avatar {
+  width: 120px; height: 120px;
+  border-radius: 50%;
+  border: 3px solid var(--accent);
+  box-shadow: 0 0 20px var(--accent-glow);
+  flex-shrink: 0;
+}
+.about-name { font-size: 24px; font-weight: 700; color: var(--text); }
+.about-role { font-size: 14px; color: var(--accent); margin-top: 4px; }
+.about-links { display: flex; gap: 12px; margin-top: 8px; }
+.about-links a {
+  color: var(--text-dim);
+  font-size: 13px;
+  text-decoration: none;
+  transition: color 0.2s;
+}
+.about-links a:hover { color: var(--accent); }
+.about-section { margin-bottom: 24px; }
+.about-section-title {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--accent);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  margin-bottom: 8px;
+}
+.about-text { font-size: 14px; line-height: 1.8; color: var(--text); }
+.about-text a { color: var(--accent); text-decoration: none; }
+.about-text a:hover { text-decoration: underline; }
+.about-disclaimer {
+  background: rgba(255, 215, 61, 0.08);
+  border: 1px solid rgba(255, 215, 61, 0.2);
+  border-radius: var(--radius);
+  padding: 16px 20px;
+  margin-top: 24px;
+}
+.about-disclaimer-title {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--warning);
+  margin-bottom: 6px;
+}
+.about-disclaimer-text {
+  font-size: 13px;
+  line-height: 1.7;
+  color: var(--text-dim);
+}
+
 @media (max-width: 768px) {
   .compare-grid, .search-results { grid-template-columns: 1fr; }
   .nav { padding: 0 12px; }
@@ -711,6 +762,7 @@ select:focus { outline: none; border-color: var(--accent); }
   <button class="tab-btn" data-tab="search">🔍 Search</button>
   <button class="tab-btn" data-tab="benchmark">⏱ Benchmark</button>
   <button class="tab-btn" data-tab="explore">📚 Explore</button>
+  <button class="tab-btn" data-tab="about">ℹ️ About</button>
 </div>
 
 <div class="main">
@@ -1001,6 +1053,73 @@ Reranking models rescore initial search results to improve relevance ordering.</
 
 </div>
 
+<!-- ========== ABOUT TAB ========== -->
+<div class="tab-panel" id="tab-about">
+  <div class="about-container">
+    <div class="card">
+      <div class="about-header">
+        <img src="https://avatars.githubusercontent.com/u/192552?v=4" alt="Michael Lynn" class="about-avatar">
+        <div>
+          <div class="about-name">Michael Lynn</div>
+          <div class="about-role">Principal Staff Developer Advocate · MongoDB</div>
+          <div class="about-links">
+            <a href="https://github.com/mrlynn" target="_blank" rel="noopener">🔗 GitHub</a>
+            <a href="https://mlynn.org" target="_blank" rel="noopener">🌐 mlynn.org</a>
+            <a href="https://www.npmjs.com/package/voyageai-cli" target="_blank" rel="noopener">📦 npm</a>
+          </div>
+        </div>
+      </div>
+
+      <div class="about-section">
+        <div class="about-section-title">About This Project</div>
+        <div class="about-text">
+          <strong>voyageai-cli</strong> (<code style="color:var(--accent);">vai</code>) is a community-built command-line tool for working with
+          <a href="https://www.mongodb.com/docs/voyageai/" target="_blank">Voyage AI</a> embeddings, reranking, and
+          <a href="https://www.mongodb.com/products/platform/atlas-vector-search" target="_blank">MongoDB Atlas Vector Search</a>.
+          It was created to make it easier for developers to explore, benchmark, and integrate
+          Voyage AI models into their applications — right from the terminal or this playground.
+        </div>
+      </div>
+
+      <div class="about-section">
+        <div class="about-section-title">About Michael</div>
+        <div class="about-text">
+          Michael Lynn is a Principal Staff Developer Advocate at MongoDB with 25+ years in enterprise
+          infrastructure and over a decade at MongoDB. He focuses on strategic developer relations,
+          creating educational content around Vector Search, AI enablement, and developer tooling.
+          He builds tools like this to help developers get hands-on with new technology faster.
+        </div>
+      </div>
+
+      <div class="about-section">
+        <div class="about-section-title">What You Can Do Here</div>
+        <div class="about-text">
+          <strong>⚡ Embed</strong> — Generate vector embeddings for any text<br>
+          <strong>⚖️ Compare</strong> — Measure cosine similarity between texts<br>
+          <strong>🔍 Search</strong> — Semantic search with optional reranking<br>
+          <strong>⏱ Benchmark</strong> — Compare model latency, ranking quality, and costs<br>
+          <strong>📚 Explore</strong> — Learn about embeddings, vector search, RAG, and more
+        </div>
+      </div>
+
+      <div class="about-disclaimer">
+        <div class="about-disclaimer-title">⚠️ Community Tool Disclaimer</div>
+        <div class="about-disclaimer-text">
+          This tool is <strong>not</strong> an official product of MongoDB, Inc. or Voyage AI.
+          It is independently built and maintained by Michael Lynn as a community resource.
+          It is not supported, endorsed, or guaranteed by either company. Use at your own discretion.
+          For official documentation, visit
+          <a href="https://www.mongodb.com/docs/voyageai/" target="_blank" style="color:var(--warning);">mongodb.com/docs/voyageai</a>.
+        </div>
+      </div>
+    </div>
+
+    <div style="text-align:center;margin-top:16px;font-size:12px;color:var(--text-muted);">
+      Made with ☕ and curiosity · <a href="https://github.com/mrlynn/voyageai-cli" target="_blank" style="color:var(--text-dim);">Source on GitHub</a>
+    </div>
+  </div>
+</div>
+
 <!-- ========== EXPLORE TAB ========== -->
 <div class="tab-panel" id="tab-explore">
   <div style="margin-bottom:16px;">

package/test/commands/about.test.js

@@ -0,0 +1,23 @@
+'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');
+  });
+});