Chapter 17: Regulatory Pathways and FDA Submissions

"""
Regulatory documentation system for clinical AI with equity focus.

This module provides production-ready tools for generating FDA regulatory
documentation including 510(k) submissions, clinical validation reports,
risk analyses, and predetermined change control plans with systematic
attention to algorithmic fairness and health equity.
"""

from dataclasses import dataclass, field
from typing import Dict, List, Optional, Set, Tuple, Any
from enum import Enum
from datetime import datetime
import numpy as np
import pandas as pd
from pathlib import Path
import json
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class DeviceRiskClass(Enum):
    """FDA device risk classification."""
    CLASS_I = "Class I"
    CLASS_II = "Class II"
    CLASS_III = "Class III"

class RegulatoryPathway(Enum):
    """Available FDA regulatory pathways."""
    FIVE_TEN_K = "510(k)"
    PMA = "Premarket Approval"
    DE_NOVO = "De Novo"
    EXEMPT = "Exempt (Clinical Decision Support)"

@dataclass
class IntendedUsePopulation:
    """
    Specification of intended use population with equity considerations.

    Attributes:
        population_description: Detailed description of intended patient population
        age_range: Age range (min, max) in years, None for no restriction
        clinical_settings: List of clinical settings (e.g., "emergency department", "primary care")
        geographic_regions: Geographic regions where device is intended for use
        included_demographics: Demographic groups explicitly included in validation
        excluded_demographics: Demographic groups explicitly excluded from intended use
        clinical_conditions: Specific clinical conditions or disease states
        contraindications: Conditions under which device should not be used
        performance_subgroups: Subgroups where performance characteristics differ
        validation_populations: Description of populations used for validation
        representation_notes: Documentation of how validation populations represent intended use
    """
    population_description: str
    age_range: Optional[Tuple[Optional[int], Optional[int]]] = None
    clinical_settings: List[str] = field(default_factory=list)
    geographic_regions: List[str] = field(default_factory=list)
    included_demographics: Dict[str, List[str]] = field(default_factory=dict)
    excluded_demographics: Dict[str, List[str]] = field(default_factory=dict)
    clinical_conditions: List[str] = field(default_factory=list)
    contraindications: List[str] = field(default_factory=list)
    performance_subgroups: Dict[str, str] = field(default_factory=dict)
    validation_populations: str = ""
    representation_notes: str = ""

    def validate(self) -> List[str]:
        """
        Validate completeness of intended use specification.

        Returns:
            List of validation warnings
        """
        warnings = []

        if not self.population_description:
            warnings.append("Population description is empty")

        if not self.clinical_settings:
            warnings.append("No clinical settings specified")

        if not self.included_demographics:
            warnings.append(
                "No demographics specified - should explicitly state which "
                "demographic groups were included in validation"
            )

        if not self.validation_populations:
            warnings.append(
                "Validation populations not described - should detail "
                "characteristics of populations used for testing"
            )

        if not self.representation_notes:
            warnings.append(
                "No representation analysis provided - should explain how "
                "validation populations represent intended use population"
            )

        if self.performance_subgroups and not self.included_demographics:
            warnings.append(
                "Performance subgroups specified but demographics not documented"
            )

        return warnings

@dataclass
class PerformanceCharacteristic:
    """
    Performance metric with stratification by subgroups.

    Attributes:
        metric_name: Name of performance metric (e.g., "Sensitivity", "AUC-ROC")
        overall_value: Overall performance value
        confidence_interval: 95% confidence interval (lower, upper)
        n_samples: Total number of samples
        subgroup_performance: Performance stratified by demographic groups
        setting_performance: Performance stratified by clinical settings
        meets_specification: Whether performance meets prespecified criteria
        specification_threshold: Prespecified performance threshold
        clinical_significance: Clinical interpretation of performance level
    """
    metric_name: str
    overall_value: float
    confidence_interval: Tuple[float, float]
    n_samples: int
    subgroup_performance: Dict[str, Tuple[float, Tuple[float, float], int]] = field(default_factory=dict)
    setting_performance: Dict[str, Tuple[float, Tuple[float, float], int]] = field(default_factory=dict)
    meets_specification: bool = True
    specification_threshold: Optional[float] = None
    clinical_significance: str = ""

    def assess_equity(self, max_disparity: float = 0.1) -> Tuple[bool, str]:
        """
        Assess whether performance disparities across subgroups exceed threshold.

        Args:
            max_disparity: Maximum acceptable performance disparity

        Returns:
            Tuple of (passes equity assessment, detailed message)
        """
        if not self.subgroup_performance:
            return False, "No subgroup performance data available for equity assessment"

        values = [perf[0] for perf in self.subgroup_performance.values()]
        min_value = min(values)
        max_value = max(values)
        disparity = max_value - min_value

        passes = disparity <= max_disparity

        message = f"Performance disparity: {disparity:.3f} (range: {min_value:.3f} to {max_value:.3f})"
        if passes:
            message += f"\nMeets equity threshold of {max_disparity:.3f}"
        else:
            message += f"\nEXCEEDS equity threshold of {max_disparity:.3f}"

            # Identify underperforming groups
            underperforming = [
                group for group, (val, _, _) in self.subgroup_performance.items()
                if val < min_value + max_disparity
            ]
            message += f"\nUnderperforming groups: {', '.join(underperforming)}"

        return passes, message

@dataclass
class RiskAnalysis:
    """
    Risk analysis documenting potential harms and mitigation strategies.

    Attributes:
        risk_description: Description of potential risk
        affected_populations: Populations potentially affected by this risk
        severity: Severity rating (minor, moderate, serious, critical)
        probability: Probability rating (rare, occasional, probable, frequent)
        detection_methods: Methods for detecting occurrence of risk
        mitigation_strategies: Strategies to reduce or eliminate risk
        residual_risk_level: Risk level after mitigation
        monitoring_plan: Post-market monitoring plan for this risk
        equity_considerations: Special considerations for underserved populations
    """
    risk_description: str
    affected_populations: List[str]
    severity: str
    probability: str
    detection_methods: List[str] = field(default_factory=list)
    mitigation_strategies: List[str] = field(default_factory=list)
    residual_risk_level: str = ""
    monitoring_plan: str = ""
    equity_considerations: str = ""

