verifydoc 0.1.0__py3-none-any.whl

verifydoc/__init__.py

@@ -0,0 +1,16 @@
+"""VerifyDoc: a trust layer for document -> structured-JSON extraction."""
+
+from verifydoc.pipeline import VerifiedResult, verify
+from verifydoc.types import Document, FieldGold, FieldPrediction, Grounding, Schema
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Document",
+    "FieldGold",
+    "FieldPrediction",
+    "Grounding",
+    "Schema",
+    "VerifiedResult",
+    "verify",
+]

verifydoc/adapters/__init__.py

@@ -0,0 +1,33 @@
+"""Extractor adapters. Golden rule #1: all model-specific code lives here.
+
+Nothing outside this package may import a model SDK; adding a new extractor
+is one new file implementing ``ExtractorAdapter``.
+"""
+
+from verifydoc.adapters.base import ExtractorAdapter
+from verifydoc.adapters.mock import MockAdapter
+from verifydoc.adapters.text_search import TextSearchAdapter
+
+__all__ = ["ExtractorAdapter", "MockAdapter", "TextSearchAdapter", "get_adapter"]
+
+_REGISTRY = {
+    "mock": "verifydoc.adapters.mock:MockAdapter",
+    "text-search": "verifydoc.adapters.text_search:TextSearchAdapter",
+    "paddleocr-vl": "verifydoc.adapters.paddleocr_vl:PaddleOCRVLAdapter",
+    "dots-ocr": "verifydoc.adapters.dots_ocr:DotsOCRAdapter",
+    "docling": "verifydoc.adapters.docling:DoclingAdapter",
+    "api-vlm": "verifydoc.adapters.api_vlm:APIVLMAdapter",
+}
+
+
+def get_adapter(name: str, **kwargs: object) -> ExtractorAdapter:
+    """Instantiate a registered adapter by CLI name (lazy import)."""
+    import importlib
+    from typing import cast
+
+    if name not in _REGISTRY:
+        raise ValueError(f"unknown adapter {name!r}; available: {sorted(_REGISTRY)}")
+    module_name, _, class_name = _REGISTRY[name].partition(":")
+    module = importlib.import_module(module_name)
+    adapter_cls = getattr(module, class_name)
+    return cast(ExtractorAdapter, adapter_cls(**kwargs))

verifydoc/adapters/_ocr_common.py

