#!/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())