uipath-langchain 0.1.28__py3-none-any.whl → 0.3.1__py3-none-any.whl

uipath_langchain/agent/guardrails/guardrails_factory.py

@@ -1,22 +1,218 @@
 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,
+    AgentGuardrailFilterAction,
     AgentGuardrailLogAction,
     AgentGuardrailSeverityLevel,
+    AgentNumberOperator,
+    AgentNumberRule,
     AgentUnknownGuardrail,
+    AgentWordOperator,
+    AgentWordRule,
+    StandardRecipient,
 )
-from uipath.platform.guardrails import BaseGuardrail
+from uipath.core.guardrails import (
+    BooleanRule,
+    DeterministicGuardrail,
+    NumberRule,
+    UniversalRule,
+    WordRule,
+)
+from uipath.platform.guardrails import BaseGuardrail, GuardrailScope
 
 from uipath_langchain.agent.guardrails.actions import (
     BlockAction,
     EscalateAction,
+    FilterAction,
     GuardrailAction,
     LogAction,
 )
+from uipath_langchain.agent.guardrails.utils import _sanitize_selector_tool_names
+
+
+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 and sanitized selector.
+    """
+    converted_rules = [
+        _convert_agent_rule_to_deterministic(rule) for rule in guardrail.rules
+    ]
+
+    # Sanitize tool names in selector for Tool scope guardrails
+    sanitized_selector = _sanitize_selector_tool_names(guardrail.selector)
+
+    return DeterministicGuardrail(
+        id=guardrail.id,
+        name=guardrail.name,
+        description=guardrail.description,
+        enabled_for_evals=guardrail.enabled_for_evals,
+        selector=sanitized_selector,
+        guardrail_type="custom",
+        rules=converted_rules,
+    )
 
 
 def build_guardrails_with_actions(
@@ -38,10 +234,32 @@ def build_guardrails_with_actions(
         if isinstance(guardrail, AgentUnknownGuardrail):
             continue
 
+        converted_guardrail: BaseGuardrail
+        if isinstance(guardrail, AgentCustomGuardrail):
+            converted_guardrail = _convert_agent_custom_guardrail_to_deterministic(
+                guardrail
+            )
+            # Validate that DeterministicGuardrails only have TOOL scope
+            non_tool_scopes = [
+                scope
+                for scope in converted_guardrail.selector.scopes
+                if scope != GuardrailScope.TOOL
+            ]
+
+            if non_tool_scopes:
+                raise ValueError(
+                    f"Deterministic guardrail '{converted_guardrail.name}' can only be used with TOOL scope. "
+                    f"Found invalid scopes: {[scope.name for scope in non_tool_scopes]}. "
+                    f"Please configure this guardrail to use only TOOL scope."
+                )
+        else:
+            converted_guardrail = guardrail
+            _sanitize_selector_tool_names(converted_guardrail.selector)
+
         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,20 +269,23 @@ 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,
-                    EscalateAction(
-                        app_name=action.app.name,
-                        app_folder_path=action.app.folder_name,
-                        version=action.app.version,
-                        assignee=action.recipient.value,
-                    ),
+            if isinstance(action.recipient, StandardRecipient):
+                result.append(
+                    (
+                        converted_guardrail,
+                        EscalateAction(
+                            app_name=action.app.name,
+                            app_folder_path=action.app.folder_name,
+                            version=action.app.version,
+                            assignee=action.recipient.value,
+                        ),
+                    )
                 )
-            )
+        elif isinstance(action, AgentGuardrailFilterAction):
+            result.append((converted_guardrail, FilterAction(fields=action.fields)))
     return result

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,177 @@
+import json
+import logging
+from typing import Any
+
+from langchain_core.messages import (
+    AIMessage,
+    AnyMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
+
+from uipath_langchain.agent.react.types import AgentGuardrailsGraphState
+from uipath_langchain.agent.tools.utils import sanitize_tool_name
+
+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'", tool_name
+                        )
+                        return {}
+
+    return {}
+
+
+def _extract_tools_args_from_message(message: AnyMessage) -> list[dict[str, Any]]:
+    if not isinstance(message, AIMessage):
+        return []
+
+    if not message.tool_calls:
+        return []
+
+    result: list[dict[str, Any]] = []
+
+    for tool_call in message.tool_calls:
+        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):
+                result.append(args)
+            # If it's a JSON string, parse it
+            elif isinstance(args, str):
+                try:
+                    parsed = json.loads(args)
+                    if isinstance(parsed, dict):
+                        result.append(parsed)
+                except json.JSONDecodeError:
+                    logger.warning("Failed to parse tool args as JSON")
+
+    return result
+
+
+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:
+            # Try to parse as Python literal (dict/list representation)
+            try:
+                import ast
+
+                parsed = ast.literal_eval(content)
+                if isinstance(parsed, dict):
+                    return parsed
+                else:
+                    return {"output": parsed}
+            except (ValueError, SyntaxError):
+                logger.warning("Tool output is not valid JSON or Python literal")
+                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 ""
+
+
+def _sanitize_selector_tool_names(selector):
+    """Sanitize tool names in the selector's match_names for Tool scope guardrails.
+
+    This ensures that the tool names in the selector match the sanitized tool names
+    used in the actual tool nodes.
+
+    Args:
+        selector: The guardrail selector object.
+
+    Returns:
+        The selector with sanitized match_names (if applicable).
+    """
+    from uipath.platform.guardrails import GuardrailScope
+
+    # Only sanitize for Tool scope guardrails
+    if GuardrailScope.TOOL in selector.scopes and selector.match_names is not None:
+        # Sanitize each tool name in match_names
+        sanitized_names = [sanitize_tool_name(name) for name in selector.match_names]
+        # Update the selector with sanitized names
+        selector.match_names = sanitized_names
+
+    return selector

uipath_langchain/agent/react/agent.py

@@ -9,10 +9,13 @@ from langgraph.graph import StateGraph
 from pydantic import BaseModel
 from uipath.platform.guardrails import BaseGuardrail
 
-from ..guardrails import create_llm_guardrails_subgraph
 from ..guardrails.actions import GuardrailAction
-from ..guardrails.guardrails_subgraph import create_tools_guardrails_subgraph
-from ..tools import create_tool_node
+from .guardrails.guardrails_subgraph import (
+    create_agent_init_guardrails_subgraph,
+    create_agent_terminate_guardrails_subgraph,
+    create_llm_guardrails_subgraph,
+    create_tools_guardrails_subgraph,
+)
 from .init_node import (
     create_init_node,
 )
@@ -20,7 +23,7 @@ from .llm_node import (
     create_llm_node,
 )
 from .router import (
-    route_agent,
+    create_route_agent,
 )
 from .terminate_node import (
     create_terminate_node,
@@ -54,7 +57,7 @@ def create_agent(
     config: AgentGraphConfig | None = None,
     guardrails: Sequence[tuple[BaseGuardrail, GuardrailAction]] | None = None,
 ) -> StateGraph[AgentGraphState, None, InputT, OutputT]:
-    """Build agent graph with INIT -> AGENT(subgraph) <-> TOOLS loop, terminated by control flow tools.
+    """Build agent graph with INIT -> AGENT (subgraph) <-> TOOLS loop, terminated by control flow tools.
 
     The AGENT node is a subgraph that runs:
     - before-agent guardrail middlewares
@@ -63,6 +66,8 @@ def create_agent(
 
     Control flow tools (end_execution, raise_error) are auto-injected alongside regular tools.
     """
+    from ..tools import create_tool_node
+
     if config is None:
         config = AgentGraphConfig()
 
@@ -72,7 +77,8 @@ def create_agent(
     flow_control_tools: list[BaseTool] = create_flow_control_tools(output_schema)
     llm_tools: list[BaseTool] = [*agent_tools, *flow_control_tools]
 
-    init_node = create_init_node(messages)
+    init_node = create_init_node(messages, input_schema)
+
     tool_nodes = create_tool_node(agent_tools)
     tool_nodes_with_guardrails = create_tools_guardrails_subgraph(
         tool_nodes, guardrails
@@ -86,16 +92,24 @@ def create_agent(
     builder: StateGraph[AgentGraphState, None, InputT, OutputT] = StateGraph(
         InnerAgentGraphState, input_schema=input_schema, output_schema=output_schema
     )
-    builder.add_node(AgentGraphNode.INIT, init_node)
+    init_with_guardrails_subgraph = create_agent_init_guardrails_subgraph(
+        (AgentGraphNode.GUARDED_INIT, init_node),
+        guardrails,
+    )
+    builder.add_node(AgentGraphNode.INIT, init_with_guardrails_subgraph)
 
     for tool_name, tool_node in tool_nodes_with_guardrails.items():
         builder.add_node(tool_name, tool_node)
 
-    builder.add_node(AgentGraphNode.TERMINATE, terminate_node)
+    terminate_with_guardrails_subgraph = create_agent_terminate_guardrails_subgraph(
+        (AgentGraphNode.GUARDED_TERMINATE, terminate_node),
+        guardrails,
+    )
+    builder.add_node(AgentGraphNode.TERMINATE, terminate_with_guardrails_subgraph)
 
     builder.add_edge(START, AgentGraphNode.INIT)
 
-    llm_node = create_llm_node(model, llm_tools)
+    llm_node = create_llm_node(model, llm_tools, config.thinking_messages_limit)
     llm_with_guardrails_subgraph = create_llm_guardrails_subgraph(
         (AgentGraphNode.LLM, llm_node), guardrails
     )
@@ -103,6 +117,7 @@ def create_agent(
     builder.add_edge(AgentGraphNode.INIT, AgentGraphNode.AGENT)
 
     tool_node_names = list(tool_nodes_with_guardrails.keys())
+    route_agent = create_route_agent(config.thinking_messages_limit)
     builder.add_conditional_edges(
         AgentGraphNode.AGENT,
         route_agent,

uipath_langchain/agent/react/constants.py

@@ -1,2 +1 @@
-# Agent routing configuration
-MAX_SUCCESSIVE_COMPLETIONS = 1
+MAX_CONSECUTIVE_THINKING_MESSAGES = 0

uipath_langchain/agent/react/file_type_handler.py

@@ -0,0 +1,123 @@
+import base64
+from enum import StrEnum
+from typing import Any
+
+import httpx
+from uipath._utils._ssl_context import get_httpx_client_kwargs
+
+IMAGE_MIME_TYPES: set[str] = {
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+}
+
+
+class LlmProvider(StrEnum):
+    OPENAI = "openai"
+    BEDROCK = "bedrock"
+    VERTEX = "vertex"
+    UNKNOWN = "unknown"
+
+
+def is_pdf(mime_type: str) -> bool:
+    """Check if the MIME type represents a PDF document."""
+    return mime_type.lower() == "application/pdf"
+
+
+def is_image(mime_type: str) -> bool:
+    """Check if the MIME type represents a supported image format (PNG, JPEG, GIF, WebP)."""
+    return mime_type.lower() in IMAGE_MIME_TYPES
+
+
+def detect_provider(model_name: str) -> LlmProvider:
+    """Detect the LLM provider (Bedrock, OpenAI, or Vertex) based on the model name."""
+    if not model_name:
+        raise ValueError(f"Unsupported model: {model_name}")
+
+    model_lower = model_name.lower()
+
+    if "anthropic" in model_lower or "claude" in model_lower:
+        return LlmProvider.BEDROCK
+
+    if "gpt" in model_lower:
+        return LlmProvider.OPENAI
+
+    if "gemini" in model_lower:
+        return LlmProvider.VERTEX
+
+    raise ValueError(f"Unsupported model: {model_name}")
+
+
+async def _download_file(url: str) -> str:
+    """Download a file from a URL and return its content as a base64 string."""
+    async with httpx.AsyncClient(**get_httpx_client_kwargs()) as client:
+        response = await client.get(url)
+        response.raise_for_status()
+        file_content = response.content
+
+    return base64.b64encode(file_content).decode("utf-8")
+
+
+async def build_message_content_part_from_data(
+    url: str,
+    filename: str,
+    mime_type: str,
+    model: str,
+) -> dict[str, Any]:
+    """Download a file and build a provider-specific message content part.
+
+    The format varies based on the detected provider (Bedrock, OpenAI, or Vertex).
+    """
+    provider = detect_provider(model)
+
+    if provider == LlmProvider.BEDROCK:
+        raise ValueError("Anthropic models are not yet supported for file attachments")
+
+    if provider == LlmProvider.OPENAI:
+        return await _build_openai_content_part_from_data(
+            url, mime_type, filename, False
+        )
+
+    if provider == LlmProvider.VERTEX:
+        raise ValueError("Gemini models are not yet supported for file attachments")
+
+    raise ValueError(f"Unsupported provider: {provider}")
+
+
+async def _build_openai_content_part_from_data(
+    url: str,
+    mime_type: str,
+    filename: str,
+    download_image: bool,
+) -> dict[str, Any]:
+    """Build a content part for OpenAI models (base64-encoded or URL reference)."""
+    if download_image:
+        base64_content = await _download_file(url)
+        if is_image(mime_type):
+            data_url = f"data:{mime_type};base64,{base64_content}"
+            return {
+                "type": "input_image",
+                "image_url": data_url,
+            }
+
+        if is_pdf(mime_type):
+            return {
+                "type": "input_file",
+                "filename": filename,
+                "file_data": base64_content,
+            }
+
+    elif is_image(mime_type):
+        return {
+            "type": "input_image",
+            "image_url": url,
+        }
+
+    elif is_pdf(mime_type):
+        return {
+            "type": "input_file",
+            "file_url": url,
+        }
+
+    raise ValueError(f"Unsupported mime_type: {mime_type}")