v2_app

app.py

@@ -1,265 +1,515 @@
 """
-Fraud Detection API
-FastAPI application for real-time fraud detection predictions
-Model loaded from HuggingFace Hub
+🚨 Fraud Detection API - Level UP Edition
+=========================================
+
+API FastAPI pour la détection de fraude en temps réel
+avec preprocessing et feature engineering
+
+Fonctionnalités:
+- Download automatique du model + preprocessor depuis HuggingFace
+- 3 endpoints: /predict, /preprocess, /feat_eng
+- Feature engineering complet (distance GPS, features temporelles, âge)
+- Documentation interactive sur /docs
+
+Author: Terorra
+Date: January 2026
+Version: 2.0.0
 """
 
+# =====================================================================
+# IMPORTS
+# =====================================================================
+
+# FastAPI et types
 from fastapi import FastAPI, HTTPException, status
 from fastapi.responses import JSONResponse
-from pydantic import BaseModel, Field, validator
+from pydantic import BaseModel, Field
+from typing import List, Optional, Dict, Any
+
+# HuggingFace pour télécharger les modèles
 from huggingface_hub import hf_hub_download
 
+# ML et data
 import joblib
 import pandas as pd
+import numpy as np
+
+# Utilitaires
 import os
-from typing import List, Optional
 from datetime import datetime
+import time
+
+# Notre module de feature engineering
+from feature_engineering import (
+    engineer_features,
+    prepare_for_model,
+    get_model_features,
+    haversine_distance,
+    extract_time_features
+)
+
 
-# ==========================================
-# Configuration
-# ==========================================
+# =====================================================================
+# CONFIGURATION GLOBALE
+# =====================================================================
+
+# Repository HuggingFace où sont stockés les modèles
 REPO_ID = "Terorra/fd_model_jedha"
-MODEL_FILENAME = "fraud_model.pkl"
-MODEL_VERSION = None  # None = latest, or specify "v1", "v2", etc.
 
-# ==========================================
-# FastAPI App
-# ==========================================
+# Noms des fichiers sur HuggingFace
+MODEL_FILENAME = "fraud_model.pkl"           # Le modèle RandomForest
+PREPROCESSOR_FILENAME = "preprocessor.plk"   # Le preprocessor (ColumnTransformer)
+
+# Version du modèle (None = latest, ou "v1", "v2", etc.)
+MODEL_VERSION = None
+
+
+# =====================================================================
+# VARIABLES GLOBALES (modèles chargés en mémoire)
+# =====================================================================
+
+# Ces variables seront remplies au démarrage de l'API
+model = None         # Le modèle ML (RandomForestClassifier)
+preprocessor = None  # Le preprocessor (StandardScaler + OneHotEncoder)
+
+
+# =====================================================================
+# CRÉATION DE L'APPLICATION FASTAPI
+# =====================================================================
+
 app = FastAPI(
-    title="🚨 Fraud Detection API",
+    # Titre qui apparaît dans la doc
+    title="🚨 Fraud Detection API - Level UP",
+    
+    # Description complète (supporte Markdown)
     description="""
-    Real-time credit card fraud detection API powered by Machine Learning.
-    
-    ## Features
-    - **Real-time predictions** using RandomForest classifier
-    - **Model hosted on HuggingFace** for easy updates and versioning
-    - **High recall** (>90%) optimized for fraud detection
-    - **6 numeric features** required for prediction
-    
-    ## Model Details
-    - **Algorithm**: RandomForestClassifier (scikit-learn)
-    - **Training**: Balanced classes for fraud detection
-    - **Target Metric**: Recall > 90%
-    - **Features**: Transaction amount, customer/merchant locations, city population
-    
-    ## Use Cases
-    - Real-time transaction validation
-    - Batch fraud screening
-    - Risk assessment systems
-    - Payment gateway integration
+    # API de Détection de Fraude en Temps Réel
+    
+    Cette API utilise le Machine Learning pour détecter les transactions frauduleuses
+    sur les cartes de crédit.
+    
+    ## 🚀 Fonctionnalités
+    
+    ### Endpoints Principaux
+    
+    1. **`/predict`** - Prédiction complète
+       - Prend les données brutes
+       - Applique le feature engineering
+       - Applique le preprocessing
+       - Retourne la prédiction de fraude
+    
+    2. **`/feat_eng`** - Feature Engineering seulement
+       - Calcule la distance GPS client-marchand
+       - Extrait les features temporelles (heure, jour, weekend, etc.)
+       - Calcule l'âge du porteur
+       - Retourne les features transformées
+    
+    3. **`/preprocess`** - Preprocessing seulement
+       - Prend les features (déjà engineered)
+       - Applique StandardScaler (normalisation)
+       - Applique OneHotEncoder (encoding catégories)
+       - Retourne les features preprocessed (prêtes pour le modèle)
+    
+    ### Endpoints Utilitaires
+    
+    - **`/health`** - Vérifier que l'API fonctionne
+    - **`/model/info`** - Informations sur le modèle ML
+    - **`/features`** - Liste des features nécessaires
+    
+    ## 📊 Workflow Complet
+    
+    ```
+    Données Brutes
+        ↓
+    /feat_eng → Feature Engineering
+        ↓
+    /preprocess → Preprocessing (scaling + encoding)
+        ↓
+    /predict → Prédiction ML
+        ↓
+    Résultat: Fraude ou Non
+    ```
+    
+    ## 🎯 Modèle ML
+    
+    - **Algorithme**: RandomForestClassifier
+    - **Recall**: > 90% (optimisé pour détecter les fraudes)
+    - **Features**: 21 features (17 numériques + 4 catégorielles)
+    - **Preprocessing**: StandardScaler + OneHotEncoder
+    - **Hébergement**: HuggingFace Hub
+    
+    ## 💡 Cas d'Usage
+    
+    1. **Validation en temps réel**: Valider une transaction au moment du paiement
+    2. **Analyse batch**: Analyser des milliers de transactions historiques
+    3. **Monitoring**: Surveiller les patterns de fraude
+    4. **Reporting**: Générer des rapports de fraude
+    
+    ## 🔧 Feature Engineering
+    
+    L'API calcule automatiquement:
+    - **distance_km**: Distance GPS entre client et marchand (formule Haversine)
+    - **hour**: Heure de la transaction (0-23)
+    - **is_night, is_morning, is_afternoon, is_evening**: Période de la journée
+    - **is_business_hour**: Transaction pendant heures de bureau (8h-17h)
+    - **is_weekend**: Transaction le weekend
+    - **age**: Âge du porteur de carte
+    - **year, month, day, dayofweek**: Composantes de la date
+    
+    ## 📚 Documentation
+    
+    - Cette page: Documentation interactive avec exemples
+    - Essayez les endpoints directement depuis cette page!
+    - Chaque endpoint a des exemples pré-remplis
+    
+    ## 🎓 Pour Commencer
+    
+    1. Testez `/health` pour vérifier que l'API fonctionne
+    2. Regardez `/features` pour voir les features nécessaires
+    3. Essayez `/feat_eng` avec des données de test
+    4. Utilisez `/predict` pour une prédiction complète
     """,
-    version="1.0.0",
+    
+    version="2.0.0",
+    
     contact={
         "name": "Terorra",
         "email": "your.email@example.com",
     },
+    
     license_info={
         "name": "MIT",
-    }
+    },
+    
+    # Tags pour organiser les endpoints dans la doc
+    openapi_tags=[
+        {
+            "name": "🎯 Prediction",
+            "description": "Endpoints de prédiction de fraude"
+        },
+        {
+            "name": "🔧 Feature Engineering",
+            "description": "Transformation des features"
+        },
+        {
+            "name": "⚙️ Preprocessing",
+            "description": "Preprocessing des données"
+        },
+        {
+            "name": "📊 Information",
+            "description": "Informations sur l'API et le modèle"
+        },
+    ]
 )
 
-# ==========================================
-# Global Model Variable
-# ==========================================
-model = None
 
