docling-glm-ocr 0.1.0__tar.gz

docling_glm_ocr-0.1.0/.github/workflows/main.yml

@@ -0,0 +1,62 @@
+name: Main
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Quality checks via DCC-BS reusable workflow (ruff lint + format + ty)
+  # ---------------------------------------------------------------------------
+  quality:
+    uses: DCC-BS/ci-workflows/.github/workflows/python-backend-ci.yml@v8
+    with:
+      python_versions: '["3.13"]'
+      quality_python_version: "3.13"
+      check_command: "make check"
+
+  # ---------------------------------------------------------------------------
+  # Tests + coverage
+  # ---------------------------------------------------------------------------
+  tests:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: [quality]
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov --cov-report=xml --junitxml=junit.xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./junit.xml

docling_glm_ocr-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  id-token: write  # required for PyPI trusted publishing
+  contents: write  # required to push git tags
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Create and push git tag
+        run: |
+          VERSION=$(uv version --short)
+          TAG="v${VERSION}"
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          if git rev-parse "$TAG" >/dev/null 2>&1 || git ls-remote --tags origin | grep -q "refs/tags/$TAG"; then
+            echo "Tag $TAG already exists – skipping"
+          else
+            git tag "$TAG"
+            git push origin "$TAG"
+            echo "Created and pushed tag $TAG"
+          fi
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

docling_glm_ocr-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.installed.cfg
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+MANIFEST
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.tox/
+
+# Type checkers
+.mypy_cache/
+.ruff_cache/
+.ty_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Distribution
+*.tar.gz
+*.whl
+
+# Environment variables
+.env
+.env.local

docling_glm_ocr-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v5.0.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: check-json
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.9.9"
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+        types_or: [python, pyi]
+      - id: ruff-format
+        types_or: [python, pyi]

docling_glm_ocr-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

docling_glm_ocr-0.1.0/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.

docling_glm_ocr-0.1.0/Makefile

@@ -0,0 +1,56 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help install check lint format type-check test test-xml build clean-build publish
+
+help: ## Display available commands
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n\nTargets:\n"} \
+	/^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+# ---------------------------------------------------------------------------
+# Setup
+# ---------------------------------------------------------------------------
+
+install: ## Install dependencies and pre-commit hooks
+	uv sync --all-extras --dev
+	uv run pre-commit install
+
+# ---------------------------------------------------------------------------
+# Quality checks
+# ---------------------------------------------------------------------------
+
+lint: ## Run ruff linter (with auto-fix)
+	uv run ruff check . --fix
+
+format: ## Run ruff formatter
+	uv run ruff format .
+
+type-check: ## Run ty type checker
+	uv run ty check src/
+
+check: ## Run all quality checks (lint, format check, type check)
+	uv run ruff check .
+	uv run ruff format --check .
+	uv run ty check src/
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+test: ## Run tests with terminal coverage report
+	uv run pytest
+
+test-xml: ## Run tests and produce XML coverage report only
+	uv run pytest --cov-report=xml --cov-report=
+
+# ---------------------------------------------------------------------------
+# Build & publish
+# ---------------------------------------------------------------------------
+
+build: clean-build ## Build distribution packages
+	uv build
+
+clean-build: ## Remove build artefacts
+	rm -rf dist/ build/ *.egg-info
+
+publish: build ## Publish package to PyPI
+	uv publish

docling_glm_ocr-0.1.0/PKG-INFO

@@ -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