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

microsoft_agents/hosting/core/__init__.py

@@ -11,12 +11,13 @@ from .rest_channel_service_client_factory import RestChannelServiceClientFactory
 from .turn_context import TurnContext
 
 # Application Style
+from .app._type_defs import RouteHandler, RouteSelector, StateT
 from .app.agent_application import AgentApplication
 from .app.app_error import ApplicationError
 from .app.app_options import ApplicationOptions
 from .app.input_file import InputFile, InputFileDownloader
 from .app.query import Query
-from .app.route import Route, RouteHandler
+from .app._routes import _Route, _RouteList, RouteRank
 from .app.typing_indicator import TypingIndicator
 
 # App Auth

microsoft_agents/hosting/core/_oauth/__init__.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from ._flow_state import _FlowState, _FlowStateTag, _FlowErrorTag
 from ._flow_storage_client import _FlowStorageClient
 from ._oauth_flow import _OAuthFlow, _FlowResponse

microsoft_agents/hosting/core/_oauth/_flow_state.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from typing import Optional
 
@@ -60,7 +60,7 @@ class _FlowState(BaseModel, StoreItem):
         return _FlowState.model_validate(json_data)
 
     def is_expired(self) -> bool:
-        return datetime.now().timestamp() >= self.expiration
+        return datetime.now(timezone.utc).timestamp() >= self.expiration
 
     def reached_max_attempts(self) -> bool:
         return self.attempts_remaining <= 0

