@minded-ai/mindedjs 1.0.90 → 1.0.91-beta-1

package/docs/low-code-editor/nodes.md

@@ -0,0 +1,331 @@
+# Nodes
+
+Nodes are the building blocks of MindedJS flows - discrete processing units that handle different aspects of your agent's workflow.
+
+## Node Types Overview
+
+| Node Type                               | Purpose        | Description                              |
+| --------------------------------------- | -------------- | ---------------------------------------- |
+| [**Trigger**](nodes.md#trigger-nodes)   | Entry Points   | Start flows from various sources         |
+| [**Prompt**](nodes.md#prompt-nodes)     | LLM Processing | Generate responses using language models |
+| [**Tool**](nodes.md#tool-nodes)         | Actions        | Execute external functions and APIs      |
+| [**Junction**](nodes.md#junction-nodes) | Flow Control   | Route and organize flow logic            |
+| [**Jump To**](nodes.md#jump-to-nodes)   | Flow Control   | Jump to specific nodes or subflows       |
+
+## Trigger Nodes
+
+Trigger nodes are entry points that start your flows and initialize them with memory and messages.
+
+### Trigger Types
+
+#### Manual Trigger
+
+```yaml
+- type: trigger
+  triggerType: manual
+  name: Customer Support Request
+```
+
+#### App Trigger
+
+```yaml
+- type: trigger
+  triggerType: app
+  name: Zendesk Ticket Created
+  appTriggerId: zendesk-new-ticket
+```
+
+#### Webhook Trigger
+
+```yaml
+- type: trigger
+  triggerType: webhook
+  name: Payment Failed Notification
+```
+
+### Trigger Implementation
+
+```ts
+import { events } from 'mindedjs/src/index';
+import { HumanMessage } from '@langchain/core/messages';
+
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (triggerName === 'Customer Support Request') {
+    return {
+      memory: {
+        customerQuery: triggerBody,
+        timestamp: new Date().toISOString(),
+      },
+      messages: [new HumanMessage(triggerBody)],
+    };
+  }
+});
+```
+
+#### Disqualifying Triggers
+
+Return an object with `isQualified: false` to prevent flow execution:
+
+```ts
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  // Only process during business hours
+  const hour = new Date().getHours();
+  if (hour < 9 || hour > 17) {
+    return { isQualified: false };
+  }
+
+  return {
+    isQualified: true,
+    memory: { businessHours: true },
+    messages: [new HumanMessage(triggerBody)],
+  };
+});
+```
+
+## Prompt Nodes
+
+Prompt nodes process input through LLM to generate intelligent responses or invoke tools.
+
+**Optional Properties:**
+
+* `humanInTheLoop?: boolean` - When `true`, pauses execution after this node for human input before continuing
+* `canStayOnNode?: boolean` - When `true`, allows the node to route back to itself for iterative processing. Usually combined with `humanInTheLoop: true` to allow for iteration over human input.
+
+**Example Usage:**
+
+```yaml
+- type: promptNode
+  name: Content Reviewer
+  prompt: 'Ask user to review the content and approve or request changes.'
+  humanInTheLoop: true # Pause for human approval before proceeding
+
+- type: promptNode
+  name: Research Assistant
+  prompt: 'Request user for more information until you have gathered all necessary information.'
+  canStayOnNode: true # Allow iterative research until complete
+  humanInTheLoop: true # Pause for human approval before proceeding
+```
+
+### Basic Configuration
+
+```yaml
+- type: promptNode
+  name: Customer Service Agent
+  prompt: |
+    You are a helpful customer service representative.
+    Respond to customer inquiries professionally.
+
+    Customer: {{memory.customerName}}
+    Issue: {{memory.issueCategory}}
+  llmConfig:
+    name: ChatOpenAI
+    properties:
+      model: gpt-4o
+      temperature: 0.7
+      max_tokens: 500
+```
+
+### LLM Configuration Options
+
+```yaml
+# OpenAI
+llmConfig:
+  name: ChatOpenAI
+  properties:
+    model: gpt-4o        # or gpt-4o-mini, gpt-3.5-turbo
+    temperature: 0.7     # 0.0 (deterministic) to 1.0 (creative)
+    max_tokens: 500
+
+# Anthropic Claude
+llmConfig:
+  name: ChatAnthropic
+  properties:
+    model: claude-3-sonnet-20240229
+    temperature: 0.5
+    max_tokens: 1000
+```
+
+## Tool Nodes
+
+Tool nodes execute functions to perform actions like API calls or database queries.
+
+### Basic Tool Node
+
+```yaml
+- type: tool
+  name: Lookup Customer Order
+  toolName: lookupOrder
+```
+
+### Tool Implementation
+
+```ts
+import { z } from 'zod';
+import { Tool } from 'mindedjs/src/types/Tools.types';
+
+const schema = z.object({
+  orderId: z.string(),
+  customerEmail: z.string().optional(),
+});
+
+const lookupOrderTool: Tool<typeof schema, Memory> = {
+  name: 'lookupOrder',
+  description: 'Look up order details by order ID',
+  input: schema,
+  execute: async ({ input, memory }) => {
+    const order = await fetchOrderById(input.orderId);
+
+    if (!order) {
+      throw new Error(`Order ${input.orderId} not found`);
+    }
+
+    return {
+      memory: {
+        orderInfo: order,
+        orderStatus: order.status,
+      },
+      result: `Found order ${order.id} - Status: ${order.status}`,
+    };
+  },
+};
+
+export default lookupOrderTool;
+```
+
+## Junction Nodes
+
+Junction nodes provide flow control without processing, useful for organizing routing logic.
+
+### Basic Junction
+
+```yaml
+- type: junction
+  name: Customer Routing Hub
+```
+
+### Routing Example
+
+```yaml
+nodes:
+  - type: junction
+    name: Route Customer Request
+  - type: promptNode
+    name: VIP Support
+  - type: promptNode
+    name: Standard Support
+
+edges:
+  - source: Route Customer Request
+    target: VIP Support
+    type: logicalCondition
+    condition: "({ memory }) => memory.customerTier === 'premium'"
+
+  - source: Route Customer Request
+    target: Standard Support
+    type: logicalCondition
+    condition: "({ memory }) => memory.customerTier === 'standard'"
+```
+
+## Jump To Nodes
+
+Jump To nodes provide direct navigation to specific nodes, enabling flow transitions and subflow execution.
+
+### Basic Jump To Node
+
+```yaml
+- type: jumpToNode
+  name: Go To Order Processing
+  targetNodeId: Process Customer Order
+```
+
+### Subflow Navigation
+
+Jump To nodes are particularly useful for organizing complex workflows into multiple flows:
+
+```yaml
+# Main flow
+- type: jumpToNode
+  name: Jump To Refund Subflow
+  targetNodeId: Refund Processing Trigger
+
+# In refund subflow
+- type: trigger
+  name: Refund Processing Trigger
+  triggerType: manual
+```
+
+### Multi-Flow Example
+
+```yaml
+# flows/mainFlow.yaml
+nodes:
+  - type: trigger
+    name: Customer Request
+    triggerType: manual
+  
+  - type: promptNode
+    name: Classify Request
+    prompt: |
+      Classify the customer request as either 'refund' or 'support'.
+      Customer message: {{messages.last.content}}
+  
+  - type: jumpToNode
+    name: Go To Refund Flow
+    targetNodeId: Refund Processor
+
+# flows/refundFlow.yaml  
+nodes:
+  - type: trigger
+    name: Refund Processor
+    triggerType: manual
+    
+  - type: tool
+    name: Process Refund
+    toolName: processRefund
+```
+
+### Implementation Notes
+
+- **Direct Navigation**: Jump To nodes create direct edges to their target nodes
+- **Cross-Flow Support**: Target nodes can exist in different flow files
+- **State Preservation**: Current memory and message state is maintained during jumps
+- **No Processing**: Jump To nodes perform no data processing, only navigation
+
+## Best Practices
+
+### Use Descriptive Names
+
+```yaml
+# ✅ Good
+- type: promptNode
+  name: Technical Support Specialist
+
+# ❌ Avoid
+- type: promptNode
+  name: Agent 1
+```
+
+### Keep Prompts Focused
+
+```yaml
+# ✅ Good - Specific role and context
+- type: promptNode
+  name: Order Refund Processor
+  prompt: |
+    You process customer refund requests for e-commerce orders.
+    Order ID: {{memory.orderId}}
+    Determine if refund should be approved based on order status and timing.
+
+# ❌ Avoid - Too broad
+- type: promptNode
+  name: General Assistant
+  prompt: 'Help the customer with anything they need'
+```
+
+## Next Steps
+
+* [**Edges**](edges.md) - Connect nodes with intelligent routing
+* [**Tools**](tools.md) - Build powerful tool functions
+* [**Memory Types**](../platform/memory.md) - Design effective state management
+
+Nodes are your building blocks - combine them strategically to create powerful AI workflows! 🔧

package/docs/low-code-editor/playbooks.md

@@ -0,0 +1,262 @@
+# Playbooks
+
+Playbooks are reusable instructions that are automatically included in all prompt and tool nodes of your agent. They help maintain consistency and reduce repetition across your agent's behavior.
+
+## Overview
+
+Playbooks are defined using EditorJS blocks format and support:
+
+- **[EditorJS blocks](https://editorjs.io/)** for rich content structure
+- **EJS templating** for dynamic content
+- **Placeholders** for runtime values
+- **Multiple files** for better organization
+- **Platform integration** for web-based editing
+
+## Configuration
+
+Add the playbooks directory to your `minded.json`:
+
+```json
+{
+  "playbooks": ["./src/playbooks"]
+}
+```
+
+## Creating Playbooks
+
+Create YAML files in your playbooks directory using the EditorJS blocks structure:
+
+```yaml
+# src/playbooks/general.yaml
+id: general-playbooks
+name: General Customer Service
+blocks:
+  - type: header
+    data:
+      text: Customer Service Guidelines
+      level: 2
+  - type: paragraph
+    data:
+      text: "You are a helpful customer service agent for {companyName}."
+  - type: paragraph
+    data:
+      text: "Always be polite and professional in your responses."
+  - type: paragraph
+    data:
+      text: "Current time: <%= new Date().toISOString() %>"
+  - type: paragraph
+    data:
+      text: "User location: {userLocation}"
+```
+
+## Block Types
+
+Playbooks support various EditorJS block types:
+
+### Header Block
+```yaml
+- type: header
+  data:
+    text: "Section Title"
+    level: 2  # 1-6 for h1-h6
+```
+
+### Paragraph Block
+```yaml
+- type: paragraph
+  data:
+    text: "Your paragraph content here"
+```
+
+### List Block
+```yaml
+- type: list
+  data:
+    style: unordered  # or "ordered"
+    items:
+      - "First item"
+      - "Second item"
+      - "Third item"
+```
+
+### Quote Block
+```yaml
+- type: quote
+  data:
+    text: "Important note or quote"
+    caption: "Optional caption"
+```
+
+### Code Block
+```yaml
+- type: code
+  data:
+    code: |
+      function example() {
+        return "code example";
+      }
+```
+
+### Delimiter Block
+```yaml
+- type: delimiter
+  data: {}
+```
+
+## Using Templates
+
+### EJS Templates
+
+Use EJS syntax (`<%= %>`) for dynamic content evaluated at compile time:
+
+```yaml
+- type: paragraph
+  data:
+    text: "Today is <%= new Date().toDateString() %>"
+- type: paragraph
+  data:
+    text: "Environment: <%= process.env.NODE_ENV %>"
+```
+
+### Placeholders
+
+Use placeholders (`{state.memory.key}`) for values from the agent's memory state:
+
+```yaml
+- type: paragraph
+  data:
+    text: "Hello {state.memory.customerName},"
+- type: paragraph
+  data:
+    text: "Your order {state.memory.orderId} is being processed."
+```
+
+These placeholders are automatically replaced with values from `state.memory` when the playbooks are compiled.
+
+## Using Memory Values in Playbooks
+
+Placeholders in playbooks are replaced with values from the agent's memory state:
+
+```typescript
+const updateCustomerTool: Tool<typeof inputSchema, any> = {
+  name: 'updateCustomer',
+  description: 'Update customer information',
+  input: inputSchema,
+  isGlobal: true,
+  execute: async ({ input, state }) => {
+    return {
+      memory: {
+        ...state.memory,
+        customer: input,
+        customerName: input.name,
+        userLocation: input.location,
+      },
+    };
+  },
+};
+```
+
+## Nested Values
+
+Placeholders support nested object access from the memory state:
+
+```yaml
+- type: paragraph
+  data:
+    text: "Customer: {state.memory.customer.name}"
+- type: paragraph
+  data:
+    text: "Email: {state.memory.customer.email}"
+- type: paragraph
+  data:
+    text: "Order status: {state.memory.order.status}"
+```
+
+These values are resolved from nested properties in `state.memory`, for example: `state.state.memory.customer.name`.
+
+## Complete Example
+
+```yaml
+# src/playbooks/customer-service.yaml
+id: customer-service-guidelines
+name: Customer Service Guidelines
+blocks:
+  - type: header
+    data:
+      text: Customer Service Best Practices
+      level: 1
+  - type: paragraph
+    data:
+      text: "You are representing {companyName} as a professional customer service agent."
+  - type: list
+    data:
+      style: unordered
+      items:
+        - "Always greet customers warmly"
+        - "Listen actively to their concerns" 
+        - "Provide clear and helpful solutions"
+        - "Follow up to ensure satisfaction"
+  - type: quote
+    data:
+      text: "The customer's experience is our top priority"
+      caption: "Company motto"
+  - type: paragraph
+    data:
+      text: "Current session started: <%= new Date().toISOString() %>"
+```
+
+## Best Practices
+
+1. **Organize by purpose**: Create separate files for different aspects (general, domain-specific, compliance, etc.)
+2. **Use meaningful IDs**: Each playbook must have a unique ID
+3. **Structure content logically**: Use headers, lists, and quotes to organize information
+4. **Keep blocks focused**: Each block should contain a single concept or instruction
+5. **Document placeholders**: Comment which parameters your playbooks expect
+6. **Test thoroughly**: Verify that all placeholders are being populated correctly
+
+## Example Structure
+
+```
+src/playbooks/
+├── general.yaml          # General behavior guidelines
+├── compliance.yaml       # Regulatory compliance rules
+├── brand-voice.yaml      # Brand-specific communication style
+└── domain-specific.yaml  # Domain-specific instructions
+```
+
+## Platform Integration
+
+When using the Minded platform:
+
+1. Playbooks are editable through the web interface using a rich text editor
+2. Changes are synchronized with your Git repository
+3. The platform uses the same EditorJS blocks format
+4. Local YAML files are automatically converted to the blocks format
+5. All templating features work the same in both local and platform environments
+
+## Migration from Content Format
+
+If you have existing playbooks using the old `content` format, convert them to blocks:
+
+**Old format:**
+```yaml
+content: |
+  # Customer Service
+  Always be polite and professional.
+  Current time: <%= new Date().toISOString() %>
+```
+
+**New format:**
+```yaml
+blocks:
+  - type: header
+    data:
+      text: Customer Service
+      level: 1
+  - type: paragraph
+    data:
+      text: Always be polite and professional.
+  - type: paragraph
+    data:
+      text: "Current time: <%= new Date().toISOString() %>"
+```