Flowcharts without the editor

Flowcharts can be built, read, changed, checked and run without the graphical editor: from the command line with seamm-flowchart, from Python, or by an AI assistant through SEAMM’s MCP server. All of them check every step, parameter, choice, number and unit as the editor does, and write a complete flowchart that the editor opens and the JobServer runs.

Flowchart format 3.0

Flowcharts (.flow files) now have a second, readable format, 3.0, written in YAML. It holds the flowchart’s metadata, the versions of the plug-ins it was made with, a digest that identifies its content, every parameter of every step, steps that are not connected (kept for the editor), and the layout. Format 2.0, the JSON format, is still read: it is converted to 3.0 as it is loaded, by a converter that never changes.

Format 3.0 was introduced in two releases, so that every installation could read it before any wrote it: SEAMM 2026.10.1 read 3.0 but still wrote 2.0 from the editor, and since 2026.10.2 everything writes 3.0. Setting the environment variable SEAMM_FLOWCHART_FORMAT to 2.0 writes the old format, for an installation that must still exchange flowcharts with one older than 2026.10.1.

Jobs run between updating to 2026.10.1 and to 2026.10.2 still saved 2.0 flowcharts; seamm-manager flowcharts migrate converts them (see below).

The seamm-flowchart command

seamm-flowchart is installed with SEAMM. Each command loads the installed plug-ins first, which takes several seconds.

seamm-flowchart steps [--json]                  # every step, by group
seamm-flowchart steps ORCA                      # the sub-steps of a step
seamm-flowchart describe "ORCA/Energy"          # parameters, choices, defaults, help
seamm-flowchart build spec.yaml -o my.flow      # build a flowchart from a spec
seamm-flowchart show my.flow                    # what a flowchart does, as a spec
seamm-flowchart tree my.flow                    # its steps and their addresses
seamm-flowchart set my.flow ORCA/Energy basis=def2-TZVP
seamm-flowchart insert my.flow Energy method=MP2 --after ORCA/Optimization
seamm-flowchart remove my.flow 3.2
seamm-flowchart move my.flow 4 --before 2
seamm-flowchart validate my.flow
seamm-flowchart convert old.flow -o new.flow    # e.g. 2.0 to 3.0
seamm-flowchart migrate --root ~/SEAMM          # see below
seamm-flowchart mcp                             # the MCP server, see below

set, insert, remove and move write the flowchart back unless -o is given. Values are name=value, read as YAML, so 10, [1, 2] and {energy: {table: table1, column: E}} work; quote names with spaces or use underscores. A step is addressed by position (3, 3.2 for the second step inside step 3), by name (ORCA/Energy), or both (3/Energy).

Specs

A spec is a short YAML description of a flowchart that gives only what differs from the defaults. seamm-flowchart build turns it into a complete flowchart, and seamm-flowchart show turns a flowchart back into one:

title: Water optimization and frequencies
description: B3LYP/def2-SVP optimization, then frequencies
steps:
- Model Chemistry: {model chemistry: "ORCA:DFT@B3LYP/bse:def2-SVP"}
- FromSMILESStep: {smiles string: O}
- ORCA:
    steps:
    - Optimization
    - Frequencies
- Loop:
    type: Foreach
    variable: SMILES
    values: C CC CCC
    body:
    - FromSMILESStep: {smiles string: $SMILES}

Steps are named by extension name, as the editor’s step menu shows them. steps: holds the sub-steps of a code step, and body: the steps of a loop (the Join a loop needs is added). Units are written 300 K or [300, K], and SEAMM’s conversions between energy, temperature, wavenumbers and frequency are allowed. $name uses a variable; an = expression is Python with bare variable names. A spec is never run itself: it is always built into a complete flowchart first.

From Python

from seamm.builder import FlowchartBuilder

fb = FlowchartBuilder(title="Methane to propane")
fb.add("Model Chemistry", model_chemistry="ORCA:DFT@B3LYP/bse:def2-SVP")
with fb.loop(type="Foreach", variable="SMILES", values="C CC CCC") as body:
    body.add("FromSMILESStep", smiles_string="$SMILES")
    orca = body.add("ORCA")
    orca.add("Optimization")
fb.write("alkanes.flow")             # checks the flowchart first

seamm.spec builds and reduces specs (spec.build(text), spec.reduce(fc)), and seamm.edit reads and changes existing flowcharts (read, set_parameters, insert, remove, move, tree, validate).

Settings that depend on each other

A step can say which of its parameters apply given the others, narrow a list of choices, and fill in a value that follows from another. The step’s dialog and these tools share the same rules, so a setting with no effect is refused, with the reason (for example “it applies when ‘use model chemistry’ is ‘no’”), and a value that contradicts another is refused too. Set the controlling parameters in the same command. describe shows when each parameter applies, and validate reports combinations that cannot work.

Converting an installation’s flowcharts

The flowchart of every job (flowchart.flow in its directory) and the datastore’s record of it can be converted to format 3.0 in one step:

seamm-manager flowcharts status       # how many job flowcharts are still 2.0
seamm-manager flowcharts migrate      # dry run, confirm, convert

migrate shows what it would change, asks for confirmation, stops the JobServer and web UI, backs up the datastore, renames each job’s original flowchart to flowchart.v2.flow (unchanged) beside the new flowchart.flow, converts the datastore, and restarts the services. Back up the Jobs directory first. Moving the datastore aside and letting the web UI rebuild it is not a conversion: the rebuilt datastore keeps no accounts and converts nothing.

The step-by-step guide to upgrading an installation, including what the messages mean, how to undo the conversion and how to convert your own flowcharts, is Upgrading to flowchart format 3.0 in the main SEAMM documentation.

AI assistants: the MCP server

seamm-flowchart mcp serves these operations as tools to AI assistants that support the Model Context Protocol, such as Claude Desktop and Claude Code. It needs the optional mcp package (pip install 'seamm[mcp]'). It keeps the plug-ins loaded, so each call takes under a second. For Claude Code:

claude mcp add --scope user seamm -- ~/SEAMM/venv/bin/seamm-flowchart mcp

Its tools list and describe steps; build, show, check, convert and edit flowcharts; and run them through a dashboard: list the dashboards and their projects and queues, submit a job, follow it, and read its files. Submitting checks the flowchart first and needs a queue when the dashboard has queues. The dashboards and credentials are read from the installation’s dashboards.ini and ~/.seamm.d/seammrc, never written, and the credentials are never shown. An assistant should confirm the dashboard, project and queue with you before submitting, since a submission starts a real calculation.

The server also tells the assistant when to offer SEAMM. Asked to calculate a molecular or materials property, or asked about one that can be computed, it offers – after giving any known values and their source – to calculate it with SEAMM, in a line or two: a method suited to the property and the size of the system, roughly how long it will take, and a cheaper or a more accurate alternative. It proposes only methods that your installed plug-ins provide, builds nothing until you agree, and does not offer for purely conceptual questions. SEAMM is offered, not imposed: the assistant may have other ways to calculate a property.