docling-glm-ocr 0.1.0__py3-none-any.whl

docling_glm_ocr/__init__.py

@@ -0,0 +1,8 @@
+"""A docling OCR plugin for GLM-OCR."""
+
+__version__ = "0.1.0"
+
+from docling_glm_ocr.model import GlmOcrRemoteModel
+from docling_glm_ocr.options import GlmOcrRemoteOptions
+
+__all__ = ["GlmOcrRemoteModel", "GlmOcrRemoteOptions"]

docling_glm_ocr/model.py

@@ -0,0 +1,159 @@
+"""GLM-OCR remote OCR engine for the docling standard pipeline.
+
+Sends each page crop to a vLLM-hosted GLM-OCR model and returns the
+recognised text as ``TextCell`` objects that docling merges with its
+standard-pipeline output.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+from typing import TYPE_CHECKING
+
+import httpx
+from docling.models.base_ocr_model import BaseOcrModel
+from docling.utils.profiling import TimeRecorder
+from docling_core.types.doc import BoundingBox, CoordOrigin
+from docling_core.types.doc.page import BoundingRectangle, TextCell
+
+from docling_glm_ocr.options import GlmOcrRemoteOptions
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from pathlib import Path
+
+    from docling.datamodel.accelerator_options import AcceleratorOptions
+    from docling.datamodel.base_models import Page
+    from docling.datamodel.document import ConversionResult
+    from docling.datamodel.pipeline_options import OcrOptions
+    from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+def _pil_to_base64_uri(image: Image.Image, fmt: str = "PNG") -> str:
+    buf = io.BytesIO()
+    image.save(buf, format=fmt)
+    b64 = base64.b64encode(buf.getvalue()).decode()
+    return f"data:image/{fmt.lower()};base64,{b64}"
+
+
+class GlmOcrRemoteModel(BaseOcrModel):
+    """OCR engine that delegates recognition to a remote GLM-OCR vLLM server."""
+
+    def __init__(
+        self,
+        *,
+        enabled: bool,
+        artifacts_path: Path | None,
+        options: GlmOcrRemoteOptions,
+        accelerator_options: AcceleratorOptions,
+    ) -> None:
+        super().__init__(
+            enabled=enabled,
+            artifacts_path=artifacts_path,
+            options=options,
+            accelerator_options=accelerator_options,
+        )
+        self.options: GlmOcrRemoteOptions
+        self.scale = 3  # 72 dpi → 216 dpi
+
+        if self.enabled:
+            self._client = httpx.Client(timeout=self.options.timeout)
+            logger.info(
+                "GlmOcrRemoteModel initialised: api_url=%s  model=%s",
+                self.options.api_url,
+                self.options.model_name,
+            )
+
+    def _recognise_crop(self, image: Image.Image) -> str:
+        """Send a single cropped image to the remote GLM-OCR endpoint."""
+        data_uri = _pil_to_base64_uri(image)
+        payload = {
+            "model": self.options.model_name,
+            "max_tokens": self.options.max_tokens,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": self.options.prompt},
+                        {"type": "image_url", "image_url": {"url": data_uri}},
+                    ],
+                }
+            ],
+        }
+        resp = self._client.post(self.options.api_url, json=payload)
+        resp.raise_for_status()
+        choices = resp.json().get("choices", [])
+        if not choices:
+            return ""
+        return choices[0].get("message", {}).get("content", "")
+
+    def __call__(
+        self,
+        conv_res: ConversionResult,
+        page_batch: Iterable[Page],
+    ) -> Iterable[Page]:
+        """Run OCR on each page crop and yield pages with recognised text cells."""
+        if not self.enabled:
+            yield from page_batch
+            return
+
+        for page in page_batch:
+            if page._backend is None or not page._backend.is_valid():  # noqa: SLF001
+                yield page
+                continue
+
+            with TimeRecorder(conv_res, "ocr"):
+                ocr_rects = self.get_ocr_rects(page)
+                all_ocr_cells: list[TextCell] = []
+
+                for cell_idx, ocr_rect in enumerate(ocr_rects):
+                    if ocr_rect.area() == 0:
+                        continue
+
+                    high_res_image = page._backend.get_page_image(  # noqa: SLF001
+                        scale=self.scale,
+                        cropbox=ocr_rect,
+                    )
+
+                    try:
+                        text = self._recognise_crop(high_res_image)
+                    except httpx.HTTPError:
+                        logger.exception("GLM-OCR remote call failed for crop %d", cell_idx)
+                        continue
+
+                    if not text.strip():
+                        continue
+
+                    all_ocr_cells.append(
+                        TextCell(
+                            index=cell_idx,
+                            text=text,
+                            orig=text,
+                            from_ocr=True,
+                            confidence=1.0,
+                            rect=BoundingRectangle.from_bounding_box(
+                                BoundingBox.from_tuple(
+                                    coord=(
+                                        ocr_rect.l,
+                                        ocr_rect.t,
+                                        ocr_rect.r,
+                                        ocr_rect.b,
+                                    ),
+                                    origin=CoordOrigin.TOPLEFT,
+                                )
+                            ),
+                        )
+                    )
+
+                self.post_process_cells(all_ocr_cells, page)
+
+            yield page
+
+    @classmethod
+    def get_options_type(cls) -> type[OcrOptions]:
+        """Return the options class for this OCR engine."""
+        return GlmOcrRemoteOptions

docling_glm_ocr/options.py

@@ -0,0 +1,46 @@
+"""Configuration model for the GLM-OCR remote OCR engine."""
+
+from __future__ import annotations
+
+import os
+from typing import ClassVar, Literal
+
+from docling.datamodel.pipeline_options import OcrOptions
+from pydantic import ConfigDict, Field
+
+
+class GlmOcrRemoteOptions(OcrOptions):
+    """Options for the remote GLM-OCR OCR engine.
+
+    The engine sends each page crop to a vLLM-hosted GLM-OCR model via its
+    OpenAI-compatible chat completion endpoint and returns the recognised text.
+
+    Attributes:
+        api_url: OpenAI-compatible chat completion URL of the vLLM server.
+            Falls back to the ``GLMOCR_REMOTE_OCR_API_URL`` env var, then to
+            a localhost default.
+        model_name: ``model`` parameter sent in the chat completion request.
+        prompt: Text prompt sent alongside each image crop.
+            Falls back to the ``GLMOCR_REMOTE_OCR_PROMPT`` env var.
+        timeout: HTTP request timeout in seconds per crop.
+        max_tokens: Maximum tokens for the chat completion response.
+    """
+
+    kind: ClassVar[Literal["glm-ocr-remote"]] = "glm-ocr-remote"
+
+    lang: list[str] = Field(default_factory=lambda: ["en"])
+    api_url: str = os.environ.get(
+        "GLMOCR_REMOTE_OCR_API_URL",
+        "http://localhost:8001/v1/chat/completions",
+    )
+    model_name: str = "zai-org/GLM-OCR"
+    prompt: str = os.environ.get(
+        "GLMOCR_REMOTE_OCR_PROMPT",
+        """Recognize the text in the image and output in Markdown format.
+      Preserve the original layout (headings/paragraphs/tables/formulas).
+      Do not fabricate content that does not exist in the image.""",
+    )
+    timeout: float = 120
+    max_tokens: int = 16384
+
+    model_config = ConfigDict(extra="forbid")

docling_glm_ocr/plugin.py

@@ -0,0 +1,8 @@
+"""Docling plugin entry point registering the GLM-OCR remote OCR engine."""
+
+from docling_glm_ocr.model import GlmOcrRemoteModel
+
+
+def ocr_engines() -> dict[str, list[type]]:
+    """Return the OCR engine classes provided by this plugin."""
+    return {"ocr_engines": [GlmOcrRemoteModel]}

docling_glm_ocr-0.1.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: docling-glm-ocr
+Version: 0.1.0
+Summary: A docling OCR plugin for GLM-OCR
+Project-URL: Homepage, https://github.com/DCC-BS/docling-glm-ocr
+Project-URL: Repository, https://github.com/DCC-BS/docling-glm-ocr
+Project-URL: Issues, https://github.com/DCC-BS/docling-glm-ocr/issues
+Project-URL: Changelog, https://github.com/DCC-BS/docling-glm-ocr/releases
+Author-email: Yanick Schraner <yanick.schraner@bs.ch>, Tobias Bollinger <tobias.bollinger@bs.ch>
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: docling>=2.73
+Requires-Dist: httpx>=0.27
+Requires-Dist: pillow>=10.0
+Description-Content-Type: text/markdown
+
+# docling-glm-ocr
+
+A docling OCR plugin that delegates text recognition to a remote
+[GLM-OCR](https://huggingface.co/zai-org/GLM-OCR) model served by vLLM.
+
+---
+
+<p align="center">
+  <a href="https://github.com/DCC-BS/docling-glm-ocr">GitHub</a>
+  &nbsp;|&nbsp;
+  <a href="https://pypi.org/project/docling-glm-ocr/">PyPI</a>
+</p>
+
+---
+
+[![PyPI version](https://img.shields.io/pypi/v/docling-glm-ocr.svg)](https://pypi.org/project/docling-glm-ocr/)
+[![Python versions](https://img.shields.io/pypi/pyversions/docling-glm-ocr.svg)](https://pypi.org/project/docling-glm-ocr/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/DCC-BS/docling-glm-ocr/blob/main/LICENSE)
+[![CI](https://github.com/DCC-BS/docling-glm-ocr/actions/workflows/main.yml/badge.svg)](https://github.com/DCC-BS/docling-glm-ocr/actions/workflows/main.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![codecov](https://codecov.io/gh/DCC-BS/docling-glm-ocr/graph/badge.svg?token=LOPIP1UZOC)](https://codecov.io/gh/DCC-BS/docling-glm-ocr)
+
+## Overview
+
+`docling-glm-ocr` is a [docling](https://github.com/DS4SD/docling) plugin that
+replaces the built-in OCR stage with a call to a remote
+[GLM-OCR](https://huggingface.co/zai-org/GLM-OCR) model hosted on a
+[vLLM](https://github.com/vllm-project/vllm) server.
+
+Each page crop is sent to the vLLM OpenAI-compatible chat completion endpoint
+as a base64-encoded image. The model returns Markdown-formatted text which
+docling merges back into the document structure.
+
+The plugin registers itself under the `"glm-ocr-remote"` OCR engine key so it
+can be selected per-request through docling or docling-serve without changing
+application code.
+
+## Requirements
+
+- Python 3.13+
+- A running vLLM server hosting `zai-org/GLM-OCR` (or any compatible model)
+
+## Installation
+
+```bash
+# with uv (recommended)
+uv add docling-glm-ocr
+
+# with pip
+pip install docling-glm-ocr
+```
+
+## Usage
+
+### Python SDK
+
+```python
+from docling.datamodel.base_models import InputFormat
+from docling.datamodel.pipeline_options import PdfPipelineOptions
+from docling.document_converter import DocumentConverter, PdfFormatOption
+
+from docling_glm_ocr import GlmOcrRemoteOptions
+
+pipeline_options = PdfPipelineOptions(
+    allow_external_plugins=True,
+    ocr_options=GlmOcrRemoteOptions(
+        api_url="http://localhost:8001/v1/chat/completions",
+        model_name="zai-org/GLM-OCR",
+    ),
+)
+
+converter = DocumentConverter(
+    format_options={
+        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
+    }
+)
+result = converter.convert("document.pdf")
+print(result.document.export_to_markdown())
+```
+
+### docling-serve
+
+Select the engine per-request via the standard API:
+
+```bash
+curl -X POST http://localhost:5001/v1/convert/source \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "options": {
+      "ocr_engine": "glm-ocr-remote"
+    },
+    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]
+  }'
+```
+
+The server must have `DOCLING_SERVE_ALLOW_EXTERNAL_PLUGINS=true` set so the
+plugin is loaded automatically.
+
+## Configuration
+
+### Environment variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `GLMOCR_REMOTE_OCR_API_URL` | vLLM chat completion URL | `http://localhost:8001/v1/chat/completions` |
+| `GLMOCR_REMOTE_OCR_PROMPT` | Text prompt sent with each image crop | see below |
+
+### `GlmOcrRemoteOptions`
+
+All options can be set programmatically via `GlmOcrRemoteOptions`:
+
+| Option | Type | Description | Default |
+|---|---|---|---|
+| `api_url` | `str` | OpenAI-compatible chat completion URL | `GLMOCR_REMOTE_OCR_API_URL` env or `http://localhost:8001/v1/chat/completions` |
+| `model_name` | `str` | Model name sent to vLLM | `zai-org/GLM-OCR` |
+| `prompt` | `str` | Text prompt for each image crop | `GLMOCR_REMOTE_OCR_PROMPT` env or default prompt |
+| `timeout` | `float` | HTTP timeout per crop (seconds) | `120` |
+| `max_tokens` | `int` | Max tokens per completion | `16384` |
+| `lang` | `list[str]` | Language hint (passed to docling) | `["en"]` |
+
+Default prompt:
+
+```
+Recognize the text in the image and output in Markdown format.
+Preserve the original layout (headings/paragraphs/tables/formulas).
+Do not fabricate content that does not exist in the image.
+```
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph docling
+        Pipeline --> GlmOcrRemoteModel
+    end
+
+    subgraph vLLM
+        GLMOCR["zai-org/GLM-OCR"]
+    end
+
+    GlmOcrRemoteModel -- "POST /v1/chat/completions\n(base64 image)" --> GLMOCR
+    GLMOCR -- "Markdown text" --> GlmOcrRemoteModel
+```
+
+For each page the model:
+1. Collects OCR regions from the docling layout analysis
+2. Renders each region at 3× scale (216 dpi) using the page backend
+3. Encodes the crop as a base64 PNG data URI
+4. POSTs a chat completion request to the vLLM endpoint
+5. Returns the recognised text as `TextCell` objects for docling to merge
+
+## Starting a GLM-OCR vLLM server
+
+```bash
+docker run -d \
+  --rm --name ocr-glm \
+  --gpus device=0 \
+  --ipc=host \
+  -p 8001:8000 \
+  -v "${HOME}/.cache/huggingface:/root/.cache/huggingface" \
+  -e "HF_TOKEN=${HF_TOKEN}" \
+  --entrypoint /bin/bash \
+  vllm/vllm-openai:latest \
+  -c "uv pip install --system --upgrade transformers && \
+      exec vllm serve zai-org/GLM-OCR \
+        --served-model-name zai-org/GLM-OCR \
+        --port 8000 \
+        --trust-remote-code"
+```
+
+The plugin will connect to `http://localhost:8001/v1/chat/completions` by default.
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/DCC-BS/docling-glm-ocr.git
+cd docling-glm-ocr
+make install
+```
+
+### Available commands
+
+```
+make install     Install dependencies and pre-commit hooks
+make check       Run all quality checks (ruff lint, format, ty type check)
+make test        Run tests with coverage report
+make build       Build distribution packages
+make publish     Publish to PyPI
+```
+
+### Running tests
+
+```bash
+make test
+```
+
+Tests are in `tests/` and use [pytest](https://pytest.org).
+Coverage reports are generated at `coverage.xml` and printed to the terminal.
+
+#### End-to-end tests
+
+The e2e tests hit a real vLLM server and are **skipped by default**.
+To run them, set the server URL and use the `e2e` marker:
+
+```bash
+GLMOCR_REMOTE_OCR_API_URL=http://localhost:8001/v1/chat/completions pytest -m e2e
+```
+
+### Code quality
+
+This project uses:
+
+- **[ruff](https://github.com/astral-sh/ruff)** – linting and formatting
+- **[ty](https://github.com/astral-sh/ty)** – type checking
+- **[pre-commit](https://pre-commit.com/)** – pre-commit hooks
+
+Run all checks:
+
+```bash
+make check
+```
+
+### Releasing
+
+Releases are published to PyPI automatically.
+Update the version in `pyproject.toml`, then trigger the **Publish** workflow from GitHub Actions:
+
+```
+GitHub → Actions → Publish to PyPI → Run workflow
+```
+
+The workflow tags the commit, builds the package, and publishes to PyPI via trusted publishing.
+
+## License
+
+[MIT](LICENSE) © Data Competence Center Basel-Stadt

docling_glm_ocr-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+docling_glm_ocr/__init__.py,sha256=vu6BnFv3j7UPZX4sPxxNHyYZhh_eZggSzONFNvRAcLM,228
+docling_glm_ocr/model.py,sha256=XlnqbPMOljLKxn9UR6qe5oaYqaQW-r1MUsALcbuyhqg,5470
+docling_glm_ocr/options.py,sha256=wDIQWfUeck3n6t8uILp-e0UMh5IjzFYDTHhxjeHkG-g,1724
+docling_glm_ocr/plugin.py,sha256=QsILIweZ1mr-n3SjdNbKi98sjJFcDbCSWfNAhhW77Ww,288
+docling_glm_ocr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docling_glm_ocr-0.1.0.dist-info/METADATA,sha256=4rdsiNTZMY8gq68Xi35GR-tann-nPN01b9-Wi7KqR9c,8025
+docling_glm_ocr-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+docling_glm_ocr-0.1.0.dist-info/entry_points.txt,sha256=jLx9L5LwAeV8eolH8xufrZuKbnnnmUIWUxMMdxeiVFM,51
+docling_glm_ocr-0.1.0.dist-info/licenses/LICENSE,sha256=APpdFXym3_5C78pFAfnlLvmP7umPBWYpQ2MKidnoRuw,1091
+docling_glm_ocr-0.1.0.dist-info/RECORD,,

docling_glm_ocr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

docling_glm_ocr-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[docling]
+docling_glm_ocr = docling_glm_ocr.plugin

docling_glm_ocr-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Data Competence Center Basel-Stadt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.