humainflow-web/docs/user-guide.md

HumAIn Flow — User Guide

Introduction

HumAIn Flow is a web application for designing, validating and running workflows made of logical blocks, data connections and execution dependencies.

The application supports two main ways of working:

• building the flow by hand in the visual editor
• generating or reshaping the flow through the assistant

Once a flow exists you can save it, review its validation errors, run it from the Tasks tab, and — for flows that involve language models — study how a deliberately introduced bias, or a mitigation meant to counter one, changes what the flow produces.

This guide covers the standard use of the editor, of executions, and of the bias tooling. It describes what you see on screen and what each action does, not how the platform is implemented internally.

Signing in and finding your way around

After signing in you land on the main screen. The top bar contains:

• Editor: where flows are designed
• Tasks: where flow instances are inspected and run
• the user menu, under your username: Change password, and Admin users for accounts that have it

Areas you are not entitled to use are not shown at all.

Notifications — confirmations, warnings and errors — appear briefly at the bottom of the screen, colour-coded, and can be dismissed by clicking them.

The Editor layout

The Editor tab has three main areas:

• a left panel listing the available Blocks and Containers
• the central workflow canvas
• a right panel holding the Assistant and, when relevant, the Errors panel

The Tasks layout

The Tasks tab has:

• the list of executions in the left column
• the detail of the selected execution in the central area

Core concepts

Flow

A flow is the definition of a workflow. It contains:

• blocks
• containers
• data connections
• execution dependencies

A flow also carries a status. The one that matters day to day is whether it is EXECUTABLE — a flow that still has validation errors stays a DRAFT and cannot be run.

Block

A block represents a single step of the workflow. Typical examples:

• LLM blocks, which send a prompt to a language model
• input and output blocks
• human interaction blocks
• conditional blocks, which route the flow down one branch or another
• agent blocks, which let a model call external tools

Container

A container holds a subFlow — a nested flow. Use one to group part of the workflow into a reusable, more readable unit, or to repeat a part of the workflow over a list of items.

A container without a subFlow is considered incomplete.

Data connections

Standard connections link:

• a source output
• to a destination input

They exist to carry values between nodes.

Execution dependencies

Dependencies carry no data. They only impose an order of execution.

The labels visible on the nodes are:

• Depends on: this node must wait for another node
• Prerequisite of: this node unblocks the execution of another

Use a dependency when you want to guarantee the right order between two steps without passing a value as input.

Global inputs

Some values are not produced by a node but supplied when the execution starts — a document to analyse, a topic, a threshold. These are the flow’s global inputs. They are declared once on the flow and can then be referenced by any block that needs them, instead of being wired node by node.

A block that references a global input which the flow does not declare is a validation error (GLOBAL_INPUT_NOT_DECLARED). Global inputs belong to the top-level flow: a subflow inside a container cannot declare its own.

Projects

A project groups related flows under one name. It gives you three things: a folder in the flows list, a set of shared values every flow in it can read, and an order in which those flows run when you run the project as a whole.

Projects are private to whoever created them. A flow can be published and shared; the project structure around it cannot.

Creating a project

In the editor sidebar, the New button above the flows list offers New project alongside Empty flow, Create with AI and From JSON. A project needs a name; the description is optional. Both can be changed later from the same dialog.

Organising flows into projects

Once projects exist, the flows list is grouped by project, with a No project group for everything else. Each group header shows the name, the description and how many flows it holds, and Filters & sorting gains a project filter.

There are two ways to put a flow in a project:

• from the project group’s ⋮ menu, New flow in this project, which creates an empty flow already assigned;
• from a flow’s own ⋮ menu, Move to project, which also offers Remove from project.

When a project group holds more than one flow, arrows appear beside each entry: Run earlier in this project and Run later in this project. That order is what a project run follows.

Shared context

A project’s ⋮ menu offers Shared context… — values that every flow in the project can read at run time. Each entry has a name, a type (TEXT, BOOLEAN, JSON or CSV) and a value, and the dialog shows the placeholder to use it with, which you can copy:

${{project.myVariable}}

They work exactly like the flow’s own global inputs, one level up: define a value once for the project, reference it from any flow inside it.

Names must be unique, must be usable in a placeholder (start with a letter, then letters, digits, _, . or -), and must not start with project., global., context. or vars.. Saving replaces the whole context, so an entry you remove from the dialog is removed for good.

Running a project

The play button on the project group header runs every executable flow in the project. It is available only when at least one of them is executable; the ones that are not are skipped, and the notification tells you how many.

The flows run one at a time, in the project’s order, each starting only after the previous one has succeeded. The application takes you to the Tasks tab with the first execution selected, and executions started this way carry a chip with the project name.

Creating the run does not fill anything in for you. Each execution still needs its own inputs and credentials, exactly as it would on its own. A flow that fails stops the run, and a flow waiting for inputs or a credential blocks it — supply what is missing and run the project again to carry on from where it stopped.

