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.

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: