Metadata-Version: 2.4
Name: ocrbridge-core
Version: 3.0.0
Summary: Core interfaces and utilities for OCR Bridge engine packages
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0.0
Provides-Extra: build
Requires-Dist: python-semantic-release>=10.5.2; extra == 'build'
Provides-Extra: dev
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest~=8.0; extra == 'dev'
Requires-Dist: python-semantic-release>=10.5.2; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest~=8.0; extra == 'test'
Description-Content-Type: text/markdown

# OCR Bridge Core

Core interfaces and utilities for OCR Bridge engine packages.

## Overview

`ocrbridge-core` provides the foundational abstract base classes, models, and utilities that all OCR engine packages must implement. This package enables a modular, plugin-based architecture where OCR engines can be dynamically discovered and loaded at runtime.

## Installation

```bash
pip install ocrbridge-core
```

For local development, we recommend using `uv` and the provided `Makefile`.

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed setup instructions.

```bash
# Quick start (requires uv)
make install
make check
```

## Core Components

### OCREngine Base Class

All OCR engines must inherit from `OCREngine` and implement:

- `process(file_path, params)` - Process a document and return HOCR XML
- `name` property - Engine identifier (e.g., 'tesseract', 'easyocr')
- `supported_formats` property - Set of supported file extensions

### OCREngineParams

Base model for engine-specific parameters using Pydantic validation.

### Exceptions

- `OCRBridgeError` - Base exception
- `OCRProcessingError` - Processing failures
- `UnsupportedFormatError` - Unsupported file format
- `EngineNotAvailableError` - Engine not installed/available
- `InvalidParametersError` - Invalid parameters

### HOCR Utilities

Helper functions for HOCR XML parsing, validation, and conversion:

- `parse_hocr()` - Parse and extract HOCR information
- `validate_hocr()` - Validate HOCR structure
- `extract_bbox()` - Extract bounding box coordinates
- `easyocr_to_hocr()` - Convert EasyOCR results to HOCR format

## Implementing a New Engine

See the engine packages for examples:
- `ocrbridge-tesseract` - Simple reference implementation
- `ocrbridge-easyocr` - Deep learning with GPU support
- `ocrbridge-ocrmac` - Platform-specific (macOS only)
