---
title: Employee Churn Prediction
emoji: 📊
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: apache-2.0
short_description: Predicts employee turnover risk
---

![GitLab Contributors](https://img.shields.io/gitlab/contributors/79758190)
![GitLab Last Commit](https://img.shields.io/gitlab/last-commit/79758190)
![GitLab Forks](https://img.shields.io/gitlab/forks/79758190)
![GitLab Stars](https://img.shields.io/gitlab/stars/79758190)
![GitLab Issues](https://img.shields.io/gitlab/issues/all/79758190)
![GitLab License](https://img.shields.io/gitlab/license/79758190)

# 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

![Static Badge](https://img.shields.io/badge/uv-v0.8.17-blue?style=for-the-badge&logo=uv)

![Static Badge](https://img.shields.io/badge/fastapi-v0.129.0-blue?style=for-the-badge&logo=fastapi)

![Static Badge](https://img.shields.io/badge/pydantic-v2.12.5-blue?style=for-the-badge&logo=pydantic&logoColor=%23E92063)

![Static Badge](https://img.shields.io/badge/numpy-v2.3.5-blue?style=for-the-badge&logo=numpy&logoColor=%23013243)

![Static Badge](https://img.shields.io/badge/pandas-v2.3.3-blue?style=for-the-badge&logo=pandas&logoColor=%23150458)

![Static Badge](https://img.shields.io/badge/scikitlearn-v1.8.0-blue?style=for-the-badge&logo=scikitlearn)

![Static Badge](https://img.shields.io/badge/sqlalchemy-v2.0.46-blue?style=for-the-badge&logo=sqlalchemy&logoColor=%23D71F00)

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