/**
 * VectorService - sqlite-vec vector storage and similarity search
 *
 * Handles vector CRUD operations on vec_embeddings virtual table.
 * Search results are self-contained per CP-002 (original text always included).
 *
 * Uses vec_distance_cosine() for all similarity calculations to ensure
 * consistent cosine similarity scoring regardless of underlying index configuration.
 *
 * @module services/storage/vector
 */
import Database from 'better-sqlite3';
/**
 * Error codes for vector operations
 */
declare enum VectorErrorCode {
    INVALID_VECTOR_DIMENSIONS = "INVALID_VECTOR_DIMENSIONS",
    EMBEDDING_NOT_FOUND = "EMBEDDING_NOT_FOUND",
    VEC_EXTENSION_NOT_LOADED = "VEC_EXTENSION_NOT_LOADED",
    STORE_FAILED = "STORE_FAILED",
    SEARCH_FAILED = "SEARCH_FAILED",
    DELETE_FAILED = "DELETE_FAILED"
}
/**
 * Custom error class for vector operations
 * Includes error code and optional details for debugging
 */
export declare class VectorError extends Error {
    readonly code: VectorErrorCode;
    readonly details?: Record<string, unknown> | undefined;
    constructor(message: string, code: VectorErrorCode, details?: Record<string, unknown> | undefined);
}
/**
 * Search result from vector similarity search
 * FLAT structure - no nested objects - direct from SQL join
 *
 * CRITICAL: original_text is ALWAYS included per CP-002
 */
export interface VectorSearchResult {
    embedding_id: string;
    chunk_id: string | null;
    image_id: string | null;
    extraction_id: string | null;
    document_id: string;
    result_type: 'chunk' | 'vlm' | 'extraction';
    similarity_score: number;
    distance: number;
    original_text: string;
    original_text_length: number;
    source_file_path: string;
    source_file_name: string;
    source_file_hash: string;
    page_number: number | null;
    page_range: string | null;
    character_start: number;
    character_end: number;
    chunk_index: number;
    total_chunks: number;
    model_name: string;
    model_version: string;
    provenance_id: string;
    content_hash: string;
    heading_context?: string | null;
    section_path?: string | null;
    content_types?: string | null;
    is_atomic?: boolean;
    chunk_page_range?: string | null;
    heading_level?: number | null;
    ocr_quality_score?: number | null;
    doc_title?: string | null;
    doc_author?: string | null;
    doc_subject?: string | null;
    overlap_previous?: number;
    overlap_next?: number;
    chunking_strategy?: string | null;
    embedding_status?: string;
    doc_page_count?: number | null;
    datalab_mode?: string | null;
}
/**
 * Options for vector similarity search
 */
export interface VectorSearchOptions {
    /** Maximum results to return. Default: 10, Max: 100 */
    limit?: number;
    /** Similarity threshold 0-1. Default: 0.0 (no threshold) */
    threshold?: number;
    /** Filter by document IDs */
    documentFilter?: string[];
    /** Chunk-level filter conditions (from resolveChunkFilter) */
    chunkFilter?: {
        conditions: string[];
        params: unknown[];
    };
    /** Page range filter for VLM/extraction results */
    pageRangeFilter?: {
        min_page?: number;
        max_page?: number;
    };
}
/**
 * VectorService - handles vector storage and similarity search
 *
 * Wraps sqlite-vec operations for 768-dimensional vectors.
 * All search results are self-contained with original text per CP-002.
 */
export declare class VectorService {
    private readonly db;
    private vecLoaded;
    /**
     * Create a new VectorService
     *
     * @param db - Better-sqlite3 database connection with schema already initialized
     * @throws VectorError if sqlite-vec extension cannot be loaded
     */
    constructor(db: Database.Database);
    /**
     * Ensure sqlite-vec extension is loaded
     * FAIL FAST if not available - no workarounds
     */
    private ensureVecExtension;
    /**
     * Store a vector in vec_embeddings
     *
     * PREREQUISITE: Embedding record must already exist in embeddings table
     * (inserted via DatabaseService.insertEmbedding)
     *
     * @param embeddingId - Must match an existing embeddings.id
     * @param vector - 768-dimensional Float32Array
     * @throws VectorError if dimensions != 768 or embedding doesn't exist
     */
    storeVector(embeddingId: string, vector: Float32Array): void;
    /**
     * Store multiple vectors in a single transaction
     *
     * @param items - Array of {embeddingId, vector} pairs
     * @returns Count of vectors stored
     * @throws VectorError on any failure (transaction rolls back)
     */
    batchStoreVectors(items: Array<{
        embeddingId: string;
        vector: Float32Array;
    }>): number;
    /**
     * Search for similar vectors using cosine distance
     *
     * CRITICAL: Results ALWAYS include original_text per CP-002.
     * No follow-up queries needed - results are self-contained.
     *
     * Uses vec_distance_cosine() for consistent cosine similarity.
     *
     * @param queryVector - 768-dim query vector
     * @param options - Search options (limit, threshold, filters)
     * @returns Array of VectorSearchResult with original text and source info
     */
    searchSimilar(queryVector: Float32Array, options?: VectorSearchOptions): VectorSearchResult[];
    /**
     * Build chunk filter SQL fragment for vector search.
     * Translates chunk filter conditions from 'c.' alias to 'ch.' alias used in vector queries.
     */
    private buildChunkFilterSQL;
    /**
     * Search with document filter
     */
    private searchWithFilter;
    /**
     * Search all vectors without filter
     */
    private searchAll;
    /**
     * Determine result type from row identity fields.
     */
    private static getResultType;
    /**
     * Map database rows to VectorSearchResult and filter by threshold.
     * Applies quality-weighted scoring to all results.
     */
    private mapAndFilterResults;
    /**
     * Delete a vector from vec_embeddings
     *
     * @param embeddingId - The embedding ID
     * @returns true if deleted, false if not found
     */
    deleteVector(embeddingId: string): boolean;
    /**
     * Delete all vectors for a document
     *
     * @param documentId - The document ID
     * @returns Count of vectors deleted
     */
    deleteVectorsByDocumentId(documentId: string): number;
    /**
     * Get count of vectors stored
     */
    getVectorCount(): number;
    /**
     * Check if vector exists
     */
    vectorExists(embeddingId: string): boolean;
    /**
     * Get raw vector by embedding ID
     * @returns Float32Array or null if not found
     */
    getVector(embeddingId: string): Float32Array | null;
}
export {};
//# sourceMappingURL=vector.d.ts.map