Metadata-Version: 2.5
Name: zerograd
Version: 0.2.2
Summary: Predictions over your tabular data with open foundation models (TabPFN, TabICL, Mitra, TabDPT). Nothing to train.
Project-URL: Homepage, https://zerograd.dev
Project-URL: Documentation, https://zerograd.dev/docs
Project-URL: Source, https://github.com/zerogradlabs/zerograd-python
Project-URL: Issues, https://github.com/zerogradlabs/zerograd-python/issues
Author: ZeroGrad
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: automl,classification,foundation-models,mitra,regression,tabdpt,tabicl,tabpfn,tabular
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25
Requires-Dist: huggingface-hub>=0.23
Requires-Dist: numpy>=1.25
Requires-Dist: pandas>=1.5
Requires-Dist: pyarrow>=12
Requires-Dist: safetensors>=0.4
Requires-Dist: scikit-learn>=1.3
Requires-Dist: tabicl>=2.0
Requires-Dist: tabpfn>=2.1
Requires-Dist: torch>=2.5
Provides-Extra: all
Requires-Dist: autogluon-tabular[mitra]>=1.6; extra == 'all'
Requires-Dist: tabdpt>=1.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: matplotlib>=3.5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: local
Provides-Extra: mitra
Requires-Dist: autogluon-tabular[mitra]>=1.6; extra == 'mitra'
Provides-Extra: tabdpt
Requires-Dist: tabdpt>=1.1; extra == 'tabdpt'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/banner-dark.gif">
    <source media="(prefers-color-scheme: light)" srcset="docs/banner-light.gif">
    <img alt="ZeroGrad: one Python interface to tabular foundation models" src="https://raw.githubusercontent.com/zerogradlabs/zerograd-python/main/docs/banner-light.gif" width="100%">
  </picture>
</p>

<p align="center">
  <a href="https://pypi.org/project/zerograd/"><img alt="PyPI" src="https://img.shields.io/pypi/v/zerograd"></a>
  <a href="https://github.com/zerogradlabs/zerograd-python/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/zerogradlabs/zerograd-python/actions/workflows/ci.yml/badge.svg"></a>
  <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-blue"></a>
  <a href="https://colab.research.google.com/github/zerogradlabs/zerograd-python/blob/main/examples/quickstart.ipynb"><img alt="Open in Colab" src="https://colab.research.google.com/assets/colab-badge.svg"></a>
</p>

## Tabular foundation models

The usual way to predict something from a table (churn, fraud, default, demand) is to train a model for that
problem: pick an algorithm, tune it, validate it, retrain it when the data changes.

Tabular foundation models work differently. They are pretrained once, on millions of synthetic datasets, to learn
*in context*: you give them your labeled rows as context and they predict new rows in a single forward pass, with no
training and no hyperparameters. On small and medium tables they are competitive with tuned gradient boosting.

Several research groups have released them: TabPFN (Prior Labs), TabICL (Inria), Mitra (Amazon), TabDPT (Layer 6)
and others. Each comes with its own package, checkpoints, preprocessing and license.

## What ZeroGrad does

ZeroGrad puts them behind one interface. The same two calls, `create` and `predict`, work with every model, on your
machine or on the ZeroGrad platform. On top of that:

* **A championship instead of a guess.** Which model is best depends on the data. ZeroGrad scores every model on the
  same holdout of your rows and keeps the best one as the champion, with the comparison in a table.
* **Licenses you can see.** Some models allow commercial use and some do not. `zerograd.list_models()` shows each
  license and where the weights come from; non-commercial models stay off unless you enable them by name.
* **Local or cloud, same code.** Locally, nothing leaves your machine. With `remote=True` the same capability runs on
  the platform, with versions, scheduled championships, monitoring and batch pipelines.

## Quickstart

```bash
pip install zerograd
```

```python
from zerograd import ZeroGrad

zg = ZeroGrad()                                        # local: runs on your machine
cap = zg.create("churn", examples=history, target="churned")
cap.evaluation                                         # every model on the same holdout; the champion is marked
cap.predict(new_customers)                             # prediction, score and probability per class
```

<p align="center"><img src="https://raw.githubusercontent.com/zerogradlabs/zerograd-python/main/docs/demo.gif" alt="A ZeroGrad championship in the terminal" width="760"></p>

