griptape-nodes 0.67.0__tar.gz → 0.68.0__tar.gz

{griptape_nodes-0.67.0 → griptape_nodes-0.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: griptape-nodes
-Version: 0.67.0
+Version: 0.68.0
 Summary: Add your description here
 Requires-Dist: griptape>=1.8.12
 Requires-Dist: pydantic>=2.10.6

{griptape_nodes-0.67.0 → griptape_nodes-0.68.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "griptape-nodes"
-version = "0.67.0"
+version = "0.68.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12.0, <3.13"

{griptape_nodes-0.67.0 → griptape_nodes-0.68.0}/src/griptape_nodes/bootstrap/utils/python_subprocess_executor.py

@@ -2,16 +2,24 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import os
 import sys
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from pathlib import Path
-    from subprocess import _ENV
 
 logger = logging.getLogger(__name__)
 
 
+def _create_subprocess_env(extra_env: dict[str, str] | None = None) -> dict[str, str]:
+    """Create environment for subprocess, inheriting parent env with optional overrides."""
+    env = os.environ.copy()
+    if extra_env:
+        env.update(extra_env)
+    return env
+
+
 class PythonSubprocessExecutorError(Exception):
     """Exception raised during Python subprocess execution."""
 
@@ -22,7 +30,11 @@ class PythonSubprocessExecutor:
         self._is_running = False
 
     async def execute_python_script(
-        self, script_path: Path, args: list[str] | None = None, cwd: Path | None = None, env: _ENV | None = None
+        self,
+        script_path: Path,
+        args: list[str] | None = None,
+        cwd: Path | None = None,
+        env: dict[str, str] | None = None,
     ) -> None:
         """Execute a Python script in a subprocess and wait for completion.
 
@@ -30,7 +42,7 @@ class PythonSubprocessExecutor:
             script_path: Path to the Python script to execute
             args: Additional command line arguments
             cwd: Working directory for the subprocess
-            env: Environment variables for the subprocess
+            env: Extra environment variables to add or override in the subprocess
         """
         if self.is_running():
             logger.warning("Another subprocess is already running. Terminating it first.")
@@ -38,6 +50,7 @@ class PythonSubprocessExecutor:
 
         args = args or []
         command = [sys.executable, str(script_path), *args]
+        subprocess_env = _create_subprocess_env(env)
 
         try:
             logger.info("Starting subprocess: %s", " ".join(command))
@@ -46,7 +59,7 @@ class PythonSubprocessExecutor:
             self._process = await asyncio.create_subprocess_exec(
                 *command,
                 cwd=cwd,
-                env=env,
+                env=subprocess_env,
                 stdout=asyncio.subprocess.PIPE,
                 stderr=asyncio.subprocess.PIPE,
             )

{griptape_nodes-0.67.0 → griptape_nodes-0.68.0}/src/griptape_nodes/common/node_executor.py

@@ -5,6 +5,7 @@ import asyncio
 import logging
 import pickle
 from dataclasses import dataclass
+from enum import StrEnum
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, NamedTuple
 
@@ -16,7 +17,7 @@ from griptape_nodes.exe_types.base_iterative_nodes import (
     BaseIterativeStartNode,
 )
 from griptape_nodes.exe_types.core_types import ParameterTypeBuiltin
-from griptape_nodes.exe_types.node_groups import BaseIterativeNodeGroup, SubflowNodeGroup
+from griptape_nodes.exe_types.node_groups import BaseIterativeNodeGroup, IterationControlParam, SubflowNodeGroup
 from griptape_nodes.exe_types.node_types import (
     CONTROL_INPUT_PARAMETER,
     LOCAL_EXECUTION,
@@ -106,6 +107,15 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("griptape_nodes")
 
+
+class IterationControlAction(StrEnum):
+    """Enum for iterative group control actions."""
+
+    ADD = "add"  # Normal path - add result to list
+    SKIP = "skip"  # Skip this iteration, don't add result
+    BREAK = "break"  # Break out of loop immediately
+
+
 LOOP_EVENTS_TO_SUPPRESS = {
     CreateFlowResultSuccess,
     CreateFlowResultFailure,
@@ -816,13 +826,153 @@ class NodeExecutor:
         # Check if it's the break signal
         return next_control_output == deserialized_end_node.break_loop_signal_output
 
-    async def _execute_loop_iterations_sequentially(  # noqa: PLR0915
+    def _get_iteration_control_action_for_group(
+        self,
+        end_loop_node: BaseIterativeNodeGroup,
+        node_name_mappings: dict[str, str],
+    ) -> IterationControlAction:
+        """Determine which control action was taken during iteration for an iterative group.
+
+        Checks if any internal nodes have executed their control outputs that connect to the
+        group's control parameters (loop_complete, skip_iteration, break_loop). This is done by
+        checking the source node's parameter_output_values for CONTROL_INPUT_PARAMETER.
+
+        Args:
+            end_loop_node: The BaseIterativeNodeGroup being executed
+            node_name_mappings: Mapping from original to deserialized node names
+
+        Returns:
+            IterationControlAction indicating which control path was taken
+        """
+        # Get incoming connections to the end_loop_node (the iterative group)
+        list_connections_request = ListConnectionsForNodeRequest(node_name=end_loop_node.name)
+        list_connections_result = GriptapeNodes.handle_request(list_connections_request)
+        if not isinstance(list_connections_result, ListConnectionsForNodeResultSuccess):
+            logger.warning("Failed to list connections for node %s", end_loop_node.name)
+            return IterationControlAction.ADD
+
+        incoming_connections = list_connections_result.incoming_connections
+
+        # Check each control parameter to see if its source node has fired
+        # Priority: BREAK > SKIP > LOOP_COMPLETE > default ADD
+        break_source = self._find_source_for_control_param(incoming_connections, IterationControlParam.BREAK_LOOP)
+        skip_source = self._find_source_for_control_param(incoming_connections, IterationControlParam.SKIP_ITERATION)
+        loop_complete_source = self._find_source_for_control_param(
+            incoming_connections, IterationControlParam.LOOP_COMPLETE
+        )
+
+        # Check if break was triggered
+        if self._check_control_source_fired(break_source, node_name_mappings):
+            return IterationControlAction.BREAK
+
+        # Check if skip was triggered
+        if self._check_control_source_fired(skip_source, node_name_mappings):
+            return IterationControlAction.SKIP
+
+        # Check if loop_complete was triggered
+        if self._check_control_source_fired(loop_complete_source, node_name_mappings):
+            return IterationControlAction.ADD
+
+        # If none of the control parameters were triggered, default to ADD
+        # This preserves backward compatibility for workflows without explicit loop_complete connections
+        return IterationControlAction.ADD
+
+    def _check_control_source_fired(
+        self,
+        source: tuple[str, str] | None,
+        node_name_mappings: dict[str, str],
+    ) -> bool:
+        """Check if a control source node has fired its control output.
+
+        Args:
+            source: Tuple of (source_node_name, source_parameter_name) or None
+            node_name_mappings: Mapping from original to deserialized node names
+
+        Returns:
+            True if the source node's next control output matches the specified parameter
+        """
+        if source is None:
+            return False
+
+        source_node_name, source_param_name = source
+        deserialized_source_name = node_name_mappings.get(source_node_name)
+        if deserialized_source_name is None:
+            return False
+
+        node_manager = GriptapeNodes.NodeManager()
+        try:
+            deserialized_source_node = node_manager.get_node_by_name(deserialized_source_name)
+        except ValueError:
+            return False
+
+        if deserialized_source_node is None:
+            return False
+
+        # Check if the node's next control output matches the source parameter
+        next_control_output = deserialized_source_node.get_next_control_output()
+        if next_control_output is None:
+            return False
+
+        # Get the parameter object to compare
+        source_param = deserialized_source_node.get_parameter_by_name(source_param_name)
+        return next_control_output == source_param
+
+    def _find_source_for_control_param(
+        self,
+        incoming_connections: list,
+        control_param_name: str,
+    ) -> tuple[str, str] | None:
+        """Find the source node and parameter that connects to a control parameter on the iterative group.
+
+        Args:
+            incoming_connections: List of incoming connections to the iterative group
+            control_param_name: Name of the control parameter to find (e.g., "break_loop")
+
+        Returns:
+            Tuple of (source_node_name, source_parameter_name), or None if not found
+        """
+        flow_manager = GriptapeNodes.FlowManager()
+        connections = flow_manager.get_connections()
+
+        for conn in incoming_connections:
+            if conn.target_parameter_name != control_param_name:
+                continue
+
+            source_node_name = conn.source_node_name
+            source_param_name = conn.source_parameter_name
+
+            # If source is a SubflowNodeGroup, follow the internal connection to get the actual source
+            node_manager = GriptapeNodes.NodeManager()
+            try:
+                source_node = node_manager.get_node_by_name(source_node_name)
+            except ValueError:
+                continue
+
+            if isinstance(source_node, SubflowNodeGroup):
+                # Get connections to this proxy parameter to find the actual internal source
+                proxy_param = source_node.get_parameter_by_name(source_param_name)
+                if proxy_param:
+                    internal_connections = connections.get_all_incoming_connections(source_node)
+                    for internal_conn in internal_connections:
+                        if (
+                            internal_conn.target_parameter.name == source_param_name
+                            and internal_conn.is_node_group_internal
+                        ):
+                            source_node_name = internal_conn.source_node.name
+                            source_param_name = internal_conn.source_parameter.name
+                            break
+
+            return (source_node_name, source_param_name)
+
+        return None
+
+    async def _execute_loop_iterations_sequentially(  # noqa: PLR0915, C901, PLR0912
         self,
         package_result: PackageNodesAsSerializedFlowResultSuccess,
         total_iterations: int,
         parameter_values_per_iteration: dict[int, dict[str, Any]],
         end_loop_node: BaseIterativeEndNode | BaseIterativeNodeGroup,
-    ) -> tuple[dict[int, Any], list[int], dict[str, Any]]:
+    ) -> tuple[dict[int, Any], list[int], dict[str, Any], int, bool]:
         """Execute loop iterations sequentially by running one flow instance N times.
 
         Args:
@@ -834,8 +984,10 @@ class NodeExecutor:
         Returns:
             Tuple of:
             - iteration_results: Dict mapping iteration_index -> result value
-            - successful_iterations: List of iteration indices that succeeded
+            - successful_iterations: List of iteration indices that executed without error
             - last_iteration_values: Dict mapping parameter names -> values from last iteration
+            - skipped_count: Number of iterations that were skipped via skip control signal
+            - break_occurred: True if the loop exited early due to a break signal
         """
         # Deserialize flow once
         context_manager = GriptapeNodes.ContextManager()
@@ -868,6 +1020,8 @@ class NodeExecutor:
 
         iteration_results: dict[int, Any] = {}
         successful_iterations: list[int] = []
+        skipped_count = 0
+        break_occurred = False
 
         # Build reverse mapping: packaged_name → original_name for event translation
         reverse_node_mapping = {
@@ -927,6 +1081,39 @@ class NodeExecutor:
 
                 successful_iterations.append(iteration_index)
 
+                # For BaseIterativeNodeGroup, check control action to handle skip/break
+                if isinstance(end_loop_node, BaseIterativeNodeGroup):
+                    control_action = self._get_iteration_control_action_for_group(end_loop_node, node_name_mappings)
+
+                    if control_action == IterationControlAction.SKIP:
+                        logger.info(
+                            "Skip detected at iteration %d/%d - skipping result collection",
+                            iteration_index + 1,
+                            total_iterations,
+                        )
+                        skipped_count += 1
+                        continue
+
+                    if control_action == IterationControlAction.BREAK:
+                        logger.info(
+                            "Break detected at iteration %d/%d - collecting result then stopping",
+                            iteration_index + 1,
+                            total_iterations,
+                        )
+                        # Extract result from this iteration before breaking
+                        # (the work was done, so we should collect the result)
+                        deserialized_flows = [(iteration_index, flow_name, node_name_mappings)]
+                        single_iteration_results = self.get_parameter_values_from_iterations(
+                            end_loop_node=end_loop_node,
+                            deserialized_flows=deserialized_flows,
+                            package_flow_result_success=package_result,
+                        )
+                        iteration_results.update(single_iteration_results)
+                        break_occurred = True
+                        break
+
+                    # control_action == ADD: fall through to extract result
+
                 # Extract result from this iteration
                 deserialized_flows = [(iteration_index, flow_name, node_name_mappings)]
                 single_iteration_results = self.get_parameter_values_from_iterations(
@@ -938,13 +1125,14 @@ class NodeExecutor:
 
                 logger.info("Completed sequential iteration %d/%d", iteration_index + 1, total_iterations)
 
-                # Check if the end node signaled a break
+                # Check if the end node signaled a break (for BaseIterativeEndNode)
                 if self._should_break_loop(node_name_mappings, package_result):
                     logger.info(
                         "Loop break detected at iteration %d/%d - stopping execution early",
                         iteration_index + 1,
                         total_iterations,
                     )
+                    break_occurred = True
                     break
 
             # Extract last iteration values from the last successful iteration
@@ -956,7 +1144,7 @@ class NodeExecutor:
                 total_iterations=len(successful_iterations),
             )
 
-            return iteration_results, successful_iterations, last_iteration_values
+            return iteration_results, successful_iterations, last_iteration_values, skipped_count, break_occurred
 
         finally:
             # Cleanup - delete the flow
@@ -1018,6 +1206,8 @@ class NodeExecutor:
                 iteration_results,
                 successful_iterations,
                 last_iteration_values,
+                _skipped_count,
+                _break_occurred,
             ) = await self._execute_loop_iterations_sequentially(
                 package_result=package_result,
                 total_iterations=total_iterations,
@@ -1383,12 +1573,16 @@ class NodeExecutor:
         parameter_values_per_iteration = self._get_merged_parameter_values_for_iterative_group(node, package_result)
 
         # Execute iterations sequentially based on execution environment
+        skipped_count = 0
+        break_occurred = False
         match execution_type:
             case node_types.LOCAL_EXECUTION:
                 (
                     iteration_results,
                     successful_iterations,
                     last_iteration_values,
+                    skipped_count,
+                    break_occurred,
                 ) = await self._execute_loop_iterations_sequentially(
                     package_result=package_result,
                     total_iterations=total_iterations,
@@ -1420,19 +1614,25 @@ class NodeExecutor:
                     execution_type=execution_type,
                 )
 
-        # Check if execution stopped early due to break (not failure)
+        # Check if execution stopped early
         if len(successful_iterations) < total_iterations:
-            expected_count = len(successful_iterations)
-            actual_count = len(iteration_results)
-            if expected_count != actual_count:
-                failed_count = expected_count - actual_count
-                msg = f"Iterative group execution failed: {failed_count} of {expected_count} iterations failed"
-                raise RuntimeError(msg)
-            logger.info(
-                "Iterative group execution stopped early at %d of %d iterations (break signal)",
-                len(successful_iterations),
-                total_iterations,
-            )
+            if break_occurred:
+                # Early exit due to break signal - this is expected behavior
+                logger.info(
+                    "Iterative group execution stopped early at %d of %d iterations (break signal)",
+                    len(successful_iterations),
+                    total_iterations,
+                )
+            else:
+                # Early exit not due to break - check for failures
+                # successful_iterations includes skipped iterations, but iteration_results does not
+                # So we need to account for skipped iterations when checking for failures
+                expected_result_count = len(successful_iterations) - skipped_count
+                actual_result_count = len(iteration_results)
+                if expected_result_count != actual_result_count:
+                    failed_count = expected_result_count - actual_result_count
+                    msg = f"Iterative group execution failed: {failed_count} of {len(successful_iterations)} iterations failed"
+                    raise RuntimeError(msg)
 
         # Build results list in iteration order
         node._results_list = []

griptape_nodes-0.68.0/src/griptape_nodes/exe_types/node_groups/__init__.py

@@ -0,0 +1,7 @@
+"""Node group implementations for managing collections of nodes."""
+
+from .base_iterative_node_group import BaseIterativeNodeGroup, IterationControlParam
+from .base_node_group import BaseNodeGroup
+from .subflow_node_group import SubflowNodeGroup
+
+__all__ = ["BaseIterativeNodeGroup", "BaseNodeGroup", "IterationControlParam", "SubflowNodeGroup"]

{griptape_nodes-0.67.0 → griptape_nodes-0.68.0}/src/griptape_nodes/exe_types/node_groups/base_iterative_node_group.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 from abc import abstractmethod
+from enum import StrEnum
 from typing import Any
 
 from griptape_nodes.exe_types.core_types import (
+    ControlParameterInput,
     Parameter,
     ParameterMode,
     ParameterTypeBuiltin,
@@ -23,6 +25,14 @@ EXECUTION_MODE_VALUE_LOOKUP = {
 }
 
 
+class IterationControlParam(StrEnum):
+    """Parameter names for iteration control on iterative node groups."""
+
+    LOOP_COMPLETE = "loop_complete"
+    SKIP_ITERATION = "skip_iteration"
+    BREAK_LOOP = "break_loop"
+
+
 class BaseIterativeNodeGroup(SubflowNodeGroup):
     """Base class for iterative node groups (ForEach, ForLoop, etc.).
 
@@ -100,7 +110,15 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
             self.metadata["left_parameters"] = []
         self.metadata["left_parameters"].append("index")
 
-        # Results collection parameters (right side - collects from group)
+        # Control input for loop completion (right side - primary loop completion path)
+        self.loop_complete = ControlParameterInput(
+            tooltip="Signal that this iteration is complete and continue to next iteration",
+            name=IterationControlParam.LOOP_COMPLETE.value,
+        )
+        self.loop_complete.ui_options = {"display_name": "Loop Complete"}
+        self.add_parameter(self.loop_complete)
+
+        # Data parameter for the item to add (right side - collects from group)
         self.new_item_to_add = Parameter(
             name="new_item_to_add",
             tooltip="Item to add to results list for each iteration",
@@ -109,6 +127,21 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
         )
         self.add_parameter(self.new_item_to_add)
 
+        # Skip and Break control inputs (right side - for loop control)
+        self.skip_iteration = ControlParameterInput(
+            tooltip="Skip current item and continue to next iteration",
+            name=IterationControlParam.SKIP_ITERATION.value,
+        )
+        self.skip_iteration.ui_options = {"display_name": "Skip to Next Iteration"}
+        self.add_parameter(self.skip_iteration)
+
+        self.break_loop = ControlParameterInput(
+            tooltip="Break out of loop immediately",
+            name=IterationControlParam.BREAK_LOOP.value,
+        )
+        self.break_loop.ui_options = {"display_name": "Break Out of Loop"}
+        self.add_parameter(self.break_loop)
+
         self.results = Parameter(
             name="results",
             tooltip="Collected results from all iterations",
@@ -120,7 +153,15 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
         # Track right parameters for UI layout
         if "right_parameters" not in self.metadata:
             self.metadata["right_parameters"] = []
-        self.metadata["right_parameters"].extend(["new_item_to_add", "results"])
+        self.metadata["right_parameters"].extend(
+            [
+                IterationControlParam.LOOP_COMPLETE.value,
+                "new_item_to_add",
+                IterationControlParam.SKIP_ITERATION.value,
+                IterationControlParam.BREAK_LOOP.value,
+                "results",
+            ]
+        )
 
     def after_value_set(self, parameter: Parameter, value: Any) -> None:
         """Handle parameter value changes."""
@@ -130,6 +171,17 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
             run_in_order = EXECUTION_MODE_VALUE_LOOKUP.get(value, True)
             self.set_parameter_value("run_in_order", run_in_order)
 
+            # Hide or show skip/break controls based on execution mode
+            # Skip and Break are only supported in sequential mode (run_in_order=True)
+            if run_in_order:
+                # Show controls when running sequentially
+                self.show_parameter_by_name(self.skip_iteration.name)
+                self.show_parameter_by_name(self.break_loop.name)
+            else:
+                # Hide controls when running in parallel (not supported)
+                self.hide_parameter_by_name(self.skip_iteration.name)
+                self.hide_parameter_by_name(self.break_loop.name)
+
     @abstractmethod
     def _get_iteration_items(self) -> list[Any]:
         """Get the list of items to iterate over.

griptape_nodes-0.68.0/src/griptape_nodes/exe_types/param_components/huggingface/huggingface_repo_variant_parameter.py

@@ -0,0 +1,152 @@
+"""HuggingFace parameter class that supports repo + variant/subfolder selection."""
+
+import logging
+from pathlib import Path
+
+from huggingface_hub.constants import HF_HUB_CACHE
+
+from griptape_nodes.exe_types.node_types import BaseNode
+from griptape_nodes.exe_types.param_components.huggingface.huggingface_model_parameter import HuggingFaceModelParameter
+
+logger = logging.getLogger("griptape_nodes")
+
+
+def _get_repo_cache_path(repo_id: str) -> Path | None:
+    """Get the cache path for a repo if it exists."""
+    cache_path = Path(HF_HUB_CACHE)
+    if not cache_path.exists():
+        return None
+
+    # Convert repo_id to cache folder format: owner/repo -> models--owner--repo
+    folder_name = f"models--{repo_id.replace('/', '--')}"
+    repo_path = cache_path / folder_name
+
+    if repo_path.exists():
+        return repo_path
+    return None
+
+
+def _get_snapshot_path(repo_path: Path) -> Path | None:
+    """Get the latest snapshot path for a repo."""
+    snapshots_dir = repo_path / "snapshots"
+    if not snapshots_dir.exists():
+        return None
+
+    snapshots = [p for p in snapshots_dir.iterdir() if p.is_dir()]
+    if not snapshots:
+        return None
+
+    # Return the most recent snapshot
+    return max(snapshots, key=lambda p: p.stat().st_mtime)
+
+
+def _list_variants_in_cache(repo_id: str, variants: list[str]) -> list[tuple[str, str, str]]:
+    """List (repo_id, variant, revision) tuples for variants that exist in cache.
+
+    Args:
+        repo_id: The HuggingFace repo ID (e.g., "Lightricks/LTX-2")
+        variants: List of variant/subfolder names to check for (e.g., ["ltx-2-19b-dev", "ltx-2-19b-dev-fp8"])
+
+    Returns:
+        List of (repo_id, variant, revision) tuples for variants found in cache
+    """
+    repo_path = _get_repo_cache_path(repo_id)
+    if repo_path is None:
+        return []
+
+    snapshot_path = _get_snapshot_path(repo_path)
+    if snapshot_path is None:
+        return []
+
+    revision = snapshot_path.name
+    results = []
+
+    for variant in variants:
+        # Check for variant as a directory (subfolder model structure)
+        variant_dir_path = snapshot_path / variant
+        if variant_dir_path.exists() and variant_dir_path.is_dir():
+            results.append((repo_id, variant, revision))
+            continue
+
+        # Check for variant as a .safetensors file (single-file model structure)
+        variant_file_path = snapshot_path / f"{variant}.safetensors"
+        if variant_file_path.exists() and variant_file_path.is_file():
+            results.append((repo_id, variant, revision))
+
+    return results
+
+
+class HuggingFaceRepoVariantParameter(HuggingFaceModelParameter):
+    """Parameter class for selecting a variant/subfolder within a HuggingFace repo.
+
+    Use this when a single repo contains multiple model variants as subfolders.
+    For example, Lightricks/LTX-2 contains:
+    - ltx-2-19b-dev
+    - ltx-2-19b-dev-fp8
+    - ltx-2-19b-dev-fp4
+    """
+
+    def __init__(
+        self,
+        node: BaseNode,
+        repo_id: str,
+        variants: list[str],
+        parameter_name: str = "model",
+    ):
+        """Initialize the parameter.
+
+        Args:
+            node: The node this parameter belongs to
+            repo_id: The HuggingFace repo ID (e.g., "Lightricks/LTX-2")
+            variants: List of variant/subfolder names (e.g., ["ltx-2-19b-dev", "ltx-2-19b-dev-fp8"])
+            parameter_name: Name of the parameter (default: "model")
+        """
+        super().__init__(node, parameter_name)
+        self._repo_id = repo_id
+        self._variants = variants
+        self.refresh_parameters()
+
+    @classmethod
+    def _repo_variant_to_key(cls, repo_id: str, variant: str) -> str:
+        """Convert repo_id and variant to a display key."""
+        return f"{repo_id}/{variant}"
+
+    @classmethod
+    def _key_to_repo_variant(cls, key: str) -> tuple[str, str]:
+        """Parse a display key back to repo_id and variant.
+
+        Key format: "owner/repo/variant"
+        """
+        parts = key.rsplit("/", 1)
+        if len(parts) == 2:  # noqa: PLR2004
+            return parts[0], parts[1]
+        # Fallback: treat entire key as repo_id with empty variant
+        return key, ""
+
+    def fetch_repo_revisions(self) -> list[tuple[str, str]]:
+        """Fetch available variants from cache.
+
+        Returns list of (display_key, revision) tuples where display_key is "repo_id/variant".
+        """
+        variant_revisions = _list_variants_in_cache(self._repo_id, self._variants)
+        return [
+            (self._repo_variant_to_key(repo_id, variant), revision) for repo_id, variant, revision in variant_revisions
+        ]
+
+    def get_download_commands(self) -> list[str]:
+        """Return download commands for the repo."""
+        return [f'huggingface-cli download "{self._repo_id}"']
+
+    def get_download_models(self) -> list[str]:
+        """Return list of model names for download."""
+        return [self._repo_id]
+
+    def get_repo_variant_revision(self) -> tuple[str, str, str]:
+        """Get the selected repo_id, variant, and revision.
+
+        Returns:
+            Tuple of (repo_id, variant, revision)
+        """
+        repo_key, revision = self.get_repo_revision()
+        repo_id, variant = self._key_to_repo_variant(repo_key)
+        return repo_id, variant, revision