@illalabs/sdk 0.0.0 → 0.1.0-canary.48bfe253

package/dist/src/context/ContextManager.js

@@ -0,0 +1,93 @@
+const DEFAULT_PREFIX = "illa:sdk:ctx";
+const DEFAULT_TOOLS_CONFIG = {};
+const cloneMessageContent = (content) => {
+    if (typeof content === "string") {
+        return content;
+    }
+    return content.map((part) => ({ ...part }));
+};
+const cloneMessages = (messages) => messages.map((message) => ({
+    ...message,
+    content: cloneMessageContent(message.content),
+}));
+const cloneToolsConfig = (config) => structuredClone(config);
+/**
+ * Manages chat context using an injected cache implementation.
+ */
+export class ContextManager {
+    cache;
+    cacheEntryOptions;
+    defaultSnapshot;
+    prefix;
+    constructor(cache, options = {}) {
+        this.cache = cache;
+        this.prefix = options.cacheKeyPrefix ?? DEFAULT_PREFIX;
+        this.cacheEntryOptions = options.cacheEntryOptions;
+        this.defaultSnapshot = {
+            messages: [],
+            toolsConfig: cloneToolsConfig(options.defaultToolsConfig ?? DEFAULT_TOOLS_CONFIG),
+        };
+    }
+    /** @inheritdoc */
+    async getContext(chatId) {
+        const record = await this.readRecord(chatId);
+        return {
+            messages: cloneMessages(record.messages),
+            toolsConfig: cloneToolsConfig(record.toolsConfig),
+        };
+    }
+    /** @inheritdoc */
+    async setMessages(chatId, messages) {
+        const record = await this.readRecord(chatId);
+        const updated = {
+            messages: cloneMessages(messages),
+            toolsConfig: record.toolsConfig,
+        };
+        await this.writeRecord(chatId, updated);
+    }
+    /** @inheritdoc */
+    async appendMessages(chatId, messages) {
+        if (messages.length === 0) {
+            return;
+        }
+        const record = await this.readRecord(chatId);
+        const appended = cloneMessages(record.messages).concat(cloneMessages(messages));
+        await this.writeRecord(chatId, {
+            messages: appended,
+            toolsConfig: record.toolsConfig,
+        });
+    }
+    /** @inheritdoc */
+    async setToolsConfig(chatId, toolsConfig) {
+        const record = await this.readRecord(chatId);
+        const updated = {
+            messages: record.messages,
+            toolsConfig: cloneToolsConfig(toolsConfig),
+        };
+        await this.writeRecord(chatId, updated);
+    }
+    /** @inheritdoc */
+    async deleteContext(chatId) {
+        await this.cache.del(this.buildCacheKey(chatId));
+    }
+    async readRecord(chatId) {
+        const stored = await this.cache.get(this.buildCacheKey(chatId));
+        if (stored === undefined) {
+            return {
+                messages: cloneMessages(this.defaultSnapshot.messages),
+                toolsConfig: cloneToolsConfig(this.defaultSnapshot.toolsConfig),
+            };
+        }
+        return {
+            messages: cloneMessages(stored.messages),
+            toolsConfig: cloneToolsConfig(stored.toolsConfig),
+        };
+    }
+    async writeRecord(chatId, record) {
+        await this.cache.set(this.buildCacheKey(chatId), record, this.cacheEntryOptions);
+    }
+    buildCacheKey(chatId) {
+        return `${this.prefix}:${chatId}`;
+    }
+}
+//# sourceMappingURL=ContextManager.js.map

package/dist/src/context/ContextManager.js.map

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

package/dist/src/context/index.d.ts

@@ -0,0 +1,2 @@
+export { ContextManager } from "./ContextManager.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/context/index.js

@@ -0,0 +1,2 @@
+export { ContextManager } from "./ContextManager.js";
+//# sourceMappingURL=index.js.map

package/dist/src/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/context/types.d.ts

@@ -0,0 +1,17 @@
+import type { MessageHistoryType, ToolAutorouterRequest } from "@illalabs/interfaces";
+/**
+ * Internal record structure stored in cache.
+ */
+export type ContextRecord = {
+    readonly messages: MessageHistoryType;
+    readonly toolsConfig: ToolAutorouterRequest;
+};
+/**
+ * Single message entry from the message history.
+ */
+export type MessageEntry = MessageHistoryType[number];
+/**
+ * Content of a message, which can be a string or an array of content parts.
+ */
+export type MessageContent = MessageEntry["content"];
+//# sourceMappingURL=types.d.ts.map

