/**
 * Tool Selection Strategy Module
 *
 * Encapsulates the logic for selecting relevant tools for a given query.
 * Extracted from CodeBuddyAgent to improve modularity and testability.
 *
 * Features:
 * - RAG-based semantic tool selection
 * - Fallback to full tool set when RAG is disabled
 * - Tool filtering based on query classification
 * - Tool caching for multi-round consistency
 * - Selection metrics and monitoring
 *
 * Based on research from:
 * - RAG-MCP (arXiv:2505.03275)
 * - ToolLLM (ICLR'24)
 */
import type { CodeBuddyTool } from '../../codebuddy/client.js';
import type { ToolCategory, QueryClassification, ToolSelectionResult, ToolSelectionMetrics } from '../../tools/types.js';
import type { UnifiedSkill } from '../../skills/types.js';
export type { ToolCategory, QueryClassification, ToolSelectionResult, ToolSelectionMetrics, };
/**
 * Configuration options for tool selection strategy
 */
export interface ToolSelectionConfig {
    /** Enable RAG-based tool selection (default: true) */
    useRAG: boolean;
    /** Maximum number of tools to select (default: 15) */
    maxTools: number;
    /** Minimum score threshold for tool inclusion (default: 0.5) */
    minScore: number;
    /** Tool names that should always be included (default: core tools) */
    alwaysInclude: string[];
    /** Enable adaptive threshold based on success metrics (default: true) */
    useAdaptiveThreshold: boolean;
    /** Enable caching of selected tools for multi-round consistency (default: true) */
    enableCaching: boolean;
    /** Cache TTL in milliseconds (default: 5 minutes) */
    cacheTTLMs: number;
}
/**
 * Result of a tool selection operation
 */
export interface SelectionResult {
    /** The selected tools */
    tools: CodeBuddyTool[];
    /** The detailed selection result (null if RAG disabled) */
    selection: ToolSelectionResult | null;
    /** Whether tools were served from cache */
    fromCache: boolean;
    /** The query used for selection */
    query: string;
    /** Selection timestamp */
    timestamp: Date;
}
/**
 * Tool Selection Strategy
 *
 * Manages the selection of relevant tools for user queries using
 * RAG-based semantic matching or fallback strategies.
 *
 * @example
 * ```typescript
 * const strategy = new ToolSelectionStrategy();
 *
 * // Select tools for a query
 * const result = await strategy.selectToolsForQuery('read package.json');
 * console.log(result.tools.map(t => t.function.name));
 *
 * // Cache tools for multi-round consistency
 * strategy.cacheTools(result.tools);
 *
 * // Get cached tools in subsequent rounds
 * const cached = strategy.getCachedTools();
 * ```
 */
export declare class ToolSelectionStrategy {
    private config;
    private cachedTools;
    private cachedToolNames;
    private lastQuery;
    private lastSelection;
    private cacheTimestamp;
    private activeSkill;
    /**
     * Create a new ToolSelectionStrategy instance
     *
     * @param config - Optional configuration overrides
     */
    constructor(config?: Partial<ToolSelectionConfig>);
    /**
     * Select relevant tools for a given query
     *
     * Uses RAG-based selection when enabled, otherwise returns all tools.
     * Results are cached for prompt optimization.
     *
     * @param query - The user's query
     * @param options - Optional overrides for this selection
     * @returns Selection result with tools and metadata
     */
    selectToolsForQuery(query: string, options?: Partial<ToolSelectionConfig>): Promise<SelectionResult>;
    /**
     * Cache tools for multi-round consistency
     *
     * Caching tools after the first round ensures consistent tool availability
     * throughout a conversation, saving ~9000 tokens on multi-round queries.
     *
     * @param tools - Tools to cache
     */
    cacheTools(tools: CodeBuddyTool[]): void;
    /**
     * Get cached tools if available and valid
     *
     * @returns Cached tools or null if cache is invalid/empty
     */
    getCachedTools(): CodeBuddyTool[] | null;
    /**
     * Set the active skill for tool augmentation.
     *
     * When set, `selectToolsForQuery` will ensure all tools required by the
     * skill are included in the selection, even if RAG filtering would have
     * excluded them.
     *
     * @param skill - The matched UnifiedSkill, or null to clear
     */
    setActiveSkill(skill: UnifiedSkill | null): void;
    /**
     * Get the currently active skill
     */
    getActiveSkill(): UnifiedSkill | null;
    /**
     * Clear the tool cache
     *
     * Should be called at the start of a new conversation turn.
     */
    clearCache(): void;
    /**
     * Check if the cache is still valid
     */
    private isCacheValid;
    /**
     * Record a tool request for metrics tracking
     *
     * Call this when the LLM requests a tool to track whether
     * our selection correctly included it.
     *
     * @param toolName - The tool name requested by LLM
     */
    recordToolRequest(toolName: string): void;
    /**
     * Get selection metrics for monitoring and debugging
     */
    getSelectionMetrics(): ToolSelectionMetrics;
    /**
     * Format metrics as a readable string
     */
    formatSelectionMetrics(): string;
    /**
     * Get the last tool selection result
     */
    getLastSelection(): ToolSelectionResult | null;
    /**
     * Get the last query used for tool selection
     */
    getLastQuery(): string;
    /**
     * Get the names of currently cached tools
     */
    getCachedToolNames(): string[];
    /**
     * Check if a query should use web search
     *
     * Heuristic: enable web search only when likely needed based on
     * keywords indicating recency, current events, or external data.
     *
     * @param message - The user's message
     * @returns Whether web search should be enabled
     */
    shouldUseSearchFor(message: string): boolean;
    /**
     * Classify a query to understand what types of tools might be needed
     *
     * @param query - The user's query
     * @returns Classification result with categories and confidence
     */
    classifyQuery(query: string): QueryClassification;
    /**
     * Get most frequently missed tools for debugging
     *
     * @param limit - Maximum number of tools to return
     */
    getMostMissedTools(limit?: number): Array<{
        tool: string;
        count: number;
    }>;
    /**
     * Get cache statistics
     */
    getCacheStats(): {
        hasCachedTools: boolean;
        cachedToolCount: number;
        cacheAge: number;
        isValid: boolean;
        classificationCache: {
            size: number;
        };
        selectionCache: {
            size: number;
        };
    };
    /**
     * Reset metrics to initial state
     */
    resetMetrics(): void;
    /**
     * Clear all caches (both local and selector caches)
     */
    clearAllCaches(): void;
    /**
     * Update configuration
     *
     * @param config - Partial configuration to merge
     */
    updateConfig(config: Partial<ToolSelectionConfig>): void;
    /**
     * Get current configuration
     */
    getConfig(): Readonly<ToolSelectionConfig>;
    /**
     * Format a summary of the last tool selection
     */
    formatLastSelectionStats(): string;
}
/**
 * Get the global ToolSelectionStrategy instance
 *
 * @param config - Optional configuration for first initialization
 * @returns The singleton instance
 */
export declare function getToolSelectionStrategy(config?: Partial<ToolSelectionConfig>): ToolSelectionStrategy;
/**
 * Reset the singleton instance (useful for testing)
 */
export declare function resetToolSelectionStrategy(): void;
