<!-- https://predictabl.tech/docs/predictions/ -->
# 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

```python
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

```python
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

```python
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:

```python
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

```python
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:

```python
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.
