fresh_cbm.family

Declared treatment-chain family for a state cache.

class fresh_cbm.family.ChainFamily(treatment: str, offsets: tuple[int, ...], events: int = 1, allow_empty: bool = True)[source]

Bases: object

The chains a cache is allowed to contain.

The current builder supports untreated plus exactly one event from a single treatment. Multi-event chains are rejected explicitly rather than producing a cache with an ambiguous family.

Parameters:

  • treatment (str) – Treatment name, such as "CC".

  • offsets (tuple of int) – Allowed event offsets.

  • events (int, optional) – Events per chain. Only one is supported. Defaults to one.

  • allow_empty (bool, optional) – Whether untreated rows are stored. Defaults to True.

Raises:

ValueError – When the treatment, offsets, event count, or empty policy is invalid.

chain(offset: int) → tuple[tuple[str, int], ...][source]

Return the chain for one offset.

Parameters:

offset (int) – Event offset.

Returns:

tuple of (str, int) – The one-event chain.

Raises:

ValueError – When the offset is outside the family.

offset_for(chain: tuple[tuple[str, int], ...]) → int[source]

Return the family offset for a chain.

Parameters:

chain (tuple of (str, int)) – A treatment chain.

Returns:

int – The event offset, or -1 for untreated.

Raises:

ValueError – When the chain is outside the family.

as_manifest() → dict[str, object][source]

Return the manifest representation.

Returns:

dict of str to object – The JSON-compatible family record.

classmethod from_manifest(raw: object) → ChainFamily[source]

Read a family from a manifest record.

Parameters:

raw (object) – Decoded chain_family value.

Returns:

ChainFamily – The parsed family.

Raises:

ValueError – When the record is malformed.