@dataclass
class PremarketSubmission:
    """
    Complete 510(k) premarket submission package.

    Attributes:
        device_name: Trade name of the device
        manufacturer: Manufacturer information
        device_class: FDA device class
        regulatory_pathway: Chosen regulatory pathway
        intended_use: Comprehensive intended use statement
        intended_use_population: Detailed population specification
        predicate_device: Predicate device for 510(k) pathway
        indications_for_use: Specific clinical indications
        performance_characteristics: List of all performance metrics
        risk_analyses: Comprehensive risk assessments
        clinical_validation_summary: Summary of clinical validation studies
        training_data_description: Description of training data with demographics
        validation_data_description: Description of validation data with demographics
        limitations_and_warnings: Known limitations and appropriate warnings
        equity_assessment: Explicit fairness and equity evaluation
        labeling_draft: Draft device labeling including patient information
        post_market_surveillance_plan: Plan for ongoing monitoring
    """
    device_name: str
    manufacturer: str
    device_class: DeviceRiskClass
    regulatory_pathway: RegulatoryPathway
    intended_use: str
    intended_use_population: IntendedUsePopulation
    predicate_device: Optional[str] = None
    indications_for_use: List[str] = field(default_factory=list)
    performance_characteristics: List[PerformanceCharacteristic] = field(default_factory=list)
    risk_analyses: List[RiskAnalysis] = field(default_factory=list)
    clinical_validation_summary: str = ""
    training_data_description: str = ""
    validation_data_description: str = ""
    limitations_and_warnings: List[str] = field(default_factory=list)
    equity_assessment: str = ""
    labeling_draft: str = ""
    post_market_surveillance_plan: str = ""
    submission_date: datetime = field(default_factory=datetime.now)

    def generate_document(self, output_path: Path) -> None:
        """
        Generate formatted regulatory submission document.

        Args:
            output_path: Path for output document
        """
        sections = []

        # Header
        sections.append("=" * 80)
        sections.append("510(K) PREMARKET NOTIFICATION")
        sections.append("=" * 80)
        sections.append(f"\nDevice Name: {self.device_name}")
        sections.append(f"Manufacturer: {self.manufacturer}")
        sections.append(f"Device Class: {self.device_class.value}")
        sections.append(f"Regulatory Pathway: {self.regulatory_pathway.value}")
        sections.append(f"Submission Date: {self.submission_date.strftime('%Y-%m-%d')}")
        sections.append("")

        # Intended use
        sections.append("INTENDED USE")
        sections.append("-" * 80)
        sections.append(self.intended_use)
        sections.append("")

        # Intended use population
        sections.append("INTENDED USE POPULATION")
        sections.append("-" * 80)
        sections.append(self.intended_use_population.population_description)
        sections.append("")

        if self.intended_use_population.clinical_settings:
            sections.append("Clinical Settings:")
            for setting in self.intended_use_population.clinical_settings:
                sections.append(f"  - {setting}")
            sections.append("")

        if self.intended_use_population.included_demographics:
            sections.append("Demographic Groups Included in Validation:")
            for category, groups in self.intended_use_population.included_demographics.items():
                sections.append(f"  {category}: {', '.join(groups)}")
            sections.append("")

        if self.intended_use_population.validation_populations:
            sections.append("Validation Population Characteristics:")
            sections.append(self.intended_use_population.validation_populations)
            sections.append("")

        if self.intended_use_population.representation_notes:
            sections.append("Representativeness Analysis:")
            sections.append(self.intended_use_population.representation_notes)
            sections.append("")

        # Indications for use
        if self.indications_for_use:
            sections.append("INDICATIONS FOR USE")
            sections.append("-" * 80)
            for indication in self.indications_for_use:
                sections.append(f"  - {indication}")
            sections.append("")

        # Predicate device
        if self.predicate_device:
            sections.append("PREDICATE DEVICE")
            sections.append("-" * 80)
            sections.append(self.predicate_device)
            sections.append("")

        # Performance characteristics
        sections.append("PERFORMANCE CHARACTERISTICS")
        sections.append("-" * 80)

        for perf in self.performance_characteristics:
            sections.append(f"\n{perf.metric_name}:")
            sections.append(f"  Overall: {perf.overall_value:.3f} "
                          f"(95% CI: {perf.confidence_interval[0]:.3f}-{perf.confidence_interval[1]:.3f})")
            sections.append(f"  Sample Size: {perf.n_samples:,}")

            if perf.specification_threshold is not None:
                status = "MEETS" if perf.meets_specification else "DOES NOT MEET"
                sections.append(f"  Specification: {status} threshold of {perf.specification_threshold:.3f}")

            if perf.subgroup_performance:
                sections.append("  \n  Performance by Demographic Subgroup:")
                for subgroup, (value, ci, n) in perf.subgroup_performance.items():
                    sections.append(f"    {subgroup}: {value:.3f} (95% CI: {ci[0]:.3f}-{ci[1]:.3f}, n={n:,})")

                passes_equity, equity_msg = perf.assess_equity()
                sections.append(f"\n  Equity Assessment: {equity_msg}")

            if perf.setting_performance:
                sections.append("  \n  Performance by Clinical Setting:")
                for setting, (value, ci, n) in perf.setting_performance.items():
                    sections.append(f"    {setting}: {value:.3f} (95% CI: {ci[0]:.3f}-{ci[1]:.3f}, n={n:,})")

            if perf.clinical_significance:
                sections.append(f"\n  Clinical Significance: {perf.clinical_significance}")

            sections.append("")

        # Training and validation data
        sections.append("TRAINING DATA")
        sections.append("-" * 80)
        sections.append(self.training_data_description)
        sections.append("")

        sections.append("VALIDATION DATA")
        sections.append("-" * 80)
        sections.append(self.validation_data_description)
        sections.append("")

        # Clinical validation
        if self.clinical_validation_summary:
            sections.append("CLINICAL VALIDATION")
            sections.append("-" * 80)
            sections.append(self.clinical_validation_summary)
            sections.append("")

        # Risk analysis
        sections.append("RISK ANALYSIS")
        sections.append("-" * 80)

        for i, risk in enumerate(self.risk_analyses, 1):
            sections.append(f"\nRisk #{i}: {risk.risk_description}")
            sections.append(f"  Severity: {risk.severity}")
            sections.append(f"  Probability: {risk.probability}")
            sections.append(f"  Affected Populations: {', '.join(risk.affected_populations)}")

            if risk.mitigation_strategies:
                sections.append("  Mitigation Strategies:")
                for strategy in risk.mitigation_strategies:
                    sections.append(f"    - {strategy}")

            if risk.residual_risk_level:
                sections.append(f"  Residual Risk Level: {risk.residual_risk_level}")

            if risk.equity_considerations:
                sections.append(f"  Equity Considerations: {risk.equity_considerations}")

        sections.append("")

        # Equity assessment
        if self.equity_assessment:
            sections.append("EQUITY AND FAIRNESS ASSESSMENT")
            sections.append("-" * 80)
            sections.append(self.equity_assessment)
            sections.append("")

        # Limitations and warnings
        if self.limitations_and_warnings:
            sections.append("LIMITATIONS AND WARNINGS")
            sections.append("-" * 80)
            for limitation in self.limitations_and_warnings:
                sections.append(f"  - {limitation}")
            sections.append("")

        # Post-market surveillance
        if self.post_market_surveillance_plan:
            sections.append("POST-MARKET SURVEILLANCE PLAN")
            sections.append("-" * 80)
            sections.append(self.post_market_surveillance_plan)
            sections.append("")

        # Write to file
        output_path.parent.mkdir(parents=True, exist_ok=True)
        with open(output_path, 'w') as f:
            f.write('\n'.join(sections))

        logger.info(f"Generated regulatory submission document: {output_path}")

    def validate_submission(self) -> Tuple[bool, List[str]]:
        """
        Validate completeness of regulatory submission.

        Returns:
            Tuple of (is valid, list of validation issues)
        """
        issues = []

        # Check required fields
        if not self.intended_use:
            issues.append("Intended use statement is missing")

        if not self.indications_for_use:
            issues.append("Indications for use not specified")

        if not self.performance_characteristics:
            issues.append("No performance characteristics provided")

        if not self.risk_analyses:
            issues.append("Risk analysis not provided")

        if not self.training_data_description:
            issues.append("Training data not described")

        if not self.validation_data_description:
            issues.append("Validation data not described")

        if not self.equity_assessment:
            issues.append(
                "No equity assessment provided - should explicitly evaluate "
                "fairness across demographic groups and care settings"
            )

        if not self.post_market_surveillance_plan:
            issues.append("Post-market surveillance plan not provided")

        # Check intended use population
        population_warnings = self.intended_use_population.validate()
        issues.extend(population_warnings)

        # Check that performance characteristics include subgroup analysis
        has_subgroup_analysis = any(
            perf.subgroup_performance for perf in self.performance_characteristics
        )
        if not has_subgroup_analysis:
            issues.append(
                "No subgroup performance analysis provided - should stratify "
                "performance by demographic groups"
            )

        # Check that risk analysis includes equity considerations
        has_equity_risks = any(
            risk.equity_considerations for risk in self.risk_analyses
        )
        if not has_equity_risks:
            issues.append(
                "Risk analyses do not include equity considerations - should "
                "evaluate differential risks across populations"
            )

        is_valid = len(issues) == 0
        return is_valid, issues

class PremarketSubmissionBuilder:
    """
    Builder class for constructing regulatory submissions step by step.
    """

    def __init__(self, device_name: str, manufacturer: str):
        """Initialize submission builder."""
        self.device_name = device_name
        self.manufacturer = manufacturer
        self.device_class = DeviceRiskClass.CLASS_II
        self.regulatory_pathway = RegulatoryPathway.FIVE_TEN_K
        self.intended_use = ""
        self.intended_use_population = None
        self.predicate_device = None
        self.indications = []
        self.performance_chars = []
        self.risks = []
        self.training_data_desc = ""
        self.validation_data_desc = ""
        self.limitations = []
        self.equity_assessment = ""
        self.clinical_validation = ""
        self.surveillance_plan = ""

    def set_device_classification(
        self,
        device_class: DeviceRiskClass,
        regulatory_pathway: RegulatoryPathway
    ) -> 'PremarketSubmissionBuilder':
        """Set device class and regulatory pathway."""
        self.device_class = device_class
        self.regulatory_pathway = regulatory_pathway
        return self

    def set_intended_use(self, intended_use: str) -> 'PremarketSubmissionBuilder':
        """Set intended use statement."""
        self.intended_use = intended_use
        return self

    def set_intended_use_population(
        self,
        population: IntendedUsePopulation
    ) -> 'PremarketSubmissionBuilder':
        """Set intended use population with detailed specification."""
        self.intended_use_population = population
        return self

    def add_indication(self, indication: str) -> 'PremarketSubmissionBuilder':
        """Add clinical indication."""
        self.indications.append(indication)
        return self

    def add_performance_characteristic(
        self,
        characteristic: PerformanceCharacteristic
    ) -> 'PremarketSubmissionBuilder':
        """Add performance characteristic."""
        self.performance_chars.append(characteristic)
        return self

    def add_risk_analysis(self, risk: RiskAnalysis) -> 'PremarketSubmissionBuilder':
        """Add risk analysis."""
        self.risks.append(risk)
        return self

    def set_training_data_description(self, description: str) -> 'PremarketSubmissionBuilder':
        """Set training data description."""
        self.training_data_desc = description
        return self

    def set_validation_data_description(self, description: str) -> 'PremarketSubmissionBuilder':
        """Set validation data description."""
        self.validation_data_desc = description
        return self

    def add_limitation(self, limitation: str) -> 'PremarketSubmissionBuilder':
        """Add known limitation."""
        self.limitations.append(limitation)
        return self

    def set_equity_assessment(self, assessment: str) -> 'PremarketSubmissionBuilder':
        """Set comprehensive equity assessment."""
        self.equity_assessment = assessment
        return self

    def set_clinical_validation_summary(self, summary: str) -> 'PremarketSubmissionBuilder':
        """Set clinical validation summary."""
        self.clinical_validation = summary
        return self

    def set_post_market_surveillance_plan(self, plan: str) -> 'PremarketSubmissionBuilder':
        """Set post-market surveillance plan."""
        self.surveillance_plan = plan
        return self

    def build(self) -> PremarketSubmission:
        """Build the complete submission package."""
        if self.intended_use_population is None:
            raise ValueError("Intended use population must be specified")

        return PremarketSubmission(
            device_name=self.device_name,
            manufacturer=self.manufacturer,
            device_class=self.device_class,
            regulatory_pathway=self.regulatory_pathway,
            intended_use=self.intended_use,
            intended_use_population=self.intended_use_population,
            predicate_device=self.predicate_device,
            indications_for_use=self.indications,
            performance_characteristics=self.performance_chars,
            risk_analyses=self.risks,
            clinical_validation_summary=self.clinical_validation,
            training_data_description=self.training_data_desc,
            validation_data_description=self.validation_data_desc,
            limitations_and_warnings=self.limitations,
            equity_assessment=self.equity_assessment,
            post_market_surveillance_plan=self.surveillance_plan
        )

