koode-taskgraph 0.4.0__tar.gz → 0.5.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 → koode_taskgraph-0.5.0}/PKG-INFO +101 -87
  2. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/README.md +100 -86
  3. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/PKG-INFO +101 -87
  4. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/SOURCES.txt +3 -0
  5. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/pyproject.toml +1 -1
  6. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/cli.py +1 -1
  7. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/model.py +172 -4
  8. koode_taskgraph-0.5.0/taskgraph/nodes/builtin.py +96 -0
  9. koode_taskgraph-0.5.0/taskgraph/nodes/systems.py +265 -0
  10. koode_taskgraph-0.5.0/taskgraph/nodes/utils.py +24 -0
  11. koode_taskgraph-0.5.0/taskgraph/ui/code_editor.py +69 -0
  12. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/items.py +3 -2
  13. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/main_window.py +1 -0
  14. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/plugins.py +34 -92
  15. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/properties.py +15 -63
  16. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/theme.py +4 -0
  17. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/tests/test_core.py +73 -4
  18. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/tests/test_gui_plugins.py +124 -78
  19. koode_taskgraph-0.4.0/taskgraph/nodes/builtin.py +0 -156
  20. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/LICENSE +0 -0
  21. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/dependency_links.txt +0 -0
  22. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/entry_points.txt +0 -0
  23. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/requires.txt +0 -0
  24. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/koode_taskgraph.egg-info/top_level.txt +0 -0
  25. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/setup.cfg +0 -0
  26. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/__init__.py +0 -0
  27. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/__main__.py +0 -0
  28. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/app.py +0 -0
  29. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/__init__.py +0 -0
  30. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/executor.py +0 -0
  31. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/registry.py +0 -0
  32. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/core/serialization.py +0 -0
  33. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/nodes/__init__.py +0 -0
  34. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/__init__.py +0 -0
  35. {koode_taskgraph-0.4.0 → koode_taskgraph-0.5.0}/taskgraph/ui/scene.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: koode-taskgraph
3
- Version: 0.4.0
3
+ Version: 0.5.0
4
4
  Summary: An extensible process node graph built with QtPy and PySide6
5
5
  Requires-Python: >=3.10
6
6
  Description-Content-Type: text/markdown
@@ -34,6 +34,91 @@ koode-taskgraph
34
34
  For local development from this repository, use `python -m pip install -e .`.
35
35
  See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
36
36
 
