microsoft-agents-hosting-core 0.4.0.dev6__py3-none-any.whl → 0.4.0.dev10__py3-none-any.whl

microsoft_agents/hosting/core/storage/__init__.py

@@ -1,5 +1,24 @@
 from .store_item import StoreItem
 from .storage import Storage, AsyncStorageBase
 from .memory_storage import MemoryStorage
+from .transcript_info import TranscriptInfo
+from .transcript_logger import (
+    TranscriptLogger,
+    ConsoleTranscriptLogger,
+    TranscriptLoggerMiddleware,
+    FileTranscriptLogger,
+)
+from .transcript_store import TranscriptStore
 
-__all__ = ["StoreItem", "Storage", "AsyncStorageBase", "MemoryStorage"]
+__all__ = [
+    "StoreItem",
+    "Storage",
+    "AsyncStorageBase",
+    "MemoryStorage",
+    "TranscriptInfo",
+    "TranscriptLogger",
+    "ConsoleTranscriptLogger",
+    "TranscriptLoggerMiddleware",
+    "TranscriptStore",
+    "FileTranscriptLogger",
+]

microsoft_agents/hosting/core/storage/transcript_info.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from datetime import datetime, timezone
+from dataclasses import dataclass
+
+
+@dataclass
+class TranscriptInfo:
+    channel_id: str = ""
+    conversation_id: str = ""
+    created_on: datetime = datetime.min.replace(tzinfo=timezone.utc)

microsoft_agents/hosting/core/storage/transcript_logger.py

