feat: implement nemo_guardrails remote backend (#144)

#### Overview

Adds the first real built-in `nemo_guardrails` remote backend for NeMo Relay core.

This PR moves beyond the contract-only surface and implements the first shippable remote slice:

- built-in plugin auto-registration in core
- remote backend activation for `mode = remote`
- non-streaming and streaming LLM execution through the Guardrails server
- managed `tool_output` execution checks through the same remote backend
- request-default pass-through for remote Guardrails request semantics
- explicit validation that stock remote mode does not currently support managed `tool_input`
- focused runtime validation and coverage for transport, malformed responses, tool rewrites, and error handling

- [x] I confirm this contribution is my own work, or I have the right to submit it under this project's license.
- [x] I searched existing issues and open pull requests, and this does not duplicate existing work.

#### Details

- auto-register the built-in `nemo_guardrails` plugin through `ensure_builtin_plugins_registered()`
- add a dedicated default core feature `guardrails-remote` for the remote backend dependency path
- implement the remote Guardrails runtime across:
  - `crates/core/src/plugins/nemo_guardrails/component.rs`
  - `crates/core/src/plugins/nemo_guardrails/remote.rs`
- support the native remote server contract for `codec = "openai_chat"`
- support both non-streaming and streaming LLM execution
- support remote request defaults pass-through:
  - `context`
  - `thread_id`
  - `state`
  - `rails`
  - `llm_params`
  - `llm_output`
  - `output_vars`
  - `log`
- support managed `tool_output` execution checks via the remote backend
- reject managed `tool_input` in stock remote mode with a focused validation error instead of silently leaving it non-enforcing
- emit coarse backend-level `nemo_guardrails.remote.*` marks for both LLM and managed tool remote checks
- precompute stable remote Guardrails payloads during runtime initialization instead of rebuilding them per request
- split remote runtime coverage into `component_tests.rs` and `remote_tests.rs` to keep contract/config tests separate from transport/runtime behavior
- add focused unit coverage for:
  - built-in registration
  - remote config validation
  - transport and malformed-response lanes
  - non-streaming and streaming remote execution
  - managed `tool_output` blocking and rewrite behavior
  - tool-only config isolation from LLM execution
  - context/state/thread propagation on managed tool checks

Rail and observability boundary in this PR:

- Native NeMo Relay-managed surfaces:
  - `input`
  - `output`
  - `tool_output`
- These are real runtime interception surfaces in NeMo Relay. The built-in plugin installs managed LLM and tool execution behavior around them, and the remote backend can block or rewrite those executions directly.
- Managed `tool_input` remains a known NeMo Relay surface, but stock remote mode now rejects it explicitly because the Guardrails remote contract does not currently activate pre-execution tool-call rails from externally submitted chat-completions history.
- Remote request-time rail pass-through:
  - `request_defaults.rails.input`
  - `request_defaults.rails.output`
  - `request_defaults.rails.retrieval`
  - `request_defaults.rails.dialog`
  - `request_defaults.rails.tool_input`
  - `request_defaults.rails.tool_output`
- These are forwarded to the Guardrails server as remote request semantics. In this PR, `retrieval` and `dialog` are supported this way only: NeMo Relay does not currently expose separate managed retrieval or dialog execution surfaces to intercept locally.
- The remote backend emits coarse backend-level marks:
  - `nemo_guardrails.remote.start`
  - `nemo_guardrails.remote.end`
  - `nemo_guardrails.remote.error`
- These marks cover managed LLM remote execution and managed `tool_output` remote checks. They provide backend-level visibility into remote Guardrails activity without introducing separate NeMo Relay-native retrieval or dialog scopes in this slice.

Intentional PR2 boundary:

- native remote support is `openai_chat` only
- local backend is still not implemented
- stock remote mode supports managed `tool_output` but not managed `tool_input`
- this stays core-only; binding surface enablement is deferred

Validation:

- `cargo fmt --all`
- `cargo test -p nemo-relay nemo_guardrails --lib --tests`
- `cargo clippy --workspace --all-targets -- -D warnings`
- `uv run pre-commit run --files crates/core/src/plugins/nemo_guardrails/component.rs crates/core/tests/unit/plugins/nemo_guardrails/component_tests.rs crates/core/tests/unit/plugins/nemo_guardrails/remote_tests.rs`

Targeted live validation covered:

- allowed and blocked non-streaming LLM requests
- streaming requests
- trusted HTTPS transport
- managed `tool_output` blocked path
- direct stock Guardrails repro confirming externally supplied pre-exec tool-call history does not activate remote managed `tool_input`

Notes:

- `uv run pre-commit run --all-files` still reports an unrelated repo-environment failure in `ty` for unresolved `deepagents` integration imports
- unrelated `package-lock.json` churn was restored and is not part of this PR

#### Where should the reviewer start?

Start in `crates/core/src/plugins/nemo_guardrails/component.rs`, then `crates/core/src/plugins/nemo_guardrails/remote.rs`.

The most important design decision in this PR is that the built-in plugin now implements a real remote execution backend while keeping the remote contract honest:

- native remote support is OpenAI chat-completions shaped
- LLM and managed `tool_output` execution are supported through the core runtime
- stock remote managed `tool_input` is explicitly rejected instead of being left as a silent best-effort path
- broader non-chat codec parity and the local Python runtime remain out of scope for this slice

#### Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

- Relates to #NMF-131
- Relates to #NMF-148

Authors:
  - https://github.com/afourniernv

Approvers:
  - Will Killian (https://github.com/willkill07)

URL: #144

Author: afourniernv

crates/core/Cargo.toml

@@ -14,8 +14,12 @@ readme = "README.md"
 workspace = true
 
 [features]
-default = ["otel", "openinference"]
+default = ["otel", "openinference", "guardrails-remote"]
 schema = ["dep:schemars"]
+guardrails-remote = [
+    "dep:reqwest",
+    "dep:rustls",
+]
 otel = [
     "dep:async-trait",
     "dep:getrandom",

crates/core/src/plugin.rs

@@ -762,9 +762,11 @@ pub fn register_plugin(plugin: Arc<dyn Plugin>) -> Result<()> {
 /// Built-in plugins are available to validation and initialization without a
 /// binding or application-specific registration call.
 pub fn ensure_builtin_plugins_registered() -> Result<()> {
-    match BUILTIN_PLUGIN_REGISTRATION
-        .get_or_init(crate::observability::plugin_component::register_observability_component)
-    {
+    let register_builtins = || {
+        crate::observability::plugin_component::register_observability_component()?;
+        crate::plugins::nemo_guardrails::component::register_nemo_guardrails_component()
+    };
+    match BUILTIN_PLUGIN_REGISTRATION.get_or_init(register_builtins) {
         Ok(()) => Ok(()),
         Err(err) => Err(clone_cached_plugin_error(err)),
     }

…gins/nemo_guardrails/plugin_component.rs …src/plugins/nemo_guardrails/component.rscrates/core/src/plugins/nemo_guardrails/plugin_component.rs renamed to crates/core/src/plugins/nemo_guardrails/component.rs crates/core/src/plugins/nemo_guardrails/plugin_component.rs renamed to crates/core/src/plugins/nemo_guardrails/component.rs

@@ -17,9 +17,25 @@ use crate::plugin::{
     lookup_plugin, register_plugin,
 };
 
+#[cfg(all(feature = "guardrails-remote", not(target_arch = "wasm32")))]
+#[path = "remote.rs"]
+mod remote;
+#[cfg(all(feature = "guardrails-remote", not(target_arch = "wasm32")))]
+use remote::register_remote_backend;
+
 /// The plugin kind reserved for the planned first-party component.
 pub const NEMO_GUARDRAILS_PLUGIN_KIND: &str = "nemo_guardrails";
 
+#[cfg(any(target_arch = "wasm32", not(feature = "guardrails-remote")))]
+fn register_remote_backend(
+    _config: NeMoGuardrailsConfig,
+    _ctx: &mut PluginRegistrationContext,
+) -> PluginResult<()> {
+    Err(PluginError::RegistrationFailed(
+        "built-in NeMo Guardrails remote backend is unavailable in this build".to_string(),
+    ))
+}
+
 /// Top-level NeMo Guardrails component wrapper.
 #[derive(Debug, Clone)]
 pub struct ComponentSpec {
@@ -182,6 +198,12 @@ pub struct RequestDefaultsConfig {
     /// Default context object passed into Guardrails requests.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub context: Option<Json>,
+    /// Default remote thread identifier for continuation-aware requests.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub thread_id: Option<String>,
+    /// Default remote Guardrails state payload for continuation-aware requests.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state: Option<Json>,
     /// Default request-time rail selection.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub rails: Option<RequestRailsConfig>,
@@ -307,6 +329,8 @@ crate::editor_config! {
 crate::editor_config! {
     impl RequestDefaultsConfig {
         context => { label: "context", kind: Json, optional: true },
+        thread_id => { label: "thread_id", kind: String, optional: true },
+        state => { label: "state", kind: Json, optional: true },
         rails => {
             label: "rails",
             kind: Section,
@@ -349,13 +373,13 @@ impl Plugin for NeMoGuardrailsPlugin {
 
     fn register<'a>(
         &'a self,
-        _plugin_config: &Map<String, Json>,
-        _ctx: &'a mut PluginRegistrationContext,
+        plugin_config: &Map<String, Json>,
+        ctx: &'a mut PluginRegistrationContext,
     ) -> Pin<Box<dyn Future<Output = PluginResult<()>> + Send + 'a>> {
-        Box::pin(async {
-            Err(PluginError::RegistrationFailed(
-                "built-in NeMo Guardrails plugin backend is not implemented yet".to_string(),
-            ))
+        let parsed = parse_nemo_guardrails_config(plugin_config);
+        Box::pin(async move {
+            let config = parsed?;
+            register_nemo_guardrails_backend(config, ctx)
         })
     }
 }
@@ -419,6 +443,21 @@ fn string_enum_schema(
     schema.into()
 }
 
+fn register_nemo_guardrails_backend(
+    config: NeMoGuardrailsConfig,
+    ctx: &mut PluginRegistrationContext,
+) -> PluginResult<()> {
+    match config.mode.as_str() {
+        "remote" => register_remote_backend(config, ctx),
+        "local" => Err(PluginError::RegistrationFailed(
+            "built-in NeMo Guardrails local backend is not implemented yet".to_string(),
+        )),
+        other => Err(PluginError::InvalidConfig(format!(
+            "unsupported NeMo Guardrails mode '{other}'"
+        ))),
+    }
+}
+
 fn parse_nemo_guardrails_config(
     plugin_config: &Map<String, Json>,
 ) -> PluginResult<NeMoGuardrailsConfig> {
@@ -497,6 +536,8 @@ fn validate_nemo_guardrails_plugin_config(
         "request_defaults",
         &[
             "context",
+            "thread_id",
+            "state",
             "rails",
             "llm_params",
             "llm_output",
@@ -526,6 +567,7 @@ fn validate_nemo_guardrails_plugin_config(
     validate_config_shape(&mut diagnostics, &config.policy, &config);
     validate_codec_requirements(&mut diagnostics, &config.policy, &config);
     validate_surface_selection(&mut diagnostics, &config.policy, &config);
+    validate_remote_backend_support(&mut diagnostics, &config.policy, &config);
     validate_request_defaults(&mut diagnostics, &config.policy, &config);
 
     diagnostics
@@ -869,6 +911,43 @@ fn validate_surface_selection(
     );
 }
 
+fn validate_remote_backend_support(
+    diagnostics: &mut Vec<ConfigDiagnostic>,
+    policy: &ConfigPolicy,
+    config: &NeMoGuardrailsConfig,
+) {
+    if config.mode != "remote" {
+        return;
+    }
+
+    if (config.input || config.output)
+        && config
+            .codec
+            .as_deref()
+            .is_some_and(|codec| codec != "openai_chat")
+    {
+        push_policy_diag(
+            diagnostics,
+            policy.unsupported_value,
+            "nemo_guardrails.unsupported_value",
+            Some(NEMO_GUARDRAILS_PLUGIN_KIND.to_string()),
+            Some("codec".to_string()),
+            "remote mode currently supports only codec = 'openai_chat'".to_string(),
+        );
+    }
+
+    if config.tool_input {
+        push_policy_diag(
+            diagnostics,
+            policy.unsupported_value,
+            "nemo_guardrails.unsupported_value",
+            Some(NEMO_GUARDRAILS_PLUGIN_KIND.to_string()),
+            Some("tool_input".to_string()),
+            "remote mode does not currently support managed tool_input against the stock Guardrails remote contract".to_string(),
+        );
+    }
+}
+
 fn validate_request_defaults(
     diagnostics: &mut Vec<ConfigDiagnostic>,
     policy: &ConfigPolicy,
@@ -885,6 +964,54 @@ fn validate_request_defaults(
         "request_defaults.context",
         "request_defaults.context must be a JSON object",
     );
+    if let Some(thread_id) = &request_defaults.thread_id {
+        let trimmed_thread_id = thread_id.trim();
+        if trimmed_thread_id.is_empty() {
+            push_policy_diag(
+                diagnostics,
+                policy.unsupported_value,
+                "nemo_guardrails.unsupported_value",
+                Some(NEMO_GUARDRAILS_PLUGIN_KIND.to_string()),
+                Some("request_defaults.thread_id".to_string()),
+                "request_defaults.thread_id must not be empty".to_string(),
+            );
+        } else if trimmed_thread_id.len() < 16 {
+            push_policy_diag(
+                diagnostics,
+                policy.unsupported_value,
+                "nemo_guardrails.unsupported_value",
+                Some(NEMO_GUARDRAILS_PLUGIN_KIND.to_string()),
+                Some("request_defaults.thread_id".to_string()),
+                "request_defaults.thread_id must be at least 16 characters long".to_string(),
+            );
+        }
+    }
+    validate_json_object_field(
+        diagnostics,
+        policy,
+        request_defaults.state.as_ref(),
+        "request_defaults.state",
+        "request_defaults.state must be a JSON object",
+    );
+    if let Some(state) = request_defaults
+        .state
+        .as_ref()
+        .and_then(|value| value.as_object())
+    {
+        let contains_supported_key = state.contains_key("events") || state.contains_key("state");
+        let contains_unsupported_key = state.keys().any(|key| key != "events" && key != "state");
+        if (!state.is_empty() && !contains_supported_key) || contains_unsupported_key {
+            push_policy_diag(
+                diagnostics,
+                policy.unsupported_value,
+                "nemo_guardrails.unsupported_value",
+                Some(NEMO_GUARDRAILS_PLUGIN_KIND.to_string()),
+                Some("request_defaults.state".to_string()),
+                "request_defaults.state must be empty or contain only 'events' or 'state'"
+                    .to_string(),
+            );
+        }
+    }
     validate_json_object_field(
         diagnostics,
         policy,
@@ -1138,5 +1265,5 @@ fn default_timeout_millis() -> u64 {
 }
 
 #[cfg(test)]
-#[path = "../../../tests/unit/plugins/nemo_guardrails/plugin_component_tests.rs"]
+#[path = "../../../tests/unit/plugins/nemo_guardrails/component_tests.rs"]
 mod tests;

crates/core/src/plugins/nemo_guardrails/mod.rs

@@ -11,4 +11,4 @@ pub(crate) fn test_mutex() -> &'static Mutex<()> {
     crate::shared_runtime::runtime_owner_test_mutex()
 }
 
-pub mod plugin_component;
+pub mod component;