albert 1.10.0rc2__py3-none-any.whl → 1.11.1__py3-none-any.whl

albert/collections/reports.py

@@ -1,5 +1,7 @@
 from typing import Any
 
+from pydantic import validate_call
+
 from albert.collections.base import BaseCollection
 from albert.core.session import AlbertSession
 from albert.core.shared.identifiers import ReportId
@@ -136,6 +138,7 @@ class ReportCollection(BaseCollection):
             input_data=input_data,
         )
 
+    @validate_call
     def get_full_report(self, *, report_id: ReportId) -> FullAnalyticalReport:
         """Get a full analytical report by its ID.
 
@@ -192,6 +195,7 @@ class ReportCollection(BaseCollection):
         response = self.session.post(path, json=report_data)
         return FullAnalyticalReport(**response.json())
 
+    @validate_call
     def delete(self, *, id: ReportId) -> None:
         """Delete a report.
 

albert/collections/synthesis.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import validate_call
+
+from albert.collections.base import BaseCollection
+from albert.core.session import AlbertSession
+from albert.core.shared.identifiers import NotebookId, SynthesisId
+from albert.exceptions import AlbertException
+from albert.resources.synthesis import ReactantValues, RowSequence, Synthesis
+
+
+class SynthesisCollection(BaseCollection):
+    """
+    Collection for interacting with synthesis records used by notebook Ketcher blocks.
+    """
+
+    _api_version = "v3"
+    _updatable_attributes = {"name", "status", "hide_reaction_worksheet"}
+
+    def __init__(self, *, session: AlbertSession):
+        """
+        Initialize the SynthesisCollection.
+
+        Parameters
+        ----------
+        session : AlbertSession
+            The Albert session information.
+        """
+        super().__init__(session=session)
+        self.base_path = f"/api/{SynthesisCollection._api_version}/synthesis"
+
+    @validate_call
+    def create(
+        self, *, parent_id: NotebookId | str, name: str, block_id: str, smiles: str | None = None
+    ) -> Synthesis:
+        """
+        Create a synthesis record for a notebook Ketcher block.
+
+        Parameters
+        ----------
+        parent_id : NotebookId | str
+            The notebook ID that owns the synthesis record.
+        name : str
+            The synthesis name.
+        block_id : str
+            The Ketcher block ID associated with the synthesis.
+        smiles : str | None, optional
+            The initial SMILES string for the synthesis.
+
+        Returns
+        -------
+        Synthesis
+            The created synthesis record.
+        """
+        payload = {"name": name, "blockId": block_id, "smiles": smiles}
+        response = self.session.post(
+            url=self.base_path,
+            params={"parentId": parent_id},
+            json=payload,
+        )
+        return Synthesis(**response.json())
+
+    @validate_call
+    def get_by_id(
+        self,
+        *,
+        id: SynthesisId,
+        include_recommendations: bool = False,
+        include_predictions: bool = False,
+        version: str | None = None,
+    ) -> Synthesis:
+        """
+        Retrieve a synthesis record by ID.
+
+        Parameters
+        ----------
+        id : SynthesisId
+            The synthesis ID.
+        include_recommendations : bool, optional
+            Whether to include recommendations in the response.
+        include_predictions : bool, optional
+            Whether to include predictions in the response.
+        version : str | None, optional
+            The specific version to retrieve.
+
+        Returns
+        -------
+        Synthesis
+            The requested synthesis record.
+        """
+        params: dict[str, Any] = {
+            "recommendations": include_recommendations,
+            "predictions": include_predictions,
+        }
+        if version:
+            params["version"] = version
+        response = self.session.get(
+            url=f"{self.base_path}/{id}",
+            params=params,
+        )
+        return Synthesis(**response.json())
+
+    @validate_call
+    def update_canvas_data(
+        self, *, synthesis_id: SynthesisId, smiles: str, data: str, png: str
+    ) -> Synthesis:
+        """
+        Update the Ketcher canvas data for a synthesis record.
+
+        Parameters
+        ----------
+        synthesis_id : SynthesisId
+            The synthesis ID.
+        smiles : str
+            The updated SMILES string.
+        data : str
+            The serialized canvas data.
+        png : str
+            The base64-encoded PNG for the canvas.
+
+        Returns
+        -------
+        Synthesis
+            The updated synthesis record.
+        """
+        payload = {
+            "smiles": smiles,
+            "canvasData": {"data": data, "png": png},
+        }
+        response = self.session.put(
+            url=f"{self.base_path}/{synthesis_id}",
+            json=payload,
+        )
+        return Synthesis(**response.json())
+
+    @validate_call
+    def update(self, *, synthesis: Synthesis) -> Synthesis:
+        """
+        Update a synthesis record.
+
+        Parameters
+        ----------
+        synthesis : Synthesis
+            The synthesis record containing updated fields.
+
+        Returns
+        -------
+        Synthesis
+            The refreshed synthesis record.
+
+        Raises
+        ------
+        AlbertException
+            If the synthesis record is missing an ID.
+        """
+        if synthesis.id is None:
+            msg = "Synthesis id is required to update the record."
+            raise AlbertException(msg)
+        existing = self.get_by_id(id=synthesis.id)
+        patch_data = self._generate_patch_payload(existing=existing, updated=synthesis)
+        if len(patch_data.data) == 0:
+            return existing
+        self.session.patch(
+            url=f"{self.base_path}/{synthesis.id}",
+            json=patch_data.model_dump(by_alias=True, mode="json"),
+        )
+        return self.get_by_id(id=synthesis.id)
+
+    @validate_call
+    def update_reactant_row_values(
+        self,
+        *,
+        synthesis_id: SynthesisId,
+        row_id: str,
+        values: ReactantValues,
+    ) -> Synthesis:
+        """
+        Update the values for a reactant row.
+
+        Parameters
+        ----------
+        synthesis_id : SynthesisId
+            The synthesis ID.
+        row_id : str
+            The reactant row ID to update.
+        values : ReactantValues
+            The values to apply to the reactant row.
+
+        Returns
+        -------
+        Synthesis
+            The updated synthesis record.
+        """
+        payload = {
+            "data": [
+                {
+                    "rowId": row_id,
+                    "operation": "update",
+                    "attribute": "values",
+                    "newValue": values.model_dump(by_alias=True, mode="json"),
+                }
+            ]
+        }
+        self.session.patch(
+            url=f"{self.base_path}/{synthesis_id}/reactants/rows",
+            json=payload,
+        )
+        return self.get_by_id(id=synthesis_id)
+
+    @validate_call
+    def create_reactant_productant_table(self, *, synthesis_id: SynthesisId) -> Synthesis:
+        """
+        Initialize the reactant/product table for a synthesis.
+
+        Parameters
+        ----------
+        synthesis_id : SynthesisId
+            The synthesis ID.
+
+        Returns
+        -------
+        Synthesis
+            The synthesis record.
+        """
+        synthesis = self.get_by_id(id=synthesis_id)
+        if synthesis.inventory_id is not None:
+            return synthesis
+        row_sequence: RowSequence | None = synthesis.row_sequence
+        reactant_row_ids = row_sequence.reactants if row_sequence else []
+        if not reactant_row_ids and synthesis.reactants:
+            reactant_row_ids = [r.row_id for r in synthesis.reactants if r.row_id]
+        if not reactant_row_ids:
+            return synthesis
+
+        self.update_reactant_row_values(
+            synthesis_id=synthesis_id,
+            row_id=reactant_row_ids[0],
+            values=ReactantValues(
+                mass=None,
+                moles=None,
+                eq=None,
+                concentration=100,
+            ),
+        )
+
+        self._send_patch(
+            synthesis_id=synthesis_id,
+            payload={
+                "data": [
+                    {
+                        "attribute": "hideReactionWorksheet",
+                        "operation": "update",
+                        "newValue": "false",
+                    }
+                ]
+            },
+        )
+
+        self._send_patch(
+            synthesis_id=synthesis_id,
+            payload={
+                "data": [
+                    {
+                        "attribute": "inventoryId",
+                        "operation": "add",
+                    }
+                ]
+            },
+        )
+        return self.get_by_id(id=synthesis_id)
+
+    def _send_patch(self, *, synthesis_id: SynthesisId, payload: dict[str, Any]) -> None:
+        """
+        Send a PATCH request to the synthesis endpoint.
+
+        Parameters
+        ----------
+        synthesis_id : SynthesisId
+            The synthesis ID.
+        payload : dict[str, Any]
+            The patch payload to send.
+
+        Returns
+        -------
+        None
+        """
+        self.session.patch(
+            url=f"{self.base_path}/{synthesis_id}",
+            json=payload,
+        )