-# ==========================================
-# Pydantic Models (Request/Response Schemas)
-# ==========================================
+# =====================================================================
+# SCHEMAS PYDANTIC (Définition des types de données)
+# =====================================================================
 
-class TransactionInput(BaseModel):
+class TransactionRawInput(BaseModel):
     """
-    Input schema for a single transaction prediction
+    Données BRUTES d'une transaction (avant feature engineering)
+    
+    Ce sont les données telles qu'elles arrivent de la base de données
+    ou du système de paiement, SANS transformation.
     """
+    # Informations carte
+    cc_num: int = Field(
+        ...,
+        description="Numéro de carte de crédit (hashé)",
+        example=374125201044065
+    )
+    
+    # Montant
     amt: float = Field(
         ...,
-        description="Transaction amount in dollars",
+        description="Montant de la transaction en dollars",
         example=150.75,
-        gt=0,
-        le=100000
+        gt=0
     )
+    
+    # Localisation client
     lat: float = Field(
         ...,
-        description="Customer latitude (GPS coordinates)",
+        description="Latitude du client (coordonnées GPS)",
         example=40.7128,
         ge=-90,
         le=90
     )
     long: float = Field(
         ...,
-        description="Customer longitude (GPS coordinates)",
+        description="Longitude du client (coordonnées GPS)",
         example=-74.0060,
         ge=-180,
         le=180
     )
+    
+    # Ville
     city_pop: int = Field(
         ...,
-        description="Population of customer's city",
+        description="Population de la ville du client",
         example=8000000,
         gt=0
     )
+    zip: int = Field(
+        ...,
+        description="Code postal",
+        example=10001
+    )
+    
+    # Localisation marchand
     merch_lat: float = Field(
         ...,
-        description="Merchant latitude (GPS coordinates)",
+        description="Latitude du marchand (coordonnées GPS)",
         example=40.7589,
         ge=-90,
         le=90
     )
     merch_long: float = Field(
         ...,
-        description="Merchant longitude (GPS coordinates)",
+        description="Longitude du marchand (coordonnées GPS)",
         example=-73.9851,
         ge=-180,
         le=180
     )
     
+    # Marchand
+    merchant: str = Field(
+        ...,
+        description="Nom du marchand",
+        example="Amazon"
+    )
+    category: str = Field(
+        ...,
+        description="Catégorie de transaction",
+        example="shopping_net"
+    )
+    
+    # Client
+    gender: str = Field(
+        ...,
+        description="Genre du client (M/F)",
+        example="M"
+    )
+    state: str = Field(
+        ...,
+        description="État (US)",
+        example="NY"
+    )
+    dob: str = Field(
+        ...,
+        description="Date de naissance (YYYY-MM-DD)",
+        example="1990-01-15"
+    )
+    
+    # Transaction
+    transaction_time: str = Field(
+        ...,
+        description="Heure de la transaction (YYYY-MM-DD HH:MM:SS)",
+        example="2026-01-29 14:30:00"
+    )
+    
     class Config:
         schema_extra = {
             "example": {
+                "cc_num": 374125201044065,
                 "amt": 150.75,
                 "lat": 40.7128,
                 "long": -74.0060,
                 "city_pop": 8000000,
+                "zip": 10001,
                 "merch_lat": 40.7589,
-                "merch_long": -73.9851
+                "merch_long": -73.9851,
+                "merchant": "Amazon",
+                "category": "shopping_net",
+                "gender": "M",
+                "state": "NY",
+                "dob": "1990-01-15",
+                "transaction_time": "2026-01-29 14:30:00"
             }
         }
 
 
-class BatchTransactionInput(BaseModel):
+class FeaturesEngineeredOutput(BaseModel):
     """
-    Input schema for batch predictions
+    Résultat du Feature Engineering
+    
+    Contient les données originales + les features calculées
     """
