Chapter 18: Implementation Science for Clinical AI Systems

"""
Equity-centered implementation readiness assessment for healthcare AI.

This module provides production tools for evaluating organizational readiness
to implement healthcare AI systems with comprehensive attention to factors
that may create differential implementation success across care settings and
patient populations. The framework synthesizes constructs from RE-AIM, CFIR,
and PRISM with explicit equity evaluation.
"""

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

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

class ReadinessLevel(Enum):
    """Implementation readiness classification."""
    READY = "Ready for Implementation"
    READY_WITH_SUPPORT = "Ready with Additional Support"
    NEEDS_PREPARATION = "Needs Preparation Before Implementation"
    NOT_READY = "Not Ready for Implementation"

class SettingType(Enum):
    """Healthcare setting classification."""
    ACADEMIC_MEDICAL_CENTER = "Academic Medical Center"
    COMMUNITY_HOSPITAL = "Community Hospital"
    CRITICAL_ACCESS_HOSPITAL = "Critical Access Hospital"
    FQHC = "Federally Qualified Health Center"
    COMMUNITY_HEALTH_CENTER = "Community Health Center"
    PRIVATE_PRACTICE = "Private Practice"
    RURAL_CLINIC = "Rural Clinic"
    SAFETY_NET_HOSPITAL = "Safety-Net Hospital"

@dataclass
class PopulationCharacteristics:
    """
    Characteristics of patient population served by implementing organization.

    Captures demographic composition, social determinants, and resource access
    patterns to enable equity-centered implementation planning.
    """
    primary_payer_distribution: Dict[str, float]  # payer type -> proportion
    race_ethnicity_distribution: Dict[str, float]
    primary_language_distribution: Dict[str, float]
    age_distribution: Dict[str, float]  # age group -> proportion

    # Social determinants of health
    median_household_income: float
    area_deprivation_index_median: float
    percent_below_poverty_line: float
    percent_uninsured: float

    # Digital access indicators
    percent_with_internet_access: float
    percent_with_smartphone_access: float
    digital_literacy_score: float  # 0-100 scale from community assessment

    # Healthcare access patterns
    percent_with_usual_source_of_care: float
    average_travel_distance_to_facility: float  # miles
    percent_requiring_interpretation_services: float


@dataclass
class TechnicalInfrastructure:
    """
    Technical capacity assessment for AI deployment.

    Evaluates IT infrastructure, data systems, and technical expertise
    necessary for successful AI implementation.
    """
    # EHR and data systems
    ehr_system: str
    ehr_version: str
    data_warehouse_exists: bool
    real_time_data_access: bool
    interoperability_standards_supported: List[str]  # e.g., ["FHIR", "HL7v2"]

    # IT infrastructure
    it_staff_count: int
    has_dedicated_ml_engineering: bool
    has_clinical_informatics_expertise: bool
    server_infrastructure_adequate: bool
    network_bandwidth_adequate: bool

    # Model deployment capabilities
    can_deploy_containerized_models: bool
    has_model_monitoring_infrastructure: bool
    has_api_integration_capability: bool
    cybersecurity_certification: Optional[str]

    # Data governance
    has_data_governance_committee: bool
    has_algorithmic_fairness_policy: bool
    has_model_validation_procedures: bool


@dataclass
class OrganizationalContext:
    """
    Organizational characteristics influencing implementation success.

    Captures culture, leadership, change readiness, and resources following
    CFIR inner setting domain with equity extensions.
    """
    setting_type: SettingType
    annual_patient_volume: int
    annual_revenue: float
    margin_percent: float  # operating margin

    # Leadership and governance
    has_executive_ai_champion: bool
    has_clinical_ai_champion: bool
    has_patient_advisory_council: bool
    has_health_equity_leadership: bool

    # Organizational culture
    innovation_culture_score: float  # 0-100 from organizational assessment
    staff_change_readiness_score: float
    staff_ai_attitudes_score: float
    staff_health_equity_commitment_score: float

    # Resources and capacity
    has_quality_improvement_infrastructure: bool
    has_research_office: bool
    dedicated_implementation_team: bool
    training_capacity_adequate: bool

    # Workload and competing demands
    clinician_burnout_score: float  # 0-100, higher indicates more burnout
    competing_implementation_projects: int
    recent_major_organizational_change: bool


@dataclass
class ClinicianCharacteristics:
    """
    Characteristics of clinician population who will use AI system.

    Captures knowledge, attitudes, skills, and diversity of clinician
    workforce relevant to AI adoption.
    """
    total_clinician_count: int
    clinician_types: Dict[str, int]  # specialty -> count

    # Demographics and experience
    median_years_in_practice: float
    age_distribution: Dict[str, float]
    race_ethnicity_diversity_index: float  # 0-1, higher more diverse
    language_capabilities: List[str]

    # AI knowledge and attitudes
    ai_knowledge_score: float  # 0-100 from baseline assessment
    ai_attitudes_score: float
    clinical_decision_support_experience_score: float
    bias_awareness_score: float

    # Workflow factors
    average_patients_per_day: float
    ehr_time_per_patient: float  # minutes
    has_scribes_or_support_staff: bool


@dataclass
class ImplementationReadinessAssessment:
    """
    Comprehensive readiness assessment for healthcare AI implementation.

    Synthesizes technical, organizational, clinician, and population factors
    to evaluate implementation readiness with equity lens.
    """
    organization_name: str
    assessment_date: datetime
    ai_system_description: str

    # Context data
    population: PopulationCharacteristics
    technical: TechnicalInfrastructure
    organizational: OrganizationalContext
    clinicians: ClinicianCharacteristics

    # Calculated scores
    technical_readiness_score: float = 0.0
    organizational_readiness_score: float = 0.0
    clinician_readiness_score: float = 0.0
    equity_readiness_score: float = 0.0
    overall_readiness_score: float = 0.0
    overall_readiness_level: Optional[ReadinessLevel] = None

    # Identified barriers and facilitators
    barriers: List[str] = field(default_factory=list)
    facilitators: List[str] = field(default_factory=list)
    equity_concerns: List[str] = field(default_factory=list)

    # Recommendations
    recommendations: List[str] = field(default_factory=list)
    required_preparations: List[str] = field(default_factory=list)
    implementation_strategy_elements: List[str] = field(default_factory=list)


