heikalazzouna-svg/Tunisian-Telco-Churn

Tunisian Telco Customer Churn Prediction using XGBoost and Gradio # 🔮 Tunisian Telco Customer Churn Predictor An end-to-end Machine Learning pipeline that predicts customer churn for a Tunisian telecom operator. This project includes data processing, feature engineering, model training with XGBoost, experiment tracking with MLflow, and a production-ready serving environment using FastAPI and Gradio. ## ✨ Features - **XGBoost Classifier**: Optimized hyper-parameters for high recall and robust churn detection. - **FastAPI REST API**: High-performance backend exposing the model for programmatic access. - **Gradio Web UI**: Interactive user interface embedded directly into FastAPI for intuitive manual testing. - **MLflow Tracking**: Complete tracking of experiments, parameters, metrics, and models. - **Dockerized**: Fully containerized for consistent deployment across environments. - **CI/CD Pipeline**: GitHub Actions workflow for automated Docker image building and pushing to Docker Hub. --- ## 🚀 Quick Start (Local Development) ### 1. Setup Environment Make sure you are in the project root directory: ```bash # Create virtual environment and install dependencies python -m venv .venv # Activate environment # On Windows: .venv\Scripts\activate # On Linux/Mac: # source .venv/bin/activate # Install requirements pip install -r requirements.txt ``` ### 2. Run the Web Application The project already contains a pre-trained model exported to the `model_export/` directory. You can start the server immediately: ```bash python -m uvicorn src.app.main:app --host 127.0.0.1 --port 8000 ``` Once started, open your browser to access: - **🔮 Gradio Web UI**: 127.0.0.1 - **⚙️ API Documentation**: 127.0.0.1 - **💚 Health Check**: 127.0.0.1 ### 3. Run the ML Training Pipeline (Optional) If you want to retrain the model on the raw dataset: ```bash python scripts/run_pipeline.py --input data/raw/Tunisian_Telco_Customer_Churn.csv --target Churn ``` --- ## 🐳 Docker Deployment To build and te …