Add 1000 files (ocr-tech/tests/test_audit_limbu_book_missed_line_review_coverage.py ...)
d82db76 verified Download ocr-tech-mps-integration/src/ocrtech/engines.py from prosperious/ocr-projects-archive: direct link, hf CLI and curl.
- Browser
- Download file 130 kB
-
https://huggingface.co/prosperious/ocr-projects-archive/resolve/main/ocr-tech-mps-integration/src/ocrtech/engines.py
- Command line
-
hf download hf://prosperious/ocr-projects-archive/ocr-tech-mps-integration/src/ocrtech/engines.py
-
curl -L -o engines.py https://huggingface.co/prosperious/ocr-projects-archive/resolve/main/ocr-tech-mps-integration/src/ocrtech/engines.py
130 kB
"""Optional OCR engine adapters."""
from __future__ import annotations
import csv
import html
import json
import os
import re
import shutil
import subprocess
import tempfile
from dataclasses import dataclass, field, replace
from html.parser import HTMLParser
from pathlib import Path
from typing import Iterable, Protocol
from .errors import DataValidationError, EngineUnavailableError, ParseError
from .metrics import bbox_iou, edit_distance
from .models import ModelCard, audit_model_card
from .normalization import normalize_ocr_text
from .schemas import BBox, Figure, Page, Table, TableCell, TextLine, validate_confidence
@dataclass(slots=True)
class EngineOutput:
pages: list[Page]
tables: list[Table] = field(default_factory=list)
figures: list[Figure] = field(default_factory=list)
metadata: dict[str, object] = field(default_factory=dict)
@property
def average_confidence(self) -> float | None:
values = [
line.confidence
for page in self.pages
for line in page.text_lines
if line.confidence is not None
]
return sum(values) / len(values) if values else None
class OcrEngine(Protocol):
name: str
def recognize(self, input_path: Path) -> EngineOutput:
"""Recognize an image or document and return page text lines."""
def _synthetic_lines_from_text(text: str, page_index: int = 0) -> list[TextLine]:
lines: list[TextLine] = []
y = 0
for index, raw_line in enumerate(text.splitlines()):
line_text = normalize_ocr_text(raw_line)
if not line_text.strip():
y += 28
continue
line = TextLine(
text=line_text,
bbox=BBox(0, y, max(50, len(line_text) * 9), 22),
confidence=1.0,
page_index=page_index,
line_id=f"p{page_index}-l{index}",
)
lines.append(line)
y += 28
return lines
def sidecar_candidates(input_path: Path) -> list[Path]:
if input_path.is_dir():
return [
input_path / "document.ocr.json",
input_path / "document.txt",
input_path / "document.md",
]
candidates = [
input_path.with_suffix(input_path.suffix + ".ocr.json"),
input_path.with_suffix(".ocr.json"),
input_path.with_suffix(input_path.suffix + ".txt"),
input_path.with_suffix(".txt"),
]
if input_path.suffix.lower() in {".txt", ".md"}:
candidates.insert(0, input_path)
unique: list[Path] = []
for candidate in candidates:
if candidate not in unique:
unique.append(candidate)
return unique
def has_sidecar(input_path: Path) -> bool:
return any(candidate.exists() for candidate in sidecar_candidates(input_path))
def _bundle_page_paths(input_path: Path) -> list[Path]:
if not input_path.is_dir():
return []
allowed_suffixes = {".png", ".jpg", ".jpeg", ".tif", ".tiff", ".bmp", ".webp"}
page_paths = [path for path in sorted(input_path.iterdir()) if path.is_file() and path.suffix.lower() in allowed_suffixes]
if not page_paths:
raise ParseError(f"page bundle directory has no supported image files: {input_path}")
return page_paths
def _pages_from_lines(lines: list[TextLine], *, metadata: dict[str, object] | None = None) -> list[Page]:
grouped: dict[int, list[TextLine]] = {}
for line in lines:
grouped.setdefault(line.page_index, []).append(line)
pages: list[Page] = []
for page_index in sorted(grouped):
pages.append(Page(page_index=page_index, text_lines=grouped[page_index], metadata=dict(metadata or {})))
return pages
def _merge_engine_outputs(outputs: list[EngineOutput], *, engine_name: str) -> EngineOutput:
pages: list[Page] = []
tables: list[Table] = []
figures: list[Figure] = []
metadata: dict[str, object] = {"engine": engine_name}
for output in outputs:
pages.extend(output.pages)
tables.extend(output.tables)
figures.extend(output.figures)
return EngineOutput(pages=pages, tables=tables, figures=figures, metadata=metadata)
class SidecarEngine:
"""Deterministic engine for fixtures and pre-OCR text sidecars."""
name = "sidecar"
def recognize(self, input_path: Path) -> EngineOutput:
for candidate in sidecar_candidates(input_path):
if not candidate.exists():
continue
if candidate.suffix == ".json" or candidate.name.endswith(".ocr.json"):
return self._read_json(candidate)
return self._read_text(candidate)
raise EngineUnavailableError(
f"No OCR sidecar found for {input_path}. Expected one of: "
+ ", ".join(str(path) for path in sidecar_candidates(input_path))
)
def _read_text(self, path: Path) -> EngineOutput:
text = path.read_text(encoding="utf-8")
lines = _synthetic_lines_from_text(text)
page = Page(page_index=0, width=None, height=None, text_lines=lines, metadata={"sidecar_path": str(path)})
return EngineOutput(pages=[page], metadata={"engine": self.name, "sidecar_path": str(path)})
def _read_json(self, path: Path) -> EngineOutput:
try:
data = json.loads(path.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
raise DataValidationError(f"Invalid OCR sidecar JSON {path}: {exc}") from exc
raw_pages = data.get("pages")
if not isinstance(raw_pages, list):
raise DataValidationError(f"OCR sidecar {path} must contain a pages list")
pages: list[Page] = []
for page_index, raw_page in enumerate(raw_pages):
if not isinstance(raw_page, dict):
raise DataValidationError(f"OCR sidecar page {page_index} must be an object")
lines = [
TextLine.from_dict(raw_line, page_index=page_index)
for raw_line in raw_page.get("lines", raw_page.get("text_lines", []))
]
for line_index, line in enumerate(lines):
if line.line_id is None:
line.line_id = f"p{page_index}-l{line_index}"
pages.append(
Page(
page_index=page_index,
width=raw_page.get("width"),
height=raw_page.get("height"),
text_lines=lines,
metadata=dict(raw_page.get("metadata") or {}),
)
)
tables = [Table.from_dict(item) for item in data.get("tables", [])]
figures = [Figure.from_dict(item) for item in data.get("figures", [])]
metadata = dict(data.get("metadata") or {})
metadata.update({"engine": self.name, "sidecar_path": str(path)})
return EngineOutput(pages=pages, tables=tables, figures=figures, metadata=metadata)
class TesseractEngine:
name = "tesseract"
def __init__(self, *, language: str = "nep+eng", psm: int = 6) -> None:
self.language = language
self.psm = psm
self.binary = shutil.which("tesseract")
if self.binary is None:
raise EngineUnavailableError("tesseract binary is not installed or not on PATH")
def recognize(self, input_path: Path) -> EngineOutput:
if input_path.is_dir():
outputs: list[EngineOutput] = []
for page_index, page_path in enumerate(_bundle_page_paths(input_path)):
lines = self._recognize_page(page_path, page_index=page_index)
outputs.append(
EngineOutput(
pages=[Page(page_index=page_index, text_lines=lines, metadata={"engine": self.name, "language": self.language})],
metadata={"engine": self.name, "language": self.language},
)
)
return _merge_engine_outputs(outputs, engine_name=self.name)
lines = self._recognize_page(input_path, page_index=0)
page = Page(page_index=0, text_lines=lines, metadata={"engine": self.name, "language": self.language})
return EngineOutput(pages=[page], metadata={"engine": self.name, "language": self.language})
def _recognize_page(self, input_path: Path, *, page_index: int) -> list[TextLine]:
command = [
self.binary or "tesseract",
str(input_path),
"stdout",
"-l",
self.language,
"--psm",
str(self.psm),
"tsv",
]
completed = subprocess.run(command, check=False, capture_output=True, text=True)
if completed.returncode != 0:
raise ParseError(f"tesseract failed for {input_path}: {completed.stderr.strip()}")
return self._parse_tsv(completed.stdout, page_offset=page_index)
def _parse_tsv(self, text: str, *, page_offset: int = 0) -> list[TextLine]:
reader = csv.DictReader(text.splitlines(), delimiter="\t")
grouped: dict[tuple[str, str, str, str], list[dict[str, str]]] = {}
for row in reader:
if row.get("level") != "5":
continue
word = row.get("text", "")
if not word.strip():
continue
key = (row.get("page_num", "1"), row.get("block_num", "0"), row.get("par_num", "0"), row.get("line_num", "0"))
grouped.setdefault(key, []).append(row)
lines: list[TextLine] = []
for line_index, (key, rows) in enumerate(sorted(grouped.items(), key=lambda item: tuple(int(part) for part in item[0]))):
boxes = []
confidences = []
words = []
for row in rows:
x = int(float(row.get("left", "0") or 0))
y = int(float(row.get("top", "0") or 0))
w = int(float(row.get("width", "0") or 0))
h = int(float(row.get("height", "0") or 0))
boxes.append(BBox(x, y, w, h))
words.append(row.get("text", ""))
try:
conf = float(row.get("conf", "-1"))
except ValueError:
conf = -1
if conf >= 0:
confidences.append(conf / 100)
from .schemas import union_bbox
page_index = page_offset + max(0, int(key[0]) - 1)
confidence = sum(confidences) / len(confidences) if confidences else None
lines.append(
TextLine(
text=normalize_ocr_text(" ".join(words)),
bbox=union_bbox(boxes),
confidence=confidence,
page_index=page_index,
line_id=f"p{page_index}-l{line_index}",
)
)
return lines
class PaddleOcrEngine:
name = "paddleocr"
def __init__(
self,
*,
recognition_mode: str = "full_page",
line_mode_max_height: int = 256,
line_mode_min_aspect_ratio: float = 3.0,
**kwargs: object,
) -> None:
try:
from paddleocr import PaddleOCR
except ImportError as exc:
raise EngineUnavailableError("paddleocr is not installed. Install ocr-tech[engines].") from exc
try:
from paddleocr._models.text_recognition import TextRecognition
except ImportError:
TextRecognition = None
normalized_mode = recognition_mode.strip().lower()
if normalized_mode == "recognition_only":
normalized_mode = "line"
if normalized_mode not in {"full_page", "line", "auto"}:
raise EngineUnavailableError(f"unsupported PaddleOCR recognition_mode: {recognition_mode!r}")
self._paddle_cls = PaddleOCR
self._text_recognition_cls = TextRecognition
self._paddle_kwargs = dict(kwargs) if kwargs else {"lang": "ne"}
self._recognition_kwargs = _paddle_text_recognition_kwargs(self._paddle_kwargs)
self.recognition_mode = normalized_mode
self.line_mode_max_height = int(line_mode_max_height)
self.line_mode_min_aspect_ratio = float(line_mode_min_aspect_ratio)
self.ocr = None
self.text_recognizer = None
def recognize(self, input_path: Path) -> EngineOutput:
if input_path.is_dir():
outputs: list[EngineOutput] = []
for page_index, page_path in enumerate(_bundle_page_paths(input_path)):
outputs.append(self._recognize_image(page_path, page_index=page_index))
return _merge_engine_outputs(outputs, engine_name=self.name)
return self._recognize_image(input_path, page_index=0)
def _recognize_image(self, input_path: Path, *, page_index: int) -> EngineOutput:
if self._select_recognition_mode(input_path) == "line":
lines = self._recognize_line_image(input_path, page_index=page_index)
page = Page(page_index=page_index, text_lines=lines, metadata={"engine": self.name, "paddle_recognition_mode": "line"})
return EngineOutput(pages=[page], metadata={"engine": self.name, "paddle_recognition_mode": "line"})
raw_result = self._run_ocr(input_path)
lines = self._parse_result(raw_result, page_index=page_index)
page = Page(page_index=page_index, text_lines=lines, metadata={"engine": self.name, "paddle_recognition_mode": "full_page"})
return EngineOutput(pages=[page], metadata={"engine": self.name, "paddle_recognition_mode": "full_page"})
def _select_recognition_mode(self, input_path: Path) -> str:
if self.recognition_mode != "auto":
return self.recognition_mode
return "line" if _is_line_like_image(input_path, self.line_mode_max_height, self.line_mode_min_aspect_ratio) else "full_page"
def _run_ocr(self, input_path: Path) -> object:
ocr = self._full_page_ocr()
if hasattr(ocr, "predict"):
return ocr.predict(str(input_path))
if hasattr(ocr, "ocr"):
return ocr.ocr(str(input_path), cls=True)
raise EngineUnavailableError("Installed paddleocr object exposes neither predict() nor ocr()")
def _full_page_ocr(self) -> object:
if self.ocr is None:
try:
self.ocr = self._paddle_cls(**self._paddle_kwargs)
except RuntimeError as exc:
raise EngineUnavailableError(f"PaddleOCR runtime is unavailable: {exc}") from exc
return self.ocr
def _line_recognizer(self) -> object:
if self._text_recognition_cls is None:
raise EngineUnavailableError("Installed paddleocr package does not expose TextRecognition")
if self.text_recognizer is None:
try:
self.text_recognizer = self._text_recognition_cls(**self._recognition_kwargs)
except RuntimeError as exc:
raise EngineUnavailableError(f"PaddleOCR text-recognition runtime is unavailable: {exc}") from exc
return self.text_recognizer
def _recognize_line_image(self, input_path: Path, *, page_index: int) -> list[TextLine]:
recognizer = self._line_recognizer()
raw_result = recognizer.predict(str(input_path))
width, height = _image_size(input_path)
lines: list[TextLine] = []
for item in raw_result if isinstance(raw_result, list) else [raw_result]:
parsed = self._parse_recognition_result(item, width=width, height=height)
if parsed is None:
continue
text, bbox, confidence = parsed
if not text:
continue
lines.append(
TextLine(
text=normalize_ocr_text(text),
bbox=bbox,
confidence=confidence,
page_index=page_index,
line_id=f"p{page_index}-l{len(lines)}",
)
)
return lines
def _parse_recognition_result(self, item: object, *, width: int, height: int) -> tuple[str, BBox, float | None] | None:
payload = self._result_mapping(item)
if payload is None:
return None
text = payload.get("rec_text") or payload.get("text") or payload.get("transcription")
if text is None:
return None
score = payload.get("rec_score") or payload.get("score") or payload.get("confidence")
confidence = float(score) if score is not None else None
return str(text), BBox(0, 0, width, height), confidence
def _parse_result(self, raw_result: object, *, page_index: int) -> list[TextLine]:
lines: list[TextLine] = []
candidates = raw_result
if isinstance(raw_result, list) and len(raw_result) == 1 and isinstance(raw_result[0], list):
candidates = raw_result[0]
if not isinstance(candidates, list):
raise ParseError(f"Unsupported PaddleOCR result type: {type(raw_result).__name__}")
line_index = 0
for item in candidates:
parsed_lines = self._parse_page_result(item)
if parsed_lines is None:
parsed = self._parse_line(item)
parsed_lines = [] if parsed is None else [parsed]
for text, bbox, confidence in parsed_lines:
lines.append(
TextLine(
text=normalize_ocr_text(text),
bbox=bbox,
confidence=confidence,
page_index=page_index,
line_id=f"p{page_index}-l{line_index}",
)
)
line_index += 1
return lines
def _parse_page_result(self, item: object) -> list[tuple[str, BBox, float | None]] | None:
payload = self._result_mapping(item)
if payload is None:
return None
texts = payload.get("rec_texts")
boxes = payload.get("rec_polys") or payload.get("dt_polys")
scores = payload.get("rec_scores")
if not isinstance(texts, list) or not isinstance(boxes, list):
return None
parsed_lines: list[tuple[str, BBox, float | None]] = []
for index, text in enumerate(texts):
if text is None:
continue
if index >= len(boxes):
continue
confidence = None
if isinstance(scores, list) and index < len(scores) and scores[index] is not None:
confidence = float(scores[index])
parsed_lines.append((str(text), _bbox_from_paddle_box(boxes[index]), confidence))
return parsed_lines
def _result_mapping(self, item: object) -> dict[str, object] | None:
payload: object = item
if not isinstance(payload, dict):
payload = getattr(item, "json", None)
if not isinstance(payload, dict):
return None
nested = payload.get("res")
if isinstance(nested, dict):
return nested
return payload
def _parse_line(self, item: object) -> tuple[str, BBox, float | None] | None:
if isinstance(item, dict):
text = item.get("text") or item.get("rec_text") or item.get("transcription")
score = item.get("score") or item.get("confidence") or item.get("rec_score")
bbox_value = item.get("bbox") or item.get("box") or item.get("dt_polys")
if text is None:
return None
return str(text), _bbox_from_paddle_box(bbox_value), float(score) if score is not None else None
if isinstance(item, list | tuple) and len(item) >= 2:
bbox_value = item[0]
rec = item[1]
if isinstance(rec, list | tuple) and rec:
text = str(rec[0])
score = float(rec[1]) if len(rec) > 1 and rec[1] is not None else None
return text, _bbox_from_paddle_box(bbox_value), score
return None
class SuryaEngine:
name = "surya"
def __init__(
self,
*,
mode: str = "auto",
line_mode_max_height: int = 256,
line_mode_min_aspect_ratio: float = 3.0,
table_recognition_mode: str = "full",
) -> None:
try:
from PIL import Image
except ImportError as exc:
raise EngineUnavailableError("Pillow is not installed. Install ocr-tech[surya].") from exc
try:
from surya.inference import SuryaInferenceManager
from surya.layout.schema import LayoutBox, LayoutResult
from surya.recognition import RecognitionPredictor
from surya.table_rec import TableRecPredictor
except ImportError as exc:
raise EngineUnavailableError("surya-ocr is not installed. Install ocr-tech[surya].") from exc
normalized_mode = mode.strip().lower()
if normalized_mode not in {"auto", "full_page", "block"}:
raise EngineUnavailableError(f"unsupported surya mode: {mode!r}")
normalized_table_mode = table_recognition_mode.strip().lower()
if normalized_table_mode not in {"simple", "full"}:
raise EngineUnavailableError(f"unsupported surya table recognition mode: {table_recognition_mode!r}")
if shutil.which("llama-server") is None and not os.environ.get("LLAMA_CPP_BINARY"):
raise EngineUnavailableError("surya requires llama-server on PATH or LLAMA_CPP_BINARY to be set")
self.mode = normalized_mode
self.line_mode_max_height = int(line_mode_max_height)
self.line_mode_min_aspect_ratio = float(line_mode_min_aspect_ratio)
self.table_recognition_mode = normalized_table_mode
self._image_module = Image
self._layout_box_cls = LayoutBox
self._layout_result_cls = LayoutResult
self._manager = SuryaInferenceManager()
self._predictor = RecognitionPredictor(self._manager)
self._table_predictor = TableRecPredictor(self._manager)
def recognize(self, input_path: Path) -> EngineOutput:
if input_path.is_dir():
outputs: list[EngineOutput] = []
for page_index, page_path in enumerate(_bundle_page_paths(input_path)):
outputs.append(self._recognize_image(page_path, page_index=page_index))
return _merge_engine_outputs(outputs, engine_name=self.name)
return self._recognize_image(input_path, page_index=0)
def _recognize_image(self, input_path: Path, *, page_index: int) -> EngineOutput:
image = self._image_module.open(input_path).convert("RGB")
page_width, page_height = image.size
selected_mode = self._select_mode(page_width, page_height)
if selected_mode == "block":
page_result = self._predict_block(image)
table_results: dict[int, object] = {}
else:
page_result = self._predictor([image], full_page=True)[0]
table_results = self._predict_tables(image, page_result)
return self._convert_page_result(
page_result,
page_width,
page_height,
selected_mode,
page_index=page_index,
table_results=table_results,
)
def _select_mode(self, width: int, height: int) -> str:
if self.mode != "auto":
return self.mode
if height <= max(1, self.line_mode_max_height):
return "block"
aspect_ratio = float(width) / float(max(height, 1))
if aspect_ratio >= self.line_mode_min_aspect_ratio:
return "block"
return "full_page"
def _predict_block(self, image: object) -> object:
width, height = image.size
layout = self._layout_result_cls(
bboxes=[
self._layout_box_cls(
polygon=[[0, 0], [width, 0], [width, height], [0, height]],
label="Text",
raw_label="Text",
position=0,
count=50,
)
],
image_bbox=[0, 0, float(width), float(height)],
)
return self._predictor([image], [layout], full_page=False)[0]
def _predict_tables(self, image: object, page_result: object) -> dict[int, object]:
raw_blocks = getattr(page_result, "blocks", None)
if not isinstance(raw_blocks, list):
return {}
crops: list[object] = []
indices: list[int] = []
for index, block in enumerate(raw_blocks):
label = str(getattr(block, "label", "") or "")
if label != "Table":
continue
bbox = _bbox_from_surya_polygon(getattr(block, "polygon", None))
crop = _crop_image_to_bbox(image, bbox)
if crop is None:
continue
crops.append(crop)
indices.append(index)
if not crops:
return {}
predictions = self._table_predictor(crops, mode=self.table_recognition_mode)
return {index: prediction for index, prediction in zip(indices, predictions, strict=False)}
def _convert_page_result(
self,
page_result: object,
page_width: int,
page_height: int,
selected_mode: str,
page_index: int,
*,
table_results: dict[int, object] | None = None,
) -> EngineOutput:
raw_blocks = getattr(page_result, "blocks", None)
if not isinstance(raw_blocks, list):
raise ParseError("surya output is missing blocks")
text_lines: list[TextLine] = []
tables: list[Table] = []
figures: list[Figure] = []
table_results = table_results or {}
ordered_blocks = sorted(enumerate(raw_blocks), key=lambda item: int(getattr(item[1], "reading_order", 0) or 0))
for line_index, (block_index, block) in enumerate(ordered_blocks):
label = str(getattr(block, "label", "") or "")
polygon = getattr(block, "polygon", None)
bbox = _bbox_from_surya_polygon(polygon)
confidence = validate_confidence(getattr(block, "confidence", None), "surya confidence")
plain_text = _surya_html_to_text(str(getattr(block, "html", "") or ""))
metadata = {
"surya_label": label,
"surya_raw_label": str(getattr(block, "raw_label", "") or ""),
"surya_reading_order": int(getattr(block, "reading_order", line_index) or line_index),
"surya_html": str(getattr(block, "html", "") or ""),
"surya_skipped": bool(getattr(block, "skipped", False)),
"surya_error": bool(getattr(block, "error", False)),
}
if label == "Table":
table = _table_from_surya_block(
block_index=block_index,
table_id=f"p{page_index}-t{len(tables)}",
bbox=bbox,
confidence=confidence,
page_index=page_index,
metadata=metadata,
block_html=str(getattr(block, "html", "") or ""),
table_result=table_results.get(block_index),
)
tables.append(table)
elif label in {"Picture", "Image", "Figure", "Chart"}:
figures.append(
Figure(
figure_id=f"p{page_index}-f{len(figures)}",
page_index=page_index,
bbox=bbox,
summary=plain_text or None,
confidence=confidence,
metadata=metadata,
)
)
if plain_text:
text_lines.append(
TextLine(
text=plain_text,
bbox=bbox,
confidence=confidence,
page_index=page_index,
line_id=f"p{page_index}-l{line_index}",
metadata=metadata,
)
)
page = Page(
page_index=page_index,
width=float(page_width),
height=float(page_height),
text_lines=text_lines,
metadata={"engine": self.name, "surya_mode": selected_mode},
)
return EngineOutput(
pages=[page],
tables=tables,
figures=figures,
metadata={"engine": self.name, "surya_mode": selected_mode},
)
def _crop_image_to_bbox(image: object, bbox: BBox) -> object | None:
left = max(0, int(bbox.x))
top = max(0, int(bbox.y))
right = max(left + 1, int(bbox.right))
bottom = max(top + 1, int(bbox.bottom))
if right <= left or bottom <= top:
return None
return image.crop((left, top, right, bottom))
def _table_from_surya_block(
*,
block_index: int,
table_id: str,
bbox: BBox,
confidence: float | None,
page_index: int,
metadata: dict[str, object],
block_html: str,
table_result: object | None,
) -> Table:
html_value = ""
if table_result is not None and isinstance(getattr(table_result, "html", None), str):
html_value = str(getattr(table_result, "html", "") or "")
elif block_html:
html_value = block_html
cells = _table_cells_from_html(html_value)
table_metadata = dict(metadata)
if table_result is not None:
table_metadata["surya_table_mode"] = str(getattr(table_result, "mode", "") or "")
table_metadata["surya_table_error"] = bool(getattr(table_result, "error", False))
if hasattr(table_result, "rows"):
table_metadata["surya_table_row_count"] = len(getattr(table_result, "rows", []) or [])
if hasattr(table_result, "cols"):
table_metadata["surya_table_col_count"] = len(getattr(table_result, "cols", []) or [])
table_metadata["surya_block_index"] = block_index
return Table(
table_id=table_id,
page_index=page_index,
bbox=bbox,
cells=cells,
html=html_value or None,
confidence=confidence,
metadata=table_metadata,
)
def _bbox_from_surya_polygon(value: object) -> BBox:
if isinstance(value, list | tuple):
points: list[tuple[float, float]] = []
for point in value:
if isinstance(point, list | tuple) and len(point) >= 2:
points.append((float(point[0]), float(point[1])))
if points:
left = min(point[0] for point in points)
top = min(point[1] for point in points)
right = max(point[0] for point in points)
bottom = max(point[1] for point in points)
return BBox(left, top, right - left, bottom - top)
return BBox(0, 0, 0, 0)
class _SuryaHtmlTextExtractor(HTMLParser):
def __init__(self) -> None:
super().__init__()
self.parts: list[str] = []
def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
if tag in {"br", "tr"}:
self.parts.append("\n")
def handle_endtag(self, tag: str) -> None:
if tag in {"p", "div", "tr", "li", "table"}:
self.parts.append("\n")
def handle_data(self, data: str) -> None:
self.parts.append(data)
def get_text(self) -> str:
joined = "".join(self.parts)
collapsed = re.sub(r"\n{3,}", "\n\n", joined)
collapsed = re.sub(r"[ \t]+", " ", collapsed)
return normalize_ocr_text(html.unescape(collapsed).strip())
def _surya_html_to_text(value: str) -> str:
if not value:
return ""
parser = _SuryaHtmlTextExtractor()
parser.feed(value)
parser.close()
return parser.get_text()
class _SuryaTableHtmlExtractor(HTMLParser):
def __init__(self) -> None:
super().__init__()
self.cells: list[TableCell] = []
self._in_row = False
self._cell_text: list[str] | None = None
self._current_row = 0
self._current_col = 0
self._cell_rowspan = 1
self._cell_colspan = 1
def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
if tag == "tr":
self._in_row = True
self._current_col = 0
return
if tag in {"td", "th"} and self._in_row:
attrs_dict = {key: value for key, value in attrs}
self._cell_text = []
self._cell_rowspan = _safe_positive_int(attrs_dict.get("rowspan"), default=1)
self._cell_colspan = _safe_positive_int(attrs_dict.get("colspan"), default=1)
def handle_endtag(self, tag: str) -> None:
if tag in {"td", "th"} and self._cell_text is not None:
text = normalize_ocr_text(html.unescape("".join(self._cell_text)).strip())
self.cells.append(
TableCell(
row=self._current_row,
col=self._current_col,
text=text,
rowspan=self._cell_rowspan,
colspan=self._cell_colspan,
bbox=None,
confidence=None,
)
)
self._current_col += self._cell_colspan
self._cell_text = None
self._cell_rowspan = 1
self._cell_colspan = 1
return
if tag == "tr" and self._in_row:
self._current_row += 1
self._current_col = 0
self._in_row = False
def handle_data(self, data: str) -> None:
if self._cell_text is not None:
self._cell_text.append(data)
def _safe_positive_int(value: str | None, *, default: int) -> int:
if value is None:
return default
try:
parsed = int(value)
except (TypeError, ValueError):
return default
return parsed if parsed >= 1 else default
def _table_cells_from_html(value: str) -> list[TableCell]:
if not value:
return []
parser = _SuryaTableHtmlExtractor()
parser.feed(value)
parser.close()
return parser.cells
class CandidateEngine:
name = "candidate"
def __init__(self, *, model_config: str | Path | None = None) -> None:
if model_config is None:
raise EngineUnavailableError("candidate engine requires a model_config path")
audit = audit_model_card(model_config)
if not audit.passed:
raise EngineUnavailableError("candidate model audit failed: " + "; ".join(audit.issues))
self.model_config = Path(model_config)
self.card = ModelCard.from_path(self.model_config)
if self.card.backend == "sidecar":
self.engine: OcrEngine = SidecarEngine()
elif self.card.backend == "tesseract":
self.engine = TesseractEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "paddleocr":
self.engine = PaddleOcrEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "surya":
self.engine = SuryaEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "hf_vision_encoder_decoder":
self.engine = HuggingFaceVisionTextEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "text_correction_composite":
self.engine = TextCorrectionCompositeEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "quality_select_composite":
self.engine = QualitySelectCompositeEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "quality_ranked_ensemble":
self.engine = QualityRankedEnsembleEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "script_select_composite":
self.engine = ScriptSelectCompositeEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "line_align_composite":
self.engine = LineAlignCompositeEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "table_cell_refine_composite":
self.engine = TableCellRefineCompositeEngine(**_resolve_model_kwargs(self.card, self.model_config))
elif self.card.backend == "figure_caption_refine_composite":
self.engine = FigureCaptionRefineCompositeEngine(**_resolve_model_kwargs(self.card, self.model_config))
else:
raise EngineUnavailableError(f"unsupported candidate backend: {self.card.backend}")
def recognize(self, input_path: Path) -> EngineOutput:
output = self.engine.recognize(input_path)
output.metadata["engine"] = self.name
output.metadata["candidate_model"] = {
"model_id": self.card.model_id,
"backend": self.card.backend,
"model_config": str(self.model_config),
"base_model": self.card.base_model,
}
return output
def _bbox_from_paddle_box(value: object) -> BBox:
if hasattr(value, "tolist"):
value = value.tolist() # type: ignore[assignment, attr-defined]
if isinstance(value, list | tuple):
if len(value) == 4 and all(isinstance(item, int | float) for item in value):
return BBox.from_any(value)
points = []
for point in value:
if isinstance(point, list | tuple) and len(point) >= 2:
points.append((float(point[0]), float(point[1])))
if points:
left = min(point[0] for point in points)
top = min(point[1] for point in points)
right = max(point[0] for point in points)
bottom = max(point[1] for point in points)
return BBox(left, top, right - left, bottom - top)
return BBox(0, 0, 0, 0)
def _image_size(input_path: Path) -> tuple[int, int]:
try:
from PIL import Image
except ImportError as exc:
raise EngineUnavailableError("Pillow is required to inspect image dimensions") from exc
try:
with Image.open(input_path) as image:
return image.size
except Exception as exc:
raise ParseError(f"could not inspect image dimensions for {input_path}: {type(exc).__name__}: {exc}") from exc
def _is_line_like_image(input_path: Path, max_height: int, min_aspect_ratio: float) -> bool:
width, height = _image_size(input_path)
if height <= 0:
return False
return height <= max(1, int(max_height)) and (width / height) >= float(min_aspect_ratio)
def _paddle_text_recognition_kwargs(paddle_kwargs: dict[str, object]) -> dict[str, object]:
recognition_kwargs: dict[str, object] = {}
rename = {
"text_recognition_model_name": "model_name",
"text_recognition_model_dir": "model_dir",
"text_recognition_input_shape": "input_shape",
}
passthrough = {
"device",
"enable_hpi",
"use_tensorrt",
"precision",
"enable_mkldnn",
"mkldnn_cache_capacity",
"cpu_threads",
"paddlex_config",
}
for key, value in paddle_kwargs.items():
if key in rename:
recognition_kwargs[rename[key]] = value
elif key in passthrough:
recognition_kwargs[key] = value
return recognition_kwargs
def create_engine(name: str, **kwargs: object) -> OcrEngine:
engine_name = name.lower().strip()
if engine_name == "sidecar":
return SidecarEngine()
if engine_name in {"tesseract", "tess"}:
return TesseractEngine(**kwargs)
if engine_name in {"paddleocr", "paddle", "stock-paddle"}:
return PaddleOcrEngine(**kwargs)
if engine_name == "surya":
return SuryaEngine(**kwargs)
if engine_name in {"candidate", "ours"}:
return CandidateEngine(**kwargs)
if engine_name == "auto":
return AutoEngine()
raise EngineUnavailableError(f"Unknown OCR engine: {name}")
class AutoEngine:
name = "auto"
def recognize(self, input_path: Path) -> EngineOutput:
if has_sidecar(input_path):
output = SidecarEngine().recognize(input_path)
output.metadata["auto_selected_engine"] = "sidecar"
return output
errors: list[str] = []
for factory_name in ("paddleocr", "tesseract"):
try:
engine = create_engine(factory_name)
output = engine.recognize(input_path)
output.metadata["auto_selected_engine"] = factory_name
return output
except EngineUnavailableError as exc:
errors.append(f"{factory_name}: {exc}")
raise EngineUnavailableError("No OCR engine available. " + " | ".join(errors))
def _resolve_model_kwargs(card: ModelCard, config_path: Path) -> dict[str, object]:
return {
key: _resolve_model_kwarg_value(key, value, config_path.parent)
for key, value in card.backend_kwargs.items()
}
def _resolve_model_kwarg_value(key: str, value: object, base_dir: Path) -> object:
if isinstance(value, str) and key.endswith(("_dir", "_path", "_file", "_config")):
path = Path(value)
return str(path if path.is_absolute() else base_dir / path)
if isinstance(value, dict):
return {
str(nested_key): _resolve_model_kwarg_value(str(nested_key), nested_value, base_dir)
for nested_key, nested_value in value.items()
}
if isinstance(value, list):
return [_resolve_model_kwarg_value(key, item, base_dir) for item in value]
return value
class HuggingFaceVisionTextEngine:
name = "hf_vision_encoder_decoder"
def __init__(self, *, model_dir: str, processor_dir: str | None = None, max_new_tokens: int = 128, device: str | None = None) -> None:
try:
import torch
except ImportError as exc:
raise EngineUnavailableError("torch is not installed. Install ocr-tech[hf-recognizer].") from exc
try:
from PIL import Image
except ImportError as exc:
raise EngineUnavailableError("Pillow is not installed. Install ocr-tech[hf-recognizer].") from exc
try:
from transformers import TrOCRProcessor, VisionEncoderDecoderModel
except ImportError as exc:
raise EngineUnavailableError("transformers is not installed. Install ocr-tech[hf-recognizer].") from exc
self._torch = torch
self._image_module = Image
self.max_new_tokens = int(max_new_tokens)
self.model_dir = Path(model_dir)
self.processor_dir = Path(processor_dir) if processor_dir is not None else self.model_dir
if not self.model_dir.exists():
raise EngineUnavailableError(f"hf model_dir does not exist: {self.model_dir}")
if not self.processor_dir.exists():
raise EngineUnavailableError(f"hf processor_dir does not exist: {self.processor_dir}")
self.processor = _load_trocr_processor(TrOCRProcessor, self.processor_dir)
self.model = VisionEncoderDecoderModel.from_pretrained(str(self.model_dir))
self.device = device or _default_torch_device(torch)
generation_config = getattr(self.model, "generation_config", None)
if generation_config is not None and getattr(generation_config, "max_length", None) is not None:
try:
generation_config.max_length = None
except AttributeError:
pass
self.model.to(self.device)
self.model.eval()
def recognize(self, input_path: Path) -> EngineOutput:
if input_path.is_dir():
outputs: list[EngineOutput] = []
for page_index, page_path in enumerate(_bundle_page_paths(input_path)):
outputs.append(self._recognize_page(page_path, page_index=page_index))
merged = _merge_engine_outputs(outputs, engine_name=self.name)
merged.metadata.update(
{
"hf_model_dir": str(self.model_dir),
"hf_processor_dir": str(self.processor_dir),
"hf_device": self.device,
}
)
return merged
return self._recognize_page(input_path, page_index=0)
def _recognize_page(self, input_path: Path, *, page_index: int) -> EngineOutput:
image = self._image_module.open(input_path).convert("RGB")
pixel_values = self.processor(image, return_tensors="pt").pixel_values.to(self.device)
with self._torch.no_grad():
generated_ids = self.model.generate(pixel_values, max_new_tokens=self.max_new_tokens)
text = normalize_ocr_text(self.processor.batch_decode(generated_ids, skip_special_tokens=True)[0])
line = TextLine(
text=text,
bbox=BBox(0, 0, 0, 0),
confidence=None,
page_index=page_index,
line_id=f"p{page_index}-l0",
)
page = Page(page_index=page_index, text_lines=[line], metadata={"engine": self.name})
return EngineOutput(
pages=[page],
metadata={
"engine": self.name,
"hf_model_dir": str(self.model_dir),
"hf_processor_dir": str(self.processor_dir),
"hf_device": self.device,
},
)
def _default_torch_device(torch: object) -> str:
if getattr(torch, "cuda", None) is not None and torch.cuda.is_available():
return "cuda"
backends = getattr(torch, "backends", None)
mps = getattr(backends, "mps", None)
if mps is not None and mps.is_available():
return "mps"
return "cpu"
def _load_trocr_processor(processor_cls: type[object], source: str | Path) -> object:
attempts = ({"backend": "pil"}, {"use_fast": False})
for kwargs in attempts:
try:
return processor_cls.from_pretrained(str(source), **kwargs)
except TypeError as exc:
if any(key in str(exc) for key in kwargs):
continue
raise
except ImportError as exc:
raise EngineUnavailableError("TrOCR processor loading requires sentencepiece and protobuf. Install ocr-tech[hf-recognizer].") from exc
except ValueError as exc:
message = str(exc)
if "SentencePiece" in message or "sentencepiece" in message or "tiktoken" in message or "protobuf" in message:
raise EngineUnavailableError("TrOCR processor loading requires sentencepiece and protobuf. Install ocr-tech[hf-recognizer].") from exc
raise
except AttributeError as exc:
if "'list' object has no attribute 'keys'" in str(exc):
return _load_trocr_processor_with_sanitized_tokenizer_config(processor_cls, source, kwargs)
raise
return processor_cls.from_pretrained(str(source))
def _load_trocr_processor_with_sanitized_tokenizer_config(
processor_cls: type[object],
source: str | Path,
kwargs: dict[str, object],
) -> object:
source_path = Path(source)
tokenizer_config_path = source_path / "tokenizer_config.json"
if not tokenizer_config_path.exists():
raise EngineUnavailableError(f"HF processor tokenizer_config.json does not exist: {tokenizer_config_path}")
try:
tokenizer_config = json.loads(tokenizer_config_path.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
raise DataValidationError(f"Invalid tokenizer_config.json in HF processor directory {source_path}: {exc}") from exc
extra_special_tokens = tokenizer_config.get("extra_special_tokens")
if not isinstance(extra_special_tokens, list):
raise EngineUnavailableError(
"HF processor loading failed with extra_special_tokens compatibility error, "
"but tokenizer_config.json did not contain a list to sanitize"
)
sanitized_config = dict(tokenizer_config)
sanitized_config["extra_special_tokens"] = {}
with tempfile.TemporaryDirectory(prefix="ocrtech-trocr-processor-") as tmp_dir:
tmp_path = Path(tmp_dir)
shutil.copytree(source_path, tmp_path, dirs_exist_ok=True)
(tmp_path / "tokenizer_config.json").write_text(
json.dumps(sanitized_config, ensure_ascii=False, indent=2) + "\n",
encoding="utf-8",
)
return processor_cls.from_pretrained(str(tmp_path), **kwargs)
class TextCorrectionCompositeEngine:
name = "text_correction_composite"
def __init__(
self,
*,
model_dir: str,
tokenizer_dir: str | None = None,
base_engine: str = "tesseract",
base_engine_kwargs: dict[str, object] | None = None,
max_new_tokens: int = 256,
device: str | None = None,
) -> None:
try:
import torch
except ImportError as exc:
raise EngineUnavailableError("torch is not installed. Install ocr-tech[hf-recognizer].") from exc
try:
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
except ImportError as exc:
raise EngineUnavailableError("transformers is not installed. Install ocr-tech[hf-recognizer].") from exc
if base_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"text correction composite does not support base_engine={base_engine!r}")
self.base_engine = create_engine(base_engine, **(base_engine_kwargs or {}))
self._torch = torch
self.max_new_tokens = int(max_new_tokens)
self.model_dir = Path(model_dir)
self.tokenizer_dir = Path(tokenizer_dir) if tokenizer_dir is not None else self.model_dir
if not self.model_dir.exists():
raise EngineUnavailableError(f"text corrector model_dir does not exist: {self.model_dir}")
if not self.tokenizer_dir.exists():
raise EngineUnavailableError(f"text corrector tokenizer_dir does not exist: {self.tokenizer_dir}")
self.tokenizer = AutoTokenizer.from_pretrained(str(self.tokenizer_dir), use_fast=False)
self.model = AutoModelForSeq2SeqLM.from_pretrained(str(self.model_dir))
self.device = device or _default_torch_device(torch)
generation_config = getattr(self.model, "generation_config", None)
if generation_config is not None and getattr(generation_config, "max_length", None) is not None:
try:
generation_config.max_length = None
except AttributeError:
pass
self.model.to(self.device)
self.model.eval()
def recognize(self, input_path: Path) -> EngineOutput:
base_output = self.base_engine.recognize(input_path)
all_lines = [line for page in base_output.pages for line in page.text_lines]
corrected = self._correct_lines([line.text for line in all_lines])
index = 0
corrected_pages: list[Page] = []
for page in base_output.pages:
text_lines: list[TextLine] = []
for line in page.text_lines:
text_lines.append(replace(line, text=corrected[index]))
index += 1
corrected_pages.append(replace(page, text_lines=text_lines))
metadata = dict(base_output.metadata)
metadata.update(
{
"engine": self.name,
"correction_base_engine": getattr(self.base_engine, "name", type(self.base_engine).__name__),
"correction_model_dir": str(self.model_dir),
"correction_tokenizer_dir": str(self.tokenizer_dir),
"correction_device": self.device,
}
)
return EngineOutput(pages=corrected_pages, tables=base_output.tables, figures=base_output.figures, metadata=metadata)
def _correct_lines(self, texts: list[str]) -> list[str]:
if not texts:
return []
tokenized = self.tokenizer(texts, padding=True, truncation=True, return_tensors="pt")
batch = {key: value.to(self.device) for key, value in tokenized.items()}
with self._torch.no_grad():
generated_ids = self.model.generate(**batch, max_new_tokens=self.max_new_tokens)
decoded = self.tokenizer.batch_decode(generated_ids, skip_special_tokens=True)
return [normalize_ocr_text(text) for text in decoded]
class QualitySelectCompositeEngine:
name = "quality_select_composite"
def __init__(
self,
*,
primary_engine: str,
secondary_engine: str,
primary_engine_kwargs: dict[str, object] | None = None,
secondary_engine_kwargs: dict[str, object] | None = None,
secondary_quality_margin: float = 0.0,
) -> None:
if primary_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"quality_select_composite does not support primary_engine={primary_engine!r}")
if secondary_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"quality_select_composite does not support secondary_engine={secondary_engine!r}")
self.primary_engine = create_engine(primary_engine, **(primary_engine_kwargs or {}))
self.secondary_engine = create_engine(secondary_engine, **(secondary_engine_kwargs or {}))
self.secondary_quality_margin = float(secondary_quality_margin)
def recognize(self, input_path: Path) -> EngineOutput:
primary_output, primary_error = self._try_recognize(self.primary_engine, input_path)
secondary_output, secondary_error = self._try_recognize(self.secondary_engine, input_path)
if primary_output is None and secondary_output is None:
raise ParseError(
"quality_select_composite failed: "
+ "; ".join(
[
f"primary={type(primary_error).__name__}: {primary_error}",
f"secondary={type(secondary_error).__name__}: {secondary_error}",
]
)
)
if primary_output is None:
assert secondary_output is not None
return self._finalize_output(
secondary_output,
chosen_engine=getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__),
primary_quality=None,
secondary_quality=_score_engine_output_quality(input_path, secondary_output),
primary_error=primary_error,
secondary_error=secondary_error,
)
if secondary_output is None:
return self._finalize_output(
primary_output,
chosen_engine=getattr(self.primary_engine, "name", type(self.primary_engine).__name__),
primary_quality=_score_engine_output_quality(input_path, primary_output),
secondary_quality=None,
primary_error=primary_error,
secondary_error=secondary_error,
)
primary_quality = _score_engine_output_quality(input_path, primary_output)
secondary_quality = _score_engine_output_quality(input_path, secondary_output)
quality_delta = secondary_quality.quality_score - primary_quality.quality_score
if quality_delta > self.secondary_quality_margin:
return self._finalize_output(
secondary_output,
chosen_engine=getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__),
primary_quality=primary_quality,
secondary_quality=secondary_quality,
primary_error=primary_error,
secondary_error=secondary_error,
)
return self._finalize_output(
primary_output,
chosen_engine=getattr(self.primary_engine, "name", type(self.primary_engine).__name__),
primary_quality=primary_quality,
secondary_quality=secondary_quality,
primary_error=primary_error,
secondary_error=secondary_error,
)
def _try_recognize(self, engine: OcrEngine, input_path: Path) -> tuple[EngineOutput | None, Exception | None]:
try:
return engine.recognize(input_path), None
except Exception as exc:
return None, exc
def _finalize_output(
self,
output: EngineOutput,
*,
chosen_engine: str,
primary_quality: object | None,
secondary_quality: object | None,
primary_error: Exception | None,
secondary_error: Exception | None,
) -> EngineOutput:
metadata = dict(output.metadata)
metadata.update(
{
"engine": self.name,
"quality_select_composite": {
"primary_engine": getattr(self.primary_engine, "name", type(self.primary_engine).__name__),
"secondary_engine": getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__),
"chosen_engine": chosen_engine,
"secondary_quality_margin": self.secondary_quality_margin,
"primary_quality_score": getattr(primary_quality, "quality_score", None),
"secondary_quality_score": getattr(secondary_quality, "quality_score", None),
"primary_error": f"{type(primary_error).__name__}: {primary_error}" if primary_error is not None else None,
"secondary_error": f"{type(secondary_error).__name__}: {secondary_error}" if secondary_error is not None else None,
},
}
)
return EngineOutput(pages=output.pages, tables=output.tables, figures=output.figures, metadata=metadata)
def _score_engine_output_quality(input_path: Path, output: EngineOutput) -> object:
from .quality import evaluate_document_quality
from .structure import build_document
document = build_document(str(input_path), output)
return evaluate_document_quality(document)
class QualityRankedEnsembleEngine:
name = "quality_ranked_ensemble"
def __init__(
self,
*,
primary_engine: str,
primary_engine_kwargs: dict[str, object] | None = None,
alternative_engines: list[dict[str, object]],
selection_margin: float = 0.0,
) -> None:
if primary_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"quality_ranked_ensemble does not support primary_engine={primary_engine!r}")
if not alternative_engines:
raise EngineUnavailableError("quality_ranked_ensemble requires at least one alternative engine")
self.primary = _RankedEngineSpec(
label=str(primary_engine),
engine=create_engine(primary_engine, **(primary_engine_kwargs or {})),
quality_bias=0.0,
)
self.alternatives: list[_RankedEngineSpec] = []
for index, item in enumerate(alternative_engines):
if not isinstance(item, dict):
raise EngineUnavailableError(f"quality_ranked_ensemble alternative {index} must be an object")
engine_name = str(item.get("engine") or "")
if not engine_name:
raise EngineUnavailableError(f"quality_ranked_ensemble alternative {index} is missing engine")
if engine_name in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"quality_ranked_ensemble does not support alternative engine={engine_name!r}")
self.alternatives.append(
_RankedEngineSpec(
label=str(item.get("label") or engine_name),
engine=create_engine(engine_name, **dict(item.get("engine_kwargs") or {})),
quality_bias=float(item.get("quality_bias", 0.0)),
)
)
self.selection_margin = float(selection_margin)
def recognize(self, input_path: Path) -> EngineOutput:
scored_specs: list[tuple[_RankedEngineSpec, EngineOutput, object, float]] = []
errors: list[str] = []
for spec in [self.primary, *self.alternatives]:
try:
output = spec.engine.recognize(input_path)
quality = _score_engine_output_quality(input_path, output)
adjusted_quality = float(getattr(quality, "quality_score", 0.0)) + spec.quality_bias
scored_specs.append((spec, output, quality, adjusted_quality))
except Exception as exc:
errors.append(f"{spec.label}: {type(exc).__name__}: {exc}")
if not scored_specs:
raise ParseError("quality_ranked_ensemble failed: " + "; ".join(errors))
primary_scored = next(item for item in scored_specs if item[0] is self.primary)
chosen = max(scored_specs, key=lambda item: item[3])
if chosen is not primary_scored and chosen[3] <= primary_scored[3] + self.selection_margin:
chosen = primary_scored
spec, output, quality, adjusted_quality = chosen
metadata = dict(output.metadata)
metadata.update(
{
"engine": self.name,
"quality_ranked_ensemble": {
"primary_engine": self.primary.label,
"chosen_engine": spec.label,
"selection_margin": self.selection_margin,
"adjusted_quality_score": adjusted_quality,
"quality_score": getattr(quality, "quality_score", None),
"alternatives": [
{
"label": item_spec.label,
"quality_score": getattr(item_quality, "quality_score", None),
"adjusted_quality_score": item_adjusted,
"quality_bias": item_spec.quality_bias,
}
for item_spec, _item_output, item_quality, item_adjusted in scored_specs
],
"errors": errors,
},
}
)
return EngineOutput(pages=output.pages, tables=output.tables, figures=output.figures, metadata=metadata)
@dataclass(slots=True)
class _RankedEngineSpec:
label: str
engine: OcrEngine
quality_bias: float
class ScriptSelectCompositeEngine:
name = "script_select_composite"
def __init__(
self,
*,
primary_engine: str,
secondary_engine: str,
primary_engine_kwargs: dict[str, object] | None = None,
secondary_engine_kwargs: dict[str, object] | None = None,
script: str = "devanagari",
primary_script_threshold: float = 0.2,
routing_granularity: str = "document",
secondary_structure_backfill: bool = False,
routing_signal_engine: str = "primary",
primary_guard_script: str | None = None,
primary_guard_threshold: float = 0.5,
primary_guard_min_confidence: float | None = None,
) -> None:
if primary_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"script_select_composite does not support primary_engine={primary_engine!r}")
if secondary_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"script_select_composite does not support secondary_engine={secondary_engine!r}")
self.primary_engine = create_engine(primary_engine, **(primary_engine_kwargs or {}))
self.secondary_engine = create_engine(secondary_engine, **(secondary_engine_kwargs or {}))
self.script = script.strip().lower()
self.primary_script_threshold = float(primary_script_threshold)
self.routing_granularity = routing_granularity.strip().lower()
self.secondary_structure_backfill = bool(secondary_structure_backfill)
self.routing_signal_engine = routing_signal_engine.strip().lower()
self.primary_guard_script = primary_guard_script.strip().lower() if isinstance(primary_guard_script, str) and primary_guard_script.strip() else None
self.primary_guard_threshold = float(primary_guard_threshold)
self.primary_guard_min_confidence = None if primary_guard_min_confidence is None else float(primary_guard_min_confidence)
if self.primary_guard_min_confidence is not None and not 0.0 <= self.primary_guard_min_confidence <= 1.0:
raise EngineUnavailableError(
f"primary_guard_min_confidence must be between 0 and 1: {primary_guard_min_confidence!r}"
)
if self.routing_granularity not in {"document", "page", "line"}:
raise EngineUnavailableError(f"unsupported script routing granularity: {routing_granularity!r}")
if self.routing_signal_engine not in {"primary", "secondary", "both"}:
raise EngineUnavailableError(f"unsupported script routing signal engine: {routing_signal_engine!r}")
if self.primary_guard_script is not None:
_script_ratio("x", self.primary_guard_script)
def recognize(self, input_path: Path) -> EngineOutput:
primary_output = self.primary_engine.recognize(input_path)
primary_text = _engine_output_text(primary_output)
primary_ratio = _script_ratio(primary_text, self.script)
if self.routing_granularity == "page":
secondary_output = self.secondary_engine.recognize(input_path)
return self._route_pages(
primary_output,
secondary_output,
primary_ratio=primary_ratio,
primary_text=primary_text,
)
if self.routing_granularity == "line":
secondary_output = self.secondary_engine.recognize(input_path)
return self._route_lines(
primary_output,
secondary_output,
primary_ratio=primary_ratio,
primary_text=primary_text,
)
secondary_output = None
secondary_text = ""
secondary_ratio = 0.0
if self.routing_signal_engine in {"secondary", "both"}:
secondary_output = self.secondary_engine.recognize(input_path)
secondary_text = _engine_output_text(secondary_output)
secondary_ratio = _script_ratio(secondary_text, self.script)
signal_ratio = _select_signal_ratio(primary_ratio, secondary_ratio, self.routing_signal_engine)
signal_text = secondary_text if self.routing_signal_engine == "secondary" else primary_text
primary_guard_blocks_secondary, primary_guard_ratio = self._primary_guard_blocks_secondary(primary_text)
if signal_ratio > self.primary_script_threshold and not primary_guard_blocks_secondary:
if secondary_output is None:
secondary_output = self.secondary_engine.recognize(input_path)
return self._finalize_output(
secondary_output,
chosen_engine=getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__),
primary_ratio=primary_ratio,
primary_text=primary_text,
secondary_ratio=secondary_ratio,
signal_ratio=signal_ratio,
signal_text=signal_text,
primary_guard_ratio=primary_guard_ratio,
primary_guard_applied=primary_guard_blocks_secondary,
)
if self.secondary_structure_backfill:
if secondary_output is None:
secondary_output = self.secondary_engine.recognize(input_path)
backfilled_output, structure_metadata = _backfill_structure_from_secondary(
primary_output,
secondary_output,
page_indexes={page.page_index for page in primary_output.pages},
)
backfilled_output.metadata.update(structure_metadata)
return self._finalize_output(
backfilled_output,
chosen_engine=getattr(self.primary_engine, "name", type(self.primary_engine).__name__),
primary_ratio=primary_ratio,
primary_text=primary_text,
secondary_ratio=secondary_ratio,
signal_ratio=signal_ratio,
signal_text=signal_text,
primary_guard_ratio=primary_guard_ratio,
primary_guard_applied=primary_guard_blocks_secondary,
)
return self._finalize_output(
primary_output,
chosen_engine=getattr(self.primary_engine, "name", type(self.primary_engine).__name__),
primary_ratio=primary_ratio,
primary_text=primary_text,
secondary_ratio=secondary_ratio,
signal_ratio=signal_ratio,
signal_text=signal_text,
primary_guard_ratio=primary_guard_ratio,
primary_guard_applied=primary_guard_blocks_secondary,
)
def _route_pages(
self,
primary_output: EngineOutput,
secondary_output: EngineOutput,
*,
primary_ratio: float,
primary_text: str,
) -> EngineOutput:
primary_pages = {page.page_index: page for page in primary_output.pages}
secondary_pages = {page.page_index: page for page in secondary_output.pages}
page_indexes = sorted(set(primary_pages) | set(secondary_pages))
selected_pages: list[Page] = []
page_decisions: list[dict[str, object]] = []
secondary_page_count = 0
for page_index in page_indexes:
primary_page = primary_pages.get(page_index)
secondary_page = secondary_pages.get(page_index)
page_text = _page_text(primary_page)
page_ratio = _script_ratio(page_text, self.script)
secondary_page_text = _page_text(secondary_page)
secondary_page_ratio = _script_ratio(secondary_page_text, self.script)
signal_page_ratio = _select_signal_ratio(page_ratio, secondary_page_ratio, self.routing_signal_engine)
primary_guard_blocks_secondary, primary_guard_ratio = self._primary_guard_blocks_secondary(
page_text,
confidence=_page_mean_confidence(primary_page),
)
choose_secondary = (
primary_page is not None
and secondary_page is not None
and signal_page_ratio > self.primary_script_threshold
and not primary_guard_blocks_secondary
)
if choose_secondary:
selected_pages.append(secondary_page)
chosen_engine = getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__)
secondary_page_count += 1
elif primary_page is not None:
selected_pages.append(primary_page)
chosen_engine = getattr(self.primary_engine, "name", type(self.primary_engine).__name__)
elif secondary_page is not None:
selected_pages.append(secondary_page)
chosen_engine = getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__)
secondary_page_count += 1
else:
continue
page_decisions.append(
{
"page_index": page_index,
"chosen_engine": chosen_engine,
"primary_script_ratio": page_ratio,
"secondary_script_ratio": secondary_page_ratio,
"signal_script_ratio": signal_page_ratio,
"primary_guard_script": self.primary_guard_script,
"primary_guard_ratio": primary_guard_ratio,
"primary_guard_min_confidence": self.primary_guard_min_confidence,
"primary_guard_confidence": _page_mean_confidence(primary_page),
"primary_guard_applied": primary_guard_blocks_secondary,
"primary_text_preview": page_text[:120],
"secondary_text_preview": secondary_page_text[:120],
}
)
selected_page_indexes = {page.page_index for page in selected_pages}
secondary_engine_name = getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__)
chosen_engine = (
"mixed"
if secondary_page_count and secondary_page_count != len(selected_pages)
else secondary_engine_name
if secondary_page_count
else getattr(self.primary_engine, "name", type(self.primary_engine).__name__)
)
metadata = {
"page_routing": page_decisions,
"selected_page_indexes": sorted(selected_page_indexes),
}
primary_guard_applied = any(bool(item.get("primary_guard_applied")) for item in page_decisions)
if self.secondary_structure_backfill:
primary_page_indexes = {
int(item["page_index"])
for item in page_decisions
if item.get("chosen_engine") == getattr(self.primary_engine, "name", type(self.primary_engine).__name__)
}
merged_output, structure_metadata = _backfill_structure_from_secondary(
EngineOutput(
pages=selected_pages,
tables=_select_page_items(primary_output.tables, secondary_output.tables, page_decisions, secondary_engine_name),
figures=_select_page_items(primary_output.figures, secondary_output.figures, page_decisions, secondary_engine_name),
metadata=metadata,
),
secondary_output,
page_indexes=primary_page_indexes,
)
merged_output.metadata.update(structure_metadata)
return self._finalize_output(
merged_output,
chosen_engine=chosen_engine,
primary_ratio=primary_ratio,
primary_text=primary_text,
secondary_ratio=_script_ratio(_engine_output_text(secondary_output), self.script),
signal_ratio=_select_signal_ratio(
primary_ratio,
_script_ratio(_engine_output_text(secondary_output), self.script),
self.routing_signal_engine,
),
signal_text=_engine_output_text(secondary_output) if self.routing_signal_engine == "secondary" else primary_text,
primary_guard_ratio=self._primary_guard_ratio(primary_text),
primary_guard_applied=primary_guard_applied,
)
return self._finalize_output(
EngineOutput(
pages=selected_pages,
tables=_select_page_items(primary_output.tables, secondary_output.tables, page_decisions, secondary_engine_name),
figures=_select_page_items(primary_output.figures, secondary_output.figures, page_decisions, secondary_engine_name),
metadata=metadata,
),
chosen_engine=chosen_engine,
primary_ratio=primary_ratio,
primary_text=primary_text,
secondary_ratio=_script_ratio(_engine_output_text(secondary_output), self.script),
signal_ratio=_select_signal_ratio(
primary_ratio,
_script_ratio(_engine_output_text(secondary_output), self.script),
self.routing_signal_engine,
),
signal_text=_engine_output_text(secondary_output) if self.routing_signal_engine == "secondary" else primary_text,
primary_guard_ratio=self._primary_guard_ratio(primary_text),
primary_guard_applied=primary_guard_applied,
)
def _route_lines(
self,
primary_output: EngineOutput,
secondary_output: EngineOutput,
*,
primary_ratio: float,
primary_text: str,
) -> EngineOutput:
primary_pages = {page.page_index: page for page in primary_output.pages}
secondary_pages = {page.page_index: page for page in secondary_output.pages}
page_indexes = sorted(set(primary_pages) | set(secondary_pages))
selected_pages: list[Page] = []
line_decisions: list[dict[str, object]] = []
secondary_line_count = 0
primary_engine_name = getattr(self.primary_engine, "name", type(self.primary_engine).__name__)
secondary_engine_name = getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__)
for page_index in page_indexes:
primary_page = primary_pages.get(page_index)
secondary_page = secondary_pages.get(page_index)
if primary_page is None and secondary_page is not None:
selected_pages.append(secondary_page)
secondary_line_count += len(secondary_page.text_lines)
for line in secondary_page.text_lines:
line_decisions.append(
{
"page_index": page_index,
"line_id": line.line_id,
"chosen_engine": secondary_engine_name,
"primary_script_ratio": None,
"secondary_script_ratio": _script_ratio(line.text, self.script),
"signal_script_ratio": _script_ratio(line.text, self.script),
"reason": "missing_primary_page",
}
)
continue
if primary_page is None:
continue
secondary_lines = list(secondary_page.text_lines) if secondary_page is not None else []
unmatched_secondary = set(range(len(secondary_lines)))
routed_lines: list[TextLine] = []
for line in primary_page.text_lines:
line_ratio = _script_ratio(line.text, self.script)
matched_index, alignment_iou, alignment_distance = _best_line_match(line, secondary_lines, unmatched_secondary)
secondary_line_ratio = (
_script_ratio(secondary_lines[matched_index].text, self.script)
if matched_index is not None
else 0.0
)
signal_line_ratio = _select_signal_ratio(line_ratio, secondary_line_ratio, self.routing_signal_engine)
primary_guard_blocks_secondary, primary_guard_ratio = self._primary_guard_blocks_secondary(
line.text,
confidence=line.confidence,
)
choose_secondary = (
signal_line_ratio > self.primary_script_threshold
and matched_index is not None
and not primary_guard_blocks_secondary
)
if choose_secondary:
matched_line = secondary_lines[matched_index]
unmatched_secondary.discard(matched_index)
metadata = dict(line.metadata)
metadata.update(
{
"script_select_composite": {
"chosen_engine": secondary_engine_name,
"primary_text": line.text,
"secondary_line_id": matched_line.line_id,
"primary_script_ratio": line_ratio,
"secondary_script_ratio": secondary_line_ratio,
"signal_script_ratio": signal_line_ratio,
"primary_guard_script": self.primary_guard_script,
"primary_guard_ratio": primary_guard_ratio,
"primary_guard_min_confidence": self.primary_guard_min_confidence,
"primary_guard_confidence": line.confidence,
"primary_guard_applied": primary_guard_blocks_secondary,
"alignment_iou": alignment_iou,
"alignment_center_distance": alignment_distance,
}
}
)
routed_lines.append(
replace(
line,
text=matched_line.text,
confidence=matched_line.confidence,
metadata=metadata,
)
)
chosen_engine = secondary_engine_name
secondary_line_count += 1
else:
routed_lines.append(line)
chosen_engine = primary_engine_name
line_decisions.append(
{
"page_index": page_index,
"line_id": line.line_id,
"chosen_engine": chosen_engine,
"primary_script_ratio": line_ratio,
"secondary_script_ratio": secondary_line_ratio if matched_index is not None else None,
"signal_script_ratio": signal_line_ratio,
"primary_guard_script": self.primary_guard_script,
"primary_guard_ratio": primary_guard_ratio,
"primary_guard_min_confidence": self.primary_guard_min_confidence,
"primary_guard_confidence": line.confidence,
"primary_guard_applied": primary_guard_blocks_secondary,
"matched_secondary_line_id": secondary_lines[matched_index].line_id if matched_index is not None else None,
"alignment_iou": alignment_iou if matched_index is not None else None,
"alignment_center_distance": alignment_distance if matched_index is not None else None,
}
)
selected_pages.append(replace(primary_page, text_lines=routed_lines))
selected_page_indexes = {page.page_index for page in selected_pages}
chosen_engine = "mixed" if secondary_line_count else primary_engine_name
primary_guard_applied = any(bool(item.get("primary_guard_applied")) for item in line_decisions)
output = EngineOutput(
pages=selected_pages,
tables=list(primary_output.tables),
figures=list(primary_output.figures),
metadata={
"line_routing": line_decisions,
"selected_page_indexes": sorted(selected_page_indexes),
"secondary_line_count": secondary_line_count,
},
)
if self.secondary_structure_backfill:
output, structure_metadata = _backfill_structure_from_secondary(
output,
secondary_output,
page_indexes=selected_page_indexes,
)
output.metadata.update(structure_metadata)
return self._finalize_output(
output,
chosen_engine=chosen_engine,
primary_ratio=primary_ratio,
primary_text=primary_text,
secondary_ratio=_script_ratio(_engine_output_text(secondary_output), self.script),
signal_ratio=_select_signal_ratio(
primary_ratio,
_script_ratio(_engine_output_text(secondary_output), self.script),
self.routing_signal_engine,
),
signal_text=_engine_output_text(secondary_output) if self.routing_signal_engine == "secondary" else primary_text,
primary_guard_ratio=self._primary_guard_ratio(primary_text),
primary_guard_applied=primary_guard_applied,
)
def _primary_guard_ratio(self, text: str) -> float | None:
if self.primary_guard_script is None:
return None
return _script_ratio(text, self.primary_guard_script)
def _primary_guard_blocks_secondary(self, text: str, *, confidence: float | None = None) -> tuple[bool, float | None]:
ratio = self._primary_guard_ratio(text)
if ratio is None:
return False, None
if self.primary_guard_min_confidence is not None:
if confidence is None or confidence < self.primary_guard_min_confidence:
return False, ratio
return ratio >= self.primary_guard_threshold, ratio
def _finalize_output(
self,
output: EngineOutput,
*,
chosen_engine: str,
primary_ratio: float,
primary_text: str,
secondary_ratio: float | None = None,
signal_ratio: float | None = None,
signal_text: str | None = None,
primary_guard_ratio: float | None = None,
primary_guard_applied: bool = False,
) -> EngineOutput:
metadata = dict(output.metadata)
routing_metadata = {}
for key in ("page_routing", "line_routing", "selected_page_indexes", "secondary_line_count"):
if key in metadata:
routing_metadata[key] = metadata.pop(key)
metadata.update(
{
"engine": self.name,
"script_select_composite": {
"primary_engine": getattr(self.primary_engine, "name", type(self.primary_engine).__name__),
"secondary_engine": getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__),
"chosen_engine": chosen_engine,
"script": self.script,
"primary_script_threshold": self.primary_script_threshold,
"routing_granularity": self.routing_granularity,
"routing_signal_engine": self.routing_signal_engine,
"secondary_structure_backfill": self.secondary_structure_backfill,
"primary_guard_script": self.primary_guard_script,
"primary_guard_threshold": self.primary_guard_threshold,
"primary_guard_min_confidence": self.primary_guard_min_confidence,
"primary_guard_ratio": primary_guard_ratio,
"primary_guard_applied": primary_guard_applied,
"primary_script_ratio": primary_ratio,
"secondary_script_ratio": secondary_ratio,
"signal_script_ratio": primary_ratio if signal_ratio is None else signal_ratio,
"primary_text_preview": primary_text[:120],
"signal_text_preview": (primary_text if signal_text is None else signal_text)[:120],
**routing_metadata,
},
}
)
return EngineOutput(pages=output.pages, tables=output.tables, figures=output.figures, metadata=metadata)
ScriptCodepointRange = tuple[int, int]
_DEVANAGARI_RANGES: tuple[ScriptCodepointRange, ...] = (
(0x0900, 0x097F),
(0xA8E0, 0xA8FF),
)
_LIMBU_RANGES: tuple[ScriptCodepointRange, ...] = ((0x1900, 0x194F),)
_LATIN_RANGES: tuple[ScriptCodepointRange, ...] = (
(0x0041, 0x005A),
(0x0061, 0x007A),
(0x00AA, 0x00AA),
(0x00B5, 0x00B5),
(0x00BA, 0x00BA),
(0x00C0, 0x00D6),
(0x00D8, 0x00F6),
(0x00F8, 0x00FF),
)
_SUNUWAR_RANGES: tuple[ScriptCodepointRange, ...] = ((0x11BC0, 0x11BFF),)
_NEWA_RANGES: tuple[ScriptCodepointRange, ...] = ((0x11400, 0x1147F),)
SCRIPT_CODEPOINT_RANGES: dict[str, tuple[ScriptCodepointRange, ...]] = {
"devanagari": _DEVANAGARI_RANGES,
"limbu": _LIMBU_RANGES,
"sirijonga": _LIMBU_RANGES,
"limbu/sirijonga": _LIMBU_RANGES,
"limbu-sirijonga": _LIMBU_RANGES,
"latin": _LATIN_RANGES,
"english": _LATIN_RANGES,
"sunuwar": _SUNUWAR_RANGES,
"jenticha": _SUNUWAR_RANGES,
"sunuwar/jenticha": _SUNUWAR_RANGES,
"lepcha": ((0x1C00, 0x1C4F),),
"kirat_rai": ((0x16D40, 0x16D7F),),
"newa": _NEWA_RANGES,
"prachalit": _NEWA_RANGES,
"newa/prachalit": _NEWA_RANGES,
"tirhuta": ((0x11480, 0x114DF),),
"gurung_khema": ((0x16100, 0x1613F),),
"ol_chiki": ((0x1C50, 0x1C7F),),
"tibetan": ((0x0F00, 0x0FFF),),
}
def _select_signal_ratio(primary_ratio: float, secondary_ratio: float, routing_signal_engine: str) -> float:
if routing_signal_engine == "secondary":
return secondary_ratio
if routing_signal_engine == "both":
return max(primary_ratio, secondary_ratio)
return primary_ratio
def _engine_output_text(output: EngineOutput) -> str:
return "\n".join(line.text for page in output.pages for line in page.text_lines if line.text.strip())
def _page_text(page: Page | None) -> str:
if page is None:
return ""
return "\n".join(line.text for line in page.text_lines if line.text.strip())
def _page_mean_confidence(page: Page | None) -> float | None:
if page is None:
return None
confidences = [line.confidence for line in page.text_lines if line.confidence is not None]
if not confidences:
return None
return sum(confidences) / len(confidences)
def _select_page_items(
primary_items: list[Table] | list[Figure],
secondary_items: list[Table] | list[Figure],
page_decisions: list[dict[str, object]],
secondary_engine_name: str,
) -> list[Table] | list[Figure]:
primary_by_page: dict[int, list[Table] | list[Figure]] = {}
secondary_by_page: dict[int, list[Table] | list[Figure]] = {}
for item in primary_items:
primary_by_page.setdefault(item.page_index, []).append(item)
for item in secondary_items:
secondary_by_page.setdefault(item.page_index, []).append(item)
selected: list[Table] | list[Figure] = []
for decision in page_decisions:
page_index = decision.get("page_index")
if not isinstance(page_index, int):
continue
chosen_engine = decision.get("chosen_engine")
if chosen_engine == secondary_engine_name:
selected.extend(secondary_by_page.get(page_index, []))
else:
selected.extend(primary_by_page.get(page_index, []))
return selected
def _backfill_structure_from_secondary(
primary_output: EngineOutput,
secondary_output: EngineOutput,
*,
page_indexes: set[int],
) -> tuple[EngineOutput, dict[str, object]]:
page_indexes = {int(page_index) for page_index in page_indexes}
primary_tables_by_page: dict[int, list[Table]] = {}
secondary_tables_by_page: dict[int, list[Table]] = {}
primary_figures_by_page: dict[int, list[Figure]] = {}
secondary_figures_by_page: dict[int, list[Figure]] = {}
for table in primary_output.tables:
primary_tables_by_page.setdefault(table.page_index, []).append(table)
for table in secondary_output.tables:
secondary_tables_by_page.setdefault(table.page_index, []).append(table)
for figure in primary_output.figures:
primary_figures_by_page.setdefault(figure.page_index, []).append(figure)
for figure in secondary_output.figures:
secondary_figures_by_page.setdefault(figure.page_index, []).append(figure)
tables = list(primary_output.tables)
figures = list(primary_output.figures)
backfilled_table_pages: list[int] = []
backfilled_figure_pages: list[int] = []
for page_index in sorted(page_indexes):
if not primary_tables_by_page.get(page_index) and secondary_tables_by_page.get(page_index):
tables.extend(secondary_tables_by_page[page_index])
backfilled_table_pages.append(page_index)
if not primary_figures_by_page.get(page_index) and secondary_figures_by_page.get(page_index):
figures.extend(secondary_figures_by_page[page_index])
backfilled_figure_pages.append(page_index)
metadata = {
"structure_backfill": {
"secondary_tables_pages": backfilled_table_pages,
"secondary_figures_pages": backfilled_figure_pages,
}
}
return EngineOutput(pages=primary_output.pages, tables=tables, figures=figures, metadata=dict(primary_output.metadata)), metadata
def _script_ratio(text: str, script: str) -> float:
ranges = _script_ranges(script)
non_space = [char for char in text if not char.isspace()]
if not non_space:
return 0.0
return _script_codepoint_count(non_space, ranges=ranges) / len(non_space)
def _script_ranges(script: str) -> tuple[ScriptCodepointRange, ...]:
normalized = script.strip().lower()
if normalized in SCRIPT_CODEPOINT_RANGES:
return SCRIPT_CODEPOINT_RANGES[normalized]
supported = ", ".join(sorted(SCRIPT_CODEPOINT_RANGES))
raise EngineUnavailableError(f"unsupported script routing target: {script!r}; supported scripts: {supported}")
def _script_codepoint_count(
chars: Iterable[str],
*,
ranges: tuple[ScriptCodepointRange, ...] | None = None,
script: str | None = None,
) -> int:
if ranges is None:
if script is None:
raise RuntimeError("script or ranges is required for script codepoint counting")
ranges = _script_ranges(script)
return sum(1 for char in chars if _codepoint_in_ranges(ord(char), ranges))
def _codepoint_in_ranges(codepoint: int, ranges: tuple[ScriptCodepointRange, ...]) -> bool:
return any(start <= codepoint <= end for start, end in ranges)
class LineAlignCompositeEngine:
name = "line_align_composite"
def __init__(
self,
*,
primary_engine: str,
secondary_engine: str,
primary_engine_kwargs: dict[str, object] | None = None,
secondary_engine_kwargs: dict[str, object] | None = None,
append_unmatched_primary: bool = True,
secondary_structure_backfill: bool = False,
) -> None:
if primary_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"line_align_composite does not support primary_engine={primary_engine!r}")
if secondary_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"line_align_composite does not support secondary_engine={secondary_engine!r}")
self.primary_engine = create_engine(primary_engine, **(primary_engine_kwargs or {}))
self.secondary_engine = create_engine(secondary_engine, **(secondary_engine_kwargs or {}))
self.append_unmatched_primary = bool(append_unmatched_primary)
self.secondary_structure_backfill = bool(secondary_structure_backfill)
def recognize(self, input_path: Path) -> EngineOutput:
primary_output = self.primary_engine.recognize(input_path)
secondary_output = self.secondary_engine.recognize(input_path)
primary_pages = {page.page_index: page for page in primary_output.pages}
secondary_pages = {page.page_index: page for page in secondary_output.pages}
page_indexes = sorted(set(primary_pages) | set(secondary_pages))
aligned_pages: list[Page] = []
page_alignment: list[dict[str, object]] = []
total_matches = 0
for page_index in page_indexes:
primary_page = primary_pages.get(page_index)
secondary_page = secondary_pages.get(page_index)
aligned_page, alignment_meta = _align_page_lines(
primary_page,
secondary_page,
append_unmatched_primary=self.append_unmatched_primary,
)
total_matches += int(alignment_meta.get("matched_line_count", 0))
page_alignment.append({"page_index": page_index, **alignment_meta})
aligned_pages.append(aligned_page)
output = EngineOutput(
pages=aligned_pages,
tables=list(primary_output.tables),
figures=list(primary_output.figures),
metadata={
"engine": self.name,
"line_align_composite": {
"primary_engine": getattr(self.primary_engine, "name", type(self.primary_engine).__name__),
"secondary_engine": getattr(self.secondary_engine, "name", type(self.secondary_engine).__name__),
"append_unmatched_primary": self.append_unmatched_primary,
"secondary_structure_backfill": self.secondary_structure_backfill,
"matched_line_count": total_matches,
"page_alignment": page_alignment,
},
},
)
if self.secondary_structure_backfill:
output, structure_metadata = _backfill_structure_from_secondary(
output,
secondary_output,
page_indexes={page.page_index for page in aligned_pages},
)
output.metadata.update(structure_metadata)
return output
def _align_page_lines(
primary_page: Page | None,
secondary_page: Page | None,
*,
append_unmatched_primary: bool,
) -> tuple[Page, dict[str, object]]:
if primary_page is None and secondary_page is None:
return Page(page_index=0, text_lines=[], metadata={}), {"matched_line_count": 0, "unmatched_primary_count": 0, "used_secondary_scaffold": False}
if secondary_page is None and primary_page is not None:
return primary_page, {"matched_line_count": len(primary_page.text_lines), "unmatched_primary_count": 0, "used_secondary_scaffold": False}
if primary_page is None and secondary_page is not None:
return secondary_page, {"matched_line_count": 0, "unmatched_primary_count": 0, "used_secondary_scaffold": True}
assert primary_page is not None
assert secondary_page is not None
unmatched_primary = set(range(len(primary_page.text_lines)))
aligned_lines: list[TextLine] = []
matched_count = 0
for secondary_line in secondary_page.text_lines:
matched_index, alignment_iou, alignment_distance = _best_line_match(secondary_line, primary_page.text_lines, unmatched_primary)
if matched_index is None:
aligned_lines.append(secondary_line)
continue
matched_primary = primary_page.text_lines[matched_index]
unmatched_primary.discard(matched_index)
matched_count += 1
metadata = dict(secondary_line.metadata)
metadata.update(
{
"aligned_primary_line_id": matched_primary.line_id,
"alignment_iou": alignment_iou,
"alignment_center_distance": alignment_distance,
}
)
aligned_lines.append(
TextLine(
text=matched_primary.text,
bbox=secondary_line.bbox,
confidence=matched_primary.confidence,
page_index=secondary_line.page_index,
line_id=secondary_line.line_id,
metadata=metadata,
)
)
if append_unmatched_primary:
for primary_index in sorted(unmatched_primary):
aligned_lines.append(primary_page.text_lines[primary_index])
aligned_page = Page(
page_index=secondary_page.page_index,
width=secondary_page.width,
height=secondary_page.height,
text_lines=aligned_lines,
metadata=dict(secondary_page.metadata),
)
return aligned_page, {
"matched_line_count": matched_count,
"unmatched_primary_count": len(unmatched_primary),
"used_secondary_scaffold": True,
}
def _best_line_match(
target_line: TextLine,
candidate_lines: list[TextLine],
unmatched_indexes: set[int],
) -> tuple[int | None, float, float]:
best_index: int | None = None
best_iou = -1.0
best_distance = float("inf")
for index in unmatched_indexes:
candidate = candidate_lines[index]
overlap = bbox_iou(target_line.bbox, candidate.bbox)
distance = _bbox_center_distance(target_line.bbox, candidate.bbox)
if overlap > best_iou or (overlap == best_iou and distance < best_distance):
best_index = index
best_iou = overlap
best_distance = distance
if best_index is None:
return None, 0.0, float("inf")
return best_index, best_iou, best_distance
def _bbox_center_distance(left: BBox, right: BBox) -> float:
left_center_x = left.x + left.w / 2.0
left_center_y = left.y + left.h / 2.0
right_center_x = right.x + right.w / 2.0
right_center_y = right.y + right.h / 2.0
return ((left_center_x - right_center_x) ** 2 + (left_center_y - right_center_y) ** 2) ** 0.5
class TableCellRefineCompositeEngine:
name = "table_cell_refine_composite"
def __init__(
self,
*,
structure_engine: str = "surya",
crop_engine: str = "tesseract",
structure_engine_kwargs: dict[str, object] | None = None,
crop_engine_kwargs: dict[str, object] | None = None,
crop_padding: int = 4,
min_replacement_chars: int = 1,
replacement_policy: str = "empty",
min_replacement_confidence_delta: float = 0.05,
deduplicate_tables: bool = False,
duplicate_iou_threshold: float = 0.9,
) -> None:
if structure_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"table_cell_refine_composite does not support structure_engine={structure_engine!r}")
if crop_engine in {"ours", "auto"}:
raise EngineUnavailableError(f"table_cell_refine_composite does not support crop_engine={crop_engine!r}")
try:
from PIL import Image
except ImportError as exc:
raise EngineUnavailableError("table cell refinement requires Pillow. Install ocr-tech[eval].") from exc
self.structure_engine = create_engine(structure_engine, **(structure_engine_kwargs or {}))
self.crop_engine = create_engine(crop_engine, **(crop_engine_kwargs or {}))
self.crop_padding = int(crop_padding)
self.min_replacement_chars = int(min_replacement_chars)
self.replacement_policy = replacement_policy.strip().lower()
self.min_replacement_confidence_delta = float(min_replacement_confidence_delta)
self.deduplicate_tables = bool(deduplicate_tables)
self.duplicate_iou_threshold = float(duplicate_iou_threshold)
if self.crop_padding < 0:
raise EngineUnavailableError("table_cell_refine_composite crop_padding must be non-negative")
if self.min_replacement_chars < 1:
raise EngineUnavailableError("table_cell_refine_composite min_replacement_chars must be at least 1")
if self.replacement_policy not in {"empty", "always", "guarded"}:
raise EngineUnavailableError("table_cell_refine_composite replacement_policy must be empty, guarded, or always")
if self.min_replacement_confidence_delta < 0:
raise EngineUnavailableError("table_cell_refine_composite min_replacement_confidence_delta must be non-negative")
if not 0.0 <= self.duplicate_iou_threshold <= 1.0:
raise EngineUnavailableError("table_cell_refine_composite duplicate_iou_threshold must be between 0 and 1")
self._image_module = Image
def recognize(self, input_path: Path) -> EngineOutput:
structure_output = self.structure_engine.recognize(input_path)
page_paths = _input_page_paths(input_path)
refined_tables: list[Table] = []
refined_count = 0
attempted_count = 0
error_count = 0
dropped_duplicate_tables = 0
with tempfile.TemporaryDirectory(prefix="ocrtech-cell-refine-") as tmp_dir:
tmp_path = Path(tmp_dir)
for table in structure_output.tables:
page_path = page_paths.get(table.page_index)
if page_path is None:
refined_tables.append(table)
continue
try:
with self._image_module.open(page_path).convert("RGB") as page_image:
refined_table, table_meta = self._refine_table(table, page_image, tmp_path)
except Exception as exc:
metadata = dict(table.metadata)
metadata["table_cell_refine_error"] = f"{type(exc).__name__}: {exc}"
refined_tables.append(replace(table, metadata=metadata))
error_count += 1
continue
refined_tables.append(refined_table)
refined_count += int(table_meta["replaced_cells"])
attempted_count += int(table_meta["attempted_cells"])
error_count += int(table_meta["error_cells"])
if self.deduplicate_tables:
refined_tables, dropped_duplicate_tables = _deduplicate_overlapping_tables(refined_tables, iou_threshold=self.duplicate_iou_threshold)
metadata = dict(structure_output.metadata)
metadata.update(
{
"engine": self.name,
"table_cell_refine_composite": {
"structure_engine": getattr(self.structure_engine, "name", type(self.structure_engine).__name__),
"crop_engine": getattr(self.crop_engine, "name", type(self.crop_engine).__name__),
"crop_padding": self.crop_padding,
"min_replacement_chars": self.min_replacement_chars,
"replacement_policy": self.replacement_policy,
"min_replacement_confidence_delta": self.min_replacement_confidence_delta,
"deduplicate_tables": self.deduplicate_tables,
"duplicate_iou_threshold": self.duplicate_iou_threshold,
"dropped_duplicate_tables": dropped_duplicate_tables,
"attempted_cells": attempted_count,
"replaced_cells": refined_count,
"error_cells": error_count,
},
}
)
return EngineOutput(
pages=structure_output.pages,
tables=refined_tables,
figures=structure_output.figures,
metadata=metadata,
)
def _refine_table(self, table: Table, page_image: object, tmp_dir: Path) -> tuple[Table, dict[str, int]]:
cells = list(table.cells)
if not cells:
return table, {"attempted_cells": 0, "replaced_cells": 0, "error_cells": 0}
rows = max(cell.row + cell.rowspan for cell in cells)
cols = max(cell.col + cell.colspan for cell in cells)
refined_cells: list[TableCell] = []
attempted = 0
replaced = 0
errors = 0
skipped_non_empty = 0
skipped_guarded = 0
for cell_index, cell in enumerate(cells):
if self.replacement_policy == "empty" and cell.text.strip():
refined_cells.append(_replace_cell(cell, bbox=cell.bbox if cell.bbox is not None else _infer_cell_bbox(table.bbox, cell, rows=rows, cols=cols)))
skipped_non_empty += 1
continue
bbox = cell.bbox if cell.bbox is not None and cell.bbox.w > 0 and cell.bbox.h > 0 else _infer_cell_bbox(table.bbox, cell, rows=rows, cols=cols)
crop = _crop_pil_image(page_image, _expand_bbox(bbox, self.crop_padding), self._image_module)
crop_path = tmp_dir / f"{table.table_id}-r{cell.row:03d}-c{cell.col:03d}-{cell_index:04d}.png"
crop.save(crop_path)
attempted += 1
try:
crop_output = self.crop_engine.recognize(crop_path)
crop_text = _engine_output_text(crop_output).strip()
crop_confidence = crop_output.average_confidence
except Exception as exc:
metadata = {"cell_refine_error": f"{type(exc).__name__}: {exc}"}
refined_cells.append(_replace_cell(cell, bbox=bbox, metadata=metadata))
errors += 1
continue
normalized = normalize_ocr_text(crop_text)
if len(normalized) >= self.min_replacement_chars:
should_replace, guard_reason = self._should_replace_cell(cell, normalized, crop_confidence)
if not should_replace:
metadata = {"cell_refine_guard": guard_reason} if guard_reason else None
refined_cells.append(_replace_cell(cell, bbox=bbox, metadata=metadata))
skipped_guarded += 1
continue
refined_cells.append(_replace_cell(cell, text=normalized, bbox=bbox, confidence=crop_confidence))
if normalized != cell.text:
replaced += 1
else:
refined_cells.append(_replace_cell(cell, bbox=bbox))
from .tables import cells_to_html
metadata = dict(table.metadata)
metadata["table_cell_refine"] = {
"attempted_cells": attempted,
"replaced_cells": replaced,
"error_cells": errors,
"skipped_non_empty_cells": skipped_non_empty,
"skipped_guarded_cells": skipped_guarded,
"crop_engine": getattr(self.crop_engine, "name", type(self.crop_engine).__name__),
}
refined_table = replace(table, cells=refined_cells, html=cells_to_html(refined_cells), metadata=metadata)
return refined_table, {"attempted_cells": attempted, "replaced_cells": replaced, "error_cells": errors}
def _should_replace_cell(self, cell: TableCell, replacement_text: str, replacement_confidence: float | None) -> tuple[bool, str | None]:
if self.replacement_policy == "always":
return True, None
if not cell.text.strip():
return True, None
if self.replacement_policy == "empty":
return False, "non_empty_cell"
if replacement_text == cell.text:
return False, "same_text"
if replacement_confidence is None:
return False, "missing_replacement_confidence"
if cell.confidence is None:
return False, "missing_existing_confidence"
if replacement_confidence < cell.confidence + self.min_replacement_confidence_delta:
return False, "replacement_confidence_not_higher"
return True, None
def _deduplicate_overlapping_tables(tables: list[Table], *, iou_threshold: float) -> tuple[list[Table], int]:
kept: list[Table] = []
dropped = 0
for table in sorted(tables, key=_table_dedup_sort_key):
duplicate_index = None
for index, existing in enumerate(kept):
if table.page_index != existing.page_index:
continue
if bbox_iou(table.bbox, existing.bbox) >= iou_threshold:
duplicate_index = index
break
if duplicate_index is None:
kept.append(table)
continue
existing = kept[duplicate_index]
if _table_quality_score(table) > _table_quality_score(existing):
kept[duplicate_index] = table
dropped += 1
return sorted(kept, key=lambda item: (item.page_index, item.bbox.y, item.bbox.x)), dropped
def _table_dedup_sort_key(table: Table) -> tuple[float, float, float, int, int, float]:
structure_score, non_empty, confidence = _table_quality_score(table)
return (table.page_index, table.bbox.y, table.bbox.x, -structure_score, -non_empty, -confidence)
def _table_quality_score(table: Table) -> tuple[int, int, float]:
if not table.cells:
return (0, 0, float(table.confidence or 0.0))
rows = max(cell.row + cell.rowspan for cell in table.cells)
cols = max(cell.col + cell.colspan for cell in table.cells)
non_empty = sum(1 for cell in table.cells if cell.text.strip())
rectangular_cells = rows * cols
structure_score = min(len(table.cells), rectangular_cells)
return (structure_score, non_empty, float(table.confidence or 0.0))
def _input_page_paths(input_path: Path) -> dict[int, Path]:
if input_path.is_dir():
return {index: page_path for index, page_path in enumerate(_bundle_page_paths(input_path))}
return {0: input_path}
def _infer_cell_bbox(table_bbox: BBox, cell: TableCell, *, rows: int, cols: int) -> BBox:
col_width = table_bbox.w / max(cols, 1)
row_height = table_bbox.h / max(rows, 1)
return BBox(
table_bbox.x + col_width * cell.col,
table_bbox.y + row_height * cell.row,
col_width * cell.colspan,
row_height * cell.rowspan,
)
def _expand_bbox(bbox: BBox, padding: int) -> BBox:
return BBox(bbox.x - padding, bbox.y - padding, bbox.w + padding * 2, bbox.h + padding * 2)
def _crop_pil_image(image: object, bbox: BBox, image_module: object) -> object:
width, height = image.size
left = max(0, int(bbox.x))
top = max(0, int(bbox.y))
right = min(width, max(left + 1, int(bbox.right)))
bottom = min(height, max(top + 1, int(bbox.bottom)))
if right <= left or bottom <= top:
return image_module.new("RGB", (1, 1), "white")
return image.crop((left, top, right, bottom))
def _replace_cell(
cell: TableCell,
*,
text: str | None = None,
bbox: BBox | None = None,
confidence: float | None = None,
metadata: dict[str, object] | None = None,
) -> TableCell:
cell_metadata = dict(cell.metadata)
if metadata:
cell_metadata.update(metadata)
return TableCell(
row=cell.row,
col=cell.col,
text=cell.text if text is None else text,
rowspan=cell.rowspan,
colspan=cell.colspan,
bbox=bbox if bbox is not None else cell.bbox,
confidence=confidence if confidence is not None else cell.confidence,
metadata=cell_metadata,
)
FIGURE_MARKER_LINE_RE = re.compile(r"^\s*(?:\[(?:figure|chart|image|चित्र)[^\]]*\]|(?:figure|fig\.?|chart|चित्र)\s*[::]?)", re.IGNORECASE)
CAPTION_PREFIX_SPLIT_RE = re.compile(r"[\s\d०-९IVXivx.:-]+", re.UNICODE)
class FigureCaptionRefineCompositeEngine:
name = "figure_caption_refine_composite"
def __init__(
self,
*,
primary_engine: str = "surya",
caption_engine: str = "tesseract",
primary_engine_kwargs: dict[str, object] | None = None,
caption_engine_kwargs: dict[str, object] | None = None,
min_caption_iou: float = 0.5,
min_score_delta: int = 1,
max_gap_multiplier: float = 1.5,
correct_structural_labels: bool = False,
table_name_lexicon_path: str | Path | None = None,
table_name_lexicon: list[str] | None = None,
table_name_max_distance: int = 2,
infer_table_header_colspans: bool = True,
normalize_table_grids: bool = True,
) -> None:
if primary_engine in {"candidate", "ours", "auto"}:
raise EngineUnavailableError(f"figure_caption_refine_composite does not support primary_engine={primary_engine!r}")
if caption_engine in {"ours", "auto"}:
raise EngineUnavailableError(f"figure_caption_refine_composite does not support caption_engine={caption_engine!r}")
self.primary_engine = create_engine(primary_engine, **(primary_engine_kwargs or {}))
self.caption_engine = create_engine(caption_engine, **(caption_engine_kwargs or {}))
self.min_caption_iou = float(min_caption_iou)
self.min_score_delta = int(min_score_delta)
self.max_gap_multiplier = float(max_gap_multiplier)
self.correct_structural_labels = bool(correct_structural_labels)
self.table_name_lexicon = _load_table_name_lexicon(table_name_lexicon_path, table_name_lexicon)
self.table_name_max_distance = int(table_name_max_distance)
self.infer_table_header_colspans = bool(infer_table_header_colspans)
self.normalize_table_grids = bool(normalize_table_grids)
if not 0.0 <= self.min_caption_iou <= 1.0:
raise EngineUnavailableError("figure_caption_refine_composite min_caption_iou must be between 0 and 1")
if self.min_score_delta < 0:
raise EngineUnavailableError("figure_caption_refine_composite min_score_delta must be non-negative")
if self.max_gap_multiplier <= 0:
raise EngineUnavailableError("figure_caption_refine_composite max_gap_multiplier must be positive")
if self.table_name_max_distance < 0:
raise EngineUnavailableError("figure_caption_refine_composite table_name_max_distance must be non-negative")
def recognize(self, input_path: Path) -> EngineOutput:
primary_output = self.primary_engine.recognize(input_path)
caption_output = self.caption_engine.recognize(input_path)
secondary_by_page: dict[int, list[TextLine]] = {}
for page in caption_output.pages:
secondary_by_page.setdefault(page.page_index, []).extend(page.text_lines)
refined_pages: list[Page] = []
attempted = 0
replaced_count = 0
for page in primary_output.pages:
lines = list(page.text_lines)
refined_lines = list(lines)
index = 0
while index + 1 < len(lines):
marker = lines[index]
caption = lines[index + 1]
if not _line_looks_like_figure_marker(marker.text) or not _line_can_be_caption_after_marker(marker, caption, self.max_gap_multiplier):
index += 1
continue
attempted += 1
replacement = _best_caption_replacement(
caption,
secondary_by_page.get(caption.page_index, []),
min_iou=self.min_caption_iou,
min_score_delta=self.min_score_delta,
)
if replacement is not None:
metadata = dict(caption.metadata)
metadata["figure_caption_refine"] = {
"original_text": caption.text,
"replacement_engine": getattr(self.caption_engine, "name", type(self.caption_engine).__name__),
"replacement_text": replacement.text,
}
refined_lines[index + 1] = replace(
caption,
text=normalize_ocr_text(replacement.text),
confidence=replacement.confidence,
metadata=metadata,
)
replaced_count += 1
index += 1
if self.correct_structural_labels:
refined_lines = [_correct_structural_label_line(line) for line in refined_lines]
refined_pages.append(replace(page, text_lines=refined_lines))
refined_tables, inferred_colspans = _infer_table_header_colspans(primary_output.tables, enabled=self.infer_table_header_colspans)
refined_tables, normalized_table_columns, normalized_table_rows = _normalize_table_grids(
refined_tables,
enabled=self.normalize_table_grids,
)
refined_tables, table_name_corrections = _correct_table_name_cells(
refined_tables,
lexicon=self.table_name_lexicon,
max_distance=self.table_name_max_distance,
)
metadata = dict(primary_output.metadata)
metadata.update(
{
"engine": self.name,
"figure_caption_refine_composite": {
"primary_engine": getattr(self.primary_engine, "name", type(self.primary_engine).__name__),
"caption_engine": getattr(self.caption_engine, "name", type(self.caption_engine).__name__),
"min_caption_iou": self.min_caption_iou,
"min_score_delta": self.min_score_delta,
"max_gap_multiplier": self.max_gap_multiplier,
"correct_structural_labels": self.correct_structural_labels,
"table_name_lexicon_size": len(self.table_name_lexicon),
"table_name_max_distance": self.table_name_max_distance,
"table_name_corrections": table_name_corrections,
"infer_table_header_colspans": self.infer_table_header_colspans,
"inferred_table_header_colspans": inferred_colspans,
"normalize_table_grids": self.normalize_table_grids,
"normalized_table_grid_dropped_columns": normalized_table_columns,
"normalized_table_grid_merged_rows": normalized_table_rows,
"attempted_captions": attempted,
"replaced_captions": replaced_count,
},
}
)
return EngineOutput(pages=refined_pages, tables=refined_tables, figures=primary_output.figures, metadata=metadata)
def _line_looks_like_figure_marker(text: str) -> bool:
return bool(FIGURE_MARKER_LINE_RE.match(text.strip()))
def _line_can_be_caption_after_marker(marker: TextLine, candidate: TextLine, max_gap_multiplier: float) -> bool:
if _line_looks_like_figure_marker(candidate.text):
return False
if not candidate.text.strip():
return False
if "\t" in candidate.text or "|" in candidate.text:
return False
vertical_gap = candidate.bbox.y - marker.bbox.bottom
max_gap = max(marker.bbox.h, candidate.bbox.h, 24) * max_gap_multiplier
return 0 <= vertical_gap <= max_gap
def _best_caption_replacement(
caption: TextLine,
candidates: list[TextLine],
*,
min_iou: float,
min_score_delta: int,
) -> TextLine | None:
original_score = _caption_prefix_score(caption.text)
best: tuple[int, float, TextLine] | None = None
for candidate in candidates:
overlap = bbox_iou(caption.bbox, candidate.bbox)
if overlap < min_iou:
continue
candidate_score = _caption_prefix_score(candidate.text)
if original_score - candidate_score < min_score_delta:
continue
if best is None or candidate_score < best[0] or (candidate_score == best[0] and overlap > best[1]):
best = (candidate_score, overlap, candidate)
return best[2] if best is not None else None
def _caption_prefix_score(text: str) -> int:
stripped = normalize_ocr_text(text).strip()
if not stripped:
return 99
prefix = CAPTION_PREFIX_SPLIT_RE.split(stripped, maxsplit=1)[0]
if not prefix:
return 99
lowered = prefix.lower()
if lowered in {"caption", "figure", "fig", "fig."}:
return 0
return min(edit_distance(prefix, target) for target in ("चित्र", "तालिका"))
def _correct_structural_label_line(line: TextLine) -> TextLine:
corrected = _correct_structural_label_text(line.text)
if corrected == line.text:
return line
metadata = dict(line.metadata)
metadata["structural_label_correction"] = {"original_text": line.text, "corrected_text": corrected}
return replace(line, text=corrected, metadata=metadata)
def _correct_structural_label_text(text: str) -> str:
normalized = normalize_ocr_text(text)
corrected = _correct_annual_report_title(normalized)
corrected = _correct_daily_ledger_title(corrected)
corrected = _correct_prefixed_label(corrected, target="चित्र", max_distance=2, require_separator=True)
corrected = _correct_prefixed_label(corrected, target="निष्कर्ष", max_distance=2, require_separator=True)
return corrected
def _correct_annual_report_title(text: str) -> str:
match = re.match(r"^\s*(?P<first>\S+)\s+(?P<second>\S+)(?P<rest>.*)$", text)
if match is None:
return text
first = match.group("first").rstrip(":ः")
second = match.group("second").rstrip(":ः")
if edit_distance(first, "वार्षिक") <= 1 and edit_distance(second, "प्रतिवेदन") <= 3:
return f"वार्षिक प्रतिवेदन{match.group('rest')}"
return text
def _correct_daily_ledger_title(text: str) -> str:
match = re.match(r"^\s*(?P<first>\S+)\s+(?P<second>\S+)(?P<rest>.*)$", text)
if match is None:
return text
first = match.group("first").rstrip(":ः")
second = match.group("second").rstrip(":ः")
if edit_distance(first, "दैनिक") <= 2 and edit_distance(second, "हिसाब") <= 2:
return f"दैनिक हिसाब{match.group('rest')}"
return text
def _correct_prefixed_label(text: str, *, target: str, max_distance: int, require_separator: bool) -> str:
match = re.match(r"^(?P<prefix>[^\s:ः]+)(?P<sep>[:ः]?)(?P<rest>.*)$", text)
if match is None:
return text
prefix = match.group("prefix")
sep = match.group("sep")
rest = match.group("rest")
if require_separator and not (sep or re.match(r"^\s*[०-९0-9IVXivx.:-]", rest)):
return text
if edit_distance(prefix, target) <= max_distance:
separator = ":" if sep else ""
return f"{target}{separator}{rest}"
return text
def _load_table_name_lexicon(path: str | Path | None, inline_values: list[str] | None) -> list[str]:
values: list[str] = []
if inline_values:
values.extend(str(item) for item in inline_values)
if path is not None:
lexicon_path = Path(path)
if not lexicon_path.exists():
raise EngineUnavailableError(f"figure_caption_refine_composite table_name_lexicon_path does not exist: {lexicon_path}")
values.extend(lexicon_path.read_text(encoding="utf-8").splitlines())
cleaned: list[str] = []
seen: set[str] = set()
for value in values:
item = normalize_ocr_text(value).strip()
if not item or item.startswith("#") or item in seen:
continue
seen.add(item)
cleaned.append(item)
return cleaned
def _infer_table_header_colspans(tables: list[Table], *, enabled: bool) -> tuple[list[Table], int]:
if not enabled:
return tables, 0
from .tables import infer_repeated_header_colspans
inferred_tables: list[Table] = []
total_inferred = 0
for table in tables:
inferred_table, count = infer_repeated_header_colspans(table)
inferred_tables.append(inferred_table)
total_inferred += count
return inferred_tables, total_inferred
def _normalize_table_grids(tables: list[Table], *, enabled: bool) -> tuple[list[Table], int, int]:
if not enabled:
return tables, 0, 0
from .tables import normalize_table_grid_structure
normalized_tables: list[Table] = []
total_dropped_columns = 0
total_merged_rows = 0
for table in tables:
normalized_table, _changes = normalize_table_grid_structure(table)
normalized_tables.append(normalized_table)
total_dropped_columns += int(normalized_table.metadata.get("normalized_table_grid_dropped_columns") or 0)
total_merged_rows += int(normalized_table.metadata.get("normalized_table_grid_merged_rows") or 0)
return normalized_tables, total_dropped_columns, total_merged_rows
def _correct_table_name_cells(tables: list[Table], *, lexicon: list[str], max_distance: int) -> tuple[list[Table], int]:
if not lexicon:
return tables, 0
corrected_tables: list[Table] = []
total_corrections = 0
for table in tables:
name_headers = _table_name_headers(table)
if not name_headers:
corrected_tables.append(table)
continue
corrected_cells: list[TableCell] = []
table_corrections = 0
for cell in table.cells:
header_row = name_headers.get(cell.col)
if header_row is None or cell.row <= header_row:
corrected_cells.append(cell)
continue
replacement_text = _nearest_unique_lexicon_match(cell.text, lexicon=lexicon, max_distance=max_distance)
if replacement_text is None:
corrected_cells.append(cell)
continue
corrected_cells.append(_replace_cell(cell, text=replacement_text))
table_corrections += 1
if table_corrections:
from .tables import cells_to_html
metadata = dict(table.metadata)
metadata["table_name_lexicon_corrections"] = table_corrections
corrected_table = replace(
table,
cells=corrected_cells,
html=cells_to_html(corrected_cells),
metadata=metadata,
)
corrected_tables.append(corrected_table)
total_corrections += table_corrections
else:
corrected_tables.append(table)
return corrected_tables, total_corrections
def _table_name_headers(table: Table) -> dict[int, int]:
headers: dict[int, int] = {}
for cell in table.cells:
header = normalize_ocr_text(cell.text).strip().rstrip(":ः")
if edit_distance(header, "नाम") <= 1 and (cell.col not in headers or cell.row < headers[cell.col]):
headers[cell.col] = cell.row
return headers
def _nearest_unique_lexicon_match(text: str, *, lexicon: list[str], max_distance: int) -> str | None:
normalized = normalize_ocr_text(text).strip()
if not normalized:
return None
if normalized in lexicon:
return None
suffix = ""
match = re.match(r"^(?P<base>[^-\s]+)(?P<suffix>-[A-Za-z0-9०-९]+)$", normalized)
if match is not None:
normalized = match.group("base")
suffix = match.group("suffix")
if normalized in lexicon:
return None
scores = sorted((edit_distance(normalized, item), item) for item in lexicon)
if not scores or scores[0][0] > max_distance:
return None
if len(scores) > 1 and scores[1][0] == scores[0][0]:
return None
return f"{scores[0][1]}{suffix}"
"""Optional OCR engine adapters."""
from __future__ import annotations
import csv
import html
import json
import os
import re
import shutil
import subprocess
import tempfile
from dataclasses import dataclass, field, replace
from html.parser import HTMLParser
from pathlib import Path
from typing import Iterable, Protocol
from .errors import DataValidationError, EngineUnavailableError, ParseError
from .metrics import bbox_iou, edit_distance
from .models import ModelCard, audit_model_card
from .normalization import normalize_ocr_text
from .schemas import BBox, Figure, Page, Table, TableCell, TextLine, validate_confidence
class EngineOutput:
pages: list[Page]
tables: list[Table] = field(default_factory=list)
figures: list[Figure] = field(default_factory=list)
metadata: dict[str, object] = field(default_factory=dict)
def average_confidence(self) -> float | None:
values = [
line.confidence
for page in self.pages
for line in page.text_lines
if line.confidence is not None
]
return sum(values) / len(values) if values else None
class OcrEngine(Protocol):
name: str
def recognize(self, input_path: Path) -> EngineOutput:
"""Recognize an image or document and return page text lines."""
def _synthetic_lines_from_text(text: str, page_index: int = 0) -> list[TextLine]:
lines: list[TextLine] = []
y = 0
for index, raw_line in enumerate(text.splitlines()):
line_text = normalize_ocr_text(raw_line)
if not line_text.strip():
y += 28
continue
line = TextLine(
text=line_text,
bbox=BBox(0, y, max(50, len(line_text) * 9), 22),
confidence=1.0,
page_index=page_index,
line_id=f"p{page_index}-l{index}",
)
lines.append(line)
y += 28
return lines
def sidecar_candidates(input_path: Path) -> list[Path]:
if input_path.is_dir():
return [
input_path / "document.ocr.json",
input_path / "document.txt",
input_path / "document.md",
]
candidates = [
input_path.with_suffix(input_path.suffix + ".ocr.json"),
input_path.with_suffix(".ocr.json"),
input_path.with_suffix(input_path.suffix + ".txt"),
input_path.with_suffix(".txt"),
]
if input_path.suffix.lower() in {".txt", ".md"}:
candidates.insert(0, input_path)
unique: list[Path] = []
for candidate in candidates:
if candidate not in unique:
unique.append(candidate)
return unique
def has_sidecar(input_path: Path) -> bool:
return any(candidate.exists() for candidate in sidecar_candidates(input_path))
def _bundle_page_paths(input_path: Path) -> list[Path]:
if not input_path.is_dir():
return []
allowed_suffixes = {".png", ".jpg", ".jpeg", ".tif", ".tiff", ".bmp", ".webp"}
page_paths = [path for path in sorted(input_path.iterdir()) if path.is_file() and path.suffix.lower() in allowed_suffixes]