Skip to content

Chat Messages

albert.collections.chat_messages.ChatMessageCollection 

ChatMessageCollection(*, session: AsyncAlbertSession)

Async collection for managing messages within a chat session.

Parameters:

Name Type Description Default
session AsyncAlbertSession

The async session used to make API requests.

 required

Methods:

Name Description
create

Add a message to a chat session.
get_by_id

Retrieve a single message by its source request ID and sequence.
get_all

Iterate over messages in a session.
Source code in src/albert/collections/chat_messages.py 
18
19
20
21
22
23
24
25
26
27
28
def __init__(self, *, session: AsyncAlbertSession):
    """
    Initializes the ChatMessageCollection with the provided session.

    Parameters
    ----------
    session : AsyncAlbertSession
        The async session used to make API requests.
    """
    self._session = session
    self._sessions_base = f"/api/{self._api_version}/chats/sessions"

create 

create(*, message: ChatMessage) -> ChatMessage

Add a message to a chat session.

Parameters:

Name Type Description Default
message ChatMessage

The message to create. parent_id must be set to the session ID. source_request_id is auto-generated if not provided.

 required

Returns:

Type Description
ChatMessage

The created message.
Source code in src/albert/collections/chat_messages.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
@validate_call
async def create(self, *, message: ChatMessage) -> ChatMessage:
    """
    Add a message to a chat session.

    Parameters
    ----------
    message : ChatMessage
        The message to create. ``parent_id`` must be set to the session ID.
        ``source_request_id`` is auto-generated if not provided.

    Returns
    -------
    ChatMessage
        The created message.
    """
    payload = message.model_dump(by_alias=True, exclude_unset=True, mode="json")
    # parentId is encoded in the URL path, not the request body
    payload.pop("parentId", None)
    payload.setdefault("sourceRequestId", str(uuid.uuid4()))
    url = f"{self._sessions_base}/{message.parent_id}/messages"
    response = await self._session.post(url, json=payload)
    return ChatMessage(**response.json())

get_by_id 

get_by_id(
    *,
    session_id: str,
    source_request_id: str,
    sequence: str,
    component_type: ChatComponentType | None = None,
) -> ChatMessage

Retrieve a single message by its source request ID and sequence.

Parameters:

Name Type Description Default
session_id str

The ID of the parent session.

 required
source_request_id str

The request trace identifier of the message.

 required
sequence str

The zero-padded sequence of the message (e.g. "000").

 required
component_type ChatComponentType | None

Narrows the lookup to a specific component type.

 None

Returns:

Type Description
ChatMessage

The matching message.
Source code in src/albert/collections/chat_messages.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@validate_call
async def get_by_id(
    self,
    *,
    session_id: str,
    source_request_id: str,
    sequence: str,
    component_type: ChatComponentType | None = None,
) -> ChatMessage:
    """
    Retrieve a single message by its source request ID and sequence.

    Parameters
    ----------
    session_id : str
        The ID of the parent session.
    source_request_id : str
        The request trace identifier of the message.
    sequence : str
        The zero-padded sequence of the message (e.g. "000").
    component_type : ChatComponentType | None, optional
        Narrows the lookup to a specific component type.

    Returns
    -------
    ChatMessage
        The matching message.
    """
    url = f"{self._sessions_base}/{session_id}/messages/{source_request_id}"
    params: dict = {"sequence": sequence}
    if component_type is not None:
        params["componentType"] = component_type.value
    response = await self._session.get(url, params=params)
    return ChatMessage(**response.json())

get_all 

get_all(
    *, session_id: str, max_items: int | None = None
) -> AsyncIterator[ChatMessage]

Iterate over messages in a session.

Parameters:

Name Type Description Default
session_id str

The ID of the session whose messages to list.

 required
max_items int | None

Maximum number of items to return in total. If None, fetches all available items.

 None

Yields:

Type Description
ChatMessage

Messages in the session, oldest first.
Source code in src/albert/collections/chat_messages.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
async def get_all(
    self,
    *,
    session_id: str,
    max_items: int | None = None,
) -> AsyncIterator[ChatMessage]:
    """
    Iterate over messages in a session.

    Parameters
    ----------
    session_id : str
        The ID of the session whose messages to list.
    max_items : int | None, optional
        Maximum number of items to return in total. If None, fetches all available items.

    Yields
    ------
    ChatMessage
        Messages in the session, oldest first.
    """
    url = f"{self._sessions_base}/{session_id}/messages"
    async for message in AsyncAlbertPaginator(
        session=self._session,
        path=url,
        deserialize=lambda item: ChatMessage(**item),
        max_items=max_items,
    ):
        yield message