ML-008: add statistical baseline model

Closes #19

docs/ml_api.md

@@ -3,9 +3,7 @@
 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.
+Das Serving verwendet ein lokal trainiertes statistisches Baseline-Modell.
 
 ## Basis-URL
 
@@ -13,6 +11,7 @@ Modell-Artefakt- und Vorhersage-Schnittstelle.
 - Health: `/health`
 - Modelle: `/models`
 - Retraining: `/retrain`
+- Evaluation: `/evaluate`
 - Einzelvorhersage: `/predict`
 - Batchvorhersage: `/batch`
 
@@ -62,7 +61,9 @@ Einzelne Vorhersage für einen Sensor.
 {
   "model_id": "default",
   "sensor_id": "sensor.kitchen",
-  "prediction": "default:sensor.kitchen:{'temperature': 21.0}"
+  "predictions": {"temperature": 21.4},
+  "confidence": 0.78,
+  "model_type": "statistical_baseline"
 }
 ```
 
@@ -91,10 +92,17 @@ dem Modellverzeichnis geladen.
 {
   "model_id": "home-model",
   "supported_sensors": ["sensor.kitchen"],
+  "trained_features": 1,
+  "model_type": "statistical_baseline",
   "replaced": false
 }
 ```
 
+### `POST /ml/evaluate`
+
+Vergleicht Modellvorhersagen mit Validierungsdaten und liefert MAE, RMSE und
+Coverage. Der Request verwendet dasselbe Sample-Format wie `/ml/retrain`.
+
 ### `POST /ml/batch`
 
 Batch-Vorhersage für mehrere Sensorwerte.
@@ -124,12 +132,16 @@ Batch-Vorhersage für mehrere Sensorwerte.
     {
       "model_id": "default",
       "sensor_id": "sensor.kitchen",
-      "prediction": "default:sensor.kitchen:{'temperature': 21.0}"
+      "predictions": {"temperature": 21.4},
+      "confidence": 0.78,
+      "model_type": "statistical_baseline"
     },
     {
       "model_id": "default",
       "sensor_id": "sensor.bedroom",
-      "prediction": "default:sensor.bedroom:{'temperature': 18.5}"
+      "predictions": {"temperature": 18.3},
+      "confidence": 0.74,
+      "model_type": "statistical_baseline"
     }
   ]
 }

docs/ml_training.md

@@ -1,14 +1,13 @@
 # ML Training- und Evaluations-Workflow
 
-Dieser Workflow beschreibt den aktuellen Platzhalter für Modell-Metadaten,
-Evaluation und Serving. Er trainiert in Version 0.1.0 noch kein statistisches
-Modell.
+SillyHome Next trainiert ein lokales statistisches Baseline-Modell pro Sensor
+und Merkmal. Es benötigt keine Cloud und keine externe ML-Laufzeit.
 
 ## 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. Artefakt-Metadaten erzeugen
+## 2. Statistisches Artefakt erzeugen
 
 ```python
 store = FeatureStore()
@@ -18,21 +17,30 @@ artifact = pipeline.run("my_artifact")
 pipeline.export("my_artifact")
 ```
 
-`TrainingPipeline.run(...)` erzeugt ein `TrainedArtifact` mit den unterstützten
-Sensor-IDs. Gewichte, Parameter oder ein echtes Modell werden noch nicht
-berechnet.
+`TrainingPipeline.run(...)` berechnet für jedes numerische Merkmal:
+
+- Stichprobenzahl
+- Mittelwert und Standardabweichung
+- Minimum und Maximum
+- linearen Trend mit Steigung und Achsenabschnitt
+
+Die nächste Vorhersage kombiniert den letzten beobachteten Wert mit der
+trainierten Trendsteigung. Die Confidence berücksichtigt Datenmenge und
+Stabilität.
 
 ## 3. Modell evaluieren
 
 ```python
 evaluator = Evaluator(pipeline)
-report = evaluator.evaluate(artifact.artifact_id, predictions)
+report = evaluator.evaluate(artifact.artifact_id, validation_samples)
 ```
 
-Der Report enthält:
+Der Report enthält echte numerische Vergleichsmetriken:
 - `artifact_id`
 - `sample_size`
-- Metriken wie `coverage` und `unknown_rate` mit Default-Schwellenwerten
+- `mae` (Mean Absolute Error)
+- `rmse` (Root Mean Squared Error)
+- `coverage` für den Anteil auswertbarer Merkmale
 
 ## 4. Modell registrieren
 
@@ -56,4 +64,5 @@ Der Service startet bewusst keinen eigenen Hintergrundprozess. Über
 ## 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.
-- `coverage` zählt nur exakte Sensor-Referenzen und bleibt im Bereich 0 bis 1.
+- Nur endliche numerische Werte werden trainiert.
+- `coverage` bleibt im Bereich 0 bis 1.