docpipe

Build the error, including the pip install line that fixes it.

module

the import name that failed

purpose

what it was needed for, e.g. "PDF handling"

extra

the pip name, when it differs from the import name

Import name or raise MissingDependency with a pip hint.

The gate every optional import goes through, so a missing dependency fails where the user called it rather than three frames deep inside a backend.

name

the import name, e.g. "cv2", "fitz", "PIL.Image". Note that this is the import name, not the pip name — the mapping between them is what produces a correct install hint.

purpose

what it was needed for, e.g. "Tesseract input conversion". It goes into the error message, so make it name the feature the user was reaching for.

returns

the imported module

raises MissingDependency

not importable; the message carries the pip install command

True when optional module name can be imported.

The non-raising counterpart to require, for choosing a code path rather than demanding one. Results are cached, so probing in a hot loop is cheap.

name

the import name, e.g. "cv2" or "pytesseract"

returns

whether the import succeeds. False also covers a module that is installed but broken — a native library failing to load counts as unavailable, which is the useful answer.

Enable/disable OpenCV acceleration globally. Returns the previous value.

Process-wide and not thread-safe, so set it during start-up or in a test fixture. For a scoped change prefer with Caps.without_opencv():. The DOCPIPE_DISABLE_OPENCV=1 environment variable does the same at import time, which is what CI uses to exercise the NumPy fallbacks.

enabled

False forces the pure-NumPy path even when OpenCV is installed. Results differ slightly between the two backends — the fallbacks are equivalent, not bit-identical.

returns

the previous setting, so a caller can restore it

with docpipe.without_opencv(): ... — force pure-NumPy image ops.

Report which optional integrations are usable in this interpreter.

Cheap to call and safe at import time; useful in a health check.

A short, stable, cross-process content hash.

hash() is salted per process and useless for caching; this is not.

Content hash of a NumPy array, for caching backend reads.

Hashes the pixels, shape and dtype rather than a filename, which is what makes CachingBackend correct across preprocessing changes: alter an op and the cache misses, as it should.

arr

the array to hash; a non-array falls back to hashing its repr

returns

a stable hex digest, identical across processes and runs

Clamp value into [lo, hi].

value

the number to bound

lo

lower bound, returned when value is below it

hi

upper bound, returned when value is above it

returns

the bounded value. No check that lo <= hi; inverted bounds return lo.

Linear-interpolated percentile without pulling in NumPy.

q is in [0, 100]. Returns 0.0 for an empty sequence, which is the convention the metrics code below relies on.

values

the sample, in any order; it is sorted internally

q

the percentile in 0.0..100.0, clamped. 50 is the median, 95 the usual tail metric.

returns

the interpolated value, or 0.0 for an empty sequence

Edit distance with an optional early-exit bound.

Iterative two-row DP: O(len(a) * len(b)) time, O(min) space. When max_distance is given and every cell in a row exceeds it, we bail out early and return max_distance + 1.

a

the first string

b

the second string

max_distance

give up once the distance provably exceeds this. Turns a "are these nearly equal?" test into an early exit rather than a full matrix — worth passing when scanning many candidates and only close ones matter.

returns

the edit distance, or max_distance + 1 when the bound was hit. The sentinel means "further than you asked about", not an exact distance.

Normalised similarity in [0, 1]: 1 - edit_distance / max_len.

The comparison behind evidence matching and cross-read agreement. Normalising by the longer string keeps a one-character error in a long value from scoring as badly as one in a short value.

a

the first string

b

the second string

returns

1.0 for identical strings, 0.0 when either is empty (unless both are), graded in between. Normalise the inputs first if case or punctuation should not count.

Call fn with exponential backoff and full jitter.

give_up_on wins over retry_on so that non-retryable failures (bad API key, malformed request) fail immediately instead of being hammered three times and billed three times. on_retry(attempt, exc, delay) is the hook the cost tracker uses to record failed-but-charged attempts.

fn

the zero-argument callable to attempt

attempts

total tries including the first; must be at least 1

base_delay

seconds before the first retry, doubling each time

max_delay

ceiling on the backoff, before jitter

jitter

random fraction of the delay added on top, in 0.0..1.0. 0.25 is enough to break up the thundering herd when many pages fail against the same provider at once.

retry_on

exception types worth retrying. (Exception,) is broad because provider SDKs raise their own hierarchies.

give_up_on

exception types that never become successes. These win over retry_on, so a bad API key fails once, not three times.

on_retry

called as on_retry(attempt, exc, delay) before each sleep — the hook for counting billed-but-failed attempts.

sleep

the sleep function, injectable so tests do not wait

returns

whatever fn returned on its first success

raises ConfigError

attempts is less than 1

raises Exception

the last failure, once every attempt is spent

Serialise any docpipe object graph to JSON.

Handles the types json will not: dataclasses, enums, Decimal, dates and NumPy scalars, by way of each object's to_dict.

obj

any docpipe object, or a container of them

indent

spaces per level; None produces compact one-line JSON

sort_keys

sort object keys, which makes output diffable — worth setting for anything committed as a baseline

returns

the JSON text, with non-ASCII characters left as themselves so Devanagari and CJK stay readable in a report

Start at zero; the clock only runs between __enter__ and __exit__.

Elapsed milliseconds — so far, if the block has not exited yet.

Width in points (never negative — see __post_init__).

Height in points (never negative — see __post_init__).

Area in square points.

(x, y) of the centre, in points.

Smallest box containing both. Requires the same page.

other

a box on the same page

returns

the smallest box enclosing both

raises ValueError

the boxes are on different pages. A union across pages has no geometric meaning, and silently returning one would put a reviewer highlight in the wrong place.

Overlap rectangle, or None when they do not overlap.

other

any box

returns

the overlapping rectangle, or None when the boxes are on different pages or merely touch. Edge contact is not overlap: two adjacent table cells intersect in zero area and return None.

Intersection over union in [0, 1].

other

any box

returns

overlap area divided by combined area, in 0.0..1.0. 0.0 for boxes on different pages or with no overlap; 1.0 for identical boxes.

True when other lies inside this box on the same page.

tolerance slackens every edge outward, which matters because OCR boxes and layout boxes come from different estimators and rarely nest exactly.

other

the box that might be inside this one

tolerance

