Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

feat(sdk): expose top-level lazy exports and document SDK entry

jinzhenj635e98d0ee2f
diff --git a/README.md b/README.md
index 031e4022..f6817ae6 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,32 @@ mineru-kit parse document.pdf -o document.md --tier standard
mineru-kit webui
```
+### Python SDK
+
+`DoclibClient` drives the local document library from Python. Start the server first (`mineru server start`), then:
+
+```python
+import time
+
+from mineru import DoclibClient
+from mineru.doclib import ParseRequest
+
+client = DoclibClient()
+submit = client.ensure_parse(ParseRequest(path="paper.pdf", tier="standard"))
+
+# ensure_parse returns immediately; poll the parse tasks it created.
+for parse_id in submit.wait_parse_ids:
+ while client.get_parse(parse_id).status != "done":
+ time.sleep(1)
+
+content = client.read_content(f"doc:{submit.short_id}/tier:standard/page:1")
+print(content.content)
+```
+
+`DoclibClient` also covers search, watched directories, locators for
+page/block continuation, and result invalidation — see
+`help(DoclibClient)` or the [SDK and API guide](https://opendatalab.github.io/MinerU/usage/sdk_api/).
+
The default install works out of the box: small models run ONNX CPU inference and the VLM runs llama.cpp in Vulkan mode, which offers good compatibility on the vast majority of devices. If the device has an NVIDIA GPU, install `mineru[full]>=4.0` for the best throughput. Note that on Windows the GPU build of torch must be installed separately, while on macOS the default install is already the best-throughput package and `[full]` is not needed. On other non-NVIDIA devices, you need to install an accelerated build of torch plus vllm/lmdeploy yourself to get the best inference speed and throughput.
For the document library and agent reading, use `mineru parse document.pdf --json`. It defaults to the first 10 PDF pages; continue with returned locators. Stateless `mineru-kit parse` defaults to all pages.
diff --git a/mineru/__init__.py b/mineru/__init__.py
index f65e9251..4bac4967 100644
--- a/mineru/__init__.py
+++ b/mineru/__init__.py
@@ -1,5 +1,12 @@
# Copyright (c) Opendatalab. All rights reserved.
-"""MinerU Analyze 与严格 Model/Middle JSON 的最小公开入口。"""
+"""MinerU 公开入口:文档类型即时导入,解析 API 与 SDK 客户端惰性导出。
+
+类型(Block/PageInfo/...)保持 `import mineru` 即可用且不触发依赖加载;
+解析入口(parse/MinerUParser/...)与 SDK 客户端(DoclibClient)通过 PEP 562
+的显式映射惰性提供,首次访问才导入对应子包(如 mineru.parser、mineru.doclib)。
+"""
+
+from typing import TYPE_CHECKING, Any as _Any
from .types import (
Block,
@@ -13,14 +20,52 @@ from .types import (
TextSpan,
)
+if TYPE_CHECKING:
+ from .doclib import DoclibClient
+ from .parser import DocumentParser, MinerUApiParser, MinerUParser, ParseResult, parse, parse_async
+
__all__ = [
"Block",
"CodeInlineSpan",
+ "DoclibClient",
+ "DocumentParser",
"EquationInlineSpan",
"HyperlinkSpan",
"InlineSpan",
"MiddleJson",
+ "MinerUApiParser",
+ "MinerUParser",
"ModelJson",
"PageInfo",
+ "ParseResult",
"TextSpan",
+ "parse",
+ "parse_async",
]
+
+# PEP 562 惰性导出的显式映射:名字 -> mineru 包内子模块。静态可查,
+# 新增导出时在此登记,不要在模块体顶部直接 import 以免引入重依赖。
+_LAZY_EXPORTS: dict[str, str] = {
+ "DoclibClient": "doclib",
+ "DocumentParser": "parser",
+ "MinerUApiParser": "parser",
+ "MinerUParser": "parser",
+ "ParseResult": "parser",
+ "parse": "parser",
+ "parse_async": "parser",
+}
+
+
+def __getattr__(name: str) -> _Any:
+ module = _LAZY_EXPORTS.get(name)
+ if module is None:
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+ import importlib
+
+ value = getattr(importlib.import_module(f".{module}", package=__name__), name)
+ globals()[name] = value
+ return value
+
+
+def __dir__() -> list[str]:
+ return sorted({*globals(), *_LAZY_EXPORTS})
diff --git a/mineru/doclib/__init__.py b/mineru/doclib/__init__.py
index 28ad3e3b..5f365130 100644
--- a/mineru/doclib/__init__.py
+++ b/mineru/doclib/__init__.py
@@ -1,3 +1,41 @@
-"""The local MinerU document library."""
+# Copyright (c) Opendatalab. All rights reserved.
+"""The local MinerU document library: public SDK entry points.
-__all__: list[str] = []
+`DoclibClient` talks to the local MinerU server (start it with
+`mineru server start`); the request/response models here are the stable
+SDK surface. Less common types stay in `mineru.doclib.types`.
+"""
+
+from __future__ import annotations
+
+from .base import DoclibInterface
+from .client import DoclibClient
+from .types import (
+ DocContentResponse,
+ DocInfo,
+ FindResponse,
+ ListDocsResponse,
+ ParseInfo,
+ ParseRequest,
+ ParseResponse,
+ ParseStatus,
+ ScanInfo,
+ ScanRequest,
+ SearchResponse,
+)
+
+__all__ = [
+ "DocContentResponse",
+ "DocInfo",
+ "DoclibClient",
+ "DoclibInterface",
+ "FindResponse",
+ "ListDocsResponse",
+ "ParseInfo",
+ "ParseRequest",
+ "ParseResponse",
+ "ParseStatus",
+ "ScanInfo",
+ "ScanRequest",
+ "SearchResponse",
+]
diff --git a/tests/unittest/test_sdk_exports.py b/tests/unittest/test_sdk_exports.py
new file mode 100644
index 00000000..14b27d55
--- /dev/null
+++ b/tests/unittest/test_sdk_exports.py
@@ -0,0 +1,53 @@
+# Copyright (c) Opendatalab. All rights reserved.
+"""SDK 入口契约:顶层惰性导出与 doclib 公共面。"""
+
+import subprocess
+import sys
+
+import pytest
+
+import mineru
+
+
+LAZY_PARSER_EXPORTS = ("DocumentParser", "MinerUApiParser", "MinerUParser", "ParseResult", "parse", "parse_async")
+
+
[email protected]("name", LAZY_PARSER_EXPORTS)
+def test_top_level_parser_exports_resolve_to_parser_package(name: str) -> None:
+ """顶层解析 API 惰性导出解析到 mineru.parser 的同一符号。"""
+ import mineru.parser
+
+ assert getattr(mineru, name) is getattr(mineru.parser, name)
+
+
+def test_top_level_doclib_client_is_lazy_and_correct() -> None:
+ """mineru.DoclibClient 经惰性映射解析到 doclib.client 的同一个类。"""
+ from mineru.doclib.client import DoclibClient
+
+ assert mineru.DoclibClient is DoclibClient
+ # 首次访问后缓存进 globals,二次访问是同一个对象。
+ assert mineru.DoclibClient is mineru.DoclibClient
+
+
+def test_dir_includes_lazy_exports() -> None:
+ assert "DoclibClient" in dir(mineru)
+
+
+def test_lazy_name_raises_attribute_error() -> None:
+ with pytest.raises(AttributeError):
+ mineru.NotARealExport # noqa: B018
+
+
+def test_import_mineru_stays_dependency_free() -> None:
+ """`import mineru` 不得拉起 httpx/doclib 等依赖(惰性导出的核心约束)。"""
+ code = "import mineru, sys; assert 'httpx' not in sys.modules, 'import mineru pulled httpx'"
+ result = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, check=False)
+ assert result.returncode == 0, result.stderr
+
+
+def test_doclib_exports_are_importable() -> None:
+ """doclib 公共面的每个 __all__ 名字都可导入。"""
+ from mineru import doclib
+
+ for name in doclib.__all__:
+ assert getattr(doclib, name) is not None