refactor: decouple guardrails from _uipath to avoid cyclic dependency

Author: andreiancuta-uipath

packages/uipath-platform/pyproject.toml

@@ -138,8 +138,8 @@ type = "layers"
 containers = ["uipath.platform"]
 exhaustive = true
 layers = [
-    "_uipath : guardrails : resume_triggers",
-    "agenthub : automation_ops : automation_tracker : connections : context_grounding : entities : external_applications : governance : memory : pii_detection : portal : resource_catalog : semantic_proxy",
+    "_uipath : resume_triggers",
+    "agenthub : automation_ops : automation_tracker : connections : context_grounding : entities : external_applications : governance : guardrails : memory : pii_detection : portal : resource_catalog : semantic_proxy",
     "orchestrator",
     "action_center : attachments : chat : documents : identity",
     "common",

packages/uipath-platform/src/uipath/platform/_uipath.py

@@ -1,8 +1,6 @@
 from functools import cached_property
 from typing import Optional
 
-from pydantic import ValidationError
-
 from uipath.platform.automation_tracker import AutomationTrackerService
 
 from .action_center import TasksService
@@ -12,15 +10,13 @@
 from .chat import ConversationsService, UiPathLlmChatService, UiPathOpenAIService
 from .common import (
     ApiClient,
-    UiPathApiConfig,
     UiPathExecutionContext,
 )
-from .common.auth import resolve_config_from_env
+from .common.auth import build_api_config, resolve_config_from_env
 from .connections import ConnectionsService
 from .context_grounding import ContextGroundingService
 from .documents import DocumentsService
 from .entities import EntitiesService
-from .errors import BaseUrlMissingError, SecretMissingError
 from .external_applications import ExternalApplicationService
 from .governance import GovernanceService
 from .guardrails import GuardrailsService
@@ -60,25 +56,15 @@ def __init__(
         scope: Optional[str] = None,
         debug: bool = False,
     ) -> None:
-        try:
-            if _has_valid_client_credentials(client_id, client_secret):
-                assert client_id and client_secret
-                service = ExternalApplicationService(base_url)
-                token_data = service.get_token_data(client_id, client_secret, scope)
-                base_url, secret = service._base_url, token_data.access_token
-            else:
-                base_url, secret = resolve_config_from_env(base_url, secret)
-
-            self._config = UiPathApiConfig(
-                base_url=base_url,
-                secret=secret,
-            )
-        except ValidationError as e:
-            for error in e.errors():
-                if error["loc"][0] == "base_url":
-                    raise BaseUrlMissingError() from e
-                elif error["loc"][0] == "secret":
-                    raise SecretMissingError() from e
+        if _has_valid_client_credentials(client_id, client_secret):
+            assert client_id and client_secret
+            service = ExternalApplicationService(base_url)
+            token_data = service.get_token_data(client_id, client_secret, scope)
+            base_url, secret = service._base_url, token_data.access_token
+        else:
+            base_url, secret = resolve_config_from_env(base_url, secret)
+
+        self._config = build_api_config(base_url, secret)
         self._execution_context = UiPathExecutionContext()
 
     @property

packages/uipath-platform/src/uipath/platform/common/auth.py

@@ -3,13 +3,16 @@
 from os import environ as env
 from typing import Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
 
 from uipath.platform.constants import (
     ENV_BASE_URL,
     ENV_UIPATH_ACCESS_TOKEN,
     ENV_UNATTENDED_USER_ACCESS_TOKEN,
 )
+from uipath.platform.errors import BaseUrlMissingError, SecretMissingError
+
+from ._config import UiPathApiConfig
 
 
 class TokenData(BaseModel):
@@ -35,3 +38,24 @@ def resolve_config_from_env(
         or env.get(ENV_UIPATH_ACCESS_TOKEN)
     )
     return base_url_value, secret_value
+
+
+def build_api_config(
+    base_url: Optional[str],
+    secret: Optional[str],
+) -> UiPathApiConfig:
+    """Build a validated API config, translating missing fields into typed errors.
+
+    Raises:
+        BaseUrlMissingError: If ``base_url`` is missing.
+        SecretMissingError: If ``secret`` is missing.
+    """
+    try:
+        return UiPathApiConfig(base_url=base_url, secret=secret)  # type: ignore[arg-type]
+    except ValidationError as e:
+        for error in e.errors():
+            if error["loc"][0] == "base_url":
+                raise BaseUrlMissingError() from e
+            elif error["loc"][0] == "secret":
+                raise SecretMissingError() from e
+        raise

packages/uipath-platform/src/uipath/platform/guardrails/_default_evaluator.py

@@ -0,0 +1,33 @@
+"""Default env-driven guardrail evaluator."""
+
+from typing import Any
+
+from uipath.core.guardrails import GuardrailValidationResult
+
+from ..common import UiPathExecutionContext
+from ..common.auth import build_api_config, resolve_config_from_env
+from ._guardrails_service import GuardrailsService
+from .guardrails import BuiltInValidatorGuardrail
+
+
+class DefaultGuardrailEvaluator:
+    """Evaluates guardrails via a ``GuardrailsService`` configured from env vars.
+
+    Raises:
+        BaseUrlMissingError: If the base URL is not configured.
+        SecretMissingError: If the access token is not configured.
+    """
+
+    def __init__(self) -> None:
+        base_url, secret = resolve_config_from_env(None, None)
+        self._service = GuardrailsService(
+            build_api_config(base_url, secret), UiPathExecutionContext()
+        )
+
+    def evaluate_guardrail(
+        self,
+        input_data: str | dict[str, Any],
+        guardrail: BuiltInValidatorGuardrail,
+    ) -> GuardrailValidationResult:
+        """Validate input data using the provided guardrail."""
+        return self._service.evaluate_guardrail(input_data, guardrail)

packages/uipath-platform/src/uipath/platform/guardrails/_evaluator.py

@@ -0,0 +1,19 @@
+"""Internal protocol for guardrail evaluation capabilities."""
+
+from typing import Any, Protocol
+
+from uipath.core.guardrails import GuardrailValidationResult
+
+from .guardrails import BuiltInValidatorGuardrail
+
+
+class GuardrailEvaluator(Protocol):
+    """Capability to evaluate a built-in guardrail against input data."""
+
+    def evaluate_guardrail(
+        self,
+        input_data: str | dict[str, Any],
+        guardrail: BuiltInValidatorGuardrail,
+    ) -> GuardrailValidationResult:
+        """Validate input data using the provided guardrail."""
+        ...

packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/_base.py

@@ -5,6 +5,8 @@
 
 from uipath.core.guardrails import GuardrailValidationResult
 
+from uipath.platform.guardrails._default_evaluator import DefaultGuardrailEvaluator
+from uipath.platform.guardrails._evaluator import GuardrailEvaluator
 from uipath.platform.guardrails.guardrails import BuiltInValidatorGuardrail
 
 from .._enums import GuardrailExecutionStage
@@ -78,6 +80,8 @@ def get_built_in_guardrail(self, name, description, enabled_for_evals):
                 )
     """
 
+    _evaluator: GuardrailEvaluator | None = None
+
     @abstractmethod
     def get_built_in_guardrail(
         self,
@@ -109,15 +113,13 @@ def run(
     ) -> GuardrailValidationResult:
         """Evaluate via the UiPath Guardrails API.
 
