How amitkashyap-21/churn-predictor-ml works
Project type and purpose — short summary
• This is an end‑to‑end ML project for binary classification: telecom Customer Churn Prediction.
• Purpose: build a complete ML pipeline (EDA → preprocess → train → evaluate → explain) and provide an interactive Streamlit UI for live prediction. It’s primarily a research/POC repo that contains both exploratory notebooks and lightweight production artifacts (scripts, a saved model, and a Streamlit app).
Key evidence from README + file tree
• app.py — Streamlit app used to serve predictions (interactive frontend).
• src/*.py — productionable scripts: preprocess.py, predict.py, evaluate.py, train.py (train.py exists as notebook and script).
• data/raw & data/processed — raw CSV input and processed CSV.
• models/churn_model.pkl — trained model artifact used by app and predict.py.
• notebooks/* — EDA, preprocessing, modeling, explainability (SHAP) pipelines used during development.
• outputs — figures and reports from notebooks.
• requirements.txt — dependency list (scikit-learn, pandas, numpy, streamlit, shap, etc.).
How I would represent the system
• data/raw/WA_Fn-UseC_-Telco-Customer-Churn.csv (label: Raw CSV)
• Optional: external source (Kaggle URL) as cloud/external data source
• src/preprocess.py and notebooks/02_preprocessing.ipynb
• Inputs: raw CSV → Outputs: data/processed/churn_clean.csv
• Include preprocessing functions/pipeline (categorical encoding, imputation, scaling) that are reused at inference.
• src/train.py and notebooks/03_modeling.ipynb
• Inputs: processed CSV → outputs: models/churn_model.pkl and evaluation metrics to outputs/
• Models trained: LogisticRegression, RandomForest, GradientBoosting (annotate best model)
• src/evaluate.py and notebooks/04_explainability.ipynb
• Tools: sklearn metrics, SHAP
• Outputs: ROC-AUC, confusion matrix, SHAP plots → outputs/
• models/churn_model.pkl (artifact)
• Versioning/metadata (timestamp, metrics)
• app.py (Streamlit app)
• src/predict.py (inference helper)
• Runtime: Streamlit server (http://localhost:8501)
• Inputs: user-entered customer attributes OR preprocessed records
• Uses: preprocessing pipeline (same transformations) + loaded churn_model.pkl → output: churn probability + SHAP explanation
• notebooks/* — exploratory work, reproducibility, ad‑hoc analysis; create artifacts used by other components (processed data, figures)
• Outputs (file system / reporting)
• outputs/figures and outputs/reports created by notebooks/evaluation
• CLI: "streamlit run app.py", "python src/train.py"
• requirements.txt for environment
• Future: FastAPI or containerization/CI-CD (annotate as “future improvement”)
• Raw data → Preprocessing (label: CSV ingestion, cleaning)
• Preprocessing → Processed data (churn_clean.csv)
• Processed data → Training (label: batch training; frequency: ad-hoc / nightly)
• Training → Model artifact (churn_model.pkl) and Evaluation metrics → Outputs
• Training/Evaluation → Explainability (SHAP) → Outputs/Reports
• Model artifact + Preprocessing pipeline → Serving (Streamlit app)
• User input → Serving → Predict (inference) → Output to user (probability + SHAP)
Architectural patterns / design principles to call out
• Separation of concerns: data layer (data/), processing layer (src/preprocess.py), training layer (src/train.py), evaluation/explainability (src/evaluate.py / SHAP notebooks), serving (app.py + src/predict.py).
• Reuse of preprocessing: preprocessing logic must be reusable/invariant across train and serve — emphasize packaging preprocessing code so the same transformations used during train are applied at inference.
• Artifact-driven workflow: explicit model artifact (pickle) saved to models/ and consumed by app.py.
• Offline batch training + online inference: training is batch (not real-time); inference is synchronous (Streamlit UI) or could be converted to REST API later.
• Reproducibility: notebooks produce processed data and outputs; requirements.txt pins environment.
• Python (runtime)
• Data: pandas, numpy (CSV read/write)
• ML: scikit-learn (models), joblib/pickle for serialization
• Explainability: SHAP
• Serving: Streamlit (app.py)
• Optional infra / future: FastAPI (for production API), Docker/Kubernetes, cloud storage (S3), model registry (MLflow)
Extra suggestions to improve fidelity
• A “Preprocessing contract” note — show that the same preprocessing functions must be shared between train and serve; indicate location in repo (src/preprocess.py).
• Where model metrics and artifacts are recorded (outputs/ and models/); annotate with a pointer to evaluation notebook outputs/figures.