markitdown-paddleocr 0.1.0__tar.gz

markitdown_paddleocr-0.1.0/.gitignore

@@ -0,0 +1,174 @@
+.vscode
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+.test-logs/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+src/.DS_Store
+.DS_Store
+.cursorrules
+
+# Local secrets (never commit)
+.secrets.local
+*.secrets
+.env.local
+test-data/

markitdown_paddleocr-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: markitdown-paddleocr
+Version: 0.1.0
+Summary: Intelligent PDF/Image to Markdown converter using PaddleOCR cloud API
+Project-URL: Documentation, https://github.com/microsoft/markitdown#readme
+Project-URL: Issues, https://github.com/microsoft/markitdown/issues
+Project-URL: Source, https://github.com/microsoft/markitdown
+Author-email: Contributors <noreply@github.com>
+License-Expression: MIT
+Keywords: baidu,markitdown,ocr,paddleocr,pdf,vision
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: markitdown>=0.1.0
+Requires-Dist: pdfminer-six>=20251230
+Requires-Dist: pdfplumber>=0.11.9
+Requires-Dist: pillow>=9.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# markitdown-paddleocr
+
+智能 PDF/图片转 Markdown 插件，使用百度 PaddleOCR 云端 API 驱动的 OCR 识别。
+
+## 特性
+
+- 🔍 **智能检测**：自动识别每页内容类型（纯文本 vs 图片/表格）
+- 📄 **默认解析**：纯文本页面使用 pdfplumber/pdfminer 提取，速度快、成本低
+- 🤖 **AI 增强**：复杂页面（图片、表格）使用 PaddleOCR API 转换为 Markdown
+- 🔄 **异步 Job 模型**：提交 OCR 任务 → 轮询状态 → 获取结果
+- 📊 **结构化输出**：返回 Markdown（含表格、公式、图表等）
+
+## 安装
+
+```bash
+pip install markitdown-paddleocr
+```
+
+## 配置
+
+### 环境变量（推荐）
+
+```bash
+# 必需：百度 PaddleOCR Token
+export BAIDU_PADDLE_TOKEN="your-paddle-token"
+
+# 可选
+export PADDLE_OCR_MODEL="PaddleOCR-VL-1.5"   # 模型名称
+```
+
+### 配置优先级
+
+```
+构造函数参数 > 环境变量 > 内置默认值
+```
+
+## 使用方法
+
+### 命令行（推荐）
+
+```bash
+# 1. 设置 Token
+export BAIDU_PADDLE_TOKEN="your-token"
+
+# 2. 查看已安装插件
+markitdown --list-plugins
+
+# 3. 使用插件转换 PDF
+markitdown -p document.pdf
+
+# 4. 保存到文件
+markitdown -p document.pdf -o output.md
+```
+
+### Python API
+
+```python
+from markitdown import MarkItDown
+from markitdown_paddleocr import PaddleOcrConverter
+
+# 方式1：自动从环境变量读取 BAIDU_PADDLE_TOKEN
+converter = PaddleOcrConverter()
+md = MarkItDown(enable_plugins=False)
+md.register_converter(converter, priority=-1.0)
+result = md.convert("document.pdf")
+print(result.markdown)
+
+# 方式2：手动传入 Token
+converter = PaddleOcrConverter(token="your-token")
+md = MarkItDown(enable_plugins=False)
+md.register_converter(converter, priority=-1.0)
+result = md.convert("document.pdf")
+print(result.markdown)
+
+# 方式3：强制所有页面使用 OCR
+converter = PaddleOcrConverter(token="your-token", force_ai=True)
+md = MarkItDown(enable_plugins=False)
+md.register_converter(converter, priority=-1.0)
+result = md.convert("document.pdf")
+print(result.markdown)
+```
+
+### 直接使用 PaddleClient
+
+```python
+from markitdown_paddleocr import PaddleClient
+
+client = PaddleClient(token="your-token")
+
+# 本地文件
+markdown = client.ocr(file_bytes=open("image.png", "rb").read(), filename="image.png")
+print(markdown)
+
+# URL 模式
+markdown = client.ocr(file_url="https://example.com/document.pdf")
+print(markdown)
+```
+
+## 配置选项
+
+### PaddleOcrConverter 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `token` | str | 环境变量 `BAIDU_PADDLE_TOKEN` | PaddleOCR Token |
+| `model` | str | `PaddleOCR-VL-1.5` | OCR 模型名称 |
+| `poll_interval` | float | 2.0 | 轮询间隔（秒） |
+| `poll_timeout` | float | 300.0 | 轮询超时（秒） |
+| `force_ai` | bool | False | 强制所有页面使用 OCR |
+| `use_doc_orientation_classify` | bool | False | 文档方向分类 |
+| `use_doc_unwarping` | bool | False | 文档去扭曲 |
+| `use_chart_recognition` | bool | False | 图表识别 |
+
+### 环境变量
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `BAIDU_PADDLE_TOKEN` | Token（必需） | `7963b85a...` |
+| `PADDLE_OCR_MODEL` | 模型名称 | `PaddleOCR-VL-1.5` |
+
+## 工作原理
+
+```
+PDF/图片 输入
+    │
+    ▼
+PaddleOcrConverter.convert()
+    │
+    ├─ 图片文件 ──► PaddleClient.ocr() ──► markdown
+    │
+    └─ PDF 文件 ──► 逐页分析内容类型
+          │
+          ├─ 纯文本页 ──► pdfplumber 提取文本
+          │
+          └─ 复杂页（图片/表格）
+                │
+                └─► 渲染为图片 ──► PaddleClient.ocr()
+                      │
+                      ├─ POST /api/v2/ocr/jobs  (提交 Job)
+                      ├─ GET  /api/v2/ocr/jobs/{id}  (轮询状态)
+                      └─ GET  jsonUrl  (获取 JSONL 结果)
+    │
+    ▼
+合并输出完整 Markdown
+```
+
+## 依赖
+
+- `markitdown>=0.1.0` - 基础框架
+- `pdfplumber>=0.11.9` - PDF 解析和截图
+- `pdfminer.six>=20251230` - 文本提取备用
+- `Pillow>=9.0.0` - 图像处理
+- `requests>=2.28.0` - HTTP 请求
+
+## 许可证
+
+MIT

markitdown_paddleocr-0.1.0/README.md

@@ -0,0 +1,157 @@
+# markitdown-paddleocr
+
+智能 PDF/图片转 Markdown 插件，使用百度 PaddleOCR 云端 API 驱动的 OCR 识别。
+
+## 特性
+
+- 🔍 **智能检测**：自动识别每页内容类型（纯文本 vs 图片/表格）
+- 📄 **默认解析**：纯文本页面使用 pdfplumber/pdfminer 提取，速度快、成本低
+- 🤖 **AI 增强**：复杂页面（图片、表格）使用 PaddleOCR API 转换为 Markdown
+- 🔄 **异步 Job 模型**：提交 OCR 任务 → 轮询状态 → 获取结果
+- 📊 **结构化输出**：返回 Markdown（含表格、公式、图表等）
+
+## 安装
+
+```bash
+pip install markitdown-paddleocr
+```
+
+## 配置
+
+### 环境变量（推荐）
+
+```bash
+# 必需：百度 PaddleOCR Token
+export BAIDU_PADDLE_TOKEN="your-paddle-token"
+
+# 可选
+export PADDLE_OCR_MODEL="PaddleOCR-VL-1.5"   # 模型名称
+```
+
+### 配置优先级
+
+```
+构造函数参数 > 环境变量 > 内置默认值
+```
+
+## 使用方法
+
+### 命令行（推荐）
+
+```bash
+# 1. 设置 Token
+export BAIDU_PADDLE_TOKEN="your-token"
+
+# 2. 查看已安装插件
+markitdown --list-plugins
+
+# 3. 使用插件转换 PDF
+markitdown -p document.pdf
+
+# 4. 保存到文件
+markitdown -p document.pdf -o output.md
+```
+
+### Python API
+
+```python
+from markitdown import MarkItDown
+from markitdown_paddleocr import PaddleOcrConverter
+
+# 方式1：自动从环境变量读取 BAIDU_PADDLE_TOKEN
+converter = PaddleOcrConverter()
+md = MarkItDown(enable_plugins=False)
+md.register_converter(converter, priority=-1.0)
+result = md.convert("document.pdf")
+print(result.markdown)
+
+# 方式2：手动传入 Token
+converter = PaddleOcrConverter(token="your-token")
+md = MarkItDown(enable_plugins=False)
+md.register_converter(converter, priority=-1.0)
+result = md.convert("document.pdf")
+print(result.markdown)
+
+# 方式3：强制所有页面使用 OCR
+converter = PaddleOcrConverter(token="your-token", force_ai=True)
+md = MarkItDown(enable_plugins=False)
+md.register_converter(converter, priority=-1.0)
+result = md.convert("document.pdf")
+print(result.markdown)
+```
+
+### 直接使用 PaddleClient
+
+```python
+from markitdown_paddleocr import PaddleClient
+
+client = PaddleClient(token="your-token")
+
+# 本地文件
+markdown = client.ocr(file_bytes=open("image.png", "rb").read(), filename="image.png")
+print(markdown)
+
+# URL 模式
+markdown = client.ocr(file_url="https://example.com/document.pdf")
+print(markdown)
+```
+
+## 配置选项
+
+### PaddleOcrConverter 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `token` | str | 环境变量 `BAIDU_PADDLE_TOKEN` | PaddleOCR Token |
+| `model` | str | `PaddleOCR-VL-1.5` | OCR 模型名称 |
+| `poll_interval` | float | 2.0 | 轮询间隔（秒） |
+| `poll_timeout` | float | 300.0 | 轮询超时（秒） |
+| `force_ai` | bool | False | 强制所有页面使用 OCR |
+| `use_doc_orientation_classify` | bool | False | 文档方向分类 |
+| `use_doc_unwarping` | bool | False | 文档去扭曲 |
+| `use_chart_recognition` | bool | False | 图表识别 |
+
+### 环境变量
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `BAIDU_PADDLE_TOKEN` | Token（必需） | `7963b85a...` |
+| `PADDLE_OCR_MODEL` | 模型名称 | `PaddleOCR-VL-1.5` |
+
+## 工作原理
+
+```
+PDF/图片 输入
+    │
+    ▼
+PaddleOcrConverter.convert()
+    │
+    ├─ 图片文件 ──► PaddleClient.ocr() ──► markdown
+    │
+    └─ PDF 文件 ──► 逐页分析内容类型
+          │
+          ├─ 纯文本页 ──► pdfplumber 提取文本
+          │
+          └─ 复杂页（图片/表格）
+                │
+                └─► 渲染为图片 ──► PaddleClient.ocr()
+                      │
+                      ├─ POST /api/v2/ocr/jobs  (提交 Job)
+                      ├─ GET  /api/v2/ocr/jobs/{id}  (轮询状态)
+                      └─ GET  jsonUrl  (获取 JSONL 结果)
+    │
+    ▼
+合并输出完整 Markdown
+```
+
+## 依赖
+
+- `markitdown>=0.1.0` - 基础框架
+- `pdfplumber>=0.11.9` - PDF 解析和截图
+- `pdfminer.six>=20251230` - 文本提取备用
+- `Pillow>=9.0.0` - 图像处理
+- `requests>=2.28.0` - HTTP 请求
+
+## 许可证
+
+MIT

