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

microsoft_agents/hosting/dialogs/memory/path_resolvers/at_path_resolver.py

@@ -0,0 +1,44 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .alias_path_resolver import AliasPathResolver
+
+
+class AtPathResolver(AliasPathResolver):
+    _DELIMITERS = [".", "["]
+
+    def __init__(self):
+        super().__init__(alias="@", prefix="")
+
+        self._PREFIX = "turn.recognized.entities."  # pylint: disable=invalid-name
+
+    def transform_path(self, path: str):
+        if not path:
+            raise TypeError(f"Expecting: path, but received None")
+
+        path = path.strip()
+        if (
+            path.startswith("@")
+            and len(path) > 1
+            and AtPathResolver._is_path_char(path[1])
+        ):
+            end = AtPathResolver._index_of_any(path[1:], AtPathResolver._DELIMITERS)
+            if end == -1:
+                end = len(path) - 1
+            # +1 to offset the leading '@' we skipped in the search
+            end += 1
+
+            prop = path[1:end]
+            suffix = path[end:]
+            path = f"{self._PREFIX}{prop}.first(){suffix}"
+
+        return path
+
+    @staticmethod
+    def _index_of_any(string: str, elements_to_search_for) -> int:
+        for element in elements_to_search_for:
+            index = string.find(element)
+            if index != -1:
+                return index
+
+        return -1

microsoft_agents/hosting/dialogs/memory/path_resolvers/dollar_path_resolver.py

@@ -0,0 +1,9 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .alias_path_resolver import AliasPathResolver
+
+
+class DollarPathResolver(AliasPathResolver):
+    def __init__(self):
+        super().__init__(alias="$", prefix="dialog.")

microsoft_agents/hosting/dialogs/memory/path_resolvers/hash_path_resolver.py

@@ -0,0 +1,9 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .alias_path_resolver import AliasPathResolver
+
+
+class HashPathResolver(AliasPathResolver):
+    def __init__(self):
+        super().__init__(alias="#", prefix="turn.recognized.intents.")

microsoft_agents/hosting/dialogs/memory/path_resolvers/percent_path_resolver.py

@@ -0,0 +1,9 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .alias_path_resolver import AliasPathResolver
+
+
+class PercentPathResolver(AliasPathResolver):
+    def __init__(self):
+        super().__init__(alias="%", prefix="class.")

microsoft_agents/hosting/dialogs/memory/scope_path.py

@@ -0,0 +1,38 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+# User memory scope root path.
+# <remarks>This property is deprecated, use ScopePath.User instead.</remarks>
+USER = "user"
+
+# Conversation memory scope root path.
+# <remarks>This property is deprecated, use ScopePath.Conversation instead.</remark
+CONVERSATION = "conversation"
+
+# Dialog memory scope root path.
+# <remarks>This property is deprecated, use ScopePath.Dialog instead.</remark
+DIALOG = "dialog"
+
+# DialogClass memory scope root path.
+# <remarks>This property is deprecated, use ScopePath.DialogClass instead.</remark
+DIALOG_CLASS = "dialogclass"
+
+# This memory scope root path.
+# <remarks>This property is deprecated, use ScopePath.This instead.</remark
+THIS = "this"
+
+# Class memory scope root path.
+# <remarks>This property is deprecated, use ScopePath.Class instead.</remarks>
+CLASS = "class"
+
+# Settings memory scope root path.
+# <remarks>This property is deprecated, use ScopePath.Settings instead.</remarks>
+
+SETTINGS = "settings"
+
+# Turn memory scope root path.
+# <remarks>This property is deprecated, use ScopePath.Turn instead.</remarks>
+TURN = "turn"
+
+# DialogContext memory scope root path.
+DIALOG_CONTEXT = "dialogContext"

microsoft_agents/hosting/dialogs/memory/scopes/__init__.py

