griptape-nodes 0.60.4__py3-none-any.whl → 0.62.0__py3-none-any.whl

griptape_nodes/common/project_templates/situation.py

@@ -0,0 +1,143 @@
+"""Situation template definitions for file path scenarios."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+from griptape_nodes.common.macro_parser import MacroSyntaxError, ParsedMacro
+
+if TYPE_CHECKING:
+    from griptape_nodes.common.project_templates.loader import YAMLLineInfo
+    from griptape_nodes.common.project_templates.validation import ProjectValidationInfo
+
+
+class SituationFilePolicy(StrEnum):
+    """Policy for handling file collisions in situations.
+
+    Maps to ExistingFilePolicy for file operations, except PROMPT which
+    triggers user interaction before determining final policy.
+    """
+
+    CREATE_NEW = "create_new"  # Increment {_index} in macro
+    OVERWRITE = "overwrite"  # Maps to ExistingFilePolicy.OVERWRITE
+    FAIL = "fail"  # Maps to ExistingFilePolicy.FAIL
+    PROMPT = "prompt"  # Special UI handling
+
+
+class SituationPolicy(BaseModel):
+    """Policy for file operations in a situation."""
+
+    on_collision: SituationFilePolicy = Field(description="Policy for handling file collisions")
+    create_dirs: bool = Field(description="Whether to create directories automatically")
+
+
+class SituationTemplate(BaseModel):
+    """Template defining how files are saved in a specific situation."""
+
+    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.1.0"
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    name: str = Field(description="Name of the situation")
+    macro: str = Field(description="Macro template for file path")
+    policy: SituationPolicy = Field(description="Policy for file operations")
+    fallback: str | None = Field(default=None, description="Name of fallback situation")
+    description: str | None = Field(default=None, description="Description of the situation")
+
+    @field_validator("macro")
+    @classmethod
+    def validate_macro_syntax(cls, v: str) -> str:
+        """Validate macro syntax using macro parser."""
+        try:
+            ParsedMacro(v)
+        except MacroSyntaxError as e:
+            msg = f"Invalid macro syntax: {e}"
+            raise ValueError(msg) from e
+        return v
+
+    @staticmethod
+    def merge(
+        base: SituationTemplate,
+        overlay_data: dict[str, Any],
+        field_path: str,
+        validation_info: ProjectValidationInfo,
+        line_info: YAMLLineInfo,
+    ) -> SituationTemplate:
+        """Merge overlay fields onto base situation.
+
+        Field-level merge behavior:
+        - macro: Use overlay if present, else base
+        - description: Use overlay if present, else base
+        - fallback: Use overlay if present, else base
+        - policy: Use overlay if present (must be complete), else base
+
+        Policy validation:
+        - If policy provided in overlay, must contain both on_collision and create_dirs
+        - Adds error to validation_info if incomplete
+
+        Args:
+            base: Complete base situation to start from
+            overlay_data: Partial situation dict from overlay YAML
+            field_path: Path for validation errors (e.g., "situations.save_file")
+            validation_info: Shared validation info
+            line_info: Line tracking from overlay YAML
+
+        Returns:
+            New merged SituationTemplate
+        """
+        # Start with base fields as dict
+        merged_data = base.model_dump()
+
+        # Apply overlay fields if present
+        if "macro" in overlay_data:
+            merged_data["macro"] = overlay_data["macro"]
+
+        if "description" in overlay_data:
+            merged_data["description"] = overlay_data["description"]
+
+        if "fallback" in overlay_data:
+            merged_data["fallback"] = overlay_data["fallback"]
+
+        # Policy must be complete if provided
+        if "policy" in overlay_data:
+            policy = overlay_data["policy"]
+            if not isinstance(policy, dict):
+                validation_info.add_error(
+                    field_path=f"{field_path}.policy",
+                    message="Policy must be a dict",
+                    line_number=line_info.get_line(f"{field_path}.policy"),
+                )
+            elif "on_collision" not in policy or "create_dirs" not in policy:
+                validation_info.add_error(
+                    field_path=f"{field_path}.policy",
+                    message="Policy must include both on_collision and create_dirs",
+                    line_number=line_info.get_line(f"{field_path}.policy"),
+                )
+            else:
+                merged_data["policy"] = policy
+
+        # Build merged situation using model_validate
+        # Note: name field is not in overlay_data, use base.name
+        merged_data_with_name = {"name": base.name, **merged_data}
+
+        try:
+            return SituationTemplate.model_validate(merged_data_with_name)
+        except ValidationError as e:
+            # Convert Pydantic validation errors to our validation_info format
+            for error in e.errors():
+                error_field_path = ".".join(str(loc) for loc in error["loc"])
+                full_field_path = f"{field_path}.{error_field_path}"
+                message = error["msg"]
+                line_number = line_info.get_line(full_field_path)
+
+                validation_info.add_error(
+                    field_path=full_field_path,
+                    message=message,
+                    line_number=line_number,
+                )
+
+            # Return base on validation error (fault-tolerant)
+            return base

griptape_nodes/common/project_templates/validation.py

@@ -0,0 +1,140 @@
+"""Validation infrastructure for project templates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class ProjectValidationStatus(StrEnum):
+    """Status of project template validation.
+
+    Mirrors WorkflowStatus pattern from workflow_manager.py.
+    """
+
+    GOOD = "GOOD"  # No errors detected
+    FLAWED = "FLAWED"  # Some errors, but recoverable
+    UNUSABLE = "UNUSABLE"  # Errors make template unusable
+    MISSING = "MISSING"  # File not found
+
+
+class ProjectValidationProblemSeverity(StrEnum):
+    """Severity level of a validation problem."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+class ProjectOverrideCategory(StrEnum):
+    """Category of template override during merge."""
+
+    SITUATION = "situation"
+    DIRECTORY = "directory"
+    ENVIRONMENT = "environment"
+    METADATA = "metadata"
+
+
+class ProjectOverrideAction(StrEnum):
+    """Action taken during template merge."""
+
+    MODIFIED = "modified"  # Existed in base, changed in overlay
+    ADDED = "added"  # New in overlay, not in base
+
+
+@dataclass
+class ProjectValidationProblem:
+    """Single validation problem with context."""
+
+    line_number: int | None
+    field_path: str  # e.g., "situations.copy_external_file.macro"
+    message: str
+    severity: ProjectValidationProblemSeverity
+
+
+@dataclass
+class ProjectOverride:
+    """Record of a template override during merge.
+
+    Tracks what was customized in the overlay without affecting validation status.
+    """
+
+    category: ProjectOverrideCategory
+    name: str
+    action: ProjectOverrideAction
+
+
+@dataclass
+class ProjectValidationInfo:
+    """Validation result for a project template.
+
+    Shared across construction chain - problems are accumulated as
+    the template is built from YAML.
+
+    Overrides track what was customized during merge without affecting status.
+    """
+
+    status: ProjectValidationStatus
+    problems: list[ProjectValidationProblem] = field(default_factory=list)
+    overrides: list[ProjectOverride] = field(default_factory=list)
+
+    def add_error(self, field_path: str, message: str, line_number: int | None = None) -> None:
+        """Add an error to the problems list.
+
+        Automatically downgrades status to UNUSABLE unless already MISSING.
+        Early returns if status is MISSING.
+        """
+        if self.status == ProjectValidationStatus.MISSING:
+            return
+
+        self.problems.append(
+            ProjectValidationProblem(
+                line_number=line_number,
+                field_path=field_path,
+                message=message,
+                severity=ProjectValidationProblemSeverity.ERROR,
+            ),
+        )
+        self.status = ProjectValidationStatus.UNUSABLE
+
+    def add_warning(self, field_path: str, message: str, line_number: int | None = None) -> None:
+        """Add a warning to the problems list.
+
+        Automatically downgrades status from GOOD to FLAWED if current status is GOOD.
+        Does not change status if already FLAWED or UNUSABLE.
+        Early returns if status is MISSING.
+        """
+        if self.status == ProjectValidationStatus.MISSING:
+            return
+
+        self.problems.append(
+            ProjectValidationProblem(
+                line_number=line_number,
+                field_path=field_path,
+                message=message,
+                severity=ProjectValidationProblemSeverity.WARNING,
+            ),
+        )
+
+        if self.status == ProjectValidationStatus.GOOD:
+            self.status = ProjectValidationStatus.FLAWED
+
+    def add_override(
+        self,
+        category: ProjectOverrideCategory,
+        name: str,
+        action: ProjectOverrideAction,
+    ) -> None:
+        """Record an override without affecting validation status.
+
+        Used during template merge to track what was customized in the overlay.
+
+        Args:
+            category: Type of override (situation, directory, environment, metadata)
+            name: Name of the item that was overridden
+            action: Whether it was modified (existed in base) or added (new in overlay)
+        """
+        self.overrides.append(ProjectOverride(category=category, name=name, action=action))
+
+    def is_usable(self) -> bool:
+        """Check if template can be used (GOOD or FLAWED status)."""
+        return self.status in (ProjectValidationStatus.GOOD, ProjectValidationStatus.FLAWED)

griptape_nodes/exe_types/core_types.py

@@ -787,7 +787,7 @@ class DeprecationMessage(ParameterMessage):
         kwargs.setdefault("traits", {})
         kwargs["traits"][Button(label=button_text, icon="plus", variant="secondary", on_click=migrate_function)] = None
 
-        super().__init__(value=value, **kwargs)
+        super().__init__(value=value, button_text=button_text, **kwargs)
 
     def to_dict(self) -> dict:
         """Override to_dict to use element_type instead of class name.
