Initial commit

libs/schemas/responses.py

@@ -0,0 +1,69 @@
+"""API response models."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DocumentUploadResponse(BaseModel):
+    """Response model for document upload"""
+
+    doc_id: str = Field(..., description="Document identifier")
+    s3_url: str = Field(..., description="S3 URL")
+    checksum: str = Field(..., description="Document checksum")
+
+
+class ExtractionResponse(BaseModel):
+    """Response model for document extraction"""
+
+    extraction_id: str = Field(..., description="Extraction identifier")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="Overall confidence")
+    extracted_fields: dict[str, Any] = Field(..., description="Extracted fields")
+    provenance: list[dict[str, Any]] = Field(..., description="Provenance information")
+
+
+class RAGSearchResponse(BaseModel):
+    """Response model for RAG search"""
+
+    chunks: list[dict[str, Any]] = Field(..., description="Retrieved chunks")
+    citations: list[dict[str, Any]] = Field(..., description="Source citations")
+    kg_hints: list[dict[str, Any]] = Field(..., description="Knowledge graph hints")
+    calibrated_confidence: float = Field(
+        ..., ge=0.0, le=1.0, description="Calibrated confidence"
+    )
+
+
+class ScheduleComputeResponse(BaseModel):
+    """Response model for schedule computation"""
+
+    calculation_id: str = Field(..., description="Calculation identifier")
+    schedule: str = Field(..., description="Schedule identifier")
+    form_boxes: dict[str, dict[str, Any]] = Field(
+        ..., description="Computed form boxes"
+    )
+    evidence_trail: list[dict[str, Any]] = Field(..., description="Evidence trail")
+
+
+class HMRCSubmissionResponse(BaseModel):
+    """Response model for HMRC submission"""
+
+    submission_id: str = Field(..., description="Submission identifier")
+    status: str = Field(..., description="Submission status")
+    hmrc_reference: str | None = Field(None, description="HMRC reference")
+    submission_timestamp: datetime = Field(..., description="Submission timestamp")
+    validation_results: dict[str, Any] = Field(..., description="Validation results")
+
+
+class FirmSyncResponse(BaseModel):
+    """Response from firm sync operation"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    firm_id: str = Field(..., description="Firm identifier")
+    status: str = Field(..., description="Sync status: success, error, partial")
+    message: str = Field(..., description="Status message")
+    synced_entities: int = Field(default=0, description="Number of entities synced")
+    errors: list[str] = Field(
+        default_factory=list, description="List of errors encountered"
+    )