Skip to content
Universal Model ProtocolDocs

Universal Model Protocol

Spec Draft 2.3

UMP lets a test result, a model and a budget plan pass between tools without losing what the numbers mean. Two analysts asking the same question should reach the same answer, or see exactly why they differ.

NormativeRead the specDraft 2.3, with a permalink on every section and paragraph so you can quote it.TutorialsLearn with notebooksWorked examples in pandas, from a first estimand to a served workflow.GuidesIntegrate a toolValidate your first document against the published JSON Schemas, in any language.GuidesPython packagesWhat each public package does and when to reach for it.ReferenceAPI referenceEvery public module, class and function, generated from the source.

Why it exists

Section titled “Why it exists”

It starts on a Thursday before budget lock. A geo test on Instagram Reels reads out 30% below what the marketing mix model predicted. The planning lead wants next quarter’s plan to reflect it, but the model came from a vendor as a spend-response table, so nobody can refit it.

One analyst scales the Meta curve down by the test result. Another, working on a sister brand, scales the whole Paid Social curve instead. The client receives two recommendations $400K apart, and a four-day audit cannot reconstruct either.

Schema checks would not have caught it. The vendor table measured return against zero spend, the test measured a 30% cut, and the lift covered two weeks while the curve assumed full carryover. Each number was right on its own. Combining them was the mistake. UMP treats meaning as part of the contract, so that mistake has nowhere to hide.

  1. Frame 1. The readout

    The MMM predictedA vendor spend-response table. Nobody can refit it.
    The Reels geo test read30% below that prediction

    It is the Thursday before budget lock. The planning lead wants next quarter’s plan to reflect the test.

  2. Frame 2. Two fixes

    Analyst one Copies the Meta curve into Excel and scales it down by the test result. Recommendation A
    Analyst two, sister brand Scales the whole Paid Social curve instead. Recommendation B

    $400K apart The client gets two recommendations. A four-day audit cannot reconstruct either. Bar lengths are illustrative.

  3. Frame 3. Why the checks passed

    Suppose both analysts had used the first draft of UMP perfectly: shared names, model tiers, logged data changes. The numbers still answer different questions.

    • Compared with what?The vendor table measured ROI against zero spend. The test measured a 30% cut.
    • Over how long?The Reels lift covered two weeks. The curve assumed full carryover.
    • Schema checksEvery one would pass.

    The fix is in the contract. A number now crosses UMP with its estimand, an uncertainty that combines honestly, its provenance and its trust level. Mismatched estimands are never combined without a stated assumption (G-EST-02).

Every number was right on its own. Combined, they were wrong, and nothing in the files said so. That is the gap UMP closes.

Figure 1The Thursday before budget lock: two analysts, $400K apart. Step through the story in three frames: the test readout, the two fixes, and why every schema check would still pass. The bars are illustrative; only the $400K gap comes from the story.

What every number carries

Section titled “What every number carries”
  • Its estimandSeven fields that say which question the number answers: intervention, baseline, horizon, unit, point rule, interval and schema version.
  • Its uncertaintyAn interval in a form that can be combined honestly, never a bare point.
  • Its provenanceWhich model, test or plan produced it, and from which data.
  • Its trust levelHow far it got through the acceptance bar, and any fallback it used.

When two pieces of evidence do not line up, the gate engine gives the best answer it can still defend and says what it had to assume. A decision made on a labelled best guess beats one made in an unlabelled spreadsheet because the system said no.

  1. Hard stopThe step does not run. Only eight gates: privacy, record integrity and approver identity, agent tool separation.
  2. Exclude and continueEvidence known to be wrong is left out; the step carries on with what remains.
  3. Fall backRuns on the next-best evidence or a registered default, with a fallbacks entry and a wider interval. Most gates.
  4. RouteRuns now as provisional; a named reviewer confirms, revises or reverts.
  5. WarnRuns with a visible note attached.

Gates degrade before they block. A blocked step does not make the decision go away: the plan still has to be set on Thursday. So a failed gate gives the best answer the evidence supports and says what it assumed.

A request can set on_gate_fail: "strict" for named gates, which turns their fallback into a stop with a typed error.

Figure 2What happens when a gate fails. Five outcomes, strongest first. Pick a situation to see which one applies, then turn on strict mode to see a fallback become a stop.

Who it connects

Section titled “Who it connects”

UMP sits between the tools a measurement team already uses: Bayesian and frequentist media mix models (Meridian, Robyn, PyMC-Marketing, in-house frameworks and vendor tables), geo and user-level experiments, scenario planners and budget optimisers, and decision agents that read validated results and write drafts only. It is open to model families beyond media mix: audience, reach and frequency, attribution, brand and forecasting.

Who uses the evidence

Evidence flows up

Drafts flow down; a named person approves

One adapter per tool

Where evidence comes from

Models

Experiments and data

Tools never pass files to each other. Each one speaks to a single core through an adapter. Every crossing is a typed UMP object, and a gate checks it on the way through.

Models and tests keep working as they do today. The core keeps the meaning attached to every number: which question it answers, how sure it is, where it came from and how far it can be trusted.

The core does not fit models and does not make decisions. Machines draft; named people approve.

Figure 3One core between the tools that make evidence and the people who use it. Click a tool, the core or a user of the evidence to see which typed objects cross at that point and which gates check them. Models and tests send evidence up through adapters; plans and drafts come back down, and only a named person makes them official.

How a decision moves through it

Section titled “How a decision moves through it”

Every step from fitting a model to sealing the decision writes its results through the same core, so the evidence behind a budget can be traced back months later.

  9. UMP coreGates, lineage, events

One loop, eight steps. A model is fitted. Tests are ranked by what they could change, then designed and run. Their results calibrate the model, the budget moves, a named person decides, and the record is sealed. When the decision comes up for review, what really happened feeds the next fit.

Every step writes its work through the core: gates check it, lineage links it to what it was built from, and an event announces the change.

Figure 4The measurement loop, with the core at its centre. Click a step to see what happens there in plain words, which gates check it and where the specification covers it. The six stages T0 to T5 are named in section 25; deciding and sealing come from sections 12, 17 and 18, and the review of each decision feeds the next fit.