Enum

Enum represents one label from a fixed list. Use it for payment currencies when the application already knows every allowed code.

import relflow as rf

model = rf.Model.xs(
    amount=rf.Number,
    currency=rf.Enum(values=("USD", "EUR", "GBP")),
    disputed=rf.Boolean(mask=True),
)

One labeled payment:

amount: 42.75
currency: USD
disputed: false

Every declared label is available immediately. Use Category when training data should introduce labels over time. Add mask=True to an Enum to predict one of its declared labels.

Input and options

values is a required, nonempty tuple of unique labels. Use one exact built-in Python type throughout the tuple: bool, int, float, str, or bytes. Mixed types, null labels, NaN, and infinity are rejected. For example, values=(1, 2, 3) declares integer labels; floating-point inputs must not be used in their place. Arrow widths may differ within the declared type family.

Null inputs are separate value states, not members of values. An input outside the declared set raises an error in training, validation, test, and prediction, including when the field is hidden by a mask. Use a preprocessor to normalize application-specific spellings or map unmatched inputs to a fallback label that you include in values.

Option	Default	Meaning
values	Required	Nonempty tuple of unique labels of one built-in type; tuple order defines their internal indices.
p_unavailable	0.01	Training probability of replacing known valued input content with unavailable content. Reconstruction targets remain unchanged.
topk	[]	Sorted, unique integer accuracy cutoffs greater than one; also controls prediction candidates. Each cutoff is capped by the declared label count.

See shared leaf options for reconstruction, masking, and embedding configuration. Since values is required, construct each field with rf.Enum(values=(...)).

Fixed vocabulary and learning

Declaration order fixes the embedding and decoder rows. Training updates their weights and records label counts without adding or reordering labels. All declared labels participate in reconstruction and prediction from the start, including labels that have not appeared in training.

labels = rf.Enum.vocabulary(model, rf.Address("currency"))
counts = rf.Enum.counts(model, rf.Address("currency"))

vocabulary returns the declared tuple. It also accepts a preprocessor’s encoding_context in place of model. counts returns pristine valued training exposures per declared label, including zero for unseen labels and excluding nulls and padding. Repeated epochs count again; counts synchronize across DDP ranks at epoch end. Evaluation and prediction do not update them.

Checkpoints preserve the declaration, learned weights, and counts. Rebuilding the model with the same declaration preserves its field state. Changing values with model.update(...), including changing their order, resets that field’s embedding, decoder, and counts.

Reconstruction uses unweighted state and categorical cross entropy. It shares the Category metrics, with every valid valued target inside the declared vocabulary.

Prediction

content contains value, probability, and topk. Probabilities are normalized over all declared labels. The candidate list has up to max(topk) entries, capped by the declared label count, and is empty when no cutoffs are configured. Labels are written as Arrow large_string, including when input labels are numeric or Boolean.

A declared label may receive a prediction before it has training examples; membership in the schema does not establish prediction quality. With only one declared label, its conditional probability is one. Read content probabilities alongside state and inferred in the prediction envelope.

The fixed-class proof compares informative and shuffled context. The withheld-class proof follows a declared class before and after it receives training examples. The held-out instruction proof tests whether familiar group and operation labels compose in combinations excluded from training.