Python SDK

from hollerith import Hollerith

clf = Hollerith()
clf.fit(train, target="booking")
predictions = clf.predict(test)

The Python SDK uses a familiar fit-and-predict interface. Fit a labeled table once, then predict new rows, get class probabilities, evaluate accuracy, or forecast a series.

This page covers the Python client. For the same calls over HTTP from another language, see the REST API.

Install

Install the wheel shown in the console under Playground → Code:

pip install https://hollerith.monarcha.ai/sdk/hollerith-<version>-py3-none-any.whl

Hollerith is not published on PyPI. The package requires Python 3.11 or 3.12.

Configure

Set your API key and deployment URL:

export HOLLERITH_API_KEY="hk_live_..."
export HOLLERITH_BASE_URL="https://hollerith.monarcha.ai"

Hollerith() reads both values automatically. You can also pass them directly:

clf = Hollerith(
    api_key="hk_live_...",
    base_url="https://hollerith.monarcha.ai",
)

Both values are required. Keep API keys out of source control. See Get your API key for issuing and rotating keys.

Choose a method

Method	Use it to	Returns
`fit`	Prepare a labeled table for prediction	The client or a `FitHandle`
`predict`	Predict labels or numbers	A list, DataFrame, or `PredictionHandle`
`predict_proba`	Get class probabilities	A NumPy array
`evaluate`	Measure accuracy or RMSE	An `EvaluationResult`
`forecast`	Forecast one or more time series	A pandas DataFrame
`from_fitted_context`	Resume a previous fit	A configured client

Fit a table

Pass a labeled frame with target=, or features and labels separately. Passing both, or neither, raises ValueError.

clf.fit(df, target="booking")          # labeled frame
clf.fit(X, y)                          # features and labels

Argument	Default	What it does
`target`	`None`	Names the label column in `data`. Mutually exclusive with `y`.
`task`	`None`	Overrides the inferred task with `"classification"` or `"regression"`.
`evaluate`	`False`	Also runs an evaluation and sets `evaluation_`. Billed as a separate job.
`wait`	`True`	Blocks until the fit is ready. `False` returns a handle.
`force_refit`	`False`	Skips reuse of an identical earlier fit.

Full signature

fit(
    data,
    y=None,
    *,
    target: str | None = None,
    task: Task | None = None,
    evaluate: bool = False,
    wait: bool = True,
    idempotency_key: str | None = None,
    force_refit: bool = False,
    poll_interval: float | None = None,
    timeout: float | None = 900.0,
    on_warming: WarmingHook | None = None,
) -> "Hollerith | FitHandle"

The task is inferred from the target: non-numeric and boolean targets are classification, and so is an integral target with 20 or fewer distinct values.

Check clf.task_ after fitting a numeric target with few distinct values. If it came back "classification" and you wanted regression, pass task="regression".

See Limits and quotas for table and class limits.

Predict rows

preds = clf.predict(test)
preds[0]                               # 'kept'

predict returns a Python list with one value per input row. A DataFrame must contain every column in feature_names_in_; extra columns are dropped and the rest are reordered. An array-like must already use the fitted column order.

Class probabilities

proba = clf.predict_proba(test)        # ndarray, shape (n_rows, n_classes)
proba[:, clf.classes_.index("cancelled")]   # one label's column

Classification only. Columns follow classes_.

predict_proba rewrites classes_ with the engine’s ordering so the array and the labels stay aligned. Read classes_ after the call, not before.

Prediction intervals

frame = clf.predict(test, quantiles=[0.1, 0.5, 0.9])
list(frame.columns)                    # ['prediction', '0.1', '0.5', '0.9']
frame["0.1"]                           # the 10th-percentile column

Regression only. With quantiles= you get a pandas.DataFrame instead of a list: a prediction column holding the mean, plus one column per level.

Quantile column labels are strings. frame[0.1] raises KeyError — index with frame["0.1"].

Evaluate a fit

print(clf.evaluate())

evaluate takes no data. It re-sends the labeled training table and the service splits and scores it, k-fold at 10,000 rows or fewer and holdout above that. The result is also stored on evaluation_.

Field	What it holds
`metric`	`"accuracy"` for classification, `"RMSE"` for regression.
`value`	The score.
`method`	`"kfold"` or `"holdout"`.
`rows`	Rows the evaluation covered.
`folds`	Fold count for k-fold, `None` for holdout.
`engine_version`	Engine version used for the evaluation.

fit(..., evaluate=True) does the same thing in one call. Either way it is a separately billed job. A client resumed with from_fitted_context has no training table in memory, so it cannot evaluate. See Evaluating accuracy for how to read the number.

Forecast a time series

frame = clf.forecast(history, prediction_length=14)

Forecasting uses the history directly and does not require fit().

Argument	Default	What it does
`context`	—	The history frame.
`prediction_length`	`None`	Steps to forecast past the end of `context`.
`future`	`None`	Horizon timestamps plus known covariates, as an alternative to `prediction_length`.
`quantiles`	`(0.1, 0.5, 0.9)`	Probability levels, each strictly between 0 and 1.
`timestamp`	`"timestamp"`	The time column’s name.
`target`	`"target"`	The column to forecast.
`item_id`	`None`	The series column, for many series in one call.