class EquityCenteredReadinessEvaluator:
    """
    Evaluator for implementation readiness with equity focus.

    Assesses organizational capacity to implement healthcare AI successfully
    and equitably, identifying barriers that may lead to differential
    implementation across populations or settings.
    """

    def __init__(
        self,
        technical_weight: float = 0.25,
        organizational_weight: float = 0.25,
        clinician_weight: float = 0.25,
        equity_weight: float = 0.25
    ):
        """
        Initialize readiness evaluator.

        Parameters
        ----------
        technical_weight : float
            Weight for technical readiness in overall score
        organizational_weight : float
            Weight for organizational readiness
        clinician_weight : float
            Weight for clinician readiness
        equity_weight : float
            Weight for equity readiness
        """
        if not np.isclose(
            technical_weight + organizational_weight +
            clinician_weight + equity_weight,
            1.0
        ):
            raise ValueError("Readiness weights must sum to 1.0")

        self.technical_weight = technical_weight
        self.organizational_weight = organizational_weight
        self.clinician_weight = clinician_weight
        self.equity_weight = equity_weight

        logger.info("Initialized equity-centered readiness evaluator")

    def evaluate_readiness(
        self,
        organization_name: str,
        ai_system_description: str,
        population: PopulationCharacteristics,
        technical: TechnicalInfrastructure,
        organizational: OrganizationalContext,
        clinicians: ClinicianCharacteristics
    ) -> ImplementationReadinessAssessment:
        """
        Perform comprehensive readiness assessment.

        Parameters
        ----------
        organization_name : str
            Name of implementing organization
        ai_system_description : str
            Description of AI system to be implemented
        population : PopulationCharacteristics
            Patient population characteristics
        technical : TechnicalInfrastructure
            Technical infrastructure assessment
        organizational : OrganizationalContext
            Organizational context
        clinicians : ClinicianCharacteristics
            Clinician characteristics

        Returns
        -------
        ImplementationReadinessAssessment
            Comprehensive readiness evaluation with scores and recommendations
        """
        logger.info(f"Evaluating implementation readiness for {organization_name}")

        assessment = ImplementationReadinessAssessment(
            organization_name=organization_name,
            assessment_date=datetime.now(),
            ai_system_description=ai_system_description,
            population=population,
            technical=technical,
            organizational=organizational,
            clinicians=clinicians
        )

        # Calculate component scores
        assessment.technical_readiness_score = self._evaluate_technical_readiness(
            technical, organizational
        )
        assessment.organizational_readiness_score = self._evaluate_organizational_readiness(
            organizational
        )
        assessment.clinician_readiness_score = self._evaluate_clinician_readiness(
            clinicians, organizational
        )
        assessment.equity_readiness_score = self._evaluate_equity_readiness(
            population, organizational, clinicians
        )

        # Calculate overall score
        assessment.overall_readiness_score = (
            self.technical_weight * assessment.technical_readiness_score +
            self.organizational_weight * assessment.organizational_readiness_score +
            self.clinician_weight * assessment.clinician_readiness_score +
            self.equity_weight * assessment.equity_readiness_score
        )

        # Determine readiness level
        assessment.overall_readiness_level = self._determine_readiness_level(
            assessment.overall_readiness_score,
            assessment.technical_readiness_score,
            assessment.organizational_readiness_score,
            assessment.clinician_readiness_score,
            assessment.equity_readiness_score
        )

        # Identify barriers and facilitators
        self._identify_barriers_facilitators(assessment)

        # Generate recommendations
        self._generate_recommendations(assessment)

        logger.info(
            f"Assessment complete. Overall readiness: "
            f"{assessment.overall_readiness_score:.1f}/100 "
            f"({assessment.overall_readiness_level.value})"
        )

        return assessment

    def _evaluate_technical_readiness(
        self,
        technical: TechnicalInfrastructure,
        organizational: OrganizationalContext
    ) -> float:
        """
        Evaluate technical infrastructure readiness.

        Assesses IT systems, data infrastructure, and technical expertise
        necessary for AI deployment.
        """
        score = 0.0
        max_score = 100.0

        # EHR and data systems (30 points)
        if technical.data_warehouse_exists:
            score += 10
        if technical.real_time_data_access:
            score += 10
        if "FHIR" in technical.interoperability_standards_supported:
            score += 10

        # IT staffing and expertise (25 points)
        # Scale by organization size
        expected_it_staff = max(2, organizational.annual_patient_volume / 50000)
        if technical.it_staff_count >= expected_it_staff:
            score += 10
        elif technical.it_staff_count >= 0.5 * expected_it_staff:
            score += 5

        if technical.has_dedicated_ml_engineering:
            score += 10
        elif technical.has_clinical_informatics_expertise:
            score += 5

        if technical.has_clinical_informatics_expertise:
            score += 5

        # Infrastructure (25 points)
        if technical.server_infrastructure_adequate:
            score += 10
        if technical.network_bandwidth_adequate:
            score += 5
        if technical.can_deploy_containerized_models:
            score += 5
        if technical.has_api_integration_capability:
            score += 5

        # Monitoring and governance (20 points)
        if technical.has_model_monitoring_infrastructure:
            score += 10
        if technical.has_data_governance_committee:
            score += 5
        if technical.has_model_validation_procedures:
            score += 5

        return score

    def _evaluate_organizational_readiness(
        self,
        organizational: OrganizationalContext
    ) -> float:
        """
        Evaluate organizational context and culture readiness.

        Assesses leadership support, culture, resources, and competing demands.
        """
        score = 0.0

        # Leadership (25 points)
        if organizational.has_executive_ai_champion:
            score += 10
        if organizational.has_clinical_ai_champion:
            score += 10
        if organizational.has_health_equity_leadership:
            score += 5

        # Culture (30 points)
        score += 0.15 * organizational.innovation_culture_score
        score += 0.10 * organizational.staff_change_readiness_score
        score += 0.05 * organizational.staff_health_equity_commitment_score

        # Infrastructure (25 points)
        if organizational.has_quality_improvement_infrastructure:
            score += 10
        if organizational.dedicated_implementation_team:
            score += 10
        if organizational.training_capacity_adequate:
            score += 5

        # Capacity (20 points)
        # Penalize for high burnout and competing demands
        burnout_penalty = 0.20 * organizational.clinician_burnout_score
        score += (20 - burnout_penalty)

        if organizational.competing_implementation_projects > 3:
            score -= 5
        if organizational.recent_major_organizational_change:
            score -= 5

        # Financial stability
        if organizational.margin_percent < 0:
            score -= 10

        return max(0, score)

    def _evaluate_clinician_readiness(
        self,
        clinicians: ClinicianCharacteristics,
        organizational: OrganizationalContext
    ) -> float:
        """
        Evaluate clinician knowledge, attitudes, and capacity.

        Assesses whether clinicians have knowledge, attitudes, and workflow
        capacity to successfully adopt AI system.
        """
        score = 0.0

        # Knowledge and attitudes (50 points)
        score += 0.20 * clinicians.ai_knowledge_score
        score += 0.15 * clinicians.ai_attitudes_score
        score += 0.10 * clinicians.bias_awareness_score
        score += 0.05 * clinicians.clinical_decision_support_experience_score

        # Workforce diversity (10 points)
        # Diverse workforce better positioned to identify equity issues
        score += 10 * clinicians.race_ethnicity_diversity_index

        # Workflow capacity (20 points)
        if clinicians.has_scribes_or_support_staff:
            score += 10

        # Penalize if very high patient volume without support
        if clinicians.average_patients_per_day > 25 and not clinicians.has_scribes_or_support_staff:
            score -= 10
        elif clinicians.average_patients_per_day > 20:
            score += 5
        else:
            score += 10

        # Language capabilities (10 points)
        # Match to patient population needs
        if len(clinicians.language_capabilities) > 1:
            score += 10

        # Workforce size adequacy (10 points)
        expected_clinicians = organizational.annual_patient_volume / 2000
        if clinicians.total_clinician_count >= expected_clinicians:
            score += 10
        elif clinicians.total_clinician_count >= 0.75 * expected_clinicians:
            score += 5

        return max(0, score)

    def _evaluate_equity_readiness(
        self,
        population: PopulationCharacteristics,
        organizational: OrganizationalContext,
        clinicians: ClinicianCharacteristics
    ) -> float:
        """
        Evaluate organizational capacity to implement equitably.

        Assesses whether organization can address digital divides, language
        barriers, and other factors that may create differential implementation
        success across populations.
        """
        score = 100.0  # Start at 100, penalize for equity concerns

        # Digital access barriers
        if population.percent_with_internet_access < 0.80:
            score -= 15
        elif population.percent_with_internet_access < 0.90:
            score -= 5

        if population.digital_literacy_score < 60:
            score -= 15
        elif population.digital_literacy_score < 70:
            score -= 5

        # Language and interpretation needs
        if population.percent_requiring_interpretation_services > 0.20:
            if len(clinicians.language_capabilities) <= 1:
                score -= 15
            else:
                score -= 5

        # Healthcare access barriers
        if population.average_travel_distance_to_facility > 20:
            score -= 10
        if population.percent_with_usual_source_of_care < 0.70:
            score -= 10

        # Social determinants burden
        if population.percent_below_poverty_line > 0.25:
            score -= 10
        if population.percent_uninsured > 0.15:
            score -= 10
        if population.area_deprivation_index_median > 70:
            score -= 10

        # Organizational equity infrastructure
        if organizational.has_patient_advisory_council:
            score += 5
        if organizational.has_health_equity_leadership:
            score += 5
        if organizational.staff_health_equity_commitment_score > 75:
            score += 5

        # Safety-net and resource-constrained settings
        if organizational.setting_type in [
            SettingType.FQHC,
            SettingType.SAFETY_NET_HOSPITAL,
            SettingType.CRITICAL_ACCESS_HOSPITAL
        ]:
            # These settings need extra support for equitable implementation
            if organizational.margin_percent < 0.02:
                score -= 10

        return max(0, min(100, score))

    def _determine_readiness_level(
        self,
        overall_score: float,
        technical_score: float,
        organizational_score: float,
        clinician_score: float,
        equity_score: float
    ) -> ReadinessLevel:
        """
        Determine overall readiness level from component scores.

        Uses both overall score and component minimums to ensure no critical
        gaps exist even if average is acceptable.
        """
        min_component_score = min(
            technical_score,
            organizational_score,
            clinician_score,
            equity_score
        )

        # Require all components meet minimum thresholds
        if overall_score >= 80 and min_component_score >= 70:
            return ReadinessLevel.READY
        elif overall_score >= 70 and min_component_score >= 60:
            return ReadinessLevel.READY_WITH_SUPPORT
        elif overall_score >= 50 and min_component_score >= 40:
            return ReadinessLevel.NEEDS_PREPARATION
        else:
            return ReadinessLevel.NOT_READY

    def _identify_barriers_facilitators(
        self,
        assessment: ImplementationReadinessAssessment
    ) -> None:
        """
        Identify specific barriers and facilitators from assessment data.

        Populates barriers, facilitators, and equity_concerns lists with
        concrete findings from assessment.
        """
        tech = assessment.technical
        org = assessment.organizational
        clin = assessment.clinicians
        pop = assessment.population

        # Technical barriers
        if not tech.data_warehouse_exists:
            assessment.barriers.append(
                "Lack of data warehouse infrastructure limits model training and monitoring"
            )
        if not tech.real_time_data_access:
            assessment.barriers.append(
                "Lack of real-time data access limits ability to deploy time-sensitive AI"
            )
        if tech.it_staff_count < 2:
            assessment.barriers.append(
                "Insufficient IT staffing for model deployment and troubleshooting"
            )
        if not tech.has_model_monitoring_infrastructure:
            assessment.barriers.append(
                "No infrastructure for ongoing model performance monitoring"
            )

        # Technical facilitators
        if "FHIR" in tech.interoperability_standards_supported:
            assessment.facilitators.append(
                "FHIR support enables standardized data access for AI"
            )
        if tech.has_dedicated_ml_engineering:
            assessment.facilitators.append(
                "Dedicated ML engineering expertise supports successful deployment"
            )

        # Organizational barriers
        if org.margin_percent < 0:
            assessment.barriers.append(
                "Negative operating margin limits resources for implementation"
            )
        if org.clinician_burnout_score > 70:
            assessment.barriers.append(
                "High clinician burnout may limit capacity to adopt new workflows"
            )
        if not org.training_capacity_adequate:
            assessment.barriers.append(
                "Inadequate training capacity for clinician education on AI system"
            )
        if org.competing_implementation_projects > 3:
            assessment.barriers.append(
                "Multiple competing implementation projects strain resources"
            )

        # Organizational facilitators
        if org.has_executive_ai_champion and org.has_clinical_ai_champion:
            assessment.facilitators.append(
                "Strong executive and clinical champions support AI adoption"
            )
        if org.innovation_culture_score > 75:
            assessment.facilitators.append(
                "Strong innovation culture facilitates technology adoption"
            )
        if org.dedicated_implementation_team:
            assessment.facilitators.append(
                "Dedicated implementation team enables systematic deployment"
            )

        # Clinician barriers
        if clin.ai_knowledge_score < 50:
            assessment.barriers.append(
                "Limited clinician AI knowledge requires extensive education"
            )
        if clin.ai_attitudes_score < 50:
            assessment.barriers.append(
                "Negative clinician attitudes toward AI may impede adoption"
            )
        if clin.average_patients_per_day > 25 and not clin.has_scribes_or_support_staff:
            assessment.barriers.append(
                "High patient volume without support staff limits time for AI engagement"
            )

        # Clinician facilitators
        if clin.clinical_decision_support_experience_score > 70:
            assessment.facilitators.append(
                "Prior clinical decision support experience facilitates AI adoption"
            )
        if clin.bias_awareness_score > 70:
            assessment.facilitators.append(
                "High bias awareness supports equity-centered implementation"
            )

        # Equity concerns
        if pop.percent_with_internet_access < 0.80:
            assessment.equity_concerns.append(
                "Limited internet access in patient population may limit AI reach"
            )
        if pop.digital_literacy_score < 60:
            assessment.equity_concerns.append(
                "Low digital literacy may create barriers to patient-facing AI tools"
            )
        if pop.percent_requiring_interpretation_services > 0.20 and len(clin.language_capabilities) <= 1:
            assessment.equity_concerns.append(
                "High interpretation needs with limited clinician language capabilities"
            )
        if pop.average_travel_distance_to_facility > 20:
            assessment.equity_concerns.append(
                "Large travel distances may limit follow-up for AI-triggered interventions"
            )
        if pop.percent_uninsured > 0.15:
            assessment.equity_concerns.append(
                "High uninsured rate may limit access to AI-recommended services"
            )
        if org.setting_type in [SettingType.FQHC, SettingType.SAFETY_NET_HOSPITAL]:
            assessment.equity_concerns.append(
                f"Safety-net setting ({org.setting_type.value}) requires additional support"
            )

    def _generate_recommendations(
        self,
        assessment: ImplementationReadinessAssessment
    ) -> None:
        """
        Generate specific recommendations based on identified gaps.

        Provides concrete action items for addressing barriers and building
        on facilitators, with prioritization by implementation readiness level.
        """
        level = assessment.overall_readiness_level

        # Technical recommendations
        if assessment.technical_readiness_score < 70:
            if not assessment.technical.data_warehouse_exists:
                assessment.required_preparations.append(
                    "Establish data warehouse or alternative data infrastructure"
                )
            if not assessment.technical.has_model_monitoring_infrastructure:
                assessment.required_preparations.append(
                    "Implement model monitoring infrastructure before deployment"
                )
            if assessment.technical.it_staff_count < 2:
                assessment.recommendations.append(
                    "Hire IT staff or contract with external technical support"
                )

        # Organizational recommendations
        if assessment.organizational_readiness_score < 70:
            if not assessment.organizational.has_clinical_ai_champion:
                assessment.required_preparations.append(
                    "Identify and engage clinical champion before implementation"
                )
            if assessment.organizational.clinician_burnout_score > 70:
                assessment.recommendations.append(
                    "Address clinician burnout before adding new workflow demands"
                )
            if not assessment.organizational.dedicated_implementation_team:
                assessment.recommendations.append(
                    "Assemble dedicated implementation team with protected time"
                )

        # Clinician recommendations
        if assessment.clinician_readiness_score < 70:
            if assessment.clinicians.ai_knowledge_score < 50:
                assessment.required_preparations.append(
                    "Provide comprehensive AI education before deployment"
                )
            if assessment.clinicians.bias_awareness_score < 50:
                assessment.required_preparations.append(
                    "Include bias awareness and health equity training"
                )

        # Equity recommendations
        if assessment.equity_readiness_score < 70:
            if assessment.population.digital_literacy_score < 60:
                assessment.implementation_strategy_elements.append(
                    "Design low-literacy interfaces and provide digital literacy support"
                )
            if assessment.population.percent_requiring_interpretation_services > 0.20:
                assessment.implementation_strategy_elements.append(
                    "Ensure AI system supports multiple languages and interpretation workflow"
                )
            if assessment.population.percent_uninsured > 0.15:
                assessment.implementation_strategy_elements.append(
                    "Verify AI-recommended interventions are accessible to uninsured patients"
                )

        # General implementation strategy recommendations
        if level == ReadinessLevel.READY:
            assessment.implementation_strategy_elements.extend([
                "Pilot deployment in limited clinical area with intensive monitoring",
                "Establish feedback mechanisms for rapid iteration",
                "Plan phased expansion based on pilot outcomes"
            ])
        elif level == ReadinessLevel.READY_WITH_SUPPORT:
            assessment.implementation_strategy_elements.extend([
                "Partner with external implementation support organization",
                "Allocate additional resources for training and technical assistance",
                "Establish regular check-ins with implementation science experts"
            ])
        elif level == ReadinessLevel.NEEDS_PREPARATION:
            assessment.recommendations.append(
                "Complete required preparations before attempting implementation"
            )
            assessment.recommendations.append(
                "Reassess readiness after addressing critical gaps"
            )
        else:  # NOT_READY
            assessment.recommendations.append(
                "Implementation not advisable until major gaps addressed"
            )
            assessment.recommendations.append(
                "Consider whether AI system appropriate for this setting"
            )
            assessment.recommendations.append(
                "Explore alternative interventions that better fit current capacity"
            )

    def generate_readiness_report(
        self,
        assessment: ImplementationReadinessAssessment,
        output_path: Path
    ) -> None:
        """
        Generate comprehensive readiness report.

        Parameters
        ----------
        assessment : ImplementationReadinessAssessment
            Completed readiness assessment
        output_path : Path
            Path for output report
        """
        with open(output_path, 'w') as f:
            f.write("=" * 80 + "\n")
            f.write("IMPLEMENTATION READINESS ASSESSMENT REPORT\n")
            f.write("=" * 80 + "\n\n")

            f.write(f"Organization: {assessment.organization_name}\n")
            f.write(f"Assessment Date: {assessment.assessment_date.strftime('%Y-%m-%d')}\n")
            f.write(f"AI System: {assessment.ai_system_description}\n\n")

            f.write("-" * 80 + "\n")
            f.write("READINESS SCORES\n")
            f.write("-" * 80 + "\n\n")

            f.write(f"Overall Readiness: {assessment.overall_readiness_score:.1f}/100\n")
            f.write(f"Readiness Level: {assessment.overall_readiness_level.value}\n\n")

            f.write("Component Scores:\n")
            f.write(f"  Technical Readiness:       {assessment.technical_readiness_score:.1f}/100\n")
            f.write(f"  Organizational Readiness:  {assessment.organizational_readiness_score:.1f}/100\n")
            f.write(f"  Clinician Readiness:       {assessment.clinician_readiness_score:.1f}/100\n")
            f.write(f"  Equity Readiness:          {assessment.equity_readiness_score:.1f}/100\n\n")

            if assessment.facilitators:
                f.write("-" * 80 + "\n")
                f.write("FACILITATORS\n")
                f.write("-" * 80 + "\n\n")
                for facilitator in assessment.facilitators:
                    f.write(f"• {facilitator}\n")
                f.write("\n")

            if assessment.barriers:
                f.write("-" * 80 + "\n")
                f.write("BARRIERS\n")
                f.write("-" * 80 + "\n\n")
                for barrier in assessment.barriers:
                    f.write(f"• {barrier}\n")
                f.write("\n")

            if assessment.equity_concerns:
                f.write("-" * 80 + "\n")
                f.write("EQUITY CONCERNS\n")
                f.write("-" * 80 + "\n\n")
                for concern in assessment.equity_concerns:
                    f.write(f"• {concern}\n")
                f.write("\n")

            if assessment.required_preparations:
                f.write("-" * 80 + "\n")
                f.write("REQUIRED PREPARATIONS\n")
                f.write("-" * 80 + "\n\n")
                for prep in assessment.required_preparations:
                    f.write(f"• {prep}\n")
                f.write("\n")

            if assessment.recommendations:
                f.write("-" * 80 + "\n")
                f.write("RECOMMENDATIONS\n")
                f.write("-" * 80 + "\n\n")
                for rec in assessment.recommendations:
                    f.write(f"• {rec}\n")
                f.write("\n")

            if assessment.implementation_strategy_elements:
                f.write("-" * 80 + "\n")
                f.write("IMPLEMENTATION STRATEGY ELEMENTS\n")
                f.write("-" * 80 + "\n\n")
                for element in assessment.implementation_strategy_elements:
                    f.write(f"• {element}\n")
                f.write("\n")

        logger.info(f"Readiness report saved to {output_path}")

