Package the verified-text draft annotator as text_draft

Move the draft-annotation logic (PaddleOCR line detection, word-box
grouping, three script-chosen recognition engines, crop-jitter
stability gate) from the evaluation-only scripts into the installable
package, with lazy paddle imports and a text-draft extra (CPU, no
torch). draft_text_lines() returns accepted (crop-stable, NEVER
ground-truth-correct - precision on the reference posters was 90.0% /
94.4%) and rejected proposals; source_pixel_sha256 is re-exported for
manifest building. scripts/infer_text_lines.py now dogfoods the
package module instead of loading the eval script by path.

docs/python-api.md

@@ -621,6 +621,29 @@ Content Provenance API, 2026-08-19 - detected x6 with the anchor, clean x6
 without it, controls and base outputs validated in the same sessions). Pass
 `fidelity_anchor=True` to reproduce the 0.27.0 research behavior.
 
+### Drafting manifest lines
+
+`remove_ai_watermarks.text_draft` proposes lines for a manifest; it never
+produces verified ones:
+
+```python
+from remove_ai_watermarks.text_draft import draft_text_lines
+
+draft = draft_text_lines(Path("watermarked.png"))
+for line in draft.accepted:
+    print(line.box, line.script, line.min_score, line.text)
+```
+
+Install `remove-ai-watermarks[text-draft]` (CPU, no torch: PaddleOCR detection
+plus three script-chosen recognition engines). A line lands in `accepted` only
+when three crop paddings normalize identically and every confidence clears
+`min_score` (default 0.85); `accepted` means crop-stable, NOT ground-truth-
+correct - on the reference posters the draft's exact-text precision was 90.0%
+and 94.4% because high-confidence OCR still lost punctuation. Every accepted
+line needs a human yes/no before a manifest may claim `verified: true`.
+`source_pixel_sha256` is re-exported here for building the manifest's
+pixel-binding hash against the exact source the engine will decode.
+
 `remove_watermark` takes strength, seed, tiling, resolution, and postprocessing
 controls. It takes no model id, step count or guidance scale, and neither does the
 constructor: each profile pins its model stack, its per-stage schedule and CFG

pyproject.toml

@@ -4,7 +4,7 @@
 # on it, including the ComfyUI node package. The console script below carries
 # the same weight, since users have it on PATH.
 name = "remove-ai-watermarks"
-version = "0.27.2"
+version = "0.28.0"
 description = "AI watermark remover for visible, invisible, and provenance marks in images and video"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
@@ -125,6 +125,14 @@ qwen-zimage = [
 text-restoration = [
     "remove-ai-watermarks[qwen-zimage,lama]",
 ]
+# Draft-only OCR proposals for verified-text manifests. CPU, no torch:
+# PaddleOCR detection plus three script-chosen recognition engines. The models
+# download on first use and are cached by huggingface_hub; never bundled.
+text-draft = [
+    "paddleocr>=3.3.3",
+    "paddlepaddle>=3.0.0",
+    "huggingface-hub>=0.20.0",
+]
 # Adobe TrustMark decoder -- the open, keyless watermark behind Adobe Durable
 # Content Credentials (soft-binding alg ``com.adobe.trustmark.P``). Optional
 # because it pulls torch and downloads model weights on first use. identify()

scripts/infer_text_lines.py

@@ -21,14 +21,11 @@ changes under crop jitter or whose minimum confidence is below the threshold.
 
 from __future__ import annotations
 
-import importlib.util
 import json
 import logging
 import os
 import sys
-import unicodedata
 from pathlib import Path
-from typing import Any
 
 import click
 import numpy as np
@@ -37,38 +34,15 @@ from PIL import Image
 log = logging.getLogger(__name__)
 ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(ROOT))
-RESTORATION_SCRIPT = ROOT / "scripts/selective_text_restoration.py"
 
