Architecture

`

Module dependency graph

This reflects the actual import statements found in each file (intra-package imports only).

metadata and base_plugin sit at the bottom of the graph — every other module depends on them, and they depend on nothing else in the package (only the standard library). plugin_manager is the top-level façade that wires registry, loader, and security together.

Runtime object model

Startup sequence

Execution sequence

Extension points

The framework exposes three distinct extension mechanisms, all discoverable directly from the source:

1. Plugin subclassing — the primary extension point. Subclass one of RetrievalPlugin, ToolPlugin, ActionPlugin, ProcessingPlugin (or BasePlugin directly) and implement initialize(), execute(), cleanup().
2. Hooks — PluginManager.on(event, callback, priority=50) registers a callback (sync or async) for one of the events fired internally: system.startup, system.shutdown, plugin.registered, plugin.unregistered, plugin.executed, plugin.failed. Callbacks run in descending priority order.
3. Lazy loading — PluginLoader.register_lazy(name, file_path) defers importing a plugin file until load_lazy(name) is explicitly called, useful for plugins that are expensive to import.