base.py

"""Base interfaces for clinically-constrained validation rules."""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Any

import pandas as pd


@dataclass(frozen=True)
class CandidateCorrection:
    """A proposed cell-level correction generated by a constraint."""

    row_index: int
    column: str
    proposed_value: Any
    confidence: float
    rationale: str
    constraint_name: str


@dataclass(frozen=True)
class ConstraintResult:
    """Outcome of applying one clinical constraint."""

    candidates: list[CandidateCorrection]


class ClinicalConstraint(ABC):
    """Abstract clinical constraint interface."""

    name: str = "base_constraint"

    @abstractmethod
    def apply(self, df: pd.DataFrame) -> ConstraintResult:
        """Generate correction candidates for the provided dataset."""