How-to Guides

It’s important to understand the underlying structure and concepts of BOSA Plugin Architecture. This section breaks down the main workflow involved to create a custom plugin with BOSA Core.

Define Plugin Handler

PluginHandler in BOSA Core is responsible for managing the lifecycle and dependencies of plugins associated with it. When you create your own handler by subclassing PluginHandler, it acts as the bridge between the plugin system and your specific plugin logic.

The base PluginHandler class requires implementations of two abstract methods:. create_injections and initialize_plugin. While it provides a default implementation for ainitialize_plugin that wraps the sync initialize_plugin, you must implement the two core abstract methods in your handler subclass. The most common customization points are:

1. create_injections(cls, handler)

Define what services/dependencies your plugin needs

@classmethod
def create_injections(cls, handler: 'MyPluginHandler') -> Dict[Type, Any]:
    # Provide dependencies for plugins here
    return {}

Used for dependency injection. This method should return a dictionary mapping types to objects that your plugin might need.

1. initialize_plugin(self, plugin)

Set up any plugin-specific resources after injection

def initialize_plugin(self, plugin: 'Plugin') -> None:
    # Custom initialization logic for the plugin
    print(f"Initializing plugin: {plugin.name}")

Called when a plugin is initialized. You can use this to perform setup actions or just simply logging.

For example, here's a typical implementation of a PluginHandler.

from typing import Dict, Type, Any
from bosa_core.plugin.handler import PluginHandler
from bosa_core.plugin.plugin import Plugin

class HelloPluginHandler(PluginHandler):
    @classmethod
    def create_injections(cls, handler: 'MyPluginHandler') -> Dict[Type, Any]:
        # Optionally provide dependencies for plugins
        return {}
    
    @classmethod
    def initialize_plugin(self, plugin: 'Plugin') -> None:
        # Initialization logic for plugins
        print(f"Initializing plugin: {plugin.name}")

Define Plugin Interface

The plugin interface defines the contract that all plugins of a certain type must implement. This is usually an abstract class decorated with @Plugin.for_handler, linking it to its handler.

from bosa_core.plugin.plugin import Plugin
from abc import ABC, abstractmethod

@Plugin.for_handler(HelloPluginHandler)
class HelloPlugin(Plugin, ABC):

    @abstractmethod
    def say_hello(self) -> str:
        """Returns a greeting message."""
        raise NotImplementedError

Implement the Plugin

Create a concrete class that implements the plugin interface, providing the actual functionality. Here's the previous HelloPlugin interface we create. It has say_hello() method that we need to implement.

class MyHelloPlugin(HelloPlugin):
    name = "Example Plugin"
    version = "0.1.0"
    description = "An example plugin implementation"

    def say_hello(self) -> str:
        return "Hello from MyHelloPlugin!"

Register and Use the Plugin

Plugins must be registered with the PluginManager before they can be used. The manager handles plugin discovery, instantiation, and lifecycle.

from bosa_core.plugin.manager import PluginManager

handler = HelloPluginHandler()
manager = PluginManager(handlers=[handler])
manager.register_plugin(MyHelloPlugin)

plugin = manager.get_plugin("Hello Plugin")
if plugin:
    print(plugin.say_hello())  # Output: Hello from MyHelloPlugin!

This process involving:

• Create a PluginManager and pass your handler(s).

• Register your plugin class.

• Retrieve and use plugin instances by name.