@mcp-abap-adt/llm-agent-libs 12.0.2 → 12.0.4

package/dist/agent.d.ts

@@ -0,0 +1,227 @@
+import type { CallOptions, IClientAdapter, IContextAssembler, IEmbedder, IHistoryMemory, IHistorySummarizer, ILlm, ILlmCallStrategy, IMcpClient, IRag, IRagProviderRegistry, IRagRegistry, IRequestLogger, ISkillManager, ISubpromptClassifier, IToolCache, LlmStreamChunk, Message, Result, StreamHookContext } from '@mcp-abap-adt/llm-agent';
+import { type AgentCallOptions, type IQueryExpander, OrchestratorError, type SmartAgentResponse } from '@mcp-abap-adt/llm-agent';
+import type { LlmClassifierConfig } from './classifier/llm-classifier.js';
+import type { IMcpConnectionStrategy } from './interfaces/mcp-connection-strategy.js';
+export { type AgentCallOptions, OrchestratorError, type SmartAgentResponse, type StopReason, } from '@mcp-abap-adt/llm-agent';
+import type { IPipeline } from './interfaces/pipeline.js';
+import type { ILogger } from './logger/index.js';
+import type { IMetrics } from './metrics/types.js';
+import type { IPromptInjectionDetector, IToolPolicy, SessionPolicy } 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 SmartAgentRagStores<K extends string = string> = Record<K, IRag>;
+export interface SmartAgentDeps {
+    mainLlm: ILlm;
+    helperLlm?: ILlm;
+    mcpClients: IMcpClient[];
+    ragStores: SmartAgentRagStores;
+    classifier: ISubpromptClassifier;
+    classifierLlm?: ILlm;
+    classifierConfig?: LlmClassifierConfig;
+    assembler: IContextAssembler;
+    reranker?: IReranker;
+    queryExpander?: IQueryExpander;
+    logger?: ILogger;
+    requestLogger?: IRequestLogger;
+    toolPolicy?: IToolPolicy;
+    injectionDetector?: IPromptInjectionDetector;
+    tracer?: ITracer;
+    metrics?: IMetrics;
+    toolCache?: IToolCache;
+    outputValidator?: IOutputValidator;
+    sessionManager?: ISessionManager;
+    skillManager?: ISkillManager;
+    clientAdapters?: IClientAdapter[];
+    /** Shared embedder for RAG queries. When set, creates memoized IQueryEmbedding per request. */
+    embedder?: IEmbedder;
+    connectionStrategy?: IMcpConnectionStrategy;
+    historyMemory?: IHistoryMemory;
+    historySummarizer?: IHistorySummarizer;
+    llmCallStrategy?: ILlmCallStrategy;
+    pipeline?: IPipeline;
+    /**
+     * Names of RAG stores whose content is English-only (e.g. MCP tool descriptions).
+     * The pipeline translates the query to English before searching these stores.
+     */
+    translateQueryStores?: Set<string>;
+    /** Registry of RAG collections (v9.1+). When present, ragStores is a live projection. */
+    ragRegistry?: IRagRegistry;
+    /** Registry of RAG providers for dynamic collection creation (v9.1+). */
+    ragProviderRegistry?: IRagProviderRegistry;
+}
+export interface SmartAgentConfig {
+    maxIterations: number;
+    maxToolCalls?: number;
+    toolUnavailableTtlMs?: number;
+    timeoutMs?: number;
+    tokenLimit?: number;
+    ragQueryK?: number;
+    contextBudgetTokens?: number;
+    semanticHistoryEnabled?: boolean;
+    historyRecencyWindow?: number;
+    historyTurnSummaryPrompt?: string;
+    smartAgentEnabled?: boolean;
+    sessionPolicy?: SessionPolicy;
+    showReasoning?: boolean;
+    ragTranslatePrompt?: string;
+    historySummaryPrompt?: string;
+    historyAutoSummarizeLimit?: number;
+    mode?: 'hard' | 'pass' | 'smart';
+    queryExpansionEnabled?: boolean;
+    toolResultCacheTtlMs?: number;
+    sessionTokenBudget?: number;
+    /** Interval (ms) for SSE heartbeat comments during MCP tool execution. Default: 5000. */
+    heartbeatIntervalMs?: number;
+    /** Timeout (ms) for health-check probes (LLM, RAG, MCP). Default: 5000. */
+    healthTimeoutMs?: number;
+    /**
+     * Whether classification stage runs. Default: false.
+     * When false, input is treated as a single action — LLM handles
+     * multi-step requests via the tool loop.
+     * Enable when using custom pipeline with multi-store routing.
+     */
+    classificationEnabled?: boolean;
+    /** Whether to inject matched skills into the system prompt. Default: true (when skillManager is configured). */
+    skillInjectionEnabled?: boolean;
+    /**
+     * Whether to re-fetch MCP tool list on each tool-loop iteration. Default: true.
+     * @deprecated No-op since 2.15.0 — tool lists are cached in McpClientAdapter.
+     */
+    refreshToolsPerIteration?: boolean;
+    /** Re-select tools via RAG on each tool-loop iteration. Default: false. */
+    toolReselectPerIteration?: boolean;
+    /** Whether to translate non-ASCII RAG queries to English before retrieval. Default: true. */
+    ragTranslateEnabled?: boolean;
+    /**
+     * Enable two-phase tool retrieval: other RAG stores are queried first, then
+     * `build-tool-query` composes an enriched query from RAG snippets and
+     * selected skills, which drives a second `rag-query` against the tools
+     * store (and the `tool-select` fallback). Lets skills and domain facts
+     * steer MCP tool discovery. Default: false (single-phase tool retrieval).
+     */
+    enrichedToolSearch?: boolean;
+    /** Retry options for transient LLM failures (429, 5xx). When set, wraps LLM with RetryLlm. */
+    retry?: {
+        maxAttempts?: number;
+        backoffMs?: number;
+        retryOn?: number[];
+        retryOnMidStream?: string[];
+    };
+    /**
+     * Streaming behavior for multi-iteration tool loops.
+     * - `'full'` (default): stream all chunks immediately, including intermediate iterations.
+     * - `'final'`: buffer intermediate iterations; only stream the final response.
+     * External tool calls and heartbeats are always streamed regardless of mode.
+     */
+    streamMode?: 'full' | 'final';
+    /** Called before streaming the final response. Consumer can transform or pass through. */
+    onBeforeStream?: (content: string, ctx: StreamHookContext) => AsyncIterable<string>;
+}
+export interface SmartAgentReconfigureOptions {
+    mainLlm?: ILlm;
+    classifierLlm?: ILlm;
+    helperLlm?: ILlm;
+}
+export declare class SmartAgent {
+    private readonly deps;
+    private config;
+    private readonly toolAvailabilityRegistry;
+    private readonly tracer;
+    private readonly metrics;
+    private readonly reranker;
+    private readonly queryExpander;
+    private readonly toolCache;
+    private readonly outputValidator;
+    private readonly sessionManager;
+    private readonly pendingToolResults;
+    private readonly requestLogger;
+    private readonly defaultLlmCallStrategy;
+    private _activeClients;
+    private _mainLlm;
+    private _classifierLlm;
+    private _helperLlm;
+    private _classifier;
+    constructor(deps: SmartAgentDeps, config: SmartAgentConfig);
+    /** Current main LLM instance. Use this for direct LLM calls that should respect hot-swap. */
+    get currentMainLlm(): ILlm;
+    private _resolveActiveClients;
+    private _revectorizeTools;
+    /** Apply a partial config update at runtime (hot-reload). */
+    applyConfigUpdate(update: Partial<SmartAgentConfig>): void;
+    /**
+     * Replace active LLM instances at runtime.
+     * Changes apply to new requests only — in-flight requests continue
+     * using the dependency snapshot captured at request start.
+     * Reconfigured LLMs do not inherit builder-time wrappers (retry, circuit breaker, rate limiter).
+     *
+     * **Important:** This is the only supported way to hot-swap LLMs.
+     * Direct mutation of `deps` fields has no effect — SmartAgent copies
+     * deps into private fields at construction time.
+     *
+     * @example
+     * ```typescript
+     * const newLlm = makeLlm({ provider: 'openai', model: 'gpt-5.4-pro', ... });
+     * handle.agent.reconfigure({ mainLlm: newLlm });
+     * // handle.chat() and handle.streamChat() now use the new LLM
+     * ```
+     */
+    reconfigure(update: SmartAgentReconfigureOptions): void;
+    /**
+     * Add a custom RAG store at runtime. Takes effect on the next request.
+     * Built-in store names ('tools', 'history') cannot be overwritten.
+     *
+     * @param options.translateQuery — when true, the pipeline translates the
+     *   query to English before searching this store (useful for stores with
+     *   English-only content like MCP tool descriptions).
+     */
+    addRagStore(name: string, store: IRag, options?: {
+        translateQuery?: boolean;
+    }): void;
+    /**
+     * Remove a custom RAG store at runtime. Takes effect on the next request.
+     * Built-in store names ('tools', 'history') cannot be removed.
+     */
+    removeRagStore(name: string): void;
+    /**
+     * Close a session: remove session-scoped RAG collections for the given
+     * sessionId and flush session-scoped history memory.
+     * Errors from registry cleanup are logged but not thrown — best-effort.
+     */
+    closeSession(sessionId: string): Promise<void>;
+    /** Returns the model identifiers of the currently active LLM instances. */
+    getActiveConfig(): {
+        mainModel?: string;
+        classifierModel?: string;
+        helperModel?: string;
+    };
+    /** Returns whitelisted runtime-safe agent config fields (for HTTP DTO). */
+    getAgentConfig(): {
+        maxIterations: number;
+        maxToolCalls?: number;
+        ragQueryK?: number;
+        toolUnavailableTtlMs?: number;
+        showReasoning?: boolean;
+        historyAutoSummarizeLimit?: number;
+        classificationEnabled?: boolean;
+    };
+    healthCheck(options?: CallOptions): Promise<Result<{
+        llm: boolean;
+        rag: boolean;
+        mcp: {
+            name: string;
+            ok: boolean;
+            error?: string;
+        }[];
+    }, OrchestratorError>>;
+    process(textOrMessages: string | Message[], options?: AgentCallOptions): Promise<Result<SmartAgentResponse, OrchestratorError>>;
+    streamProcess(textOrMessages: string | Message[], options?: AgentCallOptions): AsyncIterable<Result<LlmStreamChunk, OrchestratorError>>;
+    private _preparePipeline;
+    private _runStreamingToolLoop;
+    private _listAllTools;
+    private _toEnglishForRag;
+    private _summarizeHistory;
+    private _runStructuredPipeline;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}