API Reference¶

@dataclass(frozen=True)
class Candidate:
    """A generic candidate for multidimensional evaluation.

    A candidate represents an entity being evaluated under a policy.
    Domain-specific inputs are carried as raw factor values keyed by factor_id.

    Attributes:
        candidate_id: Stable identifier for the candidate.
        candidate_name: Human-readable name.
        factor_values: Mapping of factor_id to raw primitive value.
        notes: Optional free-text annotation.
        metadata: Optional auxiliary key-value data not used in scoring.
    """

    candidate_id: str
    candidate_name: str
    factor_values: dict[str, FactorValue] = field(
        default_factory=_default_factor_values
    )
    notes: str = ""
    metadata: dict[str, str] = field(default_factory=_default_metadata)

@dataclass(frozen=True)
class EvidenceRef:
    """Reference to supporting source material."""

    source_label: str
    locator: str = ""
    note: str = ""

class FactorForm(StrEnum):
    """Structural form of a factor value."""

    BINARY = "binary"
    NUMERIC = "numeric"
    CATEGORICAL = "categorical"
    EVIDENCE = "evidence"

@dataclass(frozen=True)
class FactorSpec:
    """Structural definition of a factor."""

    factor_id: str
    label: str
    form: FactorForm
    description: str = ""
    unit: str = ""
    allowed_values: tuple[str, ...] = ()

@dataclass(frozen=True)
class FactorValue:
    """Neutral recorded value for one factor."""

    factor_id: str
    form: FactorForm
    value: bool | float | str
    evidence: tuple[EvidenceRef, ...] = ()
    note: str = ""

@dataclass(frozen=True)
class CandidateResult:
    """Result of evaluating a candidate under a policy.

    Contains computed scores and optional derived representations
    for interpretation or visualization.

    Attributes:
        candidate: The evaluated candidate.
        scores: Mapping of label to numeric score.
        levels: Optional mapping of label to qualitative level
            (e.g., "low", "medium", "high").
        visual_levels: Optional mapping of label to presentation-oriented
            categories (e.g., for UI color or grouping).
    """

    candidate: Candidate
    scores: dict[str, float]
    levels: dict[str, str] = field(default_factory=_default_levels)
    visual_levels: dict[str, str] = field(default_factory=_default_visual_levels)

class Comparator(StrEnum):
    """Comparison operator for threshold rules."""

    LT = "lt"
    LE = "le"
    EQ = "eq"
    GE = "ge"
    GT = "gt"
    IN = "in"

@dataclass(frozen=True)
class ConstraintRule:
    """Rule for evaluating a hard constraint.

    Attributes:
        rule_id: Stable identifier for the rule.
        factor_id: Factor to which this rule applies.
        comparator: Comparison operator.
        threshold: Comparison target. May be bool, number, string, or tuple.
        message: Human-readable result text.
        rationale: Optional explanation of why the rule exists.
    """

    rule_id: str
    factor_id: str
    comparator: Comparator
    threshold: bool | float | str | tuple[str, ...]
    message: str
    rationale: str = ""

class EvaluationRole(StrEnum):
    """Role a factor plays in evaluation."""

    HARD_CONSTRAINT = "hard_constraint"
    SCORED_FINDING = "scored_finding"

@dataclass(frozen=True)
class NumericBand:
    """Numeric range mapped to a score and optional qualitative band.

    Attributes:
        min_inclusive: Inclusive lower bound.
        max_inclusive: Inclusive upper bound.
        score: Numeric score assigned to values in this band.
        band: Optional qualitative label such as 'low' or 'strong'.
    """

    min_inclusive: float
    max_inclusive: float
    score: float
    band: str = ""

@dataclass(frozen=True)
class Policy:
    """Configuration for multidimensional evaluation.

    A policy defines:
    - which factors are recognized
    - which factors are hard constraints versus scored findings
    - how raw factor values are mapped to pass/fail findings or scores
    - how aggregate numeric results are interpreted

    Note:
        factor_specs, constraint_rules, and score_rules are stored as lists
        for construction convenience. Callers should treat them as logically
        immutable; the frozen dataclass prevents field reassignment but does
        not prevent mutation of list contents.
    """

    factor_specs: list[FactorSpec] = field(default_factory=_default_factor_specs)
    constraint_rules: list[ConstraintRule] = field(
        default_factory=_default_constraint_rules
    )
    score_rules: list[ScoreRule] = field(default_factory=_default_score_rules)
    interpretation: dict[str, float] = field(default_factory=_default_interpretation)
    metadata: dict[str, str] = field(default_factory=_default_metadata)

    def __post_init__(self) -> None:
        """Validate cross-references between factor specs and rules."""
        known_ids = {spec.factor_id for spec in self.factor_specs}

        for rule in self.constraint_rules:
            if rule.factor_id not in known_ids:
                raise ValueError(
                    f"ConstraintRule {rule.rule_id!r} references unknown "
                    f"factor_id {rule.factor_id!r}."
                )

        for rule in self.score_rules:
            if rule.factor_id not in known_ids:
                raise ValueError(
                    f"ScoreRule {rule.rule_id!r} references unknown "
                    f"factor_id {rule.factor_id!r}."
                )

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> "Policy":
        """Create a Policy from a dictionary.

        Args:
            data: Parsed policy configuration, typically from TOML.

        Returns:
            Policy instance with typed factor and rule objects.
        """
        raw_factor_specs = _as_list_of_maps(data.get("factor_specs", []))
        raw_constraint_rules = _as_list_of_maps(data.get("constraint_rules", []))
        raw_score_rules = _as_list_of_maps(data.get("score_rules", []))

        factor_specs = [
            FactorSpec(
                factor_id=str(item["factor_id"]),
                label=str(item["label"]),
                form=FactorForm(str(item["form"])),
                description=str(item.get("description", "")),
                unit=str(item.get("unit", "")),
                allowed_values=tuple(str(v) for v in item.get("allowed_values", ())),
            )
            for item in raw_factor_specs
        ]

        constraint_rules = [
            ConstraintRule(
                rule_id=str(item["rule_id"]),
                factor_id=str(item["factor_id"]),
                comparator=Comparator(str(item["comparator"])),
                threshold=_coerce_threshold(item["threshold"]),
                message=str(item["message"]),
                rationale=str(item.get("rationale", "")),
            )
            for item in raw_constraint_rules
        ]

        score_rules = [
            ScoreRule(
                rule_id=str(item["rule_id"]),
                factor_id=str(item["factor_id"]),
                weight=float(item["weight"]),
                categorical_scores=_as_string_float_map(
                    item.get("categorical_scores", {})
                ),
                numeric_bands=tuple(
                    NumericBand(
                        min_inclusive=float(band["min_inclusive"]),
                        max_inclusive=float(band["max_inclusive"]),
                        score=float(band["score"]),
                        band=band.get("band", ""),
                    )
                    for band in item.get("numeric_bands", [])
                ),
                binary_scores=_as_bool_float_map(item.get("binary_scores", {})),
                rationale=str(item.get("rationale", "")),
            )
            for item in raw_score_rules
        ]

        return cls(
            factor_specs=factor_specs,
            constraint_rules=constraint_rules,
            score_rules=score_rules,
            interpretation=_as_string_float_map(data.get("interpretation", {})),
            metadata=_as_string_string_map(data.get("metadata", {})),
        )

@dataclass(frozen=True)
class ScoreRule:
    """Rule for converting a factor value into a score.

    Exactly one mapping style must be used for a given rule:
    - categorical_scores for categorical factors
    - numeric_bands for numeric factors
    - binary_scores for binary factors

    Raises:
        ValueError: If not exactly one mapping style is populated.
    """

    rule_id: str
    factor_id: str
    weight: float
    categorical_scores: dict[str, float] = field(
        default_factory=_default_string_float_map
    )

    numeric_bands: tuple[NumericBand, ...] = ()
    binary_scores: dict[bool, float] = field(default_factory=_default_bool_float_map)
    rationale: str = ""

    def __post_init__(self) -> None:
        """Validate that exactly one mapping style is populated."""
        active = sum(
            (
                bool(self.categorical_scores),
                bool(self.numeric_bands),
                bool(self.binary_scores),
            )
        )
        if active != 1:
            raise ValueError(
                f"ScoreRule {self.rule_id!r} must specify exactly one mapping style "
                f"(categorical_scores, numeric_bands, or binary_scores); "
                f"{active} were populated."
            )