-        Lazily initialises the ``UiPath`` client on the first call and reuses
-        it for all subsequent invocations.
+        Lazily initialises the guardrail evaluator on the first call and
+        reuses it for all subsequent invocations.
         """
         built_in = self.get_built_in_guardrail(name, description, enabled_for_evals)
-        if not hasattr(self, "_uipath"):
-            from uipath.platform import UiPath
-
-            self._uipath: Any = UiPath()
-        return self._uipath.guardrails.evaluate_guardrail(data, built_in)
+        if self._evaluator is None:
+            self._evaluator = DefaultGuardrailEvaluator()
+        return self._evaluator.evaluate_guardrail(data, built_in)
 
 
 class CustomGuardrailValidator(GuardrailValidatorBase, ABC):

packages/uipath-platform/tests/common/test_auth.py

@@ -0,0 +1,44 @@
+"""Tests for config helpers in uipath.platform.common.auth."""
+
+from unittest.mock import patch
+
+import pytest
+from pydantic import BaseModel, ValidationError
+
+from uipath.platform.common import UiPathApiConfig
+from uipath.platform.common.auth import build_api_config
+from uipath.platform.errors import BaseUrlMissingError, SecretMissingError
+
+
+class TestBuildApiConfig:
+    def test_returns_config_when_both_values_present(self):
+        config = build_api_config("https://test.uipath.com", "token")
+        assert isinstance(config, UiPathApiConfig)
+        assert config.base_url == "https://test.uipath.com"
+        assert config.secret == "token"
+
+    def test_missing_base_url_raises_typed_error(self):
+        with pytest.raises(BaseUrlMissingError):
+            build_api_config(None, "token")
+
+    def test_missing_secret_raises_typed_error(self):
+        with pytest.raises(SecretMissingError):
+            build_api_config("https://test.uipath.com", None)
+
+    def test_both_missing_raises_base_url_error_first(self):
+        with pytest.raises(BaseUrlMissingError):
+            build_api_config(None, None)
+
+    def test_unmatched_validation_error_is_reraised(self):
+        class _Other(BaseModel):
+            other: str
+
+        with pytest.raises(ValidationError) as exc_info:
+            _Other.model_validate({})
+        unmatched = exc_info.value
+
+        with patch(
+            "uipath.platform.common.auth.UiPathApiConfig", side_effect=unmatched
+        ):
+            with pytest.raises(ValidationError):
+                build_api_config("https://test.uipath.com", "token")

packages/uipath-platform/tests/services/test_guardrails_decorators.py

@@ -989,8 +989,8 @@ def test_custom_validator_path_delegates_to_run(self):
         )
         assert result == _PASSED
 
-    def test_built_in_validator_path_lazy_initializes_uipath(self):
-        """BuiltInGuardrailValidator.run() lazily creates UiPath() and calls API."""
+    def test_built_in_validator_uses_injected_evaluator(self):
+        """BuiltInGuardrailValidator.run() delegates to an injected evaluator."""
         from uipath.platform.guardrails.decorators.validators import (
             BuiltInGuardrailValidator,
         )
@@ -1003,16 +1003,102 @@ def get_built_in_guardrail(self, name, description, enabled_for_evals):
                 return mock_built_in
 
         validator = _TestBuiltIn()
+        fake_evaluator = MagicMock()
+        fake_evaluator.evaluate_guardrail.return_value = _PASSED
+        validator._evaluator = fake_evaluator
         evaluator = _make_evaluator(validator, "G", None, True)
 
-        mock_uipath = MagicMock()
-        mock_uipath.guardrails.evaluate_guardrail.return_value = _PASSED
-        with patch("uipath.platform.UiPath", return_value=mock_uipath):
+        result = evaluator({"text": "hello"}, GuardrailExecutionStage.PRE, None, None)
+
+        fake_evaluator.evaluate_guardrail.assert_called_once_with(
+            {"text": "hello"}, mock_built_in
+        )
+        assert result == _PASSED
+
+    def test_built_in_validator_path_lazy_initializes_default_evaluator(self):
+        """BuiltInGuardrailValidator.run() creates the default evaluator once."""
+        from uipath.platform.guardrails.decorators.validators import (
+            BuiltInGuardrailValidator,
+        )
+        from uipath.platform.guardrails.guardrails import BuiltInValidatorGuardrail
+
+        mock_built_in = MagicMock(spec=BuiltInValidatorGuardrail)
+
+        class _TestBuiltIn(BuiltInGuardrailValidator):
+            def get_built_in_guardrail(self, name, description, enabled_for_evals):
+                return mock_built_in
+
+        validator = _TestBuiltIn()
+        evaluator = _make_evaluator(validator, "G", None, True)
+
+        with patch(
+            "uipath.platform.guardrails.decorators.validators._base.DefaultGuardrailEvaluator"
+        ) as mock_default:
+            mock_default.return_value.evaluate_guardrail.return_value = _PASSED
+            evaluator({"text": "hello"}, GuardrailExecutionStage.PRE, None, None)
+            evaluator({"text": "hello"}, GuardrailExecutionStage.PRE, None, None)
+
+        mock_default.assert_called_once_with()
+        assert mock_default.return_value.evaluate_guardrail.call_count == 2
+
+    def test_built_in_validator_without_env_config_raises_missing_errors(
+        self, monkeypatch
+    ):
+        """Missing env credentials surface as typed errors from the decorator path."""
+        from uipath.platform.errors import BaseUrlMissingError, SecretMissingError
+        from uipath.platform.guardrails.decorators.validators import (
+            BuiltInGuardrailValidator,
+        )
+        from uipath.platform.guardrails.guardrails import BuiltInValidatorGuardrail
+
+        class _TestBuiltIn(BuiltInGuardrailValidator):
+            def get_built_in_guardrail(self, name, description, enabled_for_evals):
+                return MagicMock(spec=BuiltInValidatorGuardrail)
+
+        for var in (
+            "UIPATH_URL",
+            "UNATTENDED_USER_ACCESS_TOKEN",
+            "UIPATH_ACCESS_TOKEN",
+        ):
+            monkeypatch.delenv(var, raising=False)
+
+        evaluator = _make_evaluator(_TestBuiltIn(), "G", None, True)
+        with pytest.raises(BaseUrlMissingError):
             evaluator({"text": "hello"}, GuardrailExecutionStage.PRE, None, None)
+
+        monkeypatch.setenv("UIPATH_URL", "https://test.uipath.com")
+        with pytest.raises(SecretMissingError):
             evaluator({"text": "hello"}, GuardrailExecutionStage.PRE, None, None)
 
-        # UiPath() should be created only once despite two calls
-        assert mock_uipath.guardrails.evaluate_guardrail.call_count == 2
+
+# ---------------------------------------------------------------------------
+# 15b. DefaultGuardrailEvaluator
+# ---------------------------------------------------------------------------
+
+
+class TestDefaultGuardrailEvaluator:
+    def test_constructs_service_from_env_and_delegates(self, monkeypatch):
+        """The default evaluator builds a GuardrailsService from env config."""
+        from uipath.platform.guardrails._default_evaluator import (
+            DefaultGuardrailEvaluator,
+        )
+        from uipath.platform.guardrails._guardrails_service import GuardrailsService
+        from uipath.platform.guardrails.guardrails import BuiltInValidatorGuardrail
+
+        monkeypatch.setenv("UIPATH_URL", "https://test.uipath.com")
+        monkeypatch.setenv("UIPATH_ACCESS_TOKEN", "token")
+
+        evaluator = DefaultGuardrailEvaluator()
+        assert isinstance(evaluator._service, GuardrailsService)
+
+        mock_built_in = MagicMock(spec=BuiltInValidatorGuardrail)
+        with patch.object(
+            evaluator._service, "evaluate_guardrail", return_value=_PASSED
+        ) as mock_evaluate:
+            result = evaluator.evaluate_guardrail("hello", mock_built_in)
+
+        mock_evaluate.assert_called_once_with("hello", mock_built_in)
+        assert result == _PASSED
 
 
 # ---------------------------------------------------------------------------