# ML-Serving-API

Diese Dokumentation beschreibt die REST-Endpoints für ML-Vorhersagen in SillyHome Next.

## Basis-URL

- Standard: `http://127.0.0.1:8000/ml`
- Health: `/health`
- Modelle: `/models`
- Einzelvorhersage: `/predict`
- Batchvorhersage: `/batch`

Der Standard-Start erfolgt über `uvicorn backend.app:app --reload`, danach steht die API unter `/ml` bereit.

## Endpoints

### `GET /ml/health`

Health-Check der ML-Services.

**Beispielantwort**
```json
{
  "status": "ok",
  "updated_at": "2026-06-11T12:00:00Z"
}
```

### `GET /ml/models`

Listet alle registrierten Modell-Artefakte auf.

**Beispielantwort**
```json
{
  "models": ["default"]
}
```

### `POST /ml/predict`

Einzelne Vorhersage für einen Sensor.

**Request**
```json
{
  "modelId": "default",
  "sensor_id": "sensor.kitchen",
  "values": {"temperature": 21.0}
}
```

**Antwort**
```json
{
  "model_id": "default",
  "sensor_id": "sensor.kitchen",
  "prediction": "default:sensor.kitchen:{'temperature': 21.0}"
}
```

### `POST /ml/batch`

Batch-Vorhersage für mehrere Sensorwerte.

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

**Antwort**
```json
{
  "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

- `400 Bad Request`: Fehlende oder ungültige Felder.
- `404 Not Found`: Modell oder Sensor nicht registriert.
- `500 Internal Server Error`: Registry nicht initialisiert oder unerwarteter Fehler.

## Betrieb

Beim Start wird automatisch ein Default-Artefakt erstellt, falls noch kein Modell registriert ist. Neue Modelle müssen zusätzlich über `ModelRegistry.register(...)` eingetragen werden.

## Verweise

- `app/ml/predictor.py`
- `app/ml/registry/model_registry.py`
- `backend/routes/ml.py`