37
+ ## Application Features
38
+
39
+ - Standard commands are organized under the **File**, **Edit**, **Nodes**,
40
+ **Graph**, **Plugins**, and **View** menus.
41
+ - Use the search field at the top of the **Nodes** panel to filter nodes by
42
+ title, type id, or category.
43
+ - Drag a node from **Nodes** to the canvas, or double-click it.
44
+ - Every node has fixed gold **dependency** input/output ports. These control
45
+ process order but do not transfer values. Gold dependency connections show
46
+ an arrowhead pointing from the upstream node toward the downstream node.
47
+ - Declared node inputs and outputs are attribute ports. Attribute connections
48
+ transfer values, but execution order comes only from dependency connections.
49
+ An attribute connection therefore needs a dependency path from its source
50
+ node to its target node.
51
+ - Dependency ports connect only to dependency ports; compatible attribute
52
+ ports connect only to attribute ports.
53
+ - Select one or more nodes on the canvas and press **D** to toggle them
54
+ disabled. Disabled nodes stay in the dependency chain but their process
55
+ functions are skipped. The same command is available from **Edit**.
56
+ - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
57
+ shortcuts. Properties, disabled state, relative positions, and connections
58
+ entirely inside the copied selection are preserved.
59
+ - Select a node to edit generated property controls.
60
+ - Use **Node Name** at the top of the Properties panel to give each node
61
+ instance a descriptive name. Custom names appear in node headers and
62
+ execution messages and are preserved when saving or copying nodes.
63
+ - Select nodes or connections and press **Backspace** or **Delete** to remove
64
+ them. **Edit → Delete Selected** works on every platform too.
65
+ - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
66
+ - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
67
+ from left to right and parallel nodes vertically, then frames the result.
68
+ - **Graph → Add Backdrop** creates a movable notes region behind the graph.
69
+ Select it to edit its title, notes, color, width, and height in Properties.
70
+ Drag the grip in its bottom-right corner to resize it interactively.
71
+ Backdrops are stored in `.taskgraph` files.
72
+ - **Ctrl+R** executes nodes in dependency order.
73
+ - Independent dependency branches execute concurrently. Choose between one
74
+ worker or any even worker count from 2 through 32 under
75
+ **Graph → Worker Count**; the setting is remembered.
76
+ - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
77
+ Pending nodes are cancelled immediately. Running nodes receive a cooperative
78
+ cancellation signal, and built-in command nodes terminate their subprocess
79
+ groups promptly.
80
+ - Clear displayed execution messages with **Graph → Clear Execution Log** or
81
+ from the Execution panel's right-click menu.
82
+ - Node headers show live execution state: amber while running, green when
83
+ finished, red on failure, gray when a disabled node is skipped, and muted
84
+ red when a node is blocked by an upstream failure. Cancelled nodes use a
85
+ purple-gray state.
86
+ Execution coordination runs outside the GUI thread so the final running
87
+ node and parallel running nodes remain visible while work is in progress.
88
+ - A failed node blocks only its downstream dependency branch. Independent
89
+ parallel branches continue running and report their own final states.
90
+ - Closed panels can be restored from **View → Nodes/Properties/Execution**.
91
+ Use **View → Show All Panels** to restore everything at once.
92
+ - Graph files use readable JSON with the `.taskgraph` extension.
93
+
94
+ ## Built-in Nodes
95
+
96
+ - Built-in nodes are organized as **System → Run Command/Python Script/Print**,
97
+ **Utils → Format Text**, and **Inputs → String/Number/Path/List/Dict**.
98
+ - **Inputs → String** outputs a user-provided string value.
99
+ - **Inputs → Number** outputs a user-provided numeric value.
100
+ - **Inputs → Path** outputs a user-selected file or directory path.
101
+ - **Inputs → List** outputs a JSON-authored Python list.
102
+ - **Inputs → Dict** outputs a JSON-authored Python dictionary.
103
+ - **System → Print** prints an incoming value and supports an optional prefix.
104
+ - **System → Run Command** executes a command and exposes stdout, stderr, and
105
+ return code outputs. It supports an optional working directory, shell mode,
106
+ timeout, and failure on non-zero exit. Shell mode executes exactly what the
107
+ graph author enters, so only run trusted graphs.
108
+ - **System → Python Script** runs user-provided Python code in a subprocess.
109
+ The script must define `process(inputs)` and return a dictionary. Connected
110
+ values arrive through the multi-input `value` port as `inputs["value"]` and
111
+ `inputs["values"]`. The node exposes `result`, captured `stdout`, and
112
+ captured `stderr`. The code editor uses a monospace font, keeps line wrapping
113
+ off, inserts spaces with **Tab**, and unindents with **Shift+Tab**. Python
114
+ Script runs arbitrary code with the same user permissions as TaskGraph, so
115
+ only run trusted graphs.
116
+ - **Utils → Format Text** accepts multiple connections into its `value` input.
117
+ Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
118
+ `{value}` remains available as the first input value for simple one-input
119
+ templates. Connections into multi-input attribute ports show index labels on
120
+ the wire so the template order is visible on the graph.
121
+
37
122
  ## Remove local user settings
38
123
 
39
124
  TaskGraph stores user preferences with Qt `QSettings` under organization
@@ -109,7 +194,7 @@ node to edit its properties, then click **Run graph**.
109
194
  Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
110
195
 
111
196
  ```python
112
- from taskgraph.core.model import NodeProperty, PortSpec, ProcessNode
197
+ from taskgraph.core.model import PortSpec, ProcessNode, TextProperty
113
198
  from taskgraph.core.registry import register_node
114
199
 
115
200
  @register_node
@@ -120,17 +205,17 @@ class PrefixText(ProcessNode):
120
205
  inputs = (PortSpec("value", "any"),)
121
206
  outputs = (PortSpec("text", "text"),)
122
207
  properties = (
123
- NodeProperty("prefix", "Prefix", "text", "Result: "),
208
+ TextProperty("prefix", "Prefix", "Result: "),
124
209
  )
125
210
 
126
211
  def process(self, inputs):
127
212
  return {"text": f"{self.prefix}{inputs.get('value', '')}"}
128
213
  ```
