ump_spec.models.planning

module ump-spec

Scenarios and optimisation results (spec §8 ladder, §12).

Classes

PlanLine

class

class PlanLine(StrictModel)

Fields

Name	Type	Default
`media_id`	`str`
`spend`	`float`
`region_id`	`str \| None`	`None`
`period`	`str \| None`	`None`
`cost_basis`	`Literal['net', 'gross']`	`'net'`

Source: packages/ump-spec/src/ump_spec/models/planning.py, line 17

ChannelResult

class

class ChannelResult(StrictModel)

Fields

Name	Type	Default
`media_id`	`str`
`spend`	`float`
`contribution`	`ShownNumber \| None`	`None`
`marginal_roi`	`ShownNumber \| None`	`None`
`outside_grid`	`bool`	`False`

Source: packages/ump-spec/src/ump_spec/models/planning.py, line 25

ScenarioResult

class

class ScenarioResult(StrictModel)

Fields

Name	Type	Default
`kpi`	`ShownNumber`
`per_channel`	`list[ChannelResult]`	`list()`
`ladder_step`	`LadderStep`	`'full_model'`
`dependence_used`	`DependenceKind \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/planning.py, line 33

Scenario

class

class Scenario(ArtifactDoc)

Fields

Name	Type	Default	Description
`client_id`	`str \| None`	`None`
`name`	`str \| None`	`None`
`model_id`	`str \| None`	`None`
`endpoint_alias`	`str \| None`	`None`
`model_revision`	`str \| None`	`None`	The model revision this scenario was scored on (spec §12). The older member name `revision` is read for one cycle.
`view`	`Literal['full', 'curves', 'table']`	`'full'`
`plan`	`list[PlanLine]`
`results`	`ScenarioResult \| None`	`None`
`assumptions`	`dict[str, Any]`	`dict()`
`author`	`str \| None`	`None`
`purpose`	`str \| None`	`None`
`group_id`	`str \| None`	`None`
`crn_seed`	`int \| None`	`None`
`thinning_index`	`str \| None`	`None`
`stale`	`bool`	`False`
`stale_since_version`	`int \| None`	`None`
`fallbacks`	`list[FallbackEntry]`	`list()`
`notes`	`list[Note]`	`list()`
`scenario_kind`	`str \| None`	`None`	Kind of scenario: `current`, `optimal`, `custom`, … Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`model_version`	`int \| None`	`None`	Version of the model the scenario was scored on. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`model_content_hash`	`str \| None`	`None`	Content hash of that model version (§6). Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`engine`	`str \| None`	`None`	What computed the scenario. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`ladder_step`	`str \| None`	`None`	Fallback-ladder rung the numbers came from (§8). Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`dependence`	`dict[str, Any] \| str \| None`	`None`	Dependence declaration used for the portfolio sums (§8). Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`total_spend`	`int \| float \| None`	`None`	Total planned spend. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`baseline_plan`	`dict[str, Any] \| None`	`None`	Baseline spend per channel. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`baseline_kpi`	`dict[str, Any] \| None`	`None`	Baseline KPI as a ShownNumber. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`uplift`	`dict[str, Any] \| None`	`None`	Uplift over the baseline as a ShownNumber. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`p_beat_plan`	`float \| None`	`None`	Probability the scenario beats the baseline plan. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`expected_regret`	`float \| None`	`None`	Expected regret against the per-draw best plan. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`objective`	`str \| None`	`None`	Optimiser objective: mean, p10 or cvar5. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`optimisation_result_id`	`str \| None`	`None`	The optimisation result this scenario came from. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`allocation`	`list[Any] \| None`	`None`	Allocation lines copied from the optimisation result. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`audit_level`	`int \| None`	`None`	Spec §13 audit level of the run that made it. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`trust_level`	`int \| None`	`None`	Trust level shown with the numbers. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`seed_key`	`str \| None`	`None`	Seed-run key that made this scenario (e2e seed only). Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`drafted_by`	`str \| None`	`None`	Agent principal that drafted the scenario. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`newton_session`	`str \| None`	`None`	Newton session that drafted this scenario. Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`reader_findings`	`list[str] \| None`	`None`	Reader finding ids the actor drew on (§17). Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`reader_findings_untrusted`	`list[str] \| None`	`None`	Reader finding ids marked untrusted text (§17). Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`injection_flagged_findings`	`list[str] \| None`	`None`	Reader findings flagged as possible prompt injection (§17). Written by planner (`service.py`) and Newton’s actor (`actor_tools.py`).
`legacy_members`	`frozenset[str]`	`frozenset({'revision'})`

Source: packages/ump-spec/src/ump_spec/models/planning.py, line 40

AllocationLine

class

class AllocationLine(StrictModel)

Fields

Name	Type	Default
`media_id`	`str`
`current_spend`	`float`
`optimal_spend`	`float`
`change_pct`	`float \| None`	`None`
`spend_interval`	`Interval \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/planning.py, line 168

