import { IStreamLogger } from '../PSAgentLogger';
import { PSAgentTool } from '../PSAgentTool';
/**
 * Minimum shape for an embedding entity. Consumers extend this with
 * their own fields (metadata, source, timestamps, etc.).
 */
export interface IEmbeddingEntity {
    content: string;
}
/**
 * Anything that can turn text into a vector.
 *
 * `PSAI` satisfies this interface out of the box, but consumers can
 * provide their own OpenAI client, Cohere SDK, local model wrapper, etc.
 */
export interface IEmbeddingProvider {
    embedQuery(text: string): Promise<number[]>;
}
/**
 * A single search result returned by the repository.
 */
export interface IEmbeddingSearchResult<T extends IEmbeddingEntity> {
    /** The matched entity. */
    entity: T;
    /** Similarity score in the range [0, 1] where 1 is an exact match. */
    similarity: number;
}
/**
 * Storage-agnostic repository interface for similarity search.
 *
 * Consumers implement this for their own stack — TypeORM + pgvector,
 * Prisma, Pinecone, Weaviate, in-memory, etc.
 */
export interface IEmbeddingRepository<T extends IEmbeddingEntity> {
    /**
     * Find the `limit` most similar entities to `queryEmbedding`.
     *
     * Implementations must return results ordered by similarity descending
     * and clamp similarity values to [0, 1].
     */
    findSimilar(queryEmbedding: number[], limit: number): Promise<Array<IEmbeddingSearchResult<T>>>;
}
/**
 * Configuration for PSRetrievalTool.
 */
export interface PSRetrievalToolOptions<T extends IEmbeddingEntity = IEmbeddingEntity> {
    /** Repository that performs the actual similarity search. */
    repository: IEmbeddingRepository<T>;
    /** Provider that converts text queries into embedding vectors. */
    embeddingProvider: IEmbeddingProvider;
    /** Default number of results to return (1–20, default: 5). */
    topK?: number;
    /**
     * Override the default tool name (`search_knowledge_base`).
     * Useful when an agent has multiple retrieval tools (docs, tickets, FAQ).
     */
    name?: string;
    /**
     * Override the default tool description.
     */
    description?: string;
    /**
     * Custom result formatter. Receives each entity, its similarity score
     * (0–1), and its 0-based index. Returns a markdown string for that result.
     *
     * When omitted, the default formatter renders content in a code block
     * with a similarity percentage header.
     */
    formatResult?: (entity: T, similarity: number, index: number) => string;
}
/**
 * PSRetrievalTool — A tool for semantic similarity search over embedded
 * documents.
 *
 * The tool is storage-agnostic: consumers provide an {@link IEmbeddingRepository}
 * implementation for their own database/vector store, and an
 * {@link IEmbeddingProvider} for embedding queries.
 *
 * @example
 * ```ts
 * // Basic usage (PSAI implements IEmbeddingProvider)
 * const tool = new PSRetrievalTool({
 *   repository: myEmbeddingRepo,
 *   embeddingProvider: psai,
 * });
 * ```
 *
 * @example
 * ```ts
 * // Multiple retrieval tools with custom names
 * const docsTool = new PSRetrievalTool({
 *   repository: docsRepo,
 *   embeddingProvider: psai,
 *   name: 'search_docs',
 *   description: 'Search the documentation knowledge base.',
 * });
 *
 * const ticketsTool = new PSRetrievalTool({
 *   repository: ticketsRepo,
 *   embeddingProvider: psai,
 *   name: 'search_tickets',
 *   description: 'Search past support tickets.',
 * });
 * ```
 *
 * @example
 * ```ts
 * // Custom result formatting
 * const tool = new PSRetrievalTool({
 *   repository: myRepo,
 *   embeddingProvider: psai,
 *   formatResult: (entity, similarity, index) => {
 *     const meta = (entity as any).metadata || {};
 *     return `**${index + 1}.** [${(similarity * 100).toFixed(0)}%] ${meta.title ?? 'Untitled'}\n${entity.content}\n`;
 *   },
 * });
 * ```
 */
export declare class PSRetrievalTool<T extends IEmbeddingEntity = IEmbeddingEntity> extends PSAgentTool {
    static readonly toolName = "search_knowledge_base";
    private repository;
    private embeddingProvider;
    private topK;
    private formatResult;
    constructor(options: PSRetrievalToolOptions<T>);
    run(input: Record<string, any>, log?: IStreamLogger): Promise<Record<string, any>>;
}