feat: Grpc native converter

[krickert]

This pull request introduces new support and documentation for running and testing the gRPC server in the docling-serve project. The main changes include adding full gRPC compatibility with the docling project.

gRPC-specific test jobs to CI, new Makefile commands for running gRPC tests, improved developer documentation for running tests, and the initial implementation of the gRPC server entrypoint and package structure.

gRPC Server Implementation

• Introduced docling_serve/grpc/__main__.py as the Typer CLI entrypoint for running the gRPC server, with options for host, port, and artifact path, and a version command.
• Created docling_serve/grpc/__init__.py to set up the Python import path for generated gRPC code, ensuring it is importable at runtime.

CI and Testing Improvements

• Added two new GitHub Actions jobs to .github/workflows/job-checks.yml for running gRPC unit and integration tests separately, ensuring faster feedback and clearer test separation.
• Added corresponding Makefile commands: test-grpc-unit, test-grpc-integration, and test-grpc-ocr to easily run gRPC unit, integration, and OCR tests locally.

Developer Documentation

• Updated CONTRIBUTING.md with clear instructions and examples for running different types of tests using pytest markers, including gRPC-specific commands and explanations of what each test suite covers.

[github-actions]

✅ DCO Check Passed

Thanks @krickert, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[dosubot]

Related Documentation

3 document(s) may need updating based on files changed in this PR:

Docling

How can I set up and run docling-serve on a MacBook Pro using Docker, and what performance and stability considerations should I be aware of?

View Suggested Changes

