voyageai-cli 1.22.0 → 1.23.0

package/src/lib/preflight.js

@@ -0,0 +1,281 @@
+'use strict';
+
+/**
+ * Preflight checks for vai chat.
+ *
+ * Validates that the full RAG pipeline is ready before
+ * starting a chat session. Returns structured results
+ * usable by CLI, Playground, and Desktop.
+ */
+
+/**
+ * @typedef {Object} PreflightCheck
+ * @property {string}  id      - check identifier
+ * @property {string}  label   - human-readable label
+ * @property {boolean} ok      - passed?
+ * @property {string}  [detail] - success detail (e.g. "23,530 documents")
+ * @property {string}  [error]  - failure message
+ * @property {string[]} [fix]   - commands to fix the issue
+ */
+
+/**
+ * Run all preflight checks for chat.
+ *
+ * @param {object} params
+ * @param {string} params.db            - database name
+ * @param {string} params.collection    - collection name
+ * @param {string} params.field         - embedding field name (default: 'embedding')
+ * @param {object} params.llmConfig     - resolved LLM config ({ provider, model, ... })
+ * @param {string} [params.textField]   - document text field (default: 'text')
+ * @returns {Promise<{ checks: PreflightCheck[], ready: boolean }>}
+ */
+async function runPreflight({ db, collection, field = 'embedding', llmConfig, textField = 'text' }) {
+  const checks = [];
+
+  // 1. LLM Provider
+  checks.push({
+    id: 'llm',
+    label: 'LLM Provider',
+    ok: !!llmConfig?.provider,
+    detail: llmConfig?.provider
+      ? `${llmConfig.provider} (${llmConfig.model})`
+      : undefined,
+    error: !llmConfig?.provider ? 'No LLM provider configured' : undefined,
+    fix: !llmConfig?.provider ? [
+      'vai config set llm-provider anthropic',
+      'vai config set llm-api-key YOUR_KEY',
+    ] : undefined,
+  });
+
+  // 2–4: MongoDB checks (need connection)
+  let client;
+  try {
+    const { getMongoCollection } = require('./mongo');
+    const result = await getMongoCollection(db, collection);
+    client = result.client;
+    const coll = result.collection;
+
+    // 2. Collection + document count
+    const docCount = await coll.estimatedDocumentCount();
+    if (docCount === 0) {
+      checks.push({
+        id: 'collection',
+        label: 'Collection',
+        ok: false,
+        error: `${db}.${collection} is empty (0 documents)`,
+        fix: [
+          `vai pipeline ./your-docs --db ${db} --collection ${collection}`,
+        ],
+      });
+    } else {
+      checks.push({
+        id: 'collection',
+        label: 'Collection',
+        ok: true,
+        detail: `${db}.${collection} (${docCount.toLocaleString()} documents)`,
+      });
+    }
+
+    // 3. Embeddings — check if documents have the embedding field
+    if (docCount > 0) {
+      const withEmbedding = await coll.countDocuments(
+        { [field]: { $exists: true } },
+        { limit: 1 }
+      );
+      if (withEmbedding === 0) {
+        checks.push({
+          id: 'embeddings',
+          label: 'Embeddings',
+          ok: false,
+          error: `No '${field}' field found in documents`,
+          fix: [
+            `vai pipeline ./your-docs --db ${db} --collection ${collection}`,
+            '',
+            'Or step by step:',
+            `  vai chunk ./docs                                    # Split into chunks`,
+            `  vai store --db ${db} --collection ${collection}     # Embed and store`,
+          ],
+        });
+      } else {
+        // Check what fraction have embeddings
+        const embeddedCount = await coll.countDocuments({ [field]: { $exists: true } });
+        const pct = Math.round((embeddedCount / docCount) * 100);
+        checks.push({
+          id: 'embeddings',
+          label: 'Embeddings',
+          ok: true,
+          detail: pct === 100
+            ? `All documents have '${field}' field`
+            : `${embeddedCount.toLocaleString()}/${docCount.toLocaleString()} documents embedded (${pct}%)`,
+        });
+      }
+    } else {
+      checks.push({
+        id: 'embeddings',
+        label: 'Embeddings',
+        ok: false,
+        error: 'No documents to check',
+      });
+    }
+
+    // 4. Vector search index
+    try {
+      const indexes = await coll.listSearchIndexes().toArray();
+      const vectorIndex = indexes.find(idx => {
+        // Check if any index has a vector field mapping
+        if (idx.latestDefinition?.fields) {
+          return idx.latestDefinition.fields.some(
+            f => f.type === 'vector' || f.type === 'knnVector'
+          );
+        }
+        // Atlas Search index with vectorSearch type
+        if (idx.type === 'vectorSearch') return true;
+        return false;
+      });
+
+      if (vectorIndex) {
+        const status = vectorIndex.status || 'READY';
+        const building = status !== 'READY' && status !== 'FAILED';
+        checks.push({
+          id: 'vectorIndex',
+          label: 'Vector Search Index',
+          ok: status === 'READY',
+          building,
+          indexName: vectorIndex.name,
+          status,
+          detail: status === 'READY'
+            ? `'${vectorIndex.name}' (${status})`
+            : undefined,
+          error: status !== 'READY'
+            ? `Index '${vectorIndex.name}' status: ${status}`
+            : undefined,
+        });
+      } else {
+        checks.push({
+          id: 'vectorIndex',
+          label: 'Vector Search Index',
+          ok: false,
+          error: `No vector search index found on ${db}.${collection}`,
+          fix: [
+            `vai index create --db ${db} --collection ${collection} --field ${field} --dimensions 1024`,
+          ],
+        });
+      }
+    } catch (err) {
+      // listSearchIndexes may not be available on non-Atlas deployments
+      checks.push({
+        id: 'vectorIndex',
+        label: 'Vector Search Index',
+        ok: false,
+        error: `Could not check indexes: ${err.message}`,
+        fix: [
+          `vai index create --db ${db} --collection ${collection} --field ${field} --dimensions 1024`,
+        ],
+      });
+    }
+
+  } catch (err) {
+    // MongoDB connection failed entirely
+    checks.push({
+      id: 'collection',
+      label: 'MongoDB Connection',
+      ok: false,
+      error: err.message,
+      fix: [
+        'vai config set mongodb-uri "mongodb+srv://user:pass@cluster.mongodb.net/"',
+      ],
+    });
+  } finally {
+    if (client) {
+      try { await client.close(); } catch { /* ignore */ }
+    }
+  }
+
+  const ready = checks.every(c => c.ok);
+  return { checks, ready };
+}
+
+/**
+ * Format preflight results for terminal display.
+ * @param {PreflightCheck[]} checks
+ * @returns {string}
+ */
+function formatPreflight(checks) {
+  const pc = require('picocolors');
+  const lines = [];
+
+  for (const check of checks) {
+    const icon = check.ok ? pc.green('✓') : pc.red('✗');
+    const detail = check.ok ? pc.dim(check.detail || '') : pc.red(check.error || 'failed');
+    lines.push(`  ${icon} ${pc.bold(padRight(check.label, 22))} ${detail}`);
+  }
+
+  // Collect all fix commands from failed checks
+  const failedChecks = checks.filter(c => !c.ok && c.fix);
+  if (failedChecks.length > 0) {
+    lines.push('');
+    lines.push(pc.bold('  To fix:'));
+    for (const check of failedChecks) {
+      for (const cmd of check.fix) {
+        if (cmd === '') {
+          lines.push('');
+        } else if (cmd.startsWith('  ') || cmd.startsWith('Or ')) {
+          lines.push(`  ${pc.dim(cmd)}`);
+        } else {
+          lines.push(`    ${pc.cyan(cmd)}`);
+        }
+      }
+    }
+    lines.push('');
+    lines.push(`  ${pc.dim('Learn more: vai explain chat')}`);
+  }
+
+  return lines.join('\n');
+}
+
+function padRight(str, len) {
+  return str + ' '.repeat(Math.max(0, len - str.length));
+}
+
+/**
+ * Poll a vector search index until it's READY or timeout.
+ *
+ * @param {object} params
+ * @param {string} params.db
+ * @param {string} params.collection
+ * @param {string} params.indexName
+ * @param {number} [params.timeoutMs] - max wait time (default 5 min)
+ * @param {number} [params.pollMs] - poll interval (default 5s)
+ * @returns {Promise<{ ready: boolean, status: string, elapsed: number }>}
+ */
+async function waitForIndex({ db, collection, indexName, timeoutMs = 300000, pollMs = 5000 }) {
+  const { getMongoCollection } = require('./mongo');
+  let client;
+  try {
+    const result = await getMongoCollection(db, collection);
+    client = result.client;
+    const coll = result.collection;
+
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      const indexes = await coll.listSearchIndexes().toArray();
+      const idx = indexes.find(i => i.name === indexName);
+      if (!idx) return { ready: false, status: 'NOT_FOUND', elapsed: Date.now() - start };
+      if (idx.status === 'READY') return { ready: true, status: 'READY', elapsed: Date.now() - start };
+      if (idx.status === 'FAILED') return { ready: false, status: 'FAILED', elapsed: Date.now() - start };
+
+      await new Promise(r => setTimeout(r, pollMs));
+    }
+    return { ready: false, status: 'TIMEOUT', elapsed: Date.now() - start };
+  } finally {
+    if (client) {
+      try { await client.close(); } catch { /* ignore */ }
+    }
+  }
+}
+
+module.exports = {
+  runPreflight,
+  formatPreflight,
+  waitForIndex,
+};

