Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
bd5c6d8
feat(tariff): add the tariff adapters, price formula and price servic…
claude Oct 17, 2026
39ed082
fix(tariff): keep good prices on empty, partial and overlapping fetch…
claude Oct 17, 2026
8ba1088
fix(tariff): Nord Pool delivery days in the CET zone, currency guard,…
claude Oct 17, 2026
1a83df2
fix(tariff): spot-only warnings, request-field validation, docs and n…
claude Oct 17, 2026
a49dd6b
Merge branch 'phase-4/b-storage' into phase-4/c-tariff
claude Oct 17, 2026
56b4b17
Merge branch 'phase-4/c-tariff' into phase-4/f-planner
claude Oct 23, 2026
964ed11
feat(planner): add the LP model, the heuristic fallback and property …
claude Oct 23, 2026
09b0e14
feat(planner): add the HiGHS planner with heuristic fallback and expl…
claude Oct 23, 2026
6c48143
docs: STATUS and plan deviations for PR 4-F WP8 (planner), benchmark …
claude Oct 23, 2026
240dc46
docs: wrap a long line in the architecture planner note
claude Oct 23, 2026
687993c
wip(app): planner runtime wiring, work in progress (WP9)
claude Oct 24, 2026
d70aff7
feat(app): run the planner every 15 minutes and hand its plan to the …
claude Oct 24, 2026
3cc934c
docs: STATUS and plan deviations for PR 4-F WP9 (planner runtime)
claude Oct 24, 2026
5349b3b
fix(controller): keep the user's battery target a floor under a plan;…
claude Oct 24, 2026
6dcc168
fix(app): no real solver inside the 0.1 s run-timeout test (review B2)
claude Oct 24, 2026
2f05c78
fix(planner): review fixes - device budget on P50 plus overflow, no g…
claude Oct 24, 2026
f74cf24
fix(app): plan and status answer 409 without a planner; staleness fro…
claude Oct 24, 2026
c4004a8
docs: STATUS and plan deviations for the PR 4-F review fixes
claude Oct 24, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions addon/suncore/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,19 @@ run against real hardware yet; the guide lists what is unverified.

Change options on the app's **Configuration** tab and restart the app.

## Expert settings (environment variables)

Some timing and budget settings of the price service and the planner are not app options
(keep the Configuration tab simple). Experts can set them as environment variables of the container:

| Variable | Default | Description |
|---|---|---|
| `SUNCORE_TARIFF_REFRESH_INTERVAL_S` | `3600` | Spacing of the regular price refresh in seconds (60–86400). |
| `SUNCORE_TARIFF_TOMORROW_AFTER` | `13:00` | Local time from which tomorrow's day-ahead prices are expected. |
| `SUNCORE_TARIFF_TOMORROW_POLL_S` | `900` | Spacing of the asks between that time and the arrival of tomorrow's prices. |
| `SUNCORE_PLANNER_BUDGET_S` | `8` | Time budget of one planner run in seconds (0.5–120); the rule-based plan covers a miss. |
| `SUNCORE_PLANNER_MIP_GAP` | `0.01` | Accepted distance from the optimum of the planner's solver (0–0.5). |

## Demo mode

With `demo_mode` switched on, SunCore does not read your entities. A
Expand Down
13 changes: 13 additions & 0 deletions addon/suncore_beta/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,19 @@ run against real hardware yet; the guide lists what is unverified.

Change options on the app's **Configuration** tab and restart the app.

## Expert settings (environment variables)

Some timing and budget settings of the price service and the planner are not app options
(keep the Configuration tab simple). Experts can set them as environment variables of the container:

| Variable | Default | Description |
|---|---|---|
| `SUNCORE_TARIFF_REFRESH_INTERVAL_S` | `3600` | Spacing of the regular price refresh in seconds (60–86400). |
| `SUNCORE_TARIFF_TOMORROW_AFTER` | `13:00` | Local time from which tomorrow's day-ahead prices are expected. |
| `SUNCORE_TARIFF_TOMORROW_POLL_S` | `900` | Spacing of the asks between that time and the arrival of tomorrow's prices. |
| `SUNCORE_PLANNER_BUDGET_S` | `8` | Time budget of one planner run in seconds (0.5–120); the rule-based plan covers a miss. |
| `SUNCORE_PLANNER_MIP_GAP` | `0.01` | Accepted distance from the optimum of the planner's solver (0–0.5). |

