/**
 * SmartAgentBuilder — fluent builder for SmartAgent.
 *
 * Assembles a SmartAgent from interface-based components.
 * The builder itself has NO knowledge of concrete providers —
 * all dependencies must be injected via `withXxx()` methods or
 * resolved externally by the composition root (SmartServer, CLI).
 *
 * Usage:
 *   const handle = await new SmartAgentBuilder()
 *     .withMainLlm(myLlm)
 *     .setToolsRag(myRag)
 *     .build();
 */
import type { IClientAdapter, IContextAssembler, ICoordinatorConfig, IHistoryMemory, IHistorySummarizer, ILlm, ILlmApiAdapter, ILlmCallStrategy, ILlmRateLimiter, ILogger, IMcpClient, IMcpFailureClassifier, IMcpRequestHeadersStrategy, IModelProvider, IQueryExpander, IRequestLogger, ISkillManager, ISubAgent, ISubpromptClassifier, IToolCache, IToolSelectionStrategy, McpConnectionConfig, SubAgentRegistry, ToolLoopContextStrategyFactory } from '@mcp-abap-adt/llm-agent';
import { type CircuitBreakerConfig, type IEmbedder, type IRag, type IRagEditor, type IRagProvider, type IRagProviderRegistry, type IRagRegistry, type RagCollectionMeta, type RagCollectionScope } from '@mcp-abap-adt/llm-agent';
import { SmartAgent, type SmartAgentConfig } from './agent.js';
import type { BuilderMcpConfig, SmartAgentBuilderConfig, SmartAgentHandle } from './builder-types.js';
import type { IMcpConnectionStrategy } from './interfaces/mcp-connection-strategy.js';
import type { IPipeline } from './interfaces/pipeline.js';
import type { IMetrics } from './metrics/types.js';
import type { DagCoordinatorHandlerDeps } from './pipeline/handlers/dag-coordinator.js';
import type { IStageHandler } from './pipeline/stage-handler.js';
import type { IPluginLoader } from './plugins/types.js';
import type { IPromptInjectionDetector, IToolPolicy } from './policy/types.js';
import type { IReranker } from './reranker/types.js';
import type { ISessionManager } from './session/types.js';
import type { ITracer } from './tracer/types.js';
import type { IOutputValidator } from './validator/types.js';
export type { BuilderMcpConfig, BuilderPromptsConfig, SmartAgentBuilderConfig, SmartAgentHandle, } from './builder-types.js';
/**
 * Assemble the {@link McpConnectionConfig} array from the builder's `mcp`
 * config and attach an optional {@link IMcpRequestHeadersStrategy} to each
 * entry. Exported for unit-testing; not part of the public package barrel.
 */
