voyageai-cli 1.20.6 → 1.22.0

package/src/lib/explanations.js

@@ -1065,6 +1065,140 @@ const concepts = {
       'vai eval --mode rerank --test-set test.jsonl --json',
     ],
   },
+
+  'code-generation': {
+    title: 'Code Generation — vai generate',
+    summary: 'Generate production code from your vai configuration',
+    content: [
+      `${pc.bold('What is vai generate?')}`,
+      `The ${pc.cyan('vai generate')} command outputs production-ready code snippets that you can`,
+      `pipe directly into your project files. It reads your ${pc.cyan('.vai.json')} configuration`,
+      `and generates code pre-configured with your model, database, and collection settings.`,
+      ``,
+      `${pc.bold('Available components:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('client')} — Voyage AI API client (embed, rerank functions)`,
+      `  ${pc.dim('•')} ${pc.cyan('connection')} — MongoDB connection helper with vector search`,
+      `  ${pc.dim('•')} ${pc.cyan('retrieval')} — Full RAG retrieval: embed → search → rerank`,
+      `  ${pc.dim('•')} ${pc.cyan('ingest')} — Document ingestion: chunk → embed → store`,
+      `  ${pc.dim('•')} ${pc.cyan('search-api')} — HTTP endpoints for search and ingest`,
+      ``,
+      `${pc.bold('Supported targets:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('vanilla')} — Node.js + Express (default)`,
+      `  ${pc.dim('•')} ${pc.cyan('nextjs')} — Next.js 14 + App Router + Material UI`,
+      `  ${pc.dim('•')} ${pc.cyan('python')} — Python + Flask`,
+      ``,
+      `${pc.bold('Auto-detection:')}`,
+      `vai automatically detects your project type from:`,
+      `  ${pc.dim('•')} ${pc.cyan('next.config.js')} → nextjs`,
+      `  ${pc.dim('•')} ${pc.cyan('requirements.txt')} → python`,
+      `  ${pc.dim('•')} ${pc.cyan('package.json')} → vanilla`,
+      ``,
+      `${pc.bold('Pipe-friendly:')}`,
+      `Output goes to stdout, so you can pipe directly to files:`,
+      `  ${pc.cyan('vai generate retrieval > lib/retrieval.js')}`,
+    ].join('\n'),
+    links: ['https://github.com/mrlynn/voyageai-cli#code-generation--scaffolding'],
+    tryIt: [
+      'vai generate --list',
+      'vai generate client --target python',
+      'vai generate retrieval > lib/retrieval.js',
+      'vai generate search-api --json',
+    ],
+  },
+
+  scaffolding: {
+    title: 'Project Scaffolding — vai scaffold',
+    summary: 'Create complete starter projects with one command',
+    content: [
+      `${pc.bold('What is vai scaffold?')}`,
+      `The ${pc.cyan('vai scaffold')} command creates a complete, ready-to-run project directory`,
+      `with all the files you need for a Voyage AI RAG application. It reads your`,
+      `${pc.cyan('.vai.json')} and generates everything pre-configured.`,
+      ``,
+      `${pc.bold('What you get:')}`,
+      `  ${pc.dim('•')} Server entry point (Express, Next.js, or Flask)`,
+      `  ${pc.dim('•')} Voyage AI client library`,
+      `  ${pc.dim('•')} MongoDB connection helper with vector search`,
+      `  ${pc.dim('•')} RAG retrieval module with optional reranking`,
+      `  ${pc.dim('•')} Document ingestion pipeline`,
+      `  ${pc.dim('•')} API routes for search and ingest`,
+      `  ${pc.dim('•')} ${pc.cyan('.env.example')} with required variables`,
+      `  ${pc.dim('•')} ${pc.cyan('README.md')} with setup instructions`,
+      `  ${pc.dim('•')} ${pc.cyan('package.json')} or ${pc.cyan('requirements.txt')}`,
+      ``,
+      `${pc.bold('Available targets:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('vanilla')} — Node.js + Express (9 files)`,
+      `  ${pc.dim('•')} ${pc.cyan('nextjs')} — Next.js + MUI search UI (13 files)`,
+      `  ${pc.dim('•')} ${pc.cyan('python')} — Flask API server (8 files)`,
+      ``,
+      `${pc.bold('Configuration:')}`,
+      `All generated files use your ${pc.cyan('.vai.json')} settings:`,
+      `  ${pc.dim('•')} Embedding model and dimensions`,
+      `  ${pc.dim('•')} Database and collection names`,
+      `  ${pc.dim('•')} Vector index name and field`,
+      `  ${pc.dim('•')} Chunking strategy, size, and overlap`,
+      `  ${pc.dim('•')} Reranking (enabled/disabled, model)`,
+      ``,
+      `${pc.bold('Preview mode:')}`,
+      `Use ${pc.cyan('--dry-run')} to see what would be created without writing files.`,
+    ].join('\n'),
+    links: ['https://github.com/mrlynn/voyageai-cli#code-generation--scaffolding'],
+    tryIt: [
+      'vai scaffold my-rag-api',
+      'vai scaffold my-app --target nextjs',
+      'vai scaffold flask-api --target python',
+      'vai scaffold test-project --dry-run',
+    ],
+  },
+
+  'eval-comparison': {
+    title: 'Evaluation Comparison — vai eval compare',
+    summary: 'Compare configurations and track quality over time',
+    content: [
+      `${pc.bold('Comparing configurations')}`,
+      `The ${pc.cyan('vai eval compare')} subcommand runs the same test set against multiple`,
+      `configurations and shows a side-by-side comparison of metrics.`,
+      ``,
+      `${pc.bold('Config file format (JSON):')}`,
+      `  ${pc.dim('{')}`,
+      `    ${pc.dim('"name": "Large + Rerank",')}`,
+      `    ${pc.dim('"model": "voyage-4-large",')}`,
+      `    ${pc.dim('"rerank": true,')}`,
+      `    ${pc.dim('"rerankModel": "rerank-2.5",')}`,
+      `    ${pc.dim('"dimensions": 1024')}`,
+      `  ${pc.dim('}')}`,
+      ``,
+      `${pc.bold('Comparison output:')}`,
+      `Shows a table with best values highlighted in green:`,
+      `  ${pc.dim('Config               MRR      NDCG@5    R@5')}`,
+      `  ${pc.dim('baseline            0.69      0.78    0.82')}`,
+      `  ${pc.green('experiment          0.75      0.81    0.84')}  ← best`,
+      ``,
+      `${pc.bold('Saving results:')}`,
+      `Use ${pc.cyan('--save <path>')} to persist results for later comparison:`,
+      `  ${pc.cyan('vai eval --test-set test.jsonl --save baseline.json')}`,
+      ``,
+      `${pc.bold('Baseline comparison:')}`,
+      `Use ${pc.cyan('--baseline <path>')} to compare against a previous run:`,
+      `  ${pc.cyan('vai eval --test-set test.jsonl --baseline baseline.json')}`,
+      ``,
+      `Shows deltas with color-coded improvement/regression:`,
+      `  ${pc.dim('MRR        0.7523 vs 0.6891')}  ${pc.green('+0.0632 (+9.2%)')}`,
+      `  ${pc.dim('NDCG@5     0.8102 vs 0.7845')}  ${pc.green('+0.0257 (+3.3%)')}`,
+      ``,
+      `${pc.bold('Use cases:')}`,
+      `  ${pc.dim('•')} A/B test embedding models (voyage-4-large vs voyage-4-lite)`,
+      `  ${pc.dim('•')} Compare rerank on/off`,
+      `  ${pc.dim('•')} Track quality after chunking changes`,
+      `  ${pc.dim('•')} CI/CD regression testing`,
+    ].join('\n'),
+    links: ['https://github.com/mrlynn/voyageai-cli#evaluation'],
+    tryIt: [
+      'vai eval --test-set test.jsonl --save baseline.json',
+      'vai eval --test-set test.jsonl --baseline baseline.json',
+      'vai eval compare --test-set test.jsonl --configs baseline.json,experiment.json',
+    ],
+  },
 };
 
 /**
@@ -1165,6 +1299,27 @@ const aliases = {
   recall: 'rerank-eval',
   mrr: 'rerank-eval',
   'eval-rerank': 'rerank-eval',
+  // Code generation aliases
+  generate: 'code-generation',
+  'code-generation': 'code-generation',
+  codegen: 'code-generation',
+  'vai-generate': 'code-generation',
+  templates: 'code-generation',
+  // Scaffolding aliases
+  scaffold: 'scaffolding',
+  scaffolding: 'scaffolding',
+  'vai-scaffold': 'scaffolding',
+  'project-scaffold': 'scaffolding',
+  'starter-project': 'scaffolding',
+  boilerplate: 'scaffolding',
+  // Eval comparison aliases
+  'eval-comparison': 'eval-comparison',
+  'eval-compare': 'eval-comparison',
+  compare: 'eval-comparison',
+  baseline: 'eval-comparison',
+  'save-results': 'eval-comparison',
+  'a-b-test': 'eval-comparison',
+  regression: 'eval-comparison',
   // Provider comparison aliases
   'provider-comparison': 'provider-comparison',
   providers: 'provider-comparison',

package/src/lib/scaffold-structure.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * Project structure definitions for each target.
+ * Maps template names to output paths within the project.
+ * 
+ * Separated from scaffold.js to avoid @clack/prompts dependency
+ * when loaded from Electron.
+ */
+const PROJECT_STRUCTURE = {
+  vanilla: {
+    files: [
+      { template: 'package.json', output: 'package.json' },
+      { template: 'env.example', output: '.env.example' },
+      { template: 'README.md', output: 'README.md' },
+      { template: 'server.js', output: 'server.js' },
+      { template: 'client.js', output: 'lib/client.js' },
+      { template: 'connection.js', output: 'lib/connection.js' },
+      { template: 'retrieval.js', output: 'lib/retrieval.js' },
+      { template: 'ingest.js', output: 'lib/ingest.js' },
+      { template: 'search-api.js', output: 'lib/search-api.js' },
+    ],
+    description: 'Node.js + Express API server',
+    postInstall: 'npm install',
+    startCommand: 'npm start',
+  },
+  
+  nextjs: {
+    files: [
+      { template: 'package.json', output: 'package.json' },
+      { template: 'env.example', output: '.env.example' },
+      { template: 'README.md', output: 'README.md' },
+      { template: 'layout.jsx', output: 'app/layout.jsx' },
+      { template: 'page-search.jsx', output: 'app/search/page.jsx' },
+      { template: 'route-search.js', output: 'app/api/search/route.js' },
+      { template: 'route-ingest.js', output: 'app/api/ingest/route.js' },
+      { template: 'lib-voyage.js', output: 'lib/voyage.js' },
+      { template: 'lib-mongo.js', output: 'lib/mongodb.js' },
+      { template: 'theme.js', output: 'lib/theme.js' },
+    ],
+    extraFiles: [
+      {
+        output: 'app/page.jsx',
+        content: `'use client';
+import { redirect } from 'next/navigation';
+export default function Home() {
+  redirect('/search');
+}
+`,
+      },
+      {
+        output: 'next.config.js',
+        content: `/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    serverComponentsExternalPackages: ['mongodb'],
+  },
+};
+module.exports = nextConfig;
+`,
+      },
+      {
+        output: '.gitignore',
+        content: `node_modules/
+.next/
+.env
+.env.local
+`,
+      },
+      {
+        output: 'jsconfig.json',
+        content: `{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  }
+}
+`,
+      },
+    ],
+    description: 'Next.js + Material UI application',
+    postInstall: 'npm install',
+    startCommand: 'npm run dev',
+  },
+  
+  python: {
+    files: [
+      { template: 'requirements.txt', output: 'requirements.txt' },
+      { template: 'env.example', output: '.env.example' },
+      { template: 'README.md', output: 'README.md' },
+      { template: 'app.py', output: 'app.py' },
+      { template: 'voyage_client.py', output: 'voyage_client.py' },
+      { template: 'mongo_client.py', output: 'mongo_client.py' },
+      { template: 'chunker.py', output: 'chunker.py' },
+    ],
+    extraFiles: [
+      {
+        output: '.gitignore',
+        content: `venv/
+__pycache__/
+*.pyc
+.env
+`,
+      },
+    ],
+    description: 'Python + Flask API server',
+    postInstall: 'pip install -r requirements.txt',
+    startCommand: 'python app.py',
+  },
+};
+
+module.exports = { PROJECT_STRUCTURE };

