File size: 7,112 Bytes
02f31d3 47fbc41 8200ee1 0d468ed 8200ee1 0d468ed 8200ee1 0d468ed 8200ee1 0d468ed 8200ee1 47fbc41 8200ee1 47fbc41 8200ee1 0d468ed 8200ee1 47fbc41 8200ee1 0d468ed 8200ee1 47fbc41 8200ee1 47fbc41 8200ee1 47fbc41 8200ee1 47fbc41 8200ee1 47fbc41 8200ee1 47fbc41 8200ee1 47fbc41 0d468ed 47fbc41 0d468ed 47fbc41 0d468ed 47fbc41 e8ea78c 47fbc41 0d468ed 47fbc41 0d468ed 47fbc41 0d468ed 8200ee1 47fbc41 f4b285a 47fbc41 8200ee1 47fbc41 8200ee1 47fbc41 8200ee1 47fbc41 0d468ed 47fbc41 b666236 47fbc41 ee02de3 47fbc41 0d468ed 47fbc41 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | ---
title: Employee Churn Prediction
emoji: 📊
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: apache-2.0
short_description: Predicts employee turnover risk
---
# Employee Churn Prediction
## Table of Contents
- [About the Project](#about-the-project)
- [Features](#features)
- [Built With](#built-with)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Usage](#usage)
- [API Endpoints](#api-endpoints)
- [Example Request](#example-request)
- [Roadmap](#roadmap)
- [License](#license)
## About the Project
This project predicts whether an employee will leave the company based on a machine learning model exposed through a REST API built with FastAPI.
The pipeline works as follows: raw employee data is validated by a Pydantic schema, then transformed through a custom preprocessing module (`transformer.py`) that replicates the feature engineering steps from the training notebook — ordinal encoding, binarization, one-hot encoding, and derived features (`diff_note_evaluation`, `ratio_experience`, `ecart_revenu_categorie`). The transformed data is then fed to a RandomForestClassifier serialized as a `.pkl` file.
### Features
- Real-time prediction via a FastAPI REST API
- Automatic input validation with Pydantic (field constraints, Literal types, range checks)
- Custom data transformation module that mirrors the training pipeline
- RandomForestClassifier model with probability output
- Interactive Swagger UI and ReDoc documentation
- Unit tests (model loader, transformer) and functional tests (API endpoints) with Pytest
- Test coverage measurement with pytest-cov and Cobertura reports
- Automated CI/CD pipeline with GitLab (linting, testing, deployment)
- Automatic deployment to Hugging Face Spaces on push to `main`
- Linting and code formatting enforced with Ruff
### Built With
## Installation
### Prerequisites
- Git installed
- Python >= 3.12
> **Note:** You don't need Python installed on your machine. `uv` will automatically install Python 3.12 if it's not available.
### Getting Started
1. Clone the repository
```bash
git clone https://gitlab.com/Alexis-Ravet/employee-churn-prediction.git
cd employee-churn-prediction
```
2. Install uv
```bash
# Linux/Mac
# Use curl to download the script and execute it with sh:
curl -LsSf https://astral.sh/uv/0.8.17/install.sh | sh
# If your system doesn't have curl, you can use wget:
wget -qO- https://astral.sh/uv/0.8.17/install.sh | sh
```
```sh
# Windows (PowerShell)
# Use irm to download the script and execute it with iex:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.8.17/install.ps1 | iex"
```
3. Create and activate the virtual environment
```bash
# Linux/Mac
uv venv --python 3.12
source .venv/bin/activate
```
```sh
# Windows (PowerShell)
uv venv --python 3.12
.venv\Scripts\Activate.ps1
```
4. Install production dependencies
```bash
uv sync --no-dev
```
5. Change git remote url to avoid accidental pushes to base project
```sh
git remote set-url origin gitlab_username/repo_name
git remote -v # confirm the changes
```
## Usage
The API is automatically deployed to a Hugging Face Space via GitLab CI/CD whenever code is pushed to the `main` branch. The Space builds a Docker container from the `Dockerfile` and exposes the application on port 7860.
### API Endpoints
You can test the API directly from your browser by visiting the interactive documentation:
- **Swagger UI**: [https://alexis-ravet-employee-churn-prediction.hf.space/docs](https://alexis-ravet-employee-churn-prediction.hf.space/docs)
- **ReDoc**: [https://alexis-ravet-employee-churn-prediction.hf.space/redoc](https://alexis-ravet-employee-churn-prediction.hf.space/redoc)
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/` | Root endpoint — API info and version |
| `GET` | `/health` | Health check endpoint |
| `GET` | `/modele/info` | Model metadata (type, version, feature count) |
| `GET` | `/modele/features` | List of 24 expected features |
| `POST` | `/predire` | Predict employee churn from input data |
### Example Request
```bash
curl -X POST https://alexis-ravet-employee-churn-prediction.hf.space/predire \
-H "Content-Type: application/json" \
-d '{
"id_employee": 1,
"age": 35,
"genre": "M",
"revenu_mensuel": 4500,
"statut_marital": "Marié(e)",
"departement": "Consulting",
"poste": "Consultant",
"annee_experience_totale": 8,
"annees_dans_l_entreprise": 3,
"satisfaction_employee_environnement": 4,
"note_evaluation_precedente": 3,
"satisfaction_employee_nature_travail": 4,
"satisfaction_employee_equipe": 3,
"satisfaction_employee_equilibre_pro_perso": 3,
"note_evaluation_actuelle": 4,
"heure_supplementaires": "Non",
"augementation_salaire_precedente": 15,
"nombre_participation_pee": 2,
"nb_formations_suivies": 5,
"distance_domicile_travail": 25,
"niveau_education": 3,
"frequence_deplacement": "Occasionnel",
"annees_depuis_la_derniere_promotion": 2
}'
```
Response:
```json
{
"prediction": "Non",
"probabilite": 0.127,
"classe": 0
}
```
## Roadmap
- [x] RandomForestClassifier model training and serialization
- [x] FastAPI REST API with Pydantic validation
- [x] Custom data transformation pipeline
- [x] Unit and functional test suites with Pytest
- [x] CI/CD pipeline with GitLab
- [x] Automated deployment to Hugging Face Spaces
- [x] Test coverage reporting with pytest-cov and Cobertura
- [x] Add a database layer (Alembic + SQLAlchemy) for logging predictions
- [ ] Add a Gradio or Streamlit user interface for non-technical users
- [ ] Implement model versioning and packaging with Docker
## License
Distributed under the Apache License 2.0. See `LICENSE.txt` for more information.
|