# SillyHome Next SillyHome lernt aus Home Assistant, sagt Aktorhandlungen voraus und darf sie nach einer ausdrücklichen Freigabe ausführen. ## Schnell orientieren - Fehler finden: [`docs/DEBUGGING.md`](docs/DEBUGGING.md) - Berechnung verstehen: [`docs/BEHAVIOR_ENGINE.md`](docs/BEHAVIOR_ENGINE.md) - Steuerung übernehmen/zurückgeben: [`docs/CONTROL_HANDOFF.md`](docs/CONTROL_HANDOFF.md) - Entwickeln, testen, veröffentlichen und installieren: [`docs/OPERATIONS.md`](docs/OPERATIONS.md) - Version 1.0.0 bedienen und prüfen: [`docs/V1_0_0_OPERATING_GUIDE.md`](docs/V1_0_0_OPERATING_GUIDE.md) - Arbeitsregeln für Coding-Agenten: [`AGENTS.md`](AGENTS.md) ## Reifegrad 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. ## Ziele - Home Assistant und Sensoren/Aktoren verstehen - Historie auswerten und Gewohnheiten erkennen - Vorhersagen erstellen und erklären - Persönliches Verhalten pro Aktor lernen und zukünftige Handlungen vorhersagen - Lokal-first ohne Cloudpflicht - Erweiterbar, testbar, dokumentiert ## Quickstart 1. Python-Venv anlegen und Abhängigkeiten installieren: ```bash python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` 2. Konfiguration aus `.env.example` übernehmen und anpassen: ```bash cp .env.example .env ``` 3. API starten: ```bash uvicorn app.main:app --reload ``` 4. Erreichbar unter: - `http://127.0.0.1:8000/` - lokales Dashboard - `http://127.0.0.1:8000/health` - Health-Check - `http://127.0.0.1:8000/docs/` - OpenAPI-Dokumentation - `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 - `http://127.0.0.1:8000/v1/actuators/dashboard` - schnelle Dashboard-Startdaten aus Store und JSON-Cache - `http://127.0.0.1:8000/v1/actuators/summary` - schlanke Liste beobachteter Aktoren - `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 Ohne vollständige HA-Konfiguration liefert `/v1/entities` bewusst `503`. ### Docker Compose ```bash cp .env.example .env docker compose up --build -d curl --fail http://127.0.0.1:8000/health ``` Compose veröffentlicht die API standardmäßig nur auf `127.0.0.1`. Für Zugriff aus dem Netz muss ein authentifizierender Reverse Proxy vorgeschaltet werden. ### ENV-Konfiguration (`.env.example`) - `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_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. ### Home-Assistant-Add-on Das Repository ist zugleich ein Home-Assistant-Add-on-Repository. In Home Assistant unter **Einstellungen → Add-ons → Add-on-Shop → Repositories** diese URL eintragen: `http://192.168.6.31:3000/pino/sillyhome-next` Danach **SillyHome Next** installieren und starten. Das Dashboard wird per Ingress geöffnet. Dort werden ausschließlich erlaubte Aktoren ausgewählt; Kontext- und Lernentscheidungen erfolgen automatisch. ### Normaler Workflow 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. Eindeutig im HA-Logbuch erkannte Automationen und Scripts zählen dabei gleichwertig wie manuelle Bedienungen. Eigene Schaltungen von SillyHome werden nicht zurückgelernt. 7. Bei der Freigabe kann SillyHome passende HA-Automationen pausieren und die Steuerung übernehmen. Beim Stoppen können diese Automationen gezielt wieder fortgesetzt werden. 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 Teststand `v0.3.0` wurde als HA-Backup `7df0fca0` gesichert. ### Tests ```bash pytest ruff check . mypy app backend tests ```