Skip to content

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): preserve nullable file upload arguments

jkomynocf25f2536330
diff --git a/python/composio/core/models/_files.py b/python/composio/core/models/_files.py
index 39de3b2b5..0746c0ea6 100644
--- a/python/composio/core/models/_files.py
+++ b/python/composio/core/models/_files.py
@@ -782,6 +782,17 @@ class FileHelper(WithLogger):
if schema.get(property_name, False):
return True
+ # The default execution path uses this walker as a cheap gate before
+ # dereferencing. Inspect both modern and legacy definition containers
+ # so a file flag reachable only through ``$ref`` still passes the gate.
+ for definitions_key in ("$defs", "definitions"):
+ definitions = schema.get(definitions_key)
+ if not isinstance(definitions, dict):
+ continue
+ for definition in definitions.values():
+ if self._has_file_property(definition, property_name):
+ return True
+
# Check anyOf variants
if "anyOf" in schema:
for variant in schema["anyOf"]:
@@ -1002,6 +1013,14 @@ class FileHelper(WithLogger):
return False
+ @staticmethod
+ def _is_array_shaped_schema(schema: t.Dict) -> bool:
+ """Return whether JSON Schema declares or infers an array shape."""
+ schema_type = schema.get("type")
+ if isinstance(schema_type, list):
+ return "array" in schema_type
+ return schema_type == "array" or (schema_type is None and "items" in schema)
+
def _find_schema_variant_with_file_property(
self,
schema: t.Dict,
@@ -1042,13 +1061,12 @@ class FileHelper(WithLogger):
@staticmethod
def _drop_empty_file_value(value: t.Any) -> t.Any:
- """Leaf handler: ``None``/``""`` at a file leaf mean "no file".
+ """Omit an empty string from a file input when auto-upload is disabled.
- Neither is a staged ``{name, mimetype, s3key}`` descriptor, so the
- backend rejects them with a validation error while callers (and the
- playground UI) mean "absent". The walker omits the key instead.
+ An explicit ``None`` remains part of the payload so nullable file fields,
+ including required nullable fields, keep their JSON Schema semantics.
"""
- return _DELETE_VALUE if value is None or value == "" else value
+ return _DELETE_VALUE if value == "" else value
def _upload_file_value(
self,
@@ -1056,7 +1074,7 @@ class FileHelper(WithLogger):
tool: Tool,
before_file_upload: t.Optional[BeforeFileUpload],
) -> t.Any:
- if self._drop_empty_file_value(value) is _DELETE_VALUE:
+ if value is None or self._drop_empty_file_value(value) is _DELETE_VALUE:
return _DELETE_VALUE
return FileUploadable.from_path(
@@ -1087,17 +1105,41 @@ class FileHelper(WithLogger):
if schema.get("file_uploadable", False):
return leaf(value)
+ # Upload-enabled execution historically omits null file values, while
+ # disabled execution preserves them for nullable schemas. The active
+ # leaf handler owns that distinction.
+ if value is None and self._file_uploadable(schema):
+ return leaf(value)
+
uploadable_variant = self._find_uploadable_schema_variant(
schema=schema,
value=value,
)
if uploadable_variant is not None:
+ # An empty string cannot match an array-only file input, but it may
+ # match another non-file string variant in the same composition.
+ if value == "" and self._is_array_shaped_schema(uploadable_variant):
+ matching_non_file_variant = any(
+ not self._file_uploadable(variant)
+ and self._json_schema_type_matches_value(variant, value)
+ for variant in self._schema_variants(schema)
+ )
+ if matching_non_file_variant:
+ return value
+ return leaf(value)
return self._substitute_file_upload_value(
value=value,
schema=uploadable_variant,
leaf=leaf,
)
+ if (
+ value == ""
+ and self._is_array_shaped_schema(schema)
+ and self._file_uploadable(schema)
+ ):
+ return leaf(value)
+
if isinstance(value, dict) and "properties" in schema:
processed: t.Dict[str, t.Any] = {}
properties = schema["properties"]
@@ -1191,30 +1233,35 @@ class FileHelper(WithLogger):
)
def drop_empty_file_uploads(self, tool: Tool, request: t.Dict) -> t.Dict:
- """Omit ``None``/``""`` at ``file_uploadable`` leaves without uploading.
+ """Omit ``""`` at ``file_uploadable`` leaves without uploading.
This is the half of :meth:`substitute_file_uploads` that needs no
filesystem access, so it runs even when automatic upload is disabled:
an empty file value is never a valid staged descriptor and the backend
- would reject it (issue #4233). Any other value -- a local path, a
- staged descriptor, a list -- is forwarded untouched. Same mutation
- contract as :meth:`substitute_file_uploads`.
+ would reject it (issue #4233). Explicit ``None`` and every non-empty
+ value are forwarded untouched. File-bearing request containers are
+ rebuilt; unlike :meth:`substitute_file_uploads`, this method never
+ mutates caller-owned arguments or copies arbitrary leaf objects.
"""
- schema = dereference_json_schema(
- tool.input_parameters, on_unresolved="sentinel"
- )
# Every execution takes this path by default, so leave requests for
- # tools without a file input completely alone (identity included)
- # instead of rebuilding their nested dicts.
- if not self._file_uploadable(schema):
+ # tools without a file input completely alone. Check the raw schema
+ # first to avoid paying the dereference cost for non-file tools.
+ if not self._file_uploadable(tool.input_parameters):
return request
- return self._substitute_file_uploads_recursively(
- tool=tool,
+ schema = dereference_json_schema(
+ tool.input_parameters, on_unresolved="sentinel"
+ )
+ processed = self._substitute_file_upload_value(
+ value=request,
schema=schema,
- request=request,
leaf=self._drop_empty_file_value,
)
+ assert isinstance(processed, dict), (
+ "expected dict from _substitute_file_upload_value at the root; "
+ f"got {type(processed).__name__}"
+ )
+ return processed
def _is_file_downloadable(self, schema: t.Dict) -> bool:
"""Check if a schema has file_downloadable property."""
diff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.py
index 1fabec06f..90a62c5a0 100644
--- a/python/composio/core/models/tools.py
+++ b/python/composio/core/models/tools.py
@@ -682,7 +682,8 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
)
else:
# Auto-upload is opt-in, but "no file" must still be sent as an
- # omitted key rather than ``""``/``None`` (issue #4233).
+ # omitted key rather than ``""`` (issue #4233). Explicit ``None``
+ # remains valid for nullable file inputs.
arguments = self._file_helper.drop_empty_file_uploads(
tool=tool, request=arguments
)
diff --git a/python/tests/test_auto_upload_download_files.py b/python/tests/test_auto_upload_download_files.py
index 0b3212593..dd0e00cf6 100644
--- a/python/tests/test_auto_upload_download_files.py
+++ b/python/tests/test_auto_upload_download_files.py
@@ -492,6 +492,7 @@ class TestAutoUploadDownloadFilesDisabled:
]
},
},
+ "required": ["attachment"],
},
)
mock_execute_response = Mock()
@@ -507,20 +508,22 @@ class TestAutoUploadDownloadFilesDisabled:
):
for value, expected in (
("", {"subject": "Test"}),
- (None, {"subject": "Test"}),
+ (None, {"subject": "Test", "attachment": None}),
(
"/path/to/file.txt",
{"subject": "Test", "attachment": "/path/to/file.txt"},
),
):
mock_client.tools.execute.reset_mock()
+ arguments = {"subject": "Test", "attachment": value}
tools.execute(
slug="GMAIL_CREATE_DRAFT",
- arguments={"subject": "Test", "attachment": value},
+ arguments=arguments,
dangerously_skip_version_check=True,
)
sent = mock_client.tools.execute.call_args.kwargs["arguments"]
assert sent == expected, value
+ assert arguments == {"subject": "Test", "attachment": value}
def test_execute_skips_file_downloads_when_disabled(
self, mock_client, mock_provider
diff --git a/python/tests/test_files.py b/python/tests/test_files.py
index fbaa0889a..ef27e5ffd 100644
--- a/python/tests/test_files.py
+++ b/python/tests/test_files.py
@@ -779,11 +779,10 @@ class TestFileUploadSubstitutionWithUnionTypes:
# None/empty values should be removed
assert "fileInput" not in result
- def test_drop_empty_file_uploads_omits_empty_leaves_without_uploading(
+ def test_drop_empty_file_uploads_omits_empty_strings_without_uploading(
self, file_helper, mock_tool
):
- """Issue #4233: ``""``/``None`` at a file leaf mean "no file" even when
- auto-upload is off, while any other value is forwarded untouched."""
+ """Disabled auto-upload omits empty strings but preserves explicit nulls."""
file_uploadable = {
"type": "object",
"file_uploadable": True,
@@ -817,6 +816,7 @@ class TestFileUploadSubstitutionWithUnionTypes:
"type": "object",
"properties": {"file": {"$ref": "#/$defs/F"}},
},
+ "opaque": {"type": "object", "additionalProperties": True},
"thread_id": {"type": "string"},
},
"$defs": {"F": file_uploadable},
@@ -827,6 +827,15 @@ class TestFileUploadSubstitutionWithUnionTypes:
"attachment": "",
"extra": [None, "", staged, "/tmp/keep.txt"],
"nested": {"file": None},
+ "opaque": {"preserve_identity": True},
+ "thread_id": "",
+ }
+ original_request = {
+ "subject": "Test",
+ "attachment": "",
+ "extra": [None, "", staged, "/tmp/keep.txt"],
+ "nested": {"file": None},
+ "opaque": {"preserve_identity": True},
"thread_id": "",
}
@@ -836,14 +845,165 @@ class TestFileUploadSubstitutionWithUnionTypes:
)
from_path.assert_not_called()
- assert result is request
+ assert result is not request
assert result == {
"subject": "Test",
- "extra": [staged, "/tmp/keep.txt"],
- "nested": {},
+ "extra": [None, staged, "/tmp/keep.txt"],
+ "nested": {"file": None},
+ "opaque": {"preserve_identity": True},
# non-file empty strings are not the walker's business
"thread_id": "",
}
+ assert result["extra"] is not request["extra"]
+ assert result["extra"][1] is request["extra"][2]
+ assert result["nested"] is not request["nested"]
+ assert result["opaque"] is request["opaque"]
+ assert request == original_request
+
+ def test_drop_empty_file_uploads_skips_dereference_for_non_file_schema(
+ self, file_helper, mock_tool
+ ):
+ """Default execution does not dereference schemas without file inputs."""
+ mock_tool.input_parameters = {
+ "type": "object",
+ "properties": {
+ "filters": {
+ "type": "object",
+ "properties": {"query": {"type": "string"}},
+ }
+ },
+ }
+ request = {"filters": {"query": "open"}}
+
+ with patch(
+ "composio.core.models._files.dereference_json_schema"
+ ) as dereference:
+ result = file_helper.drop_empty_file_uploads(
+ tool=mock_tool, request=request
+ )
+
+ assert result is request
+ dereference.assert_not_called()
+
+ @pytest.mark.parametrize(
+ ("definitions_key", "ref"),
+ [
+ ("$defs", "#/$defs/FileUploadable"),
+ ("definitions", "#/definitions/FileUploadable"),
+ ],
+ )
+ def test_drop_empty_file_uploads_resolves_referenced_file_schema(
+ self, file_helper, mock_tool, definitions_key, ref
+ ):
+ """The raw cheap gate still admits modern and legacy referenced schemas."""
+ mock_tool.input_parameters = {
+ "type": "object",
+ "properties": {"attachment": {"$ref": ref}},
+ definitions_key: {
+ "FileUploadable": {
+ "type": "object",
+ "file_uploadable": True,
+ }
+ },
+ }
+
+ result = file_helper.drop_empty_file_uploads(
+ tool=mock_tool, request={"attachment": ""}
+ )
+
+ assert result == {}
+
+ @pytest.mark.parametrize(
+ "attachment_schema",
+ [
+ {
+ "type": "array",
+ "items": {"type": "object", "file_uploadable": True},
+ },
+ {
+ "items": {"type": "object", "file_uploadable": True},
+ },
+ {
+ "anyOf": [
+ {
+ "type": "array",
+ "items": {"type": "object", "file_uploadable": True},
+ },
+ {"type": "null"},
+ ]
+ },
+ {
+ "anyOf": [
+ {
+ "items": {"type": "object", "file_uploadable": True},
+ },
+ {"type": "null"},
+ ]
+ },
+ ],
+ )
+ @pytest.mark.parametrize(
+ ("value", "expected_without_upload"),
+ [("", {}), (None, {"attachment": None})],
+ )
+ def test_empty_values_follow_mode_for_array_only_file_schema(
+ self, file_helper, mock_tool, attachment_schema, value, expected_without_upload
+ ):
+ """Array-only file inputs omit empty strings and upload-mode nulls."""
+ mock_tool.input_parameters = {
+ "type": "object",
+ "properties": {"attachment": attachment_schema},
+ }
+
+ dropped = file_helper.drop_empty_file_uploads(
+ tool=mock_tool, request={"attachment": value}
+ )
+ with patch.object(FileUploadable, "from_path") as from_path:
+ uploaded = file_helper.substitute_file_uploads(
+ tool=mock_tool, request={"attachment": value}
+ )
+
+ assert dropped == expected_without_upload
+ assert uploaded == {}
+ from_path.assert_not_called()
+
+ @pytest.mark.parametrize("array_type", ["explicit", "inferred"])
+ def test_empty_string_is_preserved_when_non_file_string_variant_matches(
+ self, file_helper, mock_tool, array_type
+ ):
+ """A composed string branch takes precedence over array-file cleanup."""
+ array_file_schema = {
+ "items": {
+ "type": "object",
+ "file_uploadable": True,
+ },
+ }
+ if array_type == "explicit":
+ array_file_schema["type"] = "array"
+
+ mock_tool.input_parameters = {
+ "type": "object",
+ "properties": {
+ "attachment": {
+ "anyOf": [
+ array_file_schema,
+ {"type": "string"},
+ ]
+ }
+ },
+ }
+
+ dropped = file_helper.drop_empty_file_uploads(
+ tool=mock_tool, request={"attachment": ""}
+ )
+ with patch.object(FileUploadable, "from_path") as from_path:
+ uploaded = file_helper.substitute_file_uploads(
+ tool=mock_tool, request={"attachment": ""}
+ )
+
+ assert dropped == {"attachment": ""}
+ assert uploaded == {"attachment": ""}
+ from_path.assert_not_called()
def test_substitute_upload_empty_string_in_anyof(self, file_helper, mock_tool):
"""Test that empty string values in anyOf with file_uploadable are handled."""
diff --git a/python/tests/test_tool_execution.py b/python/tests/test_tool_execution.py
index 3677394c6..21107dc1d 100644
--- a/python/tests/test_tool_execution.py
+++ b/python/tests/test_tool_execution.py
@@ -128,6 +128,57 @@ class TestToolExecution:
("after_execute", "composio"),
]
+ @pytest.mark.parametrize(
+ ("value", "expected"),
+ [
+ ("", {"metadata": {"source": "user"}}),
+ (
+ None,
+ {"attachment": None, "metadata": {"source": "user"}},
+ ),
+ ],
+ )
+ def test_tool_router_drops_only_empty_file_strings_without_mutating_arguments(
+ self, value, expected
+ ):
+ """Session execution matches direct execution for disabled auto-upload."""
+ mock_client = mock_http_client()
+ tools = Tools(client=mock_client, provider=Mock())
+ tool = self.create_mock_tool("GMAIL_CREATE_DRAFT", "gmail")
+ tool.input_parameters = {
+ "type": "object",
+ "properties": {
+ "attachment": {
+ "anyOf": [
+ {"type": "object", "file_uploadable": True},
+ {"type": "null"},
+ ]
+ },
+ "metadata": {
+ "type": "object",
+ "properties": {"source": {"type": "string"}},
+ },
+ },
+ "required": ["attachment"],
+ }
+ tools._tool_schemas[tool.slug] = tool
+ mock_client.tool_router.session.execute.return_value = Mock(data={}, error=None)
+ execute = tools._wrap_execute_tool_for_tool_router("session_123")
+ arguments = {
+ "attachment": value,
+ "metadata": {"source": "user"},
+ }
+
+ execute(tool.slug, arguments)
+
+ sent = mock_client.tool_router.session.execute.call_args.kwargs["arguments"]
+ assert sent == expected
+ assert arguments == {
+ "attachment": value,
+ "metadata": {"source": "user"},
+ }
+ assert sent["metadata"] is not arguments["metadata"]
+
def test_execute_without_toolkit_runs_modifiers_and_fetches_once(self):
"""Toolkit-less tools execute with the same fallback used by TypeScript."""
from composio.core.models._modifiers import after_execute, before_execute