nemo_flow.plugin#

Generic plugin configuration and registration helpers.

This module exposes the top-level plugin system used to validate and activate adaptive and custom plugin components. Component registration names are scoped per component by the runtime, so end users do not provide instance ids.

Classes#

`ConfigDiagnostic`	One plugin validation diagnostic.
`ConfigReport`	Validation or activation report for a plugin config.
`PluginContext`	Component-scoped registration context passed to custom plugin handlers.
`Plugin`	Custom plugin callback contract.
`ConfigPolicy`	Policy for unsupported plugin configuration.
`ComponentSpec`	One top-level custom plugin component.
`PluginConfig`	Canonical plugin configuration document.

Functions#

`validate`(config)	Validate a plugin configuration without changing runtime state.
`initialize`(config)	Validate and activate a plugin configuration.
`clear`()	Clear the active plugin configuration.
`report`()	Return the last successful plugin report.
`list_kinds`()	List registered custom plugin kinds.
`register`(plugin_kind, plugin)	Register a custom plugin implementation.
`deregister`(plugin_kind)	Deregister a custom plugin kind.

Module Contents#

class nemo_flow.plugin.ConfigDiagnostic#

Bases: _ConfigDiagnosticRequired

One plugin validation diagnostic.

component: str#

field: str#

class nemo_flow.plugin.ConfigReport#

Bases: TypedDict

Validation or activation report for a plugin config.

diagnostics: list[ConfigDiagnostic]#

class nemo_flow.plugin.PluginContext#

Bases: Protocol

Component-scoped registration context passed to custom plugin handlers.

register_subscriber( name: str, callback: Callable[[nemo_flow.Event], None], ) → None#: Register an infallible event subscriber for this component.

register_tool_sanitize_request_guardrail( name: str, priority: int, callback: nemo_flow.ToolSanitizeGuardrail, ) → None#: Register a tool sanitize-request guardrail for this component.

register_tool_sanitize_response_guardrail( name: str, priority: int, callback: nemo_flow.ToolSanitizeGuardrail, ) → None#: Register a tool sanitize-response guardrail for this component.

register_tool_conditional_execution_guardrail( name: str, priority: int, callback: nemo_flow.ToolConditionalExecutionGuardrail, ) → None#: Register a tool conditional-execution guardrail for this component.

register_llm_sanitize_request_guardrail( name: str, priority: int, callback: nemo_flow.LlmSanitizeRequestGuardrail, ) → None#: Register an LLM sanitize-request guardrail for this component.

register_llm_sanitize_response_guardrail( name: str, priority: int, callback: nemo_flow.LlmSanitizeResponseGuardrail, ) → None#: Register an LLM sanitize-response guardrail for this component.

register_llm_conditional_execution_guardrail( name: str, priority: int, callback: nemo_flow.LlmConditionalExecutionGuardrail, ) → None#: Register an LLM conditional-execution guardrail for this component.

register_llm_request_intercept( name: str, priority: int, break_chain: bool, callback: nemo_flow.LlmRequestIntercept, ) → None#: Register an LLM request intercept for this component.

register_llm_execution_intercept( name: str, priority: int, callback: nemo_flow.LlmExecutionIntercept, ) → None#: Register an LLM execution intercept for this component.

register_llm_stream_execution_intercept( name: str, priority: int, callback: nemo_flow.LlmStreamExecutionIntercept, ) → None#: Register an LLM streaming execution intercept for this component.

register_tool_request_intercept( name: str, priority: int, break_chain: bool, callback: nemo_flow.ToolRequestIntercept, ) → None#: Register a tool request intercept for this component.

register_tool_execution_intercept( name: str, priority: int, callback: nemo_flow.ToolExecutionIntercept, ) → None#: Register a tool execution intercept for this component.

class nemo_flow.plugin.Plugin#

Bases: Protocol

Custom plugin callback contract.

validate( plugin_config: nemo_flow.JsonObject, ) → list[ConfigDiagnostic] | None#

Validate one component-local config object.

Parameters:: plugin_config – The config object from a single component.
Returns:: A list of diagnostics, or None for no diagnostics.

Behavior:: Error diagnostics block initialize(…).

