Skip to Content
Open Books for developers

Model-assisted document checks

Learn how local role inference, calibrated abstention and model hashes work when processing PDF and scanned statements.

The optional model adds a cross-check for PDF and image processing. It runs locally in the Python engine with the scan extra. A token is a word or other extracted text item with a position on the page. The model uses the token's text, shape, and bounding box to make two predictions.

PredictionExamplesWhat it checks
Column roleDebit, credit, balanceWhether the token appears to belong to a particular part of a statement row.
Value typeMoney, dateWhether the token appears to contain the type of value expected there.

From words to a cross-check

  1. The document front end produces words and boxes from the PDF text layer or OCR.
  2. Geometry reconstructs rows and columns. The optional model cross-check predicts the roles and value types.
  3. Calibration maps prediction scores to a set of plausible classes. The model abstains when its role set has zero candidates or more than one. Where applicable, balance constraints can help resolve ambiguous readings.
  4. The engine uses the model as an additional check on an otherwise verified reading. An unsupported reading can produce LOW_CONFIDENCE. A release still requires the financial checks and independent evidence.

Reproduce a model-checked run

python -m pip install "openbooks[scan]==0.2.0"
python -m openbooks doctor --deep
python -m openbooks run statement.pdf --currency INR --date-order dmy --model

The distribution ships model weights and a calibration file bound to those weights by SHA-256. If you set OPENBOOKS_MODELS_DIR, point it to a compatible pair. For a release that used the model, save the weights and calibration hashes under file.model with the input hash, engine version, and run options. Run doctor --deep to check the pair and the local model runtime when changing environments.

Inspect model output

The role inspection endpoint returns openbooks.roles.v1 for a PDF or image. Use text and the normalized box to locate a token on the page. Read role, role_set, vtype, type_set, and abstained to see what the model predicted and where it abstained. For a document decision, use the processing endpoint and read its verified output.

Evaluate on your inputs

The model was trained, calibrated, and evaluated on synthetic data. Before enabling it for a layout, compare release and refusal behavior on representative inputs. Review which values or columns cause abstention and check whether those cases cluster around a scan quality or statement layout.

The two prediction heads share a six-layer Transformer encoder with roughly 19 million parameters. The shipped weights use 8-bit storage.

View this page as Markdown