{"id":31556898,"url":"https://github.com/pradeep221b/customer_churn_prediction","last_synced_at":"2025-10-04T23:19:29.067Z","repository":{"id":317483550,"uuid":"1067601590","full_name":"pradeep221b/Customer_Churn_Prediction","owner":"pradeep221b","description":"A production-ready machine learning project in R for predicting customer churn, featuring a tuned XGBoost model and a REST API for live predictions.","archived":false,"fork":false,"pushed_at":"2025-10-01T05:47:26.000Z","size":198,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-01T07:25:49.936Z","etag":null,"topics":["api","customer-churn","data-science","explainable-ai","machine-learning","mlops","plumber","predictive-modeling","r","rstats","tidymodels","vetiver","xgboost"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pradeep221b.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T05:23:58.000Z","updated_at":"2025-10-01T05:51:51.000Z","dependencies_parsed_at":"2025-10-01T07:25:51.312Z","dependency_job_id":"420719d2-122a-4e05-a63e-9debb759383b","html_url":"https://github.com/pradeep221b/Customer_Churn_Prediction","commit_stats":null,"previous_names":["pradeep221b/customer_churn_prediction"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pradeep221b/Customer_Churn_Prediction","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pradeep221b%2FCustomer_Churn_Prediction","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pradeep221b%2FCustomer_Churn_Prediction/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pradeep221b%2FCustomer_Churn_Prediction/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pradeep221b%2FCustomer_Churn_Prediction/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pradeep221b","download_url":"https://codeload.github.com/pradeep221b/Customer_Churn_Prediction/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pradeep221b%2FCustomer_Churn_Prediction/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278386440,"owners_count":25978172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","customer-churn","data-science","explainable-ai","machine-learning","mlops","plumber","predictive-modeling","r","rstats","tidymodels","vetiver","xgboost"],"created_at":"2025-10-04T23:19:25.796Z","updated_at":"2025-10-04T23:19:29.056Z","avatar_url":"https://github.com/pradeep221b.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proactive Customer Churn Intervention with XGBoost and R\n\nThis project builds and deploys a classification model using XGBoost that predicts the probability of a telecom customer churning and provides actionable explanations for high-risk predictions.\n\n---\n\n### 💼 Business Problem \u0026 Value Proposition\n\nCustomer attrition is a critical business metric; retaining an existing customer is far more cost-effective than acquiring a new one. This project moves beyond a reactive strategy by creating a system to proactively identify customers at high risk of churning.\n\nThe model doesn't just predict *who* will churn, but provides explanations for *why* they are at risk. This allows a retention team to make targeted, personalized interventions—for example, offering a service upgrade to a customer frustrated with tech support, or a discount to someone flagged for high monthly charges. The tangible business value is realized through reduced churn, lower retention costs, and improved customer lifetime value.\n\n---\n\n### 🚀 Live API Endpoints (Demonstration)\n\nThe final model is deployed as a REST API, ready for integration into a production environment. Here are the available endpoints:\n\n* **`/predict`**: Accepts new customer data in JSON format and returns the probability of churn.\n* **`/explain`**: Accepts data for a single customer and returns its corresponding SHAP values, providing on-demand model transparency.\n\n**Example `curl` command to get a prediction:**\n```bash\n# (Example command - you would replace with your actual API URL and data)\ncurl -X POST \"[http://127.0.0.1:8000/predict](http://127.0.0.1:8000/predict)\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"gender\": \"Female\", \"SeniorCitizen\": 0, \"Partner\": \"Yes\", ...}'\n```\n\n---\n\n### 📊 Key Results \u0026 Visualizations\n\nThe final tuned XGBoost model significantly outperforms the naive baseline, demonstrating a strong ability to identify at-risk customers while maintaining high confidence in its predictions.\n\n| Model                   | ROC-AUC | PR-AUC | Recall | Precision |\n| ----------------------- | ------- | ------ | ------ | --------- |\n| Baseline (Majority Class) | 0.500   | 0.266  | 0.000  | NA        |\n| **Tuned XGBoost** | **0.859** | **0.678** | **0.775** | **0.904** |\n\n\n**Key Visualizations:**\n\n1.  **SHAP Summary Plot**: Shows the most important features driving churn predictions across all customers.\n2.  **SHAP Waterfall Plot**: Decomposes a single high-risk prediction, showing exactly how each feature contributed to the final score.\n\n\n---\n\n### 🛠️ Operational AI Skills Demonstrated\n\nThis project was engineered to reflect the best practices of operationalizing AI, ensuring the final product is reliable, safe, and efficient.\n\n* **1. Instrumentation \u0026 Monitoring** 📡\n    * The deployed API is structured for robust logging. Each call to the `/predict` endpoint can log the input features, the model's output probability, and the prediction latency, making the system observable and easy to debug.\n\n* **2. Evaluation** ✅\n    * A rigorous, offline evaluation protocol was used. The model was trained and validated on a split dataset and its performance measured against a held-out test set. The primary metric, PR-AUC, was chosen specifically to handle the known class imbalance in the data, ensuring the model is optimized for the correct business outcome.\n\n* **3. Safety \u0026 Quality Assurance** 🛡️\n    * The system includes inherent safety measures. Personally Identifiable Information (PII) is handled by assigning `customerID` an \"ID\" role in the recipe, preventing it from being used as a predictor. The API can be layered with input validation to reject malformed requests and content filters on outputs to prevent unexpected behavior.\n\n* **4. Reliability** 💪\n    * The model is deployed using `vetiver` and `plumber`, a production-grade stack for serving R models. This architecture ensures resilience. Reliability patterns like caching for frequent requests or retries with exponential backoff can be easily added to the API service to handle transient failures gracefully.\n\n* **5. Lifecycle Management** 🔄\n    * The project is designed for long-term maintenance. By continuously monitoring the model's PR-AUC on new, incoming data, a \"retraining trigger\" can be established. If performance degrades due to concept or data drift (e.g., PR-AUC drops below a set threshold), an automated retraining and deployment pipeline can be initiated to ensure the model remains accurate over time.\n\n* **6. Cost \u0026 Performance Optimization** 💰\n    * Efficiency is a core component of the design. XGBoost was chosen for its high performance on tabular data. Deploying the model as an on-demand API is highly cost-effective, as it avoids the need to run batch predictions on the entire customer base, consuming compute resources only when a prediction is requested.\n\n* **7. Agents \u0026 Workflows** 🤖\n    * This API is designed to be a \"tool\" in a larger, orchestrated business workflow. For instance, a CRM system could act as an \"agent\" that automatically calls the `/predict` endpoint for a customer after a support call. Based on the returned churn risk, the agent could then decide on a follow-up action, such as alerting a retention specialist or automatically sending a targeted offer.\n\n---\n\n### 💻 Tech Stack\n\n* **Modeling**: `tidymodels`, `recipes`, `parsnip`, `xgboost`\n* **Imbalance Handling**: `themis` (for SMOTE) \n* **Explainability**: `shapviz` (for SHAP values) \n* **Deployment**: `vetiver`, `plumber` \n* **Core R**: `dplyr`, `ggplot2` \n\n---\n\n### 🔬 Methodology\n\n1.  **EDA \u0026 Baseline**: The Telco dataset was loaded and explored, confirming a churn rate of ~27%. A naive baseline model (always predicting \"No Churn\") was established, which has an accuracy of ~73% but a recall of 0 for finding churners.\n2.  **Preprocessing**: A `tidymodels` recipe was built to handle data preparation. This included dummy coding for categorical variables, normalizing numeric predictors, and applying SMOTE to synthetically balance the training data, which is a crucial step for handling class imbalance.\n3.  **Model Training**: An initial XGBoost model was defined and bundled with the recipe into a `workflow` object.\n4.  **Hyperparameter Tuning**: The model was optimized using 10-fold cross-validation. `tune_grid` systematically tested 20 different hyperparameter combinations to find the set that maximized the PR-AUC metric.\n5.  **Finalization \u0026 Evaluation**: The workflow was finalized with the best hyperparameters and fit on the entire training set. [cite: 42, 43] Performance was then measured on the held-out test set to get a final, unbiased estimate of its effectiveness.\n6.  **Explainability**: SHAP values were calculated for the test set to provide both global feature importance and local, per-prediction explanations, turning the model from a \"black box\" into an interpretable tool.\n\n---\n\n### 🚀 How to Run\n\n**1. Setup the Environment**\n\nThis project uses `renv` for dependency management. To restore the environment, run:\n```R\n# Install renv if you haven't already\n# install.packages(\"renv\")\n\n# Restore the project's dependencies\nrenv::restore()\n```\nIf not using `renv`, manually install the packages listed in the **Tech Stack** section.\n\n**2. Run the Analysis**\n\nThe analysis is broken into scripts that should be run in order:\n```bash\n# 1. Exploratory Data Analysis and Baseline\nRscript 01_initial_eda.R\n\n# 2. Train the first, untuned model\nRscript 02_first_model.R\n\n# 3. Tune hyperparameters and train the final model\nRscript 03_tuned_model.R\n```\n\n**3. Launch the API**\n\nThe final model can be served locally using the `plumber` API script.\n```R\n# In an R session, run:\nplumber::pr(\"api/plumber.R\") %\u003e%\n  plumber::pr_run(port = 8000)\n```\nThe API will now be available at `http://127.0.0.1:8000`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpradeep221b%2Fcustomer_churn_prediction","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpradeep221b%2Fcustomer_churn_prediction","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpradeep221b%2Fcustomer_churn_prediction/lists"}