package/src/lib/prompt.js

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * Prompt Builder
+ *
+ * Constructs the message array sent to the LLM from
+ * retrieved documents, conversation history, and user query.
+ */
+
+const DEFAULT_SYSTEM_PROMPT = `You are an assistant powered by a retrieval-augmented generation (RAG) pipeline built with Voyage AI embeddings and MongoDB Atlas Vector Search. Your answers are grounded in documents retrieved from the user's knowledge base.
+
+## How to use the retrieved context
+
+- Each context document includes a source label and a relevance score (0 to 1). Higher scores indicate stronger semantic matches to the user's query.
+- Treat documents with scores below 0.3 as weak matches. If only weak matches were retrieved, say so rather than forcing an answer from them.
+- When documents conflict, surface the discrepancy and let the user decide which to trust.
+
+## Answering rules
+
+1. Ground every claim in the provided context. Do not supplement with outside knowledge unless you explicitly flag it as such (e.g. "Outside the retrieved documents, ...").
+2. Cite sources inline using the format [Source: <label>]. Use the source labels from the context block.
+3. If the context is insufficient, say so directly. Suggest how the user might refine their query or expand their knowledge base.
+4. Be concise. Prefer short, direct answers. Use lists or structure when it aids clarity.
+5. For follow-up questions, rely on the newly retrieved context for that turn. Prior context may be stale.`;
+
+/**
+ * Format retrieved documents into a context block.
+ * @param {Array<{source: string, text: string, score: number}>} docs
+ * @returns {string}
+ */
+function formatContextBlock(docs) {
+  if (!docs || docs.length === 0) return '';
+
+  const lines = ['--- Context Documents ---', ''];
+
+  for (const doc of docs) {
+    const source = doc.source || doc.metadata?.source || 'unknown';
+    const score = doc.score != null ? doc.score.toFixed(2) : 'N/A';
+    lines.push(`[Source: ${source} | Relevance: ${score}]`);
+    lines.push(doc.text || doc.chunk || '');
+    lines.push('');
+  }
+
+  lines.push('--- End Context ---');
+  return lines.join('\n');
+}
+
+/**
+ * Build the full system prompt.
+ *
+ * The base prompt (grounding rules, citation format, safety guardrails)
+ * is always included. Users can append custom instructions via
+ * `systemPrompt` — these are added after the base, not replacing it.
+ *
+ * @param {string} [customPrompt] - User's custom instructions (appended, not replacing)
+ * @returns {string}
+ */
+function buildSystemPrompt(customPrompt) {
+  if (!customPrompt) return DEFAULT_SYSTEM_PROMPT;
+
+  return `${DEFAULT_SYSTEM_PROMPT}
+
+## Additional Instructions
+
+${customPrompt}`;
+}
+
+/**
+ * Build the message array for the LLM.
+ *
+ * @param {object} params
+ * @param {string} params.query - Current user question
+ * @param {Array} params.contextDocs - Retrieved + reranked documents
+ * @param {Array} [params.history] - Previous conversation turns [{role, content}]
+ * @param {string} [params.systemPrompt] - Custom instructions (appended to base prompt)
+ * @returns {Array<{role: string, content: string}>}
+ */
+function buildMessages({ query, contextDocs = [], history = [], systemPrompt }) {
+  const messages = [];
+
+  // 1. System prompt (base + custom instructions)
+  messages.push({
+    role: 'system',
+    content: buildSystemPrompt(systemPrompt),
+  });
+
+  // 2. Conversation history (previous turns)
+  for (const turn of history) {
+    messages.push({ role: turn.role, content: turn.content });
+  }
+
+  // 3. Current user message with injected context
+  const contextBlock = formatContextBlock(contextDocs);
+  let userContent = '';
+  if (contextBlock) {
+    userContent = `${contextBlock}\n\nUser question: ${query}`;
+  } else {
+    userContent = query;
+  }
+
+  messages.push({ role: 'user', content: userContent });
+
+  return messages;
+}
+
+module.exports = {
+  DEFAULT_SYSTEM_PROMPT,
+  buildSystemPrompt,
+  formatContextBlock,
+  buildMessages,
+};

