harden delivery pipeline and production runtime

docs/ml_api.md

@@ -1,6 +1,11 @@
 # ML-Serving-API
 
-Diese Dokumentation beschreibt die REST-Endpoints für ML-Vorhersagen in SillyHome Next.
+Diese Dokumentation beschreibt die REST-Endpunkte der aktuellen
+Modell-Artefakt- und Vorhersage-Schnittstelle.
+
+> Hinweis: Version 0.1.0 enthält noch kein statistisch trainiertes ML-Modell.
+> Die Vorhersage ist eine deterministische Referenzimplementierung für den
+> späteren Modellvertrag.
 
 ## Basis-URL
 
@@ -10,7 +15,8 @@ Diese Dokumentation beschreibt die REST-Endpoints für ML-Vorhersagen in SillyHo
 - Einzelvorhersage: `/predict`
 - Batchvorhersage: `/batch`
 
-Der Standard-Start erfolgt über `uvicorn backend.app:app --reload`, danach steht die API unter `/ml` bereit.
+Der Standard-Start erfolgt über `uvicorn app.main:app`, danach stehen HA- und
+ML-Routen in derselben Anwendung bereit.
 
 ## Endpoints
 
@@ -101,16 +107,18 @@ Batch-Vorhersage für mehrere Sensorwerte.
 
 ## Fehlerfälle
 
-- `400 Bad Request`: Fehlende oder ungültige Felder.
-- `404 Not Found`: Modell oder Sensor nicht registriert.
-- `500 Internal Server Error`: Registry nicht initialisiert oder unerwarteter Fehler.
+- `404 Not Found`: Modell nicht registriert.
+- `422 Unprocessable Content`: Sensor wird vom Modell nicht unterstützt oder Eingabe ist ungültig.
+- `503 Service Unavailable`: Registry ist nicht initialisiert.
 
 ## Betrieb
 
-Beim Start wird automatisch ein Default-Artefakt erstellt, falls noch kein Modell registriert ist. Neue Modelle müssen zusätzlich über `ModelRegistry.register(...)` eingetragen werden.
+Die produktive App lädt Artefakte aus `SILLYHOME_MODEL_STORE`. Neue Artefakte
+werden derzeit intern über `ModelRegistry.register(...)` registriert. Die
+Registry speichert validiertes JSON atomisch und lädt es beim Neustart.
 
 ## Verweise
 
 - `app/ml/predictor.py`
 - `app/ml/registry/model_registry.py`
-- `backend/routes/ml.py`
+- `backend/routes/ml.py`

docs/ml_training.md

@@ -1,12 +1,14 @@
 # ML Training- und Evaluations-Workflow
 
-Dieser Workflow beschreibt, wie Modelle trainiert, evaluiert und an der Serving-Layer registriert werden.
+Dieser Workflow beschreibt den aktuellen Platzhalter für Modell-Metadaten,
+Evaluation und Serving. Er trainiert in Version 0.1.0 noch kein statistisches
+Modell.
 
 ## 1. Daten sammeln
 
 Alle Trainingsvektoren werden über `FeatureStore.add(...)` oder `add_batch(...)` eingepflegt. Jeder Vektor enthält eine Sensor-ID sowie ein Dictionary mit Merkmalen.
 
-## 2. Modell trainieren
+## 2. Artefakt-Metadaten erzeugen
 
 ```python
 store = FeatureStore()
@@ -16,7 +18,9 @@ artifact = pipeline.run("my_artifact")
 pipeline.export("my_artifact")
 ```
 
-`TrainingPipeline.run(...)` erzeugt ein `TrainedArtifact` mit den unterstützten Sensor-IDs.
+`TrainingPipeline.run(...)` erzeugt ein `TrainedArtifact` mit den unterstützten
+Sensor-IDs. Gewichte, Parameter oder ein echtes Modell werden noch nicht
+berechnet.
 
 ## 3. Modell evaluieren
 
@@ -36,4 +40,5 @@ Das trainierte Artefakt kann anschließend über `ModelRegistry.register(artifac
 
 ## Hinweise
 - Für reproduzierbare Sensor-Reihenfolgen wird in `TrainingPipeline.run(...)` eine sortierte Sensor-Liste verwendet.
-- Fehlende Trainingsdaten lösen `ValueError` aus; nicht registrierte Artefakte lösen `KeyError` aus.
+- Fehlende Trainingsdaten lösen `ValueError` aus; nicht registrierte Artefakte lösen `KeyError` aus.
+- `coverage` zählt nur exakte Sensor-Referenzen und bleibt im Bereich 0 bis 1.