art-framework 0.2.4 → 0.2.5

package/dist/index.d.ts

@@ -1,3 +1,93 @@
+type UnsubscribeFunction = () => void;
+interface Subscription<DataType, FilterType> {
+    id: string;
+    callback: (data: DataType) => void;
+    filter?: FilterType;
+    options?: {
+        threadId?: string;
+    };
+}
+/**
+ * A generic class for implementing a publish/subscribe pattern with filtering capabilities.
+ * Designed for decoupling components, particularly UI updates from backend events.
+ */
+declare class TypedSocket$1<DataType, FilterType = any> {
+    protected subscriptions: Map<string, Subscription<DataType, FilterType>>;
+    constructor();
+    /**
+     * Subscribes a callback function to receive notifications.
+     * @param callback - The function to call when new data is notified.
+     * @param filter - An optional filter to only receive specific types of data.
+     * @param options - Optional configuration, like a threadId for filtering.
+     * @returns An unsubscribe function.
+     */
+    subscribe(callback: (data: DataType) => void, filter?: FilterType, options?: {
+        threadId?: string;
+    }): UnsubscribeFunction;
+    /**
+     * Notifies all relevant subscribers with new data.
+     * @param data - The data payload to send to subscribers.
+     * @param options - Optional targeting options (e.g., targetThreadId).
+     * @param filterCheck - A function to check if a subscription's filter matches the data.
+     */
+    notify(data: DataType, options?: {
+        targetThreadId?: string;
+        targetSessionId?: string;
+    }, // targetSessionId might be useful later
+    filterCheck?: (data: DataType, filter?: FilterType) => boolean): void;
+    /**
+     * Optional: Retrieves historical data. This base implementation is empty.
+     * Subclasses might implement this by interacting with repositories.
+     */
+    getHistory?(_filter?: FilterType, _options?: {
+        threadId?: string;
+        limit?: number;
+    }): Promise<DataType[]>;
+    /**
+    * Clears all subscriptions. Useful for cleanup.
+    */
+    clearAllSubscriptions(): void;
+}
+
+/** Entry defining an available provider adapter */
+interface AvailableProviderEntry {
+    name: string;
+    adapter: new (options: any) => ProviderAdapter;
+    baseOptions?: any;
+    isLocal?: boolean;
+}
+/** Configuration for the ProviderManager passed during ART initialization */
+interface ProviderManagerConfig {
+    availableProviders: AvailableProviderEntry[];
+    /** Max concurrent ACTIVE instances per API-based provider NAME. Default: 5 */
+    maxParallelApiInstancesPerProvider?: number;
+    /** Time in seconds an API adapter instance can be idle before being eligible for removal. Default: 300 */
+    apiInstanceIdleTimeoutSeconds?: number;
+}
+/** Configuration passed AT RUNTIME for a specific LLM call */
+interface RuntimeProviderConfig {
+    providerName: string;
+    modelId: string;
+    adapterOptions: any;
+}
+/** Object returned by ProviderManager granting access to an adapter instance */
+interface ManagedAdapterAccessor {
+    adapter: ProviderAdapter;
+    /** Signals that the current call using this adapter instance is finished. */
+    release: () => void;
+}
+/** Interface for the ProviderManager */
+interface IProviderManager {
+    /** Returns identifiers for all registered potential providers */
+    getAvailableProviders(): string[];
+    /**
+     * Gets a managed adapter instance based on the runtime config.
+     * Handles instance creation, caching, pooling limits, and singleton constraints.
+     * May queue requests or throw errors based on concurrency limits.
+     */
+    getAdapter(config: RuntimeProviderConfig): Promise<ManagedAdapterAccessor>;
+}
+
 /**
  * Represents the role of a message sender in a conversation.
  */
