xcomponent-ai 0.2.2 → 0.3.0

package/examples/distributed-demo/README.md

@@ -0,0 +1,234 @@
+# Distributed Multi-Process Demo
+
+This demo shows how to run xcomponent-ai components in **separate processes** communicating via **Redis Pub/Sub**.
+
+## Architecture
+
+```
+┌─────────────────────┐         Redis         ┌─────────────────────┐
+│   Process 1         │         Pub/Sub       │   Process 2         │
+│                     │                       │                     │
+│  OrderComponent     │──────────────────────▶│  PaymentComponent   │
+│  Port: 3001         │   PROCESS event       │  Port: 3002         │
+│                     │                       │                     │
+│  Order FSM          │                       │  Payment FSM        │
+│  - Created          │                       │  - Pending          │
+│  - Validated ───────┼───────────────────────┼──▶ Processing       │
+│  - Completed        │                       │  - Completed        │
+└─────────────────────┘                       └─────────────────────┘
+```
+
+**How it works:**
+1. Process 1 (OrderComponent) runs on port 3001
+2. Process 2 (PaymentComponent) runs on port 3002
+3. When Order transitions to "Validated", it publishes a message to Redis
+4. PaymentComponent receives the message via Redis and triggers the transition
+
+## Prerequisites
+
+1. **Install Redis:**
+   ```bash
+   # macOS
+   brew install redis
+   brew services start redis
+
+   # Ubuntu/Debian
+   sudo apt-get install redis-server
+   sudo systemctl start redis
+
+   # Docker
+   docker run -d -p 6379:6379 redis:7-alpine
+   ```
+
+2. **Verify Redis is running:**
+   ```bash
+   redis-cli ping
+   # Should return: PONG
+   ```
+
+3. **Install xcomponent-ai with Redis support:**
+   ```bash
+   npm install -g xcomponent-ai redis
+   ```
+
+## Running the Demo
+
+### Step 1: Start Process 1 (OrderComponent)
+
+In **Terminal 1:**
+```bash
+xcomponent-ai serve examples/distributed-demo/order.yaml \
+  --port 3001 \
+  --broker redis://localhost:6379
+```
+
+Expected output:
+```
+📡 Mode: Distributed (broker: redis://localhost:6379)
+🚀 xcomponent-ai Runtime Started
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Component: OrderComponent
+   Machines:
+   - Order (3 states, 3 transitions)
+
+🌐 API Server:    http://localhost:3001
+📊 Dashboard:     http://localhost:3001/dashboard.html
+```
+
+### Step 2: Start Process 2 (PaymentComponent)
+
+In **Terminal 2:**
+```bash
+xcomponent-ai serve examples/distributed-demo/payment.yaml \
+  --port 3002 \
+  --broker redis://localhost:6379
+```
+
+Expected output:
+```
+📡 Mode: Distributed (broker: redis://localhost:6379)
+🚀 xcomponent-ai Runtime Started
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Component: PaymentComponent
+   Machines:
+   - Payment (4 states, 3 transitions)
+
+🌐 API Server:    http://localhost:3002
+📊 Dashboard:     http://localhost:3002/dashboard.html
+```
+
+### Step 3: Test Cross-Process Communication
+
+In **Terminal 3:**
+
+1. **Create a Payment instance in Process 2:**
+   ```bash
+   curl -X POST http://localhost:3002/api/components/PaymentComponent/instances \
+     -H "Content-Type: application/json" \
+     -d '{
+       "machineName": "Payment",
+       "context": {
+         "orderId": "ORD-001",
+         "amount": 1000,
+         "customerId": "CUST-001"
+       }
+     }'
+   ```
+
+   Note the `instanceId` returned (e.g., `abc-123-def-456`).
+
+2. **Create an Order instance in Process 1:**
+   ```bash
+   curl -X POST http://localhost:3001/api/components/OrderComponent/instances \
+     -H "Content-Type: application/json" \
+     -d '{
+       "machineName": "Order",
+       "context": {
+         "orderId": "ORD-001",
+         "amount": 1000,
+         "customerId": "CUST-001"
+       }
+     }'
+   ```
+
+   Note the `instanceId` returned (e.g., `xyz-789-uvw-012`).
+
+3. **Trigger VALIDATE on Order (Process 1):**
+   ```bash
+   ORDER_ID="xyz-789-uvw-012"  # Replace with actual ID from step 2
+
+   curl -X POST http://localhost:3001/api/instances/$ORDER_ID/events \
+     -H "Content-Type: application/json" \
+     -d '{
+       "type": "VALIDATE"
+     }'
+   ```
+
+4. **Verify Payment transitioned in Process 2:**
+   ```bash
+   PAYMENT_ID="abc-123-def-456"  # Replace with actual ID from step 1
+
+   curl http://localhost:3002/api/instances/$PAYMENT_ID
+   ```
+
+   You should see the Payment instance now in `Processing` state!
+
+### Step 4: Observe Cross-Process Communication
+
+**In Terminal 1 (OrderComponent):**
+You'll see:
+```
+[2:34:01 PM] [OrderComponent] xyz-789-uvw-012: Created → Validated (event: VALIDATE)
+```
+
+**In Terminal 2 (PaymentComponent):**
+You'll see:
+```
+[2:34:01 PM] [PaymentComponent] abc-123-def-456: Pending → Processing (event: PROCESS)
+```
+
+**Magic!** The Order in Process 1 triggered the Payment in Process 2 via Redis Pub/Sub! 🎉
+
+## Viewing Dashboards
+
+Open in your browser:
+- **Process 1 Dashboard:** http://localhost:3001/dashboard.html
+- **Process 2 Dashboard:** http://localhost:3002/dashboard.html
+
+You can see real-time state transitions in both processes independently.
+
+## Scaling Up
+
+You can run **multiple instances** of each process for load balancing:
+
+```bash
+# 2 instances of OrderComponent
+xcomponent-ai serve order.yaml --port 3001 --broker redis://localhost:6379 &
+xcomponent-ai serve order.yaml --port 3011 --broker redis://localhost:6379 &
+
+# 3 instances of PaymentComponent
+xcomponent-ai serve payment.yaml --port 3002 --broker redis://localhost:6379 &
+xcomponent-ai serve payment.yaml --port 3012 --broker redis://localhost:6379 &
+xcomponent-ai serve payment.yaml --port 3022 --broker redis://localhost:6379 &
+
+# Add nginx load balancer in front
+```
+
+All instances subscribe to the same Redis channels, enabling **horizontal scaling**.
+
+## Environment Variable
+
+Instead of `--broker` flag, you can use:
+
+```bash
+export XCOMPONENT_BROKER_URL=redis://localhost:6379
+
+xcomponent-ai serve order.yaml --port 3001
+xcomponent-ai serve payment.yaml --port 3002
+```
+
+## Production Deployment
+
+For production, use:
+- **Redis Cluster** for high availability
+- **Redis Sentinel** for automatic failover
+- **Kubernetes** for orchestration
+- **Load balancer** (nginx, HAProxy) for API endpoints
+
+See [SCALABILITY.md](../../SCALABILITY.md) for detailed production patterns.
+
+## Switching Back to In-Memory
+
+To run both components in a **single process** (in-memory mode):
+
+```bash
+xcomponent-ai serve \
+  examples/distributed-demo/order.yaml \
+  examples/distributed-demo/payment.yaml \
+  --port 3000
+  # No --broker flag = in-memory mode by default
+```
+
+**Zero code changes!** Just configuration. 🚀

