AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
fix(backend): resolve forward-ref RPC return annotations before validating (#14708)
Bentlyf16aa9c1213b
diff --git a/autogpt_platform/backend/backend/data/human_review.py b/autogpt_platform/backend/backend/data/human_review.pyindex 281a77bcab..98cca0a5d0 100644--- a/autogpt_platform/backend/backend/data/human_review.py+++ b/autogpt_platform/backend/backend/data/human_review.py@@ -272,7 +272,7 @@ async def get_or_create_human_review(async def get_pending_review_by_node_exec_id(node_exec_id: str, user_id: str-) -> Optional["PendingHumanReviewModel"]:+) -> Optional[PendingHumanReviewModel]:"""Get a pending review by its node execution ID.@@ -390,7 +390,7 @@ async def _resolve_node_id(node_exec_id: str, get_node_execution) -> str:async def get_pending_reviews_for_user(user_id: str, page: int = 1, page_size: int = 25-) -> list["PendingHumanReviewModel"]:+) -> list[PendingHumanReviewModel]:"""Get all pending reviews for a user with pagination.diff --git a/autogpt_platform/backend/backend/util/service.py b/autogpt_platform/backend/backend/util/service.pyindex df6a3dddec..48b5fae896 100644--- a/autogpt_platform/backend/backend/util/service.py+++ b/autogpt_platform/backend/backend/util/service.py@@ -23,6 +23,7 @@ from typing import (Type,TypeVar,cast,+ get_type_hints,overload,)@@ -546,6 +547,61 @@ class AppServiceClient(ABC):ASC = TypeVar("ASC", bound=AppServiceClient)+def _build_return_adapter(+ func: Callable[..., Any], annotation: Any, method_name: str+) -> TypeAdapter | None:+ """Build the TypeAdapter that validates an RPC method's return value.++ A return annotation written as a forward reference — ``list["SomeModel"]`` —+ arrives here as ``list[ForwardRef("SomeModel")]``, and pydantic resolves that+ name against the namespace of whoever builds the adapter, which is this module+ rather than the one that declared the endpoint. Such an adapter is never fully+ defined, so validating with it raises ``PydanticUserError`` on *every* call.+ Re-resolving the hints against the declaring module fixes those.++ Returns ``None`` when no usable adapter can be built, so the call falls back to+ the raw payload (as a failed validation already does) with one warning at client+ build time instead of an exception on every request.+ """+ adapter = _usable_adapter(annotation)+ if adapter is not None:+ return adapter++ try:+ # include_extras keeps Annotated metadata — a constraint or discriminator+ # carried there is part of the validation contract.+ resolved = get_type_hints(inspect.unwrap(func), include_extras=True).get(+ "return", annotation+ )+ except Exception as e:+ logger.warning(+ f"RPC return annotation {annotation!r} of {method_name} could not be "+ f"resolved ({type(e).__name__}: {e}); returning results unvalidated"+ )+ return None++ adapter = _usable_adapter(resolved)+ if adapter is None:+ logger.warning(+ f"RPC return annotation {annotation!r} of {method_name} has no usable "+ "TypeAdapter; returning results unvalidated"+ )+ return adapter+++def _usable_adapter(annotation: Any) -> TypeAdapter | None:+ """A TypeAdapter for *annotation*, or None if it cannot be built or rebuilt.++ ``rebuild()`` returns None when the adapter is already complete and False when+ it still has unresolved references.+ """+ try:+ adapter = TypeAdapter(annotation)+ return None if adapter.rebuild(raise_errors=False) is False else adapter+ except Exception:+ return None++@conn_retry("AppService client", "Creating service client", max_retry=api_comm_retry)def get_service_client(service_client_type: Type[ASC],@@ -833,7 +889,9 @@ def get_service_client(sig = inspect.signature(original_func)ret_ann = sig.return_annotationexpected_return = (- None if ret_ann is inspect.Signature.empty else TypeAdapter(ret_ann)+ None+ if ret_ann is inspect.Signature.empty+ else _build_return_adapter(original_func, ret_ann, rpc_name))if inspect.iscoroutinefunction(original_func):diff --git a/autogpt_platform/backend/backend/util/service_test.py b/autogpt_platform/backend/backend/util/service_test.pyindex 899cdf9009..426893c944 100644--- a/autogpt_platform/backend/backend/util/service_test.py+++ b/autogpt_platform/backend/backend/util/service_test.py@@ -1,9 +1,11 @@import asyncioimport contextlib+import inspect+import loggingimport timefrom datetime import datetime, timezonefrom functools import cached_property-from typing import Any, Protocol, cast+from typing import Annotated, Any, Protocol, castfrom unittest.mock import Mockimport httpx@@ -12,7 +14,7 @@ import pytestfrom fastapi import FastAPIfrom fastapi.testclient import TestClientfrom prisma.errors import DataError, UniqueViolationError-from pydantic import TypeAdapter+from pydantic import BaseModel, Field, TypeAdapter, ValidationErrorfrom backend.data.model import Userfrom backend.util.exceptions import (@@ -26,6 +28,8 @@ from backend.util.service import (HTTPClientError,HTTPServerError,RemoteCallError,+ _build_return_adapter,+ _usable_adapter,endpoint_to_async,expose,get_service_client,@@ -34,6 +38,29 @@ from backend.util.service import (TEST_SERVICE_PORT = 8765+class ReviewLike(BaseModel):+ """Stand-in for a model that only the service module can name.++ Referenced by ``ServiceTest.list_reviews`` as a forward reference, which is+ what backend.data.human_review does for PendingHumanReviewModel.+ """++ id: str+ name: str = "review"+++class _NotAPydanticType:+ """Resolvable name that pydantic cannot build a schema for."""++ def __init__(self, value: Any):+ self.value = value+++def _returns_at_most_one_review() -> Annotated[list["ReviewLike"], Field(max_length=1)]:+ """Forward reference under Annotated: the constraint is part of the contract."""+ return [ReviewLike(id="0")]++class _SupportsGetReturn(Protocol):def _get_return(self, expected_return: TypeAdapter | None, result: Any) -> Any: ...@@ -84,6 +111,11 @@ class ServiceTest(AppService):return self.run_and_wait(add_async(a, b))+ @expose+ def list_reviews(self, count: int) -> list["ReviewLike"]:+ """Quoted return annotation: unresolvable from backend.util.service."""+ return [ReviewLike(id=str(i)) for i in range(count)]+@exposedef failing_add(self, a: int, b: int) -> int:"""Method that fails 2 times then succeeds - for testing retry logic"""@@ -108,7 +140,9 @@ class ServiceTestClient(AppServiceClient):fun_with_async = ServiceTest.fun_with_asyncfailing_add = ServiceTest.failing_addalways_failing_add = ServiceTest.always_failing_add+ list_reviews = ServiceTest.list_reviewsadd_async = endpoint_to_async(ServiceTest.add)+ list_reviews_async = endpoint_to_async(ServiceTest.list_reviews)subtract_async = endpoint_to_async(ServiceTest.subtract)@@ -978,3 +1012,144 @@ class TestGetReturn:result = client._get_return(adapter, invalid_dict)assert result == invalid_dict+++class TestForwardRefReturnAnnotation:+ """Regression tests for list["Model"] return annotations over the RPC.++ ``backend.data.human_review.get_pending_reviews_for_user`` is annotated+ ``-> list["PendingHumanReviewModel"]``. The client builds the TypeAdapter in+ backend.util.service, where that name does not exist, so before the fix the+ adapter was never fully defined and every call raised PydanticUserError inside+ ``_get_return`` and handed callers raw dicts.+ """++ @property+ def annotation(self):+ """The unresolved ``list["ReviewLike"]`` as the client sees it."""+ return inspect.signature(ServiceTest.list_reviews).return_annotation++ def test_annotation_is_unresolvable_from_the_service_module(self):+ """Guards the premise of the fix.++ Pydantic resolves a forward reference against the namespace of whoever+ builds the adapter. Built from backend.util.service — where the client+ builds it — the name is not in scope and there is no usable adapter.+ """+ assert _usable_adapter(self.annotation) is None++ def test_resolvable_annotation_is_adapted_without_resolution(self):+ """The ordinary case: nothing to resolve, so the annotation is used as-is."""+ adapter = _build_return_adapter(ServiceTest.add, int, "add")++ assert adapter is not None+ assert adapter.validate_python("3") == 3++ def test_build_return_adapter_resolves_the_forward_ref(self):+ """The declaring module's namespace is what makes the name resolvable."""+ adapter = _build_return_adapter(+ ServiceTest.list_reviews, self.annotation, "list_reviews"+ )+ assert adapter is not None+ assert adapter.validate_python([{"id": "1"}]) == [ReviewLike(id="1")]++ def test_build_return_adapter_resolves_through_an_async_stub(self):+ """endpoint_to_async wraps the endpoint, so resolution must unwrap it."""+ stub = ServiceTestClient.list_reviews_async+ adapter = _build_return_adapter(+ stub, inspect.signature(stub).return_annotation, "list_reviews"+ )+ assert adapter is not None+ assert adapter.validate_python([{"id": "1"}]) == [ReviewLike(id="1")]++ def test_get_return_deserializes_the_forward_ref_payload(self):+ """_get_return with that adapter returns models, not the raw dicts."""+ adapter = _build_return_adapter(+ ServiceTest.list_reviews, self.annotation, "list_reviews"+ )+ client = cast(_SupportsGetReturn, get_service_client(ServiceTestClient))+ result = client._get_return(adapter, [{"id": "1", "name": "first"}])+ assert result == [ReviewLike(id="1", name="first")]++ def test_unresolvable_annotation_yields_no_adapter(self):+ """A name nothing can resolve degrades to unvalidated results, not an error."""++ def never_defined() -> "NeverDefinedModel": ... # type: ignore[name-defined] # noqa: F821++ annotation = inspect.signature(never_defined).return_annotation+ assert (+ _build_return_adapter(never_defined, list[annotation], "never_defined")+ is None+ )++ def test_annotated_metadata_survives_the_hint_resolution(self):+ """``get_type_hints`` drops Annotated metadata unless asked to keep it.++ Losing it here would hand back an adapter with a *different* validation+ contract — the max_length below would silently stop being enforced.+ """+ annotation = inspect.signature(_returns_at_most_one_review).return_annotation+ adapter = _build_return_adapter(+ _returns_at_most_one_review, annotation, "at_most_one_review"+ )++ assert adapter is not None+ assert adapter.validate_python([{"id": "0"}]) == [ReviewLike(id="0")]+ with pytest.raises(ValidationError):+ adapter.validate_python([{"id": "0"}, {"id": "1"}])++ def test_annotation_without_a_schema_yields_no_adapter(self, caplog):+ """Resolvable, but pydantic cannot build a schema: warn once, skip validation."""++ def returns_unschemable() -> "_NotAPydanticType": ...++ with caplog.at_level(logging.WARNING, logger="backend.util.service"):+ adapter = _build_return_adapter(+ returns_unschemable, _NotAPydanticType, "returns_unschemable"+ )++ assert adapter is None+ assert "has no usable TypeAdapter" in caplog.text+++def _client_with_canned_response(payload: Any):+ """A real client whose HTTP transport answers every call with *payload*.++ Exercises the whole client path — adapter construction in ``__getattr__``,+ the HTTP round trip and ``_get_return`` — without a service process.+ """+ client = get_service_client(ServiceTestClient)+ transport = httpx.MockTransport(lambda request: httpx.Response(200, json=payload))+ inner = cast(Any, client)+ inner._sync_clients[ServiceTest.__name__] = httpx.Client(+ transport=transport, base_url=inner.base_url+ )+ inner._async_clients[None] = httpx.AsyncClient(+ transport=transport, base_url=inner.base_url+ )+ return client+++def test_forward_ref_return_is_deserialized_over_the_rpc():+ """The sync client must hand back models, not the raw JSON list."""+ served = ServiceTest.list_reviews(cast(Any, None), 2)+ client = _client_with_canned_response([r.model_dump() for r in served])++ reviews = client.list_reviews(2)++ assert reviews == [ReviewLike(id="0"), ReviewLike(id="1")]+ assert all(isinstance(review, ReviewLike) for review in reviews)+++async def test_forward_ref_return_is_deserialized_over_the_async_rpc():+ """Same contract through the async stub, which wraps the endpoint."""+ client = _client_with_canned_response([{"id": "0"}])+ inner = cast(Any, client)+ # The async client is keyed by running event loop; reuse the mocked one.+ inner._async_clients[asyncio.get_running_loop()] = inner._async_clients[None]++ reviews = await client.list_reviews_async(1)++ assert reviews == [ReviewLike(id="0")]+ assert isinstance(reviews[0], ReviewLike)