Notebooks

albert.collections.notebooks.NotebookCollection

NotebookCollection(*, session: AlbertSession)

Bases: BaseCollection

Manage Notebooks in the Albert platform.

A Notebook is an electronic lab notebook (ELN): an ordered document made up of content blocks (paragraphs, headers, checklists, tables, images, file attachments, Ketcher chemical drawings, Microsoft Office documents, and embedded reports). Each Notebook is attached to a parent entity, which is a Project, a Task, or a custom template, and is referenced by its Notebook ID (format NTB..., e.g. "NTB123").

Notebook content is edited block-by-block rather than by overwriting the whole document. Create an empty Notebook with create, then add or change blocks with update_block_content or append_blocks. The update method changes only the Notebook name.

This collection is accessed as client.notebooks.

Example

from albert import Albert

client = Albert()
notebook = client.notebooks.get_by_id(id="NTB123")
for block in notebook.blocks:
    print(block.id, block.type)

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Attributes:

Name	Type	Description
base_path	str	The base API route for notebook requests.

Methods:

Name	Description
get_by_id	Get a single notebook by its ID.
search	Search notebook block content across projects.
list_by_parent_id	List the notebooks attached to a given parent (project or task).
create	Find or create an (empty) notebook for the given parent.
delete	Delete a notebook by its ID.
update	Update a notebook's name.
update_block_content	Replace the notebook's block content with the blocks on the object.
append_blocks	Append blocks to the end of a notebook, preserving existing blocks.
get_block_by_id	Get a single block from a notebook by block ID.
copy	Copy a notebook into a specified parent.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

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

def __init__(self, *, session: AlbertSession):
    """Initialize a NotebookCollection.

    Parameters
    ----------
    session : AlbertSession
        The authenticated Albert session used for API calls.
    """
    super().__init__(session=session)
    self.base_path = f"/api/{NotebookCollection._api_version}/notebooks"
    self._files = FileCollection(session=session)
    self._synthesis = SynthesisCollection(session=session)

base_path

base_path = (
    f"/api/{NotebookCollection._api_version}/notebooks"
)

get_by_id

get_by_id(*, id: NotebookId) -> Notebook

Get a single Notebook by its ID.

Example

notebook = client.notebooks.get_by_id(id="NTB123")
print(notebook.name)

Parameters:

Name	Type	Description	Default
id	NotebookId	The Notebook ID to retrieve (format NTB...).	required

Returns:

Type	Description
Notebook	The fully populated notebook.

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

@validate_call
def get_by_id(self, *, id: NotebookId) -> Notebook:
    """Get a single Notebook by its ID.

    !!! example
        ```python
        notebook = client.notebooks.get_by_id(id="NTB123")
        print(notebook.name)
        ```

    Parameters
    ----------
    id : NotebookId
        The Notebook ID to retrieve (format ``NTB...``).

    Returns
    -------
    Notebook
        The fully populated notebook.
    """
    response = self.session.get(f"{self.base_path}/{id}")
    return Notebook(**response.json())

list_by_parent_id

list_by_parent_id(
    *, parent_id: ProjectId | TaskId
) -> list[Notebook]

List the Notebooks attached to a given parent entity.

Example

notebooks = client.notebooks.list_by_parent_id(parent_id="PRO123")
for notebook in notebooks:
    print(notebook.id, notebook.name)

To find notebooks by their block content instead of by parent, use search.

Parameters:

Name	Type	Description	Default
parent_id	ProjectId or TaskId	The ID of the parent entity whose notebooks should be listed (a Project ID, format PRO..., or a Task ID, format TAS...).	required

Returns:

Type	Description
list[Notebook]	The fully populated notebooks attached to the parent.

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

@validate_call
def list_by_parent_id(self, *, parent_id: ProjectId | TaskId) -> list[Notebook]:
    """List the Notebooks attached to a given parent entity.

    !!! example
        ```python
        notebooks = client.notebooks.list_by_parent_id(parent_id="PRO123")
        for notebook in notebooks:
            print(notebook.id, notebook.name)
        ```

    To find notebooks by their block content instead of by parent, use
    [`search`][albert.collections.notebooks.NotebookCollection.search].

    Parameters
    ----------
    parent_id : ProjectId or TaskId
        The ID of the parent entity whose notebooks should be listed
        (a Project ID, format ``PRO...``, or a Task ID, format ``TAS...``).

    Returns
    -------
    list[Notebook]
        The fully populated notebooks attached to the parent.
    """

    # search
    response = self.session.get(f"{self.base_path}/{parent_id}/search")
    # return
    return [self.get_by_id(id=x["id"]) for x in response.json()["Items"]]

