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

microsoft_agents/hosting/dialogs/prompts/oauth_prompt_settings.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+class OAuthPromptSettings:
+    def __init__(
+        self,
+        connection_name: str,
+        title: str,
+        text: str | None = None,
+        timeout: int | None = None,
+        oauth_app_credentials=None,
+        end_on_invalid_message: bool = False,
+    ):
+        """
+        Settings used to configure an `OAuthPrompt` instance.
+         Parameters:
+            connection_name (str): Name of the OAuth connection being used.
+            title (str): The title of the cards signin button.
+            text (str): (Optional) additional text included on the signin card.
+            timeout (int): (Optional) number of milliseconds the prompt will wait for the user to authenticate.
+                `OAuthPrompt` defaults value to `900,000` ms (15 minutes).
+            oauth_app_credentials (AppCredentials): (Optional) AppCredentials to use for OAuth.  If None,
+            the Agent credentials are used.
+            end_on_invalid_message (bool): (Optional) value indicating whether the OAuthPrompt should end upon
+            receiving an invalid message.  Generally the OAuthPrompt will ignore incoming messages from the
+            user during the auth flow, if they are not related to the auth flow.  This flag enables ending the
+            OAuthPrompt rather than ignoring the user's message.  Typically, this flag will be set to 'true',
+            but is 'false' by default for backwards compatibility.
+        """
+        self.connection_name = connection_name
+        self.title = title
+        self.text = text
+        self.timeout = timeout
+        self.oauth_app_credentials = oauth_app_credentials
+        self.end_on_invalid_message = end_on_invalid_message
+
+    @property
+    def oath_app_credentials(self):
+        """Backward-compatible alias for the misspelled attribute name."""
+        return self.oauth_app_credentials
+
+    @oath_app_credentials.setter
+    def oath_app_credentials(self, value):
+        self.oauth_app_credentials = value

microsoft_agents/hosting/dialogs/prompts/prompt.py

@@ -0,0 +1,224 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from abc import abstractmethod
+import copy
+from typing import Any, Callable, Awaitable, cast
+
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.activity import InputHints, ActivityTypes, Activity
+
+from ..choices import (
+    Choice,
+    ChoiceFactory,
+    ChoiceFactoryOptions,
+    ListStyle,
+)
+from .prompt_options import PromptOptions
+from .prompt_recognizer_result import PromptRecognizerResult
+from .prompt_validator_context import PromptValidatorContext
+from ..models.dialog_reason import DialogReason
+from ..dialog import Dialog
+from ..models.dialog_instance import DialogInstance
+from ..models.dialog_turn_result import DialogTurnResult
+from ..dialog_context import DialogContext
+
+
+class Prompt(Dialog):
+    """
+    Defines the core behavior of prompt dialogs. Extends the Dialog base class.
+    """
+
+    ATTEMPT_COUNT_KEY = "AttemptCount"
+    persisted_options = "options"
+    persisted_state = "state"
+
+    def __init__(
+        self,
+        dialog_id: str,
+        validator: Callable[[PromptValidatorContext], Any] | None = None,
+    ):
+        """
+        Creates a new Prompt instance.
+        """
+        super(Prompt, self).__init__(dialog_id)
+        self._validator = validator
+
+    async def begin_dialog(
+        self, dialog_context: DialogContext, options: object = None
+    ) -> DialogTurnResult:
+        if not dialog_context:
+            raise TypeError("Prompt(): dc cannot be None.")
+        if not isinstance(options, PromptOptions):
+            raise TypeError("Prompt(): Prompt options are required for Prompt dialogs.")
+
+        # Ensure prompts have input hint set
+        if options.prompt is not None and not options.prompt.input_hint:
+            options.prompt.input_hint = InputHints.expecting_input
+
+        if options.retry_prompt is not None and not options.retry_prompt.input_hint:
+            options.retry_prompt.input_hint = InputHints.expecting_input
+
+        # Initialize prompt state
+        assert dialog_context.active_dialog is not None
+        state = dialog_context.active_dialog.state
+        state[self.persisted_options] = options
+        state[self.persisted_state] = {self.ATTEMPT_COUNT_KEY: 0}
+
+        # Send initial prompt
+        await self.on_prompt(
+            dialog_context.context,
+            state[self.persisted_state],
+            state[self.persisted_options],
+            False,
+        )
+
+        return Dialog.end_of_turn
+
+    async def continue_dialog(self, dialog_context: DialogContext):
+        if not dialog_context:
+            raise TypeError("Prompt(): dc cannot be None.")
+
+        # Don't do anything for non-message activities
+        if dialog_context.context.activity.type != ActivityTypes.message:
+            return Dialog.end_of_turn
+
+        # Perform base recognition
+        instance = dialog_context.active_dialog
+        assert instance is not None
+        state = cast(dict[str, object], instance.state[self.persisted_state])
+        options = cast(PromptOptions, instance.state[self.persisted_options])
+        recognized = await self.on_recognize(dialog_context.context, state, options)
+
+        # Validate the return value
+        is_valid = False
+        state[self.ATTEMPT_COUNT_KEY] = (
+            int(cast(int, state.get(self.ATTEMPT_COUNT_KEY, 0))) + 1
+        )
+        if self._validator is not None:
+            prompt_context = PromptValidatorContext(
+                dialog_context.context, recognized, state, options
+            )
+            is_valid = await self._validator(prompt_context)
+            if options is None:
+                options = PromptOptions()
+            options.number_of_attempts += 1
+        else:
+            if recognized.succeeded:
+                is_valid = True
+
+        # Return recognized value or re-prompt
+        if is_valid:
+            return await dialog_context.end_dialog(recognized.value)
+
+        if not dialog_context.context.responded:
+            await self.on_prompt(dialog_context.context, state, options, True)
+        return Dialog.end_of_turn
+
+    async def resume_dialog(
+        self, dialog_context: DialogContext, reason: DialogReason, result: object
+    ) -> DialogTurnResult:
+        assert dialog_context.active_dialog is not None
+        await self.reprompt_dialog(dialog_context.context, dialog_context.active_dialog)
+        return Dialog.end_of_turn
+
+    async def reprompt_dialog(self, context: TurnContext, instance: DialogInstance):
+        state = instance.state[self.persisted_state]
+        options = instance.state[self.persisted_options]
+        await self.on_prompt(context, state, options, False)
+
+    @abstractmethod
+    async def on_prompt(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+        is_retry: bool,
+    ):
+        pass
+
+    @abstractmethod
+    async def on_recognize(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+    ) -> PromptRecognizerResult:
+        pass
+
+    def append_choices(
+        self,
+        prompt: Activity | None,
+        channel_id: str,
+        choices: list[Choice],
+        style: ListStyle | int,
+        options: ChoiceFactoryOptions | None = None,
+    ) -> Activity:
+        """
+        Composes an output activity containing a set of choices.
+        """
+        # Get base prompt text (if any)
+        text = prompt.text if prompt is not None and prompt.text else ""
+
+        # Create temporary msg
+        def inline() -> Activity:
+            return ChoiceFactory.inline(choices, text, None, options)
+
+        def list_style() -> Activity:
+            return ChoiceFactory.list_style(choices, text, None, options)
+
+        def suggested_action() -> Activity:
+            return ChoiceFactory.suggested_action(choices, text)
+
+        def hero_card() -> Activity:
+            return ChoiceFactory.hero_card(choices, text)
+
+        def list_style_none() -> Activity:
+            from microsoft_agents.activity import (
+                Activity as _Activity,
+                ActivityTypes as _AT,
+            )
+
+            activity = _Activity(type=_AT.message)  # type: ignore[call-arg]
+            activity.text = text
+            return activity
+
+        def default() -> Activity:
+            return ChoiceFactory.for_channel(channel_id, choices, text, None, options)
+
+        # Maps to values in ListStyle Enum
+        switcher = {
+            0: list_style_none,
+            1: default,
+            2: inline,
+            3: list_style,
+            4: suggested_action,
+            5: hero_card,
+        }
+
+        msg = switcher.get(int(style), default)()
+
+        # Update prompt with text, actions and attachments
+        if prompt:
+            # clone the prompt set in the options
+            prompt = copy.copy(prompt)
+
+            prompt.text = msg.text
+
+            if (
+                msg.suggested_actions is not None
+                and msg.suggested_actions.actions is not None
+                and msg.suggested_actions.actions
+            ):
+                prompt.suggested_actions = msg.suggested_actions
+
+            if msg.attachments:
+                if prompt.attachments:
+                    prompt.attachments.extend(msg.attachments)
+                else:
+                    prompt.attachments = msg.attachments
+
+            return prompt
+
+        msg.input_hint = None  # type: ignore[assignment]
+        return msg