Deleting a project

Delete project deletes the project and every flow in it, finalized flows included — the ordinary protection on a finalized flow does not apply here. The confirmation dialog lists the flows that will go, marks the finalized ones, and asks you to type the project name before the button becomes available.

Past executions are kept: each one holds its own snapshot of the flow it ran, so deleting a project does not erase its history.

Building a flow by hand

1. Open the editor

Go to the Editor tab. The sidebar lists the flows you can open, with a search box and a Filters & sorting disclosure offering visibility toggles, an ordering control and, once you have projects, a project filter. Each row shows whether the flow is public or private, who wrote it and when it was created.

The New button offers four ways to start:

• Empty flow
• Create with AI, which hands the job to the assistant
• From JSON, which imports a flow file
• New project

Each flow’s ⋮ menu offers Clone flow, Export flow — which downloads it as JSON — Move to project and Delete flow.

2. Add blocks or containers

From the left panel:

• look for the block or container type you need
• drag it onto the canvas

If the catalogue is not ready yet, a loader is shown in place of the empty-list message.

3. Move and organise the nodes

You can:

• drag nodes around the canvas
• select and move nodes
• clone a node with the clone icon
• delete a node with the delete icon

Deleting a node also removes:

• the data connections attached to it
• the dependency edges attached to it

4. Connect the nodes

To pass data:

• connect an output to an input

To impose order only:

• connect Prerequisite of on the source node
• to Depends on on the destination node

Dependency connections are drawn differently from data connections: a thinner, dashed line.

5. Rename nodes

For both blocks and containers:

• click the pencil icon next to the name
• edit the name
• confirm with Save

6. Configure the parameters

Clicking a node shows its parameters.

For editable fields:

• use the pencil button on the parameter
• edit the value in the dialog
• save

For long texts:

• a long field is truncated on the node
• open it in full with the eye icon

In read-only subflow views the long fields keep the eye icon, so you can still read them completely.

Placeholders in prompts and parameters

A parameter can reference a value produced elsewhere — a connected input or a global input — through a placeholder. On the node, placeholders are rendered as distinct segments rather than plain text, so you can tell at a glance which part of a prompt is literal and which part will be substituted at run time.

During an execution, the same preview shows the resolved value once it is available; until then the original placeholder stays visible.

Working with containers

Putting a subflow inside a container

A container can receive a subflow in more than one way:

• by importing an existing flow
• by dragging a selection of nodes into it

When a subflow is replaced:

• the structural configuration of the container is rebuilt
• parameters belonging to the previous subflow are not preserved

Importing a flow into the container

If the container type supports it:

• click Import flow
• choose one of the available flows
• confirm

Viewing the subflow

If the container holds a subflow:

• a View Flow button appears
• it opens a read-only preview window

From that view you can:

• explore the subflow
• open long parameters in read-only mode with the eye icon

Validation errors inside a subflow

A subflow is validated together with the flow that contains it. An error produced inside a subflow is reported on the container that holds it — that is the node you can actually see and act on — and the inner node responsible for it is highlighted when you open the subflow view.

Required parameters and local validation

If a node has missing parameters, a warning indicator appears on it.

For blocks, the warning lists the missing required fields.

For containers:

• if the subFlow is missing, only Subflow is listed
• the inner fields of the FlowData, such as Blocks, Connections or Dependencies, are not reported as missing

Technical type fields are never shown as user parameters. These include:

• type
• typeName
• containerType
• configurationType
• configurationClass

Fields that belong to a branch of the configuration you have not selected are hidden as well: a parameter that only applies when another field has a particular value appears when that value is chosen, and does not count as missing before then.

Using the assistant

The assistant lives in the right panel of the editor.

Create and refine modes

The assistant changes behaviour depending on the state of the open flow:

• with no flow open, or with an open flow that is still empty, it works in Create mode
• with a flow that already contains nodes or connections, it works in Refine mode

An empty flow therefore does not block assisted creation.

What you can ask

Typical requests:

• create a flow from scratch
• modify an existing flow
• explain what a flow does
• help fix validation problems

What you get back

When the assistant returns a draft:

• the flow is loaded into the editor
• you can keep editing it by hand
• you can save it like any other flow

The assistant proposes; nothing is persisted until you save.

Saving a flow

While you work in the editor the flow can be modified but not yet saved.

Saving

Use the Save button in the flow toolbar.

Saving:

• updates the flow on the backend
• recomputes validation when needed

Renaming the flow

The flow title uses explicit actions:

• Save
• Cancel

It is not saved automatically when the field loses focus.

The validation errors panel

The right rail has a dedicated icon for flow errors.

When it appears

The icon:

• is always visible in the right rail
• is disabled when there are no errors
• becomes active when the flow has validation errors

How errors are loaded

Errors are requested from the backend:

• after saving, when the flow is not EXECUTABLE
• when opening a flow that is already a DRAFT

