art-framework 0.2.6 → 0.2.8

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 type UnsubscribeFunction = () => void;
 interface Subscription<DataType, FilterType> {
     id: string;
@@ -11,7 +13,7 @@ interface Subscription<DataType, FilterType> {
  * 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> {
+declare class TypedSocket<DataType, FilterType = any> {
     protected subscriptions: Map<string, Subscription<DataType, FilterType>>;
     constructor();
     /**
@@ -88,6 +90,306 @@ interface IProviderManager {
     getAdapter(config: RuntimeProviderConfig): Promise<ManagedAdapterAccessor>;
 }
 
+/**
+ * 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;
+}
+
+/**
+ * Defines standard error codes for the ART framework.
+ */
+declare enum ErrorCode {
+    INVALID_CONFIG = "INVALID_CONFIG",
+    MISSING_API_KEY = "MISSING_API_KEY",
+    STORAGE_ERROR = "STORAGE_ERROR",
+    THREAD_NOT_FOUND = "THREAD_NOT_FOUND",
+    SAVE_FAILED = "SAVE_FAILED",
+    LLM_PROVIDER_ERROR = "LLM_PROVIDER_ERROR",
+    PROMPT_GENERATION_FAILED = "PROMPT_GENERATION_FAILED",
+    OUTPUT_PARSING_FAILED = "OUTPUT_PARSING_FAILED",
+    PROMPT_ASSEMBLY_FAILED = "PROMPT_ASSEMBLY_FAILED",// Error during prompt template rendering or initial structure creation (legacy, might be removed)
+    PROMPT_FRAGMENT_NOT_FOUND = "PROMPT_FRAGMENT_NOT_FOUND",// Requested prompt fragment does not exist
+    PROMPT_VALIDATION_FAILED = "PROMPT_VALIDATION_FAILED",// Constructed prompt object failed schema validation
+    PROMPT_TRANSLATION_FAILED = "PROMPT_TRANSLATION_FAILED",// Added for Adapter translation
+    TOOL_NOT_FOUND = "TOOL_NOT_FOUND",
+    TOOL_SCHEMA_VALIDATION_FAILED = "TOOL_SCHEMA_VALIDATION_FAILED",
+    TOOL_EXECUTION_ERROR = "TOOL_EXECUTION_ERROR",// Generic tool execution error
+    TOOL_DISABLED = "TOOL_DISABLED",
+    PLANNING_FAILED = "PLANNING_FAILED",
+    TOOL_EXECUTION_FAILED = "TOOL_EXECUTION_FAILED",// Error within the ToolSystem execution loop
+    SYNTHESIS_FAILED = "SYNTHESIS_FAILED",
+    AGENT_PROCESSING_ERROR = "AGENT_PROCESSING_ERROR",// General error during agent.process
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TIMEOUT_ERROR = "TIMEOUT_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    UNKNOWN_PROVIDER = "UNKNOWN_PROVIDER",// Checklist item 4.7
+    LOCAL_PROVIDER_CONFLICT = "LOCAL_PROVIDER_CONFLICT",// Checklist item 4.7
+    LOCAL_INSTANCE_BUSY = "LOCAL_INSTANCE_BUSY",// Checklist item 4.7
+    API_QUEUE_TIMEOUT = "API_QUEUE_TIMEOUT",// Checklist item 4.7 (optional)
+    ADAPTER_INSTANTIATION_ERROR = "ADAPTER_INSTANTIATION_ERROR"
+}
+/**
+ * Custom error class for ART framework specific errors.
+ */
+declare class ARTError extends Error {
+    readonly code: ErrorCode;
+    readonly originalError?: Error;
+    constructor(message: string, code: ErrorCode, originalError?: Error);
+    toString(): string;
+}
+declare class UnknownProviderError extends ARTError {
+    constructor(providerName: string);
+}
+declare class LocalProviderConflictError extends ARTError {
+    constructor(requestedProvider: string, activeProvider: string);
+}
+declare class LocalInstanceBusyError extends ARTError {
+    constructor(providerName: string, modelId: string);
+}
+declare class ApiQueueTimeoutError extends ARTError {
+    constructor(providerName: string);
+}
+declare class AdapterInstantiationError extends ARTError {
+    constructor(providerName: string, originalError: Error);
+}
+
+/**
+ * Zod schema for validating a single ArtStandardMessage object.
+ */
+declare const ArtStandardMessageSchema: z.ZodEffects<z.ZodObject<{
+    role: z.ZodType<ArtStandardMessageRole, z.ZodTypeDef, ArtStandardMessageRole>;
+    content: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodNull]>;
+    name: z.ZodOptional<z.ZodString>;
+    tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            arguments: string;
+        }, {
+            name: string;
+            arguments: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }, {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }>, "many">>;
+    tool_call_id: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    role: ArtStandardMessageRole;
+    content: string | Record<string, any> | null;
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+    tool_call_id?: string | undefined;
+}, {
+    role: ArtStandardMessageRole;
+    content: string | Record<string, any> | null;
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+    tool_call_id?: string | undefined;
+}>, {
+    role: ArtStandardMessageRole;
+    content: string | Record<string, any> | null;
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+    tool_call_id?: string | undefined;
+}, {
+    role: ArtStandardMessageRole;
+    content: string | Record<string, any> | null;
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+    tool_call_id?: string | undefined;
+}>;
+/**
+ * Zod schema for validating an entire ArtStandardPrompt (an array of messages).
+ */
+declare const ArtStandardPromptSchema: z.ZodArray<z.ZodEffects<z.ZodObject<{
+    role: z.ZodType<ArtStandardMessageRole, z.ZodTypeDef, ArtStandardMessageRole>;
+    content: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodNull]>;
+    name: z.ZodOptional<z.ZodString>;
+    tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            arguments: string;
+        }, {
+            name: string;
+            arguments: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }, {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }>, "many">>;
+    tool_call_id: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    role: ArtStandardMessageRole;
+    content: string | Record<string, any> | null;
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+    tool_call_id?: string | undefined;
+}, {
+    role: ArtStandardMessageRole;
+    content: string | Record<string, any> | null;
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+    tool_call_id?: string | undefined;
+}>, {
+    role: ArtStandardMessageRole;
+    content: string | Record<string, any> | null;
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+    tool_call_id?: string | undefined;
+}, {
+    role: ArtStandardMessageRole;
+    content: string | Record<string, any> | null;
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+    tool_call_id?: string | undefined;
+}>, "many">;
+
 /**
  * Represents the role of a message sender in a conversation.
  */
