View as Markdown

Python reference

predictabl 0.1.1. Generated from the library itself, so the signatures here always match the package. pip install predictabl; source on GitHub.

Module functions

These use one shared client, configured by login() or the PREDICTABL_API_KEY and PREDICTABL_BASE_URL environment variables.

pb.login()

pb.login(api_key: str | None = None, base_url: str | None = None, **kw)

Configure the shared client. Without arguments, reads PREDICTABL_API_KEY (and PREDICTABL_BASE_URL) from the environment. Other keyword arguments are passed to Client.

pb.account()

pb.account()

Who you are, your plan, your credits and what is left of your allowances.

pb.connect()

pb.connect(
    source: str | Path | Iterable[str | Path] | Any,
    name: str | None = None,
    *,
    wait: bool = True,
    quiet: bool = False,
    on_progress: Callback | None = None,
    timeout: float | None = 1800,
)

Connect data to Predictabl: a database or files.

  • A Postgres address ("postgresql://user:password@host:5432/db"): Predictabl reads the database where it is, read-only. Use a read-only user, and make sure the database accepts connections from Predictabl's server.
  • CSV, Excel or Parquet files, a list of them, or a pandas DataFrame: the files are uploaded to Predictabl. Several files become several tables Predictabl can join.

With wait (default) returns once Predictabl has read the tables.

pb.datasets()

pb.datasets()

Every dataset on this account: uploads and connected databases.

pb.data()

pb.data(data_id: str)

One dataset by id (from datasets() or the web app).

pb.plan()

pb.plan(question_id: str)

The latest plan of a question (opportunity) planned earlier, e.g. in the web app, to retrain it from code without planning again.

pb.model()

pb.model(model_id: str)

One model by id (from models() or the web app address).

pb.models()

pb.models(limit: int = 50)

Your models, newest first, trained or not (check model.ready).

Client

A connection to Predictabl.

api_key defaults to the PREDICTABL_API_KEY environment variable and base_url to PREDICTABL_BASE_URL, else the hosted app. For a local instance use base_url="http://localhost:8000/api/v1".

pb.Client(
    api_key: str | None = None,
    base_url: str | None = None,
    *,
    timeout: float = 120.0,
    poll_interval: float = 2.0,
)

client.account()

client.account()

Who you are, your plan, your credits and what is left of your allowances.

client.connect()

client.connect(
    source: str | Path | Iterable[str | Path] | Any,
    name: str | None = None,
    *,
    wait: bool = True,
    quiet: bool = False,
    on_progress: Callback | None = None,
    timeout: float | None = 1800,
)

Connect data to Predictabl: a database or files.

  • A Postgres address ("postgresql://user:password@host:5432/db"): Predictabl reads the database where it is, read-only. Use a read-only user, and make sure the database accepts connections from Predictabl's server.
  • CSV, Excel or Parquet files, a list of them, or a pandas DataFrame: the files are uploaded to Predictabl. Several files become several tables Predictabl can join.

With wait (default) returns once Predictabl has read the tables.

client.datasets()

client.datasets()

Every dataset on this account: uploads and connected databases.

client.data()

client.data(data_id: str)

One dataset by id (from datasets() or the web app).

client.plan()

client.plan(question_id: str)

The latest plan of a question (opportunity) planned earlier, e.g. in the web app, to retrain it from code without planning again.

client.model()

client.model(model_id: str)

One model by id (from models() or the web app address).

client.models()

client.models(limit: int = 50)

Your models, newest first, trained or not (check model.ready).

client.close()

client.close()

Close the HTTP connection. with pb.Client() as c: does it for you.

Data

A dataset on Predictabl: uploaded files or a connected database.

Attribute
id Dataset id
name Its name
status ready once read
table_count How many tables
error Why reading failed, if it did

data.plan()

data.plan(
    question: str,
    *,
    quiet: bool = False,
    on_progress: Callback | None = None,
    timeout: float | None = 1800,
)

Turn a question into a reviewable plan: target, features and what was excluded as leakage. Spends one build on Predictabl's AI key.

data.predict()

data.predict(
    question: str,
    *,
    preset: str = "full_quality",
    engine: str = "auto",
    quiet: bool = False,
    on_progress: Callback | None = None,
    timeout: float | None = None,
)

The whole path: question -> plan -> trained, tested model.

data.questions()

data.questions()

Questions (prediction opportunities) found or asked on this data.

data.wait_ready()

data.wait_ready(*, timeout: float | None = 1800)

Wait until Predictabl has read the tables (status "ready").

data.refresh()

data.refresh()

