deidkit 0.1.0__py3-none-any.whl

deidkit/detect/gazetteer.py

@@ -0,0 +1,158 @@
+"""Gazetteer stage: dictionary matching of person names.
+
+Loads curated given-name (with gender) and surname lists, plus honorifics,
+context triggers and a medical stoplist. Proposes PERSON spans from runs of
+adjacent title-case tokens that contain at least one known name token. A run is
+only a *proposal*; the pipeline's voting gate decides whether it is confident
+enough to replace (e.g. a lone surname that is also a common word waits for
+corroboration).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Set
+
+from ..resources import load_given_names, load_set, load_surnames
+from ..textnorm import Token, is_titlecase, norm
+from .types import Detection, PERSON
+
+# Connectors allowed *inside* one compound name span. Deliberately excludes "y"
+# and "san"/"santa": "Juan Pérez y María Gómez" is two people, not one, and
+# "San ..." is usually a place. da/do/dos/das cover Portuguese/Brazilian names.
+CONNECTORS: Set[str] = {"de", "del", "la", "las", "los", "da", "das", "do", "dos"}
+MAX_RUN = 6
+
+
+class Gazetteer:
+    def __init__(
+        self,
+        given: Dict[str, str],
+        surnames: Set[str],
+        honorifics: Set[str],
+        triggers: Set[str],
+        stoplist: Set[str],
+    ):
+        self.given = given
+        self.surnames = surnames
+        self.honorifics = honorifics
+        self.triggers = triggers
+        self.stoplist = stoplist
+
+    @classmethod
+    def load(cls, lang="es", extra_name_files=(), extra_stoplist_files=(),
+             use_medical_vocab=True):
+        from ..resources import load_lang_sets
+
+        given = load_given_names(lang, extra_name_files)
+        surnames = load_surnames(lang, extra_name_files)
+        honorifics = load_lang_sets("honorifics", lang)
+        triggers = load_lang_sets("context_triggers", lang)
+        stoplist = load_lang_sets("medical_stoplist", lang, extra_stoplist_files)
+        if not stoplist:  # never run without a stoplist (precision guard)
+            stoplist = load_set("medical_stoplist_es.txt", extra_stoplist_files)
+        if use_medical_vocab:  # bundled RxNorm-derived safe-vocabulary (Philter-style)
+            try:
+                stoplist |= load_set("medical_vocab.txt")
+            except (FileNotFoundError, OSError):
+                pass
+        return cls(given, surnames, honorifics, triggers, stoplist)
+
+    # --- token predicates -------------------------------------------------- #
+    def is_given(self, nrm: str) -> bool:
+        return nrm in self.given
+
+    def gender(self, nrm: str) -> str:
+        return self.given.get(nrm, "u")
+
+    def is_surname(self, nrm: str) -> bool:
+        return nrm in self.surnames
+
+    def is_name_token(self, nrm: str) -> bool:
+        return nrm in self.given or nrm in self.surnames
+
+    def is_stopword(self, nrm: str) -> bool:
+        return nrm in self.stoplist
+
+    def is_honorific(self, nrm: str) -> bool:
+        return nrm.rstrip(".") in self.honorifics
+
+    def is_trigger(self, nrm: str) -> bool:
+        return nrm in self.triggers
+
+    def is_boundary(self, nrm: str) -> bool:
+        """A token that must not be part of a name span (stopword / anchor word).
+
+        Honorifics and role triggers *precede* names; absorbing them into the
+        span ("Acompañante María Gómez") is wrong, so they end a run.
+        """
+        return self.is_stopword(nrm) or self.is_honorific(nrm) or self.is_trigger(nrm)
+
+
+def _trim_connectors(run: List[Token]) -> List[Token]:
+    while run and run[0].norm in CONNECTORS:
+        run = run[1:]
+    while run and run[-1].norm in CONNECTORS:
+        run = run[:-1]
+    return run
+
+
+def find(text: str, tokens: List[Token], gaz: Gazetteer) -> List[Detection]:
+    """Propose PERSON spans from gazetteer-anchored title-case runs."""
+    dets: List[Detection] = []
+    n = len(tokens)
+    i = 0
+    while i < n:
+        t = tokens[i]
+        if not is_titlecase(t.text) or gaz.is_boundary(t.norm):
+            i += 1
+            continue
+        # Grow a run of title-case, non-boundary tokens (connectors allowed
+        # between name tokens for Spanish compound surnames).
+        run: List[Token] = []
+        j = i
+        while j < n and len(run) < MAX_RUN:
+            tj = tokens[j]
+            if is_titlecase(tj.text) and not gaz.is_boundary(tj.norm):
+                run.append(tj)
+                j += 1
+            elif (
+                tj.norm in CONNECTORS
+                and run
+                and j + 1 < n
+                and is_titlecase(tokens[j + 1].text)
+                and not gaz.is_boundary(tokens[j + 1].norm)
+            ):
+                run.append(tj)
+                j += 1
+            else:
+                break
+
+        run = _trim_connectors(run)
+        if run:
+            known_given = sum(1 for r in run if gaz.is_given(r.norm))
+            known_surname = sum(1 for r in run if gaz.is_surname(r.norm))
+            name_tokens = [r for r in run if r.norm not in CONNECTORS]
+            if known_given + known_surname >= 1:
+                gender = "u"
+                for r in run:
+                    if gaz.is_given(r.norm):
+                        gender = gaz.gender(r.norm)
+                        break
+                dets.append(
+                    Detection(
+                        start=run[0].start,
+                        end=run[-1].end,
+                        text=text[run[0].start : run[-1].end],
+                        entity_type=PERSON,
+                        methods={"gazetteer"},
+                        meta={
+                            "known_given": known_given,
+                            "known_surname": known_surname,
+                            "run_len": len(name_tokens),
+                            "bigram": known_given >= 1 and known_surname >= 1,
+                            "gender": gender,
+                        },
+                    )
+                )
+        i = max(j, i + 1)
+    return dets

deidkit/detect/patterns.py

@@ -0,0 +1,147 @@
+"""Regex stage: structured identifiers embedded in free text.
+
+These patterns are deliberately precise. Bare numbers are *not* matched as IDs
+(a 7-digit run could be a lab value or a code); a national ID is only taken when
+a document cue (``CC``, ``cédula``, ``documento`` ...) or thousands-dotted shape
+makes it unambiguous. Every hit here is high-precision and accepted directly by
+the voting gate.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+from .types import (
+    Detection,
+    DATE,
+    EMAIL,
+    IPADDR,
+    MRN,
+    NATIONAL_ID,
+    PHONE,
+    URL,
+)
+
+# Unicode-aware: accented local parts (e.g. diego.gómez@...) must match fully.
+EMAIL_RE = re.compile(
+    r"(?<![\w.%+\-])[\w.%+\-]+@[\w\-]+(?:\.[\w\-]+)*\.[A-Za-z]{2,}(?![\w])",
+    re.UNICODE,
+)
+
+# http(s):// URLs and bare www. hosts (which can carry names/IDs in the path).
+URL_RE = re.compile(r"\b(?:https?://|www\.)[^\s<>\"')]+", re.IGNORECASE)
+# Trailing characters that are sentence punctuation, not part of the URL.
+_URL_TRAILING = ".,;:!?'\")]}>"
+
+IP_RE = re.compile(
+    r"\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b"
+)
+
+# Colombian phones: optional +57 / (57), mobile (3xx, 10 digits) or landline
+# with separators. Requires separators or a country/area cue so we don't grab
+# plain long integers.
+PHONE_RE = re.compile(
+    r"""(?<!\d)(?:
+        (?:\+?57[\s\-.]?)?          # optional country code
+        (?:\(?\d{1,3}\)?[\s\-.])?   # optional area code in parens or with sep
+        3\d{2}[\s\-.]?\d{3}[\s\-.]?\d{2,4}   # mobile 3xx xxx xxxx
+      |
+        (?:\+?57[\s\-.]?)?\(?\d{1,3}\)?[\s\-.]\d{3}[\s\-.]?\d{4}  # landline
+    )(?!\d)""",
+    re.VERBOSE,
+)
+
+# National ID (cédula / documento) with an explicit document cue.
+CEDULA_CUED_RE = re.compile(
+    r"""(?ix)
+    \b(?:c\.?\s?c\.?|c[eé]dula(?:\s+de\s+ciudadan[ií]a)?|
+        documento|identificaci[oó]n|nuip|
+        t\.?\s?i\.?|r\.?\s?c\.?|c\.?\s?e\.?|no\.?\s?documento)
+    \s*[:#\-]?\s*
+    (\d{1,3}(?:[.\s]\d{3}){2,3}|\d{6,11})
+    """
+)
+
+# Thousands-dotted 8-11 digit number, which in ES text is almost always a cédula.
+CEDULA_DOTTED_RE = re.compile(r"(?<!\d)\d{1,3}(?:\.\d{3}){2,3}(?!\d)")
+
+# Medical-record / historia-clínica number with a cue.
+MRN_RE = re.compile(
+    r"""(?ix)
+    \b(?:h\.?\s?c\.?|historia(?:\s+cl[ií]nica)?|
+        n[uú]mero\s+de\s+historia|expediente|folio|mrn)
+    \s*(?:n[o°º]\.?)?\s*[:#\-]?\s*
+    (\d{4,12})
+    """
+)
+
+# Dates: numeric (dd/mm/yyyy etc.) and Spanish long form.
+DATE_NUMERIC_RE = re.compile(
+    r"(?<!\d)(?:\d{1,2}[/\-.]\d{1,2}[/\-.]\d{2,4}|\d{4}[/\-.]\d{1,2}[/\-.]\d{1,2})(?!\d)"
+)
+DATE_LONG_ES_RE = re.compile(
+    r"(?i)\b\d{1,2}\s+de\s+(?:enero|febrero|marzo|abril|mayo|junio|julio|agosto|"
+    r"septiembre|setiembre|octubre|noviembre|diciembre)\s+(?:de\s+)?\d{4}\b"
+)
+_EN_MONTH = (r"jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec|january|february|"
+             r"march|april|june|july|august|september|october|november|december")
+DATE_LONG_EN_RE = re.compile(
+    rf"(?i)\b(?:{_EN_MONTH})\.?\s+\d{{1,2}}(?:st|nd|rd|th)?,?\s+\d{{4}}\b"       # March 5, 2021
+    rf"|\b\d{{1,2}}(?:st|nd|rd|th)?\s+(?:{_EN_MONTH})\.?,?\s+\d{{4}}\b"          # 5 March 2021
+)
+# 05-ABR-1988 / 5-MAR-88 (day-monthname-year, common in DB exports)
+DATE_ALPHA_DMY_RE = re.compile(
+    r"(?i)\b\d{1,2}[-/](?:ene|feb|mar|abr|may|jun|jul|ago|sep|set|oct|nov|dic|"
+    rf"{_EN_MONTH})[-/]\d{{2,4}}\b"
+)
+
+
+def _add(dets: List[Detection], m, etype: str, group: int = 0, meta=None):
+    start, end = m.span(group)
+    dets.append(
+        Detection(
+            start=start,
+            end=end,
+            text=m.string[start:end],
+            entity_type=etype,
+            methods={"regex"},
+            confidence=0.99,
+            meta=meta or {},
+        )
+    )
+
+
+def find(text: str) -> List[Detection]:
+    """Return all identifier detections in ``text``."""
+    dets: List[Detection] = []
+    for m in EMAIL_RE.finditer(text):
+        _add(dets, m, EMAIL)
+    for m in URL_RE.finditer(text):
+        start, end = m.start(), m.end()
+        while end > start and text[end - 1] in _URL_TRAILING:  # keep sentence punctuation
+            end -= 1
+        dets.append(
+            Detection(start=start, end=end, text=text[start:end], entity_type=URL,
+                      methods={"regex"}, confidence=0.99)
+        )
+    for m in IP_RE.finditer(text):
+        _add(dets, m, IPADDR)
+    for m in CEDULA_CUED_RE.finditer(text):
+        _add(dets, m, NATIONAL_ID, group=1)
+    for m in CEDULA_DOTTED_RE.finditer(text):
+        _add(dets, m, NATIONAL_ID)
+    for m in MRN_RE.finditer(text):
+        _add(dets, m, MRN, group=1)
+    for m in PHONE_RE.finditer(text):
+        # Guard: skip if it is entirely inside an already-found email/url span.
+        _add(dets, m, PHONE)
+    for m in DATE_NUMERIC_RE.finditer(text):
+        _add(dets, m, DATE)
+    for m in DATE_LONG_ES_RE.finditer(text):
+        _add(dets, m, DATE)
+    for m in DATE_LONG_EN_RE.finditer(text):
+        _add(dets, m, DATE)
+    for m in DATE_ALPHA_DMY_RE.finditer(text):
+        _add(dets, m, DATE)
+    return dets

