Initial commit

libs/schemas/coverage/evaluation.py

@@ -0,0 +1,112 @@
+"""Coverage evaluation models."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from ..enums import OverallStatus, Role, Status
+
+
+class FoundEvidence(BaseModel):
+    """Evidence found in the knowledge graph"""
+
+    doc_id: str
+    kind: str
+    confidence: float = 0.0
+    pages: list[int] = Field(default_factory=list)
+    bbox: dict[str, float] | None = None
+    ocr_confidence: float = 0.0
+    extract_confidence: float = 0.0
+    date: str | None = None
+
+
+class Citation(BaseModel):
+    """Citation reference"""
+
+    rule_id: str | None = None
+    doc_id: str | None = None
+    url: str | None = None
+    locator: str | None = None
+    section_id: str | None = None
+    page: int | None = None
+    bbox: dict[str, float] | None = None
+
+
+class CoverageItem(BaseModel):
+    """Coverage evaluation for a single evidence item"""
+
+    id: str
+    role: Role
+    status: Status
+    boxes: list[str] = Field(default_factory=list)
+    found: list[FoundEvidence] = Field(default_factory=list)
+    acceptable_alternatives: list[str] = Field(default_factory=list)
+    reason: str = ""
+    citations: list[Citation] = Field(default_factory=list)
+
+
+class ScheduleCoverage(BaseModel):
+    """Coverage evaluation for a schedule"""
+
+    schedule_id: str
+    status: OverallStatus
+    evidence: list[CoverageItem] = Field(default_factory=list)
+
+
+class BlockingItem(BaseModel):
+    """Item that blocks completion"""
+
+    schedule_id: str
+    evidence_id: str
+
+
+class CoverageReport(BaseModel):
+    """Complete coverage evaluation report"""
+
+    tax_year: str
+    taxpayer_id: str
+    schedules_required: list[str] = Field(default_factory=list)
+    overall_status: OverallStatus
+    coverage: list[ScheduleCoverage] = Field(default_factory=list)
+    blocking_items: list[BlockingItem] = Field(default_factory=list)
+    evaluated_at: datetime = Field(default_factory=datetime.utcnow)
+    policy_version: str = ""
+
+
+class CoverageGap(BaseModel):
+    """Gap in coverage requiring clarification"""
+
+    schedule_id: str
+    evidence_id: str
+    role: Role
+    reason: str
+    boxes: list[str] = Field(default_factory=list)
+    citations: list[Citation] = Field(default_factory=list)
+    acceptable_alternatives: list[str] = Field(default_factory=list)
+
+
+class ClarifyContext(BaseModel):
+    """Context for clarifying question"""
+
+    tax_year: str
+    taxpayer_id: str
+    jurisdiction: str
+
+
+class UploadOption(BaseModel):
+    """Upload option for user"""
+
+    label: str
+    accepted_formats: list[str] = Field(default_factory=list)
+    upload_endpoint: str
+
+
+class ClarifyResponse(BaseModel):
+    """Response to clarifying question request"""
+
+    question_text: str
+    why_it_is_needed: str
+    citations: list[Citation] = Field(default_factory=list)
+    options_to_provide: list[UploadOption] = Field(default_factory=list)
+    blocking: bool = False
+    boxes_affected: list[str] = Field(default_factory=list)