microsoft_agents/hosting/dialogs/prompts/prompt_culture_models.py

@@ -0,0 +1,222 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from recognizers_text import Culture
+
+
+class PromptCultureModel:
+    """
+    Culture model used in Choice and Confirm Prompts.
+    """
+
+    def __init__(
+        self,
+        locale: str,
+        separator: str,
+        inline_or: str,
+        inline_or_more: str,
+        yes_in_language: str,
+        no_in_language: str,
+    ):
+        """
+
+        :param locale: Culture Model's Locale. Example: "en-US".
+        :param separator: Culture Model's Inline Separator. Example: ", ".
+        :param inline_or: Culture Model's Inline Or. Example: " or ".
+        :param inline_or_more Culture Model's Inline Or More. Example: ", or ".
+        :param yes_in_language: Equivalent of "Yes" in Culture Model's Language. Example: "Yes".
+        :param no_in_language: Equivalent of "No" in Culture Model's Language. Example: "No".
+        """
+        self.locale = locale
+        self.separator = separator
+        self.inline_or = inline_or
+        self.inline_or_more = inline_or_more
+        self.yes_in_language = yes_in_language
+        self.no_in_language = no_in_language
+
+
+class PromptCultureModels:
+    """
+    Class container for currently-supported Culture Models in Confirm and Choice Prompt.
+    """
+
+    Bulgarian = PromptCultureModel(
+        # TODO: Replace with Culture.Bulgarian after Recognizers-Text package updates.
+        locale="bg-bg",
+        inline_or=" или ",
+        inline_or_more=", или ",
+        separator=", ",
+        no_in_language="Не",
+        yes_in_language="да",
+    )
+
+    Chinese = PromptCultureModel(
+        locale=Culture.Chinese,
+        inline_or=" 要么 ",
+        inline_or_more="， 要么 ",
+        separator="， ",
+        no_in_language="不",
+        yes_in_language="是的",
+    )
+
+    Dutch = PromptCultureModel(
+        locale=Culture.Dutch,
+        inline_or=" of ",
+        inline_or_more=", of ",
+        separator=", ",
+        no_in_language="Nee",
+        yes_in_language="Ja",
+    )
+
+    English = PromptCultureModel(
+        locale=Culture.English,
+        inline_or=" or ",
+        inline_or_more=", or ",
+        separator=", ",
+        no_in_language="No",
+        yes_in_language="Yes",
+    )
+
+    Hindi = PromptCultureModel(
+        # TODO: Replace with Culture.Hindi after Recognizers-Text package updates.
+        locale="hi-in",
+        inline_or=" या ",
+        inline_or_more=", या ",
+        separator=", ",
+        no_in_language="नहीं",
+        yes_in_language="हां",
+    )
+
+    French = PromptCultureModel(
+        locale=Culture.French,
+        inline_or=" ou ",
+        inline_or_more=", ou ",
+        separator=", ",
+        no_in_language="Non",
+        yes_in_language="Oui",
+    )
+
+    German = PromptCultureModel(
+        # TODO: Replace with Culture.German after Recognizers-Text package updates.
+        locale="de-de",
+        inline_or=" oder ",
+        inline_or_more=", oder ",
+        separator=", ",
+        no_in_language="Nein",
+        yes_in_language="Ja",
+    )
+
+    Italian = PromptCultureModel(
+        locale=Culture.Italian,
+        inline_or=" o ",
+        inline_or_more=" o ",
+        separator=", ",
+        no_in_language="No",
+        yes_in_language="Si",
+    )
+
+    Japanese = PromptCultureModel(
+        locale=Culture.Japanese,
+        inline_or=" または ",
+        inline_or_more="、 または ",
+        separator="、 ",
+        no_in_language="いいえ",
+        yes_in_language="はい",
+    )
+
+    Korean = PromptCultureModel(
+        locale=Culture.Korean,
+        inline_or=" 또는 ",
+        inline_or_more=" 또는 ",
+        separator=", ",
+        no_in_language="아니",
+        yes_in_language="예",
+    )
+
+    Portuguese = PromptCultureModel(
+        locale=Culture.Portuguese,
+        inline_or=" ou ",
+        inline_or_more=", ou ",
+        separator=", ",
+        no_in_language="Não",
+        yes_in_language="Sim",
+    )
+
+    Spanish = PromptCultureModel(
+        locale=Culture.Spanish,
+        inline_or=" o ",
+        inline_or_more=", o ",
+        separator=", ",
+        no_in_language="No",
+        yes_in_language="Sí",
+    )
+
+    Swedish = PromptCultureModel(
+        # TODO: Replace with Culture.Swedish after Recognizers-Text package updates.
+        locale="sv-se",
+        inline_or=" eller ",
+        inline_or_more=" eller ",
+        separator=", ",
+        no_in_language="Nej",
+        yes_in_language="Ja",
+    )
+
+    Turkish = PromptCultureModel(
+        locale=Culture.Turkish,
+        inline_or=" veya ",
+        inline_or_more=" veya ",
+        separator=", ",
+        no_in_language="Hayır",
+        yes_in_language="Evet",
+    )
+
+    @classmethod
+    def map_to_nearest_language(cls, culture_code: str) -> str:
+        """
+        Normalize various potential locale strings to a standard.
+        :param culture_code: Represents locale. Examples: "en-US, en-us, EN".
+        :return: Normalized locale.
+        :rtype: str
+
+        .. remarks::
+            In our other SDKs, this method is a copy/paste of the ones from the Recognizers-Text library.
+            However, that doesn't exist in Python.
+        """
+        if culture_code:
+            culture_code = culture_code.lower()
+            supported_culture_codes = cls._get_supported_locales()
+
+            if culture_code not in supported_culture_codes:
+                culture_prefix = culture_code.split("-")[0]
+
+                for supported_culture_code in supported_culture_codes:
+                    if supported_culture_code.startswith(culture_prefix):
+                        culture_code = supported_culture_code
+
+        return culture_code
+
+    @classmethod
+    def get_supported_cultures(cls) -> list[PromptCultureModel]:
+        """
+        Gets a list of the supported culture models.
+        """
+        return [
+            cls.Bulgarian,
+            cls.Chinese,
+            cls.Dutch,
+            cls.English,
+            cls.French,
+            cls.German,
+            cls.Hindi,
+            cls.Italian,
+            cls.Japanese,
+            cls.Korean,
+            cls.Portuguese,
+            cls.Spanish,
+            cls.Swedish,
+            cls.Turkish,
+        ]
+
+    @classmethod
+    def _get_supported_locales(cls) -> list[str]:
+        return [c.locale for c in cls.get_supported_cultures()]

