nvidia-nat 1.4.0a20251015__py3-none-any.whl → 1.4.0a20251022__py3-none-any.whl

nat/utils/exception_handlers/automatic_retries.py

@@ -15,11 +15,13 @@
 import asyncio
 import copy
 import functools
+import gc
 import inspect
 import logging
 import re
 import time
 import types
+import weakref
 from collections.abc import Callable
 from collections.abc import Iterable
 from collections.abc import Sequence
@@ -31,9 +33,62 @@ Exc = tuple[type[BaseException], ...]  # exception classes
 CodePattern = int | str | range  # for retry_codes argument
 logger = logging.getLogger(__name__)
 
-# ──────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────────────────────
+#  Memory-optimized helpers
+# ─────────────────────────────────────────────────────────────
+
+
+def _shallow_copy_args(args: tuple, kwargs: dict) -> tuple[tuple, dict]:
+    """Create shallow copies of args and kwargs to avoid deep copy overhead."""
+    # For most use cases, shallow copy is sufficient and much faster
+    return tuple(args), dict(kwargs)
+
+
+def _deep_copy_args(args: tuple, kwargs: dict, skip_first: bool = False) -> tuple[tuple, dict]:
+    """Create deep copies of args and kwargs to prevent mutation issues.
+
+    Args:
+        args: Positional arguments to copy
+        kwargs: Keyword arguments to copy
+        skip_first: If True, skip copying the first arg (typically 'self')
+    """
+    if skip_first and args:
+        # Don't deep copy self, only the remaining arguments
+        return (args[0], ) + copy.deepcopy(args[1:]), copy.deepcopy(kwargs)
+    return copy.deepcopy(args), copy.deepcopy(kwargs)
+
+
+def _clear_exception_context(exc: BaseException) -> None:
+    """Clear exception traceback to free memory."""
+    if exc is None:
+        return
+
+    # Clear the exception's traceback to break reference cycles
+    # This is the main memory optimization
+    try:
+        exc.__traceback__ = None
+    except AttributeError:
+        pass
+
+    # Also try to clear any chained exceptions
+    try:
+        if hasattr(exc, '__cause__') and exc.__cause__ is not None:
+            _clear_exception_context(exc.__cause__)
+        if hasattr(exc, '__context__') and exc.__context__ is not None:
+            _clear_exception_context(exc.__context__)
+    except AttributeError:
+        pass
+
+
+def _run_gc_if_needed(attempt: int, gc_frequency: int = 3) -> None:
+    """Run garbage collection periodically to free memory."""
+    if attempt > 0 and attempt % gc_frequency == 0:
+        gc.collect()
+
+
+# ─────────────────────────────────────────────────────────────
 #  Helpers: status-code extraction & pattern matching
-# ──────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────────────────────
 _CODE_ATTRS = ("code", "status", "status_code", "http_status")
 
 
@@ -55,11 +110,12 @@ def _extract_status_code(exc: BaseException) -> int | None:
 
 def _pattern_to_regex(pat: str) -> re.Pattern[str]:
     """
-    Convert simple wildcard pattern (“4xx”, “5*”, “40x”) to a ^regex$.
-    Rule:  ‘x’ or ‘*’ ⇒ any digit.
+    Convert simple wildcard pattern ("4xx", "5*", "40x") to a ^regex$.
+    Rule:  'x' or '*' ⇒ any digit.
     """
     escaped = re.escape(pat)
-    return re.compile("^" + escaped.replace(r"\*", r"\d").replace("x", r"\d") + "$")
+    regex_pattern = escaped.replace(r"\*", r"\d").replace("x", r"\d")
+    return re.compile("^" + regex_pattern + "$")
 
 
 def _code_matches(code: int, pat: CodePattern) -> bool:
@@ -70,9 +126,9 @@ def _code_matches(code: int, pat: CodePattern) -> bool:
     return bool(_pattern_to_regex(pat).match(str(code)))
 
 
