SillyHome Next

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.

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
Automationen vorschlagen und direkt generieren
Lokal-first ohne Cloudpflicht
Erweiterbar, testbar, dokumentiert

Quickstart

Python-Venv anlegen und Abhängigkeiten installieren:

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

Konfiguration aus .env.example übernehmen und anpassen:

cp .env.example .env

API starten:

uvicorn app.main:app --reload

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 - 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
POST http://127.0.0.1:8000/v1/automations/proposals - sicheren Entwurf anlegen

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_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.

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. Das Add-on nutzt die Supervisor-API nur lesend; Automation-Entwürfe werden lokal gespeichert und niemals automatisch ausgeführt.

Normaler Workflow

Im Dashboard oder per API einen Aktuator auswählen, zum Beispiel light.abstellkammer.
SillyHome Next bewertet passende numerische Sensoren und binäre Kontext-Entities anhand von Bereich, Gerät, Namen, Domain und device_class.
Starke und eindeutige Zuordnungen werden automatisch genutzt; schwache oder knappe Kandidaten bleiben mit Review-Hinweis sichtbar.
Manuelle Overrides haben Vorrang, bleiben persistent und überstehen Neustarts.
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 Teststand v0.3.0 wurde als HA-Backup 7df0fca0 gesichert.

Tests

pytest
ruff check .
mypy

5.0 KiB Raw Blame History Unescape Escape