Home

PluginForge Wiki

Application-agnostic plugin framework built on pluggy.

PluginForge wraps pluggy and adds the layers that pluggy does not provide: YAML configuration, plugin lifecycle, enable/disable, dependency resolution, FastAPI integration, Alembic migration support, and i18n.

Quick Links

• Getting Started - Installation and first plugin
• BasePlugin - Plugin base class and lifecycle methods
• PluginManager - Central orchestration class
• Configuration - YAML config system (app, plugin, i18n)
• Discovery and Dependencies - Entry points and dependency resolution
• Lifecycle - Init, activate, deactivate state machine
• Hooks - pluggy hook integration
• Extensions - Extension point pattern
• FastAPI Integration - Mounting plugin routes
• Alembic Integration - Plugin database migrations
• i18n - Internationalization
• Security - Path traversal prevention and plugin name validation
• Examples - Complete example application
• Changelog - Version history
• Roadmap - Planned features and ideas

Architecture Overview

PluginManager
├── Config (YAML)        - app.yaml, plugins/*.yaml, i18n/*.yaml
├── Discovery            - Entry points + dependency resolution
├── Lifecycle            - init -> activate -> deactivate (+ hot-reload)
├── Hooks (pluggy)       - @hookspec / @hookimpl
├── Extensions           - get_extensions(type) for interface-based queries
├── Health Checks        - Plugin health monitoring
├── Security             - Plugin name validation, path traversal prevention
├── FastAPI (optional)   - Route mounting with configurable prefix
├── Alembic (optional)   - Migration directory collection
└── i18n (optional)      - Multilingual strings from YAML

Requirements

• Python 3.11+
• pluggy >= 1.5.0
• PyYAML >= 6.0