griptape-nodes 0.70.1__py3-none-any.whl → 0.72.0__py3-none-any.whl

griptape_nodes/drivers/storage/local_storage_driver.py

@@ -6,8 +6,9 @@ from urllib.parse import urljoin
 import httpx
 
 from griptape_nodes.drivers.storage.base_storage_driver import BaseStorageDriver, CreateSignedUploadUrlResponse
-from griptape_nodes.retained_mode.events.os_events import ExistingFilePolicy, WriteFileRequest
+from griptape_nodes.retained_mode.events.os_events import ExistingFilePolicy, WriteFileRequest, WriteFileResultSuccess
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+from griptape_nodes.utils import resolve_workspace_path
 
 logger = logging.getLogger("griptape_nodes")
 
@@ -44,7 +45,7 @@ class LocalStorageDriver(BaseStorageDriver):
         self, path: Path, existing_file_policy: ExistingFilePolicy = ExistingFilePolicy.OVERWRITE
     ) -> CreateSignedUploadUrlResponse:
         # on_write_file_request seems to work most reliably with an absolute path.
-        absolute_path = path if path.is_absolute() else self.workspace_directory / path
+        absolute_path = resolve_workspace_path(path, self.workspace_directory)
 
         # Always delegate to OSManager for file path resolution and policy handling.
         # Creating an empty file before the upload url gives us a chance to claim ownership
@@ -94,9 +95,55 @@ class LocalStorageDriver(BaseStorageDriver):
             "file_path": str(resolved_path),
         }
 
+    def save_file(
+        self, path: Path, file_content: bytes, existing_file_policy: ExistingFilePolicy = ExistingFilePolicy.OVERWRITE
+    ) -> str:
+        """Save a file to local storage by writing directly to disk.
+
+        Args:
+            path: The path of the file to save.
+            file_content: The file content as bytes.
+            existing_file_policy: How to handle existing files. Defaults to OVERWRITE.
+
+        Returns:
+            The absolute file path where the file was saved.
+
+        Raises:
+            FileExistsError: When existing_file_policy is FAIL and file already exists.
+            RuntimeError: If file write fails.
+        """
+        absolute_path = resolve_workspace_path(path, self.workspace_directory)
+
+        result = GriptapeNodes.OSManager().on_write_file_request(
+            WriteFileRequest(
+                file_path=str(absolute_path),
+                content=file_content,
+                existing_file_policy=existing_file_policy,
+            )
+        )
+
+        if not isinstance(result, WriteFileResultSuccess):
+            msg = f"Failed to write file {path}: {result.result_details}"
+            raise ValueError(msg)  # noqa: TRY004
+
+        return result.final_file_path
+
     def create_signed_download_url(self, path: Path) -> str:
-        # The base_url already includes the /static path, so just append the path
-        url = f"{self.base_url}/{path.as_posix()}"
+        # Resolve path, treating relative paths as workspace-relative
+        absolute_path = resolve_workspace_path(path, self.workspace_directory)
+
+        # Automatically determine if the file is external to the workspace
+        try:
+            workspace_relative_path = absolute_path.relative_to(self.workspace_directory.resolve())
+            # Internal files: use workspace-relative path
+            url = f"{self.base_url}/{workspace_relative_path.as_posix()}"
+        except ValueError:
+            # For external files, use /external path and strip leading slash from absolute path
+            path_str = str(absolute_path).removeprefix("/")
+            # Build URL with /external prefix, replacing the /workspace part of base_url
+            base_without_workspace = self.base_url.rsplit("/workspace", 1)[0]
+            url = f"{base_without_workspace}/external/{path_str}"
+
         # Add a cache-busting query parameter to the URL so that the browser always reloads the file
         cache_busted_url = f"{url}?t={int(time.time())}"
         return cache_busted_url
@@ -137,3 +184,17 @@ class LocalStorageDriver(BaseStorageDriver):
 
         response_data = response.json()
         return response_data.get("files", [])
+
+    def get_asset_url(self, path: Path) -> str:
+        """Get the permanent URL for a local asset.
+
+        Returns the absolute file path.
+
+        Args:
+            path: The path of the file
+
+        Returns:
+            Absolute file path as a string
+        """
+        absolute_path = resolve_workspace_path(path, self.workspace_directory)
+        return str(absolute_path)

griptape_nodes/drivers/thread_storage/local_thread_storage_driver.py

