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/Binding-refusal-wording · L-261006-5c7c3d (#1409)
Louis Choquel07de484fe36b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 43b00ee35..e374986db 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -27,6 +27,7 @@- **A construct path holding nothing leaves a defaulted field to its default**: a `PipeCompose` construct field fed `{ from = "doc.note" }` where `note` holds nothing is left unset when the target field refuses `null` but has a default, so it takes that default rather than failing the composition; a target field that admits `null` still receives it.- **A model's `null` on a defaulted field is refused where it can be asked again**: the class a worker rebuilds from a structure's JSON schema keeps a defaulted field non-nullable, so a model answering `null` there is asked again rather than failing when its answer reaches the caller's class. A model answering `null` on a required `native.Anything` field is asked again in process, but across a worker boundary its schema stays open, so the step fails there.- **A field whose `Literal` lists `None` may hold nothing**: a Python class field typed `Literal["a", None]` or `object` is read as one that may hold nothing, so a binding step reading it declares a possible absence and a `PipeCompose` path holding nothing gives it `None` rather than its default.+- **Binding and batch refusals name what the author wrote**: a binding step carrying a pipe step's fields proposes the remedy that applies, a dotted `batch_over` for a dotted `from`, a plain batch for a bare name, or moving `nb_output` and `multiple_output` to a pipe step, and a sequence step's refusal of its batch or count fields names the step rather than blaming the pipe the step runs. At run time, a batch over a dotted `batch_over` names that path, never the private `_bound_` name the sequence binds it under, in its message and in the error's `variable_name`, and a value there that is not a list is refused with `PipeRunInputsError` rather than an uncaught `WorkingMemoryTypeError`.### Removeddiff --git a/pipelex/pipe_controllers/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.pyindex 86b3d9861..28429d0d0 100644--- a/pipelex/pipe_controllers/batch/pipe_batch.py+++ b/pipelex/pipe_controllers/batch/pipe_batch.py@@ -102,19 +102,22 @@ class PipeBatch(PipeController):) -> None:batch_params = pipe_run_params.batch_params or self.batch_params or BatchParams.make_default()input_list_stuff_name = batch_params.input_list_stuff_name+ # The list is named as its author wrote it, never by the private name a sequence binds a dotted `batch_over` under.+ list_label = batch_params.input_list_labelif not self.inputs.is_variable_existing(variable_name=input_list_stuff_name):- msg = f"Batch input list named '{input_list_stuff_name}' is not in PipeBatch '{self.code}' input requirements: {self.inputs}"+ input_names = ", ".join(f"'{input_name}'" for input_name in self.inputs.variables) or "none"+ msg = f"The list '{list_label}' that PipeBatch '{self.code}' batches over is not among its inputs: {input_names}."raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)if not working_memory.is_stuff_exists(input_list_stuff_name):- msg = f"Input list stuff '{input_list_stuff_name}' required by this PipeBatch '{self.code}' not found in working memory"+ msg = f"The list '{list_label}' that PipeBatch '{self.code}' batches over is not in working memory."raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)input_stuff = working_memory.get_stuff(input_list_stuff_name)if not isinstance(input_stuff.content, ListContent):msg = (- f"Input list stuff '{input_list_stuff_name}' of PipeBatch '{self.code}' must be ListContent, "- f"got {input_stuff.stuff_name or 'unnamed'} = {type(input_stuff.content)}. stuff: {input_stuff}"+ f"The value '{list_label}' that PipeBatch '{self.code}' batches over is not a list: it holds a "+ f"'{input_stuff.concept.concept_ref}', and a batch runs its pipe once per item of a list.")raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)diff --git a/pipelex/pipe_controllers/binding/binding_derivation.py b/pipelex/pipe_controllers/binding/binding_derivation.pyindex 370902af5..f1b7c9271 100644--- a/pipelex/pipe_controllers/binding/binding_derivation.py+++ b/pipelex/pipe_controllers/binding/binding_derivation.py@@ -290,7 +290,7 @@ def derive_binding(*, path: str, root: BindingRoot, resolver: ConceptWalkResolveif current_leaf_field is not None:msg = (f"Cannot bind '{path}': '{reached_path}' is {current_leaf_field.value_kind.leaf_description}, a leaf holding a plain value "- f"with no fields, so the segment '{segment_name}' cannot follow it. It has no fields."+ f"with no fields, so the segment '{segment_name}' cannot follow it.")raise BindingPathUnresolvedError(msg, path=path, failed_segment=segment_name, available_fields=[])if current_concept is None:@@ -300,13 +300,13 @@ def derive_binding(*, path: str, root: BindingRoot, resolver: ConceptWalkResolvecase ConceptShape.VALUE:msg = (f"Cannot bind '{path}': '{reached_path}' holds a '{current_concept.concept_ref}', which {current_concept.shape_reason}, "- f"so it is a leaf and the segment '{segment_name}' cannot follow it. It has no fields to walk."+ f"so it is a leaf and the segment '{segment_name}' cannot follow it.")raise BindingPathUnresolvedError(msg, path=path, failed_segment=segment_name, available_fields=[])case ConceptShape.NO_STRUCTURE:msg = (f"Cannot bind '{path}': '{reached_path}' holds a '{current_concept.concept_ref}', which {current_concept.shape_reason}, "- f"so the segment '{segment_name}' has no structure to walk. It has no fields."+ f"so the segment '{segment_name}' has no structure to walk.")raise BindingPathUnresolvedError(msg, path=path, failed_segment=segment_name, available_fields=[])case ConceptShape.STRUCTURE:diff --git a/pipelex/pipe_controllers/binding/binding_step_blueprint.py b/pipelex/pipe_controllers/binding/binding_step_blueprint.pyindex 25b91ae9f..2fa24c5a0 100644--- a/pipelex/pipe_controllers/binding/binding_step_blueprint.py+++ b/pipelex/pipe_controllers/binding/binding_step_blueprint.py@@ -24,6 +24,38 @@ PATH_GRAMMAR_DESCRIPTION = (_RESULT_GRAMMAR = f"a plain input name, a snake_case identifier matching `{SNAKE_CASE_IDENTIFIER_REGEX}`"+# The pipe-step fields a binding step may carry by mistake, by the remedy their refusal proposes.+_BATCH_FIELDS = frozenset({"batch_over", "batch_as"})+_COUNT_FIELDS = frozenset({"nb_output", "multiple_output"})+++def _joined_with_or(*, field_names: list[str]) -> str:+ """The field names quoted and joined in prose: "`a`", "`a` or `b`", "`a`, `b` or `c`"."""+ quoted_names = [f"`{field_name}`" for field_name in field_names]+ if len(quoted_names) == 1:+ return quoted_names[0]+ return f"{', '.join(quoted_names[:-1])} or {quoted_names[-1]}"+++def _batch_remedy(*, from_path: Any, result: Any) -> str:+ """How to batch over what a binding step carrying batch fields binds: a dotted `batch_over` binds a path, a plain one reads a name.++ Either way, the step can stay a binding step, the next pipe step batching over what it binds, under its own `result` when it+ carries one.+ """+ bound_name = result if isinstance(result, str) else "<name>"+ keep_binding = f'Or keep this step as `{{ from = "{from_path}", result = "{bound_name}" }}` and batch over `{bound_name}` in the next pipe step.'+ if isinstance(from_path, str) and "." in from_path:+ return (+ f'To batch over the list at `{from_path}`, write `batch_over = "{from_path}"` on the pipe step to run once per item: a dotted '+ f"`batch_over` binds the list at that path and batches over it. {keep_binding}"+ )+ return (+ f'To batch over `{from_path}`, write `batch_over = "{from_path}"` on the pipe step to run once per item: a plain `batch_over` '+ f"batches over that name and needs no binding. {keep_binding}"+ )++def is_binding_step_dict(*, raw_step: Mapping[str, Any]) -> bool:"""Whether a step, as written, is a binding step: it carries `from`."""return BINDING_FROM_KEY in raw_step@@ -50,12 +82,17 @@ def check_binding_step_shape(*, raw_step: Mapping[str, Any], step_label: str) ->raise PipeValidationError(message=msg, error_type=PipeValidationErrorType.BINDING_STEP_INVALID)pipe_step_fields = [field_name for field_name in PIPE_STEP_ONLY_FIELDS if field_name in raw_step]if pipe_step_fields:- quoted_fields = ", ".join(f"`{field_name}`" for field_name in pipe_step_fields)msg = (- f"{step_label} is a binding step (it carries `from`), which carries only `from` and `result`, so it cannot carry {quoted_fields}. "- f'To batch over the list at `{from_path}`, write it as a pipe step\'s `batch_over = "{from_path}"`, which binds it and batches over '- "the bound list, or bind it first, then batch over the bound name in the next pipe step."+ f"{step_label} is a binding step (it carries `from`), which carries only `from` and `result`, so it cannot carry "+ f"{_joined_with_or(field_names=pipe_step_fields)}.")+ if any(field_name in _BATCH_FIELDS for field_name in pipe_step_fields):+ msg += f" {_batch_remedy(from_path=from_path, result=raw_step.get('result'))}"+ if any(field_name in _COUNT_FIELDS for field_name in pipe_step_fields):+ msg += (+ " `nb_output` and `multiple_output` set how many outputs a pipe produces, so they go on the pipe step running that pipe: "+ "a binding step binds the value as it is."+ )raise PipeValidationError(message=msg, error_type=PipeValidationErrorType.BINDING_STEP_INVALID)if "result" not in raw_step:msg = f"{step_label} is a binding step without `result`: a binding step names the value it binds, so `result` is required."diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence.py b/pipelex/pipe_controllers/sequence/pipe_sequence.pyindex 4990fbc13..cc78c3b03 100644--- a/pipelex/pipe_controllers/sequence/pipe_sequence.py+++ b/pipelex/pipe_controllers/sequence/pipe_sequence.py@@ -681,6 +681,8 @@ class PipeSequence(PipeController):"""last_step = self.sequential_sub_pipes[-1]last_step_concept: Concept+ # How the messages below name the last step after "the last step", each form carrying its own leading separator: a binding+ # step as written is an appositive, set off by commas, while a pipe step's code is a plain name.last_step_label: stris_last_step_output_optional: booleffective_last_step_output_multiplicity: VariableMultiplicity | None@@ -693,7 +695,7 @@ class PipeSequence(PipeController):self._refuse_escaping_absence(taint_analysis=self._analyze_taint(visited_pipes=None, typed_flow=typed_flow))returnlast_step_concept = binding_spec.concept- last_step_label = f"the {last_step.label}"+ last_step_label = f", the {last_step.label},"# A binding's own maybe-absence is the taint pass's to report, as its result's taint.is_last_step_output_optional = Falseeffective_last_step_output_multiplicity = binding_spec.multiplicity@@ -704,7 +706,7 @@ class PipeSequence(PipeController):returnlast_step_pipe = get_required_pipe(pipe_code=last_step_pipe_code)last_step_concept = last_step_pipe.output.concept- last_step_label = f"'{last_step_pipe.code}'"+ last_step_label = f" '{last_step_pipe.code}'"# What the step stores under its result, resolved exactly the way the run path and the typed flow resolve it# (`SubPipe.result_spec`): the pipe's declared multiplicity with the step's `nb_output` or `multiple_output`# override, or, for a batched step, the variable list of its branches' results, whatever count it asks for.@@ -737,7 +739,7 @@ class PipeSequence(PipeController):if not get_concept_library().is_compatible(tested_concept=last_step_concept, wanted_concept=self.output.concept):msg = (f"PipeSequence concept mismatch: the output concept '{last_step_concept.concept_ref}' "- f"of the last step {last_step_label} of sequence pipe '{self.code}' "+ f"of the last step{last_step_label} of sequence pipe '{self.code}' "f"is not compatible with the output concept '{self.output.concept.concept_ref}' of the sequence.")raise PipeValidationError(@@ -758,7 +760,7 @@ class PipeSequence(PipeController):declared_output_ref = self.output.to_bundle_representation(relative_to_domain=self.domain_code)msg = (f"PipeSequence output multiplicity mismatch: the sequence '{self.code}' declares its output as "- f"'{declared_output_ref}', but its last step {last_step_label} yields '{expected_output_ref}'. "+ f"'{declared_output_ref}', but its last step{last_step_label} yields '{expected_output_ref}'. "f"Update the sequence's output to '{expected_output_ref}' (or change the last step).")raise PipeValidationError(diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py b/pipelex/pipe_controllers/sequence/pipe_sequence_factory.pyindex 73274db6c..d83cab657 100644--- a/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py+++ b/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py@@ -61,13 +61,16 @@ class PipeSequenceFactory(PipeFactoryProtocol[PipeSequenceBlueprint, PipeSequencsequential_sub_pipes.append(BindingStep(from_path=step.from_path, output_name=step.result))continuepipe_step = step+ batch_over_path: str | None = Noneif step.batch_over is not None and is_dotted_batch_over(batch_over=step.batch_over):- private_name = make_private_binding_name(path=step.batch_over, taken_names=taken_names)+ batch_over_path = step.batch_over+ private_name = make_private_binding_name(path=batch_over_path, taken_names=taken_names)taken_names.add(private_name)- sequential_sub_pipes.append(BindingStep(from_path=step.batch_over, output_name=private_name, is_dotted_batch_over=True))- # A copy, never validated again: the private name is the runtime's own, outside the names an author writes.+ sequential_sub_pipes.append(BindingStep(from_path=batch_over_path, output_name=private_name, is_dotted_batch_over=True))+ # A copy, never validated again: the private name is the runtime's own, outside the names an author writes. The batch+ # keeps the path, so its refusals name the `batch_over` the author wrote.pipe_step = step.model_copy(update={"batch_over": private_name})- sequential_sub_pipes.append(SubPipeFactory.make_from_blueprint(blueprint=pipe_step))+ sequential_sub_pipes.append(SubPipeFactory.make_from_blueprint(blueprint=pipe_step, batch_over_path=batch_over_path))return PipeSequence(domain_code=domain_code,diff --git a/pipelex/pipe_controllers/sub_pipe.py b/pipelex/pipe_controllers/sub_pipe.pyindex 0bfb208e2..15c5e2bd5 100644--- a/pipelex/pipe_controllers/sub_pipe.py+++ b/pipelex/pipe_controllers/sub_pipe.py@@ -2,7 +2,7 @@ from typing import TYPE_CHECKINGfrom pydantic import BaseModel, field_validator-from pipelex.core.memory.exceptions import WorkingMemoryStuffNotFoundError+from pipelex.core.memory.exceptions import WorkingMemoryStuffNotFoundError, WorkingMemoryTypeErrorfrom pipelex.core.memory.working_memory import WorkingMemoryfrom pipelex.core.pipes.inputs.exceptions import InputStuffSpecNotFoundError, PipeRunInputsErrorfrom pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs@@ -89,18 +89,33 @@ class SubPipe(BaseModel):if batch_params := self.batch_params:sub_pipe_run_params.batch_params = batch_params+ # The list is named as its author wrote it: a dotted `batch_over` is stored under a private name, which the messages of+ # the working memory's own errors would name, so neither is quoted here.+ list_label = batch_params.input_list_labeltry:working_memory.get_typed_object_or_attribute(name=batch_params.input_list_stuff_name, wanted_type=ListContent)except WorkingMemoryStuffNotFoundError as exc:msg = (- f"Input list stuff named '{batch_params.input_list_stuff_name}' required by sub_pipe '{self.pipe_code}' "- f"of pipe '{calling_pipe_code}' not found in working memory: {exc}"+ f"The list '{list_label}' that the step running pipe '{self.pipe_code}' of pipe '{calling_pipe_code}' batches over "+ "is not in working memory.")raise PipeRunInputsError(message=msg,run_mode=sub_pipe_run_params.run_mode,pipe_code=self.pipe_code,- variable_name=batch_params.input_list_stuff_name,+ variable_name=list_label,+ concept_code=None,+ ) from exc+ except WorkingMemoryTypeError as exc:+ msg = (+ f"The value '{list_label}' that the step running pipe '{self.pipe_code}' of pipe '{calling_pipe_code}' batches over "+ "is not a list: a batch runs its pipe once per item of a list."+ )+ raise PipeRunInputsError(+ message=msg,+ run_mode=sub_pipe_run_params.run_mode,+ pipe_code=self.pipe_code,+ variable_name=list_label,concept_code=None,) from excdiff --git a/pipelex/pipe_controllers/sub_pipe_blueprint.py b/pipelex/pipe_controllers/sub_pipe_blueprint.pyindex f5b7e934d..c39a8a2aa 100644--- a/pipelex/pipe_controllers/sub_pipe_blueprint.py+++ b/pipelex/pipe_controllers/sub_pipe_blueprint.py@@ -25,29 +25,41 @@ class SubPipeBlueprint(BaseModel):batch_over: str | None = Nonebatch_as: str | None = None+ # Every refusal below names the step by the pipe it runs: the faulty fields are the step's, held by the sequence or the+ # parallel that the error locates, not the pipe's, and the blueprint does not know the code of the pipe holding it.+ @property+ def step_label(self) -> str:+ """How a message names the step, after "the": the step by the pipe it runs."""+ return f"step running pipe '{self.pipe}'"+@model_validator(mode="after")def validate_multiple_output(self) -> Self:if has_more_than_one_among_attributes_from_list(self, attributes_list=["nb_output", "multiple_output"]):- msg = "PipeStepBlueprint should have no more than '1' of nb_output or multiple_output"+ msg = f"The {self.step_label} carries both `nb_output` and `multiple_output`: a step sets at most one of them."raise ValueError(msg)return self@model_validator(mode="after")def validate_batch_params(self) -> Self:if self.batch_over and not self.batch_as:- msg = f"In pipe '{self.pipe}': When 'batch_over' is specified, 'batch_as' must also be provided"+ msg = (+ f"The {self.step_label} carries `batch_over` without `batch_as`: a step batching over a list hands each item to its pipe "+ "under the name `batch_as` gives it."+ )raise ValueError(msg)if self.batch_as and not self.batch_over:- msg = f"In pipe '{self.pipe}': When 'batch_as' is specified, 'batch_over' must also be provided"+ msg = (+ f"The {self.step_label} carries `batch_as` without `batch_over`: `batch_as` names each item of the list a step batches over, "+ "and `batch_over` names that list."+ )raise ValueError(msg)if self.batch_over and self.batch_as and self.batch_over == self.batch_as:msg = (- f"In pipe '{self.pipe}': 'batch_as' ('{self.batch_as}') must not be the same as "- f"'batch_over' ('{self.batch_over}'). "- f"Use a plural for batch_over and the singular form for batch_as "- f"(e.g., batch_over='items', batch_as='item')."+ f"The `batch_as` of the {self.step_label} is '{self.batch_as}', the same name as its `batch_over`: each item needs a name "+ 'of its own. Use a plural for `batch_over` and its singular for `batch_as`, such as `batch_over = "items"` and '+ '`batch_as = "item"`.')raise PipeValidationError(message=msg,@@ -62,7 +74,7 @@ class SubPipeBlueprint(BaseModel):if self.batch_over is None or not is_dotted_batch_over(batch_over=self.batch_over) or is_field_path(path=self.batch_over):return selfmsg = (- f"In pipe '{self.pipe}': the dotted `batch_over` '{self.batch_over}' is not a path. A dotted `batch_over` binds the list "+ f"The dotted `batch_over` '{self.batch_over}' of the {self.step_label} is not a path. A dotted `batch_over` binds the list "f"at its path, as a binding step's `from` does, and a path is {PATH_GRAMMAR_DESCRIPTION}.")raise PipeValidationError(message=msg, error_type=PipeValidationErrorType.BINDING_STEP_INVALID, variable_names=[self.batch_over])@@ -80,7 +92,7 @@ class SubPipeBlueprint(BaseModel):"""for field_name, name in (("result", self.result), ("batch_as", self.batch_as)):if name is not None:- check_stored_name(name=name, field_label=f"The `{field_name}` of the step running pipe '{self.pipe}'")+ check_stored_name(name=name, field_label=f"The `{field_name}` of the {self.step_label}")if self.batch_over is not None:- check_name_is_not_reserved(name=self.batch_over, field_label=f"The `batch_over` of the step running pipe '{self.pipe}'")+ check_name_is_not_reserved(name=self.batch_over, field_label=f"The `batch_over` of the {self.step_label}")return selfdiff --git a/pipelex/pipe_controllers/sub_pipe_factory.py b/pipelex/pipe_controllers/sub_pipe_factory.pyindex 6ec70b66e..1607f72c5 100644--- a/pipelex/pipe_controllers/sub_pipe_factory.py+++ b/pipelex/pipe_controllers/sub_pipe_factory.py@@ -13,8 +13,16 @@ class SubPipeFactory:def make_from_blueprint(cls,blueprint: SubPipeBlueprint,+ *,+ batch_over_path: str | None = None,) -> SubPipe:- """Create a SubPipe from a SubPipeBlueprint."""+ """Create a SubPipe from a SubPipeBlueprint.++ Args:+ blueprint: The step, its `batch_over` a name in working memory.+ batch_over_path: The dotted `batch_over` its author wrote, when a PipeSequence rewrote it into a binding under the+ private name the blueprint now batches over, so that messages name the path rather than that name.+ """batch_params: BatchParams | None = Noneoutput_multiplicity: VariableMultiplicity | None = None@@ -22,6 +30,7 @@ class SubPipeFactory:batch_params = BatchParams.make_batch_params(input_list_name=blueprint.batch_over,input_item_name=blueprint.batch_as,+ batch_over_path=batch_over_path,)output_multiplicity = Trueif blueprint.nb_output:diff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.pyindex 0ee76ee47..54cf26ca3 100644--- a/pipelex/pipe_run/pipe_run_params.py+++ b/pipelex/pipe_run/pipe_run_params.py@@ -119,6 +119,14 @@ def output_multiplicity_to_apply(class BatchParams(BaseModel):input_list_stuff_name: strinput_item_stuff_name: str+ # The dotted `batch_over` its author wrote, when a PipeSequence bound the list at that path under a private name, which+ # `input_list_stuff_name` then holds; `None` when the list name is the author's own.+ batch_over_path: str | None = None++ @property+ def input_list_label(self) -> str:+ """How a message names the list: the path its author wrote, never the private name a sequence bound it under."""+ return self.batch_over_path or self.input_list_stuff_name@classmethoddef make_batch_params(@@ -126,10 +134,12 @@ class BatchParams(BaseModel):*,input_list_name: str,input_item_name: str,+ batch_over_path: str | None = None,) -> BatchParams:return BatchParams(input_list_stuff_name=input_list_name,input_item_stuff_name=input_item_name,+ batch_over_path=batch_over_path,)@classmethoddiff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_binding_typed_flow.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_binding_typed_flow.pyindex ffa6eccfd..f77535c46 100644--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_binding_typed_flow.py+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_binding_typed_flow.py@@ -646,7 +646,7 @@ class TestBindingTypedFlow:),pytest.param("invalid_inadequate_output_multiplicity_binding",- ["page_views"],+ ['its last step, the binding step { from = "pages.page_view", result = "page_views" }, yields'],id="I17-plural-into-singular",),pytest.param(@@ -706,6 +706,51 @@ class TestBindingTypedFlow:_load_sequence(mthds_content=mthds_content, library_id=load_empty_library(), pipe_code="read_totals")+ @pytest.mark.parametrize(+ ("output", "from_path", "error_type", "message_fragment"),+ [+ pytest.param(+ "Text",+ "invoice.total",+ PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,+ 'the output concept \'native.Number\' of the last step, the binding step { from = "invoice.total", result = "bound" }, '+ "of sequence pipe 'read_bound'",+ id="another-concept",+ ),+ pytest.param(+ "Number",+ "invoice.amounts",+ PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,+ 'its last step, the binding step { from = "invoice.amounts", result = "bound" }, yields \'Number[]\'',+ id="another-multiplicity",+ ),+ ],+ )+ def test_a_final_binding_the_output_refuses_is_set_off_by_commas(+ self,+ load_empty_library: Callable[[], str],+ output: str,+ from_path: str,+ error_type: PipeValidationErrorType,+ message_fragment: str,+ ) -> None:+ """The binding step as written is an appositive of "the last step", where a pipe step's code is a plain name after it."""+ mthds_content = (+ f"{_CALLED_BINDING_BUNDLE}\n"+ "[pipe.read_bound]\n"+ 'type = "PipeSequence"\n'+ 'description = "Binds a value of an invoice that the output does not promise"\n'+ 'inputs = { invoice = "Invoice" }\n'+ f'output = "{output}"\n'+ f'steps = [{{ from = "{from_path}", result = "bound" }}]\n'+ )++ with pytest.raises(PipeValidationError) as exc_info:+ _load_sequence(mthds_content=mthds_content, library_id=load_empty_library(), pipe_code="read_bound")++ assert exc_info.value.error_type == error_type+ assert message_fragment in str(exc_info.value)+@pytest.mark.asyncio(loop_scope="class")async def test_a_single_binding_over_a_root_the_run_made_a_list_is_a_run_error(self) -> None:"""Regression: a count asked of the whole run reaches the sequence's own steps, so the step typed as writing one invoicediff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_dotted_batch_over.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_dotted_batch_over.pyindex 656cc8087..e26ee9a58 100644--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_dotted_batch_over.py+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_dotted_batch_over.py@@ -7,12 +7,18 @@ from pydantic import ValidationErrorfrom pytest_mock import MockerFixturefrom pipelex.config import get_config+from pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.working_memory import PRIVATE_BINDING_NAME_PREFIX, WorkingMemory-from pipelex.core.pipes.exceptions import PipeValidationError+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory+from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError+from pipelex.core.pipes.inputs.exceptions import PipeRunInputsError+from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs+from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec+from pipelex.core.stuffs.stuff_factory import StuffFactoryfrom pipelex.core.stuffs.text_content import TextContentfrom pipelex.graph.graph_tracer import GraphTracerfrom pipelex.graph.graphspec import EdgeKind, GraphSpec, NodeKind, NodeSpec-from pipelex.interpreter_hub import get_library_manager+from pipelex.interpreter_hub import get_library_manager, get_native_conceptfrom pipelex.mthds_parsing.exceptions import MthdsParserErrorfrom pipelex.mthds_parsing.parser import MthdsParserfrom pipelex.pipe_controllers.batch.pipe_batch import PipeBatch@@ -23,9 +29,11 @@ from pipelex.pipe_machinery.pipe_abstract import PipeAbstractfrom pipelex.pipe_run.pipe_job import PipeJobfrom pipelex.pipe_run.pipe_job_factory import PipeJobFactoryfrom pipelex.pipe_run.pipe_run_params import BatchParams+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactoryfrom pipelex.pipeline.pipeline_response import PipelexRunResultExecutefrom pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.runtime_hub import scoped_event_log+from pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.tracing.in_memory_event_log import InMemoryEventLogfrom pipelex.validation_error_types import PipeValidationErrorType@@ -178,6 +186,20 @@ def _load_sequence(*, mthds_content: str, library_id: str, pipe_code: str) -> Pireturn sequences[0]+def _make_pipe_batch(*, input_names: list[str], batch_params: BatchParams) -> PipeBatch:+ """A batch built as `SubPipe.run_pipe` builds one, its inputs these names, each of a text."""+ text_concept = get_native_concept(NativeConceptCode.TEXT)+ return PipeBatch(+ domain_code="catalog_index",+ code="write_index_line_batch",+ description="Batch processing for write_index_line",+ inputs=InputStuffSpecs(root={input_name: StuffSpec(concept=text_concept) for input_name in input_names}),+ output=StuffSpec(concept=text_concept),+ branch_pipe_code="catalog_index.write_index_line",+ batch_params=batch_params,+ )++async def _index_lines(*, mthds_content: str, inputs: "PipelineInputs") -> PipelexRunResultExecute:return await PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.LIVE).execute(mthds_contents=[mthds_content], inputs=inputs)@@ -262,8 +284,102 @@ class TestDottedBatchOver:assert pipe_step.batch_params is not Noneassert pipe_step.batch_params.input_list_stuff_name == binding_step.output_nameassert pipe_step.batch_params.input_item_stuff_name == "page"+ assert pipe_step.batch_params.batch_over_path == "catalog.pages"+ assert pipe_step.batch_params.input_list_label == "catalog.pages"assert sequence.build_typed_flow().binding_specs[0].multiplicity is True+ async def test_a_batch_over_a_name_the_author_bound_carries_no_path(self, load_empty_library: Callable[[], str]) -> None:+ sequence = _load_sequence(mthds_content=_PRODUCED_ROOT_EXPLICIT_BUNDLE, library_id=load_empty_library(), pipe_code="index_pages")++ pipe_step = sequence.sequential_sub_pipes[-1]+ assert isinstance(pipe_step, SubPipe)+ assert pipe_step.batch_params is not None+ assert pipe_step.batch_params.batch_over_path is None+ assert pipe_step.batch_params.input_list_label == "catalog_pages"++ @pytest.mark.parametrize("holds_a_single_value", [False, True], ids=["missing", "not-a-list"])+ async def test_a_step_refusing_its_bound_list_names_the_path_its_author_wrote(+ self, load_empty_library: Callable[[], str], job_metadata: JobMetadata, holds_a_single_value: bool+ ) -> None:+ """The list is stored under a private name, which the author never wrote: the refusal names the dotted `batch_over` instead."""+ sequence = _load_sequence(mthds_content=_SINGLE_ROOT_BUNDLE, library_id=load_empty_library(), pipe_code="index_pages")+ binding_step, pipe_step = sequence.sequential_sub_pipes+ assert isinstance(binding_step, BindingStep)+ assert isinstance(pipe_step, SubPipe)+ working_memory = WorkingMemoryFactory.make_empty()+ if holds_a_single_value:+ working_memory.add_new_stuff(+ name=binding_step.output_name, stuff=StuffFactory.make_from_str(str_value="Garden chairs", name=binding_step.output_name)+ )++ with pytest.raises(PipeRunInputsError) as exc_info:+ await pipe_step.run_pipe(+ calling_pipe_code="index_pages",+ working_memory=working_memory,+ job_metadata=job_metadata,+ sub_pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY),+ )++ message = str(exc_info.value)+ assert "'catalog.pages'" in message+ assert PRIVATE_BINDING_NAME_PREFIX not in message+ assert exc_info.value.variable_name == "catalog.pages"+ if holds_a_single_value:+ assert "is not a list" in message++ @pytest.mark.parametrize(+ ("input_names", "holds_a_single_value", "message_fragment"),+ [+ pytest.param(["season"], False, "is not among its inputs", id="not-among-the-inputs"),+ pytest.param([f"{PRIVATE_BINDING_NAME_PREFIX}catalog_pages"], False, "is not in working memory", id="missing"),+ pytest.param([f"{PRIVATE_BINDING_NAME_PREFIX}catalog_pages"], True, "is not a list", id="not-a-list"),+ ],+ )+ async def test_a_batch_refusing_its_bound_list_names_the_path_its_author_wrote(+ self,+ load_empty_library: Callable[[], str],+ job_metadata: JobMetadata,+ input_names: list[str],+ holds_a_single_value: bool,+ message_fragment: str,+ ) -> None:+ load_empty_library()+ private_name = f"{PRIVATE_BINDING_NAME_PREFIX}catalog_pages"+ pipe_batch = _make_pipe_batch(+ input_names=input_names,+ batch_params=BatchParams.make_batch_params(input_list_name=private_name, input_item_name="page", batch_over_path="catalog.pages"),+ )+ working_memory = WorkingMemoryFactory.make_empty()+ if holds_a_single_value:+ working_memory.add_new_stuff(name=private_name, stuff=StuffFactory.make_from_str(str_value="Garden chairs", name=private_name))++ with pytest.raises(PipeRunError) as exc_info:+ await pipe_batch._validate_before_run( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+ job_metadata=job_metadata,+ working_memory=working_memory,+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY),+ )++ message = str(exc_info.value)+ assert message_fragment in message+ assert "'catalog.pages'" in message+ assert PRIVATE_BINDING_NAME_PREFIX not in message++ async def test_a_declared_batch_names_its_own_list(self, load_empty_library: Callable[[], str], job_metadata: JobMetadata) -> None:+ load_empty_library()+ pipe_batch = _make_pipe_batch(+ input_names=["pages"], batch_params=BatchParams.make_batch_params(input_list_name="pages", input_item_name="page")+ )++ with pytest.raises(PipeRunError) as exc_info:+ await pipe_batch._validate_before_run( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+ job_metadata=job_metadata,+ working_memory=WorkingMemoryFactory.make_empty(),+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY),+ )++ assert "The list 'pages' that PipeBatch 'write_index_line_batch' batches over is not in working memory" in str(exc_info.value)+async def test_a_step_never_batches_over_a_dotted_path_itself(self) -> None:"""Only the sequence's rewrite reads a dotted path, as a binding: a step built to batch over one is refused."""with pytest.raises(ValidationError) as exc_info:diff --git a/tests/unit/pipelex/pipe_controllers/binding/test_binding_derivation_refusals.py b/tests/unit/pipelex/pipe_controllers/binding/test_binding_derivation_refusals.pyindex 5354aea19..6b88200fc 100644--- a/tests/unit/pipelex/pipe_controllers/binding/test_binding_derivation_refusals.py+++ b/tests/unit/pipelex/pipe_controllers/binding/test_binding_derivation_refusals.py@@ -58,6 +58,27 @@ class TestBindingDerivationRefusals:assert message_fragment in str(raised.value)assert f"'{failed_segment}'" in str(raised.value)+ @pytest.mark.parametrize(+ ("path", "root", "closing_clause"),+ [+ pytest.param("invoice.total.amount", INVOICE, "so the segment 'amount' cannot follow it.", id="past-a-plain-field"),+ pytest.param("invoice.metadata.code", INVOICE, "so the segment 'code' cannot follow it.", id="past-a-dict-field"),+ pytest.param(+ "note.text", make_root("native.Text"), "so it is a leaf and the segment 'text' cannot follow it.", id="into-a-single-field-native"+ ),+ pytest.param("anything.name", make_root("native.Anything"), "so the segment 'name' has no structure to walk.", id="into-no-structure"),+ ],+ )+ def test_a_leaf_refusal_ends_at_its_clause(self, path: str, root: BindingRoot, closing_clause: str):+ """The clause already says the value has no fields to walk, so no sentence after it says so again."""+ with pytest.raises(BindingPathUnresolvedError) as raised:+ derive_binding(path=path, root=root, resolver=RESOLVER)++ message = str(raised.value)+ assert message.endswith(closing_clause)+ assert message.count("no fields") <= 1+ assert raised.value.available_fields == []+def test_an_unknown_field_lists_every_field_available_there(self):with pytest.raises(BindingPathUnresolvedError) as raised:derive_binding(path="invoice.totl", root=INVOICE, resolver=RESOLVER)diff --git a/tests/unit/pipelex/pipe_controllers/binding/test_binding_step_shape.py b/tests/unit/pipelex/pipe_controllers/binding/test_binding_step_shape.pynew file mode 100644index 000000000..f3879239e--- /dev/null+++ b/tests/unit/pipelex/pipe_controllers/binding/test_binding_step_shape.py@@ -0,0 +1,106 @@+from typing import Any++import pytest++from pipelex.core.pipes.exceptions import PipeValidationError+from pipelex.pipe_controllers.binding.binding_step_blueprint import check_binding_step_shape+from pipelex.validation_error_types import PipeValidationErrorType++_STEP_LABEL = "Step 1 of pipe 'index_catalog'"+++def _shape_refusal(*, raw_step: dict[str, Any]) -> str:+ with pytest.raises(PipeValidationError) as exc_info:+ check_binding_step_shape(raw_step=raw_step, step_label=_STEP_LABEL)+ assert exc_info.value.error_type == PipeValidationErrorType.BINDING_STEP_INVALID+ return str(exc_info.value)+++class TestBindingStepShape:+ @pytest.mark.parametrize(+ ("stray_fields", "joined_fields"),+ [+ pytest.param({"batch_over": "lines"}, "cannot carry `batch_over`.", id="one-field"),+ pytest.param({"batch_over": "lines", "batch_as": "line"}, "cannot carry `batch_over` or `batch_as`.", id="two-fields"),+ pytest.param(+ {"nb_output": 2, "batch_over": "lines", "batch_as": "line"},+ "cannot carry `nb_output`, `batch_over` or `batch_as`.",+ id="three-fields",+ ),+ pytest.param(+ {"nb_output": 2, "multiple_output": True, "batch_over": "lines", "batch_as": "line"},+ "cannot carry `nb_output`, `multiple_output`, `batch_over` or `batch_as`.",+ id="four-fields",+ ),+ ],+ )+ def test_the_stray_fields_are_joined_in_prose(self, stray_fields: dict[str, Any], joined_fields: str) -> None:+ message = _shape_refusal(raw_step={"from": "invoice.lines", "result": "lines", **stray_fields})++ assert f"{_STEP_LABEL} is a binding step (it carries `from`), which carries only `from` and `result`, so it {joined_fields}" in message++ @pytest.mark.parametrize(+ "stray_fields",+ [+ pytest.param({"batch_over": "lines", "batch_as": "line"}, id="both-batch-fields"),+ pytest.param({"batch_as": "line"}, id="batch-as-alone"),+ ],+ )+ def test_a_dotted_from_proposes_the_dotted_batch_over_that_binds_it(self, stray_fields: dict[str, Any]) -> None:+ message = _shape_refusal(raw_step={"from": "invoice.lines", "result": "lines", **stray_fields})++ assert (+ 'To batch over the list at `invoice.lines`, write `batch_over = "invoice.lines"` on the pipe step to run once per item: a dotted '+ "`batch_over` binds the list at that path and batches over it. "+ 'Or keep this step as `{ from = "invoice.lines", result = "lines" }` and batch over `lines` in the next pipe step.'+ ) in message+ assert "a plain `batch_over`" not in message++ def test_a_bare_from_proposes_a_plain_batch_that_binds_nothing(self) -> None:+ message = _shape_refusal(raw_step={"from": "pages", "result": "page_list", "batch_over": "page_list", "batch_as": "page"})++ assert (+ 'To batch over `pages`, write `batch_over = "pages"` on the pipe step to run once per item: a plain `batch_over` batches over '+ 'that name and needs no binding. Or keep this step as `{ from = "pages", result = "page_list" }` and batch over `page_list` in '+ "the next pipe step."+ ) in message+ assert "binds the list" not in message++ @pytest.mark.parametrize(+ "result",+ [+ pytest.param(None, id="without-result"),+ pytest.param(3, id="a-result-that-is-not-a-string"),+ ],+ )+ def test_the_remedy_names_a_placeholder_without_a_string_result(self, result: Any) -> None:+ raw_step: dict[str, Any] = {"from": "invoice.lines", "batch_over": "lines"}+ if result is not None:+ raw_step["result"] = result++ message = _shape_refusal(raw_step=raw_step)++ assert 'Or keep this step as `{ from = "invoice.lines", result = "<name>" }` and batch over `<name>` in the next pipe step.' in message++ @pytest.mark.parametrize(+ "stray_fields",+ [+ pytest.param({"nb_output": 2}, id="nb-output"),+ pytest.param({"multiple_output": True}, id="multiple-output"),+ pytest.param({"nb_output": 2, "multiple_output": True}, id="both-count-fields"),+ ],+ )+ def test_a_stray_count_proposes_no_batch(self, stray_fields: dict[str, Any]) -> None:+ message = _shape_refusal(raw_step={"from": "invoice.lines", "result": "lines", **stray_fields})++ assert (+ "`nb_output` and `multiple_output` set how many outputs a pipe produces, so they go on the pipe step running that pipe: "+ "a binding step binds the value as it is."+ ) in message+ assert "batch_over" not in message++ def test_both_families_of_fields_get_both_remedies(self) -> None:+ message = _shape_refusal(raw_step={"from": "invoice.lines", "result": "lines", "multiple_output": True, "batch_over": "lines"})++ assert "To batch over the list at `invoice.lines`" in message+ assert "`nb_output` and `multiple_output` set how many outputs a pipe produces" in messagediff --git a/tests/unit/pipelex/pipe_controllers/sequence/test_sequence_step_union.py b/tests/unit/pipelex/pipe_controllers/sequence/test_sequence_step_union.pyindex 06aeb5cc0..8ae9ee056 100644--- a/tests/unit/pipelex/pipe_controllers/sequence/test_sequence_step_union.py+++ b/tests/unit/pipelex/pipe_controllers/sequence/test_sequence_step_union.py@@ -113,7 +113,7 @@ class TestSequenceStepUnion:pytest.param('{ from = "invoice.total" }', "a binding step without `result`", id="I7-without-result"),pytest.param('{ from = "invoice.total", result = "total_amount", batch_over = "totals", batch_as = "total" }',- "cannot carry `batch_over`, `batch_as`",+ "cannot carry `batch_over` or `batch_as`.",id="I8-batch-fields",),pytest.param('{ from = "invoice.lines[0]", result = "first_line" }', "is not a path", id="I9-subscript"),@@ -193,7 +193,7 @@ branches = [errors = exc_info.value.validation_errorsassert [error.error_type for error in errors] == [PipeValidationErrorType.BINDING_STEP_INVALID]assert errors[0].pipe_code == "acknowledge_invoice"- assert f"the dotted `batch_over` '{batch_over}' is not a path" in errors[0].message+ assert f"The dotted `batch_over` '{batch_over}' of the step running pipe 'write_receipt' is not a path" in errors[0].message@pytest.mark.parametrize("batch_over",diff --git a/tests/unit/pipelex/pipe_controllers/test_sub_pipe_blueprint.py b/tests/unit/pipelex/pipe_controllers/test_sub_pipe_blueprint.pyindex 520fd21ef..3111f1a7b 100644--- a/tests/unit/pipelex/pipe_controllers/test_sub_pipe_blueprint.py+++ b/tests/unit/pipelex/pipe_controllers/test_sub_pipe_blueprint.py@@ -1,3 +1,5 @@+from typing import Any+import pytestfrom pydantic import ValidationError@@ -28,7 +30,10 @@ class TestSubPipeBlueprint:nb_output=3,multiple_output=True,)- assert "PipeStepBlueprint should have no more than '1' of nb_output or multiple_output" in str(exc_info.value)+ assert "The step running pipe 'process' carries both `nb_output` and `multiple_output`: a step sets at most one of them." in str(+ exc_info.value+ )+ assert "PipeStepBlueprint" not in str(exc_info.value)def test_validate_batch_params_correct(self):blueprint = SubPipeBlueprint(pipe="process")@@ -49,18 +54,18 @@ class TestSubPipeBlueprint:pipe="process",batch_over="items",)- assert "When 'batch_over' is specified, 'batch_as' must also be provided" in str(exc_info.value)+ assert "The step running pipe 'process' carries `batch_over` without `batch_as`:" in str(exc_info.value)with pytest.raises(ValidationError) as exc_info:SubPipeBlueprint(pipe="process",batch_as="item",)- assert "When 'batch_as' is specified, 'batch_over' must also be provided" in str(exc_info.value)+ assert "The step running pipe 'process' carries `batch_as` without `batch_over`:" in str(exc_info.value)def test_rejects_batch_over_same_as_batch_as(self):"""SubPipeBlueprint rejects batch_as == batch_over."""- with pytest.raises(ValidationError, match="batch_as"):+ with pytest.raises(ValidationError) as exc_info:SubPipeBlueprint(pipe="process_item",result="processed",@@ -68,6 +73,42 @@ class TestSubPipeBlueprint:batch_as="items",)+ refusal = exc_info.value.errors()[0].get("ctx", {}).get("error")+ assert isinstance(refusal, PipeValidationError)+ assert refusal.error_type == PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION+ assert "The `batch_as` of the step running pipe 'process_item' is 'items', the same name as its `batch_over`:" in str(refusal)++ @pytest.mark.parametrize(+ "blueprint_fields",+ [+ pytest.param({"nb_output": 3, "multiple_output": True}, id="both-counts"),+ pytest.param({"batch_over": "items"}, id="batch-over-alone"),+ pytest.param({"batch_as": "item"}, id="batch-as-alone"),+ pytest.param({"batch_over": "items", "batch_as": "items"}, id="batch-as-is-batch-over"),+ pytest.param({"batch_over": "catalog..pages", "batch_as": "page"}, id="a-dotted-batch-over-that-is-not-a-path"),+ ],+ )+ def test_a_refusal_names_the_step_never_its_pipe_as_the_faulty_one(self, blueprint_fields: dict[str, Any]) -> None:+ """The faulty fields belong to the step, held by the sequence or parallel the error locates, not to the pipe the step runs."""+ with pytest.raises(ValidationError) as exc_info:+ SubPipeBlueprint.model_validate({"pipe": "write_index_line", **blueprint_fields})++ message = str(exc_info.value)+ assert "the step running pipe 'write_index_line'" in message.lower()+ assert "In pipe" not in message++ def test_a_dotted_batch_over_that_is_not_a_path_is_named_on_its_step(self) -> None:+ with pytest.raises(ValidationError) as exc_info:+ SubPipeBlueprint(pipe="write_index_line", batch_over="catalog..pages", batch_as="page")++ refusal = exc_info.value.errors()[0].get("ctx", {}).get("error")+ assert isinstance(refusal, PipeValidationError)+ assert refusal.error_type == PipeValidationErrorType.BINDING_STEP_INVALID+ assert refusal.variable_names == ["catalog..pages"]+ assert str(refusal).startswith(+ "The dotted `batch_over` 'catalog..pages' of the step running pipe 'write_index_line' is not a path. A dotted `batch_over` binds"+ )+@pytest.mark.parametrize("stored_name",[