xcomponent-ai 0.4.2 → 0.5.0

package/CONTRIBUTING.md

@@ -10,7 +10,7 @@ By participating in this project, you agree to maintain a respectful and inclusi
 
 ### Reporting Bugs
 
-1. Check if the bug has already been reported in [Issues](https://github.com/fredericcarre/mayele-ai/issues)
+1. Check if the bug has already been reported in [Issues](https://github.com/fredericcarre/xcomponent-ai/issues)
 2. If not, create a new issue with:
    - Clear, descriptive title
    - Steps to reproduce
@@ -20,7 +20,7 @@ By participating in this project, you agree to maintain a respectful and inclusi
 
 ### Suggesting Features
 
-1. Check existing [Discussions](https://github.com/fredericcarre/mayele-ai/discussions) and Issues
+1. Check existing [Discussions](https://github.com/fredericcarre/xcomponent-ai/discussions) and Issues
 2. Create a new discussion with:
    - Use case description
    - Proposed solution
@@ -31,8 +31,8 @@ By participating in this project, you agree to maintain a respectful and inclusi
 
 1. **Fork and Clone**
    ```bash
-   git clone https://github.com/YOUR_USERNAME/mayele-ai.git
-   cd mayele-ai
+   git clone https://github.com/YOUR_USERNAME/xcomponent-ai.git
+   cd xcomponent-ai
    npm install
    ```
 
@@ -186,7 +186,7 @@ npm run cli -- load examples/trading.yaml
 
 ## Questions?
 
-- Open a [Discussion](https://github.com/fredericcarre/mayele-ai/discussions)
+- Open a [Discussion](https://github.com/fredericcarre/xcomponent-ai/discussions)
 - Join our community chat (coming soon)
 - Email: contributors@xcomponent.com
 

package/EVENT-ACCUMULATION-GUIDE.md

@@ -53,46 +53,59 @@ stateMachines:
 
 ### Step 2: Create Accumulation Method with Explicit Control
 
+**YAML** -- declare the method name on the transition:
+
 ```yaml
-triggeredMethods:
-  accumulateExecution: |
-    async function(event, context, sender) {
-      // Initialize counters
-      if (!context.executedQuantity) {
-        context.executedQuantity = 0;
-      }
-      if (!context.executions) {
-        context.executions = [];
-      }
-
-      // Accumulate quantity from event
-      const qty = event.payload.quantity || 0;
-      context.executedQuantity += qty;
-
-      // Track individual executions
-      context.executions.push({
-        quantity: qty,
-        price: event.payload.price,
-        executionId: event.payload.executionId,
-        timestamp: event.timestamp
-      });
+transitions:
+  - from: PartiallyExecuted
+    to: PartiallyExecuted
+    event: EXECUTION_NOTIFICATION
+    type: triggerable
+    triggeredMethod: accumulateExecution
+```
 
-      console.log(`Executed: ${context.executedQuantity}/${context.totalQuantity}`);
-
-      // EXPLICIT CONTROL: Decide when to transition
-      if (context.executedQuantity >= context.totalQuantity) {
-        // Send event to self to trigger completion
-        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()
-        });
-      }
+**TypeScript** -- implement the handler:
+
+```typescript
+runtime.on('triggered_method', async ({ method, event, context, sender }) => {
+  if (method === 'accumulateExecution') {
+    // Initialize counters
+    if (!context.executedQuantity) {
+      context.executedQuantity = 0;
+    }
+    if (!context.executions) {
+      context.executions = [];
     }
+
+    // Accumulate quantity from event
+    const qty = event.payload.quantity || 0;
+    context.executedQuantity += qty;
+
+    // Track individual executions
+    context.executions.push({
+      quantity: qty,
+      price: event.payload.price,
+      executionId: event.payload.executionId,
+      timestamp: event.timestamp
+    });
+
+    console.log(`Executed: ${context.executedQuantity}/${context.totalQuantity}`);
+
+    // EXPLICIT CONTROL: Decide when to transition
+    if (context.executedQuantity >= context.totalQuantity) {
+      // Send event to self to trigger completion
+      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()
+      });
+    }
+  }
+});
 ```
 
 **Key Points:**
@@ -146,48 +159,12 @@ transitions:
 
 ## 📝 Complete Example
 
+**YAML** (`trading.yaml`):
+
 ```yaml
 name: TradingComponent
 version: 1.0.0
 
-triggeredMethods:
-  accumulateExecution: |
-    async function(event, context, sender) {
-      if (!context.executedQuantity) context.executedQuantity = 0;
-      if (!context.executions) context.executions = [];
-
-      const qty = event.payload.quantity || 0;
-      context.executedQuantity += qty;
-      context.executions.push({
-        quantity: qty,
-        price: event.payload.price,
-        executionId: event.payload.executionId,
-        timestamp: event.timestamp
-      });
-
-      console.log(`Executed: ${context.executedQuantity}/${context.totalQuantity}`);
-
-      // EXPLICIT CONTROL
-      if (context.executedQuantity >= context.totalQuantity) {
-        await sender.sendToSelf({
-          type: 'FULLY_EXECUTED',
-          payload: {
-            totalExecuted: context.executedQuantity,
-            executionCount: context.executions.length
-          },
-          timestamp: Date.now()
-        });
-      }
-    }
-
-  handleCompletion: |
-    async function(event, context, sender) {
-      console.log(`Order completed!`);
-      console.log(`  Total: ${event.payload.totalExecuted}`);
-      console.log(`  Executions: ${event.payload.executionCount}`);
-      context.stats = event.payload;
-    }
-
 stateMachines:
   - name: TradingOrder
     initialState: Created
@@ -242,6 +219,47 @@ stateMachines:
         type: triggerable
 ```
 
+**TypeScript** -- implement the handlers:
+
+```typescript
+runtime.on('triggered_method', async ({ method, event, context, sender }) => {
+  if (method === 'accumulateExecution') {
+    if (!context.executedQuantity) context.executedQuantity = 0;
+    if (!context.executions) context.executions = [];
+
+    const qty = event.payload.quantity || 0;
+    context.executedQuantity += qty;
+    context.executions.push({
+      quantity: qty,
+      price: event.payload.price,
+      executionId: event.payload.executionId,
+      timestamp: event.timestamp
+    });
+
+    console.log(`Executed: ${context.executedQuantity}/${context.totalQuantity}`);
+
+    // EXPLICIT CONTROL
+    if (context.executedQuantity >= context.totalQuantity) {
+      await sender.sendToSelf({
+        type: 'FULLY_EXECUTED',
+        payload: {
+          totalExecuted: context.executedQuantity,
+          executionCount: context.executions.length
+        },
+        timestamp: Date.now()
+      });
+    }
+  }
+
+  if (method === 'handleCompletion') {
+    console.log(`Order completed!`);
+    console.log(`  Total: ${event.payload.totalExecuted}`);
+    console.log(`  Executions: ${event.payload.executionCount}`);
+    context.stats = event.payload;
+  }
+});
+```
+
 ---
 
 ## 🧪 Testing

package/EXTERNAL-API.md

@@ -714,6 +714,6 @@ public void onOrderValidated(String orderId) {
 
 - See [SCALABILITY.md](./SCALABILITY.md) for production deployment
 - See [LLM-GUIDE.md](./LLM-GUIDE.md) for YAML FSM design patterns
-- See `examples/distributed-demo/` for working examples
+- See `examples/distributed/` (RabbitMQ) or `examples/distributed-redis/` (Redis) for working examples
 
 **Built for interoperability.** Any language, any platform. 🌍

package/LLM-GUIDE.md

@@ -50,8 +50,6 @@ stateMachines:
         to: Validated
         event: VALIDATE
         type: triggerable
-        guards:
-          - keys: [orderId, amount]
       - from: Validated
         to: Executed
         event: EXECUTE
@@ -197,7 +195,7 @@ GET /api/components/:componentName/diagrams/:machineName
 
 Returns Mermaid `stateDiagram-v2` syntax with:
 - State styling (entry/orange, final/green, error/red)
-- Transitions with guards
+- Transitions with event labels
 - State descriptions as notes
 
 ### 6. Distributed Mode (Multi-Process)
@@ -233,97 +231,153 @@ states:
 
 When Order transitions to "Validated" in Process 1, Redis automatically delivers the PROCESS event to PaymentComponent in Process 2.
 
-See: `examples/distributed-demo/` for complete working example.
+See: `examples/distributed/` (RabbitMQ) or `examples/distributed-redis/` (Redis) for complete working examples.
 
-### 7. Broadcast with Property Filters (from Triggered Methods)
+### 6b. Entry Point Modes (Singleton vs Multiple)
 
-Triggered methods can send events to **specific instances** using property filters:
+**Entry point machines** can operate in two modes, controlling how instances are created:
+
+#### Configuration Options
 
 ```yaml
-triggeredMethods:
-  notifyRiskMonitors: |
-    async function(event, context, sender) {
-      // Update local context
-      context.executedQuantity += event.payload.quantity;
-
-      // BROADCAST to risk monitors for THIS CUSTOMER ONLY
-      const count = await sender.broadcast(
-        'RiskMonitor',           // Target machine
-        'Monitoring',            // Target state
-        {
-          type: 'ORDER_UPDATE',
-          payload: {
-            orderId: context.orderId,
-            executedQuantity: context.executedQuantity
-          },
-          timestamp: Date.now()
-        },
-        [
-          // FILTERS: Property-based targeting
-          { property: 'customerId', value: context.customerId },
-          { property: 'assetClass', operator: '===', value: 'EQUITY' }
-        ]
-      );
-
-      console.log(`Notified ${count} risk monitor(s)`);
-    }
+name: OrderComponent
+entryMachine: Order           # Which machine is the entry point
+entryMachineMode: multiple    # 'singleton' or 'multiple' (default: 'singleton')
+autoCreateEntryPoint: false   # Auto-create instance on startup? (default: true for singleton, false for multiple)
+
+stateMachines:
+  - name: Order
+    initialState: Created
+    # ...
 ```
 
-**Available sender methods:**
-- `sender.sendTo(instanceId, event)` - Send to specific instance
-- `sender.broadcast(machine, state, event, filters?)` - Broadcast with optional filters
-- `sender.broadcastToComponent(component, machine, state, event, filters?)` - Cross-component broadcast
-- `sender.createInstance(machine, context)` - Create new instance
+#### Singleton Mode (Default)
 
-**Filter operators:** `===`, `!==`, `>`, `<`, `>=`, `<=`, `contains`, `in`
+Best for: Monitors, supervisors, background processors
 
-**Multiple filters = AND logic** (all must match).
+```yaml
+name: MonitoringComponent
+entryMachine: SystemMonitor
+entryMachineMode: singleton   # Only ONE instance allowed
+autoCreateEntryPoint: true    # Created automatically on startup
 
-See: `examples/advanced-patterns-demo.yaml`
+stateMachines:
+  - name: SystemMonitor
+    initialState: Idle
+```
+
+**Behavior:**
+- ✅ Runtime auto-creates the instance on startup
+- ❌ API calls to create additional instances are rejected
+- ✅ Instance recreated automatically if component restarts
+
+#### Multiple Mode
+
+Best for: Orders, payments, user workflows - entities created by users
+
+```yaml
+name: OrderComponent
+entryMachine: Order
+entryMachineMode: multiple    # Multiple instances allowed
+autoCreateEntryPoint: false   # Don't auto-create (user creates via API)
+
+stateMachines:
+  - name: Order
+    initialState: Created
+```
+
+**Behavior:**
+- ❌ No instance created on startup (unless autoCreateEntryPoint: true)
+- ✅ Create instances via API: `POST /api/components/OrderComponent/instances`
+- ✅ Dashboard "New Instance" button available for manual creation
+
+#### Creating Instances via API
+
+For **multiple mode** components, create instances programmatically:
 
-### 8. Multiple Transitions with Guards (First Matching Wins)
+```bash
+# Create Order instance with context
+curl -X POST http://localhost:3000/api/components/OrderComponent/instances \
+  -H "Content-Type: application/json" \
+  -d '{
+    "machineName": "Order",
+    "context": {
+      "orderId": "ORD-123",
+      "amount": 99.99,
+      "customerId": "CUST-456"
+    }
+  }'
+```
+
+Or via the dashboard UI: Click the **"+ New"** button in the Instances sidebar.
 
-When multiple transitions from the same state use the same event, **guards differentiate them**.
+#### Summary Table
 
-The **first transition with passing guards wins**:
+| Mode | autoCreateEntryPoint | Behavior |
+|------|---------------------|----------|
+| `singleton` | `true` (default) | One instance auto-created, API rejects new ones |
+| `singleton` | `false` | One instance allowed, created via API |
+| `multiple` | `true` | One instance auto-created, more via API |
+| `multiple` | `false` (default) | No auto-create, all via API or dashboard |
+
+### 7. Broadcast with Property Filters (from Triggered Methods)
+
+Triggered methods can send events to **specific instances** using property filters:
+
+**YAML** — declare the method name on the transition:
 
 ```yaml
 transitions:
-  # TRANSITION 1: Stay in PartiallyExecuted
   - from: PartiallyExecuted
     to: PartiallyExecuted
     event: EXECUTION_NOTIFICATION
-    triggeredMethod: accumulateExecution
-    guards:
-      - type: custom
-        condition: "context.executedQuantity < context.totalQuantity"
+    type: triggerable
+    triggeredMethod: notifyRiskMonitors
+```
 
-  # TRANSITION 2: Move to FullyExecuted
-  - from: PartiallyExecuted
-    to: FullyExecuted
-    event: EXECUTION_NOTIFICATION
-    triggeredMethod: accumulateExecution
-    guards:
-      - type: context
-        property: executedQuantity
-        operator: ">="
-        value: "{{totalQuantity}}"
+**TypeScript** — implement the handler:
+
+```typescript
+runtime.on('triggered_method', async ({ method, event, context, sender }) => {
+  if (method === 'notifyRiskMonitors') {
+    // Update local context
+    context.executedQuantity += event.payload.quantity;
+
+    // BROADCAST to risk monitors for THIS CUSTOMER ONLY
+    const count = await sender.broadcast(
+      'RiskMonitor',           // Target machine
+      {
+        type: 'ORDER_UPDATE',
+        payload: {
+          orderId: context.orderId,
+          executedQuantity: context.executedQuantity
+        },
+        timestamp: Date.now()
+      },
+      [
+        // FILTERS: Property-based targeting
+        { property: 'customerId', value: context.customerId },
+        { property: 'assetClass', operator: '===', value: 'EQUITY' }
+      ],
+      'Monitoring'             // Target state (optional)
+    );
+
+    console.log(`Notified ${count} risk monitor(s)`);
+  }
+});
 ```
 
-**Execution order:**
-1. Event arrives
-2. Triggered method runs **once** (updates context)
-3. Guards evaluated **in YAML order**
-4. First matching guard → transition fires
-5. Other transitions skipped
+**Available sender methods:**
+- `sender.sendToSelf(event)` - Send event to current instance
+- `sender.sendTo(instanceId, event)` - Send to specific instance
+- `sender.sendToComponent(componentName, instanceId, event)` - Cross-component to specific instance
+- `sender.broadcast(machineName, event, currentState?, componentName?)` - Broadcast to instances
+- `sender.createInstance(machineName, context)` - Create new instance
+- `sender.createInstanceInComponent(componentName, machineName, context)` - Cross-component instance creation
 
-**Key points:**
-- Triggered method runs **before** guards (can update context)
-- Transitions defined in YAML are evaluated in order
-- First match wins - other transitions not tried
-- Useful for accumulation patterns (partial vs. full execution)
+Instance filtering is done via `matchingRules` on the target transition in YAML, not in the sender call.
 
-See: `EVENT-ACCUMULATION-GUIDE.md` for complete guide.
+See: `examples/advanced-patterns-demo.yaml`
 
 ---
 
@@ -379,20 +433,6 @@ stateMachines:
 xcomponent-ai serve order.yaml payment.yaml
 ```
 
-### Guards
-
-Conditional transitions:
-
-```yaml
-transitions:
-  - from: Pending
-    to: Approved
-    event: APPROVE
-    guards:
-      - keys: [amount, clientId]  # Required fields
-      - customFunction: "event.payload.amount <= 100000"  # Max limit
-```
-
 ### Payload Templating
 
 Pass context data between machines:
@@ -444,20 +484,7 @@ states:
           address: "{{shippingAddress}}"
 ```
 
-### Pattern 3: Compliance with Guards
-
-```yaml
-transitions:
-  - from: Submitted
-    to: Approved
-    event: APPROVE
-    guards:
-      - keys: [complianceCheck, riskScore]
-      - customFunction: "event.payload.riskScore < 70"
-      - customFunction: "event.payload.complianceCheck === 'PASSED'"
-```
-
-### Pattern 4: Timeout Transitions
+### Pattern 3: Timeout Transitions
 
 ```yaml
 transitions:
@@ -538,10 +565,9 @@ describe('OrderEntry FSM', () => {
 1. **Start with YAML** - Define FSM first, code second
 2. **Use contextSchema** - Let dashboard generate forms automatically
 3. **Leverage cascadingRules** - Reduce orchestration code
-4. **Add guards** - Encode business rules in YAML
-5. **Test FSM** - Write tests for state transitions
-6. **Use serve for demos** - Quick prototypes with dashboard
-7. **Use programmatic mode for production** - More control, better scaling
+4. **Test FSM** - Write tests for state transitions
+5. **Use serve for demos** - Quick prototypes with dashboard
+6. **Use programmatic mode for production** - More control, better scaling
 
 ---
 

package/QUICKSTART.md

@@ -199,12 +199,29 @@ xcomponent-ai init loan-approval
 cd loan-approval
 
 # Edit fsm/LoanApprovalComponent.yaml
-# (Add your states, transitions, guards)
+# (Add your states, transitions)
 
 # Test your FSM
 xcomponent-ai serve fsm/LoanApprovalComponent.yaml
 ```
 
+## 🏗️ XComponent Pattern (Advanced)
+
+For orchestrating multiple state machines with automatic instance creation:
+
+```bash
+# Use the XComponent pattern demo
+xcomponent-ai serve examples/xcomponent-pattern-demo.yaml
+```
+
+This demonstrates:
+- **Entry Point** auto-created on startup (⭐ OrderManager)
+- **Inter-machine transitions** creating new instances (green arrows in dashboard)
+- **Auto-deallocation** of completed instances
+- **Component View** showing all machines and their connections
+
+See [XCOMPONENT-PATTERN.md](./XCOMPONENT-PATTERN.md) for complete guide.
+
 ## 🎓 Next Steps
 
 - 📖 Read the [Framework Guide](./LLM_FRAMEWORK_GUIDE.md) to understand concepts