ML-007: add retraining pipeline and API

Closes #13

docs/ml_api.md

@@ -12,6 +12,7 @@ Modell-Artefakt- und Vorhersage-Schnittstelle.
 - Standard: `http://127.0.0.1:8000/ml`
 - Health: `/health`
 - Modelle: `/models`
+- Retraining: `/retrain`
 - Einzelvorhersage: `/predict`
 - Batchvorhersage: `/batch`
 
@@ -65,6 +66,35 @@ Einzelne Vorhersage für einen Sensor.
 }
 ```
 
+### `POST /ml/retrain`
+
+Trainiert die Artefakt-Metadaten aus neuen Sensordaten. Existiert `modelId`
+bereits, wird das Artefakt atomisch ersetzt und beim nächsten Prozessstart aus
+dem Modellverzeichnis geladen.
+
+**Request**
+```json
+{
+  "modelId": "home-model",
+  "samples": [
+    {
+      "sensor_id": "sensor.kitchen",
+      "values": {"temperature": 21.0},
+      "label": "occupied"
+    }
+  ]
+}
+```
+
+**Antwort**
+```json
+{
+  "model_id": "home-model",
+  "supported_sensors": ["sensor.kitchen"],
+  "replaced": false
+}
+```
+
 ### `POST /ml/batch`
 
 Batch-Vorhersage für mehrere Sensorwerte.
@@ -114,11 +144,15 @@ Batch-Vorhersage für mehrere Sensorwerte.
 ## Betrieb
 
 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.
+werden über `/ml/retrain`, `RetrainingService` oder direkt über
+`ModelRegistry.register(...)` registriert. Die Registry speichert validiertes
+JSON atomisch und lädt es beim Neustart. Die API sollte nur in einem
+vertrauenswürdigen Netz oder hinter einem authentifizierenden Reverse Proxy
+erreichbar sein.
 
 ## Verweise
 
 - `app/ml/predictor.py`
+- `app/ml/retraining.py`
 - `app/ml/registry/model_registry.py`
 - `backend/routes/ml.py`

docs/ml_training.md

@@ -38,6 +38,21 @@ Der Report enthält:
 
 Das trainierte Artefakt kann anschließend über `ModelRegistry.register(artifact)` bereitgestellt werden. Die ML-Serving-API stellt es unter `/ml/predict` und `/ml/batch` zur Verfügung.
 
+## 5. Retraining ausführen
+
+`RetrainingService.retrain(...)` führt genau einen Trainingslauf aus und ersetzt
+ein vorhandenes Artefakt mit derselben ID atomisch in der Registry:
+
+```python
+service = RetrainingService(registry)
+result = service.retrain("home-model", vectors)
+```
+
+Scheduler, Cronjobs oder Home-Assistant-Automationen können alternativ die
+zustandslose Funktion `retrain_model(registry, artifact_id, vectors)` aufrufen.
+Der Service startet bewusst keinen eigenen Hintergrundprozess. Über
+`POST /ml/retrain` kann derselbe Ablauf per API angestoßen werden.
+
 ## 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.