search

search(
    *,
    text: str | None = None,
    project_id: SearchProjectId | None = None,
    sort_by: str | None = None,
    order: OrderBy | None = None,
    max_items: int | None = None,
) -> Iterator[NotebookSearchItem]

Search for notebook block content matching the given filters.

Each result is a NotebookSearchItem representing a single matching content block, not a full notebook. Use get_by_id or get_block_by_id to retrieve full notebook content. Results are returned as a lazily paginated iterator.

Example

hits = client.notebooks.search(text="recrystallization", max_items=10)
first = next(iter(hits))
first.notebook_id
# 'NTB123'

Parameters:

Name	Type	Description	Default
text	str	Free-text search term matched against block content.	None
project_id	SearchProjectId	Scope the search to notebooks in the given project (format PRO...). The PRO prefix is stripped before the request is sent.	None
sort_by	str	Field to sort on.	None
order	OrderBy	Sort direction for sort_by.	None
max_items	int	Maximum number of items to return in total. If None, iterates over all matches.	None

Returns:

Type	Description
Iterator[NotebookSearchItem]	A lazily paginated iterator of block-level search hits.

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

@validate_call
def search(
    self,
    *,
    text: str | None = None,
    project_id: SearchProjectId | None = None,
    sort_by: str | None = None,
    order: OrderBy | None = None,
    max_items: int | None = None,
) -> Iterator[NotebookSearchItem]:
    """Search for notebook block content matching the given filters.

    Each result is a [`NotebookSearchItem`][albert.resources.notebooks.NotebookSearchItem]
    representing a single matching content block, not a full notebook. Use
    [`get_by_id`][albert.collections.notebooks.NotebookCollection.get_by_id] or
    [`get_block_by_id`][albert.collections.notebooks.NotebookCollection.get_block_by_id]
    to retrieve full notebook content. Results are returned as a lazily
    paginated iterator.

    !!! example
        ```python
        hits = client.notebooks.search(text="recrystallization", max_items=10)
        first = next(iter(hits))
        first.notebook_id
        # 'NTB123'
        ```

    Parameters
    ----------
    text : str, optional
        Free-text search term matched against block content.
    project_id : SearchProjectId, optional
        Scope the search to notebooks in the given project (format ``PRO...``).
        The ``PRO`` prefix is stripped before the request is sent.
    sort_by : str, optional
        Field to sort on.
    order : OrderBy, optional
        Sort direction for ``sort_by``.
    max_items : int, optional
        Maximum number of items to return in total. If None, iterates over all
        matches.

    Returns
    -------
    Iterator[NotebookSearchItem]
        A lazily paginated iterator of block-level search hits.
    """
    params: dict[str, Any] = {
        "text": text,
        "projectId": project_id,
        "sortBy": sort_by,
        "order": order,
    }

    return AlbertPaginator(
        mode=PaginationMode.OFFSET,
        path=f"{self.base_path}/search",
        session=self.session,
        params=params,
        max_items=max_items,
        deserialize=lambda items: [NotebookSearchItem.model_validate(x) for x in items],
    )

create

create(*, notebook: Notebook) -> Notebook

Find or create a Notebook for the provided notebook.

The endpoint first tries to find an existing notebook for the same parent with matching properties; if one is found it is returned, otherwise a new notebook is created.

The notebook must be created empty: the blocks field must be empty. Add content afterward with update_block_content or append_blocks.

Example

from albert.resources.notebooks import Notebook

notebook = client.notebooks.create(
    notebook=Notebook(name="Trial 1 log", parent_id="PRO123")
)

Parameters:

Name	Type	Description	Default
notebook	Notebook	The notebook to find or create. Must have a parent_id and no pre-filled blocks.	required

Returns:

Type	Description
Notebook	The found or newly created notebook.

Raises:

Type	Description
AlbertException	If the notebook has pre-filled blocks.

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

