voyageai-cli 1.6.1 → 1.7.0

package/README.md

@@ -1,12 +1,13 @@
 # voyageai-cli
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mrlynn/voyageai-cli/main/voyageai-cli.png" alt="voyageai-cli" width="600" />
+</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)
 
 CLI for [Voyage AI](https://www.mongodb.com/docs/voyageai/) embeddings, reranking, and [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). Pure Node.js — no Python required.
 
-<!-- TODO: Add demo GIF -->
-<!-- ![vai demo](demo.gif) -->
-
 Generate embeddings, rerank search results, store vectors in Atlas, and run semantic search — all from the command line.
 
 > **⚠️ Disclaimer:** This is an independent, community-built tool. It is **not** an official product of MongoDB, Inc. or Voyage AI. It is not supported, endorsed, or maintained by either company. For official documentation, support, and products, visit:

package/package.json

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

package/src/cli.js

@@ -18,6 +18,7 @@ const { registerExplain } = require('./commands/explain');
 const { registerSimilarity } = require('./commands/similarity');
 const { registerIngest } = require('./commands/ingest');
 const { registerCompletions } = require('./commands/completions');
+const { registerPlayground } = require('./commands/playground');
 const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
 
 const version = getVersion();
@@ -40,6 +41,7 @@ registerExplain(program);
 registerSimilarity(program);
 registerIngest(program);
 registerCompletions(program);
+registerPlayground(program);
 
 // Append disclaimer to all help output
 program.addHelpText('after', `

package/src/commands/playground.js

@@ -0,0 +1,236 @@
+'use strict';
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { exec } = require('child_process');
+
+/**
+ * Register the playground command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerPlayground(program) {
+  program
+    .command('playground')
+    .description('Launch interactive web playground for Voyage AI')
+    .option('-p, --port <port>', 'Port to serve on', '3333')
+    .option('--no-open', 'Skip auto-opening browser')
+    .action(async (opts) => {
+      const port = parseInt(opts.port, 10) || 3333;
+      const server = createPlaygroundServer();
+
+      server.listen(port, () => {
+        const url = `http://localhost:${port}`;
+        console.log(`🧭 Playground running at ${url} — Press Ctrl+C to stop`);
+
+        if (opts.open !== false) {
+          openBrowser(url);
+        }
+      });
+
+      server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          console.error(`Error: Port ${port} is already in use. Try --port <other-port>`);
+        } else {
+          console.error(`Server error: ${err.message}`);
+        }
+        process.exit(1);
+      });
+
+      // Graceful shutdown
+      const shutdown = () => {
+        console.log('\n🧭 Playground stopped.');
+        server.close(() => process.exit(0));
+        // Force exit after 2s if connections linger
+        setTimeout(() => process.exit(0), 2000);
+      };
+      process.on('SIGINT', shutdown);
+      process.on('SIGTERM', shutdown);
+    });
+}
+
+/**
+ * Create the playground HTTP server (exported for testing).
+ * @returns {http.Server}
+ */
+function createPlaygroundServer() {
+  const { getApiBase, requireApiKey, generateEmbeddings } = require('../lib/api');
+  const { MODEL_CATALOG } = require('../lib/catalog');
+  const { cosineSimilarity } = require('../lib/math');
+  const { getConfigValue } = require('../lib/config');
+
+  const htmlPath = path.join(__dirname, '..', 'playground', 'index.html');
+
+  const server = http.createServer(async (req, res) => {
+    // CORS headers for local dev
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    try {
+      // Serve HTML
+      if (req.method === 'GET' && (req.url === '/' || req.url === '/index.html')) {
+        const html = fs.readFileSync(htmlPath, 'utf8');
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(html);
+        return;
+      }
+
+      // API: Models
+      if (req.method === 'GET' && req.url === '/api/models') {
+        const models = MODEL_CATALOG.filter(m => !m.legacy);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ models }));
+        return;
+      }
+
+      // API: Config
+      if (req.method === 'GET' && req.url === '/api/config') {
+        const key = process.env.VOYAGE_API_KEY || getConfigValue('apiKey');
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          baseUrl: getApiBase(),
+          hasKey: !!key,
+        }));
+        return;
+      }
+
+      // Parse JSON body for POST routes
+      if (req.method === 'POST') {
+        const body = await readBody(req);
+        let parsed;
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid JSON body' }));
+          return;
+        }
+
+        // API: Embed
+        if (req.url === '/api/embed') {
+          const { texts, model, inputType, dimensions } = parsed;
+          if (!texts || !Array.isArray(texts) || texts.length === 0) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'texts must be a non-empty array' }));
+            return;
+          }
+          const result = await generateEmbeddings(texts, {
+            model: model || undefined,
+            inputType: inputType || undefined,
+            dimensions: dimensions || undefined,
+          });
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+          return;
+        }
+
+        // API: Rerank
+        if (req.url === '/api/rerank') {
+          const { query, documents, model, topK } = parsed;
+          if (!query || !documents || !Array.isArray(documents)) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'query and documents are required' }));
+            return;
+          }
+          const { apiRequest } = require('../lib/api');
+          const rerankBody = {
+            query,
+            documents,
+            model: model || 'rerank-2.5',
+          };
+          if (topK) rerankBody.top_k = topK;
+          const result = await apiRequest('/rerank', rerankBody);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+          return;
+        }
+
+        // API: Similarity
+        if (req.url === '/api/similarity') {
+          const { texts, model } = parsed;
+          if (!texts || !Array.isArray(texts) || texts.length < 2) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'texts must be an array with at least 2 items' }));
+            return;
+          }
+          const result = await generateEmbeddings(texts, { model: model || undefined });
+          const embeddings = result.data.map(d => d.embedding);
+
+          // Compute pairwise similarity matrix
+          const matrix = [];
+          for (let i = 0; i < embeddings.length; i++) {
+            const row = [];
+            for (let j = 0; j < embeddings.length; j++) {
+              row.push(i === j ? 1.0 : cosineSimilarity(embeddings[i], embeddings[j]));
+            }
+            matrix.push(row);
+          }
+
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            matrix,
+            embeddings: result.data,
+            usage: result.usage,
+            model: result.model,
+          }));
+          return;
+        }
+      }
+
+      // 404
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Not found' }));
+
+    } catch (err) {
+      // Catch API errors that call process.exit — we override for playground
+      console.error(`Playground API error: ${err.message}`);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message || 'Internal server error' }));
+      }
+    }
+  });
+
+  return server;
+}
+
+/**
+ * Read the full request body as a string.
+ * @param {http.IncomingMessage} req
+ * @returns {Promise<string>}
+ */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', chunk => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Open a URL in the default browser (cross-platform).
+ * @param {string} url
+ */
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+  if (platform === 'darwin') cmd = `open "${url}"`;
+  else if (platform === 'win32') cmd = `start "${url}"`;
+  else cmd = `xdg-open "${url}"`;
+
+  exec(cmd, (err) => {
+    if (err) {
+      console.log(`Could not auto-open browser. Visit: ${url}`);
+    }
+  });
+}
+
+module.exports = { registerPlayground, createPlaygroundServer };

