griptape-nodes 0.46.0__py3-none-any.whl → 0.48.0__py3-none-any.whl

griptape_nodes/app/app.py

@@ -118,7 +118,7 @@ def _ensure_api_key() -> str:
                 "[code]gtn init --api-key <your key>[/code]\n"
                 "[bold red]You can generate a new key from [/bold red][bold blue][link=https://nodes.griptape.ai]https://nodes.griptape.ai[/link][/bold blue]",
             ),
-            title="🔑 ❌ Missing Nodes API Key",
+            title="[red]X[/red] Missing Nodes API Key",
             border_style="red",
             padding=(1, 4),
         )

griptape_nodes/exe_types/core_types.py

@@ -65,25 +65,52 @@ class ParameterType:
         return ret_val
 
     @staticmethod
-    def are_types_compatible(source_type: str | None, target_type: str | None) -> bool:
+    def _extract_base_type(type_str: str) -> str:
+        """Extract the base type from a potentially generic type string.
+
+        Examples:
+            'list[any]' -> 'list'
+            'dict[str, int]' -> 'dict'
+            'str' -> 'str'
+        """
+        bracket_index = type_str.find("[")
+        if bracket_index == -1:
+            return type_str
+        return type_str[:bracket_index]
+
+    @staticmethod
+    def are_types_compatible(source_type: str | None, target_type: str | None) -> bool:  # noqa: PLR0911
         if source_type is None or target_type is None:
             return False
 
-        ret_val = False
         source_type_lower = source_type.lower()
         target_type_lower = target_type.lower()
 
         # If either are None, bail.
         if ParameterTypeBuiltin.NONE.value in (source_type_lower, target_type_lower):
-            ret_val = False
-        elif target_type_lower == ParameterTypeBuiltin.ANY.value:
+            return False
+        if target_type_lower == ParameterTypeBuiltin.ANY.value:
             # If the TARGET accepts Any, we're good. Not always true the other way 'round.
-            ret_val = True
-        else:
-            # Do a compare.
-            ret_val = source_type_lower == target_type_lower
+            return True
 
-        return ret_val
+        # First try exact match
+        if source_type_lower == target_type_lower:
+            return True
+
+        source_base = ParameterType._extract_base_type(source_type_lower)
+        target_base = ParameterType._extract_base_type(target_type_lower)
+
+        # If base types match
+        if source_base == target_base:
+            # Allow any generic to flow to base type (list[any] -> list, list[str] -> list)
+            if target_type_lower == target_base:
+                return True
+
+            # Allow specific types to flow to [any] generic (list[str] -> list[any])
+            if target_type_lower == f"{target_base}[{ParameterTypeBuiltin.ANY.value}]":
+                return True
+
+        return False
 
     @staticmethod
     def parse_kv_type_pair(type_str: str) -> KeyValueTypePair | None:  # noqa: C901
@@ -250,7 +277,6 @@ class BaseNodeElement:
             self._changes["ui_options"] = complete_dict["ui_options"]
 
         event_data.update(self._changes)
