12. Patient Communication

Patient-facing communication presents specific challenges: tone must be appropriate for health literacy levels, medical terminology requires explanation, and emotional content needs careful handling. Local AI enables consistent patient communication without PHI leaving the organization.

Use cases include draft responses to patient portal messages, educational materials at appropriate reading levels, and appointment preparation instructions.

# patient_communication.py
from dataclasses import dataclass
from typing import Optional
import re

@dataclass
class PatientMessage:
    recipient_name: str
    recipient_age: Optional[int]
    health_literacy_level: str  # basic, intermediate, advanced
    message_content: str
    context: str  # appointment prep, follow-up, education, etc.

class PatientCommunicationDraft:
    """Draft patient-facing communications using local LLM."""
    
    def __init__(self, ollama_client):
        self.ollama = ollama_client
        
    def draft_response(self, incoming_message: str,
                       context: dict,
                       response_type: str = "portal_message") -> str:
        """Draft response to patient message."""
        
        tone_guidance = self._get_tone_guidance(context.get("urgency"))
        literacy_adjustment = self._get_literacy_instruction(
            context.get("health_literacy", "intermediate")
        )
        
        prompt = f"""Draft a response to this patient message.
        
        Patient message:
        {incoming_message}
        
        Clinical context:
        {context.get('clinical_context', 'Not provided')}
        
        Provider information: {context.get('provider_name', 'Dr. [Name]')}
        
        Tone: {tone_guidance}
        {literacy_adjustment}
        
        Response type: {response_type}
        - Include appropriate greeting and sign-off
        - Address patient concerns directly
        - Include clear next steps if applicable
        - Flag any urgent concerns that require phone contact"""
        
        response = self.ollama.generate(prompt)
        return self._clean_response(response)
    
    def generate_education_material(self, topic: str,
                                    literacy_level: str) -> str:
        """Generate patient education material at specified reading level."""
        
        reading_instruction = {
            "basic": "Use 5th grade reading level. Short sentences. Everyday words. Avoid medical jargon or explain when necessary.",
            "intermediate": "Use 8th grade reading level. Clear explanations of medical concepts. Define specialized terms.",
            "advanced": "Use appropriate medical terminology. Detailed explanations. Include nuances."
        }.get(literacy_level, "Use intermediate reading level.")
        
        prompt = f"""Generate patient education material about: {topic}
        
        {reading_instruction}
        
        Include:
        - Overview of the condition/topic
        - Key points the patient should understand
        - Warning signs that require medical attention
        - Common questions patients ask
        
        Format for easy reading: short paragraphs, bullet points for key facts, clear headings."""
        
        response = self.ollama.generate(prompt)
        return self._clean_response(response)
    
    def draft_pre_appointment_instructions(self, appointment_type: str,
                                            patient_info: dict) -> str:
        """Draft appointment preparation instructions."""
        
        prompt = f"""Draft preparation instructions for a {appointment_type}.
        
        Patient: {patient_info.get('name')}
        Provider: {patient_info.get('provider')}
        Date/Time: {patient_info.get('datetime')}
        
        Include:
        - What to bring (ID, insurance card, referral, etc.)
        - How to prepare (fasting, medications, etc.)
        - What to expect during the visit
        - How long the appointment typically takes
        - Any questions they should prepare
        
        Use clear, simple language. Provide specific times and requirements."""
        
        response = self.ollama.generate(prompt)
        return self._clean_response(response)
    
    def translate_medical_to_plain(self, medical_text: str,
                                    target_level: str = "basic") -> str:
        """Convert medical text to plain language."""
        
        prompt = f"""Translate this medical text into plain language.
        Target reading level: {target_level}
        
        Medical text:
        {medical_text}
        
        Provide:
        1. Plain language version
        2. Brief explanation of any medical terms used
        3. Key takeaway message"""
        
        response = self.ollama.generate(prompt)
        return self._clean_response(response)
    
    def _get_tone_guidance(self, urgency: str) -> str:
        return {
            "routine": "Warm, professional, reassuring. Answer questions thoroughly.",
            "urgent": "Clear, direct, emphasize need for prompt action.",
            "critical": "Compassionate but clear about seriousness. Emphasize immediate actions."
        }.get(urgency, "Professional and helpful.")
    
    def _get_literacy_instruction(self, level: str) -> str:
        return {
            "basic": "Use simple words, short sentences. Avoid all medical jargon or explain any terms used.",
            "intermediate": "Use common medical terms but explain them. Moderate sentence length.",
            "advanced": "Standard medical terminology acceptable. Full explanations."
        }.get(level, "Use intermediate level.")
    
    def _clean_response(self, response: str) -> str:
        """Clean response of any formatting artifacts."""
        # Remove any meta-commentary the model might include
        response = re.sub(r'^Here\'s?.*?:?\s*', '', response, flags=re.IGNORECASE)
        response = response.strip()
        return response

Patient communication introduces medicolegal risk that differs from internal use. Patients may act on AI-generated content without clinician review. Minimize this risk by clearly marking draft communications as "draft - review by care team" and requiring clinician approval before sending.