In Haystack, what does the @component decorator require of your class?

## The three parts of the contract Writing a Haystack component is deliberately small: decorate the class with `@component`, define `run()`, and declare `run()`'s outputs with `@component.output_types(...)`. Everything else — constructor arguments, helper methods, internal state — is ordinary Python. The framework asks for exactly enough structure to know what flows in and what flows out. ``` @component class X: @component.output_types(name=type, ...) def run(self, arg: type, optional: type = default): return {"name": ...} ``` ## Inputs come from the run signature The parameters of `run()` are the component's input sockets. Their names are the socket names, their annotations are the socket types, and whether they have a default decides whether the socket is mandatory. This is why Haystack components read as ordinary functions: there is no separate input schema object to keep in sync. A consequence people miss in interviews: `__init__` arguments are *configuration*, not inputs. A retriever's `top_k` set at construction is not something another component can feed it; only `run()` parameters are connectable. Deciding which knobs belong in `__init__` and which belong in `run()` is a real design choice — anything that should vary per request has to be a `run()` parameter. ## Outputs are declared, never inferred Python cannot tell you at import time which keys a dict return will contain, so Haystack makes you say it. `@component.output_types(count=int, words=list[str])` declares two output sockets; `run()` then returns `{"count": ..., "words": ...}`. Returning a bare value, a tuple, or a dataclass is a contract violation — the return must be a dict, and its keys are the declared names. If you return a key you never declared, nothing downstream can connect to it; it is not part of the component's surface. If you declare a key and sometimes omit it from the return, any consumer of that socket receives nothing for that run, which in a pipeline shows up as a downstream component never firing. ## Why the declared types matter The declared types are not documentation. When you connect two components, Haystack compares the producing socket's type against the consuming socket's type and refuses an incompatible edge. That check runs while the pipeline is being built — before any model is loaded, any index is queried, or any token is paid for. In a framework whose selling point is that pipelines are inspectable and testable, this is the mechanism doing the work: a whole class of "the LLM got a list where it wanted a string" bugs becomes a build error. It follows that vague annotations weaken the framework. Annotating an input as `Any` will connect to anything and validate nothing. ## Dynamic sockets Some components genuinely do not know their sockets until they are constructed — a router whose branches come from a config list, a passthrough parameterised by type. For those, call `component.set_input_types(self, **types)` or `component.set_output_types(self, **types)` inside `__init__`. The decorator form is preferred whenever the shape is static, because it is visible in the source and in generated docs; the dynamic form hides the surface behind constructor logic. ## The optional lifecycle hooks Beyond the required core, a component may implement: - `warm_up()` — load models and other heavy resources, keeping construction cheap. The framework calls it before the component's first execution. - `to_dict()` / `from_dict()` — control serialization when the default init-parameter mapping cannot round-trip your arguments. - `run_async()` — an asynchronous twin of `run()` with the same sockets, used when the pipeline is driven asynchronously. None of these are required, and a component that is pure computation over JSON-friendly arguments needs none of them. ## What a strong answer adds The question is nominally "what does the decorator require", but the answer interviewers reward explains *why* the surface is declared rather than inferred: because the pipeline is a typed graph, and a typed graph can be validated, serialized to YAML, drawn, and diffed in review. Convenience frameworks infer wiring and fail at run time; Haystack asks for four lines of declaration and fails at wiring time instead. Stating that trade-off out loud is the difference between reciting a decorator and explaining a design.