-
         # Publish the event
         event = ExecutionGriptapeNodeEvent(
             wrapped_event=ExecutionEvent(payload=AlterElementEvent(element_details=event_data))
@@ -1326,6 +1352,27 @@ class ParameterList(ParameterContainer):
         result = f"list[{base_type}]"
         return result
 
+    def _custom_setter_for_property_type(self, value: str | None) -> None:
+        # If we are setting a type, we need to propagate this to our children as well.
+        for child in self._children:
+            if isinstance(child, Parameter):
+                child.type = value
+        super()._custom_setter_for_property_type(value)
+
+    def _custom_setter_for_property_input_types(self, value: list[str] | None) -> None:
+        # If we are setting a type, we need to propagate this to our children as well.
+        for child in self._children:
+            if isinstance(child, Parameter):
+                child.input_types = value
+        return super()._custom_setter_for_property_input_types(value)
+
+    def _custom_setter_for_property_output_type(self, value: str | None) -> None:
+        # If we are setting a type, we need to propagate this to our children as well.
+        for child in self._children:
+            if isinstance(child, Parameter):
+                child.output_type = value
+        return super()._custom_setter_for_property_output_type(value)
+
     def _custom_getter_for_property_input_types(self) -> list[str]:
         # For every valid input type, also accept a list variant of that for the CONTAINER Parameter only.
         # Children still use the input types given to them.
@@ -1395,6 +1442,78 @@ class ParameterList(ParameterContainer):
 
         return param
 
+    def clear_list(self) -> None:
+        """Remove all children that have been added to the list."""
+        children = self.find_elements_by_type(element_type=Parameter)
+        for child in children:
+            if isinstance(child, Parameter):
+                self.remove_child(child)
+                del child
+
+    # --- Convenience methods for stable list management ---
+    def get_child_parameters(self) -> list[Parameter]:
+        """Return direct child parameters only, in order of appearance."""
+        return self.find_elements_by_type(element_type=Parameter, find_recursively=False)
+
+    def append_child_parameter(self, display_name: str | None = None) -> Parameter:
+        """Append one child parameter and optionally set a display name.
+
+        This preserves existing children and adds a new one at the end.
+        """
+        child = self.add_child_parameter()
+        if display_name is not None:
+            ui_opts = child.ui_options or {}
+            ui_opts["display_name"] = display_name
+            child.ui_options = ui_opts
+        return child
+
+    def remove_last_child_parameter(self) -> None:
+        """Remove the last child parameter if one exists.
+
+        This removes from the end to preserve earlier children and their connections.
+        """
+        children = self.get_child_parameters()
+        if children:
+            last = children[-1]
+            self.remove_child(last)
+            del last
+
+    def ensure_length(self, desired_count: int, display_name_prefix: str | None = None) -> None:
+        """Grow or shrink the list to the desired length while preserving existing items.
+
+        - If increasing, appends new children to the end.
+        - If decreasing, removes children from the end.
+        - Optionally sets display names like "{prefix} 1", "{prefix} 2", ...
+        """
+        if desired_count is None:
+            return
+        try:
+            desired_count = int(desired_count)
+        except Exception:
+            desired_count = 0
+        desired_count = max(desired_count, 0)
+
+        current_children = self.get_child_parameters()
+        current_len = len(current_children)
+
+        # Grow
+        if current_len < desired_count:
+            for index in range(current_len, desired_count):
+                name = f"{display_name_prefix} {index + 1}" if display_name_prefix else None
+                self.append_child_parameter(display_name=name)
+
+        # Shrink
+        elif current_len > desired_count:
+            for _ in range(current_len - desired_count):
+                self.remove_last_child_parameter()
+
+        # Optionally re-apply display names to existing children to keep indices tidy
+        if display_name_prefix:
+            for index, child in enumerate(self.get_child_parameters()):
+                ui_opts = child.ui_options or {}
+                ui_opts["display_name"] = f"{display_name_prefix} {index + 1}"
+                child.ui_options = ui_opts
+
     def add_child(self, child: BaseNodeElement) -> None:
         """Override to mark parent node as unresolved when children are added.
 

griptape_nodes/exe_types/node_types.py

@@ -848,12 +848,12 @@ class BaseNode(ABC):
 
         # Create event data using the parameter's to_event method
         if remove:
+            # Import logger here to avoid circular dependency
             event = ExecutionGriptapeNodeEvent(
                 wrapped_event=ExecutionEvent(payload=RemoveElementEvent(element_id=parameter.element_id))
             )
         else:
             event_data = parameter.to_event(self)
-
             # Publish the event
             event = ExecutionGriptapeNodeEvent(
                 wrapped_event=ExecutionEvent(payload=AlterElementEvent(element_details=event_data))
@@ -1053,11 +1053,17 @@ class EndNode(BaseNode):
 
 
 class StartLoopNode(BaseNode):
-    finished: bool
-    current_index: int
     end_node: EndLoopNode | None = None
     """Creating class for Start Loop Node in order to implement loop functionality in execution."""
 
+    @abstractmethod
+    def is_loop_finished(self) -> bool:
+        """Return True if the loop has finished executing.
+
+        This method must be implemented by subclasses to define when
+        the loop should terminate.
+        """
+
 
 class EndLoopNode(BaseNode):
     start_node: StartLoopNode | None = None

griptape_nodes/machines/node_resolution.py

@@ -225,16 +225,18 @@ class ExecuteNodeState(State):
                 # If the upstream node is resolved, collect its output value
                 if upstream_parameter.name in upstream_node.parameter_output_values:
                     output_value = upstream_node.parameter_output_values[upstream_parameter.name]
+                else:
+                    output_value = upstream_node.get_parameter_value(upstream_parameter.name)
 
-                    # Pass the value through using the same mechanism as normal resolution
-                    GriptapeNodes.get_instance().handle_request(
-                        SetParameterValueRequest(
-                            parameter_name=parameter.name,
-                            node_name=current_node.name,
-                            value=output_value,
-                            data_type=upstream_parameter.output_type,
-                        )
+                # Pass the value through using the same mechanism as normal resolution
+                GriptapeNodes.get_instance().handle_request(
+                    SetParameterValueRequest(
+                        parameter_name=parameter.name,
+                        node_name=current_node.name,
+                        value=output_value,
+                        data_type=upstream_parameter.output_type,
                     )
+                )
 
     @staticmethod
     def on_enter(context: ResolutionContext) -> type[State] | None:

griptape_nodes/mcp_server/ws_request_manager.py

@@ -41,7 +41,7 @@ class WebSocketConnectionManager:
         try:
             message = json.dumps(data)
             await self.websocket.send(message)
-            logger.debug("📤 Sent message: %s", message)
+            logger.debug("Sent message: %s", message)
         except Exception as e:
             logger.error("Failed to send message: %s", e)
             raise
@@ -157,7 +157,7 @@ class AsyncRequestManager(Generic[T]):  # noqa: UP046
 
         except Exception as e:
             self.connection_manager.connected = False
-            logger.error("🔴 WebSocket connection failed: %s", str(e))
+            logger.error("[red]X[/red] WebSocket connection failed: %s", str(e))
             msg = f"Failed to connect to WebSocket: {e!s}"
             raise ConnectionError(msg) from e
 
@@ -192,7 +192,7 @@ class AsyncRequestManager(Generic[T]):  # noqa: UP046
         """Send an event to the API without waiting for a response."""
         from griptape_nodes.app.app import _determine_request_topic
 
-        logger.debug("📝 Creating Event: %s - %s", request_type, json.dumps(payload))
+        logger.debug("Creating Event: %s - %s", request_type, json.dumps(payload))
 
         data = {"event_type": "EventRequest", "request_type": request_type, "request": payload}
         topic = _determine_request_topic()
@@ -231,7 +231,7 @@ class AsyncRequestManager(Generic[T]):  # noqa: UP046
         def success_handler(response: Any, _: Any) -> None:
             if not response_future.done():
                 result = response.get("payload", {}).get("result", "Success")
-                logger.debug("✅ Request succeeded: %s", result)
+                logger.debug("[green]OK[/green] Request succeeded: %s", result)
                 response_future.set_result(result)
 
         def failure_handler(response: Any, _: Any) -> None:
@@ -239,14 +239,14 @@ class AsyncRequestManager(Generic[T]):  # noqa: UP046
                 error = (
                     response.get("payload", {}).get("result", {}).get("exception", "Unknown error") or "Unknown error"
                 )
-                logger.error("❌ Request failed: %s", error)
+                logger.error("[red]X[/red] Request failed: %s", error)
                 response_future.set_exception(Exception(error))
 
         # Generate request ID and subscribe
         request_id = self.connection_manager.subscribe_to_request_event(success_handler, failure_handler)
         payload["request_id"] = request_id
 
-        logger.debug("🚀 Request (%s): %s %s", request_id, request_type, json.dumps(payload))
+        logger.debug("Request (%s): %s %s", request_id, request_type, json.dumps(payload))
 
         try:
             # Send the event

griptape_nodes/retained_mode/events/base_events.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 import json
+import logging
 from abc import ABC, abstractmethod
 from dataclasses import asdict, dataclass, field, is_dataclass
-from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeVar
 
 from griptape.artifacts import BaseArtifact
 from griptape.events import BaseEvent as GtBaseEvent
@@ -16,6 +17,64 @@ if TYPE_CHECKING:
     import builtins
 
 
+@dataclass
+class ResultDetail:
+    """A single detail about an operation result, including logging level and human readable message."""
+
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+    message: str
+
+
+@dataclass
+class ResultDetails:
+    """Container for multiple ResultDetail objects."""
+
+    result_details: list[ResultDetail]
+
+    def __init__(
+        self,
+        *result_details: ResultDetail,
+        message: str | None = None,
+        level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+        logger: logging.Logger | str | None = "griptape_nodes",
+    ):
+        """Initialize with ResultDetail objects or create a single one from message/level.
+
+        Args:
+            *result_details: Variable number of ResultDetail objects
+            message: If provided, creates a single ResultDetail with this message
+            level: Logging level for the single ResultDetail (required if message is provided)
+            logger: Logger to use for auto-logging. String for logger name, Logger object, or None to skip
+        """
+        # Handle single message/level convenience
+        if message is not None:
+            if level is None:
+                err_msg = "level is required when message is provided"
+                raise ValueError(err_msg)
+            if result_details:
+                err_msg = "Cannot provide both result_details and message/level"
+                raise ValueError(err_msg)
+            self.result_details = [ResultDetail(level=level, message=message)]
+        else:
+            if not result_details:
+                err_msg = "ResultDetails requires at least one ResultDetail or message/level"
+                raise ValueError(err_msg)
+            self.result_details = list(result_details)
+
+        # Auto-log if logger is provided
+        if logger is not None:
+            try:
+                if isinstance(logger, str):
+                    logger = logging.getLogger(logger)
+
+                for detail in self.result_details:
+                    numeric_level = getattr(logging, detail.level)
+                    logger.log(numeric_level, detail.message)
+            except Exception:  # noqa: S110
+                # If logging fails for any reason, don't let it break the ResultDetails creation
+                pass
+
+
 # The Payload class is a marker interface
 class Payload(ABC):  # noqa: B024
     """Base class for all payload types. Customers will derive from this."""
@@ -32,6 +91,7 @@ class RequestPayload(Payload, ABC):
 class ResultPayload(Payload, ABC):
     """Base class for all result payloads."""
 
+    result_details: ResultDetails | str
     """When set to True, alerts clients that this result made changes to the workflow state.
     Editors can use this to determine if the workflow is dirty and needs to be re-saved, for example."""
     altered_workflow_state: bool = False
@@ -76,6 +136,13 @@ class SkipTheLineMixin:
 class ResultPayloadSuccess(ResultPayload, ABC):
     """Abstract base class for success result payloads."""
 
+    result_details: ResultDetails | str = "Success"
+
+    def __post_init__(self) -> None:
+        """Initialize success result with INFO level default for strings."""
+        if isinstance(self.result_details, str):
+            self.result_details = ResultDetails(message=self.result_details, level="DEBUG")
+
     def succeeded(self) -> bool:
         """Returns True as this is a success result.
 
@@ -90,8 +157,14 @@ class ResultPayloadSuccess(ResultPayload, ABC):
 class ResultPayloadFailure(ResultPayload, ABC):
     """Abstract base class for failure result payloads."""
 
+    result_details: ResultDetails | str = "Failure"
     exception: Exception | None = None
 
+    def __post_init__(self) -> None:
+        """Initialize failure result with ERROR level default for strings."""
+        if isinstance(self.result_details, str):
+            self.result_details = ResultDetails(message=self.result_details, level="ERROR")
+
     def succeeded(self) -> bool:
         """Returns False as this is a failure result.
 

griptape_nodes/retained_mode/events/secrets_events.py

@@ -20,11 +20,13 @@ class GetSecretValueRequest(RequestPayload):
 
     Args:
         key: Name of the secret key to retrieve
+        should_error_on_not_found: Whether to error if the key is not found (default: True)
 
     Results: GetSecretValueResultSuccess (with value) | GetSecretValueResultFailure (key not found)
     """
 
     key: str
+    should_error_on_not_found: bool = True
 
 
 @dataclass

griptape_nodes/retained_mode/griptape_nodes.py

@@ -389,11 +389,11 @@ class GriptapeNodes(metaclass=SingletonMeta):
                 )
             details = f"Attempted to get engine version. Failed because version string '{engine_ver}' wasn't in expected major.minor.patch format."
             logger.error(details)
