Metadata-Version: 2.4
Name: sohojpath
Version: 0.1.1
Summary: Geometry-preserving Bengali OCR for PDF documents
Author: Anindya
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Anindyakafka/sohojpath
Project-URL: Documentation, https://github.com/Anindyakafka/sohojpath#readme
Project-URL: Repository, https://github.com/Anindyakafka/sohojpath
Project-URL: Issues, https://github.com/Anindyakafka/sohojpath/issues
Keywords: bangla,bengali,ocr,pdf,tesseract
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Bengali
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyMuPDF>=1.24
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: coverage[toml]>=7.6; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Dynamic: license-file

# Sohojpath

[![CI](https://github.com/Anindyakafka/sohojpath/actions/workflows/ci.yml/badge.svg)](https://github.com/Anindyakafka/sohojpath/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/sohojpath.svg)](https://pypi.org/project/sohojpath/)
[![Python](https://img.shields.io/pypi/pyversions/sohojpath.svg)](https://pypi.org/project/sohojpath/)
[![License](https://img.shields.io/github/license/Anindyakafka/sohojpath)](LICENSE)

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.

```powershell
# Windows
winget install UB-Mannheim.TesseractOCR
```

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

# macOS
brew install tesseract tesseract-lang
```

Install Sohojpath:

```bash
python -m pip install sohojpath
```

For development from a clone:

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

## Command line

```bash
# 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:

```text
--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

```python
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

```bash
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](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), and
[SECURITY.md](SECURITY.md).

## License

Licensed under the [Apache License 2.0](LICENSE).
