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
hf auth login

Authenticate with an account that has access to the model weights. Package installation does not grant weight access; the first fit downloads and caches the task's checkpoint. device="auto" uses CUDA when available, otherwise CPU. Use CUDA_VISIBLE_DEVICES=0 to select a GPU.

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.

Classification supports up to 10 classes; regression returns point predictions. Targets must not be missing. See runnable classification and regression examples.

Benchmarks

Official TabArena default-only evaluation: 51 datasets, 51 Lite splits and 816 Full splits, using 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.

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. Seeds must be nonnegative integers; the same inputs and seed reproduce the fitted permutations without changing global RNG state. Bitwise floating-point determinism is not forced.

Preprocessing and execution policies are fixed. Ensembles cycle through none, rank2gaussian, robust and power normalization. CUDA uses FP16 mixed precision, with regression column stages and both output heads in FP32; CPU uses FP32. Regression target scaling and output restoration use float64.

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. Refitting replaces the context; a failed fit leaves the estimator unfitted. 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. Automatic device selection runs again; an unavailable explicit device fails. 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.