-            return GetEngineVersionResultFailure()
+            return GetEngineVersionResultFailure(result_details=details)
         except Exception as err:
             details = f"Attempted to get engine version. Failed due to '{err}'."
             logger.error(details)
-            return GetEngineVersionResultFailure()
+            return GetEngineVersionResultFailure(result_details=details)
 
     def handle_session_start_request(self, request: AppStartSessionRequest) -> ResultPayload:  # noqa: ARG002
         from griptape_nodes.app.app import subscribe_to_topic
@@ -434,7 +434,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
         except Exception as err:
             details = f"Failed to end session due to '{err}'."
             logger.error(details)
-            return AppEndSessionResultFailure()
+            return AppEndSessionResultFailure(result_details=details)
 
     def handle_get_session_request(self, _: AppGetSessionRequest) -> ResultPayload:
         return AppGetSessionResultSuccess(session_id=GriptapeNodes.SessionManager().get_active_session_id())
@@ -447,14 +447,17 @@ class GriptapeNodes(metaclass=SingletonMeta):
         try:
             active_session_id = GriptapeNodes.SessionManager().get_active_session_id()
             if active_session_id is None:
-                logger.warning("Session heartbeat received but no active session found")
-                return SessionHeartbeatResultFailure()
+                details = "Session heartbeat received but no active session found"
+                logger.warning(details)
+                return SessionHeartbeatResultFailure(result_details=details)
 
