feat(api): add custom liquid class creator

api/src/opentrons/protocol_api/_liquid.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Optional, Dict, Union, TYPE_CHECKING
+from typing import Optional, Dict, Union, TYPE_CHECKING, Tuple
 
 from opentrons_shared_data.liquid_classes.liquid_class_definition import (
     LiquidClassSchemaV1,
@@ -63,6 +63,20 @@ def create(cls, liquid_class_definition: LiquidClassSchemaV1) -> "LiquidClass":
             _by_pipette_setting=by_pipette_settings,
         )
 
+    @classmethod
+    def create_from(
+        cls,
+        name: str,
+        display_name: str,
+        by_pipette_setting: Dict[str, Dict[str, TransferProperties]],
+    ) -> "LiquidClass":
+        """Create a liquid class from the passed in args."""
+        return cls(
+            _name=name,
+            _display_name=display_name,
+            _by_pipette_setting=by_pipette_setting,
+        )
+
     @property
     def name(self) -> str:
         return self._name
@@ -71,10 +85,54 @@ def name(self) -> str:
     def display_name(self) -> str:
         return self._display_name
 
+    def update_for(
+        self,
+        pipette: Union[str, InstrumentContext],
+        tip_rack: Union[str, Labware],
+        transfer_properties: TransferProperties,
+    ) -> None:
+        """Update the transfer properties for the given pipette and tip combo.
+
+        If an entry does not exist, it will be created.
+        """
+        pipette_name, tiprack_uri = self._get_pipette_and_tiprack_names(
+            pipette, tip_rack
+        )
+        try:
+            self._by_pipette_setting[pipette_name].update(
+                {tiprack_uri: transfer_properties}
+            )
+        except KeyError:
+            self._by_pipette_setting[pipette_name] = {tiprack_uri: transfer_properties}
+
     def get_for(
         self, pipette: Union[str, InstrumentContext], tip_rack: Union[str, Labware]
     ) -> TransferProperties:
         """Get liquid class transfer properties for the specified pipette and tip."""
+        pipette_name, tiprack_uri = self._get_pipette_and_tiprack_names(
+            pipette, tip_rack
+        )
+
+        try:
+            settings_for_pipette = self._by_pipette_setting[pipette_name]
+        except KeyError:
+            raise NoLiquidClassPropertyError(
+                f"No properties found for {pipette_name} in {self._name} liquid class"
+            )
+        try:
+            transfer_properties = settings_for_pipette[tiprack_uri]
+        except KeyError:
+            raise NoLiquidClassPropertyError(
+                f"No properties found for {tiprack_uri} for {pipette_name} in {self._name} liquid class"
+            )
+        return transfer_properties
+
+    @staticmethod
+    def _get_pipette_and_tiprack_names(
+        pipette: Union[str, InstrumentContext],
+        tip_rack: Union[str, Labware],
+    ) -> Tuple[str, str]:
+        """Return the pipette and tip rack name strings from the given pipette and tip rack."""
         from . import InstrumentContext, Labware
 
         if isinstance(pipette, InstrumentContext):
@@ -96,17 +154,4 @@ def get_for(
                 f"{tip_rack} should either be a tiprack Labware object"
                 f" or a tiprack URI string."
             )
-
-        try:
-            settings_for_pipette = self._by_pipette_setting[pipette_name]
-        except KeyError:
-            raise NoLiquidClassPropertyError(
-                f"No properties found for {pipette_name} in {self._name} liquid class"
-            )
-        try:
-            transfer_properties = settings_for_pipette[tiprack_uri]
-        except KeyError:
-            raise NoLiquidClassPropertyError(
-                f"No properties found for {tiprack_uri} for {pipette_name} in {self._name} liquid class"
-            )
-        return transfer_properties
+        return pipette_name, tiprack_uri

api/src/opentrons/protocol_api/_liquid_properties.py

@@ -1,8 +1,9 @@
 from dataclasses import dataclass
 from numpy import interp
