import type { ToolDef } from './tools.js';
import type { JsonObject } from './types.js';
/**
 * Generic, provider-agnostic retrieval seam. RAG is query-time, so it does NOT fit `FilesystemSource`
 * (an eager full-dump mount) — a retriever resolves the top matches for a query on demand. Databricks
 * AI Search is the flagship implementation, but this is reusable for any vector store.
 */
export interface RetrievedChunk {
    /** Stable id of the source chunk, when the index exposes one. */
    id?: string;
    /** The chunk text returned to the model. */
    text: string;
    /** Relevance score (higher = more relevant), when the index exposes one. */
    score?: number;
    /** Any additional columns/fields returned by the index. */
    metadata?: JsonObject;
}
export interface RetrieveOptions {
    /** Number of chunks to return. */
    k?: number;
    /** Provider-specific filter (e.g. a metadata predicate). */
    filter?: JsonObject;
    signal?: AbortSignal;
}
export interface Retriever {
    /** Stable name for telemetry / logs. */
    readonly name?: string;
    retrieve(query: string, options?: RetrieveOptions): Promise<RetrievedChunk[]>;
}
/**
 * Embeddings seam. Feeds self-managed-embedding vector indexes (embed the query → query vector) and
 * any bring-your-own retrieval pipeline. Returns one vector per input text, order-preserving.
 */
export interface EmbeddingProvider {
    readonly name?: string;
    embed(texts: string[], options?: {
        signal?: AbortSignal;
    }): Promise<number[][]>;
}
export interface SearchToolOptions {
    /** Tool name exposed to the model. Default `search`. */
    name?: string;
    description?: string;
    /** Default `k` when the model doesn't specify one. Default 5. */
    defaultK?: number;
    /** Merged into the tool's metadata (e.g. `{ provider, service }`). `effect: 'read'` is set by default. */
    metadata?: JsonObject;
}
export interface SearchToolInput {
    query: string;
    k?: number;
}
export interface SearchToolResult {
    results: RetrievedChunk[];
}
/**
 * Exposes a {@link Retriever} to the model as a `search` tool. The tool is read-only; wrap it with a
 * governance decorator to stamp lineage or route approvals.
 */
export declare function createSearchTool(retriever: Retriever, options?: SearchToolOptions): ToolDef<SearchToolInput, SearchToolResult>;
//# sourceMappingURL=retrieval.d.ts.map