uipath 2.1.36__py3-none-any.whl → 2.1.38__py3-none-any.whl

uipath/_cli/_dev/_terminal/_utils/_chat.py

@@ -0,0 +1,240 @@
+import uuid
+from datetime import datetime
+from typing import Callable, Dict, Optional
+
+from uipath.agent.conversation import (
+    UiPathConversationContentPart,
+    UiPathConversationContentPartChunkEvent,
+    UiPathConversationContentPartEndEvent,
+    UiPathConversationContentPartEvent,
+    UiPathConversationContentPartStartEvent,
+    UiPathConversationEvent,
+    UiPathConversationExchangeEvent,
+    UiPathConversationMessage,
+    UiPathConversationMessageEndEvent,
+    UiPathConversationMessageEvent,
+    UiPathConversationMessageStartEvent,
+    UiPathConversationToolCall,
+    UiPathConversationToolCallResult,
+    UiPathInlineValue,
+)
+
+from ...._runtime._contracts import UiPathConversationHandler
+
+
+class RunContextChatHandler(UiPathConversationHandler):
+    """Custom chat handler that sends chat messages to CLI UI."""
+
+    def __init__(
+        self,
+        run_id: str,
+        callback: Callable[[UiPathConversationEvent, str], None],
+    ):
+        super().__init__()
+        self.run_id = run_id
+        self.callback = callback
+
+    def on_event(self, event: UiPathConversationEvent) -> None:
+        """Handle a chat message for a given execution run."""
+        self.callback(event, self.run_id)
+
+
+class ConversationAggregator:
+    """Incrementally builds messages from UiPathConversationEvents."""
+
+    messages: Dict[str, UiPathConversationMessage]
+
+    def __init__(self) -> None:
+        self.messages = {}
+
+    def add_event(
+        self, event: UiPathConversationEvent
+    ) -> Optional[UiPathConversationMessage]:
+        """Process an incoming conversation-level event and return the current message snapshot if applicable."""
+        if not event.exchange or not event.exchange.message:
+            return None
+
+        msg_event = event.exchange.message
+        return self._process_message_event(msg_event)
+
+    def _process_message_event(
+        self, ev: UiPathConversationMessageEvent
+    ) -> UiPathConversationMessage:
+        msg = self.messages.get(ev.message_id)
+
+        if not msg:
+            # Initialize message on first sighting
+            msg = UiPathConversationMessage(
+                message_id=ev.message_id,
+                role=self._infer_role(ev),
+                content_parts=[],
+                tool_calls=[],
+                created_at=self._timestamp(ev),
+                updated_at=self._timestamp(ev),
+            )
+            self.messages[ev.message_id] = msg
+
+        # --- Handle content parts (text, JSON, etc.) ---
+        if ev.content_part:
+            cp_event = ev.content_part
+
+            existing = next(
+                (
+                    cp
+                    for cp in (msg.content_parts or [])
+                    if cp.content_part_id == cp_event.content_part_id
+                ),
+                None,
+            )
+
+            # Start of a new content part
+            if cp_event.start and not existing:
+                new_cp = UiPathConversationContentPart(
+                    content_part_id=cp_event.content_part_id,
+                    mime_type=cp_event.start.mime_type,
+                    data=UiPathInlineValue(inline=""),
+                    citations=[],
+                    is_transcript=None,
+                    is_incomplete=True,
+                )
+                if msg.content_parts is None:
+                    msg.content_parts = []
+                msg.content_parts.append(new_cp)
+                existing = new_cp
+
+            # Chunk for an existing part (or backfill if start missing)
+            if cp_event.chunk:
+                if not existing:
+                    new_cp = UiPathConversationContentPart(
+                        content_part_id=cp_event.content_part_id,
+                        mime_type="text/plain",  # fallback if start missing
+                        data=UiPathInlineValue(inline=""),
+                        citations=[],
+                        is_transcript=None,
+                        is_incomplete=True,
+                    )
+                    if msg.content_parts is None:
+                        msg.content_parts = []
+                    msg.content_parts.append(new_cp)
+                    existing = new_cp
+
+                if isinstance(existing.data, UiPathInlineValue):
+                    existing.data.inline += cp_event.chunk.data or ""
+
+            # End of a part
+            if cp_event.end and existing:
+                existing.is_incomplete = bool(cp_event.end.interrupted)
+
+        # --- Handle tool calls ---
+        if ev.tool_call:
+            tc_event = ev.tool_call
+            existing_tool_call = next(
+                (
+                    tc
+                    for tc in (msg.tool_calls or [])
+                    if tc.tool_call_id == tc_event.tool_call_id
+                ),
+                None,
+            )
+
+            # Start of a tool call
+            if tc_event.start:
+                if not existing_tool_call:
+                    new_tc = UiPathConversationToolCall(
+                        tool_call_id=tc_event.tool_call_id,
+                        name=tc_event.start.tool_name,
+                        arguments=None,  # args will arrive as JSON content part
+                        timestamp=tc_event.start.timestamp,
+                        result=None,
+                    )
+                    if msg.tool_calls is None:
+                        msg.tool_calls = []
+                    msg.tool_calls.append(new_tc)
+                    existing_tool_call = new_tc
+                else:
+                    existing_tool_call.name = (
+                        tc_event.start.tool_name or existing_tool_call.name
+                    )
+                    existing_tool_call.timestamp = (
+                        tc_event.start.timestamp or existing_tool_call.timestamp
+                    )
+
+            # End of a tool call
+            if tc_event.end:
+                if not existing_tool_call:
+                    existing_tool_call = UiPathConversationToolCall(
+                        tool_call_id=tc_event.tool_call_id,
+                        name="",  # unknown until start seen
+                        arguments=None,
+                    )
+                    if msg.tool_calls is None:
+                        msg.tool_calls = []
+                    msg.tool_calls.append(existing_tool_call)
+
+                existing_tool_call.result = UiPathConversationToolCallResult(
+                    timestamp=tc_event.end.timestamp,
+                    value=tc_event.end.result,
+                    is_error=tc_event.end.is_error,
+                    cancelled=tc_event.end.cancelled,
+                )
+
+        # --- Update timestamps ---
+        msg.updated_at = self._timestamp(ev)
+        return msg
+
+    def _timestamp(self, ev: UiPathConversationMessageEvent) -> str:
+        """Choose timestamp from event if available, else fallback."""
+        if ev.start and ev.start.timestamp:
+            return ev.start.timestamp
+        return datetime.now().isoformat()
+
+    def _infer_role(self, ev: UiPathConversationMessageEvent) -> str:
+        if ev.start and ev.start.role:
+            return ev.start.role
+        return "assistant"
+
+
+def build_user_message_event(
+    user_text: str, conversation_id: str, role: str = "user"
+) -> UiPathConversationEvent:
+    message_id = str(uuid.uuid4())
+    content_part_id = str(uuid.uuid4())
+    timestamp = datetime.now().isoformat()
+
+    # Build message start
+    msg_start = UiPathConversationMessageStartEvent(
+        role=role,
+        timestamp=timestamp,
+    )
+
+    # Build content part (simple one-shot inline text)
+    cp_start = UiPathConversationContentPartStartEvent(mime_type="text/plain")
+    cp_chunk = UiPathConversationContentPartChunkEvent(data=user_text)
+    cp_end = UiPathConversationContentPartEndEvent()
+
+    content_event = UiPathConversationContentPartEvent(
+        content_part_id=content_part_id,
+        start=cp_start,
+        chunk=cp_chunk,
+        end=cp_end,
+    )
+
+    # Build message event
+    msg_event = UiPathConversationMessageEvent(
+        message_id=message_id,
+        start=msg_start,
+        content_part=content_event,
+        end=UiPathConversationMessageEndEvent(),
+    )
+
+    # Wrap in exchange event
+    exch_event = UiPathConversationExchangeEvent(
+        exchange_id=str(uuid.uuid4()),
+        message=msg_event,
+    )
+
+    # Finally wrap in conversation event
+    conv_event = UiPathConversationEvent(
+        exchange=exch_event, conversation_id=conversation_id
+    )
+    return conv_event

