Vectors and embeddings

export declare abstract class BaseVectorStore implements VectorStore {
    constructor(embedder?: EmbeddingProvider | undefined);
    abstract initialize(): Promise<void>;
    abstract upsert(collection: string, doc: VectorDocument): Promise<void>;
    abstract upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    abstract search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    abstract delete(collection: string, id: string): Promise<void>;
    abstract get(collection: string, id: string): Promise<VectorDocument | null>;
    abstract dropCollection(collection: string): Promise<void>;
    abstract close(): Promise<void>;
}

/**
 * Lightweight BM25 (Okapi BM25) implementation for keyword search.
 * Maintains an in-memory inverted index for fast full-text scoring.
 */
export interface BM25Document {
    id: string;
    content: string;
    metadata?: Record<string, unknown>;
}

export declare class BM25Index {
    constructor(opts?: {
        k1?: number;
        b?: number;
    });
    get size(): number;
    add(doc: BM25Document): void;
    addBatch(docs: BM25Document[]): void;
    remove(id: string): void;
    clear(): void;
    search(query: string, opts?: {
        topK?: number;
        minScore?: number;
        filter?: Record<string, unknown>;
    }): BM25Result[];
}

export interface BM25Result {
    id: string;
    content: string;
    score: number;
    metadata?: Record<string, unknown>;
}

/**
 * Input accepted by multimodal-capable embedding providers. Always produces one vector.
 */
export type EmbeddingInput = string | ContentPart | ContentPart[];

export interface EmbeddingProvider {
    readonly dimensions: number;
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
    /**
     * Optional: embed a single multimodal input (text + images + audio + video + PDFs).
     * Returns ONE aggregated vector. Implementations should throw if the configured model
     * does not support multimodal input.
     */
    embedMultimodal?(input: EmbeddingInput): Promise<number[]>;
    /** Whether this provider/model supports `embedMultimodal`. */
    readonly supportsMultimodal?: boolean;
}

/**
 * Fetch a remote URL and return its base64 content + MIME type.
 * Uses the global `fetch` API (Node 20+).
 */
export declare function fetchAsBase64(url: string): Promise<{
    data: string;
    mimeType: string;
}>;

export declare class GoogleEmbedding implements EmbeddingProvider {
    readonly dimensions: number;
    readonly supportsMultimodal: boolean;
    constructor(config?: GoogleEmbeddingConfig);
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
    embedMultimodal(input: EmbeddingInput): Promise<number[]>;
}

export interface GoogleEmbeddingConfig {
    apiKey?: string;
    model?: string;
    dimensions?: number;
}

/**
 * Tiny local embedder (no API key). Good enough for deterministic tests and local prototypes
 * defaults. Swap in OpenAI/Google embeddings for production search quality.
 */
export declare class HashEmbedding implements EmbeddingProvider {
    readonly dimensions: number;
    constructor(dimensions?: number);
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
}

export declare class InMemoryVectorStore extends BaseVectorStore {
    initialize(): Promise<void>;
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    delete(collection: string, id: string): Promise<void>;
    get(collection: string, id: string): Promise<VectorDocument | null>;
    dropCollection(collection: string): Promise<void>;
    close(): Promise<void>;
}

export interface MongoDBVectorConfig {
    uri: string;
    dbName?: string;
    /** Atlas Search index name (must be pre-created for $vectorSearch). Defaults to "vector_index". */
    indexName?: string;
}

export declare class MongoDBVectorStore extends BaseVectorStore {
    constructor(config: MongoDBVectorConfig, embedder?: EmbeddingProvider);
    initialize(): Promise<void>;
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    delete(collection: string, id: string): Promise<void>;
    get(collection: string, id: string): Promise<VectorDocument | null>;
    dropCollection(collection: string): Promise<void>;
    close(): Promise<void>;
}

export declare class OpenAIEmbedding implements EmbeddingProvider {
    readonly dimensions: number;
    readonly supportsMultimodal = false;
    constructor(config?: OpenAIEmbeddingConfig);
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
}

export interface OpenAIEmbeddingConfig {
    apiKey?: string;
    baseURL?: string;
    model?: string;
    dimensions?: number;
}

