@minded-ai/mindedjs 1.0.19

package/docs/core-concepts/events.md

@@ -0,0 +1,161 @@
+# Events
+
+Events are messages that flow through your agent during execution, providing visibility into what's happening and enabling reactive behavior.
+
+MindedJS currently supports two main event types: `AI_MESSAGE` and `TRIGGER_EVENT`. Each event type has its own specific input structure, output requirements, and use cases.
+
+## AI\_MESSAGE
+
+The `AI_MESSAGE` event is emitted when an AI generates a message that should be sent to the user.
+
+### Input Structure
+
+```typescript
+{
+  message: string;     // The AI-generated message content
+  memory: Memory;      // Current memory state (your defined memory schema)
+}
+```
+
+### Handler Return Value
+
+* **Return type**: `void`
+* **Purpose**: Handlers are used for side effects like sending messages to UI
+* **Note**: Return values are ignored
+
+### Usage Example
+
+```typescript
+import { Agent, events } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+
+// Listen to AI messages
+agent.on(events.AI_MESSAGE, async ({ message, memory }) => {
+  console.log('AI said:', message);
+  console.log('Current memory:', memory);
+  
+  // Send message to user interface
+  await sendMessageToUser(message);
+  
+  // Send via WebSocket
+  await websocket.send(JSON.stringify({ 
+    type: 'ai_message', 
+    content: message 
+  }));
+});
+```
+
+### Common Use Cases
+
+* **Real-time Chat UI**: Send AI responses to chat interfaces
+* **Logging**: Record AI responses for analytics or debugging
+* **Message Formatting**: Transform AI messages before displaying to users
+* **Notifications**: Trigger alerts or notifications based on AI responses
+
+## TRIGGER\_EVENT
+
+The `TRIGGER_EVENT` event is emitted when a trigger node is executed. This event allows you to qualify, transform, and provide initial state for trigger inputs before they're processed by the agent.
+
+### Input Structure
+
+```typescript
+{
+  triggerName: string;  // Name of the trigger being executed
+  triggerBody: any;     // The trigger input data (type varies by trigger)
+}
+```
+
+### Handler Return Values
+
+TRIGGER\_EVENT handlers have three possible return types:
+
+#### 1. Provide Initial State
+
+```typescript
+{
+  messages?: BaseMessage[];  // Initial messages for the conversation
+  memory?: Memory;          // Initial memory state
+}
+```
+
+#### 2. Disqualify the Trigger
+
+```typescript
+false  // Rejects/disqualifies the trigger
+```
+
+#### 3. Qualify without providing initial state
+
+```typescript
+void  // If no initial state is needed
+```
+
+### Usage Examples
+
+#### Processing User Input
+
+```typescript
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (triggerName === 'userMessage') {
+    return {
+      memory: { 
+        conversationStarted: true,
+      },
+      messages: [new HumanMessage(triggerBody)],
+    };
+  }
+});
+```
+
+#### Trigger Qualification
+
+```typescript
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  // Validate the trigger input
+  if (!isValidInput(triggerBody)) {
+    return false; // Disqualify the trigger
+  }
+  
+  // Only process business hours triggers
+  if (triggerName === 'supportRequest' && !isBusinessHours()) {
+    return false;
+  }
+  
+  return {
+    memory: { validatedInput: triggerBody },
+    messages: [],
+  };
+});
+```
+
+#### Input Transformation
+
+```typescript
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (triggerName === 'emailTrigger') {
+    // Transform email data into structured format
+    const parsedEmail = parseEmailContent(triggerBody);
+    
+    return {
+      memory: { 
+        emailSubject: parsedEmail.subject,
+        senderEmail: parsedEmail.from 
+      },
+      messages: [new HumanMessage(parsedEmail.content)],
+    };
+  }
+});
+```
+
+### Common Use Cases
+
+* **Input Validation**: Ensure trigger data meets requirements before processing
+* **Data Transformation**: Convert trigger inputs into standardized formats
+* **Context Setting**: Provide initial memory state based on trigger context
+* **Access Control**: Disqualify triggers based on permissions or business rules
+* **Routing Logic**: Handle different trigger types with specific logic

