Centralizing route handler-related annotations

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/__init__.py

@@ -123,6 +123,7 @@
     "Middleware",
     "RestChannelServiceClientFactory",
     "TurnContext",
+    "RouteRank",
     "OutboundHostValidator",
     "HttpRequestProtocol",
     "HttpResponse",

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/_type_defs.py

@@ -9,6 +9,20 @@
 RouteSelector = Callable[[TurnContext], bool]
 
 StateT = TypeVar("StateT", bound=TurnState)
+_StateContra = TypeVar("_StateContra", bound=TurnState, contravariant=True)
+_RouteHandlerT = TypeVar("_RouteHandlerT", bound=Callable)
+
+
+class _RouteDecorator(Protocol[_RouteHandlerT]):
+    """Protocol for a decorator that registers *func* as a route and returns it unchanged."""
+
+    def __call__(self, func: _RouteHandlerT) -> _RouteHandlerT:
+        """Register *func* as a route handler and return it.
+
+        :param func: The handler to register.
+        :return: The same handler, unmodified, so it can be used as a plain callable.
+        """
+        ...
 
 
 class RouteHandler(Protocol[StateT]):

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/agent_application.py

@@ -51,6 +51,7 @@
     RouteHandler,
     HandoffHandler,
     RouteSelector,
+    _RouteDecorator,
 )
 from ._routes import _RouteList, _Route, RouteRank, _agentic_selector
 from .proactive import Proactive
@@ -377,7 +378,7 @@ def activity(
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs,
-    ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
+    ) -> _RouteDecorator[RouteHandler[StateT]]:
         """
         Register a new activity event listener as either a decorator or a method.
 
@@ -416,7 +417,7 @@ def message(
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs,
-    ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
+    ) -> _RouteDecorator[RouteHandler[StateT]]:
         """
         Register a new message activity event listener as either a decorator or a method.
 
@@ -470,7 +471,7 @@ def conversation_update(
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs,
-    ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
+    ) -> _RouteDecorator[RouteHandler[StateT]]:
         """
         Register a handler for conversation update activities as either a decorator or a method.
 
@@ -526,7 +527,7 @@ def message_reaction(
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs,
-    ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
+    ) -> _RouteDecorator[RouteHandler[StateT]]:
         """
         Register a handler for message reaction activities as either a decorator or a method.
 
@@ -578,7 +579,7 @@ def message_update(
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs,
-    ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
+    ) -> _RouteDecorator[RouteHandler[StateT]]:
         """
         Register a handler for message update activities as either a decorator or a method.
 
@@ -652,24 +653,15 @@ def handoff(
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs: Any,
-    ) -> Callable[
-        [HandoffHandler[StateT]],
-        HandoffHandler[StateT],
-    ]: ...
+    ) -> _RouteDecorator[HandoffHandler[StateT]]: ...
 
     def handoff(
         self,
         func: Optional[HandoffHandler[StateT]] = None,
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs,
-    ) -> (
-        HandoffHandler[StateT]
-        | Callable[
-            [HandoffHandler[StateT]],
-            HandoffHandler[StateT],
-        ]
-    ):
+    ) -> HandoffHandler[StateT] | _RouteDecorator[HandoffHandler[StateT]]:
         """
         Register a handler to hand off conversations from one copilot to another.
 

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/channel/channel.py

@@ -12,12 +12,12 @@
     RouteRank,
     TurnContext,
 )
