API Reference

@dataclass(frozen=True, slots=True)
class Evaluation:
    """Record metric results computed elsewhere."""

    model_id: str
    metrics: Mapping[str, float]

    def __post_init__(self) -> None:
        """After initialization validation on the dataclass fields."""
        if not self.model_id.strip():
            raise ValueError("model_id must not be empty.")
        if not self.metrics:
            raise ValueError("Evaluation must contain at least one metric.")
        object.__setattr__(self, "metrics", MappingProxyType(dict(self.metrics)))

@dataclass(frozen=True, slots=True)
class ExperimentAssessment:
    """Record the conclusion drawn from comparable experiment evidence."""

    comparison: str
    conclusion: str
    rationale: Rationale
    winner_model_id: str | None = None
    baseline_beaten: bool | None = None

    def __post_init__(self) -> None:
        """After initialization validation on the dataclass fields."""
        if not self.comparison.strip():
            raise ValueError("Comparison description must not be empty.")
        if not self.conclusion.strip():
            raise ValueError("Conclusion must not be empty.")

@dataclass(frozen=True, slots=True)
class ExperimentSpec[DatasetRefT]:
    """Declare a complete analytical experiment before execution."""

    dataset: DatasetRefT

    grain: Grain
    learning_mode: LearningMode
    problem_type: ProblemType

    target: str
    selected_features: tuple[str, ...]
    feature_rationale: Rationale

    resolution: Resolution
    split: SplitPlan

    baseline_id: str
    baseline: ModelPlan

    candidate_id: str
    candidate: ModelPlan

    def __post_init__(self) -> None:
        """Validate the experiment specification."""
        if not self.target.strip():
            raise ValueError("Target must not be empty.")

        if not self.selected_features:
            raise ValueError("Selected features must not be empty.")

        if self.target in self.selected_features:
            raise ValueError("Target must not also appear in selected features.")

        if not self.baseline_id.strip():
            raise ValueError("Baseline ID must not be empty.")

        if not self.candidate_id.strip():
            raise ValueError("Candidate ID must not be empty.")

        if self.baseline_id == self.candidate_id:
            raise ValueError("Baseline and candidate IDs must be different.")

@dataclass(frozen=True, slots=True)
class Grain:
    """Declare what one observation represents."""

    observation: str

    def __post_init__(self) -> None:
        """After initialization validation on the dataclass fields."""
        if not self.observation.strip():
            raise ValueError("Grain observation must not be empty.")

class LearningMode(StrEnum):
    """Declare whether learning uses a target."""

    SUPERVISED = "supervised"
    UNSUPERVISED = "unsupervised"

@dataclass(frozen=True, slots=True)
class ModelPlan:
    """Declare one estimator choice and why it was chosen."""

    estimator: str
    role: ModelRole
    rationale: Rationale
    parameters: Mapping[str, Any] = field(default_factory=dict)

    def __post_init__(self) -> None:
        """Validate the model plan."""
        if not self.estimator.strip():
            raise ValueError("Estimator name must not be empty.")

class ModelRole(StrEnum):
    """Role played by a model in an experiment."""

    BASELINE = "baseline"
    CANDIDATE = "candidate"

class ProblemType(StrEnum):
    """Supported supervised prediction problem types."""

    CLASSIFICATION = "classification"
    REGRESSION = "regression"

@runtime_checkable
class RationaleTemplate(Protocol):
    """Protocol for structured or canonical rationale objects."""

    def render(self) -> str:
        """Return a human-readable explanation."""

@dataclass(frozen=True, slots=True)
class RationaleText:
    """Structured wrapper for free-form rationale text."""

    text: str

    def __post_init__(self) -> None:
        """After initialization validation on the dataclass fields."""
        if not self.text.strip():
            raise ValueError("Rationale text must not be empty.")

    def render(self) -> str:
        """Return a human-readable explanation."""
        return self.text

@dataclass(frozen=True, slots=True)
class Resolution:
    """Declare what to do about a data problem and why."""

    problem: str
    action: ResolutionAction
    rationale: Rationale
    field: str | None = None
    original_value: Any | None = None
    resolved_value: Any | None = None

    def __post_init__(self) -> None:
        """After initialization validation on the dataclass fields."""
        if not self.problem.strip():
            raise ValueError("Problem description must not be empty.")
        if self.action is ResolutionAction.RECODE and self.resolved_value is None:
            raise ValueError("RECODE resolutions require resolved_value.")

class ResolutionAction(StrEnum):
    """Common analyst responses to identified data problems."""

    DROP = "drop"
    RECODE = "recode"
    IMPUTE = "impute"
    FLAG = "flag"

class SplitMethod(StrEnum):
    """Common train/test partition strategies."""

    RANDOM = "random"
    STRATIFIED = "stratified"
    GROUPED = "grouped"
    TIME_ORDERED = "time_ordered"

@dataclass(frozen=True, slots=True)
class SplitPlan:
    """Declare how training and test observations should be separated."""

    method: SplitMethod
    test_size: float
    rationale: Rationale
    seed: int | None = None
    group_field: str | None = None
    time_field: str | None = None

    def __post_init__(self) -> None:
        """After initialization validation on the dataclass fields."""
        if not 0.0 < self.test_size < 1.0:
            raise ValueError("test_size must be between 0 and 1.")
        if self.method is SplitMethod.GROUPED and not self.group_field:
            raise ValueError("Grouped splits require group_field.")
        if self.method is SplitMethod.TIME_ORDERED and not self.time_field:
            raise ValueError("Time-ordered splits require time_field.")