latent.prefect.sampling¶
Params-aware eval-set sampling with an effective-truncation stamp.
Distinct from latent.stats.sampling (context-free, DataFrame-shaped
representative sampling). This module is coupled to the flow params context:
it reads the canonical sample_size / sample_seed keys and records
whether truncation actually happened, so the publish step can stamp smoke-run
reports as sampled — a committed sample_size cap >= the dataset never
un-gates a full run.
Call apply_sampling in the flow body or a directly-awaited task, BEFORE
fanning out with .map(). A set of the truncation flag inside a mapped task
invocation does not propagate to the flow context (asyncio.gather runs
each invocation in a copied context) — sampling a collection before fan-out is
the supported shape.
The flag is scoped to a flow run by :func:push_truncation_scope /
:func:reset_truncation, which @latent.flow brackets its body with.
Prefect does not isolate ContextVars per flow run: without the scope, one
smoke run's set(True) stamps every later flow run in the same task
sampled, and enforcement then skips their gates.
Functions¶
apply_sampling¶
apply_sampling(items: Iterable[T], sample_size: int | None = None, seed: int | None = None) -> list[T]
Deterministically sample items down to the requested size.
Explicit kwargs win over params; params keys are sample_size and
sample_seed (default seed 42). Unset size, size 0, or
size >= len(items) returns the items unchanged (as a list) and leaves the
truncation flag untouched. Uses a private random.Random(seed) — never
the global random state.
effective_truncation¶
True only when apply_sampling actually truncated in this context.
push_truncation_scope¶
Open a truncation scope; pass the token to :func:reset_truncation.
The scope inherits the current flag (a parent that sampled still stamps
the reports its subflows publish) but cannot leak outward: resetting the
token restores whatever the flag was on entry. Re-setting the current value
is what creates that restore point — a plain set(False) would instead
strip the stamp from a subflow publishing a parent's sampled data.
requested_sample_size¶
Read the canonical sample_size params key.
Returns None when the key is unset, falsy (0 disables sampling), or when
no flow context is active. A non-integer value raises ValueError —
garbage config must fail loudly, not silently disable sampling.