koode-taskgraph 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. koode_taskgraph-0.4.0/PKG-INFO +325 -0
  2. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/README.md +134 -37
  3. koode_taskgraph-0.4.0/koode_taskgraph.egg-info/PKG-INFO +325 -0
  4. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/pyproject.toml +2 -1
  5. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/app.py +3 -9
  6. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/cli.py +1 -1
  7. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/nodes/builtin.py +7 -3
  8. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/ui/items.py +66 -20
  9. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/ui/main_window.py +51 -24
  10. koode_taskgraph-0.4.0/taskgraph/ui/plugins.py +485 -0
  11. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/tests/test_core.py +99 -0
  12. koode_taskgraph-0.4.0/tests/test_gui_plugins.py +366 -0
  13. koode_taskgraph-0.3.0/PKG-INFO +0 -9
  14. koode_taskgraph-0.3.0/koode_taskgraph.egg-info/PKG-INFO +0 -9
  15. koode_taskgraph-0.3.0/taskgraph/ui/plugins.py +0 -208
  16. koode_taskgraph-0.3.0/tests/test_gui_plugins.py +0 -159
  17. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/LICENSE +0 -0
  18. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/koode_taskgraph.egg-info/SOURCES.txt +0 -0
  19. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/koode_taskgraph.egg-info/dependency_links.txt +0 -0
  20. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/koode_taskgraph.egg-info/entry_points.txt +0 -0
  21. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/koode_taskgraph.egg-info/requires.txt +0 -0
  22. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/koode_taskgraph.egg-info/top_level.txt +0 -0
  23. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/setup.cfg +0 -0
  24. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/__init__.py +0 -0
  25. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/__main__.py +0 -0
  26. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/core/__init__.py +0 -0
  27. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/core/executor.py +0 -0
  28. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/core/model.py +0 -0
  29. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/core/registry.py +0 -0
  30. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/core/serialization.py +0 -0
  31. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/nodes/__init__.py +0 -0
  32. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/ui/__init__.py +0 -0
  33. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/ui/properties.py +0 -0
  34. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/ui/scene.py +0 -0
  35. {koode_taskgraph-0.3.0 → koode_taskgraph-0.4.0}/taskgraph/ui/theme.py +0 -0
@@ -0,0 +1,325 @@
1
+ Metadata-Version: 2.4
2
+ Name: koode-taskgraph
3
+ Version: 0.4.0
4
+ Summary: An extensible process node graph built with QtPy and PySide6
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ License-File: LICENSE
8
+ Requires-Dist: PySide6>=6.7
9
+ Requires-Dist: QtPy>=2.4
10
+ Dynamic: license-file
11
+
12
+ <p align="left">
13
+ <a href="https://buymeacoffee.com/cgarjun">
14
+ <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="50" alt="Buy Me A Coffee">
15
+ </a>
16
+ </p>
17
+
18
+ # Koode TaskGraph
19
+
20
+ TaskGraph is a small, extensible process graph editor built from scratch with
21
+ Python, QtPy, and PySide6.
22
+
23
+ ![Koode TaskGraph demo](images/demo-koode-taskgraph.png)
24
+
25
+ ## Run
26
+
27
+ ```bash
28
+ python -m venv .venv
29
+ source .venv/bin/activate
30
+ python -m pip install koode-taskgraph
31
+ koode-taskgraph
32
+ ```
33
+
34
+ For local development from this repository, use `python -m pip install -e .`.
35
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
36
+
37
+ ## Remove local user settings
38
+
39
+ TaskGraph stores user preferences with Qt `QSettings` under organization
40
+ `TaskGraph` and application `TaskGraph`. Settings include saved custom node
41
+ locations and the execution worker count. GUI plugin locations are session-only
42
+ and are not saved, but older versions may have saved GUI plugin locations.
43
+
44
+ Default locations:
45
+
46
+ - **macOS:** `~/Library/Preferences/com.taskgraph.TaskGraph.plist`
47
+ - **Linux:** `~/.config/TaskGraph/TaskGraph.conf`
48
+ - If `XDG_CONFIG_HOME` is set:
49
+ `$XDG_CONFIG_HOME/TaskGraph/TaskGraph.conf`
50
+ - **Windows:** Registry key
51
+ `HKEY_CURRENT_USER\Software\TaskGraph\TaskGraph`
52
+
53
+ Quit TaskGraph before removing settings.
54
+
55
+ macOS:
56
+
57
+ ```bash
58
+ defaults delete com.taskgraph.TaskGraph
59
+ ```
60
+
61
+ Linux:
62
+
63
+ ```bash
64
+ rm ~/.config/TaskGraph/TaskGraph.conf
65
+ ```
66
+
67
+ Windows Command Prompt:
68
+
69
+ ```bat
70
+ reg delete HKCU\Software\TaskGraph\TaskGraph /f
71
+ ```
72
+
73
+ Windows PowerShell:
74
+
75
+ ```powershell
76
+ Remove-Item -Path "HKCU:\Software\TaskGraph\TaskGraph" -Recurse -Force
77
+ ```
78
+
79
+ ## Headless CLI
80
+
81
+ Execute a saved graph without starting Qt or opening a window:
82
+
83
+ ```bash
84
+ koode-taskgraph-cli --file /path/to/workflow.taskgraph
85
+ ```
86
+
87
+ Select the worker count and load external node locations when needed:
88
+
89
+ ```bash
90
+ koode-taskgraph-cli \
91
+ --file /path/to/workflow.taskgraph \
92
+ --workers 8 \
93
+ --node-path /path/to/custom_nodes
94
+ ```
95
+
96
+ `--node-path` may be repeated. `TASKGRAPH_CUSTOM_NODES` is also supported with
97
+ the normal platform path separator. Use `--json` for structured results,
98
+ `--quiet` to hide progress messages, and `Ctrl+C` to cancel execution.
99
+
100
+ Exit codes are `0` for success, `1` for graph execution failure, `2` for
101
+ arguments/loading errors, and `130` for cancellation.
102
+
103
+ Double-click a node type in the left panel to add it. Drag from an output port
104
+ on the right of a node to an input port on the left of another node. Select a
105
+ node to edit its properties, then click **Run graph**.
106
+
107
+ ## Add a node
108
+
109
+ Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
110
+
111
+ ```python
112
+ from taskgraph.core.model import NodeProperty, PortSpec, ProcessNode
113
+ from taskgraph.core.registry import register_node
114
+
115
+ @register_node
116
+ class PrefixText(ProcessNode):
117
+ type_id = "custom.prefix_text"
118
+ title = "Prefix Text"
119
+ category = "Custom"
120
+ inputs = (PortSpec("value", "any"),)
121
+ outputs = (PortSpec("text", "text"),)
122
+ properties = (
123
+ NodeProperty("prefix", "Prefix", "text", "Result: "),
124
+ )
125
+
126
+ def process(self, inputs):
127
+ return {"text": f"{self.prefix}{inputs.get('value', '')}"}
128
+ ```
129
+
130
+ Property kinds map to generated controls in the Properties panel: `"text"` for
131
+ a line edit, `"file"` for a file path field with a Browse button, `"bool"` for
132
+ a checkbox, `"int"`/`"float"` for numeric fields, and `"choice"` for a
133
+ dropdown using `choices`.
134
+
135
+ Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
136
+ also live anywhere on disk:
137
+
138
+ 1. Put one or more standalone `.py` node modules in a directory.
139
+ 2. Select **Nodes → Add Custom Node Location…** and choose that directory.
140
+ 3. Restarting TaskGraph reloads the saved location automatically.
141
+
142
+ Alternatively, set `TASKGRAPH_CUSTOM_NODES` before launching. Separate multiple
143
+ directories with the platform path separator (`:` on macOS/Linux and `;` on
144
+ Windows):
145
+
146
+ ```bash
147
+ TASKGRAPH_CUSTOM_NODES="/path/to/company_nodes:/path/to/my_nodes" koode-taskgraph
148
+ ```
149
+
150
+ Files beginning with `_` are ignored. Importing a custom node module executes
151
+ its Python code, so only add trusted directories. The editor, property panel,
152
+ serialization, and executor require no other changes.
153
+
154
+ This repository includes a practical custom node example in
155
+ `examples/custom_nodes/text_cleanup.py`. Load `examples/custom_nodes` from
156
+ **Nodes → Add Custom Node Location…** or with:
157
+
158
+ ```bash
159
+ TASKGRAPH_CUSTOM_NODES="/path/to/taskgraph/examples/custom_nodes" koode-taskgraph
160
+ ```
161
+
162
+ The example adds **Examples → Clean Text**, which trims text, optionally
163
+ collapses whitespace, and applies a selectable case conversion.
164
+
165
+ ## Add a GUI plugin
166
+
167
+ GUI plugins can add menus, commands, docks, and graph-building tools without
168
+ editing TaskGraph source. Put one or more `.py` files in a plugin directory and
169
+ define `class Plugin(TaskGraphGuiPlugin)`.
170
+
171
+ The plugin API is split into namespaces. Inside `TaskGraphGuiPlugin` subclasses
172
+ these are available as:
173
+
174
+ - `self.commands` registers reusable commands.
175
+ - `self.ui` exposes GUI features such as menus, docks, and status messages.
176
+ - `self.graph` creates nodes, connects ports, reads the graph model, and adds
177
+ backdrops.
178
+
179
+ ```python
180
+ from taskgraph.ui.plugins import TaskGraphGuiPlugin
181
+
182
+
183
+ class Plugin(TaskGraphGuiPlugin):
184
+ plugin_id = "example.graph_daily_report"
185
+ name = "Daily Report Graph Builder"
186
+ version = "1.0.0"
187
+
188
+ def setup(self):
189
+ self.commands.register(
190
+ f"{self.plugin_id}.build_daily_report",
191
+ label="Graph API: Build Daily Report Graph",
192
+ callback=self.build_daily_report,
193
+ )
194
+ self.ui.menus.add_command(
195
+ "Examples",
196
+ f"{self.plugin_id}.build_daily_report",
197
+ )
198
+
199
+ def build_daily_report(self):
200
+ text = self.graph.create_node(
201
+ "input.text",
202
+ name="Report Title",
203
+ values={"text": "Daily Production Report"},
204
+ position=(0, 0),
205
+ )
206
+ printer = self.graph.create_node(
207
+ "output.print",
208
+ name="Print Report",
209
+ position=(320, 0),
210
+ )
211
+ self.graph.connect_dependency(text, printer)
212
+ self.graph.connect_attribute(text, "text", printer, "value")
213
+ self.graph.add_backdrop(
214
+ title="Daily Report Template",
215
+ note="This graph was created by a GUI plugin.",
216
+ position=(-40, -140),
217
+ size=(650, 170),
218
+ )
219
+ ```
220
+
221
+ Older flat helpers such as `api.create_node(...)` and
222
+ `api.add_menu_action(...)`, plus the old `register_taskgraph_plugin(api)`
223
+ function entrypoint, are still supported for compatibility. New plugins should
224
+ use the OOP `Plugin` class and namespaced API.
225
+
226
+ Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
227
+ session. GUI plugin locations are not saved or automatically reloaded on the
228
+ next launch. To load GUI plugins at startup, set `TASKGRAPH_GUI_PLUGINS` before
229
+ launching, using the same platform path separator rules as
230
+ `TASKGRAPH_CUSTOM_NODES`.
231
+
232
+ This repository includes separate practical example plugins in
233
+ `examples/gui_plugins`:
234
+
235
+ - `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
236
+ panel and writing a status message.
237
+ - `command_validate_graph.py` demonstrates the command API by registering a
238
+ reusable graph validation command and exposing it in the menu.
239
+ - `graph_daily_report.py` demonstrates the graph API by building a reusable
240
+ daily-report graph with nodes, dependency links, attribute links, and a
241
+ backdrop.
242
+
243
+ Load that directory, then use the **Examples** menu to run each example.
244
+
245
+ GUI plugins are intentionally separate from custom node locations. The
246
+ headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
247
+ import Qt widgets without breaking `koode-taskgraph-cli`.
248
+
249
+ ## Controls
250
+
251
+ - Standard commands are organized under the **File**, **Edit**, **Nodes**,
252
+ **Graph**, **Plugins**, and **View** menus.
253
+ - Use the search field at the top of the **Nodes** panel to filter nodes by
254
+ title, type id, or category.
255
+ - Drag a node from **Nodes** to the canvas, or double-click it.
256
+ - Every node has fixed gold **dependency** input/output ports. These control
257
+ process order but do not transfer values. Gold dependency connections show
258
+ an arrowhead pointing from the upstream node toward the downstream node.
259
+ - Declared node inputs and outputs are attribute ports. Attribute connections
260
+ transfer values, but execution order comes only from dependency connections.
261
+ An attribute connection therefore needs a dependency path from its source
262
+ node to its target node.
263
+ - Dependency ports connect only to dependency ports; compatible attribute
264
+ ports connect only to attribute ports.
265
+ - Select one or more nodes on the canvas and press **D** to toggle them
266
+ disabled. Disabled nodes stay in the dependency chain but their process
267
+ functions are skipped. The same command is available from **Edit**.
268
+ - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
269
+ shortcuts. Properties, disabled state, relative positions, and connections
270
+ entirely inside the copied selection are preserved.
271
+ - Select a node to edit generated property controls.
272
+ - Use **Node Name** at the top of the Properties panel to give each node
273
+ instance a descriptive name. Custom names appear in node headers and
274
+ execution messages and are preserved when saving or copying nodes.
275
+ - Select nodes or connections and press **Backspace** or **Delete** to remove
276
+ them. **Edit → Delete Selected** works on every platform too.
277
+ - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
278
+ - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
279
+ from left to right and parallel nodes vertically, then frames the result.
280
+ - **Graph → Add Backdrop** creates a movable notes region behind the graph.
281
+ Select it to edit its title, notes, color, width, and height in Properties.
282
+ Drag the grip in its bottom-right corner to resize it interactively.
283
+ Backdrops are stored in `.taskgraph` files.
284
+ - **Ctrl+R** executes nodes in dependency order.
285
+ - Independent dependency branches execute concurrently. Choose between one
286
+ worker or any even worker count from 2 through 32 under
287
+ **Graph → Worker Count**; the setting is remembered.
288
+ - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
289
+ Pending nodes are cancelled immediately. Running nodes receive a cooperative
290
+ cancellation signal, and built-in command nodes terminate their subprocess
291
+ groups promptly.
292
+ - Clear displayed execution messages with **Graph → Clear Execution Log** or
293
+ from the Execution panel's right-click menu.
294
+ - Built-in nodes are organized as **System → Run Command/Print**,
295
+ **Utils → Format Text**, and **Inputs → Text/Number**.
296
+ - The built-in **System → Run Command** node executes a command and exposes
297
+ stdout, stderr, and return code outputs. It supports an optional working
298
+ directory, shell mode, timeout, and failure on non-zero exit. Shell mode
299
+ executes exactly what the graph author enters, so only run trusted graphs.
300
+ - The built-in **Utils → Format Text** node accepts multiple connections into
301
+ its `value` input. Use positional placeholders such as `{0}`, `{1}`, and
302
+ `{2}` in the template. `{value}` remains available as the first input value
303
+ for simple one-input templates. Connections into multi-input attribute ports
304
+ show index labels on the wire so the template order is visible on the graph.
305
+ - Node headers show live execution state: amber while running, green when
306
+ finished, red on failure, gray when a disabled node is skipped, and muted
307
+ red when a node is blocked by an upstream failure. Cancelled nodes use a
308
+ purple-gray state.
309
+ Execution coordination runs outside the GUI thread so the final running
310
+ node and parallel running nodes remain visible while work is in progress.
311
+ - A failed node blocks only its downstream dependency branch. Independent
312
+ parallel branches continue running and report their own final states.
313
+ - Closed panels can be restored from **View → Nodes/Properties/Execution**.
314
+ Use **View → Show All Panels** to restore everything at once.
315
+
316
+ Graph files use readable JSON with the `.taskgraph` extension.
317
+
318
+ ## Architecture
319
+
320
+ - `core/model.py`: node contract—including inherited dependency port
321
+ specifications—and serializable graph model
322
+ - `core/registry.py`: decorator-based built-in and external node discovery
323
+ - `core/executor.py`: validation and dependency-ordered execution
324
+ - `ui/`: graphics editor, node items, property editor, and main window
325
+ - `nodes/`: built-in examples and the extension point for new processes
@@ -1,4 +1,10 @@
1
- # TaskGraph
1
+ <p align="left">
2
+ <a href="https://buymeacoffee.com/cgarjun">
3
+ <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="50" alt="Buy Me A Coffee">
4
+ </a>
5
+ </p>
6
+
7
+ # Koode TaskGraph
2
8
 
3
9
  TaskGraph is a small, extensible process graph editor built from scratch with
4
10
  Python, QtPy, and PySide6.
@@ -17,6 +23,48 @@ koode-taskgraph
17
23
  For local development from this repository, use `python -m pip install -e .`.
18
24
  See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
19
25
 
26
+ ## Remove local user settings
27
+
28
+ TaskGraph stores user preferences with Qt `QSettings` under organization
29
+ `TaskGraph` and application `TaskGraph`. Settings include saved custom node
30
+ locations and the execution worker count. GUI plugin locations are session-only
31
+ and are not saved, but older versions may have saved GUI plugin locations.
32
+
33
+ Default locations:
34
+
35
+ - **macOS:** `~/Library/Preferences/com.taskgraph.TaskGraph.plist`
36
+ - **Linux:** `~/.config/TaskGraph/TaskGraph.conf`
37
+ - If `XDG_CONFIG_HOME` is set:
38
+ `$XDG_CONFIG_HOME/TaskGraph/TaskGraph.conf`
39
+ - **Windows:** Registry key
40
+ `HKEY_CURRENT_USER\Software\TaskGraph\TaskGraph`
41
+
42
+ Quit TaskGraph before removing settings.
43
+
44
+ macOS:
45
+
46
+ ```bash
47
+ defaults delete com.taskgraph.TaskGraph
48
+ ```
49
+
50
+ Linux:
51
+
52
+ ```bash
53
+ rm ~/.config/TaskGraph/TaskGraph.conf
54
+ ```
55
+
56
+ Windows Command Prompt:
57
+
58
+ ```bat
59
+ reg delete HKCU\Software\TaskGraph\TaskGraph /f
60
+ ```
61
+
62
+ Windows PowerShell:
63
+
64
+ ```powershell
65
+ Remove-Item -Path "HKCU:\Software\TaskGraph\TaskGraph" -Recurse -Force
66
+ ```
67
+
20
68
  ## Headless CLI
21
69
 
22
70
  Execute a saved graph without starting Qt or opening a window:
@@ -34,7 +82,7 @@ koode-taskgraph-cli \
34
82
  --node-path /path/to/custom_nodes
35
83
  ```
