Metadata-Version: 2.4
Name: causilo
Version: 1.0.1
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
```

The first fit automatically downloads and caches the task's [checkpoint](https://huggingface.co/nums-ai/causilo). `device="auto"` uses CUDA when available, otherwise CPU.

## 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 mean predictions by default and also supports median and quantile 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

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**

| Task           | Elo position | Elo ↑  | Improvability ↓ |
|:---------------|-------------:|-------:|----------------:|
| Overall        | 1 | 1792.9 | 0.0684 |
| Classification | 1 | 1771.8 | 0.0875 |
| Regression     | 1 | 2032.6 | 0.0125 |

<details>
<summary>TabArena Lite results</summary>

| Task           | Elo position | Elo ↑  | Improvability ↓ |
|:---------------|-------------:|-------:|----------------:|
| Overall        | 1 | 1817.4 | 0.0596 |
| Classification | 1 | 1780.1 | 0.0747 |
| Regression     | 1 | 2168.2 | 0.0155 |

</details>

![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. 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](https://github.com/nums-ai/causilo/blob/main/docs/inference.md) 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](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. 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.
