@vectororm/core 0.1.0

package/dist/index.js

@@ -0,0 +1,2508 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_CHUNK_OVERLAP: () => DEFAULT_CHUNK_OVERLAP,
+  DEFAULT_CHUNK_SIZE: () => DEFAULT_CHUNK_SIZE,
+  DOCXLoader: () => DOCXLoader,
+  Embedder: () => Embedder,
+  EmbeddingThemeClassifier: () => EmbeddingThemeClassifier,
+  EnrichmentPipeline: () => EnrichmentPipeline,
+  FilterBuilder: () => FilterBuilder,
+  FilterTranslator: () => FilterTranslator,
+  FixedChunker: () => FixedChunker,
+  HTMLLoader: () => HTMLLoader,
+  HorizontalFields: () => HorizontalFields,
+  IngestionPipeline: () => IngestionPipeline,
+  KeywordThemeClassifier: () => KeywordThemeClassifier,
+  LLMClient: () => LLMClient,
+  LLMThemeClassifier: () => LLMThemeClassifier,
+  LoaderRegistry: () => LoaderRegistry,
+  METADATA_PREFIXES: () => METADATA_PREFIXES,
+  MetadataBuilder: () => MetadataBuilder,
+  MockLLM: () => MockLLM,
+  PDFLoader: () => PDFLoader,
+  RAGClient: () => RAGClient,
+  RAGQueryComposer: () => RAGQueryComposer,
+  RecursiveChunker: () => RecursiveChunker,
+  SentenceChunker: () => SentenceChunker,
+  StructuralFields: () => StructuralFields,
+  TextLoader: () => TextLoader,
+  VectorDBAdapter: () => VectorDBAdapter,
+  VerticalFields: () => VerticalFields,
+  ZeroShotThemeClassifier: () => ZeroShotThemeClassifier,
+  estimateChars: () => estimateChars,
+  estimateTokens: () => estimateTokens
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/metadata/constants.ts
+var METADATA_PREFIXES = {
+  VERTICAL: "__v_",
+  HORIZONTAL: "__h_",
+  STRUCTURAL: "__s_"
+};
+var VerticalFields = {
+  /** Unique document identifier */
+  DOC_ID: "__v_doc_id",
+  /** Original source path/URL */
+  SOURCE: "__v_source",
+  /** Logical partition key (for filtering by document subsets) */
+  PARTITION: "__v_partition",
+  /** Document type classification */
+  DOC_TYPE: "__v_doc_type",
+  /** Arbitrary vertical tags */
+  TAGS: "__v_tags"
+};
+var HorizontalFields = {
+  /** Primary theme classification */
+  THEME: "__h_theme",
+  /** Multiple themes (if applicable) */
+  THEMES: "__h_themes",
+  /** Classification confidence score */
+  THEME_CONFIDENCE: "__h_theme_confidence",
+  /** Hierarchical section path (e.g., "Chapter 3/Pricing/Rates") */
+  SECTION_PATH: "__h_section_path",
+  /** Depth level in hierarchy (0 = root) */
+  SECTION_LEVEL: "__h_section_level",
+  /** Section header text */
+  SECTION_TITLE: "__h_section_title"
+};
+var StructuralFields = {
+  /** Position in document (0-indexed) */
+  CHUNK_INDEX: "__s_chunk_index",
+  /** Parent chunk ID (for hierarchical chunking) */
+  PARENT_ID: "__s_parent_id",
+  /** Whether this chunk has children */
+  HAS_CHILDREN: "__s_has_children",
+  /** Total chunks in this document */
+  TOTAL_CHUNKS: "__s_total_chunks"
+};
+
+// src/metadata/builder.ts
+var MetadataBuilder = class {
+  metadata = {};
+  /**
+   * Add vertical axis metadata (document identity).
+   * Automatically prefixes fields with '__v_'.
+   *
+   * @param fields - Vertical metadata fields (doc_id, source, partition, etc.)
+   * @returns This builder for chaining
+   */
+  vertical(fields) {
+    for (const [key, value] of Object.entries(fields)) {
+      if (value !== void 0) {
+        this.metadata[`${METADATA_PREFIXES.VERTICAL}${key}`] = value;
+      }
+    }
+    return this;
+  }
+  /**
+   * Add horizontal axis metadata (theme/section identity).
+   * Automatically prefixes fields with '__h_'.
+   *
+   * @param fields - Horizontal metadata fields (theme, section_path, etc.)
+   * @returns This builder for chaining
+   */
+  horizontal(fields) {
+    for (const [key, value] of Object.entries(fields)) {
+      if (value !== void 0) {
+        this.metadata[`${METADATA_PREFIXES.HORIZONTAL}${key}`] = value;
+      }
+    }
+    return this;
+  }
+  /**
+   * Add structural axis metadata (position/hierarchy).
+   * Automatically prefixes fields with '__s_'.
+   *
+   * @param fields - Structural metadata fields (chunk_index, parent_id, etc.)
+   * @returns This builder for chaining
+   */
+  structural(fields) {
+    for (const [key, value] of Object.entries(fields)) {
+      if (value !== void 0) {
+        this.metadata[`${METADATA_PREFIXES.STRUCTURAL}${key}`] = value;
+      }
+    }
+    return this;
+  }
+  /**
+   * Add custom user-defined metadata.
+   * Fields are added as-is without any prefix.
+   *
+   * @param fields - Custom metadata fields
+   * @returns This builder for chaining
+   */
+  custom(fields) {
+    for (const [key, value] of Object.entries(fields)) {
+      if (value !== void 0) {
+        this.metadata[key] = value;
+      }
+    }
+    return this;
+  }
+  /**
+   * Build and return the complete metadata object.
+   * Returns a copy to prevent external modification.
+   *
+   * @returns Immutable copy of the metadata object
+   */
+  build() {
+    return { ...this.metadata };
+  }
+};
+
+// src/filters/translator.ts
+var VALID_OPERATORS = [
+  "eq",
+  "neq",
+  "in",
+  "nin",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "contains",
+  "exists"
+];
+var FilterTranslator = class {
+  /**
+   * Normalize any filter input to standard UniversalFilter format.
+   *
+   * Handles:
+   * - Standard format (pass through)
+   * - Shorthand format (convert to standard)
+   * - Operator suffixes (field__op syntax)
+   */
+  static normalize(input) {
+    if (this.isStandardFormat(input)) {
+      return input;
+    }
+    return this.fromShorthand(input);
+  }
+  /**
+   * Validate filter structure and operators.
+   *
+   * Throws error if filter is invalid.
+   */
+  static validate(filter) {
+    if (this.isCompound(filter)) {
+      const compound = filter;
+      const conditions = "and" in compound ? compound.and : compound.or;
+      if (!Array.isArray(conditions) || conditions.length === 0) {
+        throw new Error("Compound filter must have at least one condition");
+      }
+      conditions.forEach((c) => this.validate(c));
+    } else {
+      const condition = filter;
+      if (!condition.field || typeof condition.field !== "string") {
+        throw new Error("Filter field must be a non-empty string");
+      }
+      if (!VALID_OPERATORS.includes(condition.op)) {
+        throw new Error(`Invalid filter operator: ${condition.op}`);
+      }
+      if (condition.value === void 0) {
+        throw new Error("Filter value is required");
+      }
+    }
+  }
+  /**
+   * Check if filter is compound (AND/OR).
+   */
+  static isCompound(filter) {
+    return "and" in filter || "or" in filter;
+  }
+  /**
+   * Check if input is already in standard format.
+   */
+  static isStandardFormat(input) {
+    if (!input || typeof input !== "object") {
+      return false;
+    }
+    if ("and" in input || "or" in input) {
+      return true;
+    }
+    if ("field" in input && "op" in input && "value" in input) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Convert shorthand format to standard.
+   */
+  static fromShorthand(shorthand) {
+    const entries = Object.entries(shorthand);
+    if (entries.length === 0) {
+      throw new Error("Cannot convert empty shorthand filter object");
+    }
+    const conditions = [];
+    for (const [key, value] of entries) {
+      let field;
+      let op;
+      if (key.includes("__") && !key.startsWith("__")) {
+        const lastIndex = key.lastIndexOf("__");
+        field = key.substring(0, lastIndex);
+        const extractedOp = key.substring(lastIndex + 2);
+        if (!VALID_OPERATORS.includes(extractedOp)) {
+          throw new Error(`Invalid filter operator in shorthand: ${extractedOp}`);
+        }
+        op = extractedOp;
+      } else {
+        field = key;
+        op = "eq";
+      }
+      conditions.push({ field, op, value });
+    }
+    if (conditions.length === 1) {
+      return conditions[0];
+    }
+    return { and: conditions };
+  }
+};
+
+// src/adapters/vector-db-adapter.ts
+var VectorDBAdapter = class {
+  // ============================================================================
+  // CAPABILITY FLAGS (WITH DEFAULT IMPLEMENTATIONS)
+  // ============================================================================
+  /**
+   * Whether this adapter supports metadata updates without re-uploading vectors.
+   *
+   * Default: false (must re-upload entire record)
+   * Override to return true if your DB supports partial updates.
+   */
+  supportsMetadataUpdate() {
+    return false;
+  }
+  /**
+   * Whether this adapter supports filtering during search.
+   *
+   * Default: false (no filtering support)
+   * Override to return true if your DB supports metadata filtering.
+   */
+  supportsFiltering() {
+    return false;
+  }
+  /**
+   * Whether this adapter supports batch operations efficiently.
+   *
+   * Default: false (single operations only)
+   * Override to return true if your DB supports batch upsert/delete.
+   */
+  supportsBatchOperations() {
+    return false;
+  }
+};
+
+// src/query/filter-builder.ts
+var FilterBuilder = class {
+  verticalFilter;
+  horizontalFilter;
+  customFilter;
+  /**
+   * Add a vertical (document-level) filter.
+   *
+   * @param filter - The vertical filter to add (standard or shorthand format)
+   * @returns This builder for method chaining
+   */
+  withVerticalFilter(filter) {
+    this.verticalFilter = FilterTranslator.normalize(filter);
+    return this;
+  }
+  /**
+   * Add a horizontal (theme-level) filter.
+   *
+   * @param filter - The horizontal filter to add (standard or shorthand format)
+   * @returns This builder for method chaining
+   */
+  withHorizontalFilter(filter) {
+    this.horizontalFilter = FilterTranslator.normalize(filter);
+    return this;
+  }
+  /**
+   * Add a custom user-defined filter.
+   *
+   * @param filter - The custom filter to add (standard or shorthand format)
+   * @returns This builder for method chaining
+   */
+  withCustomFilter(filter) {
+    this.customFilter = FilterTranslator.normalize(filter);
+    return this;
+  }
+  /**
+   * Build the combined filter.
+   *
+   * Combination logic:
+   * - If no filters: returns undefined
+   * - If single filter: returns it directly
+   * - If multiple filters: combines with AND logic
+   *
+   * @returns The combined filter, or undefined if no filters were added
+   */
+  build() {
+    const filters = [];
+    if (this.verticalFilter) {
+      filters.push(this.verticalFilter);
+    }
+    if (this.horizontalFilter) {
+      filters.push(this.horizontalFilter);
+    }
+    if (this.customFilter) {
+      filters.push(this.customFilter);
+    }
+    if (filters.length === 0) {
+      return void 0;
+    }
+    if (filters.length === 1) {
+      return filters[0];
+    }
+    return { and: filters };
+  }
+};
+
+// src/query/rag-query-composer.ts
+var RAGQueryComposer = class {
+  /**
+   * Create a new RAGQueryComposer.
+   *
+   * @param adapter - Vector database adapter for search operations
+   * @param embedder - Embedder for converting text queries to vectors
+   */
+  constructor(adapter, embedder) {
+    this.adapter = adapter;
+    this.embedder = embedder;
+  }
+  /**
+   * Main retrieval method.
+   *
+   * Performs semantic search with optional filtering:
+   * 1. Embeds query text using embedder
+   * 2. Builds combined filter using FilterBuilder
+   * 3. Calls adapter.search() with query vector and filter
+   * 4. Returns results with filter information
+   *
+   * @param params - Retrieval parameters
+   * @returns Retrieval result with records and filter information
+   */
+  async retrieve(params) {
+    const queryVector = await this.embedder.embed(params.query);
+    const filterBuilder = new FilterBuilder();
+    if (params.verticalFilters) {
+      filterBuilder.withVerticalFilter(params.verticalFilters);
+    }
+    if (params.horizontalFilters) {
+      filterBuilder.withHorizontalFilter(params.horizontalFilters);
+    }
+    if (params.customFilters) {
+      filterBuilder.withCustomFilter(params.customFilters);
+    }
+    const combinedFilter = filterBuilder.build();
+    const searchResult = await this.adapter.search(
+      params.collection,
+      queryVector,
+      {
+        topK: params.topK,
+        filter: combinedFilter,
+        includeMetadata: true,
+        includeValues: params.includeEmbeddings
+      }
+    );
+    return {
+      records: searchResult.records,
+      query: params.query,
+      filtersApplied: {
+        ...params.verticalFilters && { vertical: params.verticalFilters },
+        ...params.horizontalFilters && { horizontal: params.horizontalFilters },
+        ...params.customFilters && { custom: params.customFilters }
+      }
+    };
+  }
+  /**
+   * Retrieve and group results by document ID.
+   *
+   * Calls retrieve() and organizes results into a Map keyed by __v_doc_id.
+   * Records without a doc_id are excluded.
+   *
+   * @param params - Retrieval parameters
+   * @returns Map of document ID to array of records
+   */
+  async retrieveVertical(params) {
+    const result = await this.retrieve(params);
+    const grouped = /* @__PURE__ */ new Map();
+    for (const record of result.records) {
+      const docId = record.metadata[VerticalFields.DOC_ID];
+      if (typeof docId === "string") {
+        if (!grouped.has(docId)) {
+          grouped.set(docId, []);
+        }
+        grouped.get(docId).push(record);
+      }
+    }
+    return grouped;
+  }
+  /**
+   * Retrieve and group results by theme.
+   *
+   * Calls retrieve() and organizes results into a Map keyed by __h_theme.
+   * Records without a theme are excluded.
+   *
+   * @param params - Retrieval parameters
+   * @returns Map of theme to array of records
+   */
+  async retrieveHorizontal(params) {
+    const result = await this.retrieve(params);
+    const grouped = /* @__PURE__ */ new Map();
+    for (const record of result.records) {
+      const theme = record.metadata[HorizontalFields.THEME];
+      if (typeof theme === "string") {
+        if (!grouped.has(theme)) {
+          grouped.set(theme, []);
+        }
+        grouped.get(theme).push(record);
+      }
+    }
+    return grouped;
+  }
+};
+
+// src/embedders/embedder.ts
+var Embedder = class _Embedder {
+  /**
+   * Constructor is protected to prevent direct instantiation of abstract class.
+   * Subclasses can call super() in their constructors.
+   */
+  constructor() {
+    if (new.target === _Embedder) {
+      throw new Error("Cannot instantiate abstract class Embedder directly");
+    }
+  }
+};
+
+// src/llm/llm-client.ts
+var LLMClient = class _LLMClient {
+  /**
+   * Constructor is protected to prevent direct instantiation of abstract class.
+   * Subclasses can call super() in their constructors.
+   */
+  constructor() {
+    if (new.target === _LLMClient) {
+      throw new Error("Cannot instantiate abstract class LLMClient directly");
+    }
+  }
+};
+
+// src/llm/mock-llm.ts
+var MockLLM = class extends LLMClient {
+  _response = "";
+  constructor() {
+    super();
+  }
+  get modelName() {
+    return "mock-llm-v1";
+  }
+  get provider() {
+    return "mock";
+  }
+  /**
+   * Set the canned response that will be returned by generate methods.
+   *
+   * @param response - The response text to return
+   */
+  setResponse(response) {
+    this._response = response;
+  }
+  async generate(prompt, options) {
+    return this._response;
+  }
+  async generateJSON(prompt, options) {
+    try {
+      return JSON.parse(this._response);
+    } catch (error) {
+      throw new Error(
+        `Failed to parse mock response as JSON: ${error instanceof Error ? error.message : "unknown error"}`
+      );
+    }
+  }
+  async generateBatch(prompts, options) {
+    return prompts.map(() => this._response);
+  }
+};
+
+// src/enrichment/classifiers/keyword-classifier.ts
+var KeywordThemeClassifier = class {
+  /**
+   * Creates a new KeywordThemeClassifier
+   * @param themes - Array of theme names
+   * @param keywords - Map of theme names to their keyword arrays
+   * @param caseSensitive - Whether matching should be case sensitive (default: false)
+   */
+  constructor(themes, keywords, caseSensitive = false) {
+    this.themes = themes;
+    this.caseSensitive = caseSensitive;
+    this.patterns = /* @__PURE__ */ new Map();
+    this.keywordCounts = /* @__PURE__ */ new Map();
+    for (const theme of themes) {
+      const themeKeywords = keywords[theme] || [];
+      this.keywordCounts.set(theme, themeKeywords.length);
+      const patterns = themeKeywords.map((keyword) => {
+        const escapedKeyword = this.escapeRegex(keyword);
+        const flags = caseSensitive ? "g" : "gi";
+        return new RegExp(`\\b${escapedKeyword}\\b`, flags);
+      });
+      this.patterns.set(theme, patterns);
+    }
+  }
+  patterns;
+  keywordCounts;
+  /**
+   * Classify a single text
+   * @param text - Text to classify
+   * @returns Classification result with theme, confidence, and all scores
+   */
+  classify(text) {
+    if (!text || text.trim().length === 0) {
+      return {
+        theme: "unknown",
+        confidence: 0,
+        allScores: {}
+      };
+    }
+    const scores = {};
+    let maxScore = 0;
+    let winningTheme = "unknown";
+    for (const theme of this.themes) {
+      const patterns = this.patterns.get(theme) || [];
+      let matchCount = 0;
+      for (const pattern of patterns) {
+        const matches = text.match(pattern);
+        if (matches) {
+          matchCount += matches.length;
+        }
+      }
+      scores[theme] = matchCount;
+      if (matchCount > maxScore) {
+        maxScore = matchCount;
+        winningTheme = theme;
+      }
+    }
+    if (maxScore === 0) {
+      return {
+        theme: "unknown",
+        confidence: 0,
+        allScores: scores
+      };
+    }
+    const totalKeywords = this.keywordCounts.get(winningTheme) || 1;
+    const confidence = maxScore / totalKeywords;
+    return {
+      theme: winningTheme,
+      confidence: Math.min(confidence, 1),
+      // Cap at 1.0
+      allScores: scores
+    };
+  }
+  /**
+   * Classify multiple texts in batch
+   * @param texts - Array of texts to classify
+   * @returns Array of classification results
+   */
+  classifyBatch(texts) {
+    return texts.map((text) => this.classify(text));
+  }
+  /**
+   * Escape special regex characters in a string
+   * @param str - String to escape
+   * @returns Escaped string safe for use in regex
+   */
+  escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+};
+
+// src/enrichment/classifiers/zero-shot-classifier.ts
+var ZeroShotThemeClassifier = class {
+  model = null;
+  modelName;
+  themes;
+  /**
+   * Creates a new ZeroShotThemeClassifier
+   *
+   * @param themes - Array of theme labels to classify into
+   * @param modelName - Name of the Hugging Face model to use (default: 'Xenova/distilbert-base-uncased-mnli')
+   *
+   * @example
+   * ```typescript
+   * // Use default model
+   * const classifier = new ZeroShotThemeClassifier(['technology', 'sports', 'finance']);
+   *
+   * // Use custom model
+   * const classifier = new ZeroShotThemeClassifier(
+   *   ['positive', 'negative'],
+   *   'Xenova/distilbert-base-uncased-mnli'
+   * );
+   * ```
+   */
+  constructor(themes, modelName = "Xenova/distilbert-base-uncased-mnli") {
+    this.themes = themes;
+    this.modelName = modelName;
+  }
+  /**
+   * Lazy loads the zero-shot classification model
+   * Only loads once on first call, subsequent calls reuse the loaded model
+   *
+   * @returns Promise that resolves to the loaded pipeline
+   */
+  async ensureModelLoaded() {
+    if (!this.model) {
+      const { pipeline } = await import("@xenova/transformers");
+      this.model = await pipeline("zero-shot-classification", this.modelName);
+    }
+    return this.model;
+  }
+  /**
+   * Classify a single text into one of the provided themes
+   *
+   * @param text - The text content to classify
+   * @returns A promise that resolves to the theme classification result
+   *
+   * @example
+   * ```typescript
+   * const classifier = new ZeroShotThemeClassifier(['technology', 'sports']);
+   * const result = await classifier.classify('Machine learning and AI');
+   * console.log(result.theme); // 'technology'
+   * console.log(result.confidence); // 0.92
+   * console.log(result.allScores); // { technology: 0.92, sports: 0.08 }
+   * ```
+   */
+  async classify(text) {
+    if (!text || text.trim().length === 0) {
+      const uniformScore = 1 / this.themes.length;
+      const allScores2 = {};
+      for (const theme of this.themes) {
+        allScores2[theme] = uniformScore;
+      }
+      return {
+        theme: this.themes[0],
+        // Return first theme
+        confidence: uniformScore,
+        allScores: allScores2
+      };
+    }
+    const model = await this.ensureModelLoaded();
+    const result = await model(text, this.themes);
+    const allScores = {};
+    for (let i = 0; i < result.labels.length; i++) {
+      allScores[result.labels[i]] = result.scores[i];
+    }
+    return {
+      theme: result.labels[0],
+      confidence: result.scores[0],
+      allScores
+    };
+  }
+  /**
+   * Classify multiple texts efficiently
+   *
+   * Processes texts sequentially to avoid memory issues with large batches.
+   * The model is loaded once and reused for all texts.
+   *
+   * @param texts - Array of text contents to classify
+   * @returns A promise that resolves to an array of theme classifications
+   *
+   * @example
+   * ```typescript
+   * const classifier = new ZeroShotThemeClassifier(['technology', 'sports', 'finance']);
+   * const results = await classifier.classifyBatch([
+   *   'Machine learning is transforming AI',
+   *   'The football team won the championship',
+   *   'Stock market hits record high'
+   * ]);
+   * // results[0].theme === 'technology'
+   * // results[1].theme === 'sports'
+   * // results[2].theme === 'finance'
+   * ```
+   */
+  async classifyBatch(texts) {
+    await this.ensureModelLoaded();
+    const results = [];
+    for (const text of texts) {
+      const result = await this.classify(text);
+      results.push(result);
+    }
+    return results;
+  }
+};
+
+// src/enrichment/classifiers/embedding-classifier.ts
+var EmbeddingThemeClassifier = class {
+  themeEmbeddings = null;
+  embedder;
+  themes;
+  /**
+   * Creates a new EmbeddingThemeClassifier
+   *
+   * @param themes - Array of theme labels to classify into
+   * @param embedder - Embedder instance to use for generating embeddings
+   * @param precomputedEmbeddings - Optional precomputed theme embeddings for faster startup
+   *
+   * @example
+   * ```typescript
+   * // Lazy initialization
+   * const classifier = new EmbeddingThemeClassifier(['technology', 'sports'], embedder);
+   *
+   * // With precomputed embeddings
+   * const themeEmbeddings = {
+   *   technology: await embedder.embed('technology'),
+   *   sports: await embedder.embed('sports')
+   * };
+   * const classifier = new EmbeddingThemeClassifier(['technology', 'sports'], embedder, themeEmbeddings);
+   * ```
+   */
+  constructor(themes, embedder, precomputedEmbeddings) {
+    this.themes = themes;
+    this.embedder = embedder;
+    this.themeEmbeddings = precomputedEmbeddings || null;
+  }
+  /**
+   * Lazy loads theme embeddings on first use
+   * Computes embeddings for all theme labels if not already computed
+   *
+   * @returns Promise that resolves to the theme embeddings map
+   */
+  async ensureThemeEmbeddings() {
+    if (!this.themeEmbeddings) {
+      this.themeEmbeddings = {};
+      const embeddings = await this.embedder.embedBatch(this.themes);
+      for (let i = 0; i < this.themes.length; i++) {
+        this.themeEmbeddings[this.themes[i]] = embeddings[i];
+      }
+    }
+    return this.themeEmbeddings;
+  }
+  /**
+   * Compute cosine similarity between two vectors
+   *
+   * Cosine similarity = dotProduct / (normA * normB)
+   * Returns value in range [-1, 1] where:
+   * - 1 means vectors point in the same direction
+   * - 0 means vectors are orthogonal
+   * - -1 means vectors point in opposite directions
+   *
+   * @param a - First vector
+   * @param b - Second vector
+   * @returns Cosine similarity between the vectors
+   */
+  cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+      throw new Error("Vectors must have the same length for cosine similarity");
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    normA = Math.sqrt(normA);
+    normB = Math.sqrt(normB);
+    if (normA === 0 || normB === 0) {
+      return 0;
+    }
+    return dotProduct / (normA * normB);
+  }
+  /**
+   * Normalize cosine similarity from [-1, 1] to confidence score [0, 1]
+   *
+   * Uses linear transformation: (similarity + 1) / 2
+   *
+   * @param similarity - Cosine similarity value in range [-1, 1]
+   * @returns Confidence score in range [0, 1]
+   */
+  normalizeToConfidence(similarity) {
+    return (similarity + 1) / 2;
+  }
+  /**
+   * Classify a single text into one of the provided themes
+   *
+   * @param text - The text content to classify
+   * @returns A promise that resolves to the theme classification result
+   *
+   * @example
+   * ```typescript
+   * const classifier = new EmbeddingThemeClassifier(['technology', 'sports'], embedder);
+   * const result = await classifier.classify('Machine learning and AI');
+   * console.log(result.theme); // 'technology'
+   * console.log(result.confidence); // 0.92
+   * console.log(result.allScores); // { technology: 0.92, sports: 0.45 }
+   * ```
+   */
+  async classify(text) {
+    if (!text || text.trim().length === 0) {
+      const uniformScore = 1 / this.themes.length;
+      const allScores2 = {};
+      for (const theme of this.themes) {
+        allScores2[theme] = uniformScore;
+      }
+      return {
+        theme: this.themes[0],
+        // Return first theme
+        confidence: uniformScore,
+        allScores: allScores2
+      };
+    }
+    const themeEmbeddings = await this.ensureThemeEmbeddings();
+    const textEmbedding = await this.embedder.embed(text);
+    const similarities = {};
+    let maxSimilarity = -Infinity;
+    let winningTheme = this.themes[0];
+    for (const theme of this.themes) {
+      const themeEmbedding = themeEmbeddings[theme];
+      const similarity = this.cosineSimilarity(textEmbedding, themeEmbedding);
+      similarities[theme] = similarity;
+      if (similarity > maxSimilarity) {
+        maxSimilarity = similarity;
+        winningTheme = theme;
+      }
+    }
+    const allScores = {};
+    for (const theme of this.themes) {
+      allScores[theme] = this.normalizeToConfidence(similarities[theme]);
+    }
+    return {
+      theme: winningTheme,
+      confidence: this.normalizeToConfidence(maxSimilarity),
+      allScores
+    };
+  }
+  /**
+   * Classify multiple texts efficiently
+   *
+   * Ensures theme embeddings are loaded once, then processes all texts.
+   * Text embeddings are computed in batch for efficiency.
+   *
+   * @param texts - Array of text contents to classify
+   * @returns A promise that resolves to an array of theme classifications
+   *
+   * @example
+   * ```typescript
+   * const classifier = new EmbeddingThemeClassifier(['technology', 'sports', 'finance'], embedder);
+   * const results = await classifier.classifyBatch([
+   *   'Machine learning is transforming AI',
+   *   'The football team won the championship',
+   *   'Stock market hits record high'
+   * ]);
+   * // results[0].theme === 'technology'
+   * // results[1].theme === 'sports'
+   * // results[2].theme === 'finance'
+   * ```
+   */
+  async classifyBatch(texts) {
+    await this.ensureThemeEmbeddings();
+    const results = [];
+    for (const text of texts) {
+      const result = await this.classify(text);
+      results.push(result);
+    }
+    return results;
+  }
+};
+
+// src/enrichment/classifiers/llm-classifier.ts
+var DEFAULT_PROMPT_TEMPLATE = `You are a theme classification system. Classify the following text into one of the provided themes.
+
+Available themes: {themes}
+
+Text to classify:
+{text}
+
+Return a JSON object with the following structure:
+- theme: the most appropriate theme from the list (string)
+- confidence: confidence score between 0 and 1 (number)
+- allScores: an object mapping each theme to its confidence score (object)
+
+Return only valid JSON, no additional text.`;
+var LLMThemeClassifier = class {
+  themes;
+  llm;
+  promptTemplate;
+  /**
+   * Creates a new LLMThemeClassifier
+   *
+   * @param themes - Array of theme labels to classify into
+   * @param llm - LLM client instance to use for classification
+   * @param promptTemplate - Optional custom prompt template with {themes} and {text} placeholders
+   *
+   * @example
+   * ```typescript
+   * const classifier = new LLMThemeClassifier(
+   *   ['technology', 'sports', 'finance'],
+   *   llm
+   * );
+   * ```
+   *
+   * @example With custom prompt
+   * ```typescript
+   * const customTemplate = `Classify: {text}\nThemes: {themes}\nReturn JSON.`;
+   * const classifier = new LLMThemeClassifier(
+   *   ['technology', 'sports'],
+   *   llm,
+   *   customTemplate
+   * );
+   * ```
+   */
+  constructor(themes, llm, promptTemplate = DEFAULT_PROMPT_TEMPLATE) {
+    this.themes = themes;
+    this.llm = llm;
+    this.promptTemplate = promptTemplate;
+  }
+  /**
+   * Build the classification prompt by replacing placeholders
+   *
+   * @param text - The text to classify
+   * @returns The complete prompt with placeholders replaced
+   */
+  buildPrompt(text) {
+    const themesStr = this.themes.join(", ");
+    return this.promptTemplate.replace("{themes}", themesStr).replace("{text}", text);
+  }
+  /**
+   * Classify a single text into one of the provided themes
+   *
+   * @param text - The text content to classify
+   * @returns A promise that resolves to the theme classification result
+   *
+   * @example
+   * ```typescript
+   * const classifier = new LLMThemeClassifier(['technology', 'sports'], llm);
+   * const result = await classifier.classify('Machine learning and AI');
+   * console.log(result.theme); // 'technology'
+   * console.log(result.confidence); // 0.95
+   * console.log(result.allScores); // { technology: 0.95, sports: 0.05 }
+   * ```
+   */
+  async classify(text) {
+    if (!text || text.trim().length === 0) {
+      const uniformScore = 1 / this.themes.length;
+      const allScores = {};
+      for (const theme of this.themes) {
+        allScores[theme] = uniformScore;
+      }
+      return {
+        theme: this.themes[0],
+        // Return first theme
+        confidence: uniformScore,
+        allScores
+      };
+    }
+    const prompt = this.buildPrompt(text);
+    try {
+      const result = await this.llm.generateJSON(prompt);
+      return result;
+    } catch (error) {
+      const message = `Failed to classify text with LLM: ${error instanceof Error ? error.message : "unknown error"}`;
+      const classificationError = new Error(message);
+      if (error instanceof Error) {
+        classificationError.cause = error;
+      }
+      throw classificationError;
+    }
+  }
+  /**
+   * Classify multiple texts sequentially
+   *
+   * Processes texts one at a time to avoid rate limits and ensure predictable behavior.
+   * Sequential processing provides better error handling and rate limit compliance.
+   *
+   * @param texts - Array of text contents to classify
+   * @returns A promise that resolves to an array of theme classifications
+   *
+   * @example
+   * ```typescript
+   * const classifier = new LLMThemeClassifier(['technology', 'sports', 'finance'], llm);
+   * const results = await classifier.classifyBatch([
+   *   'Machine learning is transforming AI',
+   *   'The football team won the championship',
+   *   'Stock market hits record high'
+   * ]);
+   * // results[0].theme === 'technology'
+   * // results[1].theme === 'sports'
+   * // results[2].theme === 'finance'
+   * ```
+   */
+  async classifyBatch(texts) {
+    const results = [];
+    for (const text of texts) {
+      const result = await this.classify(text);
+      results.push(result);
+    }
+    return results;
+  }
+};
+
+// src/enrichment/enrichment-pipeline.ts
+var EnrichmentPipeline = class {
+  /**
+   * Create a new enrichment pipeline.
+   *
+   * @param adapter - Vector database adapter for reading/writing records
+   * @param embedder - Optional embedder for embedding-based enrichment
+   * @param llm - Optional LLM client for automatic enrichment
+   */
+  constructor(adapter, embedder, llm) {
+    this.adapter = adapter;
+    this.embedder = embedder;
+    this.llm = llm;
+  }
+  /**
+   * Enrich records with vertical classifications.
+   *
+   * Supports three strategies:
+   * 1. Field mapping: Map existing field values to verticals
+   * 2. Custom extractor: Use a custom function to extract verticals
+   * 3. Automatic LLM: Use an LLM to classify documents
+   *
+   * @param collection - Name of the collection to enrich
+   * @param config - Vertical enrichment configuration
+   * @returns Statistics about the enrichment operation
+   *
+   * @example
+   * ```typescript
+   * // Field mapping
+   * await pipeline.enrichVertical('docs', {
+   *   mapping: { 'tech': 'technology' }
+   * });
+   *
+   * // Custom extractor
+   * await pipeline.enrichVertical('docs', {
+   *   extractor: async (doc) => 'technology'
+   * });
+   *
+   * // Automatic LLM
+   * await pipeline.enrichVertical('docs', {
+   *   automatic: {
+   *     llm: myLLMClient,
+   *     fields: ['technology', 'finance']
+   *   }
+   * });
+   * ```
+   */
+  async enrichVertical(collection, config) {
+    const startTime = Date.now();
+    const stats = {
+      recordsProcessed: 0,
+      recordsUpdated: 0,
+      recordsSkipped: 0,
+      timeMs: 0,
+      errors: []
+    };
+    try {
+      if ("mapping" in config) {
+        await this.enrichWithFieldMapping(collection, config, stats);
+      } else if ("extractor" in config) {
+        await this.enrichWithExtractor(collection, config, stats);
+      } else if ("automatic" in config) {
+        await this.enrichWithLLM(collection, config, stats);
+      }
+    } catch (error) {
+      stats.errors?.push(
+        `Pipeline error: ${error instanceof Error ? error.message : "unknown error"}`
+      );
+    }
+    stats.timeMs = Date.now() - startTime;
+    return stats;
+  }
+  /**
+   * Enrich records using field mapping strategy.
+   *
+   * Maps values from an existing field to vertical classifications.
+   *
+   * @param collection - Collection name
+   * @param config - Field mapping configuration
+   * @param stats - Statistics object to update
+   */
+  async enrichWithFieldMapping(collection, config, stats) {
+    const batchSize = config.batchSize || 100;
+    for await (const batch of this.adapter.iterate(collection, {
+      batchSize,
+      filter: config.filter
+    })) {
+      const updates = [];
+      for (const record of batch) {
+        stats.recordsProcessed++;
+        try {
+          const vertical = this.applyFieldMapping(record, config.mapping);
+          if (vertical) {
+            updates.push({
+              id: record.id,
+              metadata: { vertical }
+            });
+          } else {
+            stats.recordsSkipped++;
+          }
+        } catch (error) {
+          stats.recordsSkipped++;
+          stats.errors?.push(
+            `Error mapping record ${record.id}: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+      if (updates.length > 0) {
+        try {
+          await this.adapter.updateMetadata(collection, updates);
+          stats.recordsUpdated += updates.length;
+        } catch (error) {
+          stats.errors?.push(
+            `Error updating batch: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Apply field mapping to extract vertical from a record.
+   *
+   * @param record - Vector record
+   * @param mapping - Field mapping configuration
+   * @returns Vertical label or null if no match
+   */
+  applyFieldMapping(record, mapping) {
+    const category = record.metadata?.category;
+    if (category && typeof category === "string" && category in mapping) {
+      return mapping[category];
+    }
+    return null;
+  }
+  /**
+   * Enrich records using custom extractor strategy.
+   *
+   * Calls the provided extractor function for each record.
+   *
+   * @param collection - Collection name
+   * @param config - Extractor configuration
+   * @param stats - Statistics object to update
+   */
+  async enrichWithExtractor(collection, config, stats) {
+    const batchSize = config.batchSize || 100;
+    for await (const batch of this.adapter.iterate(collection, {
+      batchSize,
+      filter: config.filter
+    })) {
+      const updates = [];
+      for (const record of batch) {
+        stats.recordsProcessed++;
+        try {
+          const vertical = await config.extractor(record);
+          if (vertical) {
+            updates.push({
+              id: record.id,
+              metadata: { vertical }
+            });
+          } else {
+            stats.recordsSkipped++;
+          }
+        } catch (error) {
+          stats.recordsSkipped++;
+          stats.errors?.push(
+            `Extractor error for record ${record.id}: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+      if (updates.length > 0) {
+        try {
+          await this.adapter.updateMetadata(collection, updates);
+          stats.recordsUpdated += updates.length;
+        } catch (error) {
+          stats.errors?.push(
+            `Error updating batch: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Enrich records using automatic LLM strategy.
+   *
+   * Uses a language model to classify documents into verticals.
+   *
+   * @param collection - Collection name
+   * @param config - Automatic extraction configuration
+   * @param stats - Statistics object to update
+   */
+  async enrichWithLLM(collection, config, stats) {
+    const batchSize = config.batchSize || 10;
+    const { llm, fields, promptTemplate, textField } = config.automatic;
+    const fieldName = textField || "content";
+    for await (const batch of this.adapter.iterate(collection, {
+      batchSize,
+      filter: config.filter
+    })) {
+      const updates = [];
+      for (const record of batch) {
+        stats.recordsProcessed++;
+        try {
+          const vertical = await this.extractWithLLM(
+            record,
+            llm,
+            fields,
+            fieldName,
+            promptTemplate
+          );
+          if (vertical) {
+            updates.push({
+              id: record.id,
+              metadata: { vertical }
+            });
+          } else {
+            stats.recordsSkipped++;
+          }
+        } catch (error) {
+          stats.recordsSkipped++;
+          stats.errors?.push(
+            `LLM extraction error for record ${record.id}: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+      if (updates.length > 0) {
+        try {
+          await this.adapter.updateMetadata(collection, updates);
+          stats.recordsUpdated += updates.length;
+        } catch (error) {
+          stats.errors?.push(
+            `Error updating batch: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Extract vertical classification using LLM.
+   *
+   * @param record - Vector record
+   * @param llm - LLM client
+   * @param fields - Available vertical fields
+   * @param textField - Field name containing text to classify
+   * @param promptTemplate - Optional custom prompt template
+   * @returns Vertical label
+   */
+  async extractWithLLM(record, llm, fields, textField, promptTemplate) {
+    const text = record.metadata?.[textField];
+    if (!text || typeof text !== "string") {
+      throw new Error(`No text found in field '${textField}'`);
+    }
+    const prompt = promptTemplate ? promptTemplate.replace("{fields}", fields.join(", ")).replace("{text}", text) : `Classify the following text into one of these categories: ${fields.join(", ")}
+
+Text: ${text}
+
+Category:`;
+    const result = await llm.generate(prompt);
+    return result.trim();
+  }
+  /**
+   * Enrich records with theme classifications.
+   *
+   * Uses a theme classifier to identify themes in text content and updates
+   * record metadata with theme information. Supports single and multi-theme
+   * classification with configurable confidence thresholds.
+   *
+   * @param collection - Name of the collection to enrich
+   * @param config - Theme enrichment configuration
+   * @returns Statistics about the enrichment operation
+   *
+   * @example
+   * ```typescript
+   * // Single theme classification
+   * await pipeline.enrichThemes('docs', {
+   *   themes: ['technology', 'business', 'science'],
+   *   classifier: new KeywordThemeClassifier(),
+   *   confidenceThreshold: 0.7
+   * });
+   *
+   * // Multi-theme classification
+   * await pipeline.enrichThemes('docs', {
+   *   themes: ['technology', 'business', 'science'],
+   *   classifier: new LLMThemeClassifier(),
+   *   multiTheme: true,
+   *   confidenceThreshold: 0.5
+   * });
+   * ```
+   */
+  async enrichThemes(collection, config) {
+    const startTime = Date.now();
+    const stats = {
+      recordsProcessed: 0,
+      recordsUpdated: 0,
+      recordsSkipped: 0,
+      timeMs: 0,
+      errors: []
+    };
+    try {
+      await this.enrichWithThemeClassifier(collection, config, stats);
+    } catch (error) {
+      stats.errors?.push(
+        `Pipeline error: ${error instanceof Error ? error.message : "unknown error"}`
+      );
+    }
+    stats.timeMs = Date.now() - startTime;
+    return stats;
+  }
+  /**
+   * Enrich records using theme classifier.
+   *
+   * @param collection - Collection name
+   * @param config - Theme enrichment configuration
+   * @param stats - Statistics object to update
+   */
+  async enrichWithThemeClassifier(collection, config, stats) {
+    const batchSize = config.batchSize || 100;
+    const textField = config.textField || "content";
+    const confidenceThreshold = config.confidenceThreshold ?? 0.5;
+    const multiTheme = config.multiTheme || false;
+    for await (const batch of this.adapter.iterate(collection, {
+      batchSize,
+      filter: config.filter
+    })) {
+      const textsToClassify = [];
+      const recordsToProcess = [];
+      for (const record of batch) {
+        stats.recordsProcessed++;
+        const text = record.text || record.metadata?.[textField];
+        if (!text || typeof text !== "string" || text.trim() === "") {
+          stats.recordsSkipped++;
+          continue;
+        }
+        textsToClassify.push(text);
+        recordsToProcess.push(record);
+      }
+      if (textsToClassify.length === 0) {
+        continue;
+      }
+      let classifications;
+      try {
+        classifications = await config.classifier.classifyBatch(textsToClassify);
+      } catch (error) {
+        stats.errors?.push(
+          `Batch classification error, falling back to individual classification: ${error instanceof Error ? error.message : "unknown error"}`
+        );
+        classifications = [];
+        for (let i = 0; i < textsToClassify.length; i++) {
+          try {
+            const result = await config.classifier.classify(textsToClassify[i]);
+            classifications.push(result);
+          } catch (individualError) {
+            classifications.push(null);
+            stats.errors?.push(
+              `Classification error for record ${recordsToProcess[i].id}: ${individualError instanceof Error ? individualError.message : "unknown error"}`
+            );
+          }
+        }
+      }
+      const updates = [];
+      for (let i = 0; i < recordsToProcess.length; i++) {
+        const record = recordsToProcess[i];
+        const classification = classifications[i];
+        try {
+          if (!classification || typeof classification !== "object") {
+            stats.recordsSkipped++;
+            stats.errors?.push(
+              `Invalid classification for record ${record.id}`
+            );
+            continue;
+          }
+          if (classification.confidence < confidenceThreshold) {
+            stats.recordsSkipped++;
+            continue;
+          }
+          const metadata = {
+            __h_theme: classification.theme,
+            __h_theme_confidence: classification.confidence
+          };
+          if (multiTheme && classification.allScores) {
+            const themes = Object.entries(classification.allScores).filter(([_, score]) => score >= confidenceThreshold).sort(([_, a], [__, b]) => b - a).map(([theme, _]) => theme);
+            if (themes.length > 0) {
+              metadata.__h_themes = themes;
+            }
+          }
+          updates.push({
+            id: record.id,
+            metadata
+          });
+        } catch (error) {
+          stats.recordsSkipped++;
+          stats.errors?.push(
+            `Error processing record ${record.id}: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+      if (updates.length > 0) {
+        try {
+          await this.adapter.updateMetadata(collection, updates);
+          stats.recordsUpdated += updates.length;
+        } catch (error) {
+          stats.errors?.push(
+            `Error updating batch: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+      if (config.onProgress) {
+        config.onProgress(stats);
+      }
+    }
+  }
+  /**
+   * Enrich records with section structure.
+   *
+   * Extracts section metadata from documents using either existing field mappings
+   * or automatic detection strategies (markdown, HTML, or pattern-based).
+   *
+   * @param collection - Name of the collection to enrich
+   * @param config - Section enrichment configuration
+   * @returns Statistics about the enrichment operation
+   *
+   * @example
+   * ```typescript
+   * // Use existing section field
+   * await pipeline.enrichSections('docs', {
+   *   existingField: 'section_path'
+   * });
+   *
+   * // Auto-detect sections
+   * await pipeline.enrichSections('docs', {
+   *   autoDetect: true
+   * });
+   * ```
+   */
+  async enrichSections(collection, config) {
+    const startTime = Date.now();
+    const stats = {
+      recordsProcessed: 0,
+      recordsUpdated: 0,
+      recordsSkipped: 0,
+      timeMs: 0,
+      errors: []
+    };
+    try {
+      await this.enrichWithSectionDetection(collection, config, stats);
+    } catch (error) {
+      stats.errors?.push(
+        `Pipeline error: ${error instanceof Error ? error.message : "unknown error"}`
+      );
+    }
+    stats.timeMs = Date.now() - startTime;
+    return stats;
+  }
+  /**
+   * Enrich records with all enrichment types.
+   *
+   * Runs vertical, theme, and section enrichment sequentially with shared
+   * configuration. Global filters and batch sizes apply to all operations.
+   *
+   * @param collection - Name of the collection to enrich
+   * @param config - Combined enrichment configuration
+   * @returns Statistics about the enrichment operation
+   *
+   * @example
+   * ```typescript
+   * await pipeline.enrichAll('docs', {
+   *   vertical: { mapping: { tech: 'technology' } },
+   *   themes: { themes: ['innovation'], classifier },
+   *   sections: { autoDetect: true },
+   *   filter: { field: 'status', op: 'eq', value: 'pending' },
+   *   batchSize: 50
+   * });
+   * ```
+   */
+  async enrichAll(collection, config) {
+    const startTime = Date.now();
+    const aggregateStats = {
+      recordsProcessed: 0,
+      recordsUpdated: 0,
+      recordsSkipped: 0,
+      timeMs: 0,
+      errors: []
+    };
+    try {
+      if (config.vertical) {
+        const verticalConfig = this.applyGlobalConfig(config.vertical, config);
+        const stats = await this.enrichVertical(collection, verticalConfig);
+        this.mergeStats(aggregateStats, stats);
+        if (config.onProgress) {
+          config.onProgress(aggregateStats);
+        }
+      }
+      if (config.themes) {
+        const themesConfig = this.applyGlobalConfig(config.themes, config);
+        const stats = await this.enrichThemes(collection, themesConfig);
+        this.mergeStats(aggregateStats, stats);
+        if (config.onProgress) {
+          config.onProgress(aggregateStats);
+        }
+      }
+      if (config.sections) {
+        const sectionsConfig = this.applyGlobalConfig(config.sections, config);
+        const stats = await this.enrichSections(collection, sectionsConfig);
+        this.mergeStats(aggregateStats, stats);
+        if (config.onProgress) {
+          config.onProgress(aggregateStats);
+        }
+      }
+    } catch (error) {
+      aggregateStats.errors?.push(
+        `Pipeline error: ${error instanceof Error ? error.message : "unknown error"}`
+      );
+    }
+    aggregateStats.timeMs = Date.now() - startTime;
+    return aggregateStats;
+  }
+  /**
+   * Apply global configuration to individual enrichment configs.
+   *
+   * @param individualConfig - Configuration for a specific enrichment type
+   * @param globalConfig - Global configuration
+   * @returns Merged configuration
+   */
+  applyGlobalConfig(individualConfig, globalConfig) {
+    const merged = { ...individualConfig };
+    if (globalConfig.filter && !merged.filter) {
+      merged.filter = globalConfig.filter;
+    }
+    if (globalConfig.batchSize && !merged.batchSize) {
+      merged.batchSize = globalConfig.batchSize;
+    }
+    return merged;
+  }
+  /**
+   * Merge stats from an enrichment operation into aggregate stats.
+   *
+   * @param aggregate - Aggregate stats to update
+   * @param stats - Stats from a single operation
+   */
+  mergeStats(aggregate, stats) {
+    aggregate.recordsProcessed += stats.recordsProcessed;
+    aggregate.recordsUpdated += stats.recordsUpdated;
+    aggregate.recordsSkipped += stats.recordsSkipped;
+    if (stats.errors && stats.errors.length > 0) {
+      if (!aggregate.errors) {
+        aggregate.errors = [];
+      }
+      aggregate.errors.push(...stats.errors);
+    }
+  }
+  /**
+   * Enrich records using section detection.
+   *
+   * @param collection - Collection name
+   * @param config - Section enrichment configuration
+   * @param stats - Statistics object to update
+   */
+  async enrichWithSectionDetection(collection, config, stats) {
+    const batchSize = config.batchSize || 100;
+    for await (const batch of this.adapter.iterate(collection, {
+      batchSize,
+      filter: config.filter
+    })) {
+      const updates = [];
+      for (const record of batch) {
+        stats.recordsProcessed++;
+        try {
+          let sectionMetadata = null;
+          if (config.existingField) {
+            sectionMetadata = this.extractSectionMetadata(
+              record.metadata?.[config.existingField]
+            );
+          } else if (config.autoDetect) {
+            const text = record.text || record.metadata?.content || "";
+            if (typeof text === "string") {
+              sectionMetadata = this.detectSections(text);
+            }
+          }
+          if (sectionMetadata) {
+            const metadata = {
+              __h_section_level: sectionMetadata.level,
+              __h_section_title: sectionMetadata.title
+            };
+            if (sectionMetadata.path) {
+              metadata.__h_section_path = sectionMetadata.path;
+            }
+            updates.push({
+              id: record.id,
+              metadata
+            });
+          } else {
+            stats.recordsSkipped++;
+          }
+        } catch (error) {
+          stats.recordsSkipped++;
+          stats.errors?.push(
+            `Error processing record ${record.id}: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+      if (updates.length > 0) {
+        try {
+          await this.adapter.updateMetadata(collection, updates);
+          stats.recordsUpdated += updates.length;
+        } catch (error) {
+          stats.errors?.push(
+            `Error updating batch: ${error instanceof Error ? error.message : "unknown error"}`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Extract section metadata from an existing field value.
+   *
+   * @param sectionPath - Section path string (e.g., "introduction/overview")
+   * @returns Section metadata or null
+   */
+  extractSectionMetadata(sectionPath) {
+    if (!sectionPath || typeof sectionPath !== "string") {
+      return null;
+    }
+    const parts = sectionPath.split("/").filter((p) => p.trim() !== "");
+    if (parts.length === 0) {
+      return null;
+    }
+    return {
+      path: sectionPath,
+      level: parts.length,
+      title: parts[parts.length - 1]
+    };
+  }
+  /**
+   * Detect sections in text using heuristics.
+   *
+   * @param text - Text content to analyze
+   * @returns Section metadata or null
+   */
+  detectSections(text) {
+    const markdown = this.detectMarkdownSections(text);
+    if (markdown) return markdown;
+    const html = this.detectHtmlSections(text);
+    if (html) return html;
+    const pattern = this.detectPatternSections(text);
+    if (pattern) return pattern;
+    return { level: 0, title: "unsectioned" };
+  }
+  /**
+   * Detect markdown headers (# Header).
+   *
+   * @param text - Text content
+   * @returns Section metadata or null
+   */
+  detectMarkdownSections(text) {
+    const match = text.match(/^(#{1,6})\s+(.+)$/m);
+    if (match) {
+      const level = match[1].length;
+      const title = match[2].trim();
+      return { level, title };
+    }
+    return null;
+  }
+  /**
+   * Detect HTML headers (<h1>Header</h1>).
+   *
+   * @param text - Text content
+   * @returns Section metadata or null
+   */
+  detectHtmlSections(text) {
+    const match = text.match(/<h([1-6])>(.+?)<\/h[1-6]>/i);
+    if (match) {
+      const level = parseInt(match[1], 10);
+      const title = match[2].trim();
+      return { level, title };
+    }
+    return null;
+  }
+  /**
+   * Detect sections using common patterns (SECTION: Title).
+   *
+   * @param text - Text content
+   * @returns Section metadata or null
+   */
+  detectPatternSections(text) {
+    const match = text.match(/^SECTION:\s+(.+)$/m);
+    if (match) {
+      const title = match[1].trim();
+      return { level: 1, title };
+    }
+    return null;
+  }
+};
+
+// src/ingestion/chunkers/text-chunker.ts
+var DEFAULT_CHUNK_SIZE = 500;
+var DEFAULT_CHUNK_OVERLAP = 50;
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function estimateChars(tokens) {
+  return tokens * 4;
+}
+
+// src/ingestion/chunkers/recursive-chunker.ts
+var RecursiveChunker = class {
+  separators = [
+    "\n\n",
+    // Paragraphs (double newline)
+    "\n",
+    // Lines (single newline)
+    ". ",
+    // Sentences (period + space)
+    " ",
+    // Words (space)
+    ""
+    // Characters (last resort)
+  ];
+  chunk(text, config) {
+    if (!text) return [];
+    const chunkSize = config?.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const chunkOverlap = config?.chunkOverlap ?? DEFAULT_CHUNK_OVERLAP;
+    const maxChars = estimateChars(chunkSize);
+    const overlapChars = estimateChars(chunkOverlap);
+    if (text.length <= maxChars) {
+      return [{
+        text,
+        index: 0,
+        metadata: {
+          source: "",
+          chunkIndex: 0,
+          totalChunks: 1,
+          startChar: 0,
+          endChar: text.length
+        }
+      }];
+    }
+    const splits = this.recursiveSplit(text, maxChars, 0);
+    const chunks = this.addOverlap(splits, overlapChars);
+    return chunks.map((chunk, index) => ({
+      text: chunk.text,
+      index,
+      metadata: {
+        source: "",
+        // Will be set by pipeline
+        chunkIndex: index,
+        totalChunks: chunks.length,
+        startChar: chunk.start,
+        endChar: chunk.end
+      }
+    }));
+  }
+  recursiveSplit(text, maxChars, separatorIndex) {
+    if (text.length <= maxChars) {
+      return [{ text, start: 0, end: text.length }];
+    }
+    if (separatorIndex >= this.separators.length) {
+      const result2 = [];
+      for (let i = 0; i < text.length; i += maxChars) {
+        result2.push({
+          text: text.slice(i, i + maxChars),
+          start: i,
+          end: Math.min(i + maxChars, text.length)
+        });
+      }
+      return result2;
+    }
+    const separator = this.separators[separatorIndex];
+    const parts = separator ? text.split(separator) : [text];
+    if (parts.length <= 1) {
+      return this.recursiveSplit(text, maxChars, separatorIndex + 1);
+    }
+    const result = [];
+    let currentParts = [];
+    let currentStart = 0;
+    let runningOffset = 0;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const combined = currentParts.length > 0 ? [...currentParts, part].join(separator) : part;
+      if (combined.length <= maxChars) {
+        if (currentParts.length === 0) {
+          currentStart = runningOffset;
+        }
+        currentParts.push(part);
+      } else {
+        if (currentParts.length > 0) {
+          const chunkText = currentParts.join(separator);
+          result.push({
+            text: chunkText,
+            start: currentStart,
+            end: currentStart + chunkText.length
+          });
+        }
+        currentStart = runningOffset;
+        if (part.length > maxChars) {
+          const subSplits = this.recursiveSplit(part, maxChars, separatorIndex + 1);
+          for (const sub of subSplits) {
+            result.push({
+              text: sub.text,
+              start: currentStart + sub.start,
+              end: currentStart + sub.end
+            });
+          }
+          currentParts = [];
+        } else {
+          currentParts = [part];
+        }
+      }
+      runningOffset += part.length + (i < parts.length - 1 ? separator.length : 0);
+    }
+    if (currentParts.length > 0) {
+      const chunkText = currentParts.join(separator);
+      result.push({
+        text: chunkText,
+        start: currentStart,
+        end: currentStart + chunkText.length
+      });
+    }
+    return result;
+  }
+  addOverlap(chunks, overlapChars) {
+    if (overlapChars === 0 || chunks.length <= 1) {
+      return chunks;
+    }
+    const result = [chunks[0]];
+    for (let i = 1; i < chunks.length; i++) {
+      const prevChunk = chunks[i - 1];
+      const currChunk = chunks[i];
+      const overlapText = prevChunk.text.slice(-overlapChars);
+      result.push({
+        text: overlapText + currChunk.text,
+        start: Math.max(0, prevChunk.end - overlapChars),
+        end: currChunk.end
+      });
+    }
+    return result;
+  }
+};
+
+// src/ingestion/ingestion-pipeline.ts
+var path = __toESM(require("path"));
+var IngestionPipeline = class {
+  constructor(adapter, embedder, loaderRegistry, chunker) {
+    this.adapter = adapter;
+    this.embedder = embedder;
+    this.loaderRegistry = loaderRegistry;
+    this.defaultChunker = chunker || new RecursiveChunker();
+  }
+  defaultChunker;
+  /**
+   * Ingest documents into a vector database collection.
+   * @param sources - File paths
+   * @param collection - Target collection name
+   * @param config - Optional ingestion configuration
+   * @returns Statistics about the ingestion operation
+   */
+  async ingest(sources, collection, config) {
+    const startTime = Date.now();
+    const sourceArray = Array.isArray(sources) ? sources : [sources];
+    const stats = {
+      documentsProcessed: 0,
+      documentsSucceeded: 0,
+      documentsFailed: 0,
+      chunksCreated: 0,
+      chunksUpserted: 0,
+      timeMs: 0,
+      errors: []
+    };
+    const totalDocuments = sourceArray.length;
+    for (const source of sourceArray) {
+      config?.onProgress?.({
+        stage: "loading",
+        documentsProcessed: stats.documentsProcessed,
+        totalDocuments,
+        chunksProcessed: stats.chunksUpserted,
+        currentDocument: source
+      });
+      try {
+        await this.ingestFile(source, collection, config, stats, totalDocuments);
+        stats.documentsSucceeded++;
+      } catch (error) {
+        stats.documentsFailed++;
+        stats.errors.push({
+          source,
+          stage: "load",
+          error
+        });
+      }
+      stats.documentsProcessed++;
+    }
+    stats.timeMs = Date.now() - startTime;
+    return stats;
+  }
+  async ingestFile(filePath, collection, config, stats, totalDocuments) {
+    const doc = await this.loaderRegistry.load(filePath);
+    config?.onDocumentLoaded?.(doc);
+    config?.onProgress?.({
+      stage: "chunking",
+      documentsProcessed: stats.documentsProcessed,
+      totalDocuments,
+      chunksProcessed: stats.chunksUpserted,
+      currentDocument: filePath
+    });
+    const chunker = config?.chunker || this.defaultChunker;
+    const chunks = chunker.chunk(doc.text, {
+      chunkSize: config?.chunkSize,
+      chunkOverlap: config?.chunkOverlap
+    });
+    for (const chunk of chunks) {
+      chunk.metadata.source = doc.source;
+    }
+    stats.chunksCreated += chunks.length;
+    config?.onChunksCreated?.(chunks);
+    config?.onProgress?.({
+      stage: "embedding",
+      documentsProcessed: stats.documentsProcessed,
+      totalDocuments,
+      chunksProcessed: stats.chunksUpserted,
+      totalChunks: stats.chunksCreated,
+      currentDocument: filePath
+    });
+    const texts = chunks.map((c) => c.text);
+    const embeddings = await this.embedder.embedBatch(texts);
+    const records = chunks.map((chunk, i) => {
+      const metadata = this.buildMetadata(doc, chunk, config);
+      return {
+        id: `${path.basename(doc.source)}:${chunk.index}`,
+        embedding: embeddings[i],
+        text: chunk.text,
+        metadata
+      };
+    });
+    config?.onProgress?.({
+      stage: "upserting",
+      documentsProcessed: stats.documentsProcessed,
+      totalDocuments,
+      chunksProcessed: stats.chunksUpserted,
+      totalChunks: stats.chunksCreated,
+      currentDocument: filePath
+    });
+    const batchSize = config?.batchSize || 100;
+    for (let i = 0; i < records.length; i += batchSize) {
+      const batch = records.slice(i, i + batchSize);
+      await this.adapter.upsert(collection, batch);
+      stats.chunksUpserted += batch.length;
+    }
+  }
+  buildMetadata(doc, chunk, config) {
+    const basename2 = path.basename(doc.source, path.extname(doc.source));
+    const dirname2 = path.dirname(doc.source);
+    const autoMetadata = {
+      [VerticalFields.SOURCE]: doc.source,
+      [VerticalFields.DOC_TYPE]: doc.type,
+      [VerticalFields.DOC_ID]: basename2,
+      [VerticalFields.PARTITION]: dirname2
+    };
+    const extractedMetadata = config?.metadataExtractor?.(doc) || {};
+    const userMetadata = config?.metadata || {};
+    const chunkMetadata = {
+      chunkIndex: chunk.metadata.chunkIndex,
+      totalChunks: chunk.metadata.totalChunks,
+      startChar: chunk.metadata.startChar,
+      endChar: chunk.metadata.endChar
+    };
+    return {
+      ...autoMetadata,
+      ...extractedMetadata,
+      ...userMetadata,
+      ...chunkMetadata
+    };
+  }
+};
+
+// src/ingestion/loaders/text-loader.ts
+var fs = __toESM(require("fs/promises"));
+var path2 = __toESM(require("path"));
+var TextLoader = class {
+  canHandle(filePath) {
+    return /\.(txt|md)$/i.test(filePath);
+  }
+  async load(filePath) {
+    const text = await fs.readFile(filePath, "utf-8");
+    const type = path2.extname(filePath).slice(1).toLowerCase();
+    const stats = await fs.stat(filePath);
+    const extension = path2.extname(filePath);
+    return {
+      text,
+      source: filePath,
+      type,
+      metadata: {
+        size: stats.size,
+        extension
+      }
+    };
+  }
+};
+
+// src/ingestion/loaders/pdf-loader.ts
+var fs2 = __toESM(require("fs/promises"));
+var import_pdf_parse = __toESM(require("pdf-parse"));
+var PDFLoader = class {
+  canHandle(filePath) {
+    return /\.pdf$/i.test(filePath);
+  }
+  async load(filePath) {
+    const dataBuffer = await fs2.readFile(filePath);
+    const pdfData = await (0, import_pdf_parse.default)(dataBuffer);
+    return {
+      text: pdfData.text,
+      source: filePath,
+      type: "pdf",
+      metadata: {
+        pages: pdfData.numpages,
+        info: pdfData.info
+      }
+    };
+  }
+};
+
+// src/ingestion/loaders/docx-loader.ts
+var import_mammoth = __toESM(require("mammoth"));
+var DOCXLoader = class {
+  canHandle(filePath) {
+    return /\.docx$/i.test(filePath);
+  }
+  async load(filePath) {
+    const result = await import_mammoth.default.extractRawText({ path: filePath });
+    return {
+      text: result.value,
+      source: filePath,
+      type: "docx",
+      metadata: {
+        warnings: result.messages
+        // Conversion warnings from mammoth
+      }
+    };
+  }
+};
+
+// src/ingestion/loaders/html-loader.ts
+var fs3 = __toESM(require("fs/promises"));
+var cheerio = __toESM(require("cheerio"));
+var HTMLLoader = class {
+  canHandle(filePath) {
+    return /\.html?$/i.test(filePath);
+  }
+  async load(filePath) {
+    const html = await fs3.readFile(filePath, "utf-8");
+    const $ = cheerio.load(html);
+    $("script, style, nav, footer").remove();
+    const text = $("body").text().replace(/\s+/g, " ").trim();
+    return {
+      text,
+      source: filePath,
+      type: "html",
+      metadata: {
+        title: $("title").text() || void 0,
+        description: $('meta[name="description"]').attr("content") || void 0
+      }
+    };
+  }
+};
+
+// src/ingestion/loaders/loader-registry.ts
+var LoaderRegistry = class {
+  loaders = [];
+  constructor() {
+    this.register(new TextLoader());
+    this.register(new PDFLoader());
+    this.register(new DOCXLoader());
+    this.register(new HTMLLoader());
+  }
+  /**
+   * Register a custom document loader.
+   * @param loader - Loader to register
+   */
+  register(loader) {
+    this.loaders.push(loader);
+  }
+  /**
+   * Check if any loader can handle this file.
+   * @param filePath - Path to check
+   * @returns true if a loader exists for this file type
+   */
+  canLoad(filePath) {
+    return this.loaders.some((l) => l.canHandle(filePath));
+  }
+  /**
+   * Load a document using the appropriate loader.
+   * @param filePath - Path to the file to load
+   * @returns Promise resolving to Document
+   * @throws Error if no loader found for file type
+   */
+  async load(filePath) {
+    const loader = this.loaders.find((l) => l.canHandle(filePath));
+    if (!loader) {
+      throw new Error(`No loader found for file: ${filePath}`);
+    }
+    return loader.load(filePath);
+  }
+};
+
+// src/ingestion/chunkers/fixed-chunker.ts
+var FixedChunker = class {
+  chunk(text, config) {
+    if (!text) return [];
+    const chunkSize = config?.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const chunkOverlap = config?.chunkOverlap ?? DEFAULT_CHUNK_OVERLAP;
+    const maxChars = estimateChars(chunkSize);
+    const overlapChars = estimateChars(chunkOverlap);
+    const step = maxChars - overlapChars;
+    if (text.length <= maxChars) {
+      return [{
+        text,
+        index: 0,
+        metadata: {
+          source: "",
+          chunkIndex: 0,
+          totalChunks: 1,
+          startChar: 0,
+          endChar: text.length
+        }
+      }];
+    }
+    const chunks = [];
+    let position = 0;
+    while (position < text.length) {
+      const end = Math.min(text.length, position + maxChars);
+      const chunkText = text.slice(position, end);
+      chunks.push({
+        text: chunkText,
+        index: chunks.length,
+        metadata: {
+          source: "",
+          chunkIndex: chunks.length,
+          totalChunks: 0,
+          // Updated after loop
+          startChar: position,
+          endChar: end
+        }
+      });
+      position += step;
+      if (step <= 0) break;
+    }
+    for (const chunk of chunks) {
+      chunk.metadata.totalChunks = chunks.length;
+    }
+    return chunks;
+  }
+};
+
+// src/ingestion/chunkers/sentence-chunker.ts
+var SentenceChunker = class {
+  chunk(text, config) {
+    if (!text) return [];
+    const chunkSize = config?.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const chunkOverlap = config?.chunkOverlap ?? DEFAULT_CHUNK_OVERLAP;
+    const maxChars = estimateChars(chunkSize);
+    const overlapChars = estimateChars(chunkOverlap);
+    const sentences = this.splitSentences(text);
+    if (sentences.length === 0) {
+      return [{
+        text,
+        index: 0,
+        metadata: {
+          source: "",
+          chunkIndex: 0,
+          totalChunks: 1,
+          startChar: 0,
+          endChar: text.length
+        }
+      }];
+    }
+    const rawChunks = [];
+    let currentSentences = [];
+    let currentStart = 0;
+    for (const sentence of sentences) {
+      const combined = currentSentences.length > 0 ? [...currentSentences, sentence].join(" ") : sentence;
+      if (currentSentences.length === 0) {
+        currentSentences = [sentence];
+        currentStart = text.indexOf(sentence);
+      } else if (combined.length <= maxChars) {
+        currentSentences.push(sentence);
+      } else {
+        const chunkText = currentSentences.join(" ");
+        rawChunks.push({
+          text: chunkText,
+          start: currentStart,
+          end: currentStart + chunkText.length
+        });
+        currentSentences = [sentence];
+        currentStart = text.indexOf(sentence, currentStart + 1);
+        if (currentStart === -1) currentStart = 0;
+      }
+    }
+    if (currentSentences.length > 0) {
+      const chunkText = currentSentences.join(" ");
+      rawChunks.push({
+        text: chunkText,
+        start: currentStart,
+        end: currentStart + chunkText.length
+      });
+    }
+    const withOverlap = this.addSentenceOverlap(rawChunks, overlapChars);
+    return withOverlap.map((chunk, index) => ({
+      text: chunk.text,
+      index,
+      metadata: {
+        source: "",
+        chunkIndex: index,
+        totalChunks: withOverlap.length,
+        startChar: chunk.start,
+        endChar: chunk.end
+      }
+    }));
+  }
+  splitSentences(text) {
+    const parts = text.match(/[^.!?]*[.!?]+(?:\s|$)|[^.!?]+$/g);
+    if (!parts) return [text];
+    return parts.map((s) => s.trim()).filter((s) => s.length > 0);
+  }
+  addSentenceOverlap(chunks, overlapChars) {
+    if (overlapChars === 0 || chunks.length <= 1) {
+      return chunks;
+    }
+    const result = [chunks[0]];
+    for (let i = 1; i < chunks.length; i++) {
+      const prevChunk = chunks[i - 1];
+      const currChunk = chunks[i];
+      const prevSentences = this.splitSentences(prevChunk.text);
+      const lastSentence = prevSentences[prevSentences.length - 1] || "";
+      if (lastSentence && lastSentence.length <= overlapChars) {
+        result.push({
+          text: lastSentence + " " + currChunk.text,
+          start: Math.max(0, prevChunk.end - lastSentence.length),
+          end: currChunk.end
+        });
+      } else {
+        result.push(currChunk);
+      }
+    }
+    return result;
+  }
+};
+
+// src/client/rag-client.ts
+var DEFAULT_TOP_K = 10;
+var DEFAULT_RAG_SYSTEM_PROMPT = "You are a helpful assistant. Answer the question based on the provided context. If the context doesn't contain enough information, say so.";
+var RAGClient = class {
+  adapter;
+  embedder;
+  llm;
+  defaultCollection;
+  defaultTopK;
+  queryComposer;
+  ingestionPipeline;
+  enrichmentPipeline;
+  constructor(config) {
+    this.adapter = config.adapter;
+    this.embedder = config.embedder;
+    this.llm = config.llm;
+    this.defaultCollection = config.defaultCollection;
+    this.defaultTopK = config.defaultTopK ?? DEFAULT_TOP_K;
+    this.queryComposer = new RAGQueryComposer(this.adapter, this.embedder);
+    this.ingestionPipeline = new IngestionPipeline(
+      this.adapter,
+      this.embedder,
+      new LoaderRegistry()
+    );
+    this.enrichmentPipeline = new EnrichmentPipeline(this.adapter);
+  }
+  // ==========================================================================
+  // COLLECTION MANAGEMENT
+  // ==========================================================================
+  /**
+   * Create a new vector collection.
+   * Dimension defaults to embedder.dimensions if not specified.
+   */
+  async createCollection(name, dimension, metric) {
+    const dim = dimension ?? this.embedder.dimensions;
+    await this.adapter.createCollection(name, dim, metric);
+  }
+  /**
+   * Delete a collection.
+   */
+  async deleteCollection(name) {
+    await this.adapter.deleteCollection(name);
+  }
+  /**
+   * Check if a collection exists.
+   */
+  async collectionExists(name) {
+    return this.adapter.collectionExists(name);
+  }
+  // ==========================================================================
+  // INGESTION
+  // ==========================================================================
+  /**
+   * Ingest documents into a collection.
+   * Collection defaults to defaultCollection if not specified.
+   */
+  async ingest(sources, collection, config) {
+    const col = collection ?? this.defaultCollection;
+    if (!col) {
+      throw new Error(
+        "No collection specified. Pass a collection name or set defaultCollection in config."
+      );
+    }
+    return this.ingestionPipeline.ingest(sources, col, config);
+  }
+  // ==========================================================================
+  // RETRIEVAL
+  // ==========================================================================
+  /**
+   * Retrieve relevant chunks for a query.
+   * Supports filter shorthands (partition, theme) and groupBy.
+   */
+  async retrieve(query, options) {
+    const collection = options?.collection ?? this.defaultCollection;
+    if (!collection) {
+      throw new Error(
+        "No collection specified. Pass a collection name or set defaultCollection in config."
+      );
+    }
+    const topK = options?.topK ?? this.defaultTopK;
+    let verticalFilters;
+    let horizontalFilters;
+    const customFilters = options?.filter;
+    if (options?.partition) {
+      verticalFilters = {
+        field: VerticalFields.PARTITION,
+        op: "eq",
+        value: options.partition
+      };
+    }
+    if (options?.theme) {
+      horizontalFilters = {
+        field: HorizontalFields.THEME,
+        op: "eq",
+        value: options.theme
+      };
+    }
+    const params = {
+      query,
+      collection,
+      topK,
+      verticalFilters,
+      horizontalFilters,
+      customFilters
+    };
+    if (options?.groupBy === "document") {
+      const grouped = await this.queryComposer.retrieveVertical(params);
+      const records = Array.from(grouped.values()).flat();
+      return { records, query, filtersApplied: { vertical: verticalFilters, horizontal: horizontalFilters, custom: customFilters } };
+    }
+    if (options?.groupBy === "theme") {
+      const grouped = await this.queryComposer.retrieveHorizontal(params);
+      const records = Array.from(grouped.values()).flat();
+      return { records, query, filtersApplied: { vertical: verticalFilters, horizontal: horizontalFilters, custom: customFilters } };
+    }
+    return this.queryComposer.retrieve(params);
+  }
+  // ==========================================================================
+  // ENRICHMENT
+  // ==========================================================================
+  /**
+   * Enrich a collection with vertical, theme, and/or section metadata.
+   */
+  async enrich(collection, config) {
+    return this.enrichmentPipeline.enrichAll(collection, config);
+  }
+  // ==========================================================================
+  // FULL RAG QUERY
+  // ==========================================================================
+  /**
+   * Full RAG: retrieve relevant context and generate an answer using LLM.
+   * Requires an LLM client to be provided in the constructor config.
+   */
+  async query(question, options) {
+    if (!this.llm) {
+      throw new Error(
+        "RAGClient.query() requires an LLM client. Pass one in the constructor config."
+      );
+    }
+    const retrievalResult = await this.retrieve(question, options);
+    const context = retrievalResult.records.map((r) => r.text).filter(Boolean).join("\n\n");
+    const systemPrompt = options?.systemPrompt ?? DEFAULT_RAG_SYSTEM_PROMPT;
+    const prompt = `${systemPrompt}
+
+Context:
+${context}
+
+Question: ${question}`;
+    const answer = await this.llm.generate(prompt, {
+      temperature: options?.temperature,
+      maxTokens: options?.maxTokens
+    });
+    return {
+      answer,
+      sources: retrievalResult.records,
+      query: question,
+      retrievalResult
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_CHUNK_OVERLAP,
+  DEFAULT_CHUNK_SIZE,
+  DOCXLoader,
+  Embedder,
+  EmbeddingThemeClassifier,
+  EnrichmentPipeline,
+  FilterBuilder,
+  FilterTranslator,
+  FixedChunker,
+  HTMLLoader,
+  HorizontalFields,
+  IngestionPipeline,
+  KeywordThemeClassifier,
+  LLMClient,
+  LLMThemeClassifier,
+  LoaderRegistry,
+  METADATA_PREFIXES,
+  MetadataBuilder,
+  MockLLM,
+  PDFLoader,
+  RAGClient,
+  RAGQueryComposer,
+  RecursiveChunker,
+  SentenceChunker,
+  StructuralFields,
+  TextLoader,
+  VectorDBAdapter,
+  VerticalFields,
+  ZeroShotThemeClassifier,
+  estimateChars,
+  estimateTokens
+});
+//# sourceMappingURL=index.js.map