def create_example_submission() -> PremarketSubmission:
    """
    Create example 510(k) submission for diabetic retinopathy screening AI.

    This example demonstrates comprehensive regulatory documentation with
    explicit attention to health equity throughout.

    Returns:
        Complete PremarketSubmission object
    """
    # Define intended use population
    population = IntendedUsePopulation(
        population_description=(
            "Adults aged 18 years and older with diabetes mellitus who have not "
            "been diagnosed with diabetic retinopathy, for screening to detect "
            "referable diabetic retinopathy defined as moderate non-proliferative "
            "diabetic retinopathy or worse"
        ),
        age_range=(18, None),
        clinical_settings=[
            "Primary care clinics",
            "Community health centers",
            "Federally Qualified Health Centers (FQHCs)",
            "Endocrinology clinics",
            "Optometry practices"
        ],
        geographic_regions=[
            "United States",
            "Urban and rural settings",
            "Including medically underserved areas"
        ],
        included_demographics={
            "Race/Ethnicity": [
                "White",
                "Black or African American",
                "Hispanic or Latino",
                "Asian",
                "American Indian or Alaska Native",
                "Native Hawaiian or Pacific Islander"
            ],
            "Sex": ["Male", "Female"],
            "Insurance Status": ["Medicare", "Medicaid", "Private Insurance", "Uninsured"],
            "Geographic Location": ["Urban", "Suburban", "Rural"]
        },
        clinical_conditions=[
            "Type 1 diabetes mellitus",
            "Type 2 diabetes mellitus",
            "With or without hypertension",
            "With or without hyperlipidemia"
        ],
        contraindications=[
            "Media opacity preventing adequate fundus visualization",
            "Previously diagnosed diabetic retinopathy",
            "Current ophthalmologic follow-up for retinopathy"
        ],
        performance_subgroups={
            "racial_ethnic_groups": (
                "Performance evaluated separately for major racial and ethnic groups"
            ),
            "care_settings": (
                "Performance evaluated in academic medical centers, community health "
                "centers, and FQHCs serving predominantly underserved populations"
            ),
            "image_quality": (
                "Performance evaluated across range of image quality grades with "
                "analysis of whether quality varies by care setting type"
            )
        },
        validation_populations=(
            "Validation cohort of 15,847 patients across 47 clinical sites including "
            "15 FQHCs, 12 community health centers, 8 private practices, 7 academic "
            "medical centers, and 5 rural clinics. Demographic distribution: 34% White, "
            "28% Black or African American, 24% Hispanic or Latino, 11% Asian, 3% other. "
            "Insurance: 41% Medicare, 27% Medicaid, 23% private, 9% uninsured. "
            "Geographic: 62% urban, 23% suburban, 15% rural. Mean age 58.7 years "
            "(SD 12.3), 48% female. Image quality: 82% adequate, 14% marginal, 4% poor."
        ),
        representation_notes=(
            "Validation cohort was specifically designed to over-represent populations "
            "experiencing healthcare disparities relative to national diabetes prevalence. "
            "This intentional oversampling ensures robust performance estimation for "
            "underserved groups rather than optimizing only for majority populations. "
            "Sites included 15 FQHCs and 12 community health centers to capture image "
            "quality and patient characteristics typical of resource-limited settings. "
            "Comparison to 2019-2020 NHANES data indicates validation cohort has higher "
            "proportion of racial/ethnic minorities (66% vs 44%), higher Medicaid coverage "
            "(27% vs 17%), and higher rural representation (15% vs 14%) than national "
            "diabetes population, ensuring estimates generalize to underserved patients."
        )
    )

    # Build submission
    builder = PremarketSubmissionBuilder(
        device_name="AI Diabetic Retinopathy Screening System",
        manufacturer="Equity-Focused Medical AI Corporation"
    )

    builder.set_device_classification(
        device_class=DeviceRiskClass.CLASS_II,
        regulatory_pathway=RegulatoryPathway.FIVE_TEN_K
    )

    builder.set_intended_use(
        "The AI Diabetic Retinopathy Screening System is indicated for automated "
        "detection of referable diabetic retinopathy in adults with diabetes. The "
        "device analyzes digital color fundus photographs and provides a binary "
        "classification of presence or absence of more-than-mild diabetic retinopathy "
        "(moderate non-proliferative diabetic retinopathy or worse, including severe "
        "non-proliferative diabetic retinopathy, proliferative diabetic retinopathy, "
        "or diabetic macular edema). The device is intended for use by healthcare "
        "providers to aid in detection of referable diabetic retinopathy during "
        "diabetes management. The device is not intended to replace comprehensive "
        "eye examination by an eye care professional."
    )

    builder.set_intended_use_population(population)

    builder.add_indication(
        "Screening for referable diabetic retinopathy in adults with diabetes"
    )

    # Performance characteristics
    # Overall sensitivity
    builder.add_performance_characteristic(
        PerformanceCharacteristic(
            metric_name="Sensitivity for Referable Diabetic Retinopathy",
            overall_value=0.912,
            confidence_interval=(0.896, 0.927),
            n_samples=15847,
            subgroup_performance={
                "White": (0.908, (0.885, 0.928), 5388),
                "Black or African American": (0.918, (0.893, 0.938), 4437),
                "Hispanic or Latino": (0.915, (0.889, 0.936), 3803),
                "Asian": (0.905, (0.869, 0.933), 1743),
                "American Indian/Alaska Native": (0.897, (0.837, 0.941), 476)
            },
            setting_performance={
                "Academic Medical Center": (0.925, (0.902, 0.944), 3256),
                "Community Health Center": (0.911, (0.885, 0.932), 4018),
                "FQHC": (0.908, (0.882, 0.929), 5145),
                "Private Practice": (0.917, (0.891, 0.938), 2328),
                "Rural Clinic": (0.903, (0.867, 0.932), 1100)
            },
            meets_specification=True,
            specification_threshold=0.87,
            clinical_significance=(
                "Sensitivity exceeds the 0.87 threshold established based on "
                "meta-analysis of retinal specialist performance. The system maintains "
                "sensitivity above this threshold across all major demographic groups "
                "and clinical settings, with maximum disparity of 0.021 (2.1 percentage "
                "points) between highest and lowest performing groups."
            )
        )
    )

    # Specificity
    builder.add_performance_characteristic(
        PerformanceCharacteristic(
            metric_name="Specificity for Referable Diabetic Retinopathy",
            overall_value=0.883,
            confidence_interval=(0.872, 0.893),
            n_samples=15847,
            subgroup_performance={
                "White": (0.891, (0.876, 0.905), 5388),
                "Black or African American": (0.877, (0.858, 0.894), 4437),
                "Hispanic or Latino": (0.881, (0.862, 0.898), 3803),
                "Asian": (0.886, (0.861, 0.907), 1743),
                "American Indian/Alaska Native": (0.868, (0.827, 0.902), 476)
            },
            setting_performance={
                "Academic Medical Center": (0.902, (0.885, 0.917), 3256),
                "Community Health Center": (0.879, (0.859, 0.897), 4018),
                "FQHC": (0.874, (0.855, 0.892), 5145),
                "Private Practice": (0.893, (0.873, 0.910), 2328),
                "Rural Clinic": (0.881, (0.854, 0.904), 1100)
            },
            meets_specification=True,
            specification_threshold=0.85,
            clinical_significance=(
                "Specificity meets the 0.85 threshold, balancing sensitivity with "
                "false positive rate. Higher specificity in academic medical centers "
                "may reflect better image quality. Specificity remains acceptable across "
                "all settings including FQHCs where image quality is more variable."
            )
        )
    )

    # AUC-ROC
    builder.add_performance_characteristic(
        PerformanceCharacteristic(
            metric_name="Area Under ROC Curve",
            overall_value=0.971,
            confidence_interval=(0.967, 0.975),
            n_samples=15847,
            subgroup_performance={
                "White": (0.973, (0.967, 0.978), 5388),
                "Black or African American": (0.969, (0.962, 0.975), 4437),
                "Hispanic or Latino": (0.972, (0.965, 0.978), 3803),
                "Asian": (0.968, (0.959, 0.976), 1743),
                "American Indian/Alaska Native": (0.965, (0.950, 0.978), 476)
            },
            setting_performance={
                "Academic Medical Center": (0.977, (0.971, 0.982), 3256),
                "Community Health Center": (0.970, (0.963, 0.976), 4018),
                "FQHC": (0.968, (0.962, 0.974), 5145),
                "Private Practice": (0.974, (0.967, 0.980), 2328),
                "Rural Clinic": (0.969, (0.960, 0.977), 1100)
            },
            meets_specification=True,
            specification_threshold=0.95,
            clinical_significance=(
                "Discrimination is excellent across all subgroups with narrow confidence "
                "intervals reflecting large sample sizes. Maximum disparity of 0.008 "
                "between highest and lowest AUC indicates equitable discriminative ability."
            )
        )
    )

    # Training data description
    builder.set_training_data_description(
        "Training dataset consisted of 128,175 color fundus photographs from 34,286 "
        "unique patients collected from 73 clinical sites between 2015-2020. Images "
        "were acquired using multiple camera types (Canon CR-2, Topcon TRC-NW400, "
        "Zeiss Visucam 500) reflecting equipment diversity in real-world settings. "
        "Ground truth labels were established through adjudicated consensus of three "
        "board-certified ophthalmologists, with specific attention to ensuring label "
        "quality was uniform across demographic groups. \n\n"
        "Training set demographics: 41% White, 24% Black or African American, 21% "
        "Hispanic or Latino, 11% Asian, 3% other. 46% female. Age distribution: "
        "18-39 (12%), 40-59 (45%), 60-79 (38%), 80+ (5%). Insurance: 38% Medicare, "
        "25% Medicaid, 28% private, 9% uninsured. Geographic: 58% urban, 26% suburban, "
        "16% rural. Sites included 22 FQHCs, 18 community health centers, 15 private "
        "practices, 12 academic medical centers, 6 rural clinics. \n\n"
        "Prevalence of referable diabetic retinopathy was 18.3% overall, with rates "
        "of 16.8% in White, 21.2% in Black or African American, 19.7% in Hispanic or "
        "Latino, 17.9% in Asian, and 22.4% in American Indian/Alaska Native patients, "
        "consistent with known epidemiologic patterns. Image quality distribution: "
        "79% adequate, 17% marginal, 4% poor, with comparable distributions across "
        "demographic groups after stratification by care setting type (quality "
        "variation primarily reflects setting rather than patient demographics)."
    )

    # Validation data description
    builder.set_validation_data_description(
        "Independent validation dataset described in Intended Use Population section. "
        "Validation sites were completely separate from training sites to assess "
        "generalization. Validation set was prospectively collected during 2021-2022 "
        "specifically for regulatory submission, with predetermined inclusion criteria "
        "and sampling design to ensure adequate representation of underserved populations. "
        "\n\nGround truth for validation set was established through dilated eye "
        "examination by board-certified ophthalmologists using seven-field stereo "
        "fundus photography and OCT imaging. Ophthalmologists were masked to AI system "
        "predictions. Inter-rater agreement among three ophthalmologists adjudicating "
        "ground truth labels was κ=0.89 (95% CI: 0.87-0.91). \n\n"
        "Special attention was given to ensuring geographic and facility diversity in "
        "validation set. Sites were selected to include high and low resource settings, "
        "urban and rural locations, and facilities serving predominantly underserved "
        "populations. This approach ensures validation reflects real-world deployment "
        "contexts including those most likely to serve health equity populations."
    )

    # Clinical validation summary
    builder.set_clinical_validation_summary(
        "Clinical validation study was a prospective, multi-site trial designed to "
        "evaluate the AI system's diagnostic accuracy compared to the reference "
        "standard of dilated eye examination by ophthalmologists. The study enrolled "
        "consecutive eligible patients presenting for diabetes care at 47 geographically "
        "diverse sites. Eligibility criteria included age ≥18 years, diagnosis of "
        "diabetes mellitus, and no prior diagnosis of diabetic retinopathy. Patients "
        "with media opacity preventing adequate fundus photography were excluded. "
        "\n\nImaging protocol specified acquisition of two 45-degree color fundus "
        "photographs per eye (macula-centered and disc-centered fields) using site's "
        "existing camera equipment without standardization, reflecting real-world "
        "deployment conditions. Images were uploaded to secure cloud platform and "
        "processed by AI system without human intervention. Within 48 hours, patients "
        "received dilated eye examination by board-certified ophthalmologist masked "
        "to AI results, establishing ground truth labels. \n\n"
        "Primary outcome was sensitivity and specificity for detecting referable "
        "diabetic retinopathy (moderate NPDR or worse) compared to ophthalmologist "
        "reference standard. Secondary outcomes included diagnostic accuracy stratified "
        "by demographic groups, care settings, and image quality grades. Pre-specified "
        "performance thresholds were sensitivity ≥0.87 and specificity ≥0.85 overall, "
        "with requirement that performance in each major demographic group and care "
        "setting type not fall below 0.85 for sensitivity or below 0.82 for specificity. "
        "\n\nResults demonstrated the AI system met all pre-specified performance "
        "criteria with sensitivity of 0.912 and specificity of 0.883 overall. Performance "
        "remained robust across all demographic subgroups and care settings, with no "
        "subgroup falling below the pre-specified thresholds. Statistical testing "
        "confirmed non-inferiority to ophthalmologist performance established in "
        "prior meta-analyses. Subgroup analyses revealed maximum performance disparity "
        "of 0.021 for sensitivity and 0.023 for specificity, well within pre-specified "
        "equity criteria of maximum 0.05 disparity."
    )

    # Risk analyses
    builder.add_risk_analysis(
        RiskAnalysis(
            risk_description=(
                "False negative: AI system fails to detect referable diabetic "
                "retinopathy when present, leading to delayed referral to ophthalmology "
                "and potential progression to vision-threatening complications"
            ),
            affected_populations=[
                "All patients screened with the system",
                "Particularly concerning for patients with limited healthcare access "
                "who may not receive alternative screening"
            ],
            severity="Serious",
            probability="Occasional",
            detection_methods=[
                "Continuous monitoring of sensitivity across demographic groups",
                "Analysis of false negative cases to identify patterns",
                "Patient complaint tracking and investigation"
            ],
            mitigation_strategies=[
                "Set decision threshold to achieve ≥0.87 sensitivity based on validation",
                "Require image quality check rejecting images insufficient for diagnosis",
                "Provide clear labeling that negative result does not replace comprehensive eye exam",
                "Recommend continued adherence to guideline-based screening intervals",
                "Implement post-market surveillance monitoring false negative rates by subgroup"
            ],
            residual_risk_level="Moderate",
            monitoring_plan=(
                "Post-market surveillance will track false negative cases identified "
                "through subsequent ophthalmology exams. Quarterly analysis will "
                "stratify false negative rates by demographic groups and care settings "
                "to detect any differential performance degradation. Automated alerts "
                "will trigger if false negative rate in any subgroup exceeds 0.13 "
                "(corresponding to sensitivity below 0.87)."
            ),
            equity_considerations=(
                "False negatives may disproportionately harm patients with limited "
                "healthcare access who rely more heavily on screening systems and may "
                "face greater barriers to obtaining follow-up care when referred. "
                "Validation specifically included FQHCs and rural clinics to ensure "
                "sensitivity remains adequate in these settings. Post-market monitoring "
                "stratifies by insurance status and clinic type to detect any equity "
                "issues in real-world deployment."
            )
        )
    )

    builder.add_risk_analysis(
        RiskAnalysis(
            risk_description=(
                "False positive: AI system incorrectly classifies no or mild diabetic "
                "retinopathy as referable, leading to unnecessary ophthalmology referrals, "
                "patient anxiety, and healthcare system burden"
            ),
            affected_populations=[
                "All patients screened with the system",
                "Particularly burdensome for patients facing barriers to specialist access"
            ],
            severity="Moderate",
            probability="Occasional",
            detection_methods=[
                "Monitoring of specificity and positive predictive value",
                "Analysis of referred patients found to not have referable retinopathy",
                "Healthcare system utilization data analysis"
            ],
            mitigation_strategies=[
                "Set decision threshold to achieve ≥0.85 specificity based on validation",
                "Provide probability scores to support clinical decision-making",
                "Clear labeling that positive result should be confirmed by eye care professional",
                "Monitor PPV across deployment sites with different disease prevalence"
            ],
            residual_risk_level="Low",
            monitoring_plan=(
                "Track positive predictive value across sites with different background "
                "retinopathy prevalence. Monitor referral patterns to ensure appropriate "
                "use of probability scores in clinical decision-making."
            ),
            equity_considerations=(
                "False positives create particular burden for patients facing geographic, "
                "financial, or transportation barriers to specialist care. However, "
                "missed diagnoses (false negatives) pose greater clinical risk. Threshold "
                "balances these considerations while maintaining adequate sensitivity. "
                "Patient education materials emphasize positive screening result indicates "
                "need for further evaluation, not definitive diagnosis."
            )
        )
    )

    builder.add_risk_analysis(
        RiskAnalysis(
            risk_description=(
                "Poor image quality leading to ungradable images, requiring repeat "
                "imaging or alternative screening approach"
            ),
            affected_populations=[
                "All patients, but potentially higher rates in settings with older camera "
                "equipment, less trained imaging staff, or patients with media opacity"
            ],
            severity="Minor",
            probability="Occasional",
            detection_methods=[
                "Automated image quality assessment prior to AI analysis",
                "Tracking ungradable image rates by site",
                "Analysis of demographic and clinical correlates of ungradable images"
            ],
            mitigation_strategies=[
                "Implement image quality assessment rejecting images insufficient for analysis",
                "Provide immediate feedback to imaging staff enabling re-capture",
                "Track ungradable rates by site and provide targeted technical assistance",
                "Validation included range of image qualities to establish appropriate thresholds"
            ],
            residual_risk_level="Very Low",
            monitoring_plan=(
                "Monitor ungradable image rates across sites, stratified by care setting "
                "type and camera equipment. Rates exceeding 10% trigger site assessment "
                "and potential additional training for imaging staff."
            ),
            equity_considerations=(
                "Resource-limited settings may have older camera equipment or less trained "
                "imaging staff, potentially leading to higher ungradable rates. Validation "
                "specifically included FQHCs and rural clinics to ensure quality thresholds "
                "are achievable with standard equipment. Post-market monitoring stratifies "
                "by site resource level to detect differential ungradable rates and target "
                "technical assistance accordingly."
            )
        )
    )

    builder.add_risk_analysis(
        RiskAnalysis(
            risk_description=(
                "Systematic performance degradation in specific subpopulations due to "
                "distribution shift, changes in clinical practice, or equipment updates"
            ),
            affected_populations=[
                "Potentially any patient subgroup, but particular concern for smaller "
                "demographic groups where performance degradation might be harder to detect"
            ],
            severity="Serious",
            probability="Rare",
            detection_methods=[
                "Continuous post-market surveillance with subgroup stratification",
                "Automated monitoring of performance metrics",
                "Analysis of user-reported issues and complaints"
            ],
            mitigation_strategies=[
                "Implement predetermined change control plan allowing model updates",
                "Establish automated monitoring system with demographic stratification",
                "Define performance thresholds triggering corrective action",
                "Require validation on new patient data prior to any model updates",
                "Maintain diverse training data pipeline enabling rapid retraining if needed"
            ],
            residual_risk_level="Low",
            monitoring_plan=(
                "Quarterly analysis of diagnostic accuracy stratified by demographic "
                "groups, care settings, and camera equipment types using cases with "
                "ophthalmologist ground truth labels. Automated alerts if sensitivity "
                "or specificity in any subgroup declines below pre-specified thresholds. "
                "Annual comprehensive validation study at representative sample of sites. "
                "Predetermined change control plan pre-approved by FDA enables rapid "
                "response to identified performance issues."
            ),
            equity_considerations=(
                "Performance degradation in underrepresented populations could go "
                "undetected in aggregate monitoring. Post-market surveillance explicitly "
                "stratifies all metrics by demographic groups with sample size targets "
                "ensuring adequate statistical power for each subgroup. Predetermined "
                "change control plan includes specific provisions for correcting "
                "disparities through targeted data collection and model updates if "
                "subgroup performance degrades."
            )
        )
    )

    # Limitations
    builder.add_limitation(
        "System is designed for screening patients without known diabetic retinopathy "
        "and should not be used for monitoring patients with previously diagnosed disease"
    )

    builder.add_limitation(
        "System analyzes only two 45-degree color fundus photographs per eye and may "
        "miss pathology visible only on additional imaging modalities or field positions"
    )

    builder.add_limitation(
        "System performance was validated on images from Canon, Topcon, and Zeiss "
        "fundus cameras; performance with other camera types is not established"
    )

    builder.add_limitation(
        "System was not validated in patients under age 18; performance in pediatric "
        "populations is unknown"
    )

    builder.add_limitation(
        "Validation study excluded patients with media opacity preventing adequate fundus "
        "visualization; system should not be used when image quality is insufficient"
    )

    builder.add_limitation(
        "System is not intended to replace comprehensive eye examination and should be "
        "used as part of diabetes care consistent with clinical practice guidelines"
    )

    # Equity assessment
    builder.set_equity_assessment(
        "DEMOGRAPHIC REPRESENTATION IN DEVELOPMENT AND VALIDATION\n\n"
        "The development program was specifically designed to prioritize equitable "
        "performance across diverse populations. Training data collection included "
        "intentional oversampling of underrepresented demographic groups and clinical "
        "settings serving underserved populations. The training cohort included 59% "
        "racial/ethnic minorities compared to 44% in the national diabetes population, "
        "ensuring adequate representation for learning equitable features. Site selection "
        "prioritized FQHCs (30% of training sites) and community health centers (25% of "
        "training sites) to capture image quality and patient characteristics typical of "
        "resource-limited settings.\n\n"
        "Validation study design maintained this equity focus through multi-site "
        "prospective enrollment with pre-specified demographic targets. The validation "
        "cohort achieved 66% racial/ethnic minority representation, 27% Medicaid coverage, "
        "and 15% rural location, deliberately enriching for populations that have "
        "historically experienced healthcare disparities. This approach ensures performance "
        "estimates are robust for underserved groups rather than optimized for majority "
        "populations.\n\n"
        "PERFORMANCE EQUITY ANALYSIS\n\n"
        "Primary analysis evaluated diagnostic accuracy stratified by race/ethnicity, sex, "
        "insurance status, geographic location, and care setting type. Performance metrics "
        "including sensitivity, specificity, and AUC-ROC were calculated for each subgroup "
        "with 95% confidence intervals. Statistical testing evaluated whether between-group "
        "differences exceeded pre-specified equity thresholds.\n\n"
        "Results demonstrate equitable performance across demographic groups:\n"
        "- Sensitivity ranged from 0.897 to 0.918 across racial/ethnic groups (disparity: 0.021)\n"
        "- Specificity ranged from 0.868 to 0.891 across racial/ethnic groups (disparity: 0.023)\n"
        "- AUC-ROC ranged from 0.965 to 0.973 across racial/ethnic groups (disparity: 0.008)\n"
        "- Performance by insurance status, sex, and geographic location showed similar equity\n\n"
        "All demographic subgroups met pre-specified minimum performance thresholds of "
        "sensitivity ≥0.85 and specificity ≥0.82. Statistical testing confirmed no "
        "demographic group performed significantly worse than others (p>0.05 for all "
        "pairwise comparisons after Bonferroni correction).\n\n"
        "CARE SETTING ANALYSIS\n\n"
        "Performance was evaluated across care setting types to ensure equitable function "
        "in resource-limited contexts. Settings included academic medical centers (gold "
        "standard), community health centers, FQHCs serving predominantly low-income "
        "populations, private practices, and rural clinics. Sensitivity ranged from 0.903 "
        "to 0.925 across settings, with academic medical centers showing highest performance "
        "likely due to better image quality from newer equipment and more trained imaging "
        "staff. Importantly, FQHCs and rural clinics maintained sensitivity of 0.908 and "
        "0.903 respectively, exceeding the 0.87 threshold and demonstrating adequate "
        "performance in resource-limited settings.\n\n"
        "Image quality analysis found ungradable image rates of 3.2% in academic medical "
        "centers, 4.8% in community health centers, 5.4% in FQHCs, 4.1% in private practices, "
        "and 6.1% in rural clinics. While resource-limited settings had modestly higher "
        "ungradable rates, all remained below 10% threshold for acceptable screening "
        "program performance. Importantly, ungradable rates did not correlate with patient "
        "demographics after controlling for care setting, indicating variation reflects "
        "equipment and technique differences rather than patient factors.\n\n"
        "FAIRNESS METRICS\n\n"
        "Multiple fairness metrics were evaluated:\n\n"
        "Equalized Odds: Maximum difference in true positive rate (sensitivity) across "
        "groups was 0.021 and maximum difference in false positive rate was 0.023, both "
        "well below 0.05 threshold for concerning disparity. The system achieves "
        "approximate equalized odds across demographic groups.\n\n"
        "Predictive Parity: Positive predictive value (PPV) ranged from 0.72 to 0.79 "
        "across racial/ethnic groups, with variation primarily reflecting different "
        "underlying disease prevalence rates (18-22%) consistent with known epidemiology "
        "rather than model bias. PPV was calculated separately for each care setting to "
        "account for prevalence differences.\n\n"
        "Calibration: Calibration curves were examined for each demographic group and care "
        "setting. Hosmer-Lemeshow goodness-of-fit tests indicated adequate calibration for "
        "all subgroups (p>0.05), with calibration slopes ranging from 0.96 to 1.04 across "
        "groups, indicating predicted probabilities correspond well to observed outcomes "
        "consistently across populations.\n\n"
        "IDENTIFIED LIMITATIONS AND RESIDUAL DISPARITIES\n\n"
        "Despite intentional equity focus, some limitations remain. Sample sizes for "
        "American Indian/Alaska Native patients (n=476) and Native Hawaiian/Pacific "
        "Islander patients (n=198, reported in 'other' category) are smaller than other "
        "groups, leading to wider confidence intervals and less precise performance estimates. "
        "While point estimates suggest adequate performance, larger validation cohorts "
        "for these populations would enable more definitive assessment.\n\n"
        "The study did not capture sexual orientation, gender identity, disability status, "
        "or primary language beyond English/Spanish. Performance for LGBTQ+ individuals, "
        "people with disabilities, and speakers of languages other than English and Spanish "
        "is unknown. These represent important gaps for future research.\n\n"
        "POST-MARKET SURVEILLANCE EQUITY PROVISIONS\n\n"
        "Post-market surveillance plan includes specific equity monitoring:\n\n"
        "- Quarterly performance analysis stratified by demographic groups with automated "
        "alerts if any subgroup falls below performance thresholds\n\n"
        "- Annual validation studies at representative sample of sites with intentional "
        "inclusion of safety-net settings serving underserved populations\n\n"
        "- User feedback mechanism with specific prompts for reporting potential fairness "
        "issues or differential performance\n\n"
        "- Predetermined change control plan includes provision for collecting additional "
        "training data from underperforming subgroups and retraining model to address "
        "disparities if detected\n\n"
        "- Public reporting of performance metrics stratified by demographics annually to "
        "maintain transparency and accountability\n\n"
        "CONCLUSION\n\n"
        "The AI Diabetic Retinopathy Screening System demonstrates equitable diagnostic "
        "accuracy across diverse patient populations and clinical settings. Intentional "
        "focus on health equity throughout development, from data collection through "
        "validation design through post-market surveillance planning, has resulted in a "
        "system that maintains robust performance for underserved populations. The device "
        "meets pre-specified equity criteria with performance disparities well within "
        "acceptable thresholds. Systematic post-market monitoring will ensure equitable "
        "performance is maintained during real-world deployment."
    )

    # Post-market surveillance plan
    builder.set_post_market_surveillance_plan(
        "POST-MARKET SURVEILLANCE OBJECTIVES\n\n"
        "The post-market surveillance system aims to continuously monitor device performance, "
        "safety, and equity during real-world deployment. Primary objectives include early "
        "detection of performance degradation, identification of adverse events, assessment "
        "of equity across patient populations, and evaluation of appropriate clinical use. "
        "The surveillance system incorporates both passive monitoring of routine device use "
        "and active validation studies.\n\n"
        "PERFORMANCE MONITORING\n\n"
        "Continuous monitoring of diagnostic accuracy stratified by demographics:\n\n"
        "Data Collection: All device predictions are logged with de-identified patient "
        "demographics, care setting characteristics, and image quality metrics. Ground "
        "truth outcomes are obtained for subset of patients through: (1) routine "
        "ophthalmology referrals with documented exam findings, (2) follow-up imaging "
        "showing disease progression or stability, and (3) quarterly validation studies "
        "at sample of sites with dilated eye exam reference standard.\n\n"
        "Sample Size: Target minimum 500 cases with ground truth per demographic subgroup "
        "per quarter, enabling detection of 0.05 performance change with 80% power. Higher "
        "sampling rates are implemented for smaller demographic groups to maintain "
        "statistical power.\n\n"
        "Metrics: Calculate sensitivity, specificity, positive predictive value, negative "
        "predictive value, and AUC-ROC stratified by race/ethnicity, sex, age group, "
        "insurance status, geographic location, and care setting type. Compute 95% "
        "confidence intervals and test for significant changes from baseline validation "
        "performance.\n\n"
        "Alert Thresholds: Automated alerts trigger if:\n"
        "- Any demographic subgroup sensitivity falls below 0.85\n"
        "- Any demographic subgroup specificity falls below 0.82\n"
        "- Performance disparity between highest and lowest performing groups exceeds 0.05\n"
        "- Any performance metric shows statistically significant decline from baseline\n"
        "- False negative rate for sight-threatening retinopathy exceeds 0.05\n\n"
        "Response Protocol: Alerts trigger immediate investigation including review of "
        "recent cases from affected subgroup, analysis of potential causes (distribution "
        "shift, equipment changes, workflow modifications), and implementation of corrective "
        "actions under predetermined change control plan if needed. FDA is notified of "
        "sustained performance degradation exceeding alert thresholds.\n\n"
        "SAFETY MONITORING\n\n"
        "Adverse Event Reporting: Healthcare providers are encouraged to report any adverse "
        "events potentially related to device use including delayed diagnoses due to false "
        "negatives, patient harm from inappropriate referral decisions, or system "
        "malfunctions. Reports are analyzed to identify patterns and implement corrections.\n\n"
        "Complaint Analysis: All user complaints are systematically categorized and analyzed "
        "for trends. Complaints are stratified by care setting type and demographics of "
        "affected patients to detect any systematic issues affecting specific populations.\n\n"
        "Near Miss Events: Healthcare providers are encouraged to report near miss events "
        "where device error was detected before causing patient harm, enabling proactive "
        "identification of potential failure modes.\n\n"
        "EQUITY MONITORING\n\n"
        "Demographic Stratification: All performance metrics are stratified by demographic "
        "groups with quarterly reporting. Trends are analyzed to detect any emerging "
        "disparities that might not be apparent in aggregate metrics.\n\n"
        "Care Setting Analysis: Performance is monitored separately for academic medical "
        "centers, community health centers, FQHCs, private practices, and rural clinics. "
        "Resource-limited settings are over-sampled in validation studies to ensure "
        "adequate monitoring of performance in underserved populations.\n\n"
        "Ungradable Image Rates: Track ungradable image rates by site and demographics to "
        "identify whether certain populations or settings experience differential access "
        "to successful screening. Sites with ungradable rates exceeding 10% receive "
        "targeted technical assistance.\n\n"
        "Health Equity Metrics: Calculate metrics including:\n"
        "- Difference in sensitivity between highest and lowest performing demographic groups\n"
        "- Ratio of positive predictive values across insurance status categories\n"
        "- Geographic variation in screening completion rates\n"
        "- Care setting differences in image quality and diagnostic accuracy\n\n"
        "ANNUAL VALIDATION STUDIES\n\n"
        "Comprehensive validation studies are conducted annually at representative sample "
        "of deployment sites:\n\n"
        "Site Selection: Sites are stratified by region, care setting type, and populations "
        "served. Each annual study includes minimum 5 FQHCs, 3 rural clinics, 3 community "
        "health centers, 2 academic medical centers, and 2 private practices.\n\n"
        "Patient Enrollment: Consecutive eligible patients are enrolled during 2-month "
        "window at each site with target total enrollment of 3,000 patients annually. "
        "Sampling design ensures adequate representation of demographic groups.\n\n"
        "Reference Standard: All enrolled patients receive dilated eye examination by "
        "board-certified ophthalmologist masked to AI results, establishing ground truth "
        "labels for performance assessment.\n\n"
        "Analysis: Calculate full diagnostic accuracy metrics stratified by demographics "
        "and compare to baseline validation performance. Assess calibration, examine "
        "failure modes, and identify any emerging fairness issues.\n\n"
        "PREDETERMINED CHANGE CONTROL\n\n"
        "The FDA-approved predetermined change control plan enables implementation of "
        "modifications without new regulatory submissions:\n\n"
        "Model Retraining: Model may be retrained with new images while maintaining "
        "architecture and training algorithm, provided retraining maintains performance "
        "thresholds (sensitivity ≥0.87, specificity ≥0.85) in all demographic subgroups "
        "and care settings. New training data must be collected from diverse sites and "
        "reviewed to ensure balanced representation. Retrained model requires validation "
        "on hold-out dataset stratified by demographics before deployment.\n\n"
        "Threshold Adjustment: Decision threshold may be adjusted within range 0.35-0.65 "
        "(validated range balancing sensitivity and specificity) to account for different "
        "deployment contexts or updated clinical guidelines, provided adjustment maintains "
        "minimum thresholds for both sensitivity and specificity across all subgroups.\n\n"
        "Image Quality Algorithm Updates: Image quality assessment algorithm may be updated "
        "to improve ungradable image detection or expand camera compatibility, provided "
        "updates maintain diagnostic accuracy and don't systematically exclude specific "
        "patient populations.\n\n"
        "Fairness Corrections: If monitoring detects emerging disparity exceeding thresholds, "
        "additional training data may be collected from underperforming subgroup(s) and "
        "model retrained with emphasis on equitable performance. This provision enables "
        "rapid response to fairness issues without regulatory delays.\n\n"
        "REPORTING AND TRANSPARENCY\n\n"
        "Quarterly Reports: Internal quarterly reports summarize all monitoring metrics, "
        "alert triggers, investigations, and corrective actions. Reports are provided to "
        "FDA upon request.\n\n"
        "Annual Public Reporting: Annual device performance report is published publicly "
        "including diagnostic accuracy metrics stratified by demographics, equity assessments, "
        "adverse event summaries, and any model updates implemented. This transparency "
        "enables healthcare providers and patients to make informed decisions about device "
        "use.\n\n"
        "FDA Reporting: Any sustained performance degradation below thresholds, serious "
        "adverse events, or equity concerns are promptly reported to FDA through medical "
        "device reporting system. Annual summary report is provided documenting all "
        "monitoring activities and results.\n\n"
        "CONTINUOUS IMPROVEMENT\n\n"
        "The post-market surveillance system is designed for continuous learning and "
        "improvement. Monitoring data informs ongoing development including identification "
        "of underserved populations requiring better representation, detection of failure "
        "modes enabling algorithm improvements, and understanding real-world deployment "
        "contexts to enhance system robustness. Regular review meetings evaluate surveillance "
        "effectiveness and identify opportunities to strengthen equity monitoring."
    )

    return builder.build()

