uipath-langchain 0.1.24__py3-none-any.whl → 0.1.34__py3-none-any.whl

uipath_langchain/agent/guardrails/guardrail_nodes.py

@@ -1,26 +1,109 @@
+import json
 import logging
 import re
 from typing import Any, Callable
 
-from langchain_core.messages import AnyMessage, HumanMessage, SystemMessage
 from langgraph.types import Command
+from uipath.core.guardrails import (
+    DeterministicGuardrail,
+    DeterministicGuardrailsService,
+)
 from uipath.platform import UiPath
 from uipath.platform.guardrails import (
     BaseGuardrail,
+    BuiltInValidatorGuardrail,
     GuardrailScope,
 )
+from uipath.runtime.errors import UiPathErrorCode
 
 from uipath_langchain.agent.guardrails.types import ExecutionStage
+from uipath_langchain.agent.guardrails.utils import (
+    _extract_tool_input_data,
+    _extract_tool_output_data,
+    get_message_content,
+)
+from uipath_langchain.agent.react.types import AgentGuardrailsGraphState
 
-from .types import AgentGuardrailsGraphState
+from ..exceptions import AgentTerminationException
 
 logger = logging.getLogger(__name__)
 
 
-def _message_text(msg: AnyMessage) -> str:
-    if isinstance(msg, (HumanMessage, SystemMessage)):
-        return msg.content if isinstance(msg.content, str) else str(msg.content)
-    return str(getattr(msg, "content", "")) if hasattr(msg, "content") else ""
+def _evaluate_deterministic_guardrail(
+    state: AgentGuardrailsGraphState,
+    guardrail: DeterministicGuardrail,
+    execution_stage: ExecutionStage,
+    input_data_extractor: Callable[[AgentGuardrailsGraphState], dict[str, Any]],
+    output_data_extractor: Callable[[AgentGuardrailsGraphState], dict[str, Any]] | None,
+):
+    """Evaluate deterministic guardrail.
+
+    Args:
+        state: The current agent graph state.
+        guardrail: The deterministic guardrail to evaluate.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+        input_data_extractor: Function to extract input data from state.
+        output_data_extractor: Function to extract output data from state (optional).
+
+    Returns:
+        The guardrail evaluation result.
+    """
+    service = DeterministicGuardrailsService()
+    input_data = input_data_extractor(state)
+
+    if execution_stage == ExecutionStage.PRE_EXECUTION:
+        return service.evaluate_pre_deterministic_guardrail(
+            input_data=input_data, guardrail=guardrail
+        )
+    else:  # POST_EXECUTION
+        output_data = output_data_extractor(state) if output_data_extractor else {}
+        return service.evaluate_post_deterministic_guardrail(
+            input_data=input_data,
+            output_data=output_data,
+            guardrail=guardrail,
+        )
+
+
+def _evaluate_builtin_guardrail(
+    state: AgentGuardrailsGraphState,
+    guardrail: BuiltInValidatorGuardrail,
+    payload_generator: Callable[[AgentGuardrailsGraphState], str],
+):
+    """Evaluate built-in validator guardrail.
+
+    Args:
+        state: The current agent graph state.
+        guardrail: The built-in validator guardrail to evaluate.
+        payload_generator: Function to generate payload text from state.
+
+    Returns:
+        The guardrail evaluation result.
+    """
+    text = payload_generator(state)
+    uipath = UiPath()
+    return uipath.guardrails.evaluate_guardrail(text, guardrail)
+
+
+def _create_validation_command(
+    result,
+    success_node: str,
+    failure_node: str,
+) -> Command[Any]:
+    """Create command based on validation result.
+
+    Args:
+        result: The guardrail evaluation result.
+        success_node: Node to route to on validation pass.
+        failure_node: Node to route to on validation fail.
+
+    Returns:
+        Command to update state and route to appropriate node.
+    """
+    if not result.validation_passed:
+        return Command(
+            goto=failure_node, update={"guardrail_validation_result": result.reason}
+        )
+    return Command(goto=success_node, update={"guardrail_validation_result": None})
 
 
 def _create_guardrail_node(
@@ -30,6 +113,10 @@ def _create_guardrail_node(
     payload_generator: Callable[[AgentGuardrailsGraphState], str],
     success_node: str,
     failure_node: str,
+    input_data_extractor: Callable[[AgentGuardrailsGraphState], dict[str, Any]]
+    | None = None,
+    output_data_extractor: Callable[[AgentGuardrailsGraphState], dict[str, Any]]
+    | None = None,
 ) -> tuple[str, Callable[[AgentGuardrailsGraphState], Any]]:
     """Private factory for guardrail evaluation nodes.
 
@@ -43,19 +130,41 @@ def _create_guardrail_node(
     async def node(
         state: AgentGuardrailsGraphState,
     ):
-        text = payload_generator(state)
         try:
-            uipath = UiPath()
-            result = uipath.guardrails.evaluate_guardrail(text, guardrail)
-        except Exception as exc:
-            logger.error("Failed to evaluate guardrail: %s", exc)
-            raise
+            # Route to appropriate evaluation service based on guardrail type and scope
+            if (
+                isinstance(guardrail, DeterministicGuardrail)
+                and scope == GuardrailScope.TOOL
+                and input_data_extractor is not None
+            ):
+                result = _evaluate_deterministic_guardrail(
+                    state,
+                    guardrail,
+                    execution_stage,
+                    input_data_extractor,
+                    output_data_extractor,
+                )
+            elif isinstance(guardrail, BuiltInValidatorGuardrail):
+                result = _evaluate_builtin_guardrail(
+                    state, guardrail, payload_generator
+                )
+            else:
+                raise AgentTerminationException(
+                    code=UiPathErrorCode.EXECUTION_ERROR,
+                    title="Unsupported guardrail type",
+                    detail=f"Guardrail type '{type(guardrail).__name__}' is not supported. "
+                    f"Expected DeterministicGuardrail or BuiltInValidatorGuardrail.",
+                )
+
+            return _create_validation_command(result, success_node, failure_node)
 
-        if not result.validation_passed:
-            return Command(
-                goto=failure_node, update={"guardrail_validation_result": result.reason}
+        except Exception as exc:
+            logger.error(
+                "Failed to evaluate guardrail '%s': %s",
+                guardrail.name,
+                exc,
             )
-        return Command(goto=success_node, update={"guardrail_validation_result": None})
+            raise
 
     return node_name, node
 
@@ -69,7 +178,7 @@ def create_llm_guardrail_node(
     def _payload_generator(state: AgentGuardrailsGraphState) -> str:
         if not state.messages:
             return ""
-        return _message_text(state.messages[-1])
+        return get_message_content(state.messages[-1])
 
     return _create_guardrail_node(
         guardrail,
@@ -81,17 +190,35 @@ def create_llm_guardrail_node(
     )
 
 
-def create_agent_guardrail_node(
+def create_agent_init_guardrail_node(
     guardrail: BaseGuardrail,
     execution_stage: ExecutionStage,
     success_node: str,
     failure_node: str,
 ) -> tuple[str, Callable[[AgentGuardrailsGraphState], Any]]:
-    # To be implemented in future PR
     def _payload_generator(state: AgentGuardrailsGraphState) -> str:
         if not state.messages:
             return ""
-        return _message_text(state.messages[-1])
+        return get_message_content(state.messages[-1])
+
+    return _create_guardrail_node(
+        guardrail,
+        GuardrailScope.AGENT,
+        execution_stage,
+        _payload_generator,
+        success_node,
+        failure_node,
+    )
+
+
+def create_agent_terminate_guardrail_node(
+    guardrail: BaseGuardrail,
+    execution_stage: ExecutionStage,
+    success_node: str,
+    failure_node: str,
+) -> tuple[str, Callable[[AgentGuardrailsGraphState], Any]]:
+    def _payload_generator(state: AgentGuardrailsGraphState) -> str:
+        return str(state.agent_result)
 
     return _create_guardrail_node(
         guardrail,
@@ -108,12 +235,47 @@ def create_tool_guardrail_node(
     execution_stage: ExecutionStage,
     success_node: str,
     failure_node: str,
+    tool_name: str,
 ) -> tuple[str, Callable[[AgentGuardrailsGraphState], Any]]:
-    # To be implemented in future PR
+    """Create a guardrail node for TOOL scope guardrails.
+
+    Args:
+        guardrail: The guardrail to evaluate.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+        success_node: Node to route to on validation pass.
+        failure_node: Node to route to on validation fail.
+        tool_name: Name of the tool to extract arguments from.
+
+    Returns:
+        A tuple of (node_name, node_function) for the guardrail evaluation node.
+    """
+
     def _payload_generator(state: AgentGuardrailsGraphState) -> str:
+        """Extract tool call arguments for the specified tool name.
+
+        Args:
+            state: The current agent graph state.
+
+        Returns:
+            JSON string of the tool call arguments, or empty string if not found.
+        """
         if not state.messages:
             return ""
-        return _message_text(state.messages[-1])
+
+        if execution_stage == ExecutionStage.PRE_EXECUTION:
+            # Extract tool args as dict and convert to JSON string
+            args_dict = _extract_tool_input_data(state, tool_name, execution_stage)
+            if args_dict:
+                return json.dumps(args_dict)
+
+        return get_message_content(state.messages[-1])
+
+    # Create closures for input/output data extraction (for deterministic guardrails)
+    def _input_data_extractor(state: AgentGuardrailsGraphState) -> dict[str, Any]:
+        return _extract_tool_input_data(state, tool_name, execution_stage)
+
+    def _output_data_extractor(state: AgentGuardrailsGraphState) -> dict[str, Any]:
+        return _extract_tool_output_data(state)
 
     return _create_guardrail_node(
         guardrail,
@@ -122,4 +284,6 @@ def create_tool_guardrail_node(
         _payload_generator,
         success_node,
         failure_node,
+        _input_data_extractor,
+        _output_data_extractor,
     )

uipath_langchain/agent/guardrails/guardrails_factory.py

@@ -1,13 +1,28 @@
 import logging
-from typing import Sequence
+import re
+from typing import Callable, Sequence
 
 from uipath.agent.models.agent import (
+    AgentBooleanOperator,
+    AgentBooleanRule,
+    AgentCustomGuardrail,
     AgentGuardrail,
     AgentGuardrailBlockAction,
     AgentGuardrailEscalateAction,
     AgentGuardrailLogAction,
     AgentGuardrailSeverityLevel,
+    AgentNumberOperator,
+    AgentNumberRule,
     AgentUnknownGuardrail,
+    AgentWordOperator,
+    AgentWordRule,
+)
+from uipath.core.guardrails import (
+    BooleanRule,
+    DeterministicGuardrail,
+    NumberRule,
+    UniversalRule,
+    WordRule,
 )
 from uipath.platform.guardrails import BaseGuardrail
 
@@ -19,6 +34,180 @@ from uipath_langchain.agent.guardrails.actions import (
 )
 
 
+def _assert_value_not_none(value: str | None, operator: AgentWordOperator) -> str:
+    """Assert value is not None and return as string."""
+    assert value is not None, f"value cannot be None for {operator.name} operator"
+    return value
+
+
+def _create_word_rule_func(
+    operator: AgentWordOperator, value: str | None
+) -> Callable[[str], bool]:
+    """Create a callable function from AgentWordOperator and value.
+
+    Args:
+        operator: The word operator to convert.
+        value: The value to compare against (may be None for isEmpty/isNotEmpty).
+
+    Returns:
+        A callable that takes a string and returns a boolean.
+    """
+    match operator:
+        case AgentWordOperator.CONTAINS:
+            val = _assert_value_not_none(value, operator)
+            return lambda s: val.lower() in s.lower()
+        case AgentWordOperator.DOES_NOT_CONTAIN:
+            val = _assert_value_not_none(value, operator)
+            return lambda s: val.lower() not in s.lower()
+        case AgentWordOperator.EQUALS:
+            val = _assert_value_not_none(value, operator)
+            return lambda s: s == val
+        case AgentWordOperator.DOES_NOT_EQUAL:
+            val = _assert_value_not_none(value, operator)
+            return lambda s: s != val
+        case AgentWordOperator.STARTS_WITH:
+            val = _assert_value_not_none(value, operator)
+            return lambda s: s.startswith(val)
+        case AgentWordOperator.DOES_NOT_START_WITH:
+            val = _assert_value_not_none(value, operator)
+            return lambda s: not s.startswith(val)
+        case AgentWordOperator.ENDS_WITH:
+            val = _assert_value_not_none(value, operator)
+            return lambda s: s.endswith(val)
+        case AgentWordOperator.DOES_NOT_END_WITH:
+            val = _assert_value_not_none(value, operator)
+            return lambda s: not s.endswith(val)
+        case AgentWordOperator.IS_EMPTY:
+            return lambda s: len(s) == 0
+        case AgentWordOperator.IS_NOT_EMPTY:
+            return lambda s: len(s) > 0
+        case AgentWordOperator.MATCHES_REGEX:
+            val = _assert_value_not_none(value, operator)
+            pattern = re.compile(val)
+            return lambda s: bool(pattern.match(s))
+        case _:
+            raise ValueError(f"Unsupported word operator: {operator}")
+
+
+def _create_number_rule_func(
+    operator: AgentNumberOperator, value: float
+) -> Callable[[float], bool]:
+    """Create a callable function from AgentNumberOperator and value.
+
+    Args:
+        operator: The number operator to convert.
+        value: The value to compare against.
+
+    Returns:
+        A callable that takes a float and returns a boolean.
+    """
+    match operator:
+        case AgentNumberOperator.EQUALS:
+            return lambda n: n == value
+        case AgentNumberOperator.DOES_NOT_EQUAL:
+            return lambda n: n != value
+        case AgentNumberOperator.GREATER_THAN:
+            return lambda n: n > value
+        case AgentNumberOperator.GREATER_THAN_OR_EQUAL:
+            return lambda n: n >= value
+        case AgentNumberOperator.LESS_THAN:
+            return lambda n: n < value
+        case AgentNumberOperator.LESS_THAN_OR_EQUAL:
+            return lambda n: n <= value
+        case _:
+            raise ValueError(f"Unsupported number operator: {operator}")
+
+
+def _create_boolean_rule_func(
+    operator: AgentBooleanOperator, value: bool
+) -> Callable[[bool], bool]:
+    """Create a callable function from AgentBooleanOperator and value.
+
+    Args:
+        operator: The boolean operator to convert.
+        value: The value to compare against.
+
+    Returns:
+        A callable that takes a boolean and returns a boolean.
+    """
+    match operator:
+        case AgentBooleanOperator.EQUALS:
+            return lambda b: b == value
+        case _:
+            raise ValueError(f"Unsupported boolean operator: {operator}")
+
+
+def _convert_agent_rule_to_deterministic(
+    agent_rule: AgentWordRule | AgentNumberRule | AgentBooleanRule | UniversalRule,
+) -> WordRule | NumberRule | BooleanRule | UniversalRule:
+    """Convert an Agent rule to its Deterministic equivalent.
+
+    Args:
+        agent_rule: The agent rule to convert.
+
+    Returns:
+        The corresponding deterministic rule with a callable function.
+    """
+    if isinstance(agent_rule, UniversalRule):
+        # UniversalRule is already compatible
+        return agent_rule
+
+    if isinstance(agent_rule, AgentWordRule):
+        return WordRule(
+            rule_type="word",
+            field_selector=agent_rule.field_selector,
+            detects_violation=_create_word_rule_func(
+                agent_rule.operator, agent_rule.value
+            ),
+        )
+
+    if isinstance(agent_rule, AgentNumberRule):
+        return NumberRule(
+            rule_type="number",
+            field_selector=agent_rule.field_selector,
+            detects_violation=_create_number_rule_func(
+                agent_rule.operator, agent_rule.value
+            ),
+        )
+
+    if isinstance(agent_rule, AgentBooleanRule):
+        return BooleanRule(
+            rule_type="boolean",
+            field_selector=agent_rule.field_selector,
+            detects_violation=_create_boolean_rule_func(
+                agent_rule.operator, agent_rule.value
+            ),
+        )
+
+    raise ValueError(f"Unsupported agent rule type: {type(agent_rule)}")
+
+
+def _convert_agent_custom_guardrail_to_deterministic(
+    guardrail: AgentCustomGuardrail,
+) -> DeterministicGuardrail:
+    """Convert AgentCustomGuardrail to DeterministicGuardrail.
+
+    Args:
+        guardrail: The agent custom guardrail to convert.
+
+    Returns:
+        A DeterministicGuardrail with converted rules.
+    """
+    converted_rules = [
+        _convert_agent_rule_to_deterministic(rule) for rule in guardrail.rules
+    ]
+
+    return DeterministicGuardrail(
+        id=guardrail.id,
+        name=guardrail.name,
+        description=guardrail.description,
+        enabled_for_evals=guardrail.enabled_for_evals,
+        selector=guardrail.selector,
+        guardrail_type="custom",
+        rules=converted_rules,
+    )
+
+
 def build_guardrails_with_actions(
     guardrails: Sequence[AgentGuardrail] | None,
 ) -> list[tuple[BaseGuardrail, GuardrailAction]]:
@@ -38,10 +227,17 @@ def build_guardrails_with_actions(
         if isinstance(guardrail, AgentUnknownGuardrail):
             continue
 
+        # Convert AgentCustomGuardrail to DeterministicGuardrail
+        converted_guardrail: BaseGuardrail = guardrail
+        if isinstance(guardrail, AgentCustomGuardrail):
+            converted_guardrail = _convert_agent_custom_guardrail_to_deterministic(
+                guardrail
+            )
+
         action = guardrail.action
 
         if isinstance(action, AgentGuardrailBlockAction):
-            result.append((guardrail, BlockAction(action.reason)))
+            result.append((converted_guardrail, BlockAction(action.reason)))
         elif isinstance(action, AgentGuardrailLogAction):
             severity_level_map = {
                 AgentGuardrailSeverityLevel.ERROR: logging.ERROR,
@@ -51,14 +247,14 @@ def build_guardrails_with_actions(
             level = severity_level_map.get(action.severity_level, logging.INFO)
             result.append(
                 (
-                    guardrail,
+                    converted_guardrail,
                     LogAction(message=action.message, level=level),
                 )
             )
         elif isinstance(action, AgentGuardrailEscalateAction):
             result.append(
                 (
-                    guardrail,
+                    converted_guardrail,
                     EscalateAction(
                         app_name=action.app.name,
                         app_folder_path=action.app.folder_name,

uipath_langchain/agent/guardrails/types.py

@@ -1,16 +1,4 @@
 from enum import Enum
-from typing import Annotated, Optional
-
-from langchain_core.messages import AnyMessage
-from langgraph.graph.message import add_messages
-from pydantic import BaseModel
-
-
-class AgentGuardrailsGraphState(BaseModel):
-    """Agent Guardrails Graph state for guardrail subgraph."""
-
-    messages: Annotated[list[AnyMessage], add_messages] = []
-    guardrail_validation_result: Optional[str] = None
 
 
 class ExecutionStage(str, Enum):

uipath_langchain/agent/guardrails/utils.py

@@ -0,0 +1,146 @@
+import json
+import logging
+from typing import Any
+
+from langchain_core.messages import (
+    AIMessage,
+    AnyMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
+
+from uipath_langchain.agent.guardrails.types import ExecutionStage
+from uipath_langchain.agent.react.types import AgentGuardrailsGraphState
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_tool_args_from_message(
+    message: AnyMessage, tool_name: str
+) -> dict[str, Any]:
+    """Extract tool call arguments from an AIMessage.
+
+    Args:
+        message: The message to extract from.
+        tool_name: Name of the tool to extract arguments from.
+
+    Returns:
+        Dict containing tool call arguments, or empty dict if not found.
+    """
+    if not isinstance(message, AIMessage):
+        return {}
+
+    if not message.tool_calls:
+        return {}
+
+    # Find the first tool call with matching name
+    for tool_call in message.tool_calls:
+        call_name = (
+            tool_call.get("name")
+            if isinstance(tool_call, dict)
+            else getattr(tool_call, "name", None)
+        )
+        if call_name == tool_name:
+            # Extract args from the tool call
+            args = (
+                tool_call.get("args")
+                if isinstance(tool_call, dict)
+                else getattr(tool_call, "args", None)
+            )
+            if args is not None:
+                # Args should already be a dict
+                if isinstance(args, dict):
+                    return args
+                # If it's a JSON string, parse it
+                if isinstance(args, str):
+                    try:
+                        parsed = json.loads(args)
+                        if isinstance(parsed, dict):
+                            return parsed
+                    except json.JSONDecodeError:
+                        logger.warning(
+                            "Failed to parse tool args as JSON for tool '%s': %s",
+                            tool_name,
+                            args[:100] if len(args) > 100 else args,
+                        )
+                        return {}
+
+    return {}
+
+
+def _extract_tool_input_data(
+    state: AgentGuardrailsGraphState, tool_name: str, execution_stage: ExecutionStage
+) -> dict[str, Any]:
+    """Extract tool call arguments as dict for deterministic guardrails.
+
+    Args:
+        state: The current agent graph state.
+        tool_name: Name of the tool to extract arguments from.
+        execution_stage: PRE_EXECUTION or POST_EXECUTION.
+
+    Returns:
+        Dict containing tool call arguments, or empty dict if not found.
+        - For PRE_EXECUTION: extracts from last message
+        - For POST_EXECUTION: extracts from second-to-last message
+    """
+    if not state.messages:
+        return {}
+
+    # For PRE_EXECUTION, look at last message
+    # For POST_EXECUTION, look at second-to-last message (before the ToolMessage)
+    if execution_stage == ExecutionStage.PRE_EXECUTION:
+        if len(state.messages) < 1:
+            return {}
+        message = state.messages[-1]
+    else:  # POST_EXECUTION
+        if len(state.messages) < 2:
+            return {}
+        message = state.messages[-2]
+
+    return _extract_tool_args_from_message(message, tool_name)
+
+
+def _extract_tool_output_data(state: AgentGuardrailsGraphState) -> dict[str, Any]:
+    """Extract tool execution output as dict for POST_EXECUTION deterministic guardrails.
+
+    Args:
+        state: The current agent graph state.
+
+    Returns:
+        Dict containing tool output. If output is not valid JSON, wraps it in {"output": content}.
+    """
+    if not state.messages:
+        return {}
+
+    last_message = state.messages[-1]
+    if not isinstance(last_message, ToolMessage):
+        return {}
+
+    content = last_message.content
+    if not content:
+        return {}
+
+    # Try to parse as JSON first
+    if isinstance(content, str):
+        try:
+            parsed = json.loads(content)
+            if isinstance(parsed, dict):
+                return parsed
+            else:
+                # JSON array or primitive - wrap it
+                return {"output": parsed}
+        except json.JSONDecodeError:
+            logger.warning("Tool output is not valid JSON")
+            return {"output": content}
+    elif isinstance(content, dict):
+        return content
+    else:
+        # List or other type
+        return {"output": content}
+
+
+def get_message_content(msg: AnyMessage) -> str:
+    if isinstance(msg, (HumanMessage, SystemMessage)):
+        return msg.content if isinstance(msg.content, str) else str(msg.content)
+    return str(getattr(msg, "content", "")) if hasattr(msg, "content") else ""