semantic markup update

backend/src/core/plugin_loader.py

@@ -4,6 +4,7 @@ import sys # Added this line
 from typing import Dict, Type, List, Optional
 from .plugin_base import PluginBase, PluginConfig
 from jsonschema import validate
+from .logger import belief_scope
 
 # [DEF:PluginLoader:Class]
 # @SEMANTICS: plugin, loader, dynamic, import
@@ -16,22 +17,28 @@ class PluginLoader:
     that inherit from PluginBase.
     """
 
-    # [DEF:PluginLoader.__init__:Function]
+    # [DEF:__init__:Function]
     # @PURPOSE: Initializes the PluginLoader with a directory to scan.
+    # @PRE:     plugin_dir is a valid directory path.
+    # @POST:    Plugins are loaded and registered.
     # @PARAM: plugin_dir (str) - The directory containing plugin modules.
     def __init__(self, plugin_dir: str):
-        self.plugin_dir = plugin_dir
-        self._plugins: Dict[str, PluginBase] = {}
-        self._plugin_configs: Dict[str, PluginConfig] = {}
-        self._load_plugins()
-    # [/DEF:PluginLoader.__init__:Function]
+        with belief_scope("__init__"):
+            self.plugin_dir = plugin_dir
+            self._plugins: Dict[str, PluginBase] = {}
+            self._plugin_configs: Dict[str, PluginConfig] = {}
+            self._load_plugins()
+    # [/DEF:__init__:Function]
 
-    # [DEF:PluginLoader._load_plugins:Function]
+    # [DEF:_load_plugins:Function]
     # @PURPOSE: Scans the plugin directory and loads all valid plugins.
+    # @PRE:     plugin_dir exists or can be created.
+    # @POST:    _load_module is called for each .py file.
     def _load_plugins(self):
-        """
-        Scans the plugin directory, imports modules, and registers valid plugins.
-        """
+        with belief_scope("_load_plugins"):
+            """
+            Scans the plugin directory, imports modules, and registers valid plugins.
+            """
         if not os.path.exists(self.plugin_dir):
             os.makedirs(self.plugin_dir)
 
@@ -47,16 +54,19 @@ class PluginLoader:
                 module_name = filename[:-3]
                 file_path = os.path.join(self.plugin_dir, filename)
                 self._load_module(module_name, file_path)
-    # [/DEF:PluginLoader._load_plugins:Function]
+    # [/DEF:_load_plugins:Function]
 
-    # [DEF:PluginLoader._load_module:Function]
+    # [DEF:_load_module:Function]
     # @PURPOSE: Loads a single Python module and discovers PluginBase implementations.
+    # @PRE:     module_name and file_path are valid.
+    # @POST:    Plugin classes are instantiated and registered.
     # @PARAM: module_name (str) - The name of the module.
     # @PARAM: file_path (str) - The path to the module file.
     def _load_module(self, module_name: str, file_path: str):
-        """
-        Loads a single Python module and extracts PluginBase subclasses.
-        """
+        with belief_scope("_load_module"):
+            """
+            Loads a single Python module and extracts PluginBase subclasses.
+            """
         # Try to determine the correct package prefix based on how the app is running
         # For standalone execution, we need to handle the import differently
         if __name__ == "__main__" or "test" in __name__:
@@ -94,15 +104,18 @@ class PluginLoader:
                     self._register_plugin(plugin_instance)
                 except Exception as e:
                     print(f"Error instantiating plugin {attribute_name} in {module_name}: {e}") # Replace with proper logging
-    # [/DEF:PluginLoader._load_module:Function]
+    # [/DEF:_load_module:Function]
 
-    # [DEF:PluginLoader._register_plugin:Function]
+    # [DEF:_register_plugin:Function]
     # @PURPOSE: Registers a PluginBase instance and its configuration.
+    # @PRE:     plugin_instance is a valid implementation of PluginBase.
+    # @POST:    Plugin is added to _plugins and _plugin_configs.
     # @PARAM: plugin_instance (PluginBase) - The plugin instance to register.
     def _register_plugin(self, plugin_instance: PluginBase):
-        """
-        Registers a valid plugin instance.
-        """
+        with belief_scope("_register_plugin"):
+            """
+            Registers a valid plugin instance.
+            """
         plugin_id = plugin_instance.id
         if plugin_id in self._plugins:
             print(f"Warning: Duplicate plugin ID '{plugin_id}' found. Skipping.") # Replace with proper logging
@@ -131,39 +144,48 @@ class PluginLoader:
         except Exception as e:
             from ..core.logger import logger
             logger.error(f"Error validating plugin '{plugin_instance.name}' (ID: {plugin_id}): {e}")
-    # [/DEF:PluginLoader._register_plugin:Function]
+    # [/DEF:_register_plugin:Function]
 
 
-    # [DEF:PluginLoader.get_plugin:Function]
+    # [DEF:get_plugin:Function]
     # @PURPOSE: Retrieves a loaded plugin instance by its ID.
+    # @PRE:     plugin_id is a string.
+    # @POST:    Returns plugin instance or None.
     # @PARAM: plugin_id (str) - The unique identifier of the plugin.
     # @RETURN: Optional[PluginBase] - The plugin instance if found, otherwise None.
     def get_plugin(self, plugin_id: str) -> Optional[PluginBase]:
-        """
-        Returns a loaded plugin instance by its ID.
-        """
+        with belief_scope("get_plugin"):
+            """
+            Returns a loaded plugin instance by its ID.
+            """
         return self._plugins.get(plugin_id)
-    # [/DEF:PluginLoader.get_plugin:Function]
+    # [/DEF:get_plugin:Function]
 
-    # [DEF:PluginLoader.get_all_plugin_configs:Function]
+    # [DEF:get_all_plugin_configs:Function]
     # @PURPOSE: Returns a list of all registered plugin configurations.
+    # @PRE:     None.
+    # @POST:    Returns list of all PluginConfig objects.
     # @RETURN: List[PluginConfig] - A list of plugin configurations.
     def get_all_plugin_configs(self) -> List[PluginConfig]:
-        """
-        Returns a list of all loaded plugin configurations.
-        """
+        with belief_scope("get_all_plugin_configs"):
+            """
+            Returns a list of all loaded plugin configurations.
+            """
         return list(self._plugin_configs.values())
-    # [/DEF:PluginLoader.get_all_plugin_configs:Function]
+    # [/DEF:get_all_plugin_configs:Function]
 
-    # [DEF:PluginLoader.has_plugin:Function]
+    # [DEF:has_plugin:Function]
     # @PURPOSE: Checks if a plugin with the given ID is registered.
+    # @PRE:     plugin_id is a string.
+    # @POST:    Returns True if plugin exists.
     # @PARAM: plugin_id (str) - The unique identifier of the plugin.
     # @RETURN: bool - True if the plugin is registered, False otherwise.
     def has_plugin(self, plugin_id: str) -> bool:
-        """
-        Checks if a plugin with the given ID is loaded.
-        """
+        with belief_scope("has_plugin"):
+            """
+            Checks if a plugin with the given ID is loaded.
+            """
         return plugin_id in self._plugins
-    # [/DEF:PluginLoader.has_plugin:Function]
+    # [/DEF:has_plugin:Function]
 
 # [/DEF:PluginLoader:Class]