What the panel shows

For each error you see:

• a code
• a readable message

Noisy metadata such as entity, field and id is not shown on the card.

Node highlighting

When an error names related nodes, those nodes are highlighted on the canvas. If the error comes from inside a container’s subflow, the container is highlighted while you are looking at the main flow, and the inner node is highlighted once you open the subflow.

Stale validation

If you make a structural change without saving, the errors panel shows a notice:

Validation will be recomputed after save.

Purely graphical moves of the nodes do not count as structural changes.

Published and Finalized

If you own the flow, two controls appear in the toolbar:

• Published
• Finalized

Published

Controls the visibility of the flow. You can publish and unpublish freely.

Finalized

Marks the flow as definitive and no longer modifiable.

Once finalized:

• the content of the flow becomes read-only
• the flow cannot be un-finalized
• the flow cannot be deleted
• publishing and unpublishing remain available

Finalize a flow when you intend to use it as a stable baseline — for instance as the reference version for a bias experiment.

Running a flow

When a flow is valid and executable, Execute becomes available.

What happens when you click Execute

The application:

• switches to the Tasks tab immediately
• creates the execution in the background
• shows a loader until the new execution is ready

This avoids the perceived delay before the tab changes.

Working in the Tasks tab

The Tasks tab shows a list of executions on the left and the detail on the right.

The execution list

Each entry shows:

• the name
• the status
• the date and time
• a Simulated badge when the run was simulated
• the run number, when the execution is part of a group of repeated runs

The detail of an execution

In the detail you can:

• see the graph in read-only mode
• fill in the required inputs
• read outputs and logs
• take the actions that are available for the current state: start, simulate, cancel, resume, re-run

Execution inputs

When an execution step needs manual input you provide it in the dedicated panel.

How inputs are saved

Inputs are not sent automatically when a field loses focus. The behaviour is:

• you edit the value
• the draft stays local
• you press Save to send it

This applies to multi-value fields as well.

Text and list inputs

A text input is edited in place; long values can be opened in a larger editor. A list input lets you add and remove entries, each one edited on its own row.

File inputs

An input that expects a file is filled through a drop zone: drag a file onto it, or click it to pick one.

Once a file is chosen it is uploaded straight away and the zone reports its state:

• while the transfer is running, a progress indicator and the file name
• when it is finished, the file name and a Replace action
• if the transfer fails, the error and the possibility to try again

A note under the zone states the behaviour explicitly: the file is stored as soon as it is chosen, not when you press Save. To change your mind, use Replace and pick another file.

Prompts and parameters that reference an uploaded file show its file name, not the internal storage path.

Files on global inputs

A file can also be supplied as a global input of the flow, so that several blocks use the same document without uploading it more than once. A block input that accepts a file can either take a file of its own or point at a global input; when it points at a global input, the file is chosen once with the rest of the execution inputs.

Finding your way around the panel

The panel keeps a running count of how many inputs are provided out of how many are required, and separates Global inputs from Node inputs, each group badged with how many of its values are still missing, or ticked when none are.

At the bottom, a bar states whether you have unsaved changes and how many. It is the only thing that sends them.

A few conveniences are worth knowing:

• a list input can be filled in one go with Import from JSON array;
• a long value can be opened in a larger editing box;
• Copy from another run fills the panel from a previous execution. The values arrive as unsaved changes, so you can review them before saving. Files and credentials are not copied — an uploaded file belongs to the run it was uploaded to, and credentials never leave the server.

Credentials and authorizations

Some blocks need a secret before they can run: an API key for a language model provider, an authorization header for an HTTP call. The application treats these two cases differently on purpose.

	Provider credential	Runtime authorization
Typical case	an LLM provider’s API key	a header value for an HTTP call
What you supply	a saved credential, chosen from a list	the value itself, typed into a masked field
Where it is kept	encrypted in the vault, on the server	with the execution

A provider key is never pasted as a plain value: it always goes through the vault.

When an execution asks for a credential

An execution that needs one says so before it will start. A banner above the graph reads:

This execution needs a Vault credential for <provider> before it can start.

and the start button is disabled, with a tooltip naming the missing provider. Choose credential takes you to the requirement in the Inputs tab.

Each outstanding requirement appears as its own card, headed Vault credential for <provider>, listing the steps that need it, with a dropdown of the credentials you already have for that provider and an Add credential button for when you have none or want a new one.

Adding a credential

Add credential asks for:

• the provider, which is fixed to the one being asked for;
• a label, so you can recognise it later;
• an optional description;
• the API key itself.

The value is encrypted and stored, and is never shown again — not in this dialog, not anywhere else. Only your own active credentials for that provider are offered.

Once a requirement is satisfied, the amber card becomes a green row naming the credential in force, with Change to pick a different one. A credential that cannot be used — unknown, disabled, or belonging to a different provider — is refused at the moment you choose it rather than in the middle of the run, and the reason is shown under the picker.

