CONTROL-001: add safe HA automation handoff

app/behavior/engine.py

@@ -12,6 +12,7 @@ from app.actuators.models import (
     BehaviorState,
     BehaviorStatus,
     ExecutionEvent,
+    RelatedAutomation,
 )
 from app.actuators.store import ActuatorStore
 from app.config import Settings
@@ -71,6 +72,10 @@ class BehaviorEngine:
                 record.behavior.model_copy(
                     update={
                         "status": BehaviorStatus.COLLECTING,
+                        "activation_ready": False,
+                        "activation_reason": (
+                            "Freigabe gesperrt: Noch kein geeigneter Kontext erkannt."
+                        ),
                         "last_trained_at": now,
                         "reason": "Noch kein geeigneter Kontext für Verhaltenslernen vorhanden.",
                     }
@@ -105,6 +110,11 @@ class BehaviorEngine:
                         "status": BehaviorStatus.COLLECTING,
                         "sample_count": 0,
                         "high_confidence_sample_count": 0,
+                        "activation_ready": False,
+                        "activation_reason": (
+                            "Freigabe gesperrt: Noch keine historischen "
+                            "Aktorhandlungen gefunden."
+                        ),
                         "patterns": [],
                         "last_trained_at": now,
                         "reason": "Noch keine historischen Aktorhandlungen gefunden.",
@@ -140,11 +150,26 @@ class BehaviorEngine:
                 "benötigten Handlungen gelernt."
             )
         )
+        activation_ready = (
+            status is BehaviorStatus.TRAINED
+            and trusted_actions >= self._settings.min_behavior_actions
+        )
+        activation_reason = (
+            "Freigabe bereit: Genügend eindeutig zugeordnete Handlungen gelernt."
+            if activation_ready
+            else (
+                "Freigabe gesperrt: "
+                f"{max(0, self._settings.min_behavior_actions - trusted_actions)} "
+                "eindeutig zugeordnete Handlungen fehlen."
+            )
+        )
         behavior = record.behavior.model_copy(
             update={
                 "status": status,
                 "sample_count": len(patterns),
                 "high_confidence_sample_count": trusted_actions,
+                "activation_ready": activation_ready,
+                "activation_reason": activation_reason,
                 "patterns": patterns[-_MAX_PATTERNS:],
                 "last_trained_at": now,
                 "reason": reason,
@@ -215,6 +240,17 @@ class BehaviorEngine:
             causal_window_seconds=self._settings.prediction_interval_seconds * 2,
             timezone_name=self._settings.timezone,
         )
+        if prediction is not None:
+            prediction = prediction.model_copy(
+                update={
+                    "execution_reason": self._prediction_execution_reason(
+                        record,
+                        actuator.state,
+                        prediction,
+                        now,
+                    )
+                }
+            )
         behavior = record.behavior.model_copy(
             update={
                 "last_evaluated_at": now,
@@ -231,7 +267,11 @@ class BehaviorEngine:
             and behavior.mode is BehaviorMode.ACTIVE
             and prediction.confidence >= self._settings.prediction_confidence
             and actuator.state != prediction.target_state
-            and self._cooldown_elapsed(behavior, now)
+            and self._cooldown_elapsed(
+                behavior,
+                now,
+                prediction.target_state,
+            )
         ):
             domain = actuator_entity_id.split(".", 1)[0]
             service = service_for_state(domain, prediction.target_state)
@@ -260,7 +300,14 @@ class BehaviorEngine:
                 )
                 behavior = behavior.model_copy(
                     update={
-                        "prediction": prediction.model_copy(update={"executed": True}),
+                        "prediction": prediction.model_copy(
+                            update={
+                                "executed": True,
+                                "execution_reason": (
+                                    f"Ausgeführt mit {prediction.confidence:.0%} Sicherheit."
+                                ),
+                            }
+                        ),
                         "last_executed_at": now,
                         "execution_events": [
                             *behavior.execution_events,
@@ -282,8 +329,71 @@ class BehaviorEngine:
                 )
         return self._save_behavior(record, behavior)
 
-    def set_active(self, actuator_entity_id: str, *, active: bool) -> ActuatorRecord:
+    def refresh_related_automations(self, actuator_entity_id: str) -> ActuatorRecord:
         record = self._store.get(actuator_entity_id)
+        related = [
+            RelatedAutomation(
+                entity_id=item.entity_id,
+                config_id=item.config_id,
+                friendly_name=item.friendly_name,
+                enabled=item.enabled,
+            )
+            for item in self._ha_reader.find_automations_for_entity(
+                actuator_entity_id
+            )
+        ]
+        behavior = record.behavior.model_copy(
+            update={"related_automations": related}
+        )
+        return self._save_behavior(record, behavior)
+
+    def set_automation_enabled(
+        self,
+        actuator_entity_id: str,
+        automation_entity_id: str,
+        *,
+        enabled: bool,
+    ) -> ActuatorRecord:
+        record = self.refresh_related_automations(actuator_entity_id)
+        if automation_entity_id not in {
+            item.entity_id for item in record.behavior.related_automations
+        }:
+            raise ValueError(
+                "Die Automation ist diesem Aktor nicht eindeutig zugeordnet."
+            )
+        self._ha_reader.call_service(
+            "automation",
+            "turn_on" if enabled else "turn_off",
+            {"entity_id": automation_entity_id},
+        )
+        related = [
+            item.model_copy(update={"enabled": enabled})
+            if item.entity_id == automation_entity_id
+            else item
+            for item in record.behavior.related_automations
+        ]
+        paused = [
+            entity_id
+            for entity_id in record.behavior.paused_automation_entity_ids
+            if entity_id != automation_entity_id
+        ]
+        behavior = record.behavior.model_copy(
+            update={
+                "related_automations": related,
+                "paused_automation_entity_ids": paused,
+            }
+        )
+        return self._save_behavior(record, behavior)
+
+    def set_active(
+        self,
+        actuator_entity_id: str,
+        *,
+        active: bool,
+        pause_matching_automations: bool = False,
+        restore_paused_automations: bool = False,
+    ) -> ActuatorRecord:
+        record = self.refresh_related_automations(actuator_entity_id)
         now = datetime.now(timezone.utc)
         if active:
             domain = actuator_entity_id.split(".", 1)[0]
@@ -293,30 +403,138 @@ class BehaviorEngine:
                 )
             if record.behavior.status is not BehaviorStatus.TRAINED:
                 raise ValueError("Das Verhaltensmodell hat noch nicht genügend Handlungen gelernt.")
-            if (
-                record.behavior.high_confidence_sample_count
-                < self._settings.min_behavior_actions
-            ):
-                raise ValueError(
-                    "Für die Freigabe fehlen noch eindeutig zugeordnete manuelle "
-                    "oder automatisierte Handlungen."
-                )
+            if not record.behavior.activation_ready:
+                raise ValueError(record.behavior.activation_reason)
             mode = BehaviorMode.ACTIVE
             approved_at = now
-            reason = "Autonomes Lernen und Schalten wurde ausdrücklich freigegeben."
+            behavior = record.behavior.model_copy(
+                update={
+                    "mode": mode,
+                    "approved_at": approved_at,
+                    "reason": (
+                        "Autonomes Lernen und Schalten wurde ausdrücklich freigegeben."
+                    ),
+                }
+            )
+            record = self._save_behavior(record, behavior)
+            if pause_matching_automations:
+                paused: list[str] = []
+                try:
+                    for automation in record.behavior.related_automations:
+                        if not automation.enabled:
+                            continue
+                        self._ha_reader.call_service(
+                            "automation",
+                            "turn_off",
+                            {"entity_id": automation.entity_id},
+                        )
+                        paused.append(automation.entity_id)
+                except (HaClientError, ValueError):
+                    for entity_id in paused:
+                        try:
+                            self._ha_reader.call_service(
+                                "automation",
+                                "turn_on",
+                                {"entity_id": entity_id},
+                            )
+                        except (HaClientError, ValueError):
+                            logger.exception(
+                                "Failed to restore automation %s after handoff error",
+                                entity_id,
+                            )
+                    rollback = record.behavior.model_copy(
+                        update={
+                            "mode": BehaviorMode.SHADOW,
+                            "approved_at": None,
+                            "reason": (
+                                "Übernahme fehlgeschlagen; SillyHome bleibt im "
+                                "Shadow-Modus."
+                            ),
+                        }
+                    )
+                    self._save_behavior(record, rollback)
+                    raise
+                related = [
+                    automation.model_copy(update={"enabled": False})
+                    if automation.entity_id in paused
+                    else automation
+                    for automation in record.behavior.related_automations
+                ]
+                behavior = record.behavior.model_copy(
+                    update={
+                        "related_automations": related,
+                        "paused_automation_entity_ids": paused,
+                        "reason": (
+                            "SillyHome steuert aktiv; passende HA-Automationen "
+                            "wurden pausiert."
+                        ),
+                    }
+                )
+                return self._save_behavior(record, behavior)
+            return record
         else:
+            if restore_paused_automations:
+                for entity_id in record.behavior.paused_automation_entity_ids:
+                    self._ha_reader.call_service(
+                        "automation",
+                        "turn_on",
+                        {"entity_id": entity_id},
+                    )
             mode = BehaviorMode.SHADOW
             approved_at = None
-            reason = "Shadow-Modus aktiv; Vorhersagen werden nicht ausgeführt."
+            reason = (
+                "Shadow-Modus aktiv; pausierte HA-Automationen wurden fortgesetzt."
+                if restore_paused_automations
+                else "Shadow-Modus aktiv; Vorhersagen werden nicht ausgeführt."
+            )
         behavior = record.behavior.model_copy(
             update={
                 "mode": mode,
                 "approved_at": approved_at,
+                "related_automations": [
+                    automation.model_copy(update={"enabled": True})
+                    if (
+                        restore_paused_automations
+                        and automation.entity_id
+                        in record.behavior.paused_automation_entity_ids
+                    )
+                    else automation
+                    for automation in record.behavior.related_automations
+                ],
+                "paused_automation_entity_ids": (
+                    []
+                    if restore_paused_automations
+                    else record.behavior.paused_automation_entity_ids
+                ),
                 "reason": reason,
             }
         )
         return self._save_behavior(record, behavior)
 
+    def _prediction_execution_reason(
+        self,
+        record: ActuatorRecord,
+        current_state: str | None,
+        prediction: BehaviorPrediction,
+        now: datetime,
+    ) -> str:
+        if record.behavior.mode is not BehaviorMode.ACTIVE:
+            return "Nicht ausgeführt: SillyHome ist im Shadow-Modus."
+        if prediction.confidence < self._settings.prediction_confidence:
+            return (
+                "Nicht ausgeführt: Sicherheit liegt unter der "
+                f"Schaltschwelle von {self._settings.prediction_confidence:.0%}."
+            )
+        if current_state == prediction.target_state:
+            return "Nicht ausgeführt: Zielzustand ist bereits erreicht."
+        if not self._cooldown_elapsed(
+            record.behavior,
+            now,
+            prediction.target_state,
+        ):
+            return "Nicht ausgeführt: Sicherheits-Cooldown ist noch aktiv."
+        return "Ausführung ist freigegeben."
+
     def _build_patterns(
         self,
         *,
@@ -362,10 +580,20 @@ class BehaviorEngine:
             )
         return patterns
 
-    def _cooldown_elapsed(self, behavior: BehaviorState, now: datetime) -> bool:
-        return behavior.last_executed_at is None or (
-            now - behavior.last_executed_at
-        ) >= timedelta(seconds=self._settings.execution_cooldown_seconds)
+    def _cooldown_elapsed(
+        self,
+        behavior: BehaviorState,
+        now: datetime,
+        target_state: str,
+    ) -> bool:
+        if behavior.last_executed_at is None:
+            return True
+        last_event = behavior.execution_events[-1] if behavior.execution_events else None
+        if last_event is not None and last_event.target_state != target_state:
+            return True
+        return (now - behavior.last_executed_at) >= timedelta(
+            seconds=self._settings.execution_cooldown_seconds
+        )
 
     def _save_behavior(
         self,