feat: add plugin factory classes

README.md

@@ -1,3 +1,108 @@
 # HiveMind Plugin Manager
 
-> under construction, currently only includes shared base classes
+The **HiveMind Plugin Manager (HPM)** is a system for discovering, managing, and loading plugins within the HiveMind ecosystem. It supports various plugin types, including databases, network protocols, agent protocols, and binary data handlers. HPM allows for dynamic integration of these plugins to enhance the functionality of HiveMind agents, offering a flexible and extensible architecture.
+
+## Features
+
+- **Plugin Discovery**: Easily find and load plugins of different types, including:
+  - **Database Plugins**: Supports various database types such as JSON, SQLite, and Redis.
+  - **Agent Protocol Plugins**: Integrates agent protocols like OVOS and Persona, enabling seamless communication between HiveMind agents.
+  - **Network Protocol Plugins**: Enables network protocols such as WebSockets for distributed communication.
+  - **Binary Data Handler Plugins**: Handle binary data communication, like audio data over HiveMind.
+
+- **Plugin Loading**: Dynamically load specific plugins by name, type, or from available entry points.
+
+- **Factories for Plugin Instantiation**: Factories for creating instances of each plugin type (database, agent protocol, network protocol, binary protocol) based on user configurations.
+
+## Installation
+
+```bash
+pip install hivemind-plugin-manager
+```
+
+## Usage
+
+The following example demonstrates how to discover and load plugins, along with creating instances using the provided factories.
+
+### Discovering Plugins
+
+Use the `find_plugins` function to discover all available plugins for a specific type:
+
+```python
+from hivemind_plugin_manager import find_plugins, HiveMindPluginTypes
+
+# Find all database plugins
+database_plugins = find_plugins(HiveMindPluginTypes.DATABASE)
+print(database_plugins)
+
+# Find all agent protocol plugins
+agent_protocol_plugins = find_plugins(HiveMindPluginTypes.AGENT_PROTOCOL)
+print(agent_protocol_plugins)
+```
+
+### Creating Plugin Instances
+
+Each plugin type has a corresponding factory class that allows for creating plugin instances with the required configuration.
+
+#### Database Plugin Factory
+
+```python
+from hivemind_plugin_manager import DatabaseFactory
+
+# Create an instance of a database plugin
+db_instance = DatabaseFactory.create("hivemind-redis-db-plugin", password="Password1!", host="192.168.1.11", port=6789)
+```
+
+#### Agent Protocol Factory
+
+```python
+from hivemind_plugin_manager import AgentProtocolFactory
+
+# Create an agent protocol instance
+agent_protocol_instance = AgentProtocolFactory.create("hivemind-ovos-agent-plugin")
+```
+
+#### Network Protocol Factory
+
+```python
+from hivemind_plugin_manager import NetworkProtocolFactory
+
+# Create a network protocol instance
+network_protocol_instance = NetworkProtocolFactory.create("hivemind-websocket-plugin")
+```
+
+#### Binary Data Handler Protocol Factory
+
+```python
+from hivemind_plugin_manager import BinaryDataHandlerProtocolFactory
+
+# Create a binary data handler protocol instance
+binary_data_handler_instance = BinaryDataHandlerProtocolFactory.create("hivemind-audio-binary-protocol-plugin")
+```
+
+## Plugin Types
+
+### 1. **Database Plugins**
+
+Supports multiple database systems, such as:
+
+- **JSON Database**: Stores data in a JSON format.
+- **SQLite Database**: Uses SQLite for local database storage.
+- **Redis Database**: Uses Redis for distributed caching and storage.
+
+### 2. **Agent Protocol Plugins**
+
+Supports communication protocols for agents, such as:
+
+- **OVOS Protocol**: For interaction with OVOS-based agents.
+- **Persona Protocol**: For interaction with the Persona framework.
+
+### 3. **Network Protocol Plugins**
+
+Enables network communication protocols, such as:
+
+- **WebSocket Protocol**: For real-time, bidirectional communication over WebSockets.
+
+### 4. **Binary Data Handler Protocol Plugins**
+
+Handles communication of binary data types, like audio, using specialized protocols.

hivemind_plugin_manager/__init__.py

