scriva documentation

scriva — documentation index

scriva is a composable, engine-agnostic OCR framework for Python. Every step of a recognition run — load, detect, recognise, post-process, export — is a swappable stage, and every stage is a small Protocol.

The one-liner

import scriva
text = scriva.read("scan.png")

That uses sensible defaults end-to-end. When you want to swap a model, change a prompt, or stream events, drop down to the Pipeline API — every default above is one constructor argument away.

Three ways in

import scriva
from scriva.schemas import Invoice

scriva.read("scan.png")                          # text out
scriva.extract("acme.pdf", schema=Invoice)       # typed pydantic instance out
scriva.presets.invoice("acme.pdf")               # tuned pipeline + schema

Pick the highest-level entry that fits and drop a rung when you need more control. See scriva.extract and Presets.

Three pillars for high-accuracy production OCR

When the project’s bar is “wrong answers are unacceptable,” scriva exposes three composable pillars. Every other reference page slots into one of them.

1. Learn from your environment. Keep a SampleStore of your own corrections. The same store powers few-shot exemplars on the input side (RecognitionHint.from_store) and derived dictionaries on the output side (postprocess.dictionary.from_samples). One store, two roads — see samples.md › Two roads from a SampleStore.
2. Cross-check, then route. Three accuracy levers — human-in-the-loop review, cross-check against the original crop (round-trip rendering or multi-recognizer consensus), and cross-check against ground-truth data — compose freely. See Pipeline › High-accuracy patterns.
3. Manipulate the pixels the recognizer actually sees. Page-level preprocessing (orientation, deskew, dewarp) and region-level preprocessing (per-cell binarisation, horizontal/vertical slicing, per-role padding, glare removal, whiteboard clean-up) are both first-class. See Preprocessors.

Read in order

1. Concepts
2. Quickstart
3. Architecture

Reference — high level

4. scriva.extract — schema-first one-liner, classify, batch, watch.
5. Presets — pre-tuned pipelines per document kind.
6. Schemas — built-in pydantic models (Invoice, Receipt, IdCard, …).
7. Working with results — DocumentResult accessors and serialisation.
8. CLI — scriva extract, scriva watch, scriva eval, scriva annotate.

Reference — pipeline internals

9. Pipeline
10. Preprocessors
11. Detectors
12. Recognizers
13. Post-processors
14. Exporters
15. Caching
16. Sample stores

Reference — production

17. Reliability — retries, rate limits, timeouts, cost caps, PII redaction, telemetry.
18. Evaluation — scriva.eval, ground-truth format, calibration.

Recipes

19. Cookbook — worked recipes per document kind and per workflow.
20. Domain packs — pre-built pipelines for forms, P&ID, agentic extraction, annotation.
21. Pipeline › Recipes — human-in-the-loop review, confidence-driven re-OCR, recognizer diff.
22. Cookbook › Rebuilding ocr-agent — case study porting a Japanese-forms / P&ID / annotation app, plus FastAPI hosting.

One-line map

You want to…	Read…
just read an image to text	Quickstart › one-liner
extract a typed pydantic instance	scriva.extract
understand the design	Concepts
OCR an invoice / receipt / ID	Cookbook
OCR a tabular form to Excel	Domains › forms
route an unknown document	scriva.classify_document
ingest a folder continuously	Cookbook › Batch & watch
swap OpenAI for Anthropic	Recognizers
add a new output format	Exporters
serialise a result on the fly	Exporters › result verbs
cut API spend	Caching
set a hard cost cap	Reliability › Cost caps
retry on 429 / 5xx	Reliability › Retries
redact PII before sending to a VLM	Reliability › PII redaction
stream pages from a 100-page PDF	Cookbook › Long PDFs
score a pipeline against ground truth	Evaluation
OCR pages in parallel	Pipeline › options
straighten a rotated scan	Preprocessors › orientation
binarise / sharpen each cell separately	Preprocessors › Region preprocessors
slice a tall cell into rows	Preprocessors › Slicers
use a few-shot exemplar from past corrections	Recognizers › RecognitionHint
derive a correction dictionary from a labelled store	Post-processors › dictionary.from_samples
let a human review detected cells	Pipeline › Lever 1: HITL
cross-check the recognised text against the crop	Pipeline › Lever 2: Cross-check vs original
cross-check a run against ground truth	Pipeline › Lever 3: Cross-check vs ground-truth
re-OCR only the low-confidence cells	Pipeline › 2c: Confidence-driven re-OCR
plug in your own ML detector	Detectors › Writing your own
write a one-off post-processor	Post-processors › decorator
use scriva from the shell	CLI
port a FastAPI OCR app onto scriva	Cookbook › Rebuilding ocr-agent