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

griptape_nodes/retained_mode/events/project_events.py

@@ -1,12 +1,11 @@
 """Events for project template management."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 from enum import StrEnum
-from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from griptape_nodes.common.macro_parser import MacroMatchFailure, MacroParseFailure, VariableInfo
-from griptape_nodes.common.project_templates import ProjectTemplate, ProjectValidationInfo
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
     ResultPayloadFailure,
@@ -15,6 +14,13 @@ from griptape_nodes.retained_mode.events.base_events import (
 )
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from griptape_nodes.common.macro_parser import MacroMatchFailure, ParsedMacro, VariableInfo
+    from griptape_nodes.common.project_templates import ProjectTemplate, ProjectValidationInfo, SituationTemplate
+    from griptape_nodes.retained_mode.managers.project_manager import ProjectID, ProjectInfo
+
 # Type alias for macro variable dictionaries (used by ParsedMacro)
 MacroVariables = dict[str, str | int]
 
@@ -49,12 +55,12 @@ class LoadProjectTemplateResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuc
     """Project template loaded successfully.
 
     Args:
-        project_path: Path to the loaded project.yml
+        project_id: The identifier for the loaded project
         template: The merged ProjectTemplate (system defaults + user customizations)
         validation: Validation info with status and any problems encountered
     """
 
-    project_path: Path
+    project_id: ProjectID
     template: ProjectTemplate
     validation: ProjectValidationInfo
 
@@ -65,28 +71,26 @@ class LoadProjectTemplateResultFailure(WorkflowNotAlteredMixin, ResultPayloadFai
     """Project template loading failed.
 
     Args:
-        project_path: Path to the project.yml that failed to load
         validation: Validation info with error details
     """
 
-    project_path: Path
     validation: ProjectValidationInfo
 
 
 @dataclass
 @PayloadRegistry.register
 class GetProjectTemplateRequest(RequestPayload):
-    """Get cached project template for a workspace path.
+    """Get cached project template for a project ID.
 
     Use when: Querying current project configuration, checking validation status.
 
     Args:
-        project_path: Path to the project.yml file
+        project_id: Identifier of the project
 
     Results: GetProjectTemplateResultSuccess | GetProjectTemplateResultFailure
     """
 
-    project_path: Path
+    project_id: ProjectID
 
 
 @dataclass
