Skip to content

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

Fix/pipe description and more (#540)

Thomas Hebrard14371f35a52c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c86861598..19ba8686b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -42,6 +42,10 @@
- Validation for `PipeSequence`: The multiplicity of the output of the sequence must be the same as the multiplicity of the output of the last step.
- Validation for `PipeFunc`: The multiplicity of the output of the pipe must be the same as the multiplicity of the output of the function: If the multiplicity is true, the return type of the function must be a subclass of `ListContent`. If the multiplicity is false, the return type of the function must not be a subclass of `ListContent`.
+### Fixed
+- Fixed a bug with the validation of the multiplicity of the output of the `PipeCondition`.
+- Fixed a bug with the file names of the structures generated by the `pipelex build structures` command.
+
### Changed
- **`pipelex_inference` replaced by `pipelex_gateway`** with remote model configuration fetching for always-current model support
@@ -67,6 +71,7 @@
- `pipelex doctor` command enhanced to detect outdated `telemetry.toml` formats and suggest fixes
- The `runner`, `structures`, and `inputs` CLI commands now accept `--output-dir` option (defaults to `target_dir`)
- Cost report now displays a note clarifying that it only includes LLM costs
+- `description` field is not Optional anymore in the `PipeAbstract`, `PipeBlueprint` and `PipeSpec` classes.
### Deprecated
@@ -101,6 +106,8 @@
- **New AI models support**: Added GPT-5.1, Claude 4.5 Opus, and Gemini 3 Preview to the available models.
- **Codex Cloud support**: Added support for running Pipelex in Codex Cloud environments with appropriate configuration and testing capabilities.
- **Enhanced file discovery**: Added `force_include_dirs` parameter to the `find_files_in_dir` function. This allows specific directories to be force included in the search even when they are nested within excluded directories. For example, you can now exclude `.venv` while still including `.venv/lib/python3.11/site-packages/pipelex` for loading Pipelex libraries from installed packages.
+- Added validation of the PipeLLM inputs at the blueprint level.
+- Added a xfailed test for `PipeCondition`: if one of the outcome of the pipe is `continue`, it does nothing, but the main stuff still points towards the last step. Therefore when trying to get the main stuff out of the working memory as a specific type, it fails.
### Changed
diff --git a/pipelex/builder/pipe/pipe_spec.py b/pipelex/builder/pipe/pipe_spec.py
index 3da0ffbcd..91bd502d6 100644
--- a/pipelex/builder/pipe/pipe_spec.py
+++ b/pipelex/builder/pipe/pipe_spec.py
@@ -44,7 +44,7 @@ class PipeSpec(StructuredContent):
pipe_category: Any = Field(
description=(f"Pipe category. Validated at runtime, must be one of: {PipeCategory}. Either 'PipeController' or 'PipeOperator'.")
)
- description: str | None = Field(description="Natural language description of the pipe's purpose and functionality.")
+ description: str = Field(description="Natural language description of the pipe's purpose and functionality.")
inputs: dict[str, str] = Field(
description=(
"Input specifications mapping variable names to concept codes with optional multiplicity. "
diff --git a/pipelex/cli/commands/build/structures_cmd.py b/pipelex/cli/commands/build/structures_cmd.py
index cd680fb64..2c9aa4ee1 100644
--- a/pipelex/cli/commands/build/structures_cmd.py
+++ b/pipelex/cli/commands/build/structures_cmd.py
@@ -18,6 +18,7 @@ from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.stuffs.text_content import TextContent
from pipelex.pipeline.validate_bundle import validate_bundle, validate_bundles_from_directory
from pipelex.system.registries.class_registry_utils import ClassRegistryUtils
+from pipelex.tools.misc.string_utils import pascal_case_to_snake_case
if TYPE_CHECKING:
from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint
@@ -99,7 +100,8 @@ def generate_structures_from_blueprints(
msg = f"Error generating structure class for concept '{concept_code}' in domain '{blueprint.domain}': {exc}"
raise PipelexError(msg) from exc
- output_file = output_directory / f"{blueprint.domain}_{concept_code}.py"
+ concept_snake_case = pascal_case_to_snake_case(concept_code)
+ output_file = output_directory / f"{blueprint.domain}__{concept_snake_case}.py"
output_file.write_text(generated_code)
generated_files.append((blueprint.domain, concept_code))
typer.secho(f" ✅ Generated {output_file.name}", fg=typer.colors.GREEN)
@@ -120,7 +122,8 @@ def generate_structures_from_blueprints(
msg = f"Error generating python code for structure class of concept '{concept_code}' in domain '{blueprint.domain}': {exc}"
raise PipelexError(msg) from exc
- output_file = output_directory / f"{blueprint.domain}_{concept_code}.py"
+ concept_snake_case = pascal_case_to_snake_case(concept_code)
+ output_file = output_directory / f"{blueprint.domain}__{concept_snake_case}.py"
output_file.write_text(generated_code)
generated_files.append((blueprint.domain, concept_code))
typer.secho(f" ✅ Generated {output_file.name}", fg=typer.colors.GREEN)
@@ -150,7 +153,8 @@ def generate_structures_from_blueprints(
)
raise PipelexError(msg) from exc
- output_file = output_directory / f"{blueprint.domain}_{concept_code}.py"
+ concept_snake_case = pascal_case_to_snake_case(concept_code)
+ output_file = output_directory / f"{blueprint.domain}__{concept_snake_case}.py"
output_file.write_text(generated_code)
generated_files.append((blueprint.domain, concept_code))
typer.secho(f" ✅ Generated {output_file.name}", fg=typer.colors.GREEN)
@@ -167,7 +171,8 @@ def generate_structures_from_blueprints(
msg = f"Error generating structure class for concept '{concept_code}' in domain '{blueprint.domain}': {exc}"
raise PipelexError(msg) from exc
- output_file = output_directory / f"{blueprint.domain}_{concept_code}.py"
+ concept_snake_case = pascal_case_to_snake_case(concept_code)
+ output_file = output_directory / f"{blueprint.domain}__{concept_snake_case}.py"
output_file.write_text(generated_code)
generated_files.append((blueprint.domain, concept_code))
typer.secho(f" ✅ Generated {output_file.name}", fg=typer.colors.GREEN)
diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.py
index ef807be0e..95f6cfa35 100644
--- a/pipelex/cli/error_handlers.py
+++ b/pipelex/cli/error_handlers.py
@@ -133,6 +133,34 @@ def handle_validate_bundle_error(exc: ValidateBundleError, bundle_path: str | No
if bundle_path:
console.print(f"[bold cyan]Bundle:[/bold cyan] [yellow]{bundle_path}[/yellow]\n")
+
+ # Display blueprint validation errors (e.g., MISSING_INPUT_VARIABLE, EXTRANEOUS_INPUT_VARIABLE from blueprint validation)
+ if exc.pipelex_bundle_blueprint_validation_errors:
+ console.print("[bold cyan]Blueprint Validation Errors:[/bold cyan]\n")
+ for error_index, blueprint_error in enumerate(exc.pipelex_bundle_blueprint_validation_errors, 1):
+ error_type_display = blueprint_error.error_type.replace("_", " ").title() if blueprint_error.error_type else "Validation Error"
+ console.print(f"[bold yellow]{error_index}. {error_type_display}[/bold yellow]")
+
+ # Display key identification info
+ if blueprint_error.pipe_code:
+ console.print(f" [cyan]Pipe:[/cyan] [yellow]{blueprint_error.pipe_code}[/yellow]")
+ if blueprint_error.domain_code:
+ console.print(f" [cyan]Domain:[/cyan] [green]{blueprint_error.domain_code}[/green]")
+
+ # Variables
+ if blueprint_error.variable_names:
+ variables_str = ", ".join([f"[yellow]{v}[/yellow]" for v in blueprint_error.variable_names])
+ console.print(f" [cyan]Variables:[/cyan] {variables_str}")
+
+ # Error message
+ console.print(f" [cyan]→[/cyan] {blueprint_error.message}")
+
+ # Source file
+ if blueprint_error.source:
+ console.print(f" [dim]└─ Source: {blueprint_error.source}[/dim]")
+
+ console.print()
+
# Display pipe validation errors
if exc.pipe_validation_error_data:
console.print("[bold cyan]Pipe Validation Errors:[/bold cyan]\n")
diff --git a/pipelex/core/bundles/exceptions.py b/pipelex/core/bundles/exceptions.py
index b3b9f57e0..ce87be598 100644
--- a/pipelex/core/bundles/exceptions.py
+++ b/pipelex/core/bundles/exceptions.py
@@ -1,5 +1,6 @@
from pydantic import BaseModel
+from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.types import StrEnum
@@ -14,6 +15,13 @@ class PipelexBundleBlueprintFixableErrorType(StrEnum):
class PipelexBundleBlueprintValidationErrorData(BaseModel):
"""Structured validation error data for bundle blueprint validation errors.
- This model captures information about validation errors that are actually fixed
- in the builder loop auto-fix system.
+ This model captures information about validation errors that occur during
+ blueprint validation (before pipe instantiation).
"""
+
+ error_type: PipeValidationErrorType | None = None
+ domain_code: str | None = None
+ source: str | None = None
+ pipe_code: str | None = None
+ message: str
+ variable_names: list[str] | None = None
diff --git a/pipelex/core/bundles/pipelex_bundle_blueprint.py b/pipelex/core/bundles/pipelex_bundle_blueprint.py
index c77281170..d77fe8cf6 100644
--- a/pipelex/core/bundles/pipelex_bundle_blueprint.py
+++ b/pipelex/core/bundles/pipelex_bundle_blueprint.py
@@ -80,11 +80,3 @@ class PipelexBundleBlueprint(BaseModel):
msg = f"Main pipe '{self.main_pipe}' could not be found in pipelex bundle at source '{self.source}' and domain '{self.domain}'"
raise ValueError(msg)
return self
-
- @property
- def nb_pipes(self) -> int:
- return len(self.pipe) if self.pipe else 0
-
- @property
- def nb_concepts(self) -> int:
- return len(self.concept) if self.concept else 0
diff --git a/pipelex/core/domains/domain.py b/pipelex/core/domains/domain.py
index 7a395bf84..b9a613a78 100644
--- a/pipelex/core/domains/domain.py
+++ b/pipelex/core/domains/domain.py
@@ -1,5 +1,7 @@
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, field_validator
+from pipelex.core.domains.exceptions import DomainCodeError
+from pipelex.core.domains.validation import validate_domain_code
from pipelex.types import StrEnum
@@ -24,3 +26,13 @@ class Domain(BaseModel):
code: str
description: str | None = None
system_prompt: str | None = None
+
+ @field_validator("code", mode="before")
+ @classmethod
+ def validate_domain_syntax(cls, domain_code: str) -> str:
+ try:
+ validate_domain_code(code=domain_code)
+ except DomainCodeError as exc:
+ msg = f"Error when trying to validate the pipelex bundle at domain '{domain_code}': {exc}"
+ raise ValueError(msg) from exc
+ return domain_code
diff --git a/pipelex/core/domains/domain_blueprint.py b/pipelex/core/domains/domain_blueprint.py
index 5cdceecaf..210da800a 100644
--- a/pipelex/core/domains/domain_blueprint.py
+++ b/pipelex/core/domains/domain_blueprint.py
@@ -1,10 +1,24 @@
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from pipelex.core.domains.exceptions import DomainCodeError
+from pipelex.core.domains.validation import validate_domain_code
class DomainBlueprint(BaseModel):
model_config = ConfigDict(extra="forbid")
- source: str | None = None
+
code: str
description: str
+ source: str | None = None
system_prompt: str | None = None
main_pipe: str | None = None
+
+ @field_validator("code", mode="before")
+ @classmethod
+ def validate_domain_syntax(cls, domain_code: str) -> str:
+ try:
+ validate_domain_code(code=domain_code)
+ except DomainCodeError as exc:
+ msg = f"Error when trying to validate the pipelex bundle at domain '{domain_code}': {exc}"
+ raise ValueError(msg) from exc
+ return domain_code
diff --git a/pipelex/core/interpreter/validation_error_categorizer.py b/pipelex/core/interpreter/validation_error_categorizer.py
index 95a8548b7..c067be464 100644
--- a/pipelex/core/interpreter/validation_error_categorizer.py
+++ b/pipelex/core/interpreter/validation_error_categorizer.py
@@ -1,3 +1,4 @@
+import re
from typing import Any, cast
from pydantic_core import ErrorDetails
@@ -7,6 +8,7 @@ from pipelex.core.bundles.exceptions import (
PipelexBundleBlueprintValidationErrorData,
)
from pipelex.core.interpreter.helpers import get_error_scope
+from pipelex.core.pipes.exceptions import PipeValidationErrorType
from pipelex.types import StrEnum
@@ -20,6 +22,62 @@ PIPELEX_BUNDLE_BLUEPRINT_DOMAIN_FIELD = "domain"
PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD = "source"
+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_blueprint_validation_error(
blueprint_dict: dict[str, Any],
error: ErrorDetails,
@@ -37,6 +95,24 @@ def categorize_blueprint_validation_error(
source = cast("str | None", blueprint_dict.get(PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD)) if blueprint_dict else None
loc = error.get(ErrorCatKey.LOC.value, ())
+ message = error.get(ErrorCatKey.MSG.value, "Unknown validation error")
+
+ # Extract pipe code from location if available (e.g., ('pipes', 'extract_details_of_task', ...))
+ pipe_code: str | None = None
+ if len(loc) >= 2 and loc[0] == "pipes":
+ pipe_code = str(loc[1])
+
+ # 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
+
+ # If we couldn't categorize the error, log a warning
error_scope = get_error_scope(loc)
log.warning(f"Pipelex bundle blueprint validation error that is not categorized: {error_scope} - {source} - {domain}")
diff --git a/pipelex/core/pipes/handle_pipe_errors.py b/pipelex/core/pipes/handle_pipe_errors.py
index 7dd9bf407..ad8898ecb 100644
--- a/pipelex/core/pipes/handle_pipe_errors.py
+++ b/pipelex/core/pipes/handle_pipe_errors.py
@@ -1,3 +1,5 @@
+from typing import Any
+
from pydantic import ValidationError
from pydantic_core import ErrorDetails
@@ -14,13 +16,42 @@ class ModelScope(StrEnum):
CONCEPT = "concept"
+def _extract_wrapped_pipe_validation_error(error: ErrorDetails) -> PipeValidationError | None:
+ """Extract a wrapped PipeValidationError from a pydantic error if present.
+
+ When a PipeValidationError is raised inside a model validator, pydantic wraps it.
+ This function attempts to extract the original PipeValidationError from the error context.
+
+ Args:
+ error: Pydantic error details that may contain a wrapped PipeValidationError
+
+ Returns:
+ The original PipeValidationError if found, None otherwise
+ """
+ # Check if the error type indicates a value_error (which wraps exceptions from validators)
+ error_type = error.get(ErrorCatKey.TYPE.value, "")
+ if error_type != "value_error":
+ return None
+
+ # Check if there's a context with the original error
+ ctx: dict[str, Any] | None = error.get("ctx")
+ if ctx:
+ # Pydantic may store the original exception in ctx["error"]
+ original_error = ctx.get("error")
+ if isinstance(original_error, PipeValidationError):
+ return original_error
+
+ return None
+
+
def categorize_pipe_validation_error(
validation_error: ValidationError,
) -> list[PipesAndConceptValidationErrorData]:
"""Categorize all errors from a ValidationError for Pipe instantiation.
This function determines the model scope (PIPE or CONCEPT) from the ValidationError
- and processes all errors accordingly.
+ and processes all errors accordingly. It also detects wrapped PipeValidationError
+ exceptions that were raised inside model validators.
Args:
validation_error: Pydantic ValidationError from Pipe model validation
@@ -56,7 +87,11 @@ def categorize_pipe_validation_error(
# Process all errors
categorized_errors: list[PipesAndConceptValidationErrorData] = []
for error in errors:
- if model_scope == ModelScope.PIPE:
+ # First, check if this is a wrapped PipeValidationError
+ wrapped_pipe_error = _extract_wrapped_pipe_validation_error(error)
+ if wrapped_pipe_error:
+ categorized_error = categorize_pipe_validation_with_libraries_error(pipe_error=wrapped_pipe_error)
+ elif model_scope == ModelScope.PIPE:
categorized_error = _handle_pipe_errors(
error=error,
pipe_code=None, # We don't have the code at this point
diff --git a/pipelex/core/pipes/inputs/input_stuff_specs.py b/pipelex/core/pipes/inputs/input_stuff_specs.py
index c5779da85..4351391f0 100644
--- a/pipelex/core/pipes/inputs/input_stuff_specs.py
+++ b/pipelex/core/pipes/inputs/input_stuff_specs.py
@@ -11,6 +11,7 @@ from pipelex.core.pipes.inputs.exceptions import InputStuffSpecNotFoundError
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.tools.misc.string_utils import get_root_from_dotted_path
class NamedStuffSpec(StuffSpec):
@@ -50,7 +51,7 @@ class InputStuffSpecs(RootModel[PipeInputsRoot]):
transformed_dict: PipeInputsRoot = {}
for input_name, stuff_spec in stuff_specs.items():
# in case of sub-attribute, the variable name is the object name, before the 1st dot
- transformed_key: str = input_name.split(".", 1)[0]
+ transformed_key: str = get_root_from_dotted_path(input_name)
if transformed_key != input_name:
log.verbose(f"Sub-attribute {input_name} detected, using {transformed_key} as variable name")
@@ -102,7 +103,7 @@ class InputStuffSpecs(RootModel[PipeInputsRoot]):
def required_names(self) -> list[str]:
the_required_names: list[str] = []
for requirement_expression in self.root:
- required_variable_name = requirement_expression.split(".", 1)[0]
+ required_variable_name = get_root_from_dotted_path(requirement_expression)
the_required_names.append(required_variable_name)
return the_required_names
@@ -110,7 +111,7 @@ class InputStuffSpecs(RootModel[PipeInputsRoot]):
def named_stuff_specs(self) -> list[NamedStuffSpec]:
the_named_stuff_spec: list[NamedStuffSpec] = []
for requirement_expression, stuff_spec in self.root.items():
- required_variable_name = requirement_expression.split(".", 1)[0]
+ required_variable_name = get_root_from_dotted_path(requirement_expression)
the_named_stuff_spec.append(
NamedStuffSpec(
variable_name=required_variable_name,
diff --git a/pipelex/core/pipes/pipe_abstract.py b/pipelex/core/pipes/pipe_abstract.py
index 2f6d57dfa..e266812e6 100644
--- a/pipelex/core/pipes/pipe_abstract.py
+++ b/pipelex/core/pipes/pipe_abstract.py
@@ -15,6 +15,7 @@ from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_blueprint import PipeCategory, PipeType
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec
+from pipelex.core.pipes.validation import is_variable_satisfied_by_inputs
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.pipeline.job_metadata import JobMetadata, OtelContext
@@ -42,7 +43,7 @@ class PipeAbstract(ABC, BaseModel):
type: Any # Any so that subclasses can put a Literal
code: str
domain_code: str
- description: str | None = None
+ description: str
inputs: InputStuffSpecs = Field(default_factory=InputStuffSpecs)
output: StuffSpec
@@ -131,16 +132,17 @@ class PipeAbstract(ABC, BaseModel):
@final
def generic_validate_inputs_with_library(self):
- # First validate required variables are in the inputs
- for required_variable_name in self.required_variables():
- if required_variable_name not in self.inputs.variables:
- msg = f"Required variable '{required_variable_name}' is not in the inputs of pipe '{self.code}'. Current inputs: {self.inputs}"
+ # First validate required variables are in the inputs (using prefix-based matching)
+ input_names = set(self.inputs.variables)
+ for required_variable_path in self.required_variables():
+ if not is_variable_satisfied_by_inputs(required_variable_path, input_names):
+ msg = f"Required variable '{required_variable_path}' is not in the inputs of pipe '{self.code}'. Current inputs: {self.inputs}"
raise PipeValidationError(
message=msg,
error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,
domain_code=self.domain_code,
pipe_code=self.code,
- variable_names=[required_variable_name],
+ variable_names=[required_variable_path],
)
# Then validate that all inputs are actually needed and match requirements exactly
diff --git a/pipelex/core/pipes/pipe_blueprint.py b/pipelex/core/pipes/pipe_blueprint.py
index 4e51fe60c..3cbcf1f9b 100644
--- a/pipelex/core/pipes/pipe_blueprint.py
+++ b/pipelex/core/pipes/pipe_blueprint.py
@@ -82,7 +82,7 @@ class PipeBlueprint(ABC, BaseModel):
source: str | None = None
pipe_category: Any = Field(exclude=True) # Technical field for Union discrimination, not user-facing
type: Any # TODO: Find a better way to handle this.
- description: str | None = None
+ description: str
inputs: dict[str, str] | None = None
output: str
diff --git a/pipelex/core/pipes/pipe_factory.py b/pipelex/core/pipes/pipe_factory.py
index 022881d54..f95c94f1f 100644
--- a/pipelex/core/pipes/pipe_factory.py
+++ b/pipelex/core/pipes/pipe_factory.py
@@ -29,7 +29,7 @@ class PipeFactoryProtocol(Protocol[PipeBlueprintType, PipeAbstractType]):
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeBlueprintType,
diff --git a/pipelex/core/pipes/validation.py b/pipelex/core/pipes/validation.py
index d52c26014..fcd3636fe 100644
--- a/pipelex/core/pipes/validation.py
+++ b/pipelex/core/pipes/validation.py
@@ -1,6 +1,58 @@
from pipelex.tools.misc.string_utils import is_snake_case
+def is_variable_satisfied_by_inputs(variable_path: str, input_names: set[str]) -> bool:
+ """Check if a variable path is satisfied by the declared inputs.
+
+ A variable path is satisfied if:
+ - It exactly matches an input name, OR
+ - Its root (or any prefix) matches an input name (attribute access on an input)
+
+ Args:
+ variable_path: The full dotted variable path (e.g., 'page.text_and_images.text')
+ input_names: Set of declared input names
+
+ Returns:
+ True if the variable path is satisfied by the inputs.
+ """
+ # Check for exact match
+ if variable_path in input_names:
+ return True
+
+ # Check if any prefix of the path matches an input name
+ parts = variable_path.split(".")
+ for idx in range(1, len(parts)):
+ prefix = ".".join(parts[:idx])
+ if prefix in input_names:
+ return True
+
+ return False
+
+
+def is_input_used_by_variables(input_name: str, variable_paths: set[str]) -> bool:
+ """Check if an input is used by any of the variable paths.
+
+ An input is considered used if:
+ - It exactly matches a variable path, OR
+ - It is a prefix of any variable path (the input is accessed via attributes)
+
+ Args:
+ input_name: The declared input name
+ variable_paths: Set of full dotted variable paths used in the template
+
+ Returns:
+ True if the input is used by any variable path.
+ """
+ for var_path in variable_paths:
+ # Exact match
+ if var_path == input_name:
+ return True
+ # Input is a prefix of the variable path
+ if var_path.startswith(input_name + "."):
+ return True
+ return False
+
+
def is_valid_input_name(input_name: str) -> bool:
"""Check if an input name is valid.
diff --git a/pipelex/pipe_controllers/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.py
index 0dd28f444..3501e17d3 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch.py
@@ -14,6 +14,7 @@ from pipelex.pipe_controllers.pipe_controller import PipeController
from pipelex.pipe_run.exceptions import PipeRunError
from pipelex.pipe_run.pipe_run_params import BatchParams, PipeRunMode, PipeRunParams
from pipelex.pipeline.job_metadata import JobMetadata
+from pipelex.tools.misc.string_utils import get_root_from_dotted_path
if TYPE_CHECKING:
from collections.abc import Coroutine
@@ -138,7 +139,9 @@ class PipeBatch(PipeController):
branch_memory.set_new_main_stuff(stuff=item_input_stuff, name=input_item_stuff_name)
required_variables = sub_pipe.required_variables()
- required_stuffs = branch_memory.get_existing_stuffs(names=required_variables)
+ # Extract root names from full paths for looking up stuffs in working memory
+ required_stuff_names = {get_root_from_dotted_path(req_var) for req_var in required_variables}
+ required_stuffs = branch_memory.get_existing_stuffs(names=required_stuff_names)
required_stuffs = [required_stuff for required_stuff in required_stuffs if required_stuff.stuff_code != input_stuff.stuff_code]
required_stuff_lists.append(required_stuffs)
# We create a deep copy of the run params to avoid modifying the original run params,
@@ -152,23 +155,13 @@ class PipeBatch(PipeController):
"output_multiplicity": False,
},
)
-
- task: Coroutine[Any, Any, PipeOutput]
- if pipe_run_params.run_mode == PipeRunMode.DRY:
- branch_pipe_run_params.run_mode = PipeRunMode.DRY
- task = sub_pipe.run_pipe(
- job_metadata=job_metadata,
- working_memory=branch_memory,
- output_name=f"Batch result {branch_index + 1} of {output_name}",
- pipe_run_params=branch_pipe_run_params,
- )
- else:
- task = sub_pipe.run_pipe(
- job_metadata=job_metadata,
- working_memory=branch_memory,
- output_name=f"Batch result {branch_index + 1} of {output_name}",
- pipe_run_params=branch_pipe_run_params,
- )
+ branch_pipe_run_params.run_mode = pipe_run_params.run_mode
+ task = sub_pipe.run_pipe(
+ job_metadata=job_metadata,
+ working_memory=branch_memory,
+ output_name=f"Batch result {branch_index + 1} of {output_name}",
+ pipe_run_params=branch_pipe_run_params,
+ )
tasks.append(task)
pipe_outputs = await asyncio.gather(*tasks)
diff --git a/pipelex/pipe_controllers/batch/pipe_batch_factory.py b/pipelex/pipe_controllers/batch/pipe_batch_factory.py
index a727b9a51..ac53ab161 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch_factory.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch_factory.py
@@ -19,7 +19,7 @@ class PipeBatchFactory(PipeFactoryProtocol[PipeBatchBlueprint, PipeBatch]):
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeBatchBlueprint,
diff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.py
index cf7c737a3..160cc2ca4 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition.py
@@ -22,6 +22,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.pipeline.job_metadata import JobMetadata
from pipelex.tools.jinja2.jinja2_errors import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+from pipelex.tools.misc.string_utils import get_root_from_dotted_path
ConditionOutcomeMap = dict[str, str | SpecialOutcome]
@@ -58,11 +59,11 @@ class PipeCondition(PipeController):
def required_variables(self) -> set[str]:
required_variables: set[str] = set()
# Variables from the expression/expression_template
- expression_required_variables = detect_jinja2_required_variables(
+ full_paths = detect_jinja2_required_variables(
template_category=TemplateCategory.EXPRESSION,
template_source=self.expression,
)
- required_variables.update(expression_required_variables)
+ required_variables.update(path.split(".")[0] for path in full_paths)
# Variables from the outcomes map and default_outcome
for pipe_code in self.pipe_dependencies():
@@ -84,10 +85,11 @@ class PipeCondition(PipeController):
needed_inputs = InputStuffSpecsFactory.make_empty()
# Add the variables from the expression/expression_template
- required_variables = detect_jinja2_required_variables(
+ full_paths = detect_jinja2_required_variables(
template_category=TemplateCategory.EXPRESSION,
template_source=self.expression,
)
+ required_variables = {get_root_from_dotted_path(path) for path in full_paths}
for var_name in required_variables:
if not var_name.startswith("_"): # exclude internal variables starting with `_`
@@ -107,7 +109,8 @@ class PipeCondition(PipeController):
pipe_needed_inputs = pipe.needed_inputs(visited_pipes_with_current)
for input_name, stuff_spec in pipe_needed_inputs.items:
- needed_inputs.add_stuff_spec(variable_name=input_name, concept=stuff_spec.concept)
+ needed_inputs.add_stuff_spec(variable_name=input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity)
+
return needed_inputs
@override
@@ -224,8 +227,10 @@ class PipeCondition(PipeController):
)
# Get required variables and validate they exist in working memory
+ # Extract root names from full paths for looking up stuffs in working memory
required_variables = chosen_pipe.required_variables()
- required_stuff_names = {required_variable for required_variable in required_variables if not required_variable.startswith("_")}
+ # TODO: Merge `needed_inputs` and `required_variables` methods for cleaner code.
+ required_stuff_names = {get_root_from_dotted_path(req_var) for req_var in required_variables if not req_var.startswith("_")}
try:
required_stuffs = working_memory.get_stuffs(names=required_stuff_names)
except WorkingMemoryStuffNotFoundError as exc:
@@ -271,10 +276,11 @@ class PipeCondition(PipeController):
) -> PipeOutput:
# Validate that the expression template is valid
try:
- required_variables = detect_jinja2_required_variables(
+ full_paths = detect_jinja2_required_variables(
template_category=TemplateCategory.EXPRESSION,
template_source=self.expression,
)
+ required_variables = {get_root_from_dotted_path(path) for path in full_paths}
log.verbose(f"Expression template is valid, requires variables: {required_variables}")
except Jinja2DetectVariablesError as exc:
log.error(f"Dry run failed: could not detect required variables from expression template: {exc}")
diff --git a/pipelex/pipe_controllers/condition/pipe_condition_factory.py b/pipelex/pipe_controllers/condition/pipe_condition_factory.py
index 0551e50f0..4a0b2408c 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition_factory.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition_factory.py
@@ -19,7 +19,7 @@ class PipeConditionFactory(PipeFactoryProtocol[PipeConditionBlueprint, PipeCondi
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeConditionBlueprint,
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py b/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
index 993c3e533..a1a19c8a6 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
@@ -25,7 +25,7 @@ class PipeParallelFactory(PipeFactoryProtocol[PipeParallelBlueprint, PipeParalle
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeParallelBlueprint,
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence.py b/pipelex/pipe_controllers/sequence/pipe_sequence.py
index b689158de..ab84e51ec 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence.py
@@ -85,7 +85,8 @@ class PipeSequence(PipeController):
msg = (
f"PipeSequence output multiplicity mismatch: the sequence '{self.code}' declares "
f"output multiplicity={self.output.multiplicity}, but the last step '{last_step_pipe.code}' "
- f"has output multiplicity={effective_last_step_output_multiplicity}. They are not compatible."
+ f"has output multiplicity={effective_last_step_output_multiplicity}. They are not compatible. "
+ "Update one of them to match the other."
)
raise PipeValidationError(
message=msg,
@@ -149,6 +150,7 @@ class PipeSequence(PipeController):
# Add this step's output to generated outputs
if sequential_sub_pipe.output_name:
generated_outputs.add(sequential_sub_pipe.output_name)
+
return needed_inputs
@override
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py b/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
index 0745703cb..fb12c5d32 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
@@ -22,7 +22,7 @@ class PipeSequenceFactory(PipeFactoryProtocol[PipeSequenceBlueprint, PipeSequenc
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeSequenceBlueprint,
diff --git a/pipelex/pipe_controllers/sub_pipe.py b/pipelex/pipe_controllers/sub_pipe.py
index ff2736096..542ba7f6c 100644
--- a/pipelex/pipe_controllers/sub_pipe.py
+++ b/pipelex/pipe_controllers/sub_pipe.py
@@ -101,7 +101,9 @@ class SubPipe(BaseModel):
else:
# Case 3: Normal processing
required_variables = sub_pipe.required_variables()
- required_stuff_names = {req_var for req_var in required_variables if not req_var.startswith("_")}
+ # Extract root names from full paths for looking up stuffs in working memory
+ # TODO: Merge `needed_inputs` and `required_variables` methods for cleaner code.
+ required_stuff_names = {req_var.split(".")[0] for req_var in required_variables if not req_var.startswith("_")}
try:
required_stuffs = working_memory.get_stuffs(names=required_stuff_names)
except WorkingMemoryStuffNotFoundError as exc:
diff --git a/pipelex/pipe_operators/compose/pipe_compose.py b/pipelex/pipe_operators/compose/pipe_compose.py
index 44b70fd0e..6cc45b46e 100644
--- a/pipelex/pipe_operators/compose/pipe_compose.py
+++ b/pipelex/pipe_operators/compose/pipe_compose.py
@@ -46,7 +46,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
@override
def required_variables(self) -> set[str]:
try:
- required_variables = detect_jinja2_required_variables(
+ full_paths = detect_jinja2_required_variables(
template_category=self.category,
template_source=self.template,
)
@@ -54,9 +54,9 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
msg = f"Error detecting required variables for PipeCompose: {exc}"
raise ValueError(msg) from exc
return {
- variable_name
- for variable_name in required_variables
- if not variable_name.startswith("_") and variable_name not in {"preliminary_text", "place_holder"}
+ path.split(".")[0]
+ for path in full_paths
+ if not path.split(".")[0].startswith("_") and path.split(".")[0] not in {"preliminary_text", "place_holder"}
}
@override
diff --git a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
index a08e7e9c1..4fd686f42 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
@@ -56,13 +56,14 @@ class PipeComposeBlueprint(PipeBlueprint):
except Jinja2TemplateSyntaxError as exc:
msg = f"Could not parse template for PipeCompose: {exc}"
raise ValueError(msg) from exc
+ full_paths = detect_jinja2_required_variables(
+ template_category=self.template_category,
+ template_source=preprocessed_template,
+ )
required_variables = {
- variable_name
- for variable_name in detect_jinja2_required_variables(
- template_category=self.template_category,
- template_source=preprocessed_template,
- )
- if not variable_name.startswith("_") and variable_name not in {"preliminary_text", "place_holder"}
+ path.split(".")[0]
+ for path in full_paths
+ if not path.split(".")[0].startswith("_") and path.split(".")[0] not in {"preliminary_text", "place_holder"}
}
for required_variable_name in required_variables:
if required_variable_name not in self.input_names:
diff --git a/pipelex/pipe_operators/compose/pipe_compose_factory.py b/pipelex/pipe_operators/compose/pipe_compose_factory.py
index 23a424cfb..2c28fcc2e 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_factory.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_factory.py
@@ -22,7 +22,7 @@ class PipeComposeFactory(PipeFactoryProtocol[PipeComposeBlueprint, PipeCompose])
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeComposeBlueprint,
diff --git a/pipelex/pipe_operators/extract/pipe_extract_factory.py b/pipelex/pipe_operators/extract/pipe_extract_factory.py
index db28a3c69..b427007e0 100644
--- a/pipelex/pipe_operators/extract/pipe_extract_factory.py
+++ b/pipelex/pipe_operators/extract/pipe_extract_factory.py
@@ -22,7 +22,7 @@ class PipeExtractFactory(PipeFactoryProtocol[PipeExtractBlueprint, PipeExtract])
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeExtractBlueprint,
diff --git a/pipelex/pipe_operators/func/pipe_func_factory.py b/pipelex/pipe_operators/func/pipe_func_factory.py
index 1f2f37deb..6b024db43 100644
--- a/pipelex/pipe_operators/func/pipe_func_factory.py
+++ b/pipelex/pipe_operators/func/pipe_func_factory.py
@@ -18,7 +18,7 @@ class PipeFuncFactory(PipeFactoryProtocol[PipeFuncBlueprint, PipeFunc]):
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeFuncBlueprint,
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
index 8a1351e7d..6fb498fec 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
@@ -41,14 +41,11 @@ class PipeImgGenBlueprint(PipeBlueprint):
msg = f"Could not parse template for PipeImgGen: {exc}"
raise ValueError(msg) from exc
# Filter out internal variables that start with underscore
- required_variables = {
- variable_name
- for variable_name in detect_jinja2_required_variables(
- template_category=template_category,
- template_source=preprocessed_template,
- )
- if not variable_name.startswith("_")
- }
+ full_paths = detect_jinja2_required_variables(
+ template_category=template_category,
+ template_source=preprocessed_template,
+ )
+ required_variables = {path.split(".")[0] for path in full_paths if not path.split(".")[0].startswith("_")}
# Check that all required variables are in inputs
input_names: set[str] = set(self.inputs.keys()) if self.inputs else set()
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
index ce78efa16..c1a774162 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
@@ -21,7 +21,7 @@ class PipeImgGenFactory(PipeFactoryProtocol[PipeImgGenBlueprint, PipeImgGen]):
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeImgGenBlueprint,
diff --git a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
index e118eb9ce..fb0823887 100644
--- a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
+++ b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
@@ -12,6 +12,7 @@ from pipelex.hub import get_content_generator
from pipelex.pipe_operators.llm.exceptions import LLMPromptBlueprintValueError
from pipelex.tools.misc.context_provider_abstract import ContextProviderAbstract, ContextProviderError
from pipelex.tools.misc.dict_utils import substitute_nested_in_context
+from pipelex.tools.misc.string_utils import get_root_from_dotted_path
if TYPE_CHECKING:
from pipelex.cogt.image.prompt_image import PromptImage
@@ -26,7 +27,7 @@ class LLMPromptBlueprint(BaseModel):
def required_variables(self) -> set[str]:
required_variables: set[str] = set()
if self.user_images:
- user_images_top_object_name = [user_image.split(".", 1)[0] for user_image in self.user_images]
+ user_images_top_object_name = [get_root_from_dotted_path(user_image) for user_image in self.user_images]
required_variables.update(user_images_top_object_name)
if self.prompt_blueprint:
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index c6b964ed5..cd910aae2 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -20,7 +20,9 @@ from pipelex.core.domains.domain import SpecialDomain
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.exceptions import PipeValidationError, PipeValidationErrorType
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
+from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.core.pipes.validation import is_input_used_by_variables, is_variable_satisfied_by_inputs
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_content import StuffContent
@@ -75,6 +77,34 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
for llm_choice in self.llm_choices.list_choice_strings():
check_llm_choice_with_deck(llm_choice=llm_choice)
+ needed_inputs = self.needed_inputs()
+ required_variable_paths = self.required_variables()
+ input_names = {input_name for input_name, _ in needed_inputs.items}
+
+ # Check for unused inputs: declared in inputs but not used by any variable path
+ for input_name in input_names:
+ if not is_input_used_by_variables(input_name, required_variable_paths):
+ msg = f"PipeLLM '{self.code}' has input '{input_name}' declared but it is not used in the prompt or system_prompt."
+ raise PipeValidationError(
+ message=msg,
+ error_type=PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,
+ pipe_code=self.code,
+ variable_names=[input_name],
+ explanation=f"Input '{input_name}' is declared in inputs but not referenced in prompt/system_prompt.",
+ )
+
+ # Check for missing inputs: variable paths in prompt/system_prompt not satisfied by any input
+ for variable_path in required_variable_paths:
+ if not is_variable_satisfied_by_inputs(variable_path, input_names):
+ msg = f"PipeLLM '{self.code}' uses variable '{variable_path}' in prompt/system_prompt but it is not declared in inputs."
+ raise PipeValidationError(
+ message=msg,
+ error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,
+ pipe_code=self.code,
+ variable_names=[variable_path],
+ explanation=f"Variable '{variable_path}' is used in prompt/system_prompt but not declared in inputs.",
+ )
+
@override
def validate_inputs_with_library(self):
pass
@@ -110,7 +140,12 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
@override
def needed_inputs(self, visited_pipes: set[str] | None = None) -> InputStuffSpecs:
- return self.inputs
+ needed_inputs = InputStuffSpecsFactory.make_empty()
+
+ for input_name, stuff_spec in self.inputs.items:
+ needed_inputs.add_stuff_spec(variable_name=input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity)
+
+ return needed_inputs
@override
def required_variables(self) -> set[str]:
diff --git a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
index 867c446cd..7214caac4 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
@@ -6,6 +6,7 @@ from pipelex.cogt.llm.llm_setting import LLMModelChoice
from pipelex.cogt.templating.template_category import TemplateCategory
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
+from pipelex.core.pipes.validation import is_input_used_by_variables, is_variable_satisfied_by_inputs
from pipelex.tools.jinja2.jinja2_errors import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
from pipelex.types import StrEnum
@@ -30,13 +31,13 @@ class PipeLLMBlueprint(PipeBlueprint):
@override
def validate_inputs(self):
- # Get all required variables from prompt and system_prompt
- required_variables: set[str] = set()
+ # Get all required variable paths from prompt and system_prompt (full dotted paths)
+ required_variable_paths: set[str] = set()
if self.prompt:
preprocessed_template = preprocess_template(self.prompt)
try:
- required_variables.update(
+ required_variable_paths.update(
detect_jinja2_required_variables(
template_category=TemplateCategory.LLM_PROMPT,
template_source=preprocessed_template,
@@ -49,7 +50,7 @@ class PipeLLMBlueprint(PipeBlueprint):
if self.system_prompt:
preprocessed_system_template = preprocess_template(self.system_prompt)
try:
- required_variables.update(
+ required_variable_paths.update(
detect_jinja2_required_variables(
template_category=TemplateCategory.LLM_PROMPT,
template_source=preprocessed_system_template,
@@ -58,20 +59,29 @@ class PipeLLMBlueprint(PipeBlueprint):
except Jinja2DetectVariablesError as exc:
msg = f"Could not detect required variables in system prompt for PipeLLM: {exc}"
raise ValueError(msg) from exc
+
# Filter out internal variables that start with underscore and special variables
# TODO: replace magic strings by StrEnum and also, make this check clearer and more readable
- required_variables = {var for var in required_variables if not var.startswith("_") and var not in {"preliminary_text", "place_holder"}}
+ filtered_variable_paths = {
+ var for var in required_variable_paths if not var.startswith("_") and var.split(".")[0] not in {"preliminary_text", "place_holder"}
+ }
- # Check that all required variables are in inputs
input_names: set[str] = set(self.inputs.keys()) if self.inputs else set()
- missing_variables: set[str] = required_variables - input_names
-
- 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."
- )
+
+ # 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)}
+
+ # Find inputs declared but not used by any variable path
+ unused_inputs = {input_name for input_name in input_names if not is_input_used_by_variables(input_name, 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/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 prompt/system_prompt."
raise ValueError(msg)
@override
diff --git a/pipelex/pipe_operators/llm/pipe_llm_factory.py b/pipelex/pipe_operators/llm/pipe_llm_factory.py
index f9b32b53d..3738ccd34 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_factory.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_factory.py
@@ -30,7 +30,7 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):
pipe_type: str,
pipe_code: str,
domain_code: str,
- description: str | None,
+ description: str,
inputs: InputStuffSpecs,
output: StuffSpec,
blueprint: PipeLLMBlueprint,
diff --git a/pipelex/tools/jinja2/jinja2_required_variables.py b/pipelex/tools/jinja2/jinja2_required_variables.py
index faca570d9..7316e56ef 100644
--- a/pipelex/tools/jinja2/jinja2_required_variables.py
+++ b/pipelex/tools/jinja2/jinja2_required_variables.py
@@ -1,4 +1,4 @@
-from jinja2 import meta
+from jinja2 import nodes
from jinja2.exceptions import (
TemplateSyntaxError,
UndefinedError,
@@ -9,22 +9,112 @@ from pipelex.tools.jinja2.jinja2_environment import make_jinja2_env_without_load
from pipelex.tools.jinja2.jinja2_errors import Jinja2DetectVariablesError, Jinja2StuffError
+def _build_full_path(node: nodes.Node) -> str | None:
+ """Recursively build the full dotted path from a Getattr or Name node.
+
+ Args:
+ node: A Jinja2 AST node (Name or Getattr)
+
+ Returns:
+ The full dotted path as a string, or None if the node structure is not supported.
+ """
+ if isinstance(node, nodes.Name):
+ return node.name
+ if isinstance(node, nodes.Getattr):
+ parent_path = _build_full_path(node.node)
+ if parent_path is not None:
+ return f"{parent_path}.{node.attr}"
+ 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.
+
+ This handles {% set %} and {% macro %} declarations that should be visible
+ to all subsequent nodes in the same scope.
+ """
+ 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 _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`.
+
+ Args:
+ node: The current AST node
+ paths: Set to collect discovered paths
+ declared_names: Set of locally declared names (loop variables, macro params, etc.)
+ """
+ # 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 scope
+ if isinstance(node, nodes.Template):
+ local_declared.update(_collect_declarations_from_body(node.body))
+
+ if isinstance(node, nodes.For):
+ # Loop variable is locally declared
+ 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)
+ # The special 'loop' variable is available inside for loops
+ local_declared.add("loop")
+
+ if isinstance(node, nodes.Macro):
+ # Macro parameters are locally declared (within the macro body)
+ local_declared.update(arg.name for arg in node.args)
+
+ # Merge local declarations
+ new_declared = declared_names | local_declared
+
+ # 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 = full_path.split(".")[0]
+ # 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
+ return
+
+ # Recurse into child nodes (only for non-Name/Getattr nodes)
+ for child in node.iter_child_nodes():
+ _collect_full_variable_paths(child, paths, new_declared)
+
+
def detect_jinja2_required_variables(
template_category: TemplateCategory,
template_source: str,
) -> set[str]:
- """Returns a list of variables required by the Jinja2 template.
+ """Returns the set of full variable paths required by the Jinja2 template.
+
+ For example, `{{ user.profile.name }}` returns a set containing `user.profile.name`.
Args:
- template_category: Category of the template (HTML, MARKDOWN, etc.), used to set the appropriate jinja2 environment settings
+ template_category: Category of the template (HTML, MARKDOWN, etc.)
template_source: Jinja2 template string
Returns:
- List of variable names required by the template
+ Set of full dotted variable paths required by the template
Raises:
Jinja2DetectVariablesError: If there is an error parsing the template
-
"""
jinja2_env = make_jinja2_env_without_loader(
template_category=template_category,
@@ -32,7 +122,6 @@ def detect_jinja2_required_variables(
try:
parsed_ast = jinja2_env.parse(template_source)
- undeclared_variables = meta.find_undeclared_variables(parsed_ast)
except Jinja2StuffError as stuff_error:
msg = f"Jinja2 detect variables — stuff error: '{stuff_error}', template_category: {template_category}, template_source:\n{template_source}"
raise Jinja2DetectVariablesError(msg) from stuff_error
@@ -45,4 +134,6 @@ def detect_jinja2_required_variables(
)
raise Jinja2DetectVariablesError(msg) from undef_error
- return undeclared_variables
+ paths: set[str] = set()
+ _collect_full_variable_paths(parsed_ast, paths, set())
+ return paths
diff --git a/pipelex/tools/misc/string_utils.py b/pipelex/tools/misc/string_utils.py
index 47870b40a..e08e9c498 100644
--- a/pipelex/tools/misc/string_utils.py
+++ b/pipelex/tools/misc/string_utils.py
@@ -246,6 +246,32 @@ def normalize_to_ascii(text: str) -> str:
return "".join(c for c in normalized if ord(c) < 128 and (c.isalnum() or c == "_"))
+def get_root_from_dotted_path(dotted_path: str) -> str:
+ """Extract the root segment from a dot-separated path.
+
+ This function returns the first segment of a dotted path (everything before
+ the first dot). If there is no dot, returns the entire string unchanged.
+
+ Args:
+ dotted_path: A string that may contain dots as separators (e.g., "object.attribute.sub").
+
+ Returns:
+ The first segment before the first dot, or the whole string if no dot exists.
+
+ Examples:
+ >>> get_root_from_dotted_path("foo.bar.baz")
+ 'foo'
+ >>> get_root_from_dotted_path("foo.bar")
+ 'foo'
+ >>> get_root_from_dotted_path("foo")
+ 'foo'
+ >>> get_root_from_dotted_path("")
+ ''
+
+ """
+ return dotted_path.split(".", 1)[0]
+
+
def matches_wildcard_pattern(text: str, pattern: str) -> bool:
"""Check if a text matches a wildcard pattern.
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/pipe_condition_continue_output_type.plx b/tests/integration/pipelex/pipes/controller/pipe_condition/pipe_condition_continue_output_type.plx
new file mode 100644
index 000000000..e72d95d07
--- /dev/null
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/pipe_condition_continue_output_type.plx
@@ -0,0 +1,44 @@
+domain = "test_pipe_condition_continue_output_type"
+description = "Test PipeCondition with continue outcome and batching over verified links"
+
+[concept]
+VerifiedLink = "A verified link with a verdict (approved or rejected)"
+Constraint = "A mathematical price constraint"
+
+[pipe]
+[pipe.process_verified_links]
+type = "PipeBatch"
+description = "Batches over verified links and routes each based on verdict."
+inputs = { verified_links = "VerifiedLink[]" }
+output = "Constraint[]"
+input_list_name = "verified_links"
+input_item_name = "verified_link"
+branch_pipe_code = "build_or_skip"
+
+[pipe.build_or_skip]
+type = "PipeCondition"
+description = "Routes approved links to builder, rejected links to skip (continue)."
+inputs = { verified_link = "VerifiedLink" }
+output = "Constraint"
+expression_template = "{{ verified_link.verdict }}"
+default_outcome = "continue"
+
+[pipe.build_or_skip.outcomes]
+approved = "build_single_constraint"
+rejected = "continue"
+
+[pipe.build_single_constraint]
+type = "PipeLLM"
+description = "Converts an approved verified link into a mathematical price constraint."
+inputs = { verified_link = "VerifiedLink" }
+output = "Constraint"
+prompt = """
+@verified_link
+
+Convert to a price constraint.
+The math: If A → B, then Price(A) ≤ Price(B).
+
+Output a constraint with:
+- expression: "Price({{ verified_link.source }}_Yes) <= Price({{ verified_link.target }}_Yes)"
+- description: "{{ verified_link.source }} implies {{ verified_link.target }}"
+"""
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/pipe_condition_continue_output_type.py b/tests/integration/pipelex/pipes/controller/pipe_condition/pipe_condition_continue_output_type.py
new file mode 100644
index 000000000..027f9c26d
--- /dev/null
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/pipe_condition_continue_output_type.py
@@ -0,0 +1,20 @@
+from typing import Literal
+
+from pydantic import Field
+
+from pipelex.core.stuffs.structured_content import StructuredContent
+
+
+class VerifiedLink(StructuredContent):
+ """A verified link with a verdict indicating if it should be processed or skipped."""
+
+ source: str = Field(..., description="The source of the link")
+ target: str = Field(..., description="The target of the link")
+ verdict: Literal["approved", "rejected"] = Field(..., description="The verdict of the link verification")
+
+
+class Constraint(StructuredContent):
+ """A mathematical price constraint derived from a verified link."""
+
+ expression: str = Field(..., description="The constraint expression, e.g. 'Price(A) <= Price(B)'")
+ description: str = Field(..., description="Human-readable description of the constraint")
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_output_type.py b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_output_type.py
new file mode 100644
index 000000000..7093cfbf8
--- /dev/null
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_continue_output_type.py
@@ -0,0 +1,105 @@
+"""Integration test for PipeCondition with continue outcome in a batch context.
+
+Tests that when batching over VerifiedLinks, the PipeCondition correctly:
+- Creates Constraints for approved links
+- Skips (continues) for rejected links
+"""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+from pipelex import pretty_print
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.core.stuffs.list_content import ListContent
+from pipelex.core.stuffs.stuff_factory import StuffFactory
+from pipelex.hub import get_pipe_router, get_required_pipe
+from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
+from pipelex.pipe_run.pipe_run_params import PipeRunMode
+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
+from pipelex.pipeline.job_metadata import JobMetadata
+from tests.integration.pipelex.pipes.controller.pipe_condition.pipe_condition_continue_output_type import (
+ Constraint,
+ VerifiedLink,
+)
+
+
[email protected](reason="This test identifies a bug. it should be fixed")
[email protected](loop_scope="class")
+class TestPipeConditionContinueOutputType:
+ """Test PipeCondition with continue outcome when batching over verified links."""
+
+ async def test_batch_with_mixed_verdicts(
+ self,
+ load_test_library: Callable[[list[Path]], None],
+ pipe_run_mode: PipeRunMode,
+ ):
+ """Test batching over VerifiedLinks with mixed verdicts.
+
+ Given 2 VerifiedLinks:
+ - One approved (should create a Constraint)
+ - One rejected (should be skipped via 'continue')
+
+ The output should be a list with only 1 Constraint (from the approved link).
+ """
+ load_test_library([Path("tests/integration/pipelex/pipes/controller/pipe_condition")])
+
+ # Create two VerifiedLinks - one approved, one rejected
+ approved_link = VerifiedLink(
+ source="EventA",
+ target="EventB",
+ verdict="approved",
+ )
+ rejected_link = VerifiedLink(
+ source="EventC",
+ target="EventD",
+ verdict="rejected",
+ )
+
+ # Create a list of verified links
+ verified_links_content = ListContent[VerifiedLink](items=[approved_link, rejected_link])
+
+ verified_links_stuff = StuffFactory.make_stuff(
+ concept=ConceptFactory.make(
+ concept_code="VerifiedLink",
+ domain_code="test_pipe_condition_continue_output_type",
+ description="test_pipe_condition_continue_output_type.VerifiedLink",
+ structure_class_name="VerifiedLink",
+ ),
+ content=verified_links_content,
+ name="verified_links",
+ )
+
+ working_memory = WorkingMemoryFactory.make_from_single_stuff(verified_links_stuff)
+
+ # Run the batch pipe
+ pipe_output = await get_pipe_router().run(
+ pipe_job=PipeJobFactory.make_pipe_job(
+ pipe=get_required_pipe(pipe_code="process_verified_links"),
+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=pipe_run_mode),
+ working_memory=working_memory,
+ job_metadata=JobMetadata(),
+ ),
+ )
+
+ pretty_print(pipe_output, title="PipeBatch output with mixed verdicts")
+
+ # Verify the pipe executed
+ assert pipe_output is not None
+ assert pipe_output.working_memory is not None
+ assert pipe_output.main_stuff is not None
+
+ # Get the output as a list of Constraints
+ constraint_list = pipe_output.main_stuff_as_list(item_type=Constraint)
+
+ pretty_print(constraint_list, title="Constraint list")
+
+ # Should have only 1 Constraint (from the approved link)
+ # The rejected link should have been skipped via 'continue'
+ if pipe_run_mode.is_dry:
+ assert len(constraint_list.items) == 1, f"Expected 1 constraint, got {len(constraint_list.items)}"
diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py
index 9175a2959..a99a1fa97 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm.py
@@ -163,14 +163,15 @@ class TestPipeLLMBasic:
if not stuff_name:
pytest.fail(f"Cannot use nameless stuff in this test: {stuff}")
working_memory = WorkingMemoryFactory.make_from_single_stuff(stuff=stuff)
+ # Build prompt dynamically to include the input variable reference
+ prompt_with_input = f"Here is the input: ${stuff_name}\n{PipeTestCases.MULTI_IMG_DESC_PROMPT}"
pipe_llm_blueprint = PipeLLMBlueprint(
description="LLM test for image processing with attributes",
- inputs={stuff_name: stuff.concept.concept_ref},
+ inputs={stuff_name: "native.Image"},
output=NativeConceptCode.TEXT,
system_prompt=PipeTestCases.SYSTEM_PROMPT,
- prompt=PipeTestCases.MULTI_IMG_DESC_PROMPT,
+ prompt=prompt_with_input,
)
-
pipe_job = PipeJobFactory.make_pipe_job(
working_memory=working_memory,
pipe=PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/unit/pipelex/cogt/templating/test_template_pipeline.py b/tests/unit/pipelex/cogt/templating/test_template_pipeline.py
new file mode 100644
index 000000000..5363053d2
--- /dev/null
+++ b/tests/unit/pipelex/cogt/templating/test_template_pipeline.py
@@ -0,0 +1,573 @@
+"""Integration tests for template preprocessing and variable detection working together.
+
+These tests verify the complete pipeline: preprocess_template converts custom syntax (@, $, @?)
+to Jinja2 syntax, then detect_jinja2_required_variables extracts the required variables.
+"""
+
+from typing import ClassVar
+
+import pytest
+
+from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.cogt.templating.template_preprocessor import preprocess_template
+from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+
+
+class TestData:
+ """Test data for template pipeline integration tests."""
+
+ # (topic, raw_template, expected_jinja2, expected_variables)
+ AT_VARIABLE_PIPELINE: ClassVar[list[tuple[str, str, str, set[str]]]] = [
+ (
+ "single_at_variable",
+ "Hello @name",
+ 'Hello {{ name|tag("name") }}',
+ {"name"},
+ ),
+ (
+ "multiple_at_variables",
+ "@first and @second",
+ '{{ first|tag("first") }} and {{ second|tag("second") }}',
+ {"first", "second"},
+ ),
+ (
+ "at_variable_with_trailing_dot",
+ "The value is @amount.",
+ 'The value is {{ amount|tag("amount") }}.',
+ {"amount"},
+ ),
+ (
+ "nested_at_variable",
+ "User: @user.profile.name",
+ 'User: {{ user.profile.name|tag("user.profile.name") }}',
+ {"user.profile.name"},
+ ),
+ ]
+
+ DOLLAR_VARIABLE_PIPELINE: ClassVar[list[tuple[str, str, str, set[str]]]] = [
+ (
+ "single_dollar_variable",
+ "Topic: $topic",
+ "Topic: {{ topic|format() }}",
+ {"topic"},
+ ),
+ (
+ "multiple_dollar_variables",
+ "$first and $second",
+ "{{ first|format() }} and {{ second|format() }}",
+ {"first", "second"},
+ ),
+ (
+ "dollar_variable_with_trailing_dot",
+ "The price is $price.",
+ "The price is {{ price|format() }}.",
+ {"price"},
+ ),
+ (
+ "nested_dollar_variable",
+ "Config: $config.setting.value",
+ "Config: {{ config.setting.value|format() }}",
+ {"config.setting.value"},
+ ),
+ ]
+
+ OPTIONAL_VARIABLE_PIPELINE: ClassVar[list[tuple[str, str, str, set[str]]]] = [
+ (
+ "single_optional_variable",
+ "Optional: @?optional_field",
+ 'Optional: {% if optional_field %}{{ optional_field|tag("optional_field") }}{% endif %}',
+ {"optional_field"},
+ ),
+ (
+ "optional_with_trailing_dot",
+ "Notes: @?notes.",
+ 'Notes: {% if notes %}{{ notes|tag("notes") }}{% endif %}.',
+ {"notes"},
+ ),
+ (
+ "nested_optional_variable",
+ "@?user.profile.bio",
+ '{% if user.profile.bio %}{{ user.profile.bio|tag("user.profile.bio") }}{% endif %}',
+ {"user.profile.bio"},
+ ),
+ ]
+
+ MIXED_PATTERNS_PIPELINE: ClassVar[list[tuple[str, str, str, set[str]]]] = [
+ (
+ "all_three_patterns",
+ """Summary for $name:
+@description
+@?notes""",
+ """Summary for {{ name|format() }}:
+{{ description|tag("description") }}
+{% if notes %}{{ notes|tag("notes") }}{% endif %}""",
+ {"name", "description", "notes"},
+ ),
+ (
+ "complex_mixed_template",
+ """Report for $report_title
+
+@main_content
+
+Additional details:
+@?extra_info
+
+Generated by: $author_name""",
+ """Report for {{ report_title|format() }}
+
+{{ main_content|tag("main_content") }}
+
+Additional details:
+{% if extra_info %}{{ extra_info|tag("extra_info") }}{% endif %}
+
+Generated by: {{ author_name|format() }}""",
+ {"report_title", "main_content", "extra_info", "author_name"},
+ ),
+ ]
+
+ # Real-world complex templates
+ REAL_WORLD_TEMPLATES: ClassVar[list[tuple[str, str, set[str]]]] = [
+ (
+ "gantt_chart_analysis",
+ """I am sharing an image of a Gantt chart: $gantt_chart_image.
+Please analyse the image and for a given task name (and only this task), extract the information of the task, if relevant.
+
+Be careful, the time unit is this:
+@gantt_timescale
+
+If the task is a milestone, then only output the start_date.
+
+Here is the name of the task you have to extract the dates for:
+@gantt_task_name""",
+ {"gantt_chart_image", "gantt_timescale", "gantt_task_name"},
+ ),
+ (
+ "invoice_extraction_prompt",
+ """Extract employee information from this invoice text: @invoice_text.
+
+The company name is: $company_name
+
+Please extract the following fields:
+- Employee name
+- Employee ID
+- Department
+
+@?additional_instructions""",
+ {"invoice_text", "company_name", "additional_instructions"},
+ ),
+ (
+ "document_analysis",
+ """Analyze the following document: $document_content.
+
+Context information:
+@context_info
+
+@?reference_documents
+
+Please provide:
+1. Summary of key points
+2. Action items if any
+3. Any risks or concerns
+
+Output format: @output_format""",
+ {"document_content", "context_info", "reference_documents", "output_format"},
+ ),
+ (
+ "image_generation_prompt",
+ """Generate an image with the following characteristics:
+
+Subject: @subject_description
+Style: $art_style
+Mood: @mood
+
+@?additional_details
+
+Camera angle: $camera_angle
+Lighting: @lighting_type""",
+ {
+ "subject_description",
+ "art_style",
+ "mood",
+ "additional_details",
+ "camera_angle",
+ "lighting_type",
+ },
+ ),
+ (
+ "code_review_prompt",
+ """Review the following code: @code_snippet.
+
+Programming language: $language
+Code purpose: @purpose
+
+@?coding_standards
+
+Check for:
+- Bugs and errors
+- Performance issues
+- Security vulnerabilities
+- Code style
+
+Expected output format: $output_format""",
+ {"code_snippet", "language", "purpose", "coding_standards", "output_format"},
+ ),
+ (
+ "multi_section_document",
+ """# $document_title
+
+## Introduction
+@introduction_text
+
+## Main Content
+@main_content
+
+## Optional Sections
+@?section_a
+@?section_b
+@?section_c
+
+## Conclusion
+@conclusion_text
+
+---
+Author: $author_name
+Date: $document_date
+Version: @version_info""",
+ {
+ "document_title",
+ "introduction_text",
+ "main_content",
+ "section_a",
+ "section_b",
+ "section_c",
+ "conclusion_text",
+ "author_name",
+ "document_date",
+ "version_info",
+ },
+ ),
+ ]
+
+ # Edge cases with numbers
+ NUMBER_EDGE_CASES: ClassVar[list[tuple[str, str, str, set[str]]]] = [
+ (
+ "dollar_amount_not_variable",
+ "The price is $10 and $20",
+ "The price is $10 and $20", # Should not be converted
+ set(),
+ ),
+ (
+ "at_version_not_variable",
+ "Version @1.0 is released",
+ "Version @1.0 is released", # Should not be converted
+ set(),
+ ),
+ (
+ "mixed_amounts_and_variables",
+ "Price is $10 but budget is $budget_amount",
+ "Price is $10 but budget is {{ budget_amount|format() }}",
+ {"budget_amount"},
+ ),
+ (
+ "version_and_at_variable",
+ "Version @1.0 with @release_notes",
+ 'Version @1.0 with {{ release_notes|tag("release_notes") }}',
+ {"release_notes"},
+ ),
+ ]
+
+
+class TestTemplatePipelineIntegration:
+ """Tests for the complete template preprocessing and variable detection pipeline."""
+
+ @pytest.mark.parametrize(
+ ("topic", "raw_template", "expected_jinja2", "expected_variables"),
+ TestData.AT_VARIABLE_PIPELINE,
+ )
+ def test_at_variable_pipeline(
+ self,
+ topic: str,
+ raw_template: str,
+ expected_jinja2: str,
+ expected_variables: set[str],
+ ):
+ """Test @ variable pattern through the complete pipeline."""
+ # Step 1: Preprocess
+ processed = preprocess_template(raw_template)
+ assert processed == expected_jinja2, f"Preprocessing failed for topic: {topic}"
+
+ # Step 2: Detect variables
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == expected_variables, f"Variable detection failed for topic: {topic}"
+
+ @pytest.mark.parametrize(
+ ("topic", "raw_template", "expected_jinja2", "expected_variables"),
+ TestData.DOLLAR_VARIABLE_PIPELINE,
+ )
+ def test_dollar_variable_pipeline(
+ self,
+ topic: str,
+ raw_template: str,
+ expected_jinja2: str,
+ expected_variables: set[str],
+ ):
+ """Test $ variable pattern through the complete pipeline."""
+ # Step 1: Preprocess
+ processed = preprocess_template(raw_template)
+ assert processed == expected_jinja2, f"Preprocessing failed for topic: {topic}"
+
+ # Step 2: Detect variables
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == expected_variables, f"Variable detection failed for topic: {topic}"
+
+ @pytest.mark.parametrize(
+ ("topic", "raw_template", "expected_jinja2", "expected_variables"),
+ TestData.OPTIONAL_VARIABLE_PIPELINE,
+ )
+ def test_optional_variable_pipeline(
+ self,
+ topic: str,
+ raw_template: str,
+ expected_jinja2: str,
+ expected_variables: set[str],
+ ):
+ """Test @? optional variable pattern through the complete pipeline."""
+ # Step 1: Preprocess
+ processed = preprocess_template(raw_template)
+ assert processed == expected_jinja2, f"Preprocessing failed for topic: {topic}"
+
+ # Step 2: Detect variables
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == expected_variables, f"Variable detection failed for topic: {topic}"
+
+ @pytest.mark.parametrize(
+ ("topic", "raw_template", "expected_jinja2", "expected_variables"),
+ TestData.MIXED_PATTERNS_PIPELINE,
+ )
+ def test_mixed_patterns_pipeline(
+ self,
+ topic: str,
+ raw_template: str,
+ expected_jinja2: str,
+ expected_variables: set[str],
+ ):
+ """Test templates with mixed @, $, and @? patterns."""
+ # Step 1: Preprocess
+ processed = preprocess_template(raw_template)
+ assert processed == expected_jinja2, f"Preprocessing failed for topic: {topic}"
+
+ # Step 2: Detect variables
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == expected_variables, f"Variable detection failed for topic: {topic}"
+
+ @pytest.mark.parametrize(
+ ("topic", "raw_template", "expected_variables"),
+ TestData.REAL_WORLD_TEMPLATES,
+ )
+ def test_real_world_templates(
+ self,
+ topic: str,
+ raw_template: str,
+ expected_variables: set[str],
+ ):
+ """Test real-world complex templates through the pipeline."""
+ # Step 1: Preprocess
+ processed = preprocess_template(raw_template)
+
+ # Step 2: Detect variables
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == expected_variables, f"Variable detection failed for topic: {topic}"
+
+ @pytest.mark.parametrize(
+ ("topic", "raw_template", "expected_jinja2", "expected_variables"),
+ TestData.NUMBER_EDGE_CASES,
+ )
+ def test_number_edge_cases(
+ self,
+ topic: str,
+ raw_template: str,
+ expected_jinja2: str,
+ expected_variables: set[str],
+ ):
+ """Test edge cases where $ and @ are followed by numbers (not variables)."""
+ # Step 1: Preprocess
+ processed = preprocess_template(raw_template)
+ assert processed == expected_jinja2, f"Preprocessing failed for topic: {topic}"
+
+ # Step 2: Detect variables
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == expected_variables, f"Variable detection failed for topic: {topic}"
+
+ def test_no_variables_template(self):
+ """Test a template with no special syntax passes through unchanged."""
+ raw_template = "This is a plain text template with no variables."
+
+ processed = preprocess_template(raw_template)
+ assert processed == raw_template
+
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == set()
+
+ def test_already_jinja2_template(self):
+ """Test a template that already has Jinja2 syntax."""
+ raw_template = "Hello {{ name }}, welcome to {{ place }}"
+
+ processed = preprocess_template(raw_template)
+ assert processed == raw_template # Should not be modified
+
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == {"name", "place"}
+
+ def test_mixed_jinja2_and_custom_syntax(self):
+ """Test a template with both Jinja2 and custom syntax."""
+ raw_template = """Hello {{ existing_var }}!
+Your topic is: $topic
+Additional info: @info
+Optional: @?optional_data"""
+
+ processed = preprocess_template(raw_template)
+ expected = """Hello {{ existing_var }}!
+Your topic is: {{ topic|format() }}
+Additional info: {{ info|tag("info") }}
+Optional: {% if optional_data %}{{ optional_data|tag("optional_data") }}{% endif %}"""
+ assert processed == expected
+
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ assert variables == {"existing_var", "topic", "info", "optional_data"}
+
+ @pytest.mark.parametrize(
+ "template_category",
+ [
+ TemplateCategory.BASIC,
+ TemplateCategory.LLM_PROMPT,
+ TemplateCategory.HTML,
+ TemplateCategory.MARKDOWN,
+ TemplateCategory.IMG_GEN_PROMPT,
+ ],
+ )
+ def test_pipeline_across_template_categories(self, template_category: TemplateCategory):
+ """Test the pipeline works across different template categories."""
+ raw_template = """Title: $title
+Content: @content
+Optional: @?optional"""
+
+ processed = preprocess_template(raw_template)
+ expected = """Title: {{ title|format() }}
+Content: {{ content|tag("content") }}
+Optional: {% if optional %}{{ optional|tag("optional") }}{% endif %}"""
+ assert processed == expected
+
+ variables = detect_jinja2_required_variables(
+ template_category=template_category,
+ template_source=processed,
+ )
+ assert variables == {"title", "content", "optional"}
+
+ def test_multiline_template_with_all_patterns(self):
+ """Test a complex multiline template with all pattern types."""
+ raw_template = """
+==============================
+Report: $report_name
+==============================
+
+Section 1: Overview
+-------------------
+@overview_content
+
+Section 2: Details
+------------------
+@details_content
+
+Section 3: Optional Notes
+-------------------------
+@?optional_notes
+
+Section 4: Summary
+------------------
+@summary_content
+
+==============================
+Generated for: $recipient_name
+Date: $generation_date
+==============================
+"""
+
+ processed = preprocess_template(raw_template)
+
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+
+ expected_vars = {
+ "report_name",
+ "overview_content",
+ "details_content",
+ "optional_notes",
+ "summary_content",
+ "recipient_name",
+ "generation_date",
+ }
+ assert variables == expected_vars
+
+ def test_variable_used_multiple_times(self):
+ """Test that a variable used multiple times is detected only once."""
+ raw_template = """
+@name appears here.
+And @name appears again.
+Also $name as dollar variable.
+And @?name as optional.
+"""
+ processed = preprocess_template(raw_template)
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ # All should resolve to the same variable
+ assert variables == {"name"}
+
+ def test_deeply_nested_variable_names(self):
+ """Test variables with deep dot notation."""
+ raw_template = """
+User info: @user.profile.settings.preferences.theme
+Config: $app.config.database.connection.host
+Optional: @?system.logs.archive.old.entries
+"""
+ processed = preprocess_template(raw_template)
+ variables = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=processed,
+ )
+ # Full variable paths are detected
+ assert variables == {
+ "user.profile.settings.preferences.theme",
+ "app.config.database.connection.host",
+ "system.logs.archive.old.entries",
+ }
diff --git a/tests/unit/pipelex/cogt/templating/test_template_preprocessor.py b/tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
index fb90125ea..e2fd2ab3d 100644
--- a/tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
+++ b/tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
@@ -145,3 +145,293 @@ Optional notes:
pretty_print(result, title="result")
pretty_print(expected, title="expected")
assert result == expected
+
+ # =========================================================================
+ # Real-world template tests
+ # =========================================================================
+
+ def test_gantt_chart_analysis_template(self):
+ """Test real-world Gantt chart analysis template."""
+ template = """I am sharing an image of a Gantt chart: $gantt_chart_image.
+Please analyse the image and for a given task name (and only this task), extract the information of the task, if relevant.
+
+Be careful, the time unit is this:
+@gantt_timescale
+
+If the task is a milestone, then only output the start_date.
+
+Here is the name of the task you have to extract the dates for:
+@gantt_task_name"""
+
+ result = preprocess_template(template)
+ expected = """I am sharing an image of a Gantt chart: {{ gantt_chart_image|format() }}.
+Please analyse the image and for a given task name (and only this task), extract the information of the task, if relevant.
+
+Be careful, the time unit is this:
+{{ gantt_timescale|tag("gantt_timescale") }}
+
+If the task is a milestone, then only output the start_date.
+
+Here is the name of the task you have to extract the dates for:
+{{ gantt_task_name|tag("gantt_task_name") }}"""
+
+ assert result == expected
+
+ def test_invoice_extraction_template(self):
+ """Test real-world invoice extraction template."""
+ template = """Extract employee information from this invoice text: @invoice_text.
+
+The company name is: $company_name
+
+Please extract the following fields:
+- Employee name
+- Employee ID
+- Department
+
+@?additional_instructions"""
+
+ result = preprocess_template(template)
+ expected = """Extract employee information from this invoice text: {{ invoice_text|tag("invoice_text") }}.
+
+The company name is: {{ company_name|format() }}
+
+Please extract the following fields:
+- Employee name
+- Employee ID
+- Department
+
+{% if additional_instructions %}{{ additional_instructions|tag("additional_instructions") }}{% endif %}"""
+
+ assert result == expected
+
+ # =========================================================================
+ # Edge cases with punctuation and special characters
+ # =========================================================================
+
+ def test_variable_followed_by_comma(self):
+ """Test variable followed by comma."""
+ template = "Values: @first, @second, and @third"
+ result = preprocess_template(template)
+ expected = 'Values: {{ first|tag("first") }}, {{ second|tag("second") }}, and {{ third|tag("third") }}'
+ assert result == expected
+
+ def test_variable_followed_by_colon(self):
+ """Test variable followed by colon."""
+ template = "@label: the value is @value"
+ result = preprocess_template(template)
+ expected = '{{ label|tag("label") }}: the value is {{ value|tag("value") }}'
+ assert result == expected
+
+ def test_variable_followed_by_semicolon(self):
+ """Test variable followed by semicolon."""
+ template = "First: @first; Second: @second"
+ result = preprocess_template(template)
+ expected = 'First: {{ first|tag("first") }}; Second: {{ second|tag("second") }}'
+ assert result == expected
+
+ def test_variable_in_parentheses(self):
+ """Test variable inside parentheses."""
+ template = "The value (@value) is important"
+ result = preprocess_template(template)
+ expected = 'The value ({{ value|tag("value") }}) is important'
+ assert result == expected
+
+ def test_variable_in_brackets(self):
+ """Test variable inside square brackets."""
+ template = "Array element [$index] = @element"
+ result = preprocess_template(template)
+ expected = 'Array element [{{ index|format() }}] = {{ element|tag("element") }}'
+ assert result == expected
+
+ def test_variable_followed_by_question_mark(self):
+ """Test variable followed by question mark (but not @? pattern)."""
+ template = "Is @value correct?"
+ result = preprocess_template(template)
+ expected = 'Is {{ value|tag("value") }} correct?'
+ assert result == expected
+
+ def test_variable_followed_by_exclamation(self):
+ """Test variable followed by exclamation mark."""
+ template = "Hello @name!"
+ result = preprocess_template(template)
+ expected = 'Hello {{ name|tag("name") }}!'
+ assert result == expected
+
+ # =========================================================================
+ # Variables at different positions
+ # =========================================================================
+
+ def test_variable_at_start_of_line(self):
+ """Test variable at the start of a line."""
+ template = "@start_var is at the beginning"
+ result = preprocess_template(template)
+ expected = '{{ start_var|tag("start_var") }} is at the beginning'
+ assert result == expected
+
+ def test_variable_at_end_of_line(self):
+ """Test variable at the end of a line (no trailing punctuation)."""
+ template = "The value is @end_var"
+ result = preprocess_template(template)
+ expected = 'The value is {{ end_var|tag("end_var") }}'
+ assert result == expected
+
+ def test_variable_alone_on_line(self):
+ """Test variable alone on its own line."""
+ template = """Line before
+@alone_var
+Line after"""
+ result = preprocess_template(template)
+ expected = """Line before
+{{ alone_var|tag("alone_var") }}
+Line after"""
+ assert result == expected
+
+ def test_back_to_back_at_variables(self):
+ """Test multiple @ variables back to back with space."""
+ template = "@first @second @third"
+ result = preprocess_template(template)
+ expected = '{{ first|tag("first") }} {{ second|tag("second") }} {{ third|tag("third") }}'
+ assert result == expected
+
+ def test_back_to_back_dollar_variables(self):
+ """Test multiple $ variables back to back with space."""
+ template = "$first $second $third"
+ result = preprocess_template(template)
+ expected = "{{ first|format() }} {{ second|format() }} {{ third|format() }}"
+ assert result == expected
+
+ # =========================================================================
+ # Complex nested variable names
+ # =========================================================================
+
+ def test_deeply_nested_at_variable(self):
+ """Test deeply nested @ variable with multiple dots."""
+ template = "@user.profile.settings.preferences.theme"
+ result = preprocess_template(template)
+ expected = '{{ user.profile.settings.preferences.theme|tag("user.profile.settings.preferences.theme") }}'
+ assert result == expected
+
+ def test_deeply_nested_dollar_variable(self):
+ """Test deeply nested $ variable with multiple dots."""
+ template = "$config.database.connection.pool.size"
+ result = preprocess_template(template)
+ expected = "{{ config.database.connection.pool.size|format() }}"
+ assert result == expected
+
+ def test_deeply_nested_optional_variable(self):
+ """Test deeply nested @? optional variable."""
+ template = "@?system.logs.archive.entries"
+ result = preprocess_template(template)
+ expected = '{% if system.logs.archive.entries %}{{ system.logs.archive.entries|tag("system.logs.archive.entries") }}{% endif %}'
+ assert result == expected
+
+ # =========================================================================
+ # Variable names with underscores
+ # =========================================================================
+
+ def test_variable_with_leading_underscore(self):
+ """Test variable name starting with underscore."""
+ template = "@_private_var and $_another_private"
+ result = preprocess_template(template)
+ expected = '{{ _private_var|tag("_private_var") }} and {{ _another_private|format() }}'
+ assert result == expected
+
+ def test_variable_with_multiple_underscores(self):
+ """Test variable name with multiple consecutive underscores."""
+ template = "@snake__case__var"
+ result = preprocess_template(template)
+ expected = '{{ snake__case__var|tag("snake__case__var") }}'
+ assert result == expected
+
+ def test_variable_ending_with_underscore(self):
+ """Test variable name ending with underscore."""
+ template = "@trailing_"
+ result = preprocess_template(template)
+ expected = '{{ trailing_|tag("trailing_") }}'
+ assert result == expected
+
+ # =========================================================================
+ # Mixed scenarios
+ # =========================================================================
+
+ def test_all_pattern_types_in_one_line(self):
+ """Test all three pattern types in a single line."""
+ template = "$dollar_var @at_var @?optional_var"
+ result = preprocess_template(template)
+ expected = '{{ dollar_var|format() }} {{ at_var|tag("at_var") }} {% if optional_var %}{{ optional_var|tag("optional_var") }}{% endif %}'
+ assert result == expected
+
+ def test_nested_with_trailing_dot_in_complex_sentence(self):
+ """Test nested variable with trailing dot in complex context."""
+ template = "The user's preference is @user.settings.theme. Please apply it."
+ result = preprocess_template(template)
+ expected = 'The user\'s preference is {{ user.settings.theme|tag("user.settings.theme") }}. Please apply it.'
+ assert result == expected
+
+ def test_variable_adjacent_to_newline(self):
+ """Test variable immediately before newline."""
+ template = "First: @first\nSecond: @second"
+ result = preprocess_template(template)
+ expected = 'First: {{ first|tag("first") }}\nSecond: {{ second|tag("second") }}'
+ assert result == expected
+
+ def test_empty_template(self):
+ """Test empty template string."""
+ template = ""
+ result = preprocess_template(template)
+ assert result == ""
+
+ def test_whitespace_only_template(self):
+ """Test template with only whitespace."""
+ template = " \n\t\n "
+ result = preprocess_template(template)
+ assert result == template
+
+ def test_template_with_existing_jinja2_syntax(self):
+ """Test that existing Jinja2 syntax is preserved."""
+ template = "Hello {{ existing_var }}, your topic is $topic"
+ result = preprocess_template(template)
+ expected = "Hello {{ existing_var }}, your topic is {{ topic|format() }}"
+ assert result == expected
+
+ def test_multiple_optional_variables_in_sequence(self):
+ """Test multiple optional variables in sequence."""
+ template = "@?first @?second @?third"
+ result = preprocess_template(template)
+ expected = (
+ '{% if first %}{{ first|tag("first") }}{% endif %} '
+ '{% if second %}{{ second|tag("second") }}{% endif %} '
+ '{% if third %}{{ third|tag("third") }}{% endif %}'
+ )
+ assert result == expected
+
+ # =========================================================================
+ # Edge cases with @ symbol in non-variable contexts
+ # =========================================================================
+
+ def test_email_address_partially_processed(self):
+ """Test that email-like patterns are partially processed (after @).
+
+ The regex pattern [a-zA-Z0-9_.] matches 'example.com' as a single variable
+ name since dots are allowed in variable names.
+ """
+ # Note: [email protected] will match 'domain.ext' as variable after @
+ template = "Contact: [email protected]"
+ result = preprocess_template(template)
+ # After @ we have example.com which matches entirely as variable name
+ expected = 'Contact: someone{{ example.com|tag("example.com") }}'
+ assert result == expected
+
+ def test_at_sign_alone(self):
+ """Test @ sign alone (not followed by valid variable name char)."""
+ template = "Price @ store: $price"
+ result = preprocess_template(template)
+ expected = "Price @ store: {{ price|format() }}"
+ assert result == expected
+
+ def test_dollar_sign_alone(self):
+ """Test $ sign alone (not followed by valid variable name char)."""
+ template = "Cost is $ for @item"
+ result = preprocess_template(template)
+ expected = 'Cost is $ for {{ item|tag("item") }}'
+ assert result == expected
diff --git a/tests/unit/pipelex/core/bundles/test_data_pipe_sorter.py b/tests/unit/pipelex/core/bundles/test_data_pipe_sorter.py
index 69da65b0c..a0e56fc68 100644
--- a/tests/unit/pipelex/core/bundles/test_data_pipe_sorter.py
+++ b/tests/unit/pipelex/core/bundles/test_data_pipe_sorter.py
@@ -176,16 +176,19 @@ class PipeSorterTestCases:
description="Analyzes the input photo to understand visual elements, composition, mood, etc.",
inputs={"input_photo": "Image"},
output="ImageAnalysis",
+ prompt="Analyze this image: @input_photo",
),
"define_opposite_concept": PipeLLMBlueprint(
description="Determines what constitutes the opposite for the analyzed image",
inputs={"image_analysis": "ImageAnalysis"},
output="OppositeDefinition",
+ prompt="Define opposite for: @image_analysis",
),
"generate_image_prompt": PipeLLMBlueprint(
description="Crafts a detailed image generation prompt from the opposite definition",
inputs={"opposite_definition": "OppositeDefinition"},
output="ImagePrompt",
+ prompt="Generate prompt from: @opposite_definition",
),
"generate_opposite_image": PipeImgGenBlueprint(
description="Generates the opposite image using AI",
@@ -254,31 +257,37 @@ class PipeSorterTestCases:
description="Prepare the data",
inputs={"input": "Text"},
output="Text",
+ prompt="Prepare: @input",
),
"validate_data": PipeLLMBlueprint(
description="Validate the prepared data",
inputs={"prepared_data": "Text"},
output="Text",
+ prompt="Validate: @prepared_data",
),
"process_small": PipeLLMBlueprint(
description="Process small items",
inputs={"item": "Text"},
output="Text",
+ prompt="Process small: @item",
),
"process_large": PipeLLMBlueprint(
description="Process large items",
inputs={"item": "Text"},
output="Text",
+ prompt="Process large: @item",
),
"process_default": PipeLLMBlueprint(
description="Default processing",
inputs={"item": "Text"},
output="Text",
+ prompt="Process default: @item",
),
"final_process": PipeLLMBlueprint(
description="Final processing step",
inputs={"processed": "Text"},
output="Text",
+ prompt="Final process: @processed",
),
}
# Expected order: main_pipeline first, then following step order
diff --git a/tests/unit/pipelex/core/pipes/test_pipe_blueprint.py b/tests/unit/pipelex/core/pipes/test_pipe_blueprint.py
index 84a766090..75ee52826 100644
--- a/tests/unit/pipelex/core/pipes/test_pipe_blueprint.py
+++ b/tests/unit/pipelex/core/pipes/test_pipe_blueprint.py
@@ -20,6 +20,7 @@ class TestPipeBlueprintValidation:
blueprint = ConcretePipeBlueprint(
type=pipe_type,
pipe_category=category,
+ description="lorem ipsum",
output="Text",
)
assert blueprint.type == pipe_type
@@ -31,6 +32,7 @@ class TestPipeBlueprintValidation:
ConcretePipeBlueprint(
type=invalid_type,
pipe_category="PipeOperator",
+ description="lorem ipsum",
output="Text",
)
assert "Invalid pipe type" in str(exc_info.value)
@@ -46,6 +48,7 @@ class TestPipeBlueprintValidation:
blueprint = ConcretePipeBlueprint(
type=pipe_type,
pipe_category=category,
+ description="lorem ipsum",
output="Text",
)
assert blueprint.pipe_category == category
@@ -57,6 +60,7 @@ class TestPipeBlueprintValidation:
ConcretePipeBlueprint(
type="PipeLLM",
pipe_category=invalid_category,
+ description="lorem ipsum",
output="Text",
)
assert "Invalid pipe category" in str(exc_info.value)
@@ -65,6 +69,7 @@ class TestPipeBlueprintValidation:
blueprint = ConcretePipeBlueprint(
type="PipeLLM",
pipe_category="PipeOperator",
+ description="lorem ipsum",
inputs={"text": "Text", "prompt": "Text"},
output="Text",
)
@@ -73,6 +78,7 @@ class TestPipeBlueprintValidation:
blueprint = ConcretePipeBlueprint(
type="PipeLLM",
pipe_category="PipeOperator",
+ description="lorem ipsum",
inputs=None,
output="Text",
)
@@ -81,6 +87,7 @@ class TestPipeBlueprintValidation:
blueprint = ConcretePipeBlueprint(
type="PipeLLM",
pipe_category="PipeOperator",
+ description="lorem ipsum",
inputs={"items": "Text[]", "count": "Number[2]"},
output="Text",
)
@@ -91,6 +98,7 @@ class TestPipeBlueprintValidation:
ConcretePipeBlueprint(
type="PipeLLM",
pipe_category="PipeOperator",
+ description="lorem ipsum",
inputs={"text": "InvalidFormat!"},
output="Text",
)
@@ -100,6 +108,7 @@ class TestPipeBlueprintValidation:
ConcretePipeBlueprint(
type="PipeLLM",
pipe_category="PipeOperator",
+ description="lorem ipsum",
inputs={"text": "invalid_concept"},
output="Text",
)
@@ -109,6 +118,7 @@ class TestPipeBlueprintValidation:
ConcretePipeBlueprint(
type="PipeLLM",
pipe_category="PipeOperator",
+ description="lorem ipsum",
inputs={"text": "Text"},
output="InvalidConcept!",
)
@@ -119,6 +129,7 @@ class TestPipeBlueprintValidation:
ConcretePipeBlueprint(
type="PipeLLM",
pipe_category="PipeOperator",
+ description="lorem ipsum",
output="Text",
extra_field="should not be allowed", # type: ignore[call-arg]
)
diff --git a/tests/unit/pipelex/core/test_data/pipes/operators/llm/pipe_llm.py b/tests/unit/pipelex/core/test_data/pipes/operators/llm/pipe_llm.py
index da348241f..fe8ea6cde 100644
--- a/tests/unit/pipelex/core/test_data/pipes/operators/llm/pipe_llm.py
+++ b/tests/unit/pipelex/core/test_data/pipes/operators/llm/pipe_llm.py
@@ -188,7 +188,7 @@ type = "PipeLLM"
description = "Analyze image content"
inputs = { image = "Image" }
output = "Text"
-prompt = "Describe what you see in this image in detail"
+prompt = "Describe what you see in this image in detail: $image"
""",
PipelexBundleBlueprint(
domain="test_pipes",
@@ -199,7 +199,7 @@ prompt = "Describe what you see in this image in detail"
description="Analyze image content",
inputs={"image": "Image"},
output=NativeConceptCode.TEXT,
- prompt="Describe what you see in this image in detail",
+ prompt="Describe what you see in this image in detail: $image",
),
},
),
diff --git a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_blueprint.py b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_blueprint.py
index 4e5e446c7..b0dfa83f2 100644
--- a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_blueprint.py
+++ b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_blueprint.py
@@ -4,19 +4,21 @@ from pipelex.pipe_controllers.batch.pipe_batch_blueprint import PipeBatchBluepri
class TestPipeBatchBlueprint:
def test_pipe_dependencies_correct(self):
blueprint = PipeBatchBlueprint(
+ description="lorem ipsum",
+ inputs={"items": "Text[]"},
+ output="Text[]",
branch_pipe_code="process_item",
input_list_name="items",
input_item_name="item",
- inputs={"items": "Text[]"},
- output="Text[]",
)
assert blueprint.pipe_dependencies == {"process_item"}
blueprint = PipeBatchBlueprint(
+ description="lorem ipsum",
+ inputs={"data_list": "Number[]"},
+ output="Number[]",
branch_pipe_code="transform_data",
input_list_name="data_list",
input_item_name="data",
- inputs={"data_list": "Number[]"},
- output="Number[]",
)
assert blueprint.pipe_dependencies == {"transform_data"}
diff --git a/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_blueprint.py b/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_blueprint.py
index fb4a0c10e..50f68e93c 100644
--- a/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_blueprint.py
+++ b/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_blueprint.py
@@ -8,58 +8,64 @@ from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
class TestPipeConditionBlueprint:
def test_pipe_dependencies_correct(self):
blueprint = PipeConditionBlueprint(
+ description="lorem ipsum",
+ inputs={"status": "Text"},
+ output="Text",
expression="status",
outcomes={"active": "process_active", "inactive": "process_inactive"},
default_outcome="process_default",
- inputs={"status": "Text"},
- output="Text",
)
assert blueprint.pipe_dependencies == {"process_active", "process_inactive", "process_default"}
blueprint = PipeConditionBlueprint(
+ description="lorem ipsum",
+ inputs={"type": "Text"},
+ output="Text",
expression="type",
outcomes={"A": "handle_a"},
default_outcome=SpecialOutcome.FAIL,
- inputs={"type": "Text"},
- output="Text",
)
assert blueprint.pipe_dependencies == {"handle_a"}
blueprint = PipeConditionBlueprint(
+ description="lorem ipsum",
+ inputs={"flag": "Text"},
+ output="Text",
expression="flag",
outcomes={"yes": "process_yes", "no": "process_no"},
default_outcome=SpecialOutcome.CONTINUE,
- inputs={"flag": "Text"},
- output="Text",
)
assert blueprint.pipe_dependencies == {"process_yes", "process_no"}
def test_validate_outcome_map_correct(self):
blueprint = PipeConditionBlueprint(
+ description="lorem ipsum",
+ inputs={"value": "Text"},
+ output="Text",
expression="value",
outcomes={"high": "process_high"},
default_outcome="process_default",
- inputs={"value": "Text"},
- output="Text",
)
assert blueprint.outcomes == {"high": "process_high"}
blueprint = PipeConditionBlueprint(
+ description="lorem ipsum",
+ inputs={"status": "Text"},
+ output="Text",
expression="status",
outcomes={"active": "process_active", "inactive": "process_inactive"},
default_outcome="process_default",
- inputs={"status": "Text"},
- output="Text",
)
assert len(blueprint.outcomes) == 2
def test_validate_outcome_map_incorrect(self):
with pytest.raises(ValidationError) as exc_info:
PipeConditionBlueprint(
+ description="lorem ipsum",
+ inputs={"value": "Text"},
+ output="Text",
expression="value",
outcomes={},
default_outcome="process_default",
- inputs={"value": "Text"},
- output="Text",
)
assert "PipeConditionBlueprint must have at least one mapping in outcomes" in str(exc_info.value)
diff --git a/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py b/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py
new file mode 100644
index 000000000..0491e6398
--- /dev/null
+++ b/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py
@@ -0,0 +1,749 @@
+from typing import Callable
+
+import pytest
+
+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.pipes.exceptions import PipeValidationError
+from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
+from pipelex.core.pipes.pipe_factory import PipeFactory
+from pipelex.hub import get_concept_library, get_pipe_library
+from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
+from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
+from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
+from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
+from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
+
+
+class TestPipeConditionNeededInputs:
+ """Tests for PipeCondition.needed_inputs method."""
+
+ def test_needed_inputs_collects_expression_variables(self, load_empty_library: Callable[[], None]):
+ """Test that variables from the expression are collected as needed inputs."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+
+ # Create concepts
+ text_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="TextOutput",
+ blueprint_or_string_description=ConceptBlueprint(description="Text output"),
+ )
+ concept_library.add_concepts(concepts=[text_concept])
+
+ # Create PipeCondition with expression that uses variables
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with expression variables",
+ inputs={"status": "native.Text", "priority": "native.Text"},
+ output="native.Text",
+ expression="status", # Uses 'status' variable (gets wrapped in {{ }} internally)
+ outcomes={"active": SpecialOutcome.CONTINUE, "inactive": SpecialOutcome.CONTINUE},
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Get needed inputs
+ needed_inputs = pipe_condition.needed_inputs()
+
+ # Verify it returns InputStuffSpecs
+ assert isinstance(needed_inputs, InputStuffSpecs)
+
+ # The expression uses 'status', so it should be in needed inputs
+ assert "status" in needed_inputs.root
+ # The concept for expression variables is Anything since we can't infer the type
+ assert needed_inputs.root["status"].concept.code == NativeConceptCode.ANYTHING
+
+ concept_library.teardown()
+
+ def test_needed_inputs_collects_from_mapped_pipes(self, load_empty_library: Callable[[], None]):
+ """Test that needed_inputs collects inputs from all mapped pipes."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create concepts
+ document_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Document",
+ blueprint_or_string_description=ConceptBlueprint(description="A document"),
+ )
+ analysis_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Analysis",
+ blueprint_or_string_description=ConceptBlueprint(description="An analysis"),
+ )
+ concept_library.add_concepts(concepts=[document_concept, analysis_concept])
+
+ # Create two PipeLLM pipes that the condition will map to
+ pipe_a_blueprint = PipeLLMBlueprint(
+ description="Pipe A",
+ inputs={"doc_input": document_concept.concept_ref},
+ output=analysis_concept.concept_ref,
+ prompt="Analyze: @doc_input",
+ )
+ pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_a",
+ blueprint=pipe_a_blueprint,
+ concept_codes_from_the_same_domain=[document_concept.code, analysis_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_a)
+
+ pipe_b_blueprint = PipeLLMBlueprint(
+ description="Pipe B",
+ inputs={"other_doc": document_concept.concept_ref},
+ output=analysis_concept.concept_ref,
+ prompt="Summarize: @other_doc",
+ )
+ pipe_b = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_b",
+ blueprint=pipe_b_blueprint,
+ concept_codes_from_the_same_domain=[document_concept.code, analysis_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_b)
+
+ # Create PipeCondition that maps to these pipes
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition mapping to pipe_a and pipe_b",
+ inputs={"selector": "native.Text"},
+ output=analysis_concept.concept_ref,
+ expression="selector",
+ outcomes={"option_a": "pipe_a", "option_b": "pipe_b"},
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Get needed inputs
+ needed_inputs = pipe_condition.needed_inputs()
+
+ # Should contain 'selector' from expression
+ assert "selector" in needed_inputs.root
+
+ # Should contain inputs from pipe_a and pipe_b
+ assert "doc_input" in needed_inputs.root
+ assert "other_doc" in needed_inputs.root
+
+ # Verify concept types for mapped pipe inputs
+ assert needed_inputs.root["doc_input"].concept.code == document_concept.code
+ assert needed_inputs.root["other_doc"].concept.code == document_concept.code
+
+ concept_library.teardown()
+
+ def test_needed_inputs_preserves_multiplicity(self, load_empty_library: Callable[[], None]):
+ """Test that needed_inputs correctly preserves multiplicity from mapped pipes."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create concepts
+ item_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Item",
+ blueprint_or_string_description=ConceptBlueprint(description="An item"),
+ )
+ result_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Result",
+ blueprint_or_string_description=ConceptBlueprint(description="A result"),
+ )
+ concept_library.add_concepts(concepts=[item_concept, result_concept])
+
+ # Create a pipe with multiplicity input (list of items)
+ pipe_with_list_blueprint = PipeLLMBlueprint(
+ description="Pipe with list input",
+ inputs={"items": f"{item_concept.concept_ref}[]"}, # List multiplicity
+ output=result_concept.concept_ref,
+ prompt="Process items: @items",
+ )
+ pipe_with_list = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_with_list",
+ blueprint=pipe_with_list_blueprint,
+ concept_codes_from_the_same_domain=[item_concept.code, result_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_with_list)
+
+ # Create PipeCondition that maps to this pipe
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with list input pipe",
+ inputs={"mode": "native.Text"},
+ output=result_concept.concept_ref,
+ expression="mode",
+ outcomes={"batch": "pipe_with_list"},
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Get needed inputs
+ needed_inputs = pipe_condition.needed_inputs()
+
+ # Verify multiplicity is preserved
+ assert "items" in needed_inputs.root
+ assert needed_inputs.root["items"].multiplicity is True # [] means list (True)
+
+ concept_library.teardown()
+
+
+class TestPipeConditionOutputValidation:
+ """Tests for PipeCondition output validation (all mapped pipes should have matching outputs)."""
+
+ def test_validate_output_all_pipes_same_output(self, load_empty_library: Callable[[], None]):
+ """Test that validation passes when all mapped pipes have the same output concept."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create concepts
+ input_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Input",
+ blueprint_or_string_description=ConceptBlueprint(description="Input"),
+ )
+ output_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="SharedOutput",
+ blueprint_or_string_description=ConceptBlueprint(description="Shared output"),
+ )
+ concept_library.add_concepts(concepts=[input_concept, output_concept])
+
+ # Create two pipes with the SAME output concept
+ pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_a",
+ blueprint=PipeLLMBlueprint(
+ description="Pipe A",
+ inputs={"input_a": input_concept.concept_ref},
+ output=output_concept.concept_ref, # Same output
+ prompt="Process A: @input_a",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_a)
+
+ pipe_b = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_b",
+ blueprint=PipeLLMBlueprint(
+ description="Pipe B",
+ inputs={"input_b": input_concept.concept_ref},
+ output=output_concept.concept_ref, # Same output
+ prompt="Process B: @input_b",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_b)
+
+ # Create PipeCondition with the SAME output as mapped pipes
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with matching outputs",
+ inputs={"selector": "native.Text"},
+ output=output_concept.concept_ref, # Matches pipe_a and pipe_b output
+ expression="selector",
+ outcomes={"a": "pipe_a", "b": "pipe_b"},
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Should not raise - outputs match
+ pipe_condition.validate_output_with_library()
+
+ concept_library.teardown()
+
+ def test_validate_output_mismatched_outputs_raises_error(self, load_empty_library: Callable[[], None]):
+ """Test that validation fails when PipeCondition output doesn't match a mapped pipe's output."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create concepts
+ input_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Input",
+ blueprint_or_string_description=ConceptBlueprint(description="Input"),
+ )
+ output_a = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="OutputA",
+ blueprint_or_string_description=ConceptBlueprint(description="Output A"),
+ )
+ output_b = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="OutputB",
+ blueprint_or_string_description=ConceptBlueprint(description="Output B"),
+ )
+ concept_library.add_concepts(concepts=[input_concept, output_a, output_b])
+
+ # Create two pipes with DIFFERENT output concepts
+ pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_a",
+ blueprint=PipeLLMBlueprint(
+ description="Pipe A",
+ inputs={"input_a": input_concept.concept_ref},
+ output=output_a.concept_ref, # OutputA
+ prompt="Process A: @input_a",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_a)
+
+ pipe_b = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_b",
+ blueprint=PipeLLMBlueprint(
+ description="Pipe B",
+ inputs={"input_b": input_concept.concept_ref},
+ output=output_b.concept_ref, # OutputB - different!
+ prompt="Process B: @input_b",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_b)
+
+ # Create PipeCondition with OutputA (doesn't match pipe_b's output)
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with mismatched outputs",
+ inputs={"selector": "native.Text"},
+ output=output_a.concept_ref, # Only matches pipe_a, not pipe_b
+ expression="selector",
+ outcomes={"a": "pipe_a", "b": "pipe_b"},
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Should raise PipeValidationError because pipe_b has different output
+ with pytest.raises(PipeValidationError) as exc_info:
+ pipe_condition.validate_output_with_library()
+
+ assert "OutputB" in str(exc_info.value) or "not matching" in str(exc_info.value)
+
+ concept_library.teardown()
+
+ def test_validate_output_anything_matches_all(self, load_empty_library: Callable[[], None]):
+ """Test that PipeCondition with Anything output matches any mapped pipe output."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create concepts
+ input_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Input",
+ blueprint_or_string_description=ConceptBlueprint(description="Input"),
+ )
+ output_a = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="OutputA",
+ blueprint_or_string_description=ConceptBlueprint(description="Output A"),
+ )
+ output_b = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="OutputB",
+ blueprint_or_string_description=ConceptBlueprint(description="Output B"),
+ )
+ concept_library.add_concepts(concepts=[input_concept, output_a, output_b])
+
+ # Create two pipes with DIFFERENT output concepts
+ pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_a",
+ blueprint=PipeLLMBlueprint(
+ description="Pipe A",
+ inputs={"input_a": input_concept.concept_ref},
+ output=output_a.concept_ref,
+ prompt="Process A: @input_a",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_a)
+
+ pipe_b = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_b",
+ blueprint=PipeLLMBlueprint(
+ description="Pipe B",
+ inputs={"input_b": input_concept.concept_ref},
+ output=output_b.concept_ref,
+ prompt="Process B: @input_b",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_b)
+
+ # Create PipeCondition with ANYTHING output - should match any pipe output
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with Anything output",
+ inputs={"selector": "native.Text"},
+ output=NativeConceptCode.ANYTHING.concept_ref, # Anything matches all
+ expression="selector",
+ outcomes={"a": "pipe_a", "b": "pipe_b"},
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Should not raise - Anything matches any output
+ pipe_condition.validate_output_with_library()
+
+ concept_library.teardown()
+
+ def test_validate_output_dynamic_matches_all(self, load_empty_library: Callable[[], None]):
+ """Test that PipeCondition with Dynamic output matches any mapped pipe output."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create concepts
+ input_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Input",
+ blueprint_or_string_description=ConceptBlueprint(description="Input"),
+ )
+ output_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="SpecificOutput",
+ blueprint_or_string_description=ConceptBlueprint(description="Specific output"),
+ )
+ concept_library.add_concepts(concepts=[input_concept, output_concept])
+
+ # Create a pipe with a specific output
+ pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="pipe_a",
+ blueprint=PipeLLMBlueprint(
+ description="Pipe A",
+ inputs={"input_a": input_concept.concept_ref},
+ output=output_concept.concept_ref,
+ prompt="Process A: @input_a",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_a)
+
+ # Create PipeCondition with DYNAMIC output - should match any pipe output
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with Dynamic output",
+ inputs={"selector": "native.Text"},
+ output=NativeConceptCode.DYNAMIC.concept_ref, # Dynamic matches all
+ expression="selector",
+ outcomes={"a": "pipe_a"},
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Should not raise - Dynamic matches any output
+ pipe_condition.validate_output_with_library()
+
+ concept_library.teardown()
+
+
+class TestPipeConditionSpecialOutcomes:
+ """Tests for PipeCondition with special outcomes (CONTINUE, FAIL)."""
+
+ def test_needed_inputs_with_all_continue_outcomes(self, load_empty_library: Callable[[], None]):
+ """Test needed_inputs when all outcomes are CONTINUE (no actual pipes)."""
+ load_empty_library()
+ domain_code = "test_domain"
+
+ # Create PipeCondition where all outcomes are CONTINUE
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with only CONTINUE outcomes",
+ inputs={"status": "native.Text"},
+ output="native.Text",
+ expression="status",
+ outcomes={"active": SpecialOutcome.CONTINUE, "inactive": SpecialOutcome.CONTINUE},
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Get needed inputs
+ needed_inputs = pipe_condition.needed_inputs()
+
+ # Should only contain expression variable, no inputs from mapped pipes (there are none)
+ assert isinstance(needed_inputs, InputStuffSpecs)
+ assert "status" in needed_inputs.root
+ # Only the expression variable should be present
+ assert len(needed_inputs.root) == 1
+
+ def test_needed_inputs_with_all_fail_outcomes(self, load_empty_library: Callable[[], None]):
+ """Test needed_inputs when all outcomes are FAIL (no actual pipes)."""
+ load_empty_library()
+ domain_code = "test_domain"
+
+ # Create PipeCondition where all outcomes are FAIL
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with only FAIL outcomes",
+ inputs={"error_type": "native.Text"},
+ output="native.Text",
+ expression="error_type",
+ outcomes={"critical": SpecialOutcome.FAIL, "warning": SpecialOutcome.FAIL},
+ default_outcome=SpecialOutcome.FAIL,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Get needed inputs
+ needed_inputs = pipe_condition.needed_inputs()
+
+ # Should only contain expression variable, no inputs from mapped pipes (there are none)
+ assert isinstance(needed_inputs, InputStuffSpecs)
+ assert "error_type" in needed_inputs.root
+ assert len(needed_inputs.root) == 1
+
+ def test_needed_inputs_with_mixed_pipe_and_continue(self, load_empty_library: Callable[[], None]):
+ """Test needed_inputs when some outcomes are pipes and some are CONTINUE."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create concepts
+ input_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Input",
+ blueprint_or_string_description=ConceptBlueprint(description="Input"),
+ )
+ output_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Output",
+ blueprint_or_string_description=ConceptBlueprint(description="Output"),
+ )
+ concept_library.add_concepts(concepts=[input_concept, output_concept])
+
+ # Create a pipe for one of the outcomes
+ pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="process_pipe",
+ blueprint=PipeLLMBlueprint(
+ description="Process pipe",
+ inputs={"doc": input_concept.concept_ref},
+ output=output_concept.concept_ref,
+ prompt="Process: @doc",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_a)
+
+ # Create PipeCondition with mixed outcomes: one pipe, one CONTINUE, default CONTINUE
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with mixed pipe and CONTINUE",
+ inputs={"action": "native.Text"},
+ output=output_concept.concept_ref,
+ expression="action",
+ outcomes={
+ "process": "process_pipe", # Actual pipe
+ "skip": SpecialOutcome.CONTINUE, # Special outcome
+ },
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Get needed inputs
+ needed_inputs = pipe_condition.needed_inputs()
+
+ # Should contain expression variable AND inputs from the actual pipe
+ assert "action" in needed_inputs.root # From expression
+ assert "doc" in needed_inputs.root # From process_pipe
+
+ concept_library.teardown()
+
+ def test_needed_inputs_with_mixed_pipe_and_fail(self, load_empty_library: Callable[[], None]):
+ """Test needed_inputs when some outcomes are pipes and some are FAIL."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create concepts
+ input_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Input",
+ blueprint_or_string_description=ConceptBlueprint(description="Input"),
+ )
+ output_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Output",
+ blueprint_or_string_description=ConceptBlueprint(description="Output"),
+ )
+ concept_library.add_concepts(concepts=[input_concept, output_concept])
+
+ # Create a pipe for one of the outcomes
+ pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="success_pipe",
+ blueprint=PipeLLMBlueprint(
+ description="Success pipe",
+ inputs={"data": input_concept.concept_ref},
+ output=output_concept.concept_ref,
+ prompt="Process: @data",
+ ),
+ concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_a)
+
+ # Create PipeCondition with mixed outcomes: one pipe, one FAIL
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with mixed pipe and FAIL",
+ inputs={"status": "native.Text"},
+ output=output_concept.concept_ref,
+ expression="status",
+ outcomes={
+ "success": "success_pipe", # Actual pipe
+ "error": SpecialOutcome.FAIL, # Special outcome
+ },
+ default_outcome=SpecialOutcome.FAIL,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Get needed inputs
+ needed_inputs = pipe_condition.needed_inputs()
+
+ # Should contain expression variable AND inputs from the actual pipe
+ assert "status" in needed_inputs.root # From expression
+ assert "data" in needed_inputs.root # From success_pipe
+
+ concept_library.teardown()
+
+ def test_validate_output_with_only_special_outcomes(self, load_empty_library: Callable[[], None]):
+ """Test that output validation passes when all outcomes are special (CONTINUE/FAIL)."""
+ load_empty_library()
+ domain_code = "test_domain"
+
+ # Create PipeCondition with only special outcomes
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with only special outcomes",
+ inputs={"flag": "native.Text"},
+ output="native.Text",
+ expression="flag",
+ outcomes={
+ "yes": SpecialOutcome.CONTINUE,
+ "no": SpecialOutcome.FAIL,
+ },
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # Should not raise - no actual pipes to validate against
+ pipe_condition.validate_output_with_library()
+
+ def test_mapped_pipe_codes_excludes_special_outcomes(self, load_empty_library: Callable[[], None]):
+ """Test that mapped_pipe_codes property excludes CONTINUE and FAIL."""
+ load_empty_library()
+ domain_code = "test_domain"
+ concept_library = get_concept_library()
+ pipe_library = get_pipe_library()
+
+ # Create a minimal pipe
+ output_concept = ConceptFactory.make_from_blueprint(
+ domain_code=domain_code,
+ concept_code="Output",
+ blueprint_or_string_description=ConceptBlueprint(description="Output"),
+ )
+ concept_library.add_concepts(concepts=[output_concept])
+
+ pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="real_pipe",
+ blueprint=PipeLLMBlueprint(
+ description="Real pipe",
+ inputs={},
+ output=output_concept.concept_ref,
+ prompt="Do something",
+ ),
+ concept_codes_from_the_same_domain=[output_concept.code],
+ )
+ pipe_library.add_new_pipe(pipe=pipe_a)
+
+ # Create PipeCondition with mix of real pipe and special outcomes
+ pipe_condition_blueprint = PipeConditionBlueprint(
+ description="Condition with mixed outcomes",
+ inputs={"mode": "native.Text"},
+ output=output_concept.concept_ref,
+ expression="mode",
+ outcomes={
+ "run": "real_pipe",
+ "skip": SpecialOutcome.CONTINUE,
+ "abort": SpecialOutcome.FAIL,
+ },
+ default_outcome=SpecialOutcome.CONTINUE,
+ )
+
+ pipe_condition = PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code="test_condition",
+ blueprint=pipe_condition_blueprint,
+ )
+
+ # mapped_pipe_codes should only contain actual pipes, not special outcomes
+ assert pipe_condition.mapped_pipe_codes == {"real_pipe"}
+ assert SpecialOutcome.CONTINUE not in pipe_condition.mapped_pipe_codes
+ assert SpecialOutcome.FAIL not in pipe_condition.mapped_pipe_codes
+
+ concept_library.teardown()
diff --git a/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_blueprint.py b/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_blueprint.py
index 3ee38ce2e..3574cffac 100644
--- a/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_blueprint.py
+++ b/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_blueprint.py
@@ -8,78 +8,86 @@ from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
class TestPipeParallelBlueprint:
def test_pipe_dependencies_correct(self):
blueprint = PipeParallelBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
parallels=[
SubPipeBlueprint(pipe="process_a", result="result_a"),
SubPipeBlueprint(pipe="process_b", result="result_b"),
],
add_each_output=True,
- inputs={"data": "Text"},
- output="Text",
)
assert blueprint.pipe_dependencies == {"process_a", "process_b"}
blueprint = PipeParallelBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
parallels=[
SubPipeBlueprint(pipe="step1", result="result1"),
SubPipeBlueprint(pipe="step2", result="result2"),
SubPipeBlueprint(pipe="step3", result="result3"),
],
add_each_output=True,
- inputs={"data": "Text"},
- output="Text",
)
assert blueprint.pipe_dependencies == {"step1", "step2", "step3"}
def test_validate_combined_output_correct(self):
blueprint = PipeParallelBlueprint(
- parallels=[SubPipeBlueprint(pipe="process", result="result")],
- combined_output="Text",
+ description="lorem ipsum",
inputs={"data": "Text"},
output="Text",
+ parallels=[SubPipeBlueprint(pipe="process", result="result")],
+ combined_output="Text",
)
assert blueprint.combined_output == "Text"
blueprint = PipeParallelBlueprint(
- parallels=[SubPipeBlueprint(pipe="process", result="result")],
- combined_output="Number",
+ description="lorem ipsum",
inputs={"data": "Text"},
output="Text",
+ parallels=[SubPipeBlueprint(pipe="process", result="result")],
+ combined_output="Number",
)
assert blueprint.combined_output == "Number"
def test_validate_combined_output_incorrect(self):
with pytest.raises(ValidationError) as exc_info:
PipeParallelBlueprint(
- parallels=[SubPipeBlueprint(pipe="process", result="result")],
- combined_output="InvalidConcept!",
+ description="lorem ipsum",
inputs={"data": "Text"},
output="Text",
+ parallels=[SubPipeBlueprint(pipe="process", result="result")],
+ combined_output="InvalidConcept!",
)
assert "Combined output 'InvalidConcept!' is not a valid concept string or code" in str(exc_info.value)
def test_validate_output_options_correct(self):
blueprint = PipeParallelBlueprint(
- parallels=[SubPipeBlueprint(pipe="process", result="result")],
- add_each_output=True,
+ description="lorem ipsum",
inputs={"data": "Text"},
output="Text",
+ parallels=[SubPipeBlueprint(pipe="process", result="result")],
+ add_each_output=True,
)
assert blueprint.add_each_output is True
blueprint = PipeParallelBlueprint(
- parallels=[SubPipeBlueprint(pipe="process", result="result")],
- combined_output="Text",
+ description="lorem ipsum",
inputs={"data": "Text"},
output="Text",
+ parallels=[SubPipeBlueprint(pipe="process", result="result")],
+ combined_output="Text",
)
assert blueprint.combined_output == "Text"
blueprint = PipeParallelBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
parallels=[SubPipeBlueprint(pipe="process", result="result")],
add_each_output=True,
combined_output="Text",
- inputs={"data": "Text"},
- output="Text",
)
assert blueprint.add_each_output is True
assert blueprint.combined_output == "Text"
@@ -87,10 +95,11 @@ class TestPipeParallelBlueprint:
def test_validate_output_options_incorrect(self):
with pytest.raises(ValidationError) as exc_info:
PipeParallelBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
parallels=[SubPipeBlueprint(pipe="process", result="result")],
add_each_output=False,
combined_output=None,
- inputs={"data": "Text"},
- output="Text",
)
assert "PipeParallel requires either add_each_output to be True or combined_output to be set" in str(exc_info.value)
diff --git a/tests/unit/pipelex/pipe_controllers/sequence/test_pipe_sequence_blueprint.py b/tests/unit/pipelex/pipe_controllers/sequence/test_pipe_sequence_blueprint.py
index c67287855..fa9ddeb32 100644
--- a/tests/unit/pipelex/pipe_controllers/sequence/test_pipe_sequence_blueprint.py
+++ b/tests/unit/pipelex/pipe_controllers/sequence/test_pipe_sequence_blueprint.py
@@ -8,71 +8,78 @@ from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
class TestPipeSequenceBlueprint:
def test_pipe_dependencies_correct(self):
blueprint = PipeSequenceBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
steps=[
SubPipeBlueprint(pipe="step1", result="result1"),
SubPipeBlueprint(pipe="step2", result="result2"),
],
- inputs={"data": "Text"},
- output="Text",
)
assert blueprint.pipe_dependencies == {"step1", "step2"}
blueprint = PipeSequenceBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
steps=[
SubPipeBlueprint(pipe="process_a", result="result_a"),
SubPipeBlueprint(pipe="process_b", result="result_b"),
SubPipeBlueprint(pipe="process_c", result="result_c"),
],
- inputs={"data": "Text"},
- output="Text",
)
assert blueprint.pipe_dependencies == {"process_a", "process_b", "process_c"}
def test_ordered_pipe_dependencies_correct(self):
blueprint = PipeSequenceBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
steps=[
SubPipeBlueprint(pipe="step1", result="result1"),
SubPipeBlueprint(pipe="step2", result="result2"),
SubPipeBlueprint(pipe="step3", result="result3"),
],
- inputs={"data": "Text"},
- output="Text",
)
assert blueprint.ordered_pipe_dependencies == ["step1", "step2", "step3"]
blueprint = PipeSequenceBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
steps=[
SubPipeBlueprint(pipe="first", result="first_result"),
SubPipeBlueprint(pipe="second", result="second_result"),
],
- inputs={"data": "Text"},
- output="Text",
)
assert blueprint.ordered_pipe_dependencies == ["first", "second"]
def test_validate_steps_correct(self):
blueprint = PipeSequenceBlueprint(
- steps=[SubPipeBlueprint(pipe="step1", result="result1")],
+ description="lorem ipsum",
inputs={"data": "Text"},
output="Text",
+ steps=[SubPipeBlueprint(pipe="step1", result="result1")],
)
assert len(blueprint.steps) == 1
blueprint = PipeSequenceBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "Text"},
+ output="Text",
steps=[
SubPipeBlueprint(pipe="step1", result="result1"),
SubPipeBlueprint(pipe="step2", result="result2"),
],
- inputs={"data": "Text"},
- output="Text",
)
assert len(blueprint.steps) == 2
def test_validate_steps_incorrect(self):
with pytest.raises(ValidationError) as exc_info:
PipeSequenceBlueprint(
- steps=[],
+ description="lorem ipsum",
inputs={"data": "Text"},
output="Text",
+ steps=[],
)
assert "PipeSequence must have at least 1 step" in str(exc_info.value)
diff --git a/tests/unit/pipelex/pipe_operators/pipe_extract/test_pipe_extract_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_extract/test_pipe_extract_blueprint.py
index 3b6d8e0c7..780fddd44 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_extract/test_pipe_extract_blueprint.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_extract/test_pipe_extract_blueprint.py
@@ -7,12 +7,14 @@ from pipelex.pipe_operators.extract.pipe_extract_blueprint import PipeExtractBlu
class TestPipeExtractBlueprint:
def test_force_output_correct(self):
blueprint = PipeExtractBlueprint(
+ description="lorem ipsum",
inputs={"document": "PDF"},
output="Page[]",
)
assert blueprint.output == "Page[]"
blueprint = PipeExtractBlueprint(
+ description="lorem ipsum",
inputs={"image": "Image"},
output="Page[]",
)
@@ -20,6 +22,7 @@ class TestPipeExtractBlueprint:
def test_validate_inputs_correct(self):
blueprint = PipeExtractBlueprint(
+ description="lorem ipsum",
inputs={"document": "PDF"},
output="Page[]",
)
@@ -27,6 +30,7 @@ class TestPipeExtractBlueprint:
assert blueprint.input_names == ["document"]
blueprint = PipeExtractBlueprint(
+ description="lorem ipsum",
inputs={"image": "Image"},
output="Page[]",
)
@@ -36,6 +40,7 @@ class TestPipeExtractBlueprint:
def test_validate_inputs_incorrect(self):
with pytest.raises(ValidationError) as exc_info:
PipeExtractBlueprint(
+ description="lorem ipsum",
inputs={},
output="Page[]",
)
@@ -43,6 +48,7 @@ class TestPipeExtractBlueprint:
with pytest.raises(ValidationError) as exc_info:
PipeExtractBlueprint(
+ description="lorem ipsum",
inputs={"doc1": "PDF", "doc2": "PDF"},
output="Page[]",
)
@@ -50,6 +56,7 @@ class TestPipeExtractBlueprint:
def test_validate_output_correct(self):
blueprint = PipeExtractBlueprint(
+ description="lorem ipsum",
inputs={"document": "PDF"},
output="Page[]",
)
@@ -57,6 +64,7 @@ class TestPipeExtractBlueprint:
def test_validate_output_incorrect(self):
blueprint = PipeExtractBlueprint(
+ description="lorem ipsum",
inputs={"document": "PDF"},
output="Page[]",
)
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.py
index 2aba0e78c..5e1f5b680 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
@@ -7,6 +7,7 @@ from pipelex.pipe_operators.img_gen.pipe_img_gen_blueprint import PipeImgGenBlue
class TestPipeImgGenBlueprint:
def test_validate_inputs_correct(self):
blueprint = PipeImgGenBlueprint(
+ description="lorem ipsum",
inputs=None,
output="Image",
prompt="A beautiful sunset",
@@ -15,6 +16,7 @@ class TestPipeImgGenBlueprint:
assert blueprint.prompt == "A beautiful sunset"
blueprint = PipeImgGenBlueprint(
+ description="lorem ipsum",
inputs={"topic": "Text"},
output="Image",
prompt="Sketch black and white illustration of: $topic",
@@ -25,6 +27,7 @@ class TestPipeImgGenBlueprint:
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",
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.py
index fee37780f..dcc7c1869 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
@@ -8,6 +8,7 @@ class TestPipeLLMBlueprint:
def test_validate_inputs_correct_with_prompt_variables(self):
"""Test that prompt variables matching inputs are valid."""
blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
inputs={"input_one": "native.Text", "input_two": "native.Text"},
output="native.Text",
prompt="Process @input_one and @input_two",
@@ -18,6 +19,7 @@ class TestPipeLLMBlueprint:
def test_validate_inputs_correct_with_system_prompt_variables(self):
"""Test that system_prompt variables matching inputs are valid."""
blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
inputs={"context": "native.Text"},
output="native.Text",
system_prompt="Use this context: @context",
@@ -29,6 +31,7 @@ class TestPipeLLMBlueprint:
def test_validate_inputs_correct_with_both_prompts(self):
"""Test that variables in both prompt and system_prompt are validated."""
blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
inputs={"context": "native.Text", "query": "native.Text"},
output="native.Text",
system_prompt="Context: @context",
@@ -40,6 +43,7 @@ class TestPipeLLMBlueprint:
def test_validate_inputs_correct_no_variables(self):
"""Test that prompts without variables work fine."""
blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
inputs=None,
output="native.Text",
prompt="Generate a random story",
@@ -49,6 +53,7 @@ class TestPipeLLMBlueprint:
def test_validate_inputs_correct_with_inline_variables(self):
"""Test that inline variables ($variable) are also validated."""
blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
inputs={"topic": "native.Text", "style": "native.Text"},
output="native.Text",
prompt="Write about $topic in $style style",
@@ -60,12 +65,13 @@ class TestPipeLLMBlueprint:
"""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 prompt template" in error_msg
+ assert "Missing input variable(s):" in error_msg
assert "input_three" in error_msg
assert "not declared in inputs" in error_msg
@@ -73,12 +79,13 @@ class TestPipeLLMBlueprint:
"""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 prompt template" in error_msg
+ assert "Missing input variable(s):" in error_msg
assert "input_two" in error_msg
assert "input_three" in error_msg
@@ -86,29 +93,32 @@ class TestPipeLLMBlueprint:
"""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 prompt template" in error_msg
+ assert "Missing input variable(s):" in error_msg
assert "context" in error_msg
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 prompt template" in error_msg or "data" in error_msg
+ assert "Missing input variable(s):" in error_msg or "data" in error_msg
def test_validate_inputs_ignores_internal_variables(self):
"""Test that internal variables (starting with _) are ignored."""
blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
inputs=None,
output="native.Text",
prompt="Use internal variable @_internal_var",
@@ -119,6 +129,7 @@ class TestPipeLLMBlueprint:
def test_validate_inputs_ignores_special_variables(self):
"""Test that special variables like preliminary_text are ignored."""
blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
inputs=None,
output="native.Text",
prompt="Use @preliminary_text and @place_holder",
diff --git a/tests/unit/pipelex/tools/misc/test_string_utils.py b/tests/unit/pipelex/tools/misc/test_string_utils.py
index 466960e07..37c672a5b 100644
--- a/tests/unit/pipelex/tools/misc/test_string_utils.py
+++ b/tests/unit/pipelex/tools/misc/test_string_utils.py
@@ -3,6 +3,7 @@ import pytest
from pipelex.tools.misc.string_utils import (
camel_to_snake_case,
can_inject_text,
+ get_root_from_dotted_path,
is_none_or_has_text,
is_not_none_and_has_text,
is_pascal_case,
@@ -199,6 +200,32 @@ def test_is_pascal_case(word: str, expected: bool) -> None:
assert is_pascal_case(word) is expected
+ ("dotted_path", "expected"),
+ [
+ # Paths with multiple dots
+ ("foo.bar.baz", "foo"),
+ ("object.attribute.sub", "object"),
+ ("a.b.c.d.e", "a"),
+ # Paths with single dot
+ ("foo.bar", "foo"),
+ ("domain.ConceptCode", "domain"),
+ # Paths without dots (returns unchanged)
+ ("foo", "foo"),
+ ("single", "single"),
+ # Edge cases
+ ("", ""),
+ (".leading", ""),
+ ("trailing.", "trailing"),
+ ("..", ""),
+ ("a.", "a"),
+ (".b", ""),
+ ],
+)
+def test_get_root_from_dotted_path(dotted_path: str, expected: str) -> None:
+ assert get_root_from_dotted_path(dotted_path) == expected
+
+
@pytest.mark.parametrize(
("text", "expected"),
[
diff --git a/tests/unit/pipelex/tools/test_jinja2_required_variables.py b/tests/unit/pipelex/tools/test_jinja2_required_variables.py
new file mode 100644
index 000000000..7050c96b7
--- /dev/null
+++ b/tests/unit/pipelex/tools/test_jinja2_required_variables.py
@@ -0,0 +1,542 @@
+from typing import ClassVar
+
+import pytest
+
+from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.tools.jinja2.jinja2_errors import Jinja2DetectVariablesError
+from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
+
+
+class TestData:
+ """Test data for detect_jinja2_required_variables tests.
+
+ Note: The function returns ONLY the leaf (full) paths, not intermediate paths.
+ For example, `{{ foo.bar.baz }}` returns `{"foo.bar.baz"}`, NOT `{"foo", "foo.bar", "foo.bar.baz"}`.
+ """
+
+ # (topic, template_source, expected_variables)
+ SIMPLE_VARIABLES: ClassVar[list[tuple[str, str, set[str]]]] = [
+ ("single_variable", "Hello {{ name }}", {"name"}),
+ ("two_variables", "{{ first }} and {{ second }}", {"first", "second"}),
+ ("variable_in_sentence", "The value is {{ value }} today", {"value"}),
+ ("variable_with_spaces", "{{ spaced }}", {"spaced"}),
+ ("empty_template", "No variables here", set()),
+ ("just_text", "Plain text without any jinja", set()),
+ ]
+
+ MULTIPLE_VARIABLES: ClassVar[list[tuple[str, str, set[str]]]] = [
+ (
+ "three_variables",
+ "Name: {{ name }}, Age: {{ age }}, City: {{ city }}",
+ {"name", "age", "city"},
+ ),
+ (
+ "five_variables_multiline",
+ """
+ Name: {{ name }}
+ Age: {{ age }}
+ Email: {{ email }}
+ Phone: {{ phone }}
+ Address: {{ address }}
+ """,
+ {"name", "age", "email", "phone", "address"},
+ ),
+ (
+ "repeated_variable",
+ "{{ var }} is the same as {{ var }}",
+ {"var"}, # Should detect only once
+ ),
+ ]
+
+ NESTED_VARIABLES: ClassVar[list[tuple[str, str, set[str]]]] = [
+ # Full paths are returned
+ ("simple_dot_notation", "{{ user.name }}", {"user.name"}),
+ ("deep_nesting", "{{ user.profile.bio.short }}", {"user.profile.bio.short"}),
+ (
+ "multiple_nested",
+ "{{ user.name }} and {{ config.setting }}",
+ {"user.name", "config.setting"},
+ ),
+ (
+ "mix_nested_and_simple",
+ "Hello {{ name }}, your email is {{ user.email }}",
+ {"name", "user.email"},
+ ),
+ ]
+
+ VARIABLES_WITH_FILTERS: ClassVar[list[tuple[str, str, set[str]]]] = [
+ ("single_filter", '{{ name|tag("name") }}', {"name"}),
+ ("format_filter", "{{ amount|format() }}", {"amount"}),
+ ("chained_filters", "{{ value|lower|upper }}", {"value"}),
+ (
+ "filter_with_argument",
+ "{{ text|truncate(50) }}",
+ {"text"},
+ ),
+ (
+ "multiple_vars_with_filters",
+ '{{ first|tag("first") }} and {{ second|format() }}',
+ {"first", "second"},
+ ),
+ (
+ "nested_with_filter",
+ '{{ user.name|tag("user.name") }}',
+ {"user.name"},
+ ),
+ ]
+
+ CONTROL_STRUCTURES: ClassVar[list[tuple[str, str, set[str]]]] = [
+ (
+ "if_statement",
+ "{% if show_name %}{{ name }}{% endif %}",
+ {"show_name", "name"},
+ ),
+ (
+ "if_else_statement",
+ "{% if condition %}{{ yes_value }}{% else %}{{ no_value }}{% endif %}",
+ {"condition", "yes_value", "no_value"},
+ ),
+ (
+ "for_loop",
+ "{% for item in items %}{{ item }}{% endfor %}",
+ {"items"}, # 'item' is defined within the loop
+ ),
+ (
+ "for_loop_with_extra_var",
+ "{% for item in items %}{{ item }} ({{ prefix }}){% endfor %}",
+ {"items", "prefix"}, # 'item' is loop var, items and prefix are external
+ ),
+ (
+ "nested_for_loops",
+ "{% for row in rows %}{% for cell in row.cells %}{{ cell }}{% endfor %}{% endfor %}",
+ {"rows"},
+ ),
+ (
+ "for_loop_with_nested_external",
+ "{% for item in items %}{{ item.name }} ({{ prefix.value }}){% endfor %}",
+ {"items", "prefix.value"},
+ ),
+ ]
+
+ COMPLEX_REAL_WORLD: ClassVar[list[tuple[str, str, set[str]]]] = [
+ (
+ "gantt_chart_analysis",
+ """I am sharing an image of a Gantt chart: {{ gantt_chart_image|format() }}.
+Please analyse the image and for a given task name (and only this task), extract the information of the task, if relevant.
+
+Be careful, the time unit is this:
+{{ gantt_timescale|tag("gantt_timescale") }}
+
+If the task is a milestone, then only output the start_date.
+
+Here is the name of the task you have to extract the dates for:
+{{ gantt_task_name|tag("gantt_task_name") }}""",
+ {"gantt_chart_image", "gantt_timescale", "gantt_task_name"},
+ ),
+ (
+ "invoice_extraction",
+ """Extract employee information from this invoice text: {{ invoice_text|tag("invoice_text") }}.
+
+The company details are:
+{{ company_info|format() }}
+
+Please extract the following fields:
+- Employee name
+- Employee ID
+- Department""",
+ {"invoice_text", "company_info"},
+ ),
+ (
+ "email_template",
+ """Dear {{ recipient.name }},
+
+{% if greeting %}{{ greeting }}{% else %}Hello{% endif %}
+
+We are writing to inform you about {{ topic }}.
+
+{% for item in action_items %}
+- {{ item }}
+{% endfor %}
+
+Best regards,
+{{ sender.name }}
+{{ sender.title }}""",
+ {"recipient.name", "greeting", "topic", "action_items", "sender.name", "sender.title"},
+ ),
+ ]
+
+ OPTIONAL_VARIABLES: ClassVar[list[tuple[str, str, set[str]]]] = [
+ (
+ "optional_with_if",
+ '{% if optional_field %}{{ optional_field|tag("optional_field") }}{% endif %}',
+ {"optional_field"},
+ ),
+ (
+ "optional_nested",
+ '{% if user.bio %}{{ user.bio|tag("user.bio") }}{% endif %}',
+ {"user.bio"},
+ ),
+ ]
+
+ PLX_STYLE_TEMPLATES: ClassVar[list[tuple[str, str, set[str]]]] = [
+ (
+ "plx_at_variable_preprocessed",
+ '{{ page.page_view|tag("page.page_view") }}',
+ {"page.page_view"},
+ ),
+ (
+ "plx_dollar_variable_preprocessed",
+ "{{ page.text_and_images.text.text|format() }}",
+ {"page.text_and_images.text.text"},
+ ),
+ (
+ "plx_mixed_preprocessed",
+ '{{ page.page_view|tag("page.page_view") }}\n{{ page.text_and_images.text.text|format() }}',
+ {"page.page_view", "page.text_and_images.text.text"},
+ ),
+ ]
+
+ TEMPLATE_CATEGORIES: ClassVar[list[TemplateCategory]] = [
+ TemplateCategory.BASIC,
+ TemplateCategory.LLM_PROMPT,
+ TemplateCategory.HTML,
+ TemplateCategory.MARKDOWN,
+ TemplateCategory.EXPRESSION,
+ TemplateCategory.IMG_GEN_PROMPT,
+ TemplateCategory.MERMAID,
+ ]
+
+ # Error test cases
+ SYNTAX_ERRORS: ClassVar[list[tuple[str, str]]] = [
+ ("unclosed_brace", "{{ unclosed"),
+ ("unclosed_block", "{% if condition %}missing endif"),
+ ("invalid_filter_syntax", "{{ value|filter( }}"),
+ ("unmatched_endif", "{% endif %}"),
+ ("broken_for_loop", "{% for item in %}{{ item }}{% endfor %}"),
+ ]
+
+
+class TestDetectJinja2Variables:
+ """Tests for detect_jinja2_required_variables function."""
+
+ @pytest.mark.parametrize(
+ ("topic", "template_source", "expected_variables"),
+ TestData.SIMPLE_VARIABLES,
+ )
+ def test_simple_variables(
+ self,
+ topic: str,
+ template_source: str,
+ expected_variables: set[str],
+ ):
+ """Test detection of simple single and double variable templates."""
+ 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.MULTIPLE_VARIABLES,
+ )
+ def test_multiple_variables(
+ self,
+ topic: str,
+ template_source: str,
+ expected_variables: set[str],
+ ):
+ """Test detection of multiple variables in templates."""
+ 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.NESTED_VARIABLES,
+ )
+ def test_nested_variables(
+ self,
+ topic: str,
+ template_source: str,
+ expected_variables: set[str],
+ ):
+ """Test detection of nested/dotted variables returns full paths."""
+ 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.VARIABLES_WITH_FILTERS,
+ )
+ def test_variables_with_filters(
+ self,
+ topic: str,
+ template_source: str,
+ expected_variables: set[str],
+ ):
+ """Test detection of variables used with Jinja2 filters."""
+ 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.CONTROL_STRUCTURES,
+ )
+ def test_control_structures(
+ self,
+ topic: str,
+ template_source: str,
+ expected_variables: set[str],
+ ):
+ """Test detection of variables in control structures (if, for, etc.)."""
+ 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.COMPLEX_REAL_WORLD,
+ )
+ def test_complex_real_world_templates(
+ self,
+ topic: str,
+ template_source: str,
+ expected_variables: set[str],
+ ):
+ """Test detection in complex real-world template scenarios."""
+ 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.OPTIONAL_VARIABLES,
+ )
+ def test_optional_variables(
+ self,
+ topic: str,
+ template_source: str,
+ expected_variables: set[str],
+ ):
+ """Test detection of optional variables wrapped in if statements."""
+ 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_paths"),
+ TestData.PLX_STYLE_TEMPLATES,
+ )
+ def test_plx_style_templates(
+ self,
+ topic: str,
+ template_source: str,
+ expected_paths: set[str],
+ ):
+ """Test detection in PLX-style preprocessed templates with tag/format filters."""
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == expected_paths, f"Failed for topic: {topic}"
+
+ @pytest.mark.parametrize("template_category", TestData.TEMPLATE_CATEGORIES)
+ def test_different_template_categories(
+ self,
+ template_category: TemplateCategory,
+ ):
+ """Test that variable detection works across all template categories."""
+ template_source = "Hello {{ name }}, welcome to {{ place }}"
+ expected = {"name", "place"}
+
+ result = detect_jinja2_required_variables(
+ template_category=template_category,
+ template_source=template_source,
+ )
+ assert result == expected, f"Failed for category: {template_category}"
+
+ def test_empty_template(self):
+ """Test that empty template returns empty set."""
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source="",
+ )
+ assert result == set()
+
+ def test_whitespace_only_template(self):
+ """Test that whitespace-only template returns empty set."""
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=" \n\t\n ",
+ )
+ assert result == set()
+
+ @pytest.mark.parametrize(
+ ("topic", "template_source"),
+ TestData.SYNTAX_ERRORS,
+ )
+ def test_syntax_errors_raise_exception(
+ self,
+ topic: str, # noqa: ARG002
+ template_source: str,
+ ):
+ """Test that invalid templates raise Jinja2DetectVariablesError."""
+ with pytest.raises(Jinja2DetectVariablesError):
+ detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+
+ def test_set_with_variable(self):
+ """Test that set statements don't add their target to required variables."""
+ template_source = """
+ {% set computed = base_value * 2 %}
+ Result: {{ computed }} from {{ base_value }}
+ """
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ # 'computed' is defined in the template, only base_value is required
+ assert result == {"base_value"}
+
+ def test_macro_variables(self):
+ """Test variables inside macro definitions."""
+ template_source = """
+ {% macro render_item(item) %}
+ <div>{{ item.name }}</div>
+ {% endmacro %}
+ {{ render_item(my_item) }}
+ {{ external_var }}
+ """
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ # my_item and external_var are required; item is macro parameter
+ assert result == {"my_item", "external_var"}
+
+ def test_variables_with_default_filter(self):
+ """Test variables with default filter."""
+ template_source = '{{ name|default("Anonymous") }} - {{ age|default(0) }}'
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"name", "age"}
+
+ def test_complex_expressions(self):
+ """Test variables in complex expressions."""
+ template_source = """
+ {% if items|length > 0 and show_items %}
+ {% for item in items %}
+ {{ item.name }}: {{ item.price * quantity }}
+ {% endfor %}
+ {% endif %}
+ """
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"items", "show_items", "quantity"}
+
+ def test_arithmetic_operations(self):
+ """Test variables in arithmetic operations."""
+ template_source = "Total: {{ price * quantity + tax - discount }}"
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"price", "quantity", "tax", "discount"}
+
+ def test_comparison_operations(self):
+ """Test variables in comparison operations."""
+ template_source = "{% if age >= min_age and age <= max_age %}Valid{% endif %}"
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"age", "min_age", "max_age"}
+
+ def test_string_concatenation(self):
+ """Test variables in string concatenation."""
+ template_source = "{{ first_name ~ ' ' ~ last_name }}"
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"first_name", "last_name"}
+
+ def test_list_and_dict_access(self):
+ """Test variables with subscript access."""
+ template_source = "{{ items[0] }} and {{ data['key'] }}"
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"items", "data"}
+
+ def test_ternary_expression(self):
+ """Test variables in ternary expressions."""
+ template_source = "{{ active_value if is_active else inactive_value }}"
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"active_value", "is_active", "inactive_value"}
+
+ def test_loop_special_variables_not_required(self):
+ """Test that loop special variables (loop.index, etc.) are not required."""
+ template_source = """
+ {% for item in items %}
+ {{ loop.index }}: {{ item }}
+ {% endfor %}
+ """
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"items"}
+
+ def test_unicode_variable_names(self):
+ """Test detection with variable names containing unicode."""
+ template_source = "{{ nom_français }} and {{ 日本語 }}"
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"nom_français", "日本語"}
+
+ def test_underscore_variable_names(self):
+ """Test detection with underscore-prefixed and suffixed variables."""
+ template_source = "{{ _private }} and {{ __dunder__ }} and {{ normal_var }}"
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"_private", "__dunder__", "normal_var"}
+
+ def test_full_paths_are_returned(self):
+ """Test that full dotted paths are returned."""
+ template_source = "{{ user.profile.name }} and {{ config.value }}"
+
+ result = detect_jinja2_required_variables(
+ template_category=TemplateCategory.LLM_PROMPT,
+ template_source=template_source,
+ )
+ assert result == {"user.profile.name", "config.value"}