Open source under Apache 2.0. Try it without installing anything, in Colab:

| Notebook | What it shows | |
|---|---|---|
| [Six use cases](examples/use-cases.ipynb) | The whole SDK in one run: churn, house prices, cross-validation and thresholds, anomalies, clustering, and outcomes on the platform with a key | [Open in Colab](https://colab.research.google.com/github/zerogradlabs/zerograd-python/blob/main/examples/use-cases.ipynb) |
| [Quickstart](examples/quickstart.ipynb) | Model catalog, a championship on breast cancer data, predictions, saving, and a context curve on Adult | [Open in Colab](https://colab.research.google.com/github/zerogradlabs/zerograd-python/blob/main/examples/quickstart.ipynb) |
| [Titanic](examples/titanic.ipynb) | A championship you check against your own holdout, one-row predictions, how much history you need, multiclass | [Open in Colab](https://colab.research.google.com/github/zerogradlabs/zerograd-python/blob/main/examples/titanic.ipynb) |
| [Evaluate and decide](examples/evaluation.ipynb) | Cross-validation at random, by customer and by date, a threshold by the cost of each mistake, column importance, scikit-learn | [Open in Colab](https://colab.research.google.com/github/zerogradlabs/zerograd-python/blob/main/examples/evaluation.ipynb) |
| [Without a target](examples/no-target.ipynb) | Anomalies with the columns why, imputation, synthetic rows scored by detection AUC, clustering with profiles | [Open in Colab](https://colab.research.google.com/github/zerogradlabs/zerograd-python/blob/main/examples/no-target.ipynb) |

## Install

```bash
pip install zerograd                  # local engine with TabPFN v2 and TabICLv2
pip install "zerograd[all]"           # adds Mitra-v2 and TabDPT
```

Python 3.10+. A GPU helps but is not required: on CPU, histories up to a few thousand rows take seconds to
minutes. Weights download from each model's official Hugging Face repository the first time you use it and
are cached there (`HF_HOME`); ZeroGrad hosts none. Importing zerograd or building `ZeroGrad()` downloads nothing.

```python
zerograd.download(["tabpfn-v2"])          # fetch now instead of on first use, e.g. before a demo without wifi
zerograd.cached_weights()                 # what is on disk, how big, and whether ZeroGrad downloaded it
zerograd.remove_weights()                 # delete what ZeroGrad downloaded; the next run fetches it again
zerograd.config(auto_remove_weights=True) # or ZEROGRAD_AUTO_REMOVE_WEIGHTS=1: delete this session's downloads at exit
```

ZeroGrad keeps a list of the files it downloaded, so `remove_weights` never touches weights another project put in
your Hugging Face cache. With auto-remove on, the files go when the Python process ends normally (a script
finishing, a notebook kernel shutting down or restarting), not if it is killed.

## What models are there?

```python
import zerograd

zerograd.list_models()                                  # every model: tasks, license, commercial use, installed
zerograd.list_models(task="classification", commercial=True)
zerograd.list_tasks()                                   # every task and which models do it
zerograd.list_models().to_frame()                       # as a DataFrame
```

In a notebook these render as tables with a badge for commercial and non-commercial use. In this version:

| Model | Name | License | Commercial use | Default |
|---|---|---|---|---|
| TabPFN v2 | `tabpfn-v2` | Prior Labs License (Apache 2.0 + attribution) | yes | yes |
| TabICLv2 | `tabicl-v2` | BSD-3-Clause | yes | yes |
| Mitra-v2 | `mitra-v2` | Apache 2.0 | yes | yes, with `pip install "zerograd[mitra]"` |
| TabDPT | `tabdpt` | Apache 2.0 | yes | yes, with `pip install "zerograd[tabdpt]"` |
| Mitra | `mitra` | Apache 2.0 | yes | by name |
| FoMo-0D | `fomo-0d` | MIT | yes | anomaly detection |
| ZEUS | `zeus` | Apache 2.0 | yes | clustering |

The full list, with sources and the models that are off by default, is in [MODELS.md](MODELS.md).
This version runs **classification** (binary and multiclass, up to 10 classes) and **regression** (locally, with
TabPFN v2, TabICLv2 and TabDPT), plus four tasks with no target: anomaly detection, imputation, synthetic data and
clustering. `zerograd.list_tasks()` shows which models run each task.

## Benchmark

We ran 12 OpenML classification datasets and 6 regression datasets, 3 seeds each. The champion
is picked on the training rows only, and every number below comes from a 20% test split that nothing saw during
selection. The baseline is scikit-learn's HistGradientBoosting with default settings, and regression also gets Ridge
as a linear baseline.

| | champion against HistGradientBoosting (wins / ties / losses) |
|---|---|
| ROC AUC | 11 / 0 / 1 (mean 0.894 against 0.866) |
| Log loss | 12 / 0 / 0 (0.323 against 0.454) |
| Brier score | 12 / 0 / 0 |
| Accuracy | 10 / 1 / 1 |
| Regression RMSE | 6 / 0 / 0 (and 6 / 0 / 0 against Ridge) |

The one loss is churn, by 0.004 of ROC AUC: TabPFN v2 alone would have won it, but the championship picked another
model on the training rows. Per-dataset tables for every model are in [benchmarks/RESULTS.md](benchmarks/RESULTS.md), and
`python benchmarks/run.py` reproduces them.

## What the SDK can do

Everything below is explained, with code, in the [docs](https://zerograd.dev/docs).

* **[Championship](https://zerograd.dev/docs#how-it-works):** every model scored on the same holdout of your rows, with the champion and baselines in one table.
* **[Predictions](https://zerograd.dev/docs#predict):** a DataFrame or a single row in, the prediction, score and probabilities out.
* **[Classification](https://zerograd.dev/docs#classification) and [regression](https://zerograd.dev/docs#regression):** binary and multiclass (up to 10 classes), or numeric targets, picked automatically.
* **[Context size](https://zerograd.dev/docs#context-size):** find how many rows of history you need, trading a little quality for much faster predictions.
* **[Evaluation](https://zerograd.dev/docs#evaluation):** [cross-validation](https://zerograd.dev/docs#cross-validation) at random, by group or by time, [thresholds](https://zerograd.dev/docs#optimize-threshold) chosen by the cost of each mistake, and [column importance](https://zerograd.dev/docs#importance).
* **[scikit-learn](https://zerograd.dev/docs#sklearn):** `ZeroGradClassifier` and `ZeroGradRegressor` work in pipelines, grid search and `cross_val_score`.
* **[No target](https://zerograd.dev/docs#no-target):** [anomaly detection](https://zerograd.dev/docs#anomaly-detection) with the columns why, [imputation](https://zerograd.dev/docs#imputation), [synthetic data](https://zerograd.dev/docs#synthetic-data) and [clustering](https://zerograd.dev/docs#clustering).
* **[Privacy](https://zerograd.dev/docs#privacy):** find and drop sensitive columns, or pseudonymize them with a local vault, before anything leaves your machine.
* **Save and open:** `cap.save()` writes one file and `zerograd.load()` opens it again.
* **Bring your own model:** plug any model into the championship with `zerograd.register_model`.
* **[The ZeroGrad platform](https://zerograd.dev/docs#platform):** with `remote=True` the same code runs on the platform, with versions, scheduled championships, monitoring and batch pipelines.

## Licenses and attribution

The SDK is Apache 2.0. Each model has its own license, shown by `zerograd.list_models()`, and **you are
responsible for complying with it** ([TERMS.md](TERMS.md)). If you build a product with TabPFN v2, its license
asks you to show **"Built with PriorLabs-TabPFN"**; `cap.attribution` tells you when the champion needs it.

Some newer models are released under non-commercial licenses. They are off by default, can be enabled one by
one by name for research and evaluation, and never run on the ZeroGrad platform. See
[MODELS.md](MODELS.md#non-commercial-off-by-default-research-and-evaluation-only) and [TERMS.md](TERMS.md).

## Development

```bash
pip install -e ".[dev]"
pytest                                        # fast tests, no models, no network
ZEROGRAD_REAL_MODELS=1 pytest tests/test_real_models.py   # the real models (downloads weights)
```

## Security

See [SECURITY.md](SECURITY.md). Releases are published from GitHub Actions with PyPI trusted publishing.

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). The models have their own licenses: [MODELS.md](MODELS.md).
