gradio-workflowcanvas 0.0.1__tar.gz

gradio_workflowcanvas-0.0.1/.gitignore

@@ -0,0 +1,12 @@
+.eggs/
+dist/
+*.pyc
+__pycache__/
+*.py[cod]
+*$py.class
+__tmp/*
+*.pyi
+.mypycache
+.ruff_cache
+node_modules
+backend/**/templates/

gradio_workflowcanvas-0.0.1/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: gradio-workflowcanvas
+Version: 0.0.1
+Summary: Visual workflow builder for connecting Hugging Face Spaces into AI pipelines
+Project-URL: Repository, https://github.com/gradio-app/workflow-builder
+Project-URL: Space, https://huggingface.co/spaces/hmb/workflow
+Project-URL: Documentation, https://github.com/gradio-app/workflow-builder/blob/main/WORKFLOW_SPEC.md
+Author-email: Gradio Team <hello@gradio.app>
+License-Expression: Apache-2.0
+Keywords: gradio-custom-component,gradio-template-HTML
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Requires-Dist: gradio<7.0,>=6.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+---
+title: Workflow Builder
+app_file: app.py
+sdk: gradio
+sdk_version: 6.12.0
+hf_oauth: true
+---
+
+# Workflow Builder
+
+Build and run AI pipelines visually by connecting Hugging Face Spaces together.

gradio_workflowcanvas-0.0.1/README.md

@@ -0,0 +1,11 @@
+---
+title: Workflow Builder
+app_file: app.py
+sdk: gradio
+sdk_version: 6.12.0
+hf_oauth: true
+---
+
+# Workflow Builder
+
+Build and run AI pipelines visually by connecting Hugging Face Spaces together.

gradio_workflowcanvas-0.0.1/WORKFLOW_SPEC.md