"""
Stakeholder engagement framework for equitable healthcare AI implementation.

This module provides tools for planning, conducting, and documenting stakeholder
engagement that centers community voices and ensures meaningful participation in
implementation decisions affecting underserved populations.
"""

from dataclasses import dataclass, field
from typing import Dict, List, Optional, Set
from enum import Enum
from datetime import datetime
import pandas as pd
import json
import logging

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

class StakeholderType(Enum):
    """Categories of stakeholders in AI implementation."""
    CLINICIAN = "Clinician"
    PATIENT = "Patient"
    COMMUNITY_MEMBER = "Community Member"
    COMMUNITY_HEALTH_WORKER = "Community Health Worker"
    ADMINISTRATOR = "Health System Administrator"
    IT_STAFF = "IT/Technical Staff"
    QUALITY_IMPROVEMENT = "Quality Improvement Staff"
    COMMUNITY_ORGANIZATION = "Community Organization Representative"
    PATIENT_ADVOCATE = "Patient Advocate"

class EngagementMethod(Enum):
    """Methods for stakeholder engagement."""
    ADVISORY_BOARD = "Advisory Board Meeting"
    FOCUS_GROUP = "Focus Group"
    INDIVIDUAL_INTERVIEW = "Individual Interview"
    SURVEY = "Survey"
    WORKSHOP = "Workshop/Design Session"
    USABILITY_TESTING = "Usability Testing"
    COMMUNITY_FORUM = "Community Forum"
    CO_DESIGN_SESSION = "Co-Design Session"

class DecisionAuthority(Enum):
    """Level of stakeholder authority in decision making."""
    INFORM = "Inform Only"
    CONSULT = "Consult for Input"
    INVOLVE = "Involve in Options Development"
    COLLABORATE = "Collaborate on Decision"
    EMPOWER = "Empower to Decide"

@dataclass
class Stakeholder:
    """
    Individual stakeholder participating in engagement.

    Tracks demographics, perspectives, and engagement history to ensure
    diverse voices are included throughout implementation.
    """
    stakeholder_id: str
    stakeholder_type: StakeholderType
    demographics: Dict[str, str]  # race, ethnicity, language, etc.
    represents_underserved: bool

    # Background and expertise
    years_in_role: Optional[float] = None
    specialty_or_focus: Optional[str] = None
    practice_setting: Optional[str] = None

    # Engagement history
    engagement_dates: List[datetime] = field(default_factory=list)
    engagement_methods: List[EngagementMethod] = field(default_factory=list)
    compensation_provided: float = 0.0

    # Perspectives captured
    concerns_raised: List[str] = field(default_factory=list)
    suggestions_made: List[str] = field(default_factory=list)
    equity_issues_identified: List[str] = field(default_factory=list)

@dataclass
class EngagementActivity:
    """
    Specific stakeholder engagement activity.

    Documents what engagement occurred, who participated, what input was
    received, and how input influenced implementation decisions.
    """
    activity_id: str
    activity_date: datetime
    method: EngagementMethod
    decision_authority_level: DecisionAuthority

    # Participants
    participants: List[str]  # stakeholder_ids
    participant_demographics_summary: Dict[str, float]  # race -> proportion, etc.

    # Activity details
    topics_discussed: List[str]
    materials_provided: List[str]
    compensation_per_participant: float

    # Input received
    key_themes: List[str]
    concerns_raised: List[str]
    suggestions_received: List[str]
    equity_issues_identified: List[str]

    # Follow-up and influence
    actions_taken: List[str] = field(default_factory=list)
    implementation_changes: List[str] = field(default_factory=list)
    feedback_provided_to_stakeholders: bool = False
    feedback_date: Optional[datetime] = None

