griptape-nodes 0.52.1__py3-none-any.whl → 0.54.0__py3-none-any.whl

griptape_nodes/machines/{node_resolution.py → sequential_resolution.py}

@@ -42,6 +42,14 @@ class ResolutionContext:
         self.focus_stack = []
         self.paused = False
 
+    @property
+    def current_node(self) -> BaseNode:
+        """Get the currently focused node from the focus stack."""
+        if not self.focus_stack:
+            msg = "No node is currently in focus - focus stack is empty"
+            raise RuntimeError(msg)
+        return self.focus_stack[-1].node
+
     def reset(self) -> None:
         if self.focus_stack:
             node = self.focus_stack[-1].node
@@ -55,12 +63,6 @@ class InitializeSpotlightState(State):
     @staticmethod
     async def on_enter(context: ResolutionContext) -> type[State] | None:
         # If the focus stack is empty
-        current_node = context.focus_stack[-1].node
-        GriptapeNodes.EventManager().put_event(
-            ExecutionGriptapeNodeEvent(
-                wrapped_event=ExecutionEvent(payload=CurrentDataNodeEvent(node_name=current_node.name))
-            )
-        )
         if not context.paused:
             return InitializeSpotlightState
         return None
@@ -70,7 +72,7 @@ class InitializeSpotlightState(State):
         # If the focus stack is empty
         if not len(context.focus_stack):
             return CompleteState
-        current_node = context.focus_stack[-1].node
+        current_node = context.current_node
         if current_node.state == NodeResolutionState.UNRESOLVED:
             # Mark all future nodes unresolved.
             # TODO: https://github.com/griptape-ai/griptape-nodes/issues/862
@@ -95,7 +97,7 @@ class InitializeSpotlightState(State):
 class EvaluateParameterState(State):
     @staticmethod
     async def on_enter(context: ResolutionContext) -> type[State] | None:
-        current_node = context.focus_stack[-1].node
+        current_node = context.current_node
         current_parameter = current_node.get_current_parameter()
         if current_parameter is None:
             return ExecuteNodeState
@@ -116,7 +118,7 @@ class EvaluateParameterState(State):
 
     @staticmethod
     async def on_update(context: ResolutionContext) -> type[State] | None:
-        current_node = context.focus_stack[-1].node
+        current_node = context.current_node
         current_parameter = current_node.get_current_parameter()
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
@@ -143,48 +145,6 @@ class EvaluateParameterState(State):
 
 
 class ExecuteNodeState(State):
-    # TODO: https://github.com/griptape-ai/griptape-nodes/issues/864
-    @staticmethod
-    async def clear_parameter_output_values(context: ResolutionContext) -> None:
-        """Clears all parameter output values for the currently focused node in the resolution context.
-
-        This method iterates through each parameter output value stored in the current node,
-        removes it from the node's parameter_output_values dictionary, and publishes an event
-        to notify the system about the parameter value being set to None.
-
-        Args:
-            context (ResolutionContext): The resolution context containing the focus stack
-                with the current node being processed.
-
-        Raises:
-            ValueError: If a parameter name in parameter_output_values doesn't correspond
-                to an actual parameter in the node.
-
-        Note:
-            - Uses a copy of parameter_output_values to safely modify the dictionary during iteration
-            - For each parameter, publishes a ParameterValueUpdateEvent with value=None
-            - Events are wrapped in ExecutionGriptapeNodeEvent before publishing
-        """
-        current_node = context.focus_stack[-1].node
-        for parameter_name in current_node.parameter_output_values.copy():
-            parameter = current_node.get_parameter_by_name(parameter_name)
-            if parameter is None:
-                err = f"Attempted to execute node '{current_node.name}' but could not find parameter '{parameter_name}' that was indicated as having a value."
-                raise ValueError(err)
-            parameter_type = parameter.type
-            if parameter_type is None:
-                parameter_type = ParameterTypeBuiltin.NONE.value
-            payload = ParameterValueUpdateEvent(
-                node_name=current_node.name,
-                parameter_name=parameter_name,
-                data_type=parameter_type,
-                value=None,
-            )
-            GriptapeNodes.EventManager().put_event(
-                ExecutionGriptapeNodeEvent(wrapped_event=ExecutionEvent(payload=payload))
-            )
-        current_node.parameter_output_values.clear()
-
     @staticmethod
     async def collect_values_from_upstream_nodes(context: ResolutionContext) -> None:
         """Collect output values from resolved upstream nodes and pass them to the current node.
@@ -199,7 +159,7 @@ class ExecuteNodeState(State):
         """
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
-        current_node = context.focus_stack[-1].node
+        current_node = context.current_node
         connections = GriptapeNodes.FlowManager().get_connections()
 
         for parameter in current_node.parameters:
@@ -237,14 +197,23 @@ class ExecuteNodeState(State):
 
     @staticmethod
     async def on_enter(context: ResolutionContext) -> type[State] | None:
-        current_node = context.focus_stack[-1].node
+        current_node = context.current_node
 
         # Clear all of the current output values
         # if node is locked, don't clear anything. skip all of this.
+        GriptapeNodes.EventManager().put_event(
+            ExecutionGriptapeNodeEvent(
+                wrapped_event=ExecutionEvent(payload=CurrentDataNodeEvent(node_name=current_node.name))
+            )
+        )
         if current_node.lock:
             return ExecuteNodeState
         await ExecuteNodeState.collect_values_from_upstream_nodes(context)
-        await ExecuteNodeState.clear_parameter_output_values(context)
+
+        # Clear all of the current output values but don't broadcast the clearing.
+        # to avoid any flickering in subscribers (UI).
+        context.current_node.parameter_output_values.silent_clear()
+
         for parameter in current_node.parameters:
             if ParameterTypeBuiltin.CONTROL_TYPE.value.lower() == parameter.output_type:
                 continue
@@ -398,14 +367,17 @@ class CompleteState(State):
         return None
 
 
-class NodeResolutionMachine(FSM[ResolutionContext]):
+class SequentialResolutionMachine(FSM[ResolutionContext]):
     """State machine for resolving node dependencies."""
 
     def __init__(self) -> None:
         resolution_context = ResolutionContext()
         super().__init__(resolution_context)
 
-    async def resolve_node(self, node: BaseNode) -> None:
+    async def resolve_node(self, node: BaseNode | None = None) -> None:
+        if node is None:
+            msg = "SequentialResolutionMachine requires a node to resolve"
+            raise ValueError(msg)
         self._context.focus_stack.append(Focus(node=node))
         await self.start(InitializeSpotlightState)
 
@@ -418,6 +390,7 @@ class NodeResolutionMachine(FSM[ResolutionContext]):
     def is_started(self) -> bool:
         return self._current_state is not None
 
-    def reset_machine(self) -> None:
+    # Unused argument but necessary for parallel_resolution because of futures ending during cancel but not reset.
+    def reset_machine(self, *, cancel: bool = False) -> None:  # noqa: ARG002
         self._context.reset()
         self._current_state = None

griptape_nodes/node_library/library_registry.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from griptape_nodes.utils.metaclasses import SingletonMeta
 
@@ -85,6 +85,9 @@ class Setting(BaseModel):
     category: str  # Name of the category in the config
     contents: dict[str, Any]  # The actual settings content
     description: str | None = None  # Optional description for the setting
+    json_schema: dict[str, Any] | None = Field(
+        default=None, alias="schema"
+    )  # JSON schema for the setting (including enums)
 
 
 class LibrarySchema(BaseModel):
@@ -230,6 +233,36 @@ class LibraryRegistry(metaclass=SingletonMeta):
         # Ask the library to create the node.
         return dest_library.create_node(node_type=node_type, name=name, metadata=metadata)
 
