Register Plugin Behavior

Use this guide when plugin config validation is in place and you need the plugin to install real NeMo Relay runtime behavior.

What You Build

You will register a plugin kind, initialize a validated config, install subscribers or middleware through PluginContext, and clear active plugin configuration during teardown.

Use PluginContext

PluginContext is the component-scoped registration surface passed to the plugin during initialization. Register subscribers, guardrails, and intercepts through this context rather than through global registration calls inside application startup.

That gives the plugin system three important guarantees:

• Runtime names can be qualified for the component instance.
• Partial setup can be rolled back if one registration fails.
• Activation reports can identify which configured component installed behavior.

Use the context only after validation succeeds. Validation should inspect config and return diagnostics; registration should create runtime objects and attach them to the context.

Activation APIs

Use the plugin APIs in this order:

1. Register the plugin kind.
2. Build a PluginConfig.
3. Validate the config.
4. Initialize the config.
5. Inspect the activation report.
6. Clear active config during teardown when needed.

1
import nemo_relay
2
3
config = nemo_relay.plugin.PluginConfig()
4
config.components = [
5
    nemo_relay.plugin.ComponentSpec(
6
        kind="header-plugin",
7
        config={"header_name": "x-tenant", "value": "tenant-a"},
8
    )
9
]
10
11
report = nemo_relay.plugin.validate(config)
12
active_report = await nemo_relay.plugin.initialize(config)
13
kinds = nemo_relay.plugin.list_kinds()
14
nemo_relay.plugin.clear()

Header Plugin Example

The same model applies in every binding: validate component-local config, then install middleware through the component-scoped registration context.

1
from typing import Any
2
3
import nemo_relay
4
5
class HeaderPlugin:
6
    def validate(self, plugin_config: dict[str, Any]) -> list[dict[str, str]]:
7
        if "header_name" not in plugin_config or "value" not in plugin_config:
8
            return [{
9
                "level": "error",
10
                "code": "header-plugin.invalid_config",
11
                "message": "header_name and value are required",
12
            }]
13
        return []
14
15
    def register(self, plugin_config: dict[str, Any], context: nemo_relay.plugin.PluginContext):
16
        def add_header(
17
            name: str,
18
            request: nemo_relay.LLMRequest,
19
            annotated: nemo_relay.AnnotatedLLMRequest | None
20
        ) -> tuple[nemo_relay.LLMRequest, nemo_relay.AnnotatedLLMRequest | None]:
21
            headers = request.headers.copy()
22
            headers[plugin_config["header_name"]] = plugin_config["value"]
23
            return nemo_relay.LLMRequest(headers=headers, content=request.content), annotated
24
25
        context.register_llm_request_intercept("inject-header", 100, False, add_header)
26
27
nemo_relay.plugin.register("header-plugin", HeaderPlugin())

Registration Checklist

Before publishing or sharing a plugin:

1. Validate a correct config and confirm no errors are reported.
2. Validate an intentionally invalid config and confirm diagnostics are actionable.
3. Initialize the plugin and verify the expected subscribers or middleware run.
4. Force one registration failure and confirm partial setup is rolled back.
5. Deregister or clear active config during teardown.

Common Issues

Check these symptoms first when the workflow does not behave as expected.

• Middleware names collide: Use component-local names and let the plugin runtime qualify them.
• Partial registrations remain after failure: Register through PluginContext so rollback can clean up.
• Registration does validation work: Move deterministic checks into the validation hook.
• Global state leaks across component instances: Create instance-local state during registration or key shared state by component identity.

Next Steps

Use these links to continue from this workflow into the next related task.

• Add advanced validation and rollout controls with Design Plugin Configuration.
• Review concrete authoring patterns in Code Examples.