Audit a folder
complydoc audit ~/contractsReads 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.
What the report holds
Section titled “What the report holds”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-textleaves the text out altogether. - Pages carry no picture unless one is asked for. With
--detail fullthe 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 |
How much the JSON carries
Section titled “How much the JSON carries”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.
Report summary
Section titled “Report summary”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.
From Python
Section titled “From Python”"""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")Comparing readers
Section titled “Comparing readers”Libraries read the same PDF differently, and the default is not always right:
complydoc audit ~/contracts --compare-extractor pypdfFindings 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.
Documents that never finish
Section titled “Documents that never finish”A parser can hang on a malformed file. --timeout gives each document a number of
seconds and stops the ones that pass it:
complydoc audit ~/contracts --timeout 120A 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.
Large folders and sampling
Section titled “Large folders and sampling”--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.