Runtime authorizations

Requirements that are not provider credentials appear in the Provider Authorizations section of the inputs panel. Each card names the provider and the field, describes what is wanted, lists the steps that need it, and offers a masked input with Show / Hide and its own Save.

Credentials and reruns

A rerun carries over the authorizations that were already provided, so it usually starts ready to go. Copying inputs from another run does not carry them over.

Human interaction blocks

Human interaction blocks can ask for a confirmation or for a manual answer.

The interaction dialog

When a node requires it, a dedicated dialog opens.

In the non-chat case you can:

• confirm the current input
• edit the answer
• send it with Send Output

In the chat case you can:

• carry on the conversation
• send a final answer

These buttons really do send

The sending buttons perform a real call to the backend. Specifically:

• Send Output
• Confirm Input
• sending a chat message
• sending the final answer

all go through the interaction endpoint of the execution.

Reading an execution

The detail of an execution has a header, the graph, and a side panel with five tabs: Inputs, Intermediate, Logs, Output and Bias impact.

The header

The header carries the run’s name, a fullscreen toggle, and any badges that apply — Simulated, Subflow for one iteration of a container’s subflow, and the bias variant badges described later. A Details disclosure shows the execution identifier and, for a subflow run, its parent, container, iteration and role. Below it, five tiles: status, start, end, duration and steps.

Two banners appear when they apply:

• Execution cancelled. This execution is closed. Start a new execution to continue.
• Execution suspended after service restart. Resume the execution to continue. — paired with a Resume execution button.

Outcomes

Above the graph, a collapsible Outcome(s) section lists what each End node concluded: the outcome code, its label, and the step it came through, with its payload rendered as text or as a JSON tree. An End node that received no value shows only its label, and says so.

Task nodes

In the execution viewer:

• containers show a View Subflow button
• dependency ports are shown only when they are actually connected
• long texts can be opened in read-only mode

Outputs

Outputs are grouped by node. For each node you see the node title and the list of its individual outputs.

If an output exceeds the expected length it is truncated, and the eye icon opens it in full.

When a response is an array it is not shown as a single blob: it is expanded into separate entries, Item 1, Item 2, and so on.

Logs

In the logs tab:

• the content scrolls automatically to the bottom as it refreshes
• the readable text is shown
• the raw JSON detail block is not displayed

Intermediate inputs

The Intermediate tab shows the inputs each step actually received, grouped by node, with the eye icon for long values. For agent and LLM steps it is what was really sent to the model — the first place to look when a step produces something unexpected, because it distinguishes a bad prompt from a bad answer.

The execution tree

When a run has container iterations, an Execution tree panel appears under the executions rail. It shows the run, its container steps — badged waiting when a container is waiting on its subflow — and one child entry per iteration. Clicking any of them opens that execution.

This is the only place to reach past iterations of a container; the canvas shows the current one.

Containers waiting for a person

When more than one container is waiting for a human answer, a bar above the viewer lists them, one button per container and iteration, so you can go straight to the one you mean to answer.

Simulated runs

A simulated run is one where the flow’s human interaction steps are answered by a language model instead of by a person, so the flow can go from end to end without anyone sitting at the dialog.

Starting one

Next to the ordinary start button in the execution toolbar there is a second play button, marked with a robot icon rather than a person. The two tooltips say which is which:

• Run - you answer the human steps
• Run simulated - an LLM answers the human steps

The simulated button only appears when the flow actually has interactive steps and all of them can be simulated. It is otherwise subject to the same conditions as a normal start: the inputs filled in, the credentials provided, the execution not yet started, and not a subflow run.

Clicking it opens Simulation Settings, which asks for the provider and the model, and — under Model parameters — optionally for temperature, top P, top K, maximum tokens and a seed. Each is left at the server’s default when empty.

The seed deserves attention. It fixes the randomness, so the same inputs produce the same answer. Without it, two runs of the same flow differ for reasons that have nothing to do with anything you changed — which is precisely what you are trying to rule out when you compare runs.

What is different about a simulated run

• The interactive nodes cannot be opened during the run; the interaction dialog will not appear.
• The execution header carries a Simulated badge and, under Details, the simulator that answered: provider / model.
• The execution list marks the run with the same badge.
• Containers pass the simulation down to their subflow runs automatically.

Only the answering of interactive steps is simulated. LLM blocks, HTTP calls and agent steps run exactly as they normally would.

Repeating a simulated run

A rerun inherits the simulator of the run it repeats, but not the decision to simulate — that stays an explicit act. When you rerun a simulated execution, a notice says so:

The run this one repeats was simulated with <model>. Start it simulated, with the same model, or the comparison will also be comparing two simulators.

The settings dialog preselects that model for you.

Re-running and comparing executions

Re-running

Each run in the executions list has a replay button, Rerun execution, available once the run has reached a final state. Subflow runs cannot be rerun on their own.

