Merge branch 'main' of https://github.com/Diaure/Futurisys_ML_API

.github/workflows/ci.yml

@@ -16,16 +16,15 @@ jobs:
     steps:
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.11.9"
 
       - uses: actions/checkout@v4
 
-      - name: Install dependencies
-        run: |
-          pip install .
-          pip install -r requirements.txt
-          pip install pytest
-
-      - name: Run tests
-        run: pytest
-
+      - name: Install Poetry 
+        run: pip install poetry 
+      
+      - name: Install dependencies with Poetry 
+        run: poetry install --no-interaction --no-root 
+        
+      - name: Run tests 
+        run: poetry run pytest

.gitignore

@@ -7,4 +7,4 @@ venv/
 App/model/
 *.joblib
 *.json
-App/model/modele_final_xgb.joblib
+App/model/modele_final_xgb.joblib

App/database.py

@@ -0,0 +1,30 @@
+import os
+from dotenv import load_dotenv
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, declarative_base
+
+load_dotenv()
+
+# Détection si on est en CI (GitHub Actions) ou en test 
+IS_CI = os.getenv("CI") == "true"
+IS_PYTEST = "pytest" in os.getenv("PYTHONPATH", "") or os.getenv("PYTEST_CURRENT_TEST") is not None 
+
+SKIP_DB = IS_CI or IS_PYTEST
+
+DB_USER = os.getenv("DB_USER", "postgres")
+DB_PASSWORD = os.getenv("DB_PASSWORD", "password")
+DB_HOST = os.getenv("DB_HOST", "localhost")
+DB_PORT = os.getenv("DB_PORT", "5432")
+DB_NAME = os.getenv("DB_NAME", "test_db")
+
+DATABASE_URL = (f"postgresql+psycopg2://{DB_USER}:{DB_PASSWORD}"f"@{DB_HOST}:{DB_PORT}/{DB_NAME}")
+
+Base = declarative_base()
+
+if not SKIP_DB:
+    engine = create_engine(DATABASE_URL)
+    SessionLocal = sessionmaker(autocommit = False, autoflush = False, bind = engine)
+
+else: 
+    engine = None 
+    SessionLocal = None

App/main.py

@@ -8,6 +8,10 @@ app = FastAPI(
     version="0.1.0"
 )
 