# Example usage
if __name__ == "__main__":
    # Create example submission
    submission = create_example_submission()

    # Validate submission
    is_valid, issues = submission.validate_submission()

    print("Submission Validation:")
    print(f"Valid: {is_valid}")
    if issues:
        print("\nValidation Issues:")
        for issue in issues:
            print(f"  - {issue}")
    else:
        print("No validation issues found.")

    # Generate documentation
    output_path = Path("regulatory_submission.txt")
    submission.generate_document(output_path)
    print(f"\nGenerated regulatory submission document: {output_path}")

"""
FHIR-based AI deployment framework with equity monitoring.

This module provides production infrastructure for integrating AI systems
with EHRs via FHIR APIs, including comprehensive equity monitoring, missing
demographic data handling, and post-deployment performance tracking.
"""

from typing import Dict, List, Optional, Any, Tuple
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from enum import Enum
import numpy as np
import pandas as pd
from fhirclient import client
from fhirclient.models import patient, observation, condition
import logging
import json

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@dataclass
class PatientDemographics:
    """
    Structured demographics extracted from FHIR Patient resource.

    Tracks whether each field was available to enable missing data analysis.

    Attributes:
        patient_id: FHIR patient ID
        age: Patient age in years
        sex: Administrative sex
        race: Race categories (US Core standard)
        ethnicity: Ethnicity (US Core standard)
        preferred_language: Preferred language for communication
        zip_code: ZIP code for social determinants mapping
        insurance_type: Insurance category (Medicare, Medicaid, private, uninsured)
        has_race: Whether race was documented
        has_ethnicity: Whether ethnicity was documented
        has_preferred_language: Whether language preference was documented
        has_zip_code: Whether ZIP code was available
        has_insurance_type: Whether insurance was documented
    """
    patient_id: str
    age: Optional[int] = None
    sex: Optional[str] = None
    race: Optional[str] = None
    ethnicity: Optional[str] = None
    preferred_language: Optional[str] = None
    zip_code: Optional[str] = None
    insurance_type: Optional[str] = None
    has_race: bool = False
    has_ethnicity: bool = False
    has_preferred_language: bool = False
    has_zip_code: bool = False
    has_insurance_type: bool = False

    def completeness_score(self) -> float:
        """
        Calculate demographic data completeness for this patient.

        Returns:
            Proportion of demographic fields that are documented (0-1)
        """
        fields_checked = [
            self.has_race,
            self.has_ethnicity,
            self.has_preferred_language,
            self.has_zip_code,
            self.has_insurance_type
        ]
        return sum(fields_checked) / len(fields_checked)

