sillyhome-next/docs/ml_api.md

ML-Serving-API

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

• Standard: http://127.0.0.1:8000/ml
• Health: /health
• Modelle: /models
• Retraining: /retrain
• Einzelvorhersage: /predict
• Batchvorhersage: /batch

Der Standard-Start erfolgt über uvicorn app.main:app, danach stehen HA- und ML-Routen in derselben Anwendung bereit.

Endpoints

GET /ml/health

Health-Check der ML-Services.

Beispielantwort

{
  "status": "ok",
  "updated_at": "2026-06-11T12:00:00Z"
}

GET /ml/models

Listet alle registrierten Modell-Artefakte auf.

Beispielantwort

{
  "models": ["default"]
}

POST /ml/predict

Einzelne Vorhersage für einen Sensor.

Request

{
  "modelId": "default",
  "sensor_id": "sensor.kitchen",
  "values": {"temperature": 21.0}
}

Antwort

{
  "model_id": "default",
  "sensor_id": "sensor.kitchen",
  "prediction": "default:sensor.kitchen:{'temperature': 21.0}"
}

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

{
  "modelId": "home-model",
  "samples": [
    {
      "sensor_id": "sensor.kitchen",
      "values": {"temperature": 21.0},
      "label": "occupied"
    }
  ]
}

Antwort

{
  "model_id": "home-model",
  "supported_sensors": ["sensor.kitchen"],
  "replaced": false
}

POST /ml/batch

Batch-Vorhersage für mehrere Sensorwerte.

Request

{
  "requests": [
    {
      "modelId": "default",
      "sensor_id": "sensor.kitchen",
      "values": {"temperature": 21.0}
    },
    {
      "modelId": "default",
      "sensor_id": "sensor.bedroom",
      "values": {"temperature": 18.5}
    }
  ]
}

Antwort

{
  "predictions": [
    {
      "model_id": "default",
      "sensor_id": "sensor.kitchen",
      "prediction": "default:sensor.kitchen:{'temperature': 21.0}"
    },
    {
      "model_id": "default",
      "sensor_id": "sensor.bedroom",
      "prediction": "default:sensor.bedroom:{'temperature': 18.5}"
    }
  ]
}

Fehlerfälle

• 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

Die produktive App lädt Artefakte aus SILLYHOME_MODEL_STORE. Neue Artefakte 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