An open accelerator for context generation over structured data.
NVIDIA Kumo Engine prepares connected records and their history for predictive modeling at scale. Its Rust-based DiskGraph engine indexes data on local SSDs and retrieves time-correct neighborhoods for training and batch prediction, without keeping the full graph index in RAM.
Define your tables, relationships, and prediction task in Python. Kumo Engine handles ingestion, graph construction, context sampling, training, evaluation, and prediction.
For example, to predict whether a customer will order in the next 30 days, Kumo Engine connects the customer to their order history and samples eligible records as model inputs.
Schematic example: the model plan determines sampling, and future outcomes remain outside the model inputs.
Benchmark highlight: One million three-hop neighborhoods in 19 seconds.
Documentation
Installation
Quick Tour
Benchmarks
- Context at scale: Retrieve connected records from an NVMe-backed graph index without keeping the full index in RAM.
- End-to-end workflows: Train and evaluate models, run batch predictions, generate embeddings, and save reloadable model bundles.
- Production ready: Ingest in parallel from S3, Snowflake, Databricks, BigQuery, and GCS.
- Existing data and infrastructure: Read files or connect to cloud storage and warehouses using existing compute and credentials.
- Compatible with agentic workflows: Agent skills let AI agents set up and run Kumo Engine workflows.
Browse the example collection for industry notebooks, standalone scripts, and synthetic-data generators for Kumo Engine and Structured Data Models.
See how to install Kumo Engine in a notebook, connect customer and order tables, and render their schema.
Predict which customers will order in the next 30 days using their connected order history. Try the Python quickstart with the bundled sample dataset.
For complete walkthroughs, follow the Google Colab, Snowflake, or Databricks notebook. Explore more tasks in Predictive Query Examples.
NVIDIA Kumo is a family of open models, libraries, and tools for predictive AI across tabular, relational, and time-series data, and a core part of the NVIDIA Agent Knowledge Foundation.
- NVIDIA Kumo Structured: pretrained foundation models (Kumo Tabular, Kumo Relational, Kumo Forecast, and Kumo Anomaly) that make predictions without training a model per task. Refer to NVIDIA/structured-data-models.
- NVIDIA Kumo Engine (this repository): an open accelerator for preparing connected structured data and training predictive models at production scale.
The published 1.0.0 wheel targets Linux x86-64 with glibc 2.34 or later and CPython 3.11 or later. The documented Linux setup uses Ubuntu 24.04 and Python 3.12. Prepare an NVIDIA GPU and local SSD working storage for the documented training workflows.
pip install kumo-engineThe base package reads local CSV and Parquet files. To read from a remote data source, install the matching optional dependency:
| Data Source | Installation |
|---|---|
| Amazon S3 | pip install "kumo-engine[s3]" |
| Google Cloud Storage | pip install "kumo-engine[gcs]" |
| BigQuery | pip install "kumo-engine[bigquery]" |
| Snowflake | pip install "kumo-engine[snowflake]" |
| Databricks | pip install "kumo-engine[databricks]" |
Refer to prerequisites and GPU sizing for a compatible runtime and storage capacity. Follow the setup guide for Linux, Snowflake notebooks, or Databricks notebooks. For an ARM64 source build, refer to the DGX Spark guide.
One million starting entities; synthetic graph: 50 billion nodes, 175.5 billion edges:
| Sampling Depth | Kumo Engine | Prepared DuckDB |
|---|---|---|
| 2 hops | 5 seconds | 4.0 minutes |
| 3 hops | 19 seconds | 5.3 minutes |
| 4 hops | 39 seconds | 6.5 minutes |
Both ran with warm caches on one AWS i4i.32xlarge: 128 vCPUs, 1 TiB RAM, and 30 TB local NVMe. Kumo Engine's 2.6 TiB index exceeded RAM. Timings exclude preparation and model training. Initial preparation took 49.8 minutes for DiskGraph and 40.1 minutes for DuckDB.
On a separate 111-million-node citation graph, Kumo Engine completed 15 training/validation epochs in 41 minutes 14 seconds, compared with 64 minutes 13 seconds for matched-model PyG. Test accuracy was 63.26% versus 63.93%; both used one g5.16xlarge with one A10G GPU.
Refer to the full benchmark report for experimental scope, preparation costs, memory measurements, and additional comparisons. Results depend on the workload and configuration.
| Goal | Start Here |
|---|---|
| Connect data, define graphs, train, and predict | User Code Guide |
| Configure sampling and training | Model Plan Guide |
| Use the in-process Python API | Local Python interface, imported as kumo.engine |
| Use a configured Kumo service from Python | Service client, imported as kumoai_studio |
| Run REST and the web UI on a single host | Compose topology |
| Deploy the application on Kubernetes | Application Helm chart |
| Explore deployment reference examples | Helm examples and support boundary |
For repository internals, refer to the architecture and engineering documentation index.
Report bugs or documentation problems in GitHub Issues, including the affected path and observed behavior. Keep credentials and private deployment details out of reports.
This project is currently not accepting contributions.
Development guides and source-checkout validation
Kumo-owned source is licensed under the Apache License 2.0. Vendored and incorporated third-party code retains its applicable licenses and attribution.
Component licenses and third-party attribution
Apache-licensed Python subprojects retain a copy of the root license at each package build root so it accompanies independently built wheels and source distributions. The nested component license files are:
Third-party attribution is recorded in the repository notice, Python distribution notice, UI catalog notice, and Helm stack notice.