@@ -0,0 +1,450 @@
+# Workflow Builder Specification
+
+## Overview
+
+**Workflow Builder** is a visual, no-code platform for building AI pipelines by connecting Hugging Face Spaces together. Users design workflows by:
+1. Creating input/output nodes
+2. Dragging Spaces onto the canvas
+3. Wiring ports between nodes based on type compatibility
+4. Running the workflow end-to-end
+5. Exporting workflows as JSON for sharing
+
+**Key Principle**: Workflows are first-class artifacts (JSON files). They're separate from any UI/deployment. A single workflow can power multiple vibenodes or integrations.
+
+---
+
+## Architecture
+
+### Frontend (TypeScript/Svelte)
+- **WorkflowCanvas.svelte** (1690 lines) — main UI, toolbar, modals, pan/zoom, keyboard shortcuts
+- **WorkflowNode.svelte** (1209 lines) — node rendering, inline widgets, ports, drag-and-drop
+- **WorkflowEdges.svelte** (212 lines) — edge rendering with type badges, DOM-based port positioning
+- **WorkflowSidebar.svelte** (858 lines) — component library, Space search, favorites, resizable
+- **workflow-store.ts** (153 lines) — Svelte writable store, node/edge CRUD, undo/redo foundation
+- **workflow-executor.ts** (230 lines) — parallel layer-based execution, client caching, retry logic
+- **space-api.ts** (180 lines) — API introspection via `client.view_api()`, endpoint heuristics
+- **node-library.ts** (256 lines) — preset Spaces (RMBG, FLUX, Whisper, etc.), component templates
+- **workflow-types.ts** (99 lines) — TypeScript interfaces and port color scheme
+- **workflow-to-space.ts** (236 lines) — generates `app.py` using `gradio_client.Client.predict()`
+
+### Backend (Python)
+- **app.py** (133 lines) — Gradio block hosting the custom WorkflowCanvas component
+- **workflowcanvas.py** — Python wrapper for the custom component
+- `server_functions` exposed to frontend:
+  - `get_token()` — returns HF token from OAuth
+  - `call_space(data, token)` — calls remote Space with file handling
+
+### Custom Component
+- Built with Gradio's custom component SDK
+- Compiled to wheel file for easy distribution
+- Exposes `server_functions` for frontend→backend RPC
+
+---
+
+## Data Model
+
+### Workflow (JSON)
+```typescript
+interface Workflow {
+  version: "1";                    // schema version
+  name: string;                    // workflow name (used in export filename)
+  nodes: WFNode[];
+  edges: WFEdge[];
+}
+```
+
+### Node
+```typescript
+interface WFNode {
+  id: string;                      // unique ID (e.g., "n1", "n2")
+  kind: "input" | "transform" | "output";
+  label: string;                   // display name
+  source: "local" | "space";       // local = input/output, space = HF Space
+  space_id?: string;               // "username/space-name" if source=space
+  endpoint?: string;               // API endpoint (e.g., "/predict", "/image")
+  inputs: Port[];
+  outputs: Port[];
+  x: number;                       // canvas position (px)
+  y: number;
+  width: number;                   // node card size
+  height: number;
+  data: Record<string, unknown>;   // state for input nodes or inline widgets
+}
+```
+
+### Port
+```typescript
+interface Port {
+  id: string;                      // "in_0", "out_1", etc.
+  label: string;                   // display name
+  type: PortType;                  // e.g., "image", "text", "file"
+  required?: boolean;              // from API introspection
+  default_value?: unknown;
+}
+```
+
+### Port Types
+```
+"image" | "text" | "audio" | "video" | "number" | "boolean" | 
+"file" | "json" | "gallery" | "model3d" | "any"
+```
+
+### Edge
+```typescript
+interface WFEdge {
+  id: string;
+  from_node_id: string;
+  from_port_id: string;
+  to_node_id: string;
+  to_port_id: string;
+  type: PortType;                  // enforced at connection time
+}
+```
+
+---
+
+## Core Features
+
+### 1. Canvas & Interaction
+- **Pan/Zoom**: scroll to pan, pinch/scroll to zoom, `Cmd+0` to reset
+- **Grid**: dot grid, snap-to-grid on node drop
+- **Node Selection**: click to select, `Delete` to remove
+- **Duplication**: `Cmd+D` to duplicate selected node
+- **Rename**: double-click node label to edit
+- **Auto-layout**: `Layout` button distributes nodes vertically
+
+### 2. Wiring & Type Safety
+- Ports colored by type (image=cyan, text=purple, audio=orange, etc.)
+- Type checking: can only wire compatible types
+- Auto-create input/output nodes: `+` button on ports
+- Connection badges show port type on hover
+- Edge delete on hover (X icon)
+
+### 3. Node Library
+- **Presets**: BRIA RMBG, FLUX.1-schnell, Whisper, Finegrain, UNESCO/nllb, etc.
+- **Space Search**: search HuggingFace Hub, filter to running Spaces
+- **API Introspection**: auto-detect inputs, outputs, required/optional params
+- **Endpoint Selection**: heuristic picks best endpoint (filters event handlers, prioritizes rich outputs)
+- **Custom Spaces**: add by space ID, saved to localStorage
+
+### 4. Execution Engine
+- **Topological Sort**: executes nodes in dependency order
+- **Parallel Layers**: nodes at same depth run in parallel
+- **Client Caching**: one `Client` instance per Space to share auth/connection
+- **Retry Logic**: retries stale clients (connection reset)
+- **File Handling**: 
+  - Blob URLs → uploaded to server → passed to Space
+  - Remote file paths → converted to `/file=` URLs
+  - Results stored in node output for downstream use
+- **Status Tracking**: idle→running→done/error per node
+- **Abort Signal**: can stop running workflow with `Cmd+.`
+
+### 5. API Introspection
+- Uses `client.view_api(return_format="dict")` to inspect Space
+- Extracts `named_endpoints`, parameter names, types, defaults, labels
+- Maps Gradio component types to port types (e.g., `Image` → `image`)
+- Falls back to type field parsing (e.g., "filepath" → `file`)
+- Detects optional params via `parameter_has_default`
+
+### 6. Export & Import
+- **Export**: downloads workflow as `workflow_name.workflow.json`
+- **Import**: loads JSON back into canvas
+- **No Server Dependency**: JSON is self-contained, portable
+
+---
+
+## Execution Flow
+
+1. **User clicks Run**
+   - Collect all node inputs from canvas state
+   - Build dependency graph from edges
+   - Topologically sort nodes
+
+2. **Execute Layer by Layer**
+   - For each layer (depth level):
+     - For each node in parallel:
+       - Resolve inputs (from upstream outputs or node.data)
+       - If transform node: call Space endpoint
+       - Update node output data
+       - Update UI status
+
+3. **File Handling During Execution**
+   - Blob URLs (from file upload) → `POST /upload` → get server path
+   - Remote file paths → passed to Space as-is
+   - Space returns local paths → convert to `/file=/path` URLs
+   - Downstream nodes receive readable URLs
+
+4. **Error Handling**
+   - Classify errors (GPU unavailable, quota exceeded, timeout, etc.)
+   - Show contextual toast messages
+   - Mark node as error, stop execution
+   - User can fix inputs and re-run
+
+---
+
+## Backend API
+
+### Python Backend (app.py)
+
+**Server Functions** exposed to frontend:
+
+#### `get_token(token: Optional[OAuthToken]) -> str`
+Returns the user's HF token if logged in, empty string otherwise.
+
+#### `call_space(data: list, token: Optional[OAuthToken]) -> str`
+Calls a remote Gradio Space.
+
+**Parameters:**
+```python
+data = [
+  space_id,       # "username/space-name"
+  endpoint,       # "/predict" or "/image" etc.
+  args_json,      # JSON array of arguments
+  manual_token    # Optional token from localStorage
+]
+```
+
+**Returns:** JSON-encoded output array
+```json
+[
+  { "path": "/tmp/file", "url": "/file=/tmp/file", "is_file": true },
+  { "data": "text result" },
+  ...
+]
+```
+
+**Error Response:**
+```json
+{
+  "error": "error message",
+  "error_type": "gpu|quota|timeout|not_found|...",
+  "suggestion": "user-facing hint",
+  "title": "optional error title"
+}
+```
+
+**Error Classification:**
+- `gpu`: ZeroGPU unavailable
+- `quota`: Rate limit / GPU quota exceeded
+- `sleeping`: Space paused or sleeping
+- `not_found`: Space deleted or renamed
+- `build_error`: Space has build errors
+- `connection`: Cannot connect to Space (timeout, down, etc.)
+- `unknown`: Other errors
+
+---
+
+## Workflow JSON Example
+
+```json
+{
+  "version": "1",
+  "name": "Image Background Removal",
+  "nodes": [
+    {
+      "id": "input_1",
+      "kind": "input",
+      "label": "Image",
+      "source": "local",
+      "inputs": [],
+      "outputs": [
+        { "id": "out_0", "label": "Image", "type": "image" }
+      ],
+      "x": 100,
+      "y": 100,
+      "width": 220,
+      "height": 160,
+      "data": {}
+    },
+    {
+      "id": "transform_1",
+      "kind": "transform",
+      "label": "Remove Background",
+      "source": "space",
+      "space_id": "not-lain/background-removal",
+      "endpoint": "/image",
+      "inputs": [
+        { "id": "in_0", "label": "Image", "type": "image", "required": true }
+      ],
+      "outputs": [
+        { "id": "out_0", "label": "Image", "type": "image" }
+      ],
+      "x": 450,
+      "y": 100,
+      "width": 200,
+      "height": 90,
+      "data": {}
+    },
+    {
+      "id": "output_1",
+      "kind": "output",
+      "label": "Result",
+      "source": "local",
+      "inputs": [
+        { "id": "in_0", "label": "Image", "type": "image" }
+      ],
+      "outputs": [],
+      "x": 750,
+      "y": 100,
+      "width": 220,
+      "height": 160,
+      "data": {}
+    }
+  ],
+  "edges": [
+    {
+      "id": "edge_1",
+      "from_node_id": "input_1",
+      "from_port_id": "out_0",
+      "to_node_id": "transform_1",
+      "to_port_id": "in_0",
+      "type": "image"
+    },
+    {
+      "id": "edge_2",
+      "from_node_id": "transform_1",
+      "from_port_id": "out_0",
+      "to_node_id": "output_1",
+      "to_port_id": "in_0",
+      "type": "image"
+    }
+  ]
+}
+```
+
+---
+
+## UI/UX
+
+### Toolbar
+- **Token Input**: paste HF token for GPU access (saved to localStorage)
+- **Templates**: quick-start workflows (background removal, image generation, etc.)
+- **Export/Import**: download/upload workflow.json
+- **Layout**: auto-arrange nodes
+- **Clear**: delete all nodes and edges
+- **Run**: execute workflow end-to-end
+- **Stop**: abort running workflow
+
+### Keyboard Shortcuts
+- `Cmd+R` or Click Run → execute
+- `Cmd+.` → stop running
+- `Cmd+S` → export workflow
+- `Delete` → remove selected node
+- `Cmd+D` → duplicate selected node
+- `Cmd+0` → reset pan/zoom
+- `?` → show shortcuts help
+
+### Sidebar
+- **Component Library**: input/output/transform node templates
+- **Spaces**: preset and custom Spaces with categories (IMAGE, AUDIO, TEXT, etc.)
+- **Search**: find Spaces on HF Hub, filter by name
+- **Resizable**: drag divider to expand/collapse
+- **Collapsible**: click chevron to collapse header
+
+### Modals
+- **Deploy** (removed): was generating Gradio Space apps, no longer needed
+- **Templates**: quick-start workflows
+- **Shortcuts**: keyboard reference
+
+---
+
+## Constraints & Design Decisions
+
+1. **Workflows ≠ Gradio Apps**: Workflows are JSON artifacts, not UI deployments. Separate concerns.
+
+2. **Type System**: Simple 10-type system covers most cases. `any` for unknowns.
+
+3. **API Introspection**: Uses Gradio client's `view_api()` for zero-configuration Space discovery.
+
+4. **File Handling**: 
+   - Blob URLs must be uploaded to server before passing to remote Spaces
+   - Remote file paths use `/file=` URL scheme for browser access
+   - Gradio handles auth/CORS transparently via client
+
+5. **Execution**: Topological sort + layer-based parallel execution maximizes throughput without complexity.
+
+6. **Storage**: 
+   - Workflow JSON is portable (no server state)
+   - HF token saved to localStorage (client-side only)
+   - Node state persisted only in running workflow
+
+7. **Error Recovery**: 
+   - Client caching + retry handles transient connection issues
+   - Classified errors provide user-facing guidance
+   - No auto-recovery for invalid Space IDs or missing endpoints
+
+---
+
+## Limitations & Future Work
+
+### Current Limitations
+- No loops or conditional branching
+- No multi-Space chains (edges can only wire N→1, 1→N, never M→N split)
+- No node comments or versioning
+- No collaborative editing
+- No workflow versioning or rollback
+- Endpoint selection heuristic can fail on complex Spaces (needs manual override UI)
+
+### Future Enhancements
+1. **Workflow Sharing Registry**: platform to publish/discover workflows
+2. **Vibenode Integration**: export workflow → auto-generate vibenode boilerplate
+3. **Branches & Loops**: conditional execution, map operations
+4. **Caching Layer**: skip re-running unchanged nodes
+5. **Scheduling**: trigger workflows on cron schedule
+6. **Monitoring**: runtime logs, performance metrics
+7. **Version Control**: git-like workflow snapshots
+8. **Collaborative**: real-time multi-user editing
+
+---
+
+## Tech Stack
+
+- **Frontend**: Svelte 4, TypeScript, Vite
+- **Canvas**: DOM-based (no canvas library), custom pan/zoom
+- **Backend**: Python, Gradio 6.12+, gradio_client
+- **Component Distribution**: Gradio custom component wheel
+- **Hosting**: HuggingFace Spaces
+- **External API**: HuggingFace Hub (`gradio_client.Client`)
+
+---
+
+## File Structure
+
+```
+workflow-app/
+├── app.py                          # Main Gradio app
+├── pyproject.toml                  # Python package config
+├── backend/
+│   └── gradio_workflowcanvas/      # Custom component backend
+│       └── workflowcanvas.py
+├── frontend/
+│   ├── Index.svelte                # Component root
+│   ├── gradio.config.js
+│   ├── package.json
+│   ├── tsconfig.json
+│   └── workflow/                   # Main app logic
+│       ├── WorkflowCanvas.svelte   # Main UI
+│       ├── WorkflowNode.svelte     # Node renderer
+│       ├── WorkflowEdges.svelte    # Edge renderer
+│       ├── WorkflowSidebar.svelte  # Component library
+│       ├── workflow-types.ts       # Type definitions
+│       ├── workflow-store.ts       # State management
+│       ├── workflow-executor.ts    # Execution engine
+│       ├── space-api.ts            # API introspection
+│       ├── node-library.ts         # Preset Spaces
+│       └── workflow-to-space.ts    # Code generation (removed)
+└── dist/                           # Built wheel file
+```
+
+---
+
+## Glossary
+
+- **Node**: A UI card on canvas representing either an input, transformation (Space call), or output
+- **Port**: An input or output pin on a node (e.g., "image in", "text out")
+- **Edge**: A connection between two ports
+- **Workflow**: A complete DAG of nodes and edges, exportable as JSON
+- **Space**: A Gradio app on HuggingFace Hub
+- **Endpoint**: An API function in a Space (e.g., `/predict`, `/image`)
+- **Transform**: A node that calls a Space endpoint (fn node)
+- **Vibenode**: A separate UI layer built on top of workflows (not part of this spec)

