nvalchemi.gen.GenerationStage#

class nvalchemi.gen.GenerationStage(*values)[source]#

Stages of the AtomisticGenerator pipeline.

One stage per distinct point of the fixed pipeline (optionally condition the inputs, then generate — a Batch return takes the contract path). Hooks mutate the GenerationContext by replacing its fields, and the driver re-reads the context after each dispatch. Hooks at one stage run in list order, and a raising hook aborts the call (nothing catches it).

Firing policy: BEFORE_CONDITION/AFTER_CONDITION fire only when a condition step was provided for the call (the driver’s condition_func or the generating function’s condition attribute); AFTER_GENERATE fires only when the sample is a Batch.

BEFORE_CONDITION#

Fired before the condition step runs; ctx.inputs holds the call’s raw input (and ctx.batch holds it too when it is a Batch, None otherwise). Edit or replace ctx.inputs here — the condition callable receives whatever ctx.inputs holds after this dispatch. Fires only when a condition step was provided for the call.

AFTER_CONDITION#

Fired after the condition step; ctx.inputs holds the conditioned value the generating function is about to be called with (e.g. a conditioning Batch tiled by num_samples). Attach conditioning metadata (e.g. text embeddings for classifier-free guidance) or replace the conditioned input here. Fires only when a condition step was provided for the call.

AFTER_GENERATE#

Fired after generation when the sample is a Batch; ctx.batch holds it. A function returning a non-Batch container skips this stage. Filter or mutate the generated batch here — filtering is graph-level subsetting (ctx.batch = ctx.batch[keep]). The batch may already be zero-graph (a function may signal total rejection via empty()), so filters should tolerate num_graphs == 0. Zero-graph selections still raise IndexError — a hook signalling total rejection replaces ctx.batch with an explicitly built empty batch rather than subsetting to nothing.