@dataclass
class PredictionRequest:
    """
    Request for AI prediction including patient data and context.

    Attributes:
        patient_id: FHIR patient ID
        demographics: Patient demographics
        clinical_features: Clinical features for prediction
        care_setting: Care setting context (FQHC, academic center, etc.)
        prediction_timestamp: When prediction was requested
        requesting_user: User who requested prediction
    """
    patient_id: str
    demographics: PatientDemographics
    clinical_features: Dict[str, Any]
    care_setting: str
    prediction_timestamp: datetime
    requesting_user: Optional[str] = None

@dataclass
class PredictionResponse:
    """
    AI prediction with comprehensive documentation for equity monitoring.

    Attributes:
        patient_id: FHIR patient ID
        prediction: Primary prediction output
        probability: Probability score if applicable
        confidence_interval: Confidence interval for prediction
        contributing_features: Top features contributing to prediction
        prediction_timestamp: When prediction was generated
        model_version: Version of model used
        demographic_completeness: Proportion of demographics documented
        monitoring_flags: Any flags for quality or equity review
        explanation: Human-readable explanation of prediction
    """
    patient_id: str
    prediction: Any
    probability: Optional[float] = None
    confidence_interval: Optional[Tuple[float, float]] = None
    contributing_features: Dict[str, float] = field(default_factory=dict)
    prediction_timestamp: datetime = field(default_factory=datetime.now)
    model_version: str = ""
    demographic_completeness: float = 0.0
    monitoring_flags: List[str] = field(default_factory=list)
    explanation: str = ""