package/dist/src/context/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/context/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IACxB,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;CAC/C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC"}

package/dist/src/context/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/context/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/context/types.ts"],"names":[],"mappings":""}

package/dist/src/external.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public API exports for the Illa SDK package
+ *
+ * This file explicitly defines the public interface of the SDK.
+ * Only exports listed here are considered part of the public API.
+ */
+export { InMemoryCache } from "./caching/index.js";
+export { Chat } from "./chat/index.js";
+export { ContextManager } from "./context/index.js";
+export { AsyncToolChecker } from "./asyncToolChecker/index.js";
+export type { CacheEntryOptions, ChatContextSnapshot, ContextManagerOptions, ICache, IContextManager, } from "./interfaces/index.js";
+export * from "./prompt/index.js";
+export * from "./providers/index.js";
+//# sourceMappingURL=external.d.ts.map

package/dist/src/external.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../src/external.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EACR,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,MAAM,EACN,eAAe,GAClB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/src/external.js

@@ -0,0 +1,13 @@
+/**
+ * Public API exports for the Illa SDK package
+ *
+ * This file explicitly defines the public interface of the SDK.
+ * Only exports listed here are considered part of the public API.
+ */
+export { InMemoryCache } from "./caching/index.js";
+export { Chat } from "./chat/index.js";
+export { ContextManager } from "./context/index.js";
+export { AsyncToolChecker } from "./asyncToolChecker/index.js";
+export * from "./prompt/index.js";
+export * from "./providers/index.js";
+//# sourceMappingURL=external.js.map

package/dist/src/external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../../src/external.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAQ/D,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Main entry point for the Illa SDK package
+ *
+ * This file serves as the package entry point and re-exports the public API
+ * defined in external.ts. For internal development and testing, use internal.ts.
+ */
+export * from "./external.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,eAAe,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,8 @@
+/**
+ * Main entry point for the Illa SDK package
+ *
+ * This file serves as the package entry point and re-exports the public API
+ * defined in external.ts. For internal development and testing, use internal.ts.
+ */
+export * from "./external.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,eAAe,CAAC"}

package/dist/src/interfaces/asyncToolChecker.interface.d.ts