@@ -0,0 +1,209 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+import copy
+import random
+import string
+import json
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from queue import Queue
+from typing import Awaitable, Callable, List, Optional
+
+from microsoft_agents.activity import Activity, ChannelAccount
+from microsoft_agents.activity.activity import ConversationReference
+from microsoft_agents.activity.activity_types import ActivityTypes
+from microsoft_agents.activity.conversation_reference import ActivityEventNames
+from microsoft_agents.hosting.core.middleware_set import Middleware, TurnContext
+
+
+class TranscriptLogger(ABC):
+    @abstractmethod
+    async def log_activity(self, activity: Activity) -> None:
+        """
+        Asynchronously logs an activity.
+
+        :param activity: The activity to log.
+        """
+        pass
+
+
+class ConsoleTranscriptLogger(TranscriptLogger):
+    """
+    ConsoleTranscriptLogger writes activities to Console output. This is a DEBUG class, intended for testing
+    and log tailing
+    """
+
+    async def log_activity(self, activity: Activity) -> None:
+        """Log an activity to the transcript.
+        :param activity:Activity being logged.
+        """
+        if not activity:
+            raise TypeError("Activity is required")
+
+        json_data = activity.model_dump_json()
+        parsed = json.loads(json_data)
+        print(json.dumps(parsed, indent=4))
+
+
+class FileTranscriptLogger(TranscriptLogger):
+    """
+    A TranscriptLogger implementation that appends each activity as JSON to a file. This class appends
+    each activity to the given file using basic formatting. This is a DEBUG class, intended for testing
+    and log tailing.
+    """
+
+    def __init__(self, file_path: str, encoding: Optional[str] = "utf-8"):
+        """
+        Initializes the FileTranscriptLogger and opens the file for appending.
+
+        :param file_path: Path to the transcript log file.
+        :param encoding: File encoding (default: utf-8).
+        """
+        self.file_path = file_path
+        self.encoding = encoding
+
+        # Open file in append mode to ensure it exists
+        self._file = open(self.file_path, "a", encoding=self.encoding)
+
+    async def log_activity(self, activity: Activity) -> None:
+        """
+        Appends the given activity as a JSON line to the file. This method pretty-prints the JSON for readability, which makes
+        it non-performant. For production scenarios, consider a more efficient logging mechanism.
+
+        :param activity: The Activity object to log.
+        """
+        if not activity:
+            raise TypeError("Activity is required")
+
+        json_data = activity.model_dump_json()
+        parsed = json.loads(json_data)
+
+        self._file.write(json.dumps(parsed, indent=4))
+
+        # As this is a logging / debugging class, we want to ensure the data is written out immediately. This is another
+        # consideration that makes this class non-performant for production scenarios.
+        self._file.flush()
+
+    def __del__(self):
+        if hasattr(self, "_file"):
+            self._file.close()
+
+
+class TranscriptLoggerMiddleware(Middleware):
+    """Logs incoming and outgoing activities to a TranscriptLogger."""
+
+    def __init__(self, logger: TranscriptLogger):
+        if not logger:
+            raise TypeError(
+                "TranscriptLoggerMiddleware requires a TranscriptLogger instance."
+            )
+
+        self.logger = logger
+
+    async def on_turn(
+        self, context: TurnContext, logic: Callable[[TurnContext], Awaitable]
+    ):
+        """Initialization for middleware.
+        :param context: Context for the current turn of conversation with the user.
+        :param logic: Function to call at the end of the middleware chain.
+        """
+        transcript = Queue()
+        activity = context.activity
+        # Log incoming activity at beginning of turn
+        if activity:
+            if not activity.from_property:
+                activity.from_property = ChannelAccount()
+            if not activity.from_property.role:
+                activity.from_property.role = "user"
+
+            # We should not log ContinueConversation events used by skills to initialize the middleware.
+            if not (
+                context.activity.type == ActivityTypes.event
+                and context.activity.name == ActivityEventNames.continue_conversation
+            ):
+                await self._queue_activity(transcript, copy.copy(activity))
+
+        # hook up onSend pipeline
+        # pylint: disable=unused-argument
+        async def send_activities_handler(
+            ctx: TurnContext,
+            activities: List[Activity],
+            next_send: Callable[[], Awaitable[None]],
+        ):
+            # Run full pipeline
+            responses = await next_send()
+            for index, activity in enumerate(activities):
+                cloned_activity = copy.copy(activity)
+                if responses and index < len(responses):
+                    cloned_activity.id = responses[index].id
+
+                # For certain channels, a ResourceResponse with an id is not always sent to the bot.
+                # This fix uses the timestamp on the activity to populate its id for logging the transcript
+                # If there is no outgoing timestamp, the current time for the bot is used for the activity.id
+                if not cloned_activity.id:
+                    alphanumeric = string.ascii_lowercase + string.digits
+                    prefix = "g_" + "".join(
+                        random.choice(alphanumeric) for i in range(5)
+                    )
+                    epoch = datetime.fromtimestamp(0, timezone.utc)
+                    if cloned_activity.timestamp:
+                        reference = cloned_activity.timestamp
+                    else:
+                        reference = datetime.now(timezone.utc)
+                    delta = (reference - epoch).total_seconds() * 1000
+                    cloned_activity.id = f"{prefix}{delta}"
+                await self._queue_activity(transcript, cloned_activity)
+            return responses
+
+        context.on_send_activities(send_activities_handler)
+
+        # hook up update activity pipeline
+        async def update_activity_handler(
+            ctx: TurnContext, activity: Activity, next_update: Callable[[], Awaitable]
+        ):
+            # Run full pipeline
+            response = await next_update()
+            update_activity = copy.copy(activity)
+            update_activity.type = ActivityTypes.message_update
+            await self._queue_activity(transcript, update_activity)
+            return response
+
+        context.on_update_activity(update_activity_handler)
+
+        # hook up delete activity pipeline
+        async def delete_activity_handler(
+            ctx: TurnContext,
+            reference: ConversationReference,
+            next_delete: Callable[[], Awaitable],
+        ):
+            # Run full pipeline
+            await next_delete()
+
+            delete_msg = Activity(
+                type=ActivityTypes.message_delete, id=reference.activity_id
+            )
+            deleted_activity: Activity = TurnContext.apply_conversation_reference(
+                delete_msg, reference, False
+            )
+            await self._queue_activity(transcript, deleted_activity)
+
+        context.on_delete_activity(delete_activity_handler)
+
+        if logic:
+            await logic()
+
+        # Flush transcript at end of turn
+        while not transcript.empty():
+            activity = transcript.get()
+            if activity is None:
+                break
+            await self.logger.log_activity(activity)
+            transcript.task_done()
+
+    async def _queue_activity(self, transcript: Queue, activity: Activity) -> None:
+        """Logs the activity.
+        :param transcript: transcript.
+        :param activity: Activity to log.
+        """
+        transcript.put(activity)

microsoft_agents/hosting/core/storage/transcript_memory_store.py

