nvidia-nat 1.2.0__py3-none-any.whl

nat/llm/utils/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

nat/llm/utils/env_config_value.py

@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from abc import ABC
+from enum import Enum
+
+
+class EnvConfigValueSource(Enum):
+    ENV_DEFAULT = 1
+    CONSTRUCTOR = 2
+    ENV_OVERRIDE = 3
+
+
+class EnvConfigValue(ABC):
+    """
+    A wrapper for a string used as a configuration value which can be loaded from the system environment or injected via
+    the constructor. This class should be subclassed and the class fields `_ENV_KEY` and `_ENV_KEY_OVERRIDE` can be set
+    to enable environment-loading functionality. Convienience properties are available to check from where the value was
+    loaded.
+    """
+
+    _ENV_KEY: str | None = None
+    _ENV_KEY_OVERRIDE: str | None = None
+    _ALLOW_NONE: bool = False
+
+    def __init__(self, value: str | None = None, use_env: bool = True):
+        """
+        Parameters
+        ----------
+        value : str, optional
+            The value to be contained in the EnvConfigValue. If the value is `None`, an attempt will be made to load it
+            from the environment using `_ENV_KEY`. if the `_ENV_KEY_OVERRIDE` field is not `None`, an attempt will be
+            made to load that environment variable in place of the passed-in value.
+        use_env : bool
+            If False, all environment-loading logic will be bypassed and the passed-in value will be used as-is.
+            defaults to True.
+        """
+
+        self._source = EnvConfigValueSource.CONSTRUCTOR
+
+        if use_env:
+            if value is None and self.__class__._ENV_KEY is not None:
+                value = os.environ.get(self.__class__._ENV_KEY, None)
+                self._source = EnvConfigValueSource.ENV_DEFAULT
+
+            if self.__class__._ENV_KEY_OVERRIDE is not None and self.__class__._ENV_KEY_OVERRIDE in os.environ:
+                value = os.environ[self.__class__._ENV_KEY_OVERRIDE]
+                self._source = EnvConfigValueSource.ENV_OVERRIDE
+
+            if not self.__class__._ALLOW_NONE and value is None:
+
+                message = ("value must not be None, but provided value was None and no environment-based default or "
+                           "override was found.")
+
+                if self.__class__._ENV_KEY is None:
+                    raise ValueError(message)
+
+                raise ValueError(
+                    f"{message} Try passing a value to the constructor, or setting the `{self.__class__._ENV_KEY}` "
+                    "environment variable.")
+
+        else:
+            if not self.__class__._ALLOW_NONE and value is None:
+                raise ValueError("value must not be none")
+
+        assert isinstance(value, str) or value is None
+
+        self._value = value
+        self._use_env = use_env
+
+    @property
+    def source(self) -> EnvConfigValueSource:
+        return self._source
+
+    @property
+    def use_env(self) -> bool:
+        return self._use_env
+
+    @property
+    def value(self) -> str | None:
+        return self._value

nat/llm/utils/error.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+IMPORT_ERROR_MESSAGE = (
+    "{package} not found. Install it and other additional dependencies by running the following command:\n")

