CPEX — ContextForge Plugin Extensibility Framework on CPEX Documentation

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Overview#

Why CPEX?#

AI systems interact with tools, APIs, data sources, and other agents. Adding guardrails, observability, or policy checks typically means embedding that logic directly into application code — leading to duplication, tight coupling, and drift.

CPEX introduces standardized interception hooks between your application and its operations. Plugins attach to these hooks and run automatically, keeping enforcement logic separate from business logic.

How It Works#

Your application defines hooks — named interception points before and after critical operations. Plugins register against these hooks and execute automatically when triggered. The plugin manager handles registration, ordering, execution, timeouts, and error isolation.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Your First Plugin in 5 Minutes#

This guide walks you through installing CPEX, writing a plugin, configuring it, and running it.

Install#

pip install cpex

What Are Plugins?#

Plugins let you intercept and modify execution at well-defined points — without changing the targeted application code.

You define hooks in your application where you want extensibility. Plugins attach to those hooks and run automatically whenever they fire.

1. Write a Plugin#

A plugin is a class that subclasses Plugin and implements one or more hook handlers. Here you will create a plugin that blocks specific tools by name.

Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Hooks#

A hook is a named interception point in your application. You define hooks where you want plugins to run, then call them at those points. The plugin manager dispatches the payload to every registered plugin and returns the combined result.

Anatomy of a Hook Handler#

Every hook handler is an async method on a Plugin subclass. It receives a typed payload and a context, and returns a result.

from cpex.framework import (
 Plugin,
 PluginContext,
 PluginResult,
 ToolPreInvokePayload,
 ToolPreInvokeResult,
)


class MyPlugin(Plugin):
 async def tool_pre_invoke(
 self, payload: ToolPreInvokePayload, context: PluginContext
 ) -> ToolPreInvokeResult:
 return ToolPreInvokeResult(continue_processing=True)

The framework validates the signature at registration time. It checks that the method:

Hook Types Reference

Mon, 01 Jan 0001 00:00:00 +0000

Hook Types Reference#

CPEX ships with built-in hooks for common AI and application operations. Each hook defines a typed payload (the data your plugin receives) and a result type (what you return). You can also register custom hooks.

Tool Hooks#

Intercept tool/function calls before execution and inspect results after.

`tool_pre_invoke`#

Fires before a tool is executed.

Field	Type	Description
`name`	`str`	Tool name
`args`	`dict[str, Any]`	Tool arguments

Payload: ToolPreInvokePayload | Result: ToolPreInvokeResult

Common Message Format

Mon, 01 Jan 0001 00:00:00 +0000

Common Message Format (CMF)#

The Common Message Format is a canonical message representation for interactions between users, agents, tools, and language models. It lets you write a single plugin that evaluates content at every interception point — tool calls, LLM input/output, resource access — using one unified interface.

Why CMF?#

Without CMF, you write separate handlers for each hook type:

async def tool_pre_invoke(self, payload: ToolPreInvokePayload, context):
 # check tool arguments for prohibited content
 ...

async def agent_pre_invoke(self, payload: AgentPreInvokePayload, context):
 # check agent messages for prohibited content — same logic, different payload
 ...

With CMF, you write the logic once and register for multiple hook points:

Execution Modes

Mon, 01 Jan 0001 00:00:00 +0000

Execution Modes#

Every plugin has an execution mode that controls whether it can block the pipeline, modify payloads, and how it runs relative to other plugins. Modes are set in the plugin’s YAML configuration.

Phase Order#

At each hook invocation, plugins are grouped by mode and dispatched in strict phase order:

sequential → transform → audit → concurrent → fire_and_forget

Within each serial phase, plugins execute in priority order — lower numbers run first (e.g., priority 10 runs before 20). The default priority is 100.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration Reference#

Plugins are configured in a YAML file. You pass the file path when creating the PluginManager:

manager = PluginManager("plugins/config.yaml")

Or set it via environment variable:

export PLUGINS_CONFIG_FILE=plugins/config.yaml
export PLUGINS_ENABLED=true

YAML Structure#

plugin_dirs:
 - ./plugins

