Chat Folders (🧪Beta)

albert.collections.chat_folders.ChatFolderCollection

ChatFolderCollection(*, session: AsyncAlbertSession)

Async collection for managing chat folders (🧪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!

Parameters:

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

Attributes:

Name	Type	Description
base_path	str	The base URL for chat folder API requests.

Methods:

Name	Description
create	Creates a new chat folder.
get_by_id	Retrieves a chat folder by its ID.
get_all	Iterates over chat folders with optional filters.
update	Updates a chat folder by ID.
delete	Deletes a chat folder by its ID.

Parameters:

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

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

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

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

base_path

base_path: str = f'/api/{_api_version}/chats/folders'

create

create(*, folder: ChatFolder) -> ChatFolder

Create a new chat folder.

Parameters:

Name	Type	Description	Default
folder	ChatFolder	The folder to create.	required

Returns:

Type	Description
ChatFolder	The created folder.

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

@validate_call
async def create(self, *, folder: ChatFolder) -> ChatFolder:
    """
    Create a new chat folder.

    Parameters
    ----------
    folder : ChatFolder
        The folder to create.

    Returns
    -------
    ChatFolder
        The created folder.
    """
    response = await self._session.post(
        self.base_path,
        json=folder.model_dump(by_alias=True, exclude_unset=True, mode="json"),
    )
    return ChatFolder(**response.json())

get_by_id

get_by_id(*, id: str) -> ChatFolder

Retrieve a chat folder by its ID.

Parameters:

Name	Type	Description	Default
id	str	The folder ID.	required

Returns:

Type	Description
ChatFolder	The matching folder.

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

@validate_call
async def get_by_id(self, *, id: str) -> ChatFolder:
    """
    Retrieve a chat folder by its ID.

    Parameters
    ----------
    id : str
        The folder ID.

    Returns
    -------
    ChatFolder
        The matching folder.
    """
    response = await self._session.get(f"{self.base_path}/{id}")
    return ChatFolder(**response.json())

get_all

get_all(
    *,
    name: list[str] | None = None,
    exact_match: bool = False,
    max_items: int | None = None,
) -> AsyncIterator[ChatFolder]

Iterate over chat folders with optional filters.

Parameters:

Name	Type	Description	Default
name	list[str] | None	Filter by folder name(s).	None
exact_match	bool	Whether name filtering uses exact matching (default False).	False
max_items	int | None	Maximum number of items to return in total. If None, fetches all available items.	None

Yields:

Type	Description
ChatFolder	Folders matching the given filters.

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

@validate_call
async def get_all(
    self,
    *,
    name: list[str] | None = None,
    exact_match: bool = False,
    max_items: int | None = None,
) -> AsyncIterator[ChatFolder]:
    """
    Iterate over chat folders with optional filters.

    Parameters
    ----------
    name : list[str] | None, optional
        Filter by folder name(s).
    exact_match : bool, optional
        Whether name filtering uses exact matching (default False).
    max_items : int | None, optional
        Maximum number of items to return in total. If None, fetches all available items.

    Yields
    ------
    ChatFolder
        Folders matching the given filters.
    """
    params: dict[str, str | list[str]] = {}
    if name:
        params["name"] = name
    if exact_match:
        params["exactMatch"] = "true"

    async for folder in AsyncAlbertPaginator(
        session=self._session,
        path=self.base_path,
        deserialize=lambda item: ChatFolder(**item),
        params=params,
        max_items=max_items,
    ):
        yield folder

update

update(
    *,
    id: str,
    name: str | None = None,
    sequence: list[str] | None = None,
) -> ChatFolder

Update a chat folder.

Parameters:

Name	Type	Description	Default
id	str	The ID of the folder to update.	required
name	str | None	New display name for the folder.	None
sequence	list | None	New ordering of child sessions or folders.	None

Returns:

Type	Description
ChatFolder	The updated folder.

Notes

The following fields can be updated: name, sequence.

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

@validate_call
async def update(
    self,
    *,
    id: str,
    name: str | None = None,
    sequence: list[str] | None = None,
) -> ChatFolder:
    """
    Update a chat folder.

    Parameters
    ----------
    id : str
        The ID of the folder to update.
    name : str | None, optional
        New display name for the folder.
    sequence : list | None, optional
        New ordering of child sessions or folders.

    Returns
    -------
    ChatFolder
        The updated folder.

    Notes
    -----
    The following fields can be updated: ``name``, ``sequence``.
    """
    data = []
    if name is not None:
        data.append({"operation": "update", "attribute": "name", "newValue": name})
    if sequence is not None:
        data.append({"operation": "update", "attribute": "sequence", "newValue": sequence})
    if not data:
        return await self.get_by_id(id=id)
    await self._session.patch(f"{self.base_path}/{id}", json={"data": data})
    return await self.get_by_id(id=id)

delete

delete(*, id: str) -> None

Delete a chat folder by ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the folder to delete.	required

Returns:

Type	Description
None

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

@validate_call
async def delete(self, *, id: str) -> None:
    """
    Delete a chat folder by ID.

    Parameters
    ----------
    id : str
        The ID of the folder to delete.

    Returns
    -------
    None
    """
    await self._session.delete(f"{self.base_path}/{id}")