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

uipath_langchain/agent/guardrails/actions/escalate_action.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, Literal
+
+from langchain_core.messages import AIMessage, ToolMessage
+from langgraph.types import Command, interrupt
+from uipath.platform.common import CreateEscalation
+from uipath.platform.guardrails import (
+    BaseGuardrail,
+    GuardrailScope,
+)
+from uipath.runtime.errors import UiPathErrorCode
+
+from ...exceptions import AgentTerminationException
+from ..guardrail_nodes import _message_text
+from ..types import AgentGuardrailsGraphState, ExecutionStage
+from .base_action import GuardrailAction, GuardrailActionNode
+
+
+class EscalateAction(GuardrailAction):
+    """Node-producing action that inserts a HITL interruption node into the graph.
+
+    The returned node creates a human-in-the-loop interruption that suspends execution
+    and waits for human review. When execution resumes, if the escalation was approved,
+    the flow continues with the reviewed content; otherwise, an error is raised.
+    """
+
+    def __init__(
+        self,
+        app_name: str,
+        app_folder_path: str,
+        version: int,
+        assignee: str,
+    ):
+        self.app_name = app_name
+        self.app_folder_path = app_folder_path
+        self.version = version
+        self.assignee = assignee
+
+    def action_node(
+        self,
+        *,
+        guardrail: BaseGuardrail,
+        scope: GuardrailScope,
+        execution_stage: ExecutionStage,
+    ) -> GuardrailActionNode:
+        node_name = _get_node_name(execution_stage, guardrail, scope)
+
+        async def _node(
+            state: AgentGuardrailsGraphState,
+        ) -> Dict[str, Any] | Command[Any]:
+            input = _extract_escalation_content(state, scope, execution_stage)
+            escalation_field = _execution_stage_to_escalation_field(execution_stage)
+
+            data = {
+                "GuardrailName": guardrail.name,
+                "GuardrailDescription": guardrail.description,
+                "Component": scope.name.lower(),
+                "ExecutionStage": _execution_stage_to_string(execution_stage),
+                "GuardrailResult": state.guardrail_validation_result,
+                escalation_field: input,
+            }
+
+            escalation_result = interrupt(
+                CreateEscalation(
+                    app_name=self.app_name,
+                    app_folder_path=self.app_folder_path,
+                    title=self.app_name,
+                    data=data,
+                    assignee=self.assignee,
+                )
+            )
+
+            if escalation_result.action == "Approve":
+                return _process_escalation_response(
+                    state, escalation_result.data, scope, execution_stage
+                )
+
+            raise AgentTerminationException(
+                code=UiPathErrorCode.EXECUTION_ERROR,
+                title="Escalation rejected",
+                detail=f"Action was rejected after reviewing the task created by guardrail [{guardrail.name}]. Please contact your administrator.",
+            )
+
+        return node_name, _node
+
+
+def _get_node_name(
+    execution_stage: ExecutionStage, guardrail: BaseGuardrail, scope: GuardrailScope
+) -> str:
+    sanitized = re.sub(r"\W+", "_", guardrail.name).strip("_").lower()
+    node_name = f"{sanitized}_hitl_{execution_stage.name.lower()}_{scope.lower()}"
+    return node_name
+
+
+def _execution_stage_to_string(
+    execution_stage: ExecutionStage,
+) -> Literal["PreExecution", "PostExecution"]:
+    """Convert ExecutionStage enum to string literal.
+
+    Args:
+        execution_stage: The execution stage enum.
+
+    Returns:
+        "PreExecution" for PRE_EXECUTION, "PostExecution" for POST_EXECUTION.
+    """
+    if execution_stage == ExecutionStage.PRE_EXECUTION:
+        return "PreExecution"
+    return "PostExecution"
+
+
+def _process_escalation_response(
+    state: AgentGuardrailsGraphState,
+    escalation_result: Dict[str, Any],
+    scope: GuardrailScope,
+    execution_stage: ExecutionStage,
+) -> Dict[str, Any] | Command[Any]:
+    """Process escalation response and update state based on guardrail scope.
+
+    Args:
+        state: The current agent graph state.
+        escalation_result: The result from the escalation interrupt.
+        scope: The guardrail scope (LLM/AGENT/TOOL).
+        execution_stage: The hook type ("PreExecution" or "PostExecution").
+
+    Returns:
+        For LLM scope: Command to update messages with reviewed inputs/outputs.
+        For non-LLM scope: Empty dict (no message alteration).
+
+    Raises:
+        AgentTerminationException: If escalation response processing fails.
+    """
+    if scope != GuardrailScope.LLM:
+        return {}
+
+    try:
+        reviewed_field = (
+            "ReviewedInputs"
+            if execution_stage == ExecutionStage.PRE_EXECUTION
+            else "ReviewedOutputs"
+        )
+
+        msgs = state.messages.copy()
+        if not msgs or reviewed_field not in escalation_result:
+            return {}
+
+        last_message = msgs[-1]
+
+        if execution_stage == ExecutionStage.PRE_EXECUTION:
+            reviewed_content = escalation_result[reviewed_field]
+            if reviewed_content:
+                last_message.content = json.loads(reviewed_content)
+        else:
+            reviewed_outputs_json = escalation_result[reviewed_field]
+            if not reviewed_outputs_json:
+                return {}
+
+            content_list = json.loads(reviewed_outputs_json)
+            if not content_list:
+                return {}
+
+            # For AI messages, process tool calls if present
+            if isinstance(last_message, AIMessage):
+                ai_message: AIMessage = last_message
+                content_index = 0
+
+                if ai_message.tool_calls:
+                    tool_calls = list(ai_message.tool_calls)
+                    for tool_call in tool_calls:
+                        args = tool_call["args"]
+                        if (
+                            isinstance(args, dict)
+                            and "content" in args
+                            and args["content"] is not None
+                        ):
+                            if content_index < len(content_list):
+                                updated_content = json.loads(
+                                    content_list[content_index]
+                                )
+                                args["content"] = updated_content
+                                tool_call["args"] = args
+                                content_index += 1
+                    ai_message.tool_calls = tool_calls
+
+                if len(content_list) > content_index:
+                    ai_message.content = content_list[-1]
+            else:
+                # Fallback for other message types
+                if content_list:
+                    last_message.content = content_list[-1]
+
+        return Command[Any](update={"messages": msgs})
+    except Exception as e:
+        raise AgentTerminationException(
+            code=UiPathErrorCode.EXECUTION_ERROR,
+            title="Escalation rejected",
+            detail=str(e),
+        ) from e
+
+
+def _extract_escalation_content(
+    state: AgentGuardrailsGraphState,
+    scope: GuardrailScope,
+    execution_stage: ExecutionStage,
+) -> str | list[str | Dict[str, Any]]:
+    """Extract escalation content from state based on guardrail scope and execution stage.
+
+    Args:
+        state: The current agent graph state.
+        scope: The guardrail scope (LLM/AGENT/TOOL).
+        execution_stage: The execution stage enum.
+
+    Returns:
+        For non-LLM scope: Empty string.
+        For LLM PreExecution: JSON string with message content.
+        For LLM PostExecution: JSON array with tool call content and message content.
+    """
+    if scope != GuardrailScope.LLM:
+        return ""
+
+    if not state.messages:
+        raise AgentTerminationException(
+            code=UiPathErrorCode.EXECUTION_ERROR,
+            title="Invalid state message",
+            detail="No messages in state",
+        )
+
+    last_message = state.messages[-1]
+    if execution_stage == ExecutionStage.PRE_EXECUTION:
+        if isinstance(last_message, ToolMessage):
+            return last_message.content
+
+        content = _message_text(last_message)
+        return json.dumps(content) if content else ""
+
+    # For AI messages, process tool calls if present
+    if isinstance(last_message, AIMessage):
+        ai_message: AIMessage = last_message
+        content_list: list[str] = []
+
+        if ai_message.tool_calls:
+            for tool_call in ai_message.tool_calls:
+                args = tool_call["args"]
+                if (
+                    isinstance(args, dict)
+                    and "content" in args
+                    and args["content"] is not None
+                ):
+                    content_list.append(json.dumps(args["content"]))
+
+        message_content = _message_text(last_message)
+        if message_content:
+            content_list.append(message_content)
+
+        return json.dumps(content_list)
+
+    # Fallback for other message types
+    return _message_text(last_message)
+
+
+def _execution_stage_to_escalation_field(
+    execution_stage: ExecutionStage,
+) -> str:
+    """Convert execution stage to escalation data field name.
+
+    Args:
+        execution_stage: The execution stage enum.
+
+    Returns:
+        "Inputs" for PRE_EXECUTION, "Outputs" for POST_EXECUTION.
+    """
+    return "Inputs" if execution_stage == ExecutionStage.PRE_EXECUTION else "Outputs"

