ump_spec.models.benchmark

module ump-spec

Benchmark store rows (spec §25.9): evidence, cells, prior cards, release ledger, maturity.

Classes

Moderators

class

class Moderators(StrictModel)

Fields

Name	Type	Default
`retargeting_share`	`float \| None`	`None`
`spend_intensity`	`float \| None`	`None`
`peak`	`bool \| None`	`None`
`self_measured`	`bool \| None`	`None`
`creative_refresh`	`bool \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/benchmark.py, line 26

BenchmarkEvidence

class

class BenchmarkEvidence(ArtifactDoc)

One evidence row. client_ref is salted; client names never enter pooled tables.

Fields

Name	Type	Default	Description
`client_ref`	`str`
`channel`	`str`
`vertical`	`str`
`quarter`	`str`		e.g. 2026 Q2
`source_type`	`SourceType`
`estimand_id`	`str \| None`	`None`	E-BM-AVG-ROI, E-BM-MARG-ROI, … or None.
`admissibility_class`	`AdmissibilityClass \| None`	`None`
`log_value`	`float \| None`	`None`	log iROAS (or log cost per person lifted).
`se`	`float \| None`	`None`
`interval_lo`	`float \| None`	`None`
`interval_hi`	`float \| None`	`None`
`confidence_level`	`float \| None`	`None`
`value_basis`	`Literal['net', 'gross'] \| None`	`None`
`calibrated`	`bool`	`False`
`refit_id`	`str \| None`	`None`
`absorbed_by`	`str \| None`	`None`
`moderators`	`Moderators`	`Moderators()`
`notes`	`list[str]`	`list()`	Note codes.
`hold_reason`	`str \| None`	`None`
`pool_status`	`PoolStatus`	`'on_file'`
`metric_family`	`MetricFamily`	`'sales_return'`
`licence`	`Literal['pooled_use', 'client_only']`	`'pooled_use'`
`feed_cost`	`float \| None`	`None`
`spend`	`float \| None`	`None`
`is_forecast`	`bool`	`False`
`filed_at`	`datetime \| None`	`None`
`value`	`float \| None`	`None`	§25.3 rule 4a: the estimate on its reported scale, kept when non-positive (note NONPOSITIVE_ESTIMATE).
`value_scale`	`Literal['identity', 'log'] \| None`	`None`	Scale of `value`.
`se_multipliers`	`dict[str, float] \| None`	`None`	§25.3 rule 1: every SE multiplier applied to this row (source, age, …).
`filed_by`	`str \| None`	`None`	Principal that filed the row. Written by core `GET /v1/benchmark/evidence` row view (`services/benchmark.py`).
`se_effective`	`float \| None`	`None`	SE after every recorded multiplier (`se_multipliers`), the one pooling uses. Written by core `GET /v1/benchmark/evidence` row view (`services/benchmark.py`).

Source: packages/ump-spec/src/ump_spec/models/benchmark.py, line 34

BenchmarkCell

class

class BenchmarkCell(ArtifactDoc)

Fields

Name	Type	Default	Description
`vintage_id`	`str`
`vertical`	`str`
`channel`	`str`
`estimand_id`	`str`	`'E-BM-AVG-ROI'`
`method`	`Literal['DL', 'REML', 'bayes_hier']`	`'DL'`
`k`	`int`
`n`	`int`
`mu`	`float`
`se`	`float`
`tau`	`float`
`i2`	`float \| None`	`None`
`ci95`	`tuple[float, float]`
`pi95`	`tuple[float, float]`
`spend_shares`	`dict[str, float]`	`dict()`
`precision_shares`	`dict[str, float]`	`dict()`
`suppressed`	`bool`	`False`
`parent_cell_ref`	`str \| None`	`None`
`egger_flag`	`bool`	`False`
`released`	`bool`	`False`
`contributor_band`	`Literal['<5', '5-9', '10+'] \| None`	`None`
`notes`	`list[str]`	`list()`
`ci_method`	`Literal['hksj', 'wald', 'bayes_eti'] \| None`	`None`	§25.3 rule 4: HKSJ by default; Wald with DL, or ETI under a Bayesian model.
`construction`	`Literal['log_delta', 'reported_scale_log_link', 'bayes_hier'] \| None`	`None`	§25.3 rule 4a: delta-method log transform, or the reported-scale likelihood with a log link when any row is non-positive.
`contributors`	`list[str] \| None`	`None`	Salted client refs that contribute (internal view only; gives the exact k). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`superseded_rows`	`int \| None`	`None`	Rows set aside by the latest-refit rule (§25.3 rule 1; note SUPERSEDED_REFIT). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`ci_df`	`int \| None`	`None`	Degrees of freedom of the HKSJ t interval, k - 1 (internal view only). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`hksj_multiplier`	`float \| None`	`None`	HKSJ variance multiplier (internal view only). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`pi_note`	`str \| None`	`None`	How the prediction interval was built (internal view only). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`pooling_failed`	`str \| None`	`None`	Why no log-link cell mean exists (the cell is `empty`). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`empty`	`bool \| None`	`None`	No pooled estimate: mu, se and tau are placeholders. Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`shown`	`dict[str, Any] \| None`	`None`	The cell as a ShownNumber-like view: value, intervals, estimand and words. Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`parent_cell`	`dict[str, Any] \| None`	`None`	The cross-vertical parent cell, read in place of a suppressed cell (G-BM-04 Fall back). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`no_vertical_rows`	`bool \| None`	`None`	Placeholder for a channel with no row in this vertical (`fill_parents=true`). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`leave_one_out`	`bool \| None`	`None`	Pooled without one client (`exclude_client_ref`; note LEAVE_ONE_OUT). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`window`	`str \| None`	`None`	Rule 1 window applied: `all` or `four_quarters`. Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`proposed_thresholds`	`dict[str, Any] \| None`	`None`	The proposed benchmark parameters the cell was computed under. Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).
`reason`	`str \| None`	`None`	Public reason a suppressed cell is held (public view only). Written by core benchmark cells (`services/benchmark.py`; live cells, vintage rows).

Source: packages/ump-spec/src/ump_spec/models/benchmark.py, line 85

PriorCard

class

class PriorCard(ArtifactDoc)

Fields

Name	Type	Default	Description
`client_ref`	`str`
`estimand_id`	`str`	`'E-BM-AVG-ROI'`
`channel`	`str`
`source_cell`	`str`
`vintage_id`	`str`
`mixture_weight`	`float`	`0.8`	0.8, or 0.6 on parent-cell fallback (placeholder).
`mu`	`float`
`sd`	`float`
`wide_sd`	`float`	`1.0`
`parent_fallback`	`bool`	`False`
`client_id`	`str \| None`	`None`	Client the prior is for (the card also carries the salted `client_ref`). Written by onboarding and models (prior cards from the benchmark store, §25.6).
`source`	`str \| None`	`None`	Where the prior came from: `cell`, `parent` or `reference`. Written by onboarding and models (prior cards from the benchmark store, §25.6).
`best_guess`	`bool \| None`	`None`	True when the prior is a labelled best guess (parent cell or reference prior). Written by onboarding and models (prior cards from the benchmark store, §25.6).
`contributor_band`	`str \| None`	`None`	Contributor band of the source cell (`<5`, `5-9`, `10+`). Written by onboarding and models (prior cards from the benchmark store, §25.6).
`moderator_shift`	`float \| None`	`None`	Shift applied to mu for the client’s moderators (§25.6). Written by onboarding and models (prior cards from the benchmark store, §25.6).
`moderator_shift_assumed`	`bool \| None`	`None`	True when the shift was assumed, not computed. Written by onboarding and models (prior cards from the benchmark store, §25.6).
`formula`	`str \| None`	`None`	The mixture prior in words. Written by onboarding and models (prior cards from the benchmark store, §25.6).
`iroas`	`dict[str, Any] \| None`	`None`	The prior on the iROAS scale: median, lo, hi, level, sd_dollar. Written by onboarding and models (prior cards from the benchmark store, §25.6).
`proposed`	`bool \| None`	`None`	True while the mixture weights and widths are proposed values. Written by onboarding and models (prior cards from the benchmark store, §25.6).
`fallbacks`	`list[Any] \| None`	`None`	Fallback entries (code, gate, field, assumed, effect). Written by onboarding and models (prior cards from the benchmark store, §25.6).
`notes`	`list[str] \| None`	`None`	Note codes. Written by onboarding and models (prior cards from the benchmark store, §25.6).

Source: packages/ump-spec/src/ump_spec/models/benchmark.py, line 173

ReleaseLedgerEntry

class

class ReleaseLedgerEntry(StrictModel)

Fields

Name	Type	Default	Description
`id`	`str`
`client_ref`	`str`
`release_id`	`str`
`cell_or_stat`	`str`
`epsilon`	`float`
`year`	`int`

Source: packages/ump-spec/src/ump_spec/models/benchmark.py, line 230

StageFlag

class

class StageFlag(StrictModel)

Fields

Name	Type	Default	Description
`reached`	`bool`	`False`
`at`	`date \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/benchmark.py, line 239

ClientMaturity

class

class ClientMaturity(StrictModel)

Fields

Name	Type	Default
`client_ref`	`str`
`foundations`	`StageFlag`	`StageFlag()`
`model_live`	`StageFlag`	`StageFlag()`
`experimenting`	`StageFlag`	`StageFlag()`
`calibrated`	`StageFlag`	`StageFlag()`
`reallocating`	`StageFlag`	`StageFlag()`
`score`	`float`
`stage`	`str`
`pipeline_stage`	`dict[str, Literal['T0_fit', 'T1_prioritise', 'T2_design', 'T3_running', 'T4_calibrate', 'T5_reallocate']]`	`dict()`

Source: packages/ump-spec/src/ump_spec/models/benchmark.py, line 244

Constants

Name	Type	Value	Description
`SourceType`		`Literal['mmm_meridian', 'mmm_pymc', 'redacted_engine', 'mmm_robyn', 'mmm_vend...`
`PoolStatus`		`Literal['pooled', 'on_file', 'held_from_pool', 'decision_score', 'client_only']`
`MetricFamily`		`Literal['sales_return', 'brand_awareness', 'ad_recall', 'consideration', 'del...`
`BenchmarkRow`		`BenchmarkEvidence`