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

microsoft_agents/hosting/dialogs/prompts/activity_prompt.py

@@ -0,0 +1,203 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Any, Callable, cast
+
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.activity import ActivityTypes, InputHints
+
+from ..dialog import Dialog
+from ..dialog_context import DialogContext
+from ..models.dialog_instance import DialogInstance
+from ..models.dialog_reason import DialogReason
+from ..models.dialog_turn_result import DialogTurnResult
+from .prompt import Prompt
+from .prompt_options import PromptOptions
+from .prompt_recognizer_result import PromptRecognizerResult
+from .prompt_validator_context import PromptValidatorContext
+
+
+class ActivityPrompt(Dialog):
+    """
+    Waits for an activity to be received.
+
+    This prompt requires a validator be passed in and is useful when waiting for non-message
+    activities like an event to be received. The validator can ignore received events until the
+    expected activity is received.
+    """
+
+    persisted_options = "options"
+    persisted_state = "state"
+
+    def __init__(
+        self, dialog_id: str, validator: Callable[[PromptValidatorContext], Any]
+    ):
+        Dialog.__init__(self, dialog_id)
+
+        if validator is None:
+            raise TypeError("validator was expected but received None")
+        self._validator = validator
+
+    async def begin_dialog(
+        self, dialog_context: DialogContext, options: object = None
+    ) -> DialogTurnResult:
+        """Starts the prompt by sending the initial prompt activity.
+
+        Initialises persisted state with an attempt count of 0, then calls
+        :meth:`on_prompt`.
+
+        :param dialog_context: The dialog context for the current turn.
+        :param options: Must be a :class:`PromptOptions` instance.
+        :raises TypeError: If ``options`` is not a :class:`PromptOptions`.
+        :return: :attr:`Dialog.end_of_turn` to wait for the user's response.
+        """
+        if not dialog_context:
+            raise TypeError("ActivityPrompt.begin_dialog(): dc cannot be None.")
+        if not isinstance(options, PromptOptions):
+            raise TypeError(
+                "ActivityPrompt.begin_dialog(): Prompt options are required for ActivityPrompts."
+            )
+
+        # 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: dict[str, object] = dialog_context.active_dialog.state
+        state[self.persisted_options] = options
+        state[self.persisted_state] = {Prompt.ATTEMPT_COUNT_KEY: 0}
+
+        # Send initial prompt
+        await self.on_prompt(
+            dialog_context.context,
+            cast(dict[str, object], state[self.persisted_state]),
+            cast(PromptOptions, state[self.persisted_options]),
+            False,
+        )
+
+        return Dialog.end_of_turn
+
+    async def continue_dialog(self, dialog_context: DialogContext) -> DialogTurnResult:
+        """Processes the next incoming activity through the prompt.
+
+        Increments the persisted attempt count **before** calling the validator,
+        so :attr:`PromptValidatorContext.attempt_count` is at least 1 on the
+        first validation call.
+
+        .. note::
+            This differs from the base :class:`Prompt` class, where
+            ``attempt_count`` is never stored in state and is always 0 when the
+            validator runs.  Code that validates both ``ActivityPrompt`` and
+            ``Prompt`` subclasses should rely on
+            :attr:`PromptOptions.number_of_attempts` for consistent counting.
+
+        :param dialog_context: The dialog context for the current turn.
+        :return: :attr:`Dialog.end_of_turn` while waiting for valid input, or
+            a Complete result once the validator accepts the activity.
+        """
+        if not dialog_context:
+            raise TypeError(
+                "ActivityPrompt.continue_dialog(): DialogContext cannot be None."
+            )
+
+        # Perform base recognition
+        instance = dialog_context.active_dialog
+        assert instance is not None
+        state: dict[str, object] = cast(
+            dict[str, object], instance.state[self.persisted_state]
+        )
+        prompt_options: PromptOptions = cast(
+            PromptOptions, instance.state[self.persisted_options]
+        )
+        recognized: PromptRecognizerResult = await self.on_recognize(
+            dialog_context.context, state, prompt_options
+        )
+
+        # Increment attempt count
+        state[Prompt.ATTEMPT_COUNT_KEY] = (
+            int(cast(int, state.get(Prompt.ATTEMPT_COUNT_KEY, 0))) + 1
+        )
+
+        # Validate the return value
+        is_valid = False
+        if self._validator is not None:
+            prompt_context = PromptValidatorContext(
+                dialog_context.context, recognized, state, prompt_options
+            )
+            is_valid = await self._validator(prompt_context)
+
+            prompt_options.number_of_attempts += 1
+        elif recognized.succeeded:
+            is_valid = True
+
+        # Return recognized value or re-prompt
+        if is_valid:
+            return await dialog_context.end_dialog(recognized.value)
+
+        if (
+            dialog_context.context.activity.type == ActivityTypes.message
+            and not dialog_context.context.responded
+        ):
+            await self.on_prompt(dialog_context.context, state, prompt_options, True)
+
+        return Dialog.end_of_turn
+
+    async def resume_dialog(  # pylint: disable=unused-argument
+        self, dialog_context: DialogContext, reason: DialogReason, result: object = None
+    ):
+        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: dict[str, object] = instance.state[self.persisted_state]
+        options: PromptOptions = instance.state[self.persisted_options]
+        await self.on_prompt(context, state, options, False)
+
+    async def on_prompt(
+        self,
+        context: TurnContext,
+        state: dict[str, object],  # pylint: disable=unused-argument
+        options: PromptOptions,
+        is_retry: bool = False,
+    ):
+        """Sends the initial or retry prompt activity to the user.
+
+        Always sets ``input_hint`` to ``expecting_input`` before sending.
+
+        :param context: The context for the current turn.
+        :param state: Persisted prompt state (unused by default implementation).
+        :param options: Prompt options containing the prompt and optional retry prompt.
+        :param is_retry: ``True`` when re-prompting after failed validation.
+        """
+        if is_retry and options.retry_prompt:
+            options.retry_prompt.input_hint = InputHints.expecting_input
+            await context.send_activity(options.retry_prompt)
+        elif options.prompt:
+            options.prompt.input_hint = InputHints.expecting_input
+            await context.send_activity(options.prompt)
+
+    async def on_recognize(  # pylint: disable=unused-argument
+        self, context: TurnContext, state: dict[str, object], options: PromptOptions
+    ) -> PromptRecognizerResult:
+        """Default recognizer: always succeeds and returns the raw incoming activity.
+
+        Override this in a subclass to restrict which activities are considered
+        valid (e.g. accept only events with a specific name).
+
+        :param context: The context for the current turn.
+        :param state: Persisted prompt state.
+        :param options: Prompt options.
+        :return: A result with ``succeeded=True`` and ``value`` set to the
+            current :class:`Activity`.
+        """
+        result = PromptRecognizerResult()
+        result.succeeded = True
+        result.value = context.activity
+
+        return result

microsoft_agents/hosting/dialogs/prompts/attachment_prompt.py

@@ -0,0 +1,87 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Callable
+
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.activity import ActivityTypes
+
+from .prompt import Prompt, PromptValidatorContext
+from .prompt_options import PromptOptions
+from .prompt_recognizer_result import PromptRecognizerResult
+
+
+class AttachmentPrompt(Prompt):
+    """
+    Prompts a user to upload attachments like images.
+
+    By default the prompt will return to the calling dialog an `[Attachment]`
+    """
+
+    def __init__(
+        self,
+        dialog_id: str,
+        validator: Callable[[PromptValidatorContext], bool] | None = None,
+    ):
+        super().__init__(dialog_id, validator)
+
+    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 AttachmentPrompt).
+        :param options: Prompt options containing the prompt and optional retry prompt.
+        :param is_retry: ``True`` when re-prompting after failed validation.
+        """
+        if not turn_context:
+            raise TypeError("AttachmentPrompt.on_prompt(): TurnContext cannot be None.")
+
+        if not isinstance(options, PromptOptions):
+            raise TypeError(
+                "AttachmentPrompt.on_prompt(): PromptOptions are required for Attachment Prompt dialogs."
+            )
+
+        if is_retry and options.retry_prompt:
+            await turn_context.send_activity(options.retry_prompt)
+        elif options.prompt:
+            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 attachments from the incoming activity.
+
+        Succeeds only when the activity is a message **and** ``activity.attachments``
+        is a non-empty list.  The full attachment list is returned as the result.
+
+        .. note::
+            A message activity with no attachments (e.g. plain text) will fail
+            recognition and trigger the retry prompt.
+
+        :param turn_context: The context for the current turn.
+        :param state: Persisted prompt state (unused by AttachmentPrompt).
+        :param options: Prompt options (unused by AttachmentPrompt).
+        :return: Recognition result with ``succeeded=True`` and the list of
+            :class:`Attachment` objects, or ``succeeded=False`` if none were found.
+        """
+        if not turn_context:
+            raise TypeError("AttachmentPrompt.on_recognize(): context cannot be None.")
+
+        result = PromptRecognizerResult()
+
+        if turn_context.activity.type == ActivityTypes.message:
+            message = turn_context.activity
+            if isinstance(message.attachments, list) and message.attachments:
+                result.succeeded = True
+                result.value = message.attachments
+
+        return result

microsoft_agents/hosting/dialogs/prompts/choice_prompt.py

@@ -0,0 +1,156 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Callable
+
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.activity import Activity, ActivityTypes
+
+from ..choices import (
+    Choice,
+    ChoiceFactoryOptions,
+    ChoiceRecognizers,
+    FindChoicesOptions,
+    ListStyle,
+)
+
+from .prompt import Prompt
+from .prompt_culture_models import PromptCultureModels
+from .prompt_options import PromptOptions
+from .prompt_validator_context import PromptValidatorContext
+from .prompt_recognizer_result import PromptRecognizerResult
+
+
+class ChoicePrompt(Prompt):
+    """
+    Prompts a user to select from a list of choices.
+
+    By default the prompt will return to the calling dialog a `FoundChoice` object containing the choice that
+    was selected.
+    """
+
+    _default_choice_options: dict[str, ChoiceFactoryOptions] = {
+        c.locale: ChoiceFactoryOptions(
+            inline_separator=c.separator,
+            inline_or=c.inline_or,
+            inline_or_more=c.inline_or_more,
+            include_numbers=True,
+        )
+        for c in PromptCultureModels.get_supported_cultures()
+    }
+
+    def __init__(
+        self,
+        dialog_id: str,
+        validator: Callable[[PromptValidatorContext], bool] | None = None,
+        default_locale: str | None = None,
+        choice_defaults: dict[str, ChoiceFactoryOptions] | None = None,
+    ):
+        super().__init__(dialog_id, validator)
+
+        self.style = ListStyle.auto
+        self.default_locale = default_locale
+        self.choice_options: ChoiceFactoryOptions | None = None
+        self.recognizer_options: FindChoicesOptions | None = None
+
+        if choice_defaults is not None:
+            self._default_choice_options = choice_defaults
+
+    async def on_prompt(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+        is_retry: bool,
+    ):
+        if not turn_context:
+            raise TypeError("ChoicePrompt.on_prompt(): turn_context cannot be None.")
+
+        if not options:
+            raise TypeError("ChoicePrompt.on_prompt(): options cannot be None.")
+
+        # Determine culture
+        culture = self._determine_culture(turn_context.activity)
+
+        # Format prompt to send
+        choices: list[Choice] = options.choices if options.choices else []
+        channel_id: str = turn_context.activity.channel_id or ""
+        choice_options: ChoiceFactoryOptions = (
+            self.choice_options
+            if self.choice_options
+            else self._default_choice_options[culture]
+        )
+        choice_style = (
+            0 if options.style == 0 else options.style if options.style else self.style
+        )
+
+        if is_retry and options.retry_prompt is not None:
+            prompt = self.append_choices(
+                options.retry_prompt, channel_id, choices, choice_style, choice_options
+            )
+        else:
+            prompt = self.append_choices(
+                options.prompt, channel_id, choices, choice_style, choice_options
+            )
+
+        # Send prompt
+        await turn_context.send_activity(prompt)
+
+    async def on_recognize(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+    ) -> PromptRecognizerResult:
+        if not turn_context:
+            raise TypeError("ChoicePrompt.on_recognize(): turn_context cannot be None.")
+
+        choices: list[Choice] = options.choices if (options and options.choices) else []
+        result: PromptRecognizerResult = PromptRecognizerResult()
+
+        if turn_context.activity.type == ActivityTypes.message:
+            activity: Activity = turn_context.activity
+            utterance: str = activity.text
+            if not utterance:
+                return result
+            opt: FindChoicesOptions = (
+                self.recognizer_options
+                if self.recognizer_options
+                else FindChoicesOptions()
+            )
+            opt.locale = self._determine_culture(turn_context.activity, opt)
+            results = ChoiceRecognizers.recognize_choices(utterance, choices, opt)
+
+            if results is not None and results:
+                result.succeeded = True
+                result.value = results[0].resolution
+
+        return result
+
+    def _determine_culture(
+        self, activity: Activity, opt: FindChoicesOptions | None = None
+    ) -> str:
+        """Resolves the culture/locale string to use for choice formatting and recognition.
+
+        Resolution order:
+        1. ``activity.locale`` (mapped to the nearest supported language)
+        2. ``self.default_locale`` set at construction
+        3. ``opt.locale`` from the recognizer options (if provided)
+        4. English (``en-us``) as the final fallback
+
+        If the resolved locale is not in ``_default_choice_options``, English is used.
+
+        :param activity: The incoming activity (provides ``locale``).
+        :param opt: Optional recogniser options (provides ``locale`` fallback).
+        :return: A locale string present in :attr:`_default_choice_options`.
+        """
+        culture = (
+            PromptCultureModels.map_to_nearest_language(activity.locale)
+            or self.default_locale
+            or (opt.locale if opt else None)
+            or PromptCultureModels.English.locale
+        )
+        if not culture or not self._default_choice_options.get(culture):
+            culture = PromptCultureModels.English.locale
+
+        return culture

