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

.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/nemo_relay_python_grpc_worker_example --extra-search-path python/plugin/src
+        language: system
+        files: '^(examples/python-grpc-worker-plugin/nemo_relay_python_grpc_worker_example/.*\.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'

codecov.yml

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

crates/cli/Cargo.toml

@@ -25,7 +25,7 @@ default = ["atof-streaming"]
 atof-streaming = ["nemo-relay/atof-streaming"]
 
 [dependencies]
-nemo-relay = { workspace = true, features = ["guardrails-remote", "object-store", "openinference"] }
+nemo-relay = { workspace = true, features = ["guardrails-remote", "object-store", "openinference", "worker-grpc"] }
 nemo-relay-adaptive = { workspace = true, features = ["redis-backend"] }
 nemo-relay-pii-redaction.workspace = true
 async-stream = "0.3"

crates/cli/src/server.rs

@@ -10,7 +10,8 @@ use axum::http::HeaderMap;
 use axum::routing::{get, post};
 use axum::{Json, Router};
 use nemo_relay::plugin::dynamic::{
-    DynamicPluginKind, NativePluginActivation, NativePluginLoadSpec, load_native_plugins,
+    DynamicPluginKind, NativePluginActivation, NativePluginLoadSpec, WorkerPluginActivation,
+    WorkerPluginLoadSpec, load_native_plugins, load_worker_plugins,
 };
 use nemo_relay::plugin::{
     PluginComponentSpec, PluginConfig, clear_plugin_configuration, initialize_plugins_exact,
@@ -216,6 +217,7 @@ async fn idle_shutdown_future(
 struct PluginActivation {
     active: bool,
     native: Option<NativePluginActivation>,
+    worker: Option<WorkerPluginActivation>,
 }
 
 impl PluginActivation {
@@ -227,6 +229,7 @@ impl PluginActivation {
             return Ok(Self {
                 active: false,
                 native: None,
+                worker: None,
             });
         };
         register_adaptive_component().map_err(|error| {
@@ -251,6 +254,23 @@ impl PluginActivation {
                 })
             })
             .collect::<Result<Vec<_>, CliError>>()?;
+        let worker_specs = dynamic_plugins
+            .iter()
+            .filter(|plugin| plugin.kind == DynamicPluginKind::Worker)
+            .map(|plugin| {
+                let manifest_ref = plugin.manifest_ref.clone().ok_or_else(|| {
+                    CliError::Config(format!(
+                        "worker dynamic plugin '{}' has no manifest_ref in lifecycle state",
+                        plugin.plugin_id
+                    ))
+                })?;
+                Ok(WorkerPluginLoadSpec {
+                    plugin_id: plugin.plugin_id.clone(),
+                    manifest_ref,
+                    config: plugin.config.clone(),
+                })
+            })
+            .collect::<Result<Vec<_>, CliError>>()?;
         let native =
             if native_specs.is_empty() {
                 None
@@ -259,6 +279,14 @@ impl PluginActivation {
                     CliError::Config(format!("native plugin load failed: {error}"))
                 })?)
             };
+        let worker =
+            if worker_specs.is_empty() {
+                None
+            } else {
+                Some(load_worker_plugins(worker_specs).map_err(|error| {
+                    CliError::Config(format!("worker plugin load failed: {error}"))
+                })?)
+            };
         // Gateway already resolved its config; activate exactly (no re-discovery).
         let mut plugin_config: PluginConfig = match config {
             Some(config) => serde_json::from_value(config)
@@ -282,6 +310,7 @@ impl PluginActivation {
         Ok(Self {
             active: true,
             native,
+            worker,
         })
     }
 
@@ -295,6 +324,7 @@ impl PluginActivation {
             Ok(())
         };
         self.native.take();
+        self.worker.take();
         result
     }
 }

crates/core/Cargo.toml

@@ -73,9 +73,24 @@ openinference = [
     "dep:wasm-bindgen",
     "dep:wasm-bindgen-futures",
 ]
+worker-grpc = [
+    "dep:nemo-relay-worker-proto",
+    "dep:hyper-util",
+    "dep:tower",
+    "dep:tonic",
+    "tokio-stream/net",
+    "tonic/codegen",
+    "tonic/router",
+    "tonic/transport",
+    "tokio/io-util",
+    "tokio/net",
+    "tokio/process",
+    "tokio/rt-multi-thread",
+]
 
 [dependencies]
 nemo-relay-types.workspace = true
+nemo-relay-worker-proto = { workspace = true, optional = true }
 uuid = { workspace = true, features = ["v7", "serde"] }
 serde = { version = "1", features = ["derive", "rc"] }
 serde_json = "1"
@@ -120,6 +135,11 @@ path = "tests/integration/context_isolation_tests.rs"
 name = "native_plugin_integration"
 path = "tests/integration/native_plugin_tests.rs"
 
+[[test]]
+name = "worker_plugin_integration"
+path = "tests/integration/worker_plugin_tests.rs"
+required-features = ["worker-grpc"]
+
 [[test]]
 name = "middleware_integration"
 path = "tests/integration/middleware_tests.rs"
@@ -163,3 +183,5 @@ rustls = { version = "0.23", default-features = false, features = ["ring", "std"
 tonic = { version = "0.14.1", default-features = false, optional = true }
 object_store = { version = "0.13", default-features = false, features = ["aws"], optional = true }
 tokio-tungstenite = { version = "0.27", default-features = false, features = ["connect", "rustls-tls-native-roots"], optional = true }
+tower = { version = "0.5", features = ["util"], optional = true }
+hyper-util = { version = "0.1", features = ["tokio"], optional = true }

crates/core/src/plugin/dynamic.rs

@@ -22,11 +22,15 @@ mod manifest;
 #[cfg(not(target_arch = "wasm32"))]
 mod native;
 mod registry;
+#[cfg(all(feature = "worker-grpc", not(target_arch = "wasm32")))]
+mod worker;
 
 pub use manifest::*;
 #[cfg(not(target_arch = "wasm32"))]
 pub use native::*;
 pub use registry::*;
+#[cfg(all(feature = "worker-grpc", not(target_arch = "wasm32")))]
+pub use worker::*;
 
 /// Plugin execution lane.
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash, Display)]