Implementation Guide: Transcribe care coordination calls and generate shared care summaries

speedtest-cli --simple

# Inter-VLAN Firewall Rules:
#    - DENY Guest -> Clinical
#    - DENY Guest -> Management
#    - ALLOW Clinical -> Internet
#    - ALLOW Management -> All

manage-bde -status C:
manage-bde -on C: -RecoveryPassword

fdesetup status
sudo fdesetup enable

SentinelOneInstaller_windows_64bit.exe /SITE_TOKEN=<your_site_token> /quiet
sudo installer -pkg SentinelOne_macos.pkg -target /

pip install openai python-dotenv flask gunicorn cryptography

mkdir care-summary-generator && cd care-summary-generator

cat > .env << 'EOF'
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_ORG_ID=org-your-org-id
FLASK_SECRET_KEY=generate-a-secure-random-key
ALLOWED_ORIGINS=https://your-practice-domain.com
EOF

eb init -p python-3.11 care-summary-generator
eb create care-summary-prod --single --instance-type t3.small
eb setenv OPENAI_API_KEY=sk-xxx

az webapp up --name care-summary-generator --runtime PYTHON:3.11
az webapp config appsettings set --settings OPENAI_API_KEY=sk-xxx

DNS TXT record: v=spf1 include:_spf.paubox.com ~all
DNS CNAME: selector1._domainkey -> provided by Paubox

Subject: Care Coordination Summary - [Patient Initials] - [Date]
Body: [Standardized summary sections from AI generator]
Footer: 'This summary was generated with AI assistance and reviewed
         by [Clinician Name, Credentials]. Please contact [phone/email]
         with questions or corrections.'

# Complete Flask application for generating care coordination summaries

# care_summary_generator.py
# Complete Flask application for generating care coordination summaries

import os
import json
import logging
import hashlib
import datetime
from functools import wraps
from dotenv import load_dotenv
from flask import Flask, request, jsonify
from openai import OpenAI

load_dotenv()

app = Flask(__name__)
app.config['SECRET_KEY'] = os.environ.get('FLASK_SECRET_KEY', 'change-me')

# Configure logging - NEVER log PHI
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('care_summary_generator')

# OpenAI client
client = OpenAI(
    api_key=os.environ.get('OPENAI_API_KEY'),
    organization=os.environ.get('OPENAI_ORG_ID')
)

# API key authentication
API_KEYS = os.environ.get('AUTHORIZED_API_KEYS', '').split(',')

def require_api_key(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        api_key = request.headers.get('X-API-Key')
        if not api_key or api_key not in API_KEYS:
            logger.warning(f'Unauthorized access attempt from {request.remote_addr}')
            return jsonify({'error': 'Unauthorized'}), 401
        return f(*args, **kwargs)
    return decorated

# The core prompt template for care coordination summaries
CARE_COORDINATION_PROMPT = """You are a clinical documentation assistant specializing in care coordination for allied and mental health practices. You will receive a transcript of a care coordination call between healthcare providers discussing a shared patient.

Your task is to generate a structured Care Coordination Summary from this transcript. The summary will be shared with all providers on the patient's treatment team.

IMPORTANT RULES:
1. ONLY include information explicitly stated in the transcript. NEVER infer, assume, or fabricate clinical details.
2. If speaker attribution is unclear, use "[Unidentified Speaker]" rather than guessing.
3. If a medication name, dosage, or clinical detail is unclear in the transcript, flag it as "[VERIFY: unclear in recording]" rather than guessing.
4. Use professional clinical language appropriate for inter-provider communication.
5. Do not include verbatim patient quotes unless clinically relevant.
6. Protect patient privacy: use initials or "the patient" rather than full names in the summary.
7. Flag any safety concerns (suicidal ideation, self-harm, abuse, neglect) prominently at the top of the summary.

Generate the summary using EXACTLY this structure:

---
CARE COORDINATION SUMMARY
Date: [date of call]
Generated: [current date/time] (AI-assisted, pending clinician review)

SAFETY ALERTS:
[List any safety concerns discussed, or state "No safety concerns identified in this call."]

PARTICIPANTS:
- [Name, Credentials, Role] (e.g., "Dr. Jane Smith, PhD, LCSW - Primary Therapist")
- [Name, Credentials, Role]

PATIENT IDENTIFIER: [Patient initials and DOB if mentioned, or other identifier used in the call]

PURPOSE OF CALL:
[1-2 sentence summary of why this coordination call was held]

CLINICAL DISCUSSION SUMMARY:
[3-8 bullet points summarizing key clinical topics discussed, organized by theme]

TREATMENT PLAN UPDATES:
[Bullet points listing any changes to the treatment plan discussed or agreed upon]
[If no changes discussed, state "No treatment plan changes discussed."]

MEDICATION DISCUSSION:
[Any medication changes, concerns, or recommendations discussed]
[If no medication discussion, state "No medication topics discussed."]

ACTION ITEMS:
| # | Action Item | Responsible Party | Due Date |
|---|------------|-------------------|----------|
| 1 | [specific action] | [who] | [when] |
[Include ALL action items mentioned in the call]

FOLLOW-UP PLAN:
- Next coordination call: [date/timeframe if discussed]
- Next steps: [any agreed-upon next steps]

NOTES:
[Any additional context, caveats, or items that don't fit above categories]

---
DISCLAIMER: This summary was generated with AI assistance from an audio recording of the care coordination call. It must be reviewed and approved by a licensed clinician before distribution or entry into the medical record. AI-generated content may contain errors. The reviewing clinician is responsible for verifying accuracy.
---
"""

@app.route('/api/v1/generate-summary', methods=['POST'])
@require_api_key
def generate_summary():
    """Generate a care coordination summary from a transcript."""
    try:
        data = request.get_json()
        
        if not data or 'transcript' not in data:
            return jsonify({'error': 'Missing required field: transcript'}), 400
        
        transcript = data['transcript']
        call_date = data.get('call_date', datetime.date.today().isoformat())
        note_format = data.get('format', 'standard')  # standard, brief, detailed
        
        # Input validation
        if len(transcript) < 50:
            return jsonify({'error': 'Transcript too short to generate meaningful summary'}), 400
        if len(transcript) > 500000:  # ~100k words
            return jsonify({'error': 'Transcript exceeds maximum length'}), 400
        
        # Build the messages
        format_instruction = ''
        if note_format == 'brief':
            format_instruction = '\nGenerate a CONCISE version - limit the Clinical Discussion Summary to 3-4 bullet points and keep the overall summary to one page.'
        elif note_format == 'detailed':
            format_instruction = '\nGenerate a DETAILED version - include comprehensive clinical discussion notes and expand on treatment rationale where discussed.'
        
        messages = [
            {
                'role': 'system',
                'content': CARE_COORDINATION_PROMPT + format_instruction
            },
            {
                'role': 'user',
                'content': f'Call Date: {call_date}\n\nTRANSCRIPT:\n{transcript}'
            }
        ]
        
        # Call OpenAI GPT-5.4
        response = client.chat.completions.create(
            model='gpt-5.4',
            messages=messages,
            temperature=0.2,  # Low temperature for clinical accuracy
            max_tokens=4000,
            top_p=0.95
        )
        
        summary = response.choices[0].message.content
        
        # Log metadata only - NEVER log the transcript or summary (PHI)
        request_hash = hashlib.sha256(transcript[:100].encode()).hexdigest()[:12]
        logger.info(
            f'Summary generated | request_hash={request_hash} | '
            f'transcript_chars={len(transcript)} | '
            f'summary_chars={len(summary)} | '
            f'model={response.model} | '
            f'tokens_used={response.usage.total_tokens}'
        )
        
        return jsonify({
            'summary': summary,
            'metadata': {
                'model': response.model,
                'tokens_used': response.usage.total_tokens,
                'generated_at': datetime.datetime.utcnow().isoformat(),
                'format': note_format,
                'status': 'DRAFT - REQUIRES CLINICIAN REVIEW'
            }
        })
    
    except Exception as e:
        # Log error without PHI
        logger.error(f'Summary generation failed: {type(e).__name__}')
        return jsonify({'error': 'Summary generation failed. Please try again.'}), 500


@app.route('/api/v1/health', methods=['GET'])
def health_check():
    return jsonify({'status': 'healthy', 'timestamp': datetime.datetime.utcnow().isoformat()})


if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)

flask==3.0.3
gunicorn==22.0.0
openai==1.35.0
python-dotenv==1.0.1
cryptography==42.0.8

