Merge pull request #16 from UiPath/fix/fix-citation-source-on-event-model

fix: fix citation source on event model and add error & interrupt models

Author: GabrielVasilescu04

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-core"
-version = "0.1.0"
+version = "0.1.1"
 description = "UiPath Core abstractions"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

src/uipath/core/chat/__init__.py

@@ -66,13 +66,23 @@
     UiPathConversationStartedEvent,
     UiPathConversationStartEvent,
 )
-from .event import UiPathConversationEvent
+from .error import (
+    UiPathConversationErrorEndEvent,
+    UiPathConversationErrorEvent,
+    UiPathConversationErrorStartEvent,
+)
+from .event import UiPathConversationEvent, UiPathConversationLabelUpdatedEvent
 from .exchange import (
     UiPathConversationExchange,
     UiPathConversationExchangeEndEvent,
     UiPathConversationExchangeEvent,
     UiPathConversationExchangeStartEvent,
 )
+from .interrupt import (
+    UiPathConversationInterruptEndEvent,
+    UiPathConversationInterruptEvent,
+    UiPathConversationInterruptStartEvent,
+)
 from .message import (
     UiPathConversationMessage,
     UiPathConversationMessageEndEvent,
@@ -91,6 +101,11 @@
 __all__ = [
     # Root
     "UiPathConversationEvent",
+    "UiPathConversationLabelUpdatedEvent",
+    # Error
+    "UiPathConversationErrorStartEvent",
+    "UiPathConversationErrorEndEvent",
+    "UiPathConversationErrorEvent",
     # Conversation
     "UiPathConversationCapabilities",
     "UiPathConversationStartEvent",
@@ -106,6 +121,10 @@
     "UiPathConversationMessageEndEvent",
     "UiPathConversationMessageEvent",
     "UiPathConversationMessage",
+    # Interrupt
+    "UiPathConversationInterruptStartEvent",
+    "UiPathConversationInterruptEndEvent",
+    "UiPathConversationInterruptEvent",
     # Content
     "UiPathConversationContentPartChunkEvent",
     "UiPathConversationContentPartStartEvent",

src/uipath/core/chat/async_stream.py

@@ -4,11 +4,12 @@
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from .error import UiPathConversationErrorEvent
+
 
 class UiPathConversationInputStreamChunkEvent(BaseModel):
     """Represents a single chunk of input stream data."""
 
-    input_stream_sequence: int | None = Field(None, alias="inputStreamSequence")
     data: str
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
@@ -44,9 +45,16 @@ class UiPathConversationAsyncInputStreamEvent(BaseModel):
     """Encapsulates sub-events related to an asynchronous input stream."""
 
     stream_id: str = Field(..., alias="streamId")
-    start: UiPathConversationAsyncInputStreamStartEvent | None = None
-    end: UiPathConversationAsyncInputStreamEndEvent | None = None
+    start: UiPathConversationAsyncInputStreamStartEvent | None = Field(
+        None, alias="startAsyncInputStream"
+    )
+    end: UiPathConversationAsyncInputStreamEndEvent | None = Field(
+        None, alias="endAsyncInputStream"
+    )
     chunk: UiPathConversationInputStreamChunkEvent | None = None
     meta_event: dict[str, Any] | None = Field(None, alias="metaEvent")
+    error: UiPathConversationErrorEvent | None = Field(
+        None, alias="asyncInputStreamError"
+    )
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)

src/uipath/core/chat/citation.py

@@ -1,9 +1,11 @@
 """Citation events for message content."""
 
-from typing import Any
+from __future__ import annotations
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from .error import UiPathConversationErrorEvent
+
 
 class UiPathConversationCitationStartEvent(BaseModel):
     """Indicates the start of a citation target in a content part."""
@@ -14,7 +16,7 @@ class UiPathConversationCitationStartEvent(BaseModel):
 class UiPathConversationCitationEndEvent(BaseModel):
     """Indicates the end of a citation target in a content part."""
 
-    sources: list[dict[str, Any]]
+    sources: list[UiPathConversationCitationSource]
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
@@ -27,6 +29,7 @@ class UiPathConversationCitationEvent(BaseModel):
         None, alias="startCitation"
     )
     end: UiPathConversationCitationEndEvent | None = Field(None, alias="endCitation")
