ump_spec.models.client

module ump-spec

Client, profile and contract terms (onboarding, §20, §25.5, §25.9).

Classes

Licence

class

class Licence(StrictModel)

Fields

Name	Type	Default	Description
vendor	str
product	str | None	None
scope	Literal['pooled_use', 'client_only']	'client_only'
feed_cost	float | None	None	Annual feed cost in client currency.

Source: packages/ump-spec/src/ump_spec/models/client.py, line 92

MaterialityThresholds

class

class MaterialityThresholds(StrictModel)

G-MAT-01 thresholds, per account. All proposed (spec §15).

Fields

Name	Type	Default	Description
standard_spend	Proposed	Proposed(value=250000, source='§15')
full_spend	Proposed	Proposed(value=2000000, source='§15')
full_review_cost	Proposed	Proposed(value=25000, source='§15')
light_max_weeks_to_reverse	Proposed	Proposed(value=4, source="§15 'a month'")
full_min_weeks_to_reverse	Proposed	Proposed(value=13, source="§15 'a quarter'")

Source: packages/ump-spec/src/ump_spec/models/client.py, line 99

ContractTerms

class

class ContractTerms(StrictModel)

Fields

Name	Type	Default	Description
min_segment_size	int	50	G-PRIV-01 floor from the contract.
pool_opt_in	bool	True
opt_out_channels	list[str]	list()
licences	list[Licence]	list()
retention_days	int | None	None
query_budget	int | None	None	G-PRIV-03 aggregate query budget.
on_gate_fail	OnGateFail	'fallback'	Account policy (spec §15): a string for every gate or {gate_id: mode, ’*’: default}. A request never relaxes it.
strict_gates	list[str]	list()	Deprecated: read as on_gate_fail {gate_id: strict} entries.
materiality	MaterialityThresholds	MaterialityThresholds()

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

ClientProfile

class

class ClientProfile(StrictModel)

Fields

Name	Type	Default	Description
name	str
vertical	str		e.g. apparel, beverage, beauty, insurance.
annual_media_spend	float
currency	str	'USD'
annual_revenue	float | None	None
kpis	list[str]	lambda: ['revenue']()
channels	list[str]	list()	Shared-name media ids in use.
geos	list[str]	list()
contacts	list[str]	list()	Principal ids, never emails in leaves.
channel_spend	dict[str, float] | None	None	Optional annual spend per shared-name channel id. When present, maturity’s share_spend_with_test_or_cal uses it instead of the share of channels.

Source: packages/ump-spec/src/ump_spec/models/client.py, line 124

Client

class

class Client(ArtifactDoc)

Fields

Name	Type	Default	Description
id	str
client_ref	str		Salted hash used in pooled tables; client names never pooled.
profile	ClientProfile
contract	ContractTerms	ContractTerms()
maturity_stage	MaturityStage	'none'
maturity_score	float | None	None
pool_only	bool	False	Benchmark contributor without portfolio views.
created_at	datetime | None	None
onboarding_terms	dict[str, Any] | None	None	Onboarding contract terms beyond contract: clean room, data licences, vendors. Written by onboarding (wizard.py) and core’s client view (services/clients.view).
name	str | None	None	Core client view only: profile.name, served flat; not stored. Written by onboarding (wizard.py) and core’s client view (services/clients.view).
vertical	str | None	None	Core client view only: profile.vertical, served flat; not stored. Written by onboarding (wizard.py) and core’s client view (services/clients.view).
created_by	str | None	None	Core client view only: the principal that created the client; not stored. Written by onboarding (wizard.py) and core’s client view (services/clients.view).
updated_at	str | None	None	Core client view only: last change, RFC 3339; not stored. Written by onboarding (wizard.py) and core’s client view (services/clients.view).

Source: packages/ump-spec/src/ump_spec/models/client.py, line 139

Functions

gate_mode_map

function

def gate_mode_map(
    value: Any,
    *,
    pointer: str = '/on_gate_fail',
) -> dict[str, GateFailMode]

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.

Source: packages/ump-spec/src/ump_spec/models/client.py, line 28

resolve_gate_mode

function

def resolve_gate_mode(
    request: Any,
    account: Any = None,
    account_strict_gates: Iterable[str] = (),
) -> dict[str, GateFailMode]

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.

Source: packages/ump-spec/src/ump_spec/models/client.py, line 53

gate_mode_args

function

def gate_mode_args(
    effective: Mapping[str, GateFailMode],
) -> tuple[GateFailMode, list[str]]

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

Source: packages/ump-spec/src/ump_spec/models/client.py, line 68

gate_mode_header

function

def gate_mode_header(effective: Mapping[str, GateFailMode]) -> str

The UMP-On-Gate-Fail echo: the string when one mode covers every gate, else the object form as compact JSON with sorted keys.

Source: packages/ump-spec/src/ump_spec/models/client.py, line 83

salted_client_ref

function

def salted_client_ref(client_id: str, salt: str) -> str

cref_<16 hex>: salted ref for pooled tables (§25.9). Erasure deletes the salt.

Source: packages/ump-spec/src/ump_spec/models/client.py, line 170

Constants

Name	Type	Value	Description
MaturityStage		Literal['none', 'foundations', 'model_live', 'experimenting', 'calibrated', '...
GateFailMode		Literal['fallback', 'strict']	on_gate_fail: strict turns a gate fallback into a stop (spec §15).
GATE_MODE_KEY_RE		'^(\\*|G-[A-Z]+-[0-9]{2})$'
GateModeKey		Annotated[str, StringConstraints(pattern=GATE_MODE_KEY_RE)]
OnGateFail		GateFailMode | dict[GateModeKey, GateFailMode]	Spec §15: the string "fallback" or "strict" for every gate, or an object mapping gate ids to either value with "*" as the default key.
MATURITY_STAGES	tuple[str, ...]	('foundations', 'model_live', 'experimenting', 'calibrated', 'reallocating')