36
84
 
37
- `--node-path` may be repeated. `TASKGRAPH_NODE_PATH` is also supported with
85
+ `--node-path` may be repeated. `TASKGRAPH_CUSTOM_NODES` is also supported with
38
86
  the normal platform path separator. Use `--json` for structured results,
39
87
  `--quiet` to hide progress messages, and `Ctrl+C` to cancel execution.
40
88
 
@@ -80,75 +128,119 @@ also live anywhere on disk:
80
128
  2. Select **Nodes → Add Custom Node Location…** and choose that directory.
81
129
  3. Restarting TaskGraph reloads the saved location automatically.
82
130
 
83
- Alternatively, set `TASKGRAPH_NODE_PATH` before launching. Separate multiple
131
+ Alternatively, set `TASKGRAPH_CUSTOM_NODES` before launching. Separate multiple
84
132
  directories with the platform path separator (`:` on macOS/Linux and `;` on
85
133
  Windows):
86
134
 
87
135
  ```bash
88
- TASKGRAPH_NODE_PATH="/path/to/company_nodes:/path/to/my_nodes" koode-taskgraph
136
+ TASKGRAPH_CUSTOM_NODES="/path/to/company_nodes:/path/to/my_nodes" koode-taskgraph
89
137
  ```
90
138
 
