telco-churn-nba-engine

Holdout briefing · IBM public sample

GitHub (opens in a new tab)

POST /score

Score

Pick one of the three request bodies committed in the repository. The live demo scores all three. examples/score_response.json is the committed response for the first. The save-call and offer files do not have committed response JSON, so their panels show the documented action and the rule text, and they leave probability, CLV, and reasons blank.

Committed holdout examples

No action

Fiber optic · One year · tenure 52 · MonthlyCharges 80.200000

Customer id 5343-SGUBI, historical Churn No. The id and the label are not sent to the model. The request is the first held-out test customer with a numeric TotalCharges.

Local command from the README. This page does not send it.

curl -s -X POST http://localhost:8000/score \
  -H 'Content-Type: application/json' \
  -d @examples/score_request.json

Request

Account

genderFemale
SeniorCitizen0
PartnerNo
DependentsNo
tenure52
ContractOne year
PaperlessBillingYes
PaymentMethodMailed check

Services

PhoneServiceYes
MultipleLinesYes
InternetServiceFiber optic
OnlineSecurityNo
OnlineBackupYes
DeviceProtectionNo
TechSupportNo
StreamingTVNo
StreamingMoviesNo

Charges

MonthlyCharges80.200000
TotalCharges4297.600000
Committed request JSON
{
  "gender": "Female",
  "SeniorCitizen": 0,
  "Partner": "No",
  "Dependents": "No",
  "tenure": 52,
  "PhoneService": "Yes",
  "MultipleLines": "Yes",
  "InternetService": "Fiber optic",
  "OnlineSecurity": "No",
  "OnlineBackup": "Yes",
  "DeviceProtection": "No",
  "TechSupport": "No",
  "StreamingTV": "No",
  "StreamingMovies": "No",
  "Contract": "One year",
  "PaperlessBilling": "Yes",
  "PaymentMethod": "Mailed check",
  "MonthlyCharges": 80.200000,
  "TotalCharges": 4297.600000
}

examples/score_request.json

Committed response

No action

Churn probability

0.122990

Scoring model gradient_boosting. Rule no_action. Offer null.

Churn risk, CLV, and offer eligibility do not match a save call or an offer.

README, on this response: churn probability 0.122990 is below churn_medium 0.165703, so the rule is no_action, even though the OnlineSecurity lookalike probability is 0.618604, above the offer cutoff 0.400000.

Top reasons

Path contributions along the gradient-boosting trees. They sum with the model intercept to the churn log-odds for this customer. They are not SHAP values.

Contract-0.357808 Decreases churn risk
StreamingMovies-0.235742 Decreases churn risk
MonthlyCharges-0.169382 Decreases churn risk

Add-on propensities

Lookalike probability of current holding. Eligible means the customer has internet service and does not already hold that add-on.

OnlineSecurity0.618604 · eligible
TechSupport0.478232 · eligible

CLV proxy

Value 1511.445671

Monthly charges 80.200000 × expected remaining months 18.845956. Horizon 72.000000 months. The README states that the value is the six-decimal product of those two displayed figures.

Frozen cutoffs

From reports/metrics.json. Cutoffs are not chosen on the test set.
churn_high0.442962
churn_medium0.165703
clv_high3311.917019
min_offer_propensity0.400000
Path contributions for the example score. The churn probability sits below the medium cutoff, so the action is no_action.
Committed chart for customer 5343-SGUBI. Contract, StreamingMovies, and MonthlyCharges lower this customer's churn log-odds. The contributions are not SHAP values.
Committed response JSON
{
  "churn_probability": 0.122990,
  "scoring_model": "gradient_boosting",
  "top_reasons": [
    {
      "feature": "Contract",
      "contribution": -0.357808,
      "direction": "decreases_churn_risk"
    },
    {
      "feature": "StreamingMovies",
      "contribution": -0.235742,
      "direction": "decreases_churn_risk"
    },
    {
      "feature": "MonthlyCharges",
      "contribution": -0.169382,
      "direction": "decreases_churn_risk"
    }
  ],
  "next_best_action": {
    "action": "no_action",
    "offer": null,
    "rule_id": "no_action",
    "rationale": "Churn risk, CLV, and offer eligibility do not match a save call or an offer."
  },
  "addon_propensities": {
    "OnlineSecurity": {
      "eligible": true,
      "probability": 0.618604,
      "reason": null
    },
    "TechSupport": {
      "eligible": true,
      "probability": 0.478232,
      "reason": null
    }
  },
  "clv_proxy": {
    "monthly_charges": 80.200000,
    "expected_remaining_months": 18.845956,
    "value": 1511.445671,
    "horizon_months": 72.000000
  },
  "explanation_method": "Path contributions along the gradient-boosting trees. They sum with the model intercept to the churn log-odds for this customer. They are not SHAP values."
}