package/src/lib/wizard-cli.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * CLI renderer for the wizard engine.
+ *
+ * Uses @clack/prompts for beautiful terminal UI with
+ * back-navigation support (type "back" or "<" at any prompt).
+ */
+
+// Lazy-loaded — @clack/prompts is ESM-only in some versions,
+// and eager require crashes on Node <22. Only loaded when actually used.
+let p;
+let pc;
+function ensureDeps() {
+  if (!p) p = require('@clack/prompts');
+  if (!pc) pc = require('picocolors');
+}
+
+const BACK = Symbol.for('back');
+const CANCEL = Symbol.for('cancel');
+
+/**
+ * Create a CLI renderer for runWizard().
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.title]       - intro title
+ * @param {string} [opts.doneMessage] - outro message
+ * @param {boolean} [opts.showBackHint] - show "type < to go back" hint (default true)
+ * @returns {object} renderer compatible with runWizard
+ */
+function createCLIRenderer(opts = {}) {
+  ensureDeps();
+  const showBackHint = opts.showBackHint !== false;
+
+  return {
+    async intro(steps, config) {
+      if (opts.title) {
+        p.intro(pc.bold(opts.title));
+      }
+    },
+
+    async prompt(step, ctx) {
+      const { options, defaultValue, stepNumber, totalSteps, isFirst } = ctx;
+      const backHint = (!isFirst && showBackHint)
+        ? pc.dim('  (< to go back)')
+        : '';
+      const stepLabel = pc.dim(`[${stepNumber}/${totalSteps}]`);
+      const label = `${stepLabel} ${step.label}${backHint}`;
+
+      let result;
+
+      switch (step.type) {
+        case 'select': {
+          // Map options to clack format
+          const clackOptions = options.map(o => ({
+            value: o.value,
+            label: o.label,
+            hint: o.hint || undefined,
+          }));
+
+          // Add "Go back" option if not first step
+          if (!isFirst) {
+            clackOptions.push({
+              value: '__back__',
+              label: pc.dim('← Go back'),
+            });
+          }
+
+          result = await p.select({
+            message: label,
+            options: clackOptions,
+            initialValue: defaultValue || undefined,
+          });
+
+          if (p.isCancel(result)) return CANCEL;
+          if (result === '__back__') return BACK;
+          return result;
+        }
+
+        case 'text':
+        case 'password': {
+          result = await p.text({
+            message: label,
+            placeholder: step.placeholder || '',
+            defaultValue: defaultValue != null ? String(defaultValue) : undefined,
+            validate: (val) => {
+              if (val == null) return undefined;
+              // Handle back navigation
+              if (val === '<' || (typeof val === 'string' && val.toLowerCase() === 'back')) return undefined;
+              if (step.required && !val) return `${step.label} is required`;
+              if (step.validate) {
+                const v = step.validate(val, ctx.answers);
+                if (v !== true) return v;
+              }
+              return undefined;
+            },
+          });
+
+          if (p.isCancel(result)) return CANCEL;
+          if (result === '<' || (typeof result === 'string' && result.toLowerCase() === 'back')) return BACK;
+          return result;
+        }
+
+        case 'confirm': {
+          result = await p.confirm({
+            message: label,
+            initialValue: defaultValue != null ? defaultValue : true,
+          });
+
+          if (p.isCancel(result)) return CANCEL;
+          return result;
+        }
+
+        default:
+          throw new Error(`Unknown step type: ${step.type}`);
+      }
+    },
+
+    async error(message) {
+      p.log.error(message);
+    },
+
+    async cancel() {
+      p.cancel('Setup cancelled.');
+    },
+
+    async outro(answers) {
+      if (opts.doneMessage) {
+        p.outro(opts.doneMessage);
+      }
+    },
+  };
+}
+
+module.exports = { createCLIRenderer };

package/src/lib/wizard-steps-chat.js

@@ -0,0 +1,171 @@
+'use strict';
+
+/**
+ * Chat setup wizard step definitions.
+ *
+ * Surface-agnostic — consumed by CLI (@clack/prompts),
+ * Playground (React), and Desktop (Electron/LeafyGreen).
+ *
+ * Each step is a plain declarative object. Dynamic values
+ * (options, defaults, skip predicates) are functions of
+ * (answers, config) so renderers can evaluate them.
+ */
+
+const { PROVIDER_DEFAULTS, PROVIDER_MODELS, listOllamaModels } = require('./llm');
+
+// Cache Ollama detection across steps
+let _ollamaModels = null;
+let _ollamaChecked = false;
+
+async function detectOllama() {
+  if (_ollamaChecked) return _ollamaModels;
+  _ollamaChecked = true;
+  try {
+    _ollamaModels = await listOllamaModels({ timeoutMs: 2000 });
+  } catch {
+    _ollamaModels = [];
+  }
+  return _ollamaModels;
+}
+
+/**
+ * Reset Ollama cache (for testing).
+ */
+function resetOllamaCache() {
+  _ollamaModels = null;
+  _ollamaChecked = false;
+}
+
+/**
+ * Build provider options dynamically — detects Ollama availability.
+ * @returns {Promise<Array<{value: string, label: string, hint: string}>>}
+ */
+async function getProviderOptions() {
+  const ollamaModels = await detectOllama();
+  const ollamaAvailable = ollamaModels && ollamaModels.length > 0;
+
+  const options = [
+    {
+      value: 'anthropic',
+      label: 'Anthropic (Claude)',
+      hint: 'Best instruction following',
+    },
+    {
+      value: 'openai',
+      label: 'OpenAI (GPT-4o)',
+      hint: 'Broad model selection',
+    },
+    {
+      value: 'ollama',
+      label: ollamaAvailable
+        ? `Ollama (${ollamaModels.length} model${ollamaModels.length === 1 ? '' : 's'} installed)`
+        : 'Ollama (local — not detected)',
+      hint: ollamaAvailable ? 'Free, fully private' : 'Requires ollama running locally',
+    },
+  ];
+
+  return options;
+}
+
+/**
+ * Build model options for the selected provider.
+ */
+async function getModelOptions(answers) {
+  const provider = answers.provider;
+  if (!provider) return [];
+
+  if (provider === 'ollama') {
+    const models = await detectOllama();
+    if (models.length === 0) {
+      return [{ value: 'llama3.1', label: 'llama3.1', hint: 'default (pull with: ollama pull llama3.1)' }];
+    }
+    return models.map(m => ({
+      value: m.id,
+      label: m.name,
+      hint: [m.parameterSize, m.size].filter(Boolean).join(' — ') || undefined,
+    }));
+  }
+
+  const cloudModels = PROVIDER_MODELS[provider] || [];
+  return cloudModels.map(m => ({
+    value: m.id,
+    label: m.name,
+    hint: m.context ? `context: ${m.context}` : undefined,
+  }));
+}
+
+/**
+ * The chat setup wizard steps.
+ *
+ * These are consumed by:
+ *   - CLI:        wizard-cli.js (via runWizard)
+ *   - Playground: Settings panel in Chat tab
+ *   - Desktop:    Chat settings in Electron app
+ */
+const chatSetupSteps = [
+  {
+    id: 'provider',
+    label: 'LLM Provider',
+    type: 'select',
+    options: () => getProviderOptions(),
+    required: true,
+    skip: (_answers, config) => !!config.llmProvider,
+    group: 'LLM Configuration',
+  },
+
+  {
+    id: 'apiKey',
+    label: 'API Key',
+    type: 'password',
+    required: true,
+    placeholder: 'sk-...',
+    skip: (answers, config) => {
+      // Skip for Ollama (no key needed)
+      const provider = answers.provider || config.llmProvider;
+      if (provider === 'ollama') return true;
+      // Skip if already configured
+      if (config.llmApiKey) return true;
+      return false;
+    },
+    validate: (value) => {
+      if (!value || value.length < 8) return 'API key looks too short';
+      return true;
+    },
+    group: 'LLM Configuration',
+  },
+
+  {
+    id: 'model',
+    label: 'Model',
+    type: 'select',
+    options: (answers) => getModelOptions(answers),
+    getDefault: (answers, config) => {
+      const provider = answers.provider || config.llmProvider;
+      return config.llmModel || PROVIDER_DEFAULTS[provider] || null;
+    },
+    required: false, // uses provider default if skipped
+    group: 'LLM Configuration',
+  },
+
+  {
+    id: 'ollamaBaseUrl',
+    label: 'Ollama URL',
+    type: 'text',
+    defaultValue: 'http://localhost:11434',
+    placeholder: 'http://localhost:11434',
+    required: false,
+    skip: (answers, config) => {
+      const provider = answers.provider || config.llmProvider;
+      return provider !== 'ollama';
+    },
+    group: 'LLM Configuration',
+  },
+];
+
+module.exports = {
+  chatSetupSteps,
+  getProviderOptions,
+  getModelOptions,
+  detectOllama,
+  resetOllamaCache,
+};