BEHAVIOR-001: learn and predict actuator actions

docs/automations.md

@@ -1,14 +1,6 @@
-# Automation-Vorschläge
+# Keine manuell erzeugten Automationen
 
-SillyHome Next führt Automationen niemals automatisch aus. Der Workflow ist:
-
-1. Vorschlag als `draft` erstellen.
-2. Inhalt und Ziel-Entity prüfen.
-3. Mit aktueller Revision explizit freigeben oder ablehnen.
-4. Nur freigegebene Vorschläge als Home-Assistant-YAML exportieren.
-5. Das YAML außerhalb von SillyHome Next in Home Assistant importieren.
-
-Erlaubt sind numerische Sensor-Trigger und Aktionsdienste aus den Domains
-`light`, `switch`, `climate`, `fan` und `cover`. Shell-Kommandos, Skripte und
-beliebige Service-Domains werden abgewiesen. Eine einmal getroffene Entscheidung
-kann nicht überschrieben werden; Änderungen benötigen einen neuen Vorschlag.
+Seit `v0.5.0` erstellt SillyHome Next keine YAML-Automationen und bietet keinen
+Regel- oder Trigger-Editor mehr an. Der produktive Ablauf besteht aus
+Aktorauswahl, automatischem Verhaltenslernen, Shadow-Vorhersage und einer
+separaten Ausführungsfreigabe pro Aktor.

docs/ml_api.md

@@ -178,9 +178,10 @@ Listet unterstützte Aktuatoren mit angereicherter HA-Metadatenbasis.
 
 ### `POST /v1/actuators`
 
-Registriert einen Aktuator, ermittelt passende numerische Sensoren und
-Kontext-Entities, trainiert bei ausreichender History automatisch ein Modell und
-liefert Zuordnung, Confidence, Evidenz und Lifecycle-Status zurück.
+Registriert einen Aktor. Das System ermittelt passende Messwerte und
+Kontext-Entities vollständig automatisch, trainiert bei ausreichender Historie
+ein Modell und liefert Zuordnung, Confidence, Evidenz und Lifecycle-Status zur
+Diagnose zurück.
 
 **Request**
 ```json
@@ -190,21 +191,31 @@ liefert Zuordnung, Confidence, Evidenz und Lifecycle-Status zurück.
 }
 ```
 
-### `POST /v1/actuators/{actuator_entity_id}/override`
-
-Persistiert manuelle Overrides. Diese haben Vorrang vor der automatischen
-Heuristik und überstehen Neustarts.
-
 ### `POST /v1/actuators/reconciliation/run`
 
 Führt eine sichere globale Reconciliation aus. Die periodische Add-on-Schleife
 ruft denselben idempotenten Ablauf auf, startet aber keine Services in Home
 Assistant.
 
+### `POST /v1/actuators/{actuator_entity_id}/evaluate`
+
+Erstellt aus aktuellem Kontext eine neue Shadow- oder Aktiv-Vorhersage. Im
+Shadow-Modus wird niemals geschaltet.
+
+### `POST /v1/actuators/{actuator_entity_id}/activation`
+
+```json
+{"active": true}
+```
+
+Aktiviert autonomes Schalten erst nach ausreichendem Training und nur für
+erlaubte Aktor-Domains. Mit `false` wird der Aktor sofort wieder in den
+Shadow-Modus versetzt.
+
 ## Betrieb
 
-Die produktive App lädt Artefakte aus `SILLYHOME_MODEL_STORE`. Aktuator-,
-Override- und Reconciliation-Zustände liegen atomisch in
+Die produktive App lädt Artefakte aus `SILLYHOME_MODEL_STORE`. Aktor- und
+Reconciliation-Zustände liegen atomisch in
 `SILLYHOME_ACTUATOR_STORE`. Neue Artefakte werden über `/ml/retrain`,
 `RetrainingService` oder den aktor-zentrierten Lifecycle registriert. Die API
 sollte nur in einem vertrauenswürdigen Netz oder hinter einem

docs/ml_training.md

@@ -1,92 +1,51 @@
-# ML Training- und Evaluations-Workflow
+# Verhaltenslernen und Vorhersage
 
-SillyHome Next trainiert ein lokales statistisches Baseline-Modell pro Sensor
-und Merkmal. Es benötigt keine Cloud und keine externe ML-Laufzeit.
+Seit `v0.5.0` ist der produktive Lernpfad aktor-zentriert. Nutzer wählen nur
+einen Aktor; Sensoren, Kontext und Modelle werden automatisch verwaltet.
 
-Seit `v0.4.0` ist der bevorzugte Weg aktor-zentriert: ein bestätigter Aktuator
-wird mit einem numerischen Primärsensor verknüpft, die Historie dieses Sensors
-wird automatisch geladen und in ein deterministisches Artefakt überführt.
+## Datengrundlage
 
-## 1. Daten sammeln
+Für jeden Aktor lädt SillyHome Next:
 
-Alle Trainingsvektoren werden über `FeatureStore.add(...)` oder `add_batch(...)` eingepflegt. Jeder Vektor enthält eine Sensor-ID sowie ein Dictionary mit Merkmalen.
+- dessen Zustandswechsel aus der Home-Assistant-Historie
+- Logbook-Einträge zur Herkunft der Handlung
+- automatisch zugeordnete Mess- und Kontext-Entities
+- deren Zustand zum Zeitpunkt der Handlung
 
