Metadata-Version: 2.4
Name: universal-doc-reader
Version: 0.1.0
Summary: Offline, lightweight layout-agnostic document processing library and CLI
Author-email: NabPrime03 <nabneetpanda003@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/NabPrime03/Universal_Doc_Reader
Project-URL: Repository, https://github.com/NabPrime03/Universal_Doc_Reader
Project-URL: Issues, https://github.com/NabPrime03/Universal_Doc_Reader/issues
Keywords: ocr,document-processing,invoice-parser,receipt-parser,table-extraction,rapidocr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rapidocr-onnxruntime>=1.2.3
Requires-Dist: pillow>=10.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: click>=8.0.0
Requires-Dist: opencv-python-headless>=4.8.0
Provides-Extra: tesseract
Requires-Dist: pytesseract>=0.3.10; extra == "tesseract"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install universal-doc-reader
```

### Install from Source (Development)
```bash
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)

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

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

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

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

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

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

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

```bash
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](LICENSE) for details.
