SillyHome Next

Lokaler, datenschutzfreundlicher API-Prototyp für Home Assistant.

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:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

2. Konfiguration aus .env.example übernehmen und anpassen:

cp .env.example .env

3. API starten:

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
• 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

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. 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 Backup öffnen, SillyHome Next auswählen und wiederherstellen. Der erste produktive Teststand v0.3.0 wurde als HA-Backup 7df0fca0 gesichert.

Tests

pytest
ruff check .
mypy