slack in points applied outward on every edge. 0.0 demands exact containment; 2.0 (about a character's width at 12pt) is realistic when testing OCR word boxes against a detected table region.

returns

whether other lies within this box, on the same page

True when the two boxes share any area on the same page.

other

any box

returns

whether the two share positive area. Touching edges do not count — see intersection.

This box grown by margin points on every side (negative shrinks).

margin

points to add to every side; negative shrinks. Useful for padding a highlight so it does not clip the glyphs it marks.

returns

a new box. Not clipped to the page, so follow it up with clipped when the result must stay on the sheet.

This box with every coordinate multiplied by factor.

Scales position as well as size, since it multiplies the coordinates rather than resizing about the centre.

factor

multiplier applied to all four coordinates

returns

a new box on the same page

This box shifted by (dx, dy) points.

dx

horizontal shift in points; positive moves right

dy

vertical shift in points; positive moves down, since the origin is the top-left corner

returns

a new box on the same page

This box confined to a width x height page.

width

page width in points (595 for A4, 612 for US Letter)

height

page height in points (842 for A4, 792 for US Letter)

returns

a new box with every coordinate clamped into the page. A box entirely outside collapses to zero area rather than raising.

(x0, y0, x1, y1) in integer pixels at dpi.

dpi

the resolution to express the box at. Use page.raster_dpi to index into that page's current raster — passing a different DPI gives coordinates for an image that does not exist.

returns

(x0, y0, x1, y1) as rounded integer pixels

Build a point-space BBox from pixel coordinates measured at dpi.

The conversion every backend needs: engines report pixels, the IR stores points, and storing pixels would silently invalidate every box the moment a resolution-changing op ran.

page

zero-based page index the box belongs to

x0

left edge in pixels

y0

top edge in pixels

x1

right edge in pixels

y1

bottom edge in pixels

dpi

resolution the pixel coordinates were measured at, normally page.raster_dpi

returns

the box in points (1/72 inch), which stays valid across rescaling

Build from a top-left corner plus a width and height.

For engines reporting (x, y, w, h) rather than two corners — Tesseract's TSV output among them.

page

zero-based page index

x

left edge, in points

y

top edge, in points

w

width in points

h

height in points

returns

the equivalent corner-based box

Axis-aligned hull of a polygon — what most detectors actually emit.

PaddleOCR, RapidOCR and EasyOCR all detect quadrilaterals so that rotated text is found correctly. The IR stores axis-aligned boxes, so the hull is taken here; backends that need the original keep it in span.meta.

page

zero-based page index

points

the polygon's vertices as [(x, y), ...] in points — any number of them, though detectors emit four

returns

the smallest axis-aligned box containing every vertex

A box covering the entire page — the default evidence region.

What a vision backend attaches to its spans, since it reports no coordinates. Such spans are marked approximate_bbox so nothing mistakes a page-sized box for real geometry.

page

zero-based page index

width_pt

page width in points

height_pt

page height in points

returns

a box spanning the whole page

JSON-ready dict; coordinates are rounded to 3 decimals (~0.001 pt).

Inverse of to_dict.

d

a mapping with page, x0, y0, x1, y1

returns

the reconstructed box

raises KeyError

a required key is missing

Index of the page this span sits on.

True when the span carries no non-whitespace text.

JSON-ready dict.

Optional fields are omitted when unset rather than serialised as null: a document's span list is the bulk of its JSON, and absent-means-unknown round-trips through from_dict unchanged.

Inverse of to_dict.

d

a mapping as produced by to_dict

returns

the reconstructed span

raises KeyError

text or bbox is missing

True unless the page was judged UNREADABLE.

Single scalar in [0, 1] summarising page health.

Used as the prior term in confidence fusion. Weights are deliberately blunt — they exist to be recalibrated against a labelled set (Layer 5), not to be believed as-is.

JSON-ready dict, including the derived score.

Inverse of to_dict (the derived score key is ignored).

d

a mapping as produced by to_dict

returns

the reconstructed quality. Every key has a default that means "undegraded", so a partial dict loads as a clean page rather than a spuriously bad one. score is recomputed from the components.

JSON-ready dict.

Inverse of to_dict.

d

a mapping as produced by to_dict

returns

the reconstructed region

raises KeyError

bbox is missing

raises ValueError

kind is not a RegionKind value

Every region of exactly kind, in detection order.

kind

the RegionKind to filter on, e.g. RegionKind.TABLE or RegionKind.SIGNATURE. Exact, not hierarchical — asking for TABLE never returns table cells.

returns

the matching regions, in the order the detector found them

True when at least one table region was detected.

True when at least one handwriting region was detected.

True when at least one stamp region was detected.

JSON-ready dict.

Inverse of to_dict.

d

a mapping as produced by to_dict

returns

the reconstructed layout; a missing regions key yields an empty layout rather than an error

JSON-ready dict, omitting empty params and notes.

Return the page image as a uint8 NumPy array, rendering on demand.

Semantics that matter:

• With a provider still attached (nothing has been preprocessed yet), a request at a different DPI re-renders from source — always better than upsampling.
• Once an op has run, the provider is dropped and the processed raster is authoritative; a differing DPI request rescales it instead, so an op chain is never silently discarded.

dpi

the resolution wanted. None keeps the page's current DPI, falling back to DEFAULT_DPI. Ask for what you need rather than rescaling afterwards — a re-render from the PDF beats an upsample every time, and this method knows which is possible.

returns

the page image as a uint8 NumPy array, greyscale or RGB

raises DocpipeError

the page has neither a raster nor a provider, e.g. an email-body page, which carries text but no pixels. Guard with has_raster.

True when a raster is materialised or can be produced without I/O errors.

Install img as this page's raster. Ops use this.

Dropping the provider is the default and is deliberate: after a deskew, re-rendering from the PDF would silently undo the op.

img

the new raster, a uint8 NumPy array

dpi

the resolution img represents. None keeps the page's current DPI — correct for an op that preserved size, wrong for one that rescaled, which must pass the new value.

keep_provider

retain the lazy source. Leave this False except when installing a raster equivalent to what the provider would return; keeping it lets a later DPI change discard your image.

returns

self, so calls chain

Attach a lazy raster source, e.g. a PDF page renderer.

provider

called as provider(dpi) and must return an ImageArray

dpi

the resolution to assume until one is requested explicitly

Drop the materialised raster. Only safe while a provider remains.

Resolution of the current raster, falling back to DEFAULT_DPI.

(width, height) of the current raster in pixels, (0, 0) if none.

Reading-order text. Spans are sorted by line, then by x.

separator

placed between lines; the default single newline preserves the page's line structure, which is what amount-and-label parsing depends on

returns

the page's text. Empty for a page that has not been read.

Group spans into visual lines and return them top-to-bottom.

y_tolerance defaults to 60% of the median span height, which tracks font size instead of assuming one.

y_tolerance

vertical distance in points within which two spans count as the same line. None derives it from the page's own median span height, which is right across font sizes. Pass a value only for pages that defeat that — a table whose rows are closer than its text is tall.

returns

one string per visual line, top to bottom, words joined by single spaces. Empty lines are dropped.

Spans whose area overlaps bbox by at least min_overlap.

The fraction is of the span's area, not the box's, so a small word inside a large region counts as fully contained.

bbox

the region to search, in points

min_overlap

least fraction of each span's area that must fall inside, in 0.0..1.0. 0.5 requires the majority of the word; 0.3 is more forgiving and is what evidence matching uses, since OCR boxes and layout boxes come from different estimators.

returns

the qualifying spans, in page order

Total non-whitespace characters across every span on the page.

True when the page is worth skipping entirely.

Either it was classified blank at ingest, or it has no text and essentially no ink — both checks are needed, because an unread scan of a full page also has a character count of zero.

Append an entry to this page's processing history. Returns self.

op

the op's registered name

params

the arguments it ran with, for reproducibility

ms

wall-clock duration

note

anything worth knowing, e.g. why an op declined to run

The op history as one a -> b -> c line.

A box covering the whole page, in points.

Shallow-copy the page, sharing the raster but not the span list.

Ops use this so that a pipeline never mutates the caller's document — A/B'ing two pipelines against one ingested document has to be safe.

The raster is shared, not copied: it is large, and ops replace it rather than writing into it. Everything else — spans, layout, history, meta — is copied, so the two pages diverge cleanly.

deep_spans

copy each TextSpan rather than sharing the objects. True is right whenever the copy will be read or normalised, since span mutation would otherwise reach back into the original.

returns

the new page

JSON-ready dict.

include_spans=False keeps the structure and the measurements but drops the text, which is what the eval harness stores for a fixture.

include_spans

keep the per-span text and geometry

returns

a JSON-serialisable dict. The raster is never included — see from_dict.

Inverse of to_dict. The raster is not restored.

Pixels are deliberately not serialised — a JSON document would be enormous — so a restored page has spans, geometry and history but has_raster is False. Re-ingest the source to read it again.

d

a mapping as produced by to_dict

returns

the reconstructed page

raises KeyError

index is missing; every other key has a default

Number of pages.

Iterate over pages in order.

Page by list position (see page for lookup by page index).

Position and page index diverge the moment pages are filtered or split, which is why both accessors exist.

i

list position, negative indexing allowed

returns

the page at that position

raises IndexError

out of range

Page by its index attribute (not its list position).

The accessor to use when resolving provenance: every bbox.page is a page index, not a position, and the two differ after select.

index

the page's own index attribute

returns

the matching page

raises KeyError

no page carries that index

Reading-order text of every non-empty page, joined by separator.

separator

placed between pages. The default blank line reads naturally; use format_document_text instead when the text is headed for a prompt, since that one adds page markers.

returns

the document's text. Empty for a document that has been ingested but not read.

Every span in the document, page by page, in order.

Total non-whitespace characters in the document.

Count of pages per PageKind, e.g. {"scanned": 12}.

Record a de-duplicated warning and log it. Returns self.

Warnings survive on the Document rather than being raised because a bad page is not a bad document: the caller usually wants the other 40 pages.

message

what went wrong. Duplicates are dropped, so a warning raised once per page on a 300-page bundle appears once.

returns

self, so calls chain

Deep-enough copy: pages are copied, rasters are shared.

Free every materialised raster that can be re-rendered on demand.

A new Document containing only pages satisfying predicate.

Page index attributes are preserved, not renumbered, so provenance still resolves through page. Use merge_documents when you do want contiguous renumbering.

predicate

Callable[[Page], bool], e.g. lambda p: not p.is_blank or lambda p: p.quality.score > 0.5

returns

a new document sharing the surviving page objects

JSON-ready dict; include_spans=False drops the text.

include_spans

keep per-page spans. False yields a compact structural summary — geometry, quality, history — which is what you want for a manifest or a diff between two runs.

returns

a JSON-serialisable dict. Rasters are never included.

Inverse of to_dict. Rasters are not restored.

d

a mapping as produced by to_dict

returns

the reconstructed document, on which every page reports a has_raster of False.

Write to_dict to path as UTF-8 JSON. Returns path.

path

destination file; overwritten if it exists

include_spans

keep per-page spans, as to_dict

returns

path, so it can be used inline

Read a document back from a file written by save_json.

path

a file written by save_json

returns

the reconstructed document, without rasters

raises OSError

the file could not be read

raises ValueError

the file is not valid JSON

Sum two costs.

Mixing currencies raises ConfigError — unless one side is zero, which is what makes sum(costs) (starting from 0) work.

other

the cost to add

returns

a new Cost with amounts, tokens, calls and wasted calls summed. NotImplemented for a non-Cost, so Python falls back to the reflected operand.

raises ConfigError

both sides are non-zero and in different currencies. No conversion is attempted — a guessed exchange rate is exactly the kind of confidently wrong number this library refuses to produce.

An empty cost in currency — the identity for addition.

currency

the currency label; no conversion is ever performed, so it must match the units of your registered prices

returns

a zero cost, safe to use as an accumulator seed

Input plus output tokens.

JSON-ready dict; the amount keeps 6 decimals (sub-cent per page).

Coerce any numeric array to uint8, scaling float [0,1] images by 255.

The guard at the top of every image primitive, so ops need not care whether an upstream step handed back floats or booleans.

img

any numeric array — uint8 passes straight through, floats peaking at or below 1.0 are scaled by 255, booleans map to 0/255, and anything else is clipped into 0..255

returns

a uint8 array of the same shape

Grayscale view of img using ITU-R 601 luma weights.

img

a greyscale or colour array. Greyscale input is returned unchanged, so this is safe to call unconditionally; an alpha channel is dropped.

returns

a single-channel uint8 array

3-channel RGB view of img.

img

a greyscale or colour array. Greyscale is replicated across three channels; a 4-channel image loses its alpha.

returns

an (H, W, 3) uint8 array

Local (mean, std) over a window x window neighbourhood.

Uses summed-area tables, so cost is independent of window size — which is what makes Sauvola-family binarisation practical at 300 DPI. Windows are clipped at the borders and the divisor tracks the clipped area, so edge pixels are not biased toward black the way zero-padding would make them.

gray

a single-channel array

window

neighbourhood side in pixels. Cost does not grow with it, so pick it by what the page needs — a little taller than one text line for binarisation.

returns

(mean, std), both float arrays the same shape as gray

Mean filter of radius radius (integral-image based in the fallback).

img

greyscale or colour; colour is filtered per channel

radius

half-width in pixels, so the kernel is 2 * radius + 1 square. Below 1 the image is returned unchanged.

returns

the blurred uint8 array

Gaussian blur. The fallback is three variance-matched box blurs.

The fallback still loses a little tail mass, because each pass rounds back to uint8, so its effective sigma runs slightly under the request at large radii. Measured against measure_blur the two paths agree to within about 0.02 over sigma 0.8-4.0, which is what the tests assert.

img

greyscale or colour

sigma

standard deviation in pixels. Zero or negative returns the image unchanged. The kernel radius is derived from it, so cost grows with sigma on the OpenCV path and stays flat on the fallback.

returns

the blurred uint8 array

Median filter — the right tool for salt-and-pepper scanner speckle.

Unlike a mean filter it removes isolated specks without softening the stroke edges around them, which is why denoising uses it rather than a blur.

img

greyscale or colour; colour is filtered per channel

ksize

kernel side in pixels, forced odd. 3 removes single speckles; 5 handles heavier fax noise and starts to round off the corners of glyphs.

returns

the filtered uint8 array

Resize to size=(width, height) or by scale.

interpolation="auto" picks cubic when upscaling (preserves stroke edges that OCR character models rely on) and area when downscaling (avoids the aliasing that makes fine print look like noise).

img

greyscale or colour

size

target (width, height) in pixels — note this is the opposite order to image_shape. Takes precedence over scale.

scale

uniform multiplier, used when size is None. A scale of 1.0 returns the image unchanged.

interpolation

"auto" (cubic up, area down), or one of "nearest", "linear", "cubic", "area". Use "nearest" on an already-binarised page, where interpolation would reintroduce grey.

returns

the resized uint8 array

Rotate counter-clockwise by angle_deg about the image centre.

expand=True grows the canvas so no content is clipped — deskewing a page and losing the top-right corner of the letterhead is a real failure mode of the naive implementation. border_value defaults to the image's median, which keeps a white page white and a dark scan dark rather than stamping black wedges that later confuse ink-coverage measurement.

img

greyscale or colour

angle_deg

counter-clockwise rotation in degrees. Angles under 1e-4 return the image unchanged.

border_value

fill level for exposed corners, 0..255. None uses the image's median, which is what keeps a white page white and a dark scan dark.

expand

grow the canvas so nothing is clipped. Leave it True for deskewing — False keeps the original dimensions and cuts the corners off, which loses letterheads.

returns

the rotated uint8 array, larger than the input when expand is set

Horizontal projection profile as if the image were rotated by angle_deg.

Note carefully which axis is sheared. Shearing rows horizontally — the obvious reading of "shear to simulate rotation" — leaves every row sum unchanged, so a skew search built on it measures nothing but border artefacts. The columns must be shifted vertically instead, so that content from a tilted text line lands in the same output row.

For angles under ~15 degrees a shear and a rotation give indistinguishable profiles, and the shear costs one integer fancy-index instead of a full resampling pass.

gray

a single-channel array

angle_deg

the tilt to simulate, in degrees. Accurate for small angles only — beyond about 15 degrees a shear stops approximating a rotation, which is why the skew search is bounded there.

returns

the per-row ink sums as a float array, whose variance peaks at the angle that makes text lines horizontal

Otsu's global threshold via between-class variance maximisation.

gray

a greyscale or colour array; colour is converted first

returns

the threshold as an integer in 0..255. Global, so it is exact on an evenly-lit page and badly wrong under a shadow gradient — which is what ink_mask detects and works around.

Boolean mask of "ink" pixels (dark on light).

Otsu is the right default: it is cheap, global, and exact on an evenly-lit page. It is also catastrophically wrong on an unevenly-lit one — under a shadow gradient the darker paper falls below the global threshold, so a third of the page is classified as ink. Everything built on this mask then fails together: ink coverage reads 40%, the skew search locks onto the shadow boundary instead of the text lines, and stroke width becomes meaningless. Shadowed phone photographs are a primary input here, so the mask checks for that case and switches to a local (Sauvola) threshold, which is immune to it.

gray

a greyscale or colour array

threshold

force a fixed grey level, 0..255; pixels at or below it are ink. None chooses a threshold automatically, which is almost always what you want.

adaptive

"auto" (default) uses a local Sauvola threshold only when the page looks unevenly lit; True always does; False always uses global Otsu. Ignored when threshold is given.

returns

a boolean mask, True where there is ink

Sobel gradient magnitude as float64. Used by the sharpness metric.

gray

a greyscale or colour array; colour is converted first

returns

a float array of edge strengths, the same shape as the input. Unnormalised, so compare it against itself rather than an absolute number.

Binary morphology with a rectangular structuring element.

Implemented with summed-area tables so that a 1x120 kernel (what line removal needs) costs the same as a 3x3 one.

mask

a boolean or 0/1 array

kh

kernel height in pixels

kw

kernel width in pixels. Asymmetry is the point: (1, 120) finds horizontal rules and ignores everything else.

operation

"erode", "dilate", "open" (erode then dilate, removing specks) or "close" (dilate then erode, filling gaps). Named from the mask's point of view, so "dilate" grows the True region.

returns

the transformed boolean mask

Estimate the page background (paper + lighting) with the text erased.

The kernel has to be larger than the tallest glyph, or the middle of a text line survives as background and the correction punches a hole through it. Sized at 1/12 of the shorter side and clamped: big enough for body text at any sane DPI, small enough to still follow a shadow gradient.

gray

a greyscale or colour array

radius

kernel size in pixels, forced odd, minimum 3. None derives one from the page size, which is right unless the text is unusually large — a kernel narrower than a glyph is tall leaves text in the background estimate.

returns

the estimated background as a uint8 array, the same shape as the input. Divide the page by it to flatten lighting, which is what normalize_illumination does.

Encode an array as PNG bytes — what vision backends actually send.

Lossless, so prefer it for archival and for debugging output. For a model call use encode_jpeg, which is several times smaller at a quality the page cannot tell apart.

img

greyscale or colour

returns

the PNG bytes

raises MissingDependency

neither OpenCV nor Pillow is importable

Encode as JPEG. Preferred for VLM calls: a 300 DPI page as PNG is several megabytes, and the artefacts JPEG adds at q>=85 are well below what the scanner already introduced.

img

greyscale or colour; greyscale is expanded to RGB

quality

JPEG quality in 1..100. 88 is the default and sits above the point where compression artefacts become visible to a recogniser; below 75 ringing around glyph edges starts to cost accuracy.

returns

the JPEG bytes

raises MissingDependency

neither OpenCV nor Pillow is importable

Decode image bytes to a uint8 RGB/gray array.

Raises IngestError — not a Pillow or OpenCV exception — when the bytes are not a decodable image. Callers batch-processing a directory or walking email attachments need one exception type to catch, or a single corrupt scan takes down the run.

data

the encoded bytes — PNG, JPEG, BMP, GIF or WebP. Format is detected from content, so no filename is needed.

returns

a uint8 array, greyscale (H, W) or RGB (H, W, 3)

raises IngestError

the bytes are empty or not a decodable image

raises MissingDependency

neither OpenCV nor Pillow is importable

Write an array to disk, choosing the encoder from the extension.

img

greyscale or colour

path

destination. .jpg/.jpeg encode as JPEG; every other extension, including none, encodes as PNG.

returns

path, so it can be used inline

raises MissingDependency

neither OpenCV nor Pillow is importable

raises OSError

the file could not be written

Sharpness in [0, 1], from edge-transition width.

Variance of the Laplacian is the textbook answer and it is the wrong one here. It rises with noise, so a grainy scan scores sharper than a clean one, and it falls on sparse pages, so a crisp page with little ink scores blurry. Both are everyday cases in scanned bills.

Two independent sub-scores are computed instead, and the **worse of the two wins**, because each covers the other's blind spot:

Concentration — the fraction of edge pixels carrying strong gradient. A sharp edge puts its whole intensity step into one or two pixels; blurring spreads it over many pixels of medium gradient. Being a ratio it is immune to contrast and to noise, and it correctly catches a low-resolution page that was upsampled. It saturates under extreme blur, where the gradient field becomes smooth and self-similar.

Steepness — peak gradient divided by the ink-to-paper step, i.e. the reciprocal of the edge's transition width in pixels. It degrades cleanly all the way into heavy blur, but it is fooled by noise (which supplies spurious steep gradients) and by upsampling.

The result is contrast-invariant by construction: a faded page and a dark one score the same, which is correct, because fading is measure_contrast's job to report, not this one's.

Roughly: crisp print ~0.9, Gaussian sigma=1 ~0.6, sigma=2 ~0.45, sigma=4 ~0.3, sigma=8 ~0.05, a 120 DPI scan upsampled to 300 ~0.18.

gray

the page as a greyscale array; colour input is converted

returns

sharpness in 0.0..1.0; 1.0 is crisp. Compare against QualityThresholds.blur_floor (degraded) and blur_unreadable.

Contrast in [0, 1] — specifically, ink-to-paper separation.

A generic 5th-95th percentile spread is wrong for documents: a perfectly crisp page that is 97% white paper has both percentiles sitting at 255 and reports zero contrast. What actually matters to a recogniser is how far the ink sits from the paper, so we split on Otsu and measure the gap between the two populations, using inner percentiles on each side so that antialiased edge pixels do not flatter the result.

Falls back to the percentile spread when the page has too little (or too much) ink for the split to mean anything.

gray

the page as a greyscale array; colour input is converted

returns

ink-to-paper separation in 0.0..1.0. A near-blank page reports high contrast rather than zero, since there is no ink whose separation could be poor.

Fraction of pixels that are ink, using an illumination-aware mask.

gray

the page as a greyscale array; colour input is converted

returns

inked fraction in 0.0..1.0. Body text lands near 0.05, dense Devanagari near 0.25; above 0.4 suggests a negative scan — see invert_if_dark.

Speckle estimate in [0, 1].

The high-frequency residual (image minus its median-filtered self) contains both text edges and noise. Text edges are sparse and large; sensor noise is dense and small, so the median absolute residual tracks noise while being largely blind to text.

gray

the page as a greyscale array; colour input is converted

returns

speckle in 0.0..1.0; 0.0 is clean. Above QualityThresholds.noise_ceiling the page is treated as degraded and denoise is reached for.

Lighting evenness in [0, 1]; 1 is flat, 0 is a hard shadow gradient.

The page background is estimated by heavy downsampling (which averages text away) and its spread measured. This is what catches phone photos with a shadow across one half — the exact case where global binarisation destroys a third of the page.

gray

the page as a greyscale array; colour input is converted

returns

evenness in 0.0..1.0; 1.0 is perfectly flat lighting and 0.0 a hard shadow gradient. Below the QualityThresholds.illumination_floor cut-off, the op normalize_illumination is applied.

Estimate the page's skew in degrees (positive = content tilted clockwise).

method:

projection

Coarse-to-fine search maximising the variance of the horizontal projection profile. Text lines align into sharp peaks only at the correct angle. Robust on sparse pages, needs no OpenCV, and is the default because it degrades gracefully on forms and tables.

hough

Probabilistic Hough transform over Canny edges, taking the median angle of near-horizontal segments. Excellent when ruled lines exist.

minarearect

Minimum-area rectangle of all ink pixels. Fast, but fooled by a single stray margin mark, so it is only used inside auto's median.

auto

Median of whichever of the above are available — a cheap consensus that avoids each method's individual failure mode.

min_improvement is how much better than the straight-page hypothesis a candidate angle must score before it is believed; see by_projection.

Returns 0.0 when the page has too little ink to judge, or when no angle is convincingly better than leaving the page alone.

gray

the page as a greyscale array; colour input is converted

max_angle

widest tilt to search, in degrees either way. Beyond 15 a page is not skewed but rotated — a different problem, and searching that far mostly finds table rules.

method

"auto", "projection", "hough", or "minarearect", each described above. "auto" takes the median of whichever are available.

coarse_step

degrees per step in the first projection pass. 1.0 is ample; smaller only costs time, since the fine pass refines whatever the coarse pass found.

fine_step

degrees per step in the refinement pass. 0.1 is below what deskewing can act on anyway — deskew declines under 0.4 degrees.

min_improvement

how much better than the straight-page hypothesis a candidate must score to be believed, as a relative margin. 0.15 keeps a page that is genuinely straight from being rotated by noise.

returns

the skew in degrees, positive meaning content tilted clockwise; 0.0 when the page is straight, nearly blank, or ink-saturated

Mean ink stroke thickness in pixels, from the area-to-perimeter ratio.

For an elongated shape, 2 * area / perimeter is its width. Cheap and exact on clean print — but it inflates under blur, because a soft edge puts the Otsu threshold outside the true stroke and the halo is counted as ink. Callers must not use it as a resolution estimate on a soft page; see estimate_line_pitch.

gray

the page as a greyscale array; colour input is converted

returns

mean stroke thickness in pixels, or 0.0 when the page has too little ink. Roughly 3 px for body text at 300 DPI — but it inflates under blur, so prefer line pitch for resolution.

Dominant text-line spacing in pixels, via autocorrelation, or 0.0.

Blur, fading and threshold choice all move stroke width around; none of them move the distance between one baseline and the next. That makes line pitch the sturdiest resolution cue a page offers, and it is what estimate_effective_dpi prefers.

Returns 0.0 when the projection has no convincing periodicity — a title page, a photograph, or a form with irregular row heights.

gray

the page as a greyscale array

min_pitch

shortest spacing considered, in pixels. 8 is below body text at any usable resolution; raising it rejects the harmonics that dense text can produce.

max_pitch

longest spacing considered, in pixels. 200 covers double-spaced large print at 600 DPI.

returns

the dominant line spacing in pixels, or 0.0 when the page has too little ink or no convincing periodicity

Estimate the content resolution of a page image.

A page can be rendered at 600 DPI and still carry only 120 DPI of signal, because it was scanned once at 120 and upsampled by three tools since. Rendering DPI is therefore not resolution, and this is the number that should drive ensure_dpi and the confidence prior.

Two independent cues are used. Line pitch is preferred: it survives blur, fading and threshold choice, all of which distort stroke width. Stroke width is the fallback for pages with no regular text lines, and the two are averaged when they roughly agree, which tightens the estimate on ordinary prose.

Returns fallback when the page carries too little ink to judge.

gray

the page as a greyscale array

fallback

returned when neither cue yields an estimate. Pass the page's nominal raster_dpi so callers always get a usable number.

returns

estimated content DPI, clamped to 30..1200. Compare it against page.raster_dpi: a large gap means the page was upsampled somewhere and carries less signal than its size suggests.

Turn measurements into clean / degraded / unreadable.

unreadable is a routing signal, not a discard: those pages get the vision model and a confidence penalty rather than being dropped, because a human reviewer would rather see a low-confidence guess than a blank.

q

the measured PageQuality

thresholds

cut-offs to compare against. None uses the defaults in DEFAULT_THRESHOLDS

returns

a Verdict. A near-blank page reports CLEAN rather than UNREADABLE — there is nothing on it to misread, and calling it unreadable would route empty pages to the expensive backend.

Measure every channel-degradation signal for one page image.

The measurement half of adaptive preprocessing: policies read the result and reach only for the ops a page's actual degradation warrants.

img

the page raster, greyscale or colour

raster_dpi

the resolution the image was rendered at, recorded on the result and used as the fallback for effective_dpi. 0 means unknown.

thresholds

cut-offs for the verdict. None uses the defaults in DEFAULT_THRESHOLDS

skew_method

passed to estimate_skew — "auto", "projection", "hough", or "minarearect"

max_skew

widest skew to search, in degrees

returns

a PageQuality carrying blur, skew, contrast, ink coverage, noise, illumination, effective DPI and an overall verdict

Measure page in place and return it. No-op for pages without rasters.

page

the page to measure; page.quality is replaced and the measurement recorded in page.history

dpi

render the raster at this DPI for measuring; None uses whatever the page already has

thresholds

cut-offs for the verdict. None uses the defaults in DEFAULT_THRESHOLDS

kwargs

forwarded to measure_quality — skew_method, max_skew

returns

the same page, mutated. A page with no raster is returned untouched, its quality left at defaults.

Measure every page's quality. Returns the same Document, mutated.

doc

the document to measure, page by page

dpi

render DPI for measuring; None uses each page's own

thresholds

cut-offs for the verdict. None uses the defaults in DEFAULT_THRESHOLDS

max_workers

threads to measure with. 0 runs serially.

kwargs

forwarded to measure_quality

returns

the same document, mutated. preprocess does this for you — call it directly to inspect quality without changing pixels, which is what docpipe quality does.

Identify a document format from its bytes, falling back to its name.

Content first, extension last, because in practice the extension lies: scanners emit .pdf files that are really TIFFs, and mail gateways strip extensions entirely.

data

the leading bytes of the file; the first 2 KB are enough

filename

used only for its extension, and only when the magic bytes were inconclusive

returns

one of "pdf", "png", "jpeg", "tiff", "bmp", "gif", "webp", "eml", or "unknown". A .msg file reports "eml", since it takes the same path.

Decide how a page stores its text, from cheap PDF-level evidence.

image_area_ratio is the fraction of the page covered by embedded raster images. The interesting case is HYBRID: a native-text page with a scanned insert pasted in (a photographed bill stapled into a typed claim form). Those pages need both paths, and treating them as native silently loses the insert — which is usually where the numbers are.

char_count

characters the PDF's text layer reports for this page

image_area_ratio

fraction of the page covered by embedded raster images, in 0.0..1.0. Above 0.35 alongside real text means HYBRID — a scanned insert on a typed form.

has_images

whether the page embeds any raster image at all

min_chars

characters below which the text layer is not trusted. Defaults to MIN_NATIVE_CHARS. Scanned pages routinely carry a handful of stray characters from a header stamp, so the floor cannot be 1.

ink_hint

measured ink coverage in 0.0..1.0, when known. Lets a page with no text and no embedded image still be called SCANNED rather than BLANK, which is the case for a page whose content is one large drawing.

returns

the PageKind — DIGITAL_NATIVE, HYBRID, SCANNED, or BLANK. This drives routing, as decided by default_router.

Open a PDF, read any native text layer, and attach lazy page renderers.

Handles the three things that break naive PDF ingest in production: encrypted-but-openable files (empty owner password), files with leading junk before %PDF-, and structurally damaged files that PyMuPDF can repair on a second pass.

source

path, path-like, raw bytes, or an open binary file

password

for an encrypted PDF. Files encrypted with an empty owner password — the common case for bank and hospital statements — open without this.

max_pages

stop after this many pages; 0 means all of them. Applied after page_range.

page_range

zero-based page indices to ingest, e.g. range(10, 20) or [0, 5, 9]. None takes every page.

render_dpi

resolution for the lazy page renderers. 300 is the floor for reliable OCR, 400 helps on small print. Nothing is rendered until a page's raster is actually asked for — a 300-page bundle at 400 DPI would be tens of gigabytes eagerly.

extract_text

read the embedded text layer. Leave it on: it is nearly free, and it is what lets default_router route a digital page to the exact, free "pymupdf" read.

min_native_chars

per-page character floor for trusting that text layer; passed to classify_page_kind.

returns

a Document whose pages carry native spans where they exist and a lazy raster provider throughout

raises IngestError

the file could not be opened even after a repair pass, or the password was wrong

Ingest a single-page image (PNG/JPEG/BMP/WebP) as a one-page Document.

source

path, path-like, raw bytes, or an open binary file

dpi

the image's true resolution. None reads it from the file's metadata and falls back to DEFAULT_IMAGE_DPI. Worth passing explicitly for phone photos, whose EXIF DPI is meaningless — every DPI-relative threshold downstream depends on this number.

page_index

the index this page takes in the document, for assembling a multi-page document from separate image files

returns

a one-page Document with the raster already attached

raises IngestError

the bytes could not be decoded as an image

Ingest a (possibly multi-page) TIFF. Fax archives are full of these.

Needs Pillow for multi-page files; without it, only the first frame is read, via ingest_image.

source

path, path-like, raw bytes, or an open binary file

dpi

true resolution; None reads the TIFF tag and falls back to DEFAULT_IMAGE_DPI. Fax TIFFs commonly declare 204x98, which is anisotropic and worth overriding.

returns

a Document with one page per frame

raises IngestError

the file could not be opened as a TIFF

Ingest an .eml message: every readable attachment becomes pages.

Inbound claim registration lives on this path. Attachments arrive as native PDFs, scans, and images pasted into the body, all in one message, and each part has to be routed on its actual bytes rather than its filename. Pages carry meta['attachment'] so a downstream reviewer can be told which attachment a field came from.

source

path, path-like, raw bytes, or an open binary file holding an RFC 822 message

dpi

passed to each image attachment's ingest; None detects per attachment

include_body

turn the message body into a leading text page. Useful — claim references and policy numbers are often typed in the covering mail rather than attached. That page carries no raster.

max_attachments

ceiling on attachments processed, guarding against a mail bomb. Attachments past the limit are noted in the document's warnings rather than silently dropped.

returns

a Document whose pages span every readable attachment, in message order, each tagged with meta["attachment"]. An attachment that cannot be read is recorded as a warning and skipped, so one corrupt part does not cost the message.

Public helper: build a Page from an in-memory array.

The entry point for pages that never came from a file — a frame grabbed from a scanner SDK, a crop produced upstream, a synthetic test page.

img

a NumPy array, greyscale or RGB. Converted to uint8.

index

the page's index within its document, which every span's bbox.page refers back to

dpi

the array's true resolution. Defaults to the constant DEFAULT_IMAGE_DPI. Get this right: every DPI-relative threshold downstream is computed from it.

returns

a Page with the raster attached and its point-space geometry derived from the array's shape and dpi

Public helper: build a Document from in-memory arrays.

images

the page rasters, in order

dpi

resolution assumed for every array, as described in page_from_image

source_uri

label recorded on the document and used in reports

returns

a Document with one page per array, indexed from 0

Ingest anything: PDF, image, multi-page TIFF, .eml, path or bytes.

Format is decided by content, not by extension. Returns a Document whose pages are geometry-complete but not rasterised.

source

a path or path-like ("scan.pdf"), raw bytes, or an open binary file object. A directory is not accepted here; walk one with ingest_dir instead.

filename

name hint, used only when source is bytes or a stream and only to break a tie the magic bytes could not. Also becomes the document's source_uri.

dpi

assumed resolution for bare images. None reads the file's metadata and falls back to DEFAULT_IMAGE_DPI. Ignored for PDFs, which use render_dpi.

password

for an encrypted PDF; ignored for other formats

max_pages

stop after this many pages; 0 means no limit

page_range

explicit zero-based page indices to keep, e.g. range(10, 20). PDFs only.

render_dpi

resolution for PDF page rendering. 300 is the floor for reliable OCR; 400 helps on small print.

min_native_chars

per-page character floor for trusting a PDF text layer; see classify_page_kind.

returns

a Document whose pages are geometry-complete but not yet rasterised — raster() is lazy by contract, not as an optimisation.

raises IngestError

the input was empty, the format was unrecognised, or the file could not be opened

Bytes off a queue, with the name as the only hint:

doc = ingest(payload, filename="claim-4471.pdf")

Ingest every readable document in a directory tree.

Unreadable files are reported as warnings on an empty Document rather than aborting the batch — a 5000-file inbox with three corrupt scans should still process 4997 of them.

directory

the root to walk. Dotfiles are skipped; files are taken in sorted order per directory, so the result is stable.

pattern

a regular expression matched against each filename with re.search, e.g. "[.]pdf$" or "^claim-". None attempts every file, relying on content sniffing.

recursive

descend into subdirectories. False reads only the top level.

kwargs

forwarded to ingest for each file — render_dpi, max_pages, password, ...

returns

one Document per file attempted, in walk order. A file that failed yields an empty document carrying the reason in its warnings, so the count always matches the files seen.

Concatenate documents into one, renumbering pages and their bboxes.

Renumbering is the point: every span's bbox.page refers to a page index, so concatenating without reindexing would leave provenance pointing at the wrong pages.

docs

the documents to concatenate, in order

source_uri

label for the merged document

returns

one Document whose pages are numbered from 0, with warnings unioned and duplicates dropped

Build an Op from positional/keyword op parameters.

Bind a raster function and its parameters into a reusable op.

name

the registered name, used for history and serialisation

fn

fn(img, page, **params) -> Optional[ImageArray]; returning None means "declined, leave the raster alone"

params

keyword arguments bound now and passed to fn at every application, e.g. {"max_angle": 10.0}. Copied, so the caller's dict cannot change the op afterwards.

geometric

True when the op changes the page's pixel dimensions, so that point-space geometry is recomputed afterwards

needs_raster

when True the op is skipped (and says so in the history) on a page that has no raster

Run the op, returning a new page. The input page is never mutated.

Timing and parameters land in the returned page's history whether or not the op actually changed anything, so a pipeline is reconstructable from its output alone.

page

the page to transform; it is copied, never mutated

returns

a new Page. Identical in pixels to the input when the op declined (returned None) or was skipped for want of a raster — but its history records the attempt either way.

a.then(b) — a composite that runs this op, then other.

other

the op to run second

returns

a CompositeOp of the two, equivalent to compose(self, other) and chainable further

JSON-ready dict; feed it back to op_from_dict.

Wrap an ordered sequence of ops as a single op.

ops

the member ops, applied in this order. Kept on .ops so they stay reachable for inspection and serialisation.

Run every op in order, threading the page through.

page

the starting page; it is not mutated

returns

the page after every member op, carrying one history entry per op rather than a single entry for the composite

JSON-ready dict containing each member op.

Collapse to a single channel.

Do this before classical OCR (which discards colour anyway) but not before colour-based stamp removal, which needs hue.

Invert white-on-black pages (negative scans, some fax modes).

Every downstream measurement assumes dark ink on light paper; a negative page reports 90% ink coverage and gets classified unreadable, when in fact it just needs one subtraction.

ink_threshold

inked fraction above which the page is judged to be a negative, in 0.0..1.0. The default 0.55 sits well above any real document — dense Devanagari body text reaches about 0.25, a solid-black form header about 0.4 — so this fires on true negatives and not on merely heavy pages. Lower it towards 0.45 only if you have genuinely ink-saturated scans; below that you will start inverting healthy pages.

Stretch the [low_pct, high_pct] intensity range to full scale.

Percentile-based so that a punch hole or a black scan border does not eat the entire dynamic range, which is what naive min/max stretching does.

low_pct

percentile mapped to black, in 0.0..100.0. 1.0 discards the darkest 1% of pixels — enough to absorb punch holes, staple shadows and a thin scan border. 0.0 is exact min/max stretching and is what you want only on synthetic images.

high_pct

percentile mapped to white, in 0.0..100.0. 99.0 pairs with the default low_pct; widen to 0.5/99.5 for a gentler stretch on pages that are already close to full range.

returns

None when the two percentiles are within one grey level of each other — a blank or already-saturated page, where stretching would only amplify noise.

Apply gamma correction. value < 1 brightens, > 1 darkens.

Non-linear, unlike autocontrast: it moves the midtones while leaving true black and true white fixed, which is what recovers faint pencil or carbon-copy strokes without blowing out the paper.

value

gamma exponent, practically 0.4..2.5. 0.6 lifts faint grey strokes on an underexposed phone photo; 1.4 deepens washed-out thermal-printer output; 1.0 is identity and returns None so a no-op costs nothing.

returns

None when value is 1.0 within tolerance

Contrast-limited adaptive histogram equalisation.

The right tool for a page that is faded in one corner and fine elsewhere — a global stretch cannot fix that by construction. Falls back to autocontrast without OpenCV.

clip

contrast ceiling per tile. 2.0 is the usual document setting; 1.0 is nearly a no-op, and above 4.0 the noise in blank paper is amplified into visible grain that OCR reads as specks.

grid

tile count along each axis, so 8 means an 8x8 grid. Fewer, larger tiles (4) approach a global stretch; more, smaller tiles (16) track tighter lighting gradients but start equalising within a glyph, which thins strokes.

returns

the equalised greyscale page; never None, since the caller has already decided the page needs it

Flatten uneven lighting by dividing out the estimated background.

This is the fix for phone photos and book scans with a shadow gradient. Doing it before binarisation is what lets a global threshold work at all; skipping it is why so many pipelines lose the shadowed third of a page.

radius

background-estimation window in pixels; None derives one from the page size, which is right unless your text is unusually large. The window must be comfortably wider than a glyph — set it near a character width and the estimator treats the text itself as background and erases it.

strength

how far to move towards the flattened result, in 0.0..1.0. 1.0 applies it fully, whereas the gentler vlm policy uses 0.7 — vision models read the greyscale gradient, and a fully flattened page discards the very cue that distinguishes a faint stroke from paper. See the gentler vlm_policy.

Remove cast shadows via dilate-then-median background subtraction.

The classic recipe: dilating with a mid-sized kernel removes text, the median then removes residual structure, and the difference is the page without its shadow.

Overlaps with normalize_illumination; prefer that one for a smooth lighting gradient and this one for a hard-edged cast shadow, such as the photographer's hand or the spine shadow of an open book.

radius

dilation and median kernel in pixels, forced odd. It must exceed the thickest stroke on the page or the text survives dilation and is subtracted away with the shadow. 21 suits 300 DPI body text; raise towards 41 at 600 DPI or for large print.

Scale the raster by factor, keeping physical page size constant.

Point-space coordinates are unaffected because DPI scales with the pixels; that invariant is what keeps every previously-extracted bbox valid.

factor

linear scale. 2.0 doubles each side and quadruples the pixel count; 0.5 halves it. 1.0 returns None.

interpolation

"auto" picks by direction — cubic when enlarging, area when shrinking, which is the pairing that avoids both softness and aliasing. Override with "nearest" (preserves hard edges on already-binarised pages), "linear", "cubic", or "area".

returns

None when factor is 1.0 within tolerance

Upsample until the page reaches min_dpi, capped at max_dpi.

Upsampling adds no information — but Tesseract's and PaddleOCR's character models are trained around 300 DPI glyph sizes and measurably lose accuracy on smaller input, so the resample buys real recall even though it buys no new signal. The cap exists because beyond ~400 DPI you pay quadratically in pixels for nothing.

Measures against page.quality.effective_dpi — the resolution the text actually carries — not the nominal raster DPI, so a 600 DPI upscan of a 150 DPI fax is correctly seen as still needing help.

min_dpi

floor to reach. 300 is where Tesseract and PaddleOCR are trained; 400 measurably helps on small print and Indic scripts.

max_dpi

ceiling that overrides min_dpi when honouring it would produce an unreasonably large raster. 600 is already past the point of accuracy returns.

interpolation

as rescale; "auto" resolves to cubic here, since this op only ever enlarges.

returns

None when the page is already at or above min_dpi, or when the cap leaves no room to scale

Cap the longest side. Vision-model cost is ~linear in pixels, and most providers downscale above ~1500px anyway — paying to upload pixels the provider will discard is pure waste.

The counterpart to ensure_dpi: that one raises resolution for classical OCR, this one caps it for a VLM. Running both is normal — they clamp opposite ends.

max_px

ceiling for the longer side, in pixels. 2000 is what the vlm policy uses, comfortably above every major provider's internal downscale; 1500 matches it more tightly and costs less; below ~1000 small print stops being legible to the model.

interpolation

"area" by default, which is the correct filter for downscaling — it averages the discarded pixels instead of point sampling, so thin strokes fade rather than disappear.

returns

None when the page is already within max_px

Rotate the page so its text lines are horizontal.

Rotation is skipped below min_angle because resampling always costs a little sharpness, and correcting 0.2 degrees costs more than it recovers. Above max_angle the page is not skewed, it is rotated — a different problem, handled by auto_orient.

Existing span coordinates are rotated with the image rather than discarded.

max_angle

refuse to correct beyond this many degrees. A larger reading almost always means the detector locked onto a table rule or a page edge rather than the text baselines, and acting on it would wreck a page that was fine.

min_angle

skip below this many degrees, since resampling costs sharpness that 0.2 degrees of skew does not. 0.4 is the default; drop to 0.2 only if downstream is a classical OCR engine, which is far more skew-sensitive than a VLM.

method

skew estimator — "auto" (projection profile, then Hough if OpenCV is present), "projection", or "hough". Projection is more robust on dense text; Hough does better on sparse forms with strong rules.

angle

bypass detection and rotate by exactly this many degrees. Use when you already know the skew, e.g. from a calibration target or a previous page of the same batch. Still subject to min_angle and max_angle.

returns

None when the measured skew falls outside [min_angle, max_angle] — the page is left untouched

Rotate by an exact multiple of 90 degrees (lossless).

Quarter-turns resample nothing, so unlike deskew this costs no sharpness and needs no threshold. Span coordinates turn with the page.

degrees

clockwise rotation, rounded to the nearest multiple of 90 and taken modulo 360. 90, 180, 270 are the useful values; -90 is accepted and means the same as 270. 0 returns None.

returns

None when the rotation is a whole number of full turns

Detect and correct 90/180/270-degree page rotation.

Tesseract's orientation-and-script-detection is used when available because it is the only cheap method that can tell upside-down text from right-way-up text. Without it we fall back to a projection-profile test, which reliably distinguishes portrait from landscape text but **cannot** detect a 180-degree flip — that limitation is reported in the page history rather than hidden.

use_osd

allow the Tesseract OSD path when the binary or pytesseract is importable. Set False to force the projection fallback — worth doing when OSD is present but unreliable, which it is on sparse forms and on scripts it was not trained for.

min_confidence

least OSD confidence to act on. Tesseract reports roughly 0.5..5.0 here, and its low-confidence guesses on sparse pages are close to coin flips; 1.0 rejects those. Raise to 2.0 if you would rather leave a page unrotated than risk a wrong quarter-turn.

returns

None when the page is already upright, or when the page has too little ink to judge

Crop away empty margins, keeping margin_pt of whitespace.

Guarded by min_keep: if the detected content occupies less than that fraction of the page, the detection is more likely to have locked onto a speck of dust than onto the content, and the crop is refused.

margin_pt

whitespace to keep around the content, in typographic points (1/72 inch), so it means the same thing at any DPI. 6.0 is roughly a line of leading. Do not drop to 0 — OCR layout analysis degrades when glyphs touch the edge, which is precisely what pad exists to prevent.

min_keep

least fraction of the original area the crop may keep, in 0.0..1.0. At 0.25 a crop discarding more than three quarters of the page is refused and the reason recorded in page.meta["crop_refused"]. Lower it only for documents that genuinely are a receipt on a big scan bed.

returns

None when the page is blank, when the crop would be a no-op, or when min_keep refuses it

Trim the black frame a flatbed leaves when the lid is open.

Those frames wreck contrast measurement and ink coverage, and Tesseract frequently reads them as a column of punctuation.

Trims only inward from the four edges, so unlike crop_to_content it cannot cut into the page when content reaches the margin.

max_frac

most of each dimension the trim may eat, in 0.0..1.0. 0.08 allows an 8% frame, which covers the usual lid-open border while making it impossible to consume a dark but legitimate header.

dark_threshold

mean grey level, 0..255, below which a row or column counts as frame. 90 clears true scanner black (near 0) with margin to spare; raise towards 120 for a grey plastic lid, but not so far that a dense text row qualifies.

returns

None when no edge rows or columns are dark enough to trim

Add a quiet margin. Tesseract's layout analysis degrades noticeably when glyphs touch the image edge.

The usual last step of an OCR policy, after cropping and binarisation have both had the chance to leave text flush against the border.

margin_px

border width in pixels, applied to all four sides. 16 is enough for Tesseract at 300 DPI; scale it with your DPI if you render higher. 0 or negative returns None.

value

fill level, 0..255. 255 (white) is right for a normal page; use 0 after invert_if_dark has left you with light ink on dark paper, so the margin matches the paper rather than framing it.

returns

None when margin_px is not positive

Flatten a photographed page by warping its detected quadrilateral.

Only fires when a convincing four-sided contour covering most of the frame is found, because warping on a bad quad is far worse than not warping: it shears the text irrecoverably. Requires OpenCV.

min_area_ratio

least fraction of the frame the detected quad must cover, in 0.0..1.0. 0.35 rejects the small quadrilaterals that table borders and photo frames produce. Raise towards 0.6 when every photo is known to be page-filling; lowering it is how you get a page warped to the shape of a table.

epsilon_frac

contour simplification tolerance as a fraction of the perimeter. 0.02 is the standard value that collapses a slightly wavy page outline to four corners; too small and the contour keeps more than four vertices and is rejected, too large and unrelated shapes collapse into plausible-looking quads.

returns

None when OpenCV is missing, or when no quad passes both guards — an unwarped page beats a sheared one

Suppress scanner noise.

method="auto" picks bilateral filtering, which smooths flat paper while preserving stroke edges — ordinary Gaussian blur removes noise and glyph detail in equal measure, which is why "denoise then OCR" so often scores worse than doing nothing.

strength

one of "light", "medium", "aggressive". "light" is the only safe default: each step up also erodes diacritics, Devanagari matras and thin CJK strokes, so "aggressive" is for genuinely filthy fax output and nothing else.

method

"auto" (bilateral with OpenCV, median without), "bilateral", "nlmeans", "median", or "gaussian". "nlmeans" is the highest quality and by far the slowest; "gaussian" is the one to avoid, since it blurs strokes and noise alike. "bilateral" and "nlmeans" fall through to a non-OpenCV path when OpenCV is missing.

raises ConfigError

strength or method is not one of the above — a typo here silently disabling denoising would be worse

Remove ink blobs smaller than min_area_px.

Dust, fax speckle and JPEG mosquito noise become spurious punctuation otherwise — which then poisons amount parsing (1.234 vs 1,234).

min_area_px

connected ink components smaller than this many pixels are painted back to the local paper colour. 6 is tuned for 300 DPI, where a full stop covers roughly 12-20 pixels — so the default leaves real punctuation alone. Scale it with the square of your DPI (about 24 at 600 DPI); leave it low if the script carries small marks, since Devanagari matras and Arabic dots are legitimately tiny.

returns

None when the page has no ink, or nothing is small enough to remove

Unsharp masking: img + amount * (img - blur(img)).

The one operation that genuinely recovers readability on soft scans. threshold suppresses sharpening of low-contrast areas so that paper grain is not amplified along with the strokes.

amount

how much of the high-frequency difference to add back. 1.0 is a normal correction, and 1.2 is what the default policy applies to a page measured as blurred. Past about 2.0 strokes gain white halos that OCR segments as extra characters — oversharpening reads worse than the soft original.

radius

Gaussian radius in pixels defining "detail". 2.0 suits 300 DPI body text; raise it for large print, lower it towards 1.0 for dense small type, where a wide radius sharpens the gaps between glyphs rather than the glyphs.

threshold

least absolute difference, 0..255, that gets sharpened at all. 0 sharpens everything including paper grain; 5-10 leaves flat paper alone and is worth setting on any noisy scan.

Grayscale morphology. close fills broken strokes in faded thermal print; open thins bleed-through from the reverse side.

Named from the point of view of the ink, not the pixel values. Because ink is dark, an OCR-sense "dilate the text" is a greyscale erosion, and this op flips the operation for you — so "dilate" thickens strokes, as the name suggests.

operation

one of "open", "close", "erode", "dilate", "tophat", "blackhat". Use "close" for broken strokes, "open" for speckle and show-through, "dilate" to thicken hairline print before OCR, and "tophat" to pull small bright detail off an uneven background. Without OpenCV only the first four are meaningful, as the fallback runs on a binary ink mask.

ksize

structuring element side in pixels, forced odd. 3 is a one-pixel nudge; 5 and 7 act fast, and anything larger tends to merge adjacent glyphs into blobs.

iterations

how many times to apply it. Two passes of 3 are gentler and more controllable than one pass of 5.

raises ConfigError

operation is not one of the six listed (OpenCV path only)

Binarise a grayscale array to a 0/255 image.

otsu

One global threshold from between-class variance. Fast and excellent on evenly-lit print; catastrophic under a shadow gradient.

adaptive

Local mean minus offset. Cheap, robust, slightly noisy.

sauvola (default)

T = m * (1 + k * (s / R - 1)). Designed for degraded documents: it lowers the threshold where local contrast is low, so faint strokes survive without dragging the background in with them.

niblack

T = m + k * s (k negative). Sauvola's predecessor; keeps more faint text, at the cost of needing the min_std guard below.

wolf

Niblack normalised by the global minimum and maximum local deviation. Better than Sauvola when contrast varies wildly across the page.

nick

T = m + k * sqrt(var + m^2). Tuned for very low-contrast scans — the faded thermal-printer case.

bradley

Integral-image mean with a percentage offset. Very fast, and the most forgiving of a badly chosen window.

window should be a little larger than one text line's height. Too small and glyph interiors get their own threshold (hollow letters); too large and it degenerates to Otsu.

min_std guards Niblack, and only Niblack. In a uniform patch of paper the local deviation is ~0, so Niblack's threshold collapses onto the local mean and half the blank page comes out black — its notorious failure mode. Where the local deviation is below min_std there is no local evidence to use, so the global Otsu decision is taken instead. The other local methods need no such guard: Sauvola's (s/R - 1) term, Wolf's normalisation and NICK's sqrt(var + m^2) all drive the threshold well below the mean when deviation vanishes.

gray

the page as a greyscale array; colour input is converted

method

one of "otsu", "adaptive", "sauvola", "niblack", "wolf", "nick", "bradley", each described above. "sauvola" is the default because it degrades most gracefully across the widest range of real scans.

window

local window side in pixels, forced odd, minimum 3. 31 suits 300 DPI body text; use 51-61 at 600 DPI. Ignored by "otsu", which is global.

k

method-specific sensitivity; None selects the published default for the chosen method — 0.2 for Sauvola, -0.2 for Niblack, 0.5 for Wolf, -0.14 for NICK, 0.15 for Bradley. Raising Sauvola's k keeps less faint ink; lowering it keeps more background. Ignored by "otsu" and "adaptive".

offset

grey levels subtracted from the local mean. Used only by "adaptive", where 10 is a mild bias towards keeping ink.

min_std

local deviation below which "niblack" falls back to the global Otsu threshold. Guards Niblack, and only Niblack, against turning blank paper black.

returns

an array of the same shape holding only 0 and 255

raises ConfigError

method is not one of the seven listed

Binarise the page.

Deliberately not part of default_policy. Binarisation reliably lifts classical OCR accuracy and reliably degrades vision-language model accuracy, because VLMs use greyscale gradient to disambiguate faint strokes that a threshold has already destroyed. Apply it in an OCR-bound branch only — see ocr_policy versus vlm_policy.

The op wrapper around binarize_array; every parameter has the same meaning and defaults there, where each method is described in full.

method

"sauvola" (default), "otsu", "adaptive", "niblack", "wolf", "nick", or "bradley"

window

local window side in pixels, forced odd; 31 at 300 DPI

k

method sensitivity; None takes each method's published default

offset

grey levels below the local mean, "adaptive" only

min_std

flat-region guard for "niblack" only

raises ConfigError

method is not one of the seven listed

Erase long ruled lines (table borders, form rules, underlines).

Ruled lines merge with glyphs during OCR line segmentation and turn |1,234| into 11,2341. Removing them costs nothing on prose pages and buys a lot on the ruled tables that dominate hospital bills. keep_text restores pixels where a line crossed a glyph, so struck-through or underlined text is not punched full of holes.

direction

"both", "horizontal", or "vertical". Use "horizontal" alone on statements ruled only between rows, which avoids mistaking a tall bracket or a devanagari shirorekha stem for a vertical rule.

min_len_ratio

least run length for a line to count, as a fraction of the page dimension, in 0.0..1.0. 0.4 means a horizontal rule must span 40% of the width. Lower it towards 0.25 for narrow-column tables; raising it protects underlines from removal.

thickness

dilation in pixels applied to the detected run, so that the anti-aliased edges of a rule are erased along with its core. 2 suits 300 DPI; 3-4 for heavier print or higher DPI.

keep_text

restore pixels that also look like glyph, so a rule crossing a digit does not punch a hole in it. Leave this True unless you are removing rules from a page with no text on them.

returns

None when the page has no ink, or no run is long enough to count as a rule

raises ConfigError

direction is not one of the three listed

Suppress coloured stamps, seals and signatures, keeping black print.

Purple "PAID" stamps and blue ink signatures land on top of the numbers that matter, and OCR reads the overlap as garbage. Detection is by saturation: black toner is unsaturated by definition, so anything strongly coloured is an overlay. coverage_max aborts the removal on genuinely colourful documents (a colour brochure) where the premise does not hold. Requires a colour raster; on grayscale input this is a no-op.

Order matters: run this before to_grayscale, which throws away the hue this op detects with.

saturation_min

least HSV saturation, 0..255, for a pixel to count as coloured. 70 clears black and grey toner, which sit near 0, while catching blue and purple ink. Lower it towards 50 for faded stamps, at the risk of eating colour-tinted paper.

value_min

least HSV value (brightness), 0..255. 40 excludes near-black pixels whose hue is meaningless noise — without it, dark toner gets classified by whatever hue the sensor guessed.

coverage_max

abort if more than this fraction of the page is coloured, in 0.0..1.0. At 0.25 a colour brochure or a coloured-paper form is left alone, because there the premise "colour means overlay" is simply false. The reason lands in page.meta["remove_stamps"].

returns

None on greyscale input, when nothing is coloured, or when coverage_max aborts the removal

Split a page carrying several documents into one page per document.

Two bills photocopied side by side onto one A4 is routine, and every downstream assumption (one header, one total) breaks on it. Splitting is by wide whitespace gutters in the ink projection profile.

Returns [page] unchanged when no confident split is found — a false split is much more damaging than a missed one, so the thresholds are deliberately conservative.

Not an Op: ops map one page to one page, and this changes the page count. Reach for it through Pipeline(split_pages=True), or apply it document-wide with split_document.

page

a page with a raster; a page without one is returned as-is

axis

"auto", "vertical", or "horizontal". "auto" prefers whichever axis yields more gutters, which handles both side-by-side and stacked layouts. Name the axis when you know it — forcing "vertical" on side-by-side bills stops a wide gap between table sections being read as a horizontal split.

min_gap_frac

least whitespace-gutter width for a split, as a fraction of the page dimension, in 0.0..1.0. 0.06 is about half an inch on A4. Raise it if inter-column spacing is being read as a document boundary.

max_parts

refuse the split entirely if it would produce more than this many pages. 3 reflects what fits on a sheet; a result of eight parts means the detector found text columns, not documents.

min_part_frac

least fraction of the page each part must occupy, in 0.0..1.0. At 0.2 a cut near the edge — a margin note, a punch-hole strip — cannot become its own document.

returns

one page per detected document, each with split_from and split_part in page.meta and spans remapped into its own coordinate space; or [page] when no confident split was found

raises ConfigError

axis is not one of the three listed

Apply split_multi_bill_page across a document, renumbering pages.

Renumbering matters: every span's bbox.page and every provenance reference is keyed by page index, so the new pages are reindexed contiguously rather than inheriting the index they were split from.

doc

the document to split; it is not mutated

kwargs

forwarded per page to split_multi_bill_page — axis, min_gap_frac, max_parts, min_part_frac

returns

a new Document whose pages are numbered from 0; pages that did not split carry through unchanged

Correct the distortions this page actually has, and nothing else.

Reads only from page.quality, so it is pure, testable, and cheap to audit. Every branch here corresponds to a measured degradation; there is no unconditional step, because a clean 400 DPI native render needs nothing done to it and every op applied to it can only remove signal.

Reader-agnostic by design, which is why it omits binarisation — that helps classical OCR and hurts VLMs, so it belongs in ocr_policy, not here.

page

a page whose quality measure_page has already filled in. On an unmeasured page every reading is zero and this returns an empty list.

thresholds

the cut-offs each branch compares against; None uses DEFAULT_THRESHOLDS. Pass a modified QualityThresholds to retune the whole policy without rewriting it — e.g. dataclasses.replace( DEFAULT_THRESHOLDS, min_dpi=400) to upsample more eagerly.

returns

the ops this page warrants, in application order; empty for a page that needs nothing

Policy for classical OCR engines (Tesseract, Paddle, docTR).

Everything default_policy does, plus the steps that only make sense when a threshold-based recogniser is downstream: line removal, ruled-form cleanup, and binarisation.

Line removal is conditional on the page looking tabular, but greyscale conversion, binarisation, despeckling and padding are unconditional — every classical engine wants them, so there is no measurement to gate on.

page

a page whose quality has been measured

thresholds

as default_policy; None uses DEFAULT_THRESHOLDS

binarization

method passed to binarize — "sauvola" (default), "otsu", "adaptive", "niblack", "wolf", "nick", or "bradley". Try "otsu" on evenly-lit laser print, where it is faster and marginally cleaner; stay on "sauvola" for anything photographed or faded.

returns

the ops for this page, ending with the binarise-despeckle-pad sequence that classical OCR expects

Policy for vision-language models.

Gentler on purpose. No binarisation (it destroys the greyscale gradient the model reads faint strokes from), no aggressive denoising (it removes diacritics and thin Devanagari strokes), and a hard pixel cap because cost scales with image size while accuracy stops improving well before the provider's limit.

Its skew tolerance is also twice default_policy's, since vision models read moderately tilted text without help and the resampling would cost more sharpness than the tilt costs accuracy.

page

a page whose quality has been measured

thresholds

as default_policy; None uses DEFAULT_THRESHOLDS. Note the skew branch here compares against twice skew_correct_deg.

max_side

pixel cap for the longer side, handed to resize_max_side. 2000 is comfortably above every major provider's internal downscale; 1500 cuts cost with no measurable accuracy loss on ordinary print.

returns

a short op list — often empty for a clean page, which is the intended behaviour

Apply nothing. Useful as an eval baseline.

Distinct from policy=None in intent only — both skip preprocessing. Use this one when you want a named policy in the eval report, so the baseline row reads no_policy rather than None.

page

ignored; the signature exists to satisfy PolicyFn

returns

always an empty list

Turn a fixed op list into a policy, for A/B against adaptive ones.

The honest way to test the library's central claim. Pit a fixed sequence against default_policy in an EvalSuite and see

whether adapting to measured quality actually wins on your documents:

fixed = fixed_policy(deskew(), binarize(), despeckle())

ops

the ops to apply to every page, in order. A fresh copy of the list is returned per page, so callers cannot mutate it.

returns

a PolicyFn ignoring page quality entirely

All non-empty spans joined by spaces, in the order returned.

JSON-ready dict. raw is deliberately excluded (unbounded size).

Whether this backend can read page at all.

Asked per page, so the answer may legitimately differ across a document: a text-layer backend supports the digital pages of a mixed PDF and not the scanned ones.

page

the page in question

returns

False when this backend needs a raster the page lacks, when its dependencies are missing, or when the page is otherwise outside what it handles

Whether this backend's dependencies are importable right now.

Part of the protocol, not just of BaseBackend: the routers call it to skip a backend whose engine is not installed, so a custom backend that omits it breaks routing rather than merely failing to read.

Predicted cost of reading page, before doing it.

Consulted by BudgetRouter to decide whether a page can afford this backend, so it must not read the page or call the provider.

page

the page that would be read

returns

a Cost; Cost.zero() for local engines. Money is 0.00 until set_pricing is called, though token counts are always real.

Read page and return its spans, cost and timing.

page

the page to read; implementations must not mutate it

returns

a ReadResult whose spans carry text, geometry and per-span confidence. A page the backend could not read yields an empty span list and a warning, not an exception — one bad page must not cost the document.

Configure the backend.

name

overrides the class-level registry name, so the same engine can be registered twice with different options

options

passed through to the underlying engine at construction

Whether this backend can read page at all.

page

the page in question

returns

True unless the page lacks a raster this backend needs, or is_available is False. Override to add engine-specific limits, such as a script or a page-size ceiling.

Whether this backend's dependencies are importable right now.

Predicted cost of reading page. Free by default (local engines).

page

the page that would be read

returns

Cost.zero(). Vision backends override this; see the per-token estimate in estimate_cost.

Read page, timing the call and tagging spans with this backend.

Do not override this; implement _read instead. This wrapper is what fills in latency, stamps span.source with the backend name, and detects the script of each span — three things every backend would otherwise have to remember.

page

the page to read

returns

the ReadResult from _read, with latency_ms, backend, and each span's source and script filled in

Do the actual reading. Subclasses implement this, not read.

Timing, span sourcing and script detection are handled by read, so an implementation only has to produce spans.

The raster this backend should see, at its preferred DPI when free.

Pixel coordinates from an engine -> canonical page points.

Start empty. Factories are registered, never instances.

Register a backend under name.

Prefer a callable: instantiating PaddleOCR or Surya loads hundreds of megabytes of weights, and a document that never routes there must not pay for it. Passing an instance is supported for cheap backends and

test doubles, and constructs eagerly by definition:

registry.register("myocr", lambda: MyOCRBackend(lang="hi"))

name

the routing key, as used by backend="myocr" and by any RuleRouter rule

factory

a zero-argument callable returning a backend, or a backend instance (wrapped in a callable for you)

replace

allow overwriting an existing registration. Off by default so a name collision is an error rather than a backend that silently stops being used; any cached instance is dropped.

raises ConfigError

name is taken and replace is False

Instantiate (once) and return the backend registered as name.

The instance is cached under the lock, so the weights load once even if several pages race for the same backend.

name

a registered name, e.g. "tesseract" or "anthropic"

returns

the shared backend instance

raises ConfigError

nothing is registered under name; the message lists what is

"tesseract" in registry — true if registered, available or not.

Registered is not the same as usable: use available to ask whether the engine's dependencies are actually importable.

name

the name to look for

returns

whether a factory exists under that name

registry["tesseract"] — alias for get.

name

a registered name

returns

the shared backend instance

raises ConfigError

nothing is registered under name

Every registered name, sorted.

Names whose dependencies are importable, without constructing them.

Drop cached instances, keeping the factories.

Next use reconstructs them — which is how a test swaps a backend's configuration, and how a long-lived process releases model weights.

True only for a page that already carries a trustworthy text layer.

Stricter than supports on purpose: a scanned page in a PDF has a text layer of empty strings, and reading that would return nothing while looking like a success.

page

the page in question

returns

True only when the page is DIGITAL_NATIVE or HYBRID and already carries spans — see classify_page_kind

Return the page's existing native spans, re-tagged as this backend's.

Configure the engine.

lang

Tesseract language code(s), +-joined, e.g. "eng", "eng+hin", "eng+deu". Each needs its traineddata installed; naming a missing one fails at read time, not here.

psm

page segmentation mode. 3 (fully automatic) is right for a whole page; 6 ("a single uniform block") is markedly better on a cropped table cell or a form field; 7 reads one line, 11 finds sparse text in any order.

oem

OCR engine mode. 3 picks the best available, 1 forces the LSTM engine, 0 the legacy one. Leave it at 3 unless you are reproducing an old result.

config

extra flags appended to the command line, e.g. "-c tessedit_char_whitelist=0123456789.," to read an amounts-only column.

min_confidence

drop words below this confidence, in 0.0..1.0. 0.0 keeps everything, which is the right default — confidence is a fusion input, and dropping words here hides evidence from locate_value rather than improving accuracy.

name

overrides the registry name, so the same engine can be registered twice with different options

options

forwarded to BaseBackend

True when either pytesseract or the tesseract binary is present.

The --psm/--oem/extra flags as one command-line string.

Read via pytesseract when importable, else via the binary.

Read through pytesseract's word-level TSV output.

Shell out to tesseract, parsing TSV. Used when pytesseract is absent.

Configure the engine.

lang

PaddleOCR language code, e.g. "en", "ch", "devanagari". One per engine instance — register the backend twice under different names to read two scripts.

use_angle_cls

run the text-direction classifier, needed for pages with rotated or vertical text. Costs a little latency per page and is worth keeping on for anything photographed.

name

overrides the registry name, so the same engine can be registered twice with different options

options

forwarded to BaseBackend

True when paddleocr is importable.

Construct the engine once, under the lock. Loads model weights.

Run PP-OCR and convert its quads into spans.

Configure the engine.

name

overrides the registry name, so the same engine can be registered twice with different options

options

passed straight to RapidOCR at construction, e.g. det_model_path=... to point at your own ONNX weights

True when either RapidOCR distribution is importable.

Construct the engine once, under the lock. Loads ONNX weights.

Run RapidOCR and convert its quads into spans.

Configure the engine.

languages

EasyOCR language codes loaded together, e.g. ("en",) or ("en", "hi"). EasyOCR restricts which codes may be combined — Latin scripts mix freely, but most non-Latin scripts pair only with English.

gpu

use CUDA if EasyOCR finds it. False is the safe default; on CPU this engine is several times slower than PP-OCR.

name

overrides the registry name, so the same engine can be registered twice with different options

options

forwarded to BaseBackend

True when easyocr is importable.

Construct the reader once, under the lock. Loads model weights.

Run EasyOCR and convert its quads into spans.

Configure the two-stage predictor.

det_arch

text-detection architecture. "db_resnet50" is the accurate default; "db_mobilenet_v3_large" is markedly faster and a little worse on small print.

reco_arch

recognition architecture. "crnn_vgg16_bn" is the balanced default; "crnn_mobilenet_v3_small" trades accuracy for speed, and "master" or "parseq" cost more for better results on irregular text.

pretrained

download pretrained weights rather than start cold. False is only useful when loading your own fine-tuned weights — an untrained model reads nothing.

name

overrides the registry name, so the same engine can be registered twice with different options

options

forwarded to BaseBackend

True when doctr is importable.

Build the OCR predictor once, under the lock. Loads model weights.

Run docTR and scale its relative geometry back into pixels.

Configure the engine.

languages

script/language hints passed to the recogniser, e.g. ("en",) or ("en", "hi"). Surya detects script itself, so these are hints rather than a restriction — which is why it handles a Devanagari letterhead over a Latin amounts table without being told the page is mixed.

name

overrides the registry name, so the same engine can be registered twice with different options

options

forwarded to BaseBackend

True when surya is importable.

Build (detection, recognition) predictors once, under the lock.

Surya's constructor signature has changed across releases, so several known variants are tried before giving up with a clear error.

Construct a predictor via the older SuryaInferenceManager API.

Construct a predictor via the newer FoundationPredictor API.

Run Surya and convert its text lines into spans.

Register token prices (USD per million tokens) for model.

Until a model is priced, Cost reports token counts with a zero amount and warns once, so a missing price is visible rather than silently reported as free.

Register what your account actually pays, not the list price — committed spend and enterprise agreements both move it, and the point of this table

is that the number in the report is one you can defend:

Pricing.set_pricing("claude-sonnet-4-5", 3.0, 15.0)

model

the model id exactly as the backend reports it in Cost.model; a mismatched string leaves the model unpriced

input_per_mtok

USD per million input tokens, e.g. 3.0

output_per_mtok

USD per million output tokens, e.g. 15.0, typically several times the input rate

Convert token counts to a Cost using the registered pricing.

model

the model id to look up in PRICING

input_tokens

prompt tokens consumed

output_tokens

completion tokens produced

returns

a Cost for one call. When the model is unpriced the token counts are still exact and amount is 0.0, with a warning logged once per model — never an exception, since an unpriced model must not stop a document being read.

Approximate the token cost of an image for a vision model.

Providers bill images roughly by area; width * height / 750 is the documented approximation for Claude and is close enough for OpenAI's high-detail mode to be useful for budgeting. It is an estimate, and the reconciled figure from the response's usage block always wins.