@@ -117,6 +117,7 @@ class LocalThreadStorageDriver(BaseThreadStorageDriver):
             msg = f"Cannot delete thread {thread_id}. Archive it first."
             raise ValueError(msg)
 
+        # TODO: Replace with DeleteFileRequest https://github.com/griptape-ai/griptape-nodes/issues/3765
         thread_file.unlink()
 
     def thread_exists(self, thread_id: str) -> bool:

griptape_nodes/exe_types/base_iterative_nodes.py

@@ -139,7 +139,7 @@ class BaseIterativeStartNode(BaseNode):
                 allowed_modes={ParameterMode.PROPERTY, ParameterMode.OUTPUT},
                 settable=False,
                 default_value=0,
-                ui_options={"hide_property": True},
+                hide_property=True,
             )
         self.add_node_element(group)
 

griptape_nodes/exe_types/node_groups/base_node_group.py

@@ -80,6 +80,9 @@ class BaseNodeGroup(BaseNode):
             if node.name in self.nodes:
                 del self.nodes[node.name]
 
+        node_names_in_group = set(self.nodes.keys())
+        self.metadata["node_names_in_group"] = list(node_names_in_group)
+
     def _add_nodes_to_group_dict(self, nodes: list[BaseNode]) -> None:
         """Add nodes to the group's node dictionary."""
         for node in nodes:

griptape_nodes/exe_types/node_groups/subflow_node_group.py

@@ -16,6 +16,7 @@ from griptape_nodes.exe_types.node_types import (
     LOCAL_EXECUTION,
     get_library_names_with_publish_handlers,
 )
