sapiopycommons 2025.2.25a450__py3-none-any.whl → 2025.3.6a453__py3-none-any.whl

sapiopycommons/ai/tool_of_tools.py

@@ -1,7 +1,6 @@
 import base64
 import io
 import math
-import re
 from typing import Final, Mapping, Any
 
 import requests
@@ -26,7 +25,7 @@ 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
-from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnEntryType, ElnBaseDataType
+from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnEntryType, ElnBaseDataType, ExperimentEntryStatus
 from sapiopylib.rest.pojo.eln.eln_headings import ElnExperimentTabAddCriteria, ElnExperimentTab
 from sapiopylib.rest.pojo.eln.field_set import ElnFieldSetInfo
 from sapiopylib.rest.utils.ProtocolUtils import ELNStepFactory
@@ -35,6 +34,7 @@ from sapiopylib.rest.utils.Protocols import ElnEntryStep, ElnExperimentProtocol
 from sapiopycommons.callbacks.field_builder import FieldBuilder
 from sapiopycommons.general.aliases import AliasUtil, SapioRecord
 from sapiopycommons.general.exceptions import SapioException
+from sapiopycommons.general.html_formatter import HtmlFormatter
 from sapiopycommons.general.time_util import TimeUtil
 from sapiopycommons.multimodal.multimodal import MultiModalManager
 from sapiopycommons.multimodal.multimodal_data import ImageDataRequestPojo
@@ -102,88 +102,6 @@ def format_tot_headers(headers: Mapping[str, str]) -> dict[str, str]:
     return {k.lower(): v for k, v in headers.items()}
 
 
-class HtmlFormatter:
-    """
-    A class for formatting text in HTML with tag classes supported by the client.
-    """
-    TIMESTAMP_TEXT__CSS_CLASS_NAME: Final[str] = "timestamp-text"
-    HEADER_1_TEXT__CSS_CLASS_NAME: Final[str] = "header1-text"
-    HEADER_2_TEXT__CSS_CLASS_NAME: Final[str] = "header2-text"
-    HEADER_3_TEXT__CSS_CLASS_NAME: Final[str] = "header3-text"
-    BODY_TEXT__CSS_CLASS_NAME: Final[str] = "body-text"
-    CAPTION_TEXT__CSS_CLASS_NAME: Final[str] = "caption-text"
-
-    @staticmethod
-    def timestamp(text: str) -> str:
-        """
-        Given a text string, return that same text string HTML formatted using the timestamp CSS class.
-
-        :param text: The text to format.
-        :return: The HTML formatted text.
-        """
-        return f"<span class=\"{HtmlFormatter.TIMESTAMP_TEXT__CSS_CLASS_NAME}\">{text}</span>"
-
-    @staticmethod
-    def header_1(text: str) -> str:
-        """
-        Given a text string, return that same text string HTML formatted using the header 1 CSS class.
-
-        :param text: The text to format.
-        :return: The HTML formatted text.
-        """
-        return f"<span class=\"{HtmlFormatter.HEADER_1_TEXT__CSS_CLASS_NAME}\">{text}</span>"
-
-    @staticmethod
-    def header_2(text: str) -> str:
-        """
-        Given a text string, return that same text string HTML formatted using the header 2 CSS class.
-
-        :param text: The text to format.
-        :return: The HTML formatted text.
-        """
-        return f"<span class=\"{HtmlFormatter.HEADER_2_TEXT__CSS_CLASS_NAME}\">{text}</span>"
-
-    @staticmethod
-    def header_3(text: str) -> str:
-        """
-        Given a text string, return that same text string HTML formatted using the header 3 CSS class.
-
-        :param text: The text to format.
-        :return: The HTML formatted text.
-        """
-        return f"<span class=\"{HtmlFormatter.HEADER_3_TEXT__CSS_CLASS_NAME}\">{text}</span>"
-
-    @staticmethod
-    def body(text: str) -> str:
-        """
-        Given a text string, return that same text string HTML formatted using the body CSS class.
-
-        :param text: The text to format.
-        :return: The HTML formatted text.
-        """
-        return f"<span class=\"{HtmlFormatter.BODY_TEXT__CSS_CLASS_NAME}\">{text}</span>"
-
-    @staticmethod
-    def caption(text: str) -> str:
-        """
-        Given a text string, return that same text string HTML formatted using the caption CSS class.
-
-        :param text: The text to format.
-        :return: The HTML formatted text.
-        """
-        return f"<span class=\"{HtmlFormatter.CAPTION_TEXT__CSS_CLASS_NAME}\">{text}</span>"
-
-    @staticmethod
-    def replace_newlines(text: str) -> str:
-        """
-        Given a text string, return that same text string HTML formatted with newlines replaced by HTML line breaks.
-
-        :param text: The text to format.
-        :return: The HTML formatted text.
-        """
-        return re.sub("\r?\n", "<br>", text)
-
-
 class AiHelper:
     """
     A class with helper methods for the AI to make use of when creating/updating experiment tabs and entries.
@@ -611,6 +529,8 @@ class ToolOfToolsHelper:
     # Stuff created by this helper.
     _initialized: bool
     """Whether a tab for this tool has been initialized."""
+    _new_tab: bool
+    """Whether a new tab was created for this tool."""
     tab: ElnExperimentTab
     """The tab that contains the tool's entries."""
     description_entry: ElnEntryStep | None
