semantics

backend/src/core/plugin_base.py

@@ -8,9 +8,9 @@ from .logger import belief_scope
 
 # #region PluginBase [TYPE Class] [SEMANTICS plugin, interface, base, abstract]
 # @BRIEF Defines the abstract base class that all plugins must implement to be recognized by the system. It enforces a common structure for plugin metadata and execution.
-# @LAYER: Core
-# @RELATION Used by PluginLoader to identify valid plugins.
-# @INVARIANT: All plugins MUST inherit from this class.
+# @LAYER Core
+# @PURPOSE PluginLoader scans for subclasses of PluginBase.
+# @INVARIANT  All plugins MUST inherit from this class.
 class PluginBase(ABC):
     """
     Base class for all plugins.
@@ -20,9 +20,9 @@ class PluginBase(ABC):
     @abstractmethod
     # #region id [TYPE Function]
     # @PURPOSE: Returns the unique identifier for the plugin.
-    # @PRE: Plugin instance exists.
-    # @POST: Returns string ID.
-    # @RETURN: str - Plugin ID.
+    # @PRE  Plugin instance exists.
+    # @POST  Returns string ID.
+    # @RETURN  str - Plugin ID.
     def id(self) -> str:
         """A unique identifier for the plugin."""
         with belief_scope("id"):
@@ -32,9 +32,9 @@ class PluginBase(ABC):
     @abstractmethod
     # #region name [TYPE Function]
     # @PURPOSE: Returns the human-readable name of the plugin.
-    # @PRE: Plugin instance exists.
-    # @POST: Returns string name.
-    # @RETURN: str - Plugin name.
+    # @PRE  Plugin instance exists.
+    # @POST  Returns string name.
+    # @RETURN  str - Plugin name.
     def name(self) -> str:
         """A human-readable name for the plugin."""
         with belief_scope("name"):
@@ -44,9 +44,9 @@ class PluginBase(ABC):
     @abstractmethod
     # #region description [TYPE Function]
     # @PURPOSE: Returns a brief description of the plugin.
-    # @PRE: Plugin instance exists.
-    # @POST: Returns string description.
-    # @RETURN: str - Plugin description.
+    # @PRE  Plugin instance exists.
+    # @POST  Returns string description.
+    # @RETURN  str - Plugin description.
     def description(self) -> str:
         """A brief description of what the plugin does."""
         with belief_scope("description"):
@@ -56,9 +56,9 @@ class PluginBase(ABC):
     @abstractmethod
     # #region version [TYPE Function]
     # @PURPOSE: Returns the version of the plugin.
-    # @PRE: Plugin instance exists.
-    # @POST: Returns string version.
-    # @RETURN: str - Plugin version.
+    # @PRE  Plugin instance exists.
+    # @POST  Returns string version.
+    # @RETURN  str - Plugin version.
     def version(self) -> str:
         """The version of the plugin."""
         with belief_scope("version"):
@@ -67,9 +67,9 @@ class PluginBase(ABC):
     @property
     # #region required_permission [TYPE Function]
     # @PURPOSE: Returns the required permission string to execute this plugin.
-    # @PRE: Plugin instance exists.
-    # @POST: Returns string permission.
-    # @RETURN: str - Required permission (e.g., "plugin:backup:execute").
+    # @PRE  Plugin instance exists.
+    # @POST  Returns string permission.
+    # @RETURN  str - Required permission (e.g., "plugin:backup:execute").
     def required_permission(self) -> str:
         """The permission string required to execute this plugin."""
         with belief_scope("required_permission"):
@@ -78,9 +78,9 @@ class PluginBase(ABC):
     @property
     # #region ui_route [TYPE Function]
     # @PURPOSE: Returns the frontend route for the plugin's UI, if applicable.
-    # @PRE: Plugin instance exists.
-    # @POST: Returns string route or None.
-    # @RETURN: Optional[str] - Frontend route.
+    # @PRE  Plugin instance exists.
+    # @POST  Returns string route or None.
+    # @RETURN  Optional[str] - Frontend route.
     def ui_route(self) -> str | None:
         """
         The frontend route for the plugin's UI.
@@ -92,9 +92,9 @@ class PluginBase(ABC):
     @abstractmethod
     # #region get_schema [TYPE Function]
     # @PURPOSE: Returns the JSON schema for the plugin's input parameters.
-    # @PRE: Plugin instance exists.
-    # @POST: Returns dict schema.
-    # @RETURN: Dict[str, Any] - JSON schema.
+    # @PRE  Plugin instance exists.
+    # @POST  Returns dict schema.
+    # @RETURN  Dict[str, Any] - JSON schema.
     def get_schema(self) -> dict[str, Any]:
         """
         Returns the JSON schema for the plugin's input parameters.
@@ -106,9 +106,9 @@ class PluginBase(ABC):
     @abstractmethod
     # #region execute [TYPE Function]
     # @PURPOSE: Executes the plugin's core logic.
-    # @PARAM: params (Dict[str, Any]) - Validated input parameters.
-    # @PRE: params must be a dictionary.
-    # @POST: Plugin execution is completed.
+    # @PARAM  params (Dict[str, Any]) - Validated input parameters.
+    # @PRE  params must be a dictionary.
+    # @POST  Plugin execution is completed.
     async def execute(self, params: dict[str, Any]):
         with belief_scope("execute"):
             pass
@@ -121,8 +121,8 @@ class PluginBase(ABC):
 # #endregion PluginBase
 # #region PluginConfig [TYPE Class] [SEMANTICS plugin, config, schema, pydantic]
 # @BRIEF A Pydantic model used to represent the validated configuration and metadata of a loaded plugin. This object is what gets exposed to the API layer.
-# @LAYER: Core
-# @RELATION Instantiated by PluginLoader after validating a PluginBase instance.
+# @LAYER Core
+# @PURPOSE Validated PluginConfig exposed to API layer.
 class PluginConfig(BaseModel):
     """Pydantic model for plugin configuration."""
     id: str = Field(..., description="Unique identifier for the plugin")