@minded-ai/mindedjs 1.0.29 → 1.0.31

package/docs/core-concepts/tools.md

@@ -1,225 +0,0 @@
-# Tools
-
-Tools are reusable functions that agents can call to perform specific actions like processing payments, sending emails, or updating databases.
-
-## Tool Structure
-
-Every tool must implement the `Tool` interface:
-
-```ts
-interface Tool<Input extends z.ZodSchema, Memory> {
-  name: string;           // Unique tool identifier
-  description: string;    // What the tool does (used by LLM)
-  input: Input;          // Zod schema for input validation
-  isGlobal?: boolean;    // Optional: available across all LLM calls
-  execute: ({ input, memory }) => Promise<{ memory?, result? }>;
-}
-```
-
-## Execute Function Signature
-
-The `execute` function is the core of every tool. It receives validated input from the LLM and current memory state, then returns updated memory and/or result tool result which will be added to the message history and be available for future LLM calls.
-
-### Parameters
-
-```ts
-execute: ({ input, memory }) => Promise<{ memory?, result? }>
-```
-
-- **`input`**: Validated data matching your Zod schema - contains the parameters the LLM extracted from the conversation
-- **`memory`**: Current conversation memory state - contains all the context and data accumulated during the flow
-
-### Return Value
-
-The execute function returns a Promise with an object containing:
-
-- **`memory?`** (optional): Updated memory state that will be merged with existing memory
-- **`result?`** (optional): Result that gets sent back to the LLM as the tool's response
-
-## Basic Tool Example
-
-Here's a simple refund processing tool:
-
-```ts
-import { z } from 'zod';
-import { Tool } from 'mindedjs/src/types/Tools.types';
-import memorySchema from '../schema';
-
-type Memory = z.infer<typeof memorySchema>;
-
-const schema = z.object({
-  orderId: z.string(),
-  customerName: z.string(),
-});
-
-const refundOrderTool: Tool<typeof schema, Memory> = {
-  name: 'refundOrder',
-  description: 'Process a customer refund for their order',
-  input: schema,
-  execute: async ({ input, memory }) => {
-    // Your business logic here
-    console.log(`Processing refund for order ${input.orderId}`);
-    
-    // Call external API, update database, etc.
-    const refundAmount = await processRefundInSystem(input.orderId);
-    
-    return {
-      memory: {
-        orderId: input.orderId,
-        customerName: input.customerName,
-        issue: `Refund processed: $${refundAmount}`,
-      },
-    };
-  },
-};
-
-export default refundOrderTool;
-```
-
-## Tool Registration
-
-### Global Tools
-
-Mark tools as global if you want them to be available in all LLM calls.
-
-```ts
-const auditLogTool: Tool<typeof auditSchema, Memory> = {
-  name: 'auditLog',
-  description: 'Log user action for compliance',
-  isGlobal: true, // Available in all flows
-  input: z.object({
-    action: z.string(),
-    details: z.string(),
-  }),
-  execute: async ({ input, memory }) => {
-    await auditService.log({
-      userId: memory.userId,
-      action: input.action,
-      details: input.details,
-      timestamp: new Date(),
-    });
-  },
-};
-```
-
-## Memory Management
-
-Tools can read and update memory state:
-
-```ts
-const updateProfileTool: Tool<typeof profileSchema, Memory> = {
-  name: 'updateProfile',
-  description: 'Update customer profile information',
-  input: z.object({
-    field: z.string(),
-    value: z.string(),
-  }),
-  execute: async ({ input, memory }) => {
-    // Read current memory
-    console.log(`Current customer: ${memory.customerName}`);
-    
-    // Update external system
-    await profileService.update(memory.customerId, {
-      [input.field]: input.value
-    });
-    
-    // Return updated memory
-    return {
-      memory: {
-        ...memory,
-        [`${input.field}Updated`]: true,
-      },
-    };
-  },
-};
-```
-
-## Error Handling
-
-Handle errors gracefully in tools:
-
-```ts
-const paymentTool: Tool<typeof paymentSchema, Memory> = {
-  name: 'processPayment',
-  description: 'Process customer payment',
-  input: z.object({
-    amount: z.number(),
-    cardToken: z.string(),
-  }),
-  execute: async ({ input, memory }) => {
-    try {
-      const result = await paymentService.charge({
-        amount: input.amount,
-        cardToken: input.cardToken,
-        customerId: memory.customerId,
-      });
-      
-      return {
-        result: `Payment successful: ${result.transactionId}`,
-        memory: { lastPaymentId: result.transactionId },
-      };
-    } catch (error) {
-      console.error('Payment failed:', error);
-      return {
-        result: 'Payment failed. Please try again or contact support.',
-        memory: { paymentError: error.message },
-      };
-    }
-  },
-};
-```
-
-## Best Practices
-
-1. **Clear Descriptions**: Write descriptions that help the LLM understand when to use the tool
-2. **Input Validation**: Use Zod schemas to validate all inputs
-3. **Memory Updates**: Update memory with relevant information for future tool calls
-4. **Error Handling**: Always handle errors gracefully and provide meaningful messages
-5. **Async Operations**: Use async/await for external API calls and database operations
-6. **Logging**: Log important actions for debugging and auditing
-
-## Tool Nodes
-
-Tool nodes force execution of specific tools at defined points in your flow, bypassing LLM decision-making.
-
-### Configuration
-
-```yaml
-nodes:
-  - name: 'Force Refund Processing'
-    type: 'tool'
-    toolName: 'refundOrder'
-```
-
-### Tool Node vs Automatic Tool Calls
-
-| Feature       | Tool Nodes                      | Automatic Tool Calls                |
-| ------------- | ------------------------------- | ----------------------------------- |
-| **Execution** | Guaranteed when node is reached | Only when LLM decides to call       |
-| **Control**   | Explicit flow control           | LLM-driven decision                 |
-| **Use Case**  | Required business logic steps   | Flexible, context-dependent actions |
-
-### Example
-
-```yaml
-nodes:
-  - name: 'Customer Support Start'
-    type: 'prompt'
-    prompt: 'How can I help you today?'
-  - name: 'Log Interaction'
-    type: 'tool'
-    toolName: 'auditLog'
-
-edges:
-  - source: 'Customer Support Start'
-    target: 'Log Interaction'
-    type: 'always'
-```
-
-### Best Practices
-
-1. **Strategic Placement**: Use for critical business logic that must always execute
-2. **Clear Context**: Ensure conversation provides context for parameter extraction
-3. **Error Handling**: Handle errors gracefully since they bypass LLM error recovery
-
-Tool parameters are automatically extracted from conversation context and memory state using an internal LLM agent.

