Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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

Dhawal Upadhyay6196f2e338ff
diff --git a/python/composio/__init__.py b/python/composio/__init__.py
index 143e25b44..033065579 100644
--- a/python/composio/__init__.py
+++ b/python/composio/__init__.py
@@ -1,8 +1,4 @@
from .__version__ import __version__
-from .core.models.custom_tool import (
- experimental_create_tool,
- experimental_create_toolkit,
-)
from .core.models.custom_tool_types import (
CustomTool,
CustomToolkit,
@@ -47,8 +43,6 @@ __all__ = (
"WebhookEventType",
"after_execute",
"before_execute",
- "experimental_create_tool",
- "experimental_create_toolkit",
"is_connection_expired_event",
"schema_modifier",
"__version__",
diff --git a/python/composio/core/models/__init__.py b/python/composio/core/models/__init__.py
index 9770a0612..565b9da62 100644
--- a/python/composio/core/models/__init__.py
+++ b/python/composio/core/models/__init__.py
@@ -1,6 +1,6 @@
from .auth_configs import AuthConfigs
from .connected_accounts import ConnectedAccounts
-from .custom_tool import experimental_create_tool, experimental_create_toolkit
+from .custom_tool import ExperimentalAPI, ExperimentalToolkit
from .custom_tool_types import (
CustomTool,
CustomToolkit,
@@ -35,6 +35,8 @@ __all__ = [
"ConnectionStatusEnum",
"CustomTool",
"CustomToolkit",
+ "ExperimentalAPI",
+ "ExperimentalToolkit",
"MCP",
"ProxyExecuteResponse",
"RegisteredCustomTool",
@@ -51,7 +53,5 @@ __all__ = [
"WebhookConnectionMetadata",
"WebhookEvent",
"WebhookEventType",
- "experimental_create_tool",
- "experimental_create_toolkit",
"is_connection_expired_event",
]
diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.py
index 318d89057..a6185b40d 100644
--- a/python/composio/core/models/custom_tool.py
+++ b/python/composio/core/models/custom_tool.py
@@ -1,29 +1,47 @@
-"""Factory functions for creating custom tools and toolkits.
+"""Custom tools and toolkits for tool router sessions.
+
+Decorator API for defining custom tools that run in-process alongside
+remote Composio tools. Accessed via ``composio.experimental``.
Usage::
- from composio import experimental_create_tool, experimental_create_toolkit
from pydantic import BaseModel, Field
+ from composio import Composio
+
+ composio = Composio()
class GrepInput(BaseModel):
pattern: str = Field(description="Pattern to search for")
- grep = experimental_create_tool("GREP",
- name="Grep Search",
- description="Search for patterns in files",
- input_params=GrepInput,
- execute=lambda input, ctx: {"matches": []},
- )
+ @composio.experimental.tool()
+ def grep(input: GrepInput, ctx):
+ \"\"\"Search for a pattern in local files.\"\"\"
+ return {"matches": []}
- dev_tools = experimental_create_toolkit("DEV_TOOLS",
+ dev_tools = composio.experimental.Toolkit(
+ slug="DEV_TOOLS",
name="Dev Tools",
description="Local dev utilities",
- tools=[grep],
+ )
+
+ @dev_tools.tool()
+ def search_code(input: GrepInput, ctx):
+ \"\"\"Search developer resources.\"\"\"
+ return {"results": []}
+
+ session = composio.create(
+ user_id="default",
+ experimental={
+ "custom_tools": [grep],
+ "custom_toolkits": [dev_tools],
+ },
)
"""
from __future__ import annotations
+import asyncio
+import inspect
import typing as t
from pydantic import BaseModel
@@ -120,18 +138,17 @@ def _get_input_json_schema(model: t.Type[BaseModel]) -> t.Dict[str, t.Any]:
schema["properties"] = full_schema["properties"]
if "required" in full_schema:
schema["required"] = full_schema["required"]
- # Inline $defs if present (Pydantic puts nested models there)
if "$defs" in full_schema:
schema["$defs"] = full_schema["$defs"]
return schema
# ────────────────────────────────────────────────────────────────
-# Factory functions
+# Internal tool creation (used by decorator API)
# ────────────────────────────────────────────────────────────────
-def experimental_create_tool(
+def _create_tool(
slug: str,
*,
name: str,
@@ -141,80 +158,22 @@ def experimental_create_tool(
extends_toolkit: t.Optional[str] = None,
output_params: t.Optional[t.Type[BaseModel]] = None,
) -> CustomTool:
- """Create a custom tool for use in tool router sessions.
-
- The returned object is a lightweight reference containing the tool's metadata
- and execute function. Pass it to
- ``composio.create(user_id, experimental={"custom_tools": [...]})``
- to bind it to a session.
-
- Just return the result data from ``execute``, or raise an error.
- The SDK wraps it into the standard response format internally.
-
- :param slug: Unique tool identifier (alphanumeric, underscores, hyphens;
- no LOCAL_ or COMPOSIO_ prefix)
- :param name: Human-readable display name
- :param description: Tool description (used for BM25 search matching)
- :param input_params: Pydantic BaseModel class for input parameters
- :param execute: Function ``(input, ctx) -> dict`` that executes the tool
- :param extends_toolkit: Composio toolkit slug to inherit auth from (e.g. 'gmail')
- :param output_params: Optional Pydantic BaseModel class for output documentation
- :returns: A CustomTool to pass to session creation
-
- Example — standalone tool (no auth)::
-
- class GrepInput(BaseModel):
- pattern: str = Field(description="Pattern to search for")
- path: str = Field(description="File path")
-
- grep = experimental_create_tool("GREP",
- name="Grep Search",
- description="Search for patterns in files",
- input_params=GrepInput,
- execute=lambda input, ctx: {"matches": []},
- )
-
- Example — tool extending a Composio toolkit (inherits auth)::
-
- class DraftInput(BaseModel):
- to: str = Field(description="Recipient email")
- subject: str = Field(description="Subject")
- body: str = Field(description="Body")
-
- create_draft = experimental_create_tool("CREATE_DRAFT",
- name="Create Gmail draft",
- description="Create a real Gmail draft via the Gmail API",
- extends_toolkit="gmail",
- input_params=DraftInput,
- execute=lambda input, ctx: ctx.proxy_execute(
- toolkit="gmail",
- endpoint="https://gmail.googleapis.com/gmail/v1/users/me/drafts",
- method="POST",
- body={"message": {"raw": "..."}},
- ),
- )
- """
- context = "experimental_create_tool"
+ """Internal: create and validate a CustomTool."""
+ context = "experimental.tool"
- # Validate slug
_validate_slug(slug, context)
- # Validate required fields
if not name:
raise ValidationError(f"{context}: name is required")
if not description:
raise ValidationError(f"{context}: description is required")
- # Validate input_params is a Pydantic BaseModel subclass (not an instance)
- # and produces an object-shaped JSON Schema (rejects RootModel[list[...]] etc.)
if not isinstance(input_params, type) or not issubclass(input_params, BaseModel):
raise ValidationError(
f"{context}: input_params must be a Pydantic BaseModel subclass. "
f"Tool input parameters are always an object with named properties."
)
- # Reject RootModel and other non-object schemas — tool router only passes
- # named argument objects, so the schema must have named properties.
try:
from pydantic import RootModel
@@ -225,28 +184,22 @@ def experimental_create_tool(
f"named properties."
)
except ImportError:
- pass # RootModel not available in older Pydantic
+ pass
- # Validate execute is callable and synchronous
if not callable(execute):
raise ValidationError(f"{context}: execute must be a callable")
- import asyncio
-
if asyncio.iscoroutinefunction(execute):
raise ValidationError(
f"{context}: execute must be a synchronous function, not async. "
f"The Composio Python SDK is synchronous — use a regular "
- f"'def execute(input, ctx)' instead of 'async def'."
+ f"'def fn(input, ctx)' instead of 'async def'."
)
- # Early length validation
_validate_slug_length(slug, extends_toolkit, context)
- # Convert Pydantic model → JSON Schema
input_schema = _get_input_json_schema(input_params)
- # Convert output schema if provided
output_schema: t.Optional[t.Dict[str, t.Any]] = None
if output_params is not None:
if not isinstance(output_params, type) or not issubclass(
@@ -269,65 +222,248 @@ def experimental_create_tool(
)
-def experimental_create_toolkit(
- slug: str,
+def _infer_tool_from_function(
+ fn: t.Callable[..., t.Any],
*,
- name: str,
- description: str,
- tools: t.List[CustomTool],
-) -> CustomToolkit:
- """Create a custom toolkit that groups related tools.
+ slug: t.Optional[str] = None,
+ name: t.Optional[str] = None,
+ description: t.Optional[str] = None,
+ extends_toolkit: t.Optional[str] = None,
+ output_params: t.Optional[t.Type[BaseModel]] = None,
+) -> CustomTool:
+ """Create a CustomTool by inferring metadata from a decorated function.
+
+ - slug: from ``fn.__name__.upper()``
+ - name: from ``fn.__name__`` humanized
+ - description: from ``fn.__doc__``
+ - input_params: from the first parameter with a BaseModel type annotation
+ """
+ # Infer slug
+ actual_slug = slug or fn.__name__.upper()
+ actual_name = name or fn.__name__.replace("_", " ").title()
+ actual_description = description or (fn.__doc__ or "").strip()
+
+ if not actual_description:
+ raise ValidationError(
+ f"experimental.tool: description is required. "
+ f'Add a docstring to "{fn.__name__}" or pass description=...'
+ )
+
+ # Infer input_params from type annotation
+ sig = inspect.signature(fn)
+ params = list(sig.parameters.values())
+ input_params: t.Optional[t.Type[BaseModel]] = None
+ for p in params:
+ if p.annotation is not inspect.Parameter.empty:
+ ann = p.annotation
+ if isinstance(ann, type) and issubclass(ann, BaseModel):
+ input_params = ann
+ break
+
+ if input_params is None:
+ raise ValidationError(
+ f'experimental.tool: could not infer input parameters for "{fn.__name__}". '
+ f"Annotate a parameter with a Pydantic BaseModel subclass, e.g. "
+ f"def {fn.__name__}(input: MyInput, ctx): ..."
+ )
+
+ # Wrap function to match CustomToolExecuteFn: (input, ctx) -> dict
+ # Support both (input) and (input, ctx) signatures
+ num_params = len(params)
+ if num_params <= 1:
+
+ def execute(input: t.Any, ctx: t.Any) -> t.Dict[str, t.Any]:
+ return fn(input)
+ else:
+ execute = fn
+
+ return _create_tool(
+ slug=actual_slug,
+ name=actual_name,
+ description=actual_description,
+ input_params=input_params,
+ execute=execute,
+ extends_toolkit=extends_toolkit,
+ output_params=output_params,
+ )
- Tools passed here must NOT have ``extends_toolkit`` set — they inherit the
- toolkit identity instead.
- :param slug: Unique toolkit identifier (alphanumeric, underscores, hyphens;
- no LOCAL_ or COMPOSIO_ prefix)
- :param name: Human-readable display name
- :param description: Toolkit description
- :param tools: List of CustomTool objects to include in this toolkit
- :returns: A CustomToolkit to pass to session creation
+# ────────────────────────────────────────────────────────────────
+# ExperimentalToolkit — custom toolkit with .tool() decorator
+# ────────────────────────────────────────────────────────────────
+
+
+class ExperimentalToolkit:
+ """Custom toolkit that groups related tools under one namespace.
+
+ Use ``@toolkit.tool()`` to add tools. Pass the toolkit to
+ ``composio.create(experimental={"custom_toolkits": [toolkit]})``.
+
+ Tools added to a toolkit must NOT use ``extends_toolkit`` — they
+ inherit the toolkit identity instead.
Example::
- dev_tools = experimental_create_toolkit("DEV_TOOLS",
+ dev_tools = composio.experimental.Toolkit(
+ slug="DEV_TOOLS",
name="Dev Tools",
description="Local dev utilities",
- tools=[grep_tool, sed_tool],
)
+
+ @dev_tools.tool()
+ def search_code(input: SearchInput, ctx):
+ \"\"\"Search developer resources.\"\"\"
+ return {"results": []}
"""
- context = "experimental_create_toolkit"
- # Validate slug
- _validate_slug(slug, context)
+ def __init__(self, *, slug: str, name: str, description: str) -> None:
+ context = "experimental.Toolkit"
+ _validate_slug(slug, context)
+ if not name:
+ raise ValidationError(f"{context}: name is required")
+ if not description:
+ raise ValidationError(f"{context}: description is required")
+
+ self.slug = slug
+ self.name = name
+ self.description = description
+ self._tools: t.List[CustomTool] = []
+
+ @property
+ def tools(self) -> t.Tuple[CustomTool, ...]:
+ return tuple(self._tools)
+
+ @t.overload
+ def tool(self, fn: t.Callable[..., t.Any], /) -> CustomTool: ...
+
+ @t.overload
+ def tool(
+ self,
+ *,
+ slug: t.Optional[str] = None,
+ name: t.Optional[str] = None,
+ description: t.Optional[str] = None,
+ output_params: t.Optional[t.Type[BaseModel]] = None,
+ ) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
+
+ def tool(
+ self,
+ fn: t.Optional[t.Callable[..., t.Any]] = None,
+ *,
+ slug: t.Optional[str] = None,
+ name: t.Optional[str] = None,
+ description: t.Optional[str] = None,
+ output_params: t.Optional[t.Type[BaseModel]] = None,
+ ) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
+ """Decorator to add a tool to this toolkit.
+
+ Infers slug, name, description, and input_params from the function
+ if not explicitly provided.
+ """
+
+ def decorator(f: t.Callable[..., t.Any]) -> CustomTool:
+ custom_tool = _infer_tool_from_function(
+ f,
+ slug=slug,
+ name=name,
+ description=description,
+ output_params=output_params,
+ # No extends_toolkit for toolkit tools
+ )
+ if custom_tool.extends_toolkit:
+ raise ValidationError(
+ f'experimental.Toolkit.tool: tool "{custom_tool.slug}" has '
+ f"extends_toolkit set. Tools in a custom toolkit must not "
+ f"use extends_toolkit — they inherit the toolkit identity."
+ )
+ _validate_slug_length(
+ custom_tool.slug, self.slug, f'experimental.Toolkit("{self.slug}").tool'
+ )
+ self._tools.append(custom_tool)
+ return custom_tool
- # Validate required fields
- if not name:
- raise ValidationError(f"{context}: name is required")
- if not description:
- raise ValidationError(f"{context}: description is required")
+ if fn is not None:
+ return decorator(fn)
+ return decorator
- # Non-empty tools required
- if not tools:
- raise ValidationError(f"{context}: at least one tool is required")
- # Validate each tool
- for tool in tools:
- if tool.extends_toolkit:
- raise ValidationError(
- f'{context}: tool "{tool.slug}" has extends_toolkit set. '
- f"Tools in a custom toolkit must not use extends_toolkit — "
- f"they inherit the toolkit identity instead."
+# ────────────────────────────────────────────────────────────────
+# ExperimentalAPI — the composio.experimental namespace
+# ────────────────────────────────────────────────────────────────
+
+
+class ExperimentalAPI:
+ """Experimental APIs accessed via ``composio.experimental``.
+
+ Provides decorators for creating custom tools and toolkits
+ that run in-process alongside remote Composio tools.
+ """
+
+ Toolkit = ExperimentalToolkit
+
+ @t.overload
+ def tool(self, fn: t.Callable[..., t.Any], /) -> CustomTool: ...
+
+ @t.overload
+ def tool(
+ self,
+ *,
+ slug: t.Optional[str] = None,
+ name: t.Optional[str] = None,
+ description: t.Optional[str] = None,
+ extends_toolkit: t.Optional[str] = None,
+ output_params: t.Optional[t.Type[BaseModel]] = None,
+ ) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
+
+ def tool(
+ self,
+ fn: t.Optional[t.Callable[..., t.Any]] = None,
+ *,
+ slug: t.Optional[str] = None,
+ name: t.Optional[str] = None,
+ description: t.Optional[str] = None,
+ extends_toolkit: t.Optional[str] = None,
+ output_params: t.Optional[t.Type[BaseModel]] = None,
+ ) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
+ """Decorator to create a custom tool from a function.
+
+ Infers slug, name, description, and input_params from the function.
+ Override any with explicit keyword arguments.
+
+ Examples::
+
+ # Bare decorator — no parens
+ @composio.experimental.tool
+ def grep(input: GrepInput, ctx):
+ \"\"\"Search for a pattern.\"\"\"
+ return {"matches": []}
+
+ # With parens — no args
+ @composio.experimental.tool()
+ def grep(input: GrepInput, ctx):
+ \"\"\"Search for a pattern.\"\"\"
+ return {"matches": []}
+
+ # With extends_toolkit — inherits auth
+ @composio.experimental.tool(extends_toolkit="gmail")
+ def create_draft(input: DraftInput, ctx):
+ \"\"\"Create a Gmail draft.\"\"\"
+ return ctx.proxy_execute(toolkit="gmail", ...)
+ """
+
+ def decorator(f: t.Callable[..., t.Any]) -> CustomTool:
+ return _infer_tool_from_function(
+ f,
+ slug=slug,
+ name=name,
+ description=description,
+ extends_toolkit=extends_toolkit,
+ output_params=output_params,
)
- # Early length validation with toolkit slug
- _validate_slug_length(tool.slug, slug, f'{context}("{slug}")')
- return CustomToolkit(
- slug=slug,
- name=name,
- description=description,
- tools=tuple(tools),
- )
+ if fn is not None:
+ return decorator(fn)
+ return decorator
# ────────────────────────────────────────────────────────────────
@@ -354,7 +490,7 @@ def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.An
def serialize_custom_toolkits(
- toolkits: t.List[CustomToolkit],
+ toolkits: t.Sequence[t.Union[CustomToolkit, ExperimentalToolkit]],
) -> t.List[t.Dict[str, t.Any]]:
"""Serialize custom toolkits into the format expected by the backend."""
result = []
@@ -388,12 +524,9 @@ def serialize_custom_toolkits(
def build_custom_tools_map(
tools: t.List[CustomTool],
- toolkits: t.Optional[t.List[CustomToolkit]] = None,
+ toolkits: t.Optional[t.List[t.Union[CustomToolkit, ExperimentalToolkit]]] = None,
) -> CustomToolsMap:
- """Build a CustomToolsMap from custom tools and toolkits.
-
- Used internally by ToolRouter.create() to construct the per-session routing map.
- """
+ """Build a CustomToolsMap from custom tools and toolkits."""
by_final_slug: t.Dict[str, CustomToolsMapEntry] = {}
by_original_slug: t.Dict[str, CustomToolsMapEntry] = {}
@@ -445,24 +578,20 @@ def build_custom_tools_map(
return CustomToolsMap(
by_final_slug=by_final_slug,
by_original_slug=by_original_slug,
- toolkits=list(toolkits) if toolkits else None,
+ toolkits=list(toolkits) if toolkits else None, # type: ignore[arg-type]
)
def build_custom_tools_map_from_response(
tools: t.List[CustomTool],
- toolkits: t.Optional[t.List[CustomToolkit]],
+ toolkits: t.Optional[t.List[t.Union[CustomToolkit, ExperimentalToolkit]]],
experimental: t.Optional[SessionCreateResponseExperimental],
) -> CustomToolsMap:
- """Build a CustomToolsMap using the slug/original_slug mapping from the backend response.
-
- Uses the backend's authoritative prefixed slugs instead of computing them client-side.
- """
+ """Build a CustomToolsMap using the slug/original_slug mapping from the backend response."""
by_final_slug: t.Dict[str, CustomToolsMapEntry] = {}
by_original_slug: t.Dict[str, CustomToolsMapEntry] = {}
- # Build lookup from original slug → handle + toolkit
- # Detect duplicate original slugs across standalone tools and toolkit tools
+ # Build lookup from original slug -> handle + toolkit
handles_by_original: t.Dict[str, t.Tuple[CustomTool, t.Optional[str]]] = {}
for handle in tools:
key = handle.slug.upper()
@@ -488,22 +617,19 @@ def build_custom_tools_map_from_response(
) -> None:
match = handles_by_original.get(original_slug.upper())
if not match:
- return # Response tool not found in our handles
+ return
handle, default_toolkit = match
resolved_toolkit = toolkit if toolkit is not None else default_toolkit
entry = CustomToolsMapEntry(
handle=handle, final_slug=final_slug, toolkit=resolved_toolkit
)
- # Store with uppercased keys to match find_custom_tool's .upper() lookup
by_final_slug[final_slug.upper()] = entry
by_original_slug[original_slug.upper()] = entry
- # Map standalone custom tools from response
if experimental and experimental.custom_tools:
for ct in experimental.custom_tools:
add_entry(ct.slug, ct.original_slug, ct.extends_toolkit)
- # Map toolkit custom tools from response
if experimental and experimental.custom_toolkits:
for ctk in experimental.custom_toolkits:
for ctk_tool in ctk.tools:
@@ -512,5 +638,5 @@ def build_custom_tools_map_from_response(
return CustomToolsMap(
by_final_slug=by_final_slug,
by_original_slug=by_original_slug,
- toolkits=list(toolkits) if toolkits else None,
+ toolkits=list(toolkits) if toolkits else None, # type: ignore[arg-type]
)
diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.py
index 5409ddd5f..8cefafd6b 100644
--- a/python/composio/core/models/tool_router.py
+++ b/python/composio/core/models/tool_router.py
@@ -18,6 +18,7 @@ from composio_client.types.tool_router import session_create_params
from composio.client import HttpClient
from composio.core.models.base import Resource
from composio.core.models.custom_tool import (
+ ExperimentalToolkit,
build_custom_tools_map_from_response,
serialize_custom_tools,
serialize_custom_toolkits,
@@ -194,7 +195,7 @@ class ToolRouterExperimentalConfig(te.TypedDict, total=False):
assistive_prompt: ToolRouterAssistivePromptConfig
custom_tools: t.List["CustomTool"]
- custom_toolkits: t.List["CustomToolkit"]
+ custom_toolkits: t.List[t.Union["CustomToolkit", "ExperimentalToolkit"]]
@dataclass
diff --git a/python/composio/sdk.py b/python/composio/sdk.py
index 599c9653a..09b69e0e5 100644
--- a/python/composio/sdk.py
+++ b/python/composio/sdk.py
@@ -144,6 +144,11 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
self.connected_accounts = ConnectedAccounts(client=self._client)
self.mcp = MCP(client=self._client)
+ # experimental API — decorators for custom tools and toolkits
+ from composio.core.models.custom_tool import ExperimentalAPI
+
+ self.experimental = ExperimentalAPI()
+
# initialize tool router methods
self.tool_router = ToolRouter(
client=self._client,
diff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.py
index 4387949d9..340f15c03 100644
--- a/python/tests/test_custom_tools.py
+++ b/python/tests/test_custom_tools.py
@@ -1,7 +1,8 @@
"""Tests for custom tools in tool router sessions.
Covers:
-- Factory function validation (slug rules, required fields, Pydantic model check)
+- Decorator API (inference, overrides, validation)
+- Toolkit builder with @toolkit.tool() decorator
- Slug prefixing and collision detection
- Serialization to API format
- Custom tool execution (validation, defaults, errors)
@@ -16,8 +17,9 @@ from unittest.mock import MagicMock
import pytest
from pydantic import BaseModel, Field
-from composio import experimental_create_tool, experimental_create_toolkit
from composio.core.models.custom_tool import (
+ ExperimentalAPI,
+ ExperimentalToolkit,
build_custom_tools_map,
build_custom_tools_map_from_response,
serialize_custom_tools,
@@ -36,6 +38,8 @@ from composio.exceptions import ValidationError
# Fixtures
# ────────────────────────────────────────────────────────────────
+exp = ExperimentalAPI()
+
class GrepInput(BaseModel):
pattern: str = Field(description="Pattern to search for")
@@ -54,50 +58,41 @@ class SetRoleInput(BaseModel):
@pytest.fixture
def grep_tool():
- return experimental_create_tool(
- "GREP",
- name="Grep Search",
- description="Search for patterns in files",
- input_params=GrepInput,
- execute=lambda input, ctx: {"matches": [input.pattern], "path": input.path},
- )
+ @exp.tool()
+ def grep(input: GrepInput, ctx):
+ """Search for patterns in files."""
+ return {"matches": [input.pattern], "path": input.path}
+
+ return grep
@pytest.fixture
def email_tool():
- return experimental_create_tool(
- "GET_EMAILS",
- name="Get Emails",
- description="Get emails from Gmail",
- input_params=EmailInput,
- execute=lambda input, ctx: {"emails": []},
- extends_toolkit="gmail",
- )
+ @exp.tool(extends_toolkit="gmail")
+ def get_emails(input: EmailInput, ctx):
+ """Get emails from Gmail."""
+ return {"emails": []}
+
+ return get_emails
@pytest.fixture
def set_role_tool():
- return experimental_create_tool(
- "SET_ROLE",
- name="Set role",
- description="Set a user's role",
- input_params=SetRoleInput,
- execute=lambda input, ctx: {
- "user_id": input.user_id,
- "role": input.role,
- "updated": True,
- },
- )
+ @exp.tool()
+ def set_role(input: SetRoleInput, ctx):
+ """Set a user's role."""
+ return {"user_id": input.user_id, "role": input.role, "updated": True}
+
+ return set_role
@pytest.fixture
def role_toolkit(set_role_tool):
- return experimental_create_toolkit(
- "ROLE_MANAGER",
- name="Role Manager",
- description="Manage user roles",
- tools=[set_role_tool],
+ tk = ExperimentalToolkit(
+ slug="ROLE_MANAGER", name="Role Manager", description="Manage user roles"
)
+ tk._tools.append(set_role_tool)
+ return tk
class MockSessionContext:
@@ -111,248 +106,179 @@ class MockSessionContext:
# ────────────────────────────────────────────────────────────────
-# Factory validation tests
+# Decorator API tests
# ────────────────────────────────────────────────────────────────
-class TestCreateCustomTool:
- def test_creates_tool_with_valid_params(self, grep_tool):
- assert grep_tool.slug == "GREP"
- assert grep_tool.name == "Grep Search"
- assert grep_tool.description == "Search for patterns in files"
- assert grep_tool.extends_toolkit is None
- assert grep_tool.input_schema["type"] == "object"
- assert "pattern" in grep_tool.input_schema["properties"]
- assert grep_tool.output_schema is None
-
- def test_creates_extension_tool(self, email_tool):
- assert email_tool.slug == "GET_EMAILS"
- assert email_tool.extends_toolkit == "gmail"
-
- def test_slug_empty(self):
- with pytest.raises(ValidationError, match="slug is required"):
- experimental_create_tool(
- "",
- name="Bad",
- description="Bad",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
-
- def test_slug_invalid_chars(self):
- with pytest.raises(ValidationError, match="alphanumeric"):
- experimental_create_tool(
- "BAD SLUG!",
- name="Bad",
- description="Bad",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
-
- def test_slug_local_prefix(self):
- with pytest.raises(ValidationError, match="LOCAL_"):
- experimental_create_tool(
- "LOCAL_BAD",
- name="Bad",
- description="Bad",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
-
- def test_slug_composio_prefix(self):
- with pytest.raises(ValidationError, match="COMPOSIO_"):
- experimental_create_tool(
- "COMPOSIO_BAD",
- name="Bad",
- description="Bad",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
-
- def test_name_required(self):
- with pytest.raises(ValidationError, match="name is required"):
- experimental_create_tool(
- "GOOD",
- name="",
- description="Desc",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
-
- def test_description_required(self):
+class TestDecoratorTool:
+ def test_bare_decorator(self):
+ @exp.tool
+ def my_tool(input: GrepInput, ctx):
+ """My tool description."""
+ return {}
+
+ assert my_tool.slug == "MY_TOOL"
+ assert my_tool.name == "My Tool"
+ assert my_tool.description == "My tool description."
+ assert my_tool.input_schema["type"] == "object"
+ assert "pattern" in my_tool.input_schema["properties"]
+
+ def test_decorator_with_parens(self):
+ @exp.tool()
+ def search(input: GrepInput, ctx):
+ """Search stuff."""
+ return {}
+
+ assert search.slug == "SEARCH"
+
+ def test_decorator_with_extends_toolkit(self):
+ @exp.tool(extends_toolkit="gmail")
+ def fetch_mail(input: EmailInput, ctx):
+ """Fetch mail."""
+ return {}
+
+ assert fetch_mail.extends_toolkit == "gmail"
+
+ def test_decorator_explicit_overrides(self):
+ @exp.tool(slug="CUSTOM", name="Custom Name", description="Custom desc")
+ def whatever(input: GrepInput, ctx):
+ """Original docstring."""
+ return {}
+
+ assert whatever.slug == "CUSTOM"
+ assert whatever.name == "Custom Name"
+ assert whatever.description == "Custom desc"
+
+ def test_infers_from_function_name(self):
+ @exp.tool()
+ def search_user_by_email(input: GrepInput, ctx):
+ """Find a user."""
+ return {}
+
+ assert search_user_by_email.slug == "SEARCH_USER_BY_EMAIL"
+ assert search_user_by_email.name == "Search User By Email"
+
+ def test_infers_description_from_docstring(self):
+ @exp.tool()
+ def my_func(input: GrepInput, ctx):
+ """Trimmed docstring."""
+ return {}
+
+ assert my_func.description == "Trimmed docstring."
+
+ def test_missing_docstring_raises(self):
with pytest.raises(ValidationError, match="description is required"):
- experimental_create_tool(
- "GOOD",
- name="Name",
- description="",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
-
- def test_input_params_must_be_basemodel_subclass(self):
- with pytest.raises(ValidationError, match="BaseModel subclass"):
- experimental_create_tool(
- "GOOD",
- name="Name",
- description="Desc",
- input_params=dict, # type: ignore
- execute=lambda i, c: {},
- )
-
- def test_input_params_must_not_be_instance(self):
+
+ @exp.tool()
+ def no_doc(input: GrepInput, ctx):
+ return {}
+
+ def test_missing_basemodel_annotation_raises(self):
with pytest.raises(ValidationError, match="BaseModel subclass"):
- experimental_create_tool(
- "GOOD",
- name="Name",
- description="Desc",
- input_params=GrepInput(pattern="x"), # type: ignore
- execute=lambda i, c: {},
- )
-
- def test_execute_must_be_callable(self):
- with pytest.raises(ValidationError, match="callable"):
- experimental_create_tool(
- "GOOD",
- name="Name",
- description="Desc",
- input_params=GrepInput,
- execute="not a function", # type: ignore
- )
-
- def test_slug_length_validation_standalone(self):
- # LOCAL_ + 55 chars = 61 > 60
- with pytest.raises(ValidationError, match="too long"):
- experimental_create_tool(
- "A" * 55,
- name="Name",
- description="Desc",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
-
- def test_slug_length_validation_extension(self):
- # LOCAL_ + GMAIL_ + slug must be <= 60
- with pytest.raises(ValidationError, match="too long"):
- experimental_create_tool(
- "A" * 50,
- name="Name",
- description="Desc",
- input_params=GrepInput,
- execute=lambda i, c: {},
- extends_toolkit="gmail",
- )
-
- def test_output_params(self):
- class OutputSchema(BaseModel):
- matches: int
-
- tool = experimental_create_tool(
- "TOOL",
- name="Tool",
- description="Desc",
- input_params=GrepInput,
- execute=lambda i, c: {},
- output_params=OutputSchema,
- )
- assert tool.output_schema is not None
- assert "properties" in tool.output_schema
- def test_rejects_root_model(self):
+ @exp.tool()
+ def bad(x: str, ctx):
+ """Bad tool."""
+ return {}
+
+ def test_async_function_rejected(self):
+ with pytest.raises(ValidationError, match="synchronous"):
+
+ @exp.tool()
+ async def async_tool(input: GrepInput, ctx):
+ """Async tool."""
+ return {}
+
+ def test_root_model_rejected(self):
from pydantic import RootModel
class ListInput(RootModel[list[int]]):
pass
with pytest.raises(ValidationError, match="RootModel"):
- experimental_create_tool(
- "BAD",
- name="Bad",
- description="Desc",
- input_params=ListInput,
- execute=lambda i, c: {},
- )
-
- def test_rejects_async_execute(self):
- async def async_execute(input, ctx):
- return {"result": "ok"}
- with pytest.raises(ValidationError, match="synchronous"):
- experimental_create_tool(
- "ASYNC",
- name="Async",
- description="Desc",
- input_params=GrepInput,
- execute=async_execute,
- )
+ @exp.tool()
+ def bad(input: ListInput, ctx):
+ """Bad tool."""
+ return {}
+
+ def test_single_param_function(self):
+ """Function with only input param (no ctx) should work."""
+
+ @exp.tool()
+ def simple(input: GrepInput):
+ """Simple tool."""
+ return {"pattern": input.pattern}
+
+ m = build_custom_tools_map([simple])
+ entry = find_custom_tool(m, "SIMPLE")
+ result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore
+ assert result["successful"] is True
+ assert result["data"]["pattern"] == "test"
+
+ def test_slug_validation(self):
+ with pytest.raises(ValidationError, match="LOCAL_"):
+
+ @exp.tool(slug="LOCAL_BAD")
+ def bad(input: GrepInput, ctx):
+ """Bad tool."""
+ return {}
+
+ def test_creates_frozen_custom_tool(self):
+ @exp.tool()
+ def frozen(input: GrepInput, ctx):
+ """Frozen tool."""
+ return {}
+
+ with pytest.raises(AttributeError):
+ frozen.slug = "NEW" # type: ignore
def test_input_schema_includes_defaults(self, grep_tool):
- # path has default="." - Pydantic won't include it in required
assert "pattern" in grep_tool.input_schema.get("required", [])
assert "path" not in grep_tool.input_schema.get("required", [])
- def test_frozen_dataclass(self, grep_tool):
- with pytest.raises(AttributeError):
- grep_tool.slug = "NEW" # type: ignore
-
-
-class TestCreateCustomToolkit:
- def test_creates_toolkit(self, role_toolkit, set_role_tool):
- assert role_toolkit.slug == "ROLE_MANAGER"
- assert role_toolkit.name == "Role Manager"
- assert len(role_toolkit.tools) == 1
- assert role_toolkit.tools[0].slug == "SET_ROLE"
-
- def test_rejects_empty_tools(self):
- with pytest.raises(ValidationError, match="at least one tool"):
- experimental_create_toolkit(
- "TK",
- name="TK",
- description="Desc",
- tools=[],
- )
-
- def test_rejects_extends_toolkit_in_tools(self, email_tool):
- with pytest.raises(ValidationError, match="extends_toolkit"):
- experimental_create_toolkit(
- "TK",
- name="TK",
- description="Desc",
- tools=[email_tool],
- )
-
- def test_slug_length_validation(self):
- tool = experimental_create_tool(
- "A" * 45,
- name="Name",
- description="Desc",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
- # LOCAL_ + LONG_TOOLKIT_ + AAAA... would exceed 60
- with pytest.raises(ValidationError, match="too long"):
- experimental_create_toolkit(
- "LONG_TOOLKIT",
- name="TK",
- description="Desc",
- tools=[tool],
- )
- def test_slug_validation(self):
+class TestToolkitBuilder:
+ def test_toolkit_with_decorator(self):
+ tk = ExperimentalToolkit(slug="MY_TK", name="My TK", description="Desc")
+
+ @tk.tool()
+ def tool_a(input: GrepInput, ctx):
+ """Tool A."""
+ return {}
+
+ @tk.tool()
+ def tool_b(input: GrepInput, ctx):
+ """Tool B."""
+ return {}
+
+ assert tk.slug == "MY_TK"
+ assert len(tk.tools) == 2
+ assert tk.tools[0].slug == "TOOL_A"
+ assert tk.tools[1].slug == "TOOL_B"
+
+ def test_toolkit_bare_decorator(self):
+ tk = ExperimentalToolkit(slug="TK2", name="TK2", description="Desc")
+
+ @tk.tool
+ def tool_c(input: GrepInput, ctx):
+ """Tool C."""
+ return {}
+
+ assert len(tk.tools) == 1
+
+ def test_toolkit_slug_validation(self):
with pytest.raises(ValidationError, match="LOCAL_"):
- experimental_create_toolkit(
- "LOCAL_BAD",
- name="TK",
- description="Desc",
- tools=[
- experimental_create_tool(
- "T",
- name="T",
- description="D",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
- ],
- )
+ ExperimentalToolkit(slug="LOCAL_BAD", name="Bad", description="Desc")
+
+ def test_toolkit_name_required(self):
+ with pytest.raises(ValidationError, match="name is required"):
+ ExperimentalToolkit(slug="TK", name="", description="Desc")
+
+ def test_toolkit_via_experimental_api(self):
+ tk = exp.Toolkit(slug="API_TK", name="API TK", description="Via API")
+ assert isinstance(tk, ExperimentalToolkit)
+ assert tk.slug == "API_TK"
# ────────────────────────────────────────────────────────────────
@@ -365,7 +291,6 @@ class TestSerialization:
result = serialize_custom_tools([grep_tool])
assert len(result) == 1
assert result[0]["slug"] == "GREP"
- assert result[0]["name"] == "Grep Search"
assert result[0]["input_schema"]["type"] == "object"
assert "extends_toolkit" not in result[0]
@@ -378,7 +303,6 @@ class TestSerialization:
assert len(result) == 1
assert result[0]["slug"] == "ROLE_MANAGER"
assert len(result[0]["tools"]) == 1
- assert result[0]["tools"][0]["slug"] == "SET_ROLE"
# ────────────────────────────────────────────────────────────────
@@ -390,73 +314,28 @@ class TestCustomToolsMap:
def test_build_map_standalone(self, grep_tool):
m = build_custom_tools_map([grep_tool])
assert "LOCAL_GREP" in m.by_final_slug
- assert "GREP" in m.by_original_slug
def test_build_map_extension(self, email_tool):
m = build_custom_tools_map([email_tool])
assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug
- assert "GET_EMAILS" in m.by_original_slug
- def test_build_map_toolkit(self, set_role_tool, role_toolkit):
+ def test_build_map_toolkit(self, role_toolkit):
m = build_custom_tools_map([], [role_toolkit])
assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug
- assert "SET_ROLE" in m.by_original_slug
-
- def test_build_map_mixed(self, grep_tool, email_tool, role_toolkit):
- m = build_custom_tools_map([grep_tool, email_tool], [role_toolkit])
- assert len(m.by_final_slug) == 3
- assert len(m.by_original_slug) == 3
- def test_collision_detection_final_slug(self, grep_tool):
+ def test_collision_detection(self, grep_tool):
with pytest.raises(ValidationError, match="collision"):
build_custom_tools_map([grep_tool, grep_tool])
- def test_collision_detection_original_slug(self):
- tool1 = experimental_create_tool(
- "FOO",
- name="Foo",
- description="Desc",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
- # Same slug in a toolkit produces different final slug but same original
- # This would collide on original slug
- toolkit = experimental_create_toolkit(
- "TK",
- name="TK",
- description="D",
- tools=[
- experimental_create_tool(
- "FOO",
- name="Foo2",
- description="Desc2",
- input_params=GrepInput,
- execute=lambda i, c: {},
- )
- ],
- )
- with pytest.raises(ValidationError, match="collision"):
- build_custom_tools_map([tool1], [toolkit])
-
class TestFindCustomTool:
def test_find_by_final_slug(self, grep_tool):
m = build_custom_tools_map([grep_tool])
- entry = find_custom_tool(m, "LOCAL_GREP")
- assert entry is not None
- assert entry.final_slug == "LOCAL_GREP"
-
- def test_find_by_original_slug(self, grep_tool):
- m = build_custom_tools_map([grep_tool])
- entry = find_custom_tool(m, "GREP")
- assert entry is not None
- assert entry.final_slug == "LOCAL_GREP"
+ assert find_custom_tool(m, "LOCAL_GREP") is not None
def test_find_case_insensitive(self, grep_tool):
m = build_custom_tools_map([grep_tool])
- entry = find_custom_tool(m, "grep")
- assert entry is not None
- assert entry.final_slug == "LOCAL_GREP"
+ assert find_custom_tool(m, "grep") is not None
def test_find_nonexistent(self, grep_tool):
m = build_custom_tools_map([grep_tool])
@@ -468,43 +347,32 @@ class TestFindCustomTool:
class TestBuildMapFromResponse:
def test_builds_from_response(self, grep_tool, email_tool, role_toolkit):
- # Mock response experimental
mock_exp = MagicMock()
-
- mock_ct1 = MagicMock()
- mock_ct1.slug = "LOCAL_GREP"
- mock_ct1.original_slug = "GREP"
- mock_ct1.extends_toolkit = None
-
- mock_ct2 = MagicMock()
- mock_ct2.slug = "LOCAL_GMAIL_GET_EMAILS"
- mock_ct2.original_slug = "GET_EMAILS"
- mock_ct2.extends_toolkit = "gmail"
-
+ mock_ct1 = MagicMock(
+ slug="LOCAL_GREP", original_slug="GREP", extends_toolkit=None
+ )
+ mock_ct2 = MagicMock(
+ slug="LOCAL_GMAIL_GET_EMAILS",
+ original_slug="GET_EMAILS",
+ extends_toolkit="gmail",
+ )
mock_exp.custom_tools = [mock_ct1, mock_ct2]
-
- mock_ctk = MagicMock()
- mock_ctk.slug = "ROLE_MANAGER"
- mock_ctk_tool = MagicMock()
- mock_ctk_tool.slug = "LOCAL_ROLE_MANAGER_SET_ROLE"
- mock_ctk_tool.original_slug = "SET_ROLE"
- mock_ctk.tools = [mock_ctk_tool]
+ mock_ctk = MagicMock(slug="ROLE_MANAGER")
+ mock_ctk.tools = [
+ MagicMock(slug="LOCAL_ROLE_MANAGER_SET_ROLE", original_slug="SET_ROLE")
+ ]
mock_exp.custom_toolkits = [mock_ctk]
m = build_custom_tools_map_from_response(
- [grep_tool, email_tool],
- [role_toolkit],
- mock_exp,
+ [grep_tool, email_tool], [role_toolkit], mock_exp
)
-
assert "LOCAL_GREP" in m.by_final_slug
assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug
assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug
- assert m.by_final_slug["LOCAL_GMAIL_GET_EMAILS"].toolkit == "gmail"
# ────────────────────────────────────────────────────────────────
-# Custom tool execution tests
+# Execution tests
# ────────────────────────────────────────────────────────────────
@@ -515,52 +383,24 @@ class TestExecuteCustomTool:
result = execute_custom_tool(entry, {"pattern": "hello"}, MockSessionContext()) # type: ignore
assert result["successful"] is True
assert result["data"]["matches"] == ["hello"]
- assert result["data"]["path"] == "." # default value
- assert result["error"] is None
-
- def test_applies_pydantic_defaults(self, grep_tool):
- m = build_custom_tools_map([grep_tool])
- entry = find_custom_tool(m, "GREP")
- result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore
- assert result["data"]["path"] == "." # default applied
def test_validation_failure(self, grep_tool):
m = build_custom_tools_map([grep_tool])
entry = find_custom_tool(m, "GREP")
- result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignore # missing required "pattern"
+ result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignore
assert result["successful"] is False
- assert "validation" in result["error"].lower()
-
- def test_execute_function_error(self):
- def bad_execute(input, ctx):
- raise RuntimeError("Something went wrong")
-
- tool = experimental_create_tool(
- "BAD",
- name="Bad",
- description="Desc",
- input_params=GrepInput,
- execute=bad_execute,
- )
- m = build_custom_tools_map([tool])
+
+ def test_execute_error(self):
+ @exp.tool()
+ def bad(input: GrepInput, ctx):
+ """Bad."""
+ raise RuntimeError("boom")
+
+ m = build_custom_tools_map([bad])
entry = find_custom_tool(m, "BAD")
result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignore
assert result["successful"] is False
- assert "Something went wrong" in result["error"]
-
- def test_execute_returns_none(self):
- tool = experimental_create_tool(
- "NOOP",
- name="Noop",
- description="Returns None",
- input_params=GrepInput,
- execute=lambda i, c: None, # type: ignore
- )
- m = build_custom_tools_map([tool])
- entry = find_custom_tool(m, "NOOP")
- result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignore
- assert result["successful"] is True
- assert result["data"] == {}
+ assert "boom" in result["error"]
# ────────────────────────────────────────────────────────────────
@@ -569,447 +409,195 @@ class TestExecuteCustomTool:
class TestSessionContextImpl:
- def test_user_id(self):
- ctx = SessionContextImpl(
- client=MagicMock(),
- user_id="user-1",
- session_id="sess-1",
- )
- assert ctx.user_id == "user-1"
-
- def test_execute_routes_to_sibling(self, grep_tool):
+ def test_sibling_routing(self, grep_tool):
m = build_custom_tools_map([grep_tool])
ctx = SessionContextImpl(
- client=MagicMock(),
- user_id="user-1",
- session_id="sess-1",
- custom_tools_map=m,
+ client=MagicMock(), user_id="u", session_id="s", custom_tools_map=m
)
result = ctx.execute("GREP", {"pattern": "test"})
assert result["successful"] is True
- assert result["data"]["matches"] == ["test"]
- def test_execute_falls_back_to_remote(self, grep_tool):
+ def test_remote_fallback(self, grep_tool):
m = build_custom_tools_map([grep_tool])
mock_client = MagicMock()
- mock_response = MagicMock()
- mock_response.data = {"remote": True}
- mock_response.error = None
- mock_client.tool_router.session.execute.return_value = mock_response
-
+ mock_client.tool_router.session.execute.return_value = MagicMock(
+ data={"remote": True}, error=None
+ )
ctx = SessionContextImpl(
- client=mock_client,
- user_id="user-1",
- session_id="sess-1",
- custom_tools_map=m,
+ client=mock_client, user_id="u", session_id="s", custom_tools_map=m
)
- result = ctx.execute("NONEXISTENT_TOOL", {"arg": "val"})
+ ctx.execute("NONEXISTENT", {"arg": "val"})
mock_client.tool_router.session.execute.assert_called_once()
- assert result["data"] == {"remote": True}
def test_proxy_execute(self):
mock_client = MagicMock()
- mock_response = MagicMock()
- mock_response.status = 200
- mock_response.data = {"result": "ok"}
- mock_response.headers = {"Content-Type": "application/json"}
- mock_response.binary_data = None
- mock_client.tool_router.session.proxy_execute.return_value = mock_response
-
- ctx = SessionContextImpl(
- client=mock_client,
- user_id="user-1",
- session_id="sess-1",
+ mock_client.tool_router.session.proxy_execute.return_value = MagicMock(
+ status=200, data={"ok": True}, headers={}, binary_data=None
)
+ ctx = SessionContextImpl(client=mock_client, user_id="u", session_id="s")
result = ctx.proxy_execute(
- toolkit="gmail",
- endpoint="https://gmail.googleapis.com/test",
- method="GET",
+ toolkit="gmail", endpoint="https://example.com", method="GET"
)
assert result["status"] == 200
- assert result["data"] == {"result": "ok"}
- mock_client.tool_router.session.proxy_execute.assert_called_once()
# ────────────────────────────────────────────────────────────────
-# ToolRouterSession integration tests
+# ToolRouterSession integration
# ────────────────────────────────────────────────────────────────
@pytest.fixture
def mock_session_deps(grep_tool, email_tool, role_toolkit):
- """Create mock dependencies for ToolRouterSession with custom tools."""
- client = MagicMock()
- provider = MagicMock()
- experimental = MagicMock()
- experimental.files = MagicMock()
- experimental.assistive_prompt = None
-
- # Build tools map
- tools_map = build_custom_tools_map([grep_tool, email_tool], [role_toolkit])
-
return {
- "client": client,
- "provider": provider,
- "experimental": experimental,
- "tools_map": tools_map,
+ "client": MagicMock(),
+ "provider": MagicMock(),
+ "experimental": MagicMock(),
+ "tools_map": build_custom_tools_map([grep_tool, email_tool], [role_toolkit]),
}
+def _session(deps, **overrides):
+ kwargs = dict(
+ client=deps["client"],
+ provider=deps["provider"],
+ auto_upload_download_files=True,
+ session_id="s",
+ mcp=MagicMock(),
+ experimental=deps["experimental"],
+ custom_tools_map=deps["tools_map"],
+ user_id="u",
+ )
+ kwargs.update(overrides)
+ return ToolRouterSession(**kwargs)
+
+
class TestToolRouterSessionCustomTools:
- def test_execute_routes_to_local(self, mock_session_deps, grep_tool):
- session = ToolRouterSession(
- client=mock_session_deps["client"],
- provider=mock_session_deps["provider"],
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=mock_session_deps["experimental"],
- custom_tools_map=mock_session_deps["tools_map"],
- user_id="user-1",
- )
- result = session.execute("GREP", arguments={"pattern": "test"})
- # session.execute returns SessionExecuteResponse shape: data, error, log_id
- assert result["data"]["matches"] == ["test"]
+ def test_execute_local(self, mock_session_deps):
+ s = _session(mock_session_deps)
+ result = s.execute("GREP", arguments={"pattern": "x"})
assert result["error"] is None
assert result["log_id"] == ""
- # Should NOT have called the backend
mock_session_deps["client"].tool_router.session.execute.assert_not_called()
- def test_execute_routes_to_local_by_final_slug(self, mock_session_deps):
- session = ToolRouterSession(
- client=mock_session_deps["client"],
- provider=mock_session_deps["provider"],
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=mock_session_deps["experimental"],
- custom_tools_map=mock_session_deps["tools_map"],
- user_id="user-1",
- )
- result = session.execute("LOCAL_GREP", arguments={"pattern": "test"})
- assert result["error"] is None
-
- def test_execute_case_insensitive(self, mock_session_deps):
- session = ToolRouterSession(
- client=mock_session_deps["client"],
- provider=mock_session_deps["provider"],
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=mock_session_deps["experimental"],
- custom_tools_map=mock_session_deps["tools_map"],
- user_id="user-1",
- )
- result = session.execute("grep", arguments={"pattern": "test"})
- assert result["error"] is None
-
- def test_execute_routes_to_remote(self, mock_session_deps):
- mock_response = MagicMock()
+ def test_execute_remote(self, mock_session_deps):
mock_session_deps[
"client"
- ].tool_router.session.execute.return_value = mock_response
-
- session = ToolRouterSession(
- client=mock_session_deps["client"],
- provider=mock_session_deps["provider"],
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=mock_session_deps["experimental"],
- custom_tools_map=mock_session_deps["tools_map"],
- user_id="user-1",
- )
- session.execute("GMAIL_SEND_EMAIL", arguments={"to": "[email protected]"})
+ ].tool_router.session.execute.return_value = MagicMock()
+ s = _session(mock_session_deps)
+ s.execute("GMAIL_SEND_EMAIL", arguments={"to": "[email protected]"})
mock_session_deps["client"].tool_router.session.execute.assert_called_once()
def test_custom_tools_list(self, mock_session_deps):
- session = ToolRouterSession(
- client=mock_session_deps["client"],
- provider=mock_session_deps["provider"],
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=mock_session_deps["experimental"],
- custom_tools_map=mock_session_deps["tools_map"],
- user_id="user-1",
- )
- tools = session.custom_tools()
- assert len(tools) == 3
- slugs = {t.slug for t in tools}
- assert "LOCAL_GREP" in slugs
- assert "LOCAL_GMAIL_GET_EMAILS" in slugs
- assert "LOCAL_ROLE_MANAGER_SET_ROLE" in slugs
-
- def test_custom_tools_filter_by_toolkit(self, mock_session_deps):
- session = ToolRouterSession(
- client=mock_session_deps["client"],
- provider=mock_session_deps["provider"],
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=mock_session_deps["experimental"],
- custom_tools_map=mock_session_deps["tools_map"],
- user_id="user-1",
- )
- gmail_tools = session.custom_tools(toolkit="gmail")
- assert len(gmail_tools) == 1
- assert gmail_tools[0].slug == "LOCAL_GMAIL_GET_EMAILS"
+ s = _session(mock_session_deps)
+ assert len(s.custom_tools()) == 3
+
+ def test_custom_tools_filter(self, mock_session_deps):
+ s = _session(mock_session_deps)
+ assert len(s.custom_tools(toolkit="gmail")) == 1
def test_custom_toolkits_list(self, mock_session_deps):
- session = ToolRouterSession(
- client=mock_session_deps["client"],
- provider=mock_session_deps["provider"],
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=mock_session_deps["experimental"],
- custom_tools_map=mock_session_deps["tools_map"],
- user_id="user-1",
- )
- toolkits = session.custom_toolkits()
- assert len(toolkits) == 1
- assert toolkits[0].slug == "ROLE_MANAGER"
- assert len(toolkits[0].tools) == 1
- assert toolkits[0].tools[0].slug == "LOCAL_ROLE_MANAGER_SET_ROLE"
-
- def test_custom_tools_empty_when_no_map(self):
- session = ToolRouterSession(
+ s = _session(mock_session_deps)
+ tks = s.custom_toolkits()
+ assert len(tks) == 1
+ assert tks[0].slug == "ROLE_MANAGER"
+
+ def test_empty_when_no_map(self):
+ s = ToolRouterSession(
client=MagicMock(),
provider=MagicMock(),
auto_upload_download_files=True,
- session_id="sess-1",
+ session_id="s",
mcp=MagicMock(),
experimental=MagicMock(),
)
- assert session.custom_tools() == []
- assert session.custom_toolkits() == []
-
- def test_proxy_execute(self, mock_session_deps):
- mock_response = MagicMock()
- mock_response.status = 200
- mock_response.data = {"result": "ok"}
- mock_response.headers = {"Content-Type": "application/json"}
- mock_response.binary_data = None
- mock_session_deps[
- "client"
- ].tool_router.session.proxy_execute.return_value = mock_response
-
- session = ToolRouterSession(
- client=mock_session_deps["client"],
- provider=mock_session_deps["provider"],
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=mock_session_deps["experimental"],
- )
- result = session.proxy_execute(
- toolkit="gmail",
- endpoint="https://gmail.googleapis.com/test",
- method="GET",
- )
- assert result["status"] == 200
- mock_session_deps[
- "client"
- ].tool_router.session.proxy_execute.assert_called_once()
+ assert s.custom_tools() == []
# ────────────────────────────────────────────────────────────────
-# Multi-execute routing tests
+# Multi-execute routing
# ────────────────────────────────────────────────────────────────
class TestMultiExecuteRouting:
- def _make_session(self, grep_tool, mock_client=None):
- m = build_custom_tools_map([grep_tool])
- client = mock_client or MagicMock()
- session = ToolRouterSession(
- client=client,
+ def _make_session(self, *tools):
+ m = build_custom_tools_map(list(tools))
+ return ToolRouterSession(
+ client=MagicMock(),
provider=MagicMock(),
auto_upload_download_files=True,
- session_id="sess-1",
+ session_id="s",
mcp=MagicMock(),
experimental=MagicMock(),
custom_tools_map=m,
- user_id="user-1",
+ user_id="u",
)
- return session
-
- def test_route_all_local(self, grep_tool):
- session = self._make_session(grep_tool)
- mock_tools_model = MagicMock()
- result = session._route_multi_execute(
- {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "test"}}]},
- mock_tools_model,
+ def test_single_local(self, grep_tool):
+ s = self._make_session(grep_tool)
+ result = s._route_multi_execute(
+ {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "x"}}]},
+ MagicMock(),
None,
)
- # Single local tool returns unwrapped
assert result["successful"] is True
- assert result["data"]["matches"] == ["test"]
-
- def test_route_all_remote(self, grep_tool):
- session = self._make_session(grep_tool)
- mock_tools_model = MagicMock()
-
- remote_response = {
+ assert result["data"]["matches"] == ["x"]
+
+ def test_all_remote(self, grep_tool):
+ s = self._make_session(grep_tool)
+ tm = MagicMock()
+ remote = {"data": {"results": []}, "error": None, "successful": True}
+ tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
+ result = s._route_multi_execute(
+ {"tools": [{"tool_slug": "REMOTE", "arguments": {}}]}, tm, None
+ )
+ assert result == remote
+
+ def test_mixed(self, grep_tool):
+ s = self._make_session(grep_tool)
+ tm = MagicMock()
+ remote = {
"data": {
"results": [
- {"tool_slug": "GMAIL_SEND", "response": {"successful": True}}
+ {"tool_slug": "R", "response": {"successful": True, "data": {}}}
]
},
"error": None,
"successful": True,
}
- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
- lambda slug, args: remote_response
- )
-
- result = session._route_multi_execute(
+ tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
+ result = s._route_multi_execute(
{
"tools": [
- {"tool_slug": "GMAIL_SEND", "arguments": {"to": "[email protected]"}}
+ {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
+ {"tool_slug": "REMOTE", "arguments": {}},
]
},
- mock_tools_model,
+ tm,
None,
)
- assert result == remote_response
+ assert len(result["data"]["results"]) == 2
- def test_route_mixed_local_and_remote(self, grep_tool):
- session = self._make_session(grep_tool)
- mock_tools_model = MagicMock()
+ def test_failure_propagated(self):
+ @exp.tool()
+ def ok_tool(input: GrepInput, ctx):
+ """OK."""
+ return {"ok": True}
- remote_response = {
- "data": {
- "results": [
- {
- "tool_slug": "GMAIL_SEND",
- "response": {"successful": True, "data": {"sent": True}},
- }
- ]
- },
- "error": None,
- "successful": True,
- }
- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
- lambda slug, args: remote_response
- )
+ @exp.tool()
+ def bad_tool(input: GrepInput, ctx):
+ """Bad."""
+ raise RuntimeError("boom")
- result = session._route_multi_execute(
- {
- "tools": [
- {"tool_slug": "GREP", "arguments": {"pattern": "test"}},
- {"tool_slug": "GMAIL_SEND", "arguments": {"to": "[email protected]"}},
- ]
- },
- mock_tools_model,
- None,
- )
- # Should have merged results
- assert result["successful"] is True
- results = result["data"]["results"]
- assert len(results) == 2
- # First should be the local GREP result
- assert results[0]["tool_slug"] == "GREP"
- assert results[0]["response"]["successful"] is True
- # Second should be the remote result
- assert results[1]["tool_slug"] == "GMAIL_SEND"
-
- def test_route_empty_tools(self, grep_tool):
- session = self._make_session(grep_tool)
- mock_tools_model = MagicMock()
- fallback_result = {"data": {}, "error": None, "successful": True}
- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
- lambda slug, args: fallback_result
- )
-
- result = session._route_multi_execute({"tools": []}, mock_tools_model, None)
- # Should fall back to remote
- assert result == fallback_result
-
- def test_route_multiple_local_tools(self):
- tool1 = experimental_create_tool(
- "TOOL_A",
- name="A",
- description="D",
- input_params=GrepInput,
- execute=lambda i, c: {"tool": "A", "pattern": i.pattern},
- )
- tool2 = experimental_create_tool(
- "TOOL_B",
- name="B",
- description="D",
- input_params=GrepInput,
- execute=lambda i, c: {"tool": "B", "pattern": i.pattern},
- )
- m = build_custom_tools_map([tool1, tool2])
- session = ToolRouterSession(
- client=MagicMock(),
- provider=MagicMock(),
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=MagicMock(),
- custom_tools_map=m,
- user_id="user-1",
- )
- result = session._route_multi_execute(
- {
- "tools": [
- {"tool_slug": "TOOL_A", "arguments": {"pattern": "x"}},
- {"tool_slug": "TOOL_B", "arguments": {"pattern": "y"}},
- ]
- },
- MagicMock(),
- None,
- )
- assert result["successful"] is True
- results = result["data"]["results"]
- assert len(results) == 2
- assert results[0]["response"]["data"]["tool"] == "A"
- assert results[1]["response"]["data"]["tool"] == "B"
-
- def test_route_propagates_local_failure(self):
- ok_tool = experimental_create_tool(
- "OK",
- name="OK",
- description="D",
- input_params=GrepInput,
- execute=lambda i, c: {"ok": True},
- )
- bad_tool = experimental_create_tool(
- "BAD",
- name="Bad",
- description="D",
- input_params=GrepInput,
- execute=lambda i, c: (_ for _ in ()).throw(RuntimeError("boom")),
- )
- m = build_custom_tools_map([ok_tool, bad_tool])
- session = ToolRouterSession(
- client=MagicMock(),
- provider=MagicMock(),
- auto_upload_download_files=True,
- session_id="sess-1",
- mcp=MagicMock(),
- experimental=MagicMock(),
- custom_tools_map=m,
- user_id="user-1",
- )
- result = session._route_multi_execute(
+ s = self._make_session(ok_tool, bad_tool)
+ result = s._route_multi_execute(
{
"tools": [
- {"tool_slug": "OK", "arguments": {"pattern": "x"}},
- {"tool_slug": "BAD", "arguments": {"pattern": "y"}},
+ {"tool_slug": "OK_TOOL", "arguments": {"pattern": "x"}},
+ {"tool_slug": "BAD_TOOL", "arguments": {"pattern": "y"}},
]
},
MagicMock(),
None,
)
- # Overall result should report failure
assert result["successful"] is False
assert "1 out of 2" in result["error"]
- # Individual results preserved
- results = result["data"]["results"]
- assert results[0]["response"]["successful"] is True
- assert results[1]["response"]["successful"] is False