+    @classmethod
+    def get_all_library_schemas(cls) -> dict[str, dict]:
+        """Get schemas from all loaded libraries.
+
+        Returns:
+            Dictionary mapping category names to their JSON Schema dicts
+        """
+        instance = cls()
+        schemas = {}
+
+        # Get explicit schemas from loaded libraries
+        for library in instance._libraries.values():
+            library_data = library.get_library_data()
+            if library_data.settings:
+                for setting in library_data.settings:
+                    if setting.json_schema:
+                        schemas[setting.category] = {
+                            "type": "object",
+                            "properties": setting.json_schema,
+                            "title": setting.description or f"{setting.category.title()} Settings",
+                        }
+                    else:
+                        # Create fallback schema for settings without explicit schemas
+                        schemas[setting.category] = {
+                            "type": "object",
+                            "title": setting.description or f"{setting.category.title()} Settings",
+                        }
+
+        return schemas
+
 
 class Library:
     """A collection of nodes curated by library author.

griptape_nodes/retained_mode/events/app_events.py

@@ -1,4 +1,4 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from griptape_nodes.retained_mode.events.base_events import (
     AppPayload,
@@ -76,6 +76,10 @@ class AppGetSessionResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
 class AppInitializationComplete(AppPayload):
     """Application initialization completed successfully. All subsystems ready."""
 
+    libraries_to_register: list[str] = field(default_factory=list)
+    workflows_to_register: list[str] = field(default_factory=list)
+    models_to_download: list[str] = field(default_factory=list)
+
 
 @dataclass
 @PayloadRegistry.register

griptape_nodes/retained_mode/events/base_events.py

@@ -4,7 +4,7 @@ import json
 import logging
 from abc import ABC, abstractmethod
 from dataclasses import asdict, dataclass, field, is_dataclass
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
 
 from griptape.artifacts import BaseArtifact
 from griptape.mixins.serializable_mixin import SerializableMixin
@@ -20,7 +20,7 @@ if TYPE_CHECKING:
 class ResultDetail:
     """A single detail about an operation result, including logging level and human readable message."""
 
-    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+    level: int
     message: str
 
 
@@ -34,7 +34,7 @@ class ResultDetails:
         self,
         *result_details: ResultDetail,
         message: str | None = None,
-        level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+        level: int | None = None,
         logger: logging.Logger | str | None = "griptape_nodes",
     ):
         """Initialize with ResultDetail objects or create a single one from message/level.
@@ -67,8 +67,8 @@ class ResultDetails:
                     logger = logging.getLogger(logger)
 
                 for detail in self.result_details:
-                    numeric_level = getattr(logging, detail.level)
-                    logger.log(numeric_level, detail.message)
+                    # Handle both string and int levels
+                    logger.log(detail.level, detail.message)
             except Exception:  # noqa: S110
                 # If logging fails for any reason, don't let it break the ResultDetails creation
                 pass
@@ -135,12 +135,12 @@ class SkipTheLineMixin:
 class ResultPayloadSuccess(ResultPayload, ABC):
     """Abstract base class for success result payloads."""
 
-    result_details: ResultDetails | str = "Success"
+    result_details: ResultDetails | str
 
     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")
+            self.result_details = ResultDetails(message=self.result_details, level=logging.DEBUG)
 
     def succeeded(self) -> bool:
         """Returns True as this is a success result.
@@ -156,13 +156,13 @@ class ResultPayloadSuccess(ResultPayload, ABC):
 class ResultPayloadFailure(ResultPayload, ABC):
     """Abstract base class for failure result payloads."""
 
-    result_details: ResultDetails | str = "Failure"
+    result_details: ResultDetails | str
     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")
+            self.result_details = ResultDetails(message=self.result_details, level=logging.ERROR)
 
     def succeeded(self) -> bool:
         """Returns False as this is a failure result.

griptape_nodes/retained_mode/events/config_events.py

@@ -194,3 +194,33 @@ class ResetConfigResultSuccess(ResultPayloadSuccess):
 @PayloadRegistry.register
 class ResetConfigResultFailure(ResultPayloadFailure):
     """Configuration reset failed. Common causes: file system errors, permission issues, initialization errors."""
+
+
+@dataclass
+@PayloadRegistry.register
+class GetConfigSchemaRequest(RequestPayload):
+    """Get the JSON schema for the configuration model.
+
+    Use when: Frontend needs to understand field types, enums, and validation rules
+    for rendering appropriate UI components (dropdowns, text inputs, etc.).
+
+    Results: GetConfigSchemaResultSuccess (with schema) | GetConfigSchemaResultFailure (schema generation error)
+    """
+
+
+@dataclass
+@PayloadRegistry.register
+class GetConfigSchemaResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Configuration schema retrieved successfully.
+
+    Args:
+        schema: The JSON schema for the configuration model
+    """
+
+    schema: dict[str, Any]
+
+
+@dataclass
+@PayloadRegistry.register
+class GetConfigSchemaResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Configuration schema retrieval failed. Common causes: schema generation error, model validation issues."""

griptape_nodes/retained_mode/events/execution_events.py

