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.

refactor(experimental-py): move ExperimentalAPI to its own module

venkat8238620df15222
diff --git a/python/composio/core/models/__init__.py b/python/composio/core/models/__init__.py
index f69dedec3..b975f5898 100644
--- a/python/composio/core/models/__init__.py
+++ b/python/composio/core/models/__init__.py
@@ -1,12 +1,13 @@
from .auth_configs import AuthConfigs
from .connected_accounts import ConnectedAccounts
-from .custom_tool import ExperimentalAPI, ExperimentalToolkit
+from .custom_tool import ExperimentalToolkit
from .custom_tool_types import (
CustomTool,
RegisteredCustomTool,
RegisteredCustomToolkit,
SessionContext,
)
+from .experimental import ExperimentalAPI
from .mcp import MCP
from .tool_router import ToolRouter
from .tool_router_constants import SESSION_PRESET_DIRECT_TOOLS
diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.py
index 0a7bf7e75..584b25e41 100644
--- a/python/composio/core/models/custom_tool.py
+++ b/python/composio/core/models/custom_tool.py
@@ -478,177 +478,6 @@ class ExperimentalToolkit:
return decorator
-# ────────────────────────────────────────────────────────────────
-# 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, plus experimental SDK
- methods whose shape may change in future releases.
- """
-
- Toolkit = ExperimentalToolkit
-
- def __init__(self, client: t.Optional[t.Any] = None) -> None:
- self._client = client
-
- def update_acl(
- self,
- nanoid: str,
- *,
- allow_all_users: t.Optional[bool] = None,
- allowed_user_ids: t.Optional[t.List[str]] = None,
- not_allowed_user_ids: t.Optional[t.List[str]] = None,
- ) -> t.Any:
- """
- Update the per-user ACL on a SHARED connected account. Experimental —
- shape may change in future releases.
-
- Only valid on SHARED connections; raises
- ``ComposioAclOnlyForSharedError`` on a PRIVATE connection. Omit a
- parameter to leave it unchanged; pass an empty list to clear an
- allow/deny list. At least one parameter must be provided.
-
- :param nanoid: The connected account ID (``ca_xxx``).
- :param allow_all_users: When True, any ``user_id`` may use this
- SHARED connection (subject to the deny list).
- :param allowed_user_ids: Explicit list of allowed ``user_id`` strings.
- Pass ``[]`` to clear.
- :param not_allowed_user_ids: Explicit deny list (wins over allow on
- conflict). Pass ``[]`` to clear — note that clearing the deny
- list silently re-grants access to previously-blocked users.
- :return: Response with ``id``, ``status``, and ``success``.
-
- Example:
- composio.experimental.update_acl(
- 'ca_abc',
- allow_all_users=True,
- not_allowed_user_ids=['user_bob'],
- )
- """
- from composio_client import BadRequestError, omit
-
- from composio import exceptions
-
- if self._client is None:
- raise exceptions.ValidationError(
- "update_acl requires a Composio client. Access it via "
- "composio.experimental.update_acl(...)."
- )
- if (
- allow_all_users is None
- and allowed_user_ids is None
- and not_allowed_user_ids is None
- ):
- raise exceptions.ValidationError(
- "update_acl requires at least one of allow_all_users, "
- "allowed_user_ids, or not_allowed_user_ids"
- )
-
- acl: t.Dict[str, t.Any] = {}
- if allow_all_users is not None:
- acl["allow_all_users"] = allow_all_users
- if allowed_user_ids is not None:
- acl["allowed_user_ids"] = allowed_user_ids
- if not_allowed_user_ids is not None:
- acl["not_allowed_user_ids"] = not_allowed_user_ids
-
- try:
- return self._client.connected_accounts.patch(
- nanoid,
- experimental={"acl_config_for_shared": acl},
- alias=omit,
- connection=omit,
- )
- except BadRequestError as error:
- message = str(error)
- if "acl_config_for_shared is only valid on SHARED" in message:
- raise exceptions.ComposioAclOnlyForSharedError(message) from error
- raise
-
- @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,
- preload: t.Optional[bool] = 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,
- preload: t.Optional[bool] = 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:
- annotation_locals = _get_caller_locals()
- return _infer_tool_from_function(
- f,
- slug=slug,
- name=name,
- description=description,
- extends_toolkit=extends_toolkit,
- output_params=output_params,
- preload=preload,
- annotation_locals=annotation_locals,
- )
-
- if fn is not None:
- return _infer_tool_from_function(
- fn,
- slug=slug,
- name=name,
- description=description,
- extends_toolkit=extends_toolkit,
- output_params=output_params,
- preload=preload,
- annotation_locals=_get_caller_locals(),
- )
- return decorator
-
-
# ────────────────────────────────────────────────────────────────
# Serialization (for backend API payload)
# ────────────────────────────────────────────────────────────────
diff --git a/python/composio/core/models/experimental.py b/python/composio/core/models/experimental.py
new file mode 100644
index 000000000..0d66679e2
--- /dev/null
+++ b/python/composio/core/models/experimental.py
@@ -0,0 +1,194 @@
+"""The ``composio.experimental`` namespace.
+
+Houses experimental SDK surfaces whose shape may change in future
+releases. Two flavours live here today:
+
+- Decorators for in-process custom tools and toolkits
+ (``composio.experimental.tool`` / ``composio.experimental.Toolkit``).
+ Implementation details for these still live in :mod:`custom_tool`;
+ this module just exposes them on the namespace.
+- Experimental SDK methods that take a Composio client
+ (``composio.experimental.update_acl``).
+
+Anything new on the ``composio.experimental`` namespace should land here,
+not on the underlying model modules.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from pydantic import BaseModel
+
+from .custom_tool import (
+ CustomTool,
+ ExperimentalToolkit,
+ _get_caller_locals,
+ _infer_tool_from_function,
+)
+
+
+class ExperimentalAPI:
+ """Experimental APIs accessed via ``composio.experimental``.
+
+ Provides decorators for creating custom tools and toolkits that run
+ in-process alongside remote Composio tools, plus experimental SDK
+ methods whose shape may change in future releases.
+ """
+
+ Toolkit = ExperimentalToolkit
+
+ def __init__(self, client: t.Optional[t.Any] = None) -> None:
+ self._client = client
+
+ def update_acl(
+ self,
+ nanoid: str,
+ *,
+ allow_all_users: t.Optional[bool] = None,
+ allowed_user_ids: t.Optional[t.List[str]] = None,
+ not_allowed_user_ids: t.Optional[t.List[str]] = None,
+ ) -> t.Any:
+ """
+ Update the per-user ACL on a SHARED connected account. Experimental —
+ shape may change in future releases.
+
+ Only valid on SHARED connections; raises
+ ``ComposioAclOnlyForSharedError`` on a PRIVATE connection. Omit a
+ parameter to leave it unchanged; pass an empty list to clear an
+ allow/deny list. At least one parameter must be provided.
+
+ :param nanoid: The connected account ID (``ca_xxx``).
+ :param allow_all_users: When True, any ``user_id`` may use this
+ SHARED connection (subject to the deny list).
+ :param allowed_user_ids: Explicit list of allowed ``user_id`` strings.
+ Pass ``[]`` to clear.
+ :param not_allowed_user_ids: Explicit deny list (wins over allow on
+ conflict). Pass ``[]`` to clear — note that clearing the deny
+ list silently re-grants access to previously-blocked users.
+ :return: Response with ``id``, ``status``, and ``success``.
+
+ Example:
+ composio.experimental.update_acl(
+ 'ca_abc',
+ allow_all_users=True,
+ not_allowed_user_ids=['user_bob'],
+ )
+ """
+ from composio_client import BadRequestError, omit
+
+ from composio import exceptions
+
+ if self._client is None:
+ raise exceptions.ValidationError(
+ "update_acl requires a Composio client. Access it via "
+ "composio.experimental.update_acl(...)."
+ )
+ if (
+ allow_all_users is None
+ and allowed_user_ids is None
+ and not_allowed_user_ids is None
+ ):
+ raise exceptions.ValidationError(
+ "update_acl requires at least one of allow_all_users, "
+ "allowed_user_ids, or not_allowed_user_ids"
+ )
+
+ acl: t.Dict[str, t.Any] = {}
+ if allow_all_users is not None:
+ acl["allow_all_users"] = allow_all_users
+ if allowed_user_ids is not None:
+ acl["allowed_user_ids"] = allowed_user_ids
+ if not_allowed_user_ids is not None:
+ acl["not_allowed_user_ids"] = not_allowed_user_ids
+
+ try:
+ return self._client.connected_accounts.patch(
+ nanoid,
+ experimental={"acl_config_for_shared": acl},
+ alias=omit,
+ connection=omit,
+ )
+ except BadRequestError as error:
+ message = str(error)
+ if "acl_config_for_shared is only valid on SHARED" in message:
+ raise exceptions.ComposioAclOnlyForSharedError(message) from error
+ raise
+
+ @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,
+ preload: t.Optional[bool] = 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,
+ preload: t.Optional[bool] = 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:
+ annotation_locals = _get_caller_locals()
+ return _infer_tool_from_function(
+ f,
+ slug=slug,
+ name=name,
+ description=description,
+ extends_toolkit=extends_toolkit,
+ output_params=output_params,
+ preload=preload,
+ annotation_locals=annotation_locals,
+ )
+
+ if fn is not None:
+ return _infer_tool_from_function(
+ fn,
+ slug=slug,
+ name=name,
+ description=description,
+ extends_toolkit=extends_toolkit,
+ output_params=output_params,
+ preload=preload,
+ annotation_locals=_get_caller_locals(),
+ )
+ return decorator
diff --git a/python/composio/sdk.py b/python/composio/sdk.py
index 882de093e..a5dd0d50b 100644
--- a/python/composio/sdk.py
+++ b/python/composio/sdk.py
@@ -181,7 +181,7 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
# experimental API — decorators for custom tools and toolkits,
# plus experimental SDK methods (e.g. update_acl)
- from composio.core.models.custom_tool import ExperimentalAPI
+ from composio.core.models.experimental import ExperimentalAPI
self.experimental = ExperimentalAPI(client=self._client)
diff --git a/python/tests/test_connected_accounts.py b/python/tests/test_connected_accounts.py
index 86a3a429b..858e0a3ec 100644
--- a/python/tests/test_connected_accounts.py
+++ b/python/tests/test_connected_accounts.py
@@ -575,7 +575,7 @@ class TestConnectedAccountsAcl:
@pytest.fixture
def experimental(self, mock_client):
- from composio.core.models.custom_tool import ExperimentalAPI
+ from composio.core.models.experimental import ExperimentalAPI
return ExperimentalAPI(client=mock_client)
@@ -741,7 +741,7 @@ class TestConnectedAccountsAcl:
experimental.update_acl("ca_abc", allow_all_users=True)
def test_update_acl_requires_client(self):
- from composio.core.models.custom_tool import ExperimentalAPI
+ from composio.core.models.experimental import ExperimentalAPI
with pytest.raises(exceptions.ValidationError):
ExperimentalAPI().update_acl("ca_abc", allow_all_users=True)
diff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.py
index 7e402981c..f6268b080 100644
--- a/python/tests/test_custom_tools.py
+++ b/python/tests/test_custom_tools.py
@@ -26,22 +26,21 @@ from composio_client.types.tool_router.session_proxy_execute_response import (
from pydantic import BaseModel, Field
from composio.core.models.custom_tool import (
- ExperimentalAPI,
ExperimentalToolkit,
build_custom_tools_map,
build_custom_tools_map_from_response,
- serialize_custom_tools,
serialize_custom_toolkits,
+ serialize_custom_tools,
)
from composio.core.models.custom_tool_execution import (
execute_custom_tool,
find_custom_tool,
)
+from composio.core.models.experimental import ExperimentalAPI
from composio.core.models.session_context import SessionContextImpl
from composio.core.models.tool_router_session import ToolRouterSession
from composio.exceptions import ValidationError
-
# ────────────────────────────────────────────────────────────────
# Fixtures
# ────────────────────────────────────────────────────────────────
diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.py
index be51e8f9e..a7b6561be 100644
--- a/python/tests/test_tool_router.py
+++ b/python/tests/test_tool_router.py
@@ -6,7 +6,7 @@ import pytest
from composio_client import omit
from pydantic import BaseModel, Field
-from composio.core.models.custom_tool import ExperimentalAPI
+from composio.core.models.experimental import ExperimentalAPI
from composio.core.models.tool_router import (
SESSION_PRESET_DIRECT_TOOLS,
ToolkitConnectionsDetails,