# Home-Assistant-Datenpipeline

SillyHome Next trennt aktuelle Entity-Metadaten, Discovery und historische
Messwerte. Dadurch gelangen nur klassifizierte, geeignete Daten in spätere
Trainings- und Erklärungsprozesse.

## Entity Discovery

`GET /v1/discovery` klassifiziert Home-Assistant-Entities in:

- `measurement`: numerische Messsensoren, für Training geeignet
- `binary_context`: binäre Kontextsensoren wie Bewegung oder Anwesenheit
- `context`: Personen-, Wetter- und Standortkontext
- `actuator`: mögliche Automationsziele, nicht als Trainingssensor verwendet
- `unsupported`: noch nicht klassifizierte Entity-Typen

Zusätzlich reichert `HaReader` verfügbare Metadaten wie `friendly_name`,
Bereich und Gerät aus Home Assistant an. Für die aktor-zentrierte Zuordnung
nutzt SillyHome Next bevorzugt:

- `area_id` und `area_name`
- `device_id` und `device_name`
- Friendly Names und Entity-ID-Tokens
- Domain und `device_class`

Optionale Query-Parameter:

- `domain=sensor` kann mehrfach angegeben werden
- `learnable=true|false` filtert nach Trainingsrelevanz

## Historische Daten

Historische Zustände werden über Home Assistants
`/api/history/period/<start>`-Schnittstelle geladen. Abfragen verlangen:

- mindestens eine Entity-ID, maximal 100
- zeitzonenbehaftete Start- und Endzeit
- ein Enddatum nach dem Startdatum
- maximal 31 Tage pro Abfrage

Die Normalisierung übernimmt nur endliche numerische Zustände. `unknown`,
`unavailable`, nichtnumerische Werte, `NaN` und unendliche Werte werden nicht
als Trainingsdaten verwendet. Ergebnisse werden je Entity chronologisch
sortiert. Binäre Kontext-Entities werden bewusst nicht in numerische
Trainingsreihen konvertiert.

## Datenschutz und Betrieb

Die Daten bleiben lokal. Home-Assistant-Tokens gehören ausschließlich in die
Umgebungskonfiguration und dürfen nicht protokolliert oder versioniert werden.
Die API sollte nur lokal oder hinter einem authentifizierenden Reverse Proxy
erreichbar sein.