Causilo quickstart: classification and regression in one call each

Causilo is a tabular foundation model served as an API. You send a table with the answers filled in and a table with them blank, and get a prediction for every blank row. There is no training step, and nothing is kept after the answer goes out unless you ask for a context to be stored.

You need an API key. Sign up at https://api.nums.world/signup with a Google account, and the key is issued on the spot. Put the key in CAUSILO_KEY and the endpoint URL in CAUSILO_ENDPOINT, then:

pip install -U causilo-client scikit-learn
python quickstart.py

import os

import numpy as np
from sklearn.datasets import fetch_openml, load_diabetes
from sklearn.metrics import accuracy_score, mean_absolute_error, r2_score, roc_auc_score
from sklearn.model_selection import train_test_split

from causilo_client import Causilo

cx = Causilo(os.environ["CAUSILO_ENDPOINT"], token=os.environ["CAUSILO_KEY"])
print("ready:", cx.health())

Classification

The German credit dataset from OpenML: 1,000 applicants, 20 columns of mixed numeric and categorical features, and a good/bad label. Pass the DataFrame as it comes. Categorical columns, missing values and column order are handled on the server; no encoding or scaling on your side.

X, y = fetch_openml(data_id=31, as_frame=True, return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, stratify=y, random_state=42)

context = X_train.assign(credit=y_train.values)   # answers filled in
query = X_test                                     # answers blank
print("context", context.shape, "query", query.shape)

proba, meta = cx.predict_with_metadata(context, query, target="credit", model="causilo-clf", output_type="probas")
proba = np.array(proba)
good = proba[:, meta["classes"].index("good")]
print("ROC AUC:", round(roc_auc_score(y_test == "good", good), 4))
print("accuracy:", round(accuracy_score(y_test, np.where(good >= 0.5, "good", "bad")), 4))

predict_with_metadata also returns what the server did with the call. classes gives the column order of the probability matrix, served_by names the image and the weights that answered, and quota says how much of your allowance is left.

print("classes:", meta["classes"])
print("served_by:", meta["served_by"])
print("quota:", meta["quota"])

Regression

The diabetes dataset from scikit-learn: 442 patients, 10 features, a disease-progression score. Ask for the mean, or for quantiles when you want an interval rather than a point.

d = load_diabetes(as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(d.data, d.target, test_size=0.2, random_state=42)

pred = cx.predict(X_train.assign(progression=y_train.values), X_test, target="progression", model="causilo-reg")
print("R2:", round(r2_score(y_test, pred), 4))
print("MAE:", round(mean_absolute_error(y_test, pred), 2))

q = np.array(cx.predict(X_train.assign(progression=y_train.values), X_test,
                        target="progression", model="causilo-reg",
                        output_type="quantiles", quantiles=[0.1, 0.5, 0.9]))
inside = np.mean((y_test.values >= q[:, 0]) & (y_test.values <= q[:, 2]))
print("quantiles array shape (rows, quantiles):", q.shape)
print("share of held-out values inside the 10-90 band:", round(inside, 3))

What you were charged

The unit is one cell of the table you sent, context and query together. Nothing else enters into it: not the number of estimators, not the output type, not the time it took. usage() reads the figures without spending any.

u = cx.usage()
print("usage:", {k: u[k] for k in ("scope", "limit", "used", "remaining", "resets_at")})

Output

stdout

ready: True
context (800, 21) query (200, 20)
ROC AUC: 0.7771
accuracy: 0.735
classes: ['bad', 'good']
served_by: {'image': '0.12.16', 'checkpoint': '2fe50487b33e', 'n_estimators': 8, 'device': 'cuda:0', 'deterministic': False}
quota: {'scope': 'daily', 'limit': 6250000, 'used': 20000, 'remaining': 6230000, 'resets_at': '2026-09-19T00:00:00+00:00'}
R2: 0.5055
MAE: 40.49
quantiles array shape (rows, quantiles): (89, 3)
share of held-out values inside the 10-90 band: 0.831
usage: {'scope': 'daily', 'limit': 6250000, 'used': 28840, 'remaining': 6221160, 'resets_at': '2026-09-19T00:00:00+00:00'}

Causilo vs XGBoost →

Recorded 2026-09-18 · image 0.12.16