-    transactions: List[TransactionInput] = Field(
+    # Données originales
+    original_data: Dict[str, Any] = Field(
         ...,
-        description="List of transactions to predict",
-        min_items=1,
-        max_items=100
+        description="Données brutes d'entrée"
     )
     
-    class Config:
-        schema_extra = {
-            "example": {
-                "transactions": [
-                    {
-                        "amt": 150.75,
-                        "lat": 40.7128,
-                        "long": -74.0060,
-                        "city_pop": 8000000,
-                        "merch_lat": 40.7589,
-                        "merch_long": -73.9851
-                    },
-                    {
-                        "amt": 2500.00,
-                        "lat": 34.0522,
-                        "long": -118.2437,
-                        "city_pop": 100,
-                        "merch_lat": 51.5074,
-                        "merch_long": -0.1278
-                    }
-                ]
-            }
-        }
+    # Features engineered
+    engineered_features: Dict[str, Any] = Field(
+        ...,
+        description="Nouvelles features calculées"
+    )
+    
+    # Toutes les features combinées
+    all_features: Dict[str, Any] = Field(
+        ...,
+        description="Données originales + features engineered"
+    )
+
+
+class PreprocessedOutput(BaseModel):
+    """
+    Résultat du Preprocessing
+    
+    Features transformées (scaled + encoded) prêtes pour le modèle
+    """
+    preprocessed_shape: tuple = Field(
+        ...,
+        description="Dimensions des données preprocessed (lignes, colonnes)"
+    )
+    
+    sample_values: List[float] = Field(
+        ...,
+        description="Premières valeurs (pour debug)"
+    )
+    
+    message: str = Field(
+        ...,
+        description="Message de confirmation"
+    )
 
 
 class PredictionOutput(BaseModel):
     """
-    Output schema for a single prediction
+    Résultat de la Prédiction de Fraude
     """
+    # Prédiction
     is_fraud: bool = Field(
         ...,
-        description="Whether the transaction is predicted as fraud"
+        description="True si la transaction est frauduleuse"
     )
+    
     fraud_probability: float = Field(
         ...,
-        description="Probability of fraud (0.0 to 1.0)",
+        description="Probabilité de fraude (0.0 à 1.0)",
         ge=0.0,
         le=1.0
     )
+    
+    # Classification du risque
     risk_level: str = Field(
         ...,
-        description="Risk classification: LOW, MEDIUM, HIGH, CRITICAL"
+        description="Niveau de risque: LOW, MEDIUM, HIGH, CRITICAL"
     )
+    
+    # Confiance du modèle
     confidence: float = Field(
         ...,
-        description="Model confidence in the prediction (0.0 to 1.0)",
+        description="Confiance du modèle (0.0 à 1.0)",
         ge=0.0,
         le=1.0
     )
+    
+    # Métadonnées
     timestamp: str = Field(
         ...,
-        description="Prediction timestamp (ISO format)"
+        description="Heure de la prédiction (ISO format)"
     )
     
-    class Config:
-        schema_extra = {
-            "example": {
-                "is_fraud": False,
-                "fraud_probability": 0.15,
-                "risk_level": "LOW",
-                "confidence": 0.85,
-                "timestamp": "2026-01-24T15:30:45.123456"
-            }
-        }
-
-
-class BatchPredictionOutput(BaseModel):
-    """
-    Output schema for batch predictions
-    """
-    predictions: List[PredictionOutput]
-    total_transactions: int
-    fraud_count: int
-    fraud_rate: float
-    processing_time_ms: float
-
+    processing_time_ms: float = Field(
+        ...,
+        description="Temps de traitement en millisecondes"
+    )
 
-class HealthResponse(BaseModel):
-    """
-    Health check response
-    """
-    status: str
-    model_loaded: bool
-    model_repo: str
-    model_type: Optional[str]
-    timestamp: str
 
+# =====================================================================
+# FONCTIONS HELPER
+# =====================================================================
 
-class ModelInfoResponse(BaseModel):
+def load_models_from_hf():
     """
-    Model information response
+    Télécharge et charge les modèles depuis HuggingFace Hub
+    
+    Cette fonction:
+    1. Télécharge fraud_model.pkl (le modèle ML)
+    2. Télécharge preprocessor.plk (le preprocessor)
+    3. Charge les 2 fichiers en mémoire
+    4. Met à jour les variables globales model et preprocessor
+    
+    Returns:
+        tuple: (success: bool, message: str)
+            success = True si tout s'est bien passé
+            message = Message d'information ou d'erreur
     """
-    model_repo: str
-    model_filename: str
-    model_type: str
-    feature_names: List[str]
-    n_features: int
-    model_version: Optional[str]
-
-
-# ==========================================
-# Helper Functions
-# ==========================================
-
-def load_model_from_hf():
-    """Load model from HuggingFace Hub"""
-    global model
+    global model, preprocessor
     
     try:
+        print("=" * 70)
+        print("📥 Téléchargement des modèles depuis HuggingFace...")
+        print(f"   Repository: {REPO_ID}")
+        print("=" * 70)
+        
+        # ========================================
+        # 1. TÉLÉCHARGER LE MODÈLE ML
+        # ========================================
+        
+        print(f"\n⬇️ Download: {MODEL_FILENAME}...")
         model_path = hf_hub_download(
             repo_id=REPO_ID,
             filename=MODEL_FILENAME,
-            revision=MODEL_VERSION
+            revision=MODEL_VERSION,  # None = latest
+            cache_dir="/tmp"         # Dossier de cache
         )
+        print(f"✅ Téléchargé: {model_path}")
+        
+        # Charger le modèle
         model = joblib.load(model_path)
-        return True
+        print(f"✅ Modèle chargé: {type(model).__name__}")
+        
+        # ========================================
+        # 2. TÉLÉCHARGER LE PREPROCESSOR
+        # ========================================
+        
+        print(f"\n⬇️ Download: {PREPROCESSOR_FILENAME}...")
+        preprocessor_path = hf_hub_download(
+            repo_id=REPO_ID,
+            filename=PREPROCESSOR_FILENAME,
+            revision=MODEL_VERSION,
+            cache_dir="/tmp"
+        )
+        print(f"✅ Téléchargé: {preprocessor_path}")
+        
+        # Charger le preprocessor
+        preprocessor = joblib.load(preprocessor_path)
+        print(f"✅ Preprocessor chargé: {type(preprocessor).__name__}")
+        
+        print("\n" + "=" * 70)
+        print("✅ TOUS LES MODÈLES SONT CHARGÉS ET PRÊTS")
+        print("=" * 70)
+        
+        return True, "Models loaded successfully"
         
     except Exception as e:
-        return False
+        error_msg = f"Erreur lors du chargement des modèles: {str(e)}"
+        print(f"\n❌ {error_msg}")
+        return False, error_msg
 
 
 def calculate_risk_level(probability: float) -> str:
-    """Calculate risk level based on fraud probability"""
+    """
+    Calcule le niveau de risque basé sur la probabilité de fraude
+    
+    Args:
+        probability (float): Probabilité de fraude (0.0 à 1.0)
+    
+    Returns:
+        str: Niveau de risque (LOW, MEDIUM, HIGH, CRITICAL)
+    
+    Seuils:
+        < 0.3  : LOW       (Risque faible)
+        < 0.6  : MEDIUM    (Risque moyen)
+        < 0.8  : HIGH      (Risque élevé)
+        >= 0.8 : CRITICAL  (Risque critique)
+    """
     if probability < 0.3:
         return "LOW"
     elif probability < 0.6:
@@ -270,279 +520,633 @@ def calculate_risk_level(probability: float) -> str:
         return "CRITICAL"
 
 
-def predict_transaction(data: dict) -> dict:
-    """Make prediction for a single transaction"""
-    
-    # Convert to DataFrame
-    df = pd.DataFrame([data])
+# =====================================================================
+# ÉVÉNEMENT DE DÉMARRAGE
+# =====================================================================
+
+@app.on_event("startup")
+async def startup_event():
+    """
+    Fonction appelée AU DÉMARRAGE de l'API
     
-    # Predict
-    prediction = model.predict(df)[0]
-    proba = model.predict_proba(df)[0]
+    Cette fonction:
+    - Est exécutée UNE SEULE FOIS quand l'API démarre
+    - Télécharge et charge les modèles en mémoire
+    - Les modèles restent en mémoire pour toutes les requêtes
     
-    # Get fraud probability
-    fraud_prob = float(proba[1])
+    Si les modèles ne se chargent pas, l'API démarre quand même
+    mais les endpoints de prédiction renverront une erreur 503.
+    """
+    print("\n" + "🚀" * 35)
+    print("🚀 DÉMARRAGE DE L'API FRAUD DETECTION")
+    print("🚀" * 35)
     
-    # Calculate confidence (distance from 0.5 threshold)
-    confidence = abs(fraud_prob - 0.5) * 2
+    # Charger les modèles
+    success, message = load_models_from_hf()
     
-    return {
-        "is_fraud": bool(prediction),
-        "fraud_probability": round(fraud_prob, 4),
-        "risk_level": calculate_risk_level(fraud_prob),
-        "confidence": round(confidence, 4),
-        "timestamp": datetime.utcnow().isoformat()
-    }
-
-
-# ==========================================
-# Startup Event
-# ==========================================
-
-@app.on_event("startup")
-async def startup_event():
-    """Load model on startup"""    
-    success = load_model_from_hf()
+    if success:
+        print("\n✅ API prête à recevoir des requêtes!\n")
+    else:
+        print(f"\n⚠️ API démarrée mais modèles non chargés: {message}")
+        print("⚠️ Les endpoints de prédiction ne fonctionneront pas.\n")
 
 
-# ==========================================
-# Endpoints
-# ==========================================
+# =====================================================================
+# ENDPOINTS - INFORMATION
+# =====================================================================
 
 @app.get(
     "/",
-    summary="Root endpoint",
-    description="Welcome message with API information"
+    tags=["📊 Information"],
+    summary="Page d'accueil",
+    description="Informations générales sur l'API"
 )
 async def root():
-    """Root endpoint"""
+    """
+    Endpoint racine - Informations sur l'API
+    
+    Retourne:
+    - Nom de l'API
+    - Version
+    - Liens vers la documentation
+    - Liste des endpoints disponibles
+    """
     return {
-        "message": "🚨 Fraud Detection API",
-        "version": "1.0.0",
+        "message": "🚨 Fraud Detection API - Level UP",
+        "version": "2.0.0",
         "status": "online",
-        "docs": "/docs",
-        "health": "/health",
+        "documentation": "/docs",
+        "health_check": "/health",
         "endpoints": {
-            "predict": "/predict - Single transaction prediction",
-            "batch": "/predict/batch - Batch predictions",
-            "model_info": "/model/info - Model details"
+            "prediction": {
+                "predict": "/predict - Prédiction complète (feat_eng + preprocess + predict)",
+            },
+            "feature_engineering": {
+                "feat_eng": "/feat_eng - Feature engineering seulement",
+            },
+            "preprocessing": {
+                "preprocess": "/preprocess - Preprocessing seulement",
+            },
+            "information": {
+                "model_info": "/model/info - Informations sur le modèle",
+                "features": "/features - Liste des features nécessaires",
+            }
+        },
+        "example_workflow": {
+            "1": "Données brutes → /feat_eng → Features engineered",
+            "2": "Features engineered → /preprocess → Features preprocessed",
+            "3": "Features preprocessed → /predict → Prédiction",
+            "shortcut": "Données brutes → /predict → Prédiction directe (recommandé)"
         }
     }
 
 
 @app.get(
     "/health",
-    response_model=HealthResponse,
+    tags=["📊 Information"],
     summary="Health check",
-    description="Check API health and model status"
+    description="Vérifier que l'API et les modèles sont opérationnels"
 )
 async def health_check():
     """
-    Health check endpoint
+    Vérifie l'état de santé de l'API
     
-    Returns:
-    - **status**: API status (healthy/unhealthy)
-    - **model_loaded**: Whether ML model is loaded
-    - **model_repo**: HuggingFace repository
-    - **model_type**: Type of ML model
-    - **timestamp**: Current server time
+    Retourne:
+    - Status de l'API (healthy/unhealthy)
+    - État du modèle ML (loaded/not loaded)
+    - État du preprocessor (loaded/not loaded)
+    - Timestamp
     """
+    # Vérifier si les modèles sont chargés
+    models_loaded = (model is not None) and (preprocessor is not None)
+    
     return {
-        "status": "healthy" if model is not None else "unhealthy",
+        "status": "healthy" if models_loaded else "unhealthy",
         "model_loaded": model is not None,
+        "preprocessor_loaded": preprocessor is not None,
         "model_repo": REPO_ID,
         "model_type": type(model).__name__ if model else None,
+        "preprocessor_type": type(preprocessor).__name__ if preprocessor else None,
         "timestamp": datetime.utcnow().isoformat()
     }
 
 
 @app.get(
     "/model/info",
-    response_model=ModelInfoResponse,
-    summary="Model information",
-    description="Get detailed information about the ML model"
+    tags=["📊 Information"],
+    summary="Informations sur le modèle",
+    description="Détails techniques sur le modèle ML et le preprocessor"
 )
 async def model_info():
     """
-    Get model information
+    Informations détaillées sur le modèle ML
     
-    Returns:
-    - **model_repo**: HuggingFace repository
-    - **model_filename**: Model file name
-    - **model_type**: Type of model (e.g., RandomForestClassifier)
-    - **feature_names**: List of required features
-    - **n_features**: Number of features
-    - **model_version**: Model version if specified
+    Retourne:
+    - Type de modèle
+    - Repository HuggingFace
+    - Nombre de features
+    - Liste des features
     """
-    if model is None:
+    # Vérifier que les modèles sont chargés
+    if model is None or preprocessor is None:
         raise HTTPException(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="Model not loaded"
+            detail="Models not loaded. Please check /health endpoint."
         )
     
-    feature_names = ["amt", "lat", "long", "city_pop", "merch_lat", "merch_long"]
+    # Récupérer la liste des features
+    features = get_model_features()
     
     return {
-        "model_repo": REPO_ID,
-        "model_filename": MODEL_FILENAME,
-        "model_type": type(model).__name__,
-        "feature_names": feature_names,
-        "n_features": len(feature_names),
-        "model_version": MODEL_VERSION
+        "model": {
+            "type": type(model).__name__,
+            "repo_id": REPO_ID,
+            "filename": MODEL_FILENAME,
+            "version": MODEL_VERSION or "latest"
+        },
+        "preprocessor": {
+            "type": type(preprocessor).__name__,
+            "filename": PREPROCESSOR_FILENAME
+        },
+        "features": {
+            "total": len(features),
+            "numerical": 17,
+            "categorical": 4,
+            "list": features
+        }
+    }
+
+
+@app.get(
+    "/features",
+    tags=["📊 Information"],
+    summary="Liste des features",
+    description="Liste complète des features nécessaires pour une prédiction"
+)
+async def list_features():
+    """
+    Liste toutes les features attendues par le modèle
+    
+    Retourne:
+    - Features numériques (17)
+    - Features catégorielles (4)
+    - Total (21)
+    """
+    features = get_model_features()
+    
+    numerical = features[:17]  # Premières 17 = numériques
+    categorical = features[17:]  # Dernières 4 = catégorielles
+    
+    return {
+        "total_features": len(features),
+        "numerical_features": {
+            "count": len(numerical),
+            "list": numerical
+        },
+        "categorical_features": {
+            "count": len(categorical),
+            "list": categorical
+        },
+        "all_features_in_order": features
     }
 
 
+# =====================================================================
+# ENDPOINTS - FEATURE ENGINEERING
+# =====================================================================
+
 @app.post(
-    "/predict",
-    response_model=PredictionOutput,
-    summary="Predict single transaction",
-    description="Predict if a single transaction is fraudulent",
-    response_description="Prediction result with fraud probability and risk level"
+    "/feat_eng",
+    response_model=FeaturesEngineeredOutput,
+    tags=["🔧 Feature Engineering"],
+    summary="Feature Engineering",
+    description="Transforme les données brutes en features pour le modèle ML"
 )
-async def predict_single(transaction: TransactionInput):
+async def feature_engineering_endpoint(transaction: TransactionRawInput):
     """
-    Predict if a transaction is fraudulent
-    
-    **Input Features:**
-    - **amt**: Transaction amount in dollars (required, > 0)
-    - **lat**: Customer latitude, range [-90, 90] (required)
-    - **long**: Customer longitude, range [-180, 180] (required)
-    - **city_pop**: Population of customer's city (required, > 0)
-    - **merch_lat**: Merchant latitude, range [-90, 90] (required)
-    - **merch_long**: Merchant longitude, range [-180, 180] (required)
-    
-    **Output:**
-    - **is_fraud**: Boolean indicating if transaction is fraud
-    - **fraud_probability**: Probability score between 0.0 and 1.0
-    - **risk_level**: Risk classification (LOW/MEDIUM/HIGH/CRITICAL)
-    - **confidence**: Model confidence in the prediction
-    - **timestamp**: When the prediction was made
-    
-    **Risk Levels:**
-    - **LOW**: fraud_probability < 0.3
-    - **MEDIUM**: 0.3 ≤ fraud_probability < 0.6
-    - **HIGH**: 0.6 ≤ fraud_probability < 0.8
-    - **CRITICAL**: fraud_probability ≥ 0.8
-    
-    **Example Use Cases:**
-    - Real-time transaction validation at checkout
-    - Post-transaction fraud screening
-    - Risk assessment for high-value transactions
+    Applique le FEATURE ENGINEERING sur une transaction
+    
+    ## Ce que fait cet endpoint:
+    
+    1. **Calcul de distance GPS**
+       - Calcule la distance entre le client et le marchand
+       - Utilise la formule Haversine (précision: ±1%)
+       - Feature créée: `distance_km`
+    
+    2. **Extraction des features temporelles**
+       - Heure de la journée (0-23)
+       - Jour de la semaine (0-6)
+       - Période (nuit, matin, après-midi, soir)
+       - Weekend ou non
+       - Heures de bureau ou non
+       - Features créées: `hour`, `dayofweek`, `is_night`, `is_morning`, 
+         `is_afternoon`, `is_evening`, `is_business_hour`, `is_we`, 
+         `year`, `month`, `day`
+    
+    3. **Calcul de l'âge**
+       - À partir de la date de naissance
+       - Feature créée: `age`
+    
+    ## Input:
+    Données brutes de la transaction (voir schema TransactionRawInput)
+    
+    ## Output:
+    - `original_data`: Données brutes d'entrée
+    - `engineered_features`: Nouvelles features calculées
+    - `all_features`: Toutes les features (original + engineered)
+    
+    ## Exemple d'utilisation:
+    ```python
+    import requests
+    
+    data = {
+        "cc_num": 374125201044065,
+        "amt": 150.75,
+        "lat": 40.7128,
+        "long": -74.0060,
+        # ... autres champs
+    }
+    
+    response = requests.post("http://localhost:8000/feat_eng", json=data)
+    features = response.json()["all_features"]
+    ```
     """
-    if model is None:
+    try:
+        # Convertir en dictionnaire
+        transaction_dict = transaction.dict()
+        
+        print("\n" + "=" * 70)
+        print("🔧 FEATURE ENGINEERING")
+        print("=" * 70)
+        
+        # Appliquer le feature engineering
+        # (voir feature_engineering.py pour les détails)
+        engineered = engineer_features(transaction_dict)
+        
+        # Identifier les features qui ont été ajoutées
+        original_keys = set(transaction_dict.keys())
+        all_keys = set(engineered.keys())
+        new_features = all_keys - original_keys
+        
+        print(f"\n✅ Feature engineering terminé")
+        print(f"   Features ajoutées: {len(new_features)}")
+        print(f"   Total features: {len(engineered)}")
+        
+        # Préparer la réponse
+        return {
+            "original_data": transaction_dict,
+            "engineered_features": {k: engineered[k] for k in new_features},
+            "all_features": engineered
+        }
+        
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Feature engineering failed: {str(e)}"
+        )
+
+
+# =====================================================================
+# ENDPOINTS - PREPROCESSING
+# =====================================================================
+
+@app.post(
+    "/preprocess",
+    response_model=PreprocessedOutput,
+    tags=["⚙️ Preprocessing"],
+    summary="Preprocessing",
+    description="Applique le preprocessing (scaling + encoding) sur les features"
+)
+async def preprocessing_endpoint(features: Dict[str, Any]):
+    """
+    Applique le PREPROCESSING sur les features
+    
+    ## Ce que fait cet endpoint:
+    
+    1. **StandardScaler** (normalisation)
+       - Met les features numériques à l'échelle
+       - Moyenne = 0, Écart-type = 1
+       - Exemple: 100$ → 0.52, 5000$ → 2.31
+    
+    2. **OneHotEncoder** (encoding catégoriel)
+       - Convertit les catégories en colonnes binaires
+       - Exemple: 'NY' → [0, 0, 1, 0, ...] (vecteur de 50 dimensions)
+       - Exemple: 'shopping_net' → [0, 1, 0, ...] (vecteur de 14 dimensions)
+    
+    ## Input:
+    Dictionnaire avec toutes les features (déjà engineered)
+    
+    Les 21 features attendues:
+    - **Numériques** (17): cc_num, amt, zip, city_pop, distance_km, age, 
+      hour, is_night, is_morning, is_afternoon, is_evening, is_business_hour, 
+      year, month, day, dayofweek, is_we
+    - **Catégorielles** (4): merchant, category, gender, state
+    
+    ## Output:
+    - `preprocessed_shape`: Dimensions des données transformées
+    - `sample_values`: Premières valeurs (pour vérification)
+    - `message`: Message de confirmation
+    
+    ## Note:
+    Les données preprocessed ne sont PAS retournées en entier 
+    (trop volumineuses), seulement leur shape et un échantillon.
+    
+    Pour obtenir une prédiction, utilisez directement `/predict`
+    qui fait feat_eng + preprocess + predict.
+    """
+    # Vérifier que le preprocessor est chargé
+    if preprocessor is None:
         raise HTTPException(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="Model not loaded. Please try again later."
+            detail="Preprocessor not loaded"
         )
     
     try:
-        # Convert to dict
-        data = transaction.dict()
+        print("\n" + "=" * 70)
+        print("⚙️ PREPROCESSING")
+        print("=" * 70)
         
-        # Predict
-        result = predict_transaction(data)
+        # Préparer les features pour le modèle
+        # (sélectionne les bonnes colonnes dans le bon ordre)
+        df = prepare_for_model(features)
         
-        return result
+        if df is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Missing required features. Use /features to see the full list."
+            )
+        
+        print(f"\n📊 Features préparées: {df.shape}")
+        
+        # Appliquer le preprocessing
+        # Le preprocessor fait:
+        # 1. StandardScaler sur les numériques
+        # 2. OneHotEncoder sur les catégorielles
+        X_preprocessed = preprocessor.transform(df)
+        
+        print(f"✅ Preprocessing terminé: {X_preprocessed.shape}")
+        print(f"   Input: {df.shape[1]} features")
+        print(f"   Output: {X_preprocessed.shape[1]} features (après encoding)")
+        
+        # Retourner les informations (pas les données complètes, trop volumineux)
+        return {
+            "preprocessed_shape": X_preprocessed.shape,
+            "sample_values": X_preprocessed[0, :10].tolist(),  # 10 premières valeurs
+            "message": f"Preprocessing successful. Shape: {X_preprocessed.shape}"
+        }
         
     except Exception as e:
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Prediction failed: {str(e)}"
+            detail=f"Preprocessing failed: {str(e)}"
         )
 
 
