Plugin System Quick Reference

Quick reference for common plugin development tasks.

File Structure

services/integrations/[name]/
├── __init__.py              # Package exports
├── config_service.py        # Configuration (~50 lines)
├── [name]_integration_router.py  # Routes (~100-300 lines)
├── [name]_plugin.py         # Plugin wrapper (~130 lines)
└── tests/
    └── test_[name]_plugin.py     # Tests (~100 lines)

Checklist for New Plugin

Key Patterns

Config Service

class MyConfigService:
    def __init__(self):
        self.api_key = os.getenv("MY_API_KEY", "")

    def is_configured(self) -> bool:
        return bool(self.api_key)

Router

class MyIntegrationRouter:
    def __init__(self, config_service: MyConfigService):
        self.config = config_service
        self.router = APIRouter(prefix="/api/integrations/my")
        self._setup_routes()

Plugin

class MyPlugin(PiperPlugin):
    def __init__(self):
        self.config_service = MyConfigService()
        self.router_instance = MyIntegrationRouter(self.config_service)

    # Implement 6 interface methods...

Auto-Registration

from services.plugins import get_plugin_registry
_my_plugin = MyPlugin()
get_plugin_registry().register(_my_plugin)

Common Commands

# Run plugin tests
PYTHONPATH=. pytest services/integrations/[name]/tests/ -v

# Run all plugin tests
PYTHONPATH=. pytest tests/plugins/ -v

# Start with your plugin
python3 main.py

# Test plugin endpoint
curl http://localhost:8001/api/integrations/[name]/health

Resources