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 600 lines 21.8 KB
Raw
1 """
2 This module is a light wrapper around the auto-generated composio client.
3 """
4
5 import contextvars
6 import logging
7 import os
8 import platform
9 import re
10 import typing as t
11 import weakref
12 from importlib.metadata import PackageNotFoundError, version
13 from uuid import uuid4
14
15 import typing_extensions as te
16 from composio_client import (
17 DEFAULT_MAX_RETRIES,
18 NOT_GIVEN,
19 APIError,
20 APIStatusError,
21 Auth,
22 ClientIdentity,
23 NotGiven,
24 Scope,
25 )
26 from composio_client import Composio as BaseComposio
27 from httpx import URL, Client, Response, Timeout
28
29 from composio.exceptions import ComposioError, sanitize_error_text
30 from composio.utils.logging import LogLevel, WithLogger, _VerbosityWrapper
31 from composio.utils.toolkit_deprecation import (
32 install_hook as _install_toolkit_deprecation_hook,
33 )
34
35
36 def _distribution_version(name: str) -> str:
37 try:
38 return version(name)
39 except PackageNotFoundError:
40 return "unknown"
41
42
43 _SDK_VERSION = _distribution_version("composio")
44
45 #: What the client accepts as an identity value: printable ASCII with no
46 #: leading or trailing whitespace.
47 _HEADER_SAFE = re.compile(r"[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?")
48
49
50 def _client_identity(provider: str) -> ClientIdentity:
51 """
52 The SDK as the generated client reports it.
53
54 The client sends the product headers from it, adds its own library
55 headers, and reports the Python runtime and version itself. A provider
56 name that cannot be sent as a header value is reported as ``unknown``
57 rather than making the client fail to construct.
58 """
59 return ClientIdentity(
60 product="composio",
61 version=_SDK_VERSION,
62 source="PYTHON_SDK",
63 framework=provider if _HEADER_SAFE.fullmatch(provider) else "unknown",
64 runtime=HttpClient._runtime_env,
65 )
66
67
68 ComposioAPIError = APIError
69 APIEnvironment = te.Literal["production", "staging", "local"]
70
71
72 _SDK_ERROR_CLASSES: t.Dict[t.Type[APIStatusError], t.Type[APIStatusError]] = {}
73
74 _STATUS_FALLBACK_FIXES: t.Dict[int, t.List[str]] = {
75 401: ["Ensure you are using a valid Composio API key for this project"],
76 402: ["Check the plan and billing limits of your Composio organization"],
77 403: ["Ensure your API key and the connected account are allowed to run this tool"],
78 410: [
79 "The tool or the resource it acts on is no longer available; see the error message"
80 ],
81 429: [
82 "Wait before retrying",
83 "Reduce how many requests your organization sends per minute",
84 ],
85 }
86 _CODE_FALLBACK_FIXES: t.Dict[int, t.List[str]] = {
87 1803: [
88 "Ensure the connected account exists and is active in your Composio dashboard"
89 ],
90 }
91 _SERVER_ERROR_FIXES = [
92 "The Composio API failed to process the request; retry later",
93 "If it keeps failing, contact Composio support with the request id",
94 ]
95 _DEFAULT_FIXES = [
96 "Ensure the tool slug is correct and the input arguments for the tool is valid",
97 ]
98
99
100 def _fallback_fixes(status_code: int) -> t.List[str]:
101 """What to try when the API rejected the request without a ``suggested_fix``."""
102 if status_code in _STATUS_FALLBACK_FIXES:
103 return list(_STATUS_FALLBACK_FIXES[status_code])
104 if status_code >= 500:
105 return list(_SERVER_ERROR_FIXES)
106 return list(_DEFAULT_FIXES)
107
108
109 def _api_error_code(error: APIStatusError) -> t.Optional[int]:
110 details = error.details
111 return details.get("code") if details is not None else None
112
113
114 def _suggested_fix(error: APIStatusError) -> t.Optional[str]:
115 details = error.details
116 raw = details.get("suggested_fix") if details is not None else None
117 return sanitize_error_text(raw) or None if raw else None
118
119
120 def _possible_fixes(error: APIStatusError) -> t.List[str]:
121 fix = _suggested_fix(error)
122 if fix:
123 return [fix]
124 details = error.details
125 code = details.get("code") if details is not None else None
126 if code in _CODE_FALLBACK_FIXES:
127 return list(_CODE_FALLBACK_FIXES[code])
128 return _fallback_fixes(error.status_code)
129
130
131 def _with_sdk_error_base(
132 error_class: t.Type[APIStatusError],
133 ) -> t.Type[APIStatusError]:
134 """
135 Return a subclass of a generated-client status error that also derives
136 from the SDK's ``ComposioError``.
137
138 The generated client has its own exception root, unrelated to
139 ``composio.exceptions.ComposioError``, so HTTP failures such as an invalid
140 API key used to escape ``except ComposioError``. Keeping the generated
141 class as the first base preserves its constructor, ``status_code`` and
142 ``isinstance`` checks, so existing ``except APIStatusError`` handlers keep
143 working unchanged.
144 """
145 cached = _SDK_ERROR_CLASSES.get(error_class)
146 if cached is not None:
147 return cached
148 sdk_class = t.cast(
149 t.Type[APIStatusError],
150 type(
151 error_class.__name__,
152 (error_class, ComposioError),
153 {
154 "__module__": error_class.__module__,
155 "__reduce__": _reduce_sdk_error,
156 "api_error_code": property(_api_error_code),
157 "suggested_fix": property(_suggested_fix),
158 "possible_fixes": property(_possible_fixes),
159 },
160 ),
161 )
162 # setdefault keeps the first class if two threads race to build one.
163 return _SDK_ERROR_CLASSES.setdefault(error_class, sdk_class)
164
165
166 def _reduce_sdk_error(self: APIStatusError) -> t.Tuple[t.Any, ...]:
167 """
168 Pickle support for the classes built by ``_with_sdk_error_base``.
169
170 They are not module attributes, so pickle cannot find them by name. Record
171 the generated class instead and rebuild the SDK subclass on load.
172 """
173 error_class = type(self).__mro__[1]
174 return (
175 _rebuild_sdk_error,
176 (error_class, self.message, self.response, self.body),
177 self.__dict__,
178 )
179
180
181 def _rebuild_sdk_error(
182 error_class: t.Type[APIStatusError],
183 message: str,
184 response: Response,
185 body: object,
186 ) -> APIStatusError:
187 return _with_sdk_error_base(error_class)(message, response=response, body=body)
188
189
190 def _as_sdk_error(error: APIStatusError) -> APIStatusError:
191 if isinstance(error, ComposioError):
192 return error
193 sdk_error = _with_sdk_error_base(type(error))(
194 sanitize_error_text(error.message), response=error.response, body=error.body
195 )
196 return sdk_error.with_traceback(error.__traceback__)
197
198
199 CLIENT_LOGGER_NAME = "composio_client"
200 """Name of the logger the generated ``composio_client`` package writes to."""
201
202
203 _active_log_wrapper: contextvars.ContextVar[t.Optional[_VerbosityWrapper]] = (
204 contextvars.ContextVar("composio_client_log_wrapper", default=None)
205 )
206 """The SDK logger of the :class:`HttpClient` currently performing a request.
207
208 The generated client writes every lifecycle record to one process-wide
209 ``composio_client`` logger, so the record itself does not say which SDK
210 instance made the request. :meth:`HttpClient.request` binds this variable
211 for the duration of each call so the forwarder can deliver the record to
212 that instance's logger instead of whichever instance was constructed last.
213 """
214
215
216 class _ClientLogForwarder(logging.Handler):
217 """Forward ``composio_client`` records into the SDK logger.
218
219 The generated client logs request/response lifecycle through
220 ``logging.getLogger("composio_client")``. Routing those records through
221 the SDK's :class:`_VerbosityWrapper` keeps one destination for SDK users
222 and applies the same credential redaction and line truncation the SDK's
223 own records get. The client's INFO records (per-request lifecycle) are
224 forwarded as DEBUG.
225
226 One forwarder is installed per process. A record emitted while an
227 :class:`HttpClient` request is in flight goes to that client's logger
228 (see :data:`_active_log_wrapper`); a record emitted outside any request
229 goes to the logger of the most recently constructed client.
230 """
231
232 def __init__(self, wrapper: _VerbosityWrapper) -> None:
233 super().__init__()
234 self.wrapper = wrapper
235
236 def emit(self, record: logging.LogRecord) -> None:
237 wrapper = _active_log_wrapper.get() or self.wrapper
238 try:
239 message = record.getMessage()
240 if record.levelno >= logging.ERROR:
241 wrapper.error(message, exc_info=record.exc_info)
242 elif record.levelno >= logging.WARNING:
243 wrapper.warning(message, exc_info=record.exc_info)
244 else:
245 wrapper.debug(message, exc_info=record.exc_info)
246 except Exception: # noqa: BLE001 - logging must never fail the call
247 self.handleError(record)
248
249
250 _forwarding_wrappers: "weakref.WeakSet[_VerbosityWrapper]" = weakref.WeakSet()
251 """The SDK loggers of the :class:`HttpClient` instances still alive.
252
253 The ``composio_client`` logger has one process-wide level, so it is kept at
254 the most permissive level any live instance needs; each instance's wrapper
255 then filters what it actually emits. Weak references let an instance that
256 was garbage collected stop holding the level down.
257 """
258
259
260 def _client_level_for(wrapper: _VerbosityWrapper) -> int:
261 """The ``composio_client`` level that lets ``wrapper`` see what it wants.
262
263 The client's INFO records are forwarded as DEBUG, so the client only
264 needs to produce them when the SDK logger is at DEBUG; otherwise only
265 its WARNING and above records are worth producing.
266 """
267 level = wrapper.logger.getEffectiveLevel()
268 return level if level <= logging.DEBUG else max(level, logging.WARNING)
269
270
271 def _install_client_log_forwarder(wrapper: _VerbosityWrapper) -> logging.Logger:
272 """Attach the process-wide forwarder to the client logger.
273
274 Idempotent: the single forwarder is created on first use and kept
275 afterwards. Each call rebinds its fallback logger to ``wrapper`` (the
276 most recently constructed SDK instance); records emitted during a
277 request are routed to the requesting instance regardless of that
278 fallback, so earlier instances keep receiving their own request logs.
279
280 The client logger's level is the most permissive one any live instance
281 needs, so constructing a quieter instance never silences the lifecycle
282 records of an earlier, more verbose one.
283 """
284 client_logger = logging.getLogger(CLIENT_LOGGER_NAME)
285 forwarder: t.Optional[_ClientLogForwarder] = None
286 for handler in list(client_logger.handlers):
287 if not isinstance(handler, _ClientLogForwarder):
288 continue
289 if forwarder is None:
290 forwarder = handler
291 continue
292 client_logger.removeHandler(handler)
293 if forwarder is None:
294 client_logger.addHandler(_ClientLogForwarder(wrapper))
295 else:
296 forwarder.wrapper = wrapper
297 _forwarding_wrappers.add(wrapper)
298 client_logger.setLevel(min(_client_level_for(w) for w in _forwarding_wrappers))
299 client_logger.propagate = False
300 return client_logger
301
302
303 def _get_python_implementation() -> str:
304 """
305 Get the Python implementation name.
306
307 Returns:
308 String identifier for Python implementation (CPYTHON, PYPY, JYTHON, IRONPYTHON, etc.)
309 """
310 impl = platform.python_implementation().upper()
311 return impl
312
313
314 def _detect_runtime_environment() -> str:
315 """
316 Detect the runtime environment where the code is executing.
317
318 Returns a string identifier for the environment.
319 """
320 # Check for Google Colab
321 try:
322 import google.colab # type: ignore # noqa: F401
323
324 return "GOOGLE_COLAB"
325 except ImportError:
326 pass
327
328 # Check for Jupyter/IPython
329 try:
330 shell = get_ipython().__class__.__name__ # type: ignore # noqa: F821
331 if shell == "ZMQInteractiveShell":
332 return "JUPYTER_NOTEBOOK"
333 elif shell == "TerminalInteractiveShell":
334 return "IPYTHON"
335 except NameError:
336 pass
337
338 # Check for AWS Lambda
339 if os.environ.get("AWS_LAMBDA_FUNCTION_NAME"):
340 return "AWS_LAMBDA"
341
342 # Check for Google Cloud Functions
343 if os.environ.get("FUNCTION_NAME") or os.environ.get("K_SERVICE"):
344 return "GOOGLE_CLOUD_FUNCTION"
345
346 # Check for Azure Functions
347 if os.environ.get("FUNCTIONS_WORKER_RUNTIME"):
348 return "AZURE_FUNCTION"
349
350 # Check for Kaggle
351 if os.environ.get("KAGGLE_KERNEL_RUN_TYPE"):
352 return "KAGGLE"
353
354 # Check for Replit
355 if os.environ.get("REPL_ID") or os.environ.get("REPLIT_DB_URL"):
356 return "REPLIT"
357
358 # Check for GitHub Actions
359 if os.environ.get("GITHUB_ACTIONS"):
360 return "GITHUB_ACTIONS"
361
362 # Check for GitLab CI
363 if os.environ.get("GITLAB_CI"):
364 return "GITLAB_CI"
365
366 # Check for CircleCI
367 if os.environ.get("CIRCLECI"):
368 return "CIRCLECI"
369
370 # Check for Jenkins
371 if os.environ.get("JENKINS_HOME"):
372 return "JENKINS"
373
374 # Check for Docker
375 if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
376 return "DOCKER"
377
378 # Check if running in a container (generic)
379 try:
380 with open("/proc/1/cgroup", "r") as f:
381 if "docker" in f.read() or "containerd" in f.read():
382 return "CONTAINER"
383 except (FileNotFoundError, PermissionError):
384 pass
385
386 # Default to LOCAL for development environments
387 return "LOCAL"
388
389
390 class RequestContext(te.TypedDict):
391 id: te.NotRequired[t.Optional[str]]
392 provider: str
393
394
395 # TODO: Rename `Composio` to `HttpClient` in stainless generator
396 class HttpClient(BaseComposio, WithLogger):
397 """
398 Wrapper around the auto-generated composio client.
399 """
400
401 request_ctx: contextvars.ContextVar[RequestContext]
402 not_given = NOT_GIVEN
403
404 # Detect once at class initialization
405 _runtime_env: str = (
406 f"{_detect_runtime_environment()}_{_get_python_implementation()}"
407 )
408
409 def __init__(
410 self,
411 *,
412 provider: str,
413 auth: Auth,
414 scope: t.Optional[Scope] = None,
415 environment: te.Union[NotGiven, APIEnvironment] = "production",
416 base_url: t.Optional[t.Union[str, URL, NotGiven]] = NOT_GIVEN,
417 timeout: t.Optional[t.Union[float, Timeout, NotGiven]] = NOT_GIVEN,
418 max_retries: int = DEFAULT_MAX_RETRIES,
419 default_headers: t.Optional[t.Mapping[str, t.Optional[str]]] = None,
420 identity: t.Optional[ClientIdentity] = None,
421 http_client: t.Optional[Client] = None,
422 logger: t.Optional[logging.Logger] = None,
423 logging_level: t.Optional[LogLevel] = None,
424 _strict_response_validation: bool = False,
425 ) -> None:
426 """
427 Initialize the client.
428
429 :param provider: The provider to use for the client.
430 :param auth: How the client authenticates (``ProjectAuth``, ``UserAuth``,
431 ``AutoAuth``, ...). The client reads no environment variable; the SDK
432 resolves the keys before constructing it.
433 :param scope: The organization and project requests are routed to, sent
434 as ``x-org-id`` / ``x-project-id``.
435 :param logger: Logger that receives SDK and ``composio_client`` records.
436 :param logging_level: Level applied to the SDK and ``composio_client`` loggers.
437 :param environment: The environment to use for the client.
438 :param base_url: The base URL to use for the client.
439 :param timeout: The timeout to use for the client.
440 :param max_retries: The maximum number of retries to use for the client.
441 :param default_headers: The default headers to use for the client. They
442 may not name a credential header while ``auth`` holds a credential, nor
443 a scope header while ``scope`` is set.
444 :param identity: How the client reports the SDK; derived from ``provider``
445 when omitted. Clones pass the parent's.
446 :param http_client: The HTTP client to use for the client.
447 """
448 WithLogger.__init__(self, logger=logger, logging_level=logging_level)
449 BaseComposio.__init__(
450 self,
451 auth=auth,
452 scope=scope,
453 environment=environment,
454 base_url=base_url,
455 timeout=timeout,
456 max_retries=max_retries,
457 default_headers=default_headers,
458 http_client=http_client,
459 identity=identity if identity is not None else _client_identity(provider),
460 _strict_response_validation=_strict_response_validation,
461 )
462 # The SDK's own reference to the credentials it authenticated with, for
463 # the places that hand a key to something other than this client (the
464 # session MCP config, the realtime channel auth). The client reads no
465 # key back, and `auth` is the generated `/auth` resource.
466 self.sdk_auth: Auth = auth
467 _install_client_log_forwarder(self._logger)
468 # Warns once per deprecated toolkit version reported through the
469 # `Composio-Deprecated-Toolkits` response header. The hook lives on the
470 # underlying httpx client, which `copy()` / `with_options()` (and so
471 # `without_retries`) reuse, so clones share it. Idempotent, and a
472 # user-supplied client keeps its own hooks.
473 _install_toolkit_deprecation_hook(self._client)
474 self.provider = provider
475 self.request_ctx = contextvars.ContextVar[RequestContext](
476 "request_ctx",
477 default={
478 "id": None,
479 "provider": provider,
480 },
481 )
482 # Lazily-built sibling client with retries disabled; see `without_retries`.
483 self._without_retries: t.Optional[te.Self] = None
484
485 def with_options( # type: ignore[override]
486 self,
487 *,
488 _extra_kwargs: t.Mapping[str, t.Any] = {},
489 **kwargs: t.Any,
490 ) -> te.Self:
491 """
492 Clone the client, re-injecting the SDK-only constructor keywords.
493
494 The generated ``with_options`` rebuilds the client via ``type(self)(...)``
495 with the parent's ``auth``, ``scope``, ``identity`` and options, but
496 cannot know ``provider``, which this subclass requires, or the SDK
497 logger. Threading them through ``_extra_kwargs`` makes
498 ``with_options`` work (e.g. ``with_options(max_retries=0)``).
499 """
500 return super().with_options( # type: ignore[misc]
501 _extra_kwargs={
502 "provider": self.provider,
503 # Share the parent's logger; otherwise constructing the clone
504 # rebinds the process-wide client log forwarder to the default
505 # `composio` logger.
506 "logger": self._logger.logger,
507 **_extra_kwargs,
508 },
509 **kwargs,
510 )
511
512 @property
513 def without_retries(self) -> te.Self:
514 """
515 A cached sibling client that never retries requests.
516
517 Used for tool executions and proxied API calls (``tools.execute``,
518 ``tools.proxy``, and the session ``execute`` / ``proxy_execute`` paths),
519 where a silent retry after a read timeout can duplicate a side effect
520 (e.g. send an email twice). Reads keep the default retry behaviour.
521
522 Scope: every execution path routes through this, because the backend
523 does not deduplicate executions. Other non-idempotent writes
524 (``auth_configs.create`` / ``update`` / ``delete``, ``mcp.update`` /
525 ``delete``, ``connected_accounts.delete`` / ``refresh``,
526 ``link.create``) keep the default retries — most are naturally
527 idempotent on retry, and the durable fix is backend-honoured
528 idempotency keys.
529
530 The sibling is cached rather than rebuilt per call so a fresh client is
531 not constructed on every execute/proxy (the hottest path); its options
532 never change, so one per client suffices.
533 """
534 if self._without_retries is None:
535 self._without_retries = self.with_options(max_retries=0)
536 return self._without_retries
537
538 def request( # type: ignore[override]
539 self,
540 cast_to: t.Any,
541 options: t.Mapping[str, t.Any],
542 *,
543 stream: bool = False,
544 stream_cls: t.Optional[t.Type[t.Any]] = None,
545 ) -> t.Any:
546 # Bind this instance's logger for the request so the client's
547 # lifecycle records reach it (see `_active_log_wrapper`).
548 token = _active_log_wrapper.set(self._logger)
549 try:
550 return super().request(
551 cast_to, options, stream=stream, stream_cls=stream_cls
552 )
553 finally:
554 _active_log_wrapper.reset(token)
555
556 def _make_status_error(
557 self,
558 err_msg: str,
559 *,
560 body: object,
561 response: Response,
562 ) -> APIStatusError:
563 """
564 Build status errors that are also ``ComposioError``s; see
565 ``_with_sdk_error_base``.
566
567 Every status error the client raises is built through this hook, so
568 overriding it here covers all response paths at once.
569 """
570 return _as_sdk_error(
571 super()._make_status_error(err_msg, body=body, response=response)
572 )
573
574 def _headers_for(self, url: str, **kwargs: t.Any) -> t.Dict[str, str]:
575 """
576 Add ``x-request-id`` to every dispatch to the API origin.
577
578 The client builds every other header itself (credential from ``auth``,
579 ``x-org-id`` / ``x-project-id`` from ``scope``, identity from
580 ``identity``) and generates no request id, so this is all the override
581 still does. The client calls it once per logical call (its retries
582 reuse those headers) and again for each redirect hop, so a fresh id is
583 minted per call and per same-origin hop unless the caller pinned one in
584 ``default_headers`` or the request context. The keywords are forwarded
585 untouched so the override does not depend on the client's private
586 signature.
587 """
588 headers = super()._headers_for(url, **kwargs)
589 target, base = URL(url), URL(self.base_url)
590 if (target.scheme, target.host, target.port) != (
591 base.scheme,
592 base.host,
593 base.port,
594 ):
595 return headers
596 ctx = self.request_ctx.get()
597 headers["x-request-id"] = (
598 ctx.get("id") or headers.get("x-request-id") or uuid4().hex
599 )
600 return headers