@techspokes/ocr-box-geometry-descriptor

Turn OCR boxes into page-position descriptors that a small LLM can classify reliably.

The package converts geometry into words, counts, and ordered lists, then keeps exact percentages in a separate geometry block. One configuration drives three coordinated artifacts: per-box descriptors, a legend for prompts, and a JSON Schema contract.

Table of contents

• Installation
• Quick start
• Typical LLM workflow
• Public API
• Documentation map
• Version notes
• License

Installation

npm install @techspokes/ocr-box-geometry-descriptor

Quick start

import { describeBox } from '@techspokes/ocr-box-geometry-descriptor';

const descriptor = describeBox(
  { left: 0.5836, top: 0.9215, right: 0.9284, bottom: 0.9695 },
  { pageNumber: 1, totalPages: 11 },
);

console.log(descriptor.location.main_cell);
console.log(descriptor.size.vs_page);
console.log(descriptor.coverage.concentration);

Typical LLM workflow

Generate the legend once per resolved configuration and place it in the system prompt.

Generate the JSON Schema once per resolved configuration and register it as a structured-output contract.

Call describeBox for each OCR element, or describeBoxes for chunk batches, then feed descriptors as model input.

Public API

| Export | Purpose | |---|---| | describeBox(box, page, options?) | Convert one normalized box and page meta into a descriptor. | | describeBoxes(chunks, totalPages, options?) | Convert an OCR chunk batch where chunk pages are 0-based. | | generateLegend(options?, render?) | Generate prompt text tied to the same resolved grid. | | generateSchema(options?) | Generate JSON Schema 2020-12 for descriptor validation. | | resolveGrid(options?) | Resolve, merge, and validate the effective grid config. | | getPreset(name) | Get preset boundaries only. | | DEFAULT_GRID | Default complete grid configuration. | | SCHEMA_ID | Schema identifier constant: ocr-box/v3. | | DescriptorError | Typed runtime error with code. |

Documentation map

• Start here: docs/README.md
• Getting started guide: docs/getting-started.md
• API reference: docs/api-reference.md
• Configuration guide: docs/guides/configuration.md
• LLM integration guide: docs/guides/llm-integration.md
• Error handling guide: docs/guides/error-handling.md
• Runtime compatibility guide: docs/guides/runtime-compatibility.md
• Full technical specification: docs/specifications/ocr-box-v3-spec.md

Version notes

Default vertical bands are top, upper, main, lower, bottom.

If you migrated from earlier defaults that used header, update any string checks or stored fixture expectations.

License

MIT