@@ -332,13 +634,19 @@ interface ThreadConfig {
     enabledTools: string[];
     /** The maximum number of past messages (`ConversationMessage` objects) to retrieve for context. */
     historyLimit: number;
+    /** Optional system prompt string to be used for this thread, overriding instance or agent defaults. */
+    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. */
+    /** The primary data payload of the agent's state. Structure is application-defined. */
+    data: any;
+    /** An optional version number for the agent's state, useful for migrations or tracking changes. */
+    version?: number;
+    /** Allows for other arbitrary properties to be stored in the agent's state. */
     [key: string]: any;
 }
 /**
@@ -386,6 +694,8 @@ interface AgentOptions {
     stream?: boolean;
     /** Override the prompt template used for this specific call. */
     promptTemplateId?: string;
+    /** Optional system prompt string to override thread, instance, or agent defaults for this specific call. */
+    systemPrompt?: string;
 }
 /**
  * The final structured response returned by the agent core after processing.
@@ -609,13 +919,70 @@ interface ObservationFilter {
     /** Retrieve observations recorded after this Unix timestamp (milliseconds). */
     afterTimestamp?: number;
 }
+/**
+ * Defines the strategy for saving AgentState.
+ * - 'explicit': AgentState is only saved when `StateManager.setAgentState()` is explicitly called by the agent.
+ *               `StateManager.saveStateIfModified()` will be a no-op for AgentState persistence.
+ * - 'implicit': AgentState is loaded by `StateManager.loadThreadContext()`, and if modified by the agent,
+ *               `StateManager.saveStateIfModified()` will attempt to automatically persist these changes
+ *               by comparing the current state with a snapshot taken at load time.
+ *               `StateManager.setAgentState()` will still work for explicit saves.
+ */
+type StateSavingStrategy = 'explicit' | 'implicit';
+
+/**
+ * Configuration for creating an ART instance.
+ */
+interface ArtInstanceConfig {
+    /**
+     * Configuration for the storage adapter.
+     * Can be a pre-configured `StorageAdapter` instance,
+     * or an object specifying the type and options for a built-in adapter.
+     * Example: `{ type: 'indexedDB', dbName: 'MyArtDB' }`
+     */
+    storage: StorageAdapter | {
+        type: 'memory' | 'indexedDB';
+        dbName?: string;
+        version?: number;
+        objectStores?: any[];
+    };
+    /** Configuration for the ProviderManager, defining available LLM provider adapters. */
+    providers: ProviderManagerConfig;
+    /**
+     * The agent core implementation class to use.
+     * Defaults to `PESAgent` if not provided.
+     * Example: `MyCustomAgentClass`
+     */
+    agentCore?: new (dependencies: any) => IAgentCore;
+    /** An optional array of tool executor instances to register at initialization. */
+    tools?: IToolExecutor[];
+    /**
+     * Defines the strategy for saving `AgentState`. Defaults to 'explicit'.
+     * - 'explicit': `AgentState` is only saved when `StateManager.setAgentState()` is explicitly called by the agent.
+     *               `StateManager.saveStateIfModified()` will be a no-op for `AgentState` persistence.
+     * - 'implicit': `AgentState` is loaded by `StateManager.loadThreadContext()`. If modified by the agent,
+     *               `StateManager.saveStateIfModified()` will attempt to automatically persist these changes.
+     *               `StateManager.setAgentState()` will still work for explicit saves in this mode.
+     */
+    stateSavingStrategy?: StateSavingStrategy;
+    /** Optional configuration for the framework's logger. */
+    logger?: {
+        /** Minimum log level to output. Defaults to 'info'. */
+        level?: LogLevel;
+    };
+    /**
+     * Optional default system prompt string to be used for the entire ART instance.
+     * This can be overridden at the thread level or at the individual call level.
+     */
+    defaultSystemPrompt?: string;
+}
 
 type StreamEventTypeFilter = StreamEvent['type'] | Array<StreamEvent['type']>;
 /**
  * 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 LLMStreamSocket extends TypedSocket$1<StreamEvent, StreamEventTypeFilter> {
+declare class LLMStreamSocket extends TypedSocket<StreamEvent, StreamEventTypeFilter> {
     constructor();
     /**
      * Notifies subscribers about a new LLM stream event.
@@ -630,7 +997,7 @@ declare class LLMStreamSocket extends TypedSocket$1<StreamEvent, StreamEventType
  * Allows filtering by ObservationType.
  * Can optionally fetch historical observations from a repository.
  */
