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

next
py 303 lines 11 KB
Raw
1 from __future__ import annotations
2
3 import typing as t
4
5 import typing_extensions as te
6
7 from composio import exceptions
8 from composio.client import HttpClient
9 from composio.client.types import (
10 AuthSchemeL,
11 toolkit_list_params,
12 toolkit_list_response,
13 toolkit_recommend_scopes_params,
14 toolkit_recommend_scopes_response,
15 toolkit_retrieve_changelog_response,
16 toolkit_retrieve_response,
17 toolkit_retrieve_scopes_grant_context_params,
18 toolkit_retrieve_scopes_grant_context_response,
19 )
20 from composio.core.models.connected_accounts import ConnectedAccounts
21 from composio.utils.pydantic import none_to_omit
22
23 from .base import Resource
24
25 AuthFieldsT: t.TypeAlias = t.List[
26 toolkit_retrieve_response.AuthConfigDetailFieldsConnectedAccountInitiationRequired
27 | toolkit_retrieve_response.AuthConfigDetailFieldsConnectedAccountInitiationOptional
28 | toolkit_retrieve_response.AuthConfigDetailFieldsAuthConfigCreationRequired
29 | toolkit_retrieve_response.AuthConfigDetailFieldsAuthConfigCreationOptional
30 ]
31
32
33 class Toolkits(Resource):
34 """
35 Toolkits are a collectiono of tools that can be used to perform various tasks.
36 They're conceptualized as a set of tools. Ex: Github toolkit can perform
37 Github actions via its collection of tools. This is a replacement of the
38 `apps` concept in the earlier versions of the SDK.
39 """
40
41 connected_accounts: ConnectedAccounts
42
43 def __init__(self, client: HttpClient):
44 super().__init__(client)
45 self.connected_accounts = ConnectedAccounts(client)
46
47 def list(
48 self,
49 *,
50 category: t.Optional[str] = None,
51 cursor: t.Optional[str] = None,
52 limit: t.Optional[float] = None,
53 sort_by: t.Optional[t.Literal["usage", "alphabetically"]] = None,
54 managed_by: t.Optional[t.Literal["composio", "all", "project"]] = None,
55 ) -> toolkit_list_response.ToolkitListResponse:
56 """List all toolkits."""
57 return self._client.toolkits.list(
58 category=none_to_omit(category),
59 cursor=none_to_omit(cursor),
60 limit=none_to_omit(limit),
61 managed_by=none_to_omit(managed_by),
62 sort_by=none_to_omit(sort_by),
63 )
64
65 @t.overload
66 def get(self) -> t.List[toolkit_list_response.Item]:
67 """Get all toolkits."""
68
69 @t.overload
70 def get(self, slug: str) -> toolkit_retrieve_response.ToolkitRetrieveResponse:
71 """Get a toolkit by slug."""
72
73 @t.overload
74 def get(
75 self,
76 *,
77 query: toolkit_list_params.ToolkitListParams,
78 ) -> t.List[toolkit_list_response.Item]:
79 """Get a list of toolkits by query."""
80
81 def get(
82 self,
83 slug: t.Optional[str] = None,
84 *,
85 query: t.Optional[toolkit_list_params.ToolkitListParams] = None,
86 ) -> t.Union[
87 toolkit_retrieve_response.ToolkitRetrieveResponse,
88 t.List[toolkit_list_response.Item],
89 ]:
90 if slug is not None:
91 return self._client.toolkits.retrieve(slug=slug)
92 return self._client.toolkits.list(**(query or {})).items
93
94 def get_many(
95 self,
96 slugs: t.Sequence[str],
97 *,
98 category: t.Optional[str] = None,
99 managed_by: t.Optional[t.Literal["composio", "all", "project"]] = None,
100 sort_by: t.Optional[t.Literal["usage", "alphabetically"]] = None,
101 limit: t.Optional[float] = None,
102 cursor: t.Optional[str] = None,
103 ) -> t.List[t.Any]:
104 """
105 Fetch several toolkits by slug in one request.
106
107 :param slugs: The toolkit slugs to fetch.
108 :param category: Only return toolkits in this category.
109 :param managed_by: Filter by who manages the toolkit.
110 :param sort_by: Sort order of the returned toolkits.
111 :param limit: Maximum number of toolkits to return.
112 :param cursor: Pagination cursor from a previous response.
113 :return: The matching toolkits.
114
115 Example:
116 toolkits = composio.toolkits.get_many(["github", "slack"])
117 for toolkit in toolkits:
118 print(toolkit.slug, toolkit.name)
119 """
120 return self._client.toolkits.retrieve_multi(
121 toolkits=list(slugs),
122 category=none_to_omit(category),
123 managed_by=none_to_omit(managed_by),
124 sort_by=none_to_omit(sort_by),
125 limit=none_to_omit(limit),
126 cursor=none_to_omit(cursor),
127 ).items
128
129 def changelog(
130 self,
131 ) -> toolkit_retrieve_changelog_response.ToolkitRetrieveChangelogResponse:
132 """
133 Retrieve the toolkit changelog (the last 10 versions per toolkit).
134
135 :return: The changelog entries under ``.items``.
136
137 Example:
138 changelog = composio.toolkits.changelog()
139 for entry in changelog.items:
140 print(entry.slug, [v.version for v in entry.versions])
141 """
142 return self._client.toolkits.retrieve_changelog()
143
144 def recommend_scopes(
145 self,
146 toolkit_slug: str,
147 **params: te.Unpack[
148 toolkit_recommend_scopes_params.ToolkitRecommendScopesParams
149 ],
150 ) -> toolkit_recommend_scopes_response.ToolkitRecommendScopesResponse:
151 """
152 Recommend the OAuth scopes to request so a connection can run the
153 given tools. Experimental — the API marks this endpoint beta.
154
155 :param toolkit_slug: The toolkit to recommend scopes for.
156 :param tools: Tool slugs to cover; ``[]`` covers every tool in the toolkit.
157 :param auth_scheme: Auth scheme the connection will use (API default ``OAUTH2``).
158 :param toolkit_version: Toolkit version to compute from (API default: latest).
159 :param grant_context: Dimension to selected value, e.g.
160 ``{"account_type": "Google Workspace"}``. See :meth:`list_grant_contexts`.
161 :param include: Scopes the recommendation must include.
162 :param exclude: Scopes the recommendation must not include.
163 :param available_scopes: Scopes your OAuth app can request; the
164 recommendation never goes outside this list.
165 :return: The ``least_privilege`` and ``fewest`` scope sets plus the
166 ``conditional`` scopes, under ``.scopes``.
167
168 Example:
169 recommendation = composio.toolkits.recommend_scopes(
170 "gmail",
171 tools=["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
172 )
173 print(recommendation.scopes.least_privilege)
174 """
175 return self._client.toolkits.recommend_scopes(toolkit_slug, **params)
176
177 def list_grant_contexts(
178 self,
179 toolkit_slug: str,
180 **params: te.Unpack[
181 toolkit_retrieve_scopes_grant_context_params.ToolkitRetrieveScopesGrantContextParams
182 ],
183 ) -> toolkit_retrieve_scopes_grant_context_response.ToolkitRetrieveScopesGrantContextResponse:
184 """
185 List the grant-context dimensions a toolkit's scope recommendation
186 depends on, with their allowed values and the default the API
187 assumes. Experimental — the API marks this endpoint beta.
188
189 :param toolkit_slug: The toolkit to list grant contexts for.
190 :param auth_scheme: Auth scheme the connection will use (API default ``OAUTH2``).
191 :param toolkit_version: Toolkit version to read from (API default: latest).
192 :return: ``grant_context_dimensions`` and ``default_grant_context``.
193
194 Example:
195 contexts = composio.toolkits.list_grant_contexts("gmail")
196 for dimension in contexts.grant_context_dimensions:
197 print(dimension.dimension, dimension.values)
198 """
199 return self._client.toolkits.retrieve_scopes_grant_context(
200 toolkit_slug, **params
201 )
202
203 def list_categories(self):
204 """List all categories of toolkits."""
205 return self._client.toolkits.retrieve_categories().items
206
207 def _get_auth_config_id(self, toolkit: str) -> str:
208 """Get the auth config ID for a toolkit."""
209 auth_configs = self._client.auth_configs.list(toolkit_slug=toolkit)
210 if len(auth_configs.items) > 0:
211 (auth_config, *_) = sorted(
212 auth_configs.items,
213 key=lambda x: t.cast(str, x.created_at),
214 reverse=True,
215 )
216 return auth_config.id
217
218 return self._client.auth_configs.create(
219 toolkit={"slug": toolkit},
220 auth_config={
221 "type": "use_composio_managed_auth",
222 "tool_access_config": {
223 "tools_for_connected_account_creation": [],
224 },
225 },
226 ).auth_config.id
227
228 def authorize(self, *, user_id: str, toolkit: str):
229 """
230 Authorize a user to a toolkit
231
232 If auth config is not found, it will be created using composio managed auth.
233
234 :param user_id: The ID of the user to authorize.
235 :param toolkit: The slug of the toolkit to authorize.
236 :return: The connection request.
237 """
238 return self.connected_accounts.initiate(
239 user_id=user_id,
240 auth_config_id=self._get_auth_config_id(
241 toolkit=toolkit,
242 ),
243 )
244
245 def get_connected_account_initiation_fields(
246 self,
247 toolkit: str,
248 auth_scheme: AuthSchemeL,
249 required_only: bool = False,
250 ) -> AuthFieldsT:
251 """
252 Get the required property for a given toolkit and auth scheme.
253 """
254 details = self._client.toolkits.retrieve(slug=toolkit).auth_config_details or []
255 for auth_detail in details:
256 if auth_detail.mode != auth_scheme:
257 continue
258
259 if required_only:
260 return t.cast(
261 AuthFieldsT,
262 auth_detail.fields.connected_account_initiation.required,
263 )
264
265 return t.cast(
266 AuthFieldsT,
267 auth_detail.fields.connected_account_initiation.required
268 + auth_detail.fields.connected_account_initiation.optional,
269 )
270
271 raise exceptions.InvalidParams(
272 f"auth config details not found with {toolkit=} and {auth_scheme=}"
273 )
274
275 def get_auth_config_creation_fields(
276 self,
277 toolkit: str,
278 auth_scheme: AuthSchemeL,
279 required_only: bool = False,
280 ) -> AuthFieldsT:
281 """
282 Get the required property for a given toolkit and auth scheme.
283 """
284 info = self._client.toolkits.retrieve(slug=toolkit)
285 for auth_detail in info.auth_config_details or []:
286 if auth_detail.mode != auth_scheme:
287 continue
288
289 if required_only:
290 return t.cast(
291 AuthFieldsT,
292 auth_detail.fields.auth_config_creation.required,
293 )
294
295 return t.cast(
296 AuthFieldsT,
297 auth_detail.fields.auth_config_creation.required
298 + auth_detail.fields.auth_config_creation.optional,
299 )
300
301 raise exceptions.InvalidParams(
302 f"auth config details not found with {toolkit=} and {auth_scheme=}"
303 )