Skip to main content

mellea.plugins.registry

Plugin registration and helpers.

Functions​

FUNC modify ​

modify(payload: Any, **field_updates: Any) -> Any

Convenience helper for returning a modifying 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 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.

Returns:

  • A PluginResult with continue_processing=True and the modified payload.

Raises:

  • ImportError: If the ContextForge plugin framework is not installed.

FUNC block ​

block(reason: str) -> Any

Convenience helper for returning a blocking PluginResult.

Args:

  • reason: Short reason for the violation.
  • code: Machine-readable violation code.
  • description: Longer description (defaults to reason).
  • details: Additional structured details.

Returns:

  • A PluginResult with continue_processing=False and a violation.

Raises:

  • ImportError: If the ContextForge plugin framework is not installed.

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 instances, or lists thereof.

Args:

  • items: One or more plugins to register — standalone @hook functions, @plugin-decorated class instances, MelleaPlugin instances, PluginSet instances, or a list of any combination.
  • session_id: Optional session identifier. When provided, the plugins are scoped to that session and automatically deregistered on session cleanup.

Raises:

  • ImportError: If the ContextForge plugin framework is not installed.

FUNC unregister ​

unregister(items: Callable | Any | PluginSet | list[Callable | Any | PluginSet]) -> None

Unregister globally-registered plugins.

Accepts the same items as register(): standalone @hook-decorated functions, Plugin subclass instances, MelleaPlugin instances, PluginSet instances, or lists thereof.

Silently ignores items that are not currently registered.

Args:

  • items: One or more plugins to unregister — same types accepted by register().

Raises:

  • ImportError: If the ContextForge plugin framework is not installed.

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 register(): standalone @hook-decorated functions, @plugin-decorated class instances, MelleaPlugin instances, and 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.