> ## 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.

# mellea.plugins.registry

> Plugin registration and helpers.

export const SidebarFix = () => <script dangerouslySetInnerHTML={{
  __html: `
        (function () {
          const INTERVAL_MS = 500;

          const upgradeSidebar = () => {
            const links = document.querySelectorAll('a[href^="#"]');

            links.forEach((link) => {
              if (link.dataset.badged === "true") return;

              const rawText = (link.textContent || "").trim();

              // ========== FUNC ==========
              if (rawText.startsWith("FUNC ")) {
                const label = rawText.replace(/^FUNC\\s+/, "").trim();

                while (link.firstChild) link.removeChild(link.firstChild);

                // 👉 Make the whole link a single flex row & prevent wrapping
                link.style.display = "flex";
                link.style.alignItems = "center";
                link.style.whiteSpace = "nowrap";
                link.style.columnGap = "0.5rem";

                const badge = document.createElement("span");
                badge.style.marginRight = "0.5rem";
                badge.style.display = "inline-flex";
                badge.style.alignItems = "center";
                badge.style.borderRadius = "9999px";
                badge.style.padding = "0rem 0.6rem";
                badge.style.fontSize = "0.5rem";
                badge.style.fontWeight = "700";
                badge.style.letterSpacing = "0.05em";
                badge.style.backgroundColor = "rgba(48, 100, 227, 0.20)";
                badge.style.color = "#1D4ED8";

                badge.textContent = "FUNC";

                link.appendChild(badge);
                link.appendChild(document.createTextNode(label));
                link.dataset.badged = "true";
                return;
              }

              // ========== CLASS ==========
              if (rawText.startsWith("CLASS ")) {
                const label = rawText.replace(/^CLASS\\s+/, "").trim();

                while (link.firstChild) link.removeChild(link.firstChild);

                // 👉 Same flex / nowrap treatment for class links
                link.style.display = "flex";
                link.style.alignItems = "center";
                link.style.whiteSpace = "nowrap";
                link.style.columnGap = "0.5rem";

                const badge = document.createElement("span");
                badge.style.marginRight = "0.5rem";
                badge.style.display = "inline-flex";
                badge.style.alignItems = "center";
                badge.style.borderRadius = "9999px";
                badge.style.padding = "0rem 0.6rem";
                badge.style.fontSize = "0.5rem";
                badge.style.fontWeight = "700";
                badge.style.letterSpacing = "0.05em";
                badge.style.backgroundColor = "rgba(74, 222, 128, 0.20)";
                badge.style.color = "#15803D";

                badge.textContent = "CLASS";

                link.appendChild(badge);
                link.appendChild(document.createTextNode(label));
                link.dataset.badged = "true";
                return;
              }
            });
          };

          upgradeSidebar();
          setInterval(upgradeSidebar, INTERVAL_MS);
        })();
      `
}} />;

<SidebarFix />

Plugin registration and helpers.

## Functions

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `modify` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/plugins/registry.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
modify(payload: Any, **field_updates: Any) -> Any
```

Convenience helper for returning a modifying [`PluginResult`](base#class-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`](base#class-pluginresult) with `continue_processing=True` and the modified payload.

**Raises:**

* `ImportError`: If the ContextForge plugin framework is not installed.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `block` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/plugins/registry.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
block(reason: str) -> Any
```

Convenience helper for returning a blocking [`PluginResult`](base#class-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`](base#class-pluginresult) with `continue_processing=False` and a violation.

**Raises:**

* `ImportError`: If the ContextForge plugin framework is not installed.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `register` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/plugins/registry.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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`](pluginset#class-pluginset) instances, or lists thereof.

**Args:**

* `items`: One or more plugins to register — standalone `@hook` functions,
  `@plugin`-decorated class instances, `MelleaPlugin` instances,
  [`PluginSet`](pluginset#class-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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `unregister` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/plugins/registry.py#L473" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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`](base#class-plugin) subclass instances, `MelleaPlugin` instances,
[`PluginSet`](pluginset#class-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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `plugin_scope` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/plugins/registry.py#L514" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
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`](pluginset#class-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.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />