sillyhome-next-dev/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
• 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/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 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