In LCEL, when do you use RunnableParallel versus RunnablePassthrough.assign?

## Three related pieces **`RunnablePassthrough()`** is the identity: `invoke(x)` returns `x`. On its own it looks pointless; its use is positional. Inside a parallel mapping it is the branch that carries the untouched input forward, so `{"raw": RunnablePassthrough(), "derived": some_runnable}` gives the next step both the original and the computed value. **`RunnableParallel`** takes a mapping of names to runnables. On `invoke(x)` it runs *every* value on `x` — concurrently, using a thread pool in the sync path and `asyncio.gather` in the async path — and returns a dict of the same keys with each branch's output. The crucial property is **replacement**: the output dict contains exactly the mapping's keys. Any field of the input that no branch reproduces is dropped. **`RunnablePassthrough.assign(**kwargs)`** is the merging variant. It expects a dict input, runs each keyword's runnable on that whole dict, and returns the input dict updated with the new keys. Existing keys survive; a name collision overwrites. This is the additive, accumulating idiom. ## Choosing between them Ask what the next step needs: - *The next step needs a brand-new shape built from the input* → parallel dict. You are projecting, and you want the old shape gone so the contract is explicit. - *The next step needs the original fields plus something computed* → `assign`. You are enriching, and re-listing every carried field in a parallel mapping would be noise that silently drops a field the day someone adds one. A chain of three enrichment steps written with parallel dicts has to restate every surviving key three times; written with `assign` it reads as three additions. Conversely, using `assign` where you meant to project leaves dead fields travelling down the chain, which bloats anything that serialises the payload and makes traces harder to read. ## Concurrency and cost Branches in a parallel block are genuinely concurrent, which is the performance argument for using one: two independent network calls take max(t1, t2) rather than t1 + t2. But concurrency is per-block, not global — nesting parallels multiplies in-flight work, and each branch inherits the same `RunnableConfig`, so a `max_concurrency` you set for a batch does not separately cap fan-out width inside one invocation. If a branch is expensive and its result is only sometimes needed, the parallel block will still pay for it every time; there is no laziness. ## Error semantics If any branch raises, the whole parallel step raises — there is no partial dict. If you want a degradable branch, decorate that branch alone with `.with_fallbacks([...])` so it produces a default instead of failing the block. Similarly, a slow branch sets the floor for the whole step; a per-branch `.with_config()` carrying a shorter timeout (where the underlying component honours one) is the lever. ## Shape discipline Both constructs are where shape bugs breed, because the pipe operator does not typecheck at build time. Two habits help: 1. Keep the key names identical to what the downstream step expects, so the mapping reads as the downstream contract. 2. Use `itemgetter` from the standard library as a cheap projecting step — it is a callable, so LCEL coerces it into a `RunnableLambda` automatically. ## Streaming caveat A parallel block cannot stream a dict incrementally the way a single string-producing step streams chunks: downstream steps generally see the block's result once all branches finish. If token-level streaming to the caller matters, keep the fan-out early in the chain and make the final step the streaming one. ## Common mistakes - Assuming `assign` runs its runnables on a single field rather than on the whole input dict. - Using a parallel dict mid-chain and being surprised that a field set two steps earlier has vanished. - Putting `RunnablePassthrough()` as a top-level step and expecting it to do something — outside a mapping it is a no-op. - Expecting a failed branch to yield `None` rather than propagating the exception.