91
139
  Files beginning with `_` are ignored. Importing a custom node module executes
92
140
  its Python code, so only add trusted directories. The editor, property panel,
93
141
  serialization, and executor require no other changes.
94
142
 
143
+ This repository includes a practical custom node example in
144
+ `examples/custom_nodes/text_cleanup.py`. Load `examples/custom_nodes` from
145
+ **Nodes → Add Custom Node Location…** or with:
146
+
147
+ ```bash
148
+ TASKGRAPH_CUSTOM_NODES="/path/to/taskgraph/examples/custom_nodes" koode-taskgraph
149
+ ```
150
+
151
+ The example adds **Examples → Clean Text**, which trims text, optionally
152
+ collapses whitespace, and applies a selectable case conversion.
153
+
95
154
  ## Add a GUI plugin
96
155
 
97
- GUI plugins can add menus, actions, docks, and graph-building commands without
156
+ GUI plugins can add menus, commands, docks, and graph-building tools without
98
157
  editing TaskGraph source. Put one or more `.py` files in a plugin directory and
99
- define `register_taskgraph_plugin(api)`:
158
+ define `class Plugin(TaskGraphGuiPlugin)`.
159
+
160
+ The plugin API is split into namespaces. Inside `TaskGraphGuiPlugin` subclasses
161
+ these are available as:
162
+
163
+ - `self.commands` registers reusable commands.
164
+ - `self.ui` exposes GUI features such as menus, docks, and status messages.
165
+ - `self.graph` creates nodes, connects ports, reads the graph model, and adds
166
+ backdrops.
100
167
 
