griptape-nodes 0.38.1__py3-none-any.whl → 0.41.0__py3-none-any.whl

griptape_nodes/bootstrap/workflow_executors/local_workflow_executor.py

@@ -0,0 +1,213 @@
+import logging
+from queue import Queue
+from typing import Any
+
+from griptape.events import BaseEvent, EventBus, EventListener
+
+from griptape_nodes.bootstrap.workflow_executors.workflow_executor import WorkflowExecutor
+from griptape_nodes.drivers.storage import StorageBackend
+from griptape_nodes.exe_types.node_types import EndNode, StartNode
+from griptape_nodes.retained_mode.events.base_events import (
+    AppEvent,
+    EventRequest,
+    ExecutionGriptapeNodeEvent,
+    GriptapeNodeEvent,
+    ProgressEvent,
+)
+from griptape_nodes.retained_mode.events.execution_events import SingleExecutionStepRequest, StartFlowRequest
+from griptape_nodes.retained_mode.events.parameter_events import SetParameterValueRequest
+from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+
+logger = logging.getLogger(__name__)
+
+
+class LocalExecutorError(Exception):
+    """Exception raised during local workflow execution."""
+
+
+class LocalWorkflowExecutor(WorkflowExecutor):
+    def __init__(self) -> None:
+        self.queue = Queue()
+        self.output: dict | None = None
+
+    def _load_flow_for_workflow(self) -> str:
+        try:
+            context_manager = GriptapeNodes.ContextManager()
+            return context_manager.get_current_flow().name
+        except Exception as e:
+            msg = f"Failed to get current flow from context manager: {e}"
+            logger.exception(msg)
+            raise LocalExecutorError(msg) from e
+
+    def _set_storage_backend(self, storage_backend: StorageBackend) -> None:
+        from griptape_nodes.retained_mode.managers.config_manager import ConfigManager
+
+        try:
+            config_manager = ConfigManager()
+            config_manager.set_config_value(
+                key="storage_backend",
+                value=storage_backend,
+            )
+        except Exception as e:
+            msg = f"Failed to set storage backend: {e}"
+            logger.exception(msg)
+            raise LocalExecutorError(msg) from e
+
+    def _handle_event(self, event: BaseEvent) -> None:
+        try:
+            match event:
+                case GriptapeNodeEvent():
+                    self.__handle_node_event(event)
+                case ExecutionGriptapeNodeEvent():
+                    self.__handle_execution_node_event(event)
+                case ProgressEvent():
+                    self.__handle_progress_event(event)
+                case AppEvent():
+                    self.__handle_app_event(event)
+                case _:
+                    msg = f"Unknown event type: {type(event)}"
+                    logger.info(msg)
+                    self.queue.put(event)
+        except Exception as e:
+            logger.info(e)
+
+    def __handle_node_event(self, event: GriptapeNodeEvent) -> None:
+        result_event = event.wrapped_event
+        event_json = result_event.json()
+        event_log = f"GriptapeNodeEvent: {event_json}"
+        logger.info(event_log)
+
+    def __handle_execution_node_event(self, event: ExecutionGriptapeNodeEvent) -> None:
+        result_event = event.wrapped_event
+        if type(result_event.payload).__name__ == "NodeStartProcessEvent":
+            event_log = f"NodeStartProcessEvent: {result_event.payload}"
+            logger.info(event_log)
+
+        elif type(result_event.payload).__name__ == "ResumeNodeProcessingEvent":
+            event_log = f"ResumeNodeProcessingEvent: {result_event.payload}"
+            logger.info(event_log)
+
+            # Here we need to handle the resume event since this is the callback mechanism
+            # for the flow to be resumed for any Node that yields a generator in its process method.
+            node_name = result_event.payload.node_name
+            flow_name = GriptapeNodes.NodeManager().get_node_parent_flow_by_name(node_name)
+            event_request = EventRequest(request=SingleExecutionStepRequest(flow_name=flow_name))
+            GriptapeNodes.handle_request(event_request.request)
+
+        elif type(result_event.payload).__name__ == "NodeFinishProcessEvent":
+            event_log = f"NodeFinishProcessEvent: {result_event.payload}"
+            logger.info(event_log)
+
+        else:
+            event_log = f"ExecutionGriptapeNodeEvent: {result_event.payload}"
+            logger.info(event_log)
+
+        self.queue.put(event)
+
+    def __handle_progress_event(self, gt_event: ProgressEvent) -> None:
+        event_log = f"ProgressEvent: {gt_event}"
+        logger.info(event_log)
+
+    def __handle_app_event(self, event: AppEvent) -> None:
+        event_log = f"AppEvent: {event.payload}"
+        logger.info(event_log)
+
+    def _submit_output(self, output: dict) -> None:
+        self.output = output
+
+    def _set_input_for_flow(self, flow_name: str, flow_input: dict[str, dict]) -> None:
+        control_flow = GriptapeNodes.FlowManager().get_flow_by_name(flow_name)
+        nodes = control_flow.nodes
+        for node_name, node in nodes.items():
+            if isinstance(node, StartNode):
+                param_map: dict | None = flow_input.get(node_name)
+                if param_map is not None:
+                    for parameter_name, parameter_value in param_map.items():
+                        set_parameter_value_request = SetParameterValueRequest(
+                            parameter_name=parameter_name,
+                            value=parameter_value,
+                            node_name=node_name,
+                        )
+                        set_parameter_value_result = GriptapeNodes.handle_request(set_parameter_value_request)
+
+                        if set_parameter_value_result.failed():
+                            msg = f"Failed to set parameter {parameter_name} for node {node_name}."
+                            raise LocalExecutorError(msg)
+
+    def _get_output_for_flow(self, flow_name: str) -> dict:
+        control_flow = GriptapeNodes.FlowManager().get_flow_by_name(flow_name)
+        nodes = control_flow.nodes
+        output = {}
+        for node_name, node in nodes.items():
+            if isinstance(node, EndNode):
+                output[node_name] = node.parameter_values
+
+        return output
+
+    def run(self, workflow_name: str, flow_input: Any, storage_backend: StorageBackend = StorageBackend.LOCAL) -> None:
+        """Executes a local workflow.
+
+        Executes a workflow by setting up event listeners, registering libraries,
+        loading the user-defined workflow, and running the specified workflow.
+
+        Parameters:
+            workflow_name: The name of the workflow to execute.
+            flow_input: Input data for the flow, typically a dictionary.
+            storage_backend: The storage backend to use for the workflow execution.
+
+        Returns:
+            None
+        """
+        logger.info("Executing workflow: %s", workflow_name)
+
+        EventBus.add_event_listener(
+            event_listener=EventListener(
+                on_event=self._handle_event,
+            )
+        )
+
+        # Set the storage backend
+        self._set_storage_backend(storage_backend=storage_backend)
+        # Load the flow
+        flow_name = self._load_flow_for_workflow()
+        # Now let's set the input to the flow
+        self._set_input_for_flow(flow_name=flow_name, flow_input=flow_input)
+
+        # Now send the run command to actually execute it
+        start_flow_request = StartFlowRequest(flow_name=flow_name)
+        start_flow_result = GriptapeNodes.handle_request(start_flow_request)
+
+        if start_flow_result.failed():
+            msg = f"Failed to start flow {flow_name}"
+            raise LocalExecutorError(msg)
+
+        logger.info("Workflow started!")
+
+        # Wait for the control flow to finish
+        is_flow_finished = False
+        error: Exception | None = None
+        while not is_flow_finished:
+            try:
+                event = self.queue.get(block=True)
+
+                if isinstance(event, ExecutionGriptapeNodeEvent):
+                    result_event = event.wrapped_event
+
+                    if type(result_event.payload).__name__ == "ControlFlowResolvedEvent":
+                        self._submit_output(self._get_output_for_flow(flow_name=flow_name))
+                        is_flow_finished = True
+                        logger.info("Workflow finished!")
+                    elif type(result_event.payload).__name__ == "ControlFlowCancelledEvent":
+                        msg = "Control flow cancelled"
+                        is_flow_finished = True
+                        logger.error(msg)
+                        error = LocalExecutorError(msg)
+
+                self.queue.task_done()
+
+            except Exception as e:
+                msg = f"Error handling queue event: {e}"
+                logger.info(msg)
+
+        if error is not None:
+            raise error

