@intelliweave/embedded 2.0.71 → 2.0.72-beta.2

package/dist/component/component.d.ts

@@ -1,5 +1,149 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { Optional } from 'utility-types';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+/**
+ * This class helps organize groups of tokenized text along with removing items when the window is full.
+ */
+declare class TokenWindow {
+    /** Token window size */
+    size: number;
+    /** Token groups */
+    groups: TokenWindowGroup<any>[];
+    /** Create a new group */
+    createGroup(id: string): TokenWindowGroup<unknown>;
+    /** Get a group */
+    group<CustomDataType>(id: string): TokenWindowGroup<CustomDataType> | undefined;
+    /** Counts tokens in the specified text */
+    static countTokensInText(text: string): number;
+    /** Calculate current tokens in all groups */
+    countTokens(): number;
+    /** Remove overflow from all groups. */
+    removeOverflow(): void;
+    /** Remove one overflow item. Returns null if no items were able to be removed. */
+    private removeOneItem;
+}
+/** A token group. */
+declare class TokenWindowGroup<DataType> {
+    /** Group ID */
+    id: string;
+    /** List of items */
+    items: TokenWindowGroupItem<DataType>[];
+    /**
+     * Weight controls how many items from this group should be kept in relation to the entire window. For example if all
+     * groups have a weight of 1, each group remove items equally if full. If one has a weight of 2 while the rest are 1,
+     * that group will be allowed to keep double the amount of items.
+     */
+    weight: number;
+    /** Current total token count, computed automatically. Don't update this value manually. */
+    tokenCount: number;
+    /** Group item separator. This text is added in between each item in the token window. */
+    separator: string;
+    /** Token count padding added to each item. */
+    private itemPadding;
+    /** Sets the token count padding added to each item. Useful if you don't know exactly what will be added by the LLM host. */
+    setItemPadding(padding: number): this;
+    /** Sort function */
+    private sortFunction;
+    /** Set sort function */
+    sortBy(sortFunction: (a: TokenWindowGroupItem<DataType>, b: TokenWindowGroupItem<DataType>) => number): this;
+    /** Set separator. This text is added in between each item in the token window. */
+    setSeparator(separator: string): this;
+    /**
+     * Set weight. Weight controls how many items from this group should be kept
+     * in relation to the entire window. For example if all groups have a weight
+     * of 1, each group remove items equally if full. If one has a weight of 2
+     * while the rest are 1, that group will be allowed to keep double the
+     * amount of items.
+     */
+    setWeight(weight: number): this;
+    /** Recalculate all tokens. Note this may take a while. */
+    recalculateTokens(): void;
+    /** Add an item to the group */
+    add(item: string | TokenWindowGroupItemParams<DataType>): TokenWindowGroupItem<DataType>;
+    /** Get all items as a string */
+    getAllAsString(): string;
+    /** Get all items. Doesn't return disabled items. */
+    getAll(): TokenWindowGroupItem<DataType>[];
+    /** Remove all items from this group */
+    empty(): void;
+}
+/** Token group item section types */
+declare enum TokenWindowGroupItemSectionType {
+    /** Text items represent plain text. */
+    Text = "text",
+    /** Tool call items represent a tool call requested by the AI. */
+    ToolCall = "tool_call",
+    /** Tool result items represent the result of a tool call. */
+    ToolResult = "tool_result",
+    /** Thinking section */
+    Thinking = "thinking",
+    /** Other item types */
+    Other = "other"
+}
+/** Token group item */
+interface TokenWindowGroupItem<DataType> {
+    /** Each item must have a unique ID. */
+    id: string;
+    /** True if this item should never be removed */
+    cannotRemove?: boolean;
+    /** Sorting order. If not specified, uses dateAdded instead. */
+    sortOrder: number;
+    /** Date this item was added */
+    dateAdded: number;
+    /** Token count in the content */
+    tokenCount: number;
+    /** This is the actual item that gets sent to the APIs. It will be in whatever format is required for the associated API. */
+    data?: DataType;
+    /** If disabled, this item will not be included and will not add to the token count. */
+    disabled?: boolean;
+    /** Message source, ie was this message created by the user, or by the AI? */
+    source: 'user' | 'assistant';
+    /**
+     * The string content of the item, or a summary of it. This is an autogenerated field, updated when the item is added/updated in the token window group.
+     * If `data` is a string, this will be the same as `data`. If `data` is more complex, this will be a text representation of all items in the `sections` array.
+     *
+     * Note: When the response contains text and tool calls, this will add in a summary of what's happening. For better displaying, use the `sections` array.
+     */
+    text?: string;
+    /** Message sections */
+    sections?: TokenWindowGroupItemSection[];
+    /** If this message was generated by the AI, this contains the token usage for this message. */
+    usage?: {
+        /** Number of tokens consumed from the data passed to the AI */
+        inputTokens: number;
+        /** Number of input tokens that were used in token caching */
+        cachedInputTokens: number;
+        /** Number of tokens consumed by the AI generating output */
+        outputTokens: number;
+        /** Total token usage */
+        totalTokens: number;
+    };
+}
+/** A section of a message returned by the AI */
+interface TokenWindowGroupItemSection {
+    /** Section type */
+    type: TokenWindowGroupItemSectionType;
+    /** Text content when this section represents text or thinking */
+    text?: string;
+    /** The raw tool name the AI requested to be called. */
+    toolName?: string;
+    /** The ID of the KB action this tool call maps to, if any */
+    toolKbID?: string;
+    /** The name of the KB action this tool call maps to, if any */
+    toolKbName?: string;
+    /** The parameters the AI requested to be sent to the tool. Only available if type == 'tool_call' */
+    toolParameters?: any;
+    /** Successful response of the tool call. Will be null if toolErrorResponse is set. */
+    toolSuccessResponse?: any;
+    /** Error response of the tool call. Will be null if toolSuccessResponse is set. */
+    toolErrorResponse?: string;
+    /** Tool call ID. This can be used to match a tool call request with it's result. */
+    toolCallInstanceID?: string;
+    /** True if this tool call should be hidden in the UI */
+    toolCallHiddenInUI?: 'always' | 'after-complete';
+}
+/** Token window group item input, without the autogenerated fields */
+type TokenWindowGroupItemParams<DataType> = Omit<Optional<TokenWindowGroupItem<DataType>, 'id' | 'dateAdded' | 'sortOrder' | 'text' | 'source' | 'sections'>, 'tokenCount'>;
 
 /**
  * Allows an MCP server to be used as a knowledge source for IntelliWeave.
@@ -377,12 +521,12 @@ interface KnowledgeBaseItem {
     name: string;
     /** Item tags. Helps with search optimization. */
     tags?: string;
