omnius 1.0.639 → 1.0.641

package/dist/scripts/ocr-advanced.py

@@ -37,6 +37,9 @@ import os
 import json
 import csv
 import argparse
+import signal
+import time
+from collections import OrderedDict
 from pathlib import Path
 
 def check_deps():
@@ -168,45 +171,175 @@ PSM_MODES = {
     11: "sparse",
 }
 
+# Advanced OCR is a bounded recovery pipeline, not a blind Cartesian product.
+# A 327x333 crop previously paid for 24 variants/PSMs and two Tesseract child
+# processes per attempt. Small inputs now begin with two high-yield attempts;
+# larger/low-evidence images expand only while budget remains.
+SMALL_CROP_AREA_PX = 512_000
+MEDIUM_IMAGE_AREA_PX = 2_000_000
+MAX_PIPELINE_DEADLINE_MS = 80_000
+MAX_TESSERACT_ATTEMPT_SECONDS = 12.0
+MIN_TESSERACT_ATTEMPT_SECONDS = 0.25
+MIN_ACCEPTED_CONFIDENCE = 50.0
+MIN_SUBSTANTIVE_TEXT_CHARS = 12
+HIGH_VOLUME_GARBAGE_CHARS = 64
+HIGH_VOLUME_GARBAGE_CONFIDENCE = 35.0
+ACTIVE_DEADLINE = None
+
+
+class OcrPipelineTimeout(RuntimeError):
+    pass
+
+
+class OcrPipelineCancelled(RuntimeError):
+    pass
+
+
+def cancellation_signal_handler(signum, _frame):
+    raise OcrPipelineCancelled(f"received signal {signum}")
+
+
+class OcrDeadline:
+    def __init__(self, deadline_ms):
+        self.deadline_ms = max(1_000, min(int(deadline_ms), MAX_PIPELINE_DEADLINE_MS))
+        self.started = time.monotonic()
+
+    def remaining_seconds(self):
+        return self.deadline_ms / 1000.0 - (time.monotonic() - self.started)
+
+    def check(self, stage):
+        if self.remaining_seconds() <= 0:
+            raise OcrPipelineTimeout(f"OCR deadline exceeded during {stage}")
+
+    def tesseract_timeout_seconds(self):
+        self.check("Tesseract scheduling")
+        return max(
+            MIN_TESSERACT_ATTEMPT_SECONDS,
+            min(MAX_TESSERACT_ATTEMPT_SECONDS, self.remaining_seconds()),
+        )
+
+
+def diagnostic(code, message, deadline, stage, attempts_completed=0, attempts_planned=0):
+    return {
+        "schema": "omnius.ocr-diagnostic.v1",
+        "code": code,
+        "message": message,
+        "stage": stage,
+        "deadline_ms": deadline.deadline_ms,
+        "attempts_completed": attempts_completed,
+        "attempts_planned": attempts_planned,
+    }
+
 
 # ---------------------------------------------------------------------------
 # OCR execution
 # ---------------------------------------------------------------------------
 
-def run_tesseract(binary_img, language="eng", psm=6):
-    """Run Tesseract on a preprocessed binary image.
-    Returns (text, confidence, line_count)."""
+def text_from_tesseract_data(data):
+    """Reconstruct line breaks from one TSV pass; do not spawn Tesseract twice."""
+    lines = OrderedDict()
+    texts = data.get("text", [])
+    for index, raw_text in enumerate(texts):
+        text = str(raw_text or "").strip()
+        if not text:
+            continue
+        key = tuple(
+            int(data.get(field, [0] * len(texts))[index] or 0)
+            for field in ("block_num", "par_num", "line_num")
+        )
+        lines.setdefault(key, []).append(text)
+    return "\n".join(" ".join(words) for words in lines.values()).strip()
+
+
+def run_tesseract(binary_img, deadline, language="eng", psm=6):
+    """Run one bounded Tesseract TSV pass and derive text plus confidence."""
+    deadline.check("Tesseract")
     pil_img = Image.fromarray(binary_img)
     config = f"--psm {psm}"
