nvidia-nat 1.1.0a20251020__py3-none-any.whl

nat/utils/reactive/subscription.py

@@ -0,0 +1,49 @@
+# 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.
+
+import typing
+from collections.abc import Callable
+from typing import Generic
+from typing import TypeVar
+
+if typing.TYPE_CHECKING:
+    from nat.utils.reactive.base.subject_base import SubjectBase
+
+_T = TypeVar("_T")
+
+OnNext = Callable[[_T], None]
+OnError = Callable[[Exception], None]
+OnComplete = Callable[[], None]
+
+
+class Subscription(Generic[_T]):
+    """
+    Represents a subscription to a Subject.
+    Unsubscribing removes the associated observer from the Subject's subscriber list.
+    """
+
+    def __init__(self, subject: "SubjectBase", observer: object | None):  # noqa: F821
+        self._subject = subject
+        self._observer = observer
+        self._unsubscribed = False
+
+    def unsubscribe(self) -> None:
+        """
+        Stop receiving further events.
+        """
+        if not self._unsubscribed and self._observer is not None:
+            self._subject._unsubscribe_observer(self._observer)
+            self._observer = None
+            self._unsubscribed = True

nat/utils/settings/global_settings.py

@@ -0,0 +1,195 @@
+# 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.
+
+import logging
+
+from pydantic import create_model
+
+from nat.cli.type_registry import GlobalTypeRegistry
+from nat.data_models.registry_handler import RegistryHandlerBaseConfig
+from nat.settings.global_settings import GlobalSettings
+
+logger = logging.getLogger(__name__)
+
+
+def configure_registry_channel(config_type: RegistryHandlerBaseConfig, channel_name: str) -> None:
+    """Perform channel updates, gathering input from user and validatinig against the global settings data model.
+
+    Args:
+        config_type (RegistryHandlerBaseConfig): The registry handler configuration object to ensure valid channel
+        settings
+        channel_name (str): The name to use to reference the remote registry channel.
+    """
+
+    settings = GlobalSettings.get()
+
+    channel_registry_pre = {}
+
+    for field, info in config_type.model_fields.items():
+
+        if (field == "type"):
+            continue
+
+        while (True):
+            human_prompt = " ".join(field.title().split("_"))
+            user_input = input(f"{human_prompt}: ")
+            model_fields = {}
+            model_fields[field] = (info.annotation, ...)
+            DynamicFieldModel = create_model("DynamicFieldModel", **model_fields)
+            dynamic_inputs = {field: user_input}
+
+            try:
+                validated_field_model = DynamicFieldModel(**dynamic_inputs)
+                channel_registry_pre[field] = getattr(validated_field_model, field)
+                break
+            except Exception as e:
+                logger.exception(e)
+                logger.warning("Invalid '%s' input, input must be of type %s.", field, info.annotation)
+
+    validated_model = config_type(**channel_registry_pre)
+    settings_dict = settings.model_dump(serialize_as_any=True, by_alias=True)
+    settings_dict["channels"] = {**settings_dict["channels"], **{channel_name: validated_model}}
+
+    settings.update_settings(config_obj=settings_dict)
+
+
+def add_channel_interative(channel_type: str) -> None:
+    """Add a remote registry channel to publish/search/pull NAT plugin packages.
+
+    Args:
+        channel_type (str): They type of channel to configure.
+    """
+
+    settings = GlobalSettings.get()
+    registry = GlobalTypeRegistry.get()
+
+    try:
+        ChannelConfigType = registry.get_registered_channel_info_by_channel_type(channel_type=channel_type).config_type
+    except Exception as e:
+        logger.exception("Invalid channel type: %s", e)
+        return
+
+    while (True):
+        channel_name = input("Channel Name: ").strip()
+        if len(channel_name) < 1:
+            logger.warning("Invalid channel name, cannot be empty or whitespace.")
+        if (channel_name in settings.channels):
+            logger.warning("Channel name '%s' already exists, choose a different name.", channel_name)
+        else:
+            settings.channels[channel_name] = {}
+            break
+
+    ChannelConfigType = registry.get_registered_channel_info_by_channel_type(channel_type=channel_type).config_type
+
+    configure_registry_channel(config_type=ChannelConfigType, channel_name=channel_name)
+
+
+def get_existing_channel_interactive(channel_name: str) -> tuple[str, bool]:
+    """Retrieve an existing channel by configured name.
+
+    Args:
+        channel_name (str): The name to use to reference the remote registry channel.
+
+    Returns:
+        tuple[str, bool]: A tuple containing the retrieved channel name and a boolean representing a
+            valid match was or was not successful.
+    """
+
+    settings = GlobalSettings.get()
+    valid_channel = False
+    remote_channels = settings.channels
+
+    if (len(remote_channels) == 0):
+        logger.warning("No are configured channels to remove.")
+        return channel_name, valid_channel
+
+    while (not valid_channel):
+
+        if (channel_name not in remote_channels):
+            logger.warning("Channel name '%s' does not exist, choose a name from %s",
+                           channel_name,
+                           settings.channel_names)
+            channel_name = input("Channel Name: ").strip()
+            continue
+
+        valid_channel = True
+
+    return channel_name, valid_channel
+
+
+def remove_channel(channel_name: str) -> None:
+    """Remove a configured registry channel from the global settings.
+
+    Args:
+        channel_name (str): The name to use to reference the remote registry channel.
+    """
+
+    settings = GlobalSettings.get()
+    settings_dict = settings.model_dump(serialize_as_any=True, by_alias=True).copy()
+    settings_dict["channels"].pop(channel_name)
+    settings.update_settings(config_obj=settings_dict)
+
+
+def remove_channel_interactive(channel_name: str) -> None:
+    channel_name, valid_channel = get_existing_channel_interactive(channel_name=channel_name)
+    if (not valid_channel):
+        return
+    remove_channel(channel_name=channel_name)
+
+
+def match_valid_channel(channel_name: str) -> None:
+    """Performs a match by registry channel to perform a channel configuration update.
+
+    Args:
+        channel_name (str): The name to use to reference the remote registry channel.
+    """
+
+    settings = GlobalSettings.get()
+    registry = GlobalTypeRegistry.get()
+
+    if len(settings.channel_names) == 0:
+        logger.warning("No channels have been configured, first add a channel.")
+        return
+
+    if (channel_name not in settings.channel_names):
+        logger.warning("Provided channel has not yet been configured, choose a different name "
+                       "from %s .",
+                       settings.channel_names)
+        while (True):
+            channel_name = input("Channel Name: ").strip()
+            if len(channel_name) < 1:
+                logger.warning("Invalid channel name, cannot be empty or whitespace.")
+            if (channel_name in settings.channel_names):
+                logger.warning("Channel name '%s' already exists, choose a different name.", channel_name)
+            else:
+                settings.channels[channel_name] = {}
+                break
+
+    channals_settings = settings.channels
+    channel_settings = channals_settings.get(channel_name)
+    ChannelConfigType = registry.get_registered_channel_info_by_channel_type(
+        channel_type=channel_settings.static_type()).config_type
+
+    configure_registry_channel(config_type=ChannelConfigType, channel_name=channel_name)
+
+
+def update_channel_interactive(channel_name: str):
+    """Launch an interactive session to  update a configured channels settings.
+
+    Args:
+        channel_name (str): The name to use to reference the remote registry channel.
+    """
+
+    match_valid_channel(channel_name=channel_name)

