app/agentic/models.py

"""Structured artifacts for the agentic RICS inspection pipeline."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any


@dataclass(frozen=True)
class EvidenceItem:
    doc_id: str
    chunk_id: str
    score: float
    text: str
    source: str | None = None  # filename / label
    section_hint: str | None = None
    kb: bool = False


@dataclass(frozen=True)
class Finding:
    element: str  # e.g. "E2 Roof coverings"
    observation: str
    implication: str
    recommendation: str
    urgency: str  # "Immediate" | "Short-term" | "Routine" | "Monitor" | "Verify"
    condition_rating: str | None = None  # "1"|"2"|"3"|"NI"|None
    evidence: tuple[EvidenceItem, ...] = ()


@dataclass(frozen=True)
class RiskItem:
    category: str  # e.g. "Fire", "Electrical", "Structural", "Moisture"
    risk: str
    severity: str  # "Low" | "Medium" | "High"
    likelihood: str  # "Low" | "Medium" | "High"
    action: str
    evidence: tuple[EvidenceItem, ...] = ()


@dataclass(frozen=True)
class ComplianceNote:
    standard: str  # e.g. "RICS Home Survey Standard"
    note: str
    status: str  # "OK" | "Review" | "Missing"


@dataclass(frozen=True)
class StructuredReport:
    executive_summary: str
    property_description: str
    condition_assessment: str
    defects_and_risks: str
    recommendations: str
    findings: tuple[Finding, ...] = ()
    risks: tuple[RiskItem, ...] = ()
    compliance: tuple[ComplianceNote, ...] = ()
    evidence_items: tuple[EvidenceItem, ...] = ()
    tool_trace: tuple[dict[str, object], ...] = ()
    extraction_audit: dict[str, Any] | None = None
    section_plan: dict[str, Any] | None = None
    condition_rating_summary: dict[str, Any] | None = None