rLLM: A PyTorch Library for Relational Table Learning with LLMs

The problem rLLM targets: tables that are actually several tables

Relational table learning sits between two communities that rarely share code. Tabular work, the kind ExcelFormer and Trompt belong to, assumes one flat table with rows and columns. Graph work assumes nodes and edges. Real enterprise data is neither: it is a set of tables joined by foreign keys, where a customer row links to order rows, which link to product rows. The README states rLLM handles this by treating various graphs (social, citation, e-commerce networks) as multiple tables linked by foreign keys. That is the framing the library is built on, and it is the reason the project exists rather than being another GNN package. The audience is narrow and identifiable: researchers who want to try whether an LLM adds anything to a tabular or relational prediction task, and who need the GNN and TNN baselines sitting next to it in the same codebase. The README also names a teaching role, supporting the SJTU undergraduate course Content Understanding (NIS4301) and the graduate course Social Network Analysis (NIS8023). A library that doubles as courseware tends to optimize for readable, self-contained examples rather than for deployment ergonomics, and that is what the examples directory suggests.

Combine, align, co-train: the module abstraction

The mechanism the README describes is a decomposition. State-of-the-art GNNs, LLMs and TNNs are each broken down into standardized modules, and novel models are then built by combining, aligning and co-training those modules. Read that as an interface contract: a graph encoder, a text encoder and a tabular encoder each expose a common shape so a new model is composition rather than a fork of an existing one. The practical consequence is that the library's value is concentrated in how uniform those module boundaries are. rLLM v0.1.1 is described in the news list as improving uniformity between Transform and Convolution operations, which is exactly the kind of internal change this design depends on. If the module signatures drift between the GNN side and the TNN side, the combine step stops being free. The README does not document the module base classes or their signatures, so the repository is the only place to check that. One design claim worth flagging: the library advertises one-fit-all potential by treating heterogeneous graphs as tables linked by foreign keys. That reframing is convenient, but it means the foreign-key structure has to be materialized somewhere before training, and the README does not say where that conversion happens or what it costs on a large schema.

Getting a first run: the BRIDGE example and its parameters

The documented entry point is deliberately small. The README's How to Try section shows the BRIDGE method under ./examples/bridge, with the comments that you should cd into that directory, set parameters if necessary, and then run python bridge.py. That is the whole quickstart: no install command, no pip line, no conda environment file is given in the README text. You will have to read the repository for dependency installation. The other model entry points follow the same pattern of one script per method: examples/inrtl.py, examples/ogc.py, examples/excelformer.py, examples/trompt.py, and a directory for TAPE under examples/tape. Parameter setting is left to the script itself, which the README acknowledges with the phrase set parameters if necessary. That phrasing is a signal about maturity: a library with a stable configuration surface usually documents the keys, and here the config keys are whatever each example script defines. The Todo List confirms the direction of travel, with code structure optimization, support for more TNNs and large-scale RTL training marked done, while GPU/TPU optimization and LLM prompt optimization remain unchecked. If your plan involves multi-GPU training or prompt tuning, both are listed as unfinished.

What is actually implemented, and how to read the version history

The README claims over 15 GNN and TNN models, and names a subset with paper links and example paths: InRTL (KDD 2026), OGC (TNNLS 2024), ExcelFormer (KDD 2024), TAPE (ICLR 2024) and Trompt (ICML 2023). The news list adds that OGC, ExcelFormer and Trompt were added in October 2024. The version trail is thin: rLLM v0.1 was released in July 2024 and v0.1.1 in January 2025, and no releases were retrieved for this review. Treat the version numbers as documentation of where the code stood at those dates rather than as a release cadence you can plan upgrades around. The model list is also the clearest statement of what the library is for. ExcelFormer and Trompt are pure tabular networks with no graph and no text. TAPE converts text attributes into language-model representations for a graph. InRTL is described as intra-inter interaction learning for relational tables. Those four span the space the library claims to unify, so a useful first check is whether each of those four example scripts actually shares the same module-level plumbing or whether they are four independent code paths wearing a common label.