## Demo mode

With `demo_mode` switched on, SunCore does not read your entities. A
Expand Down
136 changes: 128 additions & 8 deletions docs/STATUS.md

Large diffs are not rendered by default.

13 changes: 8 additions & 5 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,9 +68,7 @@ flowchart TB
api --> storage
ha --> core
forecast --> ha
tariff --> ha
planner --> forecast
planner --> tariff
tariff --> templates
planner --> core
controller --> core
controller --> devices
Expand All @@ -87,6 +85,7 @@ flowchart TB
sched --> planner
sched --> controller
sched --> forecast
sched --> tariff
```

Dependency rule: arrows point inward to `core/`; `core/` imports nothing
Expand All @@ -101,7 +100,7 @@ Package map (ADR-0001):
| `suncore/core` | Domain model: `Site`, `Asset` (grid, pv, battery, device), `Signal` (typed time series with unit and quality), `Capability`, `Plan`, `Intent`, `Decision`, `Reason`, units and sign conventions | stdlib, pydantic |
| `suncore/ha` | `HAConnection` (Supervisor or Direct transport), entity subscription with staleness tracking, service calls with read-back, write rate limiter, registry queries, MQTT discovery publisher | core, aiohttp |
| `suncore/forecast` | Adapter protocol + Solcast, Forecast.Solar, Open-Meteo, generic-attribute, built-in model; blending by measured skill; bias calibration; load profiles | core, ha, templates |
| `suncore/tariff` | Import/export price sources (Tibber, Nord Pool, ENTSO-E/EPEX via HACS, fixed, HT/NT), price formula, region profiles, negative-price rules | core, ha, templates |
| `suncore/tariff` | Import/export price sources (Tibber, Nord Pool, ENTSO-E/EPEX via HACS, fixed, HT/NT), price formula, region profiles, negative-price rules (Home Assistant reaches it through an injected action caller and entity reader wired in `suncore/app/adapters.py`) | core, templates |
| `suncore/planner` | Model builder, HiGHS solver worker, heuristic fallback, plan explanation, what-if | core, highspy, numpy |
| `suncore/controller` | Surplus computation, priority allocation, hysteresis state machines, peak shaving, export limiting, §14a limit | core |
| `suncore/safety` | Invariant checks, operating modes, override detection, watchdogs, fail-safe transitions; the only caller of actuators | core, devices |
Expand Down Expand Up @@ -143,7 +142,11 @@ convert at the boundary (e.g. Kostal reports battery positive = discharging).
## 4. Planner, controller, safety in time

The planner arrives in Phase 4; until then the controller consumes `Plan.default()`, which allows
everything. The control layer (Phase 3) is composed in one place, `suncore/app/control.py`
everything. Phase 4 WP8 added `suncore/planner` (`inputs.py` → `model.py` LP for HiGHS behind a
`SolverBackend` protocol → `run.py` with the heuristic fallback and `explain.py` reasons); it
depends on `core` only: the scheduler (WP9) collects prices, forecasts and the risk targets and
hands them over through `build_inputs`, and runs `run()` in a worker thread.
The control layer (Phase 3) is composed in one place, `suncore/app/control.py`
(`ControlStack`): entity cache, one driver and one power model per device, the controller
(`suncore/controller`), the safety gate with its watchdog (`suncore/safety`) and the connection
life cycle. The runtime, the demo and the simulator all use this same stack; only the connection
Expand Down
114 changes: 114 additions & 0 deletions docs/plans/phase-4.md
Original file line number Diff line number Diff line change
Expand Up @@ -394,6 +394,39 @@ shadow and assisted run is the acceptance test.
nicht ausführbar. Reicht das, oder soll eine generische „Zwangsladen“-Entität bzw. später ein
eigener §3.4-ADR kommen?

### Offene Fragen aus PR 4-C (an den Maintainer)

1. **Zusätzliche Tarif-Einstellungen:** Damit Nord Pool (`config_entry`, `areas`), Octopus (zwei
Ereignis-Entitäten), mehrere Tibber-Häuser und ENTSO-E mit eigener Preisformel funktionieren,
bekommt `tariff.import` vier optionale Felder: `role_entities`, `action_params`, `series_key`,
`price_includes` (Aussage des Nutzers, ob die Quelle schon Steuern/Netzentgelte enthält).
Alte Dokumente bleiben gültig. Einverstanden?
2. **Nord Pool `config_entry`:** Die ID des Konfigurationseintrags muss der Nutzer eintragen
(Entwicklerwerkzeuge → Aktionen zeigt sie). Ob SunCore sie aus der Entity-Registry lesen kann,
ist nicht verifiziert (`UNVERIFIED`). Reicht die manuelle Eingabe für Phase 4?
3. **Negativpreis-Regel bei All-in-Quellen (Tibber):** Der Spotpreis ist nicht bekannt; als Ersatz
gilt der Endpreis (Import) < 0. Das markiert weniger Viertelstunden als die echten
Negativ-Spot-Stunden, die Einspeisung wird dann dort noch vergütet gerechnet (`UNVERIFIED`
gegen die Praxis). Alternative: zusätzlich die Spot-Quelle (z. B. EPEX Spot Marktpreis) als
Referenz konfigurieren (Phase 5). Einverstanden mit dem Ersatzwert?
4. **`curtailment_required`:** ändert in Phase 4 keinen Preis (Abregelung ist Sache von
Planer/Regler, nicht des Preises). Nur `no_remuneration` setzt den Einspeisepreis auf 0.
5. **Dynamische Einspeisepreise:** keine der verifizierten Quellen liefert welche; der Einspeisepreis
kommt aus `tariff.export` (fest, gestaffelt, keiner). Octopus-Export-Entitäten sind nicht
angebunden.
6. **HT/NT-Preis:** pro Viertelstunde zum Beginn der Viertelstunde; Fensterkanten, die nicht auf
:00/:15/:30/:45 liegen, wirken ab der nächsten Viertelstunde.
7. **Veröffentlichung der Preise für morgen:** Standard 13:00 Ortszeit, danach alle 15 min bis die
Preise da sind (`UNVERIFIED`; Experten-Umgebungsvariablen `SUNCORE_TARIFF_TOMORROW_AFTER`,
`SUNCORE_TARIFF_TOMORROW_POLL_S`, `SUNCORE_TARIFF_REFRESH_INTERVAL_S`, keine App-Optionen,
dokumentiert in beiden `DOCS.md`). Bitte an deinem System beobachten.
8. **§51 EEG und Inbetriebnahmedatum:** Ob bei negativen Preisen vergütet wird, hängt vom
Inbetriebnahmedatum der Anlage ab. Die Regel kommt heute nur aus dem Regionsprofil (`de`:
`no_remuneration`). Soll es später (Phase 5) pro Anlage eine Abschaltmöglichkeit geben
(„diese Anlage wird auch bei negativen Preisen vergütet“)?
9. **Namensabgrenzung:** `PriceFormula.apply` heißt für Aufrufer jetzt `end_price` (der Grenztest
reserviert `.apply(` für den Geräteschreibpfad); `apply` bleibt als Alias.

## Deviations during implementation

- Phase 4 is split into the stacked PRs 4-A…4-I (§3) instead of one PR.
Expand Down Expand Up @@ -451,6 +484,87 @@ shadow and assisted run is the acceptance test.
sensors (`mean`, W); quarter hours with an unmeasured device are left out of a day type's
profile once it has 7 fully measured days, before that they are kept and flagged.
- The temperature term shifts a forecast day only with ≥ 20 hours of temperatures (m5).
- PR 4-F, WP8 (planner):
- **Flows**: PV serves the base load first; devices draw only the PV surplus over the base
load and the battery discharges only for the base load (never for export, which ADR-0013
limits cannot express). "SunCore never imports for a device" therefore holds structurally in
the LP, not through a price cap; the automatic device value is the export price + 0.01, an
explicit value is capped at `max(import price, export price + 0.01)`.
- **No binaries** in Phase 4: with that flow split and free curtailment, simultaneous charge
and discharge cannot gain at negative prices; `SolverStats.n_binaries = 0`, the backend
accepts integer columns for Phase 6 device models.
- **Morning buffer**: a soft SoC target at the earliest time a battery-first day reaches it on
P50 (or, when PV cannot, the highest SoC such a day reaches before the coming sunset), plus
"battery first" before that time (surplus beyond the battery's charge limit may go elsewhere,
more costs the buffer penalty). It never makes the plan hold energy or buy it from the grid by
itself. `priority_until_soc_pct` = the buffer until the plan reaches it, at most until the
buffer's goal slot.
- **Device budget**: before each evening/user target the devices may only take what a
battery-first day **on P50** could spare above the target, plus the PV surplus such a day
cannot absorb (charge-power and SoC limits) up to the target. The first version used PV at
the risk quantile; the PR review replaced it (lead decision D4, plan §0: caution enters only
through the WP7 targets). Consequence, measured with a rolling hourly replay of
`forecast_too_optimistic` (P10 = 0.25 × P50): the evening target is met when PV comes in at
≥ 0.5 × P50 all day; at 0.4 × P50 it is missed by about 5 %-points, because the WP7 morning
buffer's margin does not count the consumers (open question for WP7/the maintainer).
- **Targets** are soft (penalty per kWh of shortfall: buffer `2m + 0.5`, evening/user `10m + 1`,
`m` = largest absolute price), so the model is always feasible and a shortfall is explained
(`planner.battery.target_shortfall`); "relaxed targets" in the fallback chain are therefore
built in. A live SoC below the reserve or above max SoC gets a penalised slack instead of an
infeasible model.
- **Terminal value** of stored energy: `median(import) × discharge efficiency − degradation/2`;
degradation is charged half on charge, half on discharge (= the configured cost per charged
kWh over a cycle).
- **Prices**: missing prices (tomorrow before publication) are filled with the median and
reported; grid charging needs a known price; `spot_only` without a formula and no prices at
all plan in `flat` mode (self-sufficiency only, nominal import price 1, export from the tariff
configuration). On a tariff whose price varies, grid charging needs the spread rule against the
best known later price; on a flat tariff the policy alone decides and the LP charges only when
a target needs it.
- **Inputs are frozen dataclasses**, not Pydantic models (ADR-0003 says "typed Pydantic
inputs"): built once per run by a pure function, validated in `__post_init__`; the outputs are
the Pydantic plan contracts.
- **Plan v2 additions** (additive): `BatteryBand.grid_charge_max_w` / `discharge_lock`
(ADR-0013, moved from 4-G to WP8; the controller ignores them until 4-G) and
`IntervalFlows.devices_w` / `curtail_w`.
- `charge_from_surplus = False` only where the plan gives devices the surplus while no battery
target binds; the Phase 3 controller already reads this flag once a plan is wired (WP9).
- PR 4-F review (2026-10-24), lead decisions by the plan's defaults:
- **D1** `goals.battery_target` stays a floor in the controller under a plan:
`battery_share_available` keeps the battery first while the live SoC is unknown or below the
target, after the band's priority check (property: below `max(priority, target)` a plan never
gives consumers more than Phase 3).
- **D2** no grid charging without a known price: flat mode and unpublished prices give an
allowance of 0, also under a schedule-only policy.
- **D3** where the region's negative-price rule zeroed the export price (proxy: export price
≤ 0 while the known import price is negative), export costs 0.001/kWh more than curtailment,
so the plan curtails (informational until Phase 6); `planner.export.negative_price_avoided`
only where export is ≈ 0 or at most half the surplus.
- **D4** device budget on P50 plus overflow (above).
- Further: an early-charge tie-breaker (0.0001/kWh falling over the horizon) removes the
late-charging degeneracy; an evening target at max SoC is due at the start of the evening
deficit; the morning-buffer reason names the reachable SoC and `priority_until_soc_pct` ends
with the buffer's goal slot; without a load forecast the plan uses a flat 500 W (or a recent
mean passed by the runtime) and plans no consumers; median-filled prices are flagged
(`IntervalPrices.estimated`, additive) and never cited as "later price"; `violations()`
checks the flow split and the import limit; a slot the previous plan throttled stays tight
within 3 %-points / 100 Wh (band hysteresis); without a planner battery
`PlanInterval.battery` is `None` (contract: now optional) and the goal rules stay in charge;
`GET /api/v1/plan` and `/plan/status` answer 409 without a planner; a plan's age counts from
its hand-over; HiGHS releases the GIL while solving (measured: the event loop's largest gap
stays far below the solve time, slow test), `UNVERIFIED` on aarch64.
- WP4: ENTSO-E and EPEX Spot get two templates each where the unit or the price content differs
(`entsoe.price`/`_mwh`, `epex_spot.total_price`/`market_price`): a template holds one value unit
and one `price_includes`. Octopus is included (its source was verified in 4-A).
- WP9: the solve runs in a daemon thread (`run_in_daemon_thread`), not `asyncio.to_thread`: an
abandoned or hanging solver call must not keep the default executor (and with it the process
shutdown) waiting; a hung thread is never joined and blocks only further planner runs.
- WP9: a plan older than 2 h is *stale* and the controller gets `Plan.default()` from then on
(instead of following it until its intervals run out after up to 48 h): stale or missing plan =
Phase 3 behaviour. The API still serves it, flagged. Deviation thresholds (10 %-points SoC,
1500 W for 30 min) are the documented first values, not tuned.
- WP9: the controller applies a plan's battery band only while an interval covers `now`, and judges
`priority_until_soc_pct` against the live SoC.

## 7. Out of scope for Phase 4

Expand Down
9 changes: 9 additions & 0 deletions docs/research/integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,15 @@ exists but is undocumented on the page.
The action returns the undivided MWh value; the adapter divides by 1000.
The values are the day-ahead market price per area; VAT, grid fees and levies are not part
of them (no such field in the source).
- **Meaning of `date` (zone)**: the action passes `date` as `YYYY-MM-DD` to the library
(`home-assistant/core@5cfe9aad7cb428c2c2ebb449719ae81976780de1`
`homeassistant/components/nordpool/services.py:112-125`: `datetime.combine(asked_date,
dt_util.utcnow().time())`), which only formats it with `strftime("%Y-%m-%d")` as the `date`
query parameter of Nord Pool's `DayAheadPrices` (`pynordpool 0.4.0` `__init__.py:106-127`) and
keys the raw response by `deliveryDateCET` (`__init__.py:102`). So `date` is read as the **CET
delivery day** (Central European rules, i.e. `Europe/Berlin`), not the Home Assistant day; the
template sets `date_tz: Europe/Berlin`. Read from source only, the query semantics of the
Nord Pool API itself were not seen live (`UNVERIFIED`).
- **Resolution**: slot length = `end - start` per entry (the sensors compute
`resolution = entry.end - entry.start`, `sensor.py:58`), 15 or 60 minutes; a
coordinator tick every 15 minutes (`coordinator.py:57-73`). The adapter must not
Expand Down
9 changes: 8 additions & 1 deletion docs/user/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,14 @@ a template only tested in the simulator has never run against real hardware.

| Id | Kind | Name | Integration / platforms | Capabilities | Tested with | Unverified |
|---|---|---|---|---|---|---|
| `tibber.price` | tariff | Tibber dynamic price | `tibber` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `entsoe.price` | tariff | ENTSO-E day-ahead price (kWh) | `entsoe` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `entsoe.price_mwh` | tariff | ENTSO-E day-ahead price (MWh scale) | `entsoe` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `epex_spot.market_price` | tariff | EPEX Spot market price | `epex_spot` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `epex_spot.total_price` | tariff | EPEX Spot total price | `epex_spot` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `generic.price_list` | tariff | Generic price list (sensor attribute) | any | `price_curve`, `price_now` | not tested on hardware | 3 |
| `nordpool.price` | tariff | Nord Pool day-ahead price | `nordpool` | `price_curve`, `price_now` | not tested on hardware | 6 |
| `octopus_energy.rates` | tariff | Octopus Energy rates | `octopus_energy` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `tibber.price` | tariff | Tibber dynamic price | `tibber` | `price_curve`, `price_now` | not tested on hardware | 6 |

## PV forecasts

Expand Down
Loading
Loading