Chat Flags (🧪Beta)

albert.collections.chat_flags.ChatFlagCollection

ChatFlagCollection(*, session: AsyncAlbertSession)

Async collection for managing flags on chat messages (🧪Beta).

Beta Feature!

Please do not use in production or without explicit guidance from Albert. You might otherwise have a bad experience. This feature currently falls outside of the Albert support contract, but we'd love your feedback!

Flags allow users to mark messages as starred, downloaded, requested, or hallucinated.

Parameters:

Name	Type	Description	Default
session	AsyncAlbertSession	The Albert async session instance.	required

Methods:

Name	Description
get_all	Lists all flagged messages of a given flag type.
get_by_message	Retrieves all flags set on a specific message.
add	Adds a flag to a message.
remove	Removes a flag from a message.

Parameters:

Name	Type	Description	Default
session	AsyncAlbertSession	The async session used to make API requests.	required

Source code in src/albert/collections/chat_flags.py

def __init__(self, *, session: AsyncAlbertSession):
    """
    Initializes the ChatFlagCollection with the provided session.

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

get_all

get_all(*, type: ChatFlagType) -> list[ChatFlag]

List all flagged messages of a given type.

Parameters:

Name	Type	Description	Default
type	ChatFlagType	The type of flag to filter by.	required

Returns:

Type	Description
list[ChatFlag]	Flagged messages matching the given type.

Source code in src/albert/collections/chat_flags.py

@validate_call
async def get_all(self, *, type: ChatFlagType) -> list[ChatFlag]:
    """
    List all flagged messages of a given type.

    Parameters
    ----------
    type : ChatFlagType
        The type of flag to filter by.

    Returns
    -------
    list[ChatFlag]
        Flagged messages matching the given type.
    """
    response = await self._session.get(self._flags_base, params={"type": type.value})
    data = response.json()
    return [ChatFlag(**item) for item in data.get("Items", [])]

get_by_message

get_by_message(
    *,
    session_id: str,
    source_request_id: str,
    sequence: str | None = None,
) -> ChatFlagsInMessage

Retrieve all flags set on a specific message.

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 | None	The zero-padded sequence of the message.	None

Returns:

Type	Description
ChatFlagsInMessage	The flags set on the message.

Source code in src/albert/collections/chat_flags.py

@validate_call
async def get_by_message(
    self,
    *,
    session_id: str,
    source_request_id: str,
    sequence: str | None = None,
) -> ChatFlagsInMessage:
    """
    Retrieve all flags set on a specific message.

    Parameters
    ----------
    session_id : str
        The ID of the parent session.
    source_request_id : str
        The request trace identifier of the message.
    sequence : str | None, optional
        The zero-padded sequence of the message.

    Returns
    -------
    ChatFlagsInMessage
        The flags set on the message.
    """
    url = f"{self._sessions_base}/{session_id}/messages/{source_request_id}/flag"
    params: dict[str, str] = {}
    if sequence is not None:
        params["sequence"] = sequence
    response = await self._session.get(url, params=params)
    return ChatFlagsInMessage(**response.json())

add

add(
    *,
    session_id: str,
    source_request_id: str,
    sequence: str,
    type: ChatFlagType,
    component_type: ChatComponentType | None = None,
) -> ChatFlag

Add a flag to a message.

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.	required
type	ChatFlagType	The type of flag to add.	required
component_type	ChatComponentType | None	Narrows the flag to a specific component type.	None

Returns:

Type	Description
ChatFlag	The created flag.

Source code in src/albert/collections/chat_flags.py

@validate_call
async def add(
    self,
    *,
    session_id: str,
    source_request_id: str,
    sequence: str,
    type: ChatFlagType,
    component_type: ChatComponentType | None = None,
) -> ChatFlag:
    """
    Add a flag to a message.

    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.
    type : ChatFlagType
        The type of flag to add.
    component_type : ChatComponentType | None, optional
        Narrows the flag to a specific component type.

    Returns
    -------
    ChatFlag
        The created flag.
    """
    url = f"{self._sessions_base}/{session_id}/messages/{source_request_id}/flag"
    params: dict[str, str] = {"sequence": sequence, "type": type.value}
    if component_type is not None:
        params["componentType"] = component_type.value
    response = await self._session.post(url, params=params)
    return ChatFlag(**response.json())

remove

remove(
    *,
    session_id: str,
    source_request_id: str,
    sequence: str,
    type: ChatFlagType,
    component_type: ChatComponentType | None = None,
) -> None

Remove a flag from a message.

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.	required
type	ChatFlagType	The type of flag to remove.	required
component_type	ChatComponentType | None	Narrows the removal to a specific component type.	None

Returns:

Type	Description
None

Source code in src/albert/collections/chat_flags.py

@validate_call
async def remove(
    self,
    *,
    session_id: str,
    source_request_id: str,
    sequence: str,
    type: ChatFlagType,
    component_type: ChatComponentType | None = None,
) -> None:
    """
    Remove a flag from a message.

    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.
    type : ChatFlagType
        The type of flag to remove.
    component_type : ChatComponentType | None, optional
        Narrows the removal to a specific component type.

    Returns
    -------
    None
    """
    url = f"{self._sessions_base}/{session_id}/messages/{source_request_id}/flag"
    params: dict[str, str] = {"sequence": sequence, "type": type.value}
    if component_type is not None:
        params["componentType"] = component_type.value
    await self._session.delete(url, params=params)