examples/score_response.json

Save call

Fiber optic · Month-to-month · tenure 3 · MonthlyCharges 90.4

This request file does not include a customer id. The id is not part of POST /score.

Local command from the README. This page does not send it.

curl -s -X POST http://localhost:8000/score \
  -H 'Content-Type: application/json' \
  -d @examples/holdout_save_call.json

Request

Account

genderMale
SeniorCitizen0
PartnerNo
DependentsNo
tenure3
ContractMonth-to-month
PaperlessBillingNo
PaymentMethodElectronic check

Services

PhoneServiceYes
MultipleLinesNo
InternetServiceFiber optic
OnlineSecurityNo
OnlineBackupYes
DeviceProtectionYes
TechSupportNo
StreamingTVNo
StreamingMoviesYes

Charges

MonthlyCharges90.4
TotalCharges268.45
Committed request JSON
{
  "gender": "Male",
  "SeniorCitizen": 0,
  "Partner": "No",
  "Dependents": "No",
  "tenure": 3,
  "PhoneService": "Yes",
  "MultipleLines": "No",
  "InternetService": "Fiber optic",
  "OnlineSecurity": "No",
  "OnlineBackup": "Yes",
  "DeviceProtection": "Yes",
  "TechSupport": "No",
  "StreamingTV": "No",
  "StreamingMovies": "Yes",
  "Contract": "Month-to-month",
  "PaperlessBilling": "No",
  "PaymentMethod": "Electronic check",
  "MonthlyCharges": 90.4,
  "TotalCharges": 268.45
}

examples/holdout_save_call.json

Documented result

Save call

Action named for this scene: save_call

The README demo posts this file second and describes the clip as returning a save call. A response JSON is not committed for it, so this panel does not show a churn probability, CLV proxy, path contributions, or offer.

Rule text

Copied from config/nba_rules.yaml. This is the policy text, not a measured score for this request.

  • Priority 1 · save_call

    When churn_probability >= churn_high AND clv >= clv_high

    High churn risk and high CLV proxy: place a retention call.

    Action save_call, offer null

Add-on offer

Fiber optic · One year · tenure 39 · MonthlyCharges 100.0

This request file does not include a customer id. The id is not part of POST /score.

Local command from the README. This page does not send it.

curl -s -X POST http://localhost:8000/score \
  -H 'Content-Type: application/json' \
  -d @examples/holdout_offer.json

Request

Account

genderMale
SeniorCitizen0
PartnerYes
DependentsYes
tenure39
ContractOne year
PaperlessBillingNo
PaymentMethodElectronic check

Services

PhoneServiceYes
MultipleLinesYes
InternetServiceFiber optic
OnlineSecurityNo
OnlineBackupNo
DeviceProtectionYes
TechSupportNo
StreamingTVYes
StreamingMoviesYes

Charges

MonthlyCharges100.0
TotalCharges3835.55
Committed request JSON
{
  "gender": "Male",
  "SeniorCitizen": 0,
  "Partner": "Yes",
  "Dependents": "Yes",
  "tenure": 39,
  "PhoneService": "Yes",
  "MultipleLines": "Yes",
  "InternetService": "Fiber optic",
  "OnlineSecurity": "No",
  "OnlineBackup": "No",
  "DeviceProtection": "Yes",
  "TechSupport": "No",
  "StreamingTV": "Yes",
  "StreamingMovies": "Yes",
  "Contract": "One year",
  "PaperlessBilling": "No",
  "PaymentMethod": "Electronic check",
  "MonthlyCharges": 100.0,
  "TotalCharges": 3835.55
}

examples/holdout_offer.json

Documented result

Add-on offer

Action named for this scene: offer

The README demo posts this file third and describes the clip as returning an add-on offer. A response JSON is not committed for it. The files do not say whether the match was offer_high_risk or offer_medium_risk, or whether the offer was OnlineSecurity or TechSupport.

Rule text

Copied from config/nba_rules.yaml. This is the policy text, not a measured score for this request.

  • Priority 2 · offer_high_risk

    When churn_probability >= churn_high AND at least one add-on is eligible

    High churn risk with CLV below the save-call bar: offer the eligible add-on with the higher uptake propensity.

    Action offer, offer best_eligible

  • Priority 3 · offer_medium_risk

    When churn_probability >= churn_medium AND an eligible add-on has propensity >= min_offer_propensity

    Moderate churn risk and an eligible add-on whose lookalike propensity meets the policy cutoff.

    Action offer, offer best_eligible_above_cutoff