uipath_langchain/agent/guardrails/actions/log_action.py

@@ -0,0 +1,57 @@
+import logging
+import re
+from typing import Any, Optional
+
+from uipath.platform.guardrails import BaseGuardrail, GuardrailScope
+
+from uipath_langchain.agent.guardrails.types import ExecutionStage
+
+from ..types import AgentGuardrailsGraphState
+from .base_action import GuardrailAction, GuardrailActionNode
+
+logger = logging.getLogger(__name__)
+
+
+class LogAction(GuardrailAction):
+    """Action that logs guardrail violation and continues."""
+
+    def __init__(self, message: Optional[str], level: int = logging.INFO) -> None:
+        """Initialize the log action.
+
+        Args:
+            message: Message to be logged.
+            level: Logging level used when reporting a guardrail failure.
+        """
+        self.message = message
+        self.level = level
+
+    def action_node(
+        self,
+        *,
+        guardrail: BaseGuardrail,
+        scope: GuardrailScope,
+        execution_stage: ExecutionStage,
+    ) -> GuardrailActionNode:
+        """Create a guardrail action node that logs validation failures.
+
+        Args:
+            guardrail: The guardrail whose failure is being logged.
+            scope: The scope in which the guardrail applies.
+            execution_stage: Whether this runs before or after execution.
+
+        Returns:
+            A tuple containing the node name and the async node callable.
+        """
+        raw_node_name = f"{scope.name}_{execution_stage.name}_{guardrail.name}_log"
+        node_name = re.sub(r"\W+", "_", raw_node_name.lower()).strip("_")
+
+        async def _node(_state: AgentGuardrailsGraphState) -> dict[str, Any]:
+            message = (
+                self.message
+                or f"Guardrail [{guardrail.name}] validation failed for [{scope.name}] [{execution_stage.name}] with the following reason: {_state.guardrail_validation_result}"
+            )
+
+            logger.log(self.level, message)
+            return {}
+
+        return node_name, _node

