Category

Use Category for one label from a bounded vocabulary: a country, product family, customer tier, or class. Use Set for multiple labels, Hash for identifier equality, and Text for word meaning.

merchant_category: grocery
fraud: false

import relflow as rf

model = rf.Model(
    d_model=64, n_layers=2, n_heads=4,
    merchant_category=rf.Category(size=128, topk=[3, 10]),
    fraud=rf.Boolean(mask=True),
)

Input and options

Accepts scalar Boolean, integer, floating-point, string, or binary labels. Keep one compatible Arrow type family per field; normalize inconsistent labels upstream. A null is a value state, not a vocabulary member.

Option	Default	Meaning
size	1024	Positive vocabulary capacity; capacity is also accepted. Embedding and decoder tables grow with it.
p_unavailable	0.01	Training probability of replacing a known valued label with unavailable content. Applied independently to input and target content.
topk	[]	Sorted, unique accuracy cutoffs satisfying 1 < k < size; also controls prediction candidates.

Capacity counts real labels only. Do not reserve an extra class for null or unavailable values. See shared leaf options for reconstruction and embedding configuration.

Vocabulary and learning

Pristine training observations add labels until capacity is full. Validation, test, and prediction reuse the learned mapping. The mapping is shared with encoding workers and synchronized for DDP; checkpoints preserve it.

See Online Vocabulary for admission order, capacity limits, worker synchronization, and reuse during fine-tuning.

An unknown label stays valued but contributes zero categorical content to the encoder. Its internal sentinel is not an extra embedding row or decoder class. Known labels contribute learned content plus their state embedding.

Reconstruction uses state cross entropy and frequency-weighted categorical cross entropy. Unavailable valued targets use a uniform target over all capacity logits and are excluded from content accuracy. Training scores the full capacity, including unpopulated slots.

For an application-supplied trained model:

labels = rf.Category.vocabulary(model, "record/merchant_category")
counts = rf.Category.counts(model, "record/merchant_category")

vocabulary returns a tuple snapshot in index order; counts returns pristine valued training exposures, excluding nulls, unavailable values, unused slots, and the smoothing prior. Repeated epochs count again; DDP counts synchronize at epoch end. vocabulary also accepts a preprocessor’s encoding_context. Consult it for inference preprocessing only: training preprocessing occurs before new labels are reserved.

Prediction

content contains value, probability, and topk. The candidate list has up to max(topk) entries, capped by the populated vocabulary; it is empty when no cutoffs are configured. Labels are written as large_string.

Probabilities are renormalized over populated labels, excluding unused capacity and the unavailable sentinel. An empty vocabulary yields a null best label and probability zero. Confidence is not an unknown-label detector. See the prediction envelope for shared state probabilities, inferred, and repeated shapes.