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

microsoft_agents/hosting/dialogs/dialog_manager.py

@@ -0,0 +1,189 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from datetime import datetime, timedelta
+from threading import Lock
+from typing import cast
+
+from microsoft_agents.hosting.core import (
+    ChannelAdapter,
+    ConversationState,
+    UserState,
+    TurnContext,
+    ClaimsIdentity,
+)
+
+from .dialog import Dialog
+from .dialog_context import DialogContext
+from .dialog_extensions import DialogExtensions
+from .dialog_set import DialogSet
+from .dialog_state import DialogState
+from .dialog_manager_result import DialogManagerResult
+from .models.dialog_turn_status import DialogTurnStatus
+from .models.dialog_turn_result import DialogTurnResult
+
+
+class DialogManager:
+    """
+    Class which runs the dialog system.
+    """
+
+    def __init__(
+        self,
+        root_dialog: Dialog | None = None,
+        dialog_state_property: str = "DialogState",
+    ):
+        """
+        Initializes an instance of the DialogManager class.
+        :param root_dialog: Root dialog to use.
+        :param dialog_state_property: Alternate name for the dialog_state property. (Default is "DialogState").
+        """
+        self.last_access = "_lastAccess"
+        self._root_dialog_id = ""
+        self._dialog_state_property = dialog_state_property
+        self._lock = Lock()
+
+        # Gets or sets root dialog to use to start conversation.
+        self.root_dialog = root_dialog
+
+        # Gets or sets the ConversationState.
+        self.conversation_state: ConversationState | None = None
+
+        # Gets or sets the UserState.
+        self.user_state: UserState | None = None
+
+        # Gets InitialTurnState collection to copy into the TurnState on every turn.
+        self.initial_turn_state = {}
+
+        # Gets or sets global dialogs that you want to have be callable.
+        self.dialogs = DialogSet()
+
+        # Gets or sets (optional) number of milliseconds to expire the bot's state after.
+        self.expire_after: int | None = None
+
+    async def on_turn(self, context: TurnContext) -> DialogManagerResult:
+        """
+        Runs dialog system in the context of a TurnContext.
+        :param context: turn context.
+        :return:
+        """
+        # Lazy initialize RootDialog so it can refer to assets like LG function templates
+        if not self._root_dialog_id:
+            with self._lock:
+                if not self._root_dialog_id:
+                    if self.root_dialog is None:
+                        raise ValueError("DialogManager: root_dialog cannot be None.")
+                    self._root_dialog_id = self.root_dialog.id
+                    self.dialogs.add(self.root_dialog)
+
+        # Preload TurnState with DM TurnState.
+        for key, val in self.initial_turn_state.items():
+            context.turn_state[key] = val
+
+        # Register DialogManager with TurnState.
+        context.turn_state[DialogManager.__name__] = self
+
+        # Resolve ConversationState
+        conversation_state_name = ConversationState.__name__
+        if self.conversation_state is None:
+            if conversation_state_name not in context.turn_state:
+                raise Exception(
+                    f"Unable to get an instance of {conversation_state_name} from turn_context. "
+                    f"Please ensure ConversationState is available in turn_state."
+                )
+            self.conversation_state = cast(
+                ConversationState, context.turn_state[conversation_state_name]
+            )
+        else:
+            context.turn_state[conversation_state_name] = self.conversation_state
+
+        # Resolve UserState (optional)
+        user_state_name = UserState.__name__
+        if self.user_state is None:
+            self.user_state = cast(
+                UserState | None, context.turn_state.get(user_state_name, None)
+            )
+        else:
+            context.turn_state[user_state_name] = self.user_state
+
+        # Create property accessors
+        last_access_property = self.conversation_state.create_property(self.last_access)
+        last_access: datetime = cast(
+            datetime, await last_access_property.get(context, datetime.now)
+        )
+
+        # Check for expired conversation
+        if self.expire_after is not None and (
+            datetime.now() - last_access
+        ) >= timedelta(milliseconds=float(self.expire_after)):
+            # Clear conversation state
+            self.conversation_state.clear(context)
+
+        last_access = datetime.now()
+        await last_access_property.set(context, last_access)
+
+        # Get dialog stack
+        dialogs_property = self.conversation_state.create_property(
+            self._dialog_state_property
+        )
+        dialog_state: DialogState = cast(
+            DialogState, await dialogs_property.get(context, DialogState)
+        )
+
+        # Create DialogContext
+        dialog_context = DialogContext(self.dialogs, context, dialog_state)
+
+        # Call the common dialog "continue/begin" execution pattern shared with the classic RunAsync extension method
+        turn_result = (
+            await DialogExtensions._internal_run(  # pylint: disable=protected-access
+                context, self._root_dialog_id, dialog_context
+            )
+        )
+
+        # Save ConversationState changes
+        await self.conversation_state.save(context, False)
+
+        # Save UserState changes if present
+        if self.user_state is not None:
+            await self.user_state.save(context, False)
+
+        return DialogManagerResult(turn_result=turn_result)
+
+    @staticmethod
+    def is_from_parent_to_skill(turn_context: TurnContext) -> bool:
+        """
+        Determines if this turn is a 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
+    def should_send_end_of_conversation_to_parent(
+        context: TurnContext, turn_result: DialogTurnResult
+    ) -> bool:
+        """
+        Helper to determine if we should send an EndOfConversation to the parent or not.
+        """
+        if not (
+            turn_result.status == DialogTurnStatus.Complete
+            or turn_result.status == DialogTurnStatus.Cancelled
+        ):
+            # The dialog is still going, don't return EoC.
+            return False
+
+        return DialogManager.is_from_parent_to_skill(context)
+
+    @staticmethod
+    def get_active_dialog_context(dialog_context: DialogContext) -> DialogContext:
+        """
+        Recursively walk up the DC stack to find the active DC.
+        """
+        return DialogExtensions._get_active_dialog_context(  # pylint: disable=protected-access
+            dialog_context
+        )

microsoft_agents/hosting/dialogs/dialog_manager_result.py

@@ -0,0 +1,17 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from dataclasses import dataclass, field
+
+from microsoft_agents.activity import Activity
+
+from .models.dialog_turn_result import DialogTurnResult
+from .persisted_state import PersistedState
+
+
+@dataclass
+class DialogManagerResult:
+
+    turn_result: DialogTurnResult | None = None
+    activities: list[Activity] = field(default_factory=list)
+    persisted_state: PersistedState | None = None

microsoft_agents/hosting/dialogs/dialog_set.py

@@ -0,0 +1,174 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+import inspect
+from hashlib import sha256
+from typing import TYPE_CHECKING
+
+from microsoft_agents.hosting.core import TurnContext, StatePropertyAccessor
+
+from ._telemetry_client import AgentTelemetryClient, NullTelemetryClient
+from .dialog import Dialog
+from .dialog_state import DialogState
+
+if TYPE_CHECKING:
+    from .dialog_context import DialogContext
+
+
+class DialogSet:
+    def __init__(self, dialog_state: StatePropertyAccessor | None = None):
+        # pylint: disable=import-outside-toplevel
+        if dialog_state is None:
+            current_frame = inspect.currentframe()
+            frame = current_frame.f_back if current_frame is not None else None
+            try:
+                # try to access the caller's "self"
+                try:
+                    self_obj = frame.f_locals["self"] if frame is not None else None
+                    if self_obj is None:
+                        raise KeyError
+                except KeyError:
+                    raise TypeError("DialogSet(): dialog_state cannot be None.")
+                # Only ComponentDialog / DialogContainer / DialogManager can initialize with None dialog_state
+                from .component_dialog import ComponentDialog
+                from .dialog_manager import DialogManager
+                from .dialog_container import DialogContainer
+
+                if not isinstance(
+                    self_obj, (ComponentDialog, DialogContainer, DialogManager)
+                ):
+                    raise TypeError("DialogSet(): dialog_state cannot be None.")
+            finally:
+                # make sure to clean up the frame at the end to avoid ref cycles
+                del frame
+
+        self._dialog_state = dialog_state
+        self.__telemetry_client = NullTelemetryClient()
+
+        self._dialogs: dict[str, Dialog] = {}
+        self._version: str | None = None
+
+    @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 all dialogs in this set.
+        """
+        if value is None:
+            self.__telemetry_client = NullTelemetryClient()
+        else:
+            self.__telemetry_client = value
+
+        for dialog in self._dialogs.values():
+            dialog.telemetry_client = self.__telemetry_client
+        self._version = None
+
+    def get_version(self) -> str:
+        """
+        Gets a unique string which represents the combined versions of all dialogs in this dialogset.
+        Version will change when any of the child dialogs version changes.
+        """
+        if not self._version:
+            version = ""
+            for _, dialog in self._dialogs.items():
+                aux_version = dialog.get_version()
+                if aux_version:
+                    version += aux_version
+
+            self._version = sha256(version.encode()).hexdigest()
+
+        return self._version
+
+    def add(self, dialog: Dialog):
+        """
+        Adds a new dialog to the set and returns the added dialog.
+        :param dialog: The dialog to add.
+        """
+        if dialog is None or not isinstance(dialog, Dialog):
+            raise TypeError(
+                "DialogSet.add(): dialog cannot be None and must be a Dialog or derived class."
+            )
+
+        if dialog.id in self._dialogs:
+            raise TypeError(
+                "DialogSet.add(): A dialog with an id of '%s' already added."
+                % dialog.id
+            )
+
+        self._dialogs[dialog.id] = dialog
+        self._version = None
+
+        return self
+
+    async def create_context(self, turn_context: TurnContext) -> "DialogContext":
+        """Creates a DialogContext for this set using the given TurnContext.
+
+        Loads persisted dialog state via the StatePropertyAccessor provided at construction
+        and wraps it in a new DialogContext. Raises RuntimeError if the set was created
+        without a StatePropertyAccessor (e.g. from within a ComponentDialog).
+
+        :param turn_context: The current turn context.
+        :return: A DialogContext backed by the loaded dialog state.
+        """
+        # This import prevents circular dependency issues
+        # pylint: disable=import-outside-toplevel
+        from .dialog_context import DialogContext
+
+        if turn_context is None:
+            raise TypeError("DialogSet.create_context(): turn_context cannot be None.")
+
+        if not self._dialog_state:
+            raise RuntimeError(
+                "DialogSet.create_context(): DialogSet created with a null IStatePropertyAccessor."
+            )
+
+        from typing import cast as _cast  # pylint: disable=import-outside-toplevel
+
+        state: DialogState = _cast(
+            DialogState,
+            await self._dialog_state.get(turn_context, lambda: DialogState()),
+        )
+
+        return DialogContext(self, turn_context, state)
+
+    async def find(self, dialog_id: str | None) -> Dialog | None:
+        """
+        Finds a dialog that was previously added to the set using add(dialog)
+        :param dialog_id: ID of the dialog/prompt to look up.
+        :return: The dialog if found, otherwise null.
+        """
+        if not dialog_id:
+            raise TypeError("DialogSet.find(): dialog_id cannot be None.")
+
+        if dialog_id in self._dialogs:
+            return self._dialogs[dialog_id]
+
+        return None
+
+    def find_dialog(self, dialog_id: str | None) -> Dialog | None:
+        """
+        Finds a dialog that was previously added to the set using add(dialog).
+        Synchronous version of find().
+        :param dialog_id: ID of the dialog/prompt to look up.
+        :return: The dialog if found, otherwise null.
+        """
+        if not dialog_id:
+            raise TypeError("DialogSet.find_dialog(): dialog_id cannot be None.")
+
+        if dialog_id in self._dialogs:
+            return self._dialogs[dialog_id]
+
+        return None
+
+    def __str__(self):
+        if not self._dialogs:
+            return "dialog set empty!"
+        return " ".join(map(str, self._dialogs.keys()))

