🧭 Epic

Title: Improve Plugin Framework Hygiene

Goal: Enhance the plugin infrastructure with better isolation, configurability, maturity tracking, and quality standards to ensure production-ready plugin ecosystem.

Why now:

• Plugins are becoming critical for enterprise deployments (IAM, content moderation, PII filtering)
• Current plugin configuration is complex and error-prone
• No isolation between plugins risks one plugin affecting others
• No maturity model makes it hard to assess plugin readiness
• Need clear quality standards for production use

📖 User Stories

Scenario: Plugin runs in isolated venv
  Given I have a plugin with dependency "transformers==4.35.0"
  And another plugin requires "transformers==4.30.0"
  When both plugins are loaded
  Then each plugin should have its own virtual environment
  And both plugins should function correctly with their respective versions

Scenario: Plugin venv is created automatically
  Given I register a new native Python plugin
  When the plugin is loaded for the first time
  Then a virtual environment should be created for the plugin
  And the plugin's requirements.txt should be installed
  And the venv location should be logged

Scenario: Plugin venv is reused on restart
  Given a plugin has an existing virtual environment
  When the gateway restarts
  Then the existing venv should be reused
  And dependencies should not be reinstalled unless changed

Scenario: Enable plugin with minimal config
  Given the PII filter plugin is available
  When I add configuration:
    ```yaml
    plugins:
      pii_filter:
        enabled: true
    ```
  Then the plugin should be enabled with default settings
  And no additional configuration should be required

Scenario: Override specific settings
  Given a plugin has default configuration
  When I specify only the settings I want to change
  Then only those settings should be overridden
  And all other settings should use defaults

Scenario: Validate configuration on startup
  Given I have plugin configuration
  When the gateway starts
  Then configuration should be validated against the plugin's schema
  And invalid configuration should produce clear error messages
  And the gateway should fail fast with configuration errors

Scenario: View plugin maturity level
  Given I am viewing the plugin catalog
  When I look at a plugin's information
  Then I should see its maturity level (alpha, beta, stable, deprecated)
  And I should see its quality metrics (test coverage, security audit status)

Scenario: Filter plugins by maturity
  Given the plugin catalog has plugins at various maturity levels
  When I filter by maturity="stable"
  Then only production-ready plugins should be shown

Scenario: Maturity requirements for production
  Given I enable a plugin marked as "alpha"
  When I deploy to production environment
  Then I should see a warning about plugin maturity
  And the warning should be logged

Scenario: List available plugins
  Given multiple plugins are available (builtin and external)
  When I query the plugin registry
  Then I should see all available plugins
  And each plugin should have name, description, version, maturity

Scenario: View plugin capabilities
  Given I want to understand what a plugin does
  When I view the plugin's manifest
  Then I should see which hooks it implements
  And I should see its configuration schema
  And I should see its dependencies

Scenario: Search plugins by capability
  Given I need a plugin for content moderation
  When I search the registry with keywords "content moderation"
  Then I should see relevant plugins
  And results should be ranked by relevance

🏗 Architecture

Plugin Isolation Model

flowchart TD
    subgraph Gateway Process
        PM[Plugin Manager]
        GC[Global Context]
    end
    
    subgraph Plugin A venv
        PA[Plugin A Code]
        DA[Dependencies A]
    end
    
    subgraph Plugin B venv
        PB[Plugin B Code]
        DB[Dependencies B]
    end
    
    subgraph Plugin C venv
        PC[Plugin C Code]
        DC[Dependencies C]
    end
    
    PM --> PA
    PM --> PB
    PM --> PC
    GC --> PM

Maturity Model

flowchart LR
    A[Alpha] -->|"Testing<br/>Coverage >50%"| B[Beta]
    B -->|"Security Audit<br/>Coverage >80%"| C[Stable]
    C -->|"End of Life"| D[Deprecated]
    
    style A fill:#ff9999
    style B fill:#ffcc99
    style C fill:#99ff99
    style D fill:#cccccc

Plugin Configuration Flow

sequenceDiagram
    participant User as User Config
    participant PM as Plugin Manager
    participant Schema as JSON Schema
    participant Plugin as Plugin

    User->>PM: Load configuration
    PM->>PM: Load plugin defaults
    PM->>PM: Merge user config with defaults
    PM->>Schema: Validate merged config
    
    alt Valid config
        Schema-->>PM: Valid
        PM->>Plugin: Initialize with config
    else Invalid config
        Schema-->>PM: Validation errors
        PM->>User: Clear error message
    end

📋 Implementation Tasks

Phase 1: Virtual Environment Isolation

• Design venv directory structure per plugin
• Implement venv creation on plugin first load
• Implement requirements.txt installation in venv
• Execute plugin code within venv context
• Cache venvs and detect requirements changes
• Add configuration for venv base directory
• Add cleanup for orphaned venvs

Phase 2: Configuration Simplification

• Define default configuration schema for each builtin plugin
• Implement config merging (user + defaults)
• Add JSON Schema validation for plugin configs
• Improve error messages for configuration issues
• Update documentation with simplified examples
• Migrate existing plugins to new config pattern

Phase 3: Maturity Model

• Define maturity levels (alpha, beta, stable, deprecated)
• Add maturity field to plugin manifest schema
• Assess and assign maturity to all builtin plugins
• Track quality metrics (test coverage, audit status)
• Display maturity in Admin UI plugin list
• Add warning for non-stable plugins in production

Phase 4: Plugin Registry

• Enhance plugin manifest with capabilities field
• Create /admin/plugins/registry endpoint
• Add search and filter functionality
• Add version compatibility checking
• Update Admin UI with registry view
• Document manifest schema

Phase 5: QA for Production Readiness

• Identify priority plugins for production readiness
• Ensure >80% test coverage for priority plugins
• Security review for priority plugins
• Performance benchmarking for priority plugins
• Documentation review for priority plugins

⚙️ Configuration Examples

Simplified Plugin Configuration

# Before (complex)
plugins:
  pii_filter:
    enabled: true
    mode: enforce
    hooks:
      tool_pre_invoke:
        tools:
          - tool_name: "*"
            fields: ["*"]
    config:
      patterns:
        - name: email
          regex: "..."
          replacement: "[EMAIL]"
        # ... many more patterns

# After (with defaults)
plugins:
  pii_filter:
    enabled: true
    # Uses all default patterns and settings

Plugin Manifest with Maturity

name: pii_filter
version: 1.2.0
description: Filters personally identifiable information from tool inputs and outputs
maturity: stable
capabilities:
  - content_filtering
  - data_protection
hooks:
  - tool_pre_invoke
  - tool_post_invoke
config_schema:
  type: object
  properties:
    mode:
      type: string
      enum: [enforce, permissive]
      default: enforce
quality:
  test_coverage: 87%
  security_audit: 2026-01-15
  performance_benchmark: "1.2ms avg"

✅ Success Criteria

• Plugins run in isolated virtual environments
• Plugin dependencies don't conflict with each other
• Configuration uses sensible defaults
• Configuration errors produce clear messages
• Maturity levels defined and displayed
• Priority plugins have >80% test coverage
• Plugin registry API functional
• Admin UI shows plugin maturity and capabilities

🏁 Definition of Done

• Virtual environment isolation implemented
• Configuration simplification with defaults
• JSON Schema validation for configs
• Maturity model defined and applied
• Priority plugins QA'd for production
• Plugin registry API endpoint created
• Admin UI updated with registry view
• Unit tests for plugin framework changes
• Documentation updated
• Code passes make verify
• PR reviewed and approved

🔗 Related Issues

• refactor: enable plugins extensibility #1372 - Enable custom hooks (completed)
• [FEATURE][PLUGIN]: Reduce complexity in plugin configuration framework #1140 - Reduce complexity in plugin configuration
• [FEATURE][PLUGIN]: Add maturity levels to plugins #1413 - Create maturity model for plugins
• [TESTING]: QA plan for shortlist of plugins #1419 - QA priority plugins for production readiness
• [EPIC][PLUGIN]: Per-virtual-server plugin selection with multi-level RBAC #1247 - Per-virtual-server plugin selection

📓 Additional Context

Priority Plugins for Production Readiness

1. PII Filter - Data protection requirement
2. Content Moderation - Safety requirement
3. Rate Limiter - Stability requirement
4. Schema Guard - Data validation
5. Cedar Policy - Authorization

Maturity Level Criteria