+# =====================================================================
+# ENDPOINTS - PREDICTION
+# =====================================================================
+
 @app.post(
-    "/predict/batch",
-    response_model=BatchPredictionOutput,
-    summary="Predict multiple transactions",
-    description="Predict fraud for multiple transactions in batch",
-    response_description="Batch prediction results with statistics"
+    "/predict",
+    response_model=PredictionOutput,
+    tags=["🎯 Prediction"],
+    summary="Prédiction complète",
+    description="Prédiction de fraude complète (feature engineering + preprocessing + ML)"
 )
-async def predict_batch(batch: BatchTransactionInput):
+async def predict_fraud(transaction: TransactionRawInput):
     """
-    Predict fraud for multiple transactions
-    
-    **Input:**
-    - **transactions**: List of transactions (1-100 transactions per batch)
-    
-    **Output:**
-    - **predictions**: List of individual predictions
-    - **total_transactions**: Total number of transactions processed
-    - **fraud_count**: Number of frauds detected
-    - **fraud_rate**: Percentage of fraudulent transactions
-    - **processing_time_ms**: Time taken to process the batch
-    
-    **Use Cases:**
-    - Batch processing of historical transactions
-    - Daily fraud screening
-    - Report generation
-    - Data analysis and auditing
-    
-    **Performance:**
-    - Processes up to 100 transactions per request
-    - Average processing time: ~10-50ms per transaction
-    - Results cached for repeated requests
+    Prédiction COMPLÈTE de fraude
+    
+    ## Workflow:
+    
+    ```
+    Données Brutes (TransactionRawInput)
+        ↓
+    1. Feature Engineering
+        - Calcul distance GPS
+        - Extraction features temporelles
+        - Calcul âge
+        ↓
+    2. Preprocessing
+        - StandardScaler (normalisation)
+        - OneHotEncoder (encoding)
+        ↓
+    3. Prédiction ML
+        - RandomForestClassifier
+        - Probabilité de fraude
+        ↓
+    Résultat (PredictionOutput)
+    ```
+    
+    ## Input:
+    Données brutes de la transaction (voir TransactionRawInput schema)
+    
+    ## Output:
+    - **is_fraud**: True/False - Transaction frauduleuse ou non
+    - **fraud_probability**: 0.0 à 1.0 - Probabilité de fraude
+    - **risk_level**: LOW/MEDIUM/HIGH/CRITICAL - Niveau de risque
+    - **confidence**: 0.0 à 1.0 - Confiance du modèle
+    - **timestamp**: Heure de la prédiction
+    - **processing_time_ms**: Temps de traitement en millisecondes
+    
+    ## Niveaux de Risque:
+    - **LOW**: fraud_probability < 0.3 → Transaction probablement légitime
+    - **MEDIUM**: 0.3 ≤ fraud_probability < 0.6 → Vérification recommandée
+    - **HIGH**: 0.6 ≤ fraud_probability < 0.8 → Transaction suspecte
+    - **CRITICAL**: fraud_probability ≥ 0.8 → Bloquer la transaction
+    
+    ## Exemple de Code:
+    
+    ```python
+    import requests
+    
+    # Données de transaction
+    transaction = {
+        "cc_num": 374125201044065,
+        "amt": 150.75,
+        "lat": 40.7128,
+        "long": -74.0060,
+        "city_pop": 8000000,
+        "zip": 10001,
+        "merch_lat": 40.7589,
+        "merch_long": -73.9851,
+        "merchant": "Amazon",
+        "category": "shopping_net",
+        "gender": "M",
+        "state": "NY",
+        "dob": "1990-01-15",
+        "transaction_time": "2026-01-29 14:30:00"
+    }
+    
+    # Faire la prédiction
+    response = requests.post(
+        "http://localhost:8000/predict",
+        json=transaction
+    )
+    
+    result = response.json()
+    
+    if result["is_fraud"]:
+        print(f"⚠️ FRAUDE détectée! Probabilité: {result['fraud_probability']:.1%}")
+        print(f"   Niveau de risque: {result['risk_level']}")
+    else:
+        print(f"✅ Transaction légitime. Probabilité de fraude: {result['fraud_probability']:.1%}")
+    ```
+    
+    ## Performance:
+    - Temps de traitement moyen: 10-50ms
+    - Throughput: ~100-500 requêtes/seconde (selon hardware)
+    
+    ## Use Cases:
+    1. **Validation temps réel**: Au moment du paiement
+    2. **Post-transaction**: Vérification après coup
+    3. **Batch processing**: Analyse de milliers de transactions
+    4. **Monitoring**: Détection de patterns de fraude
     """
