/**
 * Tool-ranker — ranks MCP tool definitions against a natural-language query
 * using BM25 (lexical), exact-name (identity), embedding cosine (semantic),
 * usage frequency (structural), and framework-match (framework) signals.
 *
 * Used by the `plan_turn` / tool-recommendation meta tools to surface the
 * most relevant tools for an agent's current intent.
 *
 * All signals are optional — semantic and structural gracefully degrade to
 * zero when the corresponding input is unavailable (e.g. no embedding API
 * key, fresh session with no usage history).
 */
import { type BM25Index } from "./bm25.js";
import type { ToolDefinition } from "../register-tools.js";
export interface ToolRecommendation {
    name: string;
    confidence: number;
    reasoning: string;
    suggested_params?: Record<string, string>;
    is_hidden: boolean;
}
export interface ToolRankerContext {
    query: string;
    toolDefs: readonly ToolDefinition[];
    embeddings: Map<string, number[]> | null;
    queryEmbedding: number[] | null;
    usageFrequency: Map<string, number>;
    frameworkTools: string[];
    /**
     * Names of tools visible in ListTools (core tools). When provided, tools
     * outside this set are flagged as `is_hidden=true` in the recommendation.
     * Defaults to an empty set → every tool is reported as hidden.
     */
    coreToolNames?: Set<string>;
}
/** Per-signal contributions for a single tool — used for reasoning + debugging. */
interface SignalBreakdown {
    lexical: number;
    identity: number;
    semantic: number;
    structural: number;
    framework: number;
    lexicalTokens: string[];
}
/**
 * Compute a stable fingerprint for a list of tool definitions. Used to
 * invalidate the BM25 cache when the tool catalog is modified (tests,
 * hot-reload, new deployments).
 *
 * Exported for tests that need to predict cache-hit behaviour.
 */
export declare function toolDefsFingerprint(toolDefs: readonly ToolDefinition[]): string;
/**
 * Build (or return cached) BM25 index for a tool catalog. Cache is keyed
 * by fingerprint — subsequent calls with the same shape return instantly.
 */
export declare function buildToolBM25Index(toolDefs: readonly ToolDefinition[]): BM25Index;
/** Clear the BM25 cache — for tests and hot-reload. */
export declare function clearToolBM25Cache(): void;
/**
 * Render a one-line, human-readable reason explaining why this tool was
 * picked. Falls back to a generic "general match" when no signal dominates.
 */
export declare function generateReasoning(id: string, query: string, signals: SignalBreakdown): string;
/**
 * Rank tools against a natural-language query by combining lexical, identity,
 * semantic, structural, and framework signals. Returns up to 10 `ToolRecommendation`
 * entries sorted by raw weighted score, with calibrated confidence values.
 *
 * Gracefully handles missing inputs:
 *   - no embeddings           → semantic contribution is 0
 *   - empty usageFrequency    → structural contribution is 0
 *   - empty frameworkTools    → framework contribution is 0
 */
export declare function rankTools(ctx: ToolRankerContext): ToolRecommendation[];
/** Absolute path to the on-disk tool-embedding cache. */
export declare function getToolEmbeddingCachePath(): string;
/**
 * Fetch (or compute) embeddings for every tool in `defs`. Uses the on-disk
 * cache when the fingerprint matches; otherwise regenerates via the configured
 * embedding provider and persists the result.
 *
 * Returns:
 *   - `Map<toolName, number[]>` on success
 *   - `null` when no embedding provider is configured (no API key) or the
 *     provider call fails — callers should degrade to non-semantic ranking.
 */
export declare function getToolEmbeddings(defs: readonly ToolDefinition[]): Promise<Map<string, number[]> | null>;
export {};
//# sourceMappingURL=tool-ranker.d.ts.map