sapiopycommons 2025.8.20a713__tar.gz → 2025.9.8a728__tar.gz

{sapiopycommons-2025.8.20a713 → sapiopycommons-2025.9.8a728}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.8.20a713
+Version: 2025.9.8a728
 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.8.20a713 → sapiopycommons-2025.9.8a728}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sapiopycommons"
-version='2025.08.20a713'
+version='2025.09.08a728'
 authors = [
     { name="Jonathan Steck", email="jsteck@sapiosciences.com" },
     { name="Yechen Qiao", email="yqiao@sapiosciences.com" },

{sapiopycommons-2025.8.20a713 → sapiopycommons-2025.9.8a728}/src/sapiopycommons/ai/converter_service_base.py

@@ -118,7 +118,8 @@ class ConverterBase(ABC):
         :param target_type: The target content type.
         :return: True if this converter can convert from the input type to the target type, False otherwise.
         """
-        return self.input_type() == input_type.name and self.output_type() == target_type.name
+        return (self.input_type().lower() == input_type.name.lower()
+                and self.output_type().lower() == target_type.name.lower())
 
     @abstractmethod
     def convert(self, content: StepItemContainerPbo) -> StepItemContainerPbo:

{sapiopycommons-2025.8.20a713 → sapiopycommons-2025.9.8a728}/src/sapiopycommons/ai/protoapi/plan/item/item_container_pb2.py

@@ -24,7 +24,7 @@ _sym_db = _symbol_database.Default()
 
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n9sapiopycommons/ai/protoapi/plan/item/item_container.proto\"2\n\x0e\x43ontentTypePbo\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x12\n\nextensions\x18\x02 \x03(\t\"$\n\x13StepCsvHeaderRowPbo\x12\r\n\x05\x63\x65lls\x18\x01 \x03(\t\"\x1e\n\rStepCsvRowPbo\x12\r\n\x05\x63\x65lls\x18\x01 \x03(\t\"Z\n\x13StepCsvContainerPbo\x12$\n\x06header\x18\x0e \x01(\x0b\x32\x14.StepCsvHeaderRowPbo\x12\x1d\n\x05items\x18\x0f \x03(\x0b\x32\x0e.StepCsvRowPbo\"%\n\x14StepJsonContainerPbo\x12\r\n\x05items\x18\x0f \x03(\t\"%\n\x14StepTextContainerPbo\x12\r\n\x05items\x18\x0f \x03(\t\"\'\n\x16StepBinaryContainerPbo\x12\r\n\x05items\x18\x0f \x03(\x0c\"<\n\x15StepImageContainerPbo\x12\x14\n\x0cimage_format\x18\x01 \x01(\t\x12\r\n\x05items\x18\x0f \x03(\x0c\"\x94\x02\n\x14StepItemContainerPbo\x12%\n\x0c\x63ontent_type\x18\x02 \x01(\x0b\x32\x0f.ContentTypePbo\x12\x34\n\x10\x62inary_container\x18\xff\x0f \x01(\x0b\x32\x17.StepBinaryContainerPboH\x00\x12.\n\rcsv_container\x18\xfe\x0f \x01(\x0b\x32\x14.StepCsvContainerPboH\x00\x12\x30\n\x0ejson_container\x18\xfd\x0f \x01(\x0b\x32\x15.StepJsonContainerPboH\x00\x12\x30\n\x0etext_container\x18\xfc\x0f \x01(\x0b\x32\x15.StepTextContainerPboH\x00\x42\x0b\n\tcontainer*A\n\x0b\x44\x61taTypePbo\x12\n\n\x06\x42INARY\x10\x00\x12\x08\n\x04JSON\x10\x01\x12\x07\n\x03\x43SV\x10\x02\x12\x08\n\x04TEXT\x10\x03\x12\t\n\x05IMAGE\x10\x04\x42 \n\x1c\x63om.velox.protoapi.plan.itemP\x01\x62\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n9sapiopycommons/ai/protoapi/plan/item/item_container.proto\"2\n\x0e\x43ontentTypePbo\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x12\n\nextensions\x18\x02 \x03(\t\"$\n\x13StepCsvHeaderRowPbo\x12\r\n\x05\x63\x65lls\x18\x01 \x03(\t\"\x1e\n\rStepCsvRowPbo\x12\r\n\x05\x63\x65lls\x18\x01 \x03(\t\"Z\n\x13StepCsvContainerPbo\x12$\n\x06header\x18\x0e \x01(\x0b\x32\x14.StepCsvHeaderRowPbo\x12\x1d\n\x05items\x18\x0f \x03(\x0b\x32\x0e.StepCsvRowPbo\"%\n\x14StepJsonContainerPbo\x12\r\n\x05items\x18\x0f \x03(\t\"%\n\x14StepTextContainerPbo\x12\r\n\x05items\x18\x0f \x03(\t\"\'\n\x16StepBinaryContainerPbo\x12\r\n\x05items\x18\x0f \x03(\x0c\"<\n\x15StepImageContainerPbo\x12\x14\n\x0cimage_format\x18\x01 \x01(\t\x12\r\n\x05items\x18\x0f \x03(\x0c\"\xac\x02\n\x14StepItemContainerPbo\x12%\n\x0c\x63ontent_type\x18\x02 \x01(\x0b\x32\x0f.ContentTypePbo\x12\x16\n\x0e\x63ontainer_name\x18\x03 \x01(\t\x12\x34\n\x10\x62inary_container\x18\xff\x0f \x01(\x0b\x32\x17.StepBinaryContainerPboH\x00\x12.\n\rcsv_container\x18\xfe\x0f \x01(\x0b\x32\x14.StepCsvContainerPboH\x00\x12\x30\n\x0ejson_container\x18\xfd\x0f \x01(\x0b\x32\x15.StepJsonContainerPboH\x00\x12\x30\n\x0etext_container\x18\xfc\x0f \x01(\x0b\x32\x15.StepTextContainerPboH\x00\x42\x0b\n\tcontainer*A\n\x0b\x44\x61taTypePbo\x12\n\n\x06\x42INARY\x10\x00\x12\x08\n\x04JSON\x10\x01\x12\x07\n\x03\x43SV\x10\x02\x12\x08\n\x04TEXT\x10\x03\x12\t\n\x05IMAGE\x10\x04\x42 \n\x1c\x63om.velox.protoapi.plan.itemP\x01\x62\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
@@ -32,8 +32,8 @@ _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'sapiopycommons.ai.protoapi.
 if not _descriptor._USE_C_DESCRIPTORS:
   _globals['DESCRIPTOR']._loaded_options = None
   _globals['DESCRIPTOR']._serialized_options = b'\n\034com.velox.protoapi.plan.itemP\001'
-  _globals['_DATATYPEPBO']._serialized_start=735
-  _globals['_DATATYPEPBO']._serialized_end=800
+  _globals['_DATATYPEPBO']._serialized_start=759
+  _globals['_DATATYPEPBO']._serialized_end=824
   _globals['_CONTENTTYPEPBO']._serialized_start=61
   _globals['_CONTENTTYPEPBO']._serialized_end=111
   _globals['_STEPCSVHEADERROWPBO']._serialized_start=113
@@ -51,5 +51,5 @@ if not _descriptor._USE_C_DESCRIPTORS:
   _globals['_STEPIMAGECONTAINERPBO']._serialized_start=394
   _globals['_STEPIMAGECONTAINERPBO']._serialized_end=454
   _globals['_STEPITEMCONTAINERPBO']._serialized_start=457
-  _globals['_STEPITEMCONTAINERPBO']._serialized_end=733
+  _globals['_STEPITEMCONTAINERPBO']._serialized_end=757
 # @@protoc_insertion_point(module_scope)

{sapiopycommons-2025.8.20a713 → sapiopycommons-2025.9.8a728}/src/sapiopycommons/ai/protoapi/plan/item/item_container_pb2.pyi

@@ -74,15 +74,17 @@ class StepImageContainerPbo(_message.Message):
     def __init__(self, image_format: _Optional[str] = ..., items: _Optional[_Iterable[bytes]] = ...) -> None: ...
 
 class StepItemContainerPbo(_message.Message):
-    __slots__ = ("content_type", "binary_container", "csv_container", "json_container", "text_container")
+    __slots__ = ("content_type", "container_name", "binary_container", "csv_container", "json_container", "text_container")
     CONTENT_TYPE_FIELD_NUMBER: _ClassVar[int]
+    CONTAINER_NAME_FIELD_NUMBER: _ClassVar[int]
     BINARY_CONTAINER_FIELD_NUMBER: _ClassVar[int]
     CSV_CONTAINER_FIELD_NUMBER: _ClassVar[int]
     JSON_CONTAINER_FIELD_NUMBER: _ClassVar[int]
     TEXT_CONTAINER_FIELD_NUMBER: _ClassVar[int]
     content_type: ContentTypePbo
+    container_name: str
     binary_container: StepBinaryContainerPbo
     csv_container: StepCsvContainerPbo
     json_container: StepJsonContainerPbo
     text_container: StepTextContainerPbo
-    def __init__(self, content_type: _Optional[_Union[ContentTypePbo, _Mapping]] = ..., binary_container: _Optional[_Union[StepBinaryContainerPbo, _Mapping]] = ..., csv_container: _Optional[_Union[StepCsvContainerPbo, _Mapping]] = ..., json_container: _Optional[_Union[StepJsonContainerPbo, _Mapping]] = ..., text_container: _Optional[_Union[StepTextContainerPbo, _Mapping]] = ...) -> None: ...
+    def __init__(self, content_type: _Optional[_Union[ContentTypePbo, _Mapping]] = ..., container_name: _Optional[str] = ..., binary_container: _Optional[_Union[StepBinaryContainerPbo, _Mapping]] = ..., csv_container: _Optional[_Union[StepCsvContainerPbo, _Mapping]] = ..., json_container: _Optional[_Union[StepJsonContainerPbo, _Mapping]] = ..., text_container: _Optional[_Union[StepTextContainerPbo, _Mapping]] = ...) -> None: ...

{sapiopycommons-2025.8.20a713 → sapiopycommons-2025.9.8a728}/src/sapiopycommons/ai/server.py

@@ -14,13 +14,13 @@ class SapioGrpcServer:
     """
     A gRPC server for handling the various Sapio gRPC services.
     """
-    port: str
+    port: int
     options: list[tuple[str, Any]]
     _converter_services: list[ConverterServiceServicer]
     _script_services: list[ScriptServiceServicer]
     _tool_services: list[ToolServiceServicer]
 
-    def __init__(self, port: str = "50051", message_mb_size: int = 100, options: list[tuple[str, Any]] | None = None) \
+    def __init__(self, port: int = 50051, message_mb_size: int = 1024, options: list[tuple[str, Any]] | None = None) \
             -> None:
         """
         Initialize the gRPC server with the specified port and message size.
@@ -30,6 +30,8 @@ class SapioGrpcServer:
         :param options: Additional gRPC server options to set. This should be a list of tuples where the first item is
             the option name and the second item is the option value.
         """
+        if isinstance(port, str):
+            port = int(port)
         self.port = port
         self.options = [
             ('grpc.max_send_message_length', message_mb_size * 1024 * 1024),
@@ -86,9 +88,9 @@ class SapioGrpcServer:
                 print(f"Registering Tool service: {service.__class__.__name__}")
                 add_ToolServiceServicer_to_server(service, server)
 
-            server.add_insecure_port("[::]:" + self.port)
+            server.add_insecure_port(f"[::]:{self.port}")
             await server.start()
-            print("Server started, listening on " + self.port)
+            print(f"Server started, listening on {self.port}")
             try:
                 await server.wait_for_termination()
             finally:

{sapiopycommons-2025.8.20a713 → sapiopycommons-2025.9.8a728}/src/sapiopycommons/ai/test_client.py

@@ -43,10 +43,10 @@ class ToolOutput:
     status: str
     message: str
 
-    binary_output: list[bytes]
-    csv_output: list[dict[str, Any]]
-    json_output: list[Any]
-    text_output: list[str]
+    binary_output: list[list[bytes]]
+    csv_output: list[list[dict[str, Any]]]
+    json_output: list[list[Any]]
+    text_output: list[list[str]]
 
     new_records: list[dict[str, FieldValue]]
 
@@ -67,24 +67,35 @@ class ToolOutput:
         ret_val += f"\tMessage: {self.message}\n"
         ret_val += "-" * 25 + "\n"
 
-        ret_val += f"Binary Output: {len(self.binary_output)} item(s)\n"
-        for binary in self.binary_output:
-            ret_val += f"\t{len(binary)} byte(s)\n"
-            ret_val += f"\t{binary[:50]}...\n"
-
-        ret_val += f"CSV Output: {len(self.csv_output)} item(s)\n"
-        if self.csv_output:
-            ret_val += f"\tHeaders: {', '.join(self.csv_output[0].keys())}\n"
-            for i, csv_row in enumerate(self.csv_output):
-                ret_val += f"\t{i}: {', '.join(f'{v}' for k, v in csv_row.items())}\n"
-
-        ret_val += f"JSON Output: {len(self.json_output)} item(s)\n"
-        if self.json_output:
-            ret_val += f"{json.dumps(self.json_output, indent=2)}\n"
-
-        ret_val += f"Text Output: {len(self.text_output)} item(s)\n"
-        for text in self.text_output:
-            ret_val += f"\t{text}\n"
+        ret_val += f"Binary Output: {sum(len(x) for x in self.binary_output)} item(s) across {len(self.binary_output)} outputs\n"
+        for i, output in enumerate(self.binary_output, start=1):
+            output: list[bytes]
+            ret_val += f"\tBinary Output {i}:\n"
+            for binary in output:
+                ret_val += f"\t\t{len(binary)} byte(s): {binary[:50]}...\n"
+
+        ret_val += f"CSV Output: {sum(len(x) for x in self.csv_output)} item(s) across {len(self.csv_output)} outputs\n"
+        for i, output in enumerate(self.csv_output, start=1):
+            output: list[dict[str, Any]]
+            ret_val += f"\tCSV Output {i}:\n"
+            ret_val += f"\t\tHeaders: {', '.join(output[0].keys())}\n"
+            for j, csv_row in enumerate(output):
+                ret_val += f"\t\t{j}: {', '.join(f'{v}' for k, v in csv_row.items())}\n"
+
+        ret_val += f"JSON Output: {sum(len(x) for x in self.json_output)} item(s) across {len(self.json_output)} outputs\n"
+        for i, output in enumerate(self.json_output, start=1):
+            output: list[Any]
+            ret_val += f"\tJSON Output {i}:\n"
+            for json_obj in output:
+                ret_val += f"\t\t"
+                ret_val += json.dumps(json_obj, indent=2).replace("\n", "\n\t\t") + "\n"
+
+        ret_val += f"Text Output: {sum(len(x) for x in self.text_output)} item(s) across {len(self.text_output)} outputs\n"
+        for i, output in enumerate(self.text_output, start=1):
+            output: list[str]
+            ret_val += f"\tText Output {i}:\n"
+            for text in output:
+                ret_val += f"\t\t{text}\n"
 
         ret_val += f"New Records: {len(self.new_records)} item(s)\n"
         for record in self.new_records:
@@ -277,14 +288,20 @@ class TestClient:
             for item in response.output:
                 container = item.item_container
 
-                results.binary_output.extend(container.binary_container.items)
-                for header in container.csv_container.header.cells:
-                    output_row: dict[str, Any] = {}
-                    for i, row in enumerate(container.csv_container.items):
-                        output_row[header] = row.cells[i]
-                    results.csv_output.append(output_row)
-                results.json_output.extend([json.loads(x) for x in container.json_container.items])
-                results.text_output.extend(container.text_container.items)
+                if container.HasField("binary_container"):
+                    results.binary_output.append(list(container.binary_container.items))
+                elif container.HasField("csv_container"):
+                    csv_output: list[dict[str, Any]] = []
+                    for header in container.csv_container.header.cells:
+                        output_row: dict[str, Any] = {}
+                        for i, row in enumerate(container.csv_container.items):
+                            output_row[header] = row.cells[i]
+                        csv_output.append(output_row)
+                    results.csv_output.append(csv_output)
+                elif container.HasField("json_container"):
+                    results.json_output.append([json.loads(x) for x in container.json_container.items])
+                elif container.HasField("text_container"):
+                    results.text_output.append(list(container.text_container.items))
 
             for record in response.new_records:
                 field_map: dict[str, Any] = {x: ProtobufUtils.field_pbo_to_value(y) for x, y in record.fields.items()}

{sapiopycommons-2025.8.20a713 → sapiopycommons-2025.9.8a728}/src/sapiopycommons/ai/tool_service_base.py

@@ -29,6 +29,7 @@ from sapiopycommons.ai.protoapi.session.sapio_conn_info_pb2 import SapioUserSecr
 from sapiopycommons.ai.protobuf_utils import ProtobufUtils
 from sapiopycommons.ai.test_client import ContainerType
 from sapiopycommons.files.file_util import FileUtil
+from sapiopycommons.files.temp_files import TempFileHandler
 from sapiopycommons.general.aliases import FieldMap, FieldValue
 
 
@@ -53,21 +54,26 @@ class BinaryResult(SapioToolResult):
     binary_data: list[bytes]
     content_type: str
     file_extensions: list[str]
+    name: str
 
-    def __init__(self, binary_data: list[bytes], content_type: str = "binary", file_extensions: list[str] = None):
+    def __init__(self, binary_data: list[bytes], content_type: str = "binary", file_extensions: list[str] = None,
+                 name: str | None = None):
         """
         :param binary_data: The binary data as a list of bytes.
         :param content_type: The content type of the data.
         :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.
         """
         self.binary_data = binary_data
         self.content_type = content_type
         self.file_extensions = file_extensions if file_extensions else []
+        self.name = name
 
     def to_proto(self) -> StepOutputBatchPbo | list[FieldValueMapPbo]:
         return StepOutputBatchPbo(
             item_container=StepItemContainerPbo(
                 content_type=ContentTypePbo(name=self.content_type, extensions=self.file_extensions),
+                container_name=self.name,
                 binary_container=StepBinaryContainerPbo(items=self.binary_data)
             )
         )
@@ -80,21 +86,26 @@ class CsvResult(SapioToolResult):
     csv_data: list[dict[str, Any]]
     content_type: str
     file_extensions: list[str]
+    name: str
 
-    def __init__(self, csv_data: list[dict[str, Any]], content_type: str = "csv", file_extensions: list[str] = None):
+    def __init__(self, csv_data: list[dict[str, Any]], content_type: str = "csv", file_extensions: list[str] = None,
+                 name: str | None = None):
         """
         :param csv_data: The list of CSV data results, provided as a list of dictionaries of column name to value.
         :param content_type: The content type of the data.
         :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.
         """
         self.csv_data = csv_data
         self.content_type = content_type
         self.file_extensions = file_extensions if file_extensions else ["csv"]
+        self.name = name
 
     def to_proto(self) -> StepOutputBatchPbo | list[FieldValueMapPbo]:
         return StepOutputBatchPbo(
             item_container=StepItemContainerPbo(
                 content_type=ContentTypePbo(name=self.content_type, extensions=self.file_extensions),
+                container_name=self.name,
                 csv_container=StepCsvContainerPbo(
                     header=StepCsvHeaderRowPbo(cells=self.csv_data[0].keys()),
                     items=[StepCsvRowPbo(cells=[str(x) for x in row.values()]) for row in self.csv_data]
@@ -143,22 +154,27 @@ class JsonResult(SapioToolResult):
     json_data: list[Any]
     content_type: str
     file_extensions: list[str]
+    name: str
 
-    def __init__(self, json_data: list[Any], content_type: str = "json", file_extensions: list[str] = None):
+    def __init__(self, json_data: list[Any], content_type: str = "json", file_extensions: list[str] = None,
+                 name: str | None = None):
         """
         :param json_data: The list of JSON data results. Each entry in the list represents a separate JSON object.
             These entries must be able to be serialized to JSON using json.dumps().
         :param content_type: The content type of the data.
         :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.
         """
         self.json_data = json_data
         self.content_type = content_type
         self.file_extensions = file_extensions if file_extensions else ["json"]
+        self.name = name
 
     def to_proto(self) -> StepOutputBatchPbo | list[FieldValueMapPbo]:
         return StepOutputBatchPbo(
             item_container=StepItemContainerPbo(
                 content_type=ContentTypePbo(name=self.content_type, extensions=self.file_extensions),
+                container_name=self.name,
                 json_container=StepJsonContainerPbo(items=[json.dumps(x) for x in self.json_data])
             )
         )
@@ -171,21 +187,26 @@ class TextResult(SapioToolResult):
     text_data: list[str]
     content_type: str
     file_extensions: list[str]
+    name: str
 
-    def __init__(self, text_data: list[str], content_type: str = "text", file_extensions: list[str] = None):
+    def __init__(self, text_data: list[str], content_type: str = "text", file_extensions: list[str] = None,
+                 name: str | None = None):
         """
         :param text_data: The text data as a list of strings.
         :param content_type: The content type of the data.
         :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.
         """
         self.text_data = text_data
         self.content_type = content_type
         self.file_extensions = file_extensions if file_extensions else ["txt"]
+        self.name = name
 
     def to_proto(self) -> StepOutputBatchPbo | list[FieldValueMapPbo]:
         return StepOutputBatchPbo(
             item_container=StepItemContainerPbo(
                 content_type=ContentTypePbo(name=self.content_type, extensions=self.file_extensions),
+                container_name=self.name,
                 text_container=StepTextContainerPbo(items=self.text_data)
             )
         )
@@ -298,8 +319,8 @@ class ToolServiceBase(ToolServiceServicer, ABC):
             # If the tool is not found, list all of the registered tools for this service so that the LLM can correct
             # the tool it is requesting.
             all_tool_names: str = "\n".join(registered_tools.keys())
-            msg: str = (f"Tool \"{find_tool}\" not found in the registered tools for this service. The registered tools "
-                        f"for this service are: \n{all_tool_names}")
+            msg: str = (f"Tool \"{find_tool}\" not found in the registered tools for this service. The registered "
+                        f"tools for this service are: \n{all_tool_names}")
             return False, msg, [], []
 
         # Instantiate the tool class.
@@ -309,7 +330,8 @@ class ToolServiceBase(ToolServiceServicer, ABC):
             tool.setup(user, request, context)
             # Validate that the provided inputs match the tool's expected inputs.
             if len(request.input) != len(tool.input_configs):
-                msg: str = f"Expected {len(tool.input_configs)} inputs for this tool, but got {len(request.input)} instead."
+                msg: str = (f"Expected {len(tool.input_configs)} inputs for this tool, but got {len(request.input)} "
+                            f"instead.")
             else:
                 msg: str = tool.validate_input()
             # If there is no error message, then the inputs are valid.
@@ -327,6 +349,9 @@ class ToolServiceBase(ToolServiceServicer, ABC):
         except Exception as e:
             tool.log_exception("Exception occurred during tool execution.", e)
             return False, str(e), [], tool.logs
+        finally:
+            # Clean up any temporary files created by the tool.
+            tool.temp_data.cleanup()
 
 
 class ToolBase(ABC):
@@ -346,6 +371,8 @@ class ToolBase(ABC):
     logger: Logger
     verbose_logging: bool
 
+    temp_data: TempFileHandler
+
     user: SapioUser
     request: ProcessStepRequestPbo
     context: ServicerContext
@@ -383,6 +410,7 @@ class ToolBase(ABC):
         self.output_configs = []
         self._output_container_types = []
         self.config_fields = []
+        self.temp_data = TempFileHandler()
         self.logs = []
         self.logger = logging.getLogger(f"ToolBase.{self._name}")
         ensure_logger_initialized(self.logger)
@@ -508,8 +536,8 @@ class ToolBase(ABC):
         """
         self.config_fields.append(ProtobufUtils.field_def_to_pbo(field))
 
-    def add_boolean_config_field(self, field_name: str, display_name: str, description: str, default_value: bool,
-                                 optional: bool = False) -> None:
+    def add_boolean_config_field(self, field_name: str, display_name: str, description: str,
+                                 default_value: bool | None = None, 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.
@@ -532,9 +560,9 @@ 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,
-                                optional: bool = False) -> None:
+    def add_double_config_field(self, field_name: str, display_name: str, description: str,
+                                default_value: float | None = 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.
@@ -564,7 +592,7 @@ 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,
+                                 default_value: int | None = None, 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
@@ -593,7 +621,8 @@ class ToolBase(ABC):
         ))
 
     def add_string_config_field(self, field_name: str, display_name: str, description: str,
-                                default_value: str, max_length: int = 1000, optional: bool = False) -> None:
+                                default_value: str | None = None, 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.
@@ -618,8 +647,9 @@ 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, optional: bool = False) -> None:
+    def add_list_config_field(self, field_name: str, display_name: str, description: str,
+                              default_value: str | None = None, allowed_values: list[str] | None = None,
+                              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.
@@ -648,8 +678,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,
-                                    optional: bool = False) -> None:
+                                    default_value: list[str] | None = None, allowed_values: list[str] | None = None,
+                                    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.
@@ -671,7 +701,7 @@ class ToolBase(ABC):
             required=not optional,
             editable=True,
             selection_properties=SelectionPropertiesPbo(
-                default_value=",".join(default_value),
+                default_value=",".join(default_value) if default_value else None,
                 static_list_values=allowed_values,
                 multi_select=True,
                 direct_edit=direct_edit,
@@ -817,6 +847,15 @@ class ToolBase(ABC):
         self.logs.append(f"EXCEPTION: {self._name}: {message} - {e}")
         self.logger.error(f"{message}\n{traceback.format_exc()}")
 
+    def get_input_name(self, index: int = 0) -> str | None:
+        """
+        Get the name of the input from the request object.
+
+        :param index: The index of the input to parse. Defaults to 0. Used for tools that accept multiple inputs.
+        :return: The name of the input from the request object, or None if no name is set.
+        """
+        return self.request.input[index].item_container.container_name
+
     def get_input_binary(self, index: int = 0) -> list[bytes]:
         """
         Get the binary data from the request object.

sapiopycommons-2025.9.8a728/src/sapiopycommons/files/temp_files.py

@@ -0,0 +1,49 @@
+import os
+import shutil
+import tempfile
+
+
+# FR-47422: Created class.
+class TempFileHandler:
+    """
+    A utility class to manage temporary files and directories.
+    """
+    directories: list[str]
+    files: list[str]
+
+    def __init__(self) -> None:
+        self.directories = []
+        self.files = []
+
+    def create_temp_directory(self) -> str:
+        """
+        :return: The path to a newly created temporary directory.
+        """
+        directory: str = tempfile.mkdtemp()
+        self.directories.append(directory)
+        return directory
+
+    def create_temp_file(self, data: str | bytes, suffix: str = "") -> str:
+        """
+        :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.
+        """
+        mode: str = 'w' if isinstance(data, str) else 'wb'
+        with tempfile.NamedTemporaryFile(mode=mode, suffix=suffix, delete=False) as tmp_file:
+            tmp_file.write(data)
+            file_path: str = tmp_file.name
+            self.files.append(file_path)
+        return file_path
+
+    def cleanup(self) -> None:
+        """
+        Delete all temporary files and directories created by this handler.
+        """
+        for directory in self.directories:
+            if os.path.exists(directory):
+                shutil.rmtree(directory)
+
+        for file_path in self.files:
+            if os.path.exists(file_path):
+                os.remove(file_path)