@@ -109,40 +113,80 @@ class GetProjectTemplateResultFailure(WorkflowNotAlteredMixin, ResultPayloadFail
     """Project template retrieval failed (not loaded yet)."""
 
 
+@dataclass
+class ProjectTemplateInfo:
+    """Information about a loaded or failed project template."""
+
+    project_id: ProjectID
+    validation: ProjectValidationInfo
+
+
+@dataclass
+@PayloadRegistry.register
+class ListProjectTemplatesRequest(RequestPayload):
+    """List all project templates that have been loaded or attempted to load.
+
+    Use when: Displaying available projects, checking which projects are loaded.
+
+    Args:
+        include_system_builtins: Whether to include system builtin templates like SYSTEM_DEFAULTS_KEY
+
+    Results: ListProjectTemplatesResultSuccess
+    """
+
+    include_system_builtins: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class ListProjectTemplatesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """List of all project templates retrieved.
+
+    Args:
+        successfully_loaded: List of templates that loaded successfully
+        failed_to_load: List of templates that failed to load with validation errors
+    """
+
+    successfully_loaded: list[ProjectTemplateInfo]
+    failed_to_load: list[ProjectTemplateInfo]
+
+
 @dataclass
 @PayloadRegistry.register
-class GetMacroForSituationRequest(RequestPayload):
-    """Get the macro schema for a specific situation.
+class GetSituationRequest(RequestPayload):
+    """Get the full situation template for a specific situation.
+
+    Returns the complete SituationTemplate including macro and policy.
 
-    Use when: Need to know what variables a situation requires, or get schema for custom resolution.
+    Use when: Need situation macro and/or policy for file operations.
+    Uses the current project for context.
 
     Args:
-        project_path: Path to the project.yml to use
         situation_name: Name of the situation template (e.g., "save_node_output")
 
-    Results: GetMacroForSituationResultSuccess | GetMacroForSituationResultFailure
+    Results: GetSituationResultSuccess | GetSituationResultFailure
     """
 
-    project_path: Path
     situation_name: str
 
 
 @dataclass
 @PayloadRegistry.register
-class GetMacroForSituationResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    """Situation macro retrieved successfully.
+class GetSituationResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Situation template retrieved successfully.
 
     Args:
-        macro_schema: The macro template string (e.g., "{inputs}/{file_name}.{file_ext}")
+        situation: The complete situation template including macro and policy.
+                  Access via situation.macro, situation.policy.create_dirs, etc.
     """
 
-    macro_schema: str
+    situation: SituationTemplate
 
 
 @dataclass
 @PayloadRegistry.register
-class GetMacroForSituationResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """Situation macro retrieval failed (situation not found or template not loaded)."""
+class GetSituationResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Situation template retrieval failed (situation not found or template not loaded)."""
 
 
 @dataclass
@@ -152,16 +196,17 @@ class GetPathForMacroRequest(RequestPayload):
 
     Use when: Resolving paths, saving files. Works with any macro string, not tied to situations.
 
+    Uses the current project for context. Caller must parse the macro string
+    into a ParsedMacro before creating this request.
+
     Args:
-        project_path: Path to the project.yml (used for directory resolution)
-        macro_schema: The macro template string to resolve (e.g., "{inputs}/{file_name}.{file_ext}")
+        parsed_macro: The parsed macro to resolve
         variables: Variable values for macro substitution (e.g., {"file_name": "output", "file_ext": "png"})
 
     Results: GetPathForMacroResultSuccess | GetPathForMacroResultFailure
     """
 
-    project_path: Path
-    macro_schema: str
+    parsed_macro: ParsedMacro
     variables: MacroVariables
 
 
@@ -171,10 +216,12 @@ class GetPathForMacroResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess
     """Path resolved successfully from macro.
 
     Args:
-        resolved_path: The final Path after macro substitution
+        resolved_path: The relative project path after macro substitution (e.g., "outputs/file.png")
+        absolute_path: The absolute filesystem path (e.g., "/workspace/outputs/file.png")
     """
 
     resolved_path: Path
+    absolute_path: Path
 
 
 @dataclass
@@ -186,29 +233,27 @@ class GetPathForMacroResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure
         failure_reason: Specific reason for failure
         missing_variables: List of required variable names that were not provided (for MISSING_REQUIRED_VARIABLES)
         conflicting_variables: List of variables that conflict with directory names (for DIRECTORY_OVERRIDE_ATTEMPTED)
-        error_details: Additional error details from ParsedMacro (for MACRO_RESOLUTION_ERROR)
     """
 
     failure_reason: PathResolutionFailureReason
-    missing_variables: list[str] | None = None
-    conflicting_variables: list[str] | None = None
-    error_details: str | None = None
+    missing_variables: set[str] | None = None
+    conflicting_variables: set[str] | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class SetCurrentProjectRequest(RequestPayload):
-    """Set which project.yml user has currently selected.
+    """Set which project user has currently selected.
 
     Use when: User switches between projects, opens a new workspace.
 
     Args:
-        project_path: Path to the project.yml to set as current (None to clear)
+        project_id: Identifier of the project to set as current (None to clear)
 
     Results: SetCurrentProjectResultSuccess
     """
 
-    project_path: Path | None
+    project_id: ProjectID | None
 
 
 @dataclass
@@ -224,7 +269,7 @@ class GetCurrentProjectRequest(RequestPayload):
 
     Use when: Need to know which project user is working with.
 
-    Results: GetCurrentProjectResultSuccess
+    Results: GetCurrentProjectResultSuccess | GetCurrentProjectResultFailure
     """
 
 
@@ -234,10 +279,16 @@ class GetCurrentProjectResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSucce
     """Current project retrieved.
 
     Args:
-        project_path: The currently selected project path ("No Project" if None)
+        project_info: Complete information about the current project
     """
 
-    project_path: Path | None
+    project_info: ProjectInfo
+
+
+@dataclass
+@PayloadRegistry.register
+class GetCurrentProjectResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """No current project is set."""
 
 
 @dataclass
@@ -261,13 +312,7 @@ class SaveProjectTemplateRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class SaveProjectTemplateResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    """Project template saved successfully.
-
-    Args:
-        project_path: Path where project.yml was saved
-    """
-
-    project_path: Path
+    """Project template saved successfully."""
 
 
 @dataclass
@@ -281,122 +326,192 @@ class SaveProjectTemplateResultFailure(WorkflowNotAlteredMixin, ResultPayloadFai
     - Disk full
     """
 
-    project_path: Path
-
 
 @dataclass
 @PayloadRegistry.register
-class MatchPathAgainstMacroRequest(RequestPayload):
-    """Check if a path matches a macro schema and extract variables.
+class AttemptMatchPathAgainstMacroRequest(RequestPayload):
+    """Attempt to match a path against a macro schema and extract variables.
 
     Use when: Validating paths, extracting info from file paths,
     identifying which schema produced a file.
 
+    Uses the current project for context. Caller must parse the macro string
+    into a ParsedMacro before creating this request.
+
+    Pattern non-matches are returned as success with match_failure populated.
+    Only true system errors (missing SecretsManager, etc.) return failure.
+
     Args:
-        project_path: Path to project.yml (for directory resolution)
-        macro_schema: Macro template string
-        file_path: Path to test
+        parsed_macro: Parsed macro template to match against
+        file_path: Path string to test
         known_variables: Variables we already know
 
-    Results: MatchPathAgainstMacroResultSuccess | MatchPathAgainstMacroResultFailure
+    Results: AttemptMatchPathAgainstMacroResultSuccess | AttemptMatchPathAgainstMacroResultFailure
     """
 
-    project_path: Path
-    macro_schema: str
+    parsed_macro: ParsedMacro
     file_path: str
     known_variables: MacroVariables
 
 
 @dataclass
 @PayloadRegistry.register
-class MatchPathAgainstMacroResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    """Path matched the macro schema."""
+class AttemptMatchPathAgainstMacroResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Attempt completed (match succeeded or pattern didn't match).
 
-    extracted_variables: MacroVariables
+    Check match_failure to determine outcome:
+    - match_failure is None: Pattern matched, extracted_variables contains results
+    - match_failure is not None: Pattern didn't match (normal case, not an error)
+    """
+
+    extracted_variables: MacroVariables | None
+    match_failure: MacroMatchFailure | None
 
 
 @dataclass
 @PayloadRegistry.register
-class MatchPathAgainstMacroResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """Path did not match the macro schema."""
-
-    match_failure: MacroMatchFailure
+class AttemptMatchPathAgainstMacroResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """System error occurred (missing SecretsManager, invalid configuration, etc.)."""
 
 
 @dataclass
 @PayloadRegistry.register
-class GetVariablesForMacroRequest(RequestPayload):
-    """Get list of all variables in a macro schema.
+class GetStateForMacroRequest(RequestPayload):
+    """Analyze a macro and return comprehensive state information.
 
-    Use when: Building UI forms, showing what variables a schema needs,
-    validating before resolution.
+    Use when: Building UI forms, real-time validation, checking if resolution
+    would succeed before actually resolving.
+
+    Uses the current project for context. Caller must parse the macro string
+    into a ParsedMacro before creating this request.
 
     Args:
-        macro_schema: Macro template string to inspect
+        parsed_macro: The parsed macro to analyze
+        variables: Currently provided variable values
 
-    Results: GetVariablesForMacroResultSuccess | GetVariablesForMacroResultFailure
+    Results: GetStateForMacroResultSuccess | GetStateForMacroResultFailure
     """
 
-    macro_schema: str
+    parsed_macro: ParsedMacro
+    variables: MacroVariables
 
 
 @dataclass
 @PayloadRegistry.register
-class GetVariablesForMacroResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    """Variables found in the macro schema."""
+class GetStateForMacroResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Macro state analysis completed successfully.
+
+    Args:
+        all_variables: All variables found in the macro
+        satisfied_variables: Variables that have values (from user, directories, or builtins)
+        missing_required_variables: Required variables that are missing values
+        conflicting_variables: Variables that conflict (e.g., user overriding builtin with different value)
+        can_resolve: Whether the macro can be fully resolved (no missing required vars, no conflicts)
+    """
 
-    variables: list[VariableInfo]
+    all_variables: set[VariableInfo]
+    satisfied_variables: set[str]
+    missing_required_variables: set[str]
+    conflicting_variables: set[str]
+    can_resolve: bool
 
 
 @dataclass
 @PayloadRegistry.register
-class GetVariablesForMacroResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """Failed to parse macro schema."""
+class GetStateForMacroResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Macro state analysis failed.
 
-    parse_failure: MacroParseFailure
+    Failure occurs when:
+    - No current project is set
+    - Current project template is not loaded
+    - A builtin variable cannot be resolved (RuntimeError or NotImplementedError)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
-class ValidateMacroSyntaxRequest(RequestPayload):
-    """Validate a macro schema string for syntax errors.
+class AttemptMapAbsolutePathToProjectRequest(RequestPayload):
+    """Find out if an absolute path exists anywhere within a Project directory.
+
+    Use when: User selects or types an absolute path via FilePicker and you need to know:
+      1. Is this path inside any project directory?
+      2. If yes, what's the macro form (e.g., {outputs}/file.png)?
 
-    Use when: User editing schemas in UI, before saving templates,
-    real-time validation.
+    This enables automatic conversion of absolute paths to portable macro form for workflow portability.
+
+    Uses longest prefix matching to find the most specific directory match.
+    Returns Success with mapped_path if inside project, or Success with None if outside.
+    Returns Failure if operation cannot be performed (no project loaded, secrets unavailable).
 
     Args:
-        macro_schema: Schema string to validate
+        absolute_path: The absolute filesystem path to check
+
+    Results: AttemptMapAbsolutePathToProjectResultSuccess | AttemptMapAbsolutePathToProjectResultFailure
 
-    Results: ValidateMacroSyntaxResultSuccess | ValidateMacroSyntaxResultFailure
+    Examples:
+        Path inside project directory:
+            Request: absolute_path = /Users/james/project/outputs/renders/image.png
+            Result: mapped_path = "{outputs}/renders/image.png"
+
+        Path outside project:
+            Request: absolute_path = /Users/james/Downloads/image.png
+            Result: mapped_path = None
+
+        Path at directory root:
+            Request: absolute_path = /Users/james/project/outputs
+            Result: mapped_path = "{outputs}"
     """
 
-    macro_schema: str
+    absolute_path: Path
 
 
 @dataclass
 @PayloadRegistry.register
-class ValidateMacroSyntaxResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    """Syntax is valid."""
+class AttemptMapAbsolutePathToProjectResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Path check completed successfully.
+
+    Success means the check was performed (not necessarily that a match was found).
+    - mapped_path is NOT None: Path is inside a project directory (macro form returned)
+    - mapped_path is None: Path is outside all project directories (valid answer)
+
+    Args:
+        mapped_path: The macro form if path is inside a project directory (e.g., "{outputs}/file.png"),
+                    or None if path is outside all project directories
+
+    Examples:
+        Path inside project:
+            mapped_path = "{outputs}/renders/image.png"
+            result_details = "Successfully mapped absolute path to '{outputs}/renders/image.png'"
 
-    variables: list[VariableInfo]
-    warnings: list[str]
+        Path outside project:
+            mapped_path = None
+            result_details = "Attempted to map absolute path '/Users/james/Downloads/image.png'. Path is outside all project directories"
+    """
+
+    mapped_path: str | None
 
 
 @dataclass
 @PayloadRegistry.register
-class ValidateMacroSyntaxResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """Syntax is invalid."""
+class AttemptMapAbsolutePathToProjectResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Path mapping attempt failed.
 
-    parse_failure: MacroParseFailure
-    partial_variables: list[VariableInfo]
+    Returned when the operation cannot be performed (no current project, secrets manager unavailable).
+    This is distinct from "path is outside project" which returns Success with None values.
+
+    Examples:
+        No current project:
+            result_details = "Attempted to map absolute path. Failed because no current project is set"
+
+        Secrets manager unavailable:
+            result_details = "Attempted to map absolute path. Failed because SecretsManager not available"
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class GetAllSituationsForProjectRequest(RequestPayload):
-    """Get all situation names and schemas from a project template."""
-
-    project_path: Path
+    """Get all situation names and schemas from current project template."""
 
 
 @dataclass

griptape_nodes/retained_mode/managers/event_manager.py

@@ -98,6 +98,19 @@ class EventManager:
                 self._event_loop = None
                 self._loop_thread_id = None
 
+    def _is_cross_thread_call(self) -> bool:
+        """Check if the current call is from a different thread than the event loop.
+
+        Returns:
+            True if we're on a different thread and need thread-safe operations
+        """
+        current_thread_id = threading.get_ident()
+        return (
+            self._loop_thread_id is not None
+            and current_thread_id != self._loop_thread_id
+            and self._event_loop is not None
+        )
+
     def put_event(self, event: Any) -> None:
         """Put event into async queue from sync context (non-blocking).
 
@@ -109,15 +122,9 @@ class EventManager:
         if self._event_queue is None:
             return
 
-        # Check if we need thread-safe operation
-        current_thread_id = threading.get_ident()
-
-        if (
-            self._loop_thread_id is not None
-            and current_thread_id != self._loop_thread_id
-            and self._event_loop is not None
-        ):
+        if self._is_cross_thread_call() and self._event_loop is not None:
             # We're in a different thread from the event loop, use thread-safe method
+            # _is_cross_thread_call() guarantees _event_loop is not None
             self._event_loop.call_soon_threadsafe(self._event_queue.put_nowait, event)
         else:
             # We're on the same thread as the event loop or no loop thread tracked, use direct method
@@ -126,13 +133,21 @@ class EventManager:
     async def aput_event(self, event: Any) -> None:
         """Put event into async queue from async context.
 
+        Automatically detects if we're in a different thread and uses thread-safe operations.
+
         Args:
             event: The event to publish to the queue
         """
         if self._event_queue is None:
             return
 
-        await self._event_queue.put(event)
+        if self._is_cross_thread_call() and self._event_loop is not None:
+            # We're in a different thread from the event loop, use thread-safe method
+            # _is_cross_thread_call() guarantees _event_loop is not None
+            self._event_loop.call_soon_threadsafe(self._event_queue.put_nowait, event)
+        else:
+            # We're on the same thread as the event loop or no loop thread tracked, use async method
+            await self._event_queue.put(event)
 
     def assign_manager_to_request_type(
         self,

griptape_nodes/retained_mode/managers/library_manager.py

@@ -1639,6 +1639,13 @@ class LibraryManager:
         user_libraries_section = "app_events.on_app_initialization_complete.libraries_to_register"
         libraries_to_register: list[str] = config_mgr.get_config_value(user_libraries_section)
 
+        # Filter out empty or whitespace-only entries
+        original_count = len(libraries_to_register) if libraries_to_register else 0
+        libraries_to_register = [path for path in (libraries_to_register or []) if path and path.strip()]
+        filtered_count = original_count - len(libraries_to_register)
+        if filtered_count > 0:
+            logger.warning("Filtered out %d empty library path entries from configuration", filtered_count)
+
         if not libraries_to_register:
             logger.info("No libraries to register from config")
             return
@@ -1986,24 +1993,6 @@ class LibraryManager:
                     ret_val.append(file_path)
         return ret_val
 
-    def _load_libraries_from_config_category(self, config_category: str, *, load_as_default_library: bool) -> None:
-        config_mgr = GriptapeNodes.ConfigManager()
-        libraries_to_register_category: list[str] = config_mgr.get_config_value(config_category)
-
-        if libraries_to_register_category is not None:
-            for library_to_register in libraries_to_register_category:
-                if library_to_register:
-                    if library_to_register.endswith(".json"):
-                        library_load_request = RegisterLibraryFromFileRequest(
-                            file_path=library_to_register,
-                            load_as_default_library=load_as_default_library,
-                        )
-                    else:
-                        library_load_request = RegisterLibraryFromRequirementSpecifierRequest(
-                            requirement_specifier=library_to_register
-                        )
-                    GriptapeNodes.handle_request(library_load_request)
-
     def _remove_missing_libraries_from_config(self, config_category: str) -> None:
         # Now remove all libraries that were missing from the user's config.
         config_mgr = GriptapeNodes.ConfigManager()
@@ -2076,8 +2065,10 @@ class LibraryManager:
         # Add from config
         config_libraries = config_mgr.get_config_value(user_libraries_section, default=[])
         for library_path_str in config_libraries:
-            library_path = Path(library_path_str)
-            if library_path.exists():
-                process_path(library_path)
+            # Filter out falsy values that will resolve to current directory
+            if library_path_str:
+                library_path = Path(library_path_str)
+                if library_path.exists():
+                    process_path(library_path)
 
         return list(discovered_libraries)