griptape-nodes 0.64.11__py3-none-any.whl → 0.65.1__py3-none-any.whl

griptape_nodes/exe_types/connections.py

@@ -1,9 +1,11 @@
 import logging
 from dataclasses import dataclass
 from enum import StrEnum
+from typing import NamedTuple
 
+from griptape_nodes.exe_types.base_iterative_nodes import BaseIterativeEndNode, BaseIterativeStartNode
 from griptape_nodes.exe_types.core_types import Parameter, ParameterMode, ParameterTypeBuiltin
-from griptape_nodes.exe_types.node_types import BaseNode, Connection, EndLoopNode, NodeResolutionState, StartLoopNode
+from griptape_nodes.exe_types.node_types import BaseNode, Connection, NodeResolutionState
 
 logger = logging.getLogger("griptape_nodes")
 
@@ -13,6 +15,11 @@ class Direction(StrEnum):
     DOWNSTREAM = "downstream"
 
 
+class ConnectionData(NamedTuple):
+    node: BaseNode
+    parameter: Parameter
+
+
 @dataclass
 class Connections:
     # store connections as IDs
@@ -33,6 +40,8 @@ class Connections:
         source_parameter: Parameter,
         target_node: BaseNode,
         target_parameter: Parameter,
+        *,
+        is_node_group_internal: bool = False,
     ) -> Connection:
         if ParameterMode.OUTPUT not in source_parameter.get_mode():
             errormsg = f"Output Connection not allowed on Parameter '{source_parameter.name}'."
@@ -44,7 +53,13 @@ class Connections:
         if self.connection_allowed(source_node, source_parameter, is_source=True) and self.connection_allowed(
             target_node, target_parameter, is_source=False
         ):
-            connection = Connection(source_node, source_parameter, target_node, target_parameter)
+            connection = Connection(
+                source_node,
+                source_parameter,
+                target_node,
+                target_parameter,
+                is_node_group_internal=is_node_group_internal,
+            )
             # New index management.
             connection_id = id(connection)
             # Add connection to our dict here
@@ -106,14 +121,14 @@ class Connections:
         return connection is None
 
     def _get_connected_node_for_end_loop_control(
-        self, end_loop_node: EndLoopNode, control_parameter: Parameter
-    ) -> tuple[BaseNode, Parameter] | None:
-        """For an EndLoopNode and its control parameter, finds the connected node and parameter.
+        self, end_loop_node: BaseIterativeEndNode, control_parameter: Parameter
+    ) -> ConnectionData | None:
+        """For a BaseIterativeEndNode and its control parameter, finds the connected node and parameter.
 