@@ -0,0 +1,31 @@
+# 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 .bot_state_memory_scope import BotStateMemoryScope
+from .class_memory_scope import ClassMemoryScope
+from .conversation_memory_scope import ConversationMemoryScope
+from .dialog_class_memory_scope import DialogClassMemoryScope
+from .dialog_context_memory_scope import DialogContextMemoryScope
+from .dialog_memory_scope import DialogMemoryScope
+from .memory_scope import MemoryScope
+from .settings_memory_scope import SettingsMemoryScope
+from .this_memory_scope import ThisMemoryScope
+from .turn_memory_scope import TurnMemoryScope
+from .user_memory_scope import UserMemoryScope
+
+__all__ = [
+    "BotStateMemoryScope",
+    "ClassMemoryScope",
+    "ConversationMemoryScope",
+    "DialogClassMemoryScope",
+    "DialogContextMemoryScope",
+    "DialogMemoryScope",
+    "MemoryScope",
+    "SettingsMemoryScope",
+    "ThisMemoryScope",
+    "TurnMemoryScope",
+    "UserMemoryScope",
+]

microsoft_agents/hosting/dialogs/memory/scopes/bot_state_memory_scope.py

@@ -0,0 +1,66 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...dialog_context import DialogContext
+
+from microsoft_agents.hosting.core import AgentState
+
+from .memory_scope import MemoryScope
+
+
+class BotStateMemoryScope(MemoryScope):
+    def __init__(self, agent_state_type: type[AgentState], name: str):
+        super().__init__(name, include_in_snapshot=True)
+        self.agent_state_type = agent_state_type
+
+    def get_memory(self, dialog_context: "DialogContext") -> object:
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        # In the new SDK, after AgentState.load() is called, turn_state contains
+        # a CachedAgentState (not the AgentState itself) at the context_service_key.
+        # Handle both cases: AgentState (before load) and CachedAgentState (after load).
+        turn_state_value = dialog_context.context.turn_state.get(
+            self.agent_state_type.__name__
+        )
+        if turn_state_value is None:
+            return None
+        if isinstance(turn_state_value, AgentState):
+            cached_state = turn_state_value.get_cached_state(dialog_context.context)
+            # If get_cached_state() returned AgentState itself (load() skipped turn_state update)
+            # or None, the state memory is not yet available.
+            if cached_state is None or isinstance(cached_state, AgentState):
+                return None
+            return cached_state.state
+        # It's a CachedAgentState (stored after load() was called)
+        return getattr(turn_state_value, "state", None)
+
+    def set_memory(self, dialog_context: "DialogContext", memory: object):
+        raise RuntimeError("You cannot replace the root AgentState object")
+
+    async def load(self, dialog_context: "DialogContext", force: bool = False):
+        agent_state: AgentState | None = self._get_agent_state(dialog_context)
+
+        if agent_state:
+            await agent_state.load(dialog_context.context, force)
+
+    async def save_changes(self, dialog_context: "DialogContext", force: bool = False):
+        agent_state: AgentState | None = self._get_agent_state(dialog_context)
+
+        if agent_state:
+            await agent_state.save(dialog_context.context, force)
+
+    def _get_agent_state(self, dialog_context: "DialogContext") -> AgentState | None:
+        value = dialog_context.context.turn_state.get(
+            self.agent_state_type.__name__, None
+        )
+        # After AgentState.load(), the turn_state key holds CachedAgentState, not AgentState.
+        # Return None in that case so callers don't try to call AgentState methods on it.
+        if isinstance(value, AgentState):
+            return value
+        return None

microsoft_agents/hosting/dialogs/memory/scopes/class_memory_scope.py

@@ -0,0 +1,64 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...dialog_context import DialogContext
+
+from collections import namedtuple
+
+from microsoft_agents.hosting.dialogs.memory import scope_path
+
+from .memory_scope import MemoryScope
+
+
+class ClassMemoryScope(MemoryScope):
+    def __init__(self):
+        super().__init__(scope_path.CLASS, include_in_snapshot=False)
+
+    def get_memory(self, dialog_context: "DialogContext") -> object:
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        # if active dialog is a container dialog then "dialogclass" binds to it.
+        if dialog_context.active_dialog:
+            dialog = dialog_context.find_dialog_sync(dialog_context.active_dialog.id)
+            if dialog:
+                return ClassMemoryScope._bind_to_dialog_context(dialog, dialog_context)
+
+        return None
+
+    def set_memory(self, dialog_context: "DialogContext", memory: object):
+        raise Exception(
+            f"{self.__class__.__name__}.set_memory not supported (read only)"
+        )
+
+    @staticmethod
+    def _bind_to_dialog_context(obj, dialog_context: "DialogContext") -> object:
+        clone = {}
+        for prop in dir(obj):
+            # don't process double underscore attributes
+            if prop[:1] != "_":
+                prop_value = getattr(obj, prop)
+                if not callable(prop_value):
+                    # the only objects
+                    if hasattr(prop_value, "try_get_value"):
+                        clone[prop] = prop_value.try_get_value(dialog_context.state)
+                    elif hasattr(prop_value, "__dict__") and not isinstance(
+                        prop_value, type(prop_value)
+                    ):
+                        clone[prop] = ClassMemoryScope._bind_to_dialog_context(
+                            prop_value, dialog_context
+                        )
+                    else:
+                        clone[prop] = prop_value
+        if clone:
+            ReadOnlyObject = namedtuple(  # pylint: disable=invalid-name
+                "ReadOnlyObject", clone
+            )
+            return ReadOnlyObject(**clone)
+
+        return None

microsoft_agents/hosting/dialogs/memory/scopes/conversation_memory_scope.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from microsoft_agents.hosting.core import ConversationState
+
+from microsoft_agents.hosting.dialogs.memory import scope_path
+from .bot_state_memory_scope import BotStateMemoryScope
+
+
+class ConversationMemoryScope(BotStateMemoryScope):
+    def __init__(self):
+        super().__init__(ConversationState, scope_path.CONVERSATION)

microsoft_agents/hosting/dialogs/memory/scopes/dialog_class_memory_scope.py

@@ -0,0 +1,52 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...dialog_context import DialogContext
+
+from copy import deepcopy
+
+from microsoft_agents.hosting.dialogs.memory import scope_path
+
+from .memory_scope import MemoryScope
+
+
+class DialogClassMemoryScope(MemoryScope):
+    def __init__(self):
+        # pylint: disable=import-outside-toplevel
+        super().__init__(scope_path.DIALOG_CLASS, include_in_snapshot=False)
+
+        # This import is to avoid circular dependency issues
+        from microsoft_agents.hosting.dialogs.dialog_container import DialogContainer
+
+        self._dialog_container_cls = DialogContainer
+
+    def get_memory(self, dialog_context: "DialogContext") -> object:
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        # if active dialog is a container dialog then "dialogclass" binds to it.
+        if dialog_context.active_dialog:
+            dialog = dialog_context.find_dialog_sync(dialog_context.active_dialog.id)
+            if isinstance(dialog, self._dialog_container_cls):
+                return deepcopy(dialog)
+
+        # Otherwise we always bind to parent, or if there is no parent the active dialog
+        parent_id = (
+            dialog_context.parent.active_dialog.id
+            if dialog_context.parent and dialog_context.parent.active_dialog
+            else None
+        )
+        active_id = (
+            dialog_context.active_dialog.id if dialog_context.active_dialog else None
+        )
+        return deepcopy(dialog_context.find_dialog_sync(parent_id or active_id))
+
+    def set_memory(self, dialog_context: "DialogContext", memory: object):
+        raise Exception(
+            f"{self.__class__.__name__}.set_memory not supported (read only)"
+        )

microsoft_agents/hosting/dialogs/memory/scopes/dialog_context_memory_scope.py

@@ -0,0 +1,68 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...dialog_context import DialogContext
+
+from microsoft_agents.hosting.dialogs.memory import scope_path
+
+from .memory_scope import MemoryScope
+
+
+class DialogContextMemoryScope(MemoryScope):
+    def __init__(self):
+        # pylint: disable=invalid-name
+        super().__init__(scope_path.DIALOG_CONTEXT, include_in_snapshot=False)
+        # Stack name.
+        self.STACK = "stack"
+
+        # Active dialog name.
+        self.ACTIVE_DIALOG = "activeDialog"
+
+        # Parent name.
+        self.PARENT = "parent"
+
+    def get_memory(self, dialog_context: "DialogContext") -> object:
+        """
+        Gets the backing memory for this scope.
+        """
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        memory = {}
+        stack = list([])
+        current_dc = dialog_context
+
+        # go to leaf node
+        while current_dc.child:
+            current_dc = current_dc.child
+
+        while current_dc:
+            # (PORTERS NOTE: javascript stack is reversed with top of stack on end)
+            for item in current_dc.stack:
+                # filter out ActionScope items because they are internal bookkeeping.
+                if not item.id.startswith("ActionScope["):
+                    stack.append(item.id)
+
+            current_dc = current_dc.parent
+
+        # top of stack is stack[0].
+        memory[self.STACK] = stack
+        memory[self.ACTIVE_DIALOG] = (
+            dialog_context.active_dialog.id if dialog_context.active_dialog else None
+        )
+        memory[self.PARENT] = (
+            dialog_context.parent.active_dialog.id
+            if dialog_context.parent and dialog_context.parent.active_dialog
+            else None
+        )
+        return memory
+
+    def set_memory(self, dialog_context: "DialogContext", memory: object):
+        raise Exception(
+            f"{self.__class__.__name__}.set_memory not supported (read only)"
+        )

microsoft_agents/hosting/dialogs/memory/scopes/dialog_memory_scope.py

@@ -0,0 +1,75 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...dialog_context import DialogContext
+
+from microsoft_agents.hosting.dialogs.memory import scope_path
+
+from .memory_scope import MemoryScope
+
+
+class DialogMemoryScope(MemoryScope):
+    def __init__(self):
+        # pylint: disable=import-outside-toplevel
+        super().__init__(scope_path.DIALOG)
+
+        # This import is to avoid circular dependency issues
+        from microsoft_agents.hosting.dialogs.dialog_container import DialogContainer
+
+        self._dialog_container_cls = DialogContainer
+
+    def get_memory(self, dialog_context: "DialogContext") -> object:
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        # if active dialog is a container dialog then "dialog" binds to it.
+        if dialog_context.active_dialog:
+            dialog = dialog_context.find_dialog_sync(dialog_context.active_dialog.id)
+            if isinstance(dialog, self._dialog_container_cls):
+                return dialog_context.active_dialog.state
+
+        # Otherwise we always bind to parent, or if there is no parent the active dialog
+        parent_state = (
+            dialog_context.parent.active_dialog.state
+            if dialog_context.parent and dialog_context.parent.active_dialog
+            else None
+        )
+        dc_state = (
+            dialog_context.active_dialog.state if dialog_context.active_dialog else None
+        )
+        return parent_state or dc_state
+
+    def set_memory(self, dialog_context: "DialogContext", memory: object):
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        if memory is None:
+            raise TypeError(f"Expecting: memory object, but received None")
+
+        # If active dialog is a container dialog then "dialog" binds to it.
+        # Otherwise the "dialog" will bind to the dialogs parent assuming it is a container.
+        parent: DialogContext | None = dialog_context
+        if not self.is_container(parent) and self.is_container(parent.parent):
+            parent = parent.parent
+
+        # If there's no active dialog then throw an error.
+        assert parent is not None
+        if not parent.active_dialog:
+            raise Exception(
+                "Cannot set DialogMemoryScope. There is no active dialog or parent dialog in the context"
+            )
+
+        parent.active_dialog.state = memory  # type: ignore[assignment]
+
+    def is_container(self, dialog_context: "DialogContext | None"):
+        if dialog_context and dialog_context.active_dialog:
+            dialog = dialog_context.find_dialog_sync(dialog_context.active_dialog.id)
+            if isinstance(dialog, self._dialog_container_cls):
+                return True
+
+        return False

microsoft_agents/hosting/dialogs/memory/scopes/memory_scope.py

@@ -0,0 +1,91 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...dialog_context import DialogContext
+
+from abc import ABC, abstractmethod
+
+
+class MemoryScope(ABC):
+    def __init__(self, name: str, include_in_snapshot: bool = True):
+        # <summary>
+        # Gets or sets name of the scope.
+        # </summary>
+        # <value>
+        # Name of the scope.
+        # </value>
+        self.include_in_snapshot = include_in_snapshot
+        # <summary>
+        # Gets or sets a value indicating whether this memory should be included in snapshot.
+        # </summary>
+        # <value>
+        # True or false.
+        # </value>
+        self.name = name
+
+    # <summary>
+    # Get the backing memory for this scope.
+    # </summary>
+    # <param name="dc">dc.</param>
+    # <returns>memory for the scope.</returns>
+    @abstractmethod
+    def get_memory(
+        self, dialog_context: "DialogContext"
+    ) -> object:  # pylint: disable=unused-argument
+        raise NotImplementedError()
+
+    # <summary>
+    # Changes the backing object for the memory scope.
+    # </summary>
+    # <param name="dc">dc.</param>
+    # <param name="memory">memory.</param>
+    @abstractmethod
+    def set_memory(
+        self, dialog_context: "DialogContext", memory: object
+    ):  # pylint: disable=unused-argument
+        raise NotImplementedError()
+
+    # <summary>
+    # Populates the state cache for this <see cref="BotState"/> from the storage layer.
+    # </summary>
+    # <param name="dialogContext">The dialog context object for this turn.</param>
+    # <param name="force">Optional, <c>true</c> to overwrite any existing state cache
+    # or <c>false</c> to load state from storage only if the cache doesn't already exist.</param>
+    # <param name="cancellationToken">A cancellation token that can be used by other objects
+    # or threads to receive notice of cancellation.</param>
+    # <returns>A task that represents the work queued to execute.</returns>
+    async def load(
+        self, dialog_context: "DialogContext", force: bool = False
+    ):  # pylint: disable=unused-argument
+        return
+
+    # <summary>
+    # Writes the state cache for this <see cref="BotState"/> to the storage layer.
+    # </summary>
+    # <param name="dialogContext">The dialog context object for this turn.</param>
+    # <param name="force">Optional, <c>true</c> to save the state cache to storage
+    # or <c>false</c> to save state to storage only if a property in the cache has changed.</param>
+    # <param name="cancellationToken">A cancellation token that can be used by other objects
+    # or threads to receive notice of cancellation.</param>
+    # <returns>A task that represents the work queued to execute.</returns>
+    async def save_changes(
+        self, dialog_context: "DialogContext", force: bool = False
+    ):  # pylint: disable=unused-argument
+        return
+
+    # <summary>
+    # Deletes any state in storage and the cache for this <see cref="BotState"/>.
+    # </summary>
+    # <param name="dialogContext">The dialog context object for this turn.</param>
+    # <param name="cancellationToken">A cancellation token that can be used by other objects
+    # or threads to receive notice of cancellation.</param>
+    # <returns>A task that represents the work queued to execute.</returns>
+    async def delete(
+        self, dialog_context: "DialogContext"
+    ):  # pylint: disable=unused-argument
+        return

microsoft_agents/hosting/dialogs/memory/scopes/settings_memory_scope.py

@@ -0,0 +1,38 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...dialog_context import DialogContext
+
+from microsoft_agents.hosting.dialogs.memory import scope_path
+
+from .memory_scope import MemoryScope
+
+
+class SettingsMemoryScope(MemoryScope):
+    def __init__(self):
+        super().__init__(scope_path.SETTINGS)
+        self._empty_settings = {}
+        self.include_in_snapshot = False
+
+    def get_memory(self, dialog_context: "DialogContext") -> object:
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        settings: dict | None = dialog_context.context.turn_state.get(  # type: ignore[assignment]
+            scope_path.SETTINGS, None
+        )
+
+        if not settings:
+            settings = self._empty_settings
+
+        return settings
+
+    def set_memory(self, dialog_context: "DialogContext", memory: object):
+        raise Exception(
+            f"{self.__class__.__name__}.set_memory not supported (read only)"
+        )

microsoft_agents/hosting/dialogs/memory/scopes/this_memory_scope.py

@@ -0,0 +1,36 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...dialog_context import DialogContext
+
+from microsoft_agents.hosting.dialogs.memory import scope_path
+
+from .memory_scope import MemoryScope
+
+
+class ThisMemoryScope(MemoryScope):
+    def __init__(self):
+        super().__init__(scope_path.THIS)
+
+    def get_memory(self, dialog_context: "DialogContext") -> object:
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        return (
+            dialog_context.active_dialog.state if dialog_context.active_dialog else None
+        )
+
+    def set_memory(self, dialog_context: "DialogContext", memory: object):
+        if not dialog_context:
+            raise TypeError(f"Expecting: DialogContext, but received None")
+
+        if memory is None:
+            raise TypeError(f"Expecting: object, but received None")
+
+        assert dialog_context.active_dialog is not None
+        dialog_context.active_dialog.state = memory  # type: ignore[assignment]