microsoft-agents-hosting-dialogs 0.10.0.dev2__py3-none-any.whl

microsoft_agents/hosting/dialogs/__init__.py

@@ -0,0 +1,76 @@
+# coding=utf-8
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+__version__ = "0.0.0"
+
+from .component_dialog import ComponentDialog
+from .dialog_container import DialogContainer
+from .dialog_context import DialogContext
+from .models.dialog_event import DialogEvent
+from .models.dialog_events import DialogEvents
+from .models.dialog_instance import DialogInstance
+from .models.dialog_reason import DialogReason
+from .dialog_set import DialogSet
+from .dialog_state import DialogState
+from .models.dialog_turn_result import DialogTurnResult
+from .models.dialog_turn_status import DialogTurnStatus
+from .dialog_manager import DialogManager
+from .dialog_manager_result import DialogManagerResult
+from .dialog import Dialog
+from .dialog_component_registration import DialogsComponentRegistration
+from .persisted_state_keys import PersistedStateKeys
+from .persisted_state import PersistedState
+from .waterfall_dialog import WaterfallDialog
+from .waterfall_step_context import WaterfallStepContext
+from .dialog_extensions import DialogExtensions
+from .prompts import *
+from .choices import *
+from .object_path import ObjectPath
+from .models import (
+    DialogEvent,
+    DialogEvents,
+    DialogInstance,
+    DialogReason,
+    DialogTurnResult,
+    DialogTurnStatus,
+)
+
+__all__ = [
+    "ComponentDialog",
+    "DialogContainer",
+    "DialogContext",
+    "DialogEvent",
+    "DialogEvents",
+    "DialogInstance",
+    "DialogReason",
+    "DialogSet",
+    "DialogState",
+    "DialogTurnResult",
+    "DialogTurnStatus",
+    "DialogManager",
+    "DialogManagerResult",
+    "Dialog",
+    "DialogsComponentRegistration",
+    "WaterfallDialog",
+    "WaterfallStepContext",
+    "ConfirmPrompt",
+    "DateTimePrompt",
+    "DateTimeResolution",
+    "NumberPrompt",
+    "OAuthPrompt",
+    "OAuthPromptSettings",
+    "PersistedStateKeys",
+    "PersistedState",
+    "PromptRecognizerResult",
+    "PromptValidatorContext",
+    "Prompt",
+    "PromptOptions",
+    "TextPrompt",
+    "DialogExtensions",
+    "ObjectPath",
+    "__version__",
+]

microsoft_agents/hosting/dialogs/_component_registration.py

@@ -0,0 +1,30 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import List
+
+
+class ComponentRegistration:
+    """
+    Simple component registration that allows dialogs and other components
+    to register memory scopes and path resolvers.
+    """
+
+    _components: List = []
+
+    @classmethod
+    def add(cls, component: object) -> None:
+        """
+        Register a component. Duplicate types are ignored.
+        :param component: The component instance to register.
+        """
+        if not any(type(c) == type(component) for c in cls._components):
+            cls._components.append(component)
+
+    @classmethod
+    def get_components(cls) -> List:
+        """
+        Gets all registered components.
+        :return: List of registered component instances.
+        """
+        return list(cls._components)

microsoft_agents/hosting/dialogs/_telemetry_client.py

@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+
+class AgentTelemetryClient:
+    """
+    Interface for telemetry logging. Override to send telemetry to a custom sink.
+    """
+
+    def track_event(
+        self,
+        name: str,
+        properties: dict[str, str] | None = None,
+        metrics: dict[str, float] | None = None,
+    ) -> None:
+        pass
+
+    def track_exception(
+        self,
+        exception: Exception,
+        properties: dict[str, str] | None = None,
+        measurements: dict[str, float] | None = None,
+    ) -> None:
+        pass
+
+    def track_dependency(
+        self,
+        name: str,
+        data: str | None = None,
+        type_name: str | None = None,
+        target: str | None = None,
+        duration: int | None = None,
+        success: bool = True,
+        result_code: str | None = None,
+        properties: dict[str, str] | None = None,
+    ) -> None:
+        pass
+
+    def flush(self) -> None:
+        pass
+
+
+class NullTelemetryClient(AgentTelemetryClient):
+    """
+    No-op telemetry client. All calls are silently discarded.
+    """
+
+    def track_event(
+        self,
+        name: str,
+        properties: dict[str, str] | None = None,
+        metrics: dict[str, float] | None = None,
+    ) -> None:
+        pass
+
+    def track_exception(
+        self,
+        exception: Exception,
+        properties: dict[str, str] | None = None,
+        measurements: dict[str, float] | None = None,
+    ) -> None:
+        pass
+
+    def track_dependency(
+        self,
+        name: str,
+        data: str | None = None,
+        type_name: str | None = None,
+        target: str | None = None,
+        duration: int | None = None,
+        success: bool = True,
+        result_code: str | None = None,
+        properties: dict[str, str] | None = None,
+    ) -> None:
+        pass
+
+    def flush(self) -> None:
+        pass

microsoft_agents/hosting/dialogs/choices/__init__.py

@@ -0,0 +1,38 @@
+# coding=utf-8
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+from .channel import Channel
+from .models.choice import Choice
+from .models.choice_factory_options import ChoiceFactoryOptions
+from .choice_factory import ChoiceFactory
+from .choice_recognizer import ChoiceRecognizers
+from .find import Find
+from .models.find_choices_options import FindChoicesOptions, FindValuesOptions
+from .models.found_choice import FoundChoice
+from .models.found_value import FoundValue
+from .models.list_style import ListStyle
+from .models.model_result import ModelResult
+from .models.sorted_value import SortedValue
+from .models.token import Token
+from .tokenizer import Tokenizer
+
+__all__ = [
+    "Channel",
+    "Choice",
+    "ChoiceFactory",
+    "ChoiceFactoryOptions",
+    "ChoiceRecognizers",
+    "Find",
+    "FindChoicesOptions",
+    "FindValuesOptions",
+    "FoundChoice",
+    "ListStyle",
+    "ModelResult",
+    "SortedValue",
+    "Token",
+    "Tokenizer",
+]

microsoft_agents/hosting/dialogs/choices/channel.py

@@ -0,0 +1,121 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.activity import Channels
+
+
+class Channel:
+    """
+    Methods for determining channel-specific functionality.
+    """
+
+    @staticmethod
+    def supports_suggested_actions(channel_id: str, 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.
+        """
+        if isinstance(channel_id, Channels):
+            channel_id = channel_id.value
+
+        max_actions = {
+            # https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies
+            Channels.facebook.value: 10,
+            Channels.skype.value: 10,
+            # https://developers.line.biz/en/reference/messaging-api/#items-object
+            Channels.line.value: 13,
+            # https://dev.kik.com/#/docs/messaging#text-response-object
+            Channels.kik.value: 20,
+            Channels.telegram.value: 100,
+            Channels.emulator.value: 100,
+            Channels.direct_line.value: 100,
+            Channels.direct_line_speech.value: 100,
+            Channels.webchat.value: 100,
+        }
+        return (
+            button_cnt <= max_actions[channel_id]
+            if channel_id in max_actions
+            else False
+        )
+
+    @staticmethod
+    def supports_card_actions(channel_id: str, 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.
+        """
+        if isinstance(channel_id, Channels):
+            channel_id = channel_id.value
+
+        max_actions = {
+            Channels.facebook.value: 3,
+            Channels.skype.value: 3,
+            Channels.ms_teams.value: 3,
+            Channels.line.value: 99,
+            Channels.slack.value: 100,
+            Channels.telegram.value: 100,
+            Channels.emulator.value: 100,
+            Channels.direct_line.value: 100,
+            Channels.direct_line_speech.value: 100,
+            Channels.webchat.value: 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 get_channel_id(turn_context: TurnContext) -> str:
+        """Get the channel ID from the TurnContext's activity.
+
+        Args:
+            turn_context (TurnContext): The current turn context.
+
+        Returns:
+            str: The channel ID, or an empty string if not set.
+        """
+        if turn_context.activity and turn_context.activity.channel_id:
+            return turn_context.activity.channel_id
+        return ""
+
+    @staticmethod
+    def max_action_title_length(  # pylint: disable=unused-argument
+        channel_id: str,
+    ) -> 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/hosting/dialogs/choices/choice_factory.py

@@ -0,0 +1,262 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from collections.abc import Iterable
+
+from microsoft_agents.hosting.core import CardFactory, MessageFactory
+from microsoft_agents.activity import (
+    ActionTypes,
+    Activity,
+    CardAction,
+    HeroCard,
+    InputHints,
+)
+
+from . import Channel, Choice, ChoiceFactoryOptions
+
+
+class ChoiceFactory:
+    """
+    Assists with formatting a message activity that contains a list of choices.
+    """
+
+    @staticmethod
+    def for_channel(
+        channel_id: str,
+        choices: Iterable[str | Choice],
+        text: str | None = None,
+        speak: str | None = None,
+        options: ChoiceFactoryOptions | None = None,
+    ) -> Activity:
+        """
+        Creates a message activity that includes a list of choices formatted based on the
+         capabilities of a given channel.
+
+        Parameters
+        ----------
+        channel_id: A channel ID.
+        choices: List of choices to render
+        text: (Optional) Text of the message to send.
+        speak (Optional) SSML. Text to be spoken by your bot on a speech-enabled channel.
+        """
+        if channel_id is None:
+            channel_id = ""
+
+        choice_list: list[Choice] = ChoiceFactory._to_choices(choices)
+
+        # Find maximum title length
+        max_title_length = 0
+        for choice in choice_list:
+            if choice.action is not None and choice.action.title not in (None, ""):
+                size = len(choice.action.title)
+            else:
+                size = len(choice.value) if choice.value is not None else 0
+
+            max_title_length = max(max_title_length, size)
+
+        # Determine list style
+        supports_suggested_actions = Channel.supports_suggested_actions(
+            channel_id, len(choice_list)
+        )
+        supports_card_actions = Channel.supports_card_actions(
+            channel_id, len(choice_list)
+        )
+        max_action_title_length = Channel.max_action_title_length(channel_id)
+        long_titles = max_title_length > max_action_title_length
+
+        if not long_titles and not supports_suggested_actions and supports_card_actions:
+            # SuggestedActions is the preferred approach, but for channels that don't
+            # support them (e.g. Teams, Cortana) we should use a HeroCard with CardActions
+            return ChoiceFactory.hero_card(choice_list, text, speak)
+        if not long_titles and supports_suggested_actions:
+            # We always prefer showing choices using suggested actions. If the titles are too long, however,
+            # we'll have to show them as a text list.
+            return ChoiceFactory.suggested_action(choice_list, text, speak)
+        if not long_titles and len(choice_list) <= 3:
+            # If the titles are short and there are 3 or less choices we'll use an inline list.
+            return ChoiceFactory.inline(choice_list, text, speak, options)
+        # Show a numbered list.
+        return ChoiceFactory.list_style(choice_list, text, speak, options)
+
+    @staticmethod
+    def inline(
+        choices: Iterable[str | Choice],
+        text: str | None = None,
+        speak: str | None = None,
+        options: ChoiceFactoryOptions | None = None,
+    ) -> Activity:
+        """
+        Creates a message activity that includes a list of choices formatted as an inline list.
+
+        Parameters
+        ----------
+        choices: The list of choices to render.
+        text: (Optional) The text of the message to send.
+        speak: (Optional) SSML. Text to be spoken by your bot on a speech-enabled channel.
+        options: (Optional) The formatting options to use to tweak rendering of list.
+        """
+        choice_list = ChoiceFactory._to_choices(choices)
+
+        if options is None:
+            options = ChoiceFactoryOptions()
+
+        opt = ChoiceFactoryOptions(
+            inline_separator=options.inline_separator or ", ",
+            inline_or=options.inline_or or " or ",
+            inline_or_more=options.inline_or_more or ", or ",
+            include_numbers=(
+                options.include_numbers if options.include_numbers is not None else True
+            ),
+        )
+
+        # Format list of choices
+        connector = ""
+        txt_builder: list[str] = []
+        if text is not None:
+            txt_builder.append(text)
+            txt_builder.append(" ")
+
+        for index, choice in enumerate(choice_list):
+            title = (
+                choice.action.title
+                if (choice.action is not None and choice.action.title is not None)
+                else choice.value
+            )
+            txt_builder.append(connector)
+            if opt.include_numbers is True:
+                txt_builder.append("(")
+                txt_builder.append(f"{index + 1}")
+                txt_builder.append(") ")
+
+            txt_builder.append(title or "title")
+            if index == (len(choice_list) - 2):
+                connector = opt.inline_or if index == 0 else opt.inline_or_more
+                connector = connector or ""
+            else:
+                connector = opt.inline_separator or ""
+
+        # Return activity with choices as an inline list.
+        return MessageFactory.text(
+            "".join(txt_builder), speak, InputHints.expecting_input
+        )
+
+    @staticmethod
+    def list_style(
+        choices: Iterable[str | Choice],
+        text: str | None = None,
+        speak: str | None = None,
+        options: ChoiceFactoryOptions | None = None,
+    ) -> Activity:
+        """
+        Creates a message activity that includes a list of choices formatted as a numbered or bulleted list.
+
+        Parameters
+        ----------
+
+        choices: The list of choices to render.
+
+        text: (Optional) The text of the message to send.
+
+        speak: (Optional) SSML. Text to be spoken by your bot on a speech-enabled channel.
+
+        options: (Optional) The formatting options to use to tweak rendering of list.
+        """
+        choices = ChoiceFactory._to_choices(choices)
+        if options is None:
+            options = ChoiceFactoryOptions()
+
+        if options.include_numbers is None:
+            include_numbers = True
+        else:
+            include_numbers = options.include_numbers
+
+        # Format list of choices
+        connector = ""
+        txt_builder: list[str] = []
+        if text:
+            txt_builder.append(text)
+            txt_builder.append("\n\n   ")
+
+        for index, choice in enumerate(choices):
+            title = (
+                choice.action.title
+                if choice.action is not None and choice.action.title is not None
+                else choice.value
+            )
+
+            txt_builder.append(connector)
+            if include_numbers:
+                txt_builder.append(f"{index + 1}")
+                txt_builder.append(". ")
+            else:
+                txt_builder.append("- ")
+
+            txt_builder.append(title)
+            connector = "\n   "
+
+        # Return activity with choices as a numbered list.
+        txt = "".join(txt_builder)
+        return MessageFactory.text(txt, speak, InputHints.expecting_input)
+
+    @staticmethod
+    def suggested_action(
+        choices: Iterable[Choice], text: str | None = None, speak: str | None = None
+    ) -> Activity:
+        """
+        Creates a message activity that includes a list of choices that have been added as suggested actions.
+        """
+        # Return activity with choices as suggested actions
+        return MessageFactory.suggested_actions(
+            ChoiceFactory._extract_actions(choices),
+            text,
+            speak,
+            InputHints.expecting_input,
+        )
+
+    @staticmethod
+    def hero_card(
+        choices: Iterable[Choice | str],
+        text: str | None = None,
+        speak: str | None = None,
+    ) -> Activity:
+        """
+        Creates a message activity that includes a lsit of coices that have been added as `HeroCard`'s
+        """
+        attachment = CardFactory.hero_card(
+            HeroCard(text=text or "", buttons=ChoiceFactory._extract_actions(choices))
+        )
+
+        # Return activity with choices as HeroCard with buttons
+        return MessageFactory.attachment(
+            attachment, None, speak, InputHints.expecting_input
+        )
+
+    @staticmethod
+    def _to_choices(choices: Iterable[str | Choice]) -> list[Choice]:
+        """
+        Takes a list of strings and returns them as [`Choice`].
+        """
+        if choices is None:
+            return []
+        return [
+            Choice(value=choice) if isinstance(choice, str) else choice
+            for choice in choices
+        ]
+
+    @staticmethod
+    def _extract_actions(choices: Iterable[str | Choice]) -> list[CardAction]:
+        if choices is None:
+            choices = []
+        choices = ChoiceFactory._to_choices(choices)
+        card_actions: list[CardAction] = []
+        for choice in choices:
+            if choice.action is not None:
+                card_action = choice.action
+            else:
+                card_action = CardAction(
+                    type=ActionTypes.im_back, value=choice.value, title=choice.value
+                )
+
+            card_actions.append(card_action)
+
+        return card_actions