Developer Center · Engineering reference
Consumer World Model
The model layer under the Decide node: a per-brand Behavior Model (an event-sequence model of how each member behaves) plus a Digital Twin layer that runs it forward (counterfactual simulation and the synthetic research panel). This page covers what an integrator can actually touch: the events that feed it, the gate that decides whether it serves, the surfaces its outputs land on, and the MCP tools that drive the panel.
One thing to know up front: there is no raw model-inference API. You never call the model directly — you feed it events through the normal integration surfaces, and you consume its outputs where the product exposes them (segment conditions, member profile, lookalike, send-time optimization, and the synthetic panel over MCP).
1 · What feeds it
The model trains on the member event stream your integrations already produce — REST API v2 (orders, members), web & portal tracking, POS/receipt capture, loyalty and coupon activity. Events pass a governed catalog with a policy firewall before they can enter training; the firewall is enforced in the pipeline, not by convention.
Admitted: behavioral events
Purchases, receipts, points earned/redeemed, tier changes, coupon claims/redemptions, email opens/clicks, push opens, portal visits/clicks, store check-ins. Every event type is explicitly admitted to the catalog — new event types don't train silently.
Barred: feedback & content
Anything the model itself writes back (its own tags and scores) is excluded — a model must not learn from its own output. Message content and free text never enter training: the model learns that a member clicked, never what the message said.
Barred: restricted members
Members under a processing restriction (GDPR Art. 18) are excluded from training end-to-end, and an erased member's data — including their embedding — is removed as part of the deletion machinery itself.
Practical consequence for integrators: the richer and cleaner your event feed (correct member identity resolution, honest timestamps), the better the model — there is no separate “training upload.” See REST API and Web Tracking.
2 · The honesty gate & serving predicate
A brand's model is trained per tenant, deterministically (same data ⇒ same model, versioned), and it only servesafter beating a transparent baseline on that brand's own held-out data. Downstream consumers never read the model directly — they go through a single serving predicate:
If any leg fails — the model hasn't earned its place yet, the brand paused scoring, or the model has gone stale — every consumer falls back to the glass-box predictive models (or an honest empty state, in lookalike's case). Nothing is ever zero-filled and nothing pretends: a member without an embedding is served by the fallback path, never padded into the model's.
Lifecycle a brand sees
not enough history to train honestly — nothing serves
trained, being tested against the baseline on held-out reality
beat the baseline — embeddings & predictions serve
scoring stops or the model ages out — automatic fallback
3 · Outputs and where they surface
Three output families, all read-only, all consumed inside the product. If you're building on top of Flash, you meet them as segment conditions and profile fields — not as endpoints.
Member embeddings
A behavioral fingerprint per member, learned from their whole event sequence. Powers nearest-neighbor similarity: every member with behavior has one — no tags required.
Next-event probabilities
Per-member purchase imminence and churn imminence (0–100), refreshed as behavior lands. Exposed as segment conditions — e.g. "Purchase Imminence (predicted next-event, 0-100)" — and on the member profile.
Per-member timing
Each member's expected next-purchase window and engaged hour of day, from their own rhythm.
4 · Driving the synthetic panel over MCP
The Digital Twin's research panel is the one part of the world model your own AI agents can operate directly, through the governed MCP server. Four tools, verbatim from the live manifest:
list_synthetic_scenarios
((none))
List the synthetic-panel simulation scenarios with each one's honest usability boundary, confidence ceiling, and input fields. Call first to pick a kind. Requires metrics:read.
run_synthetic_panel
(segment_id, kind, fields)
Run a synthetic panel: de-identified digital twins of a segment react to a stimulus, producing an honest directional report (never real absolute numbers). Returns a run_id to poll. Bounded by a daily run cap + ≤50 twins. Requires synthetic:write.
get_synthetic_report
(run_id)
Read the frozen honest report for a synthetic-panel run — directional read, confidence ceiling, suppression flags, themes — or a blockReason if not ready. Requires metrics:read.
get_synthetic_calibration
((none))
The brand's synthetic-panel calibration (hit rate of past synthetic predictions vs reality; null until backtests exist). Requires metrics:read.
Typical flow
- 1. list_synthetic_scenarios → pick a kind + read its usability boundary
- 2. run_synthetic_panel(segment_id, kind, fields) → run_id // requires synthetic:write
- 3. get_synthetic_report(run_id) → directional read · confidence ceiling · suppression · themes — or blockReason
- 4. get_synthetic_calibration() → your brand's hit rate vs. reality (null until backtests exist)
Contract to design against: runs are bounded (daily run cap, ≤50 twins per run); reports are directional, never absolute numbers; a run that fails its honesty checks (panel collapse, sycophancy, too-small sample) comes back with a blockReason or suppression flags instead of a flattering result — treat those as terminal, not retryable. The same caps and rules apply whether a human or your agent starts the run. Setup, auth and scopes: MCP Integration Guide.
5 · Guarantees you can build on
Per-brand isolation
One model per tenant, trained on that tenant's members only. Nothing pools across brands — in either direction.
Deterministic & versioned
Same data produces the same model, bit for bit; every score is traceable to the model version that produced it.
Erasure-complete
Member erasure deletes their training data and embedding as part of the deletion transaction — not on a cleanup schedule.
Staleness-purged
Embeddings that outlive their freshness window are purged on schedule, and a stale model stops serving automatically.