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

package/dist/react/index.cjs

@@ -46669,12 +46669,15 @@ ${fake_token_around_image}${global_img_token}` + image_token.repeat(image_seq_le
 // src/react/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_TOOL_SELECTOR_MODEL: () => DEFAULT_TOOL_SELECTOR_MODEL,
   createMemoryContextSystemMessage: () => createMemoryContextSystemMessage,
   decryptData: () => decryptData,
   decryptDataBytes: () => decryptDataBytes,
   encryptData: () => encryptData,
+  executeTool: () => executeTool,
   extractConversationContext: () => extractConversationContext,
   formatMemoriesForChat: () => formatMemoriesForChat,
+  selectTool: () => selectTool,
   useChat: () => useChat,
   useEncryption: () => useEncryption,
   useMemory: () => useMemory,
@@ -47503,9 +47506,32 @@ var client = createClient(createClientConfig(createConfig()));
 // src/lib/chat/constants.ts
 var DEFAULT_LOCAL_CHAT_MODEL = "onnx-community/Qwen2.5-0.5B-Instruct";
 
-// src/lib/chat/generation.ts
-var chatPipeline = null;
+// src/lib/chat/pipeline.ts
+var sharedPipeline = null;
 var currentModel = null;
+var currentDevice = null;
+async function getTextGenerationPipeline(options) {
+  const { model, device = "wasm", dtype = "q4" } = options;
+  if (sharedPipeline && currentModel === model && currentDevice === device) {
+    return sharedPipeline;
+  }
+  const { pipeline, env: env3 } = await Promise.resolve().then(() => (init_transformers_node(), transformers_node_exports));
+  env3.allowLocalModels = false;
+  if (env3.backends?.onnx) {
+    env3.backends.onnx.logLevel = "fatal";
+  }
+  console.log(`[Pipeline] Loading model: ${model} on ${device}...`);
+  sharedPipeline = await pipeline("text-generation", model, {
+    dtype,
+    device
+  });
+  currentModel = model;
+  currentDevice = device;
+  console.log(`[Pipeline] Model loaded: ${model}`);
+  return sharedPipeline;
+}
+
+// src/lib/chat/generation.ts
 async function generateLocalChatCompletion(messages, options = {}) {
   const {
     model = DEFAULT_LOCAL_CHAT_MODEL,
@@ -47515,13 +47541,12 @@ async function generateLocalChatCompletion(messages, options = {}) {
     onToken,
     signal
   } = options;
-  const { pipeline, TextStreamer } = await Promise.resolve().then(() => (init_transformers_node(), transformers_node_exports));
-  if (!chatPipeline || currentModel !== model) {
-    chatPipeline = await pipeline("text-generation", model, {
-      dtype: "fp16"
-    });
-    currentModel = model;
-  }
+  const { TextStreamer } = await Promise.resolve().then(() => (init_transformers_node(), transformers_node_exports));
+  const chatPipeline = await getTextGenerationPipeline({
+    model,
+    device: "wasm",
+    dtype: "q4"
+  });
   class CallbackStreamer extends TextStreamer {
     constructor(tokenizer, cb) {
       super(tokenizer, {
@@ -47548,6 +47573,148 @@ async function generateLocalChatCompletion(messages, options = {}) {
   return output;
 }
 
+// src/lib/tools/selector.ts
+var DEFAULT_TOOL_SELECTOR_MODEL = "Xenova/LaMini-GPT-124M";
+function buildToolSelectionPrompt(userMessage, tools) {
+  const toolList = tools.map((t) => `${t.name} (${t.description})`).join("\n");
+  return `Pick the best tool for the task. Reply with ONLY the tool name.
+
+Available tools:
+${toolList}
+none (no tool needed)
+
+Task: "${userMessage}"
+
+Best tool:`;
+}
+function extractParams(userMessage, tool) {
+  const params = {};
+  if (!tool.parameters) return params;
+  for (const param of tool.parameters) {
+    if (param.name === "expression" || param.name === "query") {
+      params[param.name] = userMessage;
+    } else if (param.name === "location" || param.name === "city") {
+      const words = userMessage.split(/\s+/);
+      const capitalizedWords = words.filter(
+        (w) => w.length > 1 && w[0] === w[0].toUpperCase()
+      );
+      params[param.name] = capitalizedWords.length > 0 ? capitalizedWords.join(" ") : userMessage;
+    } else if (param.name === "text" || param.name === "input") {
+      params[param.name] = userMessage;
+    } else {
+      params[param.name] = userMessage;
+    }
+  }
+  return params;
+}
+function parseToolSelectionResponse(response, tools, userMessage) {
+  console.log("[Tool Selector] Raw response:", response);
+  const cleaned = response.toLowerCase().trim().split(/[\s\n,.]+/)[0].replace(/[^a-z0-9_-]/g, "");
+  console.log("[Tool Selector] Parsed tool name:", cleaned);
+  if (cleaned === "none" || cleaned === "null" || cleaned === "") {
+    console.log("[Tool Selector] No tool selected");
+    return { toolSelected: false };
+  }
+  const selectedTool = tools.find((t) => t.name.toLowerCase() === cleaned);
+  if (!selectedTool) {
+    const fuzzyTool = tools.find(
+      (t) => t.name.toLowerCase().includes(cleaned) || cleaned.includes(t.name.toLowerCase())
+    );
+    if (fuzzyTool) {
+      console.log(`[Tool Selector] Fuzzy matched tool: ${fuzzyTool.name}`);
+      const params2 = extractParams(userMessage, fuzzyTool);
+      return {
+        toolSelected: true,
+        toolName: fuzzyTool.name,
+        parameters: params2,
+        confidence: 0.6
+      };
+    }
+    console.warn(`[Tool Selector] Unknown tool: ${cleaned}`);
+    return { toolSelected: false };
+  }
+  const params = extractParams(userMessage, selectedTool);
+  console.log(`[Tool Selector] Selected tool: ${selectedTool.name}`, params);
+  return {
+    toolSelected: true,
+    toolName: selectedTool.name,
+    parameters: params,
+    confidence: 0.9
+  };
+}
+async function selectTool(userMessage, tools, options = {}) {
+  const {
+    model = DEFAULT_TOOL_SELECTOR_MODEL,
+    signal,
+    device = "wasm"
+  } = options;
+  if (!tools.length) {
+    return { toolSelected: false };
+  }
+  console.log(
+    `[Tool Selector] analyzing message: "${userMessage}" with model ${model}`
+  );
+  try {
+    const selectorPipeline = await getTextGenerationPipeline({
+      model,
+      device,
+      dtype: "q4"
+      // Aggressive quantization for speed
+    });
+    const prompt = buildToolSelectionPrompt(userMessage, tools);
+    const output = await selectorPipeline(prompt, {
+      max_new_tokens: 4,
+      // Just need the tool name
+      temperature: 0,
+      // Deterministic
+      do_sample: false,
+      return_full_text: false
+    });
+    if (signal?.aborted) {
+      return { toolSelected: false };
+    }
+    const generatedText = output?.[0]?.generated_text || output?.generated_text || "";
+    return parseToolSelectionResponse(generatedText, tools, userMessage);
+  } catch (error) {
+    console.error("[Tool Selector] Error:", error);
+    return { toolSelected: false };
+  }
+}
+var preloadPromise = null;
+async function preloadToolSelectorModel(options = {}) {
+  if (preloadPromise) {
+    return preloadPromise;
+  }
+  const { model = DEFAULT_TOOL_SELECTOR_MODEL, device = "wasm" } = options;
+  console.log(`[Tool Selector] Preloading model: ${model}`);
+  preloadPromise = getTextGenerationPipeline({
+    model,
+    device,
+    dtype: "q4"
+  }).then(() => {
+    console.log(`[Tool Selector] Model preloaded: ${model}`);
+  }).catch((error) => {
+    console.warn("[Tool Selector] Failed to preload model:", error);
+    preloadPromise = null;
+  });
+  return preloadPromise;
+}
+async function executeTool(tool, params) {
+  try {
+    console.log(
+      `[Tool Selector] Executing tool ${tool.name} with params:`,
+      params
+    );
+    const result = await tool.execute(params);
+    console.log(`[Tool Selector] Tool ${tool.name} execution result:`, result);
+    return { success: true, result };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Tool execution failed";
+    console.error(`[Tool Selector] Tool ${tool.name} failed:`, errorMessage);
+    return { success: false, error: errorMessage };
+  }
+}
+
 // src/react/useChat.ts
 function useChat(options) {
   const {
@@ -47557,9 +47724,13 @@ function useChat(options) {
     onFinish,
     onError,
     chatProvider = "api",
-    localModel = DEFAULT_LOCAL_CHAT_MODEL
+    localModel = DEFAULT_LOCAL_CHAT_MODEL,
+    tools,
+    toolSelectorModel = DEFAULT_TOOL_SELECTOR_MODEL,
+    onToolExecution
   } = options || {};
   const [isLoading, setIsLoading] = (0, import_react.useState)(false);
+  const [isSelectingTool, setIsSelectingTool] = (0, import_react.useState)(false);
   const abortControllerRef = (0, import_react.useRef)(null);
   const stop = (0, import_react.useCallback)(() => {
     if (abortControllerRef.current) {
@@ -47575,11 +47746,17 @@ function useChat(options) {
       }
     };
   }, []);
+  (0, import_react.useEffect)(() => {
+    if (tools && tools.length > 0) {
+      preloadToolSelectorModel({ model: toolSelectorModel });
+    }
+  }, [tools, toolSelectorModel]);
   const sendMessage = (0, import_react.useCallback)(
     async ({
       messages,
       model,
-      onData
+      onData,
+      runTools = true
     }) => {
       if (!messages?.length) {
         const errorMsg = "messages are required to call sendMessage.";
@@ -47592,11 +47769,75 @@ function useChat(options) {
       const abortController = new AbortController();
       abortControllerRef.current = abortController;
       setIsLoading(true);
+      let toolExecutionResult;
+      let messagesWithToolContext = messages;
+      if (runTools && tools && tools.length > 0) {
+        const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
+        if (lastUserMessage?.content) {
+          setIsSelectingTool(true);
+          try {
+            const selectionResult = await selectTool(
+              lastUserMessage.content,
+              tools,
+              {
+                model: toolSelectorModel,
+                signal: abortController.signal
+              }
+            );
+            if (selectionResult.toolSelected && selectionResult.toolName) {
+              const selectedTool = tools.find(
+                (t) => t.name === selectionResult.toolName
+              );
+              if (selectedTool) {
+                const execResult = await executeTool(
+                  selectedTool,
+                  selectionResult.parameters || {}
+                );
+                toolExecutionResult = {
+                  toolName: selectionResult.toolName,
+                  success: execResult.success,
+                  result: execResult.result,
+                  error: execResult.error
+                };
+                if (onToolExecution) {
+                  onToolExecution(toolExecutionResult);
+                }
+                if (toolExecutionResult.success && toolExecutionResult.result !== void 0) {
+                  const toolResultContext = {
+                    role: "system",
+                    content: `Tool "${toolExecutionResult.toolName}" was executed with the following result:
+${JSON.stringify(
+                      toolExecutionResult.result,
+                      null,
+                      2
+                    )}
+
+Use this information to respond to the user's request.`
+                  };
+                  messagesWithToolContext = [...messages, toolResultContext];
+                } else if (toolExecutionResult.error) {
+                  const toolErrorContext = {
+                    role: "system",
+                    content: `Tool "${toolExecutionResult.toolName}" was executed but encountered an error: ${toolExecutionResult.error}
+
+Please inform the user about this issue and try to help them alternatively.`
+                  };
+                  messagesWithToolContext = [...messages, toolErrorContext];
+                }
+              }
+            }
+          } catch (err) {
+            console.warn("Tool selection error:", err);
+          } finally {
+            setIsSelectingTool(false);
+          }
+        }
+      }
       try {
         if (chatProvider === "local") {
           let accumulatedContent = "";
           const usedModel = localModel;
-          const formattedMessages = messages.map((m) => ({
+          const formattedMessages = messagesWithToolContext.map((m) => ({
             role: m.role || "user",
             content: m.content || ""
           }));
@@ -47633,30 +47874,46 @@ function useChat(options) {
           if (onFinish) {
             onFinish(completion);
           }
-          return { data: completion, error: null };
+          return {
+            data: completion,
+            error: null,
+            toolExecution: toolExecutionResult
+          };
         } else {
           if (!model) {
             const errorMsg = "model is required to call sendMessage.";
             if (onError) onError(new Error(errorMsg));
-            return { data: null, error: errorMsg };
+            return {
+              data: null,
+              error: errorMsg,
+              toolExecution: toolExecutionResult
+            };
           }
           if (!getToken) {
             const errorMsg = "Token getter function is required.";
             if (onError) onError(new Error(errorMsg));
-            return { data: null, error: errorMsg };
+            return {
+              data: null,
+              error: errorMsg,
+              toolExecution: toolExecutionResult
+            };
           }
           const token = await getToken();
           if (!token) {
             const errorMsg = "No access token available.";
             setIsLoading(false);
             if (onError) onError(new Error(errorMsg));
-            return { data: null, error: errorMsg };
+            return {
+              data: null,
+              error: errorMsg,
+              toolExecution: toolExecutionResult
+            };
           }
           const sseResult = await client.sse.post({
             baseUrl,
             url: "/api/v1/chat/completions",
             body: {
-              messages,
+              messages: messagesWithToolContext,
               model,
               stream: true
             },
@@ -47726,12 +47983,20 @@ function useChat(options) {
           if (onFinish) {
             onFinish(completion);
           }
-          return { data: completion, error: null };
+          return {
+            data: completion,
+            error: null,
+            toolExecution: toolExecutionResult
+          };
         }
       } catch (err) {
         if (err instanceof Error && err.name === "AbortError") {
           setIsLoading(false);
-          return { data: null, error: "Request aborted" };
+          return {
+            data: null,
+            error: "Request aborted",
+            toolExecution: toolExecutionResult
+          };
         }
         const errorMsg = err instanceof Error ? err.message : "Failed to send message.";
         const errorObj = err instanceof Error ? err : new Error(errorMsg);
@@ -47739,7 +48004,11 @@ function useChat(options) {
         if (onError) {
           onError(errorObj);
         }
-        return { data: null, error: errorMsg };
+        return {
+          data: null,
+          error: errorMsg,
+          toolExecution: toolExecutionResult
+        };
       } finally {
         if (abortControllerRef.current === abortController) {
           abortControllerRef.current = null;
@@ -47753,11 +48022,15 @@ function useChat(options) {
       onFinish,
       onError,
       chatProvider,
-      localModel
+      localModel,
+      tools,
+      toolSelectorModel,
+      onToolExecution
     ]
   );
   return {
     isLoading,
+    isSelectingTool,
     sendMessage,
     stop
   };
@@ -48680,12 +48953,15 @@ var extractConversationContext = (messages, maxMessages = 3) => {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_TOOL_SELECTOR_MODEL,
   createMemoryContextSystemMessage,
   decryptData,
   decryptDataBytes,
   encryptData,
+  executeTool,
   extractConversationContext,
   formatMemoriesForChat,
+  selectTool,
   useChat,
   useEncryption,
   useMemory,

package/dist/react/index.d.mts

@@ -175,6 +175,64 @@ 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;
@@ -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>;
@@ -226,9 +291,25 @@ type UseChatOptions = {
      * 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.
@@ -257,47 +338,56 @@ type UseChatResult = {
  *   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;
@@ -469,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,6 +175,64 @@ 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;
@@ -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>;
@@ -226,9 +291,25 @@ type UseChatOptions = {
      * 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.
@@ -257,47 +338,56 @@ type UseChatResult = {
  *   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;
@@ -469,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.mjs

@@ -821,9 +821,32 @@ var client = createClient(createClientConfig(createConfig()));
 // src/lib/chat/constants.ts
 var DEFAULT_LOCAL_CHAT_MODEL = "onnx-community/Qwen2.5-0.5B-Instruct";
 
-// src/lib/chat/generation.ts
-var chatPipeline = null;
+// src/lib/chat/pipeline.ts
+var sharedPipeline = null;
 var currentModel = null;
+var currentDevice = null;
+async function getTextGenerationPipeline(options) {
+  const { model, device = "wasm", dtype = "q4" } = options;
+  if (sharedPipeline && currentModel === model && currentDevice === device) {
+    return sharedPipeline;
+  }
+  const { pipeline, env } = await import("./transformers.node-BSHUG7OY.mjs");
+  env.allowLocalModels = false;
+  if (env.backends?.onnx) {
+    env.backends.onnx.logLevel = "fatal";
+  }
+  console.log(`[Pipeline] Loading model: ${model} on ${device}...`);
+  sharedPipeline = await pipeline("text-generation", model, {
+    dtype,
+    device
+  });
+  currentModel = model;
+  currentDevice = device;
+  console.log(`[Pipeline] Model loaded: ${model}`);
+  return sharedPipeline;
+}
+
+// src/lib/chat/generation.ts
 async function generateLocalChatCompletion(messages, options = {}) {
   const {
     model = DEFAULT_LOCAL_CHAT_MODEL,
@@ -833,13 +856,12 @@ async function generateLocalChatCompletion(messages, options = {}) {
     onToken,
     signal
   } = options;
-  const { pipeline, TextStreamer } = await import("./transformers.node-BSHUG7OY.mjs");
-  if (!chatPipeline || currentModel !== model) {
-    chatPipeline = await pipeline("text-generation", model, {
-      dtype: "fp16"
-    });
-    currentModel = model;
-  }
+  const { TextStreamer } = await import("./transformers.node-BSHUG7OY.mjs");
+  const chatPipeline = await getTextGenerationPipeline({
+    model,
+    device: "wasm",
+    dtype: "q4"
+  });
   class CallbackStreamer extends TextStreamer {
     constructor(tokenizer, cb) {
       super(tokenizer, {
@@ -866,6 +888,148 @@ async function generateLocalChatCompletion(messages, options = {}) {
   return output;
 }
 
+// src/lib/tools/selector.ts
+var DEFAULT_TOOL_SELECTOR_MODEL = "Xenova/LaMini-GPT-124M";
+function buildToolSelectionPrompt(userMessage, tools) {
+  const toolList = tools.map((t) => `${t.name} (${t.description})`).join("\n");
+  return `Pick the best tool for the task. Reply with ONLY the tool name.
+
+Available tools:
+${toolList}
+none (no tool needed)
+
+Task: "${userMessage}"
+
+Best tool:`;
+}
+function extractParams(userMessage, tool) {
+  const params = {};
+  if (!tool.parameters) return params;
+  for (const param of tool.parameters) {
+    if (param.name === "expression" || param.name === "query") {
+      params[param.name] = userMessage;
+    } else if (param.name === "location" || param.name === "city") {
+      const words = userMessage.split(/\s+/);
+      const capitalizedWords = words.filter(
+        (w) => w.length > 1 && w[0] === w[0].toUpperCase()
+      );
+      params[param.name] = capitalizedWords.length > 0 ? capitalizedWords.join(" ") : userMessage;
+    } else if (param.name === "text" || param.name === "input") {
+      params[param.name] = userMessage;
+    } else {
+      params[param.name] = userMessage;
+    }
+  }
+  return params;
+}
+function parseToolSelectionResponse(response, tools, userMessage) {
+  console.log("[Tool Selector] Raw response:", response);
+  const cleaned = response.toLowerCase().trim().split(/[\s\n,.]+/)[0].replace(/[^a-z0-9_-]/g, "");
+  console.log("[Tool Selector] Parsed tool name:", cleaned);
+  if (cleaned === "none" || cleaned === "null" || cleaned === "") {
+    console.log("[Tool Selector] No tool selected");
+    return { toolSelected: false };
+  }
+  const selectedTool = tools.find((t) => t.name.toLowerCase() === cleaned);
+  if (!selectedTool) {
+    const fuzzyTool = tools.find(
+      (t) => t.name.toLowerCase().includes(cleaned) || cleaned.includes(t.name.toLowerCase())
+    );
+    if (fuzzyTool) {
+      console.log(`[Tool Selector] Fuzzy matched tool: ${fuzzyTool.name}`);
+      const params2 = extractParams(userMessage, fuzzyTool);
+      return {
+        toolSelected: true,
+        toolName: fuzzyTool.name,
+        parameters: params2,
+        confidence: 0.6
+      };
+    }
+    console.warn(`[Tool Selector] Unknown tool: ${cleaned}`);
+    return { toolSelected: false };
+  }
+  const params = extractParams(userMessage, selectedTool);
+  console.log(`[Tool Selector] Selected tool: ${selectedTool.name}`, params);
+  return {
+    toolSelected: true,
+    toolName: selectedTool.name,
+    parameters: params,
+    confidence: 0.9
+  };
+}
+async function selectTool(userMessage, tools, options = {}) {
+  const {
+    model = DEFAULT_TOOL_SELECTOR_MODEL,
+    signal,
+    device = "wasm"
+  } = options;
+  if (!tools.length) {
+    return { toolSelected: false };
+  }
+  console.log(
+    `[Tool Selector] analyzing message: "${userMessage}" with model ${model}`
+  );
+  try {
+    const selectorPipeline = await getTextGenerationPipeline({
+      model,
+      device,
+      dtype: "q4"
+      // Aggressive quantization for speed
+    });
+    const prompt = buildToolSelectionPrompt(userMessage, tools);
+    const output = await selectorPipeline(prompt, {
+      max_new_tokens: 4,
+      // Just need the tool name
+      temperature: 0,
+      // Deterministic
+      do_sample: false,
+      return_full_text: false
+    });
+    if (signal?.aborted) {
+      return { toolSelected: false };
+    }
+    const generatedText = output?.[0]?.generated_text || output?.generated_text || "";
+    return parseToolSelectionResponse(generatedText, tools, userMessage);
+  } catch (error) {
+    console.error("[Tool Selector] Error:", error);
+    return { toolSelected: false };
+  }
+}
+var preloadPromise = null;
+async function preloadToolSelectorModel(options = {}) {
+  if (preloadPromise) {
+    return preloadPromise;
+  }
+  const { model = DEFAULT_TOOL_SELECTOR_MODEL, device = "wasm" } = options;
+  console.log(`[Tool Selector] Preloading model: ${model}`);
+  preloadPromise = getTextGenerationPipeline({
+    model,
+    device,
+    dtype: "q4"
+  }).then(() => {
+    console.log(`[Tool Selector] Model preloaded: ${model}`);
+  }).catch((error) => {
+    console.warn("[Tool Selector] Failed to preload model:", error);
+    preloadPromise = null;
+  });
+  return preloadPromise;
+}
+async function executeTool(tool, params) {
+  try {
+    console.log(
+      `[Tool Selector] Executing tool ${tool.name} with params:`,
+      params
+    );
+    const result = await tool.execute(params);
+    console.log(`[Tool Selector] Tool ${tool.name} execution result:`, result);
+    return { success: true, result };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Tool execution failed";
+    console.error(`[Tool Selector] Tool ${tool.name} failed:`, errorMessage);
+    return { success: false, error: errorMessage };
+  }
+}
+
 // src/react/useChat.ts
 function useChat(options) {
   const {
@@ -875,9 +1039,13 @@ function useChat(options) {
     onFinish,
     onError,
     chatProvider = "api",
-    localModel = DEFAULT_LOCAL_CHAT_MODEL
+    localModel = DEFAULT_LOCAL_CHAT_MODEL,
+    tools,
+    toolSelectorModel = DEFAULT_TOOL_SELECTOR_MODEL,
+    onToolExecution
   } = options || {};
   const [isLoading, setIsLoading] = useState(false);
+  const [isSelectingTool, setIsSelectingTool] = useState(false);
   const abortControllerRef = useRef(null);
   const stop = useCallback(() => {
     if (abortControllerRef.current) {
@@ -893,11 +1061,17 @@ function useChat(options) {
       }
     };
   }, []);
+  useEffect(() => {
+    if (tools && tools.length > 0) {
+      preloadToolSelectorModel({ model: toolSelectorModel });
+    }
+  }, [tools, toolSelectorModel]);
   const sendMessage = useCallback(
     async ({
       messages,
       model,
-      onData
+      onData,
+      runTools = true
     }) => {
       if (!messages?.length) {
         const errorMsg = "messages are required to call sendMessage.";
@@ -910,11 +1084,75 @@ function useChat(options) {
       const abortController = new AbortController();
       abortControllerRef.current = abortController;
       setIsLoading(true);
+      let toolExecutionResult;
+      let messagesWithToolContext = messages;
+      if (runTools && tools && tools.length > 0) {
+        const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
+        if (lastUserMessage?.content) {
+          setIsSelectingTool(true);
+          try {
+            const selectionResult = await selectTool(
+              lastUserMessage.content,
+              tools,
+              {
+                model: toolSelectorModel,
+                signal: abortController.signal
+              }
+            );
+            if (selectionResult.toolSelected && selectionResult.toolName) {
+              const selectedTool = tools.find(
+                (t) => t.name === selectionResult.toolName
+              );
+              if (selectedTool) {
+                const execResult = await executeTool(
+                  selectedTool,
+                  selectionResult.parameters || {}
+                );
+                toolExecutionResult = {
+                  toolName: selectionResult.toolName,
+                  success: execResult.success,
+                  result: execResult.result,
+                  error: execResult.error
+                };
+                if (onToolExecution) {
+                  onToolExecution(toolExecutionResult);
+                }
+                if (toolExecutionResult.success && toolExecutionResult.result !== void 0) {
+                  const toolResultContext = {
+                    role: "system",
+                    content: `Tool "${toolExecutionResult.toolName}" was executed with the following result:
+${JSON.stringify(
+                      toolExecutionResult.result,
+                      null,
+                      2
+                    )}
+
+Use this information to respond to the user's request.`
+                  };
+                  messagesWithToolContext = [...messages, toolResultContext];
+                } else if (toolExecutionResult.error) {
+                  const toolErrorContext = {
+                    role: "system",
+                    content: `Tool "${toolExecutionResult.toolName}" was executed but encountered an error: ${toolExecutionResult.error}
+
+Please inform the user about this issue and try to help them alternatively.`
+                  };
+                  messagesWithToolContext = [...messages, toolErrorContext];
+                }
+              }
+            }
+          } catch (err) {
+            console.warn("Tool selection error:", err);
+          } finally {
+            setIsSelectingTool(false);
+          }
+        }
+      }
       try {
         if (chatProvider === "local") {
           let accumulatedContent = "";
           const usedModel = localModel;
-          const formattedMessages = messages.map((m) => ({
+          const formattedMessages = messagesWithToolContext.map((m) => ({
             role: m.role || "user",
             content: m.content || ""
           }));
@@ -951,30 +1189,46 @@ function useChat(options) {
           if (onFinish) {
             onFinish(completion);
           }
-          return { data: completion, error: null };
+          return {
+            data: completion,
+            error: null,
+            toolExecution: toolExecutionResult
+          };
         } else {
           if (!model) {
             const errorMsg = "model is required to call sendMessage.";
             if (onError) onError(new Error(errorMsg));
-            return { data: null, error: errorMsg };
+            return {
+              data: null,
+              error: errorMsg,
+              toolExecution: toolExecutionResult
+            };
           }
           if (!getToken) {
             const errorMsg = "Token getter function is required.";
             if (onError) onError(new Error(errorMsg));
-            return { data: null, error: errorMsg };
+            return {
+              data: null,
+              error: errorMsg,
+              toolExecution: toolExecutionResult
+            };
           }
           const token = await getToken();
           if (!token) {
             const errorMsg = "No access token available.";
             setIsLoading(false);
             if (onError) onError(new Error(errorMsg));
-            return { data: null, error: errorMsg };
+            return {
+              data: null,
+              error: errorMsg,
+              toolExecution: toolExecutionResult
+            };
           }
           const sseResult = await client.sse.post({
             baseUrl,
             url: "/api/v1/chat/completions",
             body: {
-              messages,
+              messages: messagesWithToolContext,
               model,
               stream: true
             },
@@ -1044,12 +1298,20 @@ function useChat(options) {
           if (onFinish) {
             onFinish(completion);
           }
-          return { data: completion, error: null };
+          return {
+            data: completion,
+            error: null,
+            toolExecution: toolExecutionResult
+          };
         }
       } catch (err) {
         if (err instanceof Error && err.name === "AbortError") {
           setIsLoading(false);
-          return { data: null, error: "Request aborted" };
+          return {
+            data: null,
+            error: "Request aborted",
+            toolExecution: toolExecutionResult
+          };
         }
         const errorMsg = err instanceof Error ? err.message : "Failed to send message.";
         const errorObj = err instanceof Error ? err : new Error(errorMsg);
@@ -1057,7 +1319,11 @@ function useChat(options) {
         if (onError) {
           onError(errorObj);
         }
-        return { data: null, error: errorMsg };
+        return {
+          data: null,
+          error: errorMsg,
+          toolExecution: toolExecutionResult
+        };
       } finally {
         if (abortControllerRef.current === abortController) {
           abortControllerRef.current = null;
@@ -1071,11 +1337,15 @@ function useChat(options) {
       onFinish,
       onError,
       chatProvider,
-      localModel
+      localModel,
+      tools,
+      toolSelectorModel,
+      onToolExecution
     ]
   );
   return {
     isLoading,
+    isSelectingTool,
     sendMessage,
     stop
   };
@@ -1997,12 +2267,15 @@ var extractConversationContext = (messages, maxMessages = 3) => {
   return userMessages.trim();
 };
 export {
+  DEFAULT_TOOL_SELECTOR_MODEL,
   createMemoryContextSystemMessage,
   decryptData,
   decryptDataBytes,
   encryptData,
+  executeTool,
   extractConversationContext,
   formatMemoriesForChat,
+  selectTool,
   useChat,
   useEncryption,
   useMemory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reverbia/sdk",
-  "version": "1.0.0-next.20251202092727",
+  "version": "1.0.0-next.20251202095402",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",