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
ChurnisYes. - Planning: it chose 30 features and excluded 2 columns:
Churnitself (it is the answer) andcustomerID(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
- Build a model: review and change the plan before training.
- Make predictions: score from your database, by date, or for one customer.
- AI agents and MCP: let Claude or Cursor use your models.