wip

Author: guglielmo-san

docs/ai/ai_learnings.md

@@ -15,5 +15,3 @@ derived from them. Every entry must follow the format below.
 **Mistake**: What went wrong.
 **Root cause**: Why it happened.
 **Rule**: The concrete rule added to prevent recurrence.
-
----

scripts/test_minimal_install.py

@@ -52,7 +52,7 @@
     'a2a.utils',
     'a2a.utils.constants',
     'a2a.utils.error_handlers',
-    'a2a.utils.helpers',
+    'a2a.utils.version_validator',
     'a2a.utils.proto_utils',
     'a2a.utils.task',
     'a2a.helpers.agent_card',

src/a2a/compat/v0_3/jsonrpc_adapter.py

@@ -40,7 +40,7 @@
     ServerCallContextBuilder,
 )
 from a2a.utils import constants
-from a2a.utils.helpers import validate_version
+from a2a.utils.version_validator import validate_version
 
 
 logger = logging.getLogger(__name__)

src/a2a/compat/v0_3/rest_handler.py

@@ -28,10 +28,8 @@
 from a2a.compat.v0_3.request_handler import RequestHandler03
 from a2a.server.context import ServerCallContext
 from a2a.utils import constants
-from a2a.utils.helpers import (
-    validate_version,
-)
 from a2a.utils.telemetry import SpanKind, trace_class
+from a2a.utils.version_validator import validate_version
 
 
 logger = logging.getLogger(__name__)

src/a2a/server/request_handlers/default_request_handler.py

@@ -58,7 +58,6 @@
     TaskNotFoundError,
     UnsupportedOperationError,
 )
-from a2a.utils.helpers import maybe_await
 from a2a.utils.task import (
     apply_history_length,
     validate_history_length,
@@ -100,7 +99,7 @@ def __init__(  # noqa: PLR0913
         request_context_builder: RequestContextBuilder | None = None,
         extended_agent_card: AgentCard | None = None,
         extended_card_modifier: Callable[
-            [AgentCard, ServerCallContext], Awaitable[AgentCard] | AgentCard
+            [AgentCard, ServerCallContext], Awaitable[AgentCard]
         ]
         | None = None,
     ) -> None:
@@ -695,8 +694,8 @@ async def on_get_extended_agent_card(
             raise ExtendedAgentCardNotConfiguredError
 
         if self.extended_card_modifier:
-            return await maybe_await(
-                self.extended_card_modifier(extended_card, context)
+            extended_card = await self.extended_card_modifier(
+                extended_card, context
             )
 
         return extended_card

src/a2a/server/request_handlers/default_request_handler_v2.py

@@ -47,7 +47,6 @@
     TaskNotCancelableError,
     TaskNotFoundError,
 )
-from a2a.utils.helpers import maybe_await
 from a2a.utils.task import (
     apply_history_length,
     validate_history_length,
@@ -93,7 +92,7 @@ def __init__(  # noqa: PLR0913
         request_context_builder: RequestContextBuilder | None = None,
         extended_agent_card: AgentCard | None = None,
         extended_card_modifier: Callable[
-            [AgentCard, ServerCallContext], Awaitable[AgentCard] | AgentCard
+            [AgentCard, ServerCallContext], Awaitable[AgentCard]
         ]
         | None = None,
     ) -> None:
@@ -467,8 +466,8 @@ async def on_get_extended_agent_card(
             raise ExtendedAgentCardNotConfiguredError
 
         if self.extended_card_modifier:
-            return await maybe_await(
-                self.extended_card_modifier(extended_card, context)
+            extended_card = await self.extended_card_modifier(
+                extended_card, context
             )
 
         return extended_card

src/a2a/server/routes/agent_card_routes.py

@@ -26,13 +26,11 @@
 from a2a.server.request_handlers.response_helpers import agent_card_to_dict
 from a2a.types.a2a_pb2 import AgentCard
 from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH
-from a2a.utils.helpers import maybe_await
 
 
 def create_agent_card_routes(
     agent_card: AgentCard,
-    card_modifier: Callable[[AgentCard], Awaitable[AgentCard] | AgentCard]
-    | None = None,
+    card_modifier: Callable[[AgentCard], Awaitable[AgentCard]] | None = None,
     card_url: str = AGENT_CARD_WELL_KNOWN_PATH,
 ) -> list['Route']:
     """Creates the Starlette Route for the A2A protocol agent card endpoint."""
@@ -45,7 +43,7 @@ def create_agent_card_routes(
     async def _get_agent_card(request: Request) -> Response:
         card_to_serve = agent_card
         if card_modifier:
-            card_to_serve = await maybe_await(card_modifier(card_to_serve))
+            card_to_serve = await card_modifier(card_to_serve)
         return JSONResponse(agent_card_to_dict(card_to_serve))
 
     return [

src/a2a/server/routes/jsonrpc_dispatcher.py

@@ -52,8 +52,8 @@
     TaskNotFoundError,
     UnsupportedOperationError,
 )
-from a2a.utils.helpers import validate_version
 from a2a.utils.telemetry import SpanKind, trace_class
+from a2a.utils.version_validator import validate_version
 
 
 INTERNAL_ERROR_CODE = -32603

src/a2a/server/routes/rest_dispatcher.py

@@ -28,8 +28,8 @@
     InvalidRequestError,
     TaskNotFoundError,
 )
-from a2a.utils.helpers import validate_version
 from a2a.utils.telemetry import SpanKind, trace_class
+from a2a.utils.version_validator import validate_version
 
 
 if TYPE_CHECKING:

src/a2a/utils/helpers.py src/a2a/utils/version_validator.pysrc/a2a/utils/helpers.py renamed to src/a2a/utils/version_validator.py

@@ -4,7 +4,7 @@
 import inspect
 import logging
 
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator, Callable
 from typing import Any, TypeVar, cast
 
 from packaging.version import InvalidVersion, Version
@@ -14,20 +14,12 @@
 from a2a.utils.errors import VersionNotSupportedError
 
 
-T = TypeVar('T')
 F = TypeVar('F', bound=Callable[..., Any])
 
 
 logger = logging.getLogger(__name__)
 
 
-async def maybe_await(value: T | Awaitable[T]) -> T:
-    """Awaits a value if it's awaitable, otherwise simply provides it back."""
-    if inspect.isawaitable(value):
-        return await value
-    return value
-
-
 def validate_version(expected_version: str) -> Callable[[F], F]:
     """Decorator that validates the A2A-Version header in the request context.