README.md

---
title: Employee Turnover Prediction API
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: "6.2.0"
app_file: app.py
pinned: false
---

<div align="center">

# 🚀 Employee Turnover Prediction API

[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115.14-009688.svg)](https://fastapi.tiangolo.com)
[![Code Coverage](https://img.shields.io/badge/coverage-70.26%25-yellow.svg)](htmlcov/index.html)
[![Tests](https://img.shields.io/badge/tests-97%20passed-success.svg)](tests/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**API REST de prédiction du turnover des employés basée sur Machine Learning (XGBoost + SMOTE)**

[🔗 Demo Production](https://asi-engineer-oc-p5.hf.space) · [📚 Documentation](docs/) · [🐛 Report Bug](https://github.com/chaton59/OC_P5/issues) · [💡 Request Feature](https://github.com/chaton59/OC_P5/issues)

</div>

---

## 📋 Table des Matières

- [À Propos du Projet](#-à-propos-du-projet)
- [Architecture](#-architecture)
- [Choix Techniques](#-choix-techniques)
- [Installation](#-installation)
- [Utilisation](#-utilisation)
- [Déploiement](#-déploiement)
- [Mise à Jour](#-mise-à-jour)
- [Tests](#-tests)
- [Documentation](#-documentation)
- [Changelog](#-changelog)
- [Auteurs](#-auteurs)
- [Licence](#-licence)

> **Note**: Les dépendances complètes (transitives) sont listées dans [`requirements_dev.txt`](requirements_dev.txt) pour installation de développement complet.

---

## 📊 À Propos du Projet

### Vue d'ensemble

Ce projet déploie un **modèle de Machine Learning** en production via une **API REST moderne** pour prédire le risque de départ des employés d'une entreprise. Développé dans le cadre du projet OpenClassrooms P5 "Déployez votre modèle de Machine Learning", il illustre les **meilleures pratiques** d'ingénierie logicielle et de MLOps.

### Problématique

Les entreprises perdent des talents clés sans pouvoir anticiper. Ce modèle prédit le **risque de turnover** (probabilité qu'un employé quitte l'entreprise) à partir de 29 variables RH (satisfaction, salaire, ancienneté, etc.).

### Solution

API REST performante exposant un modèle **XGBoost optimisé** avec :
- ✅ **Validation robuste** des données via Pydantic
- ✅ **Prédictions en temps réel** (<2s) ou par batch (CSV)
- ✅ **Traçabilité complète** via PostgreSQL et logs JSON
- ✅ **Monitoring** et health checks intégrés
- ✅ **CI/CD automatisé** avec GitHub Actions
- ✅ **Déploiement cloud** sur HuggingFace Spaces

### Performances du Modèle

| Métrique | Valeur | Interprétation |
|----------|--------|----------------|
| **F1 Score** | 0.85 | Excellent équilibre précision/recall |
| **Recall** | 0.88 | Détecte 88% des départs réels |
| **Precision** | 0.82 | 82% des prédictions "départ" sont correctes |
| **ROC AUC** | 0.91 | Excellente capacité de discrimination |



### Fonctionnalités Clés


- 🔮 **Prédiction unitaire** : Prédit le risque pour un employé (JSON)
- 📦 **Prédiction batch** : Traite des fichiers CSV complets (1000+ employés)
- 🔐 **Authentification** : API Key sécurisée (production)
- 🛡️ **Rate limiting** : 20 req/min pour éviter les abus
- 📊 **Monitoring** : Health check et logs structurés JSON
- 🎨 **Interface Gradio** : UI web pour tests interactifs
- 📚 **Documentation auto** : Swagger UI et ReDoc intégrés
- 🗄️ **Traçabilité** : Toutes les prédictions enregistrées en base PostgreSQL

**Version actuelle** : 3.2.1 | **Dernière mise à jour** : Janvier 2026

---

## 🏗️ Architecture

### Vue d'ensemble High-Level

```
┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│   CLIENT     │────────▶│   API REST   │────────▶│  BASE DE     │
│              │  JSON   │   (FastAPI)  │  SQL    │  DONNÉES     │
│  • curl      │         │              │         │ (PostgreSQL) │
│  • Python    │         │  • Validation│         │              │
│  • JS        │◀────────│  • Authent.  │◀────────│  • dataset   │
│  • Postman   │  200 OK │  • Logging   │  SELECT │  • ml_logs   │
└──────────────┘         └──────┬───────┘         └──────────────┘
                                │
                                ▼
                         ┌──────────────┐
                         │   MODÈLE ML  │
                         │  (XGBoost +  │
                         │    SMOTE)    │
                         │              │
                         │ HF Hub Cache │
                         └──────────────┘
```

### Pipeline de Prédiction

```
Données brutes
    │
    ▼
┌─────────────────────┐
│  1. VALIDATION      │  Pydantic vérifie types, contraintes, énumérations
│     (Pydantic)      │  → Rejette données invalides (HTTP 422)
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  2. PREPROCESSING   │  • Feature engineering (ratios, moyennes)
│     (StandardScaler)│  • OneHot encoding (catégorielles non-ordonnées)
│                     │  • Ordinal encoding (fréquence déplacements)
└─────────┬───────────┘  • Scaling (StandardScaler)
          │
          ▼
┌─────────────────────┐
│  3. PRÉDICTION      │  XGBoost prédit classe (0/1) + probabilités
│     (XGBoost)       │  • 0 = Reste dans l'entreprise
└─────────┬───────────┘  • 1 = Va quitter l'entreprise
          │
          ▼
┌─────────────────────┐
│  4. POST-TRAITEMENT │  • Calcul niveau de risque (Low/Medium/High)
│     (API)           │  • Enregistrement en DB (ml_logs)
└─────────┬───────────┘  • Logging structuré JSON
          │
          ▼
    Réponse JSON
```

### Structure du Projet

```
OC_P5/
├── api.py                      # 🚪 Point d'entrée FastAPI principal
├── app.py                      # 🎨 Point d'entrée Gradio (HF Spaces)
├── src/
│   ├── auth.py                 # 🔐 Authentification API Key
│   ├── config.py               # ⚙️ Configuration centralisée (.env)
│   ├── logger.py               # 📝 Logging structuré JSON
│   ├── models.py               # 🤖 Chargement modèle depuis HuggingFace Hub
│   ├── preprocessing.py        # 🔧 Pipeline de preprocessing
│   ├── rate_limit.py           # 🛡️ Rate limiting (SlowAPI)
│   ├── schemas.py              # ✅ Validation Pydantic (29 champs)
│   └── gradio_ui.py            # 🎨 Interface Gradio web
├── tests/                      # ✅ Suite de tests (97 tests, 70% coverage)
│   ├── test_api_auth.py        # Tests authentification
│   ├── test_api_predict.py     # Tests prédictions
│   ├── test_api_validation.py  # Tests validation Pydantic
│   ├── test_database.py        # Tests PostgreSQL
│   └── test_model.py           # Tests modèle ML
├── ml_model/                   # 🎓 Scripts d'entraînement
│   ├── main.py                 # Pipeline complet train
│   ├── train_model.py          # Training XGBoost + MLflow
│   └── preprocess.py           # Preprocessing dataset
├── scripts/                    # 🔧 Scripts utilitaires
│   ├── create_db.py            # Création base PostgreSQL
│   ├── insert_dataset.py       # Insertion données (1470 employés)
│   ├── generate_requirements_hf.sh  # Génération requirements.txt pour HF
│   └── run_local.sh            # Lancement local développement
├── docs/                       # 📚 Documentation (5 fichiers minimaux)
│   ├── architecture.md         # 🏗️ Vue d'ensemble architecture + schéma BDD
│   ├── api_documentation.md    # 📡 Endpoints REST + exemples cURL/Python
│   ├── database_setup.md       # 🗄️ Setup PostgreSQL + requêtes SQL
│   ├── tests_report.md         # 🧪 Couverture tests (73%) + résultats
│   └── deployment_guide.md     # 🚀 CI/CD + déploiement HF Spaces
├── data/                       # 📊 Données sources (1470 employés)
│   ├── extrait_sondage.csv     # Données satisfaction
│   ├── extrait_eval.csv        # Données évaluations
│   └── extrait_sirh.csv        # Données RH administratives
├── logs/                       # 📋 Logs JSON
│   ├── api.log                 # Tous les événements
│   └── error.log               # Erreurs uniquement
├── .github/workflows/          # 🔄 CI/CD
│   └── ci-cd.yml               # GitHub Actions (lint, test, deploy)
├── pyproject.toml              # 📦 Configuration Poetry
├── .env.example                # 🔑 Template variables environnement
└── README.md                   # 📖 Ce fichier
```

---

## 🎯 Choix Techniques

### Justifications des Technologies

| Technologie | Alternative | Pourquoi ce choix ? |
|-------------|-------------|---------------------|
| **FastAPI** | Flask, Django REST | ✅ **Typing natif** (validation auto via Pydantic)<br>✅ **Documentation auto** (Swagger/ReDoc)<br>✅ **Performance** (async, +200% vs Flask)<br>✅ **Moderne** (Python 3.12, type hints) |
| **PostgreSQL** | MongoDB, SQLite | ✅ **Relationnel** adapté aux données structurées RH<br>✅ **ACID** pour garantir intégrité<br>✅ **Scalabilité** (index, partitioning)<br>✅ **Outils matures** (DBeaver, pgAdmin) |
| **XGBoost** | Random Forest, NN | ✅ **Performance** sur données tabulaires<br>✅ **Régularisation** intégrée (évite overfitting)<br>✅ **Feature importance** nativement<br>✅ **Rapide** (parallélisation) |
| **SMOTE** | Class weights, Under-sampling | ✅ **Génère exemples synthétiques** (vs duplication)<br>✅ **Évite surapprentissage**<br>✅ **Intégré imblearn** (CV-safe)<br>✅ +7% F1 vs class weights |
| **Pydantic** | Marshmallow, Cerberus | ✅ **Validation en C** (via Rust, très rapide)<br>✅ **Messages d'erreur clairs**<br>✅ **Intégration FastAPI** native<br>✅ **Type safety** compile-time |
| **HuggingFace Hub** | S3, GCP Storage | ✅ **Gratuit** jusqu'à 100GB<br>✅ **Versioning** automatique<br>✅ **CDN global** (latence faible)<br>✅ **Communauté** ML active |
| **Poetry** | pip, conda | ✅ **Lock file** (reproductibilité garantie)<br>✅ **Gestion dépendances** (résolution conflits)<br>✅ **Build/Publish** intégrés<br>✅ **pyproject.toml** standard moderne |
| **GitHub Actions** | GitLab CI, Jenkins | ✅ **Gratuit** pour repos publics<br>✅ **Intégration GitHub** native<br>✅ **Marketplace** d'actions prêtes<br>✅ **Déploiement HF** simplifié |

### Architecture Technique

**Pattern utilisé** : **3-Tier Architecture** (Présentation - Logique - Données)

```
┌─────────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                        │
│  • FastAPI (REST API)                                       │
│  • Gradio (Web UI)                                          │
│  • Swagger/ReDoc (Documentation interactive)                │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                     BUSINESS LAYER                           │
│  • Validation (Pydantic)                                    │
│  • Authentification (API Key)                               │
│  • Rate Limiting (SlowAPI)                                  │
│  • Preprocessing (Feature Engineering)                      │
│  • Prédiction (XGBoost Model)                               │
│  • Logging (JSON Structured)                                │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                      DATA LAYER                              │
│  • PostgreSQL (Traçabilité prédictions)                     │
│  • HuggingFace Hub (Modèle ML en cache)                     │
│  • CSV Files (Données sources)                              │
└─────────────────────────────────────────────────────────────┘
```

---

## ⚙️ Installation

### Prérequis

| Outil | Version | Installation |
|-------|---------|--------------|
| **Python** | 3.12+ | [python.org](https://www.python.org/downloads/) |
| **Poetry** | 1.7+ | `curl -sSL https://install.python-poetry.org \| python3 -` |
| **PostgreSQL** | 14+ | [postgresql.org](https://www.postgresql.org/download/) ou Docker |
| **Git** | 2.0+ | [git-scm.com](https://git-scm.com/downloads) |

### Étape 1 : Cloner le Repository



```bash
git clone https://github.com/chaton59/OC_P5.git
cd OC_P5
```

### Étape 2 : Installer les Dépendances

```bash
# Installation via Poetry (recommandé)
poetry install

# Activer l'environnement virtuel
poetry shell

# OU utiliser pip (fallback)
pip install -r requirements.txt
```

### Étape 3 : Configuration de l'Environnement

```bash
# Copier le template
cp .env.example .env

# Éditer .env avec vos valeurs
nano .env  # ou vim, code, etc.
```

**Variables à configurer** (`.env`) :

```bash
# === MODE ===
DEBUG=true  # false en production (active auth + rate limiting)

# === API ===
API_KEY=your-secret-api-key-here  # Générer avec: python -c "import secrets; print(secrets.token_urlsafe(32))"
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL

# === DATABASE (PostgreSQL) ===
DB_HOST=localhost
DB_PORT=5432
DB_NAME=oc_p5_db
DB_USER=ml_user
DB_PASSWORD=your-secure-password  # À changer !

# === HUGGINGFACE ===
HF_MODEL_REPO=ASI-Engineer/employee-turnover-model
MODEL_FILENAME=model/model.pkl
# HF_TOKEN=hf_xxx  # Optionnel (modèles publics)
```

### Étape 4 : Configurer la Base de Données PostgreSQL

#### Option A : Installation locale PostgreSQL

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# macOS (via Homebrew)
brew install postgresql@14
brew services start postgresql@14

# Windows : Télécharger depuis https://www.postgresql.org/download/windows/
```

#### Option B : Docker (recommandé pour développement)

```bash
# Démarrer PostgreSQL dans un conteneur
docker run --name oc_p5_postgres \
  -e POSTGRES_USER=ml_user \
  -e POSTGRES_PASSWORD=your-password \
  -e POSTGRES_DB=oc_p5_db \
  -p 5432:5432 \
  -d postgres:14
```

#### Créer les tables

```bash
# Créer les tables (dataset, ml_logs)
poetry run python scripts/create_db.py

# Insérer le dataset (1470 employés)
poetry run python scripts/insert_dataset.py

# Vérifier l'insertion
psql -h localhost -U ml_user -d oc_p5_db -c "SELECT COUNT(*) FROM dataset;"
# Résultat attendu : 1470
```

**Schéma de la base de données** :

![Schéma BDD](docs/schema.png)

📖 **Guide complet débutant** : [docs/database_guide.md](docs/database_guide.md)

### Étape 5 : Vérifier l'Installation

```bash
# Tester que tout fonctionne
poetry run pytest tests/ -v

# Résultat attendu : 97 tests passés (ou 86 si skipped déployés)
```

---

## 🔧 Scripts Utilitaires

Le dossier `scripts/` contient les scripts essentiels pour la gestion de la base de données et le déploiement. **Minimalisme** : 4 fichiers maximum, code principal dans `src/`, tests dans `tests/`.

### 🗄️ `create_db.py` - Création de la base de données

**Rôle** : Crée la base de données PostgreSQL et les tables nécessaires (étape 4 du projet).

```bash
# Créer les tables (dataset, ml_logs)
poetry run python scripts/create_db.py
```

**Tables créées** :
- `dataset` : Stockage des données d'entraînement (features_json, target)
- `ml_logs` : Logs des prédictions de l'API (inputs, outputs, timestamps)

### 📊 `insert_dataset.py` - Insertion du dataset

**Rôle** : Charge les 3 fichiers CSV (sondage, eval, sirh), les fusionne et insère 1470 employés dans PostgreSQL (étape 4 du projet).

```bash
# Insérer le dataset complet
poetry run python scripts/insert_dataset.py

# Vérifier l'insertion
psql -h localhost -U ml_user -d oc_p5_db -c "SELECT COUNT(*) FROM dataset;"
# Résultat attendu : 1470
```

**Fonctionnalités** :
- Fusionne automatiquement les 3 sources de données
- Nettoie les valeurs manquantes (NaN → None)
- Commits par batch de 100 pour performance
- Validation de l'intégrité des données

### 📦 `generate_requirements_hf.sh` - Requirements pour HF Spaces

**Rôle** : Génère un fichier `requirements.txt` minimaliste pour déploiement sur Hugging Face Spaces (étape 1 & 2).

```bash
# Générer requirements.txt optimisé pour HF
bash scripts/generate_requirements_hf.sh
```

**Pourquoi nécessaire ?** HF Spaces nécessite des dépendances minimales (pas dev/test). Ce script extrait uniquement les packages essentiels depuis `pyproject.toml`.

### 🚀 `run_local.sh` - Lancement local

**Rôle** : Script de démarrage rapide pour développement local.

```bash
# Lancer l'application en mode développement
bash scripts/run_local.sh
```

**Actions effectuées** :
1. Installation des dépendances (Poetry)
2. Vérification du fichier `.env` (copie `.env.example` si nécessaire)
3. Lancement de l'interface Gradio sur http://localhost:7860

### 📝 Organisation des Scripts

**Principe de séparation** :
- **`scripts/`** : Utilitaires BDD et déploiement uniquement (4 fichiers max)
- **`src/`** : Code applicatif principal (API, modèles, preprocessing)
- **`tests/`** : Tests unitaires et fonctionnels (séparé pour clarté)
- **`.github/workflows/`** : CI/CD (GitHub Actions, pas dans scripts/)

**Justifications** (liées aux étapes du projet) :
- ✅ **create_db.py** + **insert_dataset.py** : Étape 4 (script Python pour créer BDD + insérer dataset)
- ✅ **generate_requirements_hf.sh** : Étape 1 (requirements.txt à la racine) + Étape 2 (CI/CD, environnements)
- ✅ **run_local.sh** : Développement local (pas obligatoire mais pratique)
- ✅ **Tests dans `tests/`** : Étape 5 (scripts de tests + rapport couverture)

---

## 🚀 Utilisation

### Démarrer l'API Localement

```bash
# Mode développement (avec auto-reload)
poetry run uvicorn api:app --reload --host 127.0.0.1 --port 8000

# Mode production
poetry run uvicorn api:app --host 0.0.0.0 --port 8000 --workers 4
```

**URLs disponibles** :

| Service | URL | Description |
|---------|-----|-------------|
| **API** | http://localhost:8000 | Endpoint principal |
| **Swagger UI** | http://localhost:8000/docs | Documentation interactive |
| **ReDoc** | http://localhost:8000/redoc | Documentation alternative |
| **Health Check** | http://localhost:8000/health | Statut de l'API |
| **Gradio UI** | http://localhost:8000/ui | Interface web (si activée) |

### Exemples d'Appels API

#### 1. Health Check

```bash
curl http://localhost:8000/health
```

**Réponse** :
```json
{
  "status": "healthy",
  "model_loaded": true,
  "model_type": "Pipeline",
  "version": "3.2.1"
}
```

#### 2. Prédiction Unitaire (JSON)

```bash
# Sans authentification (DEBUG=true)
curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{
    "age": 35,
    "genre": "M",
    "revenu_mensuel": 4500.0,
    "satisfaction_employee_environnement": 3,
    ...
  }'

# Avec authentification (DEBUG=false)
curl -X POST http://localhost:8000/predict \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d @employee.json
```

**Réponse** :
```json
{
  "prediction": 0,
  "probability_0": 0.85,
  "probability_1": 0.15,
  "risk_level": "Low"
}
```

#### 3. Prédiction Batch (CSV)

```bash
curl -X POST http://localhost:8000/predict/batch \
  -H "X-API-Key: your-key" \
  -F "sondage_file=@data/extrait_sondage.csv" \
  -F "eval_file=@data/extrait_eval.csv" \
  -F "sirh_file=@data/extrait_sirh.csv"
```

**Réponse** :
```json
{
  "total_employees": 1470,
  "predictions": [...],
  "summary": {
    "total_stay": 1169,
    "total_leave": 301,
    "high_risk_count": 222
  }
}
```

### Utilisation Python (SDK)

```python
import requests

# Configuration
API_URL = "http://localhost:8000/predict"
API_KEY = "your-secret-key"

# Données employé
employee = {
    "age": 28,
    "genre": "F",
    "revenu_mensuel": 3200.0,
    "departement": "Consulting",
    # ... (tous les 29 champs requis)
}

# Appel API
response = requests.post(
    API_URL,
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json=employee
)

# Résultat
if response.status_code == 200:
    result = response.json()
    print(f"Risque de départ: {result['probability_1']:.0%}")
    print(f"Niveau: {result['risk_level']}")
```

📚 **Documentation API** : [docs/api_documentation.md](docs/api_documentation.md)

---

## 🌐 Déploiement

### Environnements Disponibles

| Environnement | Branche Git | URL HuggingFace Spaces | Statut |
|---------------|-------------|------------------------|--------|
| **Production** | `main` | https://asi-engineer-oc-p5.hf.space | ✅ Live |
| **Développement** | `dev` | https://asi-engineer-oc-p5-dev.hf.space | 🚧 Testing |

### 🤗 HuggingFace Spaces Integration

L'API est déployée sur **HuggingFace Spaces** avec une interface interactive Gradio.

#### Métadonnées HF Spaces

Le fichier `README_HF.md` est fusionné dans cette section pour HF Spaces:

```yaml
title: Employee Turnover Prediction API
emoji: 👔
colorFrom: blue
colorTo: purple
sdk: gradio
pinned: true
license: mit
app_port: 7860
```

#### Endpoints HF Spaces

| Endpoint | Description | Accès |
|----------|-------------|-------|
| `/docs` | Documentation interactive Swagger | Public |
| `/health` | Status de l'API | Public |
| `/ui` | Interface Gradio interactive | Public |
| `/predict` | Prédiction unitaire (JSON, contraintes réelles) | API Key requis |
| `/predict/batch` | Prédiction batch (3 fichiers CSV bruts) | API Key requis |

#### Exemple Utilisation HF Spaces

**Prédiction unitaire** (avec toutes contraintes appliquées):
```bash
curl -X POST https://asi-engineer-oc-p5.hf.space/predict \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "nombre_participation_pee": 0,
    "nb_formations_suivies": 2,
    "nombre_employee_sous_responsabilite": 1,
    ...
  }'
```

**Prédiction batch** (3 fichiers CSV):
```bash
curl -X POST https://asi-engineer-oc-p5.hf.space/predict/batch \
  -H "X-API-Key: your-key" \
  -F "sondage_file=@extrait_sondage.csv" \
  -F "eval_file=@extrait_eval.csv" \
  -F "sirh_file=@extrait_sirh.csv"
```

**Réponse batch**:
```json
{
  "total_employees": 1470,
  "predictions": [...],
  "summary": {
    "total_stay": 1169,
    "total_leave": 301,
    "high_risk_count": 222
  }
}
```

### Pipeline CI/CD (GitHub Actions)

Le workflow `.github/workflows/ci-cd.yml` s'exécute automatiquement à chaque push :

```mermaid
graph LR
    A[Push Code] --> B[Lint: Black + Flake8]
    B --> C[Tests: pytest 97 tests]
    C --> D[Test API Server]
    D --> E{Branche?}
    E -->|dev| F[Deploy HF Dev]
    E -->|main| G[Deploy HF Prod]
```

**Jobs du pipeline** :

1. **Lint** (~30s) : Black (formatage) + Flake8 (qualité)
2. **Tests** (~3min) : pytest avec couverture (70%)
3. **Test API Server** (~2min) : Démarrage uvicorn + tests `/health` et `/predict`
4. **Deploy** : Déploiement automatique sur HuggingFace Spaces

⚡ **Temps total** : ~5-7 minutes (< 10min requis)

### Déploiement Manuel sur HuggingFace Spaces

#### Prérequis

```bash
# Installer la CLI HuggingFace
pip install huggingface_hub

# Se connecter
huggingface-cli login
# Entrer votre token (créer sur https://huggingface.co/settings/tokens)
```

#### Pousser vers HF Spaces

```bash
# 1. Ajouter le remote HF
git remote add space https://huggingface.co/spaces/ASI-Engineer/oc_p5

# 2. Push vers HF
git push space main

# 3. Vérifier le déploiement
# Visiter https://huggingface.co/spaces/ASI-Engineer/oc_p5
```

#### Configuration des Secrets HF Spaces

Dans les settings du Space HuggingFace, ajouter :

| Variable | Valeur | Description |
|----------|--------|-------------|
| `API_KEY` | `votre-clé-sécurisée` | Authentification API |
| `DEBUG` | `false` | Mode production |
| `LOG_LEVEL` | `INFO` | Niveau de logs |

### Déploiement Docker (Alternative)

```bash
# Build de l'image
docker build -t employee-turnover-api .

# Run du conteneur
docker run -d \
  -p 8000:8000 \
  -e API_KEY=your-key \
  -e DEBUG=false \
  --name turnover-api \
  employee-turnover-api

# Vérifier
curl http://localhost:8000/health
```

📖 **Guide complet** : [docs/deployment_guide.md](docs/deployment_guide.md)

---

## 🔄 Mise à Jour

### Mise à Jour du Code

```bash
# 1. Récupérer les dernières modifications
git pull origin main

# 2. Mettre à jour les dépendances
poetry update

# 3. Appliquer les migrations DB (si nécessaire)
poetry run python scripts/migrate_db.py

# 4. Relancer l'API
poetry run uvicorn api:app --reload
```

### Ré-entraînement du Modèle

**Fréquence recommandée** : Tous les 3 mois (ou si drift détecté)

```bash
# 1. Préparer les nouvelles données
cp /path/to/new/data/*.csv data/

# 2. Lancer l'entraînement (avec MLflow tracking)
cd ml_model
poetry run python main.py

# 3. Comparer les performances
poetry run mlflow ui
# Ouvrir http://localhost:5000

# 4. Si F1 Score ≥ 0.83, exporter le modèle
poetry run python -c "
import joblib
import mlflow

client = mlflow.tracking.MlflowClient()
model_version = client.get_latest_versions('XGBoost_Employee_Turnover')[0]
model = mlflow.sklearn.load_model(model_version.source)
joblib.dump(model, 'model.pkl')
"

# 5. Uploader vers HuggingFace Hub
poetry run python -c "
from huggingface_hub import HfApi

api = HfApi()
api.upload_file(
    path_or_fileobj='model.pkl',
    path_in_repo='model/model.pkl',
    repo_id='ASI-Engineer/employee-turnover-model',
    commit_message='Update model v1.1 - F1=0.87'
)
"

# 6. Créer un tag Git pour versioning
git tag -a model-v1.1 -m "Model update: F1=0.87, Recall=0.89"
git push origin model-v1.1
```

### Monitoring du Drift

```python
# Script de détection de drift (à automatiser mensuellement)
import pandas as pd
from scipy.stats import ks_2samp

train_data = pd.read_csv('data/extrait_sirh.csv')
new_data = pd.read_csv('logs/recent_predictions.csv')

for col in ['age', 'revenu_mensuel', 'annees_dans_l_entreprise']:
    statistic, pvalue = ks_2samp(train_data[col], new_data[col])
    if pvalue < 0.05:
        print(f'⚠️ DRIFT détecté sur {col} (p={pvalue:.4f})')
        # → Déclencher ré-entraînement
```

📖 **Détails modèle & maintenance** : inclus dans [docs/architecture.md](docs/architecture.md) (section Pipeline ML) et [docs/tests_report.md](docs/tests_report.md) pour les vérifications automatiques.

---



## ✅ Tests

### Suite de Tests Complète

```bash
# Lancer tous les tests
poetry run pytest tests/ -v

# Avec rapport de couverture
poetry run pytest tests/ --cov=. --cov-report=term-missing

# Avec rapport HTML
poetry run pytest tests/ --cov=. --cov-report=html
open htmlcov/index.html
```

Pour le détail de l'organisation et des catégories de tests, voir `tests/README.md`.

### Métriques

| Métrique | Valeur | Détail |
|----------|--------|--------|
| **Tests** | 97 | 86 passés, 11 skippés (déploiement) |
| **Couverture** | 70.26% | Objectif : ≥ 70% |
| **Durée** | ~4s | Temps d'exécution total |
| **Fichiers** | 9 | test_api_*.py, test_database.py, test_model.py |

### Catégories de Tests

- ✅ **Authentification** (11 tests) : API Key, headers, rate limiting
- ✅ **Health Check** (6 tests) : Status, modèle chargé, versionning
- ✅ **Prédiction** (9 tests) : Endpoint `/predict`, probabilités, cohérence
- ✅ **Validation** (15 tests) : Pydantic, types, énumérations, limites
- ✅ **Database** (7 tests) : Connexion, CRUD, intégrité
- ✅ **Fonctionnel** (19 tests) : End-to-end, performance, erreurs
- ✅ **Modèle ML** (23 tests) : Chargement HF, preprocessing, prédictions
- ✅ **API Déployée** (7 tests skippés) : Tests sur HF Spaces

📊 **Détail de couverture** :

| Module | Couverture | Lignes | Manquantes |
|--------|------------|--------|------------|
| `src/config.py` | 100% | 20 | 0 |
| `src/schemas.py` | 100% | 100 | 0 |
| `src/rate_limit.py` | 100% | 10 | 0 |
| `db_models.py` | 100% | 14 | 0 |
| `src/logger.py` | 90.32% | 62 | 6 |
| `src/preprocessing.py` | 76.36% | 55 | 13 |
| `api.py` | 55.41% | 157 | 70 |

---

## 📚 Documentation


### Navigation dans le dossier `docs/`

Documentation **minimaliste et structurée** en **5 fichiers** couvrant tous les aspects du projet :

| Document | Description | Étapes OC |
|----------|-------------|-----------|
| [🏗️ architecture.md](docs/architecture.md) | Vue d'ensemble du projet, schéma architecture, diagramme BDD (PlantUML), flux de données | Étape 4, 6 |
| [📡 api_documentation.md](docs/api_documentation.md) | Documentation API REST : endpoints, schémas Pydantic, exemples cURL/Python, codes erreurs | Étape 3, 6 |
| [🗄️ database_setup.md](docs/database_setup.md) | Configuration PostgreSQL, scripts création BDD, requêtes SQL utiles, sauvegarde/restauration | Étape 4 |
| [🧪 tests_report.md](docs/tests_report.md) | Rapport de couverture (73%), détail des 48 tests unitaires/fonctionnels, commandes pytest | Étape 5 |
| [🚀 deployment_guide.md](docs/deployment_guide.md) | CI/CD GitHub Actions, déploiement HuggingFace Spaces, gestion secrets, monitoring | Étape 2, 6 |

**Choix de conception** : Documentation concise (1-2 pages par fichier) privilégiant la **clarté** et **l'actionnable** sur l'exhaustivité.

**Documentation interactive** :
- 🌐 **Swagger UI** : http://localhost:8000/docs
- 📘 **ReDoc** : http://localhost:8000/redoc

---

## 📦 Dépendances Principales

| Package | Version | Rôle |
|---------|---------|------|
| **FastAPI** | 0.115.14 | Framework API REST |
| **Pydantic** | 2.12.5 | Validation données |
| **XGBoost** | 2.1.3 | Modèle ML |
| **imbalanced-learn** | 0.12.0 | SMOTE (rééquilibrage) |
| **SQLAlchemy** | 2.0.23 | ORM PostgreSQL |
| **psycopg2-binary** | 2.9.9 | Driver PostgreSQL |
| **SlowAPI** | 0.1.9 | Rate limiting |
| **python-json-logger** | 4.0.0 | Logs structurés |
| **pytest** | 9.0.2 | Tests unitaires |
| **MLflow** | 2.9.2 | Tracking expériences ML |
| **Gradio** | 4.13.0 | Interface web |

Voir [pyproject.toml](pyproject.toml) pour la liste complète.

---



## 🔄 Changelog

### v3.3.0 (Janvier 2026)
- 📚 Documentation minimaliste consolidée en 5 fichiers (architecture, API, BDD, tests, déploiement)
- 🧹 Suppression des documents redondants et archives pour alléger la page HF
- 📝 README simplifié avec navigation claire vers la nouvelle doc

### v3.2.1 (Janvier 2026)
- 🎛️ Sliders Gradio et schémas Pydantic alignés sur les min/max réels des données d'entraînement
- 📦 Endpoint batch CSV (3 fichiers bruts)
- 🔑 Authentification API Key (prod)
- 🔧 Correction preprocessing (scaling, ordre des colonnes)
- 📝 Documentation mise à jour (API, modèle)

### v2.2.0 (27 Décembre 2025)
- 📦 Nouvel endpoint `/predict/batch` pour traitement CSV direct
- 🔧 Fix preprocessing : ajout du scaling des features
- 🔧 Fix preprocessing : correction de l'ordre des colonnes
- 📊 Amélioration précision des prédictions (~90%)

### v2.1.0 (26 Décembre 2025)
- ✨ Système de logging structuré JSON
- 🛡️ Rate limiting avec SlowAPI
- ⚡ Amélioration gestion d'erreurs
- 📊 Monitoring des performances

### v2.0.0 (26 Décembre 2025)
- ✅ Suite de tests complète (97 tests)
- 🔐 Authentification API Key
- 📊 70% de couverture de code

---

## 👥 Auteurs

**Développeur** : Valentin (chaton59)  
**Projet** : OpenClassrooms P5 - Déployez votre modèle de Machine Learning  
**Repo GitHub** : [github.com/chaton59/OC_P5](https://github.com/chaton59/OC_P5)  
**HuggingFace** : [ASI-Engineer](https://huggingface.co/ASI-Engineer)

---

## 📄 Licence

Ce projet est développé dans un cadre pédagogique (OpenClassrooms).  
Les données utilisées sont fictives.

---

## 🤝 Contributing

Les contributions sont bienvenues ! Pour contribuer :

1. Fork le projet
2. Créer une branche feature (`git checkout -b feature/AmazingFeature`)
3. Commit les changements (`git commit -m 'Add AmazingFeature'`)
4. Push vers la branche (`git push origin feature/AmazingFeature`)
5. Ouvrir une Pull Request

---

## 📞 Contact & Support

- **Issues GitHub** : [github.com/chaton59/OC_P5/issues](https://github.com/chaton59/OC_P5/issues)
- **Discussions** : [github.com/chaton59/OC_P5/discussions](https://github.com/chaton59/OC_P5/discussions)
- **Email** : Voir profil GitHub

---

## 🙏 Remerciements

- **OpenClassrooms** pour le parcours Data Scientist
- **HuggingFace** pour l'hébergement gratuit
- **FastAPI** pour le framework moderne
- **Communauté Python ML** pour les bibliothèques open-source

---

<div align="center">

**⭐ Si ce projet vous a aidé, n'hésitez pas à lui donner une étoile sur GitHub ! ⭐**

Made with ❤️ by [chaton59](https://github.com/chaton59)

</div>