Generating a Docket Audit Report for Malpractice Review

from __future__ import annotations

from collections import defaultdict
from dataclasses import dataclass, field
from datetime import date, datetime, timedelta
from zoneinfo import ZoneInfo

from pydantic import BaseModel, Field

UTC = ZoneInfo("UTC")


class LedgerEntry(BaseModel):
    """One immutable audit-ledger record read by the report builder."""
    seq: int
    matter_id: str
    deadline_id: str                              # stable id of the specific deadline
    jurisdiction: str = Field(pattern=r"^[A-Z]{2}$")
    event_type: str                               # deadline_computed | reminder_sent | acknowledged | escalated | met | missed | override
    deadline_category: str
    effective_deadline: date | None = None
    owner: str | None = None
    tier: int | None = None                       # escalation tier, when event_type == escalated
    outcome: str | None = None                    # escalation outcome, e.g. RESOLVED | MANUAL
    recorded_at: datetime                         # UTC, timezone-aware


@dataclass
class AckLatency:
    deadline_id: str
    matter_id: str
    reminder_at: datetime
    acknowledged_at: datetime | None
    latency_hours: float | None                   # None if never acknowledged in-period


@dataclass
class DocketAuditReport:
    period_start: datetime
    period_end: datetime
    matter_population: int
    open_deadlines: list[dict[str, str]] = field(default_factory=list)
    ack_latencies: list[AckLatency] = field(default_factory=list)
    escalations: list[dict[str, str]] = field(default_factory=list)
    exceptions: list[dict[str, str]] = field(default_factory=list)

def _in_window(e: LedgerEntry, start: datetime, end: datetime) -> bool:
    return start <= e.recorded_at.astimezone(UTC) < end


def _open_deadlines(entries: list[LedgerEntry], period_end: datetime) -> list[dict[str, str]]:
    """Computed deadlines with no terminal met/missed event by period end."""
    terminal: set[str] = {
        e.deadline_id for e in entries
        if e.event_type in ("met", "missed") and e.recorded_at.astimezone(UTC) < period_end
    }
    rows = [
        {
            "deadline_id": e.deadline_id,
            "matter_id": e.matter_id,
            "jurisdiction": e.jurisdiction,
            "category": e.deadline_category,
            "effective_deadline": e.effective_deadline.isoformat() if e.effective_deadline else "",
            "owner": e.owner or "UNASSIGNED",
        }
        for e in entries
        if e.event_type == "deadline_computed" and e.deadline_id not in terminal
    ]
    return sorted(rows, key=lambda r: r["effective_deadline"])


def _ack_latencies(entries: list[LedgerEntry]) -> list[AckLatency]:
    """Pair the first reminder for each deadline with its first acknowledgment."""
    first_reminder: dict[str, datetime] = {}
    first_ack: dict[str, datetime] = {}
    matter_of: dict[str, str] = {}
    for e in sorted(entries, key=lambda x: x.recorded_at):
        matter_of.setdefault(e.deadline_id, e.matter_id)
        ts = e.recorded_at.astimezone(UTC)
        if e.event_type == "reminder_sent":
            first_reminder.setdefault(e.deadline_id, ts)
        elif e.event_type == "acknowledged":
            first_ack.setdefault(e.deadline_id, ts)

    latencies: list[AckLatency] = []
    for deadline_id, reminded in first_reminder.items():
        acked = first_ack.get(deadline_id)
        hours = round((acked - reminded).total_seconds() / 3600, 2) if acked else None
        latencies.append(AckLatency(
            deadline_id=deadline_id, matter_id=matter_of[deadline_id],
            reminder_at=reminded, acknowledged_at=acked, latency_hours=hours,
        ))
    return latencies

ACK_SLA_HOURS: float = 24.0            # acknowledge within one business day of first reminder


def _escalations(entries: list[LedgerEntry]) -> list[dict[str, str]]:
    rows = [
        {
            "deadline_id": e.deadline_id,
            "matter_id": e.matter_id,
            "tier": str(e.tier or 0),
            "outcome": e.outcome or "UNKNOWN",
            "at": e.recorded_at.astimezone(UTC).isoformat(),
        }
        for e in entries if e.event_type == "escalated"
    ]
    return sorted(rows, key=lambda r: (r["matter_id"], r["tier"]))


def _exceptions(entries: list[LedgerEntry], latencies: list[AckLatency]) -> list[dict[str, str]]:
    exceptions: list[dict[str, str]] = []
    for e in entries:
        if e.event_type == "missed":
            exceptions.append({"deadline_id": e.deadline_id, "matter_id": e.matter_id,
                               "kind": "MISSED"})
        elif e.event_type == "override":
            exceptions.append({"deadline_id": e.deadline_id, "matter_id": e.matter_id,
                               "kind": "DISCRETIONARY_OVERRIDE"})
    for lat in latencies:
        if lat.latency_hours is None or lat.latency_hours > ACK_SLA_HOURS:
            exceptions.append({"deadline_id": lat.deadline_id, "matter_id": lat.matter_id,
                               "kind": "LATE_ACKNOWLEDGMENT"})
    return exceptions


def build_audit_report(entries: list[LedgerEntry], period_start: datetime,
                       period_end: datetime, matter_population: int) -> DocketAuditReport:
    """Assemble a single-period docket audit report from a ledger slice."""
    if period_start.tzinfo is None or period_end.tzinfo is None:
        raise ValueError("period bounds must be timezone-aware (UTC)")
    windowed = [e for e in entries if _in_window(e, period_start, period_end)]

    latencies = _ack_latencies(windowed)
    return DocketAuditReport(
        period_start=period_start,
        period_end=period_end,
        matter_population=matter_population,
        open_deadlines=_open_deadlines(windowed, period_end),
        ack_latencies=latencies,
        escalations=_escalations(windowed),
        exceptions=_exceptions(windowed, latencies),
    )