Metadata-Version: 2.4
Name: kumo-relational-engine
Version: 1.0.1
Summary: Relational driver (graph building, samplers, PQL, native neighbor-sampler) for the NVIDIA Kumo Relational Client
Author: NVIDIA
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/kumo-ai/kumo-relational-client
Project-URL: Source, https://github.com/kumo-ai/kumo-relational-client
Project-URL: Issues, https://github.com/kumo-ai/kumo-relational-client/issues
Keywords: deep-learning,graph-neural-networks,relational-foundation-model,predictive-query
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyarrow>=8.0.0
Requires-Dist: python-dateutil
Requires-Dist: requests>=2.28.2
Requires-Dist: urllib3
Requires-Dist: typing_extensions>=4.5.0
Requires-Dist: pydantic>=2.7
Requires-Dist: kumo-connectors<2,>=1.0
Requires-Dist: antlr4-python3-runtime==4.13.2
Requires-Dist: rich>=9.0.0
Requires-Dist: jinja2
Requires-Dist: tabulate
Provides-Extra: databricks-serving
Requires-Dist: databricks-sdk<1.0,>=0.68.0; extra == "databricks-serving"
Provides-Extra: snowflake-serving
Requires-Dist: snowflake-snowpark-python>=1.20; extra == "snowflake-serving"
Provides-Extra: test
Requires-Dist: packaging; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: requests-mock; extra == "test"
Provides-Extra: codegen
Requires-Dist: pyyaml; extra == "codegen"
Provides-Extra: explain
Requires-Dist: openai>=1.40; extra == "explain"
Provides-Extra: relbench
Requires-Dist: pooch; extra == "relbench"
Requires-Dist: tqdm; extra == "relbench"
Provides-Extra: sqlite
Requires-Dist: kumo-connectors[sqlite]; extra == "sqlite"
Provides-Extra: duckdb
Requires-Dist: kumo-connectors[duckdb]; extra == "duckdb"
Provides-Extra: snowflake
Requires-Dist: numpy<2.0; extra == "snowflake"
Requires-Dist: kumo-connectors[snowflake]; extra == "snowflake"
Requires-Dist: pyyaml; extra == "snowflake"
Provides-Extra: databricks
Requires-Dist: kumo-connectors[databricks]; extra == "databricks"
Requires-Dist: pyyaml; extra == "databricks"
Provides-Extra: postgres
Requires-Dist: kumo-connectors[postgres]; extra == "postgres"
Dynamic: license-file
Dynamic: requires-dist

# kumo_relational_engine

The Kumo Relational driver for the [`kumo-relational-client`](../kumo-relational-client/README.md) client.

This distribution provides the heavy, client-side machinery a Kumo Relational prediction
needs before a request reaches a NIM: the relational `Graph`/`Table` abstractions,
the neighbor samplers (local native `relationallib`, plus DuckDB / SQLite / Snowflake /
Databricks / PostgreSQL backends), the PQL parser, and the HTTP client that talks to a Universal
TFM NIM.

It is imported as `kumo_relational_engine` and is normally installed transitively via the client's
`relational` extra rather than on its own:

```bash
pip install kumo-relational-client[relational]      # pulls the kumo_relational_engine driver
```

It can also be installed on its own, for the graph, sampler and PQL machinery.
Predicting is not available that way: the engine's entry points refuse a direct
call, so a prediction has to go through `kumo-relational-client`.

```bash
pip install kumo-relational-engine
# optional data backends:
pip install "kumo-relational-engine[duckdb]"      # or [sqlite] / [snowflake] / [databricks] / [postgres]
# optional features:
pip install "kumo-relational-engine[explain]"     # natural-language explanation summaries
pip install "kumo-relational-engine[relbench]"    # Graph.from_relbench() dataset loading
pip install "kumo-relational-engine[codegen]"     # regenerate the TFM API client (see scripts/)
```

`Graph.from_postgres()` reads existing PostgreSQL tables:

```python
import psycopg
from kumo_relational_client import relational

connection = psycopg.connect(
    host=host,
    dbname=database,
    user=user,
    password=credential,
    sslmode='require',
)
graph = relational.Graph.from_postgres(connection, schema='public')
```

`schema` is the table namespace; omit it to use `current_schema()` (`public` is
the usual default). `connection` may instead be a PostgreSQL URI/libpq string
or a dictionary of psycopg arguments; if omitted, psycopg uses `PG*` environment
variables. See [`postgres.py`](examples/rfm/postgres.py). Lakebase uses this same
API through its PostgreSQL endpoint with TLS and either an OAuth token or an
enabled native Postgres password. It reads existing tables directly—without
Unity Catalog registration, copying data, or DDL.

Temporal sampling returns at most the requested latest N rows at or before each
anchor, ordered by time descending then primary key ascending. For large fact
tables, an index on `(foreign_key, time_column DESC, primary_key)` improves this
pushed-down query; the SDK never creates indexes or modifies source tables.

Release wheels are built for CPython 3.10, 3.11, 3.12 and 3.13 on Linux
x86-64 and ARM64 (`manylinux_2_28`), macOS 11 and later on Intel and Apple
silicon, and Windows x64. Windows on ARM64 has no wheel, and no source
distribution is published.

Application code should import the client's neutral surface, not this package
directly:

```python
from kumo_relational_client import RelationalClient, relational

graph = relational.Graph.from_data({'users': df1, 'items': df2, 'orders': df3})
with RelationalClient(url='http://localhost:8000') as client:
    result = client.relational(graph).predict(
        'PREDICT SUM(orders.price, 0, 30, days) FOR items.item_id=1'
    )
```

## Local development

```bash
pip install -e ".[test,databricks]"
pytest tests -m "not live_nim"
```

The live-NIM suite (`scripts/run_rfm_nim_live_tests.sh --full`) includes durable,
ticket-free rejection regressions for fixed NIM defects; every rejection probe is
followed by a known-good prediction to detect service degradation.

The native neighbor sampler (`kumo_relational_engine.relationallib`) is built from
`src/kumo_relational_engine/csrc/neighbor_sampler.cpp` via CMake/scikit-build-core. Set
`WITH_RELATIONALLIB=0` to skip the native build for a pure-Python editable install.
