161 lines
7.7 KiB
Markdown
161 lines
7.7 KiB
Markdown
# 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)
|
||
- Version 1.0.x Abnahme und offene Punkte:
|
||
[`docs/V1_0_ACCEPTANCE.md`](docs/V1_0_ACCEPTANCE.md)
|
||
- Version 1.1.0 Safety, Transparenz und Job-Queue:
|
||
[`docs/V1_1_0_OPERATING_GUIDE.md`](docs/V1_1_0_OPERATING_GUIDE.md)
|
||
- Version 1.2.0 adaptive Gewichtung, Rollback und Profile:
|
||
[`docs/V1_2_0_OPERATING_GUIDE.md`](docs/V1_2_0_OPERATING_GUIDE.md)
|
||
- Version 1.3.0 Anomalie- und Performance-Überwachung:
|
||
[`docs/V1_3_0_OPERATING_GUIDE.md`](docs/V1_3_0_OPERATING_GUIDE.md)
|
||
- Version 1.4.0 deutsches Dashboard und gestufter Datenabruf:
|
||
[`docs/V1_4_0_OPERATING_GUIDE.md`](docs/V1_4_0_OPERATING_GUIDE.md)
|
||
- Version 1.5.0 Menü-Dashboard und kompakte Detaildaten:
|
||
[`docs/V1_5_0_OPERATING_GUIDE.md`](docs/V1_5_0_OPERATING_GUIDE.md)
|
||
- Version 1.5.1 Stabilisierung der Dashboard-Ladepfade:
|
||
[`docs/V1_5_1_OPERATING_GUIDE.md`](docs/V1_5_1_OPERATING_GUIDE.md)
|
||
- Version 1.5.2 Rollback-Speicher und HA-Timeouts:
|
||
[`docs/V1_5_2_OPERATING_GUIDE.md`](docs/V1_5_2_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
|
||
```
|