@@ -0,0 +1,80 @@
+"""Shared OCR-token plumbing for local OCR adapters (PaddleOCR-VL, dots.ocr).
+
+OCR engines return (text, bbox, recognition-score) tokens per page. This
+module clusters tokens into reading-order lines, builds a text-layer
+``Document``, and lets the shared field-finding heuristic run on top —
+attaching each token's recognition score as ``token_logprobs`` so the
+token-prob confidence signal works for local OCR models.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from verifydoc.adapters.text_search import TextSearchAdapter
+from verifydoc.types import Document, FieldPrediction, Page, Schema, Word
+
+
+@dataclass
+class OCRToken:
+    """One recognized token: text, normalized bbox, recognition score in (0, 1]."""
+
+    text: str
+    bbox: tuple[float, float, float, float]
+    score: float
+    page: int = 0
+
+
+def document_from_ocr_tokens(doc_id: str, tokens: list[OCRToken]) -> Document:
+    """Cluster OCR tokens into lines (by vertical overlap) and build a Document."""
+    pages: dict[int, list[OCRToken]] = {}
+    for tok in tokens:
+        pages.setdefault(tok.page, []).append(tok)
+
+    out_pages = []
+    for page_no in sorted(pages):
+        toks = sorted(pages[page_no], key=lambda t: (t.bbox[1], t.bbox[0]))
+        lines: list[list[OCRToken]] = []
+        for tok in toks:
+            placed = False
+            for line in lines:
+                y0 = sum(t.bbox[1] for t in line) / len(line)
+                y1 = sum(t.bbox[3] for t in line) / len(line)
+                mid = (tok.bbox[1] + tok.bbox[3]) / 2
+                if y0 <= mid <= y1:
+                    line.append(tok)
+                    placed = True
+                    break
+            if not placed:
+                lines.append([tok])
+        for line in lines:
+            line.sort(key=lambda t: t.bbox[0])
+        text = "\n".join(" ".join(t.text for t in line) for line in lines)
+        words = [Word(text=t.text, bbox=t.bbox) for line in lines for t in line]
+        out_pages.append(Page(page=page_no, width=1.0, height=1.0, text=text, words=words))
+    return Document(doc_id=doc_id, pages=out_pages)
+
+
+def predictions_from_ocr_tokens(
+    doc_id: str, tokens: list[OCRToken], schema: Schema
+) -> list[FieldPrediction]:
+    """Field predictions from OCR tokens: line clustering + label search +
+    per-field token log-scores for the token-prob confidence signal."""
+    doc = document_from_ocr_tokens(doc_id, tokens)
+    preds = TextSearchAdapter().extract(doc, schema)
+    by_text: dict[str, list[float]] = {}
+    for tok in tokens:
+        by_text.setdefault(tok.text.casefold(), []).append(tok.score)
+    out = []
+    for pred in preds:
+        logprobs = [
+            math.log(max(1e-6, min(1.0, by_text[part.casefold()][0])))
+            for part in str(pred.value).split()
+            if part.casefold() in by_text
+        ]
+        meta = dict(pred.meta)
+        if logprobs:
+            meta["token_logprobs"] = logprobs
+        out.append(pred.model_copy(update={"meta": meta}))
+    return out

verifydoc/adapters/api_vlm.py

@@ -0,0 +1,97 @@
+"""API-VLM adapter (comparison rows only; local models are the defaults).
+
+Prompts a vision-language model API for schema-conforming JSON where every
+leaf carries a 0-1 self-assessed confidence — the *verbalized* signal. The
+client is injectable, so unit tests run with a fake and no network
+(golden rule #5); without an injected client the Anthropic SDK is used.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol
+
+from verifydoc.adapters.base import ExtractorAdapter
+from verifydoc.types import Document, FieldPrediction, Schema, flatten_json
+
+_SYSTEM = (
+    "You extract structured data from documents. Reply with ONLY a JSON object "
+    "matching the requested schema, where every leaf value is replaced by "
+    '{"value": ..., "confidence": <float 0-1 honestly reflecting P(correct)>}.'
+)
+
+
+class CompletionClient(Protocol):
+    """Minimal client surface so tests can inject a fake."""
+
+    def complete(self, system: str, prompt: str) -> str: ...
+
+
+class APIVLMAdapter(ExtractorAdapter):
+    name = "api-vlm"
+
+    def __init__(
+        self,
+        client: CompletionClient | None = None,
+        model: str = "claude-sonnet-5",
+    ) -> None:
+        self._client = client
+        self._model = model
+
+    def extract(self, doc: Document, schema: Schema) -> list[FieldPrediction]:
+        text = "\n\f\n".join(page.text or "" for page in doc.pages)
+        prompt = (
+            f"Schema (JSON Schema):\n{json.dumps(schema.raw)}\n\n"
+            f"Document text:\n{text}\n\n"
+            "Extract every schema field you can find."
+        )
+        raw = self._complete(_SYSTEM, prompt)
+        return self._parse(raw)
+
+    def _complete(self, system: str, prompt: str) -> str:
+        if self._client is not None:
+            return self._client.complete(system, prompt)
+        return self._anthropic_complete(system, prompt)  # pragma: no cover - network
+
+    def _anthropic_complete(self, system: str, prompt: str) -> str:  # pragma: no cover
+        try:
+            import anthropic
+        except ImportError as exc:
+            raise ImportError(
+                "APIVLMAdapter without an injected client requires: pip install anthropic"
+            ) from exc
+        response = anthropic.Anthropic().messages.create(
+            model=self._model,
+            max_tokens=4096,
+            system=system,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return str(response.content[0].text)
+
+    @staticmethod
+    def _parse(raw: str) -> list[FieldPrediction]:
+        """Parse {leaf: {value, confidence}} JSON into predictions."""
+        start, end = raw.find("{"), raw.rfind("}")
+        if start == -1 or end <= start:
+            return []
+        try:
+            obj: Any = json.loads(raw[start : end + 1])
+        except json.JSONDecodeError:
+            return []
+        flat = flatten_json(obj)
+        by_field: dict[str, dict[str, Any]] = {}
+        for path, value in flat.items():
+            if path.endswith(".value"):
+                by_field.setdefault(path[: -len(".value")], {})["value"] = value
+            elif path.endswith(".confidence"):
+                by_field.setdefault(path[: -len(".confidence")], {})["confidence"] = value
+        preds = []
+        for path, parts in by_field.items():
+            if "value" not in parts:
+                continue
+            verbalized = parts.get("confidence")
+            meta = {"verbalized_confidence": float(verbalized)} if verbalized is not None else {}
+            preds.append(
+                FieldPrediction(path=path, value=parts["value"], confidence=0.5, meta=meta)
+            )
+        return preds

verifydoc/adapters/base.py

@@ -0,0 +1,31 @@
+"""The ExtractorAdapter interface: extract(doc, schema) -> list[FieldPrediction]."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from verifydoc.types import Document, FieldPrediction, Schema
+
+
+class ExtractorAdapter(ABC):
+    """Wraps one extraction model behind a model-agnostic interface.
+
+    Adapters emit raw predictions (values + whatever raw signals they have in
+    ``meta``); confidence, calibration, grounding, and abstention are applied
+    by later stages, never inside an adapter.
+    """
+
+    name: str = "adapter"
+
+    @abstractmethod
+    def extract(self, doc: Document, schema: Schema) -> list[FieldPrediction]:
+        """Extract one prediction per schema leaf found in the document."""
+
+    def extract_samples(
+        self, doc: Document, schema: Schema, k: int = 1
+    ) -> list[list[FieldPrediction]]:
+        """k independent runs for self-consistency; override when the model
+        supports cheaper native sampling (e.g. temperature > 0 decoding)."""
+        if k < 1:
+            raise ValueError("k must be >= 1")
+        return [self.extract(doc, schema) for _ in range(k)]

verifydoc/adapters/docling.py

@@ -0,0 +1,45 @@
+"""Docling/MinerU output adapter: reuse a parse you already ran.
+
+Consumes either a live ``docling`` conversion (SDK installed) or an exported
+markdown/text file from Docling/MinerU/Marker, then runs the shared
+field-finding heuristic over the parsed text.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from verifydoc.adapters.base import ExtractorAdapter
+from verifydoc.adapters.text_search import TextSearchAdapter
+from verifydoc.ingest import document_from_text
+from verifydoc.types import Document, FieldPrediction, Schema
+
+
+class DoclingAdapter(ExtractorAdapter):
+    name = "docling"
+
+    def __init__(self, parsed_output: str | Path | None = None) -> None:
+        """``parsed_output``: path to an exported markdown/text parse. When
+        omitted, the docling SDK is used to convert the source directly."""
+        self._parsed_output = Path(parsed_output) if parsed_output is not None else None
+
+    def extract(self, doc: Document, schema: Schema) -> list[FieldPrediction]:
+        if self._parsed_output is not None:
+            text = self._parsed_output.read_text(encoding="utf-8")
+        else:  # pragma: no cover - needs docling SDK
+            text = self._convert_with_sdk(doc)
+        parsed_doc = document_from_text(doc.doc_id, text.split("\f"))
+        return TextSearchAdapter().extract(parsed_doc, schema)
+
+    @staticmethod
+    def _convert_with_sdk(doc: Document) -> str:  # pragma: no cover - needs docling SDK
+        try:
+            from docling.document_converter import DocumentConverter
+        except ImportError as exc:
+            raise ImportError(
+                "DoclingAdapter without parsed_output requires docling: pip install docling"
+            ) from exc
+        if doc.source_path is None:
+            raise ValueError("document has no source_path for docling conversion")
+        result = DocumentConverter().convert(doc.source_path)
+        return str(result.document.export_to_markdown())

verifydoc/adapters/dots_ocr.py

@@ -0,0 +1,66 @@
+"""dots.ocr adapter (local, single-GPU second extractor).
+
+Requires the dots.ocr weights served via transformers; see
+https://github.com/rednote-hilab/dots.ocr. SDK use is isolated here; parsed
+layout tokens go through the shared ``_ocr_common`` pathway.
+"""
+
+from __future__ import annotations
+
+import json
+
+from verifydoc.adapters._ocr_common import OCRToken, predictions_from_ocr_tokens
+from verifydoc.adapters.base import ExtractorAdapter
+from verifydoc.types import Document, FieldPrediction, Schema
+
+_PROMPT = "Please output the layout information from the image, including text and bbox."
+
+
+class DotsOCRAdapter(ExtractorAdapter):
+    name = "dots-ocr"
+
+    def __init__(self, model_id: str = "rednote-hilab/dots.ocr") -> None:  # pragma: no cover
+        try:
+            import torch  # noqa: F401
+            from transformers import AutoModelForCausalLM, AutoProcessor
+        except ImportError as exc:
+            raise ImportError(
+                "DotsOCRAdapter requires torch + transformers: " "pip install torch transformers"
+            ) from exc
+        self._model = AutoModelForCausalLM.from_pretrained(
+            model_id, trust_remote_code=True, torch_dtype="auto", device_map="auto"
+        )
+        self._processor = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)
+
+    def extract(self, doc: Document, schema: Schema) -> list[FieldPrediction]:  # pragma: no cover
+        tokens: list[OCRToken] = []
+        for page in doc.pages:
+            if page.image_path is None:
+                continue
+            raw = self._generate(page.image_path)
+            for item in json.loads(raw):
+                x0, y0, x1, y1 = item["bbox"]
+                tokens.append(
+                    OCRToken(
+                        text=item.get("text", ""),
+                        bbox=(
+                            x0 / page.width,
+                            y0 / page.height,
+                            x1 / page.width,
+                            y1 / page.height,
+                        ),
+                        score=float(item.get("score", 0.9)),
+                        page=page.page,
+                    )
+                )
+        return predictions_from_ocr_tokens(doc.doc_id, tokens, schema)
+
+    def _generate(self, image_path: str) -> str:  # pragma: no cover
+        from PIL import Image
+
+        image = Image.open(image_path)
+        inputs = self._processor(text=_PROMPT, images=image, return_tensors="pt").to(
+            self._model.device
+        )
+        output = self._model.generate(**inputs, max_new_tokens=4096)
+        return str(self._processor.batch_decode(output, skip_special_tokens=True)[0])

verifydoc/adapters/mock.py

@@ -0,0 +1,95 @@
+"""Mock adapter: canned or noisy predictions for tests and the synthetic benchmark.
+
+No network, no model. Two modes:
+- canned: a mapping of doc_id -> predictions, returned verbatim;
+- noisy: given gold fields per doc, corrupt/omit/hallucinate at seeded rates
+  to simulate a realistic extractor for the benchmark harness.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+
+from verifydoc.adapters.base import ExtractorAdapter
+from verifydoc.types import Document, FieldGold, FieldPrediction, Schema
+
+
+class MockAdapter(ExtractorAdapter):
+    name = "mock"
+
+    def __init__(
+        self,
+        canned: dict[str, list[FieldPrediction]] | None = None,
+        gold: dict[str, list[FieldGold]] | None = None,
+        error_rate: float = 0.15,
+        omit_rate: float = 0.05,
+        hallucinate_rate: float = 0.05,
+        seed: int = 0,
+    ) -> None:
+        self._canned = canned or {}
+        self._gold = gold or {}
+        self.error_rate = error_rate
+        self.omit_rate = omit_rate
+        self.hallucinate_rate = hallucinate_rate
+        self._rng = random.Random(seed)
+
+    def extract(self, doc: Document, schema: Schema) -> list[FieldPrediction]:
+        if doc.doc_id in self._canned:
+            return [p.model_copy(deep=True) for p in self._canned[doc.doc_id]]
+        if doc.doc_id in self._gold:
+            return self._noisy(self._gold[doc.doc_id])
+        return []
+
+    def _noisy(self, golds: list[FieldGold]) -> list[FieldPrediction]:
+        rng = self._rng
+        preds: list[FieldPrediction] = []
+        for gold in golds:
+            roll = rng.random()
+            if roll < self.omit_rate:
+                continue
+            correct = roll >= self.omit_rate + self.error_rate
+            value = gold.value if correct else self._corrupt(gold)
+            preds.append(
+                FieldPrediction(
+                    path=gold.path, value=value, confidence=0.5, meta=self._signals(correct)
+                )
+            )
+        if golds and rng.random() < self.hallucinate_rate:
+            preds.append(
+                FieldPrediction(
+                    path=f"spurious_{rng.randrange(1000)}",
+                    value="ghost",
+                    confidence=0.5,
+                    meta=self._signals(False),
+                )
+            )
+        return preds
+
+    def _signals(self, correct: bool) -> dict[str, object]:
+        """Simulated raw signals with realistic pathologies: verbalized is
+        inflated regardless of correctness (the RLHF failure mode); token
+        scores carry weak-but-real signal."""
+        rng = self._rng
+        verbalized = min(1.0, max(0.0, 0.9 + rng.uniform(-0.05, 0.08)))
+        base = 0.97 if correct else 0.90
+        logprobs = [math.log(min(1.0, max(0.05, base + rng.gauss(0.0, 0.03)))) for _ in range(3)]
+        return {"verbalized_confidence": verbalized, "token_logprobs": logprobs}
+
+    def _corrupt(self, gold: FieldGold) -> object:
+        """Silently-wrong value: digit swaps for numbers, char noise for text."""
+        rng = self._rng
+        text = str(gold.value)
+        if gold.scoring == "numeric":
+            digits = [ch for ch in text if ch.isdigit()]
+            if len(digits) >= 2:
+                chars = list(text)
+                positions = [i for i, ch in enumerate(chars) if ch.isdigit()]
+                i, j = rng.sample(positions, 2)
+                chars[i], chars[j] = chars[j], chars[i]
+                return "".join(chars)
+            return text + "0"
+        if len(text) >= 2:
+            i = rng.randrange(len(text) - 1)
+            return text[:i] + text[i + 1] + text[i] + text[i + 2 :]
+        return text + "x"

verifydoc/adapters/paddleocr_vl.py

@@ -0,0 +1,50 @@
+"""PaddleOCR-VL adapter (local, single-GPU default extractor).
+
+Requires ``pip install paddleocr`` and a GPU (or slow CPU). All SDK use is
+isolated here; the token -> field mapping is the shared, unit-tested
+``_ocr_common`` pathway.
+"""
+
+from __future__ import annotations
+
+from verifydoc.adapters._ocr_common import OCRToken, predictions_from_ocr_tokens
+from verifydoc.adapters.base import ExtractorAdapter
+from verifydoc.types import Document, FieldPrediction, Schema
+
+
+class PaddleOCRVLAdapter(ExtractorAdapter):
+    name = "paddleocr-vl"
+
+    def __init__(self, lang: str = "en") -> None:  # pragma: no cover - needs SDK
+        try:
+            from paddleocr import PaddleOCR
+        except ImportError as exc:
+            raise ImportError(
+                "PaddleOCRVLAdapter requires the paddleocr package: pip install paddleocr"
+            ) from exc
+        self._ocr = PaddleOCR(use_angle_cls=True, lang=lang, show_log=False)
+
+    def extract(self, doc: Document, schema: Schema) -> list[FieldPrediction]:  # pragma: no cover
+        tokens: list[OCRToken] = []
+        for page in doc.pages:
+            if page.image_path is None:
+                continue
+            result = self._ocr.ocr(page.image_path, cls=True)
+            for line in result[0] or []:
+                quad, (text, score) = line
+                xs = [pt[0] for pt in quad]
+                ys = [pt[1] for pt in quad]
+                tokens.append(
+                    OCRToken(
+                        text=text,
+                        bbox=(
+                            min(xs) / page.width,
+                            min(ys) / page.height,
+                            max(xs) / page.width,
+                            max(ys) / page.height,
+                        ),
+                        score=float(score),
+                        page=page.page,
+                    )
+                )
+        return predictions_from_ocr_tokens(doc.doc_id, tokens, schema)

verifydoc/adapters/text_search.py

@@ -0,0 +1,53 @@
+"""Dependency-free heuristic extractor: label/value search over the text layer.
+
+The honest floor baseline: for each schema leaf, find a line whose text
+contains the leaf's label ("invoice_id" -> "invoice id") and take what follows
+the separator as the value. Real OCR/VLM adapters reuse this field-finding on
+top of their own text layers; the paper reports it as the no-model baseline.
+
+# DECISION: the heuristic baseline skips array leaves (``items[].price``) —
+# repeating-group detection is extractor territory, not a text heuristic's;
+# array handling is exercised through the mock and model adapters.
+"""
+
+from __future__ import annotations
+
+from verifydoc.adapters.base import ExtractorAdapter
+from verifydoc.types import Document, FieldPrediction, Schema
+
+
+class TextSearchAdapter(ExtractorAdapter):
+    name = "text-search"
+
+    def extract(self, doc: Document, schema: Schema) -> list[FieldPrediction]:
+        preds: list[FieldPrediction] = []
+        for leaf in schema.leaves:
+            if "[]" in leaf.path:
+                continue
+            label = leaf.path.split(".")[-1].replace("_", " ").casefold()
+            found = self._find(doc, label)
+            if found is not None:
+                value, page_no, line = found
+                preds.append(
+                    FieldPrediction(
+                        path=leaf.path,
+                        value=value,
+                        confidence=0.5,
+                        meta={"source_page": page_no, "source_line": line},
+                    )
+                )
+        return preds
+
+    @staticmethod
+    def _find(doc: Document, label: str) -> tuple[str, int, str] | None:
+        for page in doc.pages:
+            if not page.text:
+                continue
+            for line in page.text.split("\n"):
+                idx = line.casefold().find(label)
+                if idx == -1:
+                    continue
+                value = line[idx + len(label) :].lstrip(" \t:—–-").strip()
+                if value:
+                    return value, page.page, line
+        return None

verifydoc/calibration/__init__.py

@@ -0,0 +1,20 @@
+"""Post-hoc calibrators (PROJECT.md §5.G), fit ONLY on the calibration split."""
+
+from verifydoc.calibration.base import Calibrator
+from verifydoc.calibration.conformal import ConformalAbstention
+from verifydoc.calibration.histogram import HistogramBinning
+from verifydoc.calibration.isotonic import IsotonicCalibrator
+from verifydoc.calibration.platt import PlattScaling
+from verifydoc.calibration.splits import assert_disjoint, split_calibration
+from verifydoc.calibration.temperature import TemperatureScaling
+
+__all__ = [
+    "Calibrator",
+    "ConformalAbstention",
+    "HistogramBinning",
+    "IsotonicCalibrator",
+    "PlattScaling",
+    "TemperatureScaling",
+    "assert_disjoint",
+    "split_calibration",
+]

verifydoc/calibration/base.py

@@ -0,0 +1,56 @@
+"""Calibrator interface: fit on the calibration split, transform anywhere else.
+
+Golden rule #4: calibration parameters are NEVER tuned on test data. Fit takes
+the calibration split's (confidence, correctness) pairs; transform maps raw
+confidences to calibrated ones.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+import numpy as np
+
+_EPS = 1e-7
+
+
+class Calibrator(ABC):
+    """Post-hoc mapping from raw confidence to calibrated probability."""
+
+    _fitted: bool = False
+
+    def fit(self, conf: Sequence[float], correct: Sequence[int]) -> Calibrator:
+        c = np.asarray(conf, dtype=float)
+        y = np.asarray(correct, dtype=float)
+        if c.shape != y.shape or c.ndim != 1 or c.size == 0:
+            raise ValueError("conf and correct must be 1-D, equal-length, non-empty")
+        if ((c < 0) | (c > 1)).any():
+            raise ValueError("confidences must lie in [0, 1]")
+        self._fit(c, y)
+        self._fitted = True
+        return self
+
+    def transform(self, conf: Sequence[float]) -> np.ndarray:
+        if not self._fitted:
+            raise RuntimeError(f"{type(self).__name__} must be fit on the calibration split first")
+        c = np.asarray(conf, dtype=float)
+        return np.clip(self._transform(c), 0.0, 1.0)
+
+    @abstractmethod
+    def _fit(self, conf: np.ndarray, correct: np.ndarray) -> None: ...
+
+    @abstractmethod
+    def _transform(self, conf: np.ndarray) -> np.ndarray: ...
+
+
+def logit(p: np.ndarray) -> np.ndarray:
+    """Log-odds with clipping so 0/1 confidences stay finite."""
+    p = np.clip(p, _EPS, 1.0 - _EPS)
+    return np.log(p / (1.0 - p))
+
+
+def sigmoid(z: np.ndarray) -> np.ndarray:
+    from scipy.special import expit  # numerically stable for extreme log-odds
+
+    return np.asarray(expit(z), dtype=float)