Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 14:45 UTC
fix(python): preserve nullable file upload arguments
jkomyno committed
Aug 25, 2026 at 04:09 UTC
cf25f2536330d553de84afc543869a4a51f39ba9
5 files changed
+290
-28
python/composio/core/models/_files.py
+66
-19
@@ -782,6 +782,17 @@ class FileHelper(WithLogger):
782
if schema.get(property_name, False):
783
return True
784
785
+ # The default execution path uses this walker as a cheap gate before
786
+ # dereferencing. Inspect both modern and legacy definition containers
787
+ # so a file flag reachable only through ``$ref`` still passes the gate.
788
+ for definitions_key in ("$defs", "definitions"):
789
+ definitions = schema.get(definitions_key)
790
+ if not isinstance(definitions, dict):
791
+ continue
792
+ for definition in definitions.values():
793
+ if self._has_file_property(definition, property_name):
794
+ return True
795
+
796
# Check anyOf variants
797
if "anyOf" in schema:
798
for variant in schema["anyOf"]:
@@ -1002,6 +1013,14 @@ class FileHelper(WithLogger):
1013
1014
return False
1015
1016
+ @staticmethod
1017
+ def _is_array_shaped_schema(schema: t.Dict) -> bool:
1018
+ """Return whether JSON Schema declares or infers an array shape."""
1019
+ schema_type = schema.get("type")
1020
+ if isinstance(schema_type, list):
1021
+ return "array" in schema_type
1022
+ return schema_type == "array" or (schema_type is None and "items" in schema)
1023
+
1024
def _find_schema_variant_with_file_property(
1025
self,
1026
schema: t.Dict,
@@ -1042,13 +1061,12 @@ class FileHelper(WithLogger):
1061
1062
@staticmethod
1063
def _drop_empty_file_value(value: t.Any) -> t.Any:
1045
- """Leaf handler: ``None``/``""`` at a file leaf mean "no file".
1064
+ """Omit an empty string from a file input when auto-upload is disabled.
1065
1047
- Neither is a staged ``{name, mimetype, s3key}`` descriptor, so the
1048
- backend rejects them with a validation error while callers (and the
1049
- playground UI) mean "absent". The walker omits the key instead.
1066
+ An explicit ``None`` remains part of the payload so nullable file fields,
1067
+ including required nullable fields, keep their JSON Schema semantics.
1068
"""
1051
- return _DELETE_VALUE if value is None or value == "" else value
1069
+ return _DELETE_VALUE if value == "" else value
1070
1071
def _upload_file_value(
1072
self,
@@ -1056,7 +1074,7 @@ class FileHelper(WithLogger):
1074
tool: Tool,
1075
before_file_upload: t.Optional[BeforeFileUpload],
1076
) -> t.Any:
1059
- if self._drop_empty_file_value(value) is _DELETE_VALUE:
1077
+ if value is None or self._drop_empty_file_value(value) is _DELETE_VALUE:
1078
return _DELETE_VALUE
1079
1080
return FileUploadable.from_path(
@@ -1087,17 +1105,41 @@ class FileHelper(WithLogger):
1105
if schema.get("file_uploadable", False):
1106
return leaf(value)
1107
1108
+ # Upload-enabled execution historically omits null file values, while
1109
+ # disabled execution preserves them for nullable schemas. The active
1110
+ # leaf handler owns that distinction.
1111
+ if value is None and self._file_uploadable(schema):
1112
+ return leaf(value)
1113
+
1114
uploadable_variant = self._find_uploadable_schema_variant(
1115
schema=schema,
1116
value=value,
1117
)
1118
if uploadable_variant is not None:
1119
+ # An empty string cannot match an array-only file input, but it may
1120
+ # match another non-file string variant in the same composition.
1121
+ if value == "" and self._is_array_shaped_schema(uploadable_variant):
1122
+ matching_non_file_variant = any(
1123
+ not self._file_uploadable(variant)
1124
+ and self._json_schema_type_matches_value(variant, value)
1125
+ for variant in self._schema_variants(schema)
1126
+ )
1127
+ if matching_non_file_variant:
1128
+ return value
1129
+ return leaf(value)
1130
return self._substitute_file_upload_value(
1131
value=value,
1132
schema=uploadable_variant,
1133
leaf=leaf,
1134
)
1135
1136
+ if (
1137
+ value == ""
1138
+ and self._is_array_shaped_schema(schema)
1139
+ and self._file_uploadable(schema)
1140
+ ):
1141
+ return leaf(value)
1142
+
1143
if isinstance(value, dict) and "properties" in schema:
1144
processed: t.Dict[str, t.Any] = {}
1145
properties = schema["properties"]
@@ -1191,30 +1233,35 @@ class FileHelper(WithLogger):
1233
)
1234
1235
def drop_empty_file_uploads(self, tool: Tool, request: t.Dict) -> t.Dict:
1194
- """Omit ``None``/``""`` at ``file_uploadable`` leaves without uploading.
1236
+ """Omit ``""`` at ``file_uploadable`` leaves without uploading.
1237
1238
This is the half of :meth:`substitute_file_uploads` that needs no
1239
filesystem access, so it runs even when automatic upload is disabled:
1240
an empty file value is never a valid staged descriptor and the backend
1199
- would reject it (issue #4233). Any other value -- a local path, a
1200
- staged descriptor, a list -- is forwarded untouched. Same mutation
1201
- contract as :meth:`substitute_file_uploads`.
1241
+ would reject it (issue #4233). Explicit ``None`` and every non-empty
1242
+ value are forwarded untouched. File-bearing request containers are
1243
+ rebuilt; unlike :meth:`substitute_file_uploads`, this method never
1244
+ mutates caller-owned arguments or copies arbitrary leaf objects.
1245
"""
1203
- schema = dereference_json_schema(
1204
- tool.input_parameters, on_unresolved="sentinel"
1205
- )
1246
# Every execution takes this path by default, so leave requests for
1207
- # tools without a file input completely alone (identity included)
1208
- # instead of rebuilding their nested dicts.
1209
- if not self._file_uploadable(schema):
1247
+ # tools without a file input completely alone. Check the raw schema
1248
+ # first to avoid paying the dereference cost for non-file tools.
1249
+ if not self._file_uploadable(tool.input_parameters):
1250
return request
1251
1212
- return self._substitute_file_uploads_recursively(
1213
- tool=tool,
1252
+ schema = dereference_json_schema(
1253
+ tool.input_parameters, on_unresolved="sentinel"
1254
+ )
1255
+ processed = self._substitute_file_upload_value(
1256
+ value=request,
1257
schema=schema,
1215
- request=request,
1258
leaf=self._drop_empty_file_value,
1259
)
1260
+ assert isinstance(processed, dict), (
1261
+ "expected dict from _substitute_file_upload_value at the root; "
1262
+ f"got {type(processed).__name__}"
1263
+ )
1264
+ return processed
1265
1266
def _is_file_downloadable(self, schema: t.Dict) -> bool:
1267
"""Check if a schema has file_downloadable property."""
python/composio/core/models/tools.py
+2
-1
@@ -682,7 +682,8 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
682
)
683
else:
684
# Auto-upload is opt-in, but "no file" must still be sent as an
685
- # omitted key rather than ``""``/``None`` (issue #4233).
685
+ # omitted key rather than ``""`` (issue #4233). Explicit ``None``
686
+ # remains valid for nullable file inputs.
687
arguments = self._file_helper.drop_empty_file_uploads(
688
tool=tool, request=arguments
689
)
python/tests/test_auto_upload_download_files.py
+5
-2
@@ -492,6 +492,7 @@ class TestAutoUploadDownloadFilesDisabled:
492
]
493
},
494
},
495
+ "required": ["attachment"],
496
},
497
)
498
mock_execute_response = Mock()
@@ -507,20 +508,22 @@ class TestAutoUploadDownloadFilesDisabled:
508
):
509
for value, expected in (
510
("", {"subject": "Test"}),
510
- (None, {"subject": "Test"}),
511
+ (None, {"subject": "Test", "attachment": None}),
512
(
513
"/path/to/file.txt",
514
{"subject": "Test", "attachment": "/path/to/file.txt"},
515
),
516
):
517
mock_client.tools.execute.reset_mock()
518
+ arguments = {"subject": "Test", "attachment": value}
519
tools.execute(
520
slug="GMAIL_CREATE_DRAFT",
519
- arguments={"subject": "Test", "attachment": value},
521
+ arguments=arguments,
522
dangerously_skip_version_check=True,
523
)
524
sent = mock_client.tools.execute.call_args.kwargs["arguments"]
525
assert sent == expected, value
526
+ assert arguments == {"subject": "Test", "attachment": value}
527
528
def test_execute_skips_file_downloads_when_disabled(
529
self, mock_client, mock_provider
python/tests/test_files.py
+166
-6
@@ -779,11 +779,10 @@ class TestFileUploadSubstitutionWithUnionTypes:
779
# None/empty values should be removed
780
assert "fileInput" not in result
781
782
- def test_drop_empty_file_uploads_omits_empty_leaves_without_uploading(
782
+ def test_drop_empty_file_uploads_omits_empty_strings_without_uploading(
783
self, file_helper, mock_tool
784
):
785
- """Issue #4233: ``""``/``None`` at a file leaf mean "no file" even when
786
- auto-upload is off, while any other value is forwarded untouched."""
785
+ """Disabled auto-upload omits empty strings but preserves explicit nulls."""
786
file_uploadable = {
787
"type": "object",
788
"file_uploadable": True,
@@ -817,6 +816,7 @@ class TestFileUploadSubstitutionWithUnionTypes:
816
"type": "object",
817
"properties": {"file": {"$ref": "#/$defs/F"}},
818
},
819
+ "opaque": {"type": "object", "additionalProperties": True},
820
"thread_id": {"type": "string"},
821
},
822
"$defs": {"F": file_uploadable},
@@ -827,6 +827,15 @@ class TestFileUploadSubstitutionWithUnionTypes:
827
"attachment": "",
828
"extra": [None, "", staged, "/tmp/keep.txt"],
829
"nested": {"file": None},
830
+ "opaque": {"preserve_identity": True},
831
+ "thread_id": "",
832
+ }
833
+ original_request = {
834
+ "subject": "Test",
835
+ "attachment": "",
836
+ "extra": [None, "", staged, "/tmp/keep.txt"],
837
+ "nested": {"file": None},
838
+ "opaque": {"preserve_identity": True},
839
"thread_id": "",
840
}
841
@@ -836,14 +845,165 @@ class TestFileUploadSubstitutionWithUnionTypes:
845
)
846
847
from_path.assert_not_called()
839
- assert result is request
848
+ assert result is not request
849
assert result == {
850
"subject": "Test",
842
- "extra": [staged, "/tmp/keep.txt"],
843
- "nested": {},
851
+ "extra": [None, staged, "/tmp/keep.txt"],
852
+ "nested": {"file": None},
853
+ "opaque": {"preserve_identity": True},
854
# non-file empty strings are not the walker's business
855
"thread_id": "",
856
}
857
+ assert result["extra"] is not request["extra"]
858
+ assert result["extra"][1] is request["extra"][2]
859
+ assert result["nested"] is not request["nested"]
860
+ assert result["opaque"] is request["opaque"]
861
+ assert request == original_request
862
+
863
+ def test_drop_empty_file_uploads_skips_dereference_for_non_file_schema(
864
+ self, file_helper, mock_tool
865
+ ):
866
+ """Default execution does not dereference schemas without file inputs."""
867
+ mock_tool.input_parameters = {
868
+ "type": "object",
869
+ "properties": {
870
+ "filters": {
871
+ "type": "object",
872
+ "properties": {"query": {"type": "string"}},
873
+ }
874
+ },
875
+ }
876
+ request = {"filters": {"query": "open"}}
877
+
878
+ with patch(
879
+ "composio.core.models._files.dereference_json_schema"
880
+ ) as dereference:
881
+ result = file_helper.drop_empty_file_uploads(
882
+ tool=mock_tool, request=request
883
+ )
884
+
885
+ assert result is request
886
+ dereference.assert_not_called()
887
+
888
+ @pytest.mark.parametrize(
889
+ ("definitions_key", "ref"),
890
+ [
891
+ ("$defs", "#/$defs/FileUploadable"),
892
+ ("definitions", "#/definitions/FileUploadable"),
893
+ ],
894
+ )
895
+ def test_drop_empty_file_uploads_resolves_referenced_file_schema(
896
+ self, file_helper, mock_tool, definitions_key, ref
897
+ ):
898
+ """The raw cheap gate still admits modern and legacy referenced schemas."""
899
+ mock_tool.input_parameters = {
900
+ "type": "object",
901
+ "properties": {"attachment": {"$ref": ref}},
902
+ definitions_key: {
903
+ "FileUploadable": {
904
+ "type": "object",
905
+ "file_uploadable": True,
906
+ }
907
+ },
908
+ }
909
+
910
+ result = file_helper.drop_empty_file_uploads(
911
+ tool=mock_tool, request={"attachment": ""}
912
+ )
913
+
914
+ assert result == {}
915
+
916
+ @pytest.mark.parametrize(
917
+ "attachment_schema",
918
+ [
919
+ {
920
+ "type": "array",
921
+ "items": {"type": "object", "file_uploadable": True},
922
+ },
923
+ {
924
+ "items": {"type": "object", "file_uploadable": True},
925
+ },
926
+ {
927
+ "anyOf": [
928
+ {
929
+ "type": "array",
930
+ "items": {"type": "object", "file_uploadable": True},
931
+ },
932
+ {"type": "null"},
933
+ ]
934
+ },
935
+ {
936
+ "anyOf": [
937
+ {
938
+ "items": {"type": "object", "file_uploadable": True},
939
+ },
940
+ {"type": "null"},
941
+ ]
942
+ },
943
+ ],
944
+ )
945
+ @pytest.mark.parametrize(
946
+ ("value", "expected_without_upload"),
947
+ [("", {}), (None, {"attachment": None})],
948
+ )
949
+ def test_empty_values_follow_mode_for_array_only_file_schema(
950
+ self, file_helper, mock_tool, attachment_schema, value, expected_without_upload
951
+ ):
952
+ """Array-only file inputs omit empty strings and upload-mode nulls."""
953
+ mock_tool.input_parameters = {
954
+ "type": "object",
955
+ "properties": {"attachment": attachment_schema},
956
+ }
957
+
958
+ dropped = file_helper.drop_empty_file_uploads(
959
+ tool=mock_tool, request={"attachment": value}
960
+ )
961
+ with patch.object(FileUploadable, "from_path") as from_path:
962
+ uploaded = file_helper.substitute_file_uploads(
963
+ tool=mock_tool, request={"attachment": value}
964
+ )
965
+
966
+ assert dropped == expected_without_upload
967
+ assert uploaded == {}
968
+ from_path.assert_not_called()
969
+
970
+ @pytest.mark.parametrize("array_type", ["explicit", "inferred"])
971
+ def test_empty_string_is_preserved_when_non_file_string_variant_matches(
972
+ self, file_helper, mock_tool, array_type
973
+ ):
974
+ """A composed string branch takes precedence over array-file cleanup."""
975
+ array_file_schema = {
976
+ "items": {
977
+ "type": "object",
978
+ "file_uploadable": True,
979
+ },
980
+ }
981
+ if array_type == "explicit":
982
+ array_file_schema["type"] = "array"
983
+
984
+ mock_tool.input_parameters = {
985
+ "type": "object",
986
+ "properties": {
987
+ "attachment": {
988
+ "anyOf": [
989
+ array_file_schema,
990
+ {"type": "string"},
991
+ ]
992
+ }
993
+ },
994
+ }
995
+
996
+ dropped = file_helper.drop_empty_file_uploads(
997
+ tool=mock_tool, request={"attachment": ""}
998
+ )
999
+ with patch.object(FileUploadable, "from_path") as from_path:
1000
+ uploaded = file_helper.substitute_file_uploads(
1001
+ tool=mock_tool, request={"attachment": ""}
1002
+ )
1003
+
1004
+ assert dropped == {"attachment": ""}
1005
+ assert uploaded == {"attachment": ""}
1006
+ from_path.assert_not_called()
1007
1008
def test_substitute_upload_empty_string_in_anyof(self, file_helper, mock_tool):
1009
"""Test that empty string values in anyOf with file_uploadable are handled."""
python/tests/test_tool_execution.py
+51
@@ -128,6 +128,57 @@ class TestToolExecution:
128
("after_execute", "composio"),
129
]
130
131
+ @pytest.mark.parametrize(
132
+ ("value", "expected"),
133
+ [
134
+ ("", {"metadata": {"source": "user"}}),
135
+ (
136
+ None,
137
+ {"attachment": None, "metadata": {"source": "user"}},
138
+ ),
139
+ ],
140
+ )
141
+ def test_tool_router_drops_only_empty_file_strings_without_mutating_arguments(
142
+ self, value, expected
143
+ ):
144
+ """Session execution matches direct execution for disabled auto-upload."""
145
+ mock_client = mock_http_client()
146
+ tools = Tools(client=mock_client, provider=Mock())
147
+ tool = self.create_mock_tool("GMAIL_CREATE_DRAFT", "gmail")
148
+ tool.input_parameters = {
149
+ "type": "object",
150
+ "properties": {
151
+ "attachment": {
152
+ "anyOf": [
153
+ {"type": "object", "file_uploadable": True},
154
+ {"type": "null"},
155
+ ]
156
+ },
157
+ "metadata": {
158
+ "type": "object",
159
+ "properties": {"source": {"type": "string"}},
160
+ },
161
+ },
162
+ "required": ["attachment"],
163
+ }
164
+ tools._tool_schemas[tool.slug] = tool
165
+ mock_client.tool_router.session.execute.return_value = Mock(data={}, error=None)
166
+ execute = tools._wrap_execute_tool_for_tool_router("session_123")
167
+ arguments = {
168
+ "attachment": value,
169
+ "metadata": {"source": "user"},
170
+ }
171
+
172
+ execute(tool.slug, arguments)
173
+
174
+ sent = mock_client.tool_router.session.execute.call_args.kwargs["arguments"]
175
+ assert sent == expected
176
+ assert arguments == {
177
+ "attachment": value,
178
+ "metadata": {"source": "user"},
179
+ }
180
+ assert sent["metadata"] is not arguments["metadata"]
181
+
182
def test_execute_without_toolkit_runs_modifiers_and_fetches_once(self):
183
"""Toolkit-less tools execute with the same fallback used by TypeScript."""
184
from composio.core.models._modifiers import after_execute, before_execute