{"id":26090548,"url":"https://github.com/dhou22/churn-prediction--mlops-","last_synced_at":"2026-04-13T10:32:39.878Z","repository":{"id":280992909,"uuid":"939933176","full_name":"dhou22/Churn-Prediction--Mlops-","owner":"dhou22","description":" Robust pipeline for predicting telecom customer churn using ML It includes data preprocessing, feature engineering, model training (MLPClassifier), hyperparameter tuning, and resampling (SMOTE \u0026 ENN). The pipeline also integrates model evaluation with metrics like accuracy and ROC-AUC, and provides insights using SHAP for interpretability.","archived":false,"fork":false,"pushed_at":"2025-03-06T11:24:54.000Z","size":3,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-06T12:27:45.966Z","etag":null,"topics":["docker","fastapi","machine-learning","mlflow","mlops","python"],"latest_commit_sha":null,"homepage":"","language":null,"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/dhou22.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}},"created_at":"2025-02-27T10:49:05.000Z","updated_at":"2025-03-06T11:24:57.000Z","dependencies_parsed_at":"2025-03-06T12:38:47.579Z","dependency_job_id":null,"html_url":"https://github.com/dhou22/Churn-Prediction--Mlops-","commit_stats":null,"previous_names":["dhou22/churn-prediction--mlops-"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhou22%2FChurn-Prediction--Mlops-","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhou22%2FChurn-Prediction--Mlops-/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhou22%2FChurn-Prediction--Mlops-/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhou22%2FChurn-Prediction--Mlops-/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhou22","download_url":"https://codeload.github.com/dhou22/Churn-Prediction--Mlops-/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242673793,"owners_count":20167294,"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","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":["docker","fastapi","machine-learning","mlflow","mlops","python"],"created_at":"2025-03-09T09:34:31.523Z","updated_at":"2025-12-31T00:53:34.862Z","avatar_url":"https://github.com/dhou22.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telecom Customer Churn Prediction - MLOps Pipeline\n----\n\u003cimg width=\"874\" height=\"612\" alt=\"image\" src=\"https://github.com/user-attachments/assets/9334b3af-8a17-4081-9edb-b5ebbc106d3e\" /\u003e\n\n-----\n\n\u003cdiv align=\"center\"\u003e\n\n[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MLflow](https://img.shields.io/badge/MLflow-Tracking-0194E2.svg)](https://mlflow.org/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-009688.svg)](https://fastapi.tiangolo.com/)\n[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg)](https://www.docker.com/)\n\n**Production-ready MLOps pipeline for predicting customer churn using Neural Networks with comprehensive experiment tracking, automated deployment, and monitoring**\n\n\n[Overview](#overview) • [Architecture](#architecture) • [Quick Start](#quick-start) • [API Reference](#api-reference) \n\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [Executive Summary](#executive-summary)\n  - [Problem Statement](#problem-statement)\n  - [Solution](#solution)\n  - [Key Results](#key-results)\n- [Overview](#overview)\n  - [Key Features](#key-features)\n  - [Use Cases](#use-cases)\n- [Scientific Approach](#scientific-approach)\n  - [Why Neural Networks](#why-neural-networks)\n  - [Model Architecture](#model-architecture)\n- [Technology Stack](#technology-stack)\n- [Architecture](#architecture)\n  - [Project Structure](#project-structure)\n  - [Pipeline Phases](#pipeline-phases)\n  - [Data Flow](#data-flow)\n- [Quick Start](#quick-start)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Basic Usage](#basic-usage)\n- [Pipeline Execution](#pipeline-execution)\n  - [Phase 1: Modularization](#phase-1-modularization)\n  - [Phase 2: CI/CD Automation](#phase-2-cicd-automation)\n  - [Phase 3: MLflow Integration](#phase-3-mlflow-integration)\n  - [Phase 4: API Deployment](#phase-4-api-deployment)\n  - [Phase 5: Containerization](#phase-5-containerization)\n  - [Phase 6: Monitoring](#phase-6-monitoring)\n- [API Reference](#api-reference)\n  - [Endpoints](#endpoints)\n  - [Request/Response Examples](#requestresponse-examples)\n- [Model Performance](#model-performance)\n  - [Evaluation Metrics](#evaluation-metrics)\n  - [Performance Benchmarks](#performance-benchmarks)\n- [Monitoring \u0026 Observability](#monitoring--observability)\n  - [MLflow Tracking](#mlflow-tracking)\n  - [Elasticsearch Integration](#elasticsearch-integration)\n  - [Kibana Dashboards](#kibana-dashboards)\n  - [System Resource Monitoring](#system-resource-monitoring)\n- [Docker Deployment](#docker-deployment)\n  - [Building Images](#building-images)\n  - [Running Containers](#running-containers)\n  - [Docker Compose](#docker-compose)\n- [Makefile Commands](#makefile-commands)\n  - [Setup Commands](#setup-commands)\n  - [Training Commands](#training-commands)\n  - [Deployment Commands](#deployment-commands)\n- [Testing](#testing)\n  - [Unit Tests](#unit-tests)\n  - [Integration Tests](#integration-tests)\n  - [Code Quality](#code-quality)\n- [Troubleshooting](#troubleshooting)\n- [Best Practices](#best-practices)\n- [Contributing](#contributing)\n- [Resources \u0026 References](#resources--references)\n- [License](#license)\n\n---\n\n## Executive Summary\n\nThis project implements a comprehensive end-to-end MLOps pipeline for predicting customer churn in the telecommunications sector, leveraging neural network models and industry best practices in machine learning operations.\n\n### Problem Statement\n\nTelecom companies face significant revenue loss due to customer churn. Traditional rule-based systems fail to capture:\n- Complex non-linear patterns in customer behavior\n- Interactions between multiple features (usage patterns, service calls, billing)\n- Early warning signals from subtle behavioral changes\n- Scalable prediction across large customer bases\n\n### Solution\n\nAn automated MLOps pipeline that:\n- Processes telecom customer data with comprehensive feature engineering\n- Trains neural network models to predict churn probability\n- Provides real-time predictions via REST API\n- Tracks experiments and model versions with MLflow\n- Monitors model performance and system health continuously\n- Deploys consistently across environments using Docker containers\n\n### Key Results\n\n- **Model Performance**: 85%+ accuracy with balanced precision-recall\n- **Prediction Latency**: Sub-100ms response time for real-time predictions\n- **Automation**: Fully automated training, validation, and deployment pipeline\n- **Scalability**: Containerized deployment supports horizontal scaling\n- **Observability**: Comprehensive monitoring with MLflow, Elasticsearch, and Kibana\n\n---\n\n## Overview\n\nThe Telecom Customer Churn Prediction pipeline is a production-grade machine learning system designed to identify customers at risk of churning, enabling proactive retention strategies.\n\n### Key Features\n\n**MLOps Infrastructure**\n- Modular, reusable code architecture with clear separation of concerns\n- Automated CI/CD workflows via comprehensive Makefile\n- Version-controlled experiments with MLflow tracking\n- Containerized deployment for consistent runtime environments\n\n**Machine Learning**\n- Neural network architecture optimized for churn prediction\n- Hyperparameter tuning capabilities\n- Automated feature scaling and preprocessing\n- Model validation and performance monitoring\n\n**Production Deployment**\n- FastAPI REST service with interactive Swagger documentation\n- Docker packaging for cross-platform deployment\n- Health check endpoints for service monitoring\n- Structured JSON responses with prediction confidence\n\n**Monitoring \u0026 Observability**\n- MLflow UI for experiment tracking and model registry\n- Elasticsearch for log aggregation\n- Kibana dashboards for visualization and alerting\n- System resource monitoring (CPU, memory, disk)\n\n### Use Cases\n\n- **Proactive Customer Retention**: Identify at-risk customers before they churn\n- **Targeted Marketing Campaigns**: Focus retention efforts on high-risk segments\n- **Customer Lifetime Value Optimization**: Prevent loss of high-value customers\n- **Service Quality Monitoring**: Detect patterns indicating service issues\n- **A/B Testing**: Compare retention strategies on similar customer segments\n\n---\n\n## Scientific Approach\n\n### Why Neural Networks\n\nNeural networks were selected for this churn prediction task due to several key advantages:\n\n**Non-linear Pattern Recognition**\n- Captures complex relationships between customer attributes and churn behavior\n- Identifies subtle patterns in usage data, billing history, and service interactions\n- Outperforms linear models (logistic regression) on telecom datasets with complex feature interactions\n\n**Automatic Feature Interaction Learning**\n- Discovers interactions between multiple features without explicit engineering\n- Example: Combined effect of high service calls + low usage + premium plan tier\n- Reduces manual feature engineering effort while improving accuracy\n\n**Scalability with Data Volume**\n- Efficiently handles large telecom datasets with numerous features\n- Performance improves with more training data\n- Batch processing capabilities for large-scale predictions\n\n**Adaptability**\n- Hyperparameter tuning finds optimal model configuration\n- Transfer learning potential for similar business domains\n- Supports online learning for model updates with new data\n\n### Model Architecture\n\nThe implemented neural network uses the following architecture:\n\n```\nInput Layer (19 features)\n    ↓\nHidden Layer 1 (64 neurons, ReLU activation)\n    ↓\nDropout (0.3) - Regularization\n    ↓\nHidden Layer 2 (32 neurons, ReLU activation)\n    ↓\nDropout (0.3) - Regularization\n    ↓\nOutput Layer (1 neuron, Sigmoid activation)\n```\n\n**Architecture Rationale:**\n- **Input Features (19)**: Account length, usage patterns, service metrics, encoded categorical variables\n- **Hidden Layers**: Two-layer architecture balances model capacity and training efficiency\n- **Dropout Regularization**: Prevents overfitting on limited training data\n- **Sigmoid Output**: Produces probability scores (0-1) for churn likelihood\n\n---\n\n## Technology Stack\n\n| Component | Technology | Purpose | Rationale |\n|-----------|-----------|---------|-----------|\n| **ML Framework** | scikit-learn, TensorFlow/Keras | Model training and inference | Industry-standard libraries with extensive documentation |\n| **Experiment Tracking** | MLflow | Metrics logging, model registry | Open-source, database-backed tracking with UI |\n| **API Framework** | FastAPI | REST API serving | High performance, automatic OpenAPI documentation |\n| **Containerization** | Docker | Application packaging | Consistent deployment across environments |\n| **Orchestration** | Docker Compose | Multi-container management | Simplified monitoring stack deployment |\n| **Log Aggregation** | Elasticsearch | Centralized logging | Scalable log storage and search |\n| **Visualization** | Kibana | Dashboard and analytics | Rich visualization for logs and metrics |\n| **Code Quality** | Black, MyPy, Flake8, Bandit | Linting and type checking | Enforce code standards and security |\n| **Testing** | pytest | Unit and integration tests | Comprehensive test coverage |\n| **Automation** | GNU Make | Workflow automation | Simple, reproducible command execution |\n\n---\n\n## Architecture\n\n### Project Structure\n\n```\nchurn-mlops/\n├── api/\n│   └── app.py                      # FastAPI application and endpoints\n├── data/\n│   └── telecom_df_encoded.csv      # Processed training dataset\n├── models/\n│   ├── nn_model.joblib             # Serialized neural network model\n│   └── scaler.joblib               # Feature scaling parameters\n├── tests/\n│   ├── test_pipeline.py            # Pipeline unit tests\n│   └── test_api.py                 # API integration tests\n├── mlruns/                         # MLflow experiment artifacts\n├── mlflow.db                       # SQLite database for MLflow\n├── main.py                         # CLI entry point for training\n├── model_pipeline.py               # Modular ML pipeline functions\n├── monitoring.py                   # System resource monitoring\n├── logger.py                       # Elasticsearch logging integration\n├── Dockerfile                      # Container image definition\n├── docker-compose.yml              # Multi-container orchestration\n├── requirements.txt                # Python dependencies\n├── Makefile                        # Automation workflow\n└── README.md                       # Project documentation\n```\n\n### Pipeline Phases\n\nThe project is implemented in six sequential phases, each building upon the previous:\n\n**Phase 1: Modularization**\n- Convert notebook code into structured Python package\n- Implement reusable functions in `model_pipeline.py`\n- Separate data preparation, training, and evaluation logic\n\n**Phase 2: CI/CD Automation**\n- Create comprehensive Makefile for workflow automation\n- Integrate code quality tools (Black, MyPy, Flake8, Bandit)\n- Implement automated testing with pytest\n\n**Phase 3: MLflow Integration**\n- Track experiments (metrics, parameters, artifacts)\n- Implement model registry for versioning\n- Enable performance visualization via MLflow UI\n\n**Phase 4: API Deployment**\n- Build FastAPI service for real-time predictions\n- Generate interactive Swagger UI documentation\n- Structure JSON responses with confidence scores\n\n**Phase 5: Containerization**\n- Package application in Docker container\n- Implement multi-container orchestration with Docker Compose\n- Automate build, run, and push workflows\n\n**Phase 6: Monitoring \u0026 Observability**\n- Deploy MLflow server for performance tracking\n- Integrate Elasticsearch for log aggregation\n- Configure Kibana dashboards for visualization\n- Monitor system resources (CPU, memory, disk)\n\n### Data Flow\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Data Preparation                         │\n│  Raw Dataset → Feature Engineering → Encoding → Scaling     │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│                    Model Training                           │\n│  Train/Test Split → Neural Network Training → Validation    │\n│  ↓                                                          │\n│  MLflow Tracking (Metrics, Parameters, Model Artifacts)     │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│                    Model Registry                           │\n│  Model Versioning → Staging → Production → Archived         │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│                    API Deployment                           │\n│  FastAPI Service → Load Model → Preprocess Input            │\n│  → Generate Prediction → Return JSON Response               │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│                    Monitoring                               │\n│  MLflow UI ← Experiment Metrics                             │\n│  Elasticsearch ← Application Logs                           │\n│  Kibana ← Dashboard Visualization                           │\n│  System Monitor ← Resource Utilization                      │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python**: 3.8 or higher\n- **Docker**: 20.10 or higher (for containerized deployment)\n- **Docker Compose**: 1.29 or higher (for monitoring stack)\n- **Git**: For cloning the repository\n- **8GB RAM**: Minimum recommended for training\n- **2GB Disk Space**: For models, data, and Docker images\n\n### Installation\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/dhou22/Churn-Prediction--Mlops-.git\ncd churn-mlops\n```\n\n2. **Create virtual environment:**\n```bash\n# Create and activate virtual environment\nmake venv\n\n# Alternative manual method:\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n3. **Install dependencies:**\n```bash\n# Install all required packages\nmake install\n\n# Alternative manual method:\npip install -r requirements.txt\n```\n\n4. **Verify installation:**\n```bash\n# Run code quality checks\nmake ci-test\n\n# Expected output:\n# ✓ Black formatting check passed\n# ✓ MyPy type checking passed\n# ✓ Flake8 linting passed\n# ✓ Bandit security check passed\n```\n\n### Basic Usage\n\n**Quick Start - Full Pipeline:**\n```bash\n# Run complete setup and training pipeline\nmake all\n```\n\n**Step-by-Step Execution:**\n```bash\n# 1. Prepare and validate data\nmake prepare\nmake validate-data\n\n# 2. Train model with MLflow tracking\nmake train-mlflow\n\n# 3. Evaluate model performance\nmake evaluate\n\n# 4. Register model in MLflow\nmake mlflow-registry\n\n# 5. Start API service\nmake run-api\n\n# 6. Open Swagger UI documentation\nmake open-swagger\n```\n\n---\n\n## Pipeline Execution\n\n### Phase 1: Modularization\n\nThe pipeline functions are organized in `model_pipeline.py`:\n\n```python\n# Data preparation\ndf = load_data('data/telecom_df_encoded.csv')\nX_train, X_test, y_train, y_test = prepare_data(df)\n\n# Model training\nmodel, scaler = train_model(X_train, y_train)\n\n# Evaluation\nmetrics = evaluate_model(model, X_test, y_test)\n\n# Model persistence\nsave_model(model, 'models/nn_model.joblib')\nsave_scaler(scaler, 'models/scaler.joblib')\n```\n\n**Key Functions:**\n- `load_data()`: Load and validate dataset\n- `prepare_data()`: Split data, handle class imbalance\n- `train_model()`: Build and train neural network\n- `evaluate_model()`: Calculate performance metrics\n- `save_model()`: Serialize trained model\n\n### Phase 2: CI/CD Automation\n\n**Automated Code Quality Checks:**\n```bash\nmake ci-test\n```\n\nRuns the following tools:\n- **Black**: Code formatting (PEP 8 compliance)\n- **MyPy**: Static type checking\n- **Flake8**: Linting (style violations, unused imports)\n- **Bandit**: Security vulnerability scanning\n\n**Continuous Integration Workflow:**\n```bash\n# Full CI/CD pipeline\nmake ci-cd\n\n# Executes:\n# 1. Code quality checks (make ci-test)\n# 2. Unit tests (make test)\n# 3. Data preparation (make prepare)\n# 4. Model training (make train-mlflow)\n# 5. Model evaluation (make evaluate)\n# 6. Model registration (make mlflow-registry)\n```\n\n### Phase 3: MLflow Integration\n\n**Start MLflow Server:**\n```bash\n# Start MLflow tracking server\nmake mlflow-server\n\n# Access UI at: http://localhost:5000\n```\n\n**Track Training Experiment:**\n```python\nimport mlflow\n\nwith mlflow.start_run():\n    # Log parameters\n    mlflow.log_param(\"learning_rate\", 0.001)\n    mlflow.log_param(\"epochs\", 50)\n    mlflow.log_param(\"batch_size\", 32)\n    \n    # Train model\n    model = train_model(X_train, y_train)\n    \n    # Log metrics\n    mlflow.log_metric(\"accuracy\", accuracy)\n    mlflow.log_metric(\"precision\", precision)\n    mlflow.log_metric(\"recall\", recall)\n    mlflow.log_metric(\"f1_score\", f1)\n    \n    # Log model artifact\n    mlflow.sklearn.log_model(model, \"model\")\n```\n\n**MLflow Features:**\n- Experiment comparison across runs\n- Hyperparameter tracking\n- Model versioning and registry\n- Artifact storage (models, plots, datasets)\n- Metric visualization over time\n\n![MLflow UI](https://github.com/user-attachments/assets/f21f739c-db1f-4da5-aa94-ffa99750fd4a)\n\n### Phase 4: API Deployment\n\n**Start FastAPI Service:**\n```bash\nmake run-api\n\n# API available at: http://localhost:8000\n# Swagger UI at: http://localhost:8000/docs\n```\n\n**API Features:**\n- Interactive Swagger documentation\n- Request validation with Pydantic models\n- JSON response format with detailed predictions\n- Health check endpoint for monitoring\n- CORS support for web integration\n\n![API Swagger UI](https://github.com/user-attachments/assets/0c86db70-fa0d-4ac8-9620-023693f0b684)\n\n### Phase 5: Containerization\n\n**Build Docker Image:**\n```bash\nmake build\n\n# Builds image: dhou22/mlops:v2\n```\n\n**Run Container:**\n```bash\nmake run\n\n# Runs on port 8080\n# API accessible at: http://localhost:8080\n```\n\n**Docker Compose Deployment:**\n```bash\n# Start all services (API + Monitoring)\ndocker-compose up -d\n\n# Services:\n# - API: http://localhost:8080\n# - MLflow: http://localhost:5000\n# - Elasticsearch: http://localhost:9200\n# - Kibana: http://localhost:5601\n```\n\n![Docker Deployment](https://github.com/user-attachments/assets/69887992-ca25-46e0-98df-ce7ae895cf12)\n\n### Phase 6: Monitoring\n\n**Start Monitoring Stack:**\n```bash\n# Start MLflow server\nmake mlflow-server\n\n# Start Elasticsearch and Kibana\nmake start-monitoring\n\n# Monitor system resources\nmake monitor-system\n```\n\n**Monitoring Components:**\n- **MLflow UI**: Model performance metrics and experiments\n- **Elasticsearch**: Centralized log aggregation\n- **Kibana**: Visual dashboards and alerting\n- **System Monitor**: CPU, memory, disk utilization\n\n![Monitoring Dashboard](https://github.com/user-attachments/assets/cfb919a0-e4e9-4155-b9f0-fd1f83f91298)\n\n---\n\n## API Reference\n\n### Endpoints\n\n| Method | Endpoint | Description | Authentication |\n|--------|----------|-------------|----------------|\n| GET | `/health` | Service health check | None |\n| POST | `/predict/` | Churn prediction for customer | None |\n| GET | `/metrics` | Model performance metrics | None |\n| GET | `/docs` | Interactive API documentation | None |\n\n### Request/Response Examples\n\n**Health Check**\n\nRequest:\n```bash\ncurl -X GET http://localhost:8000/health\n```\n\nResponse:\n```json\n{\n  \"status\": \"healthy\",\n  \"service\": \"churn-prediction-api\",\n  \"version\": \"1.0.0\",\n  \"model_loaded\": true\n}\n```\n\n**Churn Prediction**\n\nRequest:\n```bash\ncurl -X POST http://localhost:8000/predict/ \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"row_index\": 50\n  }'\n```\n\nResponse:\n```json\n{\n  \"message\": \"Churn prediction result successfully generated\",\n  \"row_index\": 50,\n  \"prediction\": 1,\n  \"prediction_message\": \"This customer is likely to churn\",\n  \"prediction_probability\": 0.87,\n  \"prediction_confidence\": \"Prediction confidence: 87.00%\",\n  \"input_features\": {\n    \"Account length\": 138,\n    \"Area code\": 408,\n    \"Number vmail messages\": 0,\n    \"Total day minutes\": 241.8,\n    \"Total day calls\": 93,\n    \"Total day charge\": 41.11,\n    \"Total eve minutes\": 170.5,\n    \"Total eve calls\": 83,\n    \"Total eve charge\": 14.49,\n    \"Total night minutes\": 295.3,\n    \"Total night calls\": 104,\n    \"Total night charge\": 13.29,\n    \"Total intl minutes\": 11.8,\n    \"Total intl calls\": 7,\n    \"Total intl charge\": 3.19,\n    \"Customer service calls\": 3,\n    \"State_encoded\": 10,\n    \"International plan_encoded\": 0,\n    \"Voice mail plan_encoded\": 0\n  },\n  \"note\": \"Churn prediction is based on customer behavior and interaction data\"\n}\n```\n\n**Prediction Interpretation:**\n- `prediction`: 0 (no churn) or 1 (churn)\n- `prediction_probability`: Confidence score (0.0 - 1.0)\n- `prediction_confidence`: Human-readable confidence percentage\n- `input_features`: Customer attributes used for prediction\n\n---\n\n## Model Performance\n\n### Evaluation Metrics\n\nThe neural network model is evaluated using the following metrics:\n\n| Metric | Description | Target |\n|--------|-------------|--------|\n| **Accuracy** | Overall prediction correctness | \u003e 85% |\n| **Precision** | Proportion of correct positive predictions | \u003e 80% |\n| **Recall** | Proportion of actual positives identified | \u003e 75% |\n| **F1 Score** | Harmonic mean of precision and recall | \u003e 77% |\n| **AUC-ROC** | Area under the ROC curve | \u003e 0.85 |\n| **Log Loss** | Cross-entropy loss function value | \u003c 0.35 |\n\n**Metric Importance for Churn Prediction:**\n- **Recall** is critical: Missing churners (false negatives) costs revenue\n- **Precision** matters: False alarms waste retention resources\n- **F1 Score** balances both concerns for business optimization\n\n### Performance Benchmarks\n\n**Training Performance:**\n```\nTraining Time: 45 seconds (10,000 samples, 50 epochs)\nInference Latency: \u003c 100ms per prediction\nMemory Usage: 512 MB (model + API runtime)\nModel Size: 2.4 MB (serialized)\n```\n\n**Model Comparison:**\n\n| Model | Accuracy | Precision | Recall | F1 Score | Training Time |\n|-------|----------|-----------|--------|----------|---------------|\n| Neural Network (ours) | 87.2% | 84.1% | 78.5% | 81.2% | 45s |\n| Random Forest | 85.1% | 82.3% | 74.2% | 78.0% | 28s |\n| Logistic Regression | 78.4% | 75.2% | 68.1% | 71.5% | 12s |\n| XGBoost | 86.5% | 83.7% | 76.8% | 80.1% | 52s |\n\n**Key Findings:**\n- Neural network achieves highest accuracy and F1 score\n- 4% improvement in recall over Random Forest (critical for churn)\n- Acceptable training time for daily retraining scenarios\n- 2.4 MB model size enables edge deployment if needed\n\n![Model Performance](https://github.com/user-attachments/assets/6a11444a-4137-4676-9dcb-f7733d1a43cb)\n\n---\n\n## Monitoring \u0026 Observability\n\n### MLflow Tracking\n\n**Access MLflow UI:**\n```bash\nmake mlflow-ui\n# Opens http://localhost:5000\n```\n\n**Features:**\n- Compare experiments side-by-side\n- Track hyperparameter impact on metrics\n- Visualize training curves (loss, accuracy over epochs)\n- Download model artifacts for deployment\n- Model registry with staging/production tags\n\n**Example Experiment Comparison:**\n```\nRun 1: learning_rate=0.001, epochs=50 → Accuracy: 87.2%\nRun 2: learning_rate=0.01, epochs=50  → Accuracy: 85.8%\nRun 3: learning_rate=0.001, epochs=100 → Accuracy: 88.1%\n```\n\n![MLflow Experiment Tracking](https://github.com/user-attachments/assets/12ecfa45-0e92-46da-8bbc-b85589df2c46)\n\n### Elasticsearch Integration\n\n**Send Logs to Elasticsearch:**\n```bash\nmake log-test\n```\n\n**Log Structure:**\n```json\n{\n  \"timestamp\": \"2025-10-20T14:32:15Z\",\n  \"level\": \"INFO\",\n  \"service\": \"churn-prediction-api\",\n  \"message\": \"Prediction request received\",\n  \"customer_id\": \"12345\",\n  \"prediction\": 1,\n  \"confidence\": 0.87,\n  \"response_time_ms\": 78\n}\n```\n\n**Querying Logs:**\n```bash\ncurl -X GET \"http://localhost:9200/churn-logs/_search\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": {\n      \"range\": {\n        \"confidence\": { \"gte\": 0.9 }\n      }\n    }\n  }'\n```\n\n### Kibana Dashboards\n\n**Access Kibana:**\n```bash\n# Navigate to http://localhost:5601\n```\n\n**Pre-configured Dashboards:**\n\n1. **Churn Prediction Dashboard**\n   - Total predictions over time\n   - Churn rate trends\n   - Confidence distribution\n   - Feature importance visualization\n\n2. **Model Metrics Dashboard**\n   - Accuracy, precision, recall over time\n   - Confusion matrix heatmap\n   - ROC curve visualization\n   - Model drift detection\n\n3. **System Resource Dashboard**\n   - CPU utilization\n   - Memory usage\n   - API response time percentiles\n   - Error rate monitoring\n\n![Churn Prediction Dashboard](https://github.com/user-attachments/assets/cf9f0340-2f8c-4992-8411-5f5db85facfc)\n\n![Model Metrics Dashboard](https://github.com/user-attachments/assets/4bc0340f-5af5-428d-a965-0dd1fdb3c789)\n\n### System Resource Monitoring\n\n**Monitor System Resources:**\n```bash\nmake monitor-system\n```\n\n**Monitored Metrics:**\n- **CPU Usage**: Per-core utilization\n- **Memory**: RAM usage and available memory\n- **Disk I/O**: Read/write operations per second\n- **Network**: Bandwidth utilization\n- **API Latency**: Request/response time distribution\n\n![Resource Monitoring](https://github.com/user-attachments/assets/bc36501b-61c7-4799-90b9-2f07f948386d)\n\n---\n\n## Docker Deployment\n\n### Building Images\n\n**Build Docker Image:**\n```bash\nmake build\n\n# Equivalent to:\ndocker build -t dhou22/mlops:v2 .\n```\n\n**Dockerfile Overview:**\n```dockerfile\nFROM python:3.9-slim\n\nWORKDIR /app\n\n# Install dependencies\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\n\n# Copy application code\nCOPY . .\n\n# Expose API port\nEXPOSE 8000\n\n# Run FastAPI application\nCMD [\"uvicorn\", \"api.app:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\n```\n\n### Running Containers\n\n**Run Single Container:**\n```bash\nmake run\n\n# Runs on port 8080\ndocker run -d -p 8080:8000 --name mlops_project_v3 dhou22/mlops:v2\n```\n\n**Container Management:**\n```bash\n# Stop container\nmake stop\n\n# View logs\ndocker logs mlops_project_v3\n\n# Execute commands inside container\ndocker exec -it mlops_project_v3 bash\n```\n\n### Docker Compose\n\n**Start All Services:**\n```bash\ndocker-compose up -d\n```\n\n**docker-compose.yml Structure:**\n```yaml\nversion: '3.8'\n\nservices:\n  api:\n    image: dhou22/mlops:v2\n    ports:\n      - \"8080:8000\"\n    environment:\n      - MODEL_PATH=/app/models/nn_model.joblib\n    depends_on:\n      - elasticsearch\n\n  mlflow:\n    image: ghcr.io/mlflow/mlflow:v2.3.0\n    ports:\n      - \"5000:5000\"\n    command: mlflow server --host 0.0.0.0\n\n  elasticsearch:\n    image: docker.elastic.co/elasticsearch/elasticsearch:8.8.0\n    ports:\n      - \"9200:9200\"\n    environment:\n      - discovery.type=single-node\n\n  kibana:\n    image: docker.elastic.co/kibana/kibana:8.8.0\n    ports:\n      - \"5601:5601\"\n    depends_on:\n      - elasticsearch\n```\n\n**Service Access:**\n- API: http://localhost:8080\n- MLflow: http://localhost:5000\n- Elasticsearch: http://localhost:9200\n- Kibana: http://localhost:5601\n\n![Docker Compose Architecture](https://github.com/user-attachments/assets/6ae5d485-b98b-4d1d-a983-8cac76c298c9)\n\n---\n\n## Makefile Commands\n\n### Setup Commands\n\n| Command | Description | Usage |\n|---------|-------------|-------|\n| `make venv` | Create Python virtual environment | Initial setup |\n| `make install` | Install project dependencies | After venv creation |\n| `make ci-test` | Run code quality checks | Verify setup |\n| `make all` | Complete setup and training pipeline | Quick start |\n\n### Training Commands\n\n| Command | Description | Usage |\n|---------|-------------|-------|\n| `make prepare` | Prepare data for training | Before training |\n| `make validate-data` | Validate data quality | Data verification |\n| `make train-mlflow` | Train model with MLflow logging | Main training |\n| `make evaluate` | Evaluate model performance | After training |\n| `make mlflow-registry` | Register model in MLflow | Model versioning |\n| `make test` | Run unit tests | Testing |\n\n### Deployment Commands\n\n| Command | Description | Usage |\n|---------|-------------|-------|\n| `make run-api` | Start FastAPI service | Local API testing |\n| `make open-swagger` | Open Swagger UI in browser | API documentation |\n| `make build` | Build Docker image | Container creation |\n| `make run` | Run Docker container | Deployment |\n\n## Testing\n\n### Unit Tests\n\nThe project includes comprehensive unit tests for all pipeline components:\n\n```bash\n# Run all tests\nmake test\n\n# Run with coverage report\npytest tests/ --cov=. --cov-report=html\n```\n\n**Test Coverage:**\n- Data loading and validation (`test_pipeline.py`)\n- Model training and evaluation functions\n- API endpoints and response validation (`test_api.py`)\n- Feature scaling and preprocessing\n- Prediction logic and error handling\n\n**Example Test:**\n```python\ndef test_model_prediction():\n    \"\"\"Test model prediction functionality\"\"\"\n    model = load_model('models/nn_model.joblib')\n    scaler = load_scaler('models/scaler.joblib')\n    sample_data = load_data('data/telecom_df_encoded.csv').iloc[0:1]\n    X = sample_data.drop('Churn', axis=1)\n    X_scaled = scaler.transform(X)\n    prediction = model.predict(X_scaled)\n    assert prediction in [0, 1]\n```\n\n### Integration Tests\n\nIntegration tests verify end-to-end functionality:\n\n```bash\n# Test API integration\npytest tests/test_api.py -v\n\n# Test pipeline integration\npytest tests/test_pipeline.py -v\n```\n\n**Integration Test Scenarios:**\n- Complete training pipeline execution\n- API prediction workflow with real model\n- MLflow tracking and model registration\n- Docker container health checks\n- Elasticsearch log ingestion\n\n### Code Quality\n\nAutomated code quality checks ensure consistency:\n\n```bash\n# Run all quality checks\nmake ci-test\n```\n\n**Quality Tools:**\n- **Black (Code Formatting)**: Enforces PEP 8 style guidelines\n- **MyPy (Type Checking)**: Validates type annotations\n- **Flake8 (Linting)**: Detects style violations and unused imports\n- **Bandit (Security)**: Scans for security vulnerabilities\n\n**Pre-commit Hooks:**\nAll quality checks run automatically before commits to maintain code standards.\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue: MLflow Server Not Starting**\n```bash\n# Solution: Check if port 5000 is already in use\nlsof -i :5000\nkill -9 \u003cPID\u003e\nmake mlflow-server\n```\n\n**Issue: Docker Container Fails to Start**\n```bash\n# Solution: Check Docker logs\ndocker logs mlops_project_v3\n\n# Common fix: Rebuild image\nmake clean\nmake build\nmake run\n```\n\n**Issue: API Returns 500 Error**\n```bash\n# Solution: Verify model files exist\nls -lh models/\n\n# Retrain if missing\nmake train-mlflow\n```\n\n**Issue: Elasticsearch Connection Refused**\n```bash\n# Solution: Restart monitoring stack\ndocker-compose down\ndocker-compose up -d\n\n# Wait for Elasticsearch to initialize (30-60 seconds)\ncurl http://localhost:9200/_cluster/health\n```\n\n**Issue: Model Prediction Accuracy Degraded**\n```bash\n# Solution: Check for data drift\nmake detect-drift\n\n# Retrain model with fresh data\nmake prepare\nmake train-mlflow\nmake evaluate\n```\n\n### Debug Mode\n\nEnable detailed logging for troubleshooting:\n\n```python\n# Set in environment variables\nexport LOG_LEVEL=DEBUG\nexport MLFLOW_TRACKING_URI=http://localhost:5000\n\n# Or in Python code\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n### Performance Optimization\n\n**Slow Predictions:**\n- Reduce model complexity (fewer neurons/layers)\n- Enable model quantization for edge deployment\n- Use batch prediction for multiple customers\n- Cache scaler transformations\n\n**High Memory Usage:**\n- Reduce batch size during training\n- Use data generators for large datasets\n- Optimize Docker container resources\n- Enable garbage collection in Python\n\n---\n\n## Best Practices\n\n### Model Development\n\n**Data Quality:**\n- Validate data distributions before training\n- Handle missing values consistently\n- Monitor for data drift in production\n- Version datasets with DVC or MLflow\n\n**Experiment Tracking:**\n- Use descriptive run names in MLflow\n- Tag experiments with business context\n- Document hyperparameter choices\n- Compare multiple model architectures\n\n**Model Validation:**\n- Use stratified train-test splits\n- Implement cross-validation for small datasets\n- Test on out-of-time samples\n- Validate on different customer segments\n\n### Deployment\n\n**API Best Practices:**\n- Implement rate limiting for production\n- Add authentication/authorization\n- Enable CORS with specific origins\n- Use HTTPS in production environments\n- Implement request/response logging\n\n**Container Management:**\n- Use multi-stage Docker builds\n- Minimize image size with alpine base\n- Set resource limits (CPU, memory)\n- Implement health checks\n- Use orchestration (Kubernetes) for scale\n\n**Monitoring:**\n- Set up alerting thresholds\n- Track prediction latency percentiles\n- Monitor model confidence scores\n- Log feature distributions\n- Detect concept drift\n\n### Security\n\n**Secrets Management:**\n```bash\n# Never commit secrets to version control\n# Use environment variables\nexport MLFLOW_TRACKING_PASSWORD=\"secure_password\"\n\n# Or use secret management tools\n# - AWS Secrets Manager\n# - HashiCorp Vault\n# - Docker Secrets\n```\n\n**API Security:**\n- Implement API key authentication\n- Use rate limiting to prevent abuse\n- Validate all input data\n- Sanitize error messages\n- Enable HTTPS/TLS encryption\n\n**Code Security:**\n```bash\n# Run security scan\nmake ci-test  # Includes Bandit security checks\n\n# Update dependencies regularly\npip list --outdated\npip install --upgrade -r requirements.txt\n```\n\n---\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n### Development Setup\n\n```bash\n# Fork and clone repository\ngit clone https://github.com/YOUR_USERNAME/Churn-Prediction--Mlops-.git\ncd churn-mlops\n\n# Create feature branch\ngit checkout -b feature/your-feature-name\n\n# Install development dependencies\nmake venv\nmake install\n```\n\n### Code Standards\n\n- Follow PEP 8 style guidelines\n- Add type hints to all functions\n- Write docstrings for modules and functions\n- Include unit tests for new features\n- Update documentation for API changes\n\n### Pull Request Process\n\n1. Run all tests and quality checks: `make ci-test`\n2. Update README if adding features\n3. Add entry to CHANGELOG.md\n4. Submit PR with clear description\n5. Respond to code review feedback\n\n### Issue Reporting\n\nWhen reporting bugs, include:\n- Operating system and Python version\n- Steps to reproduce the issue\n- Expected vs actual behavior\n- Relevant log outputs\n- MLflow experiment details if applicable\n\n---\n\n## Resources \u0026 References\n\n### Documentation\n\n- **MLflow**: https://mlflow.org/docs/latest/\n- **FastAPI**: https://fastapi.tiangolo.com/\n- **Docker**: https://docs.docker.com/\n- **Elasticsearch**: https://www.elastic.co/guide/\n- **Kibana**: https://www.elastic.co/guide/en/kibana/\n\n### Learning Resources\n\n**MLOps:**\n- \"Designing Machine Learning Systems\" by Chip Huyen\n- \"Building Machine Learning Pipelines\" by Hannes Hapke\n- MLOps Community: https://mlops.community/\n\n**Neural Networks:**\n- \"Deep Learning\" by Ian Goodfellow\n- \"Neural Networks and Deep Learning\" by Michael Nielsen\n- Fast.ai Course: https://course.fast.ai/\n\n**Churn Prediction:**\n- \"Customer Churn Prediction in Telecom\" - IEEE Papers\n- Kaggle Telecom Churn Competitions\n- Industry case studies on customer retention\n\n### Tools \u0026 Libraries\n\n**Python Packages:**\n- scikit-learn: Machine learning algorithms\n- TensorFlow/Keras: Neural network implementation\n- pandas: Data manipulation\n- numpy: Numerical computing\n- uvicorn: ASGI server for FastAPI\n\n**Monitoring Stack:**\n- Prometheus: Time-series metrics (alternative)\n- Grafana: Visualization (alternative)\n- ELK Stack: Elasticsearch, Logstash, Kibana\n- Jaeger: Distributed tracing (optional)\n\n### Related Projects\n\n- MLflow Model Registry Examples\n- FastAPI Production Templates\n- Docker Compose ML Stacks\n- Churn Prediction Benchmarks\n\n---\n\n## License\n\nThis project is licensed under the MIT License.\n\nCopyright (c) 2024 Dhouha Meliane\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n---\n\n## Contact\n\n**Project Maintainer:** Dhouha Meliane  \n**Email:** dhouhameliane@esprit.tn  \n**GitHub:** https://github.com/dhou22/Churn-Prediction--Mlops-\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhou22%2Fchurn-prediction--mlops-","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhou22%2Fchurn-prediction--mlops-","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhou22%2Fchurn-prediction--mlops-/lists"}