sapiopycommons 2025.4.24a493__py3-none-any.whl → 2025.4.24a495__py3-none-any.whl

sapiopycommons/ai/tool_service_base.py

@@ -6,13 +6,15 @@ from abc import abstractmethod, ABC
 from typing import Any
 
 from grpc import ServicerContext
+
+from sapiopycommons.ai.api.fielddefinitions.proto.velox_field_def_pb2 import VeloxFieldDefProto
 from sapiopycommons.general.aliases import FieldMap
 from sapiopylib.rest.User import SapioUser
 
 from sapiopycommons.ai.api.plan.tool.proto.entry_pb2 import StepEntryOutputData, StepEntryData, StepJsonData, DataType, \
     StepImageData, StepTextData, StepCsvData, StepBinaryData, StepCsvHeaderRow, StepCsvRow
 from sapiopycommons.ai.api.plan.tool.proto.tool_pb2 import ProcessStepRequest, ToolDetailsRequest, ToolDetailsResponse, \
-    ProcessStepResponse, ToolDetails, StepRecord, StepRecordFieldValue
+    ProcessStepResponse, ToolDetails, StepRecord, StepRecordFieldValue, ToolInputDetails, ToolOutputDetails
 from sapiopycommons.ai.api.plan.tool.proto.tool_pb2_grpc import ToolServiceServicer
 from sapiopycommons.ai.api.session.proto.sapio_conn_info_pb2 import SapioConnectionInfo, SapioUserSecretType
 
@@ -181,20 +183,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.
     """
     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()
 
@@ -202,19 +199,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.
-            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?
+            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
@@ -244,18 +243,142 @@ class ToolServiceBase(ToolServiceServicer, ABC):
         """
         return 1
 
+    def _get_tools(self) -> list[ToolBase]:
+        """
+        return: Get the tools registered with this service.
+        """
+        tools: list[ToolBase] = self.register_tools()
+        if not tools:
+            raise Exception("No tools registered with this service.")
+        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 get_details(self, user: SapioUser, request: ToolDetailsRequest, context: ServicerContext) -> list[ToolDetails]:
+    def register_tools(self) -> list[ToolBase]:
+        """
+        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
+
+    def get_details(self) -> list[ToolDetails]:
         """
         Get the details of the tool.
 
+        :return: A ToolDetailsResponse object containing the tool details.
+        """
+        tool_details: list[ToolDetails] = []
+        for tool in self._get_tools():
+            tool_details.append(tool.to_proto())
+        return tool_details
+
+    def run(self, user: SapioUser, request: ProcessStepRequest, context: ServicerContext) \
+            -> tuple[bool, list[SapioToolResult], list[str]]:
+        """
+        Execute a tool from this service.
+
         :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.
+        :return: Whether or not the tool succeeded, the results of the tool, and any logs generated by the tool.
         """
-        pass
+        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. 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.
+        """
+        self.inputs.append(details)
+
+    def add_output(self, details: ToolOutputDetails) -> None:
+        """
+        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.
+        """
+        self.outputs.append(details)
+
+    def add_config_field(self, field: VeloxFieldDefProto) -> None:
+        """
+        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 to_proto(self) -> ToolDetails:
+        """
+        :return: The ToolDetails proto object representing this tool.
+        """
+        return ToolDetails(
+            name=self.name,
+            description=self.description,
+            input_configs=self.inputs,
+            output_configs=self.outputs,
+            output_data_type_name=self.data_type_name,
+            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]:

{sapiopycommons-2025.4.24a493.dist-info → sapiopycommons-2025.4.24a495.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.4.24a493
+Version: 2025.4.24a495
 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.24a493.dist-info → sapiopycommons-2025.4.24a495.dist-info}/RECORD

@@ -1,7 +1,7 @@
 sapiopycommons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sapiopycommons/ai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sapiopycommons/ai/tool_of_tools.py,sha256=zYmQ4rNX-qYQnc-vNDnYZjtv9JgmQAmVVuHfVOdBF3w,46984
-sapiopycommons/ai/tool_service_base.py,sha256=YJoHWTPD10TXXmZUKZIS6ryrV3Xqzt6TWNMNFaD8aQ4,10911
+sapiopycommons/ai/tool_service_base.py,sha256=NFW5ulS__vDyASZ4VwsUDYRZNpN7QlKULGflvqcq6i4,15279
 sapiopycommons/ai/api/fielddefinitions/proto/velox_field_def_pb2.py,sha256=qPkyQsREtTLMliV9JB6tC5-NhmdWVWHJr70XNfcAfDI,20605
 sapiopycommons/ai/api/fielddefinitions/proto/velox_field_def_pb2.pyi,sha256=gVXRsuscx9XavKsTcepzXWf0LDAAyQ_J5ZjFK6kPYuo,34028
 sapiopycommons/ai/api/fielddefinitions/proto/velox_field_def_pb2_grpc.py,sha256=4vD4jWanaJ4uclSkFmS7JIz_lwYXDWBE3DomuPjUyII,941
@@ -82,7 +82,7 @@ sapiopycommons/webhook/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3
 sapiopycommons/webhook/webhook_context.py,sha256=D793uLsb1691SalaPnBUk3rOSxn_hYLhdvkaIxjNXss,1909
 sapiopycommons/webhook/webhook_handlers.py,sha256=L0HetSm43NvA5KyW3xbLpGFh2DbAaeZJVtXIEl2fvV8,39689
 sapiopycommons/webhook/webservice_handlers.py,sha256=Y5dHx_UFWFuSqaoPL6Re-fsKYRuxvCWZ8bj6KSZ3jfM,14285
-sapiopycommons-2025.4.24a493.dist-info/METADATA,sha256=FMPyRCRl6p7rmhrM1EEKrCE_Iod4lx7Z2xsy5piQ_kE,3143
-sapiopycommons-2025.4.24a493.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-sapiopycommons-2025.4.24a493.dist-info/licenses/LICENSE,sha256=HyVuytGSiAUQ6ErWBHTqt1iSGHhLmlC8fO7jTCuR8dU,16725
-sapiopycommons-2025.4.24a493.dist-info/RECORD,,
+sapiopycommons-2025.4.24a495.dist-info/METADATA,sha256=Q0s3dSO7fgqX3UkSA5n0GxaaNjIADxUHhvToU8XBkmM,3143
+sapiopycommons-2025.4.24a495.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+sapiopycommons-2025.4.24a495.dist-info/licenses/LICENSE,sha256=HyVuytGSiAUQ6ErWBHTqt1iSGHhLmlC8fO7jTCuR8dU,16725
+sapiopycommons-2025.4.24a495.dist-info/RECORD,,