@@ -24,6 +24,26 @@
    - To use more CPU threads for a single document, add `-e DOCLING_NUM_THREADS=4` (or up to your CPU core count).
 
 5. **Access the UI**: Open [http://localhost:5001](http://localhost:5001) in your browser.
+
+**Choosing Between REST and gRPC:**
+
+Docling Serve supports both REST and gRPC protocols. Users can choose the protocol that best fits their application:
+
+- **REST API (default, port 5001)**: Uses JSON over HTTP/1.1. Supports multipart/form-data file uploads and provides a web UI for interactive use. This is the standard option and runs by default when starting the container.
+
+- **gRPC API (port 50051)**: Uses Protocol Buffers over HTTP/2. File uploads use base64 encoding in the `FileSource` message instead of multipart/form-data. gRPC provides server-streaming RPCs for status updates and is suitable for language-agnostic service-to-service communication.
+
+To run the gRPC server instead of REST using Docker:
+```sh
+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
+```
+
+The gRPC and REST servers run independently. If both protocols are needed, run them as separate containers on different ports.
+
+**Note:** gRPC support is experimental. File uploads in gRPC use base64-encoded content in the `FileSource` message rather than multipart/form-data. Refer to the gRPC documentation for details on protobuf schemas and client implementation.
 
 **Performance:**
 - On a modern MacBook Pro (M1/M2, 12 cores, 32GB RAM), expect to process about 5 PDFs (127 pages, 6.2MB total) in roughly 10 minutes (CPU-only). Increasing CPU cores, RAM, or worker count does not significantly improve throughput due to Python's concurrency limitations.

[Accept] [Decline]

How can you mount a PersistentVolumeClaim (PVC) in docling-serve on OpenShift to store EasyOCR models, and what steps are required to ensure docling-serve can access these models?

View Suggested Changes

@@ -1,4 +1,8 @@
-To mount a PVC in docling-serve on OpenShift for EasyOCR models, you need to edit the Deployment manifest directly (there is no Operator-specific CRD for this). Add the PVC as a volume and mount it in the container, then set the `DOCLING_SERVE_ARTIFACTS_PATH` environment variable to the mount path. Here is an example snippet:
+To mount a PVC in docling-serve on OpenShift for EasyOCR models, you need to edit the Deployment manifest directly (there is no Operator-specific CRD for this). Add the PVC as a volume and mount it in the container, then set the `DOCLING_SERVE_ARTIFACTS_PATH` environment variable to the mount path.
+
+**Note:** For the gRPC server, you can also configure the artifacts path using the `--artifacts-path` CLI argument instead of the environment variable. Both methods work with PVC mounts—the path must point to the mounted volume location. The environment variable approach works for both REST and gRPC servers.
+
+Here is an example snippet:
 
 ```yaml
 spec:
@@ -59,6 +63,16 @@
 
 Ensure your EasyOCR models are present in `/modelcache` (or your chosen path) and the directory structure matches what docling expects. If a required model is missing, docling-serve will raise a runtime error. It's recommended to preload models into the PVC using a Kubernetes Job before starting docling-serve. For more details, see the [official docling-serve documentation](https://github.com/docling-project/docling-serve/blob/a179338c785ef9b84696f41b7ab2f2cafe80973d/docs/models.md#L7-L173).
 
+**Example for gRPC server with custom artifacts path:**
+
+If running the gRPC server and using a custom mount path, you can specify it via the CLI:
+
+```sh
+docling-serve-grpc run --artifacts-path /modelcache --host 0.0.0.0 --port 50051
+```
+
+This is equivalent to setting `DOCLING_SERVE_ARTIFACTS_PATH=/modelcache` and works with the same PVC mount configuration shown above.
+
 ## Health probe configuration
 
 The deployment manifest includes health probes to ensure docling-serve is fully ready before accepting traffic:

[Accept] [Decline]

Models handling in Docling Serve

View Suggested Changes

@@ -4,7 +4,29 @@
 With Docling v2.56.x and later, EasyOCR models are now included in the default set of models downloaded by the auto-ocr feature. You no longer need to explicitly request EasyOCR models unless you are customizing the download set.
 
 ## Model Storage Location
-Docling Serve loads models from the directory specified by the `DOCLING_SERVE_ARTIFACTS_PATH` environment variable. This path must be consistent across model download and runtime. When running with multiple workers or reload enabled, you must use the environment variable rather than the CLI argument for configuration [[source]](https://github.com/docling-project/docling-serve/blob/fd1b987e8dc174f1a6013c003dde33e9acbae39a/docling_serve/settings.py).
+Docling Serve loads models from the directory specified by the `DOCLING_SERVE_ARTIFACTS_PATH` environment variable. This path must be consistent across model download and runtime.
+
+### Configuration Options
+
+**Environment Variable (REST and gRPC)**
+
+Set `DOCLING_SERVE_ARTIFACTS_PATH` to configure the artifacts path for both REST and gRPC servers:
+
+```sh
+export DOCLING_SERVE_ARTIFACTS_PATH=/path/to/models
+```
+
+This is the recommended approach for production deployments and is required when running the REST server with multiple workers or reload enabled [[source]](https://github.com/docling-project/docling-serve/blob/fd1b987e8dc174f1a6013c003dde33e9acbae39a/docling_serve/settings.py).
+
+**CLI Argument (gRPC Only)**
+
+When running the gRPC server via `docling-serve-grpc`, you can also configure the artifacts path using the `--artifacts-path` CLI argument:
+
+```sh
+docling-serve-grpc run --artifacts-path /path/to/models --host 0.0.0.0 --port 50051
+```
+
+The CLI argument is specific to the gRPC server entrypoint and provides a convenient way to set the path without environment variables. For REST server deployments with multiple workers or reload enabled, use the environment variable instead.
 
 ## Approaches for Making Extra Models Available
 There are several ways to ensure required models are present:
@@ -197,7 +219,7 @@
 ## Troubleshooting and Best Practices
 - If a required model is missing from the artifacts path, Docling Serve will raise a runtime error.
 - Always ensure the value of `DOCLING_SERVE_ARTIFACTS_PATH` matches the directory where models are stored and mounted.
-- For multi-worker or reload scenarios, use the environment variable, not the CLI argument, to set the artifacts path.
+- For REST server deployments with multiple workers or reload enabled, use the environment variable to set the artifacts path. For gRPC server deployments, you can use either the environment variable or the `--artifacts-path` CLI argument.
 - For production and cluster environments, prefer persistent storage and pre-loading models via a dedicated job.
 - EasyOCR models are now included by default in auto-ocr; explicit inclusion is only needed for custom workflows.
 - Use the `/ready` endpoint for startupProbe and readinessProbe to prevent traffic before models are loaded and dependencies are available.

[Accept] [Decline]

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[krickert]

@dolfim-ibm this is the first attempt at this. It's fully featured now, and this is what I'll run the 768/10K common crawl PDF test against.

I will look into how to move parts of this to the docling-core for the spec and grpc stubs.

[krickert]

This is tied with docling-project/docling-core#546 now - the protobuf definitions and mappers have been moved there while the server functionality is here.