voyageai-cli 1.13.0 → 1.16.0

package/src/lib/chunker.js

@@ -0,0 +1,341 @@
+'use strict';
+
+/**
+ * Available chunking strategies.
+ */
+const STRATEGIES = ['fixed', 'sentence', 'paragraph', 'recursive', 'markdown'];
+
+/**
+ * Default chunk options.
+ */
+const DEFAULTS = {
+  size: 512,
+  overlap: 50,
+  minSize: 20,
+};
+
+// ── Sentence splitting ──
+
+/**
+ * Split text into sentences. Handles common abbreviations and edge cases.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function splitSentences(text) {
+  // Split on sentence-ending punctuation followed by whitespace or EOL.
+  // Negative lookbehind for common abbreviations (Mr., Dr., etc.)
+  const parts = text.split(/(?<=[.!?])\s+(?=[A-Z\u00C0-\u024F"])/);
+  return parts.map(s => s.trim()).filter(s => s.length > 0);
+}
+
+// ── Strategy implementations ──
+
+/**
+ * Fixed-size chunking with character count and overlap.
+ * @param {string} text
+ * @param {object} opts
+ * @param {number} opts.size - Target chunk size in characters
+ * @param {number} opts.overlap - Overlap between chunks in characters
+ * @returns {string[]}
+ */
+function chunkFixed(text, opts) {
+  const { size, overlap } = opts;
+  const chunks = [];
+  let start = 0;
+
+  while (start < text.length) {
+    const end = start + size;
+    chunks.push(text.slice(start, end).trim());
+    start = end - overlap;
+    if (start >= text.length) break;
+    // Prevent infinite loop with tiny overlap
+    if (end >= text.length) break;
+  }
+
+  return chunks.filter(c => c.length >= (opts.minSize || DEFAULTS.minSize));
+}
+
+/**
+ * Sentence-boundary chunking. Groups sentences until size limit.
+ * @param {string} text
+ * @param {object} opts
+ * @returns {string[]}
+ */
+function chunkSentence(text, opts) {
+  const { size, overlap } = opts;
+  const sentences = splitSentences(text);
+  return groupUnits(sentences, size, overlap, opts.minSize || DEFAULTS.minSize);
+}
+
+/**
+ * Paragraph chunking. Splits on double newlines, groups if needed.
+ * @param {string} text
+ * @param {object} opts
+ * @returns {string[]}
+ */
+function chunkParagraph(text, opts) {
+  const { size, overlap } = opts;
+  const paragraphs = text.split(/\n\s*\n/).map(p => p.trim()).filter(p => p.length > 0);
+  return groupUnits(paragraphs, size, overlap, opts.minSize || DEFAULTS.minSize);
+}
+
+/**
+ * Recursive chunking. Tries largest delimiters first, falls back to smaller.
+ * This is the most commonly used strategy for RAG pipelines.
+ * @param {string} text
+ * @param {object} opts
+ * @returns {string[]}
+ */
+function chunkRecursive(text, opts) {
+  const { size, minSize } = opts;
+  const separators = ['\n\n', '\n', '. ', '! ', '? ', '; ', ', ', ' '];
+
+  return recursiveSplit(text, separators, size, minSize || DEFAULTS.minSize);
+}
+
+/**
+ * Internal recursive split implementation.
+ * @param {string} text
+ * @param {string[]} separators
+ * @param {number} maxSize
+ * @param {number} minSize
+ * @returns {string[]}
+ */
+function recursiveSplit(text, separators, maxSize, minSize) {
+  if (text.length <= maxSize) {
+    return text.trim().length >= minSize ? [text.trim()] : [];
+  }
+
+  // Find the first separator that exists in the text
+  let sep = null;
+  for (const s of separators) {
+    if (text.includes(s)) {
+      sep = s;
+      break;
+    }
+  }
+
+  // If no separator found, hard-split by characters
+  if (sep === null) {
+    const chunks = [];
+    for (let i = 0; i < text.length; i += maxSize) {
+      const chunk = text.slice(i, i + maxSize).trim();
+      if (chunk.length >= minSize) chunks.push(chunk);
+    }
+    return chunks;
+  }
+
+  // Split on this separator and greedily merge pieces under maxSize
+  const parts = text.split(sep);
+  const chunks = [];
+  let current = '';
+
+  for (const part of parts) {
+    const candidate = current ? current + sep + part : part;
+
+    if (candidate.length <= maxSize) {
+      current = candidate;
+    } else {
+      // Flush current chunk
+      if (current.trim().length >= minSize) {
+        chunks.push(current.trim());
+      }
+      // If this single part exceeds maxSize, recurse with next separator level
+      if (part.length > maxSize) {
+        const remainingSeps = separators.slice(separators.indexOf(sep) + 1);
+        chunks.push(...recursiveSplit(part, remainingSeps, maxSize, minSize));
+        current = '';
+      } else {
+        current = part;
+      }
+    }
+  }
+
+  // Flush remainder
+  if (current.trim().length >= minSize) {
+    chunks.push(current.trim());
+  }
+
+  return chunks;
+}
+
+/**
+ * Markdown-aware chunking. Splits on headings, preserves structure.
+ * Each heading starts a new chunk; content under it is grouped.
+ * @param {string} text
+ * @param {object} opts
+ * @returns {string[]}
+ */
+function chunkMarkdown(text, opts) {
+  const { size, minSize } = opts;
+
+  // Split on markdown headings (# through ######)
+  const headingPattern = /^(#{1,6}\s.+)$/gm;
+  const sections = [];
+  let lastIndex = 0;
+  let match;
+
+  while ((match = headingPattern.exec(text)) !== null) {
+    // Content before this heading
+    if (match.index > lastIndex) {
+      const content = text.slice(lastIndex, match.index).trim();
+      if (content) {
+        if (sections.length > 0) {
+          // Append to previous section
+          sections[sections.length - 1].content += '\n\n' + content;
+        } else {
+          sections.push({ heading: '', content });
+        }
+      }
+    }
+    sections.push({ heading: match[1], content: '' });
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Remaining content after last heading
+  if (lastIndex < text.length) {
+    const content = text.slice(lastIndex).trim();
+    if (content) {
+      if (sections.length > 0) {
+        sections[sections.length - 1].content += '\n\n' + content;
+      } else {
+        sections.push({ heading: '', content });
+      }
+    }
+  }
+
+  // Build chunks from sections, splitting large sections recursively
+  const chunks = [];
+  for (const section of sections) {
+    const full = section.heading
+      ? section.heading + '\n\n' + section.content.trim()
+      : section.content.trim();
+
+    if (!full || full.length < (minSize || DEFAULTS.minSize)) continue;
+
+    if (full.length <= size) {
+      chunks.push(full);
+    } else {
+      // Section too large — recursively split the content, prepend heading to first chunk
+      const subChunks = chunkRecursive(section.content.trim(), opts);
+      for (let i = 0; i < subChunks.length; i++) {
+        if (i === 0 && section.heading) {
+          chunks.push(section.heading + '\n\n' + subChunks[i]);
+        } else {
+          chunks.push(subChunks[i]);
+        }
+      }
+    }
+  }
+
+  return chunks;
+}
+
+// ── Shared helpers ──
+
+/**
+ * Group text units (sentences, paragraphs) into chunks under a size limit.
+ * Supports overlap by re-including trailing units from the previous chunk.
+ * @param {string[]} units
+ * @param {number} maxSize
+ * @param {number} overlapChars
+ * @param {number} minSize
+ * @returns {string[]}
+ */
+function groupUnits(units, maxSize, overlapChars, minSize) {
+  const chunks = [];
+  let current = [];
+  let currentLen = 0;
+
+  for (const unit of units) {
+    const addLen = current.length > 0 ? unit.length + 1 : unit.length; // +1 for space
+
+    if (currentLen + addLen > maxSize && current.length > 0) {
+      chunks.push(current.join(' ').trim());
+
+      // Overlap: keep trailing units that fit within overlap budget
+      if (overlapChars > 0) {
+        let overlapUnits = [];
+        let overlapLen = 0;
+        for (let i = current.length - 1; i >= 0; i--) {
+          if (overlapLen + current[i].length + 1 > overlapChars) break;
+          overlapUnits.unshift(current[i]);
+          overlapLen += current[i].length + 1;
+        }
+        current = overlapUnits;
+        currentLen = overlapLen;
+      } else {
+        current = [];
+        currentLen = 0;
+      }
+    }
+
+    current.push(unit);
+    currentLen += addLen;
+  }
+
+  // Flush remainder
+  if (current.length > 0) {
+    const text = current.join(' ').trim();
+    if (text.length >= minSize) chunks.push(text);
+  }
+
+  return chunks;
+}
+
+// ── Token estimation ──
+
+/**
+ * Rough token estimate. ~4 chars per token for English text.
+ * @param {string} text
+ * @returns {number}
+ */
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+// ── Public API ──
+
+/**
+ * Chunk text using the specified strategy.
+ * @param {string} text - Input text
+ * @param {object} [options]
+ * @param {string} [options.strategy='recursive'] - Chunking strategy
+ * @param {number} [options.size=512] - Target chunk size in characters
+ * @param {number} [options.overlap=50] - Overlap between chunks in characters
+ * @param {number} [options.minSize=20] - Minimum chunk size
+ * @returns {string[]} Array of text chunks
+ */
+function chunk(text, options = {}) {
+  const opts = {
+    strategy: options.strategy || 'recursive',
+    size: options.size || DEFAULTS.size,
+    overlap: options.overlap != null ? options.overlap : DEFAULTS.overlap,
+    minSize: options.minSize || DEFAULTS.minSize,
+  };
+
+  if (!text || text.trim().length === 0) return [];
+
+  switch (opts.strategy) {
+    case 'fixed':
+      return chunkFixed(text, opts);
+    case 'sentence':
+      return chunkSentence(text, opts);
+    case 'paragraph':
+      return chunkParagraph(text, opts);
+    case 'recursive':
+      return chunkRecursive(text, opts);
+    case 'markdown':
+      return chunkMarkdown(text, opts);
+    default:
+      throw new Error(`Unknown chunking strategy: ${opts.strategy}. Available: ${STRATEGIES.join(', ')}`);
+  }
+}
+
+module.exports = {
+  chunk,
+  splitSentences,
+  estimateTokens,
+  STRATEGIES,
+  DEFAULTS,
+};

package/src/lib/explanations.js

@@ -513,6 +513,169 @@ const concepts = {
       'vai benchmark similarity --query "your search query" --file your-docs.txt',
     ],
   },
+  'mixture-of-experts': {
+    title: 'Mixture-of-Experts (MoE) Architecture',
+    summary: 'How voyage-4-large achieves SOTA quality at 40% lower cost',
+    content: [
+      `${pc.cyan('Mixture-of-Experts (MoE)')} is a neural network architecture where multiple`,
+      `specialized sub-networks ("experts") share a single model. A learned ${pc.cyan('router')}`,
+      `selects which experts activate for each input — typically 2-4 out of 8-64 total.`,
+      ``,
+      `${pc.bold('Why MoE matters for embeddings:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('Higher capacity, lower cost')} — the model has more total parameters`,
+      `    (knowledge) but only activates a fraction per input, keeping inference fast`,
+      `  ${pc.dim('•')} ${pc.cyan('Specialization')} — different experts learn different domains (code,`,
+      `    legal, medical) without interfering with each other`,
+      `  ${pc.dim('•')} ${pc.cyan('State-of-the-art quality')} — voyage-4-large beats all competitors on`,
+      `    RTEB benchmarks while costing 40% less than comparable dense models`,
+      ``,
+      `${pc.bold('voyage-4-large')} is the ${pc.cyan('first production-grade embedding model')} to use MoE.`,
+      `Previous MoE successes (Mixtral, Switch Transformer) were language models —`,
+      `applying MoE to embedding models required solving alignment across the shared`,
+      `embedding space, which is what makes the Voyage 4 family unique.`,
+      ``,
+      `${pc.bold('Dense vs MoE:')}`,
+      `  ${pc.dim('Dense (voyage-4, voyage-4-lite):')} Every parameter is used for every input.`,
+      `    Simpler, predictable latency, lower total parameter count.`,
+      `  ${pc.dim('MoE (voyage-4-large):')} Sparse activation — more total parameters, but each`,
+      `    input only uses a subset. Higher quality ceiling, similar serving cost.`,
+      ``,
+      `${pc.bold('In practice:')} You don't need to do anything special to use MoE — the API`,
+      `interface is identical. The architecture difference shows up in quality and cost:`,
+      `  ${pc.dim('•')} voyage-4-large: $0.12/1M tokens — better quality than voyage-3-large ($0.18/1M)`,
+      `  ${pc.dim('•')} 40% cheaper than comparable dense models at the same quality tier`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+      'https://www.mongodb.com/docs/voyageai/models/text-embeddings/',
+    ],
+    tryIt: [
+      'vai embed "test MoE quality" --model voyage-4-large',
+      'vai benchmark embed --models voyage-4-large,voyage-4,voyage-4-lite',
+      'vai models --wide',
+    ],
+  },
+
+  'shared-embedding-space': {
+    title: 'Shared Embedding Space',
+    summary: 'How Voyage 4 models produce compatible, interchangeable embeddings',
+    content: [
+      `The Voyage 4 series introduces an ${pc.cyan('industry-first capability')}: all four models`,
+      `(voyage-4-large, voyage-4, voyage-4-lite, voyage-4-nano) produce embeddings in`,
+      `the ${pc.cyan('same vector space')}. Embeddings from different models are directly comparable.`,
+      ``,
+      `${pc.bold('What this means:')}`,
+      `  ${pc.dim('•')} Embed documents with ${pc.cyan('voyage-4-large')} (best quality, one-time cost)`,
+      `  ${pc.dim('•')} Query with ${pc.cyan('voyage-4-lite')} or ${pc.cyan('voyage-4-nano')} (low cost, high volume)`,
+      `  ${pc.dim('•')} Cosine similarity works across model boundaries`,
+      `  ${pc.dim('•')} Upgrade query model later ${pc.cyan('without re-vectorizing documents')}`,
+      ``,
+      `${pc.bold('Why this is new:')} Previously, embeddings from different models lived in`,
+      `incompatible vector spaces. Switching models meant re-embedding your entire`,
+      `corpus — expensive and slow. The shared space eliminates this constraint.`,
+      ``,
+      `${pc.bold('Recommended workflow:')}`,
+      `  ${pc.dim('1.')} Vectorize your document corpus once with ${pc.cyan('voyage-4-large')}`,
+      `  ${pc.dim('2.')} Start with ${pc.cyan('voyage-4-lite')} for queries in development / early production`,
+      `  ${pc.dim('3.')} Upgrade to ${pc.cyan('voyage-4')} or ${pc.cyan('voyage-4-large')} as accuracy needs grow`,
+      `  ${pc.dim('4.')} No re-vectorization needed at any step`,
+      ``,
+      `${pc.bold('Validate it yourself:')} Use ${pc.cyan('vai benchmark space')} to embed identical text`,
+      `with all Voyage 4 models and see the cross-model cosine similarities.`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+    ],
+    tryIt: [
+      'vai benchmark space',
+      'vai benchmark asymmetric --query "your search" --file corpus.txt',
+      'vai estimate --docs 1M --queries 10M',
+    ],
+  },
+
+  'rteb-benchmarks': {
+    title: 'RTEB Benchmark Scores',
+    summary: 'Retrieval quality scores across embedding providers',
+    content: [
+      `The ${pc.cyan('Retrieval Embedding Benchmark (RTEB)')} evaluates general-purpose retrieval`,
+      `quality across 29 diverse datasets. Scores are ${pc.cyan('NDCG@10')} (normalized discounted`,
+      `cumulative gain at top 10 results) — higher is better.`,
+      ``,
+      `${pc.bold('Current standings (Jan 2026):')}`,
+      `  ${pc.cyan('voyage-4-large')}       ${pc.bold('71.41')}  ${pc.dim('— SOTA, MoE architecture')}`,
+      `  ${pc.cyan('voyage-4')}             ${pc.bold('70.07')}  ${pc.dim('— near voyage-3-large quality')}`,
+      `  ${pc.cyan('Gemini Embedding 001')} ${pc.bold('68.66')}  ${pc.dim('— Google')}`,
+      `  ${pc.cyan('voyage-4-lite')}        ${pc.bold('68.10')}  ${pc.dim('— near voyage-3.5 quality')}`,
+      `  ${pc.cyan('Cohere Embed v4')}      ${pc.bold('65.75')}  ${pc.dim('— Cohere')}`,
+      `  ${pc.cyan('OpenAI v3 Large')}      ${pc.bold('62.57')}  ${pc.dim('— OpenAI')}`,
+      ``,
+      `${pc.bold('What the numbers mean:')}`,
+      `  ${pc.dim('•')} voyage-4-large beats Gemini by ${pc.cyan('3.87%')}, Cohere by ${pc.cyan('8.20%')}, OpenAI by ${pc.cyan('14.05%')}`,
+      `  ${pc.dim('•')} voyage-4 (mid-tier pricing) outperforms all non-Voyage models`,
+      `  ${pc.dim('•')} Even voyage-4-lite ($0.02/1M) is competitive with Gemini Embedding`,
+      ``,
+      `${pc.bold('Asymmetric retrieval bonus:')} When documents are embedded with voyage-4-large`,
+      `and queries with a smaller Voyage 4 model, retrieval quality ${pc.cyan('improves')} over`,
+      `using the smaller model alone — you get the benefit of the larger model's`,
+      `document representations.`,
+      ``,
+      `${pc.bold('Note:')} These scores are from Voyage AI's evaluation. Independent benchmarks`,
+      `may differ. Always test on your own data with ${pc.cyan('vai benchmark similarity')}.`,
+    ].join('\n'),
+    links: [
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+      'https://docs.google.com/spreadsheets/d/1GfPkqCAjPKaGS9f66IDhMRxVpd2bMuqL2wXjj-kNS7E/',
+    ],
+    tryIt: [
+      'vai models --benchmarks',
+      'vai benchmark similarity --query "your query" --file your-docs.txt',
+      'vai estimate --docs 1M --queries 10M',
+    ],
+  },
+
+  'voyage-4-nano': {
+    title: 'voyage-4-nano — Open-Weight Local Model',
+    summary: 'Free, local-first embeddings with shared space compatibility',
+    content: [
+      `${pc.cyan('voyage-4-nano')} is Voyage AI's first ${pc.cyan('open-weight')} embedding model, freely`,
+      `available on Hugging Face under the ${pc.bold('Apache 2.0')} license.`,
+      ``,
+      `${pc.bold('Key specs:')}`,
+      `  ${pc.dim('•')} Dimensions: 512 (default), 128, 256`,
+      `  ${pc.dim('•')} Context: 32K tokens`,
+      `  ${pc.dim('•')} License: Apache 2.0 (fully open)`,
+      `  ${pc.dim('•')} Shared space: Compatible with voyage-4-large/4/4-lite embeddings`,
+      ``,
+      `${pc.bold('Use cases:')}`,
+      `  ${pc.dim('•')} ${pc.cyan('Local development')} — no API key, no network, no cost`,
+      `  ${pc.dim('•')} ${pc.cyan('Prototyping')} — fast iteration before committing to API models`,
+      `  ${pc.dim('•')} ${pc.cyan('Edge/on-device')} — run inference on your own hardware`,
+      `  ${pc.dim('•')} ${pc.cyan('Asymmetric queries')} — use nano for queries against voyage-4-large docs`,
+      ``,
+      `${pc.bold('Getting started with Hugging Face:')}`,
+      `  ${pc.dim('pip install sentence-transformers')}`,
+      `  ${pc.dim('from sentence_transformers import SentenceTransformer')}`,
+      `  ${pc.dim('model = SentenceTransformer("voyageai/voyage-4-nano")')}`,
+      `  ${pc.dim('embeddings = model.encode(["your text here"])')}`,
+      ``,
+      `${pc.bold('With the Voyage API:')} voyage-4-nano is also available via the standard API`,
+      `endpoint, so you can use ${pc.cyan('vai embed --model voyage-4-nano')} for testing before`,
+      `switching to local inference.`,
+      ``,
+      `${pc.bold('Shared space advantage:')} Since nano shares the same embedding space as the`,
+      `larger Voyage 4 models, you can prototype locally with nano, then seamlessly`,
+      `use the same document embeddings with voyage-4 or voyage-4-large in production.`,
+    ].join('\n'),
+    links: [
+      'https://huggingface.co/voyageai/voyage-4-nano',
+      'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+    ],
+    tryIt: [
+      'vai embed "test nano" --model voyage-4-nano',
+      'vai benchmark space',
+      'vai benchmark asymmetric --doc-model voyage-4-large --query-models voyage-4-nano',
+    ],
+  },
 };
 
 /**
@@ -567,6 +730,26 @@ const aliases = {
   'model-selection': 'benchmarking',
   choosing: 'benchmarking',
   compare: 'benchmarking',
+  moe: 'mixture-of-experts',
+  'mixture-of-experts': 'mixture-of-experts',
+  'moe-architecture': 'mixture-of-experts',
+  experts: 'mixture-of-experts',
+  sparse: 'mixture-of-experts',
+  'shared-space': 'shared-embedding-space',
+  'shared-embedding-space': 'shared-embedding-space',
+  'embedding-space': 'shared-embedding-space',
+  interchangeable: 'shared-embedding-space',
+  compatible: 'shared-embedding-space',
+  rteb: 'rteb-benchmarks',
+  'rteb-benchmarks': 'rteb-benchmarks',
+  ndcg: 'rteb-benchmarks',
+  scores: 'rteb-benchmarks',
+  leaderboard: 'rteb-benchmarks',
+  nano: 'voyage-4-nano',
+  'voyage-4-nano': 'voyage-4-nano',
+  'open-weight': 'voyage-4-nano',
+  huggingface: 'voyage-4-nano',
+  local: 'voyage-4-nano',
 };
 
 /**

package/src/lib/project.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_FILE = '.vai.json';
+const PROJECT_VERSION = 1;
+
+/**
+ * Search for .vai.json starting from startDir, walking up to root.
+ * @param {string} [startDir] - Directory to start from (default: cwd)
+ * @returns {string|null} Absolute path to .vai.json or null
+ */
+function findProjectFile(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    const candidate = path.join(dir, PROJECT_FILE);
+    if (fs.existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  // Check root too
+  const rootCandidate = path.join(root, PROJECT_FILE);
+  if (fs.existsSync(rootCandidate)) return rootCandidate;
+
+  return null;
+}
+
+/**
+ * Load project config from .vai.json.
+ * @param {string} [startDir] - Directory to start searching from
+ * @returns {{ config: object, filePath: string|null }}
+ */
+function loadProject(startDir) {
+  const filePath = findProjectFile(startDir);
+  if (!filePath) return { config: {}, filePath: null };
+
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    return { config: JSON.parse(raw), filePath };
+  } catch (err) {
+    return { config: {}, filePath };
+  }
+}
+
+/**
+ * Save project config to .vai.json.
+ * @param {object} config - Project configuration
+ * @param {string} [targetPath] - Path to write (default: cwd/.vai.json)
+ */
+function saveProject(config, targetPath) {
+  const filePath = targetPath || path.join(process.cwd(), PROJECT_FILE);
+  const output = { version: PROJECT_VERSION, ...config };
+  fs.writeFileSync(filePath, JSON.stringify(output, null, 2) + '\n', 'utf-8');
+  return filePath;
+}
+
+/**
+ * Merge project config with CLI options. CLI options take precedence.
+ * Only merges known keys — doesn't blindly spread everything.
+ * @param {object} projectConfig - From .vai.json
+ * @param {object} cliOpts - From commander
+ * @returns {object} Merged options
+ */
+function mergeOptions(projectConfig, cliOpts) {
+  const merged = {};
+
+  // Map of project config keys → CLI option keys
+  const keys = [
+    'model', 'db', 'collection', 'field', 'inputType',
+    'dimensions', 'index',
+  ];
+
+  for (const key of keys) {
+    // CLI explicit value wins, then project config, then undefined
+    if (cliOpts[key] !== undefined) {
+      merged[key] = cliOpts[key];
+    } else if (projectConfig[key] !== undefined) {
+      merged[key] = projectConfig[key];
+    }
+  }
+
+  // Chunk config nests under project.chunk
+  if (projectConfig.chunk) {
+    merged.chunk = { ...projectConfig.chunk };
+  }
+
+  return merged;
+}
+
+/**
+ * Default project config scaffold.
+ * @returns {object}
+ */
+function defaultProjectConfig() {
+  return {
+    version: PROJECT_VERSION,
+    model: 'voyage-4-large',
+    db: '',
+    collection: '',
+    field: 'embedding',
+    inputType: 'document',
+    dimensions: 1024,
+    index: 'vector_index',
+    chunk: {
+      strategy: 'recursive',
+      size: 512,
+      overlap: 50,
+    },
+  };
+}
+
+module.exports = {
+  PROJECT_FILE,
+  PROJECT_VERSION,
+  findProjectFile,
+  loadProject,
+  saveProject,
+  mergeOptions,
+  defaultProjectConfig,
+};