Skip to content

Audit a folder

Terminal window
complydoc audit ~/contracts

Reads every document in the folder, writes a JSON report to .complydoc, and prints a summary. complydoc ui opens it in the viewer.

--ocr recognises pages with no text layer. Without it such a page contributes no text, and the run reports it as unread.

The report is meant to be shared, so it carries no identifier in the clear:

  • Findings show each value masked to its last few characters.
  • Page text is kept, so a reading can be checked against the page, with every identifier that was found replaced by its masked form. --no-extracted-text leaves the text out altogether.
  • Pages carry no picture unless one is asked for. With --detail full the viewer draws each as a wireframe: where the text, images and findings sit, without the content.

Masking is only as complete as detection: a name the model did not recognise is still in the page text.

Two flags change that, and both are announced when the run starts and recorded as an important limitation in the report:

Flag Adds
--page-images A picture of each page, as a JPEG in the .parts folder beside the report, with the identifiers found on it blacked out. A page with an identifier that cannot be placed has no picture. With --reveal the pictures are as the pages are
--reveal Every value unmasked, in the findings, the page text and --save-text files

The JSON is written in one of two shapes, and run.report_detail says which:

--detail Carries 200 one-page documents
summary (default) Every finding, score and limitation, and the folder’s cost on each model 4.6 MB
full All of that, plus the price of every document on every model, and the page geometry the viewer draws pages with 20.3 MB

Use --detail full on audit or cost when you need a single document’s price on a given model, or when something reprocesses the reports, since a summary reads back without the parts it left out. In Python, cd.write_json(report, path, detail="full").

Page pictures are never written into the JSON, whichever the shape: they are most of a large report, and whatever reads it would have to hold them all. Each is a JPEG in a folder beside the report, complydoc.parts/pages/ for complydoc.json, named in its page’s image. Keep or move the folder with the report; complydoc ui shows a page’s picture from it.

A report whose page text and page layout pass 16 MB keeps those beside it too, one file per document in complydoc.parts/documents/, named in the document’s parts. What each page is priced and listed by stays in the JSON, with each reading of a page standing as … where the reader read text and as empty where it read none. cd.load_report puts the files back, and complydoc ui fetches a document’s when it is opened, so a folder of thousands of pages opens without reading them all. The report is also written without indentation then. A smaller report is one file, but for its pictures.

Readiness (global readiness in the report) is one number for can these documents go through a pipeline at all, from three factors, with the weights printed beside them:

Factor Asks
Content Can the text be got off the page
Cost path Whether pages have to be sent as images
Exposure What it carries that should not leave

A factor the run did not measure is excluded and the remaining weights are renormalised. The ring shows how many documents fall in each band.

Quick wins lists remediable findings, ordered by the number of documents affected. Each carries an actor of complydoc or you, and a saving where one follows from prices in the same report. No entry predicts a resulting score.

audit_a_folder.py
"""Audit a folder and read the headline numbers off the result."""
import complydoc as cd
report = cd.full_audit("src/complydoc/sample")
print(f"{report.overall.score}/100 — {report.overall.label}")
for factor in report.overall.factors:
measured = factor.score if factor.measured else "not measured"
print(f" {factor.name:10} {measured} (weight {factor.weight:.0%})")
print(f"\n{report.overall.bands}")
for win in report.quick_wins:
print(f"[{win.actor}] {win.title} — {len(win.documents)} document(s)")
# `complydoc ui` opens what is in .complydoc, where the command line writes too.
cd.write_json(report, ".complydoc/audit.json")

Libraries read the same PDF differently, and the default is not always right:

Terminal window
complydoc audit ~/contracts --compare-extractor pypdf

Findings come from the first reader only. The others are measured and reported; the viewer’s document view shows each reader’s text with the differences marked.

The default reader is complydoc’s own: text through pdfium, word boxes and tables through pdfplumber. complydoc extractors lists the others.

Readings are compared by word order. A reader that sorts words by position reads across a two-column page and returns the same character count as one that goes down each column. The report labels this same words, different order.

A parser can hang on a malformed file. --timeout gives each document a number of seconds and stops the ones that pass it:

Terminal window
complydoc audit ~/contracts --timeout 120

A stopped document is listed as skipped with the reason timed out, and the report states how many were stopped and after how long. Reading happens in a worker process whenever a timeout is set, because that is the only way to stop a parser that has stopped responding. Without --timeout there is no limit.

complydoc compare-readers ~/contracts uses every reader and OCR engine you have installed.

--jobs 0 picks a worker count from the size of the folder.

--sample 200 audits a subset that keeps each file type’s share. The choice is deterministic, so two runs of one folder pick the same documents and their reports compare — and the front page says it read a sample.