ocr-projects-archive / ocr-tech /tools /audit_limbu_book_line_split_suggestions.py
prosperious's picture
Add 1000 files (ocr-tech/tests/test_audit_limbu_book_missed_line_review_coverage.py ...)
d82db76 verified
Raw History Blame Contribute Delete
11 kB
#!/usr/bin/env python3
"""Audit Limbu book-line split suggestion artifacts."""
from __future__ import annotations
import argparse
import csv
import json
from collections import Counter
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from ocrtech.manifest import sha256_file
REPORT_JSON = "book-line-split-suggestions.json"
SUGGESTIONS_TSV = "book-line-split-suggestions.tsv"
SUGGESTIONS_HTML = "book-line-split-suggestions.html"
AUDIT_JSON = "book-line-split-suggestions-audit.json"
REQUIRED_TSV_FIELDS = {
"packet_row_id",
"book_page_id",
"book_line_id",
"review_status",
"bbox",
"text",
"segment_count",
"suggested_split_bboxes",
"crop_path",
"crop_sha256",
"overlay_path",
"overlay_sha256",
"threshold",
"reason",
}
def _read_json_object(path: Path, issues: list[str], *, label: str) -> dict[str, Any] | None:
if not path.is_file():
issues.append(f"{label} is missing: {path}")
return None
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
issues.append(f"{label} is invalid JSON: {exc}")
return None
if not isinstance(payload, dict):
issues.append(f"{label} must contain a JSON object")
return None
return payload
def _read_tsv(path: Path, issues: list[str]) -> tuple[list[dict[str, str]], list[str]]:
if not path.is_file():
issues.append(f"suggestions TSV is missing: {path}")
return [], []
try:
with path.open("r", encoding="utf-8", newline="") as handle:
reader = csv.DictReader(handle, delimiter="\t")
if reader.fieldnames is None:
issues.append(f"suggestions TSV has no header: {path}")
return [], []
return [dict(row) for row in reader], list(reader.fieldnames)
except OSError as exc:
issues.append(f"suggestions TSV could not be read: {type(exc).__name__}: {exc}")
return [], []
def _path_from_report(report: dict[str, Any], key: str, issues: list[str]) -> Path | None:
value = report.get(key)
if not isinstance(value, str) or not value:
issues.append(f"report missing string {key}")
return None
return Path(value)
def _check_sha(path: Path | None, expected: object, issues: list[str], *, label: str) -> str | None:
if path is None:
return None
if not path.is_file():
issues.append(f"{label} is missing: {path}")
return None
actual = sha256_file(path)
if not isinstance(expected, str) or not expected:
issues.append(f"{label} missing recorded SHA-256")
elif actual != expected:
issues.append(f"{label} SHA-256 mismatch: recorded={expected} actual={actual} path={path}")
return actual
def _parse_bbox_list(value: str, issues: list[str], *, label: str) -> list[float] | None:
try:
payload = json.loads(value)
except json.JSONDecodeError as exc:
issues.append(f"{label} invalid bbox JSON: {exc}")
return None
if not isinstance(payload, list) or len(payload) != 4:
issues.append(f"{label} bbox must be a 4-item list")
return None
box: list[float] = []
for item in payload:
if not isinstance(item, int | float):
issues.append(f"{label} bbox contains non-numeric value: {payload!r}")
return None
box.append(float(item))
if box[2] <= 0 or box[3] <= 0:
issues.append(f"{label} bbox width/height must be positive: {payload!r}")
return None
return box
def _parse_split_boxes(value: str, issues: list[str], *, label: str) -> list[list[float]]:
try:
payload = json.loads(value)
except json.JSONDecodeError as exc:
issues.append(f"{label} invalid suggested_split_bboxes JSON: {exc}")
return []
if not isinstance(payload, list):
issues.append(f"{label} suggested_split_bboxes must be a list")
return []
boxes: list[list[float]] = []
for index, item in enumerate(payload, start=1):
box = _parse_bbox_list(json.dumps(item, ensure_ascii=False), issues, label=f"{label} split box {index}")
if box is not None:
boxes.append(box)
if len(boxes) < 2:
issues.append(f"{label} must contain at least two split boxes")
return boxes
def _audit_rows(
rows: list[dict[str, str]],
fieldnames: list[str],
report: dict[str, Any],
issues: list[str],
warnings: list[str],
) -> dict[str, Any]:
missing_fields = sorted(REQUIRED_TSV_FIELDS - set(fieldnames))
if missing_fields:
issues.append(f"suggestions TSV missing required fields: {missing_fields}")
row_ids: set[str] = set()
reason_counts: Counter[str] = Counter()
segment_total = 0
overlay_count = 0
for line_number, row in enumerate(rows, start=2):
row_id = str(row.get("packet_row_id") or "").strip()
label = f"suggestions TSV row {line_number} ({row_id or 'missing-id'})"
if not row_id:
issues.append(f"{label} missing packet_row_id")
elif row_id in row_ids:
issues.append(f"duplicate packet_row_id: {row_id}")
row_ids.add(row_id)
if str(row.get("review_status") or "").strip().lower() != "pending":
warnings.append(f"{label} review_status is not pending")
_parse_bbox_list(str(row.get("bbox") or ""), issues, label=label)
split_boxes = _parse_split_boxes(str(row.get("suggested_split_bboxes") or ""), issues, label=label)
try:
segment_count = int(str(row.get("segment_count") or ""))
except ValueError:
issues.append(f"{label} segment_count is not an integer: {row.get('segment_count')!r}")
segment_count = -1
if segment_count != len(split_boxes):
issues.append(f"{label} segment_count mismatch: recorded={segment_count} actual={len(split_boxes)}")
if segment_count > 0:
segment_total += segment_count
try:
threshold = int(str(row.get("threshold") or ""))
except ValueError:
issues.append(f"{label} threshold is not an integer: {row.get('threshold')!r}")
else:
if not 0 <= threshold <= 255:
issues.append(f"{label} threshold outside 0..255: {threshold}")
reason = str(row.get("reason") or "").strip()
if not reason:
issues.append(f"{label} missing reason")
else:
reason_counts[reason] += 1
crop_path = Path(str(row.get("crop_path") or ""))
expected_crop_sha = str(row.get("crop_sha256") or "")
_check_sha(crop_path, expected_crop_sha, issues, label=f"{label} crop")
overlay_path = Path(str(row.get("overlay_path") or ""))
expected_overlay_sha = str(row.get("overlay_sha256") or "")
if _check_sha(overlay_path, expected_overlay_sha, issues, label=f"{label} overlay") is not None:
overlay_count += 1
if report.get("suggestion_count") != len(rows):
issues.append(f"suggestion_count mismatch: recorded={report.get('suggestion_count')} actual={len(rows)}")
if report.get("overlay_count") != overlay_count:
issues.append(f"overlay_count mismatch: recorded={report.get('overlay_count')} actual={overlay_count}")
report_suggestions = report.get("suggestions")
if isinstance(report_suggestions, list):
report_ids = [item.get("packet_row_id") for item in report_suggestions if isinstance(item, dict)]
if report_ids != [row.get("packet_row_id") for row in rows]:
issues.append("report suggestions order/ids do not match TSV rows")
else:
issues.append("report suggestions must be a list")
return {
"suggestion_count": len(rows),
"segment_total": segment_total,
"overlay_count": overlay_count,
"reason_counts": dict(sorted(reason_counts.items())),
}
def audit_suggestions(suggestions_dir: str | Path, audit_dir: str | Path | None = None) -> dict[str, Any]:
root = Path(suggestions_dir)
issues: list[str] = []
warnings: list[str] = []
report_path = root / REPORT_JSON
report = _read_json_object(report_path, issues, label=REPORT_JSON)
row_summary: dict[str, Any] = {}
if report is not None:
if report.get("tool") != "tools/prepare_limbu_book_line_split_suggestions.py":
issues.append(f"unexpected report tool: {report.get('tool')!r}")
if report.get("out") != str(root):
issues.append(f"report out mismatch: recorded={report.get('out')!r} actual={str(root)!r}")
review_packet = _path_from_report(report, "review_packet", issues)
suggestions_tsv = _path_from_report(report, "suggestions_tsv", issues)
suggestions_html = _path_from_report(report, "suggestions_html", issues)
_check_sha(review_packet, report.get("review_packet_sha256"), issues, label="review packet TSV")
_check_sha(suggestions_tsv, report.get("suggestions_tsv_sha256"), issues, label="suggestions TSV")
_check_sha(suggestions_html, report.get("suggestions_html_sha256"), issues, label="suggestions HTML")
rows, fieldnames = _read_tsv(suggestions_tsv or root / SUGGESTIONS_TSV, issues)
row_summary = _audit_rows(rows, fieldnames, report, issues, warnings)
boundary = str(report.get("claim_boundary") or "")
if "reviewers must verify" not in boundary or "visual split suggestions only" not in boundary:
warnings.append("claim_boundary does not clearly state reviewer verification requirement")
audit = {
"created_at_utc": datetime.now(UTC).isoformat(),
"tool": "tools/audit_limbu_book_line_split_suggestions.py",
"suggestions_dir": str(root),
"report": str(report_path),
"report_sha256": sha256_file(report_path) if report_path.is_file() else None,
"audit_passed": not issues,
"operational_review_aid_safe": not issues,
"issues": issues,
"warnings": warnings,
"claim_boundary": "artifact consistency audit for split suggestions; it does not certify OCR quality or apply split repairs",
**row_summary,
}
out = Path(audit_dir) if audit_dir is not None else root
out.mkdir(parents=True, exist_ok=True)
(out / AUDIT_JSON).write_text(json.dumps(audit, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
return audit
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--suggestions-dir", type=Path, required=True)
parser.add_argument("--audit-dir", type=Path)
args = parser.parse_args(argv)
audit = audit_suggestions(args.suggestions_dir, args.audit_dir)
print(f"audit_passed={audit['audit_passed']} issues={len(audit['issues'])}")
return 0 if audit["audit_passed"] else 1
if __name__ == "__main__":
raise SystemExit(main())