kpower-forecast 2026.2.1__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.1"
+__version__ = "2026.2.2"

kpower_forecast/core.py

@@ -1,5 +1,5 @@
 import logging
-from typing import List, Literal
+from typing import List, Literal, cast
 
 import pandas as pd
 from prophet import Prophet
@@ -12,14 +12,16 @@ 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
-    
+    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)
@@ -37,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,
@@ -60,7 +63,7 @@ class KPowerForecast:
             forecast_type=forecast_type,
             heat_pump_mode=heat_pump_mode,
         )
-        
+
         self.weather_client = WeatherClient(
             lat=self.config.latitude, lon=self.config.longitude
         )
@@ -72,25 +75,26 @@ class KPowerForecast:
         """
         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()
+            df["cloud_cover"].rolling(window=window_size, min_periods=1).mean()
         )
-        
+
         return df
 
     def train(self, history_df: pd.DataFrame, force: bool = False):
@@ -107,23 +111,23 @@ 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)
 
@@ -134,9 +138,9 @@ class KPowerForecast:
         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)
+            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")
@@ -145,10 +149,10 @@ class KPowerForecast:
         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):
@@ -156,11 +160,11 @@ class KPowerForecast:
         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)
@@ -176,16 +180,16 @@ class KPowerForecast:
         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],
+            "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')
+        min_rmse = float("inf")
 
-        for cps in param_grid['changepoint_prior_scale']:
-            for sps in param_grid['seasonality_prior_scale']:
+        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")
@@ -197,24 +201,24 @@ class KPowerForecast:
                     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'
+                    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]
+                rmse = df_p["rmse"].values[0]
 
                 if rmse < min_rmse:
                     min_rmse = rmse
-                    best_params = {'cps': cps, 'sps': sps}
+                    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']
+        self.config.changepoint_prior_scale = best_params["cps"]
+        self.config.seasonality_prior_scale = best_params["sps"]
 
     def predict(self, days: int = 7) -> pd.DataFrame:
         """
@@ -225,25 +229,25 @@ 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)
-        
+
         # Night Mask & Clipping
         if self.config.forecast_type == "solar":
             logger.info("Applying night mask for solar forecast...")
@@ -251,26 +255,28 @@ class KPowerForecast:
                 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 forecast
+
+        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"]
-            ))
+            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(
@@ -278,21 +284,19 @@ class KPowerForecast:
     ) -> 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) 
+        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
-        
+        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
-        })
+
+        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,5 +1,5 @@
 import datetime
-from typing import List, Union
+from typing import List, Union, cast
 
 import numpy as np
 import pandas as pd
@@ -37,9 +37,7 @@ def calculate_solar_elevation(
     return np.array(elevations)
 
 
-def get_clear_sky_ghi(
-    lat: float, lon: float, times: pd.DatetimeIndex
-) -> pd.Series:
+def get_clear_sky_ghi(lat: float, lon: float, times: pd.DatetimeIndex) -> pd.Series:
     """
     Calculate Theoretical Clear Sky GHI (Global Horizontal Irradiance)
     using pvlib.
@@ -56,4 +54,4 @@ def get_clear_sky_ghi(
     # get_clearsky returns GHI, DNI, DHI. We only need GHI.
     # Ineichen is the default model.
     clearsky = location.get_clearsky(times)
-    return clearsky["ghi"]
+    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.1.dist-info → kpower_forecast-2026.2.2.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: kpower-forecast
-Version: 2026.2.1
+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
@@ -23,8 +23,12 @@ 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

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.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-kpower_forecast/__init__.py,sha256=WDpPbJ-2UQwUE0I2U1j0tyXPq-KOkLAuquOrMNk9oac,88
-kpower_forecast/core.py,sha256=Kg9Pc6S6N0jG4NMYMfjP03dGkULchTWggektEjh9u6w,11355
-kpower_forecast/storage.py,sha256=GBpqiirt3QG9RF_FMQ1SjKio2FR0VtkukWqtbYYaf_g,2226
-kpower_forecast/utils.py,sha256=LZLGrXq-hTFOlWIE61lEmxaW4YKVT7LMs4ZQA8sRg-g,1652
-kpower_forecast/weather_client.py,sha256=cRp2lmOfvrft2GZl3nM161OqiE5I8lnKrtJTJi7n2uw,4210
-kpower_forecast-2026.2.1.dist-info/METADATA,sha256=7H3zy8oN2hhZZIkUm_9gV1YO98WI5PEfqcD83RnxWVc,5032
-kpower_forecast-2026.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-kpower_forecast-2026.2.1.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-kpower_forecast-2026.2.1.dist-info/RECORD,,