ump_spec.models.common

module ump-spec

Shared value objects: Interval, FallbackEntry, Note, ShownNumber, Problem (RFC 9457).

Classes

Interval

class

class Interval(StrictModel)

Fields

Name	Type	Default	Description
`lo`	`float`
`hi`	`float`
`level`	`float`	`0.9`
`method`	`str \| None`	`None`
`segments`	`list[tuple[float, float]] \| None`	`None`	Spec §5: an `hdi` region that is not one interval, as ordered, non-overlapping [lo, hi] segments inside [lo, hi] (note MULTIMODAL_HDI).

Methods and properties (3)

width property

width: float

contains method

def contains(self, x: float) -> bool

covers method

def covers(self, other: Interval) -> bool

Source: packages/ump-spec/src/ump_spec/models/common.py, line 28

FallbackEntry

class

class FallbackEntry(StrictModel)

§19 fallback note. effect says how the interval changed, in plain words.

Fields

Name	Type	Default	Description
`code`	`Code`
`gate`	`str`
`field`	`str \| None`	`None`
`assumed`	`str`
`effect`	`str`
`envelope_kind`	`Literal['bound', 'range'] \| None`	`None`	G-DEP-01 (spec §7): `bound` for sums, means, CVaR and monotone functions of sums; `range` for quantile-type, non-monotone outputs and EVOI. A range is never a bound.
`interval_before`	`Interval \| None`	`None`
`interval_after`	`Interval \| None`	`None`
`acknowledged_by`	`str \| None`	`None`
`acknowledged_at`	`datetime \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/common.py, line 65

Note

class

class Note(StrictModel)

Informational or warning note (e.g. ENGINE_STUB, NOT_IMPLEMENTED_IN_POC).

Fields

Name	Type	Default
`code`	`Code`
`message`	`str`
`severity`	`Literal['info', 'warn']`	`'info'`
`gate`	`str \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/common.py, line 84

ShownNumber

class

class ShownNumber(StrictModel)

The display contract: a value can only be shown with its interval, estimand and trust labels.

Fields

Name	Type	Default	Description
`value`	`float`
`interval`	`Interval`
`estimand`	`Estimand`
`plain_words`	`str`		Estimand in plain words, including any assumed field.
`label`	`str \| None`	`None`	Short caption, e.g. ‘Paid Social iROAS’.
`unit_label`	`str \| None`	`None`
`trust_level`	`int`	`2`
`audit_level`	`AuditLevel`	`2`
`fallbacks`	`list[FallbackEntry]`	`list()`
`notes`	`list[Note]`	`list()`
`artifact_id`	`str \| None`	`None`	G-REP-01: the artifact this number resolves to.
`width_label`	`str \| None`	`None`	narrow\|moderate\|wide (proposed cut points).
`headline`	`str \| None`	`None`	Plain short label, e.g. ‘Return per $1 on Linear TV’.
`range_words`	`str \| None`	`None`	The interval in words, e.g. ‘likely between $0.60 and $1.87’.
`confidence`	`Literal['high', 'medium', 'low'] \| None`	`None`	From trust level and interval width (rule in ump_spec.rules.plain; proposed).
`why_best_guess`	`str \| None`	`None`	One plain sentence when the number rests on fallbacks.

Source: packages/ump-spec/src/ump_spec/models/common.py, line 93

ProblemIssue

class

class ProblemIssue(StrictModel)

One entry of a problem’s errors member (spec §19): {code, gate_id, pointer, detail}.

Fields

Name	Type	Default	Description
`code`	`Code`
`gate_id`	`str \| None`	`None`	The gate that raised this problem, when a gate did.
`pointer`	`str \| None`	`None`
`detail`	`str \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/common.py, line 126

Problem

class

class Problem(StrictModel)

RFC 9457 problem details plus the UMP extension members of spec §19: stable code, gate_id, pointer, suggested_action, errors (every problem when several are returned) and untrusted_text kept apart from platform text. type is always the code’s registered URI. Served as application/problem+json.

Fields

Name	Type	Default	Description
`type`	`str`	`''`	Always the registered URI of `code` (set on validation).
`title`	`str`
`status`	`int`
`detail`	`str \| None`	`None`
`instance`	`str \| None`	`None`
`code`	`Code`
`pointer`	`str \| None`	`None`
`suggested_action`	`str \| None`	`None`
`untrusted_text`	`str \| None`	`None`
`gate_id`	`str \| None`	`None`
`errors`	`list[ProblemIssue]`	`list()`
`fallbacks`	`list[FallbackEntry]`	`list()`
`extra`	`dict[str, Any]`	`dict()`

Source: packages/ump-spec/src/ump_spec/models/common.py, line 136

Functions

as_audit_level

function

def as_audit_level(n: int) -> AuditLevel

Narrow an int to AuditLevel (raises ValueError outside 1..4), for typed callers.

Source: packages/ump-spec/src/ump_spec/models/common.py, line 20

problem_type

function

def problem_type(code: str) -> str

Spec §19: the one registered type URI of a code (base + lower case, underscores to hyphens).

Source: packages/ump-spec/src/ump_spec/models/common.py, line 121

Constants

Name	Value	Description
`TrustLevel`	`int`	1 is lowest (taken on trust / unvalidated vendor). POC scale 1..4.
`AuditLevel`	`Literal[1, 2, 3, 4]`	§13: 4 exact rerun, 3 close rerun, 2 logged, 1 taken on trust.
`PROBLEM_BASE`	`'https://ump.dev/problems/'`	Spec §19 problem type base (fixed at publication, §24).