model/README.md

# 🤖 Modèle de Machine Learning - Project5

Ce dossier contient le modèle de Machine Learning pour la prédiction de consommation énergétique des bâtiments.

## 📁 Structure des fichiers

```
model/
├── model.py                    # Script de génération du modèle
├── model.pkl                   # Modèle RandomForest sérialisé (26MB)
├── model_info.json            # Métadonnées et métriques du modèle
├── generate_model_report.py    # Générateur de rapport HTML
├── Makefile                   # Automatisation des tâches
├── backup/                    # Sauvegardes des modèles
└── README.md                  # Cette documentation
```

## 🎯 Modèle actuel

### Informations générales
- **Type** : RandomForestRegressor
- **Version** : 1.0
- **Créé le** : 2025-09-21T11:07:42
- **Taille** : 26.0 MB
- **Variables** : 17 features

### Métriques de performance
```json
{
  "accuracy": 0.916,
  "RMSE": 0.09,
  "MAE": 0.22,
  "R²": 0.92
}
```

### Variables d'entrée (17 features)
```
year_built
number_of_buildings
number_of_floors
property_gfa_total
property_gfa_parking
second_largest_property_use_type_gfa
third_largest_property_use_type_gfa
multiusage
steam
electricity
natural_gas
neighborhood_id
building_type_id
largest_property_use_type_id
primary_property_type_id
second_largest_property_use_type_id
third_largest_property_use_type_id
```

## 🚀 Utilisation rapide

### Génération du modèle
```bash
# Installation et génération complète
make setup

# Génération simple
make train

# Force la régénération
make retrain
```

### Validation et tests
```bash
# Valider l'intégrité du modèle
make validate

# Tester le chargement
make test

# Tester une prédiction
make test-prediction
```

### Rapport et informations
```bash
# Générer un rapport HTML complet
make report

# Informations rapides
make info

# Taille des fichiers
make model-size
```

## 📊 Commandes disponibles

### **Génération du modèle**
- `make model` / `make train` - Génère le modèle via model.py
- `make retrain` - Force la régénération (supprime + recrée)
- `make setup` - Workflow complet (dépendances + DB + génération)

### **Validation et tests**
- `make validate` - Vérifie l'existence et l'intégrité des fichiers
- `make test` - Test de chargement et validation du modèle
- `make test-prediction` - Test d'une prédiction avec données aléatoires

### **Gestion et maintenance**
- `make info` - Affiche les informations détaillées (JSON)
- `make model-size` - Affiche la taille des fichiers
- `make backup` - Sauvegarde avec timestamp
- `make restore` - Restaure la dernière sauvegarde
- `make list-backups` - Liste toutes les sauvegardes
- `make clean` / `make clean-all` - Nettoyage

### **Environnement**
- `make check-deps` - Vérifie les dépendances Python
- `make check-db` - Teste la connexion à la base de données


## 🔧 Configuration technique

### Prérequis
```python
# Dépendances principales
import sklearn
import pandas
import numpy
import joblib
```

### Variables d'environnement
```bash
DATABASE_URL=postgresql://user:password@localhost/dbname
```

### Source des données
Le modèle est entraîné sur la vue `model_view` de la base de données PostgreSQL qui agrège :
- Données Seattle (2016_Building_Energy_Benchmarking.csv)
- Données OSE (building_consumption_OSEBuildingID.csv)

## 🛠️ Développement

### Regeneration du modèle
1. Modifier les hyperparamètres dans `model.py`
2. Exécuter `make train`
3. Valider avec `make test`
4. Générer le rapport avec `make report`

### Sauvegarde et versioning
```bash
# Sauvegarde manuelle
make backup

# Lister les versions
make list-backups

# Restaurer une version précédente
make restore
```

### Structure du modèle
```python
# Configuration RandomForest
RandomForestRegressor(
    n_estimators=500,
    max_features=0.5,
    random_state=42,
    min_samples_split=5,
    max_depth=20
)
```

## 📊 Pipeline de données

1. **Source** : Vue `model_view` (PostgreSQL)
2. **Transformation** : Log de la variable cible `site_energy_use_wn_kbtu`
3. **Split** : 80/20 train/test (random_state=42)
4. **Validation** : Cross-validation 5-fold
5. **Métriques** : RMSE, MAE, R², Accuracy

## 🔗 Intégration API

Le modèle est automatiquement chargé par l'API FastAPI au démarrage :

```python
# Dans main.py
from project5.ml.model import MLModel

model = MLModel()
model.load_model()  # Charge model.pkl
```

## 📞 Support

Pour toute question ou problème :

1. **Vérifier l'intégrité** : `make validate`
2. **Tester le modèle** : `make test`
3. **Générer un rapport** : `make report`
4. **Consulter les logs** : Vérifier les sorties des commandes make

---

**🏢 Project5 - API de gestion énergétique des bâtiments**