sapiopycommons 2025.4.24a494__tar.gz → 2025.4.25a496__tar.gz

{sapiopycommons-2025.4.24a494 → sapiopycommons-2025.4.25a496}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.4.24a494
+Version: 2025.4.25a496
 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.4.24a494 → sapiopycommons-2025.4.25a496}/pyproject.toml

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

{sapiopycommons-2025.4.24a494 → sapiopycommons-2025.4.25a496}/src/sapiopycommons/ai/tool_service_base.py

@@ -7,7 +7,8 @@ from typing import Any
 
 from grpc import ServicerContext
 
-from sapiopycommons.ai.api.fielddefinitions.proto.velox_field_def_pb2 import VeloxFieldDefProto
+from sapiopycommons.ai.api.fielddefinitions.proto.velox_field_def_pb2 import VeloxFieldDefProto, FieldTypeProto, \
+    IntegerProperties, DoubleProperties, SelectionProperties, BooleanProperties
 from sapiopycommons.general.aliases import FieldMap
 from sapiopylib.rest.User import SapioUser
 
@@ -183,22 +184,15 @@ class TextResult(SapioToolResult):
 
 class ToolServiceBase(ToolServiceServicer, ABC):
     """
-    A base class for implementing a tool service.
-
-    Subclasses must implement the get_details and run methods to provide specific functionality for the tool.
+    A base class for implementing a tool service. Subclasses should implement the register_tools method to register
+    their tools with the service.
     """
-    tools: list[ToolBase]
-
     def GetToolDetails(self, request: ToolDetailsRequest, context: ServicerContext) -> ToolDetailsResponse:
         try:
-            # Convert the SapioConnectionInfo proto object to a SapioUser object.
-            user = self.create_user(request.sapio_conn_info)
-            # Get the tool details from the subclass.
-            # TODO: Return something other than the ToolDetails proto objects? Something that's cleaner for the
-            #  implementing class to work with?
-            details: list[ToolDetails] = self.get_details(user, request, context)
+            # Get the tool details from the registered tools.
+            details: list[ToolDetails] = self.get_details()
             return ToolDetailsResponse(tool_framework_version=self.tool_version(), tool_details=details)
-        except Exception as e:
+        except Exception:
             # TODO: This response doesn't even allow logs. What should we do if an exception occurs in this case?
             return ToolDetailsResponse()
 
@@ -206,22 +200,21 @@ class ToolServiceBase(ToolServiceServicer, ABC):
         try:
             # Convert the SapioConnectionInfo proto object to a SapioUser object.
             user = self.create_user(request.sapio_user)
-            # Get the tool results from the subclass and convert them to proto objects.
+            # Get the tool results from the registered tool matching the request and convert them to proto objects.
             entry_data: list[StepEntryOutputData] = []
             new_records: list[StepRecord] = []
-            for result in self.run(user, request, context):
+            # TODO: Make use of the success value after the response object has a field for it.
+            success, results, logs = self.run(user, request, context)
+            for result in results:
                 data: StepEntryOutputData | list[StepRecord] = result.to_proto()
                 if isinstance(data, StepEntryOutputData):
                     entry_data.append(data)
                 else:
                     new_records.extend(data)
             # Return a ProcessStepResponse proto object containing the output data and new records to the caller.
-            # TODO: Return an is_success = true value.
-            # TODO: Allow logging in the tools?
-            return ProcessStepResponse(entry_data=entry_data, new_records=new_records)
-        except Exception as e:
-            # TODO: Do something other than dump the full stack trace into the logs?
-            # TODO: Eventually we'll return an is_success = false value.
+            return ProcessStepResponse(entry_data=entry_data, log=logs, new_records=new_records)
+        except Exception:
+            # TODO: Return a False success result after the response object has a field for it.
             return ProcessStepResponse(log=[traceback.format_exc()])
 
     @staticmethod
@@ -253,32 +246,40 @@ class ToolServiceBase(ToolServiceServicer, ABC):
 
     def _get_tools(self) -> list[ToolBase]:
         """
-        Get the tools registered with this service.
+        return: Get the tools registered with this service.
         """
-        # If the tools have not been registered, call the register_tools method to do so.
-        if not hasattr(self, "tools"):
-            self.tools = self.register_tools()
-        # If the tools are still not registered, raise an exception.
-        if not self.tools:
+        tools: list[ToolBase] = self.register_tools()
+        if not tools:
             raise Exception("No tools registered with this service.")
-        return self.tools
+        return tools
+
+    def _get_tool(self, name: str) -> ToolBase:
+        """
+        Get a specific tool by its name.
+
+        :param name: The name of the tool to retrieve.
+        :return: The tool object corresponding to the given name.
+        """
+        tools: dict[str, ToolBase] = {x.name: x for x in self.register_tools()}
+        if not tools:
+            raise Exception("No tools registered with this service.")
+        if name not in tools:
+            raise Exception(f"Tool \"{name}\" not found in registered tools.")
+        return tools[name]
 
     @abstractmethod
     def register_tools(self) -> list[ToolBase]:
         """
-        Register the tools with this service.
+        Register the tools with this service. Create and instantiate ToolBase subclasses to register them.
+
+        :return: A list of tools to register to this service.
         """
         pass
 
-    @abstractmethod
-    def get_details(self, user: SapioUser, request: ToolDetailsRequest, context: ServicerContext) -> list[ToolDetails]:
+    def get_details(self) -> list[ToolDetails]:
         """
         Get the details of the tool.
 
-        :param user: A user object that can be used to initialize manager classes using DataMgmtServer to query the
-            system.
-        :param request: The request object containing the input data.
-        :param context: The gRPC context.
         :return: A ToolDetailsResponse object containing the tool details.
         """
         tool_details: list[ToolDetails] = []
@@ -286,8 +287,8 @@ class ToolServiceBase(ToolServiceServicer, ABC):
             tool_details.append(tool.to_proto())
         return tool_details
 
-    @abstractmethod
-    def run(self, user: SapioUser, request: ProcessStepRequest, context: ServicerContext) -> list[SapioToolResult]:
+    def run(self, user: SapioUser, request: ProcessStepRequest, context: ServicerContext) \
+            -> tuple[bool, list[SapioToolResult], list[str]]:
         """
         Execute a tool from this service.
 
@@ -295,32 +296,48 @@ class ToolServiceBase(ToolServiceServicer, ABC):
             system.
         :param request: The request object containing the input data.
         :param context: The gRPC context.
-        :return: A SapioToolResults object containing the response data.
+        :return: Whether or not the tool succeeded, the results of the tool, and any logs generated by the tool.
         """
-        for tool in self._get_tools():
-            if request.tool_name == tool.name:
-                return tool.run(user, request, context)
-        raise Exception(f"Tool {request.tool_name} not found in registered tools.")
+        tool = self._get_tool(request.tool_name)
+        try:
+            results = tool.run(user, request, context)
+            return True, results, tool.logs
+        except Exception:
+            tool.log_message(traceback.format_exc())
+            return False, [], tool.logs
 
 
 class ToolBase(ABC):
+    """
+    A base class for implementing a tool.
+    """
     name: str
     description: str
     data_type_name: str | None
     inputs: list[ToolInputDetails]
     outputs: list[ToolOutputDetails]
     configs: list[VeloxFieldDefProto]
+    logs: list[str]
 
     def __init__(self, name: str, description: str, data_type_name: str | None = None):
+        """
+        :param name: The name of the tool.
+        :param description: A description of the tool.
+        :param data_type_name: The name of the output data type of this tool, if applicable. When this tool returns
+            FieldMapResult objects in its run method, this name will be used to set the data type of the output data.
+        """
         self.name = name
         self.description = description
         self.data_type_name = data_type_name
         self.inputs = []
         self.outputs = []
+        self.configs = []
+        self.logs = []
 
     def add_input(self, details: ToolInputDetails) -> None:
         """
-        Add an input configuration to the tool.
+        Add an input configuration to the tool. This determines how many inputs this tool will accept in the plan
+        manager, as well as what those inputs are.
 
         :param details: The input configuration details.
         """
@@ -328,7 +345,8 @@ class ToolBase(ABC):
 
     def add_output(self, details: ToolOutputDetails) -> None:
         """
-        Add an output configuration to the tool.
+        Add an output configuration to the tool. This determines how many outputs this tool will return in the plan
+        manager, as well as what those outputs are.
 
         :param details: The output configuration details.
         """
@@ -336,17 +354,119 @@ class ToolBase(ABC):
 
     def add_config_field(self, field: VeloxFieldDefProto) -> None:
         """
-        Add a configuration field to the tool.
+        Add a configuration field to the tool. This field will be used to configure the tool in the plan manager.
 
         :param field: The configuration field details.
         """
         self.configs.append(field)
 
