griptape-nodes 0.41.0__py3-none-any.whl → 0.43.0__py3-none-any.whl

griptape_nodes/retained_mode/retained_mode.py

@@ -32,8 +32,10 @@ from griptape_nodes.retained_mode.events.execution_events import (
 from griptape_nodes.retained_mode.events.flow_events import (
     CreateFlowRequest,
     DeleteFlowRequest,
+    GetFlowMetadataRequest,
     ListFlowsInFlowRequest,
     ListNodesInFlowRequest,
+    SetFlowMetadataRequest,
 )
 from griptape_nodes.retained_mode.events.library_events import (
     GetNodeMetadataFromLibraryRequest,
@@ -1247,6 +1249,48 @@ class RetainedMode:
         request = GetFlowStateRequest(flow_name=flow_name)
         return GriptapeNodes().handle_request(request)
 
+    @classmethod
+    def get_metadata_for_flow(cls, flow_name: str) -> ResultPayload:
+        """Retrieves metadata associated with a flow.
+
+        Flow metadata can include UI position, display name, tags, and other custom properties.
+
+        Args:
+            flow_name (str): Name of the flow to get metadata for.
+
+        Returns:
+            ResultPayload: Contains the flow's metadata.
+
+        Example:
+            # Get flow metadata
+            result = cmd.get_metadata_for_flow("my_flow")
+        """
+        request = GetFlowMetadataRequest(flow_name=flow_name)
+        result = GriptapeNodes().handle_request(request)
+        return result
+
+    @classmethod
+    def set_metadata_for_flow(cls, flow_name: str, metadata: dict[Any, Any]) -> ResultPayload:
+        """Sets metadata for a flow.
+
+        Args:
+            flow_name (str): Name of the flow to set metadata for.
+            metadata (dict): Dictionary containing the metadata to set.
+
+        Returns:
+            ResultPayload: Contains the result of the metadata update operation.
+
+        Example:
+            # Set flow position
+            metadata = {
+                "position": {"x": 100, "y": 200}
+            }
+            result = cmd.set_metadata_for_flow("my_flow", metadata)
+        """
+        request = SetFlowMetadataRequest(flow_name=flow_name, metadata=metadata)
+        result = GriptapeNodes().handle_request(request)
+        return result
+
     # ARBITRARY PYTHON EXECUTION
     @classmethod
     def run_arbitrary_python(cls, python_str: str) -> ResultPayload:

griptape_nodes/retained_mode/utils/engine_identity.py

@@ -1,6 +1,7 @@
-"""Manages engine identity for a single engine per machine.
+"""Manages engine identity for multiple engines per machine.
 
 Handles engine ID, name storage, and generation for unique engine identification.
+Supports multiple engines with selection via GTN_ENGINE_ID environment variable.
 """
 
 import json
@@ -15,9 +16,9 @@ from .name_generator import generate_engine_name
 
 
 class EngineIdentity:
-    """Manages engine identity for a single engine per machine."""
+    """Manages engine identity for multiple engines per machine."""
 
-    _ENGINE_DATA_FILE = "engine.json"
+    _ENGINE_DATA_FILE = "engines.json"
 
     @classmethod
     def _get_engine_data_dir(cls) -> Path:
@@ -30,11 +31,11 @@ class EngineIdentity:
         return cls._get_engine_data_dir() / cls._ENGINE_DATA_FILE
 
     @classmethod
-    def _load_engine_data(cls) -> dict:
-        """Load engine data from storage.
+    def _load_engines_data(cls) -> dict:
+        """Load engines data from storage.
 
         Returns:
-            dict: Engine data including id, name, timestamps
+            dict: Engines data structure with engines array and default_engine_id
         """
         engine_data_file = cls._get_engine_data_file()
 
@@ -42,48 +43,124 @@ class EngineIdentity:
             try:
                 with engine_data_file.open("r") as f:
                     data = json.load(f)
-                    if isinstance(data, dict):
+                    if isinstance(data, dict) and "engines" in data:
                         return data
             except (json.JSONDecodeError, OSError):
-                # If file is corrupted, return empty dict
                 pass
 
-        return {}
+        return {"engines": [], "default_engine_id": None}
 
     @classmethod
-    def _save_engine_data(cls, engine_data: dict) -> None:
-        """Save engine data to storage.
+    def _save_engines_data(cls, engines_data: dict) -> None:
+        """Save engines data to storage.
 
         Args:
-            engine_data: Engine data to save
+            engines_data: Engines data structure to save
         """
         engine_data_dir = cls._get_engine_data_dir()
         engine_data_dir.mkdir(parents=True, exist_ok=True)
 
         engine_data_file = cls._get_engine_data_file()
         with engine_data_file.open("w") as f:
-            json.dump(engine_data, f, indent=2)
+            json.dump(engines_data, f, indent=2)
+
+    @classmethod
+    def _get_selected_engine_id(cls) -> str | None:
+        """Get the selected engine ID from environment variable or default.
+
+        Returns:
+            str | None: The selected engine ID or None if not specified
+        """
+        return os.getenv("GTN_ENGINE_ID")
+
+    @classmethod
+    def _find_engine_by_id(cls, engines_data: dict, engine_id: str) -> dict | None:
+        """Find an engine by ID in the engines data.
+
+        Args:
+            engines_data: The engines data structure
+            engine_id: The engine ID to find
+
+        Returns:
+            dict | None: The engine data if found, None otherwise
+        """
+        for engine in engines_data.get("engines", []):
+            if engine.get("id") == engine_id:
+                return engine
+        return None
 
     @classmethod
     def get_engine_data(cls) -> dict:
-        """Get the engine data, creating default if it doesn't exist.
+        """Get the current engine data, creating default if it doesn't exist.
 
         Returns:
-            dict: The engine data
+            dict: The current engine data
         """
-        engine_data = cls._load_engine_data()
+        engines_data = cls._load_engines_data()
+
+        # Determine which engine to use
+        selected_engine_id = cls._get_selected_engine_id()
 
-        if not engine_data or "id" not in engine_data:
-            # Create default engine data
+        if selected_engine_id:
+            # Use specified engine ID
+            engine_data = cls._find_engine_by_id(engines_data, selected_engine_id)
+            if engine_data:
+                return engine_data
+            # If specified engine not found, create it
+            engine_data = {
+                "id": selected_engine_id,
+                "name": generate_engine_name(),
+                "created_at": datetime.now(tz=UTC).isoformat(),
+            }
+        else:
+            # Use default engine (first one) or create new one
+            if engines_data.get("engines"):
+                default_id = engines_data.get("default_engine_id")
+                if default_id:
+                    engine_data = cls._find_engine_by_id(engines_data, default_id)
+                    if engine_data:
+                        return engine_data
+                # Fall back to first engine
+                return engines_data["engines"][0]
+
+            # Create new engine
             engine_data = {
-                "id": os.getenv("GTN_ENGINE_ID") or str(uuid.uuid4()),
+                "id": str(uuid.uuid4()),
                 "name": generate_engine_name(),
                 "created_at": datetime.now(tz=UTC).isoformat(),
             }
-            cls._save_engine_data(engine_data)
 
+        # Add or update engine in the data structure
+        cls._add_or_update_engine(engine_data)
         return engine_data
 
+    @classmethod
+    def _add_or_update_engine(cls, engine_data: dict) -> None:
+        """Add or update an engine in the engines data structure.
+
+        Args:
+            engine_data: The engine data to add or update
+        """
+        engines_data = cls._load_engines_data()
+
+        # Find existing engine
+        engine_id = engine_data["id"]
+        existing_engine = cls._find_engine_by_id(engines_data, engine_id)
+
+        if existing_engine:
+            # Update existing engine
+            existing_engine.update(engine_data)
+            existing_engine["updated_at"] = datetime.now(tz=UTC).isoformat()
+        else:
+            # Add new engine
+            engines_data.setdefault("engines", []).append(engine_data)
+
+            # Set as default if it's the first engine
+            if not engines_data.get("default_engine_id") and len(engines_data["engines"]) == 1:
+                engines_data["default_engine_id"] = engine_id
+
+        cls._save_engines_data(engines_data)
+
     @classmethod
     def get_engine_id(cls) -> str:
         """Get the engine ID.
@@ -106,20 +183,57 @@ class EngineIdentity:
 
     @classmethod
     def set_engine_name(cls, engine_name: str) -> None:
-        """Set and persist the engine name.
+        """Set and persist the current engine name.
 
         Args:
             engine_name: The new engine name to set
         """
-        engine_data = cls._load_engine_data()
-
-        # Ensure we have basic engine data
-        if not engine_data or "id" not in engine_data:
-            engine_data = cls.get_engine_data()
+        # Get current engine data
+        engine_data = cls.get_engine_data()
 
+        # Update the name
         engine_data["name"] = engine_name
         engine_data["updated_at"] = datetime.now(tz=UTC).isoformat()
-        cls._save_engine_data(engine_data)
+
+        # Save updated engine data
+        cls._add_or_update_engine(engine_data)
+
+    @classmethod
+    def get_all_engines(cls) -> list[dict]:
+        """Get all registered engines.
+
+        Returns:
+            list[dict]: List of all engine data
+        """
+        engines_data = cls._load_engines_data()
+        return engines_data.get("engines", [])
+
+    @classmethod
+    def get_default_engine_id(cls) -> str | None:
+        """Get the default engine ID.
+
+        Returns:
+            str | None: The default engine ID or None if not set
+        """
+        engines_data = cls._load_engines_data()
+        return engines_data.get("default_engine_id")
+
+    @classmethod
+    def set_default_engine_id(cls, engine_id: str) -> None:
+        """Set the default engine ID.
+
+        Args:
+            engine_id: The engine ID to set as default
+        """
+        engines_data = cls._load_engines_data()
+
+        # Verify the engine exists
+        if cls._find_engine_by_id(engines_data, engine_id):
+            engines_data["default_engine_id"] = engine_id
+            cls._save_engines_data(engines_data)
+        else:
+            msg = f"Engine with ID {engine_id} not found"
+            raise ValueError(msg)
 
     @classmethod
     def get_engine_data_file_path(cls) -> Path:

griptape_nodes/traits/file_system_picker.py

@@ -0,0 +1,127 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from griptape_nodes.exe_types.core_types import Parameter, Trait
+
+
+@dataclass(eq=False)
+class FileSystemPicker(Trait):
+    allow_files: bool = False
+    allow_directories: bool = True
+    multiple: bool = False
+    file_types: list[str] = field(default_factory=list)
+    file_extensions: list[str] = field(default_factory=list)
+    exclude_patterns: list[str] = field(default_factory=list)
+    include_patterns: list[str] = field(default_factory=list)
+    max_file_size: int | None = None
+    min_file_size: int | None = None
+    workspace_only: bool = True
+    initial_path: str | None = None
+    element_id: str = field(default_factory=lambda: "FileSystemPicker")
+
+    def __init__(  # noqa: PLR0913
+        self,
+        *,
+        allow_files: bool = False,
+        allow_directories: bool = True,
+        multiple: bool = False,
+        file_types: list[str] | None = None,
+        file_extensions: list[str] | None = None,
+        exclude_patterns: list[str] | None = None,
+        include_patterns: list[str] | None = None,
+        max_file_size: int | None = None,
+        min_file_size: int | None = None,
+        workspace_only: bool = True,
+        initial_path: str | None = None,
+    ) -> None:
+        super().__init__()
+        self.allow_files = allow_files
+        self.allow_directories = allow_directories
+        self.multiple = multiple
+        self.file_types = file_types or []
+        self.file_extensions = file_extensions or []
+        self.exclude_patterns = exclude_patterns or []
+        self.include_patterns = include_patterns or []
+        self.max_file_size = max_file_size
+        self.min_file_size = min_file_size
+        self.workspace_only = workspace_only
+        self.initial_path = initial_path
+
+    @classmethod
+    def get_trait_keys(cls) -> list[str]:
+        return ["fileSystemPicker", "file_picker", "folder_picker"]
+
+    def ui_options_for_trait(self) -> dict[str, Any]:
+        """Generate the fileSystemPicker UI options dictionary."""
+        options: dict[str, Any] = {
+            "allowFiles": self.allow_files,
+            "allowDirectories": self.allow_directories,
+            "multiple": self.multiple,
+            "workspaceOnly": self.workspace_only,
+        }
+
+        # Add file types/extensions
+        if self.file_types:
+            options["fileTypes"] = self.file_types
+        elif self.file_extensions:
+            options["fileExtensions"] = self.file_extensions
+
+        # Add patterns
+        if self.exclude_patterns:
+            options["excludePatterns"] = self.exclude_patterns
+        if self.include_patterns:
+            options["includePatterns"] = self.include_patterns
+
+        # Add size limits
+        if self.max_file_size is not None:
+            options["maxFileSize"] = self.max_file_size
+        if self.min_file_size is not None:
+            options["minFileSize"] = self.min_file_size
+
+        # Add initial path
+        if self.initial_path:
+            options["initialPath"] = self.initial_path
+
+        return {"fileSystemPicker": options}
+
+    def validators_for_trait(self) -> list[Callable[[Parameter, Any], Any]]:
+        """Validate file system picker configuration."""
+
+        def validate(param: Parameter, value: Any) -> None:  # noqa: ARG001
+            # Validate that at least one selection type is enabled
+            if not self.allow_files and not self.allow_directories:
+                msg = "At least one of allow_files or allow_directories must be True"
+                raise ValueError(msg)
+
+            # Validate file size limits
+            if (
+                self.max_file_size is not None
+                and self.min_file_size is not None
+                and self.max_file_size < self.min_file_size
+            ):
+                msg = "max_file_size cannot be less than min_file_size"
+                raise ValueError(msg)
+
+            # Validate that file types/extensions are valid
+            all_file_types = self.file_types + self.file_extensions
+            for file_type in all_file_types:
+                if not file_type.startswith("."):
+                    msg = f"File type '{file_type}' must start with a dot (e.g., '.py')"
+                    raise ValueError(msg)
+
+        return [validate]
+
+    def converters_for_trait(self) -> list[Callable]:
+        """Convert file system picker values if needed."""
+
+        def converter(value: Any) -> Any:
+            # If value is a string and we expect a list, convert it
+            if isinstance(value, str) and self.multiple:
+                return [value] if value else []
+            return value
+
+        return [converter]
+
+
+# These Traits get added to a list on the parameter. When they are added they apply their functions to the parameter.

griptape_nodes/updater/__init__.py

@@ -38,7 +38,7 @@ def _download_and_run_installer() -> None:
     """Runs the update commands for the engine."""
     console.print("[bold green]Updating self...[/bold green]")
     try:
-        subprocess.run(  # noqa: S603
+        subprocess.run(
             ["uv", "tool", "upgrade", "griptape-nodes"],  # noqa: S607
             text=True,
             capture_output=True,
@@ -57,7 +57,7 @@ def _sync_libraries() -> None:
     """Syncs the libraries for the engine."""
     console.print("[bold green]Syncing libraries...[/bold green]")
     try:
-        subprocess.run(  # noqa: S603
+        subprocess.run(
             ["griptape-nodes", "libraries", "sync"],  # noqa: S607
             text=True,
             capture_output=True,

griptape_nodes/utils/image_preview.py

@@ -0,0 +1,128 @@
+"""Image preview utilities for generating thumbnails and previews."""
+
+import base64
+import io
+from pathlib import Path
+
+from PIL import Image
+
+from griptape_nodes.retained_mode.griptape_nodes import logger
+
+
+def create_image_preview(
+    image_path: Path, max_width: int = 512, max_height: int = 512, quality: int = 85, image_format: str = "WEBP"
+) -> str | None:
+    """Create a small preview image from a file path.
+
+    Args:
+        image_path: Path to the image file
+        max_width: Maximum width for the preview
+        max_height: Maximum height for the preview
+        quality: WebP quality (1-100)
+        image_format: Output format (WEBP, JPEG, PNG, etc.)
+
+    Returns:
+        Base64 encoded data URL of the preview, or None if failed
+    """
+    try:
+        # Open and resize the image
+        with Image.open(image_path) as img:
+            # Convert to RGB if necessary (for WebP/JPEG output)
+            if image_format.upper() in ("WEBP", "JPEG") and img.mode in ("RGBA", "LA", "P"):
+                converted_img = img.convert("RGB")
+            else:
+                converted_img = img
+
+            # Calculate new size maintaining aspect ratio
+            converted_img.thumbnail((max_width, max_height), Image.Resampling.LANCZOS)
+
+            # Save to bytes buffer
+            buffer = io.BytesIO()
+            converted_img.save(buffer, format=image_format, quality=quality, optimize=True)
+            buffer.seek(0)
+
+            # Convert to base64
+            image_bytes = buffer.getvalue()
+            base64_data = base64.b64encode(image_bytes).decode("utf-8")
+
+            # Create data URL
+            mime_type = f"image/{image_format.lower()}"
+            data_url = f"data:{mime_type};base64,{base64_data}"
+
+            logger.debug(f"Created preview for {image_path}: {img.size} -> {len(image_bytes)} bytes")
+            return data_url
+
+    except Exception as e:
+        logger.warning(f"Failed to create preview for {image_path}: {e}")
+        return None
+
+
+def create_image_preview_from_bytes(
+    image_bytes: bytes, max_width: int = 512, max_height: int = 512, quality: int = 85, image_format: str = "WEBP"
+) -> str | None:
+    """Create a small preview image from bytes.
+
+    Args:
+        image_bytes: Raw image bytes
+        max_width: Maximum width for the preview
+        max_height: Maximum height for the preview
+        quality: WebP quality (1-100)
+        image_format: Output format (WEBP, JPEG, PNG, etc.)
+
+    Returns:
+        Base64 encoded data URL of the preview, or None if failed
+    """
+    try:
+        # Open image from bytes
+        with Image.open(io.BytesIO(image_bytes)) as img:
+            # Convert to RGB if necessary (for WebP/JPEG output)
+            if image_format.upper() in ("WEBP", "JPEG") and img.mode in ("RGBA", "LA", "P"):
+                converted_img = img.convert("RGB")
+            else:
+                converted_img = img
+
+            # Calculate new size maintaining aspect ratio
+            converted_img.thumbnail((max_width, max_height), Image.Resampling.LANCZOS)
+
+            # Save to bytes buffer
+            buffer = io.BytesIO()
+            converted_img.save(buffer, format=image_format, quality=quality, optimize=True)
+            buffer.seek(0)
+
+            # Convert to base64
+            preview_bytes = buffer.getvalue()
+            base64_data = base64.b64encode(preview_bytes).decode("utf-8")
+
+            # Create data URL
+            mime_type = f"image/{image_format.lower()}"
+            data_url = f"data:{mime_type};base64,{base64_data}"
+
+            logger.debug(f"Created preview from bytes: {len(image_bytes)} -> {len(preview_bytes)} bytes")
+            return data_url
+
+    except Exception as e:
+        logger.warning(f"Failed to create preview from bytes: {e}")
+        return None
+
+
+def get_image_info(image_path: Path) -> dict | None:
+    """Get basic information about an image file.
+
+    Args:
+        image_path: Path to the image file
+
+    Returns:
+        Dictionary with image info (width, height, format, mode), or None if failed
+    """
+    try:
+        with Image.open(image_path) as img:
+            return {
+                "width": img.width,
+                "height": img.height,
+                "format": img.format,
+                "mode": img.mode,
+                "size_bytes": image_path.stat().st_size,
+            }
+    except Exception as e:
+        logger.warning(f"Failed to get image info for {image_path}: {e}")
+        return None

griptape_nodes/version_compatibility/versions/v0_39_0/modified_parameters_set_removal.py

@@ -7,7 +7,7 @@ from griptape_nodes.retained_mode.events.app_events import (
     GetEngineVersionResultSuccess,
 )
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes, Version
-from griptape_nodes.retained_mode.managers.library_manager import LibraryManager
+from griptape_nodes.retained_mode.managers.library_lifecycle.library_status import LibraryStatus
 from griptape_nodes.retained_mode.managers.version_compatibility_manager import (
     LibraryVersionCompatibilityCheck,
     LibraryVersionCompatibilityIssue,
@@ -47,13 +47,13 @@ class ModifiedParametersSetRemovalCheck(LibraryVersionCompatibilityCheck):
                     message=f"This library (built for engine version {library_version_str}) is incompatible with Griptape Nodes 0.39+. "
                     "The 'modified_parameters_set' parameter has been removed from BaseNode methods: 'after_incoming_connection', 'after_outgoing_connection', 'after_incoming_connection_removed', 'after_outgoing_connection_removed', 'before_value_set', and 'after_value_set'. "
                     "If this library overrides any of these methods, it will not load or function properly. Please update to a newer version of this library or contact the library author immediately.",
-                    severity=LibraryManager.LibraryStatus.UNUSABLE,
+                    severity=LibraryStatus.UNUSABLE,
                 ),
                 LibraryVersionCompatibilityIssue(
                     message=f"This library (built for engine version {library_version_str}) is incompatible with Griptape Nodes 0.39+."
                     "The 'ui_options' field has been modified on all Elements. In order to function properly, all nodes must update ui_options by setting its value to a new dictionary. Updating ui_options by accessing the private field _ui_options will no longer create UI updates in the editor."
                     "If this library accesses the private _ui_options field, it will not update the editor properly. Please update to a newer version of this library or contact the library author immediately.",
-                    severity=LibraryManager.LibraryStatus.UNUSABLE,
+                    severity=LibraryStatus.UNUSABLE,
                 ),
             ]
         if current_engine_version >= Version(0, 38, 0):
@@ -63,13 +63,13 @@ class ModifiedParametersSetRemovalCheck(LibraryVersionCompatibilityCheck):
                     message=f"WARNING: The 'modified_parameters_set' parameter will be removed in Griptape Nodes 0.39 from BaseNode methods: 'after_incoming_connection', 'after_outgoing_connection', 'after_incoming_connection_removed', 'after_outgoing_connection_removed', 'before_value_set', and 'after_value_set'. "
                     f"This library (built for engine version {library_version_str}) must be updated before the 0.39 release. "
                     "If this library overrides any of these methods, it will fail to load in 0.39. If not, no action is necessary. Please contact the library author to confirm whether this library is impacted.",
-                    severity=LibraryManager.LibraryStatus.FLAWED,
+                    severity=LibraryStatus.FLAWED,
                 ),
                 LibraryVersionCompatibilityIssue(
                     message="WARNING: The 'ui_options' field has been modified in Griptape Nodes 0.38 on all BaseNodeElements."
                     "In order to function properly, all nodes must update ui_options by setting its value to a new dictionary. Updating ui_options by accessing the private field _ui_options will no longer create UI updates in the editor."
                     "If this library accesses the private _ui_options field, it will not update the editor properly. Please update to a newer version of this library or contact the library author immediately.",
-                    severity=LibraryManager.LibraryStatus.FLAWED,
+                    severity=LibraryStatus.FLAWED,
                 ),
             ]