refactor: ensure consistency across detector APIs and reduce code duplication

- Add SYSTEM_ERROR_LABELS constant to base.py (single source of truth)
- Add SERVER_ERROR handling for HTTP 5xx responses in detections_api.py
- Add config incomplete checks before accessing rails.config in actions.py
- Add detections_api_generate_block_message action for dynamic block messages
- Fix env var names in tests (DETECTOR_API_* instead of DETECTIONS_API_*)
- Update test assertion for SERVER_ERROR label on HTTP 500

All tests passing (109 tests)

Author: srikartondapu

nemoguardrails/library/detector_clients/actions.py

@@ -22,24 +22,15 @@
 from typing import Any, Dict, Optional
 
 from nemoguardrails.actions import action
-from nemoguardrails.library.detector_clients.base import AggregatedDetectorResult, DetectorResult
+from nemoguardrails.library.detector_clients.base import (
+    SYSTEM_ERROR_LABELS,
+    AggregatedDetectorResult,
+    DetectorResult,
+)
 from nemoguardrails.library.detector_clients.detections_api import DetectionsAPIClient
 
 log = logging.getLogger(__name__)
 
-""" System error labels indicate infrastructure/configuration issues,
-    not content violations. Detectors with these labels failed to execute
-    properly and should be treated as unavailable. """
-SYSTEM_ERROR_LABELS = {
-    "ERROR",
-    "HTTP_ERROR",
-    "TIMEOUT",
-    "NOT_FOUND",
-    "VALIDATION_ERROR",
-    "INVALID_RESPONSE",
-    "CONFIG_ERROR",
-}
-
 
 async def _run_detections_api_detector(detector_name: str, detector_config: Any, text: str) -> DetectorResult:
     """
@@ -299,3 +290,43 @@ async def detections_api_check_detector(
     log.info(f"Detections API {detector_name}: {'allowed' if result.allowed else 'blocked'} (score={result.score:.3f})")
 
     return result.dict()
+
+
+@action()
+async def detections_api_generate_block_message(context: Optional[Dict] = None, **kwargs) -> str:
+    """
+    Generate detailed block message with detector information.
+
+    Creates user-friendly messages explaining why content was blocked.
+    Prioritizes system errors over content violations.
+
+    Args:
+        context: NeMo context containing input_result from detector checks
+        **kwargs: Additional arguments (ignored)
+
+    Returns:
+        Human-readable block message string
+    """
+    if context is None:
+        return "Input blocked due to content policy violation."
+
+    input_result = context.get("input_result", {})
+
+    # Check for system errors first
+    unavailable = input_result.get("unavailable_detectors", [])
+    if unavailable:
+        return f"Service temporarily unavailable. Detector(s) not reachable: {', '.join(unavailable)}"
+
+    # Check for content blocks
+    blocking = input_result.get("blocking_detectors", [])
+    if not blocking:
+        return "Input blocked due to content policy violation."
+
+    # Single detector blocked
+    if len(blocking) == 1:
+        det = blocking[0]
+        return f"Input blocked by {det['detector']} detector (score: {det['score']:.2f})"
+
+    # Multiple detectors blocked
+    detector_names = [d["detector"] for d in blocking]
+    return f"Input blocked by {len(blocking)} detectors: {', '.join(detector_names)}"

nemoguardrails/library/detector_clients/base.py

@@ -34,6 +34,21 @@
 _http_session: Optional[aiohttp.ClientSession] = None
 _session_lock = asyncio.Lock()
 
+# System error labels indicate infrastructure/configuration issues,
+# not content violations. Detectors with these labels failed to execute
+# properly and should be treated as unavailable.
+SYSTEM_ERROR_LABELS = {
+    "ERROR",
+    "HTTP_ERROR",
+    "TIMEOUT",
+    "NOT_FOUND",
+    "VALIDATION_ERROR",
+    "SERVER_ERROR",
+    "INVALID_RESPONSE",
+    "CONFIG_ERROR",
+    "CONFIG_INCOMPLETE",
+}
+
 
 class DetectorResult(BaseModel):
     """Standardized result from detector execution"""
@@ -132,14 +147,14 @@ def _get_ssl_context(self) -> Union[ssl.SSLContext, bool, None]:
         deployment environments (development, staging, production).
 
         Priority order:
-        1. Custom CA certificate file (if DETECTIONS_API_CA_CERT is set)
-        2. SSL verification toggle (if DETECTIONS_API_VERIFY_SSL is set)
+        1. Custom CA certificate file (if DETECTOR_API_CA_CERT is set)
+        2. SSL verification toggle (if DETECTOR_API_VERIFY_SSL is set)
         3. Default system CA certificates
 
         Environment Variables:
-            DETECTIONS_API_CA_CERT: Path to custom CA certificate file (PEM format)
+            DETECTOR_API_CA_CERT: Path to custom CA certificate file (PEM format)
                                 Common in Kubernetes/OpenShift with mounted secrets
-            DETECTIONS_API_VERIFY_SSL: Set to "false" to disable SSL verification
+            DETECTOR_API_VERIFY_SSL: Set to "false" to disable SSL verification
                                     WARNING: Only for development/testing!
 
         Returns:
@@ -148,17 +163,17 @@ def _get_ssl_context(self) -> Union[ssl.SSLContext, bool, None]:
             None: Use default system CA certificates
         """
         # Check for custom CA certificate file (Kubernetes secret volume)