+@app.get("/") 
+def root(): 
+    return {"status": "API OK"}
+
 @app.post("/predict")
 def predict(data: EmployeeFeatures):
     """

App/model.py

@@ -0,0 +1,51 @@
+from sqlalchemy import Column, Integer, String, Float, Boolean, DateTime, ForeignKey
+from sqlalchemy.sql import func
+from App.database import Base
+
+class Input(Base):
+    __tablename__ = "inputs"
+
+    id = Column(Integer, primary_key=True, index=True)
+    genre = Column(String)
+    statut_marital = Column(String)
+    departement = Column(String)
+    poste = Column(String)
+    domaine_etude = Column(String)
+    frequence_deplacement = Column(String)
+    heure_supplementaires = Column(Boolean)
+    evolution_cat_evol = Column(String)
+    categorie_employe = Column(String)
+    satisfaction_employee_nature_travail = Column(Integer)
+    nombre_participation_pee = Column(Integer)
+    ecart_note_evaluation = Column(Integer)
+    revenu_mensuel = Column(Integer)
+    distance_domicile_travail = Column(Integer)
+    satisfaction_globale = Column(Float)
+    niveau_education = Column(Integer)
+    note_evaluation_actuelle = Column(Integer)
+    satisfaction_employee_equipe = Column(Integer)
+    age = Column(Integer)
+    revenu_par_annee_experience_interne = Column(Integer)
+    satisfaction_employee_equilibre_pro_perso = Column(Integer)
+    nombre_experiences_precedentes = Column(Integer)
+    annees_dans_l_entreprise = Column(Integer)
+    nb_formations_suivies = Column(Integer)
+    revenu_par_annee_experience_totale = Column(Integer)
+    ratio_sans_promotion = Column(Integer)
+    satisfaction_employee_environnement = Column(Integer)
+    exp_hors_entreprise = Column(Integer)
+    mobilite_promotion = Column(Integer)
+    annees_depuis_la_derniere_promotion = Column(Integer)
+
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+class Predictions(Base):
+    __tablename__ = "predictions"
+    id = Column(Integer, primary_key=True, index=True)
+    input_id = Column(Integer, ForeignKey("inputs.id"))
+
+    prediction_label = Column(String)
+    prediction_proba = Column(Float)
+    model_version = Column(String)
+
+    created_at = Column(DateTime(timezone=True), server_default=func.now())

App/model/variables_entree.json

@@ -1 +0,0 @@
-["genre", "statut_marital", "departement", "poste", "domaine_etude", "frequence_deplacement", "heure_supplementaires", "evolution_cat_evol", "categorie_employe", "satisfaction_employee_nature_travail", "nombre_participation_pee", "ecart_note_evaluation", "revenu_mensuel", "distance_domicile_travail", "satisfaction_globale", "niveau_education", "note_evaluation_actuelle", "satisfaction_employee_equipe", "age", "revenu_par_annee_experience_interne", "satisfaction_employee_equilibre_pro_perso", "nombre_experiences_precedentes", "annees_dans_l_entreprise", "nb_formations_suivies", "revenu_par_annee_experience_totale", "ratio_sans_promotion", "satisfaction_employee_environnement", "exp_hors_entreprise", "mobilite_promotion", "annees_depuis_la_derniere_promotion"]

App/predict.py

@@ -2,16 +2,43 @@ import joblib
 import pandas as pd
 from App.schemas import EmployeeFeatures
 import json
+from pathlib import Path
+from huggingface_hub import hf_hub_download
+from sqlalchemy.orm import Session
+from App.database import SessionLocal
+from App.model import Input, Predictions
 
+MODEL_REPO = "Diaure/xgb_model"
 
-model = joblib.load("App/model/modele_final_xgb.joblib")
+# Variables chargées
+model = None
+classes_mapping = None
+Features = list(EmployeeFeatures.model_fields.keys())
 
-FEATURES = list(EmployeeFeatures.model_fields.keys())
-with open("App/model/mapping_classes.json") as f: 
-    CLASS_MAPPING = json.load(f)
 
+
+# Chargement des fichiers: fonction pour charger le modèle, le mapping afin de permettre à l'API de démarrer m^me si les éléments ne sont pas présents
+def files_load():
+    global model, classes_mapping
+
+    if model is None:
+        chemin_model = Path(hf_hub_download(repo_id=MODEL_REPO, filename="modele_final_xgb.joblib"))
+        # if not chemin_model.exists():
+        #     raise RuntimeError("Eléments du modèle introuvable.")
+        model =joblib.load(chemin_model)
+
+    if classes_mapping is None:
+        chemin_mapping = Path(hf_hub_download(repo_id=MODEL_REPO, filename="mapping_classes.json"))
+        # if not chemin_mapping.exists():
+        #     raise RuntimeError("Mapping des classes introuvable.")
+        with open(chemin_mapping) as f:
+            classes_mapping = json.load(f)
+
+# Fonction prédiction
 def predict_employee(data: dict):
-    df = pd.DataFrame([data])[FEATURES]
+    files_load()
+
+    df = pd.DataFrame([data])[Features]
 
     print("Colonnes API :", df.columns.tolist()) 
     print("Nombre colonnes API :", len(df.columns))
@@ -19,7 +46,29 @@ def predict_employee(data: dict):
     pred = model.predict(df)[0]
     proba = model.predict_proba(df)[0][1]
 
+    db: Session = SessionLocal() if SessionLocal is not None else None
+
+    if db is not None:
+        try:
+            # enregistrer les inputs: à chaque appel de POST/predict, on stocke d'abord les entrées de l'utilisateur
+            input_row = Input(**data) 
+            db.add(input_row) 
+            db.commit() 
+            db.refresh(input_row)
+
+            # puis on récupère les ids générés automatiquement et enregistre les prédictions liés aux ids
+            pred_row = Predictions(input_id = input_row.id, prediction_label = classes_mapping[str(pred)], prediction_proba = float(proba), model_version = "v1") 
+            db.add(pred_row) 
+            db.commit()
+        
+        except Exception as e: 
+            print("🔥 ERREUR DB :", e) 
+            raise e
+
+        finally:
+            db.close()
+
+    # puis on renvoie la réponse API
     return {
-        "Prediction": CLASS_MAPPING[str(pred)],
-        "Probabilite_depart": float(proba)
-    }
+        "Prediction": classes_mapping[str(pred)],
+        "Probabilite_depart": float(proba)}

App/schemas.py

@@ -10,7 +10,6 @@ class EmployeeFeatures(BaseModel):
     heure_supplementaires: bool
     evolution_cat_evol: str
     categorie_employe: str
-
     satisfaction_employee_nature_travail: int
     nombre_participation_pee: int
     ecart_note_evaluation: int

Dockerfile

@@ -0,0 +1,13 @@
+# force rebuild
+FROM python:3.11
+
+WORKDIR /code
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "App.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,3 +1,13 @@
+---
+title: Futurisys ML API
+emoji: 🚀
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+---
+
+
 # Futurisys – Déploiement d’un modèle de Machine Learning via API
 
 ## Contexte
@@ -5,9 +15,7 @@
 opérationnels et accessibles via une API performante.
 
 Ce projet correspond à un **Proof of Concept (POC)** visant à déployer un modèle de machine
-learning en production en appliquant les bonnes pratiques d’ingénierie logicielle :
-versionnage, tests, base de données et automatisation.
-
+learning en production en appliquant les bonnes pratiques d’ingénierie logicielle: versionnage, tests, base de données et automatisation.
 
 
 ## Objectifs du projet
@@ -19,7 +27,7 @@ versionnage, tests, base de données et automatisation.
 
 
 ## Périmètre fonctionnel
-Le projet inclut :
+Le projet inclut:
 - Une API développée avec **FastAPI**
 - L’exposition d’un modèle de machine learning via des endpoints REST
 - Une base de données **PostgreSQL** pour stocker les entrées/sorties du modèle
@@ -27,53 +35,75 @@ Le projet inclut :
 - Un pipeline **CI/CD** pour automatiser les tests et le déploiement
 - Une documentation technique claire
 
-## CI/CD et qualité du code
+## CI/CD et Déploiement
+
+Ce projet met en œuvre une approche CI/CD complète, séparant:
+- l’intégration continue (**CI**): garantir la qualité du code
+- le déploiement continu (**CD**): rendre l’API accessible publiquement
+
+### `Intégration Continue (CI) – GitHub Actions`
 
-Ce projet utilise une pipeline d’intégration continue (CI) via GitHub Actions.
+L’intégration continue est assurée via GitHub Actions.
 
-À chaque push sur les branches de travail et à chaque pull request vers `develop`,
+À chaque **push** sur les branches de travail et à chaque **pull request** vers **`develop`**,
 le pipeline exécute automatiquement les étapes suivantes :
 - installation d’un environnement Python 3.11 isolé
 - installation des dépendances définies dans le projet
-- exécution des tests unitaires via pytest
+- exécution des tests automatisés avec Pytest
 
-L’objectif est de garantir que :
-- le projet reste installable
-- les transformations et composants (chargement du modèle, prédiction) ne régressent pas
-- toute fusion vers la branche `develop` est validée automatiquement
+L’objectif est de:
+- vérifier que le projet est installable
+- garantir que l’API démarre correctement
+- valider le chargement du modèle et le endpoint /*`predict`*
+- éviter toute régression avant fusion vers **`develop`**.
 
-## Architecture de l’API
+### `Déploiement Continu (CD) – Hugging Face Spaces`
 
-L’API est développée avec **FastAPI** et repose sur :
-- un schéma d’entrée validé avec **Pydantic**
-- un préprocesseur entraîné et sauvegardé
-- un modèle de machine learning sérialisé avec **joblib**
+Le déploiement de l’API est réalisé sur Hugging Face Spaces qui permet:
 
-Les artefacts du modèle sont stockés dans le dossier `App/model/` :
-- `preprocesseur_fitted.joblib`
-- `model_final_xgb.joblib`
-- `mapping_classes.json`
+- d’héberger gratuitement des applications ML
+- de déployer une API Dockerisée
+- d’exposer un service accessible publiquement sans gérer de serveur
 
-## Lancer l’API en local
+Dans ce projet, Hugging Face est utilisé comme plateforme de démonstration et de mise à disposition de l’API.
 
-Depuis la racine du projet :
+Le déploiement repose sur un Dockerfile, qui définit :
+- l’image Python utilisée (Python 3.11)
+- l’installation des dépendances
+- le lancement de l’API avec Uvicorn
+
+Il garantit la reproductibilité de l'environnement lors de l'exécution de l'API.
+
+A noter que les ***fichiers binaires*** ne sont pas stochés dans le dépôt GiHub principal pour les raisons suivantes:
+- Hugging Face bloque les push Git contenant des fichiers binaires lourds
+- Git n’est pas conçu pour versionner des artefacts ML volumineux.
+
+Pour contourner la situation, dans le projet, les artefacts sont stockés dans un Space Hugging Face dédié, séparé du code. Lors du démarrage de lAPI:
+- le code télécharge dynamiquement les artefacts via huggingface_hub
+- l’API peut démarrer même si les fichiers ne sont pas présents localement
 
-```bash
-uvicorn App.main:app --reload --log-level debug
-```
-L’API est alors accessible à l’adresse  http://127.0.0.1:8000/
 
-La documentation interactive à http://127.0.0.1:8000/docs
+### `Lancer l’API en local`
 
-### Endpoint principal
+L’API est déployée publiquement sur Hugging Face Spaces.
+
+- URL de l’API :
+https://diaure-futurisys-ml-api.hf.space
+- Documentation interactive (Swagger UI):
+https://diaure-futurisys-ml-api.hf.space/docs. Ele permet de:
+  - visualiser les endpoints
+  - tester directement l’endpoint `/predict`
+  - voir les schémas d’entrée et de sortie.
+
+### `Endpoint principal`
 `POST /predict`
 
-Cet endpoint reçoit les caractéristiques d’un employé et retourne :
+Cet endpoint reçoit les caractéristiques d’un employ�� et retourne:
 
 - une prédiction lisible ("Reste" ou "Part")
 - la probabilité associée au départ
 
-Exemple de réponse :
+Exemple de réponse:
 ```json
 {
   "Prediction": "Part",
@@ -83,26 +113,121 @@ Exemple de réponse :
 Les données d’entrée sont validées automatiquement avant l’appel au modèle,
 garantissant la cohérence avec les variables utilisées lors de l’entraînement.
 
-## Documentation des endpoints
+### `Documentation des endpoints`
 
 L’API expose un endpoint principal de prédiction.
 
 **POST /predict**
   - Description : retourne une prédiction de départ d’un employé
-  - Validation des données : Pydantic
-  - Réponses possibles :
-    - 200 : prédiction valide
-    - 422 : données invalides
+  - Validation des données: Pydantic
+  - Réponses possibles:
+    - 200: prédiction valide
+    - 422: données invalides
 
-## Stack technique
-- **Langage** : Python
-- **API** : FastAPI
-- **Machine Learning** : scikit-learn
-- **Base de données** : PostgreSQL
-- **Tests** : Pytest, pytest-cov
-- **CI/CD** : GitHub Actions
-- **Versionnage** : Git / GitHub
+## Base de données et traçabilité des prédictions
+### `Objectifs`
+
+L’intégration d’une base de données PostgreSQL permet d’inscrire le projet dans une logique MLOps et de répondre à plusieurs objectifs clés:
+- assurer la traçabilité complète des prédictions du modèle
+- conserver l’historique des données d’entrée utilisateur
+- stocker les résultats de prédiction (label, probabilité, version du modèle)
+- préparer une architecture compatible avec un déploiement en production.
+
+### `Méthodologie utilisée`
+- **PostgreSQL** a été retenu pour:
+  - sa robustesse et sa fiabilité
+  - sa compatibilité native avec SQLAlchemy
+  - son usage courant en environnement professionnel
+
+- **SQLAlchemy** est utilisé comme couche d’abstraction:
+  - gestion centralisée de la connexion à la base
+  - cohérence entre le schéma Python et la base SQL
+
+Les identifiants de connexion sont stockés dans des variables d’environnement (`.env`) afin d’éviter toute exposition de secrets dans le dépôt Git.
+
+### `Modélisation de la base de données`
+La base de données repose sur trois tables distinctes, chacune ayant un rôle précis.
+1. `employees_dataset - Dataset de référence`
+Il contient le dataset final nettoyé et préparé lors de l'entraînement du modèle en incluant l'ensemble des **32 deatures** du modèle. Il sert de:
+  - référence de schéma
+  - source de validation
+  - base documentaire du modèle
 
+C'est une table qui n'est jamais alimentée par l'utilisateur.
+
+```python
+load_dotenv()
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+csv_path = os.path.join(BASE_DIR, "dataset_final.csv")
+
+df = pd.read_csv(csv_path, encoding="latin-1")
+
+DB_USER = os.getenv("DB_USER")
+DB_PASSWORD = os.getenv("DB_PASSWORD")
+DB_HOST = os.getenv("DB_HOST")
+DB_PORT = os.getenv("DB_PORT")
+DB_NAME = os.getenv("DB_NAME")
+
+DATABASE_URL = (f"postgresql+psycopg2://{DB_USER}:{DB_PASSWORD}"f"@{DB_HOST}:{DB_PORT}/{DB_NAME}")
+
+engine = create_engine(DATABASE_URL)
+
+df.to_sql("employees_dataset", engine, if_exists="replace", index=False)
+```
+
+2. `inputs - Entrées utilisateur`
+  - Enregistre chaque requête utilisateur envoyée à l'endpoint `/predict`
+  - Contient exactement les features attendues par le modèle
+  - Structure strictement alignée avec le schéma Pydandic(`EmployeeFeatures`)
+  - Permet:
+    - l'audit des predictions
+    - l'analyse à posteriori
+    - la reproductibilité des résultats.
+```python
+class Input(Base):
+    __tablename__ = "inputs"
+
+    id = Column(Integer, primary_key=True, index=True)
+    genre = Column(String)
+    statut_marital = Column(String)
+    departement = Column(String)
+    poste = Column(String)
+```
+
+3. `predictions - Résultats du modèle`
+  - Continet:
+    - le label de prédiction
+    - la probabilité associée
+  - Reliée à `inputs` via une clé étrangère
+  - Garantit une trçabilité complète.
+```python
+class Predictions(Base):
+    __tablename__ = "predictions"
+    id = Column(Integer, primary_key=True, index=True)
+    input_id = Column(Integer, ForeignKey("inputs.id"))
+
+    prediction_label = Column(String)
+    prediction_proba = Column(Float)
+    model_version = Column(String)
+```
+
+### `Interaction API <> Base de données`
+Lors d’un appel à l’endpoint `POST /predict`:
+- les données utilisateur sont validées via **Pydantic**
+- les entrées sont enregistrées dans la table **inputs**
+- le modèle est exécuté
+- la prédiction est enregistrée dans la table **predictions**
+- la réponse est retournée à l’utilisateur.
+
+## Stack technique
+- **Langage**: Python
+- **API**: FastAPI
+- **Machine Learning**: scikit-learn
+- **Base de données**: PostgreSQL
+- **Tests**: Pytest, pytest-cov
+- **CI/CD**: GitHub Actions
+- **Versionnage**: Git / GitHub
 
 
 ## Structure du projet
@@ -111,7 +236,9 @@ futurisys_ml-api/
 ├── github/workflows
 │   ├── ci.yml       # Description des évènement déclenchants des tests
 ├── app/             # Code applicatif principal
+│   ├── database.py  # Point de connexion à la base PostgreSQL
 │   ├── main.py      # Point d’entrée de l’API
+│   ├── model.py     # Définition des tables de la database
 │   ├── predict.py   # Application du modèle
 │   ├── schemas.py   # Validation des données (Pydantic)
 │   ── model/                            # Elements du modèle
@@ -119,12 +246,18 @@ futurisys_ml-api/
 │   ├── modele_final_xgb.joblib          # Modèle final avec hyperparamètres
 │   ├── preprocesseur_fitted.joblib      # Pipeline entrainé
 |
-├── scripts/         # Scripts bd (BD, données)
-├── tests/           # Tests unitaires, fonctionnels
+├── scripts/                   # Scripts bd (BD, données)
+│   ├── create_tables.py       # Créaton des tables définies dans model.py
+│   ├── dataset_final.csv      # Data final
+│   ├── insert_dataset.py      # Code chargement de la table dataset_final
+├── tests/               # Tests unitaires, fonctionnels
 │   ├── test_api.py      # Test automatisé de l'API via Pytest
 |
+├── .env             # Stockage des variables sensibles et de configuration
 ├── .gitignore       # Nettoyage du dépôt
-├── pyproject.toml   # Librairies des modules entrainement ML
+├── Dockerfile       # Reproduction du dépôt
+├── poetry.lock      # Nettoyage du dépôt
+├── pyproject.toml   # Librairies dépendances ML
 ├── README.md        # Présentation du projet
-└── requirements.txt # Librairies des modules dispensables API
+└── requirements.txt # Librairies dépendances API
 ```

pyproject.toml

@@ -21,11 +21,19 @@ dependencies = [
     "catboost ==1.2.7",
     "numba ==0.59.1",
     "llvmlite ==0.42.0",
-    "ipykernel>=6.25,<7.0"
+    "ipykernel>=6.25,<7.0",
+    "huggingface-hub ==1.3.1",
+    "fastapi ==0.115.0",
+    "uvicorn ==0.30.1",
+    "python-dotenv ==1.2.1",
+    "psycopg2-binary ==2.9.11"
 ]
 
-
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"
 
+[tool.poetry.group.dev.dependencies]
+pytest = "9.0.2"
+
+

requirements.txt

@@ -6,4 +6,11 @@ Pygments==2.19.2
 pytest==9.0.2
 fastapi==0.115.0 
 uvicorn==0.30.1 
-httpx==0.27.0
+httpx==0.27.0
+huggingface-hub==1.3.1
+joblib==1.4.2
+pandas==2.2.2
+scikit-learn==1.4.2
+xgboost ==2.0.3
+huggingface-hub ==1.3.1
+python-dotenv ==1.2.1

scripts/create_tables.py

@@ -0,0 +1,6 @@
+from App.database import engine
+from App.database import Base
+
+Base.metadata.create_all(bind=engine)
+
+print("Tables créées avec succès")

scripts/insert_dataset.py

@@ -0,0 +1,25 @@
+import os
+import pandas as pd
+from dotenv import load_dotenv
+from sqlalchemy import create_engine
+
+load_dotenv()
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+csv_path = os.path.join(BASE_DIR, "dataset_final.csv")
+
+df = pd.read_csv(csv_path, encoding="latin-1")
+
+DB_USER = os.getenv("DB_USER")
+DB_PASSWORD = os.getenv("DB_PASSWORD")
+DB_HOST = os.getenv("DB_HOST")
+DB_PORT = os.getenv("DB_PORT")
+DB_NAME = os.getenv("DB_NAME")
+
+DATABASE_URL = (f"postgresql+psycopg2://{DB_USER}:{DB_PASSWORD}"f"@{DB_HOST}:{DB_PORT}/{DB_NAME}")
+
+engine = create_engine(DATABASE_URL)
+
+df.to_sql("employees_dataset", engine, if_exists="replace", index=False)
+
+print("Dataset inséré dans PostgreSQL")