plugins:
 - name: content_filter
 kind: my_app.plugins.ContentFilterPlugin
 version: "1.0.0"
 description: "Blocks prohibited content in tool arguments"
 author: "platform-team"
 hooks:
 - tool_pre_invoke
 tags:
 - security
 - content
 mode: sequential
 on_error: fail
 priority: 10
 conditions:
 - server_ids: [prod-gateway]
 tenant_ids: [tenant-a, tenant-b]
 config:
 blocked_patterns:
 - "DROP TABLE"
 - "rm -rf"

Plugin Fields#

Field	Type	Default	Description
`name`	`str`	required	Unique plugin identifier
`kind`	`str`	required	Fully qualified class path (e.g., `my_app.plugins.MyPlugin`), `"external"` for remote plugins, or `"isolated_venv"` for venv-isolated plugins
`version`	`str`	—	Semantic version
`description`	`str`	—	Human-readable description
`author`	`str`	—	Plugin author
`hooks`	`list[str]`	`[]`	Hook types this plugin handles
`tags`	`list[str]`	`[]`	Searchable tags
`mode`	`str`	`sequential`	Execution mode — see Execution Modes
`on_error`	`str`	`fail`	Error behavior: `fail`, `ignore`, `disable`
`priority`	`int`	`100`	Execution order within mode (lower = higher priority)
`conditions`	`list`	`[]`	When the plugin should execute
`capabilities`	`list[str]`	`[]`	Declared capabilities for extension access
`config`	`dict`	—	Plugin-specific settings passed to the constructor
`max_content_size`	`int`	`10000000`	Maximum payload size in bytes
`mcp`	`object`	—	MCP client config (for external plugins)
`grpc`	`object`	—	gRPC client config (for external plugins)
`unix_socket`	`object`	—	Unix socket client config (for external plugins)

Plugin Directories#

plugin_dirs lists directories that CPEX adds to the Python path for plugin discovery. Use this when your plugin classes live outside the main application package:

Extensions & Capabilities

Mon, 01 Jan 0001 00:00:00 +0000

Extensions & Capabilities#

Extensions carry typed contextual metadata — identity, security labels, HTTP headers, delegation chains — through the plugin pipeline. The capability system controls which plugins can see and modify which extension slots.

The Extensions Container#

Extensions is a frozen Pydantic model that attaches to payloads flowing through the pipeline. Each field is an optional typed slot:

from cpex.framework.extensions.extensions import Extensions
from cpex.framework.extensions.request import RequestExtension
from cpex.framework.extensions.security import SecurityExtension

ext = Extensions(
 request=RequestExtension(environment="production", request_id="req-001"),
 security=SecurityExtension(labels=frozenset({"pii", "confidential"})),
)

ext.request.environment # "production"
ext.security.labels # frozenset({"pii", "confidential"})
ext.http # None — not populated

Extensions are frozen. To modify, use model_copy(update={...}):

External Plugins

Mon, 01 Jan 0001 00:00:00 +0000

External Plugins#

External plugins run as standalone services — separate processes, containers, or remote hosts — connected to CPEX over MCP (Streamable HTTP), gRPC, or Unix domain sockets. You write the same Plugin subclass, but it runs in its own server process.

Why External Plugins?#

Isolation — plugin failures don’t crash the host application
Independent scaling — scale plugin servers separately from your gateway
Language independence — implement the protocol in any language (the wire format is JSON/protobuf)
Security boundaries — run untrusted plugins in sandboxed environments

Building an External Plugin Server#

Create your plugin class exactly as you would for a native plugin, then wrap it in ExternalPluginServer:

Isolated Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Isolated Plugins (venv)#

Isolated plugins run in a separate Python virtual environment, preventing their dependencies from interfering with the host application. Each plugin gets its own venv with its own requirements.txt, while still communicating with the plugin manager through the standard hook interface.

When to Use#

Conflicting dependencies — a plugin needs a different version of a library than your application
Untrusted code — run third-party plugins in a sandboxed environment
Dependency hygiene — keep the host environment clean from plugin-specific packages

Configuration#

Set kind to "isolated_venv" and provide the plugin details in the config section:

Patterns & Best Practices

Mon, 01 Jan 0001 00:00:00 +0000

Patterns & Best Practices#

Curated patterns for building production plugin pipelines.