-
-from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import (
-    _RouteDecorator,
+from microsoft_agents.hosting.core.app._type_defs import (
     StateT,
+    _RouteDecorator,
 )
+
+from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
 from microsoft_agents.hosting.msteams._utils import (
     _get_channel_event_type,
     _get_channel_info,

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/channel/route_handlers.py

@@ -6,9 +6,8 @@
 from typing import Awaitable, Protocol
 
 from microsoft_teams.api.models.channel_data import ChannelInfo
-
+from microsoft_agents.hosting.core.app._type_defs import _StateContra
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import _StateContra
 
 
 class ChannelUpdateHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/config/config.py

@@ -11,12 +11,12 @@
     RouteRank,
     TurnContext,
 )
-
-from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import (
-    _RouteDecorator,
+from microsoft_agents.hosting.core.app._type_defs import (
     StateT,
+    _RouteDecorator,
 )
+
+from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
 from microsoft_agents.hosting.msteams._utils import _send_invoke_response
 
 from .route_handlers import ConfigHandler

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/config/route_handlers.py

@@ -6,9 +6,8 @@
 from typing import Any, Awaitable, Protocol
 
 from microsoft_teams.api.models.config import ConfigResponse
-
+from microsoft_agents.hosting.core.app._type_defs import _StateContra
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import _StateContra
 
 
 class ConfigHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/file_consent/file_consent.py

@@ -13,12 +13,12 @@
     RouteRank,
     TurnContext,
 )
-
-from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import (
-    _RouteDecorator,
+from microsoft_agents.hosting.core.app._type_defs import (
     StateT,
+    _RouteDecorator,
 )
+
+from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
 from microsoft_agents.hosting.msteams._utils import _send_invoke_response
 
 from .route_handlers import FileConsentHandler

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/file_consent/route_handlers.py

@@ -6,9 +6,8 @@
 from typing import Awaitable, Protocol
 
 from microsoft_teams.api.models import FileConsentCardResponse
-
+from microsoft_agents.hosting.core.app._type_defs import _StateContra
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import _StateContra
 
 
 class FileConsentHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/meeting/meeting.py

@@ -14,13 +14,13 @@
     RouteRank,
     TurnContext,
 )
-
-from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import (
-    _RouteDecorator,
+from microsoft_agents.hosting.core.app._type_defs import (
     StateT,
+    _RouteDecorator,
 )
 
+from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
+
 from .route_handlers import (
     MeetingStartHandler,
     MeetingEndHandler,

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/meeting/route_handlers.py

@@ -8,8 +8,8 @@
 from microsoft_teams.api.models.meetings import MeetingDetails
 from microsoft_agents.activity.teams import MeetingParticipantsEventDetails
 
+from microsoft_agents.hosting.core.app._type_defs import _StateContra
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import _StateContra
 
 
 class MeetingStartHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/message/message.py

@@ -13,16 +13,16 @@
     RouteRank,
     TurnContext,
 )
+from microsoft_agents.hosting.core.app._type_defs import (
+    StateT,
+    _RouteDecorator,
+)
 
 from microsoft_agents.hosting.msteams.route_handlers import (
     TeamsRouteHandler,
     wrap_teams_route_handler,
 )
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import (
-    _RouteDecorator,
-    StateT,
-)
 from microsoft_agents.hosting.msteams._utils import (
     _get_channel_event_type,
     _send_invoke_response,

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/message/route_handlers.py

@@ -7,8 +7,9 @@
 
 from microsoft_teams.api.models.o365 import O365ConnectorCardActionQuery
 
+from microsoft_agents.hosting.core.app._type_defs import _StateContra
+
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import _StateContra
 
 
 class ExecuteActionHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/message_extension/message_extension.py

@@ -18,14 +18,15 @@
     RouteRank,
     TurnContext,
 )
-
-from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import (
+from microsoft_agents.hosting.core.app._type_defs import (
     StateT,
-    CommandSelector,
     _RouteDecorator,
 )
 
+from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
+
+from microsoft_agents.hosting.msteams.type_defs import CommandSelector
+
 from microsoft_agents.hosting.msteams._utils import (
     _get_command_id,
     _match_selector,

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/message_extension/route_handlers.py

@@ -18,9 +18,9 @@
 )
 
 from microsoft_agents.activity import Activity
+from microsoft_agents.hosting.core.app._type_defs import _StateContra
 
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import _StateContra
 
 
 class FetchActionHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/route_handlers.py

@@ -14,10 +14,10 @@
 from microsoft_agents.hosting.core.app._type_defs import (
     RouteHandler,
     HandoffHandler,
+    _StateContra,
 )
 
 from .teams_turn_context import TeamsTurnContext
-from .type_defs import _StateContra
 
 
 class TeamsRouteHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/task_module/route_handlers.py

@@ -7,8 +7,9 @@
 
 from microsoft_teams.api.models import TaskModuleRequest, TaskModuleResponse
 
+from microsoft_agents.hosting.core.app._type_defs import _StateContra
+
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import _StateContra
 
 
 class FetchHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/task_module/task_module.py

@@ -10,13 +10,11 @@
 from microsoft_agents.activity import ActivityTypes
 
 from microsoft_agents.hosting.core import AgentApplication, RouteRank, TurnContext
+from microsoft_agents.hosting.core.app._type_defs import _RouteDecorator, StateT
 
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import (
-    CommandSelector,
-    _RouteDecorator,
-    StateT,
-)
+from microsoft_agents.hosting.msteams.type_defs import CommandSelector
+
 from microsoft_agents.hosting.msteams._utils import (
     _match_selector,
     _send_invoke_response,

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/team/route_handlers.py

@@ -6,9 +6,8 @@
 from typing import Awaitable, Protocol
 
 from microsoft_teams.api.models.channel_data import TeamInfo
-
+from microsoft_agents.hosting.core.app._type_defs import _StateContra
 from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import _StateContra
 
 
 class TeamUpdateHandler(Protocol[_StateContra]):

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/team/team.py

@@ -12,12 +12,12 @@
     RouteRank,
     TurnContext,
 )
-
-from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
-from microsoft_agents.hosting.msteams.type_defs import (
+from microsoft_agents.hosting.core.app._type_defs import (
     _RouteDecorator,
     StateT,
 )
+
+from microsoft_agents.hosting.msteams.teams_turn_context import TeamsTurnContext
 from microsoft_agents.hosting.msteams._utils import (
     _get_channel_event_type,
     _get_team_info,

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/teams_agent_extension.py

@@ -33,7 +33,11 @@
     AgentApplication,
     TurnContext,
 )
-from microsoft_agents.hosting.core.app._type_defs import RouteHandler, HandoffHandler
+from microsoft_agents.hosting.core.app._type_defs import (
+    RouteHandler,
+    HandoffHandler,
+    StateT,
+)
 
 from .channel import Channel
 from .config import Config
@@ -63,9 +67,6 @@
 )
 from ._utils import _try_get_channel_data
 
-from .teams_activity import TeamsActivity
-from .type_defs import StateT
-
 
 class _AppRouteDecorator(Protocol[StateT]):
     """Protocol for a decorator returned by :class:`TeamsAgentExtension` route methods."""