Glair Vision Utils

Utility functions for GLAIR Vision OCR API integrations.

This module provides the pieces shared by every GLAIR Vision OCR converter: 1. Credential and configuration validation. 2. The authenticated multipart request, with retries for transient failures. 3. Validation of the response status envelope. 4. Mapping of pixel polygons and table cells into detected objects and HTML.

GLAIRVisionAuth

Bases: BaseModel

Defines the GLAIR Vision OCR API credentials.

Sensitive fields are masked on access and serialization. Use .get_secret_value() only when the raw value is required.

Attributes:

Name	Type	Description
username	str	Basic-auth username for the GLAIR Vision OCR API.
password	SecretStr	Basic-auth password for the GLAIR Vision OCR API (masked on access).
api_key	SecretStr	Value sent as the x-api-key request header (masked on access).

RetryableHTTPError

Bases: HTTPError

Raised for HTTP responses with a transient status (408, 429, or 5xx) that should be retried.

build_glair_vision_detected_object(polygon, width, height, label, class_name, content, confidence, metadata)

Validates a pixel polygon and builds a detected object from it.

Points outside the image are clamped to its edges.

Parameters:

Name	Type	Description	Default
polygon	list[list[float]]	The item's polygon field, expected to be four [x, y] pairs in pixels. Validated at runtime, since it comes from the API response.	required
width	int	The source image width in pixels.	required
height	int	The source image height in pixels.	required
label	str	A description of the item, used for error messages.	required
class_name	str	The kind of detected region.	required
content	str | None	The textual content of the region, or None when it has none.	required
confidence	float | None	Confidence score of the detection, or None when not provided.	required
metadata	dict[str, Any]	Provider-specific attributes of the region.	required

Returns:

Name	Type	Description
DetectedObject	DetectedObject	The detected object with a pixel polygon clamped to the image.

Raises:

Type	Description
ValueError	If polygon is not four finite numeric [x, y] pairs.

glair_vision_table_to_html(cells)

Renders GLAIR Vision table cells as an HTML table.

HTML is used rather than Markdown so merged cells keep their rowspan/colspan. Cells are ordered by (row_index, column_index), header cells render as <th>, and cell values are HTML-escaped. Cells that are not objects or lack non-negative integer indices are skipped.

Parameters:

Name	Type	Description	Default
cells	Any	The table's cells field, expected to be a list of cell objects.	required

Returns:

Name	Type	Description
str	str	The table rendered as HTML.

is_non_negative_int(value)

Checks whether a value is a non-negative integer, excluding booleans.

Parameters:

Name	Type	Description	Default
value	Any	The value to check.	required

Returns:

Name	Type	Description
bool	bool	True if value is a non-negative, non-boolean integer.

parse_glair_vision_polygon(polygon, label)

Parses a four-point pixel polygon into a list of (x, y) points.

Parameters:

Name	Type	Description	Default
polygon	list[list[float]]	The item's polygon field, expected to be four [x, y] pairs. Validated at runtime, since it comes from the API response.	required
label	str	A description of the item, used for error messages.	required

Returns:

Type	Description
list[Point2D]	list[Point2D]: The polygon points in pixels, in API order.

Raises:

Type	Description
ValueError	If polygon is not a list of four finite numeric [x, y] pairs.

send_glair_vision_request(endpoint, auth, files, timeout) async

Sends an authenticated multipart GLAIR Vision OCR request, retrying transient failures.

Connection failures, timeouts, and HTTP 408/429/5xx responses are retried up to MAX_RETRIES times. Other 4xx responses and invalid JSON bodies fail immediately without retrying.

Parameters:

Name	Type	Description	Default
endpoint	str	Full GLAIR Vision OCR endpoint URL.	required
auth	GLAIRVisionAuth	The API credentials.	required
files	dict[str, Any]	The multipart files mapping for requests.post.	required
timeout	int | float	Request timeout in seconds, applied to each attempt.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The parsed JSON response body.

Raises:

Type	Description
RequestException	If the request fails after all retry attempts.
ValueError	If the successful response body is not valid JSON.

validate_glair_vision_config(username, password, api_key, endpoint, timeout)

Validates the credentials, endpoint, and timeout of a GLAIR Vision OCR converter.

Parameters:

Name	Type	Description	Default
username	str	Basic-auth username for the GLAIR Vision OCR API.	required
password	str	Basic-auth password for the GLAIR Vision OCR API.	required
api_key	str	Value sent as the x-api-key request header.	required
endpoint	str	Full GLAIR Vision OCR endpoint URL.	required
timeout	int | float	Request timeout in seconds, applied to each attempt.	required

Raises:

Type	Description
ValueError	If username, password, api_key, or endpoint is blank, or if timeout is not positive.

validate_glair_vision_envelope(response_json)

Validates the response status shared by every GLAIR Vision OCR endpoint and returns its read object.

Parameters:

Name	Type	Description	Default
response_json	Any	The parsed JSON response body.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The response's read object.

Raises:

Type	Description
ValueError	If the response is not a successful object or is missing the read object.