View as Markdown

Make predictions

There are two ways to score with a trained model:

  1. Send records: model.predict(rows=...). You pass the data.
  2. Score from your data: model.predict(). Predictabl reads the data the model was trained on and builds the features itself.

Which one fits depends on the model's kind.

Model kinds

model = pb.model("<model id>")
print(model.kind, "·", model.meaning)
kind One prediction is for… Score with
flat One record (a survey answer, a sensor reading, a form) rows=: send the records
event One row of your data at a point in time (an order, a booking, a customer) model.predict() with a date window, or rows=
forecast One entity on each future day or week (sales per store, demand per item) model.predict(), optionally as_of=

model.meaning says what the number is, for example "probability that customer churned" or "predicted sales: daily sales for a store". Show it next to the numbers; a score without it is easy to misread.

Send records

preds = model.predict(rows=[
    {"tenure": 2, "Contract": "Month-to-month", "MonthlyCharges": 89.1, ...},
])

rows can be one dict, a list of dicts, or a pandas DataFrame. Use the same column names as the data the model was trained on. Predictabl applies the model's own feature SQL to them, so the features are built exactly as in training. Any number of rows works; the library sends them in batches of 1,000.

Send every column you know. A column you leave out counts as unknown: the request still works, but the score rests on less information and is less reliable. If a record has no id column, its entity_id is its position in your list ("0", "1", …).

A record that still contains its outcome column (a row copied from the training file, say) scores the same as without it: the outcome never reaches the model. It comes back as actual, which makes a quick check easy.

If a model summarises history (counts or averages over many rows per customer), the records you send are the only history it sees. preds.warning says so; score from your data instead.

Score from your data

Forecast models

preds = model.predict()                    # from the latest data
preds = model.predict(as_of="2026-10-01")  # as if today were 1 October
print(preds.as_of)

preds.as_of is the date the forecast is made from; each prediction's entity_id reads entity·as_of·step, where step 1 is the first period after it. Check as_of: if your data stopped updating, it will be in the past.

Event models

By default, model.predict() scores rows dated today. Choose a window:

preds = model.predict(since_days=7)                          # the last 7 days
preds = model.predict(since="2026-10-01", until="2026-10-31")  # October

If nothing matched, preds.note says why and gives the newest date in the data.

Narrow it down

model.predict(ids=["store_12", "store_40"])       # specific entities
model.predict(limit=100)                          # the 100 highest scores
model.predict(filters=[{"column": "city", "op": "eq", "value": "Milano"}])
model.predict(include=["city", "branch_name"])    # extra columns per prediction

Filters accept eq, ne, in, contains, gt, gte, lt, lte, on the model's table or a table it joins. Results are sorted highest first, at most 2,000 per call. Filters and include apply to event models.

Read the predictions

model.predict() returns a list of dicts with extra attributes:

preds[0]        # {'entity_id': 'C-1042', 'prediction': 0.83, ...}
preds.meaning   # what 'prediction' is
preds.kind      # flat | event | forecast
preds.as_of     # forecasts: the date they are made from
preds.note      # why nothing matched, if so
preds.warning   # a caveat about how the scores were made, if any
preds.count     # how many matched (can exceed len(preds) when limited)
preds.to_pandas()

Each prediction has:

Key
entity_id Which customer, order, store… (forecasts add ·as_of·step)
prediction Probability of the outcome (classification) or the value (regression)
predicted_class, probabilities Multiclass models only: the likeliest class and every class's probability
actual The real outcome, when the record you sent contained it
context The columns you asked for with include
label A display name for the entity, when the data has one

For multiclass models, read predicted_class, not prediction: prediction is the probability of the likeliest class and does not say which class that is.

Calibrated probabilities

Classification scores rank well but are not always true probabilities. When scoring from your data, model.predict(calibrated=True) returns probabilities you can read as "how often this happens", for models that have a calibrator.