Skip to main content
Plugin registration and helpers.

​
Functions

​
FUNC modify 

modify(payload: Any, **field_updates: Any) -> Any
Convenience helper for returning a modifying [PluginResult](base#class-pluginresult). Creates an immutable copy of payload with field_updates applied and wraps it in a PluginResult(continue_processing=True). Only fields listed in the hook’s HookPayloadPolicy.writable_fields will be accepted by the framework; changes to read-only fields are silently discarded. Mirrors :func:block for the modification case::

​
instead of:

modified = payload.model_copy(update={“model_output”: new_mot}) return PluginResult(continue_processing=True, modified_payload=modified)

​
write:

return modify(payload, model_output=new_mot) Args:
  • payload: The original (frozen) payload received by the hook.
  • **field_updates: Fields to update on the payload copy.

​
FUNC block 

block(reason: str) -> Any
Convenience helper for returning a blocking [PluginResult](base#class-pluginresult). Args:
  • reason: Short reason for the violation.
  • code: Machine-readable violation code.
  • description: Longer description (defaults to reason).
  • details: Additional structured details.

​
FUNC register 

register(items: Callable | Any | PluginSet | list[Callable | Any | PluginSet]) -> None
Register plugins globally or for a specific session. When session_id is None, plugins are global (fire for all invocations). When session_id is provided, plugins fire only within that session. Accepts standalone @hook functions, @plugin-decorated class instances, MelleaPlugin instances, [PluginSet](pluginset#class-pluginset) instances, or lists thereof.

​
FUNC unregister 

unregister(items: Callable | Any | PluginSet | list[Callable | Any | PluginSet]) -> None
Unregister globally-registered plugins. Accepts the same items as :func:register: standalone @hook-decorated functions, [Plugin](base#class-plugin) subclass instances, MelleaPlugin instances, [PluginSet](pluginset#class-pluginset) instances, or lists thereof. Silently ignores items that are not currently registered.

​
FUNC plugin_scope 

plugin_scope(*items: Callable | Any | PluginSet) -> _PluginScope
Return a context manager that temporarily registers plugins for a block of code. Accepts the same items as :func:register: standalone @hook-decorated functions, @plugin-decorated class instances, MelleaPlugin instances, and :class:~mellea.plugins.PluginSet instances — or any mix thereof. Supports both synchronous and asynchronous with statements::

​
Sync functional API

with plugin_scope(log_hook, audit_plugin): result, ctx = instruct(“Summarize this”, ctx, backend)

​
Async functional API

async with plugin_scope(safety_hook, rate_limit_plugin): result, ctx = await ainstruct(“Generate code”, ctx, backend) Args:
  • *items: One or more plugins to register for the duration of the block.
Returns:
  • A context manager that registers the given plugins on entry and
  • deregisters them on exit.