Chandra OCR 2: layout-preserving document conversion from the datalab-to/chandra repository

What Chandra OCR 2 is for, and who it is not for

Chandra OCR 2 is an OCR model from Datalab that converts images and PDFs into structured HTML, Markdown or JSON while preserving layout information. The README frames the target as documents where plain text extraction loses meaning: complex tables, filled forms with checkboxes, handwritten math, and multi-column layouts. It also lists support for 90+ languages and says the model extracts images and diagrams and adds captions and structured data.

The audience is engineers building document pipelines that need structure, not just characters. If you are scanning a stack of invoices and want a table to come back as a table, or a lease form to come back with its checkbox states, that is the stated use case. If you only need to pull plain text out of a clean, single-column PDF, the extra machinery here is not buying you much.

The repository is Python, and pyproject.toml declares requires-python >=3.10. The code is Apache-2.0. The model weights are not: the README badge points to OpenRAIL-M, and a Commercial usage section is referenced for self-hosting. That split matters more than any feature list, and it is the first thing to resolve for a commercial deployment.

Two inference paths: vLLM server or HuggingFace

The README describes two inference modes, local via HuggingFace and remote via a vLLM server, and the install extras map onto them. The base package installs the dependencies listed in pyproject.toml (click, pillow, pypdfium2, pydantic, markdownify and others) without torch. The hf extra adds torch, torchvision, transformers and accelerate. The app extra adds streamlit.

The CLI entry points come from pyproject.toml: chandra, chandra_app, chandra_screenshot and chandra_vllm. That naming tells you the intended workflow. You either start a vLLM server with chandra_vllm and point the chandra CLI at it, or you run the model locally with --method hf. The README calls the vLLM route the recommended, lightweight install, which is consistent with the dependency split: no torch in the base package.

Output formats are Markdown, HTML and JSON, with the README promising detailed layout information in the structured formats. That is the part worth designing around. If your downstream consumer is a human reading Markdown, the format choice is trivial. If it is a parser, the JSON layout output is where the value sits, and the README does not spell out the schema in the excerpt available here.

Installing chandra-ocr and running a first PDF

The package is published as chandra-ocr. The base install targets the vLLM backend and deliberately avoids pulling torch, which keeps the environment small. The README gives this as the recommended path.

pip install chandra-ocr

After that you start the vLLM server and process a file. The README shows the server launcher and a single-file invocation; the CLI takes an input file and an output directory, with --method selecting the backend.

chandra_vllm
chandra input.pdf ./output

The README also notes the CLI handles entire directories, not just single files, so pointing it at a folder of PDFs is a supported pattern. If you prefer the local HuggingFace path instead, you install the hf extra and pass --method hf.

pip install chandra-ocr[hf]
chandra input.pdf ./output --method hf

The README recommends installing flash attention alongside the HuggingFace method for better performance. There is also a Streamlit app for interactive use, installed via the app extra and launched with chandra_app.

pip install chandra-ocr[app]
chandra_app

For a source checkout, the README uses uv: clone the repository, run uv sync, then activate the virtual environment at .venv/bin/activate.

The licensing split is the real adoption constraint

Most projects have one licence. Chandra has two, and they point in different directions. The repository code is Apache-2.0, which is permissive and familiar. The model weights are OpenRAIL-M, which is not. The README states plainly that commercial self-hosting requires a licence and links to a contact page for on-prem licensing.

This is not a footnote you can skip. A team that reads Apache-2.0 on the repository and assumes the whole stack is permissive will be wrong about the part that does the actual work. The model is the product; the code is the wrapper around it. If your deployment is commercial and self-hosted, the README says a licence is required, and there is a MODEL_LICENSE file in the repository root alongside LICENSE.

There is a managed alternative in the same README: the Datalab platform runs what it describes as an improved Chandra with higher accuracy than the open weights, zero data retention by default, SOC 2 Type 2 and custom BAAs. That is a hosted service with its own terms, and the README mentions $5 in free credits to start. For a team that wants the accuracy without the licence negotiation, that is the path the project itself steers you toward. Whether that is acceptable depends on where your documents are allowed to go.

