yaml-flow 2.4.0 → 2.6.0

package/README.md

@@ -983,6 +983,208 @@ const restored = restore(data);     // → LiveGraph (validates shape)
 
 ---
 
+## LLM Inference
+
+Pluggable AI-assisted completion detection. The caller provides the LLM via an `InferenceAdapter` — yaml-flow builds the prompt, parses the response, and applies the results. Core stays pure; inference is opt-in.
+
+```typescript
+import {
+  buildInferencePrompt, inferCompletions, applyInferences, inferAndApply,
+} from 'yaml-flow/inference';
+```
+
+### Inference Hints on Nodes
+
+Add optional `inference` metadata to any `TaskConfig`:
+
+```typescript
+const config = {
+  settings: { completion: 'all-tasks' },
+  tasks: {
+    'infra-provisioned': {
+      provides: ['infra-ready'],
+      inference: {
+        criteria: 'All Azure resources provisioned successfully',
+        keywords: ['azure', 'deployment', 'provisioning'],
+        suggestedChecks: ['scan logs for "Deployment Succeeded"'],
+        autoDetectable: true,   // LLM will analyze this node
+      },
+    },
+    'app-deployed': {
+      requires: ['infra-ready'],
+      provides: ['app-ready'],
+      inference: {
+        criteria: 'Health check returns HTTP 200',
+        autoDetectable: true,
+      },
+    },
+    'monitoring': {                         // no inference → LLM skips it
+      requires: ['app-ready'],
+      provides: ['monitored'],
+    },
+  },
+};
+```
+
+### Pluggable Adapter
+
+Implement one method — `analyze(prompt) → string`:
+
+```typescript
+import type { InferenceAdapter } from 'yaml-flow/inference';
+
+// OpenAI
+const openaiAdapter: InferenceAdapter = {
+  analyze: async (prompt) => {
+    const res = await openai.chat.completions.create({
+      model: 'gpt-4o', messages: [{ role: 'user', content: prompt }],
+    });
+    return res.choices[0].message.content ?? '[]';
+  },
+};
+
+// Anthropic
+const claudeAdapter: InferenceAdapter = {
+  analyze: async (prompt) => {
+    const res = await anthropic.messages.create({
+      model: 'claude-sonnet-4-20250514', max_tokens: 1024,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return res.content[0].type === 'text' ? res.content[0].text : '[]';
+  },
+};
+
+// Any HTTP endpoint
+const customAdapter: InferenceAdapter = {
+  analyze: async (prompt) => {
+    const res = await fetch('https://my-llm/analyze', {
+      method: 'POST', body: JSON.stringify({ prompt }),
+    });
+    return (await res.json()).response;
+  },
+};
+```
+
+### Built-in Adapter Factories
+
+Zero-boilerplate adapters for common patterns:
+
+```typescript
+import { createCliAdapter, createHttpAdapter } from 'yaml-flow/inference';
+
+// Ollama via HTTP
+const ollama = createHttpAdapter({
+  url: 'http://localhost:11434/api/generate',
+  buildBody: (prompt) => ({ model: 'llama3', prompt, stream: false }),
+  extractResponse: (json) => json.response,
+});
+
+// Ollama via CLI
+const ollamaCli = createCliAdapter({
+  command: 'ollama',
+  args: (prompt) => ['run', 'llama3', prompt],
+});
+
+// Simon Willison's llm CLI (stdin mode for long prompts)
+const llm = createCliAdapter({
+  command: 'llm',
+  args: () => ['--no-stream'],
+  stdin: true,
+});
+
+// Custom Python script
+const custom = createCliAdapter({
+  command: 'python',
+  args: (prompt) => ['scripts/infer.py', '--json', prompt],
+  cwd: '/path/to/project',
+  env: { MODEL: 'gpt-4o' },
+  timeout: 60_000,
+});
+```
+
+**`createCliAdapter(options)`** — spawns a child process, captures stdout:
+| Option | Type | Description |
+|--------|------|-------------|
+| `command` | `string` | Executable to run (`ollama`, `llm`, `python`, `gh`, …) |
+| `args` | `(prompt) => string[]` | Build argument list from the prompt |
+| `stdin` | `boolean` | Pipe prompt via stdin instead of args (default: `false`) |
+| `timeout` | `number` | Kill after N ms (default: `30000`) |
+| `cwd` | `string` | Working directory |
+| `env` | `Record<string, string>` | Extra environment variables |
+
+**`createHttpAdapter(options)`** — POSTs to an HTTP endpoint:
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | `string` | Endpoint URL |
+| `headers` | `Record<string, string>` | Request headers |
+| `buildBody` | `(prompt) => object` | Build request body (default: `{ prompt }`) |
+| `extractResponse` | `(json) => string` | Extract text from response JSON |
+| `timeout` | `number` | Abort after N ms (default: `30000`) |
+```
+
+### Three APIs: Build → Suggest → Apply
+
+```typescript
+import { createLiveGraph } from 'yaml-flow/continuous-event-graph';
+import { buildInferencePrompt, inferCompletions, applyInferences } from 'yaml-flow/inference';
+
+let live = createLiveGraph(config);
+
+// 1. BUILD: Generate the prompt (pure, sync)
+const prompt = buildInferencePrompt(live, {
+  context: 'Deployment log: "Deployment Succeeded", health check: HTTP 200',
+});
+
+// 2. SUGGEST: Ask the LLM (async)
+const result = await inferCompletions(live, adapter, {
+  threshold: 0.8,
+  context: 'Deployment log: ...',
+});
+result.suggestions;  // [{ taskName, confidence, reasoning, detectionMethod }]
+
+// 3. APPLY: Accept high-confidence suggestions (pure, sync)
+live = applyInferences(live, result, 0.8);  // only applies >= 80% confidence
+```
+
+### One-Shot Convenience
+
+```typescript
+import { inferAndApply } from 'yaml-flow/inference';
+
+const { live: updated, applied, skipped, inference } = await inferAndApply(
+  live, adapter, { threshold: 0.8, context: 'deployment logs...' }
+);
+
+console.log('Auto-completed:', applied.map(s => s.taskName));
+console.log('Skipped (low confidence):', skipped.map(s => `${s.taskName} (${s.confidence})`));
+```
+
+### Inference API Reference
+
+| Function | Description |
+|---|---|
+| `buildInferencePrompt(live, opts?)` | Build LLM prompt from graph state (pure, sync) |
+| `inferCompletions(live, adapter, opts?)` | Ask LLM to suggest completions (async) |
+| `applyInferences(live, result, threshold?)` | Apply suggestions above threshold (pure, sync) |
+| `inferAndApply(live, adapter, opts?)` | Infer + apply in one step (async, convenience) |
+| `createCliAdapter(opts)` | Factory: adapter that spawns a CLI command |
+| `createHttpAdapter(opts)` | Factory: adapter that POSTs to an HTTP endpoint |
+
+### Inference Types
+
+| Type | Description |
+|---|---|
+| `InferenceAdapter` | `{ analyze(prompt: string): Promise<string> }` — pluggable LLM bridge |
+| `InferenceHints` | `criteria`, `keywords`, `suggestedChecks`, `autoDetectable` on a TaskConfig |
+| `InferenceOptions` | `threshold`, `scope`, `context`, `systemPrompt` |
+| `InferenceResult` | `suggestions[]`, `promptUsed`, `rawResponse`, `analyzedNodes` |
+| `InferredCompletion` | `taskName`, `confidence`, `reasoning`, `detectionMethod: 'llm-inferred'` |
+| `InferAndApplyResult` | `live`, `inference`, `applied[]`, `skipped[]` |
+| `CliAdapterOptions` | `command`, `args`, `stdin`, `timeout`, `cwd`, `env` |
+| `HttpAdapterOptions` | `url`, `headers`, `buildBody`, `extractResponse`, `timeout` |
+
+---
+
 ## Loading & Exporting Graph Configs
 
 ```typescript
