feat(guardrails): add decorator framework to uipath-platform

Move @guardrail decorator, validators, actions, and adapter registry
from uipath-langchain into uipath-platform as a framework-agnostic
subpackage. Includes PIIValidator, PromptInjectionValidator,
CustomValidator, BlockAction, LogAction, and GuardrailTargetAdapter
Protocol. Bump version to 0.1.18.

Remove unused _evaluate_rules function and its tests (was dead code —
never called outside of tests). Also drops unused GuardrailValidationResultType
import and inspect module.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: apetraru-uipath

packages/uipath-platform/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-platform"
-version = "0.1.17"
+version = "0.1.18"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

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

@@ -14,6 +14,24 @@
 )
 
 from ._guardrails_service import GuardrailsService
+from .decorators import (
+    BlockAction,
+    CustomValidator,
+    GuardrailAction,
+    GuardrailBlockException,
+    GuardrailExecutionStage,
+    GuardrailTargetAdapter,
+    GuardrailValidatorBase,
+    LogAction,
+    LoggingSeverityLevel,
+    PIIDetectionEntity,
+    PIIDetectionEntityType,
+    PIIValidator,
+    PromptInjectionValidator,
+    RuleFunction,
+    guardrail,
+    register_guardrail_adapter,
+)
 from .guardrails import (
     BuiltInValidatorGuardrail,
     EnumListParameterValue,
@@ -22,7 +40,9 @@
 )
 
 __all__ = [
+    # Service
     "GuardrailsService",
+    # Guardrail models
     "BuiltInValidatorGuardrail",
     "GuardrailType",
     "GuardrailValidationResultType",
@@ -33,4 +53,21 @@
     "GuardrailValidationResult",
     "EnumListParameterValue",
     "MapEnumParameterValue",
+    # Decorator framework
+    "guardrail",
+    "GuardrailValidatorBase",
+    "PIIValidator",
+    "PromptInjectionValidator",
+    "CustomValidator",
+    "RuleFunction",
+    "PIIDetectionEntity",
+    "PIIDetectionEntityType",
+    "GuardrailExecutionStage",
+    "GuardrailAction",
+    "LogAction",
+    "BlockAction",
+    "LoggingSeverityLevel",
+    "GuardrailBlockException",
+    "GuardrailTargetAdapter",
+    "register_guardrail_adapter",
 ]

packages/uipath-platform/src/uipath/platform/guardrails/decorators/__init__.py

@@ -0,0 +1,64 @@
+"""Guardrail decorator framework for UiPath Platform.
+
+Provides the ``@guardrail`` decorator, built-in validators, actions, and an
+adapter registry that framework integrations (e.g. *uipath-langchain*) use to
+teach the decorator how to wrap their specific object types.
+
+Quick start::
+
+    from uipath.platform.guardrails.decorators import (
+        guardrail,
+        PIIValidator,
+        LogAction,
+        BlockAction,
+        PIIDetectionEntity,
+        PIIDetectionEntityType,
+        GuardrailExecutionStage,
+    )
+
+    pii = PIIValidator(entities=[PIIDetectionEntity(PIIDetectionEntityType.EMAIL)])
+
+    # Applied to a factory function (LangChain adapter must be imported first):
+    @guardrail(validator=pii, action=LogAction(), name="LLM PII")
+    def create_llm():
+        ...
+"""
+
+from ._actions import BlockAction, LogAction, LoggingSeverityLevel
+from ._enums import GuardrailExecutionStage, PIIDetectionEntityType
+from ._exceptions import GuardrailBlockException
+from ._guardrail import guardrail
+from ._models import GuardrailAction, PIIDetectionEntity
+from ._registry import GuardrailTargetAdapter, register_guardrail_adapter
+from .validators import (
+    CustomValidator,
+    GuardrailValidatorBase,
+    PIIValidator,
+    PromptInjectionValidator,
+    RuleFunction,
+)
+
+__all__ = [
+    # Decorator
+    "guardrail",
+    # Validators
+    "GuardrailValidatorBase",
+    "PIIValidator",
+    "PromptInjectionValidator",
+    "CustomValidator",
+    "RuleFunction",
+    # Models & enums
+    "PIIDetectionEntity",
+    "PIIDetectionEntityType",
+    "GuardrailExecutionStage",
+    "GuardrailAction",
+    # Actions
+    "LogAction",
+    "BlockAction",
+    "LoggingSeverityLevel",
+    # Exception
+    "GuardrailBlockException",
+    # Adapter registry
+    "GuardrailTargetAdapter",
+    "register_guardrail_adapter",
+]

