cleveragents/cleveragents-core

Fork 3

feat(extensibility): implement Plugin Architecture Framework with module:ClassName resolution #585

New issue

Closed

opened 2026-03-04 23:46:13 +00:00 by freemo · 2 comments

freemo commented

2026-03-04 23:46:13 +00:00

Owner

Metadata

Field	Value
Commit Message	`feat(extensibility): implement Plugin Architecture Framework with module:ClassName resolution`
Branch	`feature/m6plus-plugin-architecture-framework`

Summary

Implement the plugin architecture framework that enables custom implementations of tools, strategies, sandbox strategies, index backends, UKO analyzers, and pipeline components through a module:ClassName resolution mechanism and entry point discovery. This is the foundation for all extensibility features.

Spec Reference

Section: Architecture > Extensibility > Plugin Architecture Overview
Lines: ~43942-44003

Current State

No plugin framework exists.
Config keys reference custom_module and custom_class patterns (e.g., in index backend config) but no resolution logic exists.
Tools, actors, skills, and resource types are registered via YAML configs but not via a general plugin discovery mechanism.
No entry point discovery (Python entry_points or similar).

Description

The spec defines a comprehensive extensibility model with 6 categories of extension points:

User-Facing Extensions

Custom Tools (YAML/Python)
Custom Skills (YAML)
Custom Actors (YAML/Graph)

Integration Extensions

MCP Servers (stdio/SSE)
Agent Skills Standard
Custom LLM Providers

Infrastructure Extensions

Custom Resource Types (YAML)
Custom Sandbox Strategies (Python)
Custom Index Backends (Python)

ACMS Pipeline Extensions

Custom UKO Analyzers/Vocabularies
Custom Context Strategies
Custom Pipeline Components (10 slots)

Core Plugin Resolution

The plugin framework must support:

module:ClassName resolution: Given a config like custom_module = "my_extensions.elasticsearch_backend" and custom_class = "ElasticsearchTextIndex", dynamically import the module and instantiate the class.
Entry point discovery: Discover plugins registered via Python package entry points (e.g., [cleveragents.plugins] group).
Plugin lifecycle: Four phases — discover (find), activate (prepare), execute (use), deactivate (cleanup).
Protocol validation: Verify that a loaded plugin class satisfies the expected Protocol (e.g., TextIndexBackend, SandboxStrategy, etc.).

Config-driven registration example:

[index.text]
backend = "custom"
custom_module = "my_extensions.elasticsearch_backend"
custom_class = "ElasticsearchTextIndex"

[index.text.custom_options]
hosts = ["http://localhost:9200"]

Acceptance Criteria

PluginLoader class with load_class(module_path: str, class_name: str) -> type method
Dynamic import and instantiation from module:ClassName strings
Entry point discovery: scan cleveragents.plugins entry point group
Protocol validation: verify loaded class satisfies expected Protocol before use
Clear error messages on plugin load failure (module not found, class not found, protocol mismatch)
Plugin lifecycle management: discover → activate → execute → deactivate
Config-driven registration: custom_module + custom_class + custom_options pattern
Integration with existing registries: ToolRegistry, ProviderRegistry, etc.
Security: plugins cannot access internals outside their defined Protocol
Unit tests for module resolution, protocol validation, lifecycle management
Integration test: register a custom TextIndexBackend via config, verify it's used

Foundation for: Custom Sandbox Strategies, Custom Index Backends, Custom UKO Analyzers, Custom Pipeline Components
Parent epic: Extensibility

Suggested Milestone

v3.6.0

Priority

Low

Suggested Assignee

@freemo — Architecture/plugin system design

Subtasks