/**
 * Read a local file and return a `ContentPart` shaped for the given (or inferred) MIME type.
 * - `image/*`  -> `ImagePart`
 * - `audio/*`  -> `AudioPart`
 * - everything else (video, PDF, ...) -> `FilePart`
 */
export declare function partsFromFile(path: string, mimeType?: string): Promise<ContentPart>;

export interface PgVectorConfig {
    connectionString: string;
    dimensions?: number;
}

export declare class PgVectorStore extends BaseVectorStore {
    constructor(config: PgVectorConfig, embedder?: EmbeddingProvider);
    initialize(): Promise<void>;
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    delete(collection: string, id: string): Promise<void>;
    get(collection: string, id: string): Promise<VectorDocument | null>;
    dropCollection(collection: string): Promise<void>;
    close(): Promise<void>;
}

export interface QdrantConfig {
    url?: string;
    apiKey?: string;
    dimensions?: number;
    checkCompatibility?: boolean;
}

export declare class QdrantVectorStore extends BaseVectorStore {
    constructor(config?: QdrantConfig, embedder?: EmbeddingProvider);
    initialize(): Promise<void>;
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    delete(collection: string, id: string): Promise<void>;
    get(collection: string, id: string): Promise<VectorDocument | null>;
    dropCollection(collection: string): Promise<void>;
    close(): Promise<void>;
}

/**
 * Reciprocal Rank Fusion (RRF) — merges ranked result lists from different
 * retrieval methods into a single fused ranking.
 *
 * RRF score for document d = sum over all lists L of: 1 / (k + rank_L(d))
 * where k is a constant (default 60) that mitigates the impact of high
 * rankings by outlier systems.
 *
 * Reference: Cormack, Clarke & Buettcher (2009)
 */
export interface RankedItem {
    id: string;
    content: string;
    score: number;
    metadata?: Record<string, unknown>;
}

export declare function reciprocalRankFusion(rankedLists: RankedItem[][], options?: RRFOptions): RankedItem[];

export interface RRFOptions {
    /** Fusion constant. Higher values dampen the effect of rank differences. Default 60. */
    k?: number;
    /** Maximum results to return. */
    topK?: number;
    /** Minimum fused score to include. */
    minScore?: number;
    /** Weight per ranked list. Defaults to equal weighting (1.0 each). */
    weights?: number[];
}

export interface VectorDocument {
    id: string;
    content: string;
    /**
     * Optional multimodal payload (text, image, audio, video, PDF). When set and non-empty,
     * the configured `EmbeddingProvider` must implement `embedMultimodal`; the parts will
     * be used for embedding instead of `content`.
     */
    parts?: ContentPart[];
    embedding?: number[];
    metadata?: Record<string, unknown>;
}

export interface VectorSearchOptions {
    topK?: number;
    filter?: Record<string, unknown>;
    minScore?: number;
    /**
     * Optional reranker. When set, the backend fetches `topK * rerankMultiplier` candidates,
     * then reranks them down to `topK` using the given reranker.
     */
    rerank?: Reranker;
    /**
     * Multiplier applied to `topK` when a reranker is configured. Defaults to 3.
     * Example: topK=10, rerankMultiplier=3 -> initial fetch of 30 candidates, reranked down to 10.
     */
    rerankMultiplier?: number;
}

export interface VectorSearchResult {
    id: string;
    content: string;
    score: number;
    metadata?: Record<string, unknown>;
}

export interface VectorStore {
    /** Initialize collections/indexes. Call once before use. */
    initialize(): Promise<void>;
    /** Upsert a single document (embedding computed if not provided). */
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    /** Upsert multiple documents in batch. */
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    /**
     * Similarity search by vector, text query, or multimodal `ContentPart[]` query.
     * Multimodal queries require an `EmbeddingProvider` with `embedMultimodal` support.
     */
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    /** Delete a document by ID. */
    delete(collection: string, id: string): Promise<void>;
    /** Get a document by ID. */
    get(collection: string, id: string): Promise<VectorDocument | null>;
    /** Drop an entire collection. */
    dropCollection(collection: string): Promise<void>;
    /** Close connections. */
    close(): Promise<void>;
}