Flow
Contents · The Flow Book

Start here

The Flow Book1. Your first run2. Let the outside answer3. Keep the original answer

Build the decision

4. Give the program an input5. Name the work6. Give values a shape

Build the workflow

7. Decide what failure means8. Put the decision in its own file9. Put the pieces together

Go further

10. Work on several things11. Leave room for an answer12. Take Flow into an application

Build an application

13. Investigate a real question14. Challenge: diagnose and extend
Language reference ↗
The Flow Book / Build an application

Investigate a real question

Run the credential-free workbook first. You will investigate Python 3.12 cache concurrency, discover why a plausible answer can still be incomplete, and retain evidence for the decision. Allow about 20–30 minutes for this chapter and its challenge after building the CLI.

This project uses the maintained research controller in main.flow and its Tool declarations. These source links require repository access. Commands below run from a local checkout's root, in either Zed's or VS Code's integrated terminal. Stock Flow Run tasks do not prepare this application's host.

1. Prepare and predict

cargo build --locked -p flow-cli
python3 examples/research/workbook.py check

The workbook supplies explicit teaching replies and embedded editorial documentation paraphrases. It performs no fresh web research or model calls. Its checked-in public card file asks about cached_property and lru_cache; the start command supplies that file explicitly. Inspect task.json in the run directory to see the actual requirement IDs and prompts. A cited URL identifies the paraphrase's reference; it does not mean the workbook fetched that page.

Before starting the complete case, write your prediction: if the assessor supplies supported claims for every declared requirement, what else must the controller inspect before publishing? Name a condition that could still prevent publication.

python3 examples/research/workbook.py start --requirements-json examples/research/workbook-requirements.json \
  --case complete --directory /tmp/flow-book-complete

Open the printed brief.md path. Compare your prediction with the outcome. Find the admitted claims and their embedded evidence. Open result.json for the retained source text and task.json for declared cards. A claim is more than a sentence: it identifies a requirement ID, source URL and quotation. Which part connects it to the requested answer?

2. Follow the adaptive decision

Open examples/research/main.flow in your editor. Trace main into investigate and find these pieces:

  1. Planning proposes queries; search gathers URLs and fetch gathers sources.
  2. Drafting proposes claims; assessment proposes supported findings, Answered or Unresolved resolutions, gaps and followups.
  3. The Flow code admits evidence and requires one valid evidence-backed answer per declared requirement before deciding whether to publish or investigate further.

The controller filters already searched queries and fetched URLs, and continues within its supplied round and search bounds. Those are visible decisions in this application program. The model implementations and their request allowance live in the host. Follow the application boundary for the distinction, rather than inferring it from an operation's name.

Inspect your run:

python3 examples/research/workbook.py history --directory /tmp/flow-book-complete
python3 examples/research/workbook.py replay --directory /tmp/flow-book-complete

Before replaying, predict whether another search or publication should happen. Before and after replay, compare the number of lines in calls.jsonl and store/effects.jsonl in the run directory. These are the workbook's application call and publication records; replay should not add lines. An incomplete run may have no publication-effect file at all. Inspect them alongside history. A matching replay explains the original orchestration. It does not verify the documentation's truth or acquire today's version of a page.

3. Find a missing answer

Before running this case, predict the result when the assessor declares no gaps but the admitted claims leave one declared requirement unanswered. Locate the function that should decide this.

python3 examples/research/workbook.py start --requirements-json examples/research/workbook-requirements.json \
  --case missing-topic --directory /tmp/flow-book-missing
python3 examples/research/workbook.py history --directory /tmp/flow-book-missing

Use your own brief to identify the absent topic and the retained gap. Find coverage and the complete expression in main.flow. A supported finding is distinct from an answer to a requirement. Each declared requirement needs exactly one Answered resolution with a nonblank answer and nonempty, admitted evidence for that topic. Unresolved, missing, duplicate and invalid resolutions block publication even if the assessor supplies no gaps. In history, find assessment's reply and the later outcome; inspect calls.jsonl when the summary abbreviates a value. These structural checks still require semantic source review.

