Branching, routing and merging chains

What you'll learn

• Build a multi-step pipeline that keeps every intermediate result with .assign().
• Count the model calls and rounds of a fan-out and merge.
• Explain how RunnableBranch picks a chain, and why the order of its conditions decides ties.
• Design a default branch that surfaces classifier drift instead of hiding it.

Lesson 2 of T4.2 showed that a dict inside a pipe runs its values in parallel and that .assign() keeps old keys. A straight pipe still does one thing in one order. The Larkspur support desk needs more: tickets arrive in Spanish and French and must be answered in the customer's language, sales wants a plan comparison written from three angles at once, and every ticket must reach the chain that holds the right policy. On the first day of routing, a ticket labelled "Refund or outage" goes to the refund chain, and nobody notices that the outage was never handled. Notebook 03a builds the three shapes these jobs need, each from the pieces of lessons 1 and 2 of T4.2.

Linking: keep the trail

The notebook's IT-support pipeline runs four model chains in order. Each step is a RunnablePassthrough.assign(), which means each one adds a key and keeps every key before it:

Table 1: The four linked steps of notebook 03a. The last step still reads orig_lang from the first.

final_chain.map() runs the pipeline over the notebook's queue of four messages at once. We ran the same chain shape with a stub that sleeps in place of the model: 16 model calls in 4 rounds rather than 16, because the four messages run side by side while each message's four steps stay in order. A round here is one wait on the model; calls in the same round run at the same time.

Fan-out, then merge

Some jobs split into independent parts that meet again. The notebook writes a report on a topic from three branches:

Figure 1: Three model branches run at once, and one merge call reads all four keys.

The three model branches share one input and run at the same time. itemgetter('topic') copies the topic through without a model call, which lets the merge prompt name it. The merge prompt reads all four keys and writes the report. That is 4 model calls in 2 rounds, confirmed with the same stub, and the wall time is the slowest branch plus the merge. A Larkspur version compares plans: description, pros and cons of the annual plan in parallel, then one call that writes the comparison table.

Routing with RunnableBranch

Figure 2: The review router in notebook 03a. Conditions are tested top to bottom.

RunnableBranch takes (condition, Runnable) pairs followed by a default, tests the conditions in order, runs the first whose condition returns true, and runs the default when none does. It needs at least one pair and a default: given a single argument, the installed library raises ValueError: RunnableBranch requires at least two branches. In the notebook a dict first runs the classifier and copies instruction, review and sentiment beside its label, and the branch then picks a chain. A routed request costs 2 model calls in 2 rounds, or 1 call when the default answers with its fixed string.

We fed the notebook's branch a set of planted labels, with stubs in place of the three model chains:

Table 2: Planted classifier labels and where the router sent them.

The third row is first-match capture: a request that matches two conditions goes to whichever comes first, silently. The same thing happens in the keyword router of notebook 01b, which checks machine-learning words before cloud words. A deployment question that mentions both models and a cloud provider is answered by the machine-learning handler, although the notebook's own comment expects the cloud one. For the Larkspur triage router the opening ticket behaves the same way: with a refund condition ahead of an outage condition, "Refund or outage" reaches the refund chain, and "refunds" matches too because "refund" is inside it.

Planning the default

The default is where every request the classifier cannot place lands. In notebook 03a it returns a fixed apology. We call that a silent default: the request gets an answer, nothing is logged, and a classifier that has started returning new labels looks healthy. For a support desk the default should hand the ticket to a person and be counted, because a rising default rate is an early sign that the classifier has drifted.

The notebook ends with a guard of a different kind. It pipes a chain into OpenAIModerationChain, a chain class from the langchain-classic package, which screens the output before it reaches the caller. Any Runnable can take that last position, which is how output checks and guardrails attach to a pipe.

The three shapes answer different questions about the work:

Table 3: The three shapes compared on the notebook's own chains.

A ticket triage chain for Larkspur combines all three:

1. A dict runs the classifier and copies the ticket text and the customer's plan beside the label, as the review router does.
2. The classifier returns one of a fixed set of labels (refund, outage, export), which removes most multi-label answers before they reach the branch.
3. The branch sends each label to the chain whose prompt holds that policy. Exact matches replace substring tests: "refunds" no longer passes as "refund".
4. The default hands the ticket to a person, and its rate is logged per day.
5. A non-English ticket runs through the linked translation steps around whichever chain answers it.

Lesson 4 of T4.2 turns to older code: the chain classes that did these jobs before LCEL, and how to replace them.

The code for this lesson is in these notebooks. Colab runs one in your browser: install the packages its first cell imports and set the API keys it reads. To run every notebook as written, clone the repository and use its uv environment.

• Link steps with .assign() to keep every intermediate result, and use .map() to run several inputs side by side while each input's steps stay in order.
• Fan out with RunnableParallel and merge with one more chain. Wall time is the slowest branch plus the merge.
• RunnableBranch runs the first true condition, which makes first-match capture the default behaviour. Constrain the labels, and make the default hand off to a person and count it.