griptape_nodes/bootstrap/workflow_executors/workflow_executor.py

@@ -0,0 +1,13 @@
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from griptape_nodes.drivers.storage import StorageBackend
+
+logger = logging.getLogger(__name__)
+
+
+class WorkflowExecutor(ABC):
+    @abstractmethod
+    def run(self, workflow_name: str, flow_input: Any, storage_backend: StorageBackend = StorageBackend.LOCAL) -> None:
+        pass

griptape_nodes/bootstrap/workflow_runners/local_workflow_runner.py

@@ -35,7 +35,7 @@ class LocalWorkflowRunner(WorkflowRunner):
         file_path = Path(path_to_workflow)
 
         # Generate a unique module name
-        module_name = f"dynamic_module_{file_path.name.replace('.', '_')}_{hash(str(file_path))}"
+        module_name = f"gtn_dynamic_module_{file_path.name.replace('.', '_')}_{hash(str(file_path))}"
 
         # Load the module specification
         spec = importlib.util.spec_from_file_location(module_name, file_path)

griptape_nodes/drivers/storage/__init__.py

@@ -2,3 +2,7 @@
 
 Storage drivers are responsible for managing the storage and retrieval of files.
 """
+
+from .storage_backend import StorageBackend
+
+__all__ = ["StorageBackend"]

griptape_nodes/drivers/storage/storage_backend.py

@@ -0,0 +1,10 @@
+"""Storage backend enumeration."""
+
+from enum import StrEnum
+
+
+class StorageBackend(StrEnum):
+    """Enumeration of available storage backends."""
+
+    LOCAL = "local"
+    GTC = "gtc"

griptape_nodes/exe_types/core_types.py

@@ -216,7 +216,6 @@ class BaseNodeElement:
                 new_value = getattr(self, f"{func.__name__}", None) if hasattr(self, f"{func.__name__}") else None
                 # Track change if different
                 if old_value != new_value:
-                    # it needs to be static so we can call these methods.
                     self._changes[func.__name__] = new_value
                     if self._node_context is not None and self not in self._node_context._tracked_parameters:
                         self._node_context._tracked_parameters.append(self)
@@ -735,6 +734,11 @@ class Parameter(BaseNodeElement):
     @BaseNodeElement.emits_update_on_write
     def allowed_modes(self, value: Any) -> None:
         self._allowed_modes = value
+        # Handle mode flag decomposition
+        if isinstance(value, set):
+            self._changes["mode_allowed_input"] = ParameterMode.INPUT in value
+            self._changes["mode_allowed_output"] = ParameterMode.OUTPUT in value
+            self._changes["mode_allowed_property"] = ParameterMode.PROPERTY in value
 
     @property
     def ui_options(self) -> dict:

griptape_nodes/exe_types/node_types.py

@@ -136,7 +136,6 @@ class BaseNode(ABC):
         source_node: BaseNode,  # noqa: ARG002
         source_parameter: Parameter,  # noqa: ARG002
         target_parameter: Parameter,  # noqa: ARG002
-        modified_parameters_set: set[str] | None = None,  # noqa: ARG002
     ) -> None:
         """Callback after a Connection has been established TO this Node."""
         return
@@ -146,7 +145,6 @@ class BaseNode(ABC):
         source_parameter: Parameter,  # noqa: ARG002
         target_node: BaseNode,  # noqa: ARG002
         target_parameter: Parameter,  # noqa: ARG002
-        modified_parameters_set: set[str] | None = None,  # noqa: ARG002
     ) -> None:
         """Callback after a Connection has been established OUT of this Node."""
         return
@@ -156,7 +154,6 @@ class BaseNode(ABC):
         source_node: BaseNode,  # noqa: ARG002
         source_parameter: Parameter,  # noqa: ARG002
         target_parameter: Parameter,  # noqa: ARG002
-        modified_parameters_set: set[str] | None = None,  # noqa: ARG002
     ) -> None:
         """Callback after a Connection TO this Node was REMOVED."""
         return
@@ -166,7 +163,6 @@ class BaseNode(ABC):
         source_parameter: Parameter,  # noqa: ARG002
         target_node: BaseNode,  # noqa: ARG002
         target_parameter: Parameter,  # noqa: ARG002
-        modified_parameters_set: set[str] | None = None,  # noqa: ARG002
     ) -> None:
         """Callback after a Connection OUT of this Node was REMOVED."""
         return
@@ -175,7 +171,6 @@ class BaseNode(ABC):
         self,
         parameter: Parameter,  # noqa: ARG002
         value: Any,
-        modified_parameters_set: set[str] | None = None,  # noqa: ARG002
     ) -> Any:
         """Callback when a Parameter's value is ABOUT to be set.
 
@@ -191,7 +186,6 @@ class BaseNode(ABC):
         Args:
             parameter: the Parameter on this node that is about to be changed
             value: the value intended to be set (this has already gone through any converters and validators on the Parameter)
-            modified_parameters_set: A set of parameter names within this node that were modified as a result of this call.
 
         Returns:
             The final value to set for the Parameter. This gives the Node logic one last opportunity to mutate the value
@@ -204,7 +198,6 @@ class BaseNode(ABC):
         self,
         parameter: Parameter,  # noqa: ARG002
         value: Any,  # noqa: ARG002
-        modified_parameters_set: set[str] | None = None,  # noqa: ARG002
     ) -> None:
         """Callback AFTER a Parameter's value was set.
 
@@ -225,8 +218,6 @@ class BaseNode(ABC):
         Args:
             parameter: the Parameter on this node that was just changed
             value: the value that was set (already converted, validated, and possibly mutated by the node code)
-            modified_parameters_set: Optional set of parameter names within this node
-                that were modified as a result of this call. The Parameter this was called on does NOT need to be part of the return.
 
         Returns:
             Nothing
@@ -480,7 +471,9 @@ class BaseNode(ABC):
                 return element_item
         return None
 
-    def set_parameter_value(self, param_name: str, value: Any) -> None:
+    def set_parameter_value(
+        self, param_name: str, value: Any, *, initial_setup: bool = False, emit_change: bool = True
+    ) -> None:
         """Attempt to set a Parameter's value.
 
         The Node may choose to store a different value (or type) than what was passed in.
