ump_spec

package ump-spec

ump_spec: the Universal Model Protocol contract library (POC).

Pure: Pydantic v2 models, JSON Schema export, rule functions, the gate catalogue and its Python evaluator (OPA stand-in), RFC 9162 Merkle maths, canonical JSON, RFC 9457 problems, CloudEvents helpers and the engine adapter contract. The only I/O is reading packaged registry YAML.

Read the ump-spec guide first for the main entry points.

Modules

Module	What it holds
ump_spec.adapter	Engine adapter contract (POC blueprint “Engine adapter contract”).
ump_spec.errors	Typed UMP error with RFC 9457 conversion. Codes and HTTP statuses come from registries/error_codes.yaml (spec §19 and §25.4). Each code has exactly one status: a code whose registered status is an error status (400 or above) always takes it, whatever status= says; only a note code raised as a stop (registered 200) takes the caller’s status, and an unregistered code keeps the status it was given (400 by default).
ump_spec.events	CloudEvents 1.0.2 envelopes with UMP extension attributes (spec §19).
ump_spec.gates	Gate evaluator: the POC stand-in for OPA/Rego (spec §15, §25.4).
ump_spec.integrity	Record integrity (spec §18): canonical JSON, RFC 9162 Merkle tree, proofs, Ed25519 checkpoints.
ump_spec.models	All UMP contract models. Import from here: from ump_spec.models import Estimand, ShownNumber.
ump_spec.models.benchmark	Benchmark store rows (spec §25.9): evidence, cells, prior cards, release ledger, maturity.
ump_spec.models.calibration	Calibration record (spec §10): routes R1 to R6, checks 0 to 6, PSIS diagnostics.
ump_spec.models.capability	Capability manifest (spec §8) and capability lifecycle (§16).
ump_spec.models.client	Client, profile and contract terms (onboarding, §20, §25.5, §25.9).
ump_spec.models.common	Shared value objects: Interval, FallbackEntry, Note, ShownNumber, Problem (RFC 9457).
ump_spec.models.connection	Data connections: reusable, client-scoped access to data UMP may read but not keep (POC blueprint DATA-CATALOGUE §2 and §6; a proposed addition to spec §6 and §20, see context/open-questions.md).
ump_spec.models.contract	Workflow input contract: the “same necessary shape” a saved workflow accepts on new data.
ump_spec.models.dataset	Datasets, deliveries and transform steps (spec §6).
ump_spec.models.decision	Decision records and approvals (spec §12, §15, §18).
ump_spec.models.estimand	Seven-field estimand (spec §5) and its scope (applies_to).
ump_spec.models.evidence	Evidence cards (spec §17, §19 /evidence-card) and acceptance reports (§14).
ump_spec.models.experiment	Test plans and results (spec §9, EMA guide §5).
ump_spec.models.gate	Gate definitions (registry YAML) and gate results (spec §15, §25.4).
ump_spec.models.infra	Infrastructure records: lineage edges (§6), log entries and proofs (§18), CloudEvents (§19), jobs (Temporal stand-in) and run records (§13).
ump_spec.models.lifecycle	Artifact envelope and the one state machine for every kind (spec §15).
ump_spec.models.model	Model manifest (spec §7), tiers, dependence declaration, acceptance status (§14).
ump_spec.models.planning	Scenarios and optimisation results (spec §8 ladder, §12).
ump_spec.models.recipe	Transform recipes: how a derived dataset was made (POC blueprint TRANSFORM-RECIPES §4 and §6; spec §6).
ump_spec.registries	Packaged registry data (read-only YAML). The only I/O ump_spec does.
ump_spec.rules	Pure rule functions (no I/O). Import from here: from ump_spec.rules import compare_estimands.
ump_spec.rules.benchmark	Benchmark pooling maths (spec §25.3 rule 4) and the benchmark parameters registry (spec §21).
ump_spec.rules.contract	Check new input against a workflow’s InputContract (feature workflow-bundles S3).
ump_spec.rules.data	Rules for the data catalogue and connections (POC blueprint DATA-CATALOGUE §2, §4, §6). Pure functions.
ump_spec.rules.dependence	Dependence envelope for portfolio sums (G-DEP-01) and aggregation rules (G-UNC-01).
ump_spec.rules.estimands	Estimand rules (spec §5): canonical form, compare, align ladder (G-EST-02), fill undeclared with the rule 4 envelope (G-EST-01), plain words.
ump_spec.rules.experiments	Experiment rules that several gates and apps share (spec §9, §10, §25.10).
ump_spec.rules.governance	Materiality (G-MAT-01), maturity score and stages (§25.5), Benjamini-Hochberg (§10), conflict z (EMA §6.6), evidence ageing / use-by (§9, EMA §7).
ump_spec.rules.intervals	Interval helpers: envelopes, widening, width labels, imputed bands, audit level min (G-AUD-01).
ump_spec.rules.ladder	Fallback ladder (spec §8) and the tier x operation matrix.
ump_spec.rules.plain	Plain-language fields for a ShownNumber (POC reporting views for non-technical readers).
ump_spec.rules.recipes	Transform recipes on the catalogue side (POC blueprint TRANSFORM-RECIPES §6 and §7). Pure functions.
ump_spec.schema_export	Export JSON Schema 2020-12 for every public model (python -m ump_spec export-schemas <dir>).
ump_spec.secrets	Secret hygiene for data connections (POC blueprint DATA-CATALOGUE §3, spec §18 and §20).

Re-exports

Documented on the page of the module that defines them.

Name	Kind	Summary
ARTIFACT_KINDS	constant
ARTIFACT_STATES	constant
KIND_DOC_MODELS	constant	Artifact kind -> Pydantic model for its doc body.
TRANSITIONS	constant	Allowed transitions. checks_failed -> draft and rejected -> draft let an author revise (a new version); the spec’s arrows are the forward path.
AppliesTo	class	Scope beside the estimand: compared by G-EST-02 like the seven fields.
Artifact	class	Catalogue row (one per version). doc holds the kind-specific body.
Estimand	class	The seven fields plus applies_to and the registered optional members. None (written "undeclared") means undeclared.
FallbackEntry	class	§19 fallback note. effect says how the interval changed, in plain words.
GateResult	class
Interval	class
Note	class	Informational or warning note (e.g. ENGINE_STUB, NOT_IMPLEMENTED_IN_POC).
Problem	class	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.
ShownNumber	class	The display contract: a value can only be shown with its interval, estimand and trust labels.
UmpError	class	Raise anywhere; convert with to_problem(); the SDK app factory renders it.
allowed_transitions	function
can_transition	function
canonical_json	function	RFC 8785 (JCS) text, spec §18: members sorted by UTF-16 code units, ECMAScript number form, no whitespace, null members omitted, instants as UTC Z with milliseconds; non-finite numbers and duplicate member names are refused (ValueError). Encode as UTF-8 for the canonical bytes.
check_approval	function	§15 invariants (G-INT-02, hard stop): approver is a human with the approver role, is neither the submitter nor the owner nor an author of the version (the reviewer is “never the builder”), never an agent or API token; only the measurement lead approves calibrations; a rejection needs a comment.
check_transition	function	Raise UmpError(INVALID_TRANSITION) when src -> dst is not allowed.
content_hash	function	sha256:<hex> of the canonical bytes of obj (all of it; see artifact_content_hash).
leaf_hash	function	Hex leaf hash of a record under a domain tag.
problem	function
validate_doc	function	Validate an artifact doc against its kind. Raises UmpError(SCHEMA_INVALID) with every issue at once (pointer per issue).

Classes

ArtifactDoc

class

class ArtifactDoc(BaseModel)

Body of a catalogue artifact (spec §21, Extensions and Unknown members).

Declared members are validated. An unknown member is extra_forbidden (SCHEMA_INVALID at /doc/<member>) unless it is x-<prefix>-<name> with a registered prefix; such members are kept on round trip and never read by gates. extra="allow" is only the storage for those extension members: the wrap validator below refuses every other unknown member, so the effect is forbid.

Fields

Name	Type	Default	Description
id	str | None	None	Governance member (spec §6): artifact id.
revision	int | None	None	Governance member (spec §6): content revision (spec §7).
state	str | None	None	Governance member (spec §6): lifecycle state of the version.
owner	str | None	None	Governance member (spec §6): owner principal.
submitted_by	str | None	None	Governance member (spec §6): submitter principal.
approved_by	str | None	None	Governance member (spec §6): approver principal.
gate_results	list[Any] | None	None	Governance member (spec §6): gate results of the latest run.
content_hash	str | None	None	Governance member (spec §6): the artifact content hash.
valid_to	Any	None	Governance member (spec §6): end of the validity window (spec §7).
legacy_members	frozenset[str]	frozenset()	Older member names a subclass’s before validator still reads for one cycle (spec §21: read compatibility). They are not declared fields and never appear in a dump.

Source: packages/ump-spec/src/ump_spec/_base.py, line 109

Proposed

class

class Proposed(StrictModel)

A threshold value that the spec marks proposed (pending the pre-rollout studies).

Fields

Name	Type	Default	Description
value	float
proposed	bool	True
source	str	''	Spec section the value comes from, e.g. ‘§14’.

Source: packages/ump-spec/src/ump_spec/_base.py, line 185

StrictModel

class

class StrictModel(BaseModel)

Value object: unknown fields rejected.

Source: packages/ump-spec/src/ump_spec/_base.py, line 62

Constants

Name	Type	Value	Description
ESTIMAND_SCHEMA_VERSION		'est-registry/1.2.0'	Current estimand registry version. Producers write it into Estimand.schema_version explicitly: the field has no default (spec §5).
SPEC_VERSION		'2.3.0-draft'	Version of the UMP spec this contract library implements (spec §21: Draft 2.3 carries 2.3.0-draft).