@intelliweave/embedded 1.7.59 → 1.8.61

package/dist/component/component.d.ts

@@ -1,4 +1,5 @@
 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.
@@ -78,6 +79,173 @@ interface TokenWindowGroupItem<CustomDataType> {
     disabled?: boolean;
 }
 
+// ==================================================================================================
+// JSON Schema Draft 07
+// ==================================================================================================
+// https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+// --------------------------------------------------------------------------------------------------
+
+/**
+ * Primitive type
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ */
+type JSONSchema7TypeName =
+    | "string" //
+    | "number"
+    | "integer"
+    | "boolean"
+    | "object"
+    | "array"
+    | "null";
+
+/**
+ * Primitive type
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ */
+type JSONSchema7Type =
+    | string //
+    | number
+    | boolean
+    | JSONSchema7Object
+    | JSONSchema7Array
+    | null;
+
+// Workaround for infinite type recursion
+interface JSONSchema7Object {
+    [key: string]: JSONSchema7Type;
+}
+
+// Workaround for infinite type recursion
+// https://github.com/Microsoft/TypeScript/issues/3496#issuecomment-128553540
+interface JSONSchema7Array extends Array<JSONSchema7Type> {}
+
+/**
+ * Meta schema
+ *
+ * Recommended values:
+ * - 'http://json-schema.org/schema#'
+ * - 'http://json-schema.org/hyper-schema#'
+ * - 'http://json-schema.org/draft-07/schema#'
+ * - 'http://json-schema.org/draft-07/hyper-schema#'
+ *
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-5
+ */
+type JSONSchema7Version = string;
+
+/**
+ * JSON Schema v7
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+ */
+type JSONSchema7Definition = JSONSchema7 | boolean;
+interface JSONSchema7 {
+    $id?: string | undefined;
+    $ref?: string | undefined;
+    $schema?: JSONSchema7Version | undefined;
+    $comment?: string | undefined;
+
+    /**
+     * @see https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-8.2.4
+     * @see https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#appendix-A
+     */
+    $defs?: {
+        [key: string]: JSONSchema7Definition;
+    } | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1
+     */
+    type?: JSONSchema7TypeName | JSONSchema7TypeName[] | undefined;
+    enum?: JSONSchema7Type[] | undefined;
+    const?: JSONSchema7Type | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.2
+     */
+    multipleOf?: number | undefined;
+    maximum?: number | undefined;
+    exclusiveMaximum?: number | undefined;
+    minimum?: number | undefined;
+    exclusiveMinimum?: number | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.3
+     */
+    maxLength?: number | undefined;
+    minLength?: number | undefined;
+    pattern?: string | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.4
+     */
+    items?: JSONSchema7Definition | JSONSchema7Definition[] | undefined;
+    additionalItems?: JSONSchema7Definition | undefined;
+    maxItems?: number | undefined;
+    minItems?: number | undefined;
+    uniqueItems?: boolean | undefined;
+    contains?: JSONSchema7Definition | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.5
+     */
+    maxProperties?: number | undefined;
+    minProperties?: number | undefined;
+    required?: string[] | undefined;
+    properties?: {
+        [key: string]: JSONSchema7Definition;
+    } | undefined;
+    patternProperties?: {
+        [key: string]: JSONSchema7Definition;
+    } | undefined;
+    additionalProperties?: JSONSchema7Definition | undefined;
+    dependencies?: {
+        [key: string]: JSONSchema7Definition | string[];
+    } | undefined;
+    propertyNames?: JSONSchema7Definition | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.6
+     */
+    if?: JSONSchema7Definition | undefined;
+    then?: JSONSchema7Definition | undefined;
+    else?: JSONSchema7Definition | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.7
+     */
+    allOf?: JSONSchema7Definition[] | undefined;
+    anyOf?: JSONSchema7Definition[] | undefined;
+    oneOf?: JSONSchema7Definition[] | undefined;
+    not?: JSONSchema7Definition | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7
+     */
+    format?: string | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-8
+     */
+    contentMediaType?: string | undefined;
+    contentEncoding?: string | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-9
+     */
+    definitions?: {
+        [key: string]: JSONSchema7Definition;
+    } | undefined;
+
+    /**
+     * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-10
+     */
+    title?: string | undefined;
+    description?: string | undefined;
+    default?: JSONSchema7Type | undefined;
+    readOnly?: boolean | undefined;
+    writeOnly?: boolean | undefined;
+    examples?: JSONSchema7Type | undefined;
+}
+
 /** ChatGPT config options */
 interface ChatGPTConfig {
     /** API key */
@@ -110,11 +278,7 @@ interface ChatGPTToolConfig {
     /** Description of the tool */
     description: string;
     /** Parameters for the tool */
-    params: {
-        name: string;
-        type: string;
-        description: string;
-    }[];
+    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. */
@@ -188,6 +352,102 @@ declare class ChatGPT {
     resetConversation(): void;
 }
 
+/**
+ * Allows an MCP server to be used as a knowledge source for IntelliWeave.
+ */
+declare class MCPKnowledgeClient {
+    /** MCP client */
+    client?: Client;
+    /** All tools discovered on the MCP server. Only available after connect() has completed. */
+    tools: Awaited<ReturnType<Client['listTools']>>['tools'];
+    /** All toold discovered, mapped to IntelliWeave knowledge base actions */
+    iwActions: KnowledgeBaseItem[];
+    /** Statistics */
+    stats: {
+        toolsCalled: number;
+    };
+    /** Configuration */
+    config: {
+        /** Source ID */
+        id?: string;
+        /** URL to the MCP server endpoint */
+        baseURL?: string;
+        /** Custom connection function. If specified, baseURL is optional. */
+        connect?: () => Promise<Client>;
+        /**
+         * The name of the tool which provides knowledge searching. If specified, the search() will exclude this function and instead
+         * call it and show returned results. If not specified, the search() will just return all tools.
+         */
+        searchToolName?: string;
+        /** Keep search function available for the AI to use. */
+        searchToolVisible?: boolean;
+    };
+    /** Constructor */
+    constructor(config: MCPKnowledgeClient['config']);
+    /** In-progress connection attempt */
+    private connectionPromise?;
+    /** Connect to the client */
+    connect(): Promise<Client<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    }>>;
+    connectInternal(): Promise<Client<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    }>>;
+    /** Disconnect from server */
+    disconnect(): Promise<void>;
+    /** Fetch list of tools from the MCP server */
+    private fetchTools;
+    /** Cache last search result */
+    lastSearchQuery: string;
+    lastSearchResults: KnowledgeBaseItem[];
+    /** Perform a search query */
+    search(query: string): Promise<KnowledgeBaseItem[]>;
+    /** Perform search using the configured search function */
+    private performSearchCall;
+    /** Perform tool call. */
+    private performToolCall;
+}
+
 /**
  * Register knowledge base sources and perform searches.
  */
@@ -227,7 +487,11 @@ declare class KnowledgeBase {
     registerSourceFromURL(url: string, id?: string): void;
     /** Clone this instance */
     clone(): KnowledgeBase;
+    /** Registers an MCP server as a knowledge base source */
+    registerMCPSource(config: MCPKnowledgeClient['config']): MCPKnowledgeClient;
 }
+/** Knowledge fetcher */
+type KnowledgeFetcher = (query: string) => (KnowledgeBaseItem[] | Promise<KnowledgeBaseItem[]>);
 /** Knowledge base source */
 interface KnowledgeBaseSource {
     /** Source ID */
@@ -241,11 +505,15 @@ interface KnowledgeBaseSource {
     /** If true, this source will not be queried. */
     disabled?: boolean;
     /** Source query function. This function should return a list of knowledge base entries that optionally match the query. */
-    query?: (query: string) => (KnowledgeBaseItem[] | Promise<KnowledgeBaseItem[]>);
+    query?: KnowledgeFetcher;
     /** URL query for remote sources */
     url?: string;
     /** Pre-packaged knowledge base entries */
     entries?: KnowledgeBaseItem[];
+    /** Remote knowledge server type (default is 'iw') */
+    backendType?: 'mcp' | 'iw';
+    /** If using MCP, this is the name of the tool to use to search for knowledge */
+    mcpSearchToolName?: string;
 }
 /** Knowledge base item */
 interface KnowledgeBaseItem {
@@ -265,12 +533,8 @@ interface KnowledgeBaseItem {
     isContext?: boolean;
     /** If true, this item will not be visible to the AI. */
     disabled?: boolean;
-    /** List of parameters for an action function. */
-    parameters?: ({
-        name: string;
-        type: 'string' | 'boolean' | 'number';
-        description: string;
-    })[];
+    /** List of parameters for an action function. Can either use IW's format, or a JSON Schema object. */
+    parameters?: KnowledgeBaseActionParameterSchema;
     /**
      * Item action. The parameters are defined in `parameters`. The response is stringified and sent to the AI.
      * You can return any JSON-serializable object. You can also return a string describing to the AI the action
@@ -280,6 +544,14 @@ interface KnowledgeBaseItem {
     /** 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;
 }
+/** Parameter definition used by IntelliWeave */
+interface IntelliWeaveParameterDefinition {
+    name: string;
+    type: 'string' | 'boolean' | 'number';
+    description: string;
+}
+/** Tool call input schema. Can either use IW's format, or a JSON Schema object */
+type KnowledgeBaseActionParameterSchema = JSONSchema7 | IntelliWeaveParameterDefinition[];
 
 /**
  * Speech output
@@ -297,6 +569,14 @@ declare class WebWeaverSpeechOutput extends EventTarget {
     /** Current player vars */
     private currentPlayerVolume?;
     private currentPlayer?;
+    /** The audio analyser node */
+    private analyserNode?;
+    /** The audio analyser buffer */
+    private analyserBuffer?;
+    /** @private Maximum volume heard this session */
+    private maxVolumeHeard;
+    /** Get current (realtime) audio output volume level, from 0 to 1 */
+    get volumeLevel(): number;
     /** Speak the text */
     speak(text: string): Promise<void>;
     private _speakWithLock;
@@ -474,9 +754,9 @@ declare class WebWeaverSpeechRecognition extends EventTarget {
     /** True if recognition is running */
     isRunning: boolean;
     /** The audio analyser node */
-    analyserNode?: AnalyserNode;
+    private analyserNode?;
     /** The audio analyser buffer */
-    analyserBuffer?: Float32Array;
+    private analyserBuffer?;
     /** The microphone stream */
     micStream?: MediaStream;
     /** Returns true if speech recognition is supported by this persona and browser */
@@ -535,49 +815,53 @@ declare class AILogic {
     /** Constructor */
     constructor(ai: IntelliWeave);
     /** Ask the AI a yes/no question associated with the specified data. Data must be JSON-serializable, or a string of any kind of data. */
-    boolean(question: string, data: any): Promise<boolean>;
+    boolean(config: IntelliWeaveInstructConfig): Promise<boolean>;
+    /** Ask the AI to select a choice from a list of options. */
+    choose(config: IntelliWeaveInstructConfig & {
+        /** List of choices the AI can pick from. */
+        options: string[];
+    }): Promise<string | undefined>;
     /**
-        Ask the AI to select a choice from a list of options. The AI will return the selected choice.
-        @param question The question to ask the AI.
-        @param data The data to provide to the AI. This can be a string or a JSON-serializable object.
-        @param options The list of options to choose from.
+     * Ask the AI to extract data from input data. The AI will return the extracted data. Possibly an array of multiple extractions.
      */
-    choose(question: string, data: any, options: string[]): Promise<string | undefined>;
+    extract<T = any>(config: IntelliWeaveInstructConfig & {
+        /** Allow multiple items to be returned. If true, returns an array instead of an object. */
+        allowMultiple?: boolean;
+        /** Fields to extract in each object. */
+        extractions: {
+            /** Field name */
+            name: string;
+            /** Field data type */
+            type: 'string' | 'number' | 'boolean' | 'date' | 'email' | 'phone' | 'address';
+            /** Describe to the AI what data to put in this field. */
+            description?: string;
+        }[];
+    }): Promise<T[]>;
     /**
-     * Ask the AI to extract data from a text. The AI will return the extracted data. Possibly an array of multiple extractions.
-     *   Example: extract(myData, true, [
-     *   { name: "id", type: "string", description: "The user's ID number." },
-     *   { name: "firstName", type: "string", description: "The user's first name" },
-     *   ])
-     * @param question The question to ask the AI.
-     * @param data The data to provide to the AI. This can be a string or a JSON-serializable object.
-     * @param allowMultiple Whether to allow multiple extractions or not.
-     * @param extractions The list of extractions to perform. Each extraction is an object with the following properties:
-     * - name: The name of the extraction. This will be the key in the returned object.
-     * - type: The type of the extraction. This can be "string", "number", "boolean", "date", "email", "url", "phone", "address", "name", "organization", "person", "location", "time", "duration", "money", "percentage", "quantity", "custom".
-     * - description: A description of the extraction. This is optional.
-     */
-    extract(question: string, data: any, allowMultiple: boolean, extractions: {
-        name: string;
-        type: string;
-        description?: string;
-    }[]): Promise<any>;
-    /**
-     * Generate a Markdown document based on the input query from the user.
+     * Generate a Markdown document based on the data from the user.
      *
-     * @param query The query to generate the document from.
-     * @param callback The callback that will be called when streaming the response. Each call will contain the full text that has been generated so far.
+     * @param config Instruct config.
+     * @returns A markdown document.
      */
-    generateMarkdown(query: string, callback: (txt: string) => void): Promise<string | null>;
+    generateMarkdown(config: Omit<IntelliWeaveInstructConfig, 'instruction'>): Promise<string>;
     /**
      * Perform an instruction.
      *
-     * @param instruction Describe the action to perform.
-     * @param query The user query to pass to the AI.
-     * @param callback The callback that will be called when streaming the response. Each call will contain the full text that has been generated so far.
+     * @param config Instruct config.
      * @returns The final response from the AI.
      */
-    instruct(instruction: string, query: string, callback: (txt: string) => void): Promise<string | null>;
+    instruct(config: IntelliWeaveInstructConfig): Promise<string>;
+}
+/** Config for any instruct call */
+interface IntelliWeaveInstructConfig {
+    /** Instruction */
+    instruction: string;
+    /** Input data or query to process */
+    data: any;
+    /** Whether to allow the AI to use the knowledge base or not. If false, the AI will not use the knowledge base. */
+    allowKB?: boolean;
+    /** Callback that will be called when streaming the response. Each call will contain the full text that has been generated so far. */
+    callback?: (txt: string) => void;
 }
 
 /** Persona config received from the hub */
@@ -620,6 +904,8 @@ interface WebWeaverGPTConfig {
     };
     /** Knowledge base sources */
     knowledge?: KnowledgeBaseSource[];
+    /** MCP servers */
+    mcpServers?: MCPKnowledgeClient['config'][];
 }
 /**
  * IntelliWeave interface, loads a Persona from the hub and allows you to interact with it. This is the main entry point into the IntelliWeave