feat(describe-image): add provider selection and fix image loading

- Add model_provider dropdown (mirrors agent.py pattern) with refresh
  button and dynamic model list via ListAgentProvidersRequest /
  ListProviderModelsRequest; non-GTC providers use GtOpenAiChatPromptDriver
  and forward provider credentials in the agent wrapper
- Fix validate_before_workflow_run: replace buggy driver-param check with
  _uses_griptape_cloud_driver() helper so non-GTC runs aren't blocked
- Flatten nested lists from ParameterList before processing images
- Convert string paths/URLs to ImageUrlArtifact so they're loaded as
  image bytes rather than passed as text to the model

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: shhlife

griptape_nodes_library/image/describe_image.py

@@ -1,23 +1,32 @@
 import json
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from griptape.artifacts import ImageUrlArtifact, ModelArtifact
 from griptape.drivers.prompt.base_prompt_driver import BasePromptDriver
 from griptape.drivers.prompt.griptape_cloud_prompt_driver import GriptapeCloudPromptDriver
+from griptape.drivers.prompt.openai import OpenAiChatPromptDriver as GtOpenAiChatPromptDriver
 from griptape.structures import Structure
 from griptape.tasks import PromptTask
-from griptape_nodes.exe_types.core_types import Parameter, ParameterList, ParameterMode, ParameterType
+from griptape_nodes.exe_types.core_types import (
+    NodeMessageResult,
+    Parameter,
+    ParameterList,
+    ParameterMode,
+    ParameterType,
+)
 from griptape_nodes.exe_types.node_types import AsyncResult, BaseNode, ControlNode
 from griptape_nodes.exe_types.param_components.model_access_component import ModelAccessComponent
 from griptape_nodes.exe_types.param_types.parameter_bool import ParameterBool
 from griptape_nodes.exe_types.param_types.parameter_json import ParameterJson
 from griptape_nodes.exe_types.param_types.parameter_string import ParameterString
 from griptape_nodes.retained_mode.events.connection_events import CreateConnectionRequest, DeleteConnectionRequest
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes, logger
+from griptape_nodes.traits.button import Button, ButtonDetailsMessagePayload
 from griptape_nodes.traits.options import Options
 from json_schema_to_pydantic import create_model  # pyright: ignore[reportMissingImports]
 
 from griptape_nodes_library.agents.griptape_nodes_agent import GriptapeNodesAgent as GtAgent
+from griptape_nodes_library.config.prompt.cloud_models import MODEL_CHOICES_ARGS
 from griptape_nodes_library.utils.agent_utils import (
     build_rulesets_from_configs,
     build_tools,
@@ -28,10 +37,38 @@
 from griptape_nodes_library.utils.error_utils import try_throw_error
 from griptape_nodes_library.utils.image_utils import load_image_from_url_artifact
 
+if TYPE_CHECKING:
+    from griptape_nodes.retained_mode.events.agent_events import (
+        ListAgentProvidersRequest,  # pyright: ignore[reportAttributeAccessIssue]
+        ListAgentProvidersResultSuccess,  # pyright: ignore[reportAttributeAccessIssue]
+        ListProviderModelsRequest,  # pyright: ignore[reportAttributeAccessIssue]
+        ListProviderModelsResultSuccess,  # pyright: ignore[reportAttributeAccessIssue]
+        ProviderConfig,  # pyright: ignore[reportAttributeAccessIssue]
+    )
+
+_AGENT_PROVIDERS_AVAILABLE: bool = False
+_GRIPTAPE_CLOUD_PROVIDER: "ProviderConfig" = cast("ProviderConfig", None)
+
+try:
+    from griptape_nodes.retained_mode.events.agent_events import (
+        ListAgentProvidersRequest,  # pyright: ignore[reportAttributeAccessIssue]
+        ListAgentProvidersResultSuccess,  # pyright: ignore[reportAttributeAccessIssue]
+        ListProviderModelsRequest,  # pyright: ignore[reportAttributeAccessIssue]
+        ListProviderModelsResultSuccess,  # pyright: ignore[reportAttributeAccessIssue]
+        ProviderConfig,  # pyright: ignore[reportAttributeAccessIssue]
+    )
+
+    _AGENT_PROVIDERS_AVAILABLE = True
+    _GRIPTAPE_CLOUD_PROVIDER = ProviderConfig(name="griptape_cloud", type="griptape_cloud", model="")
+except ImportError:
+    pass
+
 SERVICE = "Griptape"
 API_KEY_URL = "https://cloud.griptape.ai/configuration/api-keys"
 API_KEY_ENV_VAR = "GT_CLOUD_API_KEY"
-MODEL_CHOICES = [
+
+# Vision-capable models available on Griptape Cloud.
+GTC_VISION_MODEL_CHOICES = [
     "gpt-5.2",
     "gpt-5.1",
     "gpt-5",
@@ -48,7 +85,7 @@
     "gemini-3.1-pro",
     "gemini-2.5-pro",
 ]
-DEFAULT_MODEL = MODEL_CHOICES[0]
+DEFAULT_MODEL = GTC_VISION_MODEL_CHOICES[0]
 
 
 class DescribeImage(ControlNode):
@@ -65,6 +102,29 @@ def __init__(self, **kwargs) -> None:
                 allowed_modes={ParameterMode.INPUT, ParameterMode.OUTPUT},
             )
         )
