feat(python): add nemo-relay-plugin worker SDK package

Signed-off-by: Will Killian <wkillian@nvidia.com>

Author: willkill07

.github/workflows/ci_check.yml

@@ -84,10 +84,10 @@ jobs:
           cache-bin: false
           save-if: false
 
-      - name: Install cargo-deny
+      - name: Install cargo-deny and just
         uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6
         with:
-          tool: cargo-deny@${{ steps.ci-config.outputs.cargo_deny_version }}
+          tool: cargo-deny@${{ steps.ci-config.outputs.cargo_deny_version }},just@${{ steps.ci-config.outputs.just_version }}
 
       - name: Install cargo-about
         uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6

.github/workflows/ci_python.yml

@@ -268,6 +268,24 @@ jobs:
           path: ${{ env.NEMO_RELAY_CI_WORKSPACE_TMP }}/wheels/*.whl
           if-no-files-found: error
 
+      - name: Package Python plugin SDK wheel
+        if: ${{ matrix.platform == 'linux-amd64' }}
+        working-directory: ${{ env.NEMO_RELAY_CI_WORKSPACE }}
+        run: |
+          set -e
+          just \
+            --set output_dir "${{ env.NEMO_RELAY_CI_WORKSPACE_TMP }}" \
+            --set ref_name "${NEMO_RELAY_PACKAGE_VERSION}" \
+            package-python-plugin
+
+      - name: Upload Python plugin SDK wheel artifact
+        if: ${{ matrix.platform == 'linux-amd64' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: python-plugin-wheel
+          path: ${{ env.NEMO_RELAY_CI_WORKSPACE_TMP }}/plugin-wheels/*.whl
+          if-no-files-found: error
+
       - name: Prune uv cache
         working-directory: ${{ env.NEMO_RELAY_CI_WORKSPACE }}
         run: uv cache prune --ci

.pre-commit-config.yaml

@@ -52,10 +52,16 @@ repos:
     hooks:
       - id: ty
         name: ty (type check)
-        entry: uv run ty check . --exclude docs/** --exclude fern/** --exclude third_party/** --exclude ./examples/** --exclude .cache/** --exclude .claude/**
+        entry: uv run ty check . --extra-search-path python/plugin/src --exclude docs/** --exclude fern/** --exclude third_party/** --exclude ./examples/** --exclude .cache/** --exclude .claude/** --exclude python/plugin/src/nemo_relay_plugin/_proto/**
         language: system
         types: [python]
         pass_filenames: false
+      - id: ty-python-plugin-example
+        name: ty (Python plugin example)
+        entry: uv run ty check examples/python-grpc-worker-plugin/worker.py --extra-search-path python/plugin/src
+        language: system
+        files: '^(examples/python-grpc-worker-plugin/worker\.py|python/plugin/src/nemo_relay_plugin/.*\.py)$'
+        pass_filenames: false
 
   # Documentation — external link validation
   - repo: https://github.com/lycheeverse/lychee.git
@@ -105,6 +111,13 @@ repos:
         files: '^(pyproject\.toml|uv\.lock)$'
         pass_filenames: false
 
+      - id: python-worker-proto-check
+        name: Python worker protobuf stubs are up to date
+        entry: just check-python-worker-proto
+        language: system
+        files: '^(crates/worker-proto/proto/nemo/relay/worker/v1/plugin_worker\.proto|python/plugin/src/nemo_relay_plugin/_proto/plugin_worker_pb2(_grpc)?\.py|justfile)$'
+        pass_filenames: false
+
       - id: node-lockfile-check
         name: package-lock.json is up to date
         entry: bash -c 'npm install --package-lock-only --ignore-scripts --audit=false --fund=false'

ATTRIBUTIONS-Python.md

@@ -54,18 +54,6 @@ component_management:
           threshold: 0.5%
           base: auto
           if_ci_failed: error
-    - component_id: plugin_sdk
-      name: Plugin SDK
-      paths:
-        - "crates/plugin/src"
-        - "crates/worker-proto/src"
-        - "crates/worker/src"
-      statuses:
-        - type: project
-          target: 95%
-          threshold: 0.5%
-          base: auto
-          if_ci_failed: error
     - component_id: shared_types
       name: Shared DTO Types
       paths:
@@ -128,6 +116,20 @@ component_management:
           threshold: 0.5%
           base: auto
           if_ci_failed: error
+    - component_id: plugin_sdk
+      name: Dynamic Plugin SDKs
+      paths:
+        - "crates/types/src"
+        - "crates/plugin/src"
+        - "crates/worker-proto/src"
+        - "crates/worker/src"
+        - "python/plugin/src/nemo_relay_plugin"
+      statuses:
+        - type: project
+          target: 95%
+          threshold: 0.5%
+          base: auto
+          if_ci_failed: error
 
 comment:
   after_n_builds: 22
@@ -157,6 +159,7 @@ ignore:
   - "target/"
   - "**/*.d.ts"
   - "**/*.pyi"