microsoft_agents/hosting/dialogs/dialog_state.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from dataclasses import dataclass, field
+
+from .models.dialog_instance import DialogInstance
+
+
+@dataclass
+class DialogState:
+    """
+    Contains state information for the dialog stack.
+    """
+
+    dialog_stack: list[DialogInstance] = field(default_factory=list)
+
+    def __str__(self):
+        if not self.dialog_stack:
+            return "dialog stack empty!"
+        return " ".join(map(str, self.dialog_stack))

microsoft_agents/hosting/dialogs/memory/__init__.py

@@ -0,0 +1,24 @@
+# coding=utf-8
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+from .dialog_path import DialogPath
+from .dialog_state_manager import DialogStateManager
+from .dialog_state_manager_configuration import DialogStateManagerConfiguration
+from .component_memory_scopes_base import ComponentMemoryScopesBase
+from .component_path_resolvers_base import ComponentPathResolversBase
+from .path_resolver_base import PathResolverBase
+from . import scope_path
+
+__all__ = [
+    "DialogPath",
+    "DialogStateManager",
+    "DialogStateManagerConfiguration",
+    "ComponentMemoryScopesBase",
+    "ComponentPathResolversBase",
+    "PathResolverBase",
+    "scope_path",
+]

microsoft_agents/hosting/dialogs/memory/component_memory_scopes_base.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from .scopes.memory_scope import MemoryScope
+
+
+class ComponentMemoryScopesBase(ABC):
+
+    @abstractmethod
+    def get_memory_scopes(self) -> Iterable[MemoryScope]:
+        raise NotImplementedError()

microsoft_agents/hosting/dialogs/memory/component_path_resolvers_base.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from .path_resolver_base import PathResolverBase
+
+
+class ComponentPathResolversBase(ABC):
+
+    @abstractmethod
+    def get_path_resolvers(self) -> Iterable[PathResolverBase]:
+        raise NotImplementedError()

microsoft_agents/hosting/dialogs/memory/dialog_path.py

@@ -0,0 +1,33 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+
+class DialogPath:
+    # Counter of emitted events.
+    EVENT_COUNTER = "dialog.eventCounter"
+
+    # Currently expected properties.
+    EXPECTED_PROPERTIES = "dialog.expectedProperties"
+
+    # Default operation to use for entities where there is no identified operation entity.
+    DEFAULT_OPERATION = "dialog.defaultOperation"
+
+    # Last surfaced entity ambiguity event.
+    LAST_EVENT = "dialog.lastEvent"
+
+    # Currently required properties.
+    REQUIRED_PROPERTIES = "dialog.requiredProperties"
+
+    # Number of retries for the current Ask.
+    RETRIES = "dialog.retries"
+
+    # Last intent.
+    LAST_INTENT = "dialog.lastIntent"
+
+    # Last trigger event: defined in FormEvent, ask, clarifyEntity etc..
+    LAST_TRIGGER_EVENT = "dialog.lastTriggerEvent"
+
+    @staticmethod
+    def get_property_name(prop: str) -> str:
+        """Get the property name without the 'dialog.' prefix, if it exists."""
+        return prop.removeprefix("dialog.")