Predbat Home Battery Prediction

Predbat features a machine learning component that uses a lightweight multi-layer perceptron (MLP) neural network to predict household energy consumption for the next 48 hours in 5-minute intervals.

The model learns from:

• Historical load patterns
• Time-of-day and day-of-week patterns
• Historical PV generation (optional)
• Temperature forecasts (optional)
• Historical and future energy import/export rates

Key technical characteristics:

• Implementation: Pure NumPy (no heavy deep learning frameworks required).
• Architecture: Deep neural network with 3 hidden layers containing [512, 256, 64] neurons.
• Optimization: Uses He initialization and AdamW weight decay.
• Training Lifecycle: Automatically trains on historical data (requires $\ge$ 1 day, 7+ days recommended). It fine-tunes every 2 hours using the full dataset to adapt to changing patterns. It uses time-weighted training to prioritize recent data.
• Persistence: The model persists across restarts and falls back gracefully if predictions are unreliable.

The Bot PR Flow extends the existing issue-triage bot. When a GitHub issue is already triaged (marked with the BOT_TRIAGED label) and a user adds the BOT_PR label, the bot will automatically implement the fix/feature and open a draft PR for review.

Architecture Overview

• Orchestration: tools/triage_daemon.py performs a second poll specifically for issues labelled BOT_PR.
• State Management: State is managed entirely via GitHub labels: BOT_TRIAGED, BOT_PR_OPENED, and BOT_PR_FAILED. No changes to state.json are required.
• Execution: The flow uses a separate, more permissive tool allowlist for the /issue-pr skill invocation.
• Success Criteria: Success is determined by re-checking for the existence of a PR, rather than the exit code of the tool invocation.

Global Constraints for Implementation

• Style: Use Black (256 chars) and Flake8 (250 chars) line lengths. Use British English (en-gb) for all prose and docstrings.
• Naming: Use lower_case_with_underscores for variables.
• Testing: 100% docstring coverage is required. All new code must have unit tests. tools/triage_daemon.py must have no dependency on apps/predbat.

Predbat is a home battery automation program designed to minimize energy costs by automatically managing battery charging and discharging cycles.

Core Functionality:

• Automated Planning: Runs every 5 minutes and forecasts energy needs (default 48 hours via forecast_hours). It generates a plan (typically covering 24 hours after the first charge slot via forecast_plan_hours) to optimize cost.
• Forecasting: Combines solar production forecasts (from Solcast, Open-Meteo, or Forecast.solar) with historical energy usage to predict house load and solar generation.
• Inverter Control: Automatically programs both Hybrid and AC-coupled inverters with appropriate charging and discharging controls.
• Cost Optimization: Uses energy pricing data (manual, Octopus Energy API/Home Assistant, Kraken, or spot-rate sensors like Energidataservice/Strømligning) to decide when to import/export energy.
• Load Prediction: Predicts consumption using historical data or a trained neural network that learns time-of-day and day-of-week patterns.

Key Features:

• Export Management: Supports automatic planning of export slots to discharge the battery when export rates are high.
• Load Management: Can manage EV charging or Solar Diverters, accounting for these loads in the house prediction.
• VPP Support: Supports Axle VPP export events by standing aside during events.
• Scenario Analysis: Includes tools to compare tariffs (compare.md) and project annual savings/payback via 'What If' scenarios (annual-prediction.md).

A critical distinction in Predbat is between the Plan Metric (the actual yardstick used to judge the quality of a full plan) and the Optimizer Ranking Score (the internal, adjusted score used by individual optimizers to pick a candidate within a single window).

Why they differ

Optimizers like optimise_charge_limit and optimise_export apply internal adjustments to their scores to break ties or favor specific behaviors. These adjustments are not present in the final plan metric.

Common internal adjustments include:

• Export Commitment Bonus: Applied to in-progress export commitments.
• Tie-break weightings: Small values like -0.002 for off or -0.001 for 0% to prefer certain states in a tie.
• Charge Limit adjustments: Specific weights (e.g., -0.003, -0.002, -0.001) and a metric_min_improvement factor.

The Risk

Because the internal ranking score is not identical to the plan metric, an optimizer might select a candidate that has a higher internal score but actually results in a lower total plan metric. The monotonic pass (via keep_window_change_if_improved) is designed to catch and block these regressions.

The AlphaESS control system uses a specific dictionary structure to represent battery schedules. This shape is used by both the control entities (for publishing to Home Assistant) and the payload builder (for writing to the inverter).

Schedule Shape:

• reserve: int (Battery reserve percentage)
• charge: dict
  • enable: bool
  • soc: int (Target State of Charge)
  • power: int (Power in Watts)
  • start: str (Format HH:MM:SS)
  • end: str (Format HH:MM:SS)
• export: dict (Same structure as charge)

Note: Time strings must strictly follow the HH:MM:SS format to match the INVERTER_DEF requirements; otherwise, Predbat may replace them with dummy values.

{
    "reserve": int,
    "charge": {
        "enable": bool, 
        "soc": int, 
        "power": int, 
        "start": "HH:MM:SS", 
        "end": "HH:MM:SS"
    }, 
    "export": {
        "enable": bool, 
        "soc": int, 
        "power": int, 
        "start": "HH:MM:SS", 
        "end": "HH:MM:SS"
    }
}

The triage_daemon uses a permission model to define which tools are allowed or disallowed during different execution modes. There are two primary modes:

1. Read-only Triage: Uses ALLOWED_TOOLS and DISALLOWED_TOOLS. This mode is restricted to investigating issues, searching for duplicates, and posting triage comments without modifying the repository state.
2. Push/PR Creation (/issue-pr): Uses ALLOWED_TOOLS_PR and DISALLOWED_TOOLS_PR. This mode is a superset of the triage mode, adding capabilities to git add, git commit, git push, gh pr create, and running ./run_pre_commit.

Security Boundary: The model follows a "deny wins over allow" principle. Even if a broad permission like Bash(gh *) is allowed, specific dangerous subcommands (like gh pr merge* or gh auth*) are explicitly listed in the DISALLOWED_TOOLS sets to prevent unauthorized administrative actions.

Predbat configuration items support several types of values:

• Fixed Values: Direct assignment of a value.
  • template: true
• Home Assistant Entities: Assigning a string that matches a sensor name.
  • battery_temperature_history: sensor.givtcp_battery_stack_1_bms_temperature
• Lists: A collection of values.
  • `givtcp_rest:
    • 'http://homeassistant.local:6345'
    • 'http://homeassistant.local:6346'`
• Variable Expansion: Using a variable defined earlier in the file (e.g., {dno_region}) within a string.
• Regular Expressions: Using the re:(...) prefix to match Home Assistant entity names that follow a pattern rather than a fixed name. This is useful for integrations like Solcast or Octopus where IDs change.

# Variable expansion example
dno_region: "A"
compare_list:
  - id: 'igo_fixed'
    rates_import_octopus_url: '...-{dno_region}/standard-unit-rates/'

# Regular expression example
metric_octopus_import: 're:(sensor.(octopus_energy_| )electricity_[0-9a-z]+_[0-9a-z]+_current_rate)'
pv_forecast_d3: re:(sensor.(solcast_|)(pv_forecast_| )forecast_(day_3|d3))