packages/uipath-platform/src/uipath/platform/guardrails/decorators/_actions.py

@@ -0,0 +1,82 @@
+"""Built-in GuardrailAction implementations."""
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Optional
+
+from uipath.core.guardrails import (
+    GuardrailValidationResult,
+    GuardrailValidationResultType,
+)
+
+from ._exceptions import GuardrailBlockException
+from ._models import GuardrailAction
+
+
+class LoggingSeverityLevel(int, Enum):
+    """Logging severity level for :class:`LogAction`."""
+
+    ERROR = logging.ERROR
+    INFO = logging.INFO
+    WARNING = logging.WARNING
+    DEBUG = logging.DEBUG
+
+
+@dataclass
+class LogAction(GuardrailAction):
+    """Log guardrail violations without stopping execution.
+
+    Args:
+        severity_level: Python logging level. Defaults to ``WARNING``.
+        message: Custom log message. If omitted, the validation reason is used.
+    """
+
+    severity_level: LoggingSeverityLevel = LoggingSeverityLevel.WARNING
+    message: Optional[str] = None
+
+    def handle_validation_result(
+        self,
+        result: GuardrailValidationResult,
+        data: str | dict[str, Any],
+        guardrail_name: str,
+    ) -> str | dict[str, Any] | None:
+        """Log the violation and return ``None`` (no data modification)."""
+        if result.result == GuardrailValidationResultType.VALIDATION_FAILED:
+            msg = self.message or f"Failed: {result.reason}"
+            logging.getLogger(__name__).log(
+                self.severity_level,
+                "[GUARDRAIL] [%s] %s",
+                guardrail_name,
+                msg,
+            )
+        return None
+
+
+@dataclass
+class BlockAction(GuardrailAction):
+    """Block execution by raising :class:`GuardrailBlockException`.
+
+    Framework adapters catch ``GuardrailBlockException`` at the wrapper boundary
+    and convert it to their own runtime error type.
+
+    Args:
+        title: Exception title. Defaults to a message derived from the guardrail name.
+        detail: Exception detail. Defaults to the validation reason.
+    """
+
+    title: Optional[str] = None
+    detail: Optional[str] = None
+
+    def handle_validation_result(
+        self,
+        result: GuardrailValidationResult,
+        data: str | dict[str, Any],
+        guardrail_name: str,
+    ) -> str | dict[str, Any] | None:
+        """Raise :class:`GuardrailBlockException` when validation fails."""
+        if result.result == GuardrailValidationResultType.VALIDATION_FAILED:
+            title = self.title or f"Guardrail [{guardrail_name}] blocked execution"
+            detail = self.detail or result.reason or "Guardrail validation failed"
+            raise GuardrailBlockException(title=title, detail=detail)
+        return None

packages/uipath-platform/src/uipath/platform/guardrails/decorators/_core.py