-from scripts._text_eval import normalize_text  # noqa: E402
-
-
-def _load_restoration_module() -> Any:
-    spec = importlib.util.spec_from_file_location("selective_text_restoration_for_inference", RESTORATION_SCRIPT)
-    if spec is None or spec.loader is None:
-        raise RuntimeError(f"unable to load {RESTORATION_SCRIPT}")
-    module = importlib.util.module_from_spec(spec)
-    sys.modules[spec.name] = module
-    spec.loader.exec_module(module)
-    return module
-
-
-def _has_script(text: str, script: str) -> bool:
-    return any(script in unicodedata.name(character, "") for character in text)
-
-
-def choose_language(probes: dict[str, tuple[str, float]]) -> str:
-    if _has_script(probes["ch"][0], "CJK"):
-        return "ch"
-    if _has_script(probes["ru"][0], "CYRILLIC"):
-        return "ru"
-    return "en"
-
-
-def stable_recognition(reads: list[tuple[str, float]], min_score: float = 0.85) -> str | None:
-    normalized = {normalize_text(text) for text, _score in reads}
-    if len(normalized) != 1 or min(score for _text, score in reads) < min_score:
-        return None
-    return reads[0][0]
+# Dogfoods the packaged draft API (remove_ai_watermarks.text_draft); this script
+# keeps only the CLI wrapper so the package stays the one home for the logic.
+from remove_ai_watermarks.text_draft import (  # noqa: E402
+    _detect_line_boxes,
+    _recognize,
+    choose_language,
+    stable_recognition,
+)
 
 
 @click.command()
@@ -81,7 +55,6 @@ def main(source: Path, out: Path, min_score: float) -> None:
     os.environ["PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK"] = "True"
     from paddleocr import PaddleOCR, TextRecognition
 
-    restoration = _load_restoration_module()
     source_rgb = np.asarray(Image.open(source).convert("RGB"))
     detector = PaddleOCR(
         lang="ch",
@@ -94,19 +67,17 @@ def main(source: Path, out: Path, min_score: float) -> None:
         "ru": TextRecognition(model_name="eslav_PP-OCRv5_mobile_rec"),
         "ch": TextRecognition(model_name="PP-OCRv5_server_rec"),
     }
-    boxes = restoration.detect_line_boxes(detector, source_rgb)
+    boxes = _detect_line_boxes(detector, source_rgb)
     accepted = []
     rejected = []
     for box in boxes:
         probes = {}
         for language, engine in engines.items():
             script = "cjk" if language == "ch" else "alphabetic"
-            line = restoration.TextLine(box, "", script)
-            probes[language] = restoration._recognize(engine, source_rgb, line, 0.1)
+            probes[language] = _recognize(engine, source_rgb, box, script, 0.1)
         language = choose_language(probes)
         script = "cjk" if language == "ch" else "alphabetic"
