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.
- 🔋 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.
# Core package
pip install kpower-forecast
# With CLI support (recommended for interactive use)
pip install "kpower-forecast[cli]"KPower Forecast comes with a powerful CLI for interactive forecasting and visualization.
# Forecast solar production using Home Assistant CSV export
# Supports different data categories: instant_energy, cumulative_energy, power
# Supports different units: kWh, Wh, kW, W
# Supports tuning cloud damping: --cloud-impact (default 0.35)
kpower-forecast solar rooftop-1 46.05 14.50 -i history.csv --category power --unit W --cloud-impact 0.3 --horizon 7
# Forecast power consumption
kpower-forecast consumption main-meter 46.05 14.50 -i history.csv --category cumulative_energy --unit kWh --horizon 3 --heatpumpCLI Features:
- Automatic HA Parsing: Heuristic detection of
last_changedandstatecolumns. - Smart Data Normalization: Handles meter readings (cumulative), power (kW/W), and instant energy.
- Heat Pump Mode: Enable
--heatpumpto correlate consumption with outdoor temperature. - Inconsistent Intervals: Robustly handles measurements with non-uniform time gaps.
- Rich Tables: Beautiful daily summary tables in your terminal.
- Terminal Graphs: Instant visualization of forecasts and confidence intervals via
plotext.
from kpower_forecast import KPowerForecast
from kpower_forecast.core import DataCategory, MeasurementUnit
import pandas as pd
# 1. Initialize for your location with specific data types
kp = KPowerForecast(
model_id="rooftop_solar",
latitude=46.0569,
longitude=14.5058,
forecast_type="solar",
data_category=DataCategory.POWER,
unit=MeasurementUnit.W
)
# 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())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
)| 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 |
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.
- CI Validation: Every Pull Request is checked against
scripts/validate_version.pyto ensure adherence. - Consistency: Both
pyproject.tomlandsrc/kpower_forecast/__init__.pymust match exactly.
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 .Distributed under the GNU Affero General Public License v3.0. See LICENSE for more information.
Made with ❤️ for a greener future.