sillyhome-next/README.md

SillyHome Next

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.

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

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

Niemals Administrator-Tokens oder Passwörter eintragen. .env gehört nicht ins Versionskontrollsystem.

Tests

pytest
ruff check .
mypy