-    if model is None:
+    # Vérifier que les modèles sont chargés
+    if model is None or preprocessor is None:
         raise HTTPException(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="Model not loaded"
+            detail="Models not loaded. Please check /health endpoint."
         )
     
     try:
-        start_time = datetime.utcnow()
+        # Timer pour mesurer le temps de traitement
+        start_time = time.time()
         
-        # Predict all transactions
-        predictions = []
-        for transaction in batch.transactions:
-            data = transaction.dict()
-            result = predict_transaction(data)
-            predictions.append(result)
+        print("\n" + "🎯" * 35)
+        print("🎯 PRÉDICTION DE FRAUDE - WORKFLOW COMPLET")
+        print("🎯" * 35)
         
-        # Calculate statistics
-        fraud_count = sum(1 for p in predictions if p["is_fraud"])
-        total = len(predictions)
-        fraud_rate = (fraud_count / total) * 100 if total > 0 else 0.0
+        # ========================================
+        # ÉTAPE 1: FEATURE ENGINEERING
+        # ========================================
         
-        # Calculate processing time
-        end_time = datetime.utcnow()
-        processing_time_ms = (end_time - start_time).total_seconds() * 1000
+        print("\n[1/3] 🔧 Feature Engineering...")
+        transaction_dict = transaction.dict()
+        engineered = engineer_features(transaction_dict)
         
-        return {
-            "predictions": predictions,
-            "total_transactions": total,
-            "fraud_count": fraud_count,
-            "fraud_rate": round(fraud_rate, 2),
-            "processing_time_ms": round(processing_time_ms, 2)
+        # ========================================
+        # ÉTAPE 2: PREPROCESSING
+        # ========================================
+        
+        print("\n[2/3] ⚙️ Preprocessing...")
+        df = prepare_for_model(engineered)
+        
+        if df is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Failed to prepare features for model"
+            )
+        
+        # Appliquer le preprocessing
+        X_preprocessed = preprocessor.transform(df)
+        print(f"      Shape après preprocessing: {X_preprocessed.shape}")
+        
+        # ========================================
+        # ÉTAPE 3: PRÉDICTION ML
+        # ========================================
+        
+        print("\n[3/3] 🤖 Prédiction ML...")
+        
+        # Faire la prédiction
+        prediction = model.predict(X_preprocessed)[0]  # 0 ou 1
+        proba = model.predict_proba(X_preprocessed)[0]  # [proba_class_0, proba_class_1]
+        
+        # Extraire la probabilité de fraude (classe 1)
+        fraud_prob = float(proba[1])
+        
+        # Calculer la confiance
+        # Confiance = distance par rapport à 0.5 (seuil de décision)
+        # Plus on est loin de 0.5, plus on est confiant
+        confidence = abs(fraud_prob - 0.5) * 2
+        
+        # Calculer le niveau de risque
+        risk = calculate_risk_level(fraud_prob)
+        
+        # Temps de traitement
+        processing_time = (time.time() - start_time) * 1000  # En millisecondes
+        
+        # Résultat
+        result = {
+            "is_fraud": bool(prediction),
+            "fraud_probability": round(fraud_prob, 4),
+            "risk_level": risk,
+            "confidence": round(confidence, 4),
+            "timestamp": datetime.utcnow().isoformat(),
+            "processing_time_ms": round(processing_time, 2)
         }
         
+        print("\n" + "=" * 70)
+        print(f"✅ RÉSULTAT:")
+        print(f"   Fraude: {result['is_fraud']}")
+        print(f"   Probabilité: {result['fraud_probability']:.1%}")
+        print(f"   Risque: {result['risk_level']}")
+        print(f"   Temps: {result['processing_time_ms']:.2f}ms")
+        print("=" * 70)
+        
+        return result
+        
     except Exception as e:
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Batch prediction failed: {str(e)}"
+            detail=f"Prediction failed: {str(e)}"
         )
 
 
-# ==========================================
-# Error Handlers
-# ==========================================
+# =====================================================================
+# ERROR HANDLERS (Gestion des erreurs)
+# =====================================================================
 
 @app.exception_handler(ValueError)
 async def value_error_handler(request, exc):
+    """Gère les erreurs de validation de données"""
     return JSONResponse(
         status_code=status.HTTP_400_BAD_REQUEST,
-        content={"error": "Invalid input", "detail": str(exc)}
+        content={
+            "error": "Invalid input",
+            "detail": str(exc),
+            "type": "ValueError"
+        }
     )
 
 
 @app.exception_handler(Exception)
 async def general_exception_handler(request, exc):
+    """Gère toutes les autres erreurs inattendues"""
     return JSONResponse(
         status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-        content={"error": "Internal server error", "detail": "An unexpected error occurred"}
+        content={
+            "error": "Internal server error",
+            "detail": "An unexpected error occurred",
+            "type": type(exc).__name__
+        }
     )
 
 
-# ==========================================
-# Run with: uvicorn app:app --reload --host 0.0.0.0 --port 8000
-# ==========================================
+# =====================================================================
+# POINT D'ENTRÉE
+# =====================================================================
+
+if __name__ == "__main__":
+    """
+    Lancer l'API en mode développement
+    
+    Commande:
+        python app.py
+    
+    Ou avec uvicorn:
+        uvicorn app:app --reload --host 0.0.0.0 --port 8000
+    
+    Documentation:
+        http://localhost:8000/docs
+    """
+    import uvicorn
+    
+    uvicorn.run(
+        "app:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,  # Auto-reload en mode dev
+        log_level="info"
+    )

feature_engineering.py