-            logger.debug("Session heartbeat successful for session: %s", active_session_id)
+            details = f"Session heartbeat successful for session: {active_session_id}"
+            logger.debug(details)
             return SessionHeartbeatResultSuccess()
         except Exception as err:
-            logger.error("Failed to handle session heartbeat: %s", err)
-            return SessionHeartbeatResultFailure()
+            details = f"Failed to handle session heartbeat: {err}"
+            logger.error(details)
+            return SessionHeartbeatResultFailure(result_details=details)
 
     def handle_engine_heartbeat_request(self, request: EngineHeartbeatRequest) -> ResultPayload:
         """Handle engine heartbeat requests.
@@ -483,8 +486,9 @@ class GriptapeNodes(metaclass=SingletonMeta):
                 **workflow_info,
             )
         except Exception as err:
-            logger.error("Failed to handle engine heartbeat: %s", err)
-            return EngineHeartbeatResultFailure(heartbeat_id=request.heartbeat_id)
+            details = f"Failed to handle engine heartbeat: {err}"
+            logger.error(details)
+            return EngineHeartbeatResultFailure(heartbeat_id=request.heartbeat_id, result_details=details)
 
     def handle_get_engine_name_request(self, request: GetEngineNameRequest) -> ResultPayload:  # noqa: ARG002
         """Handle requests to get the current engine name."""
@@ -495,7 +499,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
         except Exception as err:
             error_message = f"Failed to get engine name: {err}"
             logger.error(error_message)
-            return GetEngineNameResultFailure(error_message=error_message)
+            return GetEngineNameResultFailure(error_message=error_message, result_details=error_message)
 
     def handle_set_engine_name_request(self, request: SetEngineNameRequest) -> ResultPayload:
         """Handle requests to set a new engine name."""
@@ -504,7 +508,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
             if not request.engine_name or not request.engine_name.strip():
                 error_message = "Engine name cannot be empty"
                 logger.warning(error_message)
-                return SetEngineNameResultFailure(error_message=error_message)
+                return SetEngineNameResultFailure(error_message=error_message, result_details=error_message)
 
             # Set the new engine name
             GriptapeNodes.EngineIdentityManager().set_engine_name(request.engine_name.strip())
@@ -514,7 +518,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
         except Exception as err:
             error_message = f"Failed to set engine name: {err}"
             logger.error(error_message)
-            return SetEngineNameResultFailure(error_message=error_message)
+            return SetEngineNameResultFailure(error_message=error_message, result_details=error_message)
 
     def _get_instance_info(self) -> dict[str, str | None]:
         """Get instance information from environment variables.