@@ -498,6 +491,8 @@ class BaseNode(ABC):
         Args:
             param_name: the name of the Parameter on this node that is about to be changed
             value: the value intended to be set
+            emit_change: whether to emit a parameter lifecycle event, defaults to True
+            initial_setup: Whether this value is being set as the initial setup on the node, defaults to False. When True, the value is not given to any before/after hooks.
 
         Returns:
             A set of parameter names within this node that were modified as a result
@@ -525,22 +520,18 @@ class BaseNode(ABC):
 
         # Allow custom node logic to prepare and possibly mutate the value before it is actually set.
         # Record any parameters modified for cascading.
-        try:
+        if not initial_setup:
             final_value = self.before_value_set(parameter=parameter, value=candidate_value)
-        except TypeError:
-            final_value = self.before_value_set(
-                parameter=parameter, value=candidate_value, modified_parameters_set=set()
-            )
-        # ACTUALLY SET THE NEW VALUE
-        self.parameter_values[param_name] = final_value
+            # ACTUALLY SET THE NEW VALUE
+            self.parameter_values[param_name] = final_value
 
-        # If a parameter value has been set at the top level of a container, wipe all children.
-        # Allow custom node logic to respond after it's been set. Record any modified parameters for cascading.
-        try:
+            # If a parameter value has been set at the top level of a container, wipe all children.
+            # Allow custom node logic to respond after it's been set. Record any modified parameters for cascading.
             self.after_value_set(parameter=parameter, value=final_value)
