microsoft-agents-activity 0.7.0.dev0__py3-none-any.whl

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
+
+from microsoft_agents.activity.errors import activity_errors
+
+
+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(str(activity_errors.ChannelIdValueConflict))
+
+            value = value.strip()
+            if value:
+                return str.__new__(cls, value)
+            raise TypeError(str(activity_errors.ChannelIdValueMustBeNonEmpty))
+        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

@@ -0,0 +1,161 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import Enum
+from typing_extensions import Self
+
+
+class Channels(str, Enum):
+    """
+    Ids of channels supported by ABS.
+    """
+
+    """Agents channel."""
+    agents = "agents"
+
+    console = "console"
+    """Console channel."""
+
+    cortana = "cortana"
+    """Cortana channel."""
+
+    direct_line = "directline"
+    """Direct Line channel."""
+
+    direct_line_speech = "directlinespeech"
+    """Direct Line Speech channel."""
+
+    email = "email"
+    """Email channel."""
+
+    emulator = "emulator"
+    """Emulator channel."""
+
+    facebook = "facebook"
+    """Facebook channel."""
+
+    groupme = "groupme"
+    """Group Me channel."""
+
+    kik = "kik"
+    """Kik channel."""
+
+    line = "line"
+    """Line channel."""
+
+    ms_teams = "msteams"
+    """MS Teams channel."""
+
+    skype = "skype"
+    """Skype channel."""
+
+    skype_for_business = "skypeforbusiness"
+    """Skype for Business channel."""
+
+    slack = "slack"
+    """Slack channel."""
+
+    sms = "sms"
+    """SMS (Twilio) channel."""
+
+    telegram = "telegram"
+    """Telegram channel."""
+
+    test = "test"
+    """Test channel."""
+
+    webchat = "webchat"
+    """WebChat channel."""
+
+    # TODO: validate the need of Self annotations in the following methods
+    @staticmethod
+    def supports_suggested_actions(channel_id: Self, button_cnt: int = 100) -> bool:
+        """Determine if a number of Suggested Actions are supported by a Channel.
+
+        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.
+
+        Returns:
+            bool: True if the Channel supports the button_cnt total Suggested Actions, False if the Channel does not
+             support that number of Suggested Actions.
+        """
+
+        max_actions = {
+            # https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies
+            Channels.facebook: 10,
+            Channels.skype: 10,
+            # https://developers.line.biz/en/reference/messaging-api/#items-object
+            Channels.line: 13,
+            # https://dev.kik.com/#/docs/messaging#text-response-object
+            Channels.kik: 20,
+            Channels.telegram: 100,
+            Channels.emulator: 100,
+            Channels.direct_line: 100,
+            Channels.direct_line_speech: 100,
+            Channels.webchat: 100,
+        }
+        return (
+            button_cnt <= max_actions[channel_id]
+            if channel_id in max_actions
+            else False
+        )
+
+    @staticmethod
+    def supports_card_actions(channel_id: Self, button_cnt: int = 100) -> bool:
+        """Determine if a number of Card Actions are supported by a Channel.
+
+        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.
+
+        Returns:
+            bool: True if the Channel supports the button_cnt total Card Actions, False if the Channel does not support
+             that number of Card Actions.
+        """
+
+        max_actions = {
+            Channels.facebook: 3,
+            Channels.skype: 3,
+            Channels.ms_teams: 3,
+            Channels.line: 99,
+            Channels.slack: 100,
+            Channels.telegram: 100,
+            Channels.emulator: 100,
+            Channels.direct_line: 100,
+            Channels.direct_line_speech: 100,
+            Channels.webchat: 100,
+        }
+        return (
+            button_cnt <= max_actions[channel_id]
+            if channel_id in max_actions
+            else False
+        )
+
+    @staticmethod
+    def has_message_feed(_: str) -> bool:
+        """Determine if a Channel has a Message Feed.
+
+        Args:
+            channel_id (str): The Channel to check for Message Feed.
+
+        Returns:
+            bool: True if the Channel has a Message Feed, False if it does not.
+        """
+
+        return True
+
+    @staticmethod
+    def max_action_title_length(  # pylint: disable=unused-argument
+        channel_id: Self,
+    ) -> int:
+        """Maximum length allowed for Action Titles.
+
+        Args:
+            channel_id (str): The Channel to determine Maximum Action Title Length.
+
+        Returns:
+            int: The total number of characters allowed for an Action Title on a specific Channel.
+        """
+
+        return 20

microsoft_agents/activity/contact_relation_update_action_types.py