microsoft_agents/hosting/dialogs/prompts/confirm_prompt.py

@@ -0,0 +1,161 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Any, Callable
+
+from recognizers_choice import recognize_boolean
+
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.activity import ActivityTypes, Activity
+
+from ..choices import (
+    Choice,
+    ChoiceFactoryOptions,
+    ChoiceRecognizers,
+    ListStyle,
+)
+
+from .prompt import Prompt
+from .prompt_culture_models import PromptCultureModels
+from .prompt_options import PromptOptions
+from .prompt_recognizer_result import PromptRecognizerResult
+from .prompt_validator_context import PromptValidatorContext
+
+
+class ConfirmPrompt(Prompt):
+    """Prompts a user to confirm something with a yes/no response.
+
+    The prompt first attempts to recognise a boolean value using the
+    ``recognizers_choice`` package (e.g. "yes", "no", "true", "false", locale
+    equivalents).  If that fails and the prompt was configured to include
+    numbered choices (the default), it falls back to matching choice indices
+    ("1" → yes, "2" → no).
+
+    Returns ``True`` for confirmation, ``False`` for denial.
+
+    Culture/locale detection uses :class:`PromptCultureModels`.  Override
+    ``default_locale`` or ``choice_defaults`` at construction time to customise
+    the displayed choices and the locale used for recognition.
+    """
+
+    _default_choice_options: dict[str, tuple[Choice, Choice, ChoiceFactoryOptions]] = {
+        c.locale: (
+            Choice(c.yes_in_language),
+            Choice(c.no_in_language),
+            ChoiceFactoryOptions(c.separator, c.inline_or, c.inline_or_more, True),
+        )
+        for c in PromptCultureModels.get_supported_cultures()
+    }
+
+    def __init__(
+        self,
+        dialog_id: str,
+        validator: Callable[[PromptValidatorContext], Any] | None = None,
+        default_locale: str | None = None,
+        choice_defaults: (
+            dict[str, tuple[Choice, Choice, ChoiceFactoryOptions]] | None
+        ) = None,
+    ):
+        super().__init__(dialog_id, validator)
+        if dialog_id is None:
+            raise TypeError("ConfirmPrompt(): dialog_id cannot be None.")
+        self.style = ListStyle.auto
+        self.default_locale = default_locale
+        self.choice_options = None
+        self.confirm_choices = None
+
+        if choice_defaults is not None:
+            self._default_choice_options = choice_defaults
+
+    async def on_prompt(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+        is_retry: bool,
+    ):
+        if not turn_context:
+            raise TypeError("ConfirmPrompt.on_prompt(): turn_context cannot be None.")
+        if not options:
+            raise TypeError("ConfirmPrompt.on_prompt(): options cannot be None.")
+
+        # Format prompt to send
+        channel_id = turn_context.activity.channel_id or ""
+        culture = self._determine_culture(turn_context.activity)
+        defaults = self._default_choice_options[culture]
+        choice_opts = (
+            self.choice_options if self.choice_options is not None else defaults[2]
+        )
+        confirms = (
+            self.confirm_choices
+            if self.confirm_choices is not None
+            else (defaults[0], defaults[1])
+        )
+        choices = [confirms[0], confirms[1]]
+        if is_retry and options.retry_prompt is not None:
+            prompt = self.append_choices(
+                options.retry_prompt, channel_id, choices, self.style, choice_opts
+            )
+        else:
+            prompt = self.append_choices(
+                options.prompt, channel_id, choices, self.style, choice_opts
+            )
+        await turn_context.send_activity(prompt)
+
+    async def on_recognize(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+    ) -> PromptRecognizerResult:
+        if not turn_context:
+            raise TypeError("ConfirmPrompt.on_prompt(): turn_context cannot be None.")
+
+        result = PromptRecognizerResult()
+        if turn_context.activity.type == ActivityTypes.message:
+            # Recognize utterance
+            utterance = turn_context.activity.text
+            if not utterance:
+                return result
+            culture = self._determine_culture(turn_context.activity)
+            results = recognize_boolean(utterance, culture)
+            if results:
+                first = results[0]
+                if "value" in first.resolution:
+                    result.succeeded = True
+                    result.value = first.resolution["value"]
+            else:
+                # First check whether the prompt was sent to the user with numbers
+                defaults = self._default_choice_options[culture]
+                opts = (
+                    self.choice_options
+                    if self.choice_options is not None
+                    else defaults[2]
+                )
+
+                if opts.include_numbers is None or opts.include_numbers:
+                    confirm_choices = (
+                        self.confirm_choices
+                        if self.confirm_choices is not None
+                        else (defaults[0], defaults[1])
+                    )
+                    choices = [confirm_choices[0], confirm_choices[1]]
+                    second_attempt_results = ChoiceRecognizers.recognize_choices(
+                        utterance, choices
+                    )
+                    if second_attempt_results:
+                        result.succeeded = True
+                        result.value = second_attempt_results[0].resolution.index == 0
+
+        return result
+
+    def _determine_culture(self, activity: Activity) -> str:
+        culture = (
+            PromptCultureModels.map_to_nearest_language(activity.locale)
+            or self.default_locale
+            or PromptCultureModels.English.locale
+        )
+        if not culture or not self._default_choice_options.get(culture):
+            culture = PromptCultureModels.English.locale
+
+        return culture

