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

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

Author: willkill07

.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,7 +52,7 @@ 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

ATTRIBUTIONS-Python.md

@@ -106,6 +106,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: 90%
+          threshold: 0.5%
+          base: auto
+          if_ci_failed: error
 
 comment:
   after_n_builds: 22
@@ -135,6 +149,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,56 @@
+# 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 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]:
+        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",
+                )
+            ]
+        return []
+
+    def register(self, ctx: PluginContext, config: Json) -> None:
+        del config
+
+        async def tag_tool_request(tool_name: str, args: Json) -> Json:
+            await ctx.runtime.emit_mark(
+                "examples.python_grpc_worker.tool_request",
+                {"tool_name": tool_name, "source": "python-grpc-worker"},
+            )
+            return _tag_json(args)
+
+        ctx.register_tool_request_intercept("tag_tool_request", tag_tool_request)
+
+
+def _tag_json(value: Json) -> Json:
+    if isinstance(value, dict):
+        return {**value, "python_grpc_worker": True}
+    return {"value": value, "python_grpc_worker": True}
+
+
+async def main() -> None:
+    """Entrypoint referenced by relay-plugin.toml."""
+    await serve_plugin(ExamplePythonWorker())
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())