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

microsoft_agents/hosting/dialogs/dialog_context.py

@@ -0,0 +1,426 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from microsoft_agents.hosting.core.turn_context import TurnContext
+from microsoft_agents.hosting.dialogs.memory import DialogStateManager
+
+from .models.dialog_event import DialogEvent
+from .models.dialog_events import DialogEvents
+from .dialog_set import DialogSet
+from .dialog_state import DialogState
+from .models.dialog_turn_status import DialogTurnStatus
+from .models.dialog_turn_result import DialogTurnResult
+from .models.dialog_reason import DialogReason
+from .models.dialog_instance import DialogInstance
+from .dialog import Dialog
+
+
+class DialogContext:
+
+    def __init__(
+        self, dialog_set: DialogSet, turn_context: TurnContext, state: DialogState
+    ):
+        if dialog_set is None:
+            raise TypeError("DialogContext(): dialog_set cannot be None.")
+        # TODO: Circular dependency with dialog_set: Check type.
+        if turn_context is None:
+            raise TypeError("DialogContext(): turn_context cannot be None.")
+        self._turn_context = turn_context
+        self._dialogs = dialog_set
+        self._stack = state.dialog_stack
+        self.services = {}
+        self.parent: DialogContext | None = None
+        self.state = DialogStateManager(self)
+
+    @property
+    def dialogs(self) -> DialogSet:
+        """Gets the set of dialogs that can be called from this context.
+
+        :param:
+        :return DialogSet:
+        """
+        return self._dialogs
+
+    @property
+    def context(self) -> TurnContext:
+        """Gets the context for the current turn of conversation.
+
+        :param:
+        :return TurnContext:
+        """
+        return self._turn_context
+
+    @property
+    def stack(self) -> list[DialogInstance]:
+        """Gets the current dialog stack.
+
+        :param:
+        :return list:
+        """
+        return self._stack
+
+    @property
+    def active_dialog(self) -> DialogInstance | None:
+        """Gets the instance of the active (top-of-stack) dialog, or None if the stack is empty.
+
+        :return: The active DialogInstance, or None if no dialog is active.
+        """
+        if self._stack:
+            return self._stack[0]
+        return None
+
+    @property
+    def child(self) -> DialogContext | None:
+        """Gets the DialogContext for the active dialog's inner dialog stack, if the active
+        dialog is a DialogContainer (e.g. ComponentDialog). Returns None if there is no
+        active dialog or the active dialog is not a container.
+
+        :return: The child DialogContext, or None.
+        """
+        # pylint: disable=import-outside-toplevel
+        instance = self.active_dialog
+
+        if instance:
+            dialog = self.find_dialog_sync(instance.id)
+
+            # This import prevents circular dependency issues
+            from .dialog_container import DialogContainer
+
+            if isinstance(dialog, DialogContainer):
+                return dialog.create_child_context(self)
+
+        return None
+
+    async def begin_dialog(self, dialog_id: str, options: object = None):
+        """
+        Pushes a new dialog onto the dialog stack.
+        :param dialog_id: ID of the dialog to start
+        :param options: (Optional) additional argument(s) to pass to the dialog being started.
+        """
+        try:
+            if not dialog_id:
+                raise TypeError("Dialog(): dialog_id cannot be None.")
+            # Look up dialog
+            dialog = await self.find_dialog(dialog_id)
+            if dialog is None:
+                raise Exception(
+                    "'DialogContext.begin_dialog(): A dialog with an id of '%s' wasn't found."
+                    " The dialog must be included in the current or parent DialogSet."
+                    " For example, if subclassing a ComponentDialog you can call add_dialog() within your constructor."
+                    % dialog_id
+                )
+            # Push new instance onto stack
+            instance = DialogInstance()
+            instance.id = dialog_id
+            instance.state = {}
+
+            self._stack.insert(0, (instance))
+
+            # Call dialog's begin_dialog() method
+            return await dialog.begin_dialog(self, options)
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    # TODO: Fix options: PromptOptions instead of object
+    async def prompt(self, dialog_id: str, options) -> DialogTurnResult:
+        """
+        Helper function to simplify formatting the options for calling a prompt dialog. This helper will
+        take a `PromptOptions` argument and then call.
+        :param dialog_id: ID of the prompt to start.
+        :param options: Contains a Prompt, potentially a RetryPrompt and if using ChoicePrompt, Choices.
+        :return:
+        """
+        try:
+            if not dialog_id:
+                raise TypeError("DialogContext.prompt(): dialogId cannot be None.")
+
+            if not options:
+                raise TypeError("DialogContext.prompt(): options cannot be None.")
+
+            return await self.begin_dialog(dialog_id, options)
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    async def continue_dialog(self):
+        """
+        Continues execution of the active dialog, if there is one, by passing the context object to
+        its `Dialog.continue_dialog()` method. You can check `turn_context.responded` after the call completes
+        to determine if a dialog was run and a reply was sent to the user.
+        :return:
+        """
+        try:
+            # Check for a dialog on the stack
+            if self.active_dialog is not None:
+                # Look up dialog
+                dialog = await self.find_dialog(self.active_dialog.id)
+                if not dialog:
+                    raise Exception(
+                        "DialogContext.continue_dialog(): Can't continue dialog. "
+                        "A dialog with an id of '%s' wasn't found."
+                        % self.active_dialog.id
+                    )
+
+                # Continue execution of dialog
+                return await dialog.continue_dialog(self)
+
+            return DialogTurnResult(DialogTurnStatus.Empty)
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    # TODO: instance is DialogInstance
+    async def end_dialog(self, result: object = None):
+        """
+        Ends a dialog by popping it off the stack and returns an optional result to the dialog's
+        parent. The parent dialog is the dialog that started the dialog being ended via a call to
+        either "begin_dialog" or "prompt".
+        The parent dialog will have its `Dialog.resume_dialog()` method invoked with any returned
+        result. If the parent dialog hasn't implemented a `resume_dialog()` method then it will be
+        automatically ended as well and the result passed to its parent. If there are no more
+        parent dialogs on the stack then processing of the turn will end.
+        :param result: (Optional) result to pass to the parent dialogs.
+        :return:
+        """
+        try:
+            await self.end_active_dialog(DialogReason.EndCalled)
+
+            # Resume previous dialog
+            if self.active_dialog is not None:
+                # Look up dialog
+                dialog = await self.find_dialog(self.active_dialog.id)
+                if not dialog:
+                    raise Exception(
+                        "DialogContext.EndDialogAsync(): Can't resume previous dialog."
+                        " A dialog with an id of '%s' wasn't found."
+                        % self.active_dialog.id
+                    )
+
+                # Return result to previous dialog
+                return await dialog.resume_dialog(self, DialogReason.EndCalled, result)
+
+            return DialogTurnResult(DialogTurnStatus.Complete, result)
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    async def cancel_all_dialogs(
+        self,
+        cancel_parents: bool | None = None,
+        event_name: str | None = None,
+        event_value: object = None,
+    ):
+        """
+        Deletes any existing dialog stack thus cancelling all dialogs on the stack.
+        :param cancel_parents:
+        :param event_name:
+        :param event_value:
+        :return:
+        """
+        try:
+            event_name = event_name or DialogEvents.cancel_dialog
+            if self.stack or self.parent:
+                # Cancel all local and parent dialogs while checking for interception
+                notify = False
+                dialog_context = self
+
+                while dialog_context:
+                    if dialog_context.stack:
+                        # Check to see if the dialog wants to handle the event
+                        if notify:
+                            event_handled = await dialog_context.emit_event(
+                                event_name,
+                                event_value,
+                                bubble=False,
+                                from_leaf=False,
+                            )
+
+                            if event_handled:
+                                break
+
+                        # End the active dialog
+                        await dialog_context.end_active_dialog(
+                            DialogReason.CancelCalled
+                        )
+                    else:
+                        dialog_context = (
+                            dialog_context.parent if cancel_parents else None
+                        )
+
+                    notify = True
+
+                return DialogTurnResult(DialogTurnStatus.Cancelled)
+
+            # Stack was empty and no parent
+            return DialogTurnResult(DialogTurnStatus.Empty)
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    async def find_dialog(self, dialog_id: str | None) -> Dialog | None:
+        """
+        If the dialog cannot be found within the current `DialogSet`, the parent `DialogContext`
+        will be searched if there is one.
+        :param dialog_id: ID of the dialog to search for.
+        :return:
+        """
+        try:
+            dialog = await self.dialogs.find(dialog_id)
+
+            if dialog is None and self.parent is not None:
+                dialog = await self.parent.find_dialog(dialog_id)
+            return dialog
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    def find_dialog_sync(self, dialog_id: str | None) -> Dialog | None:
+        """
+        If the dialog cannot be found within the current `DialogSet`, the parent `DialogContext`
+        will be searched if there is one.
+        :param dialog_id: ID of the dialog to search for.
+        :return:
+        """
+        dialog = self.dialogs.find_dialog(dialog_id)
+
+        if dialog is None and self.parent is not None:
+            dialog = self.parent.find_dialog_sync(dialog_id)
+        return dialog
+
+    async def replace_dialog(
+        self, dialog_id: str, options: object = None
+    ) -> DialogTurnResult:
+        """
+        Ends the active dialog and starts a new dialog in its place. This is particularly useful
+        for creating loops or redirecting to another dialog.
+        :param dialog_id: ID of the dialog to search for.
+        :param options: (Optional) additional argument(s) to pass to the new dialog.
+        :return:
+        """
+        try:
+            # End the current dialog and giving the reason.
+            await self.end_active_dialog(DialogReason.ReplaceCalled)
+
+            # Start replacement dialog
+            return await self.begin_dialog(dialog_id, options)
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    async def reprompt_dialog(self):
+        """
+        Calls reprompt on the currently active dialog, if there is one. Used with Prompts that have a reprompt behavior.
+        :return:
+        """
+        try:
+            # Check for a dialog on the stack
+            if self.active_dialog is not None:
+                # Look up dialog
+                dialog = await self.find_dialog(self.active_dialog.id)
+                if not dialog:
+                    raise Exception(
+                        "DialogSet.reprompt_dialog(): Can't find A dialog with an id of '%s'."
+                        % self.active_dialog.id
+                    )
+
+                # Ask dialog to re-prompt if supported
+                await dialog.reprompt_dialog(self.context, self.active_dialog)
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    async def end_active_dialog(self, reason: DialogReason):
+        """Pops the active dialog off the stack and notifies it of the reason it ended.
+
+        :param reason: The reason the dialog is ending (e.g. EndCalled, CancelCalled).
+        """
+        instance = self.active_dialog
+        if instance is not None:
+            # Look up dialog
+            dialog = await self.find_dialog(instance.id)
+            if dialog is not None:
+                # Notify dialog of end
+                await dialog.end_dialog(self.context, instance, reason)
+
+            # Pop dialog off stack
+            self._stack.pop(0)
+
+    async def emit_event(
+        self,
+        name: str,
+        value: object = None,
+        bubble: bool = True,
+        from_leaf: bool = False,
+    ) -> bool:
+        """
+        Searches for a dialog with a given ID.
+        Emits a named event for the current dialog, or someone who started it, to handle.
+        :param name: Name of the event to raise.
+        :param value: Value to send along with the event.
+        :param bubble: Flag to control whether the event should be bubbled to its parent if not handled locally.
+        Defaults to a value of `True`.
+        :param from_leaf: Whether the event is emitted from a leaf node.
+        :param cancellationToken: The cancellation token.
+        :return: True if the event was handled.
+        """
+        try:
+            # Initialize event
+            dialog_event = DialogEvent(
+                bubble=bubble,
+                name=name,
+                value=value,
+            )
+
+            dialog_context = self
+
+            # Find starting dialog
+            if from_leaf:
+                while True:
+                    child_dc = dialog_context.child
+
+                    if child_dc:
+                        dialog_context = child_dc
+                    else:
+                        break
+
+            # Dispatch to active dialog first
+            instance = dialog_context.active_dialog
+
+            if instance:
+                dialog = await dialog_context.find_dialog(instance.id)
+
+                if dialog:
+                    return await dialog.on_dialog_event(dialog_context, dialog_event)
+
+            return False
+        except Exception as err:
+            self.__set_exception_context_data(err)
+            raise
+
+    def __set_exception_context_data(self, exception: Exception):
+        if not hasattr(exception, "data"):
+            setattr(exception, "data", {})
+
+        data = getattr(exception, "data")
+        if not type(self).__name__ in data:
+            stack = []
+            current_dc = self
+
+            while current_dc is not None:
+                stack = stack + [x.id for x in current_dc.stack]
+                current_dc = current_dc.parent
+
+            parent_active_id = None
+            if self.parent is not None and self.parent.active_dialog is not None:
+                parent_active_id = self.parent.active_dialog.id
+
+            data[type(self).__name__] = {
+                "active_dialog": (
+                    None if self.active_dialog is None else self.active_dialog.id
+                ),
+                "parent": parent_active_id,
+                "stack": self.stack,
+            }

