Universal Doc Reader

An offline, lightweight (<30 MB footprint), layout-agnostic document processing library and CLI tool. Extract structured hierarchies (standard metadata, key-value pairs, and tabular line items) from bills, tax invoices, retail receipts, and reports with zero heavy cloud models and zero data transmission.

---

Key Features

• Ultra-Small Footprint (<30 MB): Powered by RapidOCR (ONNX Runtime CPU models ~12.3 MB). Zero multi-gigabyte models or cloud API dependencies.
• Offline & Private: Runs 100% locally on CPU with zero network traffic.
• Universal Layout Engine:
  • Tables: Detected dynamically through whitespace gutters and multi-column vertical projection. Headers and rows are extracted directly from the physical layout.
  • Dense Glued Token Slicing: Slices concatenated text (e.g. ACCUSUSURE DIGITALTHERMOMETER90251910 $\to$ Description + HSN, 2404910006-28 $\to$ HSN + Exp, 560121105088 $\to$ HSN + Batch).
  • Two-Tier Header Decomposition: Handles compound and stacked headers (e.g. MFD/MKTD, DIS%GST%, GST Rate / Amt).
  • Signature-Line Fallback: Fallback extraction for obscured headers using legal signature lines.
• Usable Anywhere: Standard Python package installable into any project or virtual environment.
• Rich Developer Tools: Interactive web UI (--web), desktop file picker (--browse), CLI tool (doc-reader), and standard Python library exports.

---

Installation

pip install universal-doc-reader

Install from Source (Development)

git clone https://github.com/NabPrime03/Universal_Doc_Reader.git
cd Universal_Doc_Reader

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

---

Quickstart (3 Lines of Code)

import universal_doc_reader as udr

# 1. Parse any document image (auto-routes invoice vs receipt)
result = udr.read("samples/media_1793545751588_cdc01682.jpg")

# 2. Access metadata (vendor, invoice number, date)
for field in result.metadata_fields:
    print(f"{field.field_label}: {field.text}")

# 3. Access table line items
for table in result.tables:
    for row in table.rows:
        row_dict = {cell.column: cell.text for cell in row.cells}
        print(row_dict)

---

Python Library API Reference

1. High-Level Helper Functions

import universal_doc_reader as udr

# Auto-detects layout and extracts structured data
result = udr.read("document.jpg")

# Specific document type shortcuts
invoice_result = udr.read_invoice("tax_invoice.jpg")
receipt_result = udr.read_receipt("pos_thermal.jpg")

# Target specific columns of interest
result = udr.read("invoice.jpg", target_headers=["Particulars", "HSN", "Rate", "Amount"])

2. Exporting to Dictionary or JSON

# Convert to standard Python dictionary
data = result.to_dict()

# Serialize to formatted JSON string
json_str = result.to_json(indent=2)

3. Pipeline Class for Batch Processing

For processing multiple documents efficiently without re-initializing OCR models:

from universal_doc_reader import DocumentPipeline

pipeline = DocumentPipeline()

for img_path in ["inv1.jpg", "inv2.jpg", "receipt1.jpg"]:
    result = pipeline.process(img_path)
    print(f"{img_path}: {result.document_metadata.detected_document_type}")

4. Data Models

All models are dataclasses and can be imported directly:

from universal_doc_reader import (
    DocumentResult,
    DocumentMetadata,
    MetadataField,
    KeyValuePair,
    Table,
    TableRow,
    TableCell,
    BoundingBox,
    OCRToken,
)

---

Command Line Interface (CLI)

The library installs doc-reader globally in your virtual environment:

# Print structured JSON to stdout
doc-reader /path/to/invoice.jpg

# Save output to file
doc-reader /path/to/invoice.jpg -o output.json

# Force specific layout reader
doc-reader /path/to/receipt.jpg -r receipt

---

Interactive Developer Test Suite (test.py)

Run test.py for interactive visualization, benchmarking, and debugging:

# 1. Run on a single file with colored terminal tables:
python test.py samples/media_1793547460032_9ee76414.jpg

# 2. Launch the local web upload UI in your browser:
python test.py --web
# Open: http://localhost:5000

# 3. Open desktop file picker dialog:
python test.py --browse

---

Running Automated Tests

pytest -v

All 11 unit and integration tests run offline on CPU in ~5 seconds.

---

Project Structure

Universal_Doc_Reader/
├── src/
│   └── universal_doc_reader/
│       ├── __init__.py          # Public API exports (read, DocumentPipeline, models)
│       ├── py.typed             # PEP 561 typing marker
│       ├── pipeline.py          # Master orchestrator
│       ├── cli.py               # Click CLI (doc-reader)
│       ├── core/                # Geometry, models, text normalization, OCR engines
│       └── readers/             # Specialized tax invoice and receipt readers
├── examples/
│   ├── quickstart.py            # 3-line usage example
│   └── export_to_json.py        # JSON serialization example
├── samples/                     # Real-world test documents
├── tests/                       # Pytest test suite
├── pyproject.toml               # Modern PEP 621 packaging
├── requirements.txt
├── README.md
└── test.py                      # Interactive CLI & Web UI runner

---

License

MIT License. See LICENSE for details.