+    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:
+        """
+        Add an integer configuration field to the tool. This field will be used to configure the tool in the plan
+        manager.
+
+        :param field_name: The name of the field.
+        :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 min_value: The minimum value of the field.
+        :param max_value: The maximum value of the field.
+        """
+        self.configs.append(VeloxFieldDefProto(
+            data_field_type=FieldTypeProto.INTEGER,
+            data_field_name=field_name,
+            display_name=display_name,
+            description=description,
+            required=True,
+            editable=True,
+            integer_properties=IntegerProperties(
+                default_value=default_value,
+                min_value=min_value,
+                max_value=max_value
+            )
+        ))
+
+    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:
+        """
+        Add a double configuration field to the tool. This field will be used to configure the tool in the plan
+        manager.
+
+        :param field_name: The name of the field.
+        :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 min_value: The minimum value of the field.
+        :param max_value: The maximum value of the field.
+        :param precision: The precision of the field.
+        """
+        self.configs.append(VeloxFieldDefProto(
+            data_field_type=FieldTypeProto.DOUBLE,
+            data_field_name=field_name,
+            display_name=display_name,
+            description=description,
+            required=True,
+            editable=True,
+            double_properties=DoubleProperties(
+                default_value=default_value,
+                min_value=min_value,
+                max_value=max_value,
+                precision=precision
+            )
+        ))
+
+    def add_list_config_field(self, field_name: str, display_name: str, description: str, default_value: str,
+                              allowed_values: list[str]) -> None:
+        """
+        Add a list configuration field to the tool. This field will be used to configure the tool in the plan
+        manager.
+
+        :param field_name: The name of the field.
+        :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 allowed_values: The list of allowed values for the field.
+        """
+        self.configs.append(VeloxFieldDefProto(
+            data_field_type=FieldTypeProto.SELECTION,
+            data_field_name=field_name,
+            display_name=display_name,
+            description=description,
+            required=True,
+            editable=True,
+            selection_properties=SelectionProperties(
+                default_value=default_value,
+                static_list_values=allowed_values,
+            )
+        ))
+
+    def add_boolean_config_field(self, field_name: str, display_name: str, description: str, default_value: bool) \
+            -> None:
+        """
+        Add a boolean configuration field to the tool. This field will be used to configure the tool in the plan
+        manager.
+
+        :param field_name: The name of the field.
+        :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.
+        """
+        self.configs.append(VeloxFieldDefProto(
+            data_field_type=FieldTypeProto.BOOLEAN,
+            data_field_name=field_name,
+            display_name=display_name,
+            description=description,
+            required=True,
+            editable=True,
+            boolean_properties=BooleanProperties(
+                default_value=default_value
+            )
+        ))
+
     def to_proto(self) -> ToolDetails:
         """
-        Convert this tool to a ToolDetails proto object.
-
-        :return: The ToolDetails proto object.
+        :return: The ToolDetails proto object representing this tool.
         """
         return ToolDetails(
             name=self.name,
@@ -357,6 +477,14 @@ class ToolBase(ABC):
             config_fields=self.configs
         )
 
+    def log_message(self, message: str) -> None:
+        """
+        Log a message for this tool. This message will be included in the logs returned to the caller.
+
+        :param message: The message to log.
+        """
+        self.logs.append(message)
+
     @abstractmethod
     def run(self, user: SapioUser, request: ProcessStepRequest, context: ServicerContext) -> list[SapioToolResult]:
         """
@@ -369,3 +497,56 @@ class ToolBase(ABC):
         :return: A SapioToolResults object containing the response data.
         """
         pass
+
+    @staticmethod
+    def get_request_json(request: ProcessStepRequest, index: int = 0) -> list[Any]:
+        """
+        Parse the JSON data from the request object.
+
+        :param request: The request object containing the input data.
+        :param index: The index of the input to parse. Defaults to 0.
+        :return: A list of parsed JSON objects. Each entry in the list represents a separate JSON entry from the input.
+        """
+        entry_data = request.entry_data
+        input_data: list[Any] = [json.loads(x) for x in entry_data[index].entry_data.json_data.entries]
+        return input_data
+
+    @staticmethod
+    def read_from_json(json_data: list[dict[str, Any]], key: str) -> list[Any]:
+        """
+        From a list of dictionaries, return a list of values for the given key from each dictionary. Skips null values.
+
+        :param json_data: The JSON data to read from.
+        :param key: The key to read the values from.
+        :return: A list of values corresponding to the given key in the JSON data.
+        """
+        ret_val: list[Any] = []
+        for entry in json_data:
+            if key in entry:
+                value = entry[key]
+                if isinstance(value, list):
+                    ret_val.extend(value)
+                elif value is not None:
+                    ret_val.append(value)
+        return ret_val
+
+    @staticmethod
+    def get_config_fields(request: ProcessStepRequest) -> dict[str, Any]:
+        """
+        Get the configuration fields from the request object.
+
+        :param request: The request object containing the input data.
+        :return: A dictionary of configuration field names and their values.
+        """
+        config_fields: dict[str, Any] = {}
+        for field, value in request.config_field_values.items():
+            if value.bool_value is not None:
+                value = value.bool_value
+            elif value.string_value is not None:
+                value = value.string_value
+            elif value.int_value is not None:
+                value = value.int_value
+            elif value.double_value is not None:
+                value = value.double_value
+            config_fields[field] = value
+        return config_fields