voyageai-cli 1.6.1 → 1.8.0

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/explanations.js

@@ -406,6 +406,48 @@ const concepts = {
       'vai embed --file document.txt --input-type document',
     ],
   },
+  benchmarking: {
+    title: 'Benchmarking & Model Selection',
+    summary: 'How to choose the right model for your use case',
+    content: [
+      `Choosing the right embedding or reranking model depends on your priorities:`,
+      `${pc.cyan('latency')}, ${pc.cyan('accuracy')}, ${pc.cyan('cost')}, or a balance of all three.`,
+      ``,
+      `${pc.bold('vai benchmark embed')} — Compare embedding models head-to-head:`,
+      `  Measures avg/p50/p95 latency, token usage, and cost per model.`,
+      `  ${pc.dim('vai benchmark embed --models voyage-4-large,voyage-4,voyage-4-lite --rounds 5')}`,
+      ``,
+      `${pc.bold('vai benchmark similarity')} — Test ranking quality on your data:`,
+      `  Embeds a query + corpus with each model, shows side-by-side top-K rankings.`,
+      `  If models agree on the top results, the cheaper one is likely sufficient.`,
+      `  ${pc.dim('vai benchmark similarity --query "your query" --file corpus.txt')}`,
+      ``,
+      `${pc.bold('vai benchmark rerank')} — Compare reranking models:`,
+      `  Measures latency and shows how models order the same documents.`,
+      `  ${pc.dim('vai benchmark rerank --query "your query" --documents-file docs.json')}`,
+      ``,
+      `${pc.bold('vai benchmark cost')} — Project monthly costs at scale:`,
+      `  Shows estimated cost for each model at different daily query volumes.`,
+      `  ${pc.dim('vai benchmark cost --tokens 500 --volumes 100,1000,10000,100000')}`,
+      ``,
+      `${pc.bold('vai benchmark batch')} — Find optimal batch size for ingestion:`,
+      `  Measures throughput (texts/sec) at different batch sizes.`,
+      `  ${pc.dim('vai benchmark batch --batch-sizes 1,5,10,25,50 --rounds 3')}`,
+      ``,
+      `${pc.bold('Decision framework:')}`,
+      `  1. Run ${pc.cyan('benchmark cost')} to eliminate models outside your budget`,
+      `  2. Run ${pc.cyan('benchmark embed')} to compare latency of affordable models`,
+      `  3. Run ${pc.cyan('benchmark similarity')} with your actual data to compare quality`,
+      `  4. If quality is similar, pick the cheaper/faster model`,
+      `  5. Use ${pc.cyan('--save')} to track results over time as your data evolves`,
+    ].join('\n'),
+    links: ['https://www.mongodb.com/docs/voyageai/models/text-embeddings/'],
+    tryIt: [
+      'vai benchmark embed --rounds 3',
+      'vai benchmark cost',
+      'vai benchmark similarity --query "your search query" --file your-docs.txt',
+    ],
+  },
 };
 
 /**
@@ -446,6 +488,11 @@ const aliases = {
   batch: 'batch-processing',
   'batch-processing': 'batch-processing',
   batching: 'batch-processing',
+  benchmark: 'benchmarking',
+  benchmarking: 'benchmarking',
+  'model-selection': 'benchmarking',
+  choosing: 'benchmarking',
+  compare: 'benchmarking',
 };
 
 /**

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;