@@ -0,0 +1,9 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import Enum
+
+
+class ContactRelationUpdateActionTypes(str, Enum):
+    add = "add"
+    remove = "remove"

microsoft_agents/activity/conversation_account.py

@@ -0,0 +1,41 @@
+# 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
+
+
+class ConversationAccount(AgentsModel):
+    """Conversation account represents the identity of the conversation within a channel.
+
+    :param is_group: Indicates whether the conversation contains more than two
+     participants at the time the activity was generated
+    :type is_group: bool
+    :param conversation_type: Indicates the type of the conversation in
+     channels that distinguish between conversation types
+    :type conversation_type: str
+    :param id: Channel id for the user or agent on this channel (Example:
+     ``joe@smith.com``, or ``@joesmith`` or ``123456``)
+    :type id: str
+    :param name: Display friendly name
+    :type name: str
+    :param aad_object_id: This account's object ID within Azure Active
+     Directory (AAD)
+    :type aad_object_id: str
+    :param role: Role of the entity behind the account
+    :type role: str or ~microsoft_agents.activity.RoleTypes
+    :param tenant_id: This conversation's tenant ID
+    :type tenant_id: str
+    :param properties: This conversation's properties
+    :type properties: object
+    """
+
+    is_group: Optional[bool] = None
+    conversation_type: Optional[NonEmptyString] = None
+    id: NonEmptyString
+    name: Optional[NonEmptyString] = None
+    aad_object_id: Optional[NonEmptyString] = None
+    role: Optional[NonEmptyString] = None
+    tenant_id: Optional[NonEmptyString] = None
+    properties: object = None

microsoft_agents/activity/conversation_members.py

@@ -0,0 +1,19 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .channel_account import ChannelAccount
+from .agents_model import AgentsModel
+from ._type_aliases import NonEmptyString
+
+
+class ConversationMembers(AgentsModel):
+    """Conversation and its members.
+
+    :param id: Conversation ID
+    :type id: str
+    :param members: List of members in this conversation
+    :type members: list[~microsoft_agents.activity.ChannelAccount]
+    """
+
+    id: NonEmptyString = None
+    members: list[ChannelAccount] = None

microsoft_agents/activity/conversation_parameters.py

@@ -0,0 +1,40 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from pydantic import Field
+
+from .channel_account import ChannelAccount
+from .activity import Activity
+from .agents_model import AgentsModel
+from ._type_aliases import NonEmptyString
+
+
+class ConversationParameters(AgentsModel):
+    """Parameters for creating a new conversation.
+
+    :param is_group: IsGroup
+    :type is_group: bool
+    :param agent: The agent address for this conversation
+    :type agent: ~microsoft_agents.activity.ChannelAccount
+    :param members: Members to add to the conversation
+    :type members: list[~microsoft_agents.activity.ChannelAccount]
+    :param topic_name: (Optional) Topic of the conversation (if supported by
+     the channel)
+    :type topic_name: str
+    :param activity: (Optional) When creating a new conversation, use this
+     activity as the initial message to the conversation
+    :type activity: ~microsoft_agents.activity.Activity
+    :param channel_data: Channel specific payload for creating the
+     conversation
+    :type channel_data: object
+    :param tenant_id: (Optional) The tenant ID in which the conversation should be created
+    :type tenant_id: str
+    """
+
+    is_group: bool = None
+    agent: ChannelAccount = Field(None, alias="bot")
+    members: list[ChannelAccount] = None
+    topic_name: NonEmptyString = None
+    activity: Activity = None
+    channel_data: object = None
+    tenant_id: NonEmptyString = None

microsoft_agents/activity/conversation_reference.py