@@ -227,8 +227,8 @@ class GetFlowStateResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
         resolving_node: Name of the node currently being resolved (if any)
     """
 
-    control_node: str | None
-    resolving_node: str | None
+    control_nodes: list[str] | None
+    resolving_node: list[str] | None
 
 
 @dataclass

griptape_nodes/retained_mode/events/model_events.py

@@ -0,0 +1,296 @@
+from dataclasses import dataclass
+
+from griptape_nodes.retained_mode.events.base_events import (
+    RequestPayload,
+    ResultPayloadFailure,
+    ResultPayloadSuccess,
+    WorkflowNotAlteredMixin,
+)
+from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
+
+
+@dataclass
+@PayloadRegistry.register
+class DownloadModelRequest(RequestPayload):
+    """Download a model from Hugging Face Hub.
+
+    Use when: Downloading models for local inference, caching models for offline use,
+    retrieving specific model versions or files from Hugging Face repositories.
+
+    Args:
+        model_id: Model identifier (e.g., "microsoft/DialoGPT-medium") or full URL to Hugging Face model
+        local_dir: Optional local directory to download the model to (defaults to Hugging Face cache)
+        repo_type: Type of repository ("model", "dataset", or "space"). Defaults to "model"
+        revision: Git revision (branch, tag, or commit hash) to download. Defaults to "main"
+        allow_patterns: List of glob patterns to include when downloading. None means all files
+        ignore_patterns: List of glob patterns to exclude when downloading
+
+    Results: DownloadModelResultSuccess (with local_path) | DownloadModelResultFailure (download error)
+    """
+
+    model_id: str
+    local_dir: str | None = None
+    repo_type: str = "model"
+    revision: str = "main"
+    allow_patterns: list[str] | None = None
+    ignore_patterns: list[str] | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class DownloadModelResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Model download completed successfully.
+
+    Args:
+        model_id: The model ID that was downloaded
+        repo_info: Additional repository information returned from the download
+    """
+
+    model_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DownloadModelResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Model download failed. Common causes: invalid model ID, network error, authentication required, storage full."""
+
+
+@dataclass
+class ModelInfo:
+    """Information about a model."""
+
+    model_id: str
+    local_path: str | None = None
+    size_bytes: int | None = None
+    author: str | None = None
+    downloads: int | None = None
+    likes: int | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+    task: str | None = None
+    library: str | None = None
+    tags: list[str] | None = None
+
+
+@dataclass
+class QueryInfo:
+    """Information about a search query."""
+
+    query: str | None = None
+    task: str | None = None
+    library: str | None = None
+    author: str | None = None
+    tags: list[str] | None = None
+    limit: int = 20
+    sort: str = "downloads"
+    direction: str = "desc"
+
+
+@dataclass
+@PayloadRegistry.register
+class ListModelsRequest(RequestPayload):
+    """List all downloaded models from the local cache.
+
+    Use when: Viewing what models are available locally, checking cache usage,
+    managing local model storage.
+
+    Results: ListModelsResultSuccess (with model list) | ListModelsResultFailure (listing error)
+    """
+
+
+@dataclass
+@PayloadRegistry.register
+class ListModelsResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Model listing completed successfully.
+
+    Args:
+        models: List of model information containing model_id, local_path, size_bytes, etc.
+    """
+
+    models: list[ModelInfo]
+
+
+@dataclass
+@PayloadRegistry.register
+class ListModelsResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Model listing failed. Common causes: cache directory access error, filesystem error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteModelRequest(RequestPayload):
+    """Delete a downloaded model from the local cache.
+
+    Use when: Cleaning up disk space, removing unused models, managing local storage.
+
+    Args:
+        model_id: Model identifier to delete from local cache
+
+    Results: DeleteModelResultSuccess (deletion confirmed) | DeleteModelResultFailure (deletion error)
+    """
+
+    model_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteModelResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Model deletion completed successfully.
+
+    Args:
+        model_id: The model ID that was deleted
+        deleted_path: Local path that was removed
+    """
+
+    model_id: str
+    deleted_path: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteModelResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Model deletion failed. Common causes: model not found, filesystem error, permission denied."""
+
+
+@dataclass
+@PayloadRegistry.register
+class ListModelDownloadsRequest(RequestPayload):
+    """List download status for a specific model or all downloads.
+
+    Use when: Checking progress of ongoing downloads, viewing download history,
+    monitoring download completion.
+
+    Args:
+        model_id: Optional model identifier to get status for. If None, returns all downloads.
+
+    Results: ListModelDownloadsResultSuccess (with status data) | ListModelDownloadsResultFailure (query error)
+    """
+
+    model_id: str | None = None
+
+
+@dataclass
+class ModelDownloadStatus:
+    """Model download status tracking multiple files."""
+
+    model_id: str
+    status: str  # "downloading", "completed", "failed"
+    started_at: str
+    updated_at: str
+    total_files: int | None = None
+    completed_files: int | None = None
+    failed_files: int | None = None
+    # Optional fields for completed downloads
+    completed_at: str | None = None
+    local_path: str | None = None
+    # Optional fields for failed downloads
+    failed_at: str | None = None
+    error_message: str | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class ListModelDownloadsResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Model download status retrieved successfully.
+
+    Args:
+        downloads: List of download status records or single status if model_id was specified
+    """
+
+    downloads: list[ModelDownloadStatus]
+
+
+@dataclass
+@PayloadRegistry.register
+class ListModelDownloadsResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Model download status query failed. Common causes: filesystem error, invalid model ID."""
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteModelDownloadRequest(RequestPayload):
+    """Delete download status tracking records for a model.
+
+    Use when: Cleaning up orphaned download status files, removing tracking data
+    for models that are no longer needed.
+
+    Args:
+        model_id: Model identifier to remove download status for
+
+    Results: DeleteModelDownloadResultSuccess (deletion confirmed) | DeleteModelDownloadResultFailure (deletion error)
+    """
+
+    model_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteModelDownloadResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Model download status deletion completed successfully.
+
+    Args:
+        model_id: The model ID whose download status was deleted
+        deleted_path: Path to the status file that was removed
+    """
+
+    model_id: str
+    deleted_path: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteModelDownloadResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Model download status deletion failed. Common causes: status not found, filesystem error, permission denied."""
+
+
+@dataclass
+@PayloadRegistry.register
+class SearchModelsRequest(RequestPayload):
+    """Search for models on Hugging Face Hub.
+
+    Use when: Finding models by name, filtering models by task or library,
+    discovering available models for specific use cases.
+
+    Args:
+        query: Search query string to match against model names and descriptions
+        task: Filter by task type (e.g., "text-generation", "image-classification")
+        library: Filter by library (e.g., "transformers", "diffusers", "timm")
+        author: Filter by author/organization name
+        tags: List of tags to filter by
+        limit: Maximum number of results to return (default: 20, max: 100)
+        sort: Sort results by "downloads", "likes", "updated", or "created" (default: "downloads")
+        direction: Sort direction "asc" or "desc" (default: "desc")
+
+    Results: SearchModelsResultSuccess (with model list) | SearchModelsResultFailure (search error)
+    """
+
+    query: str | None = None
+    task: str | None = None
+    library: str | None = None
+    author: str | None = None
+    tags: list[str] | None = None
+    limit: int = 20
+    sort: str = "downloads"
+    direction: str = "desc"
+
+
+@dataclass
+@PayloadRegistry.register
+class SearchModelsResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Model search completed successfully.
+
+    Args:
+        models: List of model information containing id, author, downloads, etc.
+        total_results: Total number of models matching the search criteria
+        query_info: Information about the search query parameters used
+    """
+
+    models: list[ModelInfo]
+    total_results: int
+    query_info: QueryInfo
+
+
+@dataclass
+@PayloadRegistry.register
+class SearchModelsResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Model search failed. Common causes: network error, invalid parameters, API limits."""

griptape_nodes/retained_mode/events/node_events.py

@@ -3,6 +3,7 @@ from enum import Enum, auto
 from typing import Any, NamedTuple, NewType
 from uuid import uuid4
 
+from griptape_nodes.exe_types.core_types import NodeMessagePayload
 from griptape_nodes.exe_types.node_types import NodeResolutionState
 from griptape_nodes.node_library.library_registry import LibraryNameAndVersion
 from griptape_nodes.retained_mode.events.base_events import (
@@ -744,7 +745,7 @@ class SendNodeMessageRequest(RequestPayload):
     """
 
     message_type: str
-    message: Any
+    message: NodeMessagePayload | None
     node_name: str | None = None
     optional_element_name: str | None = None
 
@@ -758,7 +759,7 @@ class SendNodeMessageResultSuccess(ResultPayloadSuccess):
         response: Optional response data from the node's message handler
     """
 
-    response: Any = None
+    response: NodeMessagePayload | None = None
 
 
 @dataclass
@@ -773,7 +774,7 @@ class SendNodeMessageResultFailure(ResultPayloadFailure):
         response: Optional response data from the node's message handler (even on failure)
     """
 
-    response: Any = None
+    response: NodeMessagePayload | None = None
 
 
 @dataclass