@@ -649,6 +569,15 @@ class ToolOfToolsHelper:
         self.eln_man = ElnManager(self.user)
 
         self._initialized = False
+        self._new_tab = False
+
+    @property
+    def is_initialized(self) -> bool:
+        return self._initialized
+
+    @property
+    def is_new_tab(self) -> bool:
+        return self._new_tab
 
     def initialize_tab(self) -> ElnExperimentTab:
         if self._initialized:
@@ -701,6 +630,7 @@ class ToolOfToolsHelper:
 
         # Otherwise, create the tab for the tool progress and results.
         self.tab = self.helper.create_tab(tab_name)
+        self._new_tab = True
 
         # Create a hidden entry for tracking the progress of the tool.
         field_sets: list[ElnFieldSetInfo] = self.eln_man.get_field_set_info_list()
@@ -708,16 +638,18 @@ class ToolOfToolsHelper:
                                                      x.field_set_name == "Tool of Tools Progress"]
         if not progress_field_set:
             raise SapioException("Unable to locate the field set for the Tool of Tools progress.")
-        progress_entry_crit = ElnEntryCriteria(ElnEntryType.Form, f"{tab_name} Progress",
-                                               ElnBaseDataType.EXPERIMENT_DETAIL.data_type_name, 1,
-                                               notebook_experiment_tab_id=self.tab.tab_id,
-                                               enb_field_set_id=progress_field_set[0].field_set_id)
+        progress_entry_crit = _ElnEntryCriteria(ElnEntryType.Form, f"{tab_name} Progress",
+                                                ElnBaseDataType.EXPERIMENT_DETAIL.data_type_name, 1,
+                                                notebook_experiment_tab_id=self.tab.tab_id,
+                                                enb_field_set_id=progress_field_set[0].field_set_id,
+                                                is_hidden=True)
         progress_entry = ElnEntryStep(self.helper.protocol,
                                       self.eln_man.add_experiment_entry(self.exp_id, progress_entry_crit))
         self.progress_entry = progress_entry
         self.progress_record = progress_entry.get_records()[0]
 
         # Hide the progress entry.
+        # TODO: Remove once we get this working on entry creation.
         form_update_crit = ElnFormEntryUpdateCriteria()
         form_update_crit.is_hidden = True
         self.eln_man.update_experiment_entry(self.exp_id, self.progress_entry.get_id(), form_update_crit)
@@ -735,10 +667,11 @@ class ToolOfToolsHelper:
         # Create a gauge entry to display the progress.
         gauge_entry: ElnEntryStep = _ELNStepFactory._create_gauge_chart(self.helper.protocol, progress_entry,
                                                                         f"{self.name} Progress", "Progress", "StatusMsg",
-                                                                        column_order=2, column_span=2)
+                                                                        column_order=2, column_span=2, entry_height=250)
         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.
+        # TODO: Remove once we get this working on entry creation.
         dash_update_crit = ElnDashboardEntryUpdateCriteria()
         dash_update_crit.entry_height = 250
         self.eln_man.update_experiment_entry(self.exp_id, self.progress_gauge_entry.get_id(), dash_update_crit)
@@ -927,8 +860,8 @@ class _ELNStepFactory:
         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)
+        entry_criteria = _ElnEntryCriteria(entry_type, step_name, data_type_name, 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
@@ -945,3 +878,40 @@ class _GaugeChartDefinition(GaugeChartDefinition):
             "dataFieldName": self.status_field
         }
         return result
