import { EventEmitter } from 'node:events';
import type { CompactionResult, VerifyResult } from './storage-engine';
import type { DatabaseStats, DetailedSearchResult, EmbeddingEntry, EngineOptions, SearchOptions, SearchResult } from './types';
/**
 * Error thrown when the embedding model fails to initialize.
 * This can happen due to missing native bindings, network issues, or invalid model files.
 */
export declare class ModelInitializationError extends Error {
    readonly cause?: Error | undefined;
    constructor(message: string, cause?: Error | undefined);
}
/**
 * Error thrown when embedding generation fails.
 */
export declare class EmbeddingGenerationError extends Error {
    readonly cause?: Error | undefined;
    constructor(message: string, cause?: Error | undefined);
}
export declare class EmbeddingEngine extends EventEmitter {
    private storageEngine;
    private storePath;
    private cacheDir;
    private dimension;
    private readonly readOnly;
    private llama?;
    private model?;
    private embeddingContext?;
    private initPromise?;
    private storageInitPromise?;
    private hnswIndex;
    private textEmbeddingCache;
    private readonly customProvider;
    private readonly modelConfig;
    constructor(options: EngineOptions);
    /**
     * Gets or initializes the storage engine
     * Performs migration from v1 format if needed
     */
    private ensureStorageEngine;
    private initializeStorage;
    /**
     * Lazily builds HNSW index from storage on first call
     */
    private get hnswIndexPath();
    private ensureHnswIndex;
    private isHnswStale;
    private persistHnswIndex;
    /**
     * Gets or initializes the embedding model
     * Caches the model instance to avoid repeated initialization overhead
     */
    private ensureModelLoaded;
    private initializeModel;
    /**
     * Tokenizes text for embedding, truncated to the model's token limit
     * (leaves room for special tokens).
     *
     * Prepends the BOS/CLS token when the model metadata requires it:
     * node-llama-cpp skips it for UGM vocabularies (XLM-RoBERTa models such as
     * bge-m3, which expect `<s>` for CLS pooling), collapsing the embeddings of
     * short texts. getEmbeddingFor() never double-adds it and still appends the
     * end token itself, so models that already get a BOS are unaffected.
     */
    private tokenizeForEmbedding;
    /**
     * Generates embedding from text using the configured embedding model
     * @param text - Text to embed
     * @returns Embedding vector (normalized) with the model's dimension
     */
    generateEmbedding(text: string): Promise<number[]>;
    /**
     * Internal method that returns embedding as Float32Array for performance
     * Uses Float32Array throughout internal operations to avoid boxing overhead
     * Checks the text embedding cache first to avoid regenerating embeddings
     */
    private generateEmbeddingFloat32;
    /**
     * Retrieves an embedding entry by key
     * O(1) lookup via in-memory index
     * @param key - Unique identifier for the entry
     * @returns The embedding entry, or null if not found
     */
    get(key: string): Promise<EmbeddingEntry | null>;
    /**
     * Checks if a key exists in the database
     * O(1) lookup via in-memory index
     * @param key - Unique identifier for the entry
     * @returns true if the key exists, false otherwise
     */
    has(key: string): Promise<boolean>;
    /**
     * Searches for similar embeddings using cosine similarity
     * @param query - Text query to search for
     * @param limit - Maximum number of results to return (default: 10)
     * @param minSimilarity - Minimum similarity threshold (default: 0.5, range: 0 to 1)
     * @returns Array of search results sorted by similarity (highest first)
     */
    search(query: string, options: SearchOptions & {
        includeDetails: true;
    }): Promise<DetailedSearchResult[]>;
    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
    search(query: string, limit?: number, minSimilarity?: number): Promise<SearchResult[]>;
    /**
     * Finds the documents most similar to an existing key.
     *
     * Uses the stored embedding of `key` as the query vector, so no embedding is
     * generated. The source key is excluded from its own results.
     *
     * @param key - Key of an existing entry to find neighbors for
     * @returns Array of search results sorted by similarity (highest first)
     * @throws KeyNotFoundError if the key does not exist
     */
    similarTo(key: string, options: SearchOptions & {
        includeDetails: true;
    }): Promise<DetailedSearchResult[]>;
    similarTo(key: string, options?: SearchOptions): Promise<SearchResult[]>;
    similarTo(key: string, limit?: number, minSimilarity?: number): Promise<SearchResult[]>;
    /**
     * Stores a text embedding with WAL-based durability
     * @param key - Unique identifier for this entry
     * @param text - Text to embed and store
     */
    store(key: string, text: string): Promise<void>;
    /**
     * Stores multiple text embeddings in batch
     * More efficient than calling store() multiple times
     * Generates embeddings in parallel and writes records sequentially
     * Uses text embedding cache to avoid regenerating embeddings for duplicate texts
     * @param items - Array of {key, text} objects to store
     */
    storeMany(items: Array<{
        key: string;
        text: string;
    }>): Promise<void>;
    /**
     * Updates the text for an existing key. Throws KeyNotFoundError if the key doesn't exist.
     * @param key - Unique identifier for the entry to update
     * @param text - New text content to store
     */
    update(key: string, text: string): Promise<void>;
    /**
     * Stores a pre-computed embedding directly, bypassing the embedding model.
     * Useful when you have pre-computed embeddings from an external source.
     * @param key - Unique identifier for the entry
     * @param embedding - Pre-computed embedding vector (Float32Array or number[])
     */
    storeEmbedding(key: string, embedding: Float32Array | number[]): Promise<void>;
    /**
     * Stores multiple pre-computed embeddings in batch.
     * @param items - Array of {key, embedding} objects to store
     */
    storeManyEmbeddings(items: Array<{
        key: string;
        embedding: Float32Array | number[];
    }>): Promise<void>;
    /**
     * Deletes an entry by key
     * Logical delete - records a delete marker in the WAL
     * @param key - Unique identifier for the entry to delete
     * @returns true if the entry was deleted, false if it didn't exist
     */
    delete(key: string): Promise<boolean>;
    /**
     * Gets all keys in the database
     * @returns Iterator of all keys
     */
    keys(): Promise<string[]>;
    /**
     * Returns an async iterator over all keys in the database.
     * More memory-efficient than keys() for large databases.
     */
    /**
     * Searches for multiple queries in batch.
     * Generates embeddings in parallel and runs HNSW lookups for each.
     * @param queries - Array of search query strings
     * @param limit - Maximum results per query (default: 10)
     * @param minSimilarity - Minimum similarity threshold (default: 0.5)
     * @returns Map from query string to its search results
     */
    searchMany(queries: string[], limit?: number, minSimilarity?: number): Promise<Map<string, SearchResult[]>>;
    keysIterator(): AsyncIterableIterator<string>;
    /**
     * Returns an async iterator that yields search results one at a time.
     * Results are sorted by similarity (highest first).
     * @param query - Search query text
     * @param options - Search options (limit, minSimilarity)
     */
    searchStream(query: string, options?: SearchOptions): AsyncIterableIterator<SearchResult>;
    /**
     * Gets the number of entries in the database
     * @returns Number of entries
     */
    count(): Promise<number>;
    /**
     * Returns database statistics including record count, file sizes, and configuration.
     */
    /**
     * Verify the integrity of the database by scanning all records
     * and validating checksums and structure.
     */
    /**
     * Compact the database by rewriting only live records.
     * Removes dead records and reduces file size.
     */
    /**
     * Create a consistent backup of the database at the given destination path.
     * Copies the data file, WAL, and HNSW sidecar (if they exist).
     * @param destPath - Path for the backup data file (e.g., './backup/db.raptor')
     */
    backup(destPath: string): Promise<void>;
    compact(): Promise<CompactionResult>;
    verify(): Promise<VerifyResult>;
    stats(): Promise<DatabaseStats>;
    /**
     * Calculates cosine similarity between two Float32Arrays
     * Uses typed arrays throughout to avoid boxing overhead
     */
    private cosineSimilarity;
    /**
     * Check if the engine is in read-only mode.
     */
    isReadOnly(): boolean;
    /**
     * Gets statistics about the text embedding cache.
     * @returns Cache stats if enabled, null if cache is disabled
     */
    getTextEmbeddingCacheStats(): {
        size: number;
        maxSize: number;
    } | null;
    /**
     * Internal method called by the shared exit handler to dispose native resources.
     * Calls dispose without await since exit handlers must be synchronous.
     * @internal
     */
    _disposeNativeResourcesSync(): void;
    /**
     * Disposes of resources and closes the storage engine
     * Call this when you're done using the engine to free up memory
     */
    dispose(): Promise<void>;
}
//# sourceMappingURL=engine.d.ts.map