pytyche.experiment.cells

Cell (assignment cohort) + Policy protocol with shipped routing variants.

A round’s traffic is split across cells by weight; each cell routes its visitors through a Policy. assign returns the treatment’s integer index in the experiment’s treatments universe — shipped policies are constructed from treatment NAMES and resolve indices via the optional treatments universe (when omitted, UniformPolicy treats over as the universe and TreePolicy derives it from allocation-map key order, which the recommendation engine emits in universe order). Custom policies implement the two protocol members and handle their own mapping.

Module Attributes

WEIGHT_SUM_TOLERANCE

Cell-weight sums must hit 1.0 within this tolerance (spec-pinned).

Functions

validate_cell_weights(cells)

Raise ValueError unless the cells' weights sum to 1.0 (±1e-6).

Classes

BaselinePolicy()	Always routes to control (index 0).
Cell(id, policy, weight)	Assignment cohort within a single round.
Policy(*args, **kwargs)	Per-visitor treatment routing rule carried by a Cell.
TreePolicy(tree, allocation_map[, treatments])	Routes features through a fitted decision tree to a per-leaf allocation.
UniformPolicy(over[, treatments])	Uniform-random over a set of treatment names.

pytyche.experiment.cells.WEIGHT_SUM_TOLERANCE = 1e-06

Cell-weight sums must hit 1.0 within this tolerance (spec-pinned).

class pytyche.experiment.cells.Policy(*args, **kwargs)

Bases: Protocol

Per-visitor treatment routing rule carried by a Cell.

class pytyche.experiment.cells.Cell(id, policy, weight)

Bases: object

Assignment cohort within a single round.

weight is this cell’s share of the round’s traffic; weights across a round’s cells must sum to 1.0 (validated whenever a cell list is consumed — see validate_cell_weights()).

Parameters:

• id (str)

• policy (Policy)

• weight (float)

pytyche.experiment.cells.validate_cell_weights(cells)

Raise ValueError unless the cells’ weights sum to 1.0 (±1e-6).

Parameters:

cells (Sequence[Cell])

Return type:

None

class pytyche.experiment.cells.BaselinePolicy

Bases: object

Always routes to control (index 0). Ignores features.

class pytyche.experiment.cells.UniformPolicy(over, treatments=None)

Bases: object

Uniform-random over a set of treatment names.

treatments is the experiment’s full universe for index resolution; when None, over itself is the universe (the common case — the engine’s Explore cell and the round-1 default both pass the full active list as over).

Parameters:

• over (Sequence[str])

• treatments (Sequence[str] | None)

class pytyche.experiment.cells.TreePolicy(tree, allocation_map, treatments=None)

Bases: object

Routes features through a fitted decision tree to a per-leaf allocation.

allocation_map maps sklearn leaf ids to per-treatment-name weight dicts (each summing to 1.0). treatments is the index-resolution universe; when None it is derived from allocation-map key order (first-seen across leaves — the order the recommendation engine emits).

Parameters:

• tree (DecisionTreeClassifier)

• allocation_map (dict[int, dict[str, float]])

• treatments (Sequence[str] | None)