import type { RagChunk } from './rag.js';
/** Turns texts into vectors, one per text, in order. */
export type EmbeddingProvider = (texts: string[]) => Promise<number[][]> | number[][];
/** A chunk to store, with its vector when already computed. */
export interface VectorDocument extends RagChunk {
    /** Its vector. Computed with the store's embedding function when omitted. */
    embedding?: number[];
}
/** A stored chunk returned by a search. */
export interface VectorSearchResult extends RagChunk {
    /** Cosine similarity to the query, from -1 to 1. */
    score: number;
}
/** Options for a vector search. */
export interface VectorSearchOptions {
    /** Most results returned. Defaults to 5. */
    topK?: number;
    /** Lowest similarity returned. Defaults to 0. */
    minScore?: number;
    /**
     * Exact matches on top-level `metadata` fields, such as `{ tenant: 'acme' }`. Every field must
     * match. Values are strings, numbers, or booleans, which every adapter can filter on natively.
     */
    filter?: Record<string, string | number | boolean>;
}
/**
 * Where retrieval chunks live and how they are searched. `MemoryVectorStore`, `PostgresVectorStore`,
 * and `QdrantVectorStore` implement it, and pass the same contract tests.
 *
 * Adding a chunk whose id already exists replaces it, so re-ingesting a document never duplicates
 * its passages.
 */
export interface VectorStore {
    /** Adds chunks, or replaces the ones whose id already exists, embedding those without a vector. */
    add(documents: VectorDocument[]): Promise<void>;
    /** The chunks most similar to a query text, best first. */
    search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    /** The chunks most similar to a vector computed elsewhere, best first. */
    searchVector(vector: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    /** Removes chunks by id. An id that is not stored is ignored. */
    delete(ids: readonly string[]): Promise<void>;
}
/**
 * Chunks and their vectors in process memory, searched by cosine similarity. Defaults to hashed
 * term vectors, which need no provider.
 */
export declare class MemoryVectorStore implements VectorStore {
    private documents;
    private embed;
    constructor(embed?: EmbeddingProvider);
    /** Adds chunks, or replaces those whose id exists, embedding those without a vector in one batch. */
    add(documents: VectorDocument[]): Promise<void>;
    /** The chunks most similar to a query, best first. */
    search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    /** The chunks most similar to a vector, best first. */
    searchVector(vector: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    /** Removes chunks by id. */
    delete(ids: readonly string[]): Promise<void>;
    /** Removes every chunk. */
    clear(): void;
    /** Chunks held. */
    size(): number;
}
/** Whether a chunk's metadata satisfies an exact-match filter. Every adapter filters the same way. */
export declare function matchesMetadata(metadata: Record<string, unknown> | undefined, filter: VectorSearchOptions['filter']): boolean;
/**
 * Hashed term-count vectors, normalized to unit length. Deterministic and free, for tests and a
 * store without a provider.
 */
export declare function createHashEmbeddings(texts: string[], dimensions?: number): number[][];
/** Cosine similarity of two unit-length vectors, as their dot product. */
export declare function cosineSimilarity(a: number[], b: number[]): number;
/** Scales a vector to unit length, so a dot product is its cosine similarity. A zero vector stays zero. */
export declare function normalizeVector(vector: number[]): number[];