A machine learning web app that predicts the probability a telecom customer will churn. Built with a FastAPI backend and Streamlit for a simple, user-friendly way to use the model.
- Trained a simple Random Forest model on the Telco Customer Churn dataset
- Created a FastAPI endpoint that returns the probability a user may churn
- Streamlit form UI with a real-time risk gauge (0–100 bar) and color-coded result
- Python
- FastAPI
- Scikit-Learn
- Joblib
- Streamlit
- Numpy
In order to increase how many customers the model predicted were going to churn, the threshold was lowered to 0.3. This works fine because for a telecommunications company it is cheap to keep a customer. They could for example offer $15 off if they stay for another month. If the model incorrectly predicts slightly more people who may not have churned but catches almost all of the customers that would actually churn, it would save the company more money in the long run.
| Metric | Score |
|---|---|
| Accuracy | 0.759 |
| Precision | 0.532 |
| Recall | 0.751 |
| F1 Score | 0.623 |
| ROC AUC | 0.834 |
Confusion Matrix:
Predicted No Predicted Yes
Actual No 790 246
Actual Yes 93 280
- Accuracy (0.759) — The model correctly classified 76% of all customers.
- Precision (0.532) — When the model flags someone as likely to churn, it's right 53% of the time.
- Recall (0.751) — The model catches 75% of customers who actually churn. A lower prediction threshold of 0.3 is used to catch more real churners at the cost of more false alarms.
- F1 Score (0.623) — The balance between precision and recall. Lower here because recall is the harder problem.
- ROC AUC (0.834) — The model ranks a real churner above a non-churner 83% of the time.
ChurnPredictor/
├── app.py # Streamlit frontend
├── requirements.txt
├── model/
│ ├── modelAPI.py # FastAPI prediction endpoint
└── notebook/
├── notebook.ipynb # Model training & evaluation
│ └── churn_model.joblib
└── WA_Fn-UseC_-Telco-Customer-Churn.csv
The framework for this project could be copied to create applications to predict user churn inside real companies. It should not be used to predict churn in real telecom environments because data varies by company. What works in this model may not apply for a different company.
1. Create and activate a virtual environment
cd ChurnPredictor
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate2. Install dependencies
pip install -r requirements.txt3. Open Two Terminals
You need two terminals running simultaneously.
Terminal 1 — FastAPI prediction server (port 8000)
cd ChurnPredictor
venv/bin/uvicorn model.modelAPI:app --reload --port 8000Terminal 2 — Streamlit frontend (port 8501)
cd ChurnPredictor
venv/bin/streamlit run app.pyThen open http://localhost:8501 in your browser.
POST /predict
Accepts a JSON body matching the CustomerData schema (see model/modelAPI.py) and returns:
{
"churn": true,
"churn_probability": 0.7421,
"threshold": 0.3
}Interactive API docs are available at http://localhost:8000/docs.
Telco Customer Churn — IBM sample dataset via Kaggle.