# Model-assisted document checks

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

Source: https://openbooks.lumeo.co.in/docs/model

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 [#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 [#reproduce-a-model-checked-run]

~~~bash
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 [#inspect-model-output]

The [role inspection endpoint](/docs/engine-api) 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](/docs/output-contract).

## Evaluate on your inputs [#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.
