View as Markdown

Quickstart

In about five minutes you will connect a public customer dataset, ask which customers will churn, get a tested model, and score customers with it.

You need: Python 3.10 or newer, and a Predictabl account.

1. Install

pip install predictabl

2. Get an API key

In the web app, open Settings → API & MCP and select Create token (leave Predictions only unticked). Copy the token: it starts with pk_ and is shown only once.

export PREDICTABL_API_KEY=pk_...

The library reads the key from this variable. Keep it out of your code and out of git. More on keys.

3. Get the example data

The IBM Telco sample: 7,043 customers of a phone and internet company, one row each, with a Churn column saying whether they left.

curl -sLo telco.csv https://raw.githubusercontent.com/IBM/telco-customer-churn-on-icp4d/master/data/Telco-Customer-Churn.csv

4. Upload, ask, train

import predictabl as pb

data = pb.connect("telco.csv", name="Telco customers")
model = data.predict("Which customers will churn?")

Predictabl reports each step as it goes:

✓ Uploading      telco.csv · 947.7 KB
✓ Reading data   1 table
✓ Understanding  Predict which telco customers will churn
✓ Planning       30 features · 2 excluded
✓ Preparing
✓ Building data
✓ Training
✓ Testing
✓ Final model    auc 0.8458

What happened:

  • Reading data: Predictabl read the table and worked out what each column is.
  • Understanding: it turned your question into a precise target: a customer whose Churn is Yes.
  • Planning: it chose 30 features and excluded 2 columns: Churn itself (it is the answer) and customerID (an identifier, not a signal).
  • Testing: the model was scored on customers it never saw while training. AUC 0.85 means it ranks a random churner above a random non-churner 85% of the time.

Your numbers can differ slightly between runs.

5. Look at the result

print(model.report())
{'predicts': 'Predict which telco customers will churn',
 'meaning': 'probability that customer churned / left the telco provider',
 'kind': 'flat',
 'metric': 'auc', 'score': 0.8458,
 'rows_trained': 5634, 'rows_tested': 1409,
 'top_features': [...],
 'url': 'https://app.predictabl.tech/runs/...'}

Open model.url to see the same model in the web app: its plan, test results and feature importance.

6. Score customers

import csv

customers = list(csv.DictReader(open("telco.csv")))[:3]
preds = model.predict(rows=customers)

print(preds.meaning)
for p in preds:
    print(p["entity_id"], round(p["prediction"], 2), p.get("actual"))
probability that customer churned / left the telco provider
7590-VHVEG 0.71 0
5575-GNVDE 0.04 0
3668-QPYBK 0.39 1

These rows still contain their Churn column. It never reaches the model; it comes back as actual, so you can check the scores against what really happened. For new customers, just leave the column out.

A pandas DataFrame works too: model.predict(rows=df).to_pandas().

Next