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

griptape_nodes/bootstrap/workflow_publishers/local_workflow_publisher.py

@@ -32,7 +32,6 @@ class LocalWorkflowPublisher(LocalWorkflowExecutor):
         publish_workflow_request = PublishWorkflowRequest(
             workflow_name=workflow_name,
             publisher_name=publisher_name,
-            execute_on_publish=False,
             published_workflow_file_name=published_workflow_file_name,
             pickle_control_flow_result=pickle_control_flow_result,
         )

griptape_nodes/common/macro_parser/__init__.py

@@ -1,7 +1,16 @@
 """Macro language parser for template-based path generation."""
 
 from griptape_nodes.common.macro_parser.core import ParsedMacro
-from griptape_nodes.common.macro_parser.exceptions import MacroResolutionError, MacroSyntaxError
+from griptape_nodes.common.macro_parser.exceptions import (
+    MacroMatchFailure,
+    MacroMatchFailureReason,
+    MacroParseFailure,
+    MacroParseFailureReason,
+    MacroResolutionError,
+    MacroResolutionFailure,
+    MacroResolutionFailureReason,
+    MacroSyntaxError,
+)
 from griptape_nodes.common.macro_parser.formats import (
     DateFormat,
     LowerCaseFormat,
@@ -15,7 +24,13 @@ from griptape_nodes.common.macro_parser.segments import ParsedStaticValue, Parse
 __all__ = [
     "DateFormat",
     "LowerCaseFormat",
+    "MacroMatchFailure",
+    "MacroMatchFailureReason",
+    "MacroParseFailure",
+    "MacroParseFailureReason",
     "MacroResolutionError",
+    "MacroResolutionFailure",
+    "MacroResolutionFailureReason",
     "MacroSyntaxError",
     "NumericPaddingFormat",
     "ParsedMacro",

griptape_nodes/common/macro_parser/core.py

@@ -4,7 +4,11 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from griptape_nodes.common.macro_parser.exceptions import MacroResolutionError, MacroSyntaxError
+from griptape_nodes.common.macro_parser.exceptions import (
+    MacroResolutionError,
+    MacroResolutionFailureReason,
+    MacroSyntaxError,
+)
 from griptape_nodes.common.macro_parser.matching import extract_unknown_variables
 from griptape_nodes.common.macro_parser.parsing import parse_segments
 from griptape_nodes.common.macro_parser.resolution import partial_resolve
@@ -28,7 +32,11 @@ class ParsedMacro:
             segments = parse_segments(template)
         except MacroSyntaxError as err:
             msg = f"Attempted to parse template string '{template}'. Failed due to: {err}"
-            raise MacroSyntaxError(msg) from err
+            raise MacroSyntaxError(
+                msg,
+                failure_reason=err.failure_reason,
+                error_position=err.error_position,
+            ) from err
 
         if not segments:
             segments.append(ParsedStaticValue(text=""))
@@ -52,7 +60,11 @@ class ParsedMacro:
             unresolved = partial.get_unresolved_variables()
             unresolved_names = [var.info.name for var in unresolved]
             msg = f"Cannot fully resolve macro - missing required variables: {', '.join(unresolved_names)}"
-            raise MacroResolutionError(msg)
+            raise MacroResolutionError(
+                msg,
+                failure_reason=MacroResolutionFailureReason.MISSING_REQUIRED_VARIABLES,
+                missing_variables=unresolved_names,
+            )
 
         # Convert to string
         return partial.to_string()

griptape_nodes/common/macro_parser/exceptions.py

@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
+from enum import StrEnum
+
 
 class MacroSyntaxError(Exception):
     """Raised when macro template has invalid syntax.
@@ -12,6 +15,23 @@ class MacroSyntaxError(Exception):
     - Nested braces: "{outer_{inner}}"
     """
 
+    def __init__(
+        self,
+        message: str,
+        failure_reason: MacroParseFailureReason | None = None,
+        error_position: int | None = None,
+    ) -> None:
+        """Initialize MacroSyntaxError with optional structured fields.
+
+        Args:
+            message: Human-readable error message
+            failure_reason: Specific reason for the syntax error
+            error_position: Character position where error occurred
+        """
+        super().__init__(message)
+        self.failure_reason = failure_reason
+        self.error_position = error_position
+
 
 class MacroResolutionError(Exception):
     """Raised when macro cannot be resolved with provided variables.
@@ -21,3 +41,82 @@ class MacroResolutionError(Exception):
     - Environment variable referenced but not found in environment
     - Format specifier cannot be applied to value type (e.g., :03 on string)
     """
+
+    def __init__(
+        self,
+        message: str,
+        failure_reason: MacroResolutionFailureReason | None = None,
+        variable_name: str | None = None,
+        missing_variables: list[str] | None = None,
+    ) -> None:
+        """Initialize MacroResolutionError with optional structured fields.
+
+        Args:
+            message: Human-readable error message
+            failure_reason: Specific reason for the resolution error
+            variable_name: Name of the problematic variable (if applicable)
+            missing_variables: List of missing variable names (for MISSING_REQUIRED_VARIABLES)
+        """
+        super().__init__(message)
+        self.failure_reason = failure_reason
+        self.variable_name = variable_name
+        self.missing_variables = missing_variables
+
+
+class MacroMatchFailureReason(StrEnum):
+    """Reason why path matching failed."""
+
+    STATIC_TEXT_MISMATCH = "STATIC_TEXT_MISMATCH"
+    DELIMITER_NOT_FOUND = "DELIMITER_NOT_FOUND"
+    FORMAT_REVERSAL_FAILED = "FORMAT_REVERSAL_FAILED"
+    INVALID_MACRO_SYNTAX = "INVALID_MACRO_SYNTAX"
+
+
+class MacroParseFailureReason(StrEnum):
+    """Reason why macro parsing failed."""
+
+    UNMATCHED_CLOSING_BRACE = "UNMATCHED_CLOSING_BRACE"
+    UNCLOSED_BRACE = "UNCLOSED_BRACE"
+    NESTED_BRACES = "NESTED_BRACES"
+    EMPTY_VARIABLE = "EMPTY_VARIABLE"
+    UNEXPECTED_SEGMENT_TYPE = "UNEXPECTED_SEGMENT_TYPE"
+
+
+class MacroResolutionFailureReason(StrEnum):
+    """Reason why macro resolution failed."""
+
+    NUMERIC_PADDING_ON_NON_NUMERIC = "NUMERIC_PADDING_ON_NON_NUMERIC"
+    INVALID_INTEGER_PARSE = "INVALID_INTEGER_PARSE"
+    DATE_FORMAT_NOT_IMPLEMENTED = "DATE_FORMAT_NOT_IMPLEMENTED"
+    MISSING_REQUIRED_VARIABLES = "MISSING_REQUIRED_VARIABLES"
+    ENVIRONMENT_VARIABLE_NOT_FOUND = "ENVIRONMENT_VARIABLE_NOT_FOUND"
+    UNEXPECTED_SEGMENT_TYPE = "UNEXPECTED_SEGMENT_TYPE"
+
+
+@dataclass
+class MacroMatchFailure:
+    """Details about why a macro match failed."""
+
+    failure_reason: MacroMatchFailureReason
+    expected_pattern: str
+    known_variables_used: dict[str, str | int]
+    error_details: str
+
+
+@dataclass
+class MacroParseFailure:
+    """Details about why macro parsing failed."""
+
+    failure_reason: MacroParseFailureReason
+    error_position: int | None
+    error_details: str
+
+
+@dataclass
+class MacroResolutionFailure:
+    """Details about why macro resolution failed."""
+
+    failure_reason: MacroResolutionFailureReason
+    variable_name: str | None
+    missing_variables: list[str] | None
+    error_details: str

griptape_nodes/common/macro_parser/formats.py

@@ -6,7 +6,7 @@ import re
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 
-from griptape_nodes.common.macro_parser.exceptions import MacroResolutionError
+from griptape_nodes.common.macro_parser.exceptions import MacroResolutionError, MacroResolutionFailureReason
 
 
 @dataclass
@@ -89,7 +89,10 @@ class NumericPaddingFormat(FormatSpec):
                     f"Numeric padding format :{self.width:0{self.width}d} "
                     f"cannot be applied to non-numeric value: {value}"
                 )
-                raise MacroResolutionError(msg)
+                raise MacroResolutionError(
+                    msg,
+                    failure_reason=MacroResolutionFailureReason.NUMERIC_PADDING_ON_NON_NUMERIC,
+                )
             value = int(value)
         return f"{value:0{self.width}d}"
 
@@ -99,7 +102,10 @@ class NumericPaddingFormat(FormatSpec):
             return int(value)
         except ValueError as e:
             msg = f"Cannot parse '{value}' as integer"
-            raise MacroResolutionError(msg) from e
+            raise MacroResolutionError(
+                msg,
+                failure_reason=MacroResolutionFailureReason.INVALID_INTEGER_PARSE,
+            ) from e
 
 
 @dataclass
@@ -154,7 +160,10 @@ class DateFormat(FormatSpec):
         """Apply date formatting."""
         # TODO(https://github.com/griptape-ai/griptape-nodes/issues/2717): Implement date formatting
         msg = "DateFormat not yet fully implemented"
-        raise MacroResolutionError(msg)
+        raise MacroResolutionError(
+            msg,
+            failure_reason=MacroResolutionFailureReason.DATE_FORMAT_NOT_IMPLEMENTED,
+        )
 
     def reverse(self, value: str) -> str:
         """Attempt to parse date string."""

griptape_nodes/common/macro_parser/matching.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from griptape_nodes.common.macro_parser.exceptions import MacroSyntaxError
+from griptape_nodes.common.macro_parser.exceptions import MacroParseFailureReason, MacroSyntaxError
 from griptape_nodes.common.macro_parser.segments import (
     ParsedSegment,
     ParsedStaticValue,
@@ -49,7 +49,10 @@ def extract_unknown_variables(
                 current_pos = new_pos
             case _:
                 msg = f"Unexpected segment type: {type(segment).__name__}"
-                raise MacroSyntaxError(msg)
+                raise MacroSyntaxError(
+                    msg,
+                    failure_reason=MacroParseFailureReason.UNEXPECTED_SEGMENT_TYPE,
+                )
 
     return current_match
 

griptape_nodes/common/macro_parser/parsing.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import re
 
-from griptape_nodes.common.macro_parser.exceptions import MacroSyntaxError
+from griptape_nodes.common.macro_parser.exceptions import MacroParseFailureReason, MacroSyntaxError
 from griptape_nodes.common.macro_parser.formats import (
     FORMAT_REGISTRY,
     DateFormat,
@@ -47,7 +47,11 @@ def parse_segments(template: str) -> list[ParsedSegment]:
                 if "}" in static_text:
                     closing_pos = current_pos + static_text.index("}")
                     msg = f"Unmatched closing brace at position {closing_pos}"
-                    raise MacroSyntaxError(msg)
+                    raise MacroSyntaxError(
+                        msg,
+                        failure_reason=MacroParseFailureReason.UNMATCHED_CLOSING_BRACE,
+                        error_position=closing_pos,
+                    )
                 segments.append(ParsedStaticValue(text=static_text))
             break
 
@@ -58,26 +62,42 @@ def parse_segments(template: str) -> list[ParsedSegment]:
             if "}" in static_text:
                 closing_pos = current_pos + static_text.index("}")
                 msg = f"Unmatched closing brace at position {closing_pos}"
-                raise MacroSyntaxError(msg)
+                raise MacroSyntaxError(
+                    msg,
+                    failure_reason=MacroParseFailureReason.UNMATCHED_CLOSING_BRACE,
+                    error_position=closing_pos,
+                )
             segments.append(ParsedStaticValue(text=static_text))
 
         # Find matching closing brace
         brace_end = template.find("}", brace_start)
         if brace_end == -1:
             msg = f"Unclosed brace at position {brace_start}"
-            raise MacroSyntaxError(msg)
+            raise MacroSyntaxError(
+                msg,
+                failure_reason=MacroParseFailureReason.UNCLOSED_BRACE,
+                error_position=brace_start,
+            )
 
         # Check for nested braces (opening brace before closing brace)
         next_open = template.find("{", brace_start + 1)
         if next_open != -1 and next_open < brace_end:
             msg = f"Nested braces are not allowed at position {next_open}"
-            raise MacroSyntaxError(msg)
+            raise MacroSyntaxError(
+                msg,
+                failure_reason=MacroParseFailureReason.NESTED_BRACES,
+                error_position=next_open,
+            )
 
         # Extract and parse the variable content
         variable_content = template[brace_start + 1 : brace_end]
         if not variable_content:
             msg = f"Empty variable at position {brace_start}"
-            raise MacroSyntaxError(msg)
+            raise MacroSyntaxError(
+                msg,
+                failure_reason=MacroParseFailureReason.EMPTY_VARIABLE,
+                error_position=brace_start,
+            )
 
         variable = parse_variable(variable_content)
         segments.append(variable)
@@ -111,6 +131,7 @@ def parse_variable(variable_content: str) -> ParsedVariable:
 
     # Check for format specifiers (:)
     format_specs: list[FormatSpec] = []
+    is_required = True
     if ":" in variable_content:
         parts = variable_content.split(":")
         variable_part = parts[0]
@@ -120,16 +141,35 @@ def parse_variable(variable_content: str) -> ParsedVariable:
         for format_part in format_parts:
             format_spec = parse_format_spec(format_part)
             format_specs.append(format_spec)
+
+        # Check if last format spec ends with unquoted ?
+        if format_parts:
+            last_format_part = format_parts[-1]
+
+            # Check if it's quoted (quoted formats preserve ? as literal)
+            is_quoted = last_format_part.startswith("'") and last_format_part.endswith("'")
+
+            if not is_quoted and last_format_part.endswith("?"):
+                # Strip the ? and re-parse the format
+                stripped_format = last_format_part[:-1]
+                if stripped_format:
+                    # Re-parse without the ?
+                    format_specs[-1] = parse_format_spec(stripped_format)
+                else:
+                    # Format was just "?", remove it entirely
+                    format_specs.pop()
+
+                # Mark variable as optional
+                is_required = False
     else:
         variable_part = variable_content
 
-    # Check for optional marker (?)
+    # Check for optional marker (?) after variable name
     if variable_part.endswith("?"):
         name = variable_part[:-1]
         is_required = False
     else:
         name = variable_part
-        is_required = True
 
     info = VariableInfo(name=name, is_required=is_required)
     return ParsedVariable(info=info, format_specs=format_specs, default_value=default_value)

griptape_nodes/common/macro_parser/resolution.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from griptape_nodes.common.macro_parser.exceptions import MacroResolutionError
+from griptape_nodes.common.macro_parser.exceptions import MacroResolutionError, MacroResolutionFailureReason
 from griptape_nodes.common.macro_parser.segments import ParsedSegment, ParsedStaticValue, ParsedVariable
 
 if TYPE_CHECKING:
@@ -31,8 +31,14 @@ class PartiallyResolvedMacro:
     def to_string(self) -> str:
         """Convert to string (only valid if fully resolved)."""
         if not self.is_fully_resolved():
+            unresolved = self.get_unresolved_variables()
+            unresolved_names = [var.info.name for var in unresolved]
             msg = "Cannot convert partially resolved macro to string - unresolved variables remain"
-            raise MacroResolutionError(msg)
+            raise MacroResolutionError(
+                msg,
+                failure_reason=MacroResolutionFailureReason.MISSING_REQUIRED_VARIABLES,
+                missing_variables=unresolved_names,
+            )
         # All segments are ParsedStaticValue at this point
         return "".join(seg.text for seg in self.segments if isinstance(seg, ParsedStaticValue))
 
@@ -92,7 +98,10 @@ def partial_resolve(
                 continue
             case _:
                 msg = f"Unexpected segment type: {type(segment).__name__}"
-                raise MacroResolutionError(msg)
+                raise MacroResolutionError(
+                    msg,
+                    failure_reason=MacroResolutionFailureReason.UNEXPECTED_SEGMENT_TYPE,
+                )
 
     return PartiallyResolvedMacro(
         original_template=template,
@@ -122,7 +131,12 @@ def resolve_variable(
     if variable_name not in variables:
         if variable.info.is_required:
             msg = f"Required variable '{variable_name}' not found in variables dict"
-            raise MacroResolutionError(msg)
+            raise MacroResolutionError(
+                msg,
+                failure_reason=MacroResolutionFailureReason.MISSING_REQUIRED_VARIABLES,
+                variable_name=variable_name,
+                missing_variables=[variable_name],
+            )
         # Optional variable not provided, return None to signal it should be skipped
         return None
 
@@ -162,7 +176,11 @@ def resolve_env_var(value: str | int, secrets_manager: SecretsManager) -> str |
 
     if env_value is None:
         msg = f"Environment variable '{env_var_name}' not found"
-        raise MacroResolutionError(msg)
+        raise MacroResolutionError(
+            msg,
+            failure_reason=MacroResolutionFailureReason.ENVIRONMENT_VARIABLE_NOT_FOUND,
+            variable_name=env_var_name,
+        )
 
     # Return resolved env var value
     return env_value

griptape_nodes/common/project_templates/__init__.py

@@ -0,0 +1,49 @@
+"""Project template system for managing project.yml files and situations."""
+
+from griptape_nodes.common.project_templates.default_project_template import DEFAULT_PROJECT_TEMPLATE
+from griptape_nodes.common.project_templates.directory import DirectoryDefinition
+from griptape_nodes.common.project_templates.loader import (
+    ProjectOverlayData,
+    YAMLLineInfo,
+    YAMLParseResult,
+    load_partial_project_template,
+    load_project_template_from_yaml,
+    load_yaml_with_line_tracking,
+)
+from griptape_nodes.common.project_templates.project import ProjectTemplate
+from griptape_nodes.common.project_templates.situation import (
+    SituationFilePolicy,
+    SituationPolicy,
+    SituationTemplate,
+)
+from griptape_nodes.common.project_templates.validation import (
+    ProjectOverride,
+    ProjectOverrideAction,
+    ProjectOverrideCategory,
+    ProjectValidationInfo,
+    ProjectValidationProblem,
+    ProjectValidationProblemSeverity,
+    ProjectValidationStatus,
+)
+
+__all__ = [
+    "DEFAULT_PROJECT_TEMPLATE",
+    "DirectoryDefinition",
+    "ProjectOverlayData",
+    "ProjectOverride",
+    "ProjectOverrideAction",
+    "ProjectOverrideCategory",
+    "ProjectTemplate",
+    "ProjectValidationInfo",
+    "ProjectValidationProblem",
+    "ProjectValidationProblemSeverity",
+    "ProjectValidationStatus",
+    "SituationFilePolicy",
+    "SituationPolicy",
+    "SituationTemplate",
+    "YAMLLineInfo",
+    "YAMLParseResult",
+    "load_partial_project_template",
+    "load_project_template_from_yaml",
+    "load_yaml_with_line_tracking",
+]

griptape_nodes/common/project_templates/default_project_template.py

@@ -0,0 +1,92 @@
+"""Default project template defined in Python using Pydantic models."""
+
+from griptape_nodes.common.project_templates.directory import DirectoryDefinition
+from griptape_nodes.common.project_templates.project import ProjectTemplate
+from griptape_nodes.common.project_templates.situation import (
+    SituationFilePolicy,
+    SituationPolicy,
+    SituationTemplate,
+)
+
+# Default project template matching the values from project_template.yml
+DEFAULT_PROJECT_TEMPLATE = ProjectTemplate(
+    project_template_schema_version="0.1.0",
+    name="Default Project",
+    description="System default configuration",
+    directories={
+        "inputs": DirectoryDefinition(
+            name="inputs",
+            path_schema="inputs",
+        ),
+        "outputs": DirectoryDefinition(
+            name="outputs",
+            path_schema="outputs",
+        ),
+        "temp": DirectoryDefinition(
+            name="temp",
+            path_schema="temp",
+        ),
+        "previews": DirectoryDefinition(
+            name="previews",
+            path_schema="previews",
+        ),
+    },
+    environment={},
+    situations={
+        "save_file": SituationTemplate(
+            name="save_file",
+            situation_template_schema_version="0.1.0",
+            description="Generic file save operation",
+            macro="{file_name_base}{_index?:03}.{file_extension}",
+            policy=SituationPolicy(
+                on_collision=SituationFilePolicy.CREATE_NEW,
+                create_dirs=True,
+            ),
+            fallback=None,
+        ),
+        "copy_external_file": SituationTemplate(
+            name="copy_external_file",
+            situation_template_schema_version="0.1.0",
+            description="User copies external file to project",
+            macro="{inputs}/{node_name?:_}{parameter_name?:_}{file_name_base}{_index?:03}.{file_extension}",
+            policy=SituationPolicy(
+                on_collision=SituationFilePolicy.CREATE_NEW,
+                create_dirs=True,
+            ),
+            fallback="save_file",
+        ),
+        "download_url": SituationTemplate(
+            name="download_url",
+            situation_template_schema_version="0.1.0",
+            description="Download file from URL",
+            macro="{inputs}/{sanitized_url}",
+            policy=SituationPolicy(
+                on_collision=SituationFilePolicy.OVERWRITE,
+                create_dirs=True,
+            ),
+            fallback="save_file",
+        ),
+        "save_node_output": SituationTemplate(
+            name="save_node_output",
+            situation_template_schema_version="0.1.0",
+            description="Node generates and saves output",
+            macro="{outputs}/{node_name?:_}{file_name_base}{_index?:03}.{file_extension}",
+            policy=SituationPolicy(
+                on_collision=SituationFilePolicy.CREATE_NEW,
+                create_dirs=True,
+            ),
+            fallback="save_file",
+        ),
+        "save_preview": SituationTemplate(
+            name="save_preview",
+            situation_template_schema_version="0.1.0",
+            description="Generate preview/thumbnail",
+            macro="{previews}/{original_file_path}",
+            policy=SituationPolicy(
+                on_collision=SituationFilePolicy.OVERWRITE,
+                create_dirs=True,
+            ),
+            fallback="save_file",
+        ),
+    },
+)

griptape_nodes/common/project_templates/defaults/README.md

@@ -0,0 +1,36 @@
+# System Default Project Template
+
+This directory contains the system default project template used when no `project.yml` exists in a project.
+
+## Files
+
+- `project_template.yml` - Complete default project configuration with all situations
+
+## Validation
+
+The default template is loaded and validated at module import time. If validation fails, the system will raise a RuntimeError with details about what's broken.
+
+This ensures:
+
+- Default template is always valid
+- Typos/errors are caught immediately in CI/tests
+- Users can rely on defaults being correct
+
+## Modifying Defaults
+
+When modifying `project_template.yml`:
+
+1. Ensure all syntax is correct (YAML, macro templates, etc.)
+1. Run tests to validate changes
+1. Update version numbers if making breaking changes
+1. Update comments to keep documentation in sync
+
+## Usage
+
+Users can copy this file to their project root as `project.yml` and customize it:
+
+```bash
+cp defaults/project_template.yml /path/to/project/project.yml
+```
+
+The system will automatically use the project-specific version instead of these defaults.