@@ -0,0 +1,69 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from uuid import uuid4 as uuid
+from typing import Optional
+import logging
+
+from pydantic import Field
+
+from .channel_account import ChannelAccount
+from ._channel_id_field_mixin import _ChannelIdFieldMixin
+from .channel_id import ChannelId
+from .conversation_account import ConversationAccount
+from .agents_model import AgentsModel
+from ._type_aliases import NonEmptyString
+from .activity_types import ActivityTypes
+from .activity_event_names import ActivityEventNames
+
+logger = logging.getLogger(__name__)
+
+
+class ConversationReference(AgentsModel, _ChannelIdFieldMixin):
+    """An object relating to a particular point in a conversation.
+
+    :param activity_id: (Optional) ID of the activity to refer to
+    :type activity_id: str
+    :param user: (Optional) User participating in this conversation
+    :type user: ~microsoft_agents.activity.ChannelAccount
+    :param agent: Agent participating in this conversation
+    :type agent: ~microsoft_agents.activity.ChannelAccount
+    :param conversation: Conversation reference
+    :type conversation: ~microsoft_agents.activity.ConversationAccount
+    :param channel_id: Channel ID
+    :type channel_id: ~microsoft_agents.activity.ChannelId
+    :param locale: A locale name for the contents of the text field.
+        The locale name is a combination of an ISO 639 two- or three-letter
+        culture code associated with a language and an ISO 3166 two-letter
+        subculture code associated with a country or region.
+        The locale name can also correspond to a valid BCP-47 language tag.
+    :type locale: str
+    :param service_url: Service endpoint where operations concerning the
+     referenced conversation may be performed
+    :type service_url: str
+    """
+
+    # optionals here are due to webchat
+    activity_id: Optional[NonEmptyString] = None
+    user: Optional[ChannelAccount] = None
+    agent: ChannelAccount = Field(None, alias="bot")
+    conversation: ConversationAccount
+    locale: Optional[NonEmptyString] = None
+    service_url: NonEmptyString = None
+
+    def get_continuation_activity(self) -> "Activity":  # type: ignore
+        from .activity import Activity
+
+        return Activity(
+            type=ActivityTypes.event,
+            name=ActivityEventNames.continue_conversation,
+            id=str(uuid()),
+            channel_id=self.channel_id,
+            service_url=self.service_url,
+            conversation=self.conversation,
+            recipient=self.agent,
+            from_property=self.user,
+            relates_to=self,
+        )

microsoft_agents/activity/conversation_resource_response.py

@@ -0,0 +1,22 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .agents_model import AgentsModel
+from ._type_aliases import NonEmptyString
+
+
+class ConversationResourceResponse(AgentsModel):
+    """A response containing a resource.
+
+    :param activity_id: ID of the Activity (if sent)
+    :type activity_id: str
+    :param service_url: Service endpoint where operations concerning the
+     conversation may be performed
+    :type service_url: str
+    :param id: Id of the resource
+    :type id: str
+    """
+
+    activity_id: NonEmptyString = None
+    service_url: NonEmptyString = None
+    id: NonEmptyString = None

microsoft_agents/activity/conversation_update_types.py

@@ -0,0 +1,18 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import Enum
+
+
+class ConversationUpdateTypes(str, Enum):
+    CHANNEL_CREATED = "channelCreated"
+    CHANNEL_RENAMED = "channelRenamed"
+    CHANNEL_DELETED = "channelDeleted"
+    CHANNEL_RESTORED = "channelRestored"
+    MEMBERS_ADDED = "membersAdded"
+    MEMBERS_REMOVED = "membersRemoved"
+    TEAM_RENAMED = "teamRenamed"
+    TEAM_DELETED = "teamDeleted"
+    TEAM_ARCHIVED = "teamArchived"
+    TEAM_UNARCHIVED = "teamUnarchived"
+    TEAM_RESTORED = "teamRestored"

microsoft_agents/activity/conversations_result.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .conversation_members import ConversationMembers
+from .agents_model import AgentsModel
+from ._type_aliases import NonEmptyString
+
+
+class ConversationsResult(AgentsModel):
+    """Conversations result.
+
+    :param continuation_token: Paging token
+    :type continuation_token: str
+    :param conversations: List of conversations
+    :type conversations:
+     list[~microsoft_agents.activity.ConversationMembers]
+    """
+
+    continuation_token: NonEmptyString = None
+    conversations: list[ConversationMembers] = None

microsoft_agents/activity/delivery_modes.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import Enum
+
+
+class DeliveryModes(str, Enum):
+    normal = "normal"
+    notification = "notification"
+    expect_replies = "expectReplies"
+    ephemeral = "ephemeral"
+    stream = "stream"

microsoft_agents/activity/end_of_conversation_codes.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import Enum
+
+
+class EndOfConversationCodes(str, Enum):
+    unknown = "unknown"
+    completed_successfully = "completedSuccessfully"
+    user_cancelled = "userCancelled"
+    timed_out = "botTimedOut"
+    issued_invalid_message = "botIssuedInvalidMessage"
+    channel_failed = "channelFailed"

microsoft_agents/activity/entity/__init__.py

@@ -0,0 +1,36 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .mention import Mention
+from .entity import Entity
+from .entity_types import EntityTypes
+from .ai_entity import (
+    ClientCitation,
+    ClientCitationAppearance,
+    ClientCitationImage,
+    ClientCitationIconName,
+    AIEntity,
+    SensitivityPattern,
+    SensitivityUsageInfo,
+)
+from .geo_coordinates import GeoCoordinates
+from .place import Place
+from .product_info import ProductInfo
+from .thing import Thing
+
+__all__ = [
+    "Entity",
+    "EntityTypes",
+    "AIEntity",
+    "ClientCitation",
+    "ClientCitationAppearance",
+    "ClientCitationImage",
+    "ClientCitationIconName",
+    "Mention",
+    "SensitivityUsageInfo",
+    "SensitivityPattern",
+    "GeoCoordinates",
+    "Place",
+    "ProductInfo",
+    "Thing",
+]

microsoft_agents/activity/entity/ai_entity.py

@@ -0,0 +1,111 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import Enum
+from typing import List, Optional, Union, Literal
+from dataclasses import dataclass
+
+from ..agents_model import AgentsModel
+from .entity import Entity
+
+
+class ClientCitationIconName(str, Enum):
+    """Enumeration of supported citation icon names."""
+
+    MICROSOFT_WORD = "Microsoft Word"
+    MICROSOFT_EXCEL = "Microsoft Excel"
+    MICROSOFT_POWERPOINT = "Microsoft PowerPoint"
+    MICROSOFT_ONENOTE = "Microsoft OneNote"
+    MICROSOFT_SHAREPOINT = "Microsoft SharePoint"
+    MICROSOFT_VISIO = "Microsoft Visio"
+    MICROSOFT_LOOP = "Microsoft Loop"
+    MICROSOFT_WHITEBOARD = "Microsoft Whiteboard"
+    ADOBE_ILLUSTRATOR = "Adobe Illustrator"
+    ADOBE_PHOTOSHOP = "Adobe Photoshop"
+    ADOBE_INDESIGN = "Adobe InDesign"
+    ADOBE_FLASH = "Adobe Flash"
+    SKETCH = "Sketch"
+    SOURCE_CODE = "Source Code"
+    IMAGE = "Image"
+    GIF = "GIF"
+    VIDEO = "Video"
+    SOUND = "Sound"
+    ZIP = "ZIP"
+    TEXT = "Text"
+    PDF = "PDF"
+
+
+class ClientCitationImage(AgentsModel):
+    """Information about the citation's icon."""
+
+    type: str = "ImageObject"
+    name: str = ""
+
+
+class SensitivityPattern(AgentsModel):
+    """Pattern information for sensitivity usage info."""
+
+    type: str = "DefinedTerm"
+    in_defined_term_set: str = ""
+    name: str = ""
+    term_code: str = ""
+
+
+class SensitivityUsageInfo(AgentsModel):
+    """
+    Sensitivity usage info for content sent to the user.
+    This is used to provide information about the content to the user.
+    """
+
+    type: str = "https://schema.org/Message"
+    schema_type: str = "CreativeWork"
+    description: Optional[str] = None
+    name: str = ""
+    position: Optional[int] = None
+    pattern: Optional[SensitivityPattern] = None
+
+
+class ClientCitationAppearance(AgentsModel):
+    """Appearance information for a client citation."""
+
+    type: str = "DigitalDocument"
+    name: str = ""
+    text: Optional[str] = None
+    url: Optional[str] = None
+    abstract: str = ""
+    encoding_format: Optional[str] = None
+    image: Optional[ClientCitationImage] = None
+    keywords: Optional[List[str]] = None
+    usage_info: Optional[SensitivityUsageInfo] = None
+
+
+class ClientCitation(AgentsModel):
+    """
+    Represents a Teams client citation to be included in a message.
+    See Bot messages with AI-generated content for more details.
+    https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bot-messages-ai-generated-content?tabs=before%2Cbotmessage
+    """
+
+    type: str = "Claim"
+    position: int = 0
+    appearance: Optional[ClientCitationAppearance] = None
+
+    def __post_init__(self):
+        if self.appearance is None:
+            self.appearance = ClientCitationAppearance()
+
+
+class AIEntity(Entity):
+    """Entity indicating AI-generated content."""
+
+    type: str = "https://schema.org/Message"
+    schema_type: str = "Message"
+    context: str = "https://schema.org"
+    id: str = ""
+    additional_type: Optional[List[str]] = None
+    citation: Optional[List[ClientCitation]] = None
+    usage_info: Optional[SensitivityUsageInfo] = None
+
+    def __post_init__(self):
+        if self.additional_type is None:
+            self.additional_type = ["AIGeneratedContent"]