Run a Flow¶
A Flow is data work you repeat, done in numbered Phases with a person checking the result before it goes on. To write one, see Flow authoring.
Open Flows, pick a Flow, and open the Runs tab. A Flow marked will not run has a problem; the Edit tab says what.
Start a run¶
Write a brief — what this run is for — and click Start a run:
Focus on the North region, and say which stores drove the change.
The brief is saved with the run as brief.md. Phases that read it can change what they pull or
write; Phases that do not, run the same way every time.
A new run waits at the first Phase. Nothing executes until you press Run 01_pull.
The run story¶
Brief — Which North stores drove the change?
- Pulled total units sold and total revenue by date, region and category into sales_by_region_category_daily.csv · 392 rows
- Pulled total revenue by date and store into sales_by_store_daily.csv · 812 rows
- Ran compute_wow.py
A run paused at a review point after its second Phase. The next Phase reads the outputs exactly as they are when you press Continue.
The run page tells the story of the run, Phase by Phase.
- The header shows status, X of N phases done, and the main action: Run phase, Continue to phase, or Stop while it works.
- A sentence says where things are: Waiting for you. 02_forecast is done and paused for review; 03_plan runs when you continue.
- Each Phase section shows:
- Reads — the brief, files from earlier Phases;
- Follows — the rule files it obeys;
- How — a fixed script, no model, an agent that can query the data model and run Python, or an agent that writes from what it reads;
- Prepared — the queries and scripts written with the Flow;
- What it did — plain sentences: Pulled stock by store into stock_position.csv · 348 rows, Ran the prepared script forecast.py. A step marked not the prepared one is the agent doing something different from the prepared work — read why in its output;
- What it produced — each output, with its row count and a preview. Also saved, but not
passed on lists files in
scratch/.
The page re-reads the run every two seconds while it works.
Review points¶
A Phase with review: required ends at a review point. The run stops: Paused here for your
review.
- Read what the Phase produced.
- If something is wrong, click Edit on an output, fix it, and Save — the next phase reads this. Only the Phase just before the review point can be edited.
- Click Continue to
.
A review point is written to disk, so it survives a portal restart.
Script approval¶
An agent Phase that writes its own script asks first: Wants to run a script. Read it, then decide. — Run, Always in this chat, or Decline. A prepared script that is unchanged runs without asking. An approval waiting when the portal restarts fails the Phase.
When something goes wrong¶
A failure stops the run where it is: Stopped at 02_forecast: declared output has no rows: forecast.csv. Fix the cause, then use "Re-run from here" on that phase. See What fails a Phase for every message.
- Re-run from here points the run back at that Phase. Phases after it that had finished become stale — still readable, but they may no longer follow from what came before. Press Run to go on.
- Stop ends the Phase now, as a failure: stopped by the user.
- Delete run (type
delete) removes the run's folder. A run that is going must be stopped first.
Every run is kept as files under the Flow's runs/ folder: the brief, each Phase's outputs, and a
log of every step.