Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mellea.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.