ump_spec.models

module ump-spec

All UMP contract models. Import from here: from ump_spec.models import Estimand, ShownNumber.

Modules

Module	What it holds
`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).

Re-exports

Documented on the page of the module that defines them.

Name	Kind	Summary
`ACCEPTANCE_LAYERS`	constant
`ADMISSIBILITY`	constant	G-EXP-05: only A to C calibrate incrementality. E feeds the brand family only.
`APPLY_ORDER`	constant	Fixed apply order (architecture doc): hard stops, exclusions, fallbacks, routes, warnings.
`APPROVAL_TRANSITIONS`	constant	Transitions that need an approval (POST :approve), not a plain :transition.
`ARTIFACT_KINDS`	constant
`ARTIFACT_STATES`	constant
`CALIBRATION_CHECKS`	constant
`CAPABILITY_LIFECYCLE`	constant
`CAPABILITY_TRANSITIONS`	constant	Any state may go to withdrawn immediately (§16).
`CATALOGUE_FINGERPRINT_BASIS`	constant	Basis of `inputs[].catalogue_fingerprint`: `rules.canonical_rows_fingerprint` over the frame’s cells as plain JSON values, the same basis a connected dataset registers its `sha256` under.
`CHECK_GATES`	constant
`CONNECTOR_KINDS`	constant
`COPY_POLICIES`	constant
`CURRENCY_RE`	constant	ISO 4217 alpha-3 code (spec §5 `unit.currency`).
`DATA_USES`	constant
`ESTIMAND_FIELDS`	constant	The seven estimand fields, in spec order.
`EXTRACTION_ORDER`	constant	Best to worst; a model shows the lowest rating among its inputs.
`FAMILY_ALIASES`	constant	Labels seen in briefs and adapters mapped to the canonical `ModelFamily` value.
`FAMILY_NOTES`	constant	Plain words per family. Experiments are not a model family (see `adapter.AdapterKind`).
`FAMILY_REQUESTS`	constant
`HARNESS_MEASURES`	constant	The six §17 harness measures (injection resistance split into write/run successes and exfiltrations).
`INPUT_CONTRACT_VERSION`	constant
`MATURITY_STAGES`	constant
`MODEL_FAMILIES`	constant
`PER_VALUES`	constant	`unit.per` values (spec §5).
`PROV_RELATION`	constant
`RECIPE_FINGERPRINT_BASIS`	constant	Basis of `inputs[].fingerprint` and `output.fingerprint` (the client package’s round-trip rule).
`RECIPE_NOTE_CODES`	constant
`RECIPE_SCHEMA_VERSION`	constant
`RECIPE_STEP_HASH_BASIS`	constant
`RECIPE_VERIFICATION_STATUSES`	constant
`ROUTES`	constant
`STANDARD_REQUESTS`	constant
`STOP_OUTCOMES`	constant
`TIERS`	constant
`TIER_NAMES`	constant
`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.
`UNDECLARED`	constant	The wire word for a field the source did not declare (spec §5).
`AcceptanceLayer`	class
`AcceptanceMetric`	class
`AcceptanceReport`	class
`AcceptanceStatus`	class	§14: three layers. Untested is usable with reduced trust; failed is excluded (G-ACC-01).
`AcceptanceStatusValue`	constant
`AccessPolicy`	class	Access rules on a data connection, copied onto each connected dataset (POC DATA-CATALOGUE §2).
`AdmissibilityClass`	constant
`AgentEvalReport`	class	§17 agent evaluation harness run (G-NEW-03 release gate) for one agent version.
`AllocationLine`	class
`AppliesTo`	class	Scope beside the estimand: compared by `G-EST-02` like the seven fields.
`Approval`	class
`ApproveRequest`	class
`Artifact`	class	Catalogue row (one per version). `doc` holds the kind-specific body.
`ArtifactKind`	constant
`ArtifactState`	constant
`AuditLevel`	constant	§13: 4 exact rerun, 3 close rerun, 2 logged, 1 taken on trust.
`BaselineKind`	constant
`BenchmarkCell`	class
`BenchmarkEvidence`	class	One evidence row. `client_ref` is salted; client names never enter pooled tables.
`BenchmarkRow`	constant
`Calibration`	class
`CalibrationCheck`	class
`CalibrationSupport`	class
`CapabilityManifest`	class
`CapabilityStatus`	constant
`CastResult`	constant
`CategoryProfile`	class	A categorical column’s level set in the input frame (hashes and count, never values). `rows` counts the rows per level hash, so a note can say how many rows a new level excludes.
`ChannelResult`	class
`CheckOutcome`	constant
`Checkpoint`	class	C2SP tlog-checkpoint: the signed body is origin, decimal tree size and base64 root hash only. Its time is the genTime of the RFC 3161 token held beside it (`tsa_token`), never a line in the body.
`CheckpointSignature`	class
`Client`	class
`ClientMaturity`	class
`ClientProfile`	class
`CloudEvent`	class	CloudEvents 1.0.2 structured JSON with UMP extension attributes. IDs and states only.
`ColumnProfile`	class	One column of the input frame. `cast` is the caller’s cast result to the contract dtype (None when the contract names no dtype for the column).
`Conflict`	class
`ConnectionTest`	class	Result of `POST /v1/connections/{id}:test`: reachability, auth and schema. No rows.
`ConnectorKind`	constant
`ConsistencyProof`	class
`ContractTerms`	class
`ControlOutcome`	class
`CopyPolicy`	constant	`allowed`: may be cached to the blob store. `transient_only`: rows live in memory for one run (the default for connections). `aggregates_only`: clean room, only aggregates above the minimum segment size come out (G-PRIV-01..03 run on every fetch).
`CostBasis`	constant
`CurveParams`	class	Tier B per-channel curve.
`DataConnection`	class
`DataUse`	constant	What a client lets UMP do with the data. Benchmark pooling is off unless listed and the licence allows it.
`Dataset`	class
`DatasetStorage`	constant
`DecisionRecord`	class
`Delivery`	class	G-DATA-01 intake record.
`DependenceDeclaration`	class
`DependenceKind`	constant
`Design`	constant
`DomainTag`	constant
`Estimand`	class	The seven fields plus `applies_to` and the registered optional members. `None` (written `"undeclared"`) means undeclared.
`Estimator`	constant
`EvidenceCard`	class
`Excision`	class
`ExcisionMode`	constant
`Expected`	class
`ExtractionRating`	constant
`FallbackEntry`	class	§19 fallback note. `effect` says how the interval changed, in plain words.
`FetchRecord`	class	What a run saw when it read a dataset (`POST /v1/datasets/{id}:materialize`). Run records and model lineage keep this record, never the rows of a `transient_only` dataset.
`FieldStatus`	constant
`FingerprintBasis`	constant	What `sha256` hashes: the raw file’s bytes (stored) or the canonical JSON of the query result’s rows (connected; `rules.canonical_rows_fingerprint`).
`FrameProfile`	class	Everything the input check reads about a frame, with no row values in it.
`GateAppliesTo`	class
`GateDefinition`	class
`GateFailMode`	constant	`on_gate_fail`: `strict` turns a gate fallback into a stop (spec §15).
`GateOutcome`	constant	Result outcomes. `strict_stop` is a fallback turned into a stop by strict mode.
`GateResult`	class
`Horizon`	class	Time over which the effect is counted. `{type: window, anchor: fit}` is the model’s fit window: a template written before any fit (an adapter’s metadata) leaves `weeks` absent, and every quantity a fit produces states `weeks` (spec §5, “Fit-window horizon”). `weeks` is never null.
`HorizonType`	constant
`HostedEndpoint`	class	Tier X.
`InclusionProof`	class
`InputContract`	class	What new input must look like for a saved workflow to rerun on it.
`InputMode`	constant
`InputNote`	class	One finding about the input, in plain words. Never carries row values.
`InputReport`	class	The outcome of checking input against a workflow’s contract. `ok` is false when a note refuses; `route` is where the rerun goes (score, refit, or not available).
`InputRoute`	constant
`InputSeverity`	constant
`InputVar`	class	A variable the workflow reads. `required: false` makes it optional: absent gives a warning.
`IntegrityRef`	class
`Interval`	class
`IntervalMethod`	constant
`IntervalSpec`	class
`Intervention`	class
`InterventionType`	constant
`Job`	class	Spec §19 job: `state`, `steps` and, once terminal, `result` or `problem` (RFC 9457).
`JobState`	constant	Spec §19 job states; terminal states (succeeded, failed, cancelled) never change.
`JobStatus`	constant	Deprecated Python alias of `JobState` (the wire member is `state`).
`JobStep`	class
`LadderStep`	constant
`LayerName`	constant
`LayerStatus`	class
`LevelSet`	class	A categorical column’s levels without the values: the sha256 (hex) of the canonical JSON of the sorted unique non-null level values (as strings), their count, and the sorted sha256 of each level’s canonical JSON (empty in contracts written before per-level hashes; the check then compares the set hash and count only).
`Licence`	class
`LicenceLimits`	class	Vendor or client licence limits checked before export (spec §20).
`LineageEdge`	class
`LinkType`	constant
`LogEntry`	class	Spec §18 log entry: the record appended under a domain tag. The leaf is `SHA-256(0x00 \|\| domain_tag \|\| 0x0A \|\| JCS(log_entry))`; the record itself is bound by `content_hash`.
`MaterialityInputs`	class
`MaterialityThresholds`	class	G-MAT-01 thresholds, per account. All proposed (spec §15).
`MaterialityTier`	constant
`Materialization`	constant
`MaturityStage`	constant
`MetricFamily`	constant
`ModelFamily`	constant
`ModelManifest`	class
`Moderators`	class
`Note`	class	Informational or warning note (e.g. `ENGINE_STUB`, `NOT_IMPLEMENTED_IN_POC`).
`OnFail`	constant
`OnGateFail`	constant	Spec §15: the string `"fallback"` or `"strict"` for every gate, or an object mapping gate ids to either value with `"*"` as the default key.
`OperationSupport`	constant
`OptimisationResult`	class
`Outcome`	constant
`Per`	constant
`Period`	class	Calendar dates, half-open `[start, end)` (spec §4).
`PlanLine`	class
`PointRule`	constant
`PointRuleSpec`	class	`{rule, scale}` form of `point_rule` (spec §5): `scale` is `identity` or `log`.
`PointScale`	constant
`PoolStatus`	constant
`Population`	constant
`PowerAnalysis`	class
`Preregistration`	class
`PriorCard`	class
`PrioritySnapshot`	class	§11 test prioritisation snapshot: model version, joint draws used, scores, the kept portfolio (P1 cost-scaled greedy on EIG vs P2 best single test), alternatives by joint EVOI and the reason for any override. Briefs MUST NOT claim the (1 - 1/e) bound for EVOI or budget-constrained selection, so `guarantee_note` states what is (and is not) guaranteed. Signed off by the measurement lead.
`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`.
`ProblemIssue`	class	One entry of a problem’s `errors` member (spec §19): `{code, gate_id, pointer, detail}`.
`ProposedThreshold`	class
`PsisDiagnostics`	class
`ReaderSpec`	class
`Realised`	class
`RecipeCapture`	constant
`RecipeCell`	class
`RecipeEnvironment`	class
`RecipeExternalInput`	class	A recipe input with no catalogued match in the client’s scope (`UNCATALOGUED_INPUT`).
`RecipeInput`	class
`RecipeInputMatch`	class	A recipe input matched to a catalogued dataset in the same client’s scope (a `derived_from` edge).
`RecipeNote`	class
`RecipeNoteCode`	constant
`RecipeOutput`	class
`RecipeRef`	class	What a catalogued dataset keeps of its recipe (`Dataset.recipe`). The body lives in the blob store.
`RecipeStep`	class
`RecipeVerification`	class
`RecipeVerificationRef`	class	The recipe’s own verification as uploaded. Self-reported: `apps/data` never replays a recipe.
`RecipeVerificationStatus`	constant	`not_checked` is untested, not failed (`RECIPE_UNVERIFIED`).
`RegistryStatus`	constant	Status of a registry entry (spec §21, Registries).
`ReleaseLedgerEntry`	class
`Representation`	constant
`Route`	constant
`RunRecord`	class
`Scenario`	class
`ScenarioResult`	class
`SecretStatus`	class	All the API ever echoes about a secret: its reference, whether one is set, and when it changed. Rotating the secret changes `updated_at`, never the connection’s id.
`ShownNumber`	class	The display contract: a value can only be shown with its interval, estimand and trust labels.
`SizeKind`	constant
`SourceType`	constant
`SpendGrid`	class	Tier C declaration. Grid >= 21 points from 0 to 2.5x current spend is proposed (§7).
`StageFlag`	class
`SummaryNumber`	class	Tier D: ROI or mROI at current spend only.
`TestPlan`	class
`TestResult`	class
`Tier`	constant
`TimeProfile`	class	The time column of the input frame. `duplicates` counts rows whose time value repeats (expected in a panel); `regular` is false when a time is off the frequency’s grid; `gaps` counts missing steps inside the range at the frequency.
`TimestampToken`	class	RFC 3161 time-stamp token held beside a checkpoint, never a cosignature (spec §18). The POC signs with a local key standing in for a TSA (`tsa: poc-standin`); a real token is a CMS SignedData blob.
`TransformRecipe`	class	`<output>.recipe.json`: inputs by hash, steps, notebook cells, the output’s fingerprint and the analyst’s own replay check.
`TransformStep`	class
`TransformType`	constant
`TransitionRequest`	class
`TrustLevel`	constant	1 is lowest (taken on trust / unvalidated vendor). POC scale 1..4.
`Unit`	class	`per` is `spend`, `impression` or `absolute`. `currency` (ISO 4217) is required with `per: spend` and allowed with `per: absolute` (a money KPI); there its absence means the KPI is not money. Build a spend unit with `spend_unit(currency)`.
`allowed_transitions`	function
`as_audit_level`	function	Narrow an int to `AuditLevel` (raises `ValueError` outside 1..4), for typed callers.
`can_transition`	function
`capability_transition_allowed`	function
`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.
`gate_mode_args`	function	`(mode, strict_gates)` for `gates.evaluate`. A `"*": strict` map with named fallback gates becomes fallback mode with every other strict-capable gate (`strict_override`) listed.
`gate_mode_header`	function	The `UMP-On-Gate-Fail` echo: the string when one mode covers every gate, else the object form as compact JSON with sorted keys.
`gate_mode_map`	function	Normalise either form of `on_gate_fail` to `{"*": default, gate_id: mode, ...}`. `None` is the default `fallback`. Anything else is 422 `SCHEMA_INVALID` at `pointer`.
`make_dataset_ref`	function	`dataset://{scope}/{name}@sha256:{hash}`.
`normalise_legacy_estimand`	function	Read a stored estimand written before the spec §5 wire rules (fixtures, old docs; never a writer).
`normalise_legacy_unit`	function	Read compatibility for one cycle: `per: "<ccy>_spend"` becomes `per: spend` plus `currency: "CCY"`, and null members are dropped. Other values pass through unchanged (a per-thousand unit such as `usd_k_spend` is rescaled by its adapter, never here).
`normalize_family`	function	Canonical family for a label (`"brand_funnel/track"` -> `"media_tracking"`).
`parse_dataset_ref`	function
`principal_kind`	function	`user:maya.chen` -> `user`; `agent:newton-actor` -> `agent`; `token:...` -> `token`.
`psis_khat_threshold`	function	§10 (proposed): k-hat < min(1 - 1/log10(S), 0.7).
`resolve_gate_mode`	function	The effective mode per gate: the stricter of the request and the account policy (spec §15: a request MUST NOT relax a gate the account sets to strict). The account’s deprecated `strict_gates` map in as strict entries.
`run_audit_level`	function	§13: a level 3 or 4 claim needs a lockfile, an image digest, the code commit and the dataset hashes; without any of them the run is capped at level 2. Level 4 also needs seeds and a deterministic engine.
`salted_client_ref`	function	`cref_<16 hex>`: salted ref for pooled tables (§25.9). Erasure deletes the salt.
`spend_unit`	function	Members of a per-spend unit (spec §5): `{"per": "spend", "currency": "USD", ...}`. `currency` is an ISO 4217 code; lower case is upper-cased. Splat it into a unit dict or `Unit(**...)`.
`validity_expired`	function	Spec §7: the window is half-open [valid_from, valid_to), so a model is expired when `valid_to <= now`. No (or an unreadable) `valid_to` never expires.
`validity_instant`	function	A validity bound as a UTC instant (spec §4 time profile, §7 half-open window). A calendar date (`2026-01-01` or a `date`) reads as midnight UTC; a naive datetime reads as UTC; an offset is converted. Anything unreadable (or empty) is None.
`without_unset`	function	A producer’s own estimand dict with every `None` member dropped, at any depth, so optional state that is not known (no client id, no period) is left out instead of written as null. Use it only on dicts the producer builds; received input is validated as sent, where null is refused.
`worst_extraction`	function

Functions

validate_doc

function

def validate_doc(kind: str, doc: dict[str, Any]) -> BaseModel

Validate an artifact doc against its kind. Raises UmpError(SCHEMA_INVALID) with every issue at once (pointer per issue).

Source: packages/ump-spec/src/ump_spec/models/__init__.py, line 305

validation_issues

function

def validation_issues(errors: Any, prefix: str = '') -> tuple[str, list[ProblemIssue]]

Pydantic errors as problem issues with JSON pointers under prefix. An estimand member the contract does not recognise is its own issue per member with code ESTIMAND_UNKNOWN_FIELD (spec §5), and that code then names the problem; anything else is SCHEMA_INVALID.

Source: packages/ump-spec/src/ump_spec/models/__init__.py, line 323

Constants

Name	Type	Value	Description
`KIND_DOC_MODELS`	`dict[str, type[BaseModel]]`	`{'dataset': Dataset, 'transform_step': TransformStep, 'model_manifest': Model...`	Artifact kind -> Pydantic model for its `doc` body.