uipath/_cli/_dev/_terminal/{_traces → _utils}/_logger.py

@@ -11,11 +11,11 @@ class RunContextLogHandler(logging.Handler):
     def __init__(
         self,
         run_id: str,
-        on_log: Callable[[LogMessage], None],
+        callback: Callable[[LogMessage], None],
     ):
         super().__init__()
         self.run_id = run_id
-        self.on_log = on_log
+        self.callback = callback
 
     def emit(self, record: logging.LogRecord):
         """Emit a log record to CLI UI."""
@@ -26,7 +26,7 @@ class RunContextLogHandler(logging.Handler):
                 message=self.format(record),
                 timestamp=datetime.fromtimestamp(record.created),
             )
-            self.on_log(log_msg)
+            self.callback(log_msg)
         except Exception:
             # Don't let logging errors crash the app
             pass

uipath/_cli/_runtime/_contracts.py

@@ -22,6 +22,7 @@ from opentelemetry.sdk.trace.export import (
 from opentelemetry.trace import Tracer
 from pydantic import BaseModel, Field
 
+from uipath.agent.conversation import UiPathConversationEvent
 from uipath.tracing import TracingManager
 
 from ._logging import LogsInterceptor
@@ -134,6 +135,17 @@ class UiPathRuntimeResult(BaseModel):
         return result
 
 
+class UiPathConversationHandler(ABC):
+    """Base delegate for handling UiPath conversation events."""
+
+    use_streaming: bool = True
+
+    @abstractmethod
+    def on_event(self, event: UiPathConversationEvent) -> None:
+        """Handle a conversation event for a given execution run."""
+        pass
+
+
 class UiPathTraceContext(BaseModel):
     """Trace context information for tracing and debugging."""
 
@@ -173,6 +185,8 @@ class UiPathRuntimeContext(BaseModel):
     input_file: Optional[str] = None
     is_eval_run: bool = False
     log_handler: Optional[logging.Handler] = None
+    chat_handler: Optional[UiPathConversationHandler] = None
+
     model_config = {"arbitrary_types_allowed": True}
 
     @classmethod

uipath/_cli/cli_dev.py

@@ -1,23 +1,47 @@
 import asyncio
+import os
 from typing import Optional
 
 import click
 
-from ..telemetry import track
-from ._dev._terminal import UiPathDevTerminal
-from ._runtime._contracts import UiPathRuntimeContext, UiPathRuntimeFactory
-from ._runtime._runtime import UiPathRuntime
-from ._utils._console import ConsoleLogger
-from .middlewares import Middlewares
+from uipath._cli._dev._terminal import UiPathDevTerminal
+from uipath._cli._runtime._contracts import UiPathRuntimeContext, UiPathRuntimeFactory
+from uipath._cli._runtime._runtime import UiPathRuntime
+from uipath._cli._utils._console import ConsoleLogger
+from uipath._cli._utils._debug import setup_debugging
+from uipath._cli.cli_init import init  # type: ignore[attr-defined]
+from uipath._cli.middlewares import Middlewares
+from uipath.telemetry import track
 
 console = ConsoleLogger()
 
 
 @click.command()
 @click.argument("interface", default="terminal")
+@click.option(
+    "--debug",
+    is_flag=True,
+    help="Enable debugging with debugpy. The process will wait for a debugger to attach.",
+)
+@click.option(
+    "--debug-port",
+    type=int,
+    default=5678,
+    help="Port for the debug server (default: 5678)",
+)
 @track
-def dev(interface: Optional[str]) -> None:
+def dev(interface: Optional[str], debug: bool, debug_port: int) -> None:
     """Launch interactive debugging interface."""
+    project_file = os.path.join(os.getcwd(), "uipath.json")
+
+    if not os.path.exists(project_file):
+        console.warning("Project not initialized. Running `uipath init`...")
+        ctx = click.get_current_context()
+        ctx.invoke(init)
+
+    if not setup_debugging(debug, debug_port):
+        console.error(f"Failed to start debug server on port {debug_port}")
+
     console.info("Launching UiPath debugging terminal ...")
     result = Middlewares.next(
         "dev",

uipath/_cli/cli_init.py

@@ -90,7 +90,9 @@ def get_user_script(directory: str, entrypoint: Optional[str] = None) -> Optiona
     python_files = [f for f in os.listdir(directory) if f.endswith(".py")]
 
     if not python_files:
-        console.error("No python files found in the current directory.")
+        console.error(
+            "No python files found in the current directory.\nPlease specify the entrypoint: `uipath init <entrypoint_path>`"
+        )
         return None
     elif len(python_files) == 1:
         return os.path.join(directory, python_files[0])

uipath/agent/conversation/__init__.py

@@ -0,0 +1,135 @@
+"""UiPath Conversation Models.
+
+This module provides Pydantic models that represent the JSON event schema for conversations between a client (UI) and an LLM/agent.
+
+The event objects define a hierarchal conversation structure:
+
+* Conversation
+    * Exchange
+        * Message
+            * Content Parts
+                * Citations
+            * Tool Calls
+                * Tool Results
+
+ A conversation may contain multiple exchanges, and an exchange may contain multiple messages. A message may contain
+ multiple content parts, each of which can be text or binary, including media input and output streams; and each
+ content part can include multiple citations. A message may also contain multiple tool calls, which may contain a tool
+ result.
+
+ The protocol also supports a top level, "async", input media streams (audio and video), which can span multiple
+ exchanges. These are used for Gemini's automatic turn detection mode, where the LLM determines when the user has
+ stopped talking and starts producing output. The output forms one or more messages in an exchange with no explicit
+ input message. However, the LLM may produce an input transcript which can be used to construct the implicit input
+ message that started the exchange.
+
+ In addition, the protocol also supports "async" tool calls that span multiple exchanges. This can be used with
+ Gemini's asynchronous function calling protocol, which allows function calls to produce results that interrupt the
+ conversation when ready, even after multiple exchanges. They also support generating multiple results from a single
+ tool call. By contrast most tool calls are scoped to a single message, which contains both the call and the single
+ result produced by that call.
+
+ Not all features supported by the protocol will be supported by all clients and LLMs. The optional top level
+ `capabilities` property can be used to communicate information about supported features. This property should be set
+ on the first event written to a new websocket connection. This initial event may or may not contain additional
+ sub-events.
+"""
+
+from .async_stream import (
+    UiPathConversationAsyncInputStreamEndEvent,
+    UiPathConversationAsyncInputStreamEvent,
+    UiPathConversationAsyncInputStreamStartEvent,
+    UiPathConversationInputStreamChunkEvent,
+)
+from .citation import (
+    UiPathConversationCitationEndEvent,
+    UiPathConversationCitationEvent,
+    UiPathConversationCitationSource,
+    UiPathConversationCitationSourceMedia,
+    UiPathConversationCitationSourceUrl,
+    UiPathConversationCitationStartEvent,
+)
+from .content import (
+    UiPathConversationContentPart,
+    UiPathConversationContentPartChunkEvent,
+    UiPathConversationContentPartEndEvent,
+    UiPathConversationContentPartEvent,
+    UiPathConversationContentPartStartEvent,
+    UiPathExternalValue,
+    UiPathInlineValue,
+)
+from .conversation import (
+    UiPathConversationCapabilities,
+    UiPathConversationEndEvent,
+    UiPathConversationStartedEvent,
+    UiPathConversationStartEvent,
+)
+from .event import UiPathConversationEvent
+from .exchange import (
+    UiPathConversationExchange,
+    UiPathConversationExchangeEndEvent,
+    UiPathConversationExchangeEvent,
+    UiPathConversationExchangeStartEvent,
+)
+from .message import (
+    UiPathConversationMessage,
+    UiPathConversationMessageEndEvent,
+    UiPathConversationMessageEvent,
+    UiPathConversationMessageStartEvent,
+)
+from .meta import UiPathConversationMetaEvent
+from .tool import (
+    UiPathConversationToolCall,
+    UiPathConversationToolCallEndEvent,
+    UiPathConversationToolCallEvent,
+    UiPathConversationToolCallResult,
+    UiPathConversationToolCallStartEvent,
+)
+
+__all__ = [
+    # Root
+    "UiPathConversationEvent",
+    # Conversation
+    "UiPathConversationCapabilities",
+    "UiPathConversationStartEvent",
+    "UiPathConversationStartedEvent",
+    "UiPathConversationEndEvent",
+    # Exchange
+    "UiPathConversationExchangeStartEvent",
+    "UiPathConversationExchangeEndEvent",
+    "UiPathConversationExchangeEvent",
+    "UiPathConversationExchange",
+    # Message
+    "UiPathConversationMessageStartEvent",
+    "UiPathConversationMessageEndEvent",
+    "UiPathConversationMessageEvent",
+    "UiPathConversationMessage",
+    # Content
+    "UiPathConversationContentPartChunkEvent",
+    "UiPathConversationContentPartStartEvent",
+    "UiPathConversationContentPartEndEvent",
+    "UiPathConversationContentPartEvent",
+    "UiPathConversationContentPart",
+    "UiPathInlineValue",
+    "UiPathExternalValue",
+    # Citation
+    "UiPathConversationCitationStartEvent",
+    "UiPathConversationCitationEndEvent",
+    "UiPathConversationCitationEvent",
+    "UiPathConversationCitationSource",
+    "UiPathConversationCitationSourceUrl",
+    "UiPathConversationCitationSourceMedia",
+    # Tool
+    "UiPathConversationToolCallStartEvent",
+    "UiPathConversationToolCallEndEvent",
+    "UiPathConversationToolCallEvent",
+    "UiPathConversationToolCallResult",
+    "UiPathConversationToolCall",
+    # Async Stream
+    "UiPathConversationInputStreamChunkEvent",
+    "UiPathConversationAsyncInputStreamStartEvent",
+    "UiPathConversationAsyncInputStreamEndEvent",
+    "UiPathConversationAsyncInputStreamEvent",
+    # Meta
+    "UiPathConversationMetaEvent",
+]

uipath/agent/conversation/async_stream.py

@@ -0,0 +1,54 @@
+"""Async input stream events."""
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class UiPathConversationInputStreamChunkEvent(BaseModel):
+    """Represents a single chunk of input stream data."""
+
+    input_stream_sequence: Optional[int] = Field(None, alias="inputStreamSequence")
+    data: str
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationAsyncInputStreamStartEvent(BaseModel):
+    """Signals the start of an asynchronous input stream."""
+
+    mime_type: str = Field(..., alias="mimeType")
+    start_of_speech_sensitivity: Optional[str] = Field(
+        None, alias="startOfSpeechSensitivity"
+    )
+    end_of_speech_sensitivity: Optional[str] = Field(
+        None, alias="endOfSpeechSensitivity"
+    )
+    prefix_padding_ms: Optional[int] = Field(None, alias="prefixPaddingMs")
+    silence_duration_ms: Optional[int] = Field(None, alias="silenceDurationMs")
+    meta_data: Optional[Dict[str, Any]] = Field(None, alias="metaData")
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationAsyncInputStreamEndEvent(BaseModel):
+    """Signals the end of an asynchronous input stream."""
+
+    meta_data: Optional[Dict[str, Any]] = Field(None, alias="metaData")
+    last_chunk_content_part_sequence: Optional[int] = Field(
+        None, alias="lastChunkContentPartSequence"
+    )
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationAsyncInputStreamEvent(BaseModel):
+    """Encapsulates sub-events related to an asynchronous input stream."""
+
+    stream_id: str = Field(..., alias="streamId")
+    start: Optional[UiPathConversationAsyncInputStreamStartEvent] = None
+    end: Optional[UiPathConversationAsyncInputStreamEndEvent] = None
+    chunk: Optional[UiPathConversationInputStreamChunkEvent] = None
+    meta_event: Optional[Dict[str, Any]] = Field(None, alias="metaEvent")
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)

uipath/agent/conversation/citation.py

@@ -0,0 +1,70 @@
+"""Citation events for message content."""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class UiPathConversationCitationStartEvent(BaseModel):
+    """Indicates the start of a citation target in a content part."""
+
+    pass
+
+
+class UiPathConversationCitationEndEvent(BaseModel):
+    """Indicates the end of a citation target in a content part."""
+
+    sources: List[Dict[str, Any]]
+
+
+class UiPathConversationCitationEvent(BaseModel):
+    """Encapsulates sub-events related to citations."""
+
+    citation_id: str = Field(..., alias="citationId")
+    start: Optional[UiPathConversationCitationStartEvent] = None
+    end: Optional[UiPathConversationCitationEndEvent] = None
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationCitationSourceUrl(BaseModel):
+    """Represents a citation source that can be rendered as a link (URL)."""
+
+    url: str
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationCitationSourceMedia(BaseModel):
+    """Represents a citation source that references media, such as a PDF document."""
+
+    mime_type: str = Field(..., alias="mimeType")
+    download_url: Optional[str] = Field(None, alias="downloadUrl")
+    page_number: Optional[str] = Field(None, alias="pageNumber")
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationCitationSource(BaseModel):
+    """Represents a citation source, either a URL or media reference."""
+
+    title: Optional[str] = None
+
+    # Union of Url or Media
+    url: Optional[str] = None
+    mime_type: Optional[str] = Field(None, alias="mimeType")
+    download_url: Optional[str] = Field(None, alias="downloadUrl")
+    page_number: Optional[str] = Field(None, alias="pageNumber")
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationCitation(BaseModel):
+    """Represents a citation or reference inside a content part."""
+
+    citation_id: str = Field(..., alias="citationId")
+    offset: int
+    length: int
+    sources: List[UiPathConversationCitationSource]
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)