@devries-cameron20 / composio Mirror · read-only / commits / 116811bba
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 08:30 UTC

fix(py): report unresolved input annotations in `experimental.tool` (#5061)

This PR: - closes https://github.com/ComposioHQ/composio/issues/5022 - replaces `_resolve_function_annotations` (which swallowed every `get_type_hints` error) with `_resolve_input_annotation`, which resolves only the input parameter - raises a `ValidationError` naming the unresolved name and the fix (define the model before the tool, import it at runtime instead of under `TYPE_CHECKING`) instead of the misleading "must be annotated with a Pydantic BaseModel subclass" error - stops rejecting valid tools whose `ctx` or return annotation is only imported under `TYPE_CHECKING`; one unresolvable annotation used to hide a correct input model - reads signatures with `annotationlib.Format.FORWARDREF` on Python 3.14+, where a forward reference without `from __future__ import annotations` used to surface as a raw `NameError` from `inspect.signature` - adds regression tests for the model-defined-below, `TYPE_CHECKING` input, and `TYPE_CHECKING` ctx/return cases Before: ``` composio.exceptions.ValidationError: experimental.tool: first parameter of "search" must be annotated with a Pydantic BaseModel subclass. Got: 'SearchInput'. Expected: def search(input: MyInput, ctx): ... ``` After: ``` composio.exceptions.ValidationError: experimental.tool: could not resolve the annotation 'SearchInput' of the first parameter of "search" (NameError: name 'SearchInput' is not defined). Define SearchInput before the tool, and import it at runtime rather than under `if TYPE_CHECKING:`. ``` Verified with the issue's repro on Python 3.11, 3.12, and 3.14; `tests/test_custom_tools.py` passes on 3.11 and 3.14, and the full Python suite passes on 3.12.

Alberto Schiabel committed Oct 22, 2026 at 15:45 UTC 116811bba3dbb24b74ee8f5eeb7f76d7e45ebf98
2 files changed +186 -14
python/composio/core/models/custom_tool.py
+41 -14
@@ -42,6 +42,7 @@ from __future__ import annotations
42
43 import asyncio
44 import inspect
45 +import sys
46 import typing as t
47
48 from pydantic import BaseModel
@@ -289,21 +290,52 @@ def _get_caller_locals(depth: int = 2) -> t.Optional[t.Mapping[str, t.Any]]:
290 del frame
291
292
292 -def _resolve_function_annotations(
293 +def _signature(fn: t.Callable[..., t.Any]) -> inspect.Signature:
294 + """Read a signature without evaluating annotations that may not resolve yet."""
295 + if sys.version_info >= (3, 14):
296 + import annotationlib
297 +
298 + # Python 3.14 evaluates annotations lazily; the default VALUE format
299 + # raises NameError for names defined later or only under TYPE_CHECKING.
300 + return inspect.signature(fn, annotation_format=annotationlib.Format.FORWARDREF)
301 + return inspect.signature(fn)
302 +
303 +
304 +def _resolve_input_annotation(
305 fn: t.Callable[..., t.Any],
306 + param: inspect.Parameter,
307 *,
308 localns: t.Optional[t.Mapping[str, t.Any]] = None,
296 -) -> t.Dict[str, t.Any]:
297 - """Resolve annotations, including postponed string annotations when possible."""
309 +) -> t.Any:
310 + """Resolve the input parameter's annotation, including string annotations.
311 +
312 + Only this one annotation is resolved, so an unresolvable ``ctx`` or return
313 + annotation (for example one imported under ``TYPE_CHECKING``) does not fail.
314 + """
315 + annotation = param.annotation
316 + if isinstance(annotation, t.ForwardRef):
317 + annotation = annotation.__forward_arg__
318 + if not isinstance(annotation, str):
319 + return annotation
320 +
321 + def holder() -> None: ...
322 +
323 + holder.__annotations__ = {param.name: annotation}
324 try:
325 return t.get_type_hints(
300 - fn,
326 + holder,
327 globalns=getattr(fn, "__globals__", {}),
328 localns=dict(localns) if localns is not None else None,
329 include_extras=True,
304 - )
305 - except Exception:
306 - return {}
330 + )[param.name]
331 + except Exception as exc:
332 + missing = exc.name if isinstance(exc, NameError) and exc.name else annotation
333 + raise ValidationError(
334 + f"experimental.tool: could not resolve the annotation {annotation!r} of "
335 + f'the first parameter of "{fn.__name__}" '
336 + f"({type(exc).__name__}: {exc}). Define {missing} before the tool, and "
337 + f"import it at runtime rather than under `if TYPE_CHECKING:`."
338 + ) from exc
339
340
341 def _infer_tool_from_function(
@@ -348,12 +380,7 @@ def _infer_tool_from_function(
380 f"'def {fn.__name__}(input, ctx)' instead of 'async def'."
381 )
382
351 - sig = inspect.signature(fn)
352 - params = list(sig.parameters.values())
353 - resolved_annotations = _resolve_function_annotations(
354 - fn,
355 - localns=annotation_locals,
356 - )
383 + params = list(_signature(fn).parameters.values())
384
385 if not params:
386 raise ValidationError(
@@ -371,7 +398,7 @@ def _infer_tool_from_function(
398
399 # First param must be the input model
400 first = params[0]
374 - first_annotation = resolved_annotations.get(first.name, first.annotation)
401 + first_annotation = _resolve_input_annotation(fn, first, localns=annotation_locals)
402 if first_annotation is inspect.Parameter.empty or not (
403 isinstance(first_annotation, type) and issubclass(first_annotation, BaseModel)
404 ):
python/tests/test_custom_tools.py
+145
@@ -12,6 +12,7 @@ Covers:
12 - Multi-execute routing (all-local, all-remote, mixed, parallel)
13 """
14
15 +import sys
16 from dataclasses import replace
17 from unittest.mock import MagicMock
18
@@ -313,6 +314,150 @@ def future_tool(input: FutureInput, ctx):
314 local_tool, local_input = build_tool()
315 assert local_tool.input_params is local_input
316
317 + def test_input_model_defined_after_tool_names_unresolved_annotation(self):
318 + # https://github.com/ComposioHQ/composio/issues/5022
319 + with pytest.raises(
320 + ValidationError,
321 + match=(
322 + r"could not resolve the annotation 'LaterInput' .*"
323 + r"NameError: name 'LaterInput' is not defined.*"
324 + r"Define LaterInput before the tool"
325 + ),
326 + ):
327 + exec(
328 + """
329 +from __future__ import annotations
330 +
331 +from pydantic import BaseModel
332 +
333 +
334 +@exp.tool()
335 +def later_tool(input: LaterInput, ctx):
336 + '''Input model defined below the tool.'''
337 + return {}
338 +
339 +
340 +class LaterInput(BaseModel):
341 + query: str
342 +""",
343 + {"exp": exp},
344 + )
345 +
346 + def test_input_model_imported_under_type_checking_names_unresolved_annotation(
347 + self,
348 + ):
349 + with pytest.raises(
350 + ValidationError,
351 + match=r"could not resolve the annotation 'GrepInput' .*TYPE_CHECKING",
352 + ):
353 + exec(
354 + """
355 +from __future__ import annotations
356 +
357 +from typing import TYPE_CHECKING
358 +
359 +if TYPE_CHECKING:
360 + from tests.test_custom_tools import GrepInput
361 +
362 +
363 +@exp.tool()
364 +def type_checking_tool(input: GrepInput, ctx):
365 + '''Input model only imported for type checkers.'''
366 + return {}
367 +""",
368 + {"exp": exp},
369 + )
370 +
371 + def test_unresolvable_ctx_and_return_annotations_are_ignored(self):
372 + namespace = {"exp": exp}
373 + exec(
374 + """
375 +from __future__ import annotations
376 +
377 +from typing import TYPE_CHECKING
378 +
379 +from pydantic import BaseModel
380 +
381 +if TYPE_CHECKING:
382 + from composio.core.models.custom_tool import SessionContext
383 +
384 +
385 +class TypedInput(BaseModel):
386 + query: str
387 +
388 +
389 +@exp.tool()
390 +def typed_ctx_tool(input: TypedInput, ctx: SessionContext) -> ToolResult:
391 + '''ctx and return annotations exist only for type checkers.'''
392 + return {}
393 +""",
394 + namespace,
395 + )
396 +
397 + assert namespace["typed_ctx_tool"].input_params is namespace["TypedInput"]
398 +
399 + @pytest.mark.skipif(
400 + sys.version_info < (3, 14), reason="lazy annotations need Python 3.14"
401 + )
402 + def test_lazy_input_model_defined_after_tool_names_unresolved_annotation(self):
403 + # dont_inherit keeps this module's compiler flags out, so the
404 + # annotations stay lazy instead of becoming strings.
405 + code = compile(
406 + """
407 +from pydantic import BaseModel
408 +
409 +
410 +@exp.tool()
411 +def lazy_later_tool(input: LazyLaterInput, ctx):
412 + '''Input model defined below the tool.'''
413 + return {}
414 +
415 +
416 +class LazyLaterInput(BaseModel):
417 + query: str
418 +""",
419 + "<lazy_later_tool>",
420 + "exec",
421 + dont_inherit=True,
422 + )
423 + with pytest.raises(
424 + ValidationError,
425 + match=r"could not resolve the annotation 'LazyLaterInput' .*NameError",
426 + ):
427 + exec(code, {"exp": exp})
428 +
429 + @pytest.mark.skipif(
430 + sys.version_info < (3, 14), reason="lazy annotations need Python 3.14"
431 + )
432 + def test_lazy_unresolvable_ctx_and_return_annotations_are_ignored(self):
433 + code = compile(
434 + """
435 +from typing import TYPE_CHECKING
436 +
437 +from pydantic import BaseModel
438 +
439 +if TYPE_CHECKING:
440 + from composio.core.models.custom_tool import SessionContext
441 +
442 +
443 +class LazyInput(BaseModel):
444 + query: str
445 +
446 +
447 +@exp.tool()
448 +def lazy_ctx_tool(input: LazyInput, ctx: SessionContext) -> ToolResult:
449 + '''ctx and return annotations exist only for type checkers.'''
450 + return {}
451 +""",
452 + "<lazy_ctx_tool>",
453 + "exec",
454 + dont_inherit=True,
455 + )
456 + namespace = {"exp": exp}
457 + exec(code, namespace)
458 +
459 + assert namespace["lazy_ctx_tool"].input_params is namespace["LazyInput"]
460 +
461 def test_async_function_rejected(self):
462 with pytest.raises(ValidationError, match="async"):
463