griptape-nodes 0.60.3__py3-none-any.whl → 0.61.0__py3-none-any.whl

griptape_nodes/common/project_templates/project.py

@@ -0,0 +1,252 @@
+"""Project template main class."""
+
+from __future__ import annotations
+
+import io
+from typing import TYPE_CHECKING, ClassVar
+
+from pydantic import BaseModel, Field, ValidationError
+from ruamel.yaml import YAML
+
+from griptape_nodes.common.project_templates.directory import DirectoryDefinition
+from griptape_nodes.common.project_templates.situation import SituationTemplate
+from griptape_nodes.common.project_templates.validation import (
+    ProjectOverrideAction,
+    ProjectOverrideCategory,
+    ProjectValidationInfo,
+)
+
+if TYPE_CHECKING:
+    from griptape_nodes.common.project_templates.loader import ProjectOverlayData
+
+
+class ProjectTemplate(BaseModel):
+    """Complete project template loaded from project.yml."""
+
+    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.1.0"
+
+    project_template_schema_version: str = Field(description="Schema version for the project template")
+    name: str = Field(description="Name of the project")
+    situations: dict[str, SituationTemplate] = Field(description="Situation templates (situation_name -> template)")
+    directories: dict[str, DirectoryDefinition] = Field(
+        description="Directory definitions (logical_name -> definition)"
+    )
+    environment: dict[str, str] = Field(default_factory=dict, description="Custom environment variables")
+    description: str | None = Field(default=None, description="Description of the project")
+
+    def get_situation(self, situation_name: str) -> SituationTemplate | None:
+        """Get a situation by name, returns None if not found."""
+        return self.situations.get(situation_name)
+
+    def get_directory(self, directory_name: str) -> DirectoryDefinition | None:
+        """Get a directory definition by logical name."""
+        return self.directories.get(directory_name)
+
+    def to_yaml(self, *, include_comments: bool = True) -> str:
+        """Export project template to YAML string.
+
+        If include_comments=True, adds helpful comments explaining each section.
+        """
+        yaml = YAML()
+        yaml.preserve_quotes = True
+        yaml.default_flow_style = False
+
+        data = self.model_dump(mode="json", exclude_none=True)
+
+        # Convert to YAML string
+        stream = io.StringIO()
+        yaml.dump(data, stream)
+        yaml_text = stream.getvalue()
+
+        if include_comments:
+            # Add helpful header comment
+            header = (
+                "# Project Template\n"
+                f"# Version: {self.project_template_schema_version}\n"
+                "#\n"
+                "# This file defines how files are organized and saved in your project.\n"
+                "# See documentation for details on customizing situations and directories.\n\n"
+            )
+            yaml_text = header + yaml_text
+
+        return yaml_text
+
+    @staticmethod
+    def merge(  # noqa: C901, PLR0912
+        base: ProjectTemplate,
+        overlay: ProjectOverlayData,
+        validation_info: ProjectValidationInfo,
+    ) -> ProjectTemplate:
+        """Merge overlay data on top of base template.
+
+        Merge behavior:
+        - name: From overlay (required)
+        - description: From overlay if present, else base
+        - project_template_schema_version: From overlay (required)
+        - situations: Dict merge with field-level merging for conflicts
+        - directories: Dict merge with field-level merging for conflicts
+        - environment: Dict merge (overlay values override base)
+
+        Override tracking (non-status-affecting):
+        - Metadata: name (always MODIFIED), description (if different)
+        - Situations: MODIFIED if exists in base, ADDED if new
+        - Directories: MODIFIED if exists in base, ADDED if new
+        - Environment: MODIFIED if exists in base, ADDED if new
+
+        Note: Schema version compatibility should be checked by caller (ProjectManager)
+        before calling merge. This method does not validate version compatibility.
+
+        Args:
+            base: Fully constructed base template (e.g., system defaults)
+            overlay: Partially validated overlay data with raw dicts
+            validation_info: Fresh ProjectValidationInfo for tracking overrides and errors
+
+        Returns:
+            New fully constructed merged ProjectTemplate with validation_info
+        """
+        # Track metadata overrides
+        validation_info.add_override(
+            category=ProjectOverrideCategory.METADATA,
+            name="name",
+            action=ProjectOverrideAction.MODIFIED,
+        )
+
+        if overlay.description is not None and overlay.description != base.description:
+            validation_info.add_override(
+                category=ProjectOverrideCategory.METADATA,
+                name="description",
+                action=ProjectOverrideAction.MODIFIED,
+            )
+
+        # Merge situations
+        merged_situations: dict[str, SituationTemplate] = {}
+
+        # Start with all base situations
+        for sit_name, base_sit in base.situations.items():
+            if sit_name in overlay.situations:
+                # Field-level merge
+                merged_sit = SituationTemplate.merge(
+                    base=base_sit,
+                    overlay_data=overlay.situations[sit_name],
+                    field_path=f"situations.{sit_name}",
+                    validation_info=validation_info,
+                    line_info=overlay.line_info,
+                )
+                merged_situations[sit_name] = merged_sit
+
+                validation_info.add_override(
+                    category=ProjectOverrideCategory.SITUATION,
+                    name=sit_name,
+                    action=ProjectOverrideAction.MODIFIED,
+                )
+            else:
+                # Inherit from base
+                merged_situations[sit_name] = base_sit
+
+        # Add new situations from overlay
+        for sit_name, sit_data in overlay.situations.items():
+            if sit_name not in base.situations:
+                # New situation - construct from scratch
+                # Add name to dict for model_validate
+                sit_data_with_name = {"name": sit_name, **sit_data}
+
+                try:
+                    new_sit = SituationTemplate.model_validate(sit_data_with_name)
+                    merged_situations[sit_name] = new_sit
+
+                    validation_info.add_override(
+                        category=ProjectOverrideCategory.SITUATION,
+                        name=sit_name,
+                        action=ProjectOverrideAction.ADDED,
+                    )
+                except ValidationError as e:
+                    # Convert Pydantic validation errors
+                    for error in e.errors():
+                        error_field_path = ".".join(str(loc) for loc in error["loc"])
+                        full_field_path = f"situations.{sit_name}.{error_field_path}"
+                        message = error["msg"]
+                        line_number = overlay.line_info.get_line(full_field_path)
+
+                        validation_info.add_error(
+                            field_path=full_field_path,
+                            message=message,
+                            line_number=line_number,
+                        )
+
+        # Merge directories
+        merged_directories: dict[str, DirectoryDefinition] = {}
+
+        for dir_name, base_dir in base.directories.items():
+            if dir_name in overlay.directories:
+                # Field-level merge
+                merged_dir = DirectoryDefinition.merge(
+                    base=base_dir,
+                    overlay_data=overlay.directories[dir_name],
+                    field_path=f"directories.{dir_name}",
+                    validation_info=validation_info,
+                    line_info=overlay.line_info,
+                )
+                merged_directories[dir_name] = merged_dir
+
+                validation_info.add_override(
+                    category=ProjectOverrideCategory.DIRECTORY,
+                    name=dir_name,
+                    action=ProjectOverrideAction.MODIFIED,
+                )
+            else:
+                # Inherit from base
+                merged_directories[dir_name] = base_dir
+
+        # Add new directories from overlay
+        for dir_name, dir_data in overlay.directories.items():
+            if dir_name not in base.directories:
+                # New directory - construct from scratch
+                # Add name to dict for model_validate
+                dir_data_with_name = {"name": dir_name, **dir_data}
+
+                try:
+                    new_dir = DirectoryDefinition.model_validate(dir_data_with_name)
+                    merged_directories[dir_name] = new_dir
+
+                    validation_info.add_override(
+                        category=ProjectOverrideCategory.DIRECTORY,
+                        name=dir_name,
+                        action=ProjectOverrideAction.ADDED,
+                    )
+                except ValidationError as e:
+                    # Convert Pydantic validation errors
+                    for error in e.errors():
+                        error_field_path = ".".join(str(loc) for loc in error["loc"])
+                        full_field_path = f"directories.{dir_name}.{error_field_path}"
+                        message = error["msg"]
+                        line_number = overlay.line_info.get_line(full_field_path)
+
+                        validation_info.add_error(
+                            field_path=full_field_path,
+                            message=message,
+                            line_number=line_number,
+                        )
+
+        # Merge environment
+        merged_environment = {**base.environment}
+        for key, value in overlay.environment.items():
+            action = ProjectOverrideAction.MODIFIED if key in base.environment else ProjectOverrideAction.ADDED
+            merged_environment[key] = value
+
+            validation_info.add_override(
+                category=ProjectOverrideCategory.ENVIRONMENT,
+                name=key,
+                action=action,
+            )
+
+        # Use overlay metadata, fall back to base for description
+        merged_description = overlay.description if overlay.description is not None else base.description
+
+        return ProjectTemplate(
+            project_template_schema_version=overlay.project_template_schema_version,
+            name=overlay.name,
+            situations=merged_situations,
+            directories=merged_directories,
+            environment=merged_environment,
+            description=merged_description,
+        )

griptape_nodes/common/project_templates/situation.py

@@ -0,0 +1,155 @@
+"""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 schema
+    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")
+    situation_template_schema_version: str = Field(description="Schema version for this situation template")
+    macro: str = Field(
+        description="Macro template for file path", serialization_alias="schema", validation_alias="schema"
+    )
+    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
+
+    @property
+    def schema(self) -> str:
+        """Alias for macro to maintain YAML compatibility (schema field in YAML)."""
+        return self.macro
+
+    @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:
+        - schema: 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
+        - situation_template_schema_version: Use overlay if present, 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 "schema" in overlay_data:
+            merged_data["schema"] = overlay_data["schema"]
+
+        if "description" in overlay_data:
+            merged_data["description"] = overlay_data["description"]
+
+        if "fallback" in overlay_data:
+            merged_data["fallback"] = overlay_data["fallback"]
+
+        if "situation_template_schema_version" in overlay_data:
+            merged_data["situation_template_schema_version"] = overlay_data["situation_template_schema_version"]
+
+        # 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.schema"
+    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)