Layered Security Pipeline#

Compose modes and priorities to build defense-in-depth. Each layer has a specific responsibility:

plugins:
 # Layer 1: hard enforcement — blocks requests that violate policy
 - name: token_budget
 kind: security.TokenBudgetPlugin
 mode: sequential
 priority: 10
 hooks: [tool_pre_invoke]

 # Layer 2: content policy — blocks prohibited content
 - name: content_policy
 kind: security.ContentPolicyPlugin
 mode: sequential
 priority: 20
 hooks: [tool_pre_invoke, agent_pre_invoke]

 # Layer 3: transformation — redacts PII without blocking
 - name: pii_redactor
 kind: privacy.PIIRedactionPlugin
 mode: transform
 priority: 30
 hooks: [tool_pre_invoke, tool_post_invoke]

 # Layer 4: background logging — never blocks or slows
 - name: audit_logger
 kind: observability.AuditLogPlugin
 mode: fire_and_forget
 priority: 100
 hooks: [tool_pre_invoke, tool_post_invoke, prompt_pre_fetch]

Execution order: token_budget (sequential) → content_policy (sequential) → pii_redactor (transform) → audit_logger (fire_and_forget). Each layer can only do what its mode permits.

Testing Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Testing Plugins#

Plugins are plain async classes — you can test them directly without the full framework. For integration testing, use PluginManager with a test configuration.

Unit Testing#

Call hook methods directly with constructed payloads and contexts. No framework overhead needed.

import pytest

from cpex.framework import (
 GlobalContext,
 PluginConfig,
 PluginContext,
 ToolPreInvokePayload,
)


@pytest.mark.asyncio
async def test_tool_blocker_blocks_dangerous_tool():
 config = PluginConfig(
 name="test_blocker",
 kind="plugins.tool_blocker.ToolBlockerPlugin",
 version="1.0.0",
 hooks=["tool_pre_invoke"],
 config={"blocked_tools": ["dangerous_tool", "admin_delete"]},
 )

 # Import your plugin class
 from plugins.tool_blocker import ToolBlockerPlugin

 plugin = ToolBlockerPlugin(config)

 payload = ToolPreInvokePayload(name="dangerous_tool", args={"target": "prod"})
 context = PluginContext(global_context=GlobalContext(request_id="test-001"))

 result = await plugin.tool_pre_invoke(payload, context)

 assert result.continue_processing is False
 assert result.violation is not None
 assert result.violation.code == "TOOL_BLOCKED"

Testing Allowed Requests#

@pytest.mark.asyncio
async def test_tool_blocker_allows_safe_tool():
 config = PluginConfig(
 name="test_blocker",
 kind="plugins.tool_blocker.ToolBlockerPlugin",
 version="1.0.0",
 hooks=["tool_pre_invoke"],
 config={"blocked_tools": ["dangerous_tool"]},
 )

 from plugins.tool_blocker import ToolBlockerPlugin

 plugin = ToolBlockerPlugin(config)

 payload = ToolPreInvokePayload(name="web_search", args={"query": "CPEX docs"})
 context = PluginContext(global_context=GlobalContext(request_id="test-002"))

 result = await plugin.tool_pre_invoke(payload, context)

 assert result.continue_processing is True
 assert result.violation is None

Testing Payload Modification#

@pytest.mark.asyncio
async def test_pii_redaction_removes_emails():
 config = PluginConfig(
 name="test_redactor",
 kind="plugins.pii.PIIRedactionPlugin",
 version="1.0.0",
 hooks=["tool_pre_invoke"],
 )

 from plugins.pii import PIIRedactionPlugin

 plugin = PIIRedactionPlugin(config)

 payload = ToolPreInvokePayload(
 name="send_email",
 args={"body": "Contact alice@example.com for details"},
 )
 context = PluginContext(global_context=GlobalContext(request_id="test-003"))

 result = await plugin.redact_pii(payload, context)

 assert result.continue_processing is True
 assert result.modified_payload is not None
 assert "alice@example.com" not in result.modified_payload.args["body"]
 assert "[REDACTED]" in result.modified_payload.args["body"]

Integration Testing#

