schemas.py

"""Structured data contracts for the insurance claim intake workflow."""

from __future__ import annotations

from typing import Literal, Optional

from pydantic import BaseModel, Field


ClaimType = Literal[
    "home_water_damage",
    "auto_collision",
    "theft_property_loss",
    "health_medical_reimbursement",
    "travel_delay_cancellation",
    "other",
]

Severity = Literal["low", "medium", "high", "urgent"]
IntakeStatus = Literal["valid", "missing_info"]
RoutingDecision = Literal[
    "ready_for_adjuster",
    "needs_docs",
    "special_investigation",
    "emergency_escalation",
    "policy_review",
]


class EvidenceRecord(BaseModel):
    document_type: str = Field(description="Canonical document key from the extraction instructions.")
    status: Literal["unknown", "missing", "planned", "available", "received"] = "unknown"
    source_turn_ids: list[str] = Field(default_factory=list)
    evidence_ids: list[str] = Field(default_factory=list)


class SafetyFact(BaseModel):
    category: str = Field(description="injury, electrical, unsafe_housing, sewage, mold, or other immediate hazard")
    status: Literal["present", "absent", "uncertain"]
    description: str
    source_turn_ids: list[str] = Field(default_factory=list)


class FactSource(BaseModel):
    field: str
    source_turn_ids: list[str] = Field(default_factory=list)


class ClaimNarrative(BaseModel):
    """Normalized facts extracted from a messy claim narrative."""

    policyholder_name: str = Field(description="Name of the policyholder or claimant.")
    policy_number: str = Field(description="Policy or member number if supplied.")
    contact_method: str = Field(description="Best available phone, email, or mailing contact.")
    date_of_loss: str = Field(description="Exact loss date in YYYY-MM-DD format, or not specified.")
    reported_date: str = Field(description="Date the claimant says they are reporting, if supplied.")
    loss_location: str = Field(description="City, address, intersection, facility, or travel route.")
    loss_description: str = Field(description="Plain-language description of what happened.")
    estimated_loss_usd: Optional[float] = Field(
        default=None, ge=0, allow_inf_nan=False,
        description="Estimated financial loss in USD when supplied.",
    )
    injuries_or_safety_concerns: list[str] = Field(default_factory=list)
    parties_involved: list[str] = Field(default_factory=list)
    evidence_available: list[str] = Field(default_factory=list)
    documents_mentioned: list[str] = Field(default_factory=list)
    missing_or_uncertain_facts: list[str] = Field(default_factory=list)
    raw_narrative_summary: str = Field(description="Short factual summary of the source narrative.")
    assumptions: list[str] = Field(default_factory=list)
    evidence_records: list[EvidenceRecord] = Field(default_factory=list)
    safety_facts: list[SafetyFact] = Field(default_factory=list)
    fact_sources: list[FactSource] = Field(default_factory=list)


class FieldValidation(BaseModel):
    """Deterministic validation of minimum claim intake information."""

    intake_status: IntakeStatus
    missing_fields: list[str] = Field(default_factory=list)
    warnings: list[str] = Field(default_factory=list)
    ready_for_policy_review: bool


class ClaimClassification(BaseModel):
    """LLM classification of claim type and operational severity."""

    claim_type: ClaimType
    severity: Severity
    severity_rationale: str
    likely_policy_line: str
    loss_drivers: list[str] = Field(default_factory=list)
    claimant_needs: list[str] = Field(default_factory=list)


class EvidenceRuleFinding(BaseModel):
    """Deterministic finding generated by coverage, evidence, or routing rules."""

    rule_id: str
    severity: Severity
    message: str
    required_action: Literal[
        "collect_info",
        "collect_document",
        "adjuster_review",
        "siu_review",
        "emergency_escalation",
    ]
    document: Optional[str] = None


class CoverageEvidenceDecision(BaseModel):
    """Deterministic routing output after coverage and evidence gates."""

    routing_decision: RoutingDecision
    provisional_coverage_considerations: list[str] = Field(default_factory=list)
    required_documents: list[str] = Field(default_factory=list)
    findings: list[EvidenceRuleFinding] = Field(default_factory=list)
    audit_trail: list[str] = Field(default_factory=list)


class DocumentChecklistItem(BaseModel):
    """One claimant-facing checklist item."""

    item: str
    reason: str
    priority: Literal["required", "recommended", "conditional"]
    already_provided: bool = False
    status: Literal["unknown", "missing", "planned", "available", "received"] = "unknown"
    evidence_ids: list[str] = Field(default_factory=list)


class DocumentChecklist(BaseModel):
    """Generated document checklist for the claim packet."""

    items: list[DocumentChecklistItem] = Field(default_factory=list)
    claimant_tip: str


class FraudSafetySignal(BaseModel):
    """Deterministic SIU, fraud-pattern, and safety signal."""

    signal_id: str
    severity: Severity
    message: str
    route_to_siu: bool = False
    route_to_emergency: bool = False


class FraudSafetyGate(BaseModel):
    """Final deterministic safety and fraud routing gate."""

    final_routing_decision: RoutingDecision
    signals: list[FraudSafetySignal] = Field(default_factory=list)
    audit_trail: list[str] = Field(default_factory=list)


class ClaimIntakePacket(BaseModel):
    """Final polished packet returned to ADK Web."""

    claim_type: ClaimType
    intake_status: IntakeStatus
    severity: Severity
    routing_decision: RoutingDecision
    missing_information: list[str] = Field(default_factory=list)
    required_documents: list[DocumentChecklistItem] = Field(default_factory=list)
    coverage_considerations: list[str] = Field(default_factory=list)
    adjuster_handoff_summary: str
    claimant_next_message: str
    audit_trail: list[str] = Field(default_factory=list)
    markdown: str