feat(ml): initialise le pipeline d'entrainement LightGBM (ADR 0005)

ml/tests/test_baseline.py

@@ -0,0 +1,11 @@
+import pandas as pd
+
+from enervision_ml.baseline import SEASONAL_LAG_COLUMN, seasonal_persistence_predictions
+
+
+def test_seasonal_persistence_predictions_returns_the_168h_lag_column() -> None:
+    features = pd.DataFrame({SEASONAL_LAG_COLUMN: [1.0, 2.0, 3.0], "autre_colonne": [9, 9, 9]})
+
+    predictions = seasonal_persistence_predictions(features)
+
+    assert predictions.tolist() == [1.0, 2.0, 3.0]

ml/tests/test_features.py

@@ -0,0 +1,96 @@
+from datetime import UTC, datetime, timedelta
+from typing import cast
+
+import pandas as pd
+
+from enervision_ml.features import TARGET_COLUMN, build_features, feature_columns
+
+
+def make_site_reading(
+    site_id: str, *, heures: int, depart: datetime, valeur: float = 10.0
+) -> pd.DataFrame:
+    instants = [depart + timedelta(hours=h) for h in range(heures)]
+    return pd.DataFrame(
+        {
+            "site_id": site_id,
+            "timestamp": instants,
+            TARGET_COLUMN: [valeur + h for h in range(heures)],
+            "temperature_celsius": [15.0] * heures,
+            "humidity_percent": [50.0] * heures,
+            "solar_irradiance_wm2": [0.0] * heures,
+            "is_working_hours": [True] * heures,
+            "site_type": "office",
+            "capacity_kw": 100.0,
+        }
+    )
+
+
+def two_site_frame(heures: int = 200) -> pd.DataFrame:
+    depart = datetime(2026, 1, 1, tzinfo=UTC)
+    return pd.concat(
+        [
+            make_site_reading("site-a", heures=heures, depart=depart, valeur=10.0),
+            make_site_reading("site-b", heures=heures, depart=depart, valeur=1000.0),
+        ],
+        ignore_index=True,
+    )
+
+
+def test_build_features_returns_every_declared_feature_column() -> None:
+    features = build_features(two_site_frame())
+
+    manquantes = set(feature_columns()) - set(features.columns)
+
+    assert manquantes == set()
+
+
+def test_build_features_sets_a_constant_period_minutes() -> None:
+    features = build_features(two_site_frame())
+
+    assert (features["period_minutes"] == 60).all()
+
+
+def test_build_features_lag_1h_matches_the_previous_hour_of_the_same_site() -> None:
+    features = build_features(two_site_frame(heures=200))
+    site_a = features[features["site_id"] == "site-a"].reset_index(drop=True)
+
+    assert site_a.loc[10, f"{TARGET_COLUMN}_lag_1h"] == site_a.loc[9, TARGET_COLUMN]
+
+
+def test_build_features_lag_168h_is_nan_before_a_full_week_of_history() -> None:
+    features = build_features(two_site_frame(heures=200))
+    site_a = features[features["site_id"] == "site-a"].reset_index(drop=True)
+
+    assert pd.isna(site_a.loc[100, f"{TARGET_COLUMN}_lag_168h"])
+    assert not pd.isna(site_a.loc[168, f"{TARGET_COLUMN}_lag_168h"])
+
+
+def test_build_features_never_leaks_lags_across_sites() -> None:
+    # site-b demarre a 1000 : si un lag de site-a s'y glissait, la valeur sortirait de son
+    # echelle (10, 11, 12, ...).
+    features = build_features(two_site_frame(heures=200))
+    site_b = features[features["site_id"] == "site-b"].reset_index(drop=True)
+
+    assert cast(float, site_b.loc[5, f"{TARGET_COLUMN}_lag_1h"]) >= 1000.0
+
+
+def test_build_features_rolling_mean_excludes_the_current_hour() -> None:
+    # Valeurs constantes sauf la derniere ligne : si la moyenne glissante incluait l'heure
+    # courante, la constante ne resterait pas stable jusqu'au bout.
+    depart = datetime(2026, 1, 1, tzinfo=UTC)
+    frame = make_site_reading("site-a", heures=200, depart=depart, valeur=10.0)
+    frame[TARGET_COLUMN] = 10.0
+    frame.loc[frame.index[-1], TARGET_COLUMN] = 10_000.0
+
+    features = build_features(frame).reset_index(drop=True)
+
+    assert features.loc[len(features) - 1, f"{TARGET_COLUMN}_rolling_mean_24h"] == 10.0
+
+
+def test_build_features_computes_calendar_fields_from_the_timestamp() -> None:
+    depart = datetime(2026, 1, 3, 6, tzinfo=UTC)  # un samedi, 6h
+    features = build_features(make_site_reading("site-a", heures=1, depart=depart))
+
+    assert features.loc[0, "hour"] == 6
+    assert features.loc[0, "day_of_week"] == 5
+    assert features.loc[0, "is_weekend"] == 1

