voyageai-cli 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,8 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 ## [Unreleased]
 
 ### Added
+- `vai ingest` — Bulk import from JSONL/JSON/CSV/text with batching, progress bar, and dry-run
+- `vai similarity` — Compute cosine similarity between texts without MongoDB
 - `vai demo` — Interactive guided walkthrough of all features
 - ASCII banner when running `vai` with no arguments
 - CONTRIBUTING.md for open-source contributors

package/NOTICE

@@ -0,0 +1,23 @@
+voyageai-cli — Community CLI for Voyage AI and MongoDB Atlas Vector Search
+
+Copyright (c) 2026 Michael Lynn
+
+DISCLAIMER:
+This software is an independent, community-built tool. It is NOT an official
+product of MongoDB, Inc. or Voyage AI (a MongoDB company). It is not supported,
+endorsed, or maintained by either organization.
+
+This tool interacts with:
+- The MongoDB Atlas Embedding and Reranking API (https://ai.mongodb.com/v1/)
+- MongoDB Atlas Vector Search (https://www.mongodb.com/docs/atlas/atlas-vector-search/)
+
+For official documentation, support, and products:
+- MongoDB: https://www.mongodb.com
+- Voyage AI: https://www.mongodb.com/docs/voyageai/
+- MongoDB Support: https://support.mongodb.com
+
+"MongoDB", "MongoDB Atlas", and "Voyage AI" are trademarks of MongoDB, Inc.
+All trademarks belong to their respective owners.
+
+This software is provided "as is" without warranty of any kind. See LICENSE
+for the full MIT License terms.

package/README.md

@@ -6,6 +6,12 @@ CLI for [Voyage AI](https://www.mongodb.com/docs/voyageai/) embeddings, rerankin
 
 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:
+> - **MongoDB:** [mongodb.com](https://www.mongodb.com) | [MongoDB Atlas](https://www.mongodb.com/atlas) | [Support](https://support.mongodb.com)
+> - **Voyage AI:** [MongoDB Voyage AI Docs](https://www.mongodb.com/docs/voyageai/)
+>
+> Use at your own risk. No warranty is provided. See [LICENSE](LICENSE) for details.
+
 ## Install
 
 ```bash
@@ -60,6 +66,19 @@ vai rerank --query "best database" --documents-file candidates.json --top-k 3
 vai rerank --query "query" --documents "doc1" "doc2" --model rerank-2.5-lite
 ```
 
+### `vai similarity` — Compare text similarity
+
+```bash
+# Compare two texts
+vai similarity "MongoDB is a document database" "MongoDB Atlas is a cloud database"
+
+# Compare one text against many
+vai similarity "database performance" --against "MongoDB is fast" "PostgreSQL is relational"
+
+# From files
+vai similarity --file1 doc1.txt --file2 doc2.txt
+```
+
 ### `vai store` — Embed and insert into MongoDB Atlas
 
 Requires `MONGODB_URI` environment variable.
@@ -79,6 +98,29 @@ vai store --db myapp --collection docs --field embedding \
   --file documents.jsonl
 ```
 
+### `vai ingest` — Bulk import with progress
+
+```bash
+# JSONL (one JSON object per line with a "text" field)
+vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding
+
+# JSON array
+vai ingest --file documents.json --db myapp --collection docs --field embedding
+
+# CSV (specify text column)
+vai ingest --file data.csv --db myapp --collection docs --field embedding --text-column content
+
+# Plain text (one document per line)
+vai ingest --file lines.txt --db myapp --collection docs --field embedding
+
+# Options
+vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding \
+  --model voyage-4 --batch-size 100 --input-type document
+
+# Preview without embedding
+vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding --dry-run
+```
+
 ### `vai search` — Vector similarity search
 
 Requires `MONGODB_URI` environment variable.
@@ -237,6 +279,10 @@ Free tier: 200M tokens for most models. All Voyage 4 series models share the sam
 - A [MongoDB Atlas](https://www.mongodb.com/atlas) account (free tier works)
 - A [Voyage AI model API key](https://www.mongodb.com/docs/voyageai/management/api-keys/) (created in Atlas)
 
+## 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. For official support, visit [mongodb.com](https://www.mongodb.com).
+
 ## License
 
 MIT

package/package.json

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

package/src/cli.js

@@ -4,6 +4,7 @@
 require('dotenv').config({ quiet: true });
 
 const { program } = require('commander');
+const pc = require('picocolors');
 const { registerEmbed } = require('./commands/embed');
 const { registerRerank } = require('./commands/rerank');
 const { registerStore } = require('./commands/store');
@@ -13,12 +14,17 @@ const { registerModels } = require('./commands/models');
 const { registerPing } = require('./commands/ping');
 const { registerConfig } = require('./commands/config');
 const { registerDemo } = require('./commands/demo');
-const { showBanner, showQuickStart } = require('./lib/banner');
+const { registerExplain } = require('./commands/explain');
+const { registerSimilarity } = require('./commands/similarity');
+const { registerIngest } = require('./commands/ingest');
+const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
+
+const version = getVersion();
 
 program
   .name('vai')
   .description('Voyage AI embeddings, reranking, and Atlas Vector Search CLI')
-  .version('1.1.0');
+  .version(`vai/${version} (community tool — not an official MongoDB or Voyage AI product)`, '-V, --version', 'output the version number');
 
 registerEmbed(program);
 registerRerank(program);
@@ -29,6 +35,15 @@ registerModels(program);
 registerPing(program);
 registerConfig(program);
 registerDemo(program);
+registerExplain(program);
+registerSimilarity(program);
+registerIngest(program);
+
+// Append disclaimer to all help output
+program.addHelpText('after', `
+${pc.dim('Community tool — not an official MongoDB or Voyage AI product.')}
+${pc.dim('Docs: https://www.mongodb.com/docs/voyageai/')}
+`);
 
 // If no args (just `vai`), show banner + quick start + help
 if (process.argv.length <= 2) {

package/src/commands/demo.js

@@ -130,6 +130,9 @@ function registerDemo(program) {
       console.log(pc.bold('  🧭 Voyage AI Interactive Demo'));
       console.log(pc.dim('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
       console.log('');
+      console.log(pc.dim('  Note: This is a community tool, not an official MongoDB or Voyage AI product.'));
+      console.log(pc.dim('  For official docs and support: https://www.mongodb.com/docs/voyageai/'));
+      console.log('');
       console.log('  This walkthrough demonstrates embeddings, semantic search, and reranking');
       console.log('  using Voyage AI models via MongoDB Atlas.');
       console.log('');

package/src/commands/explain.js

@@ -0,0 +1,170 @@
+'use strict';
+
+const pc = require('picocolors');
+const { resolveConcept, listConcepts, getConcept } = require('../lib/explanations');
+
+const DISCLAIMER = pc.dim('  This tool is not affiliated with MongoDB, Inc. or Voyage AI.');
+
+/**
+ * Show the list of available topics.
+ */
+function showTopicList() {
+  console.log('');
+  console.log(`  🧭 ${pc.bold('Voyage AI Concepts')}`);
+  console.log('');
+  console.log('  Available topics:');
+
+  const concepts = listConcepts();
+  const maxKeyLen = Math.max(...concepts.map(k => k.length));
+
+  for (const key of concepts) {
+    const concept = getConcept(key);
+    const padding = ' '.repeat(maxKeyLen - key.length + 4);
+    console.log(`    ${pc.cyan(key)}${padding}${pc.dim(concept.summary)}`);
+  }
+
+  console.log('');
+  console.log(`  Usage: ${pc.cyan('vai explain <topic>')}`);
+  console.log('');
+}
+
+/**
+ * Show a formatted explanation of a concept.
+ * @param {string} key - canonical concept key
+ */
+function showExplanation(key) {
+  const concept = getConcept(key);
+  if (!concept) return;
+
+  console.log('');
+  console.log(`  🧭 ${pc.bold(concept.title)}`);
+  console.log(`  ${pc.dim('━'.repeat(concept.title.length + 2))}`);
+  console.log('');
+
+  // Indent the content
+  const lines = concept.content.split('\n');
+  for (const line of lines) {
+    console.log(`  ${line}`);
+  }
+
+  console.log('');
+  console.log(`  ${pc.bold('Key points:')}`);
+
+  // Extract key points from content — use a curated approach
+  // Actually, the content itself is the explanation. Let's show tryIt and links.
+
+  if (concept.tryIt && concept.tryIt.length > 0) {
+    console.log('');
+    console.log(`  ${pc.bold('Try it:')}`);
+    for (const cmd of concept.tryIt) {
+      console.log(`    ${pc.dim('$')} ${pc.cyan(cmd)}`);
+    }
+  }
+
+  if (concept.links && concept.links.length > 0) {
+    console.log('');
+    console.log(`  ${pc.bold('Learn more:')}`);
+    for (const link of concept.links) {
+      console.log(`    ${link}`);
+    }
+  }
+
+  console.log('');
+  console.log(DISCLAIMER);
+  console.log('');
+}
+
+/**
+ * Show a JSON explanation of a concept.
+ * @param {string} key - canonical concept key
+ */
+function showJsonExplanation(key) {
+  const concept = getConcept(key);
+  if (!concept) return;
+
+  // Strip ANSI codes for JSON
+  const stripAnsi = (str) => str.replace(/\x1b\[[0-9;]*m/g, '');
+
+  const output = {
+    concept: key,
+    title: concept.title,
+    summary: concept.summary,
+    content: stripAnsi(concept.content),
+    links: concept.links,
+    tryIt: concept.tryIt,
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+/**
+ * Find close matches for an unknown concept.
+ * @param {string} input
+ * @returns {string[]} up to 3 suggestions
+ */
+function findSuggestions(input) {
+  const normalized = input.toLowerCase().trim();
+  const allKeys = listConcepts();
+
+  // Simple substring matching
+  const matches = allKeys.filter(k =>
+    k.includes(normalized) || normalized.includes(k)
+  );
+
+  if (matches.length > 0) return matches.slice(0, 3);
+
+  // Levenshtein-ish: just return first 3 concepts as fallback
+  return allKeys.slice(0, 3);
+}
+
+/**
+ * Register the explain command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerExplain(program) {
+  program
+    .command('explain [concept]')
+    .description('Learn about embeddings, reranking, vector search, and more')
+    .option('--json', 'Output in JSON format')
+    .action((concept, opts) => {
+      if (!concept) {
+        // Show topic list
+        if (opts.json) {
+          const topics = listConcepts().map(key => {
+            const c = getConcept(key);
+            return { key, title: c.title, summary: c.summary };
+          });
+          console.log(JSON.stringify({ topics }, null, 2));
+        } else {
+          showTopicList();
+        }
+        return;
+      }
+
+      const resolved = resolveConcept(concept);
+      if (!resolved) {
+        const suggestions = findSuggestions(concept);
+        console.error('');
+        console.error(`  ${pc.red('✗')} Unknown topic: ${pc.bold(concept)}`);
+        console.error('');
+        if (suggestions.length > 0) {
+          console.error('  Did you mean?');
+          for (const s of suggestions) {
+            console.error(`    ${pc.cyan('vai explain ' + s)}`);
+          }
+          console.error('');
+        }
+        console.error(`  Run ${pc.cyan('vai explain')} to see all available topics.`);
+        console.error('');
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        showJsonExplanation(resolved);
+      } else {
+        showExplanation(resolved);
+      }
+    });
+}
+
+module.exports = { registerExplain };