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

microsoft_agents/hosting/dialogs/choices/tokenizer.py

@@ -0,0 +1,92 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .models.token import Token
+
+
+class Tokenizer:
+    """Provides a default tokenizer implementation."""
+
+    @staticmethod
+    def default_tokenizer(  # pylint: disable=unused-argument
+        text: str, locale: str | None = None
+    ) -> list[Token]:
+        """
+        Simple tokenizer that breaks on spaces and punctuation. The only normalization is to lowercase.
+
+        Parameter:
+        ---------
+
+        text: The input text.
+
+        locale: (Optional) Identifies the locale of the input text.
+        """
+        tokens: list[Token] = []
+        token: Token | None = None
+
+        # Parse text
+        length: int = len(text) if text else 0
+        i: int = 0
+
+        while i < length:
+            # Get both the UNICODE value of the current character and the complete character itself
+            # which can potentially be multiple segments
+            code_point = ord(text[i])
+            char = chr(code_point)
+
+            # Process current character
+            if Tokenizer._is_breaking_char(code_point):
+                # Character is in Unicode Plane 0 and is in an excluded block
+                Tokenizer._append_token(tokens, token, i - 1)
+                token = None
+            elif code_point > 0xFFFF:
+                # Character is in a Supplementary Unicode Plane. This is where emoji live so
+                # we're going to just break each character in this range out as its own token
+                Tokenizer._append_token(tokens, token, i - 1)
+                token = None
+                tokens.append(Token(start=i, end=i, text=char, normalized=char))
+            elif token is None:
+                # Start a new token
+                token = Token(start=i, end=0, text=char, normalized=None)
+            else:
+                # Add onto current token
+                token.text += char
+
+            i += 1
+
+        Tokenizer._append_token(tokens, token, length - 1)
+
+        return tokens
+
+    @staticmethod
+    def _is_breaking_char(code_point) -> bool:
+        return (
+            Tokenizer._is_between(code_point, 0x0000, 0x002F)
+            or Tokenizer._is_between(code_point, 0x003A, 0x0040)
+            or Tokenizer._is_between(code_point, 0x005B, 0x0060)
+            or Tokenizer._is_between(code_point, 0x007B, 0x00BF)
+            or Tokenizer._is_between(code_point, 0x02B9, 0x036F)
+            or Tokenizer._is_between(code_point, 0x2000, 0x2BFF)
+            or Tokenizer._is_between(code_point, 0x2E00, 0x2E7F)
+        )
+
+    @staticmethod
+    def _is_between(value: int, from_val: int, to_val: int) -> bool:
+        """
+        Parameters
+        -----------
+
+        value: number value
+
+        from: low range
+
+        to: high range
+        """
+        return from_val <= value <= to_val
+
+    @staticmethod
+    def _append_token(tokens: list[Token], token: Token | None, end: int):
+        if token is not None:
+            token.end = end
+            token.normalized = token.text.lower()
+            tokens.append(token)

microsoft_agents/hosting/dialogs/component_dialog.py

