Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fix(inputs): an empty list in a {concept, content} envelope is a value, not an error (#1096)

Thomas Hebrard59a954731dbf
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c7f19fd9..a1181a4f0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [Unreleased]
+
+### Fixed
+
+- **A `{concept, content}` envelope carrying an empty list is now a value, not an error**: a plural slot is never _absent_ — when nothing is found it is the empty list — and the top-down shaper has always honoured that for a bare `[]` (D2). The bottom-up factory did not: it infers a list's item type from the first item, so an empty list raised _"Cannot create Stuff from empty list in content"_. The two spellings of one input therefore disagreed — a caller with no pictures could send `[]` and run, or send `{"concept": "native.Image", "content": []}` and fail — which made a plural input with nothing in it unrunnable for every caller that wraps its inputs. The envelope names the concept, so there was never anything to infer; it now builds an empty `ListContent`. Case 1.5 (a bare empty `ListContent`, no concept anywhere) still raises, and must: nothing there says what the items would have been.
+
## [v0.43.0] - 2026-08-12
### Highlights
diff --git a/docs/building-methods/pipes/provide-inputs.md b/docs/building-methods/pipes/provide-inputs.md
index f8240ce52..365916fbc 100644
--- a/docs/building-methods/pipes/provide-inputs.md
+++ b/docs/building-methods/pipes/provide-inputs.md
@@ -191,6 +191,11 @@ inputs = {
A list of content objects (`[MyConcept(...), MyConcept(...)]`) or an already-wrapped `ListContent(items=[...])` is accepted for a declared-multiple input; a `DictStuff(concept=..., content=...)` is the object form of the explicit envelope. All are compatibility-checked against the declaration.
+!!! note "Nothing to provide for a list input? Send the empty list."
+ A plural slot is never *absent* — when nothing is found, it **is** the empty list (see [Understanding Multiplicity](understanding-multiplicity.md)). So a caller with no pictures provides `"photos": []`, in either spelling — bare, or as the envelope `{"concept": "native.Image", "content": []}`. Both build an empty `ListContent` typed with the declared item concept, and a template that guards its use (`{% if photos %}`) renders nothing.
+
+ **Omitting the key is not the same thing**, and fails the run with *"missing required inputs"*: the presence markers are for singular values, and `Image[]?` is rejected outright (`optional_marker_invalid`) precisely because a plural slot has no absence to declare. See [Understanding Optionality](understanding-optionality.md).
+
!!! note "Bare numbers and booleans from strictly-typed Python"
A bare number or boolean (`"priority": 3`) is accepted at runtime, but the `PipelineInputs` protocol type does not yet admit bare scalars, so a strict static type-checker may flag it until that type is widened. If your codebase runs a type-checker, type the inputs dict as `dict[str, Any]`, or pass the value through the explicit envelope (`{"concept": "...", "content": 3}`).
diff --git a/pipelex/core/stuffs/stuff_factory.py b/pipelex/core/stuffs/stuff_factory.py
index d3ced1755..43118e3a3 100644
--- a/pipelex/core/stuffs/stuff_factory.py
+++ b/pipelex/core/stuffs/stuff_factory.py
@@ -617,8 +617,20 @@ class StuffFactory:
if isinstance(content, list):
list_content_2 = cast("list[Any]", content)
if len(list_content_2) == 0:
- msg = "Cannot create Stuff from empty list in content"
- raise StuffFactoryError(msg)
+ # Case 2.7: the empty list is a VALUE, not a failure. Every arm below infers the
+ # item type from `first_item`, which an empty list has none of — but here it does
+ # not have to: the envelope NAMES the concept, so the items' type is already
+ # known. This is the same verdict the top-down shaper reaches for a bare `[]`
+ # under a plural slot (D2, "an empty list is legal and yields an empty
+ # ListContent"); refusing it here made the two spellings of one input disagree.
+ # Case 1.5 keeps raising, and must: with no concept key there is nothing to infer
+ # an empty list's type from.
+ return cls.make_stuff(
+ concept=concept,
+ content=ListContent[StuffContent](items=[]),
+ name=name,
+ code=code,
+ )
first_item = list_content_2[0]
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py b/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py
index f037de9d7..c120d20c1 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py
@@ -1,4 +1,5 @@
import datetime
+from typing import Any
import pytest
@@ -175,3 +176,44 @@ class TestInputShaperExplicitForms:
pretty_print(stuff, title="collision rule")
assert stuff.concept.concept_ref == "shaper_test.ShaperWeird"
assert stuff.content == ShaperWeird(concept="x", content="y")
+
+ def test_envelope_empty_list_yields_empty_list_content(self) -> None:
+ """An envelope carrying an empty list builds an empty ListContent, like the bare `[]` does.
+
+ Regression: this raised "Cannot create Stuff from empty list in content". The bottom-up
+ factory infers a list's item type from its first item, and an empty list has none — but
+ with an envelope it never needed to infer, because the envelope NAMES the concept. The
+ result was that the two spellings of one input disagreed: a caller with no pictures could
+ send `[]` and run, or send `{"concept": ..., "content": []}` and fail.
+ """
+ input_specs = build_input_specs([("pics", "native.Image", True)])
+ provided: dict[str, Any] = {"concept": "native.Image", "content": []}
+
+ working_memory = InputShaper.shape({"pics": provided}, input_specs=input_specs, concept_provider=get_concept_library())
+
+ stuff = working_memory.root["pics"]
+ pretty_print(stuff, title="envelope empty list")
+ assert stuff.concept.concept_ref == "native.Image"
+ assert stuff.content == ListContent(items=[])
+
+ def test_envelope_and_bare_empty_list_agree(self) -> None:
+ """The two spellings of "a plural input with nothing in it" must produce the same Stuff content."""
+ input_specs = build_input_specs([("pics", "native.Image", True)])
+
+ envelope: dict[str, Any] = {"concept": "native.Image", "content": []}
+ via_envelope = InputShaper.shape({"pics": envelope}, input_specs=input_specs, concept_provider=get_concept_library())
+ via_bare = InputShaper.shape({"pics": []}, input_specs=input_specs, concept_provider=get_concept_library())
+
+ assert via_envelope.root["pics"].content == via_bare.root["pics"].content
+ assert via_envelope.root["pics"].concept.concept_ref == via_bare.root["pics"].concept.concept_ref
+
+ def test_envelope_empty_list_under_structured_concept(self) -> None:
+ """Not just natives: a structured concept's empty list is equally representable."""
+ input_specs = build_input_specs([("questions", "shaper_test.Question", True)])
+ provided: dict[str, Any] = {"concept": "shaper_test.Question", "content": []}
+
+ working_memory = InputShaper.shape({"questions": provided}, input_specs=input_specs, concept_provider=get_concept_library())
+
+ stuff = working_memory.root["questions"]
+ assert stuff.concept.concept_ref == "shaper_test.Question"
+ assert stuff.content == ListContent(items=[])
diff --git a/tests/unit/pipelex/core/stuffs/test_stuff_factory_empty_list.py b/tests/unit/pipelex/core/stuffs/test_stuff_factory_empty_list.py
new file mode 100644
index 000000000..567657a60
--- /dev/null
+++ b/tests/unit/pipelex/core/stuffs/test_stuff_factory_empty_list.py
@@ -0,0 +1,88 @@
+"""The empty list at the bottom-up factory: a value when the concept is known, an error when it is not.
+
+A plural slot is never *absent* in MTHDS — when nothing is found, it is the empty list. The
+top-down shaper has always honoured that for a bare `[]` (D2). This module pins the same verdict
+for the `{concept, content}` envelope, and pins the one case that must still fail: a bare empty
+list with no concept anywhere, whose item type is genuinely unknowable.
+"""
+
+from pathlib import Path
+from typing import Callable, cast
+
+import pytest
+
+from pipelex import pretty_print
+from pipelex.core.stuffs.exceptions import StuffFactoryError
+from pipelex.core.stuffs.list_content import ListContent
+from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.core.stuffs.stuff_factory import StuffFactory
+from pipelex.interpreter_hub import get_concept_library
+
+
[email protected](scope="class")
+def empty_list_library(load_test_library: Callable[[list[Path]], None]):
+ load_test_library([Path(__file__).parent])
+
+
[email protected]("empty_list_library")
+class TestStuffFactoryEmptyList:
+ @pytest.mark.parametrize("concept_ref", ["native.Image", "native.Text", "native.Document"])
+ def test_envelope_empty_list_builds_empty_list_content(self, concept_ref: str) -> None:
+ """Case 2.7: the envelope names the concept, so an empty list needs no item-type inference.
+
+ Regression: this raised "Cannot create Stuff from empty list in content", which made a
+ plural input with nothing in it unrunnable through the envelope spelling.
+ """
+ result = StuffFactory.make_stuff_from_stuff_content_or_data(
+ stuff_content_or_data={"concept": concept_ref, "content": []},
+ concept_provider=get_concept_library(),
+ name="pics",
+ )
+
+ pretty_print(result, title=f"empty list under {concept_ref}")
+ assert result.concept.concept_ref == concept_ref
+ assert result.content == ListContent(items=[])
+ assert result.stuff_name == "pics"
+
+ def test_empty_list_content_is_falsy_and_iterates_zero_times(self) -> None:
+ """What makes the empty ListContent safe downstream: a template guard sees it as empty.
+
+ `{% if pics %}` must not render a heading over an empty gallery, and `{% for %}` must
+ produce nothing — so a method written for "pictures when there are pictures" behaves.
+ """
+ result = StuffFactory.make_stuff_from_stuff_content_or_data(
+ stuff_content_or_data={"concept": "native.Image", "content": []},
+ concept_provider=get_concept_library(),
+ name="pics",
+ )
+
+ content = cast("ListContent[StuffContent]", result.content)
+ assert isinstance(content, ListContent)
+ assert not content
+ assert len(content) == 0
+ assert list(content) == []
+
+ def test_bare_empty_list_without_concept_still_raises(self) -> None:
+ """Case 1.5 must keep failing: with no concept there is nothing to infer an item type from.
+
+ This is the boundary of the fix — the envelope carries the answer, a naked list does not.
+ """
+ with pytest.raises(StuffFactoryError, match="empty"):
+ StuffFactory.make_stuff_from_stuff_content_or_data(
+ stuff_content_or_data=ListContent[StuffContent](items=[]),
+ concept_provider=get_concept_library(),
+ name="pics",
+ )
+
+ def test_non_empty_envelope_list_is_unaffected(self) -> None:
+ """The populated path keeps inferring from the first item exactly as before."""
+ result = StuffFactory.make_stuff_from_stuff_content_or_data(
+ stuff_content_or_data={"concept": "native.Text", "content": ["a", "b"]},
+ concept_provider=get_concept_library(),
+ name="notes",
+ )
+
+ assert result.concept.concept_ref == "native.Text"
+ content = cast("ListContent[StuffContent]", result.content)
+ assert isinstance(content, ListContent)
+ assert len(content) == 2