Limitations the README itself exposes

The most concrete limitation is that this is research code with a teaching mandate. The contribution guide is hosted as a Google Drive file rather than in the repository, and contributions are subject to review by committers, which tells you the project is gated rather than open to drive-by patches. The todo list is honest about unfinished work: GPU/TPU optimization and LLM prompt optimization are both unchecked. If your workload is LLM-heavy, the second item matters, because prompt optimization is where most of the cost and most of the accuracy in a text-plus-table pipeline is decided. A second limitation is documentation depth. The README points to Read the Docs and to a paper on arXiv, and the quickstart is one command with an instruction to set parameters if necessary. There is no visible description of the dataset format for the three new relational table datasets the README mentions, only that they exist and include a standard classification task with examples. A third is scope: the library is not a serving system, not a feature store, and not a schema manager for the foreign-key conversion it assumes. If your problem is a single wide table and you want the best accuracy per engineering hour, a gradient-boosted tree baseline is the comparison you should make before reaching for any of this, including ExcelFormer, whose own paper title frames it as competing with GBDTs.

Where rLLM sits next to plain PyTorch Geometric

The obvious alternative for graph work is PyTorch Geometric, and the difference is not speed, it is the unit of composition. PyTorch Geometric gives you message-passing layers and data loaders and leaves model architecture to you. rLLM gives you whole named models (OGC, TAPE, ExcelFormer, Trompt, InRTL) plus a module convention intended to let you splice a GNN, a TNN and an LLM together. If your goal is a custom architecture, PyTorch Geometric is the lower-friction choice because nothing in it needs to agree with a foreign-key table abstraction. If your goal is to reproduce or extend one of the named methods, or to test whether adding a text encoder to a relational model helps, rLLM saves you the reimplementation. The second alternative is the one the README implicitly invites: a GBDT on engineered features. ExcelFormer's paper title, as quoted in the README, positions it as a neural network surpassing GBDTs on tabular data, which is a claim that only means something against that baseline. Running that baseline first is cheap and tells you whether the neural route is worth the module plumbing.

Maintenance, licensing and what to verify before adopting

The repository is MIT licensed and not archived, and the last push recorded is 2026-08-12, so the project is active rather than abandoned. Maintenance is described as coming from students and teachers at Shanghai Jiao Tong University and Tsinghua University, with funding listed from the National Natural Science Foundation of China, the Natural Science Foundation of Shanghai and the CCF-Huawei Populus Grove Fund. That is a real institutional backing structure, but it is also an academic one: staffing follows students, and the contribution guide's location outside the repository makes the review process opaque from the outside. MIT is permissive and imposes no copyleft obligation on your own code, which is the practical point for commercial use; this is a description of the licence identifier, not legal advice, and you should read the LICENSE file in the repository. Upgrade cost is the open question. With no retrieved releases and a jump from v0.1 to v0.1.1 that changed internal uniformity between Transform and Convolution operations, internal refactors have already happened once. Pin a commit rather than tracking main if you build anything on top of the module interfaces, and re-run your example script after any pull, because the module boundaries are precisely the surface a refactor like v0.1.1 would move.

Editorial conclusion

Adopt rLLM if you are doing research on relational tables and want ready-made implementations of Trompt, ExcelFormer, OGC, TAPE or InRTL behind one module interface, or if you want to experiment with combining a GNN, a TNN and an LLM in a single model. Do not adopt it as production tabular infrastructure: the README describes v0.1 and v0.1.1, there are no retrieved releases, GPU/TPU optimization and LLM prompt optimization are still open items on the todo list, and the contribution guide lives in a Google Drive link rather than the repository. Before committing, clone the repo, run python examples/bridge/bridge.py unchanged, then open examples/inrtl.py and examples/tape to check whether the module boundaries match the model you intend to build. Verify the MIT licence text in the repository itself rather than relying on this summary.

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. rllm-team/rllm on GitHub