@@ -0,0 +1,284 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Any
+
+from microsoft_agents.hosting.core import TurnContext
+
+from .dialog import Dialog
+from .dialog_context import DialogContext
+from .models.dialog_turn_result import DialogTurnResult
+from .dialog_state import DialogState
+from .models.dialog_turn_status import DialogTurnStatus
+from .models.dialog_reason import DialogReason
+from .dialog_set import DialogSet
+from .models.dialog_instance import DialogInstance
+
+
+class ComponentDialog(Dialog):
+    """
+    A :class:`microsoft_agents.hosting.dialogs.Dialog` that is composed of other dialogs
+
+    :var persisted_dialog state:
+    :vartype persisted_dialog_state: str
+    """
+
+    persisted_dialog_state = "dialogs"
+
+    def __init__(self, dialog_id: str):
+        """
+        Initializes a new instance of the :class:`ComponentDialog`
+
+        :param dialog_id: The ID to assign to the new dialog within the parent dialog set.
+        :type dialog_id: str
+        """
+        super(ComponentDialog, self).__init__(dialog_id)
+
+        if dialog_id is None:
+            raise TypeError("ComponentDialog(): dialog_id cannot be None.")
+
+        self._dialogs = DialogSet()
+        self.initial_dialog_id = None
+
+    # TODO: Add TelemetryClient
+
+    async def begin_dialog(
+        self, dialog_context: DialogContext, options: Any = None
+    ) -> DialogTurnResult:
+        """
+        Called when the dialog is started and pushed onto the parent's dialog stack.
+
+        If the task is successful, the result indicates whether the dialog is still
+        active after the turn has been processed by the dialog.
+
+        :param dialog_context: The :class:`botbuilder.dialogs.DialogContext` for the current turn of the conversation.
+        :type dialog_context: :class:`botbuilder.dialogs.DialogContext`
+        :param options: Optional, initial information to pass to the dialog.
+        :type options: Any
+        :return: Signals the end of the turn
+        :rtype: :class:`microsoft_agents.hosting.dialogs.Dialog.end_of_turn`
+        """
+        if dialog_context is None:
+            raise TypeError("ComponentDialog.begin_dialog(): outer_dc cannot be None.")
+
+        # Start the inner dialog.
+        dialog_state = DialogState()
+        assert dialog_context.active_dialog is not None
+        dialog_context.active_dialog.state[self.persisted_dialog_state] = dialog_state
+        inner_dc = DialogContext(self._dialogs, dialog_context.context, dialog_state)
+        inner_dc.parent = dialog_context
+        turn_result = await self.on_begin_dialog(inner_dc, options)
+
+        # Check for end of inner dialog
+        if turn_result.status != DialogTurnStatus.Waiting:
+            # Return result to calling dialog
+            return await self.end_component(dialog_context, turn_result.result)
+
+        # Just signal waiting
+        return Dialog.end_of_turn
+
+    async def continue_dialog(self, dialog_context: DialogContext) -> DialogTurnResult:
+        """
+        Called when the dialog is continued, where it is the active dialog and the
+        user replies with a new activity.
+
+        .. remarks::
+            If the task is successful, the result indicates whether the dialog is still
+            active after the turn has been processed by the dialog. The result may also
+            contain a return value.
+
+            If this method is *not* overriden the component dialog calls the
+            :meth:`microsoft_agents.hosting.dialogs.DialogContext.continue_dialog` method on it's inner dialog
+            context. If the inner dialog stack is empty, the component dialog ends,
+            and if a :class:`microsoft_agents.hosting.dialogs.DialogTurnResult.result` is available, the component dialog
+            uses that as it's return value.
+
+
+        :param dialog_context: The parent dialog context for the current turn of the conversation.
+        :type dialog_context: :class:`microsoft_agents.hosting.dialogs.DialogContext`
+        :return: Signals the end of the turn
+        :rtype: :class:`microsoft_agents.hosting.dialogs.Dialog.end_of_turn`
+        """
+        if dialog_context is None:
+            raise TypeError("ComponentDialog.begin_dialog(): outer_dc cannot be None.")
+
+        # Continue execution of inner dialog.
+        assert dialog_context.active_dialog is not None
+        dialog_state = dialog_context.active_dialog.state[self.persisted_dialog_state]
+        inner_dc = DialogContext(self._dialogs, dialog_context.context, dialog_state)
+        inner_dc.parent = dialog_context
+        turn_result = await self.on_continue_dialog(inner_dc)
+
+        if turn_result.status != DialogTurnStatus.Waiting:
+            return await self.end_component(dialog_context, turn_result.result)
+
+        return Dialog.end_of_turn
+
+    async def resume_dialog(
+        self, dialog_context: DialogContext, reason: DialogReason, result: object = None
+    ) -> DialogTurnResult:
+        """
+        Called when a child dialog on the parent's dialog stack completed this turn, returning
+        control to this dialog component.
+
+        .. remarks::
+            Containers are typically leaf nodes on the stack but the dev is free to push other dialogs
+            on top of the stack which will result in the container receiving an unexpected call to
+            :meth:`ComponentDialog.resume_dialog()` when the pushed on dialog ends.
+            To avoid the container prematurely ending we need to implement this method and simply
+            ask our inner dialog stack to re-prompt.
+
+        :param dialog_context: The dialog context for the current turn of the conversation.
+        :type dialog_context: :class:`microsoft_agents.hosting.dialogs.DialogContext`
+        :param reason: Reason why the dialog resumed.
+        :type reason: :class:`microsoft_agents.hosting.dialogs.DialogReason`
+        :param result: Optional, value returned from the dialog that was called.
+        :type result: object
+        :return: Signals the end of the turn
+        :rtype: :class:`microsoft_agents.hosting.dialogs.Dialog.end_of_turn`
+        """
+
+        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
+    ) -> None:
+        """
+        Called when the dialog should re-prompt the user for input.
+
+        :param context: The context object for this turn.
+        :type context: :class:`microsoft_agents.hosting.dialogs.TurnContext`
+        :param instance: State information for this dialog.
+        :type instance: :class:`microsoft_agents.hosting.dialogs.DialogInstance`
+        """
+        # Delegate to inner dialog.
+        dialog_state = instance.state[self.persisted_dialog_state]
+        inner_dc = DialogContext(self._dialogs, context, dialog_state)
+        await inner_dc.reprompt_dialog()
+
+        # Notify component
+        await self.on_reprompt_dialog(context, instance)
+
+    async def end_dialog(
+        self, context: TurnContext, instance: DialogInstance, reason: DialogReason
+    ) -> None:
+        """
+        Called when the dialog is ending.
+
+        :param context: The context object for this turn.
+        :type context: :class:`microsoft_agents.hosting.dialogs.TurnContext`
+        :param instance: State information associated with the instance of this component dialog.
+        :type instance: :class:`microsoft_agents.hosting.dialogs.DialogInstance`
+        :param reason: Reason why the dialog ended.
+        :type reason: :class:`microsoft_agents.hosting.dialogs.DialogReason`
+        """
+        # Forward cancel to inner dialog
+        if reason == DialogReason.CancelCalled:
+            dialog_state = instance.state[self.persisted_dialog_state]
+            inner_dc = DialogContext(self._dialogs, context, dialog_state)
+            await inner_dc.cancel_all_dialogs()
+        await self.on_end_dialog(context, instance, reason)
+
+    def add_dialog(self, dialog: Dialog) -> object:
+        """
+        Adds a :class:`Dialog` to the component dialog and returns the updated component.
+
+        :param dialog: The dialog to add.
+        :return: The updated :class:`ComponentDialog`.
+        :rtype: :class:`ComponentDialog`
+        """
+        self._dialogs.add(dialog)
+        if not self.initial_dialog_id:
+            self.initial_dialog_id = dialog.id
+        return self
+
+    async def find_dialog(self, dialog_id: str | None) -> Dialog | None:
+        """
+        Finds a dialog by ID.
+
+        :param dialog_id: The dialog to add.
+        :return: The dialog; or None if there is not a match for the ID.
+        :rtype: :class:`botbuilder.dialogs.Dialog`
+        """
+        return await self._dialogs.find(dialog_id)
+
+    async def on_begin_dialog(
+        self, inner_dc: DialogContext, options: object
+    ) -> DialogTurnResult:
+        """
+        Called when the dialog is started and pushed onto the parent's dialog stack.
+
+        .. remarks::
+            If the task is successful, the result indicates whether the dialog is still
+            active after the turn has been processed by the dialog.
+
+            By default, this calls the :meth:`microsoft_agents.hosting.dialogs.Dialog.begin_dialog()`
+            method of the component dialog's initial dialog.
+
+            Override this method in a derived class to implement interrupt logic.
+
+        :param inner_dc: The inner dialog context for the current turn of conversation.
+        :type inner_dc: :class:`microsoft_agents.hosting.dialogs.DialogContext`
+        :param options: Optional, initial information to pass to the dialog.
+        :type options: object
+        """
+        assert (
+            self.initial_dialog_id is not None
+        ), "ComponentDialog: initial_dialog_id must be set before begin_dialog is called."
+        return await inner_dc.begin_dialog(self.initial_dialog_id, options)
+
+    async def on_continue_dialog(self, inner_dc: DialogContext) -> DialogTurnResult:
+        """
+        Called when the dialog is continued, where it is the active dialog and the user replies with a new activity.
+
+        :param inner_dc: The inner dialog context for the current turn of conversation.
+        :type inner_dc: :class:`botbuilder.dialogs.DialogContext`
+        """
+        return await inner_dc.continue_dialog()
+
+    async def on_end_dialog(  # pylint: disable=unused-argument
+        self, context: TurnContext, instance: DialogInstance, reason: DialogReason
+    ) -> None:
+        """
+        Ends the component dialog in its parent's context.
+
+        :param turn_context: The :class:`botbuilder.core.TurnContext` for the current turn of the conversation.
+        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :param instance: State information associated with the inner dialog stack of this component dialog.
+        :type instance: :class:`botbuilder.dialogs.DialogInstance`
+        :param reason: Reason why the dialog ended.
+        :type reason: :class:`botbuilder.dialogs.DialogReason`
+        """
+        return
+
+    async def on_reprompt_dialog(  # pylint: disable=unused-argument
+        self, turn_context: TurnContext, instance: DialogInstance
+    ) -> None:
+        """
+        :param turn_context: The :class:`botbuilder.core.TurnContext` for the current turn of the conversation.
+        :type turn_context: :class:`botbuilder.dialogs.DialogInstance`
+        :param instance: State information associated with the inner dialog stack of this component dialog.
+        :type instance: :class:`botbuilder.dialogs.DialogInstance`
+        """
+        return
+
+    async def end_component(
+        self, outer_dc: DialogContext, result: object  # pylint: disable=unused-argument
+    ) -> DialogTurnResult:
+        """
+        Ends the component dialog in its parent's context.
+
+        .. remarks::
+            If the task is successful, the result indicates that the dialog ended after the
+            turn was processed by the dialog.
+
+        :param outer_dc: The parent dialog context for the current turn of conversation.
+        :type outer_dc: class:`botbuilder.dialogs.DialogContext`
+        :param result: Optional, value to return from the dialog component to the parent context.
+        :type result: object
+        :return: Value to return.
+        :rtype: :class:`botbuilder.dialogs.DialogTurnResult.result`
+        """
+        return await outer_dc.end_dialog(result)

