feat(python): initialize plugins from TOML - #684
Draft
bbednarski9 wants to merge 10 commits into
Draft
Conversation
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Enterprise Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Comment |
github-actions
Bot
added
size:XXL
License DiffCompared against Lockfile license changesLockfile License ChangesRustAdded
Removed
Updated/Changed
NodeAdded
Removed
Updated/Changed
PythonAdded
Removed
Updated/Changed
Status output |
2 tasks
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## release/0.7 #684 +/- ##
===============================================
- Coverage 94.40% 94.21% -0.19%
===============================================
Files 330 338 +8
Lines 96829 99893 +3064
Branches 113 113
===============================================
+ Hits 91404 94110 +2706
- Misses 5425 5782 +357
- Partials 0 1 +1
... and 7 files with indirect coverage changes Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>
2 tasks
rapids-bot Bot
pushed a commit
that referenced
this pull request
Aug 4, 2026
#### Overview
Adds a minimal Python compatibility API that converts standard `[[plugins.dynamic]]` records from one explicit `plugins.toml` into the existing `DynamicPluginActivationSpec` objects accepted by `initialize_with_dynamic_plugins()`.
This unblocks Python applications that embed Relay without introducing the larger file-backed activation, lifecycle reconciliation, dynamic layering, or initialization redesign proposed for a later release. The new API is intentionally a temporary 0.7 surface:
```python
plugin_config_path = os.environ["NEMO_RELAY_PLUGINS_TOML"]
dynamic_plugins = plugin.load_dynamic_plugin_activation_specs(plugin_config_path)
activation = await plugin.initialize_with_dynamic_plugins({}, dynamic_plugins)
```
`NEMO_RELAY_PLUGINS_TOML` is an optional host-side convention in this example. Relay does not read the environment variable automatically; the embedding application resolves a path through its environment, command-line, or configuration system and passes that path to the helper.
- [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.
A broader implementation exists in #684. This PR is a deliberately scoped 0.7 alternative that reuses the existing activation owner instead of introducing shared lifecycle and host-configuration infrastructure.
#### Details
##### Public API
Adds:
```python
def load_dynamic_plugin_activation_specs(
plugin_config_path: str | os.PathLike[str],
) -> list[DynamicPluginActivationSpec]: ...
```
The helper:
* Reads one explicitly selected `plugins.toml`.
* Parses every `[[plugins.dynamic]]` record in declaration order.
* Resolves relative manifest paths against the selected file.
* Reads `plugin.id` and `plugin.kind` from each manifest.
* Preserves the record's JSON-compatible `config`.
* Rejects malformed TOML, invalid record shapes, unsupported fields, invalid plugin identities, duplicate plugin IDs, and non-JSON configuration.
* Returns the existing activation-spec type without loading code.
The existing dynamic initializer now accepts a `Sequence` rather than only a `list`. This reflects its existing behavior and allows parser results, lists, and tuples to compose without casts.
##### Developer flow
```mermaid
flowchart LR
User["User selects a plugins.toml"] -->
Host["Embedding host resolves the path"]
Env["Optional NEMO_RELAY_PLUGINS_TOML"] --> Host
Host --> Helper["load_dynamic_plugin_activation_specs(path)"]
Helper --> Config["Read one explicit plugins.toml"]
Config --> Records["Parse [[plugins.dynamic]] records"]
Records --> Manifests["Resolve and read relay-plugin.toml manifests"]
Manifests --> Specs["Build DynamicPluginActivationSpec list"]
Specs --> Initialize["initialize_with_dynamic_plugins(config, specs)"]
Initialize --> Activation["Owned PluginHostActivation"]
Activation --> Runtime["Host retains activation while work is admitted"]
Runtime --> Close["await activation.close() during shutdown"]
```
##### Configuration behavior
The temporary dynamic path and existing static configuration path remain separate:
```mermaid
flowchart TB
subgraph Static["Existing static component resolution"]
UserConfig["User plugins.toml"] --> StaticLayering["User → project → system → programmatic overlay"]
ProjectConfig["Project .nemo-relay/plugins.toml"] --> StaticLayering
SystemConfig["System /etc/nemo-relay/plugins.toml"] --> StaticLayering
end
subgraph Dynamic["New 0.7 compatibility path"]
ExplicitPath["One explicit plugins.toml path"] --> DynamicParser["Parse [[plugins.dynamic]] only"]
DynamicParser --> DynamicSpecs["Explicit activation specs"]
end
StaticLayering --> HostInitializer["Existing dynamic host initializer"]
DynamicSpecs --> HostInitializer
HostInitializer --> OwnedHost["PluginHostActivation"]
```
The helper does not perform dynamic-plugin layering. It reads only the explicitly supplied file. Static `[[components]]` from that file are inherited only when the same file is also selected by Relay's normal static discovery.
Every dynamic declaration in the selected file becomes an activation spec. Passing those specs to `initialize_with_dynamic_plugins()` is explicit consent to load the referenced trusted native libraries or worker processes.
Python workers that require a lifecycle-managed `environment_ref` still require the existing explicit activation or CLI lifecycle path.
##### Intentional non-goals
This PR does not:
* Consolidate `initialize()` and `initialize_with_dynamic_plugins()`.
* Add a unified `initialize_from_plugins_toml()` API.
* Discover or merge dynamic records across user, project, and system layers.
* Read or reconcile `.dynamic-plugins.json`.
* Consult CLI enablement or tombstone state.
* Provision or attest Python worker environments.
* Change plugin enablement, install plugins, or execute package managers.
* Change Rust, Node.js, Go, FFI, or CLI behavior.
The helper is documented as a 0.7 compatibility surface and is expected to be deprecated after the unified file-backed initializer lands. Keeping the conversion behind one Relay API lets embedded hosts remove their TOML and manifest parsing now while keeping the future migration localized to one call site.
##### Documentation and validation
Updates the Python type stub, plugin-configuration guide, and 0.7 release notes. Tests cover relative and absolute manifest resolution, native and worker spec construction, config preservation, malformed records and TOML, missing manifests, duplicate IDs, and end-to-end native activation from a real `[[plugins.dynamic]]` record.
Validation completed:
* Focused parser and native-activation tests: `16 passed`.
* Ruff formatting and linting.
* `ty` type checking.
* Changed-file and repository-wide pre-commit suites.
* Cargo formatting, clippy, check, and dependency-policy checks.
* Python worker protobuf compatibility.
* Go formatting and vet.
* Node formatting and public docstring checks.
* Fern structure and strict broken-link validation.
The complete dynamic-host Python module was also attempted locally. Pre-existing tests inherited an invalid machine-level `/etc/nemo-relay/plugins.toml`, and sandboxed worker tests could not bind Unix sockets. The tests directly covering this change passed independently.
Breaking changes: none.
#### Where should the reviewer start?
Start with `python/nemo_relay/plugin.py`, specifically `load_dynamic_plugin_activation_specs()`.
The central design decision is that this helper performs only the missing file-to-activation-spec conversion. It deliberately reuses the existing dynamic initializer and owned activation lifetime rather than introducing another activation owner or pulling CLI lifecycle behavior into the Python binding.
Then review `python/tests/test_dynamic_plugin_host.py` for the standard TOML parsing, failure behavior, and end-to-end native activation coverage.
#### Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)
* Relates to #673
* Relates to #684
* Relates to [NousResearch/hermes-agent#77915](<NousResearch/hermes-agent#77915>)
## Summary by CodeRabbit
* **New Features**
* Added a Python compatibility helper for loading dynamic plugin activation specifications from a selected `plugins.toml` file.
* Supports manifest path resolution, ordered activation specifications, nested configuration, duplicate detection, and validation of plugin records and JSON values.
* Dynamic plugin initialization now accepts any ordered collection of activation specifications.
* **Documentation**
* Added guidance covering configuration resolution, explicit loading consent, supported behavior, limitations, and planned deprecation.
* **Tests**
* Expanded coverage for valid configurations, absolute and nested manifest paths, malformed files, duplicate IDs, and missing manifests.
## Summary by CodeRabbit
* **New Features**
* Added support for loading dynamic plugin activation settings from a selected `plugins.toml` file.
* Added validation for manifests, duplicate identifiers, malformed configuration, and invalid JSON values.
* Dynamic plugin initialization now accepts any ordered collection of activation specifications.
* **Documentation**
* Added configuration guidance, behavior details, limitations, compatibility notes, and planned deprecation information.
* **Tests**
* Added coverage for valid configurations, path resolution, nested settings, and common loading errors.
Authors:
- Bryan Bednarski (https://github.com/bbednarski9)
Approvers:
- Will Killian (https://github.com/willkill07)
- Maryam Najafian (https://github.com/mnajafian-nv)
URL: #694
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Adds an owned Python initialization path for ordinary
plugins.tomlfiles, including lifecycle-enabled dynamic plugins, without requiring an embedded host to parse[[plugins.dynamic]]or construct activation specs itself.This is the first PR in a two-PR stack. It introduces the binding-neutral resolver and activation foundation and exposes it in Python. A stacked follow-up will migrate the CLI runtime owner to the same activation plan while preserving the CLI control plane and bootstrap behavior.
Details
nemo-relay-plugin-host-configworkspace crate. It shares Relay's user/project/system source selection, component merge rules, dynamic host policy, lifecycle state, trust checks, managed-environment attestation, and immutable activation snapshots with embedded hosts.nemo_relay.plugin.initialize_from_plugins_toml(...)and the ownedPluginFileActivationasync lifetime. The API supports default discovery or a selectedplugins.toml, a highest-precedence static overlay, inactive no-input handles, owned static-only handles, deterministic/idempotent close, async context management, and best-effort finalization.[[plugins.dynamic]]as declarations only. Each declaration is validated and reconciled against the same source file's sibling.dynamic-plugins.json; only live records withspec.enabled == trueenter the activation plan. Initialization never installs packages, creates environments, changes enablement, or editsplugins.toml.config_ref; duplicate IDs and ambiguous live source moves fail closed.PluginHostActivationPlanthat carries resolved static config, ordered dynamic specs, redacted diagnostics, andArc-owned snapshot resources into Relay's cancellation-resistant mutation executor.libpython<major>.<minor>.dylibselected by the attestation-verifiedpyvenv.cfg; the copied runtime library is then covered by the immutable snapshot digest and protection.initialize(),initialize_with_dynamic_plugins(), explicit activation specs, generic clear APIs, and non-Python bindings unchanged.Security model: calling the new initializer is explicit consent to load lifecycle-enabled trusted native libraries or worker processes from the selected configuration scope. Enabled Python workers must already have a valid Relay-managed environment and attestation; this API is not an installer or control plane. Diagnostics include source paths and plugin IDs but do not include component values or credentials.
Validation completed locally:
cargo test -p nemo-relay-plugin-host-config— 84 unit tests and 8 integration tests passed.cargo test -p nemo-relay-cli(1,204 library tests, 12 architecture tests, and 98 CLI integration tests)cargo test -p nemo-relay-cli plugins::lifecycle::tests(79 lifecycle/control-plane tests)cargo test -p nemo-relay --features worker-grpc --test native_plugin_integration --test worker_plugin_integrationjust test-rustjust test-python-pluginjust test-python-plugin-e2eunder the CI-pinned uv CPython 3.11.14 runtime (managed gRPC worker add, enable, activation, middleware execution, and teardown)just test-pythonjust test-gojust test-nodecargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warningsjust package-rustjust package-pythonjust package-python-sdist(verified the shared crate is present in the sdist)just docsjust docs-linkcheckuv run pre-commit run --all-filesBreaking changes: none. This is an additive Python API and a document-hidden Rust host contract. Node, FFI, and Go retain their existing explicit-spec APIs.
Where should the reviewer start?
Start with
crates/plugin-host-config/src/activation.rsandcrates/plugin-host-config/src/resolver.rsfor the file-backed contract, then reviewcrates/core/src/plugin/dynamic/host.rsfor atomic ownership and teardown. The Python surface is wired incrates/python/src/py_plugin.rsandpython/nemo_relay/plugin.py.The most important design invariant is that the same immutable snapshot verified immediately before load remains owned by the native or worker runtime through the last in-flight callback. Lifecycle reconciliation is durable configuration state, not part of the runtime activation transaction.
Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)