feat: add gRPC server with schema validation and DoclingDocument conversion

Add gRPC service, mapping layer, startup schema validator, and tests
aligned with docling-core protobuf parity.

Signed-off-by: Kristian Rickert <krickert@gmail.com>

Author: krickert

.github/workflows/job-checks.yml

@@ -58,6 +58,40 @@ jobs:
       - name: Create the server
         run: .venv/bin/python -c 'from docling_serve.app import create_app; create_app()'
 
+  grpc-unit-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12']
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --no-extra flash-attn
+      - name: Run gRPC unit tests
+        run: uv run pytest -m unit -k grpc -v
+
+  grpc-integration-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12']
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --no-extra flash-attn
+      - name: Run gRPC integration tests (excluding OCR)
+        run: uv run pytest -m "integration and not ocr" -k grpc -v
+
   # markdown-lint:
   #   runs-on: ubuntu-latest
   #   steps:

.gitignore

@@ -2,6 +2,7 @@ model_artifacts/
 scratch/
 .md-lint
 actionlint
+buf.yaml
 
 # Created by https://www.toptal.com/developers/gitignore/api/python,macos,virtualenv,pycharm,visualstudiocode,emacs,vim,jupyternotebooks
 # Edit at https://www.toptal.com/developers/gitignore?templates=python,macos,virtualenv,pycharm,visualstudiocode,emacs,vim,jupyternotebooks
@@ -133,6 +134,7 @@ Temporary Items
 # Gradle
 .idea/**/gradle.xml
 .idea/**/libraries
+*.iml
 
 # Gradle and Maven with auto-import
 # When using Gradle or Maven with auto-import, you should exclude module files,
@@ -448,4 +450,8 @@ pip-selfcheck.json
 cookies.txt
 
 # Examples
-/examples/splitted_pdf/*
+/examples/splitted_pdf/*
+
+
+# Cursor workspace
+*.code-workspace

CONTRIBUTING.md

@@ -138,6 +138,32 @@ This creates a Virtual Environment with Python 3.10. For other versions, replace
 poetry add NAME
 ```
 
+## Running tests
+
+Tests are organised with pytest markers so you can run exactly the subset you need:
+
+| Marker | What it covers | Typical runtime |
+|---|---|---|
+| `unit` | Mapping logic, fake-orchestrator gRPC tests (no models loaded) | ~2 s |
+| `integration` | Real pipeline end-to-end through the gRPC server | ~60 s+ |
+| `ocr` | Tests that require an OCR engine (easyocr, rapidocr, etc.) | varies |
+
+```bash
+# Fast feedback — unit tests only (no models, no network)
+uv run pytest -m unit -k grpc -v
+
+# Integration tests excluding OCR (avoids OCR model downloads; other models may still download)
+uv run pytest -m "integration and not ocr" -k grpc -v
+
+# Everything, including OCR (requires an OCR extra installed)
+uv run pytest -m integration -k grpc -v
+
+# Run a single test file
+uv run pytest tests/test_grpc_service_fake.py -v
+```
+
+CI runs `unit` and `integration` (excluding `ocr`) as separate jobs so unit failures surface fast.
+
 ## Coding style guidelines
 
 We use the following tools to enforce code style:

Makefile

@@ -173,3 +173,15 @@ run-docling-rocm72: ## Run the docling-serve container with ROCm 7.2 support and
 		-e TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 \
 		-e DOCLING_SERVE_ENABLE_UI=true \
 		ghcr.io/docling-project/docling-serve-rocm72:main
+
+.PHONY: test-grpc-unit
+test-grpc-unit: ## Run gRPC unit tests (no models)
+	$(CMD_PREFIX) uv run pytest -m unit -k grpc -v
+
+.PHONY: test-grpc-integration
+test-grpc-integration: ## Run gRPC integration tests (excludes OCR)
+	$(CMD_PREFIX) uv run pytest -m "integration and not ocr" -k grpc -v
+
+.PHONY: test-grpc-ocr
+test-grpc-ocr: ## Run gRPC OCR integration tests
+	$(CMD_PREFIX) uv run pytest -m "integration and ocr" -k grpc -v

README.md

@@ -37,6 +37,21 @@ The server is available at
 - API documentation <http://127.0.0.1:5001/docs>
 - UI playground <http://127.0.0.1:5001/ui>
 
+### REST and gRPC
+
+Docling Serve can expose a **REST** API (JSON over HTTP, default port **5001**) or a **gRPC** API (Protocol Buffers over HTTP/2, default port **50051**). The two servers are separate processes; use two containers if you need both. gRPC support is **experimental**; see [gRPC documentation](./docs/grpc/README.md).
+
+REST uses JSON and supports `multipart/form-data` file uploads and the web UI when enabled. gRPC uses protobuf messages; file bytes are sent as **base64** in the `FileSource` message (see the [gRPC docs](./docs/grpc/README.md#file-upload-via-filesource)).
+
+Example running **only** the gRPC server in Docker with a local models directory mounted (same layout as in [Handling models](./docs/models.md)):
+
+```bash
+docker run -p 50051:50051 \
+  -v "$(pwd)/models:/opt/app-root/src/models" \
+  -e DOCLING_SERVE_ARTIFACTS_PATH="/opt/app-root/src/models" \
+  quay.io/docling-project/docling-serve -- docling-serve-grpc run --host 0.0.0.0 --port 50051
+```
+
 ![API documentation](img/fastapi-ui.png)
 
 Try it out with a simple conversion:

docling_serve/grpc/__init__.py

@@ -0,0 +1,10 @@
+"""gRPC server support for docling-serve."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_GEN_PATH = Path(__file__).resolve().parent / "gen"
+if _GEN_PATH.exists():
+    sys.path.insert(0, str(_GEN_PATH))

docling_serve/grpc/__main__.py

@@ -0,0 +1,59 @@
+import asyncio
+import logging
+import platform
+import sys
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from docling_serve.settings import docling_serve_settings
+
+from .server import serve
+
+console = Console()
+err_console = Console(stderr=True)
+app = typer.Typer(no_args_is_help=True, rich_markup_mode="rich")
+
+
+@app.command()
+def run(
+    host: Annotated[
+        str,
+        typer.Option(help="Host to bind the gRPC server."),
+    ] = "0.0.0.0",
+    port: Annotated[
+        int,
+        typer.Option(help="Port to bind the gRPC server."),
+    ] = 50051,
+    artifacts_path: Annotated[
+        str | None,
+        typer.Option(
+            help=(
+                "If set to a valid directory, the model weights will be loaded from this path."
+            )
+        ),
+    ] = None,
+) -> None:
+    if artifacts_path:
+        docling_serve_settings.artifacts_path = artifacts_path
+
+    logging.basicConfig(level=logging.INFO)
+    console.print("Starting Docling Serve gRPC server 🚀")
+    console.print(f"Listening on [bold]{host}:{port}[/]")
+    asyncio.run(serve(host=host, port=port))
+
+
+@app.command()
+def version() -> None:
+    console.print(
+        f"Python: {platform.python_version()} ({sys.implementation.cache_tag})"
+    )
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

docling_serve/grpc/docling_document_converter.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import warnings
+
+from docling_core.proto import docling_document_to_proto as docling_document_to_proto
+from docling_core.proto.gen.ai.docling.core.v1 import docling_document_pb2 as pb2
+
+# Re-export for compatibility with existing code in docling-serve
+__all__ = ["docling_document_to_proto", "pb2"]