griptape_nodes/retained_mode/managers/agent_manager.py

@@ -204,16 +204,18 @@ class AgentManager:
                         pass  # Ignore incomplete JSON
             if isinstance(last_event, FinishTaskEvent):
                 if isinstance(last_event.task_output, ErrorArtifact):
-                    return RunAgentResultFailure(last_event.task_output.to_dict())
+                    return RunAgentResultFailure(
+                        error=last_event.task_output.to_dict(), result_details=last_event.task_output.to_json()
+                    )
                 if isinstance(last_event.task_output, JsonArtifact):
                     return RunAgentResultSuccess(last_event.task_output.to_dict())
             err_msg = f"Unexpected final event: {last_event}"
             logger.error(err_msg)
-            return RunAgentResultFailure(ErrorArtifact(last_event).to_dict())
+            return RunAgentResultFailure(error=ErrorArtifact(last_event).to_dict(), result_details=err_msg)
         except Exception as e:
             err_msg = f"Error running agent: {e}"
             logger.error(err_msg)
-            return RunAgentResultFailure(ErrorArtifact(e).to_dict())
+            return RunAgentResultFailure(error=ErrorArtifact(e).to_dict(), result_details=err_msg)
 
     def on_handle_configure_agent_request(self, request: ConfigureAgentRequest) -> ResultPayload:
         try:
@@ -224,7 +226,7 @@ class AgentManager:
         except Exception as e:
             details = f"Error configuring agent: {e}"
             logger.error(details)
-            return ConfigureAgentResultFailure()
+            return ConfigureAgentResultFailure(result_details=details)
         return ConfigureAgentResultSuccess()
 
     def on_handle_reset_agent_conversation_memory_request(
@@ -235,7 +237,7 @@ class AgentManager:
         except Exception as e:
             details = f"Error resetting agent conversation memory: {e}"
             logger.error(details)
-            return ResetAgentConversationMemoryResultFailure()
+            return ResetAgentConversationMemoryResultFailure(result_details=details)
         return ResetAgentConversationMemoryResultSuccess()
 
     def on_handle_get_conversation_memory_request(self, _: GetConversationMemoryRequest) -> ResultPayload:
@@ -244,5 +246,5 @@ class AgentManager:
         except Exception as e:
             details = f"Error getting conversation memory: {e}"
             logger.error(details)
-            return GetConversationMemoryResultFailure()
+            return GetConversationMemoryResultFailure(result_details=details)
         return GetConversationMemoryResultSuccess(runs=conversation_memory)

griptape_nodes/retained_mode/managers/arbitrary_code_exec_manager.py

@@ -46,6 +46,6 @@ class ArbitraryCodeExecManager:
             result = RunArbitraryPythonStringResultSuccess(python_output=captured_output)
         except Exception as e:
             python_output = f"ERROR: {e}"
-            result = RunArbitraryPythonStringResultFailure(python_output=python_output)
+            result = RunArbitraryPythonStringResultFailure(python_output=python_output, result_details=python_output)
 
         return result