Knowledge

export interface HybridSearchConfig {
    /** Weight for vector (semantic) results in RRF. Default 1.0. */
    vectorWeight?: number;
    /** Weight for keyword (BM25) results in RRF. Default 1.0. */
    keywordWeight?: number;
    /** RRF constant k. Higher = less rank-sensitive. Default 60. */
    rrfK?: number;
}

export declare class KnowledgeBase {
    readonly name: string;
    readonly collection: string;
    constructor(config: KnowledgeBaseConfig);
    initialize(): Promise<void>;
    add(doc: VectorDocument): Promise<void>;
    addDocuments(docs: VectorDocument[]): Promise<void>;
    search(query: string, options?: VectorSearchOptions & {
        searchMode?: SearchMode;
    }): Promise<VectorSearchResult[]>;
    get(id: string): Promise<VectorDocument | null>;
    delete(id: string): Promise<void>;
    clear(): Promise<void>;
    close(): Promise<void>;
    /**
     * Returns a ToolDef that an Agent can use to search this knowledge base.
     * Plug the result directly into `Agent({ tools: [kb.asTool()] })`.
     */
    asTool(config?: KnowledgeBaseToolConfig): ToolDef;
}

export interface KnowledgeBaseConfig {
    /** Display name used in tool description auto-generation. */
    name: string;
    /** The underlying vector store (any backend). */
    vectorStore: VectorStore;
    /** Collection/index name inside the vector store. */
    collection?: string;
    /**
     * Default search mode.
     * - `"vector"` — pure semantic (embedding) search (default, backward-compatible)
     * - `"keyword"` — pure BM25 keyword search
     * - `"hybrid"` — combines vector + keyword via Reciprocal Rank Fusion
     */
    searchMode?: SearchMode;
    /** Fine-tune hybrid search behavior. */
    hybridConfig?: HybridSearchConfig;
}

export interface KnowledgeBaseToolConfig {
    /** Tool name exposed to the LLM. Defaults to `search_<collection>`. */
    toolName?: string;
    /** Custom tool description. A sensible default is generated from the KB name. */
    description?: string;
    /** Number of results to return per search. Default 5. */
    topK?: number;
    /** Minimum similarity score to include. */
    minScore?: number;
    /** Metadata filter applied to every search. */
    filter?: Record<string, unknown>;
    /** Override the search mode for this tool. Inherits from KB config if not set. */
    searchMode?: SearchMode;
    /** Custom formatter for search results. Defaults to numbered list with scores. */
    formatResults?: (results: VectorSearchResult[]) => string;
}

export type SearchMode = "vector" | "keyword" | "hybrid";