Pipelines & Wiring

## The input dict `Pipeline.run()` takes one required argument: a mapping from **component name** to that component's `run()` keyword arguments. ``` pipe.run({"retriever": {"query": "what is RAG?"}, "prompt": {"question": "what is RAG?"}}) ``` The keys are exactly the names you passed to `add_component`, which is the first reason those names matter: they are the public API of your pipeline. A typo'd key is not silently ignored — the pipeline tells you it has no such component. ## Only unconnected inputs go in the dict An input socket is filled either by a connection or by you. `prompt.documents` wired from `retriever.documents` is the pipeline's job; `prompt.question` that nothing produces is yours. Passing a value for a socket that is already connected is rejected, because it would be ambiguous which value wins. This is also why the same user query often appears twice in a real RAG input dict — once for the retriever's `query` and once for the prompt builder's `question`. That duplication looks redundant and surprises newcomers, but it is the honest consequence of two components independently needing the same external value. If a **mandatory** input is neither connected nor supplied, the component never becomes runnable, and the pipeline reports that it could not execute. Inputs with defaults are optional and simply take their default. ## The flat form A flat dict — `pipe.run({"query": q})` — is also accepted. Haystack distributes each key to every component that declares a `run()` parameter of that name. It is convenient when one value feeds several components, and it is a footgun when two components happen to share a parameter name and you only meant one of them. Prefer the nested form in code you will maintain; the flat form is a demo convenience. ## Execution order You do not schedule anything. Haystack works out the order from the graph: a component runs once all of its mandatory connected inputs have arrived. Independent branches run in whatever order the scheduler picks — treat them as unordered rather than depending on a sequence. Components not reachable with the inputs you supplied (for example, the branch a router did not choose) simply do not run. ## The return value `run()` returns a dict keyed by component name, mapping to that component's output dict. By default it contains only the outputs **no other component consumed** — the graph's leaves. In a linear RAG pipeline that means you get back just the generator's output: ``` result["llm"]["replies"] ``` The filtering is deliberate: retrieved documents, embeddings and rendered prompts can be megabytes, and returning them from every run would make the result unusable as an API response. ## Getting intermediates back When you need an intermediate — to log which documents grounded an answer, to build a citations payload, to debug a bad answer — pass `include_outputs_from` with a set of component names: ``` pipe.run(data, include_outputs_from={"retriever"}) ``` Those components' outputs appear in the result alongside the leaves. Ask for what you need rather than everything: it is the difference between a compact response and shipping the whole retrieved corpus to your caller. Note this is an *output* control only — it does not change execution. ## Practical shape of a service A typical HTTP handler builds the pipeline once at startup (paying wiring validation and any model warm-up there), then per request calls `run()` with a small nested dict and reads one or two keys out of the result. Because the same pipeline object is reused across requests, keep per-request data in the input dict, never on the component instances. ## Common mistakes - Keying the input dict by socket or connection string instead of component name. - Supplying a value for a socket that is already fed by a connection. - Expecting every component's output in the result and concluding the pipeline "lost" the documents, when they were simply consumed downstream. - Assuming parallel branches execute in declaration order.