@devries-cameron20 / composio-1 / commits / a14f9d537
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(py): normalize toolkit-less tool metadata (#4178)

This PR: - closes #4152 - normalizes model- and mapping-shaped tool responses at the Python SDK boundary - uses `unknown` for direct/schema modifiers and `composio` for Tool Router execution, matching TypeScript - caches the untouched fetched tool before schema modifiers so execution keeps the original toolkit version metadata - reuses the cached tool during execution instead of retrieving the same schema twice - adds behavior regressions for schema, before/after execution, single-fetch execution, raw metadata preservation, and TypeScript parity - verifies the Python regressions against both the current Stainless client and `ComposioHQ/composio-client` at `605f508e`

Alberto Schiabel committed Aug 20, 2026 at 15:00 UTC a14f9d537fd5396a2c3144c1e981de519b4e3e60
4 files changed +275 -47
python/composio/core/models/tools.py
+60 -42
@@ -2,15 +2,17 @@ from __future__ import annotations
2
3 import functools
4 import typing as t
5 +from collections.abc import Mapping
6 from pathlib import Path
7
8 import typing_extensions as te
8 -from pydantic import BaseModel as PydanticBaseModel
9 from composio_client import omit
10 +from pydantic import BaseModel as PydanticBaseModel
11
12 from composio.client import HttpClient
13 from composio.client.types import (
14 Tool,
15 + ToolkitMinimal,
16 tool_execute_params,
17 tool_proxy_params,
18 tool_proxy_response,
@@ -23,8 +25,7 @@ from composio.core.models.inline_custom_tools_payload import (
25 )
26 from composio.core.provider import TTool, TToolCollection
27 from composio.core.provider.agentic import AgenticProvider, AgenticProviderExecuteFn
26 -from composio.core.provider.base import ExecuteToolFn
27 -from composio.core.provider.base import BaseProvider
28 +from composio.core.provider.base import BaseProvider, ExecuteToolFn
29 from composio.core.provider.none_agentic import NonAgenticProvider
30 from composio.core.types import ToolkitVersionParam
31 from composio.exceptions import InvalidParams, ToolVersionRequiredError
@@ -46,6 +47,35 @@ from ._modifiers import (
47 TOOL_ROUTER_SESSION_TOOLS_PAGE_LIMIT = 500
48
49
50 +def _normalize_tool(tool: PydanticBaseModel | Mapping[str, object]) -> Tool:
51 + """Normalize generated-client responses to the SDK's tool model shape."""
52 + normalized: PydanticBaseModel
53 + if isinstance(tool, Mapping):
54 + normalized = Tool.model_construct(_fields_set=set(tool), **dict(tool))
55 + else:
56 + normalized = tool
57 +
58 + toolkit = getattr(normalized, "toolkit", None)
59 + if isinstance(toolkit, Mapping):
60 + normalized_toolkit = ToolkitMinimal.model_construct(
61 + _fields_set=set(toolkit), **dict(toolkit)
62 + )
63 + normalized = normalized.model_copy(update={"toolkit": normalized_toolkit})
64 +
65 + return t.cast(Tool, normalized)
66 +
67 +
68 +def _toolkit_slug(tool: Tool, fallback: str) -> str:
69 + """Resolve untrusted toolkit metadata without assuming a generated shape."""
70 + toolkit = getattr(tool, "toolkit", None)
71 + slug = (
72 + toolkit.get("slug")
73 + if isinstance(toolkit, Mapping)
74 + else getattr(toolkit, "slug", None)
75 + )
76 + return slug if isinstance(slug, str) and slug else fallback
77 +
78 +
79 def _needs_serialization(obj: t.Any) -> bool:
80 """Check if an object contains any Pydantic model instances."""
81 if isinstance(obj, PydanticBaseModel):
@@ -170,8 +200,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
200 """
201 Returns schema for the given tool slug.
202 """
173 - return t.cast(
174 - Tool,
203 + return _normalize_tool(
204 self._client.tools.retrieve(
205 tool_slug=slug,
206 toolkit_versions=none_to_omit(self._toolkit_versions),
@@ -215,7 +244,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
244 toolkit_versions=none_to_omit(self._toolkit_versions),
245 ).items
246 )
218 - return tools_list
247 + return [_normalize_tool(tool) for tool in tools_list]
248
249 def get_raw_tool_router_meta_tools(
250 self,
@@ -269,13 +298,18 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
298 cursor=none_to_omit(cursor),
299 limit=TOOL_ROUTER_SESSION_TOOLS_PAGE_LIMIT,
300 )
272 - # Cast to Tool type - session.tools returns compatible Item type from different response schema
273 - tools_list.extend(t.cast(Tool, item) for item in tools_response.items)
301 + tools_list.extend(_normalize_tool(item) for item in tools_response.items)
302
303 cursor = getattr(tools_response, "next_cursor", None)
304 if not cursor:
305 break
306
307 + self._tool_schemas.update(
308 + {tool.slug: tool.model_copy(deep=True) for tool in tools_list}
309 + )
310 +
311 + tools_list = [tool.model_copy(deep=True) for tool in tools_list]
312 +
313 # Apply schema modifiers if provided
314 if modifiers is not None:
315 from composio.core.models._modifiers import apply_modifier_by_type
@@ -285,7 +319,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
319 Tool,
320 apply_modifier_by_type(
321 modifiers=modifiers,
288 - toolkit=tool.toolkit.slug,
322 + toolkit=_toolkit_slug(tool, "unknown"),
323 tool=tool.slug,
324 type="schema",
325 schema=tool,
@@ -294,10 +328,6 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
328 for tool in tools_list
329 ]
330
297 - self._tool_schemas.update(
298 - {tool.slug: tool.model_copy(deep=True) for tool in tools_list}
299 - )
300 -
331 return tools_list
332
333 def _get(
@@ -311,18 +341,23 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
341 limit: t.Optional[int] = None,
342 ) -> TToolCollection:
343 """Get a list of tools based on the provided filters."""
314 - tools_list = self.get_raw_composio_tools(
344 + raw_tools = self.get_raw_composio_tools(
345 tools=tools,
346 search=search,
347 toolkits=toolkits,
348 scopes=scopes,
349 limit=limit,
350 )
351 + self._tool_schemas.update(
352 + {tool.slug: tool.model_copy(deep=True) for tool in raw_tools}
353 + )
354 +
355 + tools_list = [tool.model_copy(deep=True) for tool in raw_tools]
356 if modifiers is not None:
357 tools_list = [
358 apply_modifier_by_type(
359 modifiers=modifiers,
325 - toolkit=tool.toolkit.slug,
360 + toolkit=_toolkit_slug(tool, "unknown"),
361 tool=tool.slug,
362 type="schema",
363 schema=tool,
@@ -330,10 +365,6 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
365 for tool in tools_list
366 ]
367
333 - self._tool_schemas.update(
334 - {tool.slug: tool.model_copy(deep=True) for tool in tools_list}
335 - )
336 -
368 # Always enhance schema descriptions (type hints and required notes)
369 # regardless of dangerously_allow_auto_upload_download_files
370 for tool in tools_list:
@@ -469,17 +500,11 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
500 tool = self._tool_schemas.get(slug)
501
502 if tool is None:
472 - tool = t.cast(
473 - Tool,
474 - self._client.tools.retrieve(
475 - tool_slug=slug,
476 - toolkit_versions=none_to_omit(self._toolkit_versions),
477 - ),
478 - )
503 + tool = self.get_raw_composio_tool_by_slug(slug)
504 self._tool_schemas[slug] = tool
505
506 if self._auto_upload_download_files:
482 - meta_tk = tool.toolkit.slug if tool.toolkit else "composio"
507 + meta_tk = _toolkit_slug(tool, "composio")
508 bfu = merge_before_file_upload(
509 modifiers,
510 tool=slug,
@@ -491,7 +516,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
516 before_file_upload=bfu,
517 )
518
494 - toolkit_slug = tool.toolkit.slug if tool.toolkit else "composio"
519 + toolkit_slug = _toolkit_slug(tool, "composio")
520
521 # Apply before_execute modifiers
522 processed_arguments = arguments
@@ -550,6 +575,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
575 self,
576 slug: str,
577 arguments: t.Dict,
578 + tool: Tool,
579 connected_account_id: t.Optional[str] = None,
580 custom_auth_params: t.Optional[tool_execute_params.CustomAuthParams] = None,
581 custom_connection_data: t.Optional[
@@ -565,13 +591,10 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
591 # before sending to the API (fixes PLEN-1514: RootModel not JSON serializable)
592 arguments = _serialize_arguments(arguments)
593
568 - # Get the tool to determine its toolkit
569 - tool = self.get_raw_composio_tool_by_slug(slug)
570 -
594 # If version is not explicitly provided, resolve it from instance-level toolkit versions
595 # This matches the TypeScript behavior - always resolve version when None
596 if version is None:
574 - toolkit_slug = tool.toolkit.slug if tool.toolkit else "unknown"
597 + toolkit_slug = _toolkit_slug(tool, "unknown")
598 # Use instance-level toolkit versions configuration
599 version = get_toolkit_version(toolkit_slug, self._toolkit_versions)
600
@@ -638,17 +661,11 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
661 tool = self._tool_schemas.get(slug)
662
663 if tool is None:
641 - tool = t.cast(
642 - Tool,
643 - self._client.tools.retrieve(
644 - tool_slug=slug,
645 - toolkit_versions=none_to_omit(self._toolkit_versions),
646 - ),
647 - )
664 + tool = self.get_raw_composio_tool_by_slug(slug)
665 self._tool_schemas[slug] = tool
666
667 if self._auto_upload_download_files:
651 - tk = tool.toolkit.slug if tool.toolkit else "unknown"
668 + tk = _toolkit_slug(tool, "unknown")
669 bfu = merge_before_file_upload(
670 modifiers,
671 tool=slug,
@@ -683,7 +700,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
700 )
701 processed_params = apply_modifier_by_type(
702 modifiers=modifiers,
686 - toolkit=tool.toolkit.slug,
703 + toolkit=_toolkit_slug(tool, "unknown"),
704 tool=slug,
705 type=type_before_exec,
706 request=request_params,
@@ -707,6 +724,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
724 response = self._execute_tool(
725 slug=slug,
726 arguments=arguments,
727 + tool=tool,
728 connected_account_id=connected_account_id,
729 custom_auth_params=custom_auth_params,
730 custom_connection_data=custom_connection_data,
@@ -723,7 +741,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
741 if modifiers is not None:
742 response = apply_modifier_by_type(
743 modifiers=modifiers,
726 - toolkit=tool.toolkit.slug,
744 + toolkit=_toolkit_slug(tool, "unknown"),
745 tool=slug,
746 type="after_execute",
747 response=response,
python/tests/test_no_retry_writes.py
+1
@@ -145,6 +145,7 @@ class TestWritePathDoesNotRetry:
145 tools._execute_tool(
146 slug="GMAIL_SEND_EMAIL",
147 arguments={},
148 + tool=mock_tool,
149 version="1.0.0",
150 )
151
python/tests/test_tool_execution.py
+162 -3
@@ -4,14 +4,13 @@ import typing as t
4 from unittest.mock import Mock, patch
5
6 import pytest
7 -from pydantic import BaseModel, RootModel
7 from composio_client import omit
8 +from pydantic import BaseModel, RootModel
9
10 from composio.client.types import Tool, tool_list_response
11 from composio.core.models.base import allow_tracking
12 -from composio.core.models.tools import Tools, _serialize_arguments, _needs_serialization
12 +from composio.core.models.tools import Tools, _needs_serialization, _serialize_arguments
13 from composio.exceptions import ToolVersionRequiredError
14 -
14 from tests.conftest import mock_http_client
15
16
@@ -81,6 +80,159 @@ class TestToolExecution:
80 cursor="next_page",
81 )
82
83 + def test_tool_router_modifiers_handle_tool_without_toolkit(self):
84 + """Tool Router modifier fallbacks match TypeScript in each phase."""
85 + from composio.core.models._modifiers import (
86 + after_execute,
87 + before_execute,
88 + schema_modifier,
89 + )
90 +
91 + mock_client = mock_http_client()
92 + tools = Tools(client=mock_client, provider=Mock())
93 + raw_tool = self.create_mock_tool("CUSTOM_TOOL", "custom").model_dump()
94 + raw_tool.pop("toolkit")
95 + mock_client.tool_router.session.tools.return_value = Mock(
96 + items=[raw_tool], next_cursor=None
97 + )
98 + seen_toolkits = []
99 +
100 + @schema_modifier
101 + def observe_toolkit(tool, toolkit, schema):
102 + seen_toolkits.append(("schema", toolkit))
103 + return schema
104 +
105 + @before_execute
106 + def observe_before_execute(tool, toolkit, params):
107 + seen_toolkits.append(("before_execute", toolkit))
108 + return params
109 +
110 + @after_execute
111 + def observe_after_execute(tool, toolkit, response):
112 + seen_toolkits.append(("after_execute", toolkit))
113 + return response
114 +
115 + result = tools.get_raw_tool_router_meta_tools(
116 + "session_123", modifiers=[observe_toolkit]
117 + )
118 + mock_client.tool_router.session.execute.return_value = Mock(data={}, error=None)
119 + execute = tools._wrap_execute_tool_for_tool_router(
120 + "session_123", modifiers=[observe_before_execute, observe_after_execute]
121 + )
122 + execute("CUSTOM_TOOL", {})
123 +
124 + assert [tool.slug for tool in result] == ["CUSTOM_TOOL"]
125 + assert seen_toolkits == [
126 + ("schema", "unknown"),
127 + ("before_execute", "composio"),
128 + ("after_execute", "composio"),
129 + ]
130 +
131 + def test_execute_without_toolkit_runs_modifiers_and_fetches_once(self):
132 + """Toolkit-less tools execute with the same fallback used by TypeScript."""
133 + from composio.core.models._modifiers import after_execute, before_execute
134 +
135 + mock_client = mock_http_client()
136 + tools = Tools(
137 + client=mock_client,
138 + provider=Mock(),
139 + toolkit_versions={"unknown": "20250101_00"},
140 + )
141 + raw_tool = self.create_mock_tool("CUSTOM_TOOL", "custom").model_dump()
142 + raw_tool.pop("toolkit")
143 + mock_client.tools.retrieve.return_value = raw_tool
144 +
145 + execute_response = Mock()
146 + execute_response.model_dump.return_value = {
147 + "data": {"value": "original"},
148 + "error": None,
149 + "successful": True,
150 + }
151 + mock_client.tools.execute.return_value = execute_response
152 + seen_toolkits = []
153 +
154 + @before_execute
155 + def modify_request(tool, toolkit, params):
156 + seen_toolkits.append(toolkit)
157 + params["arguments"]["value"] = "modified"
158 + return params
159 +
160 + @after_execute
161 + def modify_response(tool, toolkit, response):
162 + seen_toolkits.append(toolkit)
163 + response["data"]["modified"] = True
164 + return response
165 +
166 + result = tools.execute(
167 + slug="CUSTOM_TOOL",
168 + arguments={"value": "original"},
169 + modifiers=[modify_request, modify_response],
170 + )
171 +
172 + assert result["data"] == {"value": "original", "modified": True}
173 + assert seen_toolkits == ["unknown", "unknown"]
174 + mock_client.tools.retrieve.assert_called_once()
175 + mock_client.tools.execute.assert_called_once_with(
176 + tool_slug="CUSTOM_TOOL",
177 + arguments={"value": "modified"},
178 + connected_account_id=omit,
179 + custom_auth_params=omit,
180 + custom_connection_data=omit,
181 + user_id=omit,
182 + text=omit,
183 + version="20250101_00",
184 + )
185 +
186 + def test_provider_execution_uses_raw_metadata_after_schema_modifier(self):
187 + """Schema presentation changes must not alter execution versioning."""
188 + from composio.core.models._modifiers import schema_modifier
189 +
190 + mock_client = mock_http_client()
191 + mock_provider = Mock()
192 + tools = Tools(
193 + client=mock_client,
194 + provider=mock_provider,
195 + toolkit_versions={
196 + "github": "20250101_00",
197 + "renamed": "20250102_00",
198 + },
199 + )
200 + raw_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github").model_dump()
201 + mock_client.tools.list.return_value = Mock(items=[raw_tool])
202 + execute_response = Mock()
203 + execute_response.model_dump.return_value = {
204 + "data": {"result": "success"},
205 + "error": None,
206 + "successful": True,
207 + }
208 + mock_client.tools.execute.return_value = execute_response
209 + wrapped = {}
210 +
211 + def capture_tools(tools, execute_tool):
212 + wrapped["tools"] = tools
213 + wrapped["execute_tool"] = execute_tool
214 + return tools
215 +
216 + mock_provider.wrap_tools.side_effect = capture_tools
217 +
218 + @schema_modifier
219 + def rename_toolkit(tool, toolkit, schema):
220 + schema.toolkit = tool_list_response.ItemToolkit(
221 + name="Renamed", slug="renamed", logo=""
222 + )
223 + return schema
224 +
225 + tools.get(
226 + user_id="user_123",
227 + tools=["GITHUB_GET_REPOS"],
228 + modifiers=[rename_toolkit],
229 + )
230 + wrapped["execute_tool"]("GITHUB_GET_REPOS", {})
231 +
232 + assert wrapped["tools"][0].toolkit.slug == "renamed"
233 + mock_client.tools.retrieve.assert_not_called()
234 + assert mock_client.tools.execute.call_args.kwargs["version"] == "20250101_00"
235 +
236 def test_tool_execution_uses_toolkit_version(self):
237 """Test that tool execution resolves toolkit version correctly."""
238 # Mock client and provider
@@ -118,6 +270,7 @@ class TestToolExecution:
270 tools._execute_tool(
271 slug="GITHUB_GET_REPOS",
272 arguments={"owner": "test", "repo": "test"},
273 + tool=github_tool,
274 )
275
276 # Verify that the client was called with the resolved version
@@ -166,6 +319,7 @@ class TestToolExecution:
319 tools._execute_tool(
320 slug="GITHUB_GET_REPOS",
321 arguments={"owner": "test", "repo": "test"},
322 + tool=github_tool,
323 version="20251201_03", # Explicit version should take precedence
324 )
325
@@ -215,6 +369,7 @@ class TestToolExecution:
369 tools._execute_tool(
370 slug="GITHUB_GET_REPOS",
371 arguments={"owner": "test", "repo": "test"},
372 + tool=github_tool,
373 dangerously_skip_version_check=True,
374 )
375
@@ -262,6 +417,7 @@ class TestToolExecution:
417 tools._execute_tool(
418 slug="GITHUB_GET_REPOS",
419 arguments={"owner": "test", "repo": "test"},
420 + tool=github_tool,
421 )
422
423 # Verify that the client was called with the global version
@@ -335,12 +491,14 @@ class TestToolExecution:
491 tools._execute_tool(
492 slug=tool_slug,
493 arguments={"test": "data"},
494 + tool=mock_tool,
495 dangerously_skip_version_check=True,
496 )
497 else:
498 tools._execute_tool(
499 slug=tool_slug,
500 arguments={"test": "data"},
501 + tool=mock_tool,
502 )
503
504 # Verify the version matches expected
@@ -1272,6 +1430,7 @@ class TestSerializeArguments:
1430 Block(type="paragraph", content="Hello from composio"),
1431 ],
1432 },
1433 + tool=notion_tool,
1434 dangerously_skip_version_check=True,
1435 )
1436
ts/packages/core/test/tools/tools.test.ts
+52 -2
@@ -417,6 +417,26 @@ describe('Tools', () => {
417 undefined
418 );
419 });
420 +
421 + it('should pass unknown toolkit metadata to schema modifiers', async () => {
422 + const toolWithoutToolkit = {
423 + ...toolMocks.rawTool,
424 + toolkit: undefined,
425 + };
426 + const modifySchema = vi.fn(({ schema }) => schema);
427 + mockClient.toolRouter.session.tools.mockResolvedValueOnce({
428 + items: [toolWithoutToolkit],
429 + next_cursor: null,
430 + });
431 +
432 + await context.tools.getRawToolRouterSessionTools('session_123', { modifySchema });
433 +
434 + expect(modifySchema).toHaveBeenCalledWith({
435 + toolSlug: toolMocks.rawTool.slug,
436 + toolkitSlug: 'unknown',
437 + schema: expect.objectContaining({ slug: toolMocks.rawTool.slug }),
438 + });
439 + });
440 });
441
442 describe('getRawComposioToolBySlug', () => {
@@ -1488,11 +1508,12 @@ describe('Tools', () => {
1508 });
1509
1510 const beforeExecute = vi.fn().mockImplementation(({ params }) => params);
1511 + const afterExecute = vi.fn().mockImplementation(({ result }) => result);
1512
1513 await context.tools.executeSessionTool(
1514 toolSlug,
1515 body,
1495 - { beforeExecute },
1516 + { beforeExecute, afterExecute },
1517 toolWithoutToolkit as unknown as Tool
1518 );
1519
@@ -1502,6 +1523,17 @@ describe('Tools', () => {
1523 sessionId,
1524 params: { query: 'test' },
1525 });
1526 + expect(afterExecute).toHaveBeenCalledWith({
1527 + toolSlug,
1528 + toolkitSlug: 'composio',
1529 + sessionId,
1530 + result: {
1531 + data: { results: true },
1532 + error: null,
1533 + successful: true,
1534 + logId: '123',
1535 + },
1536 + });
1537 });
1538 });
1539
@@ -2035,7 +2067,25 @@ describe('Tools', () => {
2067 dangerouslySkipVersionCheck: true, // Required when toolkit is undefined and version is 'latest'
2068 };
2069
2038 - await tools.execute('SOME_CUSTOM_TOOL', executeParams);
2070 + const beforeExecute = vi.fn().mockImplementation(({ params }) => params);
2071 + const afterExecute = vi.fn().mockImplementation(({ result }) => result);
2072 +
2073 + await tools.execute('SOME_CUSTOM_TOOL', executeParams, {
2074 + beforeExecute,
2075 + afterExecute,
2076 + });
2077 +
2078 + expect(beforeExecute).toHaveBeenCalledWith({
2079 + toolSlug: 'SOME_CUSTOM_TOOL',
2080 + toolkitSlug: 'unknown',
2081 + params: executeParams,
2082 + });
2083 + expect(afterExecute).toHaveBeenCalledWith(
2084 + expect.objectContaining({
2085 + toolSlug: 'SOME_CUSTOM_TOOL',
2086 + toolkitSlug: 'unknown',
2087 + })
2088 + );
2089
2090 expect(mockClient.tools.execute).toHaveBeenCalledWith(
2091 'COMPOSIO_TOOL',