Causilo

Causilo is a pretrained tabular foundation model from Nums AI Inc., supporting classification and regression through a scikit-learn interface.

Apache-2.0 code · Causilo License v1.0 model weights · License & contact

Installation

Python 3.10–3.12 and PyTorch 2.13+ are required.

pip install causilo

The first fit automatically downloads and caches the task's checkpoint. device="auto" uses CUDA when available, otherwise CPU.

Quick start

from causilo import CausiloClassifier, CausiloRegressor

classifier = CausiloClassifier(n_estimators=8, random_state=42)
classifier.fit(X_train, y_train)
labels = classifier.predict(X_test)
probabilities = classifier.predict_proba(X_test)

regressor = CausiloRegressor(n_estimators=8, random_state=42)
regressor.fit(X_train, y_train)
predictions = regressor.predict(X_test)

Inputs can be NumPy arrays or pandas DataFrames, including categorical features and missing feature values. Use pandas categorical dtype for numeric category codes. NumPy object arrays infer numeric columns; strings and Booleans remain categorical. Prediction reuses the fitted schema, including handling unseen categories.

The classification checkpoint has a native 10-class head. Datasets with more classes are handled automatically through deterministic error-correcting output codes. Regression returns mean predictions by default and also supports median and quantile predictions. Targets must not be missing. See runnable classification and regression examples.

Benchmarks

Evaluated using the official TabArena pipeline: 51 datasets, 51 Lite splits and 816 Full splits, using the default configuration with eight estimators and seed 42. System methods are excluded. Full plots show the top 16 model families by their best Elo, with default, tuned and ensembled variants.

TabArena Full

Overall — TabArena Full, classification and regression combined.

Local H100 80 GB comparison, one GPU and eight physical CPU cores per job:

Times are median seconds per 1,000 rows; memory is mean peak usage during fit only. Protocol, task-level resources and complete leaderboards.

Options

Refit after changing options. Use device="cuda:0" to select a specific GPU, or CUDA_VISIBLE_DEVICES to control which GPUs are available.

Ensembles cycle through none, rank2gaussian, robust and power normalization. See inference details for quantile prediction, precision and reproducibility.

Repeated prediction

Set use_kv_cache=True to move reusable context computation into fit, trading additional device memory for repeated prediction speed. With retain_preprocessing=False, fitted transforms are retained but transformed training tables are recomputed. See cached prediction.

Fitted-state storage

import joblib

joblib.dump(classifier, "classifier.joblib")
restored = joblib.load("classifier.joblib")

Saved state includes fitted preprocessing and optional K/V caches, but excludes pretrained weights. Restoration loads the pinned checkpoint and reuses saved caches. It requires matching Causilo and dependency versions, including Python major/minor. See save/restore.

License & contact

Code is licensed under Apache-2.0; model weights are separately licensed under Causilo License v1.0. Non-commercial research and free research redistribution are permitted under its conditions. Commercial or production use, and hosted/API/SaaS services whether paid or free, require separate licenses. Contact contact@nums.world.