ml/tests/test_metrics.py

@@ -0,0 +1,45 @@
+import pandas as pd
+import pytest
+
+from enervision_ml.metrics import regression_metrics
+
+
+def test_regression_metrics_computes_mae_and_rmse_on_known_values() -> None:
+    y_true = pd.Series([10.0, 20.0, 30.0])
+    y_pred = pd.Series([12.0, 18.0, 33.0])
+
+    resultat = regression_metrics(y_true, y_pred)
+
+    assert resultat["mae"] == pytest.approx(7 / 3)
+    assert resultat["n_observations"] == 3
+
+
+def test_regression_metrics_ignores_rows_with_a_missing_value() -> None:
+    y_true = pd.Series([10.0, None, 30.0])
+    y_pred = pd.Series([12.0, 18.0, None])
+
+    resultat = regression_metrics(y_true, y_pred)
+
+    assert resultat["n_observations"] == 1
+    assert resultat["mae"] == 2.0
+
+
+def test_regression_metrics_excludes_zero_actuals_from_mape_only() -> None:
+    y_true = pd.Series([0.0, 10.0])
+    y_pred = pd.Series([5.0, 12.0])
+
+    resultat = regression_metrics(y_true, y_pred)
+
+    assert resultat["n_observations"] == 2
+    assert resultat["mape"] == pytest.approx(20.0)
+
+
+def test_metrics_are_zero_for_a_perfect_prediction() -> None:
+    y_true = pd.Series([10.0, 20.0])
+    y_pred = pd.Series([10.0, 20.0])
+
+    resultat = regression_metrics(y_true, y_pred)
+
+    assert resultat["mae"] == 0.0
+    assert resultat["rmse"] == 0.0
+    assert resultat["mape"] == 0.0

ml/tests/test_train.py

@@ -0,0 +1,76 @@
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from enervision_ml.features import TARGET_COLUMN, build_features, feature_columns
+from enervision_ml.train import chronological_split, prepare_dataset, train
+
+
+def make_frame(site_id: str, *, heures: int, depart: datetime) -> pd.DataFrame:
+    instants = [depart + timedelta(hours=h) for h in range(heures)]
+    rng = np.random.default_rng(42)
+
+    return pd.DataFrame(
+        {
+            "site_id": site_id,
+            "timestamp": instants,
+            TARGET_COLUMN: 100.0 + 10.0 * np.sin(np.arange(heures) / 24) + rng.normal(0, 1, heures),
+            "temperature_celsius": 15.0,
+            "humidity_percent": 50.0,
+            "solar_irradiance_wm2": 0.0,
+            "is_working_hours": True,
+            "site_type": "office",
+            "capacity_kw": 100.0,
+        }
+    )
+
+
+def test_chronological_split_puts_the_most_recent_rows_in_validation() -> None:
+    depart = datetime(2026, 1, 1, tzinfo=UTC)
+    features = make_frame("site-a", heures=200, depart=depart)
+
+    entrainement, validation = chronological_split(features, test_fraction=0.2)
+
+    assert entrainement["timestamp"].max() < validation["timestamp"].min()
+    # La coupure vient d'un quantile sur les dates : une approximation du taux demande, pas un
+    # decompte exact de lignes.
+    assert abs(len(validation) - 0.2 * len(features)) <= 2
+
+
+def test_prepare_dataset_types_site_type_as_a_pandas_category() -> None:
+    depart = datetime(2026, 1, 1, tzinfo=UTC)
+    features = build_features(make_frame("site-a", heures=200, depart=depart))
+
+    X, y = prepare_dataset(features, feature_columns())
+
+    assert X["site_type"].dtype.name == "category"
+    assert y.name == TARGET_COLUMN
+
+
+def test_train_runs_end_to_end_on_synthetic_data_and_beats_a_dummy_baseline(
+    tmp_path: Path,
+) -> None:
+    depart = datetime(2026, 1, 1, tzinfo=UTC)
+    frame = pd.concat(
+        [
+            make_frame("site-a", heures=400, depart=depart),
+            make_frame("site-b", heures=400, depart=depart),
+        ],
+        ignore_index=True,
+    )
+    csv_path = tmp_path / "synthetic.csv"
+    frame.to_csv(csv_path, index=False)
+
+    model_metrics, baseline_metrics = train(
+        csv_path=csv_path,
+        model_output=tmp_path / "model.txt",
+        test_fraction=0.2,
+        tracking_uri=f"sqlite:///{tmp_path / 'mlflow.db'}",
+    )
+
+    assert (tmp_path / "model.txt").exists()
+    assert model_metrics["n_observations"] > 0
+    assert model_metrics["mae"] >= 0
+    assert baseline_metrics["n_observations"] == model_metrics["n_observations"]