@reverbia/sdk 1.0.0-next.20251202090922 → 1.0.0-next.20251202095402

package/dist/react/index.d.mts

@@ -175,9 +175,67 @@ type LlmapiModelTopProvider = {
  */
 type LlmapiRole = string;
 
+/**
+ * Parameter definition for a client-side tool
+ */
+interface ToolParameter {
+    /** Parameter name */
+    name: string;
+    /** Parameter type (string, number, boolean, etc.) */
+    type: "string" | "number" | "boolean" | "object" | "array";
+    /** Human-readable description of the parameter */
+    description: string;
+    /** Whether this parameter is required */
+    required?: boolean;
+    /** Default value if not provided */
+    default?: unknown;
+}
+/**
+ * Definition for a client-side tool that can be executed in the browser
+ */
+interface ClientTool {
+    /** Unique identifier for the tool */
+    name: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** Parameters the tool accepts */
+    parameters?: ToolParameter[];
+    /**
+     * The function to execute when the tool is called.
+     * Receives extracted parameters and returns a result.
+     */
+    execute: (params: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/**
+ * Result of a tool selection operation
+ */
+interface ToolSelectionResult {
+    /** Whether a tool was selected */
+    toolSelected: boolean;
+    /** Name of the selected tool (if any) */
+    toolName?: string;
+    /** Extracted parameters for the tool */
+    parameters?: Record<string, unknown>;
+    /** Confidence score (0-1) of the selection */
+    confidence?: number;
+}
+/**
+ * Result of executing a client-side tool
+ */
+interface ToolExecutionResult {
+    /** Name of the tool that was executed */
+    toolName: string;
+    /** Whether execution was successful */
+    success: boolean;
+    /** The result returned by the tool */
+    result?: unknown;
+    /** Error message if execution failed */
+    error?: string;
+}
+
 type SendMessageArgs = {
     messages: LlmapiMessage[];
-    model: string;
+    model?: string;
     /**
      * Per-request callback for data chunks. Called in addition to the global
      * `onData` callback if provided in `useChat` options.
@@ -185,13 +243,20 @@ type SendMessageArgs = {
      * @param chunk - The content delta from the current chunk
      */
     onData?: (chunk: string) => void;
+    /**
+     * Whether to run tool selection for this message.
+     * Defaults to true if tools are configured.
+     */
+    runTools?: boolean;
 };
 type SendMessageResult = {
     data: LlmapiChatCompletionResponse;
     error: null;
+    toolExecution?: ToolExecutionResult;
 } | {
     data: null;
     error: string;
+    toolExecution?: ToolExecutionResult;
 };
 type UseChatOptions = {
     getToken?: () => Promise<string | null>;
@@ -215,9 +280,36 @@ type UseChatOptions = {
      * @param error - The error that occurred (never an AbortError)
      */
     onError?: (error: Error) => void;
+    /**
+     * The provider to use for chat completions (default: "api")
+     * "local": Uses a local HuggingFace model (in-browser)
+     * "api": Uses the backend API
+     */
+    chatProvider?: "api" | "local";
+    /**
+     * The model to use for local chat completions
+     * Default is "ibm-granite/Granite-4.0-Nano-WebGPU"
+     */
+    localModel?: string;
+    /**
+     * Client-side tools that can be executed in the browser.
+     * When provided, the hook will use a local model to determine
+     * if any tool should be called based on the user's message.
+     */
+    tools?: ClientTool[];
+    /**
+     * The model to use for tool selection.
+     * Default is "onnx-community/granite-4.0-350m-ONNX-web"
+     */
+    toolSelectorModel?: string;
+    /**
+     * Callback function to be called when a tool is executed.
+     */
+    onToolExecution?: (result: ToolExecutionResult) => void;
 };
 type UseChatResult = {
     isLoading: boolean;
+    isSelectingTool: boolean;
     sendMessage: (args: SendMessageArgs) => Promise<SendMessageResult>;
     /**
      * Aborts the current streaming request if one is in progress.
@@ -244,47 +336,58 @@ type UseChatResult = {
  * @param options.onFinish - Callback function to be called when the chat completion finishes successfully.
  * @param options.onError - Callback function to be called when an unexpected error
  *   is encountered. Note: This is NOT called for aborted requests (see `stop()`).
+ * @param options.chatProvider - The provider to use for chat completions (default: "api").
+ * @param options.localModel - The model to use for local chat completions.
+ * @param options.tools - Client-side tools that can be executed in the browser.
+ * @param options.toolSelectorModel - The model to use for tool selection.
+ * @param options.onToolExecution - Callback function to be called when a tool is executed.
  *
  * @returns An object containing:
  *   - `isLoading`: A boolean indicating whether a request is currently in progress
+ *   - `isSelectingTool`: A boolean indicating whether tool selection is in progress
  *   - `sendMessage`: An async function to send chat messages
  *   - `stop`: A function to abort the current request
  *
  * @example
  * ```tsx
+ * // Basic usage with API
  * const { isLoading, sendMessage, stop } = useChat({
- *   getToken: async () => {
- *     // Get your auth token from your auth provider
- *     return await getAuthToken();
- *   },
- *   onFinish: (response) => {
- *     console.log("Chat finished:", response);
- *   },
- *   onError: (error) => {
- *     // This is only called for unexpected errors, not aborts
- *     console.error("Chat error:", error);
+ *   getToken: async () => await getAuthToken(),
+ *   onFinish: (response) => console.log("Chat finished:", response),
+ *   onError: (error) => console.error("Chat error:", error)
+ * });
+ *
+ * // With client-side tools
+ * const { isLoading, isSelectingTool, sendMessage } = useChat({
+ *   getToken: async () => await getAuthToken(),
+ *   tools: [
+ *     {
+ *       name: "get_weather",
+ *       description: "Get the current weather for a location",
+ *       parameters: [
+ *         { name: "location", type: "string", description: "City name", required: true }
+ *       ],
+ *       execute: async ({ location }) => {
+ *         // Your weather API call here
+ *         return { temperature: 72, condition: "sunny" };
+ *       }
+ *     }
+ *   ],
+ *   onToolExecution: (result) => {
+ *     console.log("Tool executed:", result.toolName, result.result);
  *   }
  * });
  *
  * const handleSend = async () => {
  *   const result = await sendMessage({
- *     messages: [{ role: 'user', content: 'Hello!' }],
+ *     messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
  *     model: 'gpt-4o-mini'
  *   });
  *
- *   if (result.error) {
- *     if (result.error === "Request aborted") {
- *       console.log("Request was aborted");
- *     } else {
- *       console.error("Error:", result.error);
- *     }
- *   } else {
- *     console.log("Success:", result.data);
+ *   if (result.toolExecution) {
+ *     console.log("Tool was called:", result.toolExecution);
  *   }
  * };
- *
- * // To stop generation:
- * // stop();
  * ```
  */
 declare function useChat(options?: UseChatOptions): UseChatResult;
@@ -456,4 +559,26 @@ declare const extractConversationContext: (messages: Array<{
     content: string;
 }>, maxMessages?: number) => string;
 
-export { createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, extractConversationContext, formatMemoriesForChat, useChat, useEncryption, useMemory, useModels };
+declare const DEFAULT_TOOL_SELECTOR_MODEL = "Xenova/LaMini-GPT-124M";
+interface ToolSelectorOptions {
+    /** Model to use for tool selection. Defaults to Xenova/LaMini-GPT-124M */
+    model?: string;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Device to use (webgpu, wasm, cpu). Defaults to wasm */
+    device?: "webgpu" | "wasm" | "cpu";
+}
+/**
+ * Select a tool based on user message using an in-browser model
+ */
+declare function selectTool(userMessage: string, tools: ClientTool[], options?: ToolSelectorOptions): Promise<ToolSelectionResult>;
+/**
+ * Execute a client-side tool with the given parameters
+ */
+declare function executeTool(tool: ClientTool, params: Record<string, unknown>): Promise<{
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}>;
+
+export { type ClientTool, DEFAULT_TOOL_SELECTOR_MODEL, type ToolExecutionResult, type ToolParameter, type ToolSelectionResult, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, executeTool, extractConversationContext, formatMemoriesForChat, selectTool, useChat, useEncryption, useMemory, useModels };

package/dist/react/index.d.ts

@@ -175,9 +175,67 @@ type LlmapiModelTopProvider = {
  */
 type LlmapiRole = string;
 
+/**
+ * Parameter definition for a client-side tool
+ */
+interface ToolParameter {
+    /** Parameter name */
+    name: string;
+    /** Parameter type (string, number, boolean, etc.) */
+    type: "string" | "number" | "boolean" | "object" | "array";
+    /** Human-readable description of the parameter */
+    description: string;
+    /** Whether this parameter is required */
+    required?: boolean;
+    /** Default value if not provided */
+    default?: unknown;
+}
+/**
+ * Definition for a client-side tool that can be executed in the browser
+ */
+interface ClientTool {
+    /** Unique identifier for the tool */
+    name: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** Parameters the tool accepts */
+    parameters?: ToolParameter[];
+    /**
+     * The function to execute when the tool is called.
+     * Receives extracted parameters and returns a result.
+     */
+    execute: (params: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/**
+ * Result of a tool selection operation
+ */
+interface ToolSelectionResult {
+    /** Whether a tool was selected */
+    toolSelected: boolean;
+    /** Name of the selected tool (if any) */
+    toolName?: string;
+    /** Extracted parameters for the tool */
+    parameters?: Record<string, unknown>;
+    /** Confidence score (0-1) of the selection */
+    confidence?: number;
+}
+/**
+ * Result of executing a client-side tool
+ */
+interface ToolExecutionResult {
+    /** Name of the tool that was executed */
+    toolName: string;
+    /** Whether execution was successful */
+    success: boolean;
+    /** The result returned by the tool */
+    result?: unknown;
+    /** Error message if execution failed */
+    error?: string;
+}
+
 type SendMessageArgs = {
     messages: LlmapiMessage[];
-    model: string;
+    model?: string;
     /**
      * Per-request callback for data chunks. Called in addition to the global
      * `onData` callback if provided in `useChat` options.
@@ -185,13 +243,20 @@ type SendMessageArgs = {
      * @param chunk - The content delta from the current chunk
      */
     onData?: (chunk: string) => void;
+    /**
+     * Whether to run tool selection for this message.
+     * Defaults to true if tools are configured.
+     */
+    runTools?: boolean;
 };
 type SendMessageResult = {
     data: LlmapiChatCompletionResponse;
     error: null;
+    toolExecution?: ToolExecutionResult;
 } | {
     data: null;
     error: string;
+    toolExecution?: ToolExecutionResult;
 };
 type UseChatOptions = {
     getToken?: () => Promise<string | null>;
@@ -215,9 +280,36 @@ type UseChatOptions = {
      * @param error - The error that occurred (never an AbortError)
      */
     onError?: (error: Error) => void;
+    /**
+     * The provider to use for chat completions (default: "api")
+     * "local": Uses a local HuggingFace model (in-browser)
+     * "api": Uses the backend API
+     */
+    chatProvider?: "api" | "local";
+    /**
+     * The model to use for local chat completions
+     * Default is "ibm-granite/Granite-4.0-Nano-WebGPU"
+     */
+    localModel?: string;
+    /**
+     * Client-side tools that can be executed in the browser.
+     * When provided, the hook will use a local model to determine
+     * if any tool should be called based on the user's message.
+     */
+    tools?: ClientTool[];
+    /**
+     * The model to use for tool selection.
+     * Default is "onnx-community/granite-4.0-350m-ONNX-web"
+     */
+    toolSelectorModel?: string;
+    /**
+     * Callback function to be called when a tool is executed.
+     */
+    onToolExecution?: (result: ToolExecutionResult) => void;
 };
 type UseChatResult = {
     isLoading: boolean;
+    isSelectingTool: boolean;
     sendMessage: (args: SendMessageArgs) => Promise<SendMessageResult>;
     /**
      * Aborts the current streaming request if one is in progress.
@@ -244,47 +336,58 @@ type UseChatResult = {
  * @param options.onFinish - Callback function to be called when the chat completion finishes successfully.
  * @param options.onError - Callback function to be called when an unexpected error
  *   is encountered. Note: This is NOT called for aborted requests (see `stop()`).
+ * @param options.chatProvider - The provider to use for chat completions (default: "api").
+ * @param options.localModel - The model to use for local chat completions.
+ * @param options.tools - Client-side tools that can be executed in the browser.
+ * @param options.toolSelectorModel - The model to use for tool selection.
+ * @param options.onToolExecution - Callback function to be called when a tool is executed.
  *
  * @returns An object containing:
  *   - `isLoading`: A boolean indicating whether a request is currently in progress
+ *   - `isSelectingTool`: A boolean indicating whether tool selection is in progress
  *   - `sendMessage`: An async function to send chat messages
  *   - `stop`: A function to abort the current request
  *
  * @example
  * ```tsx
+ * // Basic usage with API
  * const { isLoading, sendMessage, stop } = useChat({
- *   getToken: async () => {
- *     // Get your auth token from your auth provider
- *     return await getAuthToken();
- *   },
- *   onFinish: (response) => {
- *     console.log("Chat finished:", response);
- *   },
- *   onError: (error) => {
- *     // This is only called for unexpected errors, not aborts
- *     console.error("Chat error:", error);
+ *   getToken: async () => await getAuthToken(),
+ *   onFinish: (response) => console.log("Chat finished:", response),
+ *   onError: (error) => console.error("Chat error:", error)
+ * });
+ *
+ * // With client-side tools
+ * const { isLoading, isSelectingTool, sendMessage } = useChat({
+ *   getToken: async () => await getAuthToken(),
+ *   tools: [
+ *     {
+ *       name: "get_weather",
+ *       description: "Get the current weather for a location",
+ *       parameters: [
+ *         { name: "location", type: "string", description: "City name", required: true }
+ *       ],
+ *       execute: async ({ location }) => {
+ *         // Your weather API call here
+ *         return { temperature: 72, condition: "sunny" };
+ *       }
+ *     }
+ *   ],
+ *   onToolExecution: (result) => {
+ *     console.log("Tool executed:", result.toolName, result.result);
  *   }
  * });
  *
  * const handleSend = async () => {
  *   const result = await sendMessage({
- *     messages: [{ role: 'user', content: 'Hello!' }],
+ *     messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
  *     model: 'gpt-4o-mini'
  *   });
  *
- *   if (result.error) {
- *     if (result.error === "Request aborted") {
- *       console.log("Request was aborted");
- *     } else {
- *       console.error("Error:", result.error);
- *     }
- *   } else {
- *     console.log("Success:", result.data);
+ *   if (result.toolExecution) {
+ *     console.log("Tool was called:", result.toolExecution);
  *   }
  * };
- *
- * // To stop generation:
- * // stop();
  * ```
  */
 declare function useChat(options?: UseChatOptions): UseChatResult;
@@ -456,4 +559,26 @@ declare const extractConversationContext: (messages: Array<{
     content: string;
 }>, maxMessages?: number) => string;
 
-export { createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, extractConversationContext, formatMemoriesForChat, useChat, useEncryption, useMemory, useModels };
+declare const DEFAULT_TOOL_SELECTOR_MODEL = "Xenova/LaMini-GPT-124M";
+interface ToolSelectorOptions {
+    /** Model to use for tool selection. Defaults to Xenova/LaMini-GPT-124M */
+    model?: string;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Device to use (webgpu, wasm, cpu). Defaults to wasm */
+    device?: "webgpu" | "wasm" | "cpu";
+}
+/**
+ * Select a tool based on user message using an in-browser model
+ */
+declare function selectTool(userMessage: string, tools: ClientTool[], options?: ToolSelectorOptions): Promise<ToolSelectionResult>;
+/**
+ * Execute a client-side tool with the given parameters
+ */
+declare function executeTool(tool: ClientTool, params: Record<string, unknown>): Promise<{
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}>;
+
+export { type ClientTool, DEFAULT_TOOL_SELECTOR_MODEL, type ToolExecutionResult, type ToolParameter, type ToolSelectionResult, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, executeTool, extractConversationContext, formatMemoriesForChat, selectTool, useChat, useEncryption, useMemory, useModels };