ocracy.make_backend#

Abstraction tools for building OCR facades.

Writing a new backend should be mostly declarative. This module supplies the reusable machinery so an adapter is just “call the engine, return normalized blocks”:

BaseOcrAdapter — subclass it and implement _read(); kwarg translation (via the backend’s param_map) is handled for you.
make_block() / as_bbox() — build normalized TextBlock / BBox from whatever shape the engine returned, including confidence-scale normalization (e.g. Tesseract’s 0..100 -> 0..1).
scaffold_backend() — generate a new ocracy/backends/<id>/ package from the template, pre-filled from the ledger entry. This is the one-command way to start a facade for any backend in the catalog.
make_test_image() / validate_adapter() — smoke-test an adapter end to end so you know a new facade actually works.

These are the “abstraction tools and skills that know the process” — the companion SKILL.md walks an agent (or human) through using them.

Functions

`make_block`(text, *[, bbox, confidence, ...])	Build a normalized `TextBlock`.
`as_bbox`(obj)	Coerce common bbox shapes into a `BBox`.
`normalize_confidence`(value, *[, scale])	Normalize a raw confidence to `[0, 1]` (dividing by `scale`).
`scaffold_backend`(backend_id, *[, dest, ...])	Create a new `ocracy/backends/<id>/` package from the template.
`make_test_image`([text, size, font_size])	Render a black-on-white test image with `text` (needs Pillow).
`validate_adapter`(backend_id, *[, image, ...])	Smoke-test a backend adapter end to end, returning a report dict.

Classes

BaseOcrAdapter(config)

Optional base class for backend adapters.

class ocracy.make_backend.BaseOcrAdapter(config)[source]#

Bases: object

Optional base class for backend adapters.

Stores the config, builds a kwarg translator from config['param_map'], and implements read as: translate normalized kwargs -> native kwargs -> _read(). Subclasses implement _read() and return an OcrResult.

Adapters are not required to subclass this — the registry only needs an Adapter class with a read(image, **kwargs) method — but doing so removes the boilerplate.

ADAPTER_KWARGS = ('api_key', 'app_key', 'app_id')#: Keyword arguments a remote adapter reads itself (credentials), passed through untranslated: no param_map declares them, and they must never be dropped. On a local backend they are dropped with a (redacted) note.

read(image, **kwargs)[source]#

Translate kwargs, run _read(), and put any drop notes on the result.

A parameter the backend cannot honour is warned about and dropped, and the drop is recorded in result.meta["notes"] so it is visible after the warning is gone (or filtered).

Return type:: OcrResult

ocracy.make_backend.as_bbox(obj)[source]#

Coerce common bbox shapes into a BBox.

Accepts a BBox (returned as-is), a 4-tuple (x0, y0, x1, y1), or a polygon [(x, y), ...] (4+ points). None passes through.

Return type:: Optional[BBox]

ocracy.make_backend.make_block(text, *, bbox=None, confidence=None, conf_scale=1.0, level='word', language=None, **meta)[source]#

Build a normalized TextBlock.

bbox may be any shape accepted by as_bbox(). confidence is normalized to [0, 1] via conf_scale (e.g. conf_scale=100 for percent-scale engines).

Return type:: TextBlock

ocracy.make_backend.make_test_image(text='OCR test 123', *, size=(640, 140), font_size=48)[source]#

Render a black-on-white test image with text (needs Pillow).

Uses a real TrueType font (DejaVuSans, then Pillow’s sized default) at a legible size so OCR engines can actually read it — important for validate_adapter() to be a meaningful smoke test.

ocracy.make_backend.normalize_confidence(value, *, scale=1.0)[source]#

Normalize a raw confidence to [0, 1] (dividing by scale).

None passes through. Use scale=100 for engines that report 0..100.

Return type:: Optional[float]

ocracy.make_backend.scaffold_backend(backend_id, *, dest=None, overwrite=False, ledger=None, extra_overrides=None)[source]#

Create a new ocracy/backends/<id>/ package from the template.

Pre-fills config.py from the backend’s ledger entry (if any) so you only have to flesh out param_map and implement adapter.py’s _read.

Parameters:

backend_id (str) – The ledger id (e.g. "easyocr", "google-vision"). The on-disk module name uses underscores; the config id keeps the id verbatim.
dest (Union[str, Path, None]) – Target directory (defaults to ocracy/backends/<id_underscored>).
overwrite (bool) – Allow writing into an existing non-empty directory.
ledger (Any) – A Catalog to read the record from (defaults to the shipped catalog).
extra_overrides (Optional[dict]) – Extra config-key overrides applied on top of the record.

Return type:

Path

Returns:

The path to the created backend package.

ocracy.make_backend.validate_adapter(backend_id, *, image=None, expect_text=None)[source]#

Smoke-test a backend adapter end to end, returning a report dict.

Loads the adapter (reporting unavailability instead of raising), runs read on a generated (or supplied) image, and checks the contract: an OcrResult came back with text and/or blocks. Never raises on a recognition mismatch — it returns what happened so callers can decide.

Return type:: dict