Source code for fable_pyculator.scenario_rules

"""Status-aware scenario-consistency rules for FABLE scenario selections."""

from __future__ import annotations

import hashlib
import itertools
from collections import Counter
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from typing import Any

import yaml

__all__ = [
    "RuleEvaluation",
    "RuleHit",
    "ScenarioRule",
    "enumerate_domain",
    "evaluate_scenario",
    "load_rule_registry",
    "rule_registry_sha256",
    "table_population_from_spec",
]

_APPROVED = "approved"
_PROPOSED = "proposed"
_REJECTED = {"rejected", "superseded"}


[docs] @dataclass(frozen=True) class ScenarioRule: """One reviewable scenario-consistency rule.""" id: str family: str severity: str confidence: str status: str message: str review_question: str condition: Mapping[str, Any] | None = None require: Mapping[str, Any] | None = None coherence: Mapping[str, Any] | None = None review: Mapping[str, Any] | None = None
[docs] @dataclass(frozen=True) class RuleHit: """One rule consequence for a scenario.""" rule_id: str family: str severity: str status: str message: str review_question: str
[docs] @dataclass(frozen=True) class RuleEvaluation: """Rule consequences for one scenario.""" errors: tuple[RuleHit, ...] = () warnings: tuple[RuleHit, ...] = () exploratory: tuple[RuleHit, ...] = () @property def valid(self) -> bool: """Return whether no hard error was raised.""" return not self.errors @property def triggered(self) -> tuple[RuleHit, ...]: """Return every triggered rule.""" return self.errors + self.warnings + self.exploratory
[docs] def to_dict(self) -> dict[str, Any]: """Return a JSON-ready result.""" return { "valid": self.valid, "errors": [_hit_dict(hit) for hit in self.errors], "warnings": [_hit_dict(hit) for hit in self.warnings], "exploratory": [_hit_dict(hit) for hit in self.exploratory], }
def _hit_dict(hit: RuleHit) -> dict[str, str]: return { "rule_id": hit.rule_id, "family": hit.family, "severity": hit.severity, "status": hit.status, "message": hit.message, "review_question": hit.review_question, }
[docs] def load_rule_registry(path: str | Path) -> tuple[ScenarioRule, ...]: """Load the YAML rule registry into typed rules.""" payload = yaml.safe_load(Path(path).read_text(encoding="utf-8")) if not isinstance(payload, Mapping): raise ValueError("rule registry must be a mapping") rules = payload.get("rules") if not isinstance(rules, list): raise ValueError("rule registry must contain a rules list") loaded: list[ScenarioRule] = [] for item in rules: if not isinstance(item, Mapping): raise ValueError("each rule must be a mapping") status = str(item.get("status", "proposed")) severity = str(item.get("severity", "warning")) if severity not in {"error", "warning", "info"}: raise ValueError(f"invalid severity for {item.get('id')}: {severity}") loaded.append( ScenarioRule( id=str(item["id"]), family=str(item.get("family", "uncategorized")), severity=severity, confidence=str(item.get("confidence", "low")), status=status, message=str(item.get("message", "")), review_question=str(item.get("review_question", "")), condition=item.get("when"), require=item.get("require"), coherence=item.get("coherence"), review=item.get("review"), ) ) return tuple(loaded)
[docs] def rule_registry_sha256(path: str | Path) -> str: """Return the SHA-256 of the rule registry source.""" return hashlib.sha256(Path(path).read_bytes()).hexdigest()
[docs] def table_population_from_spec(spec: Mapping[str, Any]) -> dict[str, Any]: """Return populated column and row status for each scenario-definition table.""" status: dict[str, Any] = {} for table in spec.get("scenario_definition_tables", []): if not isinstance(table, Mapping): continue name = table.get("name") columns = table.get("column_labels") or [] values = table.get("values") or [] if not isinstance(name, str): continue column_status: dict[str, bool] = {} row_status: dict[str, dict[str, bool]] = {} key_column: str | None = None for index, column in enumerate(columns): if not isinstance(column, str): continue column_status[column] = any( isinstance(row, Sequence) and not isinstance(row, (str, bytes)) and index < len(row) and row[index] not in (None, "") for row in values ) if columns and isinstance(columns[0], str): key_column = columns[0] for row in values: if not isinstance(row, Sequence) or isinstance(row, (str, bytes)) or not row: continue key = str(row[0]) row_columns = row_status.setdefault(key, {}) for index, column in enumerate(columns): if not isinstance(column, str): continue populated = index < len(row) and row[index] not in (None, "") row_columns[column] = row_columns.get(column, False) or populated status[name] = {"columns": column_status, "rows": row_status, "key_column": key_column} return status
[docs] def evaluate_scenario( selections: Mapping[str, Any], rules: Iterable[ScenarioRule], *, table_status: Mapping[str, Any] | None = None, mode: str = "exploratory", ) -> RuleEvaluation: """Evaluate one scenario under approved, exploratory, or draft-enforced semantics.""" if mode not in {"approved", "exploratory", "draft_enforced"}: raise ValueError("mode must be approved, exploratory, or draft_enforced") errors: list[RuleHit] = [] warnings: list[RuleHit] = [] exploratory: list[RuleHit] = [] for rule in rules: if rule.status in _REJECTED: continue triggered = _rule_triggers(rule, selections, table_status) if not triggered: continue hit = RuleHit( rule_id=rule.id, family=rule.family, severity=rule.severity, status=rule.status, message=rule.message, review_question=rule.review_question, ) if rule.status == _APPROVED: (errors if rule.severity == "error" else warnings).append(hit) elif mode == "draft_enforced": (errors if rule.severity == "error" else warnings).append(hit) else: exploratory.append(hit) return RuleEvaluation(tuple(errors), tuple(warnings), tuple(exploratory))
def _rule_triggers( rule: ScenarioRule, selections: Mapping[str, Any], table_status: Mapping[str, Any] | None, ) -> bool: if rule.coherence is not None: return _coherence_triggers(rule.coherence, selections) if rule.require is not None: condition = rule.condition if condition is not None and not _matches_condition(condition, selections): return False return _requirement_fails(rule.require, table_status, selections) if rule.condition is not None: return _matches_condition(rule.condition, selections) return False def _matches_condition(condition: Mapping[str, Any], selections: Mapping[str, Any]) -> bool: if "all" in condition: return all(_matches_condition(item, selections) for item in condition["all"]) if "any" in condition: return any(_matches_condition(item, selections) for item in condition["any"]) switch = condition.get("switch") if not isinstance(switch, str): return False value = selections.get(switch) if "in" in condition: return any(_matches_value(value, expected) for expected in condition["in"]) if "not_in" in condition: return not any(_matches_value(value, expected) for expected in condition["not_in"]) if "equals" in condition: return _matches_value(value, condition["equals"]) return False def _matches_value(value: Any, expected: Any) -> bool: if expected is True: return value in {True, 1, "1", "yes", "Yes", "true", "True"} if expected is False: return value in {False, 0, "0", "no", "No", "false", "False"} return str(value) == str(expected) def _requirement_fails( require: Mapping[str, Any], table_status: Mapping[str, Any] | None, selections: Mapping[str, Any] | None = None, ) -> bool: if table_status is None: return True table = require.get("table") if not isinstance(table, str) or table not in table_status: return True entry = table_status[table] if not isinstance(entry, Mapping): return True key_value = require.get("key_value") key_switch = require.get("key_switch") if key_switch is not None: if not isinstance(key_switch, str) or not isinstance(selections, Mapping): return True key_value = selections.get(key_switch) if key_value is None or str(key_value) == "": return True if key_value is not None: rows = entry.get("rows") or {} columns = rows.get(str(key_value)) if isinstance(rows, Mapping) else None if not isinstance(columns, Mapping): return True else: columns = entry.get("columns") or {} required = require.get("non_null_columns") or [] if not isinstance(required, list): return True return not all(columns.get(str(column), False) for column in required) def _coherence_triggers(coherence: Mapping[str, Any], selections: Mapping[str, Any]) -> bool: if coherence.get("rule") != "equal_when_all_in_ssp_1_3": return False switches = coherence.get("switches") or [] if not isinstance(switches, list): return False values = [str(selections.get(name)) for name in switches if selections.get(name) is not None] if len(values) != len(switches): return False if not all(value in {"SSP1", "SSP2", "SSP3"} for value in values): return False return len(set(values)) > 1
[docs] def enumerate_domain( controls: Sequence[Mapping[str, Any]], baseline: Mapping[str, Any], rules: Iterable[ScenarioRule], *, table_status: Mapping[str, Any] | None = None, mode: str = "exploratory", ) -> dict[str, Any]: """Enumerate a small control domain and count rule outcomes.""" names = [str(control["name"]) for control in controls] options = [[str(option) for option in control.get("options", [])] for control in controls] total = 0 valid = 0 warning_only = 0 invalid = 0 rule_counts: Counter[str] = Counter() family_counts: Counter[str] = Counter() for values in itertools.product(*options): selections = dict(baseline) selections.update(dict(zip(names, values))) result = evaluate_scenario(selections, rules, table_status=table_status, mode=mode) total += 1 if result.valid: valid += 1 if result.warnings or result.exploratory: warning_only += 1 else: invalid += 1 for hit in result.triggered: rule_counts[hit.rule_id] += 1 family_counts[hit.family] += 1 return { "controls": names, "total": total, "valid": valid, "warning_only": warning_only, "invalid": invalid, "valid_fraction": (valid / total) if total else 0.0, "mode": mode, "rule_hits": dict(rule_counts.most_common()), "family_hits": dict(family_counts.most_common()), }