Sohojpath

Sohojpath is a Python library and command-line tool for geometry-preserving Bengali PDF OCR. It extracts normalized Unicode text while retaining each word's bounding box, Tesseract line identifiers, and confidence score for table extraction, document analysis, and human review.

Sohojpath is currently alpha software. OCR output is not ground truth; validate critical fields and retain a manual-review path.

Features

• Bengali or bilingual OCR through Tesseract (ben, ben+eng, or another installed set)
• Normalized UTF-8 plain-text output
• Page-level JSON Lines with word coordinates and confidence
• One-based page selection such as 1,3-5
• Python API and sohojpath CLI
• Explicit language-data diagnostics
• Type information through py.typed

Requirements and installation

Sohojpath requires Python 3.10 or newer and Tesseract OCR with Bengali language data.

# Windows
winget install UB-Mannheim.TesseractOCR

# Ubuntu/Debian
sudo apt install tesseract-ocr tesseract-ocr-ben

# macOS
brew install tesseract tesseract-lang

Install Sohojpath:

python -m pip install sohojpath

For development from a clone:

python -m pip install -e ".[dev]"

Command line

# Check Tesseract and language availability
sohojpath doctor

# Extract normalized text
sohojpath text document.pdf --pages 1-3 --output document.txt

# Extract page-level JSON Lines with word geometry
sohojpath ocr document.pdf --pages 1-3 --output document.jsonl

Useful options:

--language ben+eng       Tesseract languages
--dpi 300                Rendering resolution
--psm 6                  Tesseract page-segmentation mode
--minimum-confidence 40  Exclude lower-confidence words
--tesseract PATH         Explicit Tesseract executable
--tessdata PATH          Explicit language-data directory
--timeout SECONDS        Maximum time for each Tesseract invocation

Run sohojpath COMMAND --help for the complete command reference.

Python API

from sohojpath import BanglaPdfParser, ParserConfig

parser = BanglaPdfParser(ParserConfig(language="ben+eng", dpi=300))

for page in parser.parse("document.pdf", pages=[1, 2]):
    print(page.page, page.text)
    for word in page.words:
        print(word.text, word.confidence, word.left, word.top)

If language files are outside Tesseract's default location, pass ParserConfig(tessdata=Path("path/to/tessdata")).

Structured output

The ocr command emits JSON Lines so large PDFs can be processed incrementally. Each page contains its source, one-based page number, DPI, pixel dimensions, normalized text, and words with confidence, bounding box, block, paragraph, and line identifiers.

Coordinates are integer pixels in the page image rendered at the requested DPI. Pages are emitted in the requested order; words are emitted in Tesseract's TSV order. The synthesized page text groups words by Tesseract block, paragraph, and line identifiers and orders them top-to-bottom, then left-to-right.

The JSONL structure is considered provisional during the 0.x series. Incompatible schema changes will be called out in the changelog.

Scope and accuracy

Version 0.1 provides a reusable OCR and geometry layer. Document-specific schemas—such as electoral rolls, forms, registers, or fixed-column tables—should be implemented as opt-in profiles on top of the word geometry API.

Applications handling names, identity numbers, legal records, or other sensitive fields should preserve source documents, confidence values, validation results, and review decisions.

Development

python -m pip install -e ".[dev]"
python -m ruff format --check .
python -m ruff check .
python -m mypy
python -m coverage run -m unittest discover -s tests -v
python -m coverage report
python -m build
python -m twine check dist/*

The Python API raises ValueError for invalid configuration or page selection, FileNotFoundError for a missing input or Tesseract executable, and RuntimeError for PDF, language-data, malformed OCR output, timeout, and Tesseract execution failures. The CLI reports these failures on standard error and exits with status 2.

See CONTRIBUTING.md, SUPPORT.md, and SECURITY.md.

License

Licensed under the Apache License 2.0.