The unified interface for every reading.

One response contract, with content that depends on the backend. Text, pages, tables, geometry, and confidence are optional; a field-only result can use typed_fields without pages. Available bounding boxes use page-relative [0,1] coordinates. A shared shape does not promise identical readings or complete content.

{
  "schema_version": "0.3",
  "status": {"state": "succeeded"},
  "backend": {"id": "pymupdf", "type": "oss_library", "output_paradigm": ["block_tree"]},
  "document": {
    "page_count": 1,
    "pages": [
      {
        "page_number": 1,
        "width": 612,
        "height": 792,
        "unit": "pdf_point",
        "blocks": [
          {
            "type": "text",
            "native_type": "text",
            "text": "First National Bank",
            "reading_order": 0,
            "bbox": {"x": 0.0588, "y": 0.0265, "w": 0.2085, "h": 0.0243, "page": 1}
          }
        ]
      }
    ]
  },
  "usage": {"pages_processed": 1},
  "warnings": [{"code": "confidence_unavailable", "field": "block_confidence"}]
}

{
  "schema_version": "0.3",
  "status": {"state": "succeeded"},
  "backend": {"id": "tesseract", "type": "oss_library", "output_paradigm": ["element_list"]},
  "document": {
    "page_count": 1,
    "pages": [
      {
        "page_number": 1,
        "width": 1275,
        "height": 1650,
        "unit": "pixel",
        "blocks": [
          {
            "type": "text",
            "native_type": "line",
            "text": "First National Bank",
            "confidence": 0.96,
            "reading_order": 0,
            "bbox": {"x": 0.0604, "y": 0.0327, "w": 0.2063, "h": 0.0133, "page": 1}
          }
        ]
      }
    ]
  },
  "usage": {"pages_processed": 1}
}

{
  "schema_version": "0.3",
  "status": {"state": "succeeded"},
  "backend": {
    "id": "aws-textract",
    "type": "hosted_api",
    "operation": "AnalyzeDocument",
    "output_paradigm": ["block_graph"]
  },
  "document": {
    "page_count": 1,
    "pages": [
      {
        "page_number": 1,
        "blocks": [
          {
            "type": "title",
            "native_type": "LAYOUT_TITLE",
            "text": "Loan Application",
            "confidence": 0.994,
            "reading_order": 0,
            "bbox": {"x": 0.1, "y": 0.05, "w": 0.5, "h": 0.04, "page": 1}
          }
        ]
      }
    ]
  },
  "typed_fields": {"Total": {"value": "$4,400.00", "confidence": 0.965}}
}

PyMuPDF and Tesseract read the same bank statement. Textract uses separate test data. Responses are shortened and numbers rounded for readability. Other providers show capabilities, not extraction results. These are static examples, not live calls or accuracy benchmarks.

Learn more: Understand the response JSON ↗ · Tables and coordinates ↗

Parse reads documents through a supported backend. Compare shows where outputs agree or differ. Strategy runs the backend order and quality checks you specify. And each feature works for three audiences: a human at a terminal, a program, or an agent.

The CLI, Python API, and your HTTP server share the vendored JSON Schemas. Agents can use those interfaces today. Native MCP tools and triage are not shipped.

Learn more: Read a comparison ↗ · Process a folder ↗

A strategy is a named plan for trying backends and checking their results. For example, start with a PDF text parser, then run OCR when the quality check rejects its output.

version: 1

policy:
  backends: [pymupdf, tesseract]

strategies:
  scan_aware:
    try: [pymupdf, tesseract]
    escalate_when: looks_bad
    max_time: "2m"

A gate is a check that accepts a result or moves to the next backend. Here, looks_bad checks signals such as garbled text and mostly empty pages. It does not guarantee that extracted values are correct.

Install the Tesseract system binary before using this example. Validate the file with openreading strategy validate, then run openreading parse examples/1040-1988.pdf --strategy scan_aware. Follow the local-first tutorial ↗ for setup, traces, and replay.

Learn more: Read the trace ↗ · Race and compare ↗

An agent uses the same CLI, Python API, or HTTP server as your application. openreading help serves the manual directly from the code, including examples and exit codes.

Status appears in status.state, warnings carry codes, and comparison reports expose headline.verdict: equivalent, divergent, or mixed. A strategy trace records attempts and decisions for inspection.

Native openreading mcp tools and triage are not shipped. Today, start with the CLI help chapter ↗ and CLI guide.

Learn more: Read status and warnings ↗

Core does not bundle a web UI or send documents through OpenReading infrastructure. A hosted backend is a vendor API, such as Textract, called with your credentials. Local backends run in your environment.

Learn more: Install core ↗ · Use Python and HTTP ↗

Use Git and uv to install the current checkout. PyMuPDF reads the bundled example locally; you do not need a provider account.

git clone https://github.com/openreading-ai/openreading-core
cd openreading-core
uv sync --all-extras --dev
uv run openreading backends
uv run openreading parse examples/john_smith_1000_2026_01.pdf --backend pymupdf > parsed.json
uv run openreading compare parsed.json parsed.json --format diffs

import openreading

doc = openreading.run(
    "examples/john_smith_1000_2026_01.pdf",
    backend="pymupdf",
)
print(doc["status"]["state"])
# succeeded

The comparison above checks a saved result against itself without another backend call. Compare two different readings ↗ to compare different backends, add OCR, and build a strategy. Tesseract requires a separate system binary; hosted backends require your vendor credentials.

For an HTTP interface, run uv run openreading serve yourself. Core does not include serve-ui, managed hosting, or a commercial account.

Learn more: Your first parse ↗ · Build a Python consumer ↗

The tutorial lives with this website. Reference guides and the self-documenting CLI live with the engine, beside the behavior they describe.

Install the current core checkout from source. Backend availability depends on its dependencies, credentials, and supported formats. openreading backends reports local setup; a configured backend is not proof that its vendor accepted your key.

Learn more: Check your backends ↗ · Resume a strategy run ↗