sapiopycommons 2025.9.16a754__tar.gz → 2025.9.19a761__tar.gz

{sapiopycommons-2025.9.16a754 → sapiopycommons-2025.9.19a761}/PKG-INFO

@@ -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 → sapiopycommons-2025.9.19a761}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sapiopycommons"
-version='2025.09.16a754'
+version='2025.09.19a761'
 authors = [
     { name="Jonathan Steck", email="jsteck@sapiosciences.com" },
     { name="Yechen Qiao", email="yqiao@sapiosciences.com" },

{sapiopycommons-2025.9.16a754 → sapiopycommons-2025.9.19a761}/src/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-2025.9.16a754 → sapiopycommons-2025.9.19a761}/src/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-2025.9.16a754 → sapiopycommons-2025.9.19a761}/src/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-2025.9.16a754 → sapiopycommons-2025.9.19a761}/src/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.