nat/memory/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+NAT Memory Module
+
+This package provides foundational classes and interfaces
+for managing text-based memory in NAT's LLM-based agents.
+"""

nat/memory/interfaces.py

@@ -0,0 +1,183 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from abc import ABC
+from abc import abstractmethod
+from collections.abc import Callable
+
+from .models import MemoryItem
+
+
+class MemoryEditor(ABC):
+    """
+    Abstract interface for editing and
+    retrieving memory items.
+
+    A MemoryEditor is responsible for adding, searching, and
+    removing MemoryItems.
+
+    Implementations may integrate with
+    vector stores or other indexing backends.
+    """
+
+    @abstractmethod
+    async def add_items(self, items: list[MemoryItem]) -> None:
+        """
+        Insert multiple MemoryItems into the memory.
+
+        Args:
+            items (list[MemoryItem]): The items to be added.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def search(self, query: str, top_k: int = 5, **kwargs) -> list[MemoryItem]:
+        """
+        Retrieve items relevant to the given query.
+        Relevance criteria depend on implementation.
+
+        Args:
+            query (str): The query string to match.
+            top_k (int): Maximum number of items to return.
+            kwargs (dict): Keyword arguments to pass to the search method.
+
+        Returns:
+            list[MemoryItem]: The most relevant MemoryItems.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def remove_items(self, **kwargs) -> None:
+        """
+        Remove items. Additional parameters
+        needed for deletion can be specified in keyword arguments.
+
+        Args:
+            kwargs (dict): Keyword arguments to pass to the remove-items method.
+        """
+        raise NotImplementedError
+
+
+class MemoryIOBase(ABC):
+    """
+    Base abstract class for I/O operations
+    on memory, providing a common interface for
+
+    MemoryReader and MemoryWriter to interact
+    with a MemoryEditor.
+
+    Concrete subclasses should hold a
+    reference to a MemoryEditor instance.
+    """
+
+    def __init__(self, editor: MemoryEditor) -> None:
+        self._editor = editor
+
+
+class MemoryReader(MemoryIOBase):
+    """
+    Responsible for retrieving MemoryItems
+    from the MemoryEditor based on context or queries.
+    """
+
+    @abstractmethod
+    async def retrieve(self, context: str, top_k: int = 5) -> list[MemoryItem]:
+        """
+        Retrieve a subset of
+        MemoryItems relevant to the provided context.
+
+        Args:
+            context (str): A string representing
+            the current user context or query.
+            top_k (int): Maximum number of items to return.
+
+        Returns:
+            list[MemoryItem]: Relevant MemoryItems.
+        """
+        raise NotImplementedError
+
+
+class MemoryWriter(MemoryIOBase):
+    """
+    Responsible for converting new observations
+    (textual inputs) into MemoryItems andstoring
+    them via the MemoryEditor.
+    """
+
+    @abstractmethod
+    async def write(self, observation: str, context: str | None = None) -> list[MemoryItem]:
+        """
+        Process the given observation and store the resulting MemoryItems.
+
+        Args:
+            observation (str): The new textual input to record.
+            context (Optional[str]): Additional
+            context that might influence how the observation is stored.
+
+        Returns:
+            list[MemoryItem]: The newly created MemoryItems.
+        """
+        raise NotImplementedError
+
+
+class MemoryManager(ABC):
+    """
+    Manages the lifecycle of the stored
+    memory by applying policies such as summarization,
+    reflection, forgetting, and mergingn
+    to ensure long-term coherence and relevance.
+    """
+
+    @abstractmethod
+    async def summarize(self) -> None:
+        """
+        Summarize long or numerous MemoryItems into a more compact form.
+        This may remove the original items and store a new summary item.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def reflect(self) -> None:
+        """
+        Generate higher-level insights or
+        abstractions from existing MemoryItems.
+        This may call out to an LLM or other
+        logic to produce conceptual memory.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def forget(self, criteria: Callable[[MemoryItem], bool]) -> None:
+        """
+        Remove MemoryItems that are no
+        longer relevant or have low importance.
+
+        Args:
+            criteria (Callable[[MemoryItem], bool]): A function that
+            returns True for items to forget.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def merge(self, criteria: Callable[[MemoryItem, MemoryItem], bool]) -> None:
+        """
+        Merge similar or redundant MemoryItems
+        into a smaller set of more concise items.
+
+        Args:
+            criteria (Callable[[MemoryItem, MemoryItem], bool]): A function
+            that determines which items can be merged.
+        """
+        raise NotImplementedError

nat/memory/models.py