+    error: UiPathConversationErrorEvent | None = Field(None, alias="citationError")
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
@@ -52,9 +55,10 @@ class UiPathConversationCitationSourceMedia(BaseModel):
 class UiPathConversationCitationSource(BaseModel):
     """Represents a citation source, either a URL or media reference."""
 
-    title: str | None = None
+    title: str
+    number: int
 
-    # Union of Url or Media
+    # Union of Url or Media - these are optional
     url: str | None = None
     mime_type: str | None = Field(None, alias="mimeType")
     download_url: str | None = Field(None, alias="downloadUrl")

src/uipath/core/chat/content.py

@@ -5,6 +5,7 @@
 from pydantic import BaseModel, ConfigDict, Field
 
 from .citation import UiPathConversationCitation, UiPathConversationCitationEvent
+from .error import UiPathConversationErrorEvent
 
 
 class UiPathConversationContentPartChunkEvent(BaseModel):
@@ -21,6 +22,9 @@ class UiPathConversationContentPartStartEvent(BaseModel):
 
     mime_type: str = Field(..., alias="mimeType")
     metadata: dict[str, Any] | None = Field(None, alias="metaData")
+    external_value: "UiPathExternalValue | None" = Field(None, alias="externalValue")
+    name: str | None = None
+    timestamp: str | None = None
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
@@ -49,6 +53,7 @@ class UiPathConversationContentPartEvent(BaseModel):
     )
     chunk: UiPathConversationContentPartChunkEvent | None = None
     meta_event: dict[str, Any] | None = Field(None, alias="metaEvent")
+    error: UiPathConversationErrorEvent | None = Field(None, alias="contentPartError")
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
@@ -64,7 +69,7 @@ class UiPathInlineValue(BaseModel):
 class UiPathExternalValue(BaseModel):
     """Used when a value is too large to be returned inline."""
 
-    url: str
+    uri: str
     byte_count: int | None = Field(None, alias="byteCount")
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)

src/uipath/core/chat/error.py

@@ -0,0 +1,34 @@
+"""Common error event models used across all conversation event types."""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class UiPathConversationErrorStartEvent(BaseModel):
+    """Represents the start of an error condition."""
+
+    message: str
+    details: Any | None = None
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationErrorEndEvent(BaseModel):
+    """Represents the end of an error condition."""
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationErrorEvent(BaseModel):
+    """Encapsulates sub-events that represent the start and end of an error condition.
+
+    This is a common error event model used across all event types (conversation, exchange,
+    message, content part, citation, tool call, async input stream).
+    """
+
+    error_id: str = Field(..., alias="errorId")
+    start: UiPathConversationErrorStartEvent | None = Field(None, alias="startError")
+    end: UiPathConversationErrorEndEvent | None = Field(None, alias="endError")
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)

src/uipath/core/chat/event.py

@@ -12,11 +12,21 @@
     UiPathConversationStartedEvent,
     UiPathConversationStartEvent,
 )
+from .error import UiPathConversationErrorEvent
 from .exchange import UiPathConversationExchangeEvent
 from .meta import UiPathConversationMetaEvent
 from .tool import UiPathConversationToolCallEvent
 
 
