nvidia-nat 1.3.0rc1__py3-none-any.whl → 1.3.0rc3__py3-none-any.whl

nat/utils/decorators.py

@@ -0,0 +1,210 @@
+# 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.
+"""Deprecation utilities.
+
+This module provides helpers to standardize deprecation signaling across the
+codebase:
+
+- ``issue_deprecation_warning``: Builds and emits a single deprecation message
+  per function using the standard logging pipeline.
+- ``deprecated``: A decorator that wraps sync/async functions and generators to
+  log a one-time deprecation message upon first use. It supports optional
+  metadata, a planned removal version, a suggested replacement, and an
+  optional feature name label.
+
+Messages are emitted via ``logging.getLogger(__name__).warning`` (not
+``warnings.warn``) so they appear in normal application logs and respect global
+logging configuration. Each unique function logs at most once per process.
+"""
+
+import functools
+import inspect
+import logging
+from collections.abc import AsyncGenerator
+from collections.abc import Callable
+from collections.abc import Generator
+from typing import Any
+from typing import TypeVar
+from typing import overload
+
+logger = logging.getLogger(__name__)
+
+_warning_issued = set()
+
+# Type variables for overloads
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+def issue_deprecation_warning(function_name: str,
+                              removal_version: str | None = None,
+                              replacement: str | None = None,
+                              reason: str | None = None,
+                              feature_name: str | None = None,
+                              metadata: dict[str, Any] | None = None) -> None:
+    """
+    Log a deprecation warning message for the function.
+
+    A warning is emitted only once per function. When a ``metadata`` dict
+    is supplied, it is appended to the log entry to provide extra context
+    (e.g., version, author, feature flag).
+
+    Args:
+        function_name: The name of the deprecated function
+        removal_version: The version when the function will be removed
+        replacement: What to use instead of this function
+        reason: Why the function is being deprecated
+        feature_name: Optional name of the feature that is deprecated
+        metadata: Optional dictionary of metadata to log with the warning
+    """
+    if function_name not in _warning_issued:
+        # Build the deprecation message
+        if feature_name:
+            warning_message = f"{feature_name} is deprecated"
+        else:
+            warning_message = f"Function {function_name} is deprecated"
+
+        if removal_version:
+            warning_message += f" and will be removed in version {removal_version}"
+        else:
+            warning_message += " and will be removed in a future release"
+
+        warning_message += "."
+
+        if reason:
+            warning_message += f" Reason: {reason}."
+
+        if replacement:
+            warning_message += f" Use '{replacement}' instead."
+
+        if metadata:
+            warning_message += f" | Metadata: {metadata}"
+
+        # Issue warning and save function name to avoid duplicate warnings
+        logger.warning(warning_message)
+        _warning_issued.add(function_name)
+
+
+# Overloads for different function types
+@overload
+def deprecated(func: F,
+               *,
+               removal_version: str | None = None,
+               replacement: str | None = None,
+               reason: str | None = None,
+               feature_name: str | None = None,
+               metadata: dict[str, Any] | None = None) -> F:
+    """Overload for direct decorator usage (when called without parentheses)."""
+    ...
+
+
+@overload
+def deprecated(*,
+               removal_version: str | None = None,
+               replacement: str | None = None,
+               reason: str | None = None,
+               feature_name: str | None = None,
+               metadata: dict[str, Any] | None = None) -> Callable[[F], F]:
+    """Overload for decorator factory usage (when called with parentheses)."""
+    ...
+
+
+def deprecated(func: Any = None,
+               *,
+               removal_version: str | None = None,
+               replacement: str | None = None,
+               reason: str | None = None,
+               feature_name: str | None = None,
+               metadata: dict[str, Any] | None = None) -> Any:
+    """
+    Decorator that can wrap any type of function (sync, async, generator,
+    async generator) and logs a deprecation warning.
+
+    Args:
+        func: The function to be decorated.
+        removal_version: The version when the function will be removed
+        replacement: What to use instead of this function
+        reason: Why the function is being deprecated
+        feature_name: Optional name of the feature that is deprecated. If provided, the warning will be
+        prefixed with "The <feature_name> feature is deprecated".
+        metadata: Optional dictionary of metadata to log with the warning. This can include information
+        like version, author, etc. If provided, the metadata will be
+        logged alongside the deprecation warning.
+    """
+    function_name: str = f"{func.__module__}.{func.__qualname__}" if func else "<unknown_function>"
+
+    # If called as @deprecated(...) but not immediately passed a function
+    if func is None:
+
+        def decorator_wrapper(actual_func):
+            return deprecated(actual_func,
+                              removal_version=removal_version,
+                              replacement=replacement,
+                              reason=reason,
+                              feature_name=feature_name,
+                              metadata=metadata)
+
+        return decorator_wrapper
+
+    # --- Validate metadata ---
+    if metadata is not None:
+        if not isinstance(metadata, dict):
+            raise TypeError("metadata must be a dict[str, Any].")
+        if any(not isinstance(k, str) for k in metadata.keys()):
+            raise TypeError("All metadata keys must be strings.")
+
+    # --- Now detect the function type and wrap accordingly ---
+    if inspect.isasyncgenfunction(func):
+        # ---------------------
+        # ASYNC GENERATOR
+        # ---------------------
+
+        @functools.wraps(func)
+        async def async_gen_wrapper(*args, **kwargs) -> AsyncGenerator[Any, Any]:
+            issue_deprecation_warning(function_name, removal_version, replacement, reason, feature_name, metadata)
+            async for item in func(*args, **kwargs):
+                yield item  # yield the original item
+
+        return async_gen_wrapper
+
+    if inspect.iscoroutinefunction(func):
+        # ---------------------
+        # ASYNC FUNCTION
+        # ---------------------
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs) -> Any:
+            issue_deprecation_warning(function_name, removal_version, replacement, reason, feature_name, metadata)
+            result = await func(*args, **kwargs)
+            return result
+
+        return async_wrapper
+
+    if inspect.isgeneratorfunction(func):
+        # ---------------------
+        # SYNC GENERATOR
+        # ---------------------
+        @functools.wraps(func)
+        def sync_gen_wrapper(*args, **kwargs) -> Generator[Any, Any, Any]:
+            issue_deprecation_warning(function_name, removal_version, replacement, reason, feature_name, metadata)
+            yield from func(*args, **kwargs)  # yield the original item
+
+        return sync_gen_wrapper
+
+    @functools.wraps(func)
+    def sync_wrapper(*args, **kwargs) -> Any:
+        issue_deprecation_warning(function_name, removal_version, replacement, reason, feature_name, metadata)
+        result = func(*args, **kwargs)
+        return result
+
+    return sync_wrapper

nat/utils/type_converter.py

@@ -93,6 +93,14 @@ class TypeConverter:
         if to_type is None or decomposed.is_instance(data):
             return data
 
+        # 2) If data is a union type, try to convert to each type in the union
+        if decomposed.is_union:
+            for union_type in decomposed.args:
+                result = self._convert(data, union_type)
+                if result is not None:
+                    return result
+            return None
+
         root = decomposed.root
 
         # 2) Attempt direct in *this* converter

nvidia_nat-1.3.0rc3.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: nvidia-nat
+Version: 1.3.0rc3
+Summary: NVIDIA NeMo Agent toolkit
+Author: NVIDIA Corporation
+Maintainer: NVIDIA Corporation
+License: Apache-2.0
+Project-URL: documentation, https://docs.nvidia.com/nemo/agent-toolkit/latest/
+Project-URL: source, https://github.com/NVIDIA/NeMo-Agent-Toolkit
+Keywords: ai,rag,agents
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE-3rd-party.txt
+License-File: LICENSE.md
+Requires-Dist: aioboto3>=11.0.0
+Requires-Dist: authlib~=1.5
+Requires-Dist: click~=8.1
+Requires-Dist: colorama~=0.4.6
+Requires-Dist: datasets~=4.0
+Requires-Dist: expandvars~=1.0
+Requires-Dist: fastapi~=0.115.5
+Requires-Dist: httpx~=0.27
+Requires-Dist: jinja2~=3.1
+Requires-Dist: jsonpath-ng~=1.7
+Requires-Dist: mcp~=1.13
+Requires-Dist: nest-asyncio~=1.6
+Requires-Dist: networkx~=3.4
+Requires-Dist: numpy~=1.26; python_version < "3.12"
+Requires-Dist: numpy~=2.3; python_version >= "3.12"
+Requires-Dist: openinference-semantic-conventions~=0.1.14
+Requires-Dist: openpyxl~=3.1
+Requires-Dist: optuna~=4.4.0
+Requires-Dist: pip>=24.3.1
+Requires-Dist: pkce==1.0.3
+Requires-Dist: pkginfo~=1.12
+Requires-Dist: platformdirs~=4.3
+Requires-Dist: pydantic~=2.11
+Requires-Dist: pymilvus~=2.4
+Requires-Dist: python-dotenv~=1.1.1
+Requires-Dist: PyYAML~=6.0
+Requires-Dist: ragas~=0.2.14
+Requires-Dist: rich~=13.9
+Requires-Dist: tabulate~=0.9
+Requires-Dist: uvicorn[standard]<0.36
+Requires-Dist: wikipedia~=1.4
+Provides-Extra: all
+Requires-Dist: nvidia-nat-all; extra == "all"
+Provides-Extra: adk
+Requires-Dist: nvidia-nat-adk; extra == "adk"
+Provides-Extra: agno
+Requires-Dist: nvidia-nat-agno; extra == "agno"
+Provides-Extra: crewai
+Requires-Dist: nvidia-nat-crewai; extra == "crewai"
+Provides-Extra: data-flywheel
+Requires-Dist: nvidia-nat-data-flywheel; extra == "data-flywheel"
+Provides-Extra: ingestion
+Requires-Dist: nvidia-nat-ingestion; extra == "ingestion"
+Provides-Extra: langchain
+Requires-Dist: nvidia-nat-langchain; extra == "langchain"
+Provides-Extra: llama-index
+Requires-Dist: nvidia-nat-llama-index; extra == "llama-index"
+Provides-Extra: mcp
+Requires-Dist: nvidia-nat-mcp; extra == "mcp"
+Provides-Extra: mem0ai
+Requires-Dist: nvidia-nat-mem0ai; extra == "mem0ai"
+Provides-Extra: opentelemetry
+Requires-Dist: nvidia-nat-opentelemetry; extra == "opentelemetry"
+Provides-Extra: phoenix
+Requires-Dist: nvidia-nat-phoenix; extra == "phoenix"
+Provides-Extra: profiling
+Requires-Dist: nvidia-nat-profiling; extra == "profiling"
+Provides-Extra: ragaai
+Requires-Dist: nvidia-nat-ragaai; extra == "ragaai"
+Provides-Extra: mysql
+Requires-Dist: nvidia-nat-mysql; extra == "mysql"
+Provides-Extra: redis
+Requires-Dist: nvidia-nat-redis; extra == "redis"
+Provides-Extra: s3
+Requires-Dist: nvidia-nat-s3; extra == "s3"
+Provides-Extra: semantic-kernel
+Requires-Dist: nvidia-nat-semantic-kernel; extra == "semantic-kernel"
+Provides-Extra: telemetry
+Requires-Dist: nvidia-nat-opentelemetry; extra == "telemetry"
+Requires-Dist: nvidia-nat-phoenix; extra == "telemetry"
+Requires-Dist: nvidia-nat-weave; extra == "telemetry"
+Requires-Dist: nvidia-nat-ragaai; extra == "telemetry"
+Provides-Extra: weave
+Requires-Dist: nvidia-nat-weave; extra == "weave"
+Provides-Extra: zep-cloud
+Requires-Dist: nvidia-nat-zep-cloud; extra == "zep-cloud"
+Provides-Extra: examples
+Requires-Dist: nat_adk_demo; extra == "examples"
+Requires-Dist: nat_agno_personal_finance; extra == "examples"
+Requires-Dist: nat_haystack_deep_research_agent; extra == "examples"
+Requires-Dist: nat_alert_triage_agent; extra == "examples"
+Requires-Dist: nat_automated_description_generation; extra == "examples"
+Requires-Dist: nat_email_phishing_analyzer; extra == "examples"
+Requires-Dist: nat_multi_frameworks; extra == "examples"
+Requires-Dist: nat_plot_charts; extra == "examples"
+Requires-Dist: nat_por_to_jiratickets; extra == "examples"
+Requires-Dist: nat_profiler_agent; extra == "examples"
+Requires-Dist: nat_redact_pii; extra == "examples"
+Requires-Dist: nat_router_agent; extra == "examples"
+Requires-Dist: nat_semantic_kernel_demo; extra == "examples"
+Requires-Dist: nat_sequential_executor; extra == "examples"
+Requires-Dist: nat_simple_auth; extra == "examples"
+Requires-Dist: nat_simple_auth_mcp; extra == "examples"
+Requires-Dist: nat_simple_web_query; extra == "examples"
+Requires-Dist: nat_simple_web_query_eval; extra == "examples"
+Requires-Dist: nat_simple_calculator; extra == "examples"
+Requires-Dist: nat_simple_calculator_custom_routes; extra == "examples"
+Requires-Dist: nat_simple_calculator_eval; extra == "examples"
+Requires-Dist: nat_simple_calculator_mcp; extra == "examples"
+Requires-Dist: nat_simple_calculator_observability; extra == "examples"
+Requires-Dist: nat_simple_calculator_hitl; extra == "examples"
+Requires-Dist: nat_simple_rag; extra == "examples"
+Requires-Dist: nat_swe_bench; extra == "examples"
+Requires-Dist: nat_user_report; extra == "examples"
+Provides-Extra: gunicorn
+Requires-Dist: gunicorn~=23.0; extra == "gunicorn"
+Provides-Extra: async-endpoints
+Requires-Dist: aiosqlite~=0.21; extra == "async-endpoints"
+Requires-Dist: dask==2023.6; extra == "async-endpoints"
+Requires-Dist: distributed==2023.6; extra == "async-endpoints"
+Requires-Dist: sqlalchemy[asyncio]~=2.0; extra == "async-endpoints"
+Provides-Extra: nvidia-haystack
+Requires-Dist: nvidia-haystack~=0.3.0; extra == "nvidia-haystack"
+Provides-Extra: litellm
+Requires-Dist: litellm==1.74.9; extra == "litellm"
+Provides-Extra: openai
+Requires-Dist: openai~=1.106; extra == "openai"
+Dynamic: license-file
+
+<!--
+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)