+  - "python/plugin/src/nemo_relay_plugin/_proto/**"
   - "python/nemo_relay/lib_native*.dylib.dSYM/**"
   # WebAssembly Rust wrappers are covered through wasm-pack execution and
   # reported through generated package JavaScript coverage.

codecov.yml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+nemo/

examples/python-grpc-worker-plugin/.gitignore

@@ -0,0 +1,50 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Python gRPC Worker Plugin
+
+This example shows a Python worker plugin using the `nemo-relay-plugin` SDK. It
+registers a tool request intercept, emits a mark event through the host runtime,
+and returns a mutated JSON tool request.
+
+## Set Up
+
+From this directory:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ../../python/plugin -e .
+```
+
+The SDK package owns the generated protobuf stubs and gRPC server setup.
+
+## Register With Relay
+
+Point the CLI at this manifest and enable it:
+
+```bash
+nemo-relay plugins add ./relay-plugin.toml
+nemo-relay plugins enable examples.python_grpc_worker
+```
+
+When launching the gateway, point Relay at the Python interpreter that has
+`grpcio` installed:
+
+```bash
+NEMO_RELAY_PYTHON="$PWD/.venv/bin/python" nemo-relay gateway
+```
+
+You can also reference the manifest manually from `plugins.toml`:
+
+```toml
+[[plugins.dynamic]]
+manifest = "./examples/python-grpc-worker-plugin/relay-plugin.toml"
+config = { tag = "demo" }
+```
+
+The worker process is started by Relay. Do not run `worker.py` directly unless
+you also provide the worker socket, host socket, activation ID, plugin ID, and
+activation token environment variables that Relay normally supplies.

examples/python-grpc-worker-plugin/README.md

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nemo-relay-python-grpc-worker-example"
+version = "0.1.0"
+description = "Example Python gRPC worker plugin for NeMo Relay"
+requires-python = ">=3.11"
+dependencies = [
+  "nemo-relay-plugin>=0.5.0",
+]
+
+[tool.setuptools]
+py-modules = ["worker"]

examples/python-grpc-worker-plugin/pyproject.toml

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+manifest_version = 1
+
+[plugin]
+id = "examples.python_grpc_worker"
+kind = "worker"
+
+[compat]
+relay = ">=0.5,<1.0"
+worker_protocol = "grpc-v1"
+
+[defaults]
+enabled = false
+
+[capabilities]
+items = ["plugin_worker"]
+
+[load]
+runtime = "python"
+entrypoint = "worker:main"

examples/python-grpc-worker-plugin/relay-plugin.toml

@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Example Python worker plugin using the nemo-relay-plugin SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from nemo_relay_plugin import ConfigDiagnostic, DiagnosticLevel, Json, PluginContext, WorkerPlugin, serve_plugin
+
+
+class ExamplePythonWorker(WorkerPlugin):
+    """Small worker plugin that tags tool request JSON and emits a host mark."""
+
+    plugin_id = "examples.python_grpc_worker"
+
+    def validate(self, config: Json) -> list[ConfigDiagnostic | dict[str, Any]]:
+        if isinstance(config, dict) and config.get("reject") is True:
+            return [
+                ConfigDiagnostic(
+                    level=DiagnosticLevel.ERROR,
+                    code="examples.python_grpc_worker.rejected",
+                    component=self.plugin_id,
+                    field="reject",
+                    message="Python gRPC worker rejection requested",
+                )
+            ]
+        if isinstance(config, dict) and "tag" in config and not isinstance(config["tag"], str):
+            return [
+                ConfigDiagnostic(
+                    level=DiagnosticLevel.ERROR,
+                    code="examples.python_grpc_worker.invalid_tag",
+                    component=self.plugin_id,
+                    field="tag",
+                    message="tag must be a string",
+                )
+            ]
+        return []
+
+    def register(self, ctx: PluginContext, config: Json) -> None:
+        tag = config.get("tag", "python_grpc_worker") if isinstance(config, dict) else "python_grpc_worker"
+
+        async def tag_tool_request(tool_name: str, args: Json) -> Json:
+            tagged_args = _tag_json(args, tag)
+            await ctx.runtime.emit_mark(
+                "examples.python_grpc_worker.tool_request",
+                {"tool_name": tool_name, "source": "python-grpc-worker", "tag": tag},
+            )
+            return tagged_args
+
+        ctx.register_tool_request_intercept("tag_tool_request", tag_tool_request)
+
+
+def _tag_json(value: Json, tag: str) -> Json:
+    if not isinstance(value, dict):
+        raise TypeError("configured tool request tagging requires a JSON object")
+    if tag in value:
+        raise ValueError(f"tool request already contains configured tag {tag!r}")
+    return {**value, tag: True}
+
+
+async def main() -> None:
+    """Entrypoint referenced by relay-plugin.toml."""
+    await serve_plugin(ExamplePythonWorker())
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())