Predictive Advisor

The Predictive Advisor is a strictly read-only analysis and recommendation layer for your heat pump. It observes the measured data, learns how your plant behaves and turns that into explainable recommendations — it never changes anything on the heat pump by itself.

The Navigator controller remains the leading regulator at all times. The advisor advises; every change to the plant is your explicit action on the regular control entities.

The advisor is part of the Smart Energy and Comfort profile. It works entirely locally; no data leaves your Home Assistant.

Enable, disable and what it needs

• Where: integration → Configure → Presentation and additional features → Enable predictive advisor (also part of the guided setup as its own page). On by default with the Smart Energy & Comfort profile.
• Turning it off removes every advisor_* entity after a reload; the collected statistics are kept and return when you re-enable it.
• No AI required. Everything is deterministic statistics — baselines, regressions and window searches — computed locally on your Home Assistant. It does not use, need or offer any cloud or LLM. The Experimental AI plant adviser is a completely separate feature; the predictive advisor works without it.
• Optional inputs: a weather entity (already used by the weather advice), a PV forecast sensor and a dynamic electricity price sensor. Every one of them is optional — missing inputs simply disable the affected recommendation, nothing is invented.

After installing an update you will find a one-time notice in Settings → Repairs ("What's new since 0.20.1") summarizing what was added — dismiss it there once you have seen it. It appears exactly once per installed update: never on a fresh installation, never again on restarts or reloads, and only again when the next update is installed.

Room temperature without a wired sensor

