| --- |
| 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. |
|
|