export declare function prepareMcpConfigs(mcp: BuilderMcpConfig | BuilderMcpConfig[] | undefined, requestHeadersStrategy?: IMcpRequestHeadersStrategy): McpConnectionConfig[];
export declare class SmartAgentBuilder {
    private readonly cfg;
    private _mainLlm?;
    private _helperLlm?;
    private _classifierLlm?;
    private _onBeforeStream?;
    private _toolsRag?;
    private _historyRag?;
    private _pipeline?;
    private _mcpClients?;
    private _classifier?;
    private _assembler?;
    private _logger?;
    private _toolPolicy?;
    private _injectionDetector?;
    private _tracer?;
    private _metrics?;
    private _reranker?;
    private _queryExpander?;
    private _toolCache?;
    private _outputValidator?;
    private _sessionManager?;
    private _circuitBreakerConfig?;
    private _requestLogger?;
    private _agentOverrides;
    private _pluginLoader?;
    private _skillManager?;
    private _clientAdapters;
    private _apiAdapters;
    private _modelProvider?;
    private _embedder?;
    private _toolSelectionStrategy?;
    private _connectionStrategy?;
    private _mcpRequestHeadersStrategy?;
    private _mcpFailureClassifier?;
    private _toolLoopContextStrategyFactory?;
    private _subAgents?;
    private _coordinator?;
    private _dagCoordinator?;
    private _stepperCoordinator?;
    private _historySummarizer?;
    private _historyMemory?;
    private _llmCallStrategy?;
    private _rateLimiter?;
    private _providers;
    private _staticCollections;
    private _pendingDynamicCollections;
    private _ragRegistry?;
    private _ragProviderRegistry?;
    constructor(cfg?: SmartAgentBuilderConfig);
    /** Set the main LLM used in the tool loop (required). */
    withMainLlm(llm: ILlm): this;
    /** Set a model provider for model discovery and metadata. */
    withModelProvider(provider: IModelProvider): this;
    /** Set the helper LLM used for summarization and translation. */
    withHelperLlm(llm: ILlm): this;
    /** Set the LLM used by the intent classifier. If not set, mainLlm is used. */
    withClassifierLlm(llm: ILlm): this;
    /** Register a hook called before streaming the final response to the client. */
    withOnBeforeStream(hook: SmartAgentConfig['onBeforeStream']): this;
    /** Inject a custom RAG store for MCP tool selection. Overrides auto-created in-memory store. */
    setToolsRag(rag: IRag): this;
    /** Inject a custom RAG store for conversation history. Overrides auto-created in-memory store. */
    setHistoryRag(rag: IRag): this;
    /** Register an IRagProvider for dynamic collection creation. */
    addRagProvider(provider: IRagProvider): this;
    /** Register a static (pre-built) RAG collection by name. */
    addRagCollection(params: {
        name: string;
        rag: IRag;
        editor?: IRagEditor;
        meta?: Omit<RagCollectionMeta, 'name' | 'editable'>;
        /** Opt-in idempotency for callers re-run across per-session builds against a
         *  shared registry (e.g. skills wiring): skip silently if `name` is already
         *  registered. Default unset → duplicate names fail loud as before. */
        idempotent?: boolean;
    }): this;
    /** Queue a dynamic collection to be created via a provider during build(). */
    createRagCollection(params: {
        providerName: string;
        collectionName: string;
        scope: RagCollectionScope;
        sessionId?: string;
        userId?: string;
        displayName?: string;
        description?: string;
        tags?: readonly string[];
    }): this;
    /** Provide a custom IRagRegistry. Defaults to SimpleRagRegistry if not set. */
    setRagRegistry(registry: IRagRegistry): this;
    /** Provide a custom IRagProviderRegistry. Defaults to SimpleRagProviderRegistry if not set. */
    setRagProviderRegistry(registry: IRagProviderRegistry): this;
    /** Inject a pipeline implementation. Defaults to DefaultPipeline if not set. */
    setPipeline(pipeline: IPipeline): this;
    /**
     * Override MCP clients. When set, auto-connect and tool vectorization
     * are skipped — the caller is responsible for connecting clients.
     */
    withMcpClients(clients: IMcpClient[]): this;
    /** Override the intent classifier. */
    withClassifier(classifier: ISubpromptClassifier): this;
    /** Override the context assembler. */
    withAssembler(assembler: IContextAssembler): this;
    /** Set a logger for internal pipeline events. */
    withLogger(logger: ILogger): this;
    /** Set a tool execution policy (allow/deny list). */
    withToolPolicy(policy: IToolPolicy): this;
    /** Set a prompt-injection detector. */
    withInjectionDetector(detector: IPromptInjectionDetector): this;
    /** Set a tracer for pipeline span instrumentation. */
    withTracer(tracer: ITracer): this;
    /** Set a metrics collector for pipeline instrumentation. */
    withMetrics(metrics: IMetrics): this;
    /** Set a reranker to re-score RAG results before context assembly. */
    withReranker(reranker: IReranker): this;
    /** Set a query expander to broaden RAG queries with synonyms/related terms. */
    withQueryExpander(expander: IQueryExpander): this;
    /** Set a tool result cache for MCP call deduplication. */
    withToolCache(cache: IToolCache): this;
    /** Set an output validator for post-LLM response validation. */
    withOutputValidator(validator: IOutputValidator): this;
    /** Set a session manager for multi-turn token budget tracking. */
    withSessionManager(manager: ISessionManager): this;
    /** Set a skill manager for discovering and loading agent skills. */
    withSkillManager(manager: ISkillManager): this;
    /** Register a client adapter for auto-detecting prompt-based clients. */
    withClientAdapter(adapter: IClientAdapter): this;
    /** Register an API adapter. When called multiple times with the same name, the last one wins. */
    withApiAdapter(adapter: ILlmApiAdapter): this;
    /** Enable circuit breakers for LLM and embedder calls. */
    withCircuitBreaker(config?: CircuitBreakerConfig): this;
    /** Set the shared embedder for RAG queries. When set, queries embed once and share the vector. */
    withEmbedder(embedder: IEmbedder): this;
    /** Set the strategy that filters scored RAG results for tool exposure. */
    withToolSelectionStrategy(strategy: IToolSelectionStrategy): this;
    /** Set a request logger for per-model usage tracking. */
    withRequestLogger(logger: IRequestLogger): this;
    /** Set an MCP connection strategy for dynamic client management. */
    withMcpConnectionStrategy(strategy: IMcpConnectionStrategy): this;
    /** Attach a consumer-owned headers strategy to every MCP connection the
     *  builder assembles from the `mcp:` config. The strategy is propagated to
     *  each {@link McpConnectionConfig} entry so the MCP transport can merge the
     *  returned headers into its request init. Default = no-op (nothing attached). */
    withMcpRequestHeadersStrategy(strategy: IMcpRequestHeadersStrategy): this;
    /** Inject a custom MCP failure classifier. The classifier decides whether a
     *  failed tool-call result is an availability escalation (fail loud) or a
     *  tool-level error (LLM feedback). Default: DefaultMcpFailureClassifier. */
    withMcpFailureClassifier(classifier: IMcpFailureClassifier): this;
    /** Inject a per-loop tool-loop context strategy factory. When absent, resolved to
     *  Legacy (LegacyAccumulateContextStrategy) at point-of-use. */
    withToolLoopContextStrategyFactory(factory: ToolLoopContextStrategyFactory): this;
    /** Override the history summarizer used for semantic history compression. */
    withHistorySummarizer(summarizer: IHistorySummarizer): this;
    /** Set a rate limiter to throttle outbound LLM requests. */
    withRateLimiter(limiter: ILlmRateLimiter): this;
    /** Set the LLM call strategy for tool-loop (streaming, non-streaming, or fallback). */
    withLlmCallStrategy(strategy: ILlmCallStrategy): this;
    /** Override the history memory store used for semantic history retrieval. */
    withHistoryMemory(memory: IHistoryMemory): this;
    /** Set the execution mode: 'smart' (full pipeline), 'hard' (MCP-only), 'pass' (direct LLM). */
    withMode(mode: 'hard' | 'pass' | 'smart'): this;
    /** Set the maximum number of tool-loop iterations. */
    withMaxIterations(n: number): this;
    /** Set the maximum number of tool calls per request. */
    withMaxToolCalls(n: number): this;
    /** Set the request timeout in milliseconds. */
    withTimeout(ms: number): this;
    /** Set the number of RAG results to retrieve per store. */
    withRagQueryK(k: number): this;
    /**
     * Register a sub-agent registry. When provided (and non-empty), the default
     * pipeline wires in a `sub_agent_call` tool that dispatches to these agents.
     */
    withSubAgents(registry: SubAgentRegistry): this;
    /**
     * Enable the coordinator orchestration mode. When set, the pipeline swaps
     * the tool-loop stage for a plan-then-dispatch stage.
     *
     * Activation defaults to {@link ExplicitActivation} — calling this method is
     * itself the opt-in signal. Pass `activation: new AutoActivation()` if you
     * want graceful degradation back to `tool-loop` when neither subagents nor a
     * structured skill are present at request time.
     */
    withCoordinator(cfg?: ICoordinatorConfig): this;
    /**
     * Enable DAG coordinator mode. Mutually exclusive with {@link withCoordinator}
     * — when both are called, `withDagCoordinator` takes precedence (DAG wins).
     *
     * The `deps.workers` map provides the sub-agents the DAG interpreter will
     * dispatch to. Pass the same registry you supply to `withSubAgents()`.
     */
    withDagCoordinator(deps: DagCoordinatorHandlerDeps): this;
    /**
     * Enable 18.0 Stepper coordinator mode. The caller constructs a
     * `StepperCoordinatorHandler` and passes it in; it is registered under the
     * `coordinator` stage slot (taking precedence over `withDagCoordinator` and
     * `withCoordinator`). The activation strategy defaults to `ExplicitActivation`.
     */
    withStepperCoordinator(handler: IStageHandler): this;
    /**
     * Register a single sub-agent by name. Sugar for incremental registry
     * building — avoids constructing a Map manually when adding one agent at a
     * time. Accepts either a raw `ISubAgent` or a `SmartAgent` instance (which
     * is automatically wrapped in `SmartAgentSubAgent`).
     */
    withSubAgent(name: string, agent: SmartAgent | ISubAgent, opts?: {
        description?: string;
    }): this;
    /** Enable or disable query expansion for RAG queries. */
    withQueryExpansion(enabled: boolean): this;
    /** Enable or disable reasoning/strategy blocks in the response. */
    withShowReasoning(enabled: boolean): this;
    /** Set the SSE heartbeat interval in milliseconds during tool execution. */
    withHeartbeatInterval(ms: number): this;
    /** Set the health check probe timeout in milliseconds. Default: 5000. */
    withHealthTimeout(ms: number): this;
    /** Enable or disable the classification pipeline stage. When disabled, input is treated as a single action. */
    withClassification(enabled: boolean): this;
    /** Enable per-iteration RAG-based tool re-selection in the tool loop. */
    withToolReselection(enabled: boolean): this;
    /** Set the history message count threshold for auto-summarization. */
    withHistorySummarization(limit: number): this;
    /** Set the session token budget for multi-turn conversations. */
    withSessionTokenBudget(budget: number): this;
    /**
     * Set a plugin loader for automatic plugin discovery.
     *
     * During `build()`, the loader's `load()` method is called and all
     * discovered registrations are applied to the builder (stage handlers,
     * embedder factories, reranker, query expander, output validator).
     *
     * The library ships {@link FileSystemPluginLoader} as the default.
     * Consumers can provide their own `IPluginLoader` implementation to
     * load plugins from npm packages, remote registries, or any other source.
     *
     * Explicit `withReranker()`, etc. calls take
     * precedence over plugin-loaded registrations.
     *
     * @example Filesystem (default)
     * ```ts
     * import { FileSystemPluginLoader, getDefaultPluginDirs } from '@mcp-abap-adt/llm-agent';
     * builder.withPluginLoader(new FileSystemPluginLoader({
     *   dirs: getDefaultPluginDirs(),
     * }));
     * ```
     *
     * @example Custom npm loader
     * ```ts
     * builder.withPluginLoader(new NpmPluginLoader(['my-plugin-a']));
     * ```
     */
    withPluginLoader(loader: IPluginLoader): this;
    /**
     * Wraps an `IRag` + `IEmbedder` pair into a thin retrieval callback that
     * `DefaultSubAgentContextBuilder` can consume. Returns `undefined` when
     * either piece is missing so the context builder simply skips that source.
     */
    private buildRetrievalSource;
    build(): Promise<SmartAgentHandle>;
}
//# sourceMappingURL=builder.d.ts.map