Notebooks

albert.collections.notebooks.NotebookCollection

NotebookCollection(*, session: AlbertSession)

Bases: BaseCollection

NotebookCollection manages Notebook entities in the Albert platform.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The Albert session instance.	required

Attributes:

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

Methods:

Name	Description
get_by_id	Retrieves a notebook by its ID.
list_by_parent_id	Lists notebooks for a given parent (task or project).
create	Creates or returns a notebook.
delete	Deletes a notebook by its ID.
update	Updates a notebook's name.
update_block_content	Updates the block content of a notebook.
append_blocks	Appends blocks to a notebook, preserving existing blocks.
get_block_by_id	Retrieves a notebook block by its ID.
copy	Copies a notebook into a specified parent.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The Albert session instance.	required

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

def __init__(self, *, session: AlbertSession):
    """
    Initializes the NotebookCollection with the provided session.

    Parameters
    ----------
    session : AlbertSession
        The Albert session instance.
    """
    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

Retrieve a Notebook by its ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the Notebook to retrieve.	required

Returns:

Type	Description
Notebook	The Notebook object.

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

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

    Parameters
    ----------
    id : str
        The ID of the Notebook to retrieve.

    Returns
    -------
    Notebook
        The Notebook object.
    """
    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]

Retrieve a Notebook by parent ID.

Parameters:

Name	Type	Description	Default
parent_id	str	The ID of the parent ID, e.g. task or project.	required

Returns:

Type	Description
list[Notebook]	list of notebook references.

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

@validate_call
def list_by_parent_id(self, *, parent_id: ProjectId | TaskId) -> list[Notebook]:
    """Retrieve a Notebook by parent ID.

    Parameters
    ----------
    parent_id : str
        The ID of the parent ID, e.g. task or project.

    Returns
    -------
    list[Notebook]
        list of notebook references.

    """

    # 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"]]

create

create(*, notebook: Notebook) -> Notebook

Create or return notebook for the provided notebook. This endpoint automatically tries to find an existing notebook with the same parameter setpoints, and will either return the existing notebook or create a new one.

Parameters:

Name	Type	Description	Default
notebook	Notebook	A list of Notebook entities to find or create.	required

Returns:

Type	Description
Notebook	A list of created or found Notebook entities.

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

def create(self, *, notebook: Notebook) -> Notebook:
    """Create or return notebook for the provided notebook.
    This endpoint automatically tries to find an existing notebook with the same parameter setpoints, and will either return the existing notebook or create a new one.

    Parameters
    ----------
    notebook : Notebook
        A list of Notebook entities to find or create.

    Returns
    -------
    Notebook
        A list of created or found Notebook entities.
    """
    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

Deletes a notebook by its ID.

Parameters:

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

Returns:

Type	Description
None

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

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

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

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

update

update(*, notebook: Notebook) -> Notebook

Update a notebook.

Parameters:

Name	Type	Description	Default
notebook	Notebook	The updated notebook object.	required

Returns:

Type	Description
Notebook	The updated notebook object as returned by the server.

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.

    Parameters
    ----------
    notebook : Notebook
        The updated notebook object.

    Returns
    -------
    Notebook
        The updated notebook object as returned by the server.

    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

Updates the block content of a Notebook. This does not update the notebook name (use .update for that). If a block in the Notebook does not already exist on Albert, it will be created. Note: The order of the Blocks in your Notebook matter and will be used in the updated Notebook!

Warning

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

Parameters:

Name	Type	Description	Default
notebook	Notebook	The updated notebook object.	required

Returns:

Type	Description
Notebook	The updated notebook object as returned by the server.

Examples:

Add a Ketcher block from SMILES

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

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

def update_block_content(self, *, notebook: Notebook) -> Notebook:
    """
    Updates the block content of a Notebook. This does not update the notebook name (use .update for that).
    If a block in the Notebook does not already exist on Albert, it will be created.
    *Note: The order of the Blocks in your Notebook matter and will be used in the updated Notebook!*

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


    Parameters
    ----------
    notebook : Notebook
        The updated notebook object.

    Returns
    -------
    Notebook
        The updated notebook object as returned by the server.

    Examples
    --------
    !!! example "Add a Ketcher block from SMILES"
        ```python
        notebook = client.notebooks.get_by_id(id="NTB123")
        notebook.blocks.append(
            KetcherBlock(content=KetcherContent(smiles="CCO"))
        )
        notebook = client.notebooks.update_block_content(notebook=notebook)
        ```
    """
    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.

Parameters:

Name	Type	Description	Default
id	str	The ID of the Notebook to append to.	required
blocks	list[NotebookBlock]	The blocks to append to the end of the Notebook.	required

Returns:

Type	Description
Notebook	The updated Notebook.

Examples:

Append a paragraph block

from albert.resources.notebooks import ParagraphBlock, ParagraphContent

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

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.

    Parameters
    ----------
    id : str
        The ID of the Notebook to append to.
    blocks : list[NotebookBlock]
        The blocks to append to the end of the Notebook.

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

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

        notebook = client.notebooks.append_blocks(
            id="NTB123",
            blocks=[ParagraphBlock(content=ParagraphContent(text="Hello"))],
        )
        ```
    """
    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

Retrieve a Notebook Block by its ID.

Parameters:

Name	Type	Description	Default
notebook_id	str	The ID of the Notebook to which the Block belongs.	required
block_id	str	The ID of the Notebook Block to retrieve.	required

Returns:

Type	Description
NotebookBlock	The NotebookBlock object.

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

@validate_call
def get_block_by_id(self, *, notebook_id: NotebookId, block_id: str) -> NotebookBlock:
    """Retrieve a Notebook Block by its ID.

    Parameters
    ----------
    notebook_id : str
        The ID of the Notebook to which the Block belongs.
    block_id : str
        The ID of the Notebook Block to retrieve.

    Returns
    -------
    NotebookBlock
        The NotebookBlock object.
    """
    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

Create a copy of a Notebook into a specified parent

Parameters:

Name	Type	Description	Default
notebook_copy_info	NotebookCopyInfo	The copy information for the Notebook copy	required
type	NotebookCopyType	Differentiate whether copy is for templates, task, project or restoreTemplate	required

Returns:

Type	Description
Notebook	The result of the copied Notebook.

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

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

    Parameters
    ----------
    notebook_copy_info : NotebookCopyInfo
        The copy information for the Notebook copy
    type : NotebookCopyType
        Differentiate whether copy is for templates, task, project or restoreTemplate

    Returns
    -------
    Notebook
        The result of the copied Notebook.
    """
    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())