semantic markup update

backend/src/plugins/search.py

@@ -21,25 +21,57 @@ class SearchPlugin(PluginBase):
     """
 
     @property
+    # [DEF:id:Function]
+    # @PURPOSE: Returns the unique identifier for the search plugin.
+    # @PRE: Plugin instance exists.
+    # @POST: Returns string ID.
+    # @RETURN: str - "search-datasets"
     def id(self) -> str:
-        return "search-datasets"
+        with belief_scope("id"):
+            return "search-datasets"
+    # [/DEF:id:Function]
 
     @property
+    # [DEF:name:Function]
+    # @PURPOSE: Returns the human-readable name of the search plugin.
+    # @PRE: Plugin instance exists.
+    # @POST: Returns string name.
+    # @RETURN: str - Plugin name.
     def name(self) -> str:
-        return "Search Datasets"
+        with belief_scope("name"):
+            return "Search Datasets"
+    # [/DEF:name:Function]
 
     @property
+    # [DEF:description:Function]
+    # @PURPOSE: Returns a description of the search plugin.
+    # @PRE: Plugin instance exists.
+    # @POST: Returns string description.
+    # @RETURN: str - Plugin description.
     def description(self) -> str:
-        return "Search for text patterns across all datasets in a specific environment."
+        with belief_scope("description"):
+            return "Search for text patterns across all datasets in a specific environment."
+    # [/DEF:description:Function]
 
     @property
+    # [DEF:version:Function]
+    # @PURPOSE: Returns the version of the search plugin.
+    # @PRE: Plugin instance exists.
+    # @POST: Returns string version.
+    # @RETURN: str - "1.0.0"
     def version(self) -> str:
-        return "1.0.0"
+        with belief_scope("version"):
+            return "1.0.0"
+    # [/DEF:version:Function]
 
-    # [DEF:SearchPlugin.get_schema:Function]
+    # [DEF:get_schema:Function]
     # @PURPOSE: Returns the JSON schema for the search plugin parameters.
+    # @PRE: Plugin instance exists.
+    # @POST: Returns dictionary schema.
+    # @RETURN: Dict[str, Any] - JSON schema.
     def get_schema(self) -> Dict[str, Any]:
-        return {
+        with belief_scope("get_schema"):
+            return {
             "type": "object",
             "properties": {
                 "env": {
@@ -55,12 +87,14 @@ class SearchPlugin(PluginBase):
             },
             "required": ["env", "query"]
         }
-    # [/DEF:SearchPlugin.get_schema:Function]
+    # [/DEF:get_schema:Function]
 
-    # [DEF:SearchPlugin.execute:Function]
+    # [DEF:execute:Function]
     # @PURPOSE: Executes the dataset search logic.
+    # @PARAM: params (Dict[str, Any]) - Search parameters.
     # @PRE: Params contain valid 'env' and 'query'.
     # @POST: Returns a dictionary with count and results list.
+    # @RETURN: Dict[str, Any] - Search results.
     async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
         with belief_scope("SearchPlugin.execute", f"params={params}"):
             env_name = params.get("env")
@@ -124,38 +158,45 @@ class SearchPlugin(PluginBase):
             except Exception as e:
                 logger.error(f"[SearchPlugin.execute][Failure] Error during search: {e}")
                 raise
-    # [/DEF:SearchPlugin.execute:Function]
+    # [/DEF:execute:Function]
 
-    # [DEF:SearchPlugin._get_context:Function]
+    # [DEF:_get_context:Function]
     # @PURPOSE: Extracts a small context around the match for display.
+    # @PARAM: text (str) - The full text to extract context from.
+    # @PARAM: match_text (str) - The matched text pattern.
+    # @PARAM: context_lines (int) - Number of lines of context to include.
+    # @PRE: text and match_text must be strings.
+    # @POST: Returns context string.
+    # @RETURN: str - Extracted context.
     def _get_context(self, text: str, match_text: str, context_lines: int = 1) -> str:
         """
         Extracts a small context around the match for display.
         """
-        if not match_text:
-            return text[:100] + "..." if len(text) > 100 else text
+        with belief_scope("_get_context"):
+            if not match_text:
+                return text[:100] + "..." if len(text) > 100 else text
             
-        lines = text.splitlines()
+            lines = text.splitlines()
         match_line_index = -1
         for i, line in enumerate(lines):
             if match_text in line:
                 match_line_index = i
                 break
         
-        if match_line_index != -1:
-            start = max(0, match_line_index - context_lines)
-            end = min(len(lines), match_line_index + context_lines + 1)
-            context = []
-            for i in range(start, end):
-                line_content = lines[i]
-                if i == match_line_index:
-                    context.append(f"==> {line_content}")
-                else:
-                    context.append(f"    {line_content}")
-            return "\n".join(context)
-        
-        return text[:100] + "..." if len(text) > 100 else text
-    # [/DEF:SearchPlugin._get_context:Function]
+            if match_line_index != -1:
+                start = max(0, match_line_index - context_lines)
+                end = min(len(lines), match_line_index + context_lines + 1)
+                context = []
+                for i in range(start, end):
+                    line_content = lines[i]
+                    if i == match_line_index:
+                        context.append(f"==> {line_content}")
+                    else:
+                        context.append(f"    {line_content}")
+                return "\n".join(context)
+            
+            return text[:100] + "..." if len(text) > 100 else text
+    # [/DEF:_get_context:Function]
 
 # [/DEF:SearchPlugin:Class]
 # [/DEF:SearchPluginModule:Module]