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.
feature/Extraneous-inputs-unflagged · L-260929-c798cb (#1298)
Louis Choqueld92b83f54e42
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 83ce3e114..34b262b6d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,9 +6,12 @@- **`read_scope` is a required run parameter (Breaking)**: `RunMetadata`, `pipeline_run_setup`, `prepare_pipe_job`, `PipelexKernel.make`, `shape_inputs`, `InputShaper.shape`, `WorkingMemoryFactory.make_from_pipeline_inputs`, `StuffFactory.make_stuff_from_stuff_content_or_data`, `normalize_data_urls_to_storage` and the runtime bridge's `PipelexPipeRunInput` take a `read_scope` with no default: a host serving several tenants passes the tenant's prefix, which must contain the run's `storage_scope`, and `None` states that the run is unscoped. `PipelexMTHDSProtocol` defaults it to `None`, which is the truth on a laptop.- **Dry-run mocks of images and documents carry readable URLs**: a mocked `ImageContent` carries one of `inference.dry_run.image_urls` and a mocked `DocumentContent` a blank one-page PDF as a `data:` URL, where both carried a random string that reads as a local path; and a model nested two levels or more inside a mocked structure now gets the same field providers as a shallower one.+- **PipeCompose, PipeSearch and PipeImgGen refuse an input they never read (Breaking)**: as PipeLLM already did, validation refuses a declared input that none of the pipe's templates reads (the template or the construct of a PipeCompose, the prompt of a PipeSearch, the prompt or negative prompt of a PipeImgGen) as `extraneous_input_variable`, naming the input: reference it in a template, or remove it from `inputs`. A variable a PipeImgGen's `negative_prompt` reads without declaring it is refused when the bundle is parsed, and `UnusedInputError`, which nothing raised, is removed.### Fixed+- **The input errors of the template operators carry their type and names**: a missing or unread input of a PipeLLM, PipeCompose, PipeSearch or PipeImgGen is reported with its `error_type` and with `variable_names` holding the plain names, sorted. A PipeCompose template reading an undeclared variable was an uncategorized item, the PipeSearch and PipeImgGen items carried no names, and PipeLLM's unread names arrived quoted (`'platform'`).+- **A template read through a subscript, a call or a `set` counts as a read**: an input a template reads only as `{{ items[0].text }}`, `{{ (items|first).text }}` or `{{ record['meta'].title }}`, or reassigns with `{% set topic = topic|trim %}`, is seen as read, where PipeLLM refused it as unread, and such a read of an undeclared variable is refused as missing. A read placed before a top-level `{% set %}` of the same name, and a `for` loop's iterable or `else` branch, read the input. The name a top-level `{% set %}…{% endset %}` block assigns, a call to one of Jinja's globals such as `range(count)` or `namespace()`, and `caller`, `varargs` and `kwargs` inside a macro are no longer demanded as inputs, while an input named like a global, such as `range`, is read wherever the template reads the name without calling it. The images and documents PipeLLM attaches, and the reference images PipeImgGen attaches, are found under the same scopes, so an image read after `{% set image = image %}` or as the iterable of a loop named after it is attached.- **A generated object's storage key names its own format**: the extension of a key under `generated/` follows the whole MIME type the object is stored under, so a fetched `image/svg+xml` is stored as `.svg`, and a type with no extension of its own gets `.bin`, where both used to get `.jpg`. The MIME type's parameters and case no longer change the extension.- **An include in a method template is a render error**: `{% include %}`, `{% extends %}` and `{% import %}` in a template rendered without a loader raise `Jinja2TemplateRenderError`, where they leaked Jinja's own `TemplateNotFound`.- **A template reads a `Composite`'s parts by name**: `{{ combo.summary }}`, `{{ combo['summary'] }}` and `combo.get('summary')` resolve the named parts of a `Composite` output, and `iter_keys` lists them; they used to render empty, and only the raw `_content`, now refused, reached them. Like any private name, a part whose name starts with an underscore is refused when a template reads it on an input.@@ -18,9 +21,6 @@- **Every template renders in a sandbox (Breaking)**: prompts, compose and construct templates, image and search prompts and condition expressions may read data and call methods of plain values (strings, numbers, dates, containers) only, so a template that reaches for a Python internal, calls a method of a Pipelex or pydantic object, or reads a name starting with an underscore other than an input's `_stuff_name`, `_content_class`, `_concept_code` and `_stuff_code` raises `Jinja2TemplateSecurityError` instead of rendering, and validation refuses the visible cases with the new `template_private_name` error. `_content` and the `stuff` property are no longer readable on an input, and bracket access and `get` on an input resolve only its content fields and metadata fields; a plain dict's keys stay readable with brackets, `record['_id']` included, and a `namespace()` holds data only, refusing a callable. The `jinja2` floor rises to 3.1.6, the release carrying Jinja's own sandbox fix for the `attr` filter.- **Dotted paths refuse underscore segments**: a PipeCompose construct `from` path such as `note.__class__.__init__.__globals__.sys.modules.os.environ` walked into Python internals with plain `getattr` and could copy the process environment into a method's output. A `from` path or `list_to_dict_keyed_by` name with a segment starting with an underscore is now refused at validation, and every dotted path the runtime walks, batch lists and prompt image references included, refuses one.--### Security-- **A scoped run reads only under its read scope, and never the local disk**: on a run with a read scope, a `pipelex-storage://` key is read only when it lies under that scope, compared segment by segment, and a bare path or a `file://` URI is never read, whichever value carries it — an input, a `PipeCompose` construct that assembles a URL from text, a model's structured output. Every content-generation leaf checks the URLs it will read before the dry-run branch, and the input seam checks a CSV input and every file it would upload or sign; a refused read raises `UriReadRefusedError`, answered as a 422, which names where the URL sat without quoting it. A run whose read scope is `None` reads as before.## [v0.69.0] - 2026-09-28diff --git a/docs/building-methods/concepts/refining-concepts.md b/docs/building-methods/concepts/refining-concepts.mdindex 707ec31ae..f98f6ecb0 100644--- a/docs/building-methods/concepts/refining-concepts.md+++ b/docs/building-methods/concepts/refining-concepts.md@@ -39,6 +39,7 @@ type = "PipeLLM"description = "Extract key terms from a contract"inputs = { contract = "Contract" } # Clear what type of document is expectedoutput = "ContractTerms"+prompt = "Extract the key terms from this contract:\n@contract"```### 3. Domain-Specific Methods@@ -326,12 +327,14 @@ output = "Page[]"type = "PipeLLM"inputs = { invoice = "Invoice" }output = "InvoiceData"+prompt = "Extract the invoice data:\n@invoice"# This pipe accepts Contract (and any concept that refines Contract)[pipe.process_contract]type = "PipeLLM"inputs = { contract = "Contract" }output = "ContractData"+prompt = "Extract the contract data:\n@contract"```In this setup:diff --git a/docs/building-methods/pipes/pipe-controllers/PipeCondition.md b/docs/building-methods/pipes/pipe-controllers/PipeCondition.mdindex 14115bca4..8c30e0045 100644--- a/docs/building-methods/pipes/pipe-controllers/PipeCondition.md+++ b/docs/building-methods/pipes/pipe-controllers/PipeCondition.md@@ -122,7 +122,7 @@ description = "Process invoice documents"inputs = { classification = "DocumentType" }output = "ProcessedDocument"prompt = """-Process this invoice document...+Process this invoice document, classified as $classification..."""[pipe.process_receipt]@@ -131,7 +131,7 @@ description = "Process receipt documents"inputs = { classification = "DocumentType" }output = "ProcessedDocument"prompt = """-Process this receipt document...+Process this receipt document, classified as $classification..."""[pipe.process_unknown]@@ -140,7 +140,7 @@ description = "Handle unknown document types"inputs = { classification = "DocumentType" }output = "ProcessedDocument"prompt = """-Process this unknown document type...+Process this document of unknown type, classified as $classification..."""```diff --git a/docs/building-methods/pipes/pipe-controllers/PipeParallel.md b/docs/building-methods/pipes/pipe-controllers/PipeParallel.mdindex 9e660252d..33d6d2059 100644--- a/docs/building-methods/pipes/pipe-controllers/PipeParallel.md+++ b/docs/building-methods/pipes/pipe-controllers/PipeParallel.md@@ -93,12 +93,14 @@ type = "PipeLLM"description = "Extract features from text"inputs = { description = "ProductDescription" }output = "ProductFeatures"+prompt = "Extract the product features from this description:\n@description"[pipe.analyze_sentiment]type = "PipeLLM"description = "Analyze sentiment of text"inputs = { description = "ProductDescription" }output = "ProductSentiment"+prompt = "Analyze the sentiment of this product description:\n@description"# The PipeParallel definition[pipe.analyze_product_in_parallel]diff --git a/docs/building-methods/pipes/pipe-controllers/PipeSequence.md b/docs/building-methods/pipes/pipe-controllers/PipeSequence.mdindex 50b9f931a..42c6e5744 100644--- a/docs/building-methods/pipes/pipe-controllers/PipeSequence.md+++ b/docs/building-methods/pipes/pipe-controllers/PipeSequence.md@@ -61,12 +61,14 @@ type = "PipeLLM"description = "Summarize text"inputs = { extracted_text = "Page[]" }output = "Text"+prompt = "Summarize this text:\n@extracted_text"[pipe.translate_to_french]type = "PipeLLM"description = "Translate text to French"inputs = { english_summary = "Text" }output = "Text"+prompt = "Translate this summary to French:\n@english_summary"[pipe.image_to_french_summary]diff --git a/docs/building-methods/pipes/pipe-operators/PipeCompose.md b/docs/building-methods/pipes/pipe-operators/PipeCompose.mdindex b1ce69757..d443c0f45 100644--- a/docs/building-methods/pipes/pipe-operators/PipeCompose.md+++ b/docs/building-methods/pipes/pipe-operators/PipeCompose.md@@ -40,6 +40,8 @@ A template reads data and calls methods of plain values, and nothing else: it ca| `output` | string | The concept for the output | Yes || `template` | string or section | An inline template string, or a `[pipe.name.template]` section (see below) | Yes* |+Every input the pipe declares must be read by the template, and every variable the template reads must be declared in `inputs`. Validation refuses an input the template never reads as `extraneous_input_variable`, naming the input, so you either reference it in the template or remove it from `inputs`; an undeclared variable is refused as `missing_input_variable`.+*Template mode requires `template`. When using the rich form (`[pipe.name.template]` section), the following sub-fields are available:| Sub-field | Type | Description | Required |@@ -131,6 +133,8 @@ Instead of rendering a template, construct mode creates a structured object by s*Either `template` or `construct` must be provided, but not both.+The input rule of template mode applies to a construct too: what reads the inputs is every `from` path and every field template, nested constructs included. A declared input none of them reads is refused as `extraneous_input_variable`, and a path whose input is not declared as `missing_input_variable`.+### Construct Field MethodsEach field in the `[pipe.name.construct]` section can use one of these methods:diff --git a/docs/building-methods/pipes/pipe-operators/PipeImgGen.md b/docs/building-methods/pipes/pipe-operators/PipeImgGen.mdindex 8cbf3599a..45365643a 100644--- a/docs/building-methods/pipes/pipe-operators/PipeImgGen.md+++ b/docs/building-methods/pipes/pipe-operators/PipeImgGen.md@@ -17,6 +17,8 @@ The variables you declare in `inputs` are **injected into that template** at runThe pipe can be configured to generate a single image or a list of images. Its only concept constraints are that declared image inputs must be `Image`-compatible and the `output` must be `Image`-compatible.+Every input the pipe declares must be read by the `prompt` or the `negative_prompt`, and every variable they read must be declared in `inputs`. Validation refuses an input neither template reads as `extraneous_input_variable`, naming the input: an image declared in `inputs` but never referenced in the prompt is never passed to the generator, so reference it in the prompt, or remove it from `inputs`. An undeclared variable is refused as `missing_input_variable`.+## Configuration`PipeImgGen` is configured in your pipeline's `.mthds` file.diff --git a/docs/building-methods/pipes/pipe-operators/PipeLLM.md b/docs/building-methods/pipes/pipe-operators/PipeLLM.mdindex ba238d7c7..08e4489b2 100644--- a/docs/building-methods/pipes/pipe-operators/PipeLLM.md+++ b/docs/building-methods/pipes/pipe-operators/PipeLLM.md@@ -18,6 +18,8 @@ For structured outputs, you have two options:If you already have text from elsewhere (a PDF extraction, a search result, an upstream pipe), call [`PipeStructure`](./PipeStructure.md) directly — there's no need to wrap a `PipeLLM` around it.+Every input the pipe declares must be read by `prompt` or `system_prompt`, and every variable they read must be declared in `inputs`. Validation refuses an input neither prompt reads as `extraneous_input_variable`, naming the input, so you either reference it in a prompt or remove it from `inputs`; an undeclared variable is refused as `missing_input_variable`.+## Working with Images (Vision Language Models)`PipeLLM` supports Vision Language Models (VLMs) that can process both text and images. To use images in your prompts:diff --git a/docs/building-methods/pipes/pipe-operators/PipeSearch.md b/docs/building-methods/pipes/pipe-operators/PipeSearch.mdindex b4edb8e62..9b7fc02be 100644--- a/docs/building-methods/pipes/pipe-operators/PipeSearch.md+++ b/docs/building-methods/pipes/pipe-operators/PipeSearch.md@@ -15,6 +15,8 @@ The output is a `SearchResult` (or a concept that refines it), which contains:- `answer`: The synthesized answer text from the search- `sources`: A list of sources, each with a `title`, `url`, and optional `snippet`+Every input the pipe declares must be read by the `prompt`, and every variable the prompt reads must be declared in `inputs`. Validation refuses an input the prompt never reads as `extraneous_input_variable`, naming the input, so you either reference it in the prompt or remove it from `inputs`; an undeclared variable is refused as `missing_input_variable`.+## Configuration`PipeSearch` is configured in your pipeline's `.mthds` file.diff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.mdindex 2e89f551a..434e7974b 100644--- a/docs/errors/authoring-and-language.md+++ b/docs/errors/authoring-and-language.md@@ -85,7 +85,6 @@ own page. Classes are grouped by subsystem.- [`StructuredContentComposerTypeError`](structured-content-composer-type-error.md) — Structured content composer type- [`StructuredContentComposerValidationError`](structured-content-composer-validation-error.md) — Structured content composer validation- [`StructuredContentComposerValueError`](structured-content-composer-value-error.md) — Structured content composer value-- [`UnusedInputError`](unused-input-error.md) — Unused input- [`WithImagesFilterError`](with-images-filter-error.md) — With images filter## Pipe controllersdiff --git a/docs/errors/unused-input-error.md b/docs/errors/unused-input-error.mddeleted file mode 100644index c593a48cd..000000000--- a/docs/errors/unused-input-error.md+++ /dev/null@@ -1,21 +0,0 @@-----title: "Unused input"-description: "Reference for the `UnusedInputError` Pipelex error class."------<!-- pipelex:generated -->--# Unused input--Raised when an input is declared but never referenced in the template.--| Field | Value |-|---|---|-| `error_type` | `UnusedInputError` |-| `title` | Unused input |-| `type_uri` | `https://docs.pipelex.com/latest/errors/unused-input-error/` |-| `error_domain` | _(inherited from parent)_ |-| Defined in | `pipelex.pipe_operators.shared.exceptions` |-| Parent class | [`PipelexError`](pipelex-error.md) |--[Back to Error Reference](index.md)diff --git a/docs/features/validation-dry-run.md b/docs/features/validation-dry-run.mdindex d490ae823..4bc251efe 100644--- a/docs/features/validation-dry-run.md+++ b/docs/features/validation-dry-run.md@@ -18,6 +18,7 @@ Check pipeline syntax, structure, and compatibility without execution:- **Syntax validation** — Catch MTHDS language errors via plxt linting- **Structure validation** — Resolve pipe and concept references in the loaded library, and verify each pipe's declared inputs against the concepts that operator accepts — plus a controller's declared output against what it actually produces (for a `PipeSequence`, its last step's output concept and multiplicity)- **Input validation** — Ensure required inputs are provided and correctly typed, and that every variable a step reads is bound by the time that step runs+- **Declared inputs are read** — For `PipeLLM`, `PipeCompose`, `PipeSearch` and `PipeImgGen`, every variable a template reads must be declared in `inputs` (`missing_input_variable`), and every declared input must be read by one of the pipe's templates (`extraneous_input_variable`): the prompt and system prompt of a `PipeLLM`, the template or the construct of a `PipeCompose`, the prompt of a `PipeSearch`, the prompt and negative prompt of a `PipeImgGen`. An unread input is refused on the pipe that declares it, before any controller above it is asked to supply itA pipe that references a sub-pipe from a package that isn't loaded is reported as **skipped** rather than validated, so a passing run is not proof that every cross-package dependency resolves.diff --git a/pipelex/mthds_parsing/validation_error_categorizer.py b/pipelex/mthds_parsing/validation_error_categorizer.pyindex 4d24dfa65..a7ec37375 100644--- a/pipelex/mthds_parsing/validation_error_categorizer.py+++ b/pipelex/mthds_parsing/validation_error_categorizer.py@@ -108,63 +108,6 @@ def _main_pipe_strip_is_safe(*, offending_code: str, stripped_code: str, blueprireturn (offending_code in pipe_keys) != (stripped_code in pipe_keys)-def _extract_variable_names_from_message(message: str) -> list[str] | None:- """Extract variable names from error messages like 'Missing input variable(s): var1, var2.'"""- # Pattern to match variable names after the colon- match = re.search(r"variable\(s\):\s*([^.]+)\.", message)- if match:- vars_str = match.group(1)- return [var.strip() for var in vars_str.split(",")]- return None---def _categorize_input_validation_error(- message: str,- *,- domain: str | None,- source: str | None,- pipe_code: str | None,-) -> PipelexBundleBlueprintValidationErrorData | None:- """Categorize input validation errors (missing or unused inputs).-- Args:- message: The error message from the validation- domain: Domain code- source: Source file path- pipe_code: Pipe code being validated-- Returns:- Categorized error data, or None if not an input validation error- """- message_lower = message.lower()-- # Detect missing input variables- if "missing input variable" in message_lower:- variable_names = _extract_variable_names_from_message(message)- return PipelexBundleBlueprintValidationErrorData(- error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,- domain_code=domain,- source=source,- pipe_code=pipe_code,- message=message,- variable_names=variable_names,- )-- # Detect unused/extraneous input variables- if "unused input variable" in message_lower:- variable_names = _extract_variable_names_from_message(message)- return PipelexBundleBlueprintValidationErrorData(- error_type=PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,- domain_code=domain,- source=source,- pipe_code=pipe_code,- message=message,- variable_names=variable_names,- )-- return None--def _categorize_typeless_pipe_error(message: str,*,@@ -388,8 +331,9 @@ def categorize_blueprint_validation_error(pipe_code = str(loc[1])# A blueprint-stage ``PipeValidationError`` (e.g. the PipeBatch ``input_item_name`` ==- # ``input_list_name`` collision raised by ``PipeBatchBlueprint.validate_inputs``, or the SubPipe- # ``batch_over`` == ``batch_as`` collision raised by ``SubPipeBlueprint.validate_batch_params``) is+ # ``input_list_name`` collision raised by ``PipeBatchBlueprint.validate_inputs``, the SubPipe+ # ``batch_over`` == ``batch_as`` collision raised by ``SubPipeBlueprint.validate_batch_params``, or a+ # missing or unread input raised by the operators' shared ``check_inputs_match_variables``) is# raised *inside* a pydantic model validator, so pydantic wraps it as a ``value_error`` with the# original exception in ``ctx["error"]``. Unwrap it — mirroring the pipe categorizer's# ``extract_wrapped_pipe_validation_error`` (one shared helper) — so its structured ``error_type``@@ -499,16 +443,6 @@ def categorize_blueprint_validation_error(if missing_type_error:return missing_type_error- # Try to categorize input validation errors (missing/unused inputs)- input_error = _categorize_input_validation_error(- message=message,- domain=domain,- source=source,- pipe_code=pipe_code,- )- if input_error:- return input_error-# Try to categorize syntax validation errors (invalid pipe code, main_pipe)syntax_error = _categorize_syntax_validation_error(message=message,diff --git a/pipelex/pipe_machinery/validation.py b/pipelex/pipe_machinery/validation.pyindex 033fdc75d..1657fbcc6 100644--- a/pipelex/pipe_machinery/validation.py+++ b/pipelex/pipe_machinery/validation.py@@ -1,4 +1,6 @@-from pipelex.tools.misc.string_utils import is_snake_case+from pipelex.core.pipes.exceptions import PipeValidationError+from pipelex.tools.misc.string_utils import get_root_from_dotted_path, is_snake_case+from pipelex.validation_error_types import PipeValidationErrorTypedef is_variable_satisfied_by_inputs(variable_path: str, *, input_names: set[str]) -> bool:@@ -53,6 +55,59 @@ def is_input_used_by_variables(input_name: str, *, variable_paths: set[str]) ->return False+def check_inputs_match_variables(+ *,+ declared_inputs: set[str],+ variable_paths: set[str],+ reader: str,+ dotted_input_supplies_its_path: bool,+) -> None:+ """Refuse a variable the templates read that no input declares, then a declared input no template reads.++ The rule shared by every operator that reads its inputs through templates: PipeLLM, PipeCompose,+ PipeSearch and PipeImgGen. ``variable_paths`` are the full dotted paths the operator's templates read,+ already rid of the operator's special names, and ``reader`` names the fields that read them, for the+ message ("prompt or system_prompt", "template").++ ``dotted_input_supplies_its_path`` keeps each operator's own rule for a dotted input name such as+ ``page.page_view`` declared without its root. PipeLLM takes it as supplying the path it names, a shape its+ tests run; PipeCompose, PipeSearch and PipeImgGen have always required every read's root to be declared.+ Whether the four should agree is a language question this check leaves open. Either way, a dotted input+ name counts as read by the path it names.++ Raises:+ PipeValidationError: ``MISSING_INPUT_VARIABLE`` with the undeclared root names, or+ ``EXTRANEOUS_INPUT_VARIABLE`` with the unread input names, each sorted.+ """+ if dotted_input_supplies_its_path:+ unsatisfied_paths = {+ variable_path for variable_path in variable_paths if not is_variable_satisfied_by_inputs(variable_path, input_names=declared_inputs)+ }+ else:+ unsatisfied_paths = {variable_path for variable_path in variable_paths if get_root_from_dotted_path(variable_path) not in declared_inputs}+ missing_names = sorted({get_root_from_dotted_path(variable_path) for variable_path in unsatisfied_paths})+ if missing_names:+ quoted_names = _quoted_names(names=missing_names)+ if len(missing_names) == 1:+ msg = f"Variable {quoted_names} is read by the {reader} but not declared in `inputs`. Declare it in `inputs`, or stop reading it."+ else:+ msg = f"Variables {quoted_names} are read by the {reader} but not declared in `inputs`. Declare them in `inputs`, or stop reading them."+ raise PipeValidationError(message=msg, error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE, variable_names=missing_names)++ unread_names = sorted(input_name for input_name in declared_inputs if not is_input_used_by_variables(input_name, variable_paths=variable_paths))+ if unread_names:+ quoted_names = _quoted_names(names=unread_names)+ if len(unread_names) == 1:+ msg = f"Input {quoted_names} is declared but never read by the {reader}. Reference it in the {reader}, or remove it from `inputs`."+ else:+ msg = f"Inputs {quoted_names} are declared but never read by the {reader}. Reference them in the {reader}, or remove them from `inputs`."+ raise PipeValidationError(message=msg, error_type=PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE, variable_names=unread_names)+++def _quoted_names(*, names: list[str]) -> str:+ return ", ".join(f"'{name}'" for name in names)++def is_valid_input_name(input_name: str) -> bool:"""Check if an input name is valid.diff --git a/pipelex/pipe_operators/compose/construct_blueprint.py b/pipelex/pipe_operators/compose/construct_blueprint.pyindex 370dbc86c..bc2a4af56 100644--- a/pipelex/pipe_operators/compose/construct_blueprint.py+++ b/pipelex/pipe_operators/compose/construct_blueprint.py@@ -254,15 +254,28 @@ class ConstructBlueprint(BaseModel):return templatesdef get_required_variables(self) -> set[str]:- """Extract all variable names/paths required to compose this construct.+ """Extract the root names of every variable this construct reads from working memory.++ For example, 'deal' for both `from = "deal.amount"` and a template reading `$deal.customer_name`.++ Returns:+ Set of root variable names needed from working memory+ """+ return {get_root_from_dotted_path(variable_path) for variable_path in self.get_required_variable_paths()}++ def get_required_variable_paths(self) -> set[str]:+ """Extract the full dotted path of every variable this construct reads from working memory.This includes:- - All 'from' paths (variable references)- - All variables used in templates (base names only, e.g., 'deal' from 'deal.amount')- - Variables from nested constructs (recursively)+ - All 'from' paths, as written+ - All variable paths read by templates, internal and special names excluded+ - The paths read by nested constructs (recursively)++ The input check matches these paths against the declared inputs, so that a dotted input name+ (`page.page_view`), declared next to its root `page`, counts as read by the path it names.Returns:- Set of variable names/paths needed from working memory+ Set of full dotted variable paths read from working memory"""required: set[str] = set()@@ -270,9 +283,7 @@ class ConstructBlueprint(BaseModel):match field_blueprint.method:case ConstructFieldMethod.FROM_VAR:if field_blueprint.from_path:- # Also only the base variable name for input validation- base_var = get_root_from_dotted_path(field_blueprint.from_path)- required.add(base_var)+ required.add(field_blueprint.from_path)case ConstructFieldMethod.TEMPLATE:if field_blueprint.template:@@ -286,16 +297,15 @@ class ConstructBlueprint(BaseModel):except Jinja2DetectVariablesError as exc:msg = f"Error detecting required variables in construct template: {exc}"raise ValueError(msg) from exc- # Extract root names and filter out internal variables (same approach as template mode)+ # Filter out internal and special variables by their root (same approach as template mode)for var in template_vars:root_var = get_root_from_dotted_path(var)if not root_var.startswith("_") and root_var != "place_holder":- required.add(root_var)+ required.add(var)case ConstructFieldMethod.NESTED:if field_blueprint.nested:- nested_vars = field_blueprint.nested.get_required_variables()- required.update(nested_vars)+ required.update(field_blueprint.nested.get_required_variable_paths())case ConstructFieldMethod.FIXED:# Fixed values don't require any variablesdiff --git a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py b/pipelex/pipe_operators/compose/pipe_compose_blueprint.pyindex db56ea820..70ac963bf 100644--- a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py+++ b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py@@ -8,6 +8,7 @@ from pipelex.cogt.templating.template_blueprint import TemplateBlueprintfrom pipelex.cogt.templating.template_preprocessor import preprocess_templatefrom pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicityfrom pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint+from pipelex.pipe_machinery.validation import check_inputs_match_variablesfrom pipelex.pipe_operators.compose.construct_blueprint import ConstructBlueprintfrom pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxErrorfrom pipelex.tools.jinja2.jinja2_parsing import check_jinja2_parsing@@ -120,34 +121,34 @@ class PipeComposeBlueprint(PipeBlueprint):template_category=self.template_category,template_source=preprocessed_template,)- required_variables: set[str] = set()+ # Internal names (starting with an underscore) and the special `place_holder` never count as read inputs+ variable_paths: set[str] = set()for path in full_paths:root = get_root_from_dotted_path(path)if not root.startswith("_") and root != "place_holder":- required_variables.add(root)- for required_variable_name in required_variables:- if required_variable_name not in self.input_names:- msg = f"Required variable '{required_variable_name}' is not in the inputs of PipeCompose."- raise ValueError(msg)+ variable_paths.add(path)+ check_inputs_match_variables(+ declared_inputs=declared_inputs, variable_paths=variable_paths, reader="template", dotted_input_supplies_its_path=False+ )def _validate_construct_inputs(self):"""Validate inputs for construct mode.- The construct blueprint may reference variables from working memory.- We validate that the root variable names (before any dots) are declared in inputs.- For example, 'deal.customer_name' requires 'deal' to be in inputs.+ The construct reads variables from working memory through its `from` paths and its field+ templates, nested constructs included. Every path read must be satisfied by a declared input+ ('deal.customer_name' by 'deal'), and every declared input must be read by one of them."""construct_bp = self.construct_blueprintif construct_bp is None:return- required_variables = construct_bp.get_required_variables()-- for required_variable in required_variables:- root_variable_name = get_root_from_dotted_path(required_variable)- if root_variable_name not in self.input_names:- msg = f"Required variable '{root_variable_name}' from construct is not in the inputs of PipeCompose for field '{required_variable}'."- raise ValueError(msg)+ declared_inputs: set[str] = set(self.inputs.keys()) if self.inputs else set()+ check_inputs_match_variables(+ declared_inputs=declared_inputs,+ variable_paths=construct_bp.get_required_variable_paths(),+ reader="construct",+ dotted_input_supplies_its_path=False,+ )@overridedef validate_output(self):diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.pyindex 30e6cbb11..c5c84fd2a 100644--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py@@ -9,6 +9,7 @@ from pipelex.cogt.img_gen.img_gen_setting import ImgGenModelChoicefrom pipelex.cogt.templating.exceptions import TemplateSigilSyntaxErrorfrom pipelex.cogt.templating.template_preprocessor import preprocess_templatefrom pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint+from pipelex.pipe_machinery.validation import check_inputs_match_variablesfrom pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxErrorfrom pipelex.tools.jinja2.jinja2_parsing import check_jinja2_parsingfrom pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables@@ -46,13 +47,30 @@ class PipeImgGenBlueprint(PipeBlueprint):@overridedef validate_inputs(self):- # Get all required variables from prompt- template_category = TemplateCategory.IMG_GEN_PROMPT+ # An input counts as read when the prompt or the negative prompt reads itdeclared_inputs: set[str] = set(self.inputs.keys()) if self.inputs else set()+ variable_paths: set[str] = set()+ for template_source, template_label in [(self.prompt, "prompt"), (self.negative_prompt, "negative_prompt")]:+ if template_source is None:+ continue+ variable_paths.update(+ self._read_variable_paths(template_source=template_source, template_label=template_label, declared_inputs=declared_inputs)+ )+ check_inputs_match_variables(+ declared_inputs=declared_inputs,+ variable_paths=variable_paths,+ reader="prompt or negative_prompt",+ dotted_input_supplies_its_path=False,+ )++ @classmethod+ def _read_variable_paths(cls, *, template_source: str, template_label: str, declared_inputs: set[str]) -> set[str]:+ """The dotted variable paths one template reads, internal names (starting with an underscore) excluded."""+ template_category = TemplateCategory.IMG_GEN_PROMPTtry:- preprocessed_template = preprocess_template(self.prompt, declared_inputs=declared_inputs)+ preprocessed_template = preprocess_template(template_source, declared_inputs=declared_inputs)except TemplateSigilSyntaxError as exc:- msg = f"Template sigil error in PipeImgGen prompt: {exc}"+ msg = f"Template sigil error in PipeImgGen {template_label}: {exc}"raise ValueError(msg) from exctry:check_jinja2_parsing(@@ -60,29 +78,13 @@ class PipeImgGenBlueprint(PipeBlueprint):template_category=template_category,)except Jinja2TemplateSyntaxError as exc:- msg = f"Could not parse template for PipeImgGen: {exc}"+ msg = f"Could not parse {template_label} template for PipeImgGen: {exc}"raise ValueError(msg) from exc- # Filter out internal variables that start with underscorefull_paths = detect_jinja2_required_variables(template_category=template_category,template_source=preprocessed_template,)- required_variables: set[str] = set()- for path in full_paths:- root = get_root_from_dotted_path(path)- if not root.startswith("_"):- required_variables.add(root)-- # Check that all required variables are in inputs- missing_variables: set[str] = required_variables - declared_inputs-- if missing_variables:- missing_vars_str = ", ".join(sorted(missing_variables))- msg = (- f"Missing input variable(s) in prompt template: {missing_vars_str}. "- "These variables are used in the prompt but not declared in inputs."- )- raise ValueError(msg)+ return {path for path in full_paths if not get_root_from_dotted_path(path).startswith("_")}@overridedef validate_output(self):diff --git a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py b/pipelex/pipe_operators/llm/pipe_llm_blueprint.pyindex 101e33bbc..1bfa35828 100644--- a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py+++ b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py@@ -11,7 +11,7 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplicityfrom pipelex.core.qualified_ref import QualifiedReffrom pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint-from pipelex.pipe_machinery.validation import is_input_used_by_variables, is_variable_satisfied_by_inputs+from pipelex.pipe_machinery.validation import check_inputs_match_variablesfrom pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesErrorfrom pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variablesfrom pipelex.tools.jinja2.template_category import TemplateCategory@@ -110,30 +110,12 @@ class PipeLLMBlueprint(PipeBlueprint):var for var in required_variable_paths if not var.startswith("_") and get_root_from_dotted_path(var) != "place_holder"}- # Find variables used in prompts but not satisfied by any input- missing_inputs = {- var_path for var_path in filtered_variable_paths if not is_variable_satisfied_by_inputs(var_path, input_names=declared_inputs)- }-- # Find inputs declared but not used by any variable path- unused_inputs = {- input_name for input_name in declared_inputs if not is_input_used_by_variables(input_name, variable_paths=filtered_variable_paths)- }-- if missing_inputs:- missing_vars_str = ", ".join(sorted(missing_inputs))- msg = (- f"Missing input variable(s): {missing_vars_str}. These variables are used in the prompt or system_prompt but not declared in inputs."- )- raise ValueError(msg)-- if unused_inputs:- unused_vars_str = ", ".join(sorted(unused_inputs))- msg = (- f"Unused input variable(s): '{unused_vars_str}'. "- "These variables are declared in inputs but not referenced in the prompt or system_prompt."- )- raise ValueError(msg)+ check_inputs_match_variables(+ declared_inputs=declared_inputs,+ variable_paths=filtered_variable_paths,+ reader="prompt or system_prompt",+ dotted_input_supplies_its_path=True,+ )@overridedef validate_output(self):diff --git a/pipelex/pipe_operators/search/pipe_search_blueprint.py b/pipelex/pipe_operators/search/pipe_search_blueprint.pyindex 52667432a..6067290b8 100644--- a/pipelex/pipe_operators/search/pipe_search_blueprint.py+++ b/pipelex/pipe_operators/search/pipe_search_blueprint.py@@ -8,6 +8,7 @@ from pipelex.cogt.search.search_setting import SearchModelChoicefrom pipelex.cogt.templating.exceptions import TemplateSigilSyntaxErrorfrom pipelex.cogt.templating.template_preprocessor import preprocess_templatefrom pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint+from pipelex.pipe_machinery.validation import check_inputs_match_variablesfrom pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxErrorfrom pipelex.tools.jinja2.jinja2_parsing import check_jinja2_parsingfrom pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables@@ -59,18 +60,8 @@ class PipeSearchBlueprint(PipeBlueprint):template_category=template_category,template_source=preprocessed_template,)- required_variables: set[str] = set()- for path in full_paths:- root = get_root_from_dotted_path(path)- if not root.startswith("_"):- required_variables.add(root)-- missing_variables: set[str] = required_variables - declared_inputs-- if missing_variables:- missing_vars_str = ", ".join(sorted(missing_variables))- msg = (- f"Missing input variable(s) in prompt template: {missing_vars_str}. "- "These variables are used in the prompt but not declared in inputs."- )- raise ValueError(msg)+ # Names starting with an underscore are internal and never count as read inputs+ variable_paths = {path for path in full_paths if not get_root_from_dotted_path(path).startswith("_")}+ check_inputs_match_variables(+ declared_inputs=declared_inputs, variable_paths=variable_paths, reader="prompt", dotted_input_supplies_its_path=False+ )diff --git a/pipelex/pipe_operators/shared/exceptions.py b/pipelex/pipe_operators/shared/exceptions.pyindex 284419d80..12e26314f 100644--- a/pipelex/pipe_operators/shared/exceptions.py+++ b/pipelex/pipe_operators/shared/exceptions.py@@ -3,7 +3,3 @@ from pipelex.base_exceptions import PipelexErrorclass WithImagesFilterError(PipelexError):"""Raised when | with_images is used on a type without nested images."""---class UnusedInputError(PipelexError):- """Raised when an input is declared but never referenced in the template."""diff --git a/pipelex/pipe_operators/shared/template_image_analyzer.py b/pipelex/pipe_operators/shared/template_image_analyzer.pyindex 2b10d66fc..2d11fd351 100644--- a/pipelex/pipe_operators/shared/template_image_analyzer.py+++ b/pipelex/pipe_operators/shared/template_image_analyzer.py@@ -13,7 +13,7 @@ from pipelex.core.pipes.variable_multiplicity import parse_concept_with_multiplifrom pipelex.core.stuffs.image_field_search import search_for_nested_image_fieldsfrom pipelex.interpreter_hub import get_concept_library, get_native_concept, get_required_conceptfrom pipelex.kernel.prompt_references import ImageReference, ImageReferenceKind-from pipelex.pipe_operators.shared.exceptions import UnusedInputError, WithImagesFilterError+from pipelex.pipe_operators.shared.exceptions import WithImagesFilterErrorfrom pipelex.tools.jinja2.jinja2_models import Jinja2FilterNamefrom pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_variable_referencesfrom pipelex.tools.jinja2.template_category import TemplateCategory@@ -134,43 +134,6 @@ class TemplateImageAnalyzer:return image_references- @classmethod- def validate_unused_inputs(- cls,- template_sources: list[str],- *,- input_specs: dict[str, str],- template_category: TemplateCategory = TemplateCategory.LLM_PROMPT,- ) -> None:- """Validate that all declared inputs are used in at least one template.-- Args:- template_sources: List of template sources to check- input_specs: Mapping of variable names to concept codes- template_category: The template category (defaults to LLM_PROMPT for backwards compatibility)-- Raises:- UnusedInputError: If any declared input is never referenced- """- referenced_roots: set[str] = set()- declared_inputs = set(input_specs.keys())-- for template_source in template_sources:- preprocessed = preprocess_template(template_source, declared_inputs=declared_inputs)- variable_refs = detect_jinja2_variable_references(- template_category=template_category,- template_source=preprocessed,- )- for var_ref in variable_refs:- root_var = get_root_from_dotted_path(var_ref.path)- referenced_roots.add(root_var)-- unused_inputs = declared_inputs - referenced_roots-- if unused_inputs:- msg = f"Inputs declared but never used in templates: {sorted(unused_inputs)}"- raise UnusedInputError(msg)-@classmethoddef _resolve_concept(cls, concept_ref_or_code: str, *, domain_code: str) -> Concept:"""Resolve a concept reference to a Concept object.diff --git a/pipelex/tools/jinja2/jinja2_required_variables.py b/pipelex/tools/jinja2/jinja2_required_variables.pyindex 899137a1a..8bd4e4755 100644--- a/pipelex/tools/jinja2/jinja2_required_variables.py+++ b/pipelex/tools/jinja2/jinja2_required_variables.py@@ -1,4 +1,5 @@from dataclasses import field+from typing import Protocolfrom jinja2 import nodesfrom jinja2.exceptions import (@@ -17,7 +18,7 @@ from pipelex.tools.misc.string_utils import get_root_from_dotted_pathclass VariableReference:"""Represents a variable reference in a Jinja2 template with its applied filters.- Mutated in place: ``_collect_variable_references`` does ``.filters.append(...)``+ Mutated in place: ``detect_jinja2_variable_references`` extends ``.filters``on re-seen variables, so this is intentionally NOT frozen.Attributes:@@ -47,75 +48,87 @@ def _build_full_path(node: nodes.Node) -> str | None:return None-def _collect_declarations_from_body(body: list[nodes.Node]) -> set[str]:- """Pre-scan a list of nodes to collect all declarations made at this scope level.+def _set_target_name(*, statement: nodes.Node) -> str | None:+ """The name a `{% set %}` or a `{% set %}…{% endset %}` block assigns, when it assigns a plain name."""+ if isinstance(statement, (nodes.Assign, nodes.AssignBlock)) and isinstance(statement.target, nodes.Name):+ return statement.target.name+ return None+++class _ReadHandler(Protocol):+ """Deals with a node that may read a variable, given the names declared where it stands.- This handles {% set %} and {% macro %} declarations that should be visible- to all subsequent nodes in the same scope.+ Returns True when it has dealt with the node, which is then not walked into."""- declarations: set[str] = set()- for node in body:- if isinstance(node, nodes.Assign):- if isinstance(node.target, nodes.Name):- declarations.add(node.target.name)- elif isinstance(node, nodes.Macro):- declarations.add(node.name)- return declarations+ def __call__(self, *, node: nodes.Node, declared_names: set[str]) -> bool: ...-def _collect_full_variable_paths(node: nodes.Node, *, paths: set[str], declared_names: set[str]) -> None:- """Recursively walk the AST and collect full variable paths.- This function collects only the FULL (leaf) paths for each variable access chain.- For example, `{{ foo.bar.baz }}` will only return `foo.bar.baz`, not intermediate- paths like `foo.bar` or `foo`.+def _walk_reads(*, node: nodes.Node, declared_names: set[str], global_names: set[str], handle_read: _ReadHandler) -> None:+ """Walk a template's AST in Jinja's scopes, handing every node that may read a variable to ``handle_read``.++ Both detectors below walk through here, so the names they treat as declared cannot drift apart: the required+ variables the input check compares with the inputs, and the references that attach images and documents.Args:node: The current AST node- paths: Set to collect discovered paths- declared_names: Set of locally declared names (loop variables, macro params, etc.)+ declared_names: The names declared where the node stands (a `set` before it, a loop target, a macro argument)+ global_names: The environment's globals (`range`, `namespace`, `dict`...)+ handle_read: What to do with a node that may read a variable"""- # Track locally declared variables that apply to this node's children- local_declared: set[str] = set()-- # For Template nodes, pre-scan body to find all declarations at this scopeif isinstance(node, nodes.Template):- local_declared.update(_collect_declarations_from_body(node.body))+ # A macro's name is never an input, and a macro body, which runs when the macro is called, sees every+ # top-level `set`. Elsewhere a `set` declares its name only from its own statement on:+ # `{% set topic = topic|trim %}` reads the incoming `topic`, and so does a read placed before the `set`+ top_level_set_names = {name for statement in node.body if (name := _set_target_name(statement=statement)) is not None}+ scope_declared = declared_names | {statement.name for statement in node.body if isinstance(statement, nodes.Macro)}+ for statement in node.body:+ statement_declared = scope_declared | top_level_set_names if isinstance(statement, nodes.Macro) else scope_declared+ _walk_reads(node=statement, declared_names=statement_declared, global_names=global_names, handle_read=handle_read)+ if (name := _set_target_name(statement=statement)) is not None:+ scope_declared.add(name)+ returnif isinstance(node, nodes.For):- # Loop variable is locally declared+ # The iterable and the `else` branch are read outside the loop, the body and the loop filter inside it,+ # where the loop target and the special `loop` variable are declared+ loop_declared = declared_names | {"loop"}if isinstance(node.target, nodes.Name):- local_declared.add(node.target.name)+ loop_declared.add(node.target.name)elif isinstance(node.target, nodes.Tuple):- for item in node.target.items:- if isinstance(item, nodes.Name):- local_declared.add(item.name)- # The special 'loop' variable is available inside for loops- local_declared.add("loop")+ loop_declared.update(item.name for item in node.target.items if isinstance(item, nodes.Name))+ # Walked in source order, which is the order the image references are attached in+ scoped_nodes = [+ (node.iter, declared_names),+ *((statement, loop_declared) for statement in node.body),+ *((statement, declared_names) for statement in node.else_),+ *([(node.test, loop_declared)] if node.test is not None else []),+ ]+ for scoped_node, scope_declared_names in scoped_nodes:+ _walk_reads(node=scoped_node, declared_names=scope_declared_names, global_names=global_names, handle_read=handle_read)+ returnif isinstance(node, nodes.Macro):- # Macro parameters are locally declared (within the macro body)- local_declared.update(arg.name for arg in node.args)+ # Macro parameters, and the names Jinja provides inside a macro body, are locally declared+ declared_names = declared_names | {arg.name for arg in node.args} | {"caller", "varargs", "kwargs"}- # Merge local declarations- new_declared = declared_names | local_declared+ if isinstance(node, nodes.Name) and node.ctx != "load":+ # The target of a `set` or a `for` is written, not read+ return- # Check if this is a Name or Getattr node that represents a variable access- # We only add the path and DON'T recurse into Name/Getattr children to avoid- # adding intermediate paths (e.g., for `foo.bar`, we only want `foo.bar`, not also `foo`)- if isinstance(node, (nodes.Name, nodes.Getattr)):- full_path = _build_full_path(node)- if full_path:- root_name = get_root_from_dotted_path(full_path)- # Only add if the root is not a declared local variable- if root_name not in new_declared:- paths.add(full_path)- # Don't recurse into Name/Getattr children - we've captured the full path+ if isinstance(node, nodes.Call) and isinstance(node.node, nodes.Name) and node.node.name in global_names:+ # A call to a Jinja global (`range(count)`, `namespace()`) reads only its arguments. Any other read of the+ # name (`{{ range }}`, `range.low`) reads the input of that name, which shadows the global when rendered+ for child in node.iter_child_nodes():+ if child is not node.node:+ _walk_reads(node=child, declared_names=declared_names, global_names=global_names, handle_read=handle_read)+ return++ if handle_read(node=node, declared_names=declared_names):return- # Recurse into child nodes (only for non-Name/Getattr nodes)for child in node.iter_child_nodes():- _collect_full_variable_paths(child, paths=paths, declared_names=new_declared)+ _walk_reads(node=child, declared_names=declared_names, global_names=global_names, handle_read=handle_read)def detect_jinja2_required_variables(@@ -156,7 +169,20 @@ def detect_jinja2_required_variables(raise Jinja2DetectVariablesError(msg) from undef_errorpaths: set[str] = set()- _collect_full_variable_paths(parsed_ast, paths=paths, declared_names=set())++ def collect_full_path(*, node: nodes.Node, declared_names: set[str]) -> bool:+ # Only the full path of an access chain is collected: `{{ foo.bar.baz }}` gives `foo.bar.baz`, not `foo.bar` or `foo`+ if not isinstance(node, (nodes.Name, nodes.Getattr)):+ return False+ full_path = _build_full_path(node)+ if full_path is None:+ # An attribute on a subscript, a call or a filter (`items[0].text`) reads the path its chain starts from+ return False+ if get_root_from_dotted_path(full_path) not in declared_names:+ paths.add(full_path)+ return True++ _walk_reads(node=parsed_ast, declared_names=set(), global_names=set(jinja2_env.globals), handle_read=collect_full_path)return paths@@ -182,76 +208,6 @@ def _extract_filters_and_variable(node: nodes.Node) -> tuple[list[str], nodes.Noreturn filters, current_node-def _collect_variable_references(- node: nodes.Node,- *,- references: dict[str, VariableReference],- declared_names: set[str],-) -> None:- """Recursively walk the AST and collect variable references with their filters.-- This function collects VariableReference objects containing the full path- and any filters applied to each variable. If the same variable is referenced- multiple times with different filters, all filters are combined.-- Args:- node: The current AST node- references: Dict to collect discovered references (path -> VariableReference)- declared_names: Set of locally declared names (loop variables, macro params, etc.)- """- local_declared: set[str] = set()-- if isinstance(node, nodes.Template):- local_declared.update(_collect_declarations_from_body(node.body))-- if isinstance(node, nodes.For):- if isinstance(node.target, nodes.Name):- local_declared.add(node.target.name)- elif isinstance(node.target, nodes.Tuple):- for item in node.target.items:- if isinstance(item, nodes.Name):- local_declared.add(item.name)- local_declared.add("loop")-- if isinstance(node, nodes.Macro):- local_declared.update(arg.name for arg in node.args)-- new_declared = declared_names | local_declared-- # Handle Filter nodes - extract filters and find the base variable- if isinstance(node, nodes.Filter):- filters, base_node = _extract_filters_and_variable(node)- if base_node is None:- return- full_path = _build_full_path(base_node)- if full_path:- root_name = get_root_from_dotted_path(full_path)- if root_name not in new_declared:- if full_path in references:- # Extend existing filters (avoid duplicates)- for filter_name in filters:- if filter_name not in references[full_path].filters:- references[full_path].filters.append(filter_name)- else:- references[full_path] = VariableReference(path=full_path, filters=filters)- # Don't recurse into the Filter chain - we've already processed it- return-- # Handle plain Name or Getattr nodes (no filter applied)- if isinstance(node, (nodes.Name, nodes.Getattr)):- full_path = _build_full_path(node)- if full_path:- root_name = get_root_from_dotted_path(full_path)- if root_name not in new_declared:- if full_path not in references:- references[full_path] = VariableReference(path=full_path, filters=[])- return-- # Recurse into child nodes- for child in node.iter_child_nodes():- _collect_variable_references(child, references=references, declared_names=new_declared)--def detect_jinja2_variable_references(*,template_category: TemplateCategory,@@ -291,5 +247,27 @@ def detect_jinja2_variable_references(raise Jinja2DetectVariablesError(msg) from undef_errorreferences: dict[str, VariableReference] = {}- _collect_variable_references(parsed_ast, references=references, declared_names=set())++ def collect_reference(*, node: nodes.Node, declared_names: set[str]) -> bool:+ # A filter chain is taken whole, with its filter names; a chain or a path that stops at a subscript or a+ # call (`items[0].image`) gives no reference, since no image or document can be resolved from it+ if isinstance(node, nodes.Filter):+ filters, base_node = _extract_filters_and_variable(node)+ elif isinstance(node, (nodes.Name, nodes.Getattr)):+ filters, base_node = [], node+ else:+ return False+ full_path = _build_full_path(base_node) if base_node is not None else None+ if full_path is None or get_root_from_dotted_path(full_path) in declared_names:+ return True+ if full_path in references:+ # The same variable referenced several times combines its filters+ for filter_name in filters:+ if filter_name not in references[full_path].filters:+ references[full_path].filters.append(filter_name)+ else:+ references[full_path] = VariableReference(path=full_path, filters=filters)+ return True++ _walk_reads(node=parsed_ast, declared_names=set(), global_names=set(jinja2_env.globals), handle_read=collect_reference)return list(references.values())diff --git a/subject_grants.toml b/subject_grants.tomlindex bb3120dae..652d710df 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -3992,10 +3992,6 @@ rationale = "Single-operand transformation of the code; the rest is context."param = "loc"rationale = "Verb-object: categorizes the error at the loc; context stays keyword."-["pipelex/mthds_parsing/validation_error_categorizer.py::_categorize_input_validation_error"]-param = "message"-rationale = "Verb-object: categorizes the error message; context stays keyword."-["pipelex/mthds_parsing/validation_error_categorizer.py::_categorize_syntax_validation_error"]param = "message"rationale = "Verb-object: categorizes the error message; context stays keyword."@@ -4004,10 +4000,6 @@ rationale = "Verb-object: categorizes the error message; context stays keyword."param = "message"rationale = "Verb-object: categorizes the message; the rest is context."-["pipelex/mthds_parsing/validation_error_categorizer.py::_extract_variable_names_from_message"]-param = "message"-rationale = "Verb-object: extracts from the message; single operand."-["pipelex/mthds_parsing/validation_error_categorizer.py::_extract_wrapped_invalid_pipe_code_syntax_error"]param = "error"rationale = "Extraction from the single error operand."@@ -4304,10 +4296,6 @@ rationale = "Query accessor keyed by the variable path; context stays keyword."param = "template_source"rationale = "Verb-object: analyzes the template source; context stays keyword."-["pipelex/pipe_operators/shared/template_image_analyzer.py::TemplateImageAnalyzer.validate_unused_inputs"]-param = "template_sources"-rationale = "Verb-object: validates the template sources; context stays keyword."-["pipelex/pipe_operators/structure/pipe_structure.py::PipeStructure._format_error_location"]param = "pipe_run_params"rationale = "Derivation from the run params; single operand."@@ -6044,18 +6032,6 @@ rationale = "Jinja op on the template_source; single operand (context keyword-onparam = "node"rationale = "Extracts/derives from the node; single operand."-["pipelex/tools/jinja2/jinja2_required_variables.py::_collect_declarations_from_body"]-param = "body"-rationale = "Extracts/derives from the body; single operand."--["pipelex/tools/jinja2/jinja2_required_variables.py::_collect_full_variable_paths"]-param = "node"-rationale = "Extracts/derives from the node; single operand."--["pipelex/tools/jinja2/jinja2_required_variables.py::_collect_variable_references"]-param = "node"-rationale = "Extracts/derives from the node; single operand."-["pipelex/tools/jinja2/jinja2_required_variables.py::_extract_filters_and_variable"]param = "node"rationale = "Extracts/derives from the node; single operand."diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex 59e384d0f..61c459b1f 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -328,7 +328,6 @@ UnknownSecretsMethodError | Unknown secrets method | https://docs.pipelex.com/laUnknownStorageMethodError | Unknown storage method | https://docs.pipelex.com/latest/errors/unknown-storage-method-error/UnknownVarPrefixError | Unknown var prefix | https://docs.pipelex.com/latest/errors/unknown-var-prefix-error/UnsafeSchemaError | Unsafe schema | https://docs.pipelex.com/latest/errors/unsafe-schema-error/-UnusedInputError | Unused input | https://docs.pipelex.com/latest/errors/unused-input-error/UriReadRefusedError | Read outside the run's scope refused | https://docs.pipelex.com/latest/errors/uri-read-refused-error/ValidateBundleError | Validate bundle | https://docs.pipelex.com/latest/errors/validate-bundle-error/VarFallbackPatternError | Var fallback pattern | https://docs.pipelex.com/latest/errors/var-fallback-pattern-error/diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_structured_errors.py b/tests/integration/pipelex/pipeline/test_validate_bundle_structured_errors.pyindex 4a9e6b9d3..3636d43b8 100644--- a/tests/integration/pipelex/pipeline/test_validate_bundle_structured_errors.py+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_structured_errors.py@@ -20,6 +20,7 @@ categorized pipe-blueprint items (the loc key is ``pipe``, not ``pipes``)."""from collections.abc import Callable+from pathlib import Pathimport pytest@@ -136,6 +137,74 @@ prompt = "Describe $text""""+_COMPOSE_UNREAD_INPUT_MTHDS = """+domain = "structured_compose_unread"+main_pipe = "render_note"++[pipe.render_note]+type = "PipeCompose"+description = "Compose that declares an input its template never reads."+inputs = { topic = "Text", unused = "Text" }+output = "Text"+template = "A note about $topic"+"""++_COMPOSE_UNDECLARED_VARIABLE_MTHDS = """+domain = "structured_compose_undeclared"+main_pipe = "render_note"++[pipe.render_note]+type = "PipeCompose"+description = "Compose whose template reads a variable no input declares."+inputs = { topic = "Text" }+output = "Text"+template = "A note about $topic for $audience"+"""++_SEARCH_UNREAD_INPUT_MTHDS = """+domain = "structured_search_unread"+main_pipe = "find_news"++[pipe.find_news]+type = "PipeSearch"+description = "Search that declares an input its prompt never reads."+inputs = { topic = "Text", unused = "Text" }+output = "SearchResult"+prompt = "Latest news on $topic"+"""++_IMG_GEN_UNREAD_INPUT_MTHDS = """+domain = "structured_img_gen_unread"+main_pipe = "generate_thumbnail"++[pipe.generate_thumbnail]+type = "PipeImgGen"+description = "Image generation that declares an image its prompt never reads."+inputs = { image = "Image" }+output = "Image"+prompt = "A small square thumbnail"+"""++_SEQUENCE_OVER_UNREAD_INPUT_MTHDS = """+domain = "structured_sequence_unread"+main_pipe = "seq"++[pipe.seq]+type = "PipeSequence"+description = "Sequence whose step declares an input it never reads."+inputs = { topic = "Text" }+output = "Text"+steps = [{ pipe = "render_note", result = "note" }]++[pipe.render_note]+type = "PipeCompose"+description = "Compose that declares an input its template never reads."+inputs = { topic = "Text", unused = "Text" }+output = "Text"+template = "A note about $topic"+"""++async def _validation_errors_for(mthds_contents: str) -> list[ValidationErrorItem]:"""Validate one invalid bundle and return its structured validation_errors[]."""with pytest.raises(ValidateBundleError) as exc_info:@@ -292,3 +361,80 @@ class TestValidateBundleStructuredErrors:for reported in items:if reported.pipe_code is not None:assert reported.domain_code is not None, f"item {reported.error_type} carries pipe_code without domain_code"++ @pytest.mark.parametrize(+ ("mthds_contents", "pipe_code", "domain_code", "unread_input"),+ [+ (_COMPOSE_UNREAD_INPUT_MTHDS, "render_note", "structured_compose_unread", "unused"),+ (_SEARCH_UNREAD_INPUT_MTHDS, "find_news", "structured_search_unread", "unused"),+ (_IMG_GEN_UNREAD_INPUT_MTHDS, "generate_thumbnail", "structured_img_gen_unread", "image"),+ ],+ ids=["compose", "search", "img_gen"],+ )+ async def test_unread_input_is_a_located_extraneous_input_item(+ self,+ load_empty_library: Callable[[], str],+ tmp_path: Path,+ mthds_contents: str,+ pipe_code: str,+ domain_code: str,+ unread_input: str,+ ) -> None:+ """PipeCompose, PipeSearch and PipeImgGen refuse a declared input they never read, as PipeLLM does,+ with the input named plainly and the item located on its pipe, domain and source file.+ """+ load_empty_library()+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text(mthds_contents)+ with pytest.raises(ValidateBundleError) as exc_info:+ await validate_bundle(mthds_file_path=bundle_path)+ items = exc_info.value.to_error_report().validation_errors+ assert items, "Every invalid verdict must carry a non-empty validation_errors[]"+ extraneous_items = [item for item in items if item.error_type == PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE]+ assert extraneous_items, f"Expected an extraneous_input_variable item, got {[(i.category, i.error_type) for i in items]}"+ item = extraneous_items[0]+ assert item.category == ValidationErrorCategory.BLUEPRINT_VALIDATION+ assert item.variable_names == [unread_input]+ assert item.pipe_code == pipe_code+ assert item.domain_code == domain_code+ assert item.source == str(bundle_path)+ assert item.suggested_fix is None++ async def test_compose_undeclared_variable_is_a_categorized_missing_input_item(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """A PipeCompose template reading an undeclared variable carries its error_type and the variable's name."""+ load_empty_library()+ items = await _validation_errors_for(_COMPOSE_UNDECLARED_VARIABLE_MTHDS)+ missing_items = [item for item in items if item.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE]+ assert missing_items, f"Expected a missing_input_variable item, got {[(i.category, i.error_type) for i in items]}"+ item = missing_items[0]+ assert item.pipe_code == "render_note"+ assert item.variable_names == ["audience"]++ async def test_unread_input_is_refused_on_the_step_not_spread_to_its_controller(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """The step is refused for its unread input before its controller is asked to supply it, so no+ fix proposes widening the sequence's inputs with an input nothing reads.+ """+ load_empty_library()+ items = await _validation_errors_for(_SEQUENCE_OVER_UNREAD_INPUT_MTHDS)+ extraneous_items = [item for item in items if item.error_type == PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE]+ assert extraneous_items, f"Expected an extraneous_input_variable item, got {[(i.category, i.error_type) for i in items]}"+ assert extraneous_items[0].pipe_code == "render_note"+ assert extraneous_items[0].variable_names == ["unused"]+ assert all(item.suggested_fix is None for item in items), [item.suggested_fix for item in items]++ async def test_llm_unread_inputs_are_named_without_quotes(+ self,+ load_empty_library: Callable[[], str],+ ) -> None:+ """The extraneous item's variable_names are the input names, never fragments of a quoted message."""+ load_empty_library()+ items = await _validation_errors_for(_EXTRANEOUS_INPUT_MTHDS)+ extraneous_items = [item for item in items if item.error_type == PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE]+ assert extraneous_items+ assert extraneous_items[0].variable_names == ["unused_thing"]diff --git a/tests/integration/pipelex/pipes/optionals/test_optional_guard_lint.py b/tests/integration/pipelex/pipes/optionals/test_optional_guard_lint.pyindex 32143c1a9..cc97e56da 100644--- a/tests/integration/pipelex/pipes/optionals/test_optional_guard_lint.py+++ b/tests/integration/pipelex/pipes/optionals/test_optional_guard_lint.py@@ -231,9 +231,13 @@ class TestOptionalGuardLint:exactly once. When PipeCompose stored the already-preprocessed template instead, thelint's own `rewrite_template_sigils` ran a second time and resurrected the escapedliteral (`$$maybe_note` → `$maybe_note` → `{{ maybe_note|format() }}`), wrongly raising- OPTIONAL_INPUT_UNGUARDED on a pipe that never references the optional input.+ OPTIONAL_INPUT_UNGUARDED on a pipe whose only unguarded mention of the optional input is the literal.++ The template also reads the input under a guard, since a declared input no template reads is+ refused on its own account; the only reference outside the guard is the escaped literal."""load_empty_library()+ template = "The literal token is $$maybe_note here.{% if maybe_note %} Note: {{ maybe_note }}{% endif %}"compose = PipeFactory[PipeCompose].make_from_blueprint(domain_code=_DOMAIN_CODE,pipe_code="guard_lint_compose_escaped",@@ -241,9 +245,9 @@ class TestOptionalGuardLint:description="Compose whose template escapes a literal `$` before an optional input's name",inputs={"maybe_note": "Text?"},output="Text",- template="The literal token is $$maybe_note here.",+ template=template,),)assert compose.code == "guard_lint_compose_escaped"# The stored template stays authored (escaped), so a single downstream rewrite keeps it literal.- assert compose.template == "The literal token is $$maybe_note here."+ assert compose.template == templatediff --git a/tests/unit/pipelex/pipe_operators/input_check_helpers.py b/tests/unit/pipelex/pipe_operators/input_check_helpers.pynew file mode 100644index 000000000..95a8de0ef--- /dev/null+++ b/tests/unit/pipelex/pipe_operators/input_check_helpers.py@@ -0,0 +1,25 @@+from typing import Any++import pytest+from pydantic import ValidationError++from pipelex.core.pipes.exceptions import PipeValidationError+from pipelex.mthds_parsing.handle_pipe_errors import extract_wrapped_pipe_validation_error+from pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint+++def refused_input_error(*, blueprint_class: type[PipeBlueprint], blueprint_kwargs: dict[str, Any]) -> PipeValidationError:+ """Build a blueprint that the input check must refuse, and return the structured error it raised.++ The operator blueprints raise a ``PipeValidationError`` inside a pydantic model validator, so the+ error reaches the caller wrapped in a ``ValidationError``; the test asserts on the wrapped error's+ ``error_type`` and ``variable_names``, never on its message text.+ """+ with pytest.raises(ValidationError) as exc_info:+ blueprint_class.model_validate(blueprint_kwargs)+ for error_details in exc_info.value.errors():+ wrapped = extract_wrapped_pipe_validation_error(error_details)+ if wrapped is not None:+ return wrapped+ msg = f"No wrapped PipeValidationError found in: {exc_info.value}"+ raise AssertionError(msg)diff --git a/tests/unit/pipelex/pipe_operators/pipe_compose/data.py b/tests/unit/pipelex/pipe_operators/pipe_compose/data.pyindex ff93e2958..aa2709f1f 100644--- a/tests/unit/pipelex/pipe_operators/pipe_compose/data.py+++ b/tests/unit/pipelex/pipe_operators/pipe_compose/data.py@@ -1,8 +1,9 @@-from typing import ClassVar+from typing import Any, ClassVarfrom pipelex.cogt.templating.template_blueprint import TemplateBlueprintfrom pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprintfrom pipelex.tools.jinja2.template_category import TemplateCategory+from pipelex.validation_error_types import PipeValidationErrorTypeclass PipeComposeInputTestCases:@@ -94,3 +95,174 @@ class PipeComposeInputTestCases:VALID_WITH_HTML_TEMPLATE,VALID_COMPLEX_JINJA2,]+++class PipeComposeInputCheckTestCases:+ """Cases for the blueprint input check: every declared input is read, and every variable read is declared.++ A refused case is (test_id, blueprint kwargs, expected error_type, expected variable_names); an accepted+ case is (test_id, blueprint kwargs). Kwargs rather than built blueprints, since a refused one cannot be built.+ """++ REFUSED_TEMPLATE_ONE_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "template_one_unread",+ {"description": "d", "inputs": {"topic": "Text", "unused": "Text"}, "output": "Text", "template": "About $topic"},+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["unused"],+ )++ REFUSED_TEMPLATE_TWO_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "template_two_unread",+ {"description": "d", "inputs": {"topic": "Text", "bbb": "Text", "aaa": "Text"}, "output": "Text", "template": "About $topic"},+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["aaa", "bbb"],+ )++ REFUSED_TEMPLATE_BLUEPRINT_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "template_blueprint_unread",+ {+ "description": "d",+ "inputs": {"content": "Text", "unused": "Text"},+ "output": "Text",+ "template": {"template": "# Title\n\n{{ content }}", "category": "markdown"},+ },+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["unused"],+ )++ REFUSED_TEMPLATE_UNDECLARED: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "template_undeclared",+ {"description": "d", "inputs": {"topic": "Text"}, "output": "Text", "template": "About $topic and $other"},+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["other"],+ )++ REFUSED_CONSTRUCT_ONE_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "construct_one_unread",+ {+ "description": "d",+ "inputs": {"deal": "Deal", "unused": "Text"},+ "output": "Summary",+ "construct": {"customer_name": {"from": "deal.customer_name"}, "label": {"template": "Deal $deal.amount"}},+ },+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["unused"],+ )++ REFUSED_CONSTRUCT_TWO_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "construct_two_unread",+ {+ "description": "d",+ "inputs": {"deal": "Deal", "bbb": "Text", "aaa": "Text"},+ "output": "Summary",+ "construct": {"customer_name": {"from": "deal.customer_name"}},+ },+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["aaa", "bbb"],+ )++ REFUSED_CONSTRUCT_UNDECLARED_FROM: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "construct_undeclared_from",+ {+ "description": "d",+ "inputs": {"deal": "Deal"},+ "output": "Summary",+ "construct": {"customer_name": {"from": "deal.customer_name"}, "owner": {"from": "other.name"}},+ },+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["other"],+ )++ REFUSED_CONSTRUCT_UNDECLARED_NESTED_TEMPLATE: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "construct_undeclared_nested_template",+ {+ "description": "d",+ "inputs": {"deal": "Deal"},+ "output": "Summary",+ "construct": {"customer_name": {"from": "deal.customer_name"}, "address": {"line": {"template": "$place.city"}}},+ },+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["place"],+ )++ # A dotted input name alone does not supply the stuff its path is read from: the root must be declared+ REFUSED_TEMPLATE_LONE_DOTTED_INPUT: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "template_lone_dotted_input",+ {"description": "d", "inputs": {"deal.amount": "Number"}, "output": "Text", "template": "Worth $deal.amount"},+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["deal"],+ )++ REFUSED_CONSTRUCT_LONE_DOTTED_INPUT: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "construct_lone_dotted_input",+ {"description": "d", "inputs": {"page.page_view": "Image"}, "output": "Summary", "construct": {"view": {"from": "page.page_view"}}},+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["page"],+ )++ REFUSED_CASES: ClassVar[list[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]]] = [+ REFUSED_TEMPLATE_ONE_UNREAD,+ REFUSED_TEMPLATE_TWO_UNREAD,+ REFUSED_TEMPLATE_BLUEPRINT_UNREAD,+ REFUSED_TEMPLATE_UNDECLARED,+ REFUSED_CONSTRUCT_ONE_UNREAD,+ REFUSED_CONSTRUCT_TWO_UNREAD,+ REFUSED_CONSTRUCT_UNDECLARED_FROM,+ REFUSED_CONSTRUCT_UNDECLARED_NESTED_TEMPLATE,+ REFUSED_TEMPLATE_LONE_DOTTED_INPUT,+ REFUSED_CONSTRUCT_LONE_DOTTED_INPUT,+ ]++ ACCEPTED_CASES: ClassVar[list[tuple[str, dict[str, Any]]]] = [+ ("dollar_sigil", {"description": "d", "inputs": {"name": "Text"}, "output": "Text", "template": "Hello $name!"}),+ ("at_block", {"description": "d", "inputs": {"name": "Text"}, "output": "Text", "template": "Hello:\n@name\n"}),+ ("guarded_at_block_on_optional", {"description": "d", "inputs": {"note": "Text?"}, "output": "Text", "template": "Notes:\n@?note\n"}),+ (+ "jinja2_if",+ {"description": "d", "inputs": {"note": "Text?"}, "output": "Text", "template": "{% if note %}{{ note }}{% else %}none{% endif %}"},+ ),+ ("jinja2_if_only", {"description": "d", "inputs": {"flag": "Text?"}, "output": "Text", "template": "{% if flag %}flagged{% endif %}"}),+ ("dotted_path", {"description": "d", "inputs": {"deal": "Deal"}, "output": "Text", "template": "Worth $deal.amount"}),+ (+ "for_loop",+ {"description": "d", "inputs": {"items": "Text[]"}, "output": "Text", "template": "{% for item in items %}{{ item }}{% endfor %}"},+ ),+ (+ "construct_from_path",+ {"description": "d", "inputs": {"deal": "Deal"}, "output": "Summary", "construct": {"name": {"from": "deal.customer_name"}}},+ ),+ (+ "construct_nested_template",+ {+ "description": "d",+ "inputs": {"hq": "Office"},+ "output": "Summary",+ "construct": {"headquarters": {"country": "France", "phone": {"template": "+$hq.country_code $hq.phone"}}},+ },+ ),+ (+ "construct_dotted_input_name",+ {+ "description": "d",+ "inputs": {"page": "Page", "page.page_view": "Image"},+ "output": "Summary",+ "construct": {"view": {"from": "page.page_view"}, "text": {"from": "page.text_and_images"}},+ },+ ),+ (+ "attribute_after_subscript",+ {"description": "d", "inputs": {"items": "Text[]"}, "output": "Text", "template": "First: {{ items[0].text }}"},+ ),+ (+ "self_referential_set",+ {"description": "d", "inputs": {"topic": "Text"}, "output": "Text", "template": "{% set topic = topic|trim %}About {{ topic }}"},+ ),+ (+ "input_named_like_a_jinja_global",+ {"description": "d", "inputs": {"namespace": "Text"}, "output": "Text", "template": "List the pods in $namespace"},+ ),+ (+ "construct_attribute_after_subscript",+ {"description": "d", "inputs": {"items": "Text[]"}, "output": "Summary", "construct": {"first": {"template": "{{ items[0].text }}"}}},+ ),+ ]diff --git a/tests/unit/pipelex/pipe_operators/pipe_compose/test_pipe_compose_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_compose/test_pipe_compose_blueprint.pyindex e69de29bb..9b48f2de8 100644--- a/tests/unit/pipelex/pipe_operators/pipe_compose/test_pipe_compose_blueprint.py+++ b/tests/unit/pipelex/pipe_operators/pipe_compose/test_pipe_compose_blueprint.py@@ -0,0 +1,43 @@+from typing import Any++import pytest++from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint+from pipelex.validation_error_types import PipeValidationErrorType+from tests.unit.pipelex.pipe_operators.input_check_helpers import refused_input_error+from tests.unit.pipelex.pipe_operators.pipe_compose.data import PipeComposeInputCheckTestCases+++class TestPipeComposeBlueprintInputCheck:+ @pytest.mark.parametrize(+ ("test_id", "blueprint_kwargs", "expected_error_type", "expected_variable_names"),+ PipeComposeInputCheckTestCases.REFUSED_CASES,+ )+ def test_refused(+ self,+ test_id: str,+ blueprint_kwargs: dict[str, Any],+ expected_error_type: PipeValidationErrorType,+ expected_variable_names: list[str],+ ):+ error = refused_input_error(blueprint_class=PipeComposeBlueprint, blueprint_kwargs=blueprint_kwargs)+ assert error.error_type == expected_error_type, test_id+ assert error.variable_names == expected_variable_names, test_id++ @pytest.mark.parametrize(+ ("test_id", "blueprint_kwargs"),+ PipeComposeInputCheckTestCases.ACCEPTED_CASES,+ )+ def test_accepted(self, test_id: str, blueprint_kwargs: dict[str, Any]):+ blueprint = PipeComposeBlueprint.model_validate(blueprint_kwargs)+ assert set(blueprint.input_names) == set(blueprint_kwargs["inputs"]), test_id++ def test_unread_input_message_names_both_remedies(self):+ error = refused_input_error(+ blueprint_class=PipeComposeBlueprint,+ blueprint_kwargs=PipeComposeInputCheckTestCases.REFUSED_TEMPLATE_ONE_UNREAD[1],+ )+ message = str(error)+ assert "'unused'" in message+ assert "Reference it in the template" in message+ assert "remove it from `inputs`" in messagediff --git a/tests/unit/pipelex/pipe_operators/pipe_img_gen/data.py b/tests/unit/pipelex/pipe_operators/pipe_img_gen/data.pyindex dc847bf9e..724e5baa8 100644--- a/tests/unit/pipelex/pipe_operators/pipe_img_gen/data.py+++ b/tests/unit/pipelex/pipe_operators/pipe_img_gen/data.py@@ -1,8 +1,9 @@-from typing import ClassVar+from typing import Any, ClassVarfrom pipelex.cogt.img_gen.img_gen_job_components import AspectRatio, Backgroundfrom pipelex.pipe_operators.img_gen.pipe_img_gen_blueprint import PipeImgGenBlueprintfrom pipelex.tools.misc.image_utils import ImageFormat+from pipelex.validation_error_types import PipeValidationErrorTypeclass PipeImgGenInputTestCases:@@ -116,3 +117,93 @@ class PipeImgGenInputTestCases:VALID_WITH_OUTPUT_FORMAT,VALID_WITH_IS_RAW,]+++class PipeImgGenInputCheckTestCases:+ """Cases for the blueprint input check over `prompt` and `negative_prompt`.++ A refused case is (test_id, blueprint kwargs, expected error_type, expected variable_names); an accepted+ case is (test_id, blueprint kwargs).+ """++ REFUSED_ONE_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "one_unread",+ {"description": "d", "inputs": {"topic": "Text", "unused": "Text"}, "output": "Image", "prompt": "Sketch of $topic"},+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["unused"],+ )++ REFUSED_TWO_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "two_unread",+ {"description": "d", "inputs": {"topic": "Text", "bbb": "Text", "aaa": "Text"}, "output": "Image", "prompt": "Sketch of $topic"},+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["aaa", "bbb"],+ )++ REFUSED_UNREAD_IMAGE: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "unread_image",+ {"description": "d", "inputs": {"image": "Image"}, "output": "Image", "prompt": "A small thumbnail"},+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["image"],+ )++ REFUSED_UNDECLARED: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "undeclared",+ {"description": "d", "inputs": {"topic": "Text"}, "output": "Image", "prompt": "Sketch of $topic and $other"},+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["other"],+ )++ REFUSED_UNDECLARED_IN_NEGATIVE_PROMPT: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "undeclared_in_negative_prompt",+ {"description": "d", "inputs": {"topic": "Text"}, "output": "Image", "prompt": "Sketch of $topic", "negative_prompt": "No $avoid"},+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["avoid"],+ )++ # A dotted input name alone does not supply the stuff its path is read from: the root must be declared+ REFUSED_LONE_DOTTED_INPUT: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "lone_dotted_input",+ {"description": "d", "inputs": {"scene.subject": "Text"}, "output": "Image", "prompt": "Sketch of $scene.subject"},+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["scene"],+ )++ REFUSED_CASES: ClassVar[list[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]]] = [+ REFUSED_ONE_UNREAD,+ REFUSED_TWO_UNREAD,+ REFUSED_UNREAD_IMAGE,+ REFUSED_UNDECLARED,+ REFUSED_UNDECLARED_IN_NEGATIVE_PROMPT,+ REFUSED_LONE_DOTTED_INPUT,+ ]++ ACCEPTED_CASES: ClassVar[list[tuple[str, dict[str, Any]]]] = [+ ("dollar_sigil", {"description": "d", "inputs": {"topic": "Text"}, "output": "Image", "prompt": "Sketch of $topic"}),+ ("at_block", {"description": "d", "inputs": {"prompt": "Text"}, "output": "Image", "prompt": "@prompt"}),+ ("image_reference", {"description": "d", "inputs": {"image": "Image"}, "output": "Image", "prompt": "A thumbnail of $image"}),+ (+ "read_only_by_negative_prompt",+ {+ "description": "d",+ "inputs": {"topic": "Text", "avoid": "Text"},+ "output": "Image",+ "prompt": "Sketch of $topic",+ "negative_prompt": "No $avoid",+ },+ ),+ (+ "attribute_after_key",+ {"description": "d", "inputs": {"record": "Record"}, "output": "Image", "prompt": "Sketch of {{ record['meta'].title }}"},+ ),+ (+ "self_referential_set_in_negative_prompt",+ {+ "description": "d",+ "inputs": {"topic": "Text", "avoid": "Text"},+ "output": "Image",+ "prompt": "Sketch of $topic",+ "negative_prompt": "{% set avoid = avoid|trim %}No {{ avoid }}",+ },+ ),+ ]diff --git a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_blueprint.pyindex 9af15d72e..f6b64002a 100644--- a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_blueprint.py+++ b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_blueprint.py@@ -1,9 +1,14 @@+from typing import Any+import pytestfrom pydantic import ValidationErrorfrom pipelex.cogt.image.image_size import ImageSizefrom pipelex.cogt.img_gen.img_gen_job_components import AspectRatio, SizeTierfrom pipelex.pipe_operators.img_gen.pipe_img_gen_blueprint import PipeImgGenBlueprint+from pipelex.validation_error_types import PipeValidationErrorType+from tests.unit.pipelex.pipe_operators.input_check_helpers import refused_input_error+from tests.unit.pipelex.pipe_operators.pipe_img_gen.data import PipeImgGenInputCheckTestCasesclass TestPipeImgGenBlueprint:@@ -27,14 +32,40 @@ class TestPipeImgGenBlueprint:assert blueprint.input_names == ["topic"]def test_validate_inputs_incorrect(self):- with pytest.raises(ValidationError) as exc_info:- PipeImgGenBlueprint(- description="lorem ipsum",- inputs={"topic": "Text"},- output="Image",- prompt="Sketch black and white illustration of: $bingo",- )- assert "Missing input variable(s) in prompt template: bingo" in str(exc_info.value)+ error = refused_input_error(+ blueprint_class=PipeImgGenBlueprint,+ blueprint_kwargs={+ "description": "lorem ipsum",+ "inputs": {"topic": "Text"},+ "output": "Image",+ "prompt": "Sketch black and white illustration of: $bingo",+ },+ )+ assert error.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE+ assert error.variable_names == ["bingo"]++ @pytest.mark.parametrize(+ ("test_id", "blueprint_kwargs", "expected_error_type", "expected_variable_names"),+ PipeImgGenInputCheckTestCases.REFUSED_CASES,+ )+ def test_input_check_refused(+ self,+ test_id: str,+ blueprint_kwargs: dict[str, Any],+ expected_error_type: PipeValidationErrorType,+ expected_variable_names: list[str],+ ):+ error = refused_input_error(blueprint_class=PipeImgGenBlueprint, blueprint_kwargs=blueprint_kwargs)+ assert error.error_type == expected_error_type, test_id+ assert error.variable_names == expected_variable_names, test_id++ @pytest.mark.parametrize(+ ("test_id", "blueprint_kwargs"),+ PipeImgGenInputCheckTestCases.ACCEPTED_CASES,+ )+ def test_input_check_accepted(self, test_id: str, blueprint_kwargs: dict[str, Any]):+ blueprint = PipeImgGenBlueprint.model_validate(blueprint_kwargs)+ assert set(blueprint.input_names) == set(blueprint_kwargs["inputs"]), test_iddef test_size_tier_composes_with_aspect_ratio(self):"""A size tier and an aspect_ratio are complementary and may be set together."""diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.pyindex ab838ec08..f6d4da99f 100644--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py@@ -2,6 +2,8 @@ import pytestfrom pydantic import ValidationErrorfrom pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint, StructuringMethod+from pipelex.validation_error_types import PipeValidationErrorType+from tests.unit.pipelex.pipe_operators.input_check_helpers import refused_input_errorclass TestPipeLLMBlueprint:@@ -62,58 +64,126 @@ class TestPipeLLMBlueprint:assert set(blueprint.input_names) == {"topic", "style"}def test_validate_inputs_incorrect_missing_variable(self):- """Test that missing input variable raises ValueError."""- with pytest.raises(ValueError, match="Missing input variable") as exc_info:- PipeLLMBlueprint(- description="lorem ipsum",- inputs={"input_one": "native.Text", "input_two": "native.Text"},- output="native.Text",- prompt="Process $input_one, $input_two, and $input_three",- )- error_msg = str(exc_info.value)- assert "Missing input variable(s):" in error_msg- assert "input_three" in error_msg- assert "not declared in inputs" in error_msg+ """A variable the prompt reads but no input declares is refused, and the error names it."""+ error = refused_input_error(+ blueprint_class=PipeLLMBlueprint,+ blueprint_kwargs={+ "description": "lorem ipsum",+ "inputs": {"input_one": "native.Text", "input_two": "native.Text"},+ "output": "native.Text",+ "prompt": "Process $input_one, $input_two, and $input_three",+ },+ )+ assert error.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE+ assert error.variable_names == ["input_three"]+ assert "not declared in `inputs`" in str(error)def test_validate_inputs_incorrect_missing_multiple_variables(self):- """Test that multiple missing variables are all reported."""- with pytest.raises(ValueError, match="Missing input variable") as exc_info:- PipeLLMBlueprint(- description="lorem ipsum",- inputs={"input_one": "native.Text"},- output="native.Text",- prompt="Process $input_one, $input_two, and $input_three",- )- error_msg = str(exc_info.value)- assert "Missing input variable(s):" in error_msg- assert "input_two" in error_msg- assert "input_three" in error_msg+ """Every missing variable is reported, sorted."""+ error = refused_input_error(+ blueprint_class=PipeLLMBlueprint,+ blueprint_kwargs={+ "description": "lorem ipsum",+ "inputs": {"input_one": "native.Text"},+ "output": "native.Text",+ "prompt": "Process $input_one, $input_two, and $input_three",+ },+ )+ assert error.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE+ assert error.variable_names == ["input_three", "input_two"]def test_validate_inputs_incorrect_missing_in_system_prompt(self):- """Test that missing variables in system_prompt are caught."""- with pytest.raises(ValueError, match="Missing input variable") as exc_info:- PipeLLMBlueprint(- description="lorem ipsum",- inputs={"query": "native.Text"},- output="native.Text",- system_prompt="Use context: $context",- prompt="Answer: $query",- )- error_msg = str(exc_info.value)- assert "Missing input variable(s):" in error_msg- assert "context" in error_msg+ """Missing variables in system_prompt are caught."""+ error = refused_input_error(+ blueprint_class=PipeLLMBlueprint,+ blueprint_kwargs={+ "description": "lorem ipsum",+ "inputs": {"query": "native.Text"},+ "output": "native.Text",+ "system_prompt": "Use context: $context",+ "prompt": "Answer: $query",+ },+ )+ assert error.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE+ assert error.variable_names == ["context"]def test_validate_inputs_incorrect_empty_inputs_with_variables(self):- """Test that variables in prompt require inputs to be declared."""- with pytest.raises((ValidationError, ValueError)) as exc_info:- PipeLLMBlueprint(- description="lorem ipsum",- inputs={},- output="native.Text",- prompt="Process $data",- )- error_msg = str(exc_info.value)- assert "Missing input variable(s):" in error_msg or "data" in error_msg+ """Variables in the prompt require inputs to be declared."""+ error = refused_input_error(+ blueprint_class=PipeLLMBlueprint,+ blueprint_kwargs={"description": "lorem ipsum", "inputs": {}, "output": "native.Text", "prompt": "Process $data"},+ )+ assert error.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE+ assert error.variable_names == ["data"]++ def test_validate_inputs_incorrect_unread_inputs_are_named_plainly(self):+ """Unread inputs are all reported, sorted and unquoted: the names are data, not message text."""+ error = refused_input_error(+ blueprint_class=PipeLLMBlueprint,+ blueprint_kwargs={+ "description": "lorem ipsum",+ "inputs": {"topic": "native.Text", "bbb": "native.Text", "aaa": "native.Text"},+ "output": "native.Text",+ "prompt": "Write about $topic",+ },+ )+ assert error.error_type == PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE+ assert error.variable_names == ["aaa", "bbb"]+ assert "Reference them in the prompt or system_prompt" in str(error)++ def test_validate_inputs_correct_with_dotted_input_name(self):+ """A dotted input name is read by the path it names, and its root input by another path."""+ blueprint = PipeLLMBlueprint(+ description="lorem ipsum",+ inputs={"page": "Page", "page.page_view": "native.Image"},+ output="native.Text",+ prompt="Describe:\[email protected]_view\n\nText: $page.text_and_images.text.text",+ )+ assert set(blueprint.input_names) == {"page", "page.page_view"}++ def test_validate_inputs_correct_with_lone_dotted_input_name(self):+ """PipeLLM resolves a dotted input name as that attribute of the stuff, so it needs no root input beside it."""+ blueprint = PipeLLMBlueprint(+ description="lorem ipsum",+ inputs={"page.page_view": "native.Image"},+ output="native.Text",+ prompt="Describe $page.page_view",+ )+ assert set(blueprint.input_names) == {"page.page_view"}++ def test_validate_inputs_incorrect_read_beside_lone_dotted_input_name(self):+ """A dotted input name supplies its own path only, not the other attributes of its root."""+ error = refused_input_error(+ blueprint_class=PipeLLMBlueprint,+ blueprint_kwargs={+ "description": "lorem ipsum",+ "inputs": {"page.page_view": "native.Image"},+ "output": "native.Text",+ "prompt": "Describe $page.page_view in the light of $page.title",+ },+ )+ assert error.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE+ assert error.variable_names == ["page"]++ def test_validate_inputs_correct_with_attribute_after_subscript(self):+ """An input read only through a subscript followed by an attribute counts as read."""+ blueprint = PipeLLMBlueprint(+ description="lorem ipsum",+ inputs={"items": "native.Text[]"},+ output="native.Text",+ prompt="Summarize {{ items[0].text }}",+ )+ assert set(blueprint.input_names) == {"items"}++ def test_validate_inputs_correct_with_input_named_like_a_jinja_global(self):+ """An input named like a Jinja global shadows it, so reading the name reads the input."""+ blueprint = PipeLLMBlueprint(+ description="lorem ipsum",+ inputs={"range": "native.Text"},+ output="native.Text",+ prompt="Summarize the price range: $range",+ )+ assert set(blueprint.input_names) == {"range"}def test_validate_inputs_ignores_internal_variables(self):"""Test that internal variables (starting with _) are ignored."""diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.pyindex 2e8653df9..3b0feaaa8 100644--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py@@ -6,7 +6,7 @@ from typing import Callableimport pytestfrom pipelex.kernel.prompt_references import ImageReferenceKind-from pipelex.pipe_operators.shared.exceptions import UnusedInputError, WithImagesFilterError+from pipelex.pipe_operators.shared.exceptions import WithImagesFilterErrorfrom pipelex.pipe_operators.shared.template_image_analyzer import TemplateImageAnalyzer@@ -270,47 +270,3 @@ class TestTemplateImageAnalyzer:input_specs={"dynamic_in": "Dynamic"},domain_code="test_pipes",)---class TestValidateUnusedInputs:- """Tests for TemplateImageAnalyzer.validate_unused_inputs()."""-- def test_all_inputs_used_passes(self, load_test_library: Callable[[list[Path]], None]) -> None:- """Test that validation passes when all inputs are used."""- load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])-- # Should not raise- TemplateImageAnalyzer.validate_unused_inputs(- template_sources=["Process $name and $age"],- input_specs={"name": "Text", "age": "Text"},- )-- def test_unused_input_raises(self, load_test_library: Callable[[list[Path]], None]) -> None:- """Test that unused input raises error."""- load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])-- with pytest.raises(UnusedInputError, match="unused_var"):- TemplateImageAnalyzer.validate_unused_inputs(- template_sources=["Process $name"],- input_specs={"name": "Text", "unused_var": "Text"},- )-- def test_input_used_in_second_template_passes(self, load_test_library: Callable[[list[Path]], None]) -> None:- """Test that input used in any template passes validation."""- load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])-- # name in first, age in second - both should pass- TemplateImageAnalyzer.validate_unused_inputs(- template_sources=["Hello $name", "You are $age years old"],- input_specs={"name": "Text", "age": "Text"},- )-- def test_nested_path_counts_as_used(self, load_test_library: Callable[[list[Path]], None]) -> None:- """Test that nested path usage counts the root variable as used."""- load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])-- # page.page_view should count page as used- TemplateImageAnalyzer.validate_unused_inputs(- template_sources=["Look at $page.page_view"],- input_specs={"page": "Page"},- )diff --git a/tests/unit/pipelex/pipe_operators/pipe_search/data.py b/tests/unit/pipelex/pipe_operators/pipe_search/data.pynew file mode 100644index 000000000..dec8e5df1--- /dev/null+++ b/tests/unit/pipelex/pipe_operators/pipe_search/data.py@@ -0,0 +1,70 @@+from typing import Any, ClassVar++from pipelex.validation_error_types import PipeValidationErrorType+++class PipeSearchInputCheckTestCases:+ """Cases for the blueprint input check: every declared input is read by the prompt, and every variable it reads is declared.++ A refused case is (test_id, blueprint kwargs, expected error_type, expected variable_names); an accepted+ case is (test_id, blueprint kwargs).+ """++ REFUSED_ONE_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "one_unread",+ {"description": "d", "inputs": {"topic": "Text", "unused": "Text"}, "output": "SearchResult", "prompt": "Latest news on $topic"},+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["unused"],+ )++ REFUSED_TWO_UNREAD: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "two_unread",+ {"description": "d", "inputs": {"topic": "Text", "bbb": "Text", "aaa": "Text"}, "output": "SearchResult", "prompt": "News on $topic"},+ PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,+ ["aaa", "bbb"],+ )++ REFUSED_UNDECLARED: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "undeclared",+ {"description": "d", "inputs": {"topic": "Text"}, "output": "SearchResult", "prompt": "News on $topic and $other"},+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["other"],+ )++ # A dotted input name alone does not supply the stuff its path is read from: the root must be declared+ REFUSED_LONE_DOTTED_INPUT: ClassVar[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]] = (+ "lone_dotted_input",+ {"description": "d", "inputs": {"company.name": "Text"}, "output": "SearchResult", "prompt": "News on $company.name"},+ PipeValidationErrorType.MISSING_INPUT_VARIABLE,+ ["company"],+ )++ REFUSED_CASES: ClassVar[list[tuple[str, dict[str, Any], PipeValidationErrorType, list[str]]]] = [+ REFUSED_ONE_UNREAD,+ REFUSED_TWO_UNREAD,+ REFUSED_UNDECLARED,+ REFUSED_LONE_DOTTED_INPUT,+ ]++ ACCEPTED_CASES: ClassVar[list[tuple[str, dict[str, Any]]]] = [+ ("no_inputs", {"description": "d", "output": "SearchResult", "prompt": "Latest AI news"}),+ ("dollar_sigil", {"description": "d", "inputs": {"topic": "Text"}, "output": "SearchResult", "prompt": "News on $topic"}),+ ("dotted_path", {"description": "d", "inputs": {"company": "Company"}, "output": "SearchResult", "prompt": "News on $company.name"}),+ (+ "jinja2_if_on_optional",+ {+ "description": "d",+ "inputs": {"topic": "Text", "region": "Text?"},+ "output": "SearchResult",+ "prompt": "News on $topic{% if region %} in {{ region }}{% endif %}",+ },+ ),+ (+ "attribute_after_filter",+ {"description": "d", "inputs": {"items": "Text[]"}, "output": "SearchResult", "prompt": "News on {{ (items|first).text }}"},+ ),+ (+ "self_referential_set",+ {"description": "d", "inputs": {"topic": "Text"}, "output": "SearchResult", "prompt": "{% set topic = topic|trim %}News on {{ topic }}"},+ ),+ ]diff --git a/tests/unit/pipelex/pipe_operators/pipe_search/test_pipe_search_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_search/test_pipe_search_blueprint.pynew file mode 100644index 000000000..66d3ed0d9--- /dev/null+++ b/tests/unit/pipelex/pipe_operators/pipe_search/test_pipe_search_blueprint.py@@ -0,0 +1,33 @@+from typing import Any++import pytest++from pipelex.pipe_operators.search.pipe_search_blueprint import PipeSearchBlueprint+from pipelex.validation_error_types import PipeValidationErrorType+from tests.unit.pipelex.pipe_operators.input_check_helpers import refused_input_error+from tests.unit.pipelex.pipe_operators.pipe_search.data import PipeSearchInputCheckTestCases+++class TestPipeSearchBlueprintInputCheck:+ @pytest.mark.parametrize(+ ("test_id", "blueprint_kwargs", "expected_error_type", "expected_variable_names"),+ PipeSearchInputCheckTestCases.REFUSED_CASES,+ )+ def test_refused(+ self,+ test_id: str,+ blueprint_kwargs: dict[str, Any],+ expected_error_type: PipeValidationErrorType,+ expected_variable_names: list[str],+ ):+ error = refused_input_error(blueprint_class=PipeSearchBlueprint, blueprint_kwargs=blueprint_kwargs)+ assert error.error_type == expected_error_type, test_id+ assert error.variable_names == expected_variable_names, test_id++ @pytest.mark.parametrize(+ ("test_id", "blueprint_kwargs"),+ PipeSearchInputCheckTestCases.ACCEPTED_CASES,+ )+ def test_accepted(self, test_id: str, blueprint_kwargs: dict[str, Any]):+ blueprint = PipeSearchBlueprint.model_validate(blueprint_kwargs)+ assert set(blueprint.input_names) == set(blueprint_kwargs.get("inputs") or {}), test_iddiff --git a/tests/unit/pipelex/tools/test_jinja2_required_variables.py b/tests/unit/pipelex/tools/test_jinja2_required_variables.pyindex e5ee01fdd..dd9e2eb01 100644--- a/tests/unit/pipelex/tools/test_jinja2_required_variables.py+++ b/tests/unit/pipelex/tools/test_jinja2_required_variables.py@@ -199,6 +199,55 @@ Best regards,),]+ # A path stops at a subscript, a call or a filter, and the read before it still counts+ CHAINED_ACCESS: ClassVar[list[tuple[str, str, set[str]]]] = [+ ("attribute_after_subscript", "{{ items[0].text }}", {"items"}),+ ("attribute_after_subscript_on_a_path", "{{ a.items[0].name }}", {"a.items"}),+ ("attribute_after_key", "{{ record['meta'].title }}", {"record"}),+ ("attribute_after_call", "{{ a.get('k').x }}", {"a.get"}),+ ("attribute_after_filter", "{{ (items|first).text }}", {"items"}),+ ("attribute_after_subscript_on_a_loop_variable", "{% for row in rows %}{{ row[0].text }}{% endfor %}", {"rows"}),+ ]++ # A `set` declares its name from that statement on, so what it reads, and a read before it, are required+ ASSIGNMENT_ORDER: ClassVar[list[tuple[str, str, set[str]]]] = [+ ("self_referential_set", "{% set topic = topic|trim %}{{ topic }}", {"topic"}),+ ("read_before_set", "{{ note }}{% set note = 'x' %}{{ note }}", {"note"}),+ ("read_after_set", "{% set note = 'x' %}{{ note }}", set()),+ ("read_after_block_set", "{% set note %}{{ body }}{% endset %}{{ note }}", {"body"}),+ ("macro_reads_a_later_set", "{{ x }}{% macro m() %}[{{ g }}]{% endmacro %}{% set g = 'y' %}{{ m() }}", {"x"}),+ ]++ # Names Jinja provides, and the scope a loop opens, are never inputs+ SCOPES: ClassVar[list[tuple[str, str, set[str]]]] = [+ ("namespace_idiom", "{% set ns = namespace(found=false) %}{{ ns.found }}", set()),+ ("global_followed_by_attribute", "{{ dict(a=1).a }}", set()),+ ("global_called_on_an_input", "{{ range(count) }}", {"count"}),+ ("macro_internal_names", "{% macro m() %}{{ caller().strip() }}{{ varargs }}{{ kwargs }}{% endmacro %}", set()),+ ("loop_target_shadows_its_iterable", "{% for item in item %}{{ item }}{% endfor %}", {"item"}),+ ("else_branch_reads_outside_the_loop", "{% for x in xs %}{{ x }}{% else %}{{ x }}{% endfor %}", {"xs", "x"}),+ ("loop_filter_reads_inside_the_loop", "{% for x in xs if x.ok %}{{ x }}{% endfor %}", {"xs"}),+ ]++ # A Jinja global is Jinja's only where it is called; any other read of its name reads the input that shadows it+ GLOBAL_NAMES_AS_INPUTS: ClassVar[list[tuple[str, str, set[str]]]] = [+ ("bare_global_name", "Summarize the price {{ range }}", {"range"}),+ ("attribute_on_a_global_name", "{{ namespace.name }}", {"namespace.name"}),+ ("filtered_global_name", "{{ dict|upper }}", {"dict"}),+ ("global_name_read_and_called", "{{ range }}{% for i in range(3) %}{{ i }}{% endfor %}", {"range"}),+ ]++ # The reference walk shares the required-variables walk's scopes, so both see the same names read+ REFERENCE_SCOPES: ClassVar[list[tuple[str, str, set[str]]]] = [+ ("self_referential_set", "{% set image = image %}{{ image }}", {"image"}),+ ("read_before_set", "{{ image }}{% set image = 'x' %}{{ image }}", {"image"}),+ ("loop_target_shadows_its_iterable", "{% for images in images %}{{ images }}{% endfor %}", {"images"}),+ ("else_branch_reads_outside_the_loop", "{% for x in xs %}{{ x }}{% else %}{{ x|upper }}{% endfor %}", {"xs", "x"}),+ ("macro_internal_names", "{% macro m() %}{{ caller() }}{{ varargs }}{% endmacro %}", set()),+ ("global_called_on_an_input", "{{ range(count) }}", {"count"}),+ ("bare_global_name", "{{ range }}", {"range"}),+ ]+TEMPLATE_CATEGORIES: ClassVar[list[TemplateCategory]] = [TemplateCategory.BASIC,TemplateCategory.LLM_PROMPT,@@ -544,6 +593,74 @@ class TestDetectJinja2Variables:)assert result == {"user.profile.name", "config.value"}+ @pytest.mark.parametrize(+ ("topic", "template_source", "expected_variables"),+ TestData.CHAINED_ACCESS,+ )+ def test_chained_access(+ self,+ topic: str,+ template_source: str,+ expected_variables: set[str],+ ):+ """An attribute on a subscript, a call or a filter keeps the read of the path it starts from."""+ result = detect_jinja2_required_variables(+ template_category=TemplateCategory.LLM_PROMPT,+ template_source=template_source,+ )+ assert result == expected_variables, f"Failed for topic: {topic}"++ @pytest.mark.parametrize(+ ("topic", "template_source", "expected_variables"),+ TestData.ASSIGNMENT_ORDER,+ )+ def test_assignment_order(+ self,+ topic: str,+ template_source: str,+ expected_variables: set[str],+ ):+ """A top-level `set` hides its name only from the statements after it."""+ result = detect_jinja2_required_variables(+ template_category=TemplateCategory.LLM_PROMPT,+ template_source=template_source,+ )+ assert result == expected_variables, f"Failed for topic: {topic}"++ @pytest.mark.parametrize(+ ("topic", "template_source", "expected_variables"),+ TestData.SCOPES,+ )+ def test_scopes(+ self,+ topic: str,+ template_source: str,+ expected_variables: set[str],+ ):+ """Jinja's globals, a macro's internal names and a loop's own names are not required variables."""+ result = detect_jinja2_required_variables(+ template_category=TemplateCategory.LLM_PROMPT,+ template_source=template_source,+ )+ assert result == expected_variables, f"Failed for topic: {topic}"++ @pytest.mark.parametrize(+ ("topic", "template_source", "expected_variables"),+ TestData.GLOBAL_NAMES_AS_INPUTS,+ )+ def test_global_names_as_inputs(+ self,+ topic: str,+ template_source: str,+ expected_variables: set[str],+ ):+ """A read of a Jinja global's name that does not call it reads the input of that name, which shadows the global."""+ result = detect_jinja2_required_variables(+ template_category=TemplateCategory.LLM_PROMPT,+ template_source=template_source,+ )+ assert result == expected_variables, f"Failed for topic: {topic}"+class TestDetectJinja2VariableReferences:"""Tests for detect_jinja2_variable_references function that tracks filters."""@@ -687,3 +804,34 @@ class TestDetectJinja2VariableReferences:)assert result == []++ @pytest.mark.parametrize(+ ("topic", "template_source", "expected_paths"),+ TestData.REFERENCE_SCOPES,+ )+ def test_scopes_match_required_variables(+ self,+ topic: str,+ template_source: str,+ expected_paths: set[str],+ ) -> None:+ """The references follow the same scopes as the required variables, so an input the check sees read is found here too."""+ result = detect_jinja2_variable_references(+ template_category=TemplateCategory.LLM_PROMPT,+ template_source=template_source,+ )+ assert {reference.path for reference in result} == expected_paths, f"Failed for topic: {topic}"+ required = detect_jinja2_required_variables(+ template_category=TemplateCategory.LLM_PROMPT,+ template_source=template_source,+ )+ assert required == expected_paths, f"Failed for topic: {topic}"++ def test_loop_references_keep_source_order(self) -> None:+ """A loop's body is walked before its `else` branch, so references, and the images they attach, keep the template's order."""+ result = detect_jinja2_variable_references(+ template_category=TemplateCategory.LLM_PROMPT,+ template_source="{% for x in xs %}{{ body_image }}{{ a|tag }}{% else %}{{ else_image }}{{ a|with_images }}{% endfor %}",+ )+ assert [reference.path for reference in result] == ["xs", "body_image", "a", "else_image"]+ assert result[2].filters == ["tag", "with_images"]