ML-008: add statistical baseline model

Closes #19

app/main.py

@@ -38,7 +38,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
 app = FastAPI(
     title="SillyHome Next API",
     description="Lokales Smart-Home-Intelligenzsystem für Home Assistant.",
-    version="0.1.0",
+    version="0.2.0",
     lifespan=lifespan,
 )
 app.state.settings = load_settings()

app/ml/__init__.py

@@ -3,6 +3,9 @@
 __all__ = [
     "FeatureStore",
     "FeatureVector",
+    "FeatureModel",
+    "PredictionResult",
+    "Predictor",
     "RetrainingResult",
     "RetrainingService",
     "TrainedArtifact",
@@ -10,5 +13,6 @@ __all__ = [
     "retrain_model",
 ]
 from app.ml.feature_store import FeatureStore, FeatureVector
+from app.ml.predictor import PredictionResult, Predictor
 from app.ml.retraining import RetrainingResult, RetrainingService, retrain_model
-from app.ml.training import TrainedArtifact, TrainingPipeline
+from app.ml.training import FeatureModel, TrainedArtifact, TrainingPipeline

app/ml/evaluation.py

@@ -1,9 +1,13 @@
 from __future__ import annotations
 
 import logging
+import math
 from collections.abc import Sequence
 from dataclasses import dataclass
 
+from app.ml.feature_store import FeatureVector
+from app.ml.predictor import Predictor
+from app.ml.registry.model_registry import ModelRegistry
 from app.ml.training import TrainingPipeline
 
 logger = logging.getLogger(__name__)
@@ -24,41 +28,62 @@ class EvalReport:
 
 
 class Evaluator:
-    def __init__(self, pipeline: TrainingPipeline) -> None:
+    def __init__(
+        self,
+        pipeline: TrainingPipeline | None = None,
+        registry: ModelRegistry | None = None,
+    ) -> None:
+        if isinstance(pipeline, ModelRegistry) and registry is None:
+            registry = pipeline
+            pipeline = None
+        if pipeline is None and registry is None:
+            raise ValueError("Evaluator erfordert TrainingPipeline oder ModelRegistry.")
         self._pipeline = pipeline
+        self._registry = registry
+        self._predictor = Predictor(pipeline=pipeline, registry=registry)
 
-    def evaluate(self, artifact_id: str, predictions: Sequence[str]) -> EvalReport:
+    def evaluate(self, artifact_id: str, samples: Sequence[FeatureVector]) -> EvalReport:
         try:
-            supported_sensors = set(self._pipeline.export(artifact_id).supported_sensors)
+            if self._registry is not None:
+                self._registry.load_artifact(artifact_id)
+            elif self._pipeline is not None:
+                self._pipeline.export(artifact_id)
         except KeyError as exc:
             raise ValueError("Kein trainiertes Modell für Evaluation vorhanden.") from exc
 
-        parsed_sensors = [_prediction_sensor(prediction) for prediction in predictions]
-        supported_hits = sum(sensor in supported_sensors for sensor in parsed_sensors)
-        unknown_hits = sum(sensor not in supported_sensors for sensor in parsed_sensors)
-        sample_size = len(predictions)
-        coverage = supported_hits / sample_size if sample_size else 0.0
-        unknown_rate = unknown_hits / sample_size if sample_size else 0.0
+        absolute_errors: list[float] = []
+        squared_errors: list[float] = []
+        for sample in samples:
+            try:
+                prediction = self._predictor.predict(artifact_id, sample)
+            except ValueError:
+                continue
+            for feature_name, predicted in prediction.predictions.items():
+                actual = float(sample.values[feature_name])
+                error = predicted - actual
+                absolute_errors.append(abs(error))
+                squared_errors.append(error**2)
 
-        coverage_metric = Metric(name="coverage", value=coverage, threshold=0.8)
-        unknown_metric = Metric(name="unknown_rate", value=unknown_rate, threshold=0.1)
+        sample_size = len(absolute_errors)
+        mae = sum(absolute_errors) / sample_size if sample_size else 0.0
+        rmse = math.sqrt(sum(squared_errors) / sample_size) if sample_size else 0.0
+        expected_values = sum(len(sample.values) for sample in samples)
+        coverage = sample_size / expected_values if expected_values else 0.0
 
         report = EvalReport(
             artifact_id=artifact_id,
             sample_size=sample_size,
-            metrics=[coverage_metric, unknown_metric],
+            metrics=[
+                Metric(name="mae", value=mae),
+                Metric(name="rmse", value=rmse),
+                Metric(name="coverage", value=coverage, threshold=0.8),
+            ],
         )
         logger.info(
-            "Evaluation %s -> coverage=%.2f, unknown_rate=%.2f",
+            "Evaluation %s -> mae=%.4f, rmse=%.4f, coverage=%.2f",
             artifact_id,
+            mae,
+            rmse,
             coverage,
-            unknown_rate,
         )
         return report
-
-
-def _prediction_sensor(prediction: str) -> str | None:
-    parts = prediction.split(":", 2)
-    if len(parts) != 3 or not parts[0] or not parts[1]:
-        return None
-    return parts[1]

app/ml/predictor.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import logging
+import math
+from dataclasses import dataclass
 from typing import Sequence
 
 from app.ml.feature_store import FeatureVector
@@ -10,6 +12,15 @@ from app.ml.training import TrainedArtifact, TrainingPipeline
 logger = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True)