OptimisationResult

class

class OptimisationResult(ArtifactDoc)

Fields

Name	Type	Default	Description
`client_id`	`str \| None`	`None`
`model_id`	`str \| None`	`None`
`engine`	`str \| None`	`None`
`objective`	`Literal['mean', 'p10', 'cvar5']`	`'mean'`
`total_budget`	`float`
`allocation`	`list[AllocationLine]`
`expected_kpi`	`ShownNumber`
`current_kpi`	`ShownNumber \| None`	`None`
`uplift`	`ShownNumber \| None`	`None`
`p_beat_plan`	`float \| None`	`None`
`expected_regret`	`float \| None`	`None`
`dependence`	`DependenceKind \| None`	`None`
`ladder_step`	`LadderStep`	`'full_model'`
`fallbacks`	`list[FallbackEntry]`	`list()`
`notes`	`list[Note]`	`list()`
`model_version`	`int \| None`	`None`	Version of the model optimised against. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`method`	`str \| None`	`None`	Optimiser method, e.g. slsqp or greedy. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`requested_objective`	`str \| None`	`None`	Objective the caller asked for. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`engine_requested`	`str \| None`	`None`	Engine the caller asked for. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`engine_version`	`str \| None`	`None`	Version of the engine that ran. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`engine_result`	`dict[str, Any] \| None`	`None`	The engine’s own result payload. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`engine_result_digest`	`str \| None`	`None`	Digest of the engine’s raw result. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`stub`	`bool \| None`	`None`	True when a stub engine produced the result. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`plan`	`dict[str, Any] \| None`	`None`	Optimal spend per channel. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`current_plan`	`dict[str, Any] \| None`	`None`	Current spend per channel. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`bounds`	`dict[str, Any] \| None`	`None`	Per-channel spend bounds `[lo, hi]`. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`per_channel`	`list[Any] \| None`	`None`	Per-channel spend and contribution ShownNumbers. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`convergence`	`dict[str, Any] \| None`	`None`	Optimiser runs and the one chosen. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`stability`	`dict[str, Any] \| None`	`None`	Share stability across reoptimised draws. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`per_draw_reoptimised`	`int \| None`	`None`	How many draws were reoptimised for stability. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`n_draws`	`int \| None`	`None`	Draws used. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`crn`	`dict[str, Any] \| None`	`None`	Common-random-numbers settings: seed, thinning index, draws. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`shadow_price`	`dict[str, Any] \| None`	`None`	Approximate value of the next dollar, with its definition. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`mode`	`str \| None`	`None`	Engine mode, e.g. single. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`kpi_results`	`list[Any] \| None`	`None`	Per-KPI results from the engine. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`contributions_note`	`str \| None`	`None`	How per-channel contributions were read. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`fit_id`	`str \| None`	`None`	Engine fit id the result was computed from. Written by planner (`optimise.py`, `service.py`) and the planner adapters.
`bundle_address`	`str \| None`	`None`	Workflow bundle address the engine ran (mapi-mmm). Written by planner (`optimise.py`, `service.py`) and the planner adapters.

Source: packages/ump-spec/src/ump_spec/models/planning.py, line 176

Constants

Name	Type	Value	Description
`LadderStep`		`Literal['full_model', 'curve_params', 'spend_table', 'summary', 'benchmarks',...`