Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
core(py): add `auto_upload_download_files` boolean flag to `Composio()` (#2334)
Alberto Schiabel2f879e84863c
diff --git a/python/composio/core/models/_files.py b/python/composio/core/models/_files.pyindex e84c86c1e..36f5d315c 100644--- a/python/composio/core/models/_files.py+++ b/python/composio/core/models/_files.py@@ -182,14 +182,18 @@ class FileHelper(WithLogger):"title": schema.get("title"),}- def process_schema_recursively(self, schema: t.Dict) -> t.Dict:+ def enhance_schema_descriptions(self, schema: t.Dict) -> t.Dict:+ """Add type hints and required notes to parameter descriptions.++ This method enhances parameter descriptions by adding:+ - Type hints ("Please provide a value of type...")+ - Required notes ("This parameter is required.")++ This is separate from file processing and should always run+ regardless of the auto_upload_download_files setting.+ """required = schema.get("required") or []for _param, _schema in schema["properties"].items():- if self._file_uploadable(schema=_schema):- schema["properties"][_param] = self._process_file_uploadable(- schema=_schema- )-if _schema.get("type") in ["string", "integer", "number", "boolean"]:ext = f"Please provide a value of type {_schema['type']}."description = _schema.get("description", "").rstrip(".")@@ -204,6 +208,29 @@ class FileHelper(WithLogger):)return schema+ def process_file_uploadable_schema(self, schema: t.Dict) -> t.Dict:+ """Process file_uploadable fields in schema.++ This method converts file_uploadable fields to path format.+ Should only be called when auto_upload_download_files is True.+ """+ for _param, _schema in schema["properties"].items():+ if self._file_uploadable(schema=_schema):+ schema["properties"][_param] = self._process_file_uploadable(+ schema=_schema+ )+ return schema++ def process_schema_recursively(self, schema: t.Dict) -> t.Dict:+ """Process schema for both file handling and description enhancements.++ This method is kept for backward compatibility. It calls both+ process_file_uploadable_schema and enhance_schema_descriptions.+ """+ self.process_file_uploadable_schema(schema)+ self.enhance_schema_descriptions(schema)+ return schema+def _substitute_file_uploads_recursively(self,tool: Tool,diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.pyindex eeab85881..d93a5e8f1 100644--- a/python/composio/core/models/tool_router.py+++ b/python/composio/core/models/tool_router.py@@ -319,15 +319,18 @@ class ToolRouter(Resource, t.Generic[TProvider]):self,client: HttpClient,provider: t.Optional[TProvider] = None,+ auto_upload_download_files: bool = True,):"""Initialize ToolRouter instance.:param client: HTTP client for API calls:param provider: Optional provider for tool wrapping+ :param auto_upload_download_files: Whether to automatically upload and download files. Defaults to True."""super().__init__(client)self._provider = provider+ self._auto_upload_download_files = auto_upload_download_filesdef _create_mcp_server_config(self,@@ -578,6 +581,7 @@ class ToolRouter(Resource, t.Generic[TProvider]):tools_model = ToolsModel(client=self._client,provider=self._provider,+ auto_upload_download_files=self._auto_upload_download_files,)def tools_fn(modifiers: t.Optional[Modifiers] = None) -> t.Any:@@ -652,14 +656,23 @@ class ToolRouter(Resource, t.Generic[TProvider]):for tool in router_tools]- # Process file schemas+ # Always enhance schema descriptions (type hints and required notes)for tool in router_tools:tool.input_parameters = (- tools_model._file_helper.process_schema_recursively(+ tools_model._file_helper.enhance_schema_descriptions(schema=tool.input_parameters,))+ # Process file uploadable schemas+ if self._auto_upload_download_files:+ for tool in router_tools:+ tool.input_parameters = (+ tools_model._file_helper.process_file_uploadable_schema(+ schema=tool.input_parameters,+ )+ )+# Wrap tools with providerif issubclass(type(self._provider), NonAgenticProvider):return t.cast(NonAgenticProvider, self._provider).wrap_tools(diff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.pyindex 19fb5d8e8..d06014c5f 100644--- a/python/composio/core/models/tools.py+++ b/python/composio/core/models/tools.py@@ -61,6 +61,7 @@ class Tools(Resource, t.Generic[TProvider]):provider: TProvider,file_download_dir: t.Optional[str] = None,toolkit_versions: t.Optional[ToolkitVersionParam] = None,+ auto_upload_download_files: bool = True,):"""Initialize the tools resource.@@ -69,12 +70,14 @@ class Tools(Resource, t.Generic[TProvider])::param provider: The provider to use for the tools resource.:param file_download_dir: Output directory for downloadable files:param toolkit_versions: The versions of the toolkits to use. Defaults to 'latest' if not provided.+ :param auto_upload_download_files: Whether to automatically upload and download files. Defaults to True."""self._client = clientself._custom_tools = CustomTools(client)self._tool_schemas: t.Dict[str, Tool] = {}self._file_helper = FileHelper(client=self._client, outdir=file_download_dir)self._toolkit_versions = toolkit_versions+ self._auto_upload_download_files = auto_upload_download_filesself.custom_tool = self._custom_tools.registerself.provider = provider@@ -192,11 +195,23 @@ class Tools(Resource, t.Generic[TProvider]):self._tool_schemas.update({tool.slug: tool.model_copy(deep=True) for tool in tools_list})++ # Always enhance schema descriptions (type hints and required notes)+ # regardless of auto_upload_download_files settingfor tool in tools_list:- tool.input_parameters = self._file_helper.process_schema_recursively(+ tool.input_parameters = self._file_helper.enhance_schema_descriptions(schema=tool.input_parameters,)+ # Only process file_uploadable schemas when auto_upload_download_files is True+ if self._auto_upload_download_files:+ for tool in tools_list:+ tool.input_parameters = (+ self._file_helper.process_file_uploadable_schema(+ schema=tool.input_parameters,+ )+ )+if issubclass(type(self.provider), NonAgenticProvider):return t.cast(NonAgenticProvider, self.provider).wrap_tools(tools=tools_list@@ -559,10 +574,11 @@ class Tools(Resource, t.Generic[TProvider]):"dangerously_skip_version_check", dangerously_skip_version_check)- arguments = self._file_helper.substitute_file_uploads(- tool=tool,- request=arguments,- )+ if self._auto_upload_download_files:+ arguments = self._file_helper.substitute_file_uploads(+ tool=tool,+ request=arguments,+ )response = (self._execute_custom_tool(slug=slug,@@ -582,10 +598,11 @@ class Tools(Resource, t.Generic[TProvider]):dangerously_skip_version_check=dangerously_skip_version_check,))- response = self._file_helper.substitute_file_downloads(- tool=tool,- response=response,- )+ if self._auto_upload_download_files:+ response = self._file_helper.substitute_file_downloads(+ tool=tool,+ response=response,+ )if modifiers is not None:response = apply_modifier_by_type(modifiers=modifiers,diff --git a/python/composio/sdk.py b/python/composio/sdk.pyindex cf1217e93..f1eb65b3e 100644--- a/python/composio/sdk.py+++ b/python/composio/sdk.py@@ -35,6 +35,7 @@ class SDKConfig(te.TypedDict):allow_tracking: te.NotRequired[bool]file_download_dir: te.NotRequired[str]toolkit_versions: te.NotRequired[ToolkitVersionParam]+ auto_upload_download_files: te.NotRequired[bool]# class ExperimentalNamespace:@@ -76,6 +77,7 @@ class Composio(t.Generic[TProvider], WithLogger):- A dictionary mapping toolkit names to specific versions- A string (e.g., 'latest', '20250906_01') to use the same version for all toolkits- None or omitted to use 'latest' as default+ :param auto_upload_download_files: Whether to automatically upload and download files. Defaults to True."""WithLogger.__init__(self)api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))@@ -100,6 +102,7 @@ class Composio(t.Generic[TProvider], WithLogger):provider=self.provider,file_download_dir=kwargs.get("file_download_dir"),toolkit_versions=toolkit_versions,+ auto_upload_download_files=kwargs.get("auto_upload_download_files", True),)self.toolkits = Toolkits(client=self._client)@@ -112,6 +115,7 @@ class Composio(t.Generic[TProvider], WithLogger):self.tool_router = ToolRouter(client=self._client,provider=self.provider,+ auto_upload_download_files=kwargs.get("auto_upload_download_files", True),)self.create = self.tool_router.createself.use = self.tool_router.usediff --git a/python/tests/test_auto_upload_download_files.py b/python/tests/test_auto_upload_download_files.pynew file mode 100644index 000000000..e4694256e--- /dev/null+++ b/python/tests/test_auto_upload_download_files.py@@ -0,0 +1,493 @@+"""Tests for auto_upload_download_files feature in Composio SDK.++This module tests the auto_upload_download_files configuration option that controls+automatic file upload and download behavior during tool execution.+"""++from unittest.mock import Mock, patch++import pytest++from composio.client.types import Tool, tool_list_response+from composio.core.models.base import allow_tracking+from composio.core.models.tools import Tools++[email protected](autouse=True)+def disable_telemetry():+ """Disable telemetry for all tests to prevent thread issues."""+ token = allow_tracking.set(False)+ yield+ allow_tracking.reset(token)+++def mock_client():+ """Create a mock HTTP client."""+ return Mock()+++def mock_provider():+ """Create a mock provider."""+ provider = Mock()+ provider.name = "test_provider"+ return provider+++def create_mock_tool(+ slug: str,+ toolkit_slug: str,+ input_parameters: dict | None = None,+ output_parameters: dict | None = None,+) -> Tool:+ """Create a mock tool for testing."""+ return Tool(+ name=f"Test {slug}",+ slug=slug,+ description="Test tool",+ input_parameters=input_parameters or {"type": "object", "properties": {}},+ output_parameters=output_parameters or {"type": "object", "properties": {}},+ available_versions=["v1.0.0"],+ version="v1.0.0",+ scopes=[],+ toolkit=tool_list_response.ItemToolkit(+ name=toolkit_slug.title(), slug=toolkit_slug, logo=""+ ),+ deprecated=tool_list_response.ItemDeprecated(+ available_versions=["v1.0.0"],+ displayName=f"Test {slug}",+ version="v1.0.0",+ toolkit=tool_list_response.ItemDeprecatedToolkit(logo=""),+ is_deprecated=False,+ ),+ is_deprecated=False,+ no_auth=False,+ tags=[],+ )+++class TestAutoUploadDownloadFilesEnabled:+ """Test cases when auto_upload_download_files is enabled."""++ def test_get_processes_schema_for_file_uploadable(self, mock_client, mock_provider):+ """Test that _get processes schema when auto_upload_download_files is True."""+ tools = Tools(+ client=mock_client,+ provider=mock_provider,+ auto_upload_download_files=True,+ toolkit_versions={"test_toolkit": "20251201_01"},+ )++ # Create tool with file_uploadable field+ mock_tool = create_mock_tool(+ slug="TEST_TOOL",+ toolkit_slug="test_toolkit",+ input_parameters={+ "type": "object",+ "properties": {+ "file": {+ "type": "string",+ "file_uploadable": True,+ "description": "Upload a file",+ },+ "text": {"type": "string"},+ },+ },+ )++ # Mock client.tools.list+ mock_client.tools.list.return_value = Mock(items=[mock_tool])++ # Mock provider.wrap_tools+ mock_provider.wrap_tools = Mock(return_value=[])++ # Get tools+ tools._get(user_id="test-user", tools=["TEST_TOOL"])++ # Verify schema was processed (format: "path" added to file_uploadable field)+ wrap_tools_call = mock_provider.wrap_tools.call_args+ processed_tools = wrap_tools_call[1]["tools"]+ file_param = processed_tools[0].input_parameters["properties"]["file"]++ # Check that file_uploadable schema was converted to path format+ assert file_param.get("format") == "path"+ assert file_param.get("type") == "string"++ def test_execute_calls_substitute_file_uploads(self, mock_client, mock_provider):+ """Test that execute calls substitute_file_uploads when enabled."""+ tools = Tools(+ client=mock_client,+ provider=mock_provider,+ auto_upload_download_files=True,+ toolkit_versions={"test_toolkit": "20251201_01"},+ )++ mock_tool = create_mock_tool(+ slug="TEST_TOOL",+ toolkit_slug="test_toolkit",+ input_parameters={+ "type": "object",+ "properties": {+ "file": {"type": "string", "file_uploadable": True},+ },+ },+ output_parameters={+ "type": "object",+ "properties": {},+ },+ )++ with patch.object(+ tools, "get_raw_composio_tool_by_slug", return_value=mock_tool+ ):+ mock_execute_response = Mock()+ mock_execute_response.model_dump.return_value = {+ "data": {"result": "success"},+ "error": None,+ "successful": True,+ }+ mock_client.tools.execute.return_value = mock_execute_response++ # Patch both substitute methods to verify substitute_file_uploads is called+ with (+ patch.object(+ tools._file_helper, "substitute_file_uploads"+ ) as mock_upload,+ patch.object(+ tools._file_helper, "substitute_file_downloads"+ ) as mock_download,+ ):+ mock_upload.return_value = {"file": "processed_path"}+ mock_download.return_value = {+ "data": {"result": "success"},+ "error": None,+ "successful": True,+ }++ tools.execute(+ slug="TEST_TOOL",+ arguments={"file": "/path/to/file.txt"},+ dangerously_skip_version_check=True,+ )++ mock_upload.assert_called_once()++ def test_execute_calls_substitute_file_downloads(self, mock_client, mock_provider):+ """Test that execute calls substitute_file_downloads when enabled."""+ tools = Tools(+ client=mock_client,+ provider=mock_provider,+ auto_upload_download_files=True,+ toolkit_versions={"test_toolkit": "20251201_01"},+ )++ mock_tool = create_mock_tool(+ slug="TEST_TOOL",+ toolkit_slug="test_toolkit",+ input_parameters={+ "type": "object",+ "properties": {},+ },+ output_parameters={+ "type": "object",+ "properties": {+ "file": {"type": "object", "file_downloadable": True},+ },+ },+ )++ with patch.object(+ tools, "get_raw_composio_tool_by_slug", return_value=mock_tool+ ):+ mock_execute_response = Mock()+ mock_execute_response.model_dump.return_value = {+ "data": {+ "file": {+ "name": "result.txt",+ "mimetype": "text/plain",+ "s3url": "https://s3.example.com/result.txt",+ }+ },+ "error": None,+ "successful": True,+ }+ mock_client.tools.execute.return_value = mock_execute_response++ # Patch both substitute methods to verify substitute_file_downloads is called+ with (+ patch.object(+ tools._file_helper, "substitute_file_uploads"+ ) as mock_upload,+ patch.object(+ tools._file_helper, "substitute_file_downloads"+ ) as mock_download,+ ):+ mock_upload.return_value = {}+ mock_download.return_value = {+ "data": {"file": "/downloaded/result.txt"},+ "error": None,+ "successful": True,+ }++ tools.execute(+ slug="TEST_TOOL",+ arguments={},+ dangerously_skip_version_check=True,+ )++ mock_download.assert_called_once()+++class TestAutoUploadDownloadFilesDisabled:+ """Test cases when auto_upload_download_files is disabled."""++ def test_get_does_not_process_file_uploadable_when_disabled(+ self, mock_client, mock_provider+ ):+ """Test that _get does not process file_uploadable fields when auto_upload_download_files is False."""+ tools = Tools(+ client=mock_client,+ provider=mock_provider,+ auto_upload_download_files=False,+ toolkit_versions={"test_toolkit": "20251201_01"},+ )++ # Create tool with file_uploadable field+ mock_tool = create_mock_tool(+ slug="TEST_TOOL",+ toolkit_slug="test_toolkit",+ input_parameters={+ "type": "object",+ "properties": {+ "file": {+ "type": "string",+ "file_uploadable": True,+ "description": "Upload a file",+ },+ },+ },+ )++ # Mock client.tools.list+ mock_client.tools.list.return_value = Mock(items=[mock_tool])++ # Mock provider.wrap_tools+ mock_provider.wrap_tools = Mock(return_value=[])++ # Get tools+ tools._get(user_id="test-user", tools=["TEST_TOOL"])++ # Verify file_uploadable schema was NOT processed (not converted to path format)+ wrap_tools_call = mock_provider.wrap_tools.call_args+ processed_tools = wrap_tools_call[1]["tools"]+ file_param = processed_tools[0].input_parameters["properties"]["file"]++ # Should NOT have format: "path" since auto_upload_download_files is False+ assert file_param.get("format") is None+ assert file_param.get("file_uploadable") is True++ def test_get_still_enhances_descriptions_when_disabled(+ self, mock_client, mock_provider+ ):+ """Test that _get still adds type hints and required notes when auto_upload_download_files is False.++ The auto_upload_download_files flag should only control file upload/download behavior,+ not the description enhancements (type hints and required notes).+ """+ tools = Tools(+ client=mock_client,+ provider=mock_provider,+ auto_upload_download_files=False,+ toolkit_versions={"test_toolkit": "20251201_01"},+ )++ # Create tool with various parameter types+ mock_tool = create_mock_tool(+ slug="TEST_TOOL",+ toolkit_slug="test_toolkit",+ input_parameters={+ "type": "object",+ "required": ["required_param"],+ "properties": {+ "text_param": {+ "type": "string",+ "description": "A text parameter",+ },+ "required_param": {+ "type": "integer",+ "description": "A required parameter",+ },+ },+ },+ )++ # Mock client.tools.list+ mock_client.tools.list.return_value = Mock(items=[mock_tool])++ # Mock provider.wrap_tools+ mock_provider.wrap_tools = Mock(return_value=[])++ # Get tools+ tools._get(user_id="test-user", tools=["TEST_TOOL"])++ # Verify description enhancements were applied+ wrap_tools_call = mock_provider.wrap_tools.call_args+ processed_tools = wrap_tools_call[1]["tools"]+ props = processed_tools[0].input_parameters["properties"]++ # Type hints should be added+ assert (+ "Please provide a value of type string"+ in props["text_param"]["description"]+ )+ assert (+ "Please provide a value of type integer"+ in props["required_param"]["description"]+ )++ # Required notes should be added+ assert "This parameter is required" in props["required_param"]["description"]++ def test_execute_skips_file_uploads_when_disabled(self, mock_client, mock_provider):+ """Test that execute does not call substitute_file_uploads when disabled."""+ tools = Tools(+ client=mock_client,+ provider=mock_provider,+ auto_upload_download_files=False,+ toolkit_versions={"test_toolkit": "20251201_01"},+ )++ mock_tool = create_mock_tool(+ slug="TEST_TOOL",+ toolkit_slug="test_toolkit",+ input_parameters={+ "type": "object",+ "properties": {+ "file": {"type": "string", "file_uploadable": True},+ },+ },+ )++ with patch.object(+ tools, "get_raw_composio_tool_by_slug", return_value=mock_tool+ ):+ mock_execute_response = Mock()+ mock_execute_response.model_dump.return_value = {+ "data": {"result": "success"},+ "error": None,+ "successful": True,+ }+ mock_client.tools.execute.return_value = mock_execute_response++ # Patch substitute_file_uploads to verify it's NOT called+ with patch.object(+ tools._file_helper, "substitute_file_uploads"+ ) as mock_substitute:+ tools.execute(+ slug="TEST_TOOL",+ arguments={"file": "/path/to/file.txt"},+ dangerously_skip_version_check=True,+ )++ mock_substitute.assert_not_called()++ def test_execute_skips_file_downloads_when_disabled(+ self, mock_client, mock_provider+ ):+ """Test that execute does not call substitute_file_downloads when disabled."""+ tools = Tools(+ client=mock_client,+ provider=mock_provider,+ auto_upload_download_files=False,+ toolkit_versions={"test_toolkit": "20251201_01"},+ )++ mock_tool = create_mock_tool(+ slug="TEST_TOOL",+ toolkit_slug="test_toolkit",+ output_parameters={+ "type": "object",+ "properties": {+ "file": {"type": "object", "file_downloadable": True},+ },+ },+ )++ with patch.object(+ tools, "get_raw_composio_tool_by_slug", return_value=mock_tool+ ):+ mock_execute_response = Mock()+ mock_execute_response.model_dump.return_value = {+ "data": {+ "file": {+ "name": "result.txt",+ "mimetype": "text/plain",+ "s3url": "https://s3.example.com/result.txt",+ }+ },+ "error": None,+ "successful": True,+ }+ mock_client.tools.execute.return_value = mock_execute_response++ # Patch substitute_file_downloads to verify it's NOT called+ with patch.object(+ tools._file_helper, "substitute_file_downloads"+ ) as mock_substitute:+ result = tools.execute(+ slug="TEST_TOOL",+ arguments={},+ dangerously_skip_version_check=True,+ )++ mock_substitute.assert_not_called()++ # Verify raw S3 URL is preserved in response+ assert (+ result["data"]["file"]["s3url"]+ == "https://s3.example.com/result.txt"+ )+++class TestAutoUploadDownloadFilesWithSDK:+ """Test cases for auto_upload_download_files with SDK initialization."""++ def test_sdk_passes_auto_upload_download_files_to_tools(self):+ """Test that Composio SDK passes auto_upload_download_files to Tools."""+ from composio.sdk import Composio++ with patch("composio.sdk.HttpClient"):+ # Test with default (True)+ with patch.object(Tools, "__init__", return_value=None) as mock_init:+ mock_provider = Mock()+ mock_provider.name = "test"++ Composio(+ provider=mock_provider,+ api_key="test-key",+ )++ # Should have passed auto_upload_download_files=True (default)+ mock_init.assert_called()+ call_kwargs = mock_init.call_args[1]+ assert call_kwargs.get("auto_upload_download_files", True) is True++ def test_sdk_passes_false_to_tools(self):+ """Test that Composio SDK correctly passes auto_upload_download_files=False."""+ from composio.sdk import Composio++ with patch("composio.sdk.HttpClient"):+ with patch.object(Tools, "__init__", return_value=None) as mock_init:+ mock_provider = Mock()+ mock_provider.name = "test"++ Composio(+ provider=mock_provider,+ api_key="test-key",+ auto_upload_download_files=False,+ )++ mock_init.assert_called()+ call_kwargs = mock_init.call_args[1]+ assert call_kwargs.get("auto_upload_download_files") is Falsediff --git a/python/tests/test_sdk.py b/python/tests/test_sdk.pyindex fdaac40d2..749276272 100644--- a/python/tests/test_sdk.py+++ b/python/tests/test_sdk.py@@ -56,6 +56,7 @@ class TestComposioSDK:"allow_tracking","file_download_dir","toolkit_versions",+ "auto_upload_download_files",}assert set(SDKConfig.__annotations__.keys()) == expected_fieldsdiff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.pyindex c9e4bc0ed..1b88f6d85 100644--- a/python/tests/test_tool_router.py+++ b/python/tests/test_tool_router.py@@ -762,7 +762,7 @@ class TestToolRouter:# Verify Tools was instantiatedmock_tools_class.assert_called_once_with(- client=mock_client, provider=mock_provider+ client=mock_client, provider=mock_provider, auto_upload_download_files=True)# Verify get_raw_composio_tools was called