@dataclass
class EngagementPlan:
    """
    Comprehensive stakeholder engagement plan for AI implementation.

    Specifies who will be engaged, how, when, and with what authority
    throughout the implementation lifecycle.
    """
    project_name: str
    ai_system_description: str
    target_populations: List[str]
    care_settings: List[str]

    # Engagement strategy
    engagement_goals: List[str]
    underserved_population_focus: bool
    community_based_participatory_approach: bool

    # Stakeholder inventory
    stakeholders: Dict[str, Stakeholder]  # stakeholder_id -> Stakeholder

    # Planned activities
    planned_activities: List[EngagementActivity]
    completed_activities: List[EngagementActivity] = field(default_factory=list)

    # Decision points and authority
    key_decisions: List[str] = field(default_factory=list)
    stakeholder_decision_authority: Dict[str, DecisionAuthority] = field(default_factory=dict)

    # Equity evaluation
    diversity_goals: Dict[str, float] = field(default_factory=dict)  # demographic -> min proportion
    diversity_achieved: Dict[str, float] = field(default_factory=dict)

    # Budget
    total_compensation_budget: float = 0.0
    compensation_paid: float = 0.0

class EquityC enteredEngagementManager:
    """
    Manager for stakeholder engagement with equity focus.

    Facilitates inclusive engagement processes that center voices of
    underserved communities and ensure meaningful influence on implementation.
    """

    def __init__(self):
        """Initialize engagement manager."""
        logger.info("Initialized equity-centered engagement manager")

    def create_engagement_plan(
        self,
        project_name: str,
        ai_system_description: str,
        target_populations: List[str],
        care_settings: List[str],
        engagement_goals: List[str],
        diversity_goals: Dict[str, float]
    ) -> EngagementPlan:
        """
        Create comprehensive engagement plan.

        Parameters
        ----------
        project_name : str
            Name of AI implementation project
        ai_system_description : str
            Description of AI system being implemented
        target_populations : List[str]
            Patient populations who will be affected
        care_settings : List[str]
            Clinical settings where AI will be deployed
        engagement_goals : List[str]
            Specific goals for stakeholder engagement
        diversity_goals : Dict[str, float]
            Target proportions for stakeholder diversity

        Returns
        -------
        EngagementPlan
            Structured engagement plan
        """
        plan = EngagementPlan(
            project_name=project_name,
            ai_system_description=ai_system_description,
            target_populations=target_populations,
            care_settings=care_settings,
            engagement_goals=engagement_goals,
            underserved_population_focus=True,
            community_based_participatory_approach=True,
            stakeholders={},
            planned_activities=[],
            diversity_goals=diversity_goals
        )

        logger.info(f"Created engagement plan for {project_name}")
        return plan

    def recruit_stakeholders(
        self,
        plan: EngagementPlan,
        recruitment_strategy: Dict[str, str]
    ) -> None:
        """
        Recruit diverse stakeholders with attention to representation.

        Parameters
        ----------
        plan : EngagementPlan
            Engagement plan being developed
        recruitment_strategy : Dict[str, str]
            Strategy for recruiting each stakeholder type
        """
        logger.info(f"Recruiting stakeholders for {plan.project_name}")

        # In production, this would interface with recruitment systems
        # Here we provide the structure for tracking recruitment

        required_types = [
            StakeholderType.CLINICIAN,
            StakeholderType.PATIENT,
            StakeholderType.COMMUNITY_MEMBER,
            StakeholderType.COMMUNITY_HEALTH_WORKER
        ]

        logger.info("Stakeholder recruitment should ensure:")
        logger.info("1. Diverse representation across demographics")
        logger.info("2. Inclusion of underserved community members")
        logger.info("3. Range of perspectives and experiences")
        logger.info("4. Adequate representation from each care setting")

    def plan_engagement_activities(
        self,
        plan: EngagementPlan,
        implementation_timeline: pd.DataFrame
    ) -> None:
        """
        Plan engagement activities aligned with implementation milestones.

        Parameters
        ----------
        plan : EngagementPlan
            Engagement plan being developed
        implementation_timeline : pd.DataFrame
            Timeline of implementation activities and decision points
        """
        logger.info("Planning engagement activities")

        # Key phases requiring engagement
        phases = [
            {
                "phase": "Pre-Development",
                "methods": [EngagementMethod.FOCUS_GROUP, EngagementMethod.COMMUNITY_FORUM],
                "authority": DecisionAuthority.COLLABORATE,
                "topics": ["Needs assessment", "Use case prioritization", "Equity concerns"]
            },
            {
                "phase": "Development",
                "methods": [EngagementMethod.WORKSHOP, EngagementMethod.ADVISORY_BOARD],
                "authority": DecisionAuthority.COLLABORATE,
                "topics": ["Model design", "Fairness constraints", "Validation approach"]
            },
            {
                "phase": "Pre-Deployment",
                "methods": [EngagementMethod.USABILITY_TESTING, EngagementMethod.ADVISORY_BOARD],
                "authority": DecisionAuthority.EMPOWER,
                "topics": ["Interface design", "Workflow integration", "Go/no-go decision"]
            },
            {
                "phase": "Deployment",
                "methods": [EngagementMethod.INDIVIDUAL_INTERVIEW, EngagementMethod.SURVEY],
                "authority": DecisionAuthority.INVOLVE,
                "topics": ["User experience", "Workflow challenges", "Equity impact"]
            },
            {
                "phase": "Post-Deployment",
                "methods": [EngagementMethod.ADVISORY_BOARD, EngagementMethod.COMMUNITY_FORUM],
                "authority": DecisionAuthority.COLLABORATE,
                "topics": ["Performance evaluation", "Fairness monitoring", "Refinement needs"]
            }
        ]

        for phase_info in phases:
            logger.info(f"Phase: {phase_info['phase']}")
            logger.info(f"  Methods: {[m.value for m in phase_info['methods']]}")
            logger.info(f"  Authority Level: {phase_info['authority'].value}")

    def conduct_activity(
        self,
        plan: EngagementPlan,
        activity: EngagementActivity
    ) -> None:
        """
        Conduct and document engagement activity.

        Parameters
        ----------
        plan : EngagementPlan
            Overall engagement plan
        activity : EngagementActivity
            Specific activity being conducted
        """
        logger.info(f"Conducting {activity.method.value} on {activity.activity_date}")

        # Validate diverse participation
        self._validate_diversity(activity, plan.diversity_goals)

        # Document activity
        plan.completed_activities.append(activity)

        # Update stakeholder records
        for participant_id in activity.participants:
            if participant_id in plan.stakeholders:
                stakeholder = plan.stakeholders[participant_id]
                stakeholder.engagement_dates.append(activity.activity_date)
                stakeholder.engagement_methods.append(activity.method)
                stakeholder.compensation_provided += activity.compensation_per_participant
                stakeholder.concerns_raised.extend(activity.concerns_raised)
                stakeholder.suggestions_made.extend(activity.suggestions_received)

        # Update compensation tracking
        plan.compensation_paid += (
            activity.compensation_per_participant * len(activity.participants)
        )

        logger.info(f"Activity completed with {len(activity.participants)} participants")

    def _validate_diversity(
        self,
        activity: EngagementActivity,
        diversity_goals: Dict[str, float]
    ) -> None:
        """Validate that activity meets diversity goals."""
        for demographic, goal_proportion in diversity_goals.items():
            if demographic in activity.participant_demographics_summary:
                actual = activity.participant_demographics_summary[demographic]
                if actual < goal_proportion * 0.8:  # Allow some flexibility
                    logger.warning(
                        f"{demographic} representation ({actual:.1%}) below "
                        f"goal ({goal_proportion:.1%}) in this activity"
                    )

    def synthesize_stakeholder_input(
        self,
        plan: EngagementPlan
    ) -> Dict[str, List[str]]:
        """
        Synthesize themes from stakeholder input across activities.

        Parameters
        ----------
        plan : EngagementPlan
            Engagement plan with completed activities

        Returns
        -------
        Dict[str, List[str]]
            Synthesized themes by category
        """
        synthesis = {
            "key_concerns": [],
            "implementation_suggestions": [],
            "equity_issues": [],
            "workflow_recommendations": [],
            "community_priorities": []
        }

        # Aggregate across activities
        all_concerns = []
        all_suggestions = []
        all_equity_issues = []

        for activity in plan.completed_activities:
            all_concerns.extend(activity.concerns_raised)
            all_suggestions.extend(activity.suggestions_received)
            all_equity_issues.extend(activity.equity_issues_identified)

        # In production, would use NLP for theme extraction
        # Here we structure the process

        logger.info(f"Synthesized input from {len(plan.completed_activities)} activities")
        logger.info(f"Total concerns raised: {len(all_concerns)}")
        logger.info(f"Total suggestions: {len(all_suggestions)}")
        logger.info(f"Equity issues identified: {len(all_equity_issues)}")

        return synthesis

    def document_influence_on_decisions(
        self,
        plan: EngagementPlan,
        decision: str,
        stakeholder_input_considered: List[str],
        how_input_influenced_decision: str,
        input_not_incorporated: Optional[List[str]] = None,
        rationale_for_not_incorporating: Optional[str] = None
    ) -> None:
        """
        Document how stakeholder input influenced implementation decisions.

        Critical for accountability and demonstrating meaningful engagement
        rather than token consultation.

        Parameters
        ----------
        decision : str
            Implementation decision made
        stakeholder_input_considered : List[str]
            Specific stakeholder input that was considered
        how_input_influenced_decision : str
            Explanation of input's influence on decision
        input_not_incorporated : Optional[List[str]]
            Input that was not incorporated
        rationale_for_not_incorporating : Optional[str]
            Explanation for not incorporating certain input
        """
        logger.info(f"Documenting stakeholder influence on decision: {decision}")

        documentation = {
            "decision": decision,
            "input_considered": stakeholder_input_considered,
            "influence": how_input_influenced_decision,
            "input_not_incorporated": input_not_incorporated or [],
            "rationale": rationale_for_not_incorporating or "N/A",
            "timestamp": datetime.now().isoformat()
        }

        # In production, would store in decision log
        logger.info("Decision influence documented")

        # Provide feedback to stakeholders
        self._provide_feedback_to_stakeholders(plan, decision, documentation)

    def _provide_feedback_to_stakeholders(
        self,
        plan: EngagementPlan,
        decision: str,
        documentation: Dict
    ) -> None:
        """Provide feedback to stakeholders about how their input was used."""
        logger.info("Providing feedback to stakeholders about decision")

        # In production, would send communications to stakeholders
        # documenting how their input influenced decisions

        feedback_message = f"""
        Thank you for your participation in our engagement process for {plan.project_name}.

        Decision: {decision}

        Your input helped shape this decision in the following ways:
        {documentation['influence']}

        We carefully considered all suggestions raised during our engagement activities.
        Some input could not be incorporated due to technical, resource, or regulatory
        constraints, but we want to explain our reasoning:
        {documentation['rationale']}

        We value your continued partnership as we move forward with implementation.
        """

        logger.info("Stakeholder feedback communication prepared")

    def generate_engagement_report(
        self,
        plan: EngagementPlan,
        output_path: Path
    ) -> None:
        """
        Generate comprehensive report documenting engagement process.

        Parameters
        ----------
        plan : EngagementPlan
            Completed or ongoing engagement plan
        output_path : Path
            Path for output report
        """
        with open(output_path, 'w') as f:
            f.write("=" * 80 + "\n")
            f.write("STAKEHOLDER ENGAGEMENT REPORT\n")
            f.write("=" * 80 + "\n\n")

            f.write(f"Project: {plan.project_name}\n")
            f.write(f"AI System: {plan.ai_system_description}\n\n")

            f.write("-" * 80 + "\n")
            f.write("ENGAGEMENT SUMMARY\n")
            f.write("-" * 80 + "\n\n")

            f.write(f"Total Stakeholders Engaged: {len(plan.stakeholders)}\n")
            f.write(f"Total Activities Conducted: {len(plan.completed_activities)}\n")
            f.write(f"Total Compensation Provided: ${plan.compensation_paid:,.2f}\n\n")

            # Stakeholder diversity
            f.write("-" * 80 + "\n")
            f.write("STAKEHOLDER DIVERSITY\n")
            f.write("-" * 80 + "\n\n")

            f.write("Stakeholder Types:\n")
            type_counts = {}
            for s in plan.stakeholders.values():
                type_counts[s.stakeholder_type.value] = type_counts.get(s.stakeholder_type.value, 0) + 1
            for stype, count in type_counts.items():
                f.write(f"  {stype}: {count}\n")
            f.write("\n")

            underserved_count = sum(
                1 for s in plan.stakeholders.values() if s.represents_underserved
            )
            f.write(f"Stakeholders Representing Underserved Communities: {underserved_count}\n\n")

            # Activities
            f.write("-" * 80 + "\n")
            f.write("ENGAGEMENT ACTIVITIES\n")
            f.write("-" * 80 + "\n\n")

            for activity in plan.completed_activities:
                f.write(f"Date: {activity.activity_date.strftime('%Y-%m-%d')}\n")
                f.write(f"Method: {activity.method.value}\n")
                f.write(f"Participants: {len(activity.participants)}\n")
                f.write(f"Authority Level: {activity.decision_authority_level.value}\n")
                f.write(f"Topics: {', '.join(activity.topics_discussed)}\n")
                f.write("\n")

            # Key themes
            f.write("-" * 80 + "\n")
            f.write("KEY THEMES FROM STAKEHOLDER INPUT\n")
            f.write("-" * 80 + "\n\n")

            all_themes = []
            for activity in plan.completed_activities:
                all_themes.extend(activity.key_themes)

            if all_themes:
                for theme in set(all_themes):
                    f.write(f"• {theme}\n")
            f.write("\n")

        logger.info(f"Engagement report saved to {output_path}")

