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 722 lines 20.5 KB
Raw
1 from __future__ import annotations
2
3 import functools
4 import typing as t
5
6 import typing_extensions as te
7
8 if t.TYPE_CHECKING:
9 from .tools import Tool, ToolExecutionResponse, tool_execute_params
10
11
12 # TODO: Maybe use `te.Unpack` in tools.execute?
13 class ToolExecuteParams(te.TypedDict):
14 arguments: t.Dict[str, t.Optional[t.Any]]
15 connected_account_id: te.NotRequired[str]
16 custom_auth_params: te.NotRequired["tool_execute_params.CustomAuthParams"]
17 custom_connection_data: te.NotRequired["tool_execute_params.CustomConnectionData"]
18 text: te.NotRequired[str]
19 user_id: te.NotRequired[str]
20 version: te.NotRequired[str]
21 dangerously_skip_version_check: te.NotRequired[t.Optional[bool]]
22
23
24 ModifierInOut = t.Union["ToolExecuteParams", "ToolExecutionResponse", "Tool"]
25
26
27 class BeforeExecute(t.Protocol):
28 """
29 A modifier that is called before the tool is executed.
30 """
31
32 def __call__(
33 self,
34 tool: str,
35 toolkit: str,
36 params: ToolExecuteParams,
37 ) -> ToolExecuteParams: ...
38
39
40 class AfterExecute(t.Protocol):
41 """
42 A modifier that is called after the tool is executed.
43 """
44
45 def __call__(
46 self,
47 tool: str,
48 toolkit: str,
49 response: ToolExecutionResponse,
50 ) -> ToolExecutionResponse: ...
51
52
53 class SchemaModifier(t.Protocol):
54 """
55 A modifier that is called to modify the schema of the tool.
56 """
57
58 def __call__(
59 self,
60 tool: str,
61 toolkit: str,
62 schema: "Tool",
63 ) -> "Tool": ...
64
65
66 class BeforeFileUploadCallable(t.Protocol):
67 """Legacy positional form of the ``before_file_upload`` hook.
68
69 ``(path, tool, toolkit) -> str | bool``. Still supported for back-compat,
70 but new code should use :class:`BeforeFileUploadContextCallable` so it can
71 discriminate local paths from URLs via ``context["source"]``.
72 """
73
74 def __call__(
75 self,
76 path: str,
77 tool: str,
78 toolkit: str,
79 ) -> t.Union[str, bool]: ...
80
81
82 class BeforeFileUploadContext(te.TypedDict):
83 """Context passed to the new-form ``before_file_upload`` hook.
84
85 - ``path``: the local filesystem path for ``source="path"``, or the URL
86 string for ``source="url"``.
87 - ``source``: discriminator — ``"path"`` for local paths, ``"url"`` for
88 ``http(s)://...`` inputs. Mirrors the TypeScript SDK's ``source`` field
89 (TS additionally emits ``"file"`` for ``File`` objects; Python has no
90 equivalent runtime type).
91 - ``tool`` / ``toolkit``: slugs of the tool being executed.
92 """
93
94 path: str
95 source: te.Literal["path", "url"]
96 tool: str
97 toolkit: str
98
99
100 class BeforeFileUploadContextCallable(t.Protocol):
101 """Preferred form of the ``before_file_upload`` hook.
102
103 Takes a single :class:`BeforeFileUploadContext` argument and returns either
104 a new path/URL string, or ``False`` to abort the upload.
105 """
106
107 def __call__(
108 self,
109 context: BeforeFileUploadContext,
110 ) -> t.Union[str, bool]: ...
111
112
113 BeforeFileUploadLike = t.Union[
114 BeforeFileUploadCallable,
115 BeforeFileUploadContextCallable,
116 ]
117 """Either form of ``before_file_upload``. Adapted internally."""
118
119
120 def _count_positional_params(fn: t.Callable) -> int:
121 """Return the number of positional (or positional-or-keyword) params, or
122 -1 if the signature can't be introspected (e.g. builtins)."""
123 import inspect
124
125 try:
126 sig = inspect.signature(fn)
127 except (TypeError, ValueError):
128 return -1
129 return sum(
130 1
131 for p in sig.parameters.values()
132 if p.kind
133 in (
134 inspect.Parameter.POSITIONAL_ONLY,
135 inspect.Parameter.POSITIONAL_OR_KEYWORD,
136 )
137 )
138
139
140 def _adapt_before_file_upload(
141 hook: BeforeFileUploadLike,
142 ) -> BeforeFileUploadContextCallable:
143 """Normalise a user-supplied hook to the context-object form.
144
145 A hook declared with exactly 3 positional parameters is treated as the
146 legacy ``(path, tool, toolkit)`` form; anything else (typically a single
147 positional ``context`` parameter) is treated as the new form.
148 """
149 if _count_positional_params(hook) == 3:
150 legacy = t.cast(BeforeFileUploadCallable, hook)
151
152 def wrap(context: BeforeFileUploadContext) -> t.Union[str, bool]:
153 return legacy(context["path"], context["tool"], context["toolkit"])
154
155 return wrap
156 return t.cast(BeforeFileUploadContextCallable, hook)
157
158
159 ModifierSlug: t.TypeAlias = str
160 AfterExecuteModifierL: t.TypeAlias = t.Literal["after_execute"]
161 BeforeExecuteModifierL: t.TypeAlias = t.Literal["before_execute"]
162 SchemaModifierL: t.TypeAlias = t.Literal["schema"]
163 BeforeFileUploadModifierL: t.TypeAlias = t.Literal["before_file_upload"]
164
165
166 class Modifier:
167 def __init__(
168 self,
169 modifier: t.Optional[
170 AfterExecute
171 | BeforeExecute
172 | SchemaModifier
173 | BeforeExecuteMeta
174 | AfterExecuteMeta
175 | BeforeFileUploadCallable
176 | BeforeFileUploadContextCallable
177 ],
178 type_: (
179 AfterExecuteModifierL
180 | BeforeExecuteModifierL
181 | SchemaModifierL
182 | AfterExecuteMetaModifierL
183 | BeforeExecuteMetaModifierL
184 | BeforeFileUploadModifierL
185 ),
186 tools: t.List[str],
187 toolkits: t.List[str],
188 ) -> None:
189 self.modifier = modifier
190 self.tools = tools
191 self.type = type_
192 self.toolkits = toolkits
193
194 def apply(
195 self,
196 toolkit: str,
197 tool: str,
198 data: ModifierInOut,
199 modifer_type: str,
200 ) -> ModifierInOut:
201 if self.modifier is None:
202 raise ValueError("Modifier is not provided")
203
204 # If no tools or toolkits are provided, apply the modifier to all tools
205 if (
206 self.type == modifer_type
207 and len(self.tools) == 0
208 and len(self.toolkits) == 0
209 ):
210 return self.modifier(tool, toolkit, data) # type: ignore
211
212 # If the modifier is not the same type, or the slug is not in the tools or
213 # toolkits, return the data as is
214 if (
215 self.type != modifer_type
216 or tool not in self.tools
217 and toolkit not in self.toolkits
218 ):
219 return data
220
221 # Apply the modifier to the data
222 return self.modifier(tool, toolkit, data) # type: ignore
223
224
225 @t.overload
226 def after_execute(
227 modifier: t.Optional[AfterExecute],
228 ) -> Modifier: ...
229
230
231 @t.overload
232 def after_execute(
233 *,
234 tools: t.Optional[t.List[str]] = None,
235 toolkits: t.Optional[t.List[str]] = None,
236 ) -> t.Callable[[AfterExecute], Modifier]: ...
237
238
239 def after_execute(
240 modifier: t.Optional[AfterExecute] = None,
241 *,
242 tools: t.Optional[t.List[str]] = None,
243 toolkits: t.Optional[t.List[str]] = None,
244 ) -> Modifier | t.Callable[[AfterExecute], Modifier]:
245 """Build an execution-result modifier.
246
247 Your callback receives ``(tool, toolkit, response)`` and returns a
248 ``ToolExecutionResponse`` dictionary. Check ``response["successful"]``,
249 not the session model's ``result_type`` attribute. Session adapters
250 retain ``log_id`` and ``result_type`` as dictionary keys. Serialize
251 with ``json.dumps(response)`` if needed; it is not a provider message.
252 Register this on tool execution or ``session.tools(modifiers=[...])``.
253 Calling ``session.execute`` directly does not invoke it.
254 """
255 if modifier is not None:
256 return Modifier(
257 modifier=modifier,
258 type_="after_execute",
259 tools=tools or [],
260 toolkits=toolkits or [],
261 )
262
263 if tools is not None or toolkits is not None:
264 return t.cast(
265 t.Callable[[AfterExecute], Modifier],
266 functools.partial(
267 after_execute,
268 tools=tools or [],
269 toolkits=toolkits or [],
270 ),
271 )
272
273 raise ValueError("Either tools or toolkits must be provided")
274
275
276 @t.overload
277 def before_execute(modifier: t.Optional[BeforeExecute]) -> Modifier: ...
278
279
280 @t.overload
281 def before_execute(
282 *,
283 tools: t.Optional[t.List[str]] = None,
284 toolkits: t.Optional[t.List[str]] = None,
285 ) -> t.Callable[[BeforeExecute], Modifier]: ...
286
287
288 def before_execute(
289 modifier: t.Optional[BeforeExecute] = None,
290 *,
291 tools: t.Optional[t.List[str]] = None,
292 toolkits: t.Optional[t.List[str]] = None,
293 ) -> Modifier | t.Callable[[BeforeExecute], Modifier]:
294 if modifier is not None:
295 return Modifier(
296 modifier=modifier,
297 type_="before_execute",
298 tools=tools or [],
299 toolkits=toolkits or [],
300 )
301
302 if tools is not None or toolkits is not None:
303 return t.cast(
304 t.Callable[[BeforeExecute], Modifier],
305 functools.partial(
306 before_execute,
307 tools=tools or [],
308 toolkits=toolkits or [],
309 ),
310 )
311
312 raise ValueError("Either tools or toolkits must be provided")
313
314
315 @t.overload
316 def before_file_upload(modifier: t.Optional[BeforeFileUploadLike]) -> Modifier: ...
317
318
319 @t.overload
320 def before_file_upload(
321 *,
322 tools: t.Optional[t.List[str]] = None,
323 toolkits: t.Optional[t.List[str]] = None,
324 ) -> t.Callable[[BeforeFileUploadLike], Modifier]: ...
325
326
327 def before_file_upload(
328 modifier: t.Optional[BeforeFileUploadLike] = None,
329 *,
330 tools: t.Optional[t.List[str]] = None,
331 toolkits: t.Optional[t.List[str]] = None,
332 ) -> Modifier | t.Callable[[BeforeFileUploadLike], Modifier]:
333 """
334 Build a ``Modifier`` for the file-upload hook (same scoping pattern as
335 :func:`before_execute`).
336
337 Your callable may take **either**:
338
339 - a single ``context`` argument (:class:`BeforeFileUploadContext`) — the
340 preferred form, exposes ``context["source"]`` (``"path"`` or ``"url"``),
341 or
342 - three positional arguments ``(path, tool, toolkit)`` — legacy form, kept
343 for back-compat.
344
345 Return a new path/URL string to substitute, or ``False`` to abort the
346 upload (raises :class:`~composio.exceptions.FileUploadAbortedError`).
347
348 Pass the returned ``Modifier`` in ``modifiers=[...]`` on
349 :meth:`composio.core.models.tools.Tools.execute` or ``tools.get``. Multiple
350 such modifiers are composed in list order.
351 """
352 if modifier is not None:
353 return Modifier(
354 modifier=modifier,
355 type_="before_file_upload",
356 tools=tools or [],
357 toolkits=toolkits or [],
358 )
359
360 if tools is not None or toolkits is not None:
361 return t.cast(
362 t.Callable[[BeforeFileUploadLike], Modifier],
363 functools.partial(
364 before_file_upload,
365 tools=tools or [],
366 toolkits=toolkits or [],
367 ),
368 )
369
370 raise ValueError("Either tools or toolkits must be provided")
371
372
373 @t.overload
374 def schema_modifier(modifier: t.Optional[SchemaModifier]) -> Modifier: ...
375
376
377 @t.overload
378 def schema_modifier(
379 *,
380 tools: t.Optional[t.List[str]] = None,
381 toolkits: t.Optional[t.List[str]] = None,
382 ) -> t.Callable[[SchemaModifier], Modifier]: ...
383
384
385 def schema_modifier(
386 modifier: t.Optional[SchemaModifier] = None,
387 *,
388 tools: t.Optional[t.List[str]] = None,
389 toolkits: t.Optional[t.List[str]] = None,
390 ) -> Modifier | t.Callable[[SchemaModifier], Modifier]:
391 if modifier is not None:
392 return Modifier(
393 modifier=modifier,
394 type_="schema",
395 tools=tools or [],
396 toolkits=toolkits or [],
397 )
398
399 if tools is not None or toolkits is not None:
400 return t.cast(
401 t.Callable[[SchemaModifier], Modifier],
402 functools.partial(
403 schema_modifier,
404 tools=tools or [],
405 toolkits=toolkits or [],
406 ),
407 )
408
409 raise ValueError("Either tools or toolkits must be provided")
410
411
412 @t.overload
413 def before_execute_meta(modifier: t.Optional[BeforeExecuteMeta]) -> Modifier: ...
414
415
416 @t.overload
417 def before_execute_meta(
418 *,
419 tools: t.Optional[t.List[str]] = None,
420 toolkits: t.Optional[t.List[str]] = None,
421 ) -> t.Callable[[BeforeExecuteMeta], Modifier]: ...
422
423
424 def before_execute_meta(
425 modifier: t.Optional[BeforeExecuteMeta] = None,
426 *,
427 tools: t.Optional[t.List[str]] = None,
428 toolkits: t.Optional[t.List[str]] = None,
429 ) -> Modifier | t.Callable[[BeforeExecuteMeta], Modifier]:
430 if modifier is not None:
431 return Modifier(
432 modifier=modifier,
433 type_="before_execute_meta",
434 tools=tools or [],
435 toolkits=toolkits or [],
436 )
437
438 if tools is not None or toolkits is not None:
439 return t.cast(
440 t.Callable[[BeforeExecuteMeta], Modifier],
441 functools.partial(
442 before_execute_meta,
443 tools=tools or [],
444 toolkits=toolkits or [],
445 ),
446 )
447
448 raise ValueError("Either tools or toolkits must be provided")
449
450
451 @t.overload
452 def after_execute_meta(modifier: t.Optional[AfterExecuteMeta]) -> Modifier: ...
453
454
455 @t.overload
456 def after_execute_meta(
457 *,
458 tools: t.Optional[t.List[str]] = None,
459 toolkits: t.Optional[t.List[str]] = None,
460 ) -> t.Callable[[AfterExecuteMeta], Modifier]: ...
461
462
463 def after_execute_meta(
464 modifier: t.Optional[AfterExecuteMeta] = None,
465 *,
466 tools: t.Optional[t.List[str]] = None,
467 toolkits: t.Optional[t.List[str]] = None,
468 ) -> Modifier | t.Callable[[AfterExecuteMeta], Modifier]:
469 if modifier is not None:
470 return Modifier(
471 modifier=modifier,
472 type_="after_execute_meta",
473 tools=tools or [],
474 toolkits=toolkits or [],
475 )
476
477 if tools is not None or toolkits is not None:
478 return t.cast(
479 t.Callable[[AfterExecuteMeta], Modifier],
480 functools.partial(
481 after_execute_meta,
482 tools=tools or [],
483 toolkits=toolkits or [],
484 ),
485 )
486
487 raise ValueError("Either tools or toolkits must be provided")
488
489
490 Modifiers = t.List[Modifier]
491
492
493 def merge_before_file_upload(
494 modifiers: t.Optional[Modifiers],
495 tool: str,
496 toolkit: str,
497 ) -> t.Optional[BeforeFileUploadContextCallable]:
498 """Compose ``before_file_upload``-type :class:`Modifier`\\ s for this *tool* / *toolkit*.
499
500 Scoping matches :class:`Modifier` (empty ``tools`` and ``toolkits`` = all tools).
501
502 Each user-supplied hook is adapted to the context form by
503 :func:`_adapt_before_file_upload`, so legacy 3-arg callables keep working
504 while new-form callables receive the full :class:`BeforeFileUploadContext`
505 (including ``source``).
506 """
507 to_chain = [
508 m
509 for m in (modifiers or [])
510 if m.type == "before_file_upload" and m.modifier is not None
511 ]
512 if not to_chain:
513 return None
514
515 def _applies(m: Modifier) -> bool:
516 if len(m.tools) == 0 and len(m.toolkits) == 0:
517 return True
518 return tool in m.tools or toolkit in m.toolkits
519
520 adapted_chain = [
521 (m, _adapt_before_file_upload(t.cast(BeforeFileUploadLike, m.modifier)))
522 for m in to_chain
523 ]
524
525 def combined(context: BeforeFileUploadContext) -> t.Union[str, bool]:
526 p: str = context["path"]
527 for m, hook in adapted_chain:
528 if not _applies(m):
529 continue
530 # Preserve source/tool/toolkit while forwarding the (possibly
531 # rewritten) path to the next hook.
532 next_ctx: BeforeFileUploadContext = {
533 "path": p,
534 "source": context["source"],
535 "tool": context["tool"],
536 "toolkit": context["toolkit"],
537 }
538 out = hook(next_ctx)
539 if out is False:
540 return False
541 if isinstance(out, str):
542 p = out
543 return p
544
545 return combined
546
547
548 @t.overload
549 def apply_modifier_by_type(
550 modifiers: Modifiers,
551 toolkit: str,
552 tool: str,
553 *,
554 type: BeforeExecuteModifierL,
555 request: ToolExecuteParams,
556 ) -> ToolExecuteParams: ...
557
558
559 @t.overload
560 def apply_modifier_by_type(
561 modifiers: Modifiers,
562 toolkit: str,
563 tool: str,
564 *,
565 type: AfterExecuteModifierL,
566 response: "ToolExecutionResponse",
567 ) -> "ToolExecutionResponse": ...
568
569
570 @t.overload
571 def apply_modifier_by_type(
572 modifiers: Modifiers,
573 toolkit: str,
574 tool: str,
575 *,
576 type: t.Literal["schema"],
577 schema: "Tool",
578 ) -> "Tool": ...
579
580
581 @t.overload
582 def apply_modifier_by_type(
583 modifiers: Modifiers,
584 toolkit: str,
585 tool: str,
586 *,
587 type: BeforeExecuteMetaModifierL,
588 session_id: str,
589 params: t.Dict[str, t.Any],
590 ) -> t.Dict[str, t.Any]: ...
591
592
593 @t.overload
594 def apply_modifier_by_type(
595 modifiers: Modifiers,
596 toolkit: str,
597 tool: str,
598 *,
599 type: AfterExecuteMetaModifierL,
600 session_id: str,
601 response: "ToolExecutionResponse",
602 ) -> "ToolExecutionResponse": ...
603
604
605 def apply_modifier_by_type(
606 modifiers: Modifiers,
607 toolkit: str,
608 tool: str,
609 *,
610 type: t.Literal[
611 "before_execute",
612 "after_execute",
613 "schema",
614 "before_execute_meta",
615 "after_execute_meta",
616 ],
617 schema: t.Optional["Tool"] = None,
618 request: t.Optional["ToolExecuteParams"] = None,
619 response: t.Optional["ToolExecutionResponse"] = None,
620 session_id: t.Optional[str] = None,
621 params: t.Optional[t.Dict[str, t.Any]] = None,
622 ) -> t.Union[ModifierInOut, t.Dict[str, t.Any]]:
623 """Apply a modifier to a tool."""
624 # For meta modifiers, we handle them differently
625 if type in ("before_execute_meta", "after_execute_meta"):
626 if session_id is None:
627 raise ValueError("session_id is required for meta modifiers")
628
629 if type == "before_execute_meta":
630 if params is None:
631 raise ValueError("params is required for before_execute_meta")
632 result_params: t.Dict[str, t.Any] = params
633 for modifier in modifiers:
634 if modifier.type == type:
635 # Check if modifier should be applied
636 should_apply = (
637 (len(modifier.tools) == 0 and len(modifier.toolkits) == 0)
638 or tool in modifier.tools
639 or toolkit in modifier.toolkits
640 )
641
642 if should_apply and modifier.modifier is not None:
643 result_params = t.cast(BeforeExecuteMeta, modifier.modifier)(
644 tool, toolkit, session_id, result_params
645 )
646 return result_params
647 else: # after_execute_meta
648 if response is None:
649 raise ValueError("response is required for after_execute_meta")
650 result_response: "ToolExecutionResponse" = response
651 for modifier in modifiers:
652 if modifier.type == type:
653 # Check if modifier should be applied
654 should_apply = (
655 (len(modifier.tools) == 0 and len(modifier.toolkits) == 0)
656 or tool in modifier.tools
657 or toolkit in modifier.toolkits
658 )
659
660 if should_apply and modifier.modifier is not None:
661 result_response = t.cast(AfterExecuteMeta, modifier.modifier)(
662 tool, toolkit, session_id, result_response
663 )
664 return result_response
665
666 # For regular modifiers
667 result: ModifierInOut
668 if schema is not None:
669 result = schema
670 elif request is not None:
671 result = request
672 elif response is not None:
673 result = response
674 else:
675 raise ValueError("No data provided")
676
677 for modifier in modifiers:
678 result = modifier.apply(
679 toolkit=toolkit,
680 tool=tool,
681 data=result,
682 modifer_type=type,
683 )
684 return result
685
686
687 class BeforeExecuteMeta(t.Protocol):
688 """
689 A modifier that is called before the meta tool is executed in a session context.
690 """
691
692 def __call__(
693 self,
694 tool: str,
695 toolkit: str,
696 session_id: str,
697 params: t.Dict[str, t.Any],
698 ) -> t.Dict[str, t.Any]: ...
699
700
701 class AfterExecuteMeta(t.Protocol):
702 """
703 A modifier that is called after the meta tool is executed in a session context.
704 """
705
706 def __call__(
707 self,
708 tool: str,
709 toolkit: str,
710 session_id: str,
711 response: ToolExecutionResponse,
712 ) -> ToolExecutionResponse: ...
713
714
715 AfterExecuteMetaModifierL: t.TypeAlias = t.Literal["after_execute_meta"]
716 BeforeExecuteMetaModifierL: t.TypeAlias = t.Literal["before_execute_meta"]
717
718
719 class ToolOptions(te.TypedDict):
720 modify_schema: te.NotRequired[
721 t.Dict[ModifierSlug, AfterExecute | BeforeExecute | SchemaModifier]
722 ]