diff --git a/addon/suncore/DOCS.md b/addon/suncore/DOCS.md index 3a5ad2e..e51c707 100644 --- a/addon/suncore/DOCS.md +++ b/addon/suncore/DOCS.md @@ -105,6 +105,17 @@ 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) + +Three timing settings of the price service 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. | + ## Demo mode With `demo_mode` switched on, SunCore does not read your entities. A diff --git a/addon/suncore_beta/DOCS.md b/addon/suncore_beta/DOCS.md index 36975b2..8bae12e 100644 --- a/addon/suncore_beta/DOCS.md +++ b/addon/suncore_beta/DOCS.md @@ -108,6 +108,17 @@ 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) + +Three timing settings of the price service 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. | + ## Demo mode With `demo_mode` switched on, SunCore does not read your entities. A diff --git a/docs/STATUS.md b/docs/STATUS.md index b4ff05b..a9ea0b1 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -3,9 +3,10 @@ Read this first in every session, then `CLAUDE.md` (once it exists) and the ADRs relevant to your task. Keep it short; history lives in git. -**Last update:** 2026-10-17 · **Phase:** 4 in progress – PR 4-A contracts, PR 4-B storage; Phase 3 (3-A -`phase-3/a-safety`, 3-B `phase-3/b-controller`, 3-C `phase-3/c-ui`) implemented, waiting for the -maintainer's shadow test · **Branch:** `phase-4/b-storage` (stacked on `claude/zealous-mayer-j5oda9`) +**Last update:** 2026-10-17 · **Phase:** 4 in progress – PR 4-A contracts, 4-B storage, 4-C +tariffs; Phase 3 (3-A `phase-3/a-safety`, 3-B `phase-3/b-controller`, 3-C `phase-3/c-ui`) +implemented, waiting for the maintainer's shadow test · **Branch:** `phase-4/c-tariff` (stacked +on `phase-4/b-storage`) ## Done @@ -338,6 +339,33 @@ maintainer's shadow test · **Branch:** `phase-4/b-storage` (stacked on `claude/ - **ADR-0013 must be accepted before WP10** (4-G). Its contract changes (`BatteryAction` `None` = baseline, `BatteryBand.grid_charge_max_w`/`discharge_lock`, `effective_reserve_pct`, `battery_identity`) land at the start of 4-G, after the maintainer accepted it. +- **PR 4-C (WP4, branch `phase-4/c-tariff`)**: `suncore/tariff/` - a template-driven price adapter + (`engine.py`: action or attribute source, list or mapping shape, per-MWh conversion, native grid + from `end - start` or the timestamp spacing, 15/60-minute mixes as segments, gaps `None`, DST + safe; a kWh/MWh unit mismatch between sensor and template is refused), fixed and HT/NT sources, + `PriceFormula` on spot-only sources only, export fixed/tiered/none, the region's + `no_remuneration` rule (export price 0 in slots with a negative spot price; for all-in sources the + import end price is the proxy), `TariffService` (refresh hourly, on entity change for attribute + sources, every 15 min from 13:00 local until tomorrow's prices arrive, back-off after failures, + throttled calls are not failures, good data is never replaced by an empty or failed fetch, + prices stored in `timeseries.db`) and `GET /api/v1/prices?hours=48`. Templates `tibber.price` + (updated), `nordpool.price`, `entsoe.price` (+`_mwh`), `epex_spot.total_price`/`market_price`, + `octopus_energy.rates`, `generic.price_list`; schema changes are additive (templates README + changelog). Wiring in `suncore/app/adapters.py`; demo and simulator: the fake answers + `tibber.get_prices` through the same template path, scenario `negative_prices`. + `PriceFormula.end_price` is the 4-A `apply` under a name the actuator boundary test does not + reserve. `UNVERIFIED`: see the price rows in the table below. + Review fixes: a failing attribute source backs off; a fetch without a known price fails and keeps + the old data (unknown slots are carried over, `quality.carried_slots`); the old tail never overlaps + new data; Nord Pool `date` is the CET delivery day (`date_tz`, research note in + `research/integrations.md`) and "tomorrow covered" ends at the market's day end; a source in + another currency than the region is refused; `segments_from_points` (4-A) treats a multiple-step + hole at the list end as a gap. A spot-only price without a formula is a system-check warning and + `GET /api/v1/prices` says `formula_missing: true` with the top-level `price_includes`. + **For 4-F: the planner must refuse `spot_only` import prices without a formula (it must not + plan with bare market prices).** Known: the error argument `available` of + `tariff.error.ambiguous_series` carries the home names/areas of the response (shown to the user, + they are needed to choose one). - Maintainer questions from 4-A: plan §6 "Offene Fragen aus PR 4-A" (grid-charge schedule precedence, VAT on negative spot prices, export tiers, grid charging on the Kostal). @@ -533,6 +561,7 @@ maintainer's shadow test · **Branch:** `phase-4/b-storage` (stacked on `claude/ | Supervisor proxy forwards `recorder/statistics_during_period` (the 4-B rebuild logs a warning and retries) | `suncore/ha/statistics.py` | first run on HA OS | | `change`/`sum` rows of real energy counters (the rebuild reads them as verified from source, not tested against live counters); `backup_exclude` accepts the glob `timeseries.db.corrupt*` | `suncore/ha/statistics.py`, `addon/*/config.yaml` | maintainer's HA with an energy counter; a backup on HA OS | | Publication time of next-day prices (Tibber, Nord Pool, ENTSO-E, EPEX) | `research/integrations.md` | observe on the maintainer's HA | +| Nord Pool `config_entry` id source, sensor translation keys, publication time; Octopus/ENTSO-E/EPEX entity matchers (platform and unit only, no translation keys); `start`/`end` sent to `tibber.get_prices` as ISO with offset; negative-price rule proxy for all-in sources | `templates/tariff/*.yaml`, `suncore/tariff/pricing.py` | live check on a system with the integration | | VAT applied to negative spot prices | `suncore/core/tariff.py` | maintainer's bill / supplier terms | | KNN load model performance on aarch64 | plan WP12 | CI arm runner benchmark | | Energy colour variable names (`--energy-*`) | `frontend/src/app.css` | read HA frontend source | diff --git a/docs/architecture.md b/docs/architecture.md index 77c9332..013e0b8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -68,7 +68,7 @@ flowchart TB api --> storage ha --> core forecast --> ha - tariff --> ha + tariff --> templates planner --> forecast planner --> tariff planner --> core @@ -101,7 +101,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 | diff --git a/docs/plans/phase-4.md b/docs/plans/phase-4.md index 0fed4f4..65e40f7 100644 --- a/docs/plans/phase-4.md +++ b/docs/plans/phase-4.md @@ -392,6 +392,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. @@ -403,6 +436,9 @@ shadow and assisted run is the acceptance test. page was unreachable. The built-in PV fallback stays opt-in and off. - `BatteryAction` is part of the 4-A contracts but rejected by the gate until WP10 (ADR-0011 addendum); its semantics are proposed in ADR-0013. +- 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). ## 7. Out of scope for Phase 4 diff --git a/docs/research/integrations.md b/docs/research/integrations.md index c03ad92..a127b89 100644 --- a/docs/research/integrations.md +++ b/docs/research/integrations.md @@ -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 diff --git a/docs/user/compatibility.md b/docs/user/compatibility.md index 1725297..8535b12 100644 --- a/docs/user/compatibility.md +++ b/docs/user/compatibility.md @@ -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 diff --git a/frontend/src/lib/api/openapi.json b/frontend/src/lib/api/openapi.json index ae5e932..b9584b0 100644 --- a/frontend/src/lib/api/openapi.json +++ b/frontend/src/lib/api/openapi.json @@ -1,10 +1,64 @@ { "components": { "schemas": { + "ActionParam": { + "additionalProperties": false, + "description": "A field of the action's request that the user's tariff configuration supplies.\n\nThe value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the\nNord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value.", + "properties": { + "description": { + "maxLength": 120, + "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", + "title": "Description", + "type": "string" + }, + "name": { + "maxLength": 200, + "minLength": 1, + "title": "Name", + "type": "string" + }, + "required": { + "default": true, + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "name", + "description" + ], + "title": "ActionParam", + "type": "object" + }, "ActionSeries": { "additionalProperties": false, "description": "Series returned by a read-only action (``return_response`` is implied).", "properties": { + "date_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Date Field" + }, + "date_tz": { + "anyOf": [ + { + "pattern": "^[A-Za-z_]+(/[A-Za-z_+\\-0-9]+){1,2}$", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Date Tz" + }, "domain": { "maxLength": 48, "pattern": "^[a-z][a-z0-9_]*$", @@ -33,9 +87,18 @@ "title": "Max Horizon H", "type": "integer" }, + "params": { + "default": [], + "items": { + "$ref": "#/components/schemas/ActionParam" + }, + "maxItems": 8, + "title": "Params", + "type": "array" + }, "response_path": { "maxLength": 200, - "pattern": "^[A-Za-z0-9_]+(\\.([A-Za-z0-9_]+|\\*))*$", + "pattern": "^(\\*|[A-Za-z0-9_]+)(\\.([A-Za-z0-9_]+|\\*))*$", "title": "Response Path", "type": "string" }, @@ -3107,6 +3170,33 @@ "additionalProperties": false, "description": "How the price of imported energy is obtained.\n\n* ``fixed``: one ``fixed_price``.\n* ``dynamic``: a price source (``template_id`` and/or ``price_entity``); ``formula``\n turns a spot-only price into the end price (tariff v3; ``None`` = the source's price\n is used as it is, e.g. Tibber's all-in price).\n* ``tou``: fixed time-of-use prices (HT/NT, seasonal) in ``tou`` (tariff v3).", "properties": { + "action_params": { + "additionalProperties": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "items": { + "maxLength": 64, + "minLength": 1, + "type": "string" + }, + "maxItems": 16, + "minItems": 1, + "type": "array" + } + ] + }, + "propertyNames": { + "maxLength": 64, + "minLength": 1 + }, + "title": "Action Params", + "type": "object" + }, "fixed_price": { "anyOf": [ { @@ -3149,6 +3239,43 @@ } ] }, + "price_includes": { + "anyOf": [ + { + "enum": [ + "spot_only", + "all_in" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Price Includes" + }, + "role_entities": { + "patternProperties": { + "^[a-z][a-z0-9_]{0,31}$": { + "$ref": "#/components/schemas/EntityRef" + } + }, + "title": "Role Entities", + "type": "object" + }, + "series_key": { + "anyOf": [ + { + "maxLength": 120, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Series Key" + }, "template_id": { "anyOf": [ { @@ -4012,6 +4139,44 @@ "title": "PreviewOut", "type": "object" }, + "PriceErrorOut": { + "additionalProperties": false, + "description": "Why the last refresh failed, as a catalogue key.", + "properties": { + "args": { + "additionalProperties": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "integer" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ] + }, + "title": "Args", + "type": "object" + }, + "key": { + "title": "Key", + "type": "string" + } + }, + "required": [ + "key" + ], + "title": "PriceErrorOut", + "type": "object" + }, "PriceFormula": { "additionalProperties": false, "description": "Spot price -> end price (BRIEF §4.4).\n\n``end = (spot * spot_multiplier + grid_fee(at) + levies + margin) * (1 + vat_pct/100)``\n\n``grid_fee(at)`` is the fee of the first ``grid_fee_windows`` entry containing ``at``,\nelse ``grid_fee``. VAT is applied to the whole sum, as on a German bill; a negative\nspot price can make the end price negative. Only for ``price_includes = spot_only``\nsources - an all-in price never gets the formula on top.", @@ -4064,6 +4229,312 @@ "title": "PriceFormula", "type": "object" }, + "PriceFreshness": { + "additionalProperties": false, + "properties": { + "age_s": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Age S" + }, + "fetched_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Fetched At" + }, + "known_until": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Known Until" + }, + "last_error": { + "anyOf": [ + { + "$ref": "#/components/schemas/PriceErrorOut" + }, + { + "type": "null" + } + ] + }, + "next_refresh_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next Refresh At" + }, + "status": { + "enum": [ + "fresh", + "stale", + "missing", + "static" + ], + "title": "Status", + "type": "string" + } + }, + "required": [ + "status", + "fetched_at", + "age_s", + "known_until", + "next_refresh_at", + "last_error" + ], + "title": "PriceFreshness", + "type": "object" + }, + "PriceQuality": { + "additionalProperties": false, + "properties": { + "carried_slots": { + "default": 0, + "minimum": 0.0, + "title": "Carried Slots", + "type": "integer" + }, + "dropped_points": { + "minimum": 0.0, + "title": "Dropped Points", + "type": "integer" + }, + "has_tomorrow": { + "title": "Has Tomorrow", + "type": "boolean" + }, + "known_slots": { + "minimum": 0.0, + "title": "Known Slots", + "type": "integer" + }, + "slots": { + "minimum": 0.0, + "title": "Slots", + "type": "integer" + } + }, + "required": [ + "slots", + "known_slots", + "has_tomorrow", + "dropped_points" + ], + "title": "PriceQuality", + "type": "object" + }, + "PriceReport": { + "additionalProperties": false, + "properties": { + "formula_missing": { + "title": "Formula Missing", + "type": "boolean" + }, + "freshness": { + "$ref": "#/components/schemas/PriceFreshness" + }, + "price_includes": { + "enum": [ + "spot_only", + "all_in" + ], + "title": "Price Includes", + "type": "string" + }, + "quality": { + "$ref": "#/components/schemas/PriceQuality" + }, + "slots": { + "items": { + "$ref": "#/components/schemas/PriceSlot" + }, + "title": "Slots", + "type": "array" + }, + "source": { + "$ref": "#/components/schemas/PriceSourceInfo" + }, + "start": { + "format": "date-time", + "title": "Start", + "type": "string" + }, + "step_min": { + "const": 15, + "default": 15, + "title": "Step Min", + "type": "integer" + }, + "unit": { + "const": "currency/kWh", + "default": "currency/kWh", + "title": "Unit", + "type": "string" + } + }, + "required": [ + "price_includes", + "formula_missing", + "start", + "slots", + "source", + "freshness", + "quality" + ], + "title": "PriceReport", + "type": "object" + }, + "PriceSlot": { + "additionalProperties": false, + "description": "One 15-minute interval; a price is ``null`` where no source value covers it.", + "properties": { + "export_price": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Export Price" + }, + "import_price": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Import Price" + }, + "start": { + "format": "date-time", + "title": "Start", + "type": "string" + } + }, + "required": [ + "start", + "import_price", + "export_price" + ], + "title": "PriceSlot", + "type": "object" + }, + "PriceSourceInfo": { + "additionalProperties": false, + "properties": { + "currency": { + "title": "Currency", + "type": "string" + }, + "export_kind": { + "enum": [ + "fixed", + "tiered", + "none" + ], + "title": "Export Kind", + "type": "string" + }, + "export_zeroed_slots": { + "minimum": 0.0, + "title": "Export Zeroed Slots", + "type": "integer" + }, + "formula_applied": { + "title": "Formula Applied", + "type": "boolean" + }, + "import_kind": { + "enum": [ + "dynamic", + "fixed", + "tou" + ], + "title": "Import Kind", + "type": "string" + }, + "import_source_id": { + "title": "Import Source Id", + "type": "string" + }, + "native_step_min": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Native Step Min" + }, + "negative_price_rule": { + "title": "Negative Price Rule", + "type": "string" + }, + "price_includes": { + "enum": [ + "spot_only", + "all_in" + ], + "title": "Price Includes", + "type": "string" + }, + "source_price_includes": { + "enum": [ + "spot_only", + "all_in" + ], + "title": "Source Price Includes", + "type": "string" + } + }, + "required": [ + "import_source_id", + "import_kind", + "source_price_includes", + "price_includes", + "formula_applied", + "export_kind", + "negative_price_rule", + "export_zeroed_slots", + "native_step_min", + "currency" + ], + "title": "PriceSourceInfo", + "type": "object" + }, "PvArray": { "additionalProperties": false, "description": "One PV array (roof plane / inverter input). Everything but ``name`` is optional.", @@ -4486,6 +4957,19 @@ "additionalProperties": false, "description": "Names of the fields of one series point and the unit of its values.\n\n``timestamp_field`` and ``value_field`` are required for a list of point objects\n(``action`` series, ``attribute`` series of shape ``list``) and absent for an\n``attribute`` series of shape ``mapping``, whose keys are the timestamps and whose\nvalues are the values.", "properties": { + "end_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "title": "End Field" + }, "p10_field": { "anyOf": [ { @@ -7034,6 +7518,59 @@ "summary": "Preview" } }, + "/api/v1/prices": { + "get": { + "description": "Import and export prices on the 15-minute grid from now to the end of the known\nprices (at least 24 h where the tariff allows, at most ``hours``), with the source\nand its freshness. A price is ``null`` where no source value covers the interval.", + "operationId": "get_prices", + "parameters": [ + { + "in": "query", + "name": "hours", + "required": false, + "schema": { + "default": 48, + "maximum": 72, + "minimum": 1, + "title": "Hours", + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PriceReport" + } + } + }, + "description": "Successful Response" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorOut" + } + } + }, + "description": "No usable tariff is configured" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorOut" + } + } + }, + "description": "Validation error" + } + }, + "summary": "Prices" + } + }, "/api/v1/proposals": { "get": { "description": "Open assisted-mode proposals, oldest first (valid until ``expires_at``).", diff --git a/frontend/src/lib/api/schema.d.ts b/frontend/src/lib/api/schema.d.ts index e69c60c..b35e143 100644 --- a/frontend/src/lib/api/schema.d.ts +++ b/frontend/src/lib/api/schema.d.ts @@ -448,6 +448,28 @@ export interface paths { patch?: never; trace?: never; }; + "/api/v1/prices": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Prices + * @description Import and export prices on the 15-minute grid from now to the end of the known + * prices (at least 24 h where the tariff allows, at most ``hours``), with the source + * and its freshness. A price is ``null`` where no source value covers the interval. + */ + get: operations["get_prices"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/api/v1/proposals": { parameters: { query?: never; @@ -604,11 +626,33 @@ export interface paths { export type webhooks = Record; export interface components { schemas: { + /** + * ActionParam + * @description A field of the action's request that the user's tariff configuration supplies. + * + * The value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the + * Nord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value. + */ + ActionParam: { + /** Description */ + description: string; + /** Name */ + name: string; + /** + * Required + * @default true + */ + required: boolean; + }; /** * ActionSeries * @description Series returned by a read-only action (``return_response`` is implied). */ ActionSeries: { + /** Date Field */ + date_field?: string | null; + /** Date Tz */ + date_tz?: string | null; /** Domain */ domain: string; /** End Field */ @@ -616,6 +660,11 @@ export interface components { fields: components["schemas"]["SeriesFields"]; /** Max Horizon H */ max_horizon_h: number; + /** + * Params + * @default [] + */ + params: components["schemas"]["ActionParam"][]; /** Response Path */ response_path: string; /** Service */ @@ -1770,6 +1819,10 @@ export interface components { * * ``tou``: fixed time-of-use prices (HT/NT, seasonal) in ``tou`` (tariff v3). */ ImportTariff: { + /** Action Params */ + action_params?: { + [key: string]: string | string[]; + }; /** Fixed Price */ fixed_price?: number | null; formula?: components["schemas"]["PriceFormula"] | null; @@ -1779,6 +1832,14 @@ export interface components { */ kind: "fixed" | "dynamic" | "tou"; price_entity?: components["schemas"]["EntityRef"] | null; + /** Price Includes */ + price_includes?: ("spot_only" | "all_in") | null; + /** Role Entities */ + role_entities?: { + [key: string]: components["schemas"]["EntityRef"]; + }; + /** Series Key */ + series_key?: string | null; /** Template Id */ template_id?: string | null; tou?: components["schemas"]["TouTariff"] | null; @@ -2136,6 +2197,18 @@ export interface components { /** Items */ items: components["schemas"]["PreviewItemOut"][]; }; + /** + * PriceErrorOut + * @description Why the last refresh failed, as a catalogue key. + */ + PriceErrorOut: { + /** Args */ + args?: { + [key: string]: string | number | string[]; + }; + /** Key */ + key: string; + }; /** * PriceFormula * @description Spot price -> end price (BRIEF §4.4). @@ -2179,6 +2252,121 @@ export interface components { */ vat_pct: number; }; + /** PriceFreshness */ + PriceFreshness: { + /** Age S */ + age_s: number | null; + /** Fetched At */ + fetched_at: string | null; + /** Known Until */ + known_until: string | null; + last_error: components["schemas"]["PriceErrorOut"] | null; + /** Next Refresh At */ + next_refresh_at: string | null; + /** + * Status + * @enum {string} + */ + status: "fresh" | "stale" | "missing" | "static"; + }; + /** PriceQuality */ + PriceQuality: { + /** + * Carried Slots + * @default 0 + */ + carried_slots: number; + /** Dropped Points */ + dropped_points: number; + /** Has Tomorrow */ + has_tomorrow: boolean; + /** Known Slots */ + known_slots: number; + /** Slots */ + slots: number; + }; + /** PriceReport */ + PriceReport: { + /** Formula Missing */ + formula_missing: boolean; + freshness: components["schemas"]["PriceFreshness"]; + /** + * Price Includes + * @enum {string} + */ + price_includes: "spot_only" | "all_in"; + quality: components["schemas"]["PriceQuality"]; + /** Slots */ + slots: components["schemas"]["PriceSlot"][]; + source: components["schemas"]["PriceSourceInfo"]; + /** + * Start + * Format: date-time + */ + start: string; + /** + * Step Min + * @default 15 + * @constant + */ + step_min: 15; + /** + * Unit + * @default currency/kWh + * @constant + */ + unit: "currency/kWh"; + }; + /** + * PriceSlot + * @description One 15-minute interval; a price is ``null`` where no source value covers it. + */ + PriceSlot: { + /** Export Price */ + export_price: number | null; + /** Import Price */ + import_price: number | null; + /** + * Start + * Format: date-time + */ + start: string; + }; + /** PriceSourceInfo */ + PriceSourceInfo: { + /** Currency */ + currency: string; + /** + * Export Kind + * @enum {string} + */ + export_kind: "fixed" | "tiered" | "none"; + /** Export Zeroed Slots */ + export_zeroed_slots: number; + /** Formula Applied */ + formula_applied: boolean; + /** + * Import Kind + * @enum {string} + */ + import_kind: "dynamic" | "fixed" | "tou"; + /** Import Source Id */ + import_source_id: string; + /** Native Step Min */ + native_step_min: number | null; + /** Negative Price Rule */ + negative_price_rule: string; + /** + * Price Includes + * @enum {string} + */ + price_includes: "spot_only" | "all_in"; + /** + * Source Price Includes + * @enum {string} + */ + source_price_includes: "spot_only" | "all_in"; + }; /** * PvArray * @description One PV array (roof plane / inverter input). Everything but ``name`` is optional. @@ -2356,6 +2544,8 @@ export interface components { * values are the values. */ SeriesFields: { + /** End Field */ + end_field?: string | null; /** P10 Field */ p10_field?: string | null; /** P90 Field */ @@ -3896,6 +4086,46 @@ export interface operations { }; }; }; + get_prices: { + parameters: { + query?: { + hours?: number; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["PriceReport"]; + }; + }; + /** @description No usable tariff is configured */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ErrorOut"]; + }; + }; + /** @description Validation error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ValidationErrorOut"]; + }; + }; + }; + }; proposals_api_v1_proposals_get: { parameters: { query?: never; diff --git a/frontend/src/lib/i18n/locales/de.json b/frontend/src/lib/i18n/locales/de.json index 0a28c0f..9e04e52 100644 --- a/frontend/src/lib/i18n/locales/de.json +++ b/frontend/src/lib/i18n/locales/de.json @@ -39,6 +39,7 @@ "api.error.not_found": "Nicht gefunden.", "api.error.preview_too_large": "Die Vorschau nennt zu viele Entitäten.", "api.error.role_required": "Für eine Vorlage ist eine Rolle erforderlich.", + "api.error.tariff_not_configured": "Es ist noch kein Tarif eingerichtet. Wähle deinen Tarif in den Einstellungen.", "api.error.unknown": "Ein unerwarteter Fehler ist aufgetreten.", "api.error.unknown_role": "Diese Rolle existiert nicht.", "api.error.unknown_section": "Dieser Konfigurationsbereich existiert nicht.", @@ -701,6 +702,21 @@ "summary.severity.warn": "Warnung:", "tariff.dynamic_source": "Quelle des dynamischen Preises", "tariff.error.incomplete": "Gib Bezugspreis und Einspeisevergütung ein oder überspringe diesen Schritt.", + "tariff.error.source_unavailable": "Die Preisquelle ist gerade nicht verfügbar. SunCore behält die letzten Preise.", + "tariff.error.malformed_payload": "Die Preisquelle hat Daten in einem unerwarteten Format geliefert. SunCore behält die letzten Preise.", + "tariff.error.ambiguous_series": "Die Preisquelle hat mehrere Preislisten geliefert ({available}). Wähle in den Tarif-Einstellungen eine aus.", + "tariff.error.missing_param": "Die Preisquelle braucht die Einstellung „{field}“. Trage sie in den Tarif-Einstellungen ein.", + "tariff.error.missing_entity": "Die Preisquelle braucht eine Entität für „{role}“. Wähle sie in den Tarif-Einstellungen.", + "tariff.error.throttled": "Die Preisquelle wurde zu oft abgefragt und übersprungen; SunCore fragt in {retry_after_s, number} s erneut an.", + "tariff.error.action_failed": "Home Assistant konnte die Preise nicht liefern. SunCore behält die letzten Preise und versucht es erneut.", + "tariff.error.unit_mismatch": "Der Sensor meldet Preise in „{sensor_unit}“, die Vorlage erwartet „{template_unit}“. Wähle die passende Vorlage.", + "tariff.error.currency_mismatch": "Die Preise sind in {source_currency}, deine Region nutzt {region_currency}. Wähle eine Quelle in {region_currency}.", + "tariff.error.export_needs_kwp": "Die gestaffelte Einspeisevergütung braucht die Größe jeder Solaranlage (kWp) und Stufen, die die ganze Anlage abdecken.", + "tariff.error.export_tiers": "Die Einspeisestufen decken die ganze Anlage mit {kwp} kWp nicht ab. Trage einen Satz für den Teil über der letzten Stufe ein.", + "tariff.status.fresh": "Die Preise sind aktuell.", + "tariff.status.stale": "Die Preise sind veraltet; SunCore behält die letzten bekannten Werte.", + "tariff.status.missing": "Noch keine Preise.", + "tariff.status.static": "Feste Preise.", "tariff.export": "Einspeisevergütung", "tariff.export.fixed": "Fester Preis", "tariff.export.none": "Keine Vergütung", @@ -753,6 +769,25 @@ "template.lg.thinq_climate.role.energy_today": "Energie heute (Wh-Zähler desselben Geräts, stündlich aktualisiert)", "template.lg.thinq_climate.role.energy_yesterday": "Energie gestern (Wh, selbes Gerät, optional)", "template.lg.thinq_climate.role.power": "Leistungssensor (optional, z. B. Zwischenstecker oder smartthinq_sensors „Energy current“)", + "template.entsoe.price.name": "ENTSO-E Day-Ahead-Preis (kWh)", + "template.entsoe.price.role.price": "Sensor „Average electricity price“ der ENTSO-E-Integration (er trägt die Preisliste)", + "template.entsoe.price_mwh.name": "ENTSO-E Day-Ahead-Preis (MWh-Skala)", + "template.entsoe.price_mwh.role.price": "Sensor „Average electricity price“ der ENTSO-E-Integration mit MWh-Skala", + "template.epex_spot.market_price.name": "EPEX-Spot-Marktpreis", + "template.epex_spot.market_price.role.price": "Sensor „Market Price“ der EPEX-Spot-Integration (reiner Marktpreis)", + "template.epex_spot.total_price.name": "EPEX-Spot-Gesamtpreis", + "template.epex_spot.total_price.role.price": "Sensor „Total Price“ der EPEX-Spot-Integration (Marktpreis plus deine Aufschläge und Mehrwertsteuer)", + "template.generic.price_list.name": "Allgemeine Preisliste (Sensor-Attribut)", + "template.generic.price_list.role.price": "Sensor mit dem Attribut „prices“: Liste aus Startzeit und Preis pro kWh", + "template.nordpool.price.name": "Nord-Pool-Day-Ahead-Preis", + "template.nordpool.price.role.price": "Aktueller Preissensor der Nord-Pool-Integration (Währung pro kWh)", + "template.nordpool.price.param.config_entry": "ID des Nord-Pool-Konfigurationseintrags in Home Assistant", + "template.nordpool.price.param.areas": "Preisgebiet, zum Beispiel SE3 (leer: das in der Integration eingerichtete Gebiet)", + "template.nordpool.price.param.currency": "Währung der Preise (leer: die in der Integration eingerichtete Währung)", + "template.octopus_energy.rates.name": "Octopus-Energy-Tarife", + "template.octopus_energy.rates.role.price": "Sensor des aktuellen Bezugstarifs von Octopus Energy (GBP pro kWh)", + "template.octopus_energy.rates.role.current_day_rates": "Ereignis-Entität „Current day rates“ (Bezug) von Octopus Energy", + "template.octopus_energy.rates.role.next_day_rates": "Ereignis-Entität „Next day rates“ (Bezug) von Octopus Energy (optional)", "template.solcast.pv.name": "Solcast-PV-Prognose", "template.solcast.pv.role.forecast_today": "Solcast-Sensor für die Prognose von heute (kWh)", "template.solcast.pv.role.forecast_tomorrow": "Solcast-Sensor für die Prognose von morgen (kWh)", @@ -773,6 +808,7 @@ "wizard.check.battery_sign_soc": "Die Batterie lädt mit {battery_w} W, obwohl sie bei {soc_pct} % steht (oder entlädt im leeren Zustand). Das Vorzeichen könnte vertauscht sein.", "wizard.check.entities_fresh": "{count, plural, one {# Sensor liefert} other {# Sensoren liefern}} aktuelle Werte.", "wizard.check.duplicate_unit": "„{device_a}“ und „{device_b}“ steuern dasselbe Gerät „{unit_name}“ (zwei Integrationen oder dieselbe Entity doppelt). Steuere ein Gerät nur einmal.", + "wizard.check.tariff_spot_without_formula": "Der Tarif liefert reine Börsenpreise und es ist keine Preisformel gesetzt. Trage Netzentgelt, Abgaben und Mehrwertsteuer ein, sonst sind die Preise zu niedrig zum Planen.", "wizard.check.entity_invalid": "{entity_id} liefert keine Zahl.", "wizard.check.entity_missing": "{entity_id} existiert in Home Assistant nicht.", "wizard.check.entity_stale": "{entity_id} wurde seit einiger Zeit nicht aktualisiert.", @@ -835,6 +871,9 @@ "api.validation.forecast_manual_weight": "Eine manuelle Gewichtung braucht ein Gewicht.", "api.validation.grid_charge_needs_limit": "Laden aus dem Netz braucht eine Preisgrenze oder einen Zeitplan.", "api.validation.import_formula_dynamic_only": "Eine Preisformel gilt nur für einen dynamischen Tarif.", + "api.validation.import_param_missing": "Der Tarif {template_id} braucht die Einstellung „{field}“.", + "api.validation.import_role_price": "Der Preissensor wird über „Preissensor“ gesetzt, nicht als zusätzliche Entität.", + "api.validation.import_source_dynamic_only": "Sensoren, Abfrage-Einstellungen und eine Preisangabe gelten nur für einen dynamischen Tarif.", "api.validation.import_tou_extra": "Ein zeitvariabler Tarif (HT/NT) hat keinen Festpreis, keine Vorlage und keinen Preissensor.", "api.validation.import_tou_needs_periods": "Ein zeitvariabler Tarif (HT/NT) braucht seine Zeitfenster und Preise.", "api.validation.import_tou_only": "Zeitfenster mit Preisen brauchen einen zeitvariablen Tarif (HT/NT).", diff --git a/frontend/src/lib/i18n/locales/en.json b/frontend/src/lib/i18n/locales/en.json index 0bf9c58..094e483 100644 --- a/frontend/src/lib/i18n/locales/en.json +++ b/frontend/src/lib/i18n/locales/en.json @@ -39,6 +39,7 @@ "api.error.not_found": "Not found.", "api.error.preview_too_large": "The preview names too many entities.", "api.error.role_required": "A role is required for a template.", + "api.error.tariff_not_configured": "No tariff is set up yet. Choose your tariff in the settings.", "api.error.unknown": "An unexpected error occurred.", "api.error.unknown_role": "This role does not exist.", "api.error.unknown_section": "This configuration section does not exist.", @@ -701,6 +702,21 @@ "summary.severity.warn": "Warning:", "tariff.dynamic_source": "Source of the dynamic price", "tariff.error.incomplete": "Enter the import price and the feed-in remuneration, or skip this step.", + "tariff.error.source_unavailable": "The price source is not available right now. SunCore keeps the last prices.", + "tariff.error.malformed_payload": "The price source delivered data in an unexpected format. SunCore keeps the last prices.", + "tariff.error.ambiguous_series": "The price source returned several price lists ({available}). Choose one in the tariff settings.", + "tariff.error.missing_param": "The price source needs the setting “{field}”. Enter it in the tariff settings.", + "tariff.error.missing_entity": "The price source needs an entity for “{role}”. Choose it in the tariff settings.", + "tariff.error.throttled": "The price source was asked too often and skipped; SunCore asks again in {retry_after_s, number} s.", + "tariff.error.action_failed": "Home Assistant could not deliver the prices. SunCore keeps the last prices and tries again.", + "tariff.error.unit_mismatch": "The sensor reports prices in “{sensor_unit}” but the template expects “{template_unit}”. Choose the matching template.", + "tariff.error.currency_mismatch": "The prices are in {source_currency} but your region uses {region_currency}. Choose a source in {region_currency}.", + "tariff.error.export_needs_kwp": "The tiered feed-in remuneration needs the size of every solar array (kWp) and tiers that cover the whole plant.", + "tariff.error.export_tiers": "The feed-in tiers do not cover the whole plant of {kwp} kWp. Enter a rate for the part above the last tier.", + "tariff.status.fresh": "Prices are up to date.", + "tariff.status.stale": "Prices are outdated; SunCore keeps the last known values.", + "tariff.status.missing": "No prices yet.", + "tariff.status.static": "Fixed prices.", "tariff.export": "Feed-in remuneration", "tariff.export.fixed": "Fixed price", "tariff.export.none": "No remuneration", @@ -753,6 +769,25 @@ "template.lg.thinq_climate.role.energy_today": "Energy used today (Wh counter of the same device, updated hourly)", "template.lg.thinq_climate.role.energy_yesterday": "Energy used yesterday (Wh, same device, optional)", "template.lg.thinq_climate.role.power": "Power sensor (optional, e.g. smart plug or smartthinq_sensors “Energy current”)", + "template.entsoe.price.name": "ENTSO-E day-ahead price (kWh)", + "template.entsoe.price.role.price": "“Average electricity price” sensor of the ENTSO-E integration (it carries the price list)", + "template.entsoe.price_mwh.name": "ENTSO-E day-ahead price (MWh scale)", + "template.entsoe.price_mwh.role.price": "“Average electricity price” sensor of the ENTSO-E integration set to the MWh scale", + "template.epex_spot.market_price.name": "EPEX Spot market price", + "template.epex_spot.market_price.role.price": "“Market Price” sensor of the EPEX Spot integration (bare market price)", + "template.epex_spot.total_price.name": "EPEX Spot total price", + "template.epex_spot.total_price.role.price": "“Total Price” sensor of the EPEX Spot integration (market price plus your surcharges and VAT)", + "template.generic.price_list.name": "Generic price list (sensor attribute)", + "template.generic.price_list.role.price": "Sensor with an attribute “prices”: a list of start time and price per kWh", + "template.nordpool.price.name": "Nord Pool day-ahead price", + "template.nordpool.price.role.price": "Current price sensor of the Nord Pool integration (currency per kWh)", + "template.nordpool.price.param.config_entry": "ID of the Nord Pool configuration entry in Home Assistant", + "template.nordpool.price.param.areas": "Price area, for example SE3 (empty: the area set up in the integration)", + "template.nordpool.price.param.currency": "Currency of the prices (empty: the currency set up in the integration)", + "template.octopus_energy.rates.name": "Octopus Energy rates", + "template.octopus_energy.rates.role.price": "Current import rate sensor of Octopus Energy (GBP per kWh)", + "template.octopus_energy.rates.role.current_day_rates": "Event entity “Current day rates” (import) of Octopus Energy", + "template.octopus_energy.rates.role.next_day_rates": "Event entity “Next day rates” (import) of Octopus Energy (optional)", "template.solcast.pv.name": "Solcast PV forecast", "template.solcast.pv.role.forecast_today": "Solcast sensor for today's forecast (kWh)", "template.solcast.pv.role.forecast_tomorrow": "Solcast sensor for tomorrow's forecast (kWh)", @@ -773,6 +808,7 @@ "wizard.check.battery_sign_soc": "The battery charges at {battery_w} W although it is at {soc_pct} % (or discharges while empty). The sign may be inverted.", "wizard.check.entities_fresh": "All {count, plural, one {# sensor delivers} other {# sensors deliver}} current values.", "wizard.check.duplicate_unit": "“{device_a}” and “{device_b}” control the same unit “{unit_name}” (two integrations or the same entity twice). Control a unit only once.", + "wizard.check.tariff_spot_without_formula": "The tariff delivers bare market prices and no price formula is set. Add your grid fee, levies and VAT, otherwise the prices are too low to plan with.", "wizard.check.entity_invalid": "{entity_id} does not deliver a number.", "wizard.check.entity_missing": "{entity_id} does not exist in Home Assistant.", "wizard.check.entity_stale": "{entity_id} has not updated for a while.", @@ -835,6 +871,9 @@ "api.validation.forecast_manual_weight": "A manual weighting needs a weight.", "api.validation.grid_charge_needs_limit": "Grid charging needs a price level or a schedule.", "api.validation.import_formula_dynamic_only": "A price formula only applies to a dynamic tariff.", + "api.validation.import_param_missing": "The tariff {template_id} needs the setting “{field}”.", + "api.validation.import_role_price": "The price sensor is set with “price sensor”, not as an additional entity.", + "api.validation.import_source_dynamic_only": "Sensors, request settings and a price statement only apply to a dynamic tariff.", "api.validation.import_tou_extra": "A time-of-use tariff takes no fixed price, template or price sensor.", "api.validation.import_tou_needs_periods": "A time-of-use tariff needs its time windows and prices.", "api.validation.import_tou_only": "Time windows with prices need the time-of-use tariff.", diff --git a/scripts/check_reasons.py b/scripts/check_reasons.py index 0bbf5cc..58224da 100644 --- a/scripts/check_reasons.py +++ b/scripts/check_reasons.py @@ -8,9 +8,9 @@ * string constants starting with ``api.error.`` (the error ``detail`` keys of the API) or ``api.validation.`` in ``suncore/api`` (validation issue keys), * string constants that are exactly one key with the prefix ``wizard.`` (check and import - reasons built from a variable), ``detect.criterion.`` or ``ha.error.`` anywhere - in ``suncore/``, and ``controller.`` in ``suncore/controller/reasons.py`` (the - controller's key constants). + reasons built from a variable), ``detect.criterion.``, ``ha.error.`` or ``tariff.error.`` + (the tariff adapters' error keys) anywhere in ``suncore/``, and ``controller.`` in + ``suncore/controller/reasons.py`` (the controller's key constants). Each key must be present in ``frontend/src/lib/i18n/locales/en.json`` and ``de.json``. Run via ``uv run python scripts/check_reasons.py``; exit code 1 lists the gaps. @@ -28,7 +28,7 @@ SOURCE = ROOT / "suncore" LOCALES = ROOT / "frontend" / "src" / "lib" / "i18n" / "locales" ERROR_PREFIXES = ("api.error.", "api.validation.") -KEY_PREFIXES = ("wizard.", "detect.criterion.", "ha.error.") +KEY_PREFIXES = ("wizard.", "detect.criterion.", "ha.error.", "tariff.error.") CONTROLLER_KEYS = Path("controller") / "reasons.py" """The controller defines its keys as constants in one module (log event names elsewhere may share the ``controller.`` prefix).""" diff --git a/suncore/api/__init__.py b/suncore/api/__init__.py index 172ac52..8d6ab3e 100644 --- a/suncore/api/__init__.py +++ b/suncore/api/__init__.py @@ -9,6 +9,7 @@ HealthReport, PeerPolicy, Services, + TariffNotConfiguredError, UnknownRoleError, UnknownTemplateError, ) @@ -20,6 +21,7 @@ "HealthReport", "PeerPolicy", "Services", + "TariffNotConfiguredError", "UnknownRoleError", "UnknownTemplateError", "create_app", diff --git a/suncore/api/app.py b/suncore/api/app.py index 41f46ca..faf35b0 100644 --- a/suncore/api/app.py +++ b/suncore/api/app.py @@ -25,6 +25,7 @@ from fastapi.exceptions import RequestValidationError from fastapi.responses import FileResponse, JSONResponse, Response from pydantic import BaseModel, TypeAdapter +from pydantic_core import PydanticCustomError from starlette.websockets import WebSocketState from suncore.api.limits import BodyLimitMiddleware @@ -62,6 +63,7 @@ EntityQuery, HAUnavailableError, Services, + TariffNotConfiguredError, UnknownRoleError, UnknownTemplateError, ) @@ -71,6 +73,7 @@ OperationConfig, TariffConfig, formula_on_all_in_source, + missing_action_params, ) from suncore.core.controlstate import ( ControlState, @@ -92,13 +95,15 @@ ImportRejectedError, UnknownSectionError, ) +from suncore.tariff.report import PriceReport from suncore.templates import TemplateCatalog -from suncore.templates.models import TariffTemplate, TemplateKind +from suncore.templates.models import ActionSeries, TariffTemplate, TemplateKind log = logging.getLogger(__name__) API_PREFIX: Final = "/api/v1" DECISIONS_MAX: Final = 1000 +PRICES_MAX_HOURS: Final = 72 # Stable error keys for ``detail``; the SPA renders them through the message catalogue. ERR_HA_UNAVAILABLE: Final = "api.error.ha_unavailable" @@ -119,6 +124,7 @@ ERR_UNKNOWN_PROPOSAL: Final = "api.error.unknown_proposal" ERR_DEVICE_IDENTITY_CHANGED: Final = "api.error.device_identity_changed" ERR_MODE_RAISE_REJECTED: Final = "api.error.mode_raise_rejected" +ERR_TARIFF_NOT_CONFIGURED: Final = "api.error.tariff_not_configured" BODY_MAX_BYTES: Final = 64 * 1024 """Limit of the small JSON bodies of the wizard endpoints (check, preview).""" SECTION_MAX_BYTES: Final = 256 * 1024 @@ -148,6 +154,7 @@ def create_app( app.add_middleware(PeerCheckMiddleware, policy=services.peer_policy) app.add_exception_handler(RequestValidationError, validation_exception_handler) _register_http(app, services) + _register_prices(app, services) _register_live(app, services, live_min_interval_s, live_health_interval_s) _mount_spa(app, services) app.openapi = lambda: _openapi(app) # type: ignore[method-assign] @@ -268,6 +275,25 @@ async def decisions( return await services.decisions(limit, device_id=device_id, kinds=kind) +def _register_prices(app: FastAPI, services: Services) -> None: + @app.get( + f"{API_PREFIX}/prices", + response_model=PriceReport, + responses={404: {"model": ErrorOut, "description": "No usable tariff is configured"}}, + operation_id="get_prices", + ) + async def prices( + hours: int = Query(default=48, ge=1, le=PRICES_MAX_HOURS), + ) -> PriceReport: + """Import and export prices on the 15-minute grid from now to the end of the known + prices (at least 24 h where the tariff allows, at most ``hours``), with the source + and its freshness. A price is ``null`` where no source value covers the interval.""" + try: + return await services.prices(hours) + except TariffNotConfiguredError as exc: + raise HTTPException(status_code=404, detail=ERR_TARIFF_NOT_CONFIGURED) from exc + + def _register_control(app: FastAPI, services: Services) -> None: """Control state, emergency stop, overrides, proposals and operating modes (WP9).""" @@ -429,16 +455,22 @@ def _check_tariff_against_catalog(tariff: TariffConfig, catalog: TemplateCatalog template_id = tariff.import_.template_id template = catalog.get(template_id) if template_id is not None else None includes = template.price_includes if isinstance(template, TariffTemplate) else None + includes = tariff.import_.price_includes or includes # the user's statement wins + problems: list[tuple[tuple[str, ...], PydanticCustomError]] = [] error = formula_on_all_in_source(tariff, includes) if error is not None: + problems.append((("body", "import", "formula"), error)) + if isinstance(template, TariffTemplate) and isinstance(template.price_series, ActionSeries): + required = [p.name for p in template.price_series.params if p.required] + problems.extend( + (("body", "import", "action_params", name), error) + for name, error in missing_action_params(tariff, template.id, required) + ) + if problems: raise RequestValidationError( [ - { - "type": error.type, - "loc": ("body", "import", "formula"), - "msg": error.message(), - "ctx": error.context or {}, - } + {"type": e.type, "loc": loc, "msg": e.message(), "ctx": e.context or {}} + for loc, e in problems ] ) diff --git a/suncore/api/services.py b/suncore/api/services.py index 216380c..2f9695c 100644 --- a/suncore/api/services.py +++ b/suncore/api/services.py @@ -23,6 +23,7 @@ from suncore.core.site import SiteConfig from suncore.core.wizard import CheckItem, PreviewItem from suncore.storage import HistoryEntry +from suncore.tariff.report import PriceReport from suncore.templates import TemplateCatalog FATAL_HA_STATES: Final = frozenset({"auth_failed", "closed"}) @@ -211,6 +212,13 @@ def add_control_listener(self, listener: Callable[[], None]) -> Callable[[], Non """Call ``listener`` whenever the control state may have changed (tick, decision, mode).""" ... + async def prices(self, hours: int) -> PriceReport: + """The planning prices (15-minute grid) with source and freshness. + + Raises :class:`TariffNotConfiguredError` while no usable tariff exists. + """ + ... + async def export_config(self) -> dict[str, Any]: ... async def import_config(self, data: object) -> list[str]: @@ -240,3 +248,7 @@ class UnknownRoleError(LookupError): class UnknownTemplateError(LookupError): """No template with the requested id is loaded.""" + + +class TariffNotConfiguredError(LookupError): + """No usable tariff (none stored, no region, or its template is missing).""" diff --git a/suncore/api/validation.py b/suncore/api/validation.py index 0992c43..c66e73c 100644 --- a/suncore/api/validation.py +++ b/suncore/api/validation.py @@ -116,6 +116,9 @@ "suncore.forecast_manual_weight": "api.validation.forecast_manual_weight", "suncore.grid_charge_needs_limit": "api.validation.grid_charge_needs_limit", "suncore.import_formula_dynamic_only": "api.validation.import_formula_dynamic_only", + "suncore.import_param_missing": "api.validation.import_param_missing", + "suncore.import_role_price": "api.validation.import_role_price", + "suncore.import_source_dynamic_only": "api.validation.import_source_dynamic_only", "suncore.import_tou_extra": "api.validation.import_tou_extra", "suncore.import_tou_needs_periods": "api.validation.import_tou_needs_periods", "suncore.import_tou_only": "api.validation.import_tou_only", diff --git a/suncore/app/adapters.py b/suncore/app/adapters.py index 1c7e2d5..0c24446 100644 --- a/suncore/app/adapters.py +++ b/suncore/app/adapters.py @@ -1,14 +1,216 @@ # SPDX-License-Identifier: Apache-2.0 """Composition of the tariff and forecast adapters (Phase 4 WP4/WP5). -This module will build the price and forecast sources from the configured templates and hand -them the Home Assistant connection. It is the only module of ``suncore.app`` that may call +This module builds the price and forecast sources from the configured templates and hands them +the Home Assistant connection. It is the only module of ``suncore.app`` that may call ``HAConnection.call_action_response`` (``tests/safety/test_boundary.py``, rule 7): the call is a read-only action with ``return_response`` and is rate limited per ``(domain, service)`` by the -connection (``ActionRateLimiter``). An adapter passes the polling interval of its template as -``min_interval_s`` and treats ``ActionRateLimitedError`` as "use the last value". +connection (``ActionRateLimiter``). The tariff engine passes ``DEFAULT_MIN_INTERVAL_S`` (30 s, +the limiter's floor) as ``min_interval_s``; how often the service asks is its own refresh +logic. A throttled call means "use the last value" +(:class:`~suncore.tariff.errors.SourceThrottledError`). -Empty on purpose until the first adapter lands (PR 4-C). +* :class:`ConnectionActionCaller` - the ``ActionCaller`` of the tariff engine; +* :func:`cache_reader` - the ``EntityReader`` on top of the entity cache; +* :func:`build_tariff_plan` / :func:`build_tariff_service` - configuration -> service. """ from __future__ import annotations + +from collections.abc import Callable, Mapping +from datetime import datetime, time, tzinfo +from typing import Any + +import structlog + +from suncore.core.config import RegionConfig, TariffConfig +from suncore.core.site import SiteConfig +from suncore.ha import EntityCache, HAConnection, HAError +from suncore.ha.connection import ActionRateLimitedError +from suncore.tariff import ( + CurrentPriceSource, + EntityReader, + EntityReading, + FixedPriceSource, + PriceStore, + SegmentSource, + ServiceSettings, + SourceBinding, + SourceFailedError, + SourceThrottledError, + TariffPlan, + TariffService, + TemplatePriceSource, + TouPriceSource, +) +from suncore.templates import RegionTemplate, TariffTemplate, TemplateCatalog +from suncore.templates.models import NegativePriceRule + +log = structlog.get_logger(__name__) + + +class ConnectionActionCaller: + """``ActionCaller`` on a Home Assistant connection (read-only actions only). + + A call the rate limiter skips becomes :class:`SourceThrottledError` (not a failure: the + service keeps the last prices); anything else Home Assistant answers wrong becomes + :class:`SourceFailedError`. + """ + + def __init__(self, connection: HAConnection) -> None: + self._connection = connection + + async def __call__( + self, + domain: str, + service: str, + data: Mapping[str, Any], + *, + min_interval_s: float, + max_wait_s: float, + ) -> Mapping[str, Any]: + try: + return await self._connection.call_action_response( + domain, service, data, min_interval_s=min_interval_s, max_wait_s=max_wait_s + ) + except ActionRateLimitedError as exc: + raise SourceThrottledError(exc.retry_after_s) from exc + except (HAError, TimeoutError) as exc: + raise SourceFailedError(f"{type(exc).__name__}: {exc}") from exc + + +def cache_reader(cache: EntityCache) -> EntityReader: + """Entity readings from the cache; ``unavailable`` and absent entities read as ``None``. + + ``unknown`` is returned as is: an event entity is ``unknown`` until its first event while + its attributes may already be restored. + """ + + def read(entity_id: str) -> EntityReading | None: + entry = cache.get(entity_id) + if entry is None or entry.state.state == "unavailable": + return None + return EntityReading(entry.state.state, entry.state.attributes) + + return read + + +def negative_price_rule(catalog: TemplateCatalog, region: RegionConfig) -> NegativePriceRule: + """The region template's rule (``none`` for an unknown or user-defined region).""" + template = catalog.get(region.region_id) + return ( + template.negative_price_rule + if isinstance(template, RegionTemplate) + else NegativePriceRule.NONE + ) + + +def _import_source( + tariff: TariffConfig, + region: RegionConfig, + tz: tzinfo, + catalog: TemplateCatalog, + *, + connection: HAConnection, + cache: EntityCache, + clock: Callable[[], datetime], +) -> SegmentSource | None: + imp = tariff.import_ + if imp.kind == "fixed": + assert imp.fixed_price is not None + return FixedPriceSource(price=imp.fixed_price) + if imp.kind == "tou": + assert imp.tou is not None + return TouPriceSource(tou=imp.tou, tz=tz) + reader = cache_reader(cache) + template = catalog.get(imp.template_id) if imp.template_id is not None else None + if not isinstance(template, TariffTemplate) or template.price_series is None: + if imp.template_id is not None: + log.warning("tariff.template_unusable", template_id=imp.template_id) + return None + assert imp.price_entity is not None + return CurrentPriceSource( + imp.price_entity.entity_id, + reader, + price_includes=imp.price_includes or "all_in", + clock=clock, + ) + entities = {role: ref.entity_id for role, ref in imp.role_entities.items()} + if imp.price_entity is not None: + entities["price"] = imp.price_entity.entity_id + binding = SourceBinding( + tz=tz, + entities=entities, + action_params=imp.action_params, + series_key=imp.series_key, + price_includes=imp.price_includes, + currency=region.currency, + ) + return TemplatePriceSource( + template, + binding, + action=ConnectionActionCaller(connection), + attributes=reader, + clock=clock, + ) + + +def build_tariff_plan( + tariff: TariffConfig, + region: RegionConfig, + site: SiteConfig | None, + tz: tzinfo, + catalog: TemplateCatalog, + *, + connection: HAConnection, + cache: EntityCache, + clock: Callable[[], datetime], +) -> TariffPlan | None: + """The resolved tariff, ``None`` when its template is missing or not a price curve.""" + source = _import_source( + tariff, region, tz, catalog, connection=connection, cache=cache, clock=clock + ) + if source is None: + return None + return TariffPlan( + source=source, + export_tariff=tariff.export, + negative_rule=negative_price_rule(catalog, region), + tz=tz, + currency=region.currency, + formula=tariff.import_.formula, + total_kwp=None if site is None else site.total_kwp, + ) + + +def build_tariff_service( + tariff: TariffConfig, + region: RegionConfig, + site: SiteConfig | None, + tz: tzinfo, + catalog: TemplateCatalog, + *, + connection: HAConnection, + cache: EntityCache, + clock: Callable[[], datetime], + store: PriceStore | None, + refresh_interval_s: float = 3600.0, + tomorrow_after: time = time(13, 0), + tomorrow_poll_s: float = 900.0, +) -> TariffService | None: + """A :class:`TariffService` for the stored tariff, ``None`` if it cannot be built. + + Raises :class:`~suncore.tariff.errors.ExportConfigError` for a tiered export that the + site's size does not allow (the caller logs it and runs without prices). + """ + plan = build_tariff_plan( + tariff, region, site, tz, catalog, connection=connection, cache=cache, clock=clock + ) + if plan is None: + return None + settings = ServiceSettings( + refresh_interval_s=refresh_interval_s, + tomorrow_after=tomorrow_after, + tomorrow_poll_s=tomorrow_poll_s, + ) + return TariffService(plan, clock=clock, store=store, settings=settings) diff --git a/suncore/app/openapi_stub.py b/suncore/app/openapi_stub.py index 5d8ca79..87f8ab7 100644 --- a/suncore/app/openapi_stub.py +++ b/suncore/app/openapi_stub.py @@ -10,7 +10,7 @@ from pydantic import BaseModel from suncore import __version__ -from suncore.api.services import EntityQuery, HealthReport, PeerPolicy +from suncore.api.services import EntityQuery, HealthReport, PeerPolicy, TariffNotConfiguredError from suncore.core.balance import FlowSnapshot from suncore.core.config import OperationConfig from suncore.core.controlstate import ControlState, DeviceControlState, OverrideCommand @@ -19,6 +19,7 @@ from suncore.core.site import SiteConfig from suncore.core.wizard import CheckItem, PreviewItem from suncore.storage import HistoryEntry +from suncore.tariff.report import PriceReport from suncore.templates import TemplateCatalog @@ -121,6 +122,9 @@ async def set_device_mode( def add_control_listener(self, listener: Callable[[], None]) -> Callable[[], None]: # noqa: ARG002 return lambda: None + async def prices(self, hours: int) -> PriceReport: # noqa: ARG002 + raise TariffNotConfiguredError + async def export_config(self) -> dict[str, Any]: return {} diff --git a/suncore/app/runtime.py b/suncore/app/runtime.py index 8b82efb..f307992 100644 --- a/suncore/app/runtime.py +++ b/suncore/app/runtime.py @@ -23,9 +23,11 @@ HAUnavailableError, HealthReport, PeerPolicy, + TariffNotConfiguredError, UnknownRoleError, UnknownTemplateError, ) +from suncore.app.adapters import build_tariff_service from suncore.app.cadence import device_cadences, merge_cadences from suncore.app.control import ControlStack from suncore.app.history import rebuild_history @@ -33,7 +35,13 @@ from suncore.app.recorder import FLUSH_INTERVAL_S, MeasurementRecorder from suncore.app.settings import SUPERVISOR_INGRESS_PEER, Settings from suncore.core.balance import FlowSnapshot, compute_flows -from suncore.core.config import DevicesConfig, GoalsConfig, OperationConfig, RegionConfig +from suncore.core.config import ( + DevicesConfig, + GoalsConfig, + OperationConfig, + RegionConfig, + TariffConfig, +) from suncore.core.control import ControlSettings from suncore.core.controlstate import ( ControlState, @@ -51,7 +59,14 @@ from suncore.core.identity import identity_token from suncore.core.signals import Sample from suncore.core.site import SiteConfig -from suncore.core.wizard import CheckItem, PreviewItem, collect_refs, preview, run_system_check +from suncore.core.wizard import ( + CheckItem, + PreviewItem, + check_tariff, + collect_refs, + preview, + run_system_check, +) from suncore.ha import ( SITE_ROLES, CommandError, @@ -80,7 +95,9 @@ TimeseriesStore, ) from suncore.storage.timeseries import META_HISTORY_REBUILT -from suncore.templates import TemplateCatalog +from suncore.tariff import ExportConfigError, TariffService +from suncore.tariff.report import PriceReport +from suncore.templates import TariffTemplate, TemplateCatalog LOOPBACK_PEERS: tuple[str, ...] = ("127.0.0.1", "::1") @@ -128,6 +145,9 @@ class Runtime: devices: DevicesConfig | None = None region: RegionConfig | None = None goals: GoalsConfig | None = None + tariff_config: TariffConfig | None = None + tariff: TariffService | None = None + """Keeps the prices fresh (``None``: no tariff, no region or an unusable template).""" timeseries_db: Database | None = None """``timeseries.db``; ``None`` = unavailable (too new, unopenable): control is unaffected.""" timeseries: TimeseriesStore | None = None @@ -160,6 +180,7 @@ class Runtime: _flush_task: asyncio.Task[None] | None = None _maintenance_task: asyncio.Task[None] | None = None _history_task: asyncio.Task[None] | None = None + _tariff_task: asyncio.Task[None] | None = None _history_done: bool = False """The statistics rebuild ran (or was not needed) in this process.""" _stack_lock: asyncio.Lock = field(default_factory=asyncio.Lock) @@ -187,6 +208,7 @@ async def prepare(self) -> None: """ await self._load_live_sections() self.stack = self._new_stack() + self._build_tariff() async def start(self) -> None: """Wire the control stack and the connection and start connecting in the background. @@ -208,6 +230,7 @@ async def start(self) -> None: self.stack.start_ticking() self._connect_task = asyncio.create_task(self._connect(), name="suncore-ha-connect") self._prune_task = asyncio.create_task(self._prune_loop(), name="suncore-prune") + self._start_tariff() if self.timeseries is not None: self._flush_task = asyncio.create_task(self._flush_loop(), name="suncore-ts-flush") self._maintenance_task = asyncio.create_task( @@ -225,6 +248,9 @@ async def _load_live_sections(self) -> None: goals = await self.config.get("goals") assert goals is None or isinstance(goals, GoalsConfig) self.goals = goals + tariff = await self.config.get("tariff") + assert tariff is None or isinstance(tariff, TariffConfig) + self.tariff_config = tariff await self._load_modes() async def _load_modes(self) -> None: @@ -244,6 +270,63 @@ def _timezone(self) -> tzinfo: log.warning("control.timezone_unknown_using_utc") return UTC + # --- tariff (prices) -------------------------------------------------------- + + def _build_tariff(self) -> None: + """(Re)build the price service from the stored tariff, region and site. + + Without a tariff or a region there is nothing to build; an unusable tariff (missing + template, tiered export without the plant size) is logged and leaves the service off. + """ + self.tariff = None + tariff, region = self.tariff_config, self.region + if tariff is None or region is None: + return + try: + self.tariff = build_tariff_service( + tariff, + region, + self.site, + self._timezone(), + self.template_catalog, + connection=self.connection, + cache=self.cache, + clock=self.clock, + store=self.timeseries, + refresh_interval_s=float(self.settings.tariff_refresh_interval_s), + tomorrow_after=self.settings.tariff_tomorrow_after, + tomorrow_poll_s=float(self.settings.tariff_tomorrow_poll_s), + ) + except ExportConfigError as exc: + log.warning("tariff.export_unusable", error=exc.key, detail=exc.detail) + if self.tariff is None: + log.warning("tariff.service_not_built") + + def _start_tariff(self) -> None: + if self.tariff is not None and self._started and self._tariff_task is None: + self._tariff_task = asyncio.create_task( + self.tariff.run(self.control_sleep), name="suncore-tariff" + ) + + async def _stop_tariff(self) -> None: + task, self._tariff_task = self._tariff_task, None + if task is not None: + task.cancel() + with contextlib.suppress(asyncio.CancelledError, Exception): + await task + + async def _rebuild_tariff(self) -> None: + """Replace the price service after a ``tariff``, ``region`` or ``site`` change.""" + await self._stop_tariff() + self._build_tariff() + self._start_tariff() + self._notify() + + async def prices(self, hours: int) -> PriceReport: + if self.tariff is None: + raise TariffNotConfiguredError + return self.tariff.report(hours=float(hours)) + def _new_stack( self, *, after_handover: bool = False, predecessor: SafetyGate | None = None ) -> ControlStack: @@ -507,6 +590,7 @@ async def stop(self) -> None: self._flush_task, self._maintenance_task, self._history_task, + self._tariff_task, ) for task in (*control_tasks, *storage_tasks): if task is not None: @@ -517,6 +601,7 @@ async def stop(self) -> None: await task self._connect_task = self._prune_task = self._tz_task = None self._flush_task = self._maintenance_task = self._history_task = None + self._tariff_task = None # Hardware release comes first: a running downsample or retention statement keeps the # (shielded) rollback of its cancelled task waiting, and a Pi can need seconds for it. # The storage tasks are awaited only after the devices are released. @@ -558,11 +643,15 @@ def _on_entities(self, update: EntityUpdate) -> None: self._last_update = self.real_clock() if self.stack is not None: self.stack.on_update(update) + if self.tariff is not None and not self.tariff.watched_entities_isdisjoint(update.changed): + self.tariff.notify_changed() self._notify() def _on_state(self, state: ConnectionState) -> None: if self.stack is not None: self.stack.on_state(state) + if state is ConnectionState.CONNECTED and self.tariff is not None: + self.tariff.reset_backoff() # the failures were the missing connection if ( state is ConnectionState.CONNECTED and self._started @@ -581,6 +670,8 @@ async def _resubscribe(self) -> None: refs = list(self.site.entity_refs()) if self.site else [] if self.devices is not None: refs.extend(self.devices.entity_refs()) + if self.tariff_config is not None: + refs.extend(self.tariff_config.entity_refs()) ids = list(dict.fromkeys(r.entity_id for r in refs)) try: await self.connection.subscribe_entities(ids) @@ -702,8 +793,13 @@ async def _apply_stored( self.goals = stored if self.stack is not None: self.stack.set_goals(stored) - if name in ("site", "devices"): + elif name == "tariff": + assert isinstance(stored, TariffConfig) + self.tariff_config = stored + if name in ("site", "devices", "tariff"): await self._resubscribe() + if name == "tariff" or (self.site, self.region) != before[::2]: + await self._rebuild_tariff() if (self.site, self.devices, self.region) != before: await self._rebuild_stack() if name == "devices": @@ -934,9 +1030,16 @@ async def system_check(self, site: SiteConfig | None) -> list[CheckItem]: ids = [r.entity_id for r in site.entity_refs()] if site is not None else [] await self._browse_if_needed(ids) present = await self.config.stored_sections() - return run_system_check( + items = run_system_check( site, self._samples(ids), present, self.devices, self._unit_of_entity ) + template = ( + self.template_catalog.get(self.tariff_config.import_.template_id) + if self.tariff_config is not None and self.tariff_config.import_.template_id + else None + ) + includes = template.price_includes if isinstance(template, TariffTemplate) else None + return [*items, *check_tariff(self.tariff_config, includes)] async def preview(self, fragment: Mapping[str, Any]) -> list[PreviewItem]: ids = list(dict.fromkeys(entity_id for _, entity_id, _ in collect_refs(fragment))) @@ -970,9 +1073,12 @@ async def import_config(self, data: object) -> list[str]: async def _reload_live_sections(self, *, resubscribe: bool) -> None: """After a restore or import: re-read what the control layer runs on and apply it.""" before = (self.site, self.devices, self.region) + tariff_before = self.tariff_config await self._load_live_sections() if resubscribe: await self._resubscribe() + if self.tariff_config != tariff_before or (self.site, self.region) != before[::2]: + await self._rebuild_tariff() if (self.site, self.devices, self.region) != before: await self._rebuild_stack() elif self.stack is not None and self.goals is not None: diff --git a/suncore/app/settings.py b/suncore/app/settings.py index 1845194..31863de 100644 --- a/suncore/app/settings.py +++ b/suncore/app/settings.py @@ -72,6 +72,13 @@ class Settings(BaseSettings): templates_dir: Path = Field(default_factory=default_templates_dir) """Built-in templates; user templates are read from ``/templates`` (not in demo).""" + tariff_refresh_interval_s: int = Field(default=3600, ge=60, le=86_400) + """Spacing of the regular price refresh (Tibber, Nord Pool: once per hour).""" + tariff_tomorrow_after: time = time(13, 0) + """Local time from which tomorrow's day-ahead prices are expected (UNVERIFIED).""" + tariff_tomorrow_poll_s: int = Field(default=900, ge=60, le=86_400) + """Spacing of the asks between that time and the arrival of tomorrow's prices.""" + _options_path: ClassVar[Path] = DEFAULT_OPTIONS_PATH @classmethod diff --git a/suncore/core/actions.py b/suncore/core/actions.py index aa90547..0bd9a17 100644 --- a/suncore/core/actions.py +++ b/suncore/core/actions.py @@ -14,6 +14,7 @@ READ_ONLY_ACTIONS: Final[frozenset[str]] = frozenset( { "tibber.get_prices", + "nordpool.get_prices_for_date", "solcast_solar.query_forecast_data", "weather.get_forecasts", } diff --git a/suncore/core/config.py b/suncore/core/config.py index e9d7cfb..a45e4f1 100644 --- a/suncore/core/config.py +++ b/suncore/core/config.py @@ -8,7 +8,7 @@ from __future__ import annotations import itertools -from collections.abc import Mapping +from collections.abc import Collection, Mapping from typing import Annotated, Any, Final, Literal, Self from zoneinfo import ZoneInfo, ZoneInfoNotFoundError @@ -37,6 +37,15 @@ Price = Annotated[float, Field(ge=0, le=100)] """Currency per kWh.""" +ActionParamName = Annotated[str, StringConstraints(min_length=1, max_length=64)] +ActionParamValue = ( + Annotated[str, StringConstraints(min_length=1, max_length=200)] + | Annotated[ + list[Annotated[str, StringConstraints(min_length=1, max_length=64)]], + Field(min_length=1, max_length=16), + ] +) +"""A request field value of a tariff template's action: text, or a list of texts.""" class _Frozen(BaseModel): @@ -89,6 +98,35 @@ class ImportTariff(_Frozen): fixed_price: Price | None = None formula: PriceFormula | None = None tou: TouTariff | None = None + role_entities: dict[RoleName, EntityRef] = Field(default_factory=dict) + """Entities of the template's roles besides the main one (``price_entity`` is the role + ``price``), e.g. Octopus ``current_day_rates`` and ``next_day_rates`` (Phase 4 WP4).""" + action_params: dict[ActionParamName, ActionParamValue] = Field(default_factory=dict) + """Values for the request fields the template's action asks the user for (Nord Pool + ``config_entry``, ``areas``, ``currency``); the template names which are required.""" + series_key: Annotated[str, StringConstraints(min_length=1, max_length=120)] | None = None + """Which entry of a multi-entry action response to read (Tibber home name, Nord Pool + area) when the response holds more than one; ``None`` = the only one.""" + price_includes: PriceIncludes | None = None + """The user's statement about a source whose content depends on their setup (ENTSO-E + with a modifier template): overrides the template's ``price_includes``.""" + + @model_validator(mode="after") + def _source_settings(self) -> Self: + if self.kind != "dynamic" and ( + self.role_entities + or self.action_params + or self.series_key is not None + or self.price_includes is not None + ): + raise invalid( + "import_source_dynamic_only", + "tariff.import: source settings (`role_entities`, `action_params`, " + "`series_key`, `price_includes`) need kind `dynamic`", + ) + if "price" in self.role_entities: + raise invalid("import_role_price", "tariff.import: the role `price` is `price_entity`") + return self @model_validator(mode="after") def _consistent(self) -> Self: @@ -194,7 +232,8 @@ class TariffConfig(_Frozen): export: ExportTariff def entity_refs(self) -> list[EntityRef]: - return [self.import_.price_entity] if self.import_.price_entity is not None else [] + refs = [self.import_.price_entity] if self.import_.price_entity is not None else [] + return [*refs, *self.import_.role_entities.values()] # --- forecast ----------------------------------------------------------------- @@ -309,6 +348,29 @@ def formula_on_all_in_source( ) +def missing_action_params( + tariff: TariffConfig, template_id: str, required: Collection[str] +) -> list[tuple[str, PydanticCustomError]]: + """The request fields a template's action needs that ``tariff.import.action_params`` lacks. + + ``required`` are the names the template marks as required (the catalogue knows them, the + model does not - the API passes them in, like for :func:`formula_on_all_in_source`). + """ + return [ + ( + name, + invalid( + "import_param_missing", + "tariff.import: template {template_id} needs the setting {field}", + template_id=template_id, + field=name, + ), + ) + for name in required + if name not in tariff.import_.action_params + ] + + def migrate_tariff_v2_to_v3(body: dict[str, Any]) -> dict[str, Any]: """Tariff v3 only adds optional fields (``formula``, kind ``tou``): unchanged body.""" return body diff --git a/suncore/core/series.py b/suncore/core/series.py index e08fbfb..1716c74 100644 --- a/suncore/core/series.py +++ b/suncore/core/series.py @@ -465,8 +465,9 @@ def segments_from_points( * ``d == cur``: the segment continues; * ``d`` is an accepted step (expected or other) and either not a multiple of ``cur`` - or the next distance is ``d`` again (or the point is the last but one): a - **resolution change** - a new segment with step ``d`` starts at this point; + or the next distance is ``d`` again: a **resolution change** - a new segment with step + ``d`` starts at this point. The next distance has to confirm the rhythm, so at the end of + the list a multiple of ``cur`` is a gap, not a change; * ``d`` is a multiple of ``cur``: a **gap** - the point lasts ``cur`` and the missing slots become ``None`` (a gap is never filled with a neighbour's value); * anything else raises ``ValueError`` (irregular timestamps; SunCore never guesses). @@ -502,7 +503,7 @@ def close() -> None: if d == cur: values.append(value) continue - steady = i + 1 >= len(distances) or distances[i + 1] == d + steady = i + 1 < len(distances) and distances[i + 1] == d if d in accepted and (d % cur != timedelta(0) or steady): close() cur, begin, values = d, stamps[i], [value] diff --git a/suncore/core/tariff.py b/suncore/core/tariff.py index 3605ad7..c669721 100644 --- a/suncore/core/tariff.py +++ b/suncore/core/tariff.py @@ -175,11 +175,19 @@ def grid_fee_at(self, at: datetime | None, tz: tzinfo) -> float: return entry.fee return self.grid_fee - def apply(self, spot: float, at: datetime | None, tz: tzinfo) -> float: - """End price for ``spot`` at ``at`` (``None``: the base grid fee is used).""" + def end_price(self, spot: float, at: datetime | None, tz: tzinfo) -> float: + """End price for ``spot`` at ``at`` (``None``: the base grid fee is used). + + Callers outside ``core`` use this name: ``.apply(`` is reserved by the architecture + boundary test for the actuator write path (``tests/safety/test_boundary.py``, rule 1). + """ net = spot * self.spot_multiplier + self.grid_fee_at(at, tz) + self.levies + self.margin return net * (1 + self.vat_pct / 100) + def apply(self, spot: float, at: datetime | None, tz: tzinfo) -> float: + """Deprecated alias of :meth:`end_price` (the 4-A name); new code calls ``end_price``.""" + return self.end_price(spot, at, tz) + # --- HT/NT (time of use) --------------------------------------------------------------- diff --git a/suncore/core/wizard.py b/suncore/core/wizard.py index d4fe082..9d30e4f 100644 --- a/suncore/core/wizard.py +++ b/suncore/core/wizard.py @@ -22,9 +22,10 @@ from typing import Any, Final, Literal from suncore.core.balance import FlowSnapshot, compute_flows -from suncore.core.config import DevicesConfig +from suncore.core.config import DevicesConfig, TariffConfig from suncore.core.decisions import Reason from suncore.core.devices import DeviceConfig, DeviceKind +from suncore.core.series import PriceIncludes from suncore.core.signals import Quality, Sample from suncore.core.site import ENTITY_ID_PATTERN, EntityRef, SiteConfig from suncore.core.units import Dimension, apply_invert, to_base @@ -335,6 +336,23 @@ def _check_duplicate_units( return items +def check_tariff( + tariff: TariffConfig | None, template_includes: PriceIncludes | None +) -> list[CheckItem]: + """Findings about the tariff: a spot-only import price without a price formula. + + ``template_includes`` is the template's ``price_includes`` (``None`` = no template); the + user's own statement in the tariff wins. A bare spot price is neither what the household + pays nor something the planner may optimise against (Phase 4 plan, 4-F refuses it). + """ + if tariff is None or tariff.import_.kind != "dynamic" or tariff.import_.formula is not None: + return [] + includes = tariff.import_.price_includes or template_includes + if includes != "spot_only": + return [] + return [_item("warn", "wizard.check.tariff_spot_without_formula", "tariff")] + + def run_system_check( site: SiteConfig | None, samples: Mapping[str, Sample], diff --git a/suncore/sim/demo_devices.py b/suncore/sim/demo_devices.py index a86bd2a..6a2ed44 100644 --- a/suncore/sim/demo_devices.py +++ b/suncore/sim/demo_devices.py @@ -122,10 +122,16 @@ def _gauss(x: float, centre: float, sigma: float) -> float: return math.exp(-0.5 * ((x - centre) / sigma) ** 2) -def sim_price(when: datetime) -> float: - """Synthetic dynamic price in EUR/kWh for the 15 min slot containing ``when``.""" +def sim_price(when: datetime, profile: str = "default") -> float: + """Synthetic dynamic price in EUR/kWh for the 15 min slot containing ``when``. + + ``profile`` ``negative_midday`` deepens the midday dip so that the price is negative + between about 11:30 and 14:30 (the minimum is -0.08 EUR/kWh at 13:00). + """ hour = when.hour + (when.minute // 15) * 0.25 - price = 0.30 + 0.12 * _gauss(hour, 19.0, 2.0) - 0.10 * _gauss(hour, 13.0, 2.5) + dip = 0.38 if profile == "negative_midday" else 0.10 + sigma = 2.0 if profile == "negative_midday" else 2.5 + price = 0.30 + 0.12 * _gauss(hour, 19.0, 2.0) - dip * _gauss(hour, 13.0, sigma) if hour < 5: price -= 0.04 return round(price, 3) @@ -333,7 +339,7 @@ def entities(self) -> list[DemoEntity]: [ DemoEntity( PRICE_ID, - f"{sim_price(state.time):.3f}", + f"{sim_price(state.time, self.scenario.prices.profile):.3f}", { "friendly_name": "Sim electricity price", "unit_of_measurement": f"{PRICE_CURRENCY}/kWh", diff --git a/suncore/sim/fake_ha.py b/suncore/sim/fake_ha.py index 41edd80..94bb912 100644 --- a/suncore/sim/fake_ha.py +++ b/suncore/sim/fake_ha.py @@ -430,7 +430,7 @@ async def call_action_response( self, domain: str, service: str, - data: Mapping[str, Any] | None = None, # noqa: ARG002 + data: Mapping[str, Any] | None = None, *, target: Mapping[str, Any] | None = None, # noqa: ARG002 min_interval_s: float | None = None, @@ -447,16 +447,44 @@ async def call_action_response( raise ActionRateLimitedError(key, self._action_limiter.retry_after(key)) now = self._house_state.time if self._house_state is not None else self._clock() if (domain, service) == ("tibber", "get_prices"): - start = now.replace(minute=(now.minute // 15) * 15, second=0, microsecond=0) - slots = [start + timedelta(minutes=15 * i) for i in range(96)] - prices = [{"start_time": t.isoformat(), "price": sim_price(t)} for t in slots] - return {"prices": {"Home": prices}} + return {"prices": {"Home": self._tibber_prices(now, data)}} if (domain, service) == ("solcast_solar", "query_forecast_data"): today = self._published.get(FORECAST_TODAY_ID) slots_data = today.attributes.get("detailedForecast", []) if today else [] return {"data": list(slots_data)} raise CommandError("not_found", f"Service {domain}.{service} not found.") + def _tibber_prices(self, now: datetime, data: Mapping[str, Any] | None) -> list[dict[str, Any]]: + """``tibber.get_prices`` like core's ``services.py`` (re-read 2026-10-16): 15-minute + slots ``start <= t < end``, ``start``/``end`` default to local today; tomorrow only + exists after ``scenario.prices.tomorrow_after_hour`` local time.""" + + def parse(name: str) -> datetime | None: + raw = (data or {}).get(name) + if not isinstance(raw, str): + return None + parsed = datetime.fromisoformat(raw) + return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=now.tzinfo) + + midnight = now.replace(hour=0, minute=0, second=0, microsecond=0) + start = parse("start") or midnight + end = parse("end") or start + timedelta(days=1) + if start >= end: + end = start + timedelta(days=1) + params = self._scenario.prices + published_until = midnight + timedelta( + days=2 if now.hour >= params.tomorrow_after_hour else 1 + ) + end = min(end, published_until) + slots: list[dict[str, Any]] = [] + t = max(start, midnight) + t = t.replace(minute=(t.minute // 15) * 15, second=0, microsecond=0) + while t < end: + if t >= start: + slots.append({"start_time": t.isoformat(), "price": sim_price(t, params.profile)}) + t += timedelta(minutes=15) + return slots + def entity_metas(self) -> list[EntityMeta]: """Registry entries joined with the published states (what detection ranks).""" self._require_connected() diff --git a/suncore/sim/scenario.py b/suncore/sim/scenario.py index 28ddce0..52fe9c9 100644 --- a/suncore/sim/scenario.py +++ b/suncore/sim/scenario.py @@ -155,6 +155,20 @@ class ControlParams(BaseModel): """Overrides of ``ControlSettings`` (``smoothing_s``, ``min_write_interval_s`` ...).""" +PriceProfile = Literal["default", "negative_midday"] +"""``negative_midday``: the spot price turns negative around 13:00 (sunny weekends in DE).""" + + +class PriceParams(BaseModel): + """The simulated dynamic price (what the fake ``tibber.get_prices`` answers).""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + profile: PriceProfile = "default" + tomorrow_after_hour: int = Field(default=13, ge=0, le=23) + """Local hour from which tomorrow's prices are published (the real market: afternoon).""" + + class Scenario(BaseModel): """A complete simulator scenario.""" @@ -172,6 +186,7 @@ class Scenario(BaseModel): devices: tuple[SimDeviceSpec, ...] = () manual: tuple[ManualEvent, ...] = () control: ControlParams = ControlParams() + prices: PriceParams = PriceParams() @model_validator(mode="after") def _check(self) -> Scenario: diff --git a/suncore/sim/scenarios/negative_prices.yaml b/suncore/sim/scenarios/negative_prices.yaml new file mode 100644 index 0000000..f318fd1 --- /dev/null +++ b/suncore/sim/scenarios/negative_prices.yaml @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: Apache-2.0 +name: negative_prices +description: Clear summer weekend in Bavaria, the day-ahead price turns negative around noon. +start: "2026-06-21T00:00:00+02:00" +duration_s: 86400 +step_s: 60 +house: + seed: 1 + pv: {kwp: 8.0, latitude: 48.0, longitude: 11.0} + load: {noise_fraction: 0.1} + battery: {capacity_wh: 10000, initial_soc_pct: 30} +outdoor: {mean_c: 26.0, amplitude_c: 7.0} +clouds: + - {at_s: 21600, factor: 0.9} + - {at_s: 32400, factor: 1.0} +prices: + profile: negative_midday + tomorrow_after_hour: 13 diff --git a/suncore/tariff/__init__.py b/suncore/tariff/__init__.py index df1bcf7..60a1784 100644 --- a/suncore/tariff/__init__.py +++ b/suncore/tariff/__init__.py @@ -1,2 +1,86 @@ # SPDX-License-Identifier: Apache-2.0 -"""SunCore tariff package (Phase 0 placeholder, see docs/architecture.md).""" +"""Tariff adapters, price formula application and the price service (Phase 4 WP4). + +* :mod:`suncore.tariff.parse` - pure parsing of price lists (timestamps, shapes, segments); +* :mod:`suncore.tariff.engine` - a :class:`TariffTemplate` becomes a price source; +* :mod:`suncore.tariff.sources` - fixed and HT/NT sources, the source protocol; +* :mod:`suncore.tariff.pricing` - formula, export side and the negative-price rule; +* :mod:`suncore.tariff.service` - :class:`TariffService`: refresh, cache, store, serve. + +Home Assistant is reached only through the injected ``ActionCaller`` and ``AttributeReader`` +(wired in ``suncore.app.adapters``). +""" + +from suncore.tariff.engine import ( + ActionCaller, + CurrentPriceSource, + EntityReader, + EntityReading, + SourceBinding, + TemplatePriceSource, +) +from suncore.tariff.errors import ( + AmbiguousSeriesError, + CurrencyMismatchError, + ExportConfigError, + ExportTiersError, + MalformedPayloadError, + MissingEntityError, + MissingParamError, + SourceFailedError, + SourceThrottledError, + SourceUnavailableError, + TariffError, + UnitMismatchError, +) +from suncore.tariff.pricing import apply_import_formula, export_base_price, planning_prices +from suncore.tariff.report import PriceReport +from suncore.tariff.service import ( + PriceStore, + RefreshResult, + ServiceSettings, + TariffPlan, + TariffService, +) +from suncore.tariff.sources import ( + FixedPriceSource, + SegmentSource, + SourceData, + TouPriceSource, + finest_series, +) + +__all__ = [ + "ActionCaller", + "AmbiguousSeriesError", + "CurrencyMismatchError", + "CurrentPriceSource", + "EntityReader", + "EntityReading", + "ExportConfigError", + "ExportTiersError", + "FixedPriceSource", + "MalformedPayloadError", + "MissingEntityError", + "MissingParamError", + "PriceReport", + "PriceStore", + "RefreshResult", + "SegmentSource", + "ServiceSettings", + "SourceBinding", + "SourceData", + "SourceFailedError", + "SourceThrottledError", + "SourceUnavailableError", + "TariffError", + "TariffPlan", + "TariffService", + "TemplatePriceSource", + "TouPriceSource", + "UnitMismatchError", + "apply_import_formula", + "export_base_price", + "finest_series", + "planning_prices", +] diff --git a/suncore/tariff/engine.py b/suncore/tariff/engine.py new file mode 100644 index 0000000..3ecc65b --- /dev/null +++ b/suncore/tariff/engine.py @@ -0,0 +1,431 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Template-driven price adapter: a :class:`TariffTemplate` becomes a price source. + +The template (``price_series``) says where the curve is: the response of a read-only action +(Tibber, Nord Pool) or an attribute of one or more entities (ENTSO-E, EPEX Spot, Octopus, +generic). This module knows the shapes, not the integrations: field names, units and paths +come from the template; the rules below are the contract of the schema. + +* **Grid.** The native step is derived from the data: ``end - start`` per slot when the + template names ``end_field`` (Nord Pool, EPEX Spot, Octopus), otherwise the template's + ``resolution_min`` or the most common spacing of the timestamps (Tibber, ENTSO-E). Changes + between 15 and 60 minutes inside a list start a new segment; missing slots are ``None``. +* **Unit.** ``/MWh`` values are divided by 1000; ``{currency}`` is the region's currency. +* **Time.** Timestamps need a UTC offset (see :mod:`suncore.tariff.parse`); request dates of + ``date_field`` actions are local dates of the site's zone (DST: a day has 23 or 25 hours). +* **No I/O of its own.** Actions go through an injected :class:`ActionCaller` + (``suncore.app.adapters`` is the only app module allowed to call actions), attributes + through an injected :data:`EntityReader` of the entity cache. +""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass, field +from datetime import date, datetime, time, timedelta, tzinfo +from typing import Any, Final, Protocol +from zoneinfo import ZoneInfo + +from suncore.core.series import ( + PLANNING_STEP, + PriceIncludes, + PriceSeries, + SeriesUnit, + TimeRange, + TimeSeries, + floor_to_step, +) +from suncore.tariff.errors import ( + CurrencyMismatchError, + MalformedPayloadError, + MissingEntityError, + MissingParamError, + SourceUnavailableError, + UnitMismatchError, +) +from suncore.tariff.parse import ( + ParseReport, + RawSlot, + build_segments, + clip_series, + expand_path, + normalise, + parse_number, + select_series, + slots_from_mapping, + slots_from_records, + walk, +) +from suncore.tariff.sources import SourceData, SourceKind, finest_series +from suncore.tariff.units import ( + currency_of, + divisor_to_kwh, + energy_scale, + normalise_price_unit, + resolve_value_unit, +) +from suncore.templates.models import ActionSeries, AttributeSeries, TariffTemplate + +DEFAULT_MIN_INTERVAL_S: Final = 30.0 +"""Floor between two calls of the same action (``ActionRateLimiter`` default, follow-up A3).""" + + +class ActionCaller(Protocol): + """Calls a read-only action and returns its response object. + + Implemented in ``suncore.app.adapters`` on top of ``HAConnection.call_action_response``; + it raises :class:`~suncore.tariff.errors.SourceThrottledError` for a call skipped by the + rate limiter and :class:`~suncore.tariff.errors.SourceFailedError` for anything else. + """ + + async def __call__( + self, + domain: str, + service: str, + data: Mapping[str, Any], + *, + min_interval_s: float, + max_wait_s: float, + ) -> Mapping[str, Any]: ... + + +@dataclass(frozen=True, slots=True) +class EntityReading: + """State text and attributes of an entity as last seen.""" + + state: str + attributes: Mapping[str, Any] + + +EntityReader = Callable[[str], EntityReading | None] +"""Current reading of an entity, ``None`` while it is unknown to Home Assistant or +``unavailable``.""" + + +@dataclass(frozen=True, slots=True) +class SourceBinding: + """What the user's tariff configuration adds to a template (see ``ImportTariff``).""" + + tz: tzinfo + entities: Mapping[str, str] = field(default_factory=dict) + """Template role -> entity id (``price_entity`` is the role ``price``).""" + action_params: Mapping[str, str | Sequence[str]] = field(default_factory=dict) + series_key: str | None = None + price_includes: PriceIncludes | None = None + """The user's statement overriding the template's classification.""" + currency: str = "EUR" + min_interval_s: float = DEFAULT_MIN_INTERVAL_S + + +def _local_midnight(day: date, tz: tzinfo) -> datetime: + return datetime.combine(day, time.min, tzinfo=tz) + + +def request_dates(window: TimeRange, now: datetime, tz: tzinfo, max_horizon_h: int) -> list[date]: + """Local delivery dates to ask a per-date action for. + + From the window's first local day to the last, but not beyond today plus + ``ceil(max_horizon_h / 24)`` days (Nord Pool: "one day in the future" -> 24 h). + """ + first = window.start.astimezone(tz).date() + last = (window.end - timedelta(microseconds=1)).astimezone(tz).date() + limit = now.astimezone(tz).date() + timedelta(days=-(-max_horizon_h // 24)) + last = min(last, limit) + days = (last - first).days + return [first + timedelta(days=i) for i in range(max(0, days + 1))] + + +class TemplatePriceSource: + """A :class:`SegmentSource` (and ``PriceSource``) built from a dynamic tariff template.""" + + def __init__( + self, + template: TariffTemplate, + binding: SourceBinding, + *, + action: ActionCaller | None = None, + attributes: EntityReader | None = None, + clock: Callable[[], datetime], + ) -> None: + series = template.price_series + if template.tariff_type != "dynamic" or series is None: + msg = f"template {template.id} is not a dynamic tariff with a price_series" + raise ValueError(msg) + if isinstance(series, ActionSeries) and action is None: + msg = f"template {template.id} reads an action: an ActionCaller is required" + raise ValueError(msg) + if isinstance(series, AttributeSeries) and attributes is None: + msg = f"template {template.id} reads attributes: an EntityReader is required" + raise ValueError(msg) + self._template = template + self._series = series + self._binding = binding + self._action = action + self._attributes = attributes + self._clock = clock + self._unit = resolve_value_unit(series.fields.value_unit, binding.currency) + self._divisor = divisor_to_kwh(self._unit) + self._resolution = ( + None if template.resolution_min is None else timedelta(minutes=template.resolution_min) + ) + assert template.price_includes is not None # validated: required for dynamic + self._includes: PriceIncludes = binding.price_includes or template.price_includes + + # --- SegmentSource --------------------------------------------------------------- + + @property + def source_id(self) -> str: + return self._template.id + + @property + def kind(self) -> SourceKind: + return "dynamic" + + @property + def price_includes(self) -> PriceIncludes: + return self._includes + + @property + def uses_action(self) -> bool: + return isinstance(self._series, ActionSeries) + + @property + def watched_entities(self) -> tuple[str, ...]: + return tuple(dict.fromkeys(self._binding.entities.values())) + + @property + def delivery_tz(self) -> tzinfo | None: + series = self._series + if isinstance(series, ActionSeries) and series.date_tz is not None: + return ZoneInfo(series.date_tz) + return None + + def _check_currency(self, source_currency: str | None, where: str) -> None: + """Refuse prices in another currency than the region's (a silent mix-up of money).""" + expected = self._binding.currency + if source_currency is not None and source_currency.upper() != expected: + raise CurrencyMismatchError( + f"{where} is in {source_currency}, the region uses {expected}", + source_currency=source_currency.upper(), + region_currency=expected, + ) + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: + self._check_currency(currency_of(self._unit), "the template") + if isinstance(self._series, ActionSeries): + slots, bad = await self._from_action(self._series, window, now) + else: + slots, bad = self._from_attributes(self._series) + normalised, report = normalise(slots, unreadable=bad) + series = build_segments(normalised, divisor=self._divisor, resolution=self._resolution) + clipped = [c for s in series if (c := clip_series(s, window.start, window.end))] + return SourceData( + segments=tuple(self._price_series(s) for s in clipped), + report=ParseReport( + points=report.points, + unreadable_values=report.unreadable_values, + duplicates=report.duplicates, + overlaps=report.overlaps, + ), + ) + + async def fetch(self, window: TimeRange) -> PriceSeries: + """``PriceSource`` protocol: one series on the finest native step.""" + data = await self.fetch_segments(window, self._clock()) + return finest_series(self.source_id, self._includes, data.segments, window) + + def _price_series(self, series: TimeSeries) -> PriceSeries: + return PriceSeries( + source_id=self.source_id, price_includes=self._includes, import_price=series + ) + + # --- action ---------------------------------------------------------------------- + + def _request_base(self, series: ActionSeries) -> dict[str, Any]: + data: dict[str, Any] = {} + for param in series.params: + value = self._binding.action_params.get(param.name) + if value is None: + if param.required: + raise MissingParamError( + f"action field `{param.name}` is not configured", field=param.name + ) + continue + data[param.name] = value if isinstance(value, str) else list(value) + if param.name == "currency" and isinstance(value, str): + self._check_currency(value, "the action's `currency` field") + return data + + async def _from_action( + self, series: ActionSeries, window: TimeRange, now: datetime + ) -> tuple[list[RawSlot], int]: + assert self._action is not None + tz = self._binding.tz + base = self._request_base(series) + requests: list[dict[str, Any]] + if series.date_field is not None: + market_tz = ZoneInfo(series.date_tz) if series.date_tz is not None else tz + dates = request_dates(window, now, market_tz, series.max_horizon_h) + requests = [{**base, series.date_field: d.isoformat()} for d in dates] + else: + data = dict(base) + if series.start_field is not None: + first = window.start.astimezone(tz).date() + data[series.start_field] = _local_midnight(first, tz).isoformat() + if series.end_field is not None: + last = (window.end - timedelta(microseconds=1)).astimezone(tz).date() + data[series.end_field] = _local_midnight(last + timedelta(days=1), tz).isoformat() + requests = [data] + slots: list[RawSlot] = [] + bad = 0 + for index, data in enumerate(requests): + response = await self._action( + series.domain, + series.service, + data, + min_interval_s=self._binding.min_interval_s, + # the second and later dates wait for the limiter's next slot + max_wait_s=0.0 if index == 0 else self._binding.min_interval_s + 1.0, + ) + candidates = expand_path(response, series.response_path) + node = select_series(candidates, self._binding.series_key) + if node is None: + continue + part, unreadable = slots_from_records(node, series.fields) + slots.extend(part) + bad += unreadable + return slots, bad + + # --- attributes ------------------------------------------------------------------ + + def _check_unit(self, attrs: Mapping[str, Any]) -> None: + """Refuse an entity whose unit says per MWh where the template says per kWh (or back). + + A silent factor 1000 would poison every plan; an entity without a price unit + (event entities, template sensors) is not checked. + """ + raw = attrs.get("unit_of_measurement") + if not isinstance(raw, str): + return + normalised = normalise_price_unit(raw) + if energy_scale(normalised) is not None: + self._check_currency(currency_of(normalised), f"the sensor unit {raw!r}") + seen = energy_scale(normalised) + expected = energy_scale(self._unit) + if seen is not None and expected is not None and seen != expected: + raise UnitMismatchError( + f"sensor unit {raw!r} vs template unit {self._unit!r}", + sensor_unit=raw, + template_unit=self._unit, + ) + + def _from_attributes(self, series: AttributeSeries) -> tuple[list[RawSlot], int]: + assert self._attributes is not None + slots: list[RawSlot] = [] + bad = 0 + seen_entity = False + found_attribute = False + for role in series.roles: + entity_id = self._binding.entities.get(role) + if entity_id is None: + if self._template.roles[role].required: + raise MissingEntityError(f"no entity for role `{role}`", role=role) + continue + reading = self._attributes(entity_id) + if reading is None: + continue + attrs = reading.attributes + seen_entity = True + self._check_unit(attrs) + value = attrs.get(series.attribute) + if value is None: + continue + found_attribute = True + if series.list_path is not None: + value = walk(value, series.list_path) + if series.shape == "mapping": + part, unreadable = slots_from_mapping(value) + else: + part, unreadable = slots_from_records(value, series.fields) + slots.extend(part) + bad += unreadable + if not slots and not seen_entity: + raise SourceUnavailableError("no price entity is available") + if not slots and not found_attribute: + raise MalformedPayloadError( + f"attribute `{series.attribute}` is missing on the price entity", + attribute=series.attribute, + ) + return slots, bad + + +class CurrentPriceSource: + """A dynamic tariff with only a price sensor (no template): the current slot's price. + + The state is the price of the running 15-minute slot (units per kWh, as the wizard asks + for); nothing is known about later slots, so the series is one slot long. Better than no + price, much worse than a curve - the wizard recommends a template. + """ + + def __init__( + self, + entity_id: str, + reader: EntityReader, + *, + price_includes: PriceIncludes, + clock: Callable[[], datetime], + ) -> None: + self._entity_id = entity_id + self._reader = reader + self._includes = price_includes + self._clock = clock + + @property + def source_id(self) -> str: + return "entity" + + @property + def kind(self) -> SourceKind: + return "dynamic" + + @property + def price_includes(self) -> PriceIncludes: + return self._includes + + @property + def uses_action(self) -> bool: + return False + + @property + def watched_entities(self) -> tuple[str, ...]: + return (self._entity_id,) + + @property + def delivery_tz(self) -> tzinfo | None: + return None + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: # noqa: ARG002 + reading = self._reader(self._entity_id) + if reading is None: + raise SourceUnavailableError("the price sensor is not available") + value = parse_number(reading.state) + if value is None: + raise SourceUnavailableError("the price sensor has no numeric state") + divisor = 1.0 + unit = reading.attributes.get("unit_of_measurement") + if isinstance(unit, str) and energy_scale(normalise_price_unit(unit)) == "MWh": + divisor = 1000.0 + series = TimeSeries( + start=floor_to_step(now), + step=PLANNING_STEP, + values=(value / divisor,), + unit=SeriesUnit.PRICE, + ) + price = PriceSeries( + source_id=self.source_id, price_includes=self._includes, import_price=series + ) + return SourceData(segments=(price,), report=ParseReport(points=1)) + + async def fetch(self, window: TimeRange) -> PriceSeries: + data = await self.fetch_segments(window, self._clock()) + return data.segments[0] diff --git a/suncore/tariff/errors.py b/suncore/tariff/errors.py new file mode 100644 index 0000000..07c16be --- /dev/null +++ b/suncore/tariff/errors.py @@ -0,0 +1,107 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Errors of the tariff adapters; each carries a catalogue key (``tariff.error.*``). + +The keys are rendered by the frontend's ICU catalogue (``en.json`` / ``de.json``); ``args`` +are the ICU arguments. An error never carries free text for the user. +""" + +from __future__ import annotations + +from typing import Any, ClassVar, Final + +ERR_UNAVAILABLE: Final = "tariff.error.source_unavailable" +ERR_MALFORMED: Final = "tariff.error.malformed_payload" +ERR_AMBIGUOUS: Final = "tariff.error.ambiguous_series" +ERR_MISSING_PARAM: Final = "tariff.error.missing_param" +ERR_MISSING_ROLE: Final = "tariff.error.missing_entity" +ERR_THROTTLED: Final = "tariff.error.throttled" +ERR_FAILED: Final = "tariff.error.action_failed" +ERR_UNIT_MISMATCH: Final = "tariff.error.unit_mismatch" +ERR_CURRENCY_MISMATCH: Final = "tariff.error.currency_mismatch" +ERR_EXPORT_NEEDS_KWP: Final = "tariff.error.export_needs_kwp" +ERR_EXPORT_TIERS: Final = "tariff.error.export_tiers" + + +class TariffError(Exception): + """Base class: ``key`` is the catalogue key, ``args`` its ICU arguments.""" + + key: ClassVar[str] = ERR_FAILED + + def __init__(self, detail: str = "", **args: Any) -> None: + super().__init__(detail or self.key) + self.detail = detail + self.args_: dict[str, Any] = args + + @property + def message_args(self) -> dict[str, Any]: + return dict(self.args_) + + +class SourceUnavailableError(TariffError): + """The price entity (or all of them) is unknown, ``unavailable`` or has no price list.""" + + key = ERR_UNAVAILABLE + + +class MalformedPayloadError(TariffError): + """The response or attribute does not have the documented shape.""" + + key = ERR_MALFORMED + + +class AmbiguousSeriesError(TariffError): + """A response holds several series (homes, areas) and the configuration names none.""" + + key = ERR_AMBIGUOUS + + +class MissingParamError(TariffError): + """The action needs a request field the tariff configuration does not supply.""" + + key = ERR_MISSING_PARAM + + +class MissingEntityError(TariffError): + """A role the series is read from has no configured entity.""" + + key = ERR_MISSING_ROLE + + +class SourceThrottledError(TariffError): + """The action was asked for too often and skipped (not a failure: use the last data).""" + + key = ERR_THROTTLED + + def __init__(self, retry_after_s: float, detail: str = "") -> None: + super().__init__(detail, retry_after_s=retry_after_s) + self.retry_after_s = retry_after_s + + +class SourceFailedError(TariffError): + """Home Assistant or the integration failed to answer the action.""" + + key = ERR_FAILED + + +class UnitMismatchError(TariffError): + """The entity's price unit (per kWh or per MWh) contradicts the template's value unit.""" + + key = ERR_UNIT_MISMATCH + + +class CurrencyMismatchError(UnitMismatchError): + """The source's currency differs from the region's (prices would be in the wrong money).""" + + key = ERR_CURRENCY_MISMATCH + + +class ExportConfigError(TariffError): + """The export tariff cannot be turned into a price (tiered without the plant size).""" + + key = ERR_EXPORT_NEEDS_KWP + + +class ExportTiersError(ExportConfigError): + """The feed-in tiers do not cover the whole plant (or are not ordered).""" + + key = ERR_EXPORT_TIERS diff --git a/suncore/tariff/parse.py b/suncore/tariff/parse.py new file mode 100644 index 0000000..960e283 --- /dev/null +++ b/suncore/tariff/parse.py @@ -0,0 +1,330 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Pure parsing of price lists (Phase 4 WP4): no I/O, no clock, time zones explicit. + +Shapes (all from ``docs/research/integrations.md``, pinned sources there): + +* Tibber ``tibber.get_prices``: ``{"prices": {"": [{"start_time": iso, "price": float}]}}``; +* Nord Pool ``nordpool.get_prices_for_date``: ``{"": [{"start", "end", "price"}]}``, UTC + ``+00:00``, currency per MWh; +* ENTSO-E ``prices`` attribute: ``[{"time": "2026-10-16 00:00:00+02:00", "price": float}]`` + (``str(datetime)``: a space instead of ``T``); +* EPEX Spot ``data`` attribute: ``[{"start_time", "end_time", "price_per_kwh"}]``, local ISO; +* Octopus ``rates`` attribute: ``[{"start", "end", "value_inc_vat"}]``, local datetimes; +* ``mapping`` shape: ``{iso_timestamp: value}``. + +A timestamp without a UTC offset is rejected (SunCore never guesses a zone); all arithmetic is +done in UTC, so a DST day of 23 h or 25 h needs no special case. +""" + +from __future__ import annotations + +import itertools +import math +from collections import Counter +from collections.abc import Iterable, Mapping, Sequence +from dataclasses import dataclass +from datetime import UTC, datetime, timedelta +from typing import Any, Final + +from suncore.core.series import SeriesUnit, TimeSeries, segments_from_points +from suncore.tariff.errors import AmbiguousSeriesError, MalformedPayloadError +from suncore.templates.models import SeriesFields + +DEFAULT_STEP: Final = timedelta(hours=1) +"""Step assumed when a list has a single point and the template names no resolution.""" +KNOWN_STEPS: Final = (timedelta(minutes=15), timedelta(hours=1)) +"""Resolutions SunCore accepts to change to inside one list (15 min <-> 60 min).""" + + +@dataclass(frozen=True, slots=True) +class RawSlot: + """One price point: ``start`` (UTC), optional ``end`` (UTC) and the value (``None`` = gap).""" + + start: datetime + end: datetime | None + value: float | None + + +@dataclass(frozen=True, slots=True) +class ParseReport: + """What the parser had to drop; shown as quality, never silently ignored.""" + + points: int = 0 + unreadable_values: int = 0 + """Points whose value was missing or not a finite number (they become gaps).""" + duplicates: int = 0 + """Points with a start already seen (the later one wins).""" + overlaps: int = 0 + """Points that start before the previous slot ends (dropped, the earlier one wins).""" + + +def parse_timestamp(value: object) -> datetime: + """An ISO 8601 timestamp (``T`` or space separated, ``Z`` or offset) as aware UTC. + + Accepts ``str(datetime)`` output (ENTSO-E) and ``datetime.isoformat()`` (EPEX Spot, + Octopus, Nord Pool, Tibber). Raises :class:`MalformedPayloadError` for anything else, + including a timestamp without an offset. + """ + if isinstance(value, datetime): + parsed = value + elif isinstance(value, str): + try: + parsed = datetime.fromisoformat(value.strip()) + except ValueError as exc: + msg = f"not an ISO 8601 timestamp: {value!r}" + raise MalformedPayloadError(msg) from exc + else: + msg = f"timestamp is neither text nor datetime: {type(value).__name__}" + raise MalformedPayloadError(msg) + if parsed.tzinfo is None or parsed.utcoffset() is None: + msg = f"timestamp without a UTC offset: {value!r}" + raise MalformedPayloadError(msg) + return parsed.astimezone(UTC) + + +def parse_number(value: object) -> float | None: + """A finite number from a number or numeric text; ``None`` for everything else.""" + if isinstance(value, bool): + return None + if isinstance(value, int | float): + number = float(value) + elif isinstance(value, str): + try: + number = float(value.strip()) + except ValueError: + return None + else: + return None + return number if math.isfinite(number) else None + + +# --- locating the points --------------------------------------------------------------- + + +def walk(value: object, path: str) -> object: + """Follow a dotted path of mapping keys (no ``*``); ``MalformedPayloadError`` if absent.""" + node = value + for part in path.split("."): + if not isinstance(node, Mapping) or part not in node: + msg = f"path {path!r} not found at {part!r}" + raise MalformedPayloadError(msg) + node = node[part] + return node + + +def expand_path(payload: object, path: str) -> list[tuple[str, object]]: + """All ``(label, node)`` pairs a response path leads to; ``*`` fans out over a mapping. + + The label is the last expanded mapping key (home name, area) or ``""``. A path through a + missing key yields no candidate (an empty response is not an error); a path through a + non-mapping raises :class:`MalformedPayloadError`. + """ + found: list[tuple[str, object]] = [("", payload)] + for part in path.split("."): + nxt: list[tuple[str, object]] = [] + for label, node in found: + if not isinstance(node, Mapping): + msg = f"path {path!r}: {part!r} is not inside an object" + raise MalformedPayloadError(msg) + if part == "*": + nxt.extend((str(k), v) for k, v in node.items()) + elif part in node: + nxt.append((label, node[part])) + found = nxt + return found + + +def select_series(candidates: Sequence[tuple[str, object]], key: str | None) -> object | None: + """The one node of a fan-out: the entry named ``key`` or the only one. + + Raises :class:`AmbiguousSeriesError` when several entries exist and no key is configured + (SunCore never merges two homes' prices), and :class:`MalformedPayloadError` when the + configured key is absent while others exist. No candidate at all returns ``None``. + """ + if key is not None: + for label, node in candidates: + if label == key or label.casefold() == key.casefold(): + return node + if candidates: + msg = f"series key {key!r} not in the response" + raise MalformedPayloadError(msg, key=key, available=[c[0] for c in candidates]) + return None + if len(candidates) > 1: + raise AmbiguousSeriesError( + "the response holds several series", + available=", ".join(sorted(c[0] for c in candidates)), + ) + return candidates[0][1] if candidates else None + + +def _optional_stamp(value: object) -> datetime | None: + return None if value is None else parse_timestamp(value) + + +def slots_from_records(records: object, fields: SeriesFields) -> tuple[list[RawSlot], int]: + """Points from a list of objects named by ``fields``; also the count of unreadable values. + + A record without a timestamp is malformed (raises); a missing or non-numeric value is a + gap. ``fields.end_field`` gives the slot end when present in the record. + """ + if not isinstance(records, list): + msg = f"expected a list of price points, got {type(records).__name__}" + raise MalformedPayloadError(msg) + assert fields.timestamp_field is not None + assert fields.value_field is not None + slots: list[RawSlot] = [] + bad = 0 + for record in records: + if not isinstance(record, Mapping) or fields.timestamp_field not in record: + msg = f"price point without `{fields.timestamp_field}`" + raise MalformedPayloadError(msg) + value = parse_number(record.get(fields.value_field)) + bad += value is None + end = ( + _optional_stamp(record.get(fields.end_field)) if fields.end_field is not None else None + ) + slots.append(RawSlot(parse_timestamp(record[fields.timestamp_field]), end, value)) + return slots, bad + + +def slots_from_mapping(mapping: object) -> tuple[list[RawSlot], int]: + """Points from ``{iso_timestamp: value}``.""" + if not isinstance(mapping, Mapping): + msg = f"expected an object of timestamp -> value, got {type(mapping).__name__}" + raise MalformedPayloadError(msg) + slots: list[RawSlot] = [] + bad = 0 + for stamp, raw in mapping.items(): + value = parse_number(raw) + bad += value is None + slots.append(RawSlot(parse_timestamp(stamp), None, value)) + return slots, bad + + +# --- normalising and segmenting ---------------------------------------------------------- + + +def normalise( + slots: Iterable[RawSlot], *, unreadable: int = 0 +) -> tuple[list[RawSlot], ParseReport]: + """Sort by start, collapse duplicate starts (later wins) and drop overlapping slots. + + Merging two lists (Octopus current day + next day) therefore needs no special case. + Slots with an ``end`` not after their ``start`` are dropped as overlaps. + """ + ordered = sorted(enumerate(slots), key=lambda p: (p[1].start, p[0])) + unique: dict[datetime, RawSlot] = {} + total = 0 + for _, slot in ordered: + total += 1 + unique[slot.start] = slot # same start: the later one in input order wins + duplicates = total - len(unique) + result: list[RawSlot] = [] + overlaps = 0 + for slot in unique.values(): + if slot.end is not None and slot.end <= slot.start: + overlaps += 1 + continue + if result and (prev_end := result[-1].end) is not None and slot.start < prev_end: + overlaps += 1 + continue + result.append(slot) + report = ParseReport( + points=len(result), unreadable_values=unreadable, duplicates=duplicates, overlaps=overlaps + ) + return result, report + + +def infer_step(starts: Sequence[datetime], fallback: timedelta | None) -> timedelta: + """The resolution of a list without slot ends: the most common distance of neighbours. + + Ties go to the finer step. A single point uses ``fallback`` (the template's + ``resolution_min``), else one hour. + """ + distances = Counter(b - a for a, b in itertools.pairwise(starts)) + if not distances: + return fallback or DEFAULT_STEP + best = max(distances.values()) + return min(d for d, n in distances.items() if n == best) + + +def _explicit_segments(slots: Sequence[RawSlot], divisor: float) -> list[TimeSeries]: + """Segments for slots that all carry an ``end``: runs of equal length that touch.""" + segments: list[TimeSeries] = [] + run: list[RawSlot] = [] + + def close() -> None: + if run: + first = run[0] + assert first.end is not None + segments.append( + TimeSeries( + start=first.start, + step=first.end - first.start, + values=tuple(None if s.value is None else s.value / divisor for s in run), + unit=SeriesUnit.PRICE, + ) + ) + run.clear() + + for slot in slots: + assert slot.end is not None + if run: + prev = run[-1] + assert prev.end is not None + same_length = slot.end - slot.start == prev.end - prev.start + if not (same_length and slot.start == prev.end): + close() + run.append(slot) + close() + return segments + + +def build_segments( + slots: Sequence[RawSlot], *, divisor: float, resolution: timedelta | None +) -> tuple[TimeSeries, ...]: + """Regular ``currency/kWh`` segments from normalised slots. + + * every slot has an ``end`` (Nord Pool, EPEX Spot, Octopus): the slot length is + ``end - start`` and consecutive slots of equal length that touch form one segment, so a + 15/60-minute change or a gap just starts a new segment; + * otherwise (Tibber, ENTSO-E, mapping attributes): the resolution is the template's + ``resolution_min`` or the most common distance; 15 <-> 60 minutes changes inside the list + are accepted, missing slots become ``None`` (:func:`segments_from_points`). + + ``divisor`` converts the source unit to currency/kWh (``1000`` for per-MWh values). + """ + if not slots: + return () + if all(s.end is not None for s in slots): + return tuple(_explicit_segments(slots, divisor)) + expected = resolution or infer_step([s.start for s in slots], None) + other = {s for s in KNOWN_STEPS if s != expected} + points = [(s.start, None if s.value is None else s.value / divisor) for s in slots] + try: + return segments_from_points( + points, SeriesUnit.PRICE, expected_step=expected, other_steps=other + ) + except ValueError as exc: + raise MalformedPayloadError(str(exc)) from exc + + +def clip_series(series: TimeSeries, start: datetime, end: datetime) -> TimeSeries | None: + """The part of ``series`` that overlaps ``[start, end)`` (whole slots), else ``None``.""" + if series.end <= start or series.start >= end: + return None + first = max(0, (start - series.start) // series.step) + last = min(len(series), -(-(end - series.start) // series.step)) + if last <= first: + return None + return TimeSeries( + start=series.slot_start(first), + step=series.step, + values=series.values[first:last], + unit=series.unit, + ) + + +def as_attributes(value: Any) -> Mapping[str, Any]: + """Attributes mapping of an entity state (never ``None``).""" + return value if isinstance(value, Mapping) else {} diff --git a/suncore/tariff/pricing.py b/suncore/tariff/pricing.py new file mode 100644 index 0000000..d862189 --- /dev/null +++ b/suncore/tariff/pricing.py @@ -0,0 +1,153 @@ +# SPDX-License-Identifier: Apache-2.0 +"""From source prices to the planning prices: formula, export side, negative-price rule. + +Pure functions on :class:`~suncore.core.series.PriceSeries` and the contracts of +``core/tariff.py``; the service only feeds them. + +**Import.** A ``spot_only`` source goes through :meth:`PriceFormula.end_price` at the slot's +start instant, in the site's zone (``end_price`` is the 4-A ``apply``: the boundary test +reserves the call ``.apply(`` for the actuator write path). An ``all_in`` source is never +touched, even if a formula is configured (the API refuses that combination, this is the second +line of defence). + +**Export.** ``fixed``: the fixed price; ``tiered``: :func:`blended_export_price` with the +site's total kWp (the tiers must cover it, else :class:`ExportConfigError`); ``none``: 0. +A source that brings its own export prices (none of the known integrations does) wins over the +configuration. + +**Negative-price rule** (region template ``negative_price_rule``): + +* ``no_remuneration`` (``de``): in every slot whose *spot* price is negative, the export price + is 0 - the grid operator pays nothing then, so the planner must see that exporting earns + nothing and avoid it (curtail, store, consume). The spot price is the source price of a + ``spot_only`` source (before the formula). For an ``all_in`` source (Tibber) the spot price + is not known; the **import end price** is used as the proxy, which only marks slots where + the end price itself is negative, i.e. fewer slots than the true negative-spot slots + (UNVERIFIED approximation: the planner may see a remuneration in a slot with a slightly + negative spot price). A slot whose price is unknown gets an unknown export price. +* ``curtailment_required`` and ``none``: prices are not changed here (curtailment is a + planner/controller matter, not a price). +""" + +from __future__ import annotations + +from collections.abc import Sequence +from datetime import tzinfo +from typing import Final + +from suncore.core.config import ExportTariff +from suncore.core.series import ( + Grid, + PriceIncludes, + PriceSeries, + SeriesUnit, + TimeSeries, + resample_prices, +) +from suncore.core.tariff import PriceFormula, blended_export_price +from suncore.tariff.errors import ExportConfigError, ExportTiersError +from suncore.templates.models import NegativePriceRule + +NEGATIVE_EXPORT_PRICE: Final = 0.0 +"""Export price (currency/kWh) in a slot without remuneration.""" + + +def export_base_price(tariff: ExportTariff, total_kwp: float | None) -> float: + """The export price per kWh the configuration gives (``none`` -> 0). + + Raises :class:`ExportConfigError` for ``tiered`` without a known plant size or with tiers + that do not cover it (SunCore never guesses a rate). + """ + if tariff.kind == "none": + return 0.0 + if tariff.kind == "fixed": + assert tariff.fixed_price is not None + return tariff.fixed_price + if total_kwp is None: + raise ExportConfigError("tiered export needs `kwp` on every PV array") + try: + return blended_export_price(tariff.tiers, total_kwp) + except ValueError as exc: + raise ExportTiersError(str(exc), kwp=total_kwp) from exc + + +def apply_import_formula( + spot: TimeSeries, + includes: PriceIncludes, + formula: PriceFormula | None, + tz: tzinfo, +) -> tuple[TimeSeries, PriceIncludes]: + """End prices for a resampled source series, and the ``price_includes`` of the result. + + ``spot_only`` + formula -> ``all_in``; ``spot_only`` without formula stays ``spot_only`` + (the caller reports it); ``all_in`` is returned unchanged. + """ + if includes == "all_in" or formula is None: + return spot, includes + values = tuple( + None if v is None else formula.end_price(v, spot.slot_start(i), tz) + for i, v in enumerate(spot.values) + ) + return spot.model_copy(update={"values": values}), "all_in" + + +def planning_prices( + segments: Sequence[PriceSeries], + grid: Grid, + *, + formula: PriceFormula | None, + export_price: float, + rule: NegativePriceRule, + tz: tzinfo, + source_id: str | None = None, +) -> tuple[PriceSeries, int]: + """Import and export prices on ``grid`` and how many slots the negative-price rule zeroed. + + ``segments`` are one source's segments (any mix of 15/60 minutes). Slots no source value + covers are ``None`` in both series. + """ + if not segments: + empty = TimeSeries( + start=grid.start, + step=grid.step, + values=(None,) * grid.count, + unit=SeriesUnit.PRICE, + ) + return ( + PriceSeries( + source_id=source_id or "none", + price_includes="all_in", + import_price=empty, + export_price=empty, + ), + 0, + ) + resampled = resample_prices(list(segments), grid) + spot = resampled.import_price + end, includes = apply_import_formula(spot, resampled.price_includes, formula, tz) + zeroed = 0 + export_values: list[float | None] = [] + for i, end_price in enumerate(end.values): + if resampled.export_price is not None: + export_values.append(resampled.export_price.values[i]) + continue + reference = spot.values[i] if resampled.price_includes == "spot_only" else end_price + if end_price is None or reference is None: + export_values.append(None) + elif rule is NegativePriceRule.NO_REMUNERATION and reference < 0: + export_values.append(NEGATIVE_EXPORT_PRICE) + zeroed += 1 + else: + export_values.append(export_price) + export = TimeSeries( + start=end.start, step=end.step, values=tuple(export_values), unit=SeriesUnit.PRICE + ) + return ( + PriceSeries( + source_id=source_id or resampled.source_id, + price_includes=includes, + import_price=end, + export_price=export, + ), + zeroed, + ) diff --git a/suncore/tariff/report.py b/suncore/tariff/report.py new file mode 100644 index 0000000..e5fbd48 --- /dev/null +++ b/suncore/tariff/report.py @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: Apache-2.0 +"""What ``GET /api/v1/prices`` returns: the planning prices with source and freshness. + +Pydantic models are the schema (OpenAPI is generated from them). Error ``key`` values are +catalogue keys (``tariff.error.*``); ``args`` are their ICU arguments. +""" + +from __future__ import annotations + +from typing import Annotated, Literal + +from pydantic import AwareDatetime, BaseModel, ConfigDict, Field + +from suncore.core.series import PriceIncludes + +SourceKindOut = Literal["dynamic", "fixed", "tou"] +FreshnessStatus = Literal["fresh", "stale", "missing", "static"] +ExportKind = Literal["fixed", "tiered", "none"] +ErrorArg = str | float | int | list[str] + + +class _Out(BaseModel): + model_config = ConfigDict(frozen=True, extra="forbid") + + +class PriceSlot(_Out): + """One 15-minute interval; a price is ``null`` where no source value covers it.""" + + start: AwareDatetime + import_price: float | None + """End price of imported energy, currency/kWh (may be negative).""" + export_price: float | None + """Remuneration of exported energy, currency/kWh (0 when the negative-price rule applies).""" + + +class PriceErrorOut(_Out): + """Why the last refresh failed, as a catalogue key.""" + + key: str + args: dict[str, ErrorArg] = Field(default_factory=dict) + + +class PriceSourceInfo(_Out): + import_source_id: str + """Template id (``tibber.price``), ``fixed`` or ``tou``.""" + import_kind: SourceKindOut + source_price_includes: PriceIncludes + """What the source delivers: the bare spot price or the all-in end price.""" + price_includes: PriceIncludes + """What ``import_price`` is: ``all_in`` once the formula was applied.""" + formula_applied: bool + export_kind: ExportKind + negative_price_rule: str + """Region template value: ``none``, ``no_remuneration`` or ``curtailment_required``.""" + export_zeroed_slots: Annotated[int, Field(ge=0)] + """Slots whose export price was set to 0 by the negative-price rule.""" + native_step_min: int | None + """Finest native resolution of the source (15 or 60), ``null`` for fixed prices.""" + currency: str + + +class PriceFreshness(_Out): + status: FreshnessStatus + fetched_at: AwareDatetime | None + age_s: float | None + known_until: AwareDatetime | None + """End of the last interval the source has a price for.""" + next_refresh_at: AwareDatetime | None + last_error: PriceErrorOut | None + + +class PriceQuality(_Out): + slots: Annotated[int, Field(ge=0)] + known_slots: Annotated[int, Field(ge=0)] + has_tomorrow: bool + """Prices cover the whole next local day.""" + dropped_points: Annotated[int, Field(ge=0)] + """Points of the last fetch that were unreadable, duplicated or overlapping.""" + carried_slots: Annotated[int, Field(ge=0)] = 0 + """Slots the latest fetch left unknown and an earlier fetch supplied (degraded data).""" + + +class PriceReport(_Out): + unit: Literal["currency/kWh"] = "currency/kWh" + step_min: Literal[15] = 15 + price_includes: PriceIncludes + """What ``import_price`` is: ``all_in`` (end price) or ``spot_only`` (bare market price).""" + formula_missing: bool + """The import price is a bare spot price and no price formula turns it into the end price: + do not plan with it.""" + start: AwareDatetime + slots: list[PriceSlot] + source: PriceSourceInfo + freshness: PriceFreshness + quality: PriceQuality diff --git a/suncore/tariff/service.py b/suncore/tariff/service.py new file mode 100644 index 0000000..eb65610 --- /dev/null +++ b/suncore/tariff/service.py @@ -0,0 +1,610 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The tariff service: keeps import and export prices fresh and serves them on the 15-minute grid. + +One service per configured tariff. It owns a :class:`~suncore.tariff.sources.SegmentSource` +(template adapter, fixed or HT/NT), the price formula, the export side and the region's +negative-price rule. Time is injected (``clock``); nothing here sleeps except :meth:`run`, +whose ``sleep`` is injected too. + +**When it refreshes** (:meth:`due`, the one decision function; :meth:`next_refresh` mirrors it): + +* ``initial``: never fetched; +* ``changed``: the price entity changed (:meth:`notify_changed`) - at once for attribute + sources (cheap: reads the entity cache), for action sources only when the current slot has no + price (an action call costs a request to the cloud service; the sensor changes every slot); +* ``interval``: the last fetch is ``refresh_interval_s`` old (default one hour); +* ``tomorrow``: a dynamic source does not cover the whole next local day yet and the local + publication time (``tomorrow_after``, default 13:00, ``UNVERIFIED`` for Tibber and Nord + Pool) has passed: ask again every ``tomorrow_poll_s`` until it does; +* ``retry``: after a failure, with a doubling back-off (``retry_interval_s`` ... one hour). + +Action calls are additionally limited by the connection's per-action rate limiter (at least 30 s +apart); a throttled call is not a failure, the last data stays and the service asks again when +the limiter would admit it. A failed or empty fetch never replaces good data; the data of an +earlier fetch beyond the end of the new data is kept (a source that briefly forgets tomorrow's +prices does not blank them). +""" + +from __future__ import annotations + +import asyncio +from collections.abc import Awaitable, Callable, Iterable, Sequence +from dataclasses import dataclass, field +from datetime import date, datetime, time, timedelta, tzinfo +from typing import Final, Literal, Protocol + +import structlog + +from suncore.core.config import ExportTariff +from suncore.core.series import ( + PLANNING_STEP, + Grid, + PriceSeries, + TimeRange, + floor_to_step, +) +from suncore.core.tariff import PriceFormula +from suncore.tariff.errors import ( + SourceThrottledError, + SourceUnavailableError, + TariffError, +) +from suncore.tariff.parse import ParseReport, clip_series +from suncore.tariff.pricing import export_base_price, planning_prices +from suncore.tariff.report import ( + PriceErrorOut, + PriceFreshness, + PriceQuality, + PriceReport, + PriceSlot, + PriceSourceInfo, +) +from suncore.tariff.sources import SegmentSource, SourceData +from suncore.templates.models import NegativePriceRule + +log = structlog.get_logger(__name__) + +RefreshReason = Literal["initial", "changed", "interval", "tomorrow", "retry", "forced"] + +MIN_HORIZON: Final = timedelta(hours=24) +"""The series is at least this long when a window of it is requested (``None`` beyond the data).""" +FETCH_HORIZON: Final = timedelta(hours=72) +MIN_REFRESH_INTERVAL_S: Final = 60.0 +"""Below the connection's 30 s action floor with margin; a smaller setting is raised.""" +POLL_S: Final = 30.0 + + +class PriceStore(Protocol): + """``TimeseriesStore.store_prices``; ``None`` = do not persist.""" + + async def store_prices(self, prices: PriceSeries) -> int: ... + + +@dataclass(frozen=True, slots=True) +class ServiceSettings: + """Timing of the refresh logic (all configurable, defaults per the Phase 4 plan).""" + + refresh_interval_s: float = 3600.0 + """Tibber and Nord Pool: once per hour.""" + retry_interval_s: float = 300.0 + """First retry after a failure; doubles up to one hour.""" + tomorrow_after: time = time(13, 0) + """Local time from which tomorrow's day-ahead prices are expected (``UNVERIFIED``).""" + tomorrow_poll_s: float = 900.0 + """Spacing of the asks between the publication time and the arrival of tomorrow's prices.""" + + def __post_init__(self) -> None: + if self.refresh_interval_s < MIN_REFRESH_INTERVAL_S: + object.__setattr__(self, "refresh_interval_s", MIN_REFRESH_INTERVAL_S) + if self.retry_interval_s < MIN_REFRESH_INTERVAL_S: + object.__setattr__(self, "retry_interval_s", MIN_REFRESH_INTERVAL_S) + if self.tomorrow_poll_s < MIN_REFRESH_INTERVAL_S: + object.__setattr__(self, "tomorrow_poll_s", MIN_REFRESH_INTERVAL_S) + + +@dataclass(frozen=True, slots=True) +class TariffPlan: + """The configured tariff, resolved: what the service needs to turn source data into prices.""" + + source: SegmentSource + export_tariff: ExportTariff + negative_rule: NegativePriceRule + tz: tzinfo + currency: str + formula: PriceFormula | None = None + total_kwp: float | None = None + + +@dataclass(frozen=True, slots=True) +class RefreshResult: + """Outcome of one :meth:`TariffService.refresh`.""" + + reason: RefreshReason + ok: bool + throttled: bool = False + error: TariffError | None = None + known_until: datetime | None = None + + +@dataclass(slots=True) +class _State: + segments: tuple[PriceSeries, ...] = () + fetched_at: datetime | None = None + report: ParseReport = field(default_factory=ParseReport) + error: TariffError | None = None + failures: int = 0 + retry_at: datetime | None = None + dirty: bool = False + last_attempt: datetime | None = None + """Start of the latest fetch, successful or not.""" + carried: int = 0 + """Slots of the current data that an earlier fetch supplied because the latest had none.""" + + @property + def known_end(self) -> datetime | None: + return max((s.import_price.end for s in self.segments), default=None) + + +def _midnight(day: date, tz: tzinfo) -> datetime: + return datetime.combine(day, time.min, tzinfo=tz) + + +def _value_at(segments: Sequence[PriceSeries], at: datetime) -> float | None: + for series in segments: + ts = series.import_price + if ts.start <= at < ts.end: + return ts.values[int((at - ts.start) // ts.step)] + return None + + +def _fill_gaps( + new: Sequence[PriceSeries], old: Sequence[PriceSeries] +) -> tuple[tuple[PriceSeries, ...], int]: + """``new`` with every unknown slot replaced by the earlier fetch's value (if it had one). + + Returns the segments and how many slots were carried over; a source that suddenly reports + ``None`` for a price it knew an hour ago does not blank it. + """ + carried = 0 + out: list[PriceSeries] = [] + for series in new: + ts = series.import_price + values = list(ts.values) + for i, value in enumerate(values): + if value is None and (kept := _value_at(old, ts.slot_start(i))) is not None: + values[i] = kept + carried += 1 + out.append( + series.model_copy( + update={"import_price": ts.model_copy(update={"values": tuple(values)})} + ) + ) + return tuple(out), carried + + +def _old_tail( + new: Sequence[PriceSeries], old: Sequence[PriceSeries], floor: datetime +) -> list[PriceSeries]: + """The old slots that begin at or after the new data's end (and are not past). + + Each old segment is cut at its own slot boundary (rounded up), so the tail never overlaps + the new data even if the old slots were hourly and the new data ends inside an hour. + """ + new_end = max(s.import_price.end for s in new) + limit = max(new_end, floor) + tail: list[PriceSeries] = [] + for previous in old: + ts = previous.import_price + if previous.price_includes != new[0].price_includes or ts.end <= limit: + continue + first = max(0, -(-(limit - ts.start) // ts.step)) + piece = clip_series(ts, ts.slot_start(first), ts.end) + if piece is not None: + tail.append( + PriceSeries( + source_id=previous.source_id, + price_includes=previous.price_includes, + import_price=piece, + ) + ) + return tail + + +class TariffService: + """Keeps the prices fresh and answers :meth:`prices` / :meth:`report` from the cache.""" + + def __init__( + self, + plan: TariffPlan, + *, + clock: Callable[[], datetime], + store: PriceStore | None = None, + settings: ServiceSettings | None = None, + ) -> None: + self._plan = plan + self._clock = clock + self._store = store + self._settings = settings or ServiceSettings() + self._state = _State() + self._lock = asyncio.Lock() + self._listeners: list[Callable[[], None]] = [] + self._export_base = export_base_price(plan.export_tariff, plan.total_kwp) + self._last_written: tuple[object, ...] | None = None + + # --- identity ---------------------------------------------------------------------- + + @property + def plan(self) -> TariffPlan: + return self._plan + + @property + def watched_entities(self) -> tuple[str, ...]: + return self._plan.source.watched_entities + + def add_listener(self, listener: Callable[[], None]) -> Callable[[], None]: + """Call ``listener`` after every successful refresh (new prices); returns the remover.""" + self._listeners.append(listener) + + def remove() -> None: + if listener in self._listeners: + self._listeners.remove(listener) + + return remove + + # --- when to refresh --------------------------------------------------------------- + + def watched_entities_isdisjoint(self, entity_ids: Iterable[str]) -> bool: + """Whether none of ``entity_ids`` is an entity this service watches.""" + return set(self._plan.source.watched_entities).isdisjoint(entity_ids) + + def reset_backoff(self) -> None: + """Forget the failure back-off (Home Assistant is connected again).""" + self._state.failures = 0 + self._state.retry_at = None + self._state.error = None if self._state.fetched_at is not None else self._state.error + + def notify_changed(self) -> None: + """A watched entity changed state; see ``changed`` in the module docstring.""" + self._state.dirty = True + + def _current_slot_known(self, now: datetime) -> bool: + step = floor_to_step(now) + for series in self._state.segments: + ts = series.import_price + if ts.start <= step < ts.end: + index = int((step - ts.start) // ts.step) + return ts.values[index] is not None + return False + + def _tomorrow_covered(self, now: datetime) -> bool: + end = self._state.known_end + if end is None: + return False + zones = [self._plan.tz] + market = self._plan.source.delivery_tz + if market is not None: + zones.append(market) + # the day-ahead prices stop at the end of tomorrow in the market's zone, which lies + # before the site's midnight west of it (never "covered" otherwise): the earlier counts + deadline = min(_midnight(now.astimezone(z).date() + timedelta(days=2), z) for z in zones) + return end >= deadline + + def _schedule(self, now: datetime) -> tuple[datetime, RefreshReason] | None: + """The earliest time-based refresh (``None`` = nothing scheduled).""" + state = self._state + if state.fetched_at is None: + return (state.retry_at or now, "initial") + candidates: list[tuple[datetime, RefreshReason]] = [ + (state.fetched_at + timedelta(seconds=self._settings.refresh_interval_s), "interval") + ] + if state.retry_at is not None: + candidates.append((state.retry_at, "retry")) + if self._plan.source.kind == "dynamic" and not self._tomorrow_covered(now): + tz = self._plan.tz + published = datetime.combine( + now.astimezone(tz).date(), self._settings.tomorrow_after, tzinfo=tz + ) + earliest = state.fetched_at + timedelta(seconds=self._settings.tomorrow_poll_s) + candidates.append((max(published, earliest), "tomorrow")) + if state.retry_at is not None: + # after a failure or a throttled call only the retry time counts, not the regular + # schedule (which may be overdue because the fetch did not work) + return (state.retry_at, "retry") + return min(candidates, key=lambda c: c[0]) + + def due(self, now: datetime | None = None) -> RefreshReason | None: + """Why a refresh is due now, else ``None``.""" + now = now or self._clock() + state = self._state + in_backoff = state.retry_at is not None and now < state.retry_at + if state.dirty: + source = self._plan.source + recent = state.last_attempt is not None and ( + now - state.last_attempt < timedelta(seconds=POLL_S) + ) + if not source.uses_action and not recent: + return "changed" # reads the entity cache: free (but not in a tight loop) + if ( + state.fetched_at is not None + and not in_backoff + and not self._current_slot_known(now) + ): + return "changed" + scheduled = self._schedule(now) + if scheduled is not None and scheduled[0] <= now: + return scheduled[1] + return None + + def next_refresh(self, now: datetime | None = None) -> datetime | None: + """When the next time-based refresh is due (a state change can only make it earlier).""" + now = now or self._clock() + scheduled = self._schedule(now) + return None if scheduled is None else max(scheduled[0], now) + + # --- refreshing -------------------------------------------------------------------- + + async def tick(self) -> RefreshResult | None: + """One scheduler step: refresh if :meth:`due`.""" + reason = self.due() + return None if reason is None else await self.refresh(reason) + + async def run( + self, + sleep: Callable[[float], Awaitable[None]] = asyncio.sleep, + poll_s: float = POLL_S, + ) -> None: + """Poll :meth:`tick` every ``poll_s`` until cancelled; never raises (errors are state).""" + while True: + try: + await self.tick() + except asyncio.CancelledError: + raise + except Exception: + log.exception("tariff.tick_crashed") + await sleep(poll_s) + + async def refresh(self, reason: RefreshReason = "forced") -> RefreshResult | None: + """Fetch now. ``None`` when another refresh is already running.""" + if self._lock.locked(): + return None + async with self._lock: + now = self._clock() + self._state.last_attempt = now + window = TimeRange(start=floor_to_step(now), end=floor_to_step(now) + FETCH_HORIZON) + try: + data = await self._plan.source.fetch_segments(window, now) + if not any(v is not None for s in data.segments for v in s.import_price.values): + raise SourceUnavailableError("the source returned no price") + self._accept(data, now) + except SourceThrottledError as exc: + self._state.retry_at = now + timedelta(seconds=max(exc.retry_after_s, 1.0)) + return RefreshResult(reason, ok=False, throttled=True, error=exc) + except TariffError as exc: + return self._failed(reason, now, exc) + except Exception as exc: + log.exception("tariff.fetch_crashed", source=self._plan.source.source_id) + return self._failed(reason, now, TariffError(f"{type(exc).__name__}: {exc}")) + await self._persist(now) + for listener in list(self._listeners): + try: + listener() + except Exception: + log.exception("tariff.listener_failed") + return RefreshResult(reason, ok=True, known_until=self._state.known_end) + + def _failed(self, reason: RefreshReason, now: datetime, error: TariffError) -> RefreshResult: + state = self._state + state.failures += 1 + state.error = error + state.dirty = False # this fetch has seen the change; only a newer one counts + backoff = min(3600.0, self._settings.retry_interval_s * 2 ** (state.failures - 1)) + state.retry_at = now + timedelta(seconds=backoff) + log.warning( + "tariff.refresh_failed", + source=self._plan.source.source_id, + reason=reason, + error=error.key, + failures=state.failures, + retry_in_s=backoff, + ) + return RefreshResult(reason, ok=False, error=error) + + def _accept(self, data: SourceData, now: datetime) -> None: + """Take over a fetch: fill its holes from the earlier data, keep the earlier tail. + + Everything is computed before the state is touched, so an error leaves the earlier + data as it was. + """ + old = self._state.segments + filled, carried = _fill_gaps(data.segments, old) + merged = (*filled, *_old_tail(filled, old, floor_to_step(now))) + state = self._state + state.segments = merged + state.fetched_at = now + state.report = data.report + state.carried = carried + state.error = None + state.failures = 0 + state.retry_at = None + state.dirty = False + + async def _persist(self, now: datetime) -> None: + if self._store is None: + return + try: + series = self._trimmed(now) + if series is None: + return + key = ( + series.start, + series.import_price.values, + series.export_price.values if series.export_price else None, + ) + if key == self._last_written: + return + await self._store.store_prices(series) + except Exception: + log.exception("tariff.store_failed", source=self._plan.source.source_id) + return + self._last_written = key + + def _trimmed(self, now: datetime) -> PriceSeries | None: + """The planning prices from now to the end of the known prices without ``None`` edges.""" + grid = self._grid(now, FETCH_HORIZON) + prices, _ = self._planning(grid) + values = prices.import_price.values + known = [i for i, v in enumerate(values) if v is not None] + if not known: + return None + lo, hi = known[0], known[-1] + 1 + export = prices.export_price + return PriceSeries( + source_id=prices.source_id, + price_includes=prices.price_includes, + import_price=prices.import_price.model_copy( + update={"start": prices.import_price.slot_start(lo), "values": values[lo:hi]} + ), + export_price=None + if export is None + else export.model_copy( + update={"start": export.slot_start(lo), "values": export.values[lo:hi]} + ), + ) + + # --- serving ----------------------------------------------------------------------- + + def _grid(self, now: datetime, horizon: timedelta) -> Grid: + """From the interval containing ``now`` to the end of the known prices. + + At least 24 h (``None`` beyond the data) and at most ``horizon``. + """ + end = self._state.known_end + floor = floor_to_step(now) + lower = now + MIN_HORIZON + upper = now + horizon + target = min(lower if end is None else max(end, lower), upper) + count = max(1, -(-(target - floor) // PLANNING_STEP)) + return Grid(start=floor, step=PLANNING_STEP, count=count) + + def _planning(self, grid: Grid) -> tuple[PriceSeries, int]: + plan = self._plan + return planning_prices( + self._state.segments, + grid, + formula=plan.formula, + export_price=self._export_base, + rule=plan.negative_rule, + tz=plan.tz, + source_id=plan.source.source_id, + ) + + def prices(self, hours: float = 48, now: datetime | None = None) -> PriceSeries: + """Import and export prices on the 15-minute grid from now (see :meth:`_grid`).""" + now = now or self._clock() + prices, _ = self._planning(self._grid(now, timedelta(hours=hours))) + return prices + + def report(self, hours: float = 48, now: datetime | None = None) -> PriceReport: + """The API view: prices, source, freshness and quality.""" + now = now or self._clock() + plan, state = self._plan, self._state + grid = self._grid(now, timedelta(hours=hours)) + prices, zeroed = self._planning(grid) + export = prices.export_price + slots = [ + PriceSlot( + start=prices.import_price.slot_start(i), + import_price=v, + export_price=None if export is None else export.values[i], + ) + for i, v in enumerate(prices.import_price.values) + ] + known = sum(s.import_price is not None for s in slots) + native = [s.step for s in state.segments] + has_formula = plan.formula is not None and plan.source.price_includes == "spot_only" + steps = ( + min(native) // timedelta(minutes=1) + if native and plan.source.kind == "dynamic" + else None + ) + return PriceReport( + price_includes=prices.price_includes, + formula_missing=prices.price_includes == "spot_only", + start=grid.start, + slots=slots, + source=PriceSourceInfo( + import_source_id=plan.source.source_id, + import_kind=plan.source.kind, + source_price_includes=plan.source.price_includes, + price_includes=prices.price_includes, + formula_applied=has_formula, + export_kind=plan.export_tariff.kind, + negative_price_rule=plan.negative_rule.value, + export_zeroed_slots=zeroed, + native_step_min=int(steps) if steps is not None else None, + currency=plan.currency, + ), + freshness=self._freshness(now), + quality=PriceQuality( + slots=len(slots), + known_slots=known, + has_tomorrow=self._tomorrow_covered(now), + dropped_points=state.report.unreadable_values + + state.report.duplicates + + state.report.overlaps, + carried_slots=state.carried, + ), + ) + + def _freshness(self, now: datetime) -> PriceFreshness: + state = self._state + error = ( + None + if state.error is None + else PriceErrorOut(key=state.error.key, args=_json_args(state.error)) + ) + age = None if state.fetched_at is None else (now - state.fetched_at).total_seconds() + status: Literal["fresh", "stale", "missing", "static"] + if state.fetched_at is None or not state.segments: + status = "missing" + elif self._plan.source.kind != "dynamic": + status = "static" + else: + limit = 2 * self._settings.refresh_interval_s + status = ( + "fresh" + if (age or 0.0) <= limit and self._current_slot_known(now) and state.error is None + else "stale" + ) + return PriceFreshness( + status=status, + fetched_at=state.fetched_at, + age_s=age, + known_until=state.known_end, + next_refresh_at=self.next_refresh(now), + last_error=error, + ) + + +def _json_args(error: TariffError) -> dict[str, str | float | int | list[str]]: + out: dict[str, str | float | int | list[str]] = {} + for key, value in error.message_args.items(): + if isinstance(value, str | int | float) and not isinstance(value, bool): + out[key] = value + elif isinstance(value, list): + out[key] = [str(v) for v in value] + else: + out[key] = str(value) + return out + + +__all__ = [ + "FETCH_HORIZON", + "MIN_HORIZON", + "PriceStore", + "RefreshReason", + "RefreshResult", + "ServiceSettings", + "TariffPlan", + "TariffService", +] diff --git a/suncore/tariff/sources.py b/suncore/tariff/sources.py new file mode 100644 index 0000000..605cf9d --- /dev/null +++ b/suncore/tariff/sources.py @@ -0,0 +1,162 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Price sources behind one small protocol: fixed, HT/NT and the template-driven adapters. + +A :class:`SegmentSource` returns what it knows for a window as regular segments (a source may +mix 15- and 60-minute slots); :func:`finest_series` turns them into the single +:class:`~suncore.core.series.PriceSeries` that the ``PriceSource`` protocol of +``core/forecast.py`` promises. The :class:`~suncore.tariff.service.TariffService` works with +the segments directly and resamples once onto the planning grid. +""" + +from __future__ import annotations + +from collections.abc import Sequence +from dataclasses import dataclass, field +from datetime import datetime, tzinfo +from typing import Literal, Protocol + +from suncore.core.series import ( + PLANNING_STEP, + Grid, + PriceIncludes, + PriceSeries, + SeriesUnit, + TimeRange, + TimeSeries, + floor_to_step, + resample_prices, +) +from suncore.core.tariff import TouTariff +from suncore.tariff.parse import ParseReport + +SourceKind = Literal["dynamic", "fixed", "tou"] + + +@dataclass(frozen=True, slots=True) +class SourceData: + """What one fetch returned: segments (one source, one ``price_includes``) and the parse + report (what was dropped).""" + + segments: tuple[PriceSeries, ...] + report: ParseReport = field(default_factory=ParseReport) + + @property + def known_end(self) -> datetime | None: + """End of the last segment, ``None`` when nothing was returned.""" + return max((s.import_price.end for s in self.segments), default=None) + + +class SegmentSource(Protocol): + """What the :class:`TariffService` needs from an import price source.""" + + @property + def source_id(self) -> str: ... + + @property + def kind(self) -> SourceKind: ... + + @property + def price_includes(self) -> PriceIncludes: ... + + @property + def uses_action(self) -> bool: + """Whether a fetch calls a Home Assistant action (rate limited) rather than reading + entity attributes.""" + ... + + @property + def watched_entities(self) -> tuple[str, ...]: + """Entities whose state change may mean new prices.""" + ... + + @property + def delivery_tz(self) -> tzinfo | None: + """Time zone of the market's delivery day when it is not the site's (Nord Pool: CET), + else ``None``. The day-ahead prices end at the end of that zone's next day.""" + ... + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: ... + + +def finest_series( + source_id: str, + price_includes: PriceIncludes, + segments: Sequence[PriceSeries], + window: TimeRange, +) -> PriceSeries: + """One series on the finest native step of ``segments`` (step-hold for coarser ones). + + Without segments: an empty 15-minute series at ``window.start`` (nothing is invented). + """ + if not segments: + empty = TimeSeries(start=window.start, step=PLANNING_STEP, values=(), unit=SeriesUnit.PRICE) + return PriceSeries(source_id=source_id, price_includes=price_includes, import_price=empty) + step = min(s.step for s in segments) + start = floor_to_step(min(s.start for s in segments), step) + end = max(s.import_price.end for s in segments) + count = max(1, -(-(end - start) // step)) + return resample_prices(list(segments), Grid(start=start, step=step, count=count)) + + +def _slots(window: TimeRange) -> tuple[datetime, int]: + start = floor_to_step(window.start) + return start, max(1, -(-(window.end - start) // PLANNING_STEP)) + + +def _static_series( + source_id: str, values: Sequence[float], start: datetime, price_includes: PriceIncludes +) -> SourceData: + series = TimeSeries( + start=start, step=PLANNING_STEP, values=tuple(values), unit=SeriesUnit.PRICE + ) + price = PriceSeries(source_id=source_id, price_includes=price_includes, import_price=series) + return SourceData(segments=(price,), report=ParseReport(points=len(values))) + + +@dataclass(frozen=True, slots=True) +class FixedPriceSource: + """One all-in price per kWh at all times (``tariff.import.kind = fixed``).""" + + price: float + source_id: str = "fixed" + kind: SourceKind = "fixed" + price_includes: PriceIncludes = "all_in" + uses_action: bool = False + watched_entities: tuple[str, ...] = () + delivery_tz: tzinfo | None = None + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: # noqa: ARG002 + start, count = _slots(window) + return _static_series(self.source_id, [self.price] * count, start, self.price_includes) + + async def fetch(self, window: TimeRange) -> PriceSeries: + data = await self.fetch_segments(window, window.start) + return data.segments[0] + + +@dataclass(frozen=True, slots=True) +class TouPriceSource: + """HT/NT prices from local weekly windows (``tariff.import.kind = tou``). + + A slot is priced at its **start** instant, judged in the site's local time (DST safe: the + slots are absolute 15-minute intervals). A window boundary that is not on a quarter hour + therefore takes effect at the next slot start. + """ + + tou: TouTariff + tz: tzinfo + source_id: str = "tou" + kind: SourceKind = "tou" + price_includes: PriceIncludes = "all_in" + uses_action: bool = False + watched_entities: tuple[str, ...] = () + delivery_tz: tzinfo | None = None + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: # noqa: ARG002 + start, count = _slots(window) + values = [self.tou.price_at(start + PLANNING_STEP * i, self.tz) for i in range(count)] + return _static_series(self.source_id, values, start, self.price_includes) + + async def fetch(self, window: TimeRange) -> PriceSeries: + data = await self.fetch_segments(window, window.start) + return data.segments[0] diff --git a/suncore/tariff/units.py b/suncore/tariff/units.py new file mode 100644 index 0000000..6483267 --- /dev/null +++ b/suncore/tariff/units.py @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Price units of integrations -> SunCore's ``currency/kWh``. + +Documented additive alias (Phase 4 WP4): EPEX Spot labels its sensors with the *symbol* of the +currency (``"€/kWh"``, ``"£/kWh"``; ``custom_components/epex_spot/const.py:57``, tag ``4.1.0``) +while the template schema's price unit is ``/kWh|MWh``. The template keeps +``{currency}/kWh`` as the unit of the *values* and lists the literal symbols in its matcher +(``units``); :func:`normalise_price_unit` maps the symbol to the ISO code wherever an entity's +unit is compared with a template's (conformance test, wizard). +""" + +from __future__ import annotations + +from typing import Final + +from suncore.templates.models import price_unit_factor + +CURRENCY_SYMBOLS: Final[dict[str, str]] = {"€": "EUR", "£": "GBP"} +"""Currency symbols that integrations put in front of ``/kWh`` (EPEX Spot: EUR and GBP).""" + + +def normalise_price_unit(unit: str) -> str: + """``"€/kWh"`` -> ``"EUR/kWh"``; any other unit is returned unchanged.""" + symbol, sep, rest = unit.strip().partition("/") + return f"{CURRENCY_SYMBOLS[symbol]}{sep}{rest}" if symbol in CURRENCY_SYMBOLS else unit.strip() + + +def resolve_value_unit(unit: str, currency: str) -> str: + """The template's ``{currency}`` placeholder replaced by the region's ISO code.""" + return unit.replace("{currency}", currency) + + +def divisor_to_kwh(unit: str) -> float: + """What to divide a price in ``unit`` by to get currency/kWh (``EUR/MWh`` -> 1000). + + Division (not multiplication by 0.001) keeps ``45.5 / 1000`` the exact nearest double. + Raises ``ValueError`` for a unit that is not ``/kWh|MWh``. + """ + return float(round(1 / price_unit_factor(unit))) + + +def energy_scale(unit: str) -> str | None: + """``"kWh"`` or ``"MWh"`` of a ``/`` unit, else ``None``.""" + _, _, scale = unit.partition("/") + return scale if scale in ("kWh", "MWh") else None + + +def currency_of(unit: str) -> str | None: + """ISO code of a ``/`` unit (a symbol is mapped), else ``None``.""" + code, sep, _ = normalise_price_unit(unit).partition("/") + return code if sep and len(code) == 3 and code.isalpha() and code.isupper() else None diff --git a/suncore/templates/__init__.py b/suncore/templates/__init__.py index 49cae6a..9e06130 100644 --- a/suncore/templates/__init__.py +++ b/suncore/templates/__init__.py @@ -20,6 +20,7 @@ ) from suncore.templates.models import ( TEMPLATE_ADAPTER, + ActionParam, ActionSeries, AttributeSeries, BatteryTemplate, @@ -35,6 +36,7 @@ __all__ = [ "TEMPLATE_ADAPTER", + "ActionParam", "ActionSeries", "AttributeSeries", "BatteryTemplate", diff --git a/suncore/templates/models.py b/suncore/templates/models.py index 63c92c6..5372b64 100644 --- a/suncore/templates/models.py +++ b/suncore/templates/models.py @@ -18,6 +18,7 @@ from enum import StrEnum, unique from functools import lru_cache from typing import Annotated, Final, Literal, Self +from zoneinfo import ZoneInfo, ZoneInfoNotFoundError from pydantic import ( BaseModel, @@ -227,6 +228,10 @@ class SeriesFields(_Frozen): value_field: Text | None = None p10_field: Text | None = None p90_field: Text | None = None + end_field: Text | None = None + """Phase 4 WP4 (price lists): field with the slot *end*; the slot length is ``end - start`` + per point (Nord Pool, EPEX Spot, Octopus). Absent = derive the length from the spacing of + the timestamps or from the template's ``resolution_min``.""" value_unit: Text def require_point_fields(self, where: str) -> None: @@ -267,13 +272,28 @@ def _unique(self) -> Self: if self.shape == "list": f.require_point_fields("series.fields") elif any( - x is not None for x in (f.timestamp_field, f.value_field, f.p10_field, f.p90_field) + x is not None + for x in (f.timestamp_field, f.value_field, f.p10_field, f.p90_field, f.end_field) ): msg = "series.fields: shape `mapping` takes only `value_unit` (keys are the timestamps)" raise ValueError(msg) return self +class ActionParam(_Frozen): + """A field of the action's request that the user's tariff configuration supplies. + + The value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the + Nord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value. + """ + + name: Text + """The action's field name.""" + required: bool = True + description: MessageKey + """i18n key explaining the field to the user.""" + + class ActionSeries(_Frozen): """Series returned by a read-only action (``return_response`` is implied).""" @@ -282,8 +302,20 @@ class ActionSeries(_Frozen): service: Slug start_field: Text | None = None end_field: Text | None = None + date_field: Text | None = None + """Phase 4 WP4: the action takes one delivery *date* (``YYYY-MM-DD``, local date of the + site) per call (Nord Pool ``date``); the adapter calls once for every date of the window. + Excludes ``start_field``/``end_field``.""" + date_tz: ( + Annotated[str, StringConstraints(pattern=r"^[A-Za-z_]+(/[A-Za-z_+\-0-9]+){1,2}$")] | None + ) = None + """IANA zone in which ``date_field`` names the delivery day (the market's, e.g. Nord Pool's + CET day: ``Europe/Berlin``); ``None`` = the site's zone.""" + params: Annotated[tuple[ActionParam, ...], Field(max_length=8)] = () + """Request fields the user supplies (see :class:`ActionParam`).""" response_path: Annotated[ - str, StringConstraints(pattern=r"^[A-Za-z0-9_]+(\.([A-Za-z0-9_]+|\*))*$", max_length=200) + str, + StringConstraints(pattern=r"^(\*|[A-Za-z0-9_]+)(\.([A-Za-z0-9_]+|\*))*$", max_length=200), ] """Dotted path into the response; a ``*`` segment means every value of that mapping.""" fields: SeriesFields @@ -292,6 +324,28 @@ class ActionSeries(_Frozen): @model_validator(mode="after") def _allowed(self) -> Self: self.fields.require_point_fields("series.fields") + if self.date_field is not None and ( + self.start_field is not None or self.end_field is not None + ): + msg = "series: `date_field` excludes `start_field` and `end_field`" + raise ValueError(msg) + if self.date_tz is not None: + if self.date_field is None: + msg = "series: `date_tz` needs `date_field`" + raise ValueError(msg) + try: + ZoneInfo(self.date_tz) + except (ZoneInfoNotFoundError, ValueError, OSError) as exc: + msg = f"series.date_tz: unknown time zone `{self.date_tz}`" + raise ValueError(msg) from exc + names = [p.name for p in self.params] + if len(set(names)) != len(names): + msg = "series.params: names must be unique" + raise ValueError(msg) + reserved = {self.date_field, self.start_field, self.end_field} - {None} + if reserved & set(names): + msg = "series.params: a parameter cannot reuse a date, start or end field" + raise ValueError(msg) if not is_read_only_action(self.domain, self.service): msg = ( f"{ERR_ACTION_NOT_ALLOWED}: `{self.domain}.{self.service}` is not on the " @@ -494,7 +548,12 @@ def _tariff(self) -> Self: return self def message_keys(self) -> list[str]: - return [self.name, *(r.description for r in self.roles.values())] + params = ( + [p.description for p in self.price_series.params] + if isinstance(self.price_series, ActionSeries) + else [] + ) + return [self.name, *(r.description for r in self.roles.values()), *params] # --- forecast ---------------------------------------------------------------- diff --git a/templates/README.md b/templates/README.md index b1cfc4a..e7dda19 100644 --- a/templates/README.md +++ b/templates/README.md @@ -26,6 +26,11 @@ drift). | device | `generic.water_heater_steps` | water heater with power levels through one select entity, optional tank probe | generic, simulator only (`UNVERIFIED`: no hardware) | | device | `generic.water_heater_relays` | water heater with 1-3 heating elements switched by relays | generic, simulator only (`UNVERIFIED`: no hardware) | | tariff | `tibber.price` | Tibber dynamic price, curve from `tibber.get_prices` | from integration source | +| tariff | `nordpool.price` | Nord Pool day-ahead prices per area, one `nordpool.get_prices_for_date` call per date, per MWh, excl. VAT and fees | from integration source, `config_entry` entered by the user | +| tariff | `entsoe.price`, `entsoe.price_mwh` | ENTSO-E (HACS) `prices` attribute of the average-price sensor, kWh or MWh scale | from integration source; includes VAT and fees only if the user set them up | +| tariff | `epex_spot.total_price`, `epex_spot.market_price` | EPEX Spot (HACS) `data` attribute: all-in total price or bare market price, unit `€/kWh` | from integration source | +| tariff | `octopus_energy.rates` | Octopus Energy (HACS) `rates` attribute of the current-day and next-day event entities, GBP/kWh incl. VAT | from integration source | +| tariff | `generic.price_list` | any sensor with a `prices` attribute `[{start, price}]` (SunCore's own convention) | generic | | forecast | `solcast.pv` | Solcast PV Forecast (HACS), `detailedForecast` P10/P50/P90 | from integration source | | region | `de` | Germany: EUR, `Europe/Berlin`, no remuneration at negative prices for new PV | law text `UNVERIFIED` here | | region | `generic` | neutral international profile | – | @@ -70,7 +75,7 @@ unverified: [] # facts you could not verify; required if tes - Tariff and forecast curves come from `series`: an entity attribute (`source: attribute`, lists of the given roles are concatenated) or the response of a read-only action (`source: action`). Only actions on the built-in allowlist - (`suncore/core/actions.py`, currently `tibber.get_prices`, + (`suncore/core/actions.py`, currently `tibber.get_prices`, `nordpool.get_prices_for_date`, `solcast_solar.query_forecast_data`, `weather.get_forecasts`) are accepted; any other service is refused at load time with the key `template.error.action_not_allowed`. Power units in a forecast mean the average power over the slot, energy units the energy @@ -128,3 +133,4 @@ Every addition is recorded below with the SunCore version that introduced it. | 0.3.0 (unreleased, Phase 2) | `region.currency` is optional for `country: generic` (`None` = currency of the Home Assistant configuration). | | 0.4.0 (unreleased, Phase 3) | New `defaults.control` kind `relays` (additive union member, ADR-0012 policy): 1–3 switch roles (`roles`) and `steps`, each step naming the relays that are on (`relays`) and the power it draws (`power_w`, strictly increasing, relay sets distinct). `DeviceConfig` accepts the same control. Used by `generic.water_heater_relays`. | | 0.5.0 (unreleased, Phase 4) | New template kind `battery` (`battery.schema.json`): `roles`, `controls` (union on `kind`: `min_soc`, `max_charge`, `max_discharge`, `grid_charge_power` numbers; `mode` select with option meanings; `force_charge` switch), optional `settle_s`. New capabilities `battery_soc`, `min_soc_limit`, `charge_limit`, `discharge_limit`, `grid_charge`, `battery_modes`. `series` of `source: attribute` takes an optional `list_path` for the generic attribute adapter and an optional `shape` (`list` default, or `mapping` for `{iso_timestamp: value}` attributes such as Forecast.Solar `wh_hours` and Open-Meteo Solar Forecast `wh_period_15m`; `fields` then holds only `value_unit`, so `fields.timestamp_field`/`value_field` became optional and are required only for lists of point objects). Tariff `price_unit` and `price_series.fields.value_unit` may be per MWh (`{currency}/MWh`, `EUR/MWh`); the value unit's currency must match `price_unit`'s (or be `{currency}`), and adapters convert to currency/kWh (`price_unit_factor`: MWh / 1000). Battery mode option `value` is kept verbatim (no whitespace stripping). HT/NT needs no template change: time windows and prices are contract data in the `tariff` configuration section (v3). | +| 0.5.0 (unreleased, Phase 4, WP4) | Tariff price curves (all additive): `series.fields.end_field` (slot end, slot length = `end - start`; lists only); action series take `date_field` (one call per delivery date, excludes `start_field`/`end_field`) with an optional `date_tz` (IANA zone of that delivery day, e.g. Nord Pool's CET day; default the site's zone) and `params` (`name`, `required`, `description` i18n key: request fields the user supplies in the tariff configuration, e.g. Nord Pool `config_entry`, `areas`, `currency`); `response_path` may start with `*` (every entry of the response, e.g. `*` for `{area: [...]}`); the read-only action allowlist gains `nordpool.get_prices_for_date`. The `tariff` configuration section (v3) gains optional `import.role_entities`, `import.action_params`, `import.series_key` and `import.price_includes` (the user's statement overriding the template's classification). Eight tariff templates: `tibber.price` (updated), `nordpool.price`, `entsoe.price`, `entsoe.price_mwh`, `epex_spot.total_price`, `epex_spot.market_price`, `octopus_energy.rates`, `generic.price_list`. The currency symbols `€`/`£` that EPEX Spot puts in front of `/kWh` need no schema change: the matcher lists the literal units and `suncore.tariff.units.normalise_price_unit` maps them to ISO codes. | diff --git a/templates/schema/forecast.schema.json b/templates/schema/forecast.schema.json index 267aee7..bd73fea 100644 --- a/templates/schema/forecast.schema.json +++ b/templates/schema/forecast.schema.json @@ -1,9 +1,65 @@ { "$defs": { + "ActionParam": { + "additionalProperties": false, + "description": "A field of the action's request that the user's tariff configuration supplies.\n\nThe value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the\nNord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value.", + "properties": { + "description": { + "maxLength": 120, + "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", + "title": "Description", + "type": "string" + }, + "name": { + "maxLength": 200, + "minLength": 1, + "title": "Name", + "type": "string" + }, + "required": { + "default": true, + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "name", + "description" + ], + "title": "ActionParam", + "type": "object" + }, "ActionSeries": { "additionalProperties": false, "description": "Series returned by a read-only action (``return_response`` is implied).", "properties": { + "date_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Field" + }, + "date_tz": { + "anyOf": [ + { + "pattern": "^[A-Za-z_]+(/[A-Za-z_+\\-0-9]+){1,2}$", + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Tz" + }, "domain": { "maxLength": 48, "pattern": "^[a-z][a-z0-9_]*$", @@ -33,9 +89,18 @@ "title": "Max Horizon H", "type": "integer" }, + "params": { + "default": [], + "items": { + "$ref": "#/$defs/ActionParam" + }, + "maxItems": 8, + "title": "Params", + "type": "array" + }, "response_path": { "maxLength": 200, - "pattern": "^[A-Za-z0-9_]+(\\.([A-Za-z0-9_]+|\\*))*$", + "pattern": "^(\\*|[A-Za-z0-9_]+)(\\.([A-Za-z0-9_]+|\\*))*$", "title": "Response Path", "type": "string" }, @@ -327,6 +392,20 @@ "additionalProperties": false, "description": "Names of the fields of one series point and the unit of its values.\n\n``timestamp_field`` and ``value_field`` are required for a list of point objects\n(``action`` series, ``attribute`` series of shape ``list``) and absent for an\n``attribute`` series of shape ``mapping``, whose keys are the timestamps and whose\nvalues are the values.", "properties": { + "end_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "End Field" + }, "p10_field": { "anyOf": [ { diff --git a/templates/schema/tariff.schema.json b/templates/schema/tariff.schema.json index f3ce82a..ad01729 100644 --- a/templates/schema/tariff.schema.json +++ b/templates/schema/tariff.schema.json @@ -1,9 +1,65 @@ { "$defs": { + "ActionParam": { + "additionalProperties": false, + "description": "A field of the action's request that the user's tariff configuration supplies.\n\nThe value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the\nNord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value.", + "properties": { + "description": { + "maxLength": 120, + "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", + "title": "Description", + "type": "string" + }, + "name": { + "maxLength": 200, + "minLength": 1, + "title": "Name", + "type": "string" + }, + "required": { + "default": true, + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "name", + "description" + ], + "title": "ActionParam", + "type": "object" + }, "ActionSeries": { "additionalProperties": false, "description": "Series returned by a read-only action (``return_response`` is implied).", "properties": { + "date_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Field" + }, + "date_tz": { + "anyOf": [ + { + "pattern": "^[A-Za-z_]+(/[A-Za-z_+\\-0-9]+){1,2}$", + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Tz" + }, "domain": { "maxLength": 48, "pattern": "^[a-z][a-z0-9_]*$", @@ -33,9 +89,18 @@ "title": "Max Horizon H", "type": "integer" }, + "params": { + "default": [], + "items": { + "$ref": "#/$defs/ActionParam" + }, + "maxItems": 8, + "title": "Params", + "type": "array" + }, "response_path": { "maxLength": 200, - "pattern": "^[A-Za-z0-9_]+(\\.([A-Za-z0-9_]+|\\*))*$", + "pattern": "^(\\*|[A-Za-z0-9_]+)(\\.([A-Za-z0-9_]+|\\*))*$", "title": "Response Path", "type": "string" }, @@ -327,6 +392,20 @@ "additionalProperties": false, "description": "Names of the fields of one series point and the unit of its values.\n\n``timestamp_field`` and ``value_field`` are required for a list of point objects\n(``action`` series, ``attribute`` series of shape ``list``) and absent for an\n``attribute`` series of shape ``mapping``, whose keys are the timestamps and whose\nvalues are the values.", "properties": { + "end_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "End Field" + }, "p10_field": { "anyOf": [ { diff --git a/templates/schema/template.schema.json b/templates/schema/template.schema.json index 1c860c7..c3683b3 100644 --- a/templates/schema/template.schema.json +++ b/templates/schema/template.schema.json @@ -1,9 +1,65 @@ { "$defs": { + "ActionParam": { + "additionalProperties": false, + "description": "A field of the action's request that the user's tariff configuration supplies.\n\nThe value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the\nNord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value.", + "properties": { + "description": { + "maxLength": 120, + "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", + "title": "Description", + "type": "string" + }, + "name": { + "maxLength": 200, + "minLength": 1, + "title": "Name", + "type": "string" + }, + "required": { + "default": true, + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "name", + "description" + ], + "title": "ActionParam", + "type": "object" + }, "ActionSeries": { "additionalProperties": false, "description": "Series returned by a read-only action (``return_response`` is implied).", "properties": { + "date_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Field" + }, + "date_tz": { + "anyOf": [ + { + "pattern": "^[A-Za-z_]+(/[A-Za-z_+\\-0-9]+){1,2}$", + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Tz" + }, "domain": { "maxLength": 48, "pattern": "^[a-z][a-z0-9_]*$", @@ -33,9 +89,18 @@ "title": "Max Horizon H", "type": "integer" }, + "params": { + "default": [], + "items": { + "$ref": "#/$defs/ActionParam" + }, + "maxItems": 8, + "title": "Params", + "type": "array" + }, "response_path": { "maxLength": 200, - "pattern": "^[A-Za-z0-9_]+(\\.([A-Za-z0-9_]+|\\*))*$", + "pattern": "^(\\*|[A-Za-z0-9_]+)(\\.([A-Za-z0-9_]+|\\*))*$", "title": "Response Path", "type": "string" }, @@ -1487,6 +1552,20 @@ "additionalProperties": false, "description": "Names of the fields of one series point and the unit of its values.\n\n``timestamp_field`` and ``value_field`` are required for a list of point objects\n(``action`` series, ``attribute`` series of shape ``list``) and absent for an\n``attribute`` series of shape ``mapping``, whose keys are the timestamps and whose\nvalues are the values.", "properties": { + "end_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "End Field" + }, "p10_field": { "anyOf": [ { diff --git a/templates/tariff/entsoe.price.yaml b/templates/tariff/entsoe.price.yaml new file mode 100644 index 0000000..6a6ccc9 --- /dev/null +++ b/templates/tariff/entsoe.price.yaml @@ -0,0 +1,50 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# ENTSO-E (HACS `JaccoR/hass-entso-e`, domain `entsoe`). The price list sits on the "Average +# electricity price" sensor (`avg_price`) in the attribute `prices` (today and tomorrow): +# `[{"time": "2026-10-16 00:00:00+02:00", "price": 0.123}]`, local `str(datetime)`, slot start. +# Slot length = the integration's configured period (60 or 15 minutes), derived from the +# spacing. Unit `/kWh` (default scale). The integration adds the user's modifier +# template and VAT to the price: it is the market price only if the user configured none; say +# so with `price_includes` in the tariff configuration. For the `MWh` scale use +# `entsoe.price_mwh`. +id: entsoe.price +kind: tariff +schema_version: 1 +name: template.entsoe.price.name +source: + - title: "hass-entso-e v0.7.5 sensor.py (avg_price sensor with prices, prices_today, prices_tomorrow)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/sensor.py" + date: 2026-10-16 + - title: "hass-entso-e v0.7.5 coordinator.py (entry shape {time, price}, calc_price)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/coordinator.py" + date: 2026-10-16 + - title: "hass-entso-e v0.7.5 const.py (period PT60M or PT15M, energy scale kWh or MWh)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/const.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - Read from the integration source (tag v0.7.5, commit cbdf67ac) only; not observed on a running Home Assistant. + - 'Entity id and translation key of the `avg_price` sensor: the role matches platform and unit only; pick "Average electricity price", the only sensor with the price list.' + - '`spot_only` is right for an installation without modifier template and VAT; otherwise the price is an end price and the user states `price_includes: all_in` (else the formula counts fees twice).' + - '`prices` holds today and tomorrow, or yesterday and today while tomorrow is unpublished; SunCore keeps only the future part.' +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [entsoe] + unit_pattern: '^[A-Z]{3}/kWh$' + description: template.entsoe.price.role.price +price_unit: "{currency}/kWh" +price_includes: spot_only +price_series: + source: attribute + roles: [price] + attribute: prices + shape: list + fields: + timestamp_field: time + value_field: price + value_unit: "{currency}/kWh" diff --git a/templates/tariff/entsoe.price_mwh.yaml b/templates/tariff/entsoe.price_mwh.yaml new file mode 100644 index 0000000..8b02bb0 --- /dev/null +++ b/templates/tariff/entsoe.price_mwh.yaml @@ -0,0 +1,51 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# ENTSO-E (HACS `JaccoR/hass-entso-e`, domain `entsoe`). The price list sits on the "Average +# electricity price" sensor (`avg_price`) in the attribute `prices` (today and tomorrow): +# `[{"time": "2026-10-16 00:00:00+02:00", "price": 0.123}]`, local `str(datetime)`, slot start. +# Slot length = the integration's configured period (60 or 15 minutes), derived from the +# spacing. Unit `/MWh`: this template is for an installation configured with the +# `MWh` energy scale (the sensor unit says `/MWh`); the default scale is +# `entsoe.price`. The integration adds the user's modifier template and VAT to the price: it +# is the market price only if the user configured none; say so with `price_includes` in the +# tariff configuration. +id: entsoe.price_mwh +kind: tariff +schema_version: 1 +name: template.entsoe.price_mwh.name +source: + - title: "hass-entso-e v0.7.5 sensor.py (avg_price sensor with prices, prices_today, prices_tomorrow)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/sensor.py" + date: 2026-10-16 + - title: "hass-entso-e v0.7.5 coordinator.py (entry shape {time, price}, calc_price)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/coordinator.py" + date: 2026-10-16 + - title: "hass-entso-e v0.7.5 const.py (period PT60M or PT15M, energy scale kWh or MWh)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/const.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - Read from the integration source (tag v0.7.5, commit cbdf67ac) only; not observed on a running Home Assistant. + - 'Entity id and translation key of the `avg_price` sensor: the role matches platform and unit only; pick "Average electricity price", the only sensor with the price list.' + - '`spot_only` is right for an installation without modifier template and VAT; otherwise the price is an end price and the user states `price_includes: all_in` (else the formula counts fees twice).' + - '`prices` holds today and tomorrow, or yesterday and today while tomorrow is unpublished; SunCore keeps only the future part.' +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [entsoe] + unit_pattern: '^[A-Z]{3}/MWh$' + description: template.entsoe.price_mwh.role.price +price_unit: "{currency}/MWh" +price_includes: spot_only +price_series: + source: attribute + roles: [price] + attribute: prices + shape: list + fields: + timestamp_field: time + value_field: price + value_unit: "{currency}/MWh" diff --git a/templates/tariff/epex_spot.market_price.yaml b/templates/tariff/epex_spot.market_price.yaml new file mode 100644 index 0000000..fa53052 --- /dev/null +++ b/templates/tariff/epex_spot.market_price.yaml @@ -0,0 +1,51 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# EPEX Spot (HACS `mampfes/ha_epex_spot`, domain `epex_spot`). The "Total Price" sensor carries +# the whole curve in the attribute `data`: `[{"start_time", "end_time", "price_per_kwh"}]` +# (local ISO 8601, `price_per_kwh` for EUR and GBP alike). "Market Price" is the bare +# market price (the source clients convert MWh to kWh): without surcharges and VAT, so a price +# formula in the tariff configuration turns it into the end price. For the price including +# the integration's surcharges use `epex_spot.total_price`. +# Sensor unit: the currency SYMBOL (`€/kWh`, `£/kWh`), not the ISO code - the matcher lists the +# literals, SunCore maps them to EUR/GBP (`suncore.tariff.units`). +id: epex_spot.market_price +kind: tariff +schema_version: 1 +name: template.epex_spot.market_price.name +source: + - title: "ha_epex_spot 4.1.0 sensor.py (Total Price and Market Price sensors, data attribute)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/sensor.py" + date: 2026-10-16 + - title: "ha_epex_spot 4.1.0 const.py (attribute names, unit literals)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/const.py" + date: 2026-10-16 + - title: "ha_epex_spot 4.1.0 SourceShell.py (to_total_price: surcharges and VAT)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/SourceShell.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - "Read from the integration source (tag 4.1.0, commit 2aad1eb7) only; not observed on a running Home Assistant." + - "Entity ids and translation keys: the role matches platform and the unit literal only; \"Total Price\" and \"Market Price\" share the unit, so both are candidates and the user picks \"Market Price\"." + - "Which sources deliver a bare market price in this sensor was read from the source clients only (MWh converted to kWh)." + - "Slot length is `end_time - start_time` (configurable per entry, 60 minutes by default, 15 or 60 for Energy-Charts)." +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [epex_spot] + units: ["€/kWh", "£/kWh"] + description: template.epex_spot.market_price.role.price +price_unit: "{currency}/kWh" +price_includes: spot_only +price_series: + source: attribute + roles: [price] + attribute: data + shape: list + fields: + timestamp_field: start_time + end_field: end_time + value_field: price_per_kwh + value_unit: "{currency}/kWh" diff --git a/templates/tariff/epex_spot.total_price.yaml b/templates/tariff/epex_spot.total_price.yaml new file mode 100644 index 0000000..7d3f85e --- /dev/null +++ b/templates/tariff/epex_spot.total_price.yaml @@ -0,0 +1,50 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# EPEX Spot (HACS `mampfes/ha_epex_spot`, domain `epex_spot`). The "Total Price" sensor carries +# the whole curve in the attribute `data`: `[{"start_time", "end_time", "price_per_kwh"}]` +# (local ISO 8601, `price_per_kwh` for EUR and GBP alike). "Total Price" is the market price +# plus the percentage and absolute surcharges the user configured, times (1 + VAT): an all-in +# price, no price formula on top. For the bare market price use `epex_spot.market_price`. +# Sensor unit: the currency SYMBOL (`€/kWh`, `£/kWh`), not the ISO code - the matcher lists the +# literals, SunCore maps them to EUR/GBP (`suncore.tariff.units`). +id: epex_spot.total_price +kind: tariff +schema_version: 1 +name: template.epex_spot.total_price.name +source: + - title: "ha_epex_spot 4.1.0 sensor.py (Total Price and Market Price sensors, data attribute)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/sensor.py" + date: 2026-10-16 + - title: "ha_epex_spot 4.1.0 const.py (attribute names, unit literals)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/const.py" + date: 2026-10-16 + - title: "ha_epex_spot 4.1.0 SourceShell.py (to_total_price: surcharges and VAT)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/SourceShell.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - "Read from the integration source (tag 4.1.0, commit 2aad1eb7) only; not observed on a running Home Assistant." + - "Entity ids and translation keys: the role matches platform and the unit literal only; \"Total Price\" and \"Market Price\" share the unit, so both are candidates and the user picks \"Total Price\"." + - "The Tibber source of the integration returns its price as is (no surcharges); the total sensor is then Tibber's own price." + - "Slot length is `end_time - start_time` (configurable per entry, 60 minutes by default, 15 or 60 for Energy-Charts)." +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [epex_spot] + units: ["€/kWh", "£/kWh"] + description: template.epex_spot.total_price.role.price +price_unit: "{currency}/kWh" +price_includes: all_in +price_series: + source: attribute + roles: [price] + attribute: data + shape: list + fields: + timestamp_field: start_time + end_field: end_time + value_field: price_per_kwh + value_unit: "{currency}/kWh" diff --git a/templates/tariff/generic.price_list.yaml b/templates/tariff/generic.price_list.yaml new file mode 100644 index 0000000..d432ec6 --- /dev/null +++ b/templates/tariff/generic.price_list.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# Generic price list: any sensor with an attribute `prices` that is a list of +# `{"start": , "price": }`. This is SunCore's +# own convention for a template sensor the user writes (no integration is known to produce +# it); the slot length is derived from the spacing of `start`. +id: generic.price_list +kind: tariff +schema_version: 1 +name: template.generic.price_list.name +source: + - title: "Home Assistant template sensor (attributes option)" + url: "https://www.home-assistant.io/integrations/template/" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - "SunCore's own convention, not the shape of an existing integration: the attribute name `prices` and the fields `start` and `price` are defined here." + - "The Home Assistant template integration page could not be read in the authoring session (documentation sites unreachable); that template sensors accept attributes is general knowledge, not verified." + - "The price is treated as the end price (`all_in`); a spot-only list needs its own template." +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + unit_pattern: '^[A-Z]{3}/kWh$' + description: template.generic.price_list.role.price +price_unit: "{currency}/kWh" +price_includes: all_in +price_series: + source: attribute + roles: [price] + attribute: prices + shape: list + fields: + timestamp_field: start + value_field: price + value_unit: "{currency}/kWh" diff --git a/templates/tariff/nordpool.price.yaml b/templates/tariff/nordpool.price.yaml new file mode 100644 index 0000000..1d0b59d --- /dev/null +++ b/templates/tariff/nordpool.price.yaml @@ -0,0 +1,66 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# Nord Pool (core integration `nordpool`, cloud polling). Day-ahead market prices per area +# from the read-only action `nordpool.get_prices_for_date` (one call per delivery date): +# response `{"": [{"start", "end", "price"}]}`, UTC with `+00:00`, currency per MWh, +# VAT, grid fees and levies NOT included (`spot_only`): add a price formula in the tariff +# configuration. `date` is the CET delivery day (`date_tz`). Slot length is `end - start` (15 or 60 minutes, a series may mix both). +id: nordpool.price +kind: tariff +schema_version: 1 +name: template.nordpool.price.name +source: + - title: "home-assistant/core nordpool services.py (get_prices_for_date, response shape)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/nordpool/services.py" + date: 2026-10-16 + - title: "home-assistant/core nordpool services.yaml (config_entry, date, areas, currency)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/nordpool/services.yaml" + date: 2026-10-16 + - title: "home-assistant/core nordpool sensor.py (currency/kWh sensors, slot length end - start)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/nordpool/sensor.py" + date: 2026-10-16 + - title: "pynordpool 0.4.0 (PyPI wheel: model.py, util.py)" + url: "https://pypi.org/project/pynordpool/0.4.0/" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - Read from the integration source (core 5cfe9aad, pynordpool 0.4.0) only; not observed on a running Home Assistant. + - 'Entity ids and translation keys of the price sensors: all carry `/kWh`, so the role matches platform and unit only and the user picks the current price sensor.' + - Exact publication time of tomorrow's prices (afternoon CET expected); before it the action returns an empty list for that date. + - The action accepts dates from two months back to one day ahead (strings.json); SunCore asks for today and tomorrow only. + - The price is the raw day-ahead value in currency per MWh of the entry's currency (or the optional `currency` field); the integration's exchange-rate handling was not read. + - The `config_entry` id has to be entered by the user; which registry command exposes it to SunCore was not verified. +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [nordpool] + unit_pattern: '^[A-Z]{3}/kWh$' + description: template.nordpool.price.role.price +price_unit: "{currency}/MWh" +price_includes: spot_only +price_series: + source: action + domain: nordpool + service: get_prices_for_date + date_field: date + date_tz: Europe/Berlin + params: + - name: config_entry + required: true + description: template.nordpool.price.param.config_entry + - name: areas + required: false + description: template.nordpool.price.param.areas + - name: currency + required: false + description: template.nordpool.price.param.currency + response_path: "*" + fields: + timestamp_field: start + end_field: end + value_field: price + value_unit: "{currency}/MWh" + max_horizon_h: 24 diff --git a/templates/tariff/octopus_energy.rates.yaml b/templates/tariff/octopus_energy.rates.yaml new file mode 100644 index 0000000..3595765 --- /dev/null +++ b/templates/tariff/octopus_energy.rates.yaml @@ -0,0 +1,64 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# Octopus Energy (HACS `BottlecapDave/HomeAssistant-OctopusEnergy`, domain `octopus_energy`). +# The rate lists are on EVENT entities (`..._current_day_rates`, `..._next_day_rates`), not on +# the rate sensors: core's EventEntity exposes the last event's data as attributes, so the +# attribute `rates` holds `[{"start", "end", "value_inc_vat"}]` (local datetimes, GBP/kWh +# including VAT). SunCore merges the current and the next day by `start`. The slot length is +# `end - start` (30 minutes for the usual tariffs). Import rates only; export rates have their +# own `..._export_...` entities and are not a price source of this template. +id: octopus_energy.rates +kind: tariff +schema_version: 1 +name: template.octopus_energy.rates.name +source: + - title: "HomeAssistant-OctopusEnergy v19.2.1 electricity/rates_current_day.py (event entity, rates)" + url: "https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/blob/v19.2.1/custom_components/octopus_energy/electricity/rates_current_day.py" + date: 2026-10-16 + - title: "HomeAssistant-OctopusEnergy v19.2.1 utils/__init__.py (private_rates_to_public_rates: start, end, value_inc_vat)" + url: "https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/blob/v19.2.1/custom_components/octopus_energy/utils/__init__.py" + date: 2026-10-16 + - title: "HomeAssistant-OctopusEnergy v19.2.1 electricity/current_rate.py (GBP/kWh current rate sensor)" + url: "https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/blob/v19.2.1/custom_components/octopus_energy/electricity/current_rate.py" + date: 2026-10-16 + - title: "home-assistant/core event/entity.py (state_attributes: event_type plus last event data)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/event/entity.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - Read from the integration source (tag v19.2.1, commit ccfbccc3) only; not observed on a running Home Assistant. + - 'Entity ids and translation keys of the event entities: the roles match domain `event` and platform only; current-day, next-day, previous-day and export entities are all candidates.' + - The event fires only when the rates changed and is restored after a restart; before the first event the `rates` attribute is missing. + - Whether `value_inc_vat` is a complete end price (standing charges, caps) is not stated; SunCore treats it as all-in. +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [octopus_energy] + units: ["GBP/kWh"] + description: template.octopus_energy.rates.role.price + current_day_rates: + matcher: + domain: event + platforms: [octopus_energy] + description: template.octopus_energy.rates.role.current_day_rates + next_day_rates: + required: false + matcher: + domain: event + platforms: [octopus_energy] + description: template.octopus_energy.rates.role.next_day_rates +price_unit: "GBP/kWh" +price_includes: all_in +price_series: + source: attribute + roles: [current_day_rates, next_day_rates] + attribute: rates + shape: list + fields: + timestamp_field: start + end_field: end + value_field: value_inc_vat + value_unit: "GBP/kWh" diff --git a/templates/tariff/tibber.price.yaml b/templates/tariff/tibber.price.yaml index f642982..7591013 100644 --- a/templates/tariff/tibber.price.yaml +++ b/templates/tariff/tibber.price.yaml @@ -1,27 +1,31 @@ # yaml-language-server: $schema=../schema/tariff.schema.json # Tibber (core integration `tibber`, cloud polling). The price sensor only holds the current -# slot; the curve of today and tomorrow comes from the read-only action `tibber.get_prices`. +# slot; the curve of today and tomorrow comes from the read-only action `tibber.get_prices` +# (response `{"prices": {"": [{"start_time", "price"}]}}`, `price` = energy plus +# taxes). Several homes: set `series_key` in the tariff configuration to the home name. id: tibber.price kind: tariff schema_version: 1 name: template.tibber.price.name source: - title: "home-assistant/core tibber sensor.py (electricity_price, unit, state)" - url: "https://github.com/home-assistant/core/blob/14f093e/homeassistant/components/tibber/sensor.py" - date: 2026-10-13 - - title: "home-assistant/core tibber services.py (get_prices, response shape)" - url: "https://github.com/home-assistant/core/blob/14f093e/homeassistant/components/tibber/services.py" - date: 2026-10-13 + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/tibber/sensor.py" + date: 2026-10-16 + - title: "home-assistant/core tibber services.py (get_prices, response shape, price_total)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/tibber/services.py" + date: 2026-10-16 - title: "home-assistant/core tibber services.yaml (start, end fields)" - url: "https://github.com/home-assistant/core/blob/14f093e/homeassistant/components/tibber/services.yaml" - date: 2026-10-13 + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/tibber/services.yaml" + date: 2026-10-16 tested_with: [] capabilities: [price_now, price_curve] unverified: - - "Whether grid fees (network charges) are included in Tibber's `total` price is country dependent; SunCore treats the value as all-in (`price_includes: all_in`) without checking." - - "Read from the integration source (core 14f093e, pyTibber 0.37.6) only; not observed on a running Home Assistant." - - "Exact entity id (derived from the home nickname) and the time Tibber publishes tomorrow's prices." - - "Slot length is not part of the response: 15 min with pyTibber 0.37, hourly with older libraries (resolution derived from the timestamps)." + - Read from the integration source (core 5cfe9aad, pyTibber 0.37.6) only; not observed on a running Home Assistant. + - '`price` is the library''s `total` (energy plus tax). Grid fees are country dependent; SunCore treats it as all-in (plan answer 9). A supplier contract with extra fees stays the user''s call.' + - Exact entity id (derived from the home nickname) and the time Tibber publishes tomorrow's prices (about 13:00 local). + - 'Slot length is not in the response: 15 min with pyTibber 0.37, hourly with older libraries; derived from the timestamps, a mix of both is accepted.' + - '`start`/`end` are sent as local ISO 8601 with offset; the source documents `YYYY-MM-DD HH:MM:SS` or ISO 8601 (parse_datetime), the offset form was not run against a live system.' + - The home name is the key of the response (two homes with the same name collide in the integration); with several homes set `series_key`. direction: import tariff_type: dynamic roles: diff --git a/tests/api/conftest.py b/tests/api/conftest.py index 3efc871..9164d30 100644 --- a/tests/api/conftest.py +++ b/tests/api/conftest.py @@ -22,6 +22,7 @@ HAUnavailableError, HealthReport, PeerPolicy, + TariffNotConfiguredError, UnknownRoleError, UnknownTemplateError, ) @@ -57,6 +58,7 @@ ImportRejectedError, UnknownSectionError, ) +from suncore.tariff.report import PriceReport from suncore.templates import TemplateCatalog, load_templates TEMPLATES_DIR = Path(__file__).resolve().parents[2] / "templates" @@ -208,6 +210,14 @@ def __init__(self) -> None: self.proposal_list: list[Decision] = [] self.operation = OperationConfig() self.control_listeners: list[Callable[[], None]] = [] + self.price_report: PriceReport | None = None + self.price_hours: list[int] = [] + + async def prices(self, hours: int) -> PriceReport: + self.price_hours.append(hours) + if self.price_report is None: + raise TariffNotConfiguredError + return self.price_report async def health(self) -> HealthReport: self.health_calls += 1 diff --git a/tests/api/test_config_api.py b/tests/api/test_config_api.py index 72a3930..9be4001 100644 --- a/tests/api/test_config_api.py +++ b/tests/api/test_config_api.py @@ -190,3 +190,56 @@ async def test_tariff_formula_on_an_all_in_template_is_rejected(services: FakeSe } assert plain.status_code == 200 assert entity.status_code == 200 + + +async def test_the_users_price_statement_decides_whether_a_formula_is_allowed( + services: FakeServices, +) -> None: + """ENTSO-E is spot-only by default but may carry the user's modifier template and VAT.""" + formula = {"grid_fee": 0.08, "vat_pct": 19} + export = VALID["tariff"]["export"] + + def body(template: str, includes: str | None) -> dict[str, Any]: + imp: dict[str, Any] = {"kind": "dynamic", "template_id": template, "formula": formula} + if includes is not None: + imp["price_includes"] = includes + return {"import": imp, "export": export} + + async with client_for(create_app(services)) as client: + spot_default = await client.put("/api/v1/config/tariff", json=body("entsoe.price", None)) + declared_all_in = await client.put( + "/api/v1/config/tariff", json=body("entsoe.price", "all_in") + ) + declared_spot = await client.put( # a contract that passes the spot price through + "/api/v1/config/tariff", json=body("tibber.price", "spot_only") + ) + assert spot_default.status_code == 200 + assert declared_all_in.status_code == 422 + assert declared_all_in.json()["issues"][0]["key"] == "api.validation.import_formula_all_in" + assert declared_spot.status_code == 200 + + +async def test_required_request_fields_of_the_template_are_checked(services: FakeServices) -> None: + """m1: Nord Pool needs the `config_entry` id; a tariff without it is rejected with a key.""" + export = VALID["tariff"]["export"] + base = {"kind": "dynamic", "template_id": "nordpool.price"} + async with client_for(create_app(services)) as client: + bad = await client.put("/api/v1/config/tariff", json={"import": base, "export": export}) + optional_only = await client.put( + "/api/v1/config/tariff", + json={"import": {**base, "action_params": {"areas": ["SE3"]}}, "export": export}, + ) + good = await client.put( + "/api/v1/config/tariff", + json={"import": {**base, "action_params": {"config_entry": "01H"}}, "export": export}, + ) + assert bad.status_code == 422 + assert bad.json()["issues"] == [ + { + "loc": ["body", "import", "action_params", "config_entry"], + "key": "api.validation.import_param_missing", + "args": {"template_id": "nordpool.price", "field": "config_entry"}, + } + ] + assert optional_only.status_code == 422 + assert good.status_code == 200 diff --git a/tests/api/test_prices_api.py b/tests/api/test_prices_api.py new file mode 100644 index 0000000..d13bf96 --- /dev/null +++ b/tests/api/test_prices_api.py @@ -0,0 +1,111 @@ +# SPDX-License-Identifier: Apache-2.0 +"""``GET /api/v1/prices``: the 15-minute planning prices with source and freshness.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta + +from suncore.api import create_app +from suncore.tariff.report import ( + PriceFreshness, + PriceQuality, + PriceReport, + PriceSlot, + PriceSourceInfo, +) +from tests.api.conftest import FakeServices, client_for + +T0 = datetime(2026, 10, 16, 8, 0, tzinfo=UTC) + + +def report() -> PriceReport: + return PriceReport( + price_includes="all_in", + formula_missing=False, + start=T0, + slots=[ + PriceSlot(start=T0, import_price=0.31, export_price=0.08), + PriceSlot(start=T0 + timedelta(minutes=15), import_price=-0.01, export_price=0.0), + PriceSlot(start=T0 + timedelta(minutes=30), import_price=None, export_price=None), + ], + source=PriceSourceInfo( + import_source_id="tibber.price", + import_kind="dynamic", + source_price_includes="all_in", + price_includes="all_in", + formula_applied=False, + export_kind="fixed", + negative_price_rule="no_remuneration", + export_zeroed_slots=1, + native_step_min=15, + currency="EUR", + ), + freshness=PriceFreshness( + status="fresh", + fetched_at=T0, + age_s=12.5, + known_until=T0 + timedelta(hours=36), + next_refresh_at=T0 + timedelta(hours=1), + last_error=None, + ), + quality=PriceQuality(slots=3, known_slots=2, has_tomorrow=True, dropped_points=0), + ) + + +async def test_prices_are_returned_with_source_and_freshness(services: FakeServices) -> None: + services.price_report = report() + async with client_for(create_app(services)) as client: + r = await client.get("/api/v1/prices") + assert r.status_code == 200 + body = r.json() + assert services.price_hours == [48] # the default + assert body["unit"] == "currency/kWh" + assert body["step_min"] == 15 + assert body["slots"][1] == { + "start": "2026-10-16T08:15:00Z", + "import_price": -0.01, + "export_price": 0.0, + } + assert body["slots"][2]["import_price"] is None + assert body["source"]["import_source_id"] == "tibber.price" + assert body["source"]["negative_price_rule"] == "no_remuneration" + assert body["freshness"]["status"] == "fresh" + assert body["freshness"]["last_error"] is None + assert body["quality"] == { + "slots": 3, + "known_slots": 2, + "has_tomorrow": True, + "dropped_points": 0, + "carried_slots": 0, + } + + +async def test_hours_parameter_is_passed_and_bounded(services: FakeServices) -> None: + services.price_report = report() + async with client_for(create_app(services)) as client: + ok = await client.get("/api/v1/prices", params={"hours": 24}) + zero = await client.get("/api/v1/prices", params={"hours": 0}) + many = await client.get("/api/v1/prices", params={"hours": 73}) + text = await client.get("/api/v1/prices", params={"hours": "soon"}) + assert ok.status_code == 200 + assert services.price_hours == [24] + assert zero.status_code == many.status_code == text.status_code == 422 + assert zero.json()["detail"] == "api.error.validation" + + +async def test_no_tariff_is_a_404_with_a_catalogue_key(services: FakeServices) -> None: + async with client_for(create_app(services)) as client: + r = await client.get("/api/v1/prices") + assert r.status_code == 404 + assert r.json() == {"detail": "api.error.tariff_not_configured"} + + +async def test_prices_are_in_the_openapi_document(services: FakeServices) -> None: + async with client_for(create_app(services)) as client: + schema = ( + (await client.get("/openapi.json")).json() if False else create_app(services).openapi() + ) + operation = schema["paths"]["/api/v1/prices"]["get"] + assert operation["operationId"] == "get_prices" + assert {"200", "404", "422"} <= set(operation["responses"]) + assert "PriceReport" in schema["components"]["schemas"] diff --git a/tests/app/test_adapters.py b/tests/app/test_adapters.py new file mode 100644 index 0000000..b538569 --- /dev/null +++ b/tests/app/test_adapters.py @@ -0,0 +1,236 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Composition of the tariff service: the action caller, the cache reader, the builders.""" + +from __future__ import annotations + +from collections.abc import Mapping +from typing import Any +from zoneinfo import ZoneInfo + +import pytest + +from suncore.app.adapters import ( + ConnectionActionCaller, + build_tariff_plan, + build_tariff_service, + cache_reader, + negative_price_rule, +) +from suncore.core.config import ExportTariff, ExportTier, ImportTariff, RegionConfig, TariffConfig +from suncore.core.site import EntityRef, GridConfig, PvArray, SiteConfig +from suncore.core.tariff import PriceFormula, TouPeriod, TouTariff, TouWindow +from suncore.ha import EntityCache, HAError +from suncore.ha.connection import ActionRateLimitedError, EntityState, EntityUpdate +from suncore.tariff import ( + CurrentPriceSource, + ExportConfigError, + FixedPriceSource, + SourceFailedError, + SourceThrottledError, + TemplatePriceSource, + TouPriceSource, +) +from suncore.templates.models import NegativePriceRule +from tests.tariff.helpers import CATALOG, NOW + +BERLIN = ZoneInfo("Europe/Berlin") +DE = RegionConfig(region_id="de", currency="EUR", timezone="Europe/Berlin") +SITE = SiteConfig( + grid=GridConfig(power=EntityRef(entity_id="sensor.grid")), + pv=[PvArray(name="PV", power=EntityRef(entity_id="sensor.pv"), kwp=17.0)], +) + + +class Connection: + """Just enough of ``HAConnection`` for the action caller.""" + + def __init__(self) -> None: + self.error: Exception | None = None + self.calls: list[tuple[str, str, Mapping[str, Any] | None, float | None, float]] = [] + + async def call_action_response( + self, + domain: str, + service: str, + data: Mapping[str, Any] | None = None, + *, + target: Mapping[str, Any] | None = None, # noqa: ARG002 + min_interval_s: float | None = None, + max_wait_s: float = 0.0, + ) -> dict[str, Any]: + self.calls.append((domain, service, data, min_interval_s, max_wait_s)) + if self.error is not None: + raise self.error + return {"ok": True} + + +async def test_the_action_caller_passes_the_request_and_the_interval_through() -> None: + conn = Connection() + caller = ConnectionActionCaller(conn) # type: ignore[arg-type] + out = await caller("tibber", "get_prices", {"start": "x"}, min_interval_s=45.0, max_wait_s=31.0) + assert out == {"ok": True} + assert conn.calls == [("tibber", "get_prices", {"start": "x"}, 45.0, 31.0)] + + +async def test_a_rate_limited_call_becomes_a_throttle_not_a_failure() -> None: + conn = Connection() + conn.error = ActionRateLimitedError("tibber.get_prices", 12.5) + with pytest.raises(SourceThrottledError) as err: + await ConnectionActionCaller(conn)( + "tibber", "get_prices", {}, min_interval_s=30.0, max_wait_s=0.0 + ) # type: ignore[arg-type] + assert err.value.retry_after_s == 12.5 + + +@pytest.mark.parametrize("error", [HAError("down"), TimeoutError("slow")]) +async def test_home_assistant_errors_become_source_failures(error: Exception) -> None: + conn = Connection() + conn.error = error + with pytest.raises(SourceFailedError): + await ConnectionActionCaller(conn)( + "tibber", "get_prices", {}, min_interval_s=30.0, max_wait_s=0.0 + ) # type: ignore[arg-type] + + +def test_cache_reader() -> None: + cache = EntityCache() + cache.ingest( + EntityUpdate( + changed={ + "sensor.ok": EntityState("sensor.ok", "0.3", {"prices": []}), + "sensor.gone": EntityState("sensor.gone", "unavailable", {"prices": []}), + "event.new": EntityState("event.new", "unknown", {"event_types": ["x"]}), + }, + full=True, + ) + ) + read = cache_reader(cache) + ok = read("sensor.ok") + assert ok is not None + assert (ok.state, dict(ok.attributes)) == ("0.3", {"prices": []}) + assert read("sensor.gone") is None + assert read("sensor.absent") is None + unknown = read("event.new") + assert unknown is not None # an event entity is `unknown` until its first event + assert unknown.state == "unknown" + + +def test_the_negative_price_rule_comes_from_the_region_template() -> None: + assert negative_price_rule(CATALOG, DE) is NegativePriceRule.NO_REMUNERATION + generic = RegionConfig(region_id="generic", currency="EUR", timezone="UTC") + assert negative_price_rule(CATALOG, generic) is NegativePriceRule.NONE + other = RegionConfig(region_id="xx", currency="EUR", timezone="UTC") + assert negative_price_rule(CATALOG, other) is NegativePriceRule.NONE + + +def build(tariff: TariffConfig, site: SiteConfig | None = SITE) -> Any: + return build_tariff_plan( + tariff, + DE, + site, + BERLIN, + CATALOG, + connection=Connection(), # type: ignore[arg-type] + cache=EntityCache(), + clock=lambda: NOW, + ) + + +EXPORT = ExportTariff(kind="fixed", fixed_price=0.08) + + +def test_a_fixed_tariff_builds_a_fixed_source() -> None: + plan = build(TariffConfig(import_=ImportTariff(kind="fixed", fixed_price=0.3), export=EXPORT)) + assert isinstance(plan.source, FixedPriceSource) + assert plan.negative_rule is NegativePriceRule.NO_REMUNERATION + assert plan.total_kwp == 17.0 + assert plan.currency == "EUR" + + +def test_a_tou_tariff_builds_a_tou_source() -> None: + tou = TouTariff( + base_price=0.35, + periods=(TouPeriod(window=TouWindow(start="22:00", end="06:00"), price=0.25),), + ) + plan = build(TariffConfig(import_=ImportTariff(kind="tou", tou=tou), export=EXPORT)) + assert isinstance(plan.source, TouPriceSource) + + +def test_a_dynamic_tariff_builds_the_template_source_with_the_users_settings() -> None: + tariff = TariffConfig( + import_=ImportTariff( + kind="dynamic", + template_id="octopus_energy.rates", + price_entity=EntityRef(entity_id="sensor.rate"), + role_entities={ + "current_day_rates": EntityRef(entity_id="event.today"), + "next_day_rates": EntityRef(entity_id="event.tomorrow"), + }, + price_includes="spot_only", + formula=PriceFormula(grid_fee=0.1), + ), + export=EXPORT, + ) + plan = build(tariff) + assert isinstance(plan.source, TemplatePriceSource) + assert plan.source.watched_entities == ("event.today", "event.tomorrow", "sensor.rate") + assert plan.source.price_includes == "spot_only" # the user's statement beats the template + assert plan.formula is not None + + +def test_a_price_entity_without_a_template_uses_the_current_slot_only() -> None: + tariff = TariffConfig( + import_=ImportTariff(kind="dynamic", price_entity=EntityRef(entity_id="sensor.p")), + export=EXPORT, + ) + assert isinstance(build(tariff).source, CurrentPriceSource) + + +def test_an_unknown_or_unsuitable_template_builds_nothing() -> None: + unknown = TariffConfig( + import_=ImportTariff(kind="dynamic", template_id="no.such"), export=EXPORT + ) + assert build(unknown) is None + not_a_tariff = TariffConfig( + import_=ImportTariff(kind="dynamic", template_id="lg.thinq_climate"), export=EXPORT + ) + assert build(not_a_tariff) is None + + +def test_the_service_gets_the_configured_timing_and_the_store() -> None: + class Store: + async def store_prices(self, prices: object) -> int: # noqa: ARG002 + return 0 + + store = Store() + service = build_tariff_service( + TariffConfig(import_=ImportTariff(kind="fixed", fixed_price=0.3), export=EXPORT), + DE, + SITE, + BERLIN, + CATALOG, + connection=Connection(), # type: ignore[arg-type] + cache=EntityCache(), + clock=lambda: NOW, + store=store, + refresh_interval_s=1800.0, + ) + assert service is not None + assert service._settings.refresh_interval_s == 1800.0 + assert service._store is store + + +def test_a_tiered_export_needs_the_site_size() -> None: + tiered = ExportTariff( + kind="tiered", tiers=(ExportTier(up_to_kwp=10, price=0.08), ExportTier(price=0.07)) + ) + tariff = TariffConfig(import_=ImportTariff(kind="fixed", fixed_price=0.3), export=tiered) + kwargs: dict[str, Any] = { + "connection": Connection(), + "cache": EntityCache(), + "clock": lambda: NOW, + "store": None, + } + assert build_tariff_service(tariff, DE, SITE, BERLIN, CATALOG, **kwargs) is not None + with pytest.raises(ExportConfigError): + build_tariff_service(tariff, DE, None, BERLIN, CATALOG, **kwargs) diff --git a/tests/app/test_demo.py b/tests/app/test_demo.py index d461795..ed998cd 100644 --- a/tests/app/test_demo.py +++ b/tests/app/test_demo.py @@ -35,7 +35,7 @@ from suncore.core.site import EntityRef from suncore.ha.connection import CommandTimeoutError from suncore.sim.demo_config import WIZARD_STEPS -from suncore.sim.demo_devices import AC_ID +from suncore.sim.demo_devices import AC_ID, PRICE_ID from suncore.sim.fake_ha import SIM_ENTITY_IDS, FakeHAConnection, demo_site_config from suncore.templates import DeviceTemplate from tests.api.conftest import client_for, serving @@ -115,7 +115,8 @@ async def test_demo_live_feed_balance_closes(demo_runtime: Runtime) -> None: } ) """The demo starts with devices; the runtime subscribes to their entities too.""" -DEMO_SUBSCRIBED = frozenset(SIM_ENTITY_IDS) | DEMO_DEVICE_ENTITIES +DEMO_SUBSCRIBED = frozenset(SIM_ENTITY_IDS) | DEMO_DEVICE_ENTITIES | {PRICE_ID} +"""... and the price sensor of the tariff (it tells the price service when to look again).""" async def test_demo_starts_fully_configured(demo_runtime: Runtime) -> None: @@ -205,7 +206,9 @@ async def test_put_site_survives_subscribe_timeout( r = await client.put("/api/v1/config/site", json=reduced.model_dump(mode="json")) assert r.status_code == 200 assert (await demo_runtime.config.get_site()) == reduced # persisted - assert [e["event"] for e in logs if e["log_level"] == "warning"] == ["ha.subscribe_failed"] + # (the fixture's wall clock is not the simulator's, so the price service may warn as well) + warnings = [e["event"] for e in logs if e["log_level"] == "warning"] + assert [e for e in warnings if not e.startswith("tariff.")] == ["ha.subscribe_failed"] async def test_put_site_notifies_live_listeners(demo_runtime: Runtime) -> None: @@ -360,6 +363,7 @@ async def test_put_devices_resubscribes_and_shadows_new_ones(demo_runtime: Runti assert conn.subscriptions[-1] == frozenset(SIM_ENTITY_IDS) | { "switch.heater", "sensor.heater_power", + PRICE_ID, } assert await demo_runtime.get_section("devices") == stored @@ -392,4 +396,4 @@ async def test_import_reloads_devices(demo_runtime: Runtime) -> None: exported["sections"]["devices"]["body"]["devices"] = [] await demo_runtime.import_config(exported) assert demo_runtime.devices == DevicesConfig() - assert conn.subscriptions[-1] == frozenset(SIM_ENTITY_IDS) + assert conn.subscriptions[-1] == frozenset(SIM_ENTITY_IDS) | {PRICE_ID} diff --git a/tests/app/test_tariff_runtime.py b/tests/app/test_tariff_runtime.py new file mode 100644 index 0000000..c8844d0 --- /dev/null +++ b/tests/app/test_tariff_runtime.py @@ -0,0 +1,264 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The price service in the runtime: demo wiring, refresh on events, API, rebuild on change.""" + +from __future__ import annotations + +import asyncio +from collections.abc import AsyncIterator, Callable +from datetime import timedelta, timezone +from pathlib import Path + +import pytest + +from suncore.api import create_app +from suncore.app.demo import DemoClock +from suncore.app.main import build_runtime +from suncore.app.runtime import Runtime +from suncore.core.config import ExportTariff, ImportTariff, TariffConfig +from suncore.core.site import EntityRef +from suncore.ha.connection import ConnectionState, EntityState, EntityUpdate +from suncore.sim.demo_devices import PRICE_ID, sim_price +from suncore.sim.fake_ha import FakeHAConnection +from suncore.sim.scenario import load_scenario +from suncore.tariff import TariffService +from tests.api.conftest import client_for +from tests.app.conftest import demo_settings + +SPEED = 600.0 +START_HOUR = 14 +SIM_ZONE = timezone(timedelta(hours=2)) # the scenario's offset + + +class Subscribed(FakeHAConnection): + def __init__(self, scenario_name: str, clock: DemoClock) -> None: + super().__init__( + load_scenario(scenario_name), + clock=clock, + speed=SPEED, + sim_clock=clock, + start_offset_s=START_HOUR * 3600, + ) + self.subscriptions: list[frozenset[str]] = [] + + async def subscribe_entities(self, entity_ids: object) -> None: + self.subscriptions.append(frozenset(entity_ids)) # type: ignore[call-overload] + await super().subscribe_entities(entity_ids) # type: ignore[arg-type] + + +async def until(predicate: Callable[[], bool], timeout_s: float = 10.0) -> None: + async with asyncio.timeout(timeout_s): + while not predicate(): # noqa: ASYNC110 - polling a plain predicate + await asyncio.sleep(0.01) + + +async def start_runtime(tmp_path: Path, scenario_name: str) -> Runtime: + scenario = load_scenario(scenario_name) + clock = DemoClock( + scenario.start.replace(hour=START_HOUR), SPEED + ) # tomorrow's prices are published + connection = Subscribed(scenario_name, clock) + runtime = await build_runtime( + demo_settings(tmp_path, demo_speed=SPEED), env={}, connection=connection, clock=clock + ) + runtime.control_sleep = clock.sleep # the price loop polls in simulated time, like the demo + await runtime.start() + return runtime + + +@pytest.fixture +async def runtime(tmp_path: Path) -> AsyncIterator[Runtime]: + started = await start_runtime(tmp_path, "summer_day") + try: + yield started + finally: + await started.stop() + + +def service_of(runtime: Runtime) -> TariffService: + assert runtime.tariff is not None + return runtime.tariff + + +async def fetched(runtime: Runtime) -> TariffService: + service = service_of(runtime) + await until(lambda: service.report(24).freshness.fetched_at is not None) + return service + + +async def test_demo_tariff_goes_through_the_tibber_template_and_the_fake_action( + runtime: Runtime, +) -> None: + service = await fetched(runtime) + report = service.report(24) + assert report.source.import_source_id == "tibber.price" + assert report.source.import_kind == "dynamic" + assert report.source.native_step_min == 15 + assert report.source.price_includes == "all_in" + assert not report.source.formula_applied + assert report.freshness.status == "fresh" + assert report.quality.known_slots == report.quality.slots + assert report.quality.has_tomorrow + assert report.quality.slots > 24 * 4 + slot = report.slots[0] + assert slot.import_price == pytest.approx(sim_price(slot.start.astimezone(SIM_ZONE))) + assert slot.export_price == 0.08 # the demo's fixed feed-in remuneration + + +async def test_the_prices_reach_timeseries_db(runtime: Runtime) -> None: + await fetched(runtime) + assert runtime.timeseries is not None + from suncore.core.series import TimeRange # noqa: PLC0415 + + now = runtime.clock() + stored = await runtime.timeseries.read_prices( + "tibber.price", TimeRange(start=now, end=now + timedelta(hours=24)) + ) + assert stored + assert stored[0].step == timedelta(minutes=15) + assert stored[0].export_price is not None + + +async def test_negative_prices_scenario_zeroes_export_in_the_slots_below_zero( + tmp_path: Path, +) -> None: + runtime = await start_runtime(tmp_path, "negative_prices") + try: + service = await fetched(runtime) + report = service.report(24) + negative = [s for s in report.slots if s.import_price is not None and s.import_price < 0] + assert negative, "the scenario has a negative midday" + assert all(s.export_price == 0.0 for s in negative) + others = [s for s in report.slots if s.import_price is not None and s.import_price >= 0] + assert all(s.export_price == 0.08 for s in others) + assert report.source.negative_price_rule == "no_remuneration" # region template `de` + assert report.source.export_zeroed_slots == len(negative) + finally: + await runtime.stop() + + +async def test_the_api_serves_the_report(runtime: Runtime) -> None: + await fetched(runtime) + async with client_for(create_app(runtime)) as client: + r = await client.get("/api/v1/prices", params={"hours": 12}) + assert r.status_code == 200 + body = r.json() + assert body["freshness"]["status"] == "fresh" + assert 12 * 4 <= len(body["slots"]) <= 24 * 4 + 1 # at least 24 h are kept ... capped at 12 h + assert len(body["slots"]) <= 12 * 4 + 1 + + +async def test_the_price_entity_is_subscribed_and_a_change_marks_the_service( + runtime: Runtime, +) -> None: + service = await fetched(runtime) + conn = runtime.connection + assert isinstance(conn, Subscribed) + assert any(PRICE_ID in ids for ids in conn.subscriptions) + assert not service._state.dirty + runtime._on_entities( + EntityUpdate(changed={PRICE_ID: EntityState(PRICE_ID, "0.3", {})}, full=False) + ) + assert service._state.dirty + service._state.dirty = False + runtime._on_entities( + EntityUpdate(changed={"sensor.other": EntityState("sensor.other", "1", {})}) + ) + assert not service._state.dirty + + +async def test_reconnecting_clears_the_back_off(runtime: Runtime) -> None: + service = await fetched(runtime) + service._state.failures = 3 + runtime._on_state(ConnectionState.CONNECTED) + assert service._state.failures == 0 + + +async def test_putting_a_fixed_tariff_rebuilds_the_service_and_serves_static_prices( + runtime: Runtime, +) -> None: + old = service_of(runtime) + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff(kind="fixed", fixed_price=0.33), + export=ExportTariff(kind="none"), + ), + ) + new = service_of(runtime) + assert new is not old + await until(lambda: new.report(24).freshness.fetched_at is not None) + report = new.report(24) + assert report.freshness.status == "static" + assert {s.import_price for s in report.slots} == {0.33} + assert {s.export_price for s in report.slots} == {0.0} + assert (await runtime.prices(24)).source.import_source_id == "fixed" + + +async def test_putting_a_price_entity_only_tariff_uses_the_current_slot(runtime: Runtime) -> None: + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff(kind="dynamic", price_entity=EntityRef(entity_id=PRICE_ID)), + export=ExportTariff(kind="fixed", fixed_price=0.08), + ), + ) + service = service_of(runtime) + await until(lambda: service.report(24).freshness.fetched_at is not None) + assert service.report(24).source.import_source_id == "entity" + + +async def test_an_unusable_template_leaves_the_service_off_and_the_api_says_so( + runtime: Runtime, +) -> None: + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff(kind="dynamic", template_id="no.such_template"), + export=ExportTariff(kind="none"), + ), + ) + assert runtime.tariff is None + async with client_for(create_app(runtime)) as client: + r = await client.get("/api/v1/prices") + assert r.status_code == 404 + + +async def test_a_tiered_export_without_the_plant_size_leaves_the_service_off( + runtime: Runtime, +) -> None: + from suncore.core.config import ExportTier # noqa: PLC0415 + + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff(kind="fixed", fixed_price=0.3), + export=ExportTariff(kind="tiered", tiers=(ExportTier(price=0.08),)), + ), + ) + assert runtime.tariff is None # the demo site has no kWp: no rate is guessed + + +async def test_stop_cancels_the_price_loop(tmp_path: Path) -> None: + runtime = await start_runtime(tmp_path, "summer_day") + task = runtime._tariff_task + assert task is not None + await runtime.stop() + assert task.done() + assert runtime._tariff_task is None + + +async def test_the_system_check_warns_about_spot_prices_without_a_formula(runtime: Runtime) -> None: + keys = [i.reason.key for i in await runtime.system_check(None)] + assert "wizard.check.tariff_spot_without_formula" not in keys # Tibber is all-in + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff( + kind="dynamic", template_id="tibber.price", price_includes="spot_only" + ), + export=ExportTariff(kind="none"), + ), + ) + items = await runtime.system_check(None) + (warning,) = [i for i in items if i.reason.key == "wizard.check.tariff_spot_without_formula"] + assert warning.severity == "warn" diff --git a/tests/core/test_config_phase4.py b/tests/core/test_config_phase4.py index ba72101..66370db 100644 --- a/tests/core/test_config_phase4.py +++ b/tests/core/test_config_phase4.py @@ -207,3 +207,87 @@ def test_device_planner_value_is_optional() -> None: ) with pytest.raises(ValidationError): DeviceConfig.model_validate(doc | {"planner_value_per_kwh": -0.1}) + + +# --- tariff source settings (WP4, additive) ---------------------------------------------- + + +def test_dynamic_import_takes_source_settings_and_lists_their_entities() -> None: + from suncore.core.site import EntityRef # noqa: PLC0415 + + body = { + "import": { + "kind": "dynamic", + "template_id": "octopus_energy.rates", + "price_entity": {"entity_id": "sensor.rate"}, + "role_entities": { + "current_day_rates": {"entity_id": "event.today"}, + "next_day_rates": {"entity_id": "event.tomorrow"}, + }, + "action_params": {"config_entry": "01H", "areas": ["SE3", "SE4"]}, + "series_key": "SE3", + "price_includes": "all_in", + }, + "export": {"kind": "none"}, + } + tariff = TariffConfig.model_validate(body) + assert [r.entity_id for r in tariff.entity_refs()] == [ + "sensor.rate", + "event.today", + "event.tomorrow", + ] + assert tariff.import_.action_params["areas"] == ["SE3", "SE4"] + assert EntityRef(entity_id="sensor.rate") in tariff.entity_refs() + again = TariffConfig.model_validate(tariff.model_dump(mode="json", by_alias=True)) + assert again == tariff + + +def test_older_tariff_documents_load_without_the_new_fields() -> None: + tariff = TariffConfig.model_validate( + {"import": {"kind": "dynamic", "template_id": "tibber.price"}, "export": {"kind": "none"}} + ) + assert tariff.import_.role_entities == {} + assert tariff.import_.action_params == {} + assert tariff.import_.series_key is None + assert tariff.import_.price_includes is None + + +@pytest.mark.parametrize( + "extra", + [ + {"role_entities": {"x": {"entity_id": "sensor.x"}}}, + {"action_params": {"a": "b"}}, + {"series_key": "SE3"}, + {"price_includes": "all_in"}, + ], +) +def test_source_settings_need_a_dynamic_tariff(extra: dict[str, Any]) -> None: + with pytest.raises(ValidationError) as err: + TariffConfig.model_validate( + {"import": {"kind": "fixed", "fixed_price": 0.3, **extra}, "export": {"kind": "none"}} + ) + assert "suncore.import_source_dynamic_only" in str(err.value) + + +def test_the_price_role_is_the_price_entity() -> None: + with pytest.raises(ValidationError) as err: + TariffConfig.model_validate( + { + "import": { + "kind": "dynamic", + "template_id": "tibber.price", + "role_entities": {"price": {"entity_id": "sensor.x"}}, + }, + "export": {"kind": "none"}, + } + ) + assert "suncore.import_role_price" in str(err.value) + + +def test_action_params_reject_empty_and_oversized_values() -> None: + base = {"kind": "dynamic", "template_id": "nordpool.price"} + for params in ({"": "x"}, {"a": ""}, {"a": "x" * 201}, {"a": []}, {"a": [""]}, {"a": 5}): + with pytest.raises(ValidationError): + TariffConfig.model_validate( + {"import": {**base, "action_params": params}, "export": {"kind": "none"}} + ) diff --git a/tests/core/test_series.py b/tests/core/test_series.py index f7715cb..e6190e4 100644 --- a/tests/core/test_series.py +++ b/tests/core/test_series.py @@ -228,13 +228,14 @@ def test_segments_from_points_split_on_resolution_change() -> None: points = [(T0 + MIN15 * i, float(i)) for i in range(4)] + [ (T0 + HOUR, 10.0), (T0 + 2 * HOUR, 20.0), + (T0 + 3 * HOUR, 30.0), ] segments = segments_from_points( points, SeriesUnit.PRICE, expected_step=MIN15, other_steps={HOUR} ) - assert [(s.step, len(s)) for s in segments] == [(MIN15, 4), (HOUR, 2)] + assert [(s.step, len(s)) for s in segments] == [(MIN15, 4), (HOUR, 3)] assert segments[0].values == (0.0, 1.0, 2.0, 3.0) - assert segments[-1].end == T0 + 3 * HOUR + assert segments[-1].end == T0 + 4 * HOUR single = segments_from_points([(T0, 1.0)], SeriesUnit.W, expected_step=MIN15) assert single[0].end == T0 + MIN15 assert segments_from_points([], SeriesUnit.W, expected_step=MIN15) == () @@ -242,6 +243,24 @@ def test_segments_from_points_split_on_resolution_change() -> None: segments_from_points([(T0, 1.0), (T0, 2.0)], SeriesUnit.W, expected_step=MIN15) +def test_a_hole_at_the_end_of_the_list_is_a_gap_not_a_resolution_change() -> None: + """Review m4: the last distance has no following distance to confirm an hourly rhythm.""" + points = [(T0 + MIN15 * i, float(i)) for i in range(3)] + [(T0 + 2 * MIN15 + HOUR, 9.0)] + (segment,) = segments_from_points( + points, SeriesUnit.PRICE, expected_step=MIN15, other_steps={HOUR} + ) + assert segment.step == MIN15 + assert segment.values == (0.0, 1.0, 2.0, None, None, None, 9.0) + # two further hourly points confirm the rhythm: now it is a change + more = [*points, (T0 + 2 * MIN15 + 2 * HOUR, 10.0)] + assert [ + s.step + for s in segments_from_points( + more, SeriesUnit.PRICE, expected_step=MIN15, other_steps={HOUR} + ) + ] == [MIN15, HOUR] + + def test_segments_from_points_gap_is_none_not_filled() -> None: """Reviewer example 1: 15-minute prices 10:00, 10:15, 10:45 -> 10:30 is missing.""" t10 = T0 + 10 * HOUR diff --git a/tests/core/test_tariff.py b/tests/core/test_tariff.py index bbd6200..29e5d15 100644 --- a/tests/core/test_tariff.py +++ b/tests/core/test_tariff.py @@ -105,12 +105,12 @@ def test_dst_night_is_judged_in_local_time() -> None: def test_price_formula() -> None: f = PriceFormula(grid_fee=0.08, levies=0.03, margin=0.02, vat_pct=19) - assert f.apply(0.10, None, BERLIN) == pytest.approx((0.10 + 0.13) * 1.19) - assert f.apply(-0.20, None, BERLIN) == pytest.approx( + assert f.end_price(0.10, None, BERLIN) == pytest.approx((0.10 + 0.13) * 1.19) + assert f.end_price(-0.20, None, BERLIN) == pytest.approx( (-0.20 + 0.13) * 1.19 ) # negative end price - assert PriceFormula().apply(0.1, None, BERLIN) == pytest.approx(0.1) - assert PriceFormula(spot_multiplier=1.1).apply(0.1, None, BERLIN) == pytest.approx(0.11) + assert PriceFormula().end_price(0.1, None, BERLIN) == pytest.approx(0.1) + assert PriceFormula(spot_multiplier=1.1).end_price(0.1, None, BERLIN) == pytest.approx(0.11) def test_price_formula_time_variable_grid_fee() -> None: @@ -118,10 +118,10 @@ def test_price_formula_time_variable_grid_fee() -> None: high = GridFeeWindow(window=TouWindow(start="17:00", end="20:00"), fee=0.15) f = PriceFormula(grid_fee=0.08, grid_fee_windows=(low, high)) assert f.grid_fee_at(None, BERLIN) == 0.08 - assert f.apply(0.1, at(FRI, 3), BERLIN) == pytest.approx(0.12) - assert f.apply(0.1, at(FRI, 18), BERLIN) == pytest.approx(0.25) - assert f.apply(0.1, at(FRI, 12), BERLIN) == pytest.approx(0.18) - assert f.apply(0.1, datetime(2026, 10, 16, 1, tzinfo=UTC), BERLIN) == pytest.approx(0.12) + assert f.end_price(0.1, at(FRI, 3), BERLIN) == pytest.approx(0.12) + assert f.end_price(0.1, at(FRI, 18), BERLIN) == pytest.approx(0.25) + assert f.end_price(0.1, at(FRI, 12), BERLIN) == pytest.approx(0.18) + assert f.end_price(0.1, datetime(2026, 10, 16, 1, tzinfo=UTC), BERLIN) == pytest.approx(0.12) with pytest.raises(ValidationError): PriceFormula(spot_multiplier=0) with pytest.raises(ValidationError): @@ -222,3 +222,8 @@ def test_utc_instant_is_judged_in_the_given_zone_not_its_own() -> None: utc_23 = datetime(2026, 10, 16, 21, 30, tzinfo=UTC) # 23:30 in Berlin assert NIGHT_WINDOW.contains(utc_23, BERLIN) assert not NIGHT_WINDOW.contains(utc_23, UTC) + + +def test_apply_is_a_deprecated_alias_of_end_price() -> None: + f = PriceFormula(grid_fee=0.1, vat_pct=19) + assert f.apply(0.2, None, BERLIN) == f.end_price(0.2, None, BERLIN) diff --git a/tests/core/test_wizard.py b/tests/core/test_wizard.py index bc74deb..528d943 100644 --- a/tests/core/test_wizard.py +++ b/tests/core/test_wizard.py @@ -7,7 +7,7 @@ import pytest -from suncore.core.config import DevicesConfig +from suncore.core.config import DevicesConfig, TariffConfig from suncore.core.devices import DeviceConfig from suncore.core.signals import Quality, Sample from suncore.core.site import ( @@ -383,3 +383,32 @@ def test_no_duplicate_for_different_names_one_registry_device_or_unknown_registr registry.get, ) assert not any(i.reason.key == "wizard.check.duplicate_unit" for i in plugs) + + +# --- tariff check (review m1) --------------------------------------------------------- + + +def _tariff(**imp: object) -> TariffConfig: + return TariffConfig.model_validate( + {"import": {"kind": "dynamic", "template_id": "x.y", **imp}, "export": {"kind": "none"}} + ) + + +def test_spot_only_prices_without_a_formula_are_a_warning() -> None: + from suncore.core.wizard import check_tariff # noqa: PLC0415 + + (item,) = check_tariff(_tariff(), "spot_only") + assert item.severity == "warn" + assert item.reason.key == "wizard.check.tariff_spot_without_formula" + assert item.subject == "tariff" + assert check_tariff(_tariff(formula={"grid_fee": 0.1}), "spot_only") == [] + assert check_tariff(_tariff(), "all_in") == [] + assert check_tariff(_tariff(), None) == [] # unknown source: the user decides + # the user's statement beats the template + assert check_tariff(_tariff(price_includes="all_in"), "spot_only") == [] + assert len(check_tariff(_tariff(price_includes="spot_only"), "all_in")) == 1 + assert check_tariff(None, "spot_only") == [] + fixed = TariffConfig.model_validate( + {"import": {"kind": "fixed", "fixed_price": 0.3}, "export": {"kind": "none"}} + ) + assert check_tariff(fixed, "spot_only") == [] diff --git a/tests/fixtures/tariff/entsoe_avg_price.yaml b/tests/fixtures/tariff/entsoe_avg_price.yaml new file mode 100644 index 0000000..36a237a --- /dev/null +++ b/tests/fixtures/tariff/entsoe_avg_price.yaml @@ -0,0 +1,19 @@ +# Attributes of the ENTSO-E `avg_price` sensor: +# docs/research/integrations.md "ENTSO-E" (lines 277-305, Phase 4 verification 2026-10-16); +# JaccoR/hass-entso-e@v0.7.5 sensor.py:269-279 (attributes prices_today, prices_tomorrow, +# prices) and coordinator.py:250-256 (entry `{time, price}`, `time` = str() of a +# timezone-aware local datetime: a SPACE instead of `T`). Synthetic values. +entities: + - entity_id: sensor.entsoe_average_electricity_price + state: "0.0834" + attributes: + unit_of_measurement: EUR/kWh + prices_today: + - {time: "2026-10-16 00:00:00+02:00", price: 0.0712} + - {time: "2026-10-16 01:00:00+02:00", price: 0.0690} + - {time: "2026-10-16 02:00:00+02:00", price: 0.0668} + prices_tomorrow: [] + prices: + - {time: "2026-10-16 00:00:00+02:00", price: 0.0712} + - {time: "2026-10-16 01:00:00+02:00", price: 0.0690} + - {time: "2026-10-16 02:00:00+02:00", price: 0.0668} diff --git a/tests/fixtures/tariff/epex_spot_total_price.yaml b/tests/fixtures/tariff/epex_spot_total_price.yaml new file mode 100644 index 0000000..59ee2c7 --- /dev/null +++ b/tests/fixtures/tariff/epex_spot_total_price.yaml @@ -0,0 +1,15 @@ +# Attributes of the EPEX Spot "Total Price" sensor: +# docs/research/integrations.md "EPEX Spot" (lines 307-332, Phase 4 verification 2026-10-16); +# mampfes/ha_epex_spot@4.1.0 const.py:6-8,14 and sensor.py:69-82 (attribute `data`, entries +# `{start_time, end_time, price_per_kwh}`, dt_util.as_local(...).isoformat()); the unit is the +# literal `€/kWh` (const.py:57). Synthetic values. +entities: + - entity_id: sensor.epex_spot_total_price + state: "0.2631" + attributes: + unit_of_measurement: "€/kWh" + data: + - {start_time: "2026-10-16T00:00:00+02:00", end_time: "2026-10-16T01:00:00+02:00", price_per_kwh: 0.2631} + - {start_time: "2026-10-16T01:00:00+02:00", end_time: "2026-10-16T02:00:00+02:00", price_per_kwh: 0.2587} + - {start_time: "2026-10-16T02:00:00+02:00", end_time: "2026-10-16T02:15:00+02:00", price_per_kwh: 0.2561} + - {start_time: "2026-10-16T02:15:00+02:00", end_time: "2026-10-16T02:30:00+02:00", price_per_kwh: 0.2549} diff --git a/tests/fixtures/tariff/generic_price_list.yaml b/tests/fixtures/tariff/generic_price_list.yaml new file mode 100644 index 0000000..35caeb4 --- /dev/null +++ b/tests/fixtures/tariff/generic_price_list.yaml @@ -0,0 +1,11 @@ +# SunCore's own convention for a template sensor (templates/tariff/generic.price_list.yaml): +# attribute `prices` = list of `{start, price}`. Not the shape of an existing integration. +entities: + - entity_id: sensor.my_price_list + state: "0.31" + attributes: + unit_of_measurement: EUR/kWh + prices: + - {start: "2026-10-16T00:00:00+02:00", price: 0.31} + - {start: "2026-10-16T00:15:00+02:00", price: 0.30} + - {start: "2026-10-16T00:30:00+02:00", price: 0.29} diff --git a/tests/fixtures/tariff/nordpool_get_prices_for_date.yaml b/tests/fixtures/tariff/nordpool_get_prices_for_date.yaml new file mode 100644 index 0000000..81fd262 --- /dev/null +++ b/tests/fixtures/tariff/nordpool_get_prices_for_date.yaml @@ -0,0 +1,12 @@ +# Shape of the response of `nordpool.get_prices_for_date`: +# docs/research/integrations.md "Nord Pool (Core)" (lines 235-275, Phase 4 verification +# 2026-10-16); home-assistant/core@5cfe9aad components/nordpool/services.py:140-150 and +# pynordpool 0.4.0. `{AREA: [{start, end, price}]}`, `start`/`end` are datetime.isoformat() of +# UTC datetimes (`+00:00`), `price` is the raw day-ahead value in currency per MWh. +# Synthetic values, not a recording. Local date 2026-10-16 in Europe/Berlin starts at +# 2026-10-15T22:00:00+00:00. +response: + SE3: + - {start: "2026-10-15T22:00:00+00:00", end: "2026-10-15T23:00:00+00:00", price: 45.5} + - {start: "2026-10-15T23:00:00+00:00", end: "2026-10-16T00:00:00+00:00", price: 41.25} + - {start: "2026-10-16T00:00:00+00:00", end: "2026-10-16T01:00:00+00:00", price: -3.5} diff --git a/tests/fixtures/tariff/octopus_rates.yaml b/tests/fixtures/tariff/octopus_rates.yaml new file mode 100644 index 0000000..279fbaf --- /dev/null +++ b/tests/fixtures/tariff/octopus_rates.yaml @@ -0,0 +1,25 @@ +# Attributes of the Octopus Energy current-day and next-day rate event entities: +# docs/research/integrations.md "Octopus Energy" (lines 334-371, Phase 4 verification +# 2026-10-16); BottlecapDave/HomeAssistant-OctopusEnergy@v19.2.1 utils/__init__.py:149-170 +# (private_rates_to_public_rates: `start`, `end`, `value_inc_vat`, optional `is_capped`, +# `is_intelligent_adjusted`) and core event/entity.py:145-152 (last event data become +# attributes next to `event_type`). Rates in GBP/kWh including VAT, 30-minute slots, local +# datetimes. Synthetic values. +entities: + - entity_id: event.octopus_energy_electricity_1234_5678_current_day_rates + state: "2026-10-16T00:05:00.000+00:00" + attributes: + event_type: octopus_energy_electricity_current_day_rates + min_rate: 0.1245 + max_rate: 0.3421 + rates: + - {start: "2026-10-16T00:00:00+01:00", end: "2026-10-16T00:30:00+01:00", value_inc_vat: 0.1245} + - {start: "2026-10-16T00:30:00+01:00", end: "2026-10-16T01:00:00+01:00", value_inc_vat: 0.1302, is_capped: false} + - {start: "2026-10-16T01:00:00+01:00", end: "2026-10-16T01:30:00+01:00", value_inc_vat: 0.1519} + - entity_id: event.octopus_energy_electricity_1234_5678_next_day_rates + state: "2026-10-16T16:05:00.000+00:00" + attributes: + event_type: octopus_energy_electricity_next_day_rates + rates: + - {start: "2026-10-17T00:00:00+01:00", end: "2026-10-17T00:30:00+01:00", value_inc_vat: 0.1010} + - {start: "2026-10-17T00:30:00+01:00", end: "2026-10-17T01:00:00+01:00", value_inc_vat: 0.0955} diff --git a/tests/fixtures/tariff/tibber_get_prices.yaml b/tests/fixtures/tariff/tibber_get_prices.yaml new file mode 100644 index 0000000..a5acb13 --- /dev/null +++ b/tests/fixtures/tariff/tibber_get_prices.yaml @@ -0,0 +1,15 @@ +# Shape of the response of `tibber.get_prices`: +# docs/research/integrations.md "Tibber (Core)" (lines 212-233, Phase 4 verification +# 2026-10-16) and docs/research/device-integrations.md "Action tibber.get_prices" +# (lines 286-317); home-assistant/core@5cfe9aad components/tibber/services.py. +# `start_time` is the string Tibber delivers (ISO 8601 with UTC offset, slot start); `price` +# is the total (energy plus tax) per kWh. Synthetic values, not a recording. +response: + prices: + Home: + - {start_time: "2026-10-16T00:00:00.000+02:00", price: 0.2812} + - {start_time: "2026-10-16T00:15:00.000+02:00", price: 0.2790} + - {start_time: "2026-10-16T00:30:00.000+02:00", price: 0.2755} + - {start_time: "2026-10-16T00:45:00.000+02:00", price: 0.2701} + - {start_time: "2026-10-16T01:00:00.000+02:00", price: 0.2688} + - {start_time: "2026-10-16T01:15:00.000+02:00", price: 0.2650} diff --git a/tests/ha/test_websocket_registry.py b/tests/ha/test_websocket_registry.py index b812b26..2dbdc78 100644 --- a/tests/ha/test_websocket_registry.py +++ b/tests/ha/test_websocket_registry.py @@ -214,7 +214,12 @@ def test_allowlist_is_exactly_the_verified_read_only_set() -> None: """Adding an action needs a PR that verifies it against the integration source.""" assert ( frozenset( - {"tibber.get_prices", "solcast_solar.query_forecast_data", "weather.get_forecasts"} + { + "tibber.get_prices", + "nordpool.get_prices_for_date", + "solcast_solar.query_forecast_data", + "weather.get_forecasts", + } ) == READ_ONLY_ACTIONS ) diff --git a/tests/safety/test_boundary.py b/tests/safety/test_boundary.py index 28daa62..bd932cd 100644 --- a/tests/safety/test_boundary.py +++ b/tests/safety/test_boundary.py @@ -22,7 +22,9 @@ sibling package; ``suncore.safety`` imports only ``suncore.core`` and itself; ``suncore.templates`` imports only ``suncore.core`` and itself (plus yaml/pydantic, ADR-0012); ``suncore.controller`` imports only ``suncore.core`` - and itself (Phase 3 WP7: drivers, power models and the gate are injected). + and itself (Phase 3 WP7: drivers, power models and the gate are injected); + ``suncore.tariff`` imports only ``suncore.core``, ``suncore.templates`` and itself (Phase 4 + WP4: Home Assistant reaches it through the injected action caller and entity reader). 5. ``suncore.api`` imports none of ``suncore.safety``, ``suncore.ha``, ``suncore.devices`` (it talks to the ``Services`` protocol only). 6. ``suncore.safety`` imports neither ``suncore.core.config`` nor ``suncore.storage`` and @@ -57,6 +59,7 @@ CORE = "suncore.core" TEMPLATES = "suncore.templates" CONTROLLER = "suncore.controller" +TARIFF = "suncore.tariff" ACTUATOR_MODULE = "suncore.safety.actuator" GATE_MODULE = "suncore.safety.gate" DRIVERS = "suncore.devices.drivers" @@ -275,7 +278,7 @@ def test_api_does_not_import_write_side_packages(path: Path) -> None: @pytest.mark.parametrize("path", SOURCES, ids=lambda p: str(p.relative_to(ROOT))) def test_dependency_rule(path: Path) -> None: - """Rule 4: core imports no sibling; safety, templates, controller only core and itself.""" + """Rule 4: core imports no sibling; safety, templates, controller, tariff only what they may.""" module = module_name(path) if in_package(module, CORE): allowed = (CORE,) @@ -285,6 +288,8 @@ def test_dependency_rule(path: Path) -> None: allowed = (CORE, TEMPLATES) elif in_package(module, CONTROLLER): allowed = (CORE, CONTROLLER) + elif in_package(module, TARIFF): + allowed = (CORE, TEMPLATES, TARIFF) else: return offenders = fmt( @@ -367,7 +372,12 @@ def test_read_only_action_allowlist_is_fixed() -> None: assert ( frozenset( - {"tibber.get_prices", "solcast_solar.query_forecast_data", "weather.get_forecasts"} + { + "tibber.get_prices", + "nordpool.get_prices_for_date", + "solcast_solar.query_forecast_data", + "weather.get_forecasts", + } ) == READ_ONLY_ACTIONS ) diff --git a/tests/scenarios/tariff/entsoe.price.yaml b/tests/scenarios/tariff/entsoe.price.yaml new file mode 100644 index 0000000..7bce5f5 --- /dev/null +++ b/tests/scenarios/tariff/entsoe.price.yaml @@ -0,0 +1,19 @@ +template: entsoe.price +sim_scenario: summer_day +fixture: entsoe_avg_price +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 +extra_entities: + - {entity_id: sensor.entsoe_average_electricity_price, platform: entsoe, unit: EUR/kWh} + - {entity_id: sensor.entsoe_current_electricity_price, platform: entsoe, unit: EUR/kWh, state: "0.07"} +roles: + price: + tied: [sensor.entsoe_average_electricity_price, sensor.entsoe_current_electricity_price] + pick: sensor.entsoe_average_electricity_price + unit: EUR/kWh +expect: + segments: [{step_min: 60, points: 3}] + first_price: 0.0712 + includes: spot_only diff --git a/tests/scenarios/tariff/entsoe.price_mwh.yaml b/tests/scenarios/tariff/entsoe.price_mwh.yaml new file mode 100644 index 0000000..353fe75 --- /dev/null +++ b/tests/scenarios/tariff/entsoe.price_mwh.yaml @@ -0,0 +1,11 @@ +# Same sensor as `entsoe.price` set to the MWh scale: the fixture has no MWh variant, so only +# the role resolution is checked here; the conversion and the unit guard are unit-tested. +template: entsoe.price_mwh +sim_scenario: summer_day +extra_entities: + - {entity_id: sensor.entsoe_average_electricity_price, platform: entsoe, unit: EUR/MWh, state: "71.2"} +roles: + price: + entity: sensor.entsoe_average_electricity_price + unit: EUR/MWh + criteria: [domain, platforms, unit_pattern] diff --git a/tests/scenarios/tariff/epex_spot.market_price.yaml b/tests/scenarios/tariff/epex_spot.market_price.yaml new file mode 100644 index 0000000..38f5613 --- /dev/null +++ b/tests/scenarios/tariff/epex_spot.market_price.yaml @@ -0,0 +1,21 @@ +template: epex_spot.market_price +sim_scenario: summer_day +fixture: epex_spot_total_price +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 +extra_entities: + - {entity_id: sensor.epex_spot_total_price, platform: epex_spot, unit: "€/kWh"} + - {entity_id: sensor.epex_spot_market_price, platform: epex_spot, unit: "€/kWh", state: "0.0712"} +roles: + price: + tied: [sensor.epex_spot_total_price, sensor.epex_spot_market_price] + pick: sensor.epex_spot_total_price + unit: "€/kWh" +# The fixture is the total-price sensor's attribute; the market-price template reads the same +# attribute name from the chosen entity. +expect: + segments: [{step_min: 60, points: 2}, {step_min: 15, points: 2}] + first_price: 0.2631 + includes: spot_only diff --git a/tests/scenarios/tariff/epex_spot.total_price.yaml b/tests/scenarios/tariff/epex_spot.total_price.yaml new file mode 100644 index 0000000..b949268 --- /dev/null +++ b/tests/scenarios/tariff/epex_spot.total_price.yaml @@ -0,0 +1,21 @@ +# The unit is the currency SYMBOL (research "EPEX Spot": const.py:57): `€/kWh` resolves to EUR +# through suncore.tariff.units.normalise_price_unit. +template: epex_spot.total_price +sim_scenario: summer_day +fixture: epex_spot_total_price +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 +extra_entities: + - {entity_id: sensor.epex_spot_total_price, platform: epex_spot, unit: "€/kWh"} + - {entity_id: sensor.epex_spot_market_price, platform: epex_spot, unit: "€/kWh", state: "0.0712"} +roles: + price: + tied: [sensor.epex_spot_total_price, sensor.epex_spot_market_price] + pick: sensor.epex_spot_total_price + unit: "€/kWh" +expect: + segments: [{step_min: 60, points: 2}, {step_min: 15, points: 2}] + first_price: 0.2631 + includes: all_in diff --git a/tests/scenarios/tariff/generic.price_list.yaml b/tests/scenarios/tariff/generic.price_list.yaml new file mode 100644 index 0000000..71d5aee --- /dev/null +++ b/tests/scenarios/tariff/generic.price_list.yaml @@ -0,0 +1,19 @@ +template: generic.price_list +sim_scenario: summer_day +fixture: generic_price_list +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 +extra_entities: + - {entity_id: sensor.my_price_list, unit: EUR/kWh} +roles: + price: + # the demo's price sensor has the same unit: the user picks their template sensor + tied: [sensor.my_price_list, sensor.sim_electricity_price] + pick: sensor.my_price_list + unit: EUR/kWh +expect: + segments: [{step_min: 15, points: 3}] + first_price: 0.31 + includes: all_in diff --git a/tests/scenarios/tariff/nordpool.price.yaml b/tests/scenarios/tariff/nordpool.price.yaml new file mode 100644 index 0000000..f0eaa61 --- /dev/null +++ b/tests/scenarios/tariff/nordpool.price.yaml @@ -0,0 +1,22 @@ +# Nord Pool is not modelled by the simulator: the response is the documented shape +# (tests/fixtures/tariff/nordpool_get_prices_for_date.yaml, research "Nord Pool (Core)"). +template: nordpool.price +sim_scenario: summer_day +fixture: nordpool_get_prices_for_date +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 + action_params: {config_entry: 01HXEXAMPLEENTRYID, areas: [SE3]} +extra_entities: + - {entity_id: sensor.nord_pool_se3_current_price, platform: nordpool, unit: EUR/kWh, state: "0.0455"} + - {entity_id: sensor.nord_pool_se3_next_price, platform: nordpool, unit: EUR/kWh, state: "0.0412"} +roles: + price: + tied: [sensor.nord_pool_se3_current_price, sensor.nord_pool_se3_next_price] + pick: sensor.nord_pool_se3_current_price + unit: EUR/kWh +expect: + segments: [{step_min: 60, points: 3}] + first_price: 0.0455 + includes: spot_only diff --git a/tests/scenarios/tariff/octopus_energy.rates.yaml b/tests/scenarios/tariff/octopus_energy.rates.yaml new file mode 100644 index 0000000..197583b --- /dev/null +++ b/tests/scenarios/tariff/octopus_energy.rates.yaml @@ -0,0 +1,32 @@ +template: octopus_energy.rates +sim_scenario: summer_day +fixture: octopus_rates +user_input: + now: "2026-10-16T10:07:00+01:00" + window_start: "2026-10-16T00:00:00+01:00" + window_hours: 48 + timezone: Europe/London + currency: GBP +extra_entities: + - {entity_id: sensor.octopus_energy_electricity_1234_5678_current_rate, platform: octopus_energy, unit: GBP/kWh, state: "0.1302"} + - {entity_id: event.octopus_energy_electricity_1234_5678_current_day_rates, platform: octopus_energy} + - {entity_id: event.octopus_energy_electricity_1234_5678_next_day_rates, platform: octopus_energy} +roles: + price: + entity: sensor.octopus_energy_electricity_1234_5678_current_rate + unit: GBP/kWh + criteria: [domain, platforms, units] + current_day_rates: + tied: + - event.octopus_energy_electricity_1234_5678_current_day_rates + - event.octopus_energy_electricity_1234_5678_next_day_rates + pick: event.octopus_energy_electricity_1234_5678_current_day_rates + next_day_rates: + tied: + - event.octopus_energy_electricity_1234_5678_current_day_rates + - event.octopus_energy_electricity_1234_5678_next_day_rates + pick: event.octopus_energy_electricity_1234_5678_next_day_rates +expect: + segments: [{step_min: 30, points: 3}, {step_min: 30, points: 2}] + first_price: 0.1245 + includes: all_in diff --git a/tests/scenarios/tariff/tibber.price.yaml b/tests/scenarios/tariff/tibber.price.yaml index 7cd5cd4..05953a1 100644 --- a/tests/scenarios/tariff/tibber.price.yaml +++ b/tests/scenarios/tariff/tibber.price.yaml @@ -5,3 +5,10 @@ roles: entity: sensor.sim_electricity_price unit: EUR/kWh criteria: [domain, translation_key, platforms, unit_pattern] +# The simulator answers `tibber.get_prices` through the same template path as the real +# integration: 15-minute slots for today and (after 13:00 local) tomorrow. +expect: + segments: null + min_points: 96 + includes: all_in + matches_state: true diff --git a/tests/scenarios/test_conformance.py b/tests/scenarios/test_conformance.py index 6de9f5c..ca4f2db 100644 --- a/tests/scenarios/test_conformance.py +++ b/tests/scenarios/test_conformance.py @@ -14,7 +14,12 @@ * kind specific facts: a device can be instantiated from the template defaults and the resolved mapping, the tariff price unit equals the currency of the HA configuration, the forecast attribute carries the declared fields in the declared unit and resolution, the - region currency is consistent with the HA configuration. + region currency is consistent with the HA configuration; +* tariffs with a price curve run the real adapter (``suncore.tariff``) on the curve: from the + simulator (Tibber: the fake answers ``tibber.get_prices``) or from a documented-shape fixture + (``tests/fixtures/tariff``) for integrations the simulator does not model. A scenario may + list ``extra_entities`` - the registry metadata of fixture entities - and states what the + adapter must return under ``expect``. """ from __future__ import annotations @@ -23,7 +28,7 @@ import itertools import re from collections.abc import AsyncIterator, Mapping -from datetime import UTC, datetime +from datetime import UTC, datetime, timedelta from pathlib import Path from typing import Any from zoneinfo import ZoneInfo @@ -34,11 +39,14 @@ from suncore.core.devices import DeviceConfig from suncore.core.entities import EntityMeta +from suncore.core.series import TimeRange, floor_to_step from suncore.core.site import EntityRef from suncore.core.units import parse_unit from suncore.ha.connection import EntityState from suncore.sim.fake_ha import FakeHAConnection from suncore.sim.scenario import load_scenario +from suncore.tariff import EntityReading, SourceBinding, TemplatePriceSource +from suncore.tariff.units import normalise_price_unit from suncore.templates import ( DeviceTemplate, ForecastTemplate, @@ -70,13 +78,52 @@ class RoleExpectation(BaseModel): criteria: list[str] | None = None +class ExtraEntity(BaseModel): + """Registry metadata of an entity of a documented-shape fixture (not in the demo house).""" + + model_config = ConfigDict(extra="forbid") + + entity_id: str + platform: str | None = None + unit: str | None = None + translation_key: str | None = None + device_class: str | None = None + state: str = "0" + """State when the fixture has no entity of this id (action fixtures carry none).""" + + +class SegmentExpectation(BaseModel): + model_config = ConfigDict(extra="forbid") + + step_min: int + points: int + + +class SeriesExpectation(BaseModel): + """What the adapter returns for the curve.""" + + model_config = ConfigDict(extra="forbid") + + segments: list[SegmentExpectation] | None = None + min_points: int | None = None + first_price: float | None = None + """First known price, currency/kWh (after the MWh conversion).""" + includes: str | None = None + matches_state: bool = False + """The first price equals the state of the price role's entity (the sim's Tibber).""" + + class ScenarioFile(BaseModel): model_config = ConfigDict(extra="forbid") template: str sim_scenario: str + fixture: str | None = None + """Documented-shape fixture under ``tests/fixtures/tariff`` (entities and/or response).""" user_input: dict[str, Any] = Field(default_factory=dict) + extra_entities: list[ExtraEntity] = Field(default_factory=list) roles: dict[str, RoleExpectation] + expect: SeriesExpectation | None = None def _scenario_files() -> dict[str, Path]: @@ -159,18 +206,20 @@ def _check_tied( assert {m.entity_id for m in top} == set(expected.tied), name if required: # the user has to choose between the tied candidates assert expected.pick in expected.tied, f"{name}: a required role needs a pick" - resolved[name] = by_id[expected.pick] # type: ignore[index] - else: - assert expected.pick is None, f"{name}: pick is only for required roles" + if expected.pick is not None: # an optional role may be chosen too + assert expected.pick in expected.tied, f"{name}: the pick must be a tied candidate" + resolved[name] = by_id[expected.pick] @pytest.mark.parametrize("template_id", sorted(FILES)) async def test_template_conforms(template_id: str, fake: FakeHAConnection) -> None: scenario = _load(FILES[template_id]) template = CATALOG.templates[template_id] - metas = fake.entity_metas() + fixture = _fixture(scenario) + metas = [*fake.entity_metas(), *_extra_metas(scenario)] by_id = {m.entity_id: m for m in metas} states = {s.entity_id: s for s in await fake.get_states()} + states.update(_extra_states(scenario, fixture)) ranked = _resolve( template, metas, {r: e.pick for r, e in scenario.roles.items() if e.pick is not None} ) @@ -203,7 +252,9 @@ async def test_template_conforms(template_id: str, fake: FakeHAConnection) -> No if isinstance(template, DeviceTemplate): _check_device(template, scenario, resolved) elif isinstance(template, TariffTemplate): - await _check_tariff(template, fake, resolved, states) + await _check_tariff( + template, scenario, fake=fake, resolved=resolved, states=states, fixture=fixture + ) elif isinstance(template, ForecastTemplate): _check_forecast(template, resolved, states) elif isinstance(template, RegionTemplate): @@ -240,18 +291,145 @@ def _check_device( assert config.max_switches_per_hour is None # None = safety default, not unlimited +FIXTURES = ROOT / "tests" / "fixtures" / "tariff" + + +def _fixture(scenario: ScenarioFile) -> dict[str, Any]: + if scenario.fixture is None: + return {} + data = yaml.safe_load((FIXTURES / f"{scenario.fixture}.yaml").read_text(encoding="utf-8")) + assert isinstance(data, dict) + return data + + +def _extra_metas(scenario: ScenarioFile) -> list[EntityMeta]: + return [ + EntityMeta.of( + e.entity_id, + platform=e.platform, + unit=e.unit, + translation_key=e.translation_key, + device_class=e.device_class, + ) + for e in scenario.extra_entities + ] + + +def _extra_states(scenario: ScenarioFile, fixture: Mapping[str, Any]) -> dict[str, EntityState]: + from_fixture = {e["entity_id"]: e for e in fixture.get("entities", [])} + states: dict[str, EntityState] = {} + for extra in scenario.extra_entities: + recorded = from_fixture.get(extra.entity_id) + states[extra.entity_id] = EntityState( + extra.entity_id, + str(recorded["state"]) if recorded else extra.state, + dict(recorded["attributes"]) if recorded else {}, + ) + return states + + +def _currency_of(unit: str) -> str: + return normalise_price_unit(unit).split("/")[0] + + async def _check_tariff( template: TariffTemplate, + scenario: ScenarioFile, + *, fake: FakeHAConnection, resolved: Mapping[str, EntityMeta], states: Mapping[str, EntityState], + fixture: Mapping[str, Any], ) -> None: - currency = (await fake.get_config())["currency"] + currency = scenario.user_input.get("currency") or (await fake.get_config())["currency"] price = resolved["price"] - assert price.unit == template.price_unit.replace("{currency}", currency) - assert float(states[price.entity_id].state) > 0 # state = all-in price of the current slot - assert template.price_series is not None - assert template.price_series.fields.value_unit == "{currency}/kWh" + assert price.unit is not None + # the entity unit may carry a currency symbol (EPEX Spot `€/kWh`) and the other energy scale + # (Nord Pool sensors are per kWh, its action per MWh): the currency has to agree + assert ( + _currency_of(price.unit) + == template.price_unit.replace("{currency}", currency).split("/")[0] + ) + assert float(states[price.entity_id].state) is not None # the state is a number + if template.price_series is None: + return + series = template.price_series + assert series.fields.value_unit == template.price_unit # one unit for the whole template + if scenario.expect is not None: + await _check_series( + template, + scenario, + fake=fake, + resolved=resolved, + states=states, + fixture=fixture, + currency=currency, + ) + + +async def _check_series( + template: TariffTemplate, + scenario: ScenarioFile, + *, + fake: FakeHAConnection, + resolved: Mapping[str, EntityMeta], + states: Mapping[str, EntityState], + fixture: Mapping[str, Any], + currency: str, +) -> None: + """Run the real adapter on the scenario's curve and compare with the expectation.""" + expect = scenario.expect + assert expect is not None + user = scenario.user_input + now = datetime.fromisoformat(user["now"]) if "now" in user else fake.sim_time + assert now is not None + first = floor_to_step( + datetime.fromisoformat(user["window_start"]) if "window_start" in user else now + ) + window = TimeRange( + start=first, end=first + timedelta(hours=float(user.get("window_hours", 48))) + ) + readings = { + entity_id: EntityReading(state.state, state.attributes) + for entity_id, state in states.items() + } + + async def action( + domain: str, service: str, data: Mapping[str, Any], **_: float + ) -> Mapping[str, Any]: + if "response" in fixture: + return fixture["response"] # type: ignore[no-any-return] + return await fake.call_action_response(domain, service, data) + + source = TemplatePriceSource( + template, + SourceBinding( + tz=ZoneInfo(user.get("timezone", "Europe/Berlin")), + entities={role: meta.entity_id for role, meta in resolved.items()}, + action_params=user.get("action_params", {}), + series_key=user.get("series_key"), + currency=currency, + ), + action=action, # type: ignore[arg-type] + attributes=readings.get, + clock=lambda: now, + ) + data = await source.fetch_segments(window, now) + if expect.segments is not None: + got = [(int(s.step.total_seconds() // 60), len(s)) for s in data.segments] + assert got == [(e.step_min, e.points) for e in expect.segments] + if expect.min_points is not None: + assert sum(len(s) for s in data.segments) >= expect.min_points + values = [v for s in data.segments for v in s.import_price.values if v is not None] + assert values, "the adapter returned no price" + if expect.first_price is not None: + assert values[0] == pytest.approx(expect.first_price) + if expect.matches_state: + price = resolved["price"] + # the state is the total price of the running slot, rounded to 3 decimals + assert values[0] == pytest.approx(float(states[price.entity_id].state), abs=0.0006) + if expect.includes is not None: + assert {s.price_includes for s in data.segments} == {expect.includes} def _check_forecast( diff --git a/tests/sim/test_fake_prices.py b/tests/sim/test_fake_prices.py new file mode 100644 index 0000000..60e7d88 --- /dev/null +++ b/tests/sim/test_fake_prices.py @@ -0,0 +1,140 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The simulator's ``tibber.get_prices``: the documented response, the negative-price scenario.""" + +from __future__ import annotations + +import asyncio +import itertools +from collections.abc import AsyncIterator +from datetime import UTC, datetime, timedelta + +import pytest + +from suncore.sim.demo_devices import sim_price +from suncore.sim.fake_ha import FakeHAConnection +from suncore.sim.scenario import PriceParams, load_scenario, parse_scenario + +pytestmark = pytest.mark.simulator + +Q = timedelta(minutes=15) + + +async def started(name: str, hour: int) -> FakeHAConnection: + never = asyncio.Event() + + async def sleep(_: float) -> None: + await never.wait() + + conn = FakeHAConnection( + load_scenario(name), + clock=lambda: datetime(2026, 6, 21, tzinfo=UTC), + sleep=sleep, + start_offset_s=hour * 3600, + ) + await conn.connect() + return conn + + +@pytest.fixture +async def morning() -> AsyncIterator[FakeHAConnection]: + conn = await started("summer_day", 9) + yield conn + await conn.close() + + +@pytest.fixture +async def afternoon() -> AsyncIterator[FakeHAConnection]: + conn = await started("summer_day", 14) + yield conn + await conn.close() + + +def starts(response: dict[str, object]) -> list[datetime]: + slots = response["prices"]["Home"] # type: ignore[index] + return [datetime.fromisoformat(s["start_time"]) for s in slots] + + +async def test_default_window_is_local_today_in_15_minute_slots( + morning: FakeHAConnection, +) -> None: + out = await morning.call_action_response("tibber", "get_prices") + stamps = starts(out) + assert len(stamps) == 96 + assert stamps[0] == datetime(2026, 6, 21, 0, 0, tzinfo=stamps[0].tzinfo) + assert {b - a for a, b in itertools.pairwise(stamps)} == {Q} + assert stamps[0].utcoffset() == timedelta(hours=2) # the scenario's local offset + first = out["prices"]["Home"][0] + assert first == {"start_time": stamps[0].isoformat(), "price": sim_price(stamps[0])} + + +async def test_tomorrow_exists_only_after_the_publication_hour( + morning: FakeHAConnection, afternoon: FakeHAConnection +) -> None: + window = {"start": "2026-06-21T00:00:00+02:00", "end": "2026-06-23T00:00:00+02:00"} + early = starts(await morning.call_action_response("tibber", "get_prices", window)) + late = starts(await afternoon.call_action_response("tibber", "get_prices", window)) + assert len(early) == 96 # 09:00 local: tomorrow is not published yet + assert len(late) == 192 # 14:00 local: today and tomorrow + assert late[-1] == datetime(2026, 6, 22, 23, 45, tzinfo=late[-1].tzinfo) + + +async def test_start_and_end_filter_the_slots_like_the_integration( + afternoon: FakeHAConnection, +) -> None: + # The fake is rate limited like the real connection (4-B): one sub-key per call. + out = await afternoon.call_action_response( + "tibber", + "get_prices", + {"start": "2026-06-21T10:00:00+02:00", "end": "2026-06-21T11:00:00+02:00"}, + rate_key="a", + ) + assert [s.hour for s in starts(out)] == [10, 10, 10, 10] # start <= t < end + inverted = await afternoon.call_action_response( + "tibber", + "get_prices", + {"start": "2026-06-21T10:00:00+02:00", "end": "2026-06-21T09:00:00+02:00"}, + rate_key="b", + ) + assert len(starts(inverted)) == 96 # start >= end: end = start + 1 day, capped to what exists + naive = await afternoon.call_action_response( + "tibber", + "get_prices", + {"start": "2026-06-21 12:00:00", "end": "2026-06-21 12:30:00"}, + rate_key="c", + ) + assert len(starts(naive)) == 2 + + +async def test_the_negative_prices_scenario_dips_below_zero_at_noon() -> None: + conn = await started("negative_prices", 9) + try: + out = await conn.call_action_response("tibber", "get_prices") + finally: + await conn.close() + prices = { + datetime.fromisoformat(s["start_time"]).hour: s["price"] for s in out["prices"]["Home"] + } + assert prices[13] < 0 + assert min(prices.values()) == pytest.approx(-0.08, abs=0.005) + assert prices[3] > 0 + assert prices[19] > 0.3 + + +def test_the_default_profile_never_goes_negative() -> None: + day = datetime(2026, 6, 21, tzinfo=UTC) + assert min(sim_price(day + Q * i) for i in range(96)) > 0 + assert min(sim_price(day + Q * i, "negative_midday") for i in range(96)) < 0 + + +def test_the_price_profile_is_part_of_the_scenario_schema() -> None: + assert load_scenario("summer_day").prices == PriceParams() + assert load_scenario("negative_prices").prices.profile == "negative_midday" + base = "name: x\nstart: '2026-06-21T00:00:00+02:00'\nduration_s: 60\nstep_s: 60\n" + assert ( + parse_scenario(base + "prices: {profile: negative_midday}\n").prices.profile + == "negative_midday" + ) + with pytest.raises(ValueError, match="profile"): + parse_scenario(base + "prices: {profile: sideways}\n") + with pytest.raises(ValueError, match="tomorrow_after_hour"): + parse_scenario(base + "prices: {tomorrow_after_hour: 24}\n") diff --git a/tests/sim/test_scenario.py b/tests/sim/test_scenario.py index 8b8286c..1b40a7f 100644 --- a/tests/sim/test_scenario.py +++ b/tests/sim/test_scenario.py @@ -17,6 +17,7 @@ "ha_disconnect", "inverter_hang", "manual_override", + "negative_prices", "sensor_dropout", "summer_day", "water_heater_steps", @@ -139,7 +140,7 @@ def test_outdoor_temperature_is_a_daily_cosine() -> None: @pytest.mark.parametrize( "name", - [n for n in BUNDLED if n not in ("summer_day", "winter_fog")], + [n for n in BUNDLED if n not in ("summer_day", "winter_fog", "negative_prices")], ) def test_closed_loop_scenarios_declare_devices(name: str) -> None: sc = load_scenario(name) diff --git a/tests/tariff/__init__.py b/tests/tariff/__init__.py new file mode 100644 index 0000000..9881313 --- /dev/null +++ b/tests/tariff/__init__.py @@ -0,0 +1 @@ +# SPDX-License-Identifier: Apache-2.0 diff --git a/tests/tariff/helpers.py b/tests/tariff/helpers.py new file mode 100644 index 0000000..eb0e0b3 --- /dev/null +++ b/tests/tariff/helpers.py @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Shared test doubles and builders for the tariff tests (no network, no wall clock).""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping +from datetime import datetime, timedelta +from pathlib import Path +from typing import Any +from zoneinfo import ZoneInfo + +import yaml + +from suncore.core.series import PriceSeries, TimeSeries +from suncore.tariff import EntityReader, EntityReading, SourceBinding, TemplatePriceSource +from suncore.templates import TariffTemplate, load_templates + +ROOT = Path(__file__).resolve().parents[2] +FIXTURES = ROOT / "tests" / "fixtures" / "tariff" +CATALOG = load_templates(ROOT / "templates") +BERLIN = ZoneInfo("Europe/Berlin") +LONDON = ZoneInfo("Europe/London") +NOW = datetime(2026, 10, 16, 10, 7, tzinfo=BERLIN) +"""A Friday morning, CEST.""" + + +def fixture(name: str) -> dict[str, Any]: + """A documented-shape fixture (``tests/fixtures/tariff/.yaml``).""" + data = yaml.safe_load((FIXTURES / f"{name}.yaml").read_text(encoding="utf-8")) + assert isinstance(data, dict) + return data + + +def template(template_id: str) -> TariffTemplate: + found = CATALOG.get(template_id) + assert isinstance(found, TariffTemplate), template_id + return found + + +class StubActions: + """An ``ActionCaller`` answering from a function, recording every call.""" + + def __init__(self, respond: Callable[[Mapping[str, Any]], Mapping[str, Any]]) -> None: + self._respond = respond + self.calls: list[tuple[str, str, dict[str, Any], float, float]] = [] + self.error: Exception | None = None + + async def __call__( + self, + domain: str, + service: str, + data: Mapping[str, Any], + *, + min_interval_s: float, + max_wait_s: float, + ) -> Mapping[str, Any]: + self.calls.append((domain, service, dict(data), min_interval_s, max_wait_s)) + if self.error is not None: + raise self.error + return self._respond(data) + + +def reader_of(entities: Mapping[str, EntityReading | None]) -> EntityReader: + def read(entity_id: str) -> EntityReading | None: + return entities.get(entity_id) + + return read + + +def readings(name: str) -> dict[str, EntityReading]: + """Entity readings of a fixture file.""" + return { + e["entity_id"]: EntityReading(str(e["state"]), e["attributes"]) + for e in fixture(name)["entities"] + } + + +def attribute_source( + template_id: str, + entities: Mapping[str, str], + reading: Mapping[str, EntityReading | None], + *, + now: datetime = NOW, + **binding: Any, +) -> TemplatePriceSource: + tz = binding.pop("tz", BERLIN) + return TemplatePriceSource( + template(template_id), + SourceBinding(tz=tz, entities=entities, **binding), + attributes=reader_of(reading), + clock=lambda: now, + ) + + +def action_source( + template_id: str, + actions: StubActions, + *, + now: datetime = NOW, + **binding: Any, +) -> TemplatePriceSource: + tz = binding.pop("tz", BERLIN) + return TemplatePriceSource( + template(template_id), + SourceBinding(tz=tz, **binding), + action=actions, + clock=lambda: now, + ) + + +def quarter_hours( + start: datetime, count: int, first: float = 0.2, step: float = 0.001 +) -> list[tuple[datetime, float]]: + return [(start + timedelta(minutes=15 * i), round(first + step * i, 6)) for i in range(count)] + + +def prices( + start: datetime, + values: list[float | None], + *, + step: timedelta = timedelta(minutes=15), + includes: str = "all_in", + source_id: str = "t", +) -> PriceSeries: + series = TimeSeries(start=start, step=step, values=tuple(values), unit="currency/kWh") # type: ignore[arg-type] + return PriceSeries(source_id=source_id, price_includes=includes, import_price=series) # type: ignore[arg-type] diff --git a/tests/tariff/test_engine.py b/tests/tariff/test_engine.py new file mode 100644 index 0000000..347bd7e --- /dev/null +++ b/tests/tariff/test_engine.py @@ -0,0 +1,691 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The template-driven adapters, one per integration, from documented-shape fixtures.""" + +from __future__ import annotations + +from collections.abc import Mapping +from datetime import UTC, date, datetime, timedelta +from typing import Any + +import pytest + +from suncore.core.series import TimeRange, floor_to_step +from suncore.tariff import ( + CurrencyMismatchError, + CurrentPriceSource, + EntityReading, + MissingEntityError, + MissingParamError, + SourceBinding, + SourceUnavailableError, + TemplatePriceSource, + UnitMismatchError, +) +from suncore.tariff.engine import request_dates +from suncore.tariff.errors import AmbiguousSeriesError, MalformedPayloadError +from suncore.tariff.sources import finest_series +from tests.tariff.helpers import ( + BERLIN, + LONDON, + NOW, + StubActions, + action_source, + attribute_source, + fixture, + reader_of, + readings, + template, +) + +H = timedelta(hours=1) +Q = timedelta(minutes=15) +MIDNIGHT = datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN) + + +def window(hours: int = 48, start: datetime = NOW) -> TimeRange: + begin = floor_to_step(start) + return TimeRange(start=begin, end=begin + timedelta(hours=hours)) + + +def iso(moment: datetime) -> str: + return moment.isoformat() + + +# --- Tibber (action, 15 minutes, per home) ---------------------------------------------- + + +def tibber_response(start: datetime, slots: int, *, home: str = "Home") -> dict[str, Any]: + return { + "prices": { + home: [ + {"start_time": iso(start + Q * i), "price": round(0.30 + 0.001 * i, 4)} + for i in range(slots) + ] + } + } + + +async def test_tibber_fixture_is_parsed_on_the_native_15_minute_grid() -> None: + actions = StubActions(lambda _data: fixture("tibber_get_prices")["response"]) + source = action_source("tibber.price", actions) + data = await source.fetch_segments(window(2, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + (segment,) = data.segments + assert segment.source_id == "tibber.price" + assert segment.price_includes == "all_in" + assert segment.step == Q + assert segment.import_price.values[:3] == (0.2812, 0.279, 0.2755) + assert segment.start == datetime(2026, 10, 15, 22, 0, tzinfo=UTC) + assert data.known_end == datetime(2026, 10, 15, 22, 0, tzinfo=UTC) + 6 * Q + + +async def test_tibber_request_asks_for_the_local_days_of_the_window() -> None: + actions = StubActions(lambda _data: {"prices": {}}) + source = action_source("tibber.price", actions) + await source.fetch_segments(window(48), NOW) + ((domain, service, data, interval, wait),) = actions.calls + assert (domain, service) == ("tibber", "get_prices") + assert data == { + "start": "2026-10-16T00:00:00+02:00", + "end": "2026-10-19T00:00:00+02:00", # NOW + 48 h is 18 Oct 10:00: the day after is the 19th + } + assert interval == 30.0 + assert wait == 0.0 + + +async def test_tibber_empty_response_is_no_data_not_an_error() -> None: + actions = StubActions(lambda _data: {"prices": {}}) + data = await action_source("tibber.price", actions).fetch_segments(window(), NOW) + assert data.segments == () + assert data.known_end is None + + +async def test_tibber_two_homes_need_a_series_key() -> None: + payload = { + "prices": { + "Home": tibber_response(datetime(2026, 10, 16, 10, tzinfo=BERLIN), 4)["prices"]["Home"], + "Cabin": tibber_response(datetime(2026, 10, 16, 10, tzinfo=BERLIN), 4, home="x")[ + "prices" + ]["x"], + } + } + actions = StubActions(lambda _data: payload) + with pytest.raises(AmbiguousSeriesError): + await action_source("tibber.price", actions).fetch_segments(window(), NOW) + data = await action_source("tibber.price", actions, series_key="Cabin").fetch_segments( + window(), NOW + ) + assert len(data.segments[0].import_price) == 4 + + +async def test_tibber_gaps_and_unreadable_prices_are_none() -> None: + start = datetime(2026, 10, 16, 10, 0, tzinfo=BERLIN) + rows = tibber_response(start, 6)["prices"]["Home"] + del rows[2] # a missing slot + rows[4] = {"start_time": rows[4]["start_time"], "price": None} # an unreadable price + actions = StubActions(lambda _data: {"prices": {"Home": rows}}) + data = await action_source("tibber.price", actions).fetch_segments(window(), NOW) + (segment,) = data.segments + values = segment.import_price.values + assert len(values) == 6 + assert values[2] is None # the gap + assert values[3] is not None + assert values[4] is not None + assert values[5] is None # a null price is a gap too + assert data.report.unreadable_values == 1 + + +async def test_tibber_mixed_15_and_60_minutes_gives_two_segments_and_a_15_minute_series() -> None: + day = datetime(2026, 10, 16, 12, 0, tzinfo=BERLIN) + quarter = [ + {"start_time": iso(day + Q * i), "price": 0.30 + 0.01 * i} + for i in range(8) # 12:00-14:00 + ] + hourly = [ + {"start_time": iso(day + 2 * H + H * i), "price": 0.50 + 0.1 * i} for i in range(3) + ] # 14:00-17:00 + actions = StubActions(lambda _data: {"prices": {"Home": quarter + hourly}}) + source = action_source("tibber.price", actions) + data = await source.fetch_segments(window(), NOW) + first, second = data.segments + assert (first.step, len(first)) == (Q, 8) + assert (second.step, len(second)) == (H, 3) + merged = await source.fetch(window()) + assert merged.step == Q + assert len(merged) == 8 + 12 # hourly values held for four quarters each + assert merged.import_price.values[8:12] == (0.5, 0.5, 0.5, 0.5) + + +async def test_tibber_dst_end_day_has_25_hours_of_quarters() -> None: + start = datetime(2026, 10, 25, 0, 0, tzinfo=BERLIN).astimezone(UTC) # 22:00 UTC the day before + rows = [ + {"start_time": iso((start + Q * i).astimezone(BERLIN)), "price": 0.2 + 0.0001 * i} + for i in range(25 * 4) + ] + actions = StubActions(lambda _data: {"prices": {"Home": rows}}) + now = datetime(2026, 10, 25, 0, 30, tzinfo=BERLIN) + data = await action_source("tibber.price", actions, now=now).fetch_segments( + TimeRange(start=start, end=start + timedelta(hours=25)), now + ) + (segment,) = data.segments + assert len(segment.import_price) == 100 + assert segment.import_price.end - segment.start == timedelta(hours=25) + # the repeated local hour 02:00-03:00 exists twice, with different offsets, both kept + stamps = [iso((start + Q * i).astimezone(BERLIN)) for i in range(8, 16)] + assert stamps[0].endswith("+02:00") + assert stamps[-1].endswith("+01:00") + + +async def test_tibber_dst_start_day_has_23_hours() -> None: + start = datetime(2026, 3, 29, 0, 0, tzinfo=BERLIN).astimezone(UTC) + rows = [ + {"start_time": iso((start + Q * i).astimezone(BERLIN)), "price": 0.2} for i in range(23 * 4) + ] + now = datetime(2026, 3, 29, 0, 30, tzinfo=BERLIN) + actions = StubActions(lambda _data: {"prices": {"Home": rows}}) + data = await action_source("tibber.price", actions, now=now).fetch_segments( + TimeRange(start=start, end=start + timedelta(hours=23)), now + ) + assert data.segments[0].import_price.end - start == timedelta(hours=23) + + +async def test_tibber_malformed_payloads_are_rejected() -> None: + for payload in ( + {"prices": {"Home": "nope"}}, + {"prices": {"Home": [{"price": 1}]}}, + {"prices": []}, + ): + actions = StubActions(lambda _data, p=payload: p) + with pytest.raises(MalformedPayloadError): + await action_source("tibber.price", actions).fetch_segments(window(), NOW) + + +async def test_a_window_clips_the_series_to_whole_overlapping_slots() -> None: + actions = StubActions( + lambda _data: tibber_response(datetime(2026, 10, 16, 8, tzinfo=BERLIN), 40) + ) + narrow = TimeRange( + start=datetime(2026, 10, 16, 10, 0, tzinfo=BERLIN), + end=datetime(2026, 10, 16, 11, 0, tzinfo=BERLIN), + ) + data = await action_source("tibber.price", actions).fetch_segments(narrow, NOW) + (segment,) = data.segments + assert len(segment.import_price) == 4 + assert segment.start == narrow.start.astimezone(UTC) + + +# --- Nord Pool (action per date, UTC, per MWh, slot end) ------------------------------- + +NORDPOOL_PARAMS: Mapping[str, str | list[str]] = {"config_entry": "01HXENTRY", "areas": ["SE3"]} + + +def nordpool_by_date(day17: list[dict[str, Any]] | None = None) -> StubActions: + first = fixture("nordpool_get_prices_for_date")["response"] + + def respond(data: Mapping[str, Any]) -> Mapping[str, Any]: + return first if data["date"] == "2026-10-16" else {"SE3": day17 or []} + + return StubActions(respond) + + +async def test_nordpool_calls_once_per_local_date_and_never_beyond_tomorrow() -> None: + actions = nordpool_by_date() + source = action_source("nordpool.price", actions, action_params=NORDPOOL_PARAMS) + await source.fetch_segments(window(72), NOW) # a long window must not ask for the 18th/19th + assert [(c[2]["date"], c[4]) for c in actions.calls] == [ + ("2026-10-16", 0.0), + ("2026-10-17", 31.0), # the limiter's next slot is awaited for the second date + ] + assert all(c[2]["config_entry"] == "01HXENTRY" for c in actions.calls) + assert all(c[2]["areas"] == ["SE3"] for c in actions.calls) + assert "currency" not in actions.calls[0][2] # optional and not configured + + +async def test_nordpool_prices_are_divided_by_1000_and_the_slot_length_is_end_minus_start() -> None: + actions = nordpool_by_date() + source = action_source("nordpool.price", actions, action_params=NORDPOOL_PARAMS) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + (segment,) = data.segments + assert segment.price_includes == "spot_only" + assert segment.step == H + assert segment.start == datetime(2026, 10, 15, 22, tzinfo=UTC) + assert segment.import_price.values == pytest.approx((0.0455, 0.04125, -0.0035)) + + +async def test_nordpool_15_minute_day_after_the_transition_is_mixed_with_hourly() -> None: + t = datetime(2026, 10, 16, 22, 0, tzinfo=UTC) # local 17 Oct 00:00 + quarter = [ + {"start": iso(t + Q * i), "end": iso(t + Q * (i + 1)), "price": 100.0 + i} for i in range(8) + ] + actions = nordpool_by_date(quarter) + source = action_source("nordpool.price", actions, action_params=NORDPOOL_PARAMS) + data = await source.fetch_segments(window(48, MIDNIGHT), NOW) + steps = [s.step for s in data.segments] + assert steps == [H, Q] + assert data.segments[1].import_price.values[:2] == pytest.approx((0.1, 0.101)) + merged = await source.fetch(window(48, MIDNIGHT)) + assert merged.step == Q + + +async def test_nordpool_unpublished_tomorrow_returns_only_today() -> None: + source = action_source("nordpool.price", nordpool_by_date(), action_params=NORDPOOL_PARAMS) + data = await source.fetch_segments(window(48, MIDNIGHT), NOW) + assert data.known_end == datetime(2026, 10, 16, 1, 0, tzinfo=UTC) + + +async def test_nordpool_needs_the_config_entry_and_makes_no_call_without_it() -> None: + actions = nordpool_by_date() + source = action_source("nordpool.price", actions, action_params={"areas": ["SE3"]}) + with pytest.raises(MissingParamError) as err: + await source.fetch_segments(window(), NOW) + assert err.value.message_args == {"field": "config_entry"} + assert actions.calls == [] + + +async def test_nordpool_several_areas_need_a_series_key() -> None: + both = {"SE3": [], "SE4": []} + actions = StubActions(lambda _data: both) + source = action_source("nordpool.price", actions, action_params={"config_entry": "x"}) + with pytest.raises(AmbiguousSeriesError): + await source.fetch_segments(window(), NOW) + chosen = action_source( + "nordpool.price", actions, action_params={"config_entry": "x"}, series_key="SE4" + ) + assert (await chosen.fetch_segments(window(), NOW)).segments == () + + +async def test_nordpool_optional_fields_are_passed_when_configured() -> None: + actions = nordpool_by_date() + source = action_source( + "nordpool.price", + actions, + action_params={"config_entry": "x", "areas": "SE3", "currency": "EUR"}, + ) + await source.fetch_segments(window(2), NOW) + assert actions.calls[0][2] == { + "config_entry": "x", + "areas": "SE3", + "currency": "EUR", + "date": "2026-10-16", + } + + +def test_request_dates_follow_the_local_calendar_across_the_dst_change() -> None: + now = datetime(2026, 10, 24, 23, 30, tzinfo=BERLIN) + win = TimeRange(start=floor_to_step(now), end=floor_to_step(now) + timedelta(hours=30)) + assert request_dates(win, now, BERLIN, 48) == [ + date(2026, 10, 24), + date(2026, 10, 25), + date(2026, 10, 26), + ] + assert request_dates(win, now, BERLIN, 24) == [date(2026, 10, 24), date(2026, 10, 25)] + # a window that starts after the limit asks for nothing + late = TimeRange(start=now + timedelta(days=5), end=now + timedelta(days=6)) + assert request_dates(late, now, BERLIN, 24) == [] + + +# --- ENTSO-E (attribute, local str(datetime), spacing) --------------------------------- + +ENTSOE_ENTITY = "sensor.entsoe_average_electricity_price" + + +async def test_entsoe_fixture_hourly_spot_only() -> None: + source = attribute_source( + "entsoe.price", {"price": ENTSOE_ENTITY}, readings("entsoe_avg_price") + ) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + (segment,) = data.segments + assert segment.step == H + assert segment.price_includes == "spot_only" + assert segment.import_price.values == (0.0712, 0.069, 0.0668) + assert segment.start == datetime(2026, 10, 15, 22, tzinfo=UTC) + + +async def test_entsoe_user_statement_overrides_the_template_classification() -> None: + source = attribute_source( + "entsoe.price", + {"price": ENTSOE_ENTITY}, + readings("entsoe_avg_price"), + price_includes="all_in", + ) + assert source.price_includes == "all_in" + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + assert data.segments[0].price_includes == "all_in" + + +async def test_entsoe_fifteen_minute_period_is_inferred_from_the_spacing() -> None: + base = datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN) + rows = [{"time": str(base + Q * i), "price": 0.05 + 0.001 * i} for i in range(96)] + entity = EntityReading("0.05", {"unit_of_measurement": "EUR/kWh", "prices": rows}) + source = attribute_source("entsoe.price", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: entity}) + assert rows[0]["time"] == "2026-10-16 00:00:00+02:00" # the documented str(datetime) form + data = await source.fetch_segments(window(24, base), NOW) + assert data.segments[0].step == Q + assert len(data.segments[0].import_price) == 96 + + +async def test_entsoe_dst_end_day_with_str_datetime_offsets() -> None: + base = datetime(2026, 10, 25, 0, 0, tzinfo=BERLIN).astimezone(UTC) + rows = [ + {"time": str((base + H * i).astimezone(BERLIN)), "price": 0.05 + 0.001 * i} + for i in range(25) + ] + assert rows[2]["time"].endswith("+02:00") + assert rows[3]["time"] == "2026-10-25 02:00:00+01:00" + entity = EntityReading("0.05", {"prices": rows}) + now = datetime(2026, 10, 25, 0, 30, tzinfo=BERLIN) + source = attribute_source( + "entsoe.price", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: entity}, now=now + ) + data = await source.fetch_segments(window(25, base), now) + assert len(data.segments[0].import_price) == 25 + assert data.report.duplicates == 0 + + +async def test_entsoe_mwh_template_divides_by_1000_and_refuses_a_kwh_entity() -> None: + rows = [ + {"time": "2026-10-16 00:00:00+02:00", "price": 85.5}, + {"time": "2026-10-16 01:00:00+02:00", "price": 80.0}, + ] + mwh = EntityReading("85.5", {"unit_of_measurement": "EUR/MWh", "prices": rows}) + source = attribute_source("entsoe.price_mwh", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: mwh}) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + assert data.segments[0].import_price.values == pytest.approx((0.0855, 0.08)) + # the kWh template on an entity that says MWh would be a silent factor 1000: refused + wrong = attribute_source("entsoe.price", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: mwh}) + with pytest.raises(UnitMismatchError) as err: + await wrong.fetch_segments(window(24), NOW) + assert err.value.message_args["sensor_unit"] == "EUR/MWh" + + +async def test_entsoe_unavailable_entity_missing_attribute_and_empty_list() -> None: + entities = {"price": ENTSOE_ENTITY} + with pytest.raises(SourceUnavailableError): + await attribute_source("entsoe.price", entities, {}).fetch_segments(window(), NOW) + bare = {ENTSOE_ENTITY: EntityReading("unknown", {})} + with pytest.raises(MalformedPayloadError): + await attribute_source("entsoe.price", entities, bare).fetch_segments(window(), NOW) + empty = {ENTSOE_ENTITY: EntityReading("0.1", {"prices": []})} + data = await attribute_source("entsoe.price", entities, empty).fetch_segments(window(), NOW) + assert data.segments == () # published, but nothing yet: no error + + +async def test_a_required_role_without_an_entity_is_reported() -> None: + source = attribute_source("entsoe.price", {}, readings("entsoe_avg_price")) + with pytest.raises(MissingEntityError): + await source.fetch_segments(window(), NOW) + + +# --- EPEX Spot (attribute, local ISO, end_time, unit literal) -------------------------- + + +async def test_epex_total_price_mixed_hourly_and_quarter_hour_slots() -> None: + entity = "sensor.epex_spot_total_price" + source = attribute_source( + "epex_spot.total_price", {"price": entity}, readings("epex_spot_total_price") + ) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + hourly, quarter = data.segments + assert (hourly.step, hourly.import_price.values) == (H, (0.2631, 0.2587)) + assert (quarter.step, quarter.import_price.values) == (Q, (0.2561, 0.2549)) + assert source.price_includes == "all_in" + assert hourly.price_includes == "all_in" + + +async def test_epex_market_price_template_is_spot_only() -> None: + entity = "sensor.epex_spot_market_price" + source = attribute_source( + "epex_spot.market_price", + {"price": entity}, + readings("epex_spot_total_price") + | {entity: readings("epex_spot_total_price")["sensor.epex_spot_total_price"]}, + ) + assert source.price_includes == "spot_only" + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + assert data.segments[0].price_includes == "spot_only" + + +async def test_epex_gbp_symbol_is_accepted_by_the_unit_check() -> None: + attrs = dict(readings("epex_spot_total_price")["sensor.epex_spot_total_price"].attributes) + attrs["unit_of_measurement"] = "£/kWh" + source = attribute_source( + "epex_spot.total_price", + {"price": "sensor.x"}, + {"sensor.x": EntityReading("0.2", attrs)}, + currency="GBP", + ) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + assert data.segments + + +# --- Octopus (two event entities merged, 30 minutes, GBP) ------------------------------- + +CURRENT = "event.octopus_energy_electricity_1234_5678_current_day_rates" +NEXT = "event.octopus_energy_electricity_1234_5678_next_day_rates" + + +async def test_octopus_merges_current_and_next_day_rates() -> None: + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT, "next_day_rates": NEXT}, + readings("octopus_rates"), + tz=LONDON, + currency="GBP", + ) + win = TimeRange( + start=datetime(2026, 10, 15, 23, 0, tzinfo=UTC), + end=datetime(2026, 10, 17, 23, 0, tzinfo=UTC), + ) + data = await source.fetch_segments(win, NOW) + today, tomorrow = data.segments # 00:00-01:30 today, 00:00-01:00 tomorrow: two runs + assert today.step == tomorrow.step == timedelta(minutes=30) + assert today.price_includes == "all_in" + assert today.import_price.values == (0.1245, 0.1302, 0.1519) + assert tomorrow.import_price.values == (0.101, 0.0955) + assert data.known_end == datetime(2026, 10, 17, 0, 0, tzinfo=UTC) + + +async def test_octopus_without_the_next_day_entity_still_reads_the_current_day() -> None: + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT}, + readings("octopus_rates"), + tz=LONDON, + currency="GBP", + ) + win = TimeRange( + start=datetime(2026, 10, 15, 23, 0, tzinfo=UTC), + end=datetime(2026, 10, 17, 23, 0, tzinfo=UTC), + ) + data = await source.fetch_segments(win, NOW) + assert len(data.segments) == 1 + + +async def test_octopus_event_entity_before_its_first_event_has_no_rates() -> None: + r = readings("octopus_rates") + r[NEXT] = EntityReading("unknown", {"event_types": ["x"]}) + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT, "next_day_rates": NEXT}, + r, + tz=LONDON, + currency="GBP", + ) + win = TimeRange( + start=datetime(2026, 10, 15, 23, 0, tzinfo=UTC), + end=datetime(2026, 10, 17, 23, 0, tzinfo=UTC), + ) + data = await source.fetch_segments(win, NOW) + assert data.known_end == datetime(2026, 10, 16, 0, 30, tzinfo=UTC) + + +async def test_octopus_next_day_published_in_a_different_slot_length_makes_a_new_segment() -> None: + r = readings("octopus_rates") + r[NEXT] = EntityReading( + "x", + { + "rates": [ + { + "start": "2026-10-17T00:00:00+01:00", + "end": "2026-10-17T01:00:00+01:00", + "value_inc_vat": 0.1, + } + ] + }, + ) + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT, "next_day_rates": NEXT}, + r, + tz=LONDON, + currency="GBP", + ) + win = TimeRange( + start=datetime(2026, 10, 15, 23, 0, tzinfo=UTC), + end=datetime(2026, 10, 17, 23, 0, tzinfo=UTC), + ) + data = await source.fetch_segments(win, NOW) + assert [s.step for s in data.segments] == [timedelta(minutes=30), H] + + +# --- generic ---------------------------------------------------------------------------- + + +async def test_generic_price_list_quarter_hours() -> None: + entity = "sensor.my_price_list" + source = attribute_source( + "generic.price_list", {"price": entity}, readings("generic_price_list") + ) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + (segment,) = data.segments + assert (segment.step, segment.import_price.values) == (Q, (0.31, 0.3, 0.29)) + + +# --- the PriceSource protocol ----------------------------------------------------------- + + +async def test_fetch_without_data_is_an_empty_series_at_the_window_start() -> None: + actions = StubActions(lambda _data: {"prices": {}}) + out = await action_source("tibber.price", actions).fetch(window()) + assert len(out) == 0 + assert out.start == window().start + + +async def test_finest_series_holds_coarse_prices_over_finer_slots() -> None: + entity = "sensor.epex_spot_total_price" + source = attribute_source( + "epex_spot.total_price", {"price": entity}, readings("epex_spot_total_price") + ) + series = await source.fetch(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN))) + assert series.step == Q + assert series.import_price.values[:4] == (0.2631,) * 4 + assert series.import_price.values[8:10] == (0.2561, 0.2549) + again = finest_series("x", "all_in", [], window()) + assert len(again) == 0 + + +# --- construction guards ---------------------------------------------------------------- + + +def test_the_engine_refuses_templates_it_cannot_serve() -> None: + binding = SourceBinding(tz=BERLIN) + with pytest.raises(ValueError, match="ActionCaller"): + TemplatePriceSource(template("tibber.price"), binding, clock=lambda: NOW) + with pytest.raises(ValueError, match="EntityReader"): + TemplatePriceSource(template("entsoe.price"), binding, clock=lambda: NOW) + + +# --- price entity only (no template) ---------------------------------------------------- + + +async def test_current_price_source_is_one_slot_from_the_entity_state() -> None: + entity = {"sensor.p": EntityReading("0.25", {"unit_of_measurement": "EUR/kWh"})} + source = CurrentPriceSource( + "sensor.p", reader_of(entity), price_includes="all_in", clock=lambda: NOW + ) + data = await source.fetch_segments(window(), NOW) + (segment,) = data.segments + assert segment.import_price.values == (0.25,) + assert segment.start == floor_to_step(NOW) + assert source.watched_entities == ("sensor.p",) + assert (await source.fetch(window())).import_price.values == (0.25,) + + +async def test_current_price_source_converts_mwh_and_rejects_bad_states() -> None: + mwh = {"sensor.p": EntityReading("85.0", {"unit_of_measurement": "EUR/MWh"})} + data = await CurrentPriceSource( + "sensor.p", reader_of(mwh), price_includes="spot_only", clock=lambda: NOW + ).fetch_segments(window(), NOW) + assert data.segments[0].import_price.values == (0.085,) + for reading in (None, EntityReading("unknown", {})): + source = CurrentPriceSource( + "sensor.p", reader_of({"sensor.p": reading}), price_includes="all_in", clock=lambda: NOW + ) + with pytest.raises(SourceUnavailableError): + await source.fetch_segments(window(), NOW) + + +# --- delivery day in the market's zone, currency guard (review M4, m2) ------------------ + + +async def test_nordpool_dates_are_cet_delivery_days_not_the_sites_days() -> None: + """A site in London at 23:30 local on 16 Oct is already in the CET day 17 Oct.""" + now = datetime(2026, 10, 16, 22, 30, tzinfo=UTC) + actions = nordpool_by_date() + source = action_source( + "nordpool.price", actions, now=now, tz=LONDON, action_params=NORDPOOL_PARAMS + ) + win = TimeRange(start=floor_to_step(now), end=floor_to_step(now) + timedelta(hours=48)) + await source.fetch_segments(win, now) + assert [c[2]["date"] for c in actions.calls] == ["2026-10-17", "2026-10-18"] + assert source.delivery_tz is not None + assert str(source.delivery_tz) == "Europe/Berlin" + + +async def test_templates_without_a_date_zone_have_no_delivery_zone() -> None: + assert action_source("tibber.price", StubActions(lambda _d: {})).delivery_tz is None + entity = "sensor.entsoe_average_electricity_price" + assert attribute_source("entsoe.price", {"price": entity}, {}).delivery_tz is None + + +async def test_prices_in_another_currency_than_the_region_are_refused() -> None: + # the template's own currency (Octopus is GBP) against a euro region + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT}, + readings("octopus_rates"), + tz=LONDON, + ) + with pytest.raises(CurrencyMismatchError) as err: + await source.fetch_segments(window(), NOW) + assert err.value.message_args == {"source_currency": "GBP", "region_currency": "EUR"} + assert err.value.key == "tariff.error.currency_mismatch" + assert isinstance(err.value, UnitMismatchError) + + +async def test_a_sensor_unit_in_another_currency_is_refused() -> None: + rows = [{"time": "2026-10-16 00:00:00+02:00", "price": 0.1}] + entity = EntityReading("0.1", {"unit_of_measurement": "SEK/kWh", "prices": rows}) + source = attribute_source("entsoe.price", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: entity}) + with pytest.raises(CurrencyMismatchError): + await source.fetch_segments(window(24, MIDNIGHT), NOW) + # a symbol maps to its code: EPEX's euro sign is EUR + epex = readings("epex_spot_total_price") + ok = attribute_source("epex_spot.total_price", {"price": "sensor.epex_spot_total_price"}, epex) + assert (await ok.fetch_segments(window(24, MIDNIGHT), NOW)).segments + + +async def test_a_currency_field_for_the_action_must_match_the_region() -> None: + actions = nordpool_by_date() + source = action_source( + "nordpool.price", + actions, + action_params={"config_entry": "x", "currency": "SEK"}, + ) + with pytest.raises(CurrencyMismatchError): + await source.fetch_segments(window(), NOW) + assert actions.calls == [] + same = action_source( + "nordpool.price", actions, action_params={"config_entry": "x", "currency": "eur"} + ) + await same.fetch_segments(window(2), NOW) + assert actions.calls diff --git a/tests/tariff/test_parse.py b/tests/tariff/test_parse.py new file mode 100644 index 0000000..9cea91d --- /dev/null +++ b/tests/tariff/test_parse.py @@ -0,0 +1,349 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Parsing of price lists: timestamps, numbers, paths, normalising and segmenting.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta + +import pytest + +from suncore.core.series import SeriesUnit, TimeSeries +from suncore.tariff.errors import AmbiguousSeriesError, MalformedPayloadError +from suncore.tariff.parse import ( + RawSlot, + build_segments, + clip_series, + expand_path, + infer_step, + normalise, + parse_number, + parse_timestamp, + select_series, + slots_from_mapping, + slots_from_records, + walk, +) +from suncore.templates.models import SeriesFields +from tests.tariff.helpers import BERLIN + +H = timedelta(hours=1) +Q = timedelta(minutes=15) + + +def utc(*args: int) -> datetime: + return datetime(*args, tzinfo=UTC) + + +# --- timestamps ------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + ("text", "expected"), + [ + # ENTSO-E: str(datetime) with a space (research: coordinator.py:250-256) + ("2026-10-16 00:00:00+02:00", utc(2026, 10, 15, 22)), + # EPEX Spot / Octopus: local ISO 8601 + ("2026-10-16T00:00:00+02:00", utc(2026, 10, 15, 22)), + # Nord Pool: UTC +00:00 + ("2026-10-15T22:00:00+00:00", utc(2026, 10, 15, 22)), + # Tibber: milliseconds and Z + ("2026-10-16T00:00:00.000+02:00", utc(2026, 10, 15, 22)), + ("2026-10-15T22:00:00Z", utc(2026, 10, 15, 22)), + (" 2026-10-16 00:00:00+02:00 ", utc(2026, 10, 15, 22)), + ], +) +def test_timestamps_are_parsed_to_utc(text: str, expected: datetime) -> None: + assert parse_timestamp(text) == expected + assert parse_timestamp(text).tzinfo is UTC + + +def test_datetime_objects_are_accepted() -> None: + assert parse_timestamp(datetime(2026, 10, 16, tzinfo=BERLIN)) == utc(2026, 10, 15, 22) + + +@pytest.mark.parametrize( + "bad", + [ + "2026-10-16 00:00:00", + "yesterday", + "", + None, + 5, + datetime.fromisoformat("2026-01-01T00:00:00"), + ], +) +def test_a_timestamp_without_offset_or_text_is_malformed(bad: object) -> None: + with pytest.raises(MalformedPayloadError): + parse_timestamp(bad) + + +@pytest.mark.parametrize( + ("raw", "expected"), + [(1, 1.0), (0.25, 0.25), ("0.5", 0.5), (" -3.5 ", -3.5), ("1e-3", 0.001)], +) +def test_numbers(raw: object, expected: float) -> None: + assert parse_number(raw) == expected + + +@pytest.mark.parametrize("raw", [None, True, "n/a", "", float("nan"), float("inf"), "nan", [], {}]) +def test_unreadable_numbers_are_none(raw: object) -> None: + assert parse_number(raw) is None + + +# --- paths ------------------------------------------------------------------------------ + + +def test_walk_follows_dotted_keys_and_rejects_a_missing_one() -> None: + assert walk({"a": {"b": [1]}}, "a.b") == [1] + with pytest.raises(MalformedPayloadError): + walk({"a": {}}, "a.b") + with pytest.raises(MalformedPayloadError): + walk({"a": 1}, "a.b") + + +def test_star_fans_out_over_a_mapping() -> None: + payload = {"prices": {"Home": [1], "Cabin": [2]}} + assert expand_path(payload, "prices.*") == [("Home", [1]), ("Cabin", [2])] + assert expand_path({"SE3": [3]}, "*") == [("SE3", [3])] + assert expand_path({"other": 1}, "prices.*") == [] # nothing there: not an error + + +def test_a_path_through_a_non_object_is_malformed() -> None: + with pytest.raises(MalformedPayloadError): + expand_path({"prices": [1]}, "prices.*") + + +def test_select_series_the_only_one_or_the_named_one() -> None: + assert select_series([("Home", [1])], None) == [1] + assert select_series([], None) is None + two = [("Home", [1]), ("Cabin", [2])] + assert select_series(two, "Cabin") == [2] + assert select_series(two, "cabin") == [2] # area codes are case-insensitive + assert select_series([], "Home") is None + + +def test_several_series_without_a_key_are_ambiguous() -> None: + with pytest.raises(AmbiguousSeriesError) as err: + select_series([("Home", [1]), ("Cabin", [2])], None) + assert err.value.message_args["available"] == "Cabin, Home" + + +def test_an_unknown_key_is_malformed() -> None: + with pytest.raises(MalformedPayloadError): + select_series([("Home", [1])], "Cabin") + + +# --- records and mappings --------------------------------------------------------------- + +TIBBER = SeriesFields(timestamp_field="start_time", value_field="price", value_unit="EUR/kWh") +NORDPOOL = SeriesFields( + timestamp_field="start", end_field="end", value_field="price", value_unit="EUR/MWh" +) + + +def test_records_with_a_missing_or_text_value_become_gaps() -> None: + slots, bad = slots_from_records( + [ + {"start_time": "2026-10-16T00:00:00+02:00", "price": 0.1}, + {"start_time": "2026-10-16T00:15:00+02:00", "price": None}, + {"start_time": "2026-10-16T00:30:00+02:00", "price": "x"}, + {"start_time": "2026-10-16T00:45:00+02:00"}, + ], + TIBBER, + ) + assert [s.value for s in slots] == [0.1, None, None, None] + assert bad == 3 + + +def test_records_need_a_timestamp_and_a_list() -> None: + with pytest.raises(MalformedPayloadError): + slots_from_records([{"price": 1}], TIBBER) + with pytest.raises(MalformedPayloadError): + slots_from_records("nope", TIBBER) + with pytest.raises(MalformedPayloadError): + slots_from_records(["nope"], TIBBER) + + +def test_records_with_an_end_field() -> None: + slots, _ = slots_from_records( + [{"start": "2026-10-15T22:00:00+00:00", "end": "2026-10-15T23:00:00+00:00", "price": 45.5}], + NORDPOOL, + ) + assert slots == [RawSlot(utc(2026, 10, 15, 22), utc(2026, 10, 15, 23), 45.5)] + + +def test_mapping_shape() -> None: + slots, bad = slots_from_mapping( + {"2026-10-16T00:00:00+02:00": 0.1, "2026-10-16T01:00:00+02:00": "?"} + ) + assert [s.value for s in slots] == [0.1, None] + assert bad == 1 + with pytest.raises(MalformedPayloadError): + slots_from_mapping([1]) + + +# --- normalise -------------------------------------------------------------------------- + + +def test_normalise_sorts_and_the_later_duplicate_wins() -> None: + slots, report = normalise( + [ + RawSlot(utc(2026, 1, 1, 1), None, 2.0), + RawSlot(utc(2026, 1, 1, 0), None, 1.0), + RawSlot(utc(2026, 1, 1, 1), None, 3.0), + ] + ) + assert [(s.start.hour, s.value) for s in slots] == [(0, 1.0), (1, 3.0)] + assert report.duplicates == 1 + assert report.points == 2 + + +def test_normalise_drops_overlapping_and_inverted_slots() -> None: + a = RawSlot(utc(2026, 1, 1, 0), utc(2026, 1, 1, 1), 1.0) + overlap = RawSlot(utc(2026, 1, 1, 0, 30), utc(2026, 1, 1, 1, 30), 2.0) + inverted = RawSlot(utc(2026, 1, 1, 5), utc(2026, 1, 1, 4), 3.0) + slots, report = normalise([a, overlap, inverted], unreadable=2) + assert slots == [a] + assert report.overlaps == 2 + assert report.unreadable_values == 2 + + +# --- segments --------------------------------------------------------------------------- + + +def slot(start: datetime, minutes: int | None, value: float | None) -> RawSlot: + end = None if minutes is None else start + timedelta(minutes=minutes) + return RawSlot(start, end, value) + + +def test_infer_step_uses_the_most_common_distance_and_prefers_the_finer_on_a_tie() -> None: + t0 = utc(2026, 1, 1) + assert infer_step([t0, t0 + Q, t0 + 2 * Q], None) == Q + assert infer_step([t0, t0 + H], None) == H + assert infer_step([t0, t0 + Q, t0 + Q + H], None) == Q # tie: finer + assert infer_step([t0], Q) == Q + assert infer_step([t0], None) == H + + +def test_explicit_slots_hourly_become_one_segment_with_the_mwh_conversion() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [slot(t0 + H * i, 60, 45.0 * (i + 1)) for i in range(3)] + (seg,) = build_segments(slots, divisor=1000.0, resolution=None) + assert seg.step == H + assert seg.unit is SeriesUnit.PRICE + assert seg.values == (0.045, 0.09, 0.135) + + +def test_explicit_slots_mixed_15_and_60_minutes_make_two_segments() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [ + slot(t0, 60, 1.0), + slot(t0 + H, 60, 2.0), + slot(t0 + 2 * H, 15, 3.0), + slot(t0 + 2 * H + Q, 15, 4.0), + ] + hourly, quarter = build_segments(slots, divisor=1.0, resolution=None) + assert (hourly.step, hourly.values) == (H, (1.0, 2.0)) + assert (quarter.step, quarter.start, quarter.values) == (Q, t0 + 2 * H, (3.0, 4.0)) + + +def test_explicit_slots_with_a_hole_start_a_new_segment_and_no_value_is_invented() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [slot(t0, 60, 1.0), slot(t0 + 2 * H, 60, 3.0)] + first, second = build_segments(slots, divisor=1.0, resolution=None) + assert first.end == t0 + H + assert second.start == t0 + 2 * H + + +def test_inferred_hourly_with_a_gap_has_none_in_the_gap() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [slot(t0, None, 1.0), slot(t0 + H, None, 2.0), slot(t0 + 3 * H, None, 4.0)] + (seg,) = build_segments(slots, divisor=1.0, resolution=None) + assert seg.values == (1.0, 2.0, None, 4.0) + + +def test_inferred_quarter_hours_then_hourly_tomorrow() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [slot(t0 + Q * i, None, float(i)) for i in range(8)] + slots += [slot(t0 + 2 * H + H * i, None, 10.0 + i) for i in range(3)] + quarter, hourly = build_segments(slots, divisor=1.0, resolution=None) + assert quarter.step == Q + assert len(quarter) == 8 + assert hourly.step == H + assert hourly.values == (10.0, 11.0, 12.0) + + +def test_inferred_template_resolution_wins_for_a_single_point() -> None: + (seg,) = build_segments([slot(utc(2026, 1, 1), None, 1.0)], divisor=1.0, resolution=Q) + assert seg.step == Q + + +def test_irregular_timestamps_are_malformed_never_guessed() -> None: + t0 = utc(2026, 1, 1) + slots = [ + slot(t0, None, 1.0), + slot(t0 + H, None, 2.0), + slot(t0 + 2 * H, None, 3.0), + slot(t0 + 2 * H + timedelta(minutes=20), None, 4.0), + ] + with pytest.raises(MalformedPayloadError): + build_segments(slots, divisor=1.0, resolution=None) + + +def test_no_slots_no_segments() -> None: + assert build_segments([], divisor=1.0, resolution=None) == () + + +def test_dst_days_have_23_and_25_hours() -> None: + """Europe/Berlin: 2026-03-29 has 23 h, 2026-10-25 has 25 h (hourly local slots).""" + for day, hours in ( + (datetime(2026, 3, 29, tzinfo=UTC), 23), + (datetime(2026, 10, 25, tzinfo=UTC), 25), + ): + start = datetime.combine(day.date(), datetime.min.time(), tzinfo=BERLIN) + end = datetime.combine(day.date() + timedelta(days=1), datetime.min.time(), tzinfo=BERLIN) + assert end.astimezone(UTC) - start.astimezone(UTC) == timedelta(hours=hours) + slots = [] + t = start.astimezone(UTC) + while t < end.astimezone(UTC): + slots.append(slot(t, None, 0.1)) + t += H + (seg,) = build_segments(slots, divisor=1.0, resolution=None) + assert len(seg) == hours + assert seg.end == end.astimezone(UTC) + + +def test_the_repeated_local_hour_of_the_25_hour_day_keeps_both_slots() -> None: + """ENTSO-E prints `str(datetime)` with the offset: 02:00+02:00 and 02:00+01:00 differ.""" + slots = [ + slot(parse_timestamp("2026-10-25 01:00:00+02:00"), None, 1.0), + slot(parse_timestamp("2026-10-25 02:00:00+02:00"), None, 2.0), + slot(parse_timestamp("2026-10-25 02:00:00+01:00"), None, 3.0), + slot(parse_timestamp("2026-10-25 03:00:00+01:00"), None, 4.0), + ] + normalised, report = normalise(slots) + (seg,) = build_segments(normalised, divisor=1.0, resolution=None) + assert seg.values == (1.0, 2.0, 3.0, 4.0) + assert report.duplicates == 0 + + +# --- clip ------------------------------------------------------------------------------- + + +def series(start: datetime, n: int, step: timedelta = H) -> TimeSeries: + return TimeSeries( + start=start, step=step, values=tuple(float(i) for i in range(n)), unit=SeriesUnit.PRICE + ) + + +def test_clip_keeps_whole_slots_that_overlap_the_window() -> None: + t0 = utc(2026, 1, 1) + s = series(t0, 6) + clipped = clip_series(s, t0 + H + timedelta(minutes=30), t0 + 4 * H - timedelta(minutes=30)) + assert clipped is not None + assert (clipped.start, clipped.values) == (t0 + H, (1.0, 2.0, 3.0)) + assert clip_series(s, t0 + 7 * H, t0 + 8 * H) is None + assert clip_series(s, t0 - 2 * H, t0) is None + whole = clip_series(s, t0 - H, t0 + 10 * H) + assert whole is not None + assert whole.values == s.values diff --git a/tests/tariff/test_pricing.py b/tests/tariff/test_pricing.py new file mode 100644 index 0000000..24f4c2d --- /dev/null +++ b/tests/tariff/test_pricing.py @@ -0,0 +1,189 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Price formula on spot sources, the export side and the negative-price rule.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta + +import pytest + +from suncore.core.config import ExportTariff, ExportTier +from suncore.core.series import Grid, PriceSeries, SeriesUnit, TimeSeries +from suncore.core.tariff import GridFeeWindow, PriceFormula, TouWindow +from suncore.tariff import ( + ExportConfigError, + ExportTiersError, + apply_import_formula, + export_base_price, + planning_prices, +) +from suncore.templates.models import NegativePriceRule +from tests.tariff.helpers import BERLIN, prices + +T0 = datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN).astimezone(UTC) +Q = timedelta(minutes=15) +H = timedelta(hours=1) +RULE = NegativePriceRule.NO_REMUNERATION + + +def grid(count: int, start: datetime = T0) -> Grid: + return Grid(start=start, step=Q, count=count) + + +def run( + segments: list[PriceSeries], + count: int, + *, + formula: PriceFormula | None = None, + export: float = 0.08, + rule: NegativePriceRule = RULE, +) -> tuple[PriceSeries, int]: + return planning_prices( + segments, grid(count), formula=formula, export_price=export, rule=rule, tz=BERLIN + ) + + +# --- formula ---------------------------------------------------------------------------- + +FORMULA = PriceFormula(grid_fee=0.10, levies=0.05, margin=0.02, vat_pct=19) + + +def test_a_spot_source_gets_the_formula_at_the_slot_start() -> None: + spot = prices(T0, [0.10, 0.20, None, -0.05], includes="spot_only").import_price + end, includes = apply_import_formula(spot, "spot_only", FORMULA, BERLIN) + assert includes == "all_in" + assert end.values[0] == pytest.approx((0.10 + 0.10 + 0.05 + 0.02) * 1.19) + assert end.values[2] is None + assert end.values[3] == pytest.approx((-0.05 + 0.17) * 1.19) + + +def test_an_all_in_source_never_gets_the_formula_even_if_one_is_configured() -> None: + series = prices(T0, [0.30, 0.31], includes="all_in").import_price + end, includes = apply_import_formula(series, "all_in", FORMULA, BERLIN) + assert end is series + assert includes == "all_in" + + +def test_a_spot_source_without_a_formula_stays_spot_only() -> None: + series = prices(T0, [0.10], includes="spot_only").import_price + end, includes = apply_import_formula(series, "spot_only", None, BERLIN) + assert end is series + assert includes == "spot_only" + + +def test_time_variable_grid_fee_is_judged_in_local_time() -> None: + formula = PriceFormula( + grid_fee=0.10, + grid_fee_windows=(GridFeeWindow(window=TouWindow(start="22:00", end="06:00"), fee=0.03),), + ) + # 21:45 local (CEST) = 19:45Z, 22:00 local = 20:00Z + start = datetime(2026, 10, 16, 21, 45, tzinfo=BERLIN) + spot = prices(start, [0.0, 0.0], includes="spot_only").import_price + end, _ = apply_import_formula(spot, "spot_only", formula, BERLIN) + assert end.values == pytest.approx((0.10, 0.03)) + + +# --- export side ------------------------------------------------------------------------ + + +def test_export_fixed_none_and_tiered() -> None: + assert export_base_price(ExportTariff(kind="fixed", fixed_price=0.081), None) == 0.081 + assert export_base_price(ExportTariff(kind="none"), None) == 0.0 + tiered = ExportTariff( + kind="tiered", + tiers=(ExportTier(up_to_kwp=10, price=0.08), ExportTier(price=0.07)), + ) + assert export_base_price(tiered, 17.0) == pytest.approx((10 * 0.08 + 7 * 0.07) / 17) + assert export_base_price(tiered, 8.0) == pytest.approx(0.08) + + +def test_tiered_export_needs_the_plant_size_and_tiers_that_cover_it() -> None: + tiered = ExportTariff(kind="tiered", tiers=(ExportTier(up_to_kwp=10, price=0.08),)) + with pytest.raises(ExportConfigError): + export_base_price(tiered, None) + with pytest.raises(ExportTiersError) as err: + export_base_price(tiered, 17.0) # the tiers end at 10 kWp: no rate is guessed + assert err.value.key == "tariff.error.export_tiers" + assert err.value.message_args == {"kwp": 17.0} + assert isinstance(err.value, ExportConfigError) + + +# --- planning prices -------------------------------------------------------------------- + + +def test_negative_spot_price_zeroes_export_before_the_formula_hides_it() -> None: + """Spot -0.02 becomes a positive end price (grid fee, levies) but the grid operator pays + nothing in that slot: the rule looks at the spot price of a spot-only source.""" + series = prices(T0, [0.10, -0.02, 0.0, -0.001], includes="spot_only") + out, zeroed = run([series], 4, formula=FORMULA) + assert out.price_includes == "all_in" + assert out.import_price.values[1] == pytest.approx((-0.02 + 0.17) * 1.19) + assert out.import_price.values[1] > 0 + assert out.export_price is not None + assert out.export_price.values == (0.08, 0.0, 0.08, 0.0) + assert zeroed == 2 + + +def test_an_all_in_source_uses_the_import_price_as_the_negative_proxy() -> None: + series = prices(T0, [0.25, -0.01, 0.0], includes="all_in") + out, zeroed = run([series], 3) + assert out.import_price.values == (0.25, -0.01, 0.0) + assert out.export_price is not None + assert out.export_price.values == (0.08, 0.0, 0.08) # zero is not negative + assert zeroed == 1 + + +def test_without_the_rule_export_keeps_its_price_at_negative_prices() -> None: + series = prices(T0, [-0.05, 0.1], includes="spot_only") + for rule in (NegativePriceRule.NONE, NegativePriceRule.CURTAILMENT_REQUIRED): + out, zeroed = run([series], 2, rule=rule) + assert out.export_price is not None + assert out.export_price.values == (0.08, 0.08) + assert zeroed == 0 + + +def test_unknown_prices_stay_unknown_in_both_series() -> None: + series = prices(T0, [0.2, None, 0.2], includes="all_in") + out, _ = run([series], 5) + assert out.import_price.values == (0.2, None, 0.2, None, None) + assert out.export_price is not None + assert out.export_price.values == (0.08, None, 0.08, None, None) + + +def test_mixed_15_and_60_minute_segments_are_held_onto_the_grid() -> None: + hourly = prices(T0, [0.30, -0.10], step=H, includes="all_in") + quarter = prices(T0 + 2 * H, [0.20, 0.21], includes="all_in") + out, zeroed = run([hourly, quarter], 10) + assert out.import_price.values == (0.3,) * 4 + (-0.1,) * 4 + (0.2, 0.21) + assert zeroed == 4 + assert out.source_id == "t" + + +def test_a_source_with_its_own_export_prices_wins() -> None: + imp = prices(T0, [0.3, -0.2]).import_price + own = TimeSeries(start=T0, step=Q, values=(0.05, 0.04), unit=SeriesUnit.PRICE) + out, zeroed = run( + [PriceSeries(source_id="s", price_includes="all_in", import_price=imp, export_price=own)], 2 + ) + assert out.export_price is not None + assert out.export_price.values == (0.05, 0.04) # the source decides, the rule is not applied + assert zeroed == 0 + + +def test_no_segments_gives_unknown_prices_not_zeros() -> None: + out, zeroed = planning_prices( + [], grid(3), formula=None, export_price=0.08, rule=RULE, tz=BERLIN, source_id="x" + ) + assert out.source_id == "x" + assert out.import_price.values == (None, None, None) + assert out.export_price is not None + assert out.export_price.values == (None, None, None) + assert zeroed == 0 + + +def test_export_none_means_zero_not_unknown() -> None: + out, _ = run( + [prices(T0, [0.3, 0.3])], 2, export=export_base_price(ExportTariff(kind="none"), None) + ) + assert out.export_price is not None + assert out.export_price.values == (0.0, 0.0) diff --git a/tests/tariff/test_service.py b/tests/tariff/test_service.py new file mode 100644 index 0000000..4a1b050 --- /dev/null +++ b/tests/tariff/test_service.py @@ -0,0 +1,739 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The tariff service: refresh decisions with injected time, caching, storing, serving.""" + +from __future__ import annotations + +import asyncio +from collections.abc import Iterable +from dataclasses import dataclass, field +from datetime import UTC, datetime, time, timedelta, tzinfo + +import pytest + +from suncore.core.config import ExportTariff, ExportTier +from suncore.core.series import PriceSeries, TimeRange, TimeSeries +from suncore.tariff import ( + ExportConfigError, + FixedPriceSource, + MalformedPayloadError, + ServiceSettings, + SourceThrottledError, + SourceUnavailableError, + TariffPlan, + TariffService, +) +from suncore.tariff.sources import SourceData, SourceKind +from suncore.templates.models import NegativePriceRule +from tests.tariff.helpers import BERLIN + +Q = timedelta(minutes=15) +H = timedelta(hours=1) +FIXED_EXPORT = ExportTariff(kind="fixed", fixed_price=0.08) + + +def local(day: int, hour: int, minute: int = 0) -> datetime: + return datetime(2026, 10, day, hour, minute, tzinfo=BERLIN) + + +class Clock: + def __init__(self, now: datetime) -> None: + self.now = now + + def __call__(self) -> datetime: + return self.now + + def advance(self, **kwargs: float) -> None: + self.now += timedelta(**kwargs) + + +def hourly(start: datetime, values: Iterable[float | None]) -> PriceSeries: + series = TimeSeries(start=start, step=H, values=tuple(values), unit="currency/kWh") # type: ignore[arg-type] + return PriceSeries(source_id="fake", price_includes="all_in", import_price=series) + + +@dataclass +class FakeSource: + """A dynamic source whose answer the test controls.""" + + segments: tuple[PriceSeries, ...] = () + error: Exception | None = None + kind: SourceKind = "dynamic" + uses_action: bool = True + price_includes: str = "all_in" + source_id: str = "fake" + watched_entities: tuple[str, ...] = ("sensor.price",) + delivery_tz: tzinfo | None = None + calls: list[datetime] = field(default_factory=list) + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: # noqa: ARG002 + self.calls.append(now) + if self.error is not None: + raise self.error + return SourceData(segments=self.segments) + + +def day_prices(day: int, days: int = 1, value: float = 0.30) -> PriceSeries: + return hourly(local(day, 0), [value] * 24 * days) + + +class Store: + def __init__(self, *, fail: bool = False) -> None: + self.written: list[PriceSeries] = [] + self.fail = fail + + async def store_prices(self, prices: PriceSeries) -> int: + if self.fail: + msg = "disk full" + raise OSError(msg) + self.written.append(prices) + return len(prices) + + +def make( + source: FakeSource | FixedPriceSource, + now: datetime, + *, + store: Store | None = None, + export: ExportTariff = FIXED_EXPORT, + rule: NegativePriceRule = NegativePriceRule.NONE, + settings: ServiceSettings | None = None, + kwp: float | None = None, +) -> tuple[TariffService, Clock]: + clock = Clock(now) + plan = TariffPlan( + source=source, # type: ignore[arg-type] + export_tariff=export, + negative_rule=rule, + tz=BERLIN, + currency="EUR", + total_kwp=kwp, + ) + return TariffService(plan, clock=clock, store=store, settings=settings), clock + + +# --- when to refresh -------------------------------------------------------------------- + + +async def test_first_refresh_is_initial_then_nothing_is_due_until_the_interval() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 7)) + assert service.due() == "initial" + result = await service.tick() + assert result is not None + assert result.ok + assert result.reason == "initial" + assert service.due() is None + clock.advance(minutes=59) + assert service.due() is None + clock.advance(minutes=1) + assert service.due() == "interval" + assert service.next_refresh() == clock.now + await service.tick() + assert len(source.calls) == 2 + + +async def test_tomorrow_is_asked_from_the_publication_time_every_poll_interval() -> None: + source = FakeSource(segments=(day_prices(16),)) # today only + service, clock = make(source, local(16, 12, 30)) + await service.refresh("initial") + assert not service.report(48).quality.has_tomorrow + assert service.next_refresh() == local(16, 13, 0) # publication time, before the hourly one + clock.now = local(16, 12, 59) + assert service.due() is None + clock.now = local(16, 13, 0) + assert service.due() == "tomorrow" + await service.tick() # still not published + clock.now = local(16, 13, 14) + assert service.due() is None # the poll interval (15 min) has not passed + clock.now = local(16, 13, 15) + assert service.due() == "tomorrow" + source.segments = (day_prices(16, 2),) + await service.tick() + assert service.report(48).quality.has_tomorrow + clock.now = local(16, 13, 40) + assert service.due() is None # covered: back to the hourly rhythm + assert service.next_refresh() == local(16, 14, 15) + + +async def test_static_sources_do_not_poll_for_tomorrow() -> None: + service, clock = make(FixedPriceSource(price=0.3), local(16, 14, 0)) + await service.refresh("initial") + clock.now = local(16, 14, 30) + assert service.due() is None + assert service.report().freshness.status == "static" + + +async def test_an_entity_change_refreshes_attribute_sources_at_once() -> None: + source = FakeSource(segments=(day_prices(16, 2),), uses_action=False) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + clock.advance(minutes=5) + assert service.due() is None + service.notify_changed() + assert service.due() == "changed" + result = await service.tick() + assert result is not None + assert result.reason == "changed" + assert service.due() is None # the flag is cleared by a successful refresh + + +async def test_an_entity_change_does_not_hit_an_action_source_while_the_slot_is_known() -> None: + source = FakeSource(segments=(day_prices(16, 2),), uses_action=True) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + clock.advance(minutes=15) + service.notify_changed() + assert service.due() is None # an action costs a request, the sensor changes every slot + clock.now = local(18, 0, 0) # the known prices ran out: now the change is worth a call + assert service.due() == "changed" + + +async def test_a_new_change_after_a_failed_first_fetch_does_not_wait_for_the_back_off() -> None: + source = FakeSource(error=SourceUnavailableError("cache empty"), uses_action=False) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + assert service.due() is None # backing off; the change that caused the attempt is consumed + source.error = None + source.segments = (day_prices(16, 2),) + clock.advance(seconds=30) + service.notify_changed() # the entity arrived: a new change + assert service.due() == "changed" + + +async def test_a_failing_attribute_source_is_not_refetched_every_poll() -> None: + """M1: the dirty flag of a failed fetch used to stay set -> a fetch every 30 s.""" + source = FakeSource(error=MalformedPayloadError("bad"), uses_action=False) + service, clock = make(source, local(16, 10, 0)) + service.notify_changed() + await service.tick() # the first fetch fails + for _ in range(8): # four minutes of 30 s polls inside the five-minute back-off + clock.advance(seconds=30) + assert await service.tick() is None + assert len(source.calls) == 1 + clock.advance(seconds=60) + assert service.due() == "initial" # back-off over + + +async def test_changes_in_quick_succession_do_not_hammer_the_source() -> None: + source = FakeSource(segments=(day_prices(16, 2),), uses_action=False) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + clock.advance(seconds=10) + service.notify_changed() + assert service.due() is None # fetched 10 s ago + clock.advance(seconds=20) + assert service.due() == "changed" + + +# --- failures --------------------------------------------------------------------------- + + +async def test_failures_back_off_exponentially_and_success_resets() -> None: + source = FakeSource(error=SourceUnavailableError("down")) + service, clock = make(source, local(16, 10, 0)) + first = await service.refresh("initial") + assert first is not None + assert not first.ok + assert first.error is not None + assert service.due() is None + clock.advance(minutes=5) + assert service.due() == "initial" + await service.refresh("initial") + clock.advance(minutes=9) + assert service.due() is None # second failure: 10 minutes + clock.advance(minutes=1) + assert service.due() == "initial" + source.error = None + source.segments = (day_prices(16, 2),) + ok = await service.refresh("initial") + assert ok is not None + assert ok.ok + assert service.report().freshness.last_error is None + assert service.next_refresh() == clock.now + H + + +async def test_back_off_is_capped_at_one_hour() -> None: + source = FakeSource(error=MalformedPayloadError("bad")) + service, clock = make(source, local(16, 10, 0)) + for _ in range(10): + await service.refresh("retry") + clock.advance(hours=2) + assert service._state.retry_at is not None + assert service._state.retry_at - (clock.now - timedelta(hours=2)) == H + + +async def test_a_failure_keeps_the_good_data_and_reports_the_error_key() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.error = MalformedPayloadError("bad", attribute="prices") + clock.advance(hours=1) + await service.tick() + report = service.report(24) + assert report.quality.known_slots == report.quality.slots # still served + assert report.freshness.last_error is not None + assert report.freshness.last_error.key == "tariff.error.malformed_payload" + assert report.freshness.last_error.args == {"attribute": "prices"} + assert report.freshness.status == "stale" + + +async def test_an_empty_answer_never_replaces_good_data() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.segments = () + clock.advance(hours=1) + result = await service.tick() + assert result is not None + assert not result.ok + assert service.report(24).quality.known_slots > 0 + + +async def test_a_throttled_call_is_not_a_failure() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.error = SourceThrottledError(40.0) + clock.advance(hours=1) + result = await service.tick() + assert result is not None + assert result.throttled + assert service._state.failures == 0 + assert service.report().freshness.last_error is None + assert service.next_refresh() == clock.now + timedelta(seconds=40) + clock.advance(seconds=39) + assert service.due() is None + clock.advance(seconds=1) + assert service.due() == "retry" + + +async def test_an_unexpected_exception_becomes_a_failure_not_a_crash() -> None: + source = FakeSource(error=RuntimeError("boom")) + service, _ = make(source, local(16, 10, 0)) + result = await service.refresh() + assert result is not None + assert not result.ok + assert result.error is not None + assert result.error.key == "tariff.error.action_failed" + + +async def test_reset_backoff_after_reconnect() -> None: + source = FakeSource(error=SourceUnavailableError("down")) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + service.reset_backoff() + assert service.due() == "initial" + clock.advance(seconds=1) + assert service.report().freshness.last_error is not None # never succeeded: the error stays + + +async def test_a_refresh_in_progress_blocks_a_second_one() -> None: + gate = asyncio.Event() + + class Slow(FakeSource): + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: + await gate.wait() + return await super().fetch_segments(window, now) + + source = Slow(segments=(day_prices(16, 2),)) + service, _ = make(source, local(16, 10, 0)) + first = asyncio.create_task(service.refresh("initial")) + await asyncio.sleep(0) + assert await service.refresh("forced") is None + gate.set() + result = await first + assert result is not None + assert result.ok + + +# --- merging and serving ---------------------------------------------------------------- + + +async def test_slots_beyond_the_new_data_are_kept_when_a_source_forgets_tomorrow() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.segments = (hourly(local(16, 0), [0.40] * 24),) # today only, new values + clock.advance(hours=1) + await service.refresh() + report = service.report(48) + assert report.quality.has_tomorrow + prices = service.prices(48).import_price.values + assert prices[0] == 0.40 # new data wins where it has data + assert prices[-1] == 0.30 # tomorrow comes from the earlier fetch + + +async def test_the_series_is_at_least_24_hours_and_ends_with_the_known_prices() -> None: + now = local(16, 10, 7) + source = FakeSource(segments=(hourly(local(16, 10), [0.3] * 12),)) # 12 h known + service, _ = make(source, now) + await service.refresh("initial") + short = service.prices(48) + assert ( + len(short) == 24 * 4 + 1 + ) # 24 h from the quarter hour of "now" (10:00 -> 10:00 next day, +1) + assert short.import_price.values[: 12 * 4].count(None) == 0 + assert short.import_price.values[12 * 4 :].count(None) == len(short) - 12 * 4 + source.segments = (hourly(local(16, 10), [0.3] * 36),) + await service.refresh() + assert len(service.prices(48)) == 36 * 4 + assert len(service.prices(30)) == 30 * 4 + 1 # capped by the request + assert service.prices(48).step == Q + + +async def test_fixed_prices_fill_the_whole_request() -> None: + service, _ = make(FixedPriceSource(price=0.31), local(16, 10, 7)) + await service.refresh("initial") + out = service.prices(48) + assert len(out) >= 192 + assert set(out.import_price.values) == {0.31} + assert out.export_price is not None + assert set(out.export_price.values) == {0.08} + + +async def test_prices_before_any_fetch_are_unknown() -> None: + service, _ = make(FakeSource(), local(16, 10, 0)) + out = service.prices(48) + assert len(out) == 24 * 4 + assert set(out.import_price.values) == {None} + assert service.report().freshness.status == "missing" + assert service.report().freshness.next_refresh_at is not None + + +# --- no known value, partial data, overlapping tails (review M2, M3) -------------------- + + +def all_unknown(start: datetime, hours: int) -> PriceSeries: + return hourly(start, [None] * hours) + + +async def test_a_fetch_without_any_known_price_is_a_failure_and_keeps_good_data() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) # 48 good hours + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.segments = (all_unknown(local(16, 0), 48),) + clock.advance(hours=1) + result = await service.tick() + assert result is not None + assert not result.ok + after = service.prices(48) + known = [v for v in after.import_price.values if v is not None] + assert known + assert set(known) == {0.30} + assert len(known) >= 36 * 4 # the 48 good hours are still served + assert service.report(48).freshness.last_error is not None + + +async def test_unknown_slots_of_a_fetch_are_filled_from_the_earlier_data_and_reported() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + values: list[float | None] = [0.40] * 48 + values[14:18] = [None] * 4 # 14:00-18:00 missing in the new answer + source.segments = (hourly(local(16, 0), values),) + clock.advance(hours=1) + await service.refresh() + report = service.report(48) + assert report.quality.carried_slots == 4 + by_hour = {s.start.astimezone(BERLIN).hour: s.import_price for s in report.slots[:40]} + assert by_hour[15] == 0.30 # carried over + assert by_hour[12] == 0.40 # new data wins + + +async def test_the_old_tail_starts_at_the_next_whole_old_slot_when_the_grids_differ() -> None: + """M3: 60-minute old data, 15-minute new data ending inside an hour must not overlap.""" + source = FakeSource(segments=(hourly(local(16, 0), [0.30] * 48),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + start = local(16, 10).astimezone(UTC) + quarter = prices_q(start, 15) # 10:00-13:45: ends inside the 13:00 hour + source.segments = (quarter,) + clock.advance(hours=1) + result = await service.refresh() + assert result is not None + assert result.ok + out = service.prices(48) + at = { + out.import_price.slot_start(i).astimezone(BERLIN).strftime("%H:%M"): v + for i, v in enumerate(out.import_price.values) + if out.import_price.slot_start(i).astimezone(BERLIN).day == 16 + } + assert at["13:30"] == 0.55 # the new data + # 13:45-14:00 is covered by neither (the old hour is not cut), 14:00 on is old data again + assert at["13:45"] is None + assert at["14:00"] == 0.30 + assert service.report(48).freshness.last_error is None + + +def prices_q(start: datetime, count: int) -> PriceSeries: + series = TimeSeries(start=start, step=Q, values=(0.55,) * count, unit="currency/kWh") # type: ignore[arg-type] + return PriceSeries(source_id="fake", price_includes="all_in", import_price=series) + + +async def test_a_storing_error_in_the_series_assembly_does_not_escape( + monkeypatch: pytest.MonkeyPatch, +) -> None: + store = Store() + service, _ = make(FakeSource(segments=(day_prices(16, 2),)), local(16, 10, 0), store=store) + + def boom(_now: datetime) -> None: + msg = "assembly bug" + raise ValueError(msg) + + monkeypatch.setattr(service, "_trimmed", boom) + result = await service.refresh("initial") + assert result is not None + assert result.ok # prices are served; only the storing failed + assert store.written == [] + + +# --- report ----------------------------------------------------------------------------- + + +async def test_report_describes_source_formula_rule_and_freshness() -> None: + from suncore.core.tariff import PriceFormula # noqa: PLC0415 + + source = FakeSource( + segments=(hourly(local(16, 0), [0.10, -0.05] * 36),), price_includes="spot_only" + ) + spot = PriceSeries( + source_id="fake", price_includes="spot_only", import_price=source.segments[0].import_price + ) + source.segments = (spot,) + clock = Clock(local(16, 10, 7)) + plan = TariffPlan( + source=source, # type: ignore[arg-type] + export_tariff=FIXED_EXPORT, + negative_rule=NegativePriceRule.NO_REMUNERATION, + tz=BERLIN, + currency="EUR", + formula=PriceFormula(grid_fee=0.1, vat_pct=19), + ) + service = TariffService(plan, clock=clock) + await service.refresh("initial") + report = service.report(24) + assert report.unit == "currency/kWh" + assert report.step_min == 15 + info = report.source + assert info.import_source_id == "fake" + assert info.import_kind == "dynamic" + assert info.source_price_includes == "spot_only" + assert info.price_includes == "all_in" + assert info.formula_applied + assert info.export_kind == "fixed" + assert info.negative_price_rule == "no_remuneration" + assert info.export_zeroed_slots > 0 + assert info.native_step_min == 60 + assert info.currency == "EUR" + assert report.freshness.status == "fresh" + assert report.freshness.fetched_at == clock.now + assert report.freshness.age_s == 0 + assert report.freshness.known_until == local(16, 0).astimezone(UTC) + 72 * H + assert report.quality.has_tomorrow + assert report.slots[0].start == local(16, 10).astimezone(UTC) + zero = [s for s in report.slots if s.export_price == 0.0] + assert zero + assert all(s.import_price is not None for s in zero) + + +async def test_freshness_becomes_stale_with_age_or_a_missing_current_slot() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make( + source, local(16, 10, 0), settings=ServiceSettings(refresh_interval_s=3600) + ) + await service.refresh("initial") + assert service.report().freshness.status == "fresh" + source.error = SourceUnavailableError("down") + clock.advance(hours=2, minutes=1) + await service.tick() + assert service.report().freshness.status == "stale" + clock.now = local(18, 0) # the prices ended + assert service.report().freshness.status == "stale" + + +async def test_report_counts_dropped_points() -> None: + from suncore.tariff.parse import ParseReport # noqa: PLC0415 + + class Reporting(FakeSource): + async def fetch_segments( + self, + window: TimeRange, # noqa: ARG002 + now: datetime, # noqa: ARG002 + ) -> SourceData: + return SourceData( + segments=self.segments, + report=ParseReport(points=24, unreadable_values=2, duplicates=1, overlaps=3), + ) + + service, _ = make(Reporting(segments=(day_prices(16, 2),)), local(16, 10, 0)) + await service.refresh("initial") + assert service.report().quality.dropped_points == 6 + + +# --- export wiring ---------------------------------------------------------------------- + + +async def test_tiered_export_is_resolved_with_the_plant_size_at_construction() -> None: + tiered = ExportTariff( + kind="tiered", tiers=(ExportTier(up_to_kwp=10, price=0.08), ExportTier(price=0.07)) + ) + service, _ = make(FixedPriceSource(price=0.3), local(16, 10, 0), export=tiered, kwp=17.0) + await service.refresh("initial") + out = service.prices(24) + assert out.export_price is not None + assert out.export_price.values[0] == pytest.approx((10 * 0.08 + 7 * 0.07) / 17) + with pytest.raises(ExportConfigError): + make(FixedPriceSource(price=0.3), local(16, 10, 0), export=tiered, kwp=None) + + +# --- storing ---------------------------------------------------------------------------- + + +async def test_prices_are_stored_trimmed_to_the_known_range_and_only_when_changed() -> None: + store = Store() + source = FakeSource(segments=(hourly(local(16, 10), [0.3, 0.31, 0.32]),)) + service, clock = make(source, local(16, 10, 7), store=store) + await service.refresh("initial") + (written,) = store.written + assert written.source_id == "fake" + assert written.start == local(16, 10).astimezone(UTC) + assert written.import_price.values == (0.3,) * 4 + (0.31,) * 4 + (0.32,) * 4 + assert written.export_price is not None + assert set(written.export_price.values) == {0.08} + clock.advance(minutes=1) + await service.refresh() + assert len(store.written) == 1 # identical: not written again + source.segments = (hourly(local(16, 10), [0.3, 0.31, 0.33]),) + await service.refresh() + assert len(store.written) == 2 + + +async def test_a_failing_store_does_not_fail_the_refresh() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, _ = make(source, local(16, 10, 0), store=Store(fail=True)) + result = await service.refresh("initial") + assert result is not None + assert result.ok + + +async def test_nothing_is_stored_without_prices() -> None: + store = Store() + service, _ = make( + FakeSource(segments=(hourly(local(1, 0), [0.3]),)), local(16, 10, 0), store=store + ) + await service.refresh("initial") + assert store.written == [] # the only price lies in the past + + +# --- listeners, watch, run -------------------------------------------------------------- + + +async def test_listeners_hear_about_new_prices_and_can_be_removed() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + heard: list[int] = [] + + def bad() -> None: + msg = "listener bug" + raise RuntimeError(msg) + + remove = service.add_listener(lambda: heard.append(1)) + service.add_listener(bad) + await service.refresh("initial") + assert heard == [1] + remove() + remove() # idempotent + clock.advance(hours=1) + await service.refresh() + assert heard == [1] + + +def test_watched_entities() -> None: + service, _ = make(FakeSource(watched_entities=("sensor.a",)), local(16, 10, 0)) + assert service.watched_entities == ("sensor.a",) + assert not service.watched_entities_isdisjoint(["sensor.b", "sensor.a"]) + assert service.watched_entities_isdisjoint(["sensor.b"]) + + +async def test_run_ticks_until_cancelled_and_survives_a_crashing_tick( + monkeypatch: pytest.MonkeyPatch, +) -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + sleeps: list[float] = [] + + async def sleep(seconds: float) -> None: + sleeps.append(seconds) + clock.advance(seconds=seconds) + if len(sleeps) == 2: + monkeypatch.setattr(service, "tick", crash) + if len(sleeps) >= 4: + raise asyncio.CancelledError + + async def crash() -> None: + msg = "tick bug" + raise RuntimeError(msg) + + with pytest.raises(asyncio.CancelledError): + await service.run(sleep, poll_s=30.0) + assert sleeps == [30.0] * 4 + assert ( + len(source.calls) == 1 + ) # the first tick fetched, the later ones found nothing due / crashed + + +def test_settings_have_a_floor_below_the_action_limiter() -> None: + low = ServiceSettings( + refresh_interval_s=1, retry_interval_s=1, tomorrow_poll_s=1, tomorrow_after=time(12) + ) + assert (low.refresh_interval_s, low.retry_interval_s, low.tomorrow_poll_s) == (60.0, 60.0, 60.0) + + +async def test_tomorrow_is_covered_at_the_end_of_the_market_day_west_of_the_market() -> None: + """Review M4: Nord Pool ends at CET midnight, an hour before London's; it must terminate.""" + from zoneinfo import ZoneInfo # noqa: PLC0415 + + london = ZoneInfo("Europe/London") + now = datetime(2026, 10, 16, 14, 0, tzinfo=london) + cet_end = datetime(2026, 10, 18, 0, 0, tzinfo=BERLIN) # end of tomorrow in CET + start = datetime(2026, 10, 16, 13, 0, tzinfo=london) + count = int((cet_end - start) / H) + for market, expected in ((BERLIN, True), (None, False)): + source = FakeSource(segments=(hourly(start, [0.3] * count),), delivery_tz=market) + plan = TariffPlan( + source=source, # type: ignore[arg-type] + export_tariff=FIXED_EXPORT, + negative_rule=NegativePriceRule.NONE, + tz=london, + currency="EUR", + ) + service = TariffService(plan, clock=Clock(now)) + await service.refresh("initial") + assert service.report(48).quality.has_tomorrow is expected + + +async def test_report_says_when_a_spot_price_has_no_formula() -> None: + from suncore.core.tariff import PriceFormula # noqa: PLC0415 + + source = FakeSource(segments=(day_prices(16, 2),), price_includes="spot_only") + spot = PriceSeries( + source_id="fake", price_includes="spot_only", import_price=day_prices(16, 2).import_price + ) + source.segments = (spot,) + for formula, missing, includes in ( + (None, True, "spot_only"), + (PriceFormula(grid_fee=0.1), False, "all_in"), + ): + plan = TariffPlan( + source=source, # type: ignore[arg-type] + export_tariff=FIXED_EXPORT, + negative_rule=NegativePriceRule.NONE, + tz=BERLIN, + currency="EUR", + formula=formula, + ) + service = TariffService(plan, clock=Clock(local(16, 10, 0))) + await service.refresh("initial") + report = service.report(24) + assert report.formula_missing is missing + assert report.price_includes == includes diff --git a/tests/tariff/test_sources.py b/tests/tariff/test_sources.py new file mode 100644 index 0000000..512a3dc --- /dev/null +++ b/tests/tariff/test_sources.py @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Fixed and HT/NT sources, the unit helpers.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta + +import pytest + +from suncore.core.series import PLANNING_STEP, TimeRange +from suncore.core.tariff import TouPeriod, TouTariff, TouWindow +from suncore.tariff import FixedPriceSource, TouPriceSource +from suncore.tariff.units import ( + divisor_to_kwh, + energy_scale, + normalise_price_unit, + resolve_value_unit, +) +from tests.tariff.helpers import BERLIN, NOW + +H = timedelta(hours=1) + + +def rng(start: datetime, hours: float) -> TimeRange: + return TimeRange(start=start, end=start + timedelta(hours=hours)) + + +async def test_fixed_price_is_constant_all_in_on_the_planning_grid() -> None: + source = FixedPriceSource(price=0.31) + data = await source.fetch_segments(rng(NOW, 24), NOW) + (segment,) = data.segments + assert segment.price_includes == "all_in" + assert segment.step == PLANNING_STEP + assert segment.start == datetime(2026, 10, 16, 8, 0, tzinfo=UTC) # 10:07 local floors to 10:00 + assert len(segment.import_price) == 96 + 1 # the partial first quarter hour is included + assert set(segment.import_price.values) == {0.31} + assert source.kind == "fixed" + assert not source.uses_action + assert source.watched_entities == () + assert (await source.fetch(rng(NOW, 2))).import_price.values[0] == 0.31 + + +TOU = TouTariff( + base_price=0.35, + periods=(TouPeriod(window=TouWindow(start="22:00", end="06:00"), price=0.25),), +) + + +async def test_tou_prices_follow_the_local_windows() -> None: + source = TouPriceSource(tou=TOU, tz=BERLIN) + start = datetime(2026, 10, 16, 21, 0, tzinfo=BERLIN) + data = await source.fetch_segments(rng(start, 2), start) + values = data.segments[0].import_price.values + assert values == (0.35,) * 4 + (0.25,) * 4 # 22:00 local is the first NT slot + assert (await source.fetch(rng(start, 2))).import_price.values == values + + +@pytest.mark.parametrize( + ("day", "local_hours"), [((2026, 3, 29), 23), ((2026, 10, 25), 25), ((2026, 10, 16), 24)] +) +async def test_tou_on_dst_days_counts_real_hours( + day: tuple[int, int, int], local_hours: int +) -> None: + """NT 22:00-06:00 on the 25 h day: 00:00-06:00 is seven real hours, 22:00-24:00 two.""" + start = datetime(*day, tzinfo=BERLIN) + end = datetime(*day, tzinfo=BERLIN) + timedelta(days=1) + window = TimeRange(start=start.astimezone(UTC), end=end.astimezone(UTC)) + assert window.duration == timedelta(hours=local_hours) + data = await TouPriceSource(tou=TOU, tz=BERLIN).fetch_segments(window, start) + values = data.segments[0].import_price.values + assert len(values) == local_hours * 4 + nt_hours = {23: 5 + 2, 25: 7 + 2, 24: 6 + 2}[local_hours] # 00:00-06:00 is 5, 7 or 6 hours + assert values.count(0.25) == nt_hours * 4 + + +def test_unit_helpers() -> None: + assert normalise_price_unit("€/kWh") == "EUR/kWh" + assert normalise_price_unit("£/kWh") == "GBP/kWh" + assert normalise_price_unit("EUR/MWh") == "EUR/MWh" + assert normalise_price_unit(" CHF/kWh ") == "CHF/kWh" + assert resolve_value_unit("{currency}/MWh", "SEK") == "SEK/MWh" + assert divisor_to_kwh("EUR/kWh") == 1.0 + assert divisor_to_kwh("{currency}/MWh") == 1000.0 + assert 45.5 / divisor_to_kwh("EUR/MWh") == 0.0455 + assert energy_scale("EUR/MWh") == "MWh" + assert energy_scale("EUR/kWh") == "kWh" + assert energy_scale("EUR/m3") is None + with pytest.raises(ValueError, match="not a price unit"): + divisor_to_kwh("kWh") diff --git a/tests/templates/test_models.py b/tests/templates/test_models.py index a8fd44b..619a14c 100644 --- a/tests/templates/test_models.py +++ b/tests/templates/test_models.py @@ -217,7 +217,11 @@ def test_action_allowlist_refuses_unknown_service_with_reason_key() -> None: doc["price_series"].update(domain="light", service="turn_on") with pytest.raises(ValidationError, match=ERR_ACTION_NOT_ALLOWED): TEMPLATE_ADAPTER.validate_python(doc) - for domain, service in (("tibber", "get_prices"), ("weather", "get_forecasts")): + for domain, service in ( + ("tibber", "get_prices"), + ("nordpool", "get_prices_for_date"), + ("weather", "get_forecasts"), + ): doc["price_series"].update(domain=domain, service=service) assert TEMPLATE_ADAPTER.validate_python(doc).kind == "tariff" @@ -287,3 +291,78 @@ def test_attribute_series_mapping_shape() -> None: nested["series"]["list_path"] = "result.watts" assert TEMPLATE_ADAPTER.validate_python(nested).kind == "forecast" _bad(nested, lambda d: d["series"].update(list_path="result..watts")) + + +def test_action_series_per_date_requests_and_user_parameters() -> None: + """WP4: Nord Pool style action - one call per delivery date, request fields from the user.""" + doc = tariff_doc() + series = doc["price_series"] + series.update(domain="nordpool", service="get_prices_for_date", response_path="*") + series.pop("start_field") + series.pop("end_field") + series.update( + date_field="date", + params=[ + { + "name": "config_entry", + "required": True, + "description": "template.acme.dynamic.param.entry", + }, + { + "name": "areas", + "required": False, + "description": "template.acme.dynamic.param.areas", + }, + ], + ) + series["fields"].update(end_field="end", value_unit="{currency}/MWh") + doc["price_unit"] = "{currency}/MWh" + template = TEMPLATE_ADAPTER.validate_python(doc) + assert isinstance(template, TariffTemplate) + assert template.message_keys() == [ + "template.acme.dynamic.name", + "template.acme.dynamic.role.price", + "template.acme.dynamic.param.entry", + "template.acme.dynamic.param.areas", + ] + _bad(doc, lambda d: d["price_series"].update(start_field="start")) # date XOR start/end + _bad(doc, lambda d: d["price_series"].update(end_field="end")) + _bad( + doc, + lambda d: d["price_series"]["params"].append( + {"name": "areas", "required": False, "description": "template.acme.dynamic.param.x"} + ), + ) + _bad( + doc, + lambda d: d["price_series"]["params"].append( + {"name": "date", "required": False, "description": "template.acme.dynamic.param.x"} + ), + ) + _bad(doc, lambda d: d["price_series"].update(params=[{"name": "x", "description": "bad key"}])) + _bad(doc, lambda d: d["price_series"].update(response_path="*.")) + + +def test_the_slot_end_field_belongs_to_lists_not_to_mapping_attributes() -> None: + doc = tariff_doc() + doc["price_series"]["fields"]["end_field"] = "end" + assert TEMPLATE_ADAPTER.validate_python(doc).kind == "tariff" + mapping = forecast_doc() + mapping["series"].update(attribute="wh_hours", shape="mapping") + mapping["series"]["fields"] = {"value_unit": "Wh", "end_field": "end"} + mapping["resolution_min"] = 60 + _bad(mapping, lambda d: d["series"].update(shape="mapping")) # end_field on a mapping + + +def test_date_zone_of_a_per_date_action() -> None: + doc = tariff_doc() + series = doc["price_series"] + series.update(domain="nordpool", service="get_prices_for_date", response_path="*") + series.pop("start_field") + series.pop("end_field") + series["date_field"] = "date" + series["date_tz"] = "Europe/Berlin" + assert TEMPLATE_ADAPTER.validate_python(doc).price_series.date_tz == "Europe/Berlin" # type: ignore[union-attr] + _bad(doc, lambda d: d["price_series"].update(date_tz="Mars/Olympus")) + _bad(doc, lambda d: d["price_series"].update(date_tz="CET")) + _bad(doc, lambda d: d["price_series"].pop("date_field")) # a zone needs a date field