ump_spec.models.contract

module ump-spec

Workflow input contract: the “same necessary shape” a saved workflow accepts on new data.

A saved model plus its data pipeline reruns on new input when the input has the columns it needs, castable to their types, with keys unique and time regular. Rows are unbounded above (more weeks is the normal case); extra columns never fail. The check (rules.contract.check_input) is pure: it reads a FrameProfile the caller built (babelfin builds one with pandas), never the rows, so ump_spec imports no dataframe library.

Privacy: category level sets are stored as a sha256 of the sorted level values plus a count, and a sha256 per level, never the values. A per-level hash lets the check name the rows at a new level (to exclude them) without the values; like any unsalted hash of a short string it can be matched by someone who guesses the value.

Classes

InputVar

class

class InputVar(VarSpec)

A variable the workflow reads. required: false makes it optional: absent gives a warning.

Fields

Name	Type	Default	Description
`required`	`bool`	`True`

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 30

LevelSet

class

class LevelSet(StrictModel)

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).

Fields

Name	Type	Default	Description
`sha256`	`str`
`count`	`int`
`hashes`	`list[Annotated[str, Field(pattern=HEX64)]]`	`list()`	sha256 (hex) of each level’s canonical JSON string, sorted; never values.

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 39

InputContract

class

class InputContract(StrictModel)

What new input must look like for a saved workflow to rerun on it.

Fields

Name	Type	Default	Description
`schema_version`	`str`	`INPUT_CONTRACT_VERSION`
`time`	`str \| None`	`None`	The time column, if any; its dim (policy, freq) is in dims.
`dims`	`dict[str, DimSpec]`	`dict()`
`vars`	`dict[str, InputVar]`	`dict()`
`target`	`str \| None`	`None`	The target column; required to refit, not to score.
`target_dtype`	`str \| None`	`None`	The target’s dtype; on a refit the target must cast to it and have no missing values.
`key`	`list[str]`	`list()`	Columns that identify a row (each one required); empty means the time column plus the categorical dims.
`extra`	`Literal['allow', 'drop']`	`'drop'`	Columns the contract does not name: drop (info note) or allow (passed silently). Never a failure.
`min_rows`	`int \| None`	`None`	Fewest rows the workflow expects (proposed; below it is a warning).
`level_sets`	`dict[str, LevelSet]`	`dict()`	Trained level set per fixed categorical dim (hash and count, never values).

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 50

ColumnProfile

class

class ColumnProfile(StrictModel)

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).

Fields

Name	Type	Default
`dtype`	`str`
`n_null`	`int`	`0`
`cast`	`CastResult \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 73

TimeProfile

class

class TimeProfile(StrictModel)

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.

Fields

Name	Type	Default
`min`	`str`
`max`	`str`
`n_unique`	`int`
`duplicates`	`int`	`0`
`regular`	`bool`	`True`
`gaps`	`int`	`0`

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 82

CategoryProfile

class

class CategoryProfile(StrictModel)

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.

Fields

Name	Type	Default	Description
`level_set`	`LevelSet`
`rows`	`dict[str, int]`	`dict()`	Level hash to row count (optional).

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 95

FrameProfile

class

class FrameProfile(StrictModel)

Everything the input check reads about a frame, with no row values in it.

Fields

Name	Type	Default
`n_rows`	`int`
`columns`	`dict[str, ColumnProfile]`	`dict()`
`time`	`TimeProfile \| None`	`None`
`key_duplicates`	`int`	`0`
`categories`	`dict[str, CategoryProfile]`	`dict()`

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 103

InputNote

class

class InputNote(StrictModel)

One finding about the input, in plain words. Never carries row values.

Fields

Name	Type	Default
`code`	`str`
`severity`	`InputSeverity`
`column`	`str \| None`	`None`
`message`	`str`

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 113

InputReport

class

class InputReport(StrictModel)

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).

Fields

Name	Type	Default	Description
`ok`	`bool`
`mode`	`InputMode`	`'score'`
`route`	`InputRoute`	`'score'`
`notes`	`list[InputNote]`	`list()`
`drop_columns`	`list[str]`	`list()`
`coerce`	`dict[str, str]`	`dict()`	Column to the contract dtype it is cast to.
`exclude_levels`	`dict[str, list[str]]`	`dict()`	Column to the hashes of its new levels; rows at those levels are excluded.
`exclude_nulls`	`list[str]`	`list()`	Structural columns (time, categorical dims, key) whose rows with no value are excluded.

Source: packages/ump-spec/src/ump_spec/models/contract.py, line 122

Constants

Name	Type	Value	Description
`INPUT_CONTRACT_VERSION`		`'ump.input_contract/0.1'`
`InputSeverity`		`Literal['info', 'warn', 'exclude', 'refuse']`
`InputMode`		`Literal['score', 'refit']`
`InputRoute`		`Literal['score', 'refit', 'not_available']`
`CastResult`		`Literal['exact', 'coerced', 'failed']`
`HEX64`		`'^[0-9a-f]{64}$'`