Use PluginManager with a test configuration to verify the full pipeline — mode ordering, priority, chaining, and condition matching.

CLI Tools

Mon, 01 Jan 0001 00:00:00 +0000

CLI Tools#

CPEX includes the cpex command-line tool for scaffolding new plugin projects from templates.

Installation#

The CLI is included when you install CPEX:

pip install cpex

The cpex command becomes available in your environment. To use the bootstrap subcommand, install the CLI extras:

pip install "cpex[cli]"

`cpex bootstrap`#

Scaffolds a new plugin project from a cookiecutter template.

cpex bootstrap --destination ./my_plugin --template_type native

Options#

Flag	Short	Default	Description
`--destination`	`-d`	`.`	Output directory for the new plugin project
`--template_type`	`-t`	`native`	Template type: `native`, `external`, or `isolated`
`--template_url`	`-u`	—	Custom template URL (overrides built-in templates)
`--vcs_ref`	`-r`	`main`	Git branch/tag/commit for remote templates
`--no_input`	—	`false`	Use defaults without prompting
`--dry_run`	—	`false`	Preview what would be created without writing files

Template Types#

native — an in-process plugin with hook stubs for tools and prompts:

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

API Reference#

All public symbols are importable from cpex.framework:

from cpex.framework import Plugin, hook, PluginManager, PluginConfig, ...

Core#

Symbol	Description
`Plugin`	Base class for all plugins
`hook`	Decorator to bind a method to one or more hook types
`PluginManager`	Orchestrates plugin lifecycle and hook execution
`get_plugin_manager`	Get or initialize the singleton plugin manager

Configuration#

Symbol	Description
`PluginConfig`	Plugin configuration model (frozen)
`PluginMode`	Execution mode enum: `SEQUENTIAL`, `TRANSFORM`, `AUDIT`, `CONCURRENT`, `FIRE_AND_FORGET`, `DISABLED`
`OnError`	Error handling enum: `FAIL`, `IGNORE`, `DISABLE`
`PluginCondition`	Conditions for when a plugin should execute
`ConfigLoader`	Loads plugin configuration from YAML files
`PluginLoader`	Discovers and instantiates plugin classes

Context#

Symbol	Description
`GlobalContext`	Shared context across all plugins (request ID, user, tenant, server, state, metadata)
`PluginContext`	Per-plugin context that persists across hooks within a request lifecycle
`PluginContextTable`	Type alias: `dict[str, PluginContext]`

Results & Errors#

Symbol	Description
`PluginPayload`	Base class for all hook payloads (frozen)
`PluginResult`	Generic result from plugin hook processing
`PluginViolation`	Policy violation with reason, description, code, and details
`PluginError`	Exception for errors internal to a plugin
`PluginViolationError`	Exception wrapping a `PluginViolation`
`PluginErrorModel`	Pydantic model for plugin error details

Tool Hooks#

Symbol	Description
`ToolHookType`	Enum: `TOOL_PRE_INVOKE`, `TOOL_POST_INVOKE`
`ToolPreInvokePayload`	Payload for `tool_pre_invoke` (name, args)
`ToolPreInvokeResult`	Result type for `tool_pre_invoke`
`ToolPostInvokePayload`	Payload for `tool_post_invoke` (name, result)
`ToolPostInvokeResult`	Result type for `tool_post_invoke`

Prompt Hooks#

Symbol	Description
`PromptHookType`	Enum: `PROMPT_PRE_FETCH`, `PROMPT_POST_FETCH`
`PromptPrehookPayload`	Payload for `prompt_pre_fetch` (prompt_id, args)
`PromptPrehookResult`	Result type for `prompt_pre_fetch`
`PromptPosthookPayload`	Payload for `prompt_post_fetch` (prompt_id, result)
`PromptPosthookResult`	Result type for `prompt_post_fetch`

Resource Hooks#

Symbol	Description
`ResourceHookType`	Enum: `RESOURCE_PRE_FETCH`, `RESOURCE_POST_FETCH`
`ResourcePreFetchPayload`	Payload for `resource_pre_fetch` (uri, metadata)
`ResourcePreFetchResult`	Result type for `resource_pre_fetch`
`ResourcePostFetchPayload`	Payload for `resource_post_fetch` (uri, content)
`ResourcePostFetchResult`	Result type for `resource_post_fetch`

