Extension support and starter sample

libraries/microsoft-agents-activity/microsoft_agents/activity/_type_aliases.py

@@ -1,5 +1,4 @@
 from typing import Annotated
 from pydantic import StringConstraints
 
-
 NonEmptyString = Annotated[str, StringConstraints(min_length=1)]

libraries/microsoft-agents-activity/microsoft_agents/activity/activity.py

@@ -429,7 +429,6 @@ def create_reply(self, text: str = None, locale: str = None):
     def create_trace(
         self, name: str, value: object = None, value_type: str = None, label: str = None
     ):
-        # robrandao: TODO -> needs to handle Nones like create_reply
         """
         Creates a new trace activity based on this activity.
 
@@ -476,7 +475,6 @@ def create_trace(
     def create_trace_activity(
         name: str, value: object = None, value_type: str = None, label: str = None
     ):
-        # robrandao: TODO -> SkipNone
         """
         Creates an instance of the :class:`Activity` class as a TraceActivity object.
 

libraries/microsoft-agents-authentication-msal/microsoft_agents/authentication/msal/msal_auth.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from __future__ import annotations
 
 import logging

libraries/microsoft-agents-authentication-msal/microsoft_agents/authentication/msal/msal_connection_manager.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 import re
 from typing import Dict, List, Optional
 from microsoft_agents.hosting.core import (

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

@@ -11,12 +11,13 @@
 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

libraries/microsoft-agents-hosting-core/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

libraries/microsoft-agents-hosting-core/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

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

@@ -10,8 +10,9 @@
 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 (

libraries/microsoft-agents-hosting-core/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",
+]

libraries/microsoft-agents-hosting-core/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

libraries/microsoft-agents-hosting-core/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))

libraries/microsoft-agents-hosting-core/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

libraries/microsoft-agents-hosting-core/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]: ...