parsemedicalexams

🏥 Extract and summarize medical exam reports from PDFs using Vision AI 📄

Features · Quick Start · Configuration · Output Format

Features

• Vision-powered extraction — Uses Vision LLMs to read X-rays, MRIs, ultrasounds, endoscopies, and more directly from PDF scans
• Self-consistency voting — Runs multiple extractions and votes on the best result for maximum reliability
• Intelligent classification — Automatically categorizes exams (imaging, ultrasound, endoscopy, other) and standardizes naming
• Clinical summarization — Preserves all findings, impressions, and recommendations while filtering noise
• Markdown output with YAML frontmatter — Clean, structured files ready for Obsidian, static sites, or further processing
• Smart caching — Persistent JSON caches avoid redundant API calls and allow manual overrides
• Multi-era document handling — Frequency-based date voting correctly handles documents spanning multiple time periods

Quick Start

1. Install

pip install -e .

Requires Poppler for PDF processing:

• macOS: brew install poppler
• Ubuntu: apt-get install poppler-utils

2. Configure

cp .env.example .env

Edit .env with your settings:

OPENROUTER_API_KEY=your_api_key_here
INPUT_PATH=/path/to/your/exam/pdfs
OUTPUT_PATH=/path/to/output

3. Run

python main.py

How It Works

┌─────────────┐    ┌─────────────────┐    ┌────────────────┐    ┌──────────────┐    ┌────────────┐
│  PDF Input  │───▶│  Preprocessing  │───▶│ Vision LLM ×N  │───▶│ Standardize  │───▶│  Markdown  │
│             │    │  (grayscale,    │    │  + voting      │    │  + classify  │    │   Output   │
│             │    │   resize)       │    │                │    │              │    │            │
└─────────────┘    └─────────────────┘    └────────────────┘    └──────────────┘    └────────────┘

1. PDF → Images — Converts each page to grayscale, resizes, and enhances contrast
2. Document classification — Determines if the document is a medical exam before processing
3. Vision LLM transcription — Transcribes each page verbatim using function calling (runs N times for reliability)
4. Self-consistency voting — If transcriptions differ, LLM votes on the best result
5. Standardization — Classifies exam type and standardizes the name via LLM with caching
6. Summarization — Generates document-level clinical summaries preserving all findings

Configuration

Environment Variables

Using Profiles

Profiles let you save different input/output configurations for different use cases:

# Create a profile from template
cp profiles/_template.yaml profiles/myprofile.yaml

# Run with profile
python main.py --profile myprofile

# List available profiles
python main.py --list-profiles

Profile files (YAML or JSON) support path overrides and model configuration:

name: myprofile
input_path: /path/to/input
output_path: /path/to/output
input_file_regex: ".*\\.pdf"
model: google/gemini-2.5-flash  # Optional override
workers: 1                       # Optional override

CLI Options

Examples:

# Process all new PDFs
python main.py --profile tsilva

# Regenerate summaries from existing transcription files
python main.py --profile tsilva --regenerate

# Force reprocess all documents
python main.py --profile tsilva --reprocess-all

# Reprocess a specific document
python main.py -p tsilva -d exam_2024.pdf

# Reprocess a specific page within a document
python main.py -p tsilva -d exam_2024.pdf --page 2

Output Format

The parser generates structured markdown files with YAML frontmatter:

output/
├── {document}/
│   ├── {document}.pdf            # Source PDF copy
│   ├── {document}.001.jpg        # Page 1 image
│   ├── {document}.001.md         # Page 1 transcription + metadata
│   ├── {document}.002.jpg        # Page 2 image
│   ├── {document}.002.md         # Page 2 transcription + metadata
│   └── {document}.summary.md     # Document-level summary

Transcription File Structure

Each .md file contains YAML frontmatter with metadata followed by the verbatim transcription:

---
date: 2024-01-15
title: "Chest X-Ray PA and Lateral"
category: imaging
exam_name_raw: "RX TORAX PA Y LAT"
doctor: "Dr. Smith"
facility: "Hospital Central"
confidence: 0.95
page: 1
source: exam_2024.pdf
---

[Full verbatim transcription text here...]

Metadata Fields

Architecture

parsemedicalexams/
├── main.py              # Pipeline orchestration, CLI handling
├── extraction.py        # Pydantic models, Vision LLM extraction, voting
├── standardization.py   # Exam type classification with JSON cache
├── summarization.py     # Document-level clinical summarization
├── config.py            # ExtractionConfig (.env) + ProfileConfig (profiles/)
├── utils.py             # Image preprocessing, logging, JSON utilities
├── prompts/             # Externalized LLM prompts as markdown
├── profiles/            # User-specific path configurations
└── config/cache/        # Persistent LLM response caches (user-editable)

Key Design Patterns

• Two-phase processing: Classify document first, then transcribe all pages
• Two-column naming: *_raw (exact from document) + *_standardized (LLM-mapped)
• Persistent caching: LLM standardization results cached in config/cache/*.json
• Editable caches: Manually override cached values to fix misclassifications
• Profile inheritance: Profiles can inherit from .env with overrides
• Frequency-based date voting: Handles multi-era documents (e.g., 2024 cover letter + 1997 records)

Requirements

• Python 3.8+
• Poppler for PDF processing
• OpenRouter API key for Vision LLM access

License

MIT