microsoft_agents/hosting/dialogs/prompts/prompt_options.py

@@ -0,0 +1,42 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from microsoft_agents.activity import Activity
+from microsoft_agents.hosting.dialogs.choices import Choice, ListStyle
+
+
+class PromptOptions:
+    """
+    Contains settings to pass to a :class:`Prompt` object when the prompt is started.
+    """
+
+    def __init__(
+        self,
+        prompt: Activity | None = None,
+        retry_prompt: Activity | None = None,
+        choices: list[Choice] | None = None,
+        style: ListStyle | None = None,
+        validations: object = None,
+        number_of_attempts: int = 0,
+    ):
+        """
+        Contains settings to pass to a :class:`Prompt` when the prompt is started.
+
+        :param prompt: The initial prompt activity to send to the user.
+        :type prompt: :class:`microsoft_agents.activity.Activity`
+        :param retry_prompt: The activity to send when the user's input fails validation.
+        :type retry_prompt: :class:`microsoft_agents.activity.Activity`
+        :param choices: The list of choices presented to the user (used by :class:`ChoicePrompt`).
+        :type choices: list[:class:`microsoft_agents.hosting.dialogs.choices.Choice`]
+        :param style: Controls how the choice list is rendered.
+        :type style: :class:`microsoft_agents.hosting.dialogs.choices.ListStyle`
+        :param validations: Additional validation data passed through to a custom validator.
+        :param number_of_attempts: Running count of how many times the prompt has been retried.
+        :type number_of_attempts: int
+        """
+        self.prompt = prompt
+        self.retry_prompt = retry_prompt
+        self.choices = choices
+        self.style = style
+        self.validations = validations
+        self.number_of_attempts = number_of_attempts

microsoft_agents/hosting/dialogs/prompts/prompt_recognizer_result.py

