Harden RC7 API response contracts

backend/app/api/routes/detection.py

@@ -6,7 +6,21 @@ from fastapi import APIRouter, Depends
 from sqlalchemy.orm import Session
 
 from app.db.session import get_db
-from app.schemas import DetectionQaRequest, DetectionRunRequest
+from app.schemas import (
+    AnalysisQaResponse,
+    DetectionListResponse,
+    DetectionModelsResponse,
+    DetectionQaRequest,
+    DetectionRead,
+    DetectionRunListResponse,
+    DetectionRunRead,
+    DetectionRunRequest,
+    DetectionRunResponse,
+    Envelope,
+    GeoJsonFeatureCollection,
+    ModelAssetListResponse,
+    YoloPreflightResponse,
+)
 from app.services.detection_service import DetectionService
 from app.services.model_asset_catalog_service import ModelAssetCatalogService
 from app.services.model_registry_service import ModelRegistryService
@@ -16,17 +30,17 @@ from app.utils.response import envelope
 router = APIRouter(prefix="/detection", tags=["detection"])
 
 
-@router.get("/models", response_model=dict)
+@router.get("/models", response_model=Envelope[DetectionModelsResponse])
 def list_detection_models() -> dict:
     return envelope({"models": [model.model_dump() for model in ModelRegistryService.list_model_capabilities()]})
 
 
-@router.get("/model-assets", response_model=dict)
+@router.get("/model-assets", response_model=Envelope[ModelAssetListResponse])
 def list_detection_model_assets() -> dict:
     return envelope(ModelAssetCatalogService.list_assets().model_dump())
 
 
-@router.get("/yolo/preflight", response_model=dict)
+@router.get("/yolo/preflight", response_model=Envelope[YoloPreflightResponse])
 def get_yolo_preflight(
     tile_manifest_path: str | None = None,
     check_model_load: bool = False,
@@ -41,7 +55,7 @@ def get_yolo_preflight(
     )
 
 
-@router.post("/run", response_model=dict)
+@router.post("/run", response_model=Envelope[DetectionRunResponse])
 def run_detection(payload: DetectionRunRequest, db: Session = Depends(get_db)) -> dict:
     result = DetectionService.run_detection(
         db=db,
@@ -57,7 +71,7 @@ def run_detection(payload: DetectionRunRequest, db: Session = Depends(get_db)) -
     return envelope(result.model_dump())
 
 
-@router.get("/runs", response_model=dict)
+@router.get("/runs", response_model=Envelope[DetectionRunListResponse])
 def list_detection_runs(
     project_id: UUID | None = None,
     dataset_id: UUID | None = None,
@@ -66,12 +80,15 @@ def list_detection_runs(
     return envelope(DetectionService.list_runs(db, project_id=project_id, dataset_id=dataset_id).model_dump())
 
 
-@router.get("/runs/{analysis_run_id}", response_model=dict)
+@router.get("/runs/{analysis_run_id}", response_model=Envelope[DetectionRunRead])
 def get_detection_run(analysis_run_id: UUID, db: Session = Depends(get_db)) -> dict:
     return envelope(DetectionService.get_run(db, analysis_run_id).model_dump())
 
 
-@router.get("/runs/{analysis_run_id}/detections", response_model=dict)
+@router.get(
+    "/runs/{analysis_run_id}/detections",
+    response_model=Envelope[DetectionListResponse],
+)
 def list_detection_run_detections(
     analysis_run_id: UUID,
     dataset_id: UUID | None = None,
@@ -90,7 +107,10 @@ def list_detection_run_detections(
     )
 
 
-@router.get("/datasets/{dataset_id}/detections", response_model=dict)
+@router.get(
+    "/datasets/{dataset_id}/detections",
+    response_model=Envelope[DetectionListResponse],
+)
 def list_dataset_detections(
     dataset_id: UUID,
     analysis_run_id: UUID | None = None,
@@ -109,12 +129,15 @@ def list_dataset_detections(
     )
 
 
-@router.get("/detections/{detection_id}", response_model=dict)
+@router.get("/detections/{detection_id}", response_model=Envelope[DetectionRead])
 def get_detection(detection_id: UUID, db: Session = Depends(get_db)) -> dict:
     return envelope(DetectionService.get_detection(db, detection_id).model_dump())
 
 
-@router.get("/runs/{analysis_run_id}/geojson", response_model=dict)
+@router.get(
+    "/runs/{analysis_run_id}/geojson",
+    response_model=Envelope[GeoJsonFeatureCollection],
+)
 def get_detection_run_geojson(
     analysis_run_id: UUID,
     class_name: str | None = None,
@@ -131,7 +154,10 @@ def get_detection_run_geojson(
     )
 
 
-@router.get("/datasets/{dataset_id}/geojson", response_model=dict)
+@router.get(
+    "/datasets/{dataset_id}/geojson",
+    response_model=Envelope[GeoJsonFeatureCollection],
+)
 def get_dataset_detection_geojson(
     dataset_id: UUID,
     analysis_run_id: UUID | None = None,
@@ -150,7 +176,10 @@ def get_dataset_detection_geojson(
     )
 
 
-@router.post("/runs/{analysis_run_id}/qa/reference", response_model=dict)
+@router.post(
+    "/runs/{analysis_run_id}/qa/reference",
+    response_model=Envelope[AnalysisQaResponse],
+)
 def compare_detection_run_with_reference(
     analysis_run_id: UUID,
     payload: DetectionQaRequest,