@@ -0,0 +1,486 @@
+"""
+Feature Engineering Module
+--------------------------
+Toutes les transformations de features pour la détection de fraude
+
+Ce module contient les fonctions pour :
+1. Calculer la distance GPS entre client et marchand
+2. Extraire les features temporelles (heure, jour, weekend, etc.)
+3. Calculer l'âge du porteur de carte
+4. Créer toutes les features nécessaires pour le modèle ML
+
+Author: Terorra
+Date: January 2026
+"""
+
+from datetime import datetime, date
+from math import radians, sin, cos, sqrt, atan2
+import pandas as pd
+
+
+# =====================================================================
+# FONCTION 1 : CALCUL DE DISTANCE GPS
+# =====================================================================
+
+def haversine_distance(lat1, lon1, lat2, lon2):
+    """
+    Calcule la distance entre 2 points GPS avec la formule Haversine
+    
+    La formule Haversine permet de calculer la distance entre deux points
+    sur une sphère (la Terre) à partir de leurs coordonnées GPS.
+    
+    Args:
+        lat1 (float): Latitude du point 1 (client)
+        lon1 (float): Longitude du point 1 (client)
+        lat2 (float): Latitude du point 2 (marchand)
+        lon2 (float): Longitude du point 2 (marchand)
+    
+    Returns:
+        float: Distance en kilomètres (arrondie à 2 décimales)
+        None: Si une coordonnée est manquante
+    
+    Example:
+        >>> haversine_distance(48.8566, 2.3522, 51.5074, -0.1278)
+        344.45  # Distance Paris-Londres en km
+    """
+    # Vérifier si des valeurs sont manquantes
+    if any(pd.isna([lat1, lon1, lat2, lon2])):
+        return None
+    
+    try:
+        # Rayon de la Terre en kilomètres
+        R = 6371
+        
+        # Convertir les degrés en radians (nécessaire pour les calculs trigonométriques)
+        lat1, lon1, lat2, lon2 = map(radians, [lat1, lon1, lat2, lon2])
+        
+        # Différences de latitude et longitude
+        dlat = lat2 - lat1
+        dlon = lon2 - lon1
+        
+        # Formule Haversine
+        # a = sin²(Δlat/2) + cos(lat1) * cos(lat2) * sin²(Δlon/2)
+        a = sin(dlat/2)**2 + cos(lat1) * cos(lat2) * sin(dlon/2)**2
+        
+        # c = 2 * atan2(√a, √(1-a))
+        c = 2 * atan2(sqrt(a), sqrt(1-a))
+        
+        # Distance = R * c
+        distance = R * c
+        
+        # Arrondir à 2 décimales
+        return round(distance, 2)
+        
+    except Exception as e:
+        print(f"⚠️ Erreur calcul distance: {e}")
+        return None
+
+
+# =====================================================================
+# FONCTION 2 : CALCUL DE L'ÂGE
+# =====================================================================
+
+def calculate_age(born):
+    """
+    Calcule l'âge à partir de la date de naissance
+    
+    Cette fonction calcule l'âge en années complètes, en tenant compte
+    du fait que l'anniversaire peut ne pas encore être passé cette année.
+    
+    Args:
+        born (str): Date de naissance au format 'YYYY-MM-DD'
+    
+    Returns:
+        int: Âge en années
+        None: Si la date est invalide ou manquante
+    
+    Example:
+        >>> calculate_age('1990-01-15')
+        36  # Si on est en 2026
+    """
+    # Vérifier si la valeur est manquante
+    if pd.isna(born) or born is None or born == '':
+        return None
+    
+    try:
+        # Convertir la string en date
+        born_date = datetime.strptime(str(born), '%Y-%m-%d').date()
+        
+        # Date du jour
+        today = date.today()
+        
+        # Calcul de l'âge
+        # On soustrait 1 si l'anniversaire n'est pas encore passé cette année
+        age = today.year - born_date.year - (
+            (today.month, today.day) < (born_date.month, born_date.day)
+        )
+        
+        return age
+        
+    except Exception as e:
+        print(f"⚠️ Erreur calcul âge pour {born}: {e}")
+        return None
+
+
+# =====================================================================
+# FONCTION 3 : FEATURES TEMPORELLES
+# =====================================================================
+
+def extract_time_features(transaction_time):
+    """
+    Extrait toutes les features temporelles d'une transaction
+    
+    À partir de l'heure de transaction, cette fonction crée :
+    - L'heure (0-23)
+    - Le jour de la semaine (0=lundi, 6=dimanche)
+    - Si c'est le weekend (samedi ou dimanche)
+    - Si c'est la nuit (22h-6h)
+    - Si c'est le matin (6h-12h)
+    - Si c'est l'après-midi (12h-18h)
+    - Si c'est le soir (18h-22h)
+    - Si c'est pendant les heures de bureau (8h-17h)
+    - L'année, le mois, le jour
+    
+    Args:
+        transaction_time (str or datetime): Heure de la transaction
+    
+    Returns:
+        dict: Dictionnaire avec toutes les features temporelles
+        None: Si la date est invalide
+    
+    Example:
+        >>> extract_time_features('2026-01-29 14:30:00')
+        {
+            'hour': 14,
+            'day_of_week': 2,  # Mercredi
+            'is_weekend': 0,
+            'is_night': 0,
+            'is_morning': 0,
+            'is_afternoon': 1,
+            'is_evening': 0,
+            'is_business_hour': 1,
+            'year': 2026,
+            'month': 1,
+            'day': 29
+        }
+    """
+    # Vérifier si la valeur est manquante
+    if pd.isna(transaction_time) or transaction_time is None:
+        return None
+    
+    try:
+        # Convertir en datetime si nécessaire
+        if isinstance(transaction_time, str):
+            dt = pd.to_datetime(transaction_time)
+        else:
+            dt = transaction_time
+        
+        # Extraire l'heure (0-23)
+        hour = dt.hour
+        
+        # Extraire le jour de la semaine (0=lundi, 6=dimanche)
+        day_of_week = dt.dayofweek
+        
+        # Créer le dictionnaire de features
+        features = {
+            # Heure brute
+            'hour': hour,
+            'day_of_week': day_of_week,
+            
+            # Périodes de la journée (binaire : 0 ou 1)
+            'is_night': 1 if 22 <= hour or hour < 6 else 0,        # 22h-6h
+            'is_morning': 1 if 6 <= hour < 12 else 0,              # 6h-12h
+            'is_afternoon': 1 if 12 <= hour < 18 else 0,           # 12h-18h
+            'is_evening': 1 if 18 <= hour < 22 else 0,             # 18h-22h
+            'is_business_hour': 1 if 8 <= hour < 17 else 0,        # 8h-17h
+            
+            # Weekend (samedi=5, dimanche=6)
+            'is_we': 1 if day_of_week in [5, 6] else 0,
+            
+            # Composantes de la date
+            'year': dt.year,
+            'month': dt.month,
+            'day': dt.day
+        }
+        
+        return features
+        
+    except Exception as e:
+        print(f"⚠️ Erreur extraction features temps pour {transaction_time}: {e}")
+        return None
+
+
+# =====================================================================
+# FONCTION 4 : FEATURE ENGINEERING COMPLET
+# =====================================================================
+
+def engineer_features(transaction_data):
+    """
+    Applique TOUTES les transformations de features sur une transaction
+    
+    Cette fonction est la fonction PRINCIPALE qui :
+    1. Prend les données brutes d'une transaction
+    2. Calcule la distance GPS client-marchand
+    3. Extrait les features temporelles
+    4. Calcule l'âge si la date de naissance est fournie
+    5. Retourne un dictionnaire avec TOUTES les features
+    
+    Args:
+        transaction_data (dict): Dictionnaire avec les données brutes
+            Clés requises:
+            - lat, long: Coordonnées client
+            - merch_lat, merch_long: Coordonnées marchand
+            - transaction_time: Heure de transaction
+            Clés optionnelles:
+            - dob: Date de naissance (pour calculer l'âge)
+            - amt, cc_num, etc.: Autres features
+    
+    Returns:
+        dict: Dictionnaire avec toutes les features (brutes + engineered)
+    
+    Example:
+        >>> data = {
+        ...     'amt': 150.75,
+        ...     'lat': 40.7128,
+        ...     'long': -74.0060,
+        ...     'merch_lat': 40.7589,
+        ...     'merch_long': -73.9851,
+        ...     'transaction_time': '2026-01-29 14:30:00',
+        ...     'city_pop': 8000000,
+        ...     'dob': '1990-01-15'
+        ... }
+        >>> result = engineer_features(data)
+        >>> print(result['distance_km'])
+        5.87  # Distance en km
+        >>> print(result['hour'])
+        14
+        >>> print(result['age'])
+        36
+    """
+    # Copier les données pour ne pas modifier l'original
+    features = transaction_data.copy()
+    
+    # ========================================
+    # 1. CALCUL DE LA DISTANCE GPS
+    # ========================================
+    
+    # Vérifier que les coordonnées sont présentes
+    if all(key in features for key in ['lat', 'long', 'merch_lat', 'merch_long']):
+        distance = haversine_distance(
+            features['lat'],
+            features['long'],
+            features['merch_lat'],
+            features['merch_long']
+        )
+        features['distance_km'] = distance
+        print(f"  ✅ Distance calculée: {distance} km")
+    else:
+        features['distance_km'] = None
+        print(f"  ⚠️ Coordonnées GPS manquantes, distance non calculée")
+    
+    # ========================================
+    # 2. EXTRACTION DES FEATURES TEMPORELLES
+    # ========================================
+    
+    # Vérifier que l'heure de transaction est présente
+    if 'transaction_time' in features:
+        time_features = extract_time_features(features['transaction_time'])
+        
+        if time_features:
+            # Ajouter toutes les features temporelles au dictionnaire
+            features.update(time_features)
+            print(f"  ✅ Features temporelles extraites (heure: {time_features['hour']})")
+        else:
+            print(f"  ⚠️ Impossible d'extraire les features temporelles")
+    else:
+        print(f"  ⚠️ Heure de transaction manquante")
+    
+    # ========================================
+    # 3. CALCUL DE L'ÂGE (si date de naissance fournie)
+    # ========================================
+    
+    if 'dob' in features:
+        age = calculate_age(features['dob'])
+        features['age'] = age
+        if age:
+            print(f"  ✅ Âge calculé: {age} ans")
+        else:
+            print(f"  ⚠️ Impossible de calculer l'âge")
+    else:
+        features['age'] = None
+        print(f"  ⚠️ Date de naissance non fournie")
+    
+    # ========================================
+    # RETOUR
+    # ========================================
+    
+    return features
+
+
+# =====================================================================
+# FONCTION 5 : LISTE DES FEATURES POUR LE MODÈLE
+# =====================================================================
+
+def get_model_features():
+    """
+    Retourne la liste EXACTE des features attendues par le modèle ML
+    
+    Cette fonction définit l'ordre EXACT des colonnes que le modèle attend.
+    IMPORTANT: L'ordre DOIT être le même que lors de l'entraînement !
+    
+    Returns:
+        list: Liste des noms de features dans le bon ordre
+    
+    Categories:
+        - Numerical: 17 features numériques
+        - Categorical: 4 features catégorielles
+    """
+    # Features NUMÉRIQUES (17 features)
+    numerical_features = [
+        'cc_num',           # Numéro de carte (hashé)
+        'amt',              # Montant de la transaction
+        'zip',              # Code postal
+        'city_pop',         # Population de la ville
+        'distance_km',      # Distance client-marchand (ENGINEERED)
+        'age',              # Âge du porteur (ENGINEERED)
+        'hour',             # Heure 0-23 (ENGINEERED)
+        'is_night',         # 1 si nuit (ENGINEERED)
+        'is_morning',       # 1 si matin (ENGINEERED)
+        'is_afternoon',     # 1 si après-midi (ENGINEERED)
+        'is_evening',       # 1 si soir (ENGINEERED)
+        'is_business_hour', # 1 si heures de bureau (ENGINEERED)
+        'year',             # Année (ENGINEERED)
+        'month',            # Mois (ENGINEERED)
+        'day',              # Jour (ENGINEERED)
+        'dayofweek',        # Jour de la semaine (ENGINEERED) - Renommé de 'day_of_week'
+        'is_we'             # 1 si weekend (ENGINEERED)
+    ]
+    
+    # Features CATÉGORIELLES (4 features)
+    categorical_features = [
+        'merchant',         # Nom du marchand
+        'category',         # Catégorie de la transaction
+        'gender',           # Genre du client
+        'state'             # État (US)
+    ]
+    
+    # TOUTES les features dans l'ORDRE
+    all_features = numerical_features + categorical_features
+    
+    return all_features
+
+
+def prepare_for_model(features_dict):
+    """
+    Prépare les features dans le bon format pour le modèle
+    
+    Cette fonction :
+    1. Prend le dictionnaire de features
+    2. Sélectionne UNIQUEMENT les features nécessaires
+    3. Les arrange dans le BON ORDRE
+    4. Convertit en DataFrame
+    5. Renomme 'day_of_week' en 'dayofweek' (compatibilité modèle)
+    
+    Args:
+        features_dict (dict): Dictionnaire avec toutes les features
+    
+    Returns:
+        pd.DataFrame: DataFrame avec les features dans le bon ordre
+        None: Si des features manquent
+    
+    Example:
+        >>> features = engineer_features(transaction_data)
+        >>> df_ready = prepare_for_model(features)
+        >>> # df_ready est prêt pour model.predict()
+    """
+    # Renommer 'day_of_week' en 'dayofweek' si présent
+    # (Le modèle a été entraîné avec 'dayofweek')
+    if 'day_of_week' in features_dict and 'dayofweek' not in features_dict:
+        features_dict['dayofweek'] = features_dict['day_of_week']
+    
+    # Obtenir la liste des features attendues
+    expected_features = get_model_features()
+    
+    # Vérifier que toutes les features sont présentes
+    missing_features = [f for f in expected_features if f not in features_dict]
+    
+    if missing_features:
+        print(f"❌ Features manquantes: {missing_features}")
+        return None
+    
+    # Sélectionner uniquement les features nécessaires DANS LE BON ORDRE
+    selected_data = {feature: features_dict[feature] for feature in expected_features}
+    
+    # Convertir en DataFrame (le modèle attend un DataFrame)
+    df = pd.DataFrame([selected_data])
+    
+    print(f"✅ Features préparées: {df.shape[1]} colonnes")
+    
+    return df
+
+
+# =====================================================================
+# MÉTADONNÉES DU MODULE
+# =====================================================================
+
+__version__ = "1.0.0"
+__author__ = "Terorra"
+
+# Liste des fonctions exportées
+__all__ = [
+    'haversine_distance',
+    'calculate_age',
+    'extract_time_features',
+    'engineer_features',
+    'get_model_features',
+    'prepare_for_model'
+]
+
+
+# =====================================================================
+# TEST DU MODULE (si exécuté directement)
+# =====================================================================
+
+if __name__ == "__main__":
+    print("=" * 70)
+    print("🧪 Test du module Feature Engineering")
+    print("=" * 70)
+    
+    # Données de test
+    test_transaction = {
+        'cc_num': 374125201044065,
+        'amt': 150.75,
+        'lat': 40.7128,
+        'long': -74.0060,
+        'city_pop': 8000000,
+        'merch_lat': 40.7589,
+        'merch_long': -73.9851,
+        'transaction_time': '2026-01-29 14:30:00',
+        'dob': '1990-01-15',
+        'merchant': 'Amazon',
+        'category': 'shopping_net',
+        'gender': 'M',
+        'state': 'NY',
+        'zip': 10001
+    }
+    
+    print("\n📊 Données de test:")
+    for key, value in test_transaction.items():
+        print(f"  {key}: {value}")
+    
+    print("\n🔧 Application du feature engineering...")
+    engineered = engineer_features(test_transaction)
+    
+    print("\n📊 Features créées:")
+    for key in ['distance_km', 'hour', 'is_afternoon', 'age']:
+        if key in engineered:
+            print(f"  {key}: {engineered[key]}")
+    
+    print("\n📦 Préparation pour le modèle...")
+    df_ready = prepare_for_model(engineered)
+    
+    if df_ready is not None:
+        print(f"✅ Prêt pour prédiction: {df_ready.shape}")
+        print(f"   Colonnes: {list(df_ready.columns)}")
+    
+    print("\n" + "=" * 70)

