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.mdindex 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### Highlightsdiff --git a/docs/building-methods/pipes/provide-inputs.md b/docs/building-methods/pipes/provide-inputs.mdindex 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.pyindex 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.pyindex 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 Anyimport 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.pynew file mode 100644index 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