ACT-001: actuator-first sensor lifecycle

docs/ha_data.md

@@ -14,6 +14,15 @@ Trainings- und Erklärungsprozesse.
 - `actuator`: mögliche Automationsziele, nicht als Trainingssensor verwendet
 - `unsupported`: noch nicht klassifizierte Entity-Typen
 
+Zusätzlich reichert `HaReader` verfügbare Metadaten wie `friendly_name`,
+Bereich und Gerät aus Home Assistant an. Für die aktor-zentrierte Zuordnung
+nutzt SillyHome Next bevorzugt:
+
+- `area_id` und `area_name`
+- `device_id` und `device_name`
+- Friendly Names und Entity-ID-Tokens
+- Domain und `device_class`
+
 Optionale Query-Parameter:
 
 - `domain=sensor` kann mehrfach angegeben werden
@@ -32,7 +41,8 @@ Historische Zustände werden über Home Assistants
 Die Normalisierung übernimmt nur endliche numerische Zustände. `unknown`,
 `unavailable`, nichtnumerische Werte, `NaN` und unendliche Werte werden nicht
 als Trainingsdaten verwendet. Ergebnisse werden je Entity chronologisch
-sortiert.
+sortiert. Binäre Kontext-Entities werden bewusst nicht in numerische
+Trainingsreihen konvertiert.
 
 ## Datenschutz und Betrieb
 

docs/ml_api.md

@@ -1,7 +1,7 @@
 # ML-Serving-API
 
 Diese Dokumentation beschreibt die REST-Endpunkte der aktuellen
-Modell-Artefakt- und Vorhersage-Schnittstelle.
+Modell-Artefakt-, Vorhersage- und aktor-zentrierten Lifecycle-Schnittstelle.
 
 Das Serving verwendet ein lokal trainiertes statistisches Baseline-Modell.
 
@@ -15,6 +15,8 @@ Das Serving verwendet ein lokal trainiertes statistisches Baseline-Modell.
 - Einzelvorhersage: `/predict`
 - Batchvorhersage: `/batch`
 
+Die aktor-zentrierte API liegt unter `/v1/actuators`.
+
 Der Standard-Start erfolgt über `uvicorn app.main:app`, danach stehen HA- und
 ML-Routen in derselben Anwendung bereit.
 
@@ -168,14 +170,45 @@ Batch-Vorhersage für mehrere Sensorwerte.
 - `422 Unprocessable Content`: Sensor wird vom Modell nicht unterstützt oder Eingabe ist ungültig.
 - `503 Service Unavailable`: Registry ist nicht initialisiert.
 
+## Aktuator-zentrierte API
+
+### `GET /v1/actuators/discovery`
+
+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.
+
+**Request**
+```json
+{
+  "actuator_entity_id": "light.abstellkammer",
+  "enabled": true
+}
+```
+
+### `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.
+
 ## Betrieb
 
-Die produktive App lädt Artefakte aus `SILLYHOME_MODEL_STORE`. Neue Artefakte
-werden über `/ml/retrain`, `RetrainingService` oder direkt über
-`ModelRegistry.register(...)` registriert. Die Registry speichert validiertes
-JSON atomisch und lädt es beim Neustart. Die API sollte nur in einem
-vertrauenswürdigen Netz oder hinter einem authentifizierenden Reverse Proxy
-erreichbar sein.
+Die produktive App lädt Artefakte aus `SILLYHOME_MODEL_STORE`. Aktuator-,
+Override- 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
+authentifizierenden Reverse Proxy erreichbar sein.
 
 ## Verweise
 

docs/ml_training.md

@@ -3,10 +3,19 @@
 SillyHome Next trainiert ein lokales statistisches Baseline-Modell pro Sensor
 und Merkmal. Es benötigt keine Cloud und keine externe ML-Laufzeit.
 
+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.
+
 ## 1. Daten sammeln
 
 Alle Trainingsvektoren werden über `FeatureStore.add(...)` oder `add_batch(...)` eingepflegt. Jeder Vektor enthält eine Sensor-ID sowie ein Dictionary mit Merkmalen.
 
+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.
+
 ## 2. Statistisches Artefakt erzeugen
 
 ```python
@@ -61,6 +70,21 @@ 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.