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

griptape_nodes/common/project_templates/directory.py

@@ -0,0 +1,67 @@
+"""Directory definition for logical project directories."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field, ValidationError
+
+if TYPE_CHECKING:
+    from griptape_nodes.common.project_templates.loader import YAMLLineInfo
+    from griptape_nodes.common.project_templates.validation import ProjectValidationInfo
+
+
+class DirectoryDefinition(BaseModel):
+    """Definition of a logical directory in the project."""
+
+    name: str = Field(description="Logical name (e.g., 'inputs', 'outputs')")
+    path_macro: str = Field(description="Path string (may contain macros/env vars)")
+
+    @staticmethod
+    def merge(
+        base: DirectoryDefinition,
+        overlay_data: dict[str, Any],
+        field_path: str,
+        validation_info: ProjectValidationInfo,
+        line_info: YAMLLineInfo,
+    ) -> DirectoryDefinition:
+        """Merge overlay fields onto base directory.
+
+        Field-level merge behavior:
+        - path_macro: Use overlay if present, else base
+
+        Args:
+            base: Complete base directory
+            overlay_data: Partial directory dict from overlay
+            field_path: Path for validation errors (e.g., "directories.inputs")
+            validation_info: Shared validation info
+            line_info: Line tracking from overlay
+
+        Returns:
+            New merged DirectoryDefinition
+        """
+        # Start with base fields
+        merged_data = {"name": base.name, "path_macro": base.path_macro}
+
+        # Apply overlay if present
+        if "path_macro" in overlay_data:
+            merged_data["path_macro"] = overlay_data["path_macro"]
+
+        try:
+            return DirectoryDefinition.model_validate(merged_data)
+        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/loader.py

@@ -0,0 +1,342 @@
+"""YAML loading with line number tracking for project templates.
+
+Note: This module only handles YAML parsing. File I/O operations should be
+handled by ProjectManager using ReadFileRequest/WriteFileRequest to ensure
+proper long path handling on Windows and consistent error handling.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+from pydantic import ValidationError
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+from ruamel.yaml.error import YAMLError
+
+if TYPE_CHECKING:
+    from griptape_nodes.common.project_templates.project import ProjectTemplate
+    from griptape_nodes.common.project_templates.validation import ProjectValidationInfo
+
+# Field name constants
+FIELD_NAME = "name"
+FIELD_SITUATIONS = "situations"
+FIELD_DIRECTORIES = "directories"
+FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION = "project_template_schema_version"
+FIELD_ENVIRONMENT = "environment"
+FIELD_DESCRIPTION = "description"
+
+# Special constants
+ROOT_FIELD_PATH = "<root>"
+DEFAULT_SCHEMA_VERSION = "0.1.0"
+DEFAULT_PROJECT_NAME = "Invalid Project"
+
+
+@dataclass
+class YAMLLineInfo:
+    """Line number information for YAML fields."""
+
+    field_path_to_line: dict[str, int] = field(default_factory=dict)
+
+    def get_line(self, field_path: str) -> int | None:
+        """Get line number for a field path, returns None if not tracked."""
+        return self.field_path_to_line.get(field_path)
+
+    def add_mapping(self, field_path: str, line_number: int) -> None:
+        """Add a field path to line number mapping."""
+        self.field_path_to_line[field_path] = line_number
+
+
+class YAMLParseResult(NamedTuple):
+    """Result of parsing YAML with line tracking.
+
+    Contains the parsed YAML data and line number tracking information.
+    """
+
+    data: dict[str, Any]
+    line_info: YAMLLineInfo
+
+
+class ProjectOverlayData(NamedTuple):
+    """Partially validated project template data for merging.
+
+    Contains raw dicts for situations/directories with basic structural validation.
+    Line tracking preserved for error reporting during merge.
+    Used as overlay input to ProjectTemplate.merge().
+    """
+
+    name: str
+    project_template_schema_version: str
+    situations: dict[str, dict[str, Any]]  # situation_name -> raw dict
+    directories: dict[str, dict[str, Any]]  # directory_name -> raw dict
+    environment: dict[str, str]
+    description: str | None
+    line_info: YAMLLineInfo
+
+
+def load_yaml_with_line_tracking(yaml_text: str) -> YAMLParseResult:
+    """Load YAML preserving line numbers and comments.
+
+    Uses ruamel.yaml to parse while tracking line numbers for each field.
+
+    Returns:
+        - Parsed YAML data as dict
+        - Line number tracking info
+
+    Raises:
+        YAMLError: If YAML syntax is invalid (unclosed quotes, invalid structure, etc.)
+    """
+    yaml = YAML()
+    yaml.preserve_quotes = True
+    yaml.default_flow_style = False
+
+    # Parse YAML with line tracking
+    # ruamel.yaml returns CommentedMap/CommentedSeq objects with line info
+    data = yaml.load(yaml_text)
+
+    if not isinstance(data, dict):
+        msg = f"Expected YAML root to be a mapping (dict), got {type(data).__name__}"
+        raise YAMLError(msg)
+
+    # Build line number mapping
+    line_info = YAMLLineInfo()
+
+    def track_lines(obj: CommentedMap | CommentedSeq, path: str) -> None:
+        """Recursively track line numbers for YAML objects.
+
+        Args:
+            obj: CommentedMap or CommentedSeq from ruamel.yaml (has lc attribute)
+            path: Current field path for tracking
+
+        Note: Only CommentedMap/CommentedSeq objects have line tracking.
+        Plain dicts/lists and scalars don't have lc attributes.
+        """
+        # Track line number for this object
+        line = obj.lc.line + 1  # Convert to 1-indexed
+        line_info.add_mapping(path, line)
+
+        # Recurse into children
+        if isinstance(obj, CommentedMap):
+            for key, value in obj.items():
+                child_path = f"{path}.{key}" if path else key
+                if isinstance(value, CommentedMap | CommentedSeq):
+                    track_lines(value, child_path)
+        elif isinstance(obj, CommentedSeq):
+            for i, item in enumerate(obj):
+                child_path = f"{path}[{i}]"
+                if isinstance(item, CommentedMap | CommentedSeq):
+                    track_lines(item, child_path)
+
+    # At runtime, data is a CommentedMap from ruamel.yaml
+    if isinstance(data, CommentedMap):
+        track_lines(data, "")
+
+    return YAMLParseResult(data=data, line_info=line_info)
+
+
+def load_project_template_from_yaml(  # noqa: C901
+    yaml_text: str,
+    validation_info: ProjectValidationInfo,
+) -> ProjectTemplate | None:
+    """Parse project.yml text into ProjectTemplate.
+
+    Two-pass approach:
+    1. Load raw YAML with line tracking (may raise YAMLError)
+    2. Build ProjectTemplate via Pydantic validation, collecting validation problems
+
+    Args:
+        yaml_text: YAML text to parse
+        validation_info: Validation info to populate (caller-owned, will be mutated)
+
+    Returns:
+        ProjectTemplate on success, None if fatal errors prevent construction
+    """
+    # Lazy import required: circular dependency between this module and project.py
+    # project.py imports ProjectOverlayData from this file, and we need ProjectTemplate from project.py
+    from griptape_nodes.common.project_templates.project import ProjectTemplate
+
+    # Pass 1: Load YAML with line tracking
+    try:
+        result = load_yaml_with_line_tracking(yaml_text)
+    except YAMLError as e:
+        # YAML syntax error - cannot proceed
+        validation_info.add_error(
+            field_path=ROOT_FIELD_PATH,
+            message=f"YAML syntax error: {e}",
+            line_number=None,
+        )
+        return None
+
+    # Pass 2: Build ProjectTemplate with Pydantic validation
+    data = result.data
+    line_info = result.line_info
+
+    # Add names to situations and directories before validation
+    if FIELD_SITUATIONS in data and isinstance(data[FIELD_SITUATIONS], dict):
+        for sit_name, sit_data in data[FIELD_SITUATIONS].items():
+            if isinstance(sit_data, dict):
+                sit_data[FIELD_NAME] = sit_name
+
+    if FIELD_DIRECTORIES in data and isinstance(data[FIELD_DIRECTORIES], dict):
+        for dir_name, dir_data in data[FIELD_DIRECTORIES].items():
+            if isinstance(dir_data, dict):
+                dir_data[FIELD_NAME] = dir_name
+
+    try:
+        template = ProjectTemplate.model_validate(data)
+    except ValidationError as e:
+        # Convert Pydantic validation errors to our validation_info format
+        for error in e.errors():
+            # Build field path from error location
+            field_path = ".".join(str(loc) for loc in error["loc"])
+            message = error["msg"]
+
+            # Try to get line number from our line tracking
+            line_number = line_info.get_line(field_path)
+
+            validation_info.add_error(
+                field_path=field_path,
+                message=message,
+                line_number=line_number,
+            )
+
+        return None
+    else:
+        # Add warnings for schema version mismatches
+        if template.project_template_schema_version != ProjectTemplate.LATEST_SCHEMA_VERSION:
+            message = (
+                f"Schema version '{template.project_template_schema_version}' "
+                f"differs from latest '{ProjectTemplate.LATEST_SCHEMA_VERSION}'"
+            )
+            validation_info.add_warning(
+                field_path=FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION,
+                message=message,
+                line_number=line_info.get_line(FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION),
+            )
+
+        return template
+
+
+def load_partial_project_template(
+    yaml_text: str,
+    validation_info: ProjectValidationInfo,
+) -> ProjectOverlayData | None:
+    """Load project template overlay for merging without full construction.
+
+    Performs minimal structural validation:
+    - YAML syntax
+    - Required top-level fields (name, project_template_schema_version)
+    - Basic type checking (situations is dict, directories is dict, etc.)
+
+    Does NOT:
+    - Construct full SituationTemplate/DirectoryDefinition objects
+    - Validate situation macros or policy values
+    - Check directory references
+
+    Use this for loading user overlay templates before merge.
+    After merge, full validation happens during object construction.
+
+    Args:
+        yaml_text: YAML text to parse
+        validation_info: Validation info to populate (caller-owned, will be mutated)
+
+    Returns:
+        ProjectOverlayData on success, None if fatal errors prevent construction
+    """
+    # Parse YAML with line tracking
+    try:
+        result = load_yaml_with_line_tracking(yaml_text)
+        data = result.data
+        line_info = result.line_info
+    except YAMLError as e:
+        validation_info.add_error(
+            field_path=ROOT_FIELD_PATH,
+            message=f"YAML syntax error: {e}",
+            line_number=None,
+        )
+        return None
+
+    # Validate required field: name
+    name = data.get(FIELD_NAME)
+    if name is None:
+        validation_info.add_error(
+            field_path=FIELD_NAME,
+            message=f"Required field '{FIELD_NAME}' missing",
+            line_number=line_info.get_line(FIELD_NAME),
+        )
+        name = DEFAULT_PROJECT_NAME
+    elif not isinstance(name, str):
+        validation_info.add_error(
+            field_path=FIELD_NAME,
+            message=f"Field '{FIELD_NAME}' must be string, got {type(name).__name__}",
+            line_number=line_info.get_line(FIELD_NAME),
+        )
+        name = DEFAULT_PROJECT_NAME
+
+    # Validate required field: project_template_schema_version
+    schema_version = data.get(FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION)
+    if schema_version is None:
+        validation_info.add_error(
+            field_path=FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION,
+            message=f"Required field '{FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION}' missing",
+            line_number=line_info.get_line(FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION),
+        )
+        schema_version = DEFAULT_SCHEMA_VERSION
+    elif not isinstance(schema_version, str):
+        validation_info.add_error(
+            field_path=FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION,
+            message=f"Must be string, got {type(schema_version).__name__}",
+            line_number=line_info.get_line(FIELD_PROJECT_TEMPLATE_SCHEMA_VERSION),
+        )
+        schema_version = DEFAULT_SCHEMA_VERSION
+
+    # Optional field: situations (default to empty dict)
+    situations = data.get(FIELD_SITUATIONS, {})
+    if not isinstance(situations, dict):
+        validation_info.add_error(
+            field_path=FIELD_SITUATIONS,
+            message=f"Must be dict, got {type(situations).__name__}",
+            line_number=line_info.get_line(FIELD_SITUATIONS),
+        )
+        situations = {}
+
+    # Optional field: directories (default to empty dict)
+    directories = data.get(FIELD_DIRECTORIES, {})
+    if not isinstance(directories, dict):
+        validation_info.add_error(
+            field_path=FIELD_DIRECTORIES,
+            message=f"Must be dict, got {type(directories).__name__}",
+            line_number=line_info.get_line(FIELD_DIRECTORIES),
+        )
+        directories = {}
+
+    # Optional field: environment (default to empty dict)
+    environment = data.get(FIELD_ENVIRONMENT, {})
+    if not isinstance(environment, dict):
+        validation_info.add_error(
+            field_path=FIELD_ENVIRONMENT,
+            message=f"Must be dict, got {type(environment).__name__}",
+            line_number=line_info.get_line(FIELD_ENVIRONMENT),
+        )
+        environment = {}
+
+    # Optional field: description
+    description = data.get(FIELD_DESCRIPTION)
+    if description is not None and not isinstance(description, str):
+        validation_info.add_error(
+            field_path=FIELD_DESCRIPTION,
+            message=f"Must be string, got {type(description).__name__}",
+            line_number=line_info.get_line(FIELD_DESCRIPTION),
+        )
+        description = None
+
+    return ProjectOverlayData(
+        name=name,
+        project_template_schema_version=schema_version,
+        situations=situations,
+        directories=directories,
+        environment=environment,
+        description=description,
+        line_info=line_info,
+    )

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,
+        )