+from griptape_nodes.exe_types.param_components.subflow_execution_component import SubflowExecutionComponent
 from griptape_nodes.retained_mode.events.connection_events import (
     CreateConnectionRequest,
     DeleteConnectionRequest,
@@ -84,6 +85,9 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
         # Add parameters from registered StartFlow nodes for each publishing library
         self._add_start_flow_parameters()
 
+        # Add subprocess execution status component for real-time GUI updates
+        self._add_subflow_execution_parameters()
+
     def _create_subflow(self) -> None:
         """Create a dedicated subflow for this NodeGroup's nodes.
 
@@ -144,6 +148,11 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
         for library_name, handler in event_handlers.items():
             self._process_library_start_flow_parameters(library_name, handler)
 
+    def _add_subflow_execution_parameters(self) -> None:
+        """Add parameters for subflow execution tracking."""
+        self._subflow_execution_component = SubflowExecutionComponent(self)
+        self._subflow_execution_component.add_output_parameters()
+
     def _process_library_start_flow_parameters(self, library_name: str, handler: Any) -> None:
         """Process and add StartFlow parameters from a single library.
 
@@ -649,6 +658,10 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
         self._cleanup_proxy_parameter(target_parameter, metadata_key)
         return super().after_incoming_connection_removed(source_node, source_parameter, target_parameter)
 
+    def after_value_set(self, parameter: Parameter, value: Any) -> None:
+        super().after_value_set(parameter, value)
+        self.subflow_execution_component.after_value_set(parameter, value)
+
     def add_nodes_to_group(self, nodes: list[BaseNode]) -> None:
         """Add nodes to the group and track their connections.
 
@@ -1004,3 +1017,8 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
         self.remove_nodes_from_group(nodes_to_remove)
         subflow_name = self.metadata.get("subflow_name")
         return subflow_name
+
+    @property
+    def subflow_execution_component(self) -> SubflowExecutionComponent:
+        """Get the subflow execution component for real-time status updates."""
+        return self._subflow_execution_component

griptape_nodes/exe_types/node_types.py

@@ -48,6 +48,7 @@ logger = logging.getLogger("griptape_nodes")
 T = TypeVar("T")
 
 NODE_GROUP_FLOW = "NodeGroupFlow"
+NODE_DEFAULT_SIZE = {"width": 400, "height": 320}
 
 
 class TransformedParameterValue(NamedTuple):
@@ -830,6 +831,18 @@ class BaseNode(ABC):
                         emit_change=False,
                     )
 
+    def set_initial_node_size(
+        self, width: int = NODE_DEFAULT_SIZE["width"], height: int = NODE_DEFAULT_SIZE["height"]
+    ) -> None:
+        """Set the node's UI size. Node authors can call this to give the node a default or custom size.
+
+        Args:
+            width: Width in pixels.
+            height: Height in pixels.
+        """
+        if "size" not in self.metadata:
+            self.metadata["size"] = {"width": width, "height": height}
+
     def kill_parameter_children(self, parameter: Parameter) -> None:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 

griptape_nodes/exe_types/param_components/log_parameter.py

@@ -4,6 +4,7 @@ import sys
 import time
 from collections.abc import Callable, Iterator
 from types import TracebackType
+from typing import Self
 
 from griptape_nodes.exe_types.core_types import Parameter, ParameterMode
 from griptape_nodes.exe_types.node_types import BaseNode
@@ -69,10 +70,9 @@ class StdoutCapture:
         self._original_stdout.flush()
 
     def isatty(self) -> bool:
-        # Return False to prevent libraries from outputting ANSI color codes
-        return False
+        return self._original_stdout.isatty()
 
-    def __enter__(self) -> "StdoutCapture":
+    def __enter__(self) -> Self:
         sys.stdout = self
         return self
 
@@ -101,7 +101,7 @@ class LoggerCapture:
         self.target_level = level
         self._handler = CallbackHandler(callback)
 
-    def __enter__(self) -> "LoggerCapture":
+    def __enter__(self) -> Self:
         self.original_level = self.logger.level
         self.logger.setLevel(self.target_level)
         self.logger.addHandler(self._handler)

griptape_nodes/exe_types/param_components/subflow_execution_component.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from griptape_nodes.exe_types.core_types import NodeMessageResult, Parameter, ParameterMode
+from griptape_nodes.exe_types.node_types import LOCAL_EXECUTION, PRIVATE_EXECUTION
+from griptape_nodes.retained_mode.events.base_events import (
+    EventResultSuccess,
+    ExecutionEvent,
+)
+from griptape_nodes.retained_mode.events.execution_events import (
+    ControlFlowCancelledEvent,
+    ControlFlowResolvedEvent,
+    GriptapeEvent,
+    NodeFinishProcessEvent,
+    NodeResolvedEvent,
+    NodeStartProcessEvent,
+)
+from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
+from griptape_nodes.retained_mode.events.workflow_events import (
+    PublishWorkflowProgressEvent,
+    PublishWorkflowRequest,
+    PublishWorkflowResultFailure,
+    PublishWorkflowResultSuccess,
+)
+from griptape_nodes.traits.button import Button, ButtonDetailsMessagePayload, OnClickMessageResultPayload
+
+if TYPE_CHECKING:
+    from griptape_nodes.exe_types.node_types import BaseNode
+
+logger = logging.getLogger(__name__)
+
+
+class SubflowExecutionComponent:
+    """A reusable component for managing subprocess execution event parameters.
+
+    This component creates and manages parameters that display
+    real-time events from subprocess execution in the GUI.
+    """
+
+    def __init__(self, node: BaseNode) -> None:
+        """Initialize the SubflowExecutionComponent.
+
+        Args:
+            node: The node instance that will own the parameter
+        """
+        self._node = node
+
+    def add_output_parameters(self) -> None:
+        """Add the parameters to the node."""
+        self._node.add_parameter(
+            Parameter(
+                name="publishing_progress",
+                output_type="float",
+                allowed_modes={ParameterMode.PROPERTY},
+                tooltip="Progress bar showing workflow publishing completion (0.0 to 1.0)",
+                ui_options={"progress_bar": True},
+                settable=False,
+                hide=True,
+            )
+        )
+        self._node.add_parameter(
+            Parameter(
+                name="publishing_target_link",
+                output_type="str",
+                tooltip="Click the button to open the published workflow location",
+                hide=True,
+                allowed_modes={ParameterMode.PROPERTY},
+                traits={
+                    Button(
+                        icon="link",
+                        on_click=self._handle_get_publishing_target_link,
+                        tooltip="Open publishing target link",
+                        state="normal",
+                    ),
+                },
+                ui_options={"placeholder_text": "Link will appear after publishing"},
+            )
+        )
+        self._node.add_parameter(
+            Parameter(
+                name="execution_events",
+                output_type="str",
+                allowed_modes={ParameterMode.PROPERTY},
+                tooltip="Real-time events from subprocess execution",
+                ui_options={"multiline": True},
+            )
+        )
+        if "execution_panel" not in self._node.metadata:
+            self._node.metadata["execution_panel"] = {"params": []}
+        self._node.metadata["execution_panel"]["params"].append("execution_events")
+        self._node.metadata["execution_panel"]["params"].append("publishing_progress")
+        self._node.metadata["execution_panel"]["params"].append("publishing_target_link")
+
+    def _handle_get_publishing_target_link(
+        self,
+        button: Button,  # noqa: ARG002
+        button_details: ButtonDetailsMessagePayload,
+    ) -> NodeMessageResult | None:
+        publishing_target_link = self._node.get_parameter_value("publishing_target_link")
+        if publishing_target_link:
+            return NodeMessageResult(
+                success=True,
+                details="Publishing target link retrieved successfully.",
+                response=OnClickMessageResultPayload(
+                    button_details=button_details,
+                    href=publishing_target_link,
+                ),
+                altered_workflow_state=False,
+            )
+        return None
+
+    def clear_execution_state(self) -> None:
+        """Clear the component state."""
+        self.reset_publishing_progress()
+        self.clear_events()
+        self.clear_publishing_target_link()
+
+    def clear_events(self) -> None:
+        """Clear events at start of execution."""
+        self._node.publish_update_to_parameter("execution_events", "")
+
+    def clear_publishing_target_link(self) -> None:
+        """Clear the publishing target link parameter."""
+        self._node.set_parameter_value("publishing_target_link", None)
+
+    def append_event(self, event_str: str) -> None:
+        """Append a stringified event to the parameter.
+
+        Args:
+            event_str: The event string to append
+        """
+        self._node.append_value_to_parameter("execution_events", event_str + "\n")
+
+    def after_value_set(self, parameter: Parameter, value: Any) -> None:
+        """Handle actions after a parameter value is set.
+
+        Args:
+            parameter: The parameter that was set
+            value: The new value of the parameter
+        """
+        if parameter.name == "execution_environment":
+            if value in {LOCAL_EXECUTION, PRIVATE_EXECUTION}:
+                self._node.hide_parameter_by_name("publishing_progress")
+                self._node.hide_parameter_by_name("publishing_target_link")
+            else:
+                self._node.show_parameter_by_name("publishing_progress")
+
+        if parameter.name == "publishing_target_link":
+            if value and self._node.get_parameter_value("execution_environment") not in {
+                LOCAL_EXECUTION,
+                PRIVATE_EXECUTION,
+            }:
+                self._node.show_parameter_by_name("publishing_target_link")
+            else:
+                self._node.hide_parameter_by_name("publishing_target_link")
+
+    def reset_publishing_progress(self) -> None:
+        """Reset the publishing progress bar to 0."""
+        self._node.publish_update_to_parameter("publishing_progress", 0.0)
+
+    def _parse_execution_event(self, event: dict) -> ExecutionEvent | None:
+        """Parse an execution event dictionary into an ExecutionEvent object.
+
+        Args:
+            event: The event dictionary containing the execution event data.
+                   Expected to have type="execution_event" and a payload with payload_type.
+
+        Returns:
+            The parsed ExecutionEvent if successful, None if the event cannot be parsed
+            (wrong type, unknown payload type, etc.)
+        """
+        event_type = event.get("type", "unknown")
+        if event_type != "execution_event":
+            return None
+
+        payload = event.get("payload", {})
+        payload_type_name = payload.get("payload_type", "")
+        payload_type = PayloadRegistry.get_type(payload_type_name)
+
+        if payload_type is None:
+            logger.debug("Unknown payload type: %s", payload_type_name)
+            return None
+
+        return ExecutionEvent.from_dict(data=payload, payload_type=payload_type)
+
+    def handle_publishing_event(self, event: dict) -> None:
+        """Handle events from SubprocessWorkflowPublisher.
+
+        Processes publishing events and updates the GUI with relevant information.
+        Handles PublishWorkflowProgressEvent for progress bar updates, and
+        PublishWorkflowResultSuccess/Failure for completion status.
+
+        Args:
+            event: The event dictionary from the subprocess publisher
+        """
+        event_type = event.get("type", "unknown")
+
+        # Handle result events (success/failure)
+        if event_type in ("success_result", "failure_result"):
+            self._handle_publishing_result_event(event)
+            return
+
+        # Handle execution events (progress updates)
+        ex_event = self._parse_execution_event(event)
+        if ex_event is None:
+            return
+
+        if isinstance(ex_event.payload, PublishWorkflowProgressEvent):
+            # Update progress bar (convert from 0-100 to 0.0-1.0)
+            progress_value = min(1.0, max(0.0, ex_event.payload.progress / 100.0))
+            self._node.publish_update_to_parameter("publishing_progress", progress_value)
+
+            # Also append a user-friendly message if provided
+            if ex_event.payload.message:
+                self.append_event(f"Publishing: {ex_event.payload.message} ({ex_event.payload.progress:.0f}%)")
+
+    def _handle_publishing_result_event(self, event: dict) -> None:
+        """Handle publishing result events (success/failure).
+
+        Args:
+            event: The event dictionary containing the result
+        """
+        payload = event.get("payload", {})
+        result_type_name = payload.get("result_type", "")
+        result_payload_type = PayloadRegistry.get_type(result_type_name)
+
+        if result_payload_type is None:
+            logger.debug("Unknown result type: %s", result_type_name)
+            return
+
+        result_data = payload.get("result", {})
+
+        if result_payload_type == PublishWorkflowResultSuccess:
+            event_result = EventResultSuccess.from_dict(
+                data=payload, req_payload_type=PublishWorkflowRequest, res_payload_type=PublishWorkflowResultSuccess
+            )
+            if isinstance(event_result.result, PublishWorkflowResultSuccess):
+                publish_workflow_result_success = event_result.result
+                target_link = (
+                    publish_workflow_result_success.metadata.get("publish_target_link")
+                    if publish_workflow_result_success.metadata
+                    else None
+                )
+                if target_link:
+                    self._node.set_parameter_value("publishing_target_link", target_link)
+
+        elif result_payload_type == PublishWorkflowResultFailure:
+            result_details = result_data.get("result_details", "Unknown error")
+            self.append_event(f"Publishing failed: {result_details}")
+
+    def handle_execution_event(self, event: dict) -> None:
+        """Handle events from SubprocessWorkflowExecutor.
+
+        Processes execution events and updates the GUI with relevant information.
+        Filters to only display relevant events with formatted messages.
+
+        Args:
+            event: The event dictionary from the subprocess executor
+        """
+        ex_event = self._parse_execution_event(event)
+
+        if ex_event is None:
+            return
+
+        formatted_message = self._format_execution_event(ex_event)
+        if formatted_message is not None:
+            self.append_event(formatted_message)
+
+    def _format_execution_event(self, ex_event: ExecutionEvent) -> str | None:
+        """Format an execution event into a user-friendly message.
+
+        Args:
+            ex_event: The parsed ExecutionEvent
+
+        Returns:
+            A formatted string message, or None if the event should be filtered out
+        """
+        payload = ex_event.payload
+        payload_type = type(payload)
+
+        # Map payload types to their formatting functions
+        formatters = {
+            NodeStartProcessEvent: self._format_node_start_process,
+            NodeFinishProcessEvent: self._format_node_finish_process,
+            NodeResolvedEvent: self._format_node_resolved,
+            ControlFlowResolvedEvent: self._format_control_flow_resolved,
+            ControlFlowCancelledEvent: self._format_control_flow_cancelled,
+            GriptapeEvent: self._format_griptape_event,
+        }
+
+        formatter = formatters.get(payload_type)
+        if formatter is None:
+            # Filter out other event types
+            return None
+
+        return formatter(payload)
+
+    def _format_node_start_process(self, payload: NodeStartProcessEvent) -> str:
+        """Format a NodeStartProcessEvent."""
+        return f"Starting: {payload.node_name}"
+
+    def _format_node_finish_process(self, payload: NodeFinishProcessEvent) -> str:
+        """Format a NodeFinishProcessEvent."""
+        return f"Finished: {payload.node_name}"
+
+    def _format_node_resolved(self, payload: NodeResolvedEvent) -> str:
+        """Format a NodeResolvedEvent."""
+        return f"Resolved: {payload.node_name}"
+
+    def _format_control_flow_resolved(self, payload: ControlFlowResolvedEvent) -> str:
+        """Format a ControlFlowResolvedEvent."""
+        return f"Flow completed: {payload.end_node_name}"
+
+    def _format_control_flow_cancelled(self, payload: ControlFlowCancelledEvent) -> str:
+        """Format a ControlFlowCancelledEvent."""
+        details = payload.result_details or "Unknown error"
+        return f"Flow cancelled: {details}"
+
+    def _format_griptape_event(self, payload: GriptapeEvent) -> str | None:
+        """Format a GriptapeEvent (progress event).
+
+        Only formats events for the 'result_details' parameter, filtering out others.
+        """
+        if payload.parameter_name != "result_details":
+            return None
+
+        return f"{payload.node_name}: {payload.value}"

griptape_nodes/exe_types/param_types/parameter_audio.py

@@ -4,6 +4,7 @@ from collections.abc import Callable
 from typing import Any
 
 from griptape_nodes.exe_types.core_types import Parameter, ParameterMode, Trait
+from griptape_nodes.utils.artifact_normalization import normalize_artifact_input
 
 
 class ParameterAudio(Parameter):
@@ -24,7 +25,7 @@ class ParameterAudio(Parameter):
         param.pulse_on_run = True  # Change UI options at runtime
     """
 
-    def __init__(  # noqa: PLR0913
+    def __init__(  # noqa: C901, PLR0913
         self,
         name: str,
         tooltip: str | None = None,
@@ -122,6 +123,20 @@ class ParameterAudio(Parameter):
         else:
             final_input_types = ["AudioUrlArtifact"]
 
+        # Add automatic converter to normalize string inputs to AudioUrlArtifact
+        # This allows ParameterAudio to automatically handle file paths and localhost URLs
+        audio_converters = list(converters) if converters else []
+        if accept_any:
+            # Create a converter function that uses normalize_artifact_input with AudioUrlArtifact
+            def _normalize_audio(value: Any) -> Any:
+                try:
+                    from griptape.artifacts import AudioUrlArtifact
+                except ImportError:
+                    return value
+                return normalize_artifact_input(value, AudioUrlArtifact)
+
+            audio_converters.insert(0, _normalize_audio)
+
         # Call parent with explicit parameters, following ControlParameter pattern
         super().__init__(
             name=name,
@@ -135,7 +150,7 @@ class ParameterAudio(Parameter):
             tooltip_as_output=tooltip_as_output,
             allowed_modes=allowed_modes,
             traits=traits,
-            converters=converters,
+            converters=audio_converters,
             validators=validators,
             ui_options=ui_options,
             hide=hide,

griptape_nodes/exe_types/param_types/parameter_float.py

@@ -43,8 +43,8 @@ class ParameterFloat(ParameterNumber):
         ui_options: dict | None = None,
         step: float | None = None,
         slider: bool = False,
-        min_val: float = 0,
-        max_val: float = 100,
+        min_val: float | None = None,
+        max_val: float | None = None,
         validate_min_max: bool = False,
         accept_any: bool = True,
         hide: bool | None = None,
@@ -77,8 +77,8 @@ class ParameterFloat(ParameterNumber):
             ui_options: Dictionary of UI options
             step: Step size for numeric input controls
             slider: Whether to use slider trait
-            min_val: Minimum value for constraints
-            max_val: Maximum value for constraints
+            min_val: Minimum value for constraints (None to disable constraints)
+            max_val: Maximum value for constraints (None to disable constraints)
             validate_min_max: Whether to validate min/max with error
             accept_any: Whether to accept any input type and convert to float (default: True)
             hide: Whether to hide the entire parameter

griptape_nodes/exe_types/param_types/parameter_image.py

@@ -3,7 +3,10 @@
 from collections.abc import Callable
 from typing import Any
 
+from griptape.artifacts import ImageArtifact, ImageUrlArtifact
+
 from griptape_nodes.exe_types.core_types import Parameter, ParameterMode, Trait
+from griptape_nodes.utils.artifact_normalization import normalize_artifact_input
 
 
 class ParameterImage(Parameter):
@@ -122,6 +125,16 @@ class ParameterImage(Parameter):
         else:
             final_input_types = ["ImageUrlArtifact"]
 
+        # Add automatic converter to normalize string inputs to ImageUrlArtifact
+        # This allows ParameterImage to automatically handle file paths and localhost URLs
+        image_converters = list(converters) if converters else []
+        if accept_any:
+            # Create a converter function that uses normalize_artifact_input with ImageUrlArtifact
+            def _normalize_image(value: Any) -> Any:
+                return normalize_artifact_input(value, ImageUrlArtifact, accepted_types=(ImageArtifact,))
+
+            image_converters.insert(0, _normalize_image)
+
         # Call parent with explicit parameters, following ControlParameter pattern
         super().__init__(
             name=name,
@@ -135,7 +148,7 @@ class ParameterImage(Parameter):
             tooltip_as_output=tooltip_as_output,
             allowed_modes=allowed_modes,
             traits=traits,
-            converters=converters,
+            converters=image_converters,
             validators=validators,
             ui_options=ui_options,
             hide=hide,