129
214
 
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`.
215
+ Property specs map to generated controls in the Properties panel:
216
+ `TextProperty`, `MultilineProperty`, `BoolProperty`, `IntProperty`,
217
+ `FloatProperty`, `ChoiceProperty`, and `PathProperty`. Use typed specs for new
218
+ nodes so property-specific behavior stays with the property declaration.
134
219
 
135
220
  Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
136
221
  also live anywhere on disk:
@@ -192,15 +277,15 @@ class Plugin(TaskGraphGuiPlugin):
192
277
  callback=self.build_daily_report,
193
278
  )
194
279
  self.ui.menus.add_command(
195
- "Examples",
280
+ "Examples/Graph Builders",
196
281
  f"{self.plugin_id}.build_daily_report",
197
282
  )
198
283
 
199
284
  def build_daily_report(self):
200
285
  text = self.graph.create_node(
201
- "input.text",
286
+ "input.string",
202
287
  name="Report Title",
203
- values={"text": "Daily Production Report"},
288
+ values={"string": "Daily Production Report"},
204
289
  position=(0, 0),
205
290
  )
206
291
  printer = self.graph.create_node(
@@ -209,7 +294,7 @@ class Plugin(TaskGraphGuiPlugin):
209
294
  position=(320, 0),
210
295
  )
211
296
  self.graph.connect_dependency(text, printer)
212
- self.graph.connect_attribute(text, "text", printer, "value")
297
+ self.graph.connect_attribute(text, "string", printer, "value")
213
298
  self.graph.add_backdrop(
214
299
  title="Daily Report Template",
215
300
  note="This graph was created by a GUI plugin.",
@@ -218,10 +303,7 @@ class Plugin(TaskGraphGuiPlugin):
218
303
  )
219
304
  ```
220
305
 
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.
306
+ GUI plugins must define an OOP `Plugin` class and use the namespaced API.
225
307
 
226
308
  Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
227
309
  session. GUI plugin locations are not saved or automatically reloaded on the
@@ -233,12 +315,13 @@ This repository includes separate practical example plugins in
233
315
  `examples/gui_plugins`:
234
316
 