-        except TypeError:
-            self.after_value_set(parameter=parameter, value=final_value, modified_parameters_set=set())
-        self._emit_parameter_lifecycle_event(parameter)
+            if emit_change:
+                self._emit_parameter_lifecycle_event(parameter)
+        else:
+            self.parameter_values[param_name] = candidate_value
         # handle with container parameters
         if parameter.parent_container_name is not None:
             # Does it have a parent container
@@ -551,7 +542,12 @@ class BaseNode(ABC):
                 new_parent_value = handle_container_parameter(self, parent_parameter)
                 if new_parent_value is not None:
                     # set that new value if it exists.
-                    self.set_parameter_value(parameter.parent_container_name, new_parent_value)
+                    self.set_parameter_value(
+                        parameter.parent_container_name,
+                        new_parent_value,
+                        initial_setup=initial_setup,
+                        emit_change=False,
+                    )
 
     def kill_parameter_children(self, parameter: Parameter) -> None:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes

griptape_nodes/machines/node_resolution.py

@@ -230,7 +230,11 @@ class ExecuteNodeState(State):
                     )
                 )
 
-        current_node.validate_before_node_run()
+        exceptions = current_node.validate_before_node_run()
+        if exceptions:
+            msg = f"Canceling flow run. Node '{current_node.name}' encountered problems: {exceptions}"
+            # Mark the node as unresolved, broadcasting to everyone.
+            raise RuntimeError(msg)
         if not context.paused:
             return ExecuteNodeState
         return None

griptape_nodes/node_library/advanced_node_library.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from griptape_nodes.node_library.library_registry import Library, LibrarySchema
+
+
+class AdvancedNodeLibrary:
+    """Base class for advanced node libraries with callback support.
+
+    Library modules can inherit from this class to provide custom initialization
+    and cleanup logic that runs before and after node loading.
+
+    Example usage:
+        ```python
+        # In your library's advanced library module file:
+        from griptape_nodes.node_library.advanced_node_library import AdvancedNodeLibrary
+
+        class MyLibrary(AdvancedNodeLibrary):
+            def before_library_nodes_loaded(self, library_data, library):
+                # Set up any prerequisites before nodes are loaded
+                print(f"About to load nodes for {library_data.name}")
+
+            def after_library_nodes_loaded(self, library_data, library):
+                # Perform any cleanup or additional setup after nodes are loaded
+                print(f"Finished loading {len(library.get_registered_nodes())} nodes")
+        ```
+    """
+
+    def before_library_nodes_loaded(self, library_data: LibrarySchema, library: Library) -> None:
+        """Called before any nodes are loaded from the library.
+
+        This method is called after the library instance is created but before
+        any individual node classes are dynamically loaded and registered.
+
+        Args:
+            library_data: The library schema containing metadata and node definitions
+            library: The library instance that will contain the loaded nodes
+        """
+
+    def after_library_nodes_loaded(self, library_data: LibrarySchema, library: Library) -> None:
+        """Called after all nodes have been loaded from the library.
+
+        This method is called after all node classes have been successfully
+        loaded and registered with the library.
+
+        Args:
+            library_data: The library schema containing metadata and node definitions
+            library: The library instance containing the loaded nodes
+        """

griptape_nodes/node_library/library_registry.py

@@ -9,6 +9,7 @@ from griptape_nodes.utils.metaclasses import SingletonMeta
 
 if TYPE_CHECKING:
     from griptape_nodes.exe_types.node_types import BaseNode
+    from griptape_nodes.node_library.advanced_node_library import AdvancedNodeLibrary
 
 logger = logging.getLogger("griptape_nodes")
 
@@ -42,6 +43,13 @@ class LibraryMetadata(BaseModel):
     is_griptape_nodes_searchable: bool = True
 
 
