feat(robot-server): add runtime parameter definitions to run summary (#…

…14866)

Adds the runtime parameter definitions to the run summary for both current and non current runs, accessible via the GET /runs and /runs/{run_id} endpoints.

robot-server/robot_server/persistence/_migrations/v3_to_v4.py

@@ -3,6 +3,7 @@
 Summary of changes from schema 3:
 
 - Adds a new "run_time_parameter_values_and_defaults" column to analysis table
+- Adds a new "run_time_parameters" column to run table
 """
 
 from pathlib import Path
@@ -50,3 +51,8 @@ def add_column(
                 schema_4.analysis_table.name,
                 schema_4.analysis_table.c.run_time_parameter_values_and_defaults,
             )
+            add_column(
+                dest_engine,
+                schema_4.run_table.name,
+                schema_4.run_table.c.run_time_parameters,
+            )

robot-server/robot_server/persistence/pydantic.py

@@ -1,7 +1,8 @@
 """Store Pydantic objects in the SQL database."""
 
-from typing import Type, TypeVar
-from pydantic import BaseModel, parse_raw_as
+import json
+from typing import Type, TypeVar, List, Sequence
+from pydantic import BaseModel, parse_raw_as, parse_obj_as
 
 
 _BaseModelT = TypeVar("_BaseModelT", bound=BaseModel)
@@ -17,6 +18,16 @@ def pydantic_to_json(obj: BaseModel) -> str:
     )
 
 
-def json_to_pydantic(model: Type[_BaseModelT], json: str) -> _BaseModelT:
+def pydantic_list_to_json(obj_list: Sequence[BaseModel]) -> str:
+    """Serialize a list of Pydantic objects for storing in the SQL database."""
+    return json.dumps([obj.dict(by_alias=True, exclude_none=True) for obj in obj_list])
+
+
+def json_to_pydantic(model: Type[_BaseModelT], json_str: str) -> _BaseModelT:
     """Parse a Pydantic object stored in the SQL database."""
-    return parse_raw_as(model, json)
+    return parse_raw_as(model, json_str)
+
+
+def json_to_pydantic_list(model: Type[_BaseModelT], json_str: str) -> List[_BaseModelT]:
+    """Parse a list of Pydantic objects stored in the SQL database."""
+    return [parse_obj_as(model, obj_dict) for obj_dict in json.loads(json_str)]

robot-server/robot_server/persistence/tables/schema_4.py

@@ -85,6 +85,13 @@
     sqlalchemy.Column("engine_status", sqlalchemy.String, nullable=True),
     # column added in schema v1
     sqlalchemy.Column("_updated_at", UTCDateTime, nullable=True),
+    # column added in schema v4
+    sqlalchemy.Column(
+        "run_time_parameters",
+        # Stores a JSON string. See RunStore.
+        sqlalchemy.String,
+        nullable=True,
+    ),
 )
 
 action_table = sqlalchemy.Table(

robot-server/robot_server/runs/run_controller.py

@@ -106,4 +106,5 @@ async def _run_protocol_and_insert_result(
             run_id=self._run_id,
             summary=result.state_summary,
             commands=result.commands,
+            run_time_parameters=result.parameters,
         )

robot-server/robot_server/runs/run_data_manager.py

@@ -22,13 +22,14 @@
 from .run_store import RunResource, RunStore, BadRunResource, BadStateSummary
 from .run_models import Run, BadRun, RunDataError
 
-from opentrons.protocol_engine.types import DeckConfigurationType
+from opentrons.protocol_engine.types import DeckConfigurationType, RunTimeParameter
 
 
 def _build_run(
     run_resource: Union[RunResource, BadRunResource],
     state_summary: Union[StateSummary, BadStateSummary],
     current: bool,
+    run_time_parameters: List[RunTimeParameter],
 ) -> Union[Run, BadRun]:
     # TODO(mc, 2022-05-16): improve persistence strategy
     # such that this default summary object is not needed
@@ -49,6 +50,7 @@ def _build_run(
             completedAt=state_summary.completedAt,
             startedAt=state_summary.startedAt,
             liquids=state_summary.liquids,
+            runTimeParameters=run_time_parameters,
         )
 
     errors: List[EnumeratedError] = []
@@ -102,6 +104,7 @@ def _build_run(
         completedAt=state.completedAt,
         startedAt=state.startedAt,
         liquids=state.liquids,
+        runTimeParameters=run_time_parameters,
     )
 
 
@@ -172,6 +175,7 @@ async def create(
                 run_id=prev_run_id,
                 summary=prev_run_result.state_summary,
                 commands=prev_run_result.commands,
+                run_time_parameters=prev_run_result.parameters,
             )
         state_summary = await self._engine_store.create(
             run_id=run_id,
@@ -196,6 +200,7 @@ async def create(
             run_resource=run_resource,
             state_summary=state_summary,
             current=True,
+            run_time_parameters=[],
         )
 
     def get(self, run_id: str) -> Union[Run, BadRun]:
@@ -215,9 +220,10 @@ def get(self, run_id: str) -> Union[Run, BadRun]:
         """
         run_resource = self._run_store.get(run_id=run_id)
         state_summary = self._get_state_summary(run_id=run_id)