@@ -1041,6 +1243,12 @@ import {
   getUpstream, getDownstream,
 } from 'yaml-flow/continuous-event-graph';
 
+// LLM Inference (AI-assisted completion detection)
+import {
+  buildInferencePrompt, inferCompletions, applyInferences, inferAndApply,
+} from 'yaml-flow/inference';
+import type { InferenceAdapter, InferenceResult, InferenceOptions } from 'yaml-flow/inference';
+
 // Backward compatibility (v1 names → v2)
 import { FlowEngine, createEngine } from 'yaml-flow';  // aliases for StepMachine, createStepMachine
 ```
@@ -1113,6 +1321,10 @@ See the [examples/](./examples) directory:
 | [URL Pipeline](./examples/graph-of-graphs/url-processing-pipeline.ts) | Graph-of-Graphs | Outer event-graph → batch × inner event-graph per item |
 | [Multi-Stage ETL](./examples/graph-of-graphs/multi-stage-etl.ts) | Graph-of-Graphs | Mixed modes: event-graph outer → step-machine + event-graph subs |
 | [Stock Dashboard](./examples/continuous-event-graph/stock-dashboard.ts) | Continuous Event Graph | Runtime mutations, token drain, upstream/downstream, snapshot |
+| [Azure Deployment](./examples/inference/azure-deployment.ts) | Inference | LLM analyzes deployment logs, auto-completes checkpoints |
+| [Data Pipeline](./examples/inference/data-pipeline.ts) | Inference | Iterative inference — evidence arrives in waves |
+| [Pluggable Adapters](./examples/inference/pluggable-adapters.ts) | Inference | OpenAI, Anthropic, Azure, CLI, HTTP adapter factories |
+| [Copilot CLI](./examples/inference/copilot-cli.ts) | Inference | GitHub Copilot CLI as inference adapter via `createCliAdapter` |
 | [Order Processing](./examples/flows/order-processing.yaml) | Step Machine | YAML flow definition |
 | [Browser Demo](./examples/browser/index.html) | Step Machine | In-browser usage |
 

package/browser/card-compute.js

@@ -0,0 +1,446 @@
+// card_compute.js — Pure JSON expression evaluator for LiveCards nodes
+//
+// Isomorphic: works in browser (global), Node.js (require), and ESM (import).
+// No DOM dependency. Usable on both client and server.
+//
+// API:
+//   CardCompute.run(node)                 → mutates node.state with computed values, returns node
+//   CardCompute.eval(expr, node)          → evaluates a single compute_expr, returns value
+//   CardCompute.resolve(node, path)       → deep-get a state path like "state.foo.bar"
+//   CardCompute.registerFunction(name, fn) → add custom compute function
+//   CardCompute.functions                 → read-only map of all registered functions
+//
+// Compute declarations (node.compute):
+//   {
+//     "total_value": { "fn": "sum", "input": "state.raw_quotes" },
+//     "avg_price":   { "fn": "avg", "input": "state.raw_quotes" },
+//     "direction":   { "fn": "if", "cond": { "fn": "gt", "input": ["state.latest", "state.prev"] }, "then": "up", "else": "down" }
+//   }
+
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();                       // Node / CommonJS
+  } else if (typeof define === 'function' && define.amd) {
+    define(factory);                                   // AMD
+  } else {
+    root.CardCompute = factory();                      // Browser global
+  }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  'use strict';
+
+  // ===========================================================================
+  // Deep path utilities
+  // ===========================================================================
+
+  function _deepGet(obj, path) {
+    if (!path || !obj) return undefined;
+    const parts = path.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length; i++) {
+      if (cur == null) return undefined;
+      cur = cur[parts[i]];
+    }
+    return cur;
+  }
+
+  function _deepSet(obj, path, value) {
+    const parts = path.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (cur[parts[i]] == null || typeof cur[parts[i]] !== 'object') cur[parts[i]] = {};
+      cur = cur[parts[i]];
+    }
+    cur[parts[parts.length - 1]] = value;
+  }
+
+  function resolve(node, path) {
+    if (!path) return undefined;
+    return _deepGet(node, path);
+  }
+
+  // ===========================================================================
+  // Built-in function registry
+  // ===========================================================================
+
+  var _fns = {};
+
+  // ---- Aggregates ----
+
+  _fns.sum = function (input, _eval, opts) {
+    var a = Array.isArray(input) ? input : [];
+    return opts.field
+      ? a.reduce(function (s, r) { return s + (Number(r[opts.field]) || 0); }, 0)
+      : a.reduce(function (s, v) { return s + (Number(v) || 0); }, 0);
+  };
+
+  _fns.avg = function (input, _eval, opts) {
+    var s = _fns.sum(input, _eval, opts);
+    var n = Array.isArray(input) ? input.length : 1;
+    return n ? s / n : 0;
+  };
+
+  _fns.min = function (input, _eval, opts) {
+    var a = Array.isArray(input) ? input : [];
+    var vals = opts.field ? a.map(function (r) { return Number(r[opts.field]); }) : a.map(Number);
+    return vals.length ? Math.min.apply(null, vals) : 0;
+  };
+
+  _fns.max = function (input, _eval, opts) {
+    var a = Array.isArray(input) ? input : [];
+    var vals = opts.field ? a.map(function (r) { return Number(r[opts.field]); }) : a.map(Number);
+    return vals.length ? Math.max.apply(null, vals) : 0;
+  };
+
+  _fns.count = function (input) {
+    return Array.isArray(input) ? input.length : (input != null ? 1 : 0);
+  };
+
+  _fns.first = function (input) {
+    return Array.isArray(input) ? input[0] : input;
+  };
+
+  _fns.last = function (input) {
+    return Array.isArray(input) ? input[input.length - 1] : input;
+  };
+
+  // ---- Math ----
+
+  _fns.add = function (input) {
+    var a = Array.isArray(input) ? input : [];
+    return a.reduce(function (s, v) { return s + Number(v); }, 0);
+  };
+
+  _fns.sub = function (input) {
+    var a = Array.isArray(input) ? input : [];
+    return a.length >= 2 ? Number(a[0]) - Number(a[1]) : 0;
+  };
+
+  _fns.mul = function (input) {
+    var a = Array.isArray(input) ? input : [];
+    return a.reduce(function (s, v) { return s * Number(v); }, 1);
+  };
+
+  _fns.div = function (input) {
+    var a = Array.isArray(input) ? input : [];
+    return a.length >= 2 && Number(a[1]) !== 0 ? Number(a[0]) / Number(a[1]) : 0;
+  };
+
+  _fns.round = function (input, _eval, opts) {
+    var decimals = opts.decimals != null ? opts.decimals : 0;
+    var factor = Math.pow(10, decimals);
+    return Math.round(Number(input) * factor) / factor;
+  };
+
+  _fns.abs = function (input) { return Math.abs(Number(input)); };
+
+  _fns.mod = function (input) {
+    var a = Array.isArray(input) ? input : [];
+    return a.length >= 2 ? Number(a[0]) % Number(a[1]) : 0;
+  };
+
+  // ---- Compare ----
+
+  _fns.gt  = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && Number(a[0]) > Number(a[1]); };
+  _fns.gte = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && Number(a[0]) >= Number(a[1]); };
+  _fns.lt  = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && Number(a[0]) < Number(a[1]); };
+  _fns.lte = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && Number(a[0]) <= Number(a[1]); };
+  _fns.eq  = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && a[0] === a[1]; };
+  _fns.neq = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && a[0] !== a[1]; };
+
+  // ---- Logic ----
+
+  _fns.and = function (input) { var a = Array.isArray(input) ? input : []; return a.every(Boolean); };
+  _fns.or  = function (input) { var a = Array.isArray(input) ? input : []; return a.some(Boolean); };
+  _fns.not = function (input) { return !input; };
+  // "if" is handled specially in evalExpr
+
+  // ---- String ----
+
+  _fns.concat = function (input) {
+    var a = Array.isArray(input) ? input : [];
+    return a.map(function (v) { return v != null ? String(v) : ''; }).join('');
+  };
+
+  _fns.upper = function (input) { return String(input || '').toUpperCase(); };
+  _fns.lower = function (input) { return String(input || '').toLowerCase(); };
+
+  _fns.template = function (input, _eval, opts) {
+    var t = String(opts.format || '');
+    if (input && typeof input === 'object') {
+      Object.keys(input).forEach(function (k) {
+        t = t.split('{{' + k + '}}').join(input[k] != null ? String(input[k]) : '');
+      });
+    }
+    return t;
+  };
+
+  _fns.join = function (input, _eval, opts) {
+    var a = Array.isArray(input) ? input : [];
+    var sep = opts.separator != null ? opts.separator : ', ';
+    return a.map(function (v) { return v != null ? String(v) : ''; }).join(sep);
+  };
+
+  _fns.split = function (input, _eval, opts) {
+    var sep = opts.separator != null ? opts.separator : ',';
+    return String(input || '').split(sep).map(function (s) { return s.trim(); });
+  };
+
+  _fns.trim = function (input) { return String(input || '').trim(); };
+
+  // ---- Collection ----
+
+  _fns.pluck = function (input, _eval, opts) {
+    return Array.isArray(input) ? input.map(function (r) { return r[opts.field]; }) : [];
+  };
+
+  _fns.filter = function (input, evalFn, opts) {
+    // Handled specially in evalExpr for the where clause; fallback for simple truthy filter
+    if (!Array.isArray(input)) return [];
+    if (opts.field) return input.filter(function (r) { return !!r[opts.field]; });
+    return input.filter(Boolean);
+  };
+
+  _fns.map = function (input) {
+    // Handled specially in evalExpr for the apply clause
+    return Array.isArray(input) ? input.slice() : [];
+  };
+
+  _fns.sort = function (input, _eval, opts) {
+    var a = Array.isArray(input) ? input.slice() : [];
+    var f = opts.field;
+    var dir = opts.direction === 'desc' ? -1 : 1;
+    if (f) return a.sort(function (x, y) { return x[f] > y[f] ? dir : x[f] < y[f] ? -dir : 0; });
+    return a.sort(function (x, y) { return x > y ? dir : x < y ? -dir : 0; });
+  };
+
+  _fns.slice = function (input, _eval, opts) {
+    return Array.isArray(input) ? input.slice(opts.start || 0, opts.end) : input;
+  };
+
+  _fns.flat = function (input, _eval, opts) {
+    var depth = opts.depth != null ? opts.depth : 1;
+    return Array.isArray(input) ? input.flat(depth) : [input];
+  };
+
+  _fns.unique = function (input) {
+    if (!Array.isArray(input)) return [input];
+    // For primitives, use Set. For objects, use JSON comparison.
+    var seen = new Set();
+    return input.filter(function (v) {
+      var key = typeof v === 'object' ? JSON.stringify(v) : v;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  };
+
+  _fns.group = function (input, _eval, opts) {
+    var a = Array.isArray(input) ? input : [];
+    var g = {};
+    a.forEach(function (r) {
+      var k = String(r[opts.field] || '');
+      if (!g[k]) g[k] = [];
+      g[k].push(r);
+    });
+    return g;
+  };
+
+  _fns.flatten_keys = function (input) {
+    // { a: [1,2], b: [3] } → [{ key: "a", value: 1 }, { key: "a", value: 2 }, { key: "b", value: 3 }]
+    if (!input || typeof input !== 'object' || Array.isArray(input)) return [];
+    var result = [];
+    Object.keys(input).forEach(function (k) {
+      var vals = Array.isArray(input[k]) ? input[k] : [input[k]];
+      vals.forEach(function (v) { result.push({ key: k, value: v }); });
+    });
+    return result;
+  };
+
+  _fns.entries = function (input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) return [];
+    return Object.keys(input).map(function (k) { return { key: k, value: input[k] }; });
+  };
+
+  _fns.from_entries = function (input) {
+    if (!Array.isArray(input)) return {};
+    var obj = {};
+    input.forEach(function (item) { if (item.key != null) obj[item.key] = item.value; });
+    return obj;
+  };
+
+  _fns.length = function (input) {
+    if (Array.isArray(input)) return input.length;
+    if (typeof input === 'string') return input.length;
+    if (input && typeof input === 'object') return Object.keys(input).length;
+    return 0;
+  };
+
+  // ---- Lookup ----
+
+  _fns.get = function (input, _eval, opts) {
+    return _deepGet(input, opts.field || opts.path || '');
+  };
+
+  _fns.default = function (input, _eval, opts) {
+    return input != null ? input : opts.value;
+  };
+
+  _fns.coalesce = function (input) {
+    var a = Array.isArray(input) ? input : [];
+    for (var i = 0; i < a.length; i++) { if (a[i] != null) return a[i]; }
+    return null;
+  };
+
+  // ---- Date ----
+
+  _fns.now = function () { return new Date().toISOString(); };
+
+  _fns.diff_days = function (input) {
+    var a = Array.isArray(input) ? input : [];
+    return a.length >= 2 ? Math.floor((new Date(a[0]) - new Date(a[1])) / 86400000) : 0;
+  };
+
+  _fns.format_date = function (input, _eval, opts) {
+    try {
+      var d = new Date(input);
+      if (opts.format === 'iso') return d.toISOString();
+      if (opts.format === 'date') return d.toLocaleDateString();
+      if (opts.format === 'time') return d.toLocaleTimeString();
+      return d.toLocaleDateString();
+    } catch (e) {
+      return String(input);
+    }
+  };
+
+  _fns.parse_date = function (input) {
+    try { return new Date(input).toISOString(); } catch (e) { return null; }
+  };
+
+  // ---- Type ----
+
+  _fns.to_number = function (input) { return Number(input) || 0; };
+  _fns.to_string = function (input) { return input != null ? String(input) : ''; };
+  _fns.to_bool   = function (input) { return !!input; };
+  _fns.type_of   = function (input) { return Array.isArray(input) ? 'array' : typeof input; };
+  _fns.is_null   = function (input) { return input == null; };
+  _fns.is_empty  = function (input) {
+    if (input == null) return true;
+    if (Array.isArray(input)) return input.length === 0;
+    if (typeof input === 'string') return input.length === 0;
+    if (typeof input === 'object') return Object.keys(input).length === 0;
+    return false;
+  };
+
+  // ===========================================================================
+  // Expression evaluator
+  // ===========================================================================
+
+  var _customFns = {};
+
+  function evalExpr(expr, node) {
+    if (expr == null) return expr;
+
+    // Literal values pass through
+    if (typeof expr !== 'object' || Array.isArray(expr)) return expr;
+
+    // Must have fn to be an expression
+    if (!expr.fn) return expr;
+
+    // Resolve input
+    var input = expr.input;
+    if (typeof input === 'string' && input.startsWith('state.')) {
+      input = resolve(node, input);
+    } else if (Array.isArray(input)) {
+      input = input.map(function (v) {
+        if (typeof v === 'string' && v.startsWith('state.')) return resolve(node, v);
+        if (v && typeof v === 'object' && v.fn) return evalExpr(v, node);
+        return v;
+      });
+    } else if (input && typeof input === 'object' && input.fn) {
+      input = evalExpr(input, node);
+    }
+
+    // Special: if
+    if (expr.fn === 'if') {
+      var cond = evalExpr(expr.cond, node);
+      if (cond) {
+        return (expr.then && typeof expr.then === 'object' && expr.then.fn) ? evalExpr(expr.then, node) : expr.then;
+      } else {
+        return (expr.else && typeof expr.else === 'object' && expr.else.fn) ? evalExpr(expr.else, node) : expr.else;
+      }
+    }
+
+    // Special: filter with where clause
+    if (expr.fn === 'filter' && Array.isArray(input) && expr.where) {
+      return input.filter(function (item) {
+        var tmp = { state: Object.assign({}, node.state, { $: item }) };
+        return evalExpr(expr.where, tmp);
+      });
+    }
+
+    // Special: map with apply clause
+    if (expr.fn === 'map' && Array.isArray(input) && expr.apply) {
+      return input.map(function (item) {
+        var tmp = { state: Object.assign({}, node.state, { $: item }) };
+        return evalExpr(expr.apply, tmp);
+      });
+    }
+
+    // Look up function
+    var fn = _customFns[expr.fn] || _fns[expr.fn];
+    if (!fn) {
+      console.warn('CardCompute: unknown function "' + expr.fn + '"');
+      return undefined;
+    }
+
+    return fn(input, evalExpr, expr);
+  }
+
+  // ===========================================================================
+  // run — evaluate all compute declarations on a node
+  // ===========================================================================
+
+  function run(node) {
+    if (!node || !node.compute) return node;
+    if (!node.state) node.state = {};
+
+    var keys = Object.keys(node.compute);
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i];
+      try {
+        var val = evalExpr(node.compute[key], node);
+        _deepSet(node.state, key, val);
+      } catch (e) {
+        console.error('CardCompute.run error on "' + (node.id || '?') + '.' + key + '":', e);
+      }
+    }
+
+    return node;
+  }
+
+  // ===========================================================================
+  // registerFunction — extend the vocabulary
+  // ===========================================================================
+
+  function registerFunction(name, fn) {
+    _customFns[name] = fn;
+  }
+
+  // ===========================================================================
+  // Export
+  // ===========================================================================
+
+  return {
+    run: run,
+    eval: evalExpr,
+    resolve: resolve,
+    registerFunction: registerFunction,
+    get functions() {
+      var all = {};
+      Object.keys(_fns).forEach(function (k) { all[k] = _fns[k]; });
+      Object.keys(_customFns).forEach(function (k) { all[k] = _customFns[k]; });
+      return all;
+    }
+  };
+
+}));