Reload status and table count from the server.

data.delete()

data.delete()

Delete this dataset and its uploaded files. Models trained on it can no longer read it, so delete only data you no longer score from.

Plan

What Predictabl will train: the target, the features, and what it excluded as leakage. Review it, refine it in plain words, then train.

Attribute
id Plan id (what train uses)
version Plan version
opportunity_id The question it belongs to
target The outcome, in words
task binary_classification, multiclass or regression
features Features it will use
excluded Columns left out, with reasons
spec The full plan, including its SQL

plan.summary()

plan.summary()

The plan in a few readable lines; also what print(plan) shows.

plan.refine()

plan.refine(
    message: str,
    *,
    quiet: bool = False,
    on_progress: Callback | None = None,
    timeout: float | None = 1800,
)

Change the plan in plain words ("don't use the courier column"). Returns the new version; this object stays the version it was.

plan.train()

plan.train(
    *,
    preset: str = "full_quality",
    engine: str = "auto",
    wait: bool = True,
    quiet: bool = False,
    on_progress: Callback | None = None,
    timeout: float | None = None,
)

Train and test this plan. preset="fast_preview" is a ~15-second sanity check on a sample; the default is the real model.

Model

A trained (or training) model. predict() scores with it.

Attribute
id Model id
state SUCCEEDED when ready; FAILED, CANCELLED, or a step name while training
ready True once trained
title What it predicts
kind flat, event or forecast
meaning What its prediction number is
created_via The token that created it, if made from code
url The model in the web app
error_code Why it failed, if it did
suggestions Server-suggested fixes

model.predict()

model.predict(
    rows: Any = None,
    *,
    ids: Iterable[str] | str | None = None,
    since: str | date | datetime | None = None,
    until: str | date | datetime | None = None,
    since_days: int | None = None,
    as_of: str | date | datetime | None = None,
    limit: int | None = None,
    filters: list[dict] | None = None,
    include: list[str] | None = None,
    calibrated: bool = False,
)

Score with this model.

  • rows (DataFrame, list of dicts or one dict): score these records. Predictabl builds the features from them with the model's own SQL.
  • otherwise Predictabl scores from the data it was trained on: forecasts from the latest data (or as_of), event models for rows dated today (or since/until/since_days), optionally only ids, highest first, at most limit (server cap 2000).

model.report()

model.report()

The tested result: metric, rows, top features, what it predicts.

model.wait()

model.wait(
    *,
    quiet: bool = False,
    on_progress: Callback | None = None,
    timeout: float | None = None,
)

Block until training ends. Raises BuildFailed if it failed.

model.events()

model.events()

Everything the run reported, step by step.

model.refresh()

model.refresh()

Reload state, kind and errors from the server.

model.cancel()

model.cancel()

Stop training. The model ends CANCELLED.

Predictions

A list of predictions (dicts with entity_id, prediction, ...), plus what they mean: meaning, kind, as_of, and any note or warning the server attached.

Attribute
meaning What prediction is, in words
kind flat, event or forecast
as_of Forecasts: the date they are made from
note Why nothing matched, when nothing did
warning A caveat about how the scores were made
where_used Which rows were scored, as the server applied it
count How many matched (can exceed len() when limited)
raw The server's full response, without the predictions

predictions.to_pandas()

predictions.to_pandas()

The predictions as a DataFrame (needs pandas). Context columns requested with include become their own columns.

Progress updates

on_progress callbacks receive pb.Update objects:

Field
step e.g. Uploading, Planning, Training, Final model
status running, done or failed
detail Short text, e.g. 30 features · 2 excluded

Errors

Every error carries the server's machine code (when it sent one) and a message meant for a person: the API phrases refusals as "what happened and what to do", and these classes pass that through untouched.

Exception
pb.PredictablError Base class for everything this package raises.
pb.AuthenticationError The API key is missing, wrong or revoked (HTTP 401).
pb.PermissionDenied The API key is valid but its scope does not allow this (HTTP 403). Predictions only keys cannot connect data, plan or train.
pb.NotFound No such object for this account (HTTP 404). Someone else's objects look exactly like missing ones, by design.
pb.LimitReached A free-plan allowance on Predictabl's AI key is used up (HTTP 402). The message says how to continue (your own AI key, or an upgrade).
pb.InvalidRequest The request was understood but refused (HTTP 4xx), e.g. a model that needs rows was asked to score without them.
pb.BuildFailed A step of building a model (reading the data, finding the question, planning, training) ended in failure. suggestions lists the server's recovery options when it gave any.
pb.ApiError Anything else the server answered with an error.