griptape-nodes 0.59.2__tar.gz → 0.60.0__tar.gz

{griptape_nodes-0.59.2 → griptape_nodes-0.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: griptape-nodes
-Version: 0.59.2
+Version: 0.60.0
 Summary: Add your description here
 Requires-Dist: griptape>=1.8.8
 Requires-Dist: pydantic>=2.10.6

{griptape_nodes-0.59.2 → griptape_nodes-0.60.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "griptape-nodes"
-version = "0.59.2"
+version = "0.60.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12.0, <3.13"

griptape_nodes-0.60.0/src/griptape_nodes/common/macro_parser/__init__.py

@@ -0,0 +1,28 @@
+"""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.formats import (
+    DateFormat,
+    LowerCaseFormat,
+    NumericPaddingFormat,
+    SeparatorFormat,
+    SlugFormat,
+    UpperCaseFormat,
+)
+from griptape_nodes.common.macro_parser.segments import ParsedStaticValue, ParsedVariable, VariableInfo
+
+__all__ = [
+    "DateFormat",
+    "LowerCaseFormat",
+    "MacroResolutionError",
+    "MacroSyntaxError",
+    "NumericPaddingFormat",
+    "ParsedMacro",
+    "ParsedStaticValue",
+    "ParsedVariable",
+    "SeparatorFormat",
+    "SlugFormat",
+    "UpperCaseFormat",
+    "VariableInfo",
+]

griptape_nodes-0.60.0/src/griptape_nodes/common/macro_parser/core.py

@@ -0,0 +1,230 @@
+"""Core ParsedMacro class - main API for macro templates."""
+
+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.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
+from griptape_nodes.common.macro_parser.segments import ParsedStaticValue, ParsedVariable, VariableInfo
+
+if TYPE_CHECKING:
+    from griptape_nodes.retained_mode.managers.secrets_manager import SecretsManager
+
+
+class ParsedMacro:
+    """Parsed macro template with methods for resolving and matching paths.
+
+    This is the main API class for working with macro templates.
+    """
+
+    def __init__(self, template: str) -> None:
+        """Parse a macro template string, validating syntax."""
+        self.template = template
+
+        try:
+            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
+
+        if not segments:
+            segments.append(ParsedStaticValue(text=""))
+        self.segments = segments
+
+    def get_variables(self) -> list[VariableInfo]:
+        """Extract all VariableInfo from parsed segments."""
+        return [seg.info for seg in self.segments if isinstance(seg, ParsedVariable)]
+
+    def resolve(
+        self,
+        variables: dict[str, str | int],
+        secrets_manager: SecretsManager,
+    ) -> str:
+        """Fully resolve the macro template with variable values."""
+        # Partially resolve with known variables
+        partial = partial_resolve(self.template, self.segments, variables, secrets_manager)
+
+        # Check if fully resolved
+        if not partial.is_fully_resolved():
+            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)
+
+        # Convert to string
+        return partial.to_string()
+
+    def matches(
+        self,
+        path: str,
+        known_variables: dict[str, str | int],
+        secrets_manager: SecretsManager,
+    ) -> bool:
+        """Check if a path matches this template."""
+        result = self.find_matches_detailed(path, known_variables, secrets_manager)
+        return result is not None
+
+    def extract_variables(
+        self,
+        path: str,
+        known_variables: dict[str, str | int],
+        secrets_manager: SecretsManager,
+    ) -> dict[str, str | int] | None:
+        """Extract variable values from a path (plain string keys)."""
+        detailed = self.find_matches_detailed(path, known_variables, secrets_manager)
+        if detailed is None:
+            return None
+        # Convert VariableInfo keys to plain string keys
+        return {var_info.name: value for var_info, value in detailed.items()}
+
+    def find_matches_detailed(
+        self,
+        path: str,
+        known_variables: dict[str, str | int],
+        secrets_manager: SecretsManager,
+    ) -> dict[VariableInfo, str | int] | None:
+        """Extract variable values from a path with metadata (greedy match).
+
+        This is the advanced version that returns detailed variable metadata with VariableInfo keys.
+        Most callers should use extract_variables() for plain dict or matches() for boolean check.
+
+        Given a parsed template and a path, extracts variable values by matching
+        the path against the template pattern. Known variables are resolved before
+        matching to reduce ambiguity. Uses greedy matching strategy to return a single
+        result instead of exploring all possible interpretations.
+
+        MATCHING SCENARIOS (how this method handles different cases):
+
+        Scenario A: All variables known, path matches
+            Template: "{inputs}/{file_name}"
+            Known: {"inputs": "inputs", "file_name": "photo.jpg"}
+            Path: "inputs/photo.jpg"
+            Result: {"inputs": "inputs", "file_name": "photo.jpg"}
+            Flow: Step 1 → fully resolved → Step 2 → exact match → return result
+
+        Scenario B: All variables known, path doesn't match
+            Template: "{inputs}/{file_name}"
+            Known: {"inputs": "inputs", "file_name": "photo.jpg"}
+            Path: "outputs/photo.jpg"
+            Result: None
+            Flow: Step 1 → fully resolved → Step 2 → no match → return None
+
+        Scenario C: Some variables known, path matches
+            Template: "{inputs}/{workflow_name}/{file_name}"
+            Known: {"inputs": "inputs"}
+            Path: "inputs/my_workflow/photo.jpg"
+            Result: {"inputs": "inputs", "workflow_name": "my_workflow", "file_name": "photo.jpg"}
+            Flow: Step 1 → partial resolve → Step 2 skipped → Step 3 → static validated
+                  → Step 4 → extract unknowns (workflow_name, file_name) → merge with knowns → return
+
+        Scenario D: Some variables known, known variable value doesn't match path
+            Template: "{inputs}/{workflow_name}/{file_name}"
+            Known: {"inputs": "outputs"}
+            Path: "inputs/my_workflow/photo.jpg"
+            Result: None
+            Flow: Step 1 → partial resolve → Step 2 skipped → Step 3 → static mismatch → return None
+
+        Scenario E: Optional variable present in path
+            Template: "{inputs}/{workflow_name?:_}{file_name}"
+            Known: {"inputs": "inputs"}
+            Path: "inputs/my_workflow_photo.jpg"
+            Result: {"inputs": "inputs", "workflow_name": "my_workflow", "file_name": "photo.jpg"}
+            Flow: Step 1 → partial resolve → Step 2 skipped → Step 3 → validated
+                  → Step 4 → extract with separator matching → return
+
+        Scenario F: Optional variable omitted from path
+            Template: "{inputs}/{workflow_name?:_}{file_name}"
+            Known: {"inputs": "inputs"}
+            Path: "inputs/photo.jpg"
+            Result: {"inputs": "inputs", "file_name": "photo.jpg"}
+            Flow: Step 1 → partial resolve (optional removed) → Step 2 skipped → Step 3 → validated
+                  → Step 4 → extract file_name only → return
+
+        Scenario G: Multiple unknowns with delimiters
+            Template: "{inputs}/{dir}/{file_name}.{ext}"
+            Known: {"inputs": "inputs"}
+            Path: "inputs/render/output.png"
+            Result: {"inputs": "inputs", "dir": "render", "file_name": "output", "ext": "png"}
+            Flow: Step 1 → partial resolve → Step 2 skipped → Step 3 → validated
+                  → Step 4 → extract dir, file_name, ext using "/" and "." delimiters → return
+
+        Scenario H: Format spec reversal (numeric padding)
+            Template: "{inputs}/{frame:03}.png"
+            Known: {"inputs": "inputs"}
+            Path: "inputs/005.png"
+            Result: {"inputs": "inputs", "frame": 5}  # Note: integer value
+            Flow: Step 1 → partial resolve → Step 2 skipped → Step 3 → validated
+                  → Step 4 → extract "005", reverse format spec → 5 → return
+
+        Args:
+            path: Actual path string to match against template
+            known_variables: Dictionary of variables with known values. These will be
+                            resolved before matching to reduce ambiguity. Pass empty
+                            dict {} if no variables are known.
+            secrets_manager: SecretsManager instance for resolving env vars in known variables
+
+        Returns:
+            Dictionary mapping VariableInfo to extracted values, or None if path doesn't
+            match the template pattern. Uses greedy matching to return a single result.
+        """
+        # STEP 1: Partial resolve - resolve known variables into static text
+        # This reduces the matching problem from "match everything" to "match only the unknowns"
+        #
+        # Scenarios affected:
+        # - All scenarios: always runs first
+        # - Scenarios A, B: will be fully resolved (all variables known)
+        # - Scenarios C-H: will have mix of static and unknown variables
+        # - Scenarios E, F: optional variables not in known_variables are removed
+        partial = partial_resolve(self.template, self.segments, known_variables, secrets_manager)
+
+        # STEP 2: Check if fully resolved (all variables were known)
+        # If so, we can do a direct string comparison
+        #
+        # Scenarios affected:
+        # - Scenario A: fully resolved, path matches → return result dict
+        # - Scenario B: fully resolved, path doesn't match → return None
+        # - Scenarios C-H: NOT fully resolved, skip this step
+        if partial.is_fully_resolved():
+            resolved_path = partial.to_string()
+            if resolved_path == path:
+                # Scenario A: exact match
+                result: dict[VariableInfo, str | int] = {}
+                for segment in self.segments:
+                    if isinstance(segment, ParsedVariable) and segment.info.name in known_variables:
+                        result[segment.info] = known_variables[segment.info.name]
+                return result
+            # Scenario B: no match
+            return None
+
+        # STEP 3: Extract unknown variables from path
+        # Use static segments as anchors to extract variable values between them
+        #
+        # Scenarios affected:
+        # - Scenario C: extract workflow_name="my_workflow", file_name="photo.jpg"
+        # - Scenario D: static "outputs" doesn't match "inputs/" → return None
+        # - Scenario E: extract workflow_name="my_workflow", file_name="photo.jpg" (separator matched)
+        # - Scenario F: extract file_name="photo.jpg" (optional was removed in Step 1)
+        # - Scenario G: extract dir="render", file_name="output", ext="png" (multiple delimiters)
+        # - Scenario H: extract frame="005", reverse format spec → 5
+        extracted = extract_unknown_variables(partial.segments, path)
+        if extracted is None:
+            # Extraction failed (static segments don't match or can't extract variables)
+            return None
+
+        # STEP 4: Merge extracted unknowns with known variables to create complete result
+        # The extracted dict contains only extracted unknowns, need to add knowns back in
+        #
+        # Scenarios affected (D was eliminated in Step 3):
+        # - Scenario C: merge inputs="inputs" → final: {inputs, workflow_name, file_name}
+        # - Scenario E: merge inputs="inputs" → final: {inputs, workflow_name, file_name}
+        # - Scenario F: merge inputs="inputs" → final: {inputs, file_name}
+        # - Scenario G: merge inputs="inputs" → final: {inputs, dir, file_name, ext}
+        # - Scenario H: merge inputs="inputs" → final: {inputs, frame}
+        for segment in self.segments:
+            if isinstance(segment, ParsedVariable) and segment.info.name in known_variables:
+                extracted[segment.info] = known_variables[segment.info.name]
+
+        return extracted

griptape_nodes-0.60.0/src/griptape_nodes/common/macro_parser/exceptions.py

@@ -0,0 +1,23 @@
+"""Exceptions for macro language parsing and resolution."""
+
+from __future__ import annotations
+
+
+class MacroSyntaxError(Exception):
+    """Raised when macro template has invalid syntax.
+
+    Examples of syntax errors:
+    - Unbalanced braces: "{inputs}/{file_name"
+    - Invalid format specifier: "{index:xyz}"
+    - Nested braces: "{outer_{inner}}"
+    """
+
+
+class MacroResolutionError(Exception):
+    """Raised when macro cannot be resolved with provided variables.
+
+    Examples of resolution errors:
+    - Required variable missing from variables dict
+    - Environment variable referenced but not found in environment
+    - Format specifier cannot be applied to value type (e.g., :03 on string)
+    """

griptape_nodes-0.60.0/src/griptape_nodes/common/macro_parser/formats.py

@@ -0,0 +1,170 @@
+"""Format specifier classes for macro variable transformations."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from griptape_nodes.common.macro_parser.exceptions import MacroResolutionError
+
+
+@dataclass
+class FormatSpec(ABC):
+    """Base class for format specifiers."""
+
+    @abstractmethod
+    def apply(self, value: str | int) -> str | int:
+        """Apply this format spec to a value during resolution.
+
+        Args:
+            value: Value to transform
+
+        Returns:
+            Transformed value
+
+        Raises:
+            MacroResolutionError: If format cannot be applied to value type
+
+        Examples:
+            >>> # NumericPaddingFormat(width=3).apply(5)
+            "005"
+            >>> # LowerCaseFormat().apply("MyWorkflow")
+            "myworkflow"
+        """
+
+    @abstractmethod
+    def reverse(self, value: str) -> str | int:
+        """Reverse this format spec during matching (best effort).
+
+        Args:
+            value: Formatted string value from a path
+
+        Returns:
+            Original value before format was applied
+
+        Raises:
+            MacroResolutionError: If value cannot be reversed
+
+        Examples:
+            >>> # NumericPaddingFormat(width=3).reverse("005")
+            5
+            >>> # SeparatorFormat(separator="_").reverse("workflow_")
+            "workflow"
+        """
+
+
+@dataclass
+class SeparatorFormat(FormatSpec):
+    """Separator appended to variable value like :_, :/, :foo.
+
+    Must be first format spec in list (if present).
+    Syntax: {var:_} or {var:'lower'} (quotes to disambiguate from transformations)
+    """
+
+    separator: str  # e.g., "_", "/", "foo"
+
+    def apply(self, value: str | int) -> str:
+        """Append separator to value."""
+        return str(value) + self.separator
+
+    def reverse(self, value: str) -> str:
+        """Remove separator from end of value."""
+        if value.endswith(self.separator):
+            return value[: -len(self.separator)]
+        return value
+
+
+@dataclass
+class NumericPaddingFormat(FormatSpec):
+    """Numeric padding format like :03, :04."""
+
+    width: int  # e.g., 3 for :03
+
+    def apply(self, value: str | int) -> str:
+        """Apply numeric padding: 5 → "005"."""
+        if not isinstance(value, int):
+            if not str(value).isdigit():
+                msg = (
+                    f"Numeric padding format :{self.width:0{self.width}d} "
+                    f"cannot be applied to non-numeric value: {value}"
+                )
+                raise MacroResolutionError(msg)
+            value = int(value)
+        return f"{value:0{self.width}d}"
+
+    def reverse(self, value: str) -> int:
+        """Reverse numeric padding: "005" → 5."""
+        try:
+            return int(value)
+        except ValueError as e:
+            msg = f"Cannot parse '{value}' as integer"
+            raise MacroResolutionError(msg) from e
+
+
+@dataclass
+class LowerCaseFormat(FormatSpec):
+    """Lowercase transformation :lower."""
+
+    def apply(self, value: str | int) -> str:
+        """Convert value to lowercase."""
+        return str(value).lower()
+
+    def reverse(self, value: str) -> str:
+        """Cannot reliably reverse case - return as-is."""
+        return value
+
+
+@dataclass
+class UpperCaseFormat(FormatSpec):
+    """Uppercase transformation :upper."""
+
+    def apply(self, value: str | int) -> str:
+        """Convert value to uppercase."""
+        return str(value).upper()
+
+    def reverse(self, value: str) -> str:
+        """Cannot reliably reverse case - return as-is."""
+        return value
+
+
+@dataclass
+class SlugFormat(FormatSpec):
+    """Slugification format :slug (spaces to hyphens, safe chars only)."""
+
+    def apply(self, value: str | int) -> str:
+        """Convert to slug: spaces→hyphens, lowercase, safe chars."""
+        s = str(value).lower()
+        s = re.sub(r"\s+", "-", s)  # Spaces to hyphens
+        s = re.sub(r"[^a-z0-9\-_]", "", s)  # Keep only safe chars
+        return s
+
+    def reverse(self, value: str) -> str:
+        """Cannot reliably reverse slugification - return as-is."""
+        return value
+
+
+@dataclass
+class DateFormat(FormatSpec):
+    """Date formatting like :%Y-%m-%d."""
+
+    pattern: str  # e.g., "%Y-%m-%d"
+
+    def apply(self, _value: str | int) -> str:
+        """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)
+
+    def reverse(self, value: str) -> str:
+        """Attempt to parse date string."""
+        # TODO(https://github.com/griptape-ai/griptape-nodes/issues/2717): Implement date parsing
+        return value
+
+
+# Module-level registry of known format transformations
+FORMAT_REGISTRY: dict[str, FormatSpec] = {
+    "lower": LowerCaseFormat(),
+    "upper": UpperCaseFormat(),
+    "slug": SlugFormat(),
+}

griptape_nodes-0.60.0/src/griptape_nodes/common/macro_parser/matching.py

@@ -0,0 +1,134 @@
+"""Matching logic for extracting variables from paths."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from griptape_nodes.common.macro_parser.exceptions import MacroSyntaxError
+from griptape_nodes.common.macro_parser.segments import (
+    ParsedSegment,
+    ParsedStaticValue,
+    ParsedVariable,
+    VariableInfo,
+)
+
+if TYPE_CHECKING:
+    from griptape_nodes.common.macro_parser.formats import FormatSpec
+
+
+def extract_unknown_variables(
+    pattern_segments: list[ParsedSegment],
+    path: str,
+) -> dict[VariableInfo, str | int] | None:
+    """Extract unknown variable values from path (greedy matching).
+
+    Args:
+        pattern_segments: Partially resolved segments to match against
+        path: Path string to extract variables from
+
+    Returns:
+        Dict mapping VariableInfo to extracted values, or None if no match.
+    """
+    current_match: dict[VariableInfo, str | int] = {}
+    current_pos = 0
+
+    for i, segment in enumerate(pattern_segments):
+        match segment:
+            case ParsedStaticValue():
+                # Verify static text matches at current position
+                if not path[current_pos:].startswith(segment.text):
+                    # Static text doesn't match at this position
+                    return None
+                current_pos += len(segment.text)
+            case ParsedVariable():
+                result = extract_single_variable(segment, pattern_segments[i + 1 :], path, current_pos)
+                if result is None:
+                    return None
+                value, new_pos = result
+                current_match[segment.info] = value
+                current_pos = new_pos
+            case _:
+                msg = f"Unexpected segment type: {type(segment).__name__}"
+                raise MacroSyntaxError(msg)
+
+    return current_match
+
+
+def extract_single_variable(
+    variable: ParsedVariable,
+    remaining_segments: list[ParsedSegment],
+    path: str,
+    start_pos: int,
+) -> tuple[str | int, int] | None:
+    """Extract value for a single variable from path.
+
+    Args:
+        variable: The variable to extract
+        remaining_segments: Segments after this variable
+        path: Full path being matched
+        start_pos: Position in path to start extraction
+
+    Returns:
+        Tuple of (extracted_value, new_position) or None if extraction fails.
+    """
+    # Find next static segment to determine end position
+    next_static = find_next_static(remaining_segments)
+    if next_static:
+        end_pos = path.find(next_static.text, start_pos)
+        if end_pos == -1:
+            # Can't find next static - no match
+            return None
+    else:
+        # No more static segments - consume to end
+        end_pos = len(path)
+
+    # Extract raw value
+    raw_value = path[start_pos:end_pos]
+
+    # Reverse format specs
+    reversed_value = reverse_format_specs(raw_value, variable.format_specs)
+    if reversed_value is None:
+        # Can't reverse format specs - no match
+        return None
+
+    return (reversed_value, end_pos)
+
+
+def find_next_static(segments: list[ParsedSegment]) -> ParsedStaticValue | None:
+    """Find next static segment in list.
+
+    Args:
+        segments: List of segments to search
+
+    Returns:
+        First ParsedStaticValue found, or None if no static segments.
+    """
+    for seg in segments:
+        if isinstance(seg, ParsedStaticValue):
+            return seg
+    # No static segment found
+    return None
+
+
+def reverse_format_specs(value: str, format_specs: list[FormatSpec]) -> str | int | None:
+    """Apply format spec reversal in reverse order.
+
+    Args:
+        value: String value extracted from path
+        format_specs: List of format specs to reverse
+
+    Returns:
+        Reversed value (might be int after NumericPaddingFormat.reverse), or None if reversal fails.
+    """
+    result: str | int = value
+    # Apply in reverse order (last spec first)
+    for spec in reversed(format_specs):
+        # reverse() expects str but result might be int, so convert if needed
+        str_result = str(result) if isinstance(result, int) else result
+        reversed_result = spec.reverse(str_result)
+        if reversed_result is None:
+            # Can't reverse this format spec
+            return None
+        result = reversed_result
+    # Return reversed value (might be int after NumericPaddingFormat.reverse)
+    return result