def create(self, *, notebook: Notebook) -> Notebook:
    """Find or create a Notebook for the provided notebook.

    The endpoint first tries to find an existing notebook for the same parent
    with matching properties; if one is found it is returned, otherwise a new
    notebook is created.

    The notebook must be created empty: the ``blocks`` field must be empty.
    Add content afterward with [`update_block_content`][albert.collections.notebooks.NotebookCollection.update_block_content] or
    [`append_blocks`][albert.collections.notebooks.NotebookCollection.append_blocks].

    !!! example
        ```python
        from albert.resources.notebooks import Notebook

        notebook = client.notebooks.create(
            notebook=Notebook(name="Trial 1 log", parent_id="PRO123")
        )
        ```

    Parameters
    ----------
    notebook : Notebook
        The notebook to find or create. Must have a ``parent_id`` and no
        pre-filled ``blocks``.

    Returns
    -------
    Notebook
        The found or newly created notebook.

    Raises
    ------
    AlbertException
        If the notebook has pre-filled blocks.
    """
    if notebook.blocks:
        # This check keeps a user from corrupting the Notebook data.
        msg = (
            "Cannot create a Notebook with pre-filled blocks. "
            "Set `blocks=[]` (or do not set it) when creating it. "
            "Use `.update_block_content()` afterward to add, update, or delete blocks."
        )
        raise AlbertException(msg)
    response = self.session.post(
        url=self.base_path,
        json=notebook.model_dump(mode="json", by_alias=True, exclude_none=True),
        params={"parentId": notebook.parent_id},
    )
    return Notebook(**response.json())

delete

delete(*, id: NotebookId) -> None

Delete a Notebook by its ID.

Example

client.notebooks.delete(id="NTB123")

Parameters:

Name	Type	Description	Default
id	NotebookId	The Notebook ID to delete (format NTB...).	required

Returns:

Type	Description
None

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

