Declarative YAML Plugins

ContextRouter employs a declarative plugin architecture to dynamically load extended capabilities, specialized tools, and third-party connectors. This strategy ensures that the core router registration.py remains pristine while adapting perfectly to domain-specific workloads.

The Plugin Manifest (plugin.yaml)

Every plugin packaged for the Router must include a plugin.yaml manifest.

name: "my_specialized_connector"
version: "1.0.0"
description: "A secure bridge for legacy system X"
requires:
  contextrouter: ">=0.9.0"
capabilities:
  - tools
entry_point: "plugin.py"

Capability-Based Isolation

ContextUnity enforces strict security isolation inside plugins. Plugins do not receive blanket access to the global application state, the database connection pool, or environment secrets.

Instead, a plugin acts upon a PluginContext injected at startup. If a plugin attempts to register a tool or graph without explicitly declaring the required capabilities within its manifesto, the action is denied.

Loading Sequence

1. During bootstrap (via the SDK or CLI), contextunity.router scans its designated ./plugins/ directory recursively.
2. It parses the plugin.yaml manifest, validating the schema via Pydantic.
3. If requirements match and valid capabilities are requested, it negotiates a PluginContext.
4. It calls the conventional on_load(ctx) hook inside the plugin’s entry_point.

This process maps beautifully to the contextunity.project.yaml model used by project consumers, standardizing declarative capability negotiation across the entire ContextUnity ecosystem.