@@ -0,0 +1,154 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from threading import Lock
+from datetime import datetime, timezone
+from typing import List
+from .transcript_logger import TranscriptLogger
+from .transcript_info import TranscriptInfo
+from microsoft_agents.activity import Activity
+
+
+class TranscriptMemoryStore(TranscriptLogger):
+    """
+    An in-memory implementation of the TranscriptLogger for storing and retrieving activities.
+
+    This class is thread-safe and stores all activities in a list. It supports logging activities,
+    retrieving activities for a specific channel and conversation, and filtering by timestamp.
+    Activities with a None timestamp are treated as the earliest possible datetime.
+
+    Note: This class is intended for testing and prototyping purposes only. It does not persist
+    data and is not suitable for production use. This store will also grow without bound over
+    time, making it especially unsuited for production use.
+    """
+
+    def __init__(self):
+        """
+        Initializes the TranscriptMemoryStore.
+        """
+        self._transcript = []
+        self.lock = Lock()
+
+    async def log_activity(self, activity: Activity) -> None:
+        """
+        Asynchronously logs an activity to the in-memory transcript.
+
+        :param activity: The Activity object to log. Must have a valid conversation and conversation id.
+        :raises ValueError: If activity, activity.conversation, or activity.conversation.id is None.
+        """
+        if not activity:
+            raise ValueError("Activity cannot be None")
+        if not activity.conversation:
+            raise ValueError("Activity.Conversation cannot be None")
+        if not activity.conversation.id:
+            raise ValueError("Activity.Conversation.id cannot be None")
+
+        with self.lock:
+            self._transcript.append(activity)
+
+    async def get_transcript_activities(
+        self,
+        channel_id: str,
+        conversation_id: str,
+        continuation_token: str = None,
+        start_date: datetime = datetime.min.replace(tzinfo=timezone.utc),
+    ) -> tuple[list[Activity], str]:
+        """
+        Retrieves activities for a given channel and conversation, optionally filtered by start_date.
+
+        :param channel_id: The channel ID to filter activities.
+        :param conversation_id: The conversation ID to filter activities.
+        :param continuation_token: (Unused) Token for pagination.
+        :param start_date: Only activities with timestamp >= start_date are returned. None timestamps are treated as datetime.min.
+        :return: A tuple containing the filtered list of Activity objects and a continuation token (always None).
+        :raises ValueError: If channel_id or conversation_id is None.
+        """
+        if not channel_id:
+            raise ValueError("channel_id cannot be None")
+        if not conversation_id:
+            raise ValueError("conversation_id cannot be None")
+
+        with self.lock:
+            # Get the activities that match on channel and conversation id
+            relevant_activities = [
+                a
+                for a in self._transcript
+                if a.channel_id == channel_id
+                and a.conversation
+                and a.conversation.id == conversation_id
+            ]
+            # sort these by timestamp, treating None as datetime.min
+            sorted_relevant_activities = sorted(
+                relevant_activities,
+                key=lambda a: (
+                    a.timestamp
+                    if a.timestamp is not None
+                    else datetime.min.replace(tzinfo=timezone.utc)
+                ),
+            )
+            # grab the ones bigger than the requested start date, treating None as datetime.min
+            filtered_sorted_activities = [
+                a
+                for a in sorted_relevant_activities
+                if (
+                    a.timestamp
+                    if a.timestamp is not None
+                    else datetime.min.replace(tzinfo=timezone.utc)
+                )
+                >= start_date
+            ]
+
+            return filtered_sorted_activities, None
+
+    async def delete_transcript(self, channel_id: str, conversation_id: str) -> None:
+        """
+        Deletes all activities for a given channel and conversation from the in-memory transcript.
+
+        :param channel_id: The channel ID whose transcript should be deleted.
+        :param conversation_id: The conversation ID whose transcript should be deleted.
+        :raises ValueError: If channel_id or conversation_id is None.
+        """
+        if not channel_id:
+            raise ValueError("channel_id cannot be None")
+        if not conversation_id:
+            raise ValueError("conversation_id cannot be None")
+
+        with self.lock:
+            self._transcript = [
+                a
+                for a in self._transcript
+                if not (
+                    a.channel_id == channel_id
+                    and a.conversation
+                    and a.conversation.id == conversation_id
+                )
+            ]
+
+    async def list_transcripts(
+        self, channel_id: str, continuation_token: str = None
+    ) -> tuple[list[TranscriptInfo], str]:
+        """
+        Lists all transcripts (unique conversation IDs) for a given channel.
+
+        :param channel_id: The channel ID to list transcripts for.
+        :param continuation_token: (Unused) Token for pagination.
+        :return: A tuple containing a list of TranscriptInfo objects and a continuation token (always None).
+        :raises ValueError: If channel_id is None.
+        """
+        if not channel_id:
+            raise ValueError("channel_id cannot be None")
+
+        with self.lock:
+            relevant_activities = [
+                a for a in self._transcript if a.channel_id == channel_id
+            ]
+            conversations = set(
+                a.conversation.id
+                for a in relevant_activities
+                if a.conversation and a.conversation.id
+            )
+            transcript_infos = [
+                TranscriptInfo(channel_id=channel_id, conversation_id=conversation_id)
+                for conversation_id in conversations
+            ]
+            return transcript_infos, None