@@ -0,0 +1,112 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import typing
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+
+class MemoryItem(BaseModel):
+    """
+    Represents a single memory item consisting of structured content and associated metadata.
+
+    Attributes
+    ----------
+    conversation : list[dict[str, str]]
+        A list of dictionaries, each containing string key-value pairs.
+    user_id : str
+        Unique identifier for this MemoryItem's user.
+    tags : list[str]
+        A list of strings representing tags attached to the item.
+    metadata : dict[str, typing.Any]
+        Metadata providing context and utility for management operations.
+    memory : str or None
+        Optional memory string. Helpful when returning a memory.
+    """
+    # yapf: disable
+    model_config = ConfigDict(
+        json_schema_extra={
+            "examples": [
+                {
+                    "conversation": [
+                        {
+                            "role": "user",
+                            "content": "Hi, I'm Alex. I'm a vegetarian and I'm allergic to nuts."
+                        },
+                        {
+                            "role": "assistant",
+                            "content": "Hello Alex! I've noted that you're a vegetarian and have a nut allergy."
+                        }
+                    ],
+                    "user_id": "user_abc",
+                    "tags": ["diet", "allergy"],
+                    "metadata": {
+                        "key_value_pairs": {
+                            "type": "profile",
+                            "relevance": "high"
+                        }
+                    }
+                },
+                {
+                    "memory": "User prefers expensive hotels and is vegan.",
+                    "user_id": "user_abc",
+                    "tags": ["hotel", "restaurant"]
+                }
+            ]
+        },
+        # Allow population of models from arbitrary types (e.g., ORM objects)
+        arbitrary_types_allowed=True,
+        # Enable aliasing if needed
+        populate_by_name=True
+    )
+    # yapf: enable
+    conversation: list[dict[str, str]] | None = Field(
+        description="List of conversation messages. Each message must have a \"role\" "
+        "key (user or assistant. It must also have a \"content\" key.",
+        default=None)
+    tags: list[str] = Field(default_factory=list, description="List of tags applied to the item.")
+    metadata: dict[str, typing.Any] = Field(description="Metadata about the memory item.", default={})
+    user_id: str = Field(description="The user's ID.")
+    memory: str | None = Field(default=None)
+
+
+class SearchMemoryInput(BaseModel):
+    """
+    Represents a search memory input structure.
+    """
+    model_config = ConfigDict(json_schema_extra={
+        "example": {
+            "query": "What is the user's preferred programming language?",
+            "top_k": 1,
+            "user_id": "user_abc",
+        }
+    })
+
+    query: str = Field(description="Search query for which to retrieve memory.")  # noqa: E501
+    top_k: int = Field(description="Maximum number of memories to return")
+    user_id: str = Field(description="ID of the user to search for.")
+
+
+class DeleteMemoryInput(BaseModel):
+    """
+    Represents a delete memory input structure.
+    """
+    model_config = ConfigDict(json_schema_extra={"example": {"user_id": "user_abc", }})
+
+    user_id: str = Field(description="ID of the user to delete memory for. Careful when using "
+                         "this tool; make sure you use the "
+                         "username present in the conversation.")

nat/meta/pypi.md

