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

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

```bash
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](https://predictabl.tech/docs/authentication/).

## 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.

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

## 4. Upload, ask, train

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

```text
✓ 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

```python
print(model.report())
```

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

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

```text
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](https://predictabl.tech/docs/build-a-model/): review and change the plan before training.
- [Make predictions](https://predictabl.tech/docs/predictions/): score from your database, by date, or for one customer.
- [AI agents and MCP](https://predictabl.tech/docs/agents/): let Claude or Cursor use your models.
