Skip to main content
Version: 0.7.0

mellea.plugins.manager

Singleton plugin manager wrapper with session-tag filtering.

Functions​

FUNC enable_background_collection ​

enable_background_collection() -> None

Enable fire-and-forget result collection. Call in test fixtures before each test.

FUNC disable_background_collection ​

disable_background_collection() -> None

Disable fire-and-forget result collection and clear any accumulated results.

FUNC drain_background_tasks ​

drain_background_tasks() -> None

Await all accumulated FIRE_AND_FORGET tasks and clear the pending list.

Call this in tests after any operation that may have triggered fire-and-forget plugins, to ensure side effects (metrics recording, etc.) complete before assertions.

FUNC discard_background_tasks ​

discard_background_tasks() -> None

Discard all accumulated FIRE_AND_FORGET tasks without awaiting them.

Call this in test fixtures to clear stale results from a previous event loop before running the next test.

FUNC has_plugins ​

has_plugins(hook_type: HookType | None = None) -> bool

Fast check: are plugins configured and available for the given hook type.

When hook_type is provided, also checks whether any plugin has registered a handler for that specific hook, enabling callers to skip payload construction entirely when no plugin subscribes.

Args:

  • hook_type: Optional hook type to check for registered handlers.

Returns:

  • True if plugins are enabled and (when hook_type is given)
  • at least one plugin subscribes to that hook.

FUNC is_internal_tool ​

is_internal_tool(tool_name: str) -> bool

Return whether the given tool name is a framework-internal tool.

Args:

  • tool_name: Name of the tool to check.

Returns:

  • True if the tool is in the internal tools registry.

FUNC get_plugin_manager ​

get_plugin_manager() -> Any | None

Return the initialized PluginManager, or None if plugins are not configured.

Returns:

  • The singleton PluginManager instance, or None.

FUNC ensure_plugin_manager ​

ensure_plugin_manager() -> Any

Lazily initialize the PluginManager if not already created.

Returns:

  • The singleton PluginManager instance.

Raises:

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

FUNC initialize_plugins ​

initialize_plugins(config_path: str | None = None) -> Any

Initialize the PluginManager with Mellea hook registrations and optional YAML config.

Args:

  • config_path: Optional path to a YAML plugin configuration file.
  • timeout: Maximum execution time per plugin in seconds.

Returns:

  • The initialized PluginManager instance.

Raises:

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

FUNC shutdown_plugins ​

shutdown_plugins() -> None

Shut down the PluginManager and reset all state.

FUNC track_session_plugin ​

track_session_plugin(session_id: str, plugin_name: str) -> None

Track a plugin as belonging to a session for later deregistration.

Args:

  • session_id: Identifier for the session that owns the plugin.
  • plugin_name: Registered name of the plugin.

FUNC deregister_session_plugins ​

deregister_session_plugins(session_id: str) -> None

Deregister all plugins scoped to the given session.

Args:

  • session_id: Identifier for the session whose plugins should be removed.

FUNC invoke_hook ​

invoke_hook(hook_type: HookType, payload: _MelleaBasePayload, **context_fields: Any) -> tuple[Any | None, _MelleaBasePayload]

Invoke a hook if plugins are configured.

Returns (result, possibly-modified-payload). If plugins are not configured, returns (None, original_payload) immediately.

Three layers of no-op guards ensure zero overhead when plugins are not configured:

  1. _plugins_enabled boolean — single pointer dereference
  2. has_hooks_for(hook_type) — skips when no plugin subscribes
  3. Returns immediately when either guard fails

Args:

  • hook_type: The hook point to invoke.
  • payload: The immutable payload to pass to plugin handlers.
  • backend: Optional backend for building the global context.
  • **context_fields: Additional fields passed to build_global_context.

Returns:

  • A (result, payload) tuple where result is the PluginResult
  • (or None when no plugins ran) and payload is the
  • possibly-modified payload.

Raises: