The twin
A simulated copy of your tenant for example data and what-if curves. Never proof.
The twin is a simulator that behaves like your tenant: your catalog, your surfaces, simulated users and their responses. It has two jobs. It fills the panel with example data before you have real traffic, and it draws a what-if curve when you simulate a flow. It never produces proof.
What it is#
- A simulator owned by the jobs. It runs next to learning and enrichment, not in the serve path.
- The source of example data. When a tenant has no real traffic yet, every chart and number in the panel shows the twin's output with an amber "example data" badge. The "Real / Example" switch in the top bar flips the whole workspace. Real views never mix in synthetic rows.
- A curve in Simulate.
POST /surfaces/{key}/simulatereturnstwin_curvewhen the tenant has a twin: one point per week with acontroland atreatmentvalue. The panel draws it at three truth scales.
Every row the twin produces is flagged synthetic: true with source synthetic. The API exposes include_synthetic so the panel can ask for them on purpose.
What it is not#
- Not proof. Synthetic rows are excluded from the ledger. A twin curve that shows a lift says the flow could work under the twin's assumptions, nothing more.
- Not a forecast. The twin's users are simulated. Their behaviour comes from assumptions, not from your users' future.
- Not a replacement for SNIPS. SNIPS re-weights traffic that really happened. The twin invents traffic. When both are available, trust SNIPS with a large effective sample over the twin, and the holdout over both.
- Not a copy of your users. It holds no real user ids and no real events.
Truth scale#
The twin needs an assumption about how strongly simulated users respond to better ranking. That assumption is the truth scale. The panel draws the twin curve at three truth scales so you see a range instead of one line. If the flow only wins at the most optimistic scale, it is a weak candidate. If it wins at all three, it is worth a holdout.
The three scales are 1.0, 0.5 and 0.25. At 1.0 the simulated audience has as much persona structure as the twin's hidden truth model assumes; 0.5 and 0.25 shrink that structure, so personalization has less to find. The twin is calibrated on real distributions only (declared goals and attributes, catalog structure, observed activity), never on invented behaviour. The simulate answer carries the lift at each scale in lift_by_truth_scale.
Status#
The simulator is built in the jobs. twin_weekly refreshes the curve per surface every day at 05:00 UTC and stores it as a twin policy; simulate reads the latest one. A surface without items, or a tenant where the job has not run yet, gets no twin_curve.