import type { Collection, Doc, Filter } from './db.js';
/**
 * 向量检索（知识库 / 语义搜索 / 相似推荐）的应用内实现：向量随文档存进 db 集合的一个字段，
 * 查询时拉回候选文档在进程内算余弦相似度排序。没有服务端向量索引，适用规模见 vectorSearch 的说明。
 */
/** 余弦相似度，范围 [-1, 1]；维度不一致抛错 */
export declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
export interface RankOptions {
    /** 返回前几条，默认 5 */
    topK?: number;
    /** 低于该相似度的丢弃（默认不过滤；0.3~0.5 常用） */
    minScore?: number;
}
export interface Ranked<T> {
    item: T;
    score: number;
}
/** 对一批候选按与 query 的余弦相似度降序排列 */
export declare function rankBySimilarity<T>(query: ArrayLike<number>, items: T[], getVector: (item: T) => ArrayLike<number> | null | undefined, opts?: RankOptions): Ranked<T>[];
export interface VectorSearchOptions<T> extends RankOptions {
    /** 存向量的字段名，默认 `embedding` */
    field?: string;
    /** 先按业务条件缩小候选（如 `{ userId }`），再算相似度——强烈建议带上 */
    filter?: Filter<T>;
    /** 最多扫描多少条候选，默认 2000（每 200 条一次请求） */
    scanLimit?: number;
}
/**
 * 在 db 集合里做向量检索：分页拉回候选（每页 200 条）→ 进程内算相似度 → 取 topK。
 * 适用规模：单次检索候选 ≤ 2000 条（默认 scanLimit）。更大的知识库请先用 filter 分片，或告知用户当前平台不支持。
 * 返回的文档会去掉向量字段本身（体积大且对调用方无用）。
 */
export declare function vectorSearch<T = Record<string, unknown>>(collection: Collection<T>, query: ArrayLike<number>, opts?: VectorSearchOptions<T>): Promise<Ranked<Doc<T>>[]>;
export interface SplitTextOptions {
    /** 每段最大字符数，默认 500（中文按字算；embedding 模型按 token 计，500 字很安全） */
    chunkSize?: number;
    /** 相邻段重叠字符数，默认 50，保证跨段语义不断裂 */
    overlap?: number;
}
/**
 * 长文本切段（入库前用）：优先在段落 / 句号 / 换行处断开，超长再硬切；相邻段带重叠。
 * 返回的每段都已 trim 且非空。
 */
export declare function splitText(text: string, opts?: SplitTextOptions): string[];