Harden RC7 API response contracts

backend/app/api/routes/segmentation.py

@@ -6,7 +6,19 @@ from fastapi import APIRouter, Depends
 from sqlalchemy.orm import Session
 
 from app.db.session import get_db
-from app.schemas import SegmentationQaRequest, SegmentationRunRequest
+from app.schemas import (
+    AnalysisQaResponse,
+    Envelope,
+    GeoJsonFeatureCollection,
+    SegmentationListResponse,
+    SegmentationModelsResponse,
+    SegmentationQaRequest,
+    SegmentationRead,
+    SegmentationRunListResponse,
+    SegmentationRunRead,
+    SegmentationRunRequest,
+    SegmentationRunResponse,
+)
 from app.services.model_registry_service import ModelRegistryService
 from app.services.segmentation_service import SegmentationService
 from app.utils.response import envelope
@@ -14,12 +26,12 @@ from app.utils.response import envelope
 router = APIRouter(prefix="/segmentation", tags=["segmentation"])
 
 
-@router.get("/models", response_model=dict)
+@router.get("/models", response_model=Envelope[SegmentationModelsResponse])
 def list_segmentation_models() -> dict:
     return envelope({"models": [model.model_dump() for model in ModelRegistryService.list_model_capabilities(task_type="segmentation")]})
 
 
-@router.post("/run", response_model=dict)
+@router.post("/run", response_model=Envelope[SegmentationRunResponse])
 def run_segmentation(payload: SegmentationRunRequest, db: Session = Depends(get_db)) -> dict:
     result = SegmentationService.run_segmentation(
         db=db,
@@ -34,7 +46,7 @@ def run_segmentation(payload: SegmentationRunRequest, db: Session = Depends(get_
     return envelope(result.model_dump())
 
 
-@router.get("/runs", response_model=dict)
+@router.get("/runs", response_model=Envelope[SegmentationRunListResponse])
 def list_segmentation_runs(
     project_id: UUID | None = None,
     dataset_id: UUID | None = None,
@@ -43,12 +55,15 @@ def list_segmentation_runs(
     return envelope(SegmentationService.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[SegmentationRunRead])
 def get_segmentation_run(analysis_run_id: UUID, db: Session = Depends(get_db)) -> dict:
     return envelope(SegmentationService.get_run(db, analysis_run_id).model_dump())
 
 
-@router.get("/runs/{analysis_run_id}/segmentations", response_model=dict)
+@router.get(
+    "/runs/{analysis_run_id}/segmentations",
+    response_model=Envelope[SegmentationListResponse],
+)
 def list_segmentation_run_outputs(
     analysis_run_id: UUID,
     dataset_id: UUID | None = None,
@@ -67,7 +82,10 @@ def list_segmentation_run_outputs(
     )
 
 
-@router.get("/datasets/{dataset_id}/segmentations", response_model=dict)
+@router.get(
+    "/datasets/{dataset_id}/segmentations",
+    response_model=Envelope[SegmentationListResponse],
+)
 def list_dataset_segmentations(
     dataset_id: UUID,
     analysis_run_id: UUID | None = None,
@@ -86,12 +104,15 @@ def list_dataset_segmentations(
     )
 
 
-@router.get("/segmentations/{segmentation_id}", response_model=dict)
+@router.get("/segmentations/{segmentation_id}", response_model=Envelope[SegmentationRead])
 def get_segmentation(segmentation_id: UUID, db: Session = Depends(get_db)) -> dict:
     return envelope(SegmentationService.get_segmentation(db, segmentation_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_segmentation_run_geojson(
     analysis_run_id: UUID,
     class_name: str | None = None,
@@ -108,7 +129,10 @@ def get_segmentation_run_geojson(
     )
 
 
-@router.get("/datasets/{dataset_id}/geojson", response_model=dict)
+@router.get(
+    "/datasets/{dataset_id}/geojson",
+    response_model=Envelope[GeoJsonFeatureCollection],
+)
 def get_dataset_segmentation_geojson(
     dataset_id: UUID,
     analysis_run_id: UUID | None = None,
@@ -127,7 +151,10 @@ def get_dataset_segmentation_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_segmentation_run_with_reference(
     analysis_run_id: UUID,
     payload: SegmentationQaRequest,