deidkit/detect/pipeline.py

@@ -0,0 +1,234 @@
+"""Detection orchestrator + voting gate.
+
+Runs every stage over a text value, merges overlapping spans, then scores each
+person cluster from the combination of signals that fired. Whether a detection
+is *accepted* (replaced) or sent to the *review queue* depends on the score and
+the policy ``mode``:
+
+============  =========  =============================================
+mode          threshold  typical effect
+============  =========  =============================================
+conservative  0.80       only clear names (bigram / honorific / 2-detector)
+balanced      0.65       also accept single-model NER hits
+aggressive    0.35       also accept lone gazetteer tokens
+============  =========  =============================================
+
+This is how the layered design pursues high capture with low error: confident
+signals are replaced automatically, and the ambiguous tail is surfaced for human
+review in the audit workbook rather than silently changed or silently missed.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import List, Optional
+
+from ..textnorm import tokenize
+from . import context, gazetteer, patterns
+from .gazetteer import Gazetteer
+from .spacy_ner import SpacyNER
+from .types import Detection, PERSON
+
+_IDENTIFIER_TYPES = {"EMAIL", "PHONE", "NATIONAL_ID", "MRN", "URL", "DATE", "IP"}
+
+# Eponym context: a person-name token that is really a disease/sign/test name.
+_EPONYM_BEFORE = re.compile(
+    r"(?i)(?:enfermedad|s[ií]ndrome|signo|prueba|maniobra|escala|fen[oó]meno|reflejo|"
+    r"cl[aá]sificaci[oó]n|[ií]ndice|test|disease|syndrome|sign|scale|reflex|maneuver|"
+    r"score|grade|stage|classification|lesi[oó]n|tumor)\s+de\s+$"
+)
+_EPONYM_AFTER = re.compile(
+    r"(?i)^['’]?s?\s*(?:disease|syndrome|sign|test|scale|reflex|maneuver|score|grade|"
+    r"stage|classification|cell|cells|body|bodies|node|nodes|method|stain|tumou?r)\b"
+)
+
+_THRESHOLDS = {"conservative": 0.80, "balanced": 0.65, "aggressive": 0.35}
+
+
+class Detector:
+    """Full multi-stage detector for one language."""
+
+    def __init__(
+        self,
+        lang: str = "es",
+        mode: str = "conservative",
+        spacy_model: Optional[str] = None,
+        extra_name_files=(),
+        extra_stoplist_files=(),
+        id_checksums=(),
+        use_medical_vocab=True,
+    ):
+        self.lang = lang
+        self.mode = mode
+        self.id_checksums = list(id_checksums or [])
+        self.threshold = _THRESHOLDS.get(mode, 0.80)
+        self.gaz: Gazetteer = Gazetteer.load(
+            lang, extra_name_files, extra_stoplist_files, use_medical_vocab
+        )
+        self.ner: Optional[SpacyNER] = SpacyNER(spacy_model) if spacy_model else None
+
+    @property
+    def ner_status(self) -> str:
+        if self.ner is None:
+            return "disabled"
+        return "active" if self.ner.available else f"unavailable ({self.ner.error})"
+
+    # ------------------------------------------------------------------ #
+    def detect(self, text: str) -> List[Detection]:
+        """Return all detections with ``.accepted`` and ``.confidence`` set.
+
+        ``text`` is NFC-normalized first so combining-mark (NFD) input like a
+        decomposed ``Ramírez`` tokenizes correctly (otherwise the span ends early
+        and a fragment leaks). Callers that apply replacements MUST slice the same
+        NFC-normalized string (the engine does)."""
+        if not text or not str(text).strip():
+            return []
+        text = unicodedata.normalize("NFC", str(text))
+        tokens = tokenize(text)
+
+        raw: List[Detection] = []
+        raw += patterns.find(text)
+        if self.id_checksums:
+            from . import checksums
+            raw += checksums.find_valid_ids(text, self.id_checksums)
+        raw += context.find(text, tokens, self.gaz)
+        raw += gazetteer.find(text, tokens, self.gaz)
+        if self.ner is not None and self.ner.available:
+            raw += self.ner.find(text)
+
+        idents = [d for d in raw if d.entity_type in _IDENTIFIER_TYPES]
+        persons = [d for d in raw if d.entity_type == PERSON]
+
+        accepted_idents = self._resolve_identifiers(idents)
+        person_dets = self._resolve_persons(persons, accepted_idents)
+
+        final = accepted_idents + person_dets
+        final.sort(key=lambda d: (d.start, -(d.end - d.start)))
+        final = self._drop_accepted_overlaps(final)
+        self._suppress_eponyms(text, final)
+        return final
+
+    @staticmethod
+    def _suppress_eponyms(text: str, dets: List[Detection]) -> None:
+        """Demote eponymous diagnoses (``enfermedad de Wilson``, ``Down syndrome``,
+        ``Parkinson's disease``) from replace to review — they are disease names,
+        not the patient. Real names in other contexts are unaffected."""
+        for d in dets:
+            if not d.accepted or d.entity_type != PERSON:
+                continue
+            if _EPONYM_BEFORE.search(text[: d.start]) or _EPONYM_AFTER.match(text[d.end :]):
+                d.accepted = False
+                d.meta["suppressed"] = "eponym"
+
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _resolve_identifiers(idents: List[Detection]) -> List[Detection]:
+        """Greedy longest-span-wins over overlapping identifier hits."""
+        idents.sort(key=lambda d: (d.start, -(d.end - d.start)))
+        kept: List[Detection] = []
+        occupied_end = -1
+        for d in idents:
+            if d.start >= occupied_end:
+                d.accepted = True
+                d.confidence = max(d.confidence, 0.95)
+                kept.append(d)
+                occupied_end = d.end
+            elif d.end > occupied_end:
+                # partial overlap with a shorter tail; skip to avoid double-edit
+                continue
+        return kept
+
+    def _resolve_persons(
+        self, persons: List[Detection], idents: List[Detection]
+    ) -> List[Detection]:
+        clusters = _merge_person_spans(persons)
+        out: List[Detection] = []
+        for c in clusters:
+            # suppress person spans overlapping an accepted identifier
+            if any(c.overlaps(i) for i in idents):
+                continue
+            c.confidence = _score_person(c)
+            c.accepted = c.confidence >= self.threshold
+            out.append(c)
+        return out
+
+    @staticmethod
+    def _drop_accepted_overlaps(final: List[Detection]) -> List[Detection]:
+        """Ensure accepted spans never overlap (safe replacement)."""
+        result: List[Detection] = []
+        occupied_end = -1
+        for d in sorted(final, key=lambda d: (d.start, -(d.end - d.start))):
+            if not d.accepted:
+                result.append(d)
+                continue
+            if d.start >= occupied_end:
+                result.append(d)
+                occupied_end = d.end
+            # else: overlapping accepted span -> drop (already covered)
+        return result
+
+
+# --------------------------------------------------------------------------- #
+def _merge_person_spans(persons: List[Detection]) -> List[Detection]:
+    """Merge overlapping person detections into clusters (union span + meta)."""
+    if not persons:
+        return []
+    persons = sorted(persons, key=lambda d: (d.start, d.end))
+    clusters: List[Detection] = []
+    cur = _clone(persons[0])
+    for d in persons[1:]:
+        if d.start < cur.end:  # overlap
+            cur.end = max(cur.end, d.end)
+            cur.text += ""  # placeholder; text re-set below
+            _merge_meta(cur, d)
+        else:
+            clusters.append(cur)
+            cur = _clone(d)
+    clusters.append(cur)
+    return clusters
+
+
+def _clone(d: Detection) -> Detection:
+    return Detection(
+        start=d.start,
+        end=d.end,
+        text=d.text,
+        entity_type=d.entity_type,
+        methods=set(d.methods),
+        meta=dict(d.meta),
+    )
+
+
+def _merge_meta(cur: Detection, other: Detection) -> None:
+    cur.methods |= other.methods
+    for key in ("known_given", "known_surname", "run_len"):
+        cur.meta[key] = max(cur.meta.get(key, 0), other.meta.get(key, 0))
+    cur.meta["bigram"] = cur.meta.get("bigram") or other.meta.get("bigram")
+    if cur.meta.get("gender", "u") == "u":
+        cur.meta["gender"] = other.meta.get("gender", "u")
+    # keep the strongest context strength seen (strong > naming > verb)
+    rank = {"strong": 3, "naming": 2, "weak": 1, "verb": 1}
+    a, b = cur.meta.get("strength"), other.meta.get("strength")
+    cur.meta["strength"] = a if rank.get(a, 0) >= rank.get(b, 0) else b
+
+
+def _score_person(d: Detection) -> float:
+    methods = d.methods
+    meta = d.meta
+    score = 0.30
+    if "context" in methods:
+        strength = meta.get("strength")
+        score += {"strong": 0.55, "naming": 0.45}.get(strength, 0.30)
+    if "ner" in methods:
+        score += 0.35
+    if meta.get("bigram"):
+        score += 0.45
+    elif meta.get("run_len", 1) >= 2:
+        score += 0.15
+    known = meta.get("known_given", 0) + meta.get("known_surname", 0)
+    if known >= 1 and "gazetteer" in methods:
+        score += 0.10
+    if len(methods) >= 2:
+        score += 0.20
+    return min(score, 0.99)

deidkit/detect/spacy_ner.py

@@ -0,0 +1,53 @@
+"""Optional statistical NER stage (spaCy).
+
+Enabled only when ``Policy.spacy_model`` is set and spaCy + the model are
+installed. It is used as an independent PERSON detector and to corroborate
+gazetteer hits. Everything degrades gracefully: if the model is missing,
+``available`` is ``False`` and :meth:`find` returns nothing, so the tool still
+runs on the deterministic stages alone.
+
+    pip install "deidkit[ner]"
+    python -m spacy download es_core_news_lg
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from .types import Detection, PERSON
+
+_PERSON_LABELS = {"PER", "PERSON"}
+
+
+class SpacyNER:
+    def __init__(self, model: str):
+        self.model = model
+        self._nlp = None
+        self.available = False
+        self.error = None
+        try:
+            import spacy
+
+            self._nlp = spacy.load(model, disable=["lemmatizer", "textcat"])
+            self.available = True
+        except Exception as exc:  # ImportError or OSError (model not found)
+            self.error = str(exc)
+
+    def find(self, text: str) -> List[Detection]:
+        if not self.available or not text:
+            return []
+        doc = self._nlp(text)
+        out: List[Detection] = []
+        for ent in doc.ents:
+            if ent.label_ in _PERSON_LABELS:
+                out.append(
+                    Detection(
+                        start=ent.start_char,
+                        end=ent.end_char,
+                        text=ent.text,
+                        entity_type=PERSON,
+                        methods={"ner"},
+                        meta={"gender": "u"},
+                    )
+                )
+        return out

deidkit/detect/types.py

@@ -0,0 +1,53 @@
+"""Detection data model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Set
+
+# --- entity types ---------------------------------------------------------- #
+PERSON = "PERSON"
+EMAIL = "EMAIL"
+PHONE = "PHONE"
+NATIONAL_ID = "NATIONAL_ID"   # e.g. Colombian cédula
+MRN = "MRN"                   # medical-record / historia-clínica number
+URL = "URL"
+DATE = "DATE"                 # date embedded in free text
+IPADDR = "IP"
+
+# Namespace helper so callers can write ``entity.PERSON`` if they prefer.
+class entity:  # noqa: N801 - used as a namespace
+    PERSON = PERSON
+    EMAIL = EMAIL
+    PHONE = PHONE
+    NATIONAL_ID = NATIONAL_ID
+    MRN = MRN
+    URL = URL
+    DATE = DATE
+    IP = IPADDR
+
+
+@dataclass
+class Detection:
+    """A detected span of PII inside a text value.
+
+    Half-open span ``[start, end)`` over the *original* text. ``methods`` records
+    which detector stages fired (used by the voting gate). ``confidence`` is set
+    by the pipeline after voting. ``accepted`` marks whether it will be replaced
+    (vs. sent to the review queue).
+    """
+
+    start: int
+    end: int
+    text: str
+    entity_type: str
+    methods: Set[str] = field(default_factory=set)
+    confidence: float = 0.0
+    accepted: bool = False
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+    def overlaps(self, other: "Detection") -> bool:
+        return self.start < other.end and other.start < self.end
+
+    def __len__(self) -> int:
+        return self.end - self.start