@@ -0,0 +1,85 @@
+import type { ActionStatus, BaseLongPollingArgs } from "@illalabs/interfaces";
+import type { ICoreApiProvider } from "./coreApiProvider.interface.js";
+/**
+ * Options required to construct an {@link AsyncToolChecker} instance.
+ */
+export interface AsyncToolCheckerOptions {
+    /**
+     * Core API provider used to query the execution status of asynchronous tools.
+     */
+    readonly coreApiProvider: ICoreApiProvider;
+}
+/**
+ * Parameters accepted by {@link AsyncToolChecker.check}.
+ */
+export interface AsyncToolCheckerCheckParams {
+    /**
+     * Identifies the tool whose execution status should be queried.
+     */
+    readonly toolName: string;
+    /**
+     * Protocol associated with the tool execution.
+     */
+    readonly protocol: string;
+    /**
+     * Descriptor containing the metadata required to track the asynchronous execution.
+     */
+    readonly descriptor: BaseLongPollingArgs;
+}
+/**
+ * Configuration used to control polling behaviour for continuous status checks.
+ */
+export interface PollingConfig {
+    /**
+     * Interval, in seconds, between polling attempts.
+     */
+    readonly interval: number;
+    /**
+     * Maximum duration, in seconds, that polling should run before timing out. A value of zero disables the timeout.
+     */
+    readonly maxDuration: number;
+    /**
+     * Backoff threshold, in seconds, used to trigger retry logic for recoverable errors.
+     */
+    readonly retryThreshold: number;
+    /**
+     * Maximum number of retries permitted after transient errors.
+     */
+    readonly maxRetries: number;
+}
+/**
+ * Event emitted when the asynchronous tool status changes.
+ */
+export interface StatusChangedEvent<TPayload = unknown, TError = unknown> {
+    /**
+     * Previous status emitted by the checker.
+     */
+    readonly previous: ActionStatus<TPayload, TError> | null;
+    /**
+     * Current status reported by the Core API.
+     */
+    readonly current: ActionStatus<TPayload, TError>;
+}
+/**
+ * Callback configuration accepted by {@link AsyncToolChecker.subscribe}.
+ */
+export interface AsyncCheckerEvents<TPayload = unknown, TError = unknown> {
+    /**
+     * Handler invoked whenever the asynchronous status transitions.
+     */
+    readonly onStatusChange: (event: StatusChangedEvent<TPayload, TError>) => void;
+    /**
+     * Optional handler invoked when an unrecoverable error occurs while polling.
+     */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Represents a cancellable subscription created through {@link AsyncToolChecker.subscribe}.
+ */
+export interface EventSubscription {
+    /**
+     * Cancels the active subscription and stops further polling attempts.
+     */
+    unsubscribe(): void;
+}
+//# sourceMappingURL=asyncToolChecker.interface.d.ts.map

package/dist/src/interfaces/asyncToolChecker.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncToolChecker.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/asyncToolChecker.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACpC;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,gBAAgB,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IACxC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,QAAQ,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO;IACpE;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAEzD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,QAAQ,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO;IACpE;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;IAE/E;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;CACvB"}

package/dist/src/interfaces/asyncToolChecker.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=asyncToolChecker.interface.js.map

package/dist/src/interfaces/asyncToolChecker.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncToolChecker.interface.js","sourceRoot":"","sources":["../../../src/interfaces/asyncToolChecker.interface.ts"],"names":[],"mappings":""}

package/dist/src/interfaces/cache.interface.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options available when writing a cache entry.
+ */
+export interface CacheEntryOptions {
+    /**
+     * Time to live for the entry in milliseconds. When omitted the entry lives indefinitely.
+     */
+    readonly ttl?: number;
+}
+/**
+ * Represents the contract for cache implementations used by the SDK.
+ */
+export interface ICache {
+    /**
+     * Retrieves a cached value for the provided key.
+     *
+     * @param key Cache key used to identify the stored value.
+     */
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    /**
+     * Stores a value in the cache.
+     *
+     * @param key Cache key used to identify the stored value.
+     * @param value Value to store in the cache.
+     * @param options Additional options such as time to live.
+     */
+    set(key: string, value: unknown, options?: CacheEntryOptions): Promise<void>;
+    /**
+     * Removes a cached value for the provided key.
+     *
+     * @param key Cache key used to identify the stored value.
+     */
+    del(key: string): Promise<void>;
+}
+//# sourceMappingURL=cache.interface.d.ts.map

package/dist/src/interfaces/cache.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/cache.interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACnB;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEtD;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7E;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC"}

package/dist/src/interfaces/cache.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache.interface.js.map

package/dist/src/interfaces/cache.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.interface.js","sourceRoot":"","sources":["../../../src/interfaces/cache.interface.ts"],"names":[],"mappings":""}

package/dist/src/interfaces/chat.interface.d.ts

@@ -0,0 +1,84 @@
+import type { CoreApiChatBodyRequest, CoreApiChatResponse, MessageHistoryType, ToolAutorouterRequest, UserContext } from "@illalabs/interfaces";
+import type { AsyncToolChecker } from "../asyncToolChecker/index.js";
+import type { PromptRole, PromptSnapshot } from "../prompt/index.js";
+import type { IContextManager } from "./contextManager.interface.js";
+import type { ICoreApiProvider } from "./coreApiProvider.interface.js";
+/**
+ * Options used to construct a {@link Chat} instance.
+ */
+export interface ChatOptions {
+    /**
+     * Optional identifier to assign to the chat instance.
+     *
+     * When omitted, a random UUID is automatically generated using the Web Crypto API
+     * or a compatible polyfill.
+     */
+    readonly id?: string;
+    /**
+     * Core API provider used to communicate with Illa's Core API.
+     */
+    readonly coreApiProvider: ICoreApiProvider;
+    /**
+     * Context manager responsible for persisting chat history and tool configuration.
+     */
+    readonly contextManager: IContextManager;
+    /**
+     * Default role to assign to prompts when building message history entries.
+     */
+    readonly defaultRole?: PromptRole;
+    /**
+     * User context forwarded on every Core API call.
+     */
+    readonly userContext: UserContext;
+    /**
+     * Optional component responsible for monitoring long-running tool executions.
+     */
+    readonly asyncToolChecker?: AsyncToolChecker;
+}
+/**
+ * Result returned when sending a message through the chat instance.
+ */
+export interface SendMessageResult {
+    /**
+     * Identifier of the chat instance that processed the message.
+     */
+    readonly chatId: string;
+    /**
+     * The prompt that was sent to the Core API.
+     */
+    readonly prompt: CoreApiChatBodyRequest["prompt"];
+    /**
+     * Snapshot of the original prompt before normalization.
+     */
+    readonly promptSnapshot: PromptSnapshot;
+    /**
+     * Message history including the user's message and any response messages.
+     */
+    readonly messages: MessageHistoryType;
+    /**
+     * Tool configuration used for the request.
+     */
+    readonly toolsConfig: ToolAutorouterRequest;
+    /**
+     * Raw response from the Core API.
+     */
+    readonly response: CoreApiChatResponse;
+}
+/**
+ * Payload structure for chat requests sent to the Core API.
+ */
+export interface ChatRequestPayload {
+    /**
+     * Message history to include in the request.
+     */
+    readonly messages: MessageHistoryType;
+    /**
+     * Tool configuration for the request.
+     */
+    readonly toolsConfig: ToolAutorouterRequest;
+    /**
+     * User context information forwarded with the request.
+     */
+    readonly userContext: UserContext;
+}
+//# sourceMappingURL=chat.interface.d.ts.map

package/dist/src/interfaces/chat.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/chat.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,EACd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IAElD;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACrC"}

package/dist/src/interfaces/chat.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chat.interface.js.map

package/dist/src/interfaces/chat.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.interface.js","sourceRoot":"","sources":["../../../src/interfaces/chat.interface.ts"],"names":[],"mappings":""}

package/dist/src/interfaces/contextManager.interface.d.ts

@@ -0,0 +1,86 @@
+import type { MessageHistoryType, ToolAutorouterRequest } from "@illalabs/interfaces";
+import type { CacheEntryOptions } from "./index.js";
+/**
+ * Snapshot of the chat context maintained by the SDK.
+ */
+export interface ChatContextSnapshot {
+    /**
+     * Messages currently stored for the chat session.
+     */
+    readonly messages: MessageHistoryType;
+    /**
+     * Active tools configuration associated with the chat session.
+     */
+    readonly toolsConfig: ToolAutorouterRequest;
+}
+/**
+ * Options used to configure the {@link ContextManager} behavior.
+ */
+export interface ContextManagerOptions {
+    /**
+     * Prefix applied to all cache keys.
+     */
+    readonly cacheKeyPrefix?: string;
+    /**
+     * Options forwarded to the underlying cache when persisting state.
+     */
+    readonly cacheEntryOptions?: CacheEntryOptions;
+    /**
+     * Default tools configuration returned when no data is stored yet.
+     */
+    readonly defaultToolsConfig?: ToolAutorouterRequest;
+}
+/**
+ * Contract for components capable of managing chat context.
+ */
+export interface IContextManager {
+    /**
+     * Retrieves the full context for a given chat.
+     *
+     * @param chatId Identifier of the chat session.
+     *
+     * @returns Stored messages and tools configuration.
+     */
+    getContext(chatId: string): Promise<ChatContextSnapshot>;
+    /**
+     * Replaces the entire message history with the provided messages.
+     *
+     * Use this method when:
+     * - Storing the full conversation history returned by the Core API
+     * - Replacing the context with a complete message set
+     *
+     * @param chatId Identifier of the chat session.
+     * @param messages Complete message history to store.
+     */
+    setMessages(chatId: string, messages: MessageHistoryType): Promise<void>;
+    /**
+     * Appends new message entries to the existing chat history.
+     *
+     * Use this method when:
+     * - Adding messages that are known to be new (not already in context)
+     * - Building up a conversation incrementally
+     *
+     * Note: This method does NOT deduplicate messages. If the messages being
+     * appended already exist in the context, they will be duplicated. When
+     * working with Core API responses that return full conversation history,
+     * use {@link setMessages} instead.
+     *
+     * @param chatId Identifier of the chat session.
+     * @param messages New messages to append to existing history.
+     */
+    appendMessages(chatId: string, messages: MessageHistoryType): Promise<void>;
+    /**
+     * Persists the tools configuration associated with the chat.
+     *
+     * @param chatId Identifier of the chat session.
+     * @param toolsConfig Tools configuration to store.
+     */
+    setToolsConfig(chatId: string, toolsConfig: ToolAutorouterRequest): Promise<void>;
+    /**
+     * Clears all persisted data associated with the chat.
+     *
+     * @param chatId Identifier of the chat session.
+     */
+    deleteContext(chatId: string): Promise<void>;
+}
+//# sourceMappingURL=contextManager.interface.d.ts.map

package/dist/src/interfaces/contextManager.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextManager.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/contextManager.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEzD;;;;;;;;;OASG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElF;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD"}

package/dist/src/interfaces/contextManager.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contextManager.interface.js.map

package/dist/src/interfaces/contextManager.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextManager.interface.js","sourceRoot":"","sources":["../../../src/interfaces/contextManager.interface.ts"],"names":[],"mappings":""}

package/dist/src/interfaces/coreApiProvider.interface.d.ts

@@ -0,0 +1,32 @@
+import type { CoreApiChatRequest, CoreApiChatResponse, LongPollingActionRequest, LongPollingActionResponse } from "@illalabs/interfaces";
+import type { CoreApiProviderRoutes, RequestOptions } from "../providers/coreApiProvider/index.js";
+/**
+ * Contract for the Core API provider
+ */
+export interface ICoreApiProvider {
+    /**
+     * Sends a chat request to the Core API
+     *
+     * @param request Chat request payload
+     * @param options Additional request options such as cancellation support
+     *
+     * @returns Core API chat response
+     */
+    sendMessage(request: CoreApiChatRequest["body"], options?: RequestOptions): Promise<CoreApiChatResponse>;
+    /**
+     * Checks the status of a long running action
+     *
+     * @param request Long polling request parameters
+     * @param options Additional request options such as cancellation support
+     *
+     * @returns Core API execution checker response
+     */
+    awaitTransaction(request: LongPollingActionRequest["params"], options?: RequestOptions): Promise<LongPollingActionResponse>;
+    /**
+     * Retrieves the configured routes for the Core API endpoints used by the provider.
+     *
+     * @returns Route configuration including chat and action status paths.
+     */
+    getRoutes(): Required<CoreApiProviderRoutes>;
+}
+//# sourceMappingURL=coreApiProvider.interface.d.ts.map

package/dist/src/interfaces/coreApiProvider.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreApiProvider.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/coreApiProvider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;OAOG;IACH,WAAW,CACP,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,EACnC,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEhC;;;;;;;OAOG;IACH,gBAAgB,CACZ,OAAO,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAC3C,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAEtC;;;;OAIG;IACH,SAAS,IAAI,QAAQ,CAAC,qBAAqB,CAAC,CAAC;CAChD"}

package/dist/src/interfaces/coreApiProvider.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=coreApiProvider.interface.js.map

package/dist/src/interfaces/coreApiProvider.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreApiProvider.interface.js","sourceRoot":"","sources":["../../../src/interfaces/coreApiProvider.interface.ts"],"names":[],"mappings":""}

package/dist/src/interfaces/index.d.ts

@@ -0,0 +1,7 @@
+export type { ICoreApiProvider } from "./coreApiProvider.interface.js";
+export type { CacheEntryOptions, ICache } from "./cache.interface.js";
+export type { ChatContextSnapshot, ContextManagerOptions, IContextManager, } from "./contextManager.interface.js";
+export type { AsyncCheckerEvents, AsyncToolCheckerCheckParams, AsyncToolCheckerOptions, EventSubscription, PollingConfig, StatusChangedEvent, } from "./asyncToolChecker.interface.js";
+export type { AsyncToolChecker, AwaitActionResult, AwaitableActionDescriptor, } from "../asyncToolChecker/index.js";
+export type { ChatOptions, ChatRequestPayload, SendMessageResult } from "./chat.interface.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/interfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/interfaces/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACtE,YAAY,EACR,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,GAClB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACR,kBAAkB,EAClB,2BAA2B,EAC3B,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACrB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACR,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,GAC5B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/interfaces/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/src/interfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/interfaces/index.ts"],"names":[],"mappings":""}

package/dist/src/internal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal exports for the Illa SDK package
+ *
+ * This file includes all public exports plus any internal utilities
+ * needed for testing and development. External consumers should use
+ * the main index.ts entry point instead.
+ */
+export * from "./caching/index.js";
+export * from "./chat/index.js";
+export * from "./context/index.js";
+export * from "./external.js";
+export * from "./prompt/index.js";
+export * from "./asyncToolChecker/index.js";
+//# sourceMappingURL=internal.d.ts.map

package/dist/src/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,6BAA6B,CAAC"}