markitdown_paddleocr-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "markitdown-paddleocr"
+dynamic = ["version"]
+description = "Intelligent PDF/Image to Markdown converter using PaddleOCR cloud API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["markitdown", "pdf", "ocr", "paddleocr", "baidu", "vision"]
+authors = [
+  { name = "Contributors", email = "noreply@github.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+  "markitdown>=0.1.0",
+  "pdfminer.six>=20251230",
+  "pdfplumber>=0.11.9",
+  "Pillow>=9.0.0",
+  "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/microsoft/markitdown#readme"
+Issues = "https://github.com/microsoft/markitdown/issues"
+Source = "https://github.com/microsoft/markitdown"
+
+[tool.hatch.version]
+path = "src/markitdown_paddleocr/__about__.py"
+
+# Plugin entry point - MarkItDown will discover this plugin
+[project.entry-points."markitdown.plugin"]
+markitdown_paddleocr = "markitdown_paddleocr"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/markitdown_paddleocr"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/markitdown_paddleocr"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

markitdown_paddleocr-0.1.0/src/markitdown_paddleocr/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

markitdown_paddleocr-0.1.0/src/markitdown_paddleocr/__init__.py

@@ -0,0 +1,16 @@
+"""markitdown-paddleocr: PDF/Image to Markdown converter using PaddleOCR cloud API."""
+
+from ._plugin import register_converters
+from ._config import PaddleOcrConfig
+from ._converter import PaddleOcrConverter
+from ._paddle_client import PaddleClient
+from ._dual_converter import DualOcrConverter
+
+__plugin_interface_version__ = 1
+__all__ = [
+    "register_converters",
+    "PaddleOcrConfig",
+    "PaddleOcrConverter",
+    "PaddleClient",
+    "DualOcrConverter",
+]

markitdown_paddleocr-0.1.0/src/markitdown_paddleocr/_config.py

@@ -0,0 +1,46 @@
+"""Configuration for markitdown-paddleocr."""
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class PaddleOcrConfig:
+    """markitdown-paddleocr configuration.
+
+    Configuration priority (high to low):
+    1. Constructor kwargs
+    2. Environment variables
+    3. Built-in defaults
+    """
+
+    # API configuration
+    token: str = ""  # Reads from BAIDU_PADDLE_TOKEN by default
+
+    # OCR model
+    model: str = "PaddleOCR-VL-1.5"
+
+    # API endpoint
+    job_url: str = "https://paddleocr.aistudio-app.com/api/v2/ocr/jobs"
+
+    # Polling configuration
+    poll_interval: float = 2.0  # seconds between polls
+    poll_timeout: float = 300.0  # max seconds to wait for job completion
+
+    # Optional OCR features
+    use_doc_orientation_classify: bool = False
+    use_doc_unwarping: bool = False
+    use_chart_recognition: bool = False
+
+    # Processing strategy
+    force_ai: bool = False
+
+    @classmethod
+    def from_env(cls, **overrides) -> "PaddleOcrConfig":
+        """Create config from environment variables with optional overrides."""
+        defaults = {
+            "token": os.environ.get("BAIDU_PADDLE_TOKEN", ""),
+            "model": os.environ.get("PADDLE_OCR_MODEL", "PaddleOCR-VL-1.5"),
+        }
+        defaults.update(overrides)
+        return cls(**defaults)

markitdown_paddleocr-0.1.0/src/markitdown_paddleocr/_converter.py

@@ -0,0 +1,304 @@
+"""PaddleOcr Converter - PDF/Image to Markdown using PaddleOCR cloud API."""
+
+import io
+import sys
+from typing import Any, BinaryIO, Optional
+
+from markitdown import DocumentConverter, DocumentConverterResult, StreamInfo
+from markitdown._exceptions import MissingDependencyException, MISSING_DEPENDENCY_MESSAGE
+
+from ._config import PaddleOcrConfig
+from ._paddle_client import PaddleClient
+
+# Import PDF dependencies
+_dependency_exc_info = None
+try:
+    import pdfminer
+    import pdfminer.high_level
+    import pdfplumber
+except ImportError:
+    _dependency_exc_info = sys.exc_info()
+
+
+ACCEPTED_MIME_TYPE_PREFIXES = [
+    "application/pdf",
+    "application/x-pdf",
+    "image/jpeg",
+    "image/png",
+]
+
+ACCEPTED_FILE_EXTENSIONS = [".pdf", ".jpg", ".jpeg", ".png"]
+
+
+class PaddleOcrConverter(DocumentConverter):
+    """Intelligent PDF/Image converter using PaddleOCR cloud API.
+
+    Features:
+    - Auto-detect page content type (plain text vs images/tables)
+    - Plain text pages use pdfplumber/pdfminer (fast, free)
+    - Complex pages use PaddleOCR API for AI-powered OCR
+    - Image files (PNG, JPG) use PaddleOCR API directly
+    - Asynchronous job model: submit → poll → fetch result
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        model: str = "PaddleOCR-VL-1.5",
+        poll_interval: float = 2.0,
+        poll_timeout: float = 300.0,
+        force_ai: bool = False,
+        use_doc_orientation_classify: bool = False,
+        use_doc_unwarping: bool = False,
+        use_chart_recognition: bool = False,
+        config: Optional[PaddleOcrConfig] = None,
+    ):
+        """Initialize converter.
+
+        Args:
+            token: Baidu PaddleOCR token (reads from BAIDU_PADDLE_TOKEN env var if not provided)
+            model: OCR model name (default: PaddleOCR-VL-1.5)
+            poll_interval: Seconds between status polls (default: 2.0)
+            poll_timeout: Max seconds to wait for job completion (default: 300.0)
+            force_ai: Force all pages to use OCR (default: False)
+            use_doc_orientation_classify: Enable document orientation classification
+            use_doc_unwarping: Enable document unwarping
+            use_chart_recognition: Enable chart recognition
+            config: Optional PaddleOcrConfig instance
+        """
+        # Build config from explicit params or provided config
+        if config:
+            self.token = token or config.token
+            self.model = model if model != "PaddleOCR-VL-1.5" else config.model
+            self.poll_interval = poll_interval if poll_interval != 2.0 else config.poll_interval
+            self.poll_timeout = poll_timeout if poll_timeout != 300.0 else config.poll_timeout
+            self.force_ai = force_ai or config.force_ai
+            self.use_doc_orientation_classify = use_doc_orientation_classify or config.use_doc_orientation_classify
+            self.use_doc_unwarping = use_doc_unwarping or config.use_doc_unwarping
+            self.use_chart_recognition = use_chart_recognition or config.use_chart_recognition
+        else:
+            self.token = token
+            self.model = model
+            self.poll_interval = poll_interval
+            self.poll_timeout = poll_timeout
+            self.force_ai = force_ai
+            self.use_doc_orientation_classify = use_doc_orientation_classify
+            self.use_doc_unwarping = use_doc_unwarping
+            self.use_chart_recognition = use_chart_recognition
+
+        # Lazy init client
+        self._client: Optional[PaddleClient] = None
+
+    def _get_client(self) -> PaddleClient:
+        """Get or create PaddleClient instance."""
+        if self._client is None:
+            config = PaddleOcrConfig(
+                token=self.token or "",
+                model=self.model,
+                poll_interval=self.poll_interval,
+                poll_timeout=self.poll_timeout,
+                force_ai=self.force_ai,
+                use_doc_orientation_classify=self.use_doc_orientation_classify,
+                use_doc_unwarping=self.use_doc_unwarping,
+                use_chart_recognition=self.use_chart_recognition,
+            )
+            self._client = PaddleClient(config=config)
+        return self._client
+
+    def accepts(
+        self,
+        file_stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> bool:
+        mimetype = (stream_info.mimetype or "").lower()
+        extension = (stream_info.extension or "").lower()
+
+        if extension in ACCEPTED_FILE_EXTENSIONS:
+            return True
+
+        for prefix in ACCEPTED_MIME_TYPE_PREFIXES:
+            if mimetype.startswith(prefix):
+                return True
+
+        return False
+
+    def convert(
+        self,
+        file_stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        if _dependency_exc_info is not None:
+            raise MissingDependencyException(
+                MISSING_DEPENDENCY_MESSAGE.format(
+                    converter=type(self).__name__,
+                    extension=".pdf",
+                    feature="pdf",
+                )
+            ) from _dependency_exc_info[1].with_traceback(
+                _dependency_exc_info[2]
+            )
+
+        extension = (stream_info.extension or "").lower()
+
+        # Image files: use PaddleOCR directly
+        if extension in (".jpg", ".jpeg", ".png"):
+            return self._convert_image(file_stream, extension)
+
+        # PDF files: use hybrid approach
+        return self._convert_pdf(file_stream)
+
+    def _convert_image(self, file_stream: BinaryIO, extension: str = ".png") -> DocumentConverterResult:
+        """Convert image file using PaddleOCR API."""
+        img_bytes = file_stream.read()
+        filename = f"image{extension}"
+
+        try:
+            markdown = self._get_client().ocr(file_bytes=img_bytes, filename=filename)
+            return DocumentConverterResult(markdown=markdown)
+        except Exception as e:
+            return DocumentConverterResult(
+                markdown=f"<!-- Error converting image with PaddleOCR: {e} -->"
+            )
+
+    def _convert_pdf(self, file_stream: BinaryIO) -> DocumentConverterResult:
+        """Convert PDF using hybrid approach (pdfplumber for text, PaddleOCR for complex pages)."""
+        pdf_stream = io.BytesIO(file_stream.read())
+        markdown_parts = []
+
+        try:
+            with pdfplumber.open(pdf_stream) as pdf:
+                for page_num, page in enumerate(pdf.pages):
+                    # Analyze page type
+                    page_type = self._analyze_page(page)
+
+                    # Choose processing method
+                    if self.force_ai or page_type != "plain_text":
+                        # Complex content: use PaddleOCR
+                        markdown = self._convert_with_paddleocr(page, page_num)
+                    else:
+                        # Plain text: use pdfplumber
+                        markdown = self._extract_text_with_tables(page)
+
+                    if markdown.strip():
+                        markdown_parts.append(f"## Page {page_num + 1}\n\n{markdown}")
+
+                    page.close()
+
+            markdown = "\n\n".join(markdown_parts).strip()
+
+        except Exception:
+            # Fallback to pdfminer
+            pdf_stream.seek(0)
+            markdown = pdfminer.high_level.extract_text(pdf_stream) or ""
+
+        # Final fallback
+        if not markdown:
+            pdf_stream.seek(0)
+            markdown = pdfminer.high_level.extract_text(pdf_stream) or ""
+
+        return DocumentConverterResult(markdown=markdown)
+
+    def _analyze_page(self, page: Any) -> str:
+        """Analyze page content type."""
+        # Check for images
+        if hasattr(page, "images") and page.images:
+            return "complex"
+
+        # Check for tables
+        tables = page.find_tables()
+        if tables:
+            return "complex"
+
+        # Check for graphics/curves
+        if hasattr(page, "curves") and page.curves:
+            return "complex"
+
+        return "plain_text"
+
+    def _convert_with_paddleocr(self, page: Any, page_num: int) -> str:
+        """Convert page using PaddleOCR API."""
+        try:
+            # Render page to image
+            img = page.to_image(resolution=150)
+            img_bytes = io.BytesIO()
+            img.save(img_bytes, format="PNG")
+
+            markdown = self._get_client().ocr(
+                file_bytes=img_bytes.getvalue(),
+                filename=f"page_{page_num + 1}.png",
+            )
+            return markdown
+
+        except Exception:
+            # Fallback to pdfplumber text extraction
+            return self._extract_text_with_tables(page)
+
+    def _extract_text_with_tables(self, page: Any) -> str:
+        """Extract text and tables from page."""
+        parts = []
+
+        # Extract text
+        text = page.extract_text() or ""
+        if text.strip():
+            parts.append(text.strip())
+
+        # Extract tables
+        try:
+            tables = page.extract_tables()
+            if tables:
+                for table in tables:
+                    if table:
+                        md_table = self._table_to_markdown(table)
+                        if md_table.strip():
+                            parts.append(md_table)
+        except Exception:
+            pass
+
+        return "\n\n".join(parts)
+
+    def _table_to_markdown(self, table: list[list[str]]) -> str:
+        """Convert table to Markdown."""
+        if not table:
+            return ""
+
+        # Filter None values
+        table = [[cell if cell is not None else "" for cell in row] for row in table]
+
+        # Filter empty rows
+        table = [row for row in table if any(cell.strip() for cell in row)]
+
+        if not table:
+            return ""
+
+        # Calculate column widths
+        col_widths = [
+            max(len(str(row[i])) if i < len(row) else 0 for row in table)
+            for i in range(max(len(row) for row in table))
+        ]
+
+        # Format table
+        lines = []
+        for row_idx, row in enumerate(table):
+            padded_row = row + [""] * (len(col_widths) - len(row))
+            line = "| " + " | ".join(
+                str(cell).ljust(width) for cell, width in zip(padded_row, col_widths)
+            ) + " |"
+            lines.append(line)
+
+            if row_idx == 0:
+                sep = "|" + "|".join("-" * (w + 2) for w in col_widths) + "|"
+                lines.append(sep)
+
+        return "\n".join(lines)
+
+    def close(self):
+        """Close the client."""
+        self._client = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

markitdown_paddleocr-0.1.0/src/markitdown_paddleocr/_dual_converter.py

@@ -0,0 +1,160 @@
+"""DualOcrConverter - glmocr (primary) → paddleocr (fallback) automatic degradation."""
+
+import logging
+from typing import Optional
+
+from markitdown import MarkItDown, DocumentConverter, DocumentConverterResult, StreamInfo
+from typing import BinaryIO, Any
+
+logger = logging.getLogger(__name__)
+
+
+class DualOcrConverter(DocumentConverter):
+    """Dual OCR converter with automatic fallback: glmocr → paddleocr.
+
+    Usage:
+        converter = DualOcrConverter()
+        md = MarkItDown(enable_plugins=False)
+        md.register_converter(converter, priority=-1.0)
+        result = md.convert("document.pdf")
+    """
+
+    def __init__(
+        self,
+        # glmocr kwargs
+        glmocr_api_key: Optional[str] = None,
+        glmocr_timeout: int = 1800,
+        glmocr_enable_layout: bool = False,
+        glmocr_force_ai: bool = False,
+        # paddleocr kwargs
+        paddleocr_token: Optional[str] = None,
+        paddleocr_model: str = "PaddleOCR-VL-1.5",
+        paddleocr_poll_interval: float = 2.0,
+        paddleocr_poll_timeout: float = 300.0,
+        paddleocr_force_ai: bool = False,
+        paddleocr_use_doc_orientation_classify: bool = False,
+        paddleocr_use_doc_unwarping: bool = False,
+        paddleocr_use_chart_recognition: bool = False,
+    ):
+        self.glmocr_kwargs = {
+            "api_key": glmocr_api_key,
+            "timeout": glmocr_timeout,
+            "enable_layout": glmocr_enable_layout,
+            "force_ai": glmocr_force_ai,
+        }
+        self.paddleocr_kwargs = {
+            "token": paddleocr_token,
+            "model": paddleocr_model,
+            "poll_interval": paddleocr_poll_interval,
+            "poll_timeout": paddleocr_poll_timeout,
+            "force_ai": paddleocr_force_ai,
+            "use_doc_orientation_classify": paddleocr_use_doc_orientation_classify,
+            "use_doc_unwarping": paddleocr_use_doc_unwarping,
+            "use_chart_recognition": paddleocr_use_chart_recognition,
+        }
+
+        self._primary = None
+        self._fallback = None
+        self._init_converters()
+
+    def _init_converters(self):
+        """Lazily init both converters."""
+        try:
+            from markitdown_glmocr import GlmOcrConverter
+            # Filter out None values
+            kwargs = {k: v for k, v in self.glmocr_kwargs.items() if v is not None}
+            self._primary = GlmOcrConverter(**kwargs)
+            logger.info("glmocr converter initialized (primary)")
+        except Exception as e:
+            logger.warning("glmocr init failed: %s", e)
+            self._primary = None
+
+        try:
+            from markitdown_paddleocr import PaddleOcrConverter
+            kwargs = {k: v for k, v in self.paddleocr_kwargs.items() if v is not None}
+            self._fallback = PaddleOcrConverter(**kwargs)
+            logger.info("paddleocr converter initialized (fallback)")
+        except Exception as e:
+            logger.warning("paddleocr init failed: %s", e)
+            self._fallback = None
+
+    def accepts(
+        self,
+        file_stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> bool:
+        """Accept if either converter accepts."""
+        if self._primary:
+            try:
+                file_stream.seek(0)
+                if self._primary.accepts(file_stream, stream_info, **kwargs):
+                    return True
+            except Exception:
+                pass
+
+        if self._fallback:
+            try:
+                file_stream.seek(0)
+                if self._fallback.accepts(file_stream, stream_info, **kwargs):
+                    return True
+            except Exception:
+                pass
+
+        return False
+
+    def convert(
+        self,
+        file_stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        """Convert with primary, fallback on failure."""
+        data = file_stream.read()
+
+        # Try primary (glmocr)
+        if self._primary:
+            try:
+                result = self._primary.convert(io_bytes(data), stream_info, **kwargs)
+                if result.markdown and result.markdown.strip():
+                    logger.info("✓ glmocr succeeded")
+                    return result
+                logger.warning("glmocr returned empty result, falling back")
+            except Exception as e:
+                logger.warning("glmocr failed: %s, falling back to paddleocr", e)
+
+        # Fallback (paddleocr)
+        if self._fallback:
+            try:
+                result = self._fallback.convert(io_bytes(data), stream_info, **kwargs)
+                if result.markdown and result.markdown.strip():
+                    logger.info("✓ paddleocr succeeded (fallback)")
+                    return result
+                logger.warning("paddleocr returned empty result")
+            except Exception as e:
+                logger.error("paddleocr also failed: %s", e)
+
+        # Both failed
+        return DocumentConverterResult(
+            markdown="<!-- Both OCR engines (glmocr, paddleocr) failed to convert this file -->"
+        )
+
+    def close(self):
+        if self._primary and hasattr(self._primary, "close"):
+            self._primary.close()
+        if self._fallback and hasattr(self._fallback, "close"):
+            self._fallback.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+
+def io_bytes(data: bytes):
+    """Create a seekable BytesIO from bytes."""
+    import io
+    buf = io.BytesIO(data)
+    buf.seek(0)
+    return buf

markitdown_paddleocr-0.1.0/src/markitdown_paddleocr/_paddle_client.py

@@ -0,0 +1,189 @@
+"""PaddleOCR API Client - handles job submission, polling, and result fetching."""
+
+import json
+import logging
+import time
+from typing import Optional
+
+import requests
+
+from ._config import PaddleOcrConfig
+
+logger = logging.getLogger(__name__)
+
+
+class PaddleOcrError(Exception):
+    """PaddleOCR API error."""
+
+    pass
+
+
+class PaddleClient:
+    """Client for PaddleOCR cloud API.
+
+    Workflow: submit job → poll status → fetch JSONL result → extract markdown.
+    """
+
+    def __init__(self, config: Optional[PaddleOcrConfig] = None, **kwargs):
+        if config is None:
+            config = PaddleOcrConfig(**kwargs)
+        self.config = config
+
+        # Token from config or env
+        self.token = config.token
+        if not self.token:
+            import os
+            self.token = os.environ.get("BAIDU_PADDLE_TOKEN", "")
+
+    def _headers(self) -> dict:
+        """Build authorization headers."""
+        return {"Authorization": f"bearer {self.token}"}
+
+    def _optional_payload(self) -> dict:
+        """Build optional payload flags."""
+        return {
+            "useDocOrientationClassify": self.config.use_doc_orientation_classify,
+            "useDocUnwarping": self.config.use_doc_unwarping,
+            "useChartRecognition": self.config.use_chart_recognition,
+        }
+
+    def ocr(
+        self,
+        file_bytes: Optional[bytes] = None,
+        filename: Optional[str] = None,
+        file_url: Optional[str] = None,
+    ) -> str:
+        """Run OCR on a file or URL, return concatenated markdown.
+
+        Args:
+            file_bytes: File content bytes (for local file upload).
+            filename: Filename for multipart upload (e.g. "page.png").
+            file_url: File URL (for URL mode, alternative to file_bytes).
+
+        Returns:
+            Markdown text extracted from all pages.
+
+        Raises:
+            PaddleOcrError: On API errors or timeout.
+        """
+        # 1. Submit job
+        job_id = self._submit(file_bytes=file_bytes, filename=filename, file_url=file_url)
+        logger.info("Job submitted: %s", job_id)
+
+        # 2. Poll until done
+        result_url = self._poll(job_id)
+        logger.info("Job completed, result URL obtained")
+
+        # 3. Fetch and parse results
+        return self._fetch_markdown(result_url)
+
+    def _submit(
+        self,
+        file_bytes: Optional[bytes] = None,
+        filename: Optional[str] = None,
+        file_url: Optional[str] = None,
+    ) -> str:
+        """Submit an OCR job, return job ID."""
+        headers = self._headers()
+
+        if file_url:
+            # URL mode
+            headers["Content-Type"] = "application/json"
+            payload = {
+                "fileUrl": file_url,
+                "model": self.config.model,
+                "optionalPayload": self._optional_payload(),
+            }
+            resp = requests.post(self.config.job_url, json=payload, headers=headers)
+        elif file_bytes is not None:
+            # Local file mode - multipart upload
+            data = {
+                "model": self.config.model,
+                "optionalPayload": json.dumps(self._optional_payload()),
+            }
+            fname = filename or "document"
+            files = {"file": (fname, file_bytes)}
+            resp = requests.post(self.config.job_url, headers=headers, data=data, files=files)
+        else:
+            raise PaddleOcrError("Either file_bytes or file_url must be provided")
+
+        if resp.status_code != 200:
+            raise PaddleOcrError(f"Submit failed (HTTP {resp.status_code}): {resp.text}")
+
+        result = resp.json()
+        job_id = result.get("data", {}).get("jobId")
+        if not job_id:
+            raise PaddleOcrError(f"No jobId in response: {result}")
+
+        return job_id
+
+    def _poll(self, job_id: str) -> str:
+        """Poll job status until done, return JSONL result URL."""
+        headers = self._headers()
+        url = f"{self.config.job_url}/{job_id}"
+        start = time.time()
+
+        while True:
+            resp = requests.get(url, headers=headers)
+            if resp.status_code != 200:
+                raise PaddleOcrError(f"Poll failed (HTTP {resp.status_code}): {resp.text}")
+
+            data = resp.json().get("data", {})
+            state = data.get("state", "")
+
+            if state == "done":
+                result_url = data.get("resultUrl", {}).get("jsonUrl", "")
+                if not result_url:
+                    raise PaddleOcrError("Job done but no resultUrl in response")
+                return result_url
+
+            if state == "failed":
+                error_msg = data.get("errorMsg", "Unknown error")
+                raise PaddleOcrError(f"Job failed: {error_msg}")
+
+            # Still pending or running
+            if state == "running":
+                progress = data.get("extractProgress", {})
+                total = progress.get("totalPages", "?")
+                extracted = progress.get("extractedPages", "?")
+                logger.debug("Running: %s/%s pages", extracted, total)
+            else:
+                logger.debug("State: %s", state)
+
+            # Check timeout
+            elapsed = time.time() - start
+            if elapsed > self.config.poll_timeout:
+                raise PaddleOcrError(
+                    f"Job polling timed out after {self.config.poll_timeout}s (state={state})"
+                )
+
+            time.sleep(self.config.poll_interval)
+
+    def _fetch_markdown(self, jsonl_url: str) -> str:
+        """Fetch JSONL result and extract markdown from all pages."""
+        resp = requests.get(jsonl_url)
+        resp.raise_for_status()
+
+        markdown_parts = []
+        lines = resp.text.strip().split("\n")
+
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                page_data = json.loads(line)
+            except json.JSONDecodeError:
+                logger.warning("Skipping invalid JSONL line")
+                continue
+
+            result = page_data.get("result", {})
+            layout_results = result.get("layoutParsingResults", [])
+
+            for layout in layout_results:
+                md_text = layout.get("markdown", {}).get("text", "")
+                if md_text.strip():
+                    markdown_parts.append(md_text.strip())
+
+        return "\n\n".join(markdown_parts)

markitdown_paddleocr-0.1.0/src/markitdown_paddleocr/_plugin.py

@@ -0,0 +1,35 @@
+"""Plugin registration for markitdown-paddleocr."""
+
+from typing import Any
+from markitdown import MarkItDown
+
+from ._converter import PaddleOcrConverter
+
+
+__plugin_interface_version__ = 1
+
+
+def register_converters(markitdown: MarkItDown, **kwargs: Any) -> None:
+    """Register markitdown-paddleocr converter.
+
+    Config sources (priority high to low):
+    1. kwargs parameters
+    2. Environment variables (BAIDU_PADDLE_TOKEN)
+    3. Built-in defaults
+    """
+    # Register converter with higher priority than default PDF converter
+    PRIORITY_PADDLEOCR = -1.0
+
+    markitdown.register_converter(
+        PaddleOcrConverter(
+            token=kwargs.get("token"),
+            model=kwargs.get("model", "PaddleOCR-VL-1.5"),
+            poll_interval=kwargs.get("poll_interval", 2.0),
+            poll_timeout=kwargs.get("poll_timeout", 300.0),
+            force_ai=kwargs.get("force_ai", False),
+            use_doc_orientation_classify=kwargs.get("use_doc_orientation_classify", False),
+            use_doc_unwarping=kwargs.get("use_doc_unwarping", False),
+            use_chart_recognition=kwargs.get("use_chart_recognition", False),
+        ),
+        priority=PRIORITY_PADDLEOCR,
+    )