NVIDIA
diff --git a/‎docs/about-nemo-relay/release-notes/index.mdx‎
Lines changed: 6 additions & 0 deletions b/‎docs/about-nemo-relay/release-notes/index.mdx‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎docs/configure-plugins/plugin-configuration-files.mdx‎
Lines changed: 44 additions & 0 deletions b/‎docs/configure-plugins/plugin-configuration-files.mdx‎
Lines changed: 44 additions & 0 deletions
diff --git a/‎python/nemo_relay/plugin.py‎
Lines changed: 115 additions & 1 deletion b/‎python/nemo_relay/plugin.py‎
Lines changed: 115 additions & 1 deletion
diff --git a/‎python/nemo_relay/plugin.pyi‎
Lines changed: 6 additions & 2 deletions b/‎python/nemo_relay/plugin.pyi‎
Lines changed: 6 additions & 2 deletions
@@ -102,6 +102,12 @@ their values cannot be isolated between endpoints.
 
 ### Fixed Known Issues in 0.7
 
+- Embedded Python hosts can use
+  `plugin.load_dynamic_plugin_activation_specs(path)` to convert the standard
+  `[[plugins.dynamic]]` records in one explicitly selected `plugins.toml` into
+  the activation specs accepted by `initialize_with_dynamic_plugins()`. This
+  scoped 0.7 compatibility helper removes host-side TOML and manifest parsing;
+  a future unified file-backed initializer is expected to replace it.
 - Programmatically declared plugin components now apply their `enabled` value
   over discovered file configuration. When code re-enables a component that a
   discovered file disabled, initialization reports a warning that names the
 
@@ -163,6 +163,50 @@ manifest’s optional static JSON Schema before you enable or run the plugin. Us
 dynamic-plugin lifecycle. Refer to [Configure Discoverable Plugins](/configure-plugins/discoverable-plugins)
 for manifest, trust, and policy requirements.
 
+### Embedded Python Compatibility Helper
+
+Python hosts that already own plugin activation can convert the dynamic records
+from one explicitly selected file into the activation specs accepted by the
+0.7 host API:
+
+```python
+import asyncio
+
+from nemo_relay import plugin
+
+
+async def main() -> None:
+    dynamic_plugins = plugin.load_dynamic_plugin_activation_specs(
+        "path/to/plugins.toml"
+    )
+    activation = await plugin.initialize_with_dynamic_plugins({}, dynamic_plugins)
+    async with activation:
+        # Run your host application while dynamic plugins are active.
+        ...
+
+
+asyncio.run(main())
+```
+
+The helper resolves each manifest relative to `plugins.toml` and reads the
+plugin ID and execution lane from the manifest. It does not perform discovery,
+consult CLI lifecycle state, provision a Python worker environment, or change
+enablement.
+
+On success, the helper returns every `[[plugins.dynamic]]` declaration in file
+order; it does not skip invalid entries. A missing `plugins.toml` or referenced
+manifest raises `FileNotFoundError`. Malformed TOML, invalid records or required
+manifest fields, duplicate plugin IDs, and non-JSON configuration raise
+`ValueError`. The helper does not apply an optional manifest-declared static
+JSON Schema.
+
+Passing the result to `initialize_with_dynamic_plugins()` is explicit consent
+to load those trusted native libraries or worker processes.
+
+This helper is a 0.7 compatibility surface for embedded integrations and is
+planned for deprecation after Relay provides a unified file-backed
+initializer. Keep its use localized so migration is straightforward.
+
 The runtime reads only files named `plugins.toml` during default discovery.
 
 ## Runtime Discovery
 
@@ -11,8 +11,13 @@
 from __future__ import annotations
 
 import asyncio
