sapiopycommons 2025.9.16a754__py3-none-any.whl → 2025.9.19a761__py3-none-any.whl

sapiopycommons/ai/converter_service_base.py

@@ -9,15 +9,18 @@ from sapiopycommons.ai.protoapi.plan.converter.converter_pb2 import ConverterDet
     ConvertRequestPbo, ConverterDetailsRequestPbo, ContentTypePairPbo
 from sapiopycommons.ai.protoapi.plan.converter.converter_pb2_grpc import ConverterServiceServicer
 from sapiopycommons.ai.protoapi.plan.item.item_container_pb2 import ContentTypePbo, StepItemContainerPbo
+from sapiopycommons.files.temp_files import TempFileHandler
 
 
 class ConverterServiceBase(ConverterServiceServicer, ABC):
+    debug_mode: bool = False
+
     def GetConverterDetails(self, request: ConverterDetailsRequestPbo, context: ServicerContext) \
             -> ConverterDetailsResponsePbo:
         try:
             supported_types: list[ContentTypePairPbo] = []
             for c in self.register_converters():
-                converter = c()
+                converter = c(self.debug_mode)
                 supported_types.append(ContentTypePairPbo(
                     converter_name=converter.name(),
                     input_content_type=converter.input_type_pbo(),
@@ -34,12 +37,18 @@ class ConverterServiceBase(ConverterServiceServicer, ABC):
             input_container: StepItemContainerPbo = request.item_container
             input_type: ContentTypePbo = input_container.content_type
             target_type: ContentTypePbo = request.target_content_type
+
+            use_converter: ConverterBase | None = None
             for c in self.register_converters():
-                converter = c()
+                converter = c(self.debug_mode)
                 if converter.can_convert(input_type, target_type):
-                    return ConvertResponsePbo(item_container=converter.convert(input_container))
-            raise ValueError(f"No converter found for converting {input_type.name} ({', '.join(input_type.extensions)}) "
-                             f"to {target_type.name} ({', '.join(target_type.extensions)}).")
+                    use_converter = converter
+                    break
+            if use_converter is None:
+                raise ValueError(f"No converter found for converting {input_type.name} ({', '.join(input_type.extensions)}) "
+                                 f"to {target_type.name} ({', '.join(target_type.extensions)}).")
+
+            return ConvertResponsePbo(item_container=self.run(use_converter, input_container))
         except Exception as e:
             print(f"CRITICAL ERROR: {e}")
             print(traceback.format_exc())
@@ -62,8 +71,30 @@ class ConverterServiceBase(ConverterServiceServicer, ABC):
         """
         pass
 
+    def run(self, converter: ConverterBase, input_container: StepItemContainerPbo) -> StepItemContainerPbo:
+        try:
+            return converter.convert(input_container)
+        finally:
+            # Clean up any temporary files created by the converter. If in debug mode, then log the files instead
+            # so that they can be manually inspected.
+            if self.debug_mode:
+                print("Temporary files/directories created during converter execution:")
+                for directory in converter.temp_data.directories:
+                    print(f"\tDirectory: {directory}")
+                for file in converter.temp_data.files:
+                    print(f"\tFile: {file}")
+            else:
+                converter.temp_data.cleanup()
+
 
 class ConverterBase(ABC):
+    temp_data: TempFileHandler
+    debug_mode: bool
+
+    def __init__(self, debug_mode: bool):
+        self.temp_data = TempFileHandler()
+        self.debug_mode = debug_mode
+
     def name(self) -> str:
         """
         :return: The name of this converter, typically in the format "<input_type> to <output_type>".

sapiopycommons/ai/server.py

@@ -6,11 +6,13 @@ from typing import Any
 
 import grpc
 
+from sapiopycommons.ai.converter_service_base import ConverterServiceBase
 from sapiopycommons.ai.protoapi.plan.converter.converter_pb2_grpc import add_ConverterServiceServicer_to_server, \
     ConverterServiceServicer
 from sapiopycommons.ai.protoapi.plan.script.script_pb2_grpc import add_ScriptServiceServicer_to_server, \
     ScriptServiceServicer
 from sapiopycommons.ai.protoapi.plan.tool.tool_pb2_grpc import add_ToolServiceServicer_to_server, ToolServiceServicer
+from sapiopycommons.ai.tool_service_base import ToolServiceBase
 
 
 class SapioGrpcServer:
@@ -78,12 +80,13 @@ class SapioGrpcServer:
             if option_name in ('grpc.max_send_message_length', 'grpc.max_receive_message_length'):
                 self.options[i] = (option_name, message_mb_size * 1024 * 1024)
 
-    def add_converter_service(self, service: ConverterServiceServicer) -> None:
+    def add_converter_service(self, service: ConverterServiceBase) -> None:
         """
         Add a converter service to the gRPC server.
 
         :param service: The converter service to register with the server.
         """
+        service.debug_mode = self.debug_mode
         self._converter_services.append(service)
 
     def add_script_service(self, service: ScriptServiceServicer) -> None:
@@ -94,7 +97,7 @@ class SapioGrpcServer:
         """
         self._script_services.append(service)
 
-    def add_tool_service(self, service: ToolServiceServicer) -> None:
+    def add_tool_service(self, service: ToolServiceBase) -> None:
         """
         Add a tool service to the gRPC server.
 

sapiopycommons/ai/tool_service_base.py

@@ -9,8 +9,9 @@ import subprocess
 import traceback
 from abc import abstractmethod, ABC
 from logging import Logger
+from os import PathLike
 from subprocess import CompletedProcess
-from typing import Any, Iterable, Mapping
+from typing import Any, Iterable, Mapping, Sequence
 
 from grpc import ServicerContext
 from sapiopylib.rest.User import SapioUser, ensure_logger_initialized
@@ -168,6 +169,9 @@ class JsonResult(SapioToolResult):
         :param file_extensions: A list of file extensions that this binary data can be saved as.
         :param name: An optional identifying name for this result that will be accessible to the next tool.
         """
+        # Verify that the given json_data is actually a list of dictionaries.
+        if not isinstance(json_data, list) or not all(isinstance(x, dict) for x in json_data):
+            raise ValueError("json_data must be a list of dictionaries.")
         self.json_data = json_data
         self.content_type = content_type
         self.file_extensions = file_extensions if file_extensions else ["json"]
@@ -872,7 +876,10 @@ class ToolBase(ABC):
         """
         pass
 
-    def call_subprocess(self, args: list[str], cwd: str | None = None, **kwargs) -> CompletedProcess[str]:
+    def call_subprocess(self,
+                        args: str | bytes | PathLike[str] | PathLike[bytes] | Sequence[str | bytes | PathLike[str] | PathLike[bytes]],
+                        cwd: str | bytes | PathLike[str] | PathLike[bytes] | None = None,
+                        **kwargs) -> CompletedProcess[str]:
         """
         Call a subprocess with the given arguments, logging the command and any errors that occur.
         This function will raise an exception if the return code of the subprocess is non-zero. The output of the
@@ -1002,18 +1009,25 @@ class ToolBase(ABC):
             ret_val.append(row_dict)
         return list(headers), ret_val
 
-    def get_input_json(self, index: int = 0) -> list[list[Any]] | list[dict[str, Any]]:
+    def get_input_json(self, index: int = 0) -> list[dict[str, Any]]:
         """
         Parse the JSON data from the request object.
 
         :param index: The index of the input to parse. Defaults to 0. Used for tools that accept multiple inputs.
-        :return: A list of parsed JSON objects. Each entry in the list represents a separate JSON entry from the input.
-            Depending on this tool, this may be a list of dictionaries or a list of lists.
+        :return: A list of parsed JSON objects, which are represented as dictionaries.
         """
         container: StepItemContainerPbo = self.request.input[index].item_container
         if not container.HasField("json_container"):
             raise Exception(f"Input {index} does not contain a JSON container.")
-        return [json.loads(x) for x in container.json_container.items]
+        input_json: list[Any] = [json.loads(x) for x in container.json_container.items]
+        # Verify that the given JSON actually is a list of dictionaries. If they aren't then the previous step provided
+        # bad input. Tools are enforced to result in a list of dictionaries when returning JSON data, so this is likely
+        # an error caused by a script or static input step.
+        for i, entry in enumerate(input_json):
+            if not isinstance(entry, dict):
+                raise Exception(f"Element {i} of input {index} is not a dictionary object. All top-level JSON inputs "
+                                f"are expected to be dictionaries.")
+        return input_json
 
     def get_input_text(self, index: int = 0) -> list[str]:
         """

sapiopycommons/files/temp_files.py

@@ -1,6 +1,7 @@
 import os
 import shutil
 import tempfile
+from typing import Callable
 
 
 # FR-47422: Created class.
@@ -17,6 +18,8 @@ class TempFileHandler:
 
     def create_temp_directory(self) -> str:
         """
+        Create a temporary directory.
+
         :return: The path to a newly created temporary directory.
         """
         directory: str = tempfile.mkdtemp()
@@ -25,6 +28,8 @@ class TempFileHandler:
 
     def create_temp_file(self, data: str | bytes, suffix: str = "") -> str:
         """
+        Create a temporary file with the specified data and optional suffix.
+
         :param data: The data to write to the temporary file.
         :param suffix: An optional suffix for the temporary file.
         :return: The path to a newly created temporary file containing the provided data.
@@ -36,6 +41,29 @@ class TempFileHandler:
             self.files.append(file_path)
         return file_path
 
+    def create_temp_file_from_func(self, func: Callable, is_binary: bool = True, suffix: str = "", **kwargs) -> str:
+        """
+        Create a temporary file and populate it using the provided function. The function should accept parameters as
+        specified in the `params` dictionary. Any parameter in `params` with the value "<NEW_FILE>" will be replaced
+        with the path of the created temporary file.
+
+        :param func: The function to call with the temporary file path that will populate the file.
+        :param is_binary: Whether to open the temporary file in binary mode.
+        :param suffix: An optional suffix for the temporary file.
+        :param kwargs: Keyword arguments to pass to the function. Use "<NEW_FILE>" as a value to indicate where the
+            temporary file path should be inserted.
+        :return: The path to the newly created temporary file.
+        """
+        mode: str = 'wb' if is_binary else 'w'
+        with tempfile.NamedTemporaryFile(mode, suffix=suffix, delete=False) as tmp_file:
+            file_path: str = tmp_file.name
+            for key, value in kwargs.items():
+                if value == "<NEW_FILE>":
+                    kwargs[key] = file_path
+            func(**kwargs)
+            self.files.append(file_path)
+        return file_path
+
     def cleanup(self) -> None:
         """
         Delete all temporary files and directories created by this handler.

{sapiopycommons-2025.9.16a754.dist-info → sapiopycommons-2025.9.19a761.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.9.16a754
+Version: 2025.9.19a761
 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.9.16a754.dist-info → sapiopycommons-2025.9.19a761.dist-info}/RECORD

@@ -1,11 +1,11 @@
 sapiopycommons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sapiopycommons/ai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sapiopycommons/ai/converter_service_base.py,sha256=TMSyEekbbqMk9dRuAtLlSJ1sA1H8KpyCDlSOeqGFMWI,5115
+sapiopycommons/ai/converter_service_base.py,sha256=HiUXmwqv1STgyQeF9_eTFXzjIFXp5-NJ7sEhMpV3aAU,6351
 sapiopycommons/ai/protobuf_utils.py,sha256=cBjbxoFAwU02kNUxEce95WnMU2CMuDD-qFaeWgvQJMQ,24599
-sapiopycommons/ai/server.py,sha256=XDm_mj1yWHw-xQRFsFRHnsGw2JU0wsW2mR22P8PB09A,5744
+sapiopycommons/ai/server.py,sha256=GtkSKeHhahd40DXU6XIY3ZKpMl-MPMgPUYL8TakTj0w,5919
 sapiopycommons/ai/test_client.py,sha256=Um93jXmIx0YaHf-YbV5NSamPTHveJ0kU_UaAfOApnZg,16342
 sapiopycommons/ai/tool_of_tools.py,sha256=zYmQ4rNX-qYQnc-vNDnYZjtv9JgmQAmVVuHfVOdBF3w,46984
-sapiopycommons/ai/tool_service_base.py,sha256=x19ttJpLEyM-X-O0n0FG_BJktp0Vc6FL_2gKztV8nww,52892
+sapiopycommons/ai/tool_service_base.py,sha256=OmGUDsDj7sCNtjhJVohc1mUQ0PZsMhhgfG8BXAWujGs,53861
 sapiopycommons/ai/protoapi/fielddefinitions/fields_pb2.py,sha256=8tKXwLXcqFGdQHHSEBSi6Fd7dcaCFoOqmhjzqhenb_M,2372
 sapiopycommons/ai/protoapi/fielddefinitions/fields_pb2.pyi,sha256=FwtXmNAf7iYGEFm4kbqb04v77jNHbZg18ZmEDhle_bU,1444
 sapiopycommons/ai/protoapi/fielddefinitions/fields_pb2_grpc.py,sha256=uO25bcnfGqXpP4ggUur54Nr73Wj-DGWftExzLNcxdHI,931
@@ -69,7 +69,7 @@ sapiopycommons/files/file_text_converter.py,sha256=Gaj_divTiKXWd6flDOgrxNXpcn9fD
 sapiopycommons/files/file_util.py,sha256=djouyGjsYgWzjz2OBRnSeMDgj6NrsJUm1a2J93J8Wco,31915
 sapiopycommons/files/file_validator.py,sha256=ryg22-93csmRO_Pv0ZpWphNkB74xWZnHyJ23K56qLj0,28761
 sapiopycommons/files/file_writer.py,sha256=hACVl0duCjP28gJ1NPljkjagNCLod0ygUlPbvUmRDNM,17605
-sapiopycommons/files/temp_files.py,sha256=sw9Uw1ebhKzKcjE0VV7EcIA0UlySypGf90LlnJxYDiY,1602
+sapiopycommons/files/temp_files.py,sha256=e1PV07wFN5At1Ob-TbfS9nsPiZ8u9_Fl22KnWxJMmac,3056
 sapiopycommons/flowcyto/flow_cyto.py,sha256=B6DFquLi-gcWfJWyP4vYfwTXXJKl6O9W5-k8FzkM0Oo,2610
 sapiopycommons/flowcyto/flowcyto_data.py,sha256=mYKFuLbtpJ-EsQxLGtu4tNHVlygTxKixgJxJqD68F58,2596
 sapiopycommons/general/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -102,7 +102,7 @@ sapiopycommons/webhook/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3
 sapiopycommons/webhook/webhook_context.py,sha256=D793uLsb1691SalaPnBUk3rOSxn_hYLhdvkaIxjNXss,1909
 sapiopycommons/webhook/webhook_handlers.py,sha256=7o_wXOruhT9auNh8OfhJAh4WhhiPKij67FMBSpGPICc,39939
 sapiopycommons/webhook/webservice_handlers.py,sha256=cvW6Mk_110BzYqkbk63Kg7jWrltBCDALOlkJRu8h4VQ,14300
-sapiopycommons-2025.9.16a754.dist-info/METADATA,sha256=2ypbpQ44RejG2I4DXVHTd4UDrmzOWdbDCjArNSGAu_Y,3142
-sapiopycommons-2025.9.16a754.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-sapiopycommons-2025.9.16a754.dist-info/licenses/LICENSE,sha256=HyVuytGSiAUQ6ErWBHTqt1iSGHhLmlC8fO7jTCuR8dU,16725
-sapiopycommons-2025.9.16a754.dist-info/RECORD,,
+sapiopycommons-2025.9.19a761.dist-info/METADATA,sha256=As9JoZ85SMYRqYv83_ri1EKVYvMbU3dNWvkIVZ5RGA4,3142
+sapiopycommons-2025.9.19a761.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+sapiopycommons-2025.9.19a761.dist-info/licenses/LICENSE,sha256=HyVuytGSiAUQ6ErWBHTqt1iSGHhLmlC8fO7jTCuR8dU,16725
+sapiopycommons-2025.9.19a761.dist-info/RECORD,,