-declare class ObservationSocket$1 extends TypedSocket$1<Observation, ObservationType | ObservationType[]> {
+declare class ObservationSocket$1 extends TypedSocket<Observation, ObservationType | ObservationType[]> {
     private observationRepository?;
     constructor(observationRepository?: IObservationRepository);
     /**
@@ -656,7 +1023,7 @@ declare class ObservationSocket$1 extends TypedSocket$1<Observation, Observation
  * Allows filtering by MessageRole.
  * Can optionally fetch historical messages from a repository.
  */
-declare class ConversationSocket$1 extends TypedSocket$1<ConversationMessage, MessageRole | MessageRole[]> {
+declare class ConversationSocket$1 extends TypedSocket<ConversationMessage, MessageRole | MessageRole[]> {
     private conversationRepository?;
     constructor(conversationRepository?: IConversationRepository);
     /**
@@ -867,6 +1234,17 @@ interface StateManager {
      * @returns A promise that resolves when the configuration is saved.
      */
     setThreadConfig(threadId: string, config: ThreadConfig): Promise<void>;
+    /**
+     * Sets or updates the AgentState for a specific thread.
+     * This method allows an agent to explicitly persist its internal state.
+     * It requires that a ThreadConfig already exists for the thread, which is typically
+     * ensured by the application calling setThreadConfig() prior to agent execution.
+     * @param threadId - The unique identifier of the thread.
+     * @param state - The AgentState object to save.
+     * @returns A promise that resolves when the state is saved.
+     * @throws {ARTError} If no ThreadConfig exists for the threadId, or if the repository fails.
+     */
+    setAgentState(threadId: string, state: AgentState): Promise<void>;
 }
 /**
  * Interface for managing conversation history.
@@ -911,7 +1289,7 @@ interface ObservationManager {
 /**
  * Generic interface for a typed publish/subscribe socket.
  */
-interface TypedSocket<DataType, FilterType = any> {
+interface ITypedSocket<DataType, FilterType = any> {
     /**
      * Subscribes a callback function to receive data updates.
      * @param callback The function to call with new data.
@@ -945,13 +1323,13 @@ interface TypedSocket<DataType, FilterType = any> {
  * TypedSocket specifically for Observation data.
  * FilterType is ObservationType or array of ObservationType.
  */
-interface ObservationSocket extends TypedSocket<Observation, ObservationType | ObservationType[]> {
+interface ObservationSocket extends ITypedSocket<Observation, ObservationType | ObservationType[]> {
 }
 /**
  * TypedSocket specifically for ConversationMessage data.
  * FilterType is MessageRole or array of MessageRole.
  */
-interface ConversationSocket extends TypedSocket<ConversationMessage, MessageRole | MessageRole[]> {
+interface ConversationSocket extends ITypedSocket<ConversationMessage, MessageRole | MessageRole[]> {
 }
 
 /**
@@ -1042,99 +1420,6 @@ interface ArtInstance {
     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[];
-}
-/**
- * Configuration object required by the AgentFactory and createArtInstance function.
- */
-interface AgentFactoryConfig {
-    /** Configuration for the storage adapter. */
-    storage: StorageConfig;
-    /** 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;
-    };
-}
 /**
  * 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
@@ -1150,7 +1435,7 @@ interface AgentFactoryConfig {
  * });
  * const response = await art.process({ query: "Calculate 5*5", threadId: "thread1" });
  */
-declare function createArtInstance(config: AgentFactoryConfig): Promise<ArtInstance>;
+declare function createArtInstance(config: ArtInstanceConfig): Promise<ArtInstance>;
 
 /**
  * Defines the dependencies required by the PESAgent constructor.
@@ -1159,6 +1444,12 @@ declare function createArtInstance(config: AgentFactoryConfig): Promise<ArtInsta
 interface PESAgentDependencies {
     /** Manages thread configuration and state. */
     stateManager: StateManager;
+    /**
+     * Optional default system prompt string provided at the ART instance level.
+     * This serves as a custom prompt part if no thread-specific or call-specific
+     * system prompt is provided. It's appended to the agent's base system prompt.
+     */
+    instanceDefaultCustomSystemPrompt?: string;
     /** Manages conversation history. */
     conversationManager: ConversationManager;
     /** Registry for available tools. */
@@ -1192,7 +1483,13 @@ interface PESAgentDependencies {
  */
 declare class PESAgent implements IAgentCore {
     private readonly deps;
+    /** The base system prompt inherent to this agent. */
     private readonly defaultSystemPrompt;
+    /**
+     * Stores the instance-level default custom system prompt, passed during construction.
+     * Used in the system prompt hierarchy if no thread or call-level prompt is specified.
+     */
+    private readonly instanceDefaultCustomSystemPrompt?;
     /**
      * Creates an instance of the PESAgent.
      * @param dependencies - An object containing instances of all required subsystems (managers, registries, etc.).
@@ -1202,8 +1499,11 @@ declare class PESAgent implements IAgentCore {
      * 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.
+     * 1.  **Initiation & Config:** Loads thread configuration. Resolves the final system prompt based on a hierarchy:
+     *     Call-level (`AgentProps.options.systemPrompt`) > Thread-level (`ThreadConfig.systemPrompt`) >
+     *     Instance-level (`ArtInstanceConfig.defaultSystemPrompt` via constructor) > Agent's base prompt.
+     *     The resolved custom part is appended to the agent's base prompt.
+     * 2.  **Data Gathering:** Gathers history, available tools, the resolved 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`.
@@ -1730,6 +2030,73 @@ declare class DeepSeekAdapter implements ProviderAdapter {
     private translateToOpenAI;
 }
 
+/**
+ * Configuration options required for the `OllamaAdapter`.
+ */
+interface OllamaAdapterOptions {
+    /**
+     * The base URL for the Ollama API. Defaults to 'http://localhost:11434'.
+     * The '/v1' suffix for OpenAI compatibility will be added automatically.
+     */
+    ollamaBaseUrl?: string;
+    /**
+     * The default Ollama model ID to use (e.g., 'llama3', 'mistral').
+     * This can be overridden by `RuntimeProviderConfig.modelId` or `CallOptions.model`.
+     * It's recommended to set this if you primarily use one model with Ollama.
+     */
+    defaultModel?: string;
+    /**
+     * API key for Ollama (if secured). Defaults to "ollama" as commonly used.
+     */
+    apiKey?: string;
+}
+/**
+ * Implements the `ProviderAdapter` interface for interacting with Ollama's
+ * OpenAI-compatible API endpoint.
+ *
+ * Handles formatting requests, parsing responses, streaming, and tool use.
+ *
+ * @implements {ProviderAdapter}
+ */
+declare class OllamaAdapter implements ProviderAdapter {
+    readonly providerName = "ollama";
+    private client;
+    private defaultModel?;
+    private ollamaBaseUrl;
+    /**
+     * Creates an instance of the OllamaAdapter.
+     * @param options - Configuration options.
+     */
+    constructor(options: OllamaAdapterOptions);
+    /**
+     * Sends a request to the Ollama API.
+     * Translates `ArtStandardPrompt` to the OpenAI format and handles streaming and tool use.
+     *
+     * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
+     * @param {CallOptions} options - Call options.
+     * @returns {Promise<AsyncIterable<StreamEvent>>} A promise resolving to an AsyncIterable of StreamEvent objects.
+     */
+    call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
+    /**
+     * Translates the provider-agnostic `ArtStandardPrompt` into the OpenAI API's `OpenAIMessage[]` format.
+     * This is a common utility function that can be shared or adapted from other OpenAI-compatible adapters.
+     */
+    private translateToOpenAI;
+    private mapArtMessageToOpenAIMessage;
+    /**
+     * Translates ART ToolSchema array to OpenAI's tool format.
+     */
+    private translateArtToolsToOpenAI;
+    /**
+     * Optional method for graceful shutdown.
+     * For Ollama, which is typically a separate local server, this adapter
+     * doesn't manage persistent connections that need explicit closing.
+     * The OpenAI client used internally might have its own cleanup, but
+     * it's generally handled by garbage collection.
+     */
+    shutdown(): Promise<void>;
+}
+
 /**
  * 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.
@@ -1780,6 +2147,6 @@ declare const generateUUID: () => string;
  */
 
 /** The current version of the ART Framework package. */
-declare const VERSION = "0.2.4";
+declare const VERSION = "0.2.8";
 
-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 };
+export { ARTError, AdapterInstantiationError, type AgentFinalResponse, type AgentOptions, type AgentProps, type AgentState, AnthropicAdapter, ApiQueueTimeoutError, type ArtInstance, type ArtInstanceConfig, type ArtStandardMessage, type ArtStandardMessageRole, ArtStandardMessageSchema, type ArtStandardPrompt, ArtStandardPromptSchema, type AvailableProviderEntry, CalculatorTool, type CallOptions, type ConversationManager, type ConversationMessage, type ConversationSocket, DeepSeekAdapter, ErrorCode, type ExecutionContext, type ExecutionMetadata, type FilterOptions, type FormattedPrompt, GeminiAdapter, type IAgentCore, type IConversationRepository, type IObservationRepository, type IProviderManager, type IStateRepository, type IToolExecutor, type ITypedSocket, InMemoryStorageAdapter, IndexedDBStorageAdapter, type JsonObjectSchema, type JsonSchema, type LLMMetadata, LLMStreamSocket, LocalInstanceBusyError, LocalProviderConflictError, LogLevel, Logger, type ManagedAdapterAccessor, type MessageOptions, MessageRole, ModelCapability, type Observation, type ObservationFilter, type ObservationManager, type ObservationSocket, ObservationType, OllamaAdapter, type OllamaAdapterOptions, OpenAIAdapter, OpenRouterAdapter, type OutputParser, PESAgent, type ParsedToolCall, type PromptContext, type PromptManager, type ProviderAdapter, type ProviderManagerConfig, type ReasoningEngine, type RuntimeProviderConfig, type StateManager, type StateSavingStrategy, type StorageAdapter, type StreamEvent, type ThreadConfig, type ThreadContext, type ToolRegistry, type ToolResult, type ToolSchema, type ToolSystem, TypedSocket, type UISystem, UnknownProviderError, type UnsubscribeFunction, VERSION, createArtInstance, generateUUID };