Overview

The pages in this tree describe the surface BioImageFlow exposes for hosts — graphical editors, web servers, plugin frameworks. A host typically:

• holds a long-lived session that mirrors the workflow as a wire-format dict;

• mutates that dict in response to user edits (drag a node, change a field, toggle a checkbox);

• materializes a Workflow on demand to validate, plan, or compute;

• renders validation errors and cache state inline, without crashing on partial graphs.

Audience

This tree is not for workflow scripts or tool authors. The Workflow Authors tree (Concepts, Tutorials) covers how to build a DAG and write a tool. Pages here assume you are writing the host that carries those workflows.

Reading order

The pages are designed to be read in order:

1. Wire Format — the JSON shape every other page relies on.

2. Loading: from_dict — the load-time API and its validation flag matrix.

3. WorkflowSession — the editing model: when to materialize, when to mutate in place.

4. ToolRegistry — installing, registering, and indexing tool packages.

5. Live Validation — keystroke-rate validation helpers.

6. Planning and Cache State — rendering “cached / needs rebuild / unexecuted / skipped” without executing.

7. Disabled Nodes — the disable/enable flag and partial execution.

8. Progress and Cancellation — wiring progress callbacks and a Cancel button.

9. Tool Schemas — schemas for inline form widgets.

Mental model

A useful sketch for what a host typically does:

┌────────────────┐    add/remove/edit     ┌───────────────────┐
│  Editor state  │ ─────────────────────> │ WorkflowSession   │
│  (dict-shaped) │                        │  (dict + caches)  │
└────────────────┘                        └─────────┬─────────┘
                                                    │
                                    to_workflow() / validate() / plan()
                                                    │
                                                    ▼
                                     ┌──────────────────────────┐
                                     │  Workflow                │
                                     │  validate() → errors     │
                                     │  plan() → NodePlan map   │
                                     │  compute() (or steps)    │
                                     └──────────────────────────┘

Pages further down the list refine each box.