Document Service (Docling)#

class saia_python.documents.DocumentService(session: requests.Session, base_url: str, *, retry: RetryPolicy | bool | None = None)[source]#

Access the /documents/convert endpoint (Docling).

Converts PDF and other document formats to markdown, HTML, JSON, or token representations.

Parameters:

session – A requests.Session with auth headers configured.
base_url – The SAIA API base URL.

Convert a document using the Docling service.

Parameters:

file_path – Path to the document file (PDF, etc.).
response_type – Output format — "markdown" (default), "html", "json", or "tokens".
extract_tables_as_images – If True, render tables as images instead of structured text.
image_resolution_scale – Image quality multiplier (1–4).

Returns:

A ConversionResult with the converted content and any extracted images.

convert_to_markdown(file_path: str | Path, **kwargs) → str[source]#

Convert a document to markdown (convenience method).

Parameters:

file_path – Path to the document file.
**kwargs – Additional parameters passed to convert().

Returns:

The markdown content as a string.

convert_to_html(file_path: str | Path, **kwargs) → str[source]#

Convert a document to HTML (convenience method).

Parameters:

file_path – Path to the document file.
**kwargs – Additional parameters passed to convert().

Returns:

The HTML content as a string.

class saia_python.documents.ConversionResult(filename: str, response_type: str, content: str, images: list[ConversionImage] = <factory>)[source]#

Result of a document conversion via the Docling service.

Variables:

filename (str) – The original document filename.
response_type (str) – The output format (markdown, html, json, or tokens).
content (str) – The converted content as a string.
images (list[saia_python.documents.ConversionImage]) – The extracted images as ConversionImage objects (decoded bytes + filename). Use save_images() or save_all() to write them to disk.

filename: str#

response_type: str#

content: str#

images: list[ConversionImage]#

save(path: str | Path) → Path[source]#

Save the converted content to a file.

Parameters:: path – Output file path.
Returns:: The path written to.

save_images(directory: str | Path) → list[Path][source]#

Write every extracted image into directory.

Each ConversionImage is written under its filename; decoding already happened at parse time.

Parameters:: directory – Target directory (created if missing).
Returns:: The list of written image paths (empty if there are no images).

save_all(directory: str | Path, *, stem: str | None = None) → list[Path][source]#

Save the content file and all images into directory.

The content is written as <stem>.<ext> where ext is inferred from response_type (markdown → md) and stem defaults to the source filename stem. Images are written via save_images(), so any picture-N.png links in the content resolve next to it.

Parameters:

directory – Target directory (created if missing).
stem – Optional base name for the content file.

Returns:

All written paths, content file first.