@dataclass
class PerformanceMetrics:
    """
    Performance metrics for monitoring deployed AI system.

    Attributes:
        period_start: Start of monitoring period
        period_end: End of monitoring period
        n_predictions: Total number of predictions
        n_with_outcomes: Number with ground truth outcomes
        overall_metrics: Performance metrics overall
        subgroup_metrics: Performance stratified by demographics
        missing_demographics_rate: Proportion of predictions with missing demographics
        demographic_completeness: Average demographic completeness score
    """
    period_start: datetime
    period_end: datetime
    n_predictions: int
    n_with_outcomes: int
    overall_metrics: Dict[str, float] = field(default_factory=dict)
    subgroup_metrics: Dict[str, Dict[str, float]] = field(default_factory=dict)
    missing_demographics_rate: Dict[str, float] = field(default_factory=dict)
    demographic_completeness: float = 0.0

class FHIRPatientExtractor:
    """
    Extract patient demographics from FHIR resources with equity focus.

    This class handles retrieving patient data via FHIR API and extracting
    demographic information while carefully tracking data completeness to
    enable equity monitoring despite missing demographics.
    """

    def __init__(self, fhir_base_url: str, client_id: Optional[str] = None):
        """
        Initialize FHIR client for patient data extraction.

        Args:
            fhir_base_url: Base URL for FHIR server
            client_id: Client ID for authentication if required
        """
        settings = {
            'app_id': client_id or 'equity_focused_ai_system',
            'api_base': fhir_base_url
        }
        self.client = client.FHIRClient(settings=settings)
        logger.info(f"Initialized FHIR client for {fhir_base_url}")

    def extract_demographics(self, patient_id: str) -> PatientDemographics:
        """
        Extract demographic information from FHIR Patient resource.

        This implementation follows US Core FHIR profiles for demographics
        and carefully tracks which fields are actually present vs. missing.

        Args:
            patient_id: FHIR patient ID

        Returns:
            PatientDemographics with completeness tracking
        """
        try:
            # Retrieve patient resource
            patient_resource = patient.Patient.read(patient_id, self.client.server)

            demographics = PatientDemographics(patient_id=patient_id)

            # Extract birth date and calculate age
            if patient_resource.birthDate:
                birth_date = patient_resource.birthDate.date
                today = datetime.today().date()
                demographics.age = (
                    today.year - birth_date.year -
                    ((today.month, today.day) < (birth_date.month, birth_date.day))
                )

            # Extract administrative sex
            if patient_resource.gender:
                demographics.sex = patient_resource.gender

            # Extract race from US Core extensions
            if patient_resource.extension:
                for ext in patient_resource.extension:
                    if 'us-core-race' in ext.url:
                        if ext.extension:
                            for sub_ext in ext.extension:
                                if sub_ext.url == 'ombCategory':
                                    if sub_ext.valueCoding:
                                        demographics.race = sub_ext.valueCoding.display
                                        demographics.has_race = True
                                        break
                    elif 'us-core-ethnicity' in ext.url:
                        if ext.extension:
                            for sub_ext in ext.extension:
                                if sub_ext.url == 'ombCategory':
                                    if sub_ext.valueCoding:
                                        demographics.ethnicity = sub_ext.valueCoding.display
                                        demographics.has_ethnicity = True
                                        break

            # Extract preferred language
            if patient_resource.communication:
                for comm in patient_resource.communication:
                    if comm.preferred:
                        if comm.language and comm.language.coding:
                            demographics.preferred_language = comm.language.coding[0].code
                            demographics.has_preferred_language = True
                            break

            # Extract address information
            if patient_resource.address:
                for addr in patient_resource.address:
                    if addr.postalCode:
                        demographics.zip_code = addr.postalCode
                        demographics.has_zip_code = True
                        break

            # Note: Insurance information typically requires separate Coverage resource query
            # Implementation would query for Coverage resources where beneficiary = patient_id

            completeness = demographics.completeness_score()
            logger.info(
                f"Extracted demographics for patient {patient_id}: "
                f"completeness={completeness:.2f}"
            )

            return demographics

        except Exception as e:
            logger.error(f"Error extracting demographics for patient {patient_id}: {str(e)}")
            # Return demographics object with patient_id but no data
            return PatientDemographics(patient_id=patient_id)

    def check_demographic_completeness(
        self,
        patient_ids: List[str]
    ) -> Dict[str, float]:
        """
        Analyze demographic data completeness across cohort.

        Args:
            patient_ids: List of patient IDs to analyze

        Returns:
            Dictionary of completeness rates by demographic field
        """
        completeness = {
            'race': 0.0,
            'ethnicity': 0.0,
            'preferred_language': 0.0,
            'zip_code': 0.0,
            'insurance_type': 0.0
        }

        n_patients = len(patient_ids)

        for patient_id in patient_ids:
            demographics = self.extract_demographics(patient_id)

            completeness['race'] += float(demographics.has_race)
            completeness['ethnicity'] += float(demographics.has_ethnicity)
            completeness['preferred_language'] += float(demographics.has_preferred_language)
            completeness['zip_code'] += float(demographics.has_zip_code)
            completeness['insurance_type'] += float(demographics.has_insurance_type)

        # Convert counts to rates
        for key in completeness:
            completeness[key] /= n_patients

        logger.info(f"Demographic completeness analysis across {n_patients} patients:")
        for field, rate in completeness.items():
            logger.info(f"  {field}: {rate:.1%}")

        return completeness

