refactor(actions): migrate built-in rails to RailOutcome (#2151)

Migrate built-in rail actions and streaming bypasses from legacy output-mapping
returns to the engine-neutral RailOutcome contract. Remove the legacy fallback
and add runtime-flow/equivalence coverage for the migrated rails.

Signed-off-by: Pouyanpi <13303554+Pouyanpi@users.noreply.github.com>

Author: Pouyanpi

docs/configure-rails/guardrail-catalog/community/f5-ai-guardrails.mdx

@@ -145,7 +145,7 @@ To customize the behavior, you can overwrite the default flows in your configura
 define subflow f5 guardrails scan input
   $result = execute f5_guardrails_scan(text=$user_message)
 
-  if $result.result.outcome != "cleared"
+  if $result.is_blocked
     bot say "I cannot process this request due to safety policies."
     stop
 ```

nemoguardrails/actions/actions.py

@@ -30,7 +30,6 @@ class ActionMeta(TypedDict):
     name: str
     is_system_action: bool
     execute_async: bool
-    output_mapping: Optional[Callable[[Any], bool]]
 
 
 # Create a TypeVar to represent the decorated function or class
@@ -41,17 +40,13 @@ def action(
     is_system_action: bool = False,
     name: Optional[str] = None,
     execute_async: bool = False,
-    output_mapping: Optional[Callable[[Any], bool]] = None,
 ) -> Callable[[T], T]:
     """Decorator to mark a function or class as an action.
 
     Args:
         is_system_action (bool): Flag indicating if the action is a system action.
         name (str): The name to associate with the action.
         execute_async: Whether the function should be executed in async mode.
-        output_mapping (Optional[Callable[[Any], bool]]): A function to interpret the action's result.
-            It accepts the return value (e.g. the first element of a tuple) and return True if the output
-            is not safe.
 
     Returns:
         callable: The decorated function or class.
@@ -74,7 +69,6 @@ def decorator(fn_or_cls: T) -> T:
             "name": action_name,
             "is_system_action": is_system_action,
             "execute_async": execute_async,
-            "output_mapping": output_mapping,
         }
 
         setattr(fn_or_cls_target, "action_meta", action_meta)

nemoguardrails/actions/output_mapping.py

@@ -25,7 +25,7 @@
 
 from nemoguardrails.actions.actions import ActionResult
 from nemoguardrails.actions.core import create_event
-from nemoguardrails.actions.output_mapping import is_output_blocked
+from nemoguardrails.actions.rail_outcome import require_rail_outcome
 from nemoguardrails.colang import parse_colang_file
 from nemoguardrails.colang.runtime import Runtime
 from nemoguardrails.colang.v1_0.runtime.flows import (
@@ -488,11 +488,7 @@ async def run_single_rail(flow_id: str, action_info: dict) -> tuple:
                     log.error(error_msg)
                     return flow_id, "internal_error", error_msg
 
-                action_func = self.action_dispatcher.get_action(action_name)
-
-                # use the mapping to decide if the result indicates blocked content.
-                # True means blocked, False means allowed
-                result = is_output_blocked(result, action_func)
+                result = require_rail_outcome(result).is_blocked
 
                 return flow_id, result, None
 

nemoguardrails/colang/v1_0/runtime/runtime.py

@@ -15,62 +15,66 @@
 import json
 import logging
 import os
-from typing import Optional
+from typing import Literal, Optional
 
 import aiohttp
 
 from nemoguardrails.actions import action
+from nemoguardrails.actions.rail_outcome import RailOutcome
 from nemoguardrails.utils import new_uuid
 
 log = logging.getLogger(__name__)
 
-
-def call_activefence_api_mapping(result: dict) -> bool:
-    """
-    Mapping for call_activefence_api.
-
-    Expects result to be a dict with:
-      - "max_risk_score": a float representing the overall risk.
-      - "violations": a dict mapping violation type (str) to risk score (float).
-
-    Block (return True) if any of the following conditions are met:
-      1. Overall max risk score > 0.7.
-      2. Individual thresholds are exceeded:
-         - "abusive_or_harmful.harassment_or_bullying" > 0.8
-         - "abusive_or_harmful.profanity" > 0.7
-         - "abusive_or_harmful.hate_speech" > 0.6
-         - "abusive_or_harmful.child_grooming" > 0.4
-         - "abusive_or_harmful.general_violence" > 0.7
-         - "self_harm.general" > 0.8
-         - "adult_content.general" > 0.3
-         - "privacy_violation.pii" > 0.8
-    """
-    max_risk = result.get("max_risk_score", 0.0)
-    if max_risk > 0.7:
-        return True
-
-    violations = result.get("violations", {})
-
-    thresholds = {
-        "abusive_or_harmful.harassment_or_bullying": 0.8,
-        "abusive_or_harmful.profanity": 0.7,
-        "abusive_or_harmful.hate_speech": 0.6,
-        "abusive_or_harmful.child_grooming": 0.4,
-        "abusive_or_harmful.general_violence": 0.7,
-        "self_harm.general": 0.8,
-        "adult_content.general": 0.3,
-        "privacy_violation.pii": 0.8,
+ACTIVEFENCE_DETAILED_THRESHOLDS = {
+    "abusive_or_harmful.harassment_or_bullying": 0.8,
+    "abusive_or_harmful.profanity": 0.7,
+    "abusive_or_harmful.hate_speech": 0.6,
+    "abusive_or_harmful.child_grooming": 0.4,
+    "abusive_or_harmful.general_violence": 0.7,
+    "self_harm.general": 0.8,
+    "adult_content.general": 0.3,
+    "privacy_violation.pii": 0.8,
+}
+
+
+def _activefence_simple_blocked(max_risk_score: float) -> bool:
+    return max_risk_score > 0.7
+
+
+def _activefence_detailed_blocked(violations: dict[str, float]) -> bool:
+    return any(
+        violations.get(violation_type, 0) > threshold
+        for violation_type, threshold in ACTIVEFENCE_DETAILED_THRESHOLDS.items()
+    )
+
+
+def _activefence_outcome(
+    max_risk_score: float,
+    violations: dict[str, float],
+    threshold_mode: Literal["simple", "detailed"] = "simple",
+) -> RailOutcome:
+    metadata = {
+        "max_risk_score": max_risk_score,
+        "violations": violations,
+        "threshold_mode": threshold_mode,
     }
-
-    for violation_type, threshold in thresholds.items():
-        if violations.get(violation_type, 0) > threshold:
-            return True
-
-    return False
-
-
-@action(is_system_action=True, output_mapping=call_activefence_api_mapping)
-async def call_activefence_api(text: Optional[str] = None, **kwargs):
+    blocked = (
+        _activefence_detailed_blocked(violations)
+        if threshold_mode == "detailed"
+        else _activefence_simple_blocked(max_risk_score)
+    )
+
+    if blocked:
+        return RailOutcome.block(metadata=metadata)
+    return RailOutcome.allow(metadata=metadata)
+
+
+@action(is_system_action=True)
+async def call_activefence_api(
+    text: Optional[str] = None,
+    threshold_mode: Literal["simple", "detailed"] = "simple",
+    **kwargs,
+) -> RailOutcome:
     api_key = os.environ.get("ACTIVEFENCE_API_KEY")
 
     if api_key is None:
@@ -104,4 +108,4 @@ async def call_activefence_api(text: Optional[str] = None, **kwargs):
                     max_risk_score = violation["risk_score"]
                 violations_dict[violation["violation_type"]] = violation["risk_score"]
 
-            return {"max_risk_score": max_risk_score, "violations": violations_dict}
+            return _activefence_outcome(max_risk_score, violations_dict, threshold_mode)

nemoguardrails/library/activefence/actions.py

@@ -15,9 +15,9 @@ Privacy Violation	PII
 
 flow activefence moderation on input
   """Guardrail based on the maximum risk score."""
-  $result = await  CallActivefenceApiAction(text=$user_message)
+  $result = await  CallActivefenceApiAction(text=$user_message, threshold_mode="simple")
 
-  if $result.max_risk_score > 0.7
+  if $result.is_blocked
     if $system.config.enable_rails_exceptions
       send ActiveFenceModerationRailException(message="ActiveFence moderation triggered. The maximum risk score exceeded the threshold.")
     else
@@ -26,9 +26,9 @@ flow activefence moderation on input
 
 flow activefence moderation on output
   """Guardrail based on the maximum risk score."""
-  $result = await  CallActivefenceApiAction(text=$bot_message)
+  $result = await  CallActivefenceApiAction(text=$bot_message, threshold_mode="simple")
 
-  if $result.max_risk_score > 0.7
+  if $result.is_blocked
     if $system.config.enable_rails_exceptions
       send ActiveFenceModerationRailException(message="ActiveFence moderation triggered. The maximum risk score exceeded the threshold.")
     else
@@ -37,58 +37,58 @@ flow activefence moderation on output
 
 flow activefence moderation on input detailed
   """Guardrail based on individual risk scores."""
-  $result = await  CallActivefenceApiAction(text=$user_message)
+  $result = await  CallActivefenceApiAction(text=$user_message, threshold_mode="detailed")
 
-  if $result.violations.get("abusive_or_harmful.harassment_or_bullying", 0) > 0.8
+  if $result.metadata["violations"].get("abusive_or_harmful.harassment_or_bullying", 0) > 0.8
     if $system.config.enable_rails_exceptions
       send ActiveFenceHarassmentRailException(message="ActiveFence moderation triggered. The harassment or bullying risk score exceeded the threshold.")
     else
       bot inform cannot engage in abusive_or_harmful behavior
     abort
 
-  if $result.violations.get("abusive_or_harmful.profanity", 0) > 0.7
+  if $result.metadata["violations"].get("abusive_or_harmful.profanity", 0) > 0.7
     if $system.config.enable_rails_exceptions
       send ActiveFenceProfanityRailException(message="ActiveFence moderation triggered. The profanity risk score exceeded the threshold.")
     else
       bot inform cannot engage in abusive_or_harmful behavior
     abort
 
-  if $result.violations.get("abusive_or_harmful.hate_speech", 0) > 0.6
+  if $result.metadata["violations"].get("abusive_or_harmful.hate_speech", 0) > 0.6
     if $system.config.enable_rails_exceptions
       send ActiveFenceHateSpeechRailException(message="ActiveFence moderation triggered. The hate speech risk score exceeded the threshold.")
     else
       bot inform cannot engage in abusive_or_harmful behavior
     abort
 
-  if $result.violations.get("abusive_or_harmful.child_grooming", 0) > 0.4
+  if $result.metadata["violations"].get("abusive_or_harmful.child_grooming", 0) > 0.4
     if $system.config.enable_rails_exceptions
       send ActiveFenceChildGroomingRailException(message="ActiveFence moderation triggered. The child grooming risk score exceeded the threshold.")
     else
       bot inform cannot engage in abusive_or_harmful behavior
     abort
 
-  if $result.violations.get("abusive_or_harmful.general_violence", 0) > 0.7
+  if $result.metadata["violations"].get("abusive_or_harmful.general_violence", 0) > 0.7
     if $system.config.enable_rails_exceptions
       send ActiveFenceGeneralViolenceRailException(message="ActiveFence moderation triggered. The general violence risk score exceeded the threshold.")
     else
       bot inform cannot engage in abusive_or_harmful behavior
     abort
 
-  if $result.violations.get("self_harm.general", 0) > 0.8
+  if $result.metadata["violations"].get("self_harm.general", 0) > 0.8
     if $system.config.enable_rails_exceptions
       send ActiveFenceSelfHarmRailException(message="ActiveFence moderation triggered. The self harm risk score exceeded the threshold.")
     else
       bot inform cannot engage in self harm behavior
     abort
 
-  if $result.violations.get("adult_content.general", 0) > 0.3
+  if $result.metadata["violations"].get("adult_content.general", 0) > 0.3
     if $system.config.enable_rails_exceptions
       send ActiveFenceAdultContentRailException(message="ActiveFence moderation triggered. The adult content risk score exceeded the threshold.")
     else
       bot inform cannot engage with inappropriate content
     abort
 
-  if $result.violations.get("privacy_violation.pii", 0) > 0.8
+  if $result.metadata["violations"].get("privacy_violation.pii", 0) > 0.8
     if $system.config.enable_rails_exceptions
       send ActiveFencePrivacyViolationRailException(message="ActiveFence moderation triggered. The privacy violation risk score exceeded the threshold.")
     else