@vectororm/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2493 @@
+/**
+ * Represents a vector record in the database.
+ *
+ * This is the fundamental unit of storage in Glyph, containing:
+ * - Unique identifier
+ * - Embedding vector
+ * - Metadata (including V/H/S fields)
+ * - Optional text and score
+ */
+interface VectorRecord {
+    /** Unique identifier for this record */
+    id: string;
+    /** Embedding vector (dimensionality depends on embedding model) */
+    embedding: number[];
+    /**
+     * Metadata fields including:
+     * - Vertical fields (__v_*): Document-level metadata
+     * - Horizontal fields (__h_*): Theme/section metadata
+     * - Structural fields (__s_*): Position/hierarchy metadata
+     * - Custom user fields
+     */
+    metadata: Record<string, any>;
+    /** Optional text content of this chunk */
+    text?: string;
+    /** Optional similarity score (populated during search) */
+    score?: number;
+}
+
+/**
+ * Result from a vector search operation.
+ */
+interface SearchResult {
+    /** Matching vector records */
+    records: VectorRecord[];
+    /** Total count of matches (if available from DB) */
+    totalCount?: number;
+    /** Cursor for pagination (if supported by DB) */
+    nextCursor?: string;
+}
+
+/**
+ * Metadata field prefixes for the three axes of Glyph's schema.
+ *
+ * These prefixes separate framework fields from user-defined metadata:
+ * - __v_: Vertical axis (document identity)
+ * - __h_: Horizontal axis (content/theme identity)
+ * - __s_: Structural axis (position/hierarchy)
+ */
+declare const METADATA_PREFIXES: {
+    readonly VERTICAL: "__v_";
+    readonly HORIZONTAL: "__h_";
+    readonly STRUCTURAL: "__s_";
+};
+/**
+ * Vertical axis fields - identify WHICH document a chunk belongs to.
+ */
+declare const VerticalFields: {
+    /** Unique document identifier */
+    readonly DOC_ID: "__v_doc_id";
+    /** Original source path/URL */
+    readonly SOURCE: "__v_source";
+    /** Logical partition key (for filtering by document subsets) */
+    readonly PARTITION: "__v_partition";
+    /** Document type classification */
+    readonly DOC_TYPE: "__v_doc_type";
+    /** Arbitrary vertical tags */
+    readonly TAGS: "__v_tags";
+};
+/**
+ * Horizontal axis fields - identify WHAT topic/theme a chunk covers.
+ */
+declare const HorizontalFields: {
+    /** Primary theme classification */
+    readonly THEME: "__h_theme";
+    /** Multiple themes (if applicable) */
+    readonly THEMES: "__h_themes";
+    /** Classification confidence score */
+    readonly THEME_CONFIDENCE: "__h_theme_confidence";
+    /** Hierarchical section path (e.g., "Chapter 3/Pricing/Rates") */
+    readonly SECTION_PATH: "__h_section_path";
+    /** Depth level in hierarchy (0 = root) */
+    readonly SECTION_LEVEL: "__h_section_level";
+    /** Section header text */
+    readonly SECTION_TITLE: "__h_section_title";
+};
+/**
+ * Structural axis fields - track chunk position and relationships.
+ */
+declare const StructuralFields: {
+    /** Position in document (0-indexed) */
+    readonly CHUNK_INDEX: "__s_chunk_index";
+    /** Parent chunk ID (for hierarchical chunking) */
+    readonly PARENT_ID: "__s_parent_id";
+    /** Whether this chunk has children */
+    readonly HAS_CHILDREN: "__s_has_children";
+    /** Total chunks in this document */
+    readonly TOTAL_CHUNKS: "__s_total_chunks";
+};
+
+/**
+ * Type-safe metadata field names.
+ *
+ * Use these instead of string literals to get autocomplete and catch typos.
+ */
+/** Type for vertical field keys */
+type VerticalFieldKey = 'docId' | 'source' | 'partition' | 'docType' | 'tags';
+/** Type for horizontal field keys */
+type HorizontalFieldKey = 'theme' | 'themes' | 'themeConfidence' | 'sectionPath' | 'sectionLevel' | 'sectionTitle';
+/** Type for structural field keys */
+type StructuralFieldKey = 'chunkIndex' | 'parentId' | 'hasChildren' | 'totalChunks';
+
+/**
+ * MetadataBuilder provides a fluent API for constructing metadata objects
+ * with proper V/H/S prefixes and type safety.
+ *
+ * Example:
+ * ```typescript
+ * const metadata = new MetadataBuilder()
+ *   .vertical({ doc_id: 'doc123', source: 'file.pdf' })
+ *   .horizontal({ theme: 'pricing' })
+ *   .structural({ chunk_index: 0, total_chunks: 10 })
+ *   .custom({ author: 'John Doe' })
+ *   .build();
+ * ```
+ *
+ * Features:
+ * - Fluent chaining API
+ * - Automatic prefix application
+ * - Skips undefined values
+ * - Returns immutable copy on build()
+ */
+declare class MetadataBuilder {
+    private 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: Record<string, any>): 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: Record<string, any>): 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: Record<string, any>): 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: Record<string, any>): this;
+    /**
+     * Build and return the complete metadata object.
+     * Returns a copy to prevent external modification.
+     *
+     * @returns Immutable copy of the metadata object
+     */
+    build(): Record<string, any>;
+}
+
+/**
+ * Universal filter language for database-agnostic queries.
+ *
+ * Filters are expressed in a standard format, then translated
+ * to native database syntax by each adapter.
+ */
+/**
+ * Supported filter operators.
+ */
+type FilterOperator = 'eq' | 'neq' | 'in' | 'nin' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'exists';
+/**
+ * Basic filter condition.
+ */
+interface FilterCondition {
+    field: string;
+    op: FilterOperator;
+    value: any;
+}
+/**
+ * Compound AND filter (all conditions must match).
+ */
+interface AndFilter {
+    and: UniversalFilter[];
+}
+/**
+ * Compound OR filter (any condition must match).
+ */
+interface OrFilter {
+    or: UniversalFilter[];
+}
+/**
+ * Universal filter - can be a simple condition or compound.
+ */
+type UniversalFilter = FilterCondition | AndFilter | OrFilter;
+/**
+ * Shorthand filter format (user-friendly).
+ *
+ * Examples:
+ * - {region: "ny"} → {field: "region", op: "eq", value: "ny"}
+ * - {year__gte: 2023} → {field: "year", op: "gte", value: 2023}
+ * - {region: "ny", year__gte: 2023} → {and: [...]}
+ */
+type ShorthandFilter = Record<string, any>;
+
+/**
+ * Translates filters between formats and validates structure.
+ */
+declare class FilterTranslator {
+    /**
+     * 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: ShorthandFilter | UniversalFilter): UniversalFilter;
+    /**
+     * Validate filter structure and operators.
+     *
+     * Throws error if filter is invalid.
+     */
+    static validate(filter: UniversalFilter): void;
+    /**
+     * Check if filter is compound (AND/OR).
+     */
+    static isCompound(filter: UniversalFilter): boolean;
+    /**
+     * Check if input is already in standard format.
+     */
+    private static isStandardFormat;
+    /**
+     * Convert shorthand format to standard.
+     */
+    private static fromShorthand;
+}
+
+/**
+ * Types for vector database adapters.
+ *
+ * These types define the common interface elements that all
+ * adapters must support or return.
+ */
+/**
+ * Statistics about a vector collection.
+ */
+interface CollectionStats {
+    /** Total number of vectors in the collection */
+    vectorCount: number;
+    /** Dimension of vectors in this collection */
+    dimension: number;
+    /** Distance metric used (cosine, euclidean, etc.) */
+    metric: DistanceMetric;
+    /** Additional DB-specific stats (optional) */
+    [key: string]: any;
+}
+/**
+ * Metadata update operation.
+ *
+ * Used for efficient metadata enrichment without re-uploading vectors.
+ */
+interface MetadataUpdate {
+    /** ID of the record to update */
+    id: string;
+    /** Metadata fields to set/update */
+    metadata: Record<string, any>;
+}
+/**
+ * Distance metric for vector similarity.
+ */
+type DistanceMetric = 'cosine' | 'euclidean' | 'dotProduct';
+
+/**
+ * Abstract base class for all vector database adapters.
+ *
+ * This is the KEY abstraction that enables database-agnostic operations.
+ * Each database (Pinecone, Chroma, Qdrant, etc.) implements this interface,
+ * allowing the SDK to work with any vector database.
+ *
+ * Design principles:
+ * 1. All methods are abstract (must be implemented by subclasses)
+ * 2. Capability flags have default implementations (can be overridden)
+ * 3. Universal filter translation is adapter-specific
+ * 4. Async iteration enables efficient enrichment pipelines
+ *
+ * @abstract
+ */
+declare abstract class VectorDBAdapter {
+    /**
+     * Connect to the vector database.
+     *
+     * Initialize client, authenticate, verify connection.
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Disconnect from the vector database.
+     *
+     * Clean up resources, close connections.
+     */
+    abstract disconnect(): Promise<void>;
+    /**
+     * Check if currently connected to the database.
+     */
+    abstract isConnected(): Promise<boolean>;
+    /**
+     * Create a new vector collection.
+     *
+     * @param name - Collection name
+     * @param dimension - Vector dimension
+     * @param metric - Distance metric (default: cosine)
+     */
+    abstract createCollection(name: string, dimension: number, metric?: DistanceMetric): Promise<void>;
+    /**
+     * Delete a collection and all its vectors.
+     *
+     * @param name - Collection name
+     */
+    abstract deleteCollection(name: string): Promise<void>;
+    /**
+     * Check if a collection exists.
+     *
+     * @param name - Collection name
+     */
+    abstract collectionExists(name: string): Promise<boolean>;
+    /**
+     * Get statistics about a collection.
+     *
+     * @param name - Collection name
+     */
+    abstract getCollectionStats(name: string): Promise<CollectionStats>;
+    /**
+     * Upsert (insert or update) vector records.
+     *
+     * This is the primary method for adding vectors to the database.
+     * If a record with the same ID exists, it is updated.
+     *
+     * @param collection - Collection name
+     * @param records - Vector records to upsert
+     */
+    abstract upsert(collection: string, records: VectorRecord[]): Promise<void>;
+    /**
+     * Fetch vector records by ID.
+     *
+     * @param collection - Collection name
+     * @param ids - Record IDs to fetch
+     * @returns Array of matching records (may be empty)
+     */
+    abstract fetch(collection: string, ids: string[]): Promise<VectorRecord[]>;
+    /**
+     * Delete vector records by ID.
+     *
+     * @param collection - Collection name
+     * @param ids - Record IDs to delete
+     */
+    abstract delete(collection: string, ids: string[]): Promise<void>;
+    /**
+     * Update metadata for existing records without re-uploading vectors.
+     *
+     * This is CRITICAL for enrichment pipelines where we need to:
+     * 1. Insert initial vectors with basic metadata
+     * 2. Later enrich with vertical/horizontal metadata
+     * 3. Avoid re-uploading large embedding vectors
+     *
+     * @param collection - Collection name
+     * @param updates - Metadata updates to apply
+     */
+    abstract updateMetadata(collection: string, updates: MetadataUpdate[]): Promise<void>;
+    /**
+     * Search for similar vectors.
+     *
+     * @param collection - Collection name
+     * @param queryVector - Query vector to search with
+     * @param options - Search options
+     * @returns Search results
+     */
+    abstract search(collection: string, queryVector: number[], options?: {
+        topK?: number;
+        filter?: UniversalFilter;
+        includeMetadata?: boolean;
+        includeValues?: boolean;
+    }): Promise<SearchResult>;
+    /**
+     * Translate universal filter to database-specific filter format.
+     *
+     * This is the KEY method that enables database-agnostic filtering.
+     * Each adapter translates the universal filter to its native format:
+     *
+     * - Pinecone: {field: {$eq: value}}
+     * - Qdrant: {must: [{key: field, match: {value}}]}
+     * - Chroma: {field: value}
+     *
+     * @param filter - Universal filter
+     * @returns Database-specific filter object
+     */
+    abstract translateFilter(filter: UniversalFilter): any;
+    /**
+     * Iterate over all vectors in a collection in batches.
+     *
+     * This enables efficient enrichment pipelines:
+     * 1. Fetch vectors in batches
+     * 2. Enrich each batch with metadata
+     * 3. Update metadata back to DB
+     *
+     * @param collection - Collection name
+     * @param options - Iteration options
+     * @yields Batches of vector records
+     */
+    abstract iterate(collection: string, options?: {
+        batchSize?: number;
+        filter?: UniversalFilter;
+    }): AsyncIterableIterator<VectorRecord[]>;
+    /**
+     * 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(): boolean;
+    /**
+     * Whether this adapter supports filtering during search.
+     *
+     * Default: false (no filtering support)
+     * Override to return true if your DB supports metadata filtering.
+     */
+    supportsFiltering(): boolean;
+    /**
+     * Whether this adapter supports batch operations efficiently.
+     *
+     * Default: false (single operations only)
+     * Override to return true if your DB supports batch upsert/delete.
+     */
+    supportsBatchOperations(): boolean;
+}
+
+/**
+ * Query Composition Layer - Retrieval Types and Interfaces
+ *
+ * Defines the core interfaces for retrieval operations in Glyph.
+ * These types abstract query parameters and results across different
+ * vector database adapters.
+ */
+
+/**
+ * Parameters for a retrieval operation.
+ *
+ * Combines query text, collection targeting, and optional filters
+ * for both vertical (document-level) and horizontal (theme-level) filtering.
+ */
+interface RetrievalParams {
+    /** The search query text to embed and search for */
+    query: string;
+    /** Target collection to search in */
+    collection: string;
+    /** Number of results to return */
+    topK: number;
+    /** Optional document-level filters (e.g., filter by doc_id, region, year) */
+    verticalFilters?: UniversalFilter;
+    /** Optional theme/section-level filters (e.g., filter by theme, section) */
+    horizontalFilters?: UniversalFilter;
+    /** Optional additional user-defined filters */
+    customFilters?: UniversalFilter;
+    /** Whether to include embedding vectors in results (default: false) */
+    includeEmbeddings?: boolean;
+}
+/**
+ * Result of a retrieval operation.
+ *
+ * Contains the retrieved records, original query, and information
+ * about which filters were applied.
+ */
+interface RetrievalResult {
+    /** The retrieved vector records */
+    records: VectorRecord[];
+    /** The original query text */
+    query: string;
+    /** Information about which filters were applied */
+    filtersApplied: {
+        vertical?: UniversalFilter;
+        horizontal?: UniversalFilter;
+        custom?: UniversalFilter;
+    };
+}
+/**
+ * Options for a search operation at the adapter level.
+ *
+ * These are lower-level options used by adapters to perform
+ * the actual vector search.
+ */
+interface SearchOptions {
+    /** Number of results to return */
+    topK: number;
+    /**
+     * Optional universal filter for the search.
+     * This is NOT yet translated - adapters will translate it to their native format.
+     * See VectorDBAdapter.translateFilter() for translation logic.
+     */
+    filter?: UniversalFilter;
+    /** Whether to include embedding vectors in results */
+    includeEmbeddings?: boolean;
+}
+/**
+ * Results grouped by different dimensions.
+ *
+ * Used for organizing search results by vertical (document)
+ * or horizontal (theme) dimensions.
+ *
+ * **How Map keys are determined:**
+ * - Vertical: Keys are extracted from the `__v_doc_id` field in record metadata
+ * - Horizontal: Keys are extracted from the `__h_theme` field in record metadata
+ *
+ * **Handling missing metadata:**
+ * - If a record is missing `__v_doc_id`, it will NOT appear in the vertical Map
+ * - If a record is missing `__h_theme`, it will NOT appear in the horizontal Map
+ * - Records can be excluded from both Maps if they lack the required metadata fields
+ *
+ * **Grouping behavior:**
+ * - Each record appears in AT MOST ONE group per dimension (based on its metadata value)
+ * - A record with `__v_doc_id: "doc1"` will appear in `vertical.get("doc1")`
+ * - A record with `__h_theme: "legal"` will appear in `horizontal.get("legal")`
+ * - Records cannot appear in multiple groups within the same dimension
+ */
+interface GroupedResults {
+    /** Records grouped by document ID (__v_doc_id) */
+    vertical: Map<string, VectorRecord[]>;
+    /** Records grouped by theme (__h_theme) */
+    horizontal: Map<string, VectorRecord[]>;
+}
+
+/**
+ * FilterBuilder - Utility for combining multiple filters with fluent API.
+ *
+ * Provides a convenient way to combine vertical, horizontal, and custom filters
+ * into a single UniversalFilter with AND logic.
+ *
+ * @example
+ * ```typescript
+ * const filter = new FilterBuilder()
+ *   .withVerticalFilter({ field: 'doc_id', op: 'eq', value: 'doc123' })
+ *   .withHorizontalFilter({ field: 'theme', op: 'eq', value: 'legal' })
+ *   .build();
+ * ```
+ */
+declare class FilterBuilder {
+    private verticalFilter?;
+    private horizontalFilter?;
+    private 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: UniversalFilter | Record<string, any>): 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: UniversalFilter | Record<string, any>): 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: UniversalFilter | Record<string, any>): 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(): UniversalFilter | undefined;
+}
+
+/**
+ * Abstract base class for text embedding models.
+ *
+ * This abstraction allows the VectorORM to work with any embedding provider
+ * (OpenAI, Cohere, HuggingFace, etc.) by implementing a consistent interface.
+ *
+ * Implementations must provide:
+ * - `embed()`: Convert a single text string into a vector embedding
+ * - `embedBatch()`: Convert multiple texts into embeddings efficiently
+ * - `dimensions`: The size of the embedding vectors produced
+ * - `modelName`: Identifier for the embedding model being used
+ *
+ * @example
+ * ```typescript
+ * class OpenAIEmbedder extends Embedder {
+ *   get dimensions(): number { return 1536; }
+ *   get modelName(): string { return 'text-embedding-ada-002'; }
+ *
+ *   async embed(text: string): Promise<number[]> {
+ *     // Call OpenAI API
+ *   }
+ *
+ *   async embedBatch(texts: string[]): Promise<number[][]> {
+ *     // Batch call to OpenAI API
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Embedder {
+    /**
+     * The dimensionality of embeddings produced by this model.
+     * Must be consistent across all embeddings from the same model.
+     */
+    abstract get dimensions(): number;
+    /**
+     * Identifier for the embedding model.
+     * Used for tracking which model generated embeddings.
+     */
+    abstract get modelName(): string;
+    /**
+     * Embed a single text string into a vector.
+     *
+     * @param text - The text to embed
+     * @returns A promise that resolves to a number array representing the embedding
+     */
+    abstract embed(text: string): Promise<number[]>;
+    /**
+     * Embed multiple texts into vectors efficiently.
+     * Implementations should maintain the order of input texts in the output.
+     *
+     * @param texts - Array of texts to embed
+     * @returns A promise that resolves to an array of embeddings, one per input text
+     */
+    abstract embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Constructor is protected to prevent direct instantiation of abstract class.
+     * Subclasses can call super() in their constructors.
+     */
+    protected constructor();
+}
+
+/**
+ * RAGQueryComposer - Main orchestrator for retrieval operations.
+ *
+ * Coordinates between embedder and vector database adapter to perform
+ * semantic search with filtering. Provides specialized methods for
+ * grouping results by vertical (document) or horizontal (theme) dimensions.
+ *
+ * @example
+ * ```typescript
+ * const composer = new RAGQueryComposer(adapter, embedder);
+ *
+ * // Basic retrieval
+ * const result = await composer.retrieve({
+ *   query: 'pricing information',
+ *   collection: 'documents',
+ *   topK: 10
+ * });
+ *
+ * // Retrieval with filters
+ * const filtered = await composer.retrieve({
+ *   query: 'pricing information',
+ *   collection: 'documents',
+ *   topK: 10,
+ *   verticalFilters: { doc_id: 'contract-123' },
+ *   horizontalFilters: { theme: 'legal' }
+ * });
+ *
+ * // Grouped by document
+ * const byDocument = await composer.retrieveVertical({
+ *   query: 'pricing information',
+ *   collection: 'documents',
+ *   topK: 10
+ * });
+ * ```
+ */
+declare class RAGQueryComposer {
+    private readonly adapter;
+    private readonly embedder;
+    /**
+     * Create a new RAGQueryComposer.
+     *
+     * @param adapter - Vector database adapter for search operations
+     * @param embedder - Embedder for converting text queries to vectors
+     */
+    constructor(adapter: VectorDBAdapter, 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
+     */
+    retrieve(params: RetrievalParams): Promise<RetrievalResult>;
+    /**
+     * 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
+     */
+    retrieveVertical(params: RetrievalParams): Promise<Map<string, VectorRecord[]>>;
+    /**
+     * 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
+     */
+    retrieveHorizontal(params: RetrievalParams): Promise<Map<string, VectorRecord[]>>;
+}
+
+/**
+ * Options for LLM text generation.
+ *
+ * These options control how the LLM generates text,
+ * allowing fine-grained control over the output behavior.
+ */
+interface GenerateOptions {
+    /**
+     * Controls randomness in generation.
+     * Higher values (e.g., 1.0) make output more random.
+     * Lower values (e.g., 0.1) make output more deterministic.
+     * Range: 0.0 to 2.0
+     */
+    temperature?: number;
+    /**
+     * Maximum number of tokens to generate.
+     * Limits the length of the generated output.
+     */
+    maxTokens?: number;
+    /**
+     * System prompt to set context for the LLM.
+     * Used to guide the model's behavior and personality.
+     */
+    systemPrompt?: string;
+    /**
+     * Sequences where the LLM should stop generating.
+     * When encountered, generation stops immediately.
+     */
+    stopSequences?: string[];
+}
+
+/**
+ * Abstract base class for LLM (Large Language Model) clients.
+ *
+ * This abstraction allows the VectorORM to work with any LLM provider
+ * (OpenAI, Anthropic, Google, etc.) by implementing a consistent interface.
+ *
+ * Implementations must provide:
+ * - `generate()`: Generate text from a prompt
+ * - `generateJSON<T>()`: Generate structured JSON output
+ * - `generateBatch()`: Generate multiple responses efficiently
+ * - `modelName`: Identifier for the LLM model being used
+ * - `provider`: Name of the LLM provider
+ *
+ * @example
+ * ```typescript
+ * class OpenAIClient extends LLMClient {
+ *   get modelName(): string { return 'gpt-4'; }
+ *   get provider(): string { return 'openai'; }
+ *
+ *   async generate(prompt: string, options?: GenerateOptions): Promise<string> {
+ *     // Call OpenAI API
+ *   }
+ *
+ *   async generateJSON<T>(prompt: string, options?: GenerateOptions): Promise<T> {
+ *     // Call OpenAI API with JSON mode
+ *   }
+ *
+ *   async generateBatch(prompts: string[], options?: GenerateOptions): Promise<string[]> {
+ *     // Batch call to OpenAI API
+ *   }
+ * }
+ * ```
+ */
+declare abstract class LLMClient {
+    /**
+     * Identifier for the LLM model.
+     * Used for tracking which model generated responses.
+     */
+    abstract get modelName(): string;
+    /**
+     * Name of the LLM provider.
+     * Examples: 'openai', 'anthropic', 'google', 'mock'
+     */
+    abstract get provider(): string;
+    /**
+     * Generate text from a prompt.
+     *
+     * @param prompt - The text prompt to send to the LLM
+     * @param options - Optional generation parameters
+     * @returns A promise that resolves to the generated text
+     */
+    abstract generate(prompt: string, options?: GenerateOptions): Promise<string>;
+    /**
+     * Generate structured JSON output from a prompt.
+     * The LLM will be instructed to return valid JSON that matches type T.
+     *
+     * @param prompt - The text prompt to send to the LLM
+     * @param options - Optional generation parameters
+     * @returns A promise that resolves to the parsed JSON object
+     */
+    abstract generateJSON<T>(prompt: string, options?: GenerateOptions): Promise<T>;
+    /**
+     * Generate multiple responses efficiently.
+     * Implementations should maintain the order of input prompts in the output.
+     *
+     * @param prompts - Array of prompts to process
+     * @param options - Optional generation parameters
+     * @returns A promise that resolves to an array of responses, one per input prompt
+     */
+    abstract generateBatch(prompts: string[], options?: GenerateOptions): Promise<string[]>;
+    /**
+     * Constructor is protected to prevent direct instantiation of abstract class.
+     * Subclasses can call super() in their constructors.
+     */
+    protected constructor();
+}
+
+/**
+ * MockLLM for testing purposes only.
+ * Returns canned responses that can be set programmatically.
+ *
+ * @example
+ * ```typescript
+ * const llm = new MockLLM();
+ * llm.setResponse('Hello, world!');
+ * const result = await llm.generate('Say hello'); // Returns 'Hello, world!'
+ * ```
+ */
+declare class MockLLM extends LLMClient {
+    private _response;
+    constructor();
+    get modelName(): string;
+    get provider(): string;
+    /**
+     * Set the canned response that will be returned by generate methods.
+     *
+     * @param response - The response text to return
+     */
+    setResponse(response: string): void;
+    generate(prompt: string, options?: GenerateOptions): Promise<string>;
+    generateJSON<T>(prompt: string, options?: GenerateOptions): Promise<T>;
+    generateBatch(prompts: string[], options?: GenerateOptions): Promise<string[]>;
+}
+
+/**
+ * Theme classification result containing the identified theme and confidence score.
+ *
+ * @property theme - The identified theme label (e.g., 'technology', 'business', 'science')
+ * @property confidence - Confidence score between 0 and 1 indicating classification certainty
+ * @property allScores - Optional map of all theme labels to their respective confidence scores
+ */
+interface ThemeClassification {
+    /**
+     * The identified theme label.
+     * Examples: 'technology', 'business', 'science', 'healthcare', 'education', etc.
+     */
+    theme: string;
+    /**
+     * Confidence score between 0 and 1 indicating classification certainty.
+     * Higher values indicate greater confidence in the classification.
+     */
+    confidence: number;
+    /**
+     * Optional map of all theme labels to their respective confidence scores.
+     * Useful for understanding alternative themes and their relative probabilities.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   'technology': 0.85,
+     *   'business': 0.10,
+     *   'science': 0.05
+     * }
+     * ```
+     */
+    allScores?: Record<string, number>;
+}
+/**
+ * Interface for theme classification strategies.
+ *
+ * Theme classifiers identify the primary theme or topic of text content.
+ * Different implementations can use various strategies:
+ *
+ * 1. **Keyword-based Classification**: Uses predefined keyword lists to match themes
+ *    - Fast and deterministic
+ *    - Good for well-defined domains with clear vocabulary
+ *    - Example: Medical texts with specific terminology
+ *
+ * 2. **Zero-shot Classification**: Uses pre-trained models without fine-tuning
+ *    - No training data required
+ *    - Good for general-purpose classification
+ *    - Example: Hugging Face zero-shot classification models
+ *
+ * 3. **Embedding-based Classification**: Uses vector similarity between text and theme embeddings
+ *    - Semantic understanding of themes
+ *    - Can find nuanced thematic relationships
+ *    - Example: Comparing document embeddings to theme prototype embeddings
+ *
+ * 4. **LLM-based Classification**: Uses language models for theme identification
+ *    - Most flexible and powerful
+ *    - Can understand complex, nuanced themes
+ *    - Example: GPT-4, Claude, or other LLMs with structured output
+ *
+ * Implementations should:
+ * - Return confidence scores between 0 and 1
+ * - Handle empty or invalid input gracefully
+ * - Maintain consistent theme labels across calls
+ * - Optionally provide all theme scores for transparency
+ *
+ * @example
+ * ```typescript
+ * class KeywordThemeClassifier implements ThemeClassifier {
+ *   async classify(text: string): Promise<ThemeClassification> {
+ *     // Keyword matching logic
+ *     const theme = 'technology';
+ *     const confidence = 0.92;
+ *     return { theme, confidence };
+ *   }
+ *
+ *   async classifyBatch(texts: string[]): Promise<ThemeClassification[]> {
+ *     return Promise.all(texts.map(text => this.classify(text)));
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class LLMThemeClassifier implements ThemeClassifier {
+ *   constructor(private llm: LLMClient, private themes: string[]) {}
+ *
+ *   async classify(text: string): Promise<ThemeClassification> {
+ *     const prompt = `Classify the following text into one of these themes: ${this.themes.join(', ')}
+ *
+ * Text: ${text}
+ *
+ * Return JSON with: theme (string), confidence (number 0-1), allScores (object)`;
+ *
+ *     const result = await this.llm.generateJSON<ThemeClassification>(prompt);
+ *     return result;
+ *   }
+ *
+ *   async classifyBatch(texts: string[]): Promise<ThemeClassification[]> {
+ *     // Efficient batch processing
+ *     return Promise.all(texts.map(text => this.classify(text)));
+ *   }
+ * }
+ * ```
+ */
+interface ThemeClassifier {
+    /**
+     * Classify a single text and return the identified theme with confidence score.
+     *
+     * @param text - The text content to classify
+     * @returns A promise that resolves to the theme classification result
+     *
+     * @example
+     * ```typescript
+     * const classifier = new KeywordThemeClassifier();
+     * const result = await classifier.classify('Machine learning is transforming AI');
+     * console.log(result.theme); // 'technology'
+     * console.log(result.confidence); // 0.92
+     * ```
+     */
+    classify(text: string): Promise<ThemeClassification>;
+    /**
+     * Classify multiple texts efficiently and return their theme classifications.
+     *
+     * Implementations should maintain the order of input texts in the output array.
+     * May use parallel processing or batching 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 KeywordThemeClassifier();
+     * const texts = [
+     *   'Machine learning is transforming AI',
+     *   'The stock market reached new highs',
+     *   'New cancer treatment shows promise'
+     * ];
+     * const results = await classifier.classifyBatch(texts);
+     * // results[0].theme === 'technology'
+     * // results[1].theme === 'business'
+     * // results[2].theme === 'healthcare'
+     * ```
+     */
+    classifyBatch(texts: string[]): Promise<ThemeClassification[]>;
+}
+
+/**
+ * Types and interfaces for document enrichment operations.
+ *
+ * This module defines the configuration interfaces for various enrichment strategies:
+ * - Vertical enrichment: Classify documents into business verticals
+ * - Theme enrichment: Add thematic tags to documents
+ * - Section enrichment: Structure documents into logical sections
+ */
+
+/**
+ * Progress callback function for tracking enrichment operations.
+ *
+ * @param stats - Current enrichment statistics
+ *
+ * @example
+ * ```typescript
+ * const onProgress: ProgressCallback = (stats) => {
+ *   console.log(`Processed: ${stats.recordsProcessed}/${stats.recordsProcessed + stats.recordsSkipped}`);
+ *   console.log(`Updated: ${stats.recordsUpdated}`);
+ * };
+ * ```
+ */
+type ProgressCallback = (stats: EnrichmentStats) => void;
+/**
+ * Statistics for an enrichment operation.
+ *
+ * Tracks the progress and outcome of enrichment operations,
+ * including records processed, updated, skipped, and any errors encountered.
+ *
+ * @property recordsProcessed - Total number of records processed
+ * @property recordsUpdated - Number of records successfully updated
+ * @property recordsSkipped - Number of records skipped (e.g., filtered out)
+ * @property timeMs - Total time taken in milliseconds
+ * @property errors - Optional array of error messages encountered during enrichment
+ *
+ * @example
+ * ```typescript
+ * const stats: EnrichmentStats = {
+ *   recordsProcessed: 100,
+ *   recordsUpdated: 95,
+ *   recordsSkipped: 5,
+ *   timeMs: 1250,
+ *   errors: ['Failed to classify record 42']
+ * };
+ * ```
+ */
+interface EnrichmentStats {
+    /**
+     * Total number of records processed.
+     */
+    recordsProcessed: number;
+    /**
+     * Number of records successfully updated with enrichment data.
+     */
+    recordsUpdated: number;
+    /**
+     * Number of records skipped (e.g., filtered out or already enriched).
+     */
+    recordsSkipped: number;
+    /**
+     * Total time taken in milliseconds.
+     */
+    timeMs: number;
+    /**
+     * Optional array of error messages encountered during enrichment.
+     */
+    errors?: string[];
+}
+/**
+ * Configuration for field mapping-based vertical enrichment.
+ *
+ * Maps values from an existing field to vertical classifications.
+ * This is the simplest enrichment strategy, useful when vertical
+ * information is already present in a different field.
+ *
+ * @property mapping - Map of source field values to vertical labels
+ * @property filter - Optional filter to select which records to enrich
+ * @property batchSize - Optional batch size for processing (default: 100)
+ *
+ * @example
+ * ```typescript
+ * const config: FieldMappingConfig = {
+ *   mapping: {
+ *     'tech': 'technology',
+ *     'healthcare': 'medical',
+ *     'fin': 'finance'
+ *   },
+ *   filter: { field: 'category', op: 'exists', value: true },
+ *   batchSize: 50
+ * };
+ * ```
+ */
+interface FieldMappingConfig {
+    /**
+     * Map of source field values to vertical labels.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   'tech': 'technology',
+     *   'healthcare': 'medical',
+     *   'finance': 'finance'
+     * }
+     * ```
+     */
+    mapping: Record<string, string>;
+    /**
+     * Optional filter to select which records to enrich.
+     */
+    filter?: UniversalFilter;
+    /**
+     * Optional batch size for processing (default: 100).
+     */
+    batchSize?: number;
+}
+/**
+ * Configuration for custom extractor function-based vertical enrichment.
+ *
+ * Uses a custom function to extract vertical classifications from documents.
+ * This provides maximum flexibility for complex extraction logic.
+ *
+ * @property extractor - Function that extracts vertical label from a document
+ * @property filter - Optional filter to select which records to enrich
+ * @property batchSize - Optional batch size for processing (default: 100)
+ *
+ * @example
+ * ```typescript
+ * const config: ExtractorConfig = {
+ *   extractor: async (doc) => {
+ *     if (doc.content.includes('machine learning')) return 'technology';
+ *     if (doc.content.includes('stock market')) return 'finance';
+ *     return 'general';
+ *   },
+ *   filter: { field: 'content', op: 'exists', value: true },
+ *   batchSize: 25
+ * };
+ * ```
+ */
+interface ExtractorConfig {
+    /**
+     * Function that extracts vertical label from a document.
+     *
+     * @param document - The document to extract vertical from
+     * @returns Promise resolving to the vertical label
+     */
+    extractor: (document: any) => Promise<string>;
+    /**
+     * Optional filter to select which records to enrich.
+     */
+    filter?: UniversalFilter;
+    /**
+     * Optional batch size for processing (default: 100).
+     */
+    batchSize?: number;
+}
+/**
+ * Configuration for automatic LLM-based vertical enrichment.
+ *
+ * Uses a language model to automatically classify documents into verticals.
+ * Can use predefined field mappings or automatic extraction from text.
+ *
+ * @property llm - The LLM client to use for classification
+ * @property fields - Array of vertical labels to classify into
+ * @property promptTemplate - Optional custom prompt template for the LLM
+ * @property textField - Optional field name containing text to classify (default: 'content')
+ * @property filter - Optional filter to select which records to enrich
+ * @property batchSize - Optional batch size for processing (default: 10)
+ *
+ * @example
+ * ```typescript
+ * const config: AutomaticExtractionConfig = {
+ *   automatic: {
+ *     llm: myLLMClient,
+ *     fields: ['technology', 'finance', 'healthcare', 'retail'],
+ *     promptTemplate: 'Classify this text into one of: {fields}\n\nText: {text}',
+ *     textField: 'description'
+ *   },
+ *   filter: { field: 'vertical', op: 'eq', value: null },
+ *   batchSize: 5
+ * };
+ * ```
+ */
+interface AutomaticExtractionConfig {
+    /**
+     * Automatic extraction settings using an LLM.
+     */
+    automatic: {
+        /**
+         * The LLM client to use for classification.
+         */
+        llm: LLMClient;
+        /**
+         * Array of vertical labels to classify into.
+         *
+         * @example
+         * ['technology', 'finance', 'healthcare', 'retail']
+         */
+        fields: string[];
+        /**
+         * Optional custom prompt template for the LLM.
+         * Use {fields} for the list of verticals and {text} for the document text.
+         *
+         * @example
+         * 'Classify this text into one of: {fields}\n\nText: {text}'
+         */
+        promptTemplate?: string;
+        /**
+         * Optional field name containing text to classify (default: 'content').
+         */
+        textField?: string;
+    };
+    /**
+     * Optional filter to select which records to enrich.
+     */
+    filter?: UniversalFilter;
+    /**
+     * Optional batch size for processing (default: 10).
+     */
+    batchSize?: number;
+}
+/**
+ * Configuration for vertical enrichment operations.
+ *
+ * Vertical enrichment classifies documents into business verticals
+ * (e.g., technology, finance, healthcare). Three strategies are supported:
+ *
+ * 1. **Field Mapping**: Map existing field values to verticals
+ * 2. **Custom Extractor**: Use a custom function to extract verticals
+ * 3. **Automatic Extraction**: Use an LLM to automatically classify documents
+ *
+ * @example
+ * ```typescript
+ * // Field mapping
+ * const config1: VerticalEnrichmentConfig = {
+ *   mapping: { 'tech': 'technology', 'hc': 'healthcare' }
+ * };
+ *
+ * // Custom extractor
+ * const config2: VerticalEnrichmentConfig = {
+ *   extractor: async (doc) => extractVertical(doc)
+ * };
+ *
+ * // Automatic extraction
+ * const config3: VerticalEnrichmentConfig = {
+ *   automatic: {
+ *     llm: myLLMClient,
+ *     fields: ['technology', 'finance', 'healthcare']
+ *   }
+ * };
+ * ```
+ */
+type VerticalEnrichmentConfig = FieldMappingConfig | ExtractorConfig | AutomaticExtractionConfig;
+/**
+ * Configuration for theme enrichment operations.
+ *
+ * Theme enrichment adds thematic tags to documents using a theme classifier.
+ * Supports confidence thresholds, multi-theme tagging, and custom text fields.
+ *
+ * @property themes - Array of theme labels to classify into
+ * @property classifier - The theme classifier to use for classification
+ * @property textField - Optional field name containing text to classify (default: 'content')
+ * @property confidenceThreshold - Optional minimum confidence threshold (default: 0.0)
+ * @property multiTheme - Optional flag to allow multiple themes per document (default: false)
+ * @property filter - Optional filter to select which records to enrich
+ * @property batchSize - Optional batch size for processing (default: 100)
+ * @property onProgress - Optional callback for tracking progress
+ *
+ * @example
+ * ```typescript
+ * const config: ThemeEnrichmentConfig = {
+ *   themes: ['technology', 'business', 'science', 'healthcare'],
+ *   classifier: new KeywordThemeClassifier(),
+ *   textField: 'description',
+ *   confidenceThreshold: 0.7,
+ *   multiTheme: true,
+ *   filter: { field: 'themes', op: 'eq', value: null },
+ *   batchSize: 50,
+ *   onProgress: (stats) => console.log(`Processed: ${stats.recordsProcessed}`)
+ * };
+ * ```
+ */
+interface ThemeEnrichmentConfig {
+    /**
+     * Array of theme labels to classify into.
+     *
+     * @example
+     * ['technology', 'business', 'science', 'healthcare']
+     */
+    themes: string[];
+    /**
+     * The theme classifier to use for classification.
+     */
+    classifier: ThemeClassifier;
+    /**
+     * Optional field name containing text to classify (default: 'content').
+     */
+    textField?: string;
+    /**
+     * Optional minimum confidence threshold (default: 0.0).
+     * Only themes with confidence >= this value will be assigned.
+     */
+    confidenceThreshold?: number;
+    /**
+     * Optional flag to allow multiple themes per document (default: false).
+     * When true, all themes above the confidence threshold are assigned.
+     */
+    multiTheme?: boolean;
+    /**
+     * Optional filter to select which records to enrich.
+     */
+    filter?: UniversalFilter;
+    /**
+     * Optional batch size for processing (default: 100).
+     */
+    batchSize?: number;
+    /**
+     * Optional callback for tracking progress.
+     */
+    onProgress?: ProgressCallback;
+}
+/**
+ * Configuration for section enrichment operations.
+ *
+ * Section enrichment structures documents into logical sections
+ * (e.g., introduction, methodology, results, conclusion).
+ * Can use existing section markers or automatically detect sections.
+ *
+ * @property existingField - Optional field name containing existing section markers
+ * @property autoDetect - Optional flag to automatically detect sections (default: false)
+ * @property filter - Optional filter to select which records to enrich
+ * @property batchSize - Optional batch size for processing (default: 100)
+ *
+ * @example
+ * ```typescript
+ * // Use existing section markers
+ * const config1: SectionEnrichmentConfig = {
+ *   existingField: 'raw_sections',
+ *   filter: { field: 'sections', op: 'eq', value: null }
+ * };
+ *
+ * // Auto-detect sections
+ * const config2: SectionEnrichmentConfig = {
+ *   autoDetect: true,
+ *   batchSize: 25
+ * };
+ * ```
+ */
+interface SectionEnrichmentConfig {
+    /**
+     * Optional field name containing existing section markers.
+     * If provided, sections will be extracted from this field.
+     */
+    existingField?: string;
+    /**
+     * Optional flag to automatically detect sections (default: false).
+     * When true, sections will be detected using heuristics (headers, paragraphs, etc.).
+     */
+    autoDetect?: boolean;
+    /**
+     * Optional filter to select which records to enrich.
+     */
+    filter?: UniversalFilter;
+    /**
+     * Optional batch size for processing (default: 100).
+     */
+    batchSize?: number;
+}
+/**
+ * Configuration for enriching all aspects of documents.
+ *
+ * Combines vertical, theme, and section enrichment into a single operation.
+ * Allows running multiple enrichment strategies in sequence with shared settings.
+ *
+ * @property vertical - Optional vertical enrichment configuration
+ * @property themes - Optional theme enrichment configuration
+ * @property sections - Optional section enrichment configuration
+ * @property filter - Optional global filter applied to all enrichment operations
+ * @property batchSize - Optional global batch size for all operations (default: 100)
+ * @property onProgress - Optional global progress callback for all operations
+ *
+ * @example
+ * ```typescript
+ * const config: EnrichAllConfig = {
+ *   vertical: {
+ *     automatic: {
+ *       llm: myLLMClient,
+ *       fields: ['technology', 'finance', 'healthcare']
+ *     }
+ *   },
+ *   themes: {
+ *     themes: ['innovation', 'research', 'product'],
+ *     classifier: new KeywordThemeClassifier(),
+ *     confidenceThreshold: 0.8
+ *   },
+ *   sections: {
+ *     autoDetect: true
+ *   },
+ *   filter: { field: 'status', op: 'eq', value: 'pending' },
+ *   batchSize: 50,
+ *   onProgress: (stats) => console.log(`Progress: ${stats.recordsProcessed}`)
+ * };
+ * ```
+ */
+interface EnrichAllConfig {
+    /**
+     * Optional vertical enrichment configuration.
+     */
+    vertical?: VerticalEnrichmentConfig;
+    /**
+     * Optional theme enrichment configuration.
+     */
+    themes?: ThemeEnrichmentConfig;
+    /**
+     * Optional section enrichment configuration.
+     */
+    sections?: SectionEnrichmentConfig;
+    /**
+     * Optional global filter applied to all enrichment operations.
+     * This filter is combined with individual operation filters using AND logic.
+     */
+    filter?: UniversalFilter;
+    /**
+     * Optional global batch size for all operations (default: 100).
+     * Individual operation batch sizes override this value.
+     */
+    batchSize?: number;
+    /**
+     * Optional global progress callback for all operations.
+     * Called after each enrichment operation completes.
+     */
+    onProgress?: ProgressCallback;
+}
+
+/**
+ * Fast, deterministic keyword-based theme classifier
+ * Uses precompiled regex patterns with word boundaries for efficient matching
+ */
+interface ThemeClassificationResult {
+    theme: string;
+    confidence: number;
+    allScores?: Record<string, number>;
+}
+declare class KeywordThemeClassifier {
+    private themes;
+    private caseSensitive;
+    private patterns;
+    private keywordCounts;
+    /**
+     * 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: string[], keywords: Record<string, string[]>, caseSensitive?: boolean);
+    /**
+     * Classify a single text
+     * @param text - Text to classify
+     * @returns Classification result with theme, confidence, and all scores
+     */
+    classify(text: string): ThemeClassificationResult;
+    /**
+     * Classify multiple texts in batch
+     * @param texts - Array of texts to classify
+     * @returns Array of classification results
+     */
+    classifyBatch(texts: string[]): ThemeClassificationResult[];
+    /**
+     * Escape special regex characters in a string
+     * @param str - String to escape
+     * @returns Escaped string safe for use in regex
+     */
+    private escapeRegex;
+}
+
+/**
+ * Zero-shot theme classifier using Transformers.js
+ * Uses pre-trained models without requiring fine-tuning or training data
+ */
+
+/**
+ * Zero-shot classification using pre-trained transformer models.
+ *
+ * This classifier uses Hugging Face's zero-shot classification pipeline
+ * to classify text into themes without requiring training data or fine-tuning.
+ * The model is loaded lazily on the first classify() call to improve startup time.
+ *
+ * Features:
+ * - No training data required
+ * - Works with any set of theme labels
+ * - Lazy model loading (loads on first classification)
+ * - Sequential batch processing to avoid memory issues
+ * - Handles empty text with uniform scores
+ *
+ * @example
+ * ```typescript
+ * const classifier = new ZeroShotThemeClassifier(['technology', 'sports', 'business']);
+ * const result = await classifier.classify('Machine learning is transforming AI');
+ * console.log(result.theme); // 'technology'
+ * console.log(result.confidence); // 0.95
+ * ```
+ */
+declare class ZeroShotThemeClassifier implements ThemeClassifier {
+    private model;
+    private modelName;
+    private 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: string[], modelName?: string);
+    /**
+     * 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
+     */
+    private ensureModelLoaded;
+    /**
+     * 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 }
+     * ```
+     */
+    classify(text: string): Promise<ThemeClassification>;
+    /**
+     * 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'
+     * ```
+     */
+    classifyBatch(texts: string[]): Promise<ThemeClassification[]>;
+}
+
+/**
+ * Embedding-based theme classifier using cosine similarity
+ * Computes similarity between text embeddings and theme embeddings
+ */
+
+/**
+ * Embedding-based classification using cosine similarity.
+ *
+ * This classifier computes embeddings for text and themes, then uses cosine
+ * similarity to determine which theme is most similar to the text. Theme
+ * embeddings are computed lazily on the first classify() call, or can be
+ * provided precomputed in the constructor.
+ *
+ * Features:
+ * - Lazy initialization: theme embeddings computed on first classify()
+ * - Optional precomputed embeddings for faster startup
+ * - Cosine similarity: dotProduct / (normA * normB)
+ * - Normalize similarity [-1,1] to confidence [0,1]
+ * - Handles empty text with uniform scores
+ *
+ * @example
+ * ```typescript
+ * const embedder = new OpenAIEmbedder();
+ * const classifier = new EmbeddingThemeClassifier(['technology', 'sports', 'finance'], embedder);
+ * const result = await classifier.classify('Machine learning is transforming AI');
+ * console.log(result.theme); // 'technology'
+ * console.log(result.confidence); // 0.89
+ * ```
+ */
+declare class EmbeddingThemeClassifier implements ThemeClassifier {
+    private themeEmbeddings;
+    private embedder;
+    private 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: string[], embedder: Embedder, precomputedEmbeddings?: Record<string, number[]>);
+    /**
+     * 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
+     */
+    private ensureThemeEmbeddings;
+    /**
+     * 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
+     */
+    private cosineSimilarity;
+    /**
+     * 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]
+     */
+    private normalizeToConfidence;
+    /**
+     * 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 }
+     * ```
+     */
+    classify(text: string): Promise<ThemeClassification>;
+    /**
+     * 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'
+     * ```
+     */
+    classifyBatch(texts: string[]): Promise<ThemeClassification[]>;
+}
+
+/**
+ * LLM-based theme classifier using language models for high-quality classification
+ * Provides the most flexible and accurate theme classification using LLMs
+ */
+
+/**
+ * LLM-based theme classification using language models.
+ *
+ * This classifier uses LLMs to provide the highest quality theme classification
+ * with semantic understanding and nuanced reasoning. It supports custom prompt
+ * templates for domain-specific classification needs.
+ *
+ * Features:
+ * - Default prompt template with {themes} and {text} placeholders
+ * - Custom prompt template support for specialized domains
+ * - Structured JSON output using LLM.generateJSON<>
+ * - Sequential batch processing to avoid rate limits
+ * - Comprehensive error handling with cause chain
+ * - Empty text handling with uniform scores
+ *
+ * @example
+ * ```typescript
+ * const llm = new OpenAIClient('gpt-4');
+ * const classifier = new LLMThemeClassifier(
+ *   ['technology', 'sports', 'finance'],
+ *   llm
+ * );
+ * const result = await classifier.classify('Machine learning is transforming AI');
+ * console.log(result.theme); // 'technology'
+ * console.log(result.confidence); // 0.95
+ * ```
+ *
+ * @example Custom prompt template
+ * ```typescript
+ * const customTemplate = `Classify this medical text: {text}
+ * Themes: {themes}
+ * Return JSON with theme, confidence, allScores.`;
+ *
+ * const classifier = new LLMThemeClassifier(
+ *   ['cardiology', 'neurology', 'oncology'],
+ *   llm,
+ *   customTemplate
+ * );
+ * ```
+ */
+declare class LLMThemeClassifier implements ThemeClassifier {
+    private themes;
+    private llm;
+    private 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: string[], llm: LLMClient, promptTemplate?: string);
+    /**
+     * Build the classification prompt by replacing placeholders
+     *
+     * @param text - The text to classify
+     * @returns The complete prompt with placeholders replaced
+     */
+    private buildPrompt;
+    /**
+     * 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 }
+     * ```
+     */
+    classify(text: string): Promise<ThemeClassification>;
+    /**
+     * 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'
+     * ```
+     */
+    classifyBatch(texts: string[]): Promise<ThemeClassification[]>;
+}
+
+/**
+ * Enrichment pipeline for adding metadata to vector records.
+ *
+ * This class provides the main enrichment functionality:
+ * - Vertical enrichment: Classify documents into business verticals
+ * - Theme enrichment: Add thematic tags to documents
+ * - Section enrichment: Structure documents into logical sections
+ * - Batch processing: Efficiently process large collections
+ *
+ * Design principles:
+ * 1. Database-agnostic: Works with any VectorDBAdapter
+ * 2. Strategy pattern: Multiple enrichment strategies per operation
+ * 3. Batch processing: Efficient iteration and bulk updates
+ * 4. Error resilience: Continue processing despite individual failures
+ */
+
+/**
+ * EnrichmentPipeline provides methods to enrich vector records with metadata.
+ *
+ * The pipeline supports three types of enrichment:
+ * 1. Vertical enrichment: Classify into business verticals (technology, finance, etc.)
+ * 2. Theme enrichment: Add thematic tags (innovation, research, etc.)
+ * 3. Section enrichment: Structure into logical sections
+ *
+ * Each enrichment type supports multiple strategies for maximum flexibility.
+ *
+ * @example
+ * ```typescript
+ * const pipeline = new EnrichmentPipeline(adapter, embedder, llm);
+ *
+ * // Enrich using field mapping
+ * await pipeline.enrichVertical('my-collection', {
+ *   mapping: { 'tech': 'technology', 'hc': 'healthcare' }
+ * });
+ *
+ * // Enrich using custom extractor
+ * await pipeline.enrichVertical('my-collection', {
+ *   extractor: async (doc) => extractVertical(doc)
+ * });
+ *
+ * // Enrich using LLM
+ * await pipeline.enrichVertical('my-collection', {
+ *   automatic: {
+ *     llm: myLLMClient,
+ *     fields: ['technology', 'finance', 'healthcare']
+ *   }
+ * });
+ * ```
+ */
+declare class EnrichmentPipeline {
+    private adapter;
+    private embedder?;
+    private llm?;
+    /**
+     * 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: VectorDBAdapter, embedder?: any | undefined, llm?: any | undefined);
+    /**
+     * 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']
+     *   }
+     * });
+     * ```
+     */
+    enrichVertical(collection: string, config: VerticalEnrichmentConfig): Promise<EnrichmentStats>;
+    /**
+     * 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
+     */
+    private enrichWithFieldMapping;
+    /**
+     * 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
+     */
+    private applyFieldMapping;
+    /**
+     * 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
+     */
+    private enrichWithExtractor;
+    /**
+     * 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
+     */
+    private enrichWithLLM;
+    /**
+     * 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
+     */
+    private extractWithLLM;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    enrichThemes(collection: string, config: ThemeEnrichmentConfig): Promise<EnrichmentStats>;
+    /**
+     * Enrich records using theme classifier.
+     *
+     * @param collection - Collection name
+     * @param config - Theme enrichment configuration
+     * @param stats - Statistics object to update
+     */
+    private enrichWithThemeClassifier;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    enrichSections(collection: string, config: SectionEnrichmentConfig): Promise<EnrichmentStats>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    enrichAll(collection: string, config: EnrichAllConfig): Promise<EnrichmentStats>;
+    /**
+     * Apply global configuration to individual enrichment configs.
+     *
+     * @param individualConfig - Configuration for a specific enrichment type
+     * @param globalConfig - Global configuration
+     * @returns Merged configuration
+     */
+    private applyGlobalConfig;
+    /**
+     * Merge stats from an enrichment operation into aggregate stats.
+     *
+     * @param aggregate - Aggregate stats to update
+     * @param stats - Stats from a single operation
+     */
+    private mergeStats;
+    /**
+     * Enrich records using section detection.
+     *
+     * @param collection - Collection name
+     * @param config - Section enrichment configuration
+     * @param stats - Statistics object to update
+     */
+    private enrichWithSectionDetection;
+    /**
+     * Extract section metadata from an existing field value.
+     *
+     * @param sectionPath - Section path string (e.g., "introduction/overview")
+     * @returns Section metadata or null
+     */
+    private extractSectionMetadata;
+    /**
+     * Detect sections in text using heuristics.
+     *
+     * @param text - Text content to analyze
+     * @returns Section metadata or null
+     */
+    private detectSections;
+    /**
+     * Detect markdown headers (# Header).
+     *
+     * @param text - Text content
+     * @returns Section metadata or null
+     */
+    private detectMarkdownSections;
+    /**
+     * Detect HTML headers (<h1>Header</h1>).
+     *
+     * @param text - Text content
+     * @returns Section metadata or null
+     */
+    private detectHtmlSections;
+    /**
+     * Detect sections using common patterns (SECTION: Title).
+     *
+     * @param text - Text content
+     * @returns Section metadata or null
+     */
+    private detectPatternSections;
+}
+
+/**
+ * Loaded document with extracted text and metadata.
+ */
+interface Document {
+    /** Full document text */
+    text: string;
+    /** File path or source identifier */
+    source: string;
+    /** File type/extension (pdf, txt, docx, html) */
+    type: string;
+    /** Optional user-provided or loader-extracted metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Statistics returned by ingestion operations.
+ */
+interface IngestionStats {
+    documentsProcessed: number;
+    documentsSucceeded: number;
+    documentsFailed: number;
+    chunksCreated: number;
+    chunksUpserted: number;
+    timeMs: number;
+    errors?: Array<{
+        source: string;
+        stage: 'load' | 'chunk' | 'embed' | 'upsert';
+        error: Error;
+    }>;
+}
+/**
+ * Configuration for ingestion operations.
+ */
+interface IngestionConfig {
+    chunkSize?: number;
+    chunkOverlap?: number;
+    chunker?: any;
+    metadata?: Record<string, any>;
+    metadataExtractor?: (doc: Document) => Record<string, any>;
+    batchSize?: number;
+    concurrency?: number;
+    onProgress?: (progress: ProgressInfo) => void;
+    onDocumentLoaded?: (doc: Document) => void;
+    onChunksCreated?: (chunks: any[]) => void;
+}
+/**
+ * Progress information during ingestion.
+ */
+interface ProgressInfo {
+    stage: 'loading' | 'chunking' | 'embedding' | 'upserting';
+    documentsProcessed: number;
+    totalDocuments: number;
+    chunksProcessed: number;
+    totalChunks?: number;
+    currentDocument?: string;
+}
+/**
+ * Text chunk with position metadata.
+ */
+interface TextChunk {
+    text: string;
+    index: number;
+    metadata: {
+        source: string;
+        chunkIndex: number;
+        totalChunks: number;
+        startChar: number;
+        endChar: number;
+    };
+}
+/**
+ * Configuration for chunking operations.
+ */
+interface ChunkConfig {
+    chunkSize?: number;
+    chunkOverlap?: number;
+}
+
+/**
+ * Abstract interface for document loaders.
+ * Implementations load specific file formats and return standardized Document objects.
+ */
+interface DocumentLoader {
+    /**
+     * Check if this loader can handle the given file.
+     * @param filePath - Path to the file
+     * @returns true if loader can handle this file type
+     */
+    canHandle(filePath: string): boolean;
+    /**
+     * Load a document from the given file path.
+     * @param filePath - Path to the file to load
+     * @returns Promise resolving to Document
+     */
+    load(filePath: string): Promise<Document>;
+}
+
+/**
+ * Registry for document loaders.
+ * Manages loaders and routes files to correct loader based on extension.
+ */
+declare class LoaderRegistry {
+    private loaders;
+    constructor();
+    /**
+     * Register a custom document loader.
+     * @param loader - Loader to register
+     */
+    register(loader: DocumentLoader): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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
+     */
+    load(filePath: string): Promise<Document>;
+}
+
+/**
+ * Abstract interface for text chunking strategies.
+ * Implementations split text into chunks with different algorithms.
+ */
+interface TextChunker {
+    /**
+     * Chunk text into smaller pieces.
+     * @param text - Text to chunk
+     * @param config - Optional chunking configuration
+     * @returns Array of text chunks with position metadata
+     */
+    chunk(text: string, config?: ChunkConfig): TextChunk[];
+}
+/**
+ * Default chunk size in tokens (approximate).
+ */
+declare const DEFAULT_CHUNK_SIZE = 500;
+/**
+ * Default chunk overlap in tokens (approximate).
+ */
+declare const DEFAULT_CHUNK_OVERLAP = 50;
+/**
+ * Estimate token count from character count.
+ * Simple heuristic: 1 token ≈ 4 characters for English text.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Estimate character count from token count.
+ */
+declare function estimateChars(tokens: number): number;
+
+/**
+ * Main ingestion pipeline orchestrator.
+ * Coordinates loading, chunking, embedding, and upserting documents.
+ */
+declare class IngestionPipeline {
+    private adapter;
+    private embedder;
+    private loaderRegistry;
+    private defaultChunker;
+    constructor(adapter: VectorDBAdapter, embedder: Embedder, loaderRegistry: LoaderRegistry, chunker?: TextChunker);
+    /**
+     * 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
+     */
+    ingest(sources: string | string[], collection: string, config?: IngestionConfig): Promise<IngestionStats>;
+    private ingestFile;
+    private buildMetadata;
+}
+
+/**
+ * Loader for plain text files (.txt, .md).
+ * No external dependencies, uses Node.js built-in fs.
+ */
+declare class TextLoader implements DocumentLoader {
+    canHandle(filePath: string): boolean;
+    load(filePath: string): Promise<Document>;
+}
+
+/**
+ * Loader for PDF files using pdf-parse library.
+ * Extracts text from all pages and includes PDF metadata.
+ */
+declare class PDFLoader implements DocumentLoader {
+    canHandle(filePath: string): boolean;
+    load(filePath: string): Promise<Document>;
+}
+
+/**
+ * Loader for DOCX files using mammoth library.
+ * Converts DOCX to plain text, preserves paragraph structure.
+ */
+declare class DOCXLoader implements DocumentLoader {
+    canHandle(filePath: string): boolean;
+    load(filePath: string): Promise<Document>;
+}
+
+/**
+ * Loader for HTML files using cheerio library.
+ * Strips tags, extracts visible text, removes scripts/styles.
+ */
+declare class HTMLLoader implements DocumentLoader {
+    canHandle(filePath: string): boolean;
+    load(filePath: string): Promise<Document>;
+}
+
+/**
+ * Recursive text chunker that tries different separators hierarchically.
+ * Tries to split by paragraphs first, then sentences, then words, then characters.
+ */
+declare class RecursiveChunker implements TextChunker {
+    private readonly separators;
+    chunk(text: string, config?: ChunkConfig): TextChunk[];
+    private recursiveSplit;
+    private addOverlap;
+}
+
+/**
+ * Fixed-size text chunker that splits at exact character boundaries.
+ * Fast and predictable, but may split mid-sentence or mid-word.
+ */
+declare class FixedChunker implements TextChunker {
+    chunk(text: string, config?: ChunkConfig): TextChunk[];
+}
+
+/**
+ * Sentence-aware chunker that splits on sentence boundaries.
+ * Uses a simple regex-based sentence splitter for portability.
+ */
+declare class SentenceChunker implements TextChunker {
+    chunk(text: string, config?: ChunkConfig): TextChunk[];
+    private splitSentences;
+    private addSentenceOverlap;
+}
+
+/**
+ * Configuration for RAGClient.
+ */
+interface RAGClientConfig {
+    /** Vector database adapter */
+    adapter: VectorDBAdapter;
+    /** Embedding model */
+    embedder: Embedder;
+    /** Optional LLM client (required for query()) */
+    llm?: LLMClient;
+    /** Default collection name */
+    defaultCollection?: string;
+    /** Default number of results to return (default: 10) */
+    defaultTopK?: number;
+}
+/**
+ * Options for retrieval operations.
+ */
+interface RetrieveOptions {
+    /** Override defaultCollection */
+    collection?: string;
+    /** Override defaultTopK */
+    topK?: number;
+    /** Custom filter */
+    filter?: UniversalFilter;
+    /** Shorthand for vertical filter on __v_partition */
+    partition?: string;
+    /** Shorthand for horizontal filter on __h_theme */
+    theme?: string;
+    /** Group results by document or theme */
+    groupBy?: 'document' | 'theme';
+}
+/**
+ * Options for full RAG query operations.
+ */
+interface QueryOptions extends RetrieveOptions {
+    /** Override default RAG system prompt */
+    systemPrompt?: string;
+    /** LLM temperature */
+    temperature?: number;
+    /** LLM max tokens */
+    maxTokens?: number;
+}
+/**
+ * Response from a full RAG query.
+ */
+interface RAGResponse {
+    /** LLM-generated answer */
+    answer: string;
+    /** Retrieved context chunks used to generate the answer */
+    sources: VectorRecord[];
+    /** Original question */
+    query: string;
+    /** Full retrieval details */
+    retrievalResult: RetrievalResult;
+}
+
+/**
+ * RAGClient - Unified facade for all Glyph VectorORM operations.
+ *
+ * Ties together adapter, embedder, LLM, ingestion, enrichment, and query
+ * into a single developer-facing API.
+ *
+ * @example
+ * ```typescript
+ * const client = new RAGClient({
+ *   adapter: new ChromaAdapter(),
+ *   embedder: new OpenAIEmbedder(),
+ *   llm: new OpenAIClient(),
+ *   defaultCollection: 'my-docs'
+ * });
+ *
+ * // Ingest documents
+ * await client.ingest(['docs/*.pdf']);
+ *
+ * // Retrieve
+ * const result = await client.retrieve('pricing info');
+ *
+ * // Full RAG query
+ * const response = await client.query('What are the pricing terms?');
+ * console.log(response.answer);
+ * ```
+ */
+declare class RAGClient {
+    private readonly adapter;
+    private readonly embedder;
+    private readonly llm?;
+    private readonly defaultCollection?;
+    private readonly defaultTopK;
+    private readonly queryComposer;
+    private readonly ingestionPipeline;
+    private readonly enrichmentPipeline;
+    constructor(config: RAGClientConfig);
+    /**
+     * Create a new vector collection.
+     * Dimension defaults to embedder.dimensions if not specified.
+     */
+    createCollection(name: string, dimension?: number, metric?: DistanceMetric): Promise<void>;
+    /**
+     * Delete a collection.
+     */
+    deleteCollection(name: string): Promise<void>;
+    /**
+     * Check if a collection exists.
+     */
+    collectionExists(name: string): Promise<boolean>;
+    /**
+     * Ingest documents into a collection.
+     * Collection defaults to defaultCollection if not specified.
+     */
+    ingest(sources: string | string[], collection?: string, config?: IngestionConfig): Promise<IngestionStats>;
+    /**
+     * Retrieve relevant chunks for a query.
+     * Supports filter shorthands (partition, theme) and groupBy.
+     */
+    retrieve(query: string, options?: RetrieveOptions): Promise<RetrievalResult>;
+    /**
+     * Enrich a collection with vertical, theme, and/or section metadata.
+     */
+    enrich(collection: string, config: EnrichAllConfig): Promise<EnrichmentStats>;
+    /**
+     * Full RAG: retrieve relevant context and generate an answer using LLM.
+     * Requires an LLM client to be provided in the constructor config.
+     */
+    query(question: string, options?: QueryOptions): Promise<RAGResponse>;
+}
+
+export { type AndFilter, type AutomaticExtractionConfig, type ChunkConfig, type CollectionStats, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DOCXLoader, type DistanceMetric, type Document, type DocumentLoader, Embedder, EmbeddingThemeClassifier, type EnrichAllConfig, EnrichmentPipeline, type EnrichmentStats, type ExtractorConfig, type FieldMappingConfig, FilterBuilder, type FilterCondition, type FilterOperator, FilterTranslator, FixedChunker, type GenerateOptions, type GroupedResults, HTMLLoader, type HorizontalFieldKey, HorizontalFields, type IngestionConfig, IngestionPipeline, type IngestionStats, KeywordThemeClassifier, LLMClient, LLMThemeClassifier, LoaderRegistry, METADATA_PREFIXES, MetadataBuilder, type MetadataUpdate, MockLLM, type OrFilter, PDFLoader, type ProgressCallback, type ProgressInfo, type QueryOptions, RAGClient, type RAGClientConfig, RAGQueryComposer, type RAGResponse, RecursiveChunker, type RetrievalParams, type RetrievalResult, type RetrieveOptions, type SearchOptions, type SearchResult, type SectionEnrichmentConfig, SentenceChunker, type ShorthandFilter, type StructuralFieldKey, StructuralFields, type TextChunk, type TextChunker, TextLoader, type ThemeClassification, type ThemeClassificationResult, type ThemeClassifier, type ThemeEnrichmentConfig, type UniversalFilter, VectorDBAdapter, type VectorRecord, type VerticalEnrichmentConfig, type VerticalFieldKey, VerticalFields, ZeroShotThemeClassifier, estimateChars, estimateTokens };