Cluster

Use Cluster for scalar labels represented through shared latent groups. It factorizes label representation into a label-to-cluster assignment and a cluster-to-model projection. It still keeps a bounded vocabulary; it does not eliminate per-label state.

merchant_id: merchant-8042
amount: 42.75
fraud: false

import relflow as rf

model = rf.Model(
    d_model=64, n_layers=2, n_heads=4,
    merchant_id=rf.Cluster(
        capacity=100_000,
        bounds=64,
        mask=rf.Mask(rate=0.15, reconstruct=True),
    ),
    amount=rf.Number,
    fraud=rf.Boolean(mask=True),
)

Use Category for independent label embeddings, or Hash for equality without a persistent vocabulary.

Input and options

Accepts scalar Boolean, integer, floating-point, string, or binary labels, with one compatible Arrow family per field. Training grows the vocabulary; validation, test, and prediction reuse it. Unknown labels remain valued and use a shared unavailable assignment. Nulls have a separate state.

See Online Vocabulary for capacity limits, admission timing with workers/DDP, and changes during fine-tuning.

Option	Default	Meaning
capacity	1024	Positive maximum number of learned labels.
bounds	required	Integer K fixes the cluster count; (lower, upper) enables adaptive committed clusters with 0 < lower <= upper. Stored as n_clusters.
p_unavailable	0.01	Training probability of replacing known labels with unavailable content, independently in input and targets.
ema_decay	0.99	Smoothing for usage and range-adherence statistics, in [0, 1].
revive_temperature	10.0	Nonnegative revival schedule control; zero disables inactive-cluster revival.

The upper bound fixes physical cluster width. Ranged bounds allow callbacks to revive inactive columns or merge similar active columns. They do not guarantee equal use or human-interpretable groups.

Learning and inspection

A reconstructing mask is required to train the cluster head and adaptive selection. A plain visible Cluster can influence other targets, but creates no cluster reconstruction loss of its own. See shared leaf options.

Reconstruction combines state classification with label recovery through clusters. Content accuracy excludes unknown labels. The decoder uses ancestor memory but opts out of direct sibling query conditioning.

For an application-supplied trained model:

labels = rf.Cluster.vocabulary(model, "record/merchant_id")
assignments = rf.Cluster.assignments(model, "record/merchant_id")
status = rf.Cluster.status(model, "record/merchant_id")

labels is an index-ordered tuple. Each assignment contains a cluster ID and probabilities across all configured columns. Status exposes committed column IDs and usage EMA; these inspection calls read local model state under DDP.

An idle model also supports rf.Cluster.assign(model, address, label, assignment) for persistent changes and rf.Cluster.override(model, address, assignments) as a temporary context manager. An assignment is a cluster ID or a nonnegative probability vector of upper-bound width summing to one. Adding a label consumes capacity. Overrides restore state on exit; saving or rebuilding during an open override is rejected.

Prediction

cluster contains the best cluster’s integer value and probability; content contains the best populated vocabulary label and its probability. Label probabilities are normalized over populated labels, excluding unused capacity and the unavailable row. Labels use large_string; an empty vocabulary yields a null label and zero probability.

See the prediction envelope for shared state probabilities, inferred, and repeated shapes.

The reconstructing Cluster proof reports internal convergence for repeated identities. Its page distinguishes that evidence from partition recovery and held-out prediction. The plain-input control shows why downstream supervision alone leaves adaptive Cluster state dormant.