@@ -804,9 +804,18 @@ class DeprecationMessage(ParameterMessage):
 class ParameterGroup(BaseNodeElement, UIOptionsMixin):
     """UI element for a group of parameters."""
 
-    def __init__(self, name: str, ui_options: dict | None = None, **kwargs):
+    def __init__(self, name: str, ui_options: dict | None = None, *, collapsed: bool = False, **kwargs):
         super().__init__(name=name, **kwargs)
-        self._ui_options = ui_options or {}
+        if ui_options is None:
+            ui_options = {}
+        else:
+            ui_options = ui_options.copy()
+
+        # Add collapsed to ui_options if it's True
+        if collapsed:
+            ui_options["collapsed"] = collapsed
+
+        self._ui_options = ui_options
 
     @property
     def ui_options(self) -> dict:
@@ -817,6 +826,30 @@ class ParameterGroup(BaseNodeElement, UIOptionsMixin):
     def ui_options(self, value: dict) -> None:
         self._ui_options = value
 
+    @property
+    def collapsed(self) -> bool:
+        """Get whether the parameter group is collapsed.
+
+        Returns:
+            True if the group is collapsed, False otherwise
+        """
+        return self._ui_options.get("collapsed", False)
+
+    @collapsed.setter
+    @BaseNodeElement.emits_update_on_write
+    def collapsed(self, value: bool) -> None:
+        """Set whether the parameter group is collapsed.
+
+        Args:
+            value: Whether to collapse the group
+        """
+        if value:
+            self.update_ui_options_key("collapsed", value)
+        else:
+            ui_options = self._ui_options.copy()
+            ui_options.pop("collapsed", None)
+            self._ui_options = ui_options
+
     def to_dict(self) -> dict[str, Any]:
         """Returns a nested dictionary representation of this node and its children.
 

griptape_nodes/exe_types/node_types.py

@@ -793,13 +793,15 @@ class BaseNode(ABC):
 
     def get_parameter_value(self, param_name: str) -> Any:
         param = self.get_parameter_by_name(param_name)
-        if param and isinstance(param, ParameterContainer):
+        if param is None:
+            return None
+        if isinstance(param, ParameterContainer):
             value = handle_container_parameter(self, param)
             if value is not None:
                 return value
         if param_name in self.parameter_values:
             return self.parameter_values[param_name]
-        return param.default_value if param else None
+        return param.default_value
 
     def get_parameter_list_value(self, param: str) -> list:
         """Flattens the given param from self.params into a single list.