package/docs/core-concepts/triggers.md

@@ -1,87 +0,0 @@
-# Triggers
-
-Triggers are the entry points into your agent's flows. They serve as the initial contact point between external systems and your agent, handling incoming events and initializing conversations with appropriate context and memory.
-
-## Trigger Types
-
-Currently, MindedJS supports a single type of trigger:
-
-- **App Triggers**: Triggered by specific applications (e.g., Slack, Zendesk)
-  - Each app trigger is identified by a unique `appTriggerId`
-  - Triggers can be customized to handle app-specific data formats
-  - Supports automatic message conversion for certain apps (e.g., Slack messages)
-
-### Trigger Invocation History
-
-When a trigger is invoked, it creates a comprehensive record of the event that is:
-
-1. Added to the flow history for tracking and debugging
-2. Passed to subsequent tool calls via the `triggerInvocations` parameter
-3. Preserved throughout the flow's execution
-
-This history allows tools to:
-
-- Access the original trigger context
-- Make decisions based on the triggering event
-- Maintain conversation continuity
-- Debug flow execution
-
-Example:
-
-```typescript
-const tool: Tool = {
-  name: 'myTool',
-  execute: async ({ input, triggerInvocations }) => {
-    // Access trigger information
-    const trigger = triggerInvocations[0];
-    console.log(`Triggered by ${trigger.appName}: ${trigger.triggerName}`);
-  },
-};
-```
-
-### Default Message Behavior
-
-MindedJS provides intelligent message handling for different trigger types through the `triggerTypeToDefaultMessage` mapping. This system:
-
-- Automatically converts trigger data into appropriate message formats
-- Maintains conversation context without manual intervention
-- Supports different message types for different applications
-
-Currently supported default messages:
-
-- **Slack**: For "New Direct Message (Instant)" triggers, the message text is automatically converted to a human message
-
-Example:
-
-```typescript
-// Slack trigger will automatically add a human message
-const slackResult = await agent.invoke({
-  triggerName: 'New Direct Message (Instant)',
-  triggerBody: { text: 'Hello from Slack' },
-  appName: 'Slack',
-});
-
-// Other triggers won't add any messages by default
-const otherResult = await agent.invoke({
-  triggerName: 'SomeOtherTrigger',
-  triggerBody: { text: 'Hello' },
-  appName: 'OtherApp',
-});
-```
-
-### Validate Trigger Input
-
-```typescript
-// ✅ Good - Input validation
-agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
-  if (!triggerBody.customerId || !triggerBody.message) {
-    return false; // Disqualify invalid triggers
-  }
-  // Process valid trigger
-});
-
-// ❌ Avoid - No validation
-agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerBody }) => {
-  // Process without validation
-});
-```