kpower-forecast 2026.2.0__tar.gz → 2026.2.2__tar.gz

{kpower_forecast-2026.2.0 → kpower_forecast-2026.2.2}/.github/workflows/ci.yml

@@ -28,6 +28,10 @@ jobs:
       run: |
         uv pip install --system ".[dev]"
 
+    - name: Validate Version Format
+      run: |
+        python scripts/validate_version.py
+
     - name: Lint with Ruff
       run: |
         ruff check .

kpower_forecast-2026.2.2/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+        require_serial: true
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+        require_serial: true
+
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        always_run: true

{kpower_forecast-2026.2.0 → kpower_forecast-2026.2.2}/PKG-INFO

@@ -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.0 → kpower_forecast-2026.2.2}/README.md

@@ -81,6 +81,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.0 → kpower_forecast-2026.2.2}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "kpower-forecast"
-version = "2026.2.0"
+version = "2026.2.2"
 description = "Solar production and power consumption forecasting package."
 readme = "README.md"
 requires-python = ">=3.13"
 license = { text = "AGPL-3.0" }
 authors = [
-    { name = "KPower Team", email = "info@kpower.example" }
+    { name = "KSoft.TECH OSS", email = "oss@ksoft.tech" }
 ]
 keywords = ["solar", "energy", "forecast", "prophet", "weather"]
 classifiers = [
@@ -25,6 +25,7 @@ dependencies = [
     "requests>=2.31.0",
     "cmdstanpy>=1.2.0",
     "pytz>=2024.1",
+    "pvlib>=0.11.0",
 ]
 
 [project.optional-dependencies]
@@ -34,8 +35,26 @@ dev = [
     "mypy>=1.8.0",
     "types-requests",
     "types-pytz",
+    "pre-commit",
+    "scipy",
+    "pandas-stubs",
+    "scipy-stubs",
 ]
 
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = [
+    "prophet.*",
+    "pvlib.*",
+    "pysolar.*",
+]
+ignore_missing_imports = true
+
 [build-system]
 requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"

kpower_forecast-2026.2.2/scripts/validate_version.py

@@ -0,0 +1,39 @@
+import re
+import sys
+from pathlib import Path
+
+# Regex for YYYY.MM.Patch (e.g., 2026.2.1)
+VERSION_PATTERN = r"^\d{4}\.(?:[1-9]|1[0-2])\.\d+$"
+
+
+def validate_version(file_path: str, pattern: str):
+    content = Path(file_path).read_text()
+    # Find version in pyproject.toml or __init__.py
+    match = re.search(pattern, content, re.MULTILINE)
+    if not match:
+        print(f"❌ Could not find version in {file_path}")
+        return False
+
+    version = match.group(1)
+    if not re.match(VERSION_PATTERN, version):
+        print(f"❌ Invalid version format in {file_path}: '{version}'")
+        print("   Expected format: YYYY.MM.Patch (e.g., 2026.2.1)")
+        return False
+
+    print(f"✅ Version {version} in {file_path} is valid.")
+    return True
+
+
+if __name__ == "__main__":
+    success = True
+    # Check pyproject.toml
+    if not validate_version("pyproject.toml", r'^version\s*=\s*"([^"]+)"'):
+        success = False
+
+    # Check __init__.py
+    pattern = r'^__version__\s*=\s*"([^"]+)"'
+    if not validate_version("src/kpower_forecast/__init__.py", pattern):
+        success = False
+
+    if not success:
+        sys.exit(1)

{kpower_forecast-2026.2.0 → kpower_forecast-2026.2.2}/src/kpower_forecast/__init__.py

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

kpower_forecast-2026.2.2/src/kpower_forecast/core.py

@@ -0,0 +1,302 @@
+import logging
+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, 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)
+    longitude: float = Field(..., ge=-180, le=180)
+    storage_path: str = "./data"
+    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
+    def check_interval(cls, v: int) -> int:
+        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,
+        model_id: str,
+        latitude: float,
+        longitude: float,
+        storage_path: str = "./data",
+        interval_minutes: int = 15,
+        forecast_type: Literal["solar", "consumption"] = "solar",
+        heat_pump_mode: bool = False,
+    ):
+        self.config = KPowerConfig(
+            model_id=model_id,
+            latitude=latitude,
+            longitude=longitude,
+            storage_path=storage_path,
+            interval_minutes=interval_minutes,
+            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.
+        """
+        if not force and self.storage.load_model(self.config.model_id):
+            logger.info(
+                f"Model {self.config.model_id} already exists. "
+                "Use force=True to retrain."
+            )
+            return
+
+        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)
+
+        # 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("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.
+        """
+        m = self.storage.load_model(self.config.model_id)
+        if m is None:
+            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)
+
+        # 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, forecast["ds"]
+            )
+            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-2026.2.0 → kpower_forecast-2026.2.2}/src/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-2026.2.0 → kpower_forecast-2026.2.2}/src/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"])