Skip to content

Commit 06eef35

Browse files
add docs (#13545)
* add docs * Update 02_workflow.md * changes * changes * changes * Update 18_workflows.md --------- Co-authored-by: Abubakar Abid <[email protected]> Co-authored-by: Abubakar Abid <[email protected]>
1 parent d4d340d commit 06eef35

1 file changed

Lines changed: 178 additions & 0 deletions

File tree

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# gr.Workflow
2+
3+
`gr.Workflow` is a visual, node-based AI pipeline builder built into Gradio. It lets you chain together Hugging Face Spaces, models, datasets, and your own Python functions on a drag-and-drop canvas:
4+
5+
<img width="1901" alt="image" src="https://github.com/user-attachments/assets/a77bf9a8-c264-4037-80e1-2b37c5e529d4" />
6+
7+
8+
## Quickstart
9+
10+
The simplest possible Workflow app:
11+
12+
```python
13+
import gradio as gr
14+
15+
gr.Workflow().launch()
16+
```
17+
18+
Open the app, drag Spaces and models from the sidebar onto the canvas, connect their ports, and hit **Run**. As you create nodes and edges, a `workflow.json` file will automatically be created in your working directory. You can also use a coding agent to write or edit this file, allowing you to create workflows programmatically.
19+
20+
## Binding Python functions
21+
22+
Pass your own Python functions via `bind=` and they appear as callable nodes on the canvas. Gradio inspects the function signature to auto-generate input/output ports.
23+
24+
```python
25+
import gradio as gr
26+
27+
def summarize(text: str) -> str:
28+
return text[:200]
29+
30+
gr.Workflow(bind=[summarize]).launch()
31+
```
32+
33+
Use a dict to give nodes explicit names:
34+
35+
```python
36+
gr.Workflow(bind={"My Summarizer": summarize}).launch()
37+
```
38+
39+
## Defining edges in code
40+
41+
For pipelines you want to ship with a fixed topology, declare edges programmatically:
42+
43+
```python
44+
import gradio as gr
45+
46+
def clean(text: str) -> str:
47+
return text.strip().lower()
48+
49+
def tag(text: str) -> str:
50+
return f"[processed] {text}"
51+
52+
gr.Workflow(
53+
bind=[clean, tag],
54+
edges=[("clean", "tag")],
55+
).launch()
56+
```
57+
58+
Each edge is a `(from_fn, to_fn)` tuple. Use `"fn_name.port_label"` to target a specific port when a node has multiple inputs or outputs.
59+
60+
> **Note:** `edges=` is only applied when no workflow file exists yet. If `workflow.json` already exists, `edges=` is ignored — delete the file to regenerate the topology from `bind` and `edges`.
61+
62+
## Loading from a JSON file
63+
64+
Pass a `graph=` path to load a saved workflow topology. The canvas reads from the file on each page load and autosaves back to it when you make edits.
65+
66+
```python
67+
gr.Workflow(graph="workflow.json").launch()
68+
```
69+
70+
If the file doesn't exist yet, it's created on first save. Combine `graph=` with `bind=` to pre-wire Space nodes alongside your Python functions.
71+
72+
## Workflow JSON format
73+
74+
A workflow is a JSON file with three node collections:
75+
76+
```json
77+
{
78+
"schema_version": "2",
79+
"name": "My Pipeline",
80+
"references": [
81+
{
82+
"id": "ref_image", "label": "Input Photo", "role": "reference",
83+
"asset_type": "image",
84+
"inputs": [{"id": "in", "label": "Image", "type": "image"}],
85+
"outputs": [{"id": "out","label": "Image", "type": "image"}],
86+
"x": 80, "y": 120, "width": 220, "height": 124, "data": {}
87+
}
88+
],
89+
"operators": [
90+
{
91+
"id": "op_flux", "label": "FLUX.1", "role": "operator",
92+
"kind": "space",
93+
"space_id": "black-forest-labs/FLUX.1-schnell",
94+
"endpoint": "/infer",
95+
"inputs": [{"id": "in_0", "label": "Prompt", "type": "text", "required": true}],
96+
"outputs": [{"id": "out_0","label": "Result","type": "image","output_index": 0}],
97+
"x": 400, "y": 120, "width": 220, "height": 124, "data": {}
98+
}
99+
],
100+
"subjects": [
101+
{
102+
"id": "sub_img", "label": "Output Image", "role": "subject",
103+
"asset_type": "image",
104+
"inputs": [{"id": "in", "label": "Image", "type": "image"}],
105+
"outputs": [{"id": "out","label": "Image","type": "image"}],
106+
"x": 700, "y": 120, "width": 220, "height": 107, "data": {}
107+
}
108+
],
109+
"edges": [
110+
{
111+
"id": "e1",
112+
"from_node_id": "ref_image", "from_port_id": "out",
113+
"to_node_id": "op_flux", "to_port_id": "in_0",
114+
"type": "image"
115+
}
116+
]
117+
}
118+
```
119+
120+
| Collection | Role |
121+
|---|---|
122+
| `references` | Inputs — uploaded files, editable text, literal values |
123+
| `operators` | Processing steps — Spaces, models, datasets, Python functions |
124+
| `subjects` | Outputs — the results being created |
125+
126+
### Operator kinds
127+
128+
| `kind` | What it calls |
129+
|---|---|
130+
| `"space"` | Any Gradio Space on the Hub via `gradio_client` |
131+
| `"model"` | HF Inference API — set `pipeline_tag` to select the task |
132+
| `"dataset"` | Streams rows from any Hub dataset |
133+
| `"fn"` | A Python function passed via `bind=` |
134+
135+
## Port types
136+
137+
Ports are typed so the canvas can validate connections. Supported types:
138+
139+
`image` · `audio` · `video` · `text` · `number` · `boolean` · `gallery` · `file` · `json` · `model3d`
140+
141+
## Fan-out pipelines
142+
143+
One reference can feed multiple operators simultaneously — they run in parallel:
144+
145+
```python
146+
# workflow.json excerpt — one product photo → 4 FLUX Kontext branches
147+
"edges": [
148+
{"from_node_id": "ref_product", ..., "to_node_id": "op_kontext_0", ...},
149+
{"from_node_id": "ref_product", ..., "to_node_id": "op_kontext_1", ...},
150+
{"from_node_id": "ref_product", ..., "to_node_id": "op_kontext_2", ...},
151+
{"from_node_id": "ref_product", ..., "to_node_id": "op_kontext_3", ...}
152+
]
153+
```
154+
155+
## Deploying to Spaces
156+
157+
A Workflow app is a standard Gradio app — deploy it to Hugging Face Spaces exactly like any other, by uploading the code to a Space, or by simply running in your terminal:
158+
159+
```
160+
gradio deploy
161+
```
162+
163+
On a Space, the canvas authenticates visitors via OAuth. The Space owner gets write access (can edit and save the workflow); visitors get a read-only view and can run the pipeline with their own HF token. As a result, you should set `hf_oauth: true` [in your Space](https://huggingface.co/docs/hub/en/spaces-oauth).
164+
165+
## API access
166+
167+
Every Workflow app is a Gradio app, meaning that it exposes a Gradio REST API endpoint for each output (subject) node. The endpoint name is derived from the subject's label — for example, a subject labelled "Output Image" becomes `/output_image`. Use `client.view_api()` to see the exact names for your workflow:
168+
169+
```python
170+
from gradio_client import Client
171+
172+
client = Client("your-username/my-workflow")
173+
client.view_api() # lists available endpoints and their parameters
174+
175+
result = client.predict("a sunset over mountains", api_name="/output_image")
176+
```
177+
178+
This also means that you can reuse your workflows within larger workflows, making it possible to build modular and complex applications with Gradio Workflows!

0 commit comments

Comments
 (0)