requirements.txt

@@ -1,9 +1,57 @@
-fastapi[standard]
-pandas
-joblib
-uvicorn
-gunicorn
-pydantic
-scikit-learn
-huggingface_hub 
-typing
+# =====================================================================
+# Requirements pour l'API Fraud Detection - Level UP
+# =====================================================================
+# 
+# Installation:
+#   pip install -r requirements.txt
+#
+# Author: Terorra
+# Date: January 2026
+# =====================================================================
+
+# =====================================================================
+# FASTAPI ET SERVEUR WEB
+# =====================================================================
+fastapi[standard]
+gunicorn
+pydantic
+
+# =====================================================================
+# MACHINE LEARNING
+# =====================================================================
+scikit-learn
+joblib
+
+# =====================================================================
+# DATA PROCESSING
+# =====================================================================
+pandas
+numpy
+maths
+
+# test geopy
+geopy
+
+# =====================================================================
+# HUGGINGFACE
+# =====================================================================
+huggingface-hub
+
+# =====================================================================
+# UTILITAIRES
+# =====================================================================
+python-dotenv
+requests
+
+# =====================================================================
+# DÉVELOPPEMENT (optionnel)
+# =====================================================================
+
+# Pytest - Pour les tests unitaires (optionnel)
+# pytest==7.4.3
+
+# Black - Formatage de code (optionnel)
+# black==23.12.1
+
+# Flake8 - Linting (optionnel)
+# flake8==7.0.0