yaml-flow 3.0.0 → 3.1.1

package/examples/batch/batch-step-machine.ts

@@ -0,0 +1,121 @@
+/**
+ * Batch Example: Process tickets through a Step Machine flow
+ *
+ * Demonstrates:
+ *  - batch() with step-machine processor
+ *  - Concurrency control (3 slots)
+ *  - Progress tracking
+ *  - Mixed success/failure handling
+ *
+ * Run with: npx tsx examples/batch/batch-step-machine.ts
+ */
+
+import { batch } from '../../src/batch/index.js';
+import { createStepMachine } from '../../src/step-machine/index.js';
+import type { StepFlowConfig, StepHandler } from '../../src/step-machine/types.js';
+
+// ============================================================================
+// 1. Define a simple flow
+// ============================================================================
+
+const ticketFlow: StepFlowConfig = {
+  id: 'support-ticket',
+  settings: { start_step: 'classify', max_total_steps: 10 },
+  steps: {
+    classify: {
+      produces_data: ['category'],
+      transitions: { billing: 'handle', technical: 'handle', unknown: 'escalate' },
+    },
+    handle: {
+      expects_data: ['category'],
+      produces_data: ['resolution'],
+      transitions: { resolved: 'done', failed: 'escalate' },
+    },
+    escalate: {
+      expects_data: ['category'],
+      produces_data: ['escalation_id'],
+      transitions: { done: 'done' },
+    },
+  },
+  terminal_states: {
+    done: { return_intent: 'resolved', return_artifacts: ['resolution', 'escalation_id'] },
+  },
+};
+
+const handlers: Record<string, StepHandler> = {
+  classify: async (input) => {
+    const msg = (input.message as string) || '';
+    if (msg.includes('bill') || msg.includes('charge')) return { result: 'billing', data: { category: 'billing' } };
+    if (msg.includes('crash') || msg.includes('error')) return { result: 'technical', data: { category: 'technical' } };
+    return { result: 'unknown', data: { category: 'unknown' } };
+  },
+  handle: async (input) => {
+    // Simulate occasional failure
+    if (Math.random() < 0.2) return { result: 'failed' };
+    return { result: 'resolved', data: { resolution: `Resolved ${input.category} issue` } };
+  },
+  escalate: async (input) => {
+    return { result: 'done', data: { escalation_id: `ESC-${Date.now()}` } };
+  },
+};
+
+// ============================================================================
+// 2. Batch of tickets
+// ============================================================================
+
+const tickets = [
+  { id: 'T-001', message: 'I was double-charged on my bill' },
+  { id: 'T-002', message: 'App crashes on startup' },
+  { id: 'T-003', message: 'How do I change my password?' },
+  { id: 'T-004', message: 'Billing error on invoice #1234' },
+  { id: 'T-005', message: 'Error 500 on checkout page' },
+  { id: 'T-006', message: 'Cannot access my account' },
+  { id: 'T-007', message: 'Refund not processed on my bill' },
+  { id: 'T-008', message: 'App throws error on login' },
+];
+
+// ============================================================================
+// 3. Run batch
+// ============================================================================
+
+async function main() {
+  console.log(`Processing ${tickets.length} tickets with 3 concurrent slots\n`);
+
+  const result = await batch(tickets, {
+    concurrency: 3,
+
+    processor: async (ticket) => {
+      const machine = createStepMachine(ticketFlow, handlers);
+      return machine.run({ message: ticket.message });
+    },
+
+    onItemComplete: (ticket, flowResult) => {
+      console.log(`  ✓ ${ticket.id}: ${flowResult.intent} — ${flowResult.stepHistory.join(' → ')}`);
+    },
+
+    onItemError: (ticket, error) => {
+      console.log(`  ✗ ${ticket.id}: ${error.message}`);
+    },
+
+    onProgress: (p) => {
+      if (p.percent % 25 === 0) {
+        console.log(`  [${p.percent}%] ${p.completed + p.failed}/${p.total} done, ${p.active} active`);
+      }
+    },
+  });
+
+  console.log(`\n${'='.repeat(50)}`);
+  console.log(`Results: ${result.completed} completed, ${result.failed} failed (${result.durationMs}ms)`);
+
+  // Show per-item breakdown
+  for (const item of result.items) {
+    const ticket = item.item;
+    if (item.status === 'completed') {
+      console.log(`  ${ticket.id}: ${item.result?.intent} (${item.durationMs}ms)`);
+    } else {
+      console.log(`  ${ticket.id}: FAILED — ${item.error?.message}`);
+    }
+  }
+}
+
+main().catch(console.error);

