Annual electricity cost prediction tool (engine, CLI and web UI)

[springfall2008]

Adds an annual electricity cost prediction tool: a projection of a full year of household costs, run through Predbat's real planning engine rather than a simplified model. Available both as a CLI and as a new Annual tab in the web UI.

It answers "what would this system actually save me?" under three scenarios — no PV/battery, PV and battery on a dumb timer, and PV and battery with Predbat — month by month.

How it works

For each month, a couple of days are sampled (configurable), stratified by irradiance percentile so the sample represents the month's real spread of solar rather than an average day. Each sampled day is planned and costed, then projected across the month.

• Solar comes from Open-Meteo's ERA5 archive, converted GTI→kW with the SAPM/PVWatts cell-temperature model. Predbat plans against the forecast archive and is billed against actuals, so it never gets perfect foresight.
• Load is either a synthetic profile (annual kWh + night/day/flat shape) or the user's real Octopus consumption history.
• Car charging is episodic, not smeared: weekly sessions, with each sampled day planned both with and without a session and the results blended by frequency.
• Tariffs come from basic rates or Octopus URLs, with a curated dropdown merged from the user's own Compare list.

Costs use the same battery-value correction as Compare (metric_end − metric_start), so a scenario cannot look cheap by finishing on an empty battery.

Web UI

The Annual tab prefills from whatever the live instance has configured — read via the args dictionary, never by re-reading apps.yaml, which may not exist — and falls back to a typical UK system for the rest, so it works on an unconfigured instance and eventually for unregistered Predbat.com visitors. Runs happen in a subprocess with a progress bar; the last five runs are stored and switchable.

Debug mode

An opt-in flag retains each sampled day's plan JSON inside the results document (no extra files), viewable in the browser through Predbat's existing client-side plan renderer — same columns and debug toggle as the live plan page. Every scenario and both car legs are kept, so a suspicious monthly figure can be traced to the plan that produced it.

Tariffs with no history

A newly launched tariff has no rates for the replayed year. Octopus returns an empty result rather than an error, and an empty export download was previously treated as "export unpaid" — which would have produced a complete, plausible year with export silently priced at zero.

Each side now falls back to the tariff's current rates repeated across the month, keyed by local minute-of-day so an evening peak does not slide an hour across DST. The pattern is refused entirely unless it covers a full local day, so an inadequate pattern fails loudly instead of leaving minutes at 0p. Months priced this way are marked and named in a caveat. Adds Prime Outgoing export pairings alongside the existing Fixed ones (verified live across four DNO regions).

Honesty about the numbers

The tool reports what it cannot know, rather than presenting a confident wrong figure:

• A month with no rate data, no usable weather, or all-failed samples is unavailable and excluded from the annual total — never counted as a free month.
• export_credit_p_estimate is flagged as already inside cost_p; adding them double-counts.
• Self-consumption is deliberately not reported: it cannot be derived from these totals, since pv_generated − export assumes all export comes from PV, which is false whenever the battery exports grid-charged energy.
• predbat_vs_baseline_p is documented as easier to beat on half-hourly tariffs than banded ones, because of how the baseline window is chosen.

Testing

Full suite green. New tests cover the solar model, load profiles, weather sampling, tariff handling, the results assembly, the CLI, the web page, the job runner, the run store, and an end-to-end integration run.

Several defects were caught and fixed during review that would each have produced plausible-but-wrong money figures — among them a standing charge leaking into every billed cost, an open-ended tariff row leaving 47 of 48 daily slots priced at 0p, and rate-cache keys without tariff identity, which made a second run return the first tariff's numbers.

Known limitations (documented, not hidden)

• The Open-Meteo forecast archive only reaches back to ~2021; earlier years plan against actuals and are flagged as likely overstating savings.
• The current-rates fallback repeats a single daily shape — correct for fixed and banded tariffs, but it would flatter Predbat on a genuinely dynamic one. Not reachable today, as every dynamic tariff in the catalogue has history.
• Pre-existing and unrelated: chart axis text does not follow dark mode, and fetch_month anchors to UTC, which leaves 1 January unpriced in UTC+ timezones (no effect at the default Europe/London).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Copilot reviewed 47 out of 49 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

apps/predbat/annual_store.py:66

• build_label() can emit a label with no solar information when config['solar'] is present but the arrays sum to 0 kWp (e.g. missing/zero kwp values). That produces confusing run labels like “9.5kWh battery · Agile” even though a solar section exists. Consider explicitly adding “no solar” when the computed total is 0.

    solar = config.get("solar")
    if solar:
        total_kwp = sum(array.get("kwp", 0) for array in solar if isinstance(array, dict))
        if total_kwp:
            parts.append("{}kWp".format(round(total_kwp, 2)))
    else:
        parts.append("no solar")

apps/predbat/annual_store.py:17

• MAX_RUNS is set to 20, but the PR description says “the last five runs are stored and switchable.” Either update the description/docs to match 20, or reduce MAX_RUNS to 5 to match the stated behaviour (this also affects Storage growth for debug runs, even with plan-splitting).

MAX_RUNS = 20