register( plugin_config: nemo_flow.JsonObject, context: PluginContext, ) → None#

Install middleware and subscribers for one component instance.

Parameters:

plugin_config – The config object from a single component.
context – Component-scoped registration context used to install middleware and subscribers.

Returns:

None.

Behavior:: Any exception aborts the current initialization and triggers rollback of partial registrations.

class nemo_flow.plugin.ConfigPolicy#

Policy for unsupported plugin configuration.

Parameters:

unknown_component – How to handle unknown component kinds.
unknown_field – How to handle unknown fields inside known components.
unsupported_value – How to handle known fields with unsupported values.

Behavior:: “warn” emits a warning diagnostic, “error” emits an error diagnostic that blocks initialization, and “ignore” suppresses the diagnostic entirely.

unknown_component: nemo_flow.UnsupportedBehavior = 'warn'#

unknown_field: nemo_flow.UnsupportedBehavior = 'warn'#

unsupported_value: nemo_flow.UnsupportedBehavior = 'error'#

to_dict() → nemo_flow.JsonObject#: Serialize this policy to the canonical JSON object shape.

class nemo_flow.plugin.ComponentSpec#

One top-level custom plugin component.

Parameters:

kind – Registered plugin kind string.
enabled – Whether the component should be activated.
config – Component-local JSON config object.

Behavior:: Disabled components are still validated but skipped during runtime registration.

kind: str#

enabled: bool = True#

config: nemo_flow.JsonObject#

to_dict() → nemo_flow.JsonObject#: Serialize this component to the canonical JSON object shape.

class nemo_flow.plugin.PluginConfig#

Canonical plugin configuration document.

Parameters:

version – Plugin config schema version.
components – Ordered list of top-level components. This may mix plugin.ComponentSpec(…) and adaptive.ComponentSpec(…).
policy – Plugin-level unsupported-config policy.

Behavior:: Component order is preserved during initialization.

version: int = 1#

components: list[object] = []#

policy: ConfigPolicy#

to_dict() → nemo_flow.JsonObject#: Serialize this config to the canonical JSON document shape.

nemo_flow.plugin.validate(config: PluginConfig | nemo_flow.JsonObject) → ConfigReport#

Validate a plugin configuration without changing runtime state.

Parameters:: config – PluginConfig or an equivalent JSON object.
Returns:: The validation report for the supplied config.

Behavior:: Validation checks plugin-level compatibility, unknown component kinds, multiplicity rules, and per-plugin validation logic.

async nemo_flow.plugin.initialize( config: PluginConfig | nemo_flow.JsonObject, ) → ConfigReport#

Validate and activate a plugin configuration.

Parameters:: config – PluginConfig or an equivalent JSON object.
Returns:: The report for the successfully activated configuration.

Behavior:: Initialization replaces the current active plugin configuration. Partial registration is rolled back on failure, and the previous configuration is restored when possible.

nemo_flow.plugin.clear() → None#

Clear the active plugin configuration.

Returns:: None.

Behavior:: This removes active component registrations but leaves the plugin kind registry intact for future validation or initialization.

nemo_flow.plugin.report() → ConfigReport | None#

Return the last successful plugin report.

Returns:: The active ConfigReport, or None when no plugin configuration is currently active.

Behavior:: This reports the last successfully activated configuration snapshot. It does not revalidate plugin state or inspect pending registrations.

nemo_flow.plugin.list_kinds() → list[str]#

List registered custom plugin kinds.

Returns:: A sorted list of plugin kind strings known to the plugin registry.

Behavior:: This reports available plugin kinds, not the currently active component set.

nemo_flow.plugin.register(plugin_kind: str, plugin: Plugin) → None#

Register a custom plugin implementation.

Parameters:

plugin_kind – Unique top-level component kind string.
plugin – Custom plugin implementation.

Returns:

None.

Behavior:: Registering the same kind twice raises an error.

nemo_flow.plugin.deregister(plugin_kind: str) → bool#

Deregister a custom plugin kind.

Parameters:: plugin_kind – Kind string to remove from the plugin registry.
Returns:: True if a plugin was removed, otherwise False.

Behavior:: This affects future validation and initialization only. Active runtime registrations remain until clear() or the next successful initialize(…).