kpower-forecast 2026.2.0__py3-none-any.whl → 2026.2.2__py3-none-any.whl

kpower_forecast/__init__.py

@@ -1,4 +1,4 @@
 from .core import KPowerForecast
 
 __all__ = ["KPowerForecast"]
-__version__ = "2026.2.0"
+__version__ = "2026.2.2"

kpower_forecast/core.py

@@ -1,16 +1,27 @@
 import logging
-from typing import Literal
+from typing import List, Literal, cast
 
 import pandas as pd
 from prophet import Prophet
+from prophet.diagnostics import cross_validation, performance_metrics
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from .storage import ModelStorage
-from .utils import calculate_solar_elevation
+from .utils import calculate_solar_elevation, get_clear_sky_ghi
 from .weather_client import WeatherClient
 
 logger = logging.getLogger(__name__)
 
+
+class PredictionInterval(BaseModel):
+    timestamp: pd.Timestamp
+    expected_kwh: float
+    lower_bound_kwh: float  # P10
+    upper_bound_kwh: float  # P90
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
 class KPowerConfig(BaseModel):
     model_id: str
     latitude: float = Field(..., ge=-90, le=90)
@@ -19,6 +30,8 @@ class KPowerConfig(BaseModel):
     interval_minutes: int = Field(15)
     forecast_type: Literal["solar", "consumption"] = "solar"
     heat_pump_mode: bool = False
+    changepoint_prior_scale: float = 0.05
+    seasonality_prior_scale: float = 10.0
 
     @field_validator("interval_minutes")
     @classmethod
@@ -26,9 +39,10 @@ class KPowerConfig(BaseModel):
         if v not in (15, 60):
             raise ValueError("interval_minutes must be 15 or 60")
         return v
-    
+
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
+
 class KPowerForecast:
     def __init__(
         self,
@@ -49,12 +63,40 @@ class KPowerForecast:
             forecast_type=forecast_type,
             heat_pump_mode=heat_pump_mode,
         )
-        
+
         self.weather_client = WeatherClient(
             lat=self.config.latitude, lon=self.config.longitude
         )
         self.storage = ModelStorage(storage_path=self.config.storage_path)
 
+    def _prepare_features(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Add physics-informed features and rolling windows.
+        """
+        df = df.copy()
+        df["ds"] = pd.to_datetime(df["ds"], utc=True)
+
+        # 1. Physics: Clear Sky GHI
+        logger.info("Calculating physics-informed Clear Sky GHI...")
+        # Ensure index is DatetimeIndex for pvlib
+        temp_df = df.set_index("ds")
+        if not isinstance(temp_df.index, pd.DatetimeIndex):
+            raise ValueError("Index must be DatetimeIndex")
+
+        df["clear_sky_ghi"] = get_clear_sky_ghi(
+            self.config.latitude, self.config.longitude, temp_df.index
+        ).values
+
+        # 2. Rolling Cloud Cover (3-hour window)
+        # 3 hours = 180 minutes. Window depends on interval_minutes.
+        window_size = 180 // self.config.interval_minutes
+        logger.info(f"Adding rolling cloud cover (window={window_size})...")
+        df["rolling_cloud_cover"] = (
+            df["cloud_cover"].rolling(window=window_size, min_periods=1).mean()
+        )
+
+        return df
+
     def train(self, history_df: pd.DataFrame, force: bool = False):
         """
         Trains the Prophet model using the provided history.
@@ -69,41 +111,115 @@ class KPowerForecast:
         df = history_df.copy()
         if "ds" not in df.columns or "y" not in df.columns:
             raise ValueError("history_df must contain 'ds' and 'y' columns")
-        
+
         df["ds"] = pd.to_datetime(df["ds"], utc=True)
         df = df.sort_values("ds")
-        
+
         start_date = df["ds"].min().date()
         end_date = df["ds"].max().date()
-        
+
         weather_df = self.weather_client.fetch_historical(start_date, end_date)
         weather_df = self.weather_client.resample_weather(
             weather_df, self.config.interval_minutes
         )
-        
+
         df = pd.merge(df, weather_df, on="ds", how="left")
-        
+
         weather_cols = ["temperature_2m", "cloud_cover", "shortwave_radiation"]
         df[weather_cols] = df[weather_cols].interpolate(method="linear").bfill().ffill()
-        
+
         if df[weather_cols].isnull().any().any():
             df = df.dropna(subset=weather_cols)
 
-        m = Prophet()
-        
+        # Feature Engineering
+        df = self._prepare_features(df)
+
+        # Initialize Prophet with tuned hyperparameters
+        m = Prophet(
+            changepoint_prior_scale=self.config.changepoint_prior_scale,
+            seasonality_prior_scale=self.config.seasonality_prior_scale,
+            interval_width=0.8,  # Used for P10/P90 (80% interval)
+        )
+
         if self.config.forecast_type == "solar":
             m.add_regressor("temperature_2m")
-            m.add_regressor("cloud_cover")
+            m.add_regressor("rolling_cloud_cover")
             m.add_regressor("shortwave_radiation")
+            m.add_regressor("clear_sky_ghi")
         elif self.config.forecast_type == "consumption":
             if self.config.heat_pump_mode:
                 m.add_regressor("temperature_2m")
-        
+
         logger.info(f"Training Prophet model for {self.config.forecast_type}...")
         m.fit(df)
-        
+
         self.storage.save_model(m, self.config.model_id)
 
+    def tune_model(self, history_df: pd.DataFrame, days: int = 30):
+        """
+        Find optimal hyperparameters using cross-validation.
+        """
+        logger.info(f"Tuning model hyperparameters using {days} days of history...")
+
+        # We need to prepare data first as cross_validation needs the regressors
+        # This is a bit complex as we need weather data for history_df
+        # For simplicity, we assume train() logic but without fitting.
+
+        # Prepare data (duplicated logic from train, could be refactored)
+        df = history_df.copy()
+        df["ds"] = pd.to_datetime(df["ds"], utc=True)
+        start_date = df["ds"].min().date()
+        end_date = df["ds"].max().date()
+        weather_df = self.weather_client.fetch_historical(start_date, end_date)
+        weather_df = self.weather_client.resample_weather(
+            weather_df, self.config.interval_minutes
+        )
+        df = pd.merge(df, weather_df, on="ds", how="left")
+        weather_cols = ["temperature_2m", "cloud_cover", "shortwave_radiation"]
+        df[weather_cols] = df[weather_cols].interpolate(method="linear").bfill().ffill()
+        df = self._prepare_features(df.dropna(subset=weather_cols))
+
+        param_grid = {
+            "changepoint_prior_scale": [0.001, 0.05, 0.5],
+            "seasonality_prior_scale": [0.01, 1.0, 10.0],
+        }
+
+        # Simplified tuning loop
+        best_params = {}
+        min_rmse = float("inf")
+
+        for cps in param_grid["changepoint_prior_scale"]:
+            for sps in param_grid["seasonality_prior_scale"]:
+                m = Prophet(changepoint_prior_scale=cps, seasonality_prior_scale=sps)
+                if self.config.forecast_type == "solar":
+                    m.add_regressor("temperature_2m")
+                    m.add_regressor("rolling_cloud_cover")
+                    m.add_regressor("shortwave_radiation")
+                    m.add_regressor("clear_sky_ghi")
+                elif (
+                    self.config.forecast_type == "consumption"
+                    and self.config.heat_pump_mode
+                ):
+                    m.add_regressor("temperature_2m")
+
+                m.fit(df)
+
+                # Cross-validation
+                # initial should be at least 3x horizon
+                df_cv = cross_validation(
+                    m, initial=f"{days // 2} days", period="5 days", horizon="5 days"
+                )
+                df_p = performance_metrics(df_cv, rolling_window=1)
+                rmse = df_p["rmse"].values[0]
+
+                if rmse < min_rmse:
+                    min_rmse = rmse
+                    best_params = {"cps": cps, "sps": sps}
+
+        logger.info(f"Best params found: {best_params} with RMSE {min_rmse}")
+        self.config.changepoint_prior_scale = best_params["cps"]
+        self.config.seasonality_prior_scale = best_params["sps"]
+
     def predict(self, days: int = 7) -> pd.DataFrame:
         """
         Generates forecast for the next 'days' days.
@@ -113,30 +229,74 @@ class KPowerForecast:
             raise RuntimeError(
                 f"Model {self.config.model_id} not found. Please run train() first."
             )
-            
+
         weather_forecast = self.weather_client.fetch_forecast(days=days)
         weather_forecast = self.weather_client.resample_weather(
             weather_forecast, self.config.interval_minutes
         )
-        
+
         future = pd.DataFrame({"ds": weather_forecast["ds"]})
         future = pd.merge(future, weather_forecast, on="ds", how="left")
-        
+
         weather_cols = ["temperature_2m", "cloud_cover", "shortwave_radiation"]
         future[weather_cols] = (
             future[weather_cols].interpolate(method="linear").bfill().ffill()
         )
-        
+
+        # Feature Engineering
+        future = self._prepare_features(future)
+
         forecast = m.predict(future)
-        result = forecast[["ds", "yhat"]].copy()
-        
+
+        # Night Mask & Clipping
         if self.config.forecast_type == "solar":
             logger.info("Applying night mask for solar forecast...")
             elevations = calculate_solar_elevation(
-                self.config.latitude, self.config.longitude, result["ds"]
+                self.config.latitude, self.config.longitude, forecast["ds"]
             )
-            result.loc[elevations < 0, "yhat"] = 0
-        
-        result["yhat"] = result["yhat"].clip(lower=0)
-        
-        return result
+            forecast.loc[elevations < 0, ["yhat", "yhat_lower", "yhat_upper"]] = 0
+
+        for col in ["yhat", "yhat_lower", "yhat_upper"]:
+            forecast[col] = forecast[col].clip(lower=0)
+
+        return cast(pd.DataFrame, forecast)
+
+    def get_prediction_intervals(self, days: int = 7) -> List[PredictionInterval]:
+        """
+        Returns prediction intervals for EMS.
+        """
+        forecast = self.predict(days=days)
+
+        intervals = []
+        for _, row in forecast.iterrows():
+            intervals.append(
+                PredictionInterval(
+                    timestamp=row["ds"],
+                    expected_kwh=row["yhat"],
+                    lower_bound_kwh=row["yhat_lower"],
+                    upper_bound_kwh=row["yhat_upper"],
+                )
+            )
+        return intervals
+
+    def get_surplus_probability(
+        self, threshold_kwh: float, days: int = 7
+    ) -> pd.DataFrame:
+        """
+        Returns probability of exceeding threshold_kwh.
+        Prophet doesn't provide direct probabilities, but we can estimate
+        from the uncertainty interval (yhat_upper - yhat_lower)
+        assuming normal distribution.
+        """
+        forecast = self.predict(days=days)
+
+        # Estimate sigma from 80% interval (approx 1.28 * sigma)
+        sigma = (forecast["yhat_upper"] - forecast["yhat_lower"]) / (2 * 1.28)
+        sigma = sigma.replace(0, 1e-9)  # Avoid div by zero
+
+        from scipy.stats import norm
+
+        z_score = (threshold_kwh - forecast["yhat"]) / sigma
+        prob_exceed = 1 - norm.cdf(z_score)
+
+        return pd.DataFrame({"ds": forecast["ds"], "surplus_prob": prob_exceed})

kpower_forecast/storage.py

@@ -8,6 +8,7 @@ from prophet.serialize import model_from_json, model_to_json
 
 logger = logging.getLogger(__name__)
 
+
 class ModelStorage:
     def __init__(self, storage_path: str):
         self.storage_path = Path(storage_path)
@@ -50,8 +51,8 @@ class ModelStorage:
                 return model_from_json(json.load(f))
         except Exception as e:
             logger.error(f"Failed to load model {model_id}: {e}")
-            # If load fails, we might want to return None to trigger retraining, 
-            # or raise to alert the user. 
+            # If load fails, we might want to return None to trigger retraining,
+            # or raise to alert the user.
             # Given "production-grade", maybe explicit failure is safer
             # than silent fallback?
             # But the prompt says "If a model exists, load it...

kpower_forecast/utils.py

@@ -1,8 +1,9 @@
 import datetime
-from typing import List, Union
+from typing import List, Union, cast
 
 import numpy as np
 import pandas as pd
+from pvlib.location import Location
 from pysolar.solar import get_altitude
 
 
@@ -12,13 +13,13 @@ def calculate_solar_elevation(
     """
     Calculate solar elevation angles (altitude) for a list of times
     at a specific location.
-    
+
     Args:
         lat: Latitude in decimal degrees.
         lon: Longitude in decimal degrees.
-        times: List of datetime objects or pandas DatetimeIndex. 
+        times: List of datetime objects or pandas DatetimeIndex.
                Must be timezone-aware or UTC.
-               
+
     Returns:
         Numpy array of elevation angles in degrees.
     """
@@ -28,9 +29,29 @@ def calculate_solar_elevation(
         if t.tzinfo is None:
             # Assume UTC if naive, though strictly we should enforce awareness
             t = t.replace(tzinfo=datetime.timezone.utc)
-        
+
         # get_altitude returns degrees
         alt = get_altitude(lat, lon, t)
         elevations.append(alt)
-    
+
     return np.array(elevations)
+
+
+def get_clear_sky_ghi(lat: float, lon: float, times: pd.DatetimeIndex) -> pd.Series:
+    """
+    Calculate Theoretical Clear Sky GHI (Global Horizontal Irradiance)
+    using pvlib.
+
+    Args:
+        lat: Latitude.
+        lon: Longitude.
+        times: Pandas DatetimeIndex (must be timezone aware).
+
+    Returns:
+        Pandas Series of GHI values.
+    """
+    location = Location(lat, lon)
+    # get_clearsky returns GHI, DNI, DHI. We only need GHI.
+    # Ineichen is the default model.
+    clearsky = location.get_clearsky(times)
+    return cast(pd.Series, clearsky["ghi"])

kpower_forecast/weather_client.py

@@ -8,6 +8,7 @@ from pydantic import BaseModel
 
 logger = logging.getLogger(__name__)
 
+
 class WeatherConfig(BaseModel):
     base_url: str = "https://api.open-meteo.com/v1/forecast"
     # Historical API is different, usually:
@@ -19,27 +20,28 @@ class WeatherConfig(BaseModel):
     # For simplicity, let's allow passing the base_url.
     archive_url: str = "https://archive-api.open-meteo.com/v1/archive"
 
+
 class WeatherClient:
     def __init__(self, lat: float, lon: float, config: Optional[WeatherConfig] = None):
         self.lat = lat
         self.lon = lon
         self.config = config or WeatherConfig()
-        
+
     def fetch_historical(
         self, start_date: datetime.date, end_date: datetime.date
     ) -> pd.DataFrame:
         """
         Fetch historical weather data for training.
         """
-        params = {
+        params: dict[str, str | float | list[str]] = {
             "latitude": self.lat,
             "longitude": self.lon,
             "start_date": start_date.isoformat(),
             "end_date": end_date.isoformat(),
             "hourly": ["temperature_2m", "cloud_cover", "shortwave_radiation"],
-            "timezone": "UTC"
+            "timezone": "UTC",
         }
-        
+
         try:
             logger.info(f"Fetching historical weather from {self.config.archive_url}")
             response = requests.get(self.config.archive_url, params=params, timeout=10)
@@ -54,14 +56,14 @@ class WeatherClient:
         """
         Fetch weather forecast for prediction.
         """
-        params = {
+        params: dict[str, str | float | int | list[str]] = {
             "latitude": self.lat,
             "longitude": self.lon,
             "hourly": ["temperature_2m", "cloud_cover", "shortwave_radiation"],
             "forecast_days": days,
-            "timezone": "UTC"
+            "timezone": "UTC",
         }
-        
+
         try:
             logger.info(f"Fetching forecast weather from {self.config.base_url}")
             response = requests.get(self.config.base_url, params=params, timeout=10)
@@ -76,18 +78,20 @@ class WeatherClient:
         hourly = data.get("hourly", {})
         if not hourly:
             raise ValueError("No hourly data in response")
-            
-        df = pd.DataFrame({
-            "ds": pd.to_datetime(hourly["time"], utc=True),
-            "temperature_2m": hourly["temperature_2m"],
-            "cloud_cover": hourly["cloud_cover"],
-            "shortwave_radiation": hourly["shortwave_radiation"]
-        })
-        
-        # Open-Meteo returns nulls sometimes, fill or drop? 
+
+        df = pd.DataFrame(
+            {
+                "ds": pd.to_datetime(hourly["time"], utc=True),
+                "temperature_2m": hourly["temperature_2m"],
+                "cloud_cover": hourly["cloud_cover"],
+                "shortwave_radiation": hourly["shortwave_radiation"],
+            }
+        )
+
+        # Open-Meteo returns nulls sometimes, fill or drop?
         # Linear interpolation is usually safe for weather gaps
-        df = df.interpolate(method='linear').bfill().ffill()
-        
+        df = df.interpolate(method="linear").bfill().ffill()
+
         return df
 
     def resample_weather(self, df: pd.DataFrame, interval_minutes: int) -> pd.DataFrame:
@@ -97,19 +101,22 @@ class WeatherClient:
         """
         if df.empty:
             return df
-            
+
         df = df.set_index("ds").sort_index()
-        
+
         # Check if we need resampling
+        if not isinstance(df.index, pd.DatetimeIndex):
+            raise ValueError("Index must be DatetimeIndex")
+
         current_freq = pd.infer_freq(df.index)
         target_freq = f"{interval_minutes}min"
-        
+
         if current_freq == target_freq:
             return df.reset_index()
-            
+
         # Resample and interpolate
         # Cubic is good for temperature/radiation curves
         df_resampled = df.resample(target_freq).interpolate(method="cubic")
-        
+
         # Reset index to get 'ds' column back
         return df_resampled.reset_index()

{kpower_forecast-2026.2.0.dist-info → kpower_forecast-2026.2.2.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: kpower-forecast
-Version: 2026.2.0
+Version: 2026.2.2
 Summary: Solar production and power consumption forecasting package.
-Author-email: KPower Team <info@kpower.example>
+Author-email: "KSoft.TECH OSS" <oss@ksoft.tech>
 License: AGPL-3.0
 License-File: LICENSE
 Keywords: energy,forecast,prophet,solar,weather
@@ -16,14 +16,19 @@ Requires-Dist: cmdstanpy>=1.2.0
 Requires-Dist: numpy>=1.26.0
 Requires-Dist: pandas>=2.2.0
 Requires-Dist: prophet>=1.1.5
+Requires-Dist: pvlib>=0.11.0
 Requires-Dist: pydantic>=2.6.0
 Requires-Dist: pysolar>=0.8.0
 Requires-Dist: pytz>=2024.1
 Requires-Dist: requests>=2.31.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pandas-stubs; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Requires-Dist: scipy; extra == 'dev'
+Requires-Dist: scipy-stubs; extra == 'dev'
 Requires-Dist: types-pytz; extra == 'dev'
 Requires-Dist: types-requests; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -111,6 +116,21 @@ kp_cons = KPowerForecast(
 
 ---
 
+## 🔢 Versioning
+
+This project follows a custom **Date-Based Versioning** scheme:
+`YYYY.MM.Patch` (e.g., `2026.2.1`)
+
+- **YYYY**: Year of release.
+- **MM**: Month of release (no leading zero, 1-12).
+- **Patch**: Incremental counter for releases within the same month.
+
+### Enforcement
+- **CI Validation**: Every Pull Request is checked against `scripts/validate_version.py` to ensure adherence.
+- **Consistency**: Both `pyproject.toml` and `src/kpower_forecast/__init__.py` must match exactly.
+
+---
+
 ## 🧪 Development & Testing
 
 We use [uv](https://github.com/astral-sh/uv) for lightning-fast dependency management.

kpower_forecast-2026.2.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+kpower_forecast/__init__.py,sha256=K5T2i1xP5ZNLgeTdRpEd_E7_WmhaoBTiHHur-GTfY9o,88
+kpower_forecast/core.py,sha256=-cIHwUJb-2qqVfCAlS8Nb1ONcsCEDnVDk4Ljes7U0Q8,11237
+kpower_forecast/storage.py,sha256=3dwejuB2QKP1XMXcKR8nCAYFTCzylSW4jIS9xfjyaZM,2225
+kpower_forecast/utils.py,sha256=-X6e58osfN2z3oBcZHth3YXybgWNf8Ep2o_nuqsT1OM,1670
+kpower_forecast/weather_client.py,sha256=T9bi_rT0LWYVx8ug7a27GwzY-KTPlMdxI9J4SwNnfdw,4350
+kpower_forecast-2026.2.2.dist-info/METADATA,sha256=u79c7nhk3haudnOuuRyuRhYPdOI4si-6RNjU8Ywagw8,5198
+kpower_forecast-2026.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kpower_forecast-2026.2.2.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+kpower_forecast-2026.2.2.dist-info/RECORD,,

kpower_forecast-2026.2.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-kpower_forecast/__init__.py,sha256=cHOO5TdFOeVt1rmNUDwzRDX2ie2KwsBog6aV2D23APg,88
-kpower_forecast/core.py,sha256=aE2b0XBj5wcYo1l6hgTP0roWOARtsVYkj4Uy5DPHqT8,5027
-kpower_forecast/storage.py,sha256=GBpqiirt3QG9RF_FMQ1SjKio2FR0VtkukWqtbYYaf_g,2226
-kpower_forecast/utils.py,sha256=0ID3XKpbxUvphiR7apg7Mzy72c-bDtQ8AhGtVcaoN8g,1079
-kpower_forecast/weather_client.py,sha256=cRp2lmOfvrft2GZl3nM161OqiE5I8lnKrtJTJi7n2uw,4210
-kpower_forecast-2026.2.0.dist-info/METADATA,sha256=6oFS_xfcTu_UsfB1est4MjMJea_i_X1sS1vtEodDr_Y,4501
-kpower_forecast-2026.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-kpower_forecast-2026.2.0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-kpower_forecast-2026.2.0.dist-info/RECORD,,