Skip to content
Universal Model ProtocolDocs

Capabilities, standard requests and fallback

§8NormativeDraft 2.3Latest draft

A tool asks a model for a calculation through one of seven standard requests; the model’s capability manifest says whether it does the work itself, UMP computes it from what the model provides, or it is unavailable, and every answer says which fallback step produced it.

Standard requests. score, response_curve, marginal_return, decompose, optimize, calibrate, update. Family profiles add more (section 16).

Engine profile. Engine adapters and Tier X hosted endpoints expose GET /v1/metadata. For every standard request the manifest marks built_in, they expose POST /v1/<request> (score, response_curve, marginal_return, decompose, optimize, calibrate, update). Engines that fit also expose POST /v1/fit. Request and response bodies are the contract schemas <Request>Request and <Request>Response. A request the manifest marks unavailable or computed_by_ump MUST return OPERATION_UNAVAILABLE (501), naming the nearest working operation as the suggested action. The core API in section 19 is a separate surface: it addresses models by ID (/v1/models/{id}:<request>) and either routes to the engine profile or computes the result itself. Both surfaces are specified by normative OpenAPI 3.1 documents (section 21).

Capability manifest. Static JSON, readable without importing the model, modelled on modeling-api manifests: inference method, representation, dependence, score modes, decision, calibration (business_priors, lift_tests, interval_lift), owns (preprocessing the model does itself), deterministic_given_seed, and for each standard request one of built_in, computed_by_ump or unavailable.

Capability handshake. The core API answers GET /v1/models/{id}/metadata for every model with its manifest, input schema and spec version, from the engine profile’s GET /v1/metadata where the model is served by an engine or hosted endpoint, in the manner of the Open Inference Protocol’s metadata endpoint. Consumers negotiate from this as defined in section 21, Negotiation, before sending work, and requests are pre-checked against fitted coordinates from metadata alone (modeling-api’s CoordPlan), returning every problem at once (as one problem with an errors member, section 19).

Operations allowed by tier

OperationABCDX
Score a plan with rangeYesYesInside grid; beyond it, extrapolated and widenedNear current spend, warnedAs declared, else via a lower tier
Marginal returnYesYesInterpolatedCurrent spend onlyAs declared
Optimise, mean objectiveYesYesInside grid, extrapolation labelledFallback 5: benchmarks around the summaryAs declared
Optimise with risk objective, P(beat plan), regretYesYes with joint draws; otherwise dependence envelopeDependence envelope, imputed band if noneBenchmarks with imputed bandAs declared, else dependence envelope
EVOI and test prioritisationYesYes with joint draws; otherwise dependence envelopeImputed band and envelope, labelled roughLibrary prior onlyVia exported curves
Decompose a past periodYesContribution at actual spend, no baseline splitContribution at actual spend, interpolatedNoAs declared
CalibrateRefit or reweightReweight or curve adjustAttach only (section 14)Attach onlyAttach only
Update with new dataYesNo; marked stale past its valid datesNo; marked staleNoAs declared

The only operations that return nothing are ones with no defensible basis at all, such as decomposing a past period from a single ROI figure; they return the typed error with the nearest operation that does work as the suggested action.

Fallback ladder. When the best method is unavailable, UMP descends and labels the result with the step reached:

  1. 1. Full modelBest rung for tier A.
  2. 2. Curve parametersBest rung for tier B.
  3. 3. Spend table, interpolatedBest rung for tier C.
  4. 4. Summary numbers, stretched a short way from current spendBest rung for tier D. G-SCN-02 warning label
  5. 5. Benchmarks from the test library for the same mediaG-SCN-02 warning label
  6. 6. Not available, with the reasonA typed error that suggests the nearest operation that does work.

The answer still comes, from as high up the ladder as the evidence allows. A full model answers from the top. A deck with one ROI figure answers from lower down, and every answer says which step produced it.

Steps 4 and 5 are the rough ones. Any brief, deck or agent answer that uses them must name them.

Tier X, a hosted model, is different: an endpoint UMP can query but not inspect. It supports what its metadata endpoint declares.

Figure 8.1 How far down the fallback ladder an answer comes from. Pick the kind of model a team holds and the calculation it needs to see which step of the ladder answers, and when the answer must carry a warning label under G-SCN-02.
  1. Full model
  2. Curve parameters
  3. Spend table, interpolated
  4. Summary numbers, stretched a short way from current spend (warning label)
  5. Benchmarks from the test library for the same media (warning label)
  6. Not available, with the reason

Steps 4 and 5 MUST be named in any brief, deck or agent answer that uses them (G-SCN-02).

Optimisation. One request and result shape whether the engine optimises itself or UMP runs a solver over curves, taken from modeling-api’s optimise schema and extended with pacing, ROI floors and target-KPI goals. Results carry the allocation, expected KPI and range, probability of beating the current plan, expected regret, stability across draws, shadow price of the next dollar, and notes on extrapolation or non-concave curves.