nvidia-nat 1.1.0a20251020__py3-none-any.whl

nat/data_models/gated_field_mixin.py

@@ -0,0 +1,242 @@
+# 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 collections.abc import Sequence
+from dataclasses import dataclass
+from re import Pattern
+
+from pydantic import model_validator
+
+
+@dataclass
+class GatedFieldMixinConfig:
+    """Configuration for a gated field mixin."""
+
+    field_name: str
+    default_if_supported: object | None
+    unsupported: Sequence[Pattern[str]] | None
+    supported: Sequence[Pattern[str]] | None
+    keys: Sequence[str]
+
+
+class GatedFieldMixin:
+    """
+    A mixin that gates a field based on specified keys.
+
+    This should be used to automatically validate a field based on a given key.
+
+    Parameters
+    ----------
+    field_name: `str`
+                The name of the field.
+    default_if_supported: `object | None`
+                          The default value of the field if it is supported for the key.
+    keys: `Sequence[str]`
+          A sequence of keys that are used to validate the field.
+    unsupported: `Sequence[Pattern[str]] | None`
+                 A sequence of regex patterns that match the key names NOT supported for the field.
+                 Defaults to None.
+    supported: `Sequence[Pattern[str]] | None`
+               A sequence of regex patterns that match the key names supported for the field.
+               Defaults to None.
+    """
+
+    def __init_subclass__(
+        cls,
+        field_name: str | None = None,
+        default_if_supported: object | None = None,
+        keys: Sequence[str] | None = None,
+        unsupported: Sequence[Pattern[str]] | None = None,
+        supported: Sequence[Pattern[str]] | None = None,
+    ) -> None:
+        """Store the class variables for the field and define the gated field validator."""
+        super().__init_subclass__()
+
+        # Check if this class directly inherits from GatedFieldMixin
+        has_gated_field_mixin = GatedFieldMixin in cls.__bases__
+
+        if has_gated_field_mixin:
+            if keys is None:
+                raise ValueError("keys must be provided when subclassing GatedFieldMixin")
+            if field_name is None:
+                raise ValueError("field_name must be provided when subclassing GatedFieldMixin")
+
+            cls._setup_direct_mixin(field_name, default_if_supported, unsupported, supported, keys)
+
+        # Always try to collect mixins and create validators for multiple inheritance
+        # This handles both direct inheritance and deep inheritance chains
+        all_mixins = cls._collect_all_mixin_configs()
+        if all_mixins:
+            cls._create_combined_validator(all_mixins)
+
+    @classmethod
+    def _setup_direct_mixin(
+        cls,
+        field_name: str,
+        default_if_supported: object | None,
+        unsupported: Sequence[Pattern[str]] | None,
+        supported: Sequence[Pattern[str]] | None,
+        keys: Sequence[str],
+    ) -> None:
+        """Set up a class that directly inherits from GatedFieldMixin."""
+        cls._validate_mixin_parameters(unsupported, supported, keys)
+
+        # Create and store validator
+        validator = cls._create_gated_field_validator(field_name, default_if_supported, unsupported, supported, keys)
+        validator_name = f"_gated_field_validator_{field_name}"
+        setattr(cls, validator_name, validator)
+
+        # Store mixin info for multiple inheritance
+        if not hasattr(cls, "_gated_field_mixins"):
+            cls._gated_field_mixins = []
+
+        cls._gated_field_mixins.append(
+            GatedFieldMixinConfig(
+                field_name,
+                default_if_supported,
+                unsupported,
+                supported,
+                keys,
+            ))
+
+    @classmethod
+    def _validate_mixin_parameters(
+        cls,
+        unsupported: Sequence[Pattern[str]] | None,
+        supported: Sequence[Pattern[str]] | None,
+        keys: Sequence[str],
+    ) -> None:
+        """Validate that all required parameters are provided."""
+        if unsupported is None and supported is None:
+            raise ValueError("Either unsupported or supported must be provided")
+        if unsupported is not None and supported is not None:
+            raise ValueError("Only one of unsupported or supported must be provided")
+        if len(keys) == 0:
+            raise ValueError("keys must be provided and non-empty when subclassing GatedFieldMixin")
+
+    @classmethod
+    def _create_gated_field_validator(
+        cls,
+        field_name: str,
+        default_if_supported: object | None,
+        unsupported: Sequence[Pattern[str]] | None,
+        supported: Sequence[Pattern[str]] | None,
+        keys: Sequence[str],
+    ):
+        """Create the model validator function."""
+
+        @model_validator(mode="after")
+        def gated_field_validator(self):
+            """Validate the gated field."""
+            current_value = getattr(self, field_name, None)
+            is_supported = cls._check_field_support(self, unsupported, supported, keys)
+            if not is_supported:
+                if current_value is not None:
+                    blocking_key = cls._find_blocking_key(self, unsupported, supported, keys)
+                    value = getattr(self, blocking_key, "<unknown>")
+                    raise ValueError(f"{field_name} is not supported for {blocking_key}: {value}")
+            elif current_value is None:
+                setattr(self, field_name, default_if_supported)
+            return self
+
+        return gated_field_validator
+
+    @classmethod
+    def _check_field_support(
+        cls,
+        instance: object,
+        unsupported: Sequence[Pattern[str]] | None,
+        supported: Sequence[Pattern[str]] | None,
+        keys: Sequence[str],
+    ) -> bool:
+        """Check if a specific field is supported based on its configuration and keys."""
+        seen = False
+        for key in keys:
+            if not hasattr(instance, key):
+                continue
+            seen = True
+            value = str(getattr(instance, key))
+            if supported is not None:
+                if any(p.search(value) for p in supported):
+                    return True
+            elif unsupported is not None:
+                if any(p.search(value) for p in unsupported):
+                    return False
+        return True if not seen else (unsupported is not None)
+
+    @classmethod
+    def _find_blocking_key(
+        cls,
+        instance: object,
+        unsupported: Sequence[Pattern[str]] | None,
+        supported: Sequence[Pattern[str]] | None,
+        keys: Sequence[str],
+    ) -> str:
+        """Find which key is blocking the field."""
+        for key in keys:
+            if not hasattr(instance, key):
+                continue
+            value = str(getattr(instance, key))
+            if supported is not None:
+                if not any(p.search(value) for p in supported):
+                    return key
+            elif unsupported is not None:
+                if any(p.search(value) for p in unsupported):
+                    return key
+
+        return "<unknown>"
+
+    @classmethod
+    def _collect_all_mixin_configs(cls) -> list[GatedFieldMixinConfig]:
+        """Collect all mixin configurations from base classes."""
+        all_mixins = []
+        for base in cls.__bases__:
+            if hasattr(base, "_gated_field_mixins"):
+                all_mixins.extend(base._gated_field_mixins)
+        return all_mixins
+
+    @classmethod
+    def _create_combined_validator(cls, all_mixins: list[GatedFieldMixinConfig]) -> None:
+        """Create a combined validator that handles all fields."""
+
+        @model_validator(mode="after")
+        def combined_gated_field_validator(self):
+            """Validate all gated fields."""
+            for mixin_config in all_mixins:
+                field_name_local = mixin_config.field_name
+                current_value = getattr(self, field_name_local, None)
+                if not self._check_field_support_instance(mixin_config):
+                    if current_value is not None:
+                        blocking_key = self._find_blocking_key_instance(mixin_config)
+                        value = getattr(self, blocking_key, "<unknown>")
+                        raise ValueError(f"{field_name_local} is not supported for {blocking_key}: {value}")
+                elif current_value is None:
+                    setattr(self, field_name_local, mixin_config.default_if_supported)
+
+            return self
+
+        cls._combined_gated_field_validator = combined_gated_field_validator
+
+        # Add helper methods
+        def _check_field_support_instance(self, mixin_config: GatedFieldMixinConfig) -> bool:
+            """Check if a specific field is supported based on its configuration and keys."""
+            return cls._check_field_support(self, mixin_config.unsupported, mixin_config.supported, mixin_config.keys)
+
+        def _find_blocking_key_instance(self, mixin_config: GatedFieldMixinConfig) -> str:
+            """Find which key is blocking the field."""
+            return cls._find_blocking_key(self, mixin_config.unsupported, mixin_config.supported, mixin_config.keys)
+
+        cls._check_field_support_instance = _check_field_support_instance
+        cls._find_blocking_key_instance = _find_blocking_key_instance