package/examples/distributed-demo/order.yaml

@@ -0,0 +1,71 @@
+# Order Component - Process 1
+# This component runs in its own process and communicates with PaymentComponent via Redis
+
+name: OrderComponent
+version: 1.0.0
+metadata:
+  description: Order management system (distributed process 1)
+
+stateMachines:
+  - name: Order
+    initialState: Created
+    contextSchema:
+      orderId:
+        type: text
+        label: Order ID
+        required: true
+        placeholder: ORD-001
+      amount:
+        type: number
+        label: Total Amount
+        required: true
+        min: 1
+      customerId:
+        type: text
+        label: Customer ID
+        required: true
+        placeholder: CUST-001
+
+    states:
+      - name: Created
+        type: entry
+        description: Order created and awaiting validation
+
+      - name: Validated
+        type: regular
+        description: Order validated, payment triggered via Redis
+        # DISTRIBUTED CROSS-COMPONENT: Trigger payment in PaymentComponent (different process!)
+        cascadingRules:
+          - targetComponent: PaymentComponent
+            targetMachine: Payment
+            targetState: Pending
+            event: PROCESS
+            payload:
+              orderId: "{{orderId}}"
+              amount: "{{amount}}"
+              customerId: "{{customerId}}"
+
+      - name: Completed
+        type: final
+        description: Order completed successfully
+
+      - name: Cancelled
+        type: error
+        description: Order cancelled
+
+    transitions:
+      - from: Created
+        to: Validated
+        event: VALIDATE
+        type: triggerable
+        description: Validate order and trigger payment
+
+      - from: Validated
+        to: Completed
+        event: COMPLETE
+        type: triggerable
+
+      - from: Created
+        to: Cancelled
+        event: CANCEL
+        type: triggerable

