@devries-cameron20 / composio Mirror · read-only / commits / 6196f2e33
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 02:00 UTC

feat(python)!: replace factory functions with decorator API for custom tools

BREAKING: Remove experimental_create_tool() and experimental_create_toolkit() factory functions. Replace with decorator-based API on composio.experimental: @composio.experimental.tool() def grep(input: GrepInput, ctx): """Search for a pattern.""" return {"matches": []} @composio.experimental.tool(extends_toolkit="gmail") def create_draft(input: DraftInput, ctx): """Create a Gmail draft.""" return ctx.proxy_execute(toolkit="gmail", ...) dev_tools = composio.experimental.Toolkit( slug="DEV_TOOLS", name="Dev Tools", description="Dev utilities", ) @dev_tools.tool() def search_code(input: SearchInput, ctx): """Search code.""" return {"results": []} Decorator infers slug (fn name uppercased), name (humanized), description (docstring), and input_params (first BaseModel-typed parameter). All can be overridden with explicit kwargs. Supports @bare, @tool(), and @tool(extends_toolkit=...) forms. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Dhawal Upadhyay committed Mar 20, 2026 at 16:42 UTC 6196f2e338ffdb7e3b1b41fd82ac068a5a691b5d
6 files changed +590 -876
python/composio/__init__.py
-6
@@ -1,8 +1,4 @@
1 from .__version__ import __version__
2 -from .core.models.custom_tool import (
3 - experimental_create_tool,
4 - experimental_create_toolkit,
5 -)
2 from .core.models.custom_tool_types import (
3 CustomTool,
4 CustomToolkit,
@@ -47,8 +43,6 @@ __all__ = (
43 "WebhookEventType",
44 "after_execute",
45 "before_execute",
50 - "experimental_create_tool",
51 - "experimental_create_toolkit",
46 "is_connection_expired_event",
47 "schema_modifier",
48 "__version__",
python/composio/core/models/__init__.py
+3 -3
@@ -1,6 +1,6 @@
1 from .auth_configs import AuthConfigs
2 from .connected_accounts import ConnectedAccounts
3 -from .custom_tool import experimental_create_tool, experimental_create_toolkit
3 +from .custom_tool import ExperimentalAPI, ExperimentalToolkit
4 from .custom_tool_types import (
5 CustomTool,
6 CustomToolkit,
@@ -35,6 +35,8 @@ __all__ = [
35 "ConnectionStatusEnum",
36 "CustomTool",
37 "CustomToolkit",
38 + "ExperimentalAPI",
39 + "ExperimentalToolkit",
40 "MCP",
41 "ProxyExecuteResponse",
42 "RegisteredCustomTool",
@@ -51,7 +53,5 @@ __all__ = [
53 "WebhookConnectionMetadata",
54 "WebhookEvent",
55 "WebhookEventType",
54 - "experimental_create_tool",
55 - "experimental_create_toolkit",
56 "is_connection_expired_event",
57 ]
python/composio/core/models/custom_tool.py
+269 -143
@@ -1,29 +1,47 @@
1 -"""Factory functions for creating custom tools and toolkits.
1 +"""Custom tools and toolkits for tool router sessions.
2 +
3 +Decorator API for defining custom tools that run in-process alongside
4 +remote Composio tools. Accessed via ``composio.experimental``.
5
6 Usage::
7
5 - from composio import experimental_create_tool, experimental_create_toolkit
8 from pydantic import BaseModel, Field
9 + from composio import Composio
10 +
11 + composio = Composio()
12
13 class GrepInput(BaseModel):
14 pattern: str = Field(description="Pattern to search for")
15
11 - grep = experimental_create_tool("GREP",
12 - name="Grep Search",
13 - description="Search for patterns in files",
14 - input_params=GrepInput,
15 - execute=lambda input, ctx: {"matches": []},
16 - )
16 + @composio.experimental.tool()
17 + def grep(input: GrepInput, ctx):
18 + \"\"\"Search for a pattern in local files.\"\"\"
19 + return {"matches": []}
20
18 - dev_tools = experimental_create_toolkit("DEV_TOOLS",
21 + dev_tools = composio.experimental.Toolkit(
22 + slug="DEV_TOOLS",
23 name="Dev Tools",
24 description="Local dev utilities",
21 - tools=[grep],
25 + )
26 +
27 + @dev_tools.tool()
28 + def search_code(input: GrepInput, ctx):
29 + \"\"\"Search developer resources.\"\"\"
30 + return {"results": []}
31 +
32 + session = composio.create(
33 + user_id="default",
34 + experimental={
35 + "custom_tools": [grep],
36 + "custom_toolkits": [dev_tools],
37 + },
38 )
39 """
40
41 from __future__ import annotations
42
43 +import asyncio
44 +import inspect
45 import typing as t
46
47 from pydantic import BaseModel
@@ -120,18 +138,17 @@ def _get_input_json_schema(model: t.Type[BaseModel]) -> t.Dict[str, t.Any]:
138 schema["properties"] = full_schema["properties"]
139 if "required" in full_schema:
140 schema["required"] = full_schema["required"]
123 - # Inline $defs if present (Pydantic puts nested models there)
141 if "$defs" in full_schema:
142 schema["$defs"] = full_schema["$defs"]
143 return schema
144
145
146 # ────────────────────────────────────────────────────────────────
130 -# Factory functions
147 +# Internal tool creation (used by decorator API)
148 # ────────────────────────────────────────────────────────────────
149
150
134 -def experimental_create_tool(
151 +def _create_tool(
152 slug: str,
153 *,
154 name: str,
@@ -141,80 +158,22 @@ def experimental_create_tool(
158 extends_toolkit: t.Optional[str] = None,
159 output_params: t.Optional[t.Type[BaseModel]] = None,
160 ) -> CustomTool:
144 - """Create a custom tool for use in tool router sessions.
145 -
146 - The returned object is a lightweight reference containing the tool's metadata
147 - and execute function. Pass it to
148 - ``composio.create(user_id, experimental={"custom_tools": [...]})``
149 - to bind it to a session.
150 -
151 - Just return the result data from ``execute``, or raise an error.
152 - The SDK wraps it into the standard response format internally.
153 -
154 - :param slug: Unique tool identifier (alphanumeric, underscores, hyphens;
155 - no LOCAL_ or COMPOSIO_ prefix)
156 - :param name: Human-readable display name
157 - :param description: Tool description (used for BM25 search matching)
158 - :param input_params: Pydantic BaseModel class for input parameters
159 - :param execute: Function ``(input, ctx) -> dict`` that executes the tool
160 - :param extends_toolkit: Composio toolkit slug to inherit auth from (e.g. 'gmail')
161 - :param output_params: Optional Pydantic BaseModel class for output documentation
162 - :returns: A CustomTool to pass to session creation
163 -
164 - Example — standalone tool (no auth)::
165 -
166 - class GrepInput(BaseModel):
167 - pattern: str = Field(description="Pattern to search for")
168 - path: str = Field(description="File path")
169 -
170 - grep = experimental_create_tool("GREP",
171 - name="Grep Search",
172 - description="Search for patterns in files",
173 - input_params=GrepInput,
174 - execute=lambda input, ctx: {"matches": []},
175 - )
176 -
177 - Example — tool extending a Composio toolkit (inherits auth)::
178 -
179 - class DraftInput(BaseModel):
180 - to: str = Field(description="Recipient email")
181 - subject: str = Field(description="Subject")
182 - body: str = Field(description="Body")
183 -
184 - create_draft = experimental_create_tool("CREATE_DRAFT",
185 - name="Create Gmail draft",
186 - description="Create a real Gmail draft via the Gmail API",
187 - extends_toolkit="gmail",
188 - input_params=DraftInput,
189 - execute=lambda input, ctx: ctx.proxy_execute(
190 - toolkit="gmail",
191 - endpoint="https://gmail.googleapis.com/gmail/v1/users/me/drafts",
192 - method="POST",
193 - body={"message": {"raw": "..."}},
194 - ),
195 - )
196 - """
197 - context = "experimental_create_tool"
161 + """Internal: create and validate a CustomTool."""
162 + context = "experimental.tool"
163
199 - # Validate slug
164 _validate_slug(slug, context)
165
202 - # Validate required fields
166 if not name:
167 raise ValidationError(f"{context}: name is required")
168 if not description:
169 raise ValidationError(f"{context}: description is required")
170
208 - # Validate input_params is a Pydantic BaseModel subclass (not an instance)
209 - # and produces an object-shaped JSON Schema (rejects RootModel[list[...]] etc.)
171 if not isinstance(input_params, type) or not issubclass(input_params, BaseModel):
172 raise ValidationError(
173 f"{context}: input_params must be a Pydantic BaseModel subclass. "
174 f"Tool input parameters are always an object with named properties."
175 )
176
216 - # Reject RootModel and other non-object schemas — tool router only passes
217 - # named argument objects, so the schema must have named properties.
177 try:
178 from pydantic import RootModel
179
@@ -225,28 +184,22 @@ def experimental_create_tool(
184 f"named properties."
185 )
186 except ImportError:
228 - pass # RootModel not available in older Pydantic
187 + pass
188
230 - # Validate execute is callable and synchronous
189 if not callable(execute):
190 raise ValidationError(f"{context}: execute must be a callable")
191
234 - import asyncio
235 -
192 if asyncio.iscoroutinefunction(execute):
193 raise ValidationError(
194 f"{context}: execute must be a synchronous function, not async. "
195 f"The Composio Python SDK is synchronous — use a regular "
240 - f"'def execute(input, ctx)' instead of 'async def'."
196 + f"'def fn(input, ctx)' instead of 'async def'."
197 )
198
243 - # Early length validation
199 _validate_slug_length(slug, extends_toolkit, context)
200
246 - # Convert Pydantic model → JSON Schema
201 input_schema = _get_input_json_schema(input_params)
202
249 - # Convert output schema if provided
203 output_schema: t.Optional[t.Dict[str, t.Any]] = None
204 if output_params is not None:
205 if not isinstance(output_params, type) or not issubclass(
@@ -269,65 +222,248 @@ def experimental_create_tool(
222 )
223
224
272 -def experimental_create_toolkit(
273 - slug: str,
225 +def _infer_tool_from_function(
226 + fn: t.Callable[..., t.Any],
227 *,
275 - name: str,
276 - description: str,
277 - tools: t.List[CustomTool],
278 -) -> CustomToolkit:
279 - """Create a custom toolkit that groups related tools.
228 + slug: t.Optional[str] = None,
229 + name: t.Optional[str] = None,
230 + description: t.Optional[str] = None,
231 + extends_toolkit: t.Optional[str] = None,
232 + output_params: t.Optional[t.Type[BaseModel]] = None,
233 +) -> CustomTool:
234 + """Create a CustomTool by inferring metadata from a decorated function.
235 +
236 + - slug: from ``fn.__name__.upper()``
237 + - name: from ``fn.__name__`` humanized
238 + - description: from ``fn.__doc__``
239 + - input_params: from the first parameter with a BaseModel type annotation
240 + """
241 + # Infer slug
242 + actual_slug = slug or fn.__name__.upper()
243 + actual_name = name or fn.__name__.replace("_", " ").title()
244 + actual_description = description or (fn.__doc__ or "").strip()
245 +
246 + if not actual_description:
247 + raise ValidationError(
248 + f"experimental.tool: description is required. "
249 + f'Add a docstring to "{fn.__name__}" or pass description=...'
250 + )
251 +
252 + # Infer input_params from type annotation
253 + sig = inspect.signature(fn)
254 + params = list(sig.parameters.values())
255 + input_params: t.Optional[t.Type[BaseModel]] = None
256 + for p in params:
257 + if p.annotation is not inspect.Parameter.empty:
258 + ann = p.annotation
259 + if isinstance(ann, type) and issubclass(ann, BaseModel):
260 + input_params = ann
261 + break
262 +
263 + if input_params is None:
264 + raise ValidationError(
265 + f'experimental.tool: could not infer input parameters for "{fn.__name__}". '
266 + f"Annotate a parameter with a Pydantic BaseModel subclass, e.g. "
267 + f"def {fn.__name__}(input: MyInput, ctx): ..."
268 + )
269 +
270 + # Wrap function to match CustomToolExecuteFn: (input, ctx) -> dict
271 + # Support both (input) and (input, ctx) signatures
272 + num_params = len(params)
273 + if num_params <= 1:
274 +
275 + def execute(input: t.Any, ctx: t.Any) -> t.Dict[str, t.Any]:
276 + return fn(input)
277 + else:
278 + execute = fn
279 +
280 + return _create_tool(
281 + slug=actual_slug,
282 + name=actual_name,
283 + description=actual_description,
284 + input_params=input_params,
285 + execute=execute,
286 + extends_toolkit=extends_toolkit,
287 + output_params=output_params,
288 + )
289
281 - Tools passed here must NOT have ``extends_toolkit`` set — they inherit the
282 - toolkit identity instead.
290
284 - :param slug: Unique toolkit identifier (alphanumeric, underscores, hyphens;
285 - no LOCAL_ or COMPOSIO_ prefix)
286 - :param name: Human-readable display name
287 - :param description: Toolkit description
288 - :param tools: List of CustomTool objects to include in this toolkit
289 - :returns: A CustomToolkit to pass to session creation
291 +# ────────────────────────────────────────────────────────────────
292 +# ExperimentalToolkit — custom toolkit with .tool() decorator
293 +# ────────────────────────────────────────────────────────────────
294 +
295 +
296 +class ExperimentalToolkit:
297 + """Custom toolkit that groups related tools under one namespace.
298 +
299 + Use ``@toolkit.tool()`` to add tools. Pass the toolkit to
300 + ``composio.create(experimental={"custom_toolkits": [toolkit]})``.
301 +
302 + Tools added to a toolkit must NOT use ``extends_toolkit`` — they
303 + inherit the toolkit identity instead.
304
305 Example::
306
293 - dev_tools = experimental_create_toolkit("DEV_TOOLS",
307 + dev_tools = composio.experimental.Toolkit(
308 + slug="DEV_TOOLS",
309 name="Dev Tools",
310 description="Local dev utilities",
296 - tools=[grep_tool, sed_tool],
311 )
312 +
313 + @dev_tools.tool()
314 + def search_code(input: SearchInput, ctx):
315 + \"\"\"Search developer resources.\"\"\"
316 + return {"results": []}
317 """
299 - context = "experimental_create_toolkit"
318
301 - # Validate slug
302 - _validate_slug(slug, context)
319 + def __init__(self, *, slug: str, name: str, description: str) -> None:
320 + context = "experimental.Toolkit"
321 + _validate_slug(slug, context)
322 + if not name:
323 + raise ValidationError(f"{context}: name is required")
324 + if not description:
325 + raise ValidationError(f"{context}: description is required")
326 +
327 + self.slug = slug
328 + self.name = name
329 + self.description = description
330 + self._tools: t.List[CustomTool] = []
331 +
332 + @property
333 + def tools(self) -> t.Tuple[CustomTool, ...]:
334 + return tuple(self._tools)
335 +
336 + @t.overload
337 + def tool(self, fn: t.Callable[..., t.Any], /) -> CustomTool: ...
338 +
339 + @t.overload
340 + def tool(
341 + self,
342 + *,
343 + slug: t.Optional[str] = None,
344 + name: t.Optional[str] = None,
345 + description: t.Optional[str] = None,
346 + output_params: t.Optional[t.Type[BaseModel]] = None,
347 + ) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
348 +
349 + def tool(
350 + self,
351 + fn: t.Optional[t.Callable[..., t.Any]] = None,
352 + *,
353 + slug: t.Optional[str] = None,
354 + name: t.Optional[str] = None,
355 + description: t.Optional[str] = None,
356 + output_params: t.Optional[t.Type[BaseModel]] = None,
357 + ) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
358 + """Decorator to add a tool to this toolkit.
359 +
360 + Infers slug, name, description, and input_params from the function
361 + if not explicitly provided.
362 + """
363 +
364 + def decorator(f: t.Callable[..., t.Any]) -> CustomTool:
365 + custom_tool = _infer_tool_from_function(
366 + f,
367 + slug=slug,
368 + name=name,
369 + description=description,
370 + output_params=output_params,
371 + # No extends_toolkit for toolkit tools
372 + )
373 + if custom_tool.extends_toolkit:
374 + raise ValidationError(
375 + f'experimental.Toolkit.tool: tool "{custom_tool.slug}" has '
376 + f"extends_toolkit set. Tools in a custom toolkit must not "
377 + f"use extends_toolkit — they inherit the toolkit identity."
378 + )
379 + _validate_slug_length(
380 + custom_tool.slug, self.slug, f'experimental.Toolkit("{self.slug}").tool'
381 + )
382 + self._tools.append(custom_tool)
383 + return custom_tool
384
304 - # Validate required fields
305 - if not name:
306 - raise ValidationError(f"{context}: name is required")
307 - if not description:
308 - raise ValidationError(f"{context}: description is required")
385 + if fn is not None:
386 + return decorator(fn)
387 + return decorator
388
310 - # Non-empty tools required
311 - if not tools:
312 - raise ValidationError(f"{context}: at least one tool is required")
389
314 - # Validate each tool
315 - for tool in tools:
316 - if tool.extends_toolkit:
317 - raise ValidationError(
318 - f'{context}: tool "{tool.slug}" has extends_toolkit set. '
319 - f"Tools in a custom toolkit must not use extends_toolkit — "
320 - f"they inherit the toolkit identity instead."
390 +# ────────────────────────────────────────────────────────────────
391 +# ExperimentalAPI — the composio.experimental namespace
392 +# ────────────────────────────────────────────────────────────────
393 +
394 +
395 +class ExperimentalAPI:
396 + """Experimental APIs accessed via ``composio.experimental``.
397 +
398 + Provides decorators for creating custom tools and toolkits
399 + that run in-process alongside remote Composio tools.
400 + """
401 +
402 + Toolkit = ExperimentalToolkit
403 +
404 + @t.overload
405 + def tool(self, fn: t.Callable[..., t.Any], /) -> CustomTool: ...
406 +
407 + @t.overload
408 + def tool(
409 + self,
410 + *,
411 + slug: t.Optional[str] = None,
412 + name: t.Optional[str] = None,
413 + description: t.Optional[str] = None,
414 + extends_toolkit: t.Optional[str] = None,
415 + output_params: t.Optional[t.Type[BaseModel]] = None,
416 + ) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
417 +
418 + def tool(
419 + self,
420 + fn: t.Optional[t.Callable[..., t.Any]] = None,
421 + *,
422 + slug: t.Optional[str] = None,
423 + name: t.Optional[str] = None,
424 + description: t.Optional[str] = None,
425 + extends_toolkit: t.Optional[str] = None,
426 + output_params: t.Optional[t.Type[BaseModel]] = None,
427 + ) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
428 + """Decorator to create a custom tool from a function.
429 +
430 + Infers slug, name, description, and input_params from the function.
431 + Override any with explicit keyword arguments.
432 +
433 + Examples::
434 +
435 + # Bare decorator — no parens
436 + @composio.experimental.tool
437 + def grep(input: GrepInput, ctx):
438 + \"\"\"Search for a pattern.\"\"\"
439 + return {"matches": []}
440 +
441 + # With parens — no args
442 + @composio.experimental.tool()
443 + def grep(input: GrepInput, ctx):
444 + \"\"\"Search for a pattern.\"\"\"
445 + return {"matches": []}
446 +
447 + # With extends_toolkit — inherits auth
448 + @composio.experimental.tool(extends_toolkit="gmail")
449 + def create_draft(input: DraftInput, ctx):
450 + \"\"\"Create a Gmail draft.\"\"\"
451 + return ctx.proxy_execute(toolkit="gmail", ...)
452 + """
453 +
454 + def decorator(f: t.Callable[..., t.Any]) -> CustomTool:
455 + return _infer_tool_from_function(
456 + f,
457 + slug=slug,
458 + name=name,
459 + description=description,
460 + extends_toolkit=extends_toolkit,
461 + output_params=output_params,
462 )
322 - # Early length validation with toolkit slug
323 - _validate_slug_length(tool.slug, slug, f'{context}("{slug}")')
463
325 - return CustomToolkit(
326 - slug=slug,
327 - name=name,
328 - description=description,
329 - tools=tuple(tools),
330 - )
464 + if fn is not None:
465 + return decorator(fn)
466 + return decorator
467
468
469 # ────────────────────────────────────────────────────────────────
@@ -354,7 +490,7 @@ def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.An
490
491
492 def serialize_custom_toolkits(
357 - toolkits: t.List[CustomToolkit],
493 + toolkits: t.Sequence[t.Union[CustomToolkit, ExperimentalToolkit]],
494 ) -> t.List[t.Dict[str, t.Any]]:
495 """Serialize custom toolkits into the format expected by the backend."""
496 result = []
@@ -388,12 +524,9 @@ def serialize_custom_toolkits(
524
525 def build_custom_tools_map(
526 tools: t.List[CustomTool],
391 - toolkits: t.Optional[t.List[CustomToolkit]] = None,
527 + toolkits: t.Optional[t.List[t.Union[CustomToolkit, ExperimentalToolkit]]] = None,
528 ) -> CustomToolsMap:
393 - """Build a CustomToolsMap from custom tools and toolkits.
394 -
395 - Used internally by ToolRouter.create() to construct the per-session routing map.
396 - """
529 + """Build a CustomToolsMap from custom tools and toolkits."""
530 by_final_slug: t.Dict[str, CustomToolsMapEntry] = {}
531 by_original_slug: t.Dict[str, CustomToolsMapEntry] = {}
532
@@ -445,24 +578,20 @@ def build_custom_tools_map(
578 return CustomToolsMap(
579 by_final_slug=by_final_slug,
580 by_original_slug=by_original_slug,
448 - toolkits=list(toolkits) if toolkits else None,
581 + toolkits=list(toolkits) if toolkits else None, # type: ignore[arg-type]
582 )
583
584
585 def build_custom_tools_map_from_response(
586 tools: t.List[CustomTool],
454 - toolkits: t.Optional[t.List[CustomToolkit]],
587 + toolkits: t.Optional[t.List[t.Union[CustomToolkit, ExperimentalToolkit]]],
588 experimental: t.Optional[SessionCreateResponseExperimental],
589 ) -> CustomToolsMap:
457 - """Build a CustomToolsMap using the slug/original_slug mapping from the backend response.
458 -
459 - Uses the backend's authoritative prefixed slugs instead of computing them client-side.
460 - """
590 + """Build a CustomToolsMap using the slug/original_slug mapping from the backend response."""
591 by_final_slug: t.Dict[str, CustomToolsMapEntry] = {}
592 by_original_slug: t.Dict[str, CustomToolsMapEntry] = {}
593
464 - # Build lookup from original slug → handle + toolkit
465 - # Detect duplicate original slugs across standalone tools and toolkit tools
594 + # Build lookup from original slug -> handle + toolkit
595 handles_by_original: t.Dict[str, t.Tuple[CustomTool, t.Optional[str]]] = {}
596 for handle in tools:
597 key = handle.slug.upper()
@@ -488,22 +617,19 @@ def build_custom_tools_map_from_response(
617 ) -> None:
618 match = handles_by_original.get(original_slug.upper())
619 if not match:
491 - return # Response tool not found in our handles
620 + return
621 handle, default_toolkit = match
622 resolved_toolkit = toolkit if toolkit is not None else default_toolkit
623 entry = CustomToolsMapEntry(
624 handle=handle, final_slug=final_slug, toolkit=resolved_toolkit
625 )
497 - # Store with uppercased keys to match find_custom_tool's .upper() lookup
626 by_final_slug[final_slug.upper()] = entry
627 by_original_slug[original_slug.upper()] = entry
628
501 - # Map standalone custom tools from response
629 if experimental and experimental.custom_tools:
630 for ct in experimental.custom_tools:
631 add_entry(ct.slug, ct.original_slug, ct.extends_toolkit)
632
506 - # Map toolkit custom tools from response
633 if experimental and experimental.custom_toolkits:
634 for ctk in experimental.custom_toolkits:
635 for ctk_tool in ctk.tools:
@@ -512,5 +638,5 @@ def build_custom_tools_map_from_response(
638 return CustomToolsMap(
639 by_final_slug=by_final_slug,
640 by_original_slug=by_original_slug,
515 - toolkits=list(toolkits) if toolkits else None,
641 + toolkits=list(toolkits) if toolkits else None, # type: ignore[arg-type]
642 )
python/composio/core/models/tool_router.py
+2 -1
@@ -18,6 +18,7 @@ from composio_client.types.tool_router import session_create_params
18 from composio.client import HttpClient
19 from composio.core.models.base import Resource
20 from composio.core.models.custom_tool import (
21 + ExperimentalToolkit,
22 build_custom_tools_map_from_response,
23 serialize_custom_tools,
24 serialize_custom_toolkits,
@@ -194,7 +195,7 @@ class ToolRouterExperimentalConfig(te.TypedDict, total=False):
195
196 assistive_prompt: ToolRouterAssistivePromptConfig
197 custom_tools: t.List["CustomTool"]
197 - custom_toolkits: t.List["CustomToolkit"]
198 + custom_toolkits: t.List[t.Union["CustomToolkit", "ExperimentalToolkit"]]
199
200
201 @dataclass
python/composio/sdk.py
+5
@@ -144,6 +144,11 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
144 self.connected_accounts = ConnectedAccounts(client=self._client)
145 self.mcp = MCP(client=self._client)
146
147 + # experimental API — decorators for custom tools and toolkits
148 + from composio.core.models.custom_tool import ExperimentalAPI
149 +
150 + self.experimental = ExperimentalAPI()
151 +
152 # initialize tool router methods
153 self.tool_router = ToolRouter(
154 client=self._client,
python/tests/test_custom_tools.py
+311 -723
@@ -1,7 +1,8 @@
1 """Tests for custom tools in tool router sessions.
2
3 Covers:
4 -- Factory function validation (slug rules, required fields, Pydantic model check)
4 +- Decorator API (inference, overrides, validation)
5 +- Toolkit builder with @toolkit.tool() decorator
6 - Slug prefixing and collision detection
7 - Serialization to API format
8 - Custom tool execution (validation, defaults, errors)
@@ -16,8 +17,9 @@ from unittest.mock import MagicMock
17 import pytest
18 from pydantic import BaseModel, Field
19
19 -from composio import experimental_create_tool, experimental_create_toolkit
20 from composio.core.models.custom_tool import (
21 + ExperimentalAPI,
22 + ExperimentalToolkit,
23 build_custom_tools_map,
24 build_custom_tools_map_from_response,
25 serialize_custom_tools,
@@ -36,6 +38,8 @@ from composio.exceptions import ValidationError
38 # Fixtures
39 # ────────────────────────────────────────────────────────────────
40
41 +exp = ExperimentalAPI()
42 +
43
44 class GrepInput(BaseModel):
45 pattern: str = Field(description="Pattern to search for")
@@ -54,50 +58,41 @@ class SetRoleInput(BaseModel):
58
59 @pytest.fixture
60 def grep_tool():
57 - return experimental_create_tool(
58 - "GREP",
59 - name="Grep Search",
60 - description="Search for patterns in files",
61 - input_params=GrepInput,
62 - execute=lambda input, ctx: {"matches": [input.pattern], "path": input.path},
63 - )
61 + @exp.tool()
62 + def grep(input: GrepInput, ctx):
63 + """Search for patterns in files."""
64 + return {"matches": [input.pattern], "path": input.path}
65 +
66 + return grep
67
68
69 @pytest.fixture
70 def email_tool():
68 - return experimental_create_tool(
69 - "GET_EMAILS",
70 - name="Get Emails",
71 - description="Get emails from Gmail",
72 - input_params=EmailInput,
73 - execute=lambda input, ctx: {"emails": []},
74 - extends_toolkit="gmail",
75 - )
71 + @exp.tool(extends_toolkit="gmail")
72 + def get_emails(input: EmailInput, ctx):
73 + """Get emails from Gmail."""
74 + return {"emails": []}
75 +
76 + return get_emails
77
78
79 @pytest.fixture
80 def set_role_tool():
80 - return experimental_create_tool(
81 - "SET_ROLE",
82 - name="Set role",
83 - description="Set a user's role",
84 - input_params=SetRoleInput,
85 - execute=lambda input, ctx: {
86 - "user_id": input.user_id,
87 - "role": input.role,
88 - "updated": True,
89 - },
90 - )
81 + @exp.tool()
82 + def set_role(input: SetRoleInput, ctx):
83 + """Set a user's role."""
84 + return {"user_id": input.user_id, "role": input.role, "updated": True}
85 +
86 + return set_role
87
88
89 @pytest.fixture
90 def role_toolkit(set_role_tool):
95 - return experimental_create_toolkit(
96 - "ROLE_MANAGER",
97 - name="Role Manager",
98 - description="Manage user roles",
99 - tools=[set_role_tool],
91 + tk = ExperimentalToolkit(
92 + slug="ROLE_MANAGER", name="Role Manager", description="Manage user roles"
93 )
94 + tk._tools.append(set_role_tool)
95 + return tk
96
97
98 class MockSessionContext:
@@ -111,248 +106,179 @@ class MockSessionContext:
106
107
108 # ────────────────────────────────────────────────────────────────
114 -# Factory validation tests
109 +# Decorator API tests
110 # ────────────────────────────────────────────────────────────────
111
112
118 -class TestCreateCustomTool:
119 - def test_creates_tool_with_valid_params(self, grep_tool):
120 - assert grep_tool.slug == "GREP"
121 - assert grep_tool.name == "Grep Search"
122 - assert grep_tool.description == "Search for patterns in files"
123 - assert grep_tool.extends_toolkit is None
124 - assert grep_tool.input_schema["type"] == "object"
125 - assert "pattern" in grep_tool.input_schema["properties"]
126 - assert grep_tool.output_schema is None
127 -
128 - def test_creates_extension_tool(self, email_tool):
129 - assert email_tool.slug == "GET_EMAILS"
130 - assert email_tool.extends_toolkit == "gmail"
131 -
132 - def test_slug_empty(self):
133 - with pytest.raises(ValidationError, match="slug is required"):
134 - experimental_create_tool(
135 - "",
136 - name="Bad",
137 - description="Bad",
138 - input_params=GrepInput,
139 - execute=lambda i, c: {},
140 - )
141 -
142 - def test_slug_invalid_chars(self):
143 - with pytest.raises(ValidationError, match="alphanumeric"):
144 - experimental_create_tool(
145 - "BAD SLUG!",
146 - name="Bad",
147 - description="Bad",
148 - input_params=GrepInput,
149 - execute=lambda i, c: {},
150 - )
151 -
152 - def test_slug_local_prefix(self):
153 - with pytest.raises(ValidationError, match="LOCAL_"):
154 - experimental_create_tool(
155 - "LOCAL_BAD",
156 - name="Bad",
157 - description="Bad",
158 - input_params=GrepInput,
159 - execute=lambda i, c: {},
160 - )
161 -
162 - def test_slug_composio_prefix(self):
163 - with pytest.raises(ValidationError, match="COMPOSIO_"):
164 - experimental_create_tool(
165 - "COMPOSIO_BAD",
166 - name="Bad",
167 - description="Bad",
168 - input_params=GrepInput,
169 - execute=lambda i, c: {},
170 - )
171 -
172 - def test_name_required(self):
173 - with pytest.raises(ValidationError, match="name is required"):
174 - experimental_create_tool(
175 - "GOOD",
176 - name="",
177 - description="Desc",
178 - input_params=GrepInput,
179 - execute=lambda i, c: {},
180 - )
181 -
182 - def test_description_required(self):
113 +class TestDecoratorTool:
114 + def test_bare_decorator(self):
115 + @exp.tool
116 + def my_tool(input: GrepInput, ctx):
117 + """My tool description."""
118 + return {}
119 +
120 + assert my_tool.slug == "MY_TOOL"
121 + assert my_tool.name == "My Tool"
122 + assert my_tool.description == "My tool description."
123 + assert my_tool.input_schema["type"] == "object"
124 + assert "pattern" in my_tool.input_schema["properties"]
125 +
126 + def test_decorator_with_parens(self):
127 + @exp.tool()
128 + def search(input: GrepInput, ctx):
129 + """Search stuff."""
130 + return {}
131 +
132 + assert search.slug == "SEARCH"
133 +
134 + def test_decorator_with_extends_toolkit(self):
135 + @exp.tool(extends_toolkit="gmail")
136 + def fetch_mail(input: EmailInput, ctx):
137 + """Fetch mail."""
138 + return {}
139 +
140 + assert fetch_mail.extends_toolkit == "gmail"
141 +
142 + def test_decorator_explicit_overrides(self):
143 + @exp.tool(slug="CUSTOM", name="Custom Name", description="Custom desc")
144 + def whatever(input: GrepInput, ctx):
145 + """Original docstring."""
146 + return {}
147 +
148 + assert whatever.slug == "CUSTOM"
149 + assert whatever.name == "Custom Name"
150 + assert whatever.description == "Custom desc"
151 +
152 + def test_infers_from_function_name(self):
153 + @exp.tool()
154 + def search_user_by_email(input: GrepInput, ctx):
155 + """Find a user."""
156 + return {}
157 +
158 + assert search_user_by_email.slug == "SEARCH_USER_BY_EMAIL"
159 + assert search_user_by_email.name == "Search User By Email"
160 +
161 + def test_infers_description_from_docstring(self):
162 + @exp.tool()
163 + def my_func(input: GrepInput, ctx):
164 + """Trimmed docstring."""
165 + return {}
166 +
167 + assert my_func.description == "Trimmed docstring."
168 +
169 + def test_missing_docstring_raises(self):
170 with pytest.raises(ValidationError, match="description is required"):
184 - experimental_create_tool(
185 - "GOOD",
186 - name="Name",
187 - description="",
188 - input_params=GrepInput,
189 - execute=lambda i, c: {},
190 - )
191 -
192 - def test_input_params_must_be_basemodel_subclass(self):
193 - with pytest.raises(ValidationError, match="BaseModel subclass"):
194 - experimental_create_tool(
195 - "GOOD",
196 - name="Name",
197 - description="Desc",
198 - input_params=dict, # type: ignore
199 - execute=lambda i, c: {},
200 - )
201 -
202 - def test_input_params_must_not_be_instance(self):
171 +
172 + @exp.tool()
173 + def no_doc(input: GrepInput, ctx):
174 + return {}
175 +
176 + def test_missing_basemodel_annotation_raises(self):
177 with pytest.raises(ValidationError, match="BaseModel subclass"):
204 - experimental_create_tool(
205 - "GOOD",
206 - name="Name",
207 - description="Desc",
208 - input_params=GrepInput(pattern="x"), # type: ignore
209 - execute=lambda i, c: {},
210 - )
211 -
212 - def test_execute_must_be_callable(self):
213 - with pytest.raises(ValidationError, match="callable"):
214 - experimental_create_tool(
215 - "GOOD",
216 - name="Name",
217 - description="Desc",
218 - input_params=GrepInput,
219 - execute="not a function", # type: ignore
220 - )
221 -
222 - def test_slug_length_validation_standalone(self):
223 - # LOCAL_ + 55 chars = 61 > 60
224 - with pytest.raises(ValidationError, match="too long"):
225 - experimental_create_tool(
226 - "A" * 55,
227 - name="Name",
228 - description="Desc",
229 - input_params=GrepInput,
230 - execute=lambda i, c: {},
231 - )
232 -
233 - def test_slug_length_validation_extension(self):
234 - # LOCAL_ + GMAIL_ + slug must be <= 60
235 - with pytest.raises(ValidationError, match="too long"):
236 - experimental_create_tool(
237 - "A" * 50,
238 - name="Name",
239 - description="Desc",
240 - input_params=GrepInput,
241 - execute=lambda i, c: {},
242 - extends_toolkit="gmail",
243 - )
244 -
245 - def test_output_params(self):
246 - class OutputSchema(BaseModel):
247 - matches: int
248 -
249 - tool = experimental_create_tool(
250 - "TOOL",
251 - name="Tool",
252 - description="Desc",
253 - input_params=GrepInput,
254 - execute=lambda i, c: {},
255 - output_params=OutputSchema,
256 - )
257 - assert tool.output_schema is not None
258 - assert "properties" in tool.output_schema
178
260 - def test_rejects_root_model(self):
179 + @exp.tool()
180 + def bad(x: str, ctx):
181 + """Bad tool."""
182 + return {}
183 +
184 + def test_async_function_rejected(self):
185 + with pytest.raises(ValidationError, match="synchronous"):
186 +
187 + @exp.tool()
188 + async def async_tool(input: GrepInput, ctx):
189 + """Async tool."""
190 + return {}
191 +
192 + def test_root_model_rejected(self):
193 from pydantic import RootModel
194
195 class ListInput(RootModel[list[int]]):
196 pass
197
198 with pytest.raises(ValidationError, match="RootModel"):
267 - experimental_create_tool(
268 - "BAD",
269 - name="Bad",
270 - description="Desc",
271 - input_params=ListInput,
272 - execute=lambda i, c: {},
273 - )
274 -
275 - def test_rejects_async_execute(self):
276 - async def async_execute(input, ctx):
277 - return {"result": "ok"}
199
279 - with pytest.raises(ValidationError, match="synchronous"):
280 - experimental_create_tool(
281 - "ASYNC",
282 - name="Async",
283 - description="Desc",
284 - input_params=GrepInput,
285 - execute=async_execute,
286 - )
200 + @exp.tool()
201 + def bad(input: ListInput, ctx):
202 + """Bad tool."""
203 + return {}
204 +
205 + def test_single_param_function(self):
206 + """Function with only input param (no ctx) should work."""
207 +
208 + @exp.tool()
209 + def simple(input: GrepInput):
210 + """Simple tool."""
211 + return {"pattern": input.pattern}
212 +
213 + m = build_custom_tools_map([simple])
214 + entry = find_custom_tool(m, "SIMPLE")
215 + result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore
216 + assert result["successful"] is True
217 + assert result["data"]["pattern"] == "test"
218 +
219 + def test_slug_validation(self):
220 + with pytest.raises(ValidationError, match="LOCAL_"):
221 +
222 + @exp.tool(slug="LOCAL_BAD")
223 + def bad(input: GrepInput, ctx):
224 + """Bad tool."""
225 + return {}
226 +
227 + def test_creates_frozen_custom_tool(self):
228 + @exp.tool()
229 + def frozen(input: GrepInput, ctx):
230 + """Frozen tool."""
231 + return {}
232 +
233 + with pytest.raises(AttributeError):
234 + frozen.slug = "NEW" # type: ignore
235
236 def test_input_schema_includes_defaults(self, grep_tool):
289 - # path has default="." - Pydantic won't include it in required
237 assert "pattern" in grep_tool.input_schema.get("required", [])
238 assert "path" not in grep_tool.input_schema.get("required", [])
239
293 - def test_frozen_dataclass(self, grep_tool):
294 - with pytest.raises(AttributeError):
295 - grep_tool.slug = "NEW" # type: ignore
296 -
297 -
298 -class TestCreateCustomToolkit:
299 - def test_creates_toolkit(self, role_toolkit, set_role_tool):
300 - assert role_toolkit.slug == "ROLE_MANAGER"
301 - assert role_toolkit.name == "Role Manager"
302 - assert len(role_toolkit.tools) == 1
303 - assert role_toolkit.tools[0].slug == "SET_ROLE"
304 -
305 - def test_rejects_empty_tools(self):
306 - with pytest.raises(ValidationError, match="at least one tool"):
307 - experimental_create_toolkit(
308 - "TK",
309 - name="TK",
310 - description="Desc",
311 - tools=[],
312 - )
313 -
314 - def test_rejects_extends_toolkit_in_tools(self, email_tool):
315 - with pytest.raises(ValidationError, match="extends_toolkit"):
316 - experimental_create_toolkit(
317 - "TK",
318 - name="TK",
319 - description="Desc",
320 - tools=[email_tool],
321 - )
322 -
323 - def test_slug_length_validation(self):
324 - tool = experimental_create_tool(
325 - "A" * 45,
326 - name="Name",
327 - description="Desc",
328 - input_params=GrepInput,
329 - execute=lambda i, c: {},
330 - )
331 - # LOCAL_ + LONG_TOOLKIT_ + AAAA... would exceed 60
332 - with pytest.raises(ValidationError, match="too long"):
333 - experimental_create_toolkit(
334 - "LONG_TOOLKIT",
335 - name="TK",
336 - description="Desc",
337 - tools=[tool],
338 - )
240
340 - def test_slug_validation(self):
241 +class TestToolkitBuilder:
242 + def test_toolkit_with_decorator(self):
243 + tk = ExperimentalToolkit(slug="MY_TK", name="My TK", description="Desc")
244 +
245 + @tk.tool()
246 + def tool_a(input: GrepInput, ctx):
247 + """Tool A."""
248 + return {}
249 +
250 + @tk.tool()
251 + def tool_b(input: GrepInput, ctx):
252 + """Tool B."""
253 + return {}
254 +
255 + assert tk.slug == "MY_TK"
256 + assert len(tk.tools) == 2
257 + assert tk.tools[0].slug == "TOOL_A"
258 + assert tk.tools[1].slug == "TOOL_B"
259 +
260 + def test_toolkit_bare_decorator(self):
261 + tk = ExperimentalToolkit(slug="TK2", name="TK2", description="Desc")
262 +
263 + @tk.tool
264 + def tool_c(input: GrepInput, ctx):
265 + """Tool C."""
266 + return {}
267 +
268 + assert len(tk.tools) == 1
269 +
270 + def test_toolkit_slug_validation(self):
271 with pytest.raises(ValidationError, match="LOCAL_"):
342 - experimental_create_toolkit(
343 - "LOCAL_BAD",
344 - name="TK",
345 - description="Desc",
346 - tools=[
347 - experimental_create_tool(
348 - "T",
349 - name="T",
350 - description="D",
351 - input_params=GrepInput,
352 - execute=lambda i, c: {},
353 - )
354 - ],
355 - )
272 + ExperimentalToolkit(slug="LOCAL_BAD", name="Bad", description="Desc")
273 +
274 + def test_toolkit_name_required(self):
275 + with pytest.raises(ValidationError, match="name is required"):
276 + ExperimentalToolkit(slug="TK", name="", description="Desc")
277 +
278 + def test_toolkit_via_experimental_api(self):
279 + tk = exp.Toolkit(slug="API_TK", name="API TK", description="Via API")
280 + assert isinstance(tk, ExperimentalToolkit)
281 + assert tk.slug == "API_TK"
282
283
284 # ────────────────────────────────────────────────────────────────
@@ -365,7 +291,6 @@ class TestSerialization:
291 result = serialize_custom_tools([grep_tool])
292 assert len(result) == 1
293 assert result[0]["slug"] == "GREP"
368 - assert result[0]["name"] == "Grep Search"
294 assert result[0]["input_schema"]["type"] == "object"
295 assert "extends_toolkit" not in result[0]
296
@@ -378,7 +303,6 @@ class TestSerialization:
303 assert len(result) == 1
304 assert result[0]["slug"] == "ROLE_MANAGER"
305 assert len(result[0]["tools"]) == 1
381 - assert result[0]["tools"][0]["slug"] == "SET_ROLE"
306
307
308 # ────────────────────────────────────────────────────────────────
@@ -390,73 +314,28 @@ class TestCustomToolsMap:
314 def test_build_map_standalone(self, grep_tool):
315 m = build_custom_tools_map([grep_tool])
316 assert "LOCAL_GREP" in m.by_final_slug
393 - assert "GREP" in m.by_original_slug
317
318 def test_build_map_extension(self, email_tool):
319 m = build_custom_tools_map([email_tool])
320 assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug
398 - assert "GET_EMAILS" in m.by_original_slug
321
400 - def test_build_map_toolkit(self, set_role_tool, role_toolkit):
322 + def test_build_map_toolkit(self, role_toolkit):
323 m = build_custom_tools_map([], [role_toolkit])
324 assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug
403 - assert "SET_ROLE" in m.by_original_slug
404 -
405 - def test_build_map_mixed(self, grep_tool, email_tool, role_toolkit):
406 - m = build_custom_tools_map([grep_tool, email_tool], [role_toolkit])
407 - assert len(m.by_final_slug) == 3
408 - assert len(m.by_original_slug) == 3
325
410 - def test_collision_detection_final_slug(self, grep_tool):
326 + def test_collision_detection(self, grep_tool):
327 with pytest.raises(ValidationError, match="collision"):
328 build_custom_tools_map([grep_tool, grep_tool])
329
414 - def test_collision_detection_original_slug(self):
415 - tool1 = experimental_create_tool(
416 - "FOO",
417 - name="Foo",
418 - description="Desc",
419 - input_params=GrepInput,
420 - execute=lambda i, c: {},
421 - )
422 - # Same slug in a toolkit produces different final slug but same original
423 - # This would collide on original slug
424 - toolkit = experimental_create_toolkit(
425 - "TK",
426 - name="TK",
427 - description="D",
428 - tools=[
429 - experimental_create_tool(
430 - "FOO",
431 - name="Foo2",
432 - description="Desc2",
433 - input_params=GrepInput,
434 - execute=lambda i, c: {},
435 - )
436 - ],
437 - )
438 - with pytest.raises(ValidationError, match="collision"):
439 - build_custom_tools_map([tool1], [toolkit])
440 -
330
331 class TestFindCustomTool:
332 def test_find_by_final_slug(self, grep_tool):
333 m = build_custom_tools_map([grep_tool])
445 - entry = find_custom_tool(m, "LOCAL_GREP")
446 - assert entry is not None
447 - assert entry.final_slug == "LOCAL_GREP"
448 -
449 - def test_find_by_original_slug(self, grep_tool):
450 - m = build_custom_tools_map([grep_tool])
451 - entry = find_custom_tool(m, "GREP")
452 - assert entry is not None
453 - assert entry.final_slug == "LOCAL_GREP"
334 + assert find_custom_tool(m, "LOCAL_GREP") is not None
335
336 def test_find_case_insensitive(self, grep_tool):
337 m = build_custom_tools_map([grep_tool])
457 - entry = find_custom_tool(m, "grep")
458 - assert entry is not None
459 - assert entry.final_slug == "LOCAL_GREP"
338 + assert find_custom_tool(m, "grep") is not None
339
340 def test_find_nonexistent(self, grep_tool):
341 m = build_custom_tools_map([grep_tool])
@@ -468,43 +347,32 @@ class TestFindCustomTool:
347
348 class TestBuildMapFromResponse:
349 def test_builds_from_response(self, grep_tool, email_tool, role_toolkit):
471 - # Mock response experimental
350 mock_exp = MagicMock()
473 -
474 - mock_ct1 = MagicMock()
475 - mock_ct1.slug = "LOCAL_GREP"
476 - mock_ct1.original_slug = "GREP"
477 - mock_ct1.extends_toolkit = None
478 -
479 - mock_ct2 = MagicMock()
480 - mock_ct2.slug = "LOCAL_GMAIL_GET_EMAILS"
481 - mock_ct2.original_slug = "GET_EMAILS"
482 - mock_ct2.extends_toolkit = "gmail"
483 -
351 + mock_ct1 = MagicMock(
352 + slug="LOCAL_GREP", original_slug="GREP", extends_toolkit=None
353 + )
354 + mock_ct2 = MagicMock(
355 + slug="LOCAL_GMAIL_GET_EMAILS",
356 + original_slug="GET_EMAILS",
357 + extends_toolkit="gmail",
358 + )
359 mock_exp.custom_tools = [mock_ct1, mock_ct2]
485 -
486 - mock_ctk = MagicMock()
487 - mock_ctk.slug = "ROLE_MANAGER"
488 - mock_ctk_tool = MagicMock()
489 - mock_ctk_tool.slug = "LOCAL_ROLE_MANAGER_SET_ROLE"
490 - mock_ctk_tool.original_slug = "SET_ROLE"
491 - mock_ctk.tools = [mock_ctk_tool]
360 + mock_ctk = MagicMock(slug="ROLE_MANAGER")
361 + mock_ctk.tools = [
362 + MagicMock(slug="LOCAL_ROLE_MANAGER_SET_ROLE", original_slug="SET_ROLE")
363 + ]
364 mock_exp.custom_toolkits = [mock_ctk]
365
366 m = build_custom_tools_map_from_response(
495 - [grep_tool, email_tool],
496 - [role_toolkit],
497 - mock_exp,
367 + [grep_tool, email_tool], [role_toolkit], mock_exp
368 )
499 -
369 assert "LOCAL_GREP" in m.by_final_slug
370 assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug
371 assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug
503 - assert m.by_final_slug["LOCAL_GMAIL_GET_EMAILS"].toolkit == "gmail"
372
373
374 # ────────────────────────────────────────────────────────────────
507 -# Custom tool execution tests
375 +# Execution tests
376 # ────────────────────────────────────────────────────────────────
377
378
@@ -515,52 +383,24 @@ class TestExecuteCustomTool:
383 result = execute_custom_tool(entry, {"pattern": "hello"}, MockSessionContext()) # type: ignore
384 assert result["successful"] is True
385 assert result["data"]["matches"] == ["hello"]
518 - assert result["data"]["path"] == "." # default value
519 - assert result["error"] is None
520 -
521 - def test_applies_pydantic_defaults(self, grep_tool):
522 - m = build_custom_tools_map([grep_tool])
523 - entry = find_custom_tool(m, "GREP")
524 - result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore
525 - assert result["data"]["path"] == "." # default applied
386
387 def test_validation_failure(self, grep_tool):
388 m = build_custom_tools_map([grep_tool])
389 entry = find_custom_tool(m, "GREP")
530 - result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignore # missing required "pattern"
390 + result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignore
391 assert result["successful"] is False
532 - assert "validation" in result["error"].lower()
533 -
534 - def test_execute_function_error(self):
535 - def bad_execute(input, ctx):
536 - raise RuntimeError("Something went wrong")
537 -
538 - tool = experimental_create_tool(
539 - "BAD",
540 - name="Bad",
541 - description="Desc",
542 - input_params=GrepInput,
543 - execute=bad_execute,
544 - )
545 - m = build_custom_tools_map([tool])
392 +
393 + def test_execute_error(self):
394 + @exp.tool()
395 + def bad(input: GrepInput, ctx):
396 + """Bad."""
397 + raise RuntimeError("boom")
398 +
399 + m = build_custom_tools_map([bad])
400 entry = find_custom_tool(m, "BAD")
401 result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignore
402 assert result["successful"] is False
549 - assert "Something went wrong" in result["error"]
550 -
551 - def test_execute_returns_none(self):
552 - tool = experimental_create_tool(
553 - "NOOP",
554 - name="Noop",
555 - description="Returns None",
556 - input_params=GrepInput,
557 - execute=lambda i, c: None, # type: ignore
558 - )
559 - m = build_custom_tools_map([tool])
560 - entry = find_custom_tool(m, "NOOP")
561 - result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignore
562 - assert result["successful"] is True
563 - assert result["data"] == {}
403 + assert "boom" in result["error"]
404
405
406 # ────────────────────────────────────────────────────────────────
@@ -569,447 +409,195 @@ class TestExecuteCustomTool:
409
410
411 class TestSessionContextImpl:
572 - def test_user_id(self):
573 - ctx = SessionContextImpl(
574 - client=MagicMock(),
575 - user_id="user-1",
576 - session_id="sess-1",
577 - )
578 - assert ctx.user_id == "user-1"
579 -
580 - def test_execute_routes_to_sibling(self, grep_tool):
412 + def test_sibling_routing(self, grep_tool):
413 m = build_custom_tools_map([grep_tool])
414 ctx = SessionContextImpl(
583 - client=MagicMock(),
584 - user_id="user-1",
585 - session_id="sess-1",
586 - custom_tools_map=m,
415 + client=MagicMock(), user_id="u", session_id="s", custom_tools_map=m
416 )
417 result = ctx.execute("GREP", {"pattern": "test"})
418 assert result["successful"] is True
590 - assert result["data"]["matches"] == ["test"]
419
592 - def test_execute_falls_back_to_remote(self, grep_tool):
420 + def test_remote_fallback(self, grep_tool):
421 m = build_custom_tools_map([grep_tool])
422 mock_client = MagicMock()
595 - mock_response = MagicMock()
596 - mock_response.data = {"remote": True}
597 - mock_response.error = None
598 - mock_client.tool_router.session.execute.return_value = mock_response
599 -
423 + mock_client.tool_router.session.execute.return_value = MagicMock(
424 + data={"remote": True}, error=None
425 + )
426 ctx = SessionContextImpl(
601 - client=mock_client,
602 - user_id="user-1",
603 - session_id="sess-1",
604 - custom_tools_map=m,
427 + client=mock_client, user_id="u", session_id="s", custom_tools_map=m
428 )
606 - result = ctx.execute("NONEXISTENT_TOOL", {"arg": "val"})
429 + ctx.execute("NONEXISTENT", {"arg": "val"})
430 mock_client.tool_router.session.execute.assert_called_once()
608 - assert result["data"] == {"remote": True}
431
432 def test_proxy_execute(self):
433 mock_client = MagicMock()
612 - mock_response = MagicMock()
613 - mock_response.status = 200
614 - mock_response.data = {"result": "ok"}
615 - mock_response.headers = {"Content-Type": "application/json"}
616 - mock_response.binary_data = None
617 - mock_client.tool_router.session.proxy_execute.return_value = mock_response
618 -
619 - ctx = SessionContextImpl(
620 - client=mock_client,
621 - user_id="user-1",
622 - session_id="sess-1",
434 + mock_client.tool_router.session.proxy_execute.return_value = MagicMock(
435 + status=200, data={"ok": True}, headers={}, binary_data=None
436 )
437 + ctx = SessionContextImpl(client=mock_client, user_id="u", session_id="s")
438 result = ctx.proxy_execute(
625 - toolkit="gmail",
626 - endpoint="https://gmail.googleapis.com/test",
627 - method="GET",
439 + toolkit="gmail", endpoint="https://example.com", method="GET"
440 )
441 assert result["status"] == 200
630 - assert result["data"] == {"result": "ok"}
631 - mock_client.tool_router.session.proxy_execute.assert_called_once()
442
443
444 # ────────────────────────────────────────────────────────────────
635 -# ToolRouterSession integration tests
445 +# ToolRouterSession integration
446 # ────────────────────────────────────────────────────────────────
447
448
449 @pytest.fixture
450 def mock_session_deps(grep_tool, email_tool, role_toolkit):
641 - """Create mock dependencies for ToolRouterSession with custom tools."""
642 - client = MagicMock()
643 - provider = MagicMock()
644 - experimental = MagicMock()
645 - experimental.files = MagicMock()
646 - experimental.assistive_prompt = None
647 -
648 - # Build tools map
649 - tools_map = build_custom_tools_map([grep_tool, email_tool], [role_toolkit])
650 -
451 return {
652 - "client": client,
653 - "provider": provider,
654 - "experimental": experimental,
655 - "tools_map": tools_map,
452 + "client": MagicMock(),
453 + "provider": MagicMock(),
454 + "experimental": MagicMock(),
455 + "tools_map": build_custom_tools_map([grep_tool, email_tool], [role_toolkit]),
456 }
457
458
459 +def _session(deps, **overrides):
460 + kwargs = dict(
461 + client=deps["client"],
462 + provider=deps["provider"],
463 + auto_upload_download_files=True,
464 + session_id="s",
465 + mcp=MagicMock(),
466 + experimental=deps["experimental"],
467 + custom_tools_map=deps["tools_map"],
468 + user_id="u",
469 + )
470 + kwargs.update(overrides)
471 + return ToolRouterSession(**kwargs)
472 +
473 +
474 class TestToolRouterSessionCustomTools:
660 - def test_execute_routes_to_local(self, mock_session_deps, grep_tool):
661 - session = ToolRouterSession(
662 - client=mock_session_deps["client"],
663 - provider=mock_session_deps["provider"],
664 - auto_upload_download_files=True,
665 - session_id="sess-1",
666 - mcp=MagicMock(),
667 - experimental=mock_session_deps["experimental"],
668 - custom_tools_map=mock_session_deps["tools_map"],
669 - user_id="user-1",
670 - )
671 - result = session.execute("GREP", arguments={"pattern": "test"})
672 - # session.execute returns SessionExecuteResponse shape: data, error, log_id
673 - assert result["data"]["matches"] == ["test"]
475 + def test_execute_local(self, mock_session_deps):
476 + s = _session(mock_session_deps)
477 + result = s.execute("GREP", arguments={"pattern": "x"})
478 assert result["error"] is None
479 assert result["log_id"] == ""
676 - # Should NOT have called the backend
480 mock_session_deps["client"].tool_router.session.execute.assert_not_called()
481
679 - def test_execute_routes_to_local_by_final_slug(self, mock_session_deps):
680 - session = ToolRouterSession(
681 - client=mock_session_deps["client"],
682 - provider=mock_session_deps["provider"],
683 - auto_upload_download_files=True,
684 - session_id="sess-1",
685 - mcp=MagicMock(),
686 - experimental=mock_session_deps["experimental"],
687 - custom_tools_map=mock_session_deps["tools_map"],
688 - user_id="user-1",
689 - )
690 - result = session.execute("LOCAL_GREP", arguments={"pattern": "test"})
691 - assert result["error"] is None
692 -
693 - def test_execute_case_insensitive(self, mock_session_deps):
694 - session = ToolRouterSession(
695 - client=mock_session_deps["client"],
696 - provider=mock_session_deps["provider"],
697 - auto_upload_download_files=True,
698 - session_id="sess-1",
699 - mcp=MagicMock(),
700 - experimental=mock_session_deps["experimental"],
701 - custom_tools_map=mock_session_deps["tools_map"],
702 - user_id="user-1",
703 - )
704 - result = session.execute("grep", arguments={"pattern": "test"})
705 - assert result["error"] is None
706 -
707 - def test_execute_routes_to_remote(self, mock_session_deps):
708 - mock_response = MagicMock()
482 + def test_execute_remote(self, mock_session_deps):
483 mock_session_deps[
484 "client"
711 - ].tool_router.session.execute.return_value = mock_response
712 -
713 - session = ToolRouterSession(
714 - client=mock_session_deps["client"],
715 - provider=mock_session_deps["provider"],
716 - auto_upload_download_files=True,
717 - session_id="sess-1",
718 - mcp=MagicMock(),
719 - experimental=mock_session_deps["experimental"],
720 - custom_tools_map=mock_session_deps["tools_map"],
721 - user_id="user-1",
722 - )
723 - session.execute("GMAIL_SEND_EMAIL", arguments={"to": "alice@example.com"})
485 + ].tool_router.session.execute.return_value = MagicMock()
486 + s = _session(mock_session_deps)
487 + s.execute("GMAIL_SEND_EMAIL", arguments={"to": "a@b.com"})
488 mock_session_deps["client"].tool_router.session.execute.assert_called_once()
489
490 def test_custom_tools_list(self, mock_session_deps):
727 - session = ToolRouterSession(
728 - client=mock_session_deps["client"],
729 - provider=mock_session_deps["provider"],
730 - auto_upload_download_files=True,
731 - session_id="sess-1",
732 - mcp=MagicMock(),
733 - experimental=mock_session_deps["experimental"],
734 - custom_tools_map=mock_session_deps["tools_map"],
735 - user_id="user-1",
736 - )
737 - tools = session.custom_tools()
738 - assert len(tools) == 3
739 - slugs = {t.slug for t in tools}
740 - assert "LOCAL_GREP" in slugs
741 - assert "LOCAL_GMAIL_GET_EMAILS" in slugs
742 - assert "LOCAL_ROLE_MANAGER_SET_ROLE" in slugs
743 -
744 - def test_custom_tools_filter_by_toolkit(self, mock_session_deps):
745 - session = ToolRouterSession(
746 - client=mock_session_deps["client"],
747 - provider=mock_session_deps["provider"],
748 - auto_upload_download_files=True,
749 - session_id="sess-1",
750 - mcp=MagicMock(),
751 - experimental=mock_session_deps["experimental"],
752 - custom_tools_map=mock_session_deps["tools_map"],
753 - user_id="user-1",
754 - )
755 - gmail_tools = session.custom_tools(toolkit="gmail")
756 - assert len(gmail_tools) == 1
757 - assert gmail_tools[0].slug == "LOCAL_GMAIL_GET_EMAILS"
491 + s = _session(mock_session_deps)
492 + assert len(s.custom_tools()) == 3
493 +
494 + def test_custom_tools_filter(self, mock_session_deps):
495 + s = _session(mock_session_deps)
496 + assert len(s.custom_tools(toolkit="gmail")) == 1
497
498 def test_custom_toolkits_list(self, mock_session_deps):
760 - session = ToolRouterSession(
761 - client=mock_session_deps["client"],
762 - provider=mock_session_deps["provider"],
763 - auto_upload_download_files=True,
764 - session_id="sess-1",
765 - mcp=MagicMock(),
766 - experimental=mock_session_deps["experimental"],
767 - custom_tools_map=mock_session_deps["tools_map"],
768 - user_id="user-1",
769 - )
770 - toolkits = session.custom_toolkits()
771 - assert len(toolkits) == 1
772 - assert toolkits[0].slug == "ROLE_MANAGER"
773 - assert len(toolkits[0].tools) == 1
774 - assert toolkits[0].tools[0].slug == "LOCAL_ROLE_MANAGER_SET_ROLE"
775 -
776 - def test_custom_tools_empty_when_no_map(self):
777 - session = ToolRouterSession(
499 + s = _session(mock_session_deps)
500 + tks = s.custom_toolkits()
501 + assert len(tks) == 1
502 + assert tks[0].slug == "ROLE_MANAGER"
503 +
504 + def test_empty_when_no_map(self):
505 + s = ToolRouterSession(
506 client=MagicMock(),
507 provider=MagicMock(),
508 auto_upload_download_files=True,
781 - session_id="sess-1",
509 + session_id="s",
510 mcp=MagicMock(),
511 experimental=MagicMock(),
512 )
785 - assert session.custom_tools() == []
786 - assert session.custom_toolkits() == []
787 -
788 - def test_proxy_execute(self, mock_session_deps):
789 - mock_response = MagicMock()
790 - mock_response.status = 200
791 - mock_response.data = {"result": "ok"}
792 - mock_response.headers = {"Content-Type": "application/json"}
793 - mock_response.binary_data = None
794 - mock_session_deps[
795 - "client"
796 - ].tool_router.session.proxy_execute.return_value = mock_response
797 -
798 - session = ToolRouterSession(
799 - client=mock_session_deps["client"],
800 - provider=mock_session_deps["provider"],
801 - auto_upload_download_files=True,
802 - session_id="sess-1",
803 - mcp=MagicMock(),
804 - experimental=mock_session_deps["experimental"],
805 - )
806 - result = session.proxy_execute(
807 - toolkit="gmail",
808 - endpoint="https://gmail.googleapis.com/test",
809 - method="GET",
810 - )
811 - assert result["status"] == 200
812 - mock_session_deps[
813 - "client"
814 - ].tool_router.session.proxy_execute.assert_called_once()
513 + assert s.custom_tools() == []
514
515
516 # ────────────────────────────────────────────────────────────────
818 -# Multi-execute routing tests
517 +# Multi-execute routing
518 # ────────────────────────────────────────────────────────────────
519
520
521 class TestMultiExecuteRouting:
823 - def _make_session(self, grep_tool, mock_client=None):
824 - m = build_custom_tools_map([grep_tool])
825 - client = mock_client or MagicMock()
826 - session = ToolRouterSession(
827 - client=client,
522 + def _make_session(self, *tools):
523 + m = build_custom_tools_map(list(tools))
524 + return ToolRouterSession(
525 + client=MagicMock(),
526 provider=MagicMock(),
527 auto_upload_download_files=True,
830 - session_id="sess-1",
528 + session_id="s",
529 mcp=MagicMock(),
530 experimental=MagicMock(),
531 custom_tools_map=m,
834 - user_id="user-1",
532 + user_id="u",
533 )
836 - return session
837 -
838 - def test_route_all_local(self, grep_tool):
839 - session = self._make_session(grep_tool)
840 - mock_tools_model = MagicMock()
534
842 - result = session._route_multi_execute(
843 - {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "test"}}]},
844 - mock_tools_model,
535 + def test_single_local(self, grep_tool):
536 + s = self._make_session(grep_tool)
537 + result = s._route_multi_execute(
538 + {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "x"}}]},
539 + MagicMock(),
540 None,
541 )
847 - # Single local tool returns unwrapped
542 assert result["successful"] is True
849 - assert result["data"]["matches"] == ["test"]
850 -
851 - def test_route_all_remote(self, grep_tool):
852 - session = self._make_session(grep_tool)
853 - mock_tools_model = MagicMock()
854 -
855 - remote_response = {
543 + assert result["data"]["matches"] == ["x"]
544 +
545 + def test_all_remote(self, grep_tool):
546 + s = self._make_session(grep_tool)
547 + tm = MagicMock()
548 + remote = {"data": {"results": []}, "error": None, "successful": True}
549 + tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
550 + result = s._route_multi_execute(
551 + {"tools": [{"tool_slug": "REMOTE", "arguments": {}}]}, tm, None
552 + )
553 + assert result == remote
554 +
555 + def test_mixed(self, grep_tool):
556 + s = self._make_session(grep_tool)
557 + tm = MagicMock()
558 + remote = {
559 "data": {
560 "results": [
858 - {"tool_slug": "GMAIL_SEND", "response": {"successful": True}}
561 + {"tool_slug": "R", "response": {"successful": True, "data": {}}}
562 ]
563 },
564 "error": None,
565 "successful": True,
566 }
864 - mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
865 - lambda slug, args: remote_response
866 - )
867 -
868 - result = session._route_multi_execute(
567 + tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
568 + result = s._route_multi_execute(
569 {
570 "tools": [
871 - {"tool_slug": "GMAIL_SEND", "arguments": {"to": "alice@x.com"}}
571 + {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
572 + {"tool_slug": "REMOTE", "arguments": {}},
573 ]
574 },
874 - mock_tools_model,
575 + tm,
576 None,
577 )
877 - assert result == remote_response
578 + assert len(result["data"]["results"]) == 2
579
879 - def test_route_mixed_local_and_remote(self, grep_tool):
880 - session = self._make_session(grep_tool)
881 - mock_tools_model = MagicMock()
580 + def test_failure_propagated(self):
581 + @exp.tool()
582 + def ok_tool(input: GrepInput, ctx):
583 + """OK."""
584 + return {"ok": True}
585
883 - remote_response = {
884 - "data": {
885 - "results": [
886 - {
887 - "tool_slug": "GMAIL_SEND",
888 - "response": {"successful": True, "data": {"sent": True}},
889 - }
890 - ]
891 - },
892 - "error": None,
893 - "successful": True,
894 - }
895 - mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
896 - lambda slug, args: remote_response
897 - )
586 + @exp.tool()
587 + def bad_tool(input: GrepInput, ctx):
588 + """Bad."""
589 + raise RuntimeError("boom")
590
899 - result = session._route_multi_execute(
900 - {
901 - "tools": [
902 - {"tool_slug": "GREP", "arguments": {"pattern": "test"}},
903 - {"tool_slug": "GMAIL_SEND", "arguments": {"to": "alice@x.com"}},
904 - ]
905 - },
906 - mock_tools_model,
907 - None,
908 - )
909 - # Should have merged results
910 - assert result["successful"] is True
911 - results = result["data"]["results"]
912 - assert len(results) == 2
913 - # First should be the local GREP result
914 - assert results[0]["tool_slug"] == "GREP"
915 - assert results[0]["response"]["successful"] is True
916 - # Second should be the remote result
917 - assert results[1]["tool_slug"] == "GMAIL_SEND"
918 -
919 - def test_route_empty_tools(self, grep_tool):
920 - session = self._make_session(grep_tool)
921 - mock_tools_model = MagicMock()
922 - fallback_result = {"data": {}, "error": None, "successful": True}
923 - mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
924 - lambda slug, args: fallback_result
925 - )
926 -
927 - result = session._route_multi_execute({"tools": []}, mock_tools_model, None)
928 - # Should fall back to remote
929 - assert result == fallback_result
930 -
931 - def test_route_multiple_local_tools(self):
932 - tool1 = experimental_create_tool(
933 - "TOOL_A",
934 - name="A",
935 - description="D",
936 - input_params=GrepInput,
937 - execute=lambda i, c: {"tool": "A", "pattern": i.pattern},
938 - )
939 - tool2 = experimental_create_tool(
940 - "TOOL_B",
941 - name="B",
942 - description="D",
943 - input_params=GrepInput,
944 - execute=lambda i, c: {"tool": "B", "pattern": i.pattern},
945 - )
946 - m = build_custom_tools_map([tool1, tool2])
947 - session = ToolRouterSession(
948 - client=MagicMock(),
949 - provider=MagicMock(),
950 - auto_upload_download_files=True,
951 - session_id="sess-1",
952 - mcp=MagicMock(),
953 - experimental=MagicMock(),
954 - custom_tools_map=m,
955 - user_id="user-1",
956 - )
957 - result = session._route_multi_execute(
958 - {
959 - "tools": [
960 - {"tool_slug": "TOOL_A", "arguments": {"pattern": "x"}},
961 - {"tool_slug": "TOOL_B", "arguments": {"pattern": "y"}},
962 - ]
963 - },
964 - MagicMock(),
965 - None,
966 - )
967 - assert result["successful"] is True
968 - results = result["data"]["results"]
969 - assert len(results) == 2
970 - assert results[0]["response"]["data"]["tool"] == "A"
971 - assert results[1]["response"]["data"]["tool"] == "B"
972 -
973 - def test_route_propagates_local_failure(self):
974 - ok_tool = experimental_create_tool(
975 - "OK",
976 - name="OK",
977 - description="D",
978 - input_params=GrepInput,
979 - execute=lambda i, c: {"ok": True},
980 - )
981 - bad_tool = experimental_create_tool(
982 - "BAD",
983 - name="Bad",
984 - description="D",
985 - input_params=GrepInput,
986 - execute=lambda i, c: (_ for _ in ()).throw(RuntimeError("boom")),
987 - )
988 - m = build_custom_tools_map([ok_tool, bad_tool])
989 - session = ToolRouterSession(
990 - client=MagicMock(),
991 - provider=MagicMock(),
992 - auto_upload_download_files=True,
993 - session_id="sess-1",
994 - mcp=MagicMock(),
995 - experimental=MagicMock(),
996 - custom_tools_map=m,
997 - user_id="user-1",
998 - )
999 - result = session._route_multi_execute(
591 + s = self._make_session(ok_tool, bad_tool)
592 + result = s._route_multi_execute(
593 {
594 "tools": [
1002 - {"tool_slug": "OK", "arguments": {"pattern": "x"}},
1003 - {"tool_slug": "BAD", "arguments": {"pattern": "y"}},
595 + {"tool_slug": "OK_TOOL", "arguments": {"pattern": "x"}},
596 + {"tool_slug": "BAD_TOOL", "arguments": {"pattern": "y"}},
597 ]
598 },
599 MagicMock(),
600 None,
601 )
1009 - # Overall result should report failure
602 assert result["successful"] is False
603 assert "1 out of 2" in result["error"]
1012 - # Individual results preserved
1013 - results = result["data"]["results"]
1014 - assert results[0]["response"]["successful"] is True
1015 - assert results[1]["response"]["successful"] is False