101
168
  ```python
102
- def register_taskgraph_plugin(api):
103
- def build_template_graph():
104
- text = api.create_node(
169
+ from taskgraph.ui.plugins import TaskGraphGuiPlugin
170
+
171
+
172
+ class Plugin(TaskGraphGuiPlugin):
173
+ plugin_id = "example.graph_daily_report"
174
+ name = "Daily Report Graph Builder"
175
+ version = "1.0.0"
176
+
177
+ def setup(self):
178
+ self.commands.register(
179
+ f"{self.plugin_id}.build_daily_report",
180
+ label="Graph API: Build Daily Report Graph",
181
+ callback=self.build_daily_report,
182
+ )
183
+ self.ui.menus.add_command(
184
+ "Examples",
185
+ f"{self.plugin_id}.build_daily_report",
186
+ )
187
+
188
+ def build_daily_report(self):
189
+ text = self.graph.create_node(
105
190
  "input.text",
106
- name="Message",
107
- values={"text": "hello world"},
191
+ name="Report Title",
192
+ values={"text": "Daily Production Report"},
108
193
  position=(0, 0),
109
194
  )
110
- formatter = api.create_node(
111
- "text.format",
112
- name="Format Message",
113
- values={"template": "Output: {value}"},
114
- position=(280, 0),
115
- )
116
- printer = api.create_node(
195
+ printer = self.graph.create_node(
117
196
  "output.print",
118
- name="Print Result",
119
- position=(560, 0),
197
+ name="Print Report",
198
+ position=(320, 0),
120
199
  )
121
- api.connect_dependency(text, formatter)
122
- api.connect_attribute(text, "text", formatter, "value")
123
- api.connect_dependency(formatter, printer)
124
- api.connect_attribute(formatter, "text", printer, "value")
125
- api.add_backdrop(
126
- title="Template Notes",
200
+ self.graph.connect_dependency(text, printer)
201
+ self.graph.connect_attribute(text, "text", printer, "value")
202
+ self.graph.add_backdrop(
203
+ title="Daily Report Template",
127
204
  note="This graph was created by a GUI plugin.",
128
205
  position=(-40, -140),
129
- size=(720, 180),
206
+ size=(650, 170),
130
207
  )
131
-
132
- api.add_menu_action("Tools", "Build Template Graph", build_template_graph)
133
208
  ```
