microsoft-agents-hosting-core 0.4.0.dev16__py3-none-any.whl → 0.5.0__py3-none-any.whl

microsoft_agents/hosting/core/app/agent_application.py

@@ -13,9 +13,7 @@ from typing import (
     Any,
     Awaitable,
     Callable,
-    Dict,
     Generic,
-    List,
     Optional,
     Pattern,
     TypeVar,
@@ -38,16 +36,17 @@ from ..authorization import Connections
 from .app_error import ApplicationError
 from .app_options import ApplicationOptions
 
-from .route import Route, RouteHandler
 from .state import TurnState
 from ..channel_service_adapter import ChannelServiceAdapter
 from .oauth import Authorization
 from .typing_indicator import TypingIndicator
 
+from ._type_defs import RouteHandler, RouteSelector
+from ._routes import _RouteList, _Route, RouteRank, _agentic_selector
+
 logger = logging.getLogger(__name__)
 
 StateT = TypeVar("StateT", bound=TurnState)
-IN_SIGN_IN_KEY = "__InSignInFlow__"
 
 
 class AgentApplication(Agent, Generic[StateT]):
@@ -68,25 +67,33 @@ class AgentApplication(Agent, Generic[StateT]):
     _options: ApplicationOptions
     _adapter: Optional[ChannelServiceAdapter] = None
     _auth: Optional[Authorization] = None
-    _internal_before_turn: List[Callable[[TurnContext, StateT], Awaitable[bool]]] = []
-    _internal_after_turn: List[Callable[[TurnContext, StateT], Awaitable[bool]]] = []
-    _routes: List[Route[StateT]] = []
+    _internal_before_turn: list[Callable[[TurnContext, StateT], Awaitable[bool]]] = []
+    _internal_after_turn: list[Callable[[TurnContext, StateT], Awaitable[bool]]] = []
+    _route_list: _RouteList[StateT] = _RouteList[StateT]()
     _error: Optional[Callable[[TurnContext, Exception], Awaitable[None]]] = None
     _turn_state_factory: Optional[Callable[[TurnContext], StateT]] = None
 
     def __init__(
         self,
-        options: ApplicationOptions = None,
+        options: Optional[ApplicationOptions] = None,
         *,
-        connection_manager: Connections = None,
-        authorization: Authorization = None,
+        connection_manager: Optional[Connections] = None,
+        authorization: Optional[Authorization] = None,
         **kwargs,
     ) -> None:
         """
         Creates a new AgentApplication instance.
+
+        :param options: Configuration options for the application.
+        :type options: Optional[:class:`microsoft_agents.hosting.core.app.app_options.ApplicationOptions`]
+        :param connection_manager: OAuth connection manager.
+        :type connection_manager: Optional[:class:`microsoft_agents.hosting.core.authorization.Connections`]
+        :param authorization: Authorization manager for handling authentication flows.
+        :type authorization: Optional[:class:`microsoft_agents.hosting.core.app.oauth.Authorization`]
+        :param kwargs: Additional configuration parameters.
+        :type kwargs: Any
         """
-        self.typing = TypingIndicator()
-        self._routes = []
+        self._route_list = _RouteList[StateT]()
 
         configuration = kwargs
 
@@ -162,6 +169,10 @@ class AgentApplication(Agent, Generic[StateT]):
     def adapter(self) -> ChannelServiceAdapter:
         """
         The bot's adapter.
+
+        :return: The channel service adapter for the bot.
+        :rtype: :class:`microsoft_agents.hosting.core.channel_service_adapter.ChannelServiceAdapter`
+        :raises ApplicationError: If the adapter is not configured.
         """
 
         if not self._adapter:
@@ -182,6 +193,10 @@ class AgentApplication(Agent, Generic[StateT]):
     def auth(self) -> Authorization:
         """
         The application's authentication manager
+
+        :return: The authentication manager for handling OAuth flows.
+        :rtype: :class:`microsoft_agents.hosting.core.app.oauth.Authorization`
+        :raises ApplicationError: If authentication is not configured.
         """
         if not self._auth:
             logger.error(
@@ -201,14 +216,60 @@ class AgentApplication(Agent, Generic[StateT]):
     def options(self) -> ApplicationOptions:
         """
         The application's configured options.
+
+        :return: The configuration options for the application.
+        :rtype: :class:`microsoft_agents.hosting.core.app.app_options.ApplicationOptions`
         """
         return self._options
 
+    def add_route(
+        self,
+        selector: RouteSelector,
+        handler: RouteHandler[StateT],
+        is_invoke: bool = False,
+        is_agentic: bool = False,
+        rank: RouteRank = RouteRank.DEFAULT,
+        auth_handlers: Optional[list[str]] = None,
+    ) -> None:
+        """Adds a new route to the application.
+
+        Routes are ordered by: is_agentic, is_invoke, rank (lower is higher priority), in that order.
+
+        :param selector: A function that takes a TurnContext and returns a boolean indicating whether the route should be selected.
+        :type selector: :class:`microsoft_agents.hosting.core.app._type_defs.RouteSelector`
+        :param handler: A function that takes a TurnContext and a TurnState and returns an Awaitable.
+        :type handler: :class:`microsoft_agents.hosting.core.app._type_defs.RouteHandler`[StateT]
+        :param is_invoke: Whether the route is for an invoke activity, defaults to False
+        :type is_invoke: bool, Optional
+        :param is_agentic: Whether the route is for an agentic request, defaults to False. For agentic requests
+            the selector will include a new check for `context.activity.is_agentic_request()`.
+        :type is_agentic: bool, Optional
+        :param rank: The rank of the route, defaults to RouteRank.DEFAULT
+        :type rank: :class:`microsoft_agents.hosting.core.app._routes.RouteRank`, Optional
+        :param auth_handlers: A list of authentication handler IDs to use for this route, defaults to None
+        :type auth_handlers: Optional[list[str]], Optional
+        :raises ApplicationError: If the selector or handler are not valid.
+        """
+        if not selector or not handler:
+            logger.error(
+                "AgentApplication.add_route(): selector and handler are required."
+            )
+            raise ApplicationError("selector and handler are required.")
+
+        if is_agentic:
+            selector = _agentic_selector(selector)
+
+        route = _Route[StateT](
+            selector, handler, is_invoke, rank, auth_handlers, is_agentic
+        )
+        self._route_list.add_route(route)
+
     def activity(
         self,
-        activity_type: Union[str, ActivityTypes, List[Union[str, ActivityTypes]]],
+        activity_type: Union[str, ActivityTypes, list[Union[str, ActivityTypes]]],
         *,
-        auth_handlers: Optional[List[str]] = None,
+        auth_handlers: Optional[list[str]] = None,
+        **kwargs,
     ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
         """
         Registers a new activity event listener. This method can be used as either
@@ -233,18 +294,17 @@ class AgentApplication(Agent, Generic[StateT]):
             logger.debug(
                 f"Registering activity handler for route handler {func.__name__} with type: {activity_type} with auth handlers: {auth_handlers}"
             )
-            self._routes.append(
-                Route[StateT](__selector, func, auth_handlers=auth_handlers)
-            )
+            self.add_route(__selector, func, auth_handlers=auth_handlers, **kwargs)
             return func
 
         return __call
 
     def message(
         self,
-        select: Union[str, Pattern[str], List[Union[str, Pattern[str]]]],
+        select: Union[str, Pattern[str], list[Union[str, Pattern[str]]]],
         *,
-        auth_handlers: Optional[List[str]] = None,
+        auth_handlers: Optional[list[str]] = None,
+        **kwargs,
     ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
         """
         Registers a new message activity event listener. This method can be used as either
@@ -276,9 +336,7 @@ class AgentApplication(Agent, Generic[StateT]):
             logger.debug(
                 f"Registering message handler for route handler {func.__name__} with select: {select} with auth handlers: {auth_handlers}"
             )
-            self._routes.append(
-                Route[StateT](__selector, func, auth_handlers=auth_handlers)
-            )
+            self.add_route(__selector, func, auth_handlers=auth_handlers, **kwargs)
             return func
 
         return __call
@@ -287,7 +345,8 @@ class AgentApplication(Agent, Generic[StateT]):
         self,
         type: ConversationUpdateTypes,
         *,
-        auth_handlers: Optional[List[str]] = None,
+        auth_handlers: Optional[list[str]] = None,
+        **kwargs,
     ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
         """
         Registers a new message activity event listener. This method can be used as either
@@ -311,12 +370,12 @@ class AgentApplication(Agent, Generic[StateT]):
                 return False
 
             if type == "membersAdded":
-                if isinstance(context.activity.members_added, List):
+                if isinstance(context.activity.members_added, list):
                     return len(context.activity.members_added) > 0
                 return False
 
             if type == "membersRemoved":
-                if isinstance(context.activity.members_removed, List):
+                if isinstance(context.activity.members_removed, list):
                     return len(context.activity.members_removed) > 0
                 return False
 
@@ -330,15 +389,17 @@ class AgentApplication(Agent, Generic[StateT]):
             logger.debug(
                 f"Registering conversation update handler for route handler {func.__name__} with type: {type} with auth handlers: {auth_handlers}"
             )
-            self._routes.append(
-                Route[StateT](__selector, func, auth_handlers=auth_handlers)
-            )
+            self.add_route(__selector, func, auth_handlers=auth_handlers, **kwargs)
             return func
 
         return __call
 
     def message_reaction(
-        self, type: MessageReactionTypes, *, auth_handlers: Optional[List[str]] = None
+        self,
+        type: MessageReactionTypes,
+        *,
+        auth_handlers: Optional[list[str]] = None,
+        **kwargs,
     ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
         """
         Registers a new message activity event listener. This method can be used as either
@@ -361,12 +422,12 @@ class AgentApplication(Agent, Generic[StateT]):
                 return False
 
             if type == "reactionsAdded":
-                if isinstance(context.activity.reactions_added, List):
+                if isinstance(context.activity.reactions_added, list):
                     return len(context.activity.reactions_added) > 0
                 return False
 
             if type == "reactionsRemoved":
-                if isinstance(context.activity.reactions_removed, List):
+                if isinstance(context.activity.reactions_removed, list):
                     return len(context.activity.reactions_removed) > 0
                 return False
 
@@ -376,15 +437,17 @@ class AgentApplication(Agent, Generic[StateT]):
             logger.debug(
                 f"Registering message reaction handler for route handler {func.__name__} with type: {type} with auth handlers: {auth_handlers}"
             )
-            self._routes.append(
-                Route[StateT](__selector, func, auth_handlers=auth_handlers)
-            )
+            self.add_route(__selector, func, auth_handlers=auth_handlers, **kwargs)
             return func
 
         return __call
 
     def message_update(
-        self, type: MessageUpdateTypes, *, auth_handlers: Optional[List[str]] = None
+        self,
+        type: MessageUpdateTypes,
+        *,
+        auth_handlers: Optional[list[str]] = None,
+        **kwargs,
     ) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]:
         """
         Registers a new message activity event listener. This method can be used as either
@@ -435,14 +498,14 @@ class AgentApplication(Agent, Generic[StateT]):
             logger.debug(
                 f"Registering message update handler for route handler {func.__name__} with type: {type} with auth handlers: {auth_handlers}"
             )
-            self._routes.append(
-                Route[StateT](__selector, func, auth_handlers=auth_handlers)
-            )
+            self.add_route(__selector, func, auth_handlers=auth_handlers, **kwargs)
             return func
 
         return __call
 
-    def handoff(self, *, auth_handlers: Optional[List[str]] = None) -> Callable[
+    def handoff(
+        self, *, auth_handlers: Optional[list[str]] = None, **kwargs
+    ) -> Callable[
         [Callable[[TurnContext, StateT, str], Awaitable[None]]],
         Callable[[TurnContext, StateT, str], Awaitable[None]],
     ]:
@@ -483,10 +546,7 @@ class AgentApplication(Agent, Generic[StateT]):
                 f"Registering handoff handler for route handler {func.__name__} with auth handlers: {auth_handlers}"
             )
 
-            self._routes.append(
-                Route[StateT](__selector, __handler, True, auth_handlers)
-            )
-            self._routes = sorted(self._routes, key=lambda route: not route.is_invoke)
+            self.add_route(__selector, func, auth_handlers=auth_handlers, **kwargs)
             return func
 
         return __call
@@ -598,10 +658,12 @@ class AgentApplication(Agent, Generic[StateT]):
         await self._start_long_running_call(context, self._on_turn)
 
     async def _on_turn(self, context: TurnContext):
-        # robrandao: TODO
+        typing = None
         try:
             if context.activity.type != ActivityTypes.typing:
-                await self._start_typing(context)
+                if self._options.start_typing_timer:
+                    typing = TypingIndicator()
+                    await typing.start(context)
 
             self._remove_mentions(context)
 
@@ -649,11 +711,8 @@ class AgentApplication(Agent, Generic[StateT]):
             )
             await self._on_error(context, err)
         finally:
-            self.typing.stop()
-
-    async def _start_typing(self, context: TurnContext):
-        if self._options.start_typing_timer:
-            await self.typing.start(context)
+            if typing:
+                await typing.stop()
 
     def _remove_mentions(self, context: TurnContext):
         if (
@@ -663,9 +722,14 @@ class AgentApplication(Agent, Generic[StateT]):
             context.activity.text = context.remove_recipient_mention(context.activity)
 
     @staticmethod
-    def parse_env_vars_configuration(vars: Dict[str, Any]) -> dict:
+    def parse_env_vars_configuration(vars: dict[str, Any]) -> dict:
         """
         Parses environment variables and returns a dictionary with the relevant configuration.
+
+        :param vars: Dictionary of environment variable names and values.
+        :type vars: dict[str, Any]
+        :return: Parsed configuration dictionary with nested structure.
+        :rtype: dict
         """
         result = {}
         for key, value in vars.items():
@@ -738,7 +802,7 @@ class AgentApplication(Agent, Generic[StateT]):
         return True
 
     async def _on_activity(self, context: TurnContext, state: StateT):
-        for route in self._routes:
+        for route in self._route_list:
             if route.selector(context):
                 if not route.auth_handlers:
                     await route.handler(context, state)

microsoft_agents/hosting/core/app/input_file.py

@@ -16,10 +16,12 @@ from microsoft_agents.hosting.core import TurnContext
 class InputFile:
     """A file sent by the user to the bot.
 
-    Attributes:
-        content (bytes): The downloaded content of the file.
-        content_type (str): The content type of the file.
-        content_url (Optional[str]): Optional. URL to the content of the file.
+    :param content: The downloaded content of the file.
+    :type content: bytes
+    :param content_type: The content type of the file.
+    :type content_type: str
+    :param content_url: Optional. URL to the content of the file.
+    :type content_url: Optional[str]
     """
 
     content: bytes
@@ -29,17 +31,19 @@ class InputFile:
 
 class InputFileDownloader(ABC):
     """
-    A plugin responsible for downloading files relative to the current user's input.
+    Abstract base class for a plugin responsible for downloading files provided by the user.
+
+    Implementations should download any files referenced by the incoming activity and return a
+    list of :class:`InputFile` instances representing the downloaded content.
     """
 
     @abstractmethod
     async def download_files(self, context: TurnContext) -> List[InputFile]:
         """
-        Download any files relative to the current user's input.
-
-        Args:
-            context (TurnContext): Context for the current turn of conversation.
+        Download any files referenced by the incoming activity for the current turn.
 
-        Returns:
-            List[InputFile]: A list of input files.
+        :param context: The turn context for the current request.
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :return: A list of downloaded :class:`InputFile` objects.
+        :rtype: list[:class:`microsoft_agents.hosting.core.app.input_file.InputFile`]
         """

microsoft_agents/hosting/core/app/oauth/__init__.py

@@ -1,3 +1,7 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+
 from .authorization import Authorization
 from .auth_handler import AuthHandler
 from ._sign_in_state import _SignInState

microsoft_agents/hosting/core/app/oauth/_handlers/__init__.py

@@ -1,3 +1,8 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
 from .agentic_user_authorization import AgenticUserAuthorization
 from ._user_authorization import _UserAuthorization
 from ._authorization_handler import _AuthorizationHandler

microsoft_agents/hosting/core/app/oauth/_handlers/_authorization_handler.py

@@ -1,3 +1,8 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
 from abc import ABC
 from typing import Optional
 import logging
@@ -38,7 +43,7 @@ class _AuthorizationHandler(ABC):
         :param connection_manager: The connection manager for OAuth providers.
         :type connection_manager: Connections
         :param auth_handlers: Configuration for OAuth providers.
-        :type auth_handlers: dict[str, AuthHandler], optional
+        :type auth_handlers: dict[str, AuthHandler], Optional
         :raises ValueError: When storage is None or no auth handlers provided.
         """
         if not storage:
@@ -70,7 +75,7 @@ class _AuthorizationHandler(ABC):
         :param context: The turn context for the current turn of conversation.
         :type context: TurnContext
         :param scopes: Optional list of scopes to request during sign-in. If None, default scopes will be used.
-        :type scopes: Optional[list[str]], optional
+        :type scopes: Optional[list[str]], Optional
         :return: A SignInResponse indicating the result of the sign-in attempt.
         :rtype: SignInResponse
         """
@@ -87,9 +92,9 @@ class _AuthorizationHandler(ABC):
         :param context: The turn context for the current turn of conversation.
         :type context: TurnContext
         :param exchange_connection: Optional name of the connection to use for token exchange. If None, default connection will be used.
-        :type exchange_connection: Optional[str], optional
+        :type exchange_connection: Optional[str], Optional
         :param exchange_scopes: Optional list of scopes to request during token exchange. If None, default scopes will be used.
-        :type exchange_scopes: Optional[list[str]], optional
+        :type exchange_scopes: Optional[list[str]], Optional
         """
         raise NotImplementedError()
 

microsoft_agents/hosting/core/app/oauth/_handlers/_user_authorization.py

@@ -1,5 +1,7 @@
-# Copyright (c) Microsoft Corporation. All rights reserved.
-# Licensed under the MIT License.
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
 
 from __future__ import annotations
 import logging
@@ -247,9 +249,9 @@ class _UserAuthorization(_AuthorizationHandler):
         :param context: The turn context for the current turn of conversation.
         :type context: TurnContext
         :param exchange_connection: Optional name of the connection to use for token exchange. If None, default connection will be used.
-        :type exchange_connection: Optional[str], optional
+        :type exchange_connection: Optional[str], Optional
         :param exchange_scopes: Optional list of scopes to request during token exchange. If None, default scopes will be used.
-        :type exchange_scopes: Optional[list[str]], optional
+        :type exchange_scopes: Optional[list[str]], Optional
         """
         flow, _ = await self._load_flow(context)
         input_token_response = await flow.get_user_token()

microsoft_agents/hosting/core/app/oauth/_handlers/agentic_user_authorization.py

@@ -1,3 +1,8 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
 import logging
 
 from typing import Optional
@@ -36,7 +41,7 @@ class AgenticUserAuthorization(_AuthorizationHandler):
         :param connection_manager: The connection manager for OAuth providers.
         :type connection_manager: Connections
         :param auth_handlers: Configuration for OAuth providers.
-        :type auth_handlers: dict[str, AuthHandler], optional
+        :type auth_handlers: dict[str, AuthHandler], Optional
         :raises ValueError: When storage is None or no auth handlers provided.
         """
         super().__init__(
@@ -113,20 +118,20 @@ class AgenticUserAuthorization(_AuthorizationHandler):
             connection = self._connection_manager.get_token_provider(
                 context.identity, "agentic"
             )
-        upn = context.activity.get_agentic_user()
+        agentic_user_id = context.activity.get_agentic_user()
         agentic_instance_id = context.activity.get_agentic_instance_id()
-        if not upn or not agentic_instance_id:
+        if not agentic_user_id or not agentic_instance_id:
             logger.error(
-                "Unable to retrieve agentic user token: missing UPN or agentic instance ID. UPN: %s, Agentic Instance ID: %s",
-                upn,
+                "Unable to retrieve agentic user token: missing agentic user Id or agentic instance Id. agentic_user_id: %s, Agentic Instance ID: %s",
+                agentic_user_id,
                 agentic_instance_id,
             )
             raise ValueError(
-                f"Unable to retrieve agentic user token: missing UPN or agentic instance ID. UPN: {upn}, Agentic Instance ID: {agentic_instance_id}"
+                f"Unable to retrieve agentic user token: missing agentic User Id or agentic instance Id. agentic_user_id: {agentic_user_id}, Agentic Instance ID: {agentic_instance_id}"
             )
 
         token = await connection.get_agentic_user_token(
-            agentic_instance_id, upn, scopes
+            agentic_instance_id, agentic_user_id, scopes
         )
         return TokenResponse(token=token) if token else TokenResponse()
 
@@ -167,9 +172,9 @@ class AgenticUserAuthorization(_AuthorizationHandler):
         :param context: The turn context for the current turn of conversation.
         :type context: TurnContext
         :param exchange_connection: Optional name of the connection to use for token exchange. If None, default connection will be used.
-        :type exchange_connection: Optional[str], optional
+        :type exchange_connection: Optional[str], Optional
         :param exchange_scopes: Optional list of scopes to request during token exchange. If None, default scopes will be used.
-        :type exchange_scopes: Optional[list[str]], optional
+        :type exchange_scopes: Optional[list[str]], Optional
         """
         if not exchange_scopes:
             exchange_scopes = self._handler.scopes or []

microsoft_agents/hosting/core/app/oauth/_sign_in_response.py

@@ -1,3 +1,7 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+
 from typing import Optional
 
 from microsoft_agents.activity import TokenResponse

microsoft_agents/hosting/core/app/oauth/_sign_in_state.py

@@ -1,3 +1,8 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
 from __future__ import annotations
 
 from typing import Optional

microsoft_agents/hosting/core/app/oauth/auth_handler.py

@@ -1,5 +1,7 @@
-# Copyright (c) Microsoft Corporation. All rights reserved.
-# Licensed under the MIT License.
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
 
 import logging
 from typing import Optional