@@ -0,0 +1,149 @@
+"""Core framework-agnostic utilities for guardrail decorators."""
+
+import ast
+import json
+import logging
+from typing import Any, Callable
+
+from uipath.core.guardrails import GuardrailValidationResult
+
+from uipath.platform.guardrails.guardrails import BuiltInValidatorGuardrail
+
+from ._enums import GuardrailExecutionStage
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Evaluator type alias
+# ---------------------------------------------------------------------------
+
+_EvaluatorFn = Callable[
+    [
+        "str | dict[str, Any]",  # data
+        GuardrailExecutionStage,  # stage
+        "dict[str, Any] | None",  # input_data
+        "dict[str, Any] | None",  # output_data
+    ],
+    GuardrailValidationResult,
+]
+"""Type alias for the unified evaluation callable used by all wrappers."""
+
+
+# ---------------------------------------------------------------------------
+# Evaluator factory
+# ---------------------------------------------------------------------------
+
+
+def _make_evaluator(
+    validator: Any,
+    built_in_guardrail: BuiltInValidatorGuardrail | None,
+) -> _EvaluatorFn:
+    """Return a unified evaluation callable.
+
+    If *built_in_guardrail* is provided the callable hits the UiPath API (lazily
+    initializing ``UiPath()``). Otherwise, it delegates to ``validator.evaluate()``.
+
+    Args:
+        validator: :class:`GuardrailValidatorBase` instance for local evaluation.
+        built_in_guardrail: Pre-built ``BuiltInValidatorGuardrail``, or ``None``.
+
+    Returns:
+        Callable with signature ``(data, stage, input_data, output_data)``.
+    """
+    if built_in_guardrail is not None:
+        _uipath_holder: list[Any] = []
+
+        def _api_eval(
+            data: str | dict[str, Any],
+            stage: GuardrailExecutionStage,
+            input_data: dict[str, Any] | None,
+            output_data: dict[str, Any] | None,
+        ) -> GuardrailValidationResult:
+            if not _uipath_holder:
+                from uipath.platform import UiPath
+
+                _uipath_holder.append(UiPath())
+            return _uipath_holder[0].guardrails.evaluate_guardrail(
+                data, built_in_guardrail
+            )
+
+        return _api_eval
+
+    def _local_eval(
+        data: str | dict[str, Any],
+        stage: GuardrailExecutionStage,
+        input_data: dict[str, Any] | None,
+        output_data: dict[str, Any] | None,
+    ) -> GuardrailValidationResult:
+        return validator.evaluate(data, stage, input_data, output_data)
+
+    return _local_eval
+
+
+# ---------------------------------------------------------------------------
+# Guardrail evaluation helpers
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Tool I/O normalisation helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_tool_call_envelope(tool_input: Any) -> bool:
+    """Return ``True`` if *tool_input* is a LangGraph tool-call envelope dict."""
+    return (
+        isinstance(tool_input, dict)
+        and "args" in tool_input
+        and tool_input.get("type") == "tool_call"
+    )
+
+
+def _extract_input(tool_input: Any) -> dict[str, Any]:
+    """Normalise tool input to a plain dict for rule / guardrail evaluation.
+
+    LangGraph wraps tool inputs as ``{"name": ..., "args": {...}, "type": "tool_call"}``.
+    This function unwraps ``args`` so rules can access the actual tool arguments.
+    """
+    if _is_tool_call_envelope(tool_input):
+        args = tool_input["args"]
+        if isinstance(args, dict):
+            return args
+    if isinstance(tool_input, dict):
+        return tool_input
+    return {"input": tool_input}
+
+
+def _rewrap_input(original_tool_input: Any, modified_args: dict[str, Any]) -> Any:
+    """Re-wrap modified args back into the original tool-call envelope (if applicable)."""
+    if _is_tool_call_envelope(original_tool_input):
+        import copy
+
+        wrapped = copy.copy(original_tool_input)
+        wrapped["args"] = modified_args
+        return wrapped
+    return modified_args
+
+
+def _extract_output(result: Any) -> dict[str, Any]:
+    """Normalise tool output to a dict for guardrail / rule evaluation.
+
+    This is the framework-agnostic version. Framework adapters that deal with
+    framework-specific envelope types (e.g. LangGraph ``ToolMessage`` /
+    ``Command``) should pre-process the result before calling this function.
+
+    Falls back to ``{"output": content}`` for plain strings and anything else.
+    """
+    if isinstance(result, dict):
+        return result
+    if isinstance(result, str):
+        try:
+            parsed = json.loads(result)
+            return parsed if isinstance(parsed, dict) else {"output": parsed}
+        except ValueError:
+            try:
+                parsed = ast.literal_eval(result)
+                return parsed if isinstance(parsed, dict) else {"output": parsed}
+            except (ValueError, SyntaxError):
+                return {"output": result}
+    return {"output": result}