235
317
  - `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
236
- panel and writing a status message.
318
+ panel and writing a status message from **Examples → UI Panels**.
237
319
  - `command_validate_graph.py` demonstrates the command API by registering a
238
- reusable graph validation command and exposing it in the menu.
320
+ reusable graph validation command and exposing it in
321
+ **Examples → Commands**.
239
322
  - `graph_daily_report.py` demonstrates the graph API by building a reusable
240
323
  daily-report graph with nodes, dependency links, attribute links, and a
241
- backdrop.
324
+ backdrop from **Examples → Graph Builders**.
242
325
 
243
326
  Load that directory, then use the **Examples** menu to run each example.
244
327
 
@@ -246,75 +329,6 @@ GUI plugins are intentionally separate from custom node locations. The
246
329
  headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
247
330
  import Qt widgets without breaking `koode-taskgraph-cli`.
248
331
 
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
332
  ## Architecture
319
333
 
320
334
  - `core/model.py`: node contract—including inherited dependency port
@@ -23,6 +23,91 @@ koode-taskgraph
23
23
  For local development from this repository, use `python -m pip install -e .`.
24
24
  See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.
25
25
 
26
+ ## Application Features
27
+
28
+ - Standard commands are organized under the **File**, **Edit**, **Nodes**,
29
+ **Graph**, **Plugins**, and **View** menus.
30
+ - Use the search field at the top of the **Nodes** panel to filter nodes by
31
+ title, type id, or category.
32
+ - Drag a node from **Nodes** to the canvas, or double-click it.
33
+ - Every node has fixed gold **dependency** input/output ports. These control
34
+ process order but do not transfer values. Gold dependency connections show
35
+ an arrowhead pointing from the upstream node toward the downstream node.
36
+ - Declared node inputs and outputs are attribute ports. Attribute connections
37
+ transfer values, but execution order comes only from dependency connections.
38
+ An attribute connection therefore needs a dependency path from its source
39
+ node to its target node.
40
+ - Dependency ports connect only to dependency ports; compatible attribute
41
+ ports connect only to attribute ports.
42
+ - Select one or more nodes on the canvas and press **D** to toggle them
43
+ disabled. Disabled nodes stay in the dependency chain but their process
44
+ functions are skipped. The same command is available from **Edit**.
45
+ - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
46
+ shortcuts. Properties, disabled state, relative positions, and connections
47
+ entirely inside the copied selection are preserved.
48
+ - Select a node to edit generated property controls.
49
+ - Use **Node Name** at the top of the Properties panel to give each node
50
+ instance a descriptive name. Custom names appear in node headers and
51
+ execution messages and are preserved when saving or copying nodes.
52
+ - Select nodes or connections and press **Backspace** or **Delete** to remove
53
+ them. **Edit → Delete Selected** works on every platform too.
54
+ - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
55
+ - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
56
+ from left to right and parallel nodes vertically, then frames the result.
57
+ - **Graph → Add Backdrop** creates a movable notes region behind the graph.
58
+ Select it to edit its title, notes, color, width, and height in Properties.
59
+ Drag the grip in its bottom-right corner to resize it interactively.
60
+ Backdrops are stored in `.taskgraph` files.
61
+ - **Ctrl+R** executes nodes in dependency order.
62
+ - Independent dependency branches execute concurrently. Choose between one
63
+ worker or any even worker count from 2 through 32 under
64
+ **Graph → Worker Count**; the setting is remembered.
65
+ - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
66
+ Pending nodes are cancelled immediately. Running nodes receive a cooperative
67
+ cancellation signal, and built-in command nodes terminate their subprocess
68
+ groups promptly.
69
+ - Clear displayed execution messages with **Graph → Clear Execution Log** or
70
+ from the Execution panel's right-click menu.
71
+ - Node headers show live execution state: amber while running, green when
72
+ finished, red on failure, gray when a disabled node is skipped, and muted
73
+ red when a node is blocked by an upstream failure. Cancelled nodes use a
74
+ purple-gray state.
75
+ Execution coordination runs outside the GUI thread so the final running
76
+ node and parallel running nodes remain visible while work is in progress.
77
+ - A failed node blocks only its downstream dependency branch. Independent
78
+ parallel branches continue running and report their own final states.
79
+ - Closed panels can be restored from **View → Nodes/Properties/Execution**.
80
+ Use **View → Show All Panels** to restore everything at once.
81
+ - Graph files use readable JSON with the `.taskgraph` extension.
82
+
83
+ ## Built-in Nodes
84
+
85
+ - Built-in nodes are organized as **System → Run Command/Python Script/Print**,
86
+ **Utils → Format Text**, and **Inputs → String/Number/Path/List/Dict**.
87
+ - **Inputs → String** outputs a user-provided string value.
88
+ - **Inputs → Number** outputs a user-provided numeric value.
89
+ - **Inputs → Path** outputs a user-selected file or directory path.
90
+ - **Inputs → List** outputs a JSON-authored Python list.
91
+ - **Inputs → Dict** outputs a JSON-authored Python dictionary.
92
+ - **System → Print** prints an incoming value and supports an optional prefix.
93
+ - **System → Run Command** executes a command and exposes stdout, stderr, and
94
+ return code outputs. It supports an optional working directory, shell mode,
95
+ timeout, and failure on non-zero exit. Shell mode executes exactly what the
96
+ graph author enters, so only run trusted graphs.
97
+ - **System → Python Script** runs user-provided Python code in a subprocess.
98
+ The script must define `process(inputs)` and return a dictionary. Connected
99
+ values arrive through the multi-input `value` port as `inputs["value"]` and
100
+ `inputs["values"]`. The node exposes `result`, captured `stdout`, and
101
+ captured `stderr`. The code editor uses a monospace font, keeps line wrapping
102
+ off, inserts spaces with **Tab**, and unindents with **Shift+Tab**. Python
103
+ Script runs arbitrary code with the same user permissions as TaskGraph, so
104
+ only run trusted graphs.
105
+ - **Utils → Format Text** accepts multiple connections into its `value` input.
106
+ Use positional placeholders such as `{0}`, `{1}`, and `{2}` in the template.
107
+ `{value}` remains available as the first input value for simple one-input
108
+ templates. Connections into multi-input attribute ports show index labels on
109
+ the wire so the template order is visible on the graph.
110
+
26
111
  ## Remove local user settings
27
112
 
28
113
  TaskGraph stores user preferences with Qt `QSettings` under organization
@@ -98,7 +183,7 @@ node to edit its properties, then click **Run graph**.
98
183
  Create a module in `taskgraph/nodes/` and define a `ProcessNode` subclass:
99
184
 
100
185
  ```python
101
- from taskgraph.core.model import NodeProperty, PortSpec, ProcessNode
186
+ from taskgraph.core.model import PortSpec, ProcessNode, TextProperty
102
187
  from taskgraph.core.registry import register_node
103
188
 
104
189
  @register_node
@@ -109,17 +194,17 @@ class PrefixText(ProcessNode):
109
194
  inputs = (PortSpec("value", "any"),)
110
195
  outputs = (PortSpec("text", "text"),)
111
196
  properties = (
112
- NodeProperty("prefix", "Prefix", "text", "Result: "),
197
+ TextProperty("prefix", "Prefix", "Result: "),
113
198
  )
114
199
 
115
200
  def process(self, inputs):
116
201
  return {"text": f"{self.prefix}{inputs.get('value', '')}"}
117
202
  ```
118
203
 
119
- Property kinds map to generated controls in the Properties panel: `"text"` for
120
- a line edit, `"file"` for a file path field with a Browse button, `"bool"` for
121
- a checkbox, `"int"`/`"float"` for numeric fields, and `"choice"` for a
122
- dropdown using `choices`.
204
+ Property specs map to generated controls in the Properties panel:
205
+ `TextProperty`, `MultilineProperty`, `BoolProperty`, `IntProperty`,
206
+ `FloatProperty`, `ChoiceProperty`, and `PathProperty`. Use typed specs for new
207
+ nodes so property-specific behavior stays with the property declaration.
123
208
 
124
209
  Modules in `taskgraph/nodes/` are discovered automatically. Custom modules can
125
210
  also live anywhere on disk:
@@ -181,15 +266,15 @@ class Plugin(TaskGraphGuiPlugin):
181
266
  callback=self.build_daily_report,
182
267
  )
183
268
  self.ui.menus.add_command(
184
- "Examples",
269
+ "Examples/Graph Builders",
185
270
  f"{self.plugin_id}.build_daily_report",
186
271
  )
187
272
 
188
273
  def build_daily_report(self):
189
274
  text = self.graph.create_node(
190
- "input.text",
275
+ "input.string",
191
276
  name="Report Title",
192
- values={"text": "Daily Production Report"},
277
+ values={"string": "Daily Production Report"},
193
278
  position=(0, 0),
194
279
  )
195
280
  printer = self.graph.create_node(
@@ -198,7 +283,7 @@ class Plugin(TaskGraphGuiPlugin):
198
283
  position=(320, 0),
199
284
  )
200
285
  self.graph.connect_dependency(text, printer)
201
- self.graph.connect_attribute(text, "text", printer, "value")
286
+ self.graph.connect_attribute(text, "string", printer, "value")
202
287
  self.graph.add_backdrop(
203
288
  title="Daily Report Template",
204
289
  note="This graph was created by a GUI plugin.",
@@ -207,10 +292,7 @@ class Plugin(TaskGraphGuiPlugin):
207
292
  )
208
293
  ```
209
294
 
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.
295
+ GUI plugins must define an OOP `Plugin` class and use the namespaced API.
214
296
 
215
297
  Load GUI plugins from **Plugins → Add GUI Plugin Location…** for the current
216
298
  session. GUI plugin locations are not saved or automatically reloaded on the
@@ -222,12 +304,13 @@ This repository includes separate practical example plugins in
222
304
  `examples/gui_plugins`:
223
305
 
224
306
  - `ui_project_notes.py` demonstrates the UI API by opening a Project Notes dock
225
- panel and writing a status message.
307
+ panel and writing a status message from **Examples → UI Panels**.
226
308
  - `command_validate_graph.py` demonstrates the command API by registering a
227
- reusable graph validation command and exposing it in the menu.
309
+ reusable graph validation command and exposing it in
310
+ **Examples → Commands**.
228
311
  - `graph_daily_report.py` demonstrates the graph API by building a reusable
229
312
  daily-report graph with nodes, dependency links, attribute links, and a
