Enum

One label from an application-declared list, such as a currency code.

The amount 84.50 needs a currency to be interpreted consistently. Enum represents one label from an application-declared list, such as the currency codes this payment service accepts. Keep currency conversion and units in data preparation.

import relflow as rf

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

One labeled payment:

amount: 84.50
merchant: North Market
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.
strip	False	Trim surrounding whitespace from string labels, in values and in every input alike.
cased	True	False lowercases string labels, in values and in every input alike; declarations that collide after folding are rejected.

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.