sapiopycommons 2025.5.12a519__tar.gz → 2025.5.13a523__tar.gz

{sapiopycommons-2025.5.12a519 → sapiopycommons-2025.5.13a523}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.5.12a519
+Version: 2025.5.13a523
 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.5.12a519 → sapiopycommons-2025.5.13a523}/pyproject.toml

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

{sapiopycommons-2025.5.12a519 → sapiopycommons-2025.5.13a523}/src/sapiopycommons/ai/tool_service_base.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
 
 import json
+import logging
 import traceback
 from abc import abstractmethod, ABC
+from logging import Logger
 from typing import Any, Iterable, Sequence
 
 from grpc import ServicerContext
-from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.User import SapioUser, ensure_logger_initialized
 from sapiopylib.rest.pojo.datatype.FieldDefinition import AbstractVeloxFieldDefinition
 
 from sapiopycommons.ai.api.fielddefinitions.proto.fields_pb2 import FieldValueMapPbo, FieldValuePbo
@@ -305,8 +307,8 @@ class ToolServiceBase(ToolServiceServicer, ABC):
             tool.setup(user, request, context)
             results: list[SapioToolResult] = tool.run(user)
             return True, results, tool.logs
-        except Exception:
-            tool.log_message(traceback.format_exc())
+        except Exception as e:
+            tool.log_exception("Exception occurred during tool execution.", e)
             return False, [], tool.logs
 
 
@@ -321,6 +323,7 @@ class ToolBase(ABC):
     outputs: list[ToolOutputDetailsPbo]
     configs: list[VeloxFieldDefPbo]
     logs: list[str]
+    logger: Logger
 
     user: SapioUser
     request: ProcessStepRequestPbo
@@ -341,6 +344,8 @@ class ToolBase(ABC):
         self.outputs = []
         self.configs = []
         self.logs = []
+        self.logger = logging.getLogger(f"ToolBase.{self.name}")
+        ensure_logger_initialized(self.logger)
 
     def setup(self, user: SapioUser, request: ProcessStepRequestPbo, context: ServicerContext) -> None:
         """
@@ -432,8 +437,8 @@ class ToolBase(ABC):
         """
         self.configs.append(ProtobufUtils.field_def_to_pbo(field))
 
