# 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:
```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
- `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. 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
```bash
pytest
ruff check .
mypy
```