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

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

@@ -0,0 +1,392 @@
+# Edges
+
+Edges are the **routing logic** that connects nodes in your MindedJS flows. They determine how your agent moves through the workflow, making intelligent decisions about which path to take based on different conditions and contexts.
+
+## What are Edges?
+
+Edges define the **transitions between nodes** in your flow. Each edge specifies:
+
+- **Source** - The starting node
+- **Target** - The destination node
+- **Type** - The routing logic type
+- **Condition** - The criteria for taking this path
+- **Prompt** - The prompt for the LLM to make a decision
+
+```yaml
+edges:
+  - source: Customer Support Request
+    target: Classify Issue
+    type: stepForward
+
+  - source: Classify Issue
+    target: Technical Support
+    type: promptCondition
+    prompt: 'Is this a technical issue requiring troubleshooting?'
+
+  - source: Classify Issue
+    target: Billing Support
+    type: logicalCondition
+    condition: "state.memory.issueCategory === 'billing'"
+```
+
+## Edge Types
+
+MindedJS provides three types of edges for different routing scenarios:
+
+| Edge Type                                                 | Purpose       | When to Use                                      |
+| --------------------------------------------------------- | ------------- | ------------------------------------------------ |
+| [**Step Forward**](edges.md#step-forward-edges)           | Unconditional | Sequential processing, guaranteed transitions    |
+| [**Prompt Condition**](edges.md#prompt-condition-edges)   | LLM-based     | Intelligent routing based on context and content |
+| [**Logical Condition**](edges.md#logical-condition-edges) | Code-based    | Deterministic routing based on memory/data       |
+
+## Step Forward Edges
+
+Step forward edges create **unconditional transitions** between nodes. They're useful for sequential processing where you always want to move to the next step.
+
+```yaml
+- source: Customer Support Request
+  target: Support Agent
+  type: stepForward
+```
+
+**Use Cases:** Data transformation pipelines, required validation steps, guaranteed notifications, logging and audit trails.
+
+## Prompt Condition Edges
+
+Prompt condition edges use **language models** to make intelligent routing decisions based on conversation context, memory state, and complex reasoning.
+
+```yaml
+- source: Support Agent
+  target: Escalate to Human
+  type: promptCondition
+  prompt: 'Based on the conversation, should this be escalated to a human agent?'
+```
+
+### Context-Aware Routing
+
+```yaml
+- source: Customer Service Bot
+  target: VIP Support
+  type: promptCondition
+  prompt: |
+    Should this customer be routed to VIP support?
+
+    Consider:
+    - Customer tier: {{memory.customerTier}}
+    - Issue severity: {{memory.issueSeverity}}  
+    - Previous escalations: {{memory.previousEscalations}}
+    - Current sentiment: (analyze from conversation)
+```
+
+### Multi-Path Routing
+
+```yaml
+# Route to different specialists based on issue type
+- source: Issue Classifier
+  target: Technical Support
+  type: promptCondition
+  prompt: 'Is this a technical/software issue requiring troubleshooting?'
+
+- source: Issue Classifier
+  target: Billing Support
+  type: promptCondition
+  prompt: 'Is this a billing, payment, or account-related issue?'
+
+- source: Issue Classifier
+  target: General Support
+  type: promptCondition
+  prompt: "Is this a general inquiry that doesn't fit other categories?"
+```
+
+## Logical Condition Edges
+
+Logical condition edges use **JavaScript expressions** to make deterministic routing decisions based on memory state, providing precise control over flow logic.
+
+```yaml
+- source: Order Lookup
+  target: Refund Processing
+  type: logicalCondition
+  condition: "state.memory.orderStatus === 'delivered'"
+```
+
+### How Condition Expressions Work
+
+The condition field accepts a **JavaScript expression** that will be evaluated to determine if the edge should be taken. The expression has access to the current agent state through the `state` variable.
+
+The condition is automatically wrapped in a function that provides the state context:
+
+```javascript
+// Your condition: state.memory.orderStatus === 'delivered'
+// Becomes:
+(function ({ state }) {
+  return state.memory.orderStatus === 'delivered';
+});
+```
+
+### Supported Expression Types
+
+#### Simple Comparisons
+
+```yaml
+# Equality check
+condition: "state.memory.status === 'active'"
+
+# Numeric comparison
+condition: "state.memory.orderValue > 1000"
+
+# String comparison
+condition: "state.memory.customerTier !== 'basic'"
+
+# Boolean check
+condition: "state.memory.isVerified"
+condition: "!state.memory.hasErrors"
+```
+
+#### Complex Expressions
+
+```yaml
+# Multiple conditions with AND
+condition: "state.memory.orderValue > 500 && state.memory.customerAge < 30"
+
+# OR conditions
+condition: "state.memory.priority === 'high' || state.memory.customerTier === 'vip'"
+
+# Nested property access
+condition: "state.memory.order.items.length > 5"
+
+# Array methods
+condition: "state.memory.tags.includes('urgent')"
+
+# String methods
+condition: "state.memory.email.endsWith('@company.com')"
+```
+
+#### Advanced JavaScript Operations
+
+```yaml
+# Ternary operators
+condition: "state.memory.score > 80 ? state.memory.level === 'expert' : state.memory.level === 'beginner'"
+
+# Date comparisons
+condition: "new Date(state.memory.orderDate) < new Date()"
+
+# Regular expressions
+condition: "/^[A-Z]{2}\\d{4}$/.test(state.memory.orderId)"
+
+# Math operations
+condition: "Math.abs(state.memory.temperature - 72) < 5"
+
+# JSON operations
+condition: "JSON.parse(state.memory.configString).enabled === true"
+```
+
+### Available Context
+
+Your condition expressions have access to:
+
+- **state**: The full agent state object (access as `state.memory`, `state.messages`, etc.)
+- **Standard JavaScript globals**: `Math`, `Date`, `JSON`, `console`
+- **String/Array/Object methods**: All standard JavaScript methods
+
+#### Accessing State Properties
+
+```yaml
+# Access memory through state
+condition: "state.memory.orderStatus === 'pending'"
+
+# Access messages
+condition: "state.messages.length > 10"
+
+# Access other state properties
+condition: "state.conversationId && state.memory.isAuthenticated"
+```
+
+**Note:** For security, the following are NOT available:
+
+- `process`, `require`, `global`, `Buffer`
+- File system or network operations
+- Module imports
+
+### Memory-Based Routing
+
+```yaml
+# Route based on customer tier
+- source: Customer Routing
+  target: Premium Support
+  type: logicalCondition
+  condition: "state.memory.customerTier === 'premium'"
+
+# Route based on order value
+- source: Order Processing
+  target: Manual Review
+  type: logicalCondition
+  condition: 'state.memory.orderValue > 1000'
+```
+
+### Complex Logic Conditions
+
+```yaml
+# Multiple conditions with AND logic
+- source: Payment Processor
+  target: Fraud Check
+  type: logicalCondition
+  condition: |
+    state.memory.orderValue > 500 && 
+    state.memory.customerAge < 30 &&
+    state.memory.shippingCountry !== state.memory.billingCountry
+
+# Date-based conditions
+- source: Order Validator
+  target: Late Order Handler
+  type: logicalCondition
+  condition: |
+    (Date.now() - new Date(state.memory.orderDate).getTime()) / (1000 * 60 * 60 * 24) > 30
+```
+
+## Edge Evaluation Order
+
+When multiple edges exist from the same source node, MindedJS evaluates them by **edge type priority**, not declaration order:
+
+### Priority System
+
+| Priority | Edge Type          | Behavior                                                |
+| -------- | ------------------ | ------------------------------------------------------- |
+| **1st**  | `stepForward`      | Always executes first (max 1 per source)                |
+| **2nd**  | `logicalCondition` | Executes if no step forward edge                        |
+| **3rd**  | `promptCondition`  | Executes if no step forward and logical conditions fail |
+
+```yaml
+# Priority-based evaluation regardless of declaration order
+edges:
+  - source: Decision Node
+    target: AI Router # 3rd priority: Only if logical fails
+    type: promptCondition
+    prompt: 'Which handler should process this request?'
+
+  - source: Decision Node
+    target: Default Handler # 1st priority: Always executes
+    type: stepForward
+
+  - source: Decision Node
+    target: High Priority # 2nd priority: Checked if no stepForward are present
+    type: logicalCondition
+    condition: "state.memory.priority === 'high'"
+```
+
+### Logical Condition Order
+
+Within logical condition edges from the same source, evaluation follows **declaration order**:
+
+```yaml
+edges:
+  # Logical conditions evaluated in declaration order: 1 -> 2 -> 3
+  - source: Order Processor
+    target: VIP Handler # 1st: Checked first
+    type: logicalCondition
+    condition: "state.memory.customerTier === 'vip'"
+
+  - source: Order Processor
+    target: Large Order # 2nd: Checked if VIP fails
+    type: logicalCondition
+    condition: 'state.memory.orderValue > 1000'
+
+  - source: Order Processor
+    target: Standard Handler # 3rd: Checked if both above fail
+    type: logicalCondition
+    condition: 'true' # Fallback condition
+```
+
+### Mixed Edge Example
+
+```yaml
+edges:
+  # This stepForward will ALWAYS execute first, regardless of order
+  - source: Payment Processor
+    target: Success Page
+    type: stepForward
+
+  # These will never execute because stepForward takes priority
+  - source: Payment Processor
+    target: Error Handler
+    type: logicalCondition
+    condition: "state.memory.status === 'error'"
+
+  - source: Payment Processor
+    target: AI Router
+    type: promptCondition
+    prompt: 'Should we route to error handling?'
+```
+
+## Advanced Patterns
+
+### Fallback Chains
+
+```yaml
+# Try specific handlers first, fall back to general
+- source: Issue Classifier
+  target: Billing Specialist
+  type: logicalCondition
+  condition: "state.memory.issueType === 'billing'"
+
+- source: Issue Classifier
+  target: General Support
+  type: stepForward # Fallback for any unmatched cases
+```
+
+### Error Handling
+
+```yaml
+- source: Payment Processor
+  target: Success Handler
+  type: logicalCondition
+  condition: "state.memory.paymentStatus === 'success'"
+
+- source: Payment Processor
+  target: Failure Handler
+  type: logicalCondition
+  condition: "state.memory.paymentStatus === 'failed' || state.memory.retryCount >= 3"
+```
+
+## Best Practices
+
+### Use the Right Edge Type
+
+- **stepForward** for guaranteed transitions
+- **logicalCondition** for deterministic rules
+- **promptCondition** for complex reasoning
+
+### Order Edges Strategically
+
+```yaml
+# Most specific conditions first
+edges:
+  - source: Router
+    target: Emergency Handler
+    type: logicalCondition
+    condition: "state.memory.priority === 'emergency'"
+
+  - source: Router
+    target: Standard Handler
+    type: stepForward # Catch-all last
+```
+
+### Always Provide Fallback Paths
+
+```yaml
+- source: Data Processor
+  target: Success Handler
+  type: logicalCondition
+  condition: "state.memory.status === 'success'"
+
+- source: Data Processor
+  target: Failure Handler
+  type: stepForward # Handles any unexpected states
+```
+
+## Next Steps
+
+- [**Tools**](tools.md) - Build powerful functions that your edges can route to
+- [**Memory Types**](../platform/memory.md) - Design state that supports effective routing
+- [**Implementation Examples**](../implementation-examples/edge-examples.md) - See complete edge examples
+
+Master edges to create intelligent, responsive flows that adapt to any situation! 🔄

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

@@ -0,0 +1,74 @@
+# Flows
+
+Flows are the **core orchestration mechanism** in MindedJS that define how your AI agent processes conversations through a series of connected nodes. A flow represents a complete run of an AI agent that handles user interactions from trigger to completion.
+
+## What are Flows?
+
+Flows define the **conversation logic** and **decision-making pathways** for your AI agent. Each flow consists of:
+
+* **Nodes** - Processing units that handle specific tasks
+* **Edges** - Routing logic that connects nodes
+* **Memory** - Shared state that persists throughout the flow
+* **Configuration** - Settings that control flow behavior
+
+```yaml
+name: Customer Support Flow
+nodes:
+  - type: trigger
+    triggerType: manual
+    name: Customer Request
+  
+  - type: promptNode
+    name: Support Agent
+    prompt: |
+      You are a helpful customer support agent.
+      Assist the customer with their inquiry.
+    llmConfig:
+      name: ChatOpenAI
+      properties:
+        model: gpt-4o
+
+edges:
+  - source: Customer Request
+    target: Support Agent
+    type: stepForward
+```
+
+## Flow Components Overview
+
+| Component                                        | Purpose    | Description                                          |
+| ------------------------------------------------ | ---------- | ---------------------------------------------------- |
+| [**Nodes**](nodes.md)                            | Processing | Handle specific tasks like LLM calls, tool execution |
+| [**Edges**](edges.md)                            | Routing    | Define transitions and decision logic between nodes  |
+| [**Memory**](../platform/memory.md)              | State      | Shared context that persists throughout the flow     |
+| [**Configuration**](flows.md#flow-configuration) | Settings   | Flow-level settings and metadata                     |
+
+## Basic Flow Structure
+
+Every flow follows this YAML structure:
+
+```yaml
+name: Flow Name                # Required: Human-readable flow identifier
+nodes:                        # Required: Array of processing nodes
+  - type: trigger             # Node type
+    name: Node Name           # Unique node identifier
+    # ... node-specific config
+    
+edges:                        # Required: Array of routing connections
+  - source: Source Node       # Source node name
+    target: Target Node       # Target node name
+    type: stepForward         # Edge type
+    # ... edge-specific config
+```
+
+## Nodes in Flows
+
+Flows orchestrate different types of nodes to handle various aspects of conversation processing. For detailed information about each node type, see the [**Nodes documentation**](nodes.md).
+
+## Edges in Flows
+
+Edges define how your flow moves between nodes based on different conditions. For comprehensive information about edge types and routing logic, see the [**Edges documentation**](edges.md).
+
+## Memory in Flows
+
+Memory provides shared state that persists throughout flow execution, allowing nodes to access and modify data from previous steps.