indra - Moses Yebei

The Problem

Document ingestion pipelines often rely on GPU‑heavy OCR engines that add latency and cost. A lightweight, CPU‑friendly OCR that still yields accurate text, layout, and reading‑order information is missing in many production stacks.

What This Does

Indra OCR delivers a 1 M‑parameter model that reads ~49 pages/s on a single CPU core.

indra_ocr/__main__.py and indra_ocr/cli.py expose the indra‑ocr command line tool.
The core pipeline lives in indra_ocr/pipeline.py, which stitches together:
indra_ocr/det_post.py – post‑processing of line detections,
indra_ocr/rec_preproc.py – image preprocessing for the recognizer,
indra_ocr/models.py – ONNX runtime wrappers for the text recognizer,
indra_ocr/layout_post.py & indra_ocr/order_post.py – layout block classification and reading‑order inference.
indra_ocr/document.py reads PDFs, preserving existing text layers for digital PDFs.
indra_ocr/viewer.py powers the optional web viewer (indra‑ocr‑viewer).

How It Is Wired

Execution starts at the console script defined in pyproject.toml, which imports indra_ocr/cli.py. cli.main() dispatches to pipeline.process() for each input file. pipeline.process() calls document.load() to read the PDF or image; if the PDF contains a text layer, document.TextLayer objects are returned unchanged. The image is fed to rec_preproc.preprocess() and then to models.Recognizer.recognize(). Recognized text, along with bounding boxes, is passed to det_post.postprocess() to merge lines into blocks. Finally, layout_post.classify_blocks() assigns semantic labels, and order_post.compute_order() produces a reading‑order list. The resulting JSON, markdown, or plain text is written by cli.output_writer(). The viewer command imports viewer.run() which serves the JSON locally.

Key functions with wide blast radius:

pipeline.process() – orchestrates the entire OCR flow.
models.Recognizer.recognize() – the ONNX inference engine.
det_post.postprocess() – merges lines into logical blocks.

How To Use It

Setup

pip install indra-ocr

Configuration No external config files are required; the model is downloaded automatically from Hugging Face the first run.

Running it

indra-ocr paper.pdf                 # stdout markdown
indra-ocr *.pdf --out results/      # one .md per file, parallelized
indra-ocr scan.png --format json    # JSON with boxes and confidences
indra-ocr-viewer                    # launch web viewer on localhost:8765

These commands use the entry points defined in pyproject.toml.

Real‑World Use

A batch ingestion service for a publishing house can wire indra-ocr into a Celery queue. Each worker pulls a PDF, runs indra-ocr locally, and pushes the resulting JSON to an S3 bucket for downstream indexing.

# worker/task.py
from indra_ocr import pipeline

def process_pdf(path: str, out_dir: str):
    result = pipeline.process(path)
    with open(f"{out_dir}/{Path(path).stem}.json", "w") as fp:
        json.dump(result, fp)

Code Health & Issues

Low / Dependency lockfile missing – pyproject.toml lists all dependencies but no poetry.lock or pipfile.lock is present, making builds non‑reproducible. (File: pyproject.toml)
No CI for code coverage – .github/workflows/publish.yml only builds; unit tests are present but coverage metrics are absent. (File: .github/workflows/publish.yml)

No other static analysis findings were reported.

The Bottom Line

Indra OCR offers a fast, CPU‑centric OCR solution with full layout awareness and a clean CLI. It is ideal for high‑volume, low‑budget pipelines that still need accurate reading order. The main trade‑off is the lack of a lockfile, which may affect reproducibility in tightly controlled environments.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

33 files

Python19
Markdown3
YAML1
TOML1

Module dependencies

The 10 most depended-upon modules of 19, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_indra_ocr_pipeline["pipeline"] n1_indra_ocr___init__["__init__"] n2_indra_ocr_models["models"] n3_indra_ocr_document["document"] n4_indra_ocr_cli["cli"] n5_indra_ocr_parallel["parallel"] n6_indra_ocr_math["math"] n7_indra_ocr_line_mask["line_mask"] n8_indra_ocr_order_post["order_post"] n9_indra_ocr_rec_preproc["rec_preproc"] n1_indra_ocr___init__ --> n3_indra_ocr_document n1_indra_ocr___init__ --> n2_indra_ocr_models n1_indra_ocr___init__ --> n5_indra_ocr_parallel n1_indra_ocr___init__ --> n0_indra_ocr_pipeline n4_indra_ocr_cli --> n1_indra_ocr___init__ n4_indra_ocr_cli --> n5_indra_ocr_parallel n4_indra_ocr_cli --> n2_indra_ocr_models n3_indra_ocr_document --> n0_indra_ocr_pipeline n3_indra_ocr_document --> n7_indra_ocr_line_mask n3_indra_ocr_document --> n6_indra_ocr_math n7_indra_ocr_line_mask --> n9_indra_ocr_rec_preproc n6_indra_ocr_math --> n7_indra_ocr_line_mask n6_indra_ocr_math --> n9_indra_ocr_rec_preproc n5_indra_ocr_parallel --> n0_indra_ocr_pipeline n5_indra_ocr_parallel --> n1_indra_ocr___init__ n5_indra_ocr_parallel --> n2_indra_ocr_models n0_indra_ocr_pipeline --> n7_indra_ocr_line_mask n0_indra_ocr_pipeline --> n6_indra_ocr_math classDef cyc stroke:#ef4444,stroke-width:2px; class n1_indra_ocr___init__,n5_indra_ocr_parallel cyc;

Dependencies

5 declared dependencies, none a major version behind. Resolved 5 of 5 against the registry.

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium3

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

astral-sh/setup-uv@v6, pypa/gh-action-pypi-publish@release/v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/publish.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/publish.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.