[MikeBishop]

This change does options 1 and 2 from #755. Option 3, making Static and aWATTar leave out a price they don't know yet, waits on the discussion there, so this is a draft until that settles.

Shared base. ForecastingPricing lives in Pricing/Forecast.py, next to the window helpers it uses. It reads the module's config section (enabled, cheapWindow) and provides forecastMinPrice/forecastMaxPrice, cheapWindowStart, cheapWindowActive, getPriceForecast and getCheapestWindow. cheapWindowStart goes through latchedWindow, so a module can't search again mid-window and cut charging short. A module supplies its prices, updateForecast() to refresh, and _forecast(), which returns (slots, now, tz) without blocking. It also sets slotMinutes (default 30), so the base assumes no slot length and no refresh cadence. Amber, Tesla and aWATTar now use it.

Changes to Amber's behaviour:

• forecastMinPrice/forecastMaxPrice are absent until the first forecast arrives, as Tesla's already were, so the base carries the "absent, not 0" rule forward.
• The window is worked out when policy reads it, from the cached forecast. Reading it never fetches, because policy reads these values on the main loop. Only updateForecast fetches, from the background task or the HTTP API.
• getPriceForecast always fetches 48 hours. Before, a ?hours=12 call could leave only 12 hours cached until the next fetch.

aWATTar. The market-data request it already makes returns the next 24 hours of prices, so aWATTar now uses the base too, with no extra requests: still at most one call per 15 minutes, within aWATTar's 100 a day. Its slots are an hour long; the API doesn't document this, so the module works the length out from the data, and 15-minute slots work too. The current price now comes from the slot covering the current time. It still reports 0 before its first price arrives; that is option 3.

One docs page. docs/modules/Pricing.md covers what the modules share: the values policy can read, cheapest-window charging, what each module reports before it has a price, and the HTTP endpoints. The page notes that Static, aWATTar and Amber currently report 0 for a price they don't know yet. Each module's page keeps only its own setup, forecast horizon and FAQ, and the README now lists the Pricing modules. The page also corrects one claim: an unknown price fails safe only in gt/gte/lt/lte comparisons. With ne, it matches.

Cheapest window kept inside its hours. cheapWindow.endHour is documented as the hour the window must finish by, but the search checked only the hour a window starts in. With {"hours": 5, "startHour": 22, "endHour": 7} it could pick 06:00–11:00, which on Amber's typical day (cheapest mid-morning, with solar) charges outside the night the user set. Every slot of the window must now fall in the range. With startHour alone, only the start is checked, so a window can still run past midnight. This was in the original Amber forecasting code, which is not in a release yet.

Evidence: full unit suite (pytest tests --ignore=tests/API --ignore=tests/integration --ignore=tests/scenarios): 2672 passed. New tests check that Amber's attribute reads never fetch, that its price range is absent before the first forecast, and that aWATTar builds its forecast and finds windows over hourly and 15-minute slots, and that a window ends by endHour. Not run against the live aWATTar or Amber APIs.

Changelog: none (forecasting and the Pricing module type are not in a release yet)

🤖 Generated with Claude Code