microsoft_agents/hosting/dialogs/dialog.py

@@ -0,0 +1,198 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from microsoft_agents.hosting.core import TurnContext
+
+from ._telemetry_client import AgentTelemetryClient, NullTelemetryClient
+from .models.dialog_reason import DialogReason
+from .models.dialog_event import DialogEvent
+from .models.dialog_turn_status import DialogTurnStatus
+from .models.dialog_turn_result import DialogTurnResult
+from .models.dialog_instance import DialogInstance
+
+if TYPE_CHECKING:
+    from .dialog_context import DialogContext
+
+
+class Dialog(ABC):
+
+    def __init__(self, dialog_id: str):
+        if dialog_id is None or not dialog_id.strip():
+            raise TypeError("Dialog(): dialogId cannot be None.")
+
+        self._telemetry_client = NullTelemetryClient()
+        self._id = dialog_id
+
+    end_of_turn = DialogTurnResult(DialogTurnStatus.Waiting)
+    """DialogTurnResult indicating the dialog is waiting for new activity."""
+
+    @property
+    def id(self) -> str:  # pylint: disable=invalid-name
+        return self._id
+
+    @property
+    def telemetry_client(self) -> AgentTelemetryClient:
+        """
+        Gets the telemetry client for logging events.
+        """
+        return self._telemetry_client
+
+    @telemetry_client.setter
+    def telemetry_client(self, value: AgentTelemetryClient) -> None:
+        """
+        Sets the telemetry client for logging events.
+        """
+        if value is None:
+            self._telemetry_client = NullTelemetryClient()
+        else:
+            self._telemetry_client = value
+
+    @abstractmethod
+    async def begin_dialog(
+        self, dialog_context: "DialogContext", options: object = None
+    ):
+        """
+        Method called when a new dialog has been pushed onto the stack and is being activated.
+        :param dialog_context: The dialog context for the current turn of conversation.
+        :param options: (Optional) additional argument(s) to pass to the dialog being started.
+        """
+        raise NotImplementedError()
+
+    async def continue_dialog(self, dialog_context: "DialogContext"):
+        """
+        Method called when an instance of the dialog is the "current" dialog and the
+        user replies with a new activity. The dialog will generally continue to receive the user's
+        replies until it calls either `end_dialog()` or `begin_dialog()`.
+        If this method is NOT implemented then the dialog will automatically be ended when the user replies.
+        :param dialog_context: The dialog context for the current turn of conversation.
+        :return:
+        """
+        # By default just end the current dialog.
+        return await dialog_context.end_dialog(None)
+
+    async def resume_dialog(  # pylint: disable=unused-argument
+        self, dialog_context: "DialogContext", reason: DialogReason, result: object
+    ):
+        """
+        Method called when an instance of the dialog is being returned to from another
+        dialog that was started by the current instance using `begin_dialog()`.
+        If this method is NOT implemented then the dialog will be automatically ended with a call
+        to `end_dialog()`. Any result passed from the called dialog will be passed
+        to the current dialog's parent. If there are no more parent dialogs on the stack then
+        processing of the turn will end.
+        :param dialog_context: The dialog context for the current turn of conversation.
+        :param reason: Reason why the dialog resumed.
+        :param result: (Optional) value returned from the dialog that was called.
+        :return:
+        """
+        # By default just end the current dialog and return result to parent.
+        return await dialog_context.end_dialog(result)
+
+    async def reprompt_dialog(  # pylint: disable=unused-argument
+        self, context: TurnContext, instance: DialogInstance
+    ):
+        """Called when the dialog should re-prompt the user for input.
+
+        Override this method to send a repeat of the most recent prompt activity.
+        The default implementation is a no-op.
+
+        :param context: The context for the current turn.
+        :param instance: The dialog instance on the stack.
+        """
+        # No-op by default
+        return
+
+    async def end_dialog(  # pylint: disable=unused-argument
+        self, context: TurnContext, instance: DialogInstance, reason: DialogReason
+    ):
+        """Called when the dialog is ending. Override to perform cleanup or send an
+        EndOfConversation activity.
+
+        The default implementation is a no-op; subclasses should call ``super()``
+        only if they need the no-op behaviour to remain in derived chains.
+
+        :param context: The context for the current turn.
+        :param instance: The dialog instance being ended.
+        :param reason: Why the dialog is ending (EndCalled, CancelCalled, or ReplaceCalled).
+        """
+        # No-op by default
+        return
+
+    def get_version(self) -> str:
+        """Gets a string that uniquely describes this dialog's version. Changing the version
+        indicates that a stored instance of the dialog may be incompatible with the current
+        definition. By default this returns the dialog's ID.
+
+        :return: Version string for this dialog.
+        """
+        return self.id
+
+    async def on_dialog_event(
+        self, dialog_context: "DialogContext", dialog_event: DialogEvent
+    ) -> bool:
+        """
+        Called when an event has been raised, using `DialogContext.emitEvent()`, by either the current dialog or a
+         dialog that the current dialog started.
+        :param dialog_context: The dialog context for the current turn of conversation.
+        :param dialog_event: The event being raised.
+        :return: True if the event is handled by the current dialog and bubbling should stop.
+        """
+        # Before bubble
+        handled = await self._on_pre_bubble_event(dialog_context, dialog_event)
+
+        # Bubble as needed
+        if (not handled) and dialog_event.bubble and dialog_context.parent:
+            handled = await dialog_context.parent.emit_event(
+                dialog_event.name, dialog_event.value, True, False
+            )
+
+        # Post bubble
+        if not handled:
+            handled = await self._on_post_bubble_event(dialog_context, dialog_event)
+
+        return handled
+
+    async def _on_pre_bubble_event(  # pylint: disable=unused-argument
+        self, dialog_context: "DialogContext", dialog_event: DialogEvent
+    ) -> bool:
+        """
+        Called before an event is bubbled to its parent.
+        :param dialog_context: The dialog context for the current turn of conversation.
+        :param dialog_event: The event being raised.
+        :return: Whether the event is handled by the current dialog and further processing should stop.
+        """
+        return False
+
+    async def _on_post_bubble_event(  # pylint: disable=unused-argument
+        self, dialog_context: "DialogContext", dialog_event: DialogEvent
+    ) -> bool:
+        """
+        Called after an event was bubbled to all parents and wasn't handled.
+        :param dialog_context: The dialog context for the current turn of conversation.
+        :param dialog_event: The event being raised.
+        :return: Whether the event is handled by the current dialog and further processing should stop.
+        """
+        return False
+
+    def _on_compute_id(self) -> str:
+        """
+        Computes an unique ID for a dialog.
+        :return: An unique ID for a dialog
+        """
+        return self.__class__.__name__
+
+    def _register_source_location(
+        self, path: str, line_number: int
+    ):  # pylint: disable=unused-argument
+        """
+        Registers a SourceRange in the provided location.
+        :param path: The path to the source file.
+        :param line_number: The line number where the source will be located on the file.
+        """
+        if path:
+            pass