+        parameters = self._get_run_time_parameters(run_id=run_id)
         current = run_id == self._engine_store.current_run_id
 
-        return _build_run(run_resource, state_summary, current)
+        return _build_run(run_resource, state_summary, current, parameters)
 
     def get_run_loaded_labware_definitions(
         self, run_id: str
@@ -260,6 +266,7 @@ def get_all(self, length: Optional[int]) -> List[Union[Run, BadRun]]:
                 run_resource=run_resource,
                 state_summary=self._get_state_summary(run_resource.run_id),
                 current=run_resource.run_id == self._engine_store.current_run_id,
+                run_time_parameters=self._get_run_time_parameters(run_resource.run_id),
             )
             for run_resource in self._run_store.get_all(length)
         ]
@@ -310,15 +317,18 @@ async def update(self, run_id: str, current: Optional[bool]) -> Union[Run, BadRu
                 run_id=run_id,
                 summary=state_summary,
                 commands=commands,
+                run_time_parameters=parameters,
             )
         else:
             state_summary = self._engine_store.engine.state_view.get_summary()
+            parameters = self._engine_store.runner.run_time_parameters
             run_resource = self._run_store.get(run_id=run_id)
 
         return _build_run(
             run_resource=run_resource,
             state_summary=state_summary,
             current=next_current,
+            run_time_parameters=parameters,
         )
 
     def get_commands_slice(
@@ -385,3 +395,9 @@ def _get_state_summary(self, run_id: str) -> Union[StateSummary, BadStateSummary
     def _get_good_state_summary(self, run_id: str) -> Optional[StateSummary]:
         summary = self._get_state_summary(run_id)
         return summary if isinstance(summary, StateSummary) else None
+
+    def _get_run_time_parameters(self, run_id: str) -> List[RunTimeParameter]:
+        if run_id == self._engine_store.current_run_id:
+            return self._engine_store.runner.run_time_parameters
+        else:
+            return self._run_store.get_run_time_parameters(run_id=run_id)

robot-server/robot_server/runs/run_models.py

@@ -18,7 +18,7 @@
     Liquid,
     CommandNote,
 )
-from opentrons.protocol_engine.types import RunTimeParamValuesType
+from opentrons.protocol_engine.types import RunTimeParameter, RunTimeParamValuesType
 from opentrons_shared_data.errors import GeneralError
 from robot_server.service.json_api import ResourceModel
 from robot_server.errors.error_responses import ErrorDetails
@@ -121,6 +121,15 @@ class Run(ResourceModel):
         ...,
         description="Labware offsets to apply as labware are loaded.",
     )