uipath_langchain/agent/guardrails/guardrail_nodes.py

@@ -0,0 +1,125 @@
+import logging
+import re
+from typing import Any, Callable
+
+from langchain_core.messages import AnyMessage, HumanMessage, SystemMessage
+from langgraph.types import Command
+from uipath.platform import UiPath
+from uipath.platform.guardrails import (
+    BaseGuardrail,
+    GuardrailScope,
+)
+
+from uipath_langchain.agent.guardrails.types import ExecutionStage
+
+from .types import AgentGuardrailsGraphState
+
+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 _create_guardrail_node(
+    guardrail: BaseGuardrail,
+    scope: GuardrailScope,
+    execution_stage: ExecutionStage,
+    payload_generator: Callable[[AgentGuardrailsGraphState], str],
+    success_node: str,
+    failure_node: str,
+) -> tuple[str, Callable[[AgentGuardrailsGraphState], Any]]:
+    """Private factory for guardrail evaluation nodes.
+
+    Returns a node that evaluates the guardrail and routes via Command:
+    - goto success_node on validation pass
+    - goto failure_node on validation fail
+    """
+    raw_node_name = f"{scope.name}_{execution_stage.name}_{guardrail.name}"
+    node_name = re.sub(r"\W+", "_", raw_node_name.lower()).strip("_")
+
+    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
+
+        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})
+
+    return node_name, node
+
+
+def create_llm_guardrail_node(
+    guardrail: BaseGuardrail,
+    execution_stage: ExecutionStage,
+    success_node: str,
+    failure_node: str,
+) -> tuple[str, Callable[[AgentGuardrailsGraphState], Any]]:
+    def _payload_generator(state: AgentGuardrailsGraphState) -> str:
+        if not state.messages:
+            return ""
+        return _message_text(state.messages[-1])
+
+    return _create_guardrail_node(
+        guardrail,
+        GuardrailScope.LLM,
+        execution_stage,
+        _payload_generator,
+        success_node,
+        failure_node,
+    )
+
+
+def create_agent_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 _create_guardrail_node(
+        guardrail,
+        GuardrailScope.AGENT,
+        execution_stage,
+        _payload_generator,
+        success_node,
+        failure_node,
+    )
+
+
+def create_tool_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 _create_guardrail_node(
+        guardrail,
+        GuardrailScope.TOOL,
+        execution_stage,
+        _payload_generator,
+        success_node,
+        failure_node,
+    )

