Metadata-Version: 2.4
Name: relativedb
Version: 0.1.4
Summary: Predictive queries (RelQL) over your own data: GraphQL-style user-defined retrievers, no bundled database connectors.
Author: relativedb contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://relql.com
Project-URL: Repository, https://github.com/RelativeDB/RelQL
Project-URL: Issues, https://github.com/RelativeDB/RelQL/issues
Keywords: relational-transformer,predictive-query,relql,foundation-model,tabular,relational-deep-learning,zero-shot,inference-engine
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: relational-transformers>=0.1.0
Requires-Dist: relational-transformers-utils>=0.1.0
Requires-Dist: transformers>=4.40
Requires-Dist: huggingface_hub>=0.23
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Provides-Extra: triton
Requires-Dist: triton>=3.7; extra == "triton"
Provides-Extra: onnx
Requires-Dist: relational-transformers[onnx]>=0.1.0; extra == "onnx"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/RelativeDB/RelQL/main/website/static/img/logo.svg" alt="relativedb logo" width="120" />
</p>

# RelativeDB / RelQL

RelativeDB is an optimized implementation of Relational Transformers, exposed
through RelQL, a query language for predicting what happens next:

```sql
PREDICT NOT EXISTS(orders.*)
FROM customers
```

*"For every customer, what is the probability they don't place an order."*

RelativeDB works best with many tables (10–100) and needs no feature
engineering. Subgraphs are discovered automatically, though you can ablate
them to find what features really matter. Because it uses a pretrained model,
it works in environments with very little data.

```sql
# Auto-label a GitHub issue: predict its label from title, body, and history.
PREDICT issues.label
WHERE issues.label IS NULL

# Would customer 42 churn if we moved them to the premium plan?
PREDICT NOT EXISTS(orders.*)
FROM customers c
WHERE c.customer_id = 42
ASSUMING c.plan = 'premium'

# Expected spend per customer over the next quarter.
PREDICT SUM(transactions.price) OVER (90 DAYS FOLLOWING)
FROM customers

# The 12 articles each customer is most likely to buy next.
PREDICT ARRAY_AGG(transactions.article_id) OVER (30 DAYS FOLLOWING RANK TOP 12)
FROM customers
```

## Install

```bash
pip install relativedb                 # pure Python: parse, plan, assemble
pip install relativedb                 # includes the local model engine
```

Python 3.10 or newer. The base package is pure Python (numpy only): RelQL
parsing, planning, and context creation all run client-side, and the model is
reached through a **scoring backend** — either a cloud backend URL or the
optional in-process engine:

```python
engine = Engine(schema, wiring, model_backend="https://scoring.example.com")
# or, in process through relativedb.rt:
from relativedb.rt import RtBackend
engine = Engine(schema, wiring, model_backend=RtBackend(schema=schema))
```

`relativedb.rt` runs RT-J through the shared relational-transformers
runtime (torch on CPU/MPS/CUDA, Triton CUDA kernels, ONNX for exported
graphs) and embeds text with MiniLM in torch, imported lazily so query
planning never pays the torch import. relativedb never serves HTTP: remote
scoring goes through `RemoteBackend`, which calls the model gateway
(relational-transformers-gateway); the gateway imports this package to run
the model.

## Quickstart: 90-day churn from your own DataFrames

A sketch — `customer_dao`, `order_dao` and `t0` stand in for your storage and
your anchor time. A copy-paste runnable version with an in-memory database is
in the [repository README](https://github.com/RelativeDB/RelQL#the-python-library).

```python
from relativedb import (Schema, TableDef, LinkDef, ValueType,
                        RetrieverWiring, Engine, ExecutionInput, RtNativeBackend)

schema = (Schema.new_schema()
    .table(TableDef.new_table("customers")
        .column("age", ValueType.NUMBER)
        .column("signup_date", ValueType.DATETIME)
        .primary_key("customer_id").build())
    .table(TableDef.new_table("orders")
        .column("qty", ValueType.NUMBER)
        .column("order_date", ValueType.DATETIME)
        .primary_key("order_id").time_column("order_date").build())
    .link(LinkDef("orders", "customer_id", "customers"))
    .build())

wiring = (RetrieverWiring.new_wiring()
    .entities("customers", lambda table, ids, bound: customer_dao.by_ids(ids))
    .entities("orders",    lambda table, ids, bound: order_dao.by_ids(ids, bound))
    .default_links(lambda link, parent_id, bound, limit:
                   order_dao.recent_by_customer(parent_id, bound.as_of, limit))
    .build())

engine = Engine(schema, wiring, model_backend=RtBackend(schema=schema))
result = engine.execute(ExecutionInput(
    query="PREDICT NOT EXISTS(orders.*) OVER (90 DAYS FOLLOWING) FROM customers "
          "WHERE customers.customer_id IN :ids",
    params={"ids": ["C7"]},   # the cohort; drop the WHERE to score every customer
    anchor_time=t0))
```

## Checkpoints

Model checkpoints resolve through the Hugging Face cache on first use.
Quantized checkpoints (`RelativeDB/rt-j-fp8`, `-int8`, `-int4`) trade
footprint for precision:

| Checkpoint | On-disk | Accuracy | Download |
| --- | --- | --- | --- |
| fp32 | 342 MB | reference | — |
| fp16 | 172 MB | identical | [rt-j-fp16](https://huggingface.co/RelativeDB/rt-j-fp16) |
| int8 | 88 MB | ±0.01 | [rt-j-int8](https://huggingface.co/RelativeDB/rt-j-int8) |
| int4 | 64 MB | ±0.15 | [rt-j-int4](https://huggingface.co/RelativeDB/rt-j-int4) |

## The model

RelativeDB is based on:

- [stanford-star/relational-transformer](https://github.com/stanford-star/relational-transformer) — RT-J: Large-Scale Pretraining of Relational Transformers for Context-Efficient Predictions
- [Relational Transformer: Toward Zero-Shot Foundation Models for Relational Data](https://arxiv.org/abs/2510.06377) (arXiv:2510.06377)

## Development

```bash
pip install -e ".[dev]"

pytest -m "not integration"   # unit tier: no checkpoint, no network (<1s)
pytest -m integration         # native kernels + the real rt-j checkpoint
pytest                        # everything
```

Both tiers run from this directory or from the repository root. The unit
tier is pure Python — no native library, no checkpoint, no network. The
integration tier lives in `python/tests` and
resolves `hf://RelativeDB/rt-j-fp16/…` through the Hugging Face cache (~326 MB
fp32, plus ~128 MB for the pinned MiniLM text encoder).

Set `RELATIVEDB_REQUIRE_NATIVE=1` to make a missing library or an
unresolvable checkpoint a hard failure instead of a skip. CI sets it on the
integration job, so a cold or broken model cache turns the build red rather
than reporting "0 tests ran, all green".

Coverage:

```bash
pytest --cov=relativedb --cov-report=xml:coverage-python.xml --cov-report=term
```

## Docs

Read the [RelQL book](https://relql.com/docs/).

## License

Apache-2.0.