A rerun carries over the workflow inputs, the global input descriptors, the credentials that were provided, and the simulator descriptor. It is created, not started: you still press play, or the simulate button.

Re-running is also how you find out how much a flow varies on its own, which is worth knowing before you read any comparison — a difference no larger than the flow’s ordinary run-to-run variation is not evidence of anything.

Run history

Runs of the same flow are grouped into one collapsible card in the executions rail, showing the flow name, the project chip when there is one, the number of runs, the latest status and when it last ran. Collapsed, it offers Open latest execution. Expanded, it lists each run by number, with a badge saying whether it is an original Run or a Rerun, and — for a rerun — which run it repeats.

Above the list there is a search box and a Filters & sorting disclosure with status toggles (All, Init, Running, Paused, Final) and an ordering control.

These run groups are the rerun history of a single flow. They are a different thing from a project run, which is one execution of each of several flows.

Comparing two runs

On a group with more than one run, the Compare button turns on a picking mode: tick exactly two runs — the bar keeps count — and confirm. The comparison opens in place of the execution viewer.

It shows:

• a header naming the two runs, a toggle between Only differences and All values, and a Close button;
• a summary line — X of Y nodes differ — followed by the caveat that model output varies between runs on its own, so a difference is not by itself evidence of a change in behaviour;
• one section per outcome and per node, each marked equal, changed, only-left or only-right, with the status each side reached and the differing values side by side, highlighted inline.

Two runs that share no node at all are almost certainly runs of different versions of the flow, and the view says so rather than lining up unrelated steps. If the two runs were answered differently — one simulated and one not, or simulated with different models — a warning says that part of what follows comes from that, not from the runs themselves.

This is the general-purpose comparison. A bias report does the same work, but knows which intervention was applied and can therefore speak about its effect.

Bias and mitigation: the idea

A flow that runs successfully is not necessarily a flow you should trust. A prompt can lean on a stereotype, a decision step can favour one kind of answer, an automated recommendation can be taken at face value by the next step. The bias tooling exists to turn that worry into a measurement: you state the risk on the node where you suspect it, you inject the suspect behaviour on purpose, and you look at what actually changed downstream.

The work has three stages:

1. Annotate — record the risk on the node, in the editor.
2. Probe — optionally give the annotation an executable behaviour, so an experiment can switch it on.
3. Experiment and read the report — run the flow with the probe active, compare it against a baseline run, and see whether the outputs, the branches or the final outcome moved.

The same machinery works in both directions. A bias probe injects the problematic behaviour to see what it does. A mitigation probe injects a corrective instruction to see whether it helps. You can also activate both at once.

Nothing here scores a flow as fair or unfair. The platform shows you what changed; the judgement remains yours.

Annotating a node

Where annotations live

Bias annotations are attached to a node in the editor, on the node card itself. Not every block type accepts them — where the feature is not offered, the trigger does not appear.

A node that carries annotations shows a small badge with the count. Hovering it tells you how many there are and the highest severity among them, and states when one of them carries an executable probe.

Clicking the Bias annotations trigger opens the list of annotations for that node, with Add bias annotation in its header and Edit / Remove on each card. A node can hold up to 50.

During an execution the same list is reachable from the node in the execution canvas, in read-only mode.

What an annotation records

The form is driven by the server, so the exact set of fields follows the platform version. Currently it asks for:

Field	Required	What it is for
Category	yes	The kind of risk: selection, automation, historical, accessibility, measurement, confirmation or exclusion bias, or a transparency risk. The form shows a description of the option you pick.
Severity	yes	Low, Medium or High.
Issue	yes	The risk itself, in prose. Up to 2000 characters.
Rationale	no	Why it matters. Up to 4000 characters.
Mitigation	no	A possible corrective action, in prose. Up to 4000 characters. This field is documentation — it is not executed.
Status	no	Where the review stands: Proposed, Confirmed, Mitigated or Dismissed. New annotations start as Proposed.
Source	no	Manual or Automated. Annotations you write by hand are Manual.
Analysis identifier	no	For annotations produced by an external analysis.
Bias probe	no	The executable behaviour to measure. See below.
Mitigation probe	no	The executable correction to apply. See below.

Length-limited fields show a live character counter.

An annotation with no probe is perfectly useful: it documents a risk for whoever reviews the flow. It just cannot be run.

Behavioral probes

A probe is what makes an annotation executable. It is described as an optional controlled behaviour used only by bias experiments — it never affects a normal run of the flow, only a run started from an experiment.

A probe has an activation mode, which says how the behaviour is injected. Which modes are on offer depends on the node type, so the editor loads them per node:

Mode	What it does	Where it applies
PROMPT_DIRECTIVE	Adds an experimental behavioural directive to the node’s prompt.	LLM blocks, MCP agent and agent-chat blocks, human interaction and decision blocks, and conditional or switch blocks that are configured to use an LLM.
INPUT_TRANSFORMATION	Rewrites selected textual inputs before the node runs.	Any block.
OUTPUT_TRANSFORMATION	Rewrites textual outputs after the node runs.	Any block.
ROUTING_OVERRIDE	Forces a conditional, switch or human decision block down a named branch.	Conditional, switch and human decision blocks.
MOCK_RESPONSE	Skips an external call and returns a configured answer instead.	HTTP server-call blocks.

The fields you fill in follow from the mode:

• Prompt directive asks for an Experimental instruction — the text added to the prompt.
• Input transformation and output transformation ask for a Transformation template. ${original} is the only placeholder, and stands for the value being transformed; if you leave it out, your instruction is simply prepended to the original value. Input transformation additionally offers a Target inputs checklist of the node’s real input ports — leave them all unchecked to target every textual input, and note that multiple inputs are transformed item by item.
• Routing override asks for the Forced output branch, chosen from the node’s actual output ports.
• Mock response asks for one typed value per output port rather than an instruction — a checkbox for boolean outputs, a JSON value for structured ones, plain text otherwise.

Every probe also has an Expected impact field. It records what you expect to observe; it does not change the execution.

A prompt directive on a human interaction node biases the simulator’s prompt. If a real person answers that step, the probe does nothing.

A probe counts as executable, and is therefore selectable in an experiment, once it has an activation mode and the content that mode needs — a non-empty instruction, or at least one mock output for a mock response. The annotation list marks such annotations with an Executable probe badge.

Bias probe or mitigation probe

The two probe editors are identical. What differs is intent, and which side of the annotation an experiment switches on:

• the bias probe is the behaviour to measure — inject the suspect behaviour and see what moves;
• the mitigation probe is the correction to apply — inject the corrective instruction and see whether the answer improves.

Every experiment dialog has an Intervention direction selector that decides which of the two fires:

• BIAS — only annotations that carry a bias probe are offered, and only bias probes run.
• MITIGATION — only annotations that carry a mitigation probe are offered.
• BOTH — only annotations that carry both are offered, and both fire in the same run.

Take care with the word mitigation: the Mitigation text field and the Mitigated status are documentation, while the mitigation probe is the executable one.

Running an experiment

The two shapes of experiment

There are two, and you choose between them by choosing which control you click — there is no single dialog with a toggle.

	Isolated step experiment	Full-flow biased rerun
Started from	the chart icon on a node, in the execution canvas	the Create biased rerun button on the execution toolbar
What runs	that one block, repeated with the probe on	the whole flow, as a new execution
Baseline	the output already recorded in the completed run	the run you started from
Report	produced immediately, in the same dialog	produced later, when you click Compare with baseline

Both need a finished baseline execution: an experiment compares a run against a run, so the baseline has to be complete.

Measuring one step in isolation

The chart icon appears on nodes that carry an executable probe. It is shown disabled, rather than hidden, when the experiment is not currently possible, and the tooltip says why — the execution has not finished yet, or the node cannot be replayed on its own.

Nodes that cannot be replayed on their own are the user-interactive ones (chat interaction, human decision, human interactive) and containers. For those, the tooltip points you at Create biased rerun instead.

The Measure bias impact dialog asks for:

• the Intervention direction;
• which Executable annotations to activate — all of them are pre-selected, and changing the direction drops the ones that no longer qualify;
• Repetitions, between 1 and 10, 3 by default — how many times to run the biased variant;
• whether to Include raw outputs in the report, on by default;
• the external side effect policy, described below.

The experiment is queued on the server and the dialog reports its progress. When it finishes, the report replaces the form in the same window.

Two things are worth knowing about how an isolated experiment works. The baseline is not re-run: it is the output already recorded in the completed execution, and only the variants are executed. And because only one block runs, an isolated report has no downstream section — nothing downstream was executed to observe.

Closing the dialog does not cancel the job. It keeps running, and its report appears in the Bias impact tab when it is done.

Creating a biased rerun

Create biased rerun is on the toolbar above the execution graph. It needs a top-level run — a subflow run cannot be a baseline — that has reached a final state and contains at least one node with an activatable probe. When one of those conditions is missing, the Bias impact tab states which one.

The dialog lists one section per candidate node:

• for ordinary nodes, a checkbox per eligible annotation. Unlike the isolated dialog, nothing is pre-selected here;
• for containers, a single Activate biases in the subflow checkbox, which turns on every executable probe on the nodes inside it.

Confirming creates a new execution of the flow, with the same inputs and the probes active, and takes you to it. No report is produced yet — the variant simply runs.

A variant run is clearly labelled. Its header carries a Bias variant, Mitigation variant or Bias + mitigation badge, with the reminder that probes were active and the result is therefore not a baseline, and an expandable block showing the experiment, baseline and intervention identifiers. In the run picker, such runs are suffixed · bias variant.

Comparing with the baseline

