BEHAVIOR-001: learn and predict actuator actions

README.md

@@ -4,10 +4,11 @@ Lokaler, datenschutzfreundlicher API-Prototyp für Home Assistant.
 
 ## Reifegrad
 
-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.
+Die aktuelle Entwicklungslinie ist vollständig aktor-zentriert: Nutzer wählen
+nur Home-Assistant-Aktuatoren aus. SillyHome Next findet Sensoren, Zustände und
+Kontext automatisch, wertet die vorhandene Historie aus und hält passende
+lokale Modelle autonom aktuell. Es gibt keinen Regel-, Trigger-, Sensor- oder
+YAML-Konfigurationsschritt.
 
 ## 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.
@@ -16,7 +17,7 @@ TheSillyHome zeigte die Idee: statt statischer Regeln das Zuhause aus Verhaltens
 - Home Assistant und Sensoren/Aktoren verstehen
 - Historie auswerten und Gewohnheiten erkennen
 - Vorhersagen erstellen und erklären
-- Automationen vorschlagen und direkt generieren
+- Persönliches Verhalten pro Aktor lernen und zukünftige Handlungen vorhersagen
 - Lokal-first ohne Cloudpflicht
 - Erweiterbar, testbar, dokumentiert
 
@@ -46,12 +47,13 @@ uvicorn app.main:app --reload
 - `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` - Aktor freigeben; Kontextzuordnung und Modell-Lebenszyklus starten automatisch
+- `POST http://127.0.0.1:8000/v1/actuators/{entity_id}/evaluate` - Shadow-Vorhersage aktualisieren
+- `POST http://127.0.0.1:8000/v1/actuators/{entity_id}/activation` - autonomes Schalten pro Aktor freigeben oder stoppen
 - `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
-- `POST http://127.0.0.1:8000/v1/automations/proposals` - sicheren Entwurf anlegen
 
 Ohne vollständige HA-Konfiguration liefert `/v1/entities` bewusst `503`.
 
@@ -70,12 +72,17 @@ dem Netz muss ein authentifizierender Reverse Proxy vorgeschaltet werden.
 - `SILLYHOME_HA_URL` – Basis-URL deiner Home-Assistant-Instanz (z. B. `http://homeassistant.local:8123`)
 - `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_ACTUATOR_STORE` – Verzeichnis für persistente Aktor-Zuordnungen 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
+- `SILLYHOME_MIN_BEHAVIOR_ACTIONS` – Mindestzahl gelernter Handlungen vor einer Freigabe
+- `SILLYHOME_PREDICTION_CONFIDENCE` – Mindestkonfidenz für autonomes Schalten
+- `SILLYHOME_PREDICTION_WINDOW_MINUTES` – Zeitfenster um gelernte Handlungsmuster
+- `SILLYHOME_PREDICTION_INTERVAL_SECONDS` – Intervall für Shadow-/Aktiv-Vorhersagen
+- `SILLYHOME_EXECUTION_COOLDOWN_SECONDS` – Mindestabstand zwischen eigenen Schaltungen
+- `SILLYHOME_TIMEZONE` – lokale Zeitzone für Tages- und Wochenmuster
 
 Niemals Administrator-Tokens oder Passwörter eintragen. `.env` gehört nicht ins
 Versionskontrollsystem.
@@ -88,15 +95,22 @@ unter **Einstellungen → Add-ons → Add-on-Shop → Repositories** diese URL e
 `http://192.168.6.31:3000/pino/sillyhome-next`
 
 Danach **SillyHome Next** installieren und starten. Das Dashboard wird per Ingress
-geöffnet. Das Add-on nutzt die Supervisor-API nur lesend; Automation-Entwürfe werden
-lokal gespeichert und niemals automatisch ausgeführt.
+geöffnet. Dort werden ausschließlich erlaubte Aktoren ausgewählt; Kontext- und
+Lernentscheidungen erfolgen automatisch.
 
 ### 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.
+1. Im Dashboard einen Aktor auswählen, zum Beispiel `light.abstellkammer`.
+2. SillyHome Next bewertet automatisch Messwerte, Anwesenheit, Bewegung,
+   Bereiche, Gerätebeziehungen und weitere HA-Kontexte.
+3. Das System verwendet selbstständig die beste verfügbare Zuordnung.
+   Niedrige Sicherheit bleibt als Diagnose sichtbar, verlangt aber keine
+   manuelle Konfiguration.
+4. Sobald genügend Historie vorhanden ist, trainiert und aktualisiert das
+   System das lokale Modell automatisch.
+5. Vorhersagen laufen zunächst ausschließlich im Shadow-Modus.
+6. Erst nach ausdrücklicher Freigabe pro Aktor werden hochkonfidente,
+   erlaubte Zustände geschaltet. Eigene Schaltungen und erkannte
+   HA-Automationen werden nicht als Nutzerhandlungen zurückgelernt.
 
 Vor einem Update sollte in Home Assistant unter **Einstellungen → System → Backups**
 eine Teil-Sicherung des Add-ons erstellt werden. Zur Wiederherstellung das gewünschte