microsoft_agents/hosting/core/storage/transcript_store.py

@@ -0,0 +1,52 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from microsoft_agents.activity import Activity
+from .transcript_info import TranscriptInfo
+from .transcript_logger import TranscriptLogger
+
+
+class TranscriptStore(TranscriptLogger):
+    @abstractmethod
+    async def get_transcript_activities(
+        self,
+        channel_id: str,
+        conversation_id: str,
+        continuation_token: str = None,
+        start_date: datetime = datetime.min.replace(tzinfo=timezone.utc),
+    ) -> tuple[list[Activity], str]:
+        """
+        Asynchronously retrieves activities from a transcript.
+
+        :param channel_id: The channel ID of the conversation.
+        :param conversation_id: The conversation ID.
+        :param continuation_token: (Optional) A token to continue retrieving activities from a specific point.
+        :param start_date: (Optional) The start date to filter activities.
+        :return: A tuple containing a list of activities and a continuation token.
+        """
+        pass
+
+    @abstractmethod
+    async def list_transcripts(
+        self, channel_id: str, continuation_token: str = None
+    ) -> tuple[list[TranscriptInfo, str]]:
+        """
+        Asynchronously lists transcripts for a given channel.
+
+        :param channel_id: The channel ID to list transcripts for.
+        :param continuation_token: (Optional) A token to continue listing transcripts from a specific point.
+        :return: A tuple containing a list of transcripts and a continuation token.
+        """
+        pass
+
+    @abstractmethod
+    async def delete_transcript(self, channel_id: str, conversation_id: str) -> None:
+        """
+        Asynchronously deletes a transcript.
+
+        :param channel_id: The channel ID of the conversation.
+        :param conversation_id: The conversation ID.
+        """
+        pass

{microsoft_agents_hosting_core-0.4.0.dev6.dist-info → microsoft_agents_hosting_core-0.4.0.dev10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-hosting-core
-Version: 0.4.0.dev6
+Version: 0.4.0.dev10
 Summary: Core library for Microsoft Agents
 Author: Microsoft Corporation
 Project-URL: Homepage, https://github.com/microsoft/Agents
@@ -8,7 +8,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
-Requires-Dist: microsoft-agents-activity==0.4.0.dev6
+Requires-Dist: microsoft-agents-activity==0.4.0.dev10
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: isodate>=0.6.1
 Requires-Dist: azure-core>=1.30.0

{microsoft_agents_hosting_core-0.4.0.dev6.dist-info → microsoft_agents_hosting_core-0.4.0.dev10.dist-info}/RECORD

@@ -70,14 +70,17 @@ microsoft_agents/hosting/core/state/__init__.py,sha256=yckKi1wg_86ng-DL9Q3R49QiW
 microsoft_agents/hosting/core/state/agent_state.py,sha256=-6kHxVCl6oUT-XjDXkPOPw0fD227Uy3zNzqMInwFeJc,12891
 microsoft_agents/hosting/core/state/state_property_accessor.py,sha256=kpiNnzkZ6el-oRITRbRkk1Faa_CPFxpJQdvSGxIJP70,1392
 microsoft_agents/hosting/core/state/user_state.py,sha256=zEigX-sroNAyoQAxQjG1OgmJQKjk1zOkdeqylFg7M2E,1484
-microsoft_agents/hosting/core/storage/__init__.py,sha256=wq8zlkoPG6I8PfMvdGPN-tNCdP905W7jylFrmJ-GF6o,196
-microsoft_agents/hosting/core/storage/_storage_test_utils.py,sha256=QwavT0mjdknKHr_70HUZflksA4OVsfxBbS_JoVWIoDc,18315
+microsoft_agents/hosting/core/storage/__init__.py,sha256=X2jWX0qc2YdFNhwOct5Q7VJ9Q5VnOpKB0RqC7HG2_Qs,611
 microsoft_agents/hosting/core/storage/_type_aliases.py,sha256=VCKtjiCBrhEsGSm3zVVSSccdoiY02GYhABvrLjhAcz8,72
 microsoft_agents/hosting/core/storage/error_handling.py,sha256=zH34d7s4pJG_uajpBWhrtTpH2eMy88kSKaqvOqtbgzY,1265
 microsoft_agents/hosting/core/storage/memory_storage.py,sha256=NADem1wQE1MOG1qMriYw4NjILHEBDbIG5HT6wvHfG2M,2353
 microsoft_agents/hosting/core/storage/storage.py,sha256=vft_Kw4pkzo8NnBEyDx7gAn1Ndg2I9ePaxnuxbKVHzs,3227
 microsoft_agents/hosting/core/storage/store_item.py,sha256=4LSkuI0H0lgWig88YoHFn6BP8Bx44YbyuvqBvaBNdEM,276
-microsoft_agents_hosting_core-0.4.0.dev6.dist-info/METADATA,sha256=9P5bB42a9BG9qWtho8HblRQU_ekDoeguBilsjWLXgtI,584
-microsoft_agents_hosting_core-0.4.0.dev6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-microsoft_agents_hosting_core-0.4.0.dev6.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
-microsoft_agents_hosting_core-0.4.0.dev6.dist-info/RECORD,,
+microsoft_agents/hosting/core/storage/transcript_info.py,sha256=5VN32j99tshChAffvuZ6D3GH3ABCZsQGHC_bYDAwFOk,328
+microsoft_agents/hosting/core/storage/transcript_logger.py,sha256=PxAZTZVFRC2q_i1JABo-JFOPEv9QyXCMe5wZdiiq6_g,8007
+microsoft_agents/hosting/core/storage/transcript_memory_store.py,sha256=xdX4CtyDczN5jCoi-ZtXzBZq52ahsk3IQ_Y6qkmub8U,6323
+microsoft_agents/hosting/core/storage/transcript_store.py,sha256=ka74o0WvI5GhMZcFqSxVdamBhGzZcDZe6VNkG-sMy74,1944
+microsoft_agents_hosting_core-0.4.0.dev10.dist-info/METADATA,sha256=jLXmnVD1NnbBccGs57HhKye8o-c_d2ikm-hYHbjCckg,586
+microsoft_agents_hosting_core-0.4.0.dev10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_hosting_core-0.4.0.dev10.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
+microsoft_agents_hosting_core-0.4.0.dev10.dist-info/RECORD,,

microsoft_agents/hosting/core/storage/_storage_test_utils.py

@@ -1,508 +0,0 @@
-import pytest
-import gc
-from copy import deepcopy
-from abc import ABC
-from typing import Any
-
-from .storage import Storage
-from .store_item import StoreItem
-from ._type_aliases import JSON
-from .memory_storage import MemoryStorage
-
-
-class MockStoreItem(StoreItem):
-    """Test implementation of StoreItem for testing purposes"""
-
-    def __init__(self, data: dict[str, Any] = None):
-        self.data = data or {}
-
-    def store_item_to_json(self) -> JSON:
-        return self.data
-
-    @staticmethod
-    def from_json_to_store_item(json_data: JSON) -> "MockStoreItem":
-        return MockStoreItem(json_data)
-
-    def __eq__(self, other):
-        if not isinstance(other, MockStoreItem):
-            return False
-        return self.data == other.data
-
-    def __repr__(self):
-        return f"MockStoreItem({self.data})"
-
-    def deepcopy(self):
-        return MockStoreItem(my_deepcopy(self.data))
-
-
-class MockStoreItemB(MockStoreItem):
-    """Another test implementation of StoreItem for testing purposes"""
-
-    def __init__(self, data: dict[str, Any] = None, other_field: bool = True):
-        super().__init__(data or {})
-        self.other_field = other_field
-
-    def store_item_to_json(self) -> JSON:
-        return [self.data, self.other_field]
-
-    @staticmethod
-    def from_json_to_store_item(json_data: JSON) -> "MockStoreItem":
-        return MockStoreItemB(json_data[0], json_data[1])
-
-    def __eq__(self, other):
-        if not isinstance(other, MockStoreItemB):
-            return False
-        return self.data == other.data and self.other_field == other.other_field
-
-    def deepcopy(self):
-        return MockStoreItemB(my_deepcopy(self.data), self.other_field)
-
-
-def my_deepcopy(original):
-    """Deep copy an object, including StoreItem instances."""
-
-    iter_obj = None
-    if isinstance(original, list):
-        iter_obj = enumerate(original)
-    elif isinstance(original, dict):
-        iter_obj = original.items()
-    elif isinstance(original, MockStoreItem):
-        return original.deepcopy()
-    else:
-        return deepcopy(original)
-
-    obj = {} if isinstance(original, dict) else ([None] * len(original))
-    for key, value in iter_obj:
-        obj[key] = my_deepcopy(value)
-    return obj
-
-
-def subsets(lst, n=-1):
-    """Generate all subsets of a list up to length n. If n is -1, all subsets are generated.
-
-    Only contiguous subsets are generated.
-    """
-    if n < 0:
-        n = len(lst)
-    subsets = []
-    for i in range(len(lst) + 1):
-        for j in range(0, i):
-            if 1 <= i - j <= n:
-                subsets.append(lst[j:i])
-    return subsets
-
-
-# bootstrapping class to compare against
-# if this class is correct, then the tests are correct
-class StorageBaseline(Storage):
-    """ "A simple in-memory storage implementation for testing purposes."""
-
-    def __init__(self, initial_data: dict = None):
-        self._memory = deepcopy(initial_data) or {}
-        self._key_history = set(initial_data.keys()) if initial_data else set()
-
-    def read(self, keys: list[str]) -> dict[str, Any]:
-        self._key_history.update(keys)
-        return {key: self._memory.get(key) for key in keys if key in self._memory}
-
-    def write(self, changes: dict[str, Any]) -> None:
-        self._key_history.update(changes.keys())
-        self._memory.update(changes)
-
-    def delete(self, keys: list[str]) -> None:
-        self._key_history.update(keys)
-        for key in keys:
-            if key in self._memory:
-                del self._memory[key]
-
-    async def equals(self, other) -> bool:
-        """
-        Compare the items for all keys seen by this mock instance.
-
-        Note:
-        This is an extra safety measure, and I've made the
-        executive decision to not test this method itself
-        because passing tests with calls to this method
-        is also dependent on the correctness of other
-        aspects, based on the other assertions in the tests.
-        """
-        for key in self._key_history:
-            if key not in self._memory:
-                if len(await other.read([key], target_cls=MockStoreItem)) > 0:
-                    breakpoint()
-                    return False  # key should not exist in other
-                continue
-
-            # key exists in baseline instance, so let's see if the values match
-            item = self._memory.get(key, None)
-            target_cls = type(item)
-            res = await other.read([key], target_cls=target_cls)
-
-            if key not in res or item != res[key]:
-                breakpoint()
-                return False
-        return True
-
-
-class StorageTestsCommon(ABC):
-    """Common fixtures for Storage implementations."""
-
-    KEY_LIST = [
-        "f",
-        "a!0dslfj",
-        "\\?/#\t\n\r*",
-        "527",
-        "test.txt",
-        "_-__--",
-        "VAR",
-        "None",
-        "multi word key",
-    ]
-
-    READ_KEY_LIST = KEY_LIST + (["5", "20", "100", "nonexistent_key", "-"])
-
-    STATE_LIST = [
-        {key: MockStoreItem({"id": key, "value": f"value{key}"}) for key in subset}
-        for subset in subsets(KEY_LIST, 3)
-        if len(subset) == 3
-    ]
-
-    @pytest.fixture(params=[dict()] + STATE_LIST)
-    def initial_state(self, request):
-        return request.param
-
-    @pytest.fixture(params=KEY_LIST)
-    def key(self, request):
-        return request.param
-
-    @pytest.fixture(
-        params=[subset for subset in subsets(READ_KEY_LIST, 2) if len(subset) == 2]
-    )
-    def keys(self, request):
-        return request.param
-
-    @pytest.fixture(params=subsets(KEY_LIST, 2))
-    def changes(self, request):
-        changes_obj = {}
-        keys = request.param
-        changes_obj["new_key"] = MockStoreItemB(
-            {"field": "new_value_for_new_key"}, True
-        )
-        for i, key in enumerate(keys):
-            if i % 2 == 0:
-                changes_obj[key] = MockStoreItemB(
-                    {"data": f"value{key}"}, (i // 2) % 2 == 0
-                )
-            else:
-                changes_obj[key] = MockStoreItem(
-                    {"id": key, "value": f"new_value_for_{key}"}
-                )
-        changes_obj["new_key_2"] = MockStoreItem({"field": "new_value_for_new_key_2"})
-        return changes_obj
-
-
-class CRUDStorageTests(StorageTestsCommon):
-    """Tests for Storage implementations that support CRUD operations.
-
-    To use, subclass and implement the `storage` method.
-    """
-
-    async def storage(self, initial_data=None, existing=False) -> Storage:
-        """Return a Storage instance to be tested.
-        :param initial_data: The initial data to populate the storage with.
-        :param existing: If True, the storage instance should connect to an existing store.
-        """
-        raise NotImplementedError("Subclasses must implement this")
-
-    @pytest.mark.asyncio
-    async def test_read_individual(self, initial_state, key):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        expected = baseline_storage.read([key])
-        actual = await storage.read([key], target_cls=MockStoreItem)
-        assert actual == expected
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_read(self, initial_state, keys):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        expected = baseline_storage.read(keys)
-        actual = await storage.read(keys, target_cls=MockStoreItem)
-        assert actual == expected
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_read_missing_key(self, initial_state):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        keys = ["5", "20", "100", "nonexistent_key", "-"]
-        expected = baseline_storage.read(keys)
-        actual = await storage.read(keys, target_cls=MockStoreItem)
-        assert actual == expected
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_read_errors(self, initial_state):
-        initial_state_copy = my_deepcopy(initial_state)
-        storage = await self.storage(initial_state)
-        with pytest.raises(ValueError):
-            await storage.read([], target_cls=MockStoreItem)
-        with pytest.raises(ValueError):
-            await storage.read(None, target_cls=MockStoreItem)
-        with pytest.raises(ValueError):
-            await storage.read([""], target_cls=MockStoreItem)
-        with pytest.raises(ValueError):
-            await storage.read(["key"], target_cls=None)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_write_individual(self, initial_state, key):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        change = {key: MockStoreItem({key: f"new_value_for_{key}!"})}
-        baseline_storage.write(change)
-        await storage.write(change)
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_write_individual_different_target_cls(self, initial_state, key):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        change = {
-            key: MockStoreItemB({key: f"new_value_for_{key}!"}, other_field=False)
-        }
-        baseline_storage.write(change)
-        await storage.write(change)
-        assert await baseline_storage.equals(storage)
-        change = {key: MockStoreItemB({key: f"new_{key}"}, other_field=True)}
-        baseline_storage.write(change)
-        await storage.write(change)
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_write_same_values(self, initial_state):
-        if not initial_state:
-            return
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        changes = {key: value for key, value in initial_state.items()}
-        baseline_storage.write(changes)
-        await storage.write(changes)
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_write(self, initial_state, changes):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        baseline_storage.write(changes)
-        await storage.write(changes)
-        assert await baseline_storage.equals(storage)
-        baseline_storage.write(initial_state)
-        if initial_state:
-            await storage.write(initial_state)
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_write_errors(self, initial_state):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        with pytest.raises(ValueError):
-            await storage.write({})
-        with pytest.raises(ValueError):
-            await storage.write(None)
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_delete_individual(self, initial_state, key):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        baseline_storage.delete([key])
-        await storage.delete([key])
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_delete(self, initial_state, keys):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        baseline_storage.delete(keys)
-        await storage.delete(keys)
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_delete_missing_key(self, initial_state):
-        initial_state_copy = my_deepcopy(initial_state)
-        baseline_storage = StorageBaseline(initial_state)
-        storage = await self.storage(initial_state)
-        keys = ["5", "20", "100", "nonexistent_key", "-"]
-        baseline_storage.delete(keys)
-        await storage.delete(keys)
-        assert await baseline_storage.equals(storage)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_delete_errors(self, initial_state):
-        initial_state_copy = my_deepcopy(initial_state)
-        storage = await self.storage(initial_state)
-        with pytest.raises(ValueError):
-            await storage.read([])
-        with pytest.raises(ValueError):
-            await storage.read(None)
-        assert initial_state == initial_state_copy
-
-    @pytest.mark.asyncio
-    async def test_flow(self):
-        baseline_storage = StorageBaseline()
-        storage = await self.storage()
-
-        res = await storage.read(["key"], target_cls=MockStoreItemB)
-        assert len(res) == 0
-        assert await baseline_storage.equals(storage)
-
-        changes = {
-            "key_a": MockStoreItem({"id": "key_a", "value": "value_a"}),
-            "key_b": MockStoreItemB(
-                {"id": "key_b", "value": "value_b"}, other_field=False
-            ),
-        }
-        changes_copy = my_deepcopy(changes)
-
-        baseline_storage.write(changes)
-        await storage.write(changes)
-
-        assert (
-            await storage.read(["key_a"], target_cls=MockStoreItem)
-        ) == baseline_storage.read(["key_a"])
-        assert (
-            await storage.read(["key_b"], target_cls=MockStoreItemB)
-        ) == baseline_storage.read(["key_b"])
-        assert changes_copy == changes
-
-        baseline_storage.delete(["key_a"])
-        await storage.delete(["key_a"])
-        assert await baseline_storage.equals(storage)
-
-        change = {"key_b": MockStoreItem({"id": "key_b", "value": "new_value_b"})}
-        baseline_storage.write(change)
-        await storage.write(change)
-
-        assert await baseline_storage.equals(storage)
-        assert (
-            await storage.read(["key_b"], target_cls=MockStoreItem)
-        ) == baseline_storage.read(["key_b"])
-
-        with pytest.raises(ValueError):
-            await storage.read([], target_cls=MockStoreItem)
-        with pytest.raises(ValueError):
-            await storage.read(["key_b"], target_cls=None)
-
-        change = {
-            "key_c": MockStoreItemB(
-                {"id": "key_c", "value": "value_c"}, other_field=True
-            )
-        }
-        baseline_storage.write(change)
-        await storage.write(change)
-        assert (
-            await storage.read(["key_a", "key_b"], target_cls=MockStoreItem)
-        ) == baseline_storage.read(["key_a", "key_b"])
-        assert (
-            await storage.read(["key_a", "key_c"], target_cls=MockStoreItemB)
-        ) == baseline_storage.read(["key_a", "key_c"])
-
-        item_parent_class = (await storage.read(["key_c"], target_cls=MockStoreItem))[
-            "key_c"
-        ]
-        item_child_class = (await storage.read(["key_c"], target_cls=MockStoreItemB))[
-            "key_c"
-        ]
-        assert item_parent_class.data[0] == item_child_class.data
-        assert item_child_class.other_field == True
-
-        with pytest.raises(ValueError):
-            await storage.write({})
-        with pytest.raises(Exception):
-            await storage.read(["key_b"], target_cls=MockStoreItemB)
-        assert await baseline_storage.equals(storage)
-
-        if not isinstance(storage, MemoryStorage):
-            # if not memory storage, then items should persist
-            del storage
-            gc.collect()
-            storage_alt = await self.storage(existing=True)
-            assert await baseline_storage.equals(storage_alt)
-
-
-class QuickCRUDStorageTests(CRUDStorageTests):
-    """Reduced set of permutations for quicker tests. Useful for debugging."""
-
-    KEY_LIST = ["\\?/#\t\n\r*", "test.txt"]
-
-    READ_KEY_LIST = KEY_LIST + ["nonexistent_key"]
-
-    STATE_LIST = [
-        {key: MockStoreItem({"id": key, "value": f"value{key}"}) for key in KEY_LIST}
-    ]
-
-    @pytest.fixture(params=STATE_LIST)
-    def initial_state(self, request):
-        return request.param
-
-    @pytest.fixture(params=KEY_LIST)
-    def key(self, request):
-        return request.param
-
-    @pytest.fixture(params=[KEY_LIST])
-    def keys(self, request):
-        return request.param
-
-    @pytest.fixture(params=subsets(KEY_LIST, 2))
-    def changes(self, request):
-        changes_obj = {}
-        keys = request.param
-        changes_obj["new_key"] = MockStoreItemB(
-            {"field": "new_value_for_new_key"}, True
-        )
-        for i, key in enumerate(keys):
-            if i % 2 == 0:
-                changes_obj[key] = MockStoreItemB(
-                    {"data": f"value{key}"}, (i // 2) % 2 == 0
-                )
-            else:
-                changes_obj[key] = MockStoreItem(
-                    {"id": key, "value": f"new_value_for_{key}"}
-                )
-        changes_obj["new_key_2"] = MockStoreItem({"field": "new_value_for_new_key_2"})
-        return changes_obj
-
-
-def debug_print(*args):
-    """Print debug information clearly separated in the console."""
-    print("\n" * 2)
-    print("--- DEBUG ---")
-    for arg in args:
-        print("\n" * 2)
-        print(arg)
-    print("\n" * 2)
-    print("--- ----- ---")
-    print("\n" * 2)