Files
cantabile-ha-addons/src/edge/cantabile_edge/guard.py
T

212 lines
10 KiB
Python

# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""The actuation guard: every action the agent would take goes through
check() first, and only an allowed one becomes a Home Assistant service
call (executor.py). In this order:
0. policy the device's protection (policy.py): never
anything on a sealed device, never off on a protected one,
whatever the command's level
0b. switchover a thermostat that heats and cools: only its active control
(heating or cooling, switchover.py) may act
1. mode only in `auto` (shadow and advisory never act)
2. consent the owner's for the site ("control" in consent.json) and the
control's own (mapping v3), both off by default
3. allow-list the control's own entities, with the service its kind uses
4. bounds inside the effective floors and limits (limits.py: the
device's range, the owner's, the building's, the cloud's, the
grid operator's)
5. override the owner changed it by hand: the agent keeps off it for
override_hold_s (flexible), unless a binding or emergency
command says otherwise (3b command levels)
6. cycling a switch stays on/off for its minimum time (anti-cycling; only
for equipment that wears from short cycles: heating, cooling)
7. rate at most max_actions_per_hour per control; a cover moves at
most once in its params.min_move_s (default 30 min)
Emergency commands skip 5-7 (nobody overrides them; device safety and the
bounds still hold). Binding ones skip 5: the flat cannot lift them, only the
building or the cloud. Every refusal has a reason, and is reported once per
control and reason per hour (not every minute).
"""
import time
from dataclasses import dataclass, field
LEVELS = ("plan", "flexible", "binding", "emergency") # plan: the optimiser's own
@dataclass
class Action:
control: str
channel: str # the entity role (charge_from_grid, setpoint, climate, switch, current, cover)
entity: str
domain: str
service: str
data: dict
value: float | str # what is set (W, °C, A, %, "on"/"off"/"cool"/...)
quantity: str = "" # what bounds it (temp_c, power_w, current_a, position_pct; "" for on/off)
level: str = "plan"
why: str = ""
@dataclass
class _Track:
times: list = field(default_factory=list) # when actions were taken (rate limit)
switched: dict = field(default_factory=dict) # channel -> (time, value) of the last on/off change
commanded: dict = field(default_factory=dict) # entity -> (time, value) the agent last set
override_until: float = 0.0
override_entity: str = ""
moved: float = -1e18 # when a cover was last moved by the agent
changed: dict = field(default_factory=dict) # "mode" | "set" -> when the agent last changed it (steady.py)
# The service each channel uses, by domain: nothing else can be called.
SERVICES = {
"switch": {"turn_on", "turn_off"},
"input_boolean": {"turn_on", "turn_off"},
"number": {"set_value"},
"input_number": {"set_value"},
"climate": {"set_temperature", "set_hvac_mode"},
"cover": {"set_cover_position", "open_cover", "close_cover"},
"select": {"select_option"},
"input_select": {"select_option"},
}
class Guard:
def __init__(self, controls, consent, mode=lambda: "shadow", *, override_hold_s=7200, min_switch_s=600,
max_actions_per_hour=12, settle_s=90, clock=time.time):
self.controls = {c.id: c for c in controls}
self.consent, self.mode, self.clock = consent, mode, clock
self.hold, self.min_switch, self.max_rate, self.settle = override_hold_s, min_switch_s, max_actions_per_hour, settle_s
self.extra_limits: dict = {} # control -> quantity -> level -> (floor, limit), from commands
self.policy = None # policy.Policy: the devices' protection
self.switchover = None # switchover.Switchover: heating or cooling now
self.track: dict[str, _Track] = {}
self.events: list[dict] = [] # overrides seen (the executor reports them)
def min_switch_for(self, c) -> float:
"""Anti-cycling time for this control: the mapping's
params.min_switch_s if set; else the guard's min_switch_s for kinds
whose equipment wears from short cycles (heating, cooling: their
default is > 0), and 0 for batteries, EV chargers and covers."""
if "min_switch_s" in (c.params or {}):
return float(c.params["min_switch_s"])
from .controls import PARAMS
return float(self.min_switch) if PARAMS.get(c.kind, {}).get("min_switch_s", 0) > 0 else 0.0
def _t(self, cid) -> _Track:
return self.track.setdefault(cid, _Track())
def bounds(self, c, q):
return c.bounds(q, self.extra_limits.get(c.id))
def check(self, a: Action) -> tuple[bool, str]:
now = self.clock()
c = self.controls.get(a.control)
if c is None:
return False, "no such control"
if self.policy is not None:
why = self.policy.refuses(a, c)
if why:
return False, why
if self.switchover is not None and not self.switchover.active(c):
return False, f"{c.kind} is not active now (switchover: the thermostat's other control is)"
if self.mode() != "auto":
return False, f"mode {self.mode()}: the agent does not act"
if not self.consent.control:
return False, "the owner has not allowed control (site consent)"
if not c.consent:
return False, "no consent for this control"
if c.writable().get(a.channel) != a.entity:
return False, f"{a.entity} is not this control's {a.channel}"
if a.service not in SERVICES.get(a.domain, ()) or a.entity.split(".", 1)[0] != a.domain:
return False, f"{a.domain}.{a.service} is not allowed for {a.entity}"
if a.quantity:
b = self.bounds(c, a.quantity)
try:
v = float(a.value)
except (TypeError, ValueError):
return False, f"{a.value!r} is not a number"
if not b.holds(v):
return False, (f"{v:g} outside {b.lo:g}..{b.hi:g} {a.quantity} "
f"(floor by {b.lo_by}, limit by {b.hi_by})")
tr = self._t(c.id)
urgent = a.level == "emergency"
if now < tr.override_until and a.level not in ("binding", "emergency"):
return False, f"the owner changed {tr.override_entity} by hand: hands off until {_hhmm(tr.override_until)}"
min_switch = self.min_switch_for(c)
if not urgent and min_switch > 0 and a.quantity == "" and a.channel in tr.switched:
when, last = tr.switched[a.channel]
if last != a.value and now - when < min_switch:
return False, f"switched {last} {int(now - when)} s ago (minimum {min_switch:g} s)"
tr.times = [t for t in tr.times if now - t < 3600]
if not urgent and c.kind == "cover" and now - tr.moved < float(c.p("min_move_s")):
return False, (f"moved {int(now - tr.moved)} s ago (at most once in {float(c.p('min_move_s')):g} s)")
if not urgent and len(tr.times) >= self.max_rate:
return False, f"{len(tr.times)} actions in the last hour (at most {self.max_rate})"
return True, ""
def done(self, a: Action):
"""An action was carried out: count it, remember what was set."""
now = self.clock()
tr = self._t(a.control)
tr.times.append(now)
tr.commanded[a.entity] = (now, a.value)
c = self.controls.get(a.control)
boiler = c is not None and c.kind in ("heating", "cooling") and a.channel == "switch"
tr.changed["set" if a.quantity or boiler else "mode"] = now
if a.domain == "cover":
tr.moved = now
if a.quantity == "":
prev = tr.switched.get(a.channel)
if prev is None or prev[1] != a.value:
tr.switched[a.channel] = (now, a.value)
def expect(self, control_id: str, entity: str, value):
"""The agent wants this value and the device already has it (no
action needed): a later change by hand counts as an override, as if
the agent had set it (not counted as an action)."""
tr = self._t(control_id)
if entity not in tr.commanded:
tr.commanded[entity] = (self.clock() - self.settle, value)
def observe(self, control_id: str, entity: str, value, now: float | None = None):
"""A state change of a control's entity: if it differs from what the
agent set, and not right after the agent set it, the owner changed
it by hand."""
now = self.clock() if now is None else now
tr = self._t(control_id)
cmd = tr.commanded.get(entity)
if cmd is None:
return
when, want = cmd
c = self.controls.get(control_id)
cover = c is not None and c.kind == "cover"
if now - when < self.settle or _same(value, want, 3.0 if cover else 0.26):
return
# a shade the owner moved: off it for its own pause (params.override_hold_s)
tr.override_until = now + (float(c.p("override_hold_s")) if cover else self.hold)
tr.override_entity = entity
tr.commanded.pop(entity, None)
self.events.append({"control": control_id, "entity": entity, "value": value, "agent_set": want,
"until": int(tr.override_until), "at": int(now)})
def last_change(self, control_id: str, kind: str) -> float | None:
"""When the agent last changed a control's mode or setpoint (kind
"mode" | "set"; a boiler's on/off is its setpoint), or None."""
return self._t(control_id).changed.get(kind)
def overridden(self, control_id: str) -> bool:
return self.clock() < self._t(control_id).override_until
def _same(a, b, tol: float = 0.26) -> bool:
try:
return abs(float(a) - float(b)) < tol
except (TypeError, ValueError):
return str(a) == str(b)
def _hhmm(t: float) -> str:
return time.strftime("%H:%M UTC", time.gmtime(t))