+import json
+import os
+import tomllib
+from collections.abc import Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass, field, fields, is_dataclass
+from pathlib import Path
 from typing import TYPE_CHECKING, AsyncIterator, Callable, Literal, Protocol, Self, TypedDict, cast
 
 from nemo_relay import (
@@ -417,6 +422,114 @@ async def __aexit__(
         await self.close()
 
 
+def load_dynamic_plugin_activation_specs(
+    plugin_config_path: str | os.PathLike[str],
+) -> list[DynamicPluginActivationSpec]:
+    """Load dynamic activation specs from one standard ``plugins.toml``.
+
+    Args:
+        plugin_config_path: Explicit path to the ``plugins.toml`` file.
+
+    Returns:
+        Activation specs for every ``[[plugins.dynamic]]`` record, in file
+        order. Manifest paths are resolved relative to ``plugins.toml`` and
+        each plugin's identifier and execution lane come from its manifest.
+
+    Behavior:
+        This 0.7 compatibility helper parses one explicit file only. It does
+        not perform standard discovery, inspect CLI lifecycle state, provision
+        worker environments, change enablement, or activate plugins. It is
+        planned for deprecation after a unified file-backed initializer is
+        available. Keep its use localized and pass the result to
+        :func:`initialize_with_dynamic_plugins`.
+    """
+    source = Path(os.fspath(plugin_config_path)).resolve()
+    document = _load_plugin_toml(source, "plugin TOML")
+    version = document.get("version", 1)
+    if not isinstance(version, int) or isinstance(version, bool) or version != 1:
+        raise ValueError(f"plugin config version {version!r} in {source} is unsupported; expected 1")
+    plugins = document.get("plugins", {})
+    if not isinstance(plugins, dict):
+        raise ValueError(f"invalid dynamic plugin config in {source}: 'plugins' must be a table")
+    plugins = cast(dict[str, object], plugins)
+    dynamic_plugins = plugins.get("dynamic", [])
+    if not isinstance(dynamic_plugins, list):
+        raise ValueError(f"invalid dynamic plugin config in {source}: 'plugins.dynamic' must be an array of tables")
+
+    specs: list[DynamicPluginActivationSpec] = []
+    seen_plugin_ids: set[str] = set()
+    for index, entry in enumerate(dynamic_plugins):
+        if not isinstance(entry, dict):
+            raise ValueError(f"invalid dynamic plugin config in {source}: plugins.dynamic[{index}] must be a table")
+        entry = cast(dict[str, object], entry)
+        unknown_fields = sorted(set(entry) - {"manifest", "config"})
+        if unknown_fields:
+            raise ValueError(
+                f"invalid dynamic plugin config in {source}: plugins.dynamic[{index}] has unknown fields: "
+                + ", ".join(unknown_fields)
+            )
+        manifest_ref = entry.get("manifest")
+        if not isinstance(manifest_ref, str) or not manifest_ref.strip():
+            raise ValueError(
+                f"invalid dynamic plugin config in {source}: "
+                f"plugins.dynamic[{index}].manifest must be a non-empty string"
+            )
+        manifest_path = Path(manifest_ref)
+        if not manifest_path.is_absolute():
+            manifest_path = source.parent / manifest_path
+        manifest_path = manifest_path.resolve()
+
+        manifest = _load_plugin_toml(manifest_path, "dynamic plugin manifest")
+        identity = manifest.get("plugin")
+        if not isinstance(identity, dict):
+            raise ValueError(f"invalid dynamic plugin manifest in {manifest_path}: 'plugin' must be a table")
+        identity = cast(dict[str, object], identity)
+        plugin_id = identity.get("id")
+        if not isinstance(plugin_id, str) or not plugin_id.strip():
+            raise ValueError(
+                f"invalid dynamic plugin manifest in {manifest_path}: 'plugin.id' must be a non-empty string"
+            )
+        plugin_id = plugin_id.strip()
+        kind = identity.get("kind")
+        if kind not in ("rust_dynamic", "worker"):
+            raise ValueError(
+                f"invalid dynamic plugin manifest in {manifest_path}: 'plugin.kind' must be 'rust_dynamic' or 'worker'"
+            )
+        if plugin_id in seen_plugin_ids:
+            raise ValueError(f"duplicate dynamic plugin id {plugin_id!r} in {source}")
+        seen_plugin_ids.add(plugin_id)
+
+        config = entry.get("config", {})
+        if not isinstance(config, dict):
+            raise ValueError(
+                f"invalid dynamic plugin config in {source}: plugins.dynamic[{index}].config must be a table"
+            )
+        try:
+            normalized_config = cast(JsonObject, json.loads(json.dumps(config, allow_nan=False)))
+        except (TypeError, ValueError) as error:
+            raise ValueError(
+                f"invalid dynamic plugin config in {source}: "
+                f"plugins.dynamic[{index}].config must contain JSON values: {error}"
+            ) from error
+        specs.append(
+            DynamicPluginActivationSpec(
+                plugin_id=plugin_id,
+                kind=cast(DynamicPluginKind, kind),
+                manifest_ref=str(manifest_path),
+                config=normalized_config,
+            )
+        )
+    return specs
+
+
+def _load_plugin_toml(path: Path, description: str) -> dict[str, object]:
+    try:
+        with path.open("rb") as file:
+            return cast(dict[str, object], tomllib.load(file))
+    except tomllib.TOMLDecodeError as error:
+        raise ValueError(f"invalid {description} in {path}: {error}") from error
+
+
 def validate(config: PluginConfig | JsonObject) -> ConfigReport:
     """Validate a plugin configuration without changing runtime state.
 
@@ -452,7 +565,7 @@ async def initialize(config: PluginConfig | JsonObject) -> ConfigReport:
 
 async def initialize_with_dynamic_plugins(
     config: PluginConfig | JsonObject,
-    dynamic_plugins: list[DynamicPluginActivationSpec | JsonObject],
+    dynamic_plugins: Sequence[DynamicPluginActivationSpec | JsonObject],
 ) -> PluginHostActivation:
     """Initialize registered components with dynamic plugins as one owned host.
 
@@ -607,6 +720,7 @@ def deregister(plugin_kind: str) -> bool:
     "PluginContext",
     "PluginHostActivation",
     "Plugin",
+    "load_dynamic_plugin_activation_specs",
     "initialize_with_dynamic_plugins",
     "clear",
     "clear_async",
 
@@ -1,7 +1,8 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-from collections.abc import Callable
+import os
+from collections.abc import Callable, Sequence
 from types import TracebackType
 from typing import AsyncContextManager, Literal, Protocol, Self, TypedDict
 
@@ -160,11 +161,14 @@ class PluginHostActivation:
         traceback: TracebackType | None,
     ) -> None: ...
 
+def load_dynamic_plugin_activation_specs(
+    plugin_config_path: str | os.PathLike[str],
+) -> list[DynamicPluginActivationSpec]: ...
 def validate(config: PluginConfig | JsonObject) -> ConfigReport: ...
 async def initialize(config: PluginConfig | JsonObject) -> ConfigReport: ...
 async def initialize_with_dynamic_plugins(
     config: PluginConfig | JsonObject,
-    dynamic_plugins: list[DynamicPluginActivationSpec | JsonObject],
+    dynamic_plugins: Sequence[DynamicPluginActivationSpec | JsonObject],
 ) -> PluginHostActivation: ...
 def clear() -> None: ...
 async def clear_async() -> None: ...