Automated Soap Note Generator

Automated SOAP Note Generator

Overview

AI-powered clinical documentation tool that converts unstructured clinical input into professionally formatted SOAP notes compliant with medical documentation standards.

Key Capabilities:

• Intelligent Parsing: Extracts structured information from free-text clinical narratives
• SOAP Classification: Automatically categorizes content into Subjective, Objective, Assessment, Plan sections
• Medical Entity Recognition: Identifies symptoms, diagnoses, medications, procedures, and anatomical locations
• Temporal Analysis: Extracts timeline information (onset, duration, progression)
• Template Generation: Produces standardized SOAP format suitable for EHR integration
• Multi-modal Input: Accepts text dictation, transcripts, or clinical notes

When to Use

✅ Use this skill when:

• Converting physician dictation into structured SOAP format for efficiency
• Processing audio-to-text transcripts from patient encounters
• Transforming consultation rough notes into formal documentation
• Generating initial draft documentation to reduce administrative burden
• Standardizing clinical encounter summaries for consistency
• Creating preliminary notes for routine follow-up visits

❌ Do NOT use when:

• Input contains PHI that hasn't been de-identified for testing/training
• Complex psychiatric cases requiring nuanced mental status documentation → Use specialized psychiatric documentation tools
• Surgical procedures requiring operative report detail → Use operative-report-generator
• Patient requires nuanced clinical reasoning beyond text extraction
• Legal or forensic documentation requiring exact transcription → Use verbatim transcription services
• Critical care situations requiring real-time precise documentation
• Cases requiring differential diagnosis prioritization without physician input

⚠️ ALWAYS Required:

• Physician review and approval before entering into patient record
• Verification of medical facts and clinical accuracy
• Confirmation of medication names, dosages, and instructions

Integration with Other Skills

Upstream Skills:

• medical-scribe-dictation: Convert physician verbal dictation to text input
• ehr-semantic-compressor: Summarize lengthy EHR notes for SOAP generation
• dicom-anonymizer: Prepare imaging reports for SOAP inclusion
• audio-script-writer: Convert audio recordings to text format

Downstream Skills:

• medical-email-polisher: Professional communication of SOAP summaries to patients
• clinical-data-cleaner: Standardize extracted data for research databases
• hipaa-compliance-auditor: Verify de-identification before sharing documentation
• discharge-summary-writer: Generate discharge summaries from SOAP encounters
• referral-letter-generator: Create referral letters based on Assessment and Plan sections

Complete Workflow:

Medical Scribe Dictation (audio→text) → 
  Automated SOAP Note Generator (this skill) → 
    Physician Review → 
      EHR Entry / 
      Medical Email Polisher (patient communication) / 
      Referral Letter Generator (referrals)

Core Capabilities

1. Input Processing and Preprocessing

Handle various input formats and prepare for NLP analysis:

from scripts.soap_generator import SOAPNoteGenerator

generator = SOAPNoteGenerator()

# Process text input
soap_note = generator.generate(
    input_text="Patient presents with 2-day history of chest pain, radiating to left arm...",
    patient_id="P12345",
    encounter_date="2026-01-15",
    provider="Dr. Smith"
)

# Process from audio transcript
soap_note = generator.generate_from_transcript(
    transcript_path="consultation_transcript.txt",
    patient_id="P12345"
)

Input Preprocessing Steps:

1. Text Cleaning: Remove filler words ("um", "uh"), timestamps, speaker labels
2. Sentence Segmentation: Split into clinically meaningful segments
3. Normalization: Standardize abbreviations and medical shorthand
4. Encoding Detection: Handle various file formats (UTF-8, ASCII, etc.)

Parameters:

*Either input_text or transcript_path required

Best Practices:

• Always verify input text quality (clear audio → better transcription → better SOAP)
• Remove patient identifiers before processing unless in secure environment
• Split long encounters (>30 minutes) into logical segments
• Flag ambiguous abbreviations for manual review

2. Medical Named Entity Recognition (NER)

Identify and extract medical concepts from unstructured text:

# Extract entities with context
entities = generator.extract_medical_entities(
    "Patient has history of hypertension and diabetes, 
     currently taking lisinopril 10mg daily and metformin 500mg BID"
)

# Returns structured entities:
# {
#   "diagnoses": ["hypertension", "diabetes mellitus"],
#   "medications": [
#     {"name": "lisinopril", "dose": "10mg", "frequency": "daily"},
#     {"name": "metformin", "dose": "500mg", "frequency": "BID"}
#   ]
# }

Entity Types Recognized:

Common Issues and Solutions:

Issue: Missed medications

• Symptom: Generic names not recognized (e.g., "water pill" for diuretic)
• Solution: Manual review required; tool flags colloquial terms for verification

Issue: Ambiguous abbreviations

• Symptom: "SOB" could be shortness of breath or something else
• Solution: Context-aware disambiguation; flag uncertain cases

Issue: Misspelled drug names

• Symptom: "metfomin" instead of "metformin"
• Solution: Fuzzy matching with confidence threshold; flag low-confidence matches

3. SOAP Section Classification

Automatically categorize sentences into appropriate SOAP sections:

# Classify content into SOAP sections
classified = generator.classify_soap_sections(
    "Patient reports chest pain for 2 days. Physical exam shows BP 140/90. 
     Likely angina. Schedule stress test and start aspirin 81mg daily."
)

# Output structure:
# {
#   "Subjective": ["Patient reports chest pain for 2 days"],
#   "Objective": ["Physical exam shows BP 140/90"],
#   "Assessment": ["Likely angina"],
#   "Plan": ["Schedule stress test", "start aspirin 81mg daily"]
# }

Classification Rules:

Multi-label Handling: Some sentences span multiple sections (e.g., "Patient reports chest pain [S], which was sharp and 8/10 [S], with ECG showing ST elevation [O]")

• Tool splits compound sentences at conjunctions
• Assigns primary and secondary labels with confidence scores

Best Practices:

• Review classification accuracy, especially for complex multi-part statements
• Manually verify Assessment section (most critical for patient care)
• Ensure temporal context preserved (recent vs. chronic symptoms)

4. Temporal Information Extraction

Parse and normalize timeline information:

# Extract temporal relationships
timeline = generator.extract_temporal_info(
    "Patient had chest pain starting 3 days ago, worsening since yesterday. 
     Had similar episode 2 months ago that resolved with rest."
)

# Returns:
# {
#   "onset": "3 days ago",
#   "progression": "worsening",
#   "previous_episodes": [
#     {"time": "2 months ago", "resolution": "with rest"}
#   ]
# }

Temporal Elements Extracted:

• Onset: When symptoms started ("2 days ago", "this morning")
• Duration: How long symptoms lasted ("for 3 hours", "ongoing")
• Frequency: How often symptoms occur ("daily", "intermittently")
• Progression: Getting better/worse/stable
• Prior Episodes: Previous similar events
• Context: "before meals", "with exertion", "at night"

Normalization: Converts relative dates to standardized format:

• "yesterday" → Encounter date minus 1 day
• "3 days ago" → Specific date calculated
• "chronic" → Flagged for chronic condition tracking

5. Negation and Uncertainty Detection

Critical for accurate medical documentation:

# Detect negations and uncertainties
analysis = generator.analyze_certainty(
    "Patient denies chest pain. No shortness of breath. 
     Possibly had fever yesterday but not sure."
)

# Identifies:
# - "denies chest pain" → Negative finding (important!)
# - "No shortness of breath" → Negative finding
# - "Possibly had fever" → Uncertain finding (flag for verification)

Detection Categories:

⚠️ Critical: Negation errors are high-risk (e.g., missing "denies" → documenting symptom they don't have)

• Always verify negative findings in Subjective section
• Uncertain findings must be explicitly marked for review

6. Structured SOAP Generation

Produce final formatted output:

# Generate complete SOAP note
soap_output = generator.generate_soap_document(
    structured_data=classified,
    format="markdown",  # Options: markdown, json, hl7, text
    include_metadata=True
)

Output Format:

# SOAP Note

**Patient ID:** P12345  
**Date:** 2026-01-15  
**Provider:** Dr. Smith

## Subjective
Patient reports [extracted symptoms with duration]. History of [chronic conditions]. 
Currently taking [medications]. Patient denies [negative findings].

## Objective
**Vital Signs:** [BP, HR, RR, Temp, O2Sat]  
**Physical Examination:** [Exam findings by system]  
**Laboratory/Data:** [Relevant results]

## Assessment
[Primary diagnosis/differential]  
[Clinical reasoning summary]

## Plan
1. [Action item 1]
2. [Action item 2]
3. [Follow-up instructions]

---
*Generated by AI. REQUIRES PHYSICIAN REVIEW before entry into patient record.*

Export Formats:

Complete Workflow Example

From audio dictation to reviewed SOAP note:

# Step 1: Process audio to text (using medical-scribe-dictation or external)
# Assuming you have transcript: consultation.txt

# Step 2: Generate SOAP note
python scripts/main.py \
  --input-file consultation.txt \
  --patient-id P12345 \
  --provider "Dr. Smith" \
  --specialty "cardiology" \
  --output soap_draft.md \
  --format markdown

# Step 3: Review output
# - Open soap_draft.md
# - Verify medical accuracy
# - Correct any errors
# - Add missing clinical reasoning

# Step 4: Finalize (after physician approval)
# - Copy approved content to EHR
# - Or use for patient communication

Python API Usage:

from scripts.soap_generator import SOAPNoteGenerator
from scripts.post_processor import ReviewFormatter

# Initialize
generator = SOAPNoteGenerator()
reviewer = ReviewFormatter()

# Generate draft
with open("dictation.txt", "r") as f:
    raw_text = f.read()

draft = generator.generate(
    input_text=raw_text,
    patient_id="P12345",
    encounter_date="2026-01-15",
    provider="Dr. Smith",
    specialty="internal_medicine"
)

# Add physician review markers
marked_draft = reviewer.add_review_markers(draft)

# Save with warning header
reviewer.save_with_disclaimer(
    marked_draft, 
    output_path="soap_draft_review.md",
    disclaimer="REQUIRES PHYSICIAN REVIEW - NOT FOR DIRECT ENTRY"
)

Expected Output Files:

output/
├── soap_draft.md              # Generated SOAP note
├── entities_extracted.json     # Structured medical entities
├── classification_report.txt   # Confidence scores for each section
└── review_checklist.md         # Items requiring manual verification

Quality Checklist

Pre-generation Checks:

• Input text is legible (not garbled transcription)
• Audio quality was sufficient (if from dictation)
• Patient identifiers handled per HIPAA guidelines
• No obvious transcription errors (medication names make sense)

During Generation:

• All medications recognized and dosages extracted
• Temporal information correctly normalized
• Negations properly detected (denies = negative finding)
• Uncertain statements flagged for review
• SOAP sections logically organized

Post-generation Review (PHYSICIAN MUST CHECK):

• CRITICAL: Medical facts are accurate
• CRITICAL: Medication names, dosages, and frequencies correct
• CRITICAL: Assessment section reflects clinical reasoning
• Allergies correctly documented
• Vital signs accurately transcribed
• Physical exam findings complete
• Plan includes all necessary actions
• Follow-up instructions clear and appropriate
• No fabricated information (hallucinations)

Before EHR Entry:

• Physician has reviewed and approved
• Corrections made as needed
• Signed/attested by responsible provider
• Metadata complete (date, provider, encounter type)

Common Pitfalls

Input Quality Issues:

• ❌ Poor audio quality (background noise, mumbling) → Garbled transcription → Inaccurate SOAP

  • ✅ Ensure quiet environment for dictation; use high-quality microphone

• ❌ Incomplete dictation (provider trails off, changes subject) → Missing information

  • ✅ Dictate in complete sentences; pause between distinct thoughts

• ❌ Heavy accents or fast speech → Transcription errors

  • ✅ Speak clearly; review transcription immediately if possible

Medical Accuracy Issues:

• ❌ Medication name confusion ("Lipitor" vs "lipid lowerer") → Wrong drug documented

  • ✅ Always verify medication names; use generic names when possible

• ❌ Missed negations ("denies chest pain" → "has chest pain") → Critical error

  • ✅ Carefully review Subjective section for negative findings

• ❌ Temporal confusion ("pain since yesterday" vs "pain until yesterday") → Wrong timeline

  • ✅ Verify onset, duration, and progression with patient

• ❌ Uncertain findings documented as certain ("possibly pneumonia" → "pneumonia")

  • ✅ Flag all uncertain language for clarification

Documentation Issues:

• ❌ Hallucinated information (AI adds details not in input) → False documentation

  • ✅ Compare output directly with source material

• ❌ Missing context ("continue meds" without specifying which ones)

  • ✅ Ensure plan is specific and actionable

• ❌ Generic assessments ("patient is stable" without specifics)

  • ✅ Add clinical reasoning to Assessment section

Compliance Issues:

• ❌ Entering AI-generated text without review → Legal/medical liability

  • ✅ NEVER enter into patient record without physician approval

• ❌ Including PHI in unsecured processing → HIPAA violation

  • ✅ Use only in HIPAA-compliant environments

Process Issues:

• ❌ Not saving original input → Cannot verify if questions arise

  • ✅ Retain original dictation/transcript

• ❌ No audit trail → Cannot track AI involvement

  • ✅ Document that SOAP was AI-assisted in metadata