nvidia-nat 1.2.0rc5__py3-none-any.whl

aiq/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

aiq/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.")

aiq/meta/module_to_distro.json

@@ -0,0 +1,3 @@
+{
+    "aiq": "nvidia-nat"
+}

aiq/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/aiqtoolkit_banner.png "NeMo Agent toolkit banner image")
+
+# NVIDIA NeMo Agent Toolkit
+
+AIQ 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, AIQ toolkit enables true composability: build once and reuse anywhere.
+
+## Key Features
+
+- [**Framework Agnostic:**](https://docs.nvidia.com/aiqtoolkit/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/aiqtoolkit/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/aiqtoolkit/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/aiqtoolkit/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/aiqtoolkit/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/aiqtoolkit/1.2.0/workflows/observe/observe-workflow-with-phoenix.html) and [W&B Weave](https://docs.nvidia.com/aiqtoolkit/1.2.0/workflows/observe/observe-workflow-with-weave.html).
+- [**Evaluation System:**](https://docs.nvidia.com/aiqtoolkit/1.2.0/workflows/evaluate.html) Validate and maintain accuracy of agentic workflows with built-in evaluation tools.
+- [**User Interface:**](https://docs.nvidia.com/aiqtoolkit/1.2.0/quick-start/launching-ui.html) Use the AIQ toolkit UI chat interface to interact with your agents, visualize output, and debug workflows.
+- [**MCP Compatibility**](https://docs.nvidia.com/aiqtoolkit/1.2.0/workflows/mcp/mcp-client.html) Compatible with Model Context Protocol (MCP), allowing tools served by MCP Servers to be used as AIQ toolkit functions.
+
+With AIQ toolkit, you can move quickly, experiment freely, and ensure reliability across all your agent-driven projects.
+
+## Links
+ * [Documentation](https://docs.nvidia.com/aiqtoolkit/1.2.0/index.html): Explore the full documentation for AIQ toolkit.
+
+## First time user?
+ If this is your first time using AIQ 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 AIQ toolkit applications and need to add AIQ 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 AIQ 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)

aiq/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.
+"""
+AIQ Toolkit Object Store Module
+
+This package provides foundational classes and interfaces
+for managing object storage in AIQ Toolkit's LLM-based agents.
+"""

aiq/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 aiq.builder.builder import Builder
+from aiq.cli.register_workflow import register_object_store
+from aiq.data_models.object_store import KeyAlreadyExistsError
+from aiq.data_models.object_store import NoSuchKeyError
+from aiq.data_models.object_store import ObjectStoreBaseConfig
+from aiq.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()

aiq/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

aiq/object_store/models.py

@@ -0,0 +1,36 @@
+# 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 pydantic import BaseModel
+from pydantic import Field
+
+
+class ObjectStoreItem(BaseModel):
+    """
+    Represents an object store item consisting of bytes and associated metadata.
+
+    Attributes
+    ----------
+    data : bytes
+        The data to store in the object store.
+    content_type : str | None
+        The content type of the data.
+    metadata : dict[str, str] | None
+        Metadata providing context and utility for management operations.
+    """
+
+    data: bytes = Field(description="The data to store in the object store.")
+    content_type: str | None = Field(description="The content type of the data.", default=None)
+    metadata: dict[str, str] | None = Field(description="The metadata of the data.", default=None)

aiq/object_store/register.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.
+
+# pylint: disable=unused-import
+# flake8: noqa
+# isort:skip_file
+
+from . import in_memory_object_store

aiq/observability/__init__.py

@@ -0,0 +1,14 @@
+# 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.

aiq/observability/exporter/__init__.py

@@ -0,0 +1,14 @@
+# 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.