microsoft-agents-hosting-core 0.4.0.dev18__py3-none-any.whl → 0.5.0.dev5__py3-none-any.whl

microsoft_agents/hosting/core/app/state/state.py

@@ -97,9 +97,10 @@ class State(dict[str, StoreItem], ABC):
         """
         Saves The State to Storage
 
-        Args:
-            context (TurnContext): the turn context.
-            storage (Optional[Storage]): storage to save to.
+        :param _context: the turn context.
+        :type _context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :param storage: storage to save to.
+        :type storage: Optional[:class:`microsoft_agents.hosting.core.storage.Storage`]
         """
 
         if not storage or self.__key__ == "":
@@ -126,13 +127,24 @@ class State(dict[str, StoreItem], ABC):
         """
         Loads The State from Storage
 
-        Args:
-            context: (TurnContext): the turn context.
-            storage (Optional[Storage]): storage to read from.
+        :param context: the turn context.
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :param storage: storage to read from.
+        :type storage: Optional[:class:`microsoft_agents.hosting.core.storage.Storage`]
+        :return: The loaded state instance.
+        :rtype: :class:`microsoft_agents.hosting.core.app.state.state.State`
         """
         return cls()
 
     def create_property(self, name: str) -> _StatePropertyAccessor:
+        """
+        Create a property accessor for the given name.
+
+        :param name: The name of the property.
+        :type name: str
+        :return: A state property accessor for the named property.
+        :rtype: :class:`microsoft_agents.hosting.core.state.state_property_accessor.StatePropertyAccessor`
+        """
         return StatePropertyAccessor(self, name)
 
     def __setitem__(self, key: str, item: Any) -> None:
@@ -180,6 +192,14 @@ class StatePropertyAccessor(_StatePropertyAccessor):
     _state: State
 
     def __init__(self, state: State, name: str) -> None:
+        """
+        Initialize the StatePropertyAccessor.
+
+        :param state: The state object to access properties from.
+        :type state: :class:`microsoft_agents.hosting.core.app.state.state.State`
+        :param name: The name of the property to access.
+        :type name: str
+        """
         self._name = name
         self._state = state
 
@@ -190,6 +210,16 @@ class StatePropertyAccessor(_StatePropertyAccessor):
             Union[Any, Callable[[], Optional[Any]]]
         ] = None,
     ) -> Optional[Any]:
+        """
+        Get the property value from the state.
+
+        :param turn_context: The turn context.
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :param default_value_or_factory: Default value or factory function to use if property doesn't exist.
+        :type default_value_or_factory: Optional[Union[Any, Callable[[], Optional[Any]]]]
+        :return: The property value or default value if not found.
+        :rtype: Optional[Any]
+        """
         value = self._state[self._name] if self._name in self._state else None
 
         if value is None and default_value_or_factory is not None:
@@ -201,7 +231,21 @@ class StatePropertyAccessor(_StatePropertyAccessor):
         return value
 
     async def delete(self, turn_context: TurnContext) -> None:
+        """
+        Delete the property from the state.
+
+        :param turn_context: The turn context.
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        """
         del self._state[self._name]
 
     async def set(self, turn_context: TurnContext, value: Any) -> None:
+        """
+        Set the property value in the state.
+
+        :param turn_context: The turn context.
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :param value: The value to set for the property.
+        :type value: Any
+        """
         self._state[self._name] = value

microsoft_agents/hosting/core/channel_adapter.py

@@ -40,7 +40,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         Sends a set of activities to the user. An array of responses from the server will be returned.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param activities: The activities to send.
         :type activities: list[Activity]
         :return:
@@ -53,7 +53,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         Replaces an existing activity.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param activity: New replacement activity.
         :type activity: :class:`microsoft_agents.activity.Activity`
         :return:
@@ -68,7 +68,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         Deletes an existing activity.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param reference: Conversation reference for the activity to delete.
         :type reference: :class:`microsoft_agents.activity.ConversationReference`
         :return:
@@ -102,7 +102,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         :param reference: A reference to the conversation to continue.
         :type reference: :class:`microsoft_agents.activity.ConversationReference`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
         :param claims_identity: A :class:`microsoft_agents.hosting.core.ClaimsIdentity` for the conversation.
         :type claims_identity: :class:`microsoft_agents.hosting.core.ClaimsIdentity`
         :param audience:A value signifying the recipient of the proactive message.
@@ -124,11 +124,11 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         to the user.
 
         :param claims_identity: A :class:`microsoft_agents.hosting.core.ClaimsIdentity` for the conversation.
-        :type claims_identity: :class:`microsoft_agents.hosting.core.ClaimsIdentity`
+        :type claims_identity: :class:`microsoft_agents.hosting.core.authorization.ClaimsIdentity`
         :param continuation_activity: The activity to send.
         :type continuation_activity: :class:`microsoft_agents.activity.Activity`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
         :param audience: A value signifying the recipient of the proactive message.
         :type audience: str
         """
@@ -155,9 +155,9 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         :param audience: A value signifying the recipient of the proactive message.
         :type audience: str
         :param conversation_parameters: The information to use to create the conversation
-        :type conversation_parameters: :class:`microsoft_agents.activity.models.ConversationParameters`
+        :type conversation_parameters: :class:`microsoft_agents.activity.ConversationParameters`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
 
         :raises: Exception - Not implemented or when the implementation fails.
 
@@ -222,7 +222,7 @@ class ChannelAdapter(ABC, ChannelAdapterProtocol):
         the end of the chain.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param callback: A callback method to run at the end of the pipeline.
         :type callback: Callable[[TurnContext], Awaitable]
         :return:

microsoft_agents/hosting/core/channel_service_adapter.py

@@ -44,12 +44,29 @@ class ChannelServiceAdapter(ChannelAdapter, ABC):
     _AGENT_CONNECTOR_CLIENT_KEY = "ConnectorClient"
 
     def __init__(self, channel_service_client_factory: ChannelServiceClientFactoryBase):
+        """
+        Initialize the ChannelServiceAdapter.
+
+        :param channel_service_client_factory: The factory for creating channel service clients.
+        :type channel_service_client_factory: :class:`microsoft_agents.hosting.core.channel_service_client_factory_base.ChannelServiceClientFactoryBase`
+        """
         super().__init__()
         self._channel_service_client_factory = channel_service_client_factory
 
     async def send_activities(
         self, context: TurnContext, activities: list[Activity]
     ) -> list[ResourceResponse]:
+        """
+        Send a list of activities to the conversation.
+
+        :param context: The turn context for this conversation turn.
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :param activities: The list of activities to send.
+        :type activities: list[:class:`microsoft_agents.activity.Activity`]
+        :return: List of resource responses for the sent activities.
+        :rtype: list[:class:`microsoft_agents.activity.ResourceResponse`]
+        :raises TypeError: If context or activities are None/invalid.
+        """
         if not context:
             raise TypeError("Expected TurnContext but got None instead")
 
@@ -102,6 +119,17 @@ class ChannelServiceAdapter(ChannelAdapter, ABC):
         return responses
 
     async def update_activity(self, context: TurnContext, activity: Activity):
+        """
+        Update an existing activity in the conversation.
+
+        :param context: The turn context for this conversation turn.
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :param activity: The activity to update.
+        :type activity: :class:`microsoft_agents.activity.Activity`
+        :return: Resource response for the updated activity.
+        :rtype: :class:`microsoft_agents.activity.ResourceResponse`
+        :raises TypeError: If context or activity are None/invalid.
+        """
         if not context:
             raise TypeError("Expected TurnContext but got None instead")
 
@@ -122,6 +150,15 @@ class ChannelServiceAdapter(ChannelAdapter, ABC):
     async def delete_activity(
         self, context: TurnContext, reference: ConversationReference
     ):
+        """
+        Delete an activity from the conversation.
+
+        :param context: The turn context for this conversation turn.
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :param reference: Reference to the conversation and activity to delete.
+        :type reference: :class:`microsoft_agents.activity.ConversationReference`
+        :raises TypeError: If context or reference are None/invalid.
+        """
         if not context:
             raise TypeError("Expected TurnContext but got None instead")
 
@@ -155,9 +192,9 @@ class ChannelServiceAdapter(ChannelAdapter, ABC):
             and is generally found in the `MicrosoftAppId` parameter in `config.py`.
         :type agent_app_id: str
         :param continuation_activity: The activity to continue the conversation with.
-        :type continuation_activity: Activity
+        :type continuation_activity: :class:`microsoft_agents.activity.Activity`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[:class:`microsoft_agents.hosting.core.turn_context.TurnContext`], Awaitable]
         """
         if not callable:
             raise TypeError(
@@ -182,6 +219,18 @@ class ChannelServiceAdapter(ChannelAdapter, ABC):
         callback: Callable[[TurnContext], Awaitable],
         audience: str = None,
     ):
+        """
+        Continue a conversation with the provided claims identity.
+
+        :param claims_identity: The claims identity for the conversation.
+        :type claims_identity: :class:`microsoft_agents.hosting.core.authorization.ClaimsIdentity`
+        :param continuation_activity: The activity to continue the conversation with.
+        :type continuation_activity: :class:`microsoft_agents.activity.Activity`
+        :param callback: The method to call for the resulting agent turn.
+        :type callback: Callable[[:class:`microsoft_agents.hosting.core.turn_context.TurnContext`], Awaitable]
+        :param audience: The audience for the conversation.
+        :type audience: Optional[str]
+        """
         return await self.process_proactive(
             claims_identity, continuation_activity, audience, callback
         )
@@ -299,14 +348,15 @@ class ChannelServiceAdapter(ChannelAdapter, ABC):
         """
         Creates a turn context and runs the middleware pipeline for an incoming activity.
 
-        :param auth_header: The HTTP authentication header of the request
-        :type auth_header: Union[str, AuthenticateRequestResult]
+        :param claims_identity: The claims identity of the agent.
+        :type claims_identity: :class:`microsoft_agents.hosting.core.authorization.ClaimsIdentity`
         :param activity: The incoming activity
-        :type activity: Activity
+        :type activity: :class:`microsoft_agents.activity.Activity`
         :param callback: The callback to execute at the end of the adapter's middleware pipeline.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[:class:`microsoft_agents.hosting.core.turn_context.TurnContext`], Awaitable]
 
         :return: A task that represents the work queued to execute.
+        :rtype: Optional[:class:`microsoft_agents.activity.InvokeResponse`]
 
         .. remarks::
             This class processes an activity received by the agents web server. This includes any messages
@@ -372,6 +422,14 @@ class ChannelServiceAdapter(ChannelAdapter, ABC):
         return self._process_turn_results(context)
 
     def create_claims_identity(self, agent_app_id: str = "") -> ClaimsIdentity:
+        """
+        Create a claims identity for the given agent app ID.
+
+        :param agent_app_id: The agent application ID.
+        :type agent_app_id: str
+        :return: A claims identity for the agent.
+        :rtype: :class:`microsoft_agents.hosting.core.authorization.ClaimsIdentity`
+        """
         return ClaimsIdentity(
             {
                 AuthenticationConstants.AUDIENCE_CLAIM: agent_app_id,

microsoft_agents/hosting/core/connector/client/user_token_client.py

@@ -8,7 +8,12 @@ from typing import Optional
 from aiohttp import ClientSession
 
 from microsoft_agents.hosting.core.connector import UserTokenClientBase
-from microsoft_agents.activity import TokenResponse, TokenStatus, SignInResource
+from microsoft_agents.activity import (
+    TokenOrSignInResourceResponse,
+    TokenResponse,
+    TokenStatus,
+    SignInResource,
+)
 from ..get_product_info import get_product_info
 from ..user_token_base import UserTokenBase
 from ..agent_sign_in_base import AgentSignInBase
@@ -110,15 +115,6 @@ class UserToken(UserTokenBase):
         channel_id: Optional[str] = None,
         code: Optional[str] = None,
     ) -> TokenResponse:
-        """
-        Gets a token for a user and connection.
-
-        :param user_id: ID of the user.
-        :param connection_name: Name of the connection to use.
-        :param channel_id: ID of the channel.
-        :param code: Optional authorization code.
-        :return: A token response.
-        """
         params = {"userId": user_id, "connectionName": connection_name}
 
         if channel_id:
@@ -137,6 +133,40 @@ class UserToken(UserTokenBase):
             data = await response.json()
             return TokenResponse.model_validate(data)
 
+    async def _get_token_or_sign_in_resource(
+        self,
+        user_id: str,
+        connection_name: str,
+        channel_id: str,
+        state: str,
+        code: str = "",
+        final_redirect: str = "",
+        fwd_url: str = "",
+    ) -> TokenOrSignInResourceResponse:
+
+        params = {
+            "userId": user_id,
+            "connectionName": connection_name,
+            "channelId": channel_id,
+            "state": state,
+            "code": code,
+            "finalRedirect": final_redirect,
+            "fwdUrl": fwd_url,
+        }
+
+        logger.info("Getting token or sign-in resource with params: %s", params)
+        async with self.client.get(
+            "/api/usertoken/GetTokenOrSignInResource", params=params
+        ) as response:
+            if response.status != 200:
+                logger.error(
+                    "Error getting token or sign-in resource: %s", response.status
+                )
+                response.raise_for_status()
+
+            data = await response.json()
+            return TokenOrSignInResourceResponse.model_validate(data)
+
     async def get_aad_tokens(
         self,
         user_id: str,
@@ -144,15 +174,6 @@ class UserToken(UserTokenBase):
         channel_id: Optional[str] = None,
         body: Optional[dict] = None,
     ) -> dict[str, TokenResponse]:
-        """
-        Gets Azure Active Directory tokens for a user and connection.
-
-        :param user_id: ID of the user.
-        :param connection_name: Name of the connection to use.
-        :param channel_id: ID of the channel.
-        :param body: An optional dictionary containing resource URLs.
-        :return: A dictionary of tokens.
-        """
         params = {"userId": user_id, "connectionName": connection_name}
 
         if channel_id:
@@ -175,13 +196,6 @@ class UserToken(UserTokenBase):
         connection_name: Optional[str] = None,
         channel_id: Optional[str] = None,
     ) -> None:
-        """
-        Signs the user out from the specified connection.
-
-        :param user_id: ID of the user.
-        :param connection_name: Name of the connection to use.
-        :param channel_id: ID of the channel.
-        """
         params = {"userId": user_id}
 
         if connection_name:
@@ -203,14 +217,6 @@ class UserToken(UserTokenBase):
         channel_id: Optional[str] = None,
         include: Optional[str] = None,
     ) -> list[TokenStatus]:
-        """
-        Gets token status for the user.
-
-        :param user_id: ID of the user.
-        :param channel_id: ID of the channel.
-        :param include: Optional filter.
-        :return: A list of token status objects.
-        """
         params = {"userId": user_id}
 
         if channel_id:
@@ -236,15 +242,6 @@ class UserToken(UserTokenBase):
         channel_id: str,
         body: Optional[dict] = None,
     ) -> TokenResponse:
-        """
-        Exchanges a token.
-
-        :param user_id: ID of the user.
-        :param connection_name: Name of the connection to use.
-        :param channel_id: ID of the channel.
-        :param body: An optional token exchange request body.
-        :return: A token response.
-        """
         params = {
             "userId": user_id,
             "connectionName": connection_name,

microsoft_agents/hosting/core/connector/user_token_base.py

@@ -1,10 +1,19 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from abc import abstractmethod
 from typing import Protocol
 
-from microsoft_agents.activity import TokenResponse, TokenStatus
+from microsoft_agents.activity import (
+    TokenResponse,
+    TokenStatus,
+    TokenOrSignInResourceResponse,
+)
 
 
 class UserTokenBase(Protocol):
+    """Base class for user token operations."""
+
     @abstractmethod
     async def get_token(
         self,
@@ -13,6 +22,40 @@ class UserTokenBase(Protocol):
         channel_id: str = None,
         code: str = None,
     ) -> TokenResponse:
+        """
+        Get sign-in URL.
+
+        :param state: State parameter for OAuth flow.
+        :param code_challenge: Code challenge for PKCE.
+        :param emulator_url: Emulator URL if used.
+        :param final_redirect: Final redirect URL.
+        :return: The sign-in URL.
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def _get_token_or_sign_in_resource(
+        self,
+        user_id: str,
+        connection_name: str,
+        channel_id: str,
+        state: str,
+        code: str = "",
+        final_redirect: str = "",
+        fwd_url: str = "",
+    ) -> TokenOrSignInResourceResponse:
+        """
+        Gets a token or a sign-in resource for a user and connection.
+
+        :param user_id: ID of the user.
+        :param connection_name: Name of the connection to use.
+        :param channel_id: ID of the channel.
+        :param state: State parameter for OAuth flow.
+        :param code: Optional authorization code.
+        :param final_redirect: Final redirect URL.
+        :param fwd_url: Forward URL.
+        :return: A token or sign-in resource response.
+        """
         raise NotImplementedError()
 
     @abstractmethod
@@ -23,22 +66,55 @@ class UserTokenBase(Protocol):
         channel_id: str = None,
         body: dict = None,
     ) -> dict[str, TokenResponse]:
+        """
+        Gets Azure Active Directory tokens for a user and connection.
+
+        :param user_id: ID of the user.
+        :param connection_name: Name of the connection to use.
+        :param channel_id: ID of the channel.
+        :param body: An optional dictionary containing resource URLs.
+        :return: A dictionary of tokens.
+        """
         raise NotImplementedError()
 
     @abstractmethod
     async def sign_out(
         self, user_id: str, connection_name: str = None, channel_id: str = None
     ) -> None:
+        """
+        Signs the user out from the specified connection.
+
+        :param user_id: ID of the user.
+        :param connection_name: Name of the connection to use.
+        :param channel_id: ID of the channel.
+        """
         raise NotImplementedError()
 
     @abstractmethod
     async def get_token_status(
         self, user_id: str, channel_id: str = None, include: str = None
     ) -> list[TokenStatus]:
+        """
+        Gets token status for the user.
+
+        :param user_id: ID of the user.
+        :param channel_id: ID of the channel.
+        :param include: Optional filter.
+        :return: A list of token status objects.
+        """
         raise NotImplementedError()
 
     @abstractmethod
     async def exchange_token(
         self, user_id: str, connection_name: str, channel_id: str, body: dict = None
     ) -> TokenResponse:
+        """
+        Exchanges a token.
+
+        :param user_id: ID of the user.
+        :param connection_name: Name of the connection to use.
+        :param channel_id: ID of the channel.
+        :param body: An optional token exchange request body.
+        :return: A token response.
+        """
         raise NotImplementedError()

microsoft_agents/hosting/core/connector/user_token_client_base.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from abc import abstractmethod
 from typing import Protocol