microsoft-agents-activity 0.4.0.dev18__py3-none-any.whl → 0.5.0__py3-none-any.whl

microsoft_agents/activity/__init__.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from .action_types import ActionTypes
 from .activity import Activity
@@ -17,6 +20,8 @@ from .card_action import CardAction
 from .card_image import CardImage
 from .channels import Channels
 from .channel_account import ChannelAccount
+from ._channel_id_field_mixin import _ChannelIdFieldMixin
+from .channel_id import ChannelId
 from .conversation_account import ConversationAccount
 from .conversation_members import ConversationMembers
 from .conversation_parameters import ConversationParameters
@@ -26,6 +31,7 @@ from .conversations_result import ConversationsResult
 from .expected_replies import ExpectedReplies
 from .entity import (
     Entity,
+    EntityTypes,
     AIEntity,
     ClientCitation,
     ClientCitationAppearance,
@@ -36,6 +42,7 @@ from .entity import (
     SensitivityPattern,
     GeoCoordinates,
     Place,
+    ProductInfo,
     Thing,
 )
 from .error import Error
@@ -62,6 +69,7 @@ from .thumbnail_url import ThumbnailUrl
 from .token_exchange_invoke_request import TokenExchangeInvokeRequest
 from .token_exchange_invoke_response import TokenExchangeInvokeResponse
 from .token_exchange_state import TokenExchangeState
+from .token_or_sign_in_resource_response import TokenOrSignInResourceResponse
 from .token_request import TokenRequest
 from .token_response import TokenResponse
 from .token_status import TokenStatus
@@ -114,6 +122,8 @@ __all__ = [
     "CardImage",
     "Channels",
     "ChannelAccount",
+    "ChannelId",
+    "_ChannelIdFieldMixin",
     "ConversationAccount",
     "ConversationMembers",
     "ConversationParameters",
@@ -144,6 +154,7 @@ __all__ = [
     "OAuthCard",
     "PagedMembersResult",
     "Place",
+    "ProductInfo",
     "ReceiptCard",
     "ReceiptItem",
     "ResourceResponse",
@@ -185,4 +196,5 @@ __all__ = [
     "load_configuration_from_env",
     "ChannelAdapterProtocol",
     "TurnContextProtocol",
+    "TokenOrSignInResourceResponse",
 ]

microsoft_agents/activity/_channel_id_field_mixin.py

@@ -0,0 +1,96 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+import logging
+from typing import Optional, Any
+
+from pydantic import (
+    ModelWrapValidatorHandler,
+    SerializerFunctionWrapHandler,
+    computed_field,
+    model_validator,
+    model_serializer,
+)
+
+from .channel_id import ChannelId
+
+logger = logging.getLogger(__name__)
+
+
+# can be generalized in the future, if needed
+class _ChannelIdFieldMixin:
+    """A mixin to add a computed field channel_id of type ChannelId to a Pydantic model."""
+
+    _channel_id: Optional[ChannelId] = None
+
+    # required to define the setter below
+    @computed_field(return_type=Optional[ChannelId], alias="channelId")
+    @property
+    def channel_id(self) -> Optional[ChannelId]:
+        """Gets the _channel_id field"""
+        return self._channel_id
+
+    # necessary for backward compatibility
+    # previously, channel_id was directly assigned with strings
+    @channel_id.setter
+    def channel_id(self, value: Any):
+        """Sets the channel_id after validating it as a ChannelId model."""
+        if isinstance(value, ChannelId):
+            self._channel_id = value
+        elif isinstance(value, str):
+            self._channel_id = ChannelId(value)
+        else:
+            raise ValueError(
+                f"Invalid type for channel_id: {type(value)}. "
+                "Expected ChannelId or str."
+            )
+
+    def _set_validated_channel_id(self, data: Any) -> None:
+        """Sets the channel_id after validating it as a ChannelId model."""
+        if "channelId" in data:
+            self.channel_id = data["channelId"]
+        elif "channel_id" in data:
+            self.channel_id = data["channel_id"]
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def _validate_channel_id(
+        cls, data: Any, handler: ModelWrapValidatorHandler
+    ) -> _ChannelIdFieldMixin:
+        """Validate the _channel_id field after model initialization.
+
+        :return: The model instance itself.
+        """
+        try:
+            model = handler(data)
+            model._set_validated_channel_id(data)
+            return model
+        except Exception:
+            logging.error("Model %s failed to validate with data %s", cls, data)
+            raise
+
+    def _remove_serialized_unset_channel_id(
+        self, serialized: dict[str, object]
+    ) -> None:
+        """Remove the _channel_id field if it is not set."""
+        if not self._channel_id:
+            if "channelId" in serialized:
+                del serialized["channelId"]
+            elif "channel_id" in serialized:
+                del serialized["channel_id"]
+
+    @model_serializer(mode="wrap")
+    def _serialize_channel_id(
+        self, handler: SerializerFunctionWrapHandler
+    ) -> dict[str, object]:
+        """Serialize the model using Pydantic's standard serialization.
+
+        :param handler: The serialization handler provided by Pydantic.
+        :return: A dictionary representing the serialized model.
+        """
+        serialized = handler(self)
+        if self:  # serialization can be called with None
+            self._remove_serialized_unset_channel_id(serialized)
+        return serialized

microsoft_agents/activity/_load_configuration.py

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

microsoft_agents/activity/_model_utils.py

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

microsoft_agents/activity/_type_aliases.py

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

microsoft_agents/activity/action_types.py

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

microsoft_agents/activity/activity.py

@@ -1,7 +1,24 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+import logging
 from copy import copy
 from datetime import datetime, timezone
-from typing import Optional
-from pydantic import Field, SerializeAsAny
+from typing import Optional, Any
+
+from pydantic import (
+    Field,
+    SerializeAsAny,
+    model_serializer,
+    model_validator,
+    SerializerFunctionWrapHandler,
+    ModelWrapValidatorHandler,
+    computed_field,
+    ValidationError,
+)
+
 from .activity_types import ActivityTypes
 from .channel_account import ChannelAccount
 from .conversation_account import ConversationAccount
@@ -11,9 +28,11 @@ from .suggested_actions import SuggestedActions
 from .attachment import Attachment
 from .entity import (
     Entity,
+    EntityTypes,
     Mention,
     AIEntity,
     ClientCitation,
+    ProductInfo,
     SensitivityUsageInfo,
 )
 from .conversation_reference import ConversationReference
@@ -21,12 +40,16 @@ from .text_highlight import TextHighlight
 from .semantic_action import SemanticAction
 from .agents_model import AgentsModel
 from .role_types import RoleTypes
+from ._channel_id_field_mixin import _ChannelIdFieldMixin
+from .channel_id import ChannelId
 from ._model_utils import pick_model, SkipNone
 from ._type_aliases import NonEmptyString
 
+logger = logging.getLogger(__name__)
+
 
 # TODO: A2A Agent 2 is responding with None as id, had to mark it as optional (investigate)
-class Activity(AgentsModel):
+class Activity(AgentsModel, _ChannelIdFieldMixin):
     """An Activity is the basic communication type for the protocol.
 
     :param type: Contains the activity type. Possible values include:
@@ -47,8 +70,8 @@ class Activity(AgentsModel):
     :type local_timezone: str
     :param service_url: Contains the URL that specifies the channel's service endpoint. Set by the channel.
     :type service_url: str
-    :param channel_id: Contains an ID that uniquely identifies the channel. Set by the channel.
-    :type channel_id: str
+    :param channel_id: Contains an ID that uniquely identifies the channel (and possibly the sub-channel). Set by the channel.
+    :type channel_id: ~microsoft_agents.activity.ChannelId
     :param from_property: Identifies the sender of the message.
     :type from_property: ~microsoft_agents.activity.ChannelAccount
     :param conversation: Identifies the conversation to which the activity belongs.
@@ -133,7 +156,6 @@ class Activity(AgentsModel):
     local_timestamp: datetime = None
     local_timezone: NonEmptyString = None
     service_url: NonEmptyString = None
-    channel_id: NonEmptyString = None
     from_property: ChannelAccount = Field(None, alias="from")
     conversation: ConversationAccount = None
     recipient: ChannelAccount = None
@@ -170,6 +192,99 @@ class Activity(AgentsModel):
     semantic_action: SemanticAction = None
     caller_id: NonEmptyString = None
 
+    @model_validator(mode="wrap")
+    @classmethod
+    def _validate_channel_id(
+        cls, data: Any, handler: ModelWrapValidatorHandler[Activity]
+    ) -> Activity:
+        """Validate the Activity, ensuring consistency between channel_id.sub_channel and productInfo entity.
+
+        :param data: The input data to validate.
+        :param handler: The validation handler provided by Pydantic.
+        :return: The validated Activity instance.
+        """
+        try:
+            # run Pydantic's standard validation first
+            activity = handler(data)
+
+            # needed to assign to a computed field
+            # needed because we override the mixin validator
+            activity._set_validated_channel_id(data)
+
+            # sync sub_channel with productInfo entity
+            product_info = activity.get_product_info_entity()
+            if product_info and activity.channel_id:
+                if (
+                    activity.channel_id.sub_channel
+                    and activity.channel_id.sub_channel != product_info.id
+                ):
+                    raise Exception(
+                        "Conflict between channel_id.sub_channel and productInfo entity"
+                    )
+                activity.channel_id = ChannelId(
+                    channel=activity.channel_id.channel,
+                    sub_channel=product_info.id,
+                )
+
+            return activity
+        except ValidationError as exc:
+            logger.error("Validation error for Activity: %s", exc, exc_info=True)
+            raise
+
+    @model_serializer(mode="wrap")
+    def _serialize_sub_channel_data(
+        self, handler: SerializerFunctionWrapHandler
+    ) -> dict[str, object]:
+        """Serialize the Activity, ensuring consistency between channel_id.sub_channel and productInfo entity.
+
+        :param handler: The serialization handler provided by Pydantic.
+        :return: A dictionary representing the serialized Activity.
+        """
+
+        # run Pydantic's standard serialization first
+        serialized = handler(self)
+        if not self:  # serialization can be called with None
+            return serialized
+
+        # find the ProductInfo entity
+        product_info = None
+        for i, entity in enumerate(serialized.get("entities") or []):
+            if entity.get("type", "") == EntityTypes.PRODUCT_INFO:
+                product_info = entity
+                break
+
+        # self.channel_id is the source of truth for serialization
+        if self.channel_id and self.channel_id.sub_channel:
+            if product_info and product_info.get("id") != self.channel_id.sub_channel:
+                raise Exception(
+                    "Conflict between channel_id.sub_channel and productInfo entity"
+                )
+            elif not product_info:
+                if not serialized.get("entities"):
+                    serialized["entities"] = []
+                serialized["entities"].append(
+                    {
+                        "type": EntityTypes.PRODUCT_INFO,
+                        "id": self.channel_id.sub_channel,
+                    }
+                )
+
+            # simply serialized channelId value in Activity and relatesTo
+            if "channelId" in serialized:
+                serialized["channelId"] = self.channel_id.channel
+            elif "channel_id" in serialized:
+                serialized["channel_id"] = self.channel_id.channel
+
+        elif product_info:  # remove productInfo entity if sub_channel is not set
+            del serialized["entities"][i]
+            if not serialized["entities"]:  # after removal above, list may be empty
+                del serialized["entities"]
+
+        # necessary due to computed_field serialization
+        self._remove_serialized_unset_channel_id(serialized)
+
+        return serialized
+
     def apply_conversation_reference(
         self, reference: ConversationReference, is_incoming: bool = False
     ):
@@ -528,6 +643,14 @@ class Activity(AgentsModel):
             service_url=self.service_url,
         )
 
+    def get_product_info_entity(self) -> Optional[ProductInfo]:
+        if not self.entities:
+            return None
+        target = EntityTypes.PRODUCT_INFO.lower()
+        # validated entities can be Entity, and that prevents us from
+        # making assumptions about the casing of the 'type' attribute
+        return next(filter(lambda e: e.type.lower() == target, self.entities), None)
+
     def get_mentions(self) -> list[Mention]:
         """
         Resolves the mentions from the entities of this activity.
@@ -540,7 +663,7 @@ class Activity(AgentsModel):
         """
         if not self.entities:
             return []
-        return [x for x in self.entities if x.type.lower() == "mention"]
+        return [x for x in self.entities if x.type.lower() == EntityTypes.MENTION]
 
     def get_reply_conversation_reference(
         self, reply: ResourceResponse
@@ -661,7 +784,7 @@ class Activity(AgentsModel):
         return self.recipient.agentic_app_id
 
     def get_agentic_user(self) -> Optional[str]:
-        """Gets the agentic user (UPN) from the context if it's an agentic request."""
+        """Gets the agentic user (agenticUserId) from the context if it's an agentic request."""
         if not self.is_agentic_request() or not self.recipient:
             return None
-        return self.recipient.id
+        return self.recipient.agentic_user_id

microsoft_agents/activity/activity_event_names.py

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

microsoft_agents/activity/activity_importance.py

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

microsoft_agents/activity/activity_types.py

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

microsoft_agents/activity/adaptive_card_invoke_action.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString
 

microsoft_agents/activity/adaptive_card_invoke_response.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString
 

microsoft_agents/activity/adaptive_card_invoke_value.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .adaptive_card_invoke_action import AdaptiveCardInvokeAction
 from .token_exchange_invoke_request import TokenExchangeInvokeRequest
 from .agents_model import AgentsModel

microsoft_agents/activity/agents_model.py

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

microsoft_agents/activity/animation_card.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .thumbnail_url import ThumbnailUrl
 from .media_url import MediaUrl
 from .card_action import CardAction

microsoft_agents/activity/attachment.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString
 

microsoft_agents/activity/attachment_data.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString
 

microsoft_agents/activity/attachment_info.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .attachment_view import AttachmentView
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString

microsoft_agents/activity/attachment_layout_types.py

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

microsoft_agents/activity/attachment_view.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString
 

microsoft_agents/activity/audio_card.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from .thumbnail_url import ThumbnailUrl
 from .media_url import MediaUrl

microsoft_agents/activity/basic_card.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from .card_image import CardImage
 from .card_action import CardAction

microsoft_agents/activity/caller_id_constants.py

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

microsoft_agents/activity/card_action.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from typing import Optional
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString

microsoft_agents/activity/card_image.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .card_action import CardAction
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString

microsoft_agents/activity/channel_account.py

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

microsoft_agents/activity/channel_adapter_protocol.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, List, Callable, Awaitable, Optional
 

microsoft_agents/activity/channel_id.py

@@ -0,0 +1,95 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import Optional, Any
+
+from pydantic_core import CoreSchema, core_schema
+from pydantic import GetCoreSchemaHandler
+
+
+class ChannelId(str):
+    """A ChannelId represents a channel and optional sub-channel in the format 'channel:sub_channel'."""
+
+    def __init__(
+        self,
+        value: Optional[str] = None,
+        *,
+        channel: Optional[str] = None,
+        sub_channel: Optional[str] = None,
+    ) -> None:
+        """Initialize a ChannelId instance.
+
+        :param value: The full channel ID string in the format 'channel:sub_channel'. Must be provided if channel is not provided.
+        :param channel: The main channel string. Must be provided if value is not provided.
+        :param sub_channel: The sub-channel string.
+        :raises ValueError: If the input parameters are invalid. value and channel cannot both be provided.
+        """
+        super().__init__()
+        if not channel:
+            split = self.strip().split(":", 1)
+            self._channel = split[0].strip()
+            self._sub_channel = split[1].strip() if len(split) == 2 else None
+        else:
+            self._channel = channel
+            self._sub_channel = sub_channel
+
+    def __new__(
+        cls,
+        value: Optional[str] = None,
+        *,
+        channel: Optional[str] = None,
+        sub_channel: Optional[str] = None,
+    ) -> ChannelId:
+        """Create a new ChannelId instance.
+
+        :param value: The full channel ID string in the format 'channel:sub_channel'. Must be provided if channel is not provided.
+        :param channel: The main channel string. Must be provided if value is not provided. Must not contain ':', as it delimits channels and sub channels.
+        :param sub_channel: The sub-channel string.
+        :return: A new ChannelId instance.
+        :raises ValueError: If the input parameters are invalid. value and channel cannot both be provided.
+        """
+        if isinstance(value, str):
+            if channel or sub_channel:
+                raise ValueError(
+                    "If value is provided, channel and sub_channel must be None"
+                )
+
+            value = value.strip()
+            if value:
+                return str.__new__(cls, value)
+            raise TypeError("value must be a non empty string if provided")
+        else:
+            if (
+                not isinstance(channel, str)
+                or len(channel.strip()) == 0
+                or ":" in channel
+            ):
+                raise TypeError(
+                    "channel must be a non empty string, and must not contain the ':' character"
+                )
+            if sub_channel is not None and (not isinstance(sub_channel, str)):
+                raise TypeError("sub_channel must be a string if provided")
+            channel = channel.strip()
+            sub_channel = sub_channel.strip() if sub_channel else None
+            if sub_channel:
+                return str.__new__(cls, f"{channel}:{sub_channel}")
+            return str.__new__(cls, channel)
+
+    @property
+    def channel(self) -> str:
+        """The main channel, e.g. 'email' in 'email:work'."""
+        return self._channel  # type: ignore[return-value]
+
+    @property
+    def sub_channel(self) -> Optional[str]:
+        """The sub-channel, e.g. 'work' in 'email:work'. May be None."""
+        return self._sub_channel
+
+    # https://docs.pydantic.dev/dev/concepts/types/#customizing-validation-with-__get_pydantic_core_schema__
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        return core_schema.no_info_after_validator_function(cls, handler(str))

microsoft_agents/activity/channels.py

@@ -74,7 +74,7 @@ class Channels(str, Enum):
 
         Args:
             channel_id (str): The Channel to check the if Suggested Actions are supported in.
-            button_cnt (int, optional): Defaults to 100. The number of Suggested Actions to check for the Channel.
+            button_cnt (int, Optional): Defaults to 100. The number of Suggested Actions to check for the Channel.
 
         Returns:
             bool: True if the Channel supports the button_cnt total Suggested Actions, False if the Channel does not
@@ -107,7 +107,7 @@ class Channels(str, Enum):
 
         Args:
             channel_id (str): The Channel to check if the Card Actions are supported in.
-            button_cnt (int, optional): Defaults to 100. The number of Card Actions to check for the Channel.
+            button_cnt (int, Optional): Defaults to 100. The number of Card Actions to check for the Channel.
 
         Returns:
             bool: True if the Channel supports the button_cnt total Card Actions, False if the Channel does not support