Once the variant has finished, Compare with baseline — the compare icon, shown only on a variant run — produces the report. The comparison walks both runs and records what differs.

Comparisons are cached: asking again for the same pair returns the report that already exists, and a report built by an older version of the comparison is recomputed in place, keeping its identity and its assessment history.

External side effects

Some blocks call the outside world — HTTP server calls, MCP agents, MCP agent chats. Repeating them in an experiment would repeat their effects, so every experiment dialog has an External side effects section. When the nodes you selected can make such calls, a warning appears above it.

Policy	What happens
Block external calls	The default. The experiment refuses to run anything that would reach an external service.
Mock external calls	The call is not made. The block is bypassed and its outputs are filled with placeholders.
Allow after confirmation	Real calls are made. You are asked to confirm before the experiment starts.

Choosing Allow after confirmation and pressing the run button opens a confirmation dialog first; your answer is recorded on the resulting execution, so the choice remains auditable afterwards.

Three practical consequences:

• With the default policy, an experiment on a flow containing an HTTP or MCP node will fail rather than run — the message says the side effects were blocked. This is the most common reason for an experiment to error.
• The isolated experiment checks this up front, so it fails immediately. A full-flow rerun only discovers it when the offending step is reached, in the middle of the run.
• With Mock external calls, everything downstream sees a placeholder instead of a real answer. Differences downstream of a mocked node therefore partly reflect the mock, not the intervention. The report lists every mocked call for exactly this reason.

Reading a bias impact report

The same report viewer is used everywhere: inline at the end of an isolated experiment, in the compare dialog, and when you open a stored report from the Bias impact tab.

The headline

The top of the report tells you, before any number, whether the thing that matters changed:

• Final decision changed or Final decision unchanged — set when the flow’s final outcome differed, or when it took a different branch somewhere.
• X of Y subjects changed, when the compared output is a list and each element is a subject.
• The strongest numeric delta, written in the flow’s own units, for example Score 5 → 8 (+3).
• A chip about simulation, when either run was simulated.
• A chip summarising the model assessment, when one has been requested.

Below them, a one-sentence summary generated by the server, which leads with the decision, then the subjects, then the averages, then the counts of changed downstream nodes and routing changes.

A collapsed section carries the identifiers — baseline execution, biased execution, experiment, node, annotations, repetitions — for when you need to trace a report back to its runs.

Immediate impact

What the activated node itself produced, baseline against variant.

Three figures are given: whether the output changed at all, the change rate, and the maximum text difference, which runs from 0 for identical to 1 for maximally different.

For list-shaped outputs there is a Per subject breakdown, showing only the changed subjects by default. Each subject expands into a two-column diff with word-level highlighting. For container nodes, the breakdown is per iteration, and states the status each side ended on.

The numbers come in three flavours, in increasing order of usefulness:

• a normalised text difference, which tells you that something moved;
• the share of list elements that changed, which tells you how widely;
• labelled numeric deltas, which tell you how much, in the flow’s own units. These are extracted from plainly labelled numbers such as Score: 7 or confidence = 0.8, which is why they are sometimes absent.

List elements are paired by position: element i is treated as the same subject on both sides.

Downstream impact

Every node downstream of the activated one, with whether the change propagated, the status each side reached, and the same per-field and per-subject drill-down. A checkbox narrows the list to the changed nodes.

An isolated experiment always shows this section empty, and says so.

Routing and outcome changes

The two largest things an intervention can do:

• an outcome change — the flow ended on a different outcome;
• a routing change — the flow took a different branch at a named node.

A routing change is reported only when both runs produced exactly one branch at that node and the two differ.

Mocked side effects

Present only when something was mocked. Each entry names the node and the kind of call that was skipped. Read it as a caveat on everything downstream of those nodes.

Warnings

Always shown, even when empty. The ones you will actually meet:

• on an isolated report, that the baseline was captured from the completed run and only the variants were repeated;
• on a full-flow report, that observed differences may also include ordinary non-determinism from external models;
• that only the first 200 elements of a long list, or the first 20 000 characters of a long text, were compared;
• that the two runs did not perform the same number of container iterations;
• that the interactive steps were simulated on one side and answered directly on the other, or simulated with different models — in which case part of the difference does not come from the intervention at all.

Warnings are not failures. They tell you how far to trust the numbers above them.

Highlighting the report on the canvas

Highlight on canvas closes the report and paints it onto the execution graph. A legend appears above the canvas, nodes carrying an active annotation and nodes whose output changed get their own badges, and connections on a branch that changed are marked. Back to normal view restores the ordinary canvas.

Asking a model to assess a report

A report measures differences; it does not say whether a difference matters. Evaluate impact with LLM asks a model to read the compared pairs and give an opinion. You choose the provider and model in the usual picker.

Each assessment yields:

• an impact level — NONE, COSMETIC, SUBSTANTIVE or DECISIVE — how far the meaning of the output moved;
• an attribution — INJECTION, NON_DETERMINISM or UNCLEAR — whether the change carries the intervention’s fingerprint or looks like ordinary model variation;
• a narrative, plus a badge on each individual subject and field.

Assessments accumulate: the report keeps a history, newest first, so a second opinion does not erase the first. The per-subject badges follow the most recent one. Pairs that are identical are never sent to a model.

Two limits are worth stating plainly, and the viewer states them itself. This is an assessment by a model, not a measurement. And with a single run per side, a difference cannot be separated from ordinary model variation with certainty — which is the argument for raising Repetitions, and for setting a seed on the judge model when you want a repeatable opinion.

A report saved with Include raw outputs switched off cannot be assessed later: the outputs it would need were not kept. If you may want a model’s opinion, leave that box ticked.

The Bias impact tab

Every report produced for an execution is listed in the Bias impact tab of the execution panel, alongside Inputs, Intermediate, Logs and Output.

Each row shows the kind of report, whether anything changed, the date, the summary sentence, how many annotations were activated, and whether a model has assessed it. Clicking a row opens the full report.

When the tab is empty it explains what would fill it: on a variant run, that comparing it with the run it repeats is what produces the report; on an ordinary run, what a report is and how many nodes carry a probe that could be activated.

Administration

Accounts with the administrator role reach a separate workspace through Admin users in the user menu. It has a Back to editor link and a sidebar with two groups: Auth, holding Users and Create user, and Stats, holding Operations.

Users

The list shows each account with its username and email. For each one you can change the role between USER and ADMIN — the Save role button stays disabled until you actually change it — reset the password, or delete the account.

Create user

Provisions a new account: username, email, role and password. A live checklist below the password field shows which policy rules the password currently satisfies.

Operations

Aggregated usage figures, for everyone or for one account at a time. The cards cover flows (with how many are published and finalized), executions (running, succeeded, failed), simulations, and — once a user is selected — authentication figures such as login count and average session length, alongside the last flow update and last execution.

Practical tips

• save often after structural changes
• check the errors panel before running
• use Connections to pass data and Dependencies only to impose order
• use containers to isolate reusable parts of the flow
• if a node looks incomplete, check its missing parameters before running
• if a text is truncated, use the eye icon instead of widening the node
• finalize the flow you intend to use as a baseline, so later runs remain comparable
• before trusting a difference between two runs, re-run the baseline once and see how much the flow moves on its own
• when a comparison has to mean something, simulate both runs with the same model and a fixed seed
• leave Include raw outputs ticked on an experiment you may want a model to assess later
• annotate risks as you build, even without a probe: an annotation with no probe is still the record of a concern

Common problems

I see a loader instead of the blocks in the sidebar

The block or container catalogue is still loading. Wait for the backend to return the type descriptors.

A node looks empty when I open it

The type schema may not be available yet. Clicking the node makes the application retry the load.

A container is reported as incomplete

Check that it has a Subflow. A container without one is considered missing.

The flow stays DRAFT after saving

Open the validation errors panel. The flow may have been saved and still not be executable.

An error points at a container, not at a block

The error comes from inside the container’s subflow. Open the subflow with View Flow: the node responsible is highlighted there.

I cannot see a whole answer in the tasks view

If the value is long or truncated, use the eye icon to open the full content in read-only mode.

The start button is disabled and I cannot see why

Check the banner above the graph. An execution that still needs a provider credential cannot start, and the tooltip on the start button names the provider it is waiting for.

The experiment button on a node is greyed out

Its tooltip says why. Either the execution has not finished yet — an experiment needs a completed baseline — or the node cannot be replayed on its own, which is the case for interactive steps and containers. For those, use Create biased rerun on the toolbar instead.

My experiment failed with a side-effect error

The flow contains an HTTP or MCP node and the policy was left at Block external calls. Choose Mock external calls, or Allow after confirmation if the real calls are safe to repeat.

I cannot ask a model to assess my report

The report was saved without its raw outputs, so there is nothing left to assess. Run the experiment again with Include raw outputs in the report ticked.

A comparison shows differences I did not cause

Read the warnings. Model output varies between runs on its own; if the two runs were simulated differently, or not simulated at all, part of the difference comes from that. Fix a seed and simulate both sides the same way, then compare again.

My uploaded file does not appear in the prompt

Check that the input is the one the block actually reads. A block input can either hold its own file or point at a global input; if it points at a global input, the file must be provided with the execution inputs.

Conclusion

HumAIn Flow lets you work visually and with assistance. The recommended path is:

1. create or open a flow
2. build it by hand or with the assistant
3. save it
4. fix any validation errors
5. run it from the Tasks tab
6. follow inputs, outputs and logs to completion

And, when the question is not only does the flow work but what is it sensitive to:

7. finalize the flow and record a baseline run
8. annotate the steps you want to probe
9. run the experiment and read the report