134
209
 
135
- Load GUI plugins from **Plugins → Add GUI Plugin Location…**. Restarting
136
- TaskGraph reloads saved plugin locations automatically. Alternatively, set
137
- `TASKGRAPH_PLUGIN_PATH` before launching, using the same platform path
138
- separator rules as `TASKGRAPH_NODE_PATH`.
210
+ Older flat helpers such as `api.create_node(...)` and
211
+ `api.add_menu_action(...)`, plus the old `register_taskgraph_plugin(api)`
212
+ function entrypoint, are still supported for compatibility. New plugins should
213
+ use the OOP `Plugin` class and namespaced API.
214
+
215
+ Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
216
+ session. GUI plugin locations are not saved or automatically reloaded on the
217
+ next launch. To load GUI plugins at startup, set `TASKGRAPH_GUI_PLUGINS` before
218
+ launching, using the same platform path separator rules as
219
+ `TASKGRAPH_CUSTOM_NODES`.
220
+
221
+ This repository includes separate practical example plugins in
222
+ `examples/gui_plugins`:
223
+
224
+ - `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
225
+ panel and writing a status message.
226
+ - `command_validate_graph.py` demonstrates the command API by registering a
227
+ reusable graph validation command and exposing it in the menu.
228
+ - `graph_daily_report.py` demonstrates the graph API by building a reusable
229
+ daily-report graph with nodes, dependency links, attribute links, and a
230
+ backdrop.
139
231
 
140
- This repository includes minimal example plugins in `examples/gui_plugins`.
141
- Load that directory, then run **Examples → Create Hello World Print Graph** or
142
- **Examples → Create Bingooo Print Graph**.
232
+ Load that directory, then use the **Examples** menu to run each example.
143
233
 
144
234
  GUI plugins are intentionally separate from custom node locations. The
145
- headless CLI loads `TASKGRAPH_NODE_PATH` only, so UI plugin code can safely
235
+ headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
146
236
  import Qt widgets without breaking `koode-taskgraph-cli`.
147
237
 
148
238
  ## Controls
149
239
 
150
240
  - Standard commands are organized under the **File**, **Edit**, **Nodes**,
151
241
  **Graph**, **Plugins**, and **View** menus.
242
+ - Use the search field at the top of the **Nodes** panel to filter nodes by
243
+ title, type id, or category.
152
244
  - Drag a node from **Nodes** to the canvas, or double-click it.
153
245
  - Every node has fixed gold **dependency** input/output ports. These control
154
246
  process order but do not transfer values. Gold dependency connections show
@@ -194,6 +286,11 @@ import Qt widgets without breaking `koode-taskgraph-cli`.
194
286
  stdout, stderr, and return code outputs. It supports an optional working
195
287
  directory, shell mode, timeout, and failure on non-zero exit. Shell mode
196
288
  executes exactly what the graph author enters, so only run trusted graphs.
289
+ - The built-in **Utils → Format Text** node accepts multiple connections into
290
+ its `value` input. Use positional placeholders such as `{0}`, `{1}`, and
291
+ `{2}` in the template. `{value}` remains available as the first input value
292
+ for simple one-input templates. Connections into multi-input attribute ports
293
+ show index labels on the wire so the template order is visible on the graph.
197
294
  - Node headers show live execution state: amber while running, green when
198
295
  finished, red on failure, gray when a disabled node is skipped, and muted
199
296
  red when a node is blocked by an upstream failure. Cancelled nodes use a