"""
Equity-focused implementation evaluation dashboard for healthcare AI.

This module provides comprehensive tools for measuring, analyzing, and
visualizing implementation outcomes with systematic stratification across
patient demographics, care settings, and equity dimensions.
"""

from dataclasses import dataclass, field
from typing import Dict, List, Optional, Tuple
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
from scipy import stats
from datetime import datetime, timedelta
import logging

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

@dataclass
class ImplementationMetrics:
    """
    Core implementation science metrics with equity stratification.

    Tracks adoption, reach, fidelity, and other implementation outcomes
    across patient populations and care settings.
    """
    # Temporal scope
    measurement_start_date: datetime
    measurement_end_date: datetime

    # Adoption metrics
    total_eligible_settings: int
    settings_adopting: int
    adoption_rate: float = 0.0
    adoption_by_setting_type: Dict[str, float] = field(default_factory=dict)
    adoption_by_region: Dict[str, float] = field(default_factory=dict)

    # Reach metrics
    total_eligible_patients: int
    patients_exposed_to_ai: int
    reach_rate: float = 0.0
    reach_by_demographics: Dict[str, float] = field(default_factory=dict)
    reach_by_insurance: Dict[str, float] = field(default_factory=dict)
    reach_by_setting_type: Dict[str, float] = field(default_factory=dict)

    # Fidelity metrics
    intended_use_compliance_rate: float = 0.0
    fidelity_by_setting_type: Dict[str, float] = field(default_factory=dict)
    technical_issues_per_setting: Dict[str, int] = field(default_factory=dict)

    # Acceptability and satisfaction
    clinician_satisfaction_score: float = 0.0  # 0-100
    patient_satisfaction_score: float = 0.0
    satisfaction_by_demographics: Dict[str, float] = field(default_factory=dict)

    # Clinical impact
    clinical_outcome_changes: Dict[str, float] = field(default_factory=dict)
    outcome_changes_by_demographics: Dict[str, Dict[str, float]] = field(default_factory=dict)
    disparity_changes: Dict[str, float] = field(default_factory=dict)

    # Resource utilization
    implementation_costs: float = 0.0
    ongoing_maintenance_costs: float = 0.0
    cost_per_patient_reached: float = 0.0