microsoft_agents/hosting/dialogs/dialog_component_registration.py

@@ -0,0 +1,52 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Iterable
+
+from microsoft_agents.hosting.dialogs.memory import (
+    ComponentMemoryScopesBase,
+    ComponentPathResolversBase,
+    PathResolverBase,
+)
+from microsoft_agents.hosting.dialogs.memory.scopes import (
+    TurnMemoryScope,
+    SettingsMemoryScope,
+    DialogMemoryScope,
+    DialogContextMemoryScope,
+    DialogClassMemoryScope,
+    ClassMemoryScope,
+    MemoryScope,
+    ThisMemoryScope,
+    ConversationMemoryScope,
+    UserMemoryScope,
+)
+
+from microsoft_agents.hosting.dialogs.memory.path_resolvers import (
+    AtAtPathResolver,
+    AtPathResolver,
+    DollarPathResolver,
+    HashPathResolver,
+    PercentPathResolver,
+)
+
+
+class DialogsComponentRegistration(
+    ComponentMemoryScopesBase, ComponentPathResolversBase
+):
+    def get_memory_scopes(self) -> Iterable[MemoryScope]:
+        yield TurnMemoryScope()
+        yield SettingsMemoryScope()
+        yield DialogMemoryScope()
+        yield DialogContextMemoryScope()
+        yield DialogClassMemoryScope()
+        yield ClassMemoryScope()
+        yield ThisMemoryScope()
+        yield ConversationMemoryScope()
+        yield UserMemoryScope()
+
+    def get_path_resolvers(self) -> Iterable[PathResolverBase]:
+        yield AtAtPathResolver()
+        yield AtPathResolver()
+        yield DollarPathResolver()
+        yield HashPathResolver()
+        yield PercentPathResolver()

microsoft_agents/hosting/dialogs/dialog_container.py

@@ -0,0 +1,31 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from .dialog import Dialog
+from .dialog_set import DialogSet
+
+if TYPE_CHECKING:
+    from .dialog_context import DialogContext
+
+
+class DialogContainer(Dialog, ABC):
+
+    def __init__(self, dialog_id: str):
+        super().__init__(dialog_id)
+        self.dialogs = DialogSet()
+
+    @abstractmethod
+    def create_child_context(self, dialog_context: DialogContext) -> DialogContext:
+        """
+        Creates the inner dialog context for the active child dialog, if there is one.
+        :param dialog_context: The parent dialog context.
+        :return: The child dialog context, or None if there is no active child.
+        """
+        raise NotImplementedError(
+            "DialogContainer.create_child_context(): not implemented."
+        )