# Architecture and verification
Understand parsing providers, Decimal normalization, deterministic verification, typed model cross-checks and the hosted runtime topology.
Source: https://openbooks.lumeo.co.in/docs/architecture
The Python engine owns the document decision. The CLI, Node.js wrapper, web workspace, and MCP server give callers different ways to submit an input and inspect that decision.
## How a document is processed [#how-a-document-is-processed]
1. **Detection chooses the provider.** The engine examines the file type and content signatures, such as a CSV header or a structured balance record.
2. **Extraction reads the document.** A structured parser reads fields directly. The document front end reads words and positions from PDF text or OCR. The provider records source evidence as it builds records.
3. **Normalization produces a shared shape.** The engine represents amounts with exact decimals, records direction separately, and associates transactions with their batch and account.
4. **Verification checks the source.** Statement batches can check opening balance plus signed movements against closing, running balances, and continuity. Settlements check row and total arithmetic. Tax providers apply their own checks.
5. **Contract validation checks the release.** The engine checks schema, required evidence, record references, and the assertions. A failed financial check or insufficient independent evidence results in a typed refusal.
Trace these stages with the [two-row sample](/docs/quickstart). The supplied opening of INR `1000.00` and movements of `−100.00` and `+50.00` compute a closing balance of `950.00`. The source's printed balance supplies the independent comparison.
## Runtime paths [#runtime-paths]
~~~text
Python application ── process() ─────────────────→ Python engine
Node.js application ── typed wrapper ── subprocess → Python engine
Browser workspace ── Next.js ── private HTTP ────→ FastAPI → Python engine
MCP client ── Open Books MCP server ──────→ Python engine
~~~
The Node.js wrappers validate the documents they receive and can restrict accepted layouts. The Next.js web tier proxies workspace uploads and streams decisions from FastAPI. The service stages files in a per-run temporary directory and cleans them up after processing. The workspace keeps history and released outputs in the browser. Deployments can enable Q&A for released documents, with deterministic calculations performed by application code.
## Provider boundaries [#provider-boundaries]
`openbooks.core` owns format detection, normalisation, validation and the provider registry. `openbooks.statements` handles bank files and the PDF/OCR front end. `openbooks.gateways` handles payment exports, `openbooks.tax` supplies tax and workpaper parsers, and `openbooks.doctor` reports install health.
Providers are registered using Python distribution entry points such as `openbooks.layouts`, `openbooks.sniffers`, `openbooks.frontends`, and `openbooks.gates`. Install the package in editable mode when working from a checkout so Python can discover these entry points. Adding a layout requires both recognition rules for the input and a registered provider that can parse and verify it. Use `python -m openbooks engine-info` to inspect the installed layout IDs.
See the [engine HTTP API](/docs/engine-api), [model guide](/docs/model), and [MCP integration](/docs/mcp) for the other runtime paths.
---
# Bank statements
Integrate bank statement extraction, supply verified opening balances and dates, and use running-balance assertions before posting transactions.
Source: https://openbooks.lumeo.co.in/docs/bank-statements
Reconciliation means checking that the transactions explain the change in the account balance. This guide covers structured exports. Use the [PDF and OCR guide](/docs/pdf-and-ocr) when the bank provides a PDF or image.
| Export | What to prepare |
| --- | --- |
| CSV | Keep the date, debit, credit, and running-balance columns. Supply the currency and opening balance when the export omits them. |
| OFX or QFX | Use the original export with its currency and ledger balance. Supply an authoritative opening balance. |
| MT940 | Preserve the original opening and closing balance records and any statement segments. |
## Reconcile your first export [#reconcile-your-first-export]
### Identify the layout and currency [#identify-the-layout-and-currency]
Use the original export for one account and statement period. A running balance is the amount after each transaction. If the CSV has no currency, supply its three-letter code, such as `INR`. Set `date_order` to `dmy` or `mdy` when you know the source convention. For example, `02/01/2026` means January 2 with `dmy` and February 1 with `mdy`.
### Supply the opening balance [#supply-the-opening-balance]
Bank CSV and OFX need an opening balance from the caller when they lack one. Use the verified closing balance of the preceding statement or another authoritative source. MT940 carries opening and closing records. Keep money in exact decimal form.
~~~bash
python -m openbooks run statement.csv --currency INR --opening 1000.00 --date-order dmy
~~~
The CLI writes the decision under `out/`. Use the previous statement's closing amount only after confirming the account, currency, and period.
### Verify before posting [#verify-before-posting]
Check `status` first. In a release, use `data.batches` for opening and closing balances, `data.transactions` for individual movements, and `assertions` for the checks that passed. If your ledger expects signed amounts for bank movements, subtract debits and add credits using the separate `direction` field. Use decimal arithmetic and keep the currency with each amount.
## Design for mismatches [#design-for-mismatches]
1. Hold a file that returns `BALANCE_MISMATCH` for review and save the refusal in your job history.
2. Check the opening amount and compare the source running balances and closing balance. Look for missing rows, a truncated export, duplicate transactions, or a file that combines statement periods.
3. Re-export the statement or correct verified parameters, then run it again. Use [source evidence](/docs/output-contract#evidence-and-independent-checks) to trace the values in the release.
Supported layouts can derive an opening balance from the first movement and its running balance when you opt in. This arithmetic explains where the amount came from. Independent verification still requires evidence from the source. Use a documented opening balance when you can verify one.
For a runnable fixture and JSON output, use the [bank CSV quickstart](/docs/quickstart).
### Compare a release with a broken balance [#compare-a-release-with-a-broken-balance]
In the [workspace](/app), run **Bank statement CSV** alongside **Bank CSV with a tampered balance**. The second fixture uses a correct opening balance but contains a broken running-balance row. Its `BALANCE_MISMATCH` message reports that seven of eight rows tie out. Review the running-balance check and re-export the source if you encounter this in your own files. Changing a known opening balance would change the arithmetic for the rest of the statement.
---
# Build a bank statement importer
Use the Python engine to validate bank CSVs, preserve full decisions, and compute exact totals for an import job.
Source: https://openbooks.lumeo.co.in/docs/build-an-importer
Build a small Python job that accepts a bank CSV, saves the engine's decision, and prints the totals an accounting integration could use. You'll see how to handle a document refusal without treating it as a crash and how to retain the evidence behind a release.
## 1. Prepare the input and settings [#1-prepare-the-input-and-settings]
1. Follow the [Python installation guide](/docs/installation), then open a terminal with the virtual environment active.
2. [Download the sample CSV](/examples/statement.csv) and save it as `statement.csv` in your working directory.
3. Use the sample's known currency, date order, and opening balance. For a real import, store those settings per file. The currency is `INR`, the date order is `dmy`, and the sample's verified opening balance is `1000.00`.
## 2. Write the import job [#2-write-the-import-job]
Save the script as `verify_import.py` beside the CSV. The first command-line argument is the input, the second is where to save the JSON decision, and the optional third argument is the opening balance. For simplicity, this tutorial uses INR and day-first dates for every input.
~~~python
import argparse
import json
from decimal import Decimal
from pathlib import Path
from openbooks import EngineFault, Params, process, validate_output
parser = argparse.ArgumentParser()
parser.add_argument("statement", type=Path)
parser.add_argument("decision", type=Path)
parser.add_argument("--opening", type=Decimal)
args = parser.parse_args()
try:
decision = process(
args.statement,
Params(currency="INR", date_order="dmy", opening=args.opening),
strict=True,
)
except (EngineFault, OSError) as error:
parser.exit(3, f"Engine failed: {error}\n")
# Use a separate decision path for each attempt you want to retain.
with args.decision.open("x", encoding="utf-8") as output:
json.dump(decision, output, indent=2, ensure_ascii=False)
output.write("\n")
if decision["status"] == "refused":
error = decision["error"]
parser.exit(1, f'{error["code"]}: {error["message"]}\n')
validate_output(decision)
if decision["file"]["layout_version"] != "bank_csv.v1":
parser.exit(2, "This importer accepts the bank CSV layout.\n")
transactions = decision["data"]["transactions"]
totals = {"debit": Decimal("0.00"), "credit": Decimal("0.00")}
for transaction in transactions:
totals[transaction["direction"]] += Decimal(transaction["amount"]["amount"])
print(f"Released {len(transactions)} transactions")
print(f'Debits: {totals["debit"]:.2f} INR')
print(f'Credits: {totals["credit"]:.2f} INR')
print(f'Net movement: {totals["credit"] - totals["debit"]:.2f} INR')
~~~
`process()` returns the full document. The script saves it before branching on `status` so a refusal remains available for review. It opens the destination in exclusive-create mode. Use a fresh decision filename when repeating a run.
## 3. Run both outcomes [#3-run-both-outcomes]
Run these commands individually. The first exits with code `1` and writes a `PARSE_ERROR` refusal to `refused.json`. The second supplies the verified balance and writes the release to `released.json`.
~~~bash
python verify_import.py statement.csv refused.json
python verify_import.py statement.csv released.json --opening 1000.00
~~~
The corrected run prints:
~~~text
Released 2 transactions
Debits: 100.00 INR
Credits: 50.00 INR
Net movement: -50.00 INR
~~~
Open `released.json` and confirm the net movement explains the change from INR `1000.00` to INR `950.00`. The assertion for the closing balance ties out, and `evidence["batch-1.closing"]` points to the third row of the CSV.
## 4. Connect the job to your application [#4-connect-the-job-to-your-application]
| Keep | How to use it |
| --- | --- |
| Import job ID, source hash, engine version, and supplied settings | Identify the attempt and reproduce it. The same source bytes can produce different decisions with different settings. |
| Full release or refusal | Keep the original JSON so a reviewer can trace a reported number or refusal. |
| Document and record IDs | Associate imported rows with their source. Scope a transaction ID such as `txn-00001` to its document. |
| Currency and decimal value | Keep them together when storing amounts. Group by currency before computing totals for a multi-currency application. |
Before writing to a ledger, decide how your application identifies a duplicate import. A transaction ID from the JSON is local to its document. If your application retries jobs, keep the import status and ledger write together so a retry after a partial failure does not post the same entries twice.
Next, [test the integration](/docs/test-an-integration) with a missing parameter, a balance mismatch, and a source that releases.
---
# CLI commands and exit codes
Run financial files through the Python or npm CLI with reproducible flags, JSON output and diagnostic commands.
Source: https://openbooks.lumeo.co.in/docs/cli
The Python and npm installs both provide a command named `openbooks`. Use `python -m openbooks` to invoke the Python command explicitly when both are on your path.
## Run a file and find the result [#run-a-file-and-find-the-result]
Complete the [installation guide](/docs/installation), then open a terminal with the input file in the current directory. You can [download the sample CSV](/examples/statement.csv) to follow these commands. For your own file, replace the opening amount, currency, and date order with the verified values for that statement.
~~~bash
python -m openbooks run statement.csv --opening 1000.00 --currency INR --date-order dmy --out output
python -m openbooks engine-info
python -m openbooks doctor --json
~~~
`run` writes a decision under `--out` (default `out`) and prints its filename. Add `--machine` for one JSON summary per processed file and a final engine-info line on a completed run. Each summary has `file`, `status`, `code`, and `output`. Read the file at `output` for the complete decision.
~~~bash
openbooks run statement.csv --opening 1000.00 --currency INR --date-order dmy --out output --json
openbooks statements run statement.csv --opening 1000.00 --currency INR
openbooks engine-info
openbooks doctor --deep
~~~
The npm CLI also accepts a file directly, with `run` implied. Use `statements run`, `gateways run`, or `tax run` to restrict allowed layouts. For a project-local install, prefix the commands with `npx`. `--json` writes a JSON array of result wrappers to stdout. `--out` additionally writes the underlying engine documents as individual JSON files.
Open the JSON under `output/` and read `status` before accessing records. A refusal file contains the code, message, and input hash. Both CLIs use the input's SHA-256 hash as the filename. Use separate output directories when comparing different options for the same bytes.
## Flags for reproducible runs [#flags-for-reproducible-runs]
| Flag | Effect |
| --- | --- |
| `--currency INR` | Supply a known currency where required. |
| `--opening 1000.00` | Supply a verified opening balance. |
| `--account ` | Supply an account identifier where supported. |
| `--date-order dmy` | Interpret numeric dates as day-first. Use `mdy` for month-first. |
| `--allow-derived-opening` | Opt into a calculated opening for supported layouts. |
| `--no-ocr` | Disable OCR for document runs. |
| `--model` (Python), `--no-model` (npm) | Python opts into the model. The npm CLI opts out of its default document cross-check. |
| `--python `, `--timeout ` (npm) | Select the interpreter or bound runtime. |
| `--max-document-bytes ` (npm 0.2.1+) | Limit each serialized proof. The default is 64 MiB. |
## Run exit codes [#run-exit-codes]
| Code | Meaning | Batch job action |
| --- | --- | --- |
| `0` | Every file released. | Read the documents and retain their evidence. |
| `1` | One or more files refused. | Read each result and route refusals to review. |
| `2` | Invalid command or argument. | Correct the invocation. |
| `3` | Execution failed, for example because the engine could not open a file or timed out. | Check input paths, installation, and runtime limits. |
In Bash, read the exit code with `echo $?`. In PowerShell, use `$LASTEXITCODE`. Check it immediately after running Open Books. With a batch, use the individual result statuses to decide which files you can import.
## Run more than one file [#run-more-than-one-file]
Pass multiple paths to `run` when they share the same options. Run files separately when each needs a different opening balance, or use the Python CLI's `report` command to process a folder. A `params.json` in the folder can specify context keyed by filename. See each command's `--help` for accepted options. The Python CLI also exposes `eval` for fixture sets and `link` for payout matching when the optional linker is installed.
---
# Self-hosted HTTP API
Run the FastAPI engine on a private network, upload batches with multipart forms and consume server-sent release or refusal events.
Source: https://openbooks.lumeo.co.in/docs/engine-api
Use the self-hosted API when your application server needs to send files to a separate Open Books process and receive progress and decisions as they arrive. The FastAPI service wraps the Python engine. Run it on loopback or a private network and apply authentication and rate limiting at your application boundary.
## 1. Start the service [#1-start-the-service]
From the repository checkout, create and activate a Python 3.11+ virtual environment using the [installation guide](/docs/installation). Run these commands from the checkout root and leave the server running.
~~~bash
python -m pip install -e packages/py/openbooks -e server
python -m uvicorn openbooks_server.app:app --host 127.0.0.1 --port 8765
~~~
If OCR is needed, use `-e "server[scan]"` in the installation command and check its OCR and model dependencies. For an MCP client, use the separate [Open Books MCP server](/docs/mcp).
## 2. Check health and capabilities [#2-check-health-and-capabilities]
In a second terminal, request engine health. On Windows PowerShell, use `curl.exe` in place of `curl` if your shell treats `curl` as an alias.
~~~bash
curl http://127.0.0.1:8765/v1/health
~~~
Check that the service responds and reports `openbooks.v1`. Read the capability flags before sending scans, requesting model roles, or matching payouts. For example, check `link_available` before calling the optional linking endpoint.
## Endpoint reference [#endpoint-reference]
| Method and path | Request and response |
| --- | --- |
| `GET /v1/health` | Engine and schema versions, OCR/model/link capabilities and limits. |
| `GET /v1/formats` | Supported formats and layouts that are unverified on real exports. |
| `GET /v1/samples` | Synthetic sample catalog, with file metadata and sample parameters. |
| `GET /v1/samples/{id}` | Bytes of a bundled synthetic example. |
| `POST /v1/runs` | Multipart `files` and optional JSON string fields `params` and `file_params`. Streams SSE. |
| `POST /v1/roles` | Multipart `file` and optional `params`. Returns `openbooks.roles.v1`. Requires model availability. |
| `POST /v1/link` | JSON `{"docs": [...]}` containing released documents. Optional linker returns `openbooks.links.v1`. |
One run takes up to 20 files. The shared `params` field accepts `currency`, `opening` as a decimal string, `account`, `date_order` (`dmy` or `mdy`), and the boolean flags `allow_derived_opening`, `ocr`, and `model`. To override a field for a file, use its zero-based index in `file_params`. For example, `{"1":{"opening":"1590.12"}}` sets the opening balance for the second upload while retaining the other shared settings.
## 3. Upload a file and read the stream [#3-upload-a-file-and-read-the-stream]
Download the example CSV into your current directory. Run the following command in a POSIX shell, such as Bash. The `-F` options build the multipart form and `-N` displays events as curl receives them.
~~~bash
curl -N http://127.0.0.1:8765/v1/runs \
-F 'files=@statement.csv' \
-F 'params={"currency":"INR","opening":"1000.00","date_order":"dmy"}'
~~~
The response uses server-sent events (SSE). Each SSE frame has an event name and JSON data. The sample produces a `file.done` event at index `0` with `doc.status: "ok"`, followed by `run.done` with `released: 1` and `refused: 0`.
| Event | Interpret it as |
| --- | --- |
| `file.started` | The file entered processing. Track it by `index`. |
| `file.stage` | Stage progress. It carries no release decision. |
| `file.done` | `doc` contains that file's full release or refusal. |
| `run.done` | The run finished with aggregate counts. |
| `run.error` | A run-level error interrupted processing. Inspect the reported cause. |
### Override settings for one file [#override-settings-for-one-file]
The example sends the same sample twice to demonstrate how shared and per-file settings interact. The first file inherits the verified opening. The second clears it with `null` and needs review.
~~~bash
curl -N http://127.0.0.1:8765/v1/runs \
-F 'files=@statement.csv' \
-F 'files=@statement.csv' \
-F 'params={"currency":"INR","opening":"1000.00","date_order":"dmy"}' \
-F 'file_params={"1":{"opening":null}}'
~~~
Expect a `file.done` release at index `0`, a `file.done` refusal with `PARSE_ERROR` at index `1`, and `run.done` with `released: 1` and `refused: 1`. Use the index to associate each decision with its upload settings, even if the filenames are identical.
## 4. Handle failures and interrupted runs [#4-handle-failures-and-interrupted-runs]
1. Check the HTTP status before parsing SSE frames. A `422` can indicate invalid request parameters. A `503` on roles or link can indicate an unavailable capability.
2. Use an SSE parser that can assemble a frame split across network chunks. Track file decisions by index and store each full `file.done` document.
3. Use `run.done` as the batch completion signal. On `run.error` or a closed connection before completion, keep completed file decisions and mark files without `file.done` as interrupted.
4. Retry interrupted files and handle `doc.status: "refused"` using the [refusal guide](/docs/refusals). Send only released documents to downstream accounting.
---
# Supported formats and layouts
Find supported CSV, OFX, MT940, PDF, OCR and Excel formats, with layout identifiers and the requirements for each financial document.
Source: https://openbooks.lumeo.co.in/docs/formats
An extension describes the container, such as `.csv` or `.xlsx`. A layout describes the document inside it, such as a bank statement or a Stripe balance report. Open Books uses file contents and extension rules to detect the layout. Check `file.layout_version` on a release when routing documents in your application.
## Format matrix [#format-matrix]
| Document | Layout ID | Inputs and requirements |
| --- | --- | --- |
| Bank statement CSV | `bank_csv.v1` | Recognised date, debit, credit and running-balance columns. Supply opening and currency when needed. |
| OFX / QFX | `ofx.v1` | OFX content with currency and ledger balance. Supply the opening balance. |
| SWIFT MT940 | `mt940.v1` | MT940 text, commonly `.sta`, `.mt940` or `.txt`. Opening and closing come from balance records. |
| Bank statement PDF or scan | `bank_statement_pdf.v1` | `.pdf`, `.png`, `.jpg`, `.jpeg`. Scans need [OCR](/docs/pdf-and-ocr). |
| Stripe balance export | `stripe_balance.v1` | Recognised Stripe balance table and payout evidence. |
| Razorpay settlement | `razorpay_settlement.v1` | Recognised settlement table with settlement arithmetic. |
| PayPal activity | `paypal_activity.v1` | Public export layout, exercised on synthetic examples. |
| Wise statement | `wise_statement.v1` | Public export layout, exercised on synthetic examples. |
| Form 26AS | `tds_26as.v1` | Recognised Part A TDS table and proof checks. |
| AIS | `ais.v1` | Recognised statement layout. |
| FIRA | `fira.v1` | Recognised remittance advice table. |
| Form 1099-B | `form_1099b.v1` | Public export layout, exercised on synthetic examples. Other 1099 forms have no provider. |
| Trial balance | `trial_balance.v1` | Recognised debit and credit ledger table. |
| Excel workpaper | The matching table's layout ID | `.xlsx` with exactly one matching sheet. Formula-only evidence is insufficient. |
## Input limits [#input-limits]
- Maximum file size is 20 MiB in the engine. A hosting proxy may impose a smaller request limit.
- Keep one supported source document per file. A workbook with multiple matching sheets is ambiguous.
- Supply `dmy` or `mdy` when date order is known but the dates are ambiguous. The bank CSV parser defaults to day-first where it cannot infer order. PayPal and Form 1099-B can require an explicit order.
- Inspect live engine capabilities through [`GET /v1/health` and `GET /v1/formats`](/docs/engine-api) when using the service.
## Check a new export [#check-a-new-export]
1. Match the document and provider to a row in the matrix. For example, start with a balance export for Stripe.
2. Preserve the original headers, amounts, and totals. For Excel, check that the workbook contains one table that matches a supported layout.
3. Run one representative file with verified context. Read `file.layout_version` on release. For a refusal, use the code and message to decide whether to change the export or the run options.
4. Test a range of statement periods and layout variations before scheduling a recurring import, especially for layouts exercised only on synthetic data.
`UNKNOWN_LAYOUT` indicates that no available provider recognized the input. `PARSE_ERROR` can occur after a layout is recognized if required fields are missing or ambiguous. See [refusal handling](/docs/refusals) for recovery.
---
# Open Books Developer Documentation
Turn financial files into verified JSON with Open Books. Start with a sample, then integrate through the CLI, Python, Node.js, HTTP, or MCP.
Source: https://openbooks.lumeo.co.in/docs
Open Books reads bank statements, payment settlements, tax documents, and Excel workpapers. For each file, it returns a complete `openbooks.v1` document with verification checks and source evidence, or a typed refusal that explains why the file could not be released.
Start with a two-row bank CSV. Fix a missing opening balance and trace the result back to the source.
Use synthetic samples to learn how to run a batch, inspect its checks, and download a result.
Set up the Python engine, install the npm packages if needed, and verify your installation.
Learn how to branch on status, preserve exact amounts, and keep an audit trail.
## Build and test an integration [#build-and-test-an-integration]
Once you've run the sample, [build a bank statement importer](/docs/build-an-importer) that saves each decision and computes exact debit and credit totals. Then [test your integration](/docs/test-an-integration) with bundled bank, PDF, settlement, and tax fixtures. The test guide covers invalid inputs, interrupted runs, retries, and what a reviewer should be able to trace.
## How a file becomes verified JSON [#how-a-file-becomes-verified-json]
1. **Detect the layout.** Open Books identifies a table or file structure it knows how to read. Two CSV files can have different layouts even when they use the same extension.
2. **Extract and normalize records.** The engine reads values such as dates, debits, credits, and balances into a consistent schema. It records the source text and its location when available.
3. **Verify against the source.** For a bank statement, the engine can check that opening balance plus credits minus debits equals the closing balance. At least one check must use independent evidence from the document, such as a printed closing balance.
4. **Return a decision.** A release has `status: "ok"` and includes records, assertions, and evidence. A refusal has `status: "refused"`, `data: null`, and a code you can act on. Read the status before importing records.
## Choose an integration [#choose-an-integration]
| Where you work | Start here | Use it for |
| --- | --- | --- |
| Browser | [Workspace](/docs/workspace) | Explore synthetic samples and review a batch by hand. |
| Terminal | [CLI reference](/docs/cli) | Run local files, save JSON, and script jobs with exit codes. |
| Python 3.11+ | [Python API](/docs/python) | Call the engine inside a Python process and pass context per file. |
| Node.js 20+ | [Node.js and TypeScript](/docs/node) | Invoke the local Python engine and handle typed results. |
| Application server | [Self-hosted HTTP API](/docs/engine-api) | Send uploads to a private engine and track per-file decisions in a stream. |
| AI agent | [Model Context Protocol](/docs/mcp) | Run supported operations from an MCP client and retrieve parts of the proof. |
## Find a guide for your files [#find-a-guide-for-your-files]
| Your input | What the guide covers |
| --- | --- |
| Bank CSV, OFX, QFX, or MT940 | [Bank statements](/docs/bank-statements) explains opening balances, date order, and signed movements. |
| Stripe or Razorpay export | [Payment settlements](/docs/payment-settlements) covers fee checks, payout totals, and matching bank credits. |
| Tax export or spreadsheet | [Tax documents and workpapers](/docs/tax-and-workpapers) covers supported tables, workbook preparation, and source totals. |
| Bank PDF or image | [PDFs and OCR](/docs/pdf-and-ocr) explains text extraction, scan setup, and page evidence. |
Check the [format matrix](/docs/formats) before integrating a new export. Open Books uses synthetic documents for training and evaluation. Test representative exports and the refusal path before scheduling imports. See [troubleshooting](/docs/troubleshooting) when setup or processing fails.
The docs are also available as a [Markdown index](/llms.txt) and a [complete Markdown export](/llms-full.txt).
---
# Install Open Books
Install the Open Books engine and npm wrappers, add OCR and model support, and verify engine discovery in your environment.
Source: https://openbooks.lumeo.co.in/docs/installation
## 1. Check your prerequisites [#1-check-your-prerequisites]
Open Books runs on Python 3.11 or newer. The npm packages also need Node.js 20 or newer. Open a terminal in your project directory and check the runtime you plan to use.
~~~bash
python --version
node --version
npm --version
~~~
The last two checks apply to Node.js and the npm CLI. If your system uses `python3` for Python 3, use that command to create the environment below. To try a sample without a local installation, start with the [browser quickstart](/docs/quickstart).
## 2. Create and activate a virtual environment [#2-create-and-activate-a-virtual-environment]
A virtual environment keeps the engine and its dependencies together for one project. Run `python -m venv .venv` once. In each new terminal, activate it with the command for your shell.
~~~bash
source .venv/bin/activate
~~~
~~~powershell
.\.venv\Scripts\Activate.ps1
~~~
If shell policy blocks activation, call the environment's Python directly. On Windows, use `.\.venv\Scripts\python.exe`. On macOS and Linux, use `./.venv/bin/python`.
## 3. Install for your runtime [#3-install-for-your-runtime]
Install the Python distribution for both the importable API and the Python CLI.
~~~bash
python -m pip install "openbooks==0.2.0"
~~~
Install the engine into the activated environment and the Node.js wrapper into your npm project. If the project has no `package.json`, run `npm init -y` first.
~~~bash
python -m pip install "openbooks==0.2.0"
npm install @lumeo_hq/openbooks-core
~~~
Use an explicit interpreter path through `OPENBOOKS_PYTHON` in CI when the runner has more than one Python installation.
The npm CLI can install the Python engine with scan and model support through its install hook. For a global command:
~~~bash
npm install -g @lumeo_hq/openbooks
~~~
For a project-local command, run `npm install @lumeo_hq/openbooks` and invoke it with `npx openbooks`. If the install hook was skipped, run `openbooks install-engine --scan` (or prefix the command with `npx` for the local install) with your virtual environment active.
## 4. Verify engine discovery [#4-verify-engine-discovery]
Run `python -m openbooks engine-info` and look for `schema_version: "openbooks.v1"` in the JSON. The `layouts` list shows the installed layout providers. Run `python -m openbooks doctor` for a readable diagnostic report. If you installed the npm CLI, `openbooks engine-info` should also find the engine. Check [installation troubleshooting](/docs/troubleshooting#check-the-installation) if it finds a different one.
## Add scan and model support [#add-scan-and-model-support]
The base Python dependency set handles structured files and text-layer PDFs. Install the `scan` extra for image OCR and the local typed-head model. It adds EasyOCR and PyTorch, so allocate more disk and installation time.
~~~bash
python -m pip install "openbooks[scan]==0.2.0"
python -m openbooks doctor --deep
~~~
See [PDF and OCR](/docs/pdf-and-ocr) for flag defaults. The Node.js wrapper enables model cross-checking for PDF and image runs by default.
## Package map [#package-map]
| Distribution | Purpose |
| --- | --- |
| [`openbooks` on PyPI](https://pypi.org/project/openbooks/) | Python engine, provider registry, Python API and CLI. |
| [`@lumeo_hq/openbooks-core`](https://www.npmjs.com/package/@lumeo_hq/openbooks-core) | Typed runner, engine discovery and output validation. |
| [`@lumeo_hq/openbooks-statements`](https://www.npmjs.com/package/@lumeo_hq/openbooks-statements) | Runner restricted to bank statement layouts. |
| [`@lumeo_hq/openbooks-gateways`](https://www.npmjs.com/package/@lumeo_hq/openbooks-gateways) | Runner restricted to payment gateway layouts. |
| [`@lumeo_hq/openbooks-tax`](https://www.npmjs.com/package/@lumeo_hq/openbooks-tax) | Runner restricted to tax and trial-balance layouts. |
| [`@lumeo_hq/openbooks-doctor`](https://www.npmjs.com/package/@lumeo_hq/openbooks-doctor) | Programmatic diagnostics for Node.js. |
| [`@lumeo_hq/openbooks`](https://www.npmjs.com/package/@lumeo_hq/openbooks) | Unified npm CLI and Python installer. |
If you're upgrading Python from 0.1, install 0.2 in a fresh virtual environment. The `openbooks` distribution now owns all five Python modules. Existing code can still import `Params` and `process` from `openbooks.pipeline`, and new code can import them from `openbooks`.
Run the [bank CSV quickstart](/docs/quickstart) to confirm your environment can process a file.
---
# MCP for AI agents
Download and install the Open Books Model Context Protocol server to verify financial files with an AI agent and inspect the evidence in one batched call.
Source: https://openbooks.lumeo.co.in/docs/mcp
Model Context Protocol (MCP) lets an AI client call tools supplied by another program. The Open Books MCP server lets a compatible client run the Python engine and retrieve decisions, records, and proof for financial files. Choose the setup path that matches what you want to do.
| Goal | Start here |
| --- | --- |
| Verify that your client can connect | Use the connection test below. |
| Process files from a folder you control | Install the local server and connect over stdio, where the client starts the server as a subprocess. |
| Send uploads to a private shared server | Use Streamable HTTP with a bearer token. |
## Test your client's connection [#test-your-clients-connection]
1. Add the setup server shown below to your client.
2. Copy the generated prompt and paste it into the agent. The agent calls `confirm_connection` with the setup code.
3. Watch for confirmation on this page. If the code expires after ten minutes, generate a fresh code.
The setup endpoint confirms connectivity. Install the full server to process financial files.
## 1. Install the local server [#1-install-the-local-server]
[Download the Open Books MCP wheel](/downloads/openbooks_mcp-0.1.0-py3-none-any.whl) · [SHA-256 checksum](/downloads/openbooks_mcp-0.1.0-py3-none-any.whl.sha256)
Use Python 3.11 or newer. Create a virtual environment and install the downloaded wheel, or use the release URL in the command below. A wheel is a packaged Python distribution.
~~~bash
python -m venv .openbooks-mcp
# macOS and Linux
source .openbooks-mcp/bin/activate
# PowerShell uses: .\.openbooks-mcp\Scripts\Activate.ps1
python -m pip install https://openbooks.lumeo.co.in/downloads/openbooks_mcp-0.1.0-py3-none-any.whl
python -m openbooks_mcp --version
~~~
The version command should print the installed server version. For [scans or model checks](/docs/pdf-and-ocr), install the optional extras into the same environment.
~~~bash
python -m pip install "openbooks-mcp[scan] @ https://openbooks.lumeo.co.in/downloads/openbooks_mcp-0.1.0-py3-none-any.whl"
~~~
## 2. Connect an MCP client [#2-connect-an-mcp-client]
Create a dedicated directory for inputs and put a synthetic file there for your first run. For clients that use an `mcpServers` configuration, replace both absolute paths in the following example. Point `command` to the virtual environment's Python and `--root` to your existing input folder. On Windows, the interpreter is under `Scripts/python.exe`. You can use forward slashes in JSON paths, for example `C:/Projects/.openbooks-mcp/Scripts/python.exe`.
~~~json
{
"mcpServers": {
"openbooks": {
"command": "/absolute/path/.openbooks-mcp/bin/python",
"args": ["-m", "openbooks_mcp", "--root", "/absolute/path/financial-inbox"]
}
}
}
~~~
For Claude Code, register the same launch command.
~~~bash
claude mcp add openbooks -- /absolute/path/.openbooks-mcp/bin/python -m openbooks_mcp --root /absolute/path/financial-inbox
~~~
Restart the MCP client and check that it lists `search` and `execute`. Start with the synthetic sample. Omit `--root` to use just samples and uploaded bytes. The MCP client may send tool responses to its model provider. Check your client's data settings before exposing financial records.
## 3. Discover and run operations [#3-discover-and-run-operations]
`search` returns operation names and descriptions for a keyword. For example, send `{"query":"sample","details":true}` to get the operation and its argument schema. Then pass named steps to `execute`. A step that retrieves records points to a preceding processing step by ID. This follows a discovery-and-execution pattern. [Cloudflare Code Mode](https://blog.cloudflare.com/code-mode-mcp/)
| Operation | What it returns |
| --- | --- |
| `formats` | Installed layouts, supported extensions, engine contract and file limits. |
| `process_sample` | Release or refusal summary for a synthetic bank CSV. |
| `process_file` | A decision for a path relative to the approved local folder. Available with `--root` over stdio. |
| `process_upload` | A decision for up to 1 MiB of standard base64 file bytes. |
| `records` | A page of the specified collection from an earlier successful processing step. |
| `document` | The entire release or refusal document from an earlier processing step, subject to the response limit. |
### Process and inspect a statement in one call [#process-and-inspect-a-statement-in-one-call]
Send these arguments to `execute`. It processes two versions of the sample and reads the released batch balance and verification assertions in the same call.
~~~json
{
"steps": [
{ "id": "missing", "operation": "process_sample" },
{ "id": "statement", "operation": "process_sample", "arguments": { "opening": "1000.00" } },
{ "id": "balance", "operation": "records", "arguments": { "from_step": "statement", "collection": "batches" } },
{ "id": "checks", "operation": "records", "arguments": { "from_step": "statement", "collection": "assertions" } }
]
}
~~~
The first outcome is a `PARSE_ERROR` refusal. The second releases two transactions and the balance record shows a `950.00` INR closing amount. Each successful processing operation starts with a compact summary. Use `records` with `offset` and `limit` to retrieve only the needed items. For evidence, use `prefix` to match a record ID such as `txn-00001.`.
### Process a local export [#process-a-local-export]
~~~json
{
"steps": [
{
"id": "bank",
"operation": "process_file",
"arguments": { "path": "january.csv", "currency": "INR", "opening": "1000.00", "date_order": "dmy" }
},
{
"id": "rows",
"operation": "records",
"arguments": { "from_step": "bank", "collection": "transactions", "limit": 5 }
}
]
}
~~~
One batch accepts up to eight uniquely named steps. Documents referenced by `from_step` are held for the current batch. Results retain the engine's exact decimal strings. A document refusal appears inside a result. An operation error such as `INVALID_PATH` or `RESPONSE_LIMIT` appears as an error on the affected step. HTTP uses a 2 MiB request limit and batched output is bounded to 48 KiB.
## Troubleshoot a connection or tool call [#troubleshoot-a-connection-or-tool-call]
| Symptom | Check |
| --- | --- |
| The client cannot start the server | Run the configured interpreter with `-m openbooks_mcp --version` and verify that the client config points to that interpreter. |
| The client lists tools but `process_file` is missing | Use stdio with an existing directory passed to `--root`. |
| `INVALID_PATH` | Pass a path relative to the approved folder, such as `january.csv`. |
| `RESPONSE_LIMIT` | Use `records` with a smaller `limit` instead of retrieving the entire document. |
| The document returns `PARSE_ERROR` | Read the document's message and follow the [refusal guide](/docs/refusals). |
## Private HTTP transport [#private-http-transport]
Use Streamable HTTP for an organisation-managed service. Run it with `OPENBOOKS_MCP_TOKEN` set to a high-entropy secret. It listens on loopback, requires that token as an `Authorization: Bearer …` header, and supports in-memory uploads and the synthetic sample. Connect using a private SSH tunnel or an authenticated TLS gateway managed by your organisation.
~~~bash
python -m openbooks_mcp --transport streamable-http
ssh -N -L 8791:127.0.0.1:8791 developer@your-vps
~~~
Configure the MCP client for Streamable HTTP at `http://127.0.0.1:8791/mcp` and supply the bearer token via its secret store. The base installation handles structured files and text-layer PDFs. The local engine's `scan` extra adds the OCR and model runtime on deployments where those resources are available.
---
# 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.
---
# Node.js and TypeScript
Run the local Python engine from Node.js, integrate typed results and handle refusals separately from execution errors.
Source: https://openbooks.lumeo.co.in/docs/node
Use these packages in a Node.js process with Python 3.11+ and `openbooks` installed. The wrapper starts a child process on the same machine, checks schema compatibility, and validates the result. Keep calls in your application server or job runner.
## Set up your first run [#set-up-your-first-run]
1. Follow the [Node.js installation steps](/docs/installation) to install the wrapper and Python engine.
2. Run `python -m openbooks engine-info` in the same project environment. If the Node.js process uses a different environment, set `OPENBOOKS_PYTHON` to the absolute path of the interpreter that reported the engine.
3. Work through the [Node.js quickstart](/docs/quickstart) with the sample before adding multiple files.
## Process a batch [#process-a-batch]
This example uses two CSV files with the same verified opening amount, currency, and date order. Save it as an `.mjs` file to run it with Node.js, or use it in a TypeScript project.
~~~ts
import { EngineError, isReleased, runFiles } from "@lumeo_hq/openbooks-core";
try {
const results = await runFiles(["january.csv", "february.csv"], {
currency: "INR",
dateOrder: "dmy",
opening: "1000.00",
runTimeoutMs: 120_000,
});
for (const result of results) {
if (isReleased(result)) {
console.log(result.file, result.document.data.transactions.length);
} else {
console.warn(result.file, result.code, result.message);
}
}
} catch (error) {
if (!(error instanceof EngineError)) throw error;
console.error(error.kind, error.message, error.hint);
process.exitCode = 1;
}
~~~
Batch options apply to every file in the call. Results arrive as an array in input order, with one result per input when the batch completes. Use `runFile()` for individual settings, or use the job stream below for many files with different options.
## Stream jobs with per-file options [#stream-jobs-with-per-file-options]
The core package and format wrappers expose `runJobs()` from version 0.2.1. Pass an iterable or async iterable of jobs and handle each result as it arrives in input order. This lets you persist or review each result without holding an entire completed batch in memory. Runtime settings such as the interpreter, layout allowlist, and response limits apply across the stream.
Install `@lumeo_hq/openbooks-statements` for this example. Shared options set the currency and date order. Each job supplies its own opening balance.
~~~ts
import { runJobs } from "@lumeo_hq/openbooks-statements";
for await (const result of runJobs([
{ file: "jan.csv", options: { opening: "1000.00" } },
{ file: "feb.csv", options: { opening: "1590.12" } },
], { currency: "INR", dateOrder: "dmy", maxDocumentBytes: 64 * 1024 * 1024 })) {
console.log(result.file, result.kind);
}
~~~
## RunOptions [#runoptions]
| Options | Behavior |
| --- | --- |
| `currency`, `opening`, `account` | Context for the parser. Pass `opening` as a plain decimal string. |
| `dateOrder`, `allowDerivedOpening` | Set numeric date order or permit a derived opening where supported. |
| `ocr`, `model` | Enabled by default for document processing. Set `model: false` for text-layer PDF use with the base engine. |
| `python` | Overrides the interpreter path. Otherwise discovery checks `OPENBOOKS_PYTHON`, a project `.venv`, then supported system Python candidates. |
| `runTimeoutMs`, `signal`, `maxOutputBytes` | Bound runtime and process output and support cancellation. The run timeout defaults to 120,000 ms. |
| `maxDocumentBytes` | Bounds the size of a serialized proof document separately from subprocess logs. Defaults to 64 MiB. |
| `accept` | Layout ID allowlist. A withheld release is returned as `UNKNOWN_LAYOUT` with `restricted: true`. |
## Pick the wrapper [#pick-the-wrapper]
| Package | Exports and scope |
| --- | --- |
| `@lumeo_hq/openbooks-core` | `runFile`, `runFiles`, `isReleased`, `findEngine`, validation helpers and contract types. Supports the engine's installed layouts. |
| `@lumeo_hq/openbooks-statements` | The runner and `LAYOUTS` for bank CSV, OFX/QFX, MT940 and bank statement PDFs/scans. |
| `@lumeo_hq/openbooks-gateways` | The runner and `LAYOUTS` for Stripe, Razorpay, PayPal and Wise. |
| `@lumeo_hq/openbooks-tax` | The runner and `LAYOUTS` for Form 26AS, AIS, FIRA, Form 1099-B and trial balance. |
| `@lumeo_hq/openbooks-doctor` | `runDoctor(options)` returns checks, summary counts and `ok`. Set `deep: true` to load the model. |
| `@lumeo_hq/openbooks` | CLI, engine installer and programmatic `main` and `installEngine` entry points. |
## Handle results and errors [#handle-results-and-errors]
| What you receive | How to handle it |
| --- | --- |
| Result with `kind: "released"` | Use `isReleased()` to narrow the TypeScript type, then read `result.document` for records and proof. |
| Result with `kind: "refused"` | Use `code` and `message` for review. `restricted` indicates an allowlist decision and `internal` flags an unexpected engine problem. Keep the refusal document when present. |
| Thrown `EngineError` | Use `kind` and `hint` to decide whether to retry or repair the environment. Examples include `engine_not_installed`, `engine_version`, `timeout`, `aborted`, and `bad_output`. |
See [refusal handling](/docs/refusals) for source-file problems and [troubleshooting](/docs/troubleshooting) for engine discovery, version, and runtime errors.
---
# JSON output contract
Integrate the openbooks.v1 release and refusal contract with exact decimal money, source evidence and verification assertions.
Source: https://openbooks.lumeo.co.in/docs/output-contract
Every completed document decision uses the `openbooks.v1` JSON schema. The CLI, Python, Node.js, and HTTP API expose the same underlying document. Some entry points wrap it in a result or event, so unwrap it before applying the contract below.
## Read the envelope first [#read-the-envelope-first]
1. Check `schema_version` against the version your integration supports.
2. For `status: "ok"`, read the released records under `data` and retain their assertions and source evidence.
3. For `status: "refused"`, read `error.code` and `error.message`. The document has `data: null`.
4. Handle missing decisions, such as a timeout or interrupted stream, at the job level. See [refusal and execution handling](/docs/refusals).
## Released documents [#released-documents]
| Field | Contents |
| --- | --- |
| `status` | `"ok"` |
| `file` | Input name and SHA-256, detected format, layout version and extraction method. A model-checked release also identifies the weights and calibration by SHA-256. |
| `data` | `accounts`, `parties`, `batches`, `transactions` and `claims`. Collections can be empty and fields vary with the layout. |
| `evidence` | Source locations and raw text indexed by record and field. |
| `assertions` | Statement, settlement or layout-specific checks. All must pass with at least one independent check. |
This transaction is from the [sample terminal](/docs/quickstart).
~~~json
{
"id": "txn-00001",
"batch_id": "batch-1",
"account_id": "acct-1",
"date": "2026-01-02",
"direction": "debit",
"amount": { "amount": "100.00", "currency": "INR" },
"balance_after": { "amount": "900.00", "currency": "INR" },
"description": "Sample payment",
"reference": null
}
~~~
Retain money as decimal strings, and use a decimal library for arithmetic. Carry the currency alongside the amount. Date fields are ISO calendar dates where the layout supplies a date. Scope record IDs to their source document when combining files.
## Evidence and independent checks [#evidence-and-independent-checks]
Use the record ID and field name to find the source. In the quickstart, `evidence["txn-00001.amount"]` gives the first transaction's amount as it appeared on row 2 of the CSV.
~~~json
{
"page": null,
"bbox": null,
"row": 2,
"raw_text": "100.00",
"method": "parser"
}
~~~
`page`, `bbox`, and `row` describe where to look and can be null when a location is unavailable or inapplicable. `raw_text` preserves the source reading or records that a value was supplied by the caller. `method` records how the field was extracted.
Each assertion reports `id`, `rule`, `expected`, `computed`, `passed`, and `independent`. The quickstart's closing-balance assertion compares an expected `"950.00 INR"` from the source against the same amount computed from the opening balance and transactions. It passes and is independent because the expected closing amount comes from the CSV.
## Refused documents [#refused-documents]
~~~json
{
"schema_version": "openbooks.v1",
"status": "refused",
"data": null,
"error": {
"code": "PARSE_ERROR",
"message": "statement has no stated opening balance; supply --opening",
"file_sha256": "4cbb7e3f45dc4860ba6c14e51b32a2667fbb526b4f6f78e7861bc3d6b4f1f997"
}
}
~~~
Read `error.code` for programmatic handling and `error.message` during review. The refusal hash is `error.file_sha256`. In a release, it is `file.sha256`. Both identify the exact input bytes. Store processing parameters and versions when the same bytes may be run with different settings.
## Validate documents at the integration boundary [#validate-documents-at-the-integration-boundary]
Use the [release schema](/schema/openbooks.v1.schema.json) or [refusal schema](/schema/openbooks.v1.refusal.schema.json) according to the document status. Both are included in the Python package and mirrored by the Node.js validation helpers. When retaining normalized records, store the original decision with enough context to find its assertions and evidence later. See the [Python API](/docs/python#validate-stored-output) for a validation example.
---
# Payment settlements
Check gateway settlement arithmetic and payout totals with Open Books, then reconcile released amounts against bank credits.
Source: https://openbooks.lumeo.co.in/docs/payment-settlements
Payment providers collect money, deduct fees, and send payouts to a bank account. A settlement export explains how the provider arrived at a payout. Open Books checks the arithmetic within the export. Matching that payout to the receiving bank statement is a second step.
## 1. Export the settlement detail [#1-export-the-settlement-detail]
Choose the provider's balance or settlement report for the payout you want to verify. Keep the original headers, transaction identifiers, fee columns, and payout totals. See the [format matrix](/docs/formats) for recognized Stripe, Razorpay, PayPal, and Wise layouts.
## 2. Process the export [#2-process-the-export]
This Node.js example uses a Razorpay CSV in INR. Follow the [Node.js setup](/docs/installation), then install the gateway wrapper with `npm install @lumeo_hq/openbooks-gateways`.
~~~ts
import { runFile } from "@lumeo_hq/openbooks-gateways";
const result = await runFile("razorpay-settlement.csv", { currency: "INR" });
if (result.kind === "released") {
console.log(result.document.data.batches);
console.log(result.document.assertions);
} else {
console.error(result.code, result.message);
}
~~~
Save the example as an `.mjs` file and run it from the directory containing the export. For Python, pass the same file to [`process()`](/docs/python). The gateway wrapper accepts the layouts listed in its `LAYOUTS` export.
## 3. Review the settlement checks [#3-review-the-settlement-checks]
For a simple fee-bearing row, a gross payment of INR `100.00` minus INR `2.00` in fees and INR `0.36` in tax gives a net amount of INR `97.64`. Read `assertions` to see the checks for your layout and compare their expected and computed values. Read `data.batches` for batch amounts and use `evidence` to locate the source values. For a refusal, start with [the refusal code and message](/docs/refusals).
Try **Razorpay settlement** and **Stripe export, payout off by 0.01** in the [workspace](/app). The Razorpay fixture passes the row arithmetic and payout checks. The Stripe fixture refuses because the source payout is USD `125.06` and the engine computes USD `125.05` from the rows. That message tells you which amounts to trace in the export.
## 4. Match the payout to a bank credit [#4-match-the-payout-to-a-bank-credit]
1. Process the receiving account's [bank statement](/docs/bank-statements) and keep both released documents.
2. Look for a credit with the same currency and exact decimal amount. Compare payout and credit dates within the window that applies to your provider. A payout initiated on Monday can appear on a later bank date.
3. Compare references when available. If two credits have the same amount or no candidate fits, keep the payout open for review.
Open Books' optional source-checkout linker applies exact amounts, same currency and a date window. It can report ties and grouped payouts. Check `link_available` in engine health before using [`POST /v1/link`](/docs/engine-api).
PayPal activity and Wise statement layouts follow publicly documented export formats and have been exercised on synthetic files. Verify representative exports before scheduling imports.
---
# Bank PDFs and OCR
Process text-layer PDFs and scanned bank statements, choose OCR and model settings, and inspect bounding-box evidence.
Source: https://openbooks.lumeo.co.in/docs/pdf-and-ocr
PDFs can include a text layer or contain only images of each page. Optical character recognition (OCR) reads text from those images. Open Books uses the words and their positions to reconstruct statement rows, then applies the same financial checks as for structured bank exports.
## 1. Identify your input [#1-identify-your-input]
Open the original PDF and try selecting an amount and its column heading. Selectable text suggests a text layer. An image-only PDF or a standalone PNG or JPEG needs OCR. Text extracted from a PDF still needs to match a supported statement layout.
| File | Requirements |
| --- | --- |
| Text-layer bank statement PDF | Base Python install and a recognised statement layout. |
| Scanned PDF, PNG or JPEG | `openbooks[scan]` and working EasyOCR weights. |
| Model cross-check | `openbooks[scan]` and the matching shipped weights and calibration. |
## 2. Run the statement [#2-run-the-statement]
Run the command from the directory containing `statement.pdf`. Supply the currency and date order only when they match the source. If the statement omits its opening balance, add the verified value as you would for a [bank export](/docs/bank-statements).
~~~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
~~~
OCR is enabled by default. For a selectable-text PDF with the base engine, run the same command without `--model` and add `--no-ocr` to restrict extraction to the text layer. Pass `--model` when you want an additional check of the detected roles and values.
Complete the [Node.js setup](/docs/installation) and run `npm install @lumeo_hq/openbooks-statements`. Save the following as an `.mjs` file next to the PDF.
~~~ts
import { runFile } from "@lumeo_hq/openbooks-statements";
const result = await runFile("statement.pdf", {
currency: "INR",
dateOrder: "dmy",
ocr: false,
model: false,
});
if (result.kind === "released") {
console.log(result.document.assertions);
} else {
console.error(result.code, result.message);
}
~~~
This example processes a text-layer PDF with the base Python install. For scans, install the `scan` extra and enable OCR. The npm wrapper normally enables both OCR and model cross-checking for documents.
## 3. Inspect source evidence [#3-inspect-source-evidence]
When present, `page` is one-based and `bbox` contains top-left and bottom-right coordinates in the page coordinate space used for that evidence. Read `raw_text` alongside the normalised value. Evidence fields can be null when the source has no equivalent location. Role-inspection token boxes use coordinates normalised to the page.
For a released transaction, look up its amount in `evidence`, open the reported page, and compare the source text and surrounding column with the normalized value. Review the assertion for the relevant running balance or closing balance.
To see an example, run **Bank statement PDF** in the [workspace](/app). In **Checks**, find the comparison between the document-stated closing balance and the last running balance. In **Evidence**, select a transaction and compare an amount with its page and bounding box.
## Recover from an unreadable result [#recover-from-an-unreadable-result]
1. Check that all pages are present, correctly oriented, and legible. Request a text-layer export if the bank offers one.
2. For an image-only file, confirm that OCR is enabled and that [installation diagnostics](/docs/troubleshooting#check-the-installation) can find the scan dependencies.
3. Compare the [refusal reason](/docs/refusals) with the source. A balance mismatch calls for checking the source rows and totals. For a model-related refusal, use [the model guide](/docs/model) to check the local weights and calibration.
---
# Python API
Use process, Params and the schema helpers in Python for bank statements, settlements, tax documents and workpapers.
Source: https://openbooks.lumeo.co.in/docs/python
Use the Python API to process files inside a Python program. Install `openbooks` into the same Python 3.11+ environment that runs your application. The public API is available from `openbooks` and `openbooks.core`. See [installation](/docs/installation) if you need to set up a virtual environment.
## Process a file [#process-a-file]
1. [Download the sample CSV](/examples/statement.csv) and put it beside your Python script.
2. Set up `Params` with verified context for the input. Use `Decimal("1000.00")` to preserve the exact opening amount.
3. Run the script from that directory. `process(path, params)` accepts a path or a path string and returns an `openbooks.v1` dictionary for a completed decision.
~~~python
from decimal import Decimal
from pathlib import Path
from openbooks import EngineFault, Params, process
params = Params(
currency="INR",
opening=Decimal("1000.00"),
date_order="dmy",
)
try:
document = process(Path("statement.csv"), params, strict=True)
except EngineFault as error:
raise RuntimeError("Open Books could not run") from error
if document["status"] == "refused":
print(document["error"]["code"], document["error"]["message"])
else:
for row in document["data"]["transactions"]:
amount = Decimal(row["amount"]["amount"])
print(row["date"], row["direction"], amount, row["amount"]["currency"])
~~~
The sample prints a debit of INR `100.00` and a credit of INR `50.00`. Remove `opening` from `Params` and rerun to see the sample's `PARSE_ERROR` refusal.
## Handle execution failures [#handle-execution-failures]
Use `strict=True` when running jobs that need to distinguish an engine fault from a file that failed verification. An `EngineFault` can propagate for environmental problems. At the job boundary, handle file access errors as well. With the default policy, some unexpected failures return a refusal marked `error.internal`. Send those for engine diagnosis.
## Params [#params]
| Field | Type and default | Use |
| --- | --- | --- |
| `currency` | `str or None`, `None` | Three-letter currency when the layout needs a supplied currency. |
| `opening` | `Decimal or None`, `None` | Authoritative opening amount for layouts that accept it. |
| `account` | `str or None`, `None` | Caller-provided account identifier where supported. |
| `allow_derived_opening` | `bool`, `False` | Allow an opening balance derived from source rows where supported. |
| `date_order` | `str or None`, `None` | `dmy` or `mdy` for numeric dates. Omit to use layout inference and defaults. |
| `ocr` | `bool`, `True` | Allow OCR when the document front end needs it. |
| `model` | `bool`, `False` | Request the optional typed-head check on PDFs or scans. |
## Validate stored output [#validate-stored-output]
Check `schema_version` before reading a document received from another process. `validate_output()` checks a release's schema and additional rules for evidence, references, and assertions. Use `load_schema("refusal")` for the refusal variant.
~~~python
from jsonschema import validate
from openbooks import SCHEMA_VERSION, load_schema, validate_output
if document["schema_version"] != SCHEMA_VERSION:
raise ValueError("Unsupported Open Books schema")
if document["status"] == "ok":
validate_output(document)
elif document["status"] == "refused":
validate(document, load_schema("refusal"))
else:
raise ValueError("Unknown Open Books document status")
~~~
See [the output contract](/docs/output-contract) for the refusal schema and money, assertion and evidence fields. See [the architecture guide](/docs/architecture) for provider registration and extension points.
---
# Verify your first bank statement
Run a two-row bank CSV in the browser or locally, resolve a missing opening balance, and trace a released result back to its source.
Source: https://openbooks.lumeo.co.in/docs/quickstart
In this tutorial you’ll process a synthetic bank statement twice, resolve a missing opening balance, and use the released JSON to verify both transactions. The browser walkthrough requires no installation. For the local walkthrough, use Python 3.11 or newer and Node.js 20 or newer if you choose Node.js.
## 1. Read the sample [#1-read-the-sample]
The sample is a CSV, a plain-text file with comma-separated columns. The `Balance` column is the amount left in the account after each transaction.
| Date (day/month/year) | Movement | Amount (INR) | Balance after (INR) |
| --- | --- | ---: | ---: |
| 02/01/2026 | Debit | 100.00 | 900.00 |
| 03/01/2026 | Credit | 50.00 | 950.00 |
The sample omits its opening balance, the amount before the first row. For this exercise, the known opening balance is INR `1000.00`. For a real statement, get this value from the original statement or another authoritative source, such as the verified closing balance of the preceding statement for the same account.
## 2. Run in the browser [#2-run-in-the-browser]
1. Choose **Run without opening**. The engine returns `status: "refused"` and `error.code: "PARSE_ERROR"`. Look for the message asking for an opening balance.
2. Choose **Run with opening**. This sends the same CSV with `--opening 1000.00`. The engine now returns `status: "ok"`.
3. Scroll through the JSON output and find `data.transactions`, `assertions`, and `evidence`.
## 3. Repeat locally [#3-repeat-locally]
Download statement.csv into your project and open a terminal in that directory. Set up your environment using the [installation guide](/docs/installation) if you haven't installed Open Books before. The commands pass `INR` as the currency and `dmy` as the date order, so `02/01/2026` becomes `2026-01-02`.
~~~bash
python -m pip install "openbooks==0.2.0"
python -m openbooks run statement.csv --currency INR --date-order dmy --out refused
python -m openbooks run statement.csv --currency INR --date-order dmy --opening 1000.00 --out released
~~~
The first run exits `1` and writes a refusal under `refused/`. Run the two commands individually if your shell stops on nonzero exit codes. The corrected run exits `0` and writes the release under `released/`. Both files have the same SHA-256 filename because the input bytes are identical. Separate directories preserve both attempts.
Install `openbooks==0.2.0` with `python -m pip`. Save this as `quickstart.py` next to `statement.csv` and run `python quickstart.py`.
~~~python
from decimal import Decimal
from openbooks import Params, process
doc = process("statement.csv", Params(
currency="INR", date_order="dmy", opening=Decimal("1000.00"),
))
if doc["status"] == "ok":
for transaction in doc["data"]["transactions"]:
money = transaction["amount"]
print(transaction["date"], transaction["direction"], money["amount"], money["currency"])
else:
print(doc["error"]["code"], doc["error"]["message"])
~~~
The script prints `2026-01-02 debit 100.00 INR` and `2026-01-03 credit 50.00 INR`.
~~~bash
python -m pip install "openbooks==0.2.0"
npm install @lumeo_hq/openbooks-core
~~~
Save this as `quickstart.mjs` and run `node quickstart.mjs`.
~~~js
import { runFile } from "@lumeo_hq/openbooks-core";
const result = await runFile("statement.csv", {
currency: "INR",
dateOrder: "dmy",
opening: "1000.00",
});
if (result.kind === "released") {
console.log(result.document.data.transactions);
} else {
console.log(result.code, result.message);
}
~~~
## 4. Verify the result [#4-verify-the-result]
| Check | JSON field | Expected result |
| --- | --- | --- |
| Release decision | `status` | `"ok"` |
| Transaction directions | `data.transactions` | INR `100.00` debit, then INR `50.00` credit |
| Closing balance | `data.batches[0].closing.amount` | `"950.00"` |
| Reconciliation | `assertions` | Opening minus debit plus credit gives `950.00`. Each row's computed balance matches the CSV. |
| Source for the closing balance | `evidence["batch-1.closing"]` | `raw_text: "950.00"` at row 3, counting the CSV header as row 1 |
Next, [build a Python importer](/docs/build-an-importer) that saves the full decision and computes exact totals, or work through [bank statement exports](/docs/bank-statements) with a representative file.
---
# Refusals and execution errors
Find all six refusal codes, diagnose failed documents, and design retry and review behavior for reliable financial imports.
Source: https://openbooks.lumeo.co.in/docs/refusals
A refusal is a completed document decision with `status: "refused"`, `data: null`, and a machine-readable code. An execution failure interrupts the job before it can produce a decision for one or more inputs. In a batch, keep decisions already returned and track the remaining files as incomplete.
## Refusal codes [#refusal-codes]
| Code | Meaning | What to verify |
| --- | --- | --- |
| `UNKNOWN_LAYOUT` | No known layout matched, a required provider is missing, or a restricted npm runner withheld the layout. | Check the source export, the wrapper's `LAYOUTS` and the installed providers. |
| `UNSUPPORTED_INPUT` | Type, size, encoding or document structure falls outside supported inputs. | Verify the extension and size, whether the PDF is locked, and whether OCR is available. |
| `PARSE_ERROR` | The engine could not read or interpret a required field. | Check the opening balance, date order, currency and the field named in the message. Inspect `error.internal` for unexpected failures. |
| `BALANCE_MISMATCH` | A reconciliation assertion failed or there was insufficient independent evidence. | Compare printed running balances and totals against the original. Check for missing rows and truncated exports. |
| `LOW_CONFIDENCE` | The OCR or model-assisted reading could not be supported with enough confidence. | Review scan quality, orientation, column labels and source values. |
| `OUTPUT_INVALID` | The result failed contract validation or a required output check could not run. | Record the engine version and diagnose the provider or report a minimal synthetic reproduction. |
## Build a retry policy [#build-a-retry-policy]
1. **Record the outcome.** Save the input hash if available, the engine version, supplied parameters, and the refusal or execution error.
2. **Read the message.** A missing opening balance can be corrected with a verified source amount. A layout or reconciliation problem usually needs the document or its export reviewed. Send an `error.internal` refusal for engine diagnosis.
3. **Retry where appropriate.** Retry an interrupted file after checking the service. For a refusal, rerun when you can supply verified context or a corrected export.
4. **Review the new decision.** Keep both attempts in history and send only released records onward.
## Follow an example [#follow-an-example]
The [bank CSV quickstart](/docs/quickstart) returns `PARSE_ERROR` on the first run because the sample has no opening balance. Supplying its known opening balance of INR `1000.00` lets the engine check the two movements against the running balances. The result changes to a release. A wrong opening balance can still fail reconciliation.
## Find the outcome in your integration [#find-the-outcome-in-your-integration]
| Entry point | Where to look |
| --- | --- |
| [CLI](/docs/cli) | Read the exit code and inspect each written decision. |
| [Python](/docs/python) | Inspect the returned document and handle engine exceptions when using strict mode. |
| [Node.js](/docs/node) | Branch on `result.kind` and catch thrown `EngineError` values. |
| [HTTP API](/docs/engine-api) | Read each `file.done` decision and use `run.done` to confirm batch completion. |
| [MCP](/docs/mcp) | Read the document outcome and check each step for operation errors. |
---
# Tax documents and workpapers
Process Form 26AS, AIS, FIRA, Form 1099-B and trial balances, with source evidence and document-level reconciliation checks.
Source: https://openbooks.lumeo.co.in/docs/tax-and-workpapers
Start with an export from the source portal or system and verify the fields and totals the provider supports. Each layout supplies its own release checks, so review the assertions on each file.
## 1. Identify the input [#1-identify-the-input]
| Input | Review after a release |
| --- | --- |
| Form 26AS | Check the tax amounts and group totals against the source statement. |
| Annual Information Statement (AIS) | Review the source fields, reported values and any printed totals. |
| Foreign Inward Remittance Advice (FIRA) | Inspect the remittance amount, currency and references before matching to a bank credit. |
| Form 1099-B | Inspect proceeds, basis and dates. The layout is tested on synthetic data. |
| Trial balance or supported Excel workpaper | Inspect the totals and the selected sheet's evidence. |
## 2. Prepare a workbook [#2-prepare-a-workbook]
1. Keep one supported table in the workbook. If two sheets match known layouts, export the intended table to its own workbook.
2. Preserve the header row and printed totals. Use plain values for required fields. A total based only on a workbook formula is insufficient evidence.
3. For a trial balance, confirm that the debit and credit columns represent the same reporting period and currency. Keep the original workbook available during review.
## 3. Process the files [#3-process-the-files]
After following the [Node.js installation guide](/docs/installation), install the tax wrapper with `npm install @lumeo_hq/openbooks-tax`. Save this example as an `.mjs` file and run it from the directory containing the Form 26AS CSV and trial balance workbook.
~~~ts
import { runFiles } from "@lumeo_hq/openbooks-tax";
for (const result of await runFiles(["form-26as.csv", "trial-balance.xlsx"])) {
if (result.kind === "released") {
console.log(result.file, result.document.file.layout_version);
console.log(result.document.assertions);
} else {
console.error(result.file, result.code, result.message);
}
}
~~~
## 4. Review the records and proof [#4-review-the-records-and-proof]
Check the released layout ID and compare the applicable amounts in the table above with `assertions` and `evidence`. The [output contract](/docs/output-contract) describes the record collections and evidence fields. If the layout is unknown, compare the source headers with the [format matrix](/docs/formats). If an assertion fails, review the source totals and route the [refusal](/docs/refusals) for review.
Use the [workspace samples](/app) to practice these checks. For **Form 26AS (TDS)**, open **Checks** and look for the printed totals for tax deducted and tax deposited. For **Trial balance workbook**, review both the equality of debits and credits and each side's comparison with its printed total. In **Evidence**, locate the source used for a reported amount before carrying it into another system.
---
# Test a document integration
Verify release and refusal paths, use bundled fixtures for multiple layouts, and check retries and evidence before scheduling imports.
Source: https://openbooks.lumeo.co.in/docs/test-an-integration
A document integration needs to handle released files, files that fail verification, and jobs that stop before making a decision. Use known fixtures first so you can tell a plumbing problem from a source-data problem.
## 1. Establish a bank CSV baseline [#1-establish-a-bank-csv-baseline]
Install the [Python CLI](/docs/installation) and [download the two-row sample](/examples/statement.csv). Run each command individually from the directory with the sample. The last two commands return nonzero exit codes by design.
~~~bash
python -m openbooks run statement.csv --currency INR --date-order dmy --opening 1000.00 --out checks/release
python -m openbooks run statement.csv --currency INR --date-order dmy --out checks/missing-opening
python -m openbooks run statement.csv --currency INR --date-order dmy --opening 1200.00 --out checks/wrong-opening
~~~
| Case | Expected decision | Check in your application |
| --- | --- | --- |
| Verified opening | Exit `0`, `status: "ok"`, closing amount `"950.00"` | Exactly two transactions reach the import path. The full decision, including assertions and evidence, remains available. |
| Missing opening | Exit `1`, `PARSE_ERROR`, `data: null` | The file goes to review with the message explaining which parameter it needs. |
| Wrong opening | Exit `1`, `BALANCE_MISMATCH`, `data: null` | The file goes to review with the failed assertion in the message. |
Each output directory contains the decision under the same input hash. This makes it easy to check whether your job history ties all three attempts to the same source while preserving their different settings and outcomes.
## 2. Exercise the layouts you plan to use [#2-exercise-the-layouts-you-plan-to-use]
Open the [workspace sample picker](/app) or read the sample catalog from [`GET /v1/samples`](/docs/engine-api). For HTTP tests, use the catalog's `params` for each sample. Download the fixture bytes from `GET /v1/samples/{id}` and submit them through your integration.
| Sample | Catalog ID | Expected check |
| --- | --- | --- |
| Bank CSV with a tampered balance | `bad_bank_balance_break` | `BALANCE_MISMATCH` identifies the running-balance check. |
| MT940 statement | `ok_mt940` | The opening plus signed movements equals the source closing balance. |
| Bank statement PDF | `ok_pdf_text` | The stated closing balance equals the last running balance. |
| Razorpay settlement | `ok_razorpay` | Row arithmetic ties out and the net amounts match the payout. |
| Stripe export, payout off by 0.01 | `bad_stripe_payout` | `BALANCE_MISMATCH` identifies the payout total. |
| Form 26AS (TDS) | `ok_tds` | Deducted and deposited tax totals agree with the source. |
| Trial balance workbook | `ok_tb_xlsx` | Debits and credits balance and each side matches its printed total. |
The bundled documents are synthetic. Once these checks pass, test representative exports in an environment approved for those files. Include variations you expect to see, such as different date formats, statement periods, and PDF text or scan quality.
## 3. Test a stopped job and retry [#3-test-a-stopped-job-and-retry]
1. In a test environment, stop or interrupt a batch after at least one file completes. For HTTP, test a stream that delivers `file.done` for one index and closes before `run.done`.
2. Verify that your job records the finished decision and marks only files still waiting for a decision as incomplete.
3. Retry an incomplete file with its original settings. If the first attempt did finish on the server, your application should still write each set of released records at most once.
4. For a completed refusal, change the run only after obtaining verified context or a corrected source. Keep both decisions in the job history.
Use the [refusal guide](/docs/refusals) to route document and execution outcomes. For HTTP streaming behavior, see the [engine API](/docs/engine-api).
## 4. Check what a reviewer can trace [#4-check-what-a-reviewer-can-trace]
Pick a released amount and ask someone to find it from the saved JSON. They should be able to identify the input by hash, locate the relevant assertion, and trace the amount back to a row, page, or bounding box where the engine supplies one. Also check that the application preserves exact decimal strings and keeps each amount with its currency. See the [output contract](/docs/output-contract) for the full field definitions.
---
# Troubleshooting
Diagnose missing Python providers, mismatched engine versions, OCR and model setup, file refusals and interrupted streams.
Source: https://openbooks.lumeo.co.in/docs/troubleshooting
Start by finding the last completed step. If the command or wrapper cannot find the engine, check installation. If you received a JSON decision, read its `status` and message. If a batch stopped partway through, use the individual decisions to identify which files still need processing.
## Check the installation [#check-the-installation]
~~~bash
python --version
python -m openbooks engine-info
python -m openbooks doctor --json
~~~
Use Python 3.11 or newer and check that `engine-info` reports `openbooks.v1` and the expected layouts. Read the diagnostics JSON for the failing check and its message. If you installed the npm CLI, run `openbooks doctor` to check which engine Node.js discovers. Add `--deep` when you need to test model loading.
| Symptom | Action |
| --- | --- |
| Node.js reports `python_not_found` or `engine_not_installed` | Set `OPENBOOKS_PYTHON` to the interpreter in the environment where `python -m openbooks engine-info` works. |
| `engine_version` or schema mismatch | Compare the wrapper version and engine-info output, then reinstall compatible versions in the same job image. |
| Layout provider is missing from an editable checkout | Install with `python -m pip install -e packages/py/openbooks` to register it. Check `engine-info` again. |
To find the interpreter for your current environment, run `python -c "import sys; print(sys.executable)"`. Use that absolute path for `OPENBOOKS_PYTHON` when the Python command works and the Node.js wrapper is discovering a different installation.
## Diagnose a document run [#diagnose-a-document-run]
| Symptom | Action |
| --- | --- |
| Missing opening balance or ambiguous dates | Supply the authoritative opening balance or known date convention. Use the [sample run](/docs/quickstart) to test the same invocation on a known input. |
| Unknown layout | Compare the original export with the [format matrix](/docs/formats) and verify the installed provider. |
| Scan requires OCR or model files | Install the `scan` extra, make the OCR language assets available, and run `doctor --deep` for model setup. Check any model directory override. |
| npm asks for a model on a text-layer PDF | For a job using the base engine, set `model: false` in Node.js or pass `--no-model` to the npm CLI. |
| HTTP stream ends before `run.done` | Keep completed file decisions and mark missing ones interrupted. Check service logs, timeouts, and proxy buffering before retrying. |
If a known sample releases and your export refuses, use the [refusal code](/docs/refusals) to look for a layout, parameter, or evidence issue in the export.
## Report a reproducible issue [#report-a-reproducible-issue]
1. Record the package and engine versions, input type and expected layout, and the command or options.
2. Include the exact refusal or error code, the message, and the outcome you expected.
3. Reproduce with a synthetic file where possible. If you share an excerpt, redact account numbers and other identifying financial details.
---
# Use the browser workspace
Upload bank statements, tax documents and payment settlements, review the source checks, and export the verified JSON in Open Books.
Source: https://openbooks.lumeo.co.in/docs/workspace
[Open the workspace](/app) to process and review files in your browser. A batch groups files into one run. Each file still gets its own decision, so a refusal in one statement can appear alongside a release for another.
## 1. Run two sample statements [#1-run-two-sample-statements]
1. Open the sample picker and add **Bank statement CSV** and **Bank CSV without an opening balance**. The picker supplies the parameters configured for each fixture.
2. Run the batch. The first statement releases. The second refuses because it needs an opening balance.
3. Open the refused card. Enter `1000.00` in **Opening balance** and rerun that file. Use this amount for the sample. For real files, verify the opening balance against an authoritative source.
## 2. Inspect and export a release [#2-inspect-and-export-a-release]
1. On a released card, open **Data** to inspect the parsed records.
2. Open **Checks** and read the expected and computed amounts. An independent check uses a value from the input, such as a printed balance.
3. Open **Evidence** to locate the relevant source text, row, or page. For PDFs and images, the evidence can include a bounding box around the text.
4. Choose **Download JSON** to save the complete decision, including the records, checks, and evidence. See [the output contract](/docs/output-contract) for field definitions.
## 3. Run your own files [#3-run-your-own-files]
Check the [format matrix](/docs/formats), then attach the original exports. Open **Params** to supply verified currency, date order, or opening balance where required. Review each file's outcome:
| Outcome | What to do |
| --- | --- |
| Released | Inspect the records, checks, and evidence before exporting. |
| Refused | Read the code and message. If the card asks for a field, supply its verified value and rerun. You can also download the refusal for review. |
| Interrupted | Use **Retry file** when the original is still available. If prompted, choose **Attach original file** and select the same export again. |
## History and questions [#history-and-questions]
The hosted workspace processes uploads on the server and stores thread history in this browser. After a reload, you can review saved results, and a retry may ask for the original file again. Use [local Python](/docs/python) or [local MCP](/docs/mcp) if you need the extraction to run on your own machine.
When Q&A is enabled, you can ask about released files in the current thread. Try asking which transactions contributed to a total and request the source records. Application code computes totals and counts. Answers can cite files or record IDs. Deployments with the optional linker can also report [payout matches](/docs/payment-settlements).