Where Chandra OCR 2 will disappoint you

The README makes strong claims about tables, math, handwriting and 90+ languages, and points to a multilingual benchmark the team built because, in its own words, there isn't a good public multilingual OCR benchmark. That is an honest statement about the state of the field, but it also means the multilingual numbers come from a benchmark the project authors designed. Treat them as directional, not neutral.

The heavier limitation is operational. Running the HuggingFace path means torch, transformers and a GPU-sized dependency tree, plus a recommendation to add flash attention. The vLLM path means running a separate server process before the CLI does anything useful. Neither is a single pip install and go. If your environment has no GPU, or you cannot run a persistent inference server, this is the wrong tool, and no flag in the README changes that.

The README does not document rollback, version pinning between model releases, or how output schemas change across versions. There are three releases listed: v0.1.6, v0.1.7 and v0.2.0 (Chandra OCR 2). The jump from 0.1.7 to 0.2.0 is described as significant improvements to math, tables, layout and multilingual OCR, which is exactly the kind of change that can shift output on the same input. If you depend on exact output, pin your version and keep your own regression set. The repository does not provide one for you.

How it compares to a general-purpose vision model pipeline

The obvious alternative is wiring a general vision-language model into a PDF-to-image loop yourself, using something like a multimodal API and prompting for Markdown. The difference in approach is where the document structure comes from. With a general model, layout is whatever the prompt and the model's training happen to produce, and you own the page-splitting, ordering and table reconstruction logic. With Chandra, layout preservation is the stated purpose of the model, and the output formats include JSON with detailed layout information.

That matters for tables and forms specifically. A general model asked to transcribe a financial table will often produce something that reads correctly and parses incorrectly, because nothing in the pipeline enforces cell boundaries. Chandra's README claims accurate form reconstruction including checkboxes, which is a structural claim rather than a text claim.

The trade-off runs the other way too. A general model is usually reachable over an API with no GPU and no server process, and it can answer questions about the document rather than only transcribing it. Chandra is a transcription and structuring tool. If you need extraction of specific fields into a schema, you are still writing that layer on top of whatever Chandra returns. The README does not claim to do it for you.

Maintenance, releases and the cost of upgrading

The repository is not archived, and the last push was on 2026-06-26. The most recent release is v0.2.0 (Chandra OCR 2) from 2026-03-18, following v0.1.7 on 2025-10-22 and v0.1.6 on 2025-10-21. The gap between the 0.1.x line and 0.2.0 is about five months, and the project describes 0.2.0 as a major step rather than a patch.

Upgrade cost is dominated by the dependency tree rather than the package itself. The hf extra pins minimum versions of torch, torchvision, transformers and accelerate, and the base package pins markdownify exactly at 1.1.0. A model release that bumps transformers requirements can collide with whatever else is in your environment, and the README offers no guidance on supported version combinations beyond the floors in pyproject.toml.

On licence implications, the split is the thing to plan around: Apache-2.0 for the code, OpenRAIL-M for the weights, and a stated requirement for a licence for commercial self-hosting. This article is not legal advice, and the README's own pointer to a contact page for on-prem licensing is the authoritative route. What you can do without a lawyer is read LICENSE and MODEL_LICENSE in the repository root, both of which are present.

Editorial conclusion

Adopt Chandra OCR 2 if you need layout-aware output from PDFs, tables, forms or handwriting and you can accept the OpenRAIL-M model licence and a GPU-backed inference path. Do not adopt it if you need a pure CPU drop-in or a permissively licensed model for a commercial product without a licence conversation. Before committing, verify three things: which backend you will run (vLLM or HuggingFace), whether your use case falls under commercial self-hosting, and whether the JSON layout output gives you the fields your pipeline needs.

Frequently asked questions

Official sources

1. datalab-to/chandra on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases