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

uipath_langchain/agent/react/llm_node.py

@@ -1,34 +1,65 @@
-"""LLM node implementation for LangGraph."""
+"""LLM node for ReAct Agent graph."""
 
-from typing import Sequence
+from typing import Literal, Sequence
 
 from langchain_core.language_models import BaseChatModel
 from langchain_core.messages import AIMessage, AnyMessage
 from langchain_core.tools import BaseTool
 
-from .constants import MAX_SUCCESSIVE_COMPLETIONS
+from .constants import MAX_CONSECUTIVE_THINKING_MESSAGES
 from .types import AgentGraphState
-from .utils import count_successive_completions
+from .utils import count_consecutive_thinking_messages
+
+OPENAI_COMPATIBLE_CHAT_MODELS = (
+    "UiPathChatOpenAI",
+    "AzureChatOpenAI",
+    "ChatOpenAI",
+    "UiPathChat",
+    "UiPathAzureChatOpenAI",
+)
+
+
+def _get_required_tool_choice_by_model(
+    model: BaseChatModel,
+) -> Literal["required", "any"]:
+    """Get the appropriate tool_choice value to enforce tool usage based on model type.
+
+    "required" - OpenAI compatible required tool_choice value
+    "any" - Vertex and Bedrock parameter for required tool_choice value
+    """
+    model_class_name = model.__class__.__name__
+    if model_class_name in OPENAI_COMPATIBLE_CHAT_MODELS:
+        return "required"
+    return "any"
 
 
 def create_llm_node(
     model: BaseChatModel,
     tools: Sequence[BaseTool] | None = None,
+    thinking_messages_limit: int = MAX_CONSECUTIVE_THINKING_MESSAGES,
 ):
-    """Invoke LLM with tools and dynamically control tool_choice based on successive completions.
+    """Create LLM node with dynamic tool_choice enforcement.
 
-    When successive completions reach the limit, tool_choice is set to "required" to force
-    the LLM to use a tool and prevent infinite reasoning loops.
+    Controls when to force tool usage based on consecutive thinking steps
+    to prevent infinite loops and ensure progress.
+
+    Args:
+        model: The chat model to use
+        tools: Available tools to bind
+        thinking_messages_limit: Max consecutive LLM responses without tool calls
+            before enforcing tool usage. 0 = force tools every time.
     """
     bindable_tools = list(tools) if tools else []
     base_llm = model.bind_tools(bindable_tools) if bindable_tools else model
+    tool_choice_required_value = _get_required_tool_choice_by_model(model)
 
     async def llm_node(state: AgentGraphState):
         messages: list[AnyMessage] = state.messages
 
-        successive_completions = count_successive_completions(messages)
-        if successive_completions >= MAX_SUCCESSIVE_COMPLETIONS:
-            llm = base_llm.bind(tool_choice="required")
+        consecutive_thinking_messages = count_consecutive_thinking_messages(messages)
+
+        if bindable_tools and consecutive_thinking_messages >= thinking_messages_limit:
+            llm = base_llm.bind(tool_choice=tool_choice_required_value)
         else:
             llm = base_llm
 

uipath_langchain/agent/react/llm_with_files.py

@@ -0,0 +1,76 @@
+"""LLM invocation with file attachments support."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, AnyMessage, HumanMessage
+
+from .file_type_handler import build_message_content_part_from_data
+
+
+@dataclass
+class FileInfo:
+    """File information for LLM file attachments."""
+
+    url: str
+    name: str
+    mime_type: str
+
+
+def _get_model_name(model: BaseChatModel) -> str:
+    """Extract model name from a BaseChatModel instance."""
+    for attr in ["model_name", "_model_name", "model", "model_id"]:
+        value = getattr(model, attr, None)
+        if value and isinstance(value, str):
+            return value
+    raise ValueError(f"Model name not found in model {model}")
+
+
+async def create_part_for_file(
+    file_info: FileInfo,
+    model: BaseChatModel,
+) -> dict[str, Any]:
+    """Create a provider-specific message content part for a file attachment.
+
+    Downloads the file from file_info.url and formats it for the model's provider.
+    """
+    model_name = _get_model_name(model)
+    return await build_message_content_part_from_data(
+        url=file_info.url,
+        filename=file_info.name,
+        mime_type=file_info.mime_type,
+        model=model_name,
+    )
+
+
+async def llm_call_with_files(
+    messages: list[AnyMessage],
+    files: list[FileInfo],
+    model: BaseChatModel,
+) -> AIMessage:
+    """Invoke an LLM with file attachments.
+
+    Downloads files, creates provider-specific content parts, and appends them
+    as a HumanMessage. If no files are provided, equivalent to model.ainvoke().
+    """
+    if not files:
+        response = await model.ainvoke(messages)
+        if not isinstance(response, AIMessage):
+            raise TypeError(
+                f"LLM returned {type(response).__name__} instead of AIMessage"
+            )
+        return response
+
+    content_parts: list[str | dict[Any, Any]] = []
+    for file_info in files:
+        content_part = await create_part_for_file(file_info, model)
+        content_parts.append(content_part)
+
+    file_message = HumanMessage(content=content_parts)
+    all_messages = list(messages) + [file_message]
+
+    response = await model.ainvoke(all_messages)
+    if not isinstance(response, AIMessage):
+        raise TypeError(f"LLM returned {type(response).__name__} instead of AIMessage")
+    return response