@validate_call
def delete(self, *, id: NotebookId) -> None:
    """Delete a Notebook by its ID.

    !!! example
        ```python
        client.notebooks.delete(id="NTB123")
        ```

    Parameters
    ----------
    id : NotebookId
        The Notebook ID to delete (format ``NTB...``).

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

update

update(*, notebook: Notebook) -> Notebook

Update a Notebook's name.

This method changes only the notebook name; it does not modify block content. Use update_block_content to change the blocks.

Example

notebook = client.notebooks.get_by_id(id="NTB123")
notebook.name = "Revised trial log"
notebook = client.notebooks.update(notebook=notebook)

Parameters:

Name	Type	Description	Default
notebook	Notebook	The notebook carrying the desired name. It must have an id.	required

Returns:

Type	Description
Notebook	The updated notebook.

Notes

The following fields can be updated: name.

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

def update(self, *, notebook: Notebook) -> Notebook:
    """Update a Notebook's name.

    This method changes only the notebook name; it does not modify block
    content. Use [`update_block_content`][albert.collections.notebooks.NotebookCollection.update_block_content] to change the blocks.

    !!! example
        ```python
        notebook = client.notebooks.get_by_id(id="NTB123")
        notebook.name = "Revised trial log"
        notebook = client.notebooks.update(notebook=notebook)
        ```

    Parameters
    ----------
    notebook : Notebook
        The notebook carrying the desired name. It must have an ``id``.

    Returns
    -------
    Notebook
        The updated notebook.

    Notes
    -----
    The following fields can be updated: ``name``.
    """
    existing_notebook = self.get_by_id(id=notebook.id)
    patch_data = self._generate_patch_payload(existing=existing_notebook, updated=notebook)
    url = f"{self.base_path}/{notebook.id}"

    self.session.patch(url, json=patch_data.model_dump(mode="json", by_alias=True))

    return self.get_by_id(id=notebook.id)

update_block_content

update_block_content(*, notebook: Notebook) -> Notebook

Replace a Notebook's block content with the blocks on the object.

The notebook's blocks list is treated as the desired final state: the order of the blocks is preserved, any block not already on Albert is created, and any existing block that is no longer present is deleted. This does not change the notebook name (use update for that).

When writing @-mention chips (<span data-albertid="..." data-type="..."> spans) into block text, also create the backing mention links. Saving the HTML does not register them, and without a link the chip does not resolve in the UI. Create one link per mentioned entity with create (category="mention", parent = the notebook, child = the mentioned entity), then re-read the notebook and confirm its links list them.

Warning

Updating existing Ketcher blocks is not supported. To change a Ketcher block, delete it and create a new one instead.

Example

# Add a Ketcher block from SMILES
from albert.resources.notebooks import KetcherBlock, KetcherContent

notebook = client.notebooks.get_by_id(id="NTB123")
notebook.blocks.append(
    KetcherBlock(content=KetcherContent(smiles="CCO"))
)
notebook = client.notebooks.update_block_content(notebook=notebook)

Parameters:

Name	Type	Description	Default
notebook	Notebook	The notebook whose blocks describe the desired content. It must have an id.	required

Returns:

Type	Description
Notebook	The updated notebook.

Raises:

Type	Description
AlbertException	If the notebook has no id, if two blocks share the same id, or if an existing block's type is changed in place.

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

def update_block_content(self, *, notebook: Notebook) -> Notebook:
    """Replace a Notebook's block content with the blocks on the object.

    The notebook's ``blocks`` list is treated as the desired final state: the
    order of the blocks is preserved, any block not already on Albert is
    created, and any existing block that is no longer present is deleted. This
    does not change the notebook name (use [`update`][albert.collections.notebooks.NotebookCollection.update] for that).

    When writing @-mention chips (``<span data-albertid="..." data-type="...">``
    spans) into block text, also create the backing mention links. Saving the
    HTML does not register them, and without a link the chip does not resolve
    in the UI. Create one link per mentioned entity with
    [`create`][albert.collections.links.LinksCollection.create]
    (``category="mention"``, parent = the notebook, child = the mentioned
    entity), then re-read the notebook and confirm its ``links`` list them.

    !!! warning
        Updating existing Ketcher blocks is not supported. To change a Ketcher
        block, delete it and create a new one instead.

    !!! example
        ```python
        # Add a Ketcher block from SMILES
        from albert.resources.notebooks import KetcherBlock, KetcherContent

        notebook = client.notebooks.get_by_id(id="NTB123")
        notebook.blocks.append(
            KetcherBlock(content=KetcherContent(smiles="CCO"))
        )
        notebook = client.notebooks.update_block_content(notebook=notebook)
        ```

    Parameters
    ----------
    notebook : Notebook
        The notebook whose ``blocks`` describe the desired content. It must
        have an ``id``.

    Returns
    -------
    Notebook
        The updated notebook.

    Raises
    ------
    AlbertException
        If the notebook has no ``id``, if two blocks share the same id, or if
        an existing block's type is changed in place.
    """
    if notebook.id is None:
        raise AlbertException("Notebook id is required to update block content.")
    put_data, ketcher_updates = self._generate_put_block_payload(notebook=notebook)
    url = f"{self.base_path}/{notebook.id}/content"

    self.session.put(url, json=put_data.model_dump(mode="json", by_alias=True))

    for action in ketcher_updates:
        self._synthesis.update_canvas_data(
            synthesis_id=action.synthesis_id,
            smiles=action.smiles,
            data=action.data,
            png=action.png,
        )
        self._synthesis.create_reactant_productant_table(synthesis_id=action.synthesis_id)
    return self.get_by_id(id=notebook.id)

append_blocks

append_blocks(
    *, id: NotebookId, blocks: list[NotebookBlock]
) -> Notebook

Append blocks to the end of a Notebook, preserving existing blocks.

This is a convenience wrapper around update_block_content: it fetches the current notebook, adds the given blocks after the existing ones, and saves.

Example

# Append a paragraph block
from albert.resources.notebooks import ParagraphBlock, ParagraphContent

notebook = client.notebooks.append_blocks(
    id="NTB123",
    blocks=[ParagraphBlock(content=ParagraphContent(text="Hello"))],
)

Parameters:

Name	Type	Description	Default
id	NotebookId	The Notebook ID to append to (format NTB...).	required
blocks	list[NotebookBlock]	The blocks to append to the end of the notebook.	required

Returns:

Type	Description
Notebook	The updated notebook.

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

@validate_call
def append_blocks(self, *, id: NotebookId, blocks: list[NotebookBlock]) -> Notebook:
    """Append blocks to the end of a Notebook, preserving existing blocks.

    This is a convenience wrapper around [`update_block_content`][albert.collections.notebooks.NotebookCollection.update_block_content]: it
    fetches the current notebook, adds the given blocks after the existing
    ones, and saves.

    !!! example
        ```python
        # Append a paragraph block
        from albert.resources.notebooks import ParagraphBlock, ParagraphContent

        notebook = client.notebooks.append_blocks(
            id="NTB123",
            blocks=[ParagraphBlock(content=ParagraphContent(text="Hello"))],
        )
        ```

    Parameters
    ----------
    id : NotebookId
        The Notebook ID to append to (format ``NTB...``).
    blocks : list[NotebookBlock]
        The blocks to append to the end of the notebook.

    Returns
    -------
    Notebook
        The updated notebook.
    """
    notebook = self.get_by_id(id=id)
    notebook.blocks.extend(blocks)
    return self.update_block_content(notebook=notebook)

get_block_by_id

get_block_by_id(
    *, notebook_id: NotebookId, block_id: str
) -> NotebookBlock

Get a single block from a Notebook by block ID.

Example

block = client.notebooks.get_block_by_id(
    notebook_id="NTB123", block_id="abc-123"
)

Parameters:

Name	Type	Description	Default
notebook_id	NotebookId	The Notebook ID the block belongs to (format NTB...).	required
block_id	str	The ID of the block to retrieve.	required

Returns:

Type	Description
NotebookBlock	The requested block, typed according to its block type (e.g. ParagraphBlock).

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

@validate_call
def get_block_by_id(self, *, notebook_id: NotebookId, block_id: str) -> NotebookBlock:
    """Get a single block from a Notebook by block ID.

    !!! example
        ```python
        block = client.notebooks.get_block_by_id(
            notebook_id="NTB123", block_id="abc-123"
        )
        ```

    Parameters
    ----------
    notebook_id : NotebookId
        The Notebook ID the block belongs to (format ``NTB...``).
    block_id : str
        The ID of the block to retrieve.

    Returns
    -------
    NotebookBlock
        The requested block, typed according to its block type (e.g.
        [`ParagraphBlock`][albert.resources.notebooks.ParagraphBlock]).
    """
    response = self.session.get(f"{self.base_path}/{notebook_id}/blocks/{block_id}")
    return TypeAdapter(NotebookBlock).validate_python(response.json())

copy

copy(
    *,
    notebook_copy_info: NotebookCopyInfo,
    type: NotebookCopyType,
) -> Notebook

Copy a Notebook into a specified parent.

Example

from albert.resources.notebooks import NotebookCopyInfo, NotebookCopyType

copy = client.notebooks.copy(
    notebook_copy_info=NotebookCopyInfo(id="NTB123", parent_id="PRO456"),
    type=NotebookCopyType.PROJECT,
)

Parameters:

Name	Type	Description	Default
notebook_copy_info	NotebookCopyInfo	Describes the source notebook and the destination parent for the copy. When type is RESTORE_TEMPLATE, template_id must be set to the source custom template (format CTP...).	required
type	NotebookCopyType	The kind of copy to perform (e.g. into a template, task, or project, or restoring a template).	required

Returns:

Type	Description
Notebook	The newly created copy.

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

def copy(self, *, notebook_copy_info: NotebookCopyInfo, type: NotebookCopyType) -> Notebook:
    """Copy a Notebook into a specified parent.

    !!! example
        ```python
        from albert.resources.notebooks import NotebookCopyInfo, NotebookCopyType

        copy = client.notebooks.copy(
            notebook_copy_info=NotebookCopyInfo(id="NTB123", parent_id="PRO456"),
            type=NotebookCopyType.PROJECT,
        )
        ```

    Parameters
    ----------
    notebook_copy_info : NotebookCopyInfo
        Describes the source notebook and the destination parent for the copy.
        When ``type`` is [`RESTORE_TEMPLATE`][albert.resources.notebooks.NotebookCopyType.RESTORE_TEMPLATE],
        ``template_id`` must be set to the source custom template (format ``CTP...``).
    type : NotebookCopyType
        The kind of copy to perform (e.g. into a template, task, or project,
        or restoring a template).

    Returns
    -------
    Notebook
        The newly created copy.
    """
    response = self.session.post(
        url=f"{self.base_path}/copy",
        json=notebook_copy_info.model_dump(mode="json", by_alias=True, exclude_none=True),
        params={"type": type, "parentId": notebook_copy_info.parent_id},
    )
    return Notebook(**response.json())