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

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/types.py

@@ -4,6 +4,9 @@ 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,6 +25,7 @@ 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
 
 

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,7 +25,7 @@ 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
 
@@ -47,3 +49,27 @@ def count_consecutive_thinking_messages(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,13 +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",
@@ -15,5 +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")

uipath_langchain/agent/tools/escalation_tool.py

@@ -3,10 +3,9 @@
 from enum import Enum
 from typing import Any
 
-from jsonschema_pydantic_converter import transform as create_model
-from langchain.tools import ToolRuntime
 from langchain_core.messages import ToolMessage
-from langchain_core.tools import StructuredTool
+from langchain_core.messages.tool import ToolCall
+from langchain_core.tools import BaseTool, StructuredTool
 from langgraph.types import Command, interrupt
 from uipath.agent.models.agent import (
     AgentEscalationChannel,
@@ -16,7 +15,10 @@ from uipath.agent.models.agent import (
 from uipath.eval.mocks import mockable
 from uipath.platform.common import CreateEscalation
 
-from ..react.types import AgentGraphNode, AgentTerminationSource
+from uipath_langchain.agent.react.jsonschema_pydantic_converter import create_model
+
+from ..react.types import AgentGraphNode, AgentGraphState, AgentTerminationSource
+from .tool_node import ToolWrapperMixin
 from .utils import sanitize_tool_name
 
 
@@ -27,7 +29,11 @@ class EscalationAction(str, Enum):
     END = "end"
 
 
-def create_escalation_tool(resource: AgentEscalationResourceConfig) -> StructuredTool:
+class StructuredToolWithWrapper(StructuredTool, ToolWrapperMixin):
+    pass
+
+
+def create_escalation_tool(resource: AgentEscalationResourceConfig) -> BaseTool:
     """Uses interrupt() for Action Center human-in-the-loop."""
 
     tool_name: str = f"escalate_{sanitize_tool_name(resource.name)}"
@@ -48,10 +54,9 @@ def create_escalation_tool(resource: AgentEscalationResourceConfig) -> Structure
         description=resource.description,
         input_schema=input_model.model_json_schema(),
         output_schema=output_model.model_json_schema(),
+        example_calls=channel.properties.example_calls,
     )
-    async def escalation_tool_fn(
-        runtime: ToolRuntime, **kwargs: Any
-    ) -> Command[Any] | Any:
+    async def escalation_tool_fn(**kwargs: Any) -> dict[str, Any]:
         task_title = channel.task_title or "Escalation Task"
 
         result = interrupt(
@@ -72,22 +77,41 @@ def create_escalation_tool(resource: AgentEscalationResourceConfig) -> Structure
         escalation_action = getattr(result, "action", None)
         escalation_output = getattr(result, "data", {})
 
-        outcome = (
+        outcome_str = (
             channel.outcome_mapping.get(escalation_action)
             if channel.outcome_mapping and escalation_action
             else None
         )
+        outcome = (
+            EscalationAction(outcome_str) if outcome_str else EscalationAction.CONTINUE
+        )
 
-        if outcome == EscalationAction.END:
-            output_detail = f"Escalation output: {escalation_output}"
-            termination_title = f"Agent run ended based on escalation outcome {outcome} with directive {escalation_action}"
+        return {
+            "action": outcome,
+            "output": escalation_output,
+            "escalation_action": escalation_action,
+        }
+
+    async def escalation_wrapper(
+        tool: BaseTool,
+        call: ToolCall,
+        state: AgentGraphState,
+    ) -> dict[str, Any] | Command[Any]:
+        result = await tool.ainvoke(call["args"])
+
+        if result["action"] == EscalationAction.END:
+            output_detail = f"Escalation output: {result['output']}"
+            termination_title = (
+                f"Agent run ended based on escalation outcome {result['action']} "
+                f"with directive {result['escalation_action']}"
+            )
 
             return Command(
                 update={
                     "messages": [
                         ToolMessage(
                             content=f"{termination_title}. {output_detail}",
-                            tool_call_id=runtime.tool_call_id,
+                            tool_call_id=call["id"],
                         )
                     ],
                     "termination": {
@@ -99,13 +123,20 @@ def create_escalation_tool(resource: AgentEscalationResourceConfig) -> Structure
                 goto=AgentGraphNode.TERMINATE,
             )
 
-        return escalation_output
+        return result["output"]
 
-    tool = StructuredTool(
+    tool = StructuredToolWithWrapper(
         name=tool_name,
         description=resource.description,
         args_schema=input_model,
         coroutine=escalation_tool_fn,
+        metadata={
+            "tool_type": "escalation",
+            "display_name": channel.properties.app_name,
+            "channel_type": channel.type,
+            "assignee": assignee,
+        },
     )
+    tool.set_tool_wrappers(awrapper=escalation_wrapper)
 
     return tool

uipath_langchain/agent/tools/integration_tool.py

@@ -3,17 +3,21 @@
 import copy
 from typing import Any
 
-from jsonschema_pydantic_converter import transform as create_model
-from langchain.tools import ToolRuntime
 from langchain_core.tools import StructuredTool
 from uipath.agent.models.agent import AgentIntegrationToolResourceConfig
 from uipath.eval.mocks import mockable
 from uipath.platform import UiPath
 from uipath.platform.connections import ActivityMetadata, ActivityParameterLocationInfo
 
-from .static_args import handle_static_args
+from uipath_langchain.agent.react.jsonschema_pydantic_converter import create_model
+from uipath_langchain.agent.tools.tool_node import ToolWrapperMixin
+
 from .structured_tool_with_output_type import StructuredToolWithOutputType
-from .utils import sanitize_tool_name
+from .utils import sanitize_dict_for_serialization, sanitize_tool_name
+
+
+class StructuredToolWithStaticArgs(StructuredToolWithOutputType, ToolWrapperMixin):
+    pass
 
 
 def remove_asterisk_from_properties(fields: dict[str, Any]) -> dict[str, Any]:
@@ -149,33 +153,33 @@ def create_integration_tool(
         description=resource.description,
         input_schema=input_model.model_json_schema(),
         output_schema=output_model.model_json_schema(),
+        example_calls=resource.properties.example_calls,
     )
-    async def integration_tool_fn(runtime: ToolRuntime, **kwargs: Any):
+    async def integration_tool_fn(**kwargs: Any):
         try:
-            # we manually validating here and not passing input_model to StructuredTool
-            # because langchain itself will block their own injected arguments (like runtime) if the model is strict
-            val_args = input_model.model_validate(kwargs)
-            args = handle_static_args(
-                resource=resource,
-                runtime=runtime,
-                input_args=val_args.model_dump(),
-            )
             result = await sdk.connections.invoke_activity_async(
                 activity_metadata=activity_metadata,
                 connection_id=connection_id,
-                activity_input=args,
+                activity_input=sanitize_dict_for_serialization(kwargs),
             )
         except Exception:
             raise
 
         return result
 
-    tool = StructuredToolWithOutputType(
+    from uipath_langchain.agent.wrappers.static_args_wrapper import (
+        get_static_args_wrapper,
+    )
+
+    wrapper = get_static_args_wrapper(resource)
+
+    tool = StructuredToolWithStaticArgs(
         name=tool_name,
         description=resource.description,
-        args_schema=resource.input_schema,
+        args_schema=input_model,
         coroutine=integration_tool_fn,
         output_type=output_model,
     )
+    tool.set_tool_wrappers(awrapper=wrapper)
 
     return tool

uipath_langchain/agent/tools/internal_tools/__init__.py

@@ -0,0 +1,5 @@
+"""Internal Tool creation and management for LowCode agents."""
+
+from .internal_tool_factory import create_internal_tool
+
+__all__ = ["create_internal_tool"]

uipath_langchain/agent/tools/internal_tools/analyze_files_tool.py

@@ -0,0 +1,113 @@
+import uuid
+from typing import Any
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AnyMessage, HumanMessage, SystemMessage
+from langchain_core.tools import StructuredTool
+from uipath.agent.models.agent import (
+    AgentInternalToolResourceConfig,
+)
+from uipath.eval.mocks import mockable
+from uipath.platform import UiPath
+
+from uipath_langchain.agent.react.jsonschema_pydantic_converter import create_model
+from uipath_langchain.agent.react.llm_with_files import FileInfo, llm_call_with_files
+from uipath_langchain.agent.tools.structured_tool_with_output_type import (
+    StructuredToolWithOutputType,
+)
+from uipath_langchain.agent.tools.tool_node import ToolWrapperMixin
+from uipath_langchain.agent.tools.utils import sanitize_tool_name
+
+ANALYZE_FILES_SYSTEM_MESSAGE = (
+    "Process the provided files to complete the given task. "
+    "Analyze the files contents thoroughly to deliver an accurate response "
+    "based on the extracted information."
+)
+
+
+class AnalyzeFileTool(StructuredToolWithOutputType, ToolWrapperMixin):
+    pass
+
+
+def create_analyze_file_tool(
+    resource: AgentInternalToolResourceConfig, llm: BaseChatModel
+) -> StructuredTool:
+    from uipath_langchain.agent.wrappers.job_attachment_wrapper import (
+        get_job_attachment_wrapper,
+    )
+
+    tool_name = sanitize_tool_name(resource.name)
+    input_model = create_model(resource.input_schema)
+    output_model = create_model(resource.output_schema)
+
+    @mockable(
+        name=resource.name,
+        description=resource.description,
+        input_schema=input_model.model_json_schema(),
+        output_schema=output_model.model_json_schema(),
+    )
+    async def tool_fn(**kwargs: Any):
+        if "analysisTask" not in kwargs:
+            raise ValueError("Argument 'analysisTask' is not available")
+        if "attachments" not in kwargs:
+            raise ValueError("Argument 'attachments' is not available")
+
+        attachments = kwargs["attachments"]
+        analysisTask = kwargs["analysisTask"]
+
+        files = await _resolve_job_attachment_arguments(attachments)
+        messages: list[AnyMessage] = [
+            SystemMessage(content=ANALYZE_FILES_SYSTEM_MESSAGE),
+            HumanMessage(content=analysisTask),
+        ]
+        result = await llm_call_with_files(messages, files, llm)
+        return result
+
+    wrapper = get_job_attachment_wrapper()
+    tool = AnalyzeFileTool(
+        name=tool_name,
+        description=resource.description,
+        args_schema=input_model,
+        coroutine=tool_fn,
+        output_type=output_model,
+    )
+    tool.set_tool_wrappers(awrapper=wrapper)
+    return tool
+
+
+async def _resolve_job_attachment_arguments(
+    attachments: list[Any],
+) -> list[FileInfo]:
+    """Resolve job attachments to FileInfo objects.
+
+    Args:
+        attachments: List of job attachment objects (dynamically typed from schema)
+
+    Returns:
+        List of FileInfo objects with blob URIs for each attachment
+    """
+    client = UiPath()
+    file_infos: list[FileInfo] = []
+
+    for attachment in attachments:
+        # Access using Pydantic field aliases (ID, FullName, MimeType)
+        # These are dynamically created from the JSON schema
+        attachment_id_value = getattr(attachment, "ID", None)
+        if attachment_id_value is None:
+            continue
+
+        attachment_id = uuid.UUID(attachment_id_value)
+        mime_type = getattr(attachment, "MimeType", "")
+
+        blob_info = await client.attachments.get_blob_file_access_uri_async(
+            key=attachment_id
+        )
+
+        file_info = FileInfo(
+            url=blob_info.uri,
+            name=blob_info.name,
+            mime_type=mime_type,
+        )
+        file_infos.append(file_info)
+
+    return file_infos