-        line = restoration.TextLine(box, "", script)
-        reads = [restoration._recognize(engines[language], source_rgb, line, ratio) for ratio in (0.08, 0.12, 0.2)]
+        reads = [_recognize(engines[language], source_rgb, box, script, ratio) for ratio in (0.08, 0.12, 0.2)]
         text = stable_recognition(reads, min_score)
         result = {
             "box": box,

src/remove_ai_watermarks/__init__.py

@@ -32,7 +32,7 @@ _os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
 _warnings.filterwarnings("ignore", message=r".*ImageProcessorFast.*")
 
 
-__version__ = "0.27.2"
+__version__ = "0.28.0"
 
 __all__ = [
     "BatchSummary",

src/remove_ai_watermarks/text_draft.py

@@ -0,0 +1,281 @@
+"""Draft operator-verifiable text lines for verified-text manifests.
+
+Proposal-only OCR: PaddleOCR detection plus three script-chosen recognition
+engines (Latin / Cyrillic / CJK), accepted only when three crop paddings
+normalize identically and every confidence clears the floor. ``accepted``
+means crop-stable, NEVER ground-truth-correct: on the reference posters the
+draft's exact-text precision was 90.0% and 94.4% because high-confidence OCR
+still lost punctuation (one English comma dropped, one ideographic comma
+replaced with ASCII). Every accepted line needs a human yes/no before it may
+enter a manifest with ``verified: true``.
+
+Heavy imports (paddle, and the numpy/cv2/PIL pixel stack) stay inside the
+call so importing this module costs nothing without the ``text-draft`` extra;
+``draft_available()`` reports whether the extra is installed.
+"""
+
+# pyright: reportUnknownMemberType=false, reportUnknownArgumentType=false, reportUnknownVariableType=false, reportUnknownParameterType=false, reportMissingTypeArgument=false, reportMissingTypeStubs=false, reportMissingImports=false, reportArgumentType=false, reportAssignmentType=false, reportReturnType=false, reportCallIssue=false, reportIndexIssue=false, reportOperatorIssue=false
+
+from __future__ import annotations
+
+import unicodedata
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from remove_ai_watermarks._internal.text_restoration import source_pixel_sha256
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = [
+    "DraftLine",
+    "RejectedLine",
+    "TextDraft",
+    "choose_language",
+    "draft_available",
+    "draft_text_lines",
+    "group_word_boxes",
+    "source_pixel_sha256",
+    "stable_recognition",
+]
+
+# Crop paddings probed per line: recognition must be invariant across them.
+JITTER_RATIOS: tuple[float, ...] = (0.08, 0.12, 0.2)
+DETECT_SCORE_FLOOR = 0.5
+
+
+@dataclass(frozen=True)
+class DraftLine:
+    """One crop-stable proposal. ``accepted`` means stable, not correct."""
+
+    box: tuple[int, int, int, int]
+    text: str
+    script: str
+    language: str
+    min_score: float
+
+
+@dataclass(frozen=True)
+class RejectedLine:
+    """A detected line whose recognition was unstable or low-confidence."""
+
+    box: tuple[int, int, int, int]
+    script: str
+    language: str
+    reads: tuple[tuple[str, float], ...]
+
+
+@dataclass(frozen=True)
+class TextDraft:
+    """The full proposal set for one image."""
+
+    accepted: tuple[DraftLine, ...] = ()
+    rejected: tuple[RejectedLine, ...] = ()
+
+
+def normalize_text(text: str) -> str:
+    """Normalize text for layout-independent comparison (casefold + no spaces)."""
+    return "".join(unicodedata.normalize("NFC", text).casefold().split())
+
+
+def _has_script(text: str, script: str) -> bool:
+    return any(script in unicodedata.name(character, "") for character in text)
+
+
+def choose_language(probes: dict[str, tuple[str, float]]) -> str:
+    """Pick ``ch``/``ru``/``en`` from what each probe engine actually read."""
+    if _has_script(probes["ch"][0], "CJK"):
+        return "ch"
+    if _has_script(probes["ru"][0], "CYRILLIC"):
+        return "ru"
+    return "en"
+
+
+def stable_recognition(reads: list[tuple[str, float]], min_score: float = 0.85) -> str | None:
+    """The proposal text when every read normalizes identically and clears the floor."""
+    normalized = {normalize_text(text) for text, _score in reads}
+    if len(normalized) != 1 or min(score for _text, score in reads) < min_score:
+        return None
+    return reads[0][0]
+
+
+def _vertical_overlap_ratio(left: tuple[int, int, int, int], right: tuple[int, int, int, int]) -> float:
+    overlap = max(0, min(left[3], right[3]) - max(left[1], right[1]))
+    return overlap / max(1, min(left[3] - left[1], right[3] - right[1]))
+
+
+def _row_center(box: tuple[int, int, int, int]) -> float:
+    return (box[1] + box[3]) / 2
+
+
+def group_word_boxes(boxes: list[tuple[int, int, int, int]]) -> list[tuple[int, int, int, int]]:
+    """Merge word detections into line boxes by vertical overlap and gap."""
+    groups: list[tuple[int, int, int, int]] = []
+    for box in sorted(boxes, key=lambda item: (_row_center(item), item[0])):
+        matches: list[int] = []
+        for index, group in enumerate(groups):
+            if _vertical_overlap_ratio(box, group) < 0.45:
+                continue
+            horizontal_gap = max(0, max(box[0], group[0]) - min(box[2], group[2]))
+            line_height = min(box[3] - box[1], group[3] - group[1])
+            if horizontal_gap <= max(24, line_height * 3):
+                matches.append(index)
+        if not matches:
+            groups.append(box)
+            continue
+        index = max(matches, key=lambda item: _vertical_overlap_ratio(box, groups[item]))
+        x1, y1, x2, y2 = groups[index]
+        groups[index] = min(x1, box[0]), min(y1, box[1]), max(x2, box[2]), max(y2, box[3])
+    return sorted(groups, key=_row_center)
+
+
+def _recognition_box(
+    box: tuple[int, int, int, int],
+    script: str,
+    width: int,
+    height: int,
+    vertical_pad_ratio: float | None = None,
+) -> tuple[int, int, int, int]:
+    x1, y1, x2, y2 = box
+    line_height = y2 - y1
+    if script == "cjk":
+        left_pad = max(16, round(line_height * 0.2))
+        right_pad = max(16, round(line_height * 0.6))
+        return max(0, x1 - left_pad), y1, min(width, x2 + right_pad), y2
+    pad_x = max(16, line_height)
+    pad_y = max(8, line_height // 3) if vertical_pad_ratio is None else max(8, round(line_height * vertical_pad_ratio))
+    return max(0, x1 - pad_x), max(0, y1 - pad_y), min(width, x2 + pad_x), min(height, y2 + pad_y)
+
+
+def _recognize(
+    engine: Any,
+    image: Any,
+    box: tuple[int, int, int, int],
+    script: str,
+    vertical_pad_ratio: float | None = None,
+) -> tuple[str, float]:
+    import cv2
+
+    height, width = image.shape[:2]
+    x1, y1, x2, y2 = _recognition_box(box, script, width, height, vertical_pad_ratio)
+    crop = image[y1:y2, x1:x2]
+    if crop.shape[0] < 64:
+        scale = 64 / crop.shape[0]
+        crop = cv2.resize(crop, None, fx=scale, fy=scale, interpolation=cv2.INTER_CUBIC)
+    result = next(iter(engine.predict(crop)))
+    return str(result.get("rec_text", "")), float(result.get("rec_score", 0.0))
+
+
+def _detect_line_boxes(engine: Any, source_rgb: Any) -> list[tuple[int, int, int, int]]:
+    import numpy as np
+
+    boxes: list[tuple[int, int, int, int]] = []
+    for page in engine.predict(source_rgb):
+        detected = page.get("rec_boxes", None)
+        if detected is None or len(detected) == 0:
+            detected = page.get("rec_polys", [])
+        for score, raw_box in zip(page.get("rec_scores", []), detected, strict=False):
+            if float(score) < DETECT_SCORE_FLOOR:
+                continue
+            points = np.asarray(raw_box, dtype=np.float32).reshape(-1)
+            if points.size == 4:
+                x1, y1, x2, y2 = points
+            else:
+                points = points.reshape(-1, 2)
+                x1, y1 = points.min(axis=0)
+                x2, y2 = points.max(axis=0)
+            boxes.append((round(float(x1)), round(float(y1)), round(float(x2)), round(float(y2))))
+    return group_word_boxes(boxes)
+
+
+def draft_available() -> bool:
+    """True when the ``text-draft`` extra (paddleocr + paddle) can run."""
+    from remove_ai_watermarks.optional_deps import module_available
+
+    return module_available("paddleocr") and module_available("paddle")
+
+
+def _build_engines() -> tuple[Any, dict[str, Any]]:
+    from paddleocr import PaddleOCR, TextRecognition
+
+    detector = PaddleOCR(
+        lang="ch",
+        use_doc_orientation_classify=False,
+        use_doc_unwarping=False,
+        use_textline_orientation=False,
+    )
+    engines = {
+        "en": TextRecognition(model_name="en_PP-OCRv5_mobile_rec"),
+        "ru": TextRecognition(model_name="eslav_PP-OCRv5_mobile_rec"),
+        "ch": TextRecognition(model_name="PP-OCRv5_server_rec"),
+    }
+    return detector, engines
+
+
+def draft_text_lines(
+    image: Path,
+    *,
+    min_score: float = 0.85,
+    detector: Any | None = None,
+    engines: dict[str, Any] | None = None,
+) -> TextDraft:
+    """Propose verified-text manifest lines for ``image``; never verified ones.
+
+    Args:
+        image: path of the source image (draft boxes are in ITS pixel space).
+        min_score: recognition confidence floor for every jittered read.
+        detector/engines: injectable Paddle objects (tests use fakes); when
+            None they are built from the ``text-draft`` extra, which must be
+            installed (``draft_available()`` reports it).
+
+    Returns:
+        ``TextDraft`` with crop-stable ``accepted`` proposals and unstable
+        ``rejected`` lines. Both lists need human review before any manifest
+        may claim ``verified: true``; accepted means crop-stable, NOT
+        ground-truth-correct.
+    """
+    import os
+
+    import numpy as np
+    from PIL import Image
+
+    if detector is None or engines is None:
+        if not draft_available():
+            raise RuntimeError(
+                "Text drafting requires PaddleOCR. Install: pip install 'remove-ai-watermarks[text-draft]'"
+            )
+        os.environ.setdefault("PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK", "True")
+        detector, engines = _build_engines()
+
+    source_rgb = np.asarray(Image.open(image).convert("RGB"))
+    accepted: list[DraftLine] = []
+    rejected: list[RejectedLine] = []
+    for box in _detect_line_boxes(detector, source_rgb):
+        probes: dict[str, tuple[str, float]] = {}
+        for language, engine in engines.items():
+            script = "cjk" if language == "ch" else "alphabetic"
+            probes[language] = _recognize(engine, source_rgb, box, script, 0.1)
+        language = choose_language(probes)
+        script = "cjk" if language == "ch" else "alphabetic"
+        reads = [_recognize(engines[language], source_rgb, box, script, ratio) for ratio in JITTER_RATIOS]
+        text = stable_recognition(reads, min_score)
+        if text is None:
+            rejected.append(
+                RejectedLine(
+                    box=box,
+                    script=script,
+                    language=language,
+                    reads=tuple((value, score) for value, score in reads),
+                )
+            )
+        else:
+            accepted.append(
+                DraftLine(
+                    box=box,
+                    text=text,
+                    script=script,
+                    language=language,
+                    min_score=min(score for _value, score in reads),
+                )
+            )
+    return TextDraft(accepted=tuple(accepted), rejected=tuple(rejected))

tests/test_text_draft.py

@@ -0,0 +1,141 @@
+"""text_draft: proposal-only OCR for verified-text manifests (no paddle needed)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from PIL import Image
+
+from remove_ai_watermarks.text_draft import (
+    TextDraft,
+    choose_language,
+    draft_available,
+    draft_text_lines,
+    group_word_boxes,
+    stable_recognition,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class TestPureHelpers:
+    def test_choose_language_follows_unicode_script(self):
+        assert choose_language({"ch": ("你好", 0.9), "ru": ("xxx", 0.1), "en": ("yyy", 0.1)}) == "ch"
+        assert choose_language({"ch": ("??", 0.1), "ru": ("привет", 0.9), "en": ("yyy", 0.1)}) == "ru"
+        assert choose_language({"ch": ("??", 0.1), "ru": ("xxx", 0.1), "en": ("hello", 0.9)}) == "en"
+
+    def test_stable_recognition_requires_identical_normalizations(self):
+        # Same text modulo spacing/case (comma kept): stable.
+        assert (
+            stable_recognition([("Hello, World", 0.97), ("hello,world", 0.96), ("HELLO,  WORLD", 0.95)])
+            == "Hello, World"
+        )
+        # Different texts: rejected (None).
+        assert stable_recognition([("Hello", 0.97), ("Hallo", 0.96), ("Hello", 0.95)]) is None
+        # Identical text but one read under the floor: rejected.
+        assert stable_recognition([("Hello", 0.97), ("Hello", 0.60), ("Hello", 0.95)]) is None
+        assert stable_recognition([("Hello", 0.97), ("Hello", 0.96), ("Hello", 0.95)], min_score=0.99) is None
+
+    def test_group_word_boxes_merges_a_line_and_keeps_rows_apart(self):
+        # Two words on one baseline merge; a distant lower line stays separate.
+        merged = group_word_boxes([(10, 100, 60, 140), (70, 100, 120, 140)])
+        assert len(merged) == 1
+        assert merged[0] == (10, 100, 120, 140)
+        apart = group_word_boxes([(10, 100, 60, 140), (10, 300, 60, 340)])
+        assert len(apart) == 2
+
+
+class TestDraftAvailable:
+    def test_returns_a_bool_without_importing_paddle(self):
+        assert isinstance(draft_available(), bool)
+
+
+class _FakeDetector:
+    """Emits Paddle-style pages for one synthetic poster."""
+
+    def __init__(self, boxes: list[tuple[int, int, int, int]]) -> None:
+        self._boxes = boxes
+
+    def predict(self, _image: Any) -> Any:
+        import numpy as np
+
+        yield {
+            "rec_boxes": np.asarray(self._boxes, dtype=np.float32),
+            "rec_scores": [0.99] * len(self._boxes),
+        }
+
+
+class _FakeEngine:
+    """Returns a fixed text at high score regardless of the crop."""
+
+    def __init__(self, text: str) -> None:
+        self._text = text
+
+    def predict(self, _crop: Any) -> Any:
+        yield {"rec_text": self._text, "rec_score": 0.97}
+
+
+class _JitterEngine:
+    """Changes its answer with the crop height - exactly what the gate rejects."""
+
+    def __init__(self, texts: list[str]) -> None:
+        self._texts = texts
+        self._calls = 0
+
+    def predict(self, crop: Any) -> Any:
+        text = self._texts[self._calls % len(self._texts)]
+        self._calls += 1
+        yield {"rec_text": text, "rec_score": 0.97}
+
+
+class TestDraftTextLines:
+    @staticmethod
+    def _poster(tmp_path: Path) -> Path:
+        path = tmp_path / "poster.png"
+        Image.new("RGB", (400, 300), (255, 255, 255)).save(path)
+        return path
+
+    def test_accepts_crop_stable_and_rejects_jittered(self, tmp_path: Path):
+        path = self._poster(tmp_path)
+        stable = _FakeEngine("Invoice 42")
+        jitter = _JitterEngine(["Hello", "Hallo", "Hullo"])
+        # All three probe engines read the same string, so language = en; the
+        # jitter engine then serves as the en engine and flips across crops.
+        draft = draft_text_lines(
+            path,
+            detector=_FakeDetector([(20, 20, 200, 60), (20, 80, 200, 120)]),
+            engines={"en": jitter, "ru": stable, "ch": stable},
+        )
+        assert isinstance(draft, TextDraft)
+        assert len(draft.rejected) == 2
+        assert all(line.language == "en" for line in draft.rejected)
+        assert draft.accepted == ()
+
+    def test_accepted_line_carries_box_text_script_and_floor(self, tmp_path: Path):
+        path = self._poster(tmp_path)
+        engine = _FakeEngine("Total: 1,234.56")
+        draft = draft_text_lines(
+            path,
+            detector=_FakeDetector([(20, 20, 260, 60)]),
+            engines={"en": engine, "ru": engine, "ch": engine},
+        )
+        (line,) = draft.accepted
+        assert line.box == (20, 20, 260, 60)
+        assert line.text == "Total: 1,234.56"
+        assert line.script == "alphabetic"
+        assert line.language == "en"
+        assert line.min_score >= 0.85
+
+    def test_cjk_probe_switches_script_and_language(self, tmp_path: Path):
+        path = self._poster(tmp_path)
+        cjk = _FakeEngine("每天都是一个新的机会。")
+        latin = _FakeEngine("hello")
+        draft = draft_text_lines(
+            path,
+            detector=_FakeDetector([(30, 30, 300, 90)]),
+            engines={"en": latin, "ru": latin, "ch": cjk},
+        )
+        (line,) = draft.accepted
+        assert line.language == "ch"
+        assert line.script == "cjk"