Tesseract Confidence Verdict

Decide whether a Tesseract read can be TRUSTED, from the table you already have. Pure function: no I/O, no OCR, no dependency on pytesseract or the tesseract binary.

Built for tesseract 5.5.3 / pytesseract 0.3.13. Not affiliated with or endorsed by the Tesseract project.

THE SILENT FAILURE, AND IT RUNS IN BOTH DIRECTIONS.

image_to_data returns a FLAT table that interleaves four levels of a document hierarchy with the words. Only words carry a confidence; every structural row carries -1. Nothing in the Python API says so -- the image_to_data docstring reads, in full, "Returns string containing box boundaries, confidences, and other information."

MEASURED, on a clean two-word page:

  level=1  conf=-1   text=''          page
  level=2  conf=-1   text=''          block
  level=3  conf=-1   text=''          paragraph
  level=4  conf=-1   text=''          line
  level=5  conf=95   text='Invoice'   word
  level=5  conf=93   text='40071'     word

  naive mean over the column = 30.67
  true mean over the words   = 94.00
  understatement             = 3.07x

A pipeline gating on mean_conf > 50 discards that page. The page is perfect, and nothing is logged.

AND CORRECTING THAT IS NOT ENOUGH, BECAUSE THE OPPOSITE ERROR IS WORSE. Confidence answers how sure the classifier is about these glyphs, not whether this is the number that was on the page. Measured, same source number 40071 under two degradations:

  SPLIT     '4007' at conf 71 and '1' at conf 71. A parser taking the first number reads 4007 -- off by a factor of ten, and still a perfectly valid number that nothing downstream can reject. 71 clears a naive per-word gate and passes a mean-based one.
  INSERTED  '400771' at conf 77, which passes almost every gate anyone writes.

THE MEAN CANNOT SEE THE WORD YOU CARE ABOUT. Measured word confidences [96, 77, 20, 97] give a mean of 72.50 while one word sits at 20. A gate at 60 on the mean ADMITS that page. The statistic that decides trust is the MINIMUM, and fixing the -1 bug does not get you there -- it just gives you a correct mean that still admits the page whose one broken field is the one you needed.

AND THE DOCUMENTED FALLBACK REFUSES TO RUN. image_to_osd is the documented way to detect a rotated page. Measured on both a sparse and a denser rotated page, it RAISES: TesseractError, "Too few characters. Skipping this page." Orientation detection needs far more text than a receipt, a label or a single-line invoice carries -- exactly the documents most likely to be fed in sideways. Meanwhile a 180-rotated page returned 'LZ007 99IOAU|' at a word mean of 54.50, above a naive gate of 50. That failure is LOUD, so it is not sold here as a defect; it matters because it removes the fallback and leaves confidence as the only signal.

IT REFUSES RATHER THAN GUESSING. A page with no recognised words returns REFUSED, never a confidence of 0. Zero is a measurement; this is an absence, and a package that answers "0% confident" to a question it never measured is worse than one that declines. The refusal still reports every statistic that COULD be computed, because a refusal that does not carry its numbers is a package saying "I have no idea, and I am certain of that."

SCOPE, STATED PLAINLY: this does not do OCR, does not improve OCR, and does not tell you the right answer. If your pipeline already gates on min(word_conf) and independently establishes orientation, you have the two things this package is for and you do not need it.

VERIFIED: 22 tests, measured by running the suite. The reproduction script ships in evidence/ and regenerates every number above against your own Tesseract version.

DELIVERY: free, signed download of a hash-verified tarball, immediately. Full source, no card, no trial, no expiry.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateTesseractConfidence(input: ConfidenceInput): Verdict;

  export type Severity = "critical" | "warning" | "note";