Improving method signatures and typing annotations for storage providers

[Rodrigo Brandão (rodrigobr-msft)]

This pull request refactors and improves the storage core and storage providers in the Microsoft Agents Hosting SDK. It introduces better abstractions, adds type safety, improves error handling, and enhances code documentation. The changes also reorganize transcript-related modules for clarity and maintainability.

Core Storage API Improvements

• Refactored the Storage class to be an abstract base class (ABC) instead of a protocol, enforcing implementation of required methods and improving type safety. All methods now require explicit types, and docstrings and error handling were added throughout. [1] [2] [3] [4]
• Updated the StoreItem base class to enforce abstract serialization/deserialization methods and improved type hints and documentation.
• Improved the MemoryStorage implementation with better docstrings, stricter type requirements, and clearer error messages. [1] [2]
• Added a type alias module _type_aliases.py to centralize JSON type definitions.

Error Handling Enhancements

• Refactored error handling utilities to use clearer type hints, improved the error filter mechanism, and made status code error filtering more robust. [1] [2] [3]

Transcript Module Reorganization

• Moved transcript-related classes into a new transcript subpackage for better modularity and maintainability. Updated import statements and __init__.py files accordingly. [1] [2] [3] [4]

Storage Provider Improvements

• Improved the BlobStorage and CosmosDBStorage providers by adding comprehensive docstrings, better error handling, and stricter type requirements for methods. (F7e4d248L11R11, [1] [2] [3] [4] [5]

These changes significantly improve code clarity, maintainability, and reliability across the storage subsystem.

[Copilot]

Pull request overview

This pull request refactors the storage subsystem in the Microsoft Agents Hosting SDK to improve type-safety and API clarity (notably by making Storage an ABC with stricter signatures), while also reorganizing transcript logging/storage into a dedicated storage.transcript subpackage and updating providers/tests accordingly.

Changes:

• Converted Storage/StoreItem toward stricter abstract contracts and updated callers/tests to pass explicit target_cls.
• Reorganized transcript-related implementations into microsoft_agents.hosting.core.storage.transcript (new subpackage + updated imports).
• Tightened error-handling utilities typing and improved storage provider docstrings/annotations (Blob/Cosmos).

Reviewed changes

Copilot reviewed 14 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/hosting_core/storage/test_transcript_store_memory.py	Updates imports for transcript module reorg.
tests/hosting_core/storage/test_transcript_logger_middleware.py	Updates imports for transcript module reorg.
tests/hosting_core/app/state/test_state.py	Updates Storage.read() usage to pass target_cls.
tests/_common/storage/utils.py	Adjusts shared CRUD test expectations for new storage API/error behavior.
libraries/microsoft-agents-storage-cosmos/microsoft_agents/storage/cosmos/cosmos_db_storage.py	Aligns Cosmos storage read/write/delete internals with new typing/error-handling patterns.
libraries/microsoft-agents-storage-blob/microsoft_agents/storage/blob/blob_storage.py	Improves typing/docstrings for blob provider and updates read deserialization path.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript/transcript_store.py	Introduces an abstract transcript store interface (currently needs fixes to match concrete stores).
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript/transcript_memory_store.py	Adds an in-memory transcript store implementation returning PagedResult.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript/transcript_logger.py	Updates middleware send pipeline typing to return list[ResourceResponse].
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript/transcript_info.py	Adds TranscriptInfo model for transcript listing.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript/transcript_file_store.py	Adds file-based transcript store (JSONL transcripts + paging).
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript/init.py	Exposes transcript subpackage public API surface.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/store_item.py	Makes StoreItem a clearer abstract base with required serialization methods.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/storage.py	Converts Storage to ABC and centralizes bulk ops via AsyncStorageBase.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/memory_storage.py	Updates memory storage to the stricter target_cls-based read contract.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/error_handling.py	Refines typing for ignore_error and status-code filtering helpers.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/_type_aliases.py	Adds centralized JSON type alias + header.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/init.py	Re-exports transcript items via the new subpackage boundary.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 18 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/storage.py:84

• AsyncStorageBase.read no longer validates that target_cls is provided. Even though it is typed as type[StoreItemT], callers can still pass None at runtime, which will later fail with a less helpful AttributeError inside provider code. Adding an explicit check keeps the error message consistent and easier to diagnose.

    async def read(
        self, keys: list[str], *, target_cls: type[StoreItemT], **kwargs
    ) -> dict[str, StoreItemT]:
        """
        Reads multiple items from storage.

        :param keys: A list of keys to read.
        :param target_cls: The class of the StoreItem to deserialize the data into.
        :return: A dictionary of key to StoreItem.
        :raises ValueError: If keys is empty.
        """
        if not keys:
            raise ValueError("Storage.read(): Keys are required when reading.")

        with spans.StorageRead(len(keys)):

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/memory_storage.py:47

• MemoryStorage.read now assumes target_cls is always valid and has from_json_to_store_item. If target_cls is accidentally passed as None or an incompatible type at runtime, the current code will raise a raw AttributeError without context. Adding a small validation + wrapping the AttributeError makes the failure mode consistent with BlobStorage and easier to debug.

        if not keys:
            raise ValueError("Storage.read(): Keys are required when reading.")

        result: dict[str, StoreItemT] = {}
        async with self._lock:
            for key in keys:
                if key == "":
                    raise ValueError("MemoryStorage.read(): key cannot be empty")
                if key in self._memory:
                    result[key] = target_cls.from_json_to_store_item(self._memory[key])

[Copilot]

Pull request overview

Copilot reviewed 14 out of 18 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/storage.py:83

• AsyncStorageBase.read no longer validates target_cls. Since Python type hints aren’t enforced at runtime, passing target_cls=None will now fail later with a cryptic AttributeError inside providers. Add an explicit guard to raise a clear ValueError (matching the method contract).

        if not keys:
            raise ValueError("Storage.read(): Keys are required when reading.")

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/memory_storage.py:39

• MemoryStorage.read also removed the target_cls validation. If callers pass target_cls=None, this will currently fail later when calling target_cls.from_json_to_store_item(...). Add an explicit guard to raise a clear ValueError.

        if not keys:
            raise ValueError("Storage.read(): Keys are required when reading.")