Backend API REST pour RetentionAI, un système intelligent de prédiction et de rétention des employés basé sur le Machine Learning et l'IA générative.
Cette API fournit :
- 🔐 Authentification sécurisée avec JWT
- 🤖 Prédiction du risque de départ via Machine Learning
- 💡 Génération automatique de plans de rétention personnalisés
- 📊 Traçabilité complète des prédictions en base de données
retention-ai-backend/
├── app/
│ ├── __init__.py
│ │
│ ├── api/
│ │ ├── __init__.py
│ │ └── v1/
│ │ ├── __init__.py
│ │ ├── endpoints/
│ │ | ├── __init__.py
│ │ | ├── auth.py # /register, /login
│ │ | ├── predictions.py # /predict
│ │ | └── retention.py # /generate-retention-plan
│ │ |
| | └── deps.py # Dependencies (get_current_user, get_db)
| |
│ │
│ ├── core/
│ │ ├── __init__.py
│ │ └── security.py # JWT, password hashing functions
│ │
│ ├── db/
│ │ ├── __init__.py
│ │ └── session.py # Database session management
│ │
│ ├── models/
│ │ ├── __init__.py
│ │ ├── user.py # User SQLAlchemy model
│ │ ├── employe.py # Employe SQLAlchemy model
│ │ └── prediction_history.py # PredictionHistory SQLAlchemy model
│ │
│ ├── schemas/
│ │ ├── __init__.py
│ │ ├── auth.py # Token, TokenData schemas
│ │ ├── prediction.py # PredictionRequest, PredictionResponse
│ │ └── retention.py # RetentionPlanRequest, RetentionPlanResponse
│ │
│ ├── services/
│ │ ├── __init__.py
│ │ ├── llm_service.py # Call Hugging Face/Gemini API
│ │ └── retention_service.py # Business logic for retention plans
│ │
│ └── main.py # FastAPI app initialization
│
├── ml/
│ ├── __init__.py
│ ├── notebooks/
│ │ ├── 01_eda.ipynb # Exploratory Data Analysis
│ │ ├── 02_preprocessing.ipynb # Data preprocessing
│ │ └── 03_model_training.ipynb # Model training & evaluation
│ │
│ ├── data/
│ │ └──data.csv # dataset
│ │
│ ├── models/
│ │ └── proModel.pkl # Trained model (Random Forest/Logistic Regression)
│
├── tests/
│ ├── __init__.py
│ ├── test_predictions.py # Test prediction endpoint
│ └── test_ml_service.py # Test ML model loading and prediction
|
├── .env # Environment variables (not in git)
├── .gitignore # Git ignore file
├── .dockerignore # Docker ignore file
├── Dockerfile # Docker configuration for backend
├── docker-compose.yml # Docker Compose (backend + postgres)
├── requirements.txt # Python dependencies
└── README.md # Project documentation
- FastAPI - Framework web moderne et performant
- PostgreSQL - Base de données relationnelle
- SQLAlchemy - ORM Python
- Pydantic - Validation des données
- JWT (python-jose) - Authentification
- Bcrypt (passlib) - Hashing sécurisé
- Scikit-learn - Machine Learning
- Pandas & NumPy - Manipulation de données
- Pytest - Tests unitaires
- Docker - Conteneurisation
- Uvicorn - Serveur ASGI
- Google AI (Gemini)
- Python 3.10+
- PostgreSQL 14+
- Docker & Docker Compose (recommandé)
- Cloner le repository
git clone https://github.com/Khaoula1025/RetentionAI-Employee-Churn-Prediction-HR-Decision-Support-System-backend-.git- Configurer les variables d'environnement
cp .env.example .env
# Éditer .env avec vos configurations- Lancer avec Docker Compose
docker-compose up --buildL'API sera accessible sur http://localhost:8000
- Créer un environnement virtuel
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate- Installer les dépendances
pip install -r requirements.txt- Configurer PostgreSQL
# Créer la base de données
createdb retention_db- Configurer les variables d'environnement
cp .env.example .env
# Éditer .env- Lancer l'application
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000- Swagger UI :
http://localhost:8000/docs - ReDoc :
http://localhost:8000/redoc
Créer un nouveau compte utilisateur RH
Request:
{
"username": "hr_manager",
"password": "SecureP@ssw0rd"
}Response:
{
"id": 1,
"username": "hr_manager",
"created_at": "2025-12-19T10:30:00"
}Se connecter et obtenir un token JWT
Request:
{
"username": "hr_manager",
"password": "SecureP@ssw0rd"
}Response:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer"
}Prédire le risque de départ d'un employé
Headers:
Authorization: Bearer <your_jwt_token>
Request:
{
"age": 35,
"department": "Sales",
"job_role": "Sales Executive",
"monthly_income": 5000,
"years_at_company": 5,
"job_satisfaction": 2,
"work_life_balance": 3,
"performance_rating": 4,
"distance_from_home": 10,
"business_travel": "Travel_Frequently"
}Response:
{
"employee_id": "EMP001",
"churn_probability": 0.78,
"risk_level": "high",
"prediction_id": 123,
"timestamp": "2025-12-19T10:35:00"
}Générer un plan de rétention personnalisé
Headers:
Authorization: Bearer <your_jwt_token>
Request:
{
"employee_data": {
"age": 35,
"department": "Sales",
"job_role": "Sales Executive",
"job_satisfaction": 2,
"work_life_balance": 3,
"performance_rating": 4
},
"churn_probability": 0.78
}Response:
{
"retention_plan": [
"Proposer 2 jours de télétravail par semaine pour améliorer l'équilibre vie professionnelle/personnelle",
"Réévaluer la charge de déplacements professionnels et proposer des alternatives (visioconférence)",
"Mettre en place un plan de développement de carrière avec formation en management"
],
"risk_level": "high",
"generated_at": "2025-12-19T10:36:00"
}CREATE TABLE users (
id SERIAL PRIMARY KEY,
username VARCHAR(50) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);CREATE TABLE predictions_history (
id SERIAL PRIMARY KEY,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
user_id INTEGER REFERENCES users(id),
employee_id VARCHAR(50),
age INTEGER,
department VARCHAR(50),
job_role VARCHAR(100),
churn_probability FLOAT,
risk_level VARCHAR(20),
metadata JSONB
);- Algorithme principal : Random Forest Classifier
- Comparaison avec : Logistic Regression
- Optimisation : GridSearchCV
- Suppression des colonnes non pertinentes (ID, etc.)
- Encodage des variables catégorielles (OneHotEncoder)
- Normalisation/Standardisation (StandardScaler)
- Gestion des valeurs manquantes
- Accuracy : ~85%
- Precision : ~82%
- Recall : ~80%
- F1-Score : ~81%
- ROC-AUC : ~88%
# Ouvrir le notebook Jupyter
jupyter notebook notebooks/preprocessing&model_training.ipynb
# Le modèle entraîné sera sauvegardé dans app/ml/pytest tests/ -vpytest tests/ -v --cov=app --cov-report=htmlFROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]services:
db:
image: postgres:15
environment:
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: ${DB_NAME}
ports:
- "5432:5432"
# volumes:
# - postgres_data:/var/lib/postgresql/data
backend:
build: .
ports:
- "8000:8000"
environment:
DB_USER: ${DB_USER}
DB_PASSWORD: ${DB_PASSWORD}
DB_HOST: db
DB_PORT: 5432
DB_NAME: ${DB_NAME}
secret: ${SECRET}
GEMINI_API_KEY: ${GEMINI_API_KEY}
depends_on:
- db
frontend:
build: ../retentionai-frontend
ports:
- "3000:3000"
environment:
# For Next.js rewrites (server-side proxy)
API_URL: http://backend:8000
depends_on:
- backend- ✅ Hashing des mots de passe avec bcrypt (salt rounds: 12)
- ✅ Authentification JWT avec expiration
- ✅ Protection CORS configurée
- ✅ Validation des entrées avec Pydantic
- ✅ Protection contre les injections SQL (SQLAlchemy ORM)
- ✅ Variables sensibles dans .env (jamais commitées)
DEBUG=False
DATABASE_URL=postgresql://user:password@prod-db:5432/retention_db
SECRET_KEY=<générer-une-clé-forte>- Fork le projet
- Créer une branche (
git checkout -b feature/AmazingFeature) - Commit les changements (
git commit -m 'Add AmazingFeature') - Push vers la branche (
git push origin feature/AmazingFeature) - Ouvrir une Pull Request
Projet pédagogique - Tous droits réservés
Pour toute question :
- Ouvrir une issue sur GitHub
- Consulter la documentation API :
/docs