Pass exactly one of prediction_length or future. Every other column is treated as a covariate. You get back a DataFrame with a mean column plus one string-named column per quantile, indexed by timestamp — or by (item_id, timestamp) when you forecast many series at once. Output rows are capped at 200,000, counted as prediction_length × series count.

Reuse a fitted context

A fit produces a server-side context you can predict against later, from another process or another machine.

saved_id = clf.fitted_context_id_               # persist this

later = Hollerith.from_fitted_context(saved_id)
later.predict(batch)

Contexts expire after 30 inactive days, and 90 days after creation at the latest. Successful predictions push the inactivity deadline out. Once a context expires, fit again — resuming an expired one raises NotFoundError. A resumed client carries the schema, not the training data. evaluate() raises RuntimeError, and classes_ only appears once predict_proba has run.

Run without blocking

Pass wait=False to get a handle instead of a result, and poll it when you are ready.

handle = clf.predict(test, wait=False)
handle.status                          # 'queued' | 'running' | 'succeeded' | 'failed' | 'purged'
handle.refresh()                       # one round-trip for a fresh view
result = handle.wait()                 # blocks, returns a PredictionResult
result.predictions

submit(data) also returns a prediction handle without polling. fit(wait=False) returns a FitHandle with id, context, refresh(), and wait().

fit(wait=False) does not bind the completed context to the original client. To reuse that context, resume it with from_fitted_context(). evaluate=True has no effect when wait=False; call evaluate() separately on the original client if needed.

Progress and cold starts

clf.predict(test, on_progress=lambda job: print(job.status))
clf.predict(test, on_warming=lambda err: print(err.code))    # 'worker_warming_up'

on_progress is called with the latest job view on submit and on every poll. It is accepted by predict, predict_proba, evaluate, forecast and PredictionHandle.wait(), but not by fit. on_warming receives a ServiceUnavailableError while the SDK waits for a cold worker. The callback takes the error as its only argument. If you know the shape of the table you are about to fit, hint for capacity ahead of time:

clf.warm(rows=100_000, columns=30)

warm is a best-effort, non-blocking hint. It reserves nothing and returns the client.

Timeouts, polling and idempotency

Methods that wait for a job accept the same three controls.

Argument	Default	What it does
`timeout`	`900.0`	Wall-clock deadline in seconds. Raises `TimeoutError`. `None` waits indefinitely.
`poll_interval`	`None`	Seconds between status polls. `None` backs off adaptively from 100 ms to 1 s.
`idempotency_key`	`None`	A replay returns the same job. Reusing a key with a different payload raises `ConflictError`.

Reading CSV files

from hollerith import read_csv, read_csv_text

train = read_csv("train.csv")          # a path, a Path, or an open buffer
rows  = read_csv_text("a,b\n1,2\n")    # CSV already in memory

The reader supports comma, tab, semicolon, and pipe delimiters. Structural problems raise ValidationError with code malformed_csv and identify the affected line or column without including dataset contents.

Every column comes back as str. No dtype is inferred, so a numeric target read this way looks like classification. Cast the columns you need, or pass task="regression" to fit.

df = read_csv("houses.csv")
df["price"] = df["price"].astype(float)
clf.fit(df, target="price")

Handling errors

Service errors inherit from HollerithError. Catch a specific subclass when the response needs different handling:

from hollerith import HollerithError, ValidationError

try:
    clf.predict(test)
except ValidationError as err:
    print(err.code, err.fix)
except HollerithError as err:
    print(err.code, err.request_id)

Every HollerithError includes problem, code, cause, fix, doc_url, retryable, and request_id. Branch on code, which is stable across changes to the explanatory text. Calling errors raise standard Python exceptions such as ValueError or TypeError. A polling deadline raises TimeoutError. Rate-limited requests are retried twice, honoring Retry-After. Cold workers are retried inside the poll loop. See Errors for the full catalog of codes and which ones are retryable.

Quickstart — run your first prediction
Evaluating accuracy — interpret an evaluation
Forecast a time series — prepare and forecast time-series data
Errors — handle every error code
Limits and quotas — check every model and account limit

Get started

Guides

Reference

Account

Help

Install

Configure

Choose a method

Fit a table

Predict rows

Class probabilities

Prediction intervals

Evaluate a fit

Forecast a time series

Reuse a fitted context

Run without blocking

Progress and cold starts

Timeouts, polling and idempotency

Reading CSV files

Handling errors

Next

​Install

​Configure

​Choose a method

​Fit a table

​Predict rows

​Class probabilities

​Prediction intervals

​Evaluate a fit

​Forecast a time series

​Reuse a fitted context

​Run without blocking

​Progress and cold starts

​Timeouts, polling and idempotency

​Reading CSV files

​Handling errors

​Next

Install

Configure

Choose a method

Fit a table

Predict rows

Class probabilities

Prediction intervals

Evaluate a fit

Forecast a time series

Reuse a fitted context

Run without blocking

Progress and cold starts

Timeouts, polling and idempotency

Reading CSV files

Handling errors

Next