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\"``).",
"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). See Also --------",
"title": "Permissionaction"
}
},
"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)
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").
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).
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.