IO API Reference

Multi-backend document-to-Markdown converter.

Supports concurrent chunk dispatch across multiple backend groups with overflow/fallback strategies, rate-limit handling, and batch processing.

Example::

with MarkdownConverter(mode="gpu") as conv:
    md = conv.convert("document.pdf")

with MarkdownConverter(
    mode="api",
    monkey_endpoints=["http://s1:8000"],
    glm_api_keys=["key1"],
) as conv:
    results = conv.convert_batch(["a.pdf", "b.pdf"])

__init__(config=None, **overrides)

Initialize converter.

Parameters:

Name	Type	Description	Default
config	ConverterConfig | None	Configuration object. If None, built from overrides.	None
**overrides	Any	Override config fields (convenience shorthand).	{}

convert(path, *, start_page=None, end_page=None)

Convert a single file to Markdown.

Parameters:

Name	Type	Description	Default
path	str | Path	Document file path (.pdf, .doc, .docx).	required
start_page	int | None	PDF start page (1-based, inclusive).	None
end_page	int | None	PDF end page (1-based, inclusive).	None

Returns: Markdown text. Raises: OSError: File not found, unsupported format, or backend failure.

convert_batch(paths, *, on_complete=None)

Batch-convert multiple files.

Parameters:

Name	Type	Description	Default
paths	Sequence[str | Path]	File path list.	required
on_complete	Callable[[str, str | Exception], None] | None	Per-file completion callback. Signature: (path_str, markdown_or_exception) -> None. Exceptions raised inside the callback are caught and logged.	None

Returns: {path_str: markdown} dict. Failed files are omitted. Raises: OcrBackendError: If on_complete is None and any file failed.

close()

Release thread pool. Safe to call multiple times.

Configuration for MarkdownConverter.

Attributes:

Name	Type	Description
mode	Literal['api', 'gpu']	"api" (remote OCR backends) or "gpu" (local MinerU).
dispatch	Literal['overflow', 'fallback']	"overflow" (fill primary, spill) or "fallback" (degrade on failure).
api_backends	list[str]	Ordered backend priority list for API mode.
concurrency_per_group	dict[str, int]	Per-backend per-group concurrency limit.
max_failures	dict[str, int]	Per-backend max consecutive failures before fallback degrades.
chunk_pages	int	Pages per PDF chunk.
overlap_pages	int	Overlapping pages between adjacent chunks.
chunk_strategy	Literal['file_first', 'interleave']	"file_first" (sequential files) or "interleave" (mixed chunks).
gpu_backend	str	GPU backend name.
gpu_concurrency_per_group	int	Concurrent files per GPU group.
gpu_groups	int	Number of GPU groups.
html_table	Literal['keep', 'to_markdown']	"keep" raw HTML or "to_markdown" for simple tables.
timeout	int	Per-request HTTP timeout in seconds.
retries	int	Max retry count (total attempts = retries + 1).
retry_base_delay	float	First retry delay in seconds.
retry_multiplier	float	Exponential backoff multiplier.
failure_threshold	int	Consecutive failures per group before cooldown activates.
failure_cooldown_max	float	Maximum cooldown duration in seconds (also all-dead timeout).
glm_api_keys	list[str]	GLM API keys (one per group).
monkey_endpoints	list[str]	MonkeyOCR endpoint URLs.
upload_rate	int | None	MonkeyOCR upload throttle (bytes/sec), None = unlimited.
mineru_urls	list[str]	MinerU instance URLs.

__post_init__()

Validate config and fill defaults from env.

Convert a document to Markdown (simplified entry point).

Default behavior: API mode (GLM + MonkeyOCR). For advanced usage (batch, concurrency, fallback, GPU), use MarkdownConverter.

docx template renderer based on docxtpl.

list_placeholders()

Scan the template for all {{ var }} placeholders and return a sorted, deduplicated list.

render(context, output_path)

Render the template to output_path; deletes any partial output on failure.

The template is reloaded on each render call (DocxTemplate.render is stateful).

Bases: OSError

OCR 后端错误基类。

Attributes:

Name	Type	Description
status_code		HTTP 状态码（如有）。
backend		后端名称（"glm", "monkey", "mineru"）。
group		后端组索引。

Bases: OcrBackendError

HTTP 429 限流错误。