How sure the conversion is

A conversion that goes wrong does not raise. It returns a document, and the document is short, or garbled, or empty. Docling grades its own work so you can find those without reading them.

from docling.document_converter import DocumentConverter

result = DocumentConverter().convert("returns.pdf")
print(result.confidence.mean_grade)
print(result.confidence.low_grade)

Two grades from a scale of poor, fair, good and excellent. mean_grade averages the whole document and low_grade reports its worst part. They already disagree on this two page file: the average is excellent and something in it is only good. That gap is the interesting number, because it is what catches a clean report with one scanned page in the middle.

Per page

for number, page in sorted(result.confidence.pages.items()):
    print("page", number, page.mean_grade)

There is the gap. Page 2 is excellent and page 1 only good, so low_grade was reporting page 1. On a file this small the difference is not worth chasing; on a two hundred page report it is the page number to open first.

Use the grades, not the scores

print(round(result.confidence.layout_score, 2))
print(result.confidence.ocr_score)

There are numbers underneath, and the documentation asks you not to build on them: how they are computed and weighted is allowed to change between versions. The OCR score is nan here because no character was read by OCR, and a table score exists but is not implemented yet.

A format with no grade at all

html = DocumentConverter().convert("refunds.html")
print(html.confidence.mean_grade)

Unspecified. Grading is about how well a page was read, and an HTML file was not read from a page, so there is nothing to grade. Any report that mixes formats has to expect this value, and the one in lesson 28 does.

What to do with it

The useful shape is a threshold. Index anything graded good or excellent, put the rest in a list for a person to look at, and never silently accept a document that came back poor.

grade = result.confidence.mean_grade.value
print("index it" if grade in ("good", "excellent") else "review it")