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.
| Prediction | Examples | What it checks |
|---|---|---|
| Column role | Debit, credit, balance | Whether the token appears to belong to a particular part of a statement row. |
| Value type | Money, date | Whether the token appears to contain the type of value expected there. |
From words to a cross-check
- The document front end produces words and boxes from the PDF text layer or OCR.
- Geometry reconstructs rows and columns. The optional model cross-check predicts the roles and value types.
- 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.
- 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 --modelThe 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.