uipath_langchain/agent/react/router.py

@@ -6,9 +6,8 @@ from langchain_core.messages import AIMessage, AnyMessage, ToolCall
 from uipath.agent.react import END_EXECUTION_TOOL, RAISE_ERROR_TOOL
 
 from ..exceptions import AgentNodeRoutingException
-from .constants import MAX_SUCCESSIVE_COMPLETIONS
 from .types import AgentGraphNode, AgentGraphState
-from .utils import count_successive_completions
+from .utils import count_consecutive_thinking_messages
 
 FLOW_CONTROL_TOOLS = [END_EXECUTION_TOOL.name, RAISE_ERROR_TOOL.name]
 
@@ -48,50 +47,62 @@ def __validate_last_message_is_AI(messages: list[AnyMessage]) -> AIMessage:
     return last_message
 
 
-def route_agent(
-    state: AgentGraphState,
-) -> list[str] | Literal[AgentGraphNode.AGENT, AgentGraphNode.TERMINATE]:
-    """Route after agent: handles all routing logic including control flow detection.
+def create_route_agent(thinking_messages_limit: int = 0):
+    """Create a routing function configured with thinking_messages_limit.
 
-    Routing logic:
-    1. If multiple tool calls exist, filter out control flow tools (EndExecution, RaiseError)
-    2. If control flow tool(s) remain, route to TERMINATE
-    3. If regular tool calls remain, route to specific tool nodes (return list of tool names)
-    4. If no tool calls, handle successive completions
+    Args:
+        thinking_messages_limit: Max consecutive thinking messages before error
 
     Returns:
-        - list[str]: Tool node names for parallel execution
-        - AgentGraphNode.AGENT: For successive completions
-        - AgentGraphNode.TERMINATE: For control flow termination
-
-    Raises:
-        AgentNodeRoutingException: When encountering unexpected state (empty messages, non-AIMessage, or excessive completions)
+        Routing function for LangGraph conditional edges
     """
-    messages = state.messages
-    last_message = __validate_last_message_is_AI(messages)
 
-    tool_calls = list(last_message.tool_calls) if last_message.tool_calls else []
-    tool_calls = __filter_control_flow_tool_calls(tool_calls)
+    def route_agent(
+        state: AgentGraphState,
+    ) -> list[str] | Literal[AgentGraphNode.AGENT, AgentGraphNode.TERMINATE]:
+        """Route after agent: handles all routing logic including control flow detection.
+
+        Routing logic:
+        1. If multiple tool calls exist, filter out control flow tools (EndExecution, RaiseError)
+        2. If control flow tool(s) remain, route to TERMINATE
+        3. If regular tool calls remain, route to specific tool nodes (return list of tool names)
+        4. If no tool calls, handle consecutive completions
+
+        Returns:
+            - list[str]: Tool node names for parallel execution
+            - AgentGraphNode.AGENT: For consecutive completions
+            - AgentGraphNode.TERMINATE: For control flow termination
+
+        Raises:
+            AgentNodeRoutingException: When encountering unexpected state (empty messages, non-AIMessage, or excessive completions)
+        """
+        messages = state.messages
+        last_message = __validate_last_message_is_AI(messages)
 
-    if tool_calls and __has_control_flow_tool(tool_calls):
-        return AgentGraphNode.TERMINATE
+        tool_calls = list(last_message.tool_calls) if last_message.tool_calls else []
+        tool_calls = __filter_control_flow_tool_calls(tool_calls)
 
-    if tool_calls:
-        return [tc["name"] for tc in tool_calls]
+        if tool_calls and __has_control_flow_tool(tool_calls):
+            return AgentGraphNode.TERMINATE
 
-    successive_completions = count_successive_completions(messages)
+        if tool_calls:
+            return [tc["name"] for tc in tool_calls]
+
+        consecutive_thinking_messages = count_consecutive_thinking_messages(messages)
+
+        if consecutive_thinking_messages > thinking_messages_limit:
+            raise AgentNodeRoutingException(
+                f"Agent exceeded consecutive completions limit without producing tool calls "
+                f"(completions: {consecutive_thinking_messages}, max: {thinking_messages_limit}). "
+                f"This should not happen as tool_choice='required' is enforced at the limit."
+            )
+
+        if last_message.content:
+            return AgentGraphNode.AGENT
 
-    if successive_completions > MAX_SUCCESSIVE_COMPLETIONS:
         raise AgentNodeRoutingException(
-            f"Agent exceeded successive completions limit without producing tool calls "
-            f"(completions: {successive_completions}, max: {MAX_SUCCESSIVE_COMPLETIONS}). "
-            f"This should not happen as tool_choice='required' is enforced at the limit."
+            f"Agent produced empty response without tool calls "
+            f"(completions: {consecutive_thinking_messages}, has_content: False)"
         )
 
-    if last_message.content:
-        return AgentGraphNode.AGENT
-
-    raise AgentNodeRoutingException(
-        f"Agent produced empty response without tool calls "
-        f"(completions: {successive_completions}, has_content: False)"
-    )
+    return route_agent

uipath_langchain/agent/react/types.py

@@ -1,9 +1,12 @@
 from enum import StrEnum
-from typing import Annotated
+from typing import Annotated, Any, Optional
 
 from langchain_core.messages import AnyMessage
 from langgraph.graph.message import add_messages
 from pydantic import BaseModel, Field
+from uipath.platform.attachments import Attachment
+
+from uipath_langchain.agent.react.utils import add_job_attachments
 
 
 class AgentTerminationSource(StrEnum):
@@ -22,18 +25,33 @@ class AgentGraphState(BaseModel):
     """Agent Graph state for standard loop execution."""
 
     messages: Annotated[list[AnyMessage], add_messages] = []
+    job_attachments: Annotated[dict[str, Attachment], add_job_attachments] = {}
     termination: AgentTermination | None = None
 
 
+class AgentGuardrailsGraphState(AgentGraphState):
+    """Agent Guardrails Graph state for guardrail subgraph."""
+
+    guardrail_validation_result: Optional[str] = None
+    agent_result: Optional[dict[str, Any]] = None
+
+
 class AgentGraphNode(StrEnum):
     INIT = "init"
+    GUARDED_INIT = "guarded-init"
     AGENT = "agent"
     LLM = "llm"
     TOOLS = "tools"
     TERMINATE = "terminate"
+    GUARDED_TERMINATE = "guarded-terminate"
 
 
 class AgentGraphConfig(BaseModel):
     recursion_limit: int = Field(
         default=50, ge=1, description="Maximum recursion limit for the agent graph"
     )
+    thinking_messages_limit: int = Field(
+        default=0,
+        ge=0,
+        description="Max consecutive thinking messages before enforcing tool usage. 0 = force tools every time.",
+    )

uipath_langchain/agent/react/utils.py

@@ -5,7 +5,9 @@ from typing import Any, Sequence
 from langchain_core.messages import AIMessage, BaseMessage
 from pydantic import BaseModel
 from uipath.agent.react import END_EXECUTION_TOOL
-from uipath.utils.dynamic_schema import jsonschema_to_pydantic
+from uipath.platform.attachments import Attachment
+
+from uipath_langchain.agent.react.jsonschema_pydantic_converter import create_model
 
 
 def resolve_input_model(
@@ -13,7 +15,7 @@ def resolve_input_model(
 ) -> type[BaseModel]:
     """Resolve the input model from the input schema."""
     if input_schema:
-        return jsonschema_to_pydantic(input_schema)
+        return create_model(input_schema)
 
     return BaseModel
 
@@ -23,12 +25,12 @@ def resolve_output_model(
 ) -> type[BaseModel]:
     """Fallback to default end_execution tool schema when no agent output schema is provided."""
     if output_schema:
-        return jsonschema_to_pydantic(output_schema)
+        return create_model(output_schema)
 
     return END_EXECUTION_TOOL.args_schema
 
 
-def count_successive_completions(messages: Sequence[BaseMessage]) -> int:
+def count_consecutive_thinking_messages(messages: Sequence[BaseMessage]) -> int:
     """Count consecutive AIMessages without tool calls at end of message history."""
     if not messages:
         return 0
@@ -47,3 +49,27 @@ def count_successive_completions(messages: Sequence[BaseMessage]) -> int:
         count += 1
 
     return count
+
+
+def add_job_attachments(
+    left: dict[str, Attachment], right: dict[str, Attachment]
+) -> dict[str, Attachment]:
+    """Merge attachment dictionaries, with right values taking precedence.
+
+    This reducer function merges two dictionaries of attachments by UUID string.
+    If the same UUID exists in both dictionaries, the value from 'right' takes precedence.
+
+    Args:
+        left: Existing dictionary of attachments keyed by UUID string
+        right: New dictionary of attachments to merge
+
+    Returns:
+        Merged dictionary with right values overriding left values for duplicate keys
+    """
+    if not right:
+        return left
+
+    if not left:
+        return right
+
+    return {**left, **right}

uipath_langchain/agent/tools/__init__.py

@@ -1,12 +1,14 @@
 """Tool creation and management for LowCode agents."""
 
 from .context_tool import create_context_tool
+from .escalation_tool import create_escalation_tool
 from .integration_tool import create_integration_tool
+from .mcp_tool import create_mcp_tools
 from .process_tool import create_process_tool
 from .tool_factory import (
     create_tools_from_resources,
 )
-from .tool_node import create_tool_node
+from .tool_node import ToolWrapperMixin, UiPathToolNode, create_tool_node
 
 __all__ = [
     "create_tools_from_resources",
@@ -14,4 +16,8 @@ __all__ = [
     "create_context_tool",
     "create_process_tool",
     "create_integration_tool",
+    "create_escalation_tool",
+    "create_mcp_tools",
+    "UiPathToolNode",
+    "ToolWrapperMixin",
 ]

uipath_langchain/agent/tools/context_tool.py

@@ -1,12 +1,24 @@
 """Context tool creation for semantic index retrieval."""
 
+import uuid
 from typing import Any
 
 from langchain_core.documents import Document
 from langchain_core.tools import StructuredTool
+from langgraph.types import interrupt
 from pydantic import BaseModel, Field
-from uipath.agent.models.agent import AgentContextResourceConfig
+from uipath.agent.models.agent import (
+    AgentContextResourceConfig,
+    AgentContextRetrievalMode,
+)
 from uipath.eval.mocks import mockable
+from uipath.platform.common import CreateBatchTransform, CreateDeepRag
+from uipath.platform.context_grounding import (
+    BatchTransformOutputColumn,
+    BatchTransformResponse,
+    CitationMode,
+    DeepRagResponse,
+)
 
 from uipath_langchain.retrievers import ContextGroundingRetriever
 
@@ -16,6 +28,18 @@ from .utils import sanitize_tool_name
 
 def create_context_tool(resource: AgentContextResourceConfig) -> StructuredTool:
     tool_name = sanitize_tool_name(resource.name)
+    retrieval_mode = resource.settings.retrieval_mode.lower()
+    if retrieval_mode == AgentContextRetrievalMode.DEEP_RAG.value.lower():
+        return handle_deep_rag(tool_name, resource)
+    elif retrieval_mode == AgentContextRetrievalMode.BATCH_TRANSFORM.value.lower():
+        return handle_batch_transform(tool_name, resource)
+    else:
+        return handle_semantic_search(tool_name, resource)
+
+
+def handle_semantic_search(
+    tool_name: str, resource: AgentContextResourceConfig
+) -> StructuredTool:
     retriever = ContextGroundingRetriever(
         index_name=resource.index_name,
         folder_path=resource.folder_path,
@@ -40,6 +64,7 @@ def create_context_tool(resource: AgentContextResourceConfig) -> StructuredTool:
         description=resource.description,
         input_schema=input_model.model_json_schema(),
         output_schema=output_model.model_json_schema(),
+        example_calls=[],  # Examples cannot be provided for context.
     )
     async def context_tool_fn(query: str) -> dict[str, Any]:
         return {"documents": await retriever.ainvoke(query)}
@@ -51,3 +76,128 @@ def create_context_tool(resource: AgentContextResourceConfig) -> StructuredTool:
         coroutine=context_tool_fn,
         output_type=output_model,
     )
+
+
+def handle_deep_rag(
+    tool_name: str, resource: AgentContextResourceConfig
+) -> StructuredTool:
+    ensure_valid_fields(resource)
+    # needed for type checking
+    assert resource.settings.query is not None
+    assert resource.settings.query.value is not None
+
+    index_name = resource.index_name
+    prompt = resource.settings.query.value
+    if not resource.settings.citation_mode:
+        raise ValueError("Citation mode is required for Deep RAG")
+    citation_mode = CitationMode(resource.settings.citation_mode.value)
+
+    input_model = None
+    output_model = DeepRagResponse
+
+    @mockable(
+        name=resource.name,
+        description=resource.description,
+        input_schema=input_model,
+        output_schema=output_model.model_json_schema(),
+        example_calls=[],  # Examples cannot be provided for context.
+    )
+    async def context_tool_fn() -> dict[str, Any]:
+        # TODO: add glob pattern support
+        return interrupt(
+            CreateDeepRag(
+                name=f"task-{uuid.uuid4()}",
+                index_name=index_name,
+                prompt=prompt,
+                citation_mode=citation_mode,
+            )
+        )
+
+    return StructuredToolWithOutputType(
+        name=tool_name,
+        description=resource.description,
+        args_schema=input_model,
+        coroutine=context_tool_fn,
+        output_type=output_model,
+    )
+
+
+def handle_batch_transform(
+    tool_name: str, resource: AgentContextResourceConfig
+) -> StructuredTool:
+    ensure_valid_fields(resource)
+
+    # needed for type checking
+    assert resource.settings.query is not None
+    assert resource.settings.query.value is not None
+
+    index_name = resource.index_name
+    prompt = resource.settings.query.value
+
+    index_folder_path = resource.folder_path
+    if not resource.settings.web_search_grounding:
+        raise ValueError("Web search grounding field is required for Batch Transform")
+    enable_web_search_grounding = (
+        resource.settings.web_search_grounding.value.lower() == "enabled"
+    )
+
+    batch_transform_output_columns: list[BatchTransformOutputColumn] = []
+    if (output_columns := resource.settings.output_columns) is None or not len(
+        output_columns
+    ):
+        raise ValueError(
+            "Batch transform requires at least one output column to be specified in settings.output_columns"
+        )
+
+    for column in output_columns:
+        batch_transform_output_columns.append(
+            BatchTransformOutputColumn(
+                name=column.name,
+                description=column.description,
+            )
+        )
+
+    class BatchTransformSchemaModel(BaseModel):
+        destination_path: str = Field(
+            ...,
+            description="The relative file path destination for the modified csv file",
+        )
+
+    input_model = BatchTransformSchemaModel
+    output_model = BatchTransformResponse
+
+    @mockable(
+        name=resource.name,
+        description=resource.description,
+        input_schema=input_model.model_json_schema(),
+        output_schema=output_model.model_json_schema(),
+        example_calls=[],  # Examples cannot be provided for context.
+    )
+    async def context_tool_fn(destination_path: str) -> dict[str, Any]:
+        # TODO: storage_bucket_folder_path_prefix  support
+        return interrupt(
+            CreateBatchTransform(
+                name=f"task-{uuid.uuid4()}",
+                index_name=index_name,
+                prompt=prompt,
+                destination_path=destination_path,
+                index_folder_path=index_folder_path,
+                enable_web_search_grounding=enable_web_search_grounding,
+                output_columns=batch_transform_output_columns,
+            )
+        )
+
+    return StructuredToolWithOutputType(
+        name=tool_name,
+        description=resource.description,
+        args_schema=input_model,
+        coroutine=context_tool_fn,
+        output_type=output_model,
+    )
+
+
+def ensure_valid_fields(resource_config: AgentContextResourceConfig):
+    if not resource_config.settings.query:
+        raise ValueError("Query object is required")
+    if not resource_config.settings.query.value:
+        raise ValueError("Query prompt is required")