ocrkitx 0.1.0

Offline hybrid OCR SDK for structured document extraction.

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

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

For PaddleOCR support:

pip install -e ".[paddle]"

For stronger digital PDF table extraction:

pip install -e ".[table]"

For EasyOCR fallback support:

pip install -e ".[easyocr]"

For all optional local engines:

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

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.

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.

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.

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.

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

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

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

print(result)