+
+
+class _ElnEntryCriteria(ElnEntryCriteria):
+    is_hidden: bool | None
+    entry_height: int | None
+    description: str | None
+    is_initialization_required: bool | None
+    collapse_entry: bool | None
+    entry_status: ExperimentEntryStatus | None
+    template_item_fulfilled_timestamp: int | None
+
+    def __init__(self, entry_type: ElnEntryType, entry_name: str | None, data_type_name: str | None, order: int,
+                 is_hidden: bool | None = None, entry_height: int | None = None, description: str | None = None,
+                 is_initialization_required: bool | None = None, collapse_entry: bool | None = None,
+                 entry_status: ExperimentEntryStatus | None = None, template_item_fulfilled_timestamp: int | None = None,
+                 **kwargs):
+        super().__init__(entry_type, entry_name, data_type_name, order, **kwargs)
+        self.is_hidden = is_hidden
+        self.entry_height = entry_height
+        self.description = description
+        self.is_initialization_required = is_initialization_required
+        self.collapse_entry = collapse_entry
+        self.entry_status = entry_status
+        self.template_item_fulfilled_timestamp = template_item_fulfilled_timestamp
+
+    def to_json(self) -> dict[str, Any]:
+        ret: dict[str, Any] = super().to_json()
+        ret.update({
+            "hidden": self.is_hidden,
+            "entryHeight": self.entry_height,
+            "description": self.description,
+            "initializationRequired": self.is_initialization_required,
+            "collapsed": self.collapse_entry,
+            "entryStatus": self.entry_status,
+            "templateItemFulfilledTimestamp": self.template_item_fulfilled_timestamp
+        })
+        return ret

sapiopycommons/callbacks/callback_util.py

@@ -712,7 +712,7 @@ class CallbackUtil:
         if not records:
             raise SapioException("No records provided.")
         data_type: str = AliasUtil.to_singular_data_type_name(records)
-        field_map_list: list[FieldMap] = AliasUtil.to_field_map_lists(records)
+        field_map_list: list[FieldMap] = AliasUtil.to_field_map_list(records)
 
         # Convert the group_by parameter to a field name.
         if group_by is not None:
@@ -1192,7 +1192,7 @@ class CallbackUtil:
                 record: SapioRecord | FieldMap | None = row_records.get(field.data_type_name)
                 # This could be either a record, a field map, or null. Convert any records to field maps.
                 if not isinstance(record, dict) and record is not None:
-                    record: FieldMap | None = AliasUtil.to_field_map_lists([record])[0]
+                    record: FieldMap | None = AliasUtil.to_field_map(record)
 
                 # Find out if this field had its data type prepended to it. If this is the case, then we need to find
                 # the true data field name before retrieving the value from the field map.
@@ -1383,7 +1383,7 @@ class CallbackUtil:
         if not records:
             raise SapioException("No records provided.")
         data_type: str = AliasUtil.to_singular_data_type_name(records)
-        field_map_list: list[FieldMap] = AliasUtil.to_field_map_lists(records)
+        field_map_list: list[FieldMap] = AliasUtil.to_field_map_list(records, include_record_id=True)
 
         # Key fields display their columns in order before all non-key fields.
         # Unmark key fields so that the column order is respected exactly as the caller provides it.

sapiopycommons/customreport/auto_pagers.py

@@ -8,6 +8,7 @@ from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, CustomReport
 from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
 from sapiopylib.rest.utils.autopaging import SapioPyAutoPager, PagerResultCriteriaType, _default_report_page_size, \
     _default_record_page_size
+from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
 
 from sapiopycommons.general.aliases import FieldValue, UserIdentifier, AliasUtil, RecordModel
@@ -110,20 +111,20 @@ class QuickReportDictAutoPager(_DictReportPagerBase):
         super().__init__(user, first_page_criteria)
 
 
-class _RecordReportPagerBase(SapioPyAutoPager[CustomReportCriteria, WrappedType], ABC):
+class _RecordReportPagerBase(SapioPyAutoPager[CustomReportCriteria, RecordModel], ABC):
     """
     A base class for automatically paging through a report and returning the results as a list of records.
     """
     _columns: list[ReportColumn]
-    _wrapper: type[WrappedType]
+    _query_type: type[WrappedType] | str
     _data_type: str
     _rec_handler: RecordHandler
     _report_man: CustomReportManager
 