package/examples/browser/index.html

@@ -0,0 +1,367 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>yaml-flow Browser Example</title>
+    <style>
+        * { box-sizing: border-box; }
+        body { 
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            max-width: 800px; 
+            margin: 40px auto; 
+            padding: 20px;
+            background: #f5f5f5;
+        }
+        h1 { color: #333; }
+        .card {
+            background: white;
+            border-radius: 8px;
+            padding: 20px;
+            margin: 20px 0;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }
+        .step-list {
+            display: flex;
+            gap: 10px;
+            flex-wrap: wrap;
+            margin: 10px 0;
+        }
+        .step {
+            padding: 8px 16px;
+            border-radius: 20px;
+            background: #e0e0e0;
+            font-size: 14px;
+        }
+        .step.active {
+            background: #2196F3;
+            color: white;
+        }
+        .step.completed {
+            background: #4CAF50;
+            color: white;
+        }
+        button {
+            background: #2196F3;
+            color: white;
+            border: none;
+            padding: 12px 24px;
+            border-radius: 6px;
+            cursor: pointer;
+            font-size: 16px;
+            margin: 5px;
+        }
+        button:hover { background: #1976D2; }
+        button:disabled { background: #ccc; cursor: not-allowed; }
+        .log {
+            background: #263238;
+            color: #aed581;
+            padding: 15px;
+            border-radius: 6px;
+            font-family: 'Consolas', monospace;
+            font-size: 13px;
+            max-height: 300px;
+            overflow-y: auto;
+        }
+        .log-entry { margin: 5px 0; }
+        .log-entry.error { color: #ef5350; }
+        .log-entry.transition { color: #64B5F6; }
+        .result {
+            padding: 15px;
+            border-radius: 6px;
+            margin-top: 15px;
+        }
+        .result.success { background: #C8E6C9; }
+        .result.error { background: #FFCDD2; }
+        input {
+            padding: 10px;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            font-size: 16px;
+            width: 200px;
+        }
+    </style>
+</head>
+<body>
+    <h1>🔄 yaml-flow Browser Demo</h1>
+    
+    <div class="card">
+        <h2>Simple Greeting Flow</h2>
+        <p>Enter your name and run the flow to see it in action.</p>
+        
+        <div style="margin: 15px 0;">
+            <input type="text" id="nameInput" placeholder="Enter your name" value="Developer">
+            <button onclick="runFlow()">Run Flow</button>
+            <button onclick="clearLog()">Clear Log</button>
+        </div>
+
+        <h3>Steps</h3>
+        <div class="step-list" id="stepList">
+            <div class="step" data-step="greet">greet</div>
+            <div class="step" data-step="validate">validate</div>
+            <div class="step" data-step="personalize">personalize</div>
+            <div class="step" data-step="success_state">✓ success</div>
+        </div>
+    </div>
+
+    <div class="card">
+        <h3>Execution Log</h3>
+        <div class="log" id="log"></div>
+        
+        <div id="result"></div>
+    </div>
+
+    <script type="module">
+        // Import from CDN (in production) or local build
+        // For this demo, we'll inline a simplified version
+        
+        // ============= Inline yaml-flow (simplified for demo) =============
+        
+        class MemoryStore {
+            constructor() {
+                this.runs = new Map();
+                this.data = new Map();
+            }
+            async saveRunState(runId, state) { this.runs.set(runId, {...state}); }
+            async loadRunState(runId) { return this.runs.get(runId) || null; }
+            async deleteRunState(runId) { this.runs.delete(runId); this.data.delete(runId); }
+            async setData(runId, key, value) {
+                if (!this.data.has(runId)) this.data.set(runId, {});
+                this.data.get(runId)[key] = value;
+            }
+            async getData(runId, key) { return this.data.get(runId)?.[key]; }
+            async getAllData(runId) { return {...(this.data.get(runId) || {})}; }
+            async clearData(runId) { this.data.delete(runId); }
+        }
+
+        class FlowEngine {
+            constructor(flow, handlers, options = {}) {
+                this.flow = flow;
+                this.handlers = handlers;
+                this.store = options.store || new MemoryStore();
+                this.components = options.components || {};
+                this.options = options;
+            }
+
+            async run(initialData = {}) {
+                const runId = crypto.randomUUID();
+                const startedAt = Date.now();
+                
+                const runState = {
+                    runId,
+                    currentStep: this.flow.settings.start_step,
+                    status: 'running',
+                    stepHistory: [],
+                    iterationCounts: {},
+                    retryCounts: {},
+                    startedAt,
+                    updatedAt: startedAt,
+                };
+
+                await this.store.saveRunState(runId, runState);
+                for (const [key, value] of Object.entries(initialData)) {
+                    await this.store.setData(runId, key, value);
+                }
+
+                let iterations = 0;
+                const maxSteps = this.flow.settings.max_total_steps || 100;
+
+                while (iterations < maxSteps) {
+                    const currentStep = runState.currentStep;
+
+                    // Check terminal state
+                    const terminalState = this.flow.terminal_states[currentStep];
+                    if (terminalState) {
+                        const allData = await this.store.getAllData(runId);
+                        return {
+                            runId,
+                            status: 'completed',
+                            intent: terminalState.return_intent,
+                            data: this.extractReturnData(terminalState.return_artifacts, allData),
+                            finalStep: currentStep,
+                            stepHistory: runState.stepHistory,
+                            durationMs: Date.now() - startedAt,
+                        };
+                    }
+
+                    const stepConfig = this.flow.steps[currentStep];
+                    const handler = this.handlers[currentStep];
+                    
+                    // Build input
+                    const allData = await this.store.getAllData(runId);
+                    const input = stepConfig.expects_data 
+                        ? Object.fromEntries(stepConfig.expects_data.map(k => [k, allData[k]]))
+                        : allData;
+
+                    // Execute
+                    this.options.onStep?.(currentStep, 'start');
+                    const result = await handler(input, { runId, stepName: currentStep, components: this.components, store: this.store });
+                    this.options.onStep?.(currentStep, result.result);
+
+                    // Store output
+                    if (result.data) {
+                        for (const [key, value] of Object.entries(result.data)) {
+                            await this.store.setData(runId, key, value);
+                        }
+                    }
+
+                    // Transition
+                    const nextStep = stepConfig.transitions[result.result];
+                    this.options.onTransition?.(currentStep, nextStep);
+                    
+                    runState.stepHistory.push(currentStep);
+                    runState.currentStep = nextStep;
+                    iterations++;
+                }
+
+                return { runId, status: 'max_iterations', data: {}, stepHistory: runState.stepHistory };
+            }
+
+            extractReturnData(artifacts, allData) {
+                if (!artifacts || artifacts === false) return {};
+                if (typeof artifacts === 'string') return { [artifacts]: allData[artifacts] };
+                if (Array.isArray(artifacts)) return Object.fromEntries(artifacts.map(k => [k, allData[k]]));
+                return allData;
+            }
+        }
+        
+        // ============= Flow Definition =============
+        
+        const flow = {
+            settings: {
+                start_step: 'greet',
+                max_total_steps: 10
+            },
+            steps: {
+                greet: {
+                    produces_data: ['greeting', 'user_name'],
+                    transitions: { success: 'validate', failure: 'error_state' }
+                },
+                validate: {
+                    expects_data: ['greeting', 'user_name'],
+                    produces_data: ['is_valid'],
+                    transitions: { success: 'personalize', invalid: 'error_state', failure: 'error_state' }
+                },
+                personalize: {
+                    expects_data: ['greeting', 'user_name'],
+                    produces_data: ['final_message'],
+                    transitions: { success: 'success_state', failure: 'error_state' }
+                }
+            },
+            terminal_states: {
+                success_state: { return_intent: 'success', return_artifacts: ['final_message', 'user_name'] },
+                error_state: { return_intent: 'error', return_artifacts: false }
+            }
+        };
+
+        // ============= Step Handlers =============
+        
+        const handlers = {
+            async greet(input) {
+                const userName = input.initial_name || 'World';
+                await sleep(300); // Simulate async work
+                return {
+                    result: 'success',
+                    data: { greeting: 'Hello', user_name: userName }
+                };
+            },
+            
+            async validate(input) {
+                const { greeting, user_name } = input;
+                await sleep(200);
+                const isValid = greeting && user_name;
+                return {
+                    result: isValid ? 'success' : 'invalid',
+                    data: { is_valid: isValid }
+                };
+            },
+            
+            async personalize(input) {
+                const { greeting, user_name } = input;
+                await sleep(200);
+                return {
+                    result: 'success',
+                    data: { final_message: `${greeting}, ${user_name}! Welcome to yaml-flow in the browser! 🎉` }
+                };
+            }
+        };
+
+        function sleep(ms) {
+            return new Promise(resolve => setTimeout(resolve, ms));
+        }
+
+        // ============= UI Functions =============
+        
+        const logEl = document.getElementById('log');
+        const resultEl = document.getElementById('result');
+        const stepEls = document.querySelectorAll('.step');
+
+        function log(message, type = '') {
+            const entry = document.createElement('div');
+            entry.className = `log-entry ${type}`;
+            entry.textContent = `[${new Date().toLocaleTimeString()}] ${message}`;
+            logEl.appendChild(entry);
+            logEl.scrollTop = logEl.scrollHeight;
+        }
+
+        function updateStep(stepName, status) {
+            stepEls.forEach(el => {
+                if (el.dataset.step === stepName) {
+                    el.classList.remove('active', 'completed');
+                    el.classList.add(status);
+                }
+            });
+        }
+
+        function resetSteps() {
+            stepEls.forEach(el => el.classList.remove('active', 'completed'));
+        }
+
+        window.clearLog = function() {
+            logEl.innerHTML = '';
+            resultEl.innerHTML = '';
+            resetSteps();
+        };
+
+        window.runFlow = async function() {
+            resetSteps();
+            resultEl.innerHTML = '';
+            
+            const name = document.getElementById('nameInput').value || 'World';
+            log(`Starting flow with name: "${name}"`);
+
+            const engine = new FlowEngine(flow, handlers, {
+                store: new MemoryStore(),
+                onStep: (step, status) => {
+                    log(`Step [${step}]: ${status}`);
+                    updateStep(step, status === 'start' ? 'active' : 'completed');
+                },
+                onTransition: (from, to) => {
+                    log(`Transition: ${from} → ${to}`, 'transition');
+                }
+            });
+
+            try {
+                const result = await engine.run({ initial_name: name });
+                
+                log(`Flow completed: ${result.intent}`);
+                updateStep(result.finalStep, 'completed');
+
+                resultEl.innerHTML = `
+                    <div class="result ${result.intent === 'success' ? 'success' : 'error'}">
+                        <strong>Result:</strong> ${result.intent}<br>
+                        <strong>Message:</strong> ${result.data.final_message || 'N/A'}<br>
+                        <strong>Duration:</strong> ${result.durationMs}ms<br>
+                        <strong>Steps:</strong> ${result.stepHistory.join(' → ')} → ${result.finalStep}
+                    </div>
+                `;
+            } catch (error) {
+                log(`Error: ${error.message}`, 'error');
+                resultEl.innerHTML = `<div class="result error">Error: ${error.message}</div>`;
+            }
+        };
+
+        log('yaml-flow browser demo loaded. Click "Run Flow" to start.');
+    </script>
+</body>
+</html>

package/examples/continuous-event-graph/live-cards-board.ts

@@ -0,0 +1,215 @@
+/**
+ * Live Cards → Reactive Graph Example: Board Dashboard
+ *
+ * Demonstrates `liveCardsToReactiveGraph` — the bridge that converts
+ * live card / source JSON definitions into a fully wired ReactiveGraph.
+ *
+ * This example shows both overloads:
+ *   1. Flat array of cards  → reactive graph
+ *   2. LiveBoard object     → reactive graph (with board-level id/settings)
+ *
+ * Features exercised:
+ *  - Source nodes with pre-populated state (static data feeds)
+ *  - Custom sourceHandlers (simulated API fetch)
+ *  - Card nodes with compute expressions (sum, avg, count, template)
+ *  - Cross-card data flow via data.requires / data.provides
+ *  - LiveBoard overload — board.id, board.settings forwarded to GraphConfig
+ *  - validateReactiveGraph on the resulting graph
+ *
+ * Run with: npx tsx examples/continuous-event-graph/live-cards-board.ts
+ */
+
+import {
+  liveCardsToReactiveGraph,
+  validateReactiveGraph,
+} from '../../src/continuous-event-graph/index.js';
+import type { LiveCard, LiveBoard } from '../../src/continuous-event-graph/index.js';
+
+// ============================================================================
+// 1. Flat cards array → Reactive Graph
+// ============================================================================
+
+console.log('=== Part 1: Flat cards array ===\n');
+
+const cards: LiveCard[] = [
+  {
+    id: 'market-feed',
+    type: 'source',
+    meta: { title: 'Live Market Prices' },
+    state: { prices: [142.5, 305.8, 89.2, 211.0, 178.3] },
+    source: { kind: 'static', bindTo: 'state.prices' },
+  },
+  {
+    id: 'stats',
+    type: 'card',
+    meta: { title: 'Price Statistics' },
+    state: {},
+    data: { requires: ['market-feed'] },
+    compute: {
+      total: { fn: 'sum', input: 'state.market-feed.prices' },
+      avg: { fn: 'avg', input: 'state.market-feed.prices' },
+      count: { fn: 'count', input: 'state.market-feed.prices' },
+    },
+  },
+  {
+    id: 'summary',
+    type: 'card',
+    meta: { title: 'Summary Label' },
+    state: {},
+    data: { requires: ['stats'] },
+    compute: {
+      label: {
+        fn: 'template',
+        input: 'state.stats',
+        format: '{{count}} stocks — total ${{total}}, avg ${{avg}}',
+      },
+    },
+  },
+];
+
+const flatResult = liveCardsToReactiveGraph(cards, {
+});
+
+console.log('Graph ID:', flatResult.config.id);
+console.log('Tasks:', Object.keys(flatResult.config.tasks).join(', '));
+console.log('Pushing trigger event...\n');
+
+flatResult.graph.push({
+  type: 'inject-tokens',
+  tokens: [],
+  timestamp: new Date().toISOString(),
+});
+
+await sleep(1000);
+
+const flatState = flatResult.graph.getState();
+for (const [name, task] of Object.entries(flatState.state.tasks)) {
+  const hash = task.lastDataHash ? ` (hash: ${task.lastDataHash.slice(0, 8)}…)` : '';
+  console.log(`  ${name}: ${task.status}${hash}`);
+}
+console.log(`  Outputs: [${flatState.state.availableOutputs.join(', ')}]`);
+
+flatResult.graph.dispose();
+
+// ============================================================================
+// 2. LiveBoard → Reactive Graph
+// ============================================================================
+
+console.log('\n=== Part 2: LiveBoard overload ===\n');
+
+const board: LiveBoard = {
+  id: 'portfolio-board',
+  title: 'Portfolio Analytics Dashboard',
+  mode: 'board',
+  positions: {
+    'equity-feed':   { x: 0, y: 0, w: 300, h: 200 },
+    'bond-feed':     { x: 320, y: 0, w: 300, h: 200 },
+    'portfolio-mix': { x: 160, y: 240, w: 300, h: 200 },
+    'risk-summary':  { x: 160, y: 480, w: 300, h: 200 },
+  },
+  settings: {
+    completion: 'manual',
+  },
+  nodes: [
+    {
+      id: 'equity-feed',
+      type: 'source',
+      meta: { title: 'Equity Prices' },
+      state: {},
+      source: { kind: 'api', bindTo: 'state.raw', url_template: 'https://api.example.com/equity' },
+    },
+    {
+      id: 'bond-feed',
+      type: 'source',
+      meta: { title: 'Bond Yields' },
+      state: { yields: [3.2, 4.1, 2.8, 5.0] },
+      source: { kind: 'static', bindTo: 'state.yields' },
+    },
+    {
+      id: 'portfolio-mix',
+      type: 'card',
+      meta: { title: 'Portfolio Mix Calculator' },
+      state: {},
+      data: { requires: ['equity-feed', 'bond-feed'] },
+      compute: {
+        equity_total: { fn: 'sum', input: 'state.equity-feed.prices' },
+        bond_total: { fn: 'sum', input: 'state.bond-feed.yields' },
+      },
+    },
+    {
+      id: 'risk-summary',
+      type: 'card',
+      meta: { title: 'Risk Summary' },
+      state: {},
+      data: { requires: ['portfolio-mix'] },
+      compute: {
+        label: {
+          fn: 'template',
+          input: 'state.portfolio-mix',
+          format: 'Equities: ${{equity_total}} | Bonds: {{bond_total}}%',
+        },
+      },
+    },
+  ],
+};
+
+const boardResult = liveCardsToReactiveGraph(board, {
+  // Custom handler for the API-based source — simulates a fetch
+  sourceHandlers: {
+    'equity-feed': async ({ callbackToken }) => {
+      console.log('  [equity-feed] Simulating API fetch...');
+      await sleep(100);
+      // Use the graph to resolve — bridge wires this up automatically
+      boardResult.graph.resolveCallback(callbackToken, { prices: [155.2, 310.4, 92.1, 220.5] });
+      return 'task-initiated' as const;
+    },
+  },
+});
+
+console.log('Board ID:',     boardResult.config.id);
+console.log('Completion:',   boardResult.config.settings.completion);
+console.log('Tasks:',        Object.keys(boardResult.config.tasks).join(', '));
+console.log('Cards in map:', boardResult.cards.size);
+console.log();
+
+// Push and run
+boardResult.graph.push({
+  type: 'inject-tokens',
+  tokens: [],
+  timestamp: new Date().toISOString(),
+});
+
+await sleep(1500);
+
+const boardState = boardResult.graph.getState();
+console.log('Final task states:');
+for (const [name, task] of Object.entries(boardState.state.tasks)) {
+  const hash = task.lastDataHash ? ` (hash: ${task.lastDataHash.slice(0, 8)}…)` : '';
+  console.log(`  ${name}: ${task.status} (executed ${task.executionCount}x)${hash}`);
+}
+console.log(`  Outputs: [${boardState.state.availableOutputs.join(', ')}]`);
+
+// ============================================================================
+// 3. Validate the reactive graph
+// ============================================================================
+
+console.log('\n=== Validation ===');
+const validation = validateReactiveGraph({
+  graph: boardResult.graph,
+  handlers: boardResult.handlers,
+});
+console.log(`  Valid: ${validation.valid} (${validation.issues.length} issues)`);
+for (const issue of validation.issues) {
+  console.log(`    [${issue.severity}] ${issue.code}: ${issue.message}`);
+}
+
+boardResult.graph.dispose();
+console.log('\nDone.');
+
+// ============================================================================
+// Util
+// ============================================================================
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}