truthound-dashboard 1.4.4__py3-none-any.whl → 1.5.0__py3-none-any.whl

truthound_dashboard/api/drift_monitor.py

@@ -1,6 +1,12 @@
 """Drift monitoring API endpoints.
 
 This module provides REST API endpoints for drift monitoring management.
+
+API Design: Direct Response Style
+- Single resources return the resource directly
+- List endpoints return PaginatedResponse with data, total, offset, limit
+- Errors are handled via HTTPException
+- Success is indicated by HTTP status codes (200, 201, 204)
 """
 
 from __future__ import annotations
@@ -8,6 +14,7 @@ from __future__ import annotations
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel, Field
 
 from truthound_dashboard.core.drift_monitor import DriftMonitorService
 from truthound_dashboard.schemas.drift_monitor import (
@@ -15,16 +22,20 @@ from truthound_dashboard.schemas.drift_monitor import (
     DriftMonitorUpdate,
     DriftMonitorResponse,
     DriftMonitorListResponse,
+    DriftMonitorSummary,
     DriftAlertResponse,
     DriftAlertListResponse,
     DriftAlertUpdate,
-    DriftMonitorSummary,
     DriftTrendResponse,
     DriftPreviewRequest,
-    DriftPreviewResponse,
-    SamplingConfig,
-    SampledComparisonRequest,
+    DriftPreviewData,
+    RootCauseAnalysis,
+    SampleSizeEstimateResponse,
+    JobProgressResponse,
+    SampledComparisonResult,
+    MonitorRunResult,
 )
+from truthound_dashboard.schemas.base import MessageResponse
 from .deps import SessionDep
 
 router = APIRouter()
@@ -44,7 +55,7 @@ DriftMonitorServiceDep = Annotated[DriftMonitorService, Depends(get_drift_monito
 
 @router.post(
     "/drift/monitors",
-    response_model=dict,
+    response_model=DriftMonitorResponse,
     status_code=201,
     summary="Create drift monitor",
     description="Create a new drift monitor for automatic drift detection.",
@@ -52,7 +63,7 @@ DriftMonitorServiceDep = Annotated[DriftMonitorService, Depends(get_drift_monito
 async def create_monitor(
     request: DriftMonitorCreate,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> DriftMonitorResponse:
     """Create a new drift monitor."""
     monitor = await service.create_monitor(
         name=request.name,
@@ -68,10 +79,7 @@ async def create_monitor(
         notification_channel_ids=request.notification_channel_ids,
     )
 
-    return {
-        "success": True,
-        "data": _monitor_to_dict(monitor),
-    }
+    return DriftMonitorResponse(**_monitor_to_dict(monitor))
 
 
 @router.get(
@@ -94,7 +102,6 @@ async def list_monitors(
     )
 
     return DriftMonitorListResponse(
-        success=True,
         data=[DriftMonitorResponse(**_monitor_to_dict(m)) for m in monitors],
         total=total,
         offset=offset,
@@ -104,28 +111,28 @@ async def list_monitors(
 
 @router.get(
     "/drift/monitors/summary",
-    response_model=dict,
+    response_model=DriftMonitorSummary,
     summary="Get monitors summary",
     description="Get summary statistics for all drift monitors.",
 )
 async def get_monitors_summary(
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> DriftMonitorSummary:
     """Get summary of all drift monitors."""
     summary = await service.get_summary()
-    return {"success": True, "data": summary}
+    return DriftMonitorSummary(**summary)
 
 
 @router.post(
     "/drift/preview",
-    response_model=DriftPreviewResponse,
+    response_model=DriftPreviewData,
     summary="Preview drift comparison",
     description="Preview drift comparison results without creating a monitor or saving results.",
 )
 async def preview_drift(
     request: DriftPreviewRequest,
     service: DriftMonitorServiceDep,
-) -> DriftPreviewResponse:
+) -> DriftPreviewData:
     """Preview drift comparison without persisting results.
 
     This endpoint allows users to see drift comparison results before
@@ -139,10 +146,7 @@ async def preview_drift(
             method=request.method,
             threshold=request.threshold,
         )
-        return DriftPreviewResponse(
-            success=True,
-            data=preview_result,
-        )
+        return DriftPreviewData(**preview_result)
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e))
     except Exception as e:
@@ -151,25 +155,25 @@ async def preview_drift(
 
 @router.get(
     "/drift/monitors/{monitor_id}",
-    response_model=dict,
+    response_model=DriftMonitorResponse,
     summary="Get drift monitor",
     description="Get a drift monitor by ID.",
 )
 async def get_monitor(
     monitor_id: str,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> DriftMonitorResponse:
     """Get a drift monitor by ID."""
     monitor = await service.get_monitor(monitor_id)
     if not monitor:
         raise HTTPException(status_code=404, detail="Monitor not found")
 
-    return {"success": True, "data": _monitor_to_dict(monitor)}
+    return DriftMonitorResponse(**_monitor_to_dict(monitor))
 
 
 @router.put(
     "/drift/monitors/{monitor_id}",
-    response_model=dict,
+    response_model=DriftMonitorResponse,
     summary="Update drift monitor",
     description="Update a drift monitor configuration.",
 )
@@ -177,7 +181,7 @@ async def update_monitor(
     monitor_id: str,
     request: DriftMonitorUpdate,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> DriftMonitorResponse:
     """Update a drift monitor."""
     update_data = request.model_dump(exclude_unset=True)
     monitor = await service.update_monitor(monitor_id, **update_data)
@@ -185,56 +189,63 @@ async def update_monitor(
     if not monitor:
         raise HTTPException(status_code=404, detail="Monitor not found")
 
-    return {"success": True, "data": _monitor_to_dict(monitor)}
+    return DriftMonitorResponse(**_monitor_to_dict(monitor))
 
 
 @router.delete(
     "/drift/monitors/{monitor_id}",
-    response_model=dict,
+    response_model=MessageResponse,
     summary="Delete drift monitor",
     description="Delete a drift monitor.",
 )
 async def delete_monitor(
     monitor_id: str,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> MessageResponse:
     """Delete a drift monitor."""
     deleted = await service.delete_monitor(monitor_id)
     if not deleted:
         raise HTTPException(status_code=404, detail="Monitor not found")
 
-    return {"success": True, "message": "Monitor deleted"}
+    return MessageResponse(message="Monitor deleted")
 
 
 @router.post(
     "/drift/monitors/{monitor_id}/run",
-    response_model=dict,
+    response_model=MonitorRunResult,
     summary="Run drift monitor",
     description="Manually trigger a drift monitoring run.",
 )
 async def run_monitor(
     monitor_id: str,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> MonitorRunResult:
     """Manually run a drift monitor."""
-    comparison = await service.run_monitor(monitor_id)
+    # force=True allows running paused monitors manually
+    comparison = await service.run_monitor(monitor_id, force=True)
     if not comparison:
         raise HTTPException(status_code=400, detail="Monitor run failed")
 
-    return {
-        "success": True,
-        "data": {
-            "comparison_id": comparison.id,
-            "has_drift": comparison.has_drift,
-            "drift_percentage": comparison.drift_percentage,
-            "drifted_columns": comparison.drifted_columns,
-        },
-    }
+    # Extract drifted column names from result_json
+    drifted_column_names: list[str] = []
+    if comparison.result_json and "columns" in comparison.result_json:
+        drifted_column_names = [
+            col["column"]
+            for col in comparison.result_json["columns"]
+            if col.get("drifted", False)
+        ]
+
+    return MonitorRunResult(
+        comparison_id=comparison.id,
+        has_drift=comparison.has_drift,
+        drift_percentage=comparison.drift_percentage or 0.0,
+        drifted_columns=drifted_column_names,
+    )
 
 
 @router.get(
     "/drift/monitors/{monitor_id}/trend",
-    response_model=dict,
+    response_model=DriftTrendResponse,
     summary="Get drift trend",
     description="Get drift trend data for a monitor over time.",
 )
@@ -242,18 +253,153 @@ async def get_monitor_trend(
     monitor_id: str,
     service: DriftMonitorServiceDep,
     days: int = Query(30, ge=1, le=365),
-) -> dict:
+) -> DriftTrendResponse:
     """Get drift trend for a monitor."""
     trend = await service.get_trend(monitor_id, days=days)
     if not trend:
         raise HTTPException(status_code=404, detail="Monitor not found")
 
-    return {"success": True, "data": trend}
+    return DriftTrendResponse(**trend)
+
+
+# Run History Endpoints
+
+from truthound_dashboard.schemas.drift_monitor import (
+    DriftMonitorRunResponse,
+    DriftMonitorRunListResponse,
+    DriftMonitorRunStatistics,
+)
+
+
+@router.get(
+    "/drift/monitors/{monitor_id}/runs",
+    response_model=DriftMonitorRunListResponse,
+    summary="List monitor runs",
+    description="Get execution history for a drift monitor.",
+)
+async def list_monitor_runs(
+    monitor_id: str,
+    service: DriftMonitorServiceDep,
+    status: str | None = Query(None, description="Filter by status"),
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+) -> DriftMonitorRunListResponse:
+    """List runs for a drift monitor."""
+    runs, total = await service.list_runs(
+        monitor_id=monitor_id,
+        status=status,
+        limit=limit,
+        offset=offset,
+    )
+
+    return DriftMonitorRunListResponse(
+        data=[
+            DriftMonitorRunResponse(
+                id=run.id,
+                monitor_id=run.monitor_id,
+                status=run.status,
+                has_drift=run.has_drift,
+                max_drift_score=run.max_drift_score,
+                total_columns=run.total_columns,
+                drifted_columns=run.drifted_columns,
+                column_results=run.column_results,
+                root_cause_analysis=run.root_cause_analysis,
+                duration_ms=run.duration_ms,
+                error_message=run.error_message,
+                created_at=run.created_at,
+                completed_at=run.completed_at,
+            )
+            for run in runs
+        ],
+        total=total,
+        offset=offset,
+        limit=limit,
+    )
+
+
+@router.get(
+    "/drift/monitors/{monitor_id}/runs/latest",
+    response_model=DriftMonitorRunResponse | None,
+    summary="Get latest run",
+    description="Get the most recent run for a drift monitor.",
+)
+async def get_latest_run(
+    monitor_id: str,
+    service: DriftMonitorServiceDep,
+) -> DriftMonitorRunResponse | None:
+    """Get the latest run for a monitor."""
+    run = await service.get_latest_run(monitor_id)
+    if not run:
+        return None
+
+    return DriftMonitorRunResponse(
+        id=run.id,
+        monitor_id=run.monitor_id,
+        status=run.status,
+        has_drift=run.has_drift,
+        max_drift_score=run.max_drift_score,
+        total_columns=run.total_columns,
+        drifted_columns=run.drifted_columns,
+        column_results=run.column_results,
+        root_cause_analysis=run.root_cause_analysis,
+        duration_ms=run.duration_ms,
+        error_message=run.error_message,
+        created_at=run.created_at,
+        completed_at=run.completed_at,
+    )
+
+
+@router.get(
+    "/drift/monitors/{monitor_id}/runs/statistics",
+    response_model=DriftMonitorRunStatistics,
+    summary="Get run statistics",
+    description="Get aggregated statistics for drift monitor runs.",
+)
+async def get_run_statistics(
+    monitor_id: str,
+    service: DriftMonitorServiceDep,
+) -> DriftMonitorRunStatistics:
+    """Get run statistics for a monitor."""
+    stats = await service.get_run_statistics(monitor_id)
+    return DriftMonitorRunStatistics(**stats)
+
+
+@router.get(
+    "/drift/monitors/{monitor_id}/runs/{run_id}",
+    response_model=DriftMonitorRunResponse,
+    summary="Get run details",
+    description="Get detailed information about a specific run.",
+)
+async def get_run(
+    monitor_id: str,
+    run_id: str,
+    service: DriftMonitorServiceDep,
+) -> DriftMonitorRunResponse:
+    """Get a specific run."""
+    run = await service.get_run(run_id)
+    if not run or run.monitor_id != monitor_id:
+        raise HTTPException(status_code=404, detail="Run not found")
+
+    return DriftMonitorRunResponse(
+        id=run.id,
+        monitor_id=run.monitor_id,
+        status=run.status,
+        has_drift=run.has_drift,
+        max_drift_score=run.max_drift_score,
+        total_columns=run.total_columns,
+        drifted_columns=run.drifted_columns,
+        column_results=run.column_results,
+        root_cause_analysis=run.root_cause_analysis,
+        duration_ms=run.duration_ms,
+        error_message=run.error_message,
+        created_at=run.created_at,
+        completed_at=run.completed_at,
+    )
 
 
 @router.get(
     "/drift/monitors/{monitor_id}/runs/{run_id}/root-cause",
-    response_model=dict,
+    response_model=RootCauseAnalysis,
     summary="Analyze drift root cause",
     description="Analyze root causes of drift for a specific comparison run.",
 )
@@ -261,7 +407,7 @@ async def get_root_cause_analysis(
     monitor_id: str,
     run_id: str,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> RootCauseAnalysis:
     """Get root cause analysis for a drift run.
 
     Analyzes a drift comparison to identify why drift is occurring,
@@ -272,19 +418,19 @@ async def get_root_cause_analysis(
     if not analysis:
         raise HTTPException(status_code=404, detail="Drift run not found")
 
-    return {"success": True, "data": analysis}
+    return RootCauseAnalysis(**analysis)
 
 
 @router.get(
     "/drift/comparisons/{run_id}/root-cause",
-    response_model=dict,
+    response_model=RootCauseAnalysis,
     summary="Analyze drift root cause (standalone)",
     description="Analyze root causes for a drift comparison without a monitor.",
 )
 async def get_comparison_root_cause_analysis(
     run_id: str,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> RootCauseAnalysis:
     """Get root cause analysis for a standalone drift comparison.
 
     Similar to the monitor-based endpoint but for one-off comparisons.
@@ -293,7 +439,7 @@ async def get_comparison_root_cause_analysis(
     if not analysis:
         raise HTTPException(status_code=404, detail="Drift comparison not found")
 
-    return {"success": True, "data": analysis}
+    return RootCauseAnalysis(**analysis)
 
 
 # Alert Endpoints
@@ -323,7 +469,6 @@ async def list_alerts(
     )
 
     return DriftAlertListResponse(
-        success=True,
         data=[DriftAlertResponse(**_alert_to_dict(a)) for a in alerts],
         total=total,
         offset=offset,
@@ -333,25 +478,25 @@ async def list_alerts(
 
 @router.get(
     "/drift/alerts/{alert_id}",
-    response_model=dict,
+    response_model=DriftAlertResponse,
     summary="Get drift alert",
     description="Get a drift alert by ID.",
 )
 async def get_alert(
     alert_id: str,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> DriftAlertResponse:
     """Get a drift alert by ID."""
     alert = await service.get_alert(alert_id)
     if not alert:
         raise HTTPException(status_code=404, detail="Alert not found")
 
-    return {"success": True, "data": _alert_to_dict(alert)}
+    return DriftAlertResponse(**_alert_to_dict(alert))
 
 
 @router.put(
     "/drift/alerts/{alert_id}",
-    response_model=dict,
+    response_model=DriftAlertResponse,
     summary="Update drift alert",
     description="Update a drift alert status or notes.",
 )
@@ -359,7 +504,7 @@ async def update_alert(
     alert_id: str,
     request: DriftAlertUpdate,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> DriftAlertResponse:
     """Update a drift alert."""
     alert = await service.update_alert(
         alert_id,
@@ -370,7 +515,7 @@ async def update_alert(
     if not alert:
         raise HTTPException(status_code=404, detail="Alert not found")
 
-    return {"success": True, "data": _alert_to_dict(alert)}
+    return DriftAlertResponse(**_alert_to_dict(alert))
 
 
 # Large-Scale Dataset Optimization Endpoints
@@ -378,7 +523,7 @@ async def update_alert(
 
 @router.post(
     "/drift/monitors/{monitor_id}/run-sampled",
-    response_model=dict,
+    response_model=SampledComparisonResult,
     summary="Run sampled drift comparison",
     description="Run drift comparison with sampling for large datasets (100M+ rows).",
 )
@@ -390,7 +535,7 @@ async def run_sampled_comparison(
     confidence_level: float = Query(0.95, ge=0.80, le=0.99, description="Target confidence level"),
     early_stop_threshold: float = Query(0.5, ge=0.1, le=1.0, description="Early stop threshold"),
     max_workers: int = Query(4, ge=1, le=16, description="Max parallel workers"),
-) -> dict:
+) -> SampledComparisonResult:
     """Run a sampled drift comparison for large datasets.
 
     Optimized for 100M+ row datasets with:
@@ -408,7 +553,7 @@ async def run_sampled_comparison(
             early_stop_threshold=early_stop_threshold,
             max_workers=max_workers,
         )
-        return {"success": True, "data": result}
+        return SampledComparisonResult(**result)
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e))
     except Exception as e:
@@ -417,7 +562,7 @@ async def run_sampled_comparison(
 
 @router.get(
     "/drift/estimate-sample-size",
-    response_model=dict,
+    response_model=SampleSizeEstimateResponse,
     summary="Estimate optimal sample size",
     description="Estimate optimal sample size for drift comparison between two sources.",
 )
@@ -427,7 +572,7 @@ async def estimate_sample_size(
     current_source_id: str = Query(..., description="Current source ID"),
     confidence_level: float = Query(0.95, ge=0.80, le=0.99, description="Target confidence level"),
     margin_of_error: float = Query(0.03, ge=0.01, le=0.10, description="Acceptable margin of error"),
-) -> dict:
+) -> SampleSizeEstimateResponse:
     """Estimate optimal sample size for a drift comparison.
 
     Returns recommended sample size based on dataset sizes and
@@ -441,7 +586,7 @@ async def estimate_sample_size(
             confidence_level=confidence_level,
             margin_of_error=margin_of_error,
         )
-        return {"success": True, "data": estimate}
+        return SampleSizeEstimateResponse(**estimate)
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e))
     except Exception as e:
@@ -450,14 +595,14 @@ async def estimate_sample_size(
 
 @router.get(
     "/drift/jobs/{job_id}/progress",
-    response_model=dict,
+    response_model=JobProgressResponse,
     summary="Get job progress",
     description="Get progress for an active sampled comparison job.",
 )
 async def get_job_progress(
     job_id: str,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> JobProgressResponse:
     """Get progress for an active comparison job.
 
     Returns current progress including:
@@ -470,25 +615,25 @@ async def get_job_progress(
     if not progress:
         raise HTTPException(status_code=404, detail="Job not found or completed")
 
-    return {"success": True, "data": progress}
+    return JobProgressResponse(**progress)
 
 
 @router.post(
     "/drift/jobs/{job_id}/cancel",
-    response_model=dict,
+    response_model=MessageResponse,
     summary="Cancel comparison job",
     description="Cancel an active sampled comparison job.",
 )
 async def cancel_job(
     job_id: str,
     service: DriftMonitorServiceDep,
-) -> dict:
+) -> MessageResponse:
     """Cancel an active comparison job."""
     cancelled = await service.cancel_job(job_id)
     if not cancelled:
         raise HTTPException(status_code=404, detail="Job not found or already completed")
 
-    return {"success": True, "message": "Job cancelled"}
+    return MessageResponse(message="Job cancelled")
 
 
 # Helper functions
@@ -496,11 +641,21 @@ async def cancel_job(
 
 def _monitor_to_dict(monitor) -> dict:
     """Convert monitor model to dictionary."""
+    # Get source names from relationships if available
+    baseline_source_name = None
+    current_source_name = None
+    if hasattr(monitor, "baseline_source") and monitor.baseline_source:
+        baseline_source_name = monitor.baseline_source.name
+    if hasattr(monitor, "current_source") and monitor.current_source:
+        current_source_name = monitor.current_source.name
+
     return {
         "id": monitor.id,
         "name": monitor.name,
         "baseline_source_id": monitor.baseline_source_id,
         "current_source_id": monitor.current_source_id,
+        "baseline_source_name": baseline_source_name,
+        "current_source_name": current_source_name,
         "cron_expression": monitor.cron_expression,
         "method": monitor.method,
         "threshold": monitor.threshold,
@@ -510,13 +665,13 @@ def _monitor_to_dict(monitor) -> dict:
         "alert_threshold_high": monitor.alert_threshold_high,
         "notification_channel_ids": monitor.notification_channel_ids_json,
         "status": monitor.status,
-        "last_run_at": monitor.last_run_at.isoformat() if monitor.last_run_at else None,
+        "last_run_at": monitor.last_run_at,
         "last_drift_detected": monitor.last_drift_detected,
         "total_runs": monitor.total_runs,
         "drift_detected_count": monitor.drift_detected_count,
         "consecutive_drift_count": monitor.consecutive_drift_count,
-        "created_at": monitor.created_at.isoformat() if monitor.created_at else None,
-        "updated_at": monitor.updated_at.isoformat() if monitor.updated_at else None,
+        "created_at": monitor.created_at,
+        "updated_at": monitor.updated_at,
     }
 
 
@@ -525,16 +680,16 @@ def _alert_to_dict(alert) -> dict:
     return {
         "id": alert.id,
         "monitor_id": alert.monitor_id,
-        "comparison_id": alert.comparison_id,
+        "comparison_id": alert.run_id,  # Map run_id to comparison_id for frontend compatibility
         "severity": alert.severity,
-        "drift_percentage": alert.drift_percentage,
-        "drifted_columns": alert.drifted_columns_json or [],
+        "drift_percentage": alert.drift_score,  # Map drift_score to drift_percentage
+        "drifted_columns": alert.affected_columns or [],  # Map affected_columns to drifted_columns
         "message": alert.message,
         "status": alert.status,
-        "acknowledged_at": alert.acknowledged_at.isoformat() if alert.acknowledged_at else None,
+        "acknowledged_at": alert.acknowledged_at,
         "acknowledged_by": alert.acknowledged_by,
-        "resolved_at": alert.resolved_at.isoformat() if alert.resolved_at else None,
+        "resolved_at": alert.resolved_at,
         "notes": alert.notes,
-        "created_at": alert.created_at.isoformat() if alert.created_at else None,
-        "updated_at": alert.updated_at.isoformat() if alert.updated_at else None,
+        "created_at": alert.created_at,
+        "updated_at": alert.updated_at,
     }