Skip to main content
Version: Next

mellea.plugins.base

Base types for the Mellea plugin system.

Classes​

CLASS PluginMeta ​

Metadata attached to Plugin subclasses.

Args:

  • name: Unique identifier for the plugin.
  • priority: Execution priority — lower numbers execute first.

CLASS Plugin ​

Base class for multi-hook Mellea plugins.

Subclasses get automatic context-manager support and plugin metadata::

class PIIRedactor(Plugin, name="pii-redactor", priority=5): @hook(HookType.COMPONENT_PRE_EXECUTE, mode=PluginMode.SEQUENTIAL) async def redact_input(self, payload, ctx): ...

with PIIRedactor(): result = session.instruct("...")

CLASS PluginViolationError ​

Raised when a plugin blocks execution in enforce mode.

Args:

  • hook_type: The hook point where the violation occurred.
  • reason: Human-readable reason for the violation.
  • code: Machine-readable violation code.
  • plugin_name: Name of the plugin that raised the violation.

CLASS MelleaBasePayload ​

Frozen base — all payloads are immutable by design.

Plugins must use model_copy(update=\{...\}) to propose modifications and return the copy via PluginResult.modified_payload. The plugin manager applies the hook's HookPayloadPolicy to filter changes to writable fields only.

CLASS MelleaPlugin ​

Base class for Mellea plugins with lifecycle hooks and typed accessors.

Use this when you need lifecycle hooks (initialize/shutdown) or typed context accessors. For simpler plugins, prefer @hook on standalone functions or @plugin on plain classes.

Instances support the context manager protocol for temporary activation::

class MyPlugin(MelleaPlugin): def init(self): super().init(PluginConfig(name="my-plugin", hooks=[...]))

async def some_hook(self, payload, ctx): ...

with MyPlugin() as p: result, ctx = instruct("...", ctx, backend)

or async

async with MyPlugin() as p: result, ctx = await ainstruct("...", ctx, backend)

Methods:

FUNC get_backend ​

get_backend(self, context: PluginContext) -> Backend | None

Get the Backend from the plugin context.

Args:

  • context: The plugin context provided by the hook framework.

Returns:

  • The active Backend, or None if unavailable.

FUNC get_mellea_context ​

get_mellea_context(self, context: PluginContext) -> Context | None

Get the Mellea Context from the plugin context.

Args:

  • context: The plugin context provided by the hook framework.

Returns:

  • The active Mellea Context, or None if unavailable.

FUNC get_session ​

get_session(self, context: PluginContext) -> MelleaSession | None

Get the MelleaSession from the plugin context.

Args:

  • context: The plugin context provided by the hook framework.

Returns:

  • The active MelleaSession, or None if unavailable.

FUNC plugin_config ​

plugin_config(self) -> dict[str, Any]

Plugin-specific configuration from PluginConfig.config.