@minded-ai/mindedjs 2.0.36 → 2.0.38

package/docs/tooling/extraction.md

@@ -1,59 +1,65 @@
 # Data Extraction
 
-MindedJS provides a powerful AI-based extraction tool for extracting structured data from unstructured text. The extraction system uses LLM capabilities to parse content and return data in a predefined format.
+Extract structured data from unstructured text using AI. The `minded-extraction` tool uses LLM capabilities to parse content and return data in a predefined format.
 
 ## Overview
 
-The extraction tool (`minded-extraction`) enables you to extract specific information from text using:
-
-- **Structured Extraction with Zod Schema**: Define exact data structure using Zod schemas
+- **Structured Extraction with Zod Schema**: Define exact data structure
 - **Prompt-based Extraction**: Extract information using custom prompts
-- **Validation and Retries**: Automatic validation against schema with retry logic
-
-## Key Features
-
-- **LLM Structured Output Support**: When available, uses the LLM's native structured output capabilities for guaranteed schema compliance
-- **Fallback JSON Parsing**: Automatically falls back to JSON parsing with validation when structured output is unavailable
-- **Schema Validation**: Built-in Zod validation ensures extracted data matches expected structure
-- **Retry Logic**: Configurable retry attempts with error feedback for improved accuracy
-- **Strict and Non-strict Modes**: Choose between validated extraction (strict) or flexible extraction
-
-## Library Tool Integration
+- **Validation and Retries**: Automatic validation with configurable retry logic
+- **Structured Output Support**: Uses LLM native structured output when available
 
-The extraction functionality is available as a library tool called `minded-extraction` that can be added to your flows through the Minded platform.
-
-### Configuration Options
-
-- `content`: The text to extract information from
-- `schema`: Optional Zod-compatible schema defining the structure
-- `systemPrompt`: Custom instructions for extraction
-- `examples`: Input/output examples to guide extraction
-- `strictMode`: Enable/disable schema validation (default: true)
-- `maxRetries`: Number of retry attempts on validation failure (default: 3)
-- `defaultValue`: Fallback value if extraction fails
-
-## How It Works
+## Using in Flows
 
-1. **With Structured Output Support** (when available):
-
-   - The tool uses the LLM's `withStructuredOutput` method for direct schema-compliant extraction
-   - No manual JSON parsing or validation needed
-   - Guaranteed to match the provided Zod schema
-
-2. **Fallback Mode** (JSON parsing):
+```yaml
+- id: extractCustomerInfo
+  type: tool
+  toolName: minded-extraction
+  prompt: Extract customer name, email, and phone number from the message
+```
 
-   - Generates a prompt with schema description
-   - Uses JSON output parser to extract structured data
-   - Validates against Zod schema
-   - Retries with error feedback if validation fails
+### Tool Parameters
+
+| Parameter    | Type    | Description                            | Required |
+| ------------ | ------- | -------------------------------------- | -------- |
+| content      | string  | Text to extract from                   | Yes      |
+| schema       | object  | Zod-compatible schema                  | No       |
+| systemPrompt | string  | Custom instructions                    | No       |
+| examples     | array   | Input/output examples                  | No       |
+| strictMode   | boolean | Enable validation (default: true)      | No       |
+| maxRetries   | number  | Retry attempts on failure (default: 3) | No       |
+| defaultValue | any     | Fallback value                         | No       |
+
+### Overriding Parameters in Flows
+
+```yaml
+- name: 'Extract Customer Info'
+  type: 'tool'
+  toolName: 'minded-extraction'
+  parameters:
+    content: '{state.memory.rawText}'
+    schema:
+      name:
+        type: 'string'
+        description: 'Customer full name'
+      email:
+        type: 'string'
+        description: 'Email address'
+        required: false
+      phone:
+        type: 'string'
+    systemPrompt: 'Extract contact information from the text'
+    strictMode: true
+    maxRetries: 3
+```
 