-# ──────────────────────────────────────────────────────────────────────────────
-#  Unified retry-decision helper
-# ──────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────────────────────
+#  Unified retry-decision helper (unchanged)
+# ─────────────────────────────────────────────────────────────
 def _want_retry(
     exc: BaseException,
     *,
@@ -106,9 +162,9 @@ def _want_retry(
     return False
 
 
-# ──────────────────────────────────────────────────────────────────────────────
-#  Core decorator factory (sync / async / (a)gen)
-# ──────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────────────────────
+#  Memory-optimized decorator factory
+# ─────────────────────────────────────────────────────────────
 def _retry_decorator(
     *,
     retries: int = 3,
@@ -117,10 +173,12 @@ def _retry_decorator(
     retry_on: Exc = (Exception, ),
     retry_codes: Sequence[CodePattern] | None = None,
     retry_on_messages: Sequence[str] | None = None,
-    deepcopy: bool = False,
+    shallow_copy: bool = True,  # Changed default to shallow copy
+    gc_frequency: int = 3,  # Run GC every N retries
+    clear_tracebacks: bool = True,  # Clear exception tracebacks
     instance_context_aware: bool = False,
 ) -> Callable[[Callable[..., T]], Callable[..., T]]:
-    """
+    """"
     Build a decorator that retries with exponential back-off *iff*:
 
       • the raised exception is an instance of one of `retry_on`
@@ -128,10 +186,6 @@ def _retry_decorator(
 
     If both `retry_codes` and `retry_on_messages` are None, all exceptions are retried.
 
-    deepcopy:
-        If True, each retry receives deep‑copied *args and **kwargs* to avoid
-        mutating shared state between attempts.
-
     instance_context_aware:
         If True, the decorator will check for a retry context flag on the first
         argument (assumed to be 'self'). If the flag is set, retries are skipped
@@ -139,115 +193,207 @@ def _retry_decorator(
     """
 
     def decorate(fn: Callable[..., T]) -> Callable[..., T]:
-        use_deepcopy = deepcopy
+        use_shallow_copy = shallow_copy
         use_context_aware = instance_context_aware
+        skip_self_in_deepcopy = instance_context_aware
 
         class _RetryContext:
             """Context manager for instance-level retry gating."""
 
-            __slots__ = ("_obj", "_enabled", "_active")
+            __slots__ = ("_obj_ref", "_enabled", "_active")
 
             def __init__(self, args: tuple[Any, ...]):
-                self._obj = args[0] if (use_context_aware and args) else None
-                self._enabled = bool(self._obj)
+                if use_context_aware and args:
+                    try:
+                        # Use weak reference to avoid keeping objects alive
+                        self._obj_ref = weakref.ref(args[0])
+                        self._enabled = True
+                    except TypeError:
+                        # Object doesn't support weak references
+                        self._obj_ref = None
+                        self._enabled = False
+                else:
+                    self._obj_ref = None
+                    self._enabled = False
                 self._active = False
 
             def __enter__(self):
-                if not self._enabled:
+                if not self._enabled or self._obj_ref is None:
+                    return False
+
+                obj = self._obj_ref()
+                if obj is None:
                     return False
+
                 try:
-                    # If already in retry context, signal caller to skip retries
-                    if getattr(self._obj, "_in_retry_context", False):
+                    # If already in retry context, skip retries
+                    if getattr(obj, "_in_retry_context", False):
                         return True
-                    object.__setattr__(self._obj, "_in_retry_context", True)
+                    object.__setattr__(obj, "_in_retry_context", True)
                     self._active = True
                     return False
                 except Exception:
-                    # If we cannot set the attribute, behave as if context isn't enabled
+                    # Cannot set attribute, disable context
                     self._enabled = False
                     return False
 
             def __exit__(self, _exc_type, _exc, _tb):
-                if self._enabled and self._active:
-                    try:
-                        object.__setattr__(self._obj, "_in_retry_context", False)
-                    except Exception:
-                        pass
+                if (self._enabled and self._active and self._obj_ref is not None):
+                    obj = self._obj_ref()
+                    if obj is not None:
+                        try:
+                            object.__setattr__(obj, "_in_retry_context", False)
+                        except Exception:
+                            pass
 
         async def _call_with_retry_async(*args, **kw) -> T:
             with _RetryContext(args) as already_in_context:
                 if already_in_context:
                     return await fn(*args, **kw)
+
                 delay = base_delay
+                last_exception = None
+
                 for attempt in range(retries):
-                    call_args = copy.deepcopy(args) if use_deepcopy else args
-                    call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+                    # Copy args based on configuration
+                    if use_shallow_copy:
+                        call_args, call_kwargs = _shallow_copy_args(args, kw)
+                    else:
+                        call_args, call_kwargs = _deep_copy_args(args, kw, skip_first=skip_self_in_deepcopy)
+
                     try:
                         return await fn(*call_args, **call_kwargs)
                     except retry_on as exc:
-                        if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
-                                or attempt == retries - 1):
+                        last_exception = exc
+
+                        # Clear traceback to free memory
+                        if clear_tracebacks:
+                            _clear_exception_context(exc)
+
+                        # Run GC periodically
+                        _run_gc_if_needed(attempt, gc_frequency)
+
+                        if not _want_retry(exc, code_patterns=retry_codes,
+                                           msg_substrings=retry_on_messages) or attempt == retries - 1:
                             raise
+
                         await asyncio.sleep(delay)
                         delay *= backoff
 
+                if last_exception:
+                    raise last_exception
+
         async def _agen_with_retry(*args, **kw):
             with _RetryContext(args) as already_in_context:
                 if already_in_context:
                     async for item in fn(*args, **kw):
                         yield item
                     return
+
                 delay = base_delay
+                last_exception = None
+
                 for attempt in range(retries):
-                    call_args = copy.deepcopy(args) if use_deepcopy else args
-                    call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+                    if use_shallow_copy:
+                        call_args, call_kwargs = _shallow_copy_args(args, kw)
+                    else:
+                        call_args, call_kwargs = _deep_copy_args(args, kw, skip_first=skip_self_in_deepcopy)
+
                     try:
                         async for item in fn(*call_args, **call_kwargs):
                             yield item
                         return
                     except retry_on as exc:
-                        if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
-                                or attempt == retries - 1):
+                        last_exception = exc
+
+                        # Memory cleanup
+                        if clear_tracebacks:
+                            _clear_exception_context(exc)
+
+                        _run_gc_if_needed(attempt, gc_frequency)
+
+                        if not _want_retry(exc, code_patterns=retry_codes,
+                                           msg_substrings=retry_on_messages) or attempt == retries - 1:
                             raise
+
                         await asyncio.sleep(delay)
                         delay *= backoff
 
+                if last_exception:
+                    raise last_exception
+
         def _gen_with_retry(*args, **kw) -> Iterable[Any]:
             with _RetryContext(args) as already_in_context:
                 if already_in_context:
                     yield from fn(*args, **kw)
                     return
+
                 delay = base_delay
+                last_exception = None
+
                 for attempt in range(retries):
-                    call_args = copy.deepcopy(args) if use_deepcopy else args
-                    call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+                    if use_shallow_copy:
+                        call_args, call_kwargs = _shallow_copy_args(args, kw)
+                    else:
+                        call_args, call_kwargs = _deep_copy_args(args, kw, skip_first=skip_self_in_deepcopy)
+
                     try:
                         yield from fn(*call_args, **call_kwargs)
                         return
                     except retry_on as exc:
-                        if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
-                                or attempt == retries - 1):
+                        last_exception = exc
+
+                        # Memory cleanup
+                        if clear_tracebacks:
+                            _clear_exception_context(exc)
+
+                        _run_gc_if_needed(attempt, gc_frequency)
+
+                        if not _want_retry(exc, code_patterns=retry_codes,
+                                           msg_substrings=retry_on_messages) or attempt == retries - 1:
                             raise
+
                         time.sleep(delay)
                         delay *= backoff
 
+                if last_exception:
+                    raise last_exception
+
         def _sync_with_retry(*args, **kw) -> T:
             with _RetryContext(args) as already_in_context:
                 if already_in_context:
                     return fn(*args, **kw)
+
                 delay = base_delay
+                last_exception = None
+
                 for attempt in range(retries):
-                    call_args = copy.deepcopy(args) if use_deepcopy else args
-                    call_kwargs = copy.deepcopy(kw) if use_deepcopy else kw
+                    if use_shallow_copy:
+                        call_args, call_kwargs = _shallow_copy_args(args, kw)
+                    else:
+                        call_args, call_kwargs = _deep_copy_args(args, kw, skip_first=skip_self_in_deepcopy)
+
                     try:
                         return fn(*call_args, **call_kwargs)
                     except retry_on as exc:
-                        if (not _want_retry(exc, code_patterns=retry_codes, msg_substrings=retry_on_messages)
-                                or attempt == retries - 1):
+                        last_exception = exc
+
+                        # Memory cleanup
+                        if clear_tracebacks:
+                            _clear_exception_context(exc)
+
+                        _run_gc_if_needed(attempt, gc_frequency)
+
+                        if not _want_retry(exc, code_patterns=retry_codes,
+                                           msg_substrings=retry_on_messages) or attempt == retries - 1:
                             raise
+
                         time.sleep(delay)
                         delay *= backoff
 
+                if last_exception:
+                    raise last_exception
+
         # Decide which wrapper to return
         if inspect.iscoroutinefunction(fn):
             wrapper = _call_with_retry_async
@@ -263,9 +409,6 @@ def _retry_decorator(
     return decorate
 
 
-# ──────────────────────────────────────────────────────────────────────────────
-#  Public helper : patch_with_retry
-# ──────────────────────────────────────────────────────────────────────────────
 def patch_with_retry(
     obj: Any,
     *,
@@ -275,7 +418,9 @@ def patch_with_retry(
     retry_on: Exc = (Exception, ),
     retry_codes: Sequence[CodePattern] | None = None,
     retry_on_messages: Sequence[str] | None = None,
-    deepcopy: bool = False,
+    deep_copy: bool = False,
+    gc_frequency: int = 3,
+    clear_tracebacks: bool = True,
 ) -> Any:
     """
     Patch *obj* instance-locally so **every public method** retries on failure.
@@ -291,6 +436,10 @@ def patch_with_retry(
         If True, each retry receives deep‑copied *args and **kwargs* to avoid
         mutating shared state between attempts.
     """
+
+    # Invert deep copy to keep function signature the same
+    shallow_copy = not deep_copy
+
     deco = _retry_decorator(
         retries=retries,
         base_delay=base_delay,
@@ -298,11 +447,13 @@ def patch_with_retry(
         retry_on=retry_on,
         retry_codes=retry_codes,
         retry_on_messages=retry_on_messages,
-        deepcopy=deepcopy,
+        shallow_copy=shallow_copy,
+        gc_frequency=gc_frequency,
+        clear_tracebacks=clear_tracebacks,
         instance_context_aware=True,  # Prevent retry storms
     )
 
-    # Choose attribute source: the *class* to avoid triggering __getattr__
+    # Choose attribute source: the *class* to avoid __getattr__
     cls = obj if inspect.isclass(obj) else type(obj)
     cls_name = getattr(cls, "__name__", str(cls))
 
@@ -310,7 +461,7 @@ def patch_with_retry(
         descriptor = inspect.getattr_static(cls, name)
 
         # Skip dunders, privates and all descriptors we must not wrap
-        if (name.startswith("_") or isinstance(descriptor, property | staticmethod | classmethod)):
+        if name.startswith("_") or isinstance(descriptor, property | staticmethod | classmethod):
             continue
 
         original = descriptor.__func__ if isinstance(descriptor, types.MethodType) else descriptor

nat/utils/responses_api.py

@@ -0,0 +1,26 @@
+# 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.
+# pylint: disable=raising-format-tuple
+
+from nat.builder.framework_enum import LLMFrameworkEnum
+from nat.data_models.llm import APITypeEnum
+
+
+def validate_no_responses_api(llm_config, framework: LLMFrameworkEnum):
+    """Validate that the LLM config does not use the Responses API."""
+
+    if llm_config.api_type == APITypeEnum.RESPONSES:
+        raise ValueError(f"Responses API is not supported for config {str(type(llm_config))} in framework {framework}. "
+                         f"Please use a different API type.")

nat/utils/string_utils.py

@@ -36,3 +36,19 @@ def convert_to_str(value: Any) -> str:
         return str(value)
     else:
         raise ValueError(f"Unsupported type for conversion to string: {type(value)}")
+
+
+def truncate_string(text: str | None, max_length: int = 100) -> str | None:
+    """
+    Truncate a string to a maximum length, adding ellipsis if truncated.
+
+    Args:
+        text: The text to truncate (can be None)
+        max_length: Maximum allowed length (default: 100)
+
+    Returns:
+        The truncated text with ellipsis if needed, or None if input was None
+    """
+    if not text or len(text) <= max_length:
+        return text
+    return text[:max_length - 3] + "..."

{nvidia_nat-1.4.0a20251015.dist-info → nvidia_nat-1.4.0a20251022.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-nat
-Version: 1.4.0a20251015
+Version: 1.4.0a20251022
 Summary: NVIDIA NeMo Agent toolkit
 Author: NVIDIA Corporation
 Maintainer: NVIDIA Corporation
@@ -17,7 +17,7 @@ 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: authlib<2.0.0,>=1.6.5
 Requires-Dist: click~=8.1
 Requires-Dist: colorama~=0.4.6
 Requires-Dist: datasets~=4.0
@@ -84,10 +84,11 @@ 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-data-flywheel; 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"
+Requires-Dist: nvidia-nat-weave; extra == "telemetry"
 Provides-Extra: weave
 Requires-Dist: nvidia-nat-weave; extra == "weave"
 Provides-Extra: zep-cloud
@@ -103,7 +104,6 @@ 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"