+class IconVariant(BaseModel):
+    """Icon variant for light and dark themes."""
+
+    light: str
+    dark: str
+
+
 class NodeMetadata(BaseModel):
     """Metadata about each node within the library, which informs where in the hierarchy it sits, details on usage, and tags to assist search."""
 
@@ -49,6 +57,9 @@ class NodeMetadata(BaseModel):
     description: str
     display_name: str
     tags: list[str] | None = None
+    icon: str | IconVariant | None = None
+    color: str | None = None
+    group: str | None = None
 
 
 class CategoryDefinition(BaseModel):
@@ -84,7 +95,7 @@ class LibrarySchema(BaseModel):
     library itself.
     """
 
-    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.1.0"
+    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.2.0"
 
     name: str
     library_schema_version: str
@@ -95,6 +106,7 @@ class LibrarySchema(BaseModel):
     scripts: list[str] | None = None
     settings: list[Setting] | None = None
     is_default_library: bool | None = None
+    advanced_library_path: str | None = None
 
 
 class LibraryRegistry(metaclass=SingletonMeta):
@@ -110,13 +122,16 @@ class LibraryRegistry(metaclass=SingletonMeta):
         library_data: LibrarySchema,
         *,
         mark_as_default_library: bool = False,
+        advanced_library: AdvancedNodeLibrary | None = None,
     ) -> Library:
         instance = cls()
 
         if library_data.name in instance._libraries:
             msg = f"Library '{library_data.name}' already registered."
             raise KeyError(msg)
-        library = Library(library_data=library_data, is_default_library=mark_as_default_library)
+        library = Library(
+            library_data=library_data, is_default_library=mark_as_default_library, advanced_library=advanced_library
+        )
         instance._libraries[library_data.name] = library
         return library
 
@@ -227,12 +242,14 @@ class Library:
     # Maintain fast lookups for node class name to class and to its metadata.
     _node_types: dict[str, type[BaseNode]]
     _node_metadata: dict[str, NodeMetadata]
+    _advanced_library: AdvancedNodeLibrary | None
 
     def __init__(
         self,
         library_data: LibrarySchema,
         *,
         is_default_library: bool = False,
+        advanced_library: AdvancedNodeLibrary | None = None,
     ) -> None:
         self._library_data = library_data
 
@@ -244,6 +261,7 @@ class Library:
 
         self._node_types = {}
         self._node_metadata = {}
+        self._advanced_library = advanced_library
 
     def register_new_node_type(self, node_class: type[BaseNode], metadata: NodeMetadata) -> str | None:
         """Register a new node type in this library. Returns an error string for forensics, or None if all clear."""
@@ -303,3 +321,11 @@ class Library:
 
     def get_metadata(self) -> LibraryMetadata:
         return self._library_data.metadata
+
+    def get_advanced_library(self) -> AdvancedNodeLibrary | None:
+        """Get the advanced library instance for this library.
+
+        Returns:
+            The AdvancedNodeLibrary instance, or None if not set
+        """
+        return self._advanced_library

griptape_nodes/node_library/workflow_registry.py

@@ -13,7 +13,7 @@ from griptape_nodes.utils.metaclasses import SingletonMeta
 
 
 class WorkflowMetadata(BaseModel):
-    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.3.0"
+    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.4.0"
 
     name: str
     schema_version: str

griptape_nodes/retained_mode/events/agent_events.py

@@ -12,22 +12,35 @@ from griptape_nodes.retained_mode.events.base_events import (
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
 
+@dataclass
+class RunAgentRequestArtifact(dict):
+    type: str
+    value: str
+
+
 @dataclass
 @PayloadRegistry.register
 class RunAgentRequest(RequestPayload):
     input: str
+    url_artifacts: list[RunAgentRequestArtifact]
+
+
+@dataclass
+@PayloadRegistry.register
+class RunAgentResultStarted(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    pass
 
 
 @dataclass
 @PayloadRegistry.register
 class RunAgentResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    output: str
+    output: dict
 
 
 @dataclass
 @PayloadRegistry.register
 class RunAgentResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    error: str
+    error: dict
 
 
 @dataclass