ML-009: add explainable predictions

Closes #20

backend/routes/ml.py

@@ -35,6 +35,22 @@ class PredictResponse(BaseModel):
     predictions: dict[str, float]
     confidence: float
     model_type: str
+    explanations: dict[str, "FeatureExplanationResponse"]
+
+
+class FeatureExplanationResponse(BaseModel):
+    feature: str
+    current_value: float
+    predicted_value: float
+    change: float
+    direction: str
+    sample_count: int
+    historical_mean: float
+    historical_range: tuple[float, float]
+    standard_deviation: float
+    trend_per_step: float
+    confidence: float
+    summary: str
 
 
 class BatchRequest(BaseModel):
@@ -182,6 +198,10 @@ def predict(payload: PredictRequest, request: Request) -> PredictResponse:
         predictions=prediction.predictions,
         confidence=prediction.confidence,
         model_type=prediction.model_type,
+        explanations={
+            name: FeatureExplanationResponse(**explanation.__dict__)
+            for name, explanation in prediction.explanations.items()
+        },
     )
 
 
@@ -208,6 +228,10 @@ def predict_batch(payload: BatchRequest, request: Request) -> BatchResponse:
                 predictions=prediction.predictions,
                 confidence=prediction.confidence,
                 model_type=prediction.model_type,
+                explanations={
+                    name: FeatureExplanationResponse(**explanation.__dict__)
+                    for name, explanation in prediction.explanations.items()
+                },
             )
         )
     return BatchResponse(predictions=responses)