Architecture and verification
Understand parsing providers, Decimal normalization, deterministic verification, typed model cross-checks and the hosted runtime topology.
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
- Detection chooses the provider. The engine examines the file type and content signatures, such as a CSV header or a structured balance record.
- 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.
- Normalization produces a shared shape. The engine represents amounts with exact decimals, records direction separately, and associates transactions with their batch and account.
- 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.
- 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. 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
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 engineThe 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
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, model guide, and MCP integration for the other runtime paths.