Add actuator simulation tuning

app/api/v1/actuators.py

@@ -10,7 +10,14 @@ from pydantic import BaseModel, Field
 
 from app.actuators.cache_db import DashboardCache
 from app.actuators.lifecycle import ActuatorReconciliationService
-from app.actuators.models import ActuatorRecord, AnomalyEvent, FeedbackKind, ReconciliationState, SensorWeightGroup
+from app.actuators.models import (
+    ActuatorRecord,
+    AnomalyEvent,
+    FeedbackKind,
+    ReconciliationState,
+    SensorWeightGroup,
+    SimulationOutcome,
+)
 from app.actuators.models import JobQueueItem, JobQueueState, JobStatus, SafetyProfile
 from app.actuators.store import ActuatorStore
 from app.behavior.engine import BehaviorEngine
@@ -52,6 +59,14 @@ class WeightOverrideRequest(BaseModel):
     note: str | None = Field(default=None, max_length=500)
 
 
+class SimulationRequest(BaseModel):
+    sensor_states: dict[str, str] = Field(default_factory=dict)
+    sensor_weights: dict[str, float] = Field(default_factory=dict)
+    state_options: dict[str, list[str]] = Field(default_factory=dict)
+    include_current: bool = True
+    max_results: int = Field(default=8, ge=1, le=20)
+
+
 class FeedbackRequest(BaseModel):
     correct: bool
     expected_state: str | None = Field(default=None, max_length=100)
@@ -567,6 +582,28 @@ def evaluate_actuator(
         raise HTTPException(status_code=404, detail=str(exc)) from exc
 
 
+@router.post("/{actuator_entity_id}/simulate", response_model=list[SimulationOutcome])
+def simulate_actuator(
+    actuator_entity_id: str,
+    payload: SimulationRequest,
+    request: Request,
+) -> list[SimulationOutcome]:
+    try:
+        _validate_simulation_payload(payload)
+        return _behavior(request).simulate(
+            actuator_entity_id,
+            sensor_states=payload.sensor_states,
+            sensor_weights=payload.sensor_weights,
+            state_options=payload.state_options,
+            include_current=payload.include_current,
+            max_results=payload.max_results,
+        )
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
 @router.post("/{actuator_entity_id}/feedback", response_model=ActuatorRecord)
 def record_feedback(
     actuator_entity_id: str,
@@ -885,6 +922,22 @@ def _validate_weight_payload(payload: WeightOverrideRequest) -> None:
                 raise ValueError(f"Ungültige Entity-ID in Gruppe {group.name}: {entity_id}")
 
 
+def _validate_simulation_payload(payload: SimulationRequest) -> None:
+    for entity_id in [
+        *payload.sensor_states.keys(),
+        *payload.sensor_weights.keys(),
+        *payload.state_options.keys(),
+    ]:
+        if "." not in entity_id:
+            raise ValueError(f"Ungültige Entity-ID: {entity_id}")
+    for entity_id, weight in payload.sensor_weights.items():
+        if not 0.0 <= weight <= 1.0:
+            raise ValueError(f"Ungültige Gewichtung für {entity_id}: {weight}")
+    for entity_id, states in payload.state_options.items():
+        if not states:
+            raise ValueError(f"Keine Zustände für {entity_id} angegeben.")
+
+
 def _reconciliation_state_or_default(request: Request) -> ReconciliationState:
     store = getattr(request.app.state, "actuator_store", None)
     if not isinstance(store, ActuatorStore):