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