-from typing import Optional, Dict, Sequence, Tuple, List
+from typing import Optional, Dict, Sequence, Tuple, List, Union
 
 from opentrons_shared_data.liquid_classes.liquid_class_definition import (
+    TransferProperties as SharedDataTransferProperties,
     AspirateProperties as SharedDataAspirateProperties,
     SingleDispenseProperties as SharedDataSingleDispenseProperties,
     MultiDispenseProperties as SharedDataMultiDispenseProperties,
@@ -23,7 +24,6 @@
     PositionReference,
     Coordinate,
 )
-
 from . import validation
 
 
@@ -778,12 +778,20 @@ def build_multi_dispense_properties(
 
 
 def build_transfer_properties(
-    by_tip_type_setting: SharedByTipTypeSetting,
+    transfer_properties: Union[SharedDataTransferProperties, SharedByTipTypeSetting],
 ) -> TransferProperties:
+    if isinstance(transfer_properties, SharedByTipTypeSetting):
+        _transfer_properties = SharedDataTransferProperties(
+            aspirate=transfer_properties.aspirate,
+            singleDispense=transfer_properties.singleDispense,
+            multiDispense=transfer_properties.multiDispense,
+        )
+    else:
+        _transfer_properties = transfer_properties
     return TransferProperties(
-        _aspirate=build_aspirate_properties(by_tip_type_setting.aspirate),
-        _dispense=build_single_dispense_properties(by_tip_type_setting.singleDispense),
+        _aspirate=build_aspirate_properties(_transfer_properties.aspirate),
+        _dispense=build_single_dispense_properties(_transfer_properties.singleDispense),
         _multi_dispense=build_multi_dispense_properties(
-            by_tip_type_setting.multiDispense
+            _transfer_properties.multiDispense
         ),
     )

api/src/opentrons/protocol_api/core/engine/protocol.py

@@ -4,10 +4,6 @@
 from typing import Dict, Optional, Type, Union, List, Tuple, TYPE_CHECKING
 
 from opentrons_shared_data.liquid_classes import LiquidClassDefinitionDoesNotExist
-
-from opentrons.protocol_engine import commands as cmd
-from opentrons.protocol_engine.commands import LoadModuleResult
-
 from opentrons_shared_data.deck.types import DeckDefinitionV5, SlotDefV3
 from opentrons_shared_data.labware.labware_definition import (
     labware_definition_type_adapter,
@@ -35,7 +31,8 @@
 from opentrons.protocols.api_support.util import AxisMaxSpeeds
 from opentrons.protocols.api_support.types import APIVersion
 
-
+from opentrons.protocol_engine import commands as cmd
+from opentrons.protocol_engine.commands import LoadModuleResult
 from opentrons.protocol_engine import (
     DeckSlotLocation,
     AddressableAreaLocation,
@@ -1071,7 +1068,7 @@ def define_liquid(
             display_color=(liquid.displayColor.root if liquid.displayColor else None),
         )
 
-    def define_liquid_class(self, name: str, version: int = 1) -> LiquidClass:
+    def define_liquid_class(self, name: str, version: int) -> LiquidClass:
         """Define a liquid class for use in transfer functions."""
         try:
             # Check if we have already loaded this liquid class' definition

api/src/opentrons/protocol_api/core/legacy/legacy_protocol_core.py

@@ -599,7 +599,7 @@ def define_liquid(
         """Define a liquid to load into a well."""
         assert False, "define_liquid only supported on engine core"
 
-    def define_liquid_class(self, name: str) -> LiquidClass:
+    def define_liquid_class(self, name: str, version: int) -> LiquidClass:
         """Define a liquid class."""
         assert False, "define_liquid_class is only supported on engine core"
 

api/src/opentrons/protocol_api/core/protocol.py

@@ -297,7 +297,7 @@ def define_liquid(
         """Define a liquid to load into a well."""
 
     @abstractmethod
-    def define_liquid_class(self, name: str) -> LiquidClass:
+    def define_liquid_class(self, name: str, version: int) -> LiquidClass:
         """Define a liquid class for use in transfer functions."""
 
     @abstractmethod

api/src/opentrons/protocol_api/protocol_context.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+from copy import deepcopy
 from typing import (
     Callable,
     Dict,
@@ -13,6 +14,11 @@
 )
 
 from opentrons_shared_data.labware.types import LabwareDefinition
+from opentrons_shared_data.liquid_classes.liquid_class_definition import (
+    TransferProperties as SharedTransferProperties,
+)
+from opentrons_shared_data.liquid_classes import DEFAULT_LC_VERSION, definition_exists
+from opentrons_shared_data.liquid_classes.types import TransferPropertiesDict
 from opentrons_shared_data.pipette.types import PipetteNameType
 
 from opentrons.types import Mount, Location, DeckLocation, DeckSlotName, StagingSlotName
@@ -48,6 +54,7 @@
 )
 from opentrons_shared_data.errors.exceptions import CommandPreconditionViolated
 from opentrons.protocol_engine.errors import LabwareMovementNotAllowedError
+from ._liquid_properties import build_transfer_properties
 
 from ._types import OffDeckType
 from .core.common import ModuleCore, LabwareCore, ProtocolCore
@@ -1376,7 +1383,67 @@ def define_liquid_class(
 
         :meta private:
         """
-        return self._core.define_liquid_class(name=name)
+        return self._core.define_liquid_class(name=name, version=DEFAULT_LC_VERSION)
+
+    @requires_version(2, 24)
+    def define_custom_liquid_class(
+        self,
+        name: str,
+        properties: Dict[str, Dict[str, TransferPropertiesDict]],
+        base_liquid_class: Optional[LiquidClass] = None,
+        display_name: Optional[str] = None,
+    ) -> LiquidClass:
+        """Define a custom liquid class, either a completely new one or based on an existing one.
+
+        Args:
+            name: The name to give to the new liquid class. Cannot use names of existing in-built liquid classes.
+            properties: A dict of transfer properties per tip per pipette.
+                Accepts a nested dictionary in the following format:
+
+                .. code-block:: python
+
+                    {
+                    <pipette_name>: {
+                        <tiprack_uri>: <properties in the shape of TransferPropertiesDict>
+
+                        # TransferPropertiesDict is a dictionary representation of the
+                        # transfer properties returned by the `LiquidClass.get_for(..)` function.
+                    }}
+
+            base_liquid_class: A LiquidClass to base this liquid class on. The properties
+                specified in transfer_properties will override any existing ones
+                for the specified pipettes & tips.
+            display_name: An optional human-readable name for the liquid. If not provided,
+                will default to title-cased name.
+
+        """
+        if definition_exists(name, DEFAULT_LC_VERSION):
+            raise ValueError(
+                f"Liquid class named {name} already exists. Please specify a different name."
+            )
+        new_liquid_class: LiquidClass
+        if base_liquid_class:
+            # If base liquid is provided, copy to new class
+            # and replace the entries mentioned in transfer props arg
+            new_liquid_class = deepcopy(base_liquid_class)
+        else:
+            new_liquid_class = LiquidClass.create_from(
+                name=name,
+                display_name=display_name or name.title(),
+                by_pipette_setting={},
+            )
+        for pipette, by_tiprack_props in properties.items():
+            for tiprack, transfer_props in by_tiprack_props.items():
+                new_liquid_class.update_for(
+                    pipette=pipette,
+                    tip_rack=tiprack,
+                    transfer_properties=build_transfer_properties(
+                        transfer_properties=SharedTransferProperties.model_validate(
+                            transfer_props
+                        )
+                    ),
+                )
+        return new_liquid_class
 
     @property
     @requires_version(2, 5)

api/src/opentrons/protocol_engine/commands/generate_command_schema.py

@@ -11,7 +11,7 @@
 
 def generate_command_schema(version: str) -> str:
     """Generate a JSON Schema that all valid create commands can validate against."""
-    schema_as_dict = CommandCreateAdapter.json_schema(mode="validation")
+    schema_as_dict = CommandCreateAdapter.json_schema(mode="validation", by_alias=False)
     schema_as_dict["$id"] = f"opentronsCommandSchemaV{version}"
     schema_as_dict["$schema"] = "http://json-schema.org/draft-07/schema#"
     return json.dumps(schema_as_dict, indent=2, sort_keys=True)