Reranking

/**
 * Cohere reranker. Requires the `cohere-ai` package as an optional peer dependency.
 *
 * Pricing/availability docs: https://docs.cohere.com/reference/rerank
 */
export declare class CohereReranker implements Reranker {
    readonly providerId = "cohere";
    constructor(config?: CohereRerankerConfig);
    rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult[]>;
}

export interface CohereRerankerConfig {
    apiKey?: string;
    /** Cohere rerank model. Defaults to `rerank-v3.5`. */
    model?: string;
}

/** Local cross-encoder via the optional @huggingface/transformers package.
 * Scores paired query/document sequences using sequence-classification logits. */
export declare class CrossEncoderReranker implements Reranker {
    readonly providerId = "cross-encoder-local";
    constructor(config?: CrossEncoderRerankerConfig);
    ready(): Promise<void>;
    rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult[]>;
}

export interface CrossEncoderRerankerConfig {
    /** Model ID or local artifact directory. This adapter is a cross-encoder, not ColBERT late interaction. */
    model?: string;
    prewarm?: boolean;
    /** Defaults true: ordinary calls never silently download model weights. */
    localFilesOnly?: boolean;
    cacheDir?: string;
    dtype?: "fp32" | "fp16" | "q8" | "q4";
    /** Required when a classifier returns multiple labels; defaults LABEL_1. */
    positiveLabel?: string;
    /** Host-owned loader for custom devices, artifact stores and deterministic tests. */
    pipelineFactory?: (task: "text-classification", model: string, options: {
        local_files_only: boolean;
        cache_dir?: string;
        dtype?: string;
    }) => Promise<CrossEncoderPipeline>;
}

/**
 * Jina AI reranker. Uses Jina's HTTPS API directly (no SDK required).
 *
 * Docs: https://jina.ai/reranker
 */
export declare class JinaReranker implements Reranker {
    readonly providerId = "jina";
    constructor(config?: JinaRerankerConfig);
    rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult[]>;
}

export interface JinaRerankerConfig {
    apiKey?: string;
    /** Jina rerank model. Defaults to `jina-reranker-v2-base-multilingual`. */
    model?: string;
    /** Optional override for the Jina base URL. */
    baseURL?: string;
}

/**
 * Document input for reranking.
 * Accepts either a plain string, a `VectorSearchResult`-like object, or any shape
 * with a textual `content` field.
 */
export type RerankDocument = string | {
    id?: string;
    content: string;
    metadata?: Record<string, unknown>;
};

export interface Reranker {
    /** Name of the provider/model (for logging). */
    readonly providerId: string;
    /**
     * Reorder documents by relevance to a query.
     * Returns results sorted by score descending.
     */
    rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult[]>;
}

export interface RerankOptions {
    /** Maximum number of results to return. If undefined, returns all reranked. */
    topK?: number;
    /** Minimum score threshold; results below this are dropped. */
    minScore?: number;
}

export interface RerankResult {
    /** Original index in the input array (useful when callers want to keep their own metadata). */
    index: number;
    /** Relevance score from the reranker. Higher is more relevant. */
    score: number;
    /** Document content as fed to the reranker. */
    content: string;
    /** Original metadata, if the input was an object. */
    metadata?: Record<string, unknown>;
    /** Original id, if the input was an object. */
    id?: string;
}

/**
 * Voyage AI reranker. Uses Voyage's HTTPS API directly (no SDK required).
 *
 * Docs: https://docs.voyageai.com/reference/reranker-api
 */
export declare class VoyageReranker implements Reranker {
    readonly providerId = "voyage";
    constructor(config?: VoyageRerankerConfig);
    rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult[]>;
}

export interface VoyageRerankerConfig {
    apiKey?: string;
    /** Voyage rerank model. Defaults to `rerank-2`. */
    model?: string;
    /** Optional override for the Voyage base URL. */
    baseURL?: string;
}

export type CrossEncoderPipeline = (input: {
    text: string;
    text_pair: string;
}, options: {
    top_k: null;
    function_to_apply: "sigmoid";
}) => Promise<Array<{
    label: string;
    score: number;
}> | {
    label: string;
    score: number;
}>;