Metadata-Version: 2.4
Name: causilo-client
Version: 0.8.15
Summary: Python client for the Causilo inference API
Author: Nums AI
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://nums.world
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=15
Requires-Dist: requests>=2.32
Requires-Dist: google-auth>=2.28

# causilo-client

Python client for the Causilo inference API. Send a table with the answers
filled in and a table with them blank; get a prediction for every blank row.

## Install

```bash
pip install -U causilo-client
```

Python 3.11 or newer. `pandas`, `pyarrow`, `requests` and `google-auth` are
pulled in automatically.

The import name is `causilo_client`. `causilo` on PyPI is the model package,
and the two can be installed side by side. Code written against the earlier
`radix` name changes the import and the class name: `from causilo_client import
Causilo`, and `Radix(...)` becomes `Causilo(...)`. Nothing else moved.

## Use

```python
import os

from causilo_client import Causilo

cx = Causilo(
    os.environ["CAUSILO_ENDPOINT"],
    key_file=os.environ["CAUSILO_KEY_FILE"],
)

pred = cx.predict(context_df, query_df, target="churned", model="causilo-clf")
```

`context_df` holds the target column; `query_df` does not. The feature columns
must match in name and order across the two. The endpoint URL and the
credential are issued to you at handover; neither is published here.

Authentication takes either a service account key file (`key_file=`) or a
bearer token issued by the operator (`token=`). Which one applies is agreed
before handover.

## What else is there

| | |
|---|---|
| `predict_with_metadata(...)` | The prediction and the metadata the server attached: the settings it applied, `classes` for the column order of a probability matrix, `served_by` naming the image and the weights that answered, `quota` with what is left of the month |
| `usage()` | The month's figures for this credential without spending any of it; `metered: false` when no cap applies |
| `health()`, `wake()` | Whether the service is ready; `wake()` waits for a cold instance to come up before a first call |
| `to_batch_parquet(...)` | Packs a context and a query table into the single Parquet file a batch job takes |
| `MODELS` | The model keys this version knows |

Every failure is a `RadixError` with `.status`, `.error_code` and `.request_id`,
the identifier to quote when reporting a problem. The subclasses say what to do:
`RadixValidationError` (fix the request), `RadixTooLarge` (the message names what
fits), `RadixQuotaExceeded` (a cell quota is spent; `.scope` is `caller`,
`daily` or `tenant`, with `.limit`, `.used`, `.resets_at`), `RadixRateLimited`
(too many requests in one minute or hour; the client already waited out
`Retry-After` three times before raising it, and `.scope`, `.limit`, `.used`,
`.resets_at` say which window), `RadixOverloaded` (retry once the queue drains;
`RadixRateLimited` is a subclass of it), `RadixUnavailable` (already retried
three times), `RadixAuthError` (the credential was refused) and
`RadixTimeout`. Timeouts are the one failure the client will not retry: the
server is still computing, so instead it tells the server the call was
abandoned, and `.refunded` says how many cells came back. The default `timeout`
is 900 seconds.

The integration guide covers the call arguments, the input rules, the response
metadata, what each error means, and what the client does on your behalf when a
call times out.
