llama-index-readers-hexread

A LlamaIndex reader for HexRead. It converts PDFs and images to Markdown through the HexRead API and returns LlamaIndex Documents. Nothing is processed locally.

API access requires a paid HexRead plan. The free trial is web only, so no API key can be issued for it. Keys are created and revoked in your HexRead dashboard.

Install

pip install llama-index-readers-hexread

Python 3.10+. Pulls in hexread and llama-index-core.

Quick start

from llama_index.readers.hexread import HexReadReader

docs = HexReadReader().load_data("report.pdf")  # one Document per page

Set HEXREAD_API_KEY, or pass api_key= to the reader. The API client is built on the first conversion, never at construction, so a reader can be created before a key is available.

file is a path, raw bytes, or an open binary file.

Reader options

A reader holding a HexRead serves the sync methods; one holding an AsyncHexRead serves aload_data. Using the wrong one raises TypeError with the fix in the message.

Methods

extra_info is merged underneath the reader's own keys, so a SimpleDirectoryReader's file_name and creation_date survive while source and page stay authoritative.

load_data_many keeps the batch alive when one file fails: by default the failure is logged and that file's Documents are skipped. Pass raise_on_error=True to abort instead. Keep max_workers at or below the concurrency your plan allows, or the API answers 429.

reader = HexReadReader()

docs = reader.load_data_many(["a.pdf", "b.pdf", "scan.png"], max_workers=2)

Async, with a client the reader does not own and so does not close:

from hexread import AsyncHexRead
from llama_index.readers.hexread import HexReadReader

async with AsyncHexRead() as client:
    docs = await HexReadReader(client=client).aload_data("report.pdf")

With no injected client, aload_data builds one for the call and closes it before returning.

Document metadata

Each Document also gets a stable id_: "<source>:<page index>" per page, or "<source>" when split="file", so re-ingesting a document updates in place instead of duplicating.

A whole directory

HexReadReader works as a SimpleDirectoryReader file extractor:

from llama_index.core import SimpleDirectoryReader
from llama_index.readers.hexread import HexReadReader

reader = HexReadReader()
extractor = {ext: reader for ext in (".pdf", ".png", ".jpg", ".jpeg", ".tiff", ".webp")}

docs = SimpleDirectoryReader("./contracts", file_extractor=extractor).load_data()

License

Licensed under the MIT License, © HexWorld Solutions GmbH.

Source, issues and the core client: github.com/HexWorldEU/hexread-python.