@superatomai/sdk-node 0.0.10 → 0.0.12

package/dist/index.mjs

@@ -445,6 +445,13 @@ var ComponentListResponseMessageSchema = z3.object({
   type: z3.literal("COMPONENT_LIST_RES"),
   payload: ComponentListResponsePayloadSchema
 });
+var ToolSchema = z3.object({
+  id: z3.string(),
+  name: z3.string(),
+  description: z3.string(),
+  params: z3.record(z3.string()),
+  fn: z3.function().args(z3.any()).returns(z3.any())
+});
 var UsersRequestPayloadSchema = z3.object({
   operation: z3.enum(["create", "update", "delete", "getAll", "getOne"]),
   data: z3.object({
@@ -515,6 +522,26 @@ var ReportsRequestMessageSchema = z3.object({
   type: z3.literal("REPORTS"),
   payload: ReportsRequestPayloadSchema
 });
+var BookmarkDataSchema = z3.object({
+  id: z3.number().optional(),
+  uiblock: z3.any(),
+  // JSON object
+  created_at: z3.string().optional(),
+  updated_at: z3.string().optional()
+});
+var BookmarksRequestPayloadSchema = z3.object({
+  operation: z3.enum(["create", "update", "delete", "getAll", "getOne"]),
+  data: z3.object({
+    id: z3.number().optional(),
+    uiblock: z3.any().optional()
+  }).optional()
+});
+var BookmarksRequestMessageSchema = z3.object({
+  id: z3.string(),
+  from: MessageParticipantSchema,
+  type: z3.literal("BOOKMARKS"),
+  payload: BookmarksRequestPayloadSchema
+});
 
 // src/utils/logger.ts
 import fs from "fs";
@@ -972,6 +999,7 @@ var Thread = class {
       let assistantResponse = "";
       const hasComponent = metadata && Object.keys(metadata).length > 0 && metadata.type;
       const hasTextResponse = textResponse && textResponse.trim().length > 0;
+      const responseParts = [];
       if (hasComponent) {
         const parts = [];
         if (metadata.type) {
@@ -980,21 +1008,19 @@ var Thread = class {
         if (metadata.name) {
           parts.push(`Name: ${metadata.name}`);
         }
-        if (metadata.props?.title) {
-          parts.push(`Title: "${metadata.props.title}"`);
-        }
-        if (metadata.props?.query) {
-          const query = metadata.props.query;
-          const truncatedQuery = query.length > 200 ? query.substring(0, 200) + "..." : query;
-          parts.push(`Query: ${truncatedQuery}`);
+        if (metadata.description) {
+          parts.push(`Description: ${metadata.description}`);
         }
-        if (metadata.props?.config?.components && Array.isArray(metadata.props.config.components)) {
-          const componentTypes = metadata.props.config.components.map((c) => c.type).join(", ");
-          parts.push(`Multi-component with: ${componentTypes}`);
+        if (metadata.props) {
+          parts.push(`Props: ${JSON.stringify(metadata.props)}`);
         }
-        assistantResponse = parts.join(", ");
-      } else if (hasTextResponse) {
-        assistantResponse = textResponse;
+        responseParts.push(parts.join("\n"));
+      }
+      if (hasTextResponse) {
+        responseParts.push(textResponse);
+      }
+      if (responseParts.length > 0) {
+        assistantResponse = responseParts.join("\n");
       } else {
         assistantResponse = "No response generated";
       }
@@ -2346,18 +2372,16 @@ Your job is to:
 1. **Parse the component suggestions** from the text response (format: 1:component_type : reasoning)
 2. **Match each suggestion with an actual component** from the available list
 3. **Generate proper props** for each matched component to **visualize the analysis results** that were already fetched
-4. **SELECT the best dashboard layout component** that can accommodate all the matched components
+4. **Generate title and description** for the dashboard container
 5. **Generate intelligent follow-up questions (actions)** that the user might naturally ask next based on the data analysis
 
 **CRITICAL GOAL**: Create dashboard components that display the **same data that was already analyzed** - NOT new data. The queries already ran and got results. You're just creating different visualizations of those results.
 
-**APPROACH**: First match all the components suggested in the text response, THEN find the layout that best fits those components.
-
 ## Available Components
 
 {{AVAILABLE_COMPONENTS}}
 
-## Component Matching Rules (STEP 1)
+## Component Matching Rules
 For each component suggestion (c1, c2, c3, etc.) from the text response:
 
 1. **Match by type**: Find components whose \`type\` matches the suggested component type
@@ -2366,23 +2390,10 @@ For each component suggestion (c1, c2, c3, etc.) from the text response:
    - Best fit for the data being visualized
 3. **Fallback**: If no exact type match, find the closest alternative
 
-## Layout Selection Logic (STEP 2 - After Matching Components)
-
-**After you have matched all components**, select the best dashboard layout:
-
-1. **Find layout components** by looking for components with \`type: "DashboardLayout"\` in the available components list
-2. **Read each layout's description** to understand:
-   - What structure it provides
-   - When it's best used (e.g., comprehensive analysis vs focused analysis)
-   - The number and types of components it can accommodate
-3. **Select the best layout** based on:
-   - Which layout can best display ALL the matched components
-   - The layout's capacity (how many components it supports)
-   - The types of matched components (KPI, charts, tables, etc.)
-   - The user question and data complexity
-4. **If no specific layout fits**, fall back to "MultiComponentContainer" as the default layout
-
-**IMPORTANT:** The layout should be chosen to FIT the matched components, not the other way around. Don't force components to fit a layout - find a layout that accommodates your components.
+## Dashboard Container
+All matched components will be placed in the default **MultiComponentContainer** layout. Your job is to:
+1. **Generate a clear title** for the dashboard that summarizes what it shows
+2. **Generate a brief description** explaining the dashboard's purpose and scope
 
 ## Props Generation Rules
 
@@ -2496,8 +2507,8 @@ You MUST respond with ONLY a valid JSON object (no markdown, no code blocks):
 
 \`\`\`json
 {
-  "selectedLayoutId": "id_of_the_selected_layout_component",
-  "layoutReasoning": "Why this layout was selected based on its description and the analysis needs",
+  "layoutTitle": "Clear, concise title for the overall dashboard/layout (5-10 words)",
+  "layoutDescription": "Brief description of what the dashboard shows and its purpose (1-2 sentences)",
   "matchedComponents": [
     {
       "componentId": "id_from_available_list",
@@ -2527,17 +2538,14 @@ You MUST respond with ONLY a valid JSON object (no markdown, no code blocks):
 \`\`\`
 
 **CRITICAL:**
-- \`matchedComponents\` MUST include ALL components suggested in the text response (match them first!)
-- \`selectedLayoutId\` MUST be the ID of the selected layout component (must have type "DashboardLayout")
-- \`layoutReasoning\` MUST explain:
-  - Why you chose this specific layout component
-  - How many components you matched (e.g., "Matched 3 components: 1 KPI, 1 chart, 1 table")
-  - Why this layout is the best fit for displaying these specific matched components
-  - What makes this layout appropriate for the component types and count
-- The layout selection happens AFTER component matching - don't force components to fit a pre-selected layout
+- \`matchedComponents\` MUST include ALL components suggested in the text response
+- \`layoutTitle\` MUST be a clear, concise title (5-10 words) that summarizes what the entire dashboard shows
+  - Examples: "Sales Performance Overview", "Customer Metrics Analysis", "Product Category Breakdown"
+- \`layoutDescription\` MUST be a brief description (1-2 sentences) explaining the purpose and scope of the dashboard
+  - Should describe what insights the dashboard provides and what data it shows
 - \`actions\` MUST be an array of 4-5 intelligent follow-up questions based on the analysis
 - Return ONLY valid JSON (no markdown code blocks, no text before/after)
-- Generate complete props for each component
+- Generate complete props for each component including query, title, description, and config
 
 
 `,
@@ -2589,6 +2597,71 @@ Format your response as a JSON object with this structure:
 }
 
 Return ONLY valid JSON.`
+  },
+  "execute-tools": {
+    system: `You are an expert AI assistant that executes external tools to fetch data from external services.
+
+You have access to external tools that can retrieve information like emails, calendar events, and other external data. When the user requests this information, you should call the appropriate tools.
+
+## Available External Tools
+{{AVAILABLE_TOOLS}}
+
+## Your Task
+
+Analyze the user's request and:
+
+1. **Determine if external tools are needed**
+   - Examples that NEED external tools:
+     - "Show me my emails" \u2192 needs email tool
+     - "Get my last 5 Gmail messages" \u2192 needs Gmail tool
+     - "Check my Outlook inbox" \u2192 needs Outlook tool
+
+   - Examples that DON'T need external tools:
+     - "What is the total sales?" \u2192 database query (handled elsewhere)
+     - "Show me revenue trends" \u2192 internal data analysis
+     - "Hello" \u2192 general conversation
+
+2. **Call the appropriate tools**
+   - Use the tool calling mechanism to execute external tools
+   - Extract parameters from the user's request
+   - Use sensible defaults when parameters aren't specified:
+     - For email limit: default to 10
+     - For email address: use "me" for the authenticated user if not specified
+
+3. **Handle errors and retry**
+   - If a tool call fails, analyze the error message
+   - Retry with corrected parameters if possible
+   - You have up to 3 attempts per tool
+
+## Important Guidelines
+
+- **Only call external tools when necessary** - Don't call tools for database queries or general conversation
+- **Choose the right tool** - For email requests, select Gmail vs Outlook based on:
+  - Explicit mention (e.g., "Gmail", "Outlook")
+  - Email domain (e.g., @gmail.com \u2192 Gmail, @company.com \u2192 Outlook)
+- **Extract parameters carefully** - Use the user's exact values when provided
+- **If no tools are needed** - Simply respond that no external tools are required for this request
+
+## Examples
+
+**Example 1 - Gmail Request:**
+User: "Show me my last 5 Gmail messages"
+Action: Call get-gmail-mails tool with parameters: { email: "me", limit: 5 }
+
+**Example 2 - Outlook Request:**
+User: "Get emails from john.doe@company.com"
+Action: Call get-outlook-mails tool with parameters: { email: "john.doe@company.com", limit: 10 }
+
+**Example 3 - No Tools Needed:**
+User: "What is the total sales?"
+Response: This is a database query, not an external tool request. No external tools are needed.
+
+**Example 4 - Error Retry:**
+Tool call fails with: "Invalid email parameter"
+Action: Analyze error, correct the parameter, and retry the tool call
+`,
+    user: `{{USER_PROMPT}}
+`
   }
 };
 
@@ -3633,12 +3706,14 @@ var BaseLLM = class {
   /**
    * Match components from text response suggestions and generate follow-up questions
    * Takes a text response with component suggestions (c1:type format) and matches with available components
-   * Also generates intelligent follow-up questions (actions) based on the analysis
+   * Also generates title, description, and intelligent follow-up questions (actions) based on the analysis
+   * All components are placed in a default MultiComponentContainer layout
    * @param textResponse - The text response containing component suggestions
    * @param components - List of available components
    * @param apiKey - Optional API key
    * @param logCollector - Optional log collector
-   * @returns Object containing matched components, selected layout, reasoning, and follow-up actions
+   * @param componentStreamCallback - Optional callback to stream primary KPI component as soon as it's identified
+   * @returns Object containing matched components, layout title/description, and follow-up actions
    */
   async matchComponentsFromTextResponse(textResponse, components, apiKey, logCollector) {
     try {
@@ -3681,24 +3756,17 @@ var BaseLLM = class {
       );
       logger.debug(`[${this.getProviderName()}] Component matching response parsed successfully`);
       const matchedComponents = result.matchedComponents || [];
-      const selectedLayoutId = result.selectedLayoutId || "multi-component-container";
-      const layoutReasoning = result.layoutReasoning || "No layout reasoning provided";
+      const layoutTitle = result.layoutTitle || "Dashboard";
+      const layoutDescription = result.layoutDescription || "Multi-component dashboard";
       const rawActions = result.actions || [];
       const actions = convertQuestionsToActions(rawActions);
-      let selectedLayoutComponent = null;
-      if (selectedLayoutId) {
-        selectedLayoutComponent = components.find((c) => c.id === selectedLayoutId) || null;
-        if (!selectedLayoutComponent) {
-          logger.warn(`[${this.getProviderName()}] Layout component ${selectedLayoutId} not found in available components`);
-        }
-      }
       logger.info(`[${this.getProviderName()}] Matched ${matchedComponents.length} components from text response`);
-      logger.info(`[${this.getProviderName()}] Selected layout: (ID: ${selectedLayoutId})`);
-      logger.info(`[${this.getProviderName()}] Layout reasoning: ${layoutReasoning}`);
+      logger.info(`[${this.getProviderName()}] Layout title: "${layoutTitle}"`);
+      logger.info(`[${this.getProviderName()}] Layout description: "${layoutDescription}"`);
       logger.info(`[${this.getProviderName()}] Generated ${actions.length} follow-up actions`);
       if (matchedComponents.length > 0) {
-        logCollector?.info(`Matched ${matchedComponents.length} components for visualization `);
-        logCollector?.info(`Layout reasoning: ${layoutReasoning}`);
+        logCollector?.info(`Matched ${matchedComponents.length} components for visualization`);
+        logCollector?.info(`Dashboard: "${layoutTitle}"`);
         matchedComponents.forEach((comp, idx) => {
           logCollector?.info(`  ${idx + 1}. ${comp.componentName} (${comp.componentType}): ${comp.reasoning}`);
           if (comp.props?.query) {
@@ -3732,9 +3800,8 @@ var BaseLLM = class {
       }).filter(Boolean);
       return {
         components: finalComponents,
-        selectedLayoutId,
-        selectedLayoutComponent,
-        layoutReasoning,
+        layoutTitle,
+        layoutDescription,
         actions
       };
     } catch (error) {
@@ -3743,13 +3810,158 @@ var BaseLLM = class {
       logCollector?.error(`Failed to match components: ${errorMsg}`);
       return {
         components: [],
-        selectedLayoutId: "",
-        selectedLayoutComponent: null,
-        layoutReasoning: "Failed to match components due to parsing error",
+        layoutTitle: "Dashboard",
+        layoutDescription: "Failed to generate dashboard",
         actions: []
       };
     }
   }
+  /**
+   * Execute external tools based on user request using agentic LLM tool calling
+   * The LLM can directly call tools and retry on errors
+   * @param userPrompt - The user's question/request
+   * @param availableTools - Array of available external tools
+   * @param apiKey - Optional API key for LLM
+   * @param logCollector - Optional log collector
+   * @returns Object containing tool execution results and summary
+   */
+  async executeExternalTools(userPrompt, availableTools, apiKey, logCollector) {
+    const MAX_TOOL_ATTEMPTS = 3;
+    const toolResults = [];
+    try {
+      logger.debug(`[${this.getProviderName()}] Starting agentic external tool execution`);
+      logger.debug(`[${this.getProviderName()}] Available tools: ${availableTools.map((t) => t.name).join(", ")}`);
+      const llmTools = availableTools.map((tool) => {
+        const properties = {};
+        const required = [];
+        Object.entries(tool.params || {}).forEach(([key, type]) => {
+          properties[key] = {
+            type: String(type).toLowerCase(),
+            description: `${key} parameter`
+          };
+          required.push(key);
+        });
+        return {
+          name: tool.id,
+          description: tool.description,
+          input_schema: {
+            type: "object",
+            properties,
+            required
+          }
+        };
+      });
+      const toolAttempts = /* @__PURE__ */ new Map();
+      const toolHandler = async (toolName, toolInput) => {
+        const tool = availableTools.find((t) => t.id === toolName);
+        if (!tool) {
+          const errorMsg = `Tool ${toolName} not found in available tools`;
+          logger.error(`[${this.getProviderName()}] ${errorMsg}`);
+          logCollector?.error(errorMsg);
+          throw new Error(errorMsg);
+        }
+        const attempts = (toolAttempts.get(toolName) || 0) + 1;
+        toolAttempts.set(toolName, attempts);
+        logger.info(`[${this.getProviderName()}] Executing tool: ${tool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})`);
+        logCollector?.info(`Executing ${tool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})...`);
+        if (attempts > MAX_TOOL_ATTEMPTS) {
+          const errorMsg = `Maximum attempts (${MAX_TOOL_ATTEMPTS}) reached for tool: ${tool.name}`;
+          logger.error(`[${this.getProviderName()}] ${errorMsg}`);
+          logCollector?.error(errorMsg);
+          toolResults.push({
+            toolName: tool.name,
+            toolId: tool.id,
+            result: null,
+            error: errorMsg
+          });
+          throw new Error(errorMsg);
+        }
+        try {
+          logger.debug(`[${this.getProviderName()}] Tool ${tool.name} parameters:`, toolInput);
+          const result2 = await tool.fn(toolInput);
+          logger.info(`[${this.getProviderName()}] Tool ${tool.name} executed successfully`);
+          logCollector?.info(`\u2713 ${tool.name} completed successfully`);
+          toolResults.push({
+            toolName: tool.name,
+            toolId: tool.id,
+            result: result2
+          });
+          return JSON.stringify(result2, null, 2);
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          logger.error(`[${this.getProviderName()}] Tool ${tool.name} failed (attempt ${attempts}): ${errorMsg}`);
+          logCollector?.error(`\u2717 ${tool.name} failed: ${errorMsg}`);
+          if (attempts >= MAX_TOOL_ATTEMPTS) {
+            toolResults.push({
+              toolName: tool.name,
+              toolId: tool.id,
+              result: null,
+              error: errorMsg
+            });
+          }
+          throw new Error(`Tool execution failed: ${errorMsg}`);
+        }
+      };
+      const prompts = await promptLoader.loadPrompts("execute-tools", {
+        USER_PROMPT: userPrompt,
+        AVAILABLE_TOOLS: availableTools.map((tool, idx) => {
+          const paramsText = Object.entries(tool.params || {}).map(([key, type]) => `  - ${key}: ${type}`).join("\n");
+          return `${idx + 1}. ID: ${tool.id}
+   Name: ${tool.name}
+   Description: ${tool.description}
+   Parameters:
+${paramsText}`;
+        }).join("\n\n")
+      });
+      logger.debug(`[${this.getProviderName()}] Using agentic tool calling for external tools`);
+      logCollector?.info("Analyzing request and executing external tools...");
+      const result = await LLM.streamWithTools(
+        {
+          sys: prompts.system,
+          user: prompts.user
+        },
+        llmTools,
+        toolHandler,
+        {
+          model: this.model,
+          maxTokens: 2e3,
+          temperature: 0.2,
+          apiKey: this.getApiKey(apiKey)
+        },
+        MAX_TOOL_ATTEMPTS + 2
+        // max iterations: allows for retries + final response
+      );
+      logger.info(`[${this.getProviderName()}] External tool execution completed`);
+      const successfulTools = toolResults.filter((r) => !r.error);
+      const failedTools = toolResults.filter((r) => r.error);
+      let summary = "";
+      if (successfulTools.length > 0) {
+        summary += `Successfully executed ${successfulTools.length} tool(s): ${successfulTools.map((t) => t.toolName).join(", ")}.
+`;
+      }
+      if (failedTools.length > 0) {
+        summary += `Failed to execute ${failedTools.length} tool(s): ${failedTools.map((t) => t.toolName).join(", ")}.`;
+      }
+      if (toolResults.length === 0) {
+        summary = "No external tools were needed for this request.";
+      }
+      logger.info(`[${this.getProviderName()}] Tool execution summary: ${summary}`);
+      return {
+        toolResults,
+        summary,
+        hasResults: successfulTools.length > 0
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      logger.error(`[${this.getProviderName()}] Error in external tool execution: ${errorMsg}`);
+      logCollector?.error(`Error executing external tools: ${errorMsg}`);
+      return {
+        toolResults,
+        summary: `Error executing external tools: ${errorMsg}`,
+        hasResults: false
+      };
+    }
+  }
   /**
    * Generate text-based response for user question
    * This provides conversational text responses instead of component generation
@@ -3758,12 +3970,40 @@ var BaseLLM = class {
    * @param streamCallback - Optional callback function to receive text chunks as they stream
    * @param collections - Collection registry for executing database queries via database.execute
    * @param components - Optional list of available components for matching suggestions
+   * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called
    */
-  async generateTextResponse(userPrompt, apiKey, logCollector, conversationHistory, streamCallback, collections, components) {
+  async generateTextResponse(userPrompt, apiKey, logCollector, conversationHistory, streamCallback, collections, components, externalTools) {
     const errors = [];
     logger.debug(`[${this.getProviderName()}] Starting text response generation`);
     logger.debug(`[${this.getProviderName()}] User prompt: "${userPrompt.substring(0, 50)}..."`);
     try {
+      let externalToolContext = "No external tools were used for this request.";
+      if (externalTools && externalTools.length > 0) {
+        logger.info(`[${this.getProviderName()}] Executing external tools...`);
+        const toolExecution = await this.executeExternalTools(
+          userPrompt,
+          externalTools,
+          apiKey,
+          logCollector
+        );
+        if (toolExecution.hasResults) {
+          const toolResultsText = toolExecution.toolResults.map((tr) => {
+            if (tr.error) {
+              return `**${tr.toolName}** (Failed): ${tr.error}`;
+            }
+            return `**${tr.toolName}** (Success):
+${JSON.stringify(tr.result, null, 2)}`;
+          }).join("\n\n");
+          externalToolContext = `## External Tool Results
+
+${toolExecution.summary}
+
+${toolResultsText}`;
+          logger.info(`[${this.getProviderName()}] External tools executed, results available`);
+        } else {
+          logger.info(`[${this.getProviderName()}] No external tools were needed`);
+        }
+      }
       const schemaDoc = schema.generateSchemaDocumentation();
       const knowledgeBaseContext = await knowledge_base_default.getKnowledgeBase({
         prompt: userPrompt,
@@ -3771,11 +4011,13 @@ var BaseLLM = class {
         topK: 1
       });
       logger.file("\n=============================\nknowledge base context:", knowledgeBaseContext);
+      logger.file("\n=============================\nexternal tool context:", externalToolContext);
       const prompts = await promptLoader.loadPrompts("text-response", {
         USER_PROMPT: userPrompt,
         CONVERSATION_HISTORY: conversationHistory || "No previous conversation",
         SCHEMA_DOC: schemaDoc,
-        KNOWLEDGE_BASE_CONTEXT: knowledgeBaseContext || "No additional knowledge base context available."
+        KNOWLEDGE_BASE_CONTEXT: knowledgeBaseContext || "No additional knowledge base context available.",
+        EXTERNAL_TOOL_CONTEXT: externalToolContext
       });
       logger.file("\n=============================\nsystem prompt:", prompts.system);
       logger.file("\n=============================\nuser prompt:", prompts.user);
@@ -3989,9 +4231,12 @@ ${errorMsg}
           textLength: textResponse.length
         }
       );
+      if (wrappedStreamCallback && components && components.length > 0) {
+        wrappedStreamCallback("__TEXT_COMPLETE__COMPONENT_GENERATION_START__");
+      }
       let matchedComponents = [];
-      let selectedLayoutComponent = null;
-      let layoutReasoning = "No layout selected";
+      let layoutTitle = "Dashboard";
+      let layoutDescription = "Multi-component dashboard";
       let actions = [];
       if (components && components.length > 0) {
         logger.info(`[${this.getProviderName()}] Matching components from text response...`);
@@ -4002,46 +4247,30 @@ ${errorMsg}
           logCollector
         );
         matchedComponents = matchResult.components;
-        selectedLayoutComponent = matchResult.selectedLayoutComponent;
-        layoutReasoning = matchResult.layoutReasoning;
+        layoutTitle = matchResult.layoutTitle;
+        layoutDescription = matchResult.layoutDescription;
         actions = matchResult.actions;
       }
       let container_componet = null;
       if (matchedComponents.length > 0) {
-        if (selectedLayoutComponent) {
-          container_componet = {
-            ...selectedLayoutComponent,
-            id: `${selectedLayoutComponent.id}_${Date.now()}`,
-            // Make ID unique for each instance
-            props: {
-              ...selectedLayoutComponent.props,
-              config: {
-                ...selectedLayoutComponent.props?.config || {},
-                components: matchedComponents
-              },
-              actions
-            }
-          };
-          logger.info(`[${this.getProviderName()}] Created ${selectedLayoutComponent.name} (${selectedLayoutComponent.type}) container with ${matchedComponents.length} components and ${actions.length} actions`);
-          logCollector?.info(`Created ${selectedLayoutComponent.name} with ${matchedComponents.length} components and ${actions.length} actions: ${layoutReasoning}`);
-        } else {
-          container_componet = {
-            id: `multi_container_${Date.now()}`,
-            name: "MultiComponentContainer",
-            type: "Container",
-            description: layoutReasoning,
-            category: "dynamic",
-            keywords: ["dashboard", "layout", "container"],
-            props: {
-              config: {
-                components: matchedComponents
-              },
-              actions
-            }
-          };
-          logger.info(`[${this.getProviderName()}] Created fallback MultiComponentContainer with ${matchedComponents.length} components and ${actions.length} actions`);
-          logCollector?.info(`Created MultiComponentContainer with ${matchedComponents.length} components and ${actions.length} actions: ${layoutReasoning}`);
-        }
+        container_componet = {
+          id: `multi_container_${Date.now()}`,
+          name: "MultiComponentContainer",
+          type: "Container",
+          description: layoutDescription,
+          category: "dynamic",
+          keywords: ["dashboard", "layout", "container"],
+          props: {
+            config: {
+              components: matchedComponents,
+              title: layoutTitle,
+              description: layoutDescription
+            },
+            actions
+          }
+        };
+        logger.info(`[${this.getProviderName()}] Created MultiComponentContainer: "${layoutTitle}" with ${matchedComponents.length} components and ${actions.length} actions`);
+        logCollector?.info(`Created dashboard: "${layoutTitle}" with ${matchedComponents.length} components and ${actions.length} actions`);
       }
       return {
         success: true,
@@ -4049,7 +4278,6 @@ ${errorMsg}
           text: textResponse,
           matchedComponents,
           component: container_componet,
-          layoutReasoning,
           actions,
           method: `${this.getProviderName()}-text-response`
         },
@@ -4260,8 +4488,9 @@ ${errorMsg}
    * @param responseMode - 'component' for component generation (default), 'text' for text responses
    * @param streamCallback - Optional callback function to receive text chunks as they stream (only for text mode)
    * @param collections - Collection registry for executing database queries (required for text mode)
+   * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called (only for text mode)
    */
-  async handleUserRequest(userPrompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections) {
+  async handleUserRequest(userPrompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) {
     const startTime = Date.now();
     logger.info(`[${this.getProviderName()}] handleUserRequest called with responseMode: ${responseMode}`);
     if (responseMode === "text") {
@@ -4274,7 +4503,8 @@ ${errorMsg}
         conversationHistory,
         streamCallback,
         collections,
-        components
+        components,
+        externalTools
       );
       if (!textResponse.success) {
         const elapsedTime3 = Date.now() - startTime;
@@ -4420,7 +4650,7 @@ function getLLMProviders() {
     return DEFAULT_PROVIDERS;
   }
 }
-var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections) => {
+var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
   logger.debug("[useAnthropicMethod] Initializing Anthropic Claude matching method");
   logger.debug(`[useAnthropicMethod] Response mode: ${responseMode}`);
   const msg = `Using Anthropic Claude ${responseMode === "text" ? "text response" : "matching"} method...`;
@@ -4432,11 +4662,11 @@ var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conver
     return { success: false, errors: [emptyMsg] };
   }
   logger.debug(`[useAnthropicMethod] Processing with ${components.length} components`);
-  const matchResult = await anthropicLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections);
+  const matchResult = await anthropicLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
   logger.info(`[useAnthropicMethod] Successfully generated ${responseMode} using Anthropic`);
   return matchResult;
 };
-var useGroqMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections) => {
+var useGroqMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
   logger.debug("[useGroqMethod] Initializing Groq LLM matching method");
   logger.debug(`[useGroqMethod] Response mode: ${responseMode}`);
   const msg = `Using Groq LLM ${responseMode === "text" ? "text response" : "matching"} method...`;
@@ -4449,14 +4679,14 @@ var useGroqMethod = async (prompt, components, apiKey, logCollector, conversatio
     return { success: false, errors: [emptyMsg] };
   }
   logger.debug(`[useGroqMethod] Processing with ${components.length} components`);
-  const matchResult = await groqLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections);
+  const matchResult = await groqLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
   logger.info(`[useGroqMethod] Successfully generated ${responseMode} using Groq`);
   return matchResult;
 };
 var getUserResponseFromCache = async (prompt) => {
   return false;
 };
-var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey, llmProviders, logCollector, conversationHistory, responseMode = "component", streamCallback, collections) => {
+var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey, llmProviders, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
   logger.debug(`[get_user_response] Starting user response generation for prompt: "${prompt.substring(0, 50)}..."`);
   logger.debug(`[get_user_response] Response mode: ${responseMode}`);
   logger.debug("[get_user_response] Checking cache for existing response");
@@ -4489,9 +4719,9 @@ var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey,
     logCollector?.info(attemptMsg);
     let result;
     if (provider === "anthropic") {
-      result = await useAnthropicMethod(prompt, components, anthropicApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections);
+      result = await useAnthropicMethod(prompt, components, anthropicApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
     } else if (provider === "groq") {
-      result = await useGroqMethod(prompt, components, groqApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections);
+      result = await useGroqMethod(prompt, components, groqApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
     } else {
       logger.warn(`[get_user_response] Unknown provider: ${provider} - skipping`);
       errors.push(`Unknown provider: ${provider}`);
@@ -4715,11 +4945,11 @@ var CONTEXT_CONFIG = {
    * Set to 0 to disable conversation history
    * Higher values provide more context but may increase token usage
    */
-  MAX_CONVERSATION_CONTEXT_BLOCKS: 2
+  MAX_CONVERSATION_CONTEXT_BLOCKS: 3
 };
 
 // src/handlers/user-prompt-request.ts
-var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections) => {
+var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools) => {
   const errors = [];
   logger.debug("[USER_PROMPT_REQ] Parsing incoming message data");
   const parseResult = UserPromptRequestMessageSchema.safeParse(data);
@@ -4799,7 +5029,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     conversationHistory,
     responseMode,
     streamCallback,
-    collections
+    collections,
+    externalTools
   );
   logCollector.info("User prompt request completed");
   const uiBlockId = existingUiBlockId;
@@ -4860,8 +5091,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     wsId
   };
 };
-async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections) {
-  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections);
+async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools) {
+  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools);
   sendDataResponse4(
     response.id || data.id,
     {
@@ -5935,6 +6166,183 @@ function sendResponse5(id, res, sendMessage, clientId) {
   sendMessage(response);
 }
 
+// src/handlers/bookmarks.ts
+async function handleBookmarksRequest(data, collections, sendMessage) {
+  const executeCollection = async (collection, op, params) => {
+    const handler = collections[collection]?.[op];
+    if (!handler) {
+      throw new Error(`Collection operation ${collection}.${op} not found`);
+    }
+    return await handler(params);
+  };
+  try {
+    const request = BookmarksRequestMessageSchema.parse(data);
+    const { id, payload, from } = request;
+    const { operation, data: requestData } = payload;
+    const bookmarkId = requestData?.id;
+    const uiblock = requestData?.uiblock;
+    switch (operation) {
+      case "create":
+        await handleCreate4(id, uiblock, executeCollection, sendMessage, from.id);
+        break;
+      case "update":
+        await handleUpdate4(id, bookmarkId, uiblock, executeCollection, sendMessage, from.id);
+        break;
+      case "delete":
+        await handleDelete4(id, bookmarkId, executeCollection, sendMessage, from.id);
+        break;
+      case "getAll":
+        await handleGetAll4(id, executeCollection, sendMessage, from.id);
+        break;
+      case "getOne":
+        await handleGetOne4(id, bookmarkId, executeCollection, sendMessage, from.id);
+        break;
+      default:
+        sendResponse6(id, {
+          success: false,
+          error: `Unknown operation: ${operation}`
+        }, sendMessage, from.id);
+    }
+  } catch (error) {
+    logger.error("Failed to handle bookmarks request:", error);
+    sendResponse6(null, {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error occurred"
+    }, sendMessage);
+  }
+}
+async function handleCreate4(id, uiblock, executeCollection, sendMessage, clientId) {
+  if (!uiblock) {
+    sendResponse6(id, {
+      success: false,
+      error: "UIBlock data is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  try {
+    const result = await executeCollection("bookmarks", "create", { uiblock });
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      message: "Bookmark created successfully"
+    }, sendMessage, clientId);
+    logger.info(`Bookmark created: ID ${result.data.id}`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to create bookmark"
+    }, sendMessage, clientId);
+  }
+}
+async function handleUpdate4(id, bookmarkId, uiblock, executeCollection, sendMessage, clientId) {
+  if (!bookmarkId) {
+    sendResponse6(id, {
+      success: false,
+      error: "Bookmark ID is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  if (!uiblock) {
+    sendResponse6(id, {
+      success: false,
+      error: "UIBlock data is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  try {
+    const result = await executeCollection("bookmarks", "update", { id: bookmarkId, uiblock });
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      message: "Bookmark updated successfully"
+    }, sendMessage, clientId);
+    logger.info(`Bookmark updated: ID ${bookmarkId}`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to update bookmark"
+    }, sendMessage, clientId);
+  }
+}
+async function handleDelete4(id, bookmarkId, executeCollection, sendMessage, clientId) {
+  if (!bookmarkId) {
+    sendResponse6(id, {
+      success: false,
+      error: "Bookmark ID is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  try {
+    const result = await executeCollection("bookmarks", "delete", { id: bookmarkId });
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      message: "Bookmark deleted successfully"
+    }, sendMessage, clientId);
+    logger.info(`Bookmark deleted: ID ${bookmarkId}`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to delete bookmark"
+    }, sendMessage, clientId);
+  }
+}
+async function handleGetAll4(id, executeCollection, sendMessage, clientId) {
+  try {
+    const result = await executeCollection("bookmarks", "getAll", {});
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      count: result.count,
+      message: `Retrieved ${result.count} bookmarks`
+    }, sendMessage, clientId);
+    logger.info(`Retrieved all bookmarks (count: ${result.count})`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to get bookmarks"
+    }, sendMessage, clientId);
+  }
+}
+async function handleGetOne4(id, bookmarkId, executeCollection, sendMessage, clientId) {
+  if (!bookmarkId) {
+    sendResponse6(id, {
+      success: false,
+      error: "Bookmark ID is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  try {
+    const result = await executeCollection("bookmarks", "getOne", { id: bookmarkId });
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      message: `Retrieved bookmark ID ${bookmarkId}`
+    }, sendMessage, clientId);
+    logger.info(`Retrieved bookmark: ID ${bookmarkId}`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to get bookmark"
+    }, sendMessage, clientId);
+  }
+}
+function sendResponse6(id, res, sendMessage, clientId) {
+  const response = {
+    id: id || "unknown",
+    type: "BOOKMARKS_RES",
+    from: { type: "data-agent" },
+    to: {
+      type: "user",
+      id: clientId
+    },
+    payload: {
+      ...res
+    }
+  };
+  sendMessage(response);
+}
+
 // src/auth/user-manager.ts
 import fs5 from "fs";
 import path4 from "path";
@@ -6759,6 +7167,7 @@ var SuperatomSDK = class {
     this.maxReconnectAttempts = 5;
     this.collections = {};
     this.components = [];
+    this.tools = [];
     if (config.logLevel) {
       logger.setLogLevel(config.logLevel);
     }
@@ -6914,7 +7323,7 @@ var SuperatomSDK = class {
           });
           break;
         case "USER_PROMPT_REQ":
-          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.llmProviders, this.collections).catch((error) => {
+          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.llmProviders, this.collections, this.tools).catch((error) => {
             logger.error("Failed to handle user prompt request:", error);
           });
           break;
@@ -6948,6 +7357,11 @@ var SuperatomSDK = class {
             logger.error("Failed to handle reports request:", error);
           });
           break;
+        case "BOOKMARKS":
+          handleBookmarksRequest(parsed, this.collections, (msg) => this.send(msg)).catch((error) => {
+            logger.error("Failed to handle bookmarks request:", error);
+          });
+          break;
         default:
           const handler = this.messageTypeHandlers.get(message.type);
           if (handler) {
@@ -7054,6 +7468,19 @@ var SuperatomSDK = class {
   storeComponents(components) {
     this.components = components;
   }
+  /**
+   * Set tools for the SDK instance
+   */
+  setTools(tools) {
+    this.tools = tools;
+    logger.info(`Tools stored in SDK: ${tools.length} tools`);
+  }
+  /**
+   * Get the stored tools
+   */
+  getTools() {
+    return this.tools;
+  }
 };
 export {
   CONTEXT_CONFIG,