package/src/lib/templates/nextjs/README.md.tpl

@@ -0,0 +1,106 @@
+# {{projectName}}
+
+A semantic search application powered by Voyage AI embeddings, MongoDB Atlas Vector Search, and Next.js with Material UI.
+
+## Configuration
+
+| Setting | Value |
+|---------|-------|
+| Embedding Model | `{{model}}` |
+| Dimensions | {{dimensions}} |
+| Database | `{{db}}` |
+| Collection | `{{collection}}` |
+| Vector Index | `{{index}}` |
+{{#if rerank}}
+| Rerank Model | `{{rerankModel}}` |
+{{/if}}
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+npm install
+```
+
+### 2. Configure environment
+
+Copy `.env.example` to `.env.local` and fill in your credentials:
+
+```bash
+cp .env.example .env.local
+```
+
+Required variables:
+- `VOYAGE_API_KEY` - Your Voyage AI API key from [dash.voyageai.com](https://dash.voyageai.com)
+- `MONGODB_URI` - Your MongoDB Atlas connection string
+
+### 3. Create vector index
+
+In MongoDB Atlas, create a vector search index on your collection:
+
+```json
+{
+  "fields": [
+    {
+      "type": "vector",
+      "path": "{{field}}",
+      "numDimensions": {{dimensions}},
+      "similarity": "cosine"
+    }
+  ]
+}
+```
+
+Name the index `{{index}}`.
+
+### 4. Start the development server
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see the search interface.
+
+## Project Structure
+
+```
+{{projectName}}/
+├── app/
+│   ├── layout.jsx          # Root layout with MUI theme
+│   ├── page.jsx            # Home page
+│   ├── search/
+│   │   └── page.jsx        # Search page (MUI)
+│   └── api/
+│       ├── search/route.js # Search endpoint
+│       └── ingest/route.js # Ingest endpoint
+├── lib/
+│   ├── voyage.js           # Voyage AI client
+│   ├── mongodb.js          # MongoDB connection
+│   └── theme.js            # MUI theme
+├── .env.example
+├── package.json
+└── README.md
+```
+
+## API Endpoints
+
+### POST /api/search
+
+```bash
+curl -X POST http://localhost:3000/api/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "How does vector search work?", "limit": 5}'
+```
+
+### POST /api/ingest
+
+```bash
+curl -X POST http://localhost:3000/api/ingest \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Your document content...", "metadata": {"source": "api"}}'
+```
+
+---
+
+Generated by [vai](https://github.com/mrlynn/voyageai-cli) v{{vaiVersion}}

package/src/lib/templates/nextjs/env.example.tpl

@@ -0,0 +1,8 @@
+# Voyage AI API
+VOYAGE_API_KEY=your_voyage_api_key_here
+
+# MongoDB Atlas
+MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/{{db}}?retryWrites=true&w=majority
+
+# Optional: Override defaults
+# VOYAGE_API_URL=https://api.voyageai.com/v1

package/src/lib/templates/nextjs/layout.jsx.tpl

@@ -0,0 +1,29 @@
+/**
+ * Root Layout with MUI Theme
+ * Generated by vai v{{vaiVersion}} on {{generatedAt}}
+ */
+
+import { AppRouterCacheProvider } from '@mui/material-nextjs/v14-appRouter';
+import { ThemeProvider } from '@mui/material/styles';
+import CssBaseline from '@mui/material/CssBaseline';
+import { theme } from '@/lib/theme';
+
+export const metadata = {
+  title: '{{projectName}}',
+  description: 'Semantic search powered by Voyage AI',
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <AppRouterCacheProvider>
+          <ThemeProvider theme={theme}>
+            <CssBaseline />
+            {children}
+          </ThemeProvider>
+        </AppRouterCacheProvider>
+      </body>
+    </html>
+  );
+}

package/src/lib/templates/nextjs/lib-mongo.js.tpl

@@ -0,0 +1,111 @@
+/**
+ * MongoDB Connection Helper (Next.js)
+ * Generated by vai v{{vaiVersion}} on {{generatedAt}}
+ * 
+ * Uses connection caching for serverless environments.
+ */
+
+import { MongoClient } from 'mongodb';
+
+const MONGODB_URI = process.env.MONGODB_URI;
+
+if (!MONGODB_URI) {
+  throw new Error('MONGODB_URI environment variable is required');
+}
+
+// Cache the client promise for connection reuse in serverless
+let cached = global.mongo;
+
+if (!cached) {
+  cached = global.mongo = { conn: null, promise: null };
+}
+
+/**
+ * Get a cached MongoDB client connection.
+ * Reuses existing connection in serverless environment.
+ */
+export async function getMongoClient() {
+  if (cached.conn) {
+    return cached.conn;
+  }
+
+  if (!cached.promise) {
+    cached.promise = MongoClient.connect(MONGODB_URI);
+  }
+
+  cached.conn = await cached.promise;
+  return cached.conn;
+}
+
+/**
+ * Get the database instance.
+ */
+export async function getDb() {
+  const client = await getMongoClient();
+  return client.db('{{db}}');
+}
+
+/**
+ * Get the documents collection.
+ */
+export async function getCollection() {
+  const db = await getDb();
+  return db.collection('{{collection}}');
+}
+
+/**
+ * Perform a vector search.
+ */
+export async function vectorSearch(embedding, options = {}) {
+  const collection = await getCollection();
+  const limit = options.limit || 10;
+  const numCandidates = options.numCandidates || limit * 10;
+
+  const pipeline = [
+    {
+      $vectorSearch: {
+        index: '{{index}}',
+        path: '{{field}}',
+        queryVector: embedding,
+        numCandidates,
+        limit,
+      },
+    },
+    {
+      $project: {
+        _id: 1,
+        text: 1,
+        metadata: 1,
+        score: { $meta: 'vectorSearchScore' },
+      },
+    },
+  ];
+
+  if (options.filter) {
+    pipeline[0].$vectorSearch.filter = options.filter;
+  }
+
+  const results = await collection.aggregate(pipeline).toArray();
+  return results.map(doc => ({
+    document: doc,
+    score: doc.score,
+  }));
+}
+
+/**
+ * Insert documents with embeddings.
+ */
+export async function insertDocuments(docs) {
+  const collection = await getCollection();
+  
+  const documents = docs.map(doc => ({
+    text: doc.text,
+    {{field}}: doc.embedding,
+    metadata: doc.metadata || {},
+    _embeddedAt: new Date(),
+    _model: '{{model}}',
+  }));
+
+  const result = await collection.insertMany(documents);
+  return { insertedCount: result.insertedCount };
+}

package/src/lib/templates/nextjs/lib-voyage.js.tpl

@@ -0,0 +1,103 @@
+/**
+ * Voyage AI API Client (Next.js)
+ * Generated by vai v{{vaiVersion}} on {{generatedAt}}
+ * 
+ * Model: {{model}}
+ * Dimensions: {{dimensions}}
+ */
+
+const VOYAGE_API_URL = process.env.VOYAGE_API_URL || 'https://api.voyageai.com/v1';
+const VOYAGE_API_KEY = process.env.VOYAGE_API_KEY;
+
+/**
+ * Generate embeddings for text(s) using Voyage AI.
+ */
+export async function embed(input, options = {}) {
+  if (!VOYAGE_API_KEY) {
+    throw new Error('VOYAGE_API_KEY environment variable is required');
+  }
+
+  const texts = Array.isArray(input) ? input : [input];
+  
+  const response = await fetch(`${VOYAGE_API_URL}/embeddings`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${VOYAGE_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: options.model || '{{model}}',
+      input: texts,
+      input_type: options.inputType || '{{inputType}}',
+      output_dimension: options.outputDimension || {{dimensions}},
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Voyage AI API error: ${response.status} ${error}`);
+  }
+
+  const data = await response.json();
+  return {
+    embeddings: data.data.map(d => d.embedding),
+    usage: data.usage,
+  };
+}
+
+/**
+ * Embed a single query.
+ */
+export async function embedQuery(query, options = {}) {
+  const result = await embed(query, { ...options, inputType: 'query' });
+  return result.embeddings[0];
+}
+
+/**
+ * Embed multiple documents.
+ */
+export async function embedDocuments(documents, options = {}) {
+  const result = await embed(documents, { ...options, inputType: 'document' });
+  return result.embeddings;
+}
+
+{{#if rerank}}
+/**
+ * Rerank documents by relevance to a query.
+ */
+export async function rerank(query, documents, options = {}) {
+  if (!VOYAGE_API_KEY) {
+    throw new Error('VOYAGE_API_KEY environment variable is required');
+  }
+
+  const response = await fetch(`${VOYAGE_API_URL}/rerank`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${VOYAGE_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: options.model || '{{rerankModel}}',
+      query,
+      documents,
+      top_k: options.topK,
+      return_documents: true,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Voyage AI rerank error: ${response.status} ${error}`);
+  }
+
+  const data = await response.json();
+  return {
+    results: data.data.map(d => ({
+      index: d.index,
+      relevanceScore: d.relevance_score,
+      document: d.document,
+    })),
+    usage: data.usage,
+  };
+}
+{{/if}}

package/src/lib/templates/nextjs/package.json.tpl

@@ -0,0 +1,33 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@emotion/cache": "^11.11.0",
+    "@emotion/react": "^11.11.3",
+    "@emotion/styled": "^11.11.0",
+    "@mui/icons-material": "^5.15.0",
+    "@mui/material": "^5.15.0",
+    "@mui/material-nextjs": "^5.15.0",
+    "mongodb": "^6.3.0",
+    "next": "^14.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.56.0",
+    "eslint-config-next": "^14.1.0"
+  },
+  "generated": {
+    "by": "vai",
+    "version": "{{vaiVersion}}",
+    "model": "{{model}}",
+    "at": "{{generatedAt}}"
+  }
+}