albert/collections/tasks.py

@@ -27,6 +27,7 @@ from albert.core.shared.identifiers import (
 )
 from albert.exceptions import AlbertHTTPError
 from albert.resources.attachments import AttachmentCategory
+from albert.resources.data_templates import ImportMode
 from albert.resources.tasks import (
     BaseTask,
     BatchTask,
@@ -34,7 +35,6 @@ from albert.resources.tasks import (
     CsvTableResponseItem,
     GeneralTask,
     HistoryEntity,
-    ImportMode,
     PropertyTask,
     TaskAdapter,
     TaskCategory,
@@ -735,6 +735,7 @@ class TaskCollection(BaseCollection):
 
         return self.get_by_id(id=task.id)
 
+    @validate_call
     def get_history(
         self,
         *,

albert/collections/worksheets.py

@@ -48,6 +48,7 @@ class WorksheetCollection(BaseCollection):
         response_json = self._add_session_to_sheets(response_json)
         return Worksheet(**response_json)
 
+    @validate_call
     def setup_worksheet(self, *, project_id: ProjectId, add_sheet=False) -> Worksheet:
         """Setup a new worksheet for a project.
 
@@ -69,6 +70,7 @@ class WorksheetCollection(BaseCollection):
         self.session.post(path, json=params)
         return self.get_by_project_id(project_id=project_id)
 
+    @validate_call
     def setup_new_sheet_from_template(
         self, *, project_id: ProjectId, sheet_template_id: str, sheet_name: str
     ) -> Worksheet:
@@ -94,6 +96,7 @@ class WorksheetCollection(BaseCollection):
         self.session.post(path, json=payload, params=params)
         return self.get_by_project_id(project_id=project_id)
 
+    @validate_call
     def add_sheet(self, *, project_id: ProjectId, sheet_name: str) -> Worksheet:
         """Create a new blank sheet in the Worksheet with the specified name.
 

albert/core/shared/models/base.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from datetime import datetime
 
 from pydantic import Field, PrivateAttr
@@ -21,7 +23,7 @@ class EntityLink(BaseAlbertModel):
     name: str | None = Field(default=None, exclude=True)
     category: str | None = Field(default=None, exclude=True)
 
-    def to_entity_link(self) -> "EntityLink":
+    def to_entity_link(self) -> EntityLink:
         # Convience method to return self, so you can call this method on objects that are already entity links
         return self
 

albert/core/shared/models/patch.py

@@ -43,7 +43,7 @@ class PGPatchDatum(PatchDatum):
 
 class GeneralPatchDatum(PGPatchDatum):
     colId: str | None = Field(default=None)
-    actions: list[PGPatchDatum | DTPatchDatum] | None = None
+    actions: list[PGPatchDatum | DTPatchDatum | PatchDatum] | None = None
     operation: str | None = Field(default=None)
 
 

albert/resources/batch_data.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from enum import Enum
 
 from pydantic import Field
@@ -53,7 +55,7 @@ class BatchDataRow(BaseAlbertModel):
     is_formula: bool | None = Field(default=None, alias="isFormula")
     is_lot_parent: bool | None = Field(default=None, alias="isLotParent")
     values: list[BatchDataValue] = Field(default_factory=list, alias="Values")
-    child_rows: list["BatchDataRow"] = Field(default_factory=list, alias="ChildRows")
+    child_rows: list[BatchDataRow] = Field(default_factory=list, alias="ChildRows")
 
 
 class BatchDataColumn(BaseAlbertModel):
@@ -67,7 +69,7 @@ class BatchDataColumn(BaseAlbertModel):
     product_total: float | None = Field(default=None, alias="productTotal")
     parent_id: str | None = Field(default=None, alias="parentId")
     design_col_id: str | None = Field(default=None, alias="designColId")
-    lots: list["BatchDataColumn"] = Field(default_factory=list, alias="Lots")
+    lots: list[BatchDataColumn] = Field(default_factory=list, alias="Lots")
 
 
 class BatchData(BaseResource):

albert/resources/cas.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from enum import Enum
 
 from pydantic import Field
@@ -53,7 +55,7 @@ class Cas(BaseResource):
     metadata: dict[str, MetadataItem] = Field(alias="Metadata", default_factory=dict)
 
     @classmethod
-    def from_string(cls, *, number: str) -> "Cas":
+    def from_string(cls, *, number: str) -> Cas:
         """
         Creates a Cas object from a string.
 

albert/resources/custom_fields.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from enum import Enum
 from typing import Annotated, Any, Literal
 
@@ -171,7 +173,7 @@ class CustomField(BaseResource):
     api: CustomFieldAPI | None = Field(default=None)
 
     @model_validator(mode="after")
-    def confirm_field_compatability(self) -> "CustomField":
+    def confirm_field_compatability(self) -> CustomField:
         if self.field_type == FieldType.LIST and self.category is None:
             raise ValueError("Category must be set for list fields")
         return self

albert/resources/data_templates.py

@@ -1,10 +1,14 @@
+from __future__ import annotations
+
 from enum import Enum
+from pathlib import Path
+from typing import Literal
 
 from pydantic import AliasChoices, Field, model_validator
 
 from albert.core.base import BaseAlbertModel
 from albert.core.shared.enums import SecurityClass
-from albert.core.shared.identifiers import DataColumnId, DataTemplateId
+from albert.core.shared.identifiers import AttachmentId, DataColumnId, DataTemplateId
 from albert.core.shared.models.base import (
     AuditFields,
     BaseResource,
@@ -15,7 +19,7 @@ from albert.core.shared.models.base import (
 from albert.core.shared.types import MetadataItem, SerializeAsEntityLink
 from albert.resources._mixins import HydrationMixin
 from albert.resources.data_columns import DataColumn
-from albert.resources.parameter_groups import ParameterValue, ValueValidation
+from albert.resources.parameter_groups import DataType, ParameterValue, ValueValidation
 from albert.resources.tagged_base import BaseTaggedResource
 from albert.resources.units import Unit
 from albert.resources.users import User
@@ -30,6 +34,11 @@ class CSVMapping(BaseAlbertModel):
     )
 
 
+class Axis(str, Enum):
+    X = "X"
+    Y = "Y"
+
+
 class CurveDBMetadata(BaseAlbertModel):
     table_name: str | None = Field(default=None, alias="tableName")
     partition_key: str | None = Field(default=None, alias="partitionKey")
@@ -39,6 +48,9 @@ class StorageKeyReference(BaseAlbertModel):
     rawfile: str | None = None
     s3_input: str | None = Field(default=None, alias="s3Input")
     s3_output: str | None = Field(default=None, alias="s3Output")
+    preview: str | None = None
+    thumb: str | None = None
+    original: str | None = None
 
 
 class JobSummary(BaseAlbertModel):
@@ -46,11 +58,6 @@ class JobSummary(BaseAlbertModel):
     state: str | None = None
 
 
-class Axis(str, Enum):
-    X = "X"
-    Y = "Y"
-
-
 class CurveDataEntityLink(EntityLinkWithName):
     id: DataColumnId
     axis: Axis | None = Field(default=None)
@@ -102,11 +109,6 @@ class DataColumnValue(BaseResource):
         return self
 
 
-class Axis(str, Enum):
-    X = "X"
-    Y = "Y"
-
-
 class DataTemplate(BaseTaggedResource):
     name: str
     id: DataTemplateId | None = Field(None, alias="albertId")
@@ -131,6 +133,52 @@ class DataTemplate(BaseTaggedResource):
     full_name: str | None = Field(default=None, alias="fullName", exclude=True, frozen=True)
 
 
+class ImportMode(str, Enum):
+    SCRIPT = "SCRIPT"
+    CSV = "CSV"
+
+
+class CurveExample(BaseAlbertModel):
+    """
+    Curve example data for a data template column.
+
+    Attributes
+    ----------
+    mode : ImportMode
+        ``ImportMode.CSV`` ingests the CSV directly; ``ImportMode.SCRIPT`` runs the attached
+        script first (requires a script attachment on the column).
+    field_mapping : dict[str, str] | None
+        Optional header-to-curve-result mapping, e.g. ``{"visc": "Viscosity"}``. Overrides
+        auto-detected mappings.
+    file_path : str | Path | None
+        Local path to source CSV file.
+    attachment_id : AttachmentId | None
+        Existing attachment ID of source CSV file.
+        Provide exactly one source CSV (local path or existing attachment).
+    """
+
+    type: Literal[DataType.CURVE] = DataType.CURVE
+    mode: ImportMode = ImportMode.CSV
+    field_mapping: dict[str, str] | None = None
+    file_path: str | Path | None = None
+    attachment_id: AttachmentId | None = None
+
+    @model_validator(mode="after")
+    def _require_curve_source(self) -> CurveExample:
+        if (self.file_path is None) == (self.attachment_id is None):
+            raise ValueError(
+                "Provide exactly one of file_path or attachment_id for curve examples."
+            )
+        return self
+
+
+class ImageExample(BaseAlbertModel):
+    """Example data for an image data column."""
+
+    type: Literal[DataType.IMAGE] = DataType.IMAGE
+    file_path: str | Path
+
+
 class DataTemplateSearchItemDataColumn(BaseAlbertModel):
     id: str
     name: str | None = None

albert/resources/entity_types.py

@@ -1,7 +1,9 @@
+from __future__ import annotations
+
 from enum import Enum
 from typing import Any
 
-from pydantic import Field
+from pydantic import Field, model_validator
 
 from albert.core.shared.identifiers import CustomFieldId, EntityTypeId, RuleId
 from albert.core.shared.models.base import BaseAlbertModel, BaseResource, EntityLink
@@ -173,8 +175,8 @@ class EntityType(BaseResource):
     ----------
     id : EntityTypeId
         The unique identifier for the entity type.
-    category : EntityCategory
-        The category the entity type belongs to.
+    category : EntityCategory | None
+        The category the entity type belongs to. Required for tasks and inventories.
     custom_category : str | None, optional
         A custom category name for the entity type.
     label : str
@@ -194,7 +196,7 @@ class EntityType(BaseResource):
     """
 
     id: EntityTypeId | None = Field(alias="albertId", default=None)
-    category: EntityCategory
+    category: EntityCategory | None = None
     custom_category: str | None = Field(
         default=None, max_length=100, min_length=1, alias="customCategory"
     )
@@ -215,6 +217,15 @@ class EntityType(BaseResource):
         alias="searchQueryString", default=None
     )
 
+    @model_validator(mode="after")
+    def validate_category(self) -> EntityType:
+        if (
+            self.service in {EntityServiceType.TASKS, EntityServiceType.INVENTORIES}
+            and self.category is None
+        ):
+            raise ValueError("category is required for tasks and inventories entity types.")
+        return self
+
 
 class EntityTypeOptionType(str, Enum):
     """Types of options that can be used in entity type fields.

albert/resources/inventory.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from enum import Enum
 from typing import Any
 
@@ -104,7 +106,7 @@ class CasAmount(BaseAlbertModel):
     )
 
     @model_validator(mode="after")
-    def set_cas_attributes(self: "CasAmount") -> "CasAmount":
+    def set_cas_attributes(self: CasAmount) -> CasAmount:
         """Set attributes after model initialization from the Cas object, if provided."""
         if self.cas is not None:
             object.__setattr__(self, "id", self.cas.id)
@@ -132,7 +134,7 @@ class InventoryMinimum(BaseAlbertModel):
     minimum: float = Field(ge=0, le=1000000000000000)
 
     @model_validator(mode="after")
-    def check_id_or_location(self: "InventoryMinimum") -> "InventoryMinimum":
+    def check_id_or_location(self: InventoryMinimum) -> InventoryMinimum:
         """
         Ensure that either an id or a location is provided.
         """
@@ -235,7 +237,7 @@ class InventoryItem(BaseTaggedResource):
         return value
 
     @model_validator(mode="after")
-    def set_unit_category(self) -> "InventoryItem":
+    def set_unit_category(self) -> InventoryItem:
         """Set unit category from category if not defined."""
         if self.unit_category is None:
             if self.category in [InventoryCategory.RAW_MATERIALS, InventoryCategory.FORMULAS]:
@@ -245,7 +247,7 @@ class InventoryItem(BaseTaggedResource):
         return self
 
     @model_validator(mode="after")
-    def validate_formula_fields(self) -> "InventoryItem":
+    def validate_formula_fields(self) -> InventoryItem:
         """Ensure required fields are present for formulas."""
         if self.category == InventoryCategory.FORMULAS and not self.project_id and not self.id:
             # Some legacy on platform formulas don't have a project_id so check if its already on platform

albert/resources/lists.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from enum import Enum
 
 from pydantic import Field, model_validator
@@ -34,7 +36,7 @@ class ListItem(BaseResource):
     list_type: str | None = Field(default=None, alias="listType")
 
     @model_validator(mode="after")
-    def validate_list_type(self) -> "ListItem":
+    def validate_list_type(self) -> ListItem:
         if (
             self.category == ListItemCategory.PROJECTS
             and self.list_type is not None