gradio_workflowcanvas-0.0.1/app.py

@@ -0,0 +1,133 @@
+# WorkflowCanvas component is installed via pip (published to PyPI)
+# For local development: pip install -e .
+
+import gradio as gr
+from gradio.oauth import OAuthToken
+from gradio_workflowcanvas import WorkflowCanvas
+from gradio_client import Client, handle_file
+from typing import Optional
+import json
+import os
+
+
+def get_token(token: Optional[OAuthToken] = None) -> str:
+    if token is None:
+        return ""
+    return token.token
+
+
+def classify_error(e: Exception) -> dict:
+    """Classify an error into a type and suggestion for the frontend."""
+    title = getattr(e, 'title', None) or ""
+    message = getattr(e, 'message', None) or str(e)
+    full = f"{title} {message}".lower()
+
+    if "zerogpu" in full or "gpu" in full and "worker" in full:
+        return {"error_type": "gpu", "suggestion": "GPU unavailable — try again or log in with your HF account"}
+    if "quota" in full or "rate limit" in full:
+        return {"error_type": "quota", "suggestion": "GPU quota exceeded — log in with your HF account for more compute"}
+    if "sleeping" in full or "paused" in full:
+        return {"error_type": "sleeping", "suggestion": "Space is sleeping or paused — try again in a minute"}
+    if "not found" in full or "404" in full or "repository not found" in full:
+        return {"error_type": "not_found", "suggestion": "Space not found — it may have been deleted or renamed"}
+    if "build_error" in full or "build error" in full:
+        return {"error_type": "build_error", "suggestion": "Space has a build error — contact the Space owner"}
+    if "timed out" in full or "timeout" in full or "connection" in full:
+        return {"error_type": "connection", "suggestion": "Could not connect to the Space — it may be down"}
+
+    return {"error_type": "unknown", "suggestion": ""}
+
+
+def call_space(data, token: Optional[OAuthToken] = None) -> str:
+    try:
+        space_id = data[0]
+        endpoint = data[1] if len(data) > 1 else None
+        args_json = data[2] if len(data) > 2 else "[]"
+        manual_token = data[3] if len(data) > 3 else None
+
+        # Use manual token if provided, otherwise fall back to OAuth token
+        hf_token = manual_token or (token.token if token else None)
+        client = Client(space_id, token=hf_token)
+        args = json.loads(args_json)
+
+        if not endpoint or endpoint == "/predict":
+            api_info = client.view_api(return_format="dict")
+            named = list(api_info.get("named_endpoints", {}).keys())
+            if endpoint and endpoint in named:
+                pass
+            elif named:
+                endpoint = named[0]
+            else:
+                endpoint = "/predict"
+
+        processed = []
+        for arg in args:
+            if arg is None:
+                processed.append(None)
+            elif isinstance(arg, dict) and ("url" in arg or "path" in arg):
+                url = arg.get("url") or arg.get("path", "")
+                if url:
+                    processed.append(handle_file(url))
+                else:
+                    processed.append(None)
+            else:
+                processed.append(arg)
+
+        # Strip trailing None args so the Space uses its own defaults.
+        # view_api(return_format="dict") returns default=None even when defaults
+        # exist, so we'd otherwise pass null for optional args and get
+        # "No value provided for required argument".
+        while processed and processed[-1] is None:
+            processed.pop()
+
+        result = client.predict(*processed, api_name=endpoint)
+
+        if not isinstance(result, (list, tuple)):
+            result = [result]
+        else:
+            result = list(result)
+
+        output = []
+        for item in result:
+            if isinstance(item, dict) and "url" in item:
+                # Already processed by gradio_client, use as-is
+                output.append(item)
+            elif isinstance(item, str) and os.path.exists(item):
+                # Local file path - convert to /file= URL for browser access
+                output.append({"path": item, "url": f"/file={item}", "is_file": True})
+            elif isinstance(item, dict):
+                output.append(item)
+            elif isinstance(item, (list, tuple)):
+                sub = []
+                for s in item:
+                    if isinstance(s, dict) and "url" in s:
+                        sub.append(s)
+                    elif isinstance(s, str) and os.path.exists(s):
+                        sub.append({"path": s, "url": f"/file={s}", "is_file": True})
+                    elif isinstance(s, dict):
+                        sub.append(s)
+                    else:
+                        sub.append(s)
+                output.append(sub)
+            else:
+                output.append(item)
+
+        return json.dumps(output)
+    except Exception as e:
+        title = getattr(e, 'title', None)
+        message = getattr(e, 'message', None) or str(e)
+        classified = classify_error(e)
+        error_info = {
+            "error": message,
+            **classified,
+        }
+        if title:
+            error_info["title"] = title
+        return json.dumps(error_info)
+
+
+with gr.Blocks() as demo:
+    canvas = WorkflowCanvas(server_functions=[get_token, call_space])
+
+if __name__ == "__main__":
+    demo.launch(css=".toast-wrap { display: none !important; }")

gradio_workflowcanvas-0.0.1/backend/gradio_workflowcanvas/__init__.py

@@ -0,0 +1,4 @@
+
+from .workflowcanvas import WorkflowCanvas
+
+__all__ = ['WorkflowCanvas']