What would actually resolve this case: more evidence for the absent topic, changing the requirement, or merely deleting the printed gap? Explain your answer before continuing.

4. Reject a plausible quotation

Predict what happens if a proposed supported claim names a known source, but its quotation is absent from the retained source text.

python3 examples/research/workbook.py start --requirements-json examples/research/workbook-requirements.json \
  --case quote-mismatch --directory /tmp/flow-book-quote
python3 examples/research/workbook.py history --directory /tmp/flow-book-quote

Find the proposed claim in the assess input recorded in calls.jsonl. Compare it with the source excerpt in result.json and the admission expression in investigate. Locate the exact mismatch yourself. Do not silently replace the retained observation to make the run pass.

Separate three questions: did assessment propose the claim, did Flow admit it under this program's checks, and does the source actually entail every part of the claim? An exact quotation helps with provenance. It can still be out of context, about the wrong version, or insufficient for the conclusion. Domain correctness needs a source review beyond this application's deterministic gate.

5. Change a requirement, then preserve the original

Predict the effect of requiring an additional answer named Operational recovery. Start a new case with that requirement:

python3 examples/research/workbook.py start \
  --case complete --requirements-json examples/research/workbook-recovery-requirements.json \
  --directory /tmp/flow-book-extended
python3 examples/research/workbook.py replay --directory /tmp/flow-book-complete

Read task.json: the supplied card file retains both original obligations and adds a recovery obligation; IDs and prompts are explicit, with no default or automatic decomposition. Compare its coverage with the original run. The new requirement belongs to a new investigation. Replaying the original record still explains the original question, source bundle and inputs; it does not apply your new requirement retroactively.

Answer an ordinary Tool without credentials

Before starting, predict whether a paused run will already contain any research findings.

python3 examples/research/workbook.py start --requirements-json examples/research/workbook-requirements.json \
  --case complete --directory /tmp/flow-book-human --ask-focus
python3 examples/research/workbook.py history --directory /tmp/flow-book-human
python3 examples/research/workbook.py answer \
  --directory /tmp/flow-book-human \
  --answer 'Prioritize whether overlapping calls can compute twice.'

Find clarify in examples/research/request_tools.flow and its handling in request.flow. The application prints the pending question and accepts a Text reply through answer; Flow handles it as an ordinary declared Tool answer. The workbook records your answer, adds a focus card, and still supplies the same explicit teaching evidence; an uncovered added obligation remains Incomplete. It does not adapt retrieval to your criterion. A blank answer is rejected by the application while the run stays paused.

Optional: obtain evidence live and answer a Tool

Once you can diagnose the workbook, follow the maintained application recipe for prerequisites, outcome interpretation, acquisition limits and recovery. Live research requires an installed Codex CLI with an existing login. Allow several minutes; network and model latency vary.

python3 examples/research/auto.py start \
  --directory /tmp/flow-book-live \
  --question 'How do Python LangGraph interrupts resume, and can earlier code repeat?' \
  --requirements-json examples/research/live-requirements-example.json \
  --domain docs.langchain.com \
  --ask-focus --interactive --allow-live-model

Before answering, identify the clarify declaration in examples/research/request_tools.flow and its handling in request.flow. Type your criterion into the terminal prompt, for example Focus on what can execute twice after resumption. This is an ordinary typed Tool reply retained in the record. The application provides the terminal interface; the browser lesson runner does not connect it.

Without an interactive terminal, leave the run paused and supply the answer later:

python3 examples/research/auto.py answer \
  --directory /tmp/flow-book-live \
  --answer 'Focus on what can execute twice after resumption.' --allow-live-model

Use the recipe's history and replay commands afterwards. Add --json when an agent needs a machine result. A live run may honestly finish incomplete: inspect the gaps before deciding what to change.

Continue to Challenge: diagnose and extend. Exact rules: function evaluation, Tools, history and runtime execution.