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:

When to Use

✅ Use this skill when:

❌ Do NOT use when:

⚠️ ALWAYS Required:

Integration with Other Skills

Upstream Skills:

Downstream Skills:

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: | Parameter | Type | Required | Description | Default | |-----------|------|----------|-------------|---------| | input_text | str | Yes* | Raw clinical text or dictation | None | | transcript_path | str | Yes* | Path to transcript file | None | | patient_id | str | No | Patient identifier (MUST be de-identified for testing) | None | | encounter_date | str | No | Date in ISO 8601 format (YYYY-MM-DD) | Current date | | provider | str | No | Healthcare provider name | None | | specialty | str | No | Medical specialty context | "general" | | verbose | bool | No | Include confidence scores | False |

*Either input_text or transcript_path required

Best Practices:

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: | Category | Examples | Notes | |----------|----------|-------| | Diagnoses | diabetes, hypertension, pneumonia | ICD-10 compatible where possible | | Symptoms | chest pain, headache, nausea | Includes severity modifiers | | Medications | metformin, lisinopril, aspirin | Extracts dose, route, frequency | | Procedures | ECG, CT scan, blood draw | Includes body site | | Anatomy | left arm, chest, abdomen | Laterality and location | | Lab Values | glucose 120, BP 140/90 | Units and reference ranges | | Temporal | yesterday, 3 days ago, chronic | Normalized to relative dates |

Common Issues and Solutions:

Issue: Missed medications

Issue: Ambiguous abbreviations

Issue: Misspelled drug names

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: | Section | Content Type | Examples | |---------|--------------|----------| | S - Subjective | Patient-reported information | "Patient states...", "Patient reports...", "Complains of..." | | O - Objective | Observable/measurable findings | Vital signs, physical exam, lab results, imaging | | A - Assessment | Clinical interpretation | Diagnosis, differential, clinical impression | | P - Plan | Actions to be taken | Medications, procedures, follow-up, patient education |

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]")

Best Practices:

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:

Normalization: Converts relative dates to standardized format:

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: | Type | Cues | Action | |------|------|--------| | Negation | denies, no, without, absent | Mark as negative finding | | Uncertainty | possibly, maybe, uncertain, ? | Flag for physician review | | Hypothetical | if, would, could | Note as conditional | | Family History | family history of, mother had | Separate from patient findings |

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

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: | Format | Use Case | Notes | |--------|----------|-------| | Markdown | Human review, documentation | Default, readable | | JSON | System integration, research | Structured data | | HL7 FHIR | EHR integration | Healthcare standard | | Plain Text | Simple documentation | Minimal formatting | | CSV | Data analysis, research | Tabular data export |

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:

During Generation:

Post-generation Review (PHYSICIAN MUST CHECK):

Before EHR Entry:

Common Pitfalls

Input Quality Issues:

Medical Accuracy Issues:

Documentation Issues:

Compliance Issues:

Process Issues:

Troubleshooting

Problem: Poor entity recognition

Problem: Wrong SOAP classification

Problem: Missing temporal information

Problem: Inappropriate certainty level

Problem: Formatting errors in output

Problem: Processing fails or hangs

References

Available in references/ directory:

Scripts

Located in scripts/ directory:

Performance and Resources

Typical Processing Time:

System Requirements:

Supported Input Sizes:

Limitations

Regulatory and Legal Notes

Version History

Parameters

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | --input, -i | string | - | No | Input clinical text directly | | --input-file, -f | string | - | No | Path to input text file | | --output, -o | string | - | No | Output file path | | --patient-id, -p | string | - | No | Patient identifier | | --provider | string | - | No | Healthcare provider name | | --format | string | markdown | No | Output format (markdown, json) |

Usage

Basic Usage

# Generate SOAP from text
python scripts/main.py --input "Patient reports chest pain..." --output note.md
From file
python scripts/main.py --input-file consultation.txt --patient-id P12345 --provider "Dr. Smith"
JSON output
python scripts/main.py --input-file notes.txt --format json --output note.json

Risk Assessment

| Risk Indicator | Assessment | Level | |----------------|------------|-------| | Code Execution | Python script executed locally | Medium | | Network Access | No external API calls | Low | | File System Access | Read input files, write output files | Low | | Data Exposure | May process PHI (Protected Health Information) | High | | HIPAA Compliance | Must be used in compliant environment | High |

Security Checklist

Prerequisites

# Python 3.7+
No external packages required (uses standard library)

Evaluation Criteria

Success Metrics

Test Cases

Lifecycle Status

⚠️ CRITICAL REMINDER: All AI-generated SOAP notes REQUIRE physician review and approval before entry into patient records. This tool assists documentation but does not replace clinical judgment or medical decision-making.

Basic Usage

# Generate SOAP from text
python scripts/main.py --input "Patient reports chest pain..." --output note.md
From file
python scripts/main.py --input-file consultation.txt --patient-id P12345 --provider "Dr. Smith"
JSON output
python scripts/main.py --input-file notes.txt --format json --output note.json

# Python 3.7+
No external packages required (uses standard library)

Problem: Poor entity recognition

Problem: Wrong SOAP classification

Problem: Missing temporal information

Problem: Inappropriate certainty level

Problem: Formatting errors in output

Problem: Processing fails or hangs