@@ -0,0 +1,11 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""Result returned by a prompts recognizer function."""
+
+
+class PromptRecognizerResult:
+    def __init__(self, succeeded: bool = False, value: object = None):
+        """Creates result returned by a prompts recognizer function."""
+        self.succeeded = succeeded
+        self.value = value

microsoft_agents/hosting/dialogs/prompts/prompt_validator_context.py

@@ -0,0 +1,44 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+from typing import Dict, cast
+from microsoft_agents.hosting.core import TurnContext
+from .prompt_options import PromptOptions
+from .prompt_recognizer_result import PromptRecognizerResult
+
+
+class PromptValidatorContext:
+    def __init__(
+        self,
+        turn_context: TurnContext,
+        recognized: PromptRecognizerResult,
+        state: Dict[str, object],
+        options: PromptOptions,
+    ):
+        """Creates contextual information passed to a custom `PromptValidator`.
+        Parameters
+        ----------
+        turn_context
+            The context for the current turn of conversation with the user.
+        recognized
+            Result returned from the prompts recognizer function.
+        state
+            A dictionary of values persisted for each conversational turn while the prompt is active.
+        options
+            Original set of options passed to the prompt by the calling dialog.
+        """
+        self.context = turn_context
+        self.recognized = recognized
+        self.state = state
+        self.options = options
+
+    @property
+    def attempt_count(self) -> int:
+        """Gets the number of times the validator has been called for this prompt.
+
+        The counter starts at 1 on the first validation call and increments with
+        each subsequent user reply.
+        """
+        # pylint: disable=import-outside-toplevel
+        from microsoft_agents.hosting.dialogs.prompts.prompt import Prompt
+
+        return int(cast(int, self.state.get(Prompt.ATTEMPT_COUNT_KEY, 0)))

microsoft_agents/hosting/dialogs/prompts/text_prompt.py

@@ -0,0 +1,82 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.activity import ActivityTypes
+
+from .prompt import Prompt
+from .prompt_options import PromptOptions
+from .prompt_recognizer_result import PromptRecognizerResult
+
+
+class TextPrompt(Prompt):
+    """Prompts a user to enter any text.
+
+    Succeeds whenever the user sends a message activity whose ``text`` field is
+    not ``None``.  Empty strings are accepted as valid because some channels
+    send an empty ``text`` alongside attachments.  There is no built-in
+    recognizer: the raw ``activity.text`` string is returned as the result.
+
+    Pass an optional ``validator`` at construction time to apply additional
+    constraints (e.g. minimum length, allow-list, non-empty enforcement).
+
+    .. note::
+        Non-message activities and messages where ``activity.text`` is ``None``
+        cause recognition to fail and will trigger the retry prompt if one was
+        provided.
+    """
+
+    async def on_prompt(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+        is_retry: bool,
+    ):
+        """Sends the initial or retry prompt activity to the user.
+
+        :param turn_context: The context for the current turn.
+        :param state: Persisted prompt state (unused by TextPrompt).
+        :param options: Prompt options containing the prompt and optional retry prompt.
+        :param is_retry: ``True`` when re-prompting after a failed validation.
+        """
+        if not turn_context:
+            raise TypeError("TextPrompt.on_prompt(): turn_context cannot be None.")
+        if not options:
+            raise TypeError("TextPrompt.on_prompt(): options cannot be None.")
+
+        if is_retry and options.retry_prompt is not None:
+            await turn_context.send_activity(options.retry_prompt)
+        else:
+            if options.prompt is not None:
+                await turn_context.send_activity(options.prompt)
+
+    async def on_recognize(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+    ) -> PromptRecognizerResult:
+        """Attempts to recognise text from the incoming activity.
+
+        Succeeds only when the activity is a message **and** ``activity.text``
+        is not ``None``.  Empty strings are considered valid (``succeeded=True``
+        with an empty string value), since some channels send empty text with
+        attachments.
+
+        :param turn_context: The context for the current turn.
+        :param state: Persisted prompt state (unused by TextPrompt).
+        :param options: Prompt options (unused by TextPrompt).
+        :return: Recognition result with ``succeeded=True`` and the raw text when
+            a message with text is received; ``succeeded=False`` otherwise.
+        """
+        if not turn_context:
+            raise TypeError("TextPrompt.on_recognize(): turn_context cannot be None.")
+
+        result = PromptRecognizerResult()
+        if turn_context.activity.type == ActivityTypes.message:
+            message = turn_context.activity
+            if message.text is not None:
+                result.succeeded = True
+                result.value = message.text
+        return result