class EquityFocusedImplementationEvaluator:
    """
    Evaluator for implementation outcomes with equity focus.

    Provides comprehensive assessment of whether AI implementation
    succeeds uniformly or creates disparities requiring intervention.
    """

    def __init__(self):
        """Initialize implementation evaluator."""
        self.metrics_history: List[ImplementationMetrics] = []
        logger.info("Initialized equity-focused implementation evaluator")

    def calculate_implementation_metrics(
        self,
        measurement_start: datetime,
        measurement_end: datetime,
        patient_data: pd.DataFrame,
        setting_data: pd.DataFrame,
        ai_usage_data: pd.DataFrame,
        clinical_outcomes_data: pd.DataFrame
    ) -> ImplementationMetrics:
        """
        Calculate comprehensive implementation metrics.

        Parameters
        ----------
        measurement_start : datetime
            Start of measurement period
        measurement_end : datetime
            End of measurement period
        patient_data : pd.DataFrame
            Patient demographics and characteristics
        setting_data : pd.DataFrame
            Care setting characteristics
        ai_usage_data : pd.DataFrame
            AI system usage logs
        clinical_outcomes_data : pd.DataFrame
            Clinical outcomes during implementation period

        Returns
        -------
        ImplementationMetrics
            Comprehensive metrics with equity stratification
        """
        logger.info(f"Calculating implementation metrics for {measurement_start} to {measurement_end}")

        metrics = ImplementationMetrics(
            measurement_start_date=measurement_start,
            measurement_end_date=measurement_end,
            total_eligible_settings=len(setting_data),
            total_eligible_patients=len(patient_data)
        )

        # Calculate adoption metrics
        settings_with_usage = ai_usage_data['setting_id'].nunique()
        metrics.settings_adopting = settings_with_usage
        metrics.adoption_rate = settings_with_usage / metrics.total_eligible_settings

        # Adoption by setting type
        for setting_type in setting_data['setting_type'].unique():
            type_settings = setting_data[setting_data['setting_type'] == setting_type]
            type_adopting = len(
                ai_usage_data[
                    ai_usage_data['setting_id'].isin(type_settings['setting_id'])
                ]['setting_id'].unique()
            )
            metrics.adoption_by_setting_type[setting_type] = (
                type_adopting / len(type_settings) if len(type_settings) > 0 else 0
            )

        # Calculate reach metrics
        patients_with_ai = ai_usage_data['patient_id'].nunique()
        metrics.patients_exposed_to_ai = patients_with_ai
        metrics.reach_rate = patients_with_ai / metrics.total_eligible_patients

        # Reach by demographics
        patient_demographics = ['race_ethnicity', 'primary_language', 'insurance_status']
        for demo in patient_demographics:
            if demo in patient_data.columns:
                for category in patient_data[demo].unique():
                    eligible = len(patient_data[patient_data[demo] == category])
                    exposed = len(
                        ai_usage_data[
                            ai_usage_data['patient_id'].isin(
                                patient_data[patient_data[demo] == category]['patient_id']
                            )
                        ]['patient_id'].unique()
                    )
                    metrics.reach_by_demographics[f"{demo}_{category}"] = (
                        exposed / eligible if eligible > 0 else 0
                    )

        # Fidelity metrics
        if 'fidelity_score' in ai_usage_data.columns:
            metrics.intended_use_compliance_rate = ai_usage_data['fidelity_score'].mean()

            for setting_type in setting_data['setting_type'].unique():
                type_settings = setting_data[setting_data['setting_type'] == setting_type]
                type_usage = ai_usage_data[
                    ai_usage_data['setting_id'].isin(type_settings['setting_id'])
                ]
                if len(type_usage) > 0:
                    metrics.fidelity_by_setting_type[setting_type] = type_usage['fidelity_score'].mean()

        # Calculate disparity changes
        if 'outcome' in clinical_outcomes_data.columns:
            baseline_metrics = self._calculate_baseline_disparities(clinical_outcomes_data)
            current_metrics = self._calculate_current_disparities(clinical_outcomes_data)

            for outcome, baseline_disparity in baseline_metrics.items():
                current_disparity = current_metrics.get(outcome, baseline_disparity)
                disparity_change = current_disparity - baseline_disparity
                metrics.disparity_changes[outcome] = disparity_change

                if disparity_change > 0:
                    logger.warning(f"Disparity widened for {outcome}: {disparity_change:.3f}")
                else:
                    logger.info(f"Disparity narrowed for {outcome}: {abs(disparity_change):.3f}")

        self.metrics_history.append(metrics)

        return metrics

    def _calculate_baseline_disparities(
        self,
        outcomes_data: pd.DataFrame
    ) -> Dict[str, float]:
        """Calculate baseline disparities before implementation."""
        disparities = {}

        # Example: racial disparities in outcomes
        if 'race_ethnicity' in outcomes_data.columns and 'outcome' in outcomes_data.columns:
            outcome_by_race = outcomes_data.groupby('race_ethnicity')['outcome'].mean()
            if len(outcome_by_race) > 1:
                disparities['racial_outcome_disparity'] = outcome_by_race.max() - outcome_by_race.min()

        return disparities

    def _calculate_current_disparities(
        self,
        outcomes_data: pd.DataFrame
    ) -> Dict[str, float]:
        """Calculate current disparities during/after implementation."""
        # In production, would use same logic as baseline but for current period
        return self._calculate_baseline_disparities(outcomes_data)

    def generate_implementation_dashboard(
        self,
        metrics: ImplementationMetrics,
        output_dir: Path
    ) -> None:
        """
        Generate comprehensive implementation dashboard with visualizations.

        Parameters
        ----------
        metrics : ImplementationMetrics
            Metrics to visualize
        output_dir : Path
            Directory for output files
        """
        logger.info("Generating implementation evaluation dashboard")

        output_dir.mkdir(parents=True, exist_ok=True)

        # Create figure with subplots
        fig = plt.figure(figsize=(20, 12))

        # Adoption by setting type
        ax1 = plt.subplot(3, 3, 1)
        setting_types = list(metrics.adoption_by_setting_type.keys())
        adoption_rates = list(metrics.adoption_by_setting_type.values())
        ax1.barh(setting_types, adoption_rates)
        ax1.set_xlabel('Adoption Rate')
        ax1.set_title('AI Adoption by Setting Type')
        ax1.set_xlim([0, 1])

        # Add reference line at 80% adoption
        ax1.axvline(x=0.8, color='red', linestyle='--', label='Target (80%)')
        ax1.legend()

        # Reach by demographics
        ax2 = plt.subplot(3, 3, 2)
        demo_categories = list(metrics.reach_by_demographics.keys())
        reach_rates = list(metrics.reach_by_demographics.values())

        # Only show if we have demographic data
        if demo_categories:
            colors = ['green' if r >= 0.7 else 'orange' if r >= 0.5 else 'red' for r in reach_rates]
            ax2.barh(demo_categories, reach_rates, color=colors)
            ax2.set_xlabel('Reach Rate')
            ax2.set_title('AI Reach by Demographics')
            ax2.set_xlim([0, 1])
            ax2.axvline(x=0.7, color='black', linestyle='--', label='Target (70%)')
            ax2.legend()

        # Fidelity by setting type
        ax3 = plt.subplot(3, 3, 3)
        if metrics.fidelity_by_setting_type:
            setting_types_fid = list(metrics.fidelity_by_setting_type.keys())
            fidelity_scores = list(metrics.fidelity_by_setting_type.values())
            colors = ['green' if f >= 0.8 else 'orange' if f >= 0.6 else 'red' for f in fidelity_scores]
            ax3.barh(setting_types_fid, fidelity_scores, color=colors)
            ax3.set_xlabel('Fidelity Score')
            ax3.set_title('Implementation Fidelity by Setting')
            ax3.set_xlim([0, 1])

        # Disparity changes
        ax4 = plt.subplot(3, 3, 4)
        if metrics.disparity_changes:
            outcomes = list(metrics.disparity_changes.keys())
            changes = list(metrics.disparity_changes.values())
            colors = ['green' if c < 0 else 'red' for c in changes]
            ax4.barh(outcomes, changes, color=colors)
            ax4.set_xlabel('Disparity Change (negative = narrowed)')
            ax4.set_title('Changes in Health Disparities')
            ax4.axvline(x=0, color='black', linestyle='-')

        # Overall reach summary
        ax5 = plt.subplot(3, 3, 5)
        reach_data = [
            metrics.total_eligible_patients,
            metrics.patients_exposed_to_ai,
            metrics.total_eligible_patients - metrics.patients_exposed_to_ai
        ]
        labels = ['Eligible', 'Reached', 'Not Reached']
        colors_pie = ['lightblue', 'green', 'red']
        ax5.pie(reach_data, labels=labels, colors=colors_pie, autopct='%1.1f%%')
        ax5.set_title(f'Overall Patient Reach\n(Rate: {metrics.reach_rate:.1%})')

        # Satisfaction scores
        ax6 = plt.subplot(3, 3, 6)
        satisfaction_data = {
            'Clinician': metrics.clinician_satisfaction_score,
            'Patient': metrics.patient_satisfaction_score
        }
        ax6.bar(satisfaction_data.keys(), satisfaction_data.values())
        ax6.set_ylabel('Satisfaction Score (0-100)')
        ax6.set_title('Stakeholder Satisfaction')
        ax6.set_ylim([0, 100])
        ax6.axhline(y=70, color='red', linestyle='--', label='Target (70)')
        ax6.legend()

        plt.tight_layout()
        plt.savefig(output_dir / 'implementation_dashboard.png', dpi=300, bbox_inches='tight')
        plt.close()

        # Generate text report
        self._generate_text_report(metrics, output_dir / 'implementation_report.txt')

        logger.info(f"Dashboard saved to {output_dir}")

    def _generate_text_report(
        self,
        metrics: ImplementationMetrics,
        output_path: Path
    ) -> None:
        """Generate detailed text report of implementation metrics."""
        with open(output_path, 'w') as f:
            f.write("=" * 80 + "\n")
            f.write("IMPLEMENTATION EVALUATION REPORT\n")
            f.write("=" * 80 + "\n\n")

            f.write(f"Measurement Period: {metrics.measurement_start_date.strftime('%Y-%m-%d')} to ")
            f.write(f"{metrics.measurement_end_date.strftime('%Y-%m-%d')}\n\n")

            f.write("-" * 80 + "\n")
            f.write("ADOPTION METRICS\n")
            f.write("-" * 80 + "\n\n")
            f.write(f"Overall Adoption Rate: {metrics.adoption_rate:.1%}\n")
            f.write(f"Settings Adopting: {metrics.settings_adopting} of {metrics.total_eligible_settings}\n\n")

            f.write("Adoption by Setting Type:\n")
            for setting_type, rate in metrics.adoption_by_setting_type.items():
                status = "✓" if rate >= 0.8 else "⚠" if rate >= 0.5 else "✗"
                f.write(f"  {status} {setting_type}: {rate:.1%}\n")
            f.write("\n")

            f.write("-" * 80 + "\n")
            f.write("REACH METRICS\n")
            f.write("-" * 80 + "\n\n")
            f.write(f"Overall Reach Rate: {metrics.reach_rate:.1%}\n")
            f.write(f"Patients Exposed: {metrics.patients_exposed_to_ai:,} of {metrics.total_eligible_patients:,}\n\n")

            f.write("Reach by Demographics:\n")
            for demo, rate in metrics.reach_by_demographics.items():
                status = "✓" if rate >= 0.7 else "⚠" if rate >= 0.5 else "✗"
                f.write(f"  {status} {demo}: {rate:.1%}\n")
            f.write("\n")

            if metrics.reach_by_insurance:
                f.write("Reach by Insurance Status:\n")
                for insurance, rate in metrics.reach_by_insurance.items():
                    status = "✓" if rate >= 0.7 else "⚠" if rate >= 0.5 else "✗"
                    f.write(f"  {status} {insurance}: {rate:.1%}\n")
                f.write("\n")

            f.write("-" * 80 + "\n")
            f.write("FIDELITY METRICS\n")
            f.write("-" * 80 + "\n\n")
            f.write(f"Overall Fidelity: {metrics.intended_use_compliance_rate:.1%}\n\n")

            if metrics.fidelity_by_setting_type:
                f.write("Fidelity by Setting Type:\n")
                for setting_type, fidelity in metrics.fidelity_by_setting_type.items():
                    status = "✓" if fidelity >= 0.8 else "⚠" if fidelity >= 0.6 else "✗"
                    f.write(f"  {status} {setting_type}: {fidelity:.1%}\n")
                f.write("\n")

            f.write("-" * 80 + "\n")
            f.write("EQUITY IMPACT\n")
            f.write("-" * 80 + "\n\n")

            if metrics.disparity_changes:
                f.write("Changes in Health Disparities:\n")
                for outcome, change in metrics.disparity_changes.items():
                    if change < 0:
                        f.write(f"  ✓ {outcome}: Narrowed by {abs(change):.3f}\n")
                    else:
                        f.write(f"  ✗ {outcome}: Widened by {change:.3f}\n")
                f.write("\n")

            f.write("-" * 80 + "\n")
            f.write("SATISFACTION\n")
            f.write("-" * 80 + "\n\n")
            f.write(f"Clinician Satisfaction: {metrics.clinician_satisfaction_score:.1f}/100\n")
            f.write(f"Patient Satisfaction: {metrics.patient_satisfaction_score:.1f}/100\n\n")

            f.write("-" * 80 + "\n")
            f.write("RESOURCE UTILIZATION\n")
            f.write("-" * 80 + "\n\n")
            f.write(f"Total Implementation Costs: ${metrics.implementation_costs:,.2f}\n")
            f.write(f"Ongoing Maintenance Costs: ${metrics.ongoing_maintenance_costs:,.2f}\n")
            f.write(f"Cost per Patient Reached: ${metrics.cost_per_patient_reached:,.2f}\n\n")

            f.write("-" * 80 + "\n")
            f.write("RECOMMENDATIONS\n")
            f.write("-" * 80 + "\n\n")

            # Generate recommendations based on metrics
            if metrics.adoption_rate < 0.8:
                f.write("• Increase adoption support for non-adopting settings\n")

            if metrics.reach_rate < 0.7:
                f.write("• Investigate barriers to patient reach and expand access strategies\n")

            # Check for reach disparities
            if metrics.reach_by_demographics:
                reach_values = list(metrics.reach_by_demographics.values())
                if max(reach_values) - min(reach_values) > 0.2:
                    f.write("• Address significant reach disparities across demographic groups\n")

            if metrics.intended_use_compliance_rate < 0.8:
                f.write("• Improve implementation fidelity through additional training and support\n")

            # Check for widening disparities
            if metrics.disparity_changes:
                widening_disparities = [k for k, v in metrics.disparity_changes.items() if v > 0]
                if widening_disparities:
                    f.write(f"• URGENT: Address widening disparities in: {', '.join(widening_disparities)}\n")

        logger.info(f"Text report saved to {output_path}")