llama-index-readers-hexread

License: MIT

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

Option Default Effect
api_key environment, then CLI credential key for this reader
model auto parser to request; naming one requires a plan that allows it
lang unset OCR language hint, passed through to the parser
split "page" "page" for one Document per page, "file" for one per document
base_url https://api.hexread.com/v1 API base URL
client built on first use an existing HexRead or AsyncHexRead to convert with
extra_metadata {} extra keys merged into every Document's metadata

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

Method Returns Notes
load_data(file, extra_info=None) list[Document] converts one file
lazy_load_data(file, extra_info=None) Iterator[Document] converts when the first Document is pulled
aload_data(file, extra_info=None) list[Document] async; needs an AsyncHexRead or no injected client
load_data_many(files, *, max_workers=2, extra_info=None, raise_on_error=False) list[Document] several files, a few at a time, in input order

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

Key Value
source the path that was converted
page page index, 0-based (absent when split="file")
page_label page number as a string, 1-based (absent when split="file")
total_pages pages in the converted document
model parser that produced the Markdown
route_reason why the auto router picked that parser (absent when a model was requested)
parser always hexread

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.

Project links

Data verified by PyPI on Aug 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for alaamroue from gravatar.com alaamroue

Credits

Author: HexWorld Solutions GmbH

GitHub Statistics

Data verified by PyPI on Aug 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Tags

document parsing markdown ocr pdf pdf to markdown rag

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

llama_index_readers_hexread-0.1.0.tar.gz (6.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

llama_index_readers_hexread-0.1.0-py3-none-any.whl (7.3 kB view details)

Uploaded Python 3

File details

Details for the file llama_index_readers_hexread-0.1.0.tar.gz.

File metadata

File hashes

Hashes for llama_index_readers_hexread-0.1.0.tar.gz
Algorithm Hash digest
SHA256 a2eb60c9b3a3a3d53635fc0ab86da4ff0cf76df3ad0f9b656cd32a44b1962b43
MD5 05f8b0de42cb9a17d10322e4fb8093fb
BLAKE2b-256 706fb214523f5eaf4cf26e2d2094820a7bd1fde7292b2f1320aca0a9b9e23640

See more details on using hashes here.

Provenance

The following attestation bundles were made for llama_index_readers_hexread-0.1.0.tar.gz:

Publisher: release.yml on HexWorldEU/hexread-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file llama_index_readers_hexread-0.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for llama_index_readers_hexread-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 60372eb4c7999b8713bbf53b7e7f018a4a4c7baaa87126fa96b0e30224daf547
MD5 d6b1934d969b9a19de873f57605dcea8
BLAKE2b-256 d3c3bf1d51444394e302a305730982d13c5b85e4d2575c45c042b00e9300e3a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for llama_index_readers_hexread-0.1.0-py3-none-any.whl:

Publisher: release.yml on HexWorldEU/hexread-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page