sapiopycommons 2025.2.25a448__tar.gz → 2025.2.25a450__tar.gz

{sapiopycommons-2025.2.25a448 → sapiopycommons-2025.2.25a450}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.2.25a448
+Version: 2025.2.25a450
 Summary: Official Sapio Python API Utilities Package
 Project-URL: Homepage, https://github.com/sapiosciences
 Author-email: Jonathan Steck <jsteck@sapiosciences.com>, Yechen Qiao <yqiao@sapiosciences.com>

{sapiopycommons-2025.2.25a448 → sapiopycommons-2025.2.25a450}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sapiopycommons"
-version='2025.02.25a448'
+version='2025.02.25a450'
 authors = [
     { name="Jonathan Steck", email="jsteck@sapiosciences.com" },
     { name="Yechen Qiao", email="yqiao@sapiosciences.com" },

{sapiopycommons-2025.2.25a448 → sapiopycommons-2025.2.25a450}/src/sapiopycommons/ai/tool_of_tools.py

@@ -2,19 +2,20 @@ import base64
 import io
 import math
 import re
-from typing import Final, Mapping, Any, cast
+from typing import Final, Mapping, Any
 
 import requests
 from pandas import DataFrame
 from requests import Response
+from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.DataRecordManagerService import DataRecordManager
 from sapiopylib.rest.DataTypeService import DataTypeManager
 from sapiopylib.rest.ELNService import ElnManager
 from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.pojo.DataRecord import DataRecord
 from sapiopylib.rest.pojo.Sort import SortDirection
-from sapiopylib.rest.pojo.chartdata.DashboardDefinition import GaugeChartDefinition
-from sapiopylib.rest.pojo.chartdata.DashboardEnums import ChartGroupingType, ChartOperationType
+from sapiopylib.rest.pojo.chartdata.DashboardDefinition import GaugeChartDefinition, DashboardDefinition
+from sapiopylib.rest.pojo.chartdata.DashboardEnums import ChartGroupingType, ChartOperationType, DashboardScope
 from sapiopylib.rest.pojo.chartdata.DashboardSeries import GaugeChartSeries
 from sapiopylib.rest.pojo.datatype.DataType import DataTypeDefinition
 from sapiopylib.rest.pojo.datatype.DataTypeLayout import DataTypeLayout, TableLayout
@@ -24,7 +25,7 @@ from sapiopylib.rest.pojo.eln.ElnEntryPosition import ElnEntryPosition
 from sapiopylib.rest.pojo.eln.ElnExperiment import ElnExperiment
 from sapiopylib.rest.pojo.eln.ExperimentEntry import ExperimentEntry
 from sapiopylib.rest.pojo.eln.ExperimentEntryCriteria import ElnEntryCriteria, ElnFormEntryUpdateCriteria, \
-    ElnDashboardEntryUpdateCriteria, ElnTextEntryUpdateCriteria
+    ElnDashboardEntryUpdateCriteria
 from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnEntryType, ElnBaseDataType
 from sapiopylib.rest.pojo.eln.eln_headings import ElnExperimentTabAddCriteria, ElnExperimentTab
 from sapiopylib.rest.pojo.eln.field_set import ElnFieldSetInfo
@@ -325,57 +326,48 @@ class AiHelper:
         if not json_list:
             return None
 
-        def init_string_field(k: str, v: Any, n: str) -> VeloxStringFieldDefinition:
+        def update_string_field(f: AbstractVeloxFieldDefinition, v: Any) -> None:
             """
-            Initialize a string field.
+            Update the max length of the string field and whether it is a link-out field depending on the length and
+            form of the given value.
 
-            :param k: The JSON key that the field value is being pulled from. Doubles as the display name.
-            :param v: A particular value of the field.
-            :param n: The unique name of the field.
+            :param f: The definition of the string field.
+            :param v: A field value that will be present for this field.
             """
-            link_out: dict[str, str] = {}
-            if isinstance(v, str):
-	            if v.startswith("https://") or v.startswith("http://"):
-	                link_out["Link"] = "[[LINK_OUT]]"
-            return fb.string_field(n, display_name=k, link_out=link_out)
-
-        def update_field_length(k: str, v: Any, lengths: dict[str, int]) -> None:
-            """
-            Update the max length of a string field.
-
-            :param k: The JSON key that the field value is being pulled from.
-            :param v: The field value.
-            :param lengths: The dictionary of field lengths.
-            """
-            lengths[k] = max(lengths.get(k, 100), len(str(v)) if v is not None else 0)
+            if not isinstance(f, VeloxStringFieldDefinition) or v is None:
+                return
+            sv = str(v)
+            f.max_length = max(f.max_length, len(sv))
+            if not f.link_out and sv.startswith("http://") or sv.startswith("https://"):
+                link_out, link_out_url = FieldBuilder._convert_link_out({"Link": "[[LINK_OUT]]"})
+                f.link_out = link_out
+                f.link_out_url = link_out_url
 
         # Determine which fields in the JSON can be used to create field definitions.
         fb = FieldBuilder()
         json_key_to_field_def: dict[str, AbstractVeloxFieldDefinition] = {}
-        json_key_to_field_name: dict[str, str] = {}
-        json_key_to_string_length: dict[str, int] = {}
         numeric_string_fields: set[str] = set()
         for values in json_list:
             for key, value in values.items():
-                # The field name is the JSON key name, but with spaces and dashes replaced by underscores and with a leading
-                # underscore added if the field name starts with a number.
-                if key not in json_key_to_field_name:
-                    field_name: str = key.strip()
-                    if " " in field_name:
-                        field_name = field_name.replace(" ", "_")
-                    if "-" in field_name:
-                        field_name = field_name.replace("-", "_")
-                    if field_name[0].isnumeric():
-                        field_name = "_" + field_name
-                    json_key_to_field_name[key] = field_name
-                else:
-                    field_name = json_key_to_field_name[key]
+                # Skip null values, since we can't know what type they're meant to represent.
+                if value is None:
+                    continue
+
+                # The field name is the JSON key name, but with spaces and dashes replaced by underscores and with a
+                # leading underscore added if the field name starts with a number.
+                field_name: str = key.strip()
+                if " " in field_name:
+                    field_name = field_name.replace(" ", "_")
+                if "-" in field_name:
+                    field_name = field_name.replace("-", "_")
+                if field_name[0].isnumeric():
+                    field_name = "_" + field_name
 
                 # If this is the first time this key is being encountered, create a field for it.
                 if key not in json_key_to_field_def:
                     if isinstance(value, str):
-                        json_key_to_field_def[key] = init_string_field(key, value, field_name)
-                        update_field_length(key, value, json_key_to_string_length)
+                        json_key_to_field_def[key] = fb.string_field(field_name, display_name=key)
+                        update_string_field(json_key_to_field_def[key], value)
                     elif isinstance(value, bool):
                         json_key_to_field_def[key] = fb.boolean_field(field_name, display_name=key)
                     elif isinstance(value, (int, float)):
@@ -388,25 +380,21 @@ class AiHelper:
                 # Strings can be anything, so we don't need to check the value type.
                 if field_type == FieldType.STRING:
                     # We still need to make sure the lengths are fine.
-                    update_field_length(key, value, json_key_to_string_length)
+                    update_string_field(json_key_to_field_def[key], value)
                     continue
                 # Boolean values can only be booleans.
                 if field_type == FieldType.BOOLEAN and isinstance(value, bool):
                     continue
                 # Integers and floats both fit in DOUBLE fields, but floats can't be NaN or infinity.
-                if field_type == FieldType.DOUBLE and not isinstance(value, bool):
-                    if isinstance(value, int):
+                if field_type == FieldType.DOUBLE:
+                    # Booleans count as ints for isinstance, so make sure that true integers continue but bools don't.
+                    if isinstance(value, int) and not isinstance(value, bool):
                         continue
                     if isinstance(value, float) and not math.isnan(value) and not math.isinf(value):
                         continue
                     numeric_string_fields.add(key)
-                json_key_to_field_def[key] = init_string_field(key, value, field_name)
-                update_field_length(key, value, json_key_to_string_length)
-
-        # Update the max length of each string field.
-        for key, value in json_key_to_string_length.items():
-            field = cast(VeloxStringFieldDefinition, json_key_to_field_def[key])
-            field.max_length = value
+                json_key_to_field_def[key] = fb.string_field(field_name, display_name=key)
+                update_string_field(json_key_to_field_def[key], value)
 
         # Sort the JSON list if requested.
         if sort_field and sort_direction != SortDirection.NONE:
@@ -428,7 +416,7 @@ class AiHelper:
             field_map: dict[str, Any] = {}
             for key, field in json_key_to_field_def.items():
                 val: Any = json_dict.get(key)
-                if key in numeric_string_fields and val is not None and not isinstance(val, str):
+                if key in numeric_string_fields and val is not None and isinstance(val, (int, float)):
                     val: str = f"{val:.3f}"
                 field_map[field.data_field_name] = val
             field_maps.append(field_map)
@@ -738,26 +726,21 @@ class ToolOfToolsHelper:
         # tool started and format the description so that the text isn't too small to read.
         # TODO: Get the UTC offset in seconds from the header once that's being sent.
         now: str = TimeUtil.now_in_format("%Y-%m-%d %H:%M:%S UTC", "UTC")
-        text_entry = ElnEntryStep(self.helper.protocol, self.helper.create_text_entry(self.tab, now, self.description))
+        description: str = f"<p>{HtmlFormatter.timestamp(now)}<br>{HtmlFormatter.body(self.description)}</p>"
+        text_entry: ElnEntryStep = _ELNStepFactory.create_text_entry(self.helper.protocol, description,
+                                                                     column_order=0, column_span=2)
         self.description_entry = text_entry
         self.description_record = text_entry.get_records()[0]
 
-        # Shrink the text entry by one column.
-        text_update_crit = ElnTextEntryUpdateCriteria()
-        text_update_crit.column_order = 0
-        text_update_crit.column_span = 2
-        self.eln_man.update_experiment_entry(self.exp_id, self.description_entry.get_id(), text_update_crit)
-
         # Create a gauge entry to display the progress.
-        gauge_entry: ElnEntryStep = self._create_gauge_chart(self.helper.protocol, progress_entry,
-                                                             f"{self.name} Progress", "Progress", "StatusMsg")
+        gauge_entry: ElnEntryStep = _ELNStepFactory._create_gauge_chart(self.helper.protocol, progress_entry,
+                                                                        f"{self.name} Progress", "Progress", "StatusMsg",
+                                                                        column_order=2, column_span=2)
         self.progress_gauge_entry = gauge_entry
 
         # Make sure the gauge entry isn't too big and stick it to the right of the text entry.
         dash_update_crit = ElnDashboardEntryUpdateCriteria()
         dash_update_crit.entry_height = 250
-        dash_update_crit.column_order = 2
-        dash_update_crit.column_span = 2
         self.eln_man.update_experiment_entry(self.exp_id, self.progress_gauge_entry.get_id(), dash_update_crit)
 
         # Create a results entry if this tool produces result records.
@@ -852,10 +835,37 @@ class ToolOfToolsHelper:
 
         return self.helper.create_attachment_entry_from_file(self.tab, entry_name, file_path)
 
+
+class _ELNStepFactory:
+    """
+    Factory that provides simple functions to create a new ELN step under an ELN protocol.
+    """
+    @staticmethod
+    def create_text_entry(protocol: ElnExperimentProtocol, text_data: str,
+                          position: ElnEntryPosition | None = None, **kwargs) -> ElnEntryStep:
+        """
+        Create a text entry at the end of the protocol, with a initial text specified in the text entry.
+        :param protocol: The protocol to create a new step for.
+        :param text_data: Must be non-blank. This is what will be displayed. Some HTML format tags can be inserted.
+        :param position: The position of the new step. If not specified, the new step will be added at the end.
+        :return: The new text entry step.
+        """
+        eln_manager, new_entry = _ELNStepFactory._get_entry_creation_criteria(ElnBaseDataType.TEXT_ENTRY_DETAIL.data_type_name,
+                                                                              protocol, 'Text Entry', ElnEntryType.Text,
+                                                                              position, **kwargs)
+        record = eln_manager.get_data_records_for_entry(protocol.eln_experiment.notebook_experiment_id,
+                                                        new_entry.entry_id).result_list[0]
+        record.set_field_value(ElnBaseDataType.get_text_entry_data_field_name(), text_data)
+        DataMgmtServer.get_data_record_manager(protocol.user).commit_data_records([record])
+        ret = ElnEntryStep(protocol, new_entry)
+        protocol.invalidate()
+        return ret
+
     # TODO: Remove this once pylib's gauge chart definition is up to date.
     @staticmethod
     def _create_gauge_chart(protocol: ElnExperimentProtocol, data_source_step: ElnEntryStep, step_name: str,
-                            field_name: str, status_field: str, group_by_field_name: str = "DataRecordName") \
+                            field_name: str, status_field: str, group_by_field_name: str = "DataRecordName",
+                            **kwargs) \
             -> ElnEntryStep:
         """
         Create a gauge chart step in the experiment protocol.
@@ -874,11 +884,55 @@ class ToolOfToolsHelper:
         chart.grouping_type = ChartGroupingType.GROUP_BY_FIELD
         chart.grouping_type_data_type_name = data_type_name
         chart.grouping_type_data_field_name = group_by_field_name
-        dashboard, step = ELNStepFactory._create_dashboard_step_from_chart(chart, data_source_step, protocol, step_name,
-                                                                           None)
+        dashboard, step = _ELNStepFactory._create_dashboard_step_from_chart(chart, data_source_step, protocol, step_name,
+                                                                            None, **kwargs)
         protocol.invalidate()
         return step
 
+    @staticmethod
+    def _create_dashboard_step_from_chart(chart: GaugeChartDefinition, data_source_step: ElnEntryStep,
+                                          protocol: ElnExperimentProtocol, step_name: str,
+                                          position: ElnEntryPosition | None = None, **kwargs) -> \
+            tuple[DashboardDefinition, ElnEntryStep]:
+        dashboard: DashboardDefinition = DashboardDefinition()
+        dashboard.chart_definition_list = [chart]
+        dashboard.dashboard_scope = DashboardScope.PRIVATE_ELN
+        dashboard = DataMgmtServer.get_dashboard_manager(protocol.user).store_dashboard_definition(dashboard)
+        eln_manager, new_entry = _ELNStepFactory._get_entry_creation_criteria("", protocol, step_name,
+                                                                              ElnEntryType.Dashboard, position,
+                                                                              **kwargs)
+        # noinspection PyTypeChecker
+        update_criteria = ElnDashboardEntryUpdateCriteria()
+        update_criteria.dashboard_guid = dashboard.dashboard_guid
+        update_criteria.data_source_entry_id = data_source_step.get_id()
+        update_criteria.entry_height = 500
+        eln_manager.update_experiment_entry(protocol.eln_experiment.notebook_experiment_id, new_entry.entry_id,
+                                            update_criteria)
+        step = ElnEntryStep(protocol, new_entry)
+        return dashboard, step
+
+    @staticmethod
+    def _get_entry_creation_criteria(data_type_name: str | None, protocol: ElnExperimentProtocol,
+                                     step_name: str, entry_type: ElnEntryType, position: ElnEntryPosition | None = None,
+                                     **kwargs):
+        tab_id: int | None = None
+        order: int | None = None
+        if position:
+            tab_id = position.tab_id
+            order = position.order
+        # noinspection PyTypeChecker
+        last_step: ElnEntryStep = protocol.get_sorted_step_list()[-1]
+        if tab_id is None:
+            tab_id = last_step.eln_entry.notebook_experiment_tab_id
+        if order is None:
+            order = last_step.eln_entry.order + 1
+        eln_manager = DataMgmtServer.get_eln_manager(protocol.user)
+        entry_criteria = ElnEntryCriteria(entry_type, step_name, data_type_name=data_type_name,
+                                          order=order, notebook_experiment_tab_id=tab_id, **kwargs)
+        new_entry: ExperimentEntry = eln_manager.add_experiment_entry(protocol.eln_experiment.notebook_experiment_id,
+                                                                      entry_criteria)
+        return eln_manager, new_entry
+
 
 # TODO: Using this to set the new status field setting.
 class _GaugeChartDefinition(GaugeChartDefinition):