+    data = pytesseract.image_to_data(
+        pil_img,
+        lang=language,
+        config=config,
+        output_type=pytesseract.Output.DICT,
+        timeout=deadline.tesseract_timeout_seconds(),
+    )
+    text = text_from_tesseract_data(data)
+    confs = []
+    for value in data.get("conf", []):
+        try:
+            confidence = float(value)
+        except (TypeError, ValueError):
+            continue
+        if confidence >= 0:
+            confs.append(confidence)
+    avg_conf = sum(confs) / len(confs) if confs else 0.0
+    line_count = len([line for line in text.split("\n") if line.strip()])
+    return text, avg_conf, line_count
 
-    # Engine failures are not blank documents. Let callers distinguish a real
-    # low-information image from a missing language pack or broken Tesseract.
-    text = pytesseract.image_to_string(pil_img, lang=language, config=config).strip()
-
-    line_count = len([l for l in text.split("\n") if l.strip()])
 
-    # Get confidence via image_to_data
-    try:
-        data = pytesseract.image_to_data(
-            pil_img, lang=language, config=config,
-            output_type=pytesseract.Output.DICT,
+def assess_ocr_evidence(text, confidence, line_count):
+    """Classify OCR output before it can become agent-visible evidence."""
+    normalized = str(text or "").strip()
+    chars = len(normalized)
+    if chars == 0:
+        return {
+            "state": "low_information",
+            "accepted": False,
+            "reason": "no_readable_text",
+            "chars": 0,
+            "confidence": round(float(confidence), 1),
+            "lines": int(line_count),
+        }
+    alnum_ratio = sum(character.isalnum() for character in normalized) / max(1, chars)
+    if chars < MIN_SUBSTANTIVE_TEXT_CHARS and confidence < MIN_ACCEPTED_CONFIDENCE:
+        return {
+            "state": "low_information",
+            "accepted": False,
+            "reason": "insufficient_low_confidence_text",
+            "chars": chars,
+            "confidence": round(float(confidence), 1),
+            "lines": int(line_count),
+            "alnum_ratio": round(alnum_ratio, 3),
+        }
+    if (
+        (chars >= HIGH_VOLUME_GARBAGE_CHARS and confidence < HIGH_VOLUME_GARBAGE_CONFIDENCE)
+        or confidence < MIN_ACCEPTED_CONFIDENCE
+        or alnum_ratio < 0.45
+    ):
+        reason = (
+            "high_volume_low_confidence_text"
+            if chars >= HIGH_VOLUME_GARBAGE_CHARS and confidence < HIGH_VOLUME_GARBAGE_CONFIDENCE
+            else "low_confidence_or_symbol_heavy_text"
         )
-        confs = [int(c) for c in data["conf"] if int(c) >= 0]
-        avg_conf = sum(confs) / len(confs) if confs else 0.0
-    except Exception:
-        avg_conf = 0.0
-
-    return text, avg_conf, line_count
+        return {
+            "state": "rejected",
+            "accepted": False,
+            "reason": reason,
+            "chars": chars,
+            "confidence": round(float(confidence), 1),
+            "lines": int(line_count),
+            "alnum_ratio": round(alnum_ratio, 3),
+        }
+    return {
+        "state": "accepted",
+        "accepted": True,
+        "reason": "confidence_and_text_quality_met",
+        "chars": chars,
+        "confidence": round(float(confidence), 1),
+        "lines": int(line_count),
+        "alnum_ratio": round(alnum_ratio, 3),
+    }
 
 
-def compute_score(text, confidence, line_count):
+def compute_score(text, confidence, line_count, evidence=None):
     """Combined scoring heuristic:
       - confidence * sqrt(char_count)  — rewards quality and coverage
       - + line_count * 10              — bonus for structured output (more lines = better parse)
     The agent discovered that line-count is a strong proxy for successful parsing
     on structured documents like invoices and forms."""
+    quality = evidence or assess_ocr_evidence(text, confidence, line_count)
     char_count = len(text)
-    if char_count == 0:
+    if not quality["accepted"] or char_count == 0:
         return 0
     return confidence * (char_count ** 0.5) + line_count * 10
 
@@ -226,6 +359,29 @@ def extract_pixel_region(gray, x, y, w, h):
     return gray[y:y+h, x:x+w]
 
 
+def build_ocr_plan(image_area_px, single_psm=None):
+    """Return the smallest credible variant/PSM plan for the effective image."""
+    psm_modes = [single_psm] if single_psm else (
+        [6] if image_area_px <= SMALL_CROP_AREA_PX
+        else [6, 11] if image_area_px <= MEDIUM_IMAGE_AREA_PX
+        else [6, 11, 4]
+    )
+    variants = (
+        ["otsu", "adaptive_fine"] if image_area_px <= SMALL_CROP_AREA_PX
+        else ["otsu", "adaptive_fine", "denoise", "sharpen_unsharp"]
+        if image_area_px <= MEDIUM_IMAGE_AREA_PX
+        else list(ALL_VARIANTS.keys())
+    )
+    # OTSU/PSM6 is deliberately first: a legible result ends the search
+    # instead of paying for redundant variants that cannot improve the answer.
+    return [(variant, psm) for psm in psm_modes for variant in variants]
+
+
+def has_sufficient_evidence(text, confidence, line_count):
+    quality = assess_ocr_evidence(text, confidence, line_count)
+    return quality["accepted"] and confidence >= 70.0 and line_count >= 1
+
+
 # ---------------------------------------------------------------------------
 # Output writers
 # ---------------------------------------------------------------------------
@@ -295,142 +451,208 @@ def write_all_outputs(text, base_name, output_dir):
 # Main pipeline
 # ---------------------------------------------------------------------------
 
-def run_pipeline(image_path, language="eng", do_regions=False, debug_dir=None,
-                 single_psm=None, pixel_region=None, output_dir=None):
-    """Run the full multi-variant, multi-PSM OCR pipeline."""
-
-    # Load image
-    img = cv2.imread(image_path)
-    if img is None:
-        return {"error": f"Could not load image: {image_path}"}
-
-    h_orig, w_orig = img.shape[:2]
-    gray = to_grayscale(img)
-
-    # Upscale 2x
-    gray_2x = upscale_2x(gray)
-
-    # If a pixel region is specified, crop before processing
-    if pixel_region:
-        rx, ry, rw, rh = pixel_region
-        # Scale region coords to match 2x upscale
-        gray_2x = extract_pixel_region(gray_2x, rx * 2, ry * 2, rw * 2, rh * 2)
-
-    # Determine PSM modes to test
-    psm_modes = [single_psm] if single_psm else [4, 6, 11]
-
-    # Generate all variants and run OCR
+def run_variant_plan(gray, plan, deadline, language, debug_dir=None, debug_prefix="full"):
+    """Run a bounded plan, stopping early once a legible result is proven."""
     all_results = {}
     ocr_errors = []
     best_key = None
     best_score = -1
+    early_exit = False
 
-    for vname, vfunc in ALL_VARIANTS.items():
+    for vname, psm in plan:
+        deadline.check("preprocessing")
+        key = f"{vname}_psm{psm}"
         try:
-            binary = vfunc(gray_2x)
-        except Exception:
+            binary = ALL_VARIANTS[vname](gray)
+        except Exception as error:
+            ocr_errors.append(f"{key}: preprocessing failed: {error}")
             continue
-
-        # Save debug images
         if debug_dir:
             os.makedirs(debug_dir, exist_ok=True)
-            cv2.imwrite(os.path.join(debug_dir, f"full_{vname}.png"), binary)
-
-        for psm in psm_modes:
-            key = f"{vname}_psm{psm}"
-            try:
-                text, confidence, line_count = run_tesseract(binary, language, psm)
-            except Exception as error:
-                ocr_errors.append(f"{key}: {error}")
-                continue
-            char_count = len(text)
-            score = compute_score(text, confidence, line_count)
-
-            all_results[key] = {
-                "text": text,
-                "chars": char_count,
-                "lines": line_count,
-                "confidence": round(confidence, 1),
-                "score": round(score, 1),
-            }
-
-            if score > best_score:
-                best_score = score
-                best_key = key
-
-    if not best_key:
-        detail = ocr_errors[-1] if ocr_errors else "no preprocessing variant completed"
-        return {"error": f"Tesseract failed for every OCR variant: {detail}"}
-
-    best = all_results[best_key]
-    result = {
-        "text": best["text"],
-        "confidence": best["confidence"],
-        "variant": best_key,
-        "chars": best["chars"],
-        "lines": best["lines"],
-        "score": best["score"],
-        "image_size": f"{w_orig}x{h_orig}",
-        "variants_tested": len(all_results),
-        "all_variants": all_results,
-    }
-
-    # Region-based OCR
-    if do_regions:
-        regions = {}
-        region_defs = {
-            "header": (0, 35),
-            "body": (30, 80),
-            "footer": (75, 100),
+            cv2.imwrite(os.path.join(debug_dir, f"{debug_prefix}_{vname}.png"), binary)
+        try:
+            text, confidence, line_count = run_tesseract(binary, deadline, language, psm)
+        except OcrPipelineTimeout:
+            raise
+        except OcrPipelineCancelled:
+            raise
+        except Exception as error:
+            ocr_errors.append(f"{key}: {error}")
+            continue
+        char_count = len(text)
+        evidence = assess_ocr_evidence(text, confidence, line_count)
+        score = compute_score(text, confidence, line_count, evidence)
+        all_results[key] = {
+            "text": text,
+            "chars": char_count,
+            "lines": line_count,
+            "confidence": round(confidence, 1),
+            "score": round(score, 1),
+            "evidence": evidence,
         }
+        if evidence["accepted"] and score > best_score:
+            best_score = score
+            best_key = key
+        if has_sufficient_evidence(text, confidence, line_count):
+            early_exit = True
+            break
 
-        for rname, (y_start, y_end) in region_defs.items():
-            region_gray = extract_region(gray_2x, y_start, y_end)
-
-            if debug_dir:
-                cv2.imwrite(os.path.join(debug_dir, f"region_{rname}.png"), region_gray)
-
-            # Test all variants on each region for best accuracy
-            region_best = ""
-            region_best_score = -1
-
-            for vname in ["otsu", "denoise", "adaptive_fine", "sharpen_unsharp"]:
-                if vname not in ALL_VARIANTS:
-                    continue
-                try:
-                    binary = ALL_VARIANTS[vname](region_gray)
-                except Exception:
-                    continue
+    return all_results, ocr_errors, best_key, early_exit
 
-                if debug_dir:
-                    cv2.imwrite(os.path.join(debug_dir, f"region_{rname}_{vname}.png"), binary)
 
-                try:
-                    text, conf, lc = run_tesseract(binary, language, 6)
-                except Exception:
-                    continue
-                score = compute_score(text, conf, lc)
-                if score > region_best_score:
-                    region_best_score = score
-                    region_best = text
-
-            regions[rname] = region_best
+def run_pipeline(image_path, deadline, language="eng", do_regions=False, debug_dir=None,
+                 single_psm=None, pixel_region=None, output_dir=None):
+    """Run bounded OCR. The effective crop controls plan size, not the full frame."""
+    deadline.check("image load")
+    img = cv2.imread(image_path)
+    if img is None:
+        return {"error": f"Could not load image: {image_path}"}
 
-        result["regions"] = regions
+    h_orig, w_orig = img.shape[:2]
+    gray = to_grayscale(img)
+    if pixel_region:
+        rx, ry, rw, rh = pixel_region
+        if rx >= w_orig or ry >= h_orig:
+            return {"error": "Requested OCR region lies outside the image"}
+        gray = extract_pixel_region(gray, rx, ry, rw, rh)
+    if gray.size == 0:
+        return {"error": "Requested OCR region is empty"}
+
+    effective_area = int(gray.shape[0] * gray.shape[1])
+    deadline.check("image conditioning")
+    gray_2x = upscale_2x(gray)
+    plan = build_ocr_plan(effective_area, single_psm)
+    attempts_completed = 0
+    try:
+        all_results, ocr_errors, best_key, early_exit = run_variant_plan(
+            gray_2x, plan, deadline, language, debug_dir
+        )
+        attempts_completed = len(all_results)
+        if not best_key:
+            if not all_results:
+                detail = ocr_errors[-1] if ocr_errors else "no preprocessing variant completed"
+                return {"error": f"Tesseract failed for every bounded OCR attempt: {detail}"}
+            rejected = [item for item in all_results.values() if item["evidence"]["state"] == "rejected"]
+            if rejected:
+                worst = max(rejected, key=lambda item: (item["chars"], -item["confidence"]))
+                evidence = worst["evidence"]
+                message = (
+                    "OCR text was suppressed because it did not meet evidence-quality requirements "
+                    f"({evidence['reason']}; {evidence['chars']} chars at {evidence['confidence']}% confidence)."
+                )
+                return {
+                    "error": message,
+                    "diagnostic": {
+                        **diagnostic("ocr_evidence_rejected", message, deadline, "evidence_quality", attempts_completed, len(plan)),
+                        "evidence": evidence,
+                    },
+                }
+            # Empty or tiny non-substantive detections are valid observations:
+            # do not invent text and do not report them as a pipeline error.
+            result = {
+                "text": "",
+                "confidence": 0.0,
+                "variant": "none",
+                "chars": 0,
+                "lines": 0,
+                "score": 0.0,
+                "image_size": f"{w_orig}x{h_orig}",
+                "variants_tested": len(all_results),
+                "all_variants": {},
+                "quality": {
+                    "schema": "omnius.ocr-evidence.v1",
+                    "state": "low_information",
+                    "accepted": False,
+                    "reason": "no_accepted_readable_text",
+                    "low_information_variants": len(all_results),
+                },
+                "diagnostic": diagnostic(
+                    "ocr_low_information",
+                    "OCR produced no accepted readable text; the result is low-information rather than evidence.",
+                    deadline,
+                    "evidence_quality",
+                    attempts_completed,
+                    len(plan),
+                ),
+                "strategy": {
+                    "effective_area_px": effective_area,
+                    "attempts_planned": len(plan),
+                    "attempts_completed": attempts_completed,
+                    "early_exit": False,
+                    "deadline_ms": deadline.deadline_ms,
+                },
+            }
+            return result
 
-    if debug_dir:
-        result["debug_dir"] = debug_dir
+        best = all_results[best_key]
+        accepted_results = {
+            key: value for key, value in all_results.items()
+            if value["evidence"]["state"] == "accepted"
+        }
+        result = {
+            "text": best["text"],
+            "confidence": best["confidence"],
+            "variant": best_key,
+            "chars": best["chars"],
+            "lines": best["lines"],
+            "score": best["score"],
+            "image_size": f"{w_orig}x{h_orig}",
+            "variants_tested": len(all_results),
+            # Never leak rejected raw OCR as alternate evidence to agents.
+            "all_variants": accepted_results,
+            "quality": {
+                "schema": "omnius.ocr-evidence.v1",
+                **best["evidence"],
+                "rejected_variants": sum(
+                    1 for item in all_results.values() if item["evidence"]["state"] == "rejected"
+                ),
+                "low_information_variants": sum(
+                    1 for item in all_results.values() if item["evidence"]["state"] == "low_information"
+                ),
+            },
+            "strategy": {
+                "effective_area_px": effective_area,
+                "attempts_planned": len(plan),
+                "attempts_completed": attempts_completed,
+                "early_exit": early_exit,
+                "deadline_ms": deadline.deadline_ms,
+            },
+        }
 
-    # Write output files if output_dir specified
-    if output_dir:
-        base_name = Path(image_path).stem
-        files = write_all_outputs(best["text"], base_name, output_dir)
-        result["output_files"] = files
+        if do_regions:
+            regions = {}
+            region_defs = {"header": (0, 35), "body": (30, 80), "footer": (75, 100)}
+            for rname, (y_start, y_end) in region_defs.items():
+                deadline.check(f"region {rname}")
+                region_gray = extract_region(gray_2x, y_start, y_end)
+                # Region requests use at most two high-yield attempts. The
+                # main result already provides full-frame coverage.
+                region_plan = build_ocr_plan(region_gray.shape[0] * region_gray.shape[1], single_psm)[:2]
+                region_results, _errors, region_best_key, _early_exit = run_variant_plan(
+                    region_gray, region_plan, deadline, language, debug_dir, f"region_{rname}"
+                )
+                regions[rname] = region_results[region_best_key]["text"] if region_best_key else ""
+            result["regions"] = regions
 
-    return result
+        if debug_dir:
+            result["debug_dir"] = debug_dir
+        if output_dir:
+            base_name = Path(image_path).stem
+            result["output_files"] = write_all_outputs(best["text"], base_name, output_dir)
+        return result
+    except OcrPipelineTimeout as error:
+        return {
+            "error": str(error),
+            "diagnostic": diagnostic("ocr_timeout", str(error), deadline, "pipeline", attempts_completed, len(plan)),
+        }
+    except OcrPipelineCancelled as error:
+        return {
+            "error": "Advanced OCR cancelled",
+            "diagnostic": diagnostic("ocr_cancelled", str(error), deadline, "pipeline", attempts_completed, len(plan)),
+        }
 
 
-def run_batch(images_dir, language="eng", do_regions=False, debug_dir=None,
+def run_batch(images_dir, deadline, language="eng", do_regions=False, debug_dir=None,
               output_dir=None):
     """Process all images in a directory."""
     images_dir = os.path.abspath(images_dir)
@@ -450,10 +672,18 @@ def run_batch(images_dir, language="eng", do_regions=False, debug_dir=None,
         return {"error": f"No image files found in {images_dir}"}
 
     for img_file in image_files:
+        try:
+            deadline.check("batch scheduling")
+        except OcrPipelineTimeout as error:
+            return {
+                "error": str(error),
+                "diagnostic": diagnostic("ocr_timeout", str(error), deadline, "batch", len(batch_results), len(image_files)),
+            }
         img_path = os.path.join(images_dir, img_file)
         img_debug = os.path.join(debug_dir, Path(img_file).stem) if debug_dir else None
         result = run_pipeline(
             img_path,
+            deadline,
             language=language,
             do_regions=do_regions,
             debug_dir=img_debug,
@@ -469,6 +699,14 @@ def run_batch(images_dir, language="eng", do_regions=False, debug_dir=None,
             "output_files": result.get("output_files"),
             "error": result.get("error"),
         }
+        if result.get("diagnostic", {}).get("code") in {"ocr_timeout", "ocr_cancelled"}:
+            return {
+                "error": result["error"],
+                "diagnostic": result["diagnostic"],
+                "batch": True,
+                "images_processed": len(batch_results),
+                "results": batch_results,
+            }
 
     # Write summary
     summary_path = os.path.join(out_dir, "OCR_PROCESSING_SUMMARY.md")
@@ -497,6 +735,7 @@ def run_batch(images_dir, language="eng", do_regions=False, debug_dir=None,
 
 
 def main():
+    global ACTIVE_DEADLINE
     parser = argparse.ArgumentParser(
         description="Advanced multi-variant OCR pipeline for omnius"
     )
@@ -520,13 +759,20 @@ def main():
                         help="Write TXT + CSV + PDF outputs to this directory")
     parser.add_argument("--batch", action="store_true",
                         help="Process all images in a directory")
+    parser.add_argument("--deadline-ms", type=int, default=MAX_PIPELINE_DEADLINE_MS,
+                        help="Bound total OCR work; clamped to the managed maximum")
 
     args = parser.parse_args()
+    deadline = OcrDeadline(args.deadline_ms)
+    ACTIVE_DEADLINE = deadline
+    signal.signal(signal.SIGTERM, cancellation_signal_handler)
+    signal.signal(signal.SIGINT, cancellation_signal_handler)
 
     # Batch mode
     if args.batch or os.path.isdir(args.image):
         result = run_batch(
             args.image,
+            deadline,
             language=args.language,
             do_regions=args.regions,
             debug_dir=args.debug_dir,
@@ -558,6 +804,7 @@ def main():
 
     result = run_pipeline(
         args.image,
+        deadline,
         language=args.language,
         do_regions=args.regions,
         debug_dir=args.debug_dir,
@@ -578,4 +825,19 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except OcrPipelineTimeout as error:
+        deadline = ACTIVE_DEADLINE or OcrDeadline(MAX_PIPELINE_DEADLINE_MS)
+        print(json.dumps({
+            "error": str(error),
+            "diagnostic": diagnostic("ocr_timeout", str(error), deadline, "entrypoint"),
+        }))
+        sys.exit(124)
+    except OcrPipelineCancelled as error:
+        deadline = ACTIVE_DEADLINE or OcrDeadline(MAX_PIPELINE_DEADLINE_MS)
+        print(json.dumps({
+            "error": "Advanced OCR cancelled",
+            "diagnostic": diagnostic("ocr_cancelled", str(error), deadline, "entrypoint"),
+        }))
+        sys.exit(130)