nvidia-nat 1.1.0a20251020__py3-none-any.whl

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.3/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.3/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.3/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.3/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.3/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.3/workflows/observe/observe-workflow-with-phoenix.html) and [W&B Weave](https://docs.nvidia.com/nemo/agent-toolkit/1.3/workflows/observe/observe-workflow-with-weave.html).
+- [**Evaluation System:**](https://docs.nvidia.com/nemo/agent-toolkit/1.3/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.3/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.3/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.3/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

nat/object_store/models.py

@@ -0,0 +1,38 @@
+# 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 ConfigDict
+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.
+    """
+    model_config = ConfigDict(ser_json_bytes="base64", val_json_bytes="base64")
+
+    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)

nat/object_store/register.py

@@ -0,0 +1,19 @@
+# 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.
+
+# flake8: noqa
+# isort:skip_file
+
+from . import in_memory_object_store

nat/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.

nat/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.