nat/data_models/interactive.py

@@ -0,0 +1,246 @@
+# 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 re
+import typing
+from enum import Enum
+
+from pydantic import BaseModel
+from pydantic import Discriminator
+from pydantic import Field
+from pydantic import field_validator
+
+
+class HumanPromptModelType(str, Enum):
+    """
+    Represents the type of an interaction model.
+    """
+    TEXT = "text"
+    NOTIFICATION = "notification"
+    BINARY_CHOICE = "binary_choice"
+    RADIO = "radio"
+    CHECKBOX = "checkbox"
+    DROPDOWN = "dropdown"
+    OAUTH_CONSENT = "oauth_consent"
+
+
+class BinaryChoiceOptionsType(str, Enum):
+    """
+    Represents the types of system interaction binary choice content
+    """
+    CONTINUE = "continue"
+    CANCEL = "cancel"
+
+
+class MultipleChoiceOptionType(str, Enum):
+    """
+    Represents the types of system interaction multiple choice content
+    """
+    EMAIL = "email"
+    SMS = "sms"
+    PUSH = "push"
+
+
+class BinaryHumanPromptOption(BaseModel):
+    """
+    Represents a choice for a binary interaction.
+    """
+    id: str = Field(default="default", description="The ID of the choice.")
+    label: str = Field(default="default", description="Label of the choice")
+    value: typing.Any = Field(default="default", description="The value of the choice.")
+
+
+class MultipleChoiceOption(BaseModel):
+    id: str = Field(default="default", description="The ID of the choice.")
+    label: str = Field(default="default", description="The label for the multiple choice interaction.")
+    value: str = Field(default="default", description="The value for the multiple choice interaction.")
+    description: str = Field(default="default", description="The description for the multiple choice interaction.")
+
+
+class HumanResponseText(BaseModel):
+    """
+    Represents a text response to an interaction.
+    """
+    type: typing.Literal[HumanPromptModelType.TEXT] = HumanPromptModelType.TEXT
+    text: str = Field(description="The text of the response.")
+
+
+class HumanResponseNotification(BaseModel):
+    """
+    Represents a notification response to an interaction.
+    """
+    type: typing.Literal[HumanPromptModelType.NOTIFICATION] = HumanPromptModelType.NOTIFICATION
+    text: str = Field(default="Notification acknowledgement.", description="Default notification response text.")
+
+
+class HumanResponseBinary(BaseModel):
+    """
+    Represents a binary response to an interaction.
+    """
+    type: typing.Literal[HumanPromptModelType.BINARY_CHOICE] = HumanPromptModelType.BINARY_CHOICE
+    selected_option: BinaryHumanPromptOption = Field(description="The selected binary response.")
+
+
+class HumanResponseRadio(BaseModel):
+    """
+    Represents a multiple choice radio response to an interaction.
+    """
+    type: typing.Literal[HumanPromptModelType.RADIO] = HumanPromptModelType.RADIO
+    selected_option: MultipleChoiceOption = Field(description="The selected multiple choice radio response.")
+
+
+class HumanResponseCheckbox(BaseModel):
+    """
+    Represents a multiple choice checkbox response to an interaction.
+    """
+    type: typing.Literal[HumanPromptModelType.CHECKBOX] = HumanPromptModelType.CHECKBOX
+    selected_option: MultipleChoiceOption = Field(description="The selected multiple choice checkbox response.")
+
+
+class HumanResponseDropdown(BaseModel):
+    """
+    Represents a multiple choice dropdown response to an interaction.
+    """
+    type: typing.Literal[HumanPromptModelType.DROPDOWN] = HumanPromptModelType.DROPDOWN
+    selected_option: MultipleChoiceOption = Field(description="The selected multiple choice dropdown response.")
+
+
+HumanResponse = typing.Annotated[HumanResponseText | HumanResponseBinary | HumanResponseNotification
+                                 | HumanResponseRadio | HumanResponseCheckbox
+                                 | HumanResponseDropdown,
+                                 Discriminator("type")]
+
+
+class HumanPromptBase(BaseModel):
+    """
+    Base interaction model to derive from
+    """
+    text: str = Field(description="Text prompt that will be displayed to the user.")
+
+
+class HumanPromptText(HumanPromptBase):
+    """
+    Represents a text interaction.
+    """
+    input_type: typing.Literal[HumanPromptModelType.TEXT] = HumanPromptModelType.TEXT
+    placeholder: str | None = Field(description="The placeholder for the text.")
+    required: bool = Field(default=True, description="Whether the interaction is required.")
+
+
+class HumanPromptNotification(HumanPromptBase):
+    """
+    Represents a notification interaction.
+    """
+    input_type: typing.Literal[HumanPromptModelType.NOTIFICATION] = HumanPromptModelType.NOTIFICATION
+
+
+class _HumanPromptOAuthConsent(HumanPromptBase):
+    """
+    Represents an OAuth consent prompt interaction used to notify the UI to open the authentication page for completing
+    the consent flow.
+    """
+    input_type: typing.Literal[HumanPromptModelType.OAUTH_CONSENT] = HumanPromptModelType.OAUTH_CONSENT
+
+
+class HumanPromptBinary(HumanPromptBase):
+    """
+    Represents a binary interaction.
+    """
+    input_type: typing.Literal[HumanPromptModelType.BINARY_CHOICE] = HumanPromptModelType.BINARY_CHOICE
+    options: list[BinaryHumanPromptOption] = Field(description="The options for the binary interaction.")
+
+    # Field validator to make sure len(options) == 2
+    @field_validator("options", mode="before")
+    @classmethod
+    def validate_options(cls, options):
+        if len(options) != 2:
+            raise ValueError("Binary interactions must have exactly two options.")
+        return options
+
+
+class HumanPromptMultipleChoiceBase(HumanPromptBase):
+    """
+    Represents a multiple choice interaction.
+    """
+    options: list[MultipleChoiceOption] = Field(description="The options for the multiple choice interaction.")
+
+
+class HumanPromptRadio(HumanPromptMultipleChoiceBase):
+    """
+    Represents a radio interaction.
+    """
+    input_type: typing.Literal[HumanPromptModelType.RADIO] = HumanPromptModelType.RADIO
+
+
+class HumanPromptCheckbox(HumanPromptMultipleChoiceBase):
+    """
+    Represents a checkbox interaction.
+    """
+    input_type: typing.Literal[HumanPromptModelType.CHECKBOX] = HumanPromptModelType.CHECKBOX
+
+
+class HumanPromptDropdown(HumanPromptMultipleChoiceBase):
+    """
+    Represents a dropdown interaction.
+    """
+    input_type: typing.Literal[HumanPromptModelType.DROPDOWN] = HumanPromptModelType.DROPDOWN
+
+
+HumanPrompt = typing.Annotated[HumanPromptText | HumanPromptNotification | HumanPromptBinary | HumanPromptRadio
+                               | HumanPromptCheckbox | HumanPromptDropdown | _HumanPromptOAuthConsent,
+                               Discriminator("input_type")]
+
+
+class InteractionStatus(str, Enum):
+    """
+    Represents the status of an interaction.
+    """
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class InteractionBase(BaseModel):
+    """
+    Represents a system-human interaction.
+    """
+    id: str = Field(description="The ID of the interaction.")
+    type: str = Field(default="system_human_interaction", description="The type of the interaction.")
+    thread_id: str | None = Field(description="The thread ID of the interaction.", default=None)
+    parent_id: str | None = Field(description="The parent ID of the interaction.", default=None)
+    status: InteractionStatus = Field(description="The status of the interaction.", default=InteractionStatus.PENDING)
+    timestamp: str = Field(description="The timestamp of the interaction.")
+
+    @field_validator("timestamp", mode="before")
+    @classmethod
+    def validate_timestamp(cls, timestamp):
+        if not re.match(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z", timestamp):
+            raise ValueError("Timestamp must be in the format 2025-01-13T10:00:03Z")
+        return timestamp
+
+
+class InteractionPrompt(InteractionBase):
+    """
+    Represents a system-human interaction with a prompt.
+    """
+    content: HumanPrompt = Field(description="The content of the interaction.")
+
+
+class InteractionResponse(InteractionBase):
+    """
+    Represents a system-human interaction with a response.
+    """
+    content: HumanResponse = Field(description="The content of the interaction.")