-    def add_boolean_config_field(self, field_name: str, display_name: str, description: str, default_value: bool) \
-            -> None:
+    def add_boolean_config_field(self, field_name: str, display_name: str, description: str, default_value: bool,
+                                 optional: bool = False) -> None:
         """
         Add a boolean configuration field to the tool. This field will be used to configure the tool in the plan
         manager.
@@ -442,13 +447,14 @@ class ToolBase(ABC):
         :param display_name: The display name of the field.
         :param description: The description of the field.
         :param default_value: The default value of the field.
+        :param optional: If true, this field is optional. If false, this field is required.
         """
         self.configs.append(VeloxFieldDefPbo(
             data_field_type=FieldTypePbo.BOOLEAN,
             data_field_name=field_name,
             display_name=display_name,
             description=description,
-            required=True,
+            required=not optional,
             editable=True,
             boolean_properties=BooleanPropertiesPbo(
                 default_value=default_value
@@ -456,7 +462,8 @@ class ToolBase(ABC):
         ))
 
     def add_double_config_field(self, field_name: str, display_name: str, description: str, default_value: float,
-                                min_value: float = -10.**120, max_value: float = 10.**120, precision: int = 2) -> None:
+                                min_value: float = -10.**120, max_value: float = 10.**120, precision: int = 2,
+                                optional: bool = False) -> None:
         """
         Add a double configuration field to the tool. This field will be used to configure the tool in the plan
         manager.
@@ -468,13 +475,14 @@ class ToolBase(ABC):
         :param min_value: The minimum value of the field.
         :param max_value: The maximum value of the field.
         :param precision: The precision of the field.
+        :param optional: If true, this field is optional. If false, this field is required.
         """
         self.configs.append(VeloxFieldDefPbo(
             data_field_type=FieldTypePbo.DOUBLE,
             data_field_name=field_name,
             display_name=display_name,
             description=description,
-            required=True,
+            required=not optional,
             editable=True,
             double_properties=DoublePropertiesPbo(
                 default_value=default_value,
@@ -485,7 +493,8 @@ class ToolBase(ABC):
         ))
 
     def add_integer_config_field(self, field_name: str, display_name: str, description: str,
-                                 default_value: int, min_value: int = -2**31, max_value: int = 2**31-1) -> None:
+                                 default_value: int, min_value: int = -2**31, max_value: int = 2**31-1,
+                                 optional: bool = False) -> None:
         """
         Add an integer configuration field to the tool. This field will be used to configure the tool in the plan
         manager.
@@ -496,13 +505,14 @@ class ToolBase(ABC):
         :param default_value: The default value of the field.
         :param min_value: The minimum value of the field.
         :param max_value: The maximum value of the field.
+        :param optional: If true, this field is optional. If false, this field is required.
         """
         self.configs.append(VeloxFieldDefPbo(
             data_field_type=FieldTypePbo.INTEGER,
             data_field_name=field_name,
             display_name=display_name,
             description=description,
-            required=True,
+            required=not optional,
             editable=True,
             integer_properties=IntegerPropertiesPbo(
                 default_value=default_value,
@@ -512,7 +522,7 @@ class ToolBase(ABC):
         ))
 
     def add_string_config_field(self, field_name: str, display_name: str, description: str,
-                                default_value: str, max_length: int = 1000) -> None:
+                                default_value: str, max_length: int = 1000, optional: bool = False) -> None:
         """
         Add a string configuration field to the tool. This field will be used to configure the tool in the plan
         manager.
@@ -522,13 +532,14 @@ class ToolBase(ABC):
         :param description: The description of the field.
         :param default_value: The default value of the field.
         :param max_length: The maximum length of the field.
+        :param optional: If true, this field is optional. If false, this field is required.
         """
         self.configs.append(VeloxFieldDefPbo(
             data_field_type=FieldTypePbo.STRING,
             data_field_name=field_name,
             display_name=display_name,
             description=description,
-            required=True,
+            required=not optional,
             editable=True,
             string_properties=StringPropertiesPbo(
                 default_value=default_value,
@@ -537,7 +548,7 @@ class ToolBase(ABC):
         ))
 
     def add_list_config_field(self, field_name: str, display_name: str, description: str, default_value: str,
-                              allowed_values: list[str], direct_edit: bool = False) -> None:
+                              allowed_values: list[str], direct_edit: bool = False, optional: bool = False) -> None:
         """
         Add a list configuration field to the tool. This field will be used to configure the tool in the plan
         manager.
@@ -549,13 +560,14 @@ class ToolBase(ABC):
         :param allowed_values: The list of allowed values for the field.
         :param direct_edit: If true, the user can enter a value that is not in the list of allowed values. If false,
             the user can only select from the list of allowed values.
+        :param optional: If true, this field is optional. If false, this field is required.
         """
         self.configs.append(VeloxFieldDefPbo(
             data_field_type=FieldTypePbo.SELECTION,
             data_field_name=field_name,
             display_name=display_name,
             description=description,
-            required=True,
+            required=not optional,
             editable=True,
             selection_properties=SelectionPropertiesPbo(
                 default_value=default_value,
@@ -565,8 +577,8 @@ class ToolBase(ABC):
         ))
 
     def add_multi_list_config_field(self, field_name: str, display_name: str, description: str,
-                                    default_value: list[str], allowed_values: list[str], direct_edit: bool = False) \
-            -> None:
+                                    default_value: list[str], allowed_values: list[str], direct_edit: bool = False,
+                                    optional: bool = False) -> None:
         """
         Add a multi-select list configuration field to the tool. This field will be used to configure the tool in the
         plan manager.
@@ -578,13 +590,14 @@ class ToolBase(ABC):
         :param allowed_values: The list of allowed values for the field.
         :param direct_edit: If true, the user can enter a value that is not in the list of allowed values. If false,
             the user can only select from the list of allowed values.
+        :param optional: If true, this field is optional. If false, this field is required.
         """
         self.configs.append(VeloxFieldDefPbo(
             data_field_type=FieldTypePbo.SELECTION,
             data_field_name=field_name,
             display_name=display_name,
             description=description,
-            required=True,
+            required=not optional,
             editable=True,
             selection_properties=SelectionPropertiesPbo(
                 default_value=",".join(default_value),
@@ -624,16 +637,50 @@ class ToolBase(ABC):
         """
         pass
 
-    def log_message(self, message: str, verbose: bool = False) -> None:
+    def log_info(self, message: str) -> None:
+        """
+        Log an info message for this tool. If verbose logging is enabled, this message will be included in the logs
+        returned to the caller.
+        .
+
+        :param message: The message to log.
+        """
+        msg = f"INFO: {self.name}: {message}"
+        if self.verbose_logging:
+            self.logs.append(msg)
+        self.logger.info(msg)
+
+    def log_warning(self, message: str) -> None:
+        """
+        Log a warning message for this tool. This message will be included in the logs returned to the caller.
+
+        :param message: The message to log.
+        """
+        msg = f"WARNING: {self.name}: {message}"
+        self.logs.append(msg)
+        self.logger.warning(msg)
+
+    def log_error(self, message: str) -> None:
+        """
+        Log an error message for this tool. This message will be included in the logs returned to the caller.
+
+        :param message: The message to log.
+        """
+        msg = f"ERROR: {self.name}: {message}"
+        self.logs.append(msg)
+        self.logger.error(msg)
+
+    def log_exception(self, message: str, e: Exception) -> None:
         """
-        Log a message for this tool. This message will be included in the logs returned to the caller.
+        Log an exception for this tool. This message will be included in the logs returned to the caller.
 
         :param message: The message to log.
-        :param verbose: If true, the message will only be logged if verbose logging is enabled. If false, the message
-            will be logged regardless of the verbose logging setting.
+        :param e: The exception to log.
         """
-        if not verbose or self.verbose_logging:
-            self.logs.append(f"{self.name}: {message}")
+        msg = f"EXCEPTION: {self.name}: {message} - {e}"
+        self.logs.append(msg)
+        msg += "\n" + traceback.format_exc()
+        self.logger.error(msg)
 
     def get_input_binary(self, index: int = 0) -> list[bytes]:
         """