Chats (🧪Beta)

Beta Feature!

This resource is in beta. The API is subject to change.

albert.resources.chats

ChatComponentType

Bases: str, Enum

Component type of a chat message.

Attributes:

Name	Type	Description
`TEXT`
`IMAGE`
`REASONING_BLOCK`
`NOTEBOOK_CITATION`
`PRODUCT_CARD`
`INGREDIENT_CARD`
`TOOL_CALL`
`ERROR`

TEXT

TEXT = 'text'

IMAGE

IMAGE = 'image'

REASONING_BLOCK

REASONING_BLOCK = 'reasoning_block'

NOTEBOOK_CITATION

NOTEBOOK_CITATION = 'notebook_citation'

PRODUCT_CARD

PRODUCT_CARD = 'product_card'

INGREDIENT_CARD

INGREDIENT_CARD = 'ingredient_card'

TOOL_CALL

TOOL_CALL = 'tool_call'

ERROR

ERROR = 'error'

ChatUserType

Bases: str, Enum

Origin of a chat message (user-submitted vs system-generated).

Attributes:

Name	Type	Description
`USER`
`SYSTEM`

USER

USER = 'user'

SYSTEM

SYSTEM = 'system'

ChatRole

Bases: str, Enum

Chat role for a message, as used by the LLM conversation model.

Attributes:

Name	Type	Description
`USER`
`ASSISTANT`

USER

USER = 'user'

ASSISTANT

ASSISTANT = 'assistant'

ChatFolderType

Bases: str, Enum

Hierarchy level of a chat folder.

Attributes:

Name	Type	Description
`ROOT`
`CHILD`

ROOT

ROOT = 'root'

CHILD

CHILD = 'child'

ChatSession

Bases: BaseResource

A persistent chat session.

Attributes:

Name	Type	Description
`id`	`str \| None`	The session ID assigned by the server.
`name`	`str`	The display name of the session.
`parent_id`	`str \| None`	Optional folder ID that contains this session.
`source_session_id`	`str`	External session identifier for linking to a source system.
`last_message_at`	`str \| None`	ISO 8601 timestamp of the most recent message in the session.

id

id: str | None = Field(default=None)

name

name: str

parent_id

parent_id: str | None = Field(
    default=None, alias="parentId"
)

source_session_id

source_session_id: str = Field(alias='sourceSessionId')

last_message_at

last_message_at: str | None = Field(
    default=None, alias="lastMessageAt"
)

ChatMessage

Bases: BaseResource

A single message component within a chat session.

Attributes:

Name	Type	Description
`id`	`str \| None`	The message ID assigned by the server.
`source_request_id`	`str \| None`	Client-generated request trace identifier. Auto-generated on create if not set.
`sequence`	`str \| None`	Zero-padded position of this message in the session (e.g. "000", "001").
`component_type`	`ChatComponentType`	The type of message component (e.g. text, image, reasoning_block).
`user_type`	`ChatUserType`	Whether the message originates from a user or the system.
`role`	`ChatRole`	The LLM conversation role (user or assistant).
`content`	`str \| dict[str, Any]`	Component-type-specific payload; a string or free-form object.
`parent_id`	`str \| None`	The session ID this message belongs to. Present in GET responses; derived from the URL path on create.
`component_id`	`str \| None`	Component instance identifier.
`parent_request_id`	`str \| None`	Parent request ID for branched messages.
`branch_index`	`int \| None`	Branch index for branched messages.
`span_id`	`str \| None`	Span/trace identifier.
`is_visible`	`bool \| None`	Whether the component is visible in the UI.
`display_feedback_component`	`bool \| None`	Whether to show the feedback UI for this message.

id

id: str | None = Field(default=None)

source_request_id

source_request_id: str | None = Field(
    default=None, alias="sourceRequestId"
)

sequence

sequence: str | None = Field(default=None)

component_type

component_type: ChatComponentType = Field(
    alias="componentType"
)

user_type

user_type: ChatUserType = Field(alias='userType')

role

role: ChatRole = Field(alias='role')

content

content: str | dict[str, Any] = Field(alias='Content')

parent_id

parent_id: str | None = Field(
    default=None, alias="parentId"
)

component_id

component_id: str | None = Field(
    default=None, alias="componentId"
)

parent_request_id

parent_request_id: str | None = Field(
    default=None, alias="parentRequestId"
)

branch_index

branch_index: int | None = Field(
    default=None, alias="branchIndex"
)

span_id

span_id: str | None = Field(default=None, alias='spanId')

is_visible

is_visible: bool | None = Field(
    default=None, alias="isVisible"
)

display_feedback_component

display_feedback_component: bool | None = Field(
    default=None, alias="displayFeedbackComponent"
)

value

value: list[dict] | None = Field(default=None)

ChatFolder

Bases: BaseResource

A folder used to organise chat sessions.

Attributes:

Name	Type	Description
`id`	`str \| None`	The folder ID assigned by the server.
`name`	`str`	The display name of the folder.
`folder_type`	`ChatFolderType \| None`	Whether this is a root or child folder.
`parent_id`	`str \| None`	Optional parent folder ID for nested folders.

id

id: str | None = Field(default=None)

name

name: str

folder_type

folder_type: ChatFolderType | None = Field(
    default=None, alias="type"
)

parent_id

parent_id: str | None = Field(
    default=None, alias="parentId"
)

ChatFlagType

Bases: str, Enum

Type of flag that can be applied to a chat message.

Attributes:

Name	Type	Description
`STARRED`
`DOWNLOADED`
`REQUESTED`
`HALLUCINATED`

STARRED

STARRED = 'starred'

DOWNLOADED

DOWNLOADED = 'downloaded'

REQUESTED

REQUESTED = 'requested'

HALLUCINATED

HALLUCINATED = 'hallucinated'

ChatFlag

Bases: BaseResource

A flag applied to a chat message.

Attributes:

Name	Type	Description
`source_request_id`	`str \| None`	Request/trace identifier for the flagged message.
`id`	`str \| None`	Message identifier.
`parent_id`	`str \| None`	Parent session ID of the flagged message.
`type`	`ChatFlagType \| None`	The type of flag.
`component_type`	`ChatComponentType \| None`	Component type of the flagged message.
`sequence`	`str \| None`	Zero-padded sequence of the flagged message.
`starred`	`bool \| None`	Whether the message is starred.
`requested`	`bool \| None`	Whether the message is marked as requested.
`downloaded`	`bool \| None`	Whether the message is marked as downloaded.
`hallucinated`	`bool \| None`	Whether the message is marked as hallucinated.

source_request_id

source_request_id: str | None = Field(
    default=None, alias="sourceRequestId"
)

id

id: str | None = Field(default=None)

parent_id

parent_id: str | None = Field(
    default=None, alias="parentId"
)

type

type: ChatFlagType | None = Field(default=None)

component_type

component_type: ChatComponentType | None = Field(
    default=None, alias="componentType"
)

sequence

sequence: str | None = Field(default=None)

starred

starred: bool | None = Field(default=None)

requested

requested: bool | None = Field(default=None)

downloaded

downloaded: bool | None = Field(default=None)

hallucinated

hallucinated: bool | None = Field(default=None)

ChatFlagsInMessage

Bases: BaseAlbertModel

The set of flags applied to a specific chat message.

Attributes:

Name	Type	Description
`source_request_id`	`str \| None`	Request/trace identifier for the message.
`total`	`int \| None`	Total number of flags on the message.
`flags`	`list[ChatFlagType] \| None`	List of flag types set on the message.

Show JSON schema:

{
  "$defs": {
    "ChatFlagType": {
      "description": "Type of flag that can be applied to a chat message.",
      "enum": [
        "starred",
        "downloaded",
        "requested",
        "hallucinated"
      ],
      "title": "ChatFlagType",
      "type": "string"
    }
  },
  "description": "The set of flags applied to a specific chat message.\n\nAttributes\n----------\nsource_request_id : str | None\n    Request/trace identifier for the message.\ntotal : int | None\n    Total number of flags on the message.\nflags : list[ChatFlagType] | None\n    List of flag types set on the message.",
  "properties": {
    "sourceRequestId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sourcerequestid"
    },
    "total": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Total"
    },
    "flags": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/ChatFlagType"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Flags"
    }
  },
  "title": "ChatFlagsInMessage",
  "type": "object"
}

Fields:

source_request_id (str | None)
total (int | None)
flags (list[ChatFlagType] | None)

source_request_id

source_request_id: str | None = None

total

total: int | None = None

flags

flags: list[ChatFlagType] | None = None