griptape_nodes/exe_types/param_components/progress_bar_component.py

@@ -0,0 +1,57 @@
+import logging
+
+from griptape_nodes.exe_types.core_types import Parameter, ParameterMode
+from griptape_nodes.exe_types.node_types import BaseNode
+
+logger = logging.getLogger(__name__)
+
+
+class ProgressBarComponent:
+    def __init__(self, node: BaseNode):
+        self._node = node
+        self._total_steps = 0
+        self._current_step = 0
+
+    def add_property_parameters(self) -> None:
+        self._node.add_parameter(
+            Parameter(
+                name="progress",
+                output_type="float",
+                allowed_modes={ParameterMode.PROPERTY},
+                tooltip="Progress bar showing completion (0.0 to 1.0)",
+                ui_options={"progress_bar": True},
+                settable=False,
+            )
+        )
+
+    def initialize(self, total_steps: int) -> None:
+        """Initialize the progress bar with a total number of steps."""
+        self._total_steps = total_steps
+        self._current_step = 0
+        self._update_progress()
+
+    def increment(self, steps: int = 1) -> None:
+        """Increment the progress by the specified number of steps."""
+        self._current_step += steps
+        if self._current_step > self._total_steps:
+            logger.warning(
+                "Current step %i exceeds total steps %i. Progress will not exceed 100%.",
+                self._current_step,
+                self._total_steps,
+            )
+        self._update_progress()
+
+    def reset(self) -> None:
+        """Reset the progress bar to 0."""
+        self._current_step = 0
+        self._total_steps = 0
+        self._update_progress()
+
+    def _update_progress(self) -> None:
+        """Update the progress parameter based on current step and total steps."""
+        if self._total_steps <= 0:
+            progress_value = 0.0
+        else:
+            progress_value = min(1.0, self._current_step / self._total_steps)
+
+        self._node.publish_update_to_parameter("progress", progress_value)