Code: Implement PluginLoader class with load_class(module_path, class_name) for module:ClassName resolution and dynamic import
Code: Implement entry point discovery (scan cleveragents.plugins group) and Protocol validation
Code: Implement plugin lifecycle management (discover → activate → execute → deactivate) and config-driven registration (custom_module + custom_class + custom_options)
Code: Integrate with existing registries (ToolRegistry, ProviderRegistry, etc.)
Docs: Document the plugin architecture, extension points, and registration patterns
Behave tests: Add BDD feature file features/extensibility/plugin_architecture.feature covering module resolution, protocol validation, and lifecycle
Robot tests: Add Robot Framework integration test: register custom TextIndexBackend via config, verify it's used
ASV benchmarks: Add ASV benchmark for plugin loading and resolution overhead (benchmarks/bench_plugin_loader.py)
Quality: coverage ≥97%: Verify via nox -s coverage_report
Quality: nox full suite: Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks below are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Field | Value | |-------|-------| | **Commit Message** | `feat(extensibility): implement Plugin Architecture Framework with module:ClassName resolution` | | **Branch** | `feature/m6plus-plugin-architecture-framework` | ## Summary Implement the plugin architecture framework that enables custom implementations of tools, strategies, sandbox strategies, index backends, UKO analyzers, and pipeline components through a `module:ClassName` resolution mechanism and entry point discovery. This is the foundation for all extensibility features. ## Spec Reference **Section**: Architecture > Extensibility > Plugin Architecture Overview **Lines**: ~43942-44003 ## Current State - No plugin framework exists. - Config keys reference `custom_module` and `custom_class` patterns (e.g., in index backend config) but no resolution logic exists. - Tools, actors, skills, and resource types are registered via YAML configs but not via a general plugin discovery mechanism. - No entry point discovery (Python `entry_points` or similar). ## Description The spec defines a comprehensive extensibility model with 6 categories of extension points: ### User-Facing Extensions - Custom Tools (YAML/Python) - Custom Skills (YAML) - Custom Actors (YAML/Graph) ### Integration Extensions - MCP Servers (stdio/SSE) - Agent Skills Standard - Custom LLM Providers ### Infrastructure Extensions - Custom Resource Types (YAML) - Custom Sandbox Strategies (Python) - Custom Index Backends (Python) ### ACMS Pipeline Extensions - Custom UKO Analyzers/Vocabularies - Custom Context Strategies - Custom Pipeline Components (10 slots) ### Core Plugin Resolution The plugin framework must support: 1. **`module:ClassName` resolution**: Given a config like `custom_module = "my_extensions.elasticsearch_backend"` and `custom_class = "ElasticsearchTextIndex"`, dynamically import the module and instantiate the class. 2. **Entry point discovery**: Discover plugins registered via Python package entry points (e.g., `[cleveragents.plugins]` group). 3. **Plugin lifecycle**: Four phases — `discover` (find), `activate` (prepare), `execute` (use), `deactivate` (cleanup). 4. **Protocol validation**: Verify that a loaded plugin class satisfies the expected Protocol (e.g., `TextIndexBackend`, `SandboxStrategy`, etc.). ### Config-driven registration example: ```toml [index.text] backend = "custom" custom_module = "my_extensions.elasticsearch_backend" custom_class = "ElasticsearchTextIndex" [index.text.custom_options] hosts = ["http://localhost:9200"] ``` ## Acceptance Criteria - [ ] `PluginLoader` class with `load_class(module_path: str, class_name: str) -> type` method - [ ] Dynamic import and instantiation from `module:ClassName` strings - [ ] Entry point discovery: scan `cleveragents.plugins` entry point group - [ ] Protocol validation: verify loaded class satisfies expected Protocol before use - [ ] Clear error messages on plugin load failure (module not found, class not found, protocol mismatch) - [ ] Plugin lifecycle management: discover → activate → execute → deactivate - [ ] Config-driven registration: `custom_module` + `custom_class` + `custom_options` pattern - [ ] Integration with existing registries: ToolRegistry, ProviderRegistry, etc. - [ ] Security: plugins cannot access internals outside their defined Protocol - [ ] Unit tests for module resolution, protocol validation, lifecycle management - [ ] Integration test: register a custom TextIndexBackend via config, verify it's used ## Related Issues - Foundation for: Custom Sandbox Strategies, Custom Index Backends, Custom UKO Analyzers, Custom Pipeline Components - Parent epic: Extensibility ## Suggested Milestone v3.6.0 ## Priority Low ## Suggested Assignee @freemo — Architecture/plugin system design ## Subtasks - [ ] **Code**: Implement `PluginLoader` class with `load_class(module_path, class_name)` for `module:ClassName` resolution and dynamic import - [ ] **Code**: Implement entry point discovery (scan `cleveragents.plugins` group) and Protocol validation - [ ] **Code**: Implement plugin lifecycle management (discover → activate → execute → deactivate) and config-driven registration (`custom_module` + `custom_class` + `custom_options`) - [ ] **Code**: Integrate with existing registries (ToolRegistry, ProviderRegistry, etc.) - [ ] **Docs**: Document the plugin architecture, extension points, and registration patterns - [ ] **Behave tests**: Add BDD feature file `features/extensibility/plugin_architecture.feature` covering module resolution, protocol validation, and lifecycle - [ ] **Robot tests**: Add Robot Framework integration test: register custom TextIndexBackend via config, verify it's used - [ ] **ASV benchmarks**: Add ASV benchmark for plugin loading and resolution overhead (`benchmarks/bench_plugin_loader.py`) - [ ] **Quality: coverage ≥97%**: Verify via `nox -s coverage_report` - [ ] **Quality: nox full suite**: Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks below are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.

freemo self-assigned this

2026-03-05 00:30:27 +00:00

freemo added this to the v3.6.0 milestone

2026-03-05 00:30:27 +00:00

freemo added the

labels

2026-03-05 00:30:27 +00:00

freemo added

and removed

labels

2026-03-09 21:42:14 +00:00

freemo commented

2026-03-09 21:45:25 +00:00

Author

Owner

Implementation Started

Beginning work on the Plugin Architecture Framework. Plan:

PluginLoader (src/cleveragents/infrastructure/plugins/loader.py) - dynamic import via module:ClassName, entry point discovery, Protocol validation
PluginManager (src/cleveragents/infrastructure/plugins/manager.py) - lifecycle management (discover/activate/execute/deactivate), config-driven registration
Exceptions (src/cleveragents/infrastructure/plugins/exceptions.py) - PluginLoadError, PluginNotFoundError, ProtocolMismatchError
Types (src/cleveragents/infrastructure/plugins/types.py) - PluginDescriptor, PluginState, ExtensionPoint
Registry integration - Extension point hooks for ToolRegistry, ProviderRegistry
Tests - Behave BDD, Robot Framework, ASV benchmarks

