Metadata-Version: 2.4
Name: causilo
Version: 1.0.0
Summary: Pretrained tabular classification and regression
Author-email: "Nums AI Inc." <contact@nums.world>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/nums-ai/causilo
Project-URL: Issues, https://github.com/nums-ai/causilo/issues
Project-URL: Models, https://huggingface.co/nums-ai/causilo
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.13
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: scikit-learn>=1.6
Requires-Dist: safetensors>=0.8
Requires-Dist: huggingface-hub>=0.28
Requires-Dist: psutil
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: joblib; extra == "dev"
Dynamic: license-file

# 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](https://github.com/nums-ai/causilo/blob/main/LICENSE) · [Causilo License v1.0 model weights](https://huggingface.co/nums-ai/causilo/blob/main/LICENSE) · [License & contact](#license--contact)

## Installation

Python 3.10–3.12 and PyTorch 2.13+ are required.

```bash
pip install causilo
hf auth login
```

Authenticate with an account that has access to the [model weights](https://huggingface.co/nums-ai/causilo). 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

```python
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](https://github.com/nums-ai/causilo/blob/main/examples/classification.py) and [regression](https://github.com/nums-ai/causilo/blob/main/examples/regression.py) 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.

| Suite   | Task           |   Elo position |   Elo ↑ |   Improvability ↓ |
|:--------|:---------------|---------------:|--------:|------------------:|
| Lite    | Overall        |              1 |  1817.4 |            0.0596 |
| Lite    | Classification |              1 |  1780.1 |            0.0747 |
| Lite    | Regression     |              1 |  2168.2 |            0.0155 |
| Full    | Overall        |              1 |  1792.9 |            0.0684 |
| Full    | Classification |              1 |  1771.8 |            0.0875 |
| Full    | Regression     |              1 |  2032.6 |            0.0125 |

![Overall performance](https://raw.githubusercontent.com/nums-ai/causilo/main/docs/benchmarks/overall.png)

*Overall — TabArena Full, classification and regression combined.*

<details>
<summary>Classification and regression</summary>

![Classification performance](https://raw.githubusercontent.com/nums-ai/causilo/main/docs/benchmarks/classification.png)

*Classification — TabArena Full, classification datasets only.*

![Regression performance](https://raw.githubusercontent.com/nums-ai/causilo/main/docs/benchmarks/regression.png)

*Regression — TabArena Full, regression datasets only.*

</details>

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

| Model    |   Fit (s/1k) |   Predict (s/1k) |   CPU (GiB) |   GPU (GiB) |
|:---------|-------------:|-----------------:|------------:|------------:|
| **Causilo** | **2.504** | **0.251** | **1.94** | 8.15 |
| TabICLv2 | 3.449 | 0.303 | 2 | 8.37 |
| TabPFN-3 | 4.18 | 0.686 | 2.87 | **0.88** |

Times are median seconds per 1,000 rows; memory is mean peak usage during fit only. [Protocol, task-level resources and complete leaderboards](https://github.com/nums-ai/causilo/blob/main/docs/benchmarks/README.md).

## Options

| Parameter | Default | Behavior |
| --- | --- | --- |
| `n_estimators` | `8` | Number of ensemble members to evaluate |
| `random_state` | `42` | Nonnegative integer seed for feature and class permutations |
| `device` | `"auto"` | One available CUDA device, otherwise CPU; explicit `"cpu"` or `"cuda:0"` is supported |
| `use_kv_cache` | `False` | Prepare and retain attention keys and values during fit |
| `retain_preprocessing` | `True` | Retain transformed training tables for later prediction |


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](https://github.com/nums-ai/causilo/blob/main/examples/cached_prediction.py).

## Fitted-state storage

```python
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](https://github.com/nums-ai/causilo/blob/main/examples/save_restore.py).

## License & contact

Code is licensed under [Apache-2.0](https://github.com/nums-ai/causilo/blob/main/LICENSE); model weights are separately licensed under [Causilo License v1.0](https://huggingface.co/nums-ai/causilo/blob/main/LICENSE). 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.
