Metadata-Version: 2.4
Name: relational-transformers-utils
Version: 0.1.0
Summary: Context collection, normalization, metrics, quantization, and benchmark utilities for Relational Transformers
Author: RelativeDB
License: Apache-2.0
Project-URL: Homepage, https://relql.com
Project-URL: Documentation, https://utils.relationaltransformers.com
Project-URL: Repository, https://github.com/RelativeDB/relational-transformers-utils
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: torch>=2.2
Requires-Dist: safetensors>=0.4
Requires-Dist: relational-transformers>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: docs
Requires-Dist: myst-parser>=3; extra == "docs"
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
Requires-Dist: sphinx-inline-tabs>=2023.4.21; extra == "docs"
Requires-Dist: sphinx-toolbox>=3.5; extra == "docs"
Dynamic: license-file

# Relational Transformers Utils

Utility tooling that wires [Relational Transformers](https://relationaltransformers.com)
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

```bash
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.

```python
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.

```python
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.

```python
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.

```bash
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.

```python
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

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

## License

Apache License 2.0.
