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.

feature/Unsandboxed-jinja-hosted-templates · L-260928-baec1e (#1297)

Louis Choquel9cb112a03afe
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3cf828f18..83ce3e114 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,14 @@
### Fixed
- **A generated object's storage key names its own format**: the extension of a key under `generated/` follows the whole MIME type the object is stored under, so a fetched `image/svg+xml` is stored as `.svg`, and a type with no extension of its own gets `.bin`, where both used to get `.jpg`. The MIME type's parameters and case no longer change the extension.
+- **An include in a method template is a render error**: `{% include %}`, `{% extends %}` and `{% import %}` in a template rendered without a loader raise `Jinja2TemplateRenderError`, where they leaked Jinja's own `TemplateNotFound`.
+- **A template reads a `Composite`'s parts by name**: `{{ combo.summary }}`, `{{ combo['summary'] }}` and `combo.get('summary')` resolve the named parts of a `Composite` output, and `iter_keys` lists them; they used to render empty, and only the raw `_content`, now refused, reached them. Like any private name, a part whose name starts with an underscore is refused when a template reads it on an input.
+- **A template's arithmetic error is a render error**: a division by zero, or a `range` longer than the sandbox's cap, raises `Jinja2TemplateRenderError` where the raw Python exception escaped, which validation reported as an internal error rather than as the method's.
+
+### Security
+
+- **Every template renders in a sandbox (Breaking)**: prompts, compose and construct templates, image and search prompts and condition expressions may read data and call methods of plain values (strings, numbers, dates, containers) only, so a template that reaches for a Python internal, calls a method of a Pipelex or pydantic object, or reads a name starting with an underscore other than an input's `_stuff_name`, `_content_class`, `_concept_code` and `_stuff_code` raises `Jinja2TemplateSecurityError` instead of rendering, and validation refuses the visible cases with the new `template_private_name` error. `_content` and the `stuff` property are no longer readable on an input, and bracket access and `get` on an input resolve only its content fields and metadata fields; a plain dict's keys stay readable with brackets, `record['_id']` included, and a `namespace()` holds data only, refusing a callable. The `jinja2` floor rises to 3.1.6, the release carrying Jinja's own sandbox fix for the `attr` filter.
+- **Dotted paths refuse underscore segments**: a PipeCompose construct `from` path such as `note.__class__.__init__.__globals__.sys.modules.os.environ` walked into Python internals with plain `getattr` and could copy the process environment into a method's output. A `from` path or `list_to_dict_keyed_by` name with a segment starting with an underscore is now refused at validation, and every dotted path the runtime walks, batch lists and prompt image references included, refuses one.
### Security
diff --git a/docs/building-methods/pipes/pipe-controllers/PipeParallel.md b/docs/building-methods/pipes/pipe-controllers/PipeParallel.md
index 380f6cf4c..9e660252d 100644
--- a/docs/building-methods/pipes/pipe-controllers/PipeParallel.md
+++ b/docs/building-methods/pipes/pipe-controllers/PipeParallel.md
@@ -122,7 +122,7 @@ How this works:
5. A new structured object of type `ProductAnalysis` is created and populated with the results, like `{"features": ..., "sentiment": ...}`. This object becomes the main output of the `analyze_product_in_parallel` pipe.
6. Because `add_each_output` is `true`, `features` and `sentiment` are also available individually in the working memory for downstream pipes.
-If you don't want to declare a `ProductAnalysis` concept, set `output = "Composite"` instead: the combined object then holds the same `{"features": ..., "sentiment": ...}` shape as an untyped composition.
+If you don't want to declare a `ProductAnalysis` concept, set `output = "Composite"` instead: the combined object then holds the same `{"features": ..., "sentiment": ...}` shape as an untyped composition. A later template reads each part by name, as it would read a field: `{{ analysis.features }}`.
## Related Documentation
diff --git a/docs/building-methods/pipes/pipe-operators/PipeCompose.md b/docs/building-methods/pipes/pipe-operators/PipeCompose.md
index 8a6912810..b1ce69757 100644
--- a/docs/building-methods/pipes/pipe-operators/PipeCompose.md
+++ b/docs/building-methods/pipes/pipe-operators/PipeCompose.md
@@ -28,6 +28,8 @@ Template mode supports two syntax variants:
The Jinja2 template has access to all the "stuffs" currently in the working memory. You can access them by the names they were given in previous pipeline steps. For example, if a previous step produced an output named `user_profile`, you can access its attributes in the template like `{{ user_profile.name }}` or `{{ user_profile.email }}`.
+A template reads data and calls methods of plain values, and nothing else: it can read fields, call `isoformat()` on a date or `upper()` on a string, and apply any filter, but it cannot call methods of Pipelex objects or read names starting with an underscore, other than an input's metadata fields such as `_stuff_name`. This applies to every template a method contains, PipeLLM prompts and PipeCondition expressions included. The [Template Sandbox](../../../under-the-hood/template-sandbox.md) page lists what is allowed and how a refusal is reported.
+
### Template Mode Configuration
| Parameter | Type | Description | Required |
@@ -156,6 +158,8 @@ products_by_sku = { from = "products", list_to_dict_keyed_by = "sku" }
The referenced value must be a list, and every item must carry the key attribute with a string value — otherwise the composer raises an error.
+A `from` path and a `list_to_dict_keyed_by` name read public fields only: validation refuses a segment starting with an underscore, such as `{ from = "order._stuff" }`, for the reason the [Template Sandbox](../../../under-the-hood/template-sandbox.md) gives.
+
### Copying Whole Inputs Into Native Fields
The `from` reference is not limited to dotted paths like `"customer.name"` — it can name a whole input variable. When the referenced input is a native stuff (`Text`, `Number`, `YesNo`, `Date`, `Time`, or a list of them) and the target field is native-typed, the composer automatically converts the content wrapper into the field's native value. This works for required and optional fields alike.
diff --git a/docs/errors/jinja2-template-security-error.md b/docs/errors/jinja2-template-security-error.md
new file mode 100644
index 000000000..0f80b0d9d
--- /dev/null
+++ b/docs/errors/jinja2-template-security-error.md
@@ -0,0 +1,19 @@
+---
+title: "Jinja 2 template security"
+description: "Reference for the `Jinja2TemplateSecurityError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Jinja 2 template security
+
+| Field | Value |
+|---|---|
+| `error_type` | `Jinja2TemplateSecurityError` |
+| `title` | Jinja 2 template security |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-template-security-error/` |
+| `error_domain` | _(inherited from parent)_ |
+| Defined in | `pipelex.tools.jinja2.exceptions` |
+| Parent class | [`ToolError`](tool-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.md
index 48249220d..38dff034a 100644
--- a/docs/errors/platform-and-tooling.md
+++ b/docs/errors/platform-and-tooling.md
@@ -34,6 +34,7 @@ own page. Classes are grouped by subsystem.
- [`Jinja2DetectVariablesError`](jinja2-detect-variables-error.md) — Jinja 2 detect variables
- [`Jinja2StuffError`](jinja2-stuff-error.md) — Jinja 2 stuff
- [`Jinja2TemplateRenderError`](jinja2-template-render-error.md) — Jinja 2 template render
+- [`Jinja2TemplateSecurityError`](jinja2-template-security-error.md) — Jinja 2 template security
- [`Jinja2TemplateSyntaxError`](jinja2-template-syntax-error.md) — Jinja 2 template syntax
- [`JsonTypeError`](json-type-error.md) — Json type
- [`ModuleFileError`](module-file-error.md) — Module file
diff --git a/docs/under-the-hood/index.md b/docs/under-the-hood/index.md
index 74c130e9c..4fd946dbd 100644
--- a/docs/under-the-hood/index.md
+++ b/docs/under-the-hood/index.md
@@ -17,6 +17,7 @@ Welcome to the technical deep-dives of Pipelex. This section is for contributors
- **Reasoning Controls** - How reasoning effort/budget flows to each provider's SDK
- **Error Model** - How errors are classified, carried across every layer, and reported to humans, agents, and HTTP APIs
- **StuffArtefact & Image Rendering** - How template access and image extraction work
+- **Template Sandbox** - What a method's templates may read and call, and how everything else is refused
- **Test Profile Configuration** - How to configure which models are used in tests
- **Dry Run Mock Generation** - How mock objects satisfy field validation constraints
- **Init CLI Flows** - How `pipelex init` sets up the configuration directory
@@ -42,6 +43,7 @@ Welcome to the technical deep-dives of Pipelex. This section is for contributors
- [:material-image-multiple: Image Handling in LLM Prompts](./image-handling-in-llm-prompts.md){ .md-button }
- [:material-brain: Reasoning Controls](./reasoning-controls.md){ .md-button }
- [:material-code-braces: StuffArtefact & Image Rendering](./stuffartefact-and-image-rendering.md){ .md-button }
+- [:material-shield-lock: Template Sandbox](./template-sandbox.md){ .md-button }
- [:material-test-tube: Test Profile Configuration](./test-profile-configuration.md){ .md-button }
- [:material-flask-outline: Dry Run Mock Generation](./dry-run-mock-generation.md){ .md-button }
- [:material-console: Init CLI Flows](./init-cli-flows.md){ .md-button }
diff --git a/docs/under-the-hood/stuffartefact-and-image-rendering.md b/docs/under-the-hood/stuffartefact-and-image-rendering.md
index 3e3569c82..ca6bab44e 100644
--- a/docs/under-the-hood/stuffartefact-and-image-rendering.md
+++ b/docs/under-the-hood/stuffartefact-and-image-rendering.md
@@ -23,7 +23,7 @@ StuffArtefact wraps Stuff → delegates to StuffContent → Protocol enables tra
```
!!! info "Protocol over Inheritance"
- ImageRenderable uses duck typing. Any class with a `render_with_images()` method satisfies the protocol—no base class required.
+ ImageRenderable uses duck typing. Any class that defines a `render_with_images()` method satisfies the protocol, with no base class required. The filters check the class rather than the instance, so a value that merely holds such a method as an attribute is never rendered through it.
---
@@ -33,12 +33,16 @@ StuffArtefact wraps Stuff → delegates to StuffContent → Protocol enables tra
|---------|--------|
| `{{ doc.title }}` | Content field value |
| `{{ doc.pages }}` | Nested content (list, struct, etc.) |
+| `{{ combo.summary }}` | A named part of a `Composite` output |
| `{{ doc._stuff_name }}` | Metadata: variable name |
| `{{ doc._content_class }}` | Metadata: content class name |
| `{{ doc._concept_code }}` | Metadata: concept code |
+| `{{ doc._stuff_code }}` | Metadata: stuff code |
| `{{ doc \| with_images }}` | Text with `[Image N]` tokens |
| `{{ doc \| tag }}` | Tagged output (no images) |
+These are the only underscore names a template may read on an input. Templates render under the [Template Sandbox](template-sandbox.md), which refuses every other private name. The wrapped `Stuff` is not an attribute of the artefact at all: Python code reaches it through `unwrap_stuff_artefact(artefact=...)`.
+
---
## Image Extraction Behavior
@@ -63,7 +67,7 @@ flowchart TB
subgraph FILTER["with_images Filter"]
direction TB
- CHECK["isinstance(value, ImageRenderable)?"]
+ CHECK["ImageRenderable, defined by its class?"]
CALL["value.render_with_images(registry=registry, text_format=text_format)"]
CHECK --> CALL
end
@@ -107,28 +111,16 @@ def __getattribute__(self, key: str) -> Any:
if key in _PASSTHROUGH_ATTRS or key.startswith("__"):
return object.__getattribute__(self, key)
- # 2. Content fields (highest priority for templates)
- content_fields = type(content).model_fields
- if key in content_fields:
- return getattr(content, key)
-
- # 3. Metadata accessors
- match key:
- case "_stuff_name":
- return stuff.stuff_name
- case "_content_class":
- return content.__class__.__name__
- case "_concept_code":
- return stuff.concept.code
- case "_stuff_code":
- return stuff.stuff_code
- case "_content":
- return content
-
- # 4. Fallback to normal lookup
- return object.__getattribute__(self, key)
+ # 2. Content fields, then 3. metadata fields (_stuff_name, _content_class, _concept_code, _stuff_code)
+ try:
+ return _get_template_value(stuff=stuff, key=key)
+ except KeyError:
+ # 4. Fallback to normal lookup
+ return object.__getattribute__(self, key)
```
+`_get_template_value` is the whole of what a string key resolves to: a content field (a declared field, or a public extra field such as a `Composite`'s named parts), else one of the four metadata fields, else `KeyError`.
+
!!! warning "Content Field Priority"
Content fields shadow StuffArtefact methods. If your content has a field named `items`, accessing `artefact.items` returns the field value, not the iteration method. Use `artefact.iter_items()` for explicit dict-like iteration.
@@ -138,13 +130,15 @@ StuffArtefact supports bracket notation and iteration:
| Method | Purpose |
|--------|---------|
-| `artefact["field"]` | Bracket access (via `__getitem__`) |
-| `artefact.get("field", default=...)` | Safe access with default |
+| `artefact["field"]` | Bracket access (via `__getitem__`): a content field or a metadata field only |
+| `artefact.get("field", default=...)` | Safe access with default, resolving the same keys as brackets |
| `"field" in artefact` | Membership test |
| `artefact.iter_keys()` | Iterate field names |
| `artefact.iter_items()` | Iterate (key, value) pairs |
| `artefact.iter_values()` | Iterate values |
+Bracket access and `get` never resolve to the artefact's own attributes, such as the wrapped `Stuff` or a method. The accessors above and the four metadata fields are what `StuffArtefact` declares as its template surface: the only methods a template may call on it and the only underscore names it may read.
+
---
## ImageRenderable Protocol
@@ -177,7 +171,7 @@ class ImageRenderable(Protocol):
- **Avoids circular imports**: `tools/jinja2/` can check types from `core/stuffs/` without importing them
- **Duck typing**: No inheritance required—any matching method signature works
-- **Runtime checking**: `isinstance(value, ImageRenderable)` works at runtime
+- **Runtime checking**: `isinstance(value, ImageRenderable)` works at runtime, and the filters add `type_implements(value=value, protocol=ImageRenderable)`, which reads the members from the class, since on Python 3.11 the `isinstance` check alone accepts an instance merely holding the method
---
@@ -288,11 +282,11 @@ def with_images(context: Context, value: Any, _: Any = None) -> str:
if registry is None:
registry = ImageRegistry()
- # 3. Get text format
- text_format = TextFormat(context.get(Jinja2ContextKey.TEXT_FORMAT, default=TextFormat.PLAIN))
+ # 3. Get text format: no fallback, a render without a templating style fails loudly
+ text_format = TextFormat(require_templating_style_value(context=context, jinja2_context_key=Jinja2ContextKey.TEXT_FORMAT))
- # 4. Protocol-based rendering
- if isinstance(value, ImageRenderable):
+ # 4. Protocol-based rendering, licensed by the value's class, never by an attribute the instance holds
+ if isinstance(value, ImageRenderable) and type_implements(value=value, protocol=ImageRenderable):
return value.render_with_images(registry=registry, text_format=text_format)
# 5. Handle plain sequences
@@ -322,6 +316,8 @@ def with_images(context: Context, value: Any, _: Any = None) -> str:
| `{{ x["field"] }}` | Bracket access |
| `{{ x._stuff_name }}` | Variable name metadata |
| `{{ x._content_class }}` | Content class name |
+| `{{ x._concept_code }}` | Concept code |
+| `{{ x._stuff_code }}` | Stuff code |
| `{{ x \| with_images }}` | Extract images as tokens |
| `{{ x \| with_images \| tag }}` | Extract then wrap in tags |
diff --git a/docs/under-the-hood/template-sandbox.md b/docs/under-the-hood/template-sandbox.md
new file mode 100644
index 000000000..b67a4c20f
--- /dev/null
+++ b/docs/under-the-hood/template-sandbox.md
@@ -0,0 +1,76 @@
+---
+title: "Template Sandbox"
+description: "Every Jinja2 template Pipelex renders runs under one sandbox policy: a template reads data and calls methods of plain values, and nothing else."
+---
+
+# Template Sandbox
+
+A method's templates are code. PipeLLM prompts, PipeCompose templates and construct templates, PipeImgGen and PipeSearch prompts, and PipeCondition expressions are all Jinja2 templates, and they render inside the process that runs the method. When that process is shared, as it is on a hosted runner, a template must not be able to reach anything but the data it was given.
+
+Pipelex therefore renders every template, its own included, under one policy: **a template reads data and calls methods of plain values, and nothing else.**
+
+## What a template may do
+
+| A template may | For example |
+|---|---|
+| Read the public fields of an input, with a dot or with brackets, the named parts of a `Composite` included | `{{ invoice.total }}`, `{{ invoice['total'] }}`, `{{ combo.summary }}` |
+| Read an input's metadata fields | `{{ invoice._stuff_name }}`, `{{ invoice._content_class }}`, `{{ invoice._concept_code }}`, `{{ invoice._stuff_code }}` |
+| Read any key of a plain dict with brackets, underscore keys included | `{{ record['_id'] }}`, `{{ record['__typename'] }}` |
+| Call the dict-like accessors of an input | `{{ invoice.get('total') }}`, `{% for key, value in invoice.iter_items() %}` |
+| Call methods of strings, numbers, dates and times, lists, tuples, dicts and sets | `{{ issued_at.isoformat() }}`, `{{ name.upper() }}`, `{{ record.get('a') }}` |
+| Format a string, including with replacement fields | `{{ '{0} items'.format(count) }}` |
+| Use Jinja's own constructs and globals | macros and `caller()`, `loop.cycle()`, `namespace()`, `cycler()`, `joiner()`, `range()`, `dict()` |
+| Apply any filter | `{{ doc \| tag }}`, `{{ doc \| format }}`, `{{ page \| with_images }}`, `{{ items \| length }}` |
+
+## What a template may not do
+
+| A template may not | For example |
+|---|---|
+| Read a name starting with an underscore, other than the metadata fields and a plain dict's keys above | `{{ doc._stuff }}`, `{{ doc['_content'] }}`, `{{ doc.__class__ }}`, `{{ record._id }}` |
+| Read the `Stuff` an input wraps | `{{ doc.stuff }}` is undefined |
+| Call a method of anything that is not a plain value | `{{ pages[0].model_dump() }}`, `{{ photos[0].model_copy() }}` |
+| Call a class method, even through an instance | `{{ issued_at.now() }}` |
+| Change a list, a dict or a set | `{{ items.append(x) }}`, `{{ record.update(other) }}`, `{{ tags.intersection_update(other) }}` |
+| Store a callable in a `namespace()` | `{% set ns.f = name.upper %}`, `namespace(items=doc.get)` |
+| Include or extend another template | `{% include 'header.html' %}` |
+
+A method template renders without a template loader, so `{% include %}`, `{% extends %}` and `{% import %}` find nothing to load.
+
+## How a refusal shows up
+
+Many refusals are visible in the template itself, and validation reports them before anything runs: a template that reads an undeclared underscore name with a dot fails with the `template_private_name` validation error, which names the pipe and the template (`prompt`, `system_prompt`, `template`, `expression`, or `construct field '<path>'`).
+
+What validation cannot see, because it depends on the values at run time (a method call, a name computed while rendering, or a bracketed key, which is legitimate on a plain dict), is refused where it happens: the render raises [`Jinja2TemplateSecurityError`](../errors/jinja2-template-security-error.md), whose message names the refused attribute or callable and the type it was reached on. A refusal never renders as an empty string, so a prompt is never sent with a hole in it.
+
+## How it is built
+
+Every environment comes from one factory, `make_jinja2_env_from_loader` in `pipelex/tools/jinja2/jinja2_environment.py`, and that factory builds a `PipelexTemplateEnvironment` (`pipelex/tools/jinja2/jinja2_sandbox.py`), a subclass of Jinja's `ImmutableSandboxedEnvironment`. Rendering, parsing and compiling all go through it, including the condition pipe's compile at load and the load-time template walkers.
+
+Jinja's stock sandbox refuses internals, but not public methods, and every pydantic model has public constructors. Under the stock sandbox a template could call `model_validate` on a content object and forge an image pointing at a storage key of its choosing. The Pipelex policy closes that by allowing calls by kind rather than by name:
+
+- **Jinja's own runtime**: macros, `caller`, `loop`, `cycler`, `joiner`, block references, and the environment's globals.
+- **Methods a plain value type defines**, bound to an instance of that type. A subclass of a plain type (a `StrEnum` member is a `str`) cannot add or override a callable method, and a class method is refused because it is bound to the class. A method that changes a list, a dict or a set in place is refused by a list Pipelex keeps itself, since Jinja's own misses `set.intersection_update`.
+- **The sandbox's own `str.format` wrapper**, which resolves replacement fields through the same attribute and item checks. The raw `str.format` stays refused.
+- **The methods a type declares as its template surface** (`pipelex/tools/jinja2/template_surface.py`).
+
+A type declares its template surface as a `__template_surface__` class attribute: the methods a template may call on an instance and the underscore names it may read. The sandbox reads the declaration from the type, never from the instance. `StuffArtefact`, the adapter every input is wrapped in, declares `get`, `iter_keys`, `iter_items` and `iter_values`, and its four metadata fields. The `Stuff` it wraps is not one of its attributes at all: Python code reaches it through `unwrap_stuff_artefact`, and its bracket access and `get` resolve a key to a content field or a metadata field only.
+
+The sandbox refuses a bracketed name before trying `obj[name]`. Jinja only checks a bracketed name when the item lookup fails, so an object whose `__getitem__` answered any key would otherwise hand over what the dot spelling could not. A plain `dict` is the exception, because its items are data: a key it holds is returned, and a key it does not hold falls back to an attribute read, which the underscore rule refuses.
+
+Filters are not calls in this sense: they are Pipelex's or Jinja's own code, registered by the environment. That makes each filter trusted code with one obligation: **a filter never calls a callable it was handed**, since that callable came from the template's values and the policy never vetted it. So `with_images`, `format` and `tag` call a value's rendering method only when the value's class defines it, and they check that on the type (`pipelex/tools/jinja2/renderable_dispatch.py`). A runtime-checkable Protocol alone would not do: on Python 3.11 it accepts a `namespace()` holding a callable of the template's choosing.
+
+Jinja's own filters and markupsafe keep that obligation only for values whose attributes the template cannot choose: they look `__html__` up on a value when escaping, and `items` in `dictsort` and `xmlattr`, and call what they find. A `namespace()` answers any name with whatever the template stored under it, so the environment's `namespace` holds data only, and storing a callable in one, at construction or with `{% set ns.x = … %}`, is refused.
+
+## Paths outside templates
+
+A method also writes dotted paths that are not templates: a PipeCompose construct field's `from` and its `list_to_dict_keyed_by`, a PipeBatch's list, and the image and document references of a prompt. The runtime walks these with `getattr`, so the same rule applies to them: a segment starting with an underscore is refused. A construct's `from` path and `list_to_dict_keyed_by` are refused when the bundle is validated, and every path is refused again when it is walked.
+
+## What the sandbox does not cover
+
+- **Resource use.** The sandbox limits what a template can reach, not what it can spend. Jinja caps `range`, and a longer range fails the render with `Jinja2TemplateRenderError`, but nothing caps exponentiation, string repetition, nested loops or output size.
+- **The URLs values carry.** A template cannot forge content under this policy, but a value can still carry a URL, and reading it is the storage layer's decision, not the template's.
+
+## Related
+
+- [StuffArtefact & Image Rendering](stuffartefact-and-image-rendering.md): how inputs reach templates, and how images are extracted from them.
+- [`Jinja2TemplateSecurityError`](../errors/jinja2-template-security-error.md): the error a refusal raises at render time.
diff --git a/mkdocs.yml b/mkdocs.yml
index cb7a2d727..648eeb327 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -343,6 +343,7 @@ plugins:
- under-the-hood/image-handling-in-llm-prompts.md: "Image Handling in LLM Prompts"
- under-the-hood/reasoning-controls.md: "Reasoning Controls"
- under-the-hood/stuffartefact-and-image-rendering.md: "StuffArtefact & Image Rendering"
+ - under-the-hood/template-sandbox.md: "Template Sandbox"
- under-the-hood/test-profile-configuration.md: "Test Profile Configuration"
- under-the-hood/init-cli-flows.md: "Init CLI Flows"
- under-the-hood/pipe-routing-and-execution.md: "Pipe Routing & Execution"
@@ -578,6 +579,7 @@ nav:
- Image Handling in LLM Prompts: under-the-hood/image-handling-in-llm-prompts.md
- Reasoning Controls: under-the-hood/reasoning-controls.md
- StuffArtefact & Image Rendering: under-the-hood/stuffartefact-and-image-rendering.md
+ - Template Sandbox: under-the-hood/template-sandbox.md
- Test Profile Configuration: under-the-hood/test-profile-configuration.md
- Init CLI Flows: under-the-hood/init-cli-flows.md
- Pipe Routing & Execution: under-the-hood/pipe-routing-and-execution.md
diff --git a/pipelex/core/memory/working_memory.py b/pipelex/core/memory/working_memory.py
index 05dcb7845..ab5f6d619 100644
--- a/pipelex/core/memory/working_memory.py
+++ b/pipelex/core/memory/working_memory.py
@@ -28,6 +28,7 @@ from pipelex.core.stuffs.text_and_images_content import TextAndImagesContent
from pipelex.core.stuffs.text_content import TextContent
from pipelex.core.stuffs.yes_no_content import YesNoContent
from pipelex.tools.misc.context_provider_abstract import ContextProviderAbstract
+from pipelex.tools.misc.string_utils import find_private_path_segment
MAIN_STUFF_NAME = "main_stuff"
BATCH_ITEM_STUFF_NAME = "BATCH_ITEM"
@@ -316,6 +317,12 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):
"""
# TODO: Refactor this method. In the python paradigm, we should not have those ".", but arrays with field names.
if "." in name:
+ # The path is walked with `attrgetter`, which follows any name: refuse the private ones.
+ if private_segment := find_private_path_segment(path=name):
+ raise WorkingMemoryStuffAttributeNotFoundError(
+ variable_name=name,
+ message=f"Attribute path '{name}' reads '{private_segment}', which starts with an underscore: a path reads public fields only",
+ )
parts = name.split(".", 1) # Split only at the first dot
base_name = parts[0]
attr_path_str = parts[1] # Keep the rest as a dot-separated string
diff --git a/pipelex/core/stuffs/stuff_artefact.py b/pipelex/core/stuffs/stuff_artefact.py
index 797f28ddb..b4b723d9e 100644
--- a/pipelex/core/stuffs/stuff_artefact.py
+++ b/pipelex/core/stuffs/stuff_artefact.py
@@ -10,6 +10,11 @@ Example template usage:
{{ my_stuff._stuff_name }} # Access metadata
{{ my_stuff | tag }} # Use tag filter
{{ my_stuff | with_images }} # Use with_images filter
+
+Templates render under the Pipelex sandbox (`pipelex/tools/jinja2/jinja2_sandbox.py`), which lets a
+template read public data and call methods of plain values only. StuffArtefact declares its template
+surface: the dict-like accessors a template may call, and the metadata fields it may read although
+they start with an underscore.
"""
from __future__ import annotations
@@ -21,10 +26,12 @@ from typing_extensions import override
from pipelex.core.stuffs.list_content import ListContent
from pipelex.tools.jinja2.image_renderable import ImageRenderable
+from pipelex.tools.jinja2.template_surface import TemplateSurface
from pipelex.tools.templating.text_format import TextFormat
if TYPE_CHECKING:
from pipelex.core.stuffs.stuff import Stuff
+ from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.tools.jinja2.image_registry import ImageRegistry
@@ -33,14 +40,58 @@ class BaseStuffArtefactField(StrEnum):
These fields are accessible via the artefact but are not part of the
content model. They use underscore prefixes to avoid conflicts with
- user-defined content fields.
+ user-defined content fields. They are scalars, and they are the only
+ underscore-prefixed names a template may read on an artefact: the raw
+ content object is deliberately not among them.
"""
STUFF_NAME = "_stuff_name"
CONTENT_CLASS = "_content_class"
CONCEPT_CODE = "_concept_code"
STUFF_CODE = "_stuff_code"
- CONTENT = "_content"
+
+
+_METADATA_FIELD_NAMES = frozenset(field.value for field in BaseStuffArtefactField)
+
+
+def _public_extra_fields(*, content: StuffContent) -> dict[str, Any]:
+ """The public extra fields of a model that allows extras, which is where `CompositeContent` holds its parts.
+
+ They are read from `model_extra` and never with getattr, so a part named like a pydantic attribute
+ (`model_dump`, `model_extra`) resolves to the part and not to the attribute.
+ """
+ return {name: value for name, value in (content.model_extra or {}).items() if not name.startswith("_")}
+
+
+def _content_field_names(*, content: StuffContent) -> list[str]:
+ """The content fields a template reads: the declared ones, then the public extra fields."""
+ declared_names: list[str] = list(type(content).model_fields) # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
+ return [*declared_names, *_public_extra_fields(content=content)]
+
+
+def _get_template_value(*, stuff: Stuff, key: str) -> Any:
+ """Return what a template reads under `key`: a content field, else a metadata field.
+
+ This is the whole of what a string key resolves to, with a dot, with brackets or through `get`:
+ anything else (the wrapped Stuff, the artefact's own methods) raises KeyError.
+ """
+ content = stuff.content
+ if key in type(content).model_fields:
+ return getattr(content, key)
+ extra_fields = _public_extra_fields(content=content)
+ if key in extra_fields:
+ return extra_fields[key]
+ match key:
+ case BaseStuffArtefactField.STUFF_NAME:
+ return stuff.stuff_name
+ case BaseStuffArtefactField.CONTENT_CLASS:
+ return content.__class__.__name__
+ case BaseStuffArtefactField.CONCEPT_CODE:
+ return stuff.concept.code
+ case BaseStuffArtefactField.STUFF_CODE:
+ return stuff.stuff_code
+ case _:
+ raise KeyError(key)
# Attributes that should NOT be intercepted and delegated to content
@@ -58,7 +109,6 @@ _PASSTHROUGH_ATTRS = frozenset(
"render_with_images",
# Methods that must remain accessible (TextFormatRenderable protocol)
"rendered_for_template_async",
- "stuff",
# Dict-like methods for template iteration
"iter_keys",
"iter_items",
@@ -106,6 +156,13 @@ class StuffArtefact:
__slots__ = ("_stuff",)
+ # What a template may do beyond reading public data: call the dict-like accessors, and read the
+ # metadata fields although they start with an underscore.
+ __template_surface__ = TemplateSurface(
+ callable_names=frozenset({"get", "iter_keys", "iter_items", "iter_values"}),
+ private_names=_METADATA_FIELD_NAMES,
+ )
+
def __init__(self, stuff: Stuff) -> None:
"""Initialize the artefact with a Stuff object.
@@ -141,34 +198,20 @@ class StuffArtefact:
if key in _PASSTHROUGH_ATTRS or key.startswith("__"):
return object.__getattribute__(self, key)
- # Get the underlying stuff - use object.__getattribute__ to avoid recursion
+ # Content fields first (the most common access pattern in templates), then metadata fields,
+ # then normal attribute lookup for methods etc. Use object.__getattribute__ to avoid recursion.
stuff = object.__getattribute__(self, "_stuff")
- content = stuff.content
-
- # Check content fields (most common access pattern in templates)
- content_fields = type(content).model_fields # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
- if key in content_fields:
- return getattr(content, key)
-
- # Metadata accessors (underscore-prefixed)
- match key:
- case "_stuff_name":
- return stuff.stuff_name
- case "_content_class":
- return content.__class__.__name__
- case "_concept_code":
- return stuff.concept.code
- case "_stuff_code":
- return stuff.stuff_code
- case "_content":
- return content
- case _:
- # Fall back to normal attribute lookup for methods etc.
- return object.__getattribute__(self, key)
+ try:
+ return _get_template_value(stuff=stuff, key=key)
+ except KeyError:
+ return object.__getattribute__(self, key)
def __getitem__(self, key: str | int | slice) -> Any:
"""Support bracket notation: stuff['field'] or stuff[0] for list indexing.
+ A string key resolves to a content field or a metadata field only, never to the artefact's
+ own attributes: the template sandbox checks a bracketed name only when `obj[key]` fails.
+
Args:
key: String key for field access, or int/slice for list content indexing.
@@ -176,14 +219,11 @@ class StuffArtefact:
The value for the key, or the indexed item(s) from list content.
Raises:
- KeyError: If string key is not found.
+ KeyError: If string key is not a content field or a metadata field.
TypeError: If int/slice indexing on non-indexable content.
"""
if isinstance(key, str):
- try:
- return getattr(self, key)
- except AttributeError as exc:
- raise KeyError(key) from exc
+ return _get_template_value(stuff=self._stuff, key=key)
# Integer or slice - delegate to ListContent
content = self._stuff.content
if isinstance(content, ListContent):
@@ -193,18 +233,18 @@ class StuffArtefact:
raise TypeError(msg)
def get(self, key: str, *, default: Any = None) -> Any:
- """Dict-like get method.
+ """Dict-like get method, resolving the same keys as bracket access.
Args:
key: The key to access.
default: Value to return if key not found.
Returns:
- The value for the key, or default if not found.
+ The value for the key, or default if it is neither a content field nor a metadata field.
"""
try:
- return getattr(self, key)
- except AttributeError:
+ return _get_template_value(stuff=self._stuff, key=key)
+ except KeyError:
return default
def __contains__(self, key: str) -> bool:
@@ -216,14 +256,12 @@ class StuffArtefact:
Returns:
True if the key is accessible, False otherwise.
"""
- content_fields = type(self._stuff.content).model_fields # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-
# Check content fields
- if key in content_fields:
+ if key in _content_field_names(content=self._stuff.content):
return True
# Check metadata fields
- return key in {"_stuff_name", "_content_class", "_concept_code", "_stuff_code", "_content"}
+ return key in _METADATA_FIELD_NAMES
def __iter__(self) -> Iterator[Any]:
"""Enable direct iteration when content is ListContent.
@@ -289,7 +327,7 @@ class StuffArtefact:
Field names from content, followed by metadata field names.
"""
# Content fields (use self._stuff since it's in _PASSTHROUGH_ATTRS)
- yield from type(self._stuff.content).model_fields # pyright: ignore[reportUnknownMemberType]
+ yield from _content_field_names(content=self._stuff.content)
# Metadata fields
for field in BaseStuffArtefactField:
yield field.value
@@ -388,19 +426,6 @@ class StuffArtefact:
raise TypeError(msg)
return content.render_with_images(registry=registry, text_format=text_format)
- # -------------------------------------------------------------------------
- # Access to underlying Stuff
- # -------------------------------------------------------------------------
-
- @property
- def stuff(self) -> Stuff:
- """Access the underlying Stuff object.
-
- Returns:
- The wrapped Stuff object.
- """
- return self._stuff # type: ignore[no-any-return]
-
@override
def __str__(self) -> str:
"""Return plain text content for string conversion."""
@@ -411,3 +436,13 @@ class StuffArtefact:
def __repr__(self) -> str:
"""Return string representation."""
return f"StuffArtefact({self._stuff.stuff_name or 'unnamed'})"
+
+
+def unwrap_stuff_artefact(*, artefact: StuffArtefact) -> Stuff:
+ """Return the Stuff an artefact wraps, for Python code.
+
+ This is a function rather than a property on purpose: every public attribute of an artefact is
+ readable from a template, and the wrapped Stuff, with its raw content object, is not template data.
+ """
+ # The one read of the slot from outside the class, which is the point: the class exposes no accessor.
+ return artefact._stuff # type: ignore[no-any-return] # ruff: ignore[private-member-access]
diff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.py
index 6e1a5f175..5c4a1e680 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition.py
@@ -16,7 +16,7 @@ from pipelex.interpreter_hub import get_optional_pipe, get_pipe_router, get_requ
from pipelex.pipe_controllers.condition.pipe_condition_blueprint import describe_expression_parse_failure
from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
from pipelex.pipe_controllers.pipe_controller import PipeController
-from pipelex.pipe_machinery.template_guard_lint import lint_optional_input_guards
+from pipelex.pipe_machinery.template_guard_lint import lint_authored_template
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
@@ -110,9 +110,9 @@ class PipeCondition(PipeController):
@override
def validate_inputs_static(self):
- # Guard-lint (D7): a declared-optional input referenced unguarded in the expression
- # would evaluate over an undefined variable when the value is absent.
- lint_optional_input_guards(
+ # Template lints: no private names, and no declared-optional input referenced unguarded in
+ # the expression, which would evaluate over an undefined variable when the value is absent (D7).
+ lint_authored_template(
pipe_code=self.code,
domain_code=self.domain_code,
inputs=self.inputs,
diff --git a/pipelex/pipe_machinery/template_guard_lint.py b/pipelex/pipe_machinery/template_guard_lint.py
index 4647ff70d..d0ee2c79b 100644
--- a/pipelex/pipe_machinery/template_guard_lint.py
+++ b/pipelex/pipe_machinery/template_guard_lint.py
@@ -1,18 +1,62 @@
-"""Shared template guard-lint (optionals design D7), applied by every pipe that renders
-authored templates over its inputs (PipeLLM prompts, PipeCompose templates, PipeCondition
-expressions): each reference to a declared-optional (`?`) input must be guarded, otherwise
-validation fails with `OPTIONAL_INPUT_UNGUARDED` and the precise fix.
+"""Shared template lints, applied by every pipe that renders authored templates over its inputs
+(PipeLLM prompts, PipeCompose templates and construct templates, PipeImgGen and PipeSearch prompts,
+PipeCondition expressions):
+
+- the guard-lint (optionals design D7): each reference to a declared-optional (`?`) input must be
+ guarded, otherwise validation fails with `OPTIONAL_INPUT_UNGUARDED` and the precise fix;
+- the private-name lint: a template may not read, with a dot, a name starting with an underscore,
+ other than the metadata fields of an input, otherwise validation fails with `TEMPLATE_PRIVATE_NAME`.
+ The template sandbox refuses the same reads at render time; this lint turns the visible ones into a
+ located error.
"""
from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigils
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
+from pipelex.core.stuffs.stuff_artefact import StuffArtefact
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_optional_guards import detect_unguarded_optional_references
+from pipelex.tools.jinja2.jinja2_private_names import detect_private_name_references
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.validation_error_types import PipeValidationErrorType
+def lint_authored_template(
+ *,
+ pipe_code: str,
+ domain_code: str | None,
+ inputs: InputStuffSpecs,
+ template_source: str,
+ template_category: TemplateCategory,
+ template_label: str,
+) -> None:
+ """Run every template lint over one authored template of a pipe: private names, then optional guards.
+
+ Args:
+ pipe_code: The pipe being validated (for the error).
+ domain_code: The pipe's domain (for the error).
+ inputs: The pipe's declared inputs.
+ template_source: The authored template source.
+ template_category: The template's category (LLM_PROMPT, EXPRESSION, ...).
+ template_label: Which template this is, for the message.
+ """
+ lint_template_private_names(
+ pipe_code=pipe_code,
+ domain_code=domain_code,
+ template_source=template_source,
+ template_category=template_category,
+ template_label=template_label,
+ )
+ lint_optional_input_guards(
+ pipe_code=pipe_code,
+ domain_code=domain_code,
+ inputs=inputs,
+ template_source=template_source,
+ template_category=template_category,
+ template_label=template_label,
+ )
+
+
def lint_optional_input_guards(
*,
pipe_code: str,
@@ -72,3 +116,54 @@ def lint_optional_input_guards(
variable_names=[finding.variable_name],
explanation=f"Unguarded reference '{finding.path}' to optional input '{finding.variable_name}' in the {template_label}.",
)
+
+
+def lint_template_private_names(
+ *,
+ pipe_code: str,
+ domain_code: str | None,
+ template_source: str,
+ template_category: TemplateCategory,
+ template_label: str,
+) -> None:
+ """Raise `TEMPLATE_PRIVATE_NAME` when the template reads, with a dot, a name starting with an
+ underscore that is not one of the metadata fields an input declares (`_stuff_name`, `_content_class`, ...).
+
+ The template is given in authored form, like the guard-lint's. Only dot reads written in the
+ template are seen here: a bracketed key may be a plain dict's data, which only the render can tell,
+ and the template sandbox refuses the rest at render time.
+
+ Args:
+ pipe_code: The pipe being validated (for the error).
+ domain_code: The pipe's domain (for the error).
+ template_source: The authored template source.
+ template_category: The template's category (LLM_PROMPT, EXPRESSION, ...).
+ template_label: Which template this is, for the message ("prompt", "system_prompt",
+ "template", "expression", "construct field 'x'").
+ """
+ allowed_private_names = StuffArtefact.__template_surface__.private_names
+ try:
+ refused_names = detect_private_name_references(
+ template_category=template_category,
+ template_source=rewrite_template_sigils(template_source),
+ allowed_private_names=allowed_private_names,
+ )
+ except Jinja2DetectVariablesError:
+ # An unparseable template is not this lint's concern, for the reason the guard-lint gives.
+ return
+ if not refused_names:
+ return
+ refused_name = refused_names[0]
+ allowed_list = ", ".join(f"'{name}'" for name in sorted(allowed_private_names))
+ msg = (
+ f"In the {template_label} of pipe '{pipe_code}', the template reads '{refused_name}', a name starting with an underscore. "
+ f"Templates read the public fields of their inputs; the only underscore names a dot may read are an input's metadata fields: "
+ f"{allowed_list}. A key of a plain dict is read with brackets: record['_id']."
+ )
+ raise PipeValidationError(
+ message=msg,
+ error_type=PipeValidationErrorType.TEMPLATE_PRIVATE_NAME,
+ domain_code=domain_code,
+ pipe_code=pipe_code,
+ explanation=f"The {template_label} reads the private name '{refused_name}'.",
+ )
diff --git a/pipelex/pipe_operators/compose/construct_blueprint.py b/pipelex/pipe_operators/compose/construct_blueprint.py
index b0d63a745..370dbc86c 100644
--- a/pipelex/pipe_operators/compose/construct_blueprint.py
+++ b/pipelex/pipe_operators/compose/construct_blueprint.py
@@ -18,7 +18,7 @@ from pipelex.pipe_operators.compose.exceptions import ConstructFieldBlueprintTyp
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
from pipelex.tools.jinja2.template_category import TemplateCategory
-from pipelex.tools.misc.string_utils import get_root_from_dotted_path
+from pipelex.tools.misc.string_utils import find_private_path_segment, get_root_from_dotted_path
class ConstructFieldMethod(StrEnum):
@@ -160,10 +160,21 @@ class ConstructFieldBlueprint(BaseModel):
if not isinstance(from_value, str):
msg = "'from' value must be a string path"
raise ConstructFieldBlueprintTypeError(msg)
+ if private_segment := find_private_path_segment(path=from_value):
+ msg = (
+ f"'from' path '{from_value}' reads '{private_segment}', a name starting with an underscore: "
+ "a path reads the public fields of an input only."
+ )
+ raise ConstructFieldBlueprintValueError(msg)
list_to_dict_keyed_by = raw_dict.get("list_to_dict_keyed_by")
if list_to_dict_keyed_by is not None and not isinstance(list_to_dict_keyed_by, str):
msg = "'list_to_dict_keyed_by' value must be a string attribute name"
raise ConstructFieldBlueprintTypeError(msg)
+ if list_to_dict_keyed_by is not None and find_private_path_segment(path=list_to_dict_keyed_by):
+ msg = (
+ f"'list_to_dict_keyed_by' names '{list_to_dict_keyed_by}', a name starting with an underscore: it names a public field only."
+ )
+ raise ConstructFieldBlueprintValueError(msg)
return cls(
method=ConstructFieldMethod.FROM_VAR,
from_path=from_value,
@@ -220,6 +231,28 @@ class ConstructBlueprint(BaseModel):
"""Return list of all top-level field names."""
return list(self.fields.keys())
+ def field_templates(self) -> list[tuple[str, str]]:
+ """Return every template of this construct, nested constructs included, with its dotted field path.
+
+ Returns:
+ (field_path, template) pairs, in field order, a nested construct's fields after its own path.
+ """
+ templates: list[tuple[str, str]] = []
+ for field_name, field_blueprint in self.fields.items():
+ match field_blueprint.method:
+ case ConstructFieldMethod.TEMPLATE:
+ if field_blueprint.template:
+ templates.append((field_name, field_blueprint.template))
+ case ConstructFieldMethod.NESTED:
+ if field_blueprint.nested:
+ templates.extend(
+ (f"{field_name}.{nested_path}", nested_template)
+ for nested_path, nested_template in field_blueprint.nested.field_templates()
+ )
+ case ConstructFieldMethod.FROM_VAR | ConstructFieldMethod.FIXED:
+ pass
+ return templates
+
def get_required_variables(self) -> set[str]:
"""Extract all variable names/paths required to compose this construct.
diff --git a/pipelex/pipe_operators/compose/pipe_compose.py b/pipelex/pipe_operators/compose/pipe_compose.py
index ff3548d3a..e535be5cc 100644
--- a/pipelex/pipe_operators/compose/pipe_compose.py
+++ b/pipelex/pipe_operators/compose/pipe_compose.py
@@ -18,7 +18,7 @@ from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.kernel.compose_ops import run_compose_template
from pipelex.kernel.templating_style_ops import resolve_templating_style
-from pipelex.pipe_machinery.template_guard_lint import lint_optional_input_guards
+from pipelex.pipe_machinery.template_guard_lint import lint_authored_template, lint_template_private_names
from pipelex.pipe_operators.compose.construct_blueprint import ConstructBlueprint
from pipelex.pipe_operators.compose.exceptions import PipeComposeError, StructuredContentComposerValueError
from pipelex.pipe_operators.compose.structured_content_composer import StructuredContentComposer
@@ -103,10 +103,9 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
@override
def validate_inputs_static(self):
- # Guard-lint (D7): every template reference to a declared-optional input must be guarded.
- # Construct mode composes structured fields, not authored templates — nothing to lint there.
+ # Template lints: no private names, and every reference to a declared-optional input guarded (D7).
if self.template is not None:
- lint_optional_input_guards(
+ lint_authored_template(
pipe_code=self.code,
domain_code=self.domain_code,
inputs=self.inputs,
@@ -114,6 +113,17 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
template_category=self.category,
template_label="template",
)
+ # A construct's template fields render too, so the private-name lint covers them as well.
+ # The guard-lint does not run on construct templates.
+ if self.construct_blueprint is not None:
+ for field_path, field_template in self.construct_blueprint.field_templates():
+ lint_template_private_names(
+ pipe_code=self.code,
+ domain_code=self.domain_code,
+ template_source=field_template,
+ template_category=TemplateCategory.BASIC,
+ template_label=f"construct field '{field_path}'",
+ )
@override
def validate_inputs_with_library(self):
diff --git a/pipelex/pipe_operators/compose/structured_content_composer.py b/pipelex/pipe_operators/compose/structured_content_composer.py
index 9dbffaf6a..3c62b897f 100644
--- a/pipelex/pipe_operators/compose/structured_content_composer.py
+++ b/pipelex/pipe_operators/compose/structured_content_composer.py
@@ -22,6 +22,7 @@ from pipelex.pipe_operators.compose.exceptions import (
StructuredContentComposerValueError,
)
from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.misc.string_utils import find_private_path_segment
from pipelex.tools.templating.templating_style import TemplatingStyle
from pipelex.tools.typing.annotation_utils import unwrap_optional
from pipelex.tools.typing.class_utils import are_classes_equivalent
@@ -240,6 +241,9 @@ class StructuredContentComposer:
msg = f"list_to_dict_keyed_by requires ListContent or list, got {type(value).__name__}"
raise StructuredContentComposerTypeError(msg)
+ if find_private_path_segment(path=key_attr):
+ msg = f"list_to_dict_keyed_by names '{key_attr}', which starts with an underscore: it names a public field only"
+ raise StructuredContentComposerValueError(msg)
log.verbose(f" Converting list of {len(items)} items to dict keyed by '{key_attr}'")
result: dict[str, Any] = {}
@@ -282,6 +286,10 @@ class StructuredContentComposer:
Returns:
The value at the end of the attribute path, converted as appropriate
"""
+ # The blueprint refuses these at load; the walk below is raw `getattr`, so it refuses them again.
+ if private_segment := find_private_path_segment(path=path):
+ msg = f"Cannot resolve path '{path}': '{private_segment}' starts with an underscore, and a path reads public fields only"
+ raise StructuredContentComposerValueError(msg)
parts = path.split(".", 1)
base_name = parts[0]
attr_path = parts[1]
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen.py b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
index a63669305..cd5f37e3e 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
@@ -22,7 +22,7 @@ from pipelex.interpreter_hub import get_concept_library, get_native_concept
from pipelex.kernel.exceptions import PromptContentError
from pipelex.kernel.img_gen_ops import build_img_gen_job_params, resolve_img_gen_setting, run_img_gen
from pipelex.kernel.templating_style_ops import resolve_templating_style
-from pipelex.pipe_machinery.template_guard_lint import lint_optional_input_guards
+from pipelex.pipe_machinery.template_guard_lint import lint_authored_template
from pipelex.pipe_operators.img_gen.exceptions import PipeImgGenFactoryError, PipeImgGenRunError
from pipelex.pipe_operators.img_gen.img_gen_prompt_blueprint import ImgGenPromptBlueprint
from pipelex.pipe_operators.pipe_operator import PipeOperator
@@ -69,14 +69,14 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
check_img_gen_choice_with_deck(img_gen_choice=self.img_gen_choice)
self._validate_param_support_against_model_rules()
- # Guard-lint (D7): every reference to a declared-optional input must be guarded.
+ # Template lints: no private names, and every reference to a declared-optional input guarded (D7).
for template_blueprint, template_label in [
(self.img_gen_prompt_blueprint.prompt_blueprint, "prompt"),
(self.img_gen_prompt_blueprint.negative_prompt_blueprint, "negative_prompt"),
]:
if template_blueprint is None:
continue
- lint_optional_input_guards(
+ lint_authored_template(
pipe_code=self.code,
domain_code=self.domain_code,
inputs=self.inputs,
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index 6da8a4343..dcb0f9b47 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -29,7 +29,7 @@ from pipelex.kernel.llm_ops import (
run_llm_text,
)
from pipelex.kernel.templating_style_ops import resolve_templating_style
-from pipelex.pipe_machinery.template_guard_lint import lint_optional_input_guards
+from pipelex.pipe_machinery.template_guard_lint import lint_authored_template
from pipelex.pipe_machinery.validation import is_input_used_by_variables, is_variable_satisfied_by_inputs
from pipelex.pipe_operators.llm.llm_prompt_blueprint import LLMPromptBlueprint
from pipelex.pipe_operators.pipe_operator import PipeOperator
@@ -102,14 +102,14 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
explanation=f"Variable '{variable_path}' is used in prompt/system_prompt but not declared in inputs.",
)
- # Guard-lint (D7): every reference to a declared-optional input must be guarded.
+ # Template lints: no private names, and every reference to a declared-optional input guarded (D7).
for template_blueprint, template_label in [
(self.llm_prompt_spec.prompt_blueprint, "prompt"),
(self.llm_prompt_spec.system_prompt_blueprint, "system_prompt"),
]:
if template_blueprint is None:
continue
- lint_optional_input_guards(
+ lint_authored_template(
pipe_code=self.code,
domain_code=self.domain_code,
inputs=self.inputs,
diff --git a/pipelex/pipe_operators/search/pipe_search.py b/pipelex/pipe_operators/search/pipe_search.py
index 219446bfa..ff9bcc363 100644
--- a/pipelex/pipe_operators/search/pipe_search.py
+++ b/pipelex/pipe_operators/search/pipe_search.py
@@ -12,7 +12,7 @@ from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.interpreter_hub import get_concept_library
from pipelex.kernel.search_ops import resolve_search_setting, run_search
from pipelex.kernel.templating_style_ops import resolve_templating_style
-from pipelex.pipe_machinery.template_guard_lint import lint_optional_input_guards
+from pipelex.pipe_machinery.template_guard_lint import lint_authored_template
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
@@ -53,8 +53,8 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
with self.locating_model_choice(field_name="model"):
check_search_choice_with_deck(search_choice=self.search_choice)
- # Guard-lint (D7): every reference to a declared-optional input must be guarded.
- lint_optional_input_guards(
+ # Template lints: no private names, and every reference to a declared-optional input guarded (D7).
+ lint_authored_template(
pipe_code=self.code,
domain_code=self.domain_code,
inputs=self.inputs,
diff --git a/pipelex/test_extras/mthds_corpus/entries/invalid_template_private_name/bundle.mthds b/pipelex/test_extras/mthds_corpus/entries/invalid_template_private_name/bundle.mthds
new file mode 100644
index 000000000..c246e6ad5
--- /dev/null
+++ b/pipelex/test_extras/mthds_corpus/entries/invalid_template_private_name/bundle.mthds
@@ -0,0 +1,17 @@
+domain = "clinic_intake"
+description = "Write the intake summary a doctor reads before seeing a patient, naming the triage note it came from"
+main_pipe = "summarize_intake"
+
+[concept]
+TriageNote = "The note a nurse wrote at triage"
+IntakeSummary = "The summary a doctor reads before seeing a patient"
+
+[pipe.summarize_intake]
+type = "PipeLLM"
+description = "Summarize the triage note for the doctor"
+inputs = { triage_note = "TriageNote" }
+output = "IntakeSummary"
+prompt = """
+Summarize this triage note for the doctor: $triage_note
+Name the note by its record code: {{ triage_note._stuff.stuff_code }}.
+"""
diff --git a/pipelex/test_extras/mthds_corpus/entries/invalid_template_private_name/entry.toml b/pipelex/test_extras/mthds_corpus/entries/invalid_template_private_name/entry.toml
new file mode 100644
index 000000000..d1fad8d02
--- /dev/null
+++ b/pipelex/test_extras/mthds_corpus/entries/invalid_template_private_name/entry.toml
@@ -0,0 +1,12 @@
+name = "invalid_template_private_name"
+description = "An intake summary whose prompt reaches past the triage note's fields for the object that wraps it"
+
+validity = "invalid"
+tier = "static"
+granularity = "focused"
+
+covers = [
+ "error.template_private_name",
+]
+
+expected_error = "template_private_name"
diff --git a/pipelex/test_extras/mthds_corpus/vocabulary.toml b/pipelex/test_extras/mthds_corpus/vocabulary.toml
index 06d179290..b56f95602 100644
--- a/pipelex/test_extras/mthds_corpus/vocabulary.toml
+++ b/pipelex/test_extras/mthds_corpus/vocabulary.toml
@@ -157,6 +157,10 @@ fails_at = "runtime"
code = "optional_branch_required_field"
fails_at = "runtime"
+[error.template_private_name]
+code = "template_private_name"
+fails_at = "runtime"
+
[error.optional_force_redundant]
code = "optional_force_redundant"
excluded = "Advisory-only: it rides the validation report's `warnings` array and never makes a verdict invalid. An entry contract that models one `expected_error` on an invalid entry has nowhere to put a warning on a valid one, so there is no shape a focused entry could take. Revisit if the manifest ever grows a warnings axis."
diff --git a/pipelex/tools/jinja2/exceptions.py b/pipelex/tools/jinja2/exceptions.py
index c8ebaf832..7e982d579 100644
--- a/pipelex/tools/jinja2/exceptions.py
+++ b/pipelex/tools/jinja2/exceptions.py
@@ -14,6 +14,16 @@ class Jinja2TemplateRenderError(ToolError):
pass
+class Jinja2TemplateSecurityError(ToolError):
+ # A template reached for something the sandbox policy refuses (`jinja2_sandbox.py`): an undeclared
+ # private name, or a call that is not a method of a plain value. Its message names the attribute or
+ # the callable and the type it was reached on, and never quotes the template source, since the same
+ # render serves Pipelex's own templates. A type of its own, apart from `Jinja2TemplateRenderError`,
+ # so that the classification of render-time template failures can tell a refusal from the rest,
+ # although for now both are classified alike: runtime domain, message not caller-facing.
+ pass
+
+
class Jinja2StuffError(ToolError):
pass
diff --git a/pipelex/tools/jinja2/image_renderable.py b/pipelex/tools/jinja2/image_renderable.py
index bd7c86ffd..ebcf0a250 100644
--- a/pipelex/tools/jinja2/image_renderable.py
+++ b/pipelex/tools/jinja2/image_renderable.py
@@ -26,7 +26,7 @@ class ImageRenderable(Protocol):
with image tokens ([Image N]) in place of actual images.
Implementations:
- - StuffContent (base): iterates model fields, recurses into nested content
+ - StructuredContent (base of structured concepts): iterates model fields, recurses into nested content
- ImageContent: registers itself and returns [Image N] token
- ListContent: renders each item with images
- TextAndImagesContent: renders text, then registers images
diff --git a/pipelex/tools/jinja2/jinja2_environment.py b/pipelex/tools/jinja2/jinja2_environment.py
index fcac6a628..f4662b254 100644
--- a/pipelex/tools/jinja2/jinja2_environment.py
+++ b/pipelex/tools/jinja2/jinja2_environment.py
@@ -1,7 +1,8 @@
import inspect
-from jinja2 import BaseLoader, Environment
+from jinja2 import BaseLoader
+from pipelex.tools.jinja2.jinja2_sandbox import PipelexTemplateEnvironment
from pipelex.tools.jinja2.jinja2_template_registry import TemplateRegistry
from pipelex.tools.jinja2.template_category import TemplateCategory
@@ -11,7 +12,8 @@ def make_jinja2_env_from_loader(
template_category: TemplateCategory,
loader: BaseLoader,
enable_async: bool = True,
-) -> Environment:
+) -> PipelexTemplateEnvironment:
+ """Build the environment for one template category. Every template renders sandboxed (`jinja2_sandbox.py`)."""
autoescape: bool
trim_blocks: bool
lstrip_blocks: bool
@@ -45,7 +47,7 @@ def make_jinja2_env_from_loader(
trim_blocks = False
lstrip_blocks = False
- return Environment(
+ return PipelexTemplateEnvironment(
loader=loader,
enable_async=enable_async,
autoescape=autoescape,
@@ -55,7 +57,7 @@ def make_jinja2_env_from_loader(
def _register_filters(
- jinja2_env: Environment,
+ jinja2_env: PipelexTemplateEnvironment,
*,
template_category: TemplateCategory,
enable_async: bool,
@@ -82,7 +84,7 @@ def make_jinja2_env_without_loader(
template_category: TemplateCategory,
*,
enable_async: bool = True,
-) -> Environment:
+) -> PipelexTemplateEnvironment:
loader = BaseLoader()
jinja2_env = make_jinja2_env_from_loader(
template_category=template_category,
@@ -98,7 +100,7 @@ def make_jinja2_env_from_registry(
template_category: TemplateCategory,
*,
enable_async: bool = True,
-) -> Environment:
+) -> PipelexTemplateEnvironment:
"""Create Environment with DictLoader from pre-loaded registry.
This function creates a Jinja2 Environment backed by the TemplateRegistry,
diff --git a/pipelex/tools/jinja2/jinja2_filters.py b/pipelex/tools/jinja2/jinja2_filters.py
index d0964d9b4..d72e7cb60 100644
--- a/pipelex/tools/jinja2/jinja2_filters.py
+++ b/pipelex/tools/jinja2/jinja2_filters.py
@@ -7,6 +7,7 @@ from jinja2.runtime import Context, Undefined
from pipelex.tools.jinja2.exceptions import Jinja2ContextError
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
+from pipelex.tools.jinja2.renderable_dispatch import type_implements
from pipelex.tools.jinja2.tag_renderable import TagRenderable
from pipelex.tools.jinja2.text_format_renderable import TextFormatRenderable
from pipelex.tools.templating.templating_style import TagStyle
@@ -62,8 +63,8 @@ async def text_format(context: Context, value: Any, text_format: TextFormat | st
else:
applied_text_format = TextFormat(require_templating_style_value(context=context, jinja2_context_key=Jinja2ContextKey.TEXT_FORMAT))
- # Protocol-based rendering
- if isinstance(value, TextFormatRenderable):
+ # Protocol-based rendering, licensed by the value's type (see renderable_dispatch.py)
+ if isinstance(value, TextFormatRenderable) and type_implements(value=value, protocol=TextFormatRenderable):
return await value.rendered_for_template_async(text_format=applied_text_format)
if isinstance(value, StrEnum):
return value.value
@@ -97,7 +98,7 @@ async def tag(context: Context, value: Any, tag_name: str | None = None) -> str:
msg = f"Cannot use tag filter on undefined value with tag_name '{tag_name}'"
raise Jinja2ContextError(msg)
- # Protocol-based rendering
+ # Protocol-based rendering, licensed by the value's type (see renderable_dispatch.py)
rendered_value: str
final_tag_name: str | None = tag_name
@@ -111,13 +112,13 @@ async def tag(context: Context, value: Any, tag_name: str | None = None) -> str:
rendered_value = placeholder
# For registered images, use tag_name if provided, otherwise no default
# (the placeholder already identifies the image)
- elif isinstance(value, TagRenderable):
+ elif isinstance(value, TagRenderable) and type_implements(value=value, protocol=TagRenderable):
rendered_value = await value.render_for_tag_async()
if final_tag_name is None:
final_tag_name = value.default_tag_name
else:
rendered_value = str(value)
- elif isinstance(value, TagRenderable):
+ elif isinstance(value, TagRenderable) and type_implements(value=value, protocol=TagRenderable):
rendered_value = await value.render_for_tag_async()
if final_tag_name is None:
final_tag_name = value.default_tag_name
diff --git a/pipelex/tools/jinja2/jinja2_private_names.py b/pipelex/tools/jinja2/jinja2_private_names.py
new file mode 100644
index 000000000..69cb66863
--- /dev/null
+++ b/pipelex/tools/jinja2/jinja2_private_names.py
@@ -0,0 +1,67 @@
+"""Load-time detection of the private names a template reads, for a located validation error.
+
+The template sandbox (`jinja2_sandbox.py`) refuses, at render time, every name starting with an
+underscore that the value's type does not declare in its template surface. A read with a dot is
+visible in the template itself, `{{ doc._stuff }}`, and this walker finds it at load, so that
+validation names the pipe and the template instead of a run failing later.
+
+It is feedback, not enforcement. The types of the values are unknown at load, so it allows every name
+any declaring type declares, it cannot see a name that is only computed at render time, and it leaves
+bracketed keys alone: `{{ record['_id'] }}` is a legitimate read of a plain dict's data, and only the
+render knows whether the value is one. The runtime policy remains what refuses them.
+"""
+
+from collections.abc import Iterator
+
+from jinja2 import nodes
+from jinja2.exceptions import TemplateSyntaxError
+
+from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
+from pipelex.tools.jinja2.jinja2_environment import make_jinja2_env_without_loader
+from pipelex.tools.jinja2.template_category import TemplateCategory
+
+
+def detect_private_name_references(
+ *,
+ template_category: TemplateCategory,
+ template_source: str,
+ allowed_private_names: frozenset[str],
+) -> list[str]:
+ """Return the private names the template reads with a dot.
+
+ Args:
+ template_category: Category of the template (LLM_PROMPT, EXPRESSION, etc.)
+ template_source: Jinja2 template source (sigils already rewritten to Jinja2).
+ allowed_private_names: The underscore-prefixed names a declaring type lets templates read.
+
+ Returns:
+ Each refused name once, in the order a render would reach them.
+
+ Raises:
+ Jinja2DetectVariablesError: If the template cannot be parsed.
+ """
+ jinja2_env = make_jinja2_env_without_loader(template_category=template_category)
+ try:
+ parsed_ast = jinja2_env.parse(template_source)
+ except TemplateSyntaxError as syntax_error:
+ msg = (
+ f"Jinja2 private-name lint — syntax error: '{syntax_error}', template_category: {template_category}, template_source:\n{template_source}"
+ )
+ raise Jinja2DetectVariablesError(msg) from syntax_error
+
+ refused_names: list[str] = []
+ for node in _iter_nodes_in_evaluation_order(node=parsed_ast):
+ if not isinstance(node, nodes.Getattr):
+ continue
+ name = node.attr
+ if not name.startswith("_") or name in allowed_private_names or name in refused_names:
+ continue
+ refused_names.append(name)
+ return refused_names
+
+
+def _iter_nodes_in_evaluation_order(*, node: nodes.Node) -> Iterator[nodes.Node]:
+ """Yield every node after its children, so a chain's first access comes first: `__class__` before `__mro__`."""
+ for child in node.iter_child_nodes():
+ yield from _iter_nodes_in_evaluation_order(node=child)
+ yield node
diff --git a/pipelex/tools/jinja2/jinja2_rendering.py b/pipelex/tools/jinja2/jinja2_rendering.py
index ab8890e54..14965551c 100644
--- a/pipelex/tools/jinja2/jinja2_rendering.py
+++ b/pipelex/tools/jinja2/jinja2_rendering.py
@@ -2,7 +2,9 @@ from collections.abc import Awaitable, Callable
from typing import Any, Protocol
from jinja2.exceptions import (
+ SecurityError,
TemplateAssertionError,
+ TemplateNotFound,
TemplateSyntaxError,
UndefinedError,
)
@@ -11,6 +13,7 @@ from pipelex.tools.jinja2.exceptions import (
Jinja2ContextError,
Jinja2StuffError,
Jinja2TemplateRenderError,
+ Jinja2TemplateSecurityError,
)
from pipelex.tools.jinja2.jinja2_environment import (
make_jinja2_env_from_registry,
@@ -94,11 +97,16 @@ def _make_type_error_msg(template_source: str, *, templating_context: dict[str,
)
+def _make_security_error_msg(*, security_error: SecurityError) -> str:
+ # The template source is left out on purpose: the same render serves Pipelex's own templates.
+ return f"Jinja2 render — refused by the template sandbox: {security_error}"
+
+
def _make_non_type_error_msg(
template_source: str,
*,
error_label: str,
- error: Jinja2StuffError | TemplateSyntaxError | UndefinedError | Jinja2ContextError,
+ error: Jinja2StuffError | TemplateSyntaxError | UndefinedError | TemplateNotFound | Jinja2ContextError | ArithmeticError,
) -> str:
return f"Jinja2 render — {error_label}: '{error}', template_source:\n{template_source}"
@@ -106,6 +114,8 @@ def _make_non_type_error_msg(
def _render_template_sync(template_source: str, *, template: _Jinja2Template, templating_context: dict[str, Any]) -> str:
try:
generated_text: str = template.render(**templating_context)
+ except SecurityError as exc:
+ raise Jinja2TemplateSecurityError(_make_security_error_msg(security_error=exc)) from exc
except Jinja2StuffError as exc:
msg = _make_non_type_error_msg(template_source=template_source, error_label="stuff error", error=exc)
raise Jinja2TemplateRenderError(msg) from exc
@@ -115,9 +125,17 @@ def _render_template_sync(template_source: str, *, template: _Jinja2Template, te
except UndefinedError as exc:
msg = _make_non_type_error_msg(template_source=template_source, error_label="undefined error", error=exc)
raise Jinja2TemplateRenderError(msg) from exc
+ except TemplateNotFound as exc:
+ # A template without a loader (every method template) has nothing to include or extend.
+ msg = _make_non_type_error_msg(template_source=template_source, error_label="template not found", error=exc)
+ raise Jinja2TemplateRenderError(msg) from exc
except Jinja2ContextError as exc:
msg = _make_non_type_error_msg(template_source=template_source, error_label="context error", error=exc)
raise Jinja2TemplateRenderError(msg) from exc
+ except ArithmeticError as exc:
+ # The template's own arithmetic, the sandbox's range cap included: `range` raises OverflowError past it.
+ msg = _make_non_type_error_msg(template_source=template_source, error_label="arithmetic error", error=exc)
+ raise Jinja2TemplateRenderError(msg) from exc
except TypeError as exc:
msg = _make_type_error_msg(template_source=template_source, templating_context=templating_context, type_error=exc)
raise Jinja2TemplateRenderError(msg) from exc
@@ -127,6 +145,8 @@ def _render_template_sync(template_source: str, *, template: _Jinja2Template, te
async def _render_template_async(template_source: str, *, template: _Jinja2Template, templating_context: dict[str, Any]) -> str:
try:
generated_text: str = await template.render_async(**templating_context)
+ except SecurityError as exc:
+ raise Jinja2TemplateSecurityError(_make_security_error_msg(security_error=exc)) from exc
except Jinja2StuffError as exc:
msg = _make_non_type_error_msg(template_source=template_source, error_label="stuff error", error=exc)
raise Jinja2TemplateRenderError(msg) from exc
@@ -136,9 +156,17 @@ async def _render_template_async(template_source: str, *, template: _Jinja2Templ
except UndefinedError as exc:
msg = _make_non_type_error_msg(template_source=template_source, error_label="undefined error", error=exc)
raise Jinja2TemplateRenderError(msg) from exc
+ except TemplateNotFound as exc:
+ # A template without a loader (every method template) has nothing to include or extend.
+ msg = _make_non_type_error_msg(template_source=template_source, error_label="template not found", error=exc)
+ raise Jinja2TemplateRenderError(msg) from exc
except Jinja2ContextError as exc:
msg = _make_non_type_error_msg(template_source=template_source, error_label="context error", error=exc)
raise Jinja2TemplateRenderError(msg) from exc
+ except ArithmeticError as exc:
+ # The template's own arithmetic, the sandbox's range cap included: `range` raises OverflowError past it.
+ msg = _make_non_type_error_msg(template_source=template_source, error_label="arithmetic error", error=exc)
+ raise Jinja2TemplateRenderError(msg) from exc
except TypeError as exc:
msg = _make_type_error_msg(template_source=template_source, templating_context=templating_context, type_error=exc)
raise Jinja2TemplateRenderError(msg) from exc
diff --git a/pipelex/tools/jinja2/jinja2_sandbox.py b/pipelex/tools/jinja2/jinja2_sandbox.py
new file mode 100644
index 000000000..e05391a63
--- /dev/null
+++ b/pipelex/tools/jinja2/jinja2_sandbox.py
@@ -0,0 +1,293 @@
+"""The sandbox every Jinja2 template renders under: templates read data and call methods of plain values.
+
+On the hosted plane a method author's prompts, compose templates, construct templates and condition
+expressions render inside the shared runner and worker processes, so a template is customer code
+running in-process. A plain `jinja2.Environment` lets it walk from a default global into Python module
+globals, and Jinja's stock sandbox is not enough either: it refuses internals but not public methods,
+so a template could still call pydantic's public constructors (`model_validate`, `model_copy`) and
+forge content, such as an image pointing at another organisation's storage key.
+
+`PipelexTemplateEnvironment` applies one policy instead:
+
+- **Reading.** A template reads public attributes and items. A name starting with an underscore is
+ refused, with a dot or with brackets, unless the value's type declares it in its template surface
+ (`template_surface.py`), which is how `StuffArtefact` keeps its documented metadata fields readable.
+ The one exception is a key of a plain `dict` read with brackets (`record['_id']`): a dict's items
+ are data, and a key it does not hold falls back to an attribute read, which the rule above refuses.
+ Jinja's own refusals (a function's globals, a frame, a class's `mro`) stay in force.
+- **Calling.** A template calls Jinja's own runtime (macros, `caller`, `loop`, `cycler`, `joiner`,
+ block references and the environment's globals), methods bound to an instance of a plain value type
+ (`str`, numbers, dates and times, and the built-in containers), `str.format` through the sandbox's
+ safe formatter, and the methods a type declares in its template surface. Everything else is
+ refused: pydantic methods, `Stuff` and content methods, classes, free functions and class methods,
+ and every method that changes a list, a dict or a set in place.
+- **Refusing.** A refusal raises `jinja2.exceptions.SecurityError` at the point of access, which the
+ render functions turn into `Jinja2TemplateSecurityError`. Jinja's stock sandbox returns an undefined
+ value that prints as nothing, which would send a prompt with a hole in it.
+
+Filters and tests are not calls in this sense: they are Pipelex's or Jinja's own code, registered by
+the environment, and Jinja invokes them directly. That makes every filter trusted code with one
+obligation: **a filter never calls a callable it was handed**, since that callable came from the
+template's values and the policy above never vetted it. Jinja's own filters and markupsafe do look a
+few names up on a value and call them, `__html__` when escaping and `items` in `dictsort` and
+`xmlattr`, and a `namespace()` answers any name with whatever the template stored under it. So the
+environment's `namespace` holds data only: storing a callable in one is refused.
+
+Pipelex's own templates (the stuff viewer, the graph pages, the Mermaid pages) render under the same
+policy, with no trusted variant: a trust switch is one more thing a later caller could flip on a
+customer template by mistake. An internal template that needs something the policy refuses gets
+plain data instead.
+"""
+
+from __future__ import annotations
+
+import inspect
+import types
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any, NoReturn
+
+from jinja2.exceptions import SecurityError
+from jinja2.runtime import BlockReference, Context, LoopContext, Macro, Undefined
+from jinja2.sandbox import ImmutableSandboxedEnvironment, safe_range
+from jinja2.utils import Cycler, Joiner, Namespace, generate_lorem_ipsum
+from markupsafe import Markup
+from typing_extensions import override
+
+from pipelex.tools.jinja2.template_surface import get_template_surface
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+# The types whose own methods a template may call on an instance: formatting, not program logic.
+_PLAIN_VALUE_TYPES: tuple[type, ...] = (
+ str,
+ Markup,
+ int,
+ float,
+ bool,
+ Decimal,
+ date,
+ datetime,
+ time,
+ timedelta,
+ list,
+ tuple,
+ dict,
+ set,
+ frozenset,
+)
+
+
+def _refuse_callable_in_namespace(*, name: str, value: object) -> None:
+ # An undefined value is callable only so that calling it fails as an undefined value: storing it is harmless.
+ if callable(value) and not isinstance(value, Undefined):
+ msg = f"A template may not store {_describe_callable(obj=value)} in a namespace, as '{name}': a namespace holds data only."
+ raise SecurityError(msg)
+
+
+class DataNamespace(Namespace):
+ """Jinja's `namespace()`, refusing to hold a callable.
+
+ A namespace answers any attribute name with what the template stored under it, and markupsafe and some
+ of Jinja's filters look a name up on a value and call it: `__html__` when escaping (`e`, `safe`,
+ `striptags`, HTML autoescaping) and `items` in `dictsort` and `xmlattr`. A callable stored in a
+ namespace would be called there without passing the sandbox's call check.
+ """
+
+ def __init__(self, /, *args: Any, **kwargs: Any) -> None:
+ values: dict[str, Any] = dict(*args, **kwargs)
+ for name, value in values.items():
+ _refuse_callable_in_namespace(name=name, value=value)
+ super().__init__(values)
+
+ @override
+ def __setitem__(self, name: str, value: Any) -> None:
+ _refuse_callable_in_namespace(name=name, value=value)
+ super().__setitem__(name, value)
+
+
+# The callables the environment itself puts in a template's globals (`range` is the sandbox's capped one,
+# `namespace` the data-only one).
+_JINJA_GLOBAL_CALLABLES: tuple[Callable[..., Any], ...] = (safe_range, dict, generate_lorem_ipsum, Cycler, Joiner, DataNamespace)
+
+# Instances of Jinja's runtime a template calls directly: `macro()`, `caller()`, a recursive `loop()`,
+# `self.block()` and `super()`, `joiner()`. Calling an undefined value is allowed so that it keeps
+# failing as an undefined value rather than as a refusal.
+_JINJA_CALLABLE_INSTANCE_TYPES: tuple[type, ...] = (Macro, LoopContext, BlockReference, Joiner, Undefined)
+
+# Instances of Jinja's runtime whose methods a template calls: `loop.cycle()`, `loop.changed()`,
+# `cycler.next()`, `cycler.reset()`.
+_JINJA_METHOD_OWNER_TYPES: tuple[type, ...] = (LoopContext, Cycler, BlockReference)
+
+# The methods that change a mutable plain value in place, listed here rather than taken from Jinja's
+# `modifies_known_mutable`, whose list misses `set.intersection_update`. The test suite checks this list
+# against every public method of each type, so a method a later Python adds cannot slip through.
+_MUTATING_METHOD_NAMES: dict[type, frozenset[str]] = {
+ list: frozenset({"append", "clear", "extend", "insert", "pop", "remove", "reverse", "sort"}),
+ dict: frozenset({"clear", "pop", "popitem", "setdefault", "update"}),
+ set: frozenset({"add", "clear", "difference_update", "discard", "intersection_update", "pop", "remove", "symmetric_difference_update", "update"}),
+}
+
+_MISSING = object()
+
+
+class _SandboxedStrFormat:
+ """The `str.format` or `str.format_map` of a string, routed through the sandbox's safe formatter.
+
+ Jinja builds this wrapper when a template reads `format` on a string, so that the replacement
+ fields of the format string (`{0.name}`, `{0[key]}`) go through the environment's own attribute
+ and item checks. Wrapping it in a type of its own lets the call policy recognise it by type,
+ while the raw `str.format` stays refused.
+ """
+
+ __slots__ = ("_format",)
+
+ def __init__(self, format_function: Callable[..., str]) -> None:
+ self._format = format_function
+
+ def __call__(self, *args: Any, **kwargs: Any) -> str:
+ return self._format(*args, **kwargs)
+
+
+def _is_private_name(*, name: str) -> bool:
+ return name.startswith("_")
+
+
+def _declares_private_name(*, obj: object, name: str) -> bool:
+ surface = get_template_surface(obj)
+ return surface is not None and name in surface.private_names
+
+
+def _is_jinja_runtime_callable(*, obj: object) -> bool:
+ if isinstance(obj, _JINJA_CALLABLE_INSTANCE_TYPES):
+ return True
+ if any(obj is jinja_global for jinja_global in _JINJA_GLOBAL_CALLABLES):
+ return True
+ if isinstance(obj, types.MethodType):
+ bound_to = obj.__self__
+ return not isinstance(bound_to, type) and isinstance(bound_to, _JINJA_METHOD_OWNER_TYPES)
+ return False
+
+
+def _is_plain_value_method(*, obj: object) -> bool:
+ """Whether `obj` is a method a plain value type defines, bound to an instance of that type.
+
+ The binding has to be to an instance, so a class method reached through an instance
+ (`created_at.now()`, which reads the clock) is refused. The method has to be the plain type's own,
+ so a subclass (a `StrEnum` member is a `str`) cannot add a callable method or override one.
+ """
+ if not isinstance(obj, (types.BuiltinMethodType, types.MethodType)):
+ return False
+ bound_to: object = getattr(obj, "__self__", None)
+ if bound_to is None or isinstance(bound_to, (type, types.ModuleType)):
+ return False
+ plain_type = next((klass for klass in type(bound_to).__mro__ if klass in _PLAIN_VALUE_TYPES), None)
+ if plain_type is None:
+ return False
+ name = obj.__name__
+ if isinstance(bound_to, str) and name in {"format", "format_map"}:
+ # Only the sandbox's own wrapper formats a string: the raw method would resolve `{0.__class__}`.
+ return False
+ if name in _MUTATING_METHOD_NAMES.get(plain_type, frozenset()):
+ return False
+ plain_member = inspect.getattr_static(plain_type, name, _MISSING)
+ return plain_member is not _MISSING and inspect.getattr_static(type(bound_to), name, _MISSING) is plain_member
+
+
+def _is_declared_template_method(*, obj: object) -> bool:
+ """Whether `obj` is a method the type of its instance declares in its template surface."""
+ if not isinstance(obj, types.MethodType):
+ return False
+ bound_to = obj.__self__
+ if isinstance(bound_to, type):
+ return False
+ surface = get_template_surface(bound_to)
+ if surface is None or obj.__name__ not in surface.callable_names:
+ return False
+ return inspect.getattr_static(type(bound_to), obj.__name__, _MISSING) is obj.__func__
+
+
+def _describe_callable(*, obj: object) -> str:
+ """Name a refused callable by what it is and what it was reached on, never by its value's repr."""
+ if isinstance(obj, (types.BuiltinMethodType, types.MethodType)):
+ name = obj.__name__
+ bound_to: object = getattr(obj, "__self__", None)
+ if isinstance(bound_to, type):
+ return f"the method '{name}' of the class '{bound_to.__name__}'"
+ if bound_to is None or isinstance(bound_to, types.ModuleType):
+ return f"the function '{name}'"
+ return f"the method '{name}' of a '{type(bound_to).__name__}' value"
+ if isinstance(obj, type):
+ return f"the class '{obj.__name__}'"
+ if isinstance(obj, types.FunctionType):
+ return f"the function '{obj.__name__}'"
+ return f"a '{type(obj).__name__}' value"
+
+
+class PipelexTemplateEnvironment(ImmutableSandboxedEnvironment):
+ """The Jinja2 environment every Pipelex template renders under. The module docstring states its policy."""
+
+ def __init__(self, *args: Any, **kwargs: Any) -> None:
+ super().__init__(*args, **kwargs)
+ self.globals["namespace"] = DataNamespace
+
+ @override
+ def is_safe_attribute(self, obj: Any, attr: str, value: Any) -> bool:
+ if _is_private_name(name=attr) and _declares_private_name(obj=obj, name=attr):
+ return True
+ return super().is_safe_attribute(obj, attr, value)
+
+ @override
+ def is_safe_callable(self, obj: Any) -> bool:
+ if not super().is_safe_callable(obj):
+ return False
+ return (
+ isinstance(obj, _SandboxedStrFormat)
+ or _is_jinja_runtime_callable(obj=obj)
+ or _is_plain_value_method(obj=obj)
+ or _is_declared_template_method(obj=obj)
+ )
+
+ @override
+ def getattr(self, obj: Any, attribute: str) -> Any:
+ # Refuse before the lookup, so an undeclared private name never runs a property or a
+ # `__getattr__`, and never reaches Jinja's fallback to `obj[attribute]`, which it does not check.
+ if _is_private_name(name=attribute) and not isinstance(obj, Undefined) and not _declares_private_name(obj=obj, name=attribute):
+ self.unsafe_undefined(obj, attribute)
+ return super().getattr(obj, attribute)
+
+ @override
+ def getitem(self, obj: Any, argument: Any) -> Any:
+ # Jinja tries `obj[argument]` first and checks the name only when that fails, so an object whose
+ # `__getitem__` answers any key would hand over what a dot could not: refuse the name up front.
+ # A plain dict is the exception: its items are data, and a key it does not hold falls back to
+ # an attribute read, which `is_safe_attribute` refuses for every underscore name.
+ if (
+ isinstance(argument, str)
+ and _is_private_name(name=argument)
+ and type(obj) is not dict
+ and not isinstance(obj, Undefined)
+ and not _declares_private_name(obj=obj, name=argument)
+ ):
+ self.unsafe_undefined(obj, argument)
+ return super().getitem(obj, argument)
+
+ @override
+ def unsafe_undefined(self, obj: Any, attribute: str) -> NoReturn:
+ msg = f"A template may not read '{attribute}' on a '{type(obj).__name__}' value."
+ raise SecurityError(msg)
+
+ @override
+ def wrap_str_format(self, value: Any) -> Callable[..., str] | None:
+ format_function = super().wrap_str_format(value)
+ if format_function is None:
+ return None
+ return _SandboxedStrFormat(format_function)
+
+ @override
+ def call(self, context: Context, obj: Any, /, *args: Any, **kwargs: Any) -> Any:
+ if not self.is_safe_callable(obj):
+ msg = f"A template may not call {_describe_callable(obj=obj)}: templates read data and call methods of plain values only."
+ raise SecurityError(msg)
+ return context.call(obj, *args, **kwargs)
diff --git a/pipelex/tools/jinja2/jinja2_with_images_filter.py b/pipelex/tools/jinja2/jinja2_with_images_filter.py
index a6f6b0819..6be1475fb 100644
--- a/pipelex/tools/jinja2/jinja2_with_images_filter.py
+++ b/pipelex/tools/jinja2/jinja2_with_images_filter.py
@@ -10,6 +10,7 @@ from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.image_renderable import ImageRenderable
from pipelex.tools.jinja2.jinja2_filters import require_templating_style_value
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
+from pipelex.tools.jinja2.renderable_dispatch import type_implements
from pipelex.tools.templating.text_format import TextFormat
@@ -57,8 +58,9 @@ def with_images(context: Context, value: Any, _: Any = None) -> str:
# Get text format from context — no fallback, same as the tag and format filters
text_format = TextFormat(require_templating_style_value(context=context, jinja2_context_key=Jinja2ContextKey.TEXT_FORMAT))
- # Protocol-based rendering
- if isinstance(value, ImageRenderable):
+ # Protocol-based rendering, licensed by the value's type: a template can build a namespace holding a
+ # `render_with_images` callable, which passes the isinstance check on Python 3.11.
+ if isinstance(value, ImageRenderable) and type_implements(value=value, protocol=ImageRenderable):
return value.render_with_images(registry=registry, text_format=text_format)
# Handle plain lists/tuples (structural types that may contain ImageRenderable items)
@@ -93,7 +95,7 @@ def _render_sequence_with_images(
"""
parts: list[str] = []
for item in sequence:
- if isinstance(item, ImageRenderable):
+ if isinstance(item, ImageRenderable) and type_implements(value=item, protocol=ImageRenderable):
rendered = item.render_with_images(registry=registry, text_format=text_format)
else:
rendered = str(item)
diff --git a/pipelex/tools/jinja2/renderable_dispatch.py b/pipelex/tools/jinja2/renderable_dispatch.py
new file mode 100644
index 000000000..79849c855
--- /dev/null
+++ b/pipelex/tools/jinja2/renderable_dispatch.py
@@ -0,0 +1,21 @@
+"""Decide from a value's type whether a filter may call the rendering method a protocol names.
+
+The `with_images`, `format` and `tag` filters call a method on the value they are handed, and the template
+sandbox never sees that call. A runtime-checkable Protocol cannot license it on its own: on Python 3.11,
+`isinstance` against one is a `hasattr` test, which a template satisfies with
+`namespace(render_with_images=...)`, and the filter would then call whatever callable the template put
+there. So a filter also requires the value's class to define every member of the protocol, looked up with
+`inspect.getattr_static` on the type: a template can build instances, but never a class.
+"""
+
+import inspect
+
+from typing_extensions import get_protocol_members
+
+_ABSENT = object()
+
+
+def type_implements(*, value: object, protocol: type) -> bool:
+ """Whether the class of `value` defines every member of `protocol`, read from the type and never from the instance."""
+ value_type = type(value)
+ return all(inspect.getattr_static(value_type, member, _ABSENT) is not _ABSENT for member in get_protocol_members(protocol))
diff --git a/pipelex/tools/jinja2/template_surface.py b/pipelex/tools/jinja2/template_surface.py
new file mode 100644
index 000000000..58f1ba2ea
--- /dev/null
+++ b/pipelex/tools/jinja2/template_surface.py
@@ -0,0 +1,52 @@
+"""The template surface: what a type declares a template may do with its instances beyond reading public data.
+
+Templates render under `PipelexTemplateEnvironment`, whose policy lets a template read public data
+and call methods of plain values (strings, numbers, dates, containers) and nothing else. A type
+whose instances templates need to call methods on, or read an underscore-prefixed name of, declares
+exactly those names as its template surface, the way `StuffArtefact` declares its dict-like
+accessors and its metadata fields.
+
+The surface is read from the type, never from the instance: `StuffArtefact` answers attribute
+lookups with content fields first, so an instance lookup would let a content field named like the
+declaration replace it. The declaration's name is a dunder for the same reason, since no content
+field can be spelled that way.
+
+This module lives in `tools/` and imports nothing from `core/`, which is the layering the other
+template protocols (`TagRenderable`, `ImageRenderable`) follow.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic.dataclasses import dataclass
+
+TEMPLATE_SURFACE_ATTRIBUTE = "__template_surface__"
+
+
+@dataclass(frozen=True)
+class TemplateSurface:
+ """What a template may do with an instance of the declaring type, beyond reading public data.
+
+ Attributes:
+ callable_names: The methods a template may call on an instance.
+ private_names: The underscore-prefixed names a template may read, with a dot or with brackets.
+ """
+
+ callable_names: frozenset[str]
+ private_names: frozenset[str]
+
+ def __post_init__(self) -> None:
+ # A dunder is never data: declaring one would reopen the path to Python internals.
+ for name in self.private_names:
+ if not name.startswith("_") or name.startswith("__"):
+ msg = f"A template surface's private names start with a single underscore, and '{name}' does not."
+ raise ValueError(msg)
+
+
+def get_template_surface(obj: object) -> TemplateSurface | None:
+ """Return the template surface the type of `obj` declares, or None when it declares none."""
+ surface: Any = getattr(type(obj), TEMPLATE_SURFACE_ATTRIBUTE, None)
+ if isinstance(surface, TemplateSurface):
+ return surface
+ return None
diff --git a/pipelex/tools/misc/string_utils.py b/pipelex/tools/misc/string_utils.py
index 80d673173..79e448ea2 100644
--- a/pipelex/tools/misc/string_utils.py
+++ b/pipelex/tools/misc/string_utils.py
@@ -352,6 +352,22 @@ def get_root_from_dotted_path(dotted_path: str) -> str:
return dotted_path.split(".", 1)[0]
+def find_private_path_segment(*, path: str) -> str | None:
+ """Return the first segment of a dotted path that starts with an underscore, or None.
+
+ A method author writes dotted paths (a construct field's `from`, a batch's list, an image reference)
+ that the runtime walks with `getattr`. A segment starting with an underscore is how such a walk
+ reaches Python internals (`__class__.__init__.__globals__`), so every such walk refuses one.
+
+ Examples:
+ >>> find_private_path_segment(path="deal.customer_name") is None
+ True
+ >>> find_private_path_segment(path="note.__class__.__init__")
+ '__class__'
+ """
+ return next((segment for segment in path.split(".") if segment.startswith("_")), None)
+
+
def pluralize(*, count: int, singular: str, plural: str | None = None) -> str:
"""Pick the singular or plural form of a word based on a count.
diff --git a/pipelex/validation_error_types.py b/pipelex/validation_error_types.py
index 94e116da1..9c77df7a8 100644
--- a/pipelex/validation_error_types.py
+++ b/pipelex/validation_error_types.py
@@ -71,6 +71,11 @@ class PipeValidationErrorType(StrEnum):
OPTIONAL_INPUT_UNGUARDED = "optional_input_unguarded"
OPTIONAL_BRANCH_REQUIRED_FIELD = "optional_branch_required_field"
+ # A template reads a name starting with an underscore that is not one of an input's declared
+ # metadata fields (`_stuff_name`, `_content_class`, `_concept_code`, `_stuff_code`). The template
+ # sandbox refuses such a read at render time; the load-time lint names the pipe and the template.
+ TEMPLATE_PRIVATE_NAME = "template_private_name"
+
# Advisory-only (rides the validation report's `warnings` array, never raised as an error):
# a `!` (force) input whose slot is guaranteed present in every analyzed flow — the
# assertion can never fire.
@@ -122,6 +127,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_NOT_HANDLED
| PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.TEMPLATE_PRIVATE_NAME
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
| PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
@@ -153,6 +159,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_NOT_HANDLED
| PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.TEMPLATE_PRIVATE_NAME
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
| PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
@@ -191,6 +198,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_NOT_HANDLED
| PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.TEMPLATE_PRIVATE_NAME
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
| PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
@@ -224,6 +232,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_NOT_HANDLED
| PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.TEMPLATE_PRIVATE_NAME
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
| PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
@@ -260,6 +269,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_NOT_HANDLED
| PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.TEMPLATE_PRIVATE_NAME
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
| PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
@@ -293,6 +303,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.OPTIONAL_NOT_HANDLED
| PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
| PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.TEMPLATE_PRIVATE_NAME
| PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
| PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
| PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
diff --git a/pyproject.toml b/pyproject.toml
index 51a148c68..fb9a11929 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -27,7 +27,7 @@ dependencies = [
"httpx>=0.23.0,<1.0.0",
"idna>=3.15",
"instructor>=1.17.0,<2.0.0", # 1.16+ supports mistralai 2.x; 2.0 is a planned major we have not assessed
- "jinja2>=3.1.4",
+ "jinja2>=3.1.6",
"json2html>=1.3.0",
"kajson==0.7.1",
"markdown>=3.6",
diff --git a/subject_grants.toml b/subject_grants.toml
index 315e5c9af..bb3120dae 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -6084,6 +6084,10 @@ rationale = "Predicate on the key; single operand."
param = "sequence"
rationale = "Jinja op on the sequence; single operand (context keyword-only)."
+["pipelex/tools/jinja2/template_surface.py::get_template_surface"]
+param = "obj"
+rationale = "Reads as get the template surface of this value; the value is the single obvious operand."
+
["pipelex/tools/log/log.py::Log._should_ignore"]
param = "problem_id"
rationale = "Predicate on the problem id; single operand."
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 2a4d3b0be..59e384d0f 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -138,6 +138,7 @@ Jinja2ContextError | Jinja 2 context | https://docs.pipelex.com/latest/errors/ji
Jinja2DetectVariablesError | Jinja 2 detect variables | https://docs.pipelex.com/latest/errors/jinja2-detect-variables-error/
Jinja2StuffError | Jinja 2 stuff | https://docs.pipelex.com/latest/errors/jinja2-stuff-error/
Jinja2TemplateRenderError | Jinja 2 template render | https://docs.pipelex.com/latest/errors/jinja2-template-render-error/
+Jinja2TemplateSecurityError | Jinja 2 template security | https://docs.pipelex.com/latest/errors/jinja2-template-security-error/
Jinja2TemplateSyntaxError | Jinja 2 template syntax | https://docs.pipelex.com/latest/errors/jinja2-template-syntax-error/
JobMetadataError | Job metadata | https://docs.pipelex.com/latest/errors/job-metadata-error/
JsonTypeError | Json type | https://docs.pipelex.com/latest/errors/json-type-error/
diff --git a/tests/integration/pipelex/pipes/templates/test_template_private_name_lint.py b/tests/integration/pipelex/pipes/templates/test_template_private_name_lint.py
new file mode 100644
index 000000000..d9973c143
--- /dev/null
+++ b/tests/integration/pipelex/pipes/templates/test_template_private_name_lint.py
@@ -0,0 +1,219 @@
+"""Template private-name lint: a template that reads a name starting with an underscore, other than an
+input's metadata fields, is a typed validation error (`TEMPLATE_PRIVATE_NAME`) naming the pipe and the
+template. The template sandbox refuses the same reads at render time; this lint locates them at load.
+"""
+
+from typing import Callable
+
+import pytest
+from pydantic import ValidationError
+
+from pipelex.base_exceptions import ValidationErrorCategory
+from pipelex.core.pipes.exceptions import PipeValidationError
+from pipelex.mthds_parsing.handle_pipe_errors import extract_wrapped_pipe_validation_error
+from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
+from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
+from pipelex.pipe_machinery.pipe_factory import PipeFactory
+from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
+from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
+from pipelex.pipe_operators.img_gen.pipe_img_gen import PipeImgGen
+from pipelex.pipe_operators.img_gen.pipe_img_gen_blueprint import PipeImgGenBlueprint
+from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
+from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
+from pipelex.pipe_operators.search.pipe_search import PipeSearch
+from pipelex.pipe_operators.search.pipe_search_blueprint import PipeSearchBlueprint
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.validation_error_types import PipeValidationErrorType
+
+_DOMAIN_CODE = "test_template_private_name_lint"
+
+_CONSTRUCT_MTHDS = """
+domain = "test_template_private_name_construct"
+main_pipe = "file_the_receipt"
+
+[concept.FiledReceipt]
+description = "A receipt filed under the name it came in with"
+
+[concept.FiledReceipt.structure]
+filed_under = { type = "text", description = "The name the receipt was filed under", required = true }
+
+[pipe.file_the_receipt]
+type = "PipeCompose"
+description = "File a receipt under the name it came in with"
+inputs = { receipt = "Text" }
+output = "FiledReceipt"
+
+[pipe.file_the_receipt.construct]
+filed_under = { template = "{{ receipt._stuff.stuff_name }}" }
+"""
+
+_CONSTRUCT_FROM_DUNDER_MTHDS = """
+domain = "test_construct_from_private_segment"
+main_pipe = "copy_the_environment"
+
+[concept.Note]
+description = "A note"
+
+[concept.Note.structure]
+body = { type = "text", description = "The body", required = true }
+
+[concept.Copied]
+description = "Whatever a path reached"
+
+[concept.Copied.structure]
+data = { type = "dict", key_type = "text", value_type = "text", description = "Anything", required = true }
+
+[pipe.copy_the_environment]
+type = "PipeCompose"
+description = "Walk from an input into the process environment"
+inputs = { note = "Note" }
+output = "Copied"
+
+[pipe.copy_the_environment.construct]
+data = { from = "note.__class__.__init__.__globals__.sys.modules.os.environ" }
+"""
+
+
+def _make_pipe_llm(*, prompt: str, system_prompt: str | None = None) -> PipeLLM:
+ return PipeFactory[PipeLLM].make_from_blueprint(
+ domain_code=_DOMAIN_CODE,
+ pipe_code="private_name_llm",
+ blueprint=PipeLLMBlueprint(
+ description="Private-name lint test pipe",
+ inputs={"contract": "Text"},
+ output="Text",
+ prompt=prompt,
+ system_prompt=system_prompt,
+ ),
+ )
+
+
+def _assert_private_name_error(error: ValidationError, *, pipe_code: str, refused_name: str, template_label: str) -> PipeValidationError:
+ wrapped = extract_wrapped_pipe_validation_error(error.errors()[0])
+ assert wrapped is not None, "expected a wrapped PipeValidationError"
+ assert wrapped.error_type == PipeValidationErrorType.TEMPLATE_PRIVATE_NAME
+ assert wrapped.pipe_code == pipe_code
+ assert f"'{refused_name}'" in str(wrapped)
+ assert f"the {template_label} of pipe '{pipe_code}'" in str(wrapped)
+ return wrapped
+
+
+class TestTemplatePrivateNameLint:
+ @pytest.mark.parametrize(
+ ("topic", "prompt", "refused_name"),
+ [
+ ("raw_stuff_by_dot", "Summarise {{ contract._stuff }}", "_stuff"),
+ ("raw_content_by_dot", "Summarise {{ contract._content }}", "_content"),
+ ("dunder_chain", "{{ contract.__class__.__mro__ }} $contract", "__class__"),
+ ],
+ )
+ def test_prompt_reading_a_private_name_is_rejected(self, topic: str, prompt: str, refused_name: str, load_empty_library: Callable[[], None]):
+ load_empty_library()
+ with pytest.raises(ValidationError) as exc_info:
+ _make_pipe_llm(prompt=prompt)
+ wrapped = _assert_private_name_error(exc_info.value, pipe_code="private_name_llm", refused_name=refused_name, template_label="prompt")
+ assert "_stuff_name" in str(wrapped), f"{topic}: the message lists the metadata fields a template may read"
+
+ def test_system_prompt_is_linted(self, load_empty_library: Callable[[], None]):
+ load_empty_library()
+ with pytest.raises(ValidationError) as exc_info:
+ _make_pipe_llm(prompt="Summarise $contract", system_prompt="You know {{ contract._stuff }}")
+ _assert_private_name_error(exc_info.value, pipe_code="private_name_llm", refused_name="_stuff", template_label="system_prompt")
+
+ def test_bracketed_key_is_left_to_the_render(self, load_empty_library: Callable[[], None]):
+ """A bracketed key may be a plain dict's data (`record['_id']`), which only the render can tell."""
+ load_empty_library()
+ pipe_llm = _make_pipe_llm(prompt="Summarise {{ contract['_id'] }} $contract")
+ assert pipe_llm.code == "private_name_llm"
+
+ def test_metadata_fields_are_accepted(self, load_empty_library: Callable[[], None]):
+ load_empty_library()
+ pipe_llm = _make_pipe_llm(
+ prompt="{{ contract._stuff_name }} {{ contract._content_class }} {{ contract._concept_code }} {{ contract._stuff_code }} $contract",
+ )
+ assert pipe_llm.code == "private_name_llm"
+
+ def test_condition_expression_is_linted(self, load_empty_library: Callable[[], None]):
+ load_empty_library()
+ with pytest.raises(ValidationError) as exc_info:
+ PipeFactory[PipeCondition].make_from_blueprint(
+ domain_code=_DOMAIN_CODE,
+ pipe_code="private_name_condition",
+ blueprint=PipeConditionBlueprint(
+ description="Condition reaching for the wrapped stuff",
+ inputs={"verdict": "Text"},
+ output="Text",
+ expression="verdict._stuff.stuff_name",
+ outcomes={"yes": "continue"},
+ default_outcome="continue",
+ ),
+ )
+ _assert_private_name_error(exc_info.value, pipe_code="private_name_condition", refused_name="_stuff", template_label="expression")
+
+ def test_compose_template_is_linted(self, load_empty_library: Callable[[], None]):
+ load_empty_library()
+ with pytest.raises(ValidationError) as exc_info:
+ PipeFactory[PipeCompose].make_from_blueprint(
+ domain_code=_DOMAIN_CODE,
+ pipe_code="private_name_compose",
+ blueprint=PipeComposeBlueprint(
+ description="Compose reaching for the raw content",
+ inputs={"note": "Text"},
+ output="Text",
+ template="note: {{ note._content }}",
+ ),
+ )
+ _assert_private_name_error(exc_info.value, pipe_code="private_name_compose", refused_name="_content", template_label="template")
+
+ def test_search_prompt_is_linted(self, load_empty_library: Callable[[], None]):
+ load_empty_library()
+ with pytest.raises(ValidationError) as exc_info:
+ PipeFactory[PipeSearch].make_from_blueprint(
+ domain_code=_DOMAIN_CODE,
+ pipe_code="private_name_search",
+ blueprint=PipeSearchBlueprint(
+ description="Search reaching for the wrapped stuff",
+ inputs={"topic": "Text"},
+ output="SearchResult[]",
+ prompt="latest news about {{ topic._stuff }}",
+ ),
+ )
+ _assert_private_name_error(exc_info.value, pipe_code="private_name_search", refused_name="_stuff", template_label="prompt")
+
+ def test_img_gen_negative_prompt_is_linted(self, load_empty_library: Callable[[], None]):
+ load_empty_library()
+ with pytest.raises(ValidationError) as exc_info:
+ PipeFactory[PipeImgGen].make_from_blueprint(
+ domain_code=_DOMAIN_CODE,
+ pipe_code="private_name_img_gen",
+ blueprint=PipeImgGenBlueprint(
+ description="Image prompt reaching for the wrapped stuff",
+ inputs={"style": "Text"},
+ output="Image",
+ prompt="a landscape in the style of $style",
+ negative_prompt="nothing like {{ style._stuff }}",
+ ),
+ )
+ _assert_private_name_error(exc_info.value, pipe_code="private_name_img_gen", refused_name="_stuff", template_label="negative_prompt")
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_construct_field_template_is_linted(self, load_empty_library: Callable[[], None]):
+ load_empty_library()
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[_CONSTRUCT_MTHDS])
+ items = exc_info.value.to_error_report().validation_errors or []
+ assert [(item.category, item.error_type) for item in items] == [
+ (ValidationErrorCategory.PIPE_VALIDATION, PipeValidationErrorType.TEMPLATE_PRIVATE_NAME)
+ ]
+ assert "construct field 'filed_under'" in (items[0].message or "")
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_construct_from_path_with_a_private_segment_is_rejected(self, load_empty_library: Callable[[], None]):
+ """A `from` path is walked with getattr at run time: a dunder segment would copy the process environment."""
+ load_empty_library()
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[_CONSTRUCT_FROM_DUNDER_MTHDS])
+ items = exc_info.value.to_error_report().validation_errors or []
+ assert len(items) == 1
+ assert "reads '__class__', a name starting with an underscore" in (items[0].message or "")
diff --git a/tests/unit/pipelex/core/memory/test_working_memory_generate_context.py b/tests/unit/pipelex/core/memory/test_working_memory_generate_context.py
index 82c41195e..3213f533f 100644
--- a/tests/unit/pipelex/core/memory/test_working_memory_generate_context.py
+++ b/tests/unit/pipelex/core/memory/test_working_memory_generate_context.py
@@ -4,7 +4,8 @@ from pipelex.core.stuffs.html_content import HtmlContent
from pipelex.core.stuffs.image_content import ImageContent
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.number_content import NumberContent
-from pipelex.core.stuffs.stuff_artefact import BaseStuffArtefactField, StuffArtefact
+from pipelex.core.stuffs.stuff_artefact import BaseStuffArtefactField, StuffArtefact, unwrap_stuff_artefact
+from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.text_and_images_content import TextAndImagesContent
from pipelex.core.stuffs.text_content import TextContent
from tests.cases.documents import DocumentTestCases
@@ -35,11 +36,12 @@ class TestWorkingMemoryGenerateContext:
# Verify artefact structure
artefact = context["sample_text"]
assert isinstance(artefact, StuffArtefact)
- assert BaseStuffArtefactField.CONTENT in artefact
- assert isinstance(artefact[BaseStuffArtefactField.CONTENT], TextContent)
+ assert BaseStuffArtefactField.CONTENT_CLASS in artefact
+ content = unwrap_stuff_artefact(artefact=artefact).content
+ assert isinstance(content, TextContent)
# Verify actual content value
- assert artefact[BaseStuffArtefactField.CONTENT].text == TestWorkingMemoryData.SAMPLE_TEXT
+ assert content.text == TestWorkingMemoryData.SAMPLE_TEXT
# Verify MAIN_STUFF_NAME points to the same artefact
assert context[MAIN_STUFF_NAME] is context["sample_text"]
@@ -56,10 +58,10 @@ class TestWorkingMemoryGenerateContext:
# Verify artefact structure
artefact = context["document_file"]
assert isinstance(artefact, StuffArtefact)
- assert BaseStuffArtefactField.CONTENT in artefact
+ assert BaseStuffArtefactField.CONTENT_CLASS in artefact
# Verify actual content value
- assert artefact[BaseStuffArtefactField.CONTENT].url == DocumentTestCases.PDF_FILE_URL_1
+ assert unwrap_stuff_artefact(artefact=artefact).as_document.url == DocumentTestCases.PDF_FILE_URL_1
# Verify MAIN_STUFF_NAME points to the same artefact
assert context[MAIN_STUFF_NAME] is context["document_file"]
@@ -76,11 +78,12 @@ class TestWorkingMemoryGenerateContext:
# Verify artefact structure
artefact = context["sample_image"]
assert isinstance(artefact, StuffArtefact)
- assert BaseStuffArtefactField.CONTENT in artefact
- assert isinstance(artefact[BaseStuffArtefactField.CONTENT], ImageContent)
+ assert BaseStuffArtefactField.CONTENT_CLASS in artefact
+ content = unwrap_stuff_artefact(artefact=artefact).content
+ assert isinstance(content, ImageContent)
# Verify actual content value
- assert artefact[BaseStuffArtefactField.CONTENT].url == ImageTestCases.IMAGE_FILE_PATH_PNG_1
+ assert content.url == ImageTestCases.IMAGE_FILE_PATH_PNG_1
# Verify MAIN_STUFF_NAME points to the same artefact
assert context[MAIN_STUFF_NAME] is context["sample_image"]
@@ -101,17 +104,20 @@ class TestWorkingMemoryGenerateContext:
assert isinstance(context["question"], StuffArtefact)
assert isinstance(context["document"], StuffArtefact)
assert isinstance(context["diagram"], StuffArtefact)
- assert BaseStuffArtefactField.CONTENT in context["question"]
- assert BaseStuffArtefactField.CONTENT in context["document"]
- assert BaseStuffArtefactField.CONTENT in context["diagram"]
+ assert BaseStuffArtefactField.CONTENT_CLASS in context["question"]
+ assert BaseStuffArtefactField.CONTENT_CLASS in context["document"]
+ assert BaseStuffArtefactField.CONTENT_CLASS in context["diagram"]
# Verify actual content values
- assert isinstance(context["question"][BaseStuffArtefactField.CONTENT], TextContent)
- assert context["question"][BaseStuffArtefactField.CONTENT].text == "What are the aerodynamic features?"
- assert isinstance(context["document"][BaseStuffArtefactField.CONTENT], TextContent)
- assert context["document"][BaseStuffArtefactField.CONTENT].text == TestWorkingMemoryData.SAMPLE_TEXT
- assert isinstance(context["diagram"][BaseStuffArtefactField.CONTENT], ImageContent)
- assert context["diagram"][BaseStuffArtefactField.CONTENT].url == ImageTestCases.IMAGE_FILE_PATH_PNG_1
+ question_content = unwrap_stuff_artefact(artefact=context["question"]).content
+ assert isinstance(question_content, TextContent)
+ assert question_content.text == "What are the aerodynamic features?"
+ document_content = unwrap_stuff_artefact(artefact=context["document"]).content
+ assert isinstance(document_content, TextContent)
+ assert document_content.text == TestWorkingMemoryData.SAMPLE_TEXT
+ diagram_content = unwrap_stuff_artefact(artefact=context["diagram"]).content
+ assert isinstance(diagram_content, ImageContent)
+ assert diagram_content.url == ImageTestCases.IMAGE_FILE_PATH_PNG_1
# Verify MAIN_STUFF_NAME points to document (main_name="document" in fixture)
assert context[MAIN_STUFF_NAME] is context["document"]
@@ -130,10 +136,12 @@ class TestWorkingMemoryGenerateContext:
assert MAIN_STUFF_NAME in context
# Verify actual content values
- assert isinstance(context["primary_text"][BaseStuffArtefactField.CONTENT], TextContent)
- assert context["primary_text"][BaseStuffArtefactField.CONTENT].text == "Primary content"
- assert isinstance(context["secondary_text"][BaseStuffArtefactField.CONTENT], TextContent)
- assert context["secondary_text"][BaseStuffArtefactField.CONTENT].text == "Secondary content"
+ primary_text_content = unwrap_stuff_artefact(artefact=context["primary_text"]).content
+ assert isinstance(primary_text_content, TextContent)
+ assert primary_text_content.text == "Primary content"
+ secondary_text_content = unwrap_stuff_artefact(artefact=context["secondary_text"]).content
+ assert isinstance(secondary_text_content, TextContent)
+ assert secondary_text_content.text == "Secondary content"
# Verify aliases point to the same artefact objects (using 'is')
assert context["main_text"] is context["primary_text"]
@@ -152,11 +160,12 @@ class TestWorkingMemoryGenerateContext:
# Verify artefact structure
artefact = context["mixed_list"]
assert isinstance(artefact, StuffArtefact)
- assert BaseStuffArtefactField.CONTENT in artefact
- assert isinstance(artefact[BaseStuffArtefactField.CONTENT], ListContent)
+ assert BaseStuffArtefactField.CONTENT_CLASS in artefact
+ content = unwrap_stuff_artefact(artefact=artefact).content
+ assert isinstance(content, ListContent)
# Verify actual list content values
- list_content = artefact[BaseStuffArtefactField.CONTENT]
+ list_content = unwrap_stuff_artefact(artefact=artefact).as_list_of_fixed_content_type(item_type=StuffContent)
assert len(list_content.items) == 3
assert isinstance(list_content.items[0], TextContent)
assert list_content.items[0].text == "The quick brown fox jumps over the lazy dog"
@@ -177,11 +186,11 @@ class TestWorkingMemoryGenerateContext:
# Verify artefact structure
artefact = context["project_overview"]
assert isinstance(artefact, StuffArtefact)
- assert BaseStuffArtefactField.CONTENT in artefact
- assert isinstance(artefact[BaseStuffArtefactField.CONTENT], TextAndImagesContent)
+ assert BaseStuffArtefactField.CONTENT_CLASS in artefact
+ content = unwrap_stuff_artefact(artefact=artefact).content
+ assert isinstance(content, TextAndImagesContent)
# Verify actual content values
- content = artefact[BaseStuffArtefactField.CONTENT]
assert content.text is not None
assert content.text.text == "Project overview with diagrams"
assert content.images is not None
@@ -201,11 +210,11 @@ class TestWorkingMemoryGenerateContext:
# Verify artefact structure
artefact = context["test_report"]
assert isinstance(artefact, StuffArtefact)
- assert BaseStuffArtefactField.CONTENT in artefact
- assert isinstance(artefact[BaseStuffArtefactField.CONTENT], HtmlContent)
+ assert BaseStuffArtefactField.CONTENT_CLASS in artefact
+ content = unwrap_stuff_artefact(artefact=artefact).content
+ assert isinstance(content, HtmlContent)
# Verify actual content values
- content = artefact[BaseStuffArtefactField.CONTENT]
assert content.inner_html == "<h1>Test Report</h1><p>This is a <strong>test</strong> report.</p><ul><li>Item 1</li><li>Item 2</li></ul>"
assert content.css_class == "report-content"
@@ -221,11 +230,12 @@ class TestWorkingMemoryGenerateContext:
# Verify artefact structure
artefact = context["pi_value"]
assert isinstance(artefact, StuffArtefact)
- assert BaseStuffArtefactField.CONTENT in artefact
- assert isinstance(artefact[BaseStuffArtefactField.CONTENT], NumberContent)
+ assert BaseStuffArtefactField.CONTENT_CLASS in artefact
+ content = unwrap_stuff_artefact(artefact=artefact).content
+ assert isinstance(content, NumberContent)
# Verify actual content value
- assert artefact[BaseStuffArtefactField.CONTENT].number == 3.14159
+ assert content.number == 3.14159
def test_generate_context_artefact_independence(self, multiple_stuff_memory: WorkingMemory):
"""Test that each stuff generates independent artefacts."""
diff --git a/tests/unit/pipelex/core/memory/test_working_memory_typed_access.py b/tests/unit/pipelex/core/memory/test_working_memory_typed_access.py
index 7945c1b12..aaf6a7d70 100644
--- a/tests/unit/pipelex/core/memory/test_working_memory_typed_access.py
+++ b/tests/unit/pipelex/core/memory/test_working_memory_typed_access.py
@@ -161,6 +161,12 @@ class TestWorkingMemoryTypedAccess:
assert "sample_page.nonexistent_field" in str(exc_info.value)
+ @pytest.mark.parametrize("name", ["sample_page.__class__", "sample_page.text_and_images.__class__.__init__", "sample_page._private"])
+ def test_private_attribute_path_is_refused(self, nested_content_memory: WorkingMemory, name: str):
+ """The path is walked with attrgetter, so a segment starting with an underscore would reach Python internals."""
+ with pytest.raises(WorkingMemoryStuffAttributeNotFoundError, match="starts with an underscore"):
+ nested_content_memory.get_typed_object_or_attribute(name)
+
def test_nested_attribute_deep_not_found(self, nested_content_memory: WorkingMemory):
"""Test that accessing non-existent deeply nested attribute raises error."""
with pytest.raises(WorkingMemoryStuffAttributeNotFoundError) as exc_info:
diff --git a/tests/unit/pipelex/core/stuffs/test_stuff_artefact_template_surface.py b/tests/unit/pipelex/core/stuffs/test_stuff_artefact_template_surface.py
new file mode 100644
index 000000000..b04692bc6
--- /dev/null
+++ b/tests/unit/pipelex/core/stuffs/test_stuff_artefact_template_surface.py
@@ -0,0 +1,101 @@
+"""StuffArtefact's template surface: what a string key resolves to, and what it declares to the sandbox."""
+
+import pytest
+
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.stuffs.composite_content import CompositeContent
+from pipelex.core.stuffs.stuff import Stuff
+from pipelex.core.stuffs.stuff_artefact import BaseStuffArtefactField, StuffArtefact, unwrap_stuff_artefact
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.tools.jinja2.template_surface import get_template_surface
+
+
+def _make_artefact() -> StuffArtefact:
+ return StuffArtefact(
+ Stuff(
+ stuff_code="note_code",
+ stuff_name="note",
+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT),
+ content=TextContent(text="hello"),
+ )
+ )
+
+
+def _make_composite_artefact() -> StuffArtefact:
+ return StuffArtefact(
+ Stuff(
+ stuff_code="combo_code",
+ stuff_name="combo",
+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.COMPOSITE),
+ content=CompositeContent.model_validate(
+ {"summary": TextContent(text="S"), "title": TextContent(text="T"), "_hidden": TextContent(text="H")}
+ ),
+ )
+ )
+
+
+class TestStuffArtefactTemplateSurface:
+ def test_declares_its_accessors_and_metadata(self) -> None:
+ surface = get_template_surface(_make_artefact())
+ assert surface is not None
+ assert surface.callable_names == frozenset({"get", "iter_keys", "iter_items", "iter_values"})
+ assert surface.private_names == frozenset({"_stuff_name", "_content_class", "_concept_code", "_stuff_code"})
+
+ @pytest.mark.parametrize("key", ["_stuff", "_content", "__class__", "stuff", "get", "render_with_images", "missing"])
+ def test_bracket_key_resolves_only_to_fields_and_metadata(self, key: str) -> None:
+ with pytest.raises(KeyError):
+ _ = _make_artefact()[key]
+
+ @pytest.mark.parametrize("key", ["_stuff", "_content", "stuff", "iter_keys"])
+ def test_get_resolves_only_to_fields_and_metadata(self, key: str) -> None:
+ assert _make_artefact().get(key, default="absent") == "absent"
+
+ def test_bracket_key_reads_fields_and_metadata(self) -> None:
+ artefact = _make_artefact()
+ assert artefact["text"] == "hello"
+ assert artefact[BaseStuffArtefactField.STUFF_NAME] == "note"
+ assert artefact[BaseStuffArtefactField.CONTENT_CLASS] == "TextContent"
+ assert artefact[BaseStuffArtefactField.CONCEPT_CODE] == "Text"
+ assert artefact[BaseStuffArtefactField.STUFF_CODE] == "note_code"
+
+ def test_raw_content_is_not_a_key(self) -> None:
+ artefact = _make_artefact()
+ assert "_content" not in artefact
+ assert "_content" not in list(artefact.iter_keys())
+
+ def test_wrapped_stuff_is_not_an_attribute(self) -> None:
+ artefact = _make_artefact()
+ assert not hasattr(artefact, "stuff")
+ assert "stuff" not in artefact
+
+ def test_python_code_unwraps_the_stuff(self) -> None:
+ artefact = _make_artefact()
+ assert unwrap_stuff_artefact(artefact=artefact).content == TextContent(text="hello")
+
+ def test_composite_parts_are_fields(self) -> None:
+ """A Composite holds its parts as extra fields of the model: they resolve like declared fields."""
+ artefact = _make_composite_artefact()
+ assert artefact["summary"] == TextContent(text="S")
+ assert artefact.get("title") == TextContent(text="T")
+ assert "summary" in artefact
+ assert list(artefact.iter_keys())[:2] == ["summary", "title"]
+
+ def test_composite_part_named_like_a_pydantic_attribute_is_the_part(self) -> None:
+ artefact = StuffArtefact(
+ Stuff(
+ stuff_code="clash_code",
+ stuff_name="clash",
+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.COMPOSITE),
+ content=CompositeContent.model_validate({"model_extra": TextContent(text="E"), "model_dump": TextContent(text="D")}),
+ )
+ )
+ assert artefact["model_extra"] == TextContent(text="E")
+ assert artefact.get("model_dump") == TextContent(text="D")
+
+ def test_private_composite_part_is_not_a_field(self) -> None:
+ artefact = _make_composite_artefact()
+ assert "_hidden" not in artefact
+ assert "_hidden" not in list(artefact.iter_keys())
+ with pytest.raises(KeyError):
+ _ = artefact["_hidden"]
diff --git a/tests/unit/pipelex/pipe_operators/pipe_compose/test_construct_field_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_compose/test_construct_field_blueprint.py
index a1fa2cfc2..274f66bda 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_compose/test_construct_field_blueprint.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_compose/test_construct_field_blueprint.py
@@ -323,6 +323,19 @@ class TestConstructFieldBlueprintValidation:
with pytest.raises(ConstructFieldBlueprintTypeError, match="string path"):
ConstructFieldBlueprint.make_from_raw({"from": 123})
+ @pytest.mark.parametrize(
+ "from_path",
+ ["note.__class__.__init__.__globals__.sys.modules.os.environ", "note._stuff", "_private"],
+ )
+ def test_from_path_with_private_segment_raises_value_error(self, from_path: str):
+ """A 'from' path is walked with getattr at run time, so a segment starting with an underscore is refused at load."""
+ with pytest.raises(ConstructFieldBlueprintValueError, match="starting with an underscore"):
+ ConstructFieldBlueprint.make_from_raw({"from": from_path})
+
+ def test_list_to_dict_keyed_by_private_name_raises_value_error(self):
+ with pytest.raises(ConstructFieldBlueprintValueError, match="starting with an underscore"):
+ ConstructFieldBlueprint.make_from_raw({"from": "items", "list_to_dict_keyed_by": "__module__"})
+
def test_list_to_dict_keyed_by_not_string_raises_type_error(self):
"""'list_to_dict_keyed_by' value must be a string."""
with pytest.raises(ConstructFieldBlueprintTypeError, match="string attribute name"):
diff --git a/tests/unit/pipelex/tools/misc/test_string_utils.py b/tests/unit/pipelex/tools/misc/test_string_utils.py
index 70eddee36..f23268817 100644
--- a/tests/unit/pipelex/tools/misc/test_string_utils.py
+++ b/tests/unit/pipelex/tools/misc/test_string_utils.py
@@ -4,6 +4,7 @@ from pipelex.tools.misc.string_utils import (
camel_to_snake_case,
can_inject_text,
count_with_noun,
+ find_private_path_segment,
get_root_from_dotted_path,
is_none_or_has_text,
is_not_none_and_has_text,
@@ -258,6 +259,21 @@ def test_get_root_from_dotted_path(dotted_path: str, expected: str) -> None:
assert get_root_from_dotted_path(dotted_path) == expected
+ ("path", "expected"),
+ [
+ ("deal.customer_name", None),
+ ("deal", None),
+ ("deal.items.first_name", None),
+ ("note.__class__.__init__", "__class__"),
+ ("note.content._private", "_private"),
+ ("_root", "_root"),
+ ],
+)
+def test_find_private_path_segment(path: str, expected: str | None) -> None:
+ assert find_private_path_segment(path=path) == expected
+
+
@pytest.mark.parametrize(
("count", "singular", "plural", "expected"),
[
diff --git a/tests/unit/pipelex/tools/test_jinja2_private_names.py b/tests/unit/pipelex/tools/test_jinja2_private_names.py
new file mode 100644
index 000000000..a0eaa8cbb
--- /dev/null
+++ b/tests/unit/pipelex/tools/test_jinja2_private_names.py
@@ -0,0 +1,43 @@
+"""The load-time walker that finds the private names a template reads, for a located validation error."""
+
+import pytest
+
+from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
+from pipelex.tools.jinja2.jinja2_private_names import detect_private_name_references
+from pipelex.tools.jinja2.template_category import TemplateCategory
+
+_ALLOWED = frozenset({"_stuff_name", "_content_class"})
+
+
+def _detect(template_source: str, *, template_category: TemplateCategory = TemplateCategory.LLM_PROMPT) -> list[str]:
+ return detect_private_name_references(
+ template_category=template_category,
+ template_source=template_source,
+ allowed_private_names=_ALLOWED,
+ )
+
+
+class TestDetectPrivateNameReferences:
+ @pytest.mark.parametrize(
+ ("topic", "template_source", "expected"),
+ [
+ ("dot", "{{ doc._stuff }}", ["_stuff"]),
+ ("bracket_is_left_to_the_render", "{{ doc['_content'] }} {{ record['_id'] }}", []),
+ ("dunder_chain_in_evaluation_order", "{{ cycler.__init__.__globals__ }}", ["__init__", "__globals__"]),
+ ("inside_a_block", "{% if doc %}{% for x in doc.items %}{{ x._secret }}{% endfor %}{% endif %}", ["_secret"]),
+ ("repeated_once", "{{ doc._stuff }} {{ other._stuff }}", ["_stuff"]),
+ ("allowed_metadata", "{{ doc._stuff_name }} {{ doc._content_class }}", []),
+ ("public_names", "{{ doc.title }} {{ doc['title'] }} {{ doc.get('x') }}", []),
+ ("dynamic_key_is_invisible", "{% set key = '_stuff' %}{{ doc[key] }}", []),
+ ("underscore_variable_name_is_not_an_attribute", "{{ _internal }}", []),
+ ],
+ )
+ def test_detects(self, topic: str, template_source: str, expected: list[str]) -> None:
+ assert _detect(template_source) == expected, topic
+
+ def test_expression_category(self) -> None:
+ assert _detect("{{ doc._stuff == 'x' }}", template_category=TemplateCategory.EXPRESSION) == ["_stuff"]
+
+ def test_unparseable_template_raises(self) -> None:
+ with pytest.raises(Jinja2DetectVariablesError):
+ _detect("{{ doc._stuff ")
diff --git a/tests/unit/pipelex/tools/test_jinja2_sandbox.py b/tests/unit/pipelex/tools/test_jinja2_sandbox.py
new file mode 100644
index 000000000..da7d87d4b
--- /dev/null
+++ b/tests/unit/pipelex/tools/test_jinja2_sandbox.py
@@ -0,0 +1,370 @@
+"""The template sandbox: templates read data and call methods of plain values, and nothing else.
+
+Every refusal is a `Jinja2TemplateSecurityError` raised at the point of access; every legitimate shape
+the templates of the workspace use renders as it did before the sandbox.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+import pytest
+
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.stuffs.composite_content import CompositeContent
+from pipelex.core.stuffs.image_content import ImageContent
+from pipelex.core.stuffs.list_content import ListContent
+from pipelex.core.stuffs.stuff import Stuff
+from pipelex.core.stuffs.stuff_artefact import StuffArtefact
+from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.tools.jinja2.exceptions import Jinja2TemplateRenderError, Jinja2TemplateSecurityError
+from pipelex.tools.jinja2.image_registry import ImageRegistry
+from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
+from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async, render_jinja2_sync
+from pipelex.tools.jinja2.jinja2_sandbox import _MUTATING_METHOD_NAMES # pyright: ignore[reportPrivateUsage]
+from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+from pipelex.tools.templating.text_format import TextFormat
+
+_TEMPLATING_STYLE = TemplatingStyle(tag_style=TagStyle.XML, text_format=TextFormat.PLAIN)
+
+
+class _Mood(StrEnum):
+ CALM = "calm"
+
+ def shout(self) -> str:
+ return self.value.upper()
+
+
+class _Impostor:
+ """Holds every rendering method as an instance attribute, which passes a runtime-checkable Protocol check on any Python."""
+
+ def __init__(self, *, calls: list[str]) -> None:
+ def record(**kwargs: Any) -> str:
+ calls.append(f"impostor {sorted(kwargs)}")
+ return "called"
+
+ self.render_with_images = record
+ self.rendered_for_template_async = record
+ self.render_for_tag_async = record
+ self.default_tag_name = "impostor"
+
+
+def _make_artefact(*, content: StuffContent, name: str, concept_code: NativeConceptCode) -> StuffArtefact:
+ return StuffArtefact(
+ Stuff(
+ stuff_code=f"{name}_code",
+ stuff_name=name,
+ concept=ConceptFactory.make_native_concept(native_concept_code=concept_code),
+ content=content,
+ )
+ )
+
+
+def _make_context(*, registry: ImageRegistry | None = None, calls: list[str] | None = None) -> dict[str, Any]:
+ calls = calls if calls is not None else []
+
+ def spy(**kwargs: Any) -> str:
+ calls.append(f"spy {sorted(kwargs)}")
+ return "called"
+
+ return {
+ "note": _make_artefact(content=TextContent(text="hello"), name="note", concept_code=NativeConceptCode.TEXT),
+ "photo": _make_artefact(content=ImageContent(url="https://example.com/photo.png"), name="photo", concept_code=NativeConceptCode.IMAGE),
+ # A list input hands a template its items, which are content objects: the route to a pydantic method.
+ "photos": _make_artefact(
+ content=ListContent[ImageContent](items=[ImageContent(url="https://example.com/photo.png")]),
+ name="photos",
+ concept_code=NativeConceptCode.IMAGE,
+ ),
+ # A PipeParallel's combined output: its parts are extra fields of the content model.
+ "combo": _make_artefact(
+ content=CompositeContent.model_validate(
+ {"summary": TextContent(text="S"), "title": TextContent(text="T"), "_hidden": TextContent(text="H")}
+ ),
+ name="combo",
+ concept_code=NativeConceptCode.COMPOSITE,
+ ),
+ # Parts named like pydantic attributes resolve to the parts, never to the attributes.
+ "clash": _make_artefact(
+ content=CompositeContent.model_validate(
+ {"model_extra": TextContent(text="E"), "model_dump": TextContent(text="D"), "_hidden": TextContent(text="H")}
+ ),
+ name="clash",
+ concept_code=NativeConceptCode.COMPOSITE,
+ ),
+ "impostor": _Impostor(calls=calls),
+ "spy": spy,
+ "created_at": datetime(2026, 1, 2, 3, 4, 5),
+ "record": {"a": 1, "b": 2},
+ "keyed": {"_id": "abc123", "__typename": "User"},
+ "tags": {"a", "b"},
+ "mood": _Mood.CALM,
+ Jinja2ContextKey.IMAGE_REGISTRY: registry or ImageRegistry(),
+ }
+
+
+async def _render(template_source: str, *, context: dict[str, Any] | None = None) -> str:
+ return await render_jinja2_async(
+ template_source=template_source,
+ template_category=TemplateCategory.LLM_PROMPT,
+ templating_context=context or _make_context(),
+ templating_style=_TEMPLATING_STYLE,
+ )
+
+
+# The methods of each mutable plain type that leave the value unchanged, so that together with the
+# sandbox's own list of mutating methods they classify every public method the type has.
+_NON_MUTATING_METHOD_NAMES: dict[type, frozenset[str]] = {
+ list: frozenset({"copy", "count", "index"}),
+ dict: frozenset({"copy", "fromkeys", "get", "items", "keys", "values"}),
+ set: frozenset({"copy", "difference", "intersection", "isdisjoint", "issubset", "issuperset", "symmetric_difference", "union"}),
+}
+
+# Templates handing a filter a value that holds a rendering method as data rather than defining it in its class.
+_NAMESPACE_WITH_RENDER_METHODS = (
+ "{% set ns = namespace(render_with_images=spy, rendered_for_template_async=spy, render_for_tag_async=spy, default_tag_name='ns') %}"
+)
+
+
+class TestTemplateSandbox:
+ @pytest.mark.parametrize(
+ ("topic", "template_source"),
+ [
+ ("globals_escape", "{{ cycler.__init__.__globals__ }}"),
+ ("raw_stuff_by_bracket", "{{ note['_stuff'] }}"),
+ ("class_by_bracket", "{{ note['__class__'] }}"),
+ ("raw_content_by_bracket", "{{ note['_content'] }}"),
+ ("raw_content_by_dot", "{{ note._content }}"),
+ ("raw_stuff_by_dot", "{{ note._stuff }}"),
+ ("raw_stuff_by_attr_filter", "{{ note | attr('_stuff') }}"),
+ ("pydantic_constructor", "{{ photos[0].model_validate({'url': 'pipelex-storage://org-b/x.png'}) }}"),
+ ("pydantic_copy", "{{ photos[0].model_copy() }}"),
+ ("pydantic_dump", "{{ photos[0].model_dump() }}"),
+ ("artefact_undeclared_method", "{{ note.render_for_tag_async() }}"),
+ ("class_method_through_instance", "{{ created_at.now() }}"),
+ ("mutating_list_method", "{% set items = [1] %}{{ items.append(2) }}"),
+ ("mutating_dict_method", "{{ record.update({'c': 3}) }}"),
+ ("mutating_set_method_jinja_misses", "{{ tags.intersection_update(['a']) }}"),
+ ("format_string_dunder", "{{ '{0.__class__}'.format(note) }}"),
+ ("format_string_private_attribute", "{{ '{0._stuff}'.format(note) }}"),
+ ("format_string_private_item", "{{ '{0[_stuff]}'.format(note) }}"),
+ ("subclass_method_on_plain_value", "{{ mood.shout() }}"),
+ ("private_name_on_plain_dict", "{{ record._secret }}"),
+ ("private_key_by_dot_on_plain_dict", "{{ keyed._id }}"),
+ ("dunder_by_bracket_on_plain_dict", "{{ record['__class__'] }}"),
+ ("private_part_of_a_composite_by_dot", "{{ combo._hidden }}"),
+ ("private_part_of_a_composite_by_bracket", "{{ combo['_hidden'] }}"),
+ ("private_part_through_a_part_named_model_extra", "{{ clash.model_extra['_hidden'] }}"),
+ # markupsafe calls a value's `__html__`, and `dictsort` and `xmlattr` call its `items`, outside the call check.
+ ("callable_in_namespace_for_escape", "{{ namespace(__html__=photos[0].model_dump_json) | e }}"),
+ ("callable_set_on_namespace", "{% set ns = namespace() %}{% set ns.__html__ = photos[0].model_dump_json %}{{ ns | striptags }}"),
+ ("callable_in_namespace_for_dictsort", "{{ namespace(items=photos[0].model_copy) | dictsort | join }}"),
+ ("callable_in_namespace_for_wordwrap", "{{ namespace(splitlines=photos[0].model_dump_json) | wordwrap }}"),
+ ("render_methods_in_namespace", _NAMESPACE_WITH_RENDER_METHODS + "{{ ns | tag }}"),
+ ],
+ )
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_refused(self, topic: str, template_source: str) -> None:
+ with pytest.raises(Jinja2TemplateSecurityError) as exc_info:
+ await _render(template_source)
+ # The message names what was refused, never the template source.
+ assert template_source not in str(exc_info.value), topic
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_forged_image_never_reaches_the_registry(self) -> None:
+ """The attack the stock sandbox let through: a template forging an image pointing at a foreign storage key."""
+ registry = ImageRegistry()
+ template_source = "{{ photos[0].model_validate({'url': 'pipelex-storage:/' ~ '/org-b/x.png'}) | with_images }}"
+ with pytest.raises(Jinja2TemplateSecurityError):
+ await _render(template_source, context=_make_context(registry=registry))
+ assert registry.images == []
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_refusal_names_the_attribute_and_the_type(self) -> None:
+ with pytest.raises(Jinja2TemplateSecurityError, match=r"may not read '_stuff' on a 'StuffArtefact' value"):
+ await _render("{{ note._stuff }}")
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_refusal_names_the_callable_and_the_type(self) -> None:
+ with pytest.raises(Jinja2TemplateSecurityError, match=r"may not call the method 'model_copy' of a 'ImageContent' value"):
+ await _render("{{ photos[0].model_copy() }}")
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_refused_mutation_leaves_the_value_unchanged(self) -> None:
+ context = _make_context()
+ with pytest.raises(Jinja2TemplateSecurityError):
+ await _render("{{ tags.intersection_update(['a']) }}", context=context)
+ assert context["tags"] == {"a", "b"}
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_wrapped_stuff_is_not_readable(self) -> None:
+ """An artefact exposes its content's fields and its metadata, never the Stuff it wraps."""
+ with pytest.raises(Jinja2TemplateRenderError, match="undefined error"):
+ await _render("{{ note.stuff.content }}")
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_method_template_cannot_include(self) -> None:
+ """A method template renders without a loader, so it cannot reach Pipelex's registered templates."""
+ with pytest.raises(Jinja2TemplateRenderError, match="template not found"):
+ await _render("{% include 'stuff_viewer.html.jinja2' %}")
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_calling_an_undefined_name_stays_an_undefined_error(self) -> None:
+ with pytest.raises(Jinja2TemplateRenderError, match="undefined error"):
+ await _render("{{ nowhere() }}")
+
+ @pytest.mark.parametrize(
+ "template_source",
+ ["{{ impostor | with_images }}"],
+ )
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_with_images_never_calls_a_method_held_as_data(self, template_source: str) -> None:
+ """The filter calls a rendering method only when the value's class defines it, which no template can build."""
+ calls: list[str] = []
+ with pytest.raises(Jinja2TemplateRenderError, match="does not implement the ImageRenderable protocol"):
+ await _render(template_source, context=_make_context(calls=calls))
+ assert calls == []
+
+ @pytest.mark.parametrize(
+ "template_source",
+ [
+ "{{ [impostor] | with_images }}",
+ "{{ impostor | tag }}",
+ "{{ impostor | format }}",
+ ],
+ )
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_filters_render_a_value_holding_methods_as_data_without_calling_them(self, template_source: str) -> None:
+ calls: list[str] = []
+ rendered = await _render(template_source, context=_make_context(calls=calls))
+ assert calls == []
+ assert "called" not in rendered
+
+ @pytest.mark.parametrize(
+ "template_source",
+ [
+ pytest.param("{{ range(200000) | length }}", id="range_past_the_sandbox_cap"),
+ pytest.param("{{ 1 / 0 }}", id="division_by_zero"),
+ ],
+ )
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_arithmetic_error_is_a_render_error(self, template_source: str) -> None:
+ with pytest.raises(Jinja2TemplateRenderError, match="arithmetic error"):
+ await _render(template_source)
+ with pytest.raises(Jinja2TemplateRenderError, match="arithmetic error"):
+ render_jinja2_sync(template_source=template_source, template_category=TemplateCategory.BASIC, templating_context=_make_context())
+
+ def test_sync_render_refuses_too(self) -> None:
+ with pytest.raises(Jinja2TemplateSecurityError):
+ render_jinja2_sync(
+ template_source="{{ note['_stuff'] }}",
+ template_category=TemplateCategory.BASIC,
+ templating_context=_make_context(),
+ )
+
+ def test_sync_render_reads_metadata(self) -> None:
+ rendered = render_jinja2_sync(
+ template_source="{{ note._stuff_name }}: {{ note.text }}",
+ template_category=TemplateCategory.BASIC,
+ templating_context=_make_context(),
+ )
+ assert rendered == "note: hello"
+
+ @pytest.mark.parametrize(
+ ("topic", "template_source", "expected"),
+ [
+ (
+ "metadata_by_dot",
+ "{{ note._stuff_name }}|{{ note._content_class }}|{{ note._concept_code }}|{{ note._stuff_code }}",
+ "note|TextContent|Text|note_code",
+ ),
+ (
+ "metadata_by_bracket",
+ "{{ note['_stuff_name'] }}|{{ note['_content_class'] }}|{{ note['_concept_code'] }}|{{ note['_stuff_code'] }}",
+ "note|TextContent|Text|note_code",
+ ),
+ ("content_fields", "{{ note.text }}|{{ note['text'] }}|{{ photo.url }}", "hello|hello|https://example.com/photo.png"),
+ ("artefact_get", "{{ note.get('text') }}|{{ note.get('missing', default='fallback') }}", "hello|fallback"),
+ ("artefact_get_refuses_attributes", "{{ note.get('_stuff') }}|{{ note.get('stuff') }}", "None|None"),
+ ("artefact_iter_keys_and_values", "{{ note.iter_keys() | list | length }}/{{ note.iter_values() | list | length }}", "5/5"),
+ (
+ "date_methods",
+ "{{ created_at.isoformat() }}|{{ created_at.strftime('%Y') }}|{{ created_at.toordinal() }}",
+ "2026-01-02T03:04:05|2026|739618",
+ ),
+ ("dict_methods", "{{ record.get('a') }}|{{ record.items() | list | length }}|{{ record.keys() | list | join(',') }}", "1|2|a,b"),
+ ("private_keys_of_a_plain_dict_by_bracket", "{{ keyed['_id'] }}|{{ keyed['__typename'] }}", "abc123|User"),
+ ("set_methods", "{{ tags.intersection(['a']) | list | join }}|{{ tags.issuperset(['a']) }}", "a|True"),
+ ("list_input_items", "{{ photos[0].url }}|{{ photos | length }}", "https://example.com/photo.png|1"),
+ (
+ "namespace_holds_data",
+ (
+ "{% set ns = namespace(n=1, s='a', c=cycler('x')) %}{% set ns.u = nowhere %}"
+ "{{ ns.n }}{{ ns.s }}{{ ns.c.next() }}{{ ns.u is defined }}"
+ ),
+ "1axFalse",
+ ),
+ (
+ "composite_part_named_like_a_pydantic_attribute",
+ "{{ clash.model_extra.text }}|{{ clash.model_dump.text }}|{{ clash['model_extra'].text }}|{{ clash.get('model_dump').text }}",
+ "E|D|E|D",
+ ),
+ (
+ "composite_parts",
+ "{{ combo.summary.text }}|{{ combo['title'].text }}|{{ combo.get('summary').text }}|{{ 'title' in combo }}|{{ '_hidden' in combo }}",
+ "S|T|S|True|False",
+ ),
+ (
+ "composite_keys",
+ "{{ combo.iter_keys() | list | join(',') }}",
+ "summary,title,_stuff_name,_content_class,_concept_code,_stuff_code",
+ ),
+ ("string_methods", "{{ 'abc'.upper() }}|{{ 'a,b'.split(',') | join('-') }}|{{ ', '.join(['x', 'y']) }}", "ABC|a-b|x, y"),
+ ("plain_method_on_plain_subclass", "{{ mood.upper() }}", "CALM"),
+ ("loop_helpers", "{% for i in [1, 2, 3] %}{{ loop.cycle('o', 'e') }}{% endfor %}", "oeo"),
+ ("loop_changed", "{% for i in [1, 1, 2] %}{{ loop.changed(i) }};{% endfor %}", "True;False;True;"),
+ ("namespace", "{% set ns = namespace(total=0) %}{% for i in [1, 2] %}{% set ns.total = ns.total + i %}{% endfor %}{{ ns.total }}", "3"),
+ ("cycler_and_joiner", "{% set c = cycler('a', 'b') %}{{ c.next() }}{{ c.next() }}{% set j = joiner(',') %}{{ j() }}x{{ j() }}y", "abx,y"),
+ ("macro_with_caller", "{% macro wrap(x) %}[{{ x }}{{ caller() }}]{% endmacro %}{% call wrap(1) %}C{% endcall %}", "[1C]"),
+ ("dict_global_and_range", "{{ dict(a=1)['a'] }}|{{ range(3) | list | length }}", "1|3"),
+ ("str_format", "{{ '{0} {1}'.format('a', 2) }}|{{ '{0.text}'.format(note) }}", "a 2|hello"),
+ ("tag_filter", "{{ note | tag }}", "<note>\nhello\n</note>"),
+ ("format_filter", "{{ note | format }}", "hello"),
+ ("with_images_filter", "{{ photo | with_images }}", "[Image 1]"),
+ (
+ "builtin_filters",
+ "{{ [1, 2] | length }}|{{ record | tojson }}|{{ [note] | map(attribute='text') | join }}",
+ '2|{"a": 1, "b": 2}|hello',
+ ),
+ ],
+ )
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_renders(self, topic: str, template_source: str, expected: str) -> None:
+ rendered = await _render(template_source)
+ assert rendered == expected, topic
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_iter_items_yields_fields_and_metadata_without_the_raw_content(self) -> None:
+ rendered = await _render("{% for key, value in note.iter_items() %}{{ key }}={{ value }};{% endfor %}")
+ assert rendered == "text=hello;_stuff_name=note;_content_class=TextContent;_concept_code=Text;_stuff_code=note_code;"
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_html_template_formats_markup_through_the_escaping_formatter(self) -> None:
+ rendered = await render_jinja2_async(
+ template_source="{{ ('<b>{0}</b>' | safe).format('<i>') }}",
+ template_category=TemplateCategory.HTML,
+ templating_context={},
+ )
+ assert rendered == "<b>&lt;i&gt;</b>"
+
+ @pytest.mark.parametrize("plain_type", [list, dict, set])
+ def test_every_mutable_type_method_is_classified(self, plain_type: type) -> None:
+ """A method a later Python adds fails here until someone decides whether it mutates."""
+ public_names = {name for name in dir(plain_type) if not name.startswith("_")}
+ mutating = _MUTATING_METHOD_NAMES[plain_type]
+ non_mutating = _NON_MUTATING_METHOD_NAMES[plain_type]
+ assert not mutating & non_mutating
+ assert public_names == mutating | non_mutating
diff --git a/tests/unit/pipelex/tools/test_jinja2_tag_filter.py b/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
index fd42ddd28..76ccae8f7 100644
--- a/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
+++ b/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
@@ -12,10 +12,26 @@ from pytest_mock import MockerFixture
from pipelex.tools.jinja2.exceptions import Jinja2ContextError
from pipelex.tools.jinja2.jinja2_filters import apply_tag_style, tag
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
-from pipelex.tools.jinja2.tag_renderable import TagRenderable
from pipelex.tools.templating.templating_style import TagStyle
+class _TagRenderableStub:
+ """Implements TagRenderable in its class: the tag filter never calls a rendering method an instance merely holds."""
+
+ def __init__(self, *, rendered: str, default_tag_name: str) -> None:
+ self.rendered = rendered
+ self.name = default_tag_name
+ self.render_calls = 0
+
+ async def render_for_tag_async(self) -> str:
+ self.render_calls += 1
+ return self.rendered
+
+ @property
+ def default_tag_name(self) -> str:
+ return self.name
+
+
@pytest.mark.asyncio(loop_scope="class")
class TestTagFilterValidation:
"""Tests for tag filter error handling and edge cases."""
@@ -79,15 +95,11 @@ class TestTagFilterValidation:
async def test_tag_with_tag_renderable(self, mocker: MockerFixture) -> None:
"""Test tag filter uses TagRenderable protocol."""
context = self._make_context(mocker, tag_style=TagStyle.TICKS)
+ renderable = _TagRenderableStub(rendered="rendered content", default_tag_name="my_stuff")
- # Create a mock TagRenderable with async method
- mock_renderable = mocker.MagicMock(spec=TagRenderable)
- mock_renderable.render_for_tag_async = mocker.AsyncMock(return_value="rendered content")
- mock_renderable.default_tag_name = "my_stuff"
-
- result = await tag(context, value=mock_renderable)
+ result = await tag(context, value=renderable)
- mock_renderable.render_for_tag_async.assert_called_once()
+ assert renderable.render_calls == 1
assert "rendered content" in result
assert "my_stuff" in result # Uses default_tag_name
@@ -95,12 +107,11 @@ class TestTagFilterValidation:
"""Test custom tag name overrides TagRenderable.default_tag_name."""
context = self._make_context(mocker, tag_style=TagStyle.XML)
- mock_renderable = mocker.MagicMock(spec=TagRenderable)
- mock_renderable.render_for_tag_async = mocker.AsyncMock(return_value="content")
- mock_renderable.default_tag_name = "default_name"
+ renderable = _TagRenderableStub(rendered="content", default_tag_name="default_name")
- result = await tag(context, value=mock_renderable, tag_name="override_name")
+ result = await tag(context, value=renderable, tag_name="override_name")
+ assert renderable.render_calls == 1
assert "<override_name>" in result
assert "default_name" not in result
diff --git a/tests/unit/pipelex/tools/test_template_surface.py b/tests/unit/pipelex/tools/test_template_surface.py
new file mode 100644
index 000000000..a839452b2
--- /dev/null
+++ b/tests/unit/pipelex/tools/test_template_surface.py
@@ -0,0 +1,43 @@
+"""The declarations the template sandbox reads: a type's template surface, and whether a type implements a rendering protocol."""
+
+import pytest
+from jinja2.utils import Namespace
+
+from pipelex.core.stuffs.image_content import ImageContent
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.tools.jinja2.image_renderable import ImageRenderable
+from pipelex.tools.jinja2.renderable_dispatch import type_implements
+from pipelex.tools.jinja2.tag_renderable import TagRenderable
+from pipelex.tools.jinja2.template_surface import TemplateSurface
+from pipelex.tools.jinja2.text_format_renderable import TextFormatRenderable
+
+
+class _HoldsRenderMethodAsData:
+ def __init__(self) -> None:
+ self.render_with_images = print
+
+
+class TestTemplateSurface:
+ @pytest.mark.parametrize("name", ["__class__", "stuff_name"])
+ def test_private_names_are_single_underscore_names(self, name: str) -> None:
+ with pytest.raises(ValueError, match="single underscore"):
+ TemplateSurface(callable_names=frozenset(), private_names=frozenset({name}))
+
+ @pytest.mark.parametrize(
+ ("value", "protocol"),
+ [(ImageContent(url="https://example.com/photo.png"), ImageRenderable), (TextContent(text="hello"), TextFormatRenderable)],
+ )
+ def test_a_class_defining_the_protocol_implements_it(self, value: object, protocol: type) -> None:
+ assert type_implements(value=value, protocol=protocol)
+
+ @pytest.mark.parametrize(
+ ("topic", "value", "protocol"),
+ [
+ ("instance_attribute", _HoldsRenderMethodAsData(), ImageRenderable),
+ ("namespace", Namespace(render_with_images=print), ImageRenderable),
+ ("namespace_with_every_member", Namespace(render_for_tag_async=print, default_tag_name="x"), TagRenderable),
+ ("plain_value", "text", TextFormatRenderable),
+ ],
+ )
+ def test_members_held_by_an_instance_do_not_implement_it(self, topic: str, value: object, protocol: type) -> None:
+ assert not type_implements(value=value, protocol=protocol), topic
diff --git a/uv.lock b/uv.lock
index c4db380ad..21fdf27d9 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3602,7 +3602,7 @@ requires-dist = [
{ name = "idna", specifier = ">=3.15" },
{ name = "instructor", specifier = ">=1.17.0,<2.0.0" },
{ name = "instructor", extras = ["google-genai"], marker = "extra == 'google-genai'" },
- { name = "jinja2", specifier = ">=3.1.4" },
+ { name = "jinja2", specifier = ">=3.1.6" },
{ name = "json2html", specifier = ">=1.3.0" },
{ name = "jsonschema", marker = "extra == 'dev'", specifier = ">=4.20.0" },
{ name = "kajson", specifier = "==0.7.1" },