-    def __init__(self, user: UserIdentifier, first_page_criteria: CustomReportCriteria, wrapper_type: type[WrappedType]):
+    def __init__(self, user: UserIdentifier, first_page_criteria: CustomReportCriteria, wrapper_type: type[WrappedType] | str):
         self._columns = first_page_criteria.column_list
-        self._wrapper = wrapper_type
-        self._data_type = wrapper_type.get_wrapper_data_type_name()
+        self._query_type = wrapper_type
+        self._data_type = AliasUtil.to_data_type_name(wrapper_type)
         self._rec_handler = RecordHandler(user)
         super().__init__(AliasUtil.to_sapio_user(user), first_page_criteria)
         self._report_man = DataMgmtServer.get_custom_report_manager(self.user)
@@ -139,9 +140,9 @@ class _RecordReportPagerBase(SapioPyAutoPager[CustomReportCriteria, WrappedType]
     def default_first_page_criteria(self) -> PagerResultCriteriaType:
         raise ValueError("Cannot generate a default first page criteria for custom reports.")
 
-    def get_next_page_result(self) -> tuple[CustomReportCriteria | None, Queue[WrappedType]]:
+    def get_next_page_result(self) -> tuple[CustomReportCriteria | None, Queue[WrappedType] | Queue[PyRecordModel]]:
         report: CustomReport = self._report_man.run_custom_report(self.next_page_criteria)
-        queue: Queue[WrappedType] = Queue()
+        queue = Queue()
         id_index: int = -1
         for i, column in enumerate(self._columns):
             if column.data_type_name == self._data_type and column.data_field_name == "RecordId":
@@ -151,7 +152,7 @@ class _RecordReportPagerBase(SapioPyAutoPager[CustomReportCriteria, WrappedType]
             raise SapioException(f"This report does not contain a Record ID column for the given record model type "
                                  f"{self._data_type}.")
         ids: list[int] = [row[id_index] for row in report.result_table]
-        for row in self._rec_handler.query_models_by_id(self._wrapper, ids, page_size=report.page_size):
+        for row in self._rec_handler.query_models_by_id(self._query_type, ids, page_size=report.page_size):
             queue.put(row)
         if report.has_next_page:
             next_page_criteria = copy(self.next_page_criteria)
@@ -165,12 +166,15 @@ class CustomReportRecordAutoPager(_RecordReportPagerBase):
     """
     A class that automatically pages through a custom report and returns the results as a list of records.
     """
-    def __init__(self, user: UserIdentifier, report_criteria: CustomReportCriteria, wrapper_type: type[WrappedType],
-                 page_number: int = 0, page_size: int = _default_record_page_size):
+    def __init__(self, user: UserIdentifier, report_criteria: CustomReportCriteria,
+                 wrapper_type: type[WrappedType] | str, page_number: int = 0,
+                 page_size: int = _default_record_page_size):
         """
         :param user: The current webhook context or a user object to send requests from.
         :param report_criteria: The custom report criteria to run.
-        :param wrapper_type: The record model wrapper type to use for the records.
+        :param wrapper_type: The record model wrapper type or data type name of the records being searched for.
+            If a data type name was used instead of a model wrapper, then the returned records will be PyRecordModels
+            instead of WrappedRecordModels.
         :param page_number: The page number to start on. The first page is page 0.
         :param page_size: The number of results to return per page.
         """
@@ -188,12 +192,14 @@ class SystemReportRecordAutoPager(_RecordReportPagerBase):
     System reports are also known as predefined searches in the system and must be defined in the data designer for
     a specific data type. That is, saved searches created by users cannot be run using this function.
     """
-    def __init__(self, user: UserIdentifier, report_name: str, wrapper_type: type[WrappedType],
+    def __init__(self, user: UserIdentifier, report_name: str, wrapper_type: type[WrappedType] | str,
                  page_number: int = 0, page_size: int = _default_record_page_size):
         """
         :param user: The current webhook context or a user object to send requests from.
         :param report_name: The name of the system report to run.
-        :param wrapper_type: The record model wrapper type to use for the records.
+        :param wrapper_type: The record model wrapper type or data type name of the records being searched for.
+            If a data type name was used instead of a model wrapper, then the returned records will be PyRecordModels
+            instead of WrappedRecordModels.
         :param page_number: The page number to start on. The first page is page 0.
         :param page_size: The number of results to return per page.
         """
@@ -208,12 +214,14 @@ class QuickReportRecordAutoPager(_RecordReportPagerBase):
     """
     A class that automatically pages through a quick report and returns the results as a list of records.
     """
-    def __init__(self, user: UserIdentifier, report_term: RawReportTerm, wrapper_type: type[WrappedType],
+    def __init__(self, user: UserIdentifier, report_term: RawReportTerm, wrapper_type: type[WrappedType] | str,
                  page_number: int = 0, page_size: int = _default_record_page_size):
         """
         :param user: The current webhook context or a user object to send requests from.
         :param report_term: The raw report term to use for the quick report.
-        :param wrapper_type: The record model wrapper type to use for the records.
+        :param wrapper_type: The record model wrapper type or data type name of the records being searched for.
+            If a data type name was used instead of a model wrapper, then the returned records will be PyRecordModels
+            instead of WrappedRecordModels.
         :param page_number: The page number to start on. The first page is page 0.
         :param page_size: The number of results to return per page.
         """
@@ -225,12 +233,12 @@ class QuickReportRecordAutoPager(_RecordReportPagerBase):
         super().__init__(user, first_page_criteria, wrapper_type)
 
 
-def _add_record_id_column(report: CustomReportCriteria, wrapper_type: type[WrappedType]) -> None:
+def _add_record_id_column(report: CustomReportCriteria, wrapper_type: type[WrappedType] | str) -> None:
     """
     Given a custom report criteria, ensure that the report contains a Record ID column for the given record model's
     data type. Add one if it is missing.
     """
-    dt: str = wrapper_type.get_wrapper_data_type_name()
+    dt: str = AliasUtil.to_data_type_name(wrapper_type)
     # Ensure that the root data type is the one we're looking for.
     report.root_data_type = dt
     # Enforce that the given custom report has a record ID column.

sapiopycommons/files/file_writer.py

@@ -307,7 +307,7 @@ class FieldColumn(ColumnDef):
         elif self.search_order == FieldSearchOrder.BUNDLE_ONLY:
             return row.fields.get(self.field_name)
         elif self.search_order == FieldSearchOrder.RECORD_FIRST:
-            fields: dict[str, Any] = AliasUtil.to_field_map_lists([record])[0] if record else {}
+            fields: dict[str, Any] = AliasUtil.to_field_map(record) if record else {}
             if self.field_name not in fields or (self.skip_none_values and fields.get(self.field_name) is None):
                 return row.fields.get(self.field_name)
             return fields.get(self.field_name)

sapiopycommons/general/aliases.py

@@ -207,10 +207,12 @@ class AliasUtil:
                              f"field with the name \"{field}\",")
 
     @staticmethod
-    def to_field_map(record: SapioRecord) -> FieldMap:
+    def to_field_map(record: SapioRecord, include_record_id: bool = False) -> FieldMap:
         """
-        Convert a given record value to a field map. This includes the given RecordId of the given record.
+        Convert a given record value to a field map.
 
+        :param record: A record which is a DataRecord, PyRecordModel, or WrappedRecordModel.
+        :param include_record_id: If true, include the record ID of the record in the field map using the RecordId key.
         :return: The field map for the input record.
         """
         if isinstance(record, DataRecord):
@@ -218,20 +220,25 @@ class AliasUtil:
             fields: FieldMap = record.get_fields()
         else:
             fields: FieldMap = record.fields.copy_to_dict()
-        fields["RecordId"] = AliasUtil.to_record_id(record)
+        # PR-47457: Only include the record ID if the caller requests it, since including the record ID can break
+        # callbacks in certain circumstances if the record ID is negative.
+        if include_record_id:
+            fields["RecordId"] = AliasUtil.to_record_id(record)
         return fields
 
     @staticmethod
-    def to_field_map_lists(records: Iterable[SapioRecord]) -> list[FieldMap]:
+    def to_field_map_list(records: Iterable[SapioRecord], include_record_id: bool = False) -> list[FieldMap]:
         """
         Convert a list of variables that could either be DataRecords, PyRecordModels, or WrappedRecordModels
         to a list of their field maps. This includes the given RecordId of the given records.
 
+        :param records: An iterable of records which are DataRecords, PyRecordModels, or WrappedRecordModels.
+        :param include_record_id: If true, include the record ID of the records in the field map using the RecordId key.
         :return: A list of field maps for the input records.
         """
         field_map_list: list[FieldMap] = []
         for record in records:
-            field_map_list.append(AliasUtil.to_field_map(record))
+            field_map_list.append(AliasUtil.to_field_map(record, include_record_id))
         return field_map_list
 
     @staticmethod