-        It checks both outgoing connections (where EndLoopNode's parameter is a source)
-        and incoming connections (where EndLoopNode's parameter is a target).
+        It checks both outgoing connections (where BaseIterativeEndNode's parameter is a source)
+        and incoming connections (where BaseIterativeEndNode's parameter is a target).
         """
-        # Check if the EndLoopNode's control parameter is a source for an outgoing connection
+        # Check if the BaseIterativeEndNode's control parameter is a source for an outgoing connection
         if ParameterMode.OUTPUT in control_parameter.allowed_modes:
             outgoing_connections_for_node = self.outgoing_index.get(end_loop_node.name, {})
             connection_ids_as_source = outgoing_connections_for_node.get(control_parameter.name, [])
@@ -121,23 +136,23 @@ class Connections:
                 connection_id = connection_ids_as_source[0]
                 connection = self.connections.get(connection_id)
                 if connection:
-                    return connection.target_node, connection.target_parameter
+                    return ConnectionData(connection.target_node, connection.target_parameter)
         elif ParameterMode.INPUT in control_parameter.allowed_modes:
-            # Check if the EndLoopNode's control parameter is a target for an incoming connection
+            # Check if the BaseIterativeEndNode's control parameter is a target for an incoming connection
             incoming_connections_for_node = self.incoming_index.get(end_loop_node.name, {})
             connection_ids_as_target = incoming_connections_for_node.get(control_parameter.name, [])
             if connection_ids_as_target:
                 for connection_id in connection_ids_as_target:
                     connection = self.connections.get(connection_id)
-                    if connection and isinstance(connection.source_node, StartLoopNode):
-                        return connection.source_node, connection.source_parameter
+                    if connection and isinstance(connection.source_node, BaseIterativeStartNode):
+                        return ConnectionData(connection.source_node, connection.source_parameter)
         return None  # No connection found for this control parameter
 
-    def get_connected_node(
-        self, node: BaseNode, parameter: Parameter, direction: Direction | None = None
-    ) -> tuple[BaseNode, Parameter] | None:
+    def get_connected_node(  # noqa: C901, Need if checks.
+        self, node: BaseNode, parameter: Parameter, direction: Direction | None = None, *, include_internal: bool = True
+    ) -> ConnectionData | None:
         # Check to see if we should be getting the next connection or the previous connection based on the parameter.
-        # Override this method for EndLoopNodes - these might have to go backwards or forwards.
+        # Override this method for BaseIterativeEndNodes - these might have to go backwards or forwards.
         if direction is not None:
             # We've added direction as an override, since we sometimes need to get connections in a certain direction regardless of parameter types.
             if direction == Direction.UPSTREAM:
@@ -145,7 +160,10 @@ class Connections:
             elif direction == Direction.DOWNSTREAM:
                 connections = self.outgoing_index
         else:
-            if isinstance(node, EndLoopNode) and ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
+            if (
+                isinstance(node, BaseIterativeEndNode)
+                and ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type
+            ):
                 return self._get_connected_node_for_end_loop_control(node, parameter)
             if ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
                 connections = self.outgoing_index
@@ -176,11 +194,14 @@ class Connections:
         connection_id = connection_id[0]
         if connection_id in self.connections:
             connection = self.connections[connection_id]
+            # We don't traverse internal NodeGroup connections when include_internal is False.
+            if connection.is_node_group_internal and not include_internal:
+                return None
             if direction == Direction.DOWNSTREAM:
                 # Return the target (next place to go)
-                return connection.target_node, connection.target_parameter
+                return ConnectionData(connection.target_node, connection.target_parameter)
             # Return the source (next place to chain back to)
-            return connection.source_node, connection.source_parameter
+            return ConnectionData(connection.source_node, connection.source_parameter)
         return None
 
     def remove_connection_by_object(self, conn: Connection) -> bool:
@@ -308,3 +329,77 @@ class Connections:
                                 )
                             )
                             self.unresolve_future_nodes(target_node)
+
+    def get_outgoing_connections_to_node(self, node: BaseNode, to_node: BaseNode) -> dict[str, list[Connection]]:
+        connections = {}
+        if node.name in self.outgoing_index:
+            parameters = self.outgoing_index[node.name]
+            for parameter, connection_ids in parameters.items():
+                for conn_id in connection_ids:
+                    connection = self.connections[conn_id]
+                    if connection.target_node.name == to_node.name:
+                        if parameter not in connections:
+                            connections[parameter] = [connection]
+                        else:
+                            connections[parameter].append(connection)
+        return connections
+
+    def get_incoming_connections_from_node(self, node: BaseNode, from_node: BaseNode) -> dict[str, list[Connection]]:
+        connections = {}
+        if node.name in self.incoming_index:
+            parameters = self.incoming_index[node.name]
+            for parameter, connection_ids in parameters.items():
+                for conn_id in connection_ids:
+                    connection = self.connections[conn_id]
+                    if connection.source_node.name == from_node.name:
+                        if parameter not in connections:
+                            connections[parameter] = [connection]
+                        else:
+                            connections[parameter].append(connection)
+        return connections
+
+    def get_outgoing_connections_from_parameter(self, node: BaseNode, parameter: Parameter) -> list[Connection]:
+        connections = []
+        if node.name in self.outgoing_index and parameter.name in self.outgoing_index[node.name]:
+            for conn_id in self.outgoing_index[node.name][parameter.name]:
+                connections.append(self.connections[conn_id])  # noqa: PERF401
+        return connections
+
+    def get_incoming_connections_to_parameter(self, node: BaseNode, parameter: Parameter) -> list[Connection]:
+        connections = []
+        if node.name in self.incoming_index and parameter.name in self.incoming_index[node.name]:
+            for conn_id in self.incoming_index[node.name][parameter.name]:
+                connections.append(self.connections[conn_id])  # noqa: PERF401
+        return connections
+
+    def get_all_outgoing_connections(self, node: BaseNode) -> list[Connection]:
+        """Get all outgoing connections from a node.
+
+        Args:
+            node: The node to get outgoing connections for
+
+        Returns:
+            List of all outgoing connections from the node
+        """
+        connections = []
+        if node.name in self.outgoing_index:
+            for connection_ids in self.outgoing_index[node.name].values():
+                for conn_id in connection_ids:
+                    connections.append(self.connections[conn_id])  # noqa: PERF401, Keeping loop for understanding.
+        return connections
+
+    def get_all_incoming_connections(self, node: BaseNode) -> list[Connection]:
+        """Get all incoming connections to a node.
+
+        Args:
+            node: The node to get incoming connections for
+
+        Returns:
+            List of all incoming connections to the node
+        """
+        connections = []
+        if node.name in self.incoming_index:
+            for connection_ids in self.incoming_index[node.name].values():
+                for conn_id in connection_ids:
+                    connections.append(self.connections[conn_id])  # noqa: PERF401, Keeping loop for understanding.
+        return connections

griptape_nodes/exe_types/core_types.py

@@ -479,10 +479,56 @@ class BaseNodeElement:
         # No child handled it, return None (indicating no handler)
         return None
 
+    def get_node(self) -> BaseNode | None:
+        """Get the node context associated with this element.
+
+        Returns:
+            BaseNode | None: The parent node that owns this element, or None if no node context is set.
+        """
+        return self._node_context
+
 
 class UIOptionsMixin:
     """Mixin providing UI options update functionality for classes with ui_options."""
 
+    def _validate_ui_option_conflict(
+        self,
+        ui_options_dict: dict,
+        param_name: str,
+        param_value: Any,
+    ) -> None:
+        """Validate that explicit parameter doesn't conflict with ui_options dict.
+
+        Logs a warning if there's a conflict and the ui_options value will be used.
+
+        Args:
+            ui_options_dict: The ui_options dictionary to check
+            param_name: Name of the parameter (e.g., "hide", "markdown")
+            param_value: Value of the explicit parameter
+        """
+        if param_name not in ui_options_dict:
+            return
+
+        dict_value = ui_options_dict[param_name]
+
+        if param_value != dict_value:
+            # Get element name for better error messages
+            element_name = getattr(self, "name", None)
+            class_name = self.__class__.__name__
+
+            # Build element part
+            if element_name:
+                element_part = f"{class_name} '{element_name}'"
+            else:
+                element_part = class_name
+
+            msg = (
+                f"{element_part}: Conflicting values for '{param_name}'. "
+                f'Explicit parameter {param_name}={param_value!r} conflicts with ui_options["{param_name}"]={dict_value!r}. '
+                f"The value from ui_options will be used. Please contact the library author to fix this issue."
+            )
+            logger.warning(msg)
+
     def update_ui_options_key(self, key: str, value: Any) -> None:
         """Update a single UI option key."""
         ui_options = self.ui_options
@@ -558,10 +604,15 @@ class ParameterMessage(BaseNodeElement, UIOptionsMixin):
         button_variant: ButtonVariantType = "outline",
         button_align: ButtonAlignType = "full-width",
         full_width: bool = False,
+        markdown: bool | None = None,
+        hide: bool | None = None,
         ui_options: dict | None = None,
         traits: set[Trait.__class__ | Trait] | None = None,
         **kwargs,
     ):
+        # Remove markdown and hide from kwargs to prevent passing them to parent class
+        kwargs.pop("markdown", None)
+        kwargs.pop("hide", None)
         super().__init__(element_type=ParameterMessage.__name__, **kwargs)
         self._variant = variant
         self._title = title
@@ -575,6 +626,21 @@ class ParameterMessage(BaseNodeElement, UIOptionsMixin):
         self._full_width = full_width
         self._ui_options = ui_options or {}
 
+        # Validate that explicit parameters don't conflict with ui_options (only if not None)
+        if markdown is not None:
+            self._validate_ui_option_conflict(
+                ui_options_dict=self._ui_options, param_name="markdown", param_value=markdown
+            )
+        if hide is not None:
+            self._validate_ui_option_conflict(ui_options_dict=self._ui_options, param_name="hide", param_value=hide)
+
+        # Add common UI options if explicitly provided (not None) and NOT already in ui_options
+        # (ui_options always wins in case of conflict)
+        if markdown is not None and "markdown" not in self._ui_options:
+            self._ui_options["markdown"] = markdown
+        if hide is not None and "hide" not in self._ui_options:
+            self._ui_options["hide"] = hide
+
         # Handle traits if provided
         if traits:
             for trait in traits:
@@ -676,6 +742,44 @@ class ParameterMessage(BaseNodeElement, UIOptionsMixin):
     def button_align(self, value: ButtonAlignType) -> None:
         self._button_align = value
 
+    @property
+    def markdown(self) -> bool:
+        """Get whether markdown rendering is enabled.
+
+        Returns:
+            True if markdown rendering is enabled, False otherwise
+        """
+        return self.ui_options.get("markdown", False)
+
+    @markdown.setter
+    @BaseNodeElement.emits_update_on_write
+    def markdown(self, value: bool) -> None:
+        """Set whether to enable markdown rendering.
+
+        Args:
+            value: True to enable markdown rendering, False to disable it
+        """
+        self.update_ui_options_key("markdown", value)
+
+    @property
+    def hide(self) -> bool:
+        """Get whether the message is hidden in the UI.
+
+        Returns:
+            True if the message should be hidden, False otherwise
+        """
+        return self.ui_options.get("hide", False)
+
+    @hide.setter
+    @BaseNodeElement.emits_update_on_write
+    def hide(self, value: bool) -> None:
+        """Set whether to hide the message in the UI.
+
+        Args:
+            value: True to hide the message, False to show it
+        """
+        self.update_ui_options_key("hide", value)
+
     @property
     def ui_options(self) -> dict:
         return self._ui_options
@@ -907,6 +1011,103 @@ class ParameterGroup(BaseNodeElement, UIOptionsMixin):
         return super().remove_child(child)
 
 
+class ParameterButtonGroup(BaseNodeElement, UIOptionsMixin):
+    """UI element for grouping buttons together in a row (similar to shadcn ButtonGroup).
+
+    This class creates a button group container that displays buttons horizontally
+    with proper spacing and styling, similar to shadcn/ui's ButtonGroup component.
+
+    Example:
+        with ParameterButtonGroup(name="actions", orientation="horizontal") as button_group:
+            ParameterButton(
+                name="save",
+                label="Save",
+                variant="default",
+            )
+            ParameterButton(
+                name="cancel",
+                label="Cancel",
+                variant="secondary",
+            )
+    """
+
+    def __init__(
+        self,
+        name: str,
+        ui_options: dict | None = None,
+        *,
+        orientation: Literal["horizontal", "vertical"] = "horizontal",
+        **kwargs,
+    ):
+        super().__init__(name=name, element_type="ParameterButtonGroup", **kwargs)
+        if ui_options is None:
+            ui_options = {}
+        else:
+            ui_options = ui_options.copy()
+
+        # Set button group specific UI options
+        ui_options["button_group"] = True
+        ui_options["orientation"] = orientation
+
+        self._ui_options = ui_options
+        self._orientation: Literal["horizontal", "vertical"] = orientation
+
+    @property
+    def ui_options(self) -> dict:
+        return self._ui_options
+
+    @ui_options.setter
+    @BaseNodeElement.emits_update_on_write
+    def ui_options(self, value: dict) -> None:
+        self._ui_options = value
+
+    @property
+    def orientation(self) -> Literal["horizontal", "vertical"]:
+        """Get the button group orientation.
+
+        Returns:
+            "horizontal" for buttons in a row, "vertical" for buttons in a column
+        """
+        return self._orientation
+
+    @orientation.setter
+    @BaseNodeElement.emits_update_on_write
+    def orientation(self, value: Literal["horizontal", "vertical"]) -> None:
+        """Set the button group orientation.
+
+        Args:
+            value: "horizontal" for buttons in a row, "vertical" for buttons in a column
+        """
+        self._orientation = value
+        self.update_ui_options_key("orientation", value)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Returns a nested dictionary representation of this button group and its children."""
+        our_dict = super().to_dict()
+        our_dict["name"] = self.name
+        our_dict["ui_options"] = self.ui_options
+        return our_dict
+
+    def to_event(self, node: BaseNode) -> dict:
+        event_data = super().to_event(node)
+        event_data["ui_options"] = self.ui_options
+        return event_data
+
+    def add_child(self, child: BaseNodeElement) -> None:
+        child.parent_group_name = self.name
+        return super().add_child(child)
+
+    def remove_child(self, child: BaseNodeElement | str) -> None:
+        if isinstance(child, str):
+            child_from_str = self.find_element_by_name(child)
+            if child_from_str is not None and isinstance(child_from_str, BaseNodeElement):
+                child_from_str.parent_group_name = None
+                return super().remove_child(child_from_str)
+        else:
+            child.parent_group_name = None
+        return super().remove_child(child)
+
+
 # TODO: https://github.com/griptape-ai/griptape-nodes/issues/856
 class ParameterBase(BaseNodeElement, ABC):
     @property
@@ -1012,9 +1213,9 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         traits: set[Trait.__class__ | Trait] | None = None,  # We are going to make these children.
         ui_options: dict | None = None,
         *,
-        hide: bool = False,
-        hide_label: bool = False,
-        hide_property: bool = False,
+        hide: bool | None = None,
+        hide_label: bool | None = None,
+        hide_property: bool | None = None,
         allow_input: bool = True,
         allow_property: bool = True,
         allow_output: bool = True,
@@ -1092,12 +1293,25 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         else:
             self._ui_options = ui_options.copy()
 
-        # Add common UI options if they have truthy values
-        if hide:
+        # Validate that explicit parameters don't conflict with ui_options (only if not None)
+        if hide is not None:
+            self._validate_ui_option_conflict(ui_options_dict=self._ui_options, param_name="hide", param_value=hide)
+        if hide_label is not None:
+            self._validate_ui_option_conflict(
+                ui_options_dict=self._ui_options, param_name="hide_label", param_value=hide_label
+            )
+        if hide_property is not None:
+            self._validate_ui_option_conflict(
+                ui_options_dict=self._ui_options, param_name="hide_property", param_value=hide_property
+            )
+
+        # Add common UI options if explicitly provided (not None) and NOT already in ui_options
+        # (ui_options always wins in case of conflict)
+        if hide is not None and "hide" not in self._ui_options:
             self._ui_options["hide"] = hide
-        if hide_label:
+        if hide_label is not None and "hide_label" not in self._ui_options:
             self._ui_options["hide_label"] = hide_label
-        if hide_property:
+        if hide_property is not None and "hide_property" not in self._ui_options:
             self._ui_options["hide_property"] = hide_property
         if traits:
             for trait in traits:
@@ -1753,6 +1967,7 @@ class ParameterContainer(Parameter, ABC):
         converters: list[Callable[[Any], Any]] | None = None,
         validators: list[Callable[[Parameter, Any], None]] | None = None,
         *,
+        hide: bool = False,
         settable: bool = True,
         user_defined: bool = False,
         element_id: str | None = None,
@@ -1773,6 +1988,7 @@ class ParameterContainer(Parameter, ABC):
             traits=traits,
             converters=converters,
             validators=validators,
+            hide=hide,
             settable=settable,
             user_defined=user_defined,
             element_id=element_id,
@@ -1821,6 +2037,7 @@ class ParameterList(ParameterContainer):
         converters: list[Callable[[Any], Any]] | None = None,
         validators: list[Callable[[Parameter, Any], None]] | None = None,
         *,
+        hide: bool = False,
         settable: bool = True,
         user_defined: bool = False,
         element_id: str | None = None,
@@ -1860,6 +2077,7 @@ class ParameterList(ParameterContainer):
             traits=traits,
             converters=converters,
             validators=validators,
+            hide=hide,
             settable=settable,
             user_defined=user_defined,
             element_id=element_id,

griptape_nodes/exe_types/flow.py

@@ -81,17 +81,17 @@ class ControlFlow:
     def clear_execution_queue(self) -> None:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
-        GriptapeNodes.FlowManager().clear_execution_queue()
+        GriptapeNodes.FlowManager().clear_execution_queue(self)
 
     def get_connections_on_node(self, node: BaseNode) -> list[BaseNode] | None:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
-        return GriptapeNodes.FlowManager().get_connections_on_node(self, node)
+        return GriptapeNodes.FlowManager().get_connections_on_node(node)
 
     def get_all_connected_nodes(self, node: BaseNode) -> list[BaseNode]:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
-        return GriptapeNodes.FlowManager().get_all_connected_nodes(self, node)
+        return GriptapeNodes.FlowManager().get_all_connected_nodes(node)
 
     def get_node_dependencies(self, node: BaseNode) -> list[BaseNode]:
         """Get all upstream nodes that the given node depends on.