@@ -0,0 +1,58 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+![NVIDIA NeMo Agent Toolkit](https://media.githubusercontent.com/media/NVIDIA/NeMo-Agent-Toolkit/refs/heads/main/docs/source/_static/banner.png "NeMo Agent toolkit banner image")
+
+# NVIDIA NeMo Agent Toolkit
+
+NeMo Agent toolkit is a flexible library designed to seamlessly integrate your enterprise agents—regardless of framework—with various data sources and tools. By treating agents, tools, and agentic workflows as simple function calls, NeMo Agent toolkit enables true composability: build once and reuse anywhere.
+
+## Key Features
+
+- [**Framework Agnostic:**](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/extend/plugins.html) Works with any agentic framework, so you can use your current technology stack without replatforming.
+- [**Reusability:**](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/extend/sharing-components.html) Every agent, tool, or workflow can be combined and repurposed, allowing developers to leverage existing work in new scenarios.
+- [**Rapid Development:**](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/tutorials/index.html) Start with a pre-built agent, tool, or workflow, and customize it to your needs.
+- [**Profiling:**](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/workflows/profiler.html) Profile entire workflows down to the tool and agent level, track input/output tokens and timings, and identify bottlenecks.
+- [**Observability:**](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/workflows/observe/observe-workflow-with-phoenix.html) Monitor and debug your workflows with any OpenTelemetry-compatible observability tool, with examples using [Phoenix](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/workflows/observe/observe-workflow-with-phoenix.html) and [W&B Weave](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/workflows/observe/observe-workflow-with-weave.html).
+- [**Evaluation System:**](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/workflows/evaluate.html) Validate and maintain accuracy of agentic workflows with built-in evaluation tools.
+- [**User Interface:**](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/quick-start/launching-ui.html) Use the NeMo Agent toolkit UI chat interface to interact with your agents, visualize output, and debug workflows.
+- [**MCP Compatibility**](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/workflows/mcp/mcp-client.html) Compatible with Model Context Protocol (MCP), allowing tools served by MCP Servers to be used as NeMo Agent toolkit functions.
+
+With NeMo Agent toolkit, you can move quickly, experiment freely, and ensure reliability across all your agent-driven projects.
+
+## Links
+ * [Documentation](https://docs.nvidia.com/nemo/agent-toolkit/1.2.0/index.html): Explore the full documentation for NeMo Agent toolkit.
+
+## First time user?
+ If this is your first time using NeMo Agent toolkit, it is recommended to install the latest version from the [source repository](https://github.com/NVIDIA/NeMo-Agent-Toolkit?tab=readme-ov-file#quick-start) on GitHub. This package is intended for users who are familiar with NeMo Agent toolkit applications and need to add NeMo Agent toolkit as a dependency to their project.
+
+## Feedback
+
+We would love to hear from you! Please file an issue on [GitHub](https://github.com/NVIDIA/NeMo-Agent-Toolkit/issues) if you have any feedback or feature requests.
+
+## Acknowledgements
+
+We would like to thank the following open source projects that made NeMo Agent toolkit possible:
+
+- [CrewAI](https://github.com/crewAIInc/crewAI)
+- [FastAPI](https://github.com/tiangolo/fastapi)
+- [LangChain](https://github.com/langchain-ai/langchain)
+- [Llama-Index](https://github.com/run-llama/llama_index)
+- [Mem0ai](https://github.com/mem0ai/mem0)
+- [Ragas](https://github.com/explodinggradients/ragas)
+- [Semantic Kernel](https://github.com/microsoft/semantic-kernel)
+- [uv](https://github.com/astral-sh/uv)

nat/object_store/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+NAT Object Store Module
+
+This package provides foundational classes and interfaces
+for managing object storage in NAT's LLM-based agents.
+"""

nat/object_store/in_memory_object_store.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+
+from nat.builder.builder import Builder
+from nat.cli.register_workflow import register_object_store
+from nat.data_models.object_store import KeyAlreadyExistsError
+from nat.data_models.object_store import NoSuchKeyError
+from nat.data_models.object_store import ObjectStoreBaseConfig
+from nat.utils.type_utils import override
+
+from .interfaces import ObjectStore
+from .models import ObjectStoreItem
+
+
+class InMemoryObjectStoreConfig(ObjectStoreBaseConfig, name="in_memory"):
+    """
+    Object store that stores objects in memory. Objects are not persisted when the process shuts down.
+    """
+    pass
+
+
+class InMemoryObjectStore(ObjectStore):
+    """
+    Implementation of ObjectStore that stores objects in memory. Objects are not persisted when the process shuts down.
+    """
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+        self._store: dict[str, ObjectStoreItem] = {}
+
+    @override
+    async def put_object(self, key: str, item: ObjectStoreItem) -> None:
+        async with self._lock:
+            if key in self._store:
+                raise KeyAlreadyExistsError(key)
+            self._store[key] = item
+
+    @override
+    async def upsert_object(self, key: str, item: ObjectStoreItem) -> None:
+        async with self._lock:
+            self._store[key] = item
+
+    @override
+    async def get_object(self, key: str) -> ObjectStoreItem:
+        async with self._lock:
+            value = self._store.get(key)
+            if value is None:
+                raise NoSuchKeyError(key)
+            return value
+
+    @override
+    async def delete_object(self, key: str) -> None:
+        try:
+            async with self._lock:
+                self._store.pop(key)
+        except KeyError:
+            raise NoSuchKeyError(key)
+
+
+@register_object_store(config_type=InMemoryObjectStoreConfig)
+async def in_memory_object_store(config: InMemoryObjectStoreConfig, builder: Builder):
+    yield InMemoryObjectStore()

nat/object_store/interfaces.py

@@ -0,0 +1,84 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from abc import ABC
+from abc import abstractmethod
+
+from .models import ObjectStoreItem
+
+
+class ObjectStore(ABC):
+    """
+    Abstract interface for an object store.
+
+    Implementations may integrate with various object stores,
+    such as S3, MySQL, etc.
+    """
+
+    @abstractmethod
+    async def put_object(self, key: str, item: ObjectStoreItem) -> None:
+        """
+        Save an ObjectStoreItem in the object store with the given key.
+        If the key already exists, raise an error.
+
+        Args:
+            key (str): The key to save the item under.
+            item (ObjectStoreItem): The item to save.
+
+        Raises:
+            KeyAlreadyExistsError: If the key already exists.
+        """
+        pass
+
+    @abstractmethod
+    async def upsert_object(self, key: str, item: ObjectStoreItem) -> None:
+        """
+        Save an ObjectStoreItem in the object store with the given key.
+        If the key already exists, update the item.
+
+        Args:
+            key (str): The key to save the item under.
+            item (ObjectStoreItem): The item to save.
+        """
+        pass
+
+    @abstractmethod
+    async def get_object(self, key: str) -> ObjectStoreItem:
+        """
+        Get an ObjectStoreItem from the object store by key.
+
+        Args:
+            key (str): The key to get the item from.
+
+        Returns:
+            ObjectStoreItem: The item retrieved from the object store.
+
+        Raises:
+            NoSuchKeyError: If the item does not exist.
+        """
+        pass
+
+    @abstractmethod
+    async def delete_object(self, key: str) -> None:
+        """
+        Delete an ObjectStoreItem from the object store by key.
+
+        Args:
+            key (str): The key to delete the item from.
+
+        Raises:
+            NoSuchKeyError: If the item does not exist.
+        """
+        pass