Merge pull request NVIDIA-NeMo#384 from NVIDIA/feature/support-for-exceptions

Initial work on support for exceptions.

Author: drazvan

docs/user_guides/configuration-guide.md

@@ -706,6 +706,71 @@ rails:
 
 **IMPORTANT**: This is recommended only when enough examples are provided.
 
+## Exceptions
+
+NeMo Guardrails supports raising exceptions from within flows.
+An exception is an event whose name ends with `Exception`, e.g., `InputRailException`.
+When an exception is raised, the final output is a message with the role set to `exception` and the content
+set to additional information about the exception. For example:
+
+```colang
+define flow input rail example
+ # ...
+ create event InputRailException(message="Input not allowed.")
+```
+
+```json
+{
+ "role": "exception",
+ "content": {
+ "type": "InputRailException",
+ "uid": "45a452fa-588e-49a5-af7a-0bab5234dcc3",
+ "event_created_at": "9999-99-99999:24:30.093749+00:00",
+ "source_uid": "NeMoGuardrails",
+ "message": "Input not allowed."
+ }
+}
+```
+
+### Guardrails Library Exception
+
+By default, all the guardrails included in the [Guardrails Library](./guardrails-library.md) return a predefined message
+when a rail is triggered. You can change this behavior by setting the `enable_rails_exceptions` key to `True` in your
+`config.yml` file:
+
+```yaml
+enable_rails_exceptions: True
+```
+
+When this setting is enabled, the rails are triggered, they will return an exception message.
+To understand better what is happening under the hood, here's how the `self check input` rail is implemented:
+
+```colang
+define flow self check input
+ $allowed = execute self_check_input
+ if not $allowed
+ if $config.enable_rails_exceptions
+ create event InputRailException(message="Input not allowed. The input was blocked by the 'self check input' flow.")
+ else
+ bot refuse to respond
+ stop
+```
+
+When the `self check input` rail is triggered, the following exception is returned.
+
+```json
+{
+ "role": "exception",
+ "content": {
+ "type": "InputRailException",
+ "uid": "45a452fa-588e-49a5-af7a-0bab5234dcc3",
+ "event_created_at": "9999-99-99999:24:30.093749+00:00",
+ "source_uid": "NeMoGuardrails",
+ "message": "Input not allowed. The input was blocked by the 'self check input' flow."
+ }
+}
+```
+
 ## Knowledge base Documents
 
 By default, an `LLMRails` instance supports using a set of documents as context for generating the bot responses. To include documents as part of your knowledge base, you must place them in the `kb` folder inside your config folder:

examples/configs/guardrails_only/input/config.co

@@ -7,9 +7,15 @@ define bot deny
 define subflow dummy input rail
  """A dummy input rail which checks if the word "dummy" is included in the text."""
  if "dummy" in $user_message
- bot deny
+ if $config.enable_rails_exceptions
+ create event DummyInputRailException(message="Dummy input detected. The user's message contains the word 'dummy'.")
+ else
+ bot deny
  stop
 
 define subflow allow input
- bot allow
+ if $config.enable_rails_exceptions
+ create event AllowInputRailException(message="Allow input triggered. The bot will respond with 'ALLOW'.")
+ else
+ bot allow
  stop

examples/configs/guardrails_only/output/config.co

@@ -12,11 +12,17 @@ define bot deny
  "DENY"
 
 define subflow dummy output rail
- """A dummy input rail which checks if the word "dummy" is included in the text."""
+ """A dummy output rail which checks if the word "dummy" is included in the text."""
  if "dummy" in $bot_message
- bot deny
+ if $config.enable_rails_exceptions
+ create event DummyOutputRailException(message="Dummy output detected. The bot's message contains the word 'dummy'.")
+ else
+ bot deny
  stop
 
 define subflow allow output
- bot allow
+ if $config.enable_rails_exceptions
+ create event AllowOutputRailException(message="Allow output triggered. The bot will respond with 'ALLOW'. To see it in action you must disable the `enable_rails_exceptions` configuration setting.")
+ else
+ bot allow
  stop

examples/configs/rag/fact_checking/rails/factcheck.co

@@ -24,21 +24,28 @@ define subflow check facts
 
  $accuracy = execute check_facts
  if $accuracy < 0.4
- bot inform answer unknown
+ if $config.enable_rails_exceptions
+ create event FactCheckLowAccuracyRailException(message="Fact check triggered. The accuracy of the response is below 0.4.")
+ else
+ bot inform answer unknown
  stop
 
  if $accuracy < 0.6
  # We need to provide a warning in this case
+ # TODO: Add a warning message
  $bot_message_potentially_inaccurate = True
 
-
 define flow flag potentially inaccurate response
  """Tell the user that the previous answer is potentially inaccurate."""
  bot ...
 
  if $bot_message_potentially_inaccurate
  $bot_message_potentially_inaccurate = False
- bot inform answer potentially inaccurate
+ if $config.enable_rails_exceptions
+ create event PotentiallyInaccurateResponseRailException(message="Potentially inaccurate response detected. The bot's response may be inaccurate.")
+ else
+ bot inform answer potentially inaccurate
+ stop
 
 define bot inform answer potentially inaccurate
  "Attention: the answer above is potentially inaccurate."

nemoguardrails/library/activefence/flows.co

@@ -18,46 +18,72 @@ define subflow activefence moderation
  $result = execute call activefence api
 
  if $result.max_risk_score > 0.7
- bot refuse to respond
+ if $config.enable_rails_exceptions
+ create event ActiveFenceModerationRailException(message="ActiveFence moderation triggered. The maximum risk score exceeded the threshold.")
+ else
+ bot refuse to respond
  stop
 
 define subflow activefence moderation detailed
  """Guardrail based on individual risk scores."""
  $result = execute call activefence api
 
  if $result.violations.get("abusive_or_harmful.harassment_or_bullying", 0) > 0.8
- bot inform cannot engage in abusive or harmful behavior
+ if $config.enable_rails_exceptions
+ create event ActiveFenceHarassmentRailException(message="ActiveFence moderation triggered. The harassment or bullying risk score exceeded the threshold.")
+ else
+ bot inform cannot engage in abusive or harmful behavior
  stop
 
  if $result.violations.get("abusive_or_harmful.profanity", 0) > 0.7
- bot inform cannot engage in abusive or harmful behavior
+ if $config.enable_rails_exceptions
+ create event ActiveFenceProfanityRailException(message="ActiveFence moderation triggered. The profanity risk score exceeded the threshold.")
+ else
+ bot inform cannot engage in abusive or harmful behavior
  stop
 
  if $result.violations.get("abusive_or_harmful.hate_speech", 0) > 0.6
- bot inform cannot engage in abusive or harmful behavior
+ if $config.enable_rails_exceptions
+ create event ActiveFenceHateSpeechRailException(message="ActiveFence moderation triggered. The hate speech risk score exceeded the threshold.")
+ else
+ bot inform cannot engage in abusive or harmful behavior
  stop
 
  if $result.violations.get("abusive_or_harmful.child_grooming", 0) > 0.4
- bot inform cannot engage in abusive or harmful behavior
+ if $config.enable_rails_exceptions
+ create event ActiveFenceChildGroomingRailException(message="ActiveFence moderation triggered. The child grooming risk score exceeded the threshold.")
+ else
+ bot inform cannot engage in abusive or harmful behavior
  stop
 
  if $result.violations.get("abusive_or_harmful.general_violence", 0) > 0.7
- bot inform cannot engage in abusive or harmful behavior
+ if $config.enable_rails_exceptions
+ create event ActiveFenceGeneralViolenceRailException(message="ActiveFence moderation triggered. The general violence risk score exceeded the threshold.")
+ else
+ bot inform cannot engage in abusive or harmful behavior
  stop
 
  if $result.violations.get("self_harm.general", 0) > 0.8
- bot inform cannot engage in self harm behavior
+ if $config.enable_rails_exceptions
+ create event ActiveFenceSelfHarmRailException(message="ActiveFence moderation triggered. The self harm risk score exceeded the threshold.")
+ else
+ bot inform cannot engage in self harm behavior
  stop
 
  if $result.violations.get("adult_content.general", 0) > 0.3
- bot inform cannot engage with inappropriate content
+ if $config.enable_rails_exceptions
+ create event ActiveFenceAdultContentRailException(message="ActiveFence moderation triggered. The adult content risk score exceeded the threshold.")
+ else
+ bot inform cannot engage with inappropriate content
  stop
 
  if $result.violations.get("privacy_violation.pii", 0) > 0.8
- bot inform cannot engage with sensitive content
+ if $config.enable_rails_exceptions
+ create event ActiveFencePrivacyViolationRailException(message="ActiveFence moderation triggered. The privacy violation risk score exceeded the threshold.")
+ else
+ bot inform cannot engage with sensitive content
  stop
 
-
 define bot inform cannot engage in abusive or harmful behavior
  "I will not engage in any abusive or harmful behavior."
 

nemoguardrails/library/hallucination/flows.co

@@ -23,5 +23,8 @@ define subflow self check hallucination
  $check_hallucination = False
 
  if $is_hallucination
- bot inform answer unknown
+ if $config.enable_rails_exceptions
+ create event CheckHallucinationRailException(message="Hallucination detected. The previous answer may not be accurate")
+ else
+ bot inform answer unknown
  stop

nemoguardrails/library/jailbreak_detection/flows.co

@@ -1,12 +1,15 @@
+define bot refuse to respond
+ "I'm sorry, I can't respond to that."
+
 define subflow jailbreak detection heuristics
  """
  Heuristic checks to assess whether the user's prompt is an attempted jailbreak.
  """
  $is_jailbreak = execute jailbreak_detection_heuristics
 
  if $is_jailbreak
- bot refuse to respond
+ if $config.enable_rails_exceptions
+ create event JailbreakDetectionRailException(message="Jailbreak attempt detected. The user's prompt was identified as an attempted jailbreak. Please ensure your prompt adheres to the guidelines.")
+ else
+ bot refuse to respond
  stop
-
-define bot refuse to respond
- "I'm sorry, I can't respond to that."

nemoguardrails/library/llama_guard/flows.co

@@ -8,7 +8,10 @@ define flow llama guard check input
  $llama_guard_policy_violations = $llama_guard_response["policy_violations"]
 
  if not $allowed
- bot refuse to respond
+ if $config.enable_rails_exceptions
+ create event LlamaGuardInputRailException(message="Input not allowed. The input was blocked by the 'llama guard check input' flow. Please ensure your input meets the required criteria.")
+ else
+ bot refuse to respond
  stop
 
 define flow llama guard check output
@@ -17,5 +20,8 @@ define flow llama guard check output
  $llama_guard_policy_violations = $llama_guard_response["policy_violations"]
 
  if not $allowed
- bot refuse to respond
+ if $config.enable_rails_exceptions
+ create event LlamaGuardOutputRailException(message="Output not allowed. The output was blocked by the 'llama guard check output' flow. Please ensure your output meets the required criteria.")
+ else
+ bot refuse to respond
  stop

nemoguardrails/library/self_check/facts/flows.co

@@ -12,5 +12,8 @@ define subflow self check facts
 
  $accuracy = execute self_check_facts
  if $accuracy < 0.5
- bot refuse to respond
+ if $config.enable_rails_exceptions
+ create event FactCheckRailRailException(message="Fact check failed. The accuracy of the previous answer was below the required threshold.")
+ else
+ bot refuse to respond
  stop

nemoguardrails/library/self_check/input_check/flows.co

@@ -5,5 +5,8 @@ define flow self check input
  $allowed = execute self_check_input
 
  if not $allowed
- bot refuse to respond
+ if $config.enable_rails_exceptions
+ create event InputRailException(message="Input not allowed. The input was blocked by the 'self check input' flow.")
+ else
+ bot refuse to respond
  stop