@@ -0,0 +1,140 @@
+import enum
+from typing import Optional, Dict, Any, Union
+
+from ovos_utils.log import LOG
+
+from hivemind_plugin_manager.database import AbstractDB, AbstractRemoteDB
+from hivemind_plugin_manager.protocols import AgentProtocol, BinaryDataHandlerProtocol, NetworkProtocol
+
+
+class HiveMindPluginTypes(str, enum.Enum):
+    DATABASE = "hivemind.database"
+    NETWORK_PROTOCOL = "hivemind.network.protocol"
+    AGENT_PROTOCOL = "hivemind.agent.protocol"
+    BINARY_PROTOCOL = "hivemind.binary.protocol"
+
+
+class DatabaseFactory:
+
+    @classmethod
+    def create(cls, plugin_name: str,
+               name: str = "clients",
+               subfolder: str = "hivemind-core",
+               password: Optional[str] = None,
+               host: Optional[str] = None,
+               port: Optional[int] = None) -> Union[AbstractRemoteDB, AbstractDB]:
+        plugins = find_plugins(HiveMindPluginTypes.DATABASE)
+        if plugin_name not in plugins:
+            raise KeyError(f"'{plugin_name}' not found. Available plugins: {list(plugins.keys())}")
+        if issubclass(plugins[plugin_name], AbstractRemoteDB):
+            return plugins[plugin_name](name=name, subfolder=subfolder,
+                                        password=password, host=host, port=port)
+        return plugins[plugin_name](name=name, subfolder=subfolder,
+                                    password=password)
+
+
+class AgentProtocolFactory:
+
+    @classmethod
+    def create(cls, plugin_name: str,
+               config: Optional[Dict[str, Any]] = None,
+               bus: Optional[Union['FakeBus', 'MessageBusClient']] = None,
+               hm_protocol: Optional['HiveMindListenerProtocol'] = None) -> AgentProtocol:
+        config = config or {}
+        plugins = find_plugins(HiveMindPluginTypes.AGENT_PROTOCOL)
+        if plugin_name not in plugins:
+            raise KeyError(f"'{plugin_name}' not found. Available plugins: {list(plugins.keys())}")
+        return plugins[plugin_name](config=config, bus=bus, hm_protocol=hm_protocol)
+
+
+class NetworkProtocolFactory:
+
+    @classmethod
+    def create(cls, plugin_name: str,
+               config: Optional[Dict[str, Any]] = None,
+               hm_protocol: Optional['HiveMindListenerProtocol'] = None) -> NetworkProtocol:
+        config = config or {}
+        plugins = find_plugins(HiveMindPluginTypes.NETWORK_PROTOCOL)
+        if plugin_name not in plugins:
+            raise KeyError(f"'{plugin_name}' not found. Available plugins: {list(plugins.keys())}")
+        return plugins[plugin_name](config=config, hm_protocol=hm_protocol)
+
+
+class BinaryDataHandlerProtocolFactory:
+
+    @classmethod
+    def create(cls, plugin_name: str,
+               config: Optional[Dict[str, Any]] = None,
+               hm_protocol: Optional['HiveMindListenerProtocol'] = None,
+               agent_protocol: Optional['AgentProtocol'] = None) -> BinaryDataHandlerProtocol:
+        config = config or {}
+        plugins = find_plugins(HiveMindPluginTypes.BINARY_PROTOCOL)
+        if plugin_name not in plugins:
+            raise KeyError(f"'{plugin_name}' not found. Available plugins: {list(plugins.keys())}")
+        return plugins[plugin_name](config=config,
+                                    hm_protocol=hm_protocol,
+                                    agent_protocol=agent_protocol)
+
+
+def _iter_entrypoints(plug_type: Optional[str]):
+    """
+    Return an iterator containing all entrypoints of the requested type
+    @param plug_type: entrypoint name to load
+    @return: iterator of all entrypoints
+    """
+    try:
+        from importlib_metadata import entry_points
+        for entry_point in entry_points(group=plug_type):
+            yield entry_point
+    except ImportError:
+        import pkg_resources
+        for entry_point in pkg_resources.iter_entry_points(plug_type):
+            yield entry_point
+
+
+def find_plugins(plug_type: HiveMindPluginTypes = None) -> dict:
+    """
+    Finds all plugins matching specific entrypoint type.
+
+    Arguments:
+        plug_type (str): plugin entrypoint string to retrieve
+
+    Returns:
+        dict mapping plugin names to plugin entrypoints
+    """
+    entrypoints = {}
+    if not plug_type:
+        plugs = list(HiveMindPluginTypes)
+    elif isinstance(plug_type, str):
+        plugs = [plug_type]
+    else:
+        plugs = plug_type
+    for plug in plugs:
+        for entry_point in _iter_entrypoints(plug):
+            try:
+                entrypoints[entry_point.name] = entry_point.load()
+                if entry_point.name not in entrypoints:
+                    LOG.debug(f"Loaded plugin entry point {entry_point.name}")
+            except Exception as e:
+                if entry_point not in find_plugins._errored:
+                    find_plugins._errored.append(entry_point)
+                    # NOTE: this runs in a loop inside skills manager, this would endlessly spam logs
+                    LOG.error(f"Failed to load plugin entry point {entry_point}: "
+                              f"{e}")
+    return entrypoints
+
+
+find_plugins._errored = []
+
+if __name__ == "__main__":
+    print(find_plugins(HiveMindPluginTypes.DATABASE))
+    # {'hivemind-json-db-plugin': <class 'json_database.hpm.JsonDB'>,
+    # 'hivemind-sqlite-db-plugin': <class 'hivemind_sqlite_database.SQLiteDB'>,
+    # 'hivemind-redis-db-plugin': <class 'hivemind_redis_database.RedisDB'>}
+    print(find_plugins(HiveMindPluginTypes.NETWORK_PROTOCOL))
+    # {'hivemind-websocket-plugin': <class 'hivemind_websocket_protocol.HiveMindWebsocketProtocol'>}
+    print(find_plugins(HiveMindPluginTypes.AGENT_PROTOCOL))
+    # {'hivemind-ovos-agent-plugin': <class 'ovos_bus_client.hpm.OVOSProtocol'>,
+    # 'hivemind-persona-agent-plugin': <class 'ovos_persona.hpm.PersonaProtocol'>}}
+    print(find_plugins(HiveMindPluginTypes.BINARY_PROTOCOL))
+    # {'hivemind-audio-binary-protocol-plugin': <class 'hivemind_listener.protocol.AudioBinaryProtocol'>}

hivemind_plugin_manager/database.py

@@ -154,13 +154,17 @@ def __repr__(self) -> str:
         return self.serialize()
 
 
+@dataclass
 class AbstractDB(abc.ABC):
     """
     Abstract base class for all database implementations.
 
     All database implementations should derive from this class and implement
     the abstract methods.
     """
+    name: str = "clients"
+    subfolder: str = "hivemind-core"
+    password: Optional[str] = None
 
     @abc.abstractmethod
     def add_item(self, client: Client) -> bool:
@@ -173,7 +177,6 @@ def add_item(self, client: Client) -> bool:
         Returns:
             True if the addition was successful, False otherwise.
         """
-        pass
 
     def delete_item(self, client: Client) -> bool:
         """
@@ -227,7 +230,6 @@ def search_by_value(self, key: str, val: Union[str, bool, int, float]) -> List[C
         Returns:
             A list of clients that match the search criteria.
         """
-        pass
 
     @abc.abstractmethod
     def __len__(self) -> int:
@@ -237,7 +239,6 @@ def __len__(self) -> int:
         Returns:
             The number of items in the database.
         """
-        return 0
 
     @abc.abstractmethod
     def __iter__(self) -> Iterable['Client']:
@@ -247,7 +248,6 @@ def __iter__(self) -> Iterable['Client']:
         Returns:
             An iterator over the clients in the database.
         """
-        pass
 
     def sync(self):
         """update db from disk if needed"""
@@ -262,3 +262,57 @@ def commit(self) -> bool:
         """
         return True
 
+
+@dataclass
+class AbstractRemoteDB(AbstractDB):
+    """
+    Abstract base class for remote database implementations.
+    """
+    host: str = "127.0.0.1"
+    port: Optional[int] = None
+    name: str = "clients"
+    subfolder: str = "hivemind-core"
+    password: Optional[str] = None
+
+    @abc.abstractmethod
+    def add_item(self, client: Client) -> bool:
+        """
+        Add a client to the database.
+
+        Args:
+            client: The client to be added.
+
+        Returns:
+            True if the addition was successful, False otherwise.
+        """
+
+    @abc.abstractmethod
+    def search_by_value(self, key: str, val: Union[str, bool, int, float]) -> List[Client]:
+        """
+        Search for clients by a specific key-value pair.
+
+        Args:
+            key: The key to search by.
+            val: The value to search for.
+
+        Returns:
+            A list of clients that match the search criteria.
+        """
+
+    @abc.abstractmethod
+    def __len__(self) -> int:
+        """
+        Get the number of items in the database.
+
+        Returns:
+            The number of items in the database.
+        """
+
+    @abc.abstractmethod
+    def __iter__(self) -> Iterable['Client']:
+        """
+        Iterate over all clients in the database.
+
+        Returns:
+            An iterator over the clients in the database.
+        """