+class PredictionResult:
+    artifact_id: str
+    sensor_id: str
+    predictions: dict[str, float]
+    confidence: float
+    model_type: str
+
+
 class Predictor:
     def __init__(
         self,
@@ -24,15 +35,45 @@ class Predictor:
         self._pipeline = pipeline
         self._registry = registry
 
-    def predict(self, artifact_id: str, entity: FeatureVector) -> str:
+    def predict(self, artifact_id: str, entity: FeatureVector) -> PredictionResult:
         artifact = self._get_artifact(artifact_id)
         if entity.sensor_id not in artifact.supported_sensors:
             raise ValueError(
                 f"Sensor '{entity.sensor_id}' wird vom Modell '{artifact_id}' nicht unterstützt."
             )
-        return f"{artifact_id}:{entity.sensor_id}:{entity.values}"
+        sensor_models = artifact.feature_models.get(entity.sensor_id, {})
+        if not sensor_models:
+            raise ValueError(f"Modell '{artifact_id}' enthält keine statistischen Parameter.")
 
-    def predict_batch(self, artifact_id: str, entities: Sequence[FeatureVector]) -> list[str]:
+        feature_names = sorted(set(sensor_models).intersection(entity.values))
+        if not feature_names:
+            raise ValueError(
+                f"Keine Eingabemerkmale werden vom Modell '{artifact_id}' unterstützt."
+            )
+
+        predictions: dict[str, float] = {}
+        confidences: list[float] = []
+        for feature_name in feature_names:
+            model = sensor_models[feature_name]
+            current_value = float(entity.values[feature_name])
+            if not math.isfinite(current_value):
+                raise ValueError("Vorhersagewerte müssen endlich sein.")
+            predictions[feature_name] = model.forecast(current_value)
+            confidences.append(model.confidence)
+
+        return PredictionResult(
+            artifact_id=artifact_id,
+            sensor_id=entity.sensor_id,
+            predictions=predictions,
+            confidence=sum(confidences) / len(confidences),
+            model_type=artifact.model_type,
+        )
+
+    def predict_batch(
+        self,
+        artifact_id: str,
+        entities: Sequence[FeatureVector],
+    ) -> list[PredictionResult]:
         return [self.predict(artifact_id, entity) for entity in entities]
 
     @staticmethod
@@ -47,4 +88,4 @@ class Predictor:
             return self._registry.load_artifact(artifact_id)
         if self._pipeline is not None:
             return self._pipeline.export(artifact_id)
-        raise RuntimeError("Predictor nicht initialisiert.")
+        raise RuntimeError("Predictor nicht initialisiert.")

app/ml/registry/model_registry.py

@@ -2,13 +2,14 @@ from __future__ import annotations
 
 import json
 import logging
+import math
 import os
 from pathlib import Path
 import re
 from threading import RLock
 from collections.abc import Iterable
 
-from app.ml.training import TrainedArtifact
+from app.ml.training import FeatureModel, TrainedArtifact
 
 logger = logging.getLogger(__name__)
 
@@ -52,19 +53,26 @@ class ModelRegistry:
                 raw = json.loads(source.read_text(encoding="utf-8"))
                 artifact_id = raw["artifact_id"]
                 supported_sensors = raw["supported_sensors"]
+                model_type = raw.get("model_type", "metadata")
+                raw_feature_models = raw.get("feature_models", {})
                 if not isinstance(artifact_id, str) or not isinstance(supported_sensors, list):
                     raise ValueError("invalid artifact structure")
+                if not isinstance(model_type, str):
+                    raise ValueError("model_type must be a string")
                 self._validate_artifact_id(artifact_id)
                 if source.name != f"{artifact_id}.json":
                     raise ValueError("artifact id does not match filename")
                 if not all(isinstance(sensor, str) for sensor in supported_sensors):
                     raise ValueError("supported_sensors must contain strings")
+                feature_models = _deserialize_feature_models(raw_feature_models)
             except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
                 raise ValueError(f"Ungültiges Modell-Artefakt: {source.name}") from exc
 
             self._artifacts[artifact_id] = TrainedArtifact(
                 artifact_id=artifact_id,
                 supported_sensors=tuple(supported_sensors),
+                feature_models=feature_models,
+                model_type=model_type,
             )
 
     def _persist(self, artifact: TrainedArtifact) -> None:
@@ -73,6 +81,22 @@ class ModelRegistry:
         payload = {
             "artifact_id": artifact.artifact_id,
             "supported_sensors": list(artifact.supported_sensors),
+            "model_type": artifact.model_type,
+            "feature_models": {
+                sensor_id: {
+                    feature_name: {
+                        "sample_count": model.sample_count,
+                        "mean": model.mean,
+                        "standard_deviation": model.standard_deviation,
+                        "minimum": model.minimum,
+                        "maximum": model.maximum,
+                        "slope": model.slope,
+                        "intercept": model.intercept,
+                    }
+                    for feature_name, model in sorted(models.items())
+                }
+                for sensor_id, models in sorted(artifact.feature_models.items())
+            },
         }
         temporary.write_text(
             json.dumps(payload, ensure_ascii=True, sort_keys=True) + "\n",
@@ -88,3 +112,51 @@ class ModelRegistry:
                 "artifact_id darf nur Buchstaben, Ziffern, Punkt, Unterstrich "
                 "und Bindestrich enthalten."
             )
+
+
+def _deserialize_feature_models(raw: object) -> dict[str, dict[str, FeatureModel]]:
+    if not isinstance(raw, dict):
+        raise ValueError("feature_models must be an object")
+
+    result: dict[str, dict[str, FeatureModel]] = {}
+    for sensor_id, raw_features in raw.items():
+        if not isinstance(sensor_id, str) or not isinstance(raw_features, dict):
+            raise ValueError("invalid sensor feature models")
+        features: dict[str, FeatureModel] = {}
+        for feature_name, raw_model in raw_features.items():
+            if not isinstance(feature_name, str) or not isinstance(raw_model, dict):
+                raise ValueError("invalid feature model")
+            sample_count = raw_model.get("sample_count")
+            if not isinstance(sample_count, int) or isinstance(sample_count, bool) or sample_count < 1:
+                raise ValueError("sample_count must be a positive integer")
+            values = {
+                key: _finite_number(raw_model.get(key))
+                for key in (
+                    "mean",
+                    "standard_deviation",
+                    "minimum",
+                    "maximum",
+                    "slope",
+                    "intercept",
+                )
+            }
+            features[feature_name] = FeatureModel(
+                sample_count=sample_count,
+                mean=values["mean"],
+                standard_deviation=values["standard_deviation"],
+                minimum=values["minimum"],
+                maximum=values["maximum"],
+                slope=values["slope"],
+                intercept=values["intercept"],
+            )
+        result[sensor_id] = features
+    return result
+
+
+def _finite_number(value: object) -> float:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise ValueError("feature model values must be finite numbers")
+    converted = float(value)
+    if not math.isfinite(converted):
+        raise ValueError("feature model values must be finite numbers")
+    return converted

app/ml/training.py

@@ -1,17 +1,44 @@
 from __future__ import annotations
 
 import logging
-from dataclasses import dataclass
+import math
+from collections import defaultdict
+from dataclasses import dataclass, field
 
 from app.ml.feature_store import FeatureStore
 
 logger = logging.getLogger(__name__)
 
 
-@dataclass
+@dataclass(frozen=True)
+class FeatureModel:
+    sample_count: int
+    mean: float
+    standard_deviation: float
+    minimum: float
+    maximum: float
+    slope: float
+    intercept: float
+
+    def forecast(self, current_value: float | None = None) -> float:
+        if current_value is not None:
+            return current_value + self.slope
+        return self.intercept + self.slope * self.sample_count
+
+    @property
+    def confidence(self) -> float:
+        sample_score = self.sample_count / (self.sample_count + 2)
+        scale = abs(self.mean) if abs(self.mean) > 1e-9 else 1.0
+        stability_score = 1.0 / (1.0 + self.standard_deviation / scale)
+        return min(0.99, max(0.05, sample_score * stability_score))
+
+
+@dataclass(frozen=True)
 class TrainedArtifact:
     artifact_id: str
     supported_sensors: tuple[str, ...]
+    feature_models: dict[str, dict[str, FeatureModel]] = field(default_factory=dict)
+    model_type: str = "statistical_baseline"
 
 
 class TrainingPipeline:
@@ -24,8 +51,33 @@ class TrainingPipeline:
         if not vectors:
             raise ValueError("FeatureStore enthält keine Trainingsdaten.")
 
-        sensors = tuple(sorted({vector.sensor_id for vector in vectors}))
-        artifact = TrainedArtifact(artifact_id=artifact_id, supported_sensors=sensors)
+        samples: dict[str, dict[str, list[float]]] = defaultdict(lambda: defaultdict(list))
+        for vector in vectors:
+            for feature_name, raw_value in vector.values.items():
+                value = float(raw_value)
+                if math.isfinite(value):
+                    samples[vector.sensor_id][feature_name].append(value)
+
+        feature_models = {
+            sensor_id: {
+                feature_name: _fit_feature(values)
+                for feature_name, values in sorted(features.items())
+                if values
+            }
+            for sensor_id, features in sorted(samples.items())
+        }
+        feature_models = {
+            sensor_id: models for sensor_id, models in feature_models.items() if models
+        }
+        if not feature_models:
+            raise ValueError("Trainingsdaten enthalten keine endlichen numerischen Werte.")
+
+        sensors = tuple(feature_models)
+        artifact = TrainedArtifact(
+            artifact_id=artifact_id,
+            supported_sensors=sensors,
+            feature_models=feature_models,
+        )
         self._artifacts[artifact_id] = artifact
         logger.info("Training abgeschlossen für %s mit %d Sensoren", artifact_id, len(sensors))
         return artifact
@@ -34,3 +86,32 @@ class TrainingPipeline:
         if artifact_id not in self._artifacts:
             raise KeyError(f"Artifact '{artifact_id}' nicht gefunden.")
         return self._artifacts[artifact_id]
+
+
+def _fit_feature(values: list[float]) -> FeatureModel:
+    sample_count = len(values)
+    mean = sum(values) / sample_count
+    variance = sum((value - mean) ** 2 for value in values) / sample_count
+    standard_deviation = math.sqrt(variance)
+
+    if sample_count == 1:
+        slope = 0.0
+        intercept = mean
+    else:
+        x_mean = (sample_count - 1) / 2
+        denominator = sum((index - x_mean) ** 2 for index in range(sample_count))
+        numerator = sum(
+            (index - x_mean) * (value - mean) for index, value in enumerate(values)
+        )
+        slope = numerator / denominator
+        intercept = mean - slope * x_mean
+
+    return FeatureModel(
+        sample_count=sample_count,
+        mean=mean,
+        standard_deviation=standard_deviation,
+        minimum=min(values),
+        maximum=max(values),
+        slope=slope,
+        intercept=intercept,
+    )