Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | ) |