-3. **Non-strict Mode**:
-   - Skips validation for more flexible extraction
-   - Useful when schema compliance is not critical
+**Available schema field properties:**
 
-## Standalone Usage
+- `type`: `'string'`, `'number'`, `'boolean'`, `'array'`, or `'object'`
+- `description`: Optional field description
+- `required`: Optional boolean (defaults to true)
 
-The extraction utility can also be used programmatically:
+## Programmatic Usage
 
 ```typescript
 import { extract, createExtractor } from '@minded-ai/mindedjs';
@@ -76,3 +82,9 @@ const result = await extract(
 const extractor = createExtractor(schema, { systemPrompt: 'Extract data' });
 const result = await extractor(content, agent.llm);
 ```
+
+## How It Works
+
+1. **With Structured Output Support**: Uses LLM's `withStructuredOutput` for direct schema-compliant extraction
+2. **Fallback Mode**: Generates prompt with schema description, parses JSON, validates against Zod schema, retries with error feedback
+3. **Non-strict Mode**: Skips validation for flexible extraction

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "2.0.36",
+  "version": "2.0.38",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,4 +72,4 @@
   "peerDependencies": {
     "playwright": "^1.55.0"
   }
-}
+}

package/src/agent.ts

@@ -488,7 +488,8 @@ export class Agent {
     try {
       await this.waitForInitialization();
     } catch (err) {
-      logger.error({ msg: '[Trigger] Agent initialization failed', err });
+      const { baseUrl } = getConfig();
+      logger.error({ msg: '[Trigger] Agent initialization failed', err, sessionId, baseUrl });
       throw err;
     }
 

package/src/index.ts

@@ -85,7 +85,7 @@ export {
   TriggerEvent,
 } from './types/Agent.types';
 export type { AgentInvokeParams, MindedSDKConfig } from './types/Agent.types';
-export type { Environment } from './types/Platform.types';
+export { Environment } from './types/Platform.types';
 export type { State } from './types/LangGraph.types';
 export { zendesk } from './interfaces/zendesk';
 

package/src/nodes/addToolNode.ts

@@ -13,6 +13,7 @@ import { combinePlaybooks } from '../playbooks/playbooks';
 import { compilePrompt } from './compilePrompt';
 import { AnalyticsEventName } from '../types/Analytics.types';
 import { trackAnalyticsEvent } from '../internalTools/analytics';
+import { z } from 'zod';
 
 export const addToolNode = async ({
   graph,
@@ -49,38 +50,144 @@ export const addToolNode = async ({
     await agent.interruptSessionManager.checkQueueAndInterrupt(state.sessionId);
     logger.debug({ msg: `[Node] Executing tool node`, node: toolNode.displayName });
 
-    const tool = langchainTool(() => { }, {
-      name: matchedTool.name,
-      description: matchedTool.description,
-      schema: matchedTool.input,
-    });
+    // Compile parameters with variable injection support
+    const compiledParameters: Record<string, any> = {};
+    const compileContext = { state, memory: state.memory, env: process.env };
+
+    for (const [key, value] of Object.entries(node.parameters || {})) {
+      if (value !== '') {
+        // If the value is a string, compile it to allow variable injection
+        if (typeof value === 'string') {
+          compiledParameters[key] = compilePrompt(value, compileContext);
+        } else {
+          compiledParameters[key] = value;
+        }
+      }
+    }
+
+    // Create a filtered schema for the LLM (exclude overridden parameters)
+    let schemaForLLM = matchedTool.input;
+    const overriddenKeys = Object.keys(compiledParameters);
+    let skipLLMCall = false;
 
-    const combinedPlaybooks = combinePlaybooks(agent.playbooks);
-    const toolPrompt = node.prompt;
+    if (overriddenKeys.length > 0) {
+      try {
+        // Only filter if it's a ZodObject
+        if (matchedTool.input instanceof z.ZodObject) {
+          // Create omit map: { key1: true, key2: true, ... }
+          const omitMap = overriddenKeys.reduce((acc, key) => {
+            acc[key] = true;
+            return acc;
+          }, {} as Record<string, true>);
 
-    let finalMessage = toolPrompt;
-    if (combinedPlaybooks) {
-      if (toolPrompt) {
-        finalMessage = combinedPlaybooks + '\n\n' + toolPrompt;
-      } else {
-        finalMessage = combinedPlaybooks;
+          schemaForLLM = matchedTool.input.omit(omitMap);
+
+          // Check if all parameters are overridden
+          const remainingKeys = Object.keys(schemaForLLM.shape);
+          skipLLMCall = remainingKeys.length === 0;
+        }
+      } catch (err) {
+        logger.warn({
+          msg: '[Tool] Failed to filter schema, using original',
+          tool: matchedTool.name,
+          err,
+        });
+        // Fall back to original schema on error
       }
     }
-    if (finalMessage) {
-      const compiledPrompt = compilePrompt(finalMessage, { state: state, memory: state.memory, env: process.env });
-      const systemMessage = new SystemMessage(compiledPrompt);
-      if (state.messages.length === 0 || state.messages[0].getType() === 'system') {
-        state.messages[0] = systemMessage;
-      } else {
-        state.messages.unshift(systemMessage);
+
+    let AIToolCallMessage: AIMessage;
+
+    if (skipLLMCall) {
+      // All parameters are overridden - create synthetic tool call without LLM
+      AIToolCallMessage = new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            name: matchedTool.name,
+            args: compiledParameters,
+            id: `call_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+          },
+        ],
+      });
+    } else {
+      // Need LLM to infer remaining parameters
+      const tool = langchainTool(() => {}, {
+        name: matchedTool.name,
+        description: matchedTool.description,
+        schema: schemaForLLM, // Use filtered schema
+      });
+
+      const combinedPlaybooks = combinePlaybooks(agent.playbooks) || '';
+      const compiledNodePrompt = node.prompt ? compilePrompt(node.prompt, compileContext) : null;
+      const hasOverriddenParameters = overriddenKeys.length > 0;
+
+      // Only build system message if there's actual content (playbooks, prompt, or overridden parameters)
+      if (combinedPlaybooks || compiledNodePrompt || hasOverriddenParameters) {
+        // Check if any compiled parameter is too long (>1000 characters)
+        const hasLongParameters = Object.values(compiledParameters).some((value) => typeof value === 'string' && value.length > 1000);
+
+        // Prepare parameters string for the system message
+        let parametersString: string;
+        if (hasOverriddenParameters) {
+          if (hasLongParameters) {
+            logger.debug({
+              msg: '[Tool] Omitting parameters from system prompt due to length',
+              tool: matchedTool.name,
+              parameterLengths: Object.entries(compiledParameters).reduce((acc, [key, value]) => {
+                if (typeof value === 'string') {
+                  acc[key] = value.length;
+                }
+                return acc;
+              }, {} as Record<string, number>),
+            });
+            parametersString = '[Parameters omitted - one or more values exceed 1000 characters]';
+          } else {
+            parametersString = JSON.stringify(compiledParameters);
+          }
+        } else {
+          parametersString = '{}';
+        }
+
+        // Build system message with overridden parameters info
+        const message = `${combinedPlaybooks ? combinedPlaybooks + '\n\n' : ''}
+    Additional context:
+    previous messages are available for context.
+    Your goal is execute the tool with the correct parameters, some of them already chosen by the user and the rest should be generated.
+    You have 4 things to base your parameters on:
+    - Previous messages
+    - Parameters manually configured by the user (if any)
+    - User instructions for choosing tool parameters that are not set by the user (if any)
+    - Workflow memory
+    Parameters manually configured by the user are:
+    ${parametersString}
+    User instructions for choosing tool parameters are:
+        ${compiledNodePrompt ? compiledNodePrompt : 'no instructions set by the user'}`;
+
+        const compiledPrompt = compilePrompt(message, { state: state, memory: state.memory, env: process.env });
+        const systemMessage = new SystemMessage(compiledPrompt);
+        if (state.messages.length === 0 || state.messages[0].getType() === 'system') {
+          state.messages[0] = systemMessage;
+        } else {
+          state.messages.unshift(systemMessage);
+        }
+      }
+
+      const startTime = Date.now();
+      AIToolCallMessage = await llm.bindTools([tool], { tool_choice: tool.name }).invoke(state.messages);
+      const endTime = Date.now();
+      logger.debug({ msg: '[Tool] Model execution time', tool: matchedTool.name, executionTimeMs: endTime - startTime });
+      await agent.interruptSessionManager.checkQueueAndInterrupt(state.sessionId);
+
+      // Merge AI-generated parameters with user-set parameters
+      if (AIToolCallMessage.tool_calls && AIToolCallMessage.tool_calls.length > 0) {
+        AIToolCallMessage.tool_calls[0].args = {
+          ...AIToolCallMessage.tool_calls[0].args,
+          ...compiledParameters, // User-set parameters have priority over AI-generated parameters
+        };
       }
     }
 
-    const startTime = Date.now();
-    const AIToolCallMessage: AIMessage = await llm.bindTools([tool], { tool_choice: tool.name }).invoke(state.messages);
-    const endTime = Date.now();
-    logger.debug({ msg: '[Tool] Model execution time', tool: matchedTool.name, executionTimeMs: endTime - startTime });
-    await agent.interruptSessionManager.checkQueueAndInterrupt(state.sessionId);
     state.goto = null;
 
     if (!AIToolCallMessage.additional_kwargs) {

package/src/nodes/addToolRunNode.ts

@@ -3,7 +3,6 @@ import { RunnableLike } from '@langchain/core/runnables';
 import { Tool } from '../types/Tools.types';
 import { LLMProviders } from '../types/LLM.types';
 import { internalNodesSuffix, NodeType, ToolNode } from '../types/Flows.types';
-import { tool as langchainTool } from '@langchain/core/tools';
 import { z } from 'zod';
 import { Agent } from '../agent';
 import { logger } from '../utils/logger';
@@ -57,7 +56,7 @@ export const addToolRunNode = async ({ graph, tools, toolNode, attachedToNodeNam
               });
 
               return toolResult;
-            }
+            },
           );
 
           const endTime = Date.now();
@@ -76,17 +75,25 @@ export const addToolRunNode = async ({ graph, tools, toolNode, attachedToNodeNam
         throw err;
       }
     };
-    const tool = langchainTool(executeWrapper, {
-      name: matchedTool.name,
-      description: matchedTool.description,
-      schema: matchedTool.input,
-    });
 
     const toolCallObj = state.messages[state.messages.length - 1] as any;
     if (!toolCallObj.tool_calls) {
       throw new Error('Tool call not found');
     }
-    const toolCallMessage = await tool.invoke(toolCallObj.tool_calls[0]);
+
+    // Parse and validate args using the tool's schema
+    const toolCall = toolCallObj.tool_calls[0];
+    const parsedArgs = matchedTool.input.parse(toolCall.args);
+
+    // Execute the tool with validated args
+    const result = await executeWrapper(parsedArgs);
+
+    // Create a ToolMessage with the result
+    const toolCallMessage = new ToolMessage({
+      content: typeof result === 'string' ? result : JSON.stringify(result),
+      tool_call_id: toolCall.id,
+      name: matchedTool.name,
+    });
 
     // Add the tool message to the state
     state.messages.push(toolCallMessage);

package/src/types/Flows.types.ts

@@ -195,6 +195,7 @@ export interface ToolNode extends BaseNode {
   toolName: string;
   prompt: string;
   appImgSrc?: string;
+  parameters?: Record<string, any>;
 }
 
 export interface AppToolNode extends BaseNode, BaseAppNode {