uipath_langchain/agent/guardrails/guardrails_factory.py

@@ -0,0 +1,70 @@
+import logging
+from typing import Sequence
+
+from uipath.agent.models.agent import (
+    AgentGuardrail,
+    AgentGuardrailBlockAction,
+    AgentGuardrailEscalateAction,
+    AgentGuardrailLogAction,
+    AgentGuardrailSeverityLevel,
+    AgentUnknownGuardrail,
+)
+from uipath.platform.guardrails import BaseGuardrail
+
+from uipath_langchain.agent.guardrails.actions import (
+    BlockAction,
+    EscalateAction,
+    GuardrailAction,
+    LogAction,
+)
+
+
+def build_guardrails_with_actions(
+    guardrails: Sequence[AgentGuardrail] | None,
+) -> list[tuple[BaseGuardrail, GuardrailAction]]:
+    """Build a list of (guardrail, action) tuples from model definitions.
+
+    Args:
+        guardrails: Sequence of guardrail model objects or None.
+
+    Returns:
+        A list of tuples pairing each supported guardrail with its executable action.
+    """
+    if not guardrails:
+        return []
+
+    result: list[tuple[BaseGuardrail, GuardrailAction]] = []
+    for guardrail in guardrails:
+        if isinstance(guardrail, AgentUnknownGuardrail):
+            continue
+
+        action = guardrail.action
+
+        if isinstance(action, AgentGuardrailBlockAction):
+            result.append((guardrail, BlockAction(action.reason)))
+        elif isinstance(action, AgentGuardrailLogAction):
+            severity_level_map = {
+                AgentGuardrailSeverityLevel.ERROR: logging.ERROR,
+                AgentGuardrailSeverityLevel.WARNING: logging.WARNING,
+                AgentGuardrailSeverityLevel.INFO: logging.INFO,
+            }
+            level = severity_level_map.get(action.severity_level, logging.INFO)
+            result.append(
+                (
+                    guardrail,
+                    LogAction(message=action.message, level=level),
+                )
+            )
+        elif isinstance(action, AgentGuardrailEscalateAction):
+            result.append(
+                (
+                    guardrail,
+                    EscalateAction(
+                        app_name=action.app.name,
+                        app_folder_path=action.app.folder_name,
+                        version=action.app.version,
+                        assignee=action.recipient.value,
+                    ),
+                )
+            )
+    return result