@@ -11,40 +101,128 @@ declare enum MessageRole {
  * Represents a single message within a conversation thread.
  */
 interface ConversationMessage {
+    /** A unique identifier for this specific message. */
     messageId: string;
+    /** The identifier of the conversation thread this message belongs to. */
     threadId: string;
+    /** The role of the sender (User, AI, System, or Tool). */
     role: MessageRole;
+    /** The textual content of the message. */
     content: string;
+    /** A Unix timestamp (in milliseconds) indicating when the message was created. */
     timestamp: number;
+    /** Optional metadata associated with the message (e.g., related observation IDs, tool call info, UI state). */
     metadata?: Record<string, any>;
 }
 /**
- * Represents the type of an observation record.
+ * Represents the type of an observation record, capturing significant events during agent execution.
  */
 declare enum ObservationType {
     INTENT = "INTENT",
     PLAN = "PLAN",
     THOUGHTS = "THOUGHTS",
-    TOOL_CALL = "TOOL_CALL",// Renamed from checklist for clarity
+    /** Records the LLM's decision to call one or more tools (part of the plan). */
+    TOOL_CALL = "TOOL_CALL",
+    /** Records the actual execution attempt and result of a specific tool call. */
     TOOL_EXECUTION = "TOOL_EXECUTION",
-    SYNTHESIS = "SYNTHESIS",// Added for final synthesis step
+    /** Records events specifically related to the synthesis phase (e.g., the LLM call). */
+    SYNTHESIS = "SYNTHESIS",
+    /** Records an error encountered during any phase of execution. */
     ERROR = "ERROR",
-    FINAL_RESPONSE = "FINAL_RESPONSE",// Added for the final AI response message
-    STATE_UPDATE = "STATE_UPDATE"
+    /** Records the final AI response message generated by the agent. */
+    FINAL_RESPONSE = "FINAL_RESPONSE",
+    /** Records changes made to the agent's persistent state. */
+    STATE_UPDATE = "STATE_UPDATE",
+    /** Logged by Agent Core when LLM stream consumption begins. */
+    LLM_STREAM_START = "LLM_STREAM_START",
+    /** Logged by Agent Core upon receiving a METADATA stream event. Content should be LLMMetadata. */
+    LLM_STREAM_METADATA = "LLM_STREAM_METADATA",
+    /** Logged by Agent Core upon receiving an END stream event. */
+    LLM_STREAM_END = "LLM_STREAM_END",
+    /** Logged by Agent Core upon receiving an ERROR stream event. Content should be Error object or message. */
+    LLM_STREAM_ERROR = "LLM_STREAM_ERROR"
+}
+/**
+ * Represents the different capabilities a model might possess.
+ * Used for model selection and validation.
+ */
+declare enum ModelCapability {
+    TEXT = "text",// Basic text generation/understanding
+    VISION = "vision",// Ability to process and understand images
+    STREAMING = "streaming",// Supports streaming responses chunk by chunk
+    TOOL_USE = "tool_use",// Capable of using tools/function calling
+    RAG = "rag",// Built-in or optimized for Retrieval-Augmented Generation
+    CODE = "code",// Specialized in understanding or generating code
+    REASONING = "reasoning"
 }
 /**
  * Represents a recorded event during the agent's execution.
  */
 interface Observation {
+    /** A unique identifier for this specific observation record. */
     id: string;
+    /** The identifier of the conversation thread this observation relates to. */
     threadId: string;
+    /** An optional identifier for tracing a request across multiple systems or components. */
     traceId?: string;
+    /** A Unix timestamp (in milliseconds) indicating when the observation was recorded. */
     timestamp: number;
+    /** The category of the event being observed (e.g., PLAN, THOUGHTS, TOOL_EXECUTION). */
     type: ObservationType;
+    /** A concise, human-readable title summarizing the observation (often generated based on type/metadata). */
     title: string;
+    /** The main data payload of the observation, structure depends on the `type`. */
     content: any;
+    /** Optional metadata providing additional context (e.g., source phase, related IDs, status). */
     metadata?: Record<string, any>;
 }
+/**
+ * Represents a single event emitted from an asynchronous LLM stream (`ReasoningEngine.call`).
+ * Allows for real-time delivery of tokens, metadata, errors, and lifecycle signals.
+ * Adapters are responsible for translating provider-specific stream chunks into these standard events.
+ */
+interface StreamEvent {
+    /**
+     * The type of the stream event:
+     * - `TOKEN`: A chunk of text generated by the LLM.
+     * - `METADATA`: Information about the LLM call (e.g., token counts, stop reason), typically sent once at the end.
+     * - `ERROR`: An error occurred during the LLM call or stream processing. `data` will contain the Error object.
+     * - `END`: Signals the successful completion of the stream. `data` is typically null.
+     */
+    type: 'TOKEN' | 'METADATA' | 'ERROR' | 'END';
+    /**
+     * The actual content of the event.
+     * - For `TOKEN`: string (the text chunk).
+     * - For `METADATA`: `LLMMetadata` object.
+     * - For `ERROR`: `Error` object or error details.
+     * - For `END`: null.
+     */
+    data: any;
+    /**
+     * Optional: Provides a more specific classification for `TOKEN` events,
+     * combining LLM-level detection (thinking/response, if available from adapter)
+     * and agent-level context (`callContext` from `CallOptions`).
+     * Used by consumers (like UI) to differentiate between intermediate thoughts and the final response.
+     *
+     * - `LLM_THINKING`: Token identified by the adapter as part of the LLM's internal reasoning/thought process.
+     * - `LLM_RESPONSE`: Token identified by the adapter as part of the LLM's final response content.
+     * - `AGENT_THOUGHT_LLM_THINKING`: Token from an LLM call made in the 'AGENT_THOUGHT' context, identified as thinking.
+     * - `AGENT_THOUGHT_LLM_RESPONSE`: Token from an LLM call made in the 'AGENT_THOUGHT' context, identified as response (e.g., the raw planning output).
+     * - `FINAL_SYNTHESIS_LLM_THINKING`: Token from an LLM call made in the 'FINAL_SYNTHESIS' context, identified as thinking.
+     * - `FINAL_SYNTHESIS_LLM_RESPONSE`: Token from an LLM call made in the 'FINAL_SYNTHESIS' context, identified as response (part of the final answer to the user).
+     *
+     * Note: Not all adapters can reliably distinguish 'LLM_THINKING' vs 'LLM_RESPONSE'.
+     * Adapters should prioritize setting the agent context part (`AGENT_THOUGHT_...` or `FINAL_SYNTHESIS_...`) based on `CallOptions.callContext`.
+     * If thinking detection is unavailable, adapters should default to `AGENT_THOUGHT_LLM_RESPONSE` or `FINAL_SYNTHESIS_LLM_RESPONSE`.
+     */
+    tokenType?: 'LLM_THINKING' | 'LLM_RESPONSE' | 'AGENT_THOUGHT_LLM_THINKING' | 'AGENT_THOUGHT_LLM_RESPONSE' | 'FINAL_SYNTHESIS_LLM_THINKING' | 'FINAL_SYNTHESIS_LLM_RESPONSE';
+    /** The identifier of the conversation thread this event belongs to. */
+    threadId: string;
+    /** The identifier tracing the specific agent execution cycle this event is part of. */
+    traceId: string;
+    /** Optional identifier linking the event to a specific UI tab/window. */
+    sessionId?: string;
+}
 /**
  * Represents a basic JSON Schema definition, focusing on object types commonly used for tool inputs/outputs.
  * This is a simplified representation and doesn't cover all JSON Schema features.
@@ -74,15 +252,42 @@ type JsonSchema = JsonObjectSchema | {
     type: 'string' | 'number' | 'boolean' | 'array';
     [key: string]: any;
 };
+/**
+ * Structure for holding metadata about an LLM call, typically received via a `METADATA` `StreamEvent`
+ * or parsed from a non-streaming response. Fields are optional as availability varies by provider and stream state.
+ */
+interface LLMMetadata {
+    /** The number of tokens in the input prompt, if available. */
+    inputTokens?: number;
+    /** The number of tokens generated in the output response, if available. */
+    outputTokens?: number;
+    /** The number of tokens identified as part of the LLM's internal thinking process (if available from provider). */
+    thinkingTokens?: number;
+    /** The time elapsed (in milliseconds) until the first token was generated in a streaming response, if applicable and available. */
+    timeToFirstTokenMs?: number;
+    /** The total time elapsed (in milliseconds) for the entire generation process, if available. */
+    totalGenerationTimeMs?: number;
+    /** The reason the LLM stopped generating tokens (e.g., 'stop_sequence', 'max_tokens', 'tool_calls'), if available. */
+    stopReason?: string;
+    /** Optional raw usage data provided directly by the LLM provider for extensibility (structure depends on provider). */
+    providerRawUsage?: any;
+    /** The trace ID associated with the LLM call, useful for correlating metadata with the specific request. */
+    traceId?: string;
+}
 /**
  * Defines the schema for a tool, including its input parameters.
  * Uses JSON Schema format for inputSchema.
  */
 interface ToolSchema {
+    /** A unique name identifying the tool (used in LLM prompts and registry lookups). Must be unique. */
     name: string;
+    /** A clear description of what the tool does, intended for the LLM to understand its purpose and usage. */
     description: string;
+    /** A JSON Schema object defining the structure, types, and requirements of the input arguments the tool expects. */
     inputSchema: JsonSchema;
+    /** An optional JSON Schema object defining the expected structure of the data returned in the `output` field of a successful `ToolResult`. */
     outputSchema?: JsonSchema;
+    /** Optional array of examples demonstrating how to use the tool, useful for few-shot prompting of the LLM. */
     examples?: Array<{
         input: any;
         output?: any;
@@ -93,186 +298,331 @@ interface ToolSchema {
  * Represents the structured result of a tool execution.
  */
 interface ToolResult {
+    /** The unique identifier of the corresponding `ParsedToolCall` that initiated this execution attempt. */
     callId: string;
+    /** The name of the tool that was executed. */
     toolName: string;
+    /** Indicates whether the tool execution succeeded or failed. */
     status: 'success' | 'error';
+    /** The data returned by the tool upon successful execution. Structure may be validated against `outputSchema`. */
     output?: any;
+    /** A descriptive error message if the execution failed (`status` is 'error'). */
     error?: string;
+    /** Optional metadata about the execution (e.g., duration, cost, logs). */
     metadata?: Record<string, any>;
 }
 /**
  * Represents a parsed request from the LLM to call a specific tool.
  */
 interface ParsedToolCall {
+    /** A unique identifier generated by the OutputParser for this specific tool call request within a plan. */
     callId: string;
+    /** The name of the tool the LLM intends to call. Must match a registered tool's schema name. */
     toolName: string;
+    /** The arguments object, parsed from the LLM response, intended to be passed to the tool's `execute` method after validation. */
     arguments: any;
 }
 /**
  * Configuration specific to a conversation thread.
  */
 interface ThreadConfig {
-    reasoning: {
-        provider: string;
-        model: string;
-        parameters?: Record<string, any>;
-    };
+    /** Default provider configuration for this thread. */
+    providerConfig: RuntimeProviderConfig;
+    /** An array of tool names (matching `ToolSchema.name`) that are permitted for use within this thread. */
     enabledTools: string[];
+    /** The maximum number of past messages (`ConversationMessage` objects) to retrieve for context. */
     historyLimit: number;
-    systemPrompt?: string;
 }
 /**
  * Represents non-configuration state associated with an agent or thread.
  * Could include user preferences, accumulated knowledge, etc. (Less defined for v1.0)
  */
 interface AgentState {
+    /** A flexible object to store persistent, non-configuration data associated with a thread or user (e.g., preferences, summaries, intermediate results). Structure is application-defined. */
     [key: string]: any;
 }
 /**
  * Encapsulates the configuration and state for a specific thread.
  */
 interface ThreadContext {
+    /** The configuration settings (`ThreadConfig`) currently active for the thread. */
     config: ThreadConfig;
+    /** The persistent state (`AgentState`) associated with the thread, or `null` if no state exists. */
     state: AgentState | null;
 }
 /**
  * Properties required to initiate an agent processing cycle.
  */
 interface AgentProps {
+    /** The user's input query or request to the agent. */
     query: string;
+    /** The mandatory identifier for the conversation thread. All context is scoped to this ID. */
     threadId: string;
+    /** An optional identifier for the specific UI session, useful for targeting UI updates. */
     sessionId?: string;
+    /** An optional identifier for the user interacting with the agent. */
     userId?: string;
+    /** An optional identifier used for tracing a request across multiple systems or services. */
     traceId?: string;
+    /** Optional runtime options that can override default behaviors for this specific `process` call. */
     options?: AgentOptions;
 }
 /**
  * Options to override agent behavior at runtime.
  */
 interface AgentOptions {
+    /** Override specific LLM parameters (e.g., temperature, max_tokens) for this call only. */
     llmParams?: Record<string, any>;
+    /** Override provider configuration for this specific call. */
+    providerConfig?: RuntimeProviderConfig;
+    /** Force the use of specific tools, potentially overriding the thread's `enabledTools` for this call (use with caution). */
     forceTools?: string[];
+    /** Specify a particular reasoning model to use for this call, overriding the thread's default. */
+    overrideModel?: {
+        provider: string;
+        model: string;
+    };
+    /** Request a streaming response for this specific agent process call. */
+    stream?: boolean;
+    /** Override the prompt template used for this specific call. */
+    promptTemplateId?: string;
 }
 /**
  * The final structured response returned by the agent core after processing.
  */
 interface AgentFinalResponse {
+    /** The final `ConversationMessage` generated by the AI, which has also been persisted. */
     response: ConversationMessage;
+    /** Metadata summarizing the execution cycle that produced this response. */
     metadata: ExecutionMetadata;
 }
 /**
- * Metadata summarizing an agent execution cycle.
+ * Metadata summarizing an agent execution cycle, including performance metrics and outcomes.
  */
 interface ExecutionMetadata {
+    /** The thread ID associated with this execution cycle. */
     threadId: string;
+    /** The trace ID used during this execution, if provided. */
     traceId?: string;
+    /** The user ID associated with the execution, if provided. */
     userId?: string;
+    /** The overall status of the execution ('success', 'error', or 'partial' if some steps failed but a response was generated). */
     status: 'success' | 'error' | 'partial';
+    /** The total duration of the `agent.process()` call in milliseconds. */
     totalDurationMs: number;
+    /** The number of calls made to the `ReasoningEngine`. */
     llmCalls: number;
+    /** The number of tool execution attempts made by the `ToolSystem`. */
     toolCalls: number;
+    /** An optional estimated cost for the LLM calls made during this execution. */
     llmCost?: number;
+    /** A top-level error message if the overall status is 'error' or 'partial'. */
     error?: string;
+    /** Aggregated metadata from LLM calls made during the execution. */
+    llmMetadata?: LLMMetadata;
 }
 /**
  * Context provided to a tool during its execution.
  */
 interface ExecutionContext {
+    /** The ID of the thread in which the tool is being executed. */
     threadId: string;
+    /** The trace ID for this execution cycle, if available. */
     traceId?: string;
+    /** The user ID associated with the execution, if available. */
     userId?: string;
 }
 /**
- * Options for configuring an LLM call.
+ * Options for configuring an LLM call, including streaming and context information.
  */
 interface CallOptions {
+    /** The mandatory thread ID, used by the ReasoningEngine to fetch thread-specific configuration (e.g., model, params) via StateManager. */
     threadId: string;
+    /** Optional trace ID for correlation. */
     traceId?: string;
+    /** Optional user ID. */
     userId?: string;
-    onThought?: (thought: string) => void;
+    /** Optional session ID. */
+    sessionId?: string;
+    /**
+     * Request a streaming response from the LLM provider.
+     * Adapters MUST check this flag.
+     */
+    stream?: boolean;
+    /**
+     * Provides context for the LLM call, allowing adapters to differentiate
+     * between agent-level thoughts and final synthesis calls for token typing.
+     * Agent Core MUST provide this.
+     */
+    callContext?: 'AGENT_THOUGHT' | 'FINAL_SYNTHESIS' | string;
+    /** An optional callback function invoked when the LLM streams intermediate 'thoughts' or reasoning steps.
+     * @deprecated Prefer using StreamEvent with appropriate tokenType for thoughts. Kept for potential transitional compatibility.
+     */
+    /** Carries the specific target provider and configuration for this call. */
+    providerConfig: RuntimeProviderConfig;
+    /** Additional key-value pairs representing provider-specific parameters (e.g., `temperature`, `max_tokens`, `top_p`). These often override defaults set in `ThreadConfig`. */
+    [key: string]: any;
+}
+/**
+ * Defines the standard roles for messages within the `ArtStandardPrompt` format.
+ * These roles are chosen for broad compatibility across major LLM providers (like OpenAI, Anthropic, Gemini).
+ * Provider Adapters are responsible for translating these standard roles into the specific formats
+ * required by their respective APIs (e.g., 'assistant' might become 'model' for Gemini).
+ *
+ * - `system`: Instructions or context provided to the AI, typically at the beginning.
+ * - `user`: Input or queries from the end-user. Also used to wrap `tool_result` content for some providers (e.g., Gemini).
+ * - `assistant`: Responses generated by the AI model. Can contain text content and/or `tool_calls`.
+ * - `tool_request`: Represents the LLM's request to use tools (often implicitly part of an `assistant` message with `tool_calls`). Included for potential future explicit use.
+ * - `tool_result`: The outcome (output or error) of executing a requested tool call.
+ */
+type ArtStandardMessageRole = 'system' | 'user' | 'assistant' | 'tool_request' | 'tool_result' | 'tool';
+/**
+ * Represents a single message in the standardized, provider-agnostic `ArtStandardPrompt` format.
+ * This structure aims to capture common message elements used by various LLM APIs.
+ */
+interface ArtStandardMessage {
+    /** The role indicating the source or type of the message. */
+    role: ArtStandardMessageRole;
+    /**
+     * The primary content of the message. The type and interpretation depend on the `role`:
+     * - `system`: string (The system instruction).
+     * - `user`: string (The user's text input).
+     * - `assistant`: string | null (The AI's text response, or null/empty if only making `tool_calls`).
+     * - `tool_request`: object | null (Structured representation of the tool call, often implicitly handled via `assistant` message's `tool_calls`).
+     * - `tool_result`: string (Stringified JSON output or error message from the tool execution).
+     */
+    content: string | object | null;
+    /** Optional name associated with the message. Primarily used for `tool_result` role to specify the name of the tool that was executed. */
+    name?: string;
+    /**
+     * Optional array of tool calls requested by the assistant.
+     * Only relevant for 'assistant' role messages that trigger tool usage.
+     * Structure mirrors common provider formats (e.g., OpenAI).
+     */
+    tool_calls?: Array<{
+        /** A unique identifier for this specific tool call request. */
+        id: string;
+        /** The type of the tool call, typically 'function'. */
+        type: 'function';
+        /** Details of the function to be called. */
+        function: {
+            /** The name of the function/tool to call. */
+            name: string;
+            /** A stringified JSON object representing the arguments for the function. */
+            arguments: string;
+        };
+    }>;
+    /**
+     * Optional identifier linking a 'tool_result' message back to the specific 'tool_calls' entry
+     * in the preceding 'assistant' message that requested it.
+     * Required for 'tool_result' role.
+     */
+    tool_call_id?: string;
+}
+/**
+ * Represents the entire prompt as an array of standardized messages (`ArtStandardMessage`).
+ * This is the standard format produced by `PromptManager.assemblePrompt` and consumed
+ * by `ProviderAdapter.call` for translation into provider-specific API formats.
+ */
+type ArtStandardPrompt = ArtStandardMessage[];
+/**
+ * Represents the contextual data gathered by Agent Logic (e.g., `PESAgent`) to be injected
+ * into a Mustache blueprint/template by the `PromptManager.assemblePrompt` method.
+ *
+ * Contains standard fields commonly needed for prompts, plus allows for arbitrary
+ * additional properties required by specific agent blueprints. Agent logic is responsible
+ * for populating this context appropriately before calling `assemblePrompt`.
+ */
+interface PromptContext {
+    /** The user's current query or input relevant to this prompt generation step. */
+    query?: string;
+    /**
+     * The conversation history, typically formatted as an array suitable for the blueprint
+     * (e.g., array of objects with `role` and `content`). Agent logic should pre-format this.
+     * Note: While `ArtStandardPrompt` could be used, simpler structures might be preferred for blueprints.
+     */
+    history?: Array<{
+        role: string;
+        content: string;
+        [key: string]: any;
+    }>;
+    /**
+     * The schemas of the tools available for use, potentially pre-formatted for the blueprint
+     * (e.g., with `inputSchemaJson` pre-stringified).
+     */
+    availableTools?: Array<ToolSchema & {
+        inputSchemaJson?: string;
+    }>;
+    /**
+     * The results from any tools executed in a previous step, potentially pre-formatted for the blueprint
+     * (e.g., with `outputJson` pre-stringified).
+     */
+    toolResults?: Array<ToolResult & {
+        outputJson?: string;
+    }>;
+    /** The system prompt string to be used (resolved by agent logic from config or defaults). */
+    systemPrompt?: string;
+    /** Allows agent patterns (like PES) to pass any other custom data needed by their specific blueprints (e.g., `intent`, `plan`). */
     [key: string]: any;
 }
 /**
  * Represents the prompt data formatted for a specific LLM provider.
  * Can be a simple string or a complex object (e.g., for OpenAI Chat Completion API).
+ * @deprecated Use `ArtStandardPrompt` as the standard intermediate format. ProviderAdapters handle final formatting.
  */
-type FormattedPrompt = string | object | Array<object>;
+type FormattedPrompt = ArtStandardPrompt;
 /**
  * Options for filtering data retrieved from storage.
  * Structure depends heavily on the underlying adapter's capabilities.
  */
 interface FilterOptions {
+    /** An object defining filter criteria (e.g., `{ threadId: 'abc', type: 'TOOL_EXECUTION' }`). Structure may depend on adapter capabilities. */
     filter?: Record<string, any>;
+    /** An object defining sorting criteria (e.g., `{ timestamp: 'desc' }`). */
     sort?: Record<string, 'asc' | 'desc'>;
+    /** The maximum number of records to return. */
     limit?: number;
+    /** The number of records to skip (for pagination). */
     skip?: number;
 }
 /**
  * Options for retrieving conversation messages.
  */
 interface MessageOptions {
+    /** The maximum number of messages to retrieve. */
     limit?: number;
+    /** Retrieve messages created before this Unix timestamp (milliseconds). */
     beforeTimestamp?: number;
+    /** Retrieve messages created after this Unix timestamp (milliseconds). */
     afterTimestamp?: number;
+    /** Optionally filter messages by role (e.g., retrieve only 'AI' messages). */
+    roles?: MessageRole[];
 }
 /**
  * Options for filtering observations.
  */
 interface ObservationFilter {
+    /** An array of `ObservationType` enums to filter by. If provided, only observations matching these types are returned. */
     types?: ObservationType[];
+    /** Retrieve observations recorded before this Unix timestamp (milliseconds). */
     beforeTimestamp?: number;
+    /** Retrieve observations recorded after this Unix timestamp (milliseconds). */
     afterTimestamp?: number;
 }
 
-type UnsubscribeFunction = () => void;
-interface Subscription<DataType, FilterType> {
-    id: string;
-    callback: (data: DataType) => void;
-    filter?: FilterType;
-    options?: {
-        threadId?: string;
-    };
-}
+type StreamEventTypeFilter = StreamEvent['type'] | Array<StreamEvent['type']>;
 /**
- * A generic class for implementing a publish/subscribe pattern with filtering capabilities.
- * Designed for decoupling components, particularly UI updates from backend events.
+ * A dedicated socket for broadcasting LLM stream events (`StreamEvent`) to UI subscribers.
+ * Extends the generic TypedSocket and implements filtering based on `StreamEvent.type`.
  */
-declare class TypedSocket$1<DataType, FilterType = any> {
-    protected subscriptions: Map<string, Subscription<DataType, FilterType>>;
+declare class LLMStreamSocket extends TypedSocket$1<StreamEvent, StreamEventTypeFilter> {
     constructor();
     /**
-     * Subscribes a callback function to receive notifications.
-     * @param callback - The function to call when new data is notified.
-     * @param filter - An optional filter to only receive specific types of data.
-     * @param options - Optional configuration, like a threadId for filtering.
-     * @returns An unsubscribe function.
+     * Notifies subscribers about a new LLM stream event.
+     * Filters based on event type if a filter is provided during subscription.
+     * @param event - The StreamEvent data.
      */
-    subscribe(callback: (data: DataType) => void, filter?: FilterType, options?: {
-        threadId?: string;
-    }): UnsubscribeFunction;
-    /**
-     * Notifies all relevant subscribers with new data.
-     * @param data - The data payload to send to subscribers.
-     * @param options - Optional targeting options (e.g., targetThreadId).
-     * @param filterCheck - A function to check if a subscription's filter matches the data.
-     */
-    notify(data: DataType, options?: {
-        targetThreadId?: string;
-        targetSessionId?: string;
-    }, // targetSessionId might be useful later
-    filterCheck?: (data: DataType, filter?: FilterType) => boolean): void;
-    /**
-     * Optional: Retrieves historical data. This base implementation is empty.
-     * Subclasses might implement this by interacting with repositories.
-     */
-    getHistory?(_filter?: FilterType, _options?: {
-        threadId?: string;
-        limit?: number;
-    }): Promise<DataType[]>;
-    /**
-     * Clears all subscriptions. Useful for cleanup.
-     */
-    clearAllSubscriptions(): void;
+    notifyStreamEvent(event: StreamEvent): void;
 }
 
 /**
@@ -331,6 +681,13 @@ declare class ConversationSocket$1 extends TypedSocket$1<ConversationMessage, Me
  * Interface for the central agent orchestrator.
  */
 interface IAgentCore {
+    /**
+     * Processes a user query through the configured agent reasoning pattern (e.g., PES).
+     * Orchestrates interactions between various ART subsystems.
+     * @param props - The input properties for the agent execution, including the query, thread ID, and injected dependencies.
+     * @returns A promise that resolves with the final agent response and execution metadata.
+     * @throws {ARTError} If a critical error occurs during orchestration that prevents completion.
+     */
     process(props: AgentProps): Promise<AgentFinalResponse>;
 }
 /**
@@ -338,50 +695,55 @@ interface IAgentCore {
  */
 interface ReasoningEngine {
     /**
-     * Calls the underlying LLM provider.
-     * @param prompt The formatted prompt for the provider.
-     * @param options Call-specific options, including threadId and callbacks.
-     * @returns The raw string response from the LLM.
+     * Executes a call to the configured Large Language Model (LLM).
+     * This method is typically implemented by a specific `ProviderAdapter`.
+     * When streaming is requested via `options.stream`, it returns an AsyncIterable
+     * that yields `StreamEvent` objects as they are generated by the LLM provider.
+     * When streaming is not requested, it should still return an AsyncIterable
+     * that yields a minimal sequence of events (e.g., a single TOKEN event with the full response,
+     * a METADATA event if available, and an END event).
+     * @param prompt - The prompt to send to the LLM, potentially formatted specifically for the provider.
+     * @param options - Options controlling the LLM call, including mandatory `threadId`, tracing IDs, model parameters (like temperature), streaming preference, and call context.
+     * @returns A promise resolving to an AsyncIterable of `StreamEvent` objects.
+     * @throws {ARTError} If a critical error occurs during the initial call setup or if the stream itself errors out (typically code `LLM_PROVIDER_ERROR`).
      */
-    call(prompt: FormattedPrompt, options: CallOptions): Promise<string>;
+    call(prompt: FormattedPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
 }
 /**
- * Interface for managing and constructing prompts for the LLM.
+ * Interface for the stateless prompt assembler.
+ * Uses a blueprint (template) and context provided by Agent Logic
+ * to create a standardized prompt format (`ArtStandardPrompt`).
  */
 interface PromptManager {
     /**
-     * Creates the prompt for the planning phase.
-     * @param query User query.
-     * @param history Conversation history.
-     * @param systemPrompt System prompt string.
-     * @param availableTools Schemas of available tools.
-     * @param threadContext Current thread context.
-     * @returns Formatted prompt suitable for the ReasoningEngine.
+     * Retrieves a named prompt fragment (e.g., a piece of instruction text).
+     * Optionally allows for simple variable substitution if the fragment is a basic template.
+     *
+     * @param name - The unique identifier for the fragment.
+     * @param context - Optional data for simple variable substitution within the fragment.
+     * @returns The processed prompt fragment string.
+     * @throws {ARTError} If the fragment is not found.
      */
-    createPlanningPrompt(query: string, history: ConversationMessage[], systemPrompt: string | undefined, availableTools: ToolSchema[], threadContext: ThreadContext): Promise<FormattedPrompt>;
+    getFragment(name: string, context?: Record<string, any>): string;
     /**
-     * Creates the prompt for the synthesis phase.
-     * @param query User query.
-     * @param intent Parsed intent from planning.
-     * @param plan Parsed plan from planning.
-     * @param toolResults Results from tool execution.
-     * @param history Conversation history.
-     * @param systemPrompt System prompt string.
-     * @param threadContext Current thread context.
-     * @returns Formatted prompt suitable for the ReasoningEngine.
+     * Validates a constructed prompt object against the standard schema.
+     *
+     * @param prompt - The ArtStandardPrompt object constructed by the agent.
+     * @returns The validated prompt object (potentially after normalization if the schema does that).
+     * @throws {ZodError} If validation fails (can be caught and wrapped in ARTError).
      */
-    createSynthesisPrompt(query: string, intent: string | undefined, // Or a structured intent object
-    plan: string | undefined, // Or a structured plan object
-    toolResults: ToolResult[], history: ConversationMessage[], systemPrompt: string | undefined, threadContext: ThreadContext): Promise<FormattedPrompt>;
+    validatePrompt(prompt: ArtStandardPrompt): ArtStandardPrompt;
 }
 /**
  * Interface for parsing structured output from LLM responses.
  */
 interface OutputParser {
     /**
-     * Parses the output of the planning LLM call.
-     * @param output Raw LLM output string.
-     * @returns Structured planning data (intent, plan, tool calls).
+     * Parses the raw string output from the planning LLM call to extract structured information.
+     * Implementations should be robust to variations in LLM output formatting.
+     * @param output - The raw string response from the planning LLM call.
+     * @returns A promise resolving to an object containing the extracted intent, plan description, and an array of parsed tool calls.
+     * @throws {ARTError} If the output cannot be parsed into the expected structure (typically code `OUTPUT_PARSING_FAILED`).
      */
     parsePlanningOutput(output: string): Promise<{
         intent?: string;
@@ -389,9 +751,11 @@ interface OutputParser {
         toolCalls?: ParsedToolCall[];
     }>;
     /**
-     * Parses the output of the synthesis LLM call.
-     * @param output Raw LLM output string.
-     * @returns The final synthesized response content.
+     * Parses the raw string output from the synthesis LLM call to extract the final, user-facing response content.
+     * This might involve removing extraneous tags or formatting.
+     * @param output - The raw string response from the synthesis LLM call.
+     * @returns A promise resolving to the clean, final response string.
+     * @throws {ARTError} If the final response cannot be extracted (typically code `OUTPUT_PARSING_FAILED`).
      */
     parseSynthesisOutput(output: string): Promise<string>;
 }
@@ -400,7 +764,10 @@ interface OutputParser {
  * Implementations will handle provider-specific API calls, authentication, etc.
  */
 interface ProviderAdapter extends ReasoningEngine {
+    /** The unique identifier name for this provider (e.g., 'openai', 'anthropic'). */
     readonly providerName: string;
+    /** Optional: Method for graceful shutdown */
+    shutdown?(): Promise<void>;
 }
 /**
  * Interface for the executable logic of a tool.
@@ -421,20 +788,21 @@ interface IToolExecutor {
  */
 interface ToolRegistry {
     /**
-     * Registers a tool executor.
-     * @param executor The tool executor instance.
+     * Registers a tool executor instance, making it available for use.
+     * @param executor - The instance of the class implementing `IToolExecutor`.
+     * @throws {Error} If a tool with the same name is already registered.
      */
     registerTool(executor: IToolExecutor): Promise<void>;
     /**
-     * Retrieves a tool executor by its name.
-     * @param toolName The unique name of the tool.
-     * @returns The executor instance or undefined if not found.
+     * Retrieves a registered tool executor instance by its unique name.
+     * @param toolName - The `name` property defined in the tool's schema.
+     * @returns A promise resolving to the executor instance, or `undefined` if no tool with that name is registered.
      */
     getToolExecutor(toolName: string): Promise<IToolExecutor | undefined>;
     /**
-     * Retrieves the schemas of all registered tools, potentially filtered.
-     * @param filter Optional criteria (e.g., only enabled tools for a thread).
-     * @returns An array of tool schemas.
+     * Retrieves the schemas of available tools. Can be filtered, e.g., to get only tools enabled for a specific thread.
+     * @param filter - Optional filter criteria. If `enabledForThreadId` is provided, it should consult the `StateManager` to return only schemas for tools enabled in that thread's configuration.
+     * @returns A promise resolving to an array of `ToolSchema` objects.
      */
     getAvailableTools(filter?: {
         enabledForThreadId?: string;
@@ -445,11 +813,12 @@ interface ToolRegistry {
  */
 interface ToolSystem {
     /**
-     * Executes a list of parsed tool calls.
-     * @param toolCalls Array of tool calls requested by the LLM.
-     * @param threadId The current thread ID for context and permissions.
-     * @param traceId Optional trace ID.
-     * @returns A promise resolving to an array of tool results.
+     * Orchestrates the execution of a sequence of tool calls determined during the planning phase.
+     * This involves verifying permissions, validating inputs, calling the tool executor, and recording observations.
+     * @param toolCalls - An array of `ParsedToolCall` objects generated by the `OutputParser`.
+     * @param threadId - The ID of the current thread, used for context and checking tool permissions via `StateManager`.
+     * @param traceId - Optional trace ID for correlating observations.
+     * @returns A promise resolving to an array of `ToolResult` objects, one for each attempted tool call (including errors).
      */
     executeTools(toolCalls: ParsedToolCall[], threadId: string, traceId?: string): Promise<ToolResult[]>;
 }
@@ -458,36 +827,44 @@ interface ToolSystem {
  */
 interface StateManager {
     /**
-     * Loads the full context (config + state) for a given thread.
-     * @param threadId The ID of the thread.
-     * @param userId Optional user ID for access control.
-     * @returns The thread context.
+     * Loads the complete context (`ThreadConfig` and `AgentState`) for a specific thread.
+     * This is typically called at the beginning of an agent execution cycle.
+     * @param threadId - The unique identifier for the thread.
+     * @param userId - Optional user identifier, potentially used for retrieving user-specific state or config overrides.
+     * @returns A promise resolving to the `ThreadContext` object containing the loaded configuration and state.
+     * @throws {ARTError} If the context for the thread cannot be loaded (e.g., code `THREAD_NOT_FOUND`).
      */
     loadThreadContext(threadId: string, userId?: string): Promise<ThreadContext>;
     /**
-     * Checks if a specific tool is enabled for the given thread based on its config.
-     * @param threadId The ID of the thread.
-     * @param toolName The name of the tool.
-     * @returns True if the tool is enabled, false otherwise.
+     * Verifies if a specific tool is permitted for use within a given thread.
+     * Checks against the `enabledTools` array in the thread's loaded `ThreadConfig`.
+     * @param threadId - The ID of the thread.
+     * @param toolName - The name of the tool to check.
+     * @returns A promise resolving to `true` if the tool is enabled for the thread, `false` otherwise.
      */
     isToolEnabled(threadId: string, toolName: string): Promise<boolean>;
     /**
-     * Retrieves a specific configuration value for the thread.
-     * @param threadId The ID of the thread.
-     * @param key The configuration key (potentially nested, e.g., 'reasoning.model').
-     * @returns The configuration value or undefined.
+     * Retrieves a specific value from the thread's configuration (`ThreadConfig`).
+     * Supports accessing nested properties using dot notation (e.g., 'reasoning.model').
+     * @template T - The expected type of the configuration value.
+     * @param threadId - The ID of the thread.
+     * @param key - The key (potentially nested) of the configuration value to retrieve.
+     * @returns A promise resolving to the configuration value, or `undefined` if the key doesn't exist or the thread config isn't loaded.
      */
     getThreadConfigValue<T>(threadId: string, key: string): Promise<T | undefined>;
     /**
-     * Saves the thread's state if it has been modified during execution.
-     * Implementations should track changes to avoid unnecessary writes.
-     * @param threadId The ID of the thread.
+     * Persists the `AgentState` for the thread, but only if it has been marked as modified during the current execution cycle.
+     * This prevents unnecessary writes to the storage layer.
+     * @param threadId - The ID of the thread whose state should potentially be saved.
+     * @returns A promise that resolves when the save operation is complete (or skipped).
      */
     saveStateIfModified(threadId: string): Promise<void>;
     /**
-     * Sets or updates the configuration for a specific thread.
-     * @param threadId The ID of the thread.
-     * @param config The complete configuration object to set.
+     * Sets or completely replaces the configuration (`ThreadConfig`) for a specific thread.
+     * Use with caution, as this overwrites the existing configuration. Consider methods for partial updates if needed.
+     * @param threadId - The ID of the thread whose configuration is being set.
+     * @param config - The complete `ThreadConfig` object to save.
+     * @returns A promise that resolves when the configuration is saved.
      */
     setThreadConfig(threadId: string, config: ThreadConfig): Promise<void>;
 }
@@ -496,16 +873,18 @@ interface StateManager {
  */
 interface ConversationManager {
     /**
-     * Adds one or more messages to a thread's history.
-     * @param threadId The ID of the thread.
-     * @param messages An array of messages to add.
+     * Appends one or more `ConversationMessage` objects to the history of a specific thread.
+     * Typically called at the end of an execution cycle to save the user query and the final AI response.
+     * @param threadId - The ID of the thread to add messages to.
+     * @param messages - An array containing the `ConversationMessage` objects to add.
+     * @returns A promise that resolves when the messages have been successfully added to storage.
      */
     addMessages(threadId: string, messages: ConversationMessage[]): Promise<void>;
     /**
-     * Retrieves messages from a thread's history.
-     * @param threadId The ID of the thread.
-     * @param options Filtering and pagination options.
-     * @returns An array of conversation messages.
+     * Retrieves messages from a specific thread's history, usually in reverse chronological order.
+     * @param threadId - The ID of the thread whose history is needed.
+     * @param options - Optional parameters to control retrieval, such as `limit` (max number of messages) or `beforeTimestamp` (for pagination). See `MessageOptions` type.
+     * @returns A promise resolving to an array of `ConversationMessage` objects, ordered according to the implementation (typically newest first if not specified otherwise).
      */
     getMessages(threadId: string, options?: MessageOptions): Promise<ConversationMessage[]>;
 }
@@ -514,16 +893,18 @@ interface ConversationManager {
  */
 interface ObservationManager {
     /**
-     * Records a new observation. Automatically assigns ID, timestamp, and potentially title.
-     * Notifies the ObservationSocket.
-     * @param observationData Data for the observation (excluding id, timestamp, title).
+     * Creates, persists, and broadcasts a new observation record.
+     * This is the primary method used by other systems to log significant events.
+     * It automatically generates a unique ID, timestamp, and potentially a title.
+     * @param observationData - An object containing the core data for the observation (`threadId`, `type`, `content`, `metadata`, etc.), excluding fields generated by the manager (`id`, `timestamp`, `title`).
+     * @returns A promise that resolves when the observation has been recorded and notified.
      */
     record(observationData: Omit<Observation, 'id' | 'timestamp' | 'title'>): Promise<void>;
     /**
-     * Retrieves observations for a specific thread, with optional filtering.
-     * @param threadId The ID of the thread.
-     * @param filter Optional filtering criteria.
-     * @returns An array of observations.
+     * Retrieves historical observations stored for a specific thread.
+     * @param threadId - The ID of the thread whose observations are to be retrieved.
+     * @param filter - Optional criteria to filter the observations, e.g., by `ObservationType`. See `ObservationFilter`.
+     * @returns A promise resolving to an array of `Observation` objects matching the criteria.
      */
     getObservations(threadId: string, filter?: ObservationFilter): Promise<Observation[]>;
 }
@@ -577,8 +958,12 @@ interface ConversationSocket extends TypedSocket<ConversationMessage, MessageRol
  * Interface for the system providing access to UI communication sockets.
  */
 interface UISystem {
+    /** Returns the singleton instance of the ObservationSocket. */
     getObservationSocket(): ObservationSocket$1;
+    /** Returns the singleton instance of the ConversationSocket. */
     getConversationSocket(): ConversationSocket$1;
+    /** Returns the singleton instance of the LLMStreamSocket. */
+    getLLMStreamSocket(): LLMStreamSocket;
 }
 /**
  * Interface for a storage adapter, providing a generic persistence layer.
@@ -638,124 +1023,313 @@ interface IStateRepository {
     setThreadContext(threadId: string, context: ThreadContext): Promise<void>;
 }
 /**
- * Represents the initialized ART instance returned by the factory function.
+ * Represents the fully initialized and configured ART Framework client instance.
+ * This object is the main entry point for interacting with the framework after setup.
+ * It provides access to the core processing method and key subsystems.
  */
 interface ArtInstance {
-    process: IAgentCore['process'];
-    uiSystem: UISystem;
-    stateManager: StateManager;
-    conversationManager: ConversationManager;
-    toolRegistry: ToolRegistry;
-    observationManager: ObservationManager;
+    /** The main method to process a user query using the configured Agent Core. */
+    readonly process: IAgentCore['process'];
+    /** Accessor for the UI System, used to get sockets for subscriptions. */
+    readonly uiSystem: UISystem;
+    /** Accessor for the State Manager, used for managing thread configuration and state. */
+    readonly stateManager: StateManager;
+    /** Accessor for the Conversation Manager, used for managing message history. */
+    readonly conversationManager: ConversationManager;
+    /** Accessor for the Tool Registry, used for managing available tools. */
+    readonly toolRegistry: ToolRegistry;
+    /** Accessor for the Observation Manager, used for recording and retrieving observations. */
+    readonly observationManager: ObservationManager;
+}
+
+/**
+ * Defines the available logging levels, ordered from most verbose to least verbose.
+ */
+declare enum LogLevel {
+    /** Detailed debugging information, useful for development. */
+    DEBUG = 0,
+    /** General informational messages about application flow. */
+    INFO = 1,
+    /** Potential issues or unexpected situations that don't prevent execution. */
+    WARN = 2,
+    /** Errors that indicate a failure or problem. */
+    ERROR = 3
+}
+/**
+ * Configuration options for the static Logger class.
+ */
+interface LoggerConfig {
+    /** The minimum log level to output messages for. Messages below this level will be ignored. */
+    level: LogLevel;
+    /** An optional prefix string to prepend to all log messages (e.g., '[MyApp]'). Defaults to '[ART]'. */
+    prefix?: string;
+}
+/**
+ * A simple static logger class for outputting messages to the console at different levels.
+ * Configuration is global via the static `configure` method.
+ */
+declare class Logger {
+    private static config;
+    /**
+     * Configures the static logger settings.
+     * @param config - A partial `LoggerConfig` object. Provided settings will override defaults.
+     */
+    static configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Logs a message at the DEBUG level.
+     * Only outputs if the configured log level is DEBUG.
+     * @param message - The main log message string.
+     * @param args - Additional arguments to include in the console output (e.g., objects, arrays).
+     */
+    static debug(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the INFO level.
+     * Outputs if the configured log level is INFO or DEBUG.
+     * @param message - The main log message string.
+     * @param args - Additional arguments to include in the console output.
+     */
+    static info(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the WARN level.
+     * Outputs if the configured log level is WARN, INFO, or DEBUG.
+     * @param message - The main log message string.
+     * @param args - Additional arguments to include in the console output.
+     */
+    static warn(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the ERROR level.
+     * Outputs if the configured log level is ERROR, WARN, INFO, or DEBUG.
+     * @param message - The main log message string.
+     * @param args - Additional arguments to include in the console output (often an error object).
+     */
+    static error(message: string, ...args: any[]): void;
 }
 
+/**
+ * Configuration for the Storage System adapter.
+ */
 interface StorageConfig {
+    /** Specifies the type of storage adapter to use. */
     type: 'memory' | 'indexedDB';
+    /** The name of the database to use (required for 'indexedDB'). */
     dbName?: string;
+    /** Optional: Database version for schema migrations (for 'indexedDB'). Defaults might apply. */
+    version?: number;
+    /** Optional: Advanced configuration for IndexedDB object stores and indexes. Defaults are usually sufficient. */
+    objectStores?: any[];
 }
-interface ReasoningConfig {
-    provider: 'openai' | 'gemini' | 'anthropic' | 'openrouter' | 'deepseek';
-    apiKey: string;
-    model?: string;
-    baseURL?: string;
-}
+/**
+ * Configuration object required by the AgentFactory and createArtInstance function.
+ */
 interface AgentFactoryConfig {
+    /** Configuration for the storage adapter. */
     storage: StorageConfig;
-    reasoning: ReasoningConfig;
+    /** Configuration for the Provider Manager, defining available adapters and rules. */
+    providers: ProviderManagerConfig;
+    /** Optional array of tool executor instances to register at initialization. */
     tools?: IToolExecutor[];
+    /** Optional: Specify a different Agent Core implementation class (defaults to PESAgent). */
     agentCore?: new (dependencies: any) => IAgentCore;
+    /** Optional: Configuration for the logger. */
+    logger?: {
+        level?: LogLevel;
+    };
 }
 /**
- * Creates and initializes an ART instance with the specified configuration.
- * This is the recommended way to get started with the ART framework.
- * @param config The configuration for the ART instance.
- * @returns A promise resolving to the initialized ArtInstance.
+ * High-level factory function to create and initialize a complete ART framework instance.
+ * This simplifies the setup process by handling the instantiation and wiring of all
+ * necessary components based on the provided configuration.
+ * @param config - The configuration object specifying storage, reasoning, tools, etc.
+ * @returns A promise that resolves to a ready-to-use `ArtInstance` object, providing access to the core `process` method and essential managers/systems.
+ * @throws {Error} If initialization fails (e.g., invalid config, storage connection error).
+ * @example
+ * const art = await createArtInstance({
+ *   storage: { type: 'indexedDB', dbName: 'myAgentDb' },
+ *   reasoning: { provider: 'openai', apiKey: '...' },
+ *   tools: [new CalculatorTool()]
+ * });
+ * const response = await art.process({ query: "Calculate 5*5", threadId: "thread1" });
  */
 declare function createArtInstance(config: AgentFactoryConfig): Promise<ArtInstance>;
 
+/**
+ * Defines the dependencies required by the PESAgent constructor.
+ * These are typically provided by the AgentFactory during instantiation.
+ */
 interface PESAgentDependencies {
+    /** Manages thread configuration and state. */
     stateManager: StateManager;
+    /** Manages conversation history. */
     conversationManager: ConversationManager;
+    /** Registry for available tools. */
     toolRegistry: ToolRegistry;
-    promptManager: PromptManager;
+    /** Handles interaction with the LLM provider. */
     reasoningEngine: ReasoningEngine;
+    /** Parses LLM responses. */
     outputParser: OutputParser;
+    /** Records agent execution observations. */
     observationManager: ObservationManager;
+    /** Orchestrates tool execution. */
     toolSystem: ToolSystem;
+    /** Provides access to UI communication sockets. */
+    uiSystem: UISystem;
 }
 /**
  * Implements the Plan-Execute-Synthesize (PES) agent orchestration logic.
+ * This agent follows a structured approach:
+ * 1.  **Plan:** Understand the user query, determine intent, and create a plan (potentially involving tool calls).
+ * 2.  **Execute:** Run any necessary tools identified in the planning phase.
+ * 3.  **Synthesize:** Generate a final response based on the query, plan, and tool results.
+ *
+ * It constructs standardized prompts (`ArtStandardPrompt`) directly as JavaScript objects
+ * for the `ReasoningEngine`. It processes the `StreamEvent` output from the reasoning engine for both planning and synthesis.
+ *
+ * @implements {IAgentCore}
+ * // @see {PromptManager} // Removed
+ * @see {ReasoningEngine}
+ * @see {ArtStandardPrompt}
+ * @see {StreamEvent}
  */
 declare class PESAgent implements IAgentCore {
     private readonly deps;
+    private readonly defaultSystemPrompt;
+    /**
+     * Creates an instance of the PESAgent.
+     * @param dependencies - An object containing instances of all required subsystems (managers, registries, etc.).
+     */
     constructor(dependencies: PESAgentDependencies);
+    /**
+     * Executes the full Plan-Execute-Synthesize cycle for a given user query.
+     *
+     * **Workflow:**
+     * 1.  **Initiation & Config:** Loads thread configuration and system prompt.
+     * 2.  **Data Gathering:** Gathers history, available tools, system prompt, and query.
+     * 3.  **Planning Prompt Construction:** Directly constructs the `ArtStandardPrompt` object/array for planning.
+     * 4.  **Planning LLM Call:** Sends the planning prompt object to the `reasoningEngine` (requesting streaming). Consumes the `StreamEvent` stream, buffers the output text, and handles potential errors.
+     * 5.  **Planning Output Parsing:** Parses the buffered planning output text to extract intent, plan, and tool calls using `outputParser.parsePlanningOutput`.
+     * 6.  **Tool Execution:** Executes identified tool calls via the `toolSystem`.
+     * 7.  **Data Gathering (Synthesis):** Gathers the original query, plan, tool results, history, etc.
+     * 8.  **Synthesis Prompt Construction:** Directly constructs the `ArtStandardPrompt` object/array for synthesis.
+     * 9.  **Synthesis LLM Call:** Sends the synthesis prompt object to the `reasoningEngine` (requesting streaming). Consumes the `StreamEvent` stream, buffers the final response text, and handles potential errors.
+     * 10. **Finalization:** Saves the final AI message, updates state if needed, records observations, and returns the result.
+     *
+     * **Error Handling:**
+     * - Errors during critical phases (planning/synthesis LLM call) will throw an `ARTError`. Prompt construction errors are less likely but possible if data is malformed.
+     * - Errors during tool execution or synthesis LLM call might result in a 'partial' success status, potentially using the error message as the final response content.
+     *
+     * @param {AgentProps} props - The input properties containing the user query, threadId, userId, traceId, etc.
+     * @returns {Promise<AgentFinalResponse>} A promise resolving to the final response, including the AI message and execution metadata.
+     * @throws {ARTError} If a critical error occurs that prevents the agent from completing the process (e.g., config loading, planning failure).
+     * @see {AgentProps}
+     * @see {AgentFinalResponse}
+     * // @see {PromptContext} // Removed - context is implicit in object construction
+     * @see {ArtStandardPrompt}
+     * @see {StreamEvent}
+     */
     process(props: AgentProps): Promise<AgentFinalResponse>;
+    /**
+     * Formats conversation history messages for direct inclusion in ArtStandardPrompt.
+     * Converts internal MessageRole to ArtStandardMessageRole.
+     * @param history - Array of ConversationMessage objects.
+     * @returns Array of messages suitable for ArtStandardPrompt.
+     */
+    private formatHistoryForPrompt;
 }
 
 /**
- * An in-memory implementation of the StorageAdapter interface.
- * Useful for testing, development, or simple scenarios where persistence
- * across sessions is not required.
+ * An in-memory implementation of the `StorageAdapter` interface.
+ * Stores all data in JavaScript Maps within the current process memory.
+ * Data is **not persisted** and will be lost when the application session ends.
+ *
+ * Useful for:
+ * - Unit and integration testing (fast, no external dependencies).
+ * - Simple demos or examples where persistence isn't needed.
+ * - Ephemeral agents that don't require long-term memory.
+ *
+ * @implements {StorageAdapter}
  */
 declare class InMemoryStorageAdapter implements StorageAdapter {
     private storage;
     /**
-     * Initializes the adapter (no-op for in-memory).
-     * @param _config Optional configuration (ignored).
+     * Initializes the adapter. This is a no-op for the in-memory adapter.
+     * @param _config - Optional configuration (ignored by this adapter).
+     * @returns A promise that resolves immediately.
      */
     init(_config?: any): Promise<void>;
     /**
-     * Retrieves a single item from a collection by its ID.
-     * @param collection The name of the data collection.
-     * @param id The unique ID of the item.
-     * @returns The item or null if not found.
+     * Retrieves a single item (as a deep copy) from a specified collection by its ID.
+     * @template T - The expected type of the retrieved item.
+     * @param collection - The name of the data collection (e.g., 'messages', 'observations').
+     * @param id - The unique ID of the item within the collection.
+     * @returns A promise resolving to a deep copy of the item if found, or `null` otherwise.
      */
     get<T>(collection: string, id: string): Promise<T | null>;
     /**
-     * Saves (creates or updates) an item in a collection.
-     * @param collection The name of the collection.
-     * @param id The unique ID of the item.
-     * @param data The data to save (will be deep copied).
+     * Saves (creates or updates) an item in a specified collection.
+     * Stores a deep copy of the provided data to prevent external mutations.
+     * @template T - The type of the data being saved.
+     * @param collection - The name of the collection.
+     * @param id - The unique ID for the item.
+     * @param data - The data object to save.
+     * @returns A promise that resolves when the data is saved in memory.
      */
     set<T>(collection: string, id: string, data: T): Promise<void>;
     /**
-     * Deletes an item from a collection by its ID.
-     * @param collection The name of the collection.
-     * @param id The unique ID of the item.
+     * Deletes an item from a specified collection using its ID.
+     * If the collection or item does not exist, the operation completes silently.
+     * @param collection - The name of the collection.
+     * @param id - The unique ID of the item to delete.
+     * @returns A promise that resolves when the deletion attempt is complete.
      */
     delete(collection: string, id: string): Promise<void>;
     /**
-     * Queries items in a collection based on simple filter options.
-     * Note: This is a basic implementation. It only supports exact matches
-     * on top-level properties defined in the filter object. It does not
-     * support complex queries, sorting, or deep filtering.
-     * @param collection The name of the collection.
-     * @param filterOptions Filtering options. Only `filter` is partially supported.
-     * @returns An array of matching items (deep copies).
+     * Queries items within a collection based on provided filter options.
+     * **Note:** This in-memory implementation provides basic filtering capabilities:
+     * - Supports exact matches on top-level properties specified in `filterOptions.filter`.
+     * - Supports limiting results via `filterOptions.limit`.
+     * - **Does not** support sorting (`filterOptions.sort`), skipping (`filterOptions.skip`), complex operators (like $gt, $in), or nested property filtering.
+     * @template T - The expected type of the items in the collection.
+     * @param collection - The name of the collection to query.
+     * @param filterOptions - Options for filtering and limiting the results.
+     * @returns A promise resolving to an array of deep copies of the matching items.
      */
     query<T>(collection: string, filterOptions: FilterOptions): Promise<T[]>;
     /**
-     * Clears all items from a specific collection.
-     * @param collection The name of the collection to clear.
+     * Removes all items from a specific collection within the in-memory store.
+     * @param collection - The name of the collection to clear.
+     * @returns A promise that resolves when the collection is cleared.
      */
     clearCollection(collection: string): Promise<void>;
     /**
-     * Clears all data managed by the adapter.
+     * Removes all collections and all data stored within the adapter instance.
+     * Use with caution, especially during testing.
+     * @returns A promise that resolves when all data is cleared.
      */
     clearAll(): Promise<void>;
 }
 
 /**
- * Configuration options for the IndexedDBStorageAdapter.
+ * Configuration options for initializing the `IndexedDBStorageAdapter`.
  */
 interface IndexedDBConfig {
+    /** The name of the IndexedDB database to use. Defaults to 'ART_Framework_DB'. */
     dbName?: string;
+    /** The version of the database schema. Increment this when changing `objectStores` or indexes to trigger an upgrade. Defaults to 1. */
     dbVersion?: number;
+    /** An array of strings specifying the names of the object stores (collections) required by the application. Core stores like 'conversations', 'observations', 'state' are usually added automatically. */
     objectStores: string[];
 }
 /**
- * An implementation of the StorageAdapter interface using IndexedDB
- * for persistent storage in the browser.
+ * An implementation of the `StorageAdapter` interface that uses the browser's
+ * IndexedDB API for persistent, client-side storage.
+ *
+ * This adapter is suitable for web applications where conversation history,
+ * agent state, and observations need to persist across sessions.
+ *
+ * **Important:** The `init()` method *must* be called and awaited before performing
+ * any other database operations (get, set, delete, query).
+ *
+ * @implements {StorageAdapter}
  */
 declare class IndexedDBStorageAdapter implements StorageAdapter {
     private db;
@@ -763,78 +1337,235 @@ declare class IndexedDBStorageAdapter implements StorageAdapter {
     private dbVersion;
     private requiredObjectStores;
     private initPromise;
+    /**
+     * Creates an instance of IndexedDBStorageAdapter.
+     * Note: The database connection is not opened until `init()` is called.
+     * @param config - Configuration options including database name, version, and required object stores.
+     */
     constructor(config: IndexedDBConfig);
     /**
-     * Initializes the IndexedDB database connection and ensures object stores exist.
-     * This method should be called before any other operations.
+     * Opens the IndexedDB database connection and ensures the required object stores
+     * are created or updated based on the configured `dbVersion`.
+     * This method MUST be called and awaited successfully before using other adapter methods.
+     * It handles the `onupgradeneeded` event to create stores.
+     * @returns A promise that resolves when the database is successfully opened and ready, or rejects on error.
      */
     init(): Promise<void>;
+    /**
+     * Helper method to create and return an IndexedDB transaction.
+     * Ensures the database is initialized and the requested store(s) exist.
+     * @param storeName - The name of the object store or an array of store names for the transaction.
+     * @param mode - The transaction mode ('readonly' or 'readwrite').
+     * @returns The initiated IDBTransaction.
+     * @throws {Error} If the database is not initialized or if a requested store does not exist.
+     */
     private getTransaction;
+    /**
+     * Retrieves a single item by its ID from the specified object store (collection).
+     * @template T - The expected type of the retrieved item.
+     * @param collection - The name of the object store.
+     * @param id - The ID (key) of the item to retrieve.
+     * @returns A promise resolving to a copy of the item if found, or `null` otherwise.
+     * @throws {Error} If the database is not initialized, the store doesn't exist, or a database error occurs.
+     */
     get<T>(collection: string, id: string): Promise<T | null>;
+    /**
+     * Saves (creates or updates) an item in the specified object store (collection).
+     * Assumes the object store uses 'id' as its keyPath. The `id` parameter provided
+     * should match the `id` property within the `data` object.
+     * Uses `structuredClone` to store a deep copy.
+     * @template T - The type of the data being saved. Must have an 'id' property.
+     * @param collection - The name of the object store.
+     * @param id - The unique ID of the item (should match `data.id`).
+     * @param data - The data object to save. Must contain an `id` property matching the `id` parameter.
+     * @returns A promise that resolves when the data is successfully saved.
+     * @throws {Error} If the database is not initialized, the store doesn't exist, data is missing the 'id' property, or a database error occurs.
+     */
     set<T>(collection: string, id: string, data: T): Promise<void>;
+    /**
+     * Deletes an item from the specified object store (collection) by its ID.
+     * @param collection - The name of the object store.
+     * @param id - The ID (key) of the item to delete.
+     * @returns A promise that resolves when the deletion is successful.
+     * @throws {Error} If the database is not initialized, the store doesn't exist, or a database error occurs.
+     */
     delete(collection: string, id: string): Promise<void>;
+    /**
+     * Queries items within a collection based on provided filter options.
+     * **Note:** This implementation uses `getAll()` and performs filtering, sorting,
+     * and limiting **client-side**. For large datasets, performance may be suboptimal.
+     * A more advanced version would leverage IndexedDB indexes and cursors for
+     * efficient querying directly within the database.
+     * Supports basic exact-match filtering and single-key sorting.
+     * @template T - The expected type of the items in the collection.
+     * @param collection - The name of the object store to query.
+     * @param filterOptions - Options for filtering, sorting, skipping, and limiting results.
+     * @returns A promise resolving to an array of deep copies of the matching items.
+     * @throws {Error} If the database is not initialized, the store doesn't exist, or a database error occurs.
+     */
     query<T>(collection: string, filterOptions: FilterOptions): Promise<T[]>;
+    /**
+     * Removes all items from a specific object store (collection).
+     * @param collection - The name of the object store to clear.
+     * @returns A promise that resolves when the collection is successfully cleared.
+     * @throws {Error} If the database is not initialized, the store doesn't exist, or a database error occurs.
+     */
     clearCollection(collection: string): Promise<void>;
+    /**
+     * Removes all data from all object stores managed by this adapter instance within the database.
+     * Use with caution as this is destructive.
+     * @returns A promise that resolves when all specified object stores have been cleared.
+     * @throws {Error} If the database is not initialized or a transaction error occurs.
+     */
     clearAll(): Promise<void>;
 }
 
+/**
+ * Configuration options required for the `GeminiAdapter`.
+ */
 interface GeminiAdapterOptions {
+    /** Your Google AI API key (e.g., from Google AI Studio). Handle securely. */
     apiKey: string;
+    /** The default Gemini model ID to use (e.g., 'gemini-1.5-flash-latest', 'gemini-pro'). Defaults to 'gemini-1.5-flash-latest' if not provided. */
     model?: string;
+    /** Optional: Override the base URL for the Google Generative AI API. */
     apiBaseUrl?: string;
+    /** Optional: Specify the API version to use (e.g., 'v1beta'). Defaults to 'v1beta'. */
     apiVersion?: string;
 }
 declare class GeminiAdapter implements ProviderAdapter {
     readonly providerName = "gemini";
     private apiKey;
-    private model;
-    private apiBaseUrl;
-    private apiVersion;
+    private defaultModel;
+    private genAI;
+    /**
+     * Creates an instance of GeminiAdapter.
+     * @param {GeminiAdapterOptions} options - Configuration options for the adapter.
+     * @throws {Error} If `apiKey` is missing in the options.
+     */
     constructor(options: GeminiAdapterOptions);
     /**
-     * Calls the Google Generative AI API (Gemini).
-     * Note: Assumes prompt is a string for basic user input.
-     *       Does not yet handle complex history or system prompts.
-     *       `onThought` is not implemented (requires streaming API).
-     * @param prompt - Treated as the user message content.
-     * @param options - Call options including LLM parameters.
-     * @returns The content string from the API response.
+     * Makes a call to the configured Gemini model.
+     * Translates the `ArtStandardPrompt` into the Gemini API format, sends the request
+     * using the `@google/genai` SDK, and yields `StreamEvent` objects representing
+     * the response (tokens, metadata, errors, end signal).
+     *
+     * Handles both streaming and non-streaming requests based on `options.stream`.
+     *
+     * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
+     * @param {CallOptions} options - Options for the LLM call, including streaming preference, model override, and execution context.
+     * @returns {Promise<AsyncIterable<StreamEvent>>} An async iterable that yields `StreamEvent` objects.
+     *   - `TOKEN`: Contains a chunk of the response text. `tokenType` indicates if it's part of agent thought or final synthesis.
+     *   - `METADATA`: Contains information like stop reason, token counts, and timing, yielded once at the end.
+     *   - `ERROR`: Contains any error encountered during translation, SDK call, or response processing.
+     *   - `END`: Signals the completion of the stream.
+     * @see {ArtStandardPrompt}
+     * @see {CallOptions}
+     * @see {StreamEvent}
+     * @see {LLMMetadata}
+     */
+    call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
+    /**
+     * Translates the provider-agnostic `ArtStandardPrompt` into the Gemini API's `Content[]` format.
+     *
+     * Key translations:
+     * - `system` role: Merged into the first `user` message.
+     * - `user` role: Maps to Gemini's `user` role.
+     * - `assistant` role: Maps to Gemini's `model` role. Handles text content and `tool_calls` (mapped to `functionCall`).
+     * - `tool_result` role: Maps to Gemini's `user` role with a `functionResponse` part.
+     * - `tool_request` role: Skipped (implicitly handled by `assistant`'s `tool_calls`).
+     *
+     * Adds validation to ensure the conversation doesn't start with a 'model' role.
+     *
+     * @private
+     * @param {ArtStandardPrompt} artPrompt - The input `ArtStandardPrompt` array.
+     * @returns {Content[]} The `Content[]` array formatted for the Gemini API.
+     * @throws {ARTError} If translation encounters an issue, such as a `tool_result` missing required fields (ErrorCode.PROMPT_TRANSLATION_FAILED).
+     * @see https://ai.google.dev/api/rest/v1beta/Content
      */
-    call(prompt: FormattedPrompt, options: CallOptions): Promise<string>;
+    private translateToGemini;
 }
 
+/**
+ * Configuration options required for the `OpenAIAdapter`.
+ */
 interface OpenAIAdapterOptions {
+    /** Your OpenAI API key. Handle securely. */
     apiKey: string;
+    /** The default OpenAI model ID to use (e.g., 'gpt-4o', 'gpt-4o-mini'). Defaults to 'gpt-3.5-turbo' if not provided. */
     model?: string;
+    /** Optional: Override the base URL for the OpenAI API (e.g., for Azure OpenAI or custom proxies). */
     apiBaseUrl?: string;
 }
+/**
+ * Implements the `ProviderAdapter` interface for interacting with OpenAI's
+ * Chat Completions API (compatible models like GPT-3.5, GPT-4, GPT-4o).
+ *
+ * Handles formatting requests and parsing responses for OpenAI.
+ * Uses raw `fetch` for now.
+ *
+ * @implements {ProviderAdapter}
+ */
 declare class OpenAIAdapter implements ProviderAdapter {
     readonly providerName = "openai";
     private apiKey;
     private model;
     private apiBaseUrl;
+    /**
+     * Creates an instance of the OpenAIAdapter.
+     * @param options - Configuration options including the API key and optional model/baseURL overrides.
+     * @throws {Error} If the API key is missing.
+     */
     constructor(options: OpenAIAdapterOptions);
     /**
-     * Calls the OpenAI Chat Completions API.
-     * Note: This basic implementation assumes the FormattedPrompt is a string
-     *       representing the user's message or a pre-formatted structure.
-     *       It doesn't yet handle complex history formatting or system prompts
-     *       directly from the FormattedPrompt type itself.
-     *       The `onThought` callback is not implemented in this non-streaming version.
-     * @param prompt - For this basic version, treated as the primary user message content.
-     *                 A more robust version would parse a structured prompt object.
-     * @param options - Call options, including threadId, traceId, and LLM parameters.
-     * @returns The content string from the API response.
+     * Sends a request to the OpenAI Chat Completions API.
+     * Translates `ArtStandardPrompt` to the OpenAI format, handles streaming and non-streaming responses.
+     *
+     * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
+     * @param {CallOptions} options - Call options, including `threadId`, `traceId`, `stream` preference, and any OpenAI-specific parameters (like `temperature`, `max_tokens`) passed through.
+     * @returns {Promise<AsyncIterable<StreamEvent>>} A promise resolving to an AsyncIterable of StreamEvent objects.
+     */
+    call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
+    /**
+      * Processes the Server-Sent Events (SSE) stream from OpenAI.
+      * @param stream - The ReadableStream from the fetch response.
+      * @param options - The original CallOptions containing threadId, traceId, sessionId, and callContext.
+      * @returns An AsyncIterable yielding StreamEvent objects.
+      */
+    private processStream;
+    /**
+     * Translates the provider-agnostic `ArtStandardPrompt` into the OpenAI API's `OpenAIMessage[]` format.
+     *
+     * @private
+     * @param {ArtStandardPrompt} artPrompt - The input `ArtStandardPrompt` array.
+     * @returns {OpenAIMessage[]} The `OpenAIMessage[]` array formatted for the OpenAI API.
+     * @throws {ARTError} If translation encounters an issue (ErrorCode.PROMPT_TRANSLATION_FAILED).
      */
-    call(prompt: FormattedPrompt, options: CallOptions): Promise<string>;
+    private translateToOpenAI;
 }
 
+/**
+ * Configuration options required for the `AnthropicAdapter`.
+ */
 interface AnthropicAdapterOptions {
+    /** Your Anthropic API key. Handle securely. */
     apiKey: string;
+    /** The default Anthropic model ID to use (e.g., 'claude-3-opus-20240229', 'claude-3-5-sonnet-20240620'). Defaults to 'claude-3-haiku-20240307' if not provided. */
     model?: string;
+    /** Optional: The Anthropic API version to target (e.g., '2023-06-01'). Defaults to '2023-06-01'. */
     apiVersion?: string;
+    /** Optional: Override the base URL for the Anthropic API. */
     apiBaseUrl?: string;
 }
+/**
+ * Implements the `ProviderAdapter` interface for interacting with Anthropic's
+ * Messages API (Claude models).
+ *
+ * Handles formatting requests and parsing responses for Anthropic.
+ * Note: Streaming is **not yet implemented** for this adapter. Calls requesting streaming will yield an error and end.
+ *
+ * @implements {ProviderAdapter}
+ */
 declare class AnthropicAdapter implements ProviderAdapter {
     readonly providerName = "anthropic";
     private apiKey;
@@ -842,26 +1573,65 @@ declare class AnthropicAdapter implements ProviderAdapter {
     private apiVersion;
     private apiBaseUrl;
     private defaultMaxTokens;
+    /**
+     * Creates an instance of the AnthropicAdapter.
+     * @param options - Configuration options including the API key and optional model/apiVersion/baseURL overrides.
+     * @throws {Error} If the API key is missing.
+     */
     constructor(options: AnthropicAdapterOptions);
     /**
-     * Calls the Anthropic Messages API.
-     * Note: Assumes prompt is a string for basic user input.
-     *       Does not yet handle complex history or system prompts robustly.
-     *       `onThought` is not implemented (requires streaming API).
-     * @param prompt - Treated as the user message content.
-     * @param options - Call options including LLM parameters. Requires max_tokens/maxOutputTokens.
-     * @returns The content string from the API response.
+     * Sends a request to the Anthropic Messages API.
+     * Translates `ArtStandardPrompt` to the Anthropic format.
+     *
+     * **Note:** Streaming is **not yet implemented**.
+     *
+     * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
+     * @param {CallOptions} options - Call options, including `threadId`, `traceId`, `stream`, and any Anthropic-specific generation parameters.
+     * @returns {Promise<AsyncIterable<StreamEvent>>} A promise resolving to an AsyncIterable of StreamEvent objects. If streaming is requested, it yields an error event and ends.
+     * @throws {ARTError} If `max_tokens` is missing in options (required by Anthropic).
+     */
+    call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
+    /**
+     * Translates the provider-agnostic `ArtStandardPrompt` into the Anthropic Messages API format.
+     *
+     * @private
+     * @param {ArtStandardPrompt} artPrompt - The input `ArtStandardPrompt` array.
+     * @returns {{ systemPrompt?: string; messages: AnthropicMessage[] }} The system prompt string and the `AnthropicMessage[]` array.
+     * @throws {ARTError} If translation encounters an issue (ErrorCode.PROMPT_TRANSLATION_FAILED).
      */
-    call(prompt: FormattedPrompt, options: CallOptions): Promise<string>;
+    private translateToAnthropic;
+    /**
+     * Helper to map ArtStandardMessage content/tool_calls to Anthropic Content Blocks.
+     * @private
+     */
+    private mapArtContentToAnthropicBlocks;
 }
 
+/**
+ * Configuration options required for the `OpenRouterAdapter`.
+ */
 interface OpenRouterAdapterOptions {
+    /** Your OpenRouter API key. Handle securely. */
     apiKey: string;
+    /** The required OpenRouter model identifier string (e.g., 'google/gemini-pro', 'anthropic/claude-3-haiku', 'openai/gpt-4o'). This specifies which underlying model OpenRouter should use. */
     model: string;
+    /** Optional: Override the base URL for the OpenRouter API. Defaults to 'https://openrouter.ai/api/v1'. */
     apiBaseUrl?: string;
+    /** Optional: Your application's site URL, sent as the 'HTTP-Referer' header (recommended by OpenRouter). */
     siteUrl?: string;
+    /** Optional: Your application's name, sent as the 'X-Title' header (recommended by OpenRouter). */
     appName?: string;
 }
+/**
+ * Implements the `ProviderAdapter` interface for interacting with the OpenRouter API,
+ * which provides access to various LLMs through an OpenAI-compatible interface.
+ *
+ * Handles formatting requests and parsing responses for OpenRouter's chat completions endpoint.
+ * Handles formatting requests and parsing responses for OpenRouter's chat completions endpoint.
+ * Note: Streaming is **not yet implemented** for this adapter. Calls requesting streaming will yield an error and end.
+ *
+ * @implements {ProviderAdapter}
+ */
 declare class OpenRouterAdapter implements ProviderAdapter {
     readonly providerName = "openrouter";
     private apiKey;
@@ -869,69 +1639,139 @@ declare class OpenRouterAdapter implements ProviderAdapter {
     private apiBaseUrl;
     private siteUrl?;
     private appName?;
+    /**
+     * Creates an instance of the OpenRouterAdapter.
+     * @param options - Configuration options including the API key, the specific OpenRouter model identifier, and optional headers/baseURL.
+     * @throws {Error} If the API key or model identifier is missing.
+     */
     constructor(options: OpenRouterAdapterOptions);
     /**
-     * Calls the OpenRouter Chat Completions API (OpenAI compatible).
-     * Note: Assumes prompt is a string for basic user input.
-     *       Does not yet handle complex history or system prompts robustly.
-     *       `onThought` is not implemented (requires streaming API).
-     * @param prompt - Treated as the user message content.
-     * @param options - Call options including LLM parameters.
-     * @returns The content string from the API response.
+     * Sends a request to the OpenRouter Chat Completions API endpoint.
+     * Translates `ArtStandardPrompt` to the OpenAI-compatible format.
+     *
+     * **Note:** Streaming is **not yet implemented**.
+     *
+     * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
+     * @param {CallOptions} options - Call options, including `threadId`, `traceId`, `stream`, and any OpenAI-compatible generation parameters.
+     * @returns {Promise<AsyncIterable<StreamEvent>>} A promise resolving to an AsyncIterable of StreamEvent objects. If streaming is requested, it yields an error event and ends.
+     */
+    call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
+    /**
+     * Translates the provider-agnostic `ArtStandardPrompt` into the OpenAI API's `OpenAIMessage[]` format.
+     * (Copied from OpenAIAdapter - assumes OpenRouter compatibility)
+     *
+     * @private
+     * @param {ArtStandardPrompt} artPrompt - The input `ArtStandardPrompt` array.
+     * @returns {OpenAIMessage[]} The `OpenAIMessage[]` array formatted for the OpenAI API.
+     * @throws {ARTError} If translation encounters an issue (ErrorCode.PROMPT_TRANSLATION_FAILED).
      */
-    call(prompt: FormattedPrompt, options: CallOptions): Promise<string>;
+    private translateToOpenAI;
 }
 
+/**
+ * Configuration options required for the `DeepSeekAdapter`.
+ */
 interface DeepSeekAdapterOptions {
+    /** Your DeepSeek API key. Handle securely. */
     apiKey: string;
+    /** The default DeepSeek model ID to use (e.g., 'deepseek-chat', 'deepseek-coder'). Defaults to 'deepseek-chat' if not provided. */
     model?: string;
+    /** Optional: Override the base URL for the DeepSeek API. Defaults to 'https://api.deepseek.com/v1'. */
     apiBaseUrl?: string;
 }
+/**
+ * Implements the `ProviderAdapter` interface for interacting with the DeepSeek API,
+ * which uses an OpenAI-compatible Chat Completions endpoint.
+ *
+ * Handles formatting requests and parsing responses for DeepSeek models.
+ * Note: Streaming is **not yet implemented** for this adapter. Calls requesting streaming will yield an error and end.
+ *
+ * @implements {ProviderAdapter}
+ */
 declare class DeepSeekAdapter implements ProviderAdapter {
     readonly providerName = "deepseek";
     private apiKey;
     private model;
     private apiBaseUrl;
+    /**
+     * Creates an instance of the DeepSeekAdapter.
+     * @param options - Configuration options including the API key and optional model/baseURL overrides.
+     * @throws {Error} If the API key is missing.
+     */
     constructor(options: DeepSeekAdapterOptions);
     /**
-     * Calls the DeepSeek Chat Completions API (OpenAI compatible).
-     * Note: Assumes prompt is a string for basic user input.
-     *       Does not yet handle complex history or system prompts robustly.
-     *       `onThought` is not implemented (requires streaming API).
-     * @param prompt - Treated as the user message content.
-     * @param options - Call options including LLM parameters.
-     * @returns The content string from the API response.
+     * Sends a request to the DeepSeek Chat Completions API endpoint.
+     * Translates `ArtStandardPrompt` to the OpenAI-compatible format.
+     *
+     * **Note:** Streaming is **not yet implemented**.
+     *
+     * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
+     * @param {CallOptions} options - Call options, including `threadId`, `traceId`, `stream`, and any OpenAI-compatible generation parameters.
+     * @returns {Promise<AsyncIterable<StreamEvent>>} A promise resolving to an AsyncIterable of StreamEvent objects. If streaming is requested, it yields an error event and ends.
+     */
+    call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
+    /**
+     * Translates the provider-agnostic `ArtStandardPrompt` into the OpenAI API's `OpenAIMessage[]` format.
+     * (Copied from OpenAIAdapter - assumes DeepSeek compatibility)
+     *
+     * @private
+     * @param {ArtStandardPrompt} artPrompt - The input `ArtStandardPrompt` array.
+     * @returns {OpenAIMessage[]} The `OpenAIMessage[]` array formatted for the OpenAI API.
+     * @throws {ARTError} If translation encounters an issue (ErrorCode.PROMPT_TRANSLATION_FAILED).
      */
-    call(prompt: FormattedPrompt, options: CallOptions): Promise<string>;
+    private translateToOpenAI;
 }
 
+/**
+ * An ART Framework tool that safely evaluates mathematical expressions using the mathjs library.
+ * It supports basic arithmetic, variables via a scope, complex numbers, and a predefined list of safe functions.
+ *
+ * @implements {IToolExecutor}
+ */
 declare class CalculatorTool implements IToolExecutor {
+    /** The unique name identifier for this tool. */
     static readonly toolName = "calculator";
+    /** Store for previous calculation results by threadId */
+    private resultStore;
+    /**
+     * The schema definition for the CalculatorTool, conforming to the `ToolSchema` interface.
+     * It defines the tool's name, description, input parameters (expression and optional scope),
+     * and provides examples for the LLM.
+     */
     readonly schema: ToolSchema;
+    /**
+    * Executes the calculator tool by evaluating the provided mathematical expression.
+    * It uses a restricted scope including only allowed mathjs functions and any variables
+    * passed in the `input.scope`. Handles basic number and complex number results.
+    *
+    * @param input - An object containing the `expression` (string) and optional `scope` (object). Must match `inputSchema`.
+    * @param context - The execution context containing `threadId`, `traceId`, etc.
+    * @returns A promise resolving to a `ToolResult` object.
+    *          On success, `status` is 'success' and `output` is `{ result: number | string }`.
+    *          On failure, `status` is 'error' and `error` contains the error message.
+    */
     execute(input: any, context: ExecutionContext): Promise<ToolResult>;
 }
 
-declare enum LogLevel {
-    DEBUG = 0,
-    INFO = 1,
-    WARN = 2,
-    ERROR = 3
-}
-interface LoggerConfig {
-    level: LogLevel;
-    prefix?: string;
-}
-declare class Logger {
-    private static config;
-    static configure(config: Partial<LoggerConfig>): void;
-    static debug(message: string, ...args: any[]): void;
-    static info(message: string, ...args: any[]): void;
-    static warn(message: string, ...args: any[]): void;
-    static error(message: string, ...args: any[]): void;
-}
-
+/**
+ * Generates a unique Version 4 UUID (Universally Unique Identifier) string.
+ * Uses the underlying 'uuid' library's v4 implementation.
+ * @returns A randomly generated UUID string (e.g., "f47ac10b-58cc-4372-a567-0e02b2c3d479").
+ */
 declare const generateUUID: () => string;
 
+/**
+ * Main entry point for the ART Framework library.
+ * This file exports the primary factory function (`createArtInstance`),
+ * core components, adapters, types, interfaces, and utilities needed
+ * to build and run ART agents.
+ */
+/**
+ * The main function to create and initialize an ART instance.
+ * @see {@link ./core/agent-factory.ts} for implementation details.
+ */
+
+/** The current version of the ART Framework package. */
 declare const VERSION = "0.2.4";
 
-export { type AgentFinalResponse, type AgentOptions, type AgentProps, type AgentState, AnthropicAdapter, type ArtInstance, CalculatorTool, type CallOptions, type ConversationManager, type ConversationMessage, type ConversationSocket, DeepSeekAdapter, type ExecutionContext, type ExecutionMetadata, type FilterOptions, type FormattedPrompt, GeminiAdapter, type IAgentCore, type IConversationRepository, type IObservationRepository, type IStateRepository, type IToolExecutor, InMemoryStorageAdapter, IndexedDBStorageAdapter, type JsonObjectSchema, type JsonSchema, LogLevel, Logger, type MessageOptions, MessageRole, type Observation, type ObservationFilter, type ObservationManager, type ObservationSocket, ObservationType, OpenAIAdapter, OpenRouterAdapter, type OutputParser, PESAgent, type ParsedToolCall, type PromptManager, type ProviderAdapter, type ReasoningEngine, type StateManager, type StorageAdapter, type ThreadConfig, type ThreadContext, type ToolRegistry, type ToolResult, type ToolSchema, type ToolSystem, type TypedSocket, type UISystem, VERSION, createArtInstance, generateUUID };
+export { type AgentFinalResponse, type AgentOptions, type AgentProps, type AgentState, AnthropicAdapter, type ArtInstance, type ArtStandardMessage, type ArtStandardMessageRole, type ArtStandardPrompt, type AvailableProviderEntry, CalculatorTool, type CallOptions, type ConversationManager, type ConversationMessage, type ConversationSocket, DeepSeekAdapter, type ExecutionContext, type ExecutionMetadata, type FilterOptions, type FormattedPrompt, GeminiAdapter, type IAgentCore, type IConversationRepository, type IObservationRepository, type IProviderManager, type IStateRepository, type IToolExecutor, InMemoryStorageAdapter, IndexedDBStorageAdapter, type JsonObjectSchema, type JsonSchema, type LLMMetadata, LogLevel, Logger, type ManagedAdapterAccessor, type MessageOptions, MessageRole, ModelCapability, type Observation, type ObservationFilter, type ObservationManager, type ObservationSocket, ObservationType, OpenAIAdapter, OpenRouterAdapter, type OutputParser, PESAgent, type ParsedToolCall, type PromptContext, type PromptManager, type ProviderAdapter, type ProviderManagerConfig, type ReasoningEngine, type RuntimeProviderConfig, type StateManager, type StorageAdapter, type StreamEvent, type ThreadConfig, type ThreadContext, type ToolRegistry, type ToolResult, type ToolSchema, type ToolSystem, type TypedSocket, type UISystem, VERSION, createArtInstance, generateUUID };