radreport 0.4.0__py3-none-any.whl

radreport/__init__.py

@@ -0,0 +1,60 @@
+"""
+radreport
+~~~~~~~~~
+Parse, de-identify, structure, and export radiology free-text reports.
+
+Quick start:
+    from radreport import ReportParser, CriticalFindingsDetector, FHIRExporter
+    from radreport import RecommendationExtractor, Deidentifier
+
+    parser    = ReportParser()
+    detector  = CriticalFindingsDetector()
+    extractor = RecommendationExtractor()
+    exporter  = FHIRExporter()
+
+    # Optional: strip PHI first so downstream output is safe to share.
+    raw_text = Deidentifier().deidentify(raw_text).text
+
+    report = parser.parse(raw_text, modality="CT")
+    report = detector.detect(report)
+    report = extractor.extract(report)
+    fhir   = exporter.export(report, patient_id="pt-001")
+
+    # Flat dict for CSV/pandas:
+    row = report.to_flat_dict()
+"""
+
+from .report_parser import ReportParser
+from .critical_findings import CriticalFindingsDetector
+from .recommendation_extractor import RecommendationExtractor
+from .fhir_exporter import FHIRExporter
+from .deidentifier import Deidentifier, deidentify
+from .report_schema import (
+    ParsedReport,
+    ReportSection,
+    Finding,
+    Measurement,
+    CriticalFinding,
+    FollowUpRecommendation,
+    Redaction,
+    DeidentificationResult,
+)
+
+__version__ = "0.4.0"
+__all__ = [
+    "ReportParser",
+    "CriticalFindingsDetector",
+    "RecommendationExtractor",
+    "FHIRExporter",
+    "Deidentifier",
+    "deidentify",
+    "ParsedReport",
+    "ReportSection",
+    "Finding",
+    "Measurement",
+    "CriticalFinding",
+    "FollowUpRecommendation",
+    "Redaction",
+    "DeidentificationResult",
+    "__version__",
+]

radreport/cli.py

