From 337ea6a56eeb96c2d69695bc2ab68818d4307d76 Mon Sep 17 00:00:00 2001 From: Alex Fournier Date: Tue, 4 Aug 2026 10:39:07 -0700 Subject: [PATCH 1/3] docs: complete the plugin lifecycle model Signed-off-by: Alex Fournier --- docs/about-nemo-relay/concepts/plugins.mdx | 62 +++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/about-nemo-relay/concepts/plugins.mdx b/docs/about-nemo-relay/concepts/plugins.mdx index bb5f06528..21904e5d6 100644 --- a/docs/about-nemo-relay/concepts/plugins.mdx +++ b/docs/about-nemo-relay/concepts/plugins.mdx @@ -40,6 +40,18 @@ declares what it is and which config it should use. Policy controls how strictly the plugin system interprets unknown fields, unsupported values, or compatibility issues. +Two similarly named files serve different purposes: + +| File | Owner | Purpose | +| --- | --- | --- | +| `plugins.toml` | Relay operator or application | Configures built-in components and records references to discoverable plugins. Relay discovers and layers this file. | +| `relay-plugin.toml` | Discoverable plugin author | Describes one packaged native library or worker, including compatibility, capabilities, loading, and integrity. Relay reads it through a reference in `plugins.toml`. | + +Refer to [Plugin Configuration Files](/configure-plugins/plugin-configuration-files) +for runtime configuration and +[Discoverable Plugins](/build-plugins/dynamic-plugins/about) for the package +manifest. + ## Component Lifecycle Plugins follow a small lifecycle rather than registering everything blindly. @@ -59,6 +71,16 @@ behavior. Reporting provides structured diagnostics about what activated successfully and what did not. +### Deactivation and Cleanup + +Plugin initialization owns the registrations it installs. Clearing active +plugin configuration removes those registrations and runs component cleanup. +Dynamic plugin teardown also stops managed workers and releases native +activations after their callbacks are no longer registered. Applications should +clear plugin configuration during graceful shutdown and test teardown. Refer to +[Register Plugin Behavior](/build-plugins/language-binding/register-behavior) +for the binding lifecycle. + ### Failure Boundary Plugin validation and initialization are setup boundaries. If configuration is @@ -138,7 +160,9 @@ them. ## Ownership and Scope Plugin initialization is process-level. It is intended for runtime components -that should activate once for the running process rather than once per request. +that should remain active across requests in one process. It is not permanent: +clearing or replacing the active plugin configuration removes plugin-owned +runtime behavior. Scope-local behavior still matters after plugin installation, but the plugin system itself is a global activation layer. @@ -147,6 +171,17 @@ Plugins install runtime behavior; they do not create a separate execution model. Scopes still own parentage and cleanup, middleware still owns execution ordering, and events still own the canonical runtime record. +## Plugin Delivery Models + +All plugin components use the same validation and activation model. They differ +in how their component kind becomes available to the host: + +| Delivery model | How it becomes available | Use when | +| --- | --- | --- | +| Built-in | The Relay host registers a linked first-party component automatically. | The component ships as part of that host. | +| Host-registered | An embedding application links a component crate and registers its kind before validation. | A direct host controls its linked feature set. | +| Discoverable | The CLI loads a manifest-backed native library or worker at startup. | A separately packaged extension should be installed without rebuilding Relay. | + ## Built-In Plugin Components The core runtime registers the `observability`, `nemo_guardrails`, and @@ -220,6 +255,16 @@ The core crate ships a built-in `pricing` component. It loads catalog sources that response codecs can use to annotate managed LLM responses with cost estimates. Configure catalog sources through [Model Pricing](/configure-plugins/model-pricing). +### Switchyard (Experimental) + +The experimental `switchyard` component asks a separately running Switchyard +Decision API to select a configured model backend. It is excluded from default +CLI builds and is registered only when the CLI is built with the optional +`switchyard` feature. Direct Rust, Python, and Node.js hosts do not register it +automatically. Refer to +[Switchyard (Experimental)](/configure-plugins/switchyard/about) for the pinned +compatibility and deployment requirements. + For `plugins.toml` discovery, precedence, merge, and gateway editing rules, refer to [Plugin Configuration Files](/configure-plugins/plugin-configuration-files). @@ -240,6 +285,21 @@ to [Configure Discoverable Plugins](/configure-plugins/discoverable-plugins) for the operator workflow and [Discoverable Plugins](/build-plugins/dynamic-plugins/about) for the authoring model. +The operator lifecycle is explicit: + +1. `plugins add` records the manifest and prepares managed worker resources when + required. +2. `plugins validate` checks compatibility, schema, policy, and trust evidence. +3. `plugins enable` changes desired state; the plugin loads during the next host + startup. +4. `plugins disable` keeps the registration but prevents it from loading on the + next startup. +5. `plugins remove` deletes the registration and any Relay-managed worker + environment after the running host has stopped. + +These commands manage future host activation. Teardown of an already running +host remains part of that host's owned plugin cleanup. + ## Practical Guidance Use these practices when applying the concept in application or integration code. From 7e7e8a8bb3b75d5dc8fb408adf4811aa7da70b76 Mon Sep 17 00:00:00 2001 From: Alex Fournier Date: Tue, 4 Aug 2026 13:19:54 -0700 Subject: [PATCH 2/3] docs: clarify plugin terminology Signed-off-by: Alex Fournier --- docs/about-nemo-relay/concepts/plugins.mdx | 28 +++++++++++----------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/about-nemo-relay/concepts/plugins.mdx b/docs/about-nemo-relay/concepts/plugins.mdx index 21904e5d6..990e29da7 100644 --- a/docs/about-nemo-relay/concepts/plugins.mdx +++ b/docs/about-nemo-relay/concepts/plugins.mdx @@ -16,11 +16,11 @@ Plugins let NeMo Relay install reusable runtime behavior from configuration instead of requiring every application or framework integration to register the same middleware and subscribers by hand. -They are the main packaging layer for reusable runtime components. +Plugins package reusable runtime components. ## Plugin Configuration Model -The canonical plugin document has three main areas: +A plugin configuration document has three main areas: - `version` - `components` @@ -32,8 +32,8 @@ The version identifies the configuration format expected by the plugin system. ### Components -Components describe the individual runtime pieces to activate. Each component -declares what it is and which config it should use. +Components identify the runtime behavior to activate. Each component declares +its kind and configuration. ### Policy @@ -54,7 +54,7 @@ manifest. ## Component Lifecycle -Plugins follow a small lifecycle rather than registering everything blindly. +Relay validates plugin configuration before it activates any component. ### Validation @@ -73,7 +73,7 @@ what did not. ### Deactivation and Cleanup -Plugin initialization owns the registrations it installs. Clearing active +Relay tracks registrations created during plugin initialization. Clearing active plugin configuration removes those registrations and runs component cleanup. Dynamic plugin teardown also stops managed workers and releases native activations after their callbacks are no longer registered. Applications should @@ -81,11 +81,11 @@ clear plugin configuration during graceful shutdown and test teardown. Refer to [Register Plugin Behavior](/build-plugins/language-binding/register-behavior) for the binding lifecycle. -### Failure Boundary +### Setup Failures -Plugin validation and initialization are setup boundaries. If configuration is -invalid, a component kind is unavailable, or initialization fails, callers should -treat the plugin setup as failed before relying on the new runtime behavior. +Plugin validation and initialization happen during setup. If configuration is +invalid, a component kind is unavailable, or initialization fails, callers +should treat setup as failed before relying on the new runtime behavior. Activation reports are the public way to inspect what validated or activated. Runtime behavior after activation still belongs to the installed component. For @@ -142,8 +142,8 @@ flowchart TB ## Plugin Context -The plugin context is the runtime surface that a component uses to register its -behavior. This is where plugins connect configuration to real runtime state. +The plugin context is the API that a component uses to register its behavior. +It connects plugin configuration to the active runtime. ## What Plugins Can Register @@ -179,7 +179,7 @@ in how their component kind becomes available to the host: | Delivery model | How it becomes available | Use when | | --- | --- | --- | | Built-in | The Relay host registers a linked first-party component automatically. | The component ships as part of that host. | -| Host-registered | An embedding application links a component crate and registers its kind before validation. | A direct host controls its linked feature set. | +| Host-registered | An embedding application links a component crate and registers its kind before validation. | An embedding application decides which component crates to link. | | Discoverable | The CLI loads a manifest-backed native library or worker at startup. | A separately packaged extension should be installed without rebuilding Relay. | ## Built-In Plugin Components @@ -283,7 +283,7 @@ evidence before enabling or running a dynamic plugin. During startup, Relay loads the enabled adapter and then validates the synthesized component. Refer to [Configure Discoverable Plugins](/configure-plugins/discoverable-plugins) for the operator workflow and [Discoverable Plugins](/build-plugins/dynamic-plugins/about) -for the authoring model. +for the authoring workflow. The operator lifecycle is explicit: From 5e5de820be9f01127eebb3ac6f5d660c3f4e287f Mon Sep 17 00:00:00 2001 From: Alex Fournier Date: Tue, 4 Aug 2026 16:18:29 -0700 Subject: [PATCH 3/3] docs: complete discoverable plugin commands Signed-off-by: Alex Fournier --- docs/about-nemo-relay/concepts/plugins.mdx | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/about-nemo-relay/concepts/plugins.mdx b/docs/about-nemo-relay/concepts/plugins.mdx index 990e29da7..96dd7cdf4 100644 --- a/docs/about-nemo-relay/concepts/plugins.mdx +++ b/docs/about-nemo-relay/concepts/plugins.mdx @@ -287,15 +287,18 @@ for the authoring workflow. The operator lifecycle is explicit: -1. `plugins add` records the manifest and prepares managed worker resources when - required. -2. `plugins validate` checks compatibility, schema, policy, and trust evidence. -3. `plugins enable` changes desired state; the plugin loads during the next host - startup. -4. `plugins disable` keeps the registration but prevents it from loading on the - next startup. -5. `plugins remove` deletes the registration and any Relay-managed worker - environment after the running host has stopped. +1. `nemo-relay plugins add ` records the manifest and prepares managed + worker resources when required. +2. `nemo-relay plugins inspect ` reads the stored registration and + resolved manifest without changing desired state. +3. `nemo-relay plugins validate ` checks compatibility, schema, + policy, and trust evidence. +4. `nemo-relay plugins enable ` changes desired state; the plugin + loads during the next host startup. +5. `nemo-relay plugins disable ` keeps the registration but prevents + it from loading on the next startup. +6. `nemo-relay plugins remove ` deletes the registration and any + Relay-managed worker environment after the running host has stopped. These commands manage future host activation. Teardown of an already running host remains part of that host's owned plugin cleanup.