relational-transformer 1.8.0__tar.gz

relational_transformer-1.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Relational Transformer Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

relational_transformer-1.8.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: relational-transformer
+Version: 1.8.0
+Requires-Dist: beartype
+Requires-Dist: einops
+Requires-Dist: huggingface-hub
+Requires-Dist: ml-dtypes
+Requires-Dist: numpy
+Requires-Dist: orjson
+Requires-Dist: pandas
+Requires-Dist: polars
+Requires-Dist: pyarrow
+Requires-Dist: pyyaml
+Requires-Dist: safetensors
+Requires-Dist: scikit-learn
+Requires-Dist: sentence-transformers
+Requires-Dist: torch
+Requires-Dist: wandb
+Requires-Dist: matplotlib ; extra == 'dev'
+Requires-Dist: pre-commit ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: tqdm ; extra == 'dev'
+Requires-Dist: wandb-workspaces ; extra == 'dev'
+Requires-Dist: xgboost ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Relational Transformer (RT): a foundation model for relational data, bundling a native Rust data-processing engine (rt.rustler).
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# Relational Transformer (RT)
+
+The official implementation of the **Relational Transformer (RT)**, an
+architecture for **Relational Foundation Models (RFMs)** that predict directly
+over relational databases (tables linked by foreign keys) and generalize
+zero-shot to new databases, tasks, and schemas.
+
+| Paper | Venue | Implementation |
+|---|---|---|
+| [Relational Transformer: Toward Zero-Shot Foundation Models for Relational Data](https://arxiv.org/abs/2510.06377) | ICLR 2026 | [`rt-v1`](https://github.com/stanford-star/relational-transformer/tree/rt-v1) |
+| [PluRel: Synthetic Data unlocks Scaling Laws for Relational Foundation Models](https://arxiv.org/abs/2602.04029) | ICML 2026 | [`stanford-star/plurel`](https://github.com/stanford-star/plurel) |
+| RT-J: Large-Scale Pretraining of Relational Transformers for Context-Efficient Predictions | In progress | [`main`](https://github.com/stanford-star/relational-transformer) |
+
+## Installation
+
+Install the `rt` package (the model plus the native Rust data engine) from
+GitHub. It builds the extension from source, so you need a
+[Rust toolchain](https://rustup.rs) and Python 3.12+:
+
+```bash
+pip install "git+https://github.com/stanford-star/relational-transformer.git"
+```
+
+## Quickstart
+
+The quickest way to try a released checkpoint is on a RelBench
+database already preprocessed into RT's tensor format on the Hub. The example below predicts whether an F1 driver fails to finish a race (`driver-dnf`) with a released RT-J checkpoint:
+
+```python
+import os
+
+# flex_attention's compiled kernel is CUDA-only; run it eager on CPU/MPS
+os.environ.setdefault("TORCHDYNAMO_DISABLE", "1")
+
+import torch
+from huggingface_hub import snapshot_download
+
+from rt import RelationalTransformer
+from rt.eval import build_evaluator
+from rt.data import get_tasks
+
+device = (
+    "cuda" if torch.cuda.is_available()
+    else "mps" if torch.backends.mps.is_available()
+    else "cpu"
+)
+
+# 1. download one RelBench database, already preprocessed into RT's tensor format
+pre_dir = snapshot_download(
+    "stanford-star/relbench-preprocessed",
+    repo_type="dataset",
+    allow_patterns="rel-f1/*",
+)
+
+# 2. load a pretrained checkpoint (RT-J here)
+model = RelationalTransformer.from_pretrained(
+    "stanford-star/rt-j/classification", device=device
+).to(torch.bfloat16)
+cfg = model.config
+
+# 3. build an evaluator for one task and predict zero-shot for 5 test rows.
+#    the evaluator samples each row's context from the preprocessed DB;
+tasks = get_tasks(pre_dir, [("rel-f1", "driver-dnf")], ("test",),
+                  embedder=cfg["embedder"])
+ev = build_evaluator(
+    tasks, pre_dir,
+    embedder=cfg["embedder"], d_text=cfg["d_text"], device=device,
+    ctx_size=128, local_ctx_size=64, bfs_width=32, prefer_latest=True,
+    num_walks=10_000, walk_length=20, tokens_per_gpu=2**18,
+    items_per_task=5, num_workers=0, prefetch_factor=2,
+    shuffle_seed=0, context_seed=0, mmap_populate=True, vector_db_path=None,
+)
+
+# evaluate_raw yields one (task, ctx, labels, preds, n) per task
+results = ev.evaluate_raw([(model, "")], [128])
+_task, _ctx, _labels, out, _n = next(iter(results))
+preds = torch.sigmoid(torch.tensor(out[""], dtype=torch.float32))
+print("driver-dnf probability:", [round(p, 3) for p in preds.tolist()])
+```
+
+> [!NOTE]
+> `items_per_task=5` and `ctx_size=128` keep this demo quick (most of the runtime
+> is one-time warmup). On a GPU, raise `ctx_size` toward RT-J's training context of
+> 8192 (with `local_ctx_size <= ctx_size`) for full accuracy over the whole test
+> split.
+
+## Bring your own database
+
+Point RT at your **own** database, define a
+prediction task, and infer with a released checkpoint:
+
+- **Colab, no setup**: the [fully worked notebook](byod/colab.ipynb)
+  ([open in Colab](https://colab.research.google.com/github/stanford-star/relational-transformer/blob/main/byod/colab.ipynb))
+  runs the whole flow end-to-end on your database (or the bundled demo).
+
+## Development
+
+We use [pixi](https://pixi.sh) to manage one self-contained
+environment (Python, PyTorch + CUDA, Rust, and all dependencies), built on first
+use. There is nothing to build past `pixi install`: the native Rust extension is
+compiled as part of the project's own editable install.
+
+```bash
+git clone https://github.com/stanford-star/relational-transformer.git
+cd relational-transformer
+pixi run pytest                        # the test suite
+pixi run python examples/train.py      # or eval.py, preprocess.py, ...
+```
+
+## Documentation
+
+| Guide | Description |
+|---|---|
+| [Downloads](docs/downloads.md) | Bulk-download raw data, preprocessed data, and checkpoints from HuggingFace |
+| [Preprocess](docs/preprocess.md) | Convert RelBench-format databases into RT's on-disk format |
+| [Inference](docs/inference.md) | Run a trained checkpoint; evaluate, engineer, tune, and ensemble contexts |
+| [Pretrain](docs/train.md) | Train RT from scratch, single-GPU to multi-node |
+| [Experiments](expts/README.md) | How experiments in `expts/` are laid out and submitted to slurm |
+
+There is no CLI: RT is a library, and a run is a script that calls it. Copy
+something from [`examples/`](examples/) and edit it — every entry point takes
+its arguments explicitly, so nothing is hidden in a default you did not choose.
+

relational_transformer-1.8.0/README.md

@@ -0,0 +1,122 @@
+# Relational Transformer (RT)
+
+The official implementation of the **Relational Transformer (RT)**, an
+architecture for **Relational Foundation Models (RFMs)** that predict directly
+over relational databases (tables linked by foreign keys) and generalize
+zero-shot to new databases, tasks, and schemas.
+
+| Paper | Venue | Implementation |
+|---|---|---|
+| [Relational Transformer: Toward Zero-Shot Foundation Models for Relational Data](https://arxiv.org/abs/2510.06377) | ICLR 2026 | [`rt-v1`](https://github.com/stanford-star/relational-transformer/tree/rt-v1) |
+| [PluRel: Synthetic Data unlocks Scaling Laws for Relational Foundation Models](https://arxiv.org/abs/2602.04029) | ICML 2026 | [`stanford-star/plurel`](https://github.com/stanford-star/plurel) |
+| RT-J: Large-Scale Pretraining of Relational Transformers for Context-Efficient Predictions | In progress | [`main`](https://github.com/stanford-star/relational-transformer) |
+
+## Installation
+
+Install the `rt` package (the model plus the native Rust data engine) from
+GitHub. It builds the extension from source, so you need a
+[Rust toolchain](https://rustup.rs) and Python 3.12+:
+
+```bash
+pip install "git+https://github.com/stanford-star/relational-transformer.git"
+```
+
+## Quickstart
+
+The quickest way to try a released checkpoint is on a RelBench
+database already preprocessed into RT's tensor format on the Hub. The example below predicts whether an F1 driver fails to finish a race (`driver-dnf`) with a released RT-J checkpoint:
+
+```python
+import os
+
+# flex_attention's compiled kernel is CUDA-only; run it eager on CPU/MPS
+os.environ.setdefault("TORCHDYNAMO_DISABLE", "1")
+
+import torch
+from huggingface_hub import snapshot_download
+
+from rt import RelationalTransformer
+from rt.eval import build_evaluator
+from rt.data import get_tasks
+
+device = (
+    "cuda" if torch.cuda.is_available()
+    else "mps" if torch.backends.mps.is_available()
+    else "cpu"
+)
+
+# 1. download one RelBench database, already preprocessed into RT's tensor format
+pre_dir = snapshot_download(
+    "stanford-star/relbench-preprocessed",
+    repo_type="dataset",
+    allow_patterns="rel-f1/*",
+)
+
+# 2. load a pretrained checkpoint (RT-J here)
+model = RelationalTransformer.from_pretrained(
+    "stanford-star/rt-j/classification", device=device
+).to(torch.bfloat16)
+cfg = model.config
+
+# 3. build an evaluator for one task and predict zero-shot for 5 test rows.
+#    the evaluator samples each row's context from the preprocessed DB;
+tasks = get_tasks(pre_dir, [("rel-f1", "driver-dnf")], ("test",),
+                  embedder=cfg["embedder"])
+ev = build_evaluator(
+    tasks, pre_dir,
+    embedder=cfg["embedder"], d_text=cfg["d_text"], device=device,
+    ctx_size=128, local_ctx_size=64, bfs_width=32, prefer_latest=True,
+    num_walks=10_000, walk_length=20, tokens_per_gpu=2**18,
+    items_per_task=5, num_workers=0, prefetch_factor=2,
+    shuffle_seed=0, context_seed=0, mmap_populate=True, vector_db_path=None,
+)
+
+# evaluate_raw yields one (task, ctx, labels, preds, n) per task
+results = ev.evaluate_raw([(model, "")], [128])
+_task, _ctx, _labels, out, _n = next(iter(results))
+preds = torch.sigmoid(torch.tensor(out[""], dtype=torch.float32))
+print("driver-dnf probability:", [round(p, 3) for p in preds.tolist()])
+```
+
+> [!NOTE]
+> `items_per_task=5` and `ctx_size=128` keep this demo quick (most of the runtime
+> is one-time warmup). On a GPU, raise `ctx_size` toward RT-J's training context of
+> 8192 (with `local_ctx_size <= ctx_size`) for full accuracy over the whole test
+> split.
+
+## Bring your own database
+
+Point RT at your **own** database, define a
+prediction task, and infer with a released checkpoint:
+
+- **Colab, no setup**: the [fully worked notebook](byod/colab.ipynb)
+  ([open in Colab](https://colab.research.google.com/github/stanford-star/relational-transformer/blob/main/byod/colab.ipynb))
+  runs the whole flow end-to-end on your database (or the bundled demo).
+
+## Development
+
+We use [pixi](https://pixi.sh) to manage one self-contained
+environment (Python, PyTorch + CUDA, Rust, and all dependencies), built on first
+use. There is nothing to build past `pixi install`: the native Rust extension is
+compiled as part of the project's own editable install.
+
+```bash
+git clone https://github.com/stanford-star/relational-transformer.git
+cd relational-transformer
+pixi run pytest                        # the test suite
+pixi run python examples/train.py      # or eval.py, preprocess.py, ...
+```
+
+## Documentation
+
+| Guide | Description |
+|---|---|
+| [Downloads](docs/downloads.md) | Bulk-download raw data, preprocessed data, and checkpoints from HuggingFace |
+| [Preprocess](docs/preprocess.md) | Convert RelBench-format databases into RT's on-disk format |
+| [Inference](docs/inference.md) | Run a trained checkpoint; evaluate, engineer, tune, and ensemble contexts |
+| [Pretrain](docs/train.md) | Train RT from scratch, single-GPU to multi-node |
+| [Experiments](expts/README.md) | How experiments in `expts/` are laid out and submitted to slurm |
+
+There is no CLI: RT is a library, and a run is a script that calls it. Copy
+something from [`examples/`](examples/) and edit it — every entry point takes
+its arguments explicitly, so nothing is hidden in a default you did not choose.

relational_transformer-1.8.0/pyproject.toml

@@ -0,0 +1,133 @@
+[build-system]
+requires = ["maturin>=1.7,<2"]
+build-backend = "maturin"
+
+[project]
+name = "relational-transformer"
+version = "1.8.0"
+description = "Relational Transformer (RT): a foundation model for relational data, bundling a native Rust data-processing engine (rt.rustler)."
+readme = "README.md"
+license = { file = "LICENSE" }
+# 3.11, not 3.12: nothing in `src/` uses 3.12-only syntax or stdlib, and a
+# consumer that pins 3.11 (relarena does, `~=3.11.0`) cannot resolve this
+# package at all if the floor is 3.12. Development still happens on 3.12 --
+# that is what `[tool.pixi.dependencies]` asks for.
+requires-python = ">=3.11"
+# Runtime only: what an `import rt.<something>` actually reaches for. Anything
+# used by the repo's own tooling, experiments or plots belongs in `dev` below,
+# so installing this package as a *library* (relarena does) does not drag a
+# plotting stack and a pre-commit install into the consumer's environment.
+dependencies = [
+    # roach.slurm ships in this distribution and type-checks its arguments.
+    "beartype",
+    "einops",
+    "huggingface-hub",
+    "ml_dtypes",
+    "numpy",
+    "orjson",
+    "pandas",
+    "polars",
+    "pyarrow",
+    "pyyaml",
+    "safetensors",
+    # mean_absolute_error / roc_auc_score in rt.eval only. The former `<1.6`
+    # cap was inherited from a relbench pin, not from anything here.
+    "scikit-learn",
+    "sentence-transformers",
+    "torch",
+    # Imported at module scope by rt.train._train and rt.eval._eval, so it is a
+    # hard runtime dependency even for a run with `wandb_disabled=True`.
+    "wandb",
+]
+
+[project.optional-dependencies]
+# The repo's own tooling and experiments: the test suite, the pre-commit hooks,
+# the wandb workspace builder (expts/fine_tune/workspace.py), and the baselines
+# and plots under expts/. None of it is imported from `src/rt`.
+dev = [
+    "matplotlib",
+    "pre-commit",
+    "pytest",
+    "tqdm",
+    "wandb-workspaces",
+    "xgboost",
+]
+
+[tool.maturin]
+python-source = "src"
+manifest-path = "rustler/Cargo.toml"
+module-name = "rt.rustler"
+# The whole crate, FAISS aside (`vecdb` needs cmake and a BLAS; see rustler/Cargo.toml).
+features = ["pyo3/extension-module"]
+# Nothing extra. `roach` is slurm submission tooling, not part of RT, and lives
+# at the repo root beside `expts/` rather than under `python-source` -- a
+# consumer who `pip install`s this wants a relational transformer, not a batch
+# submitter. Experiments reach it because the bootstrap `cd`s to the checkout,
+# which is the same way they reach `expts`.
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# The repo root, so `examples.*` and `expts.*` import the same way in a test as
+# they do in a job (roach targets are module paths relative to the checkout).
+pythonpath = ["."]
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64"]
+
+# conda-forge's rust package writes an activation script that bakes the
+# environment's own prefix into the linker setting:
+#
+#   CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=<prefix>/bin/x86_64-conda-linux-gnu-cc
+#
+# Cargo hashes the per-target linker into every unit's fingerprint, including
+# registry crates that never invoke a linker, so a checkout at a new path
+# rebuilds the entire dependency tree however little changed. Pinning the bare
+# name -- the same binary, resolved through PATH, which puts this environment's
+# bin first -- makes the fingerprint independent of where the environment lives.
+# Measured: a second checkout of the same commit went from 3m39s to 15s.
+[tool.pixi.activation.env]
+CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER = "x86_64-conda-linux-gnu-cc"
+
+[tool.pixi.dependencies]
+# 3.12, not ">=3.12": on 3.14 the default multiprocessing start method on Linux
+# is forkserver rather than fork, and a forkserver child is built by *pickling*
+# the work over to it. rustler's Sampler is a pyo3 object and does not pickle,
+# so every DataLoader with workers dies with
+#
+#   TypeError: cannot pickle 'builtins.Sampler' object
+#
+# rt assumes fork throughout (see the comment in rt/_env.py about workers
+# inheriting the thread budget "at fork"). Pinning the interpreter is the
+# smaller change than making every dataset picklable, and it also puts this
+# environment inside relarena's own `requires-python`.
+python = "3.12.*"
+rust = "*"
+maturin = "*"
+uv = "*"
+
+[tool.pixi.pypi-dependencies]
+# The **released wheel**, not an editable install of this checkout. Experiments
+# must exercise the same artifact a user gets from `uv sync --extra rt`, because
+# that is the path that breaks silently: v1.1.0 shipped without
+# `_resolve_cutoff` and every one of our jobs was fine, running the checkout.
+# Bumping this is now part of changing `src/rt` -- `tests/test_release.py` fails
+# if the two drift apart.
+#
+# `expts/` is not packaged (`python-source = "src"`), so it still comes from the
+# checkout, which is what lets a submit script change without a release.
+relational-transformer = { url = "https://github.com/rishabh-ranjan/relational-transformer/releases/download/v1.7.0/relational_transformer-1.7.0-cp311-abi3-manylinux_2_28_x86_64.whl", extras = ["dev"] }
+# snap-stanford's relbench, exactly pinned -- NOT the rishabh-ranjan fork `main`
+# carries. This branch exists to run relarena's experiments (see
+# expts/relarena/), and relarena requires relbench 2.1.2: the package version is
+# the data version there (it ships the dataset checksums), and its Database /
+# get_dataset API is the 2.x one.
+#
+# Nothing in `src/rt` needs the fork for those experiments. `rt.preprocess`
+# mirrors relbench.hf rather than importing it; `rt.data.datasets` imports
+# relbench only to resolve a dataset's test timestamp, which is reached only
+# when `db_cutoff` is set, and relarena passes None because it hands RT a
+# database it has already censored; and `rt.eval.relbench` scores against
+# relbench's own evaluator, which relarena replaces with `task.evaluate`.
+# `main` keeps the fork -- this pin is this branch's, for this purpose.
+relbench = "==2.1.2"

relational_transformer-1.8.0/rustler/.gitignore

@@ -0,0 +1 @@
+/target/