From a160b45504bc47799544a69065f6291b3f93b074 Mon Sep 17 00:00:00 2001 From: saivedant169 Date: Tue, 7 Apr 2026 21:47:03 -0400 Subject: [PATCH 1/4] docs: clarify auto-variadic socket input ordering in connect() Document the input ordering behavior of auto-promoted lazy variadic sockets in Pipeline.connect() and PipelineBase._make_socket_auto_variadic(). When multiple senders are connected to the same list-typed receiver socket, the items in the resulting list are ordered alphabetically by sender component name (because Pipeline.run() schedules components in alphabetical order for deterministic execution), not by the order in which connect() was called. The docstrings now point users to a dedicated joiner component when they need explicit ordering. fixes #10979 --- haystack/core/pipeline/base.py | 16 ++++++++++++++++ ...variadic-input-ordering-530d8feee4a1b900.yaml | 10 ++++++++++ 2 files changed, 26 insertions(+) create mode 100644 releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml diff --git a/haystack/core/pipeline/base.py b/haystack/core/pipeline/base.py index d691780d54..1db96f8bde 100644 --- a/haystack/core/pipeline/base.py +++ b/haystack/core/pipeline/base.py @@ -446,6 +446,13 @@ def connect(self, sender: str, receiver: str) -> "PipelineBase": # noqa: PLR091 If connecting to a component that has several output connections, specify the inputs and output names as 'component_name.connections_name'. + When multiple senders are connected to the same list-typed receiver socket, the socket is + automatically promoted to a lazy-variadic socket so it can accept all of them. The items + in the resulting list are ordered by sender component name (alphabetically), not by the + order in which ``connect()`` was called. If your downstream component depends on a specific + input order, use a dedicated joiner component (for example ``DocumentJoiner``) that lets + you control ordering explicitly. + :param sender: The component that delivers the value. This can be either just a component name or can be in the format `component_name.connection_name` if the component has multiple outputs. @@ -956,6 +963,15 @@ def _make_socket_auto_variadic( When auto-variadicity is applied, `wrap_input_in_list` is also set to False so that sender output types match the receiver socket's declared list type directly. + .. note:: + When multiple senders are connected to the same auto-variadic socket, the items + in the resulting list are ordered by sender component name (alphabetically), not by + the order in which the connections were declared via ``connect()``. This is because + ``Pipeline.run()`` schedules components in alphabetical order so that execution is + deterministic and independent of pipeline insertion order. If your downstream + component is sensitive to the input order, consider using a dedicated joiner + component that lets you control ordering explicitly. + :param component_name: Name of the component owning the receiver socket, used in error messages. :param receiver_socket: diff --git a/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml b/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml new file mode 100644 index 0000000000..4e56823e7b --- /dev/null +++ b/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml @@ -0,0 +1,10 @@ +--- +enhancements: + - | + Document the input ordering behavior of auto-promoted lazy variadic sockets in + ``Pipeline.connect()`` and ``PipelineBase._make_socket_auto_variadic()``. When + multiple senders are connected to the same list-typed receiver socket, the items + in the resulting list are ordered alphabetically by sender component name (because + ``Pipeline.run()`` schedules components in alphabetical order for deterministic + execution), not by the order in which ``connect()`` was called. The docstrings now + point users to a dedicated joiner component when they need explicit ordering. From b390210b50aac6469b4553d2edfea387037414bf Mon Sep 17 00:00:00 2001 From: saivedant169 Date: Tue, 14 Apr 2026 21:46:22 -0400 Subject: [PATCH 2/4] docs: clarify Pipeline vs AsyncPipeline variadic ordering Applied sjrl's review feedback. The previous text was wrong about DocumentJoiner (it behaves the same as a promoted variadic socket) and it missed the difference between Pipeline and AsyncPipeline. Pipeline schedules components alphabetically, so the resulting list is ordered by sender name. AsyncPipeline runs branches in parallel, so ordering is not guaranteed. Updated both the connect() docstring and the _make_socket_auto_variadic note, plus the release note. --- haystack/core/pipeline/base.py | 25 +++++++++---------- ...iadic-input-ordering-530d8feee4a1b900.yaml | 12 +++++---- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/haystack/core/pipeline/base.py b/haystack/core/pipeline/base.py index 1db96f8bde..8e6bd85beb 100644 --- a/haystack/core/pipeline/base.py +++ b/haystack/core/pipeline/base.py @@ -446,12 +446,11 @@ def connect(self, sender: str, receiver: str) -> "PipelineBase": # noqa: PLR091 If connecting to a component that has several output connections, specify the inputs and output names as 'component_name.connections_name'. - When multiple senders are connected to the same list-typed receiver socket, the socket is - automatically promoted to a lazy-variadic socket so it can accept all of them. The items - in the resulting list are ordered by sender component name (alphabetically), not by the - order in which ``connect()`` was called. If your downstream component depends on a specific - input order, use a dedicated joiner component (for example ``DocumentJoiner``) that lets - you control ordering explicitly. + If multiple senders are connected to the same list-typed receiver socket, the socket is + promoted to a lazy variadic socket so it can accept all incoming values. With ``Pipeline``, + the resulting list is ordered alphabetically by sender component name, not by the order in + which ``connect()`` was called. With ``AsyncPipeline``, no ordering is guaranteed, since + components in different branches may run in parallel. :param sender: The component that delivers the value. This can be either just a component name or can be @@ -964,13 +963,13 @@ def _make_socket_auto_variadic( the receiver socket's declared list type directly. .. note:: - When multiple senders are connected to the same auto-variadic socket, the items - in the resulting list are ordered by sender component name (alphabetically), not by - the order in which the connections were declared via ``connect()``. This is because - ``Pipeline.run()`` schedules components in alphabetical order so that execution is - deterministic and independent of pipeline insertion order. If your downstream - component is sensitive to the input order, consider using a dedicated joiner - component that lets you control ordering explicitly. + When multiple senders are connected to the same auto-variadic socket, ordering + depends on the pipeline class. ``Pipeline.run()`` schedules components + alphabetically by name, so the resulting list is ordered alphabetically by sender + name rather than by the order of ``connect()`` calls. ``AsyncPipeline`` does not + guarantee any ordering, since components in different branches may run in parallel. + If your downstream component is sensitive to input order, consider using a + dedicated joiner component that lets you control ordering explicitly. :param component_name: Name of the component owning the receiver socket, used in error messages. diff --git a/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml b/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml index 4e56823e7b..0877a70ab9 100644 --- a/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml +++ b/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml @@ -3,8 +3,10 @@ enhancements: - | Document the input ordering behavior of auto-promoted lazy variadic sockets in ``Pipeline.connect()`` and ``PipelineBase._make_socket_auto_variadic()``. When - multiple senders are connected to the same list-typed receiver socket, the items - in the resulting list are ordered alphabetically by sender component name (because - ``Pipeline.run()`` schedules components in alphabetical order for deterministic - execution), not by the order in which ``connect()`` was called. The docstrings now - point users to a dedicated joiner component when they need explicit ordering. + multiple senders are connected to the same list-typed receiver socket, ordering + depends on the pipeline class. With ``Pipeline``, items are ordered alphabetically + by sender component name (because ``Pipeline.run()`` schedules components in + alphabetical order for deterministic execution), not by the order of ``connect()`` + calls. With ``AsyncPipeline``, no ordering is guaranteed, since components in + different branches may run in parallel. The docstrings now point users to a + dedicated joiner component when they need explicit ordering. From 6a9065ff93caa8f2a4e59e2f717658acf3f2c64e Mon Sep 17 00:00:00 2001 From: saivedant169 Date: Mon, 20 Apr 2026 11:45:26 -0400 Subject: [PATCH 3/4] docs: apply review feedback on connect() variadic docstring Switch the inline literals from double to single backticks so they match how the rest of our api docstrings are written. Double backticks belong in the release notes, not here. Also drop the note block from the private _make_socket_auto_variadic helper. That method is not exposed on the docs site, so the extra context does not buy users anything. The public-facing explanation on connect() is enough. --- haystack/core/pipeline/base.py | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/haystack/core/pipeline/base.py b/haystack/core/pipeline/base.py index 8e6bd85beb..80e601ae4e 100644 --- a/haystack/core/pipeline/base.py +++ b/haystack/core/pipeline/base.py @@ -447,9 +447,9 @@ def connect(self, sender: str, receiver: str) -> "PipelineBase": # noqa: PLR091 'component_name.connections_name'. If multiple senders are connected to the same list-typed receiver socket, the socket is - promoted to a lazy variadic socket so it can accept all incoming values. With ``Pipeline``, + promoted to a lazy variadic socket so it can accept all incoming values. With `Pipeline`, the resulting list is ordered alphabetically by sender component name, not by the order in - which ``connect()`` was called. With ``AsyncPipeline``, no ordering is guaranteed, since + which `connect()` was called. With `AsyncPipeline`, no ordering is guaranteed, since components in different branches may run in parallel. :param sender: @@ -962,15 +962,6 @@ def _make_socket_auto_variadic( When auto-variadicity is applied, `wrap_input_in_list` is also set to False so that sender output types match the receiver socket's declared list type directly. - .. note:: - When multiple senders are connected to the same auto-variadic socket, ordering - depends on the pipeline class. ``Pipeline.run()`` schedules components - alphabetically by name, so the resulting list is ordered alphabetically by sender - name rather than by the order of ``connect()`` calls. ``AsyncPipeline`` does not - guarantee any ordering, since components in different branches may run in parallel. - If your downstream component is sensitive to input order, consider using a - dedicated joiner component that lets you control ordering explicitly. - :param component_name: Name of the component owning the receiver socket, used in error messages. :param receiver_socket: From 65b25f6c37057990cfbc2d5867f79a0ff1062324 Mon Sep 17 00:00:00 2001 From: Sebastian Husch Lee <10526848+sjrl@users.noreply.github.com> Date: Tue, 21 Apr 2026 08:44:31 +0200 Subject: [PATCH 4/4] Apply suggestion from @sjrl --- .../document-variadic-input-ordering-530d8feee4a1b900.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml b/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml index 0877a70ab9..81dc5fea51 100644 --- a/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml +++ b/releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml @@ -2,7 +2,7 @@ enhancements: - | Document the input ordering behavior of auto-promoted lazy variadic sockets in - ``Pipeline.connect()`` and ``PipelineBase._make_socket_auto_variadic()``. When + ``Pipeline.connect()``. When multiple senders are connected to the same list-typed receiver socket, ordering depends on the pipeline class. With ``Pipeline``, items are ordered alphabetically by sender component name (because ``Pipeline.run()`` schedules components in