+class UiPathConversationLabelUpdatedEvent(BaseModel):
+    """Indicates the update of the conversation label."""
+
+    label: str
+    autogenerated: bool
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
 class UiPathConversationEvent(BaseModel):
     """The top-level event type representing an event in a conversation.
 
@@ -31,13 +41,17 @@ class UiPathConversationEvent(BaseModel):
     )
     start: UiPathConversationStartEvent | None = Field(
         None,
+        alias="startSession",
         description="Signals the start of an event stream concerning a conversation. This event does NOT necessarily mean this is a brand new conversation. It may be a continuation of an existing conversation.",
     )
     started: UiPathConversationStartedEvent | None = Field(
-        None, description="Signals the acceptance of the start of a conversation."
+        None,
+        alias="sessionStarted",
+        description="Signals the acceptance of the start of a conversation.",
     )
     end: UiPathConversationEndEvent | None = Field(
         None,
+        alias="endSession",
         description="Signals the end of a conversation event stream. This does NOT mean the conversation is over. A new event stream for the conversation could be started in the future.",
     )
     exchange: UiPathConversationExchangeEvent | None = Field(
@@ -54,10 +68,20 @@ class UiPathConversationEvent(BaseModel):
         alias="asyncToolCall",
         description="Optional async tool call sub-event. This feature is not supported by all LLMs. Most tool calls are scoped to a message, and use the toolCall and toolResult properties defined by the ConversationMessage type.",
     )
+    label_updated: "UiPathConversationLabelUpdatedEvent | None" = Field(
+        None,
+        alias="labelUpdated",
+        description="Indicates that the conversation's label has been updated. Useful for UIs to update the display name of live conversations.",
+    )
     meta_event: UiPathConversationMetaEvent | None = Field(
         None,
         alias="metaEvent",
         description="Allows additional events to be sent in the context of the enclosing event stream.",
     )
+    error: UiPathConversationErrorEvent | None = Field(
+        None,
+        alias="conversationError",
+        description="Sent by the service to indicate the start and end of an error condition impacting a conversation. The client should not send any events for this conversation while the error condition is present.",
+    )
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)

src/uipath/core/chat/exchange.py

@@ -20,6 +20,7 @@
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from .error import UiPathConversationErrorEvent
 from .message import UiPathConversationMessage, UiPathConversationMessageEvent
 
 
@@ -28,6 +29,7 @@ class UiPathConversationExchangeStartEvent(BaseModel):
 
     conversation_sequence: int | None = Field(None, alias="conversationSequence")
     metadata: dict[str, Any] | None = Field(None, alias="metaData")
+    timestamp: str | None = None
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 
@@ -50,6 +52,7 @@ class UiPathConversationExchangeEvent(BaseModel):
     end: UiPathConversationExchangeEndEvent | None = Field(None, alias="endExchange")
     message: UiPathConversationMessageEvent | None = None
     meta_event: dict[str, Any] | None = Field(None, alias="metaEvent")
+    error: UiPathConversationErrorEvent | None = Field(None, alias="exchangeError")
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
 

src/uipath/core/chat/interrupt.py

@@ -0,0 +1,35 @@
+"""Interrupt events for human-in-the-loop patterns."""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class UiPathConversationInterruptStartEvent(BaseModel):
+    """Signals the start of an interrupt - a pause point where the agent needs external input."""
+
+    type: str
+    value: Any
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+
+class UiPathConversationInterruptEndEvent(BaseModel):
+    """Signals the interrupt end event with the provided value."""
+
+    # Can be any type
+    model_config = ConfigDict(
+        validate_by_name=True, validate_by_alias=True, extra="allow"
+    )
+
+
+class UiPathConversationInterruptEvent(BaseModel):
+    """Encapsulates interrupt-related events within a message."""
+
+    interrupt_id: str = Field(..., alias="interruptId")
+    start: UiPathConversationInterruptStartEvent | None = Field(
+        None, alias="startInterrupt"
+    )
+    end: Any | None = Field(None, alias="endInterrupt")
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)

src/uipath/core/chat/message.py

@@ -5,6 +5,8 @@
 from pydantic import BaseModel, ConfigDict, Field
 
 from .content import UiPathConversationContentPart, UiPathConversationContentPartEvent
+from .error import UiPathConversationErrorEvent
+from .interrupt import UiPathConversationInterruptEvent
 from .tool import UiPathConversationToolCall, UiPathConversationToolCallEvent
 
 
@@ -39,7 +41,9 @@ class UiPathConversationMessageEvent(BaseModel):
         None, alias="contentPart"
     )
     tool_call: UiPathConversationToolCallEvent | None = Field(None, alias="toolCall")
+    interrupt: UiPathConversationInterruptEvent | None = None
     meta_event: dict[str, Any] | None = Field(None, alias="metaEvent")
+    error: UiPathConversationErrorEvent | None = Field(None, alias="messageError")
 
     model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)