OBLITERATUS/obliteratus/analysis/numerical_contracts.py

"""Pure validation contracts shared by numerical analysis routines."""

from __future__ import annotations

import math


def validate_whitened_parameters(
    regularization_eps: object,
    min_variance_ratio: object,
) -> tuple[float, float]:
    """Validate and normalize whitened-SVD tuning parameters."""
    if (
        isinstance(regularization_eps, bool)
        or not isinstance(regularization_eps, (int, float))
        or not math.isfinite(regularization_eps)
        or regularization_eps <= 0
    ):
        raise ValueError("regularization_eps must be a finite positive number")
    if (
        isinstance(min_variance_ratio, bool)
        or not isinstance(min_variance_ratio, (int, float))
        or not math.isfinite(min_variance_ratio)
        or not 0 <= min_variance_ratio < 1
    ):
        raise ValueError("min_variance_ratio must be in the interval [0, 1)")
    return float(regularization_eps), float(min_variance_ratio)


def validate_whitened_request(
    harmful_count: int,
    harmless_count: int,
    n_directions: object,
) -> int:
    """Validate paired sample counts and requested direction count."""
    if harmful_count <= 0 or harmless_count <= 0:
        raise ValueError("harmful and harmless activations must both be non-empty")
    if harmful_count != harmless_count:
        raise ValueError(
            "harmful and harmless activations must have equal sample counts, got "
            f"{harmful_count} and {harmless_count}",
        )
    if isinstance(n_directions, bool) or not isinstance(n_directions, int):
        raise ValueError("n_directions must be a positive integer")
    if n_directions <= 0:
        raise ValueError("n_directions must be a positive integer")
    return n_directions