web: gunicorn care_summary_generator:app --bind 0.0.0.0:$PORT --workers 2 --timeout 120

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY care_summary_generator.py .
EXPOSE 5000
CMD ["gunicorn", "care_summary_generator:app", "--bind", "0.0.0.0:5000", "--workers", "2", "--timeout", "120"]

# paste into the Care Coordination Summary Generator GPT configuration

You are a clinical documentation assistant for an allied and mental health practice. When given a transcript of a care coordination call, you generate a structured Care Coordination Summary.

RULES:
- ONLY include information explicitly stated in the transcript
- NEVER fabricate, infer, or hallucinate clinical details
- If speaker identity is unclear, write "[Unidentified Speaker]"
- If any clinical detail (medication, dosage, diagnosis) is unclear, write "[VERIFY: unclear in recording]"
- Use "the patient" or initials instead of full patient names
- Flag ALL safety concerns (SI, SH, abuse, neglect) at the very top

OUTPUT FORMAT:

CARE COORDINATION SUMMARY
Date: [call date]
Generated: [today's date] (AI-assisted — REQUIRES CLINICIAN REVIEW)

SAFETY ALERTS:
[List any safety concerns, or "No safety concerns identified."]

PARTICIPANTS:
- [Name, Credentials, Role]

PATIENT: [Initials/DOB as mentioned]

PURPOSE: [1-2 sentences]

CLINICAL DISCUSSION:
- [Bullet points of key topics]

TREATMENT PLAN UPDATES:
- [Changes discussed, or "No changes discussed."]

MEDICATION DISCUSSION:
- [Medication topics, or "None discussed."]

ACTION ITEMS:
| # | Action | Responsible | Due Date |
|---|--------|-------------|----------|
| 1 | ... | ... | ... |

FOLLOW-UP:
- Next call: [date/timeframe]
- Next steps: [agreed actions]

DISCLAIMER: AI-generated summary requiring clinician review before distribution or charting.

# End-to-end pipeline processing audio through Deepgram transcription and
# into the Care Coordination Summary Generator API

# transcript_preprocessor.py
# Processes audio files through Deepgram and prepares for summary generation

import os
import json
import requests
from dotenv import load_dotenv

load_dotenv()

DEEPGRAM_API_KEY = os.environ.get('DEEPGRAM_API_KEY')
SUMMARY_API_URL = os.environ.get('SUMMARY_API_URL', 'http://localhost:5000/api/v1/generate-summary')
SUMMARY_API_KEY = os.environ.get('SUMMARY_API_KEY')

def transcribe_audio(audio_file_path: str) -> dict:
    """
    Send audio file to Deepgram Nova-3 Medical for transcription.
    Returns raw Deepgram response with speaker diarization.
    """
    url = 'https://api.deepgram.com/v1/listen'
    
    params = {
        'model': 'nova-3-medical',  # Medical vocabulary model
        'smart_format': 'true',      # Punctuation and formatting
        'diarize': 'true',           # Speaker identification
        'diarize_version': 'latest',
        'punctuate': 'true',
        'paragraphs': 'true',
        'utterances': 'true',
        'language': 'en-US'
    }
    
    headers = {
        'Authorization': f'Token {DEEPGRAM_API_KEY}',
        'Content-Type': 'audio/wav'  # Adjust based on actual format
    }
    
    with open(audio_file_path, 'rb') as audio_file:
        response = requests.post(url, params=params, headers=headers, data=audio_file)
    
    response.raise_for_status()
    return response.json()


def format_transcript_with_speakers(deepgram_response: dict) -> str:
    """
    Convert Deepgram response into a readable transcript with speaker labels.
    """
    utterances = deepgram_response.get('results', {}).get('utterances', [])
    
    if not utterances:
        # Fallback to paragraphs if utterances not available
        paragraphs = deepgram_response.get('results', {}).get('channels', [{}])[0].get('alternatives', [{}])[0].get('paragraphs', {}).get('paragraphs', [])
        formatted_lines = []
        for para in paragraphs:
            speaker = para.get('speaker', 'Unknown')
            sentences = ' '.join([s.get('text', '') for s in para.get('sentences', [])])
            formatted_lines.append(f'Speaker {speaker}: {sentences}')
        return '\n\n'.join(formatted_lines)
    
    formatted_lines = []
    current_speaker = None
    current_text = []
    
    for utterance in utterances:
        speaker = f"Speaker {utterance.get('speaker', 'Unknown')}"
        text = utterance.get('transcript', '')
        
        if speaker != current_speaker:
            if current_speaker and current_text:
                formatted_lines.append(f'{current_speaker}: {" ".join(current_text)}')
            current_speaker = speaker
            current_text = [text]
        else:
            current_text.append(text)
    
    # Don't forget the last speaker
    if current_speaker and current_text:
        formatted_lines.append(f'{current_speaker}: {" ".join(current_text)}')
    
    return '\n\n'.join(formatted_lines)


def generate_summary(transcript: str, call_date: str, note_format: str = 'standard') -> dict:
    """
    Send formatted transcript to the Care Coordination Summary Generator API.
    """
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': SUMMARY_API_KEY
    }
    
    payload = {
        'transcript': transcript,
        'call_date': call_date,
        'format': note_format
    }
    
    response = requests.post(SUMMARY_API_URL, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()


def process_care_coordination_call(audio_file_path: str, call_date: str, note_format: str = 'standard') -> dict:
    """
    End-to-end pipeline: audio -> transcription -> formatted transcript -> care summary.
    """
    # Step 1: Transcribe with Deepgram
    print(f'Transcribing {audio_file_path}...')
    deepgram_result = transcribe_audio(audio_file_path)
    
    # Step 2: Format with speaker labels
    print('Formatting transcript with speaker labels...')
    formatted_transcript = format_transcript_with_speakers(deepgram_result)
    
    # Step 3: Generate summary
    print('Generating care coordination summary...')
    summary_result = generate_summary(formatted_transcript, call_date, note_format)
    
    return {
        'transcript': formatted_transcript,
        'summary': summary_result.get('summary'),
        'metadata': summary_result.get('metadata')
    }


if __name__ == '__main__':
    import sys
    if len(sys.argv) < 3:
        print('Usage: python transcript_preprocessor.py <audio_file> <call_date YYYY-MM-DD>')
        sys.exit(1)
    
    result = process_care_coordination_call(sys.argv[1], sys.argv[2])
    print('\n=== FORMATTED TRANSCRIPT ===\n')
    print(result['transcript'])
    print('\n=== CARE COORDINATION SUMMARY ===\n')
    print(result['summary'])

# AI-ASSISTED RECORDING AND DOCUMENTATION CONSENT FORM
# Template for Allied & Mental Health Practices
# MUST BE REVIEWED BY PRACTICE'S LEGAL COUNSEL BEFORE USE

---

## CONSENT FOR AI-ASSISTED AMBIENT RECORDING AND DOCUMENTATION

**Practice Name:** [Practice Name]
**Date:** _______________
**Patient Name:** _______________
**Date of Birth:** _______________

### PURPOSE
Our practice uses AI-assisted technology to record and transcribe clinical conversations, including care coordination calls between your treatment providers. This technology helps us create accurate, timely documentation and care coordination summaries to improve the quality and continuity of your care.

### WHAT THIS MEANS
- **Recording:** Audio from your clinical sessions and/or care coordination calls involving your care may be recorded using a microphone in the treatment room or on a phone/video call.
- **Transcription:** The audio recording is processed by an AI (artificial intelligence) system to create a written transcript of the conversation.
- **Documentation:** The AI system generates draft clinical notes and/or care coordination summaries based on the transcript.
- **Human Review:** ALL AI-generated documents are reviewed, edited, and approved by your licensed healthcare provider before being finalized, shared, or entered into your medical record.
- **Audio Handling:** Audio recordings are processed by [Vendor Name], our HIPAA-compliant technology partner. [Audio is automatically deleted after processing / Audio is retained for X days before automatic deletion — customize based on vendor policy].

### HOW YOUR INFORMATION IS PROTECTED
- All audio and text data are encrypted during transmission and storage.
- Our technology vendor has signed a Business Associate Agreement (BAA) as required by HIPAA.
- Audio recordings are NOT used to train AI models and are NOT shared with third parties beyond what is necessary for processing.
- Your information is protected by federal (HIPAA) and state privacy laws.
- [FOR SUD PRACTICES: Your substance use disorder treatment information is additionally protected under 42 CFR Part 2, which provides heightened confidentiality protections. This AI recording consent is separate from and in addition to your Part 2 consent for disclosure.]

### YOUR RIGHTS
- **You may decline this recording at any time** without any impact on the quality or availability of your care.
- If you decline, your provider will document your sessions manually, as was done before this technology was available.
- You may withdraw this consent at any time by notifying your provider or our front office staff.
- You may request information about what AI-generated documentation has been created from your recorded sessions.
- [CALIFORNIA: As required by California AB 3030, you may contact a human healthcare provider at any time regarding any AI-generated communication or documentation by calling [practice phone number] or emailing [practice email].]

### LIMITATIONS OF AI TECHNOLOGY
- AI-generated transcripts and summaries may contain errors. Your provider reviews all output for accuracy.
- The AI system may occasionally miss or misinterpret spoken words, particularly medical terminology, accents, or overlapping speech.
- AI-generated documentation is a tool to assist — not replace — your provider's clinical judgment.

### CONSENT

By signing below, I acknowledge that:

- [ ] I have read and understand this consent form.
- [ ] I understand that my clinical sessions and/or care coordination calls may be recorded and processed by AI technology.
- [ ] I understand that all AI-generated documentation will be reviewed by a licensed clinician before use.
- [ ] I understand that I may decline or withdraw consent at any time without impact on my care.
- [ ] I have had the opportunity to ask questions about this technology and its use.

**Patient Signature:** _______________  **Date:** _______________

**Provider Signature:** _______________  **Date:** _______________

**Witness (if required by state law):** _______________  **Date:** _______________

---

**Consent Declined:**
- [ ] Patient declines AI recording consent. Manual documentation will be used.

**Patient Signature:** _______________  **Date:** _______________

---

*This consent is valid for 12 months from the date of signature and will be renewed annually or when there are material changes to the technology or vendor used.*

*Form Version: 1.0 | Last Updated: [Date] | Next Review: [Date + 12 months]*

// Drag this to your bookmarks bar. Select care summary text on the page
// first, then click the bookmark to format and copy to clipboard.

javascript:(function(){
  var text = window.getSelection().toString();
  if(!text){alert('Select the care summary text first, then click this bookmark.');return;}
  // Clean up formatting for EHR plain-text fields
  text = text.replace(/\|/g, ' ').replace(/---/g, '').replace(/\n{3,}/g, '\n\n');
  // Add EHR-friendly header
  var formatted = 'CARE COORDINATION NOTE\n';
  formatted += 'Date: ' + new Date().toLocaleDateString() + '\n';
  formatted += 'Type: Care Coordination Call Summary (AI-Assisted)\n';
  formatted += '---\n' + text;
  formatted += '\n---\nReviewed and approved by: [Provider Name, Credentials]';
  // Copy to clipboard
  navigator.clipboard.writeText(formatted).then(function(){
    alert('Formatted summary copied to clipboard. Paste into your EHR.');
  });
})()

# Requires Healthie Enterprise plan with API access.

# healthie_integration.py
# Push care coordination summaries directly to Healthie via GraphQL API

import requests
import os

HEALTHIE_API_URL = 'https://api.gethealthie.com/graphql'
HEALTHIE_API_KEY = os.environ.get('HEALTHIE_API_KEY')

def create_care_coordination_note(patient_id: str, summary: str, call_date: str, provider_id: str) -> dict:
    """
    Create a new chart note in Healthie with the care coordination summary.
    Requires Healthie Enterprise plan with API access.
    """
    mutation = '''
    mutation createFormAnswerGroup($input: createFormAnswerGroupInput!) {
      createFormAnswerGroup(input: $input) {
        form_answer_group {
          id
          created_at
        }
        messages {
          field
          message
        }
      }
    }
    '''
    
    # Note: Actual Healthie GraphQL schema may vary.
    # Consult Healthie API docs for exact mutation structure.
    # This is a representative example.
    variables = {
        'input': {
            'user_id': patient_id,
            'form_id': 'care_coordination_form_id',  # Pre-configured form template ID
            'form_answers': [
                {
                    'custom_module_id': 'summary_field_id',
                    'answer': summary
                },
                {
                    'custom_module_id': 'call_date_field_id', 
                    'answer': call_date
                }
            ],
            'finished': True
        }
    }
    
    headers = {
        'Authorization': f'Basic {HEALTHIE_API_KEY}',
        'Content-Type': 'application/json',
        'AuthorizationSource': 'API'
    }
    
    response = requests.post(
        HEALTHIE_API_URL,
        json={'query': mutation, 'variables': variables},
        headers=headers
    )
    
    return response.json()