-    /** Item content. Can be a function to return a dynamic string. */
-    content: string | (() => string);
+    /** Item content */
+    content: string;
     /** If true, this item will always be returned from all search results. */
     isContext?: boolean;
     /** If true, this item will not be visible to the AI. */
-    disabled?: boolean;
+    disabled?: boolean | ((ai: IntelliWeave) => boolean);
     /** List of parameters for an action function. Can either use IW's format, or a JSON Schema object. */
     parameters?: KnowledgeBaseActionParameterSchema;
     /**
@@ -391,8 +535,8 @@ interface KnowledgeBaseItem {
      * that was performed. If an error is thrown, the AI will respond appropriately to the user.
      */
     action?: (input: any, ai: IntelliWeave) => (any | Promise<any>);
-    /** If true, this item will be removed from the AI's message history after it gets called. This is a special case for LLMs that struggle with follow-up function calls and need to use the KB search functino first. */
-    removeFromMessageHistory?: boolean;
+    /** If specified, will hide this action from the default UI after the AI finishes running it, or always hide it */
+    hideActionInUI?: 'always' | 'after-complete';
 }
 /** Parameter definition used by IntelliWeave */
 interface IntelliWeaveParameterDefinition {
@@ -721,84 +865,6 @@ interface IntelliWeaveInstructConfig {
     callback?: (txt: string) => void;
 }
 
-/**
- * This class helps organize groups of tokenized text along with removing items when the window is full.
- */
-declare class TokenWindow {
-    /** Token window size */
-    size: number;
-    /** Token groups */
-    groups: TokenWindowGroup<any>[];
-    /** Create a new group */
-    createGroup(id: string): TokenWindowGroup<unknown>;
-    /** Get a group */
-    group<CustomDataType>(id: string): TokenWindowGroup<CustomDataType> | undefined;
-    /** Calculate current tokens in all groups */
-    countTokens(): number;
-    /** Remove overflow from all groups. */
-    removeOverflow(): void;
-    /** Remove one overflow item. Returns null if no items were able to be removed. */
-    private removeOneItem;
-}
-/** A token group. */
-declare class TokenWindowGroup<CustomDataType> {
-    /** Group ID */
-    id: string;
-    /** List of items */
-    items: TokenWindowGroupItem<CustomDataType>[];
-    /**
-     * Weight controls how many items from this group should be kept in relation to the entire window. For example if all
-     * groups have a weight of 1, each group remove items equally if full. If one has a weight of 2 while the rest are 1,
-     * that group will be allowed to keep double the amount of items.
-     */
-    weight: number;
-    /** Current total token count, computed automatically. Don't update this value manually. */
-    tokenCount: number;
-    /** Group item separator */
-    separator: string;
-    /** Token count padding added to each item. */
-    private itemPadding;
-    /** Sets the token count padding added to each item. Useful if you don't know exactly what will be added by the LLM host. */
-    setItemPadding(padding: number): this;
-    /** Sort function */
-    private sortFunction;
-    /** Set sort function */
-    sortBy(sortFunction: (a: TokenWindowGroupItem<CustomDataType>, b: TokenWindowGroupItem<CustomDataType>) => number): this;
-    /** Set separator */
-    setSeparator(separator: string): this;
-    /** Set weight */
-    setWeight(weight: number): this;
-    /** Recalculate all tokens. Note this may take a while. */
-    recalculateTokens(): void;
-    /** Add an item to the group */
-    add(item: string | Omit<Optional<TokenWindowGroupItem<CustomDataType>, 'id' | 'dateAdded' | 'sortOrder'>, 'tokenCount'>): TokenWindowGroupItem<CustomDataType>;
-    /** Get all items as a string */
-    getAllAsString(): string;
-    /** Get all items. Doesn't return disabled items. */
-    getAll(): TokenWindowGroupItem<CustomDataType>[];
-    /** Remove all items from this group */
-    empty(): void;
-}
-/** Token group item */
-interface TokenWindowGroupItem<CustomDataType> {
-    /** Each item must have a unique ID. */
-    id: string;
-    /** The string content of the item */
-    content: string;
-    /** True if this item should never be removed */
-    cannotRemove?: boolean;
-    /** Sorting order. If not specified, uses dateAdded instead. */
-    sortOrder: number;
-    /** Date this item was added */
-    dateAdded: number;
-    /** Token count in the content */
-    tokenCount: number;
-    /** Anything to attach to this item */
-    customData?: CustomDataType;
-    /** If disabled, this item will not be included and will not add tot he token count. */
-    disabled?: boolean;
-}
-
 /** Chat config options */
 interface ChatBaseConfig {
     /** API key */
@@ -819,8 +885,8 @@ interface ChatBaseConfig {
     maxTokens: number;
     /** Callback before the AI sends info to the LLM */
     onBeforeMessageProcessing?: () => void;
-    /** Callback when a message from the AI is returned. If isChunk is true, it may be incomplete and be called again with more updates. */
-    onAIMessage?: (text: string, isChunk: boolean) => void;
+    /** Callback when a message from the AI is returned. If isPartial is true, it may be incomplete and be called again with more updates. */
+    onAIMessage?: (output: TokenWindowGroupItemParams<any>[], isPartial: boolean) => void;
     /** Callback when the AI starts performing an action */
     onAIToolStart?: (toolName: string, input: any) => void;
 }
@@ -834,19 +900,17 @@ interface ChatBaseToolConfig {
     params: JSONSchema7;
     /** Callback function to process the tool */
     callback: (params: any) => any;
-    /** If true, this tool call will be removed from the message history after it is executed. */
-    removeFromMessageHistory?: boolean;
     /** If true, this item can be removed if there's not enough context available. */
     canRemove?: boolean;
-    /** Misc app context */
-    [key: string]: any;
+    /** Knowledge base item this tool use represents */
+    kbItem?: KnowledgeBaseItem;
 }
 /**
  * API for interacting with chat APIs.
  */
 declare class ChatBase<
 /** Format for messages in the token window */
-MessageFormat = any, 
+DataType = any, 
 /** Optional extended config */
 ConfigFormat extends ChatBaseConfig = ChatBaseConfig> {
     /** ID */
@@ -865,27 +929,58 @@ ConfigFormat extends ChatBaseConfig = ChatBaseConfig> {
     /** Token window management */
     tokenWindow: TokenWindow;
     /** Token window group used for the context message */
-    get contextGroup(): TokenWindowGroup<any>;
+    get contextGroup(): TokenWindowGroup<string>;
     /** Token window group used for tools / actions */
     get toolGroup(): TokenWindowGroup<ChatBaseToolConfig>;
     /** Token window group used for messages */
-    get messageGroup(): TokenWindowGroup<MessageFormat>;
+    get messageGroup(): TokenWindowGroup<DataType>;
+    /** Get the API base after stripping out exact endpoints, or undefined for the default */
+    getBaseURL(): string | undefined;
     /** Constructor */
     constructor(config: ConfigFormat);
-    /** Send a message, and get the response */
-    sendMessage(message: string): Promise<string>;
+    /** Send a message, and get the response as a string. */
+    sendMessage(message: string, onPartial?: (items: TokenWindowGroupItemParams<DataType>[]) => void): Promise<TokenWindowGroupItemParams<any>[]>;
     /** Add a user message to the message history */
     addUserMessage(message: string): void;
     /** Add an assistant message to the message history */
     addAssistantMessage(message: string): void;
+    /** Helper to add a plain text item */
+    protected addTextMessage(text: string, source: 'user' | 'assistant', data: DataType): void;
     /** Process incoming message from the AI. Can be used to respond to encoded actions in the text response. */
-    onBeforeIncomingMessage(message: MessageFormat): void;
+    onBeforeIncomingMessage(message: DataType): void;
     /** Reset the conversation */
     resetConversation(): void;
     /** Trim message list */
     trimMessages(): Promise<void>;
     /** Register a tool. */
     registerTool(tool: ChatBaseToolConfig): TokenWindowGroupItem<ChatBaseToolConfig>;
+    /** Find a tool based on the AI-safe name */
+    protected findToolBySafeName(toolSafeName: string): ChatBaseToolConfig | undefined;
+    /** Execute the specified tool. Throws an error if the tool is undefined. */
+    protected executeTool(tool: ChatBaseToolConfig | undefined, input: any): Promise<string>;
+}
+
+/** Parses the response from `IntelliWeave.sendMessage()` or a collection of message items. */
+declare class IntelliWeaveMessageParser {
+    /** New messages produced after sendMessage() was called */
+    messages: TokenWindowGroupItemParams<unknown>[];
+    /** Constructor */
+    constructor(items: TokenWindowGroupItemParams<unknown>[]);
+    /** Plain text output from the AI */
+    text(): string;
+    /** Total token usage */
+    tokenUsage(): {
+        cachedInputTokens: number;
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    /** Component sections for display */
+    sections(): TokenWindowGroupItemParams<unknown>['sections'];
+    /** List all tool calls that took place */
+    toolCalls(): TokenWindowGroupItemSection[];
+    /** Find the response for a tool call */
+    toolResult(toolCallInstanceID: string): TokenWindowGroupItemSection | null;
 }
 
 /** Built-in action flags for the persona */
@@ -925,6 +1020,8 @@ interface WebWeaverGPTConfig {
     textColor?: string;
     /** Display mode: 'closed' (default - starts minimized) or 'open' (always open) */
     displayMode?: 'closed' | 'open';
+    /** Layout preset: 'widget' (default) or 'fullscreen' */
+    layout?: 'widget' | 'fullscreen';
     /** Positioning mode: 'fixed' (default - floats on page) or 'container' (fills parent container) */
     positioningMode?: 'fixed' | 'container';
     /** Horizontal position: 'left' or 'right' (default: 'right') - only used when positioningMode is 'fixed' */
@@ -959,6 +1056,8 @@ interface WebWeaverGPTConfig {
     mcpServers?: MCPKnowledgeClient['config'][];
     /** Built-in action flags that are currently enabled */
     flags?: BuiltInActionFlags;
+    /** Allow custom chat provider */
+    onCreateProvider?: (config: ChatBaseConfig) => ChatBase;
 }
 /**
  * IntelliWeave interface, loads a Persona from the hub and allows you to interact with it. This is the main entry point into the IntelliWeave
@@ -969,7 +1068,7 @@ interface WebWeaverGPTConfig {
  * - event `webweaver_loaded` - Fired when the AI is loaded with a new configuration. This is a global event that is fired on the window object.
  * - event `webweaver_error` - Fired when an error occurs during loading. This is a global event that is fired on the window object.
  * - event `input` - Fired when the user sends a message to the AI.
- * - event `output` - Fired when the AI sends a message back to the user. If `event.detail.isChunk` is true, the message is incomplete and will be followed by more events.
+ * - event `output` - Fired when the AI sends a message back to the user. If `event.detail.isPartial` is true, the message is incomplete and will be followed by more events.
  * - event `toolstart` - Fired when the AI starts performing an action.
  * - event `tool` - Fired when the AI finishes performing an action.
  */
@@ -978,8 +1077,8 @@ declare class IntelliWeave extends EventTarget {
     static version: string;
     /** Built-in actions version - increment this when adding new actions */
     static builtInActionsVersion: string;
-    /** Callback when a message from the AI is returned. If isChunk is true, it may be incomplete and be called again with more updates. */
-    onAIMessage?: (text: string, isChunk: boolean) => void;
+    /** Callback when a message from the AI is returned. If isPartial is true, it may be incomplete and be called again with more updates. */
+    onAIMessage?: (messages: TokenWindowGroupItemParams<unknown>[], isPartial: boolean) => void;
     /** Callback when the AI starts performing an action */
     onAIToolStart?: ChatBaseConfig['onAIToolStart'];
     /** Current conversation ID */
@@ -1029,7 +1128,7 @@ declare class IntelliWeave extends EventTarget {
     /** URL of the IntelliWeave Hub API */
     hubAPI: string;
     /** Set model and load data from an API key */
-    load(apiKey: string): Promise<WebWeaverGPTConfig>;
+    load(apiKey: string, config?: Partial<WebWeaverGPTConfig>): Promise<IntelliWeave>;
     /** Set the current model */
     setModel(id: string): void;
     private _lastSystemMsg;
@@ -1037,17 +1136,15 @@ declare class IntelliWeave extends EventTarget {
     getContextPrefix(): Promise<string>;
     /** Get system message to send to the AI */
     onBeforeMessageProcessing(): Promise<void>;
-    /** @private Process incoming message from the AI. Can be used to respond to encoded actions in the text response. */
-    processIncomingMessage(message: string, isChunk?: boolean): void;
+    /** @private Process incoming message(s) from the AI. Can be used to respond to encoded actions in the text response. */
+    processIncomingMessage(messages: TokenWindowGroupItemParams<unknown>[], isPartial?: boolean): void;
     /** True if currently processing a message */
     isProcessing: boolean;
-    /** @private Last tracked token count for calculating per-message token usage */
-    private _lastTrackedTokens;
     /** Send a message, and get the response */
-    sendMessage(message: string): Promise<string | null>;
+    sendMessage(message: string, onPartial?: (items: TokenWindowGroupItemParams<unknown>[]) => void): Promise<IntelliWeaveMessageParser>;
     /** @private Called when the AI wants to run a KB action */
     toolRunKBAction(kb: KnowledgeBaseItem, input: any): Promise<any>;
-    /** Submit an analytics event asynchronously */
+    /** Submit an analytics event asynchronously. These events are for use in the Conversation Analytics code. For anonymous statistic analysis, use track() instead. */
     submitAnalyticsEvent(data: any): void;
     /** Reset the conversation */
     resetConversation(): void;
@@ -1057,12 +1154,14 @@ declare class IntelliWeave extends EventTarget {
     exportState(): {
         type: string;
         conversationID: string;
-        messages: any[] | undefined;
+        messages: TokenWindowGroupItem<any>[] | undefined;
     };
     /** Import conversation state from JSON */
     importState(state: any): void;
     /** Clone this instance without any message history */
     clone(): IntelliWeave;
+    /** Get all messages in the conversation history */
+    get messages(): TokenWindowGroupItem<any>[];
 }
 
 /**
@@ -1147,11 +1246,18 @@ declare class WebWeaverEmbed extends BaseComponent {
     private _lastBackground?;
     private _lastTextColor?;
     private _lastDisplayMode?;
+    private _lastLayout?;
+    private _lastPersonaName?;
+    private _lastHeaderLogo?;
     private _lastPositioningMode?;
     private _lastPositionX?;
     private _lastPositionY?;
     private _lastOffsetX?;
     private _lastOffsetY?;
+    /** Apply persona-based color variants as CSS variables */
+    private applyPersonaColorVariants;
+    /** Parse a color string to RGB (supports hex and rgb/rgba) */
+    private parseColorToRGB;
     /** Apply UI styles from config and attributes, prioritizing attributes */
     private applyConfigStylesAndAttributes;
     /** Called on update */
@@ -1175,9 +1281,11 @@ declare class WebWeaverEmbed extends BaseComponent {
     /** Process input text from the user */
     processInput(inputText: string): Promise<void>;
     /** Called when the AI responds with some text */
-    onAIMessage(msg: string): Promise<void>;
-    /** Called when the AI starts running a tool */
-    onAIToolStart(toolName: string, args: any): void;
+    onAIMessage(messages: TokenWindowGroupItemParams<unknown>[], isPartial: boolean): Promise<void>;
+    /** Updates a text element */
+    updateTextElement(elementID: string, text: string): void;
+    /** Updates an info block element */
+    updateInfoElement(elementID: string, text: string, iconType: string): void;
     /** Called when a suggestion button is clicked */
     onSuggestionClick(e: Event, suggestion: string): void;
     /** Called when an LLM model is selected */