class EquityAwareDeploymentMonitor:
    """
    Monitoring system for deployed AI with comprehensive equity tracking.

    This class implements continuous monitoring of deployed AI systems with
    stratified performance analysis, missing demographic handling, and
    automated alerting for equity concerns.
    """

    def __init__(
        self,
        model_name: str,
        model_version: str,
        alert_thresholds: Optional[Dict[str, float]] = None
    ):
        """
        Initialize deployment monitoring system.

        Args:
            model_name: Name of deployed model
            model_version: Version identifier
            alert_thresholds: Thresholds for automated alerts
        """
        self.model_name = model_name
        self.model_version = model_version

        # Default alert thresholds
        self.alert_thresholds = alert_thresholds or {
            'min_sensitivity': 0.85,
            'min_specificity': 0.82,
            'max_disparity': 0.05,
            'min_calibration': 0.95,
            'max_calibration': 1.05
        }

        # Storage for predictions and outcomes
        self.predictions_log: List[Dict[str, Any]] = []
        self.outcomes_log: List[Dict[str, Any]] = []

        logger.info(f"Initialized monitoring for {model_name} v{model_version}")

    def log_prediction(
        self,
        prediction_request: PredictionRequest,
        prediction_response: PredictionResponse
    ) -> None:
        """
        Log prediction for monitoring and audit trail.

        Args:
            prediction_request: Original prediction request
            prediction_response: Model's prediction response
        """
        log_entry = {
            'patient_id': prediction_request.patient_id,
            'timestamp': prediction_response.prediction_timestamp.isoformat(),
            'prediction': prediction_response.prediction,
            'probability': prediction_response.probability,
            'model_version': prediction_response.model_version,
            'care_setting': prediction_request.care_setting,
            'demographic_completeness': prediction_response.demographic_completeness,
            'demographics': {
                'age': prediction_request.demographics.age,
                'sex': prediction_request.demographics.sex,
                'race': prediction_request.demographics.race,
                'ethnicity': prediction_request.demographics.ethnicity,
                'has_race': prediction_request.demographics.has_race,
                'has_ethnicity': prediction_request.demographics.has_ethnicity
            }
        }

        self.predictions_log.append(log_entry)
        logger.debug(f"Logged prediction for patient {prediction_request.patient_id}")

    def log_outcome(
        self,
        patient_id: str,
        outcome: Any,
        outcome_timestamp: datetime
    ) -> None:
        """
        Log ground truth outcome for performance monitoring.

        Args:
            patient_id: Patient ID
            outcome: Ground truth outcome
            outcome_timestamp: When outcome occurred/was documented
        """
        outcome_entry = {
            'patient_id': patient_id,
            'outcome': outcome,
            'outcome_timestamp': outcome_timestamp.isoformat()
        }

        self.outcomes_log.append(outcome_entry)
        logger.debug(f"Logged outcome for patient {patient_id}")

    def compute_performance(
        self,
        period_start: datetime,
        period_end: datetime
    ) -> PerformanceMetrics:
        """
        Compute performance metrics for specified time period.

        Args:
            period_start: Start of monitoring period
            period_end: End of monitoring period

        Returns:
            PerformanceMetrics with stratified analysis
        """
        # Filter predictions and outcomes to period
        predictions_df = pd.DataFrame(self.predictions_log)
        outcomes_df = pd.DataFrame(self.outcomes_log)

        predictions_df['timestamp'] = pd.to_datetime(predictions_df['timestamp'])
        outcomes_df['outcome_timestamp'] = pd.to_datetime(outcomes_df['outcome_timestamp'])

        period_predictions = predictions_df[
            (predictions_df['timestamp'] >= period_start) &
            (predictions_df['timestamp'] <= period_end)
        ]

        # Join with outcomes
        merged = period_predictions.merge(
            outcomes_df[['patient_id', 'outcome']],
            on='patient_id',
            how='left'
        )

        n_predictions = len(merged)
        n_with_outcomes = merged['outcome'].notna().sum()

        # Compute overall metrics
        complete_cases = merged[merged['outcome'].notna()].copy()

        if len(complete_cases) > 0:
            y_true = complete_cases['outcome'].values
            y_pred = complete_cases['prediction'].values
            y_prob = complete_cases['probability'].values

            from sklearn.metrics import accuracy_score, roc_auc_score, confusion_matrix

            overall_metrics = {
                'accuracy': accuracy_score(y_true, y_pred),
                'auc_roc': roc_auc_score(y_true, y_prob) if y_prob.mean() > 0 else None
            }

            # Compute sensitivity and specificity
            tn, fp, fn, tp = confusion_matrix(y_true, y_pred).ravel()
            overall_metrics['sensitivity'] = tp / (tp + fn) if (tp + fn) > 0 else None
            overall_metrics['specificity'] = tn / (tn + fp) if (tn + fp) > 0 else None
        else:
            overall_metrics = {}

        # Compute subgroup metrics where demographics are available
        subgroup_metrics = {}

        for demo_field in ['race', 'ethnicity', 'sex']:
            subgroup_metrics[demo_field] = {}

            # Only analyze where demographic is documented
            has_demo = complete_cases[
                complete_cases['demographics'].apply(
                    lambda x: x.get(f'has_{demo_field}', False)
                )
            ]

            if len(has_demo) > 0:
                for group_value in has_demo['demographics'].apply(
                    lambda x: x.get(demo_field)
                ).unique():
                    if group_value and group_value != 'Unknown':
                        group_data = has_demo[
                            has_demo['demographics'].apply(
                                lambda x: x.get(demo_field) == group_value
                            )
                        ]

                        if len(group_data) >= 30:  # Minimum sample size
                            y_true_group = group_data['outcome'].values
                            y_pred_group = group_data['prediction'].values

                            tn, fp, fn, tp = confusion_matrix(
                                y_true_group, y_pred_group
                            ).ravel()

                            subgroup_metrics[demo_field][group_value] = {
                                'n': len(group_data),
                                'sensitivity': tp / (tp + fn) if (tp + fn) > 0 else None,
                                'specificity': tn / (tn + fp) if (tn + fp) > 0 else None
                            }

        # Analyze missing demographics
        missing_demographics_rate = {
            'race': 1 - period_predictions['demographics'].apply(
                lambda x: x.get('has_race', False)
            ).mean(),
            'ethnicity': 1 - period_predictions['demographics'].apply(
                lambda x: x.get('has_ethnicity', False)
            ).mean()
        }

        avg_completeness = period_predictions['demographic_completeness'].mean()

        metrics = PerformanceMetrics(
            period_start=period_start,
            period_end=period_end,
            n_predictions=n_predictions,
            n_with_outcomes=n_with_outcomes,
            overall_metrics=overall_metrics,
            subgroup_metrics=subgroup_metrics,
            missing_demographics_rate=missing_demographics_rate,
            demographic_completeness=avg_completeness
        )

        logger.info(
            f"Computed performance metrics for period {period_start} to {period_end}: "
            f"{n_predictions} predictions, {n_with_outcomes} with outcomes"
        )

        return metrics

    def check_alerts(self, metrics: PerformanceMetrics) -> List[str]:
        """
        Check performance metrics against alert thresholds.

        Args:
            metrics: Performance metrics to evaluate

        Returns:
            List of alert messages for issues detected
        """
        alerts = []

        # Check overall performance
        if 'sensitivity' in metrics.overall_metrics:
            sens = metrics.overall_metrics['sensitivity']
            if sens < self.alert_thresholds['min_sensitivity']:
                alerts.append(
                    f"Overall sensitivity ({sens:.3f}) below threshold "
                    f"({self.alert_thresholds['min_sensitivity']:.3f})"
                )

        if 'specificity' in metrics.overall_metrics:
            spec = metrics.overall_metrics['specificity']
            if spec < self.alert_thresholds['min_specificity']:
                alerts.append(
                    f"Overall specificity ({spec:.3f}) below threshold "
                    f"({self.alert_thresholds['min_specificity']:.3f})"
                )

        # Check for performance disparities
        for demo_field, subgroups in metrics.subgroup_metrics.items():
            if len(subgroups) > 1:
                sensitivities = [
                    sg['sensitivity'] for sg in subgroups.values()
                    if sg['sensitivity'] is not None
                ]
                if sensitivities:
                    disparity = max(sensitivities) - min(sensitivities)
                    if disparity > self.alert_thresholds['max_disparity']:
                        alerts.append(
                            f"Sensitivity disparity across {demo_field} ({disparity:.3f}) "
                            f"exceeds threshold ({self.alert_thresholds['max_disparity']:.3f})"
                        )

        # Check missing demographics rates
        for demo_field, missing_rate in metrics.missing_demographics_rate.items():
            if missing_rate > 0.4:  # More than 40% missing
                alerts.append(
                    f"High missing rate for {demo_field} ({missing_rate:.1%}), "
                    f"limiting equity monitoring capability"
                )

        if alerts:
            logger.warning(f"Detected {len(alerts)} performance alerts")
            for alert in alerts:
                logger.warning(f"  ALERT: {alert}")

        return alerts