README.md

🚀 Employee Turnover Prediction API - v2.1.0

📊 Vue d'ensemble

API REST de prédiction du turnover des employés basée sur un modèle XGBoost avec SMOTE.

✨ Nouveautés v2.1.0 :

• 📝 Logging structuré JSON
• 🛡️ Rate limiting (20 req/min par IP)
• ⚡ Gestion d'erreurs améliorée
• 📊 Monitoring des performances
• 🔐 Authentification API Key

🏗️ Architecture

OC_P5/
├── app.py                    # Point d'entrée FastAPI
├── src/
│   ├── auth.py              # Authentification API Key
│   ├── config.py            # Configuration centralisée
│   ├── logger.py            # Logging structuré (NOUVEAU)
│   ├── models.py            # Chargement modèle HF Hub
│   ├── preprocessing.py     # Pipeline preprocessing
│   ├── rate_limit.py        # Rate limiting (NOUVEAU)
│   └── schemas.py           # Validation Pydantic
├── tests/                   # Suite pytest (33 tests, 88% couverture)
├── logs/                    # Logs JSON (NOUVEAU)
│   ├── api.log              # Tous les logs
│   └── error.log            # Erreurs uniquement
├── docs/                    # Documentation
├── ml_model/                # Scripts training
└── data/                    # Données sources

🚀 Installation

Prérequis

• Python 3.12+
• Poetry 1.7+
• Git

Setup rapide

# 1. Cloner le repo
git clone https://github.com/chaton59/OC_P5.git
cd OC_P5

# 2. Installer les dépendances
poetry install

# 3. Configurer l'environnement
cp .env.example .env
# Éditer .env avec vos valeurs

# 4. Lancer l'API
poetry run uvicorn app:app --reload

# 5. Accéder à la documentation
# http://localhost:8000/docs

📝 Configuration (.env)

# Mode développement (désactive auth + active logs détaillés)
DEBUG=true

# API Key (requis en production)
API_KEY=your-secret-key-here

# Logging (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_LEVEL=INFO

# HuggingFace Model
HF_MODEL_REPO=ASI-Engineer/employee-turnover-model
MODEL_FILENAME=model/model.pkl

🔒 Authentification

Mode DEBUG (développement)

# L'API Key n'est PAS requise
curl http://localhost:8000/predict -H "Content-Type: application/json" -d '{...}'

Mode PRODUCTION

# L'API Key est REQUISE
curl http://localhost:8000/predict \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{...}'

📡 Endpoints

🏥 Health Check

GET /health

# Réponse
{
  "status": "healthy",
  "model_loaded": true,
  "model_type": "Pipeline",
  "version": "2.1.0"
}

🔮 Prédiction

POST /predict
Content-Type: application/json
X-API-Key: your-key (en production)

# Exemple payload (voir docs/API_GUIDE.md pour tous les champs)
{
  "satisfaction_employee_environnement": 3,
  "satisfaction_employee_nature_travail": 4,
  "satisfaction_employee_equipe": 5,
  "satisfaction_employee_equilibre_pro_perso": 3,
  "note_evaluation_actuelle": 85,
  "annees_depuis_la_derniere_promotion": 2,
  "nombre_formations_realisees": 3,
  ...
}

# Réponse
{
  "prediction": 0,                    # 0 = reste, 1 = part
  "probability_0": 0.85,              # Probabilité de rester
  "probability_1": 0.15,              # Probabilité de partir
  "risk_level": "Low"                 # Low, Medium, High
}

📊 Logging

Logs structurés JSON

Fichiers :

• logs/api.log : Tous les logs
• logs/error.log : Erreurs uniquement

Format :

{
  "timestamp": "2025-12-26T10:30:45",
  "level": "INFO",
  "logger": "employee_turnover_api",
  "message": "Request POST /predict",
  "method": "POST",
  "path": "/predict",
  "status_code": 200,
  "duration_ms": 23.45,
  "client_host": "127.0.0.1"
}

🛡️ Rate Limiting

Configuration :

• Développement : Désactivé (DEBUG=true)
• Production : 20 requêtes/minute par IP ou API Key

En cas de dépassement :

{
  "error": "Rate limit exceeded",
  "message": "20 per 1 minute"
}

✅ Tests

# Tous les tests
poetry run pytest tests/ -v

# Avec couverture
poetry run pytest tests/ --cov --cov-report=html

# Voir rapport HTML
open htmlcov/index.html

Résultats :

• ✅ 33 tests passés
• 📊 88% de couverture globale

🚀 Déploiement

Variables d'environnement requises

DEBUG=false
API_KEY=<votre-clé-sécurisée>
LOG_LEVEL=INFO

HuggingFace Spaces

Prêt pour déploiement avec app.py et requirements.txt

📚 Documentation

• API Interactive : http://localhost:8000/docs
• ReDoc : http://localhost:8000/redoc
• Guide complet : docs/API_GUIDE.md
• Standards : docs/standards.md
• Couverture tests : docs/TEST_COVERAGE.md

📦 Dépendances principales

• FastAPI 0.115.14 : Framework web
• Pydantic 2.12.5 : Validation données
• XGBoost 2.1.3 : Modèle ML
• SlowAPI 0.1.9 : Rate limiting
• python-json-logger 4.0.0 : Logs structurés
• pytest 9.0.2 : Tests

🔄 Changelog

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 (33 tests)
• 🔐 Authentification API Key
• 📊 88% de couverture de code

👥 Auteurs

• Projet : OpenClassrooms P5
• Repo : github.com/chaton59/OC_P5