Agent Hooks#

Symbol	Description
`AgentHookType`	Enum: `AGENT_PRE_INVOKE`, `AGENT_POST_INVOKE`
`AgentPreInvokePayload`	Payload for `agent_pre_invoke` (agent_id, messages, tools, model, system_prompt, parameters)
`AgentPreInvokeResult`	Result type for `agent_pre_invoke`
`AgentPostInvokePayload`	Payload for `agent_post_invoke` (agent_id, messages, tool_calls)
`AgentPostInvokeResult`	Result type for `agent_post_invoke`

HTTP Hooks#

Symbol	Description
`HttpHookType`	Enum: `HTTP_PRE_REQUEST`, `HTTP_POST_REQUEST`, `HTTP_AUTH_RESOLVE_USER`, `HTTP_AUTH_CHECK_PERMISSION`
`HttpPreRequestPayload`	Payload for `http_pre_request` (path, method, client_host, client_port, headers)
`HttpPreRequestResult`	Result type for `http_pre_request`
`HttpPostRequestPayload`	Payload for `http_post_request` (extends pre-request with response_headers, status_code)
`HttpPostRequestResult`	Result type for `http_post_request`
`HttpAuthResolveUserPayload`	Payload for `http_auth_resolve_user` (credentials, headers)
`HttpAuthResolveUserResult`	Result type for `http_auth_resolve_user`
`HttpAuthCheckPermissionPayload`	Payload for `http_auth_check_permission` (user_email, permission, resource_type, …)
`HttpAuthCheckPermissionResult`	Result type for `http_auth_check_permission`
`HttpAuthCheckPermissionResultPayload`	Result payload with granted/reason fields
`HttpHeaderPayload`	HTTP headers dict wrapper

Hook Registry#

Symbol	Description
`HookRegistry`	Singleton registry mapping hook types to payload/result classes
`get_hook_registry`	Get the global `HookRegistry` instance
`HookPayloadPolicy`	Defines which payload fields plugins may modify

External Plugins#

Symbol	Description
`ExternalPluginServer`	MCP-compatible server for hosting external plugins
`MCPClientConfig`	Client-side MCP transport configuration
`MCPServerConfig`	Server-side MCP configuration
`TransportType`	Enum: `SSE`, `HTTP`, `STDIO`, `STREAMABLEHTTP`, `GRPC`

Observability#

Symbol	Description
`ObservabilityProvider`	Protocol for injecting tracing into the plugin pipeline

Utilities#

Symbol	Description
`get_attr`	Safe nested attribute access utility

CPEX — ContextForge Plugin Extensibility Framework on CPEX Documentation

Overview

Overview#

Why CPEX?#

How It Works#

Quick Start

Your First Plugin in 5 Minutes#

Install#

What Are Plugins?#

1. Write a Plugin#

Hooks

Hooks#

Anatomy of a Hook Handler#

Hook Types Reference

Hook Types Reference#

Tool Hooks#

tool_pre_invoke#

Common Message Format

Common Message Format (CMF)#

Why CMF?#

Execution Modes

Execution Modes#

Phase Order#

Configuration

Configuration Reference#

YAML Structure#

Plugin Fields#

Plugin Directories#

Extensions & Capabilities

Extensions & Capabilities#

The Extensions Container#

External Plugins

External Plugins#

Why External Plugins?#

Building an External Plugin Server#

Isolated Plugins

Isolated Plugins (venv)#

When to Use#

Configuration#

Patterns & Best Practices

Patterns & Best Practices#

Layered Security Pipeline#

Testing Plugins

Testing Plugins#

Unit Testing#

Testing Allowed Requests#

Testing Payload Modification#

Integration Testing#

CLI Tools

CLI Tools#

Installation#

cpex bootstrap#

Options#

Template Types#

API Reference

API Reference#

Core#

Configuration#

Context#

Results & Errors#

Tool Hooks#

Prompt Hooks#

Resource Hooks#

Agent Hooks#

HTTP Hooks#

Hook Registry#

External Plugins#

Observability#

Utilities#

`tool_pre_invoke`#

`cpex bootstrap`#