@intelliweave/embedded 1.7.59 → 1.8.61

package/dist/webpack/index.d.ts

@@ -1,4 +1,5 @@
 import { Optional } from 'utility-types';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import * as onnxruntime_web from 'onnxruntime-web';
 import { InferenceSession, Tensor } from 'onnxruntime-web';
 import React from 'react';
@@ -81,6 +82,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 */
@@ -113,11 +281,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. */
@@ -191,6 +355,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.
  */
@@ -230,7 +490,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 */
@@ -244,11 +508,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 {
@@ -268,12 +536,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
@@ -283,6 +547,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[];
 /** Format for incoming KB webook. Sent from IntelliWeave to your endpoint. */
 interface KnowledgeBaseWebhookRequest {
     /** Type of the request. */
@@ -334,49 +606,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 */
@@ -419,6 +695,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
@@ -530,6 +808,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;
@@ -707,9 +993,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 */
@@ -1319,6 +1605,8 @@ declare function intelliweaveConfig(): IntelliWeaveGlobalConfig;
 declare function sseEvents(stream: ReadableStream<Uint8Array>): AsyncGenerator<any, void, unknown>;
 /** Get or create a user ID for this device. */
 declare function getDefaultUserID(): string;
+/** Convert an IntelliWeave parameter list to JSON schema. Does not modify if it's already a JSON schema. */
+declare function convertParamsToJSONSchema(params: KnowledgeBaseActionParameterSchema): JSONSchema7;
 
 /** Class to help with logging */
 declare class Logging {
@@ -1461,4 +1749,4 @@ declare function useIntelliWeave(): IntelliWeave | undefined;
 /** React hook to add an external KB search hook. This can provide static KB entries, or perform an async search and return dynamic entries. */
 declare function useIntelliWeaveKnowledge(query: KnowledgeBaseSource['query'], dependencies?: any[]): void;
 
-export { AILogic, AudioSystem, type BufferType, BufferedWebSocket, ChatGPT, type ChatGPTConfig, type ChatGPTMessage, type ChatGPTToolConfig, FixedBufferStream, IntelliWeave, type IntelliWeaveGlobalConfig, IntelliWeaveProvider, IntelliWeaveStream, type IntelliWeaveStreamErrorEvent, type IntelliWeaveStreamEvent, type IntelliWeaveStreamTextOutputEvent, IntelliWeaveTranscriptionNode, KnowledgeBase, type KnowledgeBaseItem, type KnowledgeBaseSource, type KnowledgeBaseWebhookActionResponse, type KnowledgeBaseWebhookRequest, type KnowledgeBaseWebhookSearchResponse, Logging, ONNXModel, type ONNXTensors, OpenAITranscriptionNode, PCMPlayerNode, PCMReceiverNode, Resampler, type SupportedArrayBuffers, TokenWindow, TokenWindowGroup, type TokenWindowGroupItem, VoiceChunkOutputNode, VoiceDetectionNode, WebWeaverEmbed, type WebWeaverGPTConfig, WebWeaverSpeechOutput, WebWeaverSpeechRecognition, WebWeaverUI, audioToWav, floatTo16BitPCM, floatTo64BitPCM, getDefaultUserID, int16ToFloat32BitPCM, intelliweaveConfig, intelliweaveGlobalThis, sseEvents, trimWhitespaceInText, useIntelliWeave, useIntelliWeaveKnowledge };
+export { AILogic, AudioSystem, type BufferType, BufferedWebSocket, ChatGPT, type ChatGPTConfig, type ChatGPTMessage, type ChatGPTToolConfig, FixedBufferStream, IntelliWeave, type IntelliWeaveGlobalConfig, type IntelliWeaveInstructConfig, type IntelliWeaveParameterDefinition, IntelliWeaveProvider, IntelliWeaveStream, type IntelliWeaveStreamErrorEvent, type IntelliWeaveStreamEvent, type IntelliWeaveStreamTextOutputEvent, IntelliWeaveTranscriptionNode, KnowledgeBase, type KnowledgeBaseActionParameterSchema, type KnowledgeBaseItem, type KnowledgeBaseSource, type KnowledgeBaseWebhookActionResponse, type KnowledgeBaseWebhookRequest, type KnowledgeBaseWebhookSearchResponse, type KnowledgeFetcher, Logging, MCPKnowledgeClient, ONNXModel, type ONNXTensors, OpenAITranscriptionNode, PCMPlayerNode, PCMReceiverNode, Resampler, type SupportedArrayBuffers, TokenWindow, TokenWindowGroup, type TokenWindowGroupItem, VoiceChunkOutputNode, VoiceDetectionNode, WebWeaverEmbed, type WebWeaverGPTConfig, WebWeaverSpeechOutput, WebWeaverSpeechRecognition, WebWeaverUI, audioToWav, convertParamsToJSONSchema, floatTo16BitPCM, floatTo64BitPCM, getDefaultUserID, int16ToFloat32BitPCM, intelliweaveConfig, intelliweaveGlobalThis, sseEvents, trimWhitespaceInText, useIntelliWeave, useIntelliWeaveKnowledge };