Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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__.pyindex 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 AuthConfigsfrom .connected_accounts import ConnectedAccounts-from .custom_tool import ExperimentalAPI, ExperimentalToolkit+from .custom_tool import ExperimentalToolkitfrom .custom_tool_types import (CustomTool,RegisteredCustomTool,RegisteredCustomToolkit,SessionContext,)+from .experimental import ExperimentalAPIfrom .mcp import MCPfrom .tool_router import ToolRouterfrom .tool_router_constants import SESSION_PRESET_DIRECT_TOOLSdiff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.pyindex 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.pynew file mode 100644index 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 decoratordiff --git a/python/composio/sdk.py b/python/composio/sdk.pyindex 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 ExperimentalAPIself.experimental = ExperimentalAPI(client=self._client)diff --git a/python/tests/test_connected_accounts.py b/python/tests/test_connected_accounts.pyindex 86a3a429b..858e0a3ec 100644--- a/python/tests/test_connected_accounts.py+++ b/python/tests/test_connected_accounts.py@@ -575,7 +575,7 @@ class TestConnectedAccountsAcl:@pytest.fixturedef experimental(self, mock_client):- from composio.core.models.custom_tool import ExperimentalAPI+ from composio.core.models.experimental import ExperimentalAPIreturn 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 ExperimentalAPIwith 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.pyindex 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, Fieldfrom 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 ExperimentalAPIfrom composio.core.models.session_context import SessionContextImplfrom composio.core.models.tool_router_session import ToolRouterSessionfrom composio.exceptions import ValidationError-# ────────────────────────────────────────────────────────────────# Fixtures# ────────────────────────────────────────────────────────────────diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.pyindex be51e8f9e..a7b6561be 100644--- a/python/tests/test_tool_router.py+++ b/python/tests/test_tool_router.py@@ -6,7 +6,7 @@ import pytestfrom composio_client import omitfrom pydantic import BaseModel, Field-from composio.core.models.custom_tool import ExperimentalAPI+from composio.core.models.experimental import ExperimentalAPIfrom composio.core.models.tool_router import (SESSION_PRESET_DIRECT_TOOLS,ToolkitConnectionsDetails,