Relational Transformers Utils

Utility tooling that wires Relational Transformers into a working product: context collection, normalization, ablation measurement, metrics, and checkpoint quantization. A second package, relben, holds RelBench benchmark utilities. Everything is pure Python over numpy and torch.

Applications own retrieval and encoding. This package covers the numeric steps between retrieved rows and a RelationalBatch, and the measurement steps after a prediction comes back. It contains no query language, no connectors, and no context-builder pipeline.

Installation

pip install -U relational-transformers-utils

What's Inside

Context collection (csc)

CscAdjacency is a compressed-sparse-column adjacency over foreign-key edges. Build it once from edge arrays, then answer time-bounded "latest children at or before this anchor" queries with one binary search each. CscIndex wraps a whole schema of caller-provided rows behind the same idea. Tie handling matches the RT-J reference byte for byte.

from relational_transformers_utils import CscIndex, TemporalBound

index = CscIndex.build(schema, {"customers": customer_rows, "orders": order_rows})
recent_orders = index.children(link, customer_id, TemporalBound.at_or_before(anchor), 16)

Normalization

ColumnStats fits per-column mean/std for numeric cells and one global normalizer for datetimes, with the reference preprocessor's exact conventions: sample std for columns, population std for datetimes, and 1.0 in place of a zero std. normalize_sequence turns one context's raw scalar cells into model-ready floats in zero-shot or reference mode, and bf16_as_f32 reproduces the bfloat16 storage boundary.

from relational_transformers_utils import ColumnStats, normalize_sequence

stats = ColumnStats.fit(schema, tables, bound=training_bound)
values = normalize_sequence(columns, sem_types, raw_values, is_target,
                            mode="reference", column_stats=stats)

Ablation

AblationEvaluator measures how much named groups of cells move a model's predictions across a dataset, through RelationalBatch.ablate and identity-activation scores.

from relational_transformers_utils import AblationEvaluator

metrics = AblationEvaluator(examples, {"support": [11, 12]})(model)

Metrics

Pure-numpy AUROC with tie-corrected rank sums, accuracy, Brier score, clamped log loss, bootstrap AUROC intervals, MAE, R², and a direction-aware better() comparator for model selection.

Quantizers

rt-quantize converts an RT-J checkpoint to FP8, row-wise int8, or packed int4. Every output loads through the standard relational-transformers constructor.

rt-quantize RelativeDB/rt-j-fp16 ./rt-j-int8 --format int8

Benchmarks (relben)

The curated 21-task RelBench catalog, keyed submission-CSV writers, atomic run records, score-matrix reports with gain-versus-baseline tables, and hurdle-gate tuning for zero-inflated regression targets.

from relben import select_tasks, write_submission

for task in select_tasks(["rel-f1"]):
    write_submission(out / task.filename, task.target, predictions[task.id])

Development

python -m pip install -e '.[dev]'
pytest

License

Apache License 2.0.