Metadata-Version: 2.4
Name: ocrkitx
Version: 0.1.0
Summary: Offline hybrid OCR SDK for structured document extraction.
Author: OCRKitX Contributors
License: MIT License
        
        Copyright (c) 2026 OCRKitX Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/OCRKitX/ocrkitx
Project-URL: Documentation, https://github.com/OCRKitX/ocrkitx#readme
Project-URL: Issues, https://github.com/OCRKitX/ocrkitx/issues
Keywords: ocr,pdf,invoice,bank-statement,document-extraction,paddleocr,tesseract
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.0.0
Requires-Dist: pytesseract>=0.3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: image
Requires-Dist: opencv-python<4.7,>=4.6; extra == "image"
Provides-Extra: pdf
Requires-Dist: pdf2image>=1.17.0; extra == "pdf"
Requires-Dist: pdfplumber>=0.11.0; extra == "pdf"
Provides-Extra: table
Requires-Dist: camelot-py[cv]>=0.11.0; extra == "table"
Provides-Extra: paddle
Requires-Dist: paddleocr<2.8,>=2.7; extra == "paddle"
Requires-Dist: paddlepaddle<3.0,>=2.6; extra == "paddle"
Provides-Extra: easyocr
Requires-Dist: easyocr>=1.7.0; extra == "easyocr"
Provides-Extra: all
Requires-Dist: opencv-python<4.7,>=4.6; extra == "all"
Requires-Dist: pdf2image>=1.17.0; extra == "all"
Requires-Dist: pdfplumber>=0.11.0; extra == "all"
Requires-Dist: camelot-py[cv]>=0.11.0; extra == "all"
Requires-Dist: paddleocr<2.8,>=2.7; extra == "all"
Requires-Dist: paddlepaddle<3.0,>=2.6; extra == "all"
Requires-Dist: easyocr>=1.7.0; extra == "all"
Dynamic: license-file

# ocrkitx

`ocrkitx` is a production-oriented Python SDK for offline OCR and structured business document extraction.

Current milestone includes:

- `OCRKit` public API
- Tesseract OCR integration
- Optional digital PDF text extraction with `pdfplumber`
- Optional digital PDF table extraction with Camelot, with `pdfplumber` fallback
- Optional PaddleOCR primary engine
- Tesseract fallback engine
- Optional EasyOCR fallback for difficult images
- Hybrid Paddle + Tesseract field merge
- Scanned PDF conversion with `pdf2image`
- Routing for image, digital PDF, and scanned PDF detection
- Auto document classification for invoice, bank statement, and generic documents
- Page-wise output, layout blocks, and table metadata in the standard result
- Invoice, bank statement, and generic document types
- Text, JSON, and Markdown formatters
- TOON formatter for token-oriented object notation
- Confidence, warnings, and `review_required`
- Debug trace output with route, timing, pages processed, and low-confidence fields
- Production targeted extraction with `fields=[...]`, custom aliases, and presets
- Optional generic `all_fields` discovery with confidence scoring

## Install for development

```bash
pip install -e ".[dev,image,pdf]"
```

For PaddleOCR support:

```bash
pip install -e ".[paddle]"
```

For stronger digital PDF table extraction:

```bash
pip install -e ".[table]"
```

For EasyOCR fallback support:

```bash
pip install -e ".[easyocr]"
```

For all optional local engines:

```bash
pip install -e ".[all]"
```

On Windows, scanned PDF conversion through `pdf2image` may also require Poppler installed and available on `PATH`.

For Tesseract OCR you also need the Tesseract binary installed on your system.

On Windows, install it separately and make sure `tesseract.exe` is available on your `PATH`.

## Basic usage

```python
from ocrkitx import OCRKit

ocr = OCRKit(
    mode="auto",
    tesseract_cmd=r"C:\Program Files\Tesseract-OCR\tesseract.exe",
)

result = ocr.extract(
    file="invoice.pdf",
    document_type="auto",
    output_format="json",
    debug=True,
)

print(result)
```

## Production targeted extraction

For production apps, pass the exact fields you want. This keeps output clean and avoids noisy generic discovery.

```python
from ocrkitx import OCRKit

ocr = OCRKit(mode="auto")

result = ocr.extract(
    "invoice.pdf",
    document_type="invoice",
    fields=["invoice_number", "po_number", "total_amount"],
    output_format="json",
)

print(result["fields"])
```

When `fields` or `preset` is provided:

- `fields` contains only requested fields
- `key_values` contains only requested fields that were found
- `all_fields` discovery is disabled by default
- missing required fields add warnings and can set `review_required=True`

## Custom fields

Use custom aliases for fields that are specific to your workflow.

```python
result = ocr.extract(
    "invoice.pdf",
    document_type="invoice",
    fields={
        "vehicle_type": {
            "type": "text",
            "aliases": ["Vehicle Type", "Truck Type"],
        },
        "delivery_terms": {
            "type": "text",
            "aliases": ["Delivery Terms", "Incoterms"],
            "required": False,
        },
    },
    output_format="json",
)
```

Supported field types include:

- `text`
- `date`
- `amount`
- `gstin`
- `ifsc`

## Presets

Presets are shortcuts for common production use cases.

```python
result = ocr.extract(
    "invoice.pdf",
    document_type="invoice",
    preset="invoice_compliance",
    output_format="json",
)
```

Available presets:

- `invoice_basic`
- `invoice_compliance`
- `invoice_logistics`
- `bank_basic`

## Discovery mode

Generic discovery is still available for exploration/debugging.

```python
result = ocr.extract(
    "invoice.pdf",
    document_type="invoice",
    output_format="json",
    all_fields=True,
    all_fields_min_confidence="medium",
)

print(result["all_fields"])
```

Use targeted extraction for production. Use `all_fields` when exploring a new document format.

## Modes

- `mode="auto"`: digital PDFs use `pdfplumber`; scanned PDFs/images use PaddleOCR with Tesseract fallback.
- `mode="fast"`: prefer digital PDF text or PaddleOCR.
- `mode="fallback"`: PaddleOCR first, then Tesseract, then EasyOCR if confidence is low.
- `mode="hybrid"`: run PaddleOCR and Tesseract, then merge extracted fields.

## Document types

- `invoice`
- `bank_statement`
- `generic`
- `auto`

## Output formats

- `json`
- `markdown`
- `text`
- `toon`

Internally, extraction runs once into one standard result schema. Formatters only convert that result for humans or machines.

## Standard result highlights

JSON output includes:

- `fields` with value, confidence, source, validity, and validation errors
- `pages` for page-wise text/tables/confidence metadata
- `blocks` for simple layout sections such as headers, parties, tables, totals, and footers
- `tables` from digital PDFs when available
- `warnings` and `review_required`
- optional `debug` details when `debug=True`

## Backward-compatible Tesseract-only usage

```python
from ocrkitx import OCRKit

ocr = OCRKit(
    engine="tesseract",
    tesseract_cmd=r"C:\Program Files\Tesseract-OCR\tesseract.exe",
)

result = ocr.extract("invoice.png", output_format="json")
print(result)
```

## TOON Output

```python
result = ocr.extract(
    "invoice.pdf",
    document_type="invoice",
    output_format="toon",
)

print(result)
```