nat/utils/string_utils.py

@@ -0,0 +1,38 @@
+# 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.
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def convert_to_str(value: Any) -> str:
+    """
+    Convert a value to a string representation.
+    Handles various types including lists, dictionaries, and other objects.
+    """
+    if isinstance(value, str):
+        return value
+
+    if isinstance(value, list):
+        return ", ".join(map(str, value))
+    elif isinstance(value, BaseModel):
+        return value.model_dump_json(exclude_none=True, exclude_unset=True)
+    elif isinstance(value, dict):
+        return ", ".join(f"{k}: {v}" for k, v in value.items())
+    elif hasattr(value, '__str__'):
+        return str(value)
+    else:
+        raise ValueError(f"Unsupported type for conversion to string: {type(value)}")

nat/utils/type_converter.py

@@ -0,0 +1,299 @@
+# 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 logging
+import typing
+from collections import OrderedDict
+from collections.abc import Callable
+from io import TextIOWrapper
+
+from nat.utils.type_utils import DecomposedType
+
+logger = logging.getLogger(__name__)
+
+_T = typing.TypeVar("_T")
+
+
+class ConvertException(Exception):
+    pass
+
+
+class TypeConverter:
+    _global_initialized = False
+
+    def __init__(self, converters: list[Callable[[typing.Any], typing.Any]], parent: "TypeConverter | None" = None):
+        """
+        Parameters
+        ----------
+        converters : list[Callable[[typing.Any], typing.Any]]
+            A list of single-argument converter callables annotated with their input param and return type.
+        parent : TypeConverter | None
+            An optional parent TypeConverter for fallback.
+        """
+        # dict[to_type, dict[from_type, converter]]
+        self._converters: OrderedDict[type, OrderedDict[type, Callable]] = OrderedDict()
+        self._indirect_warnings_shown: set[tuple[type, type]] = set()
+
+        for converter in converters:
+            self.add_converter(converter)
+
+        if parent is None and TypeConverter._global_initialized:
+            parent = GlobalTypeConverter.get()
+        self._parent = parent
+
+    def add_converter(self, converter: Callable) -> None:
+        """
+        Registers a converter. Must have exactly one parameter
+        and an annotated return type.
+
+        Parameters
+        ----------
+        converter : Callable
+            A converter function. Must have exactly one parameter and an annotated return type.
+
+        Raises
+        ------
+        ValueError
+            If the converter does not have a return type or exactly one argument or the argument has no data type.
+        """
+        sig = typing.get_type_hints(converter)
+        to_type = sig.pop("return", None)
+        if to_type is None:
+            raise ValueError("Converter must have a return type.")
+
+        if len(sig) != 1:
+            raise ValueError("Converter must have exactly one argument.")
+
+        from_type = next(iter(sig.values()))
+        if from_type is None:
+            raise ValueError("Converter's argument must have a data type.")
+
+        self._converters.setdefault(to_type, OrderedDict())[from_type] = converter
+        # to do(MDD): If needed, sort by specificity here.
+
+    def _convert(self, data: typing.Any, to_type: type[_T]) -> _T | None:
+        """
+        Attempts to convert `data` into `to_type`. Returns None if no path is found.
+        """
+        decomposed = DecomposedType(to_type)
+
+        # 1) If data is already correct type, return it
+        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
+        direct_result = self._try_direct_conversion(data, root)
+        if direct_result is not None:
+            return direct_result
+
+        # 3) If direct fails entirely, do indirect in *this* converter
+        indirect_result = self._try_indirect_convert(data, to_type)
+        if indirect_result is not None:
+            return indirect_result
+
+        # 4) If we still haven't succeeded, return None
+        return None
+
+    def convert(self, data: typing.Any, to_type: type[_T]) -> _T:
+        """
+        Converts or raises ValueError if no conversion path is found.
+        We also give the parent a chance if self fails.
+
+        Parameters
+        ----------
+        data : typing.Any
+            The value to convert.
+        to_type : type
+            The type to convert the value to.
+
+        Returns
+        -------
+        _T
+            The converted value.
+
+        Raises
+        ------
+        ValueError
+            If the value cannot be converted to the specified type.
+        """
+        result = self._convert(data, to_type)
+        if result is None and self._parent:
+            # fallback on parent entirely
+            return self._parent.convert(data, to_type)
+
+        if result is not None:
+            return result
+        raise ValueError(f"Cannot convert type {type(data)} to {to_type}. No match found.")
+
+    def try_convert(self, data: typing.Any, to_type: type[_T]) -> _T | typing.Any:
+        """
+        Converts with graceful error handling. If conversion fails, returns the original data
+        and continues processing.
+
+        Parameters
+        ----------
+        data : typing.Any
+            The value to convert.
+        to_type : type
+            The type to convert the value to.
+
+        Returns
+        -------
+        _T | typing.Any
+            The converted value, or original value if conversion fails.
+        """
+        try:
+            return self.convert(data, to_type)
+        except ValueError:
+            logger.warning("Type conversion failed, using original value. From %s to %s", type(data), to_type)
+            # Return original data, let downstream code handle it
+            return data
+
+    # -------------------------------------------------
+    # INTERNAL DIRECT CONVERSION (with parent fallback)
+    # -------------------------------------------------
+    def _try_direct_conversion(self, data: typing.Any, target_root_type: type) -> typing.Any | None:
+        """
+        Tries direct conversion in *this* converter's registry.
+        If no match here, we forward to parent's direct conversion
+        for recursion up the chain.
+        """
+        for convert_to_type, to_type_converters in self._converters.items():
+            # e.g. if Derived is a subclass of Base, this is valid
+            if issubclass(DecomposedType(convert_to_type).root, target_root_type):
+                for convert_from_type, from_type_converter in to_type_converters.items():
+                    if isinstance(data, DecomposedType(convert_from_type).root):
+                        try:
+                            return from_type_converter(data)
+                        except ConvertException:
+                            pass
+
+        # If we can't convert directly here, try parent
+        if self._parent is not None:
+            return self._parent._try_direct_conversion(data, target_root_type)
+
+        return None
+
+    # -------------------------------------------------
+    # INTERNAL INDIRECT CONVERSION (with parent fallback)
+    # -------------------------------------------------
+    def _try_indirect_convert(self, data: typing.Any, to_type: type[_T]) -> _T | None:
+        """
+        Attempt indirect conversion (DFS) in *this* converter.
+        If no success, fallback to parent's indirect attempt.
+        """
+        visited = set()
+        final = self._try_indirect_conversion(data, to_type, visited)
+        src_type = type(data)
+        if final is not None:
+            # Warn once if found a chain
+            self._maybe_warn_indirect(src_type, to_type)
+            return final
+
+        # If no success, try parent's indirect
+        if self._parent is not None:
+            parent_final = self._parent._try_indirect_convert(data, to_type)
+            if parent_final is not None:
+                self._maybe_warn_indirect(src_type, to_type)
+                return parent_final
+
+        return None
+
+    def _try_indirect_conversion(self, data: typing.Any, to_type: type[_T], visited: set[type]) -> _T | None:
+        """
+        DFS attempt to find a chain of conversions from type(data) to to_type,
+        ignoring parent. If not found, returns None.
+        """
+        # 1) If data is already correct type
+        if isinstance(data, to_type):
+            return data
+
+        current_type = type(data)
+        if current_type in visited:
+            return None
+
+        visited.add(current_type)
+
+        # 2) Attempt each known converter from current_type -> ???, then recurse
+        for _, to_type_converters in self._converters.items():
+            for convert_from_type, from_type_converter in to_type_converters.items():
+                if isinstance(data, convert_from_type):
+                    try:
+                        next_data = from_type_converter(data)
+                        if isinstance(next_data, to_type):
+                            return next_data
+                        # else keep going
+                        deeper = self._try_indirect_conversion(next_data, to_type, visited)
+                        if deeper is not None:
+                            return deeper
+                    except ConvertException:
+                        pass
+
+        return None
+
+    def _maybe_warn_indirect(self, source_type: type, to_type: type):
+        """
+        Warn once if an indirect path was used between these two types.
+        """
+        pair = (source_type, to_type)
+        if pair not in self._indirect_warnings_shown:
+            logger.warning(
+                "Indirect type conversion used to convert %s to %s, which may lead to unintended conversions. "
+                "Consider adding a direct converter from %s to %s to ensure correctness.",
+                source_type,
+                to_type,
+                source_type,
+                to_type)
+            self._indirect_warnings_shown.add(pair)
+
+
+class GlobalTypeConverter:
+    _global_converter: TypeConverter = TypeConverter([])
+
+    @staticmethod
+    def get() -> TypeConverter:
+        return GlobalTypeConverter._global_converter
+
+    @staticmethod
+    def register_converter(converter: Callable) -> None:
+        GlobalTypeConverter._global_converter.add_converter(converter)
+
+    @staticmethod
+    def convert(data, to_type: type[_T]) -> _T:
+        return GlobalTypeConverter._global_converter.convert(data, to_type)
+
+    @staticmethod
+    def try_convert(data: typing.Any, to_type: type[_T]) -> _T | typing.Any:
+        return GlobalTypeConverter._global_converter.try_convert(data, to_type)
+
+
+TypeConverter._global_initialized = True
+
+
+def _text_io_wrapper_to_string(data: TextIOWrapper) -> str:
+    return data.read()
+
+
+GlobalTypeConverter.register_converter(_text_io_wrapper_to_string)