/**
 * KnowledgeProvider — Runtime-level knowledge orchestrator.
 *
 * Implements three-layer retrieval:
 * - Layer 1 (compiled): Stable knowledge injected into system prompt (0ms)
 * - Layer 2 (cache): Semantic cache lookup via document embeddings (~0.4ms)
 * - Layer 3 (search): Hybrid search via configured retriever (50-150ms)
 *
 * Configured once on the Runtime, inherited by all agents. Per-agent
 * overrides restrict capabilities (filter, topK, disable compiled/tool).
 *
 * The provider holds no mutable state itself — per-session cache state is
 * stored on RunContext.retrievalCache so it survives agent handoffs.
 */
import type { KnowledgeProviderConfig, AgentKnowledgeOverrides, KnowledgeRetrievalResult, HarnessStreamPart, RetrievalCacheAdapter } from '../types/index.js';
export type { RetrievalCacheAdapter } from '../types/index.js';
interface ResolvedKnowledgeConfig {
    compiledEnabled: boolean;
    compiled: string | undefined;
    toolEnabled: boolean;
    topK: number;
    maxOutputTokens: number;
    includeEmbeddings: boolean;
    filter?: Record<string, unknown>;
}
/**
 * Factory function that creates a session-level cache instance.
 * Provided by the integrator so that `@ariaflowagents/core` does not
 * depend on `@ariaflowagents/rag`.
 */
export type RetrievalCacheFactory = () => RetrievalCacheAdapter;
export interface KnowledgeProviderOptions {
    config: KnowledgeProviderConfig;
    /** Factory for creating per-session cache instances. */
    cacheFactory?: RetrievalCacheFactory;
}
export declare class KnowledgeProvider {
    private readonly config;
    private readonly retriever;
    private readonly embedder;
    private readonly cacheFactory;
    constructor(options: KnowledgeProviderOptions);
    /**
     * Create a new session-level cache instance. Called once per session
     * in IntakeStage, stored on RunContext.retrievalCache.
     */
    createSessionCache(): RetrievalCacheAdapter | undefined;
    /**
     * Resolve effective knowledge config by merging Runtime-level config
     * with per-agent overrides. Agent overrides can only reduce capabilities.
     */
    resolveConfig(agentOverrides?: AgentKnowledgeOverrides): ResolvedKnowledgeConfig;
    /**
     * Get compiled knowledge text for system prompt injection (Layer 1).
     * Returns undefined if compiled knowledge is not configured or disabled.
     */
    getCompiledKnowledge(agentOverrides?: AgentKnowledgeOverrides): string | undefined;
    /**
     * Run layered retrieval for a user query.
     *
     * Order: cache lookup → hybrid search (on cache miss) → quality check.
     * Results are written back to the cache for future turns.
     *
     * @param query - The user's query text.
     * @param cache - Session-level retrieval cache (may be undefined).
     * @param agentOverrides - Per-agent overrides for knowledge config.
     * @param isVoice - Whether this is a voice agent. Voice agents never
     *   block on reformulation — background reformulation is signalled instead.
     * @returns Results and observability events.
     */
    retrieve(query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<{
        results: KnowledgeRetrievalResult[];
        events: HarnessStreamPart[];
    }>;
    /**
     * Run quality check on retrieval results and optionally reformulate.
     * Sub-millisecond for the score check; reformulation adds latency only
     * for text agents with low-quality results.
     */
    private runQualityCheck;
    /** Whether this provider has a retriever configured. */
    get hasRetriever(): boolean;
    /** Whether this provider has compiled knowledge. */
    get hasCompiled(): boolean;
    /** Whether predictive pre-fetch is enabled. */
    get prefetchEnabled(): boolean;
    /** Get pre-fetch config. */
    get prefetchConfig(): KnowledgeProviderConfig['prefetch'];
}