API reference

Generated from the docstrings in src/obliq_ocr. Everything here can be imported from the top-level package, for example from obliq_ocr import parse_document.

Parsing

parse_document is the main entry point. In the code it is obliq_ocr.core.extract_document, exported under this name.

parse_document

Parse a PDF or image file and return a DocResult.

This is the primary public entrypoint, aliased as parse_document in obliq_ocr.__init__.

Parameters:

Name	Type	Description	Default
path		str or pathlib.Path pointing to the document to parse. Supported formats: PDF, JPEG, PNG, TIFF, BMP, WebP.	required
force_device	Optional[str]	"cpu", "cuda", or None (auto-detect). Overrides the OBLIQ_OCR_DEVICE environment variable.	None
verbose	bool	Print per-page progress to stdout. Default True.	True

Returns:

Type	Description
DocResult	Structured result with one PageResult per page.

Raises:

Type	Description
FileNotFoundError	If path does not exist.
ValueError	If the file is password-protected.

save_result(res, out_dir='outputs')

Write JSON and plain-text files for res to out_dir.

Parameters:

Name	Type	Description	Default
res	DocResult	A DocResult returned by extract_document.	required
out_dir	str	Directory path (created automatically if it does not exist).	'outputs'

Returns:

Type	Description
(json_path, txt_path)	Paths to the saved files.

Results

What parse_document returns. The architecture page explains every field and what confidence means.

DocResult dataclass

Top-level result for a parsed document.

Parameters:

Name	Type	Description	Default
source	str	Base filename of the input document.	required
device	str	"CPU" or "CUDA".	required
pages	List[PageResult]	Ordered list of PageResult objects.	list()

full_text()

Return all pages concatenated with page-number headers.

PageResult dataclass

Per-page extraction result.

Parameters:

Name	Type	Description	Default
page	int	1-indexed page number.	required
method	str	"text_layer", "ocr", or "blank".	required
reason	str	Human-readable triage reason.	required
text	str	Extracted text (reading-order, columns separated by |).	required
n_chars	int	Character count of text.	required
confidence	Optional[float]	Mean OCR confidence in [0, 1], or None for text-layer pages.	required
seconds	float	Wall-clock processing time for this page.	required

OCR engine

detect_device(force=None)

Return True if CUDA should be used for OCR inference.

Parameters:

Name	Type	Description	Default
force	Optional[str]	"cpu" to always use CPU, "cuda" to require GPU, or None (default) for automatic detection.	None

Raises:

Type	Description
RuntimeError	If force="cuda" is requested but CUDA is unavailable.

build_ocr(use_cuda=False)

Instantiate and return a rapidocr_onnxruntime.RapidOCR engine.

Falls back silently to CPU if GPU initialisation fails.

Parameters:

Name	Type	Description	Default
use_cuda	bool	Whether to request CUDA execution providers for all three sub-models (detection, classification, recognition).	False

Returns:

Type	Description
RapidOCR	A configured OCR engine ready for inference.

Schema types

These typed classes are exported, but parse_document doesn't return them yet (#71).

DocumentOutput dataclass

Top-level structured output for a parsed document.

Parameters:

Name	Type	Description	Default
file_name	str	Base name of the source file (no directory path).	required
device	str	Compute device used for OCR: "CPU" or "CUDA".	required
pages	List[PageOutput]	Ordered list of PageOutput objects, one per page.	list()

full_text()

Concatenate all pages into a single string with page headers.

PageOutput dataclass

Structured result for a single page.

Parameters:

Name	Type	Description	Default
page_number	int	1-indexed page number.	required
method	str	How text was extracted: "text_layer", "ocr", or "blank".	required
reason	str	Human-readable explanation of why that method was chosen, e.g. "only 3 text chars" or "garbled text layer (20% junk)".	required
text	str	Full page text, re-assembled into reading order. Column gaps are represented as | so table rows remain readable.	required
elements	List[TextElement]	Individual text regions with bounding boxes and per-element confidence scores. Empty list for blank pages.	list()
confidence	Optional[float]	Mean OCR confidence for the page (None for text-layer pages).	None
processing_seconds	float	Wall-clock time to process this page.	0.0

TextElement dataclass

A single text region (word group / OCR box) on a page.

Parameters:

Name	Type	Description	Default
text	str	Extracted text string.	required
bbox	List[float]	[x0, y0, x1, y1] bounding box (see module docstring for units).	required
confidence	Optional[float]	Model confidence in range [0, 1], or None for text-layer elements where PyMuPDF does not supply a score.	None

BoundingBox dataclass

Axis-aligned bounding box [x0, y0, x1, y1].

as_list()

Return [x0, y0, x1, y1] for JSON serialisation.