kpower-forecast 2026.2.1

Solar production and power consumption forecasting package.

☀️ KPower Forecast 📈

Production-grade solar production and power consumption forecasting.

Built with Facebook Prophet and powered by Open-Meteo. KPower Forecast provides a high-level API for training and predicting energy metrics with physics-informed corrections.

---

✨ Key Features

• 🔋 Dual Mode: Specialized logic for both Solar Production and Energy Consumption.
• 🌓 Night Masking: Physics-informed clamping using solar elevation to eliminate "ghost production" at night.
• 🌡️ Weather Integration: Automatic fetching and resampling of temperature, cloud cover, and radiation.
• 🤖 Prophet Optimized: Pre-configured regressors for maximum accuracy.
• 💾 Smart Persistence: Automatic serialization of models to skip retraining when possible.
• ❄️ Heat Pump Mode: Optional temperature correlation for energy consumption models.

---

🚀 Quick Start

Installation

pip install kpower-forecast

☀️ Solar Production Forecast

from kpower_forecast import KPowerForecast
import pandas as pd

# 1. Initialize for your location
kp = KPowerForecast(
    model_id="rooftop_solar",
    latitude=46.0569,
    longitude=14.5058,
    forecast_type="solar"
)

# 2. Train with your history
# history_df = pd.DataFrame({'ds': [...], 'y': [...]})
# kp.train(history_df)

# 3. Predict the next 7 days
forecast = kp.predict(days=7)
print(forecast[['ds', 'yhat']].head())

🏠 Energy Consumption Forecast

kp_cons = KPowerForecast(
    model_id="house_meter",
    latitude=46.0569,
    longitude=14.5058,
    forecast_type="consumption",
    heat_pump_mode=True # Accounts for heating/cooling loads
)

---

🛠️ Advanced Configuration

Parameter	Type	Default	Description
model_id	str	required	Unique ID for model persistence
latitude	float	required	Location Latitude
longitude	float	required	Location Longitude
interval_minutes	`int"	15	Data resolution (15 or 60)
storage_path	str	"./data"	Directory for saved models
heat_pump_mode	bool	False	Enable temperature regressor for consumption

---

🔢 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 for lightning-fast dependency management.

# Clone and setup
git clone https://github.com/akorenc/kpower-forecast
cd kpower-forecast
uv sync --all-extras

# Run tests
uv run pytest

# Linting
uv run ruff check .

---

📄 License

Distributed under the GNU Affero General Public License v3.0. See LICENSE for more information.

---

Made with ❤️ for a greener future.