package/docs/core-concepts/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**](memory-types.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.

package/docs/core-concepts/memory-types.md

@@ -0,0 +1,208 @@
+# Memory Types
+
+Memory in MindedJS allows agents to persist and share data across conversation turns and flow executions. It acts as the agent's working memory, storing context, user information, conversation state, and any other data your agent needs to remember.
+
+## What is Memory?
+
+Memory is a structured data store that:
+- Persists throughout an agent session
+- Is accessible to all nodes in your flows
+- Gets automatically merged when updated
+- Is validated against a schema you define
+- Can store any JSON-serializable data
+
+## Defining Memory Schema
+
+Memory schemas are defined using [Zod](https://zod.dev/) for type safety and runtime validation.
+
+```typescript
+import { z } from 'zod';
+
+const memorySchema = z.object({
+  user: z.object({
+    id: z.string(),
+    name: z.string(),
+    preferences: z.object({
+      language: z.string().default('en'),
+      timezone: z.string().default('UTC'),
+    }),
+  }),
+  conversation: z.object({
+    topic: z.string().optional(),
+    urgency: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  order: z.object({
+    id: z.string(),
+    status: z.string(),
+    total: z.number(),
+  }).optional(),
+});
+
+type Memory = z.infer<typeof memorySchema>;
+```
+
+## Using Memory in Your Agent
+
+### 1. Configure Memory Schema
+
+```typescript
+import { Agent } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+```
+
+### 2. Initialize Memory
+
+Memory is typically initialized when a trigger event occurs:
+
+```typescript
+import { events } from 'mindedjs';
+
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (triggerName === 'new_order_issue') {
+    return {
+      memory: {
+        user: { id: triggerBody.userId, name: triggerBody.userName },
+        order: { id: triggerBody.orderId, status: 'pending' },
+      },
+      messages: [],
+    };
+  }
+});
+```
+
+### 3. Access Memory in Tools
+
+Tools can read from and write to memory:
+
+```typescript
+const updateOrderStatus = {
+  name: 'updateOrderStatus',
+  description: 'Updates the order status in memory',
+  inputSchema: z.object({
+    newStatus: z.string(),
+  }),
+  execute: async ({ input, memory }) => {
+    // Read from memory
+    const currentOrder = memory.order;
+    
+    // Return updated memory (merges with existing)
+    return {
+      result: `Order status updated to ${input.newStatus}`,
+      memory: {
+        order: {
+          ...currentOrder,
+          status: input.newStatus,
+          lastUpdated: new Date().toISOString(),
+        }
+      }
+    };
+  },
+};
+```
+
+## Memory Lifecycle
+
+1. **Initialization**: Memory starts empty `{}` and gets populated during trigger events
+2. **Persistence**: Automatically persisted between conversation turns
+3. **Updates**: Memory updates are merged when tools return a memory object
+4. **Validation**: All updates are validated against your schema
+
+```typescript
+// Current memory: { userId: "123", userName: "John" }
+// Tool returns: { memory: { userName: "John Doe", email: "john@example.com" } }
+// Result: { userId: "123", userName: "John Doe", email: "john@example.com" }
+```
+
+## Best Practices
+
+### 1. Keep It Focused
+Only store data relevant to your agent's functionality:
+
+```typescript
+// Good: Focused schema
+const memorySchema = z.object({
+  customerId: z.string(),
+  currentIssue: z.string(),
+  resolutionSteps: z.array(z.string()),
+});
+```
+
+### 2. Use Optional Fields and Defaults
+```typescript
+const memorySchema = z.object({
+  userId: z.string(),
+  orderId: z.string().optional(), // Not all conversations involve orders
+  conversationState: z.enum(['started', 'in_progress', 'resolved']).default('started'),
+  attemptCount: z.number().default(0),
+});
+```
+
+### 3. Structure Related Data
+Group related fields into objects:
+
+```typescript
+const memorySchema = z.object({
+  customer: z.object({
+    id: z.string(),
+    name: z.string(),
+    tier: z.enum(['bronze', 'silver', 'gold']),
+  }),
+  session: z.object({
+    startTime: z.string(),
+    channel: z.enum(['chat', 'email', 'phone']),
+  }),
+});
+```
+
+## Common Patterns
+
+### User Context Pattern
+```typescript
+const memorySchema = z.object({
+  user: z.object({
+    id: z.string(),
+    profile: z.object({
+      name: z.string(),
+      email: z.string(),
+      preferences: z.record(z.unknown()),
+    }),
+  }),
+});
+```
+
+### Conversation State Pattern
+```typescript
+const memorySchema = z.object({
+  conversation: z.object({
+    phase: z.enum(['greeting', 'information_gathering', 'processing', 'resolution']),
+    data: z.record(z.unknown()),
+  }),
+});
+```
+
+## Memory vs Messages
+
+- **Memory**: Structured data representing current state and context
+- **Messages**: Message history (AI, Human, Tool call, System etc.)
+
+```typescript
+// Memory: Current state
+{
+  orderId: "ORD-123",
+  status: "processing",
+  customer: { name: "John", tier: "gold" }
+}
+
+// Messages: Conversation history
+[
+  { role: "user", content: "I need help with my order" },
+  { role: "assistant", content: "I'd be happy to help!" },
+]
+```
+
+Both work together to provide complete context to your agent. 

package/docs/core-concepts/nodes.md

@@ -0,0 +1,239 @@
+# 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](#trigger-nodes)** | Entry Points | Start flows from various sources |
+| **[Prompt](#prompt-nodes)** | LLM Processing | Generate responses using language models |
+| **[Tool](#tool-nodes)** | Actions | Execute external functions and APIs |
+| **[Junction](#junction-nodes)** | Flow Control | Route and organize flow logic |
+
+## 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 `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 false;
+  }
+  
+  return {
+    memory: { businessHours: true },
+    messages: [new HumanMessage(triggerBody)],
+  };
+});
+```
+
+## Prompt Nodes
+
+Prompt nodes process input through LLM to generate intelligent responses or invoke tools.
+
+### 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'"
+```
+
+## 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](memory-types.md)** - Design effective state management
+
+Nodes are your building blocks - combine them strategically to create powerful AI workflows! 🔧