@devries-cameron20 / composio Mirror · read-only / commits / 38620df15
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 21, 21:00 UTC

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

ExperimentalAPI was sitting inside custom_tool.py because custom tools were the first thing the SDK exposed on the composio.experimental namespace. Now that update_acl has moved onto the same namespace, keeping the class in custom_tool.py reads wrong — grepping for update_acl lands in a file named after custom tools. Splits the class out into core/models/experimental.py. custom_tool.py keeps the custom-tool machinery (ExperimentalToolkit, decorator helpers, serializers); experimental.py imports what it needs from custom_tool.py and is now the home for anything on the composio.experimental namespace. Pure rearrangement — no behaviour change, no public-import-path change (composio.core.models still re-exports ExperimentalAPI). Stack-frame depth in _get_caller_locals(depth=2) stays correct: the decorator → user-module hop is the same regardless of which file ExperimentalAPI.tool lives in. Tests still pass (201/201), mypy still clean on composio/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

venkat82 committed May 12, 2026 at 20:53 UTC 38620df15222cf76303e9e400137154dca231762
7 files changed +202 -179
python/composio/core/models/__init__.py
+2 -1
@@ -1,12 +1,13 @@
1 from .auth_configs import AuthConfigs
2 from .connected_accounts import ConnectedAccounts
3 -from .custom_tool import ExperimentalAPI, ExperimentalToolkit
3 +from .custom_tool import ExperimentalToolkit
4 from .custom_tool_types import (
5 CustomTool,
6 RegisteredCustomTool,
7 RegisteredCustomToolkit,
8 SessionContext,
9 )
10 +from .experimental import ExperimentalAPI
11 from .mcp import MCP
12 from .tool_router import ToolRouter
13 from .tool_router_constants import SESSION_PRESET_DIRECT_TOOLS
python/composio/core/models/custom_tool.py
-171
@@ -478,177 +478,6 @@ class ExperimentalToolkit:
478 return decorator
479
480
481 -# ────────────────────────────────────────────────────────────────
482 -# ExperimentalAPI — the composio.experimental namespace
483 -# ────────────────────────────────────────────────────────────────
484 -
485 -
486 -class ExperimentalAPI:
487 - """Experimental APIs accessed via ``composio.experimental``.
488 -
489 - Provides decorators for creating custom tools and toolkits that run
490 - in-process alongside remote Composio tools, plus experimental SDK
491 - methods whose shape may change in future releases.
492 - """
493 -
494 - Toolkit = ExperimentalToolkit
495 -
496 - def __init__(self, client: t.Optional[t.Any] = None) -> None:
497 - self._client = client
498 -
499 - def update_acl(
500 - self,
501 - nanoid: str,
502 - *,
503 - allow_all_users: t.Optional[bool] = None,
504 - allowed_user_ids: t.Optional[t.List[str]] = None,
505 - not_allowed_user_ids: t.Optional[t.List[str]] = None,
506 - ) -> t.Any:
507 - """
508 - Update the per-user ACL on a SHARED connected account. Experimental —
509 - shape may change in future releases.
510 -
511 - Only valid on SHARED connections; raises
512 - ``ComposioAclOnlyForSharedError`` on a PRIVATE connection. Omit a
513 - parameter to leave it unchanged; pass an empty list to clear an
514 - allow/deny list. At least one parameter must be provided.
515 -
516 - :param nanoid: The connected account ID (``ca_xxx``).
517 - :param allow_all_users: When True, any ``user_id`` may use this
518 - SHARED connection (subject to the deny list).
519 - :param allowed_user_ids: Explicit list of allowed ``user_id`` strings.
520 - Pass ``[]`` to clear.
521 - :param not_allowed_user_ids: Explicit deny list (wins over allow on
522 - conflict). Pass ``[]`` to clear — note that clearing the deny
523 - list silently re-grants access to previously-blocked users.
524 - :return: Response with ``id``, ``status``, and ``success``.
525 -
526 - Example:
527 - composio.experimental.update_acl(
528 - 'ca_abc',
529 - allow_all_users=True,
530 - not_allowed_user_ids=['user_bob'],
531 - )
532 - """
533 - from composio_client import BadRequestError, omit
534 -
535 - from composio import exceptions
536 -
537 - if self._client is None:
538 - raise exceptions.ValidationError(
539 - "update_acl requires a Composio client. Access it via "
540 - "composio.experimental.update_acl(...)."
541 - )
542 - if (
543 - allow_all_users is None
544 - and allowed_user_ids is None
545 - and not_allowed_user_ids is None
546 - ):
547 - raise exceptions.ValidationError(
548 - "update_acl requires at least one of allow_all_users, "
549 - "allowed_user_ids, or not_allowed_user_ids"
550 - )
551 -
552 - acl: t.Dict[str, t.Any] = {}
553 - if allow_all_users is not None:
554 - acl["allow_all_users"] = allow_all_users
555 - if allowed_user_ids is not None:
556 - acl["allowed_user_ids"] = allowed_user_ids
557 - if not_allowed_user_ids is not None:
558 - acl["not_allowed_user_ids"] = not_allowed_user_ids
559 -
560 - try:
561 - return self._client.connected_accounts.patch(
562 - nanoid,
563 - experimental={"acl_config_for_shared": acl},
564 - alias=omit,
565 - connection=omit,
566 - )
567 - except BadRequestError as error:
568 - message = str(error)
569 - if "acl_config_for_shared is only valid on SHARED" in message:
570 - raise exceptions.ComposioAclOnlyForSharedError(message) from error
571 - raise
572 -
573 - @t.overload
574 - def tool(self, fn: t.Callable[..., t.Any], /) -> CustomTool: ...
575 -
576 - @t.overload
577 - def tool(
578 - self,
579 - *,
580 - slug: t.Optional[str] = None,
581 - name: t.Optional[str] = None,
582 - description: t.Optional[str] = None,
583 - extends_toolkit: t.Optional[str] = None,
584 - output_params: t.Optional[t.Type[BaseModel]] = None,
585 - preload: t.Optional[bool] = None,
586 - ) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
587 -
588 - def tool(
589 - self,
590 - fn: t.Optional[t.Callable[..., t.Any]] = None,
591 - *,
592 - slug: t.Optional[str] = None,
593 - name: t.Optional[str] = None,
594 - description: t.Optional[str] = None,
595 - extends_toolkit: t.Optional[str] = None,
596 - output_params: t.Optional[t.Type[BaseModel]] = None,
597 - preload: t.Optional[bool] = None,
598 - ) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
599 - """Decorator to create a custom tool from a function.
600 -
601 - Infers slug, name, description, and input_params from the function.
602 - Override any with explicit keyword arguments.
603 -
604 - Examples::
605 -
606 - # Bare decorator — no parens
607 - @composio.experimental.tool
608 - def grep(input: GrepInput, ctx):
609 - \"\"\"Search for a pattern.\"\"\"
610 - return {"matches": []}
611 -
612 - # With parens — no args
613 - @composio.experimental.tool()
614 - def grep(input: GrepInput, ctx):
615 - \"\"\"Search for a pattern.\"\"\"
616 - return {"matches": []}
617 -
618 - # With extends_toolkit — inherits auth
619 - @composio.experimental.tool(extends_toolkit="gmail")
620 - def create_draft(input: DraftInput, ctx):
621 - \"\"\"Create a Gmail draft.\"\"\"
622 - return ctx.proxy_execute(toolkit="gmail", ...)
623 - """
624 -
625 - def decorator(f: t.Callable[..., t.Any]) -> CustomTool:
626 - annotation_locals = _get_caller_locals()
627 - return _infer_tool_from_function(
628 - f,
629 - slug=slug,
630 - name=name,
631 - description=description,
632 - extends_toolkit=extends_toolkit,
633 - output_params=output_params,
634 - preload=preload,
635 - annotation_locals=annotation_locals,
636 - )
637 -
638 - if fn is not None:
639 - return _infer_tool_from_function(
640 - fn,
641 - slug=slug,
642 - name=name,
643 - description=description,
644 - extends_toolkit=extends_toolkit,
645 - output_params=output_params,
646 - preload=preload,
647 - annotation_locals=_get_caller_locals(),
648 - )
649 - return decorator
650 -
651 -
481 # ────────────────────────────────────────────────────────────────
482 # Serialization (for backend API payload)
483 # ────────────────────────────────────────────────────────────────
python/composio/core/models/experimental.py new
+194
@@ -0,0 +1,194 @@
1 +"""The ``composio.experimental`` namespace.
2 +
3 +Houses experimental SDK surfaces whose shape may change in future
4 +releases. Two flavours live here today:
5 +
6 +- Decorators for in-process custom tools and toolkits
7 + (``composio.experimental.tool`` / ``composio.experimental.Toolkit``).
8 + Implementation details for these still live in :mod:`custom_tool`;
9 + this module just exposes them on the namespace.
10 +- Experimental SDK methods that take a Composio client
11 + (``composio.experimental.update_acl``).
12 +
13 +Anything new on the ``composio.experimental`` namespace should land here,
14 +not on the underlying model modules.
15 +"""
16 +
17 +from __future__ import annotations
18 +
19 +import typing as t
20 +
21 +from pydantic import BaseModel
22 +
23 +from .custom_tool import (
24 + CustomTool,
25 + ExperimentalToolkit,
26 + _get_caller_locals,
27 + _infer_tool_from_function,
28 +)
29 +
30 +
31 +class ExperimentalAPI:
32 + """Experimental APIs accessed via ``composio.experimental``.
33 +
34 + Provides decorators for creating custom tools and toolkits that run
35 + in-process alongside remote Composio tools, plus experimental SDK
36 + methods whose shape may change in future releases.
37 + """
38 +
39 + Toolkit = ExperimentalToolkit
40 +
41 + def __init__(self, client: t.Optional[t.Any] = None) -> None:
42 + self._client = client
43 +
44 + def update_acl(
45 + self,
46 + nanoid: str,
47 + *,
48 + allow_all_users: t.Optional[bool] = None,
49 + allowed_user_ids: t.Optional[t.List[str]] = None,
50 + not_allowed_user_ids: t.Optional[t.List[str]] = None,
51 + ) -> t.Any:
52 + """
53 + Update the per-user ACL on a SHARED connected account. Experimental —
54 + shape may change in future releases.
55 +
56 + Only valid on SHARED connections; raises
57 + ``ComposioAclOnlyForSharedError`` on a PRIVATE connection. Omit a
58 + parameter to leave it unchanged; pass an empty list to clear an
59 + allow/deny list. At least one parameter must be provided.
60 +
61 + :param nanoid: The connected account ID (``ca_xxx``).
62 + :param allow_all_users: When True, any ``user_id`` may use this
63 + SHARED connection (subject to the deny list).
64 + :param allowed_user_ids: Explicit list of allowed ``user_id`` strings.
65 + Pass ``[]`` to clear.
66 + :param not_allowed_user_ids: Explicit deny list (wins over allow on
67 + conflict). Pass ``[]`` to clear — note that clearing the deny
68 + list silently re-grants access to previously-blocked users.
69 + :return: Response with ``id``, ``status``, and ``success``.
70 +
71 + Example:
72 + composio.experimental.update_acl(
73 + 'ca_abc',
74 + allow_all_users=True,
75 + not_allowed_user_ids=['user_bob'],
76 + )
77 + """
78 + from composio_client import BadRequestError, omit
79 +
80 + from composio import exceptions
81 +
82 + if self._client is None:
83 + raise exceptions.ValidationError(
84 + "update_acl requires a Composio client. Access it via "
85 + "composio.experimental.update_acl(...)."
86 + )
87 + if (
88 + allow_all_users is None
89 + and allowed_user_ids is None
90 + and not_allowed_user_ids is None
91 + ):
92 + raise exceptions.ValidationError(
93 + "update_acl requires at least one of allow_all_users, "
94 + "allowed_user_ids, or not_allowed_user_ids"
95 + )
96 +
97 + acl: t.Dict[str, t.Any] = {}
98 + if allow_all_users is not None:
99 + acl["allow_all_users"] = allow_all_users
100 + if allowed_user_ids is not None:
101 + acl["allowed_user_ids"] = allowed_user_ids
102 + if not_allowed_user_ids is not None:
103 + acl["not_allowed_user_ids"] = not_allowed_user_ids
104 +
105 + try:
106 + return self._client.connected_accounts.patch(
107 + nanoid,
108 + experimental={"acl_config_for_shared": acl},
109 + alias=omit,
110 + connection=omit,
111 + )
112 + except BadRequestError as error:
113 + message = str(error)
114 + if "acl_config_for_shared is only valid on SHARED" in message:
115 + raise exceptions.ComposioAclOnlyForSharedError(message) from error
116 + raise
117 +
118 + @t.overload
119 + def tool(self, fn: t.Callable[..., t.Any], /) -> CustomTool: ...
120 +
121 + @t.overload
122 + def tool(
123 + self,
124 + *,
125 + slug: t.Optional[str] = None,
126 + name: t.Optional[str] = None,
127 + description: t.Optional[str] = None,
128 + extends_toolkit: t.Optional[str] = None,
129 + output_params: t.Optional[t.Type[BaseModel]] = None,
130 + preload: t.Optional[bool] = None,
131 + ) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
132 +
133 + def tool(
134 + self,
135 + fn: t.Optional[t.Callable[..., t.Any]] = None,
136 + *,
137 + slug: t.Optional[str] = None,
138 + name: t.Optional[str] = None,
139 + description: t.Optional[str] = None,
140 + extends_toolkit: t.Optional[str] = None,
141 + output_params: t.Optional[t.Type[BaseModel]] = None,
142 + preload: t.Optional[bool] = None,
143 + ) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
144 + """Decorator to create a custom tool from a function.
145 +
146 + Infers slug, name, description, and input_params from the function.
147 + Override any with explicit keyword arguments.
148 +
149 + Examples::
150 +
151 + # Bare decorator — no parens
152 + @composio.experimental.tool
153 + def grep(input: GrepInput, ctx):
154 + \"\"\"Search for a pattern.\"\"\"
155 + return {"matches": []}
156 +
157 + # With parens — no args
158 + @composio.experimental.tool()
159 + def grep(input: GrepInput, ctx):
160 + \"\"\"Search for a pattern.\"\"\"
161 + return {"matches": []}
162 +
163 + # With extends_toolkit — inherits auth
164 + @composio.experimental.tool(extends_toolkit="gmail")
165 + def create_draft(input: DraftInput, ctx):
166 + \"\"\"Create a Gmail draft.\"\"\"
167 + return ctx.proxy_execute(toolkit="gmail", ...)
168 + """
169 +
170 + def decorator(f: t.Callable[..., t.Any]) -> CustomTool:
171 + annotation_locals = _get_caller_locals()
172 + return _infer_tool_from_function(
173 + f,
174 + slug=slug,
175 + name=name,
176 + description=description,
177 + extends_toolkit=extends_toolkit,
178 + output_params=output_params,
179 + preload=preload,
180 + annotation_locals=annotation_locals,
181 + )
182 +
183 + if fn is not None:
184 + return _infer_tool_from_function(
185 + fn,
186 + slug=slug,
187 + name=name,
188 + description=description,
189 + extends_toolkit=extends_toolkit,
190 + output_params=output_params,
191 + preload=preload,
192 + annotation_locals=_get_caller_locals(),
193 + )
194 + return decorator
python/composio/sdk.py
+1 -1
@@ -181,7 +181,7 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
181
182 # experimental API — decorators for custom tools and toolkits,
183 # plus experimental SDK methods (e.g. update_acl)
184 - from composio.core.models.custom_tool import ExperimentalAPI
184 + from composio.core.models.experimental import ExperimentalAPI
185
186 self.experimental = ExperimentalAPI(client=self._client)
187
python/tests/test_connected_accounts.py
+2 -2
@@ -575,7 +575,7 @@ class TestConnectedAccountsAcl:
575
576 @pytest.fixture
577 def experimental(self, mock_client):
578 - from composio.core.models.custom_tool import ExperimentalAPI
578 + from composio.core.models.experimental import ExperimentalAPI
579
580 return ExperimentalAPI(client=mock_client)
581
@@ -741,7 +741,7 @@ class TestConnectedAccountsAcl:
741 experimental.update_acl("ca_abc", allow_all_users=True)
742
743 def test_update_acl_requires_client(self):
744 - from composio.core.models.custom_tool import ExperimentalAPI
744 + from composio.core.models.experimental import ExperimentalAPI
745
746 with pytest.raises(exceptions.ValidationError):
747 ExperimentalAPI().update_acl("ca_abc", allow_all_users=True)
python/tests/test_custom_tools.py
+2 -3
@@ -26,22 +26,21 @@ from composio_client.types.tool_router.session_proxy_execute_response import (
26 from pydantic import BaseModel, Field
27
28 from composio.core.models.custom_tool import (
29 - ExperimentalAPI,
29 ExperimentalToolkit,
30 build_custom_tools_map,
31 build_custom_tools_map_from_response,
33 - serialize_custom_tools,
32 serialize_custom_toolkits,
33 + serialize_custom_tools,
34 )
35 from composio.core.models.custom_tool_execution import (
36 execute_custom_tool,
37 find_custom_tool,
38 )
39 +from composio.core.models.experimental import ExperimentalAPI
40 from composio.core.models.session_context import SessionContextImpl
41 from composio.core.models.tool_router_session import ToolRouterSession
42 from composio.exceptions import ValidationError
43
44 -
44 # ────────────────────────────────────────────────────────────────
45 # Fixtures
46 # ────────────────────────────────────────────────────────────────
python/tests/test_tool_router.py
+1 -1
@@ -6,7 +6,7 @@ import pytest
6 from composio_client import omit
7 from pydantic import BaseModel, Field
8
9 -from composio.core.models.custom_tool import ExperimentalAPI
9 +from composio.core.models.experimental import ExperimentalAPI
10 from composio.core.models.tool_router import (
11 SESSION_PRESET_DIRECT_TOOLS,
12 ToolkitConnectionsDetails,