package/examples/distributed-demo/payment.yaml

@@ -0,0 +1,60 @@
+# Payment Component - Process 2
+# This component runs in a SEPARATE process and receives events from OrderComponent via Redis
+
+name: PaymentComponent
+version: 1.0.0
+metadata:
+  description: Payment processing system (distributed process 2)
+
+stateMachines:
+  - name: Payment
+    initialState: Pending
+    contextSchema:
+      orderId:
+        type: text
+        label: Order ID
+        required: true
+      amount:
+        type: number
+        label: Amount
+        required: true
+      customerId:
+        type: text
+        label: Customer ID
+        required: true
+
+    states:
+      - name: Pending
+        type: entry
+        description: Payment awaiting processing (receives PROCESS from OrderComponent)
+
+      - name: Processing
+        type: regular
+        description: Payment being processed
+
+      - name: Completed
+        type: final
+        description: Payment completed successfully
+
+      - name: Failed
+        type: error
+        description: Payment failed
+
+    transitions:
+      - from: Pending
+        to: Processing
+        event: PROCESS
+        type: triggerable
+        description: Start payment processing (triggered by OrderComponent via Redis)
+
+      - from: Processing
+        to: Completed
+        event: CONFIRM
+        type: triggerable
+        description: Confirm payment success
+
+      - from: Processing
+        to: Failed
+        event: FAIL
+        type: triggerable
+        description: Mark payment as failed

package/examples/event-accumulation-demo.yaml