Circuits that have no room sensor wired to the Navigator report uninitialized memory on the hc_x_room_temp register (observed as -327.33 on a Navigator 2.0, #504). The advisor ignores such values. If the integration options enable the predictive advisor, the options walk offers one read-only Home Assistant temperature sensor per heating circuit as the advisor's room temperature source. Nothing is written to the heat pump; the sensor value feeds the advisor's models, data quality and capability detection under the same plausibility range (0-50 °C) as the register. A configured source that is unavailable counts as an unavailable sample - it never falls back to the garbage register value.

Entities

Shared evidence and optimization review

The Predictive Advisor, measurement reports and local Assist share one numerical history and the same period comparisons. The history collects while either the Predictive Advisor or experimental AI adviser is enabled; it needs no model or cloud provider. It retains up to 28 days, capped independently at 4 MiB by removing the oldest details. Collection stops on disable/reload; stored data is retained. There is no Recorder backfill, and existing AI report history remains separate.

• Advisor changes (advisor_changes) counts changed comparison metrics; attributes explain energy, COP, compressor starts, DHW operating-time share, room deviation, weather context and missing evidence. Unknown means a suitable comparison is unavailable; zero means no marked change in comparable windows.
• Advisor optimization review (advisor_optimization_review) records observed heating-curve readback changes and evaluates the latest stable change. This cannot establish who made a change or whether it was manual. It never writes.
• Recommendation attributes include localized observations, supporting reasons, current/suggested values, confidence interpretation, missing evidence and a first check. Confidence is not a probability that the plant has a defect.
• Since 0.27.0-b1 the recommendation titles are localized too: the sensor attributes and local Assist render them in German or English following the Home Assistant language, with German decimal commas. The title field itself stays the documented English data field — events, stored records and diagnostics remain language-independent, and recommendations persisted before the update keep working and render their stored title.
• Regenerate the plant dashboard to add the available Advisor view and explanation cards. Existing dashboards are not modified automatically.

Review needs 72 hours before the change and 72 hours after a six-hour settling period. Both windows need at least 80% observed energy-counter coverage. Only pure heating intervals are compared within two-degree outdoor-temperature bins: at least six matched hours and 60% matching of the larger heating history are required. Changed room targets, missing comfort readings or overlapping changes leave the result open. A COP difference of at least 5% is reported as an observed change; worsening absolute room deviation by more than 0.3 K or increasing starts by more than both 0.2 per hour and 20% prevents a simple improvement verdict. These are conservative descriptive thresholds, not statistical significance or proof of cause. Other influences such as occupancy and solar gains remain unknown.

Assist examples: What changed?, Why is consumption higher?, How is cycling developing?, What data is missing?, Did it help?. The last question reviews the latest recorded heating-curve change; it does not change settings or acknowledge a recommendation as applied.

Mapped room sensors are converted from Fahrenheit or Kelvin to Celsius before quality checks and model fitting; a missing unit retains the Celsius assumption. Unavailable or mismatched mapped sources do not fall back to register values. Failed coordinator updates break learning intervals instead of repeating cached measurements. Only exact heating or hot-water modes feed dedicated COP domains.

Operating explanations prioritize explicit controller demand over temperature inferences. A cool DHW tank alone does not override reported heating operation, and a tank already above target is described accordingly.

The 24-hour heat-demand estimate requires 24 distinct consecutive forecast hours; short or gapped forecasts do not produce a full-day estimate. Warm hours cannot cancel heating demand in cold hours. PV period energy is split at hour boundaries and duplicate timestamps are counted once. PV recommendations describe forecast generation, not confirmed surplus after household consumption.

The local Assist agent uses these corrected operation explanations. It accepts subzero outdoor temperatures, identifies instantaneous COP explicitly, and does not claim a fault-free plant when alarm readings are missing. Failed updates produce an unavailable-state explanation instead of cached live values.

All entities appear under the Smart profile and become meaningful as the advisor collects data. Sensors that depend on not-yet-learned models stay unavailable instead of guessing.

Where the external inputs come from

• Weather: the existing Weather entity option (hourly forecast via weather.get_forecasts).
• PV forecast: optional sensor in the options (Predictive advisor PV forecast sensor (optional)). The field may be left empty — the advisor works fully without it; the sensor is only the basis for the PV-based hot-water window recommendations. PVForecast-style detailed_forecast attributes and Solcast-style forecast lists are understood, and a sensor of the core Forecast.Solar integration is read through its get_forecast service (hourly wh_period) — its own sensors carry no hourly attributes.
• Electricity price: the existing Dynamic electricity price sensor option; future hourly prices are read from common attribute shapes (today/tomorrow/data/prices lists).

Missing or unparsable inputs leave the affected recommendation out — the advisor never falls back to invented numbers.

Events

Every new, changed or acknowledged recommendation fires an idm_advisor_recommendation event you can use in automations:

event_type: idm_advisor_recommendation
data:
  action: new          # new | updated | status
  id: heating_curve_a_20261007
  category: heating_curve
  severity: info
  confidence: 0.91
  confidence_level: very_high
  current_value: 0.35
  recommended_value: 0.32
  reasons:
    - room_temperature_above_target
    - flow_temperature_above_estimated_requirement

How confidence works

Each recommendation carries a confidence value with four levels — low, medium, high, very high — instead of pseudo-exact percentages. The score is a documented formula: 60 % observation coverage (complete after 14 days) plus 40 % share of usable samples. Bad data (unavailable, implausible or frozen sensors) lowers the confidence instead of producing recommendations.

Data quality

Before anything is analyzed, every input is classified sample by sample: unavailable, implausible (outside the documented range), frozen (a nonzero power or flow reading that has not moved for three hours) or usable. Recommendations are never built on bad data.

Building-model learning

Heat loss and optimal flow temperature learn only during exclusive space heating (hp_operating_mode == 1) with an actively heating circuit. An explicit circuit active mode must be heating; if it is absent, a positive circuit flow setpoint is required. DHW, cooling, defrost, mixed or unknown modes and inactive circuits cannot feed these regressions. Heat loss uses a room temperature from an active heating circuit. General operating metrics and COP learning continue independently.

After upgrading from the earlier learning logic, the heat-loss and flow-curve regressions and their derived thermal-capacity estimate restart once: old aggregates cannot distinguish space heating from DHW. Those sensors remain unavailable until enough new heating samples exist. Other analytics, including daily baselines, COP data and cooldown observations, are preserved.

What the advisor will never do

• Change setpoints, heating curves, modes, schedules or power limits
• Activate PV boost or priority charging on its own
• Write registers, coils or web settings
• "Apply" a recommendation without your explicit confirmation

Accepting a recommendation in a future UI records only that you consider it sensible. Applying a value remains a separate, confirmed user action, with the previous value journalled so it can be restored.