SIENTIAPDE-1273

Enhance orchestrator utilities and activities with improved documentation and functionality. Update README to reflect new orchestrator functions for drift and simple metrics workflows. Refactor email, formatters, mongo_db, slot_manager, and temporal_manager activities to include detailed docstrings and improve clarity on input parameters and return values. Ensure consistent metadata handling across activities for better logging and tracking.

orchestrator/utils/email_builder.py

@@ -32,12 +32,15 @@ class EmailBuilder:
         """
         Replace parameters in a Jinja2 template with provided values.
 
+        Renders a Jinja2 template string with the provided parameter dictionary,
+        replacing all template variables with their corresponding values.
+
         Args:
-            template (str): The Jinja2 template string.
-            parameters (dict): Dictionary of parameters to replace in the template.
+            template (str): The Jinja2 template string
+            parameters (dict): Dictionary of parameters to replace in the template
 
         Returns:
-            str: The rendered template with parameters replaced.
+            str: The rendered template with parameters replaced
         """
         # Create a Jinja2 template from the provided string
         template_obj = Template(template)
@@ -48,13 +51,16 @@ class EmailBuilder:
         """
         Build parameters dictionary for email templates based on general events and mail type.
 
+        Processes notification events organized by level and model, rendering HTML
+        sections for each notification level using the general template.
+
         Args:
             general_events (dict): Dictionary containing events categorized by level (ERROR, WARNING, INFO).
-                Each level contains a 'models' key with model-specific event data.
-            mail_type (str): The type of email being sent.
+                Each level contains a 'models' key with model-specific event data
+            mail_type (str): The type of email being sent (Alerts/Reports)
 
         Returns:
-            dict: Dictionary with mail_type and rendered event sections for each notification level.
+            dict: Dictionary with mail_type and rendered event sections for each notification level
         """
         error_events = general_events.get('ERROR', {})
         warning_events = general_events.get('WARNING', {})
@@ -79,16 +85,20 @@ class EmailBuilder:
 
     def build_email(self, report_data: list[dict[str, Any]], mail_type: str) -> str:
         """
-        Builds the email HTML by organizing report data by notification level and model.
+        Build the email HTML by organizing report data by notification level and model.
+
+        Organizes notification data by level and model, then renders the complete
+        HTML email using the report template with all event sections.
 
         Args:
-            report_data (List[Dict[str, Any]]): List of notification reports, each containing:
+            report_data (list[dict[str, Any]]): List of notification reports, each containing:
                 - level (str): Notification level (ERROR, WARNING, INFO)
                 - model_name (str): Name of the model
                 - Additional notification details
+            mail_type (str): The type of email being built (Alerts/Reports)
 
         Returns:
-            str: Complete HTML email content ready for sending.
+            str: Complete HTML email content ready for sending
         """
         general_events: dict[str, dict[str, Any]] = {}
 

orchestrator/utils/orchestrator_functions.py

@@ -35,6 +35,19 @@ def common_config(config: dict[str, Any]):
 def drift(config: dict[str, Any]):
     """
     Build drift configuration from pipeline config.
+
+    Creates a drift detection workflow configuration with database table mappings
+    and drift metric specifications for monitoring data distribution changes.
+
+    Args:
+        config (dict[str, Any]): Pipeline configuration containing:
+            - interval_minutes (int, optional): Detection interval in minutes (default: 60)
+            - drift_metrics (list[str], optional): List of drift metrics to compute
+                (default: ['kolmogorov_smirnov', 'jensen_shannon', 'wasserstein'])
+            - Additional fields from common_config
+
+    Returns:
+        dict[str, Any]: Drift configuration with workflow type set to 'drift'
     """
     return {
         **common_config(config),
@@ -51,6 +64,19 @@ def drift(config: dict[str, Any]):
 def simple_metrics(config: dict[str, Any]):
     """
     Build simple metrics configuration from pipeline config.
+
+    Creates a simple metrics computation workflow configuration for calculating
+    model performance metrics like RMSE, MSE, MAE, and R².
+
+    Args:
+        config (dict[str, Any]): Pipeline configuration containing:
+            - interval_minutes (int, optional): Computation interval in minutes (default: 60)
+            - metrics (list[str], optional): List of metrics to compute
+                (default: ['rmse', 'mse', 'mae', 'r2'])
+            - Additional fields from common_config
+
+    Returns:
+        dict[str, Any]: Simple metrics configuration with workflow type set to 'simple_metrics'
     """
     return {
         **common_config(config),
@@ -245,13 +271,17 @@ def predictions_batch(config: dict[str, Any]):
 
 def gather_read_tags(pipelines: list[dict[str, Any]]) -> dict[str, Any]:
     """
-    Gathers all read tags from input pipelines.
+    Gather all read tags from input pipelines.
+
+    Collects all read tags from scouter pipelines and organizes them by
+    server_id and tag_address, tracking which topics each tag is associated with.
 
     Args:
-        - pipelines (list[dict[str, Any]]): The schedules to process.
+        pipelines (list[dict[str, Any]]): The pipeline configurations to process
 
     Returns:
-        - dict[str, Any]: The read tags dictionary
+        dict[str, Any]: Dictionary of read tags keyed by "server_id:tag_address",
+            each containing tag configuration and associated topics
     """
 
     tags = {}
@@ -274,19 +304,24 @@ def build_tag_config(
     """
     Build tag configuration for a specific slot and OPC server.
 
+    Organizes tags by OPC server and calculates the minimum subscription period
+    based on tag frequencies. Validates that all server IDs exist in the OPC
+    servers configuration.
+
     Args:
         tags (list[dict[str, Any]]): List of tag configurations containing:
             - server_id (str): ID of the OPC server
             - tag_address (str): Address of the tag
-        slot_config (dict[str, Any]): Current slot configuration to update.
-        opc_servers (dict[str, Any]): Dictionary of OPC server configurations.
-        i (int): Slot number to configure.
+            - frequency (int): Tag read frequency in milliseconds
+        opc_servers (dict[str, Any]): Dictionary of OPC server configurations
 
     Returns:
-        dict[str, Any]: Updated slot configuration with the new tag.
+        tuple[dict[str, Any], list]: A tuple containing:
+            - Slot configuration dictionary organized by server name
+            - List of server IDs that were not found in opc_servers
 
     Raises:
-        ValueError: If the specified server_id is not found in opc_servers.
+        ValueError: If the specified server_id is not found in opc_servers
     """
 
     slot_config = {}