microsoft_agents/hosting/dialogs/dialog_extensions.py

@@ -0,0 +1,201 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from microsoft_agents.hosting.core import (
+    ClaimsIdentity,
+    ChannelAdapter,
+    StatePropertyAccessor,
+    TurnContext,
+)
+from microsoft_agents.activity import Activity, ActivityTypes, EndOfConversationCodes
+
+from microsoft_agents.hosting.dialogs.memory import DialogStateManager
+from .dialog import Dialog
+from .dialog_context import DialogContext
+from .models import DialogTurnResult
+from .models.dialog_events import DialogEvents
+from .dialog_set import DialogSet
+from .models.dialog_turn_status import DialogTurnStatus
+
+
+class DialogExtensions:
+    @staticmethod
+    async def run_dialog(
+        dialog: Dialog,
+        turn_context: TurnContext,
+        accessor: StatePropertyAccessor,
+    ):
+        """
+        Creates a dialog stack and starts a dialog, pushing it onto the stack.
+        """
+        dialog_set = DialogSet(accessor)
+        dialog_set.add(dialog)
+
+        dialog_context: DialogContext = await dialog_set.create_context(turn_context)
+
+        await DialogExtensions._internal_run(turn_context, dialog.id, dialog_context)
+
+    @staticmethod
+    async def _internal_run(
+        context: TurnContext, dialog_id: str, dialog_context: DialogContext
+    ) -> DialogTurnResult:
+        # map TurnState into root dialog context.services
+        for key, service in context.turn_state.items():
+            dialog_context.services[key] = service
+
+        # get the DialogStateManager configuration
+        dialog_state_manager = DialogStateManager(dialog_context)
+        await dialog_state_manager.load_all_scopes()
+        dialog_context.context.turn_state[dialog_state_manager.__class__.__name__] = (
+            dialog_state_manager
+        )
+
+        # Loop as long as we are getting valid OnError handled we should continue executing the actions for the turn.
+        end_of_turn = False
+        dialog_turn_result: DialogTurnResult = DialogTurnResult(DialogTurnStatus.Empty)
+        while not end_of_turn:
+            try:
+                dialog_turn_result = await DialogExtensions.__inner_run(
+                    context, dialog_id, dialog_context
+                )
+
+                # turn successfully completed, break the loop
+                end_of_turn = True
+            except Exception as err:
+                # fire error event, bubbling from the leaf.
+                handled = await dialog_context.emit_event(
+                    DialogEvents.error, err, bubble=True, from_leaf=True
+                )
+
+                if not handled:
+                    # error was NOT handled, throw the exception and end the turn. (This will trigger the
+                    # Adapter.OnError handler and end the entire dialog stack)
+                    raise
+
+        # save all state scopes to their respective AgentState locations.
+        await dialog_state_manager.save_all_changes()
+
+        # return the result
+        return dialog_turn_result
+
+    @staticmethod
+    async def __inner_run(
+        turn_context: TurnContext, dialog_id: str, dialog_context: DialogContext
+    ) -> DialogTurnResult:
+        # Handle EoC and Reprompt event from a parent bot (can be root bot to skill or skill to skill)
+        if DialogExtensions.__is_from_parent_to_skill(turn_context):
+            # Handle remote cancellation request from parent.
+            if turn_context.activity.type == ActivityTypes.end_of_conversation:
+                if not dialog_context.stack:
+                    # No dialogs to cancel, just return.
+                    return DialogTurnResult(DialogTurnStatus.Empty)
+
+                # Send cancellation message to the dialog to ensure all the parents are canceled
+                # in the right order.
+                return await dialog_context.cancel_all_dialogs(True)
+
+            # Handle a reprompt event sent from the parent.
+            if (
+                turn_context.activity.type == ActivityTypes.event
+                and turn_context.activity.name == DialogEvents.reprompt_dialog
+            ):
+                if not dialog_context.stack:
+                    # No dialogs to reprompt, just return.
+                    return DialogTurnResult(DialogTurnStatus.Empty)
+
+                await dialog_context.reprompt_dialog()
+                return DialogTurnResult(DialogTurnStatus.Waiting)
+
+        # Continue or start the dialog.
+        result = await dialog_context.continue_dialog()
+        if result.status == DialogTurnStatus.Empty:
+            result = await dialog_context.begin_dialog(dialog_id)
+
+        await DialogExtensions._send_state_snapshot_trace(dialog_context)
+
+        # Skills should send EoC when the dialog completes.
+        if (
+            result.status == DialogTurnStatus.Complete
+            or result.status == DialogTurnStatus.Cancelled
+        ):
+            if DialogExtensions.__send_eoc_to_parent(turn_context):
+                activity = Activity(  # type: ignore[call-arg]
+                    type=ActivityTypes.end_of_conversation,
+                    value=result.result,
+                    locale=turn_context.activity.locale,
+                    code=(
+                        EndOfConversationCodes.completed_successfully
+                        if result.status == DialogTurnStatus.Complete
+                        else EndOfConversationCodes.user_cancelled
+                    ),
+                )
+                await turn_context.send_activity(activity)
+
+        return result
+
+    @staticmethod
+    def __is_from_parent_to_skill(turn_context: TurnContext) -> bool:
+        """
+        Determines if this turn is an incoming request from a parent bot to this skill.
+        """
+        claims_identity = turn_context.turn_state.get(
+            ChannelAdapter.AGENT_IDENTITY_KEY, None
+        )
+        return (
+            isinstance(claims_identity, ClaimsIdentity)
+            and claims_identity.is_agent_claim()
+        )
+
+    @staticmethod
+    async def _send_state_snapshot_trace(dialog_context: DialogContext):
+        """
+        Helper to send a trace activity with a memory snapshot of the active dialog DC.
+        """
+        claims_identity = dialog_context.context.turn_state.get(
+            ChannelAdapter.AGENT_IDENTITY_KEY, None
+        )
+        trace_label = (
+            "Skill State"
+            if isinstance(claims_identity, ClaimsIdentity)
+            and claims_identity.is_agent_claim()
+            else "Bot State"
+        )
+        # send trace of memory
+        snapshot = DialogExtensions._get_active_dialog_context(
+            dialog_context
+        ).state.get_memory_snapshot()
+        trace_activity = Activity(  # type: ignore[call-arg]
+            type=ActivityTypes.trace,
+            name="BotState",
+            value_type="https://www.botframework.com/schemas/botState",
+            value=snapshot,
+            label=trace_label,
+        )
+        await dialog_context.context.send_activity(trace_activity)
+
+    @staticmethod
+    def __send_eoc_to_parent(turn_context: TurnContext) -> bool:
+        """
+        Determines whether to send an EndOfConversation to the parent bot.
+        """
+        claims_identity = turn_context.turn_state.get(
+            ChannelAdapter.AGENT_IDENTITY_KEY, None
+        )
+        if (
+            isinstance(claims_identity, ClaimsIdentity)
+            and claims_identity.is_agent_claim()
+        ):
+            return True
+
+        return False
+
+    @staticmethod
+    def _get_active_dialog_context(dialog_context: DialogContext) -> DialogContext:
+        """
+        Recursively walk up the DC stack to find the active DC.
+        """
+        child = dialog_context.child
+        if not child:
+            return dialog_context
+
+        return DialogExtensions._get_active_dialog_context(child)