package/src/lib/ui.js

@@ -1,8 +1,32 @@
 'use strict';
 
 const pc = require('picocolors');
-const oraModule = require('ora');
-const ora = oraModule.default || oraModule;
+
+// ora v9 is ESM-only. Use dynamic import with a sync fallback for environments
+// that don't support top-level require() of ESM (Node 18).
+let _ora = null;
+
+/**
+ * Get the ora spinner function. Lazy-loaded via dynamic import.
+ * Returns a no-op fallback if ora can't be loaded (Node 18 CJS compat).
+ * @returns {Promise<Function>}
+ */
+async function getOra() {
+  if (_ora) return _ora;
+  try {
+    const mod = await import('ora');
+    _ora = mod.default || mod;
+  } catch {
+    // Fallback: no-op spinner for environments where ora can't load
+    _ora = ({ text }) => ({
+      start() { if (text) process.stderr.write(text + '\n'); return this; },
+      stop() { return this; },
+      succeed() { return this; },
+      fail() { return this; },
+    });
+  }
+  return _ora;
+}
 
 // Semantic color helpers
 const ui = {
@@ -40,8 +64,33 @@ const ui = {
     return s;
   },
 
-  // Spinner
-  spinner: (text) => ora({ text, color: 'cyan' }),
+  /**
+   * Create a spinner. Returns an object with start()/stop().
+   * Because ora is loaded async, this returns a proxy that buffers
+   * the start call until ora is ready.
+   * @param {string} text
+   * @returns {{ start: Function, stop: Function }}
+   */
+  spinner: (text) => {
+    let realSpinner = null;
+    let started = false;
+    const proxy = {
+      start() {
+        started = true;
+        getOra().then(ora => {
+          realSpinner = ora({ text, color: 'cyan' });
+          if (started) realSpinner.start();
+        });
+        return proxy;
+      },
+      stop() {
+        started = false;
+        if (realSpinner) realSpinner.stop();
+        return proxy;
+      },
+    };
+    return proxy;
+  },
 };
 
 module.exports = ui;