griptape_nodes/exe_types/param_types/parameter_audio.py

@@ -0,0 +1,243 @@
+"""ParameterAudio component for audio inputs with enhanced UI options."""
+
+from collections.abc import Callable
+from typing import Any
+
+from griptape_nodes.exe_types.core_types import Parameter, ParameterMode, Trait
+
+
+class ParameterAudio(Parameter):
+    """A specialized Parameter class for audio inputs with enhanced UI options.
+
+    This class provides a convenient way to create audio parameters with common
+    UI customizations like file browser, microphone capture, and audio editing.
+    It exposes these UI options as direct properties for easy runtime modification.
+
+    Example:
+        param = ParameterAudio(
+            name="input_audio",
+            tooltip="Select an audio file",
+            clickable_file_browser=True,
+            microphone_capture_audio=True,
+            edit_audio=True
+        )
+        param.pulse_on_run = True  # Change UI options at runtime
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        name: str,
+        tooltip: str | None = None,
+        *,
+        type: str = "AudioUrlArtifact",  # noqa: A002, ARG002
+        input_types: list[str] | None = None,  # noqa: ARG002
+        output_type: str = "AudioUrlArtifact",  # noqa: ARG002
+        default_value: Any = None,
+        tooltip_as_input: str | None = None,
+        tooltip_as_property: str | None = None,
+        tooltip_as_output: str | None = None,
+        allowed_modes: set[ParameterMode] | None = None,
+        traits: set[type[Trait] | Trait] | None = None,
+        converters: list[Callable[[Any], Any]] | None = None,
+        validators: list[Callable[[Parameter, Any], None]] | None = None,
+        ui_options: dict | None = None,
+        pulse_on_run: bool = False,
+        clickable_file_browser: bool = True,
+        microphone_capture_audio: bool = False,
+        edit_audio: bool = False,
+        accept_any: bool = True,
+        hide: bool = False,
+        hide_label: bool = False,
+        hide_property: bool = False,
+        allow_input: bool = True,
+        allow_property: bool = True,
+        allow_output: bool = True,
+        settable: bool = True,
+        serializable: bool = True,
+        user_defined: bool = False,
+        element_id: str | None = None,
+        element_type: str | None = None,
+        parent_container_name: str | None = None,
+    ) -> None:
+        """Initialize an audio parameter with enhanced UI options.
+
+        Args:
+            name: Parameter name
+            tooltip: Parameter tooltip
+            type: Parameter type (ignored, always "AudioUrlArtifact" for ParameterAudio)
+            input_types: Allowed input types (ignored, set based on accept_any)
+            output_type: Output type (ignored, always "AudioUrlArtifact" for ParameterAudio)
+            default_value: Default parameter value
+            tooltip_as_input: Tooltip for input mode
+            tooltip_as_property: Tooltip for property mode
+            tooltip_as_output: Tooltip for output mode
+            allowed_modes: Allowed parameter modes
+            traits: Parameter traits
+            converters: Parameter converters
+            validators: Parameter validators
+            ui_options: Dictionary of UI options
+            pulse_on_run: Whether to pulse the parameter on run
+            clickable_file_browser: Whether to show clickable file browser
+            microphone_capture_audio: Whether to enable microphone capture
+            edit_audio: Whether to enable audio editing functionality
+            accept_any: Whether to accept any input type and convert to audio (default: True)
+            hide: Whether to hide the entire parameter
+            hide_label: Whether to hide the parameter label
+            hide_property: Whether to hide the parameter in property mode
+            allow_input: Whether to allow input mode
+            allow_property: Whether to allow property mode
+            allow_output: Whether to allow output mode
+            settable: Whether the parameter is settable
+            serializable: Whether the parameter is serializable
+            user_defined: Whether the parameter is user-defined
+            element_id: Element ID
+            element_type: Element type
+            parent_container_name: Name of parent container
+        """
+        # Build ui_options dictionary from the provided UI-specific parameters
+        if ui_options is None:
+            ui_options = {}
+        else:
+            ui_options = ui_options.copy()
+
+        # Add audio-specific UI options if they have values
+        if pulse_on_run:
+            ui_options["pulse_on_run"] = pulse_on_run
+        if clickable_file_browser:
+            ui_options["clickable_file_browser"] = clickable_file_browser
+        if microphone_capture_audio:
+            ui_options["microphone_capture_audio"] = microphone_capture_audio
+        if edit_audio:
+            ui_options["edit_audio"] = edit_audio
+
+        # Auto-disable clickable_file_browser if neither input nor property modes are allowed
+        if not allow_input and not allow_property and clickable_file_browser:
+            ui_options.pop("clickable_file_browser", None)
+
+        # Set up input types based on accept_any setting
+        if accept_any:
+            final_input_types = ["any"]
+        else:
+            final_input_types = ["AudioUrlArtifact"]
+
+        # Call parent with explicit parameters, following ControlParameter pattern
+        super().__init__(
+            name=name,
+            tooltip=tooltip,
+            type="AudioUrlArtifact",  # Always an AudioUrlArtifact type for ParameterAudio
+            input_types=final_input_types,
+            output_type="AudioUrlArtifact",  # Always output as AudioUrlArtifact
+            default_value=default_value,
+            tooltip_as_input=tooltip_as_input,
+            tooltip_as_property=tooltip_as_property,
+            tooltip_as_output=tooltip_as_output,
+            allowed_modes=allowed_modes,
+            traits=traits,
+            converters=converters,
+            validators=validators,
+            ui_options=ui_options,
+            hide=hide,
+            hide_label=hide_label,
+            hide_property=hide_property,
+            allow_input=allow_input,
+            allow_property=allow_property,
+            allow_output=allow_output,
+            settable=settable,
+            serializable=serializable,
+            user_defined=user_defined,
+            element_id=element_id,
+            element_type=element_type,
+            parent_container_name=parent_container_name,
+        )
+
+    @property
+    def pulse_on_run(self) -> bool:
+        """Get whether pulse on run is enabled.
+
+        Returns:
+            True if pulse on run is enabled, False otherwise
+        """
+        return self.ui_options.get("pulse_on_run", False)
+
+    @pulse_on_run.setter
+    def pulse_on_run(self, value: bool) -> None:
+        """Set whether pulse on run is enabled.
+
+        Args:
+            value: Whether to enable pulse on run
+        """
+        if value:
+            self.update_ui_options_key("pulse_on_run", value)
+        else:
+            ui_options = self.ui_options.copy()
+            ui_options.pop("pulse_on_run", None)
+            self.ui_options = ui_options
+
+    @property
+    def clickable_file_browser(self) -> bool:
+        """Get whether clickable file browser is enabled.
+
+        Returns:
+            True if clickable file browser is enabled, False otherwise
+        """
+        return self.ui_options.get("clickable_file_browser", False)
+
+    @clickable_file_browser.setter
+    def clickable_file_browser(self, value: bool) -> None:
+        """Set whether clickable file browser is enabled.
+
+        Args:
+            value: Whether to enable clickable file browser
+        """
+        if value:
+            self.update_ui_options_key("clickable_file_browser", value)
+        else:
+            ui_options = self.ui_options.copy()
+            ui_options.pop("clickable_file_browser", None)
+            self.ui_options = ui_options
+
+    @property
+    def microphone_capture_audio(self) -> bool:
+        """Get whether microphone capture audio is enabled.
+
+        Returns:
+            True if microphone capture audio is enabled, False otherwise
+        """
+        return self.ui_options.get("microphone_capture_audio", False)
+
+    @microphone_capture_audio.setter
+    def microphone_capture_audio(self, value: bool) -> None:
+        """Set whether microphone capture audio is enabled.
+
+        Args:
+            value: Whether to enable microphone capture audio
+        """
+        if value:
+            self.update_ui_options_key("microphone_capture_audio", value)
+        else:
+            ui_options = self.ui_options.copy()
+            ui_options.pop("microphone_capture_audio", None)
+            self.ui_options = ui_options
+
+    @property
+    def edit_audio(self) -> bool:
+        """Get whether edit audio is enabled.
+
+        Returns:
+            True if edit audio is enabled, False otherwise
+        """
+        return self.ui_options.get("edit_audio", False)
+
+    @edit_audio.setter
+    def edit_audio(self, value: bool) -> None:
+        """Set whether edit audio is enabled.
+
+        Args:
+            value: Whether to enable edit audio
+        """
+        if value:
+            self.update_ui_options_key("edit_audio", value)
+        else:
+            ui_options = self.ui_options.copy()
+            ui_options.pop("edit_audio", None)
+            self.ui_options = ui_options