+
+        # Provider selector — populated from the engine's configured providers.
+        provider_names = self._fetch_provider_names()
+        self.add_parameter(
+            Parameter(
+                name="model_provider",
+                type="str",
+                default_value=provider_names[0] if provider_names else "griptape_cloud",
+                allowed_modes={ParameterMode.INPUT, ParameterMode.PROPERTY},
+                tooltip="Choose a provider. Refresh to see all configured providers.",
+                traits={
+                    Options(choices=provider_names),
+                    Button(
+                        icon="list-restart",
+                        size="icon",
+                        variant="secondary",
+                        on_click=self._refresh_providers_button,
+                    ),
+                },
+                ui_options={"display_name": "provider"},
+            )
+        )
+
         model_param = Parameter(
             name="model",
             input_types=["str", "Prompt Model Config"],
@@ -82,7 +142,7 @@ def __init__(self, **kwargs) -> None:
         self._model_access = ModelAccessComponent(
             node=self,
             parameter=model_param,
-            model_choices=MODEL_CHOICES,
+            model_choices=GTC_VISION_MODEL_CHOICES,
             default_model=DEFAULT_MODEL,
         )
         self.add_parameter(
@@ -148,6 +208,94 @@ def __init__(self, **kwargs) -> None:
             )
         )
 
+    # --- Provider / model helpers (mirrors agent.py) ---
+
+    def _fetch_providers(self) -> "list[ProviderConfig]":
+        _FALLBACK = [_GRIPTAPE_CLOUD_PROVIDER]
+        try:
+            result = GriptapeNodes.handle_request(ListAgentProvidersRequest())
+            if not isinstance(result, ListAgentProvidersResultSuccess):
+                return _FALLBACK
+            return cast(ListAgentProvidersResultSuccess, result).providers or _FALLBACK
+        except Exception:
+            return _FALLBACK
+
+    def _fetch_provider_names(self) -> list[str]:
+        providers = self._fetch_providers()
+        return [p.name for p in providers] or ["griptape_cloud"]
+
+    def _resolve_provider_api_key(self, provider_config: "ProviderConfig") -> str:
+        secret_name = provider_config.api_key_secret_name or ""
+        if secret_name:
+            return (
+                GriptapeNodes.SecretsManager().get_secret(secret_name, should_error_on_not_found=False) or "not-needed"
+            )
+        return "not-needed"
+
+    def _fetch_models_for_provider(self, provider_name: str) -> list[str]:
+        if not _AGENT_PROVIDERS_AVAILABLE:
+            return GTC_VISION_MODEL_CHOICES
+        try:
+            providers = self._fetch_providers()
+            provider_config = next((p for p in providers if p.name == provider_name), None)
+            if provider_config is None:
+                return GTC_VISION_MODEL_CHOICES
+            result = GriptapeNodes.handle_request(
+                ListProviderModelsRequest(
+                    provider=provider_config.type,
+                    base_url=provider_config.base_url or "",
+                    api_key=self._resolve_provider_api_key(provider_config),
+                )
+            )
+            if isinstance(result, ListProviderModelsResultSuccess):
+                return cast(ListProviderModelsResultSuccess, result).models or GTC_VISION_MODEL_CHOICES
+        except Exception:
+            pass
+        return GTC_VISION_MODEL_CHOICES
+
+    def _update_model_choices_for_provider(self, provider_name: str) -> None:
+        if provider_name == "griptape_cloud":
+            models = GTC_VISION_MODEL_CHOICES
+            new_data = MODEL_CHOICES_ARGS
+        else:
+            models = self._fetch_models_for_provider(provider_name)
+            new_data = [{"name": m, "icon": "", "args": {}} for m in models]
+        default = models[0] if models else DEFAULT_MODEL
+        self._update_option_choices(param="model", choices=models, default=default)
+        param = self.get_parameter_by_name("model")
+        if param:
+            param.update_ui_options_key("data", new_data)
+
+    def _refresh_providers_button(
+        self,
+        button: Button,
+        button_details: ButtonDetailsMessagePayload,  # noqa: ARG002
+    ) -> NodeMessageResult | None:
+        provider_names = self._fetch_provider_names()
+        current = self.get_parameter_value("model_provider") or "griptape_cloud"
+        default = current if current in provider_names else (provider_names[0] if provider_names else "griptape_cloud")
+        self._update_option_choices(param="model_provider", choices=provider_names, default=default)
+        return None
+
+    def _refresh_models_button(
+        self,
+        button: Button,
+        button_details: ButtonDetailsMessagePayload,  # noqa: ARG002
+    ) -> NodeMessageResult | None:
+        provider_name = self.get_parameter_value("model_provider") or "griptape_cloud"
+        self._update_model_choices_for_provider(provider_name)
+        return None
+
+    def _uses_griptape_cloud_driver(self) -> bool:
+        if self.get_parameter_value("agent") is not None:
+            return False
+        if isinstance(self.get_parameter_value("model"), BasePromptDriver):
+            return False
+        provider_name = self.get_parameter_value("model_provider") or "griptape_cloud"
+        return provider_name == "griptape_cloud"
+
+    # --- Connection / UI helpers ---
+
     def _update_output_type_and_validate_connections(self, new_output_type: str) -> None:
         output_param = self.get_parameter_by_name("output")
         if output_param is None:
@@ -238,12 +386,10 @@ def set_parameter_value(
         )
 
     def validate_before_workflow_run(self) -> list[Exception] | None:
-        # TODO: https://github.com/griptape-ai/griptape-nodes/issues/871
         exceptions = []
-        api_key = GriptapeNodes.SecretsManager().get_secret(API_KEY_ENV_VAR)
-        # No need for the api key. These exceptions caught on other nodes.
-        if self.parameter_values.get("agent", None) and self.parameter_values.get("driver", None):
+        if not self._uses_griptape_cloud_driver():
             return None
+        api_key = GriptapeNodes.SecretsManager().get_secret(API_KEY_ENV_VAR)
         if not api_key:
             msg = f"{API_KEY_ENV_VAR} is not defined"
             exceptions.append(KeyError(msg))
@@ -258,6 +404,7 @@ def after_incoming_connection(
     ) -> None:
         if target_parameter.name == "agent":
             self.hide_parameter_by_name("model")
+            self.hide_parameter_by_name("model_provider")
 
         if target_parameter.name == "output_schema":
             self._update_output_type_and_validate_connections("json")
@@ -283,6 +430,7 @@ def after_incoming_connection_removed(
     ) -> None:
         if target_parameter.name == "agent":
             self.show_parameter_by_name("model")
+            self.show_parameter_by_name("model_provider")
         if target_parameter.name == "output_schema":
             self.set_parameter_value("output_schema", None)
             self._update_output_type_and_validate_connections("str")
@@ -309,17 +457,18 @@ def after_value_set(self, parameter: Parameter, value: Any) -> None:
         super().after_value_set(parameter, value)
         if parameter.name == "model":
             self._model_access.on_value_changed(value)
+        elif parameter.name == "model_provider":
+            self._update_model_choices_for_provider(str(value))
 
     def process(self) -> AsyncResult[Structure]:  # noqa: C901, PLR0915, PLR0912
         # Get the parameters from the node
         params = self.parameter_values
         model_input = self.get_parameter_value("model")
+        provider_name = self.get_parameter_value("model_provider") or "griptape_cloud"
 
-        # License-policy runtime gate. Raises RuntimeError if the currently-selected
-        # model is denied, which propagates as an error toast in the workflow.
-        # Bypasses non-string values (e.g. a connected Prompt Model Config driver
-        # carries its own model identity that the helper isn't aware of).
-        self._model_access.raise_if_denied(model_input)
+        # License-policy runtime gate — only enforced for Griptape Cloud models.
+        if provider_name == "griptape_cloud":
+            self._model_access.raise_if_denied(model_input)
 
         agent = None
 
@@ -366,18 +515,14 @@ def process(self) -> AsyncResult[Structure]:  # noqa: C901, PLR0915, PLR0912
                     logger.error(msg)
                     raise
 
-        # If an agent is provided, we'll use and ensure it's using a PromptTask
-        # If a prompt_driver is provided, we'll use that
-        # If neither are provided, we'll create a new one with the selected model.
-        # Otherwise, we'll just use the default model
         tool_configs: list = []
         ruleset_configs: list = []
+        non_gtc_provider_config = None
         agent_value = self.get_parameter_value("agent")
         if isinstance(agent_value, dict):
             agent_core_dict, tool_configs, ruleset_configs = unwrap_agent(agent_value)
             agent = GtAgent().from_dict(agent_core_dict)
             restore_provider_driver(agent, agent_value)
-            # Rebuild tools and rulesets from configs so they're fresh for this run.
             if tool_configs:
                 live_tools, _ = build_tools(tool_configs)
                 if live_tools and agent.tasks:
@@ -391,6 +536,19 @@ def process(self) -> AsyncResult[Structure]:  # noqa: C901, PLR0915, PLR0912
                 agent.tasks[0].output_schema = pydantic_schema
         elif isinstance(model_input, BasePromptDriver):
             agent = GtAgent(prompt_driver=model_input, output_schema=pydantic_schema)
+        elif provider_name != "griptape_cloud":
+            providers = self._fetch_providers()
+            non_gtc_provider_config = next((p for p in providers if p.name == provider_name), None)
+            if non_gtc_provider_config is not None:
+                prompt_driver = GtOpenAiChatPromptDriver(
+                    model=model_input if isinstance(model_input, str) else DEFAULT_MODEL,
+                    base_url=non_gtc_provider_config.base_url or "",
+                    api_key=self._resolve_provider_api_key(non_gtc_provider_config),
+                    stream=True,
+                )
+            else:
+                prompt_driver = default_prompt_driver
+            agent = GtAgent(prompt_driver=prompt_driver, output_schema=pydantic_schema)
         elif isinstance(model_input, str):
             if model_input not in self._model_access.model_choices:
                 model_input = DEFAULT_MODEL
@@ -401,7 +559,6 @@ def process(self) -> AsyncResult[Structure]:  # noqa: C901, PLR0915, PLR0912
             )
             agent = GtAgent(prompt_driver=prompt_driver, output_schema=pydantic_schema)
         else:
-            # If the agent is not provided, we'll create a new one with a default prompt driver
             agent = GtAgent(prompt_driver=default_prompt_driver, output_schema=pydantic_schema)
 
         prompt = params.get("prompt", "")
@@ -412,17 +569,32 @@ def process(self) -> AsyncResult[Structure]:  # noqa: C901, PLR0915, PLR0912
         if get_description_only:
             prompt += "\n\nOutput image description only."
 
-        image_artifacts = [
-            load_image_from_url_artifact(img) if isinstance(img, ImageUrlArtifact) else img
-            for img in (self.get_parameter_value("images") or [])
-            if img is not None
-        ]
+        # Flatten nested lists — a ParameterList child may receive a list of artifacts
+        # when connected to an output that produces List[ImageUrlArtifact].
+        raw_images = self.get_parameter_value("images") or []
+        flat_images: list = []
+        for img in raw_images:
+            if isinstance(img, list):
+                flat_images.extend(img)
+            else:
+                flat_images.append(img)
+
+        image_artifacts = []
+        for img in flat_images:
+            if img is None:
+                continue
+            if isinstance(img, ImageUrlArtifact):
+                image_artifacts.append(load_image_from_url_artifact(img))
+            elif isinstance(img, str) and img.strip():
+                # String path or URL — load as image bytes rather than passing as text.
+                image_artifacts.append(load_image_from_url_artifact(ImageUrlArtifact(img)))
+            else:
+                image_artifacts.append(img)
 
         if not image_artifacts:
             self.parameter_output_values["output"] = "No image provided"
             return
 
-        # Run the agent
         yield lambda: agent.run([prompt, *image_artifacts])
         agent_output = agent.output
         output_value = agent_output.value
@@ -431,7 +603,8 @@ def process(self) -> AsyncResult[Structure]:  # noqa: C901, PLR0915, PLR0912
 
         self.parameter_output_values["output"] = output_value
 
-        # Insert a false memory to prevent the base64
+        # Replace the run's image bytes with text — without this, those bytes get serialized
+        # into conversation history and resent on every downstream API call.
         memory_output = output_value
         if isinstance(memory_output, (dict, list)):
             memory_output = json.dumps(memory_output, ensure_ascii=False)
@@ -441,9 +614,20 @@ def process(self) -> AsyncResult[Structure]:  # noqa: C901, PLR0915, PLR0912
         # Clear live tools before serializing, then wrap with configs for downstream nodes.
         if agent.tasks:
             cast(PromptTask, agent.tasks[0]).tools = []
+
+        # For non-GTC providers, include provider info so downstream nodes can restore the driver.
+        incoming_provider = agent_value.get("provider") if isinstance(agent_value, dict) else None
+        provider_info = None
+        if non_gtc_provider_config is not None:
+            provider_info = {
+                "name": provider_name,
+                "base_url": non_gtc_provider_config.base_url or "",
+                "api_key": self._resolve_provider_api_key(non_gtc_provider_config),
+            }
+
         self.parameter_output_values["agent"] = wrap_agent(
             agent.to_dict(),
             tool_configs,
             ruleset_configs,
-            provider=agent_value.get("provider") if isinstance(agent_value, dict) else None,
+            provider=provider_info or incoming_provider,
         )