Regulated Ai¶

Regulated AI Decision Assistance Harness (spec: agentic_regulated_industry.md).

Cluster: Uncategorised | Type: component | MCP Tools: None

Overview¶

Regulated-AI decision-assistance harness. Two deterministic, DOWN-only gates that keep AI-assisted decisions inside regulated guardrails: they only ever block or downgrade, never silently upgrade.

The two gates:

assess_deployment_readiness (deployment-readiness gate): a DOWN-only constraint-completeness check over a declared control matrix. It returns verified (decision go) ONLY when the intended use is approved AND every required + blocking control for the risk tier is satisfied (control status in approved/retired). A missing or unsatisfied blocking control means the artifact is not constraint-complete (no_go, blocked-escalated); an R5 (prohibited / not supportable) intended use is refused outright. The verified result carries an executed gate trace (risk tier, the required controls checked, each blocking control's id + status + satisfied flag, and the approval flag).
validate_recommendation (runtime recommendation-validity gate): per-case enforcement of three invariants — no recommendation without evidence, abstention is a first-class success path, and assistance never silently becomes automation (directive/binding output is forbidden unless the intended use is approved for that autonomy level). A valid recommendation is NEVER verified; it is qualified-draft with requires_human=True.

When to use:

Deciding whether a regulated decision-support system is constraint-complete enough to deploy
Validating a per-case AI recommendation before a qualified human decides
Classifying a workflow's risk tier (classify_risk_tier) to scale required controls

Example:

from mvp.regulated_ai import (
    assess_deployment_readiness, validate_recommendation,
    Control, ControlMatrix, IntendedUseCard, CaseRecommendation,
)

readiness = assess_deployment_readiness(
    ControlMatrix(controls=[...]), risk_tier="R3",
    intended_use=IntendedUseCard(system_name="loan_review", approved=True),
)
# readiness.decision: go | go_with_conditions | no_go | refuse
# readiness.reliability_label: verified only on the fully-approved GO path

verdict = validate_recommendation(
    CaseRecommendation(recommendation_type="recommend",
                       has_supporting_evidence=True, confidence=0.9),
    IntendedUseCard(system_name="loan_review", approved=True),
)
# verdict.reliability_label == "qualified-draft"; verdict.requires_human is True

Both gates carry a non-permissive @block_contract and emit the canonical reliability envelope (completion_state, reliability_label, warning_card, evidence, request_id, run_id) plus G6_E_REGULATED_* codes on blocked/degraded results. Exposed over MCP as regulated_deployment_gate and regulated_recommendation_gate.

Works well with: action_gating (execution-time gating), align_csf (control framework alignment)

Public API¶

`GroupMetrics`¶

Per-protected-group rates derived from labelled (predicted, actual) outcomes.

Field	Type	Default
`group`	`str`	required
`n`	`int`	required
`selection_rate`	`float`	required
`true_positive_rate`	`float`	required
`false_positive_rate`	`float`	required

Methods:

`to_dict() -> dict`¶

`FairnessReport`¶

Field	Type	Default
`passed`	`bool`	required
`reliability_label`	`str`	required
`disparate_impact_ratio`	`float`	required
`demographic_parity_diff`	`float`	required
`tpr_gap`	`float`	required
`fpr_gap`	`float`	required
`group_metrics`	`list[GroupMetrics]`	field(default_factory=list)
`reasons`	`list[str]`	field(default_factory=list)

Methods:

`to_dict() -> dict`¶

`Control`¶

One row of the §9 Phase 3 control matrix.

Field	Type	Default
`control_id`	`str`	required
`objective`	`str`	required
`applies_to`	`str`	'provider'
`status`	`str`	'missing'
`blocking`	`bool`	True

Methods:

`is_satisfied() -> bool`¶

`IntendedUseCard`¶

§8.2 the locked intended-use artifact.

Field	Type	Default
`system_name`	`str`	required
`assistance_level`	`str`	'recommendation'
`human_decision_owner`	`str`	''
`allowed_outputs`	`frozenset[str]`	frozenset()
`disallowed_outputs`	`frozenset[str]`	frozenset()
`approved`	`bool`	False

`CaseRecommendation`¶

A per-case draft recommendation (§11 decision packet, trimmed).

Field	Type	Default
`recommendation_type`	`str`	'recommend'
`is_directive`	`bool`	False
`has_supporting_evidence`	`bool`	False
`confidence`	`float`	0.0
`within_intended_use`	`bool`	True
`data_quality_ok`	`bool`	True
`output_kind`	`str`	''

`ControlMatrix`¶

§9 Phase 3 — the set of controls compiled for a system.

Field	Type	Default
`controls`	`list[Control]`	field(default_factory=list)

Methods:

`by_id() -> dict[str, Control]`¶

`ImpactAssessment`¶

§8.4 / ISO/IEC 42001 Clause 8.4 + Annex A.5 — the structured AI system impact

Field	Type	Default
`system_name`	`str`	''
`affected_individuals`	`list[str]`	field(default_factory=list)
`affected_groups`	`list[str]`	field(default_factory=list)
`societal_impacts`	`list[str]`	field(default_factory=list)
`fairness_risks`	`list[str]`	field(default_factory=list)
`severity`	`str`	''
`likelihood`	`str`	''
`mitigations`	`list[str]`	field(default_factory=list)
`residual_risk`	`str`	''
`human_reviewer`	`str`	''
`approved`	`bool`	False

Methods:

`missing_fields() -> list[str]`¶

Return the substantive gaps that make the assessment INCOMPLETE (empty == complete).

`is_complete() -> bool`¶

`to_dict() -> dict`¶

`from_dict(data: dict) -> 'ImpactAssessment'`¶

`DeploymentReadiness`¶

Field	Type	Default
`decision`	`str`	required
`reliability_label`	`str`	required
`risk_tier`	`str`	required
`constraint_complete`	`bool`	required
`missing_required_controls`	`list[str]`	field(default_factory=list)
`unsatisfied_blocking_controls`	`list[str]`	field(default_factory=list)
`reasons`	`list[str]`	field(default_factory=list)
`evidence`	`list[dict]`	field(default_factory=list)
`request_id`	`str`	''
`run_id`	`str`	''
`code`	`str`	''

Methods:

`to_dict() -> dict`¶

`RecommendationVerdict`¶

Field	Type	Default
`decision`	`str`	required
`reliability_label`	`str`	required
`requires_human`	`bool`	required
`reasons`	`list[str]`	field(default_factory=list)
`evidence`	`list[dict]`	field(default_factory=list)
`request_id`	`str`	''
`run_id`	`str`	''
`code`	`str`	''

Methods:

`to_dict() -> dict`¶

Functions¶

`evaluate_fairness(groups: dict[str, list[tuple[bool, bool]]], min_disparate_impact: float = _DEFAULT_MIN_DISPARATE_IMPACT, max_parity_diff: float = _DEFAULT_MAX_PARITY_DIFF, max_odds_gap: float = _DEFAULT_MAX_ODDS_GAP) -> FairnessReport`¶

Evaluate group fairness across protected groups, fail-closed.

`fairness_evaluation_control(report: FairnessReport | None) -> Control`¶

Bridge a :class:FairnessReport onto the §9 control matrix.

`impact_assessment_control(assessment: ImpactAssessment | None) -> Control`¶

Bridge the :class:ImpactAssessment artifact onto the §9 control matrix.

`classify_risk_tier(affects_rights_or_safety: bool, regulated_domain: bool, autonomy_level: str = 'recommendation', irreversible: bool = False, prohibited_use: bool = False) -> str`¶

Section 9 Phase 2 risk tiering: final = max(base bucket, domain floor).

`assess_deployment_readiness(matrix: ControlMatrix, risk_tier: str, intended_use: IntendedUseCard) -> DeploymentReadiness`¶

Decide regulated deployment readiness honestly. Missing blocking control => not ready.

`validate_recommendation(rec: CaseRecommendation, intended_use: IntendedUseCard, confidence_threshold: float = 0.7) -> RecommendationVerdict`¶

Decide whether a per-case recommendation is valid, must abstain, or is forbidden.

Regulated Ai¶

Overview¶

Public API¶

GroupMetrics¶

to_dict() -> dict¶

FairnessReport¶

to_dict() -> dict¶

Control¶

is_satisfied() -> bool¶

IntendedUseCard¶

CaseRecommendation¶

ControlMatrix¶

by_id() -> dict[str, Control]¶

ImpactAssessment¶

missing_fields() -> list[str]¶

is_complete() -> bool¶

to_dict() -> dict¶

from_dict(data: dict) -> 'ImpactAssessment'¶

DeploymentReadiness¶

to_dict() -> dict¶

RecommendationVerdict¶

to_dict() -> dict¶

Functions¶

evaluate_fairness(groups: dict[str, list[tuple[bool, bool]]], min_disparate_impact: float = _DEFAULT_MIN_DISPARATE_IMPACT, max_parity_diff: float = _DEFAULT_MAX_PARITY_DIFF, max_odds_gap: float = _DEFAULT_MAX_ODDS_GAP) -> FairnessReport¶

fairness_evaluation_control(report: FairnessReport | None) -> Control¶

impact_assessment_control(assessment: ImpactAssessment | None) -> Control¶

classify_risk_tier(affects_rights_or_safety: bool, regulated_domain: bool, autonomy_level: str = 'recommendation', irreversible: bool = False, prohibited_use: bool = False) -> str¶

assess_deployment_readiness(matrix: ControlMatrix, risk_tier: str, intended_use: IntendedUseCard) -> DeploymentReadiness¶

validate_recommendation(rec: CaseRecommendation, intended_use: IntendedUseCard, confidence_threshold: float = 0.7) -> RecommendationVerdict¶

`GroupMetrics`¶

`to_dict() -> dict`¶

`FairnessReport`¶

`to_dict() -> dict`¶

`Control`¶

`is_satisfied() -> bool`¶

`IntendedUseCard`¶

`CaseRecommendation`¶

`ControlMatrix`¶

`by_id() -> dict[str, Control]`¶

`ImpactAssessment`¶

`missing_fields() -> list[str]`¶

`is_complete() -> bool`¶

`to_dict() -> dict`¶

`from_dict(data: dict) -> 'ImpactAssessment'`¶

`DeploymentReadiness`¶

`to_dict() -> dict`¶

`RecommendationVerdict`¶

`to_dict() -> dict`¶

`evaluate_fairness(groups: dict[str, list[tuple[bool, bool]]], min_disparate_impact: float = _DEFAULT_MIN_DISPARATE_IMPACT, max_parity_diff: float = _DEFAULT_MAX_PARITY_DIFF, max_odds_gap: float = _DEFAULT_MAX_ODDS_GAP) -> FairnessReport`¶

`fairness_evaluation_control(report: FairnessReport | None) -> Control`¶

`impact_assessment_control(assessment: ImpactAssessment | None) -> Control`¶

`classify_risk_tier(affects_rights_or_safety: bool, regulated_domain: bool, autonomy_level: str = 'recommendation', irreversible: bool = False, prohibited_use: bool = False) -> str`¶

`assess_deployment_readiness(matrix: ControlMatrix, risk_tier: str, intended_use: IntendedUseCard) -> DeploymentReadiness`¶

`validate_recommendation(rec: CaseRecommendation, intended_use: IntendedUseCard, confidence_threshold: float = 0.7) -> RecommendationVerdict`¶