microsoft_agents/hosting/core/_oauth/_oauth_flow.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 import logging
 
 from pydantic import BaseModel
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Optional
 
 from microsoft_agents.activity import (
@@ -30,7 +30,6 @@ class _FlowResponse(BaseModel):
     flow_error_tag: _FlowErrorTag = _FlowErrorTag.NONE
     token_response: Optional[TokenResponse] = None
     sign_in_resource: Optional[SignInResource] = None
-    continuation_activity: Optional[Activity] = None
 
 
 class _OAuthFlow:
@@ -112,7 +111,7 @@ class _OAuthFlow:
         """Get the user token based on the context.
 
         Args:
-            magic_code (str, optional): Defaults to None. The magic code for user authentication.
+            magic_code (str, Optional): Defaults to None. The magic code for user authentication.
 
         Returns:
             TokenResponse
@@ -137,7 +136,7 @@ class _OAuthFlow:
         if token_response:
             logger.info("User token obtained successfully: %s", token_response)
             self._flow_state.expiration = (
-                datetime.now().timestamp() + self._default_flow_duration
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
             )
             self._flow_state.tag = _FlowStateTag.COMPLETE
 
@@ -183,20 +182,8 @@ class _OAuthFlow:
         Notes:
             The flow state is reset if a token is not obtained from cache.
         """
-        token_response = await self.get_user_token()
-        if token_response:
-            return _FlowResponse(
-                flow_state=self._flow_state, token_response=token_response
-            )
 
         logger.debug("Starting new OAuth flow")
-        self._flow_state.tag = _FlowStateTag.BEGIN
-        self._flow_state.expiration = (
-            datetime.now().timestamp() + self._default_flow_duration
-        )
-
-        self._flow_state.attempts_remaining = self._max_attempts
-        self._flow_state.continuation_activity = activity.model_copy()
 
         token_exchange_state = TokenExchangeState(
             connection_name=self._abs_oauth_connection_name,
@@ -205,16 +192,33 @@ class _OAuthFlow:
             ms_app_id=self._ms_app_id,
         )
 
-        sign_in_resource = (
-            await self._user_token_client.agent_sign_in.get_sign_in_resource(
-                state=token_exchange_state.get_encoded_state()
+        res = await self._user_token_client.user_token._get_token_or_sign_in_resource(
+            activity.from_property.id,
+            self._abs_oauth_connection_name,
+            activity.channel_id,
+            token_exchange_state.get_encoded_state(),
+        )
+
+        if res.token_response:
+            logger.info("Skipping flow, user token obtained.")
+            self._flow_state.tag = _FlowStateTag.COMPLETE
+            self._flow_state.expiration = (
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
+            )
+            return _FlowResponse(
+                flow_state=self._flow_state, token_response=res.token_response
             )
+
+        self._flow_state.tag = _FlowStateTag.BEGIN
+        self._flow_state.expiration = (
+            datetime.now(timezone.utc).timestamp() + self._default_flow_duration
         )
+        self._flow_state.attempts_remaining = self._max_attempts
 
-        logger.debug("Sign-in resource obtained successfully: %s", sign_in_resource)
+        logger.debug("Sign-in resource obtained successfully: %s", res.sign_in_resource)
 
         return _FlowResponse(
-            flow_state=self._flow_state, sign_in_resource=sign_in_resource
+            flow_state=self._flow_state, sign_in_resource=res.sign_in_resource
         )
 
     async def _continue_from_message(
@@ -299,7 +303,7 @@ class _OAuthFlow:
         else:
             self._flow_state.tag = _FlowStateTag.COMPLETE
             self._flow_state.expiration = (
-                datetime.now().timestamp() + self._default_flow_duration
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
             )
             logger.debug(
                 "OAuth flow completed successfully, got TokenResponse: %s",
@@ -310,7 +314,6 @@ class _OAuthFlow:
             flow_state=self._flow_state.model_copy(),
             flow_error_tag=flow_error_tag,
             token_response=token_response,
-            continuation_activity=self._flow_state.continuation_activity,
         )
 
     async def begin_or_continue_flow(self, activity: Activity) -> _FlowResponse:

microsoft_agents/hosting/core/activity_handler.py

@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
+
 from __future__ import annotations
 from http import HTTPStatus
 from pydantic import BaseModel
@@ -37,7 +38,7 @@ class ActivityHandler(Agent):
         in order to process an inbound :class:`microsoft_agents.activity.Activity`.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -142,7 +143,7 @@ class ActivityHandler(Agent):
         :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -175,7 +176,7 @@ class ActivityHandler(Agent):
 
         :param members_added: A list of all the members added to the conversation, as described by the
         conversation update activity
-        :type members_added: list[ChannelAccount]
+        :type members_added: list[:class:`microsoft_agents.activity.ChannelAccount`]
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
@@ -194,9 +195,9 @@ class ActivityHandler(Agent):
         Override this method in a derived class to provide logic for when members other than the agent leave
         the conversation.  You can add your agent's good-bye logic.
 
-        :param members_added: A list of all the members removed from the conversation, as described by the
+        :param members_removed: A list of all the members removed from the conversation, as described by the
         conversation update activity
-        :type members_added: list[ChannelAccount]
+        :type members_removed: list[:class:`microsoft_agents.activity.ChannelAccount`]
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
@@ -215,7 +216,7 @@ class ActivityHandler(Agent):
         :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -259,7 +260,7 @@ class ActivityHandler(Agent):
         are added to the conversation.
 
         :param message_reactions: The list of reactions added
-        :type message_reactions: list[MessageReaction]
+        :type message_reactions: list[:class:`microsoft_agents.activity.MessageReaction`]
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
@@ -284,7 +285,7 @@ class ActivityHandler(Agent):
         are removed from the conversation.
 
         :param message_reactions: The list of reactions removed
-        :type message_reactions: list[MessageReaction]
+        :type message_reactions: list[:class:`microsoft_agents.activity.MessageReaction`]
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
@@ -381,7 +382,7 @@ class ActivityHandler(Agent):
         ActivityTypes.typing activities, such as the conversational logic.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -394,7 +395,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         if turn_context.activity.action in ("add", "add-upgrade"):
@@ -411,7 +412,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities with 'action' set to 'add'.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -424,7 +425,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities with 'action' set to 'remove'.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -438,7 +439,7 @@ class ActivityHandler(Agent):
         If overridden, this method could potentially respond to any of the other activity types.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -455,9 +456,10 @@ class ActivityHandler(Agent):
         Registers an activity event handler for the _invoke_ event, emitted for every incoming event activity.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
+        :rtype: Optional[:class:`microsoft_agents.activity.InvokeResponse`]
         """
         try:
             if (
@@ -491,7 +493,7 @@ class ActivityHandler(Agent):
         By default, this method does nothing.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
         """
@@ -507,10 +509,11 @@ class ActivityHandler(Agent):
         calls this method.
 
         :param turn_context: A context object for this turn.
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :param invoke_value: A string-typed object from the incoming activity's value.
-        :type invoke_value: :class:`microsoft_agents.activity.adaptive_card_invoke_value.AdaptiveCardInvokeValue`
+        :type invoke_value: :class:`microsoft_agents.activity.AdaptiveCardInvokeValue`
         :return: The HealthCheckResponse object
+        :rtype: :class:`microsoft_agents.activity.AdaptiveCardInvokeResponse`
         """
         raise _InvokeResponseException(HTTPStatus.NOT_IMPLEMENTED)
 

microsoft_agents/hosting/core/app/__init__.py

@@ -10,8 +10,9 @@ from .app_error import ApplicationError
 from .app_options import ApplicationOptions
 from .input_file import InputFile, InputFileDownloader
 from .query import Query
-from .route import Route, RouteHandler
+from ._routes import _RouteList, _Route, RouteRank
 from .typing_indicator import TypingIndicator
+from ._type_defs import RouteHandler, RouteSelector, StateT
 
 # Auth
 from .oauth import (

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

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from ._route_list import _RouteList
+from ._route import _Route, _agentic_selector
+from .route_rank import RouteRank
+
+__all__ = [
+    "_RouteList",
+    "_Route",
+    "RouteRank",
+    "_agentic_selector",
+]

microsoft_agents/hosting/core/app/_routes/_route.py

@@ -0,0 +1,89 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import Generic, Optional, TypeVar
+
+from ...turn_context import TurnContext
+from .._type_defs import RouteHandler, RouteSelector
+from ..state.turn_state import TurnState
+from .route_rank import RouteRank
+
+
+def _agentic_selector(selector: RouteSelector) -> RouteSelector:
+    def wrapped_selector(context: TurnContext) -> bool:
+        return context.activity.is_agentic_request() and selector(context)
+
+    return wrapped_selector
+
+
+StateT = TypeVar("StateT", bound=TurnState)
+
+
+class _Route(Generic[StateT]):
+    selector: RouteSelector
+    handler: RouteHandler[StateT]
+    _is_invoke: bool
+    _rank: int
+    auth_handlers: list[str]
+    _is_agentic: bool
+
+    def __init__(
+        self,
+        selector: RouteSelector,
+        handler: RouteHandler[StateT],
+        is_invoke: bool = False,
+        rank: int = RouteRank.DEFAULT,
+        auth_handlers: Optional[list[str]] = None,
+        is_agentic: bool = False,
+        **kwargs,
+    ) -> None:
+
+        if rank < 0 or rank > RouteRank.LAST:
+            raise ValueError(
+                "Route rank must be between 0 and RouteRank.LAST (inclusive)"
+            )
+
+        self.selector = selector
+        self.handler = handler
+        self._is_invoke = is_invoke
+        self._rank = int(rank)  # conversion from RouteRank IntEnum if necessary
+        self._is_agentic = is_agentic
+        self.auth_handlers = auth_handlers or []
+
+    @property
+    def is_invoke(self) -> bool:
+        return self._is_invoke
+
+    @property
+    def rank(self) -> int:
+        return self._rank
+
+    @property
+    def is_agentic(self) -> bool:
+        return self._is_agentic
+
+    @property
+    def priority(self) -> list[int]:
+        """Lower "values" indicate higher priority.
+
+        Priority is determined by:
+        1. Whether the route is for an invoke activity (0) or not (1).
+        2. Whether the route is agentic (0) or not (1).
+        3. The rank of the route (lower numbers indicate higher priority).
+
+        In that order. If both are invokes, the agentic one has higher priority.
+        If both are agentic and invokes, then the rank determines priority.
+
+        priority is represented as a list of three integers for easy lexicographic comparison.
+        """
+        return [
+            0 if self._is_invoke else 1,
+            0 if self._is_agentic else 1,
+            self._rank,
+        ]
+
+    def __lt__(self, other: _Route) -> bool:
+        # built-in list ordering is a lexicographic comparison in Python
+        return self.priority < other.priority

microsoft_agents/hosting/core/app/_routes/_route_list.py

@@ -0,0 +1,32 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+import heapq
+from typing import Generic, TypeVar
+
+from ..state.turn_state import TurnState
+from ._route import _Route
+
+StateT = TypeVar("StateT", bound=TurnState)
+
+
+class _RouteList(Generic[StateT]):
+    _routes: list[_Route[StateT]]
+
+    def __init__(
+        self,
+    ) -> None:
+        # a min-heap where lower "values" indicate higher priority
+        self._routes = []
+
+    def add_route(self, route: _Route[StateT]) -> None:
+        """Adds a route to the list."""
+        heapq.heappush(self._routes, route)
+
+    def __iter__(self):
+        # sorted will return a new list, leaving the heap intact
+        # returning an iterator over the previous list would expose
+        # internal details
+        return iter(sorted(self._routes))

microsoft_agents/hosting/core/app/_routes/route_rank.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import IntEnum
+
+_MAX_RANK = 2**16 - 1  # 65,535
+
+
+class RouteRank(IntEnum):
+    """Defines the rank of a route. Lower values indicate higher priority."""
+
+    FIRST = 0
+    DEFAULT = _MAX_RANK // 2
+    LAST = _MAX_RANK

microsoft_agents/hosting/core/app/_type_defs.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Callable, TypeVar, Awaitable, Protocol
+
+from ..turn_context import TurnContext
+from .state import TurnState
+
+RouteSelector = Callable[[TurnContext], bool]
+
+StateT = TypeVar("StateT", bound=TurnState)
+
+
+class RouteHandler(Protocol[StateT]):
+    def __call__(self, context: TurnContext, state: StateT) -> Awaitable[None]: ...