Starting implementation now.

## Implementation Started Beginning work on the Plugin Architecture Framework. Plan: 1. **PluginLoader** (`src/cleveragents/infrastructure/plugins/loader.py`) - dynamic import via `module:ClassName`, entry point discovery, Protocol validation 2. **PluginManager** (`src/cleveragents/infrastructure/plugins/manager.py`) - lifecycle management (discover/activate/execute/deactivate), config-driven registration 3. **Exceptions** (`src/cleveragents/infrastructure/plugins/exceptions.py`) - PluginLoadError, PluginNotFoundError, ProtocolMismatchError 4. **Types** (`src/cleveragents/infrastructure/plugins/types.py`) - PluginDescriptor, PluginState, ExtensionPoint 5. **Registry integration** - Extension point hooks for ToolRegistry, ProviderRegistry 6. **Tests** - Behave BDD, Robot Framework, ASV benchmarks Starting implementation now.

freemo referenced this issue from a commit

2026-03-10 02:53:08 +00:00

feat(extensibility): implement Plugin Architecture Framework with module:ClassName resolution

freemo referenced this issue from a pull request that will close it,

2026-03-10 03:07:24 +00:00

feat(extensibility): implement Plugin Architecture Framework with module:ClassName resolution #666

freemo added

and removed

labels

2026-03-10 03:46:24 +00:00

freemo commented

2026-03-10 04:05:06 +00:00

Author

Owner

Implementation Complete

Branch: feature/m6plus-plugin-architecture-framework
PR: #666
Commit: 83fa4133

Files Created

src/cleveragents/infrastructure/plugins/__init__.py — Package exports
src/cleveragents/infrastructure/plugins/types.py — PluginState, ExtensionPoint, PluginDescriptor
src/cleveragents/infrastructure/plugins/exceptions.py — PluginError, PluginLoadError, PluginNotFoundError, ProtocolMismatchError
src/cleveragents/infrastructure/plugins/loader.py — PluginLoader with load_class(), load_from_entry_points(), validate_protocol()
src/cleveragents/infrastructure/plugins/manager.py — PluginManager with lifecycle, config-driven registration
features/extensibility/plugin_architecture.feature — 48 BDD scenarios
features/steps/plugin_architecture_steps.py — Step definitions
robot/plugin_architecture.robot — 10 Robot integration tests
robot/helper_plugin_architecture.py — Robot helper
benchmarks/bench_plugin_loader.py — ASV benchmarks

Files Modified

src/cleveragents/application/container.py — Register PluginManager as Singleton

Nox Results

lint ✅
typecheck ✅ (0 errors)
unit_tests ✅ (9776 scenarios, 0 failures)
integration_tests ✅ (10/10 robot tests passed)
coverage_report: 98.5% (threshold: 97%)

## Implementation Complete **Branch**: `feature/m6plus-plugin-architecture-framework` **PR**: #666 **Commit**: `83fa4133` ### Files Created - `src/cleveragents/infrastructure/plugins/__init__.py` — Package exports - `src/cleveragents/infrastructure/plugins/types.py` — `PluginState`, `ExtensionPoint`, `PluginDescriptor` - `src/cleveragents/infrastructure/plugins/exceptions.py` — `PluginError`, `PluginLoadError`, `PluginNotFoundError`, `ProtocolMismatchError` - `src/cleveragents/infrastructure/plugins/loader.py` — `PluginLoader` with `load_class()`, `load_from_entry_points()`, `validate_protocol()` - `src/cleveragents/infrastructure/plugins/manager.py` — `PluginManager` with lifecycle, config-driven registration - `features/extensibility/plugin_architecture.feature` — 48 BDD scenarios - `features/steps/plugin_architecture_steps.py` — Step definitions - `robot/plugin_architecture.robot` — 10 Robot integration tests - `robot/helper_plugin_architecture.py` — Robot helper - `benchmarks/bench_plugin_loader.py` — ASV benchmarks ### Files Modified - `src/cleveragents/application/container.py` — Register `PluginManager` as Singleton ### Nox Results - `lint` ✅ - `typecheck` ✅ (0 errors) - `unit_tests` ✅ (9776 scenarios, 0 failures) - `integration_tests` ✅ (10/10 robot tests passed) - `coverage_report`: **98.5%** (threshold: 97%)

freemo referenced this issue from a commit

2026-03-10 14:51:41 +00:00

feat(extensibility): implement Plugin Architecture Framework with module:ClassName resolution

freemo closed this issue

2026-03-10 14:58:30 +00:00

freemo referenced this issue

2026-04-06 07:38:50 +00:00

UAT: PluginManager missing get_extension_point(name) public method — only O(n) list scan available #3939

freemo added a new dependency

2026-04-06 07:39:03 +00:00

#3939 UAT: PluginManager missing get_extension_point(name) public method — only O(n) list scan available