Merge pull request #575 from abhishek-8081/issue-543-fix

Author: marcvergees

app/api/routes/forms.py

@@ -23,7 +23,7 @@ def fill_form(form: FormFill, db: Session = Depends(get_db)):
 
     fetched_template = get_template(db, form.template_id)
     if not fetched_template:
-        raise AppError("Template not found", status_code=404)
+        raise AppError("Template not found", status_code=404, error_code="TEMPLATE_NOT_FOUND")
 
     controller = Controller()
     try:
@@ -40,7 +40,7 @@ def fill_form(form: FormFill, db: Session = Depends(get_db)):
         )
         return create_form(db, submission)
     except Exception as e:
-        raise AppError(str(e), status_code=500)
+        raise AppError(str(e), status_code=500, error_code="FORM_FILL_ERROR")
 
 
 @router.get("/models", response_model=ModelsResponse)
@@ -93,9 +93,10 @@ def transcribe(audio: UploadFile = File(...)):
             f"Could not connect to the speech-to-text service at {whisper_url}. "
             "Please ensure the whisper service is running.",
             status_code=503,
+            error_code="STT_UNAVAILABLE",
         )
     except requests.exceptions.RequestException as e:
-        raise AppError(f"Transcription failed: {e}", status_code=502)
+        raise AppError(f"Transcription failed: {e}", status_code=502, error_code="TRANSCRIPTION_FAILED")
 
     try:
         text = (response.json().get("text") or "").strip()

app/api/schemas/common.py

@@ -1,14 +1,55 @@
-from pydantic import BaseModel
+from __future__ import annotations
+
+from datetime import datetime
 from typing import Any
 
-class SuccessResponse(BaseModel):
-    success: bool = True
-    data: Any
+from pydantic import BaseModel, ConfigDict
+
+from app.api.schemas.enums import JobStatus, JobType
+
+
+class ValidationErrorItem(BaseModel):
+    model_config = ConfigDict()
+    field: str | None = None
+    issue: str | None = None
+    value: Any = None
 
-class ErrorDetail(BaseModel):
-    code: str
-    message: str
 
 class ErrorResponse(BaseModel):
-    success: bool = False
-    error: ErrorDetail
+    model_config = ConfigDict()
+    error_code: str
+    message: str
+    detail: dict[str, Any] | None = None
+    retry_after_seconds: int | None = None
+    validation_errors: list[ValidationErrorItem] | None = None
+
+
+class Pagination(BaseModel):
+    model_config = ConfigDict()
+    total: int
+    page: int
+    per_page: int
+    total_pages: int
+    has_next: bool
+    has_prev: bool
+
+
+class AsyncJobResponse(BaseModel):
+    model_config = ConfigDict()
+    job_id: str
+    job_type: JobType | None = None
+    status: JobStatus
+    estimated_seconds: int | None = None
+    poll_url: str | None = None
+
+
+class Job(BaseModel):
+    model_config = ConfigDict()
+    job_id: str
+    job_type: JobType
+    status: JobStatus
+    progress_percent: int | None = None
+    result_url: str | None = None
+    error: ErrorResponse | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

app/api/schemas/enums.py

@@ -0,0 +1,111 @@
+from enum import Enum
+
+
+class InputStatus(str, Enum):
+    queued = "queued"
+    transcribing = "transcribing"
+    ready = "ready"
+    failed = "failed"
+
+
+class ExtractionStatus(str, Enum):
+    processing = "processing"
+    completed = "completed"
+    failed = "failed"
+    needs_review = "needs_review"
+
+
+class FormStatus(str, Enum):
+    queued = "queued"
+    generating = "generating"
+    completed = "completed"
+    failed = "failed"
+
+
+class ReportStatus(str, Enum):
+    draft = "draft"
+    under_review = "under_review"
+    approved = "approved"
+    submitted = "submitted"
+
+
+class JobStatus(str, Enum):
+    queued = "queued"
+    processing = "processing"
+    completed = "completed"
+    failed = "failed"
+
+
+class JobType(str, Enum):
+    transcription = "transcription"
+    extraction = "extraction"
+    form_generation = "form_generation"
+    batch_form_generation = "batch_form_generation"
+    report_generation = "report_generation"
+
+
+class FormType(str, Enum):
+    neris = "neris"
+    nemsis_epcr = "nemsis_epcr"
+    nibrs = "nibrs"
+    nfirs_basic = "nfirs_basic"
+    nfirs_fire = "nfirs_fire"
+    nfirs_structure = "nfirs_structure"
+    nfirs_wildland = "nfirs_wildland"
+    nfirs_ems = "nfirs_ems"
+    nfirs_hazmat = "nfirs_hazmat"
+    nfirs_apparatus = "nfirs_apparatus"
+    nfirs_personnel = "nfirs_personnel"
+    nfirs_arson = "nfirs_arson"
+    nfirs_casualty_civilian = "nfirs_casualty_civilian"
+    nfirs_casualty_responder = "nfirs_casualty_responder"
+    cal_fire_ics209 = "cal_fire_ics209"
+    osha_301 = "osha_301"
+    un_ssirs = "un_ssirs"
+    state_georgia = "state_georgia"
+    state_california = "state_california"
+    state_new_york = "state_new_york"
+
+
+class IncidentCategory(str, Enum):
+    fire = "fire"
+    ems = "ems"
+    rescue = "rescue"
+    hazardous_conditions = "hazardous_conditions"
+    service_call = "service_call"
+    good_intent = "good_intent"
+    false_alarm = "false_alarm"
+    law_enforcement = "law_enforcement"
+
+
+class CauseCertainty(str, Enum):
+    confirmed = "confirmed"
+    probable = "probable"
+    suspected = "suspected"
+    undetermined = "undetermined"
+
+
+class InjurySeverity(str, Enum):
+    minor = "minor"
+    moderate = "moderate"
+    severe = "severe"
+    fatal = "fatal"
+
+
+class RateOfSpread(str, Enum):
+    slow = "slow"
+    moderate = "moderate"
+    rapid = "rapid"
+    extreme = "extreme"
+
+
+class PeriodType(str, Enum):
+    monthly = "monthly"
+    quarterly = "quarterly"
+    annual = "annual"
+
+
+class OutputFormat(str, Enum):
+    pdf = "pdf"
+    json = "json"
+    both = "both"

app/api/v1/routes/system.py

@@ -161,8 +161,6 @@ def get_health():
 
 @router.get("/schema/incident", summary="Get canonical incident JSON Schema")
 def get_schema_incident():
-    # PROVISIONAL: This 501 body shape is not canonical — it will be updated
-    # to match the standardized ErrorResponse envelope once #543 lands.
     return JSONResponse(
         status_code=501,
         content={
@@ -174,7 +172,6 @@ def get_schema_incident():
 
 @router.get("/schema/incident/versions", summary="Get incident schema version history")
 def get_schema_versions():
-    # PROVISIONAL: Same as /schema/incident — shape will align with #543.
     return JSONResponse(
         status_code=501,
         content={

app/core/config.py

@@ -44,3 +44,8 @@
     for origin in os.getenv("FRONTEND_ORIGINS", _DEFAULT_ORIGINS).split(",")
     if origin.strip()
 ]
+
+# --- Error handling -------------------------------------------------------
+# Advisory Retry-After sent to clients on 503 responses. This is a client
+# hint, not a measured backpressure value — the app has no queue-depth signal.
+RETRY_AFTER_SECONDS = 30

app/core/errors/base.py

@@ -1,4 +1,23 @@
+def _default_error_code(status_code: int) -> str:
+    return {
+        400: "BAD_REQUEST",
+        404: "NOT_FOUND",
+        422: "VALIDATION_ERROR",
+        500: "INTERNAL_ERROR",
+        502: "BAD_GATEWAY",
+        503: "SERVICE_UNAVAILABLE",
+    }.get(status_code, "ERROR")
+
+
 class AppError(Exception):
-    def __init__(self, message: str, status_code: int = 400):
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 400,
+        error_code: str | None = None,
+        detail: dict | None = None,
+    ):
         self.message = message
-        self.status_code = status_code
+        self.status_code = status_code
+        self.error_code = error_code or _default_error_code(status_code)
+        self.detail = detail

app/core/errors/handlers.py

@@ -1,11 +1,37 @@
 from fastapi import Request
+from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
+
+from app.core.config import RETRY_AFTER_SECONDS
 from app.core.errors.base import AppError
 
+
 def register_exception_handlers(app):
     @app.exception_handler(AppError)
     async def app_error_handler(request: Request, exc: AppError):
+        body: dict = {"error_code": exc.error_code, "message": exc.message}
+        if exc.detail is not None:
+            body["detail"] = exc.detail
+        if exc.status_code == 503:
+            body["retry_after_seconds"] = RETRY_AFTER_SECONDS
+        return JSONResponse(status_code=exc.status_code, content=body)
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_error_handler(request: Request, exc: RequestValidationError):
+        validation_errors = []
+        for error in exc.errors():
+            loc = error.get("loc", ())
+            field = ".".join(str(x) for x in loc if x != "body")
+            validation_errors.append({
+                "field": field or None,
+                "issue": error.get("msg"),
+                "value": error.get("input"),
+            })
         return JSONResponse(
-            status_code=exc.status_code,
-            content={"error": exc.message},
-        )
+            status_code=422,
+            content={
+                "error_code": "VALIDATION_ERROR",
+                "message": "Request validation failed",
+                "validation_errors": validation_errors,
+            },
+        )

tests/test_api.py

@@ -210,12 +210,18 @@ def test_fill_form_template_file_not_found(self, client, mock_controller):
             "input_text": "some text",
         })
         assert resp.status_code == 500
-        assert "PDF template not found" in resp.json()["error"]
+        assert resp.json()["error_code"] == "FORM_FILL_ERROR"
+        assert "PDF template not found" in resp.json()["message"]
 
     def test_fill_form_validates_body(self, client):
-        """Missing required fields → 422."""
+        """Missing required fields → 422 with contract envelope."""
         resp = client.post("/forms/fill", json={})
         assert resp.status_code == 422
+        body = resp.json()
+        assert body["error_code"] == "VALIDATION_ERROR"
+        assert len(body["validation_errors"]) >= 1
+        assert body["validation_errors"][0]["field"] is not None
+        assert body["validation_errors"][0]["issue"] is not None
 
     def test_transcribe_success(self, client, monkeypatch):
         """Audio is forwarded to the whisper sidecar and its text returned."""