@devries-cameron20 / composio-1 / commits / fccec8b14
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(python-sdk): handle file upload list unions (#3373)

## Summary This updates the Python SDK's automatic file upload/download substitution so it can handle tool schemas that accept either a single file or a list of files. Tools can expose file inputs as a union such as: ```json { "anyOf": [ { "type": "object", "file_uploadable": true }, { "type": "array", "items": { "type": "object", "file_uploadable": true } } ] } ``` When auto-upload is enabled, the SDK presents those file-uploadable objects to models as file path strings. If the model supplies a list of local paths, the old resolver selected the first file-bearing union branch, usually the single-file branch, and attempted to upload the entire Python list as one path. That fails before the backend ever receives the intended list of staged file descriptors. ## Changes - Refactors upload substitution into a value/schema recursive walker via `_substitute_file_upload_value`. - Adds the same value/schema traversal shape for downloads via `_substitute_file_download_value`. - Selects composed-schema variants by runtime shape when possible, so list values choose array branches and string/dict values keep the single-value behavior. - Preserves the existing fallback behavior: if no runtime shape matches, use the first file-bearing variant. - Treats `anyOf`, `oneOf`, and `allOf` consistently with the SDK's existing composed-schema convention. - Preserves root request/response dict mutation behavior for existing call sites. - Adds regression coverage for single-file vs multi-file unions, nested array-item unions, download parity, and first-match fallback. ## Why This is needed for file-capable tool schemas that are backward compatible at the API level by accepting both a single file and multiple files. The Python SDK should transform a list of local paths into a list of staged `{name, mimetype, s3key}` descriptors, just as it already does for direct array schemas. ## Verification - `python -m ruff check python/tests/test_files.py python/composio/core/models/_files.py` - `python -m pytest python/tests/test_files.py -q` -> 119 passed - `python -m pytest python/tests/test_files.py python/tests/test_auto_upload_download_files.py python/tests/test_upload_dir_allowlist.py python/tests/test_tool_router_session_files.py -q` -> 166 passed - Manual playground verification with a Gmail send using two local attachments: both files were staged and sent successfully as an attachment array. Note: a full local `python/tests` run still has three unrelated failures because `composio_langchain` is not installed in this environment; the affected file-upload suites pass. --------- Co-authored-by: Zen <zen@composio.dev>

Shrey Singla committed May 14, 2026 at 12:57 UTC fccec8b14304bd77e888b909b77bf66f548338ca
2 files changed +561 -263
python/composio/core/models/_files.py
+278 -263
@@ -58,6 +58,13 @@ Connect timeout is short to fail fast on unreachable hosts.
58 Read timeout is longer to allow for slower file transfers.
59 """
60
61 +_DELETE_VALUE: t.Final = object()
62 +"""
63 +Sentinel returned by the upload walker to signal that a value should be dropped
64 +from its parent container. ``None`` and ``""`` are both legal payload values, so
65 +the walker cannot use either to mean "remove this key/item".
66 +"""
67 +
68 LOCAL_CACHE_DIRECTORY_NAME = ".composio"
69 """
70 Local cache directory name for composio CLI
@@ -776,153 +783,197 @@ class FileHelper(WithLogger):
783 self.enhance_schema_descriptions(schema)
784 return schema
785
779 - def _find_uploadable_schema_variant(self, schema: t.Dict) -> t.Optional[t.Dict]:
780 - """Find a schema variant that contains file_uploadable properties."""
781 - # Check anyOf variants
782 - if "anyOf" in schema:
783 - for variant in schema["anyOf"]:
784 - if self._has_file_property(variant, "file_uploadable"):
785 - return variant
786 + def _schema_variants(self, schema: t.Dict) -> t.List[t.Dict]:
787 + """Return composed schema variants in the SDK's historical order."""
788 + variants: t.List[t.Dict] = []
789 + for key in ("anyOf", "oneOf", "allOf"):
790 + schema_variants = schema.get(key)
791 + if not isinstance(schema_variants, list):
792 + continue
793 + variants.extend(v for v in schema_variants if isinstance(v, dict))
794 + return variants
795 +
796 + def _json_schema_type_matches_value(self, schema: t.Dict, value: t.Any) -> bool:
797 + """Best-effort runtime shape match for selecting composed schemas."""
798 + schema_type = schema.get("type")
799 + if isinstance(schema_type, list):
800 + return any(
801 + self._json_schema_type_matches_value({**schema, "type": tpe}, value)
802 + for tpe in schema_type
803 + )
804
787 - # Check oneOf variants
788 - if "oneOf" in schema:
789 - for variant in schema["oneOf"]:
790 - if self._has_file_property(variant, "file_uploadable"):
791 - return variant
805 + if schema_type is None:
806 + if "properties" in schema:
807 + return isinstance(value, dict)
808 + if "items" in schema:
809 + return isinstance(value, list)
810 + return False
811
793 - # Check allOf - merge all variants
794 - if "allOf" in schema:
795 - for variant in schema["allOf"]:
796 - if self._has_file_property(variant, "file_uploadable"):
797 - return variant
812 + if schema_type == "array":
813 + return isinstance(value, list)
814 + if schema_type == "object":
815 + return isinstance(value, dict)
816 + if schema_type == "string":
817 + return isinstance(value, str)
818 + if schema_type == "integer":
819 + return isinstance(value, int) and not isinstance(value, bool)
820 + if schema_type == "number":
821 + return isinstance(value, (int, float)) and not isinstance(value, bool)
822 + if schema_type == "boolean":
823 + return isinstance(value, bool)
824 + if schema_type == "null":
825 + return value is None
826
799 - return None
827 + return False
828
801 - def _substitute_file_uploads_recursively(
829 + def _find_schema_variant_with_file_property(
830 self,
803 - tool: Tool,
831 schema: t.Dict,
805 - request: t.Dict,
832 + property_name: str,
833 + value: t.Any = None,
834 + ) -> t.Optional[t.Dict]:
835 + """Find the composed schema variant that should process a file value.
836 +
837 + ``anyOf``, ``oneOf`` and ``allOf`` are intentionally treated the same
838 + here, matching the SDK's existing convention. When a runtime value is
839 + available, prefer the file-bearing variant with the matching JSON Schema
840 + shape; otherwise keep the historical first-match behavior.
841 + """
842 + candidates = [
843 + variant
844 + for variant in self._schema_variants(schema)
845 + if self._has_file_property(variant, property_name)
846 + ]
847 + if not candidates:
848 + return None
849 +
850 + if value is not None:
851 + for candidate in candidates:
852 + if self._json_schema_type_matches_value(candidate, value):
853 + return candidate
854 +
855 + return candidates[0]
856 +
857 + def _find_uploadable_schema_variant(
858 + self, schema: t.Dict, value: t.Any = None
859 + ) -> t.Optional[t.Dict]:
860 + """Find a schema variant that contains file_uploadable properties."""
861 + return self._find_schema_variant_with_file_property(
862 + schema=schema,
863 + property_name="file_uploadable",
864 + value=value,
865 + )
866 +
867 + def _upload_file_value(
868 + self,
869 + value: t.Any,
870 + tool: Tool,
871 + before_file_upload: t.Optional[BeforeFileUpload],
872 + ) -> t.Any:
873 + if value is None or value == "":
874 + return _DELETE_VALUE
875 +
876 + return FileUploadable.from_path(
877 + client=self._client,
878 + file=value,
879 + tool=tool.slug,
880 + toolkit=tool.toolkit.slug,
881 + sensitive_file_upload_protection=self._sensitive_file_upload_protection,
882 + file_upload_path_deny_segments=self._file_upload_path_deny_segments,
883 + file_upload_allowlist=self._file_upload_allowlist,
884 + before_file_upload=before_file_upload,
885 + ).model_dump()
886 +
887 + def _substitute_file_upload_value(
888 + self,
889 + value: t.Any,
890 + schema: t.Optional[t.Dict],
891 + tool: Tool,
892 *,
893 before_file_upload: t.Optional[BeforeFileUpload] = None,
808 - ) -> t.Dict:
809 - if "properties" not in schema:
810 - return request
894 + ) -> t.Any:
895 + """Return ``value`` with file-uploadable leaves staged for execution."""
896 + if not isinstance(schema, dict):
897 + return value
898
812 - params = schema["properties"]
813 - for _param in list(request.keys()):
814 - if _param not in params:
815 - continue
899 + if schema.get("file_uploadable", False):
900 + return self._upload_file_value(
901 + value=value,
902 + tool=tool,
903 + before_file_upload=before_file_upload,
904 + )
905
817 - param_schema = params[_param]
818 -
819 - # Direct file_uploadable check
820 - if param_schema.get("file_uploadable", False):
821 - # skip if the file is not provided
822 - if request[_param] is None or request[_param] == "":
823 - del request[_param]
824 - continue
825 -
826 - request[_param] = FileUploadable.from_path(
827 - client=self._client,
828 - file=request[_param],
829 - tool=tool.slug,
830 - toolkit=tool.toolkit.slug,
831 - sensitive_file_upload_protection=self._sensitive_file_upload_protection,
832 - file_upload_path_deny_segments=self._file_upload_path_deny_segments,
833 - file_upload_allowlist=self._file_upload_allowlist,
834 - before_file_upload=before_file_upload,
835 - ).model_dump()
836 - continue
906 + uploadable_variant = self._find_uploadable_schema_variant(
907 + schema=schema,
908 + value=value,
909 + )
910 + if uploadable_variant is not None:
911 + return self._substitute_file_upload_value(
912 + value=value,
913 + schema=uploadable_variant,
914 + tool=tool,
915 + before_file_upload=before_file_upload,
916 + )
917
838 - # Check anyOf/oneOf/allOf for file_uploadable
839 - uploadable_variant = self._find_uploadable_schema_variant(param_schema)
840 - if uploadable_variant is not None:
841 - # If the variant itself is file_uploadable
842 - if uploadable_variant.get("file_uploadable", False):
843 - if request[_param] is None or request[_param] == "":
844 - del request[_param]
845 - continue
846 -
847 - request[_param] = FileUploadable.from_path(
848 - client=self._client,
849 - file=request[_param],
850 - tool=tool.slug,
851 - toolkit=tool.toolkit.slug,
852 - sensitive_file_upload_protection=self._sensitive_file_upload_protection,
853 - file_upload_path_deny_segments=self._file_upload_path_deny_segments,
854 - file_upload_allowlist=self._file_upload_allowlist,
855 - before_file_upload=before_file_upload,
856 - ).model_dump()
857 - continue
858 -
859 - # If the variant has nested properties with file_uploadable
860 - if (
861 - isinstance(request[_param], dict)
862 - and uploadable_variant.get("type") == "object"
863 - ):
864 - request[_param] = self._substitute_file_uploads_recursively(
865 - schema=uploadable_variant,
866 - request=request[_param],
867 - tool=tool,
868 - before_file_upload=before_file_upload,
869 - )
870 - continue
871 -
872 - # Handle nested objects
873 - if (
874 - isinstance(request[_param], dict)
875 - and param_schema.get("type") == "object"
876 - ):
877 - request[_param] = self._substitute_file_uploads_recursively(
878 - schema=param_schema,
879 - request=request[_param],
918 + if isinstance(value, dict) and "properties" in schema:
919 + processed: t.Dict[str, t.Any] = {}
920 + properties = schema["properties"]
921 + for key, item in value.items():
922 + item_schema = properties.get(key)
923 + processed_item = self._substitute_file_upload_value(
924 + value=item,
925 + schema=item_schema,
926 tool=tool,
927 before_file_upload=before_file_upload,
928 )
883 - continue
929 + if processed_item is not _DELETE_VALUE:
930 + processed[key] = processed_item
931 + return processed
932 +
933 + if isinstance(value, list) and "items" in schema:
934 + items_schema = schema["items"]
935 + if isinstance(items_schema, list):
936 + items_schema = items_schema[0] if items_schema else None
937 +
938 + processed_items: t.List[t.Any] = []
939 + for item in value:
940 + processed_item = self._substitute_file_upload_value(
941 + value=item,
942 + schema=items_schema,
943 + tool=tool,
944 + before_file_upload=before_file_upload,
945 + )
946 + if processed_item is not _DELETE_VALUE:
947 + processed_items.append(processed_item)
948 + return processed_items
949
885 - # Handle arrays with file_uploadable items
886 - if (
887 - isinstance(request[_param], list)
888 - and param_schema.get("type") == "array"
889 - and "items" in param_schema
890 - ):
891 - items_schema = param_schema["items"]
892 - if isinstance(items_schema, dict):
893 - processed_items: t.List[t.Any] = []
894 - for item in request[_param]:
895 - if self._has_file_property(items_schema, "file_uploadable"):
896 - if items_schema.get("file_uploadable", False):
897 - if item is not None and item != "":
898 - processed_items.append(
899 - FileUploadable.from_path(
900 - client=self._client,
901 - file=item,
902 - tool=tool.slug,
903 - toolkit=tool.toolkit.slug,
904 - sensitive_file_upload_protection=self._sensitive_file_upload_protection,
905 - file_upload_path_deny_segments=self._file_upload_path_deny_segments,
906 - file_upload_allowlist=self._file_upload_allowlist,
907 - before_file_upload=before_file_upload,
908 - ).model_dump()
909 - )
910 - elif isinstance(item, dict):
911 - processed_items.append(
912 - self._substitute_file_uploads_recursively(
913 - schema=items_schema,
914 - request=item,
915 - tool=tool,
916 - before_file_upload=before_file_upload,
917 - )
918 - )
919 - else:
920 - processed_items.append(item)
921 - else:
922 - processed_items.append(item)
923 - request[_param] = processed_items
924 -
925 - return request
950 + return value
951 +
952 + def _substitute_file_uploads_recursively(
953 + self,
954 + tool: Tool,
955 + schema: t.Dict,
956 + request: t.Dict,
957 + *,
958 + before_file_upload: t.Optional[BeforeFileUpload] = None,
959 + ) -> t.Dict:
960 + processed = self._substitute_file_upload_value(
961 + value=request,
962 + schema=schema,
963 + tool=tool,
964 + before_file_upload=before_file_upload,
965 + )
966 + if processed is request:
967 + return request
968 + if isinstance(processed, dict):
969 + request.clear()
970 + request.update(processed)
971 + return request
972 + assert isinstance(processed, dict), (
973 + "expected dict from _substitute_file_upload_value at the root; "
974 + f"got {type(processed).__name__}"
975 + )
976 + return processed
977
978 def substitute_file_uploads(
979 self,
@@ -931,6 +982,14 @@ class FileHelper(WithLogger):
982 *,
983 before_file_upload: t.Optional[BeforeFileUpload] = None,
984 ) -> t.Dict:
985 + """Stage file-uploadable leaves in ``request`` and return it.
986 +
987 + Mutation contract: the top-level ``request`` dict is mutated in place
988 + and its identity is preserved (the return value is the same object).
989 + Nested dicts inside ``request`` may be replaced with fresh dicts
990 + rather than mutated, so callers should not retain references to
991 + nested values across this call.
992 + """
993 return self._substitute_file_uploads_recursively(
994 tool=tool,
995 schema=tool.input_parameters,
@@ -942,155 +1001,111 @@ class FileHelper(WithLogger):
1001 """Check if a schema has file_downloadable property."""
1002 return self._has_file_property(schema, "file_downloadable")
1003
945 - def _find_downloadable_schema_variant(self, schema: t.Dict) -> t.Optional[t.Dict]:
1004 + def _find_downloadable_schema_variant(
1005 + self, schema: t.Dict, value: t.Any = None
1006 + ) -> t.Optional[t.Dict]:
1007 """Find a schema variant that contains file_downloadable properties."""
947 - # Check anyOf variants
948 - if "anyOf" in schema:
949 - for variant in schema["anyOf"]:
950 - if self._has_file_property(variant, "file_downloadable"):
951 - return variant
952 -
953 - # Check oneOf variants
954 - if "oneOf" in schema:
955 - for variant in schema["oneOf"]:
956 - if self._has_file_property(variant, "file_downloadable"):
957 - return variant
958 -
959 - # Check allOf variants
960 - if "allOf" in schema:
961 - for variant in schema["allOf"]:
962 - if self._has_file_property(variant, "file_downloadable"):
963 - return variant
1008 + return self._find_schema_variant_with_file_property(
1009 + schema=schema,
1010 + property_name="file_downloadable",
1011 + value=value,
1012 + )
1013
965 - return None
1014 + def _download_file_value(self, value: t.Any, tool: Tool) -> t.Any:
1015 + if isinstance(value, dict) and "s3url" in value:
1016 + return str(
1017 + FileDownloadable(**value).download(
1018 + self._outdir / tool.toolkit.slug / tool.slug
1019 + )
1020 + )
1021 + return value
1022
967 - def _substitute_file_downloads_recursively(
1023 + def _substitute_file_download_value(
1024 self,
1025 + value: t.Any,
1026 + schema: t.Optional[t.Dict],
1027 tool: Tool,
970 - schema: t.Dict,
971 - request: t.Dict,
972 - ) -> t.Dict:
973 - if "properties" not in schema:
974 - return request
975 -
976 - params = schema["properties"]
977 - for _param in list(request.keys()):
978 - if _param not in params:
979 - continue
980 -
981 - param_schema = params[_param]
982 - param_value = request[_param]
1028 + ) -> t.Any:
1029 + """Return ``value`` with file-downloadable leaves saved locally."""
1030 + if not isinstance(schema, dict):
1031 + return value
1032
984 - # Skip None values
985 - if param_value is None:
986 - continue
1033 + if schema.get("file_downloadable", False):
1034 + return self._download_file_value(value=value, tool=tool)
1035
988 - # Direct file_downloadable check
989 - if param_schema.get("file_downloadable", False):
990 - if isinstance(param_value, dict) and "s3url" in param_value:
991 - request[_param] = str(
992 - FileDownloadable(**param_value).download(
993 - self._outdir / tool.toolkit.slug / tool.slug
994 - )
995 - )
996 - continue
1036 + downloadable_variant = self._find_downloadable_schema_variant(
1037 + schema=schema,
1038 + value=value,
1039 + )
1040 + if downloadable_variant is not None:
1041 + return self._substitute_file_download_value(
1042 + value=value,
1043 + schema=downloadable_variant,
1044 + tool=tool,
1045 + )
1046
998 - # Check anyOf/oneOf/allOf for file_downloadable
999 - downloadable_variant = self._find_downloadable_schema_variant(param_schema)
1000 - if downloadable_variant is not None:
1001 - # If the variant itself is file_downloadable
1002 - if downloadable_variant.get("file_downloadable", False):
1003 - if isinstance(param_value, dict) and "s3url" in param_value:
1004 - request[_param] = str(
1005 - FileDownloadable(**param_value).download(
1006 - self._outdir / tool.toolkit.slug / tool.slug
1007 - )
1008 - )
1009 - continue
1010 -
1011 - # If the variant has nested properties with file_downloadable
1012 - if (
1013 - isinstance(param_value, dict)
1014 - and downloadable_variant.get("type") == "object"
1015 - ):
1016 - request[_param] = self._substitute_file_downloads_recursively(
1017 - schema=downloadable_variant,
1018 - request=param_value,
1019 - tool=tool,
1020 - )
1021 - continue
1047 + if isinstance(value, dict) and "properties" in schema:
1048 + properties = schema["properties"]
1049 + return {
1050 + key: self._substitute_file_download_value(
1051 + value=item,
1052 + schema=properties.get(key),
1053 + tool=tool,
1054 + )
1055 + for key, item in value.items()
1056 + }
1057
1023 - # Handle nested objects
1024 - if isinstance(param_value, dict) and param_schema.get("type") == "object":
1025 - request[_param] = self._substitute_file_downloads_recursively(
1026 - schema=param_schema,
1027 - request=param_value,
1058 + if isinstance(value, list) and "items" in schema:
1059 + items_schema = schema["items"]
1060 + if isinstance(items_schema, list):
1061 + items_schema = items_schema[0] if items_schema else None
1062 + return [
1063 + self._substitute_file_download_value(
1064 + value=item,
1065 + schema=items_schema,
1066 tool=tool,
1067 )
1030 - continue
1068 + for item in value
1069 + ]
1070
1032 - # Handle arrays with file_downloadable items
1033 - if (
1034 - isinstance(param_value, list)
1035 - and param_schema.get("type") == "array"
1036 - and "items" in param_schema
1037 - ):
1038 - items_schema = param_schema["items"]
1039 - if isinstance(items_schema, dict):
1040 - processed_items: t.List[t.Any] = []
1041 - for item in param_value:
1042 - if item is None:
1043 - processed_items.append(item)
1044 - continue
1045 -
1046 - if self._has_file_property(items_schema, "file_downloadable"):
1047 - if items_schema.get("file_downloadable", False):
1048 - if isinstance(item, dict) and "s3url" in item:
1049 - processed_items.append(
1050 - str(
1051 - FileDownloadable(**item).download(
1052 - self._outdir
1053 - / tool.toolkit.slug
1054 - / tool.slug
1055 - )
1056 - )
1057 - )
1058 - else:
1059 - processed_items.append(item)
1060 - elif isinstance(item, dict):
1061 - # Check for anyOf/oneOf/allOf in items schema
1062 - item_variant = self._find_downloadable_schema_variant(
1063 - items_schema
1064 - )
1065 - if item_variant is not None:
1066 - processed_items.append(
1067 - self._substitute_file_downloads_recursively(
1068 - schema=item_variant,
1069 - request=item,
1070 - tool=tool,
1071 - )
1072 - )
1073 - else:
1074 - processed_items.append(
1075 - self._substitute_file_downloads_recursively(
1076 - schema=items_schema,
1077 - request=item,
1078 - tool=tool,
1079 - )
1080 - )
1081 - else:
1082 - processed_items.append(item)
1083 - else:
1084 - processed_items.append(item)
1085 - request[_param] = processed_items
1086 -
1087 - return request
1071 + return value
1072 +
1073 + def _substitute_file_downloads_recursively(
1074 + self,
1075 + tool: Tool,
1076 + schema: t.Dict,
1077 + request: t.Dict,
1078 + ) -> t.Dict:
1079 + processed = self._substitute_file_download_value(
1080 + value=request,
1081 + schema=schema,
1082 + tool=tool,
1083 + )
1084 + if processed is request:
1085 + return request
1086 + if isinstance(processed, dict):
1087 + request.clear()
1088 + request.update(processed)
1089 + return request
1090 + assert isinstance(processed, dict), (
1091 + "expected dict from _substitute_file_download_value at the root; "
1092 + f"got {type(processed).__name__}"
1093 + )
1094 + return processed
1095
1096 def substitute_file_downloads(
1097 self,
1098 tool: Tool,
1099 response: ToolExecutionResponse,
1100 ) -> ToolExecutionResponse:
1101 + """Materialize file-downloadable leaves in ``response`` and return it.
1102 +
1103 + Mutation contract: the top-level ``response`` dict is mutated in
1104 + place and its identity is preserved (the return value is the same
1105 + object). Nested dicts inside ``response`` may be replaced with
1106 + fresh dicts rather than mutated, so callers should not retain
1107 + references to nested values across this call.
1108 + """
1109 return t.cast(
1110 "ToolExecutionResponse",
1111 self._substitute_file_downloads_recursively(
python/tests/test_files.py
+283
@@ -612,6 +612,161 @@ class TestFileUploadSubstitutionWithUnionTypes:
612 request={"content": {"attachment": "/path/to/file.pdf"}},
613 )
614
615 + @patch("composio.core.models._files.FileUploadable.from_path")
616 + def test_substitute_upload_anyof_single_or_array_prefers_array_for_list_value(
617 + self, mock_from_path, file_helper, mock_tool
618 + ):
619 + """List runtime values should use the array branch and upload each item."""
620 + mock_tool.input_parameters = {
621 + "type": "object",
622 + "properties": {
623 + "attachment": {
624 + "anyOf": [
625 + {"type": "string", "file_uploadable": True},
626 + {
627 + "type": "array",
628 + "items": {"type": "string", "file_uploadable": True},
629 + },
630 + ]
631 + }
632 + },
633 + }
634 +
635 + upload_1 = MagicMock()
636 + upload_1.model_dump.return_value = {
637 + "name": "a.txt",
638 + "mimetype": "text/plain",
639 + "s3key": "key-a",
640 + }
641 + upload_2 = MagicMock()
642 + upload_2.model_dump.return_value = {
643 + "name": "b.txt",
644 + "mimetype": "text/plain",
645 + "s3key": "key-b",
646 + }
647 + mock_from_path.side_effect = [upload_1, upload_2]
648 +
649 + request = {"attachment": ["/tmp/a.txt", "/tmp/b.txt"]}
650 + result = file_helper._substitute_file_uploads_recursively(
651 + tool=mock_tool,
652 + schema=mock_tool.input_parameters,
653 + request=request,
654 + )
655 +
656 + assert result is request
657 + assert result["attachment"] == [
658 + {"name": "a.txt", "mimetype": "text/plain", "s3key": "key-a"},
659 + {"name": "b.txt", "mimetype": "text/plain", "s3key": "key-b"},
660 + ]
661 + assert [call.kwargs["file"] for call in mock_from_path.call_args_list] == [
662 + "/tmp/a.txt",
663 + "/tmp/b.txt",
664 + ]
665 +
666 + @patch("composio.core.models._files.FileUploadable.from_path")
667 + def test_substitute_upload_anyof_single_or_array_keeps_string_behavior(
668 + self, mock_from_path, file_helper, mock_tool
669 + ):
670 + """String runtime values should still use the single-file branch."""
671 + mock_tool.input_parameters = {
672 + "type": "object",
673 + "properties": {
674 + "attachment": {
675 + "anyOf": [
676 + {"type": "string", "file_uploadable": True},
677 + {
678 + "type": "array",
679 + "items": {"type": "string", "file_uploadable": True},
680 + },
681 + ]
682 + }
683 + },
684 + }
685 +
686 + upload = MagicMock()
687 + upload.model_dump.return_value = {
688 + "name": "a.txt",
689 + "mimetype": "text/plain",
690 + "s3key": "key-a",
691 + }
692 + mock_from_path.return_value = upload
693 +
694 + result = file_helper._substitute_file_uploads_recursively(
695 + tool=mock_tool,
696 + schema=mock_tool.input_parameters,
697 + request={"attachment": "/tmp/a.txt"},
698 + )
699 +
700 + assert result["attachment"] == {
701 + "name": "a.txt",
702 + "mimetype": "text/plain",
703 + "s3key": "key-a",
704 + }
705 + mock_from_path.assert_called_once()
706 + assert mock_from_path.call_args.kwargs["file"] == "/tmp/a.txt"
707 +
708 + @patch("composio.core.models._files.FileUploadable.from_path")
709 + def test_substitute_upload_array_items_with_anyof_file_branch(
710 + self, mock_from_path, file_helper, mock_tool
711 + ):
712 + """Array item schemas can contain file-uploadable union branches."""
713 + mock_tool.input_parameters = {
714 + "type": "object",
715 + "properties": {
716 + "attachments": {
717 + "type": "array",
718 + "items": {
719 + "anyOf": [
720 + {"type": "string", "file_uploadable": True},
721 + {"type": "null"},
722 + ]
723 + },
724 + }
725 + },
726 + }
727 +
728 + upload_1 = MagicMock()
729 + upload_1.model_dump.return_value = {"s3key": "key-a"}
730 + upload_2 = MagicMock()
731 + upload_2.model_dump.return_value = {"s3key": "key-b"}
732 + mock_from_path.side_effect = [upload_1, upload_2]
733 +
734 + result = file_helper._substitute_file_uploads_recursively(
735 + tool=mock_tool,
736 + schema=mock_tool.input_parameters,
737 + request={"attachments": ["/tmp/a.txt", None, "", "/tmp/b.txt"]},
738 + )
739 +
740 + assert result["attachments"] == [{"s3key": "key-a"}, {"s3key": "key-b"}]
741 + assert [call.kwargs["file"] for call in mock_from_path.call_args_list] == [
742 + "/tmp/a.txt",
743 + "/tmp/b.txt",
744 + ]
745 +
746 + @patch("composio.core.models._files.FileUploadable.from_path")
747 + def test_substitute_upload_array_drops_all_null_and_empty_items(
748 + self, mock_from_path, file_helper, mock_tool
749 + ):
750 + """Array of file-uploadable items collapses to [] when every item is null/empty."""
751 + mock_tool.input_parameters = {
752 + "type": "object",
753 + "properties": {
754 + "attachments": {
755 + "type": "array",
756 + "items": {"type": "string", "file_uploadable": True},
757 + }
758 + },
759 + }
760 +
761 + result = file_helper._substitute_file_uploads_recursively(
762 + tool=mock_tool,
763 + schema=mock_tool.input_parameters,
764 + request={"attachments": [None, "", None]},
765 + )
766 +
767 + assert result["attachments"] == []
768 + mock_from_path.assert_not_called()
769 +
770
771 class TestFileDownloadSubstitutionWithUnionTypes:
772 """Test cases for file download substitution with anyOf, oneOf, and allOf schemas."""
@@ -792,6 +947,95 @@ class TestFileDownloadSubstitutionWithUnionTypes:
947 },
948 )
949
950 + @patch("composio.core.models._files.FileDownloadable.download")
951 + def test_substitute_download_anyof_single_or_array_prefers_array_for_list_value(
952 + self, mock_download, file_helper, mock_tool
953 + ):
954 + """List runtime values should use the array branch and download each item."""
955 + mock_tool.output_parameters = {
956 + "type": "object",
957 + "properties": {
958 + "attachment": {
959 + "anyOf": [
960 + {"type": "object", "file_downloadable": True},
961 + {
962 + "type": "array",
963 + "items": {"type": "object", "file_downloadable": True},
964 + },
965 + ]
966 + }
967 + },
968 + }
969 + mock_download.side_effect = ["/tmp/a.txt", "/tmp/b.txt"]
970 +
971 + request = {
972 + "attachment": [
973 + {
974 + "s3url": "https://s3.example.com/a.txt",
975 + "mimetype": "text/plain",
976 + "name": "a.txt",
977 + },
978 + {
979 + "s3url": "https://s3.example.com/b.txt",
980 + "mimetype": "text/plain",
981 + "name": "b.txt",
982 + },
983 + ]
984 + }
985 + result = file_helper._substitute_file_downloads_recursively(
986 + tool=mock_tool,
987 + schema=mock_tool.output_parameters,
988 + request=request,
989 + )
990 +
991 + assert result is request
992 + assert result["attachment"] == ["/tmp/a.txt", "/tmp/b.txt"]
993 + assert mock_download.call_count == 2
994 +
995 + @patch("composio.core.models._files.FileDownloadable.download")
996 + def test_substitute_download_array_items_with_anyof_file_branch(
997 + self, mock_download, file_helper, mock_tool
998 + ):
999 + """Array item schemas can contain file-downloadable union branches."""
1000 + mock_tool.output_parameters = {
1001 + "type": "object",
1002 + "properties": {
1003 + "attachments": {
1004 + "type": "array",
1005 + "items": {
1006 + "anyOf": [
1007 + {"type": "object", "file_downloadable": True},
1008 + {"type": "null"},
1009 + ]
1010 + },
1011 + }
1012 + },
1013 + }
1014 + mock_download.side_effect = ["/tmp/a.txt", "/tmp/b.txt"]
1015 +
1016 + result = file_helper._substitute_file_downloads_recursively(
1017 + tool=mock_tool,
1018 + schema=mock_tool.output_parameters,
1019 + request={
1020 + "attachments": [
1021 + {
1022 + "s3url": "https://s3.example.com/a.txt",
1023 + "mimetype": "text/plain",
1024 + "name": "a.txt",
1025 + },
1026 + None,
1027 + {
1028 + "s3url": "https://s3.example.com/b.txt",
1029 + "mimetype": "text/plain",
1030 + "name": "b.txt",
1031 + },
1032 + ]
1033 + },
1034 + )
1035 +
1036 + assert result["attachments"] == ["/tmp/a.txt", None, "/tmp/b.txt"]
1037 + assert mock_download.call_count == 2
1038 +
1039
1040 class TestFileHelperFindVariantMethods:
1041 """Test cases for _find_uploadable_schema_variant and _find_downloadable_schema_variant."""
@@ -843,6 +1087,45 @@ class TestFileHelperFindVariantMethods:
1087 result = file_helper._find_uploadable_schema_variant(schema)
1088 assert result is None
1089
1090 + def test_find_uploadable_variant_prefers_runtime_value_shape(self, file_helper):
1091 + """Runtime values should select the matching file-bearing schema shape."""
1092 + schema = {
1093 + "anyOf": [
1094 + {"type": "string", "file_uploadable": True},
1095 + {
1096 + "type": "array",
1097 + "items": {"type": "string", "file_uploadable": True},
1098 + },
1099 + ]
1100 + }
1101 +
1102 + result = file_helper._find_uploadable_schema_variant(
1103 + schema,
1104 + value=["/tmp/a.txt", "/tmp/b.txt"],
1105 + )
1106 +
1107 + assert result is not None
1108 + assert result["type"] == "array"
1109 +
1110 + def test_find_uploadable_variant_falls_back_to_first_file_bearing_variant(
1111 + self, file_helper
1112 + ):
1113 + """No runtime shape match should preserve historical first-match behavior."""
1114 + schema = {
1115 + "anyOf": [
1116 + {"type": "string", "file_uploadable": True},
1117 + {
1118 + "type": "array",
1119 + "items": {"type": "string", "file_uploadable": True},
1120 + },
1121 + ]
1122 + }
1123 +
1124 + result = file_helper._find_uploadable_schema_variant(schema, value=123)
1125 +
1126 + assert result is not None
1127 + assert result["type"] == "string"
1128 +
1129 def test_find_downloadable_variant_in_anyof(self, file_helper):
1130 """Test finding downloadable variant in anyOf."""
1131 schema = {