+    runTimeParameters: List[RunTimeParameter] = Field(
+        default_factory=list,
+        description=(
+            "Run time parameters used during the run."
+            " These are the parameters that are defined in the protocol, with values"
+            " specified either in the run creation request or default values from the protocol"
+            " if none are specified in the request."
+        ),
+    )
     protocolId: Optional[str] = Field(
         None,
         description=(
@@ -185,6 +194,15 @@ class BadRun(ResourceModel):
         ...,
         description="Labware offsets to apply as labware are loaded.",
     )
+    runTimeParameters: List[RunTimeParameter] = Field(
+        default_factory=list,
+        description=(
+            "Run time parameters used during the run."
+            " These are the parameters that are defined in the protocol, with values"
+            " specified either in the run creation request or default values from the protocol"
+            " if none are specified in the request."
+        ),
+    )
     protocolId: Optional[str] = Field(
         None,
         description=(

robot-server/robot_server/runs/run_store.py

@@ -12,6 +12,7 @@
 from opentrons.util.helpers import utc_now
 from opentrons.protocol_engine import StateSummary, CommandSlice
 from opentrons.protocol_engine.commands import Command
+from opentrons.protocol_engine.types import RunTimeParameter
 
 from opentrons_shared_data.errors.exceptions import (
     EnumeratedError,
@@ -25,7 +26,12 @@
     run_command_table,
     action_table,
 )
-from robot_server.persistence.pydantic import json_to_pydantic, pydantic_to_json
+from robot_server.persistence.pydantic import (
+    json_to_pydantic,
+    pydantic_to_json,
+    json_to_pydantic_list,
+    pydantic_list_to_json,
+)
 from robot_server.protocols.protocol_store import ProtocolNotFoundError
 
 from .action_models import RunAction, RunActionType
@@ -102,13 +108,15 @@ def update_run_state(
         run_id: str,
         summary: StateSummary,
         commands: List[Command],
+        run_time_parameters: List[RunTimeParameter],
     ) -> RunResource:
         """Update the run's state summary and commands list.
 
         Args:
             run_id: The run to update
             summary: The run's equipment and status summary.
             commands: The run's commands.
+            run_time_parameters: The run's run time parameters, if any.
 
         Returns:
             The run resource.
@@ -124,6 +132,7 @@ def update_run_state(
                     run_id=run_id,
                     state_summary=summary,
                     engine_status=summary.status,
+                    run_time_parameters=run_time_parameters,
                 )
             )
         )
@@ -346,6 +355,33 @@ def get_state_summary(self, run_id: str) -> Union[StateSummary, BadStateSummary]
                 )
             )
 
+    @lru_cache(maxsize=_CACHE_ENTRIES)
+    def get_run_time_parameters(self, run_id: str) -> List[RunTimeParameter]:
+        """Get the archived run time parameters.
+
+        This is a list of the run's parameter definitions (if any),
+        including the values used in the run itself, along with the default value,
+        constraints and associated names and descriptions.
+        """
+        select_run_data = sqlalchemy.select(run_table.c.run_time_parameters).where(
+            run_table.c.id == run_id
+        )
+
+        with self._sql_engine.begin() as transaction:
+            row = transaction.execute(select_run_data).one()
+
+        try:
+            return (
+                json_to_pydantic_list(RunTimeParameter, row.run_time_parameters)  # type: ignore[arg-type]
+                if row.run_time_parameters is not None
+                else []
+            )
+        except ValidationError:
+            log.warning(
+                f"Error retrieving run time parameters for {run_id}", exc_info=True
+            )
+            return []
+
     def get_commands_slice(
         self,
         run_id: str,
@@ -476,6 +512,7 @@ def _clear_caches(self) -> None:
         self.get_all.cache_clear()
         self.get_state_summary.cache_clear()
         self.get_command.cache_clear()
+        self.get_run_time_parameters.cache_clear()
 
 
 # The columns that must be present in a row passed to _convert_row_to_run().
@@ -552,9 +589,11 @@ def _convert_state_to_sql_values(
     run_id: str,
     state_summary: StateSummary,
     engine_status: str,
+    run_time_parameters: List[RunTimeParameter],
 ) -> Dict[str, object]:
     return {
         "state_summary": pydantic_to_json(state_summary),
         "engine_status": engine_status,
         "_updated_at": utc_now(),
+        "run_time_parameters": pydantic_list_to_json(run_time_parameters),
     }

robot-server/tests/integration/http_api/runs/test_json_v6_protocol_run.tavern.yaml

@@ -50,6 +50,7 @@ stages:
               displayName: Water
               description: Liquid H2O
               displayColor: '#7332a8'
+          runTimeParameters: []
           protocolId: '{protocol_id}'
 
   - name: Execute a setup command

robot-server/tests/integration/http_api/runs/test_json_v7_protocol_run.tavern.yaml

@@ -45,6 +45,7 @@ stages:
               definitionUri: opentrons/opentrons_1_trash_1100ml_fixed/1
               location: !anydict
           labwareOffsets: []
+          runTimeParameters: []
           liquids:
             - id: waterId
               displayName: Water

robot-server/tests/integration/http_api/runs/test_protocol_run.tavern.yaml

@@ -42,6 +42,7 @@ stages:
               definitionUri: opentrons/opentrons_1_trash_1100ml_fixed/1
               location: !anydict
           labwareOffsets: []
+          runTimeParameters: []
           protocolId: '{protocol_id}'
           liquids: []
       save:
@@ -237,6 +238,7 @@ stages:
           createdAt: !re_search "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d+\\+\\d{2}:\\d{2}$"
           startedAt: !re_search "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d+\\+\\d{2}:\\d{2}$"
           liquids: []
+          runTimeParameters: []
           completedAt: !re_search "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d+\\+\\d{2}:\\d{2}$"
           errors: []
           pipettes: []

robot-server/tests/integration/http_api/runs/test_run_queued_protocol_commands.tavern.yaml

@@ -94,6 +94,7 @@ stages:
           labware: []
           labwareOffsets: []
           liquids: []
+          runTimeParameters: []
           modules: []
           pipettes: []
           status: 'idle'