ACT-001: actuator-first sensor lifecycle

README.md

@@ -4,11 +4,10 @@ Lokaler, datenschutzfreundlicher API-Prototyp für Home Assistant.
 
 ## Reifegrad
 
-Die aktuelle Entwicklungslinie stellt eine gehärtete technische Basis bereit:
-Home-Assistant-Entities und Historie lesen, Sensoren klassifizieren,
-regelbasierte Bausteine sowie ein lokal trainierbares statistisches
-Baseline-Modell mit persistenter Registry, Confidence und echten
-Evaluationsmetriken.
+Die aktuelle Entwicklungslinie ist aktor-zentriert: Nutzer konfigurieren nur
+noch Home-Assistant-Aktuatoren. SillyHome Next findet dazu passende numerische
+Sensoren und Kontext-Entities, zeigt Evidenz und Review-Bedarf an und hält
+passende Modelle lokal und autonom aktuell.
 
 ## Motivation
 TheSillyHome zeigte die Idee: statt statischer Regeln das Zuhause aus Verhaltensmustern verstehen. Diese Architektur modernisiert den Ansatz in Richtung Explainable AI, hybride Intelligenzebenen und langlebige Wartbarkeit.
@@ -46,6 +45,9 @@ uvicorn app.main:app --reload
 - `http://127.0.0.1:8000/v1/entities` - Home-Assistant-Entities
 - `http://127.0.0.1:8000/v1/discovery` - klassifizierte, filterbare Entities
 - `http://127.0.0.1:8000/v1/history` - normalisierte numerische Zeitreihen
+- `http://127.0.0.1:8000/v1/actuators/discovery` - unterstützte Aktuatoren für den aktor-zentrierten Workflow
+- `POST http://127.0.0.1:8000/v1/actuators` - Aktuator registrieren, Sensorzuordnung prüfen und Modell-Lebenszyklus starten
+- `POST http://127.0.0.1:8000/v1/actuators/reconciliation/run` - globale Reconciliation manuell anstoßen
 - `http://127.0.0.1:8000/ml/health` - Registry-/Serving-Health
 - `POST http://127.0.0.1:8000/ml/retrain` - Modell-Metadaten aktualisieren
 - `POST http://127.0.0.1:8000/ml/evaluate` - MAE/RMSE/Coverage berechnen
@@ -69,6 +71,11 @@ dem Netz muss ein authentifizierender Reverse Proxy vorgeschaltet werden.
 - `SILLYHOME_HA_TOKEN` – Long-Lived Access Token eines dedizierten HA-Benutzers mit minimalen Rechten
 - `SILLYHOME_MODEL_STORE` – Verzeichnis für persistierte Modell-Metadaten
 - `SILLYHOME_AUTOMATION_STORE` – Verzeichnis für Automation-Entwürfe
+- `SILLYHOME_ACTUATOR_STORE` – Verzeichnis für persistente Aktuator-Zuordnungen, Overrides und Reconciliation-Status
+- `SILLYHOME_HISTORY_DAYS` – Trainingsfenster für HA-History (1 bis 31 Tage)
+- `SILLYHOME_MIN_TRAINING_POINTS` – Mindestanzahl nutzbarer numerischer Messpunkte vor einem Modelltraining
+- `SILLYHOME_RETRAIN_STALE_HOURS` – Staleness-Grenze für automatisches Retraining
+- `SILLYHOME_RECONCILE_INTERVAL_SECONDS` – Intervall für sichere periodische Reconciliation
 
 Niemals Administrator-Tokens oder Passwörter eintragen. `.env` gehört nicht ins
 Versionskontrollsystem.
@@ -84,6 +91,13 @@ Danach **SillyHome Next** installieren und starten. Das Dashboard wird per Ingre
 geöffnet. Das Add-on nutzt die Supervisor-API nur lesend; Automation-Entwürfe werden
 lokal gespeichert und niemals automatisch ausgeführt.
 
+### Normaler Workflow
+1. Im Dashboard oder per API einen Aktuator auswählen, zum Beispiel `light.abstellkammer`.
+2. SillyHome Next bewertet passende numerische Sensoren und binäre Kontext-Entities anhand von Bereich, Gerät, Namen, Domain und `device_class`.
+3. Starke und eindeutige Zuordnungen werden automatisch genutzt; schwache oder knappe Kandidaten bleiben mit Review-Hinweis sichtbar.
+4. Manuelle Overrides haben Vorrang, bleiben persistent und überstehen Neustarts.
+5. Sobald genügend numerische HA-Historie vorhanden ist, trainiert das System automatisch ein lokales Modell pro Aktuator-Zuordnung und retrainiert es bei relevanten Datenänderungen oder Staleness.
+
 Vor einem Update sollte in Home Assistant unter **Einstellungen → System → Backups**
 eine Teil-Sicherung des Add-ons erstellt werden. Zur Wiederherstellung das gewünschte
 Backup öffnen, **SillyHome Next** auswählen und wiederherstellen. Der erste produktive