voyageai-cli 1.1.0 → 1.2.0

package/src/commands/demo.js

@@ -0,0 +1,353 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const readline = require('readline');
+const pc = require('picocolors');
+
+const CLI_PATH = path.join(__dirname, '..', 'cli.js');
+
+/**
+ * Wait for the user to press Enter.
+ * Resolves immediately if noPause is true.
+ * @param {boolean} noPause
+ * @returns {Promise<void>}
+ */
+function waitForEnter(noPause) {
+  if (noPause) return Promise.resolve();
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(pc.dim('  Press Enter to continue...'), () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+/**
+ * Print a command that's about to be run.
+ * @param {string} cmd
+ */
+function showCommand(cmd) {
+  console.log(`\n  ${pc.bold(pc.cyan('$ ' + cmd))}\n`);
+}
+
+/**
+ * Run a vai sub-command as a child process with inherited stdio.
+ * @param {string[]} args
+ * @returns {{ status: number }}
+ */
+function runVai(args) {
+  return spawnSync(process.execPath, [CLI_PATH, ...args], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+}
+
+/**
+ * Print a step header.
+ * @param {number} num
+ * @param {string} title
+ */
+function stepHeader(num, title) {
+  const label = `── Step ${num}: ${title} `;
+  const pad = Math.max(0, 60 - label.length);
+  console.log(`\n${pc.bold(label)}${'─'.repeat(pad)}`);
+}
+
+/**
+ * Run a vai command, show it, and return whether it succeeded.
+ * @param {string} display  - the display string (e.g. 'vai embed "hello"')
+ * @param {string[]} args   - args to pass to vai
+ * @returns {boolean} success
+ */
+function runStep(display, args) {
+  showCommand(display);
+  const result = runVai(args);
+  return result.status === 0;
+}
+
+/**
+ * Ask user whether to continue after a failure.
+ * @param {boolean} noPause
+ * @returns {Promise<boolean>} true = continue, false = abort
+ */
+function askContinue(noPause) {
+  if (noPause) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(pc.yellow('  Step failed. Continue anyway? (Y/n) '), (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      resolve(a === '' || a === 'y' || a === 'yes');
+    });
+  });
+}
+
+/**
+ * Sleep for ms milliseconds.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Register the demo command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerDemo(program) {
+  program
+    .command('demo')
+    .description('Interactive guided walkthrough of Voyage AI features')
+    .option('--no-pause', 'Skip Enter prompts (for CI/recording)')
+    .option('--skip-pipeline', 'Skip the full pipeline step (Step 5)')
+    .option('--keep', 'Keep the demo collection after pipeline step')
+    .action(async (opts) => {
+      const noPause = !opts.pause;
+
+      // ── Preflight: check API key ──
+      const apiKey = process.env.VOYAGE_API_KEY;
+      if (!apiKey) {
+        const { getConfigValue } = require('../lib/config');
+        const configKey = getConfigValue('apiKey');
+        if (!configKey) {
+          console.error('');
+          console.error(pc.red('  ✗ VOYAGE_API_KEY is not set.'));
+          console.error('');
+          console.error('  Set it with:');
+          console.error(`    ${pc.cyan('export VOYAGE_API_KEY="your-key"')}`);
+          console.error('  Or:');
+          console.error(`    ${pc.cyan('vai config set api-key "your-key"')}`);
+          console.error('');
+          process.exit(1);
+        }
+      }
+
+      // ── Banner ──
+      console.log('');
+      console.log(pc.bold('  🧭 Voyage AI Interactive Demo'));
+      console.log(pc.dim('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+      console.log('');
+      console.log('  This walkthrough demonstrates embeddings, semantic search, and reranking');
+      console.log('  using Voyage AI models via MongoDB Atlas.');
+      console.log('');
+
+      await waitForEnter(noPause);
+
+      // ── Step 1: Ping ──
+      stepHeader(1, 'Check Connection');
+      console.log('  First, let\'s verify your API key works.');
+
+      let ok = runStep('vai ping', ['ping']);
+      if (!ok) {
+        const cont = await askContinue(noPause);
+        if (!cont) process.exit(1);
+      }
+
+      await waitForEnter(noPause);
+
+      // ── Step 2: Embeddings ──
+      stepHeader(2, 'Generate Embeddings');
+      console.log('  Embeddings convert text into numerical vectors that capture meaning.');
+      console.log('  Let\'s embed a sentence:');
+
+      ok = runStep('vai embed "MongoDB is the most popular document database"',
+        ['embed', 'MongoDB is the most popular document database']);
+      if (!ok) {
+        const cont = await askContinue(noPause);
+        if (!cont) process.exit(1);
+      }
+
+      console.log('\n  Let\'s try another:');
+
+      ok = runStep('vai embed "I love using NoSQL databases for modern applications"',
+        ['embed', 'I love using NoSQL databases for modern applications']);
+      if (!ok) {
+        const cont = await askContinue(noPause);
+        if (!cont) process.exit(1);
+      }
+
+      console.log('');
+      console.log('  These two sentences are about related topics — their vectors will be');
+      console.log('  close together in embedding space, even though they share few words.');
+
+      await waitForEnter(noPause);
+
+      // ── Step 3: Compare Similarity ──
+      stepHeader(3, 'Compare Similarity');
+      console.log('  Let\'s embed a set of diverse documents and see how the model');
+      console.log('  distinguishes meaning:');
+
+      runStep('vai embed "MongoDB Atlas is a cloud database" --quiet',
+        ['embed', 'MongoDB Atlas is a cloud database', '--quiet']);
+      runStep('vai embed "The weather in Paris is lovely" --quiet',
+        ['embed', 'The weather in Paris is lovely', '--quiet']);
+      runStep('vai embed "Vector search enables AI applications" --quiet',
+        ['embed', 'Vector search enables AI applications', '--quiet']);
+
+      console.log('');
+      console.log('  Notice how the model captures semantic relationships — database topics');
+      console.log('  cluster together, while unrelated topics are far apart.');
+
+      await waitForEnter(noPause);
+
+      // ── Step 4: Reranking ──
+      stepHeader(4, 'Reranking');
+      console.log('  Reranking scores how relevant each document is to a specific query.');
+      console.log('  This is the "precision" stage of two-stage retrieval.');
+
+      ok = runStep(
+        'vai rerank --query "How do I build AI search?" --documents ...',
+        [
+          'rerank',
+          '--query', 'How do I build AI search?',
+          '--documents',
+          'MongoDB Atlas provides vector search capabilities',
+          'The recipe calls for two cups of flour',
+          'Voyage AI embeddings power semantic retrieval',
+          'Python is a popular programming language',
+          'Atlas Search combines full-text and vector search',
+        ]
+      );
+      if (!ok) {
+        const cont = await askContinue(noPause);
+        if (!cont) process.exit(1);
+      }
+
+      console.log('');
+      console.log('  Notice how the reranker assigns HIGH scores to relevant documents');
+      console.log('  and LOW scores to irrelevant ones — much more decisive than');
+      console.log('  embedding similarity alone.');
+
+      await waitForEnter(noPause);
+
+      // ── Step 5: Full Pipeline (optional) ──
+      const { getConfigValue } = require('../lib/config');
+      const mongoUri = process.env.MONGODB_URI || getConfigValue('mongodbUri');
+      const skipPipeline = opts.skipPipeline || !mongoUri;
+
+      if (skipPipeline && !opts.skipPipeline) {
+        stepHeader(5, 'Full Pipeline (skipped)');
+        console.log(pc.dim('  Skipping pipeline demo — set MONGODB_URI to try the full flow.'));
+        console.log(pc.dim('  See: vai config set mongodb-uri "mongodb+srv://..."'));
+        console.log('');
+      } else if (!skipPipeline) {
+        stepHeader(5, 'Full Pipeline');
+        console.log('  Now let\'s put it all together: embed → store → index → search → rerank.');
+        console.log('');
+
+        const db = 'test';
+        const collection = 'demo_voyage_test';
+        const field = 'embedding';
+
+        const documents = [
+          'MongoDB Atlas is a fully managed cloud database',
+          'Voyage AI provides state of the art embedding models',
+          'Vector search enables semantic retrieval for AI applications',
+          'Atlas Search combines full-text and vector search capabilities',
+          'The recipe calls for two cups of flour and three eggs',
+        ];
+
+        console.log(pc.dim(`  Creating test collection: ${collection}...`));
+        console.log('');
+
+        let pipelineOk = true;
+        for (const text of documents) {
+          const short = text.length > 50 ? text.slice(0, 47) + '...' : text;
+          ok = runStep(
+            `vai store --db ${db} --collection ${collection} --field ${field} --text "${short}"`,
+            ['store', '--db', db, '--collection', collection, '--field', field, '--text', text]
+          );
+          if (!ok) {
+            pipelineOk = false;
+            const cont = await askContinue(noPause);
+            if (!cont) break;
+          }
+        }
+
+        if (pipelineOk) {
+          // Create index
+          ok = runStep(
+            `vai index create --db ${db} --collection ${collection} --field ${field} --dimensions 1024`,
+            ['index', 'create', '--db', db, '--collection', collection, '--field', field, '--dimensions', '1024']
+          );
+
+          if (ok) {
+            // Wait for index to be ready
+            console.log('');
+            console.log(pc.dim('  Waiting for index to build...'));
+
+            const { getConnection } = require('../lib/mongo');
+            let indexReady = false;
+            const deadline = Date.now() + 120000;
+
+            try {
+              const client = await getConnection();
+              const coll = client.db(db).collection(collection);
+
+              while (Date.now() < deadline) {
+                const indexes = await coll.listSearchIndexes().toArray();
+                const idx = indexes.find(i => i.name && i.status);
+                if (idx && idx.status === 'READY') {
+                  indexReady = true;
+                  console.log(pc.green('  ✓ Index is READY'));
+                  break;
+                }
+                const statusStr = idx ? idx.status : 'PENDING';
+                process.stdout.write(pc.dim(`\r  Index status: ${statusStr}...`));
+                await sleep(5000);
+              }
+
+              if (!indexReady) {
+                console.log(pc.yellow('\n  ⚠ Index build timed out (120s). Trying search anyway...'));
+              }
+            } catch (err) {
+              console.log(pc.yellow(`\n  ⚠ Could not check index status: ${err.message}`));
+            }
+
+            console.log('');
+
+            // Search
+            ok = runStep(
+              `vai search --query "cloud database for AI apps" --db ${db} --collection ${collection} --field ${field}`,
+              ['search', '--query', 'cloud database for AI apps', '--db', db, '--collection', collection, '--field', field]
+            );
+          }
+        }
+
+        // Cleanup
+        if (!opts.keep) {
+          console.log('');
+          console.log(pc.dim(`  Cleaning up: dropping ${collection}...`));
+          try {
+            const { getConnection } = require('../lib/mongo');
+            const client = await getConnection();
+            await client.db(db).collection(collection).drop();
+            console.log(pc.dim('  ✓ Collection dropped.'));
+          } catch (err) {
+            console.log(pc.dim(`  ⚠ Cleanup note: ${err.message}`));
+          }
+        } else {
+          console.log(pc.dim(`  Collection ${collection} kept (--keep flag).`));
+        }
+      }
+
+      // ── Done ──
+      console.log('');
+      console.log('─'.repeat(60));
+      console.log(pc.bold('  🧭 That\'s Voyage AI in action!'));
+      console.log('');
+      console.log('  Next steps:');
+      console.log(`    • Read the docs: ${pc.cyan('https://www.mongodb.com/docs/voyageai/')}`);
+      console.log(`    • Explore models: ${pc.cyan('vai models')}`);
+      console.log(`    • Configure: ${pc.cyan('vai config set api-key <your-key>')}`);
+      console.log(`    • Full pipeline: ${pc.cyan('vai store → vai index create → vai search')}`);
+      console.log('');
+      console.log('  Happy searching! 🚀');
+      console.log('');
+    });
+}
+
+module.exports = { registerDemo };

package/src/commands/embed.js

@@ -1,8 +1,9 @@
 'use strict';
 
-const { DEFAULT_EMBED_MODEL } = require('../lib/catalog');
+const { getDefaultModel } = require('../lib/catalog');
 const { generateEmbeddings } = require('../lib/api');
 const { resolveTextInput } = require('../lib/input');
+const ui = require('../lib/ui');
 
 /**
  * Register the embed command on a Commander program.
@@ -12,7 +13,7 @@ function registerEmbed(program) {
   program
     .command('embed [text]')
     .description('Generate embeddings for text')
-    .option('-m, --model <model>', 'Embedding model', DEFAULT_EMBED_MODEL)
+    .option('-m, --model <model>', 'Embedding model', getDefaultModel())
     .option('-t, --input-type <type>', 'Input type: query or document')
     .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
     .option('-f, --file <path>', 'Read text from file')
@@ -23,12 +24,22 @@ function registerEmbed(program) {
       try {
         const texts = await resolveTextInput(text, opts.file);
 
+        const useColor = !opts.json;
+        const useSpinner = useColor && !opts.quiet;
+        let spin;
+        if (useSpinner) {
+          spin = ui.spinner('Generating embeddings...');
+          spin.start();
+        }
+
         const result = await generateEmbeddings(texts, {
           model: opts.model,
           inputType: opts.inputType,
           dimensions: opts.dimensions,
         });
 
+        if (spin) spin.stop();
+
         if (opts.outputFormat === 'array') {
           if (result.data.length === 1) {
             console.log(JSON.stringify(result.data[0].embedding));
@@ -45,21 +56,24 @@ function registerEmbed(program) {
 
         // Friendly output
         if (!opts.quiet) {
-          console.log(`Model: ${result.model}`);
-          console.log(`Texts: ${result.data.length}`);
+          console.log(ui.label('Model', ui.cyan(result.model)));
+          console.log(ui.label('Texts', String(result.data.length)));
           if (result.usage) {
-            console.log(`Tokens: ${result.usage.total_tokens}`);
+            console.log(ui.label('Tokens', ui.dim(String(result.usage.total_tokens))));
           }
-          console.log(`Dimensions: ${result.data[0]?.embedding?.length || 'N/A'}`);
+          console.log(ui.label('Dimensions', ui.bold(String(result.data[0]?.embedding?.length || 'N/A'))));
           console.log('');
         }
 
         for (const item of result.data) {
           const preview = item.embedding.slice(0, 5).map(v => v.toFixed(6)).join(', ');
-          console.log(`[${item.index}] [${preview}, ...] (${item.embedding.length} dims)`);
+          console.log(`${ui.dim('[' + item.index + ']')} [${preview}, ...] (${item.embedding.length} dims)`);
         }
+
+        console.log('');
+        console.log(ui.success('Embeddings generated'));
       } catch (err) {
-        console.error(`Error: ${err.message}`);
+        console.error(ui.error(err.message));
         process.exit(1);
       }
     });

package/src/commands/index.js

@@ -1,7 +1,8 @@
 'use strict';
 
-const { DEFAULT_DIMENSIONS } = require('../lib/catalog');
+const { getDefaultDimensions } = require('../lib/catalog');
 const { getMongoCollection } = require('../lib/mongo');
+const ui = require('../lib/ui');
 
 /**
  * Register the index command (with create, list, delete subcommands) on a Commander program.
@@ -19,7 +20,7 @@ function registerIndex(program) {
     .requiredOption('--db <database>', 'Database name')
     .requiredOption('--collection <name>', 'Collection name')
     .requiredOption('--field <name>', 'Embedding field name')
-    .option('-d, --dimensions <n>', 'Vector dimensions', (v) => parseInt(v, 10), DEFAULT_DIMENSIONS)
+    .option('-d, --dimensions <n>', 'Vector dimensions', (v) => parseInt(v, 10), getDefaultDimensions())
     .option('-s, --similarity <type>', 'Similarity function: cosine, dotProduct, euclidean', 'cosine')
     .option('-n, --index-name <name>', 'Index name', 'default')
     .option('--json', 'Machine-readable JSON output')
@@ -27,6 +28,14 @@ function registerIndex(program) {
     .action(async (opts) => {
       let client;
       try {
+        const useColor = !opts.json;
+        const useSpinner = useColor && !opts.quiet;
+        let spin;
+        if (useSpinner) {
+          spin = ui.spinner('Creating vector search index...');
+          spin.start();
+        }
+
         const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
         client = c;
 
@@ -38,7 +47,7 @@ function registerIndex(program) {
               {
                 type: 'vector',
                 path: opts.field,
-                numDimensions: parseInt(opts.dimensions, 10) || DEFAULT_DIMENSIONS,
+                numDimensions: parseInt(opts.dimensions, 10) || getDefaultDimensions(),
                 similarity: opts.similarity,
               },
             ],
@@ -47,24 +56,26 @@ function registerIndex(program) {
 
         const result = await collection.createSearchIndex(indexDef);
 
+        if (spin) spin.stop();
+
         if (opts.json) {
           console.log(JSON.stringify({ indexName: result, definition: indexDef }, null, 2));
         } else if (!opts.quiet) {
-          console.log(`✓ Vector search index created: "${result}"`);
-          console.log(`  Database:   ${opts.db}`);
-          console.log(`  Collection: ${opts.collection}`);
-          console.log(`  Field:      ${opts.field}`);
-          console.log(`  Dimensions: ${opts.dimensions}`);
-          console.log(`  Similarity: ${opts.similarity}`);
+          console.log(ui.success(`Vector search index created: "${result}"`));
+          console.log(ui.label('Database', opts.db));
+          console.log(ui.label('Collection', opts.collection));
+          console.log(ui.label('Field', opts.field));
+          console.log(ui.label('Dimensions', String(opts.dimensions)));
+          console.log(ui.label('Similarity', opts.similarity));
           console.log('');
-          console.log('Note: Index may take a few minutes to become ready.');
+          console.log(ui.dim('Note: Index may take a few minutes to become ready.'));
         }
       } catch (err) {
         if (err.message && err.message.includes('already exists')) {
-          console.error(`Error: Index "${opts.indexName}" already exists on ${opts.db}.${opts.collection}`);
-          console.error('Use a different --index-name or delete the existing index first.');
+          console.error(ui.error(`Index "${opts.indexName}" already exists on ${opts.db}.${opts.collection}`));
+          console.error(ui.dim('Use a different --index-name or delete the existing index first.'));
         } else {
-          console.error(`Error: ${err.message}`);
+          console.error(ui.error(err.message));
         }
         process.exit(1);
       } finally {
@@ -83,11 +94,21 @@ function registerIndex(program) {
     .action(async (opts) => {
       let client;
       try {
+        const useColor = !opts.json;
+        const useSpinner = useColor && !opts.quiet;
+        let spin;
+        if (useSpinner) {
+          spin = ui.spinner('Listing indexes...');
+          spin.start();
+        }
+
         const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
         client = c;
 
         const indexes = await collection.listSearchIndexes().toArray();
 
+        if (spin) spin.stop();
+
         if (opts.json) {
           console.log(JSON.stringify(indexes, null, 2));
           return;
@@ -99,21 +120,21 @@ function registerIndex(program) {
         }
 
         if (!opts.quiet) {
-          console.log(`Search indexes on ${opts.db}.${opts.collection}:`);
+          console.log(`Search indexes on ${ui.cyan(opts.db + '.' + opts.collection)}:`);
           console.log('');
         }
 
         for (const idx of indexes) {
-          console.log(`  Name:   ${idx.name}`);
-          console.log(`  Type:   ${idx.type || 'N/A'}`);
-          console.log(`  Status: ${idx.status || 'N/A'}`);
+          console.log(ui.label('Name', ui.bold(idx.name)));
+          console.log(ui.label('Type', idx.type || 'N/A'));
+          console.log(ui.label('Status', ui.status(idx.status || 'N/A')));
           if (idx.latestDefinition) {
-            console.log(`  Fields: ${JSON.stringify(idx.latestDefinition.fields || [])}`);
+            console.log(ui.label('Fields', JSON.stringify(idx.latestDefinition.fields || [])));
           }
           console.log('');
         }
       } catch (err) {
-        console.error(`Error: ${err.message}`);
+        console.error(ui.error(err.message));
         process.exit(1);
       } finally {
         if (client) await client.close();
@@ -132,20 +153,30 @@ function registerIndex(program) {
     .action(async (opts) => {
       let client;
       try {
+        const useColor = !opts.json;
+        const useSpinner = useColor && !opts.quiet;
+        let spin;
+        if (useSpinner) {
+          spin = ui.spinner('Deleting index...');
+          spin.start();
+        }
+
         const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
         client = c;
 
         await collection.dropSearchIndex(opts.indexName);
 
+        if (spin) spin.stop();
+
         if (opts.json) {
           console.log(JSON.stringify({ dropped: opts.indexName }, null, 2));
         } else if (!opts.quiet) {
-          console.log(`✓ Dropped search index: "${opts.indexName}"`);
-          console.log(`  Database:   ${opts.db}`);
-          console.log(`  Collection: ${opts.collection}`);
+          console.log(ui.success(`Dropped search index: "${opts.indexName}"`));
+          console.log(ui.label('Database', opts.db));
+          console.log(ui.label('Collection', opts.collection));
         }
       } catch (err) {
-        console.error(`Error: ${err.message}`);
+        console.error(ui.error(err.message));
         process.exit(1);
       } finally {
         if (client) await client.close();

package/src/commands/models.js

@@ -3,6 +3,7 @@
 const { MODEL_CATALOG } = require('../lib/catalog');
 const { API_BASE } = require('../lib/api');
 const { formatTable } = require('../lib/format');
+const ui = require('../lib/ui');
 
 /**
  * Register the models command on a Commander program.
@@ -28,25 +29,32 @@ function registerModels(program) {
       }
 
       if (models.length === 0) {
-        console.log(`No models found for type: ${opts.type}`);
+        console.log(ui.yellow(`No models found for type: ${opts.type}`));
         return;
       }
 
       if (!opts.quiet) {
-        console.log('Voyage AI Models');
-        console.log(`(via MongoDB AI API — ${API_BASE})`);
+        console.log(ui.bold('Voyage AI Models'));
+        console.log(ui.dim(`(via MongoDB AI API — ${API_BASE})`));
         console.log('');
       }
 
       const headers = ['Model', 'Type', 'Context', 'Dimensions', 'Price', 'Best For'];
-      const rows = models.map(m => [m.name, m.type, m.context, m.dimensions, m.price, m.bestFor]);
+      const rows = models.map(m => {
+        const name = ui.cyan(m.name);
+        const type = m.type === 'embedding' ? ui.green(m.type) : ui.yellow(m.type);
+        const price = ui.dim(m.price);
+        return [name, type, m.context, m.dimensions, price, m.bestFor];
+      });
 
-      console.log(formatTable(headers, rows));
+      // Use bold headers
+      const boldHeaders = headers.map(h => ui.bold(h));
+      console.log(formatTable(boldHeaders, rows));
 
       if (!opts.quiet) {
         console.log('');
-        console.log('Free tier: 200M tokens (most models), 50M (domain-specific)');
-        console.log('All 4-series models share the same embedding space.');
+        console.log(ui.dim('Free tier: 200M tokens (most models), 50M (domain-specific)'));
+        console.log(ui.dim('All 4-series models share the same embedding space.'));
       }
     });
 }