@@ -0,0 +1,148 @@
+"""
+Command-line interface for radreport.
+
+Usage:
+    radreport report.txt
+    radreport report.txt --fhir --patient-id pt-001 --modality CT
+    radreport reports/*.txt --critical --recommend --format csv -o batch.csv
+    radreport report.txt --deidentify
+"""
+
+import argparse
+import csv
+import io
+import json
+import sys
+from pathlib import Path
+
+from . import (
+    ReportParser, CriticalFindingsDetector, FHIRExporter,
+    RecommendationExtractor, Deidentifier,
+)
+
+_parser = ReportParser()
+_detector = CriticalFindingsDetector()
+_extractor = RecommendationExtractor()
+_exporter = FHIRExporter()
+_deidentifier = Deidentifier()
+
+
+def _process(path: Path, modality, run_critical, run_recommend, as_fhir, patient_id,
+             run_deidentify=False):
+    """Return (ParsedReport, output_dict). output_dict is FHIR when as_fhir=True."""
+    text = path.read_text(encoding="utf-8")
+
+    if run_deidentify:
+        result = _deidentifier.deidentify(text)
+        if result.redaction_count:
+            print(f"[deid] {path.name}: redacted {result.redaction_count} span(s) "
+                  f"({result.category_counts()})", file=sys.stderr)
+        text = result.text
+
+    report = _parser.parse(text, modality=modality)
+
+    if run_critical:
+        report = _detector.detect(report)
+    if run_recommend:
+        report = _extractor.extract(report)
+
+    if as_fhir:
+        return report, _exporter.export(report, patient_id=patient_id)
+
+    d = report.to_dict()
+    d["source_file"] = path.name
+    return report, d
+
+
+def _to_csv(rows: list[dict]) -> str:
+    if not rows:
+        return ""
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=list(rows[0].keys()), lineterminator="\n")
+    writer.writeheader()
+    writer.writerows(rows)
+    return buf.getvalue()
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="radreport",
+        description="Parse radiology free-text reports into structured JSON, FHIR, or CSV.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+examples:
+  radreport report.txt
+  radreport report.txt --fhir --patient-id pt-001 --modality CT
+  radreport reports/*.txt --critical --recommend --format csv -o batch.csv
+  radreport report.txt --deidentify --critical
+""",
+    )
+    ap.add_argument("files", nargs="+", metavar="FILE",
+                    help="Report .txt file(s) to parse")
+    ap.add_argument("--modality", "-m", metavar="MOD",
+                    help="Imaging modality: CT, MRI, XR, US, NM, PET …")
+    ap.add_argument("--critical", "-c", action="store_true",
+                    help="Run critical findings detection")
+    ap.add_argument("--recommend", "-r", action="store_true",
+                    help="Extract follow-up imaging recommendations")
+    ap.add_argument("--deidentify", "-d", action="store_true",
+                    help="Redact PHI (dates, MRN, names, phone, …) before parsing")
+    ap.add_argument("--fhir", "-f", action="store_true",
+                    help="Export as FHIR R4 DiagnosticReport (implies --critical; not compatible with --format csv)")
+    ap.add_argument("--patient-id", metavar="ID",
+                    help="FHIR Patient resource ID (used with --fhir)")
+    ap.add_argument("--format", "--fmt", dest="fmt", metavar="FMT",
+                    choices=["json", "csv"], default="json",
+                    help="Output format: json (default) or csv (flat one-row-per-report)")
+    ap.add_argument("--output", "-o", metavar="FILE",
+                    help="Write output to FILE instead of stdout")
+
+    args = ap.parse_args(argv)
+
+    if args.fmt == "csv" and args.fhir:
+        ap.error("--format csv is not compatible with --fhir")
+
+    run_critical = args.critical or args.fhir
+    run_recommend = args.recommend
+
+    reports = []   # (ParsedReport, path) for CSV mode
+    json_rows = [] # dicts for JSON mode
+    errors = []
+
+    for f in args.files:
+        p = Path(f)
+        if not p.is_file():
+            errors.append(f"not found: {f}")
+            continue
+        try:
+            report_obj, out = _process(p, args.modality, run_critical, run_recommend,
+                                        args.fhir, args.patient_id, args.deidentify)
+            if args.fmt == "csv":
+                flat = report_obj.to_flat_dict()
+                reports.append({"source_file": p.name, **flat})
+            else:
+                json_rows.append(out)
+        except Exception as e:
+            errors.append(f"{p.name}: {e}")
+
+    for err in errors:
+        print(f"[error] {err}", file=sys.stderr)
+
+    if not reports and not json_rows:
+        sys.exit(1)
+
+    if args.fmt == "csv":
+        output_str = _to_csv(reports)
+    else:
+        output = json_rows[0] if len(json_rows) == 1 else json_rows
+        output_str = json.dumps(output, indent=2)
+
+    if args.output:
+        Path(args.output).write_text(output_str, encoding="utf-8")
+        print(f"Written to {args.output}", file=sys.stderr)
+    else:
+        print(output_str)
+
+
+if __name__ == "__main__":
+    main()

radreport/critical_findings.py

@@ -0,0 +1,221 @@
+"""
+Critical findings detector for radiology reports.
+
+Rule-based and fully auditable — no ML, no external dependencies.
+Designed to be safe to use in clinical alerting pipelines.
+
+IMPORTANT: This library flags *potential* critical findings for human review.
+It is NOT a substitute for radiologist interpretation.
+"""
+
+import re
+from .report_schema import ParsedReport, CriticalFinding
+
+
+# ---------------------------------------------------------------------------
+# Critical findings dictionary
+# Format: term -> (category, severity)
+# severity levels: "critical" | "urgent" | "significant"
+# ---------------------------------------------------------------------------
+
+CRITICAL_TERMS: dict[str, tuple[str, str]] = {
+    # Vascular emergencies
+    "aortic dissection":            ("vascular", "critical"),
+    "aortic rupture":               ("vascular", "critical"),
+    "aortic aneurysm":              ("vascular", "urgent"),
+    "pulmonary embolism":           ("pulmonary", "critical"),
+    "pe":                           ("pulmonary", "critical"),  # abbreviation
+    "saddle embolus":               ("pulmonary", "critical"),
+    "deep vein thrombosis":         ("vascular", "urgent"),
+    "dvt":                          ("vascular", "urgent"),
+    "venous thrombosis":            ("vascular", "urgent"),
+
+    # Pulmonary
+    "pneumothorax":                 ("pulmonary", "critical"),
+    "tension pneumothorax":         ("pulmonary", "critical"),
+    "hemothorax":                   ("pulmonary", "critical"),
+    "pneumomediastinum":            ("pulmonary", "urgent"),
+    "airway obstruction":           ("pulmonary", "critical"),
+    "pulmonary edema":              ("pulmonary", "urgent"),
+    "consolidation":                ("pulmonary", "significant"),
+
+    # Neurological
+    "intracranial hemorrhage":      ("neuro", "critical"),
+    "subdural hematoma":            ("neuro", "critical"),
+    "subdural hemorrhage":          ("neuro", "critical"),
+    "epidural hematoma":            ("neuro", "critical"),
+    "subarachnoid hemorrhage":      ("neuro", "critical"),
+    "cerebral infarction":          ("neuro", "critical"),
+    "stroke":                       ("neuro", "critical"),
+    "brain herniation":             ("neuro", "critical"),
+    "midline shift":                ("neuro", "critical"),
+    "hydrocephalus":                ("neuro", "urgent"),
+    "mass effect":                  ("neuro", "urgent"),
+
+    # Abdominal
+    "bowel perforation":            ("abdominal", "critical"),
+    "free air":                     ("abdominal", "critical"),
+    "pneumoperitoneum":             ("abdominal", "critical"),
+    "mesenteric ischemia":          ("abdominal", "critical"),
+    "bowel obstruction":            ("abdominal", "urgent"),
+    "intussusception":              ("abdominal", "urgent"),
+    "appendicitis":                 ("abdominal", "urgent"),
+    "ruptured ectopic":             ("abdominal", "critical"),
+    "splenic laceration":           ("abdominal", "critical"),
+    "hepatic laceration":           ("abdominal", "critical"),
+
+    # Cardiac
+    "pericardial effusion":         ("cardiac", "urgent"),
+    "cardiac tamponade":            ("cardiac", "critical"),
+    "myocardial infarction":        ("cardiac", "critical"),
+
+    # Spinal / trauma
+    "spinal cord compression":      ("spinal", "critical"),
+    "cervical fracture":            ("spinal", "critical"),
+    "unstable fracture":            ("spinal", "critical"),
+    "cord compression":             ("spinal", "critical"),
+
+    # Oncologic
+    "malignancy":                   ("oncologic", "significant"),
+    "metastasis":                   ("oncologic", "significant"),
+    "metastases":                   ("oncologic", "significant"),
+    "lymphoma":                     ("oncologic", "significant"),
+    "carcinoma":                    ("oncologic", "significant"),
+}
+
+# Negation phrases — if a finding is preceded by these, mark as negated
+NEGATION_PHRASES = [
+    r"no\s+",
+    r"no\s+evidence\s+of\s+",
+    r"no\s+acute\s+",
+    r"without\s+",
+    r"absence\s+of\s+",
+    r"negative\s+for\s+",
+    r"unremarkable\s+for\s+",
+    r"ruled\s+out",
+    r"not\s+seen",
+    r"not\s+identified",
+    r"not\s+present",
+]
+
+NEGATION_WINDOW = 60  # max characters to look back for negation context
+
+# Sentence boundary just before the match. Negation is scoped to the current
+# sentence so a negation in a *previous* sentence cannot suppress a finding in
+# the current one (e.g. "No acute hemorrhage. Large subdural hematoma present.").
+_SENTENCE_BOUNDARY = re.compile(r"[.!?\n]")
+
+
+def _is_negated(text: str, match_start: int) -> bool:
+    """
+    Check if a matched term is preceded by a negation phrase.
+
+    The look-back window is bounded by both NEGATION_WINDOW characters *and* the
+    start of the current sentence, whichever is closer. Scoping to the sentence
+    prevents a negation from a previous sentence from wrongly negating a real
+    finding — a false-negative that would suppress a critical alert.
+    """
+    char_window_start = max(0, match_start - NEGATION_WINDOW)
+
+    # Find the start of the current sentence (after the last boundary char).
+    sentence_start = 0
+    for m in _SENTENCE_BOUNDARY.finditer(text, 0, match_start):
+        sentence_start = m.end()
+
+    window_start = max(char_window_start, sentence_start)
+    preceding = text[window_start:match_start].lower()
+
+    for phrase in NEGATION_PHRASES:
+        if re.search(phrase, preceding):
+            return True
+    return False
+
+
+def _get_sentence_context(text: str, match_start: int, match_end: int) -> str:
+    """Extract the sentence containing the matched term."""
+    # Walk back to sentence start
+    start = text.rfind('.', 0, match_start)
+    start = start + 1 if start != -1 else 0
+
+    # Walk forward to sentence end
+    end = text.find('.', match_end)
+    end = end + 1 if end != -1 else len(text)
+
+    return text[start:end].strip()
+
+
+class CriticalFindingsDetector:
+    """
+    Scans a ParsedReport for critical, urgent, and significant findings.
+
+    Usage:
+        detector = CriticalFindingsDetector()
+        report = detector.detect(parsed_report)
+        # report.critical_findings is now populated
+    """
+
+    def detect(self, report: ParsedReport) -> ParsedReport:
+        """
+        Scan all sections of a ParsedReport and attach CriticalFinding objects.
+        Modifies the report in place and returns it.
+
+        Args:
+            report: A ParsedReport from ReportParser.parse()
+
+        Returns:
+            The same ParsedReport with critical_findings populated.
+        """
+        # Focus on clinically meaningful sections
+        target_sections = {"findings", "impression", "preamble"}
+        scan_text_parts = []
+
+        for section in report.sections:
+            if section.name in target_sections:
+                scan_text_parts.append(section.raw_text)
+
+        # Fallback: scan full text if no structured sections
+        scan_text = "\n".join(scan_text_parts) if scan_text_parts else report.raw_text
+
+        findings: list[CriticalFinding] = []
+
+        for term, (category, severity) in CRITICAL_TERMS.items():
+            pattern = re.compile(r'\b' + re.escape(term) + r'\b', re.IGNORECASE)
+            normalized_term = term.strip()
+
+            # Collect every occurrence of the term, then emit a single finding.
+            # A term is only reported as negated if EVERY occurrence is negated:
+            # a real (non-negated) mention must never be suppressed by a negated
+            # one elsewhere in the report — that would drop a critical alert.
+            matches = list(pattern.finditer(scan_text))
+            if not matches:
+                continue
+
+            active_match = None
+            for match in matches:
+                if not _is_negated(scan_text, match.start()):
+                    active_match = match
+                    break
+
+            chosen = active_match or matches[0]
+            negated = active_match is None
+            context = _get_sentence_context(scan_text, chosen.start(), chosen.end())
+
+            findings.append(CriticalFinding(
+                term=normalized_term,
+                category=category,
+                severity=severity,
+                context=context,
+                negated=negated,
+            ))
+
+        # Sort: critical first, then urgent, then significant; negated last
+        severity_order = {"critical": 0, "urgent": 1, "significant": 2}
+        findings.sort(key=lambda f: (f.negated, severity_order.get(f.severity, 9)))
+
+        report.critical_findings = findings
+        return report
+
+    @property
+    def supported_terms(self) -> list[str]:
+        """Return all terms currently monitored."""
+        return list(CRITICAL_TERMS.keys())

radreport/deidentifier.py

@@ -0,0 +1,237 @@
+"""
+Rule-based de-identification (PHI redaction) for radiology reports.
+
+Removes Protected Health Information so that reports can be shared with research
+collaborators, stored in analytics warehouses, or processed off-site. Every
+decision is a traceable regular-expression rule — no ML, no GPU, no external
+service — so the transformation can be audited line by line and re-run
+deterministically. This is what makes it acceptable in environments where
+sending text to a cloud NER API is not an option.
+
+The categories map to the HIPAA Safe Harbor identifier list where they are
+reliably matchable from text alone: dates, telephone/fax numbers, email
+addresses, SSNs, medical-record and accession numbers, URLs, IP addresses, ZIP
+codes, ages over 89, and names that follow an explicit title or header label.
+
+IMPORTANT — read before relying on this for compliance:
+    Free-text de-identification is inherently imperfect. Names that appear in
+    narrative prose *without* a title or label (e.g. a surname mentioned mid
+    sentence) are NOT caught by a rule-based system. Treat the output as a
+    strong first pass that must still be reviewed before any PHI leaves a
+    controlled environment. This tool does not certify Safe Harbor compliance.
+"""
+
+import re
+from typing import Iterable, Optional
+
+from .report_schema import DeidentificationResult, Redaction
+
+
+# ---------------------------------------------------------------------------
+# Replacement placeholders, one per category.
+# ---------------------------------------------------------------------------
+PLACEHOLDERS: dict[str, str] = {
+    "date": "[DATE]",
+    "age": "[AGE]",
+    "ssn": "[SSN]",
+    "mrn": "[MRN]",
+    "accession": "[ACCESSION]",
+    "phone": "[PHONE]",
+    "email": "[EMAIL]",
+    "url": "[URL]",
+    "ipv4": "[IP]",
+    "zip": "[ZIP]",
+    "name": "[NAME]",
+}
+
+# All categories, in the order they are applied. Order is only a tie-breaker
+# for overlapping matches (earlier categories win); non-overlapping matches are
+# unaffected. More specific / higher-confidence patterns come first.
+DEFAULT_CATEGORIES: tuple[str, ...] = (
+    "ssn", "mrn", "accession", "phone", "email", "url", "ipv4",
+    "date", "age", "zip", "name",
+)
+
+
+# ---------------------------------------------------------------------------
+# Rules. Each category maps to a list of compiled patterns. The full match
+# (group 0) is what gets redacted, so patterns use lookahead/label groups to
+# anchor context without consuming text that must be kept.
+# ---------------------------------------------------------------------------
+_MONTHS = (
+    r"Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|"
+    r"Jul(?:y)?|Aug(?:ust)?|Sep(?:t|tember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?"
+)
+
+_RULES: dict[str, list[re.Pattern]] = {
+    "ssn": [
+        re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+    ],
+    "mrn": [
+        # "MRN: 12345678", "Medical Record Number 12345678", "MRN# 1234567"
+        re.compile(
+            r"\b(?:MRN|medical\s+record\s+(?:number|no|#))\s*[:#]?\s*[A-Z]?\d[\d-]{4,}\b",
+            re.IGNORECASE,
+        ),
+    ],
+    "accession": [
+        # "Accession: A12345678", "Acc # 12345678", "Accession Number 12345678"
+        re.compile(
+            r"\b(?:accession(?:\s+(?:number|no|#))?|acc\s*#)\s*[:#]?\s*[A-Z]{0,3}\d[\d-]{4,}\b",
+            re.IGNORECASE,
+        ),
+    ],
+    "phone": [
+        # (555) 123-4567 / 555-123-4567 / 555.123.4567 / +1 555 123 4567
+        re.compile(
+            r"(?<!\d)(?:\+?1[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]\d{3}[\s.-]\d{4}(?!\d)"
+        ),
+    ],
+    "email": [
+        re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"),
+    ],
+    "url": [
+        re.compile(r"\bhttps?://[^\s<>\"')]+", re.IGNORECASE),
+    ],
+    "ipv4": [
+        re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b"),
+    ],
+    "date": [
+        # 03/10/2024, 3-10-24, 2024-03-10
+        re.compile(r"\b\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b"),
+        re.compile(r"\b\d{4}-\d{1,2}-\d{1,2}\b"),
+        # March 5, 2024 / 5 March 2024 / Mar 2024
+        re.compile(rf"\b(?:{_MONTHS})\.?\s+\d{{1,2}}(?:st|nd|rd|th)?,?\s+\d{{4}}\b", re.IGNORECASE),
+        re.compile(rf"\b\d{{1,2}}(?:st|nd|rd|th)?\s+(?:{_MONTHS})\.?\s+\d{{4}}\b", re.IGNORECASE),
+        re.compile(rf"\b(?:{_MONTHS})\.?\s+\d{{4}}\b", re.IGNORECASE),
+    ],
+    "age": [
+        # HIPAA: ages 90+ must not be reported in the clear. Require an age cue
+        # so ordinary measurements ("90 mm") are never mistaken for an age.
+        re.compile(
+            r"\b(?:9\d|1\d\d)\s*[- ]?\s*(?:years?|yrs?|y)[- ]?(?:old|/o|o)\b",
+            re.IGNORECASE,
+        ),
+        re.compile(r"\bage[d]?\s*[:#]?\s*(?:9\d|1\d\d)\b", re.IGNORECASE),
+    ],
+    "zip": [
+        # Only when preceded by a 2-letter state code, to avoid nuking any 5-digit number.
+        re.compile(r"\b[A-Z]{2}\s+\d{5}(?:-\d{4})?\b"),
+    ],
+    "name": [
+        # Titled names: Dr. Jane Smith, Mr. John Q. Doe
+        re.compile(
+            r"\b(?:Dr|Doctor|Mr|Mrs|Ms|Miss|Prof)\.?\s+"
+            r"[A-Z][a-z]+(?:\s+[A-Z]\.?)?(?:\s+[A-Z][a-z]+)?"
+        ),
+        # Header label followed by a value, e.g. "Patient Name: John Doe".
+        # Only the value (group 1) is redacted; the label is preserved. The
+        # value stops at a column break (2+ spaces) or end of line so that a
+        # multi-field header line ("Name: Doe    MRN: 123") does not swallow the
+        # following fields — those are matched by their own category rules.
+        re.compile(
+            r"(?im)^[ \t]*(?:patient(?:\s+name)?|name|physician|"
+            r"referring(?:\s+physician)?|referred\s+by|dictated\s+by|"
+            r"signed\s+by|attending|resident|technologist)\s*:[ \t]*"
+            r"([^\n]+?)(?=\s{2,}|$)"
+        ),
+    ],
+}
+
+
+class Deidentifier:
+    """
+    Redact PHI from radiology report text.
+
+    Usage:
+        deid = Deidentifier()
+        result = deid.deidentify(raw_text)
+        clean_text = result.text
+        print(result.category_counts())   # {"date": 2, "mrn": 1, ...}
+
+    Args:
+        categories: Iterable of category names to enable. Defaults to all.
+        placeholders: Optional overrides for the replacement tokens, e.g.
+                      {"name": "XXXX"}. Categories not listed keep their default.
+    """
+
+    def __init__(
+        self,
+        categories: Optional[Iterable[str]] = None,
+        placeholders: Optional[dict[str, str]] = None,
+    ):
+        requested = tuple(categories) if categories is not None else DEFAULT_CATEGORIES
+        unknown = [c for c in requested if c not in _RULES]
+        if unknown:
+            raise ValueError(
+                f"Unknown de-identification categor{'y' if len(unknown) == 1 else 'ies'}: "
+                f"{', '.join(unknown)}. Valid options: {', '.join(sorted(_RULES))}."
+            )
+        # Preserve the canonical ordering (tie-break priority) among requested cats.
+        self.categories = tuple(c for c in DEFAULT_CATEGORIES if c in set(requested))
+        self.placeholders = {**PLACEHOLDERS, **(placeholders or {})}
+
+    def deidentify(self, text: str) -> DeidentificationResult:
+        """
+        Scrub PHI from `text` and return a DeidentificationResult.
+
+        The returned `text` has every detected identifier replaced by a category
+        placeholder. `redactions` is the audit trail, ordered by position, with
+        offsets into the ORIGINAL text.
+        """
+        if text is None:
+            raise ValueError("Text cannot be None.")
+
+        candidates: list[tuple[int, int, str]] = []  # (start, end, category)
+        for category in self.categories:
+            for pattern in _RULES[category]:
+                for m in pattern.finditer(text):
+                    # If the pattern captured a value group (label fields), redact
+                    # only that group; otherwise redact the whole match.
+                    if m.groups():
+                        start, end = m.span(1)
+                    else:
+                        start, end = m.span(0)
+                    if start < end:
+                        candidates.append((start, end, category))
+
+        # Resolve overlaps: sort by start, then longer span, then category priority.
+        priority = {c: i for i, c in enumerate(self.categories)}
+        candidates.sort(key=lambda c: (c[0], -(c[1] - c[0]), priority.get(c[2], 99)))
+
+        chosen: list[tuple[int, int, str]] = []
+        last_end = 0
+        for start, end, category in candidates:
+            if start >= last_end:
+                chosen.append((start, end, category))
+                last_end = end
+
+        # Rebuild the scrubbed text and the redaction records in one pass.
+        out_parts: list[str] = []
+        redactions: list[Redaction] = []
+        cursor = 0
+        for start, end, category in chosen:
+            out_parts.append(text[cursor:start])
+            replacement = self.placeholders[category]
+            out_parts.append(replacement)
+            redactions.append(Redaction(
+                category=category,
+                original=text[start:end],
+                replacement=replacement,
+                start=start,
+                end=end,
+            ))
+            cursor = end
+        out_parts.append(text[cursor:])
+
+        return DeidentificationResult(text="".join(out_parts), redactions=redactions)
+
+    @property
+    def supported_categories(self) -> list[str]:
+        """All PHI categories this de-identifier can detect."""
+        return list(_RULES.keys())
+
+
+def deidentify(text: str, **kwargs) -> DeidentificationResult:
+    """Convenience wrapper: `Deidentifier(**kwargs).deidentify(text)`."""
+    return Deidentifier(**kwargs).deidentify(text)