@@ -0,0 +1,172 @@
+# Event Accumulation Demo
+# Shows how to accumulate multiple events and use EXPLICIT CONTROL for transitions
+#
+# Use Case: Trading Order that receives multiple execution notifications
+# and transitions to "Fully Executed" only when all quantity is executed
+#
+# Key Pattern: sender.sendToSelf() for explicit transition control
+
+name: TradingComponent
+version: 1.0.0
+metadata:
+  description: Trading order with partial executions and explicit control
+
+# Define triggered methods that accumulate data and EXPLICITLY control transitions
+triggeredMethods:
+  # Accumulates execution data and EXPLICITLY decides when to transition
+  accumulateExecution: |
+    async function(event, context, sender) {
+      // Initialize if first execution
+      if (!context.executedQuantity) {
+        context.executedQuantity = 0;
+      }
+      if (!context.executions) {
+        context.executions = [];
+      }
+
+      // Add executed quantity from event
+      const executedQty = event.payload.quantity || 0;
+      context.executedQuantity += executedQty;
+
+      // Track individual executions for audit
+      context.executions.push({
+        quantity: executedQty,
+        price: event.payload.price,
+        timestamp: event.timestamp,
+        executionId: event.payload.executionId
+      });
+
+      console.log(`Accumulated: ${context.executedQuantity}/${context.totalQuantity}`);
+
+      // EXPLICIT CONTROL: Decide when to transition to FullyExecuted
+      if (context.executedQuantity >= context.totalQuantity) {
+        console.log(`Order ${context.orderId} is now fully executed!`);
+        // Send event to self to trigger transition to FullyExecuted
+        await sender.sendToSelf({
+          type: 'FULLY_EXECUTED',
+          payload: {
+            totalExecuted: context.executedQuantity,
+            executionCount: context.executions.length,
+            averagePrice: context.executions.reduce((sum, e) => sum + e.price, 0) / context.executions.length
+          },
+          timestamp: Date.now()
+        });
+      }
+    }
+
+  # Handle completion
+  handleCompletion: |
+    async function(event, context, sender) {
+      console.log(`Order ${context.orderId} completed!`);
+      console.log(`  Total executed: ${event.payload.totalExecuted}`);
+      console.log(`  Executions: ${event.payload.executionCount}`);
+      console.log(`  Average price: ${event.payload.averagePrice}`);
+
+      context.completedAt = Date.now();
+      context.stats = event.payload;
+    }
+
+stateMachines:
+  - name: TradingOrder
+    initialState: Created
+
+    contextSchema:
+      orderId:
+        type: text
+        label: Order ID
+        required: true
+      symbol:
+        type: text
+        label: Symbol (e.g., AAPL)
+        required: true
+      totalQuantity:
+        type: number
+        label: Total Quantity to Execute
+        required: true
+        min: 1
+      side:
+        type: select
+        label: Side
+        options:
+          - BUY
+          - SELL
+        required: true
+
+    states:
+      - name: Created
+        type: entry
+        description: Order created, waiting for market submission
+
+      - name: Submitted
+        type: regular
+        description: Order submitted to market
+
+      - name: PartiallyExecuted
+        type: regular
+        description: Order partially executed, waiting for more fills
+
+      - name: FullyExecuted
+        type: regular
+        description: Order fully executed
+
+      - name: Completed
+        type: final
+        description: Order completed (settlement done)
+
+      - name: Cancelled
+        type: error
+        description: Order cancelled
+
+    transitions:
+      # Submit order to market
+      - from: Created
+        to: Submitted
+        event: SUBMIT
+        type: triggerable
+
+      # First execution notification (Submitted → PartiallyExecuted)
+      - from: Submitted
+        to: PartiallyExecuted
+        event: EXECUTION_NOTIFICATION
+        type: triggerable
+        triggeredMethod: accumulateExecution
+
+      # SELF-LOOP: Subsequent execution notifications (PartiallyExecuted → PartiallyExecuted)
+      # Triggered method decides when to send FULLY_EXECUTED event
+      - from: PartiallyExecuted
+        to: PartiallyExecuted
+        event: EXECUTION_NOTIFICATION
+        type: triggerable
+        triggeredMethod: accumulateExecution
+
+      # EXPLICIT TRANSITION: Triggered by sender.sendToSelf() in accumulateExecution
+      # No guards! The business logic is in the triggered method
+      - from: PartiallyExecuted
+        to: FullyExecuted
+        event: FULLY_EXECUTED
+        type: triggerable
+        triggeredMethod: handleCompletion
+
+      # Also handle direct full execution from Submitted (single large fill)
+      - from: Submitted
+        to: FullyExecuted
+        event: FULLY_EXECUTED
+        type: triggerable
+        triggeredMethod: handleCompletion
+
+      # Settlement
+      - from: FullyExecuted
+        to: Completed
+        event: SETTLE
+        type: triggerable
+
+      # Cancellation
+      - from: Submitted
+        to: Cancelled
+        event: CANCEL
+        type: triggerable
+
+      - from: PartiallyExecuted
+        to: Cancelled
+        event: CANCEL
+        type: triggerable