230
- backdrop.
313
+ backdrop from **Examples → Graph Builders**.
231
314
 
232
315
  Load that directory, then use the **Examples** menu to run each example.
233
316
 
@@ -235,75 +318,6 @@ GUI plugins are intentionally separate from custom node locations. The
235
318
  headless CLI loads `TASKGRAPH_CUSTOM_NODES` only, so UI plugin code can safely
236
319
  import Qt widgets without breaking `koode-taskgraph-cli`.
237
320
 
238
- ## Controls
239
-
240
- - Standard commands are organized under the **File**, **Edit**, **Nodes**,
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.
244
- - Drag a node from **Nodes** to the canvas, or double-click it.
245
- - Every node has fixed gold **dependency** input/output ports. These control
246
- process order but do not transfer values. Gold dependency connections show
247
- an arrowhead pointing from the upstream node toward the downstream node.
248
- - Declared node inputs and outputs are attribute ports. Attribute connections
249
- transfer values, but execution order comes only from dependency connections.
250
- An attribute connection therefore needs a dependency path from its source
251
- node to its target node.
252
- - Dependency ports connect only to dependency ports; compatible attribute
253
- ports connect only to attribute ports.
254
- - Select one or more nodes on the canvas and press **D** to toggle them
255
- disabled. Disabled nodes stay in the dependency chain but their process
256
- functions are skipped. The same command is available from **Edit**.
257
- - **Copy Nodes** and **Paste Nodes** under **Edit** use the standard platform
258
- shortcuts. Properties, disabled state, relative positions, and connections
259
- entirely inside the copied selection are preserved.
260
- - Select a node to edit generated property controls.
261
- - Use **Node Name** at the top of the Properties panel to give each node
262
- instance a descriptive name. Custom names appear in node headers and
263
- execution messages and are preserved when saving or copying nodes.
264
- - Select nodes or connections and press **Backspace** or **Delete** to remove
265
- them. **Edit → Delete Selected** works on every platform too.
266
- - Middle-drag pans, the mouse wheel zooms, and **F** frames the graph.
267
- - **Shift+A** or **Graph → Auto Arrange Nodes** lays out dependency layers
268
- from left to right and parallel nodes vertically, then frames the result.
269
- - **Graph → Add Backdrop** creates a movable notes region behind the graph.
270
- Select it to edit its title, notes, color, width, and height in Properties.
271
- Drag the grip in its bottom-right corner to resize it interactively.
272
- Backdrops are stored in `.taskgraph` files.
273
- - **Ctrl+R** executes nodes in dependency order.
274
- - Independent dependency branches execute concurrently. Choose between one
275
- worker or any even worker count from 2 through 32 under
276
- **Graph → Worker Count**; the setting is remembered.
277
- - Use **Graph → Cancel Execution** or **Esc** to cancel the complete run.
278
- Pending nodes are cancelled immediately. Running nodes receive a cooperative
279
- cancellation signal, and built-in command nodes terminate their subprocess
280
- groups promptly.
281
- - Clear displayed execution messages with **Graph → Clear Execution Log** or
282
- from the Execution panel's right-click menu.
283
- - Built-in nodes are organized as **System → Run Command/Print**,
284
- **Utils → Format Text**, and **Inputs → Text/Number**.
285
- - The built-in **System → Run Command** node executes a command and exposes
286
- stdout, stderr, and return code outputs. It supports an optional working
287
- directory, shell mode, timeout, and failure on non-zero exit. Shell mode
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.
294
- - Node headers show live execution state: amber while running, green when
295
- finished, red on failure, gray when a disabled node is skipped, and muted
296
- red when a node is blocked by an upstream failure. Cancelled nodes use a
297
- purple-gray state.
298
- Execution coordination runs outside the GUI thread so the final running
299
- node and parallel running nodes remain visible while work is in progress.
300
- - A failed node blocks only its downstream dependency branch. Independent
301
- parallel branches continue running and report their own final states.
302
- - Closed panels can be restored from **View → Nodes/Properties/Execution**.
303
- Use **View → Show All Panels** to restore everything at once.
304
-
305
- Graph files use readable JSON with the `.taskgraph` extension.
306
-
307
321
  ## Architecture
308
322
 
309
323
  - `core/model.py`: node contract—including inherited dependency port