PDF Classifier

What it is for

OCR is the expensive step in any document pipeline — whether the cost is per-page cloud pricing, GPU time, or an afternoon of someone’s attention. In most real archives a large share of the PDFs already carry a perfectly good text layer and need no OCR at all, while others carry one that looks present and is quietly useless. Sorting those apart by hand does not scale, and guessing wrong is expensive in both directions: OCR everything and you pay for work already done; trust the text layer blindly and you extract garbage.

PDF Classifier is the step before the expensive step. Point it at a file or a folder, and it tells you, page by page, which pages need OCR and which do not — then gets out of the way.

How it decides

“Does this PDF have a text layer?” is the wrong question — plenty of PDFs have one that is unusable. Each page is judged on the things that actually predict whether extraction will work:

• Text density, measured against the space the page actually occupies.
• Artifacts — (cid:123) sequences, replacement characters, mojibake from a bad encoding.
• Script consistency, so a page that drifts between alphabets is caught.
• Bounding-box coverage and reading order, which is where a technically-present text layer usually fails.

The result is a per-page and per-document verdict, and a recommended processing mode that downstream tooling can route on directly, rather than a coarse yes-or-no flag. A document is rarely uniformly good or bad, and the per-page verdict is what lets you OCR six pages of a two-hundred-page report instead of all of it.

Where the verdict lives

By default the summary is written back into the PDF itself as namespaced XMP metadata, with a compact DocInfo fallback and roundtrip verification. That makes the file self-describing: whatever moves it next can read the decision without a companion file to lose or a database to query. Re-embedding replaces the previous block in place rather than leaving stale classification data beside it.

Embedded metadata is checked against a content fingerprint before it is trusted, so a PDF that was re-saved after classification is never silently treated as already classified — the one failure mode that would quietly corrupt a routing decision.

Alongside that, every scan writes run-level JSONL and CSV reports and records itself in a local SQLite history that survives deleting or moving a run’s output folder. Sidecar JSON is available but off by default, and when enabled its location is explicit rather than assumed. CSV exports carry a UTF-8 byte-order mark, so Excel renders Cyrillic and Azerbaijani text instead of guessing the system codepage.

The desktop application

The app opens by asking which of two jobs you are doing, before the database is touched at all.

The regular application has seven tabs. Dashboard shows all-time and last-run statistics with clickable drilldowns straight into filtered results. Scan runs a folder, recursively, with excludes. Results filters, searches, exports and offers a context menu, with per-row columns for classification source, completeness and sidecar write status, and tinting for dry runs. PDF Detail gives a per-page table, a page preview, a provenance summary, and a three-way human-review override that persists. Metadata, Settings and Logs complete it, with settings separating appearance and persistence from classification thresholds. Single-file actions run on a background thread, so the window never freezes mid-scan.

Quick One-File Classification does exactly one PDF with no database involved — no connection, no migration, no run recorded, no effect on the dashboard or history. It reuses the same classifier, the same review interface and the same metadata schema as the full workflow, and stamps its output so it stays import-ready if you later decide it belongs in the record.

Also a command line and a library

Everything the interface does is available from the CLI — classify one file, scan a tree, read, verify or embed metadata, set a human override — and a small Python API exposes the routing decision to downstream OCR tools directly, so the classifier can sit inside a pipeline rather than in front of a person.

Languages

Language reporting is deliberately narrow. English, Russian and Azerbaijani are reported as document languages; mixed documents among them are expected rather than penalised, and formula symbols are treated as scientific notation rather than as language text. Other scripts are used as artifact and unsupported-script diagnostics, but are never claimed as supported OCR routes — a claim the tool cannot honestly make is worse than no claim.

What it deliberately does not do