How ayushsyntax/telecomchurnprediction works
Project type and purpose
• This is a machine-learning-driven full-stack application for telecom customer churn prediction.
• It includes an offline training/EDA pipeline (Jupyter notebook), model persistence, a REST API backend (FastAPI via app.py), and an interactive frontend (Streamlit).
File structure
• Top-level:
• Telco_Customer_Churn.ipynb – exploratory data analysis, feature engineering, model training
• models/ – serialized artifacts (champion_model.pkl, kmeans.pkl, preprocessor.pkl, scaler.pkl)
• app.py – FastAPI application exposing prediction endpoints
• streamlit_app.py – Streamlit UI for users to input customer data, view churn probability & segment
• requirements.txt – dependency list
• No external DB: models are loaded from file system
• Configuration: .gitignore, LICENSE, README.md
Extract README insights
• Offline workflow: EDA → feature engineering → model selection (CatBoost) → clustering (K-Means) → SHAP interpretability → model persistence
• Deployment: joblib-pickled objects consumed by app.py & streamlit_app.py
• Tech stack: Python, scikit-learn, CatBoost, FastAPI, Uvicorn, Streamlit, SHAP
Main components
a. Offline Training Pipeline
• Jupyter Notebook (Telco_Customer_Churn.ipynb)
• Preprocessing module → Feature engineering → Model training (CatBoost) → Model evaluation → SHAP analysis → Model & artifacts persisted to file system (models/)
b. Model Artifact Store
• File system directory “models/” holding .pkl files
c. Backend API
• app.py (FastAPI + Uvicorn)
• Loads preprocessor.pkl, scaler.pkl, champion_model.pkl, kmeans.pkl
• Exposes endpoints: /predict (churn probability), /segment (K-Means cluster)
d. Frontend UI
• streamlit_app.py (Streamlit server)
• User inputs customer features
• Calls internal prediction functions or HTTP API to fetch churn score & segment
• Displays results and SHAP plots (optional)
e. End User
• Browser interacting with Streamlit
f. (Optional) CI/CD or retraining scheduler – not present but can be shown as future extension
Relationships & data flow
• Offline: Notebook → generate .pkl artifacts → models/
• At runtime:
• Streamlit UI loads artifacts OR calls FastAPI
• FastAPI loads artifacts into memory at startup
• User submits data → API receives POST → preprocessing → model.predict → returns JSON → UI displays
[User] → (1) Streamlit → (2) FastAPI → (3) Model objects → (4) Response → [Streamlit] → [User]
Architectural patterns & design principles
• Separation of concerns: training vs. inference
• Single-responsibility services: API for inference; Notebook for training; UI for presentation
• Artifact versioning & immutability: pickled models in dedicated directory
• Stateless API: no database, uses files in read-only mode at startup
Technologies & libraries
• Python 3.x, FastAPI, Uvicorn (backend)
• Streamlit (frontend)
• scikit-learn, CatBoost, joblib (modeling)
• Pandas, NumPy, SHAP (data processing & interpretability)
Detail without overcomplicating
• Do not collapse the inference pipeline—show preprocessing, prediction, clustering as distinct steps