README.md

metadata

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
  • Features
  • Built With
• Installation
  • Prerequisites
  • Getting Started
• Usage
  • API Endpoints
  • Example Request
• Roadmap
• 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

git clone https://gitlab.com/Alexis-Ravet/employee-churn-prediction.git
cd employee-churn-prediction

2. Install uv

# 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

# 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

# Linux/Mac
uv venv --python 3.12
source .venv/bin/activate  

# Windows (PowerShell)
uv venv --python 3.12
.venv\Scripts\Activate.ps1

4. Install production dependencies

uv sync --no-dev

5. Change git remote url to avoid accidental pushes to base project

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

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:

{
  "prediction": "Non",
  "probabilite": 0.127,
  "classe": 0
}

Roadmap

• RandomForestClassifier model training and serialization
• FastAPI REST API with Pydantic validation
• Custom data transformation pipeline
• Unit and functional test suites with Pytest
• CI/CD pipeline with GitLab
• Automated deployment to Hugging Face Spaces
• Test coverage reporting with pytest-cov and Cobertura
• 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.