Preparación final para despliegue con Daggr visual

README.md

@@ -1,14 +1,17 @@
 ---
-title: Watercolor Portrait Generator
+title: Acuarela Portrait Daggr
 emoji: 🎨
-colorFrom: indigo
-colorTo: pink
+colorFrom: blue
+colorTo: purple
 sdk: gradio
-sdk_version: "4.19.2"
-python_version: "3.11"
-app_file: app.py
+sdk_version: 4.19.2
+app_file: app_daggr.py
 pinned: false
-license: mit
+tags:
+- daggr
+- modal
+- sdxl
+- watercolor
 ---
 
 # Generador de Retratos Acuarela con IA

app_daggr.py

@@ -16,18 +16,24 @@ $ python app_daggr.py
 
 import os
 import io
+import base64
+import tempfile
+import uuid
+import shutil
+from pathlib import Path
+
+# Fix for Windows Long Paths in Gradio (must set before importing gradio)
+if os.name == 'nt':
+    custom_temp = os.path.join(tempfile.gettempdir(), "gr")
+    os.makedirs(custom_temp, exist_ok=True)
+    os.environ["GRADIO_TEMP_DIR"] = custom_temp
+
 import modal
 import gradio as gr
 from PIL import Image
-import uuid
-from dotenv import load_dotenv
-
-# Import Daggr components
 from daggr import FnNode, GradioNode, InferenceNode, Graph
 
-load_dotenv()
-
-# --- Modal Setup ---
+# --- Inference Setup ---
 try:
     ImageCaptioner = modal.Cls.from_name("acuarela-portrait", "ImageCaptioner")
     ImageGenerator = modal.Cls.from_name("acuarela-portrait", "ImageGenerator")
@@ -43,23 +49,71 @@ except Exception as e:
 
 # --- Function Nodes ---
 
-def convert_image_to_bytes(image) -> bytes:
-    """Convert PIL Image to bytes for Modal processing"""
+def convert_image_to_path(image) -> str:
+    """Save image to a temporary file and return the path for Daggr nodes"""
     if image is None:
         return None
-    img_byte_arr = io.BytesIO()
-    image.save(img_byte_arr, format='PNG')
-    return img_byte_arr.getvalue()
+    
+    try:
+        # Create a unique temp file in our short gr folder
+        temp_dir = os.environ.get("GRADIO_TEMP_DIR", tempfile.gettempdir())
+        temp_path = os.path.join(temp_dir, f"input_{uuid.uuid4()}.png")
+        
+        # Handle Base64 Data URI from Gradio/Daggr
+        if isinstance(image, str) and image.startswith('data:image'):
+            header, encoded = image.split(",", 1)
+            data = base64.b64decode(encoded)
+            with open(temp_path, "wb") as f:
+                f.write(data)
+            return temp_path
+
+        # Handle file paths (already a path, just verify and return)
+        if isinstance(image, (str, Path)):
+            path_str = str(image)
+            # Windows Long Path fix
+            if os.name == 'nt' and not path_str.startswith('\\\\?\\'):
+                abs_path = os.path.abspath(path_str)
+                path_str = '\\\\?\\' + abs_path if len(abs_path) > 250 else abs_path
+            
+            # If it's already a file, we can just return it, but better to copy to temp
+            # to avoid permissions/lifetime issues with Gradio's deep temp folders
+            shutil.copy2(path_str, temp_path)
+            return temp_path
+            
+        # Handle PIL objects
+        if hasattr(image, 'save'):
+            image.save(temp_path, format='PNG')
+            return temp_path
+            
+        # If it's bytes
+        if isinstance(image, bytes):
+            with open(temp_path, "wb") as f:
+                f.write(image)
+            return temp_path
+
+        return str(image)
+    except Exception as e:
+        print(f"❌ Error in convert_image_to_path: {e}")
+        raise e
 
 
-def generate_caption(img_bytes: bytes) -> str:
+def generate_caption(img_path: str) -> str:
     """
     Step 1: Generate image caption using Modal
     """
-    if not MODAL_AVAILABLE or img_bytes is None:
-        raise ValueError("Modal not available or image is None")
+    if not MODAL_AVAILABLE or img_path is None:
+        raise ValueError("Modal not available or image path is None")
     
     try:
+        # Read bytes from the provided path
+        path_str = str(img_path)
+        if os.name == 'nt' and not path_str.startswith('\\\\?\\'):
+            abs_path = os.path.abspath(path_str)
+            path_str = '\\\\?\\' + abs_path if len(abs_path) > 250 else abs_path
+            
+        with open(path_str, "rb") as f:
+            img_bytes = f.read()
+
         captioner = ImageCaptioner()
         caption = captioner.caption.remote(img_bytes)
         if not caption:
@@ -82,14 +136,23 @@ def create_artistic_prompt(caption: str) -> str:
     return prompt
 
 
-def generate_watercolor_image(img_bytes: bytes, prompt: str) -> Image.Image:
+def generate_watercolor_image(img_path: str, prompt: str) -> str:
     """
-    Step 3: Generate watercolor image using Modal SDXL
+    Step 3: Generate watercolor image using Modal SDXL and return the file path
     """
-    if not MODAL_AVAILABLE or img_bytes is None:
-        raise ValueError("Modal not available or image is None")
+    if not MODAL_AVAILABLE or img_path is None:
+        raise ValueError("Modal not available or image path is None")
     
     try:
+        # Read bytes from the provided path
+        path_str = str(img_path)
+        if os.name == 'nt' and not path_str.startswith('\\\\?\\'):
+            abs_path = os.path.abspath(path_str)
+            path_str = '\\\\?\\' + abs_path if len(abs_path) > 250 else abs_path
+            
+        with open(path_str, "rb") as f:
+            img_bytes = f.read()
+
         negative_prompt = (
             "photorealistic, 3d render, photograph, complex background, "
             "white background, dark background, messy sketch, blurry, "
@@ -99,8 +162,14 @@ def generate_watercolor_image(img_bytes: bytes, prompt: str) -> Image.Image:
         
         generator = ImageGenerator()
         result_bytes = generator.generate.remote(img_bytes, prompt, negative_prompt, strength=0.65)
-        result_image = Image.open(io.BytesIO(result_bytes))
-        return result_image
+        
+        # Save result to a temp file
+        temp_dir = os.environ.get("GRADIO_TEMP_DIR", tempfile.gettempdir())
+        output_path = os.path.join(temp_dir, f"output_{uuid.uuid4()}.png")
+        with open(output_path, "wb") as f:
+            f.write(result_bytes)
+            
+        return output_path
     except Exception as e:
         raise ValueError(f"Image generation failed: {str(e)}")
 
@@ -113,15 +182,15 @@ def create_workflow():
     """
     
     # Node 1: Image Input (implicit - handled by Gradio interface)
-    # Node 2: Convert image to bytes
+    # Node 2: Convert image to path (using string to avoid bytes JSON error)
     converter = FnNode(
-        fn=convert_image_to_bytes,
+        fn=convert_image_to_path,
         name="Image Converter",
         inputs={
-            "image": gr.Image(label="Upload your photo", type="pil"),
+            "image": gr.Image(label="Upload your photo"),
         },
         outputs={
-            "return": gr.Textbox(visible=False),  # Hidden - intermediate step
+            "output": gr.Textbox(visible=False), 
         },
     )
     
@@ -130,10 +199,10 @@ def create_workflow():
         fn=generate_caption,
         name="Image Analysis (BLIP Caption)",
         inputs={
-            "img_bytes": converter.return_,
+            "img_path": converter.output,
         },
         outputs={
-            "return": gr.Textbox(label="Generated Caption"),
+            "output": gr.Textbox(label="Generated Caption"),
         },
     )
     
@@ -142,10 +211,10 @@ def create_workflow():
         fn=create_artistic_prompt,
         name="Artistic Prompt Engineering",
         inputs={
-            "caption": captioner.return_,
+            "caption": captioner.output,
         },
         outputs={
-            "return": gr.Textbox(label="Artistic Prompt", lines=3),
+            "output": gr.Textbox(label="Artistic Prompt", lines=3),
         },
     )
     
@@ -154,11 +223,11 @@ def create_workflow():
         fn=generate_watercolor_image,
         name="Watercolor Generation (SDXL)",
         inputs={
-            "img_bytes": converter.return_,
-            "prompt": prompt_engineer.return_,
+            "img_path": converter.output,
+            "prompt": prompt_engineer.output,
         },
         outputs={
-            "return": gr.Image(label="Watercolor Portrait"),
+            "output": gr.Image(label="Watercolor Portrait"),
         },
     )
     
@@ -166,8 +235,7 @@ def create_workflow():
     graph = Graph(
         name="🎨 Acuarela Portrait Generator - Daggr Workflow",
         nodes=[converter, captioner, prompt_engineer, image_generator],
-        description="Transform your photos into watercolor artworks using AI. "
-                   "Each step is visualized and can be rerun independently!",
+        persist_key=False, # Disable persistence to avoid bytes -> str serialization issues
     )
     
     return graph

daggr/CHANGELOG.md

@@ -0,0 +1,65 @@
+# daggr
+
+## 0.7.0
+
+### Features
+
+- [#69](https://github.com/gradio-app/daggr/pull/69) [`297d104`](https://github.com/gradio-app/daggr/commit/297d104d0e3fbd6b59dfcd1f69c9a478de81bc3d) - Add stop button to cancel running nodes.  Thanks @abidlabs!
+- [#64](https://github.com/gradio-app/daggr/pull/64) [`a9e53c6`](https://github.com/gradio-app/daggr/commit/a9e53c64db6b3beede0b19b3876a3e50ab572233) - Fix ChoiceNode: public .name property and respect explicit names.  Thanks @abidlabs!
+- [#62](https://github.com/gradio-app/daggr/pull/62) [`695411c`](https://github.com/gradio-app/daggr/commit/695411ce94bc8fedd3320ac941ab41233bf8f887) - Standardize file handling: all files are path strings.  Thanks @abidlabs!
+- [#66](https://github.com/gradio-app/daggr/pull/66) [`1ed16f8`](https://github.com/gradio-app/daggr/commit/1ed16f806d535413c3718fc47d81d79d93d73ee0) - Fix gr.JSON rendering (use @render snippet syntax).  Thanks @abidlabs!
+- [#63](https://github.com/gradio-app/daggr/pull/63) [`00b05ac`](https://github.com/gradio-app/daggr/commit/00b05ac526642c91560cbebb258626a4511082c2) - Fix file downloads from private HF Spaces.  Thanks @abidlabs!
+- [#70](https://github.com/gradio-app/daggr/pull/70) [`33ccb74`](https://github.com/gradio-app/daggr/commit/33ccb7470a482ee1b09fddf1d51de81b1e2c4a40) - Fix gr.Image not rendering with initial value or None input.  Thanks @abidlabs!
+- [#68](https://github.com/gradio-app/daggr/pull/68) [`4b76dca`](https://github.com/gradio-app/daggr/commit/4b76dca815e2802b70ac03bb95fb03f21d81a8fa) - Add dependency hash tracking for upstream Spaces and models.  Thanks @abidlabs!
+
+## 0.6.0
+
+### Features
+
+- [#54](https://github.com/gradio-app/daggr/pull/54) [`c1abb26`](https://github.com/gradio-app/daggr/commit/c1abb260b254af6ca2060292232049ea89f0f944) - Fix cache.  Thanks @abidlabs!
+- [#56](https://github.com/gradio-app/daggr/pull/56) [`6e3dfc0`](https://github.com/gradio-app/daggr/commit/6e3dfc0a585b673adb77bb11ab1dcfd80d01da5a) - Add paste from clipboard button to Image component.  Thanks @abidlabs!
+- [#57](https://github.com/gradio-app/daggr/pull/57) [`76855ba`](https://github.com/gradio-app/daggr/commit/76855ba967e3f3132e8ec0590ae037d3151af310) - Fix dropdown options being clipped inside node.  Thanks @abidlabs!
+- [#58](https://github.com/gradio-app/daggr/pull/58) [`eb52b72`](https://github.com/gradio-app/daggr/commit/eb52b725b17d277e85f6eac1cc9d07f8068b011b) - Add theme support to daggr.  Thanks @abidlabs!
+- [#59](https://github.com/gradio-app/daggr/pull/59) [`78189a4`](https://github.com/gradio-app/daggr/commit/78189a4163b4041c814e52110b65754dc4dbf863) - Add run mode dropdown to control node execution scope.  Thanks @abidlabs!
+- [#39](https://github.com/gradio-app/daggr/pull/39) [`e8792ad`](https://github.com/gradio-app/daggr/commit/e8792ad1b5818ff8d13660b0b156f329bbc1c33a) - feat: add --state-db-path CLI arg and DAGGR_DB_PATH env var support.  Thanks @leith-bartrich!
+
+## 0.5.4
+
+### Features
+
+- [#27](https://github.com/gradio-app/daggr/pull/27) [`3952b2c`](https://github.com/gradio-app/daggr/commit/3952b2ccf30e7d18994f23049c2a2e84b323cfd6) - changes.  Thanks @abidlabs!
+
+## 0.5.3
+
+### Features
+
+- [#19](https://github.com/gradio-app/daggr/pull/19) [`cd956fe`](https://github.com/gradio-app/daggr/commit/cd956fe29945bdfd31bbe76fcb80d3f9c97cc301) - Add daggr tag to deployed Spaces.  Thanks @gary149!
+
+## 0.5.2
+
+### Features
+
+- [#14](https://github.com/gradio-app/daggr/pull/14) [`3fa412d`](https://github.com/gradio-app/daggr/commit/3fa412d678988608d49d46d99d193a05469892d2) - Fixes.  Thanks @abidlabs!
+
+## 0.5.1
+
+### Features
+
+- [#11](https://github.com/gradio-app/daggr/pull/11) [`ce1d5f4`](https://github.com/gradio-app/daggr/commit/ce1d5f4deaac60d95d9a021b0aa057bc2941b018) - Fixes.  Thanks @abidlabs!
+- [#13](https://github.com/gradio-app/daggr/pull/13) [`3246921`](https://github.com/gradio-app/daggr/commit/32469213dad5fd29a7ac85938dffbd976e2c6643) - fixes.  Thanks @abidlabs!
+
+## 0.5.0
+
+### Features
+
+- [#8](https://github.com/gradio-app/daggr/pull/8) [`e480065`](https://github.com/gradio-app/daggr/commit/e480065dd058dbf19053a80956dbfc90cf3e3caf) - Improving security around executor and various bug fixes.  Thanks @abidlabs!
+
+## 0.4.0
+
+### Features
+
+- [#1](https://github.com/gradio-app/daggr/pull/1) [`23538c8`](https://github.com/gradio-app/daggr/commit/23538c884fb3f2d84bbe4bf14f475dc85fa17c79) - Refactor files, add Dialogue component, and implement fully working podcast example.  Thanks @abidlabs!
+
+## 0.1.0
+
+Initial release

daggr/__init__.py

@@ -0,0 +1,53 @@
+"""daggr - Build visual, node-based AI pipelines with Gradio Spaces.
+
+daggr lets you create DAG (directed acyclic graph) pipelines that connect
+Gradio Spaces, Hugging Face models, and Python functions into interactive
+applications.
+
+Example:
+    >>> from daggr import Graph, GradioNode, FnNode
+    >>> import gradio as gr
+    >>>
+    >>> tts = GradioNode(
+    ...     "mrfakename/MeloTTS",
+    ...     inputs={"text": gr.Textbox()},
+    ...     outputs={"audio": gr.Audio()},
+    ... )
+    >>> graph = Graph("TTS Demo", nodes=[tts])
+    >>> graph.launch()
+"""
+
+import json
+from pathlib import Path
+
+__version__ = json.loads((Path(__file__).parent / "package.json").read_text())[
+    "version"
+]
+
+from daggr.edge import Edge
+from daggr.graph import Graph
+from daggr.node import (
+    ChoiceNode,
+    FnNode,
+    GradioNode,
+    InferenceNode,
+    InteractionNode,
+    Node,
+)
+from daggr.port import ItemList, Port
+from daggr.server import DaggrServer
+
+__all__ = [
+    "__version__",
+    "ChoiceNode",
+    "Edge",
+    "Graph",
+    "Node",
+    "FnNode",
+    "GradioNode",
+    "InferenceNode",
+    "InteractionNode",
+    "ItemList",
+    "Port",
+    "DaggrServer",
+]

daggr/_client_cache.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from daggr.state import get_daggr_cache_dir
+
+_client_cache: dict[str, Any] = {}
+_api_memory_cache: dict[str, dict] = {}
+_validated_set: set[str] = set()
+_model_task_cache: dict[str, str] = {}
+_dependency_hash_cache: dict[str, str] = {}
+_dependency_hash_loaded: bool = False
+
+
+def _is_hot_reload() -> bool:
+    return os.environ.get("DAGGR_HOT_RELOAD") == "1"
+
+
+def _get_cache_path(src: str) -> Path:
+    src_hash = hashlib.md5(src.encode()).hexdigest()[:16]
+    return get_daggr_cache_dir() / f"{src_hash}.json"
+
+
+def _get_validated_file() -> Path:
+    return get_daggr_cache_dir() / "_validated.json"
+
+
+def _load_validated_set() -> None:
+    global _validated_set
+    if _validated_set:
+        return
+    if not _is_hot_reload():
+        return
+    validated_file = _get_validated_file()
+    if validated_file.exists():
+        try:
+            _validated_set = set(json.loads(validated_file.read_text()))
+        except (json.JSONDecodeError, OSError):
+            _validated_set = set()
+
+
+def _save_validated_set() -> None:
+    if not _is_hot_reload():
+        return
+    try:
+        get_daggr_cache_dir().mkdir(parents=True, exist_ok=True)
+        _get_validated_file().write_text(json.dumps(list(_validated_set)))
+    except OSError:
+        pass
+
+
+def is_validated(cache_key: tuple) -> bool:
+    if not _is_hot_reload():
+        return False
+    _load_validated_set()
+    return str(cache_key) in _validated_set
+
+
+def mark_validated(cache_key: tuple) -> None:
+    if not _is_hot_reload():
+        return
+    _load_validated_set()
+    _validated_set.add(str(cache_key))
+    _save_validated_set()
+
+
+def get_api_info(src: str) -> dict | None:
+    if src in _api_memory_cache:
+        return _api_memory_cache[src]
+
+    if not _is_hot_reload():
+        return None
+
+    cache_path = _get_cache_path(src)
+    if cache_path.exists():
+        try:
+            data = json.loads(cache_path.read_text())
+            _api_memory_cache[src] = data
+            return data
+        except (json.JSONDecodeError, OSError):
+            pass
+    return None
+
+
+def set_api_info(src: str, info: dict) -> None:
+    _api_memory_cache[src] = info
+    if not _is_hot_reload():
+        return
+    try:
+        get_daggr_cache_dir().mkdir(parents=True, exist_ok=True)
+        cache_path = _get_cache_path(src)
+        cache_path.write_text(json.dumps(info))
+    except OSError:
+        pass
+
+
+def get_client(src: str):
+    return _client_cache.get(src)
+
+
+def set_client(src: str, client) -> None:
+    _client_cache[src] = client
+
+
+def _get_model_task_cache_path() -> Path:
+    return get_daggr_cache_dir() / "_model_tasks.json"
+
+
+def _load_model_task_cache() -> None:
+    global _model_task_cache
+    if _model_task_cache:
+        return
+    if not _is_hot_reload():
+        return
+    cache_path = _get_model_task_cache_path()
+    if cache_path.exists():
+        try:
+            _model_task_cache = json.loads(cache_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            _model_task_cache = {}
+
+
+def _save_model_task_cache() -> None:
+    if not _is_hot_reload():
+        return
+    try:
+        get_daggr_cache_dir().mkdir(parents=True, exist_ok=True)
+        _get_model_task_cache_path().write_text(json.dumps(_model_task_cache))
+    except OSError:
+        pass
+
+
+def get_model_task(model: str) -> tuple[bool, str | None]:
+    """Get cached task for a model.
+
+    Returns:
+        (found_in_cache, task) where:
+        - found_in_cache is True if we have cached info for this model
+        - task is the pipeline_tag (can be None if model has no task, or "__NOT_FOUND__" if model doesn't exist)
+    """
+    if model in _model_task_cache:
+        return True, _model_task_cache[model]
+
+    if not _is_hot_reload():
+        return False, None
+
+    _load_model_task_cache()
+    if model in _model_task_cache:
+        return True, _model_task_cache[model]
+    return False, None
+
+
+def set_model_task(model: str, task: str | None) -> None:
+    _model_task_cache[model] = task
+    _save_model_task_cache()
+
+
+def set_model_not_found(model: str) -> None:
+    _model_task_cache[model] = "__NOT_FOUND__"
+    _save_model_task_cache()
+
+
+def _get_dependency_hash_path() -> Path:
+    return get_daggr_cache_dir() / "_dependency_hashes.json"
+
+
+def _load_dependency_hash_cache() -> None:
+    global _dependency_hash_cache, _dependency_hash_loaded
+    if _dependency_hash_loaded:
+        return
+    cache_path = _get_dependency_hash_path()
+    if cache_path.exists():
+        try:
+            _dependency_hash_cache = json.loads(cache_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            _dependency_hash_cache = {}
+    _dependency_hash_loaded = True
+
+
+def _save_dependency_hash_cache() -> None:
+    try:
+        get_daggr_cache_dir().mkdir(parents=True, exist_ok=True)
+        _get_dependency_hash_path().write_text(json.dumps(_dependency_hash_cache))
+    except OSError:
+        pass
+
+
+def get_dependency_hash(src: str) -> str | None:
+    _load_dependency_hash_cache()
+    return _dependency_hash_cache.get(src)
+
+
+def set_dependency_hash(src: str, sha: str) -> None:
+    _load_dependency_hash_cache()
+    _dependency_hash_cache[src] = sha
+    _save_dependency_hash_cache()

daggr/_utils.py

@@ -0,0 +1,19 @@
+"""Internal utilities for daggr."""
+
+from __future__ import annotations
+
+import difflib
+
+
+def suggest_similar(invalid: str, valid_options: set[str]) -> str | None:
+    """Find a similar string from valid_options using fuzzy matching.
+
+    Args:
+        invalid: The invalid string to find matches for.
+        valid_options: Set of valid options to search through.
+
+    Returns:
+        The closest matching string if found with >= 60% similarity, else None.
+    """
+    matches = difflib.get_close_matches(invalid, valid_options, n=1, cutoff=0.6)
+    return matches[0] if matches else None

daggr/cli.py

@@ -0,0 +1,689 @@
+from __future__ import annotations
+
+import argparse
+import ast
+import importlib.util
+import os
+import re
+import shutil
+import socket
+import sqlite3
+import sys
+import tempfile
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+INITIAL_PORT_VALUE = int(os.getenv("DAGGR_SERVER_PORT", "7860"))
+TRY_NUM_PORTS = int(os.getenv("DAGGR_NUM_PORTS", "100"))
+
+
+def _find_available_port(host: str, start_port: int) -> int:
+    """Find an available port starting from start_port."""
+    for port in range(start_port, start_port + TRY_NUM_PORTS):
+        try:
+            s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host if host != "0.0.0.0" else "127.0.0.1", port))
+            s.close()
+            return port
+        except OSError:
+            continue
+    raise OSError(
+        f"Cannot find empty port in range: {start_port}-{start_port + TRY_NUM_PORTS - 1}. "
+        f"You can specify a different port by setting the DAGGR_SERVER_PORT environment variable "
+        f"or passing the --port parameter."
+    )
+
+
+def find_python_imports(file_path: Path) -> list[Path]:
+    """Find local Python files imported by the given file."""
+    imports = []
+    try:
+        with open(file_path) as f:
+            content = f.read()
+
+        tree = ast.parse(content)
+
+        file_dir = file_path.parent
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    module_path = file_dir / f"{alias.name.replace('.', '/')}.py"
+                    if module_path.exists():
+                        imports.append(module_path)
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    module_path = file_dir / f"{node.module.replace('.', '/')}.py"
+                    if module_path.exists():
+                        imports.append(module_path)
+                    package_init = (
+                        file_dir / node.module.replace(".", "/") / "__init__.py"
+                    )
+                    if package_init.exists():
+                        imports.append(package_init.parent)
+    except Exception:
+        pass
+    return imports
+
+
+def main():
+    if len(sys.argv) > 1 and sys.argv[1] == "deploy":
+        _deploy_main()
+        return
+
+    parser = argparse.ArgumentParser(
+        prog="daggr",
+        description="Run a daggr app with hot reload",
+    )
+    parser.add_argument(
+        "script",
+        help="Path to the Python script containing the daggr Graph",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind to (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=7860,
+        help="Port to bind to (default: 7860)",
+    )
+    parser.add_argument(
+        "--no-reload",
+        action="store_true",
+        help="Disable auto-reload",
+    )
+    parser.add_argument(
+        "--watch-daggr",
+        action="store_true",
+        default=True,
+        help="Watch daggr source for changes (default: True, useful for development)",
+    )
+    parser.add_argument(
+        "--no-watch-daggr",
+        action="store_true",
+        help="Don't watch daggr source for changes",
+    )
+    parser.add_argument(
+        "--delete-sheets",
+        action="store_true",
+        help="Delete all cached data (sheets, results, downloaded files) for this project and exit",
+    )
+    parser.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Skip confirmation prompts (use with --delete-sheets)",
+    )
+    parser.add_argument(
+        "--state-db-path",
+        help="Optional path to SQLite state database. Overrides DAGGR_DB_PATH env var. Defaults to HuggingFace cache.",
+    )
+
+    args = parser.parse_args()
+
+    script_path = Path(args.script).resolve()
+    if not script_path.exists():
+        print(f"Error: Script not found: {script_path}")
+        sys.exit(1)
+
+    if not script_path.suffix == ".py":
+        print(f"Error: Script must be a Python file: {script_path}")
+        sys.exit(1)
+
+    if args.delete_sheets:
+        _delete_sheets(script_path, force=args.force)
+        sys.exit(0)
+
+    watch_daggr = args.watch_daggr and not args.no_watch_daggr
+
+    os.environ["DAGGR_SCRIPT_PATH"] = str(script_path)
+    os.environ["DAGGR_HOST"] = args.host
+    os.environ["DAGGR_PORT"] = str(args.port)
+    if args.state_db_path:
+        os.environ["DAGGR_DB_PATH"] = str(Path(args.state_db_path).resolve())
+
+    if args.no_reload:
+        _run_script(script_path, args.host, args.port)
+    else:
+        os.environ["DAGGR_HOT_RELOAD"] = "1"
+        _run_with_reload(script_path, args.host, args.port, watch_daggr)
+
+
+def _deploy_main():
+    """Entry point for the deploy subcommand."""
+    parser = argparse.ArgumentParser(
+        prog="daggr deploy",
+        description="Deploy a daggr app to Hugging Face Spaces",
+    )
+    parser.add_argument(
+        "script",
+        help="Path to the Python script containing the daggr Graph",
+    )
+    parser.add_argument(
+        "--name",
+        "-n",
+        help="Space name (default: derived from Graph name)",
+    )
+    parser.add_argument(
+        "--title",
+        "-t",
+        help="Display title for the Space (default: Graph name)",
+    )
+    parser.add_argument(
+        "--org",
+        "-o",
+        help="Organization or username to deploy under (default: your HF account)",
+    )
+    parser.add_argument(
+        "--private",
+        "-p",
+        action="store_true",
+        help="Make the Space private",
+    )
+    parser.add_argument(
+        "--hardware",
+        default="cpu-basic",
+        help="Hardware tier (default: cpu-basic). Options: cpu-basic, cpu-upgrade, t4-small, t4-medium, a10g-small, etc.",
+    )
+    parser.add_argument(
+        "--secret",
+        "-s",
+        action="append",
+        dest="secrets",
+        metavar="KEY=VALUE",
+        help="Add a secret (can be repeated). Example: --secret HF_TOKEN=xxx",
+    )
+    parser.add_argument(
+        "--requirements",
+        "-r",
+        help="Path to requirements.txt (default: auto-detect or generate)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview what would be deployed without actually deploying",
+    )
+
+    args = parser.parse_args(sys.argv[2:])
+
+    script_path = Path(args.script).resolve()
+    if not script_path.exists():
+        print(f"Error: Script not found: {script_path}")
+        sys.exit(1)
+
+    if not script_path.suffix == ".py":
+        print(f"Error: Script must be a Python file: {script_path}")
+        sys.exit(1)
+
+    secrets = {}
+    if args.secrets:
+        for secret in args.secrets:
+            if "=" not in secret:
+                print(f"Error: Invalid secret format '{secret}'. Use KEY=VALUE")
+                sys.exit(1)
+            key, value = secret.split("=", 1)
+            secrets[key] = value
+
+    _deploy(
+        script_path=script_path,
+        name=args.name,
+        title=args.title,
+        org=args.org,
+        private=args.private,
+        hardware=args.hardware,
+        secrets=secrets,
+        requirements_path=args.requirements,
+        dry_run=args.dry_run,
+    )
+
+
+def _extract_graph(script_path: Path):
+    """Extract the Graph object from a script without running it."""
+    from daggr.graph import Graph
+
+    sys.path.insert(0, str(script_path.parent))
+
+    original_launch = Graph.launch
+    captured_graph = None
+
+    def capture_launch(self, **kwargs):
+        nonlocal captured_graph
+        captured_graph = self
+
+    Graph.launch = capture_launch
+
+    try:
+        spec = importlib.util.spec_from_file_location("__daggr_deploy__", script_path)
+        if spec is None or spec.loader is None:
+            print(f"Error: Could not load script: {script_path}")
+            sys.exit(1)
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules["__daggr_deploy__"] = module
+        spec.loader.exec_module(module)
+    finally:
+        Graph.launch = original_launch
+
+    if captured_graph is None:
+        for name in dir(module):
+            obj = getattr(module, name)
+            if isinstance(obj, Graph):
+                captured_graph = obj
+                break
+
+    if captured_graph is None:
+        print(f"Error: No Graph found in {script_path}")
+        sys.exit(1)
+
+    return captured_graph
+
+
+def _sanitize_space_name(name: str) -> str:
+    """Convert a Graph name to a valid HF Space name."""
+    sanitized = re.sub(r"[^a-zA-Z0-9\s-]", "", name)
+    sanitized = re.sub(r"[\s_]+", "-", sanitized)
+    sanitized = sanitized.lower().strip("-")
+    return sanitized or "daggr-app"
+
+
+def _deploy(
+    script_path: Path,
+    name: str | None,
+    title: str | None,
+    org: str | None,
+    private: bool,
+    hardware: str,
+    secrets: dict[str, str],
+    requirements_path: str | None,
+    dry_run: bool,
+):
+    """Deploy a daggr app to Hugging Face Spaces."""
+    import huggingface_hub
+    from huggingface_hub import HfApi
+
+    import daggr
+
+    print("\n  Extracting Graph from script...")
+    graph = _extract_graph(script_path)
+
+    space_name = name or _sanitize_space_name(graph.name)
+    space_title = title or graph.name
+
+    print(f"  Graph name: {graph.name}")
+    print(f"  Space name: {space_name}")
+    print(f"  Space title: {space_title}")
+
+    hf_api = HfApi()
+    whoami = None
+    login_needed = False
+
+    try:
+        whoami = hf_api.whoami()
+        if whoami["auth"]["accessToken"]["role"] != "write":
+            login_needed = True
+    except Exception:
+        login_needed = True
+
+    if login_needed:
+        print("\n  Need 'write' access token to create a Spaces repo.")
+        huggingface_hub.login(add_to_git_credential=False)
+        whoami = hf_api.whoami()
+
+    username = whoami["name"]
+    namespace = org or username
+    repo_id = f"{namespace}/{space_name}"
+
+    print(f"\n  Target: https://huggingface.co/spaces/{repo_id}")
+    print(f"  Hardware: {hardware}")
+    print(f"  Private: {private}")
+    if secrets:
+        print(f"  Secrets: {list(secrets.keys())}")
+
+    local_imports = find_python_imports(script_path)
+    print("\n  Files to upload:")
+    print(f"    • app.py (from {script_path.name})")
+    print("    • requirements.txt")
+    print("    • README.md")
+    for imp in local_imports:
+        if imp.is_file():
+            print(f"    • {imp.name}")
+        else:
+            print(f"    • {imp.name}/ (package)")
+
+    if dry_run:
+        print("\n  [Dry run] No changes made.")
+        return
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+
+        shutil.copy(script_path, tmpdir / "app.py")
+
+        for imp in local_imports:
+            if imp.is_file():
+                shutil.copy(imp, tmpdir / imp.name)
+            else:
+                shutil.copytree(imp, tmpdir / imp.name)
+
+        if requirements_path:
+            req_path = Path(requirements_path)
+            if not req_path.exists():
+                print(f"Error: Requirements file not found: {req_path}")
+                sys.exit(1)
+            shutil.copy(req_path, tmpdir / "requirements.txt")
+
+            with open(tmpdir / "requirements.txt", "r") as f:
+                req_content = f.read()
+            if "daggr" not in req_content:
+                with open(tmpdir / "requirements.txt", "a") as f:
+                    f.write(f"\ndaggr>={daggr.__version__}\n")
+        else:
+            script_dir = script_path.parent
+            existing_req = script_dir / "requirements.txt"
+            if existing_req.exists():
+                shutil.copy(existing_req, tmpdir / "requirements.txt")
+                with open(tmpdir / "requirements.txt", "r") as f:
+                    req_content = f.read()
+                if "daggr" not in req_content:
+                    with open(tmpdir / "requirements.txt", "a") as f:
+                        f.write(f"\ndaggr>={daggr.__version__}\n")
+            else:
+                with open(tmpdir / "requirements.txt", "w") as f:
+                    f.write(f"daggr>={daggr.__version__}\n")
+
+        readme_content = f"""---
+title: {space_title}
+emoji: 🔀
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: "{_get_gradio_version()}"
+app_file: app.py
+pinned: false
+tags:
+  - daggr
+---
+
+# {space_title}
+
+This Space was deployed using [daggr](https://github.com/gradio-app/daggr).
+"""
+        with open(tmpdir / "README.md", "w") as f:
+            f.write(readme_content)
+
+        print("\n  Creating Space repository...")
+        try:
+            hf_api.create_repo(
+                repo_id=repo_id,
+                repo_type="space",
+                space_sdk="gradio",
+                space_hardware=hardware,
+                private=private,
+                exist_ok=True,
+            )
+        except Exception as e:
+            print(f"Error creating repository: {e}")
+            sys.exit(1)
+
+        print("  Uploading files...")
+        try:
+            hf_api.upload_folder(
+                repo_id=repo_id,
+                repo_type="space",
+                folder_path=str(tmpdir),
+            )
+        except Exception as e:
+            print(f"Error uploading files: {e}")
+            sys.exit(1)
+
+        if secrets:
+            print("  Adding secrets...")
+            for secret_name, secret_value in secrets.items():
+                try:
+                    hf_api.add_space_secret(repo_id, secret_name, secret_value)
+                except Exception as e:
+                    print(f"  Warning: Could not add secret '{secret_name}': {e}")
+
+    print(f"\n  ✓ Deployed to https://huggingface.co/spaces/{repo_id}")
+    print("    The Space may take a few minutes to build and start.\n")
+
+
+def _get_gradio_version() -> str:
+    """Get the installed Gradio version."""
+    try:
+        import gradio
+
+        return gradio.__version__
+    except ImportError:
+        return "5.0.0"
+
+
+def _delete_sheets(script_path: Path, force: bool = False):
+    """Delete all cached data for the project defined in the script."""
+    from daggr.graph import Graph
+    from daggr.state import get_daggr_cache_dir
+
+    sys.path.insert(0, str(script_path.parent))
+
+    original_launch = Graph.launch
+    captured_graph = None
+
+    def capture_launch(self, **kwargs):
+        nonlocal captured_graph
+        captured_graph = self
+
+    Graph.launch = capture_launch
+
+    try:
+        spec = importlib.util.spec_from_file_location("__daggr_reset__", script_path)
+        if spec is None or spec.loader is None:
+            print(f"Error: Could not load script: {script_path}")
+            sys.exit(1)
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules["__daggr_reset__"] = module
+        spec.loader.exec_module(module)
+    finally:
+        Graph.launch = original_launch
+
+    if captured_graph is None:
+        for name in dir(module):
+            obj = getattr(module, name)
+            if isinstance(obj, Graph):
+                captured_graph = obj
+                break
+
+    if captured_graph is None:
+        print(f"Error: No Graph found in {script_path}")
+        sys.exit(1)
+
+    persist_key = captured_graph.persist_key
+    if not persist_key:
+        print("Error: Graph has no persist_key (persistence is disabled)")
+        sys.exit(1)
+
+    cache_dir = get_daggr_cache_dir()
+    db_path = cache_dir / "sessions.db"
+
+    if not db_path.exists():
+        print(f"No cache found for project '{persist_key}'")
+        return
+
+    conn = sqlite3.connect(str(db_path))
+    cursor = conn.cursor()
+
+    cursor.execute(
+        "SELECT sheet_id FROM sheets WHERE graph_name = ?",
+        (persist_key,),
+    )
+    sheet_ids = [row[0] for row in cursor.fetchall()]
+
+    if not sheet_ids:
+        print(f"No cached data found for project '{persist_key}'")
+        conn.close()
+        return
+
+    print(f"\nProject: {persist_key}")
+    print(f"This will delete {len(sheet_ids)} sheet(s) and all associated data.")
+    print(f"Cache location: {cache_dir}\n")
+
+    if not force:
+        try:
+            response = (
+                input("Are you sure you want to continue? [y/N] ").strip().lower()
+            )
+        except (EOFError, KeyboardInterrupt):
+            print("\nAborted.")
+            conn.close()
+            return
+
+        if response not in ("y", "yes"):
+            print("Aborted.")
+            conn.close()
+            return
+
+    for sheet_id in sheet_ids:
+        cursor.execute("DELETE FROM node_inputs WHERE sheet_id = ?", (sheet_id,))
+        cursor.execute("DELETE FROM node_results WHERE sheet_id = ?", (sheet_id,))
+        cursor.execute("DELETE FROM sheets WHERE sheet_id = ?", (sheet_id,))
+
+    conn.commit()
+    conn.close()
+
+    print(f"\n✓ Deleted {len(sheet_ids)} sheet(s) for project '{persist_key}'")
+
+
+def _run_script(script_path: Path, host: str, port: int):
+    """Run the script directly without reload."""
+    spec = importlib.util.spec_from_file_location("__daggr_main__", script_path)
+    if spec is None or spec.loader is None:
+        print(f"Error: Could not load script: {script_path}")
+        sys.exit(1)
+
+    sys.path.insert(0, str(script_path.parent))
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["__daggr_main__"] = module
+    spec.loader.exec_module(module)
+
+
+def _run_with_reload(script_path: Path, host: str, port: int, watch_daggr: bool):
+    """Run the script with uvicorn hot reload."""
+    import uvicorn
+
+    actual_port = _find_available_port(host, port)
+    if actual_port != port:
+        print(f"\n  Port {port} is in use, using {actual_port} instead.")
+
+    reload_dirs = [str(script_path.parent)]
+
+    local_imports = find_python_imports(script_path)
+    for imp in local_imports:
+        imp_dir = str(imp if imp.is_dir() else imp.parent)
+        if imp_dir not in reload_dirs:
+            reload_dirs.append(imp_dir)
+
+    if watch_daggr:
+        daggr_dir = Path(__file__).parent
+        daggr_src = str(daggr_dir)
+        if daggr_src not in reload_dirs:
+            reload_dirs.append(daggr_src)
+
+    reload_includes = ["*.py"]
+
+    print("\n  daggr dev server starting...")
+    print("  Watching for changes in:")
+    for d in reload_dirs:
+        print(f"    • {d}")
+    print()
+
+    os.environ["DAGGR_PORT"] = str(actual_port)
+
+    def open_browser():
+        time.sleep(1.0)
+        webbrowser.open_new_tab(f"http://{host}:{actual_port}")
+
+    threading.Thread(target=open_browser, daemon=True).start()
+
+    uvicorn.run(
+        "daggr.cli:_create_app",
+        factory=True,
+        host=host,
+        port=actual_port,
+        reload=True,
+        reload_dirs=reload_dirs,
+        reload_includes=reload_includes,
+        log_level="warning",
+    )
+
+
+def _create_app():
+    """Factory function for uvicorn to create the FastAPI app."""
+    from daggr.graph import Graph
+    from daggr.server import DaggrServer
+
+    script_path = Path(os.environ["DAGGR_SCRIPT_PATH"])
+
+    if str(script_path.parent) not in sys.path:
+        sys.path.insert(0, str(script_path.parent))
+
+    modules_to_remove = [m for m in sys.modules if m.startswith("__daggr_user_script_")]
+    for m in modules_to_remove:
+        del sys.modules[m]
+
+    module_name = f"__daggr_user_script_{id(script_path)}__"
+
+    spec = importlib.util.spec_from_file_location(module_name, script_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Could not load script: {script_path}")
+
+    original_launch = Graph.launch
+    captured_graph = None
+    launch_kwargs = {}
+
+    def capture_launch(self, **kwargs):
+        nonlocal captured_graph, launch_kwargs
+        captured_graph = self
+        launch_kwargs = kwargs
+
+    Graph.launch = capture_launch
+
+    try:
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+    finally:
+        Graph.launch = original_launch
+
+    if captured_graph is None:
+        for name in dir(module):
+            obj = getattr(module, name)
+            if isinstance(obj, Graph):
+                captured_graph = obj
+                break
+
+    if captured_graph is None:
+        raise RuntimeError(
+            f"No Graph found in {script_path}. "
+            "Make sure your script defines a Graph and calls graph.launch() "
+            "or has a Graph instance at module level."
+        )
+
+    captured_graph._validate_edges()
+    server = DaggrServer(captured_graph)
+
+    base_url = f"http://{os.environ['DAGGR_HOST']}:{os.environ['DAGGR_PORT']}"
+    print(f"\n  UI running at: {base_url}")
+    print(f"  API server at: {base_url}/api\n")
+
+    return server.app
+
+
+if __name__ == "__main__":
+    main()

daggr/edge.py

@@ -0,0 +1,60 @@
+"""Edge module for connecting ports between nodes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from daggr.port import GatheredPort, ScatteredPort
+
+if TYPE_CHECKING:
+    from daggr.port import PortLike
+
+
+class Edge:
+    """Represents a connection between two ports in a graph.
+
+    Edges connect an output port of one node to an input port of another,
+    defining how data flows through the graph.
+
+    Attributes:
+        source_node: The node providing the output.
+        source_port: Name of the output port.
+        target_node: The node receiving the input.
+        target_port: Name of the input port.
+        is_scattered: True if this edge scatters a list to multiple executions.
+        is_gathered: True if this edge gathers results back into a list.
+        item_key: For scattered edges, the key to extract from each item.
+    """
+
+    def __init__(self, source: PortLike, target: PortLike):
+        self.is_scattered = isinstance(source, ScatteredPort)
+        self.is_gathered = isinstance(source, GatheredPort)
+        self.item_key: str | None = None
+
+        if self.is_scattered:
+            self.item_key = source.item_key
+
+        self.source_node = source.node
+        self.source_port = source.name
+        self.target_node = target.node
+        self.target_port = target.name
+
+    def __repr__(self):
+        prefix = ""
+        if self.is_scattered:
+            key_info = f"['{self.item_key}']" if self.item_key else ""
+            prefix = f"scatter{key_info}:"
+        elif self.is_gathered:
+            prefix = "gather:"
+        return (
+            f"Edge({prefix}{self.source_node._name}.{self.source_port} -> "
+            f"{self.target_node._name}.{self.target_port})"
+        )
+
+    def as_tuple(self) -> tuple[str, str, str, str]:
+        return (
+            self.source_node._name,
+            self.source_port,
+            self.target_node._name,
+            self.target_port,
+        )

daggr/executor.py

@@ -0,0 +1,846 @@
+"""Executor for daggr graphs.
+
+This module provides the AsyncExecutor for running graph nodes with proper
+concurrency control and session isolation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+from gradio_client.utils import is_file_obj_with_meta, traverse
+
+from daggr.node import (
+    ChoiceNode,
+    FnNode,
+    GradioNode,
+    InferenceNode,
+    InteractionNode,
+)
+from daggr.session import ExecutionSession
+from daggr.state import get_daggr_files_dir
+
+if TYPE_CHECKING:
+    from daggr.graph import Graph
+
+
+class FileValue(str):
+    """A string subclass that marks a value as a file URL/path from Gradio output."""
+
+    pass
+
+
+def _download_file(url: str, hf_token: str | None = None) -> str:
+    import httpx
+
+    parsed = urlparse(url)
+    ext = Path(parsed.path).suffix or ".bin"
+    url_hash = hashlib.md5(url.encode()).hexdigest()[:16]
+    filename = f"{url_hash}{ext}"
+
+    files_dir = get_daggr_files_dir()
+    local_path = files_dir / filename
+
+    if not local_path.exists():
+        headers = {}
+        if hf_token:
+            headers["Authorization"] = f"Bearer {hf_token}"
+        with httpx.Client(follow_redirects=True) as client:
+            response = client.get(url, headers=headers)
+            response.raise_for_status()
+            local_path.write_bytes(response.content)
+
+    return str(local_path)
+
+
+def _postprocess_inference_result(task: str | None, result: Any) -> Any:
+    """Unwrap HF Inference Client result objects to get the actual data."""
+    if result is None:
+        return None
+
+    if task == "automatic-speech-recognition":
+        return getattr(result, "text", result)
+    elif task == "translation":
+        return getattr(result, "translation_text", result)
+    elif task == "summarization":
+        return getattr(result, "summary_text", result)
+    elif task in (
+        "audio-classification",
+        "image-classification",
+        "text-classification",
+    ):
+        if isinstance(result, list) and result:
+            return {item.label: item.score for item in result if hasattr(item, "label")}
+        return result
+    elif task == "image-to-text":
+        return getattr(result, "generated_text", result)
+    elif task == "question-answering":
+        if hasattr(result, "answer"):
+            return result.answer
+        return result
+    elif task in ("text-to-speech", "text-to-audio"):
+        if isinstance(result, bytes):
+            file_path = get_daggr_files_dir() / f"{uuid.uuid4()}.wav"
+            file_path.write_bytes(result)
+            return str(file_path)
+        return result
+    elif task in ("text-to-image", "image-to-image"):
+        if isinstance(result, dict):
+            if "images" in result:
+                result = result["images"][0] if result["images"] else result
+            elif "image" in result:
+                result = result["image"]
+        if hasattr(result, "save"):
+            file_path = get_daggr_files_dir() / f"{uuid.uuid4()}.png"
+            result.save(file_path)
+            return str(file_path)
+        return result
+
+    return result
+
+
+def _call_inference_task(client: Any, task: str | None, inputs: dict[str, Any]) -> Any:
+    primary_input = None
+    if task in (
+        "image-to-image",
+        "image-classification",
+        "image-to-text",
+        "object-detection",
+        "image-segmentation",
+        "visual-question-answering",
+        "document-question-answering",
+    ):
+        primary_input = inputs.get("image")
+    elif task in (
+        "automatic-speech-recognition",
+        "audio-classification",
+        "audio-to-audio",
+    ):
+        primary_input = inputs.get("audio")
+
+    if primary_input is None:
+        primary_input = next(iter(inputs.values()), None) if inputs else None
+
+    if primary_input is None:
+        return None
+
+    task_method_map = {
+        "text-generation": "text_generation",
+        "text2text-generation": "text_generation",
+        "text-to-image": "text_to_image",
+        "image-to-image": "image_to_image",
+        "image-to-text": "image_to_text",
+        "image-to-video": "image_to_video",
+        "text-to-video": "text_to_video",
+        "text-to-speech": "text_to_speech",
+        "text-to-audio": "text_to_audio",
+        "automatic-speech-recognition": "automatic_speech_recognition",
+        "audio-to-audio": "audio_to_audio",
+        "audio-classification": "audio_classification",
+        "image-classification": "image_classification",
+        "object-detection": "object_detection",
+        "image-segmentation": "image_segmentation",
+        "translation": "translation",
+        "summarization": "summarization",
+        "feature-extraction": "feature_extraction",
+        "fill-mask": "fill_mask",
+        "question-answering": "question_answering",
+        "table-question-answering": "table_question_answering",
+        "sentence-similarity": "sentence_similarity",
+        "zero-shot-classification": "zero_shot_classification",
+        "zero-shot-image-classification": "zero_shot_image_classification",
+        "document-question-answering": "document_question_answering",
+        "visual-question-answering": "visual_question_answering",
+    }
+
+    method_name = (
+        task_method_map.get(task, "text_generation") if task else "text_generation"
+    )
+    method = getattr(client, method_name, None)
+
+    file_input_tasks = {
+        "image-to-image",
+        "image-classification",
+        "image-to-text",
+        "object-detection",
+        "image-segmentation",
+        "visual-question-answering",
+        "document-question-answering",
+        "automatic-speech-recognition",
+        "audio-classification",
+        "audio-to-audio",
+    }
+
+    if task in file_input_tasks and isinstance(primary_input, str):
+        primary_input = _read_file_as_bytes(primary_input)
+
+    try:
+        if method is None:
+            result = client.text_generation(primary_input)
+        elif task in ("image-to-image",):
+            prompt = inputs.get("prompt", "")
+            result = method(primary_input, prompt=prompt)
+        elif task in ("visual-question-answering", "document-question-answering"):
+            question = inputs.get("question", inputs.get("prompt", ""))
+            result = method(primary_input, question=question)
+        else:
+            result = method(primary_input)
+    except KeyError as e:
+        raise RuntimeError(
+            f"Provider returned unexpected response format for task '{task}'. "
+            f"Missing key: {e}. This model may require a specific provider "
+            f"(e.g., 'model_name:fal-ai' or 'model_name:replicate')."
+        ) from e
+
+    return _postprocess_inference_result(task, result)
+
+
+def _read_file_as_bytes(file_path: str) -> bytes:
+    """Read a file path or data URL as bytes."""
+    if file_path.startswith("data:"):
+        try:
+            _, encoded = file_path.split(",", 1)
+            return base64.b64decode(encoded)
+        except Exception:
+            pass
+
+    path = Path(file_path)
+    if path.exists():
+        return path.read_bytes()
+
+    return file_path
+
+
+class AsyncExecutor:
+    """Async executor for graph nodes.
+
+    This executor is stateless - all state is held in the ExecutionSession.
+    It handles concurrency control:
+    - GradioNode/InferenceNode: run concurrently (external API calls)
+    - FnNode: sequential by default, configurable via concurrent/concurrency_group
+    """
+
+    def __init__(self, graph: Graph):
+        self.graph = graph
+
+    def _get_client_for_gradio_node(
+        self, session: ExecutionSession, gradio_node, cache_key: str
+    ):
+        from daggr import _client_cache
+
+        token_cache_key = f"{cache_key}__token_{hash(session.hf_token or '')}"
+        if token_cache_key in session.clients:
+            return session.clients[token_cache_key]
+
+        if gradio_node._run_locally:
+            from daggr.local_space import get_local_client
+
+            client = get_local_client(gradio_node)
+            if client is not None:
+                session.clients[token_cache_key] = client
+                return client
+
+        if session.hf_token:
+            from gradio_client import Client
+
+            client = Client(
+                gradio_node._src,
+                download_files=False,
+                verbose=False,
+                token=session.hf_token,
+            )
+        else:
+            client = _client_cache.get_client(gradio_node._src)
+            if client is None:
+                from gradio_client import Client
+
+                client = Client(
+                    gradio_node._src,
+                    download_files=False,
+                    verbose=False,
+                )
+                _client_cache.set_client(gradio_node._src, client)
+
+        session.clients[token_cache_key] = client
+        return client
+
+    def _get_client(self, session: ExecutionSession, node_name: str):
+        node = self.graph.nodes[node_name]
+
+        if isinstance(node, ChoiceNode):
+            variant_idx = session.selected_variants.get(node_name, 0)
+            variant = node._variants[variant_idx]
+            if isinstance(variant, GradioNode):
+                cache_key = f"{node_name}__variant_{variant_idx}"
+                return self._get_client_for_gradio_node(session, variant, cache_key)
+            return None
+
+        if not isinstance(node, GradioNode):
+            return None
+
+        return self._get_client_for_gradio_node(session, node, node_name)
+
+    def _get_scattered_input_edges(self, node_name: str) -> list:
+        scattered = []
+        for edge in self.graph._edges:
+            if edge.target_node._name == node_name and edge.is_scattered:
+                scattered.append(edge)
+        return scattered
+
+    def _get_gathered_input_edges(self, node_name: str) -> list:
+        gathered = []
+        for edge in self.graph._edges:
+            if edge.target_node._name == node_name and edge.is_gathered:
+                gathered.append(edge)
+        return gathered
+
+    def _prepare_inputs(
+        self, session: ExecutionSession, node_name: str, skip_scattered: bool = False
+    ) -> dict[str, Any]:
+        inputs = {}
+
+        for edge in self.graph._edges:
+            if edge.target_node._name == node_name:
+                if skip_scattered and edge.is_scattered:
+                    continue
+
+                source_name = edge.source_node._name
+                source_output = edge.source_port
+                target_input = edge.target_port
+
+                if source_name in session.results:
+                    source_result = session.results[source_name]
+
+                    if (
+                        edge.is_gathered
+                        and isinstance(source_result, dict)
+                        and "_scattered_results" in source_result
+                    ):
+                        scattered_results = source_result["_scattered_results"]
+                        extracted = []
+                        for item_result in scattered_results:
+                            if (
+                                isinstance(item_result, dict)
+                                and source_output in item_result
+                            ):
+                                extracted.append(item_result[source_output])
+                            else:
+                                extracted.append(item_result)
+                        inputs[target_input] = extracted
+                    elif (
+                        isinstance(source_result, dict)
+                        and source_output in source_result
+                    ):
+                        inputs[target_input] = source_result[source_output]
+                    elif isinstance(source_result, (list, tuple)):
+                        try:
+                            output_idx = int(
+                                source_output.replace("output_", "").replace(
+                                    "output", "0"
+                                )
+                            )
+                            if 0 <= output_idx < len(source_result):
+                                inputs[target_input] = source_result[output_idx]
+                        except (ValueError, TypeError):
+                            if len(source_result) > 0:
+                                inputs[target_input] = source_result[0]
+                    else:
+                        inputs[target_input] = source_result
+
+        return inputs
+
+    def _execute_single_node_sync(
+        self, session: ExecutionSession, node_name: str, inputs: dict[str, Any]
+    ) -> Any:
+        """Synchronous node execution (called from thread pool for FnNode)."""
+        node = self.graph.nodes[node_name]
+
+        if isinstance(node, ChoiceNode):
+            variant_idx = session.selected_variants.get(node_name, 0)
+            variant = node._variants[variant_idx]
+            return self._execute_variant_node_sync(session, node_name, variant, inputs)
+
+        all_inputs = {}
+        for port_name, value in node._fixed_inputs.items():
+            all_inputs[port_name] = value() if callable(value) else value
+        for port_name, component in node._input_components.items():
+            if hasattr(component, "value"):
+                val = component.value
+                if is_file_obj_with_meta(val):
+                    val = val["path"]
+                all_inputs[port_name] = val
+        all_inputs.update(inputs)
+
+        if isinstance(node, GradioNode):
+            client = self._get_client(session, node_name)
+            if client:
+                api_name = node._api_name or "/predict"
+                if not api_name.startswith("/"):
+                    api_name = "/" + api_name
+                call_inputs = {
+                    k: self._wrap_file_input(v)
+                    for k, v in all_inputs.items()
+                    if k in node._input_ports
+                }
+                if node._preprocess:
+                    call_inputs = node._preprocess(call_inputs)
+                raw_result = client.predict(api_name=api_name, **call_inputs)
+                if node._postprocess:
+                    raw_result = self._apply_postprocess(node._postprocess, raw_result)
+                result = self._map_gradio_result(
+                    node, raw_result, hf_token=session.hf_token
+                )
+            else:
+                result = None
+
+        elif isinstance(node, FnNode):
+            fn_kwargs = {}
+            for port_name in node._input_ports:
+                if port_name in all_inputs:
+                    fn_kwargs[port_name] = all_inputs[port_name]
+            if node._preprocess:
+                fn_kwargs = node._preprocess(fn_kwargs)
+            raw_result = node._fn(**fn_kwargs)
+            if node._postprocess:
+                raw_result = self._apply_postprocess(node._postprocess, raw_result)
+            result = self._map_fn_result(node, raw_result)
+
+        elif isinstance(node, InferenceNode):
+            from huggingface_hub import InferenceClient
+
+            if not node._task_fetched:
+                node._fetch_model_info()
+            client = InferenceClient(
+                model=node._model_name_for_hub,
+                provider=node._provider,
+                token=session.hf_token,
+            )
+            inference_inputs = {
+                k: v for k, v in all_inputs.items() if k in node._input_ports
+            }
+            if node._preprocess:
+                inference_inputs = node._preprocess(inference_inputs)
+            raw_result = _call_inference_task(client, node._task, inference_inputs)
+            if node._postprocess:
+                raw_result = self._apply_postprocess(node._postprocess, raw_result)
+            result = self._map_inference_result(node, raw_result)
+
+        elif isinstance(node, InteractionNode):
+            result = all_inputs.get(
+                "input",
+                all_inputs.get(node._input_ports[0]) if node._input_ports else None,
+            )
+
+        else:
+            result = None
+
+        return result
+
+    def _execute_variant_node_sync(
+        self,
+        session: ExecutionSession,
+        node_name: str,
+        variant,
+        inputs: dict[str, Any],
+    ) -> Any:
+        all_inputs = {}
+        for port_name, value in variant._fixed_inputs.items():
+            all_inputs[port_name] = value() if callable(value) else value
+        for port_name, component in variant._input_components.items():
+            if hasattr(component, "value"):
+                val = component.value
+                if is_file_obj_with_meta(val):
+                    val = val["path"]
+                all_inputs[port_name] = val
+        all_inputs.update(inputs)
+
+        if isinstance(variant, GradioNode):
+            client = self._get_client(session, node_name)
+            if client:
+                api_name = variant._api_name or "/predict"
+                if not api_name.startswith("/"):
+                    api_name = "/" + api_name
+                call_inputs = {
+                    k: self._wrap_file_input(v)
+                    for k, v in all_inputs.items()
+                    if k in variant._input_ports
+                }
+                if variant._preprocess:
+                    call_inputs = variant._preprocess(call_inputs)
+                raw_result = client.predict(api_name=api_name, **call_inputs)
+                if variant._postprocess:
+                    raw_result = self._apply_postprocess(
+                        variant._postprocess, raw_result
+                    )
+                result = self._map_gradio_result(
+                    variant, raw_result, hf_token=session.hf_token
+                )
+            else:
+                result = None
+
+        elif isinstance(variant, FnNode):
+            fn_kwargs = {}
+            for port_name in variant._input_ports:
+                if port_name in all_inputs:
+                    fn_kwargs[port_name] = all_inputs[port_name]
+            if variant._preprocess:
+                fn_kwargs = variant._preprocess(fn_kwargs)
+            raw_result = variant._fn(**fn_kwargs)
+            if variant._postprocess:
+                raw_result = self._apply_postprocess(variant._postprocess, raw_result)
+            result = self._map_fn_result(variant, raw_result)
+
+        elif isinstance(variant, InferenceNode):
+            from huggingface_hub import InferenceClient
+
+            if not variant._task_fetched:
+                variant._fetch_model_info()
+            client = InferenceClient(
+                model=variant._model_name_for_hub,
+                provider=variant._provider,
+                token=session.hf_token,
+            )
+            inference_inputs = {
+                k: v for k, v in all_inputs.items() if k in variant._input_ports
+            }
+            if variant._preprocess:
+                inference_inputs = variant._preprocess(inference_inputs)
+            raw_result = _call_inference_task(client, variant._task, inference_inputs)
+            if variant._postprocess:
+                raw_result = self._apply_postprocess(variant._postprocess, raw_result)
+            result = self._map_inference_result(variant, raw_result)
+
+        else:
+            result = None
+
+        return result
+
+    async def execute_node(
+        self,
+        session: ExecutionSession,
+        node_name: str,
+        user_inputs: dict[str, Any] | None = None,
+    ) -> Any:
+        """Execute a single node with proper concurrency control."""
+        node = self.graph.nodes[node_name]
+        scattered_edges = self._get_scattered_input_edges(node_name)
+
+        if scattered_edges:
+            result = await self._execute_scattered_node(
+                session, node_name, scattered_edges, user_inputs
+            )
+        else:
+            inputs = self._prepare_inputs(session, node_name)
+            if user_inputs:
+                if isinstance(user_inputs, dict):
+                    inputs.update(user_inputs)
+                else:
+                    if node._input_ports:
+                        inputs[node._input_ports[0]] = user_inputs
+                    else:
+                        inputs["input"] = user_inputs
+
+            try:
+                if isinstance(node, (GradioNode, InferenceNode)):
+                    result = await asyncio.to_thread(
+                        self._execute_single_node_sync, session, node_name, inputs
+                    )
+                elif isinstance(node, FnNode):
+                    semaphore = await session.concurrency.get_semaphore(
+                        node._concurrent,
+                        node._concurrency_group,
+                        node._max_concurrent,
+                    )
+                    if semaphore:
+                        async with semaphore:
+                            result = await asyncio.to_thread(
+                                self._execute_single_node_sync,
+                                session,
+                                node_name,
+                                inputs,
+                            )
+                    else:
+                        result = await asyncio.to_thread(
+                            self._execute_single_node_sync, session, node_name, inputs
+                        )
+                else:
+                    result = await asyncio.to_thread(
+                        self._execute_single_node_sync, session, node_name, inputs
+                    )
+            except Exception as e:
+                raise RuntimeError(f"Error executing node '{node_name}': {e}")
+
+        session.results[node_name] = result
+        return result
+
+    async def _execute_scattered_node(
+        self,
+        session: ExecutionSession,
+        node_name: str,
+        scattered_edges: list,
+        user_inputs: dict[str, Any] | None = None,
+    ) -> dict[str, list[Any]]:
+        first_edge = scattered_edges[0]
+        source_name = first_edge.source_node._name
+        source_port = first_edge.source_port
+
+        source_result = session.results.get(source_name)
+        if source_result is None:
+            items = []
+        elif isinstance(source_result, dict) and source_port in source_result:
+            items = source_result[source_port]
+        else:
+            items = source_result
+
+        if not isinstance(items, list):
+            items = [items]
+
+        context_inputs = self._prepare_inputs(session, node_name, skip_scattered=True)
+        if user_inputs:
+            context_inputs.update(user_inputs)
+
+        node = self.graph.nodes[node_name]
+
+        async def execute_item(item, idx):
+            item_inputs = dict(context_inputs)
+            for edge in scattered_edges:
+                target_port = edge.target_port
+                item_key = edge.item_key
+                if item_key and isinstance(item, dict):
+                    item_inputs[target_port] = item.get(item_key)
+                else:
+                    item_inputs[target_port] = item
+
+            try:
+                if isinstance(node, (GradioNode, InferenceNode)):
+                    return await asyncio.to_thread(
+                        self._execute_single_node_sync, session, node_name, item_inputs
+                    )
+                elif isinstance(node, FnNode):
+                    semaphore = await session.concurrency.get_semaphore(
+                        node._concurrent,
+                        node._concurrency_group,
+                        node._max_concurrent,
+                    )
+                    if semaphore:
+                        async with semaphore:
+                            return await asyncio.to_thread(
+                                self._execute_single_node_sync,
+                                session,
+                                node_name,
+                                item_inputs,
+                            )
+                    else:
+                        return await asyncio.to_thread(
+                            self._execute_single_node_sync,
+                            session,
+                            node_name,
+                            item_inputs,
+                        )
+                else:
+                    return await asyncio.to_thread(
+                        self._execute_single_node_sync, session, node_name, item_inputs
+                    )
+            except Exception as e:
+                return {"error": str(e)}
+
+        if isinstance(node, (GradioNode, InferenceNode)):
+            tasks = [execute_item(item, i) for i, item in enumerate(items)]
+            results = await asyncio.gather(*tasks)
+        else:
+            results = []
+            for i, item in enumerate(items):
+                result = await execute_item(item, i)
+                results.append(result)
+
+        session.scattered_results[node_name] = list(results)
+        return {"_scattered_results": list(results), "_items": items}
+
+    def _wrap_file_input(self, value: Any) -> Any:
+        from gradio_client import handle_file
+
+        if isinstance(value, FileValue):
+            return handle_file(str(value))
+
+        if isinstance(value, str):
+            if value.startswith("data:"):
+                file_path = self._save_data_url_to_file(value)
+                if file_path:
+                    return handle_file(file_path)
+            elif Path(value).exists():
+                return handle_file(value)
+
+        return value
+
+    def _save_data_url_to_file(self, data_url: str) -> str | None:
+        """Convert a base64 data URL to a file and return the path."""
+        if not data_url.startswith("data:"):
+            return None
+
+        try:
+            header, encoded = data_url.split(",", 1)
+            media_type = header.split(":")[1].split(";")[0]
+            ext_map = {
+                "image/png": ".png",
+                "image/jpeg": ".jpg",
+                "image/jpg": ".jpg",
+                "image/gif": ".gif",
+                "image/webp": ".webp",
+                "audio/wav": ".wav",
+                "audio/mpeg": ".mp3",
+                "audio/mp3": ".mp3",
+                "audio/ogg": ".ogg",
+                "audio/webm": ".webm",
+                "video/mp4": ".mp4",
+                "video/webm": ".webm",
+            }
+            ext = ext_map.get(media_type, ".bin")
+            data = base64.b64decode(encoded)
+            file_path = get_daggr_files_dir() / f"{uuid.uuid4()}{ext}"
+            file_path.write_bytes(data)
+            return str(file_path)
+        except Exception:
+            return None
+
+    def _apply_postprocess(self, postprocess, raw_result: Any) -> Any:
+        if isinstance(raw_result, (list, tuple)):
+            return postprocess(*raw_result)
+        return postprocess(raw_result)
+
+    def _extract_file_urls(self, data: Any, hf_token: str | None = None) -> Any:
+        def download_and_wrap(file_obj: dict) -> FileValue:
+            url = file_obj.get("url")
+            if url:
+                local_path = _download_file(url, hf_token=hf_token)
+                return FileValue(local_path)
+            path = file_obj.get("path", "")
+            return FileValue(path)
+
+        return traverse(data, download_and_wrap, is_file_obj_with_meta)
+
+    def _map_gradio_result(
+        self, node, raw_result: Any, hf_token: str | None = None
+    ) -> dict[str, Any]:
+        if raw_result is None:
+            return {}
+
+        raw_result = self._extract_file_urls(raw_result, hf_token=hf_token)
+
+        output_ports = node._output_ports
+        if not output_ports:
+            return {"output": raw_result}
+
+        if isinstance(raw_result, (list, tuple)):
+            result = {}
+            for i, port_name in enumerate(output_ports):
+                if i < len(raw_result):
+                    result[port_name] = raw_result[i]
+                else:
+                    result[port_name] = None
+            return result
+        elif len(output_ports) == 1:
+            return {output_ports[0]: raw_result}
+        else:
+            return {output_ports[0]: raw_result}
+
+    def _map_fn_result(self, node, raw_result: Any) -> dict[str, Any]:
+        if raw_result is None:
+            return {}
+
+        output_ports = node._output_ports
+        if not output_ports:
+            return {"output": raw_result}
+
+        if isinstance(raw_result, tuple):
+            result = {}
+            for i, port_name in enumerate(output_ports):
+                if i < len(raw_result):
+                    result[port_name] = raw_result[i]
+                else:
+                    result[port_name] = None
+            return result
+        else:
+            return {output_ports[0]: raw_result}
+
+    def _map_inference_result(self, node, raw_result: Any) -> dict[str, Any]:
+        """Map inference API result to output ports."""
+        if raw_result is None:
+            return {}
+
+        output_ports = node._output_ports
+        if not output_ports:
+            return {"output": raw_result}
+
+        return {output_ports[0]: raw_result}
+
+    async def execute_all(
+        self, session: ExecutionSession, entry_inputs: dict[str, dict[str, Any]]
+    ) -> dict[str, Any]:
+        execution_order = self.graph.get_execution_order()
+        session.results = {}
+
+        for node_name in execution_order:
+            user_input = entry_inputs.get(node_name, {})
+            await self.execute_node(session, node_name, user_input)
+
+        return session.results
+
+
+class SequentialExecutor:
+    """Legacy synchronous executor for backwards compatibility.
+
+    This wraps the AsyncExecutor for use in synchronous contexts like node.test().
+    For production use, prefer AsyncExecutor with proper session management.
+    """
+
+    def __init__(self, graph: Graph, hf_token: str | None = None):
+        self.graph = graph
+        self._async_executor = AsyncExecutor(graph)
+        self._session = ExecutionSession(graph, hf_token)
+
+    @property
+    def results(self) -> dict[str, Any]:
+        return self._session.results
+
+    @results.setter
+    def results(self, value: dict[str, Any]):
+        self._session.results = value
+
+    @property
+    def selected_variants(self) -> dict[str, int]:
+        return self._session.selected_variants
+
+    @selected_variants.setter
+    def selected_variants(self, value: dict[str, int]):
+        self._session.selected_variants = value
+
+    def set_hf_token(self, token: str | None):
+        self._session.set_hf_token(token)
+
+    def execute_node(
+        self, node_name: str, user_inputs: dict[str, Any] | None = None
+    ) -> Any:
+        """Synchronous wrapper around async execute_node."""
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(
+                self._async_executor.execute_node(self._session, node_name, user_inputs)
+            )
+        finally:
+            loop.close()
+
+    def execute_all(self, entry_inputs: dict[str, dict[str, Any]]) -> dict[str, Any]:
+        """Synchronous wrapper around async execute_all."""
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(
+                self._async_executor.execute_all(self._session, entry_inputs)
+            )
+        finally:
+            loop.close()

daggr/graph.py

@@ -0,0 +1,767 @@
+"""Graph module for daggr.
+
+A Graph represents a directed acyclic graph (DAG) of nodes that can be
+executed to process data through a pipeline.
+"""
+
+from __future__ import annotations
+
+import itertools
+import os
+import re
+import sys
+import threading
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+import networkx as nx
+
+from daggr._utils import suggest_similar
+from daggr.edge import Edge
+from daggr.local_space import prepare_local_node
+from daggr.node import ChoiceNode, GradioNode, InferenceNode, Node
+from daggr.port import Port
+
+if TYPE_CHECKING:
+    from gradio.themes import ThemeClass as Theme
+
+
+def _parse_space_id(src: str) -> str | None:
+    if src.startswith("http://") or src.startswith("https://"):
+        match = re.match(r"https?://huggingface\.co/spaces/([^/]+/[^/?#]+)", src)
+        if match:
+            return match.group(1)
+        return None
+    if "/" in src:
+        return src
+    return None
+
+
+def _get_dependency_id(node) -> tuple[str | None, str]:
+    if isinstance(node, GradioNode):
+        space_id = _parse_space_id(node._src)
+        return space_id, "space"
+    elif isinstance(node, InferenceNode):
+        return node._model_name_for_hub, "model"
+    return None, ""
+
+
+def _fetch_current_sha(dep_id: str, dep_type: str) -> str | None:
+    try:
+        if dep_type == "space":
+            from huggingface_hub import space_info
+
+            info = space_info(dep_id)
+            return info.sha
+        elif dep_type == "model":
+            from huggingface_hub import model_info
+
+            info = model_info(dep_id)
+            return info.sha
+    except Exception:
+        return None
+    return None
+
+
+def _duplicate_space_at_revision(
+    space_id: str, revision: str, username: str
+) -> str | None:
+    try:
+        from huggingface_hub import (
+            create_repo,
+            snapshot_download,
+            upload_folder,
+        )
+
+        space_name = space_id.split("/")[-1]
+        new_repo_id = f"{username}/{space_name}"
+
+        local_dir = snapshot_download(
+            repo_id=space_id,
+            repo_type="space",
+            revision=revision,
+        )
+
+        create_repo(
+            repo_id=new_repo_id,
+            repo_type="space",
+            space_sdk="gradio",
+            exist_ok=True,
+        )
+
+        upload_folder(
+            repo_id=new_repo_id,
+            repo_type="space",
+            folder_path=local_dir,
+        )
+
+        return new_repo_id
+    except Exception as e:
+        print(f"  [daggr] Failed to duplicate Space: {e}")
+        return None
+
+
+def _prompt_dependency_changes(changed: list[dict]) -> None:
+    from daggr import _client_cache
+
+    is_tty = hasattr(sys.stdin, "isatty") and sys.stdin.isatty()
+
+    print("\n  ⚠️  Upstream dependency changes detected:\n")
+    for item in changed:
+        print(
+            f"    • {item['type']} '{item['id']}' (node: {item['node']._name})\n"
+            f"      cached:  {item['cached_sha'][:12]}\n"
+            f"      current: {item['current_sha'][:12]}"
+        )
+    print()
+
+    if not is_tty:
+        for item in changed:
+            _client_cache.set_dependency_hash(item["id"], item["current_sha"])
+        print(
+            "  [daggr] Non-interactive mode: auto-updated all hashes.\n"
+            "  Set DAGGR_DEPENDENCY_CHECK=skip to suppress this warning.\n"
+        )
+        return
+
+    for item in changed:
+        is_space = item["type"] == "space"
+        if is_space:
+            print(
+                f"  How would you like to handle '{item['id']}'?\n"
+                f"    [1] Duplicate the original version under your namespace (safer)\n"
+                f"    [2] Update to the latest version"
+            )
+        else:
+            print(
+                f"  How would you like to handle '{item['id']}'?\n"
+                f"    [1] Update to the latest version"
+            )
+
+        try:
+            choice = input("  Choice [1]: ").strip() or "1"
+        except (EOFError, KeyboardInterrupt):
+            choice = "1"
+
+        if is_space and choice == "1":
+            username = _get_hf_username()
+            if username is None:
+                print(
+                    "  [daggr] Not logged in to Hugging Face. "
+                    "Updating hash instead.\n"
+                    "  Run `huggingface-cli login` to enable Space duplication."
+                )
+                _client_cache.set_dependency_hash(item["id"], item["current_sha"])
+            else:
+                print(
+                    f"  [daggr] Duplicating '{item['id']}' at revision "
+                    f"{item['cached_sha'][:12]} under {username}/..."
+                )
+                new_id = _duplicate_space_at_revision(
+                    item["id"], item["cached_sha"], username
+                )
+                if new_id:
+                    item["node"]._src = new_id
+                    _client_cache.set_dependency_hash(new_id, item["cached_sha"])
+                    print(
+                        f"  [daggr] Duplicated → '{new_id}'. "
+                        f"Node now points to duplicated Space."
+                    )
+                else:
+                    print(
+                        "  [daggr] Duplication failed (revision may have been "
+                        "squashed). Updating hash instead."
+                    )
+                    _client_cache.set_dependency_hash(item["id"], item["current_sha"])
+        else:
+            _client_cache.set_dependency_hash(item["id"], item["current_sha"])
+            print(f"  [daggr] Updated hash for '{item['id']}'.")
+
+    print()
+
+
+def _get_hf_username() -> str | None:
+    try:
+        from huggingface_hub import get_token, whoami
+
+        token = get_token()
+        if not token:
+            return None
+        info = whoami(cache=True)
+        return info.get("name")
+    except Exception:
+        return None
+
+
+class _Spinner:
+    _CHARS = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+    def __init__(self, message: str):
+        self._message = message
+        self._is_tty = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+        if self._is_tty:
+            self._stop = threading.Event()
+            self._thread = threading.Thread(target=self._spin, daemon=True)
+            self._thread.start()
+
+    def _spin(self):
+        frames = itertools.cycle(self._CHARS)
+        while not self._stop.is_set():
+            sys.stdout.write(f"\r  {next(frames)} {self._message}")
+            sys.stdout.flush()
+            self._stop.wait(0.08)
+
+    def _finish(self, symbol: str, suffix: str = ""):
+        line = f"  {symbol} {self._message}"
+        if suffix:
+            line += f" — {suffix}"
+        if self._is_tty:
+            self._stop.set()
+            self._thread.join()
+            sys.stdout.write(f"\r{line}\033[K\n")
+        else:
+            sys.stdout.write(f"{line}\n")
+        sys.stdout.flush()
+
+    def succeed(self, suffix: str = ""):
+        self._finish("✓", suffix)
+
+    def warn(self, suffix: str = ""):
+        self._finish("⚠", suffix)
+
+
+def _get_node_display_label(node) -> str:
+    if isinstance(node, GradioNode):
+        label = node._src
+        if node._api_name:
+            label += f" ({node._api_name})"
+        return label
+    elif isinstance(node, InferenceNode):
+        return node._model_name_for_hub
+    return node._name
+
+
+class Graph:
+    """A directed acyclic graph (DAG) of nodes for data processing.
+
+    A Graph connects nodes together to form a pipeline. Data flows from entry
+    nodes (nodes with no inputs) through the graph to output nodes.
+
+    Example:
+        >>> from daggr import Graph, FnNode
+        >>> def step1(x): return {"out": x * 2}
+        >>> def step2(y): return {"out": y + 1}
+        >>> n1 = FnNode(step1)
+        >>> n2 = FnNode(step2, inputs={"y": n1.out})
+        >>> graph = Graph("My Pipeline", nodes=[n2])
+        >>> graph.launch()
+    """
+
+    def __init__(
+        self,
+        name: str,
+        nodes: Sequence[Node] | None = None,
+        persist_key: str | bool | None = None,
+    ):
+        """Create a new Graph.
+
+        Args:
+            name: Display name for this graph shown in the UI.
+            nodes: Optional list of nodes to add to the graph.
+            persist_key: Unique key used to store this graph's data in the database.
+                         If not provided, derived from name by converting to lowercase
+                         and replacing spaces/special chars with underscores.
+                         Set to False to disable persistence entirely.
+                         Use a custom string to ensure persistence works correctly
+                         if you change the display name later.
+        """
+        if not name or not isinstance(name, str):
+            raise ValueError(
+                "Graph requires a 'name' parameter. "
+                "Example: Graph(name='My Podcast Generator', nodes=[...])"
+            )
+        self.name = name
+        if persist_key is False:
+            self.persist_key = None
+        elif persist_key:
+            self.persist_key = persist_key
+        else:
+            self.persist_key = re.sub(r"[^a-z0-9]+", "_", name.lower()).strip("_")
+        self.nodes: dict[str, Node] = {}
+        self._nx_graph = nx.DiGraph()
+        self._edges: list[Edge] = []
+
+        if nodes:
+            for node in nodes:
+                self.add(node)
+
+    def add(self, node: Node) -> Graph:
+        """Add a node to the graph.
+
+        Also adds any upstream nodes connected via the node's port connections.
+
+        Args:
+            node: The node to add.
+
+        Returns:
+            self, for method chaining.
+        """
+        self._add_node(node)
+        self._create_edges_from_port_connections(node)
+        return self
+
+    def edge(self, source: Port, target: Port) -> Graph:
+        """Create an edge connecting two ports.
+
+        Args:
+            source: The source port (output of a node).
+            target: The target port (input of a node).
+
+        Returns:
+            self, for method chaining.
+
+        Raises:
+            ValueError: If the edge would create a cycle.
+        """
+        edge = Edge(source, target)
+        self._add_edge(edge)
+        return self
+
+    def _add_node(self, node: Node) -> None:
+        if node._name in self.nodes:
+            if self.nodes[node._name] is not node:
+                raise ValueError(f"Node with name '{node._name}' already exists")
+            return
+        self.nodes[node._name] = node
+        self._nx_graph.add_node(node._name)
+
+    def _create_edges_from_port_connections(self, node: Node) -> None:
+        for target_port_name, source_port in node._port_connections.items():
+            source_node = source_port.node
+            source_port_name = source_port.name
+
+            if source_port_name not in source_node._output_ports:
+                available = set(source_node._output_ports)
+                suggestion = suggest_similar(source_port_name, available)
+                available_str = ", ".join(available) or "(none)"
+                msg = (
+                    f"Output port '{source_port_name}' not found on node "
+                    f"'{source_node._name}'. Available outputs: {available_str}"
+                )
+                if suggestion:
+                    msg += f" Did you mean '{suggestion}'?"
+                raise ValueError(msg)
+
+            is_new_node = source_node._name not in self.nodes
+            self._add_node(source_node)
+            if is_new_node:
+                self._create_edges_from_port_connections(source_node)
+            target_port = Port(node, target_port_name)
+            edge = Edge(source_port, target_port)
+            self._add_edge(edge)
+
+    def _add_edge(self, edge: Edge) -> None:
+        self._add_node(edge.source_node)
+        self._add_node(edge.target_node)
+
+        self._edges.append(edge)
+        self._nx_graph.add_edge(edge.source_node._name, edge.target_node._name)
+
+        if not nx.is_directed_acyclic_graph(self._nx_graph):
+            self._nx_graph.remove_edge(edge.source_node._name, edge.target_node._name)
+            self._edges.pop()
+            raise ValueError("Connection would create a cycle in the DAG")
+
+    def get_entry_nodes(self) -> list[Node]:
+        """Get all nodes with no incoming edges (entry points of the graph)."""
+        entry_nodes = []
+        for node_name in self.nodes:
+            if self._nx_graph.in_degree(node_name) == 0:
+                entry_nodes.append(self.nodes[node_name])
+        return entry_nodes
+
+    def get_execution_order(self) -> list[str]:
+        """Get the topologically sorted order of node names for execution."""
+        return list(nx.topological_sort(self._nx_graph))
+
+    def get_connections(self) -> list[tuple]:
+        """Get all edges as tuples of (source_node, source_port, target_node, target_port)."""
+        return [edge.as_tuple() for edge in self._edges]
+
+    def _validate_edges(self) -> None:
+        errors = []
+        for edge in self._edges:
+            source_node = edge.source_node
+            target_node = edge.target_node
+            source_port = edge.source_port
+            target_port = edge.target_port
+
+            if source_port not in source_node._output_ports:
+                available = set(source_node._output_ports)
+                available_str = ", ".join(available) or "(none)"
+                suggestion = suggest_similar(source_port, available)
+                msg = (
+                    f"Output port '{source_port}' not found on node "
+                    f"'{source_node._name}'. Available outputs: {available_str}"
+                )
+                if suggestion:
+                    msg += f" Did you mean '{suggestion}'?"
+                errors.append(msg)
+
+            if target_port not in target_node._input_ports:
+                available = set(target_node._input_ports)
+                available_str = ", ".join(available) or "(none)"
+                suggestion = suggest_similar(target_port, available)
+                msg = (
+                    f"Input port '{target_port}' not found on node "
+                    f"'{target_node._name}'. Available inputs: {available_str}"
+                )
+                if suggestion:
+                    msg += f" Did you mean '{suggestion}'?"
+                errors.append(msg)
+
+        if errors:
+            raise ValueError("Invalid port connections:\n  - " + "\n  - ".join(errors))
+
+    def launch(
+        self,
+        host: str | None = None,
+        port: int | None = None,
+        share: bool | None = None,
+        open_browser: bool = True,
+        theme: Theme | str | None = None,
+        api_server: bool = True,
+        **kwargs,
+    ):
+        """Launch the graph as an interactive web application.
+
+        Starts a web server that displays the graph and allows users to
+        execute nodes and view results.
+
+        Args:
+            host: Host to bind to. Defaults to GRADIO_SERVER_NAME env var,
+                or "127.0.0.1" if not set. Set to "0.0.0.0" to make
+                accessible on a network or when deploying to Hugging Face Spaces.
+            port: Port to bind to. Defaults to GRADIO_SERVER_PORT env var,
+                or 7860 if not set.
+            share: If True, create a public share link. Defaults to True in
+                Colab/Kaggle environments, False otherwise.
+            open_browser: If True, automatically open the app in the default
+                web browser. Defaults to True.
+            theme: A Gradio theme to use for styling. Can be a Gradio `Theme` instance,
+                a string name like "default", "soft", "monochrome", "glass",
+                or a Hub theme like "gradio/seafoam". Defaults to the Gradio
+                default theme.
+            api_server: If True, expose the programmatic API endpoints
+                (/api/call, /api/schema). Defaults to True.
+            **kwargs: Additional arguments passed to uvicorn.
+        """
+        from daggr.server import DaggrServer
+
+        if host is None:
+            host = os.environ.get("GRADIO_SERVER_NAME", "127.0.0.1")
+        if port is None:
+            port = int(os.environ.get("GRADIO_SERVER_PORT", "7860"))
+
+        self._startup_display()
+        server = DaggrServer(self, theme=theme, api_server=api_server)
+        server.run(
+            host=host, port=port, share=share, open_browser=open_browser, **kwargs
+        )
+
+    def _prepare_local_nodes(self) -> None:
+        for node in self.nodes.values():
+            if isinstance(node, ChoiceNode):
+                for variant in node._variants:
+                    if isinstance(variant, GradioNode) and variant._run_locally:
+                        prepare_local_node(variant)
+            elif isinstance(node, GradioNode) and node._run_locally:
+                prepare_local_node(node)
+
+    def _check_dependency_hashes(self) -> None:
+        mode = os.environ.get("DAGGR_DEPENDENCY_CHECK", "").lower()
+        if mode == "skip":
+            return
+
+        from daggr import _client_cache
+
+        nodes_to_check: list[GradioNode | InferenceNode] = []
+        for node in self.nodes.values():
+            if isinstance(node, ChoiceNode):
+                for variant in node._variants:
+                    if isinstance(variant, (GradioNode, InferenceNode)):
+                        nodes_to_check.append(variant)
+            elif isinstance(node, (GradioNode, InferenceNode)):
+                nodes_to_check.append(node)
+
+        if not nodes_to_check:
+            return
+
+        changed: list[dict[str, Any]] = []
+        for node in nodes_to_check:
+            dep_id, dep_type = _get_dependency_id(node)
+            if dep_id is None:
+                continue
+
+            current_sha = _fetch_current_sha(dep_id, dep_type)
+            if current_sha is None:
+                continue
+
+            cached_sha = _client_cache.get_dependency_hash(dep_id)
+            if cached_sha is None:
+                _client_cache.set_dependency_hash(dep_id, current_sha)
+            elif cached_sha != current_sha:
+                changed.append(
+                    {
+                        "type": dep_type,
+                        "id": dep_id,
+                        "node": node,
+                        "cached_sha": cached_sha,
+                        "current_sha": current_sha,
+                    }
+                )
+
+        if not changed:
+            return
+
+        if mode == "update":
+            for item in changed:
+                _client_cache.set_dependency_hash(item["id"], item["current_sha"])
+                print(
+                    f"  [daggr] Auto-updated hash for {item['type']} "
+                    f"'{item['id']}' → {item['current_sha'][:12]}"
+                )
+            return
+
+        if mode == "error":
+            descs = [
+                f"  • {item['type']} '{item['id']}': "
+                f"{item['cached_sha'][:12]} → {item['current_sha'][:12]}"
+                for item in changed
+            ]
+            raise RuntimeError(
+                "Upstream dependencies have changed:\n"
+                + "\n".join(descs)
+                + "\nSet DAGGR_DEPENDENCY_CHECK=update to accept changes."
+            )
+
+        _prompt_dependency_changes(changed)
+
+    def _startup_display(self) -> None:
+        mode = os.environ.get("DAGGR_DEPENDENCY_CHECK", "").lower()
+        skip_hashes = mode == "skip"
+
+        node_count = len(self.nodes)
+        noun = "node" if node_count == 1 else "nodes"
+        print(f"\n  Launching Daggr ({self.name}) with {node_count} {noun}:\n")
+
+        from daggr import _client_cache
+
+        changed: list[dict[str, Any]] = []
+
+        def _check_hash(node):
+            dep_id, dep_type = _get_dependency_id(node)
+            if dep_id is None:
+                return None
+
+            current_sha = _fetch_current_sha(dep_id, dep_type)
+            if current_sha is None:
+                return None
+
+            cached_sha = _client_cache.get_dependency_hash(dep_id)
+            if cached_sha is None:
+                _client_cache.set_dependency_hash(dep_id, current_sha)
+                return ("recorded", f"hash {current_sha[:7]} recorded")
+            elif cached_sha == current_sha:
+                return ("matches", f"hash {current_sha[:7]} matches")
+            else:
+                changed.append(
+                    {
+                        "type": dep_type,
+                        "id": dep_id,
+                        "node": node,
+                        "cached_sha": cached_sha,
+                        "current_sha": current_sha,
+                    }
+                )
+                return ("changed", "hash changed")
+
+        for node in self.nodes.values():
+            if isinstance(node, ChoiceNode):
+                spinner = _Spinner(node._name)
+                for variant in node._variants:
+                    if isinstance(variant, GradioNode) and variant._run_locally:
+                        prepare_local_node(variant)
+                results = []
+                if not skip_hashes:
+                    for variant in node._variants:
+                        if isinstance(variant, (GradioNode, InferenceNode)):
+                            result = _check_hash(variant)
+                            if result:
+                                results.append(result)
+                if any(r[0] == "changed" for r in results):
+                    spinner.warn("hash changed")
+                elif results:
+                    spinner.succeed(results[-1][1])
+                else:
+                    spinner.succeed()
+                continue
+
+            if isinstance(node, GradioNode) and node._run_locally:
+                prepare_local_node(node)
+
+            label = _get_node_display_label(node)
+
+            if isinstance(node, (GradioNode, InferenceNode)) and not skip_hashes:
+                spinner = _Spinner(label)
+                result = _check_hash(node)
+                if result and result[0] == "changed":
+                    spinner.warn(result[1])
+                elif result:
+                    spinner.succeed(result[1])
+                else:
+                    spinner.succeed()
+            else:
+                sys.stdout.write(f"  ✓ {label}\n")
+                sys.stdout.flush()
+
+        print()
+
+        if not changed:
+            return
+
+        if mode == "update":
+            for item in changed:
+                _client_cache.set_dependency_hash(item["id"], item["current_sha"])
+                print(
+                    f"  [daggr] Auto-updated hash for {item['type']} "
+                    f"'{item['id']}' → {item['current_sha'][:12]}"
+                )
+            return
+
+        if mode == "error":
+            descs = [
+                f"  • {item['type']} '{item['id']}': "
+                f"{item['cached_sha'][:12]} → {item['current_sha'][:12]}"
+                for item in changed
+            ]
+            raise RuntimeError(
+                "Upstream dependencies have changed:\n"
+                + "\n".join(descs)
+                + "\nSet DAGGR_DEPENDENCY_CHECK=update to accept changes."
+            )
+
+        _prompt_dependency_changes(changed)
+
+    def get_subgraphs(self) -> list[set[str]]:
+        """Get all weakly connected components of the graph.
+
+        Returns a list of sets, where each set contains the node names
+        belonging to a connected subgraph. If the graph is fully connected,
+        returns a single set with all node names.
+        """
+        return [set(c) for c in nx.weakly_connected_components(self._nx_graph)]
+
+    def get_output_nodes(self) -> list[str]:
+        """Get all nodes with no outgoing edges (output/leaf nodes)."""
+        return [
+            node_name
+            for node_name in self.nodes
+            if self._nx_graph.out_degree(node_name) == 0
+        ]
+
+    def get_api_schema(self) -> dict:
+        """Get the API schema describing inputs and outputs for each subgraph.
+
+        Returns a dict with:
+        - subgraphs: list of subgraph info, each containing:
+          - id: subgraph identifier (e.g., "main" or "subgraph_0")
+          - inputs: list of {node, port, type, component} for each input
+          - outputs: list of {node, port, type, component} for each output
+        """
+        subgraphs = self.get_subgraphs()
+        output_nodes = set(self.get_output_nodes())
+        result = {"subgraphs": []}
+
+        for idx, subgraph_nodes in enumerate(subgraphs):
+            subgraph_id = "main" if len(subgraphs) == 1 else f"subgraph_{idx}"
+
+            inputs = []
+            outputs = []
+
+            for node_name in subgraph_nodes:
+                node = self.nodes[node_name]
+
+                if isinstance(node, ChoiceNode):
+                    continue
+
+                if node._input_components:
+                    for port_name, comp in node._input_components.items():
+                        comp_type = self._get_component_type(comp)
+                        inputs.append(
+                            {
+                                "node": node_name,
+                                "port": port_name,
+                                "type": comp_type,
+                                "id": f"{node_name}__{port_name}".replace(
+                                    " ", "_"
+                                ).replace("-", "_"),
+                            }
+                        )
+
+                if node_name in output_nodes and node._output_components:
+                    for port_name, comp in node._output_components.items():
+                        if comp is None:
+                            continue
+                        comp_type = self._get_component_type(comp)
+                        outputs.append(
+                            {
+                                "node": node_name,
+                                "port": port_name,
+                                "type": comp_type,
+                            }
+                        )
+
+            result["subgraphs"].append(
+                {
+                    "id": subgraph_id,
+                    "inputs": inputs,
+                    "outputs": outputs,
+                }
+            )
+
+        return result
+
+    def _get_component_type(self, component) -> str:
+        """Get the type string for a Gradio component."""
+        class_name = component.__class__.__name__
+        type_map = {
+            "Audio": "audio",
+            "Textbox": "textbox",
+            "TextArea": "textarea",
+            "JSON": "json",
+            "Chatbot": "json",
+            "Image": "image",
+            "Number": "number",
+            "Markdown": "markdown",
+            "Text": "text",
+            "Dropdown": "dropdown",
+            "Video": "video",
+            "File": "file",
+            "Model3D": "model3d",
+            "Gallery": "gallery",
+            "Slider": "slider",
+            "Radio": "radio",
+            "Checkbox": "checkbox",
+            "CheckboxGroup": "checkboxgroup",
+            "ColorPicker": "colorpicker",
+            "Label": "label",
+            "HighlightedText": "highlightedtext",
+            "Code": "code",
+            "HTML": "html",
+            "Dataframe": "dataframe",
+        }
+        return type_map.get(class_name, "text")
+
+    def __repr__(self):
+        return f"Graph(name={self.name}, nodes={len(self.nodes)}, edges={len(self._edges)})"

daggr/local_space.py

@@ -0,0 +1,503 @@
+from __future__ import annotations
+
+import atexit
+import hashlib
+import json
+import os
+import re
+import select
+import shutil
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from daggr.node import GradioNode
+
+from daggr.state import get_daggr_cache_dir
+
+
+def _get_spaces_cache_dir() -> Path:
+    return get_daggr_cache_dir() / "spaces"
+
+
+def _get_logs_dir() -> Path:
+    return get_daggr_cache_dir() / "logs"
+
+
+_running_processes: dict[str, subprocess.Popen] = {}
+
+
+def _get_space_dir(space_id: str) -> Path:
+    spaces_dir = _get_spaces_cache_dir()
+    parts = space_id.split("/")
+    if len(parts) == 2:
+        owner, name = parts
+        return spaces_dir / owner / name
+    return spaces_dir / space_id.replace("/", "_")
+
+
+def _get_metadata_path(space_dir: Path) -> Path:
+    return space_dir / ".daggr_metadata.json"
+
+
+def _hash_file(file_path: Path) -> str:
+    if not file_path.exists():
+        return ""
+    return hashlib.sha256(file_path.read_bytes()).hexdigest()[:16]
+
+
+def _find_free_port(start: int = 7861, end: int = 7960) -> int:
+    for port in range(start, end):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    raise RuntimeError(f"No free ports available in range {start}-{end}")
+
+
+def _is_space_id(src: str) -> bool:
+    if src.startswith("http://") or src.startswith("https://"):
+        return False
+    return "/" in src and not src.startswith("/")
+
+
+class LocalSpaceManager:
+    def __init__(self, node: GradioNode):
+        self.node = node
+        self.space_id = node._src
+        self.space_dir = _get_space_dir(self.space_id)
+        self.repo_dir = self.space_dir / "repo"
+        self.venv_dir = self.space_dir / ".venv"
+        self.metadata_path = _get_metadata_path(self.space_dir)
+        self.process: subprocess.Popen | None = None
+        self.local_url: str | None = None
+
+    def ensure_ready(self) -> str:
+        if not _is_space_id(self.space_id):
+            raise ValueError(
+                f"Cannot run locally: '{self.space_id}' is not a valid Space ID. "
+                "Local mode only works with Hugging Face Spaces (format: 'owner/space-name')."
+            )
+
+        try:
+            self._ensure_cloned()
+            self._ensure_venv()
+            url = self._launch_app()
+            return url
+        except Exception as e:
+            self._log_error(e)
+            raise
+
+    def _ensure_cloned(self) -> None:
+        metadata = self._load_metadata()
+
+        if self.repo_dir.exists() and metadata:
+            should_update = os.environ.get("DAGGR_UPDATE_SPACES") == "1"
+            if not should_update:
+                return
+
+        self.space_dir.mkdir(parents=True, exist_ok=True)
+
+        from huggingface_hub import snapshot_download
+
+        print(f"  Cloning Space '{self.space_id}'...")
+
+        if self.repo_dir.exists():
+            shutil.rmtree(self.repo_dir)
+
+        snapshot_download(
+            repo_id=self.space_id,
+            repo_type="space",
+            local_dir=self.repo_dir,
+        )
+
+        requirements_path = self.repo_dir / "requirements.txt"
+        metadata = {
+            "cloned_at": datetime.now().isoformat(),
+            "space_id": self.space_id,
+            "requirements_hash": _hash_file(requirements_path),
+            "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+        }
+        self._save_metadata(metadata)
+        print(f"  Cloned to {self.repo_dir}")
+
+    def _get_sdk_version(self) -> str | None:
+        readme_path = self.repo_dir / "README.md"
+        if not readme_path.exists():
+            return None
+
+        try:
+            content = readme_path.read_text()
+            if not content.startswith("---"):
+                return None
+
+            parts = content.split("---", 2)
+            if len(parts) < 3:
+                return None
+
+            match = re.search(r"sdk_version:\s*['\"]?([^\s'\"]+)", parts[1])
+            if match:
+                return match.group(1)
+        except Exception:
+            pass
+
+        return None
+
+    def _ensure_venv(self) -> None:
+        requirements_path = self.repo_dir / "requirements.txt"
+        current_hash = _hash_file(requirements_path)
+        metadata = self._load_metadata()
+
+        venv_python = self.venv_dir / "bin" / "python"
+        if sys.platform == "win32":
+            venv_python = self.venv_dir / "Scripts" / "python.exe"
+
+        needs_reinstall = False
+        if not self.venv_dir.exists() or not venv_python.exists():
+            needs_reinstall = True
+        elif metadata and metadata.get("requirements_hash") != current_hash:
+            needs_reinstall = True
+
+        if not needs_reinstall:
+            return
+
+        print(f"  Setting up virtual environment for '{self.space_id}'...")
+
+        if self.venv_dir.exists():
+            shutil.rmtree(self.venv_dir)
+
+        subprocess.run(
+            [sys.executable, "-m", "venv", str(self.venv_dir)],
+            check=True,
+            capture_output=True,
+        )
+
+        pip_path = self.venv_dir / "bin" / "pip"
+        if sys.platform == "win32":
+            pip_path = self.venv_dir / "Scripts" / "pip.exe"
+
+        subprocess.run(
+            [str(pip_path), "install", "--upgrade", "pip"],
+            check=True,
+            capture_output=True,
+        )
+
+        sdk_version = self._get_sdk_version()
+        if sdk_version:
+            gradio_pkg = f"gradio=={sdk_version}"
+            print(f"  Installing {gradio_pkg}...")
+        else:
+            gradio_pkg = "gradio"
+            print("  Installing gradio (latest)...")
+
+        result = subprocess.run(
+            [str(pip_path), "install", gradio_pkg],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            error_msg = result.stderr or result.stdout
+            self._log_to_file("pip_install_gradio", error_msg)
+            print(f"    Warning: Failed to install {gradio_pkg}")
+
+        if requirements_path.exists():
+            print(f"  Installing dependencies from {requirements_path}...")
+            print("  (this may take a few minutes)")
+
+            process = subprocess.Popen(
+                [str(pip_path), "install", "-r", str(requirements_path)],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1,
+            )
+
+            output_lines = []
+            for line in iter(process.stdout.readline, ""):
+                output_lines.append(line)
+                line_stripped = line.strip()
+                if line_stripped.startswith("Collecting "):
+                    pkg = line_stripped.replace("Collecting ", "").split()[0]
+                    print(f"    Installing {pkg}...")
+                elif (
+                    line_stripped.startswith("ERROR:")
+                    or "error" in line_stripped.lower()
+                ):
+                    print(f"    {line_stripped}")
+
+            process.wait()
+
+            if process.returncode != 0:
+                error_msg = "".join(output_lines)
+                self._log_to_file("pip_install", error_msg)
+                print("\n  ❌ Dependency installation failed!")
+                print(f"  Full log: {self._get_log_path('pip_install')}")
+                raise RuntimeError(
+                    f"Failed to install dependencies for '{self.space_id}'.\n"
+                    f"See logs at: {self._get_log_path('pip_install')}\n"
+                    f"You can try installing manually:\n"
+                    f"  {pip_path} install -r {requirements_path}"
+                )
+
+        if metadata:
+            metadata["requirements_hash"] = current_hash
+            self._save_metadata(metadata)
+
+        print("  Virtual environment ready")
+
+    def _launch_app(self) -> str:
+        global _running_processes
+
+        if self.space_id in _running_processes:
+            proc = _running_processes[self.space_id]
+            if proc.poll() is None:
+                metadata = self._load_metadata()
+                if metadata and metadata.get("local_url"):
+                    return metadata["local_url"]
+
+        app_file = self._find_app_file()
+        if not app_file:
+            raise RuntimeError(
+                f"No app.py or main.py found in '{self.space_id}'. "
+                "Cannot determine how to launch this Space."
+            )
+
+        port = _find_free_port()
+        local_url = f"http://127.0.0.1:{port}"
+
+        venv_python = self.venv_dir / "bin" / "python"
+        if sys.platform == "win32":
+            venv_python = self.venv_dir / "Scripts" / "python.exe"
+
+        timeout = int(os.environ.get("DAGGR_LOCAL_TIMEOUT", "120"))
+
+        env = os.environ.copy()
+        env["GRADIO_SERVER_PORT"] = str(port)
+        env["GRADIO_SERVER_NAME"] = "127.0.0.1"
+        env["PYTHONUNBUFFERED"] = "1"
+
+        print(f"  Launching '{self.space_id}' on port {port}...")
+        print(f"  Waiting for app to start (timeout: {timeout}s)...")
+
+        log_file = self._get_log_path("launch")
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+
+        self.process = subprocess.Popen(
+            [str(venv_python), str(app_file)],
+            cwd=str(self.repo_dir),
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+
+        _running_processes[self.space_id] = self.process
+
+        ready, error_output = self._wait_for_ready(local_url, timeout, verbose=True)
+        if not ready:
+            self._log_to_file("launch", error_output)
+            if self.process.poll() is None:
+                self.process.terminate()
+
+            print("\n  ❌ Space failed to start!")
+            if error_output:
+                error_lines = error_output.strip().split("\n")
+                relevant_lines = [ln for ln in error_lines if ln.strip()][-10:]
+                if relevant_lines:
+                    print("  Last output:")
+                    for line in relevant_lines:
+                        print(f"    {line}")
+
+            print(f"  Full log: {log_file}")
+            raise RuntimeError(
+                f"Space '{self.space_id}' failed to start.\n"
+                f"See logs at: {log_file}\n"
+                "Suggestions:\n"
+                "  1. Some Spaces require GPU hardware\n"
+                "  2. Check the Space's README for requirements\n"
+                "  3. Set DAGGR_LOCAL_VERBOSE=1 to see all output"
+            )
+
+        metadata = self._load_metadata() or {}
+        metadata["local_url"] = local_url
+        metadata["last_successful_launch"] = datetime.now().isoformat()
+        self._save_metadata(metadata)
+
+        print(f"  Space running at {local_url}")
+        return local_url
+
+    def _find_app_file(self) -> Path | None:
+        for name in ["app.py", "main.py", "demo.py"]:
+            path = self.repo_dir / name
+            if path.exists():
+                return path
+        return None
+
+    def _wait_for_ready(
+        self, url: str, timeout: int, verbose: bool = False
+    ) -> tuple[bool, str]:
+        output_lines: list[str] = []
+        start = time.time()
+        last_status_time = start
+        saw_error = False
+
+        while time.time() - start < timeout:
+            if self.process and self.process.stdout:
+                while True:
+                    if sys.platform == "win32":
+                        line = self.process.stdout.readline()
+                        if not line:
+                            break
+                    else:
+                        ready, _, _ = select.select([self.process.stdout], [], [], 0)
+                        if not ready:
+                            break
+                        line = self.process.stdout.readline()
+
+                    if line:
+                        output_lines.append(line)
+                        line_lower = line.lower()
+                        if (
+                            "traceback" in line_lower
+                            or "modulenotfounderror" in line_lower
+                        ):
+                            saw_error = True
+                        if verbose:
+                            print(f"    [app] {line.rstrip()}")
+
+            exit_code = self.process.poll() if self.process else None
+            if exit_code is not None:
+                if self.process and self.process.stdout:
+                    remaining = self.process.stdout.read()
+                    if remaining:
+                        output_lines.append(remaining)
+                        if verbose:
+                            for rem_line in remaining.strip().split("\n"):
+                                if rem_line.strip():
+                                    print(f"    [app] {rem_line}")
+                print(f"  App process exited with code {exit_code}")
+                return False, "".join(output_lines)
+
+            if saw_error:
+                time.sleep(0.5)
+                if self.process and self.process.poll() is not None:
+                    if self.process.stdout:
+                        remaining = self.process.stdout.read()
+                        if remaining:
+                            output_lines.append(remaining)
+                    print("  App crashed during startup")
+                    return False, "".join(output_lines)
+
+            elapsed = time.time() - start
+            if elapsed - (last_status_time - start) >= 10:
+                print(f"    Still waiting... ({int(elapsed)}s elapsed)")
+                last_status_time = time.time()
+
+            try:
+                with urllib.request.urlopen(url, timeout=2) as response:
+                    if response.status == 200:
+                        return True, "".join(output_lines)
+            except (urllib.error.URLError, OSError):
+                pass
+
+            time.sleep(0.3)
+
+        return False, "".join(output_lines)
+
+    def _load_metadata(self) -> dict[str, Any] | None:
+        if not self.metadata_path.exists():
+            return None
+        try:
+            return json.loads(self.metadata_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def _save_metadata(self, metadata: dict[str, Any]) -> None:
+        self.metadata_path.parent.mkdir(parents=True, exist_ok=True)
+        self.metadata_path.write_text(json.dumps(metadata, indent=2))
+
+    def _get_log_path(self, log_type: str) -> Path:
+        logs_dir = _get_logs_dir()
+        logs_dir.mkdir(parents=True, exist_ok=True)
+        safe_name = self.space_id.replace("/", "_")
+        timestamp = datetime.now().strftime("%Y-%m-%d")
+        return logs_dir / f"{safe_name}_{log_type}_{timestamp}.log"
+
+    def _log_to_file(self, log_type: str, content: str) -> None:
+        log_path = self._get_log_path(log_type)
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(log_path, "w") as f:
+            f.write(f"Timestamp: {datetime.now().isoformat()}\n")
+            f.write(f"Space: {self.space_id}\n")
+            f.write(f"Type: {log_type}\n")
+            f.write("=" * 50 + "\n")
+            f.write(content)
+
+    def _log_error(self, error: Exception) -> None:
+        self._log_to_file("error", str(error))
+
+
+def prepare_local_node(node: GradioNode) -> None:
+    if node._local_failed or node._local_url:
+        return
+
+    if not _is_space_id(node._src):
+        return
+
+    no_fallback = os.environ.get("DAGGR_LOCAL_NO_FALLBACK") == "1"
+
+    try:
+        manager = LocalSpaceManager(node)
+        url = manager.ensure_ready()
+        node._local_url = url
+    except Exception as e:
+        node._local_failed = True
+        safe_name = node._src.replace("/", "_")
+
+        print(f"\n  ⚠️  Local setup failed for '{node._src}'")
+        print(f"  Reason: {e}")
+        print(f"  Logs: {_get_logs_dir()}/{safe_name}_*.log")
+
+        if no_fallback:
+            raise RuntimeError(
+                f"Local execution failed for '{node._src}' and fallback is disabled. "
+                f"Error: {e}"
+            ) from e
+
+        print("  Will fall back to remote API at execution time.\n")
+
+
+def get_local_client(node: GradioNode) -> Any:
+    if node._local_failed:
+        return None
+
+    if node._local_url:
+        from gradio_client import Client
+
+        return Client(node._local_url, download_files=False, verbose=False)
+
+    return None
+
+
+def cleanup_local_processes() -> None:
+    global _running_processes
+    for space_id, proc in list(_running_processes.items()):
+        if proc.poll() is None:
+            proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+    _running_processes.clear()
+
+
+atexit.register(cleanup_local_processes)

daggr/node.py

@@ -0,0 +1,772 @@
+"""Node types for daggr graphs.
+
+This module defines the various node types that can be used in a daggr graph:
+- Node: Abstract base class for all nodes
+- GradioNode: Wraps a Gradio Space or endpoint
+- InferenceNode: Wraps a Hugging Face Inference API model
+- FnNode: Wraps a Python function
+- InteractionNode: Represents user interaction points
+"""
+
+from __future__ import annotations
+
+import inspect
+import warnings
+from abc import ABC
+from collections.abc import Callable
+from typing import Any
+
+from daggr._utils import suggest_similar
+from daggr.port import ItemList, Port, PortNamespace, is_port
+
+_FILE_TYPE_COMPONENTS = {
+    "Image",
+    "Audio",
+    "Video",
+    "File",
+    "Gallery",
+    "ImageEditor",
+    "ImageSlider",
+}
+
+
+def _warn_if_type_set(component: Any, port_name: str) -> None:
+    constructor_args = getattr(component, "_constructor_args", None)
+    if not constructor_args:
+        return
+    comp_type = constructor_args[0].get("type")
+    if comp_type is None:
+        return
+    class_name = type(component).__name__
+    if class_name not in _FILE_TYPE_COMPONENTS:
+        return
+    if comp_type != "filepath":
+        warnings.warn(
+            f"Gradio component {class_name}(type={comp_type!r}) on port '{port_name}': "
+            f"daggr ignores the `type` parameter. All file data is passed as file path "
+            f"strings regardless of this setting.",
+            stacklevel=4,
+        )
+
+
+def _is_gradio_component(obj: Any) -> bool:
+    if obj is None:
+        return False
+    class_name = obj.__class__.__name__
+    module = getattr(obj.__class__, "__module__", "")
+    return "gradio" in module or class_name in (
+        "Textbox",
+        "TextArea",
+        "Audio",
+        "Image",
+        "JSON",
+        "Markdown",
+        "Number",
+        "Checkbox",
+        "Dropdown",
+        "Radio",
+        "Slider",
+        "File",
+        "Video",
+        "Gallery",
+        "Chatbot",
+        "Text",
+    )
+
+
+class Node(ABC):
+    """Abstract base class for all nodes in a daggr graph.
+
+    Nodes represent processing steps in a DAG. Each node has named input and
+    output ports that can be connected to form a data processing pipeline.
+
+    Ports can be accessed as attributes: `node.port_name` returns a Port object.
+
+    Args:
+        name: Optional display name for the node. If not provided, a name will
+            be auto-generated based on the node type.
+    """
+
+    _id_counter = 0
+
+    def __init__(self, name: str | None = None):
+        self._id = Node._id_counter
+        Node._id_counter += 1
+        self._name = name or ""
+        self._name_explicitly_set = bool(name)
+        self._input_ports: list[str] = []
+        self._output_ports: list[str] = []
+        self._input_components: dict[str, Any] = {}
+        self._output_components: dict[str, Any] = {}
+        self._item_list_schemas: dict[str, dict[str, Any]] = {}
+        self._fixed_inputs: dict[str, Any] = {}
+        self._port_connections: dict[str, Any] = {}
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        self._name = value
+        self._name_explicitly_set = True
+
+    def __getattr__(self, name: str) -> Port:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return Port(self, name)
+
+    def __dir__(self) -> list[str]:
+        base = ["_name", "_inputs", "_outputs", "_input_ports", "_output_ports"]
+        return base + self._input_ports + self._output_ports
+
+    def __or__(self, other: Node) -> ChoiceNode:
+        """Combine two nodes as alternatives using the | operator.
+
+        Returns a ChoiceNode that lets users pick which variant to run.
+
+        Example:
+            >>> tts = GradioNode("space1/tts", ...) | GradioNode("space2/tts", ...)
+            >>> # tts.audio works regardless of which variant is selected
+        """
+        if isinstance(other, ChoiceNode):
+            return ChoiceNode([self] + other._variants, name=self._name)
+        return ChoiceNode([self, other], name=self._name)
+
+    @property
+    def _inputs(self) -> PortNamespace:
+        return PortNamespace(self, self._input_ports)
+
+    @property
+    def _outputs(self) -> PortNamespace:
+        return PortNamespace(self, self._output_ports)
+
+    def _default_output_port(self) -> Port:
+        if self._output_ports:
+            return Port(self, self._output_ports[0])
+        return Port(self, "output")
+
+    def _default_input_port(self) -> Port:
+        if self._input_ports:
+            return Port(self, self._input_ports[0])
+        return Port(self, "input")
+
+    def _validate_ports(self):
+        all_ports = set(self._input_ports + self._output_ports)
+        underscore_ports = [p for p in all_ports if p.startswith("_")]
+        if underscore_ports:
+            warnings.warn(
+                f"Port names {underscore_ports} start with underscore. "
+                f"Use node._inputs.{underscore_ports[0]} or node._outputs.{underscore_ports[0]} to access."
+            )
+
+    def _process_inputs(self, inputs: dict[str, Any]) -> None:
+        for port_name, value in inputs.items():
+            self._input_ports.append(port_name)
+            if is_port(value):
+                self._port_connections[port_name] = value
+            elif _is_gradio_component(value):
+                _warn_if_type_set(value, port_name)
+                self._input_components[port_name] = value
+            else:
+                self._fixed_inputs[port_name] = value
+
+    def _process_outputs(self, outputs: dict[str, Any]) -> None:
+        for port_name, component in outputs.items():
+            self._output_ports.append(port_name)
+            if component is not None and _is_gradio_component(component):
+                _warn_if_type_set(component, port_name)
+                self._output_components[port_name] = component
+
+    def test(self, **inputs) -> dict[str, Any]:
+        """Test-run this node in isolation and return the raw result.
+
+        If no inputs are provided, auto-generates example values using:
+        - Gradio component's .example_value() method
+        - Port's associated output component's .example_value()
+        - Callable inputs are called
+        - Fixed values are used directly
+
+        Args:
+            **inputs: Override inputs for the test run.
+
+        Returns:
+            Dict mapping output port names to their values.
+
+        Example:
+            >>> tts = GradioNode("mrfakename/MeloTTS", api_name="/synthesize", ...)
+            >>> result = tts.test(text="Hello world", speaker="EN-US")
+            >>> # Returns: {"audio": "/path/to/audio.wav"}
+            >>>
+            >>> # Or with auto-generated example values:
+            >>> result = tts.test()
+        """
+        from daggr import Graph
+        from daggr.executor import SequentialExecutor
+
+        if not inputs:
+            inputs = self._generate_example_inputs()
+
+        graph = Graph("_test", nodes=[self], persist_key=False)
+        executor = SequentialExecutor(graph)
+        return executor.execute_node(self._name, inputs)
+
+    def _generate_example_inputs(self) -> dict[str, Any]:
+        """Generate example values for all input ports."""
+        examples = {}
+
+        # From input components (Gradio components)
+        for port_name, comp in self._input_components.items():
+            if hasattr(comp, "example_value"):
+                examples[port_name] = comp.example_value()
+
+        # From fixed inputs (constants, callables, or port connections)
+        for port_name, source in self._fixed_inputs.items():
+            if callable(source):
+                examples[port_name] = source()
+            else:
+                examples[port_name] = source
+
+        # From port connections (use the connected port's output component)
+        for port_name, port in self._port_connections.items():
+            if is_port(port):
+                comp = port._node._output_components.get(port._port_name)
+                if comp and hasattr(comp, "example_value"):
+                    examples[port_name] = comp.example_value()
+
+        return examples
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(name={self._name})"
+
+
+class ChoiceNode(Node):
+    """A node that wraps multiple alternative nodes.
+
+    ChoiceNode allows users to select which variant to run from a set of
+    alternatives. Created using the | operator between nodes.
+
+    The output ports are the union of all variants' output ports, so downstream
+    nodes can connect to any output that exists in at least one variant.
+
+    Args:
+        variants: List of Node objects that serve as alternatives.
+        name: Optional display name. Defaults to the first variant's name.
+
+    Example:
+        >>> tts = GradioNode("space1/tts", ...) | GradioNode("space2/tts", ...)
+        >>> # tts is a ChoiceNode with two variants
+        >>> # tts.audio works regardless of which variant is selected
+    """
+
+    def __init__(
+        self,
+        variants: list[Node],
+        name: str | None = None,
+    ):
+        if not variants:
+            raise ValueError("ChoiceNode requires at least one variant")
+
+        super().__init__(name)
+        self._variants = variants
+        self._selected_variant = 0
+
+        if not self._name:
+            self._name = variants[0]._name
+
+        self._output_ports = self._compute_union_output_ports()
+        self._output_components = self._compute_union_output_components()
+
+        for variant in variants:
+            for port_name, port in variant._port_connections.items():
+                if port_name not in self._port_connections:
+                    self._port_connections[port_name] = port
+
+    def _compute_union_output_ports(self) -> list[str]:
+        seen = set()
+        ports = []
+        for variant in self._variants:
+            for port in variant._output_ports:
+                if port not in seen:
+                    seen.add(port)
+                    ports.append(port)
+        return ports
+
+    def _compute_union_output_components(self) -> dict[str, Any]:
+        components = {}
+        for variant in self._variants:
+            for port_name, comp in variant._output_components.items():
+                if port_name not in components:
+                    components[port_name] = comp
+        return components
+
+    def __or__(self, other: Node) -> ChoiceNode:
+        if isinstance(other, ChoiceNode):
+            return ChoiceNode(self._variants + other._variants, name=self._name)
+        return ChoiceNode(self._variants + [other], name=self._name)
+
+    def __repr__(self):
+        variant_names = [v._name for v in self._variants]
+        return f"ChoiceNode(name={self._name}, variants={variant_names})"
+
+
+class GradioNode(Node):
+    """A node that wraps a Gradio Space or endpoint.
+
+    GradioNode connects to a Hugging Face Space or any Gradio app and exposes
+    its API as a node in the graph.
+
+    Args:
+        space_or_url: Hugging Face Space ID (e.g., "username/space-name") or
+            a full URL to a Gradio app.
+        api_name: The API endpoint to call (e.g., "/predict"). Defaults to "/predict".
+        name: Optional display name for the node.
+        inputs: Dict mapping input port names to Gradio components, Port connections,
+            or fixed values.
+        outputs: Dict mapping output port names to Gradio components for display.
+        validate: Whether to validate the Space exists and has the specified endpoint.
+        run_locally: If True, clone and run the Space locally instead of using the
+            remote API.
+
+    Example:
+        >>> tts = GradioNode(
+        ...     "mrfakename/MeloTTS",
+        ...     api_name="/synthesize",
+        ...     inputs={"text": gr.Textbox(), "speaker": "EN-US"},
+        ...     outputs={"audio": gr.Audio()},
+        ... )
+    """
+
+    _name_counters: dict[str, int] = {}
+
+    def __init__(
+        self,
+        space_or_url: str,
+        api_name: str | None = None,
+        name: str | None = None,
+        inputs: dict[str, Any] | None = None,
+        outputs: dict[str, Any] | None = None,
+        validate: bool = True,
+        run_locally: bool = False,
+        preprocess: Callable[[dict], dict] | None = None,
+        postprocess: Callable[..., Any] | None = None,
+    ):
+        super().__init__(name)
+        self._src = space_or_url
+        self._api_name = api_name
+        self._run_locally = run_locally
+        self._local_url: str | None = None
+        self._local_failed = False
+        self._preprocess = preprocess
+        self._postprocess = postprocess
+
+        if validate:
+            self._validate_space_format()
+
+        if not self._name:
+            base_name = self._src.split("/")[-1]
+            if base_name not in GradioNode._name_counters:
+                GradioNode._name_counters[base_name] = 0
+                self._name = base_name
+            else:
+                GradioNode._name_counters[base_name] += 1
+                self._name = f"{base_name}_{GradioNode._name_counters[base_name]}"
+
+        self._process_inputs(inputs or {})
+        self._process_outputs(outputs or {})
+        self._validate_ports()
+
+        if validate and not run_locally:
+            self._validate_gradio_api(inputs or {}, outputs or {})
+
+    def _validate_space_format(self) -> None:
+        src = self._src
+        if not ("/" in src or src.startswith("http://") or src.startswith("https://")):
+            raise ValueError(
+                f"Invalid space_or_url '{src}'. Expected format: 'username/space-name' "
+                f"or a full URL like 'https://...'"
+            )
+
+    def _get_api_info(self) -> dict:
+        from daggr import _client_cache
+
+        cached = _client_cache.get_api_info(self._src)
+        if cached is not None:
+            return cached
+
+        from gradio_client import Client
+
+        client = _client_cache.get_client(self._src)
+        if client is None:
+            client = Client(self._src, download_files=False, verbose=False)
+            _client_cache.set_client(self._src, client)
+
+        api_info = client.view_api(return_format="dict", print_info=False)
+        _client_cache.set_api_info(self._src, api_info)
+        return api_info
+
+    def _validate_gradio_api(
+        self, inputs: dict[str, Any], outputs: dict[str, Any]
+    ) -> None:
+        from daggr import _client_cache
+
+        api_name = self._api_name or "/predict"
+        if not api_name.startswith("/"):
+            api_name = "/" + api_name
+
+        cache_key = (
+            self._src,
+            api_name,
+            tuple(sorted(inputs.keys())),
+            tuple(sorted(outputs.keys())) if outputs else (),
+        )
+        if _client_cache.is_validated(cache_key):
+            return
+
+        api_info = self._get_api_info()
+
+        named_endpoints = api_info.get("named_endpoints", {})
+        unnamed_endpoints = api_info.get("unnamed_endpoints", {})
+
+        endpoint_info = None
+        if api_name in named_endpoints:
+            endpoint_info = named_endpoints[api_name]
+        else:
+            try:
+                fn_index = int(api_name.lstrip("/"))
+                if fn_index in unnamed_endpoints or str(fn_index) in unnamed_endpoints:
+                    endpoint_info = unnamed_endpoints.get(
+                        fn_index, unnamed_endpoints.get(str(fn_index))
+                    )
+            except ValueError:
+                pass
+
+        if endpoint_info is None:
+            available = list(named_endpoints.keys())
+            if unnamed_endpoints:
+                available.extend([f"/{k}" for k in unnamed_endpoints.keys()])
+            suggested = suggest_similar(api_name, set(available))
+            msg = (
+                f"API endpoint '{api_name}' not found in '{self._src}'. "
+                f"Available endpoints: {available}"
+            )
+            if suggested:
+                msg += f" Did you mean '{suggested}'?"
+            raise ValueError(msg)
+
+        params_info = endpoint_info.get("parameters", [])
+        valid_params = {p.get("parameter_name", p["label"]) for p in params_info}
+        input_params = set(inputs.keys())
+        invalid_params = input_params - valid_params
+
+        if invalid_params:
+            suggestions = {}
+            for inv in invalid_params:
+                suggestion = suggest_similar(inv, valid_params)
+                if suggestion:
+                    suggestions[inv] = suggestion
+            msg = (
+                f"Invalid parameter(s) {invalid_params} for endpoint '{api_name}' "
+                f"in '{self._src}'."
+            )
+            if suggestions:
+                suggestion_str = ", ".join(
+                    f"'{k}' -> '{v}'" for k, v in suggestions.items()
+                )
+                msg += f" Did you mean: {suggestion_str}?"
+            msg += f" Valid parameters: {valid_params}"
+            raise ValueError(msg)
+
+        required_params = {
+            p.get("parameter_name", p["label"])
+            for p in params_info
+            if not p.get("parameter_has_default", False)
+        }
+        provided_params = set(inputs.keys())
+        missing_required = required_params - provided_params
+
+        if missing_required:
+            raise ValueError(
+                f"Missing required parameter(s) {missing_required} for endpoint "
+                f"'{api_name}' in '{self._src}'. These parameters have no default values."
+            )
+
+        api_returns = endpoint_info.get("returns", [])
+        if outputs and api_returns and not self._postprocess:
+            num_returns = len(api_returns)
+            num_outputs = len(outputs)
+            if num_outputs > num_returns:
+                warnings.warn(
+                    f"GradioNode '{self._name}' defines {num_outputs} outputs but "
+                    f"endpoint '{api_name}' only returns {num_returns} value(s). "
+                    f"Extra outputs will be None."
+                )
+
+        _client_cache.mark_validated(cache_key)
+
+
+class InferenceNode(Node):
+    """A node that wraps a Hugging Face Inference API model.
+
+    InferenceNode uses the Hugging Face Inference API to run models without
+    needing to download them locally. The task type (text-generation, text-to-image,
+    etc.) is automatically determined from the model's pipeline_tag on the Hub.
+
+    Args:
+        model: The Hugging Face model ID (e.g., "meta-llama/Llama-2-7b-chat-hf").
+        name: Optional display name for the node.
+        inputs: Dict mapping input port names to values or components.
+        outputs: Dict mapping output port names to components.
+        validate: Whether to validate the model exists on the Hub.
+        preprocess: Optional function that receives the input dict and returns a
+            modified dict before the inference call.
+        postprocess: Optional function that receives the raw inference result and
+            returns a transformed value before it is mapped to output ports.
+
+    Example:
+        >>> llm = InferenceNode("meta-llama/Llama-2-7b-chat-hf")
+    """
+
+    def __init__(
+        self,
+        model: str,
+        name: str | None = None,
+        inputs: dict[str, Any] | None = None,
+        outputs: dict[str, Any] | None = None,
+        validate: bool = True,
+        preprocess: Callable[[dict], dict] | None = None,
+        postprocess: Callable[..., Any] | None = None,
+    ):
+        super().__init__(name)
+        self._model = model
+        self._task: str | None = None
+        self._task_fetched: bool = False
+        self._preprocess = preprocess
+        self._postprocess = postprocess
+
+        if not self._name:
+            # Strip provider tag (e.g., ":replicate") for display name
+            self._name = self._model_name_for_hub.split("/")[-1]
+
+        if inputs:
+            self._process_inputs(inputs)
+        else:
+            self._input_ports = ["input"]
+
+        if outputs:
+            self._process_outputs(outputs)
+        else:
+            self._output_ports = ["output"]
+
+        self._validate_ports()
+
+        if validate:
+            self._fetch_model_info()
+
+    @property
+    def _model_name_for_hub(self) -> str:
+        """Return the model name without provider tags (e.g., ':replicate')."""
+        # HF Inference Client allows tags like "model:provider" for routing
+        # Strip these for Hub API calls and display
+        return self._model.split(":")[0]
+
+    @property
+    def _provider(self) -> str | None:
+        """Return the provider tag if specified (e.g., 'replicate' from 'model:replicate')."""
+        parts = self._model.split(":")
+        return parts[1] if len(parts) > 1 else None
+
+    def _fetch_model_info(self) -> None:
+        if self._task_fetched:
+            return
+
+        from daggr import _client_cache
+
+        # Use model name without provider tag for Hub lookups
+        hub_model = self._model_name_for_hub
+
+        found_in_cache, cached = _client_cache.get_model_task(hub_model)
+        if found_in_cache:
+            if cached == "__NOT_FOUND__":
+                raise ValueError(f"Model '{hub_model}' not found on Hugging Face Hub.")
+            self._task = cached
+            self._task_fetched = True
+            return
+
+        from huggingface_hub import model_info
+        from huggingface_hub.utils import RepositoryNotFoundError
+
+        try:
+            info = model_info(hub_model)
+            self._task = info.pipeline_tag
+            _client_cache.set_model_task(hub_model, self._task)
+            self._task_fetched = True
+        except RepositoryNotFoundError:
+            _client_cache.set_model_not_found(hub_model)
+            raise ValueError(
+                f"Model '{hub_model}' not found on Hugging Face Hub. "
+                f"Please check the model name is correct (format: 'username/model-name')."
+            )
+
+
+class FnNode(Node):
+    """A node that wraps a Python function.
+
+    FnNode allows you to use any Python function as a node in the graph.
+    Input ports are automatically discovered from the function signature.
+
+    Return values are mapped to output ports in order, just like GradioNode:
+    - Single value: maps to the first output port
+    - Tuple: each element maps to the corresponding output port in order
+
+    Concurrency:
+        By default, FnNodes execute sequentially (one at a time per session)
+        to prevent resource contention. Use the concurrency parameters to
+        allow parallel execution:
+
+        - concurrent=True: Allow this node to run in parallel with others
+        - concurrency_group: Group nodes that share a resource (e.g., GPU)
+        - max_concurrent: Max parallel executions within a group (default: 1)
+
+        Note: GradioNode and InferenceNode always run concurrently since they
+        are external API calls. Prefer these over FnNode when possible.
+
+    Args:
+        fn: The Python function to wrap.
+        name: Optional display name. Defaults to the function name.
+        inputs: Optional dict to explicitly define input ports and their
+            connections or UI components.
+        outputs: Optional dict mapping output port names to UI components
+            or ItemList schemas.
+        concurrent: If True, allow parallel execution. Default: False.
+        concurrency_group: Name of a group sharing a concurrency limit.
+        max_concurrent: Max parallel executions in the group. Default: 1.
+
+    Example:
+        >>> def process_text(text: str) -> tuple[str, int]:
+        ...     return text.upper(), len(text)
+        >>> node = FnNode(
+        ...     process_text,
+        ...     outputs={"uppercase": gr.Textbox(), "length": gr.Number()}
+        ... )
+
+        >>> # Allow parallel execution
+        >>> node = FnNode(my_func, concurrent=True)
+
+        >>> # Share GPU with other nodes (max 2 concurrent)
+        >>> node = FnNode(gpu_func, concurrency_group="gpu", max_concurrent=2)
+    """
+
+    def __init__(
+        self,
+        fn: Callable,
+        name: str | None = None,
+        inputs: dict[str, Any] | None = None,
+        outputs: dict[str, Any] | None = None,
+        preprocess: Callable[[dict], dict] | None = None,
+        postprocess: Callable[..., Any] | None = None,
+        concurrent: bool = False,
+        concurrency_group: str | None = None,
+        max_concurrent: int = 1,
+    ):
+        super().__init__(name)
+        self._fn = fn
+        self._preprocess = preprocess
+        self._postprocess = postprocess
+        self._concurrent = concurrent
+        self._concurrency_group = concurrency_group
+        self._max_concurrent = max_concurrent
+
+        if not self._name:
+            self._name = self._fn.__name__
+
+        if inputs:
+            self._validate_fn_inputs(inputs)
+            self._process_inputs(inputs)
+        else:
+            self._discover_signature()
+
+        if outputs:
+            self._process_outputs(outputs)
+        else:
+            self._output_ports = ["output"]
+
+        self._validate_ports()
+
+    def _discover_signature(self):
+        sig = inspect.signature(self._fn)
+        self._input_ports = list(sig.parameters.keys())
+
+    def _validate_fn_inputs(self, inputs: dict[str, Any]) -> None:
+        sig = inspect.signature(self._fn)
+        valid_params = set(sig.parameters.keys())
+        provided_params = set(inputs.keys())
+        invalid_params = provided_params - valid_params
+
+        if invalid_params:
+            suggestions = {}
+            for inv in invalid_params:
+                suggestion = suggest_similar(inv, valid_params)
+                if suggestion:
+                    suggestions[inv] = suggestion
+
+            msg = (
+                f"Invalid input(s) {invalid_params} for function '{self._fn.__name__}'."
+            )
+            if suggestions:
+                suggestion_str = ", ".join(
+                    f"'{k}' -> '{v}'" for k, v in suggestions.items()
+                )
+                msg += f" Did you mean: {suggestion_str}?"
+            msg += f" Valid parameters: {valid_params}"
+            raise ValueError(msg)
+
+    def _process_outputs(self, outputs: dict[str, Any]) -> None:
+        for port_name, component in outputs.items():
+            self._output_ports.append(port_name)
+            if component is None:
+                continue
+            if isinstance(component, ItemList):
+                self._item_list_schemas[port_name] = component.schema
+            elif _is_gradio_component(component):
+                self._output_components[port_name] = component
+
+
+class InteractionNode(Node):
+    """A node representing a user interaction point in the graph.
+
+    InteractionNodes pause execution and wait for user input before continuing.
+    They are used for approval steps, selections, or other human-in-the-loop
+    interactions.
+
+    Args:
+        name: Optional display name for the node.
+        interaction_type: Type of interaction (e.g., "generic", "approve", "choose_one").
+        inputs: Dict mapping input port names to components or connections.
+        outputs: Dict mapping output port names to components.
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        interaction_type: str = "generic",
+        inputs: dict[str, Any] | None = None,
+        outputs: dict[str, Any] | None = None,
+    ):
+        super().__init__(name)
+        self._interaction_type = interaction_type
+
+        if inputs:
+            self._process_inputs(inputs)
+        else:
+            self._input_ports = ["input"]
+
+        if outputs:
+            self._process_outputs(outputs)
+        else:
+            self._output_ports = ["output"]
+
+        if not self._name:
+            self._name = f"interaction_{self._id}"
+
+        self._validate_ports()

daggr/ops.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from daggr.node import InteractionNode
+
+
+class ChooseOne(InteractionNode):
+    _instance_counter = 0
+
+    def __init__(self, name: str | None = None):
+        ChooseOne._instance_counter += 1
+        super().__init__(
+            name=name or f"choose_one_{ChooseOne._instance_counter}",
+            interaction_type="choose_one",
+        )
+        self._input_ports = ["options"]
+        self._output_ports = ["selected"]
+
+
+class Approve(InteractionNode):
+    _instance_counter = 0
+
+    def __init__(self, name: str | None = None):
+        Approve._instance_counter += 1
+        super().__init__(
+            name=name or f"approve_{Approve._instance_counter}",
+            interaction_type="approve",
+        )
+        self._input_ports = ["input"]
+        self._output_ports = ["output"]
+
+
+class TextInput(InteractionNode):
+    _instance_counter = 0
+
+    def __init__(self, name: str | None = None, label: str = "Input"):
+        TextInput._instance_counter += 1
+        super().__init__(
+            name=name or f"text_input_{TextInput._instance_counter}",
+            interaction_type="text_input",
+        )
+        self._label = label
+        self._input_ports = []
+        self._output_ports = ["text"]
+
+
+class ImageInput(InteractionNode):
+    _instance_counter = 0
+
+    def __init__(self, name: str | None = None, label: str = "Image"):
+        ImageInput._instance_counter += 1
+        super().__init__(
+            name=name or f"image_input_{ImageInput._instance_counter}",
+            interaction_type="image_input",
+        )
+        self._label = label
+        self._input_ports = []
+        self._output_ports = ["image"]

daggr/package.json

@@ -0,0 +1,6 @@
+{
+	"name": "daggr",
+	"version": "0.7.0",
+	"description": "",
+	"python": "true"
+}

daggr/port.py

@@ -0,0 +1,158 @@
+"""Port module for node input/output definitions.
+
+Ports are named connection points on nodes. Output ports can be connected
+to input ports to form edges in the graph.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from daggr.node import Node
+
+
+class Port:
+    """A named connection point on a node.
+
+    Ports represent inputs or outputs of a node. Access them as attributes
+    on a node: `node.port_name`.
+
+    Attributes:
+        node: The node this port belongs to.
+        name: The name of the port.
+    """
+
+    def __init__(self, node: Node, name: str):
+        self.node = node
+        self.name = name
+
+    def __repr__(self):
+        return f"Port({self.node._name}.{self.name})"
+
+    def _as_source(self) -> tuple[Node, str]:
+        return (self.node, self.name)
+
+    def _as_target(self) -> tuple[Node, str]:
+        return (self.node, self.name)
+
+    def __getattr__(self, attr: str) -> ScatteredPort:
+        if attr.startswith("_"):
+            raise AttributeError(attr)
+        if (
+            hasattr(self.node, "_item_list_schemas")
+            and self.name in self.node._item_list_schemas
+        ):
+            schema = self.node._item_list_schemas[self.name]
+            if attr in schema:
+                return ScatteredPort(self, attr)
+        raise AttributeError(f"Port '{self.name}' has no attribute '{attr}'")
+
+    @property
+    def each(self) -> ScatteredPort:
+        """Scatter this port's output - run the downstream node once per item in the list."""
+        return ScatteredPort(self)
+
+    def all(self) -> GatheredPort:
+        """Gather outputs from a scattered node back into a list."""
+        return GatheredPort(self)
+
+
+class ScatteredPort:
+    """A port that scatters its list output to run downstream nodes per-item.
+
+    Created by accessing `.each` on a port. When connected to a downstream
+    node, that node will be executed once for each item in the list.
+    """
+
+    def __init__(self, port: Port, item_key: str | None = None):
+        self.port = port
+        self.item_key = item_key
+
+    @property
+    def node(self):
+        return self.port.node
+
+    @property
+    def name(self):
+        return self.port.name
+
+    def __getitem__(self, key: str) -> ScatteredPort:
+        """Access a specific field from each scattered item (e.g., dialogue.json.each["text"])."""
+        return ScatteredPort(self.port, key)
+
+    def __repr__(self):
+        if self.item_key:
+            return f"ScatteredPort({self.port}['{self.item_key}'])"
+        return f"ScatteredPort({self.port})"
+
+
+class GatheredPort:
+    """A port that gathers scattered results back into a list.
+
+    Created by calling `.all()` on a port. Collects results from all
+    scattered executions back into a single list.
+    """
+
+    def __init__(self, port: Port):
+        self.port = port
+
+    @property
+    def node(self):
+        return self.port.node
+
+    @property
+    def name(self):
+        return self.port.name
+
+    def __repr__(self):
+        return f"GatheredPort({self.port})"
+
+
+PortLike = Port | ScatteredPort | GatheredPort
+
+
+def is_port(obj: Any) -> bool:
+    """Check if an object is a Port, ScatteredPort, or GatheredPort."""
+    return isinstance(obj, (Port, ScatteredPort, GatheredPort))
+
+
+class PortNamespace:
+    """A namespace for accessing ports that start with underscores.
+
+    Used via `node._inputs` or `node._outputs` to access ports whose names
+    start with underscores (which can't be accessed directly as attributes).
+    """
+
+    def __init__(self, node: Node, port_names: list[str]):
+        self._node = node
+        self._names = set(port_names)
+
+    def __getattr__(self, name: str) -> Port:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return Port(self._node, name)
+
+    def __dir__(self) -> list[str]:
+        return list(self._names)
+
+    def __repr__(self):
+        return f"PortNamespace({list(self._names)})"
+
+
+class ItemList:
+    """Define an editable list output with per-item schema.
+
+    Example:
+        outputs={
+            "items": ItemList(
+                speaker=gr.Dropdown(choices=["Host", "Guest"]),
+                text=gr.Textbox(lines=2),
+            ),
+        }
+
+    The function should return a list of dicts matching the schema keys.
+    """
+
+    def __init__(self, **schema):
+        self.schema = schema

daggr/server.py

@@ -0,0 +1,1946 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import mimetypes
+import os
+import secrets
+import socket
+import tempfile
+import threading
+import time
+import traceback
+import uuid
+import webbrowser
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import uvicorn
+from fastapi import FastAPI, Header, Request, WebSocket, WebSocketDisconnect
+from fastapi.responses import (
+    FileResponse,
+    HTMLResponse,
+    JSONResponse,
+    PlainTextResponse,
+    Response,
+)
+from gradio_client.utils import is_file_obj_with_meta
+
+from daggr.executor import AsyncExecutor, FileValue
+from daggr.node import (
+    _FILE_TYPE_COMPONENTS,
+    ChoiceNode,
+    GradioNode,
+    InferenceNode,
+    InteractionNode,
+)
+from daggr.session import ExecutionSession
+from daggr.state import SessionState, get_daggr_cache_dir
+
+_FILE_COMP_TYPES = {c.lower() for c in _FILE_TYPE_COMPONENTS}
+
+if TYPE_CHECKING:
+    from gradio.themes import Base as Theme
+
+    from daggr.graph import Graph
+
+
+INITIAL_PORT_VALUE = int(os.getenv("DAGGR_SERVER_PORT", "7860"))
+TRY_NUM_PORTS = int(os.getenv("DAGGR_NUM_PORTS", "100"))
+
+
+def _find_available_port(host: str, start_port: int) -> int:
+    """Find an available port starting from start_port."""
+    for port in range(start_port, start_port + TRY_NUM_PORTS):
+        try:
+            s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host if host != "0.0.0.0" else "127.0.0.1", port))
+            s.close()
+            return port
+        except OSError:
+            continue
+    raise OSError(
+        f"Cannot find empty port in range: {start_port}-{start_port + TRY_NUM_PORTS - 1}. "
+        f"You can specify a different port by setting the DAGGR_SERVER_PORT environment variable "
+        f"or passing the port parameter to launch()."
+    )
+
+
+def _get_theme(theme: "Theme | str | None") -> "Theme":
+    """Get a Gradio theme instance from a theme specification.
+
+    Args:
+        theme: Can be a Theme instance, a string name like "default", "soft",
+            "monochrome", "glass", or a Hub theme like "gradio/seafoam".
+
+    Returns:
+        A Theme instance.
+    """
+    from gradio.themes import Default
+
+    if theme is None:
+        return Default()
+
+    if isinstance(theme, str):
+        from gradio.themes import Base, Default, Glass, Monochrome, Soft
+
+        theme_mapping = {
+            "default": Default,
+            "soft": Soft,
+            "monochrome": Monochrome,
+            "glass": Glass,
+            "base": Base,
+        }
+        theme_lower = theme.lower()
+        if theme_lower in theme_mapping:
+            return theme_mapping[theme_lower]()
+        # Try loading from Hub
+        try:
+            return Base.from_hub(theme)
+        except Exception:
+            return Default()
+
+    return theme
+
+
+class DaggrServer:
+    def __init__(
+        self,
+        graph: Graph,
+        theme: "Theme | str | None" = None,
+        api_server: bool = True,
+    ):
+        self.graph = graph
+        self.api_server = api_server
+        self.executor = AsyncExecutor(graph)
+        self.state = SessionState(db_path=os.environ.get("DAGGR_DB_PATH"))
+        self.app = FastAPI(title=graph.name)
+        self.connections: dict[str, WebSocket] = {}
+        self.theme = _get_theme(theme)
+        self.theme_css = self.theme._get_theme_css()
+        self._setup_routes()
+
+    def _extract_token_from_header(self, authorization: str | None) -> str | None:
+        if authorization and authorization.startswith("Bearer "):
+            return authorization[7:]
+        return None
+
+    def _validate_hf_token(self, token: str) -> dict | None:
+        try:
+            from huggingface_hub import whoami
+
+            info = whoami(token=token, cache=True)
+            return {
+                "username": info.get("name"),
+                "fullname": info.get("fullname"),
+                "avatar_url": info.get("avatarUrl"),
+            }
+        except Exception:
+            return None
+
+    def _setup_routes(self):
+        frontend_dir = Path(__file__).parent / "frontend" / "dist"
+        if not frontend_dir.exists():
+            raise RuntimeError(
+                f"Frontend not found at {frontend_dir}. "
+                "If developing, run 'npm run build' in daggr/frontend/"
+            )
+
+        @self.app.get("/theme.css", response_class=PlainTextResponse)
+        async def get_theme_css():
+            return PlainTextResponse(self.theme_css, media_type="text/css")
+
+        @self.app.get("/api/graph")
+        async def get_graph():
+            return self._build_graph_data()
+
+        @self.app.get("/api/hf_user")
+        async def get_hf_user():
+            return self._get_hf_user_info()
+
+        @self.app.get("/api/user_info")
+        async def get_user_info(authorization: str | None = Header(default=None)):
+            browser_token = self._extract_token_from_header(authorization)
+            if browser_token:
+                hf_user = self._validate_hf_token(browser_token)
+            else:
+                hf_user = self._get_hf_user_info()
+            user_id = self.state.get_effective_user_id(hf_user)
+            is_on_spaces = os.environ.get("SPACE_ID") is not None
+            persistence_enabled = self.graph.persist_key is not None
+            return {
+                "hf_user": hf_user,
+                "user_id": user_id,
+                "is_on_spaces": is_on_spaces,
+                "can_persist": user_id is not None and persistence_enabled,
+            }
+
+        @self.app.post("/api/auth/login")
+        async def auth_login(request: Request):
+            try:
+                body = await request.json()
+                token = body.get("token")
+                if not token:
+                    return JSONResponse({"error": "Token is required"}, status_code=400)
+                hf_user = self._validate_hf_token(token)
+                if not hf_user:
+                    return JSONResponse({"error": "Invalid token"}, status_code=401)
+                return {"hf_user": hf_user, "success": True}
+            except Exception as e:
+                return JSONResponse({"error": str(e)}, status_code=500)
+
+        @self.app.post("/api/auth/logout")
+        async def auth_logout():
+            return {"success": True}
+
+        @self.app.get("/api/sheets")
+        async def list_sheets(authorization: str | None = Header(default=None)):
+            if not self.graph.persist_key:
+                return {"sheets": [], "user_id": None}
+            browser_token = self._extract_token_from_header(authorization)
+            if browser_token:
+                hf_user = self._validate_hf_token(browser_token)
+            else:
+                hf_user = self._get_hf_user_info()
+            user_id = self.state.get_effective_user_id(hf_user)
+            if not user_id:
+                return JSONResponse(
+                    {"error": "Login required to access sheets on Spaces"},
+                    status_code=401,
+                )
+            sheets = self.state.list_sheets(user_id, self.graph.persist_key)
+            return {"sheets": sheets, "user_id": user_id}
+
+        @self.app.post("/api/sheets")
+        async def create_sheet(
+            request: Request, authorization: str | None = Header(default=None)
+        ):
+            if not self.graph.persist_key:
+                return JSONResponse(
+                    {"error": "Persistence is disabled for this graph"},
+                    status_code=400,
+                )
+            browser_token = self._extract_token_from_header(authorization)
+            if browser_token:
+                hf_user = self._validate_hf_token(browser_token)
+            else:
+                hf_user = self._get_hf_user_info()
+            user_id = self.state.get_effective_user_id(hf_user)
+            if not user_id:
+                return JSONResponse(
+                    {"error": "Login required to create sheets on Spaces"},
+                    status_code=401,
+                )
+            body = await request.json()
+            name = body.get("name")
+            sheet_id = self.state.create_sheet(user_id, self.graph.persist_key, name)
+            sheet = self.state.get_sheet(sheet_id)
+            return {"sheet": sheet}
+
+        @self.app.patch("/api/sheets/{sheet_id}")
+        async def rename_sheet(
+            sheet_id: str,
+            request: Request,
+            authorization: str | None = Header(default=None),
+        ):
+            browser_token = self._extract_token_from_header(authorization)
+            if browser_token:
+                hf_user = self._validate_hf_token(browser_token)
+            else:
+                hf_user = self._get_hf_user_info()
+            user_id = self.state.get_effective_user_id(hf_user)
+            if not user_id:
+                return JSONResponse({"error": "Login required"}, status_code=401)
+            sheet = self.state.get_sheet(sheet_id)
+            if not sheet:
+                return JSONResponse({"error": "Sheet not found"}, status_code=404)
+            if sheet["user_id"] != user_id:
+                return JSONResponse({"error": "Access denied"}, status_code=403)
+            body = await request.json()
+            new_name = body.get("name")
+            if not new_name:
+                return JSONResponse({"error": "Name required"}, status_code=400)
+            self.state.rename_sheet(sheet_id, new_name)
+            return {"success": True, "sheet": self.state.get_sheet(sheet_id)}
+
+        @self.app.delete("/api/sheets/{sheet_id}")
+        async def delete_sheet(
+            sheet_id: str, authorization: str | None = Header(default=None)
+        ):
+            browser_token = self._extract_token_from_header(authorization)
+            if browser_token:
+                hf_user = self._validate_hf_token(browser_token)
+            else:
+                hf_user = self._get_hf_user_info()
+            user_id = self.state.get_effective_user_id(hf_user)
+            if not user_id:
+                return JSONResponse({"error": "Login required"}, status_code=401)
+            sheet = self.state.get_sheet(sheet_id)
+            if not sheet:
+                return JSONResponse({"error": "Sheet not found"}, status_code=404)
+            if sheet["user_id"] != user_id:
+                return JSONResponse({"error": "Access denied"}, status_code=403)
+            self.state.delete_sheet(sheet_id)
+            return {"success": True}
+
+        @self.app.get("/api/sheets/{sheet_id}/state")
+        async def get_sheet_state(
+            sheet_id: str, authorization: str | None = Header(default=None)
+        ):
+            browser_token = self._extract_token_from_header(authorization)
+            if browser_token:
+                hf_user = self._validate_hf_token(browser_token)
+            else:
+                hf_user = self._get_hf_user_info()
+            user_id = self.state.get_effective_user_id(hf_user)
+            if not user_id:
+                return JSONResponse({"error": "Login required"}, status_code=401)
+            sheet = self.state.get_sheet(sheet_id)
+            if not sheet:
+                return JSONResponse({"error": "Sheet not found"}, status_code=404)
+            if sheet["user_id"] != user_id:
+                return JSONResponse({"error": "Access denied"}, status_code=403)
+            state = self.state.get_sheet_state(sheet_id)
+            return {"sheet": sheet, "state": state}
+
+        @self.app.post("/api/run/{node_name}")
+        async def run_to_node(node_name: str, data: dict):
+            session = ExecutionSession(self.graph)
+            session_id = data.get("session_id")
+            input_values = data.get("inputs", {})
+            selected_results = data.get("selected_results", {})
+            return await self._execute_to_node(
+                session, node_name, session_id, input_values, selected_results
+            )
+
+        if self.api_server:
+
+            @self.app.get("/api/schema")
+            async def get_api_schema():
+                return self.graph.get_api_schema()
+
+            @self.app.post("/api/call")
+            async def call_workflow(request: Request):
+                return await self._execute_workflow_api(request, subgraph_id=None)
+
+            @self.app.post("/api/call/{subgraph_id}")
+            async def call_subgraph(subgraph_id: str, request: Request):
+                return await self._execute_workflow_api(
+                    request, subgraph_id=subgraph_id
+                )
+
+        @self.app.websocket("/ws/{session_id}")
+        async def websocket_endpoint(websocket: WebSocket, session_id: str):
+            await websocket.accept()
+            self.connections[session_id] = websocket
+
+            hf_user = self._get_hf_user_info()
+            user_id = self.state.get_effective_user_id(hf_user)
+            current_sheet_id: str | None = None
+
+            session = ExecutionSession(self.graph)
+            running_tasks: dict[str, asyncio.Task] = {}
+
+            async def run_node_execution(
+                node_name: str,
+                sheet_id: str | None,
+                input_values: dict,
+                item_list_values: dict,
+                selected_results: dict,
+                run_id: str,
+                user_id: str | None,
+                run_ancestors: bool = True,
+            ):
+                try:
+                    async for result in self._execute_to_node_streaming(
+                        session,
+                        node_name,
+                        sheet_id,
+                        input_values,
+                        item_list_values,
+                        selected_results,
+                        run_id,
+                        user_id,
+                        run_ancestors,
+                    ):
+                        await websocket.send_json(result)
+                except asyncio.CancelledError:
+                    pass
+                except Exception as e:
+                    await websocket.send_json(
+                        {
+                            "type": "error",
+                            "run_id": run_id,
+                            "error": str(e),
+                            "node": node_name,
+                        }
+                    )
+
+            try:
+                while True:
+                    data = await websocket.receive_json()
+                    action = data.get("action")
+
+                    if "hf_token" in data:
+                        browser_hf_token = data.get("hf_token")
+                        old_user_id = user_id
+                        if browser_hf_token:
+                            hf_user = self._validate_hf_token(browser_hf_token)
+                            user_id = self.state.get_effective_user_id(hf_user)
+                            session.set_hf_token(browser_hf_token)
+                        else:
+                            hf_user = self._get_hf_user_info()
+                            user_id = self.state.get_effective_user_id(hf_user)
+                            session.set_hf_token(None)
+                        if old_user_id != user_id:
+                            session.clear_results()
+                            current_sheet_id = None
+
+                    if action == "run":
+                        node_name = data.get("node_name")
+                        input_values = data.get("inputs", {})
+                        item_list_values = data.get("item_list_values", {})
+                        selected_results = data.get("selected_results", {})
+                        run_id = data.get("run_id")
+                        sheet_id = data.get("sheet_id") or current_sheet_id
+                        run_ancestors = data.get("run_ancestors", True)
+
+                        task = asyncio.create_task(
+                            run_node_execution(
+                                node_name,
+                                sheet_id,
+                                input_values,
+                                item_list_values,
+                                selected_results,
+                                run_id,
+                                user_id,
+                                run_ancestors,
+                            )
+                        )
+                        running_tasks[run_id] = task
+                        task.add_done_callback(
+                            lambda t, rid=run_id: running_tasks.pop(rid, None)
+                        )
+
+                    elif action == "cancel":
+                        cancel_run_id = data.get("run_id")
+                        cancel_node = data.get("node_name")
+                        task = running_tasks.get(cancel_run_id)
+                        if task:
+                            task.cancel()
+                        await websocket.send_json(
+                            {
+                                "type": "cancelled",
+                                "run_id": cancel_run_id,
+                                "node": cancel_node,
+                            }
+                        )
+
+                    elif action == "get_graph":
+                        try:
+                            sheet_id = data.get("sheet_id")
+
+                            persisted_inputs = {}
+                            persisted_results: dict[str, list[Any]] = {}
+                            persisted_transform = None
+
+                            if user_id and sheet_id:
+                                sheet = self.state.get_sheet(sheet_id)
+                                if sheet and sheet["user_id"] == user_id:
+                                    current_sheet_id = sheet_id
+                                    state = self.state.get_sheet_state(sheet_id)
+                                    persisted_inputs = state.get("inputs", {})
+                                    persisted_results = state.get("results", {})
+                                    persisted_transform = sheet.get("transform")
+
+                            node_results = {}
+                            for node_name, results_list in persisted_results.items():
+                                if results_list:
+                                    last_entry = results_list[-1]
+                                    if (
+                                        isinstance(last_entry, dict)
+                                        and "result" in last_entry
+                                    ):
+                                        node_results[node_name] = last_entry["result"]
+                                    else:
+                                        node_results[node_name] = last_entry
+
+                            graph_data = self._build_graph_data(
+                                node_results=node_results,
+                                input_values=persisted_inputs,
+                            )
+                            graph_data["session_id"] = session_id
+                            graph_data["sheet_id"] = current_sheet_id
+                            graph_data["user_id"] = user_id
+                            graph_data["persisted_results"] = (
+                                self._transform_persisted_results(persisted_results)
+                            )
+                            graph_data["transform"] = persisted_transform
+
+                            await websocket.send_json(
+                                {"type": "graph", "data": graph_data}
+                            )
+                        except Exception as e:
+                            print(f"[ERROR] get_graph failed: {e}")
+                            traceback.print_exc()
+                            await websocket.send_json(
+                                {"type": "error", "error": str(e)}
+                            )
+
+                    elif action == "save_input":
+                        if user_id and current_sheet_id:
+                            node_id = data.get("node_id")
+                            port_name = data.get("port_name")
+                            value = data.get("value")
+                            if node_id and port_name is not None:
+                                self.state.save_input(
+                                    current_sheet_id, node_id, port_name, value
+                                )
+                                await websocket.send_json(
+                                    {"type": "input_saved", "node_id": node_id}
+                                )
+
+                    elif action == "save_transform":
+                        if user_id and current_sheet_id:
+                            x = data.get("x", 0)
+                            y = data.get("y", 0)
+                            scale = data.get("scale", 1)
+                            self.state.save_transform(current_sheet_id, x, y, scale)
+
+                    elif action == "set_sheet":
+                        sheet_id = data.get("sheet_id")
+                        if user_id and sheet_id:
+                            sheet = self.state.get_sheet(sheet_id)
+                            if sheet and sheet["user_id"] == user_id:
+                                current_sheet_id = sheet_id
+                                session.clear_results()
+                                await websocket.send_json(
+                                    {"type": "sheet_set", "sheet_id": sheet_id}
+                                )
+
+                    elif action == "save_variant_selection":
+                        node_id = data.get("node_id")
+                        variant_index = data.get("variant_index", 0)
+                        if user_id and current_sheet_id and node_id is not None:
+                            self.state.save_input(
+                                current_sheet_id,
+                                node_id,
+                                "_selected_variant",
+                                variant_index,
+                            )
+                            await websocket.send_json(
+                                {
+                                    "type": "variant_selection_saved",
+                                    "node_id": node_id,
+                                    "variant_index": variant_index,
+                                }
+                            )
+
+                    elif action == "clear_sheet":
+                        if user_id and current_sheet_id:
+                            self.state.clear_sheet_data(current_sheet_id)
+                            await websocket.send_json({"type": "sheet_cleared"})
+
+            except WebSocketDisconnect:
+                for task in running_tasks.values():
+                    task.cancel()
+                if session_id in self.connections:
+                    del self.connections[session_id]
+            except Exception as e:
+                for task in running_tasks.values():
+                    task.cancel()
+                print(f"[ERROR] WebSocket error: {e}")
+                traceback.print_exc()
+
+        @self.app.get("/")
+        async def serve_index():
+            index_path = frontend_dir / "index.html"
+            if index_path.exists():
+                return FileResponse(index_path)
+            return HTMLResponse(self._get_dev_html())
+
+        @self.app.get("/assets/{path:path}")
+        async def serve_assets(path: str):
+            file_path = frontend_dir / "assets" / path
+            if file_path.exists():
+                content_type, _ = mimetypes.guess_type(str(file_path))
+                return FileResponse(file_path, media_type=content_type)
+            return Response(status_code=404)
+
+        @self.app.get("/daggr-assets/{path:path}")
+        async def serve_daggr_assets(path: str):
+            assets_dir = Path(__file__).parent / "assets"
+            file_path = assets_dir / path
+            if file_path.exists():
+                content_type, _ = mimetypes.guess_type(str(file_path))
+                return FileResponse(file_path, media_type=content_type)
+            return Response(status_code=404)
+
+        @self.app.get("/file/{path:path}")
+        async def serve_local_file(path: str):
+            if len(path) >= 2 and path[1] == ":":
+                file_path = Path(path)
+            else:
+                file_path = Path("/") / path
+            temp_dir = Path(tempfile.gettempdir()).resolve()
+            daggr_cache = get_daggr_cache_dir().resolve()
+
+            try:
+                resolved = file_path.resolve()
+                is_allowed = str(resolved).startswith(str(temp_dir)) or str(
+                    resolved
+                ).startswith(str(daggr_cache))
+                if not is_allowed:
+                    return Response(status_code=403)
+            except (ValueError, OSError):
+                return Response(status_code=403)
+            if resolved.exists() and resolved.is_file():
+                content_type, _ = mimetypes.guess_type(str(resolved))
+                return FileResponse(
+                    resolved, media_type=content_type or "application/octet-stream"
+                )
+            return Response(status_code=404)
+
+        @self.app.get("/{path:path}")
+        async def serve_static(path: str):
+            if path.startswith("api/") or path.startswith("ws/"):
+                return Response(status_code=404)
+            file_path = frontend_dir / path
+            if file_path.exists() and file_path.is_file():
+                return FileResponse(file_path)
+            index_path = frontend_dir / "index.html"
+            if index_path.exists():
+                return FileResponse(index_path)
+            return HTMLResponse(self._get_dev_html())
+
+    def _get_dev_html(self) -> str:
+        return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{self.graph.name}</title>
+    <link rel="stylesheet" href="/theme.css">
+    <style>
+        * {{ margin: 0; box-sizing: border-box; }}
+        body {{
+            background: var(--body-background-fill, #000);
+            min-height: 100vh;
+            font-family: 'Space Grotesk', -apple-system, BlinkMacSystemFont, sans-serif;
+            overflow: hidden;
+            color: var(--body-text-color, #fff);
+        }}
+    </style>
+    <script type="module" src="http://localhost:5173/src/main.ts"></script>
+</head>
+<body class="dark">
+    <div id="app"></div>
+</body>
+</html>"""
+
+    def _get_node_url(self, node) -> str | None:
+        if isinstance(node, GradioNode):
+            src = node._src
+            if src.startswith("http://") or src.startswith("https://"):
+                return src
+            elif "/" in src:
+                return f"https://huggingface.co/spaces/{src}"
+        elif isinstance(node, InferenceNode):
+            return f"https://huggingface.co/{node._model_name_for_hub}"
+        return None
+
+    def _get_node_type(self, node, node_name: str) -> str:
+        type_map = {
+            "FnNode": "FN",
+            "TextInput": "INPUT",
+            "ImageInput": "IMAGE",
+            "ChooseOne": "SELECT",
+            "Approve": "APPROVE",
+            "GradioNode": "GRADIO",
+            "InferenceNode": "MODEL",
+            "InteractionNode": "ACTION",
+            "ChoiceNode": "CHOICE",
+        }
+        if isinstance(node, ChoiceNode):
+            return "CHOICE"
+        class_name = node.__class__.__name__
+        return type_map.get(class_name, class_name.upper())
+
+    def _has_scattered_input(self, node_name: str) -> bool:
+        for edge in self.graph._edges:
+            if edge.target_node._name == node_name and edge.is_scattered:
+                return True
+        return False
+
+    def _get_scattered_edge(self, node_name: str):
+        for edge in self.graph._edges:
+            if edge.target_node._name == node_name and edge.is_scattered:
+                return edge
+        return None
+
+    def _is_output_node(self, node_name: str) -> bool:
+        return self.graph._nx_graph.out_degree(node_name) == 0
+
+    def _is_running_locally(self, node) -> bool:
+        if not isinstance(node, GradioNode):
+            return False
+        return bool(node._run_locally and node._local_url and not node._local_failed)
+
+    def _build_variant_data(self, variant, input_values: dict) -> dict[str, Any]:
+        variant_name = variant._name
+        if isinstance(variant, GradioNode) and not variant._name_explicitly_set:
+            variant_name = f"{variant._src}"
+            if variant._api_name:
+                variant_name += f" ({variant._api_name})"
+
+        input_components = []
+        for port_name, comp in variant._input_components.items():
+            comp_data = self._serialize_component(comp, port_name)
+            input_components.append(comp_data)
+
+        output_components = []
+        for port_name, comp in variant._output_components.items():
+            if comp is None:
+                continue
+            visible = getattr(comp, "visible", True)
+            if visible is False:
+                continue
+            comp_data = self._serialize_component(comp, port_name)
+            output_components.append(comp_data)
+
+        return {
+            "name": variant_name,
+            "input_components": input_components,
+            "output_components": output_components,
+        }
+
+    def _get_component_type(self, component) -> str:
+        class_name = component.__class__.__name__
+        type_map = {
+            "Audio": "audio",
+            "Textbox": "textbox",
+            "TextArea": "textarea",
+            "JSON": "json",
+            "Chatbot": "json",
+            "Image": "image",
+            "Number": "number",
+            "Markdown": "markdown",
+            "Text": "text",
+            "Dropdown": "dropdown",
+            "Video": "video",
+            "File": "file",
+            "Model3D": "model3d",
+            "Gallery": "gallery",
+            "Slider": "slider",
+            "Radio": "radio",
+            "Checkbox": "checkbox",
+            "CheckboxGroup": "checkboxgroup",
+            "ColorPicker": "colorpicker",
+            "Label": "label",
+            "HighlightedText": "highlightedtext",
+            "Code": "code",
+            "HTML": "html",
+            "Dataframe": "dataframe",
+        }
+        return type_map.get(class_name, "text")
+
+    def _serialize_component(self, comp, port_name: str) -> dict[str, Any]:
+        comp_type = self._get_component_type(comp)
+        comp_class = comp.__class__.__name__
+
+        props = {
+            "label": getattr(comp, "label", "") or port_name,
+            "show_label": bool(getattr(comp, "label", "")),
+            "interactive": getattr(comp, "interactive", True),
+            "visible": getattr(comp, "visible", True),
+        }
+
+        if hasattr(comp, "placeholder"):
+            props["placeholder"] = comp.placeholder
+        if hasattr(comp, "lines"):
+            props["lines"] = comp.lines
+        if hasattr(comp, "max_lines"):
+            props["max_lines"] = comp.max_lines
+        if hasattr(comp, "type"):
+            props["type"] = comp.type
+        if hasattr(comp, "choices") and comp.choices:
+            choices = []
+            for c in comp.choices:
+                if isinstance(c, (tuple, list)) and len(c) >= 2:
+                    choices.append([c[0], c[1]])
+                else:
+                    choices.append([str(c), c])
+            props["choices"] = choices
+        if hasattr(comp, "minimum"):
+            props["minimum"] = comp.minimum
+        if hasattr(comp, "maximum"):
+            props["maximum"] = comp.maximum
+        if hasattr(comp, "step"):
+            props["step"] = comp.step
+
+        value = getattr(comp, "value", None)
+        if is_file_obj_with_meta(value):
+            value = self._file_to_url(value["path"])
+
+        return {
+            "component": comp_class.lower(),
+            "type": comp_type,
+            "port_name": port_name,
+            "props": props,
+            "value": value,
+        }
+
+    def _file_to_url(self, value: Any) -> Any:
+        if isinstance(value, str) and not value.startswith("/file/"):
+            path = Path(value)
+            if path.is_absolute() and path.exists():
+                normalized = value.replace("\\", "/")
+                if normalized.startswith("/"):
+                    return f"/file{normalized}"
+                return f"/file/{normalized}"
+        return value
+
+    def _validate_file_value(self, value: Any, comp_type: str) -> str | None:
+        """Validate that a value is appropriate for a file-type component.
+        Returns an error message if invalid, None if valid."""
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return None
+        if isinstance(value, dict):
+            if "url" in value or "path" in value:
+                return None
+            keys = list(value.keys())
+            if keys:
+                return (
+                    f"Expected a file path string for {comp_type}, but got a dict "
+                    f"with keys {keys}. If using postprocess, extract the path: "
+                    f"e.g., `postprocess=lambda x: x['{keys[0]}']`"
+                )
+            return (
+                f"Expected a file path string for {comp_type}, but got an empty dict."
+            )
+        return f"Expected a file path string for {comp_type}, but got {type(value).__name__}."
+
+    def _transform_file_paths(self, data: Any) -> Any:
+        if isinstance(data, str):
+            return self._file_to_url(data)
+        elif isinstance(data, dict):
+            return {k: self._transform_file_paths(v) for k, v in data.items()}
+        elif isinstance(data, list):
+            return [self._transform_file_paths(item) for item in data]
+        return data
+
+    def _transform_persisted_results(
+        self, persisted_results: dict[str, list[Any]]
+    ) -> dict[str, list[Any]]:
+        """Transform persisted results, handling both old format (just result)
+        and new format (dict with result and inputs_snapshot)."""
+        transformed: dict[str, list[Any]] = {}
+        for node_name, results_list in persisted_results.items():
+            transformed[node_name] = []
+            for entry in results_list:
+                if isinstance(entry, dict) and "result" in entry:
+                    transformed[node_name].append(
+                        {
+                            "result": self._transform_file_paths(entry["result"]),
+                            "inputs_snapshot": entry.get("inputs_snapshot"),
+                        }
+                    )
+                else:
+                    transformed[node_name].append(self._transform_file_paths(entry))
+        return transformed
+
+    def _build_input_components(self, node) -> list[dict[str, Any]]:
+        if not node._input_components:
+            return []
+        return [
+            self._serialize_component(comp, port_name)
+            for port_name, comp in node._input_components.items()
+        ]
+
+    def _build_output_components(
+        self, node, result: Any = None
+    ) -> tuple[list[dict[str, Any]], str | None]:
+        if not node._output_components:
+            return [], None
+
+        components = []
+        validation_error = None
+        for port_name, comp in node._output_components.items():
+            if comp is None:
+                continue
+
+            visible = getattr(comp, "visible", True)
+            if visible is False:
+                continue
+
+            comp_data = self._serialize_component(comp, port_name)
+            comp_type = self._get_component_type(comp)
+            if result is not None:
+                if isinstance(result, dict):
+                    value = result.get(
+                        port_name, result.get(comp_data["props"]["label"])
+                    )
+                else:
+                    value = result
+                if comp_type in _FILE_COMP_TYPES:
+                    error = self._validate_file_value(value, comp_type)
+                    if error and validation_error is None:
+                        validation_error = error
+                    value = self._file_to_url(value)
+                comp_data["value"] = value
+            components.append(comp_data)
+        return components, validation_error
+
+    def _build_scattered_items(
+        self, node_name: str, result: Any = None
+    ) -> list[dict[str, Any]]:
+        scattered_edge = self._get_scattered_edge(node_name)
+        if not scattered_edge:
+            return []
+
+        node = self.graph.nodes[node_name]
+        item_output_type = "text"
+        for comp in node._output_components.values():
+            if comp is None:
+                continue
+            comp_type = self._get_component_type(comp)
+            if comp_type == "audio":
+                item_output_type = "audio"
+                break
+
+        items = []
+        if result and isinstance(result, dict) and "_scattered_results" in result:
+            results = result["_scattered_results"]
+            source_items = result.get("_items", [])
+            for i, item_result in enumerate(results):
+                source_item = source_items[i] if i < len(source_items) else None
+                preview = ""
+                output = None
+
+                if isinstance(source_item, dict):
+                    preview_parts = [
+                        f"{k}: {str(v)[:20]}" for k, v in list(source_item.items())[:2]
+                    ]
+                    preview = ", ".join(preview_parts)
+                elif source_item:
+                    preview = str(source_item)[:50]
+
+                if isinstance(item_result, dict):
+                    first_key = list(item_result.keys())[0] if item_result else None
+                    if first_key:
+                        output = item_result[first_key]
+                else:
+                    output = item_result
+
+                if output:
+                    output = str(output)
+
+                items.append(
+                    {
+                        "index": i + 1,
+                        "preview": preview or f"Item {i + 1}",
+                        "output": output,
+                        "is_audio_output": item_output_type == "audio",
+                    }
+                )
+        return items
+
+    def _serialize_item_list_schema(
+        self, schema: dict[str, Any]
+    ) -> list[dict[str, Any]]:
+        serialized = []
+        for field_name, comp in schema.items():
+            comp_data = self._serialize_component(comp, field_name)
+            serialized.append(comp_data)
+        return serialized
+
+    def _build_item_list_items(
+        self, node, port_name: str, result: Any = None
+    ) -> list[dict[str, Any]]:
+        schema = node._item_list_schemas.get(port_name, {})
+        if not schema:
+            return []
+
+        items = []
+        if result and isinstance(result, dict) and port_name in result:
+            item_list = result[port_name]
+            if isinstance(item_list, list):
+                for i, item_data in enumerate(item_list):
+                    item = {"index": i, "fields": {}}
+                    if isinstance(item_data, dict):
+                        for field_name in schema:
+                            item["fields"][field_name] = item_data.get(field_name)
+                    items.append(item)
+        return items
+
+    def _apply_item_list_edits(
+        self, node_name: str, result: Any, item_list_values: dict
+    ) -> Any:
+        node = self.graph.nodes[node_name]
+        if not node._item_list_schemas:
+            return result
+
+        node_id = node_name.replace(" ", "_").replace("-", "_")
+        edits = item_list_values.get(node_id, {})
+        if not edits:
+            return result
+
+        first_port = list(node._item_list_schemas.keys())[0]
+        if isinstance(result, dict) and first_port in result:
+            items = result[first_port]
+            if isinstance(items, list):
+                for idx_str, field_edits in edits.items():
+                    idx = int(idx_str)
+                    if 0 <= idx < len(items) and isinstance(items[idx], dict):
+                        items[idx].update(field_edits)
+        return result
+
+    def _compute_node_depths(self) -> dict[str, int]:
+        depths: dict[str, int] = {}
+        connections = self.graph.get_connections()
+
+        for node_name in self.graph.nodes:
+            if self.graph._nx_graph.in_degree(node_name) == 0:
+                depths[node_name] = 0
+
+        changed = True
+        while changed:
+            changed = False
+            for source, _, target, _ in connections:
+                if source in depths:
+                    new_depth = depths[source] + 1
+                    if target not in depths or depths[target] < new_depth:
+                        depths[target] = new_depth
+                        changed = True
+
+        for node_name in self.graph.nodes:
+            if node_name not in depths:
+                depths[node_name] = 0
+
+        return depths
+
+    def _get_hf_user_info(self) -> dict | None:
+        try:
+            from huggingface_hub import get_token, whoami
+
+            token = get_token()
+            if not token:
+                return None
+
+            info = whoami(cache=True)
+            return {
+                "username": info.get("name"),
+                "fullname": info.get("fullname"),
+                "avatar_url": info.get("avatarUrl"),
+            }
+        except Exception:
+            return None
+
+    def _build_graph_data(
+        self,
+        node_results: dict[str, Any] | None = None,
+        node_statuses: dict[str, str] | None = None,
+        input_values: dict[str, Any] | None = None,
+        history: dict[str, dict[str, list[dict]]] | None = None,
+        session_id: str | None = None,
+        selected_results: dict[str, int] | None = None,
+    ) -> dict:
+        node_results = node_results or {}
+        node_statuses = node_statuses or {}
+        input_values = input_values or {}
+        history = history or {}
+        selected_results = selected_results or {}
+
+        depths = self._compute_node_depths()
+
+        synthetic_input_nodes: list[dict[str, Any]] = []
+        synthetic_edges: list[dict[str, Any]] = []
+        input_node_positions: dict[str, tuple] = {}
+
+        component_to_input_node: dict[int, str] = {}
+        creation_order = 0
+        for node_name in self.graph.nodes:
+            node = self.graph.nodes[node_name]
+
+            if isinstance(node, ChoiceNode):
+                continue
+
+            if node._input_components:
+                for idx, (port_name, comp) in enumerate(node._input_components.items()):
+                    comp_id = id(comp)
+
+                    if comp_id in component_to_input_node:
+                        existing_input_node = component_to_input_node[comp_id]
+                        existing_input_id = existing_input_node.replace(
+                            " ", "_"
+                        ).replace("-", "_")
+                        synthetic_edges.append(
+                            {
+                                "from_node": existing_input_id,
+                                "from_port": "value",
+                                "to_node": node_name.replace(" ", "_").replace(
+                                    "-", "_"
+                                ),
+                                "to_port": port_name,
+                            }
+                        )
+                        continue
+
+                    input_node_name = f"{node_name}__{port_name}"
+                    input_node_id = input_node_name.replace(" ", "_").replace("-", "_")
+                    component_to_input_node[comp_id] = input_node_name
+
+                    comp_data = self._serialize_component(comp, "value")
+                    label = comp_data["props"].get("label") or port_name
+
+                    if input_node_id in input_values:
+                        comp_data["value"] = input_values[input_node_id].get(
+                            "value", comp_data["value"]
+                        )
+
+                    synthetic_input_nodes.append(
+                        {
+                            "node_name": input_node_name,
+                            "display_name": label,
+                            "target_node": node_name,
+                            "target_port": port_name,
+                            "component": comp_data,
+                            "index": idx,
+                            "creation_order": creation_order,
+                        }
+                    )
+                    creation_order += 1
+
+                    synthetic_edges.append(
+                        {
+                            "from_node": input_node_id,
+                            "from_port": "value",
+                            "to_node": node_name.replace(" ", "_").replace("-", "_"),
+                            "to_port": port_name,
+                        }
+                    )
+
+        max_depth = max(depths.values()) if depths else 0
+
+        nodes_by_depth: dict[int, list[str]] = {}
+        for node_name, depth in depths.items():
+            if depth not in nodes_by_depth:
+                nodes_by_depth[depth] = []
+            nodes_by_depth[depth].append(node_name)
+
+        x_spacing = 350
+        input_column_x = 50
+        x_start = 400
+        y_start = 120
+        y_gap = 30
+        base_node_height = 100
+        component_base_height = 60
+        line_height = 18
+
+        def calc_component_height(comp_data: dict) -> int:
+            lines = comp_data.get("props", {}).get("lines", 1)
+            lines = min(lines, 6)
+            return component_base_height + max(0, lines - 1) * line_height
+
+        def calc_node_height(components: list[dict], num_ports: int = 1) -> int:
+            comp_height = sum(calc_component_height(c) for c in components)
+            port_height = max(num_ports, 1) * 22
+            return base_node_height + port_height + comp_height
+
+        all_input_nodes_sorted: list[dict] = []
+        for syn_node in synthetic_input_nodes:
+            target_depth = depths.get(syn_node["target_node"], 0)
+            all_input_nodes_sorted.append({**syn_node, "target_depth": target_depth})
+        all_input_nodes_sorted.sort(key=lambda x: x["creation_order"])
+
+        current_input_y = y_start
+        for syn_node in all_input_nodes_sorted:
+            input_node_positions[syn_node["node_name"]] = (
+                input_column_x,
+                current_input_y,
+            )
+            node_height = calc_node_height([syn_node["component"]], 1)
+            current_input_y += node_height + y_gap
+
+        node_positions: dict[str, tuple] = {}
+        for depth in range(max_depth + 1):
+            depth_nodes = nodes_by_depth.get(depth, [])
+            current_y = y_start
+            for node_name in depth_nodes:
+                node = self.graph.nodes[node_name]
+                output_comps, _ = self._build_output_components(node)
+                num_ports = max(
+                    len(node._input_ports or []), len(node._output_ports or [])
+                )
+                node_height = calc_node_height(output_comps, num_ports)
+                x = x_start + depth * x_spacing
+                node_positions[node_name] = (x, current_y)
+                current_y += node_height + y_gap
+
+        nodes = []
+
+        for syn_node in synthetic_input_nodes:
+            node_name = syn_node["node_name"]
+            display_name = syn_node["display_name"]
+            node_id = node_name.replace(" ", "_").replace("-", "_")
+            x, y = input_node_positions.get(node_name, (50, 50))
+            comp = syn_node["component"]
+
+            nodes.append(
+                {
+                    "id": node_id,
+                    "name": display_name,
+                    "type": "INPUT",
+                    "inputs": [],
+                    "outputs": ["value"],
+                    "x": x,
+                    "y": y,
+                    "has_input": False,
+                    "input_value": "",
+                    "input_components": [comp],
+                    "output_components": [],
+                    "is_map_node": False,
+                    "map_items": [],
+                    "map_item_count": 0,
+                    "item_output_type": "text",
+                    "status": "pending",
+                    "result": "",
+                    "is_output_node": False,
+                    "is_input_node": True,
+                }
+            )
+
+        for node_name in self.graph.nodes:
+            node = self.graph.nodes[node_name]
+            x, y = node_positions.get(node_name, (50, 50))
+
+            result = node_results.get(node_name)
+            result_str = ""
+            is_scattered = self._has_scattered_input(node_name)
+            if result is not None and not node._output_components and not is_scattered:
+                if isinstance(result, dict):
+                    display_result = {
+                        k: v for k, v in result.items() if not k.startswith("_")
+                    }
+                    result_str = json.dumps(display_result, indent=2, default=str)[:300]
+                elif isinstance(result, (list, tuple)):
+                    result_str = json.dumps(list(result)[:5], default=str)
+                else:
+                    result_str = str(result)[:300]
+
+            node_id = node_name.replace(" ", "_").replace("-", "_")
+
+            input_ports_data = []
+            for port in node._input_ports or []:
+                if port in node._fixed_inputs:
+                    continue
+                port_history = history.get(node_name, {}).get(port, [])
+                input_ports_data.append(
+                    {
+                        "name": port,
+                        "history_count": len(port_history) if port_history else 0,
+                    }
+                )
+
+            output_components, validation_error = self._build_output_components(
+                node, result
+            )
+            scattered_items = (
+                self._build_scattered_items(node_name, result) if is_scattered else []
+            )
+
+            item_output_type = "text"
+            if is_scattered:
+                for comp in node._output_components.values():
+                    if comp is None:
+                        continue
+                    comp_type = self._get_component_type(comp)
+                    if comp_type == "audio":
+                        item_output_type = "audio"
+                        break
+
+            item_list_schema = None
+            item_list_items = []
+            if node._item_list_schemas:
+                first_port = list(node._item_list_schemas.keys())[0]
+                item_list_schema = self._serialize_item_list_schema(
+                    node._item_list_schemas[first_port]
+                )
+                item_list_items = self._build_item_list_items(node, first_port, result)
+
+            output_ports = []
+            for port_name in node._output_ports or []:
+                if port_name in node._item_list_schemas:
+                    schema = node._item_list_schemas[port_name]
+                    for field_name in schema:
+                        output_ports.append(f"{port_name}.{field_name}")
+                elif port_name in node._output_components:
+                    output_ports.append(port_name)
+
+            is_output = self._is_output_node(node_name)
+            is_local = self._is_running_locally(node)
+
+            variants = None
+            selected_variant = None
+            if isinstance(node, ChoiceNode):
+                variants = [
+                    self._build_variant_data(v, input_values) for v in node._variants
+                ]
+                selected_variant = input_values.get(node_id, {}).get(
+                    "_selected_variant", 0
+                )
+
+            nodes.append(
+                {
+                    "id": node_id,
+                    "name": node_name,
+                    "type": self._get_node_type(node, node_name),
+                    "url": self._get_node_url(node),
+                    "inputs": input_ports_data,
+                    "outputs": output_ports,
+                    "x": x,
+                    "y": y,
+                    "has_input": False,
+                    "input_value": input_values.get(node_name, ""),
+                    "input_components": [],
+                    "output_components": output_components,
+                    "is_map_node": is_scattered,
+                    "map_items": scattered_items,
+                    "map_item_count": len(scattered_items),
+                    "item_output_type": item_output_type,
+                    "item_list_schema": item_list_schema,
+                    "item_list_items": item_list_items,
+                    "status": node_statuses.get(node_name, "pending"),
+                    "result": result_str,
+                    "is_output_node": is_output,
+                    "is_input_node": False,
+                    "is_local": is_local,
+                    "variants": variants,
+                    "selected_variant": selected_variant,
+                    "validation_error": validation_error,
+                }
+            )
+
+        edges = []
+        for i, edge in enumerate(self.graph._edges):
+            from_port = edge.source_port
+            if edge.item_key:
+                from_port = f"{edge.source_port}.{edge.item_key}"
+            edges.append(
+                {
+                    "id": f"edge_{i}",
+                    "from_node": edge.source_node._name.replace(" ", "_").replace(
+                        "-", "_"
+                    ),
+                    "from_port": from_port,
+                    "to_node": edge.target_node._name.replace(" ", "_").replace(
+                        "-", "_"
+                    ),
+                    "to_port": edge.target_port,
+                    "is_scattered": edge.is_scattered,
+                    "is_gathered": edge.is_gathered,
+                }
+            )
+
+        for i, syn_edge in enumerate(synthetic_edges):
+            edges.append(
+                {
+                    "id": f"input_edge_{i}",
+                    "from_node": syn_edge["from_node"],
+                    "from_port": syn_edge["from_port"],
+                    "to_node": syn_edge["to_node"],
+                    "to_port": syn_edge["to_port"],
+                }
+            )
+
+        return {
+            "name": self.graph.name,
+            "nodes": nodes,
+            "edges": edges,
+            "inputs": input_values,
+            "selected_results": selected_results,
+            "history": history,
+            "session_id": session_id,
+        }
+
+    def _get_ancestors(self, node_name: str) -> list[str]:
+        ancestors = set()
+        to_visit = [node_name]
+        while to_visit:
+            current = to_visit.pop()
+            for source, _, target, _ in self.graph.get_connections():
+                if target == current and source not in ancestors:
+                    ancestors.add(source)
+                    to_visit.append(source)
+        return list(ancestors)
+
+    def _get_user_provided_output(
+        self, node, node_id: str, input_values: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        if not node._output_components:
+            return None
+
+        node_inputs = input_values.get(node_id, {})
+        if not node_inputs:
+            return None
+
+        result = {}
+        has_user_value = False
+        for port_name, comp in node._output_components.items():
+            if comp is None:
+                continue
+            if port_name in node_inputs:
+                value = node_inputs[port_name]
+                if value is not None:
+                    if isinstance(value, str) and value.startswith("data:"):
+                        value = self._save_data_url_as_gradio_file(value)
+                    result[port_name] = value
+                    has_user_value = True
+
+        return result if has_user_value else None
+
+    def _save_data_url_as_gradio_file(self, data_url: str):
+        try:
+            header, data = data_url.split(",", 1)
+            mime_type = header.split(":")[1].split(";")[0]
+            ext_map = {
+                "image/png": ".png",
+                "image/jpeg": ".jpg",
+                "image/gif": ".gif",
+                "image/webp": ".webp",
+                "audio/webm": ".webm",
+                "audio/wav": ".wav",
+                "audio/mp3": ".mp3",
+                "audio/mpeg": ".mp3",
+            }
+            ext = ext_map.get(mime_type, ".bin")
+            file_data = base64.b64decode(data)
+            temp_dir = Path(tempfile.gettempdir()) / "daggr_uploads"
+            temp_dir.mkdir(exist_ok=True)
+            file_path = temp_dir / f"{uuid.uuid4()}{ext}"
+            file_path.write_bytes(file_data)
+            return FileValue(str(file_path))
+        except Exception as e:
+            print(f"[ERROR] Failed to save data URL: {e}")
+            return data_url
+
+    def _convert_urls_to_file_values(self, data: Any) -> Any:
+        if isinstance(data, str):
+            if data.startswith(("http://", "https://", "/")) and any(
+                data.lower().endswith(ext)
+                for ext in (
+                    ".png",
+                    ".jpg",
+                    ".jpeg",
+                    ".gif",
+                    ".webp",
+                    ".wav",
+                    ".mp3",
+                    ".webm",
+                    ".mp4",
+                    ".ogg",
+                )
+            ):
+                return FileValue(data)
+            return data
+        elif isinstance(data, dict):
+            return {k: self._convert_urls_to_file_values(v) for k, v in data.items()}
+        elif isinstance(data, list):
+            return [self._convert_urls_to_file_values(item) for item in data]
+        return data
+
+    async def _execute_to_node(
+        self,
+        session: ExecutionSession,
+        target_node: str,
+        session_id: str | None,
+        input_values: dict[str, Any],
+        selected_results: dict[str, int],
+    ) -> dict:
+        if not session_id:
+            session_id = self.state.create_session(self.graph.persist_key)
+
+        for node_name, node in self.graph.nodes.items():
+            if isinstance(node, ChoiceNode):
+                node_id = node_name.replace(" ", "_").replace("-", "_")
+                variant_idx = input_values.get(node_id, {}).get("_selected_variant", 0)
+                session.selected_variants[node_name] = variant_idx
+
+        ancestors = self._get_ancestors(target_node)
+        nodes_to_run = ancestors + [target_node]
+        execution_order = self.graph.get_execution_order()
+        nodes_to_execute = [n for n in execution_order if n in nodes_to_run]
+
+        entry_inputs: dict[str, dict[str, Any]] = {}
+        for node_name in nodes_to_execute:
+            node = self.graph.nodes[node_name]
+            if node._input_components:
+                node_inputs = {}
+                for port_name in node._input_components:
+                    input_node_name = f"{node_name}__{port_name}"
+                    input_node_id = input_node_name.replace(" ", "_").replace("-", "_")
+                    if input_node_id in input_values:
+                        value = input_values[input_node_id].get("value")
+                        if value is not None:
+                            node_inputs[port_name] = value
+                if node_inputs:
+                    entry_inputs[node_name] = node_inputs
+            elif isinstance(node, InteractionNode):
+                value = input_values.get(node_name, "")
+                port = node._input_ports[0] if node._input_ports else "input"
+                entry_inputs[node_name] = {port: value}
+
+        existing_results = {}
+        if session_id:
+            for node_name in nodes_to_execute:
+                if node_name in selected_results:
+                    cached = self.state.get_result_by_index(
+                        session_id, node_name, selected_results[node_name]
+                    )
+                else:
+                    cached = self.state.get_latest_result(session_id, node_name)
+                if cached is not None:
+                    existing_results[node_name] = self._convert_urls_to_file_values(
+                        cached
+                    )
+
+        for k, v in existing_results.items():
+            if k not in session.results:
+                session.results[k] = v
+
+        if target_node in session.results:
+            del session.results[target_node]
+
+        node_results = {}
+        node_statuses = {}
+
+        for node_name in nodes_to_execute:
+            if node_name in existing_results:
+                node_results[node_name] = existing_results[node_name]
+                node_statuses[node_name] = "completed"
+                continue
+
+            if node_name in session.results:
+                node_results[node_name] = session.results[node_name]
+                node_statuses[node_name] = "completed"
+                continue
+
+            node_statuses[node_name] = "running"
+            user_input = entry_inputs.get(node_name, {})
+            result = await self.executor.execute_node(session, node_name, user_input)
+            node_results[node_name] = result
+            node_statuses[node_name] = "completed"
+            self.state.save_result(session_id, node_name, result)
+
+        return self._build_graph_data(
+            node_results, node_statuses, input_values, {}, session_id, selected_results
+        )
+
+    async def _execute_to_node_streaming(
+        self,
+        session: ExecutionSession,
+        target_node: str,
+        sheet_id: str | None,
+        input_values: dict[str, Any],
+        item_list_values: dict[str, Any],
+        selected_results: dict[str, int],
+        run_id: str,
+        user_id: str | None = None,
+        run_ancestors: bool = True,
+    ):
+        can_persist = (
+            user_id is not None
+            and sheet_id is not None
+            and self.graph.persist_key is not None
+        )
+
+        for node_name, node in self.graph.nodes.items():
+            if isinstance(node, ChoiceNode):
+                node_id = node_name.replace(" ", "_").replace("-", "_")
+                variant_idx = input_values.get(node_id, {}).get("_selected_variant", 0)
+                session.selected_variants[node_name] = variant_idx
+
+        if run_ancestors:
+            ancestors = self._get_ancestors(target_node)
+            nodes_to_run = ancestors + [target_node]
+        else:
+            nodes_to_run = [target_node]
+        execution_order = self.graph.get_execution_order()
+        nodes_to_execute = [n for n in execution_order if n in nodes_to_run]
+
+        entry_inputs: dict[str, dict[str, Any]] = {}
+        for node_name in nodes_to_execute:
+            node = self.graph.nodes[node_name]
+            if node._input_components:
+                node_inputs = {}
+                for port_name in node._input_components:
+                    input_node_name = f"{node_name}__{port_name}"
+                    input_node_id = input_node_name.replace(" ", "_").replace("-", "_")
+                    if input_node_id in input_values:
+                        value = input_values[input_node_id].get("value")
+                        if value is not None:
+                            node_inputs[port_name] = value
+                if node_inputs:
+                    entry_inputs[node_name] = node_inputs
+            elif isinstance(node, InteractionNode):
+                value = input_values.get(node_name, "")
+                port = node._input_ports[0] if node._input_ports else "input"
+                entry_inputs[node_name] = {port: value}
+
+        existing_results = {}
+        for node_name in nodes_to_execute:
+            node = self.graph.nodes[node_name]
+            node_id = node_name.replace(" ", "_").replace("-", "_")
+            user_output = self._get_user_provided_output(node, node_id, input_values)
+            if user_output is not None:
+                existing_results[node_name] = user_output
+                if can_persist:
+                    snapshot = {
+                        "inputs": input_values,
+                        "selected_results": selected_results,
+                    }
+                    self.state.save_result(sheet_id, node_name, user_output, snapshot)
+                continue
+
+            if node_name == target_node:
+                continue
+
+            if can_persist:
+                if node_name in selected_results:
+                    cached = self.state.get_result_by_index(
+                        sheet_id, node_name, selected_results[node_name]
+                    )
+                else:
+                    cached = self.state.get_latest_result(sheet_id, node_name)
+                if cached is not None:
+                    existing_results[node_name] = self._convert_urls_to_file_values(
+                        cached
+                    )
+
+        for k, v in existing_results.items():
+            if k not in session.results:
+                session.results[k] = v
+
+        if target_node in session.results:
+            del session.results[target_node]
+
+        node_results = {}
+        node_statuses = {}
+
+        try:
+            for node_name in nodes_to_execute:
+                if node_name in existing_results:
+                    result = existing_results[node_name]
+                    result = self._apply_item_list_edits(
+                        node_name, result, item_list_values
+                    )
+                    node_results[node_name] = result
+                    session.results[node_name] = result
+                    node_statuses[node_name] = "completed"
+                    continue
+
+                if node_name in session.results:
+                    result = session.results[node_name]
+                    result = self._apply_item_list_edits(
+                        node_name, result, item_list_values
+                    )
+                    node_results[node_name] = result
+                    node_statuses[node_name] = "completed"
+                    continue
+
+                can_execute = await session.start_node_execution(node_name)
+                if not can_execute:
+                    if node_name == target_node:
+                        return
+                    await session.wait_for_node(node_name)
+                    if node_name in session.results:
+                        result = session.results[node_name]
+                        result = self._apply_item_list_edits(
+                            node_name, result, item_list_values
+                        )
+                        node_results[node_name] = result
+                        node_statuses[node_name] = "completed"
+                        continue
+
+                try:
+                    node_statuses[node_name] = "running"
+                    user_input = entry_inputs.get(node_name, {})
+
+                    yield {
+                        "type": "node_started",
+                        "started_node": node_name,
+                        "run_id": run_id,
+                    }
+
+                    start_time = time.time()
+                    result = await self.executor.execute_node(
+                        session, node_name, user_input
+                    )
+                    elapsed_ms = (time.time() - start_time) * 1000
+
+                    result = self._apply_item_list_edits(
+                        node_name, result, item_list_values
+                    )
+                    session.results[node_name] = result
+                    node_results[node_name] = result
+                    node_statuses[node_name] = "completed"
+
+                    if can_persist:
+                        current_count = self.state.get_result_count(sheet_id, node_name)
+                        snapshot = {
+                            "inputs": input_values,
+                            "selected_results": selected_results,
+                        }
+                        self.state.save_result(sheet_id, node_name, result, snapshot)
+                        selected_results[node_name] = current_count
+
+                    graph_data = self._build_graph_data(
+                        node_results,
+                        node_statuses,
+                        input_values,
+                        {},
+                        sheet_id,
+                        selected_results,
+                    )
+                    graph_data["type"] = "node_complete"
+                    graph_data["completed_node"] = node_name
+                    graph_data["run_id"] = run_id
+                    graph_data["execution_time_ms"] = elapsed_ms
+                finally:
+                    await session.finish_node_execution(node_name)
+                yield graph_data
+
+        except Exception as e:
+            error_node = None
+            if nodes_to_execute:
+                current_idx = len(node_results)
+                if current_idx < len(nodes_to_execute):
+                    error_node = nodes_to_execute[current_idx]
+                    node_statuses[error_node] = "error"
+                    node_results[error_node] = {"error": str(e)}
+
+            graph_data = self._build_graph_data(
+                node_results,
+                node_statuses,
+                input_values,
+                {},
+                sheet_id,
+                selected_results,
+            )
+            graph_data["type"] = "error"
+            graph_data["run_id"] = run_id
+            graph_data["error"] = str(e)
+            graph_data["nodes_to_clear"] = nodes_to_execute
+            if error_node:
+                graph_data["node"] = error_node
+                graph_data["completed_node"] = error_node
+            yield graph_data
+
+    async def _execute_workflow_api(
+        self, request: Request, subgraph_id: str | None = None
+    ) -> JSONResponse:
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+
+        input_values = body.get("inputs", {})
+        session = ExecutionSession(self.graph)
+
+        subgraphs = self.graph.get_subgraphs()
+        output_node_names = set(self.graph.get_output_nodes())
+
+        if subgraph_id is None:
+            if len(subgraphs) > 1:
+                return JSONResponse(
+                    {
+                        "error": "Multiple subgraphs detected. Please specify a subgraph_id.",
+                        "available_subgraphs": [
+                            f"subgraph_{i}" for i in range(len(subgraphs))
+                        ],
+                    },
+                    status_code=400,
+                )
+            target_nodes = subgraphs[0] if subgraphs else set(self.graph.nodes.keys())
+        else:
+            if subgraph_id == "main" and len(subgraphs) == 1:
+                target_nodes = subgraphs[0]
+            elif subgraph_id.startswith("subgraph_"):
+                try:
+                    idx = int(subgraph_id.split("_")[1])
+                    if idx < 0 or idx >= len(subgraphs):
+                        return JSONResponse(
+                            {"error": f"Subgraph '{subgraph_id}' not found"},
+                            status_code=404,
+                        )
+                    target_nodes = subgraphs[idx]
+                except (ValueError, IndexError):
+                    return JSONResponse(
+                        {"error": f"Invalid subgraph_id '{subgraph_id}'"},
+                        status_code=400,
+                    )
+            else:
+                return JSONResponse(
+                    {"error": f"Subgraph '{subgraph_id}' not found"},
+                    status_code=404,
+                )
+
+        for node_name, node in self.graph.nodes.items():
+            if isinstance(node, ChoiceNode):
+                node_id = node_name.replace(" ", "_").replace("-", "_")
+                variant_idx = input_values.get(f"{node_id}___selected_variant", 0)
+                session.selected_variants[node_name] = variant_idx
+
+        execution_order = self.graph.get_execution_order()
+        nodes_to_execute = [n for n in execution_order if n in target_nodes]
+
+        entry_inputs: dict[str, dict[str, Any]] = {}
+        for node_name in nodes_to_execute:
+            node = self.graph.nodes[node_name]
+            if node._input_components:
+                node_inputs = {}
+                for port_name in node._input_components:
+                    input_node_id = f"{node_name}__{port_name}".replace(
+                        " ", "_"
+                    ).replace("-", "_")
+                    if input_node_id in input_values:
+                        node_inputs[port_name] = input_values[input_node_id]
+                if node_inputs:
+                    entry_inputs[node_name] = node_inputs
+
+        session.results = {}
+        node_results = {}
+
+        try:
+            for node_name in nodes_to_execute:
+                user_input = entry_inputs.get(node_name, {})
+                result = await self.executor.execute_node(
+                    session, node_name, user_input
+                )
+                node_results[node_name] = result
+        except Exception as e:
+            return JSONResponse(
+                {"error": f"Execution error in node '{node_name}': {str(e)}"},
+                status_code=500,
+            )
+
+        outputs = {}
+        for node_name in nodes_to_execute:
+            if node_name in output_node_names and node_name in node_results:
+                result = node_results[node_name]
+                result = self._transform_file_paths(result)
+                outputs[node_name] = result
+
+        return JSONResponse({"outputs": outputs})
+
+    def run(
+        self,
+        host: str | None = None,
+        port: int | None = None,
+        share: bool | None = None,
+        open_browser: bool = True,
+        **kwargs,
+    ):
+        from gradio.utils import colab_check, ipython_check
+
+        if host is None:
+            host = os.environ.get("GRADIO_SERVER_NAME", "127.0.0.1")
+        if port is None:
+            port = int(os.environ.get("GRADIO_SERVER_PORT", "7860"))
+
+        actual_port = _find_available_port(host, port)
+        if actual_port != port:
+            print(f"\n  Port {port} is in use, using {actual_port} instead.")
+
+        self.graph._validate_edges()
+
+        is_colab = colab_check()
+        is_kaggle = os.environ.get("KAGGLE_KERNEL_RUN_TYPE") is not None
+        is_notebook = is_colab or is_kaggle or ipython_check()
+
+        if share is None:
+            share = is_colab or is_kaggle
+
+        if is_notebook or share:
+            config = uvicorn.Config(
+                app=self.app,
+                host=host,
+                port=actual_port,
+                log_level="warning",
+            )
+            server = _Server(config)
+            server.run_in_thread()
+
+            local_url = f"http://{host}:{actual_port}"
+            print(f"\n  UI running at: {local_url}")
+            if self.api_server:
+                print(f"  API server at: {local_url}/api")
+
+            share_url = None
+            if share:
+                from gradio.networking import setup_tunnel
+
+                share_token = secrets.token_urlsafe(32)
+                share_url = setup_tunnel(
+                    local_host=host,
+                    local_port=actual_port,
+                    share_token=share_token,
+                    share_server_address=None,
+                    share_server_tls_certificate=None,
+                )
+                print(f"  Public URL: {share_url}")
+                print(
+                    "\n  This share link expires in 1 week. For permanent hosting, deploy to Hugging Face Spaces.\n"
+                )
+
+            if is_colab or is_kaggle:
+                from IPython.display import HTML, display
+
+                url = share_url or local_url
+                display(
+                    HTML(f'<a href="{url}" target="_blank">Open daggr app: {url}</a>')
+                )
+            elif open_browser:
+                webbrowser.open_new_tab(share_url or local_url)
+
+            try:
+                while True:
+                    time.sleep(1)
+            except KeyboardInterrupt:
+                print("\nShutting down...")
+                server.close()
+        else:
+            local_url = f"http://{host}:{actual_port}"
+            print(f"\n  UI running at: {local_url}")
+            if self.api_server:
+                print(f"  API server at: {local_url}/api")
+            print()
+            if open_browser:
+                threading.Timer(0.5, lambda: webbrowser.open_new_tab(local_url)).start()
+            uvicorn.run(
+                self.app, host=host, port=actual_port, log_level="warning", **kwargs
+            )
+
+
+class _Server(uvicorn.Server):
+    def install_signal_handlers(self):
+        pass
+
+    def run_in_thread(self):
+        self.thread = threading.Thread(target=self.run, daemon=True)
+        self.thread.start()
+        start = time.time()
+        while not self.started:
+            time.sleep(1e-3)
+            if time.time() - start > 5:
+                raise RuntimeError(
+                    "Server failed to start. Please check that the port is available."
+                )
+
+    def close(self):
+        self.should_exit = True
+        self.thread.join(timeout=5)

daggr/session.py

@@ -0,0 +1,114 @@
+"""Session management for daggr, including per-session execution contexts for security isolation and concurrency management."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from daggr.graph import Graph
+
+
+class ConcurrencyManager:
+    """Manages concurrency limits for FnNode execution within a session.
+
+    By default, only one FnNode runs at a time per session. FnNodes can opt
+    into concurrent execution via the `concurrent` parameter, and can share
+    limits via `concurrency_group`.
+    """
+
+    def __init__(self):
+        self._default_semaphore = asyncio.Semaphore(1)
+        self._group_semaphores: dict[str, asyncio.Semaphore] = {}
+        self._lock = asyncio.Lock()
+
+    async def get_semaphore(
+        self,
+        concurrent: bool,
+        concurrency_group: str | None,
+        max_concurrent: int,
+    ) -> asyncio.Semaphore | None:
+        """Get the appropriate semaphore for a FnNode.
+
+        Returns None if the node should run without concurrency limits
+        (concurrent=True with no group).
+        """
+        if not concurrent:
+            return self._default_semaphore
+
+        if concurrency_group:
+            async with self._lock:
+                if concurrency_group not in self._group_semaphores:
+                    self._group_semaphores[concurrency_group] = asyncio.Semaphore(
+                        max_concurrent
+                    )
+                return self._group_semaphores[concurrency_group]
+
+        return None
+
+
+class ExecutionSession:
+    """Per-session execution context.
+
+    Each WebSocket connection gets its own ExecutionSession, providing:
+    - Isolated HF token
+    - Isolated results cache
+    - Isolated Gradio client cache
+    - Per-session concurrency management
+    - Node execution coordination (wait for dependencies)
+    """
+
+    def __init__(self, graph: Graph, hf_token: str | None = None):
+        self.graph = graph
+        self.hf_token = hf_token
+        self.results: dict[str, Any] = {}
+        self.scattered_results: dict[str, list[Any]] = {}
+        self.selected_variants: dict[str, int] = {}
+        self.clients: dict[str, Any] = {}
+        self.concurrency = ConcurrencyManager()
+
+        self._executing_nodes: dict[str, asyncio.Event] = {}
+        self._execution_lock = asyncio.Lock()
+
+    def set_hf_token(self, token: str | None):
+        """Update the HF token and clear cached clients."""
+        if token != self.hf_token:
+            self.hf_token = token
+            self.clients = {}
+
+    def clear_results(self):
+        """Clear cached results for a fresh execution."""
+        self.results = {}
+        self.scattered_results = {}
+
+    async def wait_for_node(self, node_name: str) -> bool:
+        """Wait for a node to finish executing if it's currently running.
+
+        Returns True if we waited (node was executing), False otherwise.
+        """
+        async with self._execution_lock:
+            event = self._executing_nodes.get(node_name)
+
+        if event:
+            await event.wait()
+            return True
+        return False
+
+    async def start_node_execution(self, node_name: str) -> bool:
+        """Mark a node as starting execution.
+
+        Returns True if we can start (no one else is executing it).
+        Returns False if someone else is already executing it.
+        """
+        async with self._execution_lock:
+            if node_name in self._executing_nodes:
+                return False
+            self._executing_nodes[node_name] = asyncio.Event()
+            return True
+
+    async def finish_node_execution(self, node_name: str):
+        """Mark a node as finished executing and notify waiters."""
+        async with self._execution_lock:
+            event = self._executing_nodes.pop(node_name, None)
+            if event:
+                event.set()

daggr/state.py

@@ -0,0 +1,457 @@
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from huggingface_hub import constants
+
+
+def get_daggr_cache_dir() -> Path:
+    """Get the daggr cache directory, respecting HF_HOME env var."""
+    cache_dir = Path(constants.HF_HOME) / "daggr"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def get_daggr_files_dir() -> Path:
+    files_dir = get_daggr_cache_dir() / "files"
+    files_dir.mkdir(parents=True, exist_ok=True)
+    return files_dir
+
+
+class SessionState:
+    def __init__(self, db_path: str | None = None):
+        if db_path is None:
+            db_path = str(get_daggr_cache_dir() / "sessions.db")
+        self.db_path = db_path
+        self._init_db()
+
+    def _init_db(self):
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        self._migrate_legacy_schema(cursor)
+
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS sheets (
+                sheet_id TEXT PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                graph_name TEXT NOT NULL,
+                name TEXT,
+                transform TEXT,
+                created_at TEXT,
+                updated_at TEXT
+            )
+        """)
+
+        cursor.execute("PRAGMA table_info(sheets)")
+        columns = [col[1] for col in cursor.fetchall()]
+        if "transform" not in columns:
+            cursor.execute("ALTER TABLE sheets ADD COLUMN transform TEXT")
+
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_sheets_user_graph 
+            ON sheets(user_id, graph_name)
+        """)
+
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS node_inputs (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                sheet_id TEXT,
+                node_name TEXT,
+                port_name TEXT,
+                value TEXT,
+                updated_at TEXT,
+                FOREIGN KEY (sheet_id) REFERENCES sheets(sheet_id) ON DELETE CASCADE,
+                UNIQUE(sheet_id, node_name, port_name)
+            )
+        """)
+
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_node_inputs_sheet 
+            ON node_inputs(sheet_id)
+        """)
+
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS node_results (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                sheet_id TEXT,
+                node_name TEXT,
+                result TEXT,
+                inputs_snapshot TEXT,
+                created_at TEXT,
+                FOREIGN KEY (sheet_id) REFERENCES sheets(sheet_id) ON DELETE CASCADE
+            )
+        """)
+
+        cursor.execute("PRAGMA table_info(node_results)")
+        result_columns = [col[1] for col in cursor.fetchall()]
+        if "inputs_snapshot" not in result_columns:
+            cursor.execute("ALTER TABLE node_results ADD COLUMN inputs_snapshot TEXT")
+
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_node_results_sheet_node 
+            ON node_results(sheet_id, node_name)
+        """)
+
+        conn.commit()
+        conn.close()
+
+    def _migrate_legacy_schema(self, cursor):
+        cursor.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='node_inputs'"
+        )
+        if cursor.fetchone():
+            cursor.execute("PRAGMA table_info(node_inputs)")
+            columns = [col[1] for col in cursor.fetchall()]
+            if "session_id" in columns and "sheet_id" not in columns:
+                cursor.execute("ALTER TABLE node_inputs RENAME TO _node_inputs_old")
+                cursor.execute("ALTER TABLE node_results RENAME TO _node_results_old")
+                cursor.execute("ALTER TABLE sessions RENAME TO _sessions_old")
+
+                cursor.execute("""
+                    CREATE TABLE sheets (
+                        sheet_id TEXT PRIMARY KEY,
+                        user_id TEXT NOT NULL,
+                        graph_name TEXT NOT NULL,
+                        name TEXT,
+                        created_at TEXT,
+                        updated_at TEXT
+                    )
+                """)
+                cursor.execute("""
+                    CREATE TABLE node_inputs (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        sheet_id TEXT,
+                        node_name TEXT,
+                        port_name TEXT,
+                        value TEXT,
+                        updated_at TEXT,
+                        FOREIGN KEY (sheet_id) REFERENCES sheets(sheet_id) ON DELETE CASCADE,
+                        UNIQUE(sheet_id, node_name, port_name)
+                    )
+                """)
+                cursor.execute("""
+                    CREATE TABLE node_results (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        sheet_id TEXT,
+                        node_name TEXT,
+                        result TEXT,
+                        created_at TEXT,
+                        FOREIGN KEY (sheet_id) REFERENCES sheets(sheet_id) ON DELETE CASCADE
+                    )
+                """)
+
+                cursor.execute("""
+                    INSERT INTO sheets (sheet_id, user_id, graph_name, name, created_at, updated_at)
+                    SELECT session_id, 'local', graph_name, 'Migrated Sheet', created_at, updated_at
+                    FROM _sessions_old
+                """)
+                cursor.execute("""
+                    INSERT INTO node_inputs (sheet_id, node_name, port_name, value, updated_at)
+                    SELECT session_id, node_name, port_name, value, updated_at
+                    FROM _node_inputs_old
+                """)
+                cursor.execute("""
+                    INSERT INTO node_results (sheet_id, node_name, result, created_at)
+                    SELECT session_id, node_name, result, created_at
+                    FROM _node_results_old
+                """)
+
+                cursor.execute("DROP TABLE _sessions_old")
+                cursor.execute("DROP TABLE _node_inputs_old")
+                cursor.execute("DROP TABLE _node_results_old")
+
+    def get_effective_user_id(self, hf_user: dict | None = None) -> str | None:
+        is_on_spaces = os.environ.get("SPACE_ID") is not None
+        if hf_user and hf_user.get("username"):
+            return hf_user["username"]
+        if is_on_spaces:
+            return None
+        return "local"
+
+    def create_sheet(
+        self, user_id: str, graph_name: str, name: str | None = None
+    ) -> str:
+        sheet_id = str(uuid.uuid4())
+        now = datetime.now().isoformat()
+
+        if not name:
+            count = self.get_sheet_count(user_id, graph_name)
+            name = f"Sheet {count + 1}"
+
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            """INSERT INTO sheets (sheet_id, user_id, graph_name, name, created_at, updated_at) 
+               VALUES (?, ?, ?, ?, ?, ?)""",
+            (sheet_id, user_id, graph_name, name, now, now),
+        )
+        conn.commit()
+        conn.close()
+        return sheet_id
+
+    def get_sheet_count(self, user_id: str, graph_name: str) -> int:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            "SELECT COUNT(*) FROM sheets WHERE user_id = ? AND graph_name = ?",
+            (user_id, graph_name),
+        )
+        count = cursor.fetchone()[0]
+        conn.close()
+        return count
+
+    def list_sheets(self, user_id: str, graph_name: str) -> list[dict[str, Any]]:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            """SELECT sheet_id, name, created_at, updated_at 
+               FROM sheets 
+               WHERE user_id = ? AND graph_name = ?
+               ORDER BY updated_at DESC""",
+            (user_id, graph_name),
+        )
+        rows = cursor.fetchall()
+        conn.close()
+        return [
+            {
+                "sheet_id": row[0],
+                "name": row[1],
+                "created_at": row[2],
+                "updated_at": row[3],
+            }
+            for row in rows
+        ]
+
+    def get_sheet(self, sheet_id: str) -> dict[str, Any] | None:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            """SELECT sheet_id, user_id, graph_name, name, transform, created_at, updated_at 
+               FROM sheets WHERE sheet_id = ?""",
+            (sheet_id,),
+        )
+        row = cursor.fetchone()
+        conn.close()
+        if row:
+            transform = None
+            if row[4]:
+                try:
+                    transform = json.loads(row[4])
+                except (json.JSONDecodeError, TypeError):
+                    pass
+            return {
+                "sheet_id": row[0],
+                "user_id": row[1],
+                "graph_name": row[2],
+                "name": row[3],
+                "transform": transform,
+                "created_at": row[5],
+                "updated_at": row[6],
+            }
+        return None
+
+    def save_transform(self, sheet_id: str, x: float, y: float, scale: float) -> bool:
+        now = datetime.now().isoformat()
+        transform = json.dumps({"x": x, "y": y, "scale": scale})
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            "UPDATE sheets SET transform = ?, updated_at = ? WHERE sheet_id = ?",
+            (transform, now, sheet_id),
+        )
+        updated = cursor.rowcount > 0
+        conn.commit()
+        conn.close()
+        return updated
+
+    def rename_sheet(self, sheet_id: str, new_name: str) -> bool:
+        now = datetime.now().isoformat()
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            "UPDATE sheets SET name = ?, updated_at = ? WHERE sheet_id = ?",
+            (new_name, now, sheet_id),
+        )
+        updated = cursor.rowcount > 0
+        conn.commit()
+        conn.close()
+        return updated
+
+    def delete_sheet(self, sheet_id: str) -> bool:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute("DELETE FROM node_inputs WHERE sheet_id = ?", (sheet_id,))
+        cursor.execute("DELETE FROM node_results WHERE sheet_id = ?", (sheet_id,))
+        cursor.execute("DELETE FROM sheets WHERE sheet_id = ?", (sheet_id,))
+        deleted = cursor.rowcount > 0
+        conn.commit()
+        conn.close()
+        return deleted
+
+    def get_or_create_sheet(
+        self, user_id: str, graph_name: str, sheet_id: str | None = None
+    ) -> str:
+        if sheet_id:
+            sheet = self.get_sheet(sheet_id)
+            if sheet and sheet["user_id"] == user_id:
+                return sheet_id
+
+        sheets = self.list_sheets(user_id, graph_name)
+        if sheets:
+            return sheets[0]["sheet_id"]
+
+        return self.create_sheet(user_id, graph_name)
+
+    def save_input(self, sheet_id: str, node_name: str, port_name: str, value: Any):
+        now = datetime.now().isoformat()
+        value_json = json.dumps(value, default=str)
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            """INSERT INTO node_inputs (sheet_id, node_name, port_name, value, updated_at)
+               VALUES (?, ?, ?, ?, ?)
+               ON CONFLICT(sheet_id, node_name, port_name) 
+               DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at""",
+            (sheet_id, node_name, port_name, value_json, now),
+        )
+        cursor.execute(
+            "UPDATE sheets SET updated_at = ? WHERE sheet_id = ?",
+            (now, sheet_id),
+        )
+        conn.commit()
+        conn.close()
+
+    def get_inputs(self, sheet_id: str) -> dict[str, dict[str, Any]]:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            "SELECT node_name, port_name, value FROM node_inputs WHERE sheet_id = ?",
+            (sheet_id,),
+        )
+        results = cursor.fetchall()
+        conn.close()
+        inputs: dict[str, dict[str, Any]] = {}
+        for node_name, port_name, value_json in results:
+            if node_name not in inputs:
+                inputs[node_name] = {}
+            inputs[node_name][port_name] = json.loads(value_json)
+        return inputs
+
+    def save_result(
+        self,
+        sheet_id: str,
+        node_name: str,
+        result: Any,
+        inputs_snapshot: dict[str, Any] | None = None,
+    ):
+        now = datetime.now().isoformat()
+        result_json = json.dumps(result, default=str)
+        inputs_json = (
+            json.dumps(inputs_snapshot, default=str) if inputs_snapshot else None
+        )
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            "INSERT INTO node_results (sheet_id, node_name, result, inputs_snapshot, created_at) VALUES (?, ?, ?, ?, ?)",
+            (sheet_id, node_name, result_json, inputs_json, now),
+        )
+        cursor.execute(
+            "UPDATE sheets SET updated_at = ? WHERE sheet_id = ?",
+            (now, sheet_id),
+        )
+        conn.commit()
+        conn.close()
+
+    def get_latest_result(self, sheet_id: str, node_name: str) -> Any | None:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            """SELECT result FROM node_results 
+               WHERE sheet_id = ? AND node_name = ? 
+               ORDER BY created_at DESC LIMIT 1""",
+            (sheet_id, node_name),
+        )
+        result = cursor.fetchone()
+        conn.close()
+        if result:
+            return json.loads(result[0])
+        return None
+
+    def get_result_count(self, sheet_id: str, node_name: str) -> int:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            "SELECT COUNT(*) FROM node_results WHERE sheet_id = ? AND node_name = ?",
+            (sheet_id, node_name),
+        )
+        count = cursor.fetchone()[0]
+        conn.close()
+        return count
+
+    def get_result_by_index(
+        self, sheet_id: str, node_name: str, index: int
+    ) -> Any | None:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            """SELECT result FROM node_results 
+               WHERE sheet_id = ? AND node_name = ? 
+               ORDER BY created_at ASC""",
+            (sheet_id, node_name),
+        )
+        results = cursor.fetchall()
+        conn.close()
+        if results and 0 <= index < len(results):
+            return json.loads(results[index][0])
+        elif results:
+            return json.loads(results[-1][0])
+        return None
+
+    def get_all_results(self, sheet_id: str) -> dict[str, list[Any]]:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute(
+            """SELECT node_name, result, inputs_snapshot FROM node_results 
+               WHERE sheet_id = ? 
+               ORDER BY created_at ASC""",
+            (sheet_id,),
+        )
+        results = cursor.fetchall()
+        conn.close()
+        all_results: dict[str, list[Any]] = {}
+        for node_name, result_json, inputs_json in results:
+            if node_name not in all_results:
+                all_results[node_name] = []
+            result_data = {
+                "result": json.loads(result_json),
+                "inputs_snapshot": json.loads(inputs_json) if inputs_json else None,
+            }
+            all_results[node_name].append(result_data)
+        return all_results
+
+    def get_sheet_state(self, sheet_id: str) -> dict[str, Any]:
+        return {
+            "inputs": self.get_inputs(sheet_id),
+            "results": self.get_all_results(sheet_id),
+        }
+
+    def clear_sheet_data(self, sheet_id: str):
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute("DELETE FROM node_inputs WHERE sheet_id = ?", (sheet_id,))
+        cursor.execute("DELETE FROM node_results WHERE sheet_id = ?", (sheet_id,))
+        conn.commit()
+        conn.close()
+
+    def create_session(self, graph_name: str) -> str:
+        return self.create_sheet("local", graph_name)
+
+    def get_or_create_session(self, session_id: str | None, graph_name: str) -> str:
+        return self.get_or_create_sheet("local", graph_name, session_id)

pyproject.toml

@@ -6,13 +6,13 @@ readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.11"
 dependencies = [
-    "gradio==4.19.2",
-    "huggingface_hub==0.20.3",
+    "gradio>=4.19.2",
+    "huggingface_hub>=0.20.3",
     "modal",
     "typer",
     "pillow",
     "python-dotenv",
-    "daggr",
+    "daggr @ git+https://github.com/gradio-app/daggr.git",
 ]
 
 [project.optional-dependencies]

requirements.txt

@@ -1,6 +1,4 @@
 gradio==4.19.2
-huggingface_hub==0.20.3
 modal
-pillow
-python-dotenv
-daggr
+Pillow
+./daggr

test_daggr_init.py

@@ -0,0 +1,28 @@
+
+import os
+import io
+import modal
+import gradio as gr
+from PIL import Image
+from daggr import FnNode, Graph
+
+def convert_image_to_bytes(image) -> bytes:
+    return b"test"
+
+try:
+    print("Attempting to create FnNode...")
+    converter = FnNode(
+        fn=convert_image_to_bytes,
+        name="Image Converter",
+        inputs={
+            "image": gr.Image(label="Upload your photo"),
+        },
+        outputs={
+            "output": gr.Textbox(visible=False),
+        },
+    )
+    print("Success!")
+    print(f"Output port: {converter.output}")
+except Exception as e:
+    import traceback
+    traceback.print_exc()