plugins

Mellea Plugins

This directory contains examples of extending Mellea with custom plugins—hooks for observability, modification, and control over the generation pipeline.

Prerequisites

These examples require a running Ollama instance:

ollama serve

Examples

Quick Start

uv run quickstart.py

Demonstrates:

• Registering a single hook function
• Using HookType.GENERATION_PRE_CALL to log before LLM calls
• Minimal plugin setup (30 lines)

Standalone Hooks

uv run standalone_hooks.py

Demonstrates:

• Function-based hooks without a class
• Token budget enforcement
• Generation latency monitoring
• Multiple hook types in one program

Class-Based Plugins

uv run class_plugin.py

Demonstrates:

• Organizing hooks in a Plugin subclass
• PII protection patterns
• Input blocking before execution
• Output scanning (observe-only)

Execution Modes

uv run execution_modes.py

Demonstrates:

• All five PluginMode execution strategies:
  • SEQUENTIAL — serial, can block and modify
  • TRANSFORM — serial, modify-only
  • AUDIT — serial, observe-only
  • CONCURRENT — parallel, can block
  • FIRE_AND_FORGET — background, observe-only

Plugin Set Composition

uv run plugin_set_composition.py

Demonstrates:

• Grouping related hooks into PluginSets
• Global vs. per-session registration
• Organizing by concern (security, observability)

Session-Scoped Plugins

uv run session_scoped.py

Demonstrates:

• Global hooks (fire for all sessions)
• Per-session plugins (fire only in specific session)
• Content policy enforcement by session

Scoped Plugins

uv run plugin_scoped.py

Demonstrates:

• Plugin activation for specific code blocks
• plugin_scope() context manager for multiple plugins
• Plugin subclasses as context managers
• PluginSet as a context manager
• Automatic deregistration on block exit

Payload Modification

uv run payload_modification.py

Demonstrates:

• Using modify() to change payload fields
• Model copying with model_copy(update={...})
• Handling read-only vs. writable fields

Tool Hooks

uv run tool_hooks.py

Demonstrates:

• TOOL_PRE_INVOKE and TOOL_POST_INVOKE hooks
• Tool allow-listing
• Argument validation and sanitization
• Tool call auditing

Testing Plugins

uv run testing_plugins.py

Demonstrates:

• Unit-testing hooks without a live session
• Constructing payloads manually
• Direct hook invocation with await
• Testing blocking and pass-through behavior

Hook Types

Mellea supports hooks at various stages of the generation pipeline:

• GENERATION_PRE_CALL — Before LLM call
• GENERATION_POST_CALL — After LLM call
• SESSION_CREATE — On session creation
• SESSION_DESTROY — On session cleanup
• (See mellea.plugins.HookType for complete list)

Key Concepts

Hooks: Functions that execute at specific pipeline stages, allowing observation and modification of Mellea's behavior.

Payload Modification: Hooks can transform request/response payloads before/after LLM calls.

Session Scope: Plugins can be registered globally or per-session.

Async Support: Hooks can be synchronous or asynchronous.

See Also

• ../telemetry/ — Monitoring and metrics collection
• ../requirements/ — Custom validation logic
• Documentation: mellea.plugins module