rc/SIENTIAPDE-2165- feat: rich metadata (filter/policy/counter) for mlflow_response_gate

laborious/activities/gates.py

@@ -28,6 +28,7 @@ InputFilterFunc = Callable[[DataFrame, dict[str, Any]], bool]
 ResponseFilterFunc = Callable[[dict[str, Any], dict[str, Any]], bool]
 ContentFilterFunc = Callable[[DataFrame, dict[str, Any]], bool]
 InputCounterFunc = Callable[[DataFrame, dict[str, Any]], int]
+ResponseCounterFunc = Callable[[dict[str, Any], dict[str, Any]], int]
 
 # Input filter function mappings
 input_filter_functions: dict[str, InputFilterFunc] = {
@@ -78,11 +79,31 @@ input_path_confidence: Mapping[str, int] = {
     'REPEAT': -1,
 }
 
+
+def _count_api_error(_response: dict[str, Any], _config: dict[str, Any]) -> int:
+    """
+    Count for the API_ERROR filter.
+
+    There's no per-row/per-item unit to count here — `api_error_filter` evaluates a single
+    API response as a whole, not tabular data — so this mirrors `_count_empty_data`'s
+    approach to a structural (not countable) trigger: a fixed value, here 1 (one API error
+    event), instead of 0 (zero rows present) like `_count_empty_data`'s own case.
+
+    Return:
+        int: Always 1.
+    """
+    return 1
+
+
 # MLFlow response filter function mappings
 mlflow_response_filter_functions: dict[str, ResponseFilterFunc] = {
     'API_ERROR': api_error_filter,
 }
 
+mlflow_response_filter_counters: dict[str, ResponseCounterFunc] = {
+    'API_ERROR': _count_api_error,
+}
+
 mlflow_response_path_confidence: Mapping[str, int] = {
     'STOP': -1,
     'CONTINUE': 10,
@@ -320,7 +341,9 @@ class Gates(SientiaMonitoring):
         return None, 0, '', None
 
     @activity.defn(name='mlflow_response_gate')
-    def mlflow_response_gate(self, input_data: dict[str, Any]) -> tuple[str | None, int, str]:
+    def mlflow_response_gate(
+        self, input_data: dict[str, Any]
+    ) -> tuple[str | None, int, str, dict[str, Any] | None]:
         """
         Validate MLFlow API response quality and integrity.
 
@@ -334,6 +357,9 @@ class Gates(SientiaMonitoring):
         3. Determines path decisions based on response validation results
         4. Provides confidence scores and detailed validation comments
         5. Handles API errors and response validation failures
+        6. Builds a metadata document describing which filter(s) triggered, with their policy
+           and a counter, whenever one does — this activity only computes it, it never writes it
+           (see `PredictionMetadata.write_prediction_metadata` for the actual write)
 
         Args:
             input_data: Configuration and data for response validation
@@ -345,10 +371,14 @@ class Gates(SientiaMonitoring):
                     - path_priority (list[str]): Priority order for path decisions
 
         Returns:
-            tuple: (path_flag, confidence, comment)
+            tuple: (path_flag, confidence, comment, document)
                 - path_flag (str | None): Decision path (STOP, CONTINUE, REPEAT, or None)
                 - confidence (int): Confidence score for the decision
                 - comment (str): Detailed explanation of the decision
+                - document (dict | None): Metadata describing the filter(s) that produced
+                    `path_flag`, shaped `{'filters': [{'name', 'policy', 'counter'}, ...]}`;
+                    `None` when nothing was filtered. Not written anywhere by this activity —
+                    the caller decides whether and how to persist it.
 
         Raises:
             Exception: If response validation fails or configuration is invalid
@@ -369,10 +399,11 @@ class Gates(SientiaMonitoring):
         gate_type = input_data['type']
         path_priority = input_data['path_priority']
 
-        filter_output = []
-
         comments = []
 
+        # (filter_name, policy, filter_config) per filter that triggered, in configured order
+        triggered_filters: list[tuple[str, str, dict[str, Any]]] = []
+
         status = payload.status or {}
 
         for fil, config in filters.items():
@@ -381,7 +412,7 @@ class Gates(SientiaMonitoring):
             policy, filter_config = self._read_filter_entry(config)
             try:
                 if mlflow_response_filter_functions[fil](status, filter_config):
-                    filter_output.append(policy)
+                    triggered_filters.append((fil, policy, filter_config))
                     comments.append(status.get('message', 'Unknown MLFlow API error'))
                     self.send_notification(
                         metadata=metadata,
@@ -402,16 +433,42 @@ class Gates(SientiaMonitoring):
                     attachment_content=trace,
                 )
 
+        triggered_policies = [policy for _, policy, _ in triggered_filters]
+
         for path_flag in path_priority:
-            if path_flag in filter_output:
+            if path_flag in triggered_policies:
                 self.info(f'Mlflow response gate result: {path_flag}', metadata)
-                return path_flag, mlflow_response_path_confidence[path_flag], ', '.join(comments)
+
+                matched = [
+                    (fil, filter_config)
+                    for fil, policy, filter_config in triggered_filters
+                    if policy == path_flag
+                ]
+                document = {
+                    'filters': [
+                        {
+                            'name': fil,
+                            'policy': path_flag,
+                            'counter': mlflow_response_filter_counters.get(fil, lambda *_: 0)(
+                                status, filter_config
+                            ),
+                        }
+                        for fil, filter_config in matched
+                    ],
+                }
+
+                return (
+                    path_flag,
+                    mlflow_response_path_confidence[path_flag],
+                    ', '.join(comments),
+                    document,
+                )
 
         self.info('Nothing was filtered by the mlflow response gate', metadata)
 
         del data
 
-        return None, 0, ''
+        return None, 0, '', None
 
     @activity.defn(name='mlflow_content_gate')
     def mlflow_content_gate(self, input_data: dict[str, Any]) -> tuple[str | None, int, str]:

laborious/workflows/sub_workflows/prediction_process.py

@@ -156,7 +156,7 @@ class PredictionProcess:
         )
 
         # Validate MLFlow transform response
-        path_flag, confidence, comment = await workflow.execute_local_activity_method(
+        path_flag, confidence, comment, document = await workflow.execute_local_activity_method(
             Activities.mlflow_response_gate,
             {
                 **metadata,
@@ -171,7 +171,7 @@ class PredictionProcess:
 
         # Handle path decision based on transform validation
         if await self.path_flag_handler(
-            data, path_flag, input_data, confidence, last_timestamp, comment
+            data, path_flag, input_data, confidence, last_timestamp, comment, document
         ):
             return
 
@@ -206,7 +206,7 @@ class PredictionProcess:
         )
 
         # Validate MLFlow prediction response
-        path_flag, confidence, comment = await workflow.execute_local_activity_method(
+        path_flag, confidence, comment, document = await workflow.execute_local_activity_method(
             Activities.mlflow_response_gate,
             {
                 **metadata,
@@ -221,7 +221,7 @@ class PredictionProcess:
 
         # Handle path decision based on prediction validation
         if await self.path_flag_handler(
-            data, path_flag, input_data, confidence, last_timestamp, comment
+            data, path_flag, input_data, confidence, last_timestamp, comment, document
         ):
             return
 
@@ -271,9 +271,9 @@ class PredictionProcess:
         """
         if not document:
             # Skip the remote activity call entirely rather than dispatching it just to have
-            # `write_prediction_metadata` decide there's nothing to write — `mlflow_response_gate`
-            # and `mlflow_content_gate` don't build a `document` yet, so this is the common case
-            # today, not a rare edge case (review finding, 2026-10-01).
+            # `write_prediction_metadata` decide there's nothing to write — `mlflow_content_gate`
+            # doesn't build a `document` yet, so this is the common case today, not a rare edge
+            # case (review finding, 2026-10-01).
             return None
 
         try: