Chats (🧪Beta)
Beta Feature!
This resource is in beta. The API is subject to change.
The kind of content a single ChatMessage component carries.
A turn in an "Ask Albert" conversation is stored as one or more message
components, each of a specific type. The component type determines how the
content payload is shaped and how the UI renders it.
The primary payload is always content (a string or typed JSON object);
some user-side structured responses are carried on separate fields, as noted.
Attributes:
| Name | Type | Description |
|---|---|---|
TEXT |
str
|
Prose / markdown assistant or user text (streamed, APPEND semantics). |
IMAGE |
str
|
Image or code-interpreter chart payload. |
REASONING_BLOCK |
str
|
Collapsible agent reasoning block. |
NOTEBOOK_CITATION |
str
|
Citation card linking to a notebook source. |
DOCUMENT_CITATION |
str
|
Citation card linking to a document source. |
PRODUCT_CARD |
str
|
Formulation inventory card (feedback-eligible in the UI). |
INGREDIENT_CARD |
str
|
Ingredient inventory card (feedback-eligible in the UI). |
TOOL_CALL |
str
|
Structured tool-execution chip (tool name, status, I/O display items);
REPLACE semantics (latest row per |
ERROR |
str
|
An error surfaced to the user. |
PLAN |
str
|
Supervisor plan artifact (plan content in |
PERMISSION_REQUEST |
str
|
Gated SDK-write approval card (permission content in |
Bases: TypedDict
The Albert page a user was viewing when they sent a chat message.
Captured so "Ask Albert" can ground its answer in the entity the user was looking at. All keys are optional.
Attributes:
| Name | Type | Description |
|---|---|---|
url |
str
|
The URL of the page the user was on. |
entity |
str
|
The type of entity in view (e.g. an inventory item or project). |
albert_id |
str
|
The Albert ID of the entity in view. |
parent_id |
str
|
The Albert ID of the entity's parent, when applicable. |
parent_entity |
str
|
The type of the parent entity, when applicable. |
section |
str
|
The section or tab of the page in view. |
Bases: BaseAlbertModel
A chat session to notify when an asynchronous job finishes.
Both identifiers are required. They are issued by the chat platform and are normally supplied automatically by the agent runtime; a script calling the SDK directly has no reason to construct one.
Show JSON schema:
{
"description": "A chat session to notify when an asynchronous job finishes.\n\nBoth identifiers are required. They are issued by the chat platform and\nare normally supplied automatically by the agent runtime; a script calling the\nSDK directly has no reason to construct one.",
"properties": {
"sourceSessionId": {
"description": "The originating frontend session identifier.",
"format": "uuid",
"title": "Sourcesessionid",
"type": "string"
},
"chatSessionId": {
"description": "The chat session identifier (``SES\u2026``) that receives the completion message.",
"title": "Chatsessionid",
"type": "string"
}
},
"required": [
"sourceSessionId",
"chatSessionId"
],
"title": "ChatSessionRef",
"type": "object"
}
Fields:
Bases: BaseResource
A single "Ask Albert" conversation.
A chat session is one conversation thread with Albert's AI assistant. It holds
an ordered series of ChatMessage turns and can be filed under a
ChatFolder. A session has a server-assigned id plus a required
client-facing source_session_id that externally links it to the Ask
session.
Sessions are managed through
ChatSessionCollection
(client.chat_sessions).
Example
Show JSON schema:
{
"$defs": {
"AuditFields": {
"description": "The audit fields for a resource",
"properties": {
"by": {
"default": null,
"title": "By",
"type": "string"
},
"byName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Byname"
},
"at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "At"
}
},
"title": "AuditFields",
"type": "object"
},
"Status": {
"description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n The resource is fully operational and visible in normal operations.\nINACTIVE : str\n The resource is hidden from normal operations and disabled from use.",
"enum": [
"active",
"inactive"
],
"title": "Status",
"type": "string"
}
},
"description": "A single \"Ask Albert\" conversation.\n\nA chat session is one conversation thread with Albert's AI assistant. It holds\nan ordered series of [`ChatMessage`][albert.resources.chats.ChatMessage] turns and can be filed under a\n[`ChatFolder`][albert.resources.chats.ChatFolder]. A session has a server-assigned ``id`` plus a required\nclient-facing ``source_session_id`` that externally links it to the Ask\nsession.\n\nSessions are managed through\n[`ChatSessionCollection`][albert.collections.chat_sessions.ChatSessionCollection]\n(``client.chat_sessions``).\n\n!!! example\n ```python\n from albert.resources.chats import ChatSession\n\n session = ChatSession(name=\"Titanium dioxide questions\", source_session_id=\"ext-123\")\n ```",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The session identifier assigned by Albert. Set once the session is created or retrieved.",
"title": "Id"
},
"name": {
"description": "The display name of the session. Required.",
"title": "Name",
"type": "string"
},
"parentId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The [`ChatFolder`][albert.resources.chats.ChatFolder] this session is filed under, if any. Serialized as ``parentId``.",
"title": "Parentid"
},
"sourceSessionId": {
"description": "An external identifier that links this session to a source system. Required. Serialized as ``sourceSessionId``.",
"title": "Sourcesessionid",
"type": "string"
},
"lastMessageAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp of the most recent message in the session. Read from the server. Serialized as ``lastMessageAt``. See Also --------",
"title": "Lastmessageat"
}
},
"required": [
"name",
"sourceSessionId"
],
"title": "ChatSession",
"type": "object"
}
Fields:
-
status(Status | None) -
created(AuditFields | None) -
updated(AuditFields | None) -
id(str | None) -
name(str) -
parent_id(str | None) -
source_session_id(str) -
last_message_at(str | None)
id: str | None = None
The session identifier assigned by Albert. Set once the session is created or retrieved.
parent_id: str | None = None
The ChatFolder this session is filed under, if any. Serialized as parentId.
source_session_id: str
An external identifier that links this session to a source system. Required. Serialized as sourceSessionId.
last_message_at: str | None = None
ISO 8601 timestamp of the most recent message in the session. Read from the server. Serialized as lastMessageAt. See Also --------
Bases: BaseAlbertModel
A compact reference to a file attached to a chat message.
Records which files arrived with a message so the transcript can render them. Carries display metadata only, never file content or signed URLs.
Show JSON schema:
{
"description": "A compact reference to a file attached to a chat message.\n\nRecords which files arrived with a message so the transcript can render them.\nCarries display metadata only, never file content or signed URLs.",
"properties": {
"fileId": {
"description": "The attachment (ATT) ID of the file.",
"title": "Fileid",
"type": "string"
},
"title": {
"description": "The file's display name.",
"title": "Title",
"type": "string"
},
"kind": {
"description": "The file kind (e.g. ``pdf``, ``image``, ``workbook``, ``csv``).",
"title": "Kind",
"type": "string"
},
"sizeBytes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "The file size in bytes.",
"title": "Sizebytes"
},
"partsSummary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A human-readable description of the file's structure (e.g. ``\"34 pages\"``).",
"title": "Partssummary"
}
},
"required": [
"fileId",
"title",
"kind"
],
"title": "ChatMessageAttachment",
"type": "object"
}
Fields:
-
file_id(str) -
title(str) -
kind(str) -
size_bytes(int | None) -
parts_summary(str | None)
parts_summary: str | None = None
A human-readable description of the file's structure (e.g. "34 pages").
Bases: BaseResource
A single turn (or turn component) within an "Ask Albert" conversation.
A chat message is one component of the back-and-forth inside a
ChatSession: a user prompt, an assistant reply, a reasoning block, a
citation, and so on, as given by its ChatComponentType. Messages are
addressed by the composite key (source_request_id, sequence) (sequence
is zero-padded, e.g. "000"); id exists but lookups use
source_request_id + sequence, and ChatComponentType further
distinguishes components that share a request.
Messages are managed through
ChatMessageCollection
(client.chat_messages).
Example
Show JSON schema:
{
"$defs": {
"AuditFields": {
"description": "The audit fields for a resource",
"properties": {
"by": {
"default": null,
"title": "By",
"type": "string"
},
"byName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Byname"
},
"at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "At"
}
},
"title": "AuditFields",
"type": "object"
},
"ChatComponentType": {
"description": "The kind of content a single [`ChatMessage`][albert.resources.chats.ChatMessage] component carries.\n\nA turn in an \"Ask Albert\" conversation is stored as one or more message\ncomponents, each of a specific type. The component type determines how the\n``content`` payload is shaped and how the UI renders it.\n\nThe primary payload is always ``content`` (a string or typed JSON object);\nsome user-side structured responses are carried on separate fields, as noted.\n\nAttributes\n----------\nTEXT : str\n Prose / markdown assistant or user text (streamed, APPEND semantics).\nIMAGE : str\n Image or code-interpreter chart payload.\nREASONING_BLOCK : str\n Collapsible agent reasoning block.\nNOTEBOOK_CITATION : str\n Citation card linking to a notebook source.\nDOCUMENT_CITATION : str\n Citation card linking to a document source.\nPRODUCT_CARD : str\n Formulation inventory card (feedback-eligible in the UI).\nINGREDIENT_CARD : str\n Ingredient inventory card (feedback-eligible in the UI).\nTOOL_CALL : str\n Structured tool-execution chip (tool name, status, I/O display items);\n REPLACE semantics (latest row per ``component_id`` wins).\nERROR : str\n An error surfaced to the user.\nPLAN : str\n Supervisor plan artifact (plan content in ``content``); the user's\n approve/answer/changes response is carried on the user message via\n [`plan_action`][albert.resources.chats.ChatMessage.plan_action], not in the plan card's ``content``.\nPERMISSION_REQUEST : str\n Gated SDK-write approval card (permission content in ``content``); the\n user's allow/deny is carried via [`permission_action`][albert.resources.chats.ChatMessage.permission_action]\n on the user message (an ``allow_session`` response persists as a durable\n session grant).",
"enum": [
"text",
"image",
"reasoning_block",
"notebook_citation",
"document_citation",
"product_card",
"ingredient_card",
"tool_call",
"error",
"plan",
"permission_request"
],
"title": "ChatComponentType",
"type": "string"
},
"ChatMessageAttachment": {
"description": "A compact reference to a file attached to a chat message.\n\nRecords which files arrived with a message so the transcript can render them.\nCarries display metadata only, never file content or signed URLs.",
"properties": {
"fileId": {
"description": "The attachment (ATT) ID of the file.",
"title": "Fileid",
"type": "string"
},
"title": {
"description": "The file's display name.",
"title": "Title",
"type": "string"
},
"kind": {
"description": "The file kind (e.g. ``pdf``, ``image``, ``workbook``, ``csv``).",
"title": "Kind",
"type": "string"
},
"sizeBytes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "The file size in bytes.",
"title": "Sizebytes"
},
"partsSummary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A human-readable description of the file's structure (e.g. ``\"34 pages\"``).",
"title": "Partssummary"
}
},
"required": [
"fileId",
"title",
"kind"
],
"title": "ChatMessageAttachment",
"type": "object"
},
"ChatRole": {
"description": "The conversation role of a [`ChatMessage`][albert.resources.chats.ChatMessage] in the LLM turn model.\n\nAttributes\n----------\nUSER : str\n A turn spoken by the user.\nASSISTANT : str\n A turn spoken by the assistant.",
"enum": [
"user",
"assistant"
],
"title": "ChatRole",
"type": "string"
},
"ChatUserType": {
"description": "Whether a [`ChatMessage`][albert.resources.chats.ChatMessage] was submitted by a person or generated by Albert.\n\nAttributes\n----------\nUSER : str\n The message was submitted by a person.\nSYSTEM : str\n The message was generated by Albert (the assistant or platform).",
"enum": [
"user",
"system"
],
"title": "ChatUserType",
"type": "string"
},
"PageContext": {
"description": "The Albert page a user was viewing when they sent a chat message.\n\nCaptured so \"Ask Albert\" can ground its answer in the entity the user was\nlooking at. All keys are optional.\n\nAttributes\n----------\nurl : str\n The URL of the page the user was on.\nentity : str\n The type of entity in view (e.g. an inventory item or project).\nalbert_id : str\n The Albert ID of the entity in view.\nparent_id : str\n The Albert ID of the entity's parent, when applicable.\nparent_entity : str\n The type of the parent entity, when applicable.\nsection : str\n The section or tab of the page in view.",
"properties": {
"url": {
"title": "Url",
"type": "string"
},
"entity": {
"title": "Entity",
"type": "string"
},
"albert_id": {
"title": "Albert Id",
"type": "string"
},
"parent_id": {
"title": "Parent Id",
"type": "string"
},
"parent_entity": {
"title": "Parent Entity",
"type": "string"
},
"section": {
"title": "Section",
"type": "string"
}
},
"title": "PageContext",
"type": "object"
},
"Status": {
"description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n The resource is fully operational and visible in normal operations.\nINACTIVE : str\n The resource is hidden from normal operations and disabled from use.",
"enum": [
"active",
"inactive"
],
"title": "Status",
"type": "string"
}
},
"description": "A single turn (or turn component) within an \"Ask Albert\" conversation.\n\nA chat message is one component of the back-and-forth inside a\n[`ChatSession`][albert.resources.chats.ChatSession]: a user prompt, an assistant reply, a reasoning block, a\ncitation, and so on, as given by its [`ChatComponentType`][albert.resources.chats.ChatComponentType]. Messages are\naddressed by the composite key ``(source_request_id, sequence)`` (``sequence``\nis zero-padded, e.g. ``\"000\"``); ``id`` exists but lookups use\n``source_request_id`` + ``sequence``, and [`ChatComponentType`][albert.resources.chats.ChatComponentType] further\ndistinguishes components that share a request.\n\nMessages are managed through\n[`ChatMessageCollection`][albert.collections.chat_messages.ChatMessageCollection]\n(``client.chat_messages``).\n\n!!! example\n ```python\n from albert.resources.chats import ChatMessage, ChatComponentType, ChatUserType, ChatRole\n\n message = ChatMessage(\n parent_id=\"<session id>\",\n component_type=ChatComponentType.TEXT,\n user_type=ChatUserType.USER,\n role=ChatRole.USER,\n content=\"What raw materials contain titanium dioxide?\",\n )\n ```",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The message identifier assigned by Albert.",
"title": "Id"
},
"sourceRequestId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Client-generated request trace identifier that groups the components of one turn. Auto-generated on create when not set. Serialized as ``sourceRequestId``.",
"title": "Sourcerequestid"
},
"sequence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Zero-padded position of this component within the session (e.g. ``\"000\"``, ``\"001\"``). Required on create; defaults to ``\"000\"`` when not set.",
"title": "Sequence"
},
"componentType": {
"$ref": "#/$defs/ChatComponentType",
"description": "The kind of component this message carries (e.g. text, image, reasoning block). Required. Serialized as ``componentType``."
},
"userType": {
"$ref": "#/$defs/ChatUserType",
"description": "Whether the message originates from a person or from Albert. Required. Serialized as ``userType``."
},
"role": {
"$ref": "#/$defs/ChatRole",
"description": "The LLM conversation role (user or assistant). Required."
},
"Content": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": true,
"type": "object"
}
],
"description": "The component's payload, shaped by ``component_type``: a string for text or a free-form object for richer components. Required. Serialized as ``Content``.",
"title": "Content"
},
"parentId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The [`ChatSession`][albert.resources.chats.ChatSession] this message belongs to. Present in retrieved messages; on create it is taken from the URL path. Serialized as ``parentId``.",
"title": "Parentid"
},
"componentId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The component instance identifier. Serialized as ``componentId``.",
"title": "Componentid"
},
"parentRequestId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The source request ID of the parent turn, for branched conversations. Serialized as ``parentRequestId``.",
"title": "Parentrequestid"
},
"branchIndex": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "The branch index, for branched conversations. Serialized as ``branchIndex``.",
"title": "Branchindex"
},
"spanId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A span/trace identifier. Serialized as ``spanId``.",
"title": "Spanid"
},
"isVisible": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the component is shown in the UI. Serialized as ``isVisible``.",
"title": "Isvisible"
},
"displayFeedbackComponent": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the feedback UI is shown for this message. Serialized as ``displayFeedbackComponent``.",
"title": "Displayfeedbackcomponent"
},
"value": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "api-chat storage/history metadata for the message rows grouped under one message ID (revision records, e.g. ``{ts: <epoch>}``). This is NOT the component payload; the payload is in ``content``. Do not treat ``value`` as a general-purpose extra-data field.",
"title": "Value"
},
"pageContext": {
"anyOf": [
{
"$ref": "#/$defs/PageContext"
},
{
"type": "null"
}
],
"default": null,
"description": "The Albert page the user was viewing when they sent the message. Serialized as ``pageContext``."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/ChatMessageAttachment"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Files the user attached to this message, for display in the transcript.",
"title": "Attachments"
},
"planAction": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Structured record of a plan approval or change request the user submitted with this message (present on user rows that acted on a plan card).",
"title": "Planaction"
},
"permissionAction": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Structured record of a permission decision the user submitted with this message (present on user rows that responded to a permission card; an allow_session row is the durable session grant). Superseded by ``permission_actions`` where the client submits every decision as one batch; kept for older clients.",
"title": "Permissionaction"
},
"permissionActions": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Every permission decision the user submitted with this message, as one batch.\n\nPresent on user rows that answered one or more permission cards. Each entry has the\nsame shape as ``permission_action`` and may carry a ``permissionKey`` of the form\n``\"<group>.<write|delete>\"``, which scopes an ``allow_session`` grant to that group\nand action type rather than to all writes. When a row carries both fields, the list\nis authoritative.",
"title": "Permissionactions"
}
},
"required": [
"componentType",
"userType",
"role",
"Content"
],
"title": "ChatMessage",
"type": "object"
}
Fields:
-
status(Status | None) -
created(AuditFields | None) -
updated(AuditFields | None) -
id(str | None) -
source_request_id(str | None) -
sequence(str | None) -
component_type(ChatComponentType) -
user_type(ChatUserType) -
role(ChatRole) -
content(str | dict[str, Any]) -
parent_id(str | None) -
component_id(str | None) -
parent_request_id(str | None) -
branch_index(int | None) -
span_id(str | None) -
is_visible(bool | None) -
display_feedback_component(bool | None) -
value(list[dict] | None) -
page_context(PageContext | None) -
attachments(list[ChatMessageAttachment] | None) -
plan_action(dict[str, Any] | None) -
permission_action(dict[str, Any] | None) -
permission_actions(list[dict[str, Any]] | None)
source_request_id: str | None = None
Client-generated request trace identifier that groups the components of one turn. Auto-generated on create when not set. Serialized as sourceRequestId.
sequence: str | None = None
Zero-padded position of this component within the session (e.g. "000", "001"). Required on create; defaults to "000" when not set.
component_type: ChatComponentType
The kind of component this message carries (e.g. text, image, reasoning block). Required. Serialized as componentType.
user_type: ChatUserType
Whether the message originates from a person or from Albert. Required. Serialized as userType.
The component's payload, shaped by component_type: a string for text or a free-form object for richer components. Required. Serialized as Content.
parent_id: str | None = None
The ChatSession this message belongs to. Present in retrieved messages; on create it is taken from the URL path. Serialized as parentId.
component_id: str | None = None
The component instance identifier. Serialized as componentId.
parent_request_id: str | None = None
The source request ID of the parent turn, for branched conversations. Serialized as parentRequestId.
branch_index: int | None = None
The branch index, for branched conversations. Serialized as branchIndex.
is_visible: bool | None = None
Whether the component is shown in the UI. Serialized as isVisible.
display_feedback_component: bool | None = None
Whether the feedback UI is shown for this message. Serialized as displayFeedbackComponent.
api-chat storage/history metadata for the message rows grouped under one message ID (revision records, e.g. {ts: <epoch>}). This is NOT the component payload; the payload is in content. Do not treat value as a general-purpose extra-data field.
page_context: PageContext | None = None
The Albert page the user was viewing when they sent the message. Serialized as pageContext.
attachments: list[ChatMessageAttachment] | None = None
Files the user attached to this message, for display in the transcript.
Structured record of a plan approval or change request the user submitted with this message (present on user rows that acted on a plan card).
Structured record of a permission decision the user submitted with this message (present on user rows that responded to a permission card; an allow_session row is the durable session grant). Superseded by permission_actions where the client submits every decision as one batch; kept for older clients.
Every permission decision the user submitted with this message, as one batch.
Present on user rows that answered one or more permission cards. Each entry has the
same shape as permission_action and may carry a permissionKey of the form
"<group>.<write|delete>", which scopes an allow_session grant to that group
and action type rather than to all writes. When a row carries both fields, the list
is authoritative.
Bases: BaseResource
A folder for organizing "Ask Albert" conversations.
A chat folder groups related ChatSession conversations and can be
nested inside another folder. A session is filed under a folder via the
session's parent_id.
Folders are managed through
ChatFolderCollection
(client.chat_folders).
Example
Show JSON schema:
{
"$defs": {
"AuditFields": {
"description": "The audit fields for a resource",
"properties": {
"by": {
"default": null,
"title": "By",
"type": "string"
},
"byName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Byname"
},
"at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "At"
}
},
"title": "AuditFields",
"type": "object"
},
"ChatFolderType": {
"description": "The level of a [`ChatFolder`][albert.resources.chats.ChatFolder] within the folder hierarchy.\n\nAttributes\n----------\nROOT : str\n A top-level folder with no parent.\nCHILD : str\n A folder nested inside another folder.",
"enum": [
"root",
"child"
],
"title": "ChatFolderType",
"type": "string"
},
"Status": {
"description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n The resource is fully operational and visible in normal operations.\nINACTIVE : str\n The resource is hidden from normal operations and disabled from use.",
"enum": [
"active",
"inactive"
],
"title": "Status",
"type": "string"
}
},
"description": "A folder for organizing \"Ask Albert\" conversations.\n\nA chat folder groups related [`ChatSession`][albert.resources.chats.ChatSession] conversations and can be\nnested inside another folder. A session is filed under a folder via the\nsession's ``parent_id``.\n\nFolders are managed through\n[`ChatFolderCollection`][albert.collections.chat_folders.ChatFolderCollection]\n(``client.chat_folders``).\n\n!!! example\n ```python\n from albert.resources.chats import ChatFolder\n\n folder = ChatFolder(name=\"Formulation questions\")\n ```",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The folder identifier assigned by Albert. Set once the folder is created or retrieved.",
"title": "Id"
},
"name": {
"description": "The display name of the folder. Required.",
"title": "Name",
"type": "string"
},
"type": {
"anyOf": [
{
"$ref": "#/$defs/ChatFolderType"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether this is a top-level (root) or nested (child) folder. Serialized as ``type``."
},
"parentId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The parent folder for a nested folder, if any. Serialized as ``parentId``. See Also --------",
"title": "Parentid"
}
},
"required": [
"name"
],
"title": "ChatFolder",
"type": "object"
}
Fields:
-
status(Status | None) -
created(AuditFields | None) -
updated(AuditFields | None) -
id(str | None) -
name(str) -
folder_type(ChatFolderType | None) -
parent_id(str | None)
id: str | None = None
The folder identifier assigned by Albert. Set once the folder is created or retrieved.
folder_type: ChatFolderType | None = None
Whether this is a top-level (root) or nested (child) folder. Serialized as type.
parent_id: str | None = None
The parent folder for a nested folder, if any. Serialized as parentId. See Also --------
A marker that can be applied to a ChatMessage.
Flags annotate messages in an "Ask Albert" conversation, chiefly to capture user feedback and interaction state.
Attributes:
| Name | Type | Description |
|---|---|---|
STARRED |
str
|
The message was starred (marked as notable) by the user. |
DOWNLOADED |
str
|
The message's content was downloaded. |
REQUESTED |
str
|
The message was marked as requested. |
HALLUCINATED |
str
|
The message was flagged as a hallucination (an inaccurate answer). |
Bases: BaseResource
A flag applied to a message in an "Ask Albert" conversation.
A chat flag records a marker (see ChatFlagType) on a specific
ChatMessage, identified by its session, request, and sequence. Flags
are returned by Albert; they are added and removed through
ChatFlagCollection
(client.chat_flags) rather than constructed directly.
Show JSON schema:
{
"$defs": {
"AuditFields": {
"description": "The audit fields for a resource",
"properties": {
"by": {
"default": null,
"title": "By",
"type": "string"
},
"byName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Byname"
},
"at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "At"
}
},
"title": "AuditFields",
"type": "object"
},
"ChatComponentType": {
"description": "The kind of content a single [`ChatMessage`][albert.resources.chats.ChatMessage] component carries.\n\nA turn in an \"Ask Albert\" conversation is stored as one or more message\ncomponents, each of a specific type. The component type determines how the\n``content`` payload is shaped and how the UI renders it.\n\nThe primary payload is always ``content`` (a string or typed JSON object);\nsome user-side structured responses are carried on separate fields, as noted.\n\nAttributes\n----------\nTEXT : str\n Prose / markdown assistant or user text (streamed, APPEND semantics).\nIMAGE : str\n Image or code-interpreter chart payload.\nREASONING_BLOCK : str\n Collapsible agent reasoning block.\nNOTEBOOK_CITATION : str\n Citation card linking to a notebook source.\nDOCUMENT_CITATION : str\n Citation card linking to a document source.\nPRODUCT_CARD : str\n Formulation inventory card (feedback-eligible in the UI).\nINGREDIENT_CARD : str\n Ingredient inventory card (feedback-eligible in the UI).\nTOOL_CALL : str\n Structured tool-execution chip (tool name, status, I/O display items);\n REPLACE semantics (latest row per ``component_id`` wins).\nERROR : str\n An error surfaced to the user.\nPLAN : str\n Supervisor plan artifact (plan content in ``content``); the user's\n approve/answer/changes response is carried on the user message via\n [`plan_action`][albert.resources.chats.ChatMessage.plan_action], not in the plan card's ``content``.\nPERMISSION_REQUEST : str\n Gated SDK-write approval card (permission content in ``content``); the\n user's allow/deny is carried via [`permission_action`][albert.resources.chats.ChatMessage.permission_action]\n on the user message (an ``allow_session`` response persists as a durable\n session grant).",
"enum": [
"text",
"image",
"reasoning_block",
"notebook_citation",
"document_citation",
"product_card",
"ingredient_card",
"tool_call",
"error",
"plan",
"permission_request"
],
"title": "ChatComponentType",
"type": "string"
},
"ChatFlagType": {
"description": "A marker that can be applied to a [`ChatMessage`][albert.resources.chats.ChatMessage].\n\nFlags annotate messages in an \"Ask Albert\" conversation, chiefly to capture\nuser feedback and interaction state.\n\nAttributes\n----------\nSTARRED : str\n The message was starred (marked as notable) by the user.\nDOWNLOADED : str\n The message's content was downloaded.\nREQUESTED : str\n The message was marked as requested.\nHALLUCINATED : str\n The message was flagged as a hallucination (an inaccurate answer).",
"enum": [
"starred",
"downloaded",
"requested",
"hallucinated"
],
"title": "ChatFlagType",
"type": "string"
},
"Status": {
"description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n The resource is fully operational and visible in normal operations.\nINACTIVE : str\n The resource is hidden from normal operations and disabled from use.",
"enum": [
"active",
"inactive"
],
"title": "Status",
"type": "string"
}
},
"description": "A flag applied to a message in an \"Ask Albert\" conversation.\n\nA chat flag records a marker (see [`ChatFlagType`][albert.resources.chats.ChatFlagType]) on a specific\n[`ChatMessage`][albert.resources.chats.ChatMessage], identified by its session, request, and sequence. Flags\nare returned by Albert; they are added and removed through\n[`ChatFlagCollection`][albert.collections.chat_flags.ChatFlagCollection]\n(``client.chat_flags``) rather than constructed directly.",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"sourceRequestId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Request/trace identifier of the flagged message. Serialized as ``sourceRequestId``.",
"title": "Sourcerequestid"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The flagged message's identifier.",
"title": "Id"
},
"parentId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The [`ChatSession`][albert.resources.chats.ChatSession] the flagged message belongs to. Serialized as ``parentId``.",
"title": "Parentid"
},
"type": {
"anyOf": [
{
"$ref": "#/$defs/ChatFlagType"
},
{
"type": "null"
}
],
"default": null,
"description": "The type of flag."
},
"componentType": {
"anyOf": [
{
"$ref": "#/$defs/ChatComponentType"
},
{
"type": "null"
}
],
"default": null,
"description": "The component type of the flagged message. Serialized as ``componentType``."
},
"sequence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Zero-padded sequence of the flagged message within the session.",
"title": "Sequence"
},
"starred": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the message is starred.",
"title": "Starred"
},
"requested": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the message is marked as requested.",
"title": "Requested"
},
"downloaded": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the message is marked as downloaded.",
"title": "Downloaded"
},
"hallucinated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the message is flagged as a hallucination. See Also --------",
"title": "Hallucinated"
}
},
"title": "ChatFlag",
"type": "object"
}
Fields:
-
status(Status | None) -
created(AuditFields | None) -
updated(AuditFields | None) -
source_request_id(str | None) -
id(str | None) -
parent_id(str | None) -
type(ChatFlagType | None) -
component_type(ChatComponentType | None) -
sequence(str | None) -
starred(bool | None) -
requested(bool | None) -
downloaded(bool | None) -
hallucinated(bool | None)
source_request_id: str | None = None
Request/trace identifier of the flagged message. Serialized as sourceRequestId.
parent_id: str | None = None
The ChatSession the flagged message belongs to. Serialized as parentId.
component_type: ChatComponentType | None = None
The component type of the flagged message. Serialized as componentType.
sequence: str | None = None
Zero-padded sequence of the flagged message within the session.
hallucinated: bool | None = None
Whether the message is flagged as a hallucination. See Also --------
Bases: BaseAlbertModel
The set of flags currently applied to one chat message.
Returned by
get_by_message to
summarize which ChatFlagType markers are set on a single message.
Show JSON schema:
{
"$defs": {
"ChatFlagType": {
"description": "A marker that can be applied to a [`ChatMessage`][albert.resources.chats.ChatMessage].\n\nFlags annotate messages in an \"Ask Albert\" conversation, chiefly to capture\nuser feedback and interaction state.\n\nAttributes\n----------\nSTARRED : str\n The message was starred (marked as notable) by the user.\nDOWNLOADED : str\n The message's content was downloaded.\nREQUESTED : str\n The message was marked as requested.\nHALLUCINATED : str\n The message was flagged as a hallucination (an inaccurate answer).",
"enum": [
"starred",
"downloaded",
"requested",
"hallucinated"
],
"title": "ChatFlagType",
"type": "string"
}
},
"description": "The set of flags currently applied to one chat message.\n\nReturned by\n[`get_by_message`][albert.collections.chat_flags.ChatFlagCollection.get_by_message] to\nsummarize which [`ChatFlagType`][albert.resources.chats.ChatFlagType] markers are set on a single message.",
"properties": {
"sourceRequestId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Request/trace identifier of the message. Serialized as ``sourceRequestId``.",
"title": "Sourcerequestid"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Total number of flags set on the message.",
"title": "Total"
},
"flags": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/ChatFlagType"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "The flag types set on the message.",
"title": "Flags"
}
},
"title": "ChatFlagsInMessage",
"type": "object"
}
Fields:
-
source_request_id(str | None) -
total(int | None) -
flags(list[ChatFlagType] | None)
source_request_id: str | None = None
Request/trace identifier of the message. Serialized as sourceRequestId.