griptape-nodes 0.65.6__py3-none-any.whl → 0.66.0__py3-none-any.whl

griptape_nodes/retained_mode/events/library_events.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NamedTuple
 
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
@@ -13,9 +13,23 @@ 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.node_library.library_registry import LibraryMetadata, LibrarySchema, NodeMetadata
     from griptape_nodes.retained_mode.managers.fitness_problems.libraries import LibraryProblem
-    from griptape_nodes.retained_mode.managers.library_lifecycle.library_status import LibraryStatus
+    from griptape_nodes.retained_mode.managers.library_manager import LibraryManager
+
+
+class DiscoveredLibrary(NamedTuple):
+    """Information about a discovered library.
+
+    Attributes:
+        path: Absolute path to the library JSON file or sandbox directory
+        is_sandbox: True if this is a sandbox library (user-created nodes in workspace), False for regular libraries
+    """
+
+    path: Path
+    is_sandbox: bool
 
 
 @dataclass
@@ -204,7 +218,7 @@ class LoadLibraryMetadataFromFileResultFailure(WorkflowNotAlteredMixin, ResultPa
         library_path: Path to the library file that failed to load.
         library_name: Name of the library if it could be extracted from the JSON,
                      None if the name couldn't be determined.
-        status: The LibraryStatus enum indicating the type of failure
+        status: The LibraryFitness enum indicating the type of failure
                (MISSING, UNUSABLE, etc.).
         problems: List of specific problems encountered during loading
                  (file not found, JSON parse errors, validation failures, etc.).
@@ -212,7 +226,7 @@ class LoadLibraryMetadataFromFileResultFailure(WorkflowNotAlteredMixin, ResultPa
 
     library_path: str
     library_name: str | None
-    status: LibraryStatus
+    status: LibraryManager.LibraryFitness
     problems: list[LibraryProblem]
 
 
@@ -260,22 +274,74 @@ class LoadMetadataForAllLibrariesResultFailure(WorkflowNotAlteredMixin, ResultPa
     """
 
 
+@dataclass
+@PayloadRegistry.register
+class ScanSandboxDirectoryRequest(RequestPayload):
+    """Scan sandbox directory and generate/update library metadata.
+
+    This request triggers a scan of a sandbox directory,
+    discovers Python files, and either creates a new library schema or
+    merges with an existing griptape_nodes_library.json if present.
+
+    Use when: Manually triggering sandbox refresh, testing sandbox setup,
+    forcing regeneration of sandbox library metadata.
+
+    Args:
+        directory_path: Path to sandbox directory to scan (required).
+
+    Results: ScanSandboxDirectoryResultSuccess | ScanSandboxDirectoryResultFailure
+    """
+
+    directory_path: str
+
+
+@dataclass
+@PayloadRegistry.register
+class ScanSandboxDirectoryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Sandbox directory scanned successfully.
+
+    Args:
+        library_schema: The generated or merged LibrarySchema
+    """
+
+    library_schema: LibrarySchema
+
+
+@dataclass
+@PayloadRegistry.register
+class ScanSandboxDirectoryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Sandbox directory scan failed.
+
+    Common causes: directory doesn't exist, no Python files found, internal error.
+    """
+
+
 @dataclass
 @PayloadRegistry.register
 class RegisterLibraryFromFileRequest(RequestPayload):
-    """Register a library from a JSON file.
+    """Register a library by name or path, progressing through all lifecycle phases.
+
+    This request handles the complete library loading lifecycle:
+    DISCOVERED → METADATA_LOADED → EVALUATED → DEPENDENCIES_INSTALLED → LOADED
+
+    The handler automatically creates LibraryInfo if not already tracked, making it suitable
+    for both internal use (from load_all_libraries_from_config) and external use (scripts, tests, API).
 
     Use when: Loading custom libraries, adding new node types,
     registering development libraries, extending node capabilities.
 
     Args:
-        file_path: Path to the library JSON file to register
-        load_as_default_library: Whether to load as the default library (default: False)
+        library_name: Name of library to load (must match library JSON 'name' field). Either library_name OR file_path required (not both).
+        file_path: Path to library JSON file. Either library_name OR file_path required (not both).
+        perform_discovery_if_not_found: If True and library not found, trigger discovery (default: False)
+        load_as_default_library: Whether to mark this library as the default (default: False)
 
     Results: RegisterLibraryFromFileResultSuccess (with library name) | RegisterLibraryFromFileResultFailure (load error)
     """
 
-    file_path: str
+    library_name: str | None = None
+    file_path: str | None = None
+    perform_discovery_if_not_found: bool = False
     load_as_default_library: bool = False
 
 
@@ -517,6 +583,79 @@ class ReloadAllLibrariesResultFailure(ResultPayloadFailure):
     """Library reload failed. Common causes: library loading errors, system constraints, initialization failures."""
 
 
+@dataclass
+@PayloadRegistry.register
+class DiscoverLibrariesRequest(RequestPayload):
+    """Discover all libraries from configuration.
+
+    Scans configured library paths and creates LibraryInfo entries in 'discovered' state.
+    This does not load any library contents - just identifies what's available.
+
+    Use when: Refreshing library catalog, checking for new libraries, initializing
+    library tracking before selective loading.
+
+    Results: DiscoverLibrariesResultSuccess | DiscoverLibrariesResultFailure
+    """
+
+    include_sandbox: bool = True  # Whether to include sandbox library in discovery
+
+
+@dataclass
+@PayloadRegistry.register
+class DiscoverLibrariesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Libraries discovered successfully."""
+
+    libraries_discovered: set[DiscoveredLibrary]  # Discovered libraries with type info
+
+
+@dataclass
+@PayloadRegistry.register
+class DiscoverLibrariesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Library discovery failed."""
+
+
+@dataclass
+@PayloadRegistry.register
+class EvaluateLibraryFitnessRequest(RequestPayload):
+    """Evaluate a library's fitness (compatibility with current engine).
+
+    Checks version compatibility and determines if the library can be loaded.
+    Does not actually load Python modules - just validates compatibility.
+
+    Args:
+        schema: The loaded LibrarySchema from metadata loading
+
+    Results: EvaluateLibraryFitnessResultSuccess | EvaluateLibraryFitnessResultFailure
+    """
+
+    schema: LibrarySchema
+
+
+@dataclass
+@PayloadRegistry.register
+class EvaluateLibraryFitnessResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Library fitness evaluation successful.
+
+    Returns fitness and any non-fatal problems (warnings).
+    Caller manages their own lifecycle state.
+    """
+
+    fitness: LibraryManager.LibraryFitness
+    problems: list[LibraryProblem]
+
+
+@dataclass
+@PayloadRegistry.register
+class EvaluateLibraryFitnessResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Library fitness evaluation failed - library is not fit for this engine.
+
+    Returns fitness and problems for caller to update their LibraryInfo.
+    """
+
+    fitness: LibraryManager.LibraryFitness
+    problems: list[LibraryProblem]
+
+
 @dataclass
 @PayloadRegistry.register
 class LoadLibrariesRequest(RequestPayload):

griptape_nodes/retained_mode/events/os_events.py

@@ -62,10 +62,10 @@ class FileSystemEntry:
     name: str
     path: str  # Workspace-relative path (for portability)
     is_dir: bool
-    size: int
-    modified_time: float
-    absolute_path: str  # Absolute resolved path
-    mime_type: str | None = None  # None for directories, mimetype for files
+    size: int = 0  # File size in bytes (0 if not included)
+    modified_time: float = 0.0  # Modification timestamp (0.0 if not included)
+    absolute_path: str = ""  # Absolute resolved path (empty if not included)
+    mime_type: str | None = None  # None for directories, mimetype for files (None if not included)
 
 
 @dataclass
@@ -122,6 +122,10 @@ class ListDirectoryRequest(RequestPayload):
                         If None, workspace constraints don't apply (e.g., cloud environments).
         pattern: Optional glob pattern to filter entries (e.g., "*.txt", "file_*.json").
                  Only matches against file/directory names, not full paths.
+        include_size: If True, include file size in results (default: True). Set to False for faster listing.
+        include_modified_time: If True, include modified time in results (default: True). Set to False for faster listing.
+        include_mime_type: If True, include MIME type in results (default: True). Set to False for faster listing.
+        include_absolute_path: If True, include absolute resolved path in results (default: True). Set to False for faster listing.
 
     Results: ListDirectoryResultSuccess (with entries) | ListDirectoryResultFailure (access denied, not found)
     """
@@ -130,6 +134,10 @@ class ListDirectoryRequest(RequestPayload):
     show_hidden: bool = False
     workspace_only: bool | None = True
     pattern: str | None = None
+    include_size: bool = True
+    include_modified_time: bool = True
+    include_mime_type: bool = True
+    include_absolute_path: bool = True
 
 
 @dataclass

griptape_nodes/retained_mode/managers/fitness_problems/libraries/__init__.py

@@ -9,6 +9,7 @@ from .deprecated_node_warning_problem import DeprecatedNodeWarningProblem
 from .duplicate_library_problem import DuplicateLibraryProblem
 from .duplicate_node_registration_problem import DuplicateNodeRegistrationProblem
 from .engine_version_error_problem import EngineVersionErrorProblem
+from .incompatible_requirements_problem import IncompatibleRequirementsProblem
 from .insufficient_disk_space_problem import InsufficientDiskSpaceProblem
 from .invalid_version_string_problem import InvalidVersionStringProblem
 from .library_json_decode_problem import LibraryJsonDecodeProblem
@@ -39,6 +40,7 @@ __all__ = [
     "DuplicateLibraryProblem",
     "DuplicateNodeRegistrationProblem",
     "EngineVersionErrorProblem",
+    "IncompatibleRequirementsProblem",
     "InsufficientDiskSpaceProblem",
     "InvalidVersionStringProblem",
     "LibraryJsonDecodeProblem",

griptape_nodes/retained_mode/managers/fitness_problems/libraries/incompatible_requirements_problem.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from griptape_nodes.retained_mode.managers.fitness_problems.libraries.library_problem import LibraryProblem
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class IncompatibleRequirementsProblem(LibraryProblem):
+    """Problem indicating library requirements are not met by the current system."""
+
+    requirements: dict[str, Any]
+    system_capabilities: dict[str, Any]
+
+    @classmethod
+    def collate_problems_for_display(cls, instances: list[IncompatibleRequirementsProblem]) -> str:
+        """Display incompatible requirements problem.
+
+        There should only be one instance per library since each LibraryInfo
+        is already associated with a specific library path.
+        """
+        if len(instances) > 1:
+            logger.error(
+                "IncompatibleRequirementsProblem: Expected 1 instance but got %s. Each LibraryInfo should only have one IncompatibleRequirementsProblem.",
+                len(instances),
+            )
+
+        # Use the first instance's details
+        problem = instances[0]
+        return f"Library requirements not met. Required: {problem.requirements}, System: {problem.system_capabilities}"

griptape_nodes/retained_mode/managers/flow_manager.py

@@ -2206,7 +2206,19 @@ class FlowManager:
             return
 
         # For each parameter, get its value from the SubflowNodeGroup and create a set value command
+        class_name_prefix = start_node_type.lower()
         for prefixed_param_name in parameter_names:
+            # Skip parameters that don't have the expected prefix for this StartFlow node.
+            # These are group-level settings that control the group's behavior
+            # but shouldn't be passed to the StartFlow node of each iteration.
+            if not prefixed_param_name.startswith(f"{class_name_prefix}_"):
+                logger.debug(
+                    "Skipping group-level parameter '%s' - not a StartFlow parameter (expected prefix '%s_')",
+                    prefixed_param_name,
+                    class_name_prefix,
+                )
+                continue
+
             # Get the value from the SubflowNodeGroup parameter
             param_value = node_group_node.get_parameter_value(param_name=prefixed_param_name)
 
@@ -2215,7 +2227,6 @@ class FlowManager:
                 continue
 
             # Strip the prefix to get the original parameter name for the StartFlow node
-            class_name_prefix = start_node_type.lower()
             original_param_name = prefixed_param_name.removeprefix(f"{class_name_prefix}_")
 
             # Create unique parameter UUID for this value
@@ -2542,11 +2553,22 @@ class FlowManager:
             details = f"Failed to kick off flow with name {flow_name}. Exception occurred: {e} "
             return StartFlowResultFailure(validation_exceptions=[e], result_details=details)
 
+        if self._global_control_flow_machine:
+            resolution_machine = self._global_control_flow_machine.resolution_machine
+            if resolution_machine.is_errored():
+                error_message = resolution_machine.get_error_message()
+                result_details = f"Failed to kick off flow with name {flow_name}. Exception occurred: {error_message} "
+                exception = RuntimeError(error_message)
+                # Pass through the error message without adding extra wrapping
+                return StartFlowResultFailure(
+                    validation_exceptions=[exception] if error_message else [], result_details=result_details
+                )
+
         details = f"Successfully kicked off flow with name {flow_name}"
 
         return StartFlowResultSuccess(result_details=details)
 
-    async def on_start_flow_from_node_request(self, request: StartFlowFromNodeRequest) -> ResultPayload:  # noqa: C901, PLR0911
+    async def on_start_flow_from_node_request(self, request: StartFlowFromNodeRequest) -> ResultPayload:  # noqa: C901, PLR0911, PLR0912
         # which flow
         flow_name = request.flow_name
         if not flow_name:
@@ -2601,6 +2623,15 @@ class FlowManager:
             details = f"Failed to kick off flow with name {flow_name}. Exception occurred: {e} "
             return StartFlowFromNodeResultFailure(validation_exceptions=[e], result_details=details)
 
+        if self._global_control_flow_machine:
+            resolution_machine = self._global_control_flow_machine.resolution_machine
+            if resolution_machine.is_errored():
+                error_message = resolution_machine.get_error_message()
+                # Pass through the error message without adding extra wrapping
+                return StartFlowFromNodeResultFailure(
+                    validation_exceptions=[], result_details=error_message or "Flow execution failed"
+                )
+
         details = f"Successfully kicked off flow with name {flow_name}"
 
         return StartFlowFromNodeResultSuccess(result_details=details)
@@ -2710,7 +2741,24 @@ class FlowManager:
 
         return start_nodes + control_nodes + valid_data_nodes
 
-    async def on_start_local_subflow_request(self, request: StartLocalSubflowRequest) -> ResultPayload:
+    def _validate_and_get_start_node(
+        self, flow_name: str, start_node_name: str | None, flow: ControlFlow
+    ) -> BaseNode | StartLocalSubflowResultFailure:
+        """Validate and get the start node for subflow execution."""
+        if start_node_name is None:
+            start_nodes = self.get_start_nodes_in_flow(flow)
+            if not start_nodes:
+                details = f"Cannot start subflow '{flow_name}'. No start nodes found in flow."
+                return StartLocalSubflowResultFailure(result_details=details)
+            return start_nodes[0]
+
+        try:
+            return GriptapeNodes.NodeManager().get_node_by_name(start_node_name)
+        except ValueError as err:
+            details = f"Cannot start subflow '{flow_name}'. Start node '{start_node_name}' not found: {err}"
+            return StartLocalSubflowResultFailure(result_details=details)
+
+    async def on_start_local_subflow_request(self, request: StartLocalSubflowRequest) -> ResultPayload:  # noqa: C901, PLR0911
         flow_name = request.flow_name
         if not flow_name:
             details = "Must provide flow name to start a flow."
@@ -2726,19 +2774,32 @@ class FlowManager:
             msg = "There must be a flow going to start a Subflow"
             return StartLocalSubflowResultFailure(result_details=msg)
 
-        start_node_name = request.start_node
-        if start_node_name is None:
-            start_nodes = self.get_start_nodes_in_flow(flow)
-            if not start_nodes:
-                details = f"Cannot start subflow '{flow_name}'. No start nodes found in flow."
-                return StartLocalSubflowResultFailure(result_details=details)
-            start_node = start_nodes[0]
-        else:
-            try:
-                start_node = GriptapeNodes.NodeManager().get_node_by_name(start_node_name)
-            except ValueError as err:
-                details = f"Cannot start subflow '{flow_name}'. Start node '{start_node_name}' not found: {err}"
-                return StartLocalSubflowResultFailure(result_details=details)
+        start_node = self._validate_and_get_start_node(flow_name, request.start_node, flow)
+        if isinstance(start_node, StartLocalSubflowResultFailure):
+            return start_node
+
+        # Run validation before starting the subflow
+        validation_result = await self.on_validate_flow_dependencies_request(
+            ValidateFlowDependenciesRequest(flow_name=flow_name, flow_node_name=start_node.name if start_node else None)
+        )
+        if validation_result.failed():
+            # Extract error details from the failed validation result
+            details = (
+                validation_result.result_details
+                if hasattr(validation_result, "result_details")
+                else f"Subflow '{flow_name}' validation failed"
+            )
+            return StartLocalSubflowResultFailure(result_details=details)
+
+        validation_result = cast("ValidateFlowDependenciesResultSuccess", validation_result)
+        if not validation_result.validation_succeeded:
+            # Build detailed error message with all validation exceptions
+            details_lines = []
+            if validation_result.exceptions:
+                for exception in validation_result.exceptions:
+                    details_lines.append(str(exception))  # noqa: PERF401 keeping in for loop for clarity.
+            details = "\n".join(details_lines) if details_lines else f"Subflow '{flow_name}' validation failed"
+            return StartLocalSubflowResultFailure(result_details=details)
 
         subflow_machine = ControlFlowMachine(
             flow.name,
@@ -2746,7 +2807,16 @@ class FlowManager:
             is_isolated=True,
         )
 
-        await subflow_machine.start_flow(start_node)
+        try:
+            await subflow_machine.start_flow(start_node)
+        except Exception as err:
+            msg = f"Failed to run flow {flow_name}. Error: {err}"
+            return StartLocalSubflowResultFailure(result_details=msg)
+
+        if subflow_machine.resolution_machine.is_errored():
+            error_message = subflow_machine.resolution_machine.get_error_message()
+            # Pass through the error message directly without wrapping
+            return StartLocalSubflowResultFailure(result_details=error_message or "Subflow errored during execution")
 
         return StartLocalSubflowResultSuccess(result_details=f"Successfully executed local subflow '{flow_name}'")
 
@@ -3686,6 +3756,20 @@ class FlowManager:
                 if self.check_for_existing_running_flow():
                     await self.cancel_flow_run()
                 raise RuntimeError(e) from e
+
+            if resolution_machine.is_errored():
+                error_message = resolution_machine.get_error_message()
+                logger.error("Node '%s' failed: %s", node.name, error_message)
+                self._global_single_node_resolution = False
+                self._global_control_flow_machine.context.current_nodes = []
+                GriptapeNodes.EventManager().put_event(
+                    ExecutionGriptapeNodeEvent(
+                        wrapped_event=ExecutionEvent(payload=InvolvedNodesEvent(involved_nodes=[]))
+                    )
+                )
+                # Re-raise with the original error message
+                raise RuntimeError(error_message or "Node resolution failed")
+
             if resolution_machine.is_complete():
                 self._global_single_node_resolution = False
                 self._global_control_flow_machine.context.current_nodes = []
@@ -4014,9 +4098,38 @@ class FlowManager:
                         queue.put(next_node)
         return list(processed.keys())
 
-    def is_node_connected(self, start_node: BaseNode, node: BaseNode) -> bool:
-        nodes = self.get_all_connected_nodes(start_node)
-        return node in nodes
+    def is_node_connected(self, start_node: BaseNode, node: BaseNode) -> list[str]:
+        """Check if node is in the forward control path from start_node, returning boundary nodes if connected.
+
+        Returns:
+            list[str]: Names of nodes that have direct connections to 'node' and are in the forward control path,
+                      or empty list if not in forward path.
+        """
+        connections = self.get_connections()
+
+        # Check if node is in the forward control path from start_node
+        if not connections.is_node_in_forward_control_path(start_node, node):
+            return []
+
+        # Node is in forward path - find boundary nodes that connect to it
+        boundary_nodes = []
+
+        # Check incoming connections to the target node
+        if node.name in connections.incoming_index:
+            incoming_params = connections.incoming_index[node.name]
+            for connection_ids in incoming_params.values():
+                for connection_id in connection_ids:
+                    connection = connections.connections[connection_id]
+                    source_node_name = connection.source_node.name
+
+                    # Only include if source node is also in the forward control path from start_node
+                    if (
+                        connections.is_node_in_forward_control_path(start_node, connection.source_node)
+                        and source_node_name not in boundary_nodes
+                    ):
+                        boundary_nodes.append(source_node_name)
+
+        return boundary_nodes
 
     def get_node_dependencies(self, flow: ControlFlow, node: BaseNode) -> list[BaseNode]:
         """Get all upstream nodes that the given node depends on.