-Im Normalbetrieb erzeugt die Reconciliation diese Vektoren selbst aus realer
-Home-Assistant-History. Das Trainingsmerkmal heißt dabei immer `value`.
-Binäre Kontextsensoren bleiben Kontext und werden nicht als numerische Samples
-missverstanden.
+Eindeutig einem Home-Assistant-Benutzer zugeordnete Handlungen erhalten das
+höchste Gewicht. Erkannte Automations- und Script-Aktionen werden verworfen.
+Physische oder nicht eindeutig zuordenbare Bedienungen dürfen das
+Shadow-Modell ergänzen, reichen allein aber nicht zur Aktivierung.
 
-## 2. Statistisches Artefakt erzeugen
+## Modell
 
-```python
-store = FeatureStore()
-store.add(FeatureVector(sensor_id="sensor.kitchen", values={"temperature": 21.0}))
-pipeline = TrainingPipeline(store)
-artifact = pipeline.run("my_artifact")
-pipeline.export("my_artifact")
-```
+Das lokale Modell speichert pro beobachteter Handlung:
 
-`TrainingPipeline.run(...)` berechnet für jedes numerische Merkmal:
+- Zielzustand
+- lokale Tageszeit
+- Wochentag
+- Kontextzustände
+- Herkunft und Gewicht
 
-- Stichprobenzahl
-- Mittelwert und Standardabweichung
-- Minimum und Maximum
-- linearen Trend mit Steigung und Achsenabschnitt
+Eine Vorhersage bewertet zeitliche Nähe, Wochentagsmuster und aktuellen
+Kontext. Mehrere passende historische Handlungen erhöhen die Confidence.
 
-Die nächste Vorhersage kombiniert den letzten beobachteten Wert mit der
-trainierten Trendsteigung. Die Confidence berücksichtigt Datenmenge und
-Stabilität.
+## Betriebsstufen
 
-## 3. Modell evaluieren
+1. `collecting`: Noch nicht genügend Handlungen vorhanden.
+2. `shadow`: Modell ist trainiert; Vorhersagen werden angezeigt, aber nicht ausgeführt.
+3. `active`: Nutzer hat den Aktor ausdrücklich freigegeben.
 
-```python
-evaluator = Evaluator(pipeline)
-report = evaluator.evaluate(artifact.artifact_id, validation_samples)
-```
+Die Aktivierung verlangt genügend eindeutig einem Benutzer zugeordnete
+Handlungen. Ausgeführt werden nur erlaubte Zustände reversibler Domains:
+`light`, `switch`, `fan`, `humidifier` und `cover`.
 
-Der Report enthält echte numerische Vergleichsmetriken:
-- `artifact_id`
-- `sample_size`
-- `mae` (Mean Absolute Error)
-- `rmse` (Root Mean Squared Error)
-- `coverage` für den Anteil auswertbarer Merkmale
+## Schutzmechanismen
 
-## 4. Modell registrieren
-
-Das trainierte Artefakt kann anschließend über `ModelRegistry.register(artifact)` bereitgestellt werden. Die ML-Serving-API stellt es unter `/ml/predict` und `/ml/batch` zur Verfügung.
-
-## 5. Retraining ausführen
-
-`RetrainingService.retrain(...)` führt genau einen Trainingslauf aus und ersetzt
-ein vorhandenes Artefakt mit derselben ID atomisch in der Registry:
-
-```python
-service = RetrainingService(registry)
-result = service.retrain("home-model", vectors)
-```
-
-Scheduler, Cronjobs oder Home-Assistant-Automationen können alternativ die
-zustandslose Funktion `retrain_model(registry, artifact_id, vectors)` aufrufen.
-Der Service startet bewusst keinen eigenen Hintergrundprozess. Über
-`POST /ml/retrain` kann derselbe Ablauf per API angestoßen werden.
-
-## 6. Autonomer Lebenszyklus
-
-Der `ActuatorReconciliationService` verwaltet pro konfiguriertem Aktuator:
-
-- die automatische Sensor- und Kontextzuordnung mit Score, Confidence und Evidenz
-- persistente manuelle Overrides
-- den Modellstatus (`trained`, `pending_history`, `review_required`, `archived`, ...)
-- ein Audit-Protokoll mit Gründen für Training, Retraining oder Archivierung
-
-Retraining erfolgt nur, wenn:
-
-- genügend nutzbare numerische Historie vorliegt
-- die aktuelle Zuordnung eindeutig oder manuell bestätigt ist
-- die Historie sich materiell verändert hat oder das Modell als stale gilt
-
-## Hinweise
-- Für reproduzierbare Sensor-Reihenfolgen wird in `TrainingPipeline.run(...)` eine sortierte Sensor-Liste verwendet.
-- Fehlende Trainingsdaten lösen `ValueError` aus; nicht registrierte Artefakte lösen `KeyError` aus.
-- Nur endliche numerische Werte werden trainiert.
-- `coverage` bleibt im Bereich 0 bis 1.
+- explizite Freigabe pro Aktor
+- konfigurierbare Mindestkonfidenz
+- Cooldown zwischen Schaltungen
+- keine Ausführung bei bereits erreichtem Zielzustand
+- keine Ausführung unbekannter Zustände oder riskanter Domains
+- eigene Schaltungen werden beim nächsten Training herausgefiltert
+- bekannte Automation-/Script-Aktionen werden nicht als Nutzerverhalten gelernt