OCR Parser Optimizer

OCR Parser Optimizer

Iterative, batch-driven optimization loop for the 10 built-in mica-ppocr-structured parsers. The skill is not a metric calculator (use ocr-accuracy-checker for that) and not a parser authoring kit (use mica-ppocr-custom-parser for new types). It sits between the two: given a real batch of samples, it diagnoses why a field-level check fails, proposes a minimal, localized fix, and re-verifies until the target is met.

When to invoke

• User provides an image directory or PDF directory and asks to "调优 / 优化 / 修一下 / 看哪些样本解析不对" a specific parser (e.g. 行驶证 / 身份证 / 增值税发票 / 出租车票).
• User reports a regression ("升级后 X 字段错了") and wants to reproduce + diagnose on a batch.
• User wants to extend a parser's tolerance to a new document variant (e.g. 横向打印的营业执照, 异形发票) by feeding a few real samples.

Do not invoke for: one-off single-image debugging (use BaseTest directly), pure metric calculation on labeled data (ocr-accuracy-checker), or building a brand-new parser from scratch (mica-ppocr-custom-parser).

Inputs the agent should ask for up front

Always confirm these slots in one round with AskUserQuestion before doing any work.

Workflow (the optimization loop)

1.  prepare   --  collect input, ground truth, model tier
2.  baseline  --  run BatchOcrMain-style batch, compute per-field pass-rate
3.  diagnose  --  classify each failure into a Failure Pattern (see taxonomy)
4.  propose   --  emit minimal fix proposal (LabelMatcher / regex / heuristic)
5.  apply     --  edit the parser file in-place; preserve Java 8 + Lombok @Value constraints
6.  re-verify --  re-run baseline; compare; record metrics
7.  iterate   --  loop 3-6 until target hit or no fix improves metrics
8.  report    --  write optimization-reports/<parser>-<timestamp>.md

1. Prepare

• Walk the input directory:
  • image-dir: CollUtil.listOf("png","jpg","jpeg","bmp","webp")
  • pdf-dir: recursive, every *.pdf; remind the user that PDF is a dual channel (text layer + OCR fallback) and tuning the parser only affects the OCR fallback path.
• Copy a few samples (3-5) into test_images/<parser>/ if not already present so BaseTest<Parser, Result> single-image debug is available.
• If ground truth provided, load it once into a Map<String, Map<String,String>>.

2. Baseline

• For images, leverage the existing BatchOcrMain entry. Either invoke it as a subprocess (Maven exec:java) or, in agent mode, replicate its core loop using PPOcrV6Engine.run(Path) / run(byte[]) and a ParserSpec instance.
• For PDFs, use PPOcrV6Engine.run(Path) directly (it auto-sniffs %PDF- and flattens all pages). One file may produce N per-page results; the diagnosis needs to be page-aware.
• Persist raw outputs to optimization-reports/<parser>-<timestamp>/raw/<file>.txt so each iteration diffs cleanly.
• If ground truth exists, compute field-level precision / recall / F1 with the ocr-accuracy-checker conventions (string equality + whitespace-trimmed compare).

3. Diagnose (Failure Pattern taxonomy)

Always classify every failure into exactly one of these buckets before proposing a fix. The mapping is the heart of this skill.

When in doubt, render the failure sample with BaseTest.saveVis (green boxes for OCR regions; overlay the field's matched box) and look at the picture. Most F1/F4/F5 cases are obvious once visualized.

4. Propose a fix

Always emit a minimal, localized fix proposal. Match the pattern to one of these templates:

• F1 → add the OCR-mangled form to the label variant list:

  // was: matchValue(results, "号牌号码")
  // after:
  findLabelBox(results, "号牌号码", "号牌编码", "号牌号吗")  // if such helper exists

  or relax the matcher. If the parser uses a literal string, list all observed OCR variants seen in the raw output of step 2 and feed them as alternates.

• F2 → widen the right-overlap tolerance:

  matchValue(results, label, LabelMatcher.DEFAULT_RIGHT_OVERLAP_TOLERANCE) // 5 -> 8

  or add a manual y-bias when the label and value rows are visually adjacent.

• F3 → loosen the regex: [\\d\\s-]{6,} instead of \\d{6,8}; add optional spaces / dashes that OCR inserts; allow · for * masking.

• F4 → prefer the value box with the largest y-overlap to the label box, not the leftmost. If two labels are visually adjacent, anchor on the label's y-center and pick the value box whose y-center is closest within ±N px.

• F5 → swap matchValue → matchValueFromPrefix.

• F6 → not a parser bug; recommend tier bump or region pre-crop. Do not change the parser for this.

• F7 → recommend tier bump. Do not change the parser for this.

• F8 → re-think IdCardSide / InvoiceVersion heuristics. Common fix: tighten top-region keyword list (e.g. add 中华人民共和国 for the 户口本 cover side).

• F9 → preserve the matched box from matchValueWithBox / matchSubstringWithBox instead of re-deriving it from text. Use the box the matcher actually returned.

Output the proposal as a unified diff against the parser file. Never rewrite the whole parser; only the failing field's match site.