microsoft_agents/hosting/dialogs/prompts/datetime_prompt.py

@@ -0,0 +1,90 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Any, Callable, cast
+
+from recognizers_date_time import recognize_datetime
+from recognizers_text import Culture
+
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.activity import ActivityTypes
+
+from .datetime_resolution import DateTimeResolution
+from .prompt import Prompt
+from .prompt_options import PromptOptions
+from .prompt_recognizer_result import PromptRecognizerResult
+from .prompt_validator_context import PromptValidatorContext
+
+
+class DateTimePrompt(Prompt):
+    def __init__(
+        self,
+        dialog_id: str,
+        validator: Callable[[PromptValidatorContext], Any] | None = None,
+        default_locale: str | None = None,
+    ):
+        super(DateTimePrompt, self).__init__(dialog_id, validator)
+        self.default_locale = default_locale
+
+    async def on_prompt(
+        self,
+        turn_context: TurnContext,
+        state: dict[str, object],
+        options: PromptOptions,
+        is_retry: bool,
+    ):
+        if not turn_context:
+            raise TypeError("DateTimePrompt.on_prompt(): turn_context cannot be None.")
+        if not options:
+            raise TypeError("DateTimePrompt.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:
+        if not turn_context:
+            raise TypeError(
+                "DateTimePrompt.on_recognize(): turn_context cannot be None."
+            )
+
+        result = PromptRecognizerResult()
+        if turn_context.activity.type == ActivityTypes.message:
+            # Recognize utterance
+            utterance = turn_context.activity.text
+            if not utterance:
+                return result
+            culture = (
+                turn_context.activity.locale or self.default_locale or Culture.English
+            )
+
+            results = recognize_datetime(utterance, culture)
+            if results:
+                result.succeeded = True
+                result.value = []
+                values = cast(list, results[0].resolution["values"])
+                for value in values:
+                    cast(list, result.value).append(self.read_resolution(value))
+
+        return result
+
+    def read_resolution(self, resolution: dict[str, str]) -> DateTimeResolution:
+        result = DateTimeResolution()
+
+        if "timex" in resolution:
+            result.timex = resolution["timex"]
+        if "value" in resolution:
+            result.value = resolution["value"]
+        if "start" in resolution:
+            result.start = resolution["start"]
+        if "end" in resolution:
+            result.end = resolution["end"]
+
+        return result