Özgür Işık Damar
Data & Artificial Intelligence

Relational ML2026

RealPath

Answers predictive questions straight from related tables — leakage-tested and explained.

Open source · MIT · v0.1.0 alpha · GNN backend experimental

Source on GitHubRead the build notes
realpath · streamlit demo

Receipts

churn ROC-AUC on the synthetic sample database
0.749
examples/quickstart.ipynb
features changed by deleting every future row
0
tests/test_leakage.py
databases with an identical churn ROC-AUC
3
docs/BENCHMARKS.md
languages for plain-language questions
EN · TR
realpath/nlp.py

Every number comes from a file in the repository — the path is under it.

The problem

Business data lives in related tables — customers, transactions, returns — but mainstream models learn from one flat table. Flattening it takes hand-written joins and aggregations, repeated for every new question. And one aggregate computed past the prediction date lets the answer into the features: it shows up not as an error but as a score that looks too good.

The approach

RealPath reads the schema itself: keys and time columns are inferred from names, types and uniqueness, and the compiler for PQL, its predictive query language, finds the join path from the entity table to the target table on its own. Each task gets an anchor date: Featuretools' deep feature synthesis aggregates only rows at or before it, labels come from the query's time window, which every built-in template places after it (the compiler doesn't yet reject one that looks back), and a LightGBM model trained at one anchor is scored at a later one against what actually happened. A test deletes every row after the anchor and fails if a single feature changes; explanations read the same feature names back into tables and aggregations. Plain-language questions go to Claude when the Anthropic SDK and an API key are present, and its PQL must parse before it runs; otherwise offline templates cover churn, demand and return risk.

What's built

  1. Cross-table features lift churn ROC-AUC from 0.704 to 0.749 over the customer's own columns (sample DB)
  2. Keys and time columns are inferred, so a two-hop question such as customer return risk needs no SQL
  3. With the SHAP extra, “Why?” cards name join path, aggregation and value of a prediction's top contributions
  4. An LLM's PQL must parse before it runs; without an API key, offline templates keep questions local

Architecture

RealPath — The repo's pipeline diagram: schema inference, the PQL compiler and an anchor-safe temporal split feed DFS features, LightGBM and join-path explanations; RelBench/GNN stays optional.
The repo's pipeline diagram: schema inference, the PQL compiler and an anchor-safe temporal split feed DFS features, LightGBM and join-path explanations; RelBench/GNN stays optional.

Asked in plain English, “which customers will churn in the next 30 days?” matches the offline churn template (fixed 30-day window) and scores ROC-AUC 0.7492 on the synthetic sample DB.

1 / 4
// build notesDelete the future, diff the features: “no leakage” as a test, not a sloganRealPath's leakage claim is a pytest: delete everything after the anchor, rebuild, diff. What it caught when I broke the cutoff, and two leaks it still misses.Read the build notes

More 2026 builds