Flows

## Instantiate, then kick off A Flow subclass is a normal class. You create an instance and call `kickoff()` on it: ``` flow = ReportFlow() result = flow.kickoff(inputs={"topic": "solid-state batteries"}) ``` That call fires every `@start` method, dispatches listeners as steps complete, and returns when nothing is left pending. There is no separate build or compile step and no runner object to construct. ## What inputs actually do The `inputs` dict is not passed to your methods as arguments. It is applied to the flow's state *before* the start methods run. So a start method reads what it needs from `self.state`: ``` @start() def outline(self): return f"Outline for {self.state['topic']}" ``` This matters for two reasons. First, with structured Pydantic state the incoming values go through the model, so types are validated and coerced rather than stored blindly — a run started with the wrong shape fails at kickoff rather than three steps in. Second, it keeps the flow testable: because everything a run needs is on state, a test can construct the flow, set state directly, and call a single step in isolation without going through kickoff at all. ## Async `kickoff_async()` is the awaitable variant, for running a flow from within an event loop — a web handler, or alongside other concurrent work. Steps themselves may be declared `async def`, which is how a single step performs concurrent I/O internally. Note the distinction interviewers like: awaiting the flow does not make your synchronous steps concurrent with each other. Fan-out across steps is expressed structurally, with multiple entry points or branches, and rejoined with an explicit join condition — not by switching the kickoff call. ## What comes back `kickoff()` returns the output of the last method that executed. In a straight chain that is the obvious terminal step. In a branching flow, "last executed" depends on which branch a router chose and how branches interleave, so treating the return value as *the* result is fragile. The habit that survives contact with production is to write the authoritative result onto state and read `flow.state` after the call — the flow instance is still yours, and its state is fully populated. The same object also carries the auto-generated run `id`, which is the value to log next to everything the run produced so a later investigation can tie output back to one execution. ## Errors An exception raised inside a step propagates out of `kickoff()`. Downstream listeners never fire, there is no automatic retry, and there is no partial-success return value — but the state the flow accumulated up to that point is still readable on the instance, which is often enough to see how far it got and what the last successful step wrote. If you need retries or compensation, they are code you write inside the step or the caller. ## Seeing the graph `flow.plot()` generates an interactive HTML visualization of the flow's steps and the edges between them. It reads the declarative wiring, so it works without executing anything. It is the fastest way to catch the two classic wiring mistakes — a listener attached to the wrong trigger, and a branch label with no subscriber, which leaves a step floating with no inbound edge. On a flow with more than a handful of steps, plotting it is cheaper than reading the decorators. ## Running the same flow many times Each flow instance owns one state, so running two requests concurrently means two instances — do not reuse one instance across concurrent kickoffs and expect its state to stay coherent. Constructing a flow is cheap; the expensive parts are the crews inside it. For a batch, instantiate per item and, if you want them concurrent, drive the async form from your own gather rather than expecting the flow to parallelize across runs.