-        ca_cert_file = os.getenv("DETECTIONS_API_CA_CERT")
+        ca_cert_file = os.getenv("DETECTOR_API_CA_CERT")
         if ca_cert_file and os.path.exists(ca_cert_file):
             ssl_context = ssl.create_default_context(cafile=ca_cert_file)
             log.info(f"Using custom CA certificate from {ca_cert_file}")
             return ssl_context
 
         # Option to disable SSL verification (development/testing only)
-        verify_ssl = os.getenv("DETECTIONS_API_VERIFY_SSL", "true").lower()
+        verify_ssl = os.getenv("DETECTOR_API_VERIFY_SSL", "true").lower()
         if verify_ssl == "false":
             log.warning(
-                "SSL verification disabled via DETECTIONS_API_VERIFY_SSL=false. "
+                "SSL verification disabled via DETECTOR_API_VERIFY_SSL=false. "
                 "This is NOT recommended for production environments!"
             )
             return False
@@ -206,13 +221,13 @@ async def _call_endpoint(
             token = self.api_key
         else:
             # Check for file-based secret (Kubernetes volume mount)
-            secret_file = os.getenv("DETECTIONS_API_KEY_FILE")
+            secret_file = os.getenv("DETECTOR_API_KEY_FILE")
             if secret_file and os.path.exists(secret_file):
                 with open(secret_file, "r") as f:
                     token = f.read().strip()
             else:
                 # Fallback to environment variable
-                token = os.getenv("DETECTIONS_API_KEY")
+                token = os.getenv("DETECTOR_API_KEY")
         if token:
             request_headers["Authorization"] = f"Bearer {token}"
 

nemoguardrails/library/detector_clients/detections_api.py

@@ -115,6 +115,9 @@ def parse_response(self, response: Any, http_status: int) -> DetectorResult:
             elif http_status == 422:
                 label = "VALIDATION_ERROR"
                 reason = f"Invalid request to {self.detector_name}"
+            elif http_status >= 500:
+                label = "SERVER_ERROR"
+                reason = f"Detections API server error (HTTP {http_status})"
             else:
                 label = "ERROR"
                 reason = f"HTTP {http_status} error from {self.detector_name}"

tests/test_detector_clients_base.py

@@ -486,7 +486,7 @@ async def test_post_request_with_env_api_key(self):
         mock_session.post = Mock(return_value=mock_post_cm)
 
         with patch("nemoguardrails.library.detector_clients.base._http_session", mock_session):
-            with patch.dict("os.environ", {"DETECTIONS_API_KEY": "env-key-456"}):
+            with patch.dict("os.environ", {"DETECTOR_API_KEY": "env-key-456"}):
                 await client._call_endpoint(endpoint="http://test.com/api", payload={"text": "test"}, timeout=30)
 
         # Verify env var key used
@@ -508,8 +508,8 @@ def test_ssl_context_with_custom_ca_cert(self, tmp_path):
         client = ConcreteDetectorClient(mock_config, "test-detector")
 
         # Mock ssl.create_default_context to avoid needing valid cert
-        with patch.dict("os.environ", {"DETECTIONS_API_CA_CERT": str(ca_cert_file)}):
-            with patch("ssl.create_default_context") as mock_ssl:
+        with patch.dict("os.environ", {"DETECTOR_API_CA_CERT": str(ca_cert_file)}):
+            with patch("nemoguardrails.library.detector_clients.base.ssl.create_default_context") as mock_ssl:
                 mock_ssl_context = Mock(spec=ssl.SSLContext)
                 mock_ssl.return_value = mock_ssl_context
 
@@ -525,7 +525,7 @@ def test_ssl_context_with_nonexistent_ca_cert_file(self):
 
         client = ConcreteDetectorClient(mock_config, "test-detector")
 
-        with patch.dict("os.environ", {"DETECTIONS_API_CA_CERT": "/nonexistent/path/ca-cert.pem"}):
+        with patch.dict("os.environ", {"DETECTOR_API_CA_CERT": "/nonexistent/path/ca-cert.pem"}):
             ssl_context = client._get_ssl_context()
 
         # Should fall through to default behavior (None)
@@ -537,7 +537,7 @@ def test_ssl_verification_disabled(self):
 
         client = ConcreteDetectorClient(mock_config, "test-detector")
 
-        with patch.dict("os.environ", {"DETECTIONS_API_VERIFY_SSL": "false"}):
+        with patch.dict("os.environ", {"DETECTOR_API_VERIFY_SSL": "false"}):
             ssl_context = client._get_ssl_context()
 
         # Should return False to disable verification
@@ -584,7 +584,7 @@ async def test_api_key_from_file(self, tmp_path):
         mock_session.post = Mock(return_value=mock_post_cm)
 
         with patch("nemoguardrails.library.detector_clients.base._http_session", mock_session):
-            with patch.dict("os.environ", {"DETECTIONS_API_KEY_FILE": str(api_key_file)}):
+            with patch.dict("os.environ", {"DETECTOR_API_KEY_FILE": str(api_key_file)}):
                 await client._call_endpoint(endpoint="http://test.com/api", payload={"text": "test"}, timeout=30)
 
         # Verify Authorization header used file-based key
@@ -612,7 +612,7 @@ async def test_api_key_file_not_exists(self):
         with patch("nemoguardrails.library.detector_clients.base._http_session", mock_session):
             with patch.dict(
                 "os.environ",
-                {"DETECTIONS_API_KEY_FILE": "/nonexistent/api-key", "DETECTIONS_API_KEY": "env-var-key-123"},
+                {"DETECTOR_API_KEY_FILE": "/nonexistent/api-key", "DETECTOR_API_KEY": "env-var-key-123"},
             ):
                 await client._call_endpoint(endpoint="http://test.com/api", payload={"text": "test"}, timeout=30)
 

tests/test_detector_clients_detections_api.py

@@ -335,7 +335,7 @@ def test_parse_response_http_422(self):
         assert result.metadata["http_status"] == 422
 
     def test_parse_response_http_500(self):
-        """Test HTTP 500 returns ERROR"""
+        """Test HTTP 500 returns SERVER_ERROR"""
         mock_config = Mock()
         mock_config.inference_endpoint = "http://test.com"
         mock_config.detector_id = "test-id"
@@ -345,7 +345,7 @@ def test_parse_response_http_500(self):
         result = client.parse_response({}, 500)
 
         assert result.allowed is False
-        assert result.label == "ERROR"
+        assert result.label == "SERVER_ERROR"
         assert "HTTP 500" in result.reason
         assert result.metadata["http_status"] == 500