Skip to content

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

fix: harden template preprocessor against sigil collisions (#894)

Louis Choquelbbcfd2e64091
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 21150151c..773d612bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,9 +5,16 @@
### Changed
- **Breaking (rendering): graph viewer assets are no longer bundled into generated HTML.** The ReactFlow HTML output now references `@pipelex/mthds-ui` (the standalone IIFE bundle + its CSS) and `elkjs` from `cdn.jsdelivr.net` with pinned versions and `sha384` Subresource Integrity hashes. Three external requests now load from jsDelivr at view time; the HTML itself is still generated offline by Pipelex — only viewing the rendered graph requires network access. The previous `make sync-graph-ui` / `make check-graph-ui-sync` workflow and the committed `pipelex/graph/reactflow/assets/graph-viewer.{js,css}` files have been removed; the manifest-style `package.json` and the `Graph UI sync check` GitHub Actions workflow are gone. A single Python module (`pipelex/graph/reactflow/standalone_assets.py`) is the source of truth for pinned versions and integrity hashes — the template reads them via Jinja2, so a bump touches one file plus the regenerated SRI constants. The new `pipelex-dev refresh-graph-ui-sri` command re-fetches the URLs, recomputes `sha384`, and rewrites the constants module; the `update-graph-ui` skill drives that flow. Previously, the "self-contained HTML" was already not offline (elkjs loaded from `unpkg.com` without integrity), and bumping the vendored bundle meant committing ~2 MB of regenerated JS+CSS on every mthds-ui release — SRI hashes give the same tamper-evidence with none of the diff churn.
+- **Breaking: `@var` / `@?var` sigils must be alone on their own line, and inline `@<ident>` raises at load time only when `<ident>` collides with a declared input of the surrounding pipe.** The `@`/`@?` rewriters wrap the value in a tag-shaped block envelope (`<var>...</var>` via the `tag()` filter), so the inline shapes never produced sensible output and are now rejected at load time with a new `TemplateSigilSyntaxError` — surfaced through pydantic validation with the line number, the offending span, and a migration hint. To stay friendly to coding agents authoring HTML/CSS templates (`<style>@media (...) { ... }</style>`, `@font-face { ... }`, Python/Java decorators like `@deprecated` / `@Override`), the validator is gated on the surrounding pipe's declared `inputs`: an inline `@<ident>` raises only when the candidate's root identifier matches a declared input (a real typo). Every inline candidate on a line is inspected, so a later collision can't hide behind an earlier CSS at-rule. Other inline `@` candidates pass through silently. The line-bounded rewriter (alone-on-line `@var` → `{{ var|tag("var") }}`, leading/trailing whitespace preserved) is unchanged and remains inputs-agnostic. The strict rule replaces the heuristic regex tightening from the prior CSS-collision fix: there are no residual rewrites for `@font-face` / `@counter-style` / `@view-transition` / `@property --x`, no special-case lookbehind/lookahead arms. The `$var` inline sigil is unchanged. **API:** `preprocess_template(template, *, declared_inputs=...)` gained a keyword-only `declared_inputs: set[str] | None` parameter (default `None` = lenient, no validation); a new pair of helpers `validate_template_sigils(template, declared_inputs)` and `rewrite_template_sigils(template)` exposes the validate and rewrite steps separately. `render_template` (runtime) calls `rewrite_template_sigils` directly — templates are already validated at load time, so the render path doesn't need the `declared_inputs` context. All pipe blueprints (`PipeLLMBlueprint`, `PipeComposeBlueprint`, `PipeSearchBlueprint`, `PipeImgGenBlueprint`, `PipeComposeFactory`) and template analyzers (`TemplateDocumentAnalyzer`, `TemplateImageAnalyzer`) thread their declared inputs into the validator; the base `TemplateBlueprint` and `ConstructBlueprint`-discovery validators remain lenient (no inputs context at that layer — the surrounding pipe's validator catches typos). **Migration:** for inline values, switch from `@var` to `$var`; for block-shaped content, move the sigil onto its own line; for literal `@` or `$` characters, use the `@@` / `$$` escapes documented below.
+
+### Added
+
+- **`@@` and `$$` template escapes.** Authors can opt out of sigil interpolation per occurrence: `@@var` renders as the literal string `@var` (no `{{ ... }}`), and `$$var` renders as the literal `$var`. The escapes are non-overlapping left-to-right (`@@@@var` → `@@var`, two literal `@`s). Use these for any literal `@`/`$` the author needs to keep in the rendered output — most commonly `@@font-face`, `@@namespace`, `@@media` inside CSS `<style>` blocks, or `$$10` for a literal dollar amount. Cross-link: `wip/template-preprocessor-line-bounded-at.md`.
+- **`TemplateSigilSyntaxError`** (`pipelex/cogt/templating/template_errors.py`): raised by the preprocessor when a candidate `@`/`@?` sigil is not alone on its line. Pipe blueprints (`PipeLLMBlueprint`, `PipeComposeBlueprint`, `PipeImgGenBlueprint`, `PipeSearchBlueprint`, `TemplateBlueprint`, `ConstructBlueprint`, `pipe_compose_factory`) and the `TemplateBlueprint` validator catch and re-raise as pydantic `ValueError` with pipe-specific context, so the diagnostic surfaces through normal MTHDS validation errors and IDE/`plxt check` diagnostics.
### Fixed
+- **Template preprocessor: `$<var>` no longer substitutes when `$` is adjacent to a word character on the left** (e.g. `micro$oft`, `user$host.com`, `P@ssw$rd123`, `a$b$c` now pass through unchanged instead of producing mid-word `{{ ... }}` substitutions), and no longer emits invalid Jinja for shapes like `$name..` (now renders `{{ name|format() }}..` with both trailing dots preserved as literal punctuation). The `$` arm now mirrors the `@` candidate pattern's word-boundary lookbehind (`(?<!\w)`) and uses a strict segmented identifier `[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*` that rules out a leading digit and consecutive dots structurally. The trailing-dot kludge in the `$` replacement function is gone (unreachable under the strict identifier shape). `$var` keeps its silent pass-through posture for non-candidate shapes — it does not raise like the `@` arm does.
- **Project `.pipelex/telemetry.toml` created by `pipelex init` no longer silently disables globally-enabled telemetry.** The kit previously shipped one `telemetry.toml` template carrying explicit `enabled = false` / `mode = "off"` defaults, and `pipelex init telemetry` copied it into both `~/.pipelex/` and the project's `.pipelex/`. Because the layered loader appends the project base file after `~/.pipelex/telemetry_override.toml`, a user who enabled Langfuse/PostHog globally in their override still had it turned off in every initialized project. The kit now ships a separate `telemetry.project.toml` template with every setting commented out, used only by project-level init. The global init still copies the active `telemetry.toml`. As a safety net, `telemetry_allowed_modes` defaults (`ci=False`, `cli=True`, `docker=True`, `fastapi=True`, `mcp=True`, `n8n=True`, `pytest=False`, `python=False`) now live in the `TelemetryConfig` Pydantic model rather than the TOML template, so a project file that omits the section can't disable custom telemetry for everyone.
- **Global `pipelex.toml` and `telemetry.toml` overrides no longer silently disappear when a project `.pipelex/` exists.** `ConfigLoader.load_config()` previously sourced *all* override files (`pipelex_local.toml`, `pipelex_{env}.toml`, `pipelex_{run_mode}.toml`, `pipelex_override.toml`, `pipelex_temporary_override.toml`) from a single "effective config dir" — project `.pipelex/` if present, else `~/.pipelex/`. As a result, the user's machine-wide overrides in `~/.pipelex/` were ignored entirely the moment a project shipped its own `.pipelex/`. `load_telemetry_config` had the same shadowing behavior for `telemetry.toml` and `telemetry_override.toml`, which was particularly painful because telemetry holds Langfuse/PostHog/OTLP secrets that users typically set once globally. Both loaders now layer global → project: package defaults → global base → global overrides → project base → project overrides, deep-merged so machine-wide personal preferences keep applying unless explicitly overridden by the project. The unit-testing run_mode behavior is preserved: `./tests/pipelex_{run_mode}.toml` is still the only run_mode file loaded under unit testing, replacing both layers to keep test runs hermetic. **Migration:** if a project previously relied on its `.pipelex/` to fully *replace* the user's global config rather than merging over it, the project must now redeclare any keys it wants to set explicitly — silent inheritance from `~/.pipelex/` is the new default.
- **`pipelex build structures` now emits domain-qualified class names and cross-references.** `ConceptFactory` registers each concept's structure class under `make_qualified_structure_class_name(domain, concept_code)` (e.g. `expense_validator__SpendingLimitCheck`), but the CLI generator was passing the bare `concept_code` to `StructureGenerator`. Generated files therefore contained `class ConceptCode(StructuredContent)` and unqualified cross-imports/types, while the registry expected the qualified name. `PipeFunc` validation against `concept.structure_class_name` then rejected the mismatch with `output concept expects structure class 'domain__X', but the function return type is 'X'`, breaking library load for any project that had regenerated structures. Fixed in `pipelex/cli/commands/build/structures_cmd.py`: the class-definition call sites now call `make_qualified_structure_class_name(blueprint.domain, concept_code)`; `_build_concept_ref_to_class_info` qualifies cross-reference class names while keeping the file stem unqualified so output filenames stay `domain__concept_code.py`; the `refines:` branch resolves the refined concept's domain via `QualifiedRef.parse_stripping_cross_package` and qualifies the base-class name for non-native refines, mirroring `ConceptFactory._handle_refines`.
diff --git a/TODOS.md b/TODOS.md
new file mode 100644
index 000000000..83e5fc704
--- /dev/null
+++ b/TODOS.md
@@ -0,0 +1,620 @@
+# Template preprocessor — sigil collision fix (TDD plan)
+
+## Status: `$` sigil footgun fixes landed (Phase 7 — 2026-05-13)
+
+The inline `$` sigil now mirrors the `@` candidate pattern's word-boundary lookbehind and uses a strict segmented identifier shape. Word-adjacent `$` (`micro$oft`, `user$host.com`, `P@ssw$rd123`, `a$b$c`) is now silent pass-through; `$name..` renders cleanly as `{{ name|format() }}..` (consecutive dots stay outside the match as literal punctuation). The trailing-dot kludge in `_replace_dollar_sigil` is gone — unreachable under the new identifier shape. `make agent-check` clean, `make agent-test` green.
+
+### Deviations from Phase 7 plan
+
+1. **One existing test updated to match the new contract.** `tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py::TestStructuredContentComposerRuntimeParams::test_template_field_accesses_extra_context` used the template `"Summary for $fiscal_year Q$quarter"`, which relied on the pre-Phase-7 deviation that allowed word-adjacent `$` to interpolate (so `Q$quarter` → `Q1`). Under Phase 7's word-boundary lookbehind that shape is intentional silent pass-through. The template was changed to `"Summary for $fiscal_year, quarter $quarter"` (separator added so the second `$` is not word-adjacent) and the assertion updated to `"quarter 1" in result.generated_summary`. Test intent (verifying `extra_context` is merged into template rendering) is preserved.
+2. **No `.mthds` workspace migration needed.** The Phase 7.3 grep flagged two lines in `mthds-ui/data/pipelines/pipeline_25/bundle.mthds` (`"# Text Report\n\n$classified.content"` and `"# Data Report\n\n$classified.content"`), but these are grep false positives — the `n` matched by `[[:alnum:]_]` is the `n` of the TOML `\n` escape; after TOML decoding the `$` is preceded by a real newline (whitespace), so the new regex still rewrites correctly.
+
+## Status: declared-inputs gating landed (Phase 8 — 2026-05-13)
+
+Phase 8 shipped. Inline `@<ident>` now raises only when `<ident>` (root segment for dotted paths) is a declared input of the surrounding pipe; CSS at-rules (`@media`, `@font-face`, `@import`, `@keyframes`, `@property`, …) and code decorators (`@deprecated`, `@Override`) pass through silently when they don't collide with an input. The line-bounded rewriter is unchanged. `preprocess_template` gained a keyword-only `declared_inputs: set[str] | None = None` parameter (default lenient); new helpers `validate_template_sigils(template, declared_inputs)` and `rewrite_template_sigils(template)` split the validate and rewrite steps so `render_template` skips re-validation at runtime. All pipe blueprints (`PipeLLM`, `PipeCompose`, `PipeSearch`, `PipeImgGen`, `PipeComposeFactory`) and template analyzers (`TemplateDocumentAnalyzer`, `TemplateImageAnalyzer`) thread their declared inputs into the validator. `make agent-check` clean, `make agent-test` green.
+
+### Deviations from Phase 8 plan
+
+1. **`preprocess_template` keeps its zero-arg form for legacy callers.** The plan implied every caller of `preprocess_template` would either pass `declared_inputs={...}` or explicit `None`. In practice the keyword-only signature with `declared_inputs=None` as default means the two call sites without inputs context (`TemplateBlueprint.validate_template`, `TemplateBlueprint.required_variables`, `ConstructBlueprint.get_required_variables`) keep their existing zero-arg call and benefit from the lenient default — no explicit `None` pass-through was needed.
+
+2. **Dedup'd `input_names` in three blueprints.** In `pipe_llm_blueprint.py`, `pipe_search_blueprint.py`, and `pipe_img_gen_blueprint.py`, the previous code computed `input_names: set[str] = set(self.inputs.keys()) if self.inputs else set()` separately from the new `declared_inputs` variable. Folded the two into a single `declared_inputs` reference threaded through both the preprocess call and the downstream missing/unused-inputs checks. Pure code clarity — no behavior change.
+
+3. **Existing strict-rule tests updated rather than removed.** The plan's "all existing tests still pass under the lenient-`None` default" claim was inconsistent with reality: parametrized tests like `test_strict_line_at_sigil_raises` and `test_css_at_rule_raises_under_strict_rule` called `preprocess_template(template)` with no kwarg and expected a raise. Under the new lenient default they would stop raising. Resolution: those parametrized tests now pass `declared_inputs={expected_identifier}` per case so they preserve the strict-rule assertion under the new gate, and were renamed accordingly (`*_raises_under_strict_rule` → `*_raises_when_keyword_is_declared_input`). The lenient pass-through case is covered by new parametrized tests (`test_inline_at_passes_through_when_declared_inputs_omitted/empty/no_input_matches`).
+
+4. **Workspace `.mthds` sanity check: pre-existing typos in sibling repos remain pre-existing typos.** Surfaced inline `@question` in `pipelex-cookbook` (two files) and `Idea: @idea` in `internal-tools/wip/`, all of which have the at-identifier declared as an input — these already raised under Phases 1–6's strict rule and continue to raise under Phase 8 (correct behavior). Flagged as follow-up cleanup for those sibling repos rather than fixed in this PR.
+
+## Status: strict line-bounded `@` rule landed (2026-05-13)
+
+The redesign described in `wip/template-preprocessor-line-bounded-at.md` shipped:
+
+- `@var` / `@?var` must be alone on their own line. Inline candidates raise `TemplateSigilSyntaxError`
+ at load time, surfaced through pydantic validation with line number + migration hint.
+- `$var` keeps its inline contract (unchanged).
+- `@@` and `$$` escapes preserved.
+- Workspace `.mthds` files migrated; all tests green; `make agent-check` clean; `make agent-test` clean.
+
+The history below documents the original heuristic CSS-collision fix, kept for context — the
+heuristic regex it produced was replaced by the strict rule above.
+
+## Status: heuristic CSS-collision fix complete (earlier)
+
+All phases (1–6) landed. Full `make agent-test` is green and `make agent-check` is clean. The
+work is ready to ship via `/release`.
+
+### Deviations from the original plan
+
+Two design points evolved during implementation. They are reflected in the code, the new tests,
+and the CHANGELOG, but the prose below is the historical plan and was not rewritten to match —
+read this block first, then the rest as TDD history.
+
+1. **Single-pass regex instead of three sequential `re.sub` calls.** The plan's three
+ `re.sub(...)` calls (one per sigil) cannot share the lookahead reliably: after the first pass
+ rewrites `@var` to `{{ var|tag("var") }}`, the second pass's `(?!\s*[({"'])` lookahead sees
+ the inserted `{` and aborts the next `$var` match. Combined into a single
+ `_SIGIL_PATTERN` with an alternation `(?:(?<!\w)(@\??)|(\$))...` and a dispatch callback
+ (`_replace_sigil`) so the lookahead only sees original-template characters. The original
+ `replace_at_variable` / `replace_optional_at_variable` / `replace_dollar_variable` helpers
+ were folded into the single callback.
+2. **`$` arm omits the `(?<!\w)` lookbehind.** The plan applied the lookbehind uniformly to
+ all three sigils, but it broke prose like `Summary for $fiscal_year Q$quarter` — `Q`
+ precedes the `$`, blocking the match. Splitting the alternation so only the `@`/`@?` arm
+ carries the lookbehind keeps emails (`[email protected]`) protected while letting
+ word-adjacent `$var` interpolate. Dollar amounts (`$10`) remain protected by the
+ `(?![0-9])` lookahead.
+3. **Inner-word lookahead added for `@keyframes spin {`, `@layer reset {`, `@import url(...)`.**
+ The plan's `(?!\s*[({"'])` only catches *direct* openers, but several CSS at-rules sit a
+ word between the keyword and the brace. Added a second lookahead arm
+ `\s*[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))` to cover them. The arm requires `(` or a *single* `{`
+ (NOT `{{`) so legitimate Jinja constructs in the same template (e.g.
+ `@var with {{ page | with_images }}`) aren't misclassified. `@namespace svg "..."` remains a
+ residual (too easily confused with prose like `@name said "..."`); authors escape with
+ `@@namespace`.
+
+## Quick start (cold session)
+
+Working directory: `/Users/lchoquel/repos/Pipelex/pipelex` (the `pipelex/` runtime repo inside the multi-repo workspace at `/Users/lchoquel/repos/Pipelex/`).
+
+Read in this order:
+
+1. This file (`TODOS.md`).
+2. `wip/template-preprocessor-css-collision.md` — full design rationale and alternatives considered.
+3. `pipelex/cogt/templating/template_preprocessor.py` — the file being changed (~100 lines).
+4. `tests/unit/pipelex/cogt/templating/test_template_preprocessor.py` — the test file being extended.
+
+Project conventions that apply (see `pipelex/CLAUDE.md` for the full list):
+
+- One `TestClass` per test module. The existing class is `TestTemplatePreprocessor`. Add new test methods inside that same class — do **not** create a second class.
+- Use pytest-mock, never `unittest.mock`. None of the new tests need mocking.
+- Run `make agent-check` after code changes (lint + type check).
+- Use `make agent-test` to validate, or for the targeted module: `.venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`.
+
+## Background (minimal)
+
+The template preprocessor at `pipelex/cogt/templating/template_preprocessor.py` rewrites three sigils into Jinja2 before rendering: `@var` → `{{ var|tag("var") }}`, `@?var` → optional insertion, `$var` → `{{ var|format() }}`.
+
+The current regexes are too permissive. CSS at-rules (`@media`, `@import`, `@keyframes`, …) inside `<style>` blocks of PipeCompose HTML templates get rewritten as variables and break rendering. Email addresses (`[email protected]`) and code constructs (Python decorators, bash subshells) have the same problem.
+
+Fix has two parts:
+
+1. **Heuristic regex tightening** — add a `(?<!\w)` lookbehind before each sigil (kills emails / word-adjacent `@`) and a `(?!\s*[({"'])` lookahead after the captured identifier (kills CSS at-rules and code constructs).
+2. **Explicit escapes** — `@@` → literal `@`, `$$` → literal `$`. This is the documented opt-out for any residual case the heuristic can't predict.
+
+## Current code (reference)
+
+`pipelex/cogt/templating/template_preprocessor.py`, the three regex calls inside `preprocess_template`:
+
+```python
+# Replace @?variable patterns (optional insertion) - must come before @variable
+new_template = re.sub(r"@\?(?![0-9])([a-zA-Z0-9_.]+)", replace_optional_at_variable, processed_template)
+# ...
+# Replace @variable patterns
+new_template = re.sub(r"@(?![0-9])([a-zA-Z0-9_.]+)", replace_at_variable, processed_template)
+# ...
+# Replace $variable patterns
+new_template = re.sub(r"\$(?![0-9])([a-zA-Z0-9_.]+)", replace_dollar_variable, processed_template)
+```
+
+The three `replace_*` helpers above them are unchanged by this work.
+
+## Target code
+
+New regex strings (Phase 2):
+
+```python
+r"(?<!\w)@\?(?![0-9])([a-zA-Z0-9_.]+)(?!\s*[({\"'])"
+r"(?<!\w)@(?![0-9])([a-zA-Z0-9_.]+)(?!\s*[({\"'])"
+r"(?<!\w)\$(?![0-9])([a-zA-Z0-9_.]+)(?!\s*[({\"'])"
+```
+
+Note: `(?<!\w)` is a fixed-width negative lookbehind (one char) — supported by `re`. The lookahead set `[({\"']` covers the four shapes CSS at-rules and code constructs take after the identifier; whitespace before them is allowed (`\s*`).
+
+Escape implementation (Phase 3): use null-byte sentinels that templates cannot contain. Recommended scheme:
+
+```python
+_AT_ESCAPE_SENTINEL = "\x00PIPELEX_AT_ESCAPE\x00"
+_DOLLAR_ESCAPE_SENTINEL = "\x00PIPELEX_DOLLAR_ESCAPE\x00"
+
+def preprocess_template(template: str) -> str:
+ processed_template = template.replace("@@", _AT_ESCAPE_SENTINEL).replace("$$", _DOLLAR_ESCAPE_SENTINEL)
+ # ... existing three re.sub calls run on processed_template ...
+ processed_template = processed_template.replace(_AT_ESCAPE_SENTINEL, "@").replace(_DOLLAR_ESCAPE_SENTINEL, "$")
+ return processed_template
+```
+
+`str.replace("@@", …)` is non-overlapping left-to-right greedy, which gives the correct semantics:
+
+- `@@var` → `<SENTINEL>var` → (no `@` left for the regex) → restored: `@var` (literal, no interpolation).
+- `@@@var` → `<SENTINEL>@var` → regex matches `@var` → `<SENTINEL>{{ var|tag("var") }}` → restored: `@{{ var|tag("var") }}` (literal `@` + interpolated `var`).
+- `@@@@var` → `<SENTINEL><SENTINEL>var` → no match → restored: `@@var` (two literal `@`s).
+
+---
+
+## Phase 1 — Extend tests with new expected behaviors (red)
+
+All tests go inside the existing `TestTemplatePreprocessor` class in `tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`.
+
+### 1.1 — CSS at-rule pass-through (heuristic lookahead)
+
+Identifier followed by `\s*[({"']` must not be rewritten. Expected output equals the input (unchanged) for each:
+
+- [x] `test_css_media_query_pass_through` — input `@media (max-width: 820px) { color: red; }`, output identical.
+- [x] `test_css_supports_pass_through` — input `@supports (display: grid) { color: red; }`, output identical.
+- [x] `test_css_import_string_pass_through` — input `@import "reset.css";`, output identical.
+- [x] `test_css_import_url_pass_through` — input `@import url("reset.css");`, output identical.
+- [x] `test_css_charset_pass_through` — input `@charset "UTF-8";`, output identical.
+- [x] `test_css_namespace_pass_through` — input `@namespace svg "http://www.w3.org/2000/svg";`, output identical.
+- [x] `test_css_keyframes_pass_through` — input `@keyframes spin { from { opacity: 0; } to { opacity: 1; } }`, output identical. (Both `@keyframes` and the `from`/`to` selectors are unaffected since they aren't preceded by a sigil.)
+- [x] `test_css_page_pass_through` — input `@page { margin: 1in; }`, output identical.
+- [x] `test_css_layer_named_pass_through` — input `@layer reset { color: red; }`, output identical.
+- [x] `test_css_container_pass_through` — input `@container (width > 400px) { color: red; }`, output identical.
+- [x] `test_css_font_face_pass_through` — input `@font-face { font-family: "X"; }`, output identical. Note: the identifier class today is `[a-zA-Z0-9_.]+`, which does not include `-`. So today `@font-face` already captures only `@font` and then encounters `-face` as literal — the lookahead `(?!\s*[({"'])` fires on `@font` because the next non-identifier character is `-`, not whitespace+brace. **Outcome under new regex**: `@font` captures, lookahead sees `-`, not whitespace+brace, so the lookahead does **not** fire — and `@font` would still be rewritten to `{{ font|tag("font") }}`. This is a residual case. **Decision for this test**: assert the heuristic does **not** save `@font-face` (input contains literal hyphen) and document `@@font-face` as the required author workaround. The test should assert the rewritten form so the limitation is visible:
+
+ ```text
+ input: @font-face { font-family: "X"; }
+ expected: {{ font|tag("font") }}-face { font-family: "X"; }
+ ```
+
+ Then add a companion `test_css_font_face_escaped_pass_through` that asserts `@@font-face { font-family: "X"; }` → `@font-face { font-family: "X"; }`.
+
+- [x] `test_full_style_block_pass_through` — a realistic multi-rule `<style>` block (combining `@media`, normal selectors, and at least one nested ruleset) must pass through byte-for-byte. Use this fixture:
+
+ ```html
+ <style>
+ .page { padding: 32px; }
+ @media (max-width: 820px) {
+ .page { padding: 24px; }
+ }
+ @supports (display: grid) {
+ .grid { display: grid; }
+ }
+ </style>
+ ```
+
+### 1.2 — Email and word-adjacent `@` (heuristic lookbehind)
+
+`@` preceded by a word character must not be treated as a sigil.
+
+- [x] **Update** the existing `test_email_address_partially_processed` (lines 412–423 of the current test file): rename it to `test_email_address_pass_through` and replace its body to assert pass-through:
+
+ ```text
+ input: Contact: [email protected]
+ expected: Contact: [email protected]
+ ```
+
+- [x] `test_email_in_sentence_pass_through` — input `Contact us at [email protected] for help.`, output identical.
+- [x] `test_word_adjacent_at_pass_through` — input `Send to [email protected] immediately.`, output identical.
+
+### 1.3 — `$` and `@` followed by code-like punctuation (regression guards)
+
+These shapes already pass through today because the identifier class `[a-zA-Z0-9_.]+` does not match `(` or `{`. They're included as regression guards so the new lookahead doesn't accidentally regress them, and to lock in the documented behavior.
+
+- [x] `test_jquery_call_pass_through` — input `$("body").addClass("x")`, output identical.
+- [x] `test_bash_subshell_pass_through` — input `result=$(date +%s)`, output identical.
+- [x] `test_dollar_brace_pass_through` — input `Use ${PATH} for the path.`, output identical.
+
+### 1.4 — Escape sequences `@@` and `$$`
+
+- [x] `test_double_at_escapes_to_literal_at`:
+ ```text
+ input: @@media (max-width: 820px) { color: red; }
+ expected: @media (max-width: 820px) { color: red; }
+ ```
+
+- [x] `test_double_at_makes_at_var_literal`:
+ ```text
+ input: Use @@var here.
+ expected: Use @var here.
+ ```
+ No `{{ … }}` in the output — the escape suppresses interpolation for that occurrence.
+
+- [x] `test_double_dollar_escapes_to_literal_dollar`:
+ ```text
+ input: Cost is $$10.
+ expected: Cost is $10.
+ ```
+
+- [x] `test_double_dollar_makes_dollar_var_literal`:
+ ```text
+ input: Use $$var here.
+ expected: Use $var here.
+ ```
+
+- [x] `test_escape_does_not_consume_legit_variable`:
+ ```text
+ input: @@media is literal, but @width is a variable.
+ expected: @media is literal, but {{ width|tag("width") }} is a variable.
+ ```
+
+- [x] `test_triple_at_is_escape_plus_variable`:
+ ```text
+ input: @@@var
+ expected: @{{ var|tag("var") }}
+ ```
+
+- [x] `test_quadruple_at_is_two_escapes`:
+ ```text
+ input: @@@@var
+ expected: @@var
+ ```
+
+- [x] `test_escape_inside_style_block` — `<style>` block containing `@@font-face` (the residual heuristic case from §1.1) — verifies the recommended manual override:
+ ```text
+ input: <style>@@font-face { font-family: "X"; }</style>
+ expected: <style>@font-face { font-family: "X"; }</style>
+ ```
+
+### 1.5 — Confirm all legacy tests still apply
+
+No test currently passing should regress. Skim each and confirm the new regexes don't break them. Quick reasoning for the non-obvious ones:
+
+- `test_variable_in_parentheses` — `The value (@value) is important`: the `@` is preceded by `(` (non-word), lookbehind passes; the captured `value` is followed by `)` (not in lookahead set), so lookahead passes. ✓ Still rewrites.
+- `test_email_address_partially_processed` — being replaced by `test_email_address_pass_through` (§1.2). Drop the old assertion.
+
+All other legacy tests are unaffected by the lookbehind (sigil is preceded by space/newline/start-of-string) and unaffected by the lookahead (variables are followed by space/dot/punctuation, not `(` / `{` / `"` / `'`).
+
+- [x] Re-run the full test module locally; legacy tests pass, new tests fail (red).
+
+### 1.6 — Run the suite to confirm reds
+
+- [x] `.venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`
+- [x] Confirm: all Phase 1 new tests fail with content mismatches (not import errors or syntax errors).
+
+**Checkpoint A**: Phase 1 complete when all new tests are written, all legacy tests still pass, and the new tests fail for the documented reasons.
+
+---
+
+## Phase 2 — Implement the heuristic regex tightening (green for §1.1–§1.3)
+
+Edit `pipelex/cogt/templating/template_preprocessor.py`.
+
+- [x] Replace the three regex strings in `preprocess_template` with the new ones from the "Target code" section above. The replacement-function calls (`replace_optional_at_variable`, `replace_at_variable`, `replace_dollar_variable`) and their bodies stay unchanged.
+- [x] Re-run the test module. Expected state:
+ - §1.1 CSS tests pass (except `test_css_font_face_pass_through`, which asserts the documented residual hyphen limitation, also passes — see its expected output above).
+ - §1.2 email tests pass.
+ - §1.3 regression guards pass.
+ - §1.4 escape tests still fail (escapes not implemented yet).
+ - §1.5 legacy tests still pass.
+
+---
+
+## Phase 3 — Implement the `@@` / `$$` escapes (green for §1.4)
+
+Still in `pipelex/cogt/templating/template_preprocessor.py`.
+
+- [x] Add the two sentinel module-level constants from the "Target code" section (`_AT_ESCAPE_SENTINEL`, `_DOLLAR_ESCAPE_SENTINEL`).
+- [x] In `preprocess_template`, before the existing regex substitutions, prepend:
+ ```python
+ processed_template = template.replace("@@", _AT_ESCAPE_SENTINEL).replace("$$", _DOLLAR_ESCAPE_SENTINEL)
+ ```
+ (Replaces the current `processed_template = template` line.)
+- [x] After the three regex substitutions, before the `return`, append:
+ ```python
+ processed_template = processed_template.replace(_AT_ESCAPE_SENTINEL, "@").replace(_DOLLAR_ESCAPE_SENTINEL, "$")
+ ```
+- [x] Remove the `# TODO: allow escape patterns` comment (line 73 in the current file).
+- [x] Re-run the test module. Expected: all Phase 1 tests now pass; legacy tests still pass.
+
+---
+
+## Phase 4 — Workspace sanity check
+
+Look for any existing `.mthds` file in the workspace that would behave differently under the new rules.
+
+- [x] From the workspace root (`/Users/lchoquel/repos/Pipelex/`), run:
+ ```bash
+ grep -rn '@[a-zA-Z_][a-zA-Z_0-9.]*[[:space:]]*[({"'\'']' --include="*.mthds" . | head -50
+ grep -rn '@@\|\$\$' --include="*.mthds" . | head -50
+ ```
+- [x] For any hit, decide: accept (intended behavior change, the new heuristic does what the user wants), document, or flag back to the human.
+
+---
+
+## Phase 5 — Lint and full tests
+
+- [x] `make agent-check` — Pyright, Ruff, Mypy, plxt all clean.
+- [x] Targeted test run for impacted areas:
+ ```bash
+ .venv/bin/pytest -n auto \
+ -m "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api" \
+ -o log_level=WARNING --tb=short -q \
+ tests/unit/pipelex/cogt/ tests/unit/pipelex/pipe_operators/
+ ```
+- [x] `make agent-test` — full suite green.
+
+---
+
+## Phase 6 — Docs & changelog
+
+- [x] `CHANGELOG.md`: add an entry under `## [Unreleased]` — `### Fixed` for the CSS collision, `### Added` for the `@@` / `$$` escapes. Cross-link `wip/template-preprocessor-css-collision.md`.
+- [x] Update MTHDS authoring guidance / agent prompts to mention `@@` and `$$`. Likely targets:
+ - `pipelex/builder/` (in-repo authoring docs and any prompts that describe template syntax).
+ - `mthds-plugins/` build/edit skill prompts (workspace neighbor — only update if the user explicitly asks to touch it; per `CLAUDE.md` plugin files belong to the published marketplace plugin).
+
+**Checkpoint B**: Phase 6 complete = ready to ship via `/release`.
+
+---
+
+## Out of scope / explicit non-goals
+
+- No reserved CSS keyword list. The heuristic covers the realistic surface; the escape covers the rest.
+- No HTML/`<style>`-aware parsing of templates.
+- No syntax migration (`@{var}` etc.) — purely additive change.
+- No changes to the `replace_*` helper functions or to the surrounding `tag(...)` / `format()` filters.
+- No changes to the call sites of `preprocess_template` listed in the design doc — they all benefit transparently.
+
+---
+
+## Phase 7 — `$` sigil footgun fixes (open, HIGH PRIORITY)
+
+### Why this phase
+
+A live audit of the inline `$` sigil surfaced four word-adjacent substitution bugs plus a consecutive-dots edge case. Root causes: the `$` regex is missing the `(?<!\w)` lookbehind that the `@` candidate pattern carries, and its identifier class (`[a-zA-Z0-9_.]+`) is too permissive (allows leading digit, consecutive dots, trailing dot inside the captured identifier).
+
+Concrete bugs (verified live against the current `preprocess_template`):
+
+| Input | Current output | Verdict |
+|---|---|---|
+| `micro$oft is a company` | `micro{{ oft\|format() }} is a company` | bug — mid-word substitution |
+| `user$host.com` | `user{{ host.com\|format() }}` | bug — mid-word substitution |
+| `P@ssw$rd123` | `P@ssw{{ rd123\|format() }}` | bug — mid-word substitution |
+| `a$b$c` | `a{{ b\|format() }}{{ c\|format() }}` | bug — back-to-back mid-word |
+| `$name..` | `{{ name.\|format() }}.` | bug — emits invalid Jinja |
+
+Regression guards (already correct under the current regex — must stay correct under the new one):
+
+- `see $name.` → `see {{ name|format() }}.` (sentence terminator)
+- `$user.name.first.` → `{{ user.name.first|format() }}.` (dotted access + terminator)
+- `run $(whatever) please` → unchanged (code-shape opener)
+- `price $10 today` → unchanged (dollar amount)
+- `$foo(bar)` / `$foo "bar"` → unchanged (code-shape lookahead)
+- `$$literal` → `$literal` (escape)
+
+Posture: **silent pass-through** for word-adjacent `$` (do not raise like `@` does). The `$` arm is best-effort inline by design — it already silently passes `$10`, `$(`, `${`, `$foo "..."`. Raising on `micro$oft` would be a noisier contract than warranted, and inconsistent with the existing `$` posture.
+
+### Target code
+
+In `pipelex/cogt/templating/template_preprocessor.py`:
+
+```python
+_DOLLAR_SIGIL_PATTERN = re.compile(
+ r"(?<!\w)(\$)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)(?![a-zA-Z0-9_])(?!\s*[({\"'])",
+)
+
+def _replace_dollar_sigil(match: Match[str]) -> str:
+ variable: str = match.group(2)
+ return f"{{{{ {variable}|format() }}}}"
+```
+
+Notes:
+
+- `(?<!\w)` mirrors the `@` candidate pattern's left guard. Fixes all four word-adjacent bugs.
+- The strict segmented identifier `[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*` rules out consecutive dots automatically and makes the prior `(?![0-9])` arm redundant — drop it.
+- The trailing-dot kludge in `_replace_dollar_sigil` (`if variable.endswith("."): variable = variable[:-1]; ...`) goes away. Under the strict shape a trailing `.` cannot end the captured identifier, so it naturally sits outside the match as literal punctuation. `$name.` still renders as `{{ name|format() }}.` because the `.` is simply not part of the match.
+
+### Phase 7.1 — TDD red
+
+All new tests go inside the existing `TestTemplatePreprocessor` class in `tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`.
+
+- [x] `test_word_adjacent_dollar_pass_through` — parametrized over the four mid-word bug shapes (`micro$oft is a company`, `user$host.com`, `P@ssw$rd123`, `a$b$c`); each passes through unchanged.
+
+- [x] `test_dollar_consecutive_dots_pass_through` — `$name..` renders as `{{ name|format() }}..`. Both dots stay outside the match as literal punctuation.
+
+- [x] Re-ran the targeted module — new tests went red first (content mismatches), all existing `$`-related tests still passed.
+
+### Phase 7.2 — Implementation (green)
+
+- [x] In `pipelex/cogt/templating/template_preprocessor.py`:
+ - [x] Replaced `_DOLLAR_SIGIL_PATTERN` with the strict segmented shape and added the `(?<!\w)` lookbehind.
+ - [x] Dropped the `(?![0-9])` lookahead arm (redundant under the new identifier shape).
+ - [x] Simplified `_replace_dollar_sigil` to the one-liner version. The `trailing_dot` branch is gone (unreachable under the new regex).
+ - [x] Updated the `# Inline \`$\` sigil` comment to describe the new contract.
+- [x] Targeted module green: 121 passed.
+
+### Phase 7.3 — Workspace sanity check
+
+- [x] Ran the grep against `/Users/lchoquel/repos/Pipelex/`. Two hits in `mthds-ui/data/pipelines/pipeline_25/bundle.mthds` (lines 100 and 107), both of the shape `"...\n\n$classified.content"`. These are grep false positives — the `n` matched by `[[:alnum:]_]` belongs to the TOML `\n` escape; after TOML decoding the `$` is preceded by a real newline, so the new regex still rewrites correctly. No action.
+
+### Phase 7.4 — Lint, tests, docs
+
+- [x] `make agent-check` clean (Pyright, Ruff, Mypy, plxt).
+- [x] Targeted cogt test run: 584 passed in 9.06s.
+- [x] `make agent-test` — full suite green (5148 passed, 2 skipped, 3 xfailed). One pre-existing test (`test_template_field_accesses_extra_context`) had its template changed from `Q$quarter` to `, quarter $quarter` to match the new contract — see the "Deviations from Phase 7 plan" section near the top.
+- [x] `CHANGELOG.md` updated under `[Unreleased]` `### Fixed`.
+
+**Checkpoint C**: Phase 7 complete when the four word-adjacent-`$` tests and the consecutive-dots test are green, all legacy tests are green, `make agent-check` is clean, and `make agent-test` is green.
+
+### STOP HERE — checkpoint before Phase 8
+
+**Coding must stop after Phase 7 is delivered.** Do **not** start Phase 8 in the same session. After Checkpoint C is reached:
+
+1. Update the top "Status" block to record Phase 7 as landed (with the date), mirroring the style of the existing "strict line-bounded `@` rule landed" block.
+2. Note any open questions, deviations from this plan, or follow-up items in a brief retrospective near the top of this file (same style as the existing "Deviations from the original plan" section).
+3. Hand back to the human for review.
+
+Phase 8 (declared-inputs gating, formerly Phase 7) opens a new area of concern — function split, signature change, and call-site threading across 9 files — and should be picked up in a fresh session with this `TODOS.md` as the entry point.
+
+---
+
+## Phase 8 — Declared-inputs gating for the `@`-sigil validator (landed 2026-05-13)
+
+### Why this phase
+
+The strict line-bounded `@` rule (Phases 1–6) turned every inline `@<ident>` into a load-time error to catch typos like `Extract from @invoice_text.` The same rule, however, makes inline `@media`, `@import`, `@keyframes`, `@font-face`, `@deprecated`, `@Override` — the CSS at-rules and code decorators that coding agents emit by default when writing HTML/CSS in PipeCompose templates — fail at load time too. Authors must escape every occurrence with `@@`, which is unfamiliar and surprising for both humans and agents. Phase 8 narrows the validator's "is this a real typo?" question by gating on the pipe's declared `inputs:`: an inline `@<ident>` raises only when `<ident>` (root segment for dotted paths) is one of the pipe's declared inputs. Everything else passes through silently, restoring CSS-friendliness without resurrecting the prior heuristic regex residuals (the rewriter stays strict line-bounded — alone-on-line `@var` still rewrites; nothing inline ever rewrites). LSP / `plxt check` still surface real typos at edit time because the inputs list is known at load time; no runtime threading required.
+
+### Target behavior
+
+```text
+pipe with inputs: { invoice_text: Text }:
+✗ Extract from @invoice_text. Done. → RAISES (invoice_text is declared → real typo)
+✓ Extract from $invoice_text. Done. → rewrites $invoice_text inline
+✓ @invoice_text → rewrites alone-on-line (unchanged)
+
+pipe with inputs: { invoice_text: Text } (no `media` input):
+✓ <style>@media (max-width: 820px) { ... }</style> → pass-through (media is NOT declared)
+✓ @media (max-width: 820px) { ... } → pass-through
+✓ @deprecated def foo(): → pass-through
+✓ @Override → pass-through (alone-on-line, but no Override input)
+
+pipe with inputs: { Override: Text } (unusual but possible):
+✗ @Override → RAISES at the alone-on-line shape too? NO —
+ alone-on-line still rewrites, because that's the rewriter's strict success case.
+ The gate only applies to the INLINE-candidate validator path.
+```
+
+### Target code
+
+**Signature change (`pipelex/cogt/templating/template_preprocessor.py`):**
+
+```python
+def preprocess_template(template: str, *, declared_inputs: set[str] | None = None) -> str: ...
+```
+
+When `declared_inputs is None`, the validator skips the inline-candidate check entirely (lenient pass-through). When a set is provided, the validator raises only when the candidate identifier's root segment is in the set.
+
+**Function split (for clean runtime path):**
+
+```python
+def validate_template_sigils(template: str, declared_inputs: set[str]) -> None:
+ """Raise TemplateSigilSyntaxError when an inline @-candidate matches a declared input."""
+
+def rewrite_template_sigils(template: str) -> str:
+ """Pure rewrite — applies @-line-bounded and $-inline substitutions. Does not validate."""
+
+def preprocess_template(template: str, *, declared_inputs: set[str] | None = None) -> str:
+ """Convenience entry: normalize, escape sentinels, optionally validate, rewrite, restore."""
+```
+
+`render_template` (runtime, in `template_rendering.py:17`) calls `rewrite_template_sigils` directly — by the time we reach render, the template has already been validated at load time, so the runtime call only needs the rewrite step. This avoids threading `declared_inputs` through the rendering path.
+
+**Validator gating logic (`_validate_at_sigil_alone_on_line`):**
+
+```python
+def _validate_at_sigil_alone_on_line(template: str, declared_inputs: set[str] | None) -> None:
+ if declared_inputs is None:
+ return # lenient: no inputs context, nothing to gate against
+ for line_index, line in enumerate(template.split("\n"), start=1):
+ if "@" not in line:
+ continue
+ if _AT_SIGIL_PATTERN.fullmatch(line):
+ continue
+ candidate = _AT_CANDIDATE_PATTERN.search(line)
+ if candidate is None:
+ continue
+ identifier = candidate.group(2)
+ root = get_root_from_dotted_path(identifier)
+ if root not in declared_inputs:
+ continue # not a declared input → not a typo candidate → pass through
+ # ... build current error message and raise ...
+```
+
+### Call sites to update
+
+| File | Line(s) | Inputs source | Pass |
+|---|---|---|---|
+| `pipe_llm_blueprint.py` | 41, 58 | `self.inputs: dict[str, str] \| None` | `set(self.inputs or {})` |
+| `pipe_compose_blueprint.py` | 106 | same | same |
+| `pipe_search_blueprint.py` | 44 | same | same |
+| `pipe_img_gen_blueprint.py` | 39 | same | same |
+| `pipe_compose_factory.py` | 67 | `inputs: InputStuffSpecs` | `set(inputs.variables)` |
+| `template_document_analyzer.py` | 48 | `input_specs: dict[str, str]` | `set(input_specs.keys())` |
+| `template_image_analyzer.py` | 64, 163 | same | same |
+| `construct_blueprint.py` | 249 | none (discovery function, not primary validation) | `None` |
+| `template_blueprint.py` | 25, 37 | none (base blueprint, no inputs context) | `None` |
+| `template_rendering.py` | 17 | runtime (already validated at load) | switch to `rewrite_template_sigils` |
+
+### Phase 8.1 — TDD red: tests for the new behavior
+
+All new tests go inside the existing `TestTemplatePreprocessor` class in `tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`.
+
+- [x] **Parametrized success (lenient when no matching input):** inline `@media (...)`, `@import "..."`, `@keyframes`, `@font-face`, `@deprecated def foo():`, `@Override` — each with `declared_inputs=set()` or `declared_inputs={"other_var"}` — pass through unchanged, no raise. Implemented as `test_inline_at_passes_through_when_declared_inputs_empty` and `test_inline_at_passes_through_when_no_input_matches`.
+- [x] **Parametrized success (lenient when `declared_inputs=None`):** same set of inputs as above, called with no kwarg — pass through unchanged. Implemented as `test_inline_at_passes_through_when_declared_inputs_omitted`.
+- [x] **Parametrized error (strict when match):** inline `@invoice_text.` with `declared_inputs={"invoice_text"}` raises with the existing migration hint shape (line N, sigil+identifier, `$var` hint, `@@` escape hint). Implemented as `test_inline_at_raises_when_root_is_declared_input` plus the existing `test_strict_line_at_sigil_raises` parametrized suite (updated to pass `declared_inputs={expected_identifier}` per case).
+- [x] **Dotted-access gating:** inline `@user.profile.bio` with `declared_inputs={"user"}` raises; same template with `declared_inputs={"profile"}` passes through (gate is on root segment). Implemented as `test_inline_at_with_dotted_path_raises_when_root_is_declared_input` and `test_inline_at_with_dotted_path_passes_when_only_inner_segment_declared`.
+- [x] **Alone-on-line rewrites regardless of inputs:** `@invoice_text` alone on its line still rewrites whether or not `invoice_text` is in `declared_inputs` — the rewriter is strict and inputs-agnostic. Implemented as `test_alone_on_line_rewrites_regardless_of_declared_inputs` (parametrized across empty / matching / non-matching / optional shapes).
+- [x] **Update CSS at-rule tests:** renamed `test_css_at_rule_raises_under_strict_rule` → `test_css_at_rule_raises_when_keyword_is_declared_input` (parametrized; derives the identifier from the keyword and passes `declared_inputs={identifier}`). Same renaming pattern applied to `test_full_style_block_raises_*`, `test_triple_at_raises_*`, `test_css_dash_at_rule_raises_*`. The lenient-pass-through case is covered by the new parametrized tests above. `@@`-escape companion tests are unchanged.
+
+Blueprint integration tests (`tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py`):
+
+- [x] PipeLLM with `inputs: {"invoice_text": "Text"}` and `prompt = "Extract from @invoice_text."` — pydantic raises `ValueError` wrapping `TemplateSigilSyntaxError`. Already covered by the existing `test_validate_inputs_raises_for_inline_at_sigil_in_prompt`.
+- [x] PipeLLM with `inputs: {"page": "Page"}` and `prompt = "<style>@media (max-width: 820px) { ... }</style>\n...$page"` — loads cleanly (no `media` input → CSS passes through). Implemented as `test_inline_css_at_rule_passes_when_keyword_not_declared`.
+- [x] Same prompt with `inputs: {"media": "Text"}` — raises on `@media` (declared input now matches). Implemented as `test_inline_at_raises_when_input_collides_with_at_rule_keyword`.
+- [x] Inline Python decorator (`@deprecated def foo():`) loads cleanly when `deprecated` is not a declared input. Implemented as `test_inline_python_decorator_passes_through`.
+
+Run target:
+
+```bash
+.venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
+.venv/bin/pytest -q tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py
+```
+
+Expected state after Phase 8.1: new tests fail (red), all existing tests still pass (the lenient-when-`None` default keeps current call sites' behavior intact for legacy tests that don't pass inputs).
+
+> **Deviation:** TDD was followed in spirit but not literally — under the new lenient-when-`None` default, the existing strict-rule tests that called `preprocess_template(template)` (no kwarg) would *stop raising*, breaking the "all existing tests still pass" claim. The fix was to update those parametrized tests to pass `declared_inputs={expected_identifier}` so they preserve their raise expectation under the new gate. New tests for the lenient cases were added alongside.
+
+### Phase 8.2 — Implementation (green)
+
+- [x] In `pipelex/cogt/templating/template_preprocessor.py`:
+ - [x] Added `get_root_from_dotted_path` import (from `pipelex.tools.misc.string_utils`).
+ - [x] Changed `_validate_at_sigil_alone_on_line` to accept `declared_inputs: set[str]` (not `Optional`) — the `None`-gate is now handled at the `preprocess_template` boundary so internal helpers don't need to re-check.
+ - [x] Split `preprocess_template` into `validate_template_sigils` (validator wrapper) and `rewrite_template_sigils` (escape → normalize → substitute → restore, no validation). Kept `preprocess_template` as a thin convenience entry that skips validation when `declared_inputs is None`. Extracted `_normalize_and_escape` to dedupe the line-ending + sentinel prelude across the two halves.
+ - [x] Updated the module docstring + function docstrings to describe the gating behavior.
+- [x] Threaded `declared_inputs` through the 7 call sites that have inputs context (`pipe_llm_blueprint`, `pipe_compose_blueprint`, `pipe_search_blueprint`, `pipe_img_gen_blueprint`, `pipe_compose_factory`, `template_document_analyzer`, `template_image_analyzer`). The 2 call sites without inputs context (`construct_blueprint`, `template_blueprint`) keep the zero-arg form and benefit from the lenient default — no explicit `None` pass-through needed.
+- [x] In `pipelex/cogt/templating/template_rendering.py`: switched from `preprocess_template(template)` to `rewrite_template_sigils(template)` — render path no longer re-validates.
+- [x] Dedup'd `input_names` / `declared_inputs` in `pipe_llm_blueprint`, `pipe_search_blueprint`, `pipe_img_gen_blueprint` — single `declared_inputs` variable threads through both the preprocess call and the downstream missing/unused-inputs checks. Pure code clarity, no behavior change.
+
+Run target same as Phase 8.1. Expected: all Phase 8.1 tests green, all legacy tests still green.
+
+### Phase 8.3 — Workspace sanity check
+
+- [x] Ran the workspace `.mthds` grep from `/Users/lchoquel/repos/Pipelex/`. After excluding TOML model references (`model = "@default-..."` — these never go through `preprocess_template`) and false positives from string-literal contexts, the surviving hits are:
+ - `pipelex-cookbook/examples/c_advanced/crewai_with_pipelex_tools/research_report.mthds:46` — inline `Question: @question` where `question` IS a declared input (line 40).
+ - `pipelex-cookbook/examples/b_basics/document_extract/answer_from_documents/bundle.mthds:150,261` — same shape (`Question: @question` with `question` declared on the surrounding pipe).
+ - `internal-tools/wip/carol-sessions/2026-04-07T06-11-46_dev_old-plugin/mthds-wip/haiku_writer/bundle.mthds:13` — `Idea: @idea` with `idea` declared.
+- [x] Verified: each hit is a genuine pre-existing typo that already raised under Phases 1–6 and continues to raise under Phase 8 (the declared-inputs gate intentionally fires here). They live in sibling repos (`pipelex-cookbook`, `internal-tools/wip/`), out of this PR's scope — flagged as follow-up cleanup in those repos rather than fixed here.
+- [x] Confirmed `@@`-escape workarounds still work under the new gating. None of the CSS-case workarounds needed to be added in `pipelex/` itself (the Phase 1–6 fix only touched code/tests, not `.mthds` files in this repo). No follow-up cleanup list required.
+
+### Phase 8.4 — Lint, tests, docs
+
+- [x] `make agent-check` clean (Pyright, Ruff, Mypy, plxt).
+- [x] Targeted test run for `tests/unit/pipelex/cogt/ tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/`: 994 passed, 1 xfailed (pre-existing unrelated).
+- [x] `make agent-test` — full suite green.
+- [x] `CHANGELOG.md` updated under `[Unreleased]` `### Changed`. The entry describes the gating contract, the new `validate_template_sigils` / `rewrite_template_sigils` split, the call-site threading, and the `render_template` switch to `rewrite_template_sigils` at runtime.
+- [x] MTHDS authoring guidance updated in `pipelex/builder/pipe/pipe_compose_spec.py` (the only file in `pipelex/builder/` mentioning `@@`-escapes): dropped the `@@font-face` / `@@media` CSS example, kept the `@@`/`$$` mention as the literal-character opt-out, and added a note that inline CSS at-rules now pass through silently unless their keyword collides with a declared input.
+
+**Checkpoint D**: Phase 8 complete when CSS at-rules in PipeCompose HTML templates load without `@@` escapes (where they don't collide with declared inputs), AND typo-shape inline `@<declared>` still raises with the migration hint at load time.
+
+### Open decisions for Phase 8
+
+These are small enough to default and proceed; flag objections before locking in.
+
+1. **`declared_inputs=None` default = lenient (no raise).** Reasoning: callers without inputs context (the base `TemplateBlueprint`, the `ConstructBlueprint` discovery function) can't make the gate decision; the strict behavior is hostile in those contexts. Alternative: default-strict — every call site that doesn't pass inputs gets the current Phase 1–6 behavior. Less friendly to the discovery / runtime paths.
+2. **Gate on root segment of dotted identifier.** `@user.profile.bio` is gated on `user`. Matches how Pipelex's input resolution and `detect_jinja2_required_variables` treat dotted paths.
+3. **Validator does NOT consult Jinja2-detected variables.** It only consults `declared_inputs`. Reasoning: by the time we validate, we haven't rewritten yet, so Jinja2 can't see `@var` as a variable; conversely, if the author wrote `{{ media }}` directly in Jinja, that's a separate concern. Keep the gate narrow and explicit.
+4. **Reserved-name handling unchanged.** Internal vars (`preliminary_text`, `place_holder`, `_-prefixed`) are still filtered downstream in `pipe_llm_blueprint.py:78`. The validator doesn't need to know about them — they're not realistic typo candidates inline.
+
+### Out of scope for Phase 8
+
+- **Auto-cleanup of existing `@@`-escapes in workspace `.mthds` files.** Phase 4 of the line-bounded plan added some; they keep working under the new gating. A follow-up PR can strip the ones that are no longer needed.
+- **Runtime gating on actual working-memory contents.** The proposal we considered first (check the candidate against the runtime context) would catch typos that aren't declared as inputs. Rejected because it moves validation from load time to render time and breaks LSP / `plxt check` integration. The declared-inputs gate is the load-time approximation.
+- **Heuristic shape detection inside the validator.** No `(?!\s*[({"'])` lookahead — the declared-inputs gate fully replaces shape-based heuristics for the `@` arm.
+- **Changes to the `$` sigil contract.** `$` is unchanged.
diff --git a/docs/building-methods/pipes/pipe-operators/PipeLLM.md b/docs/building-methods/pipes/pipe-operators/PipeLLM.md
index e59db0619..737c120b4 100644
--- a/docs/building-methods/pipes/pipe-operators/PipeLLM.md
+++ b/docs/building-methods/pipes/pipe-operators/PipeLLM.md
@@ -222,7 +222,7 @@ Analyze the document and explain how it relates to the context: $reference_doc
| `model` | string or table | Specifies the LLM choice by name, setting, or preset to use. | No |
| `model_to_structure` | string or table | Specifies the LLM choice by name, setting, or preset to use for structuring after preliminary text generation. | No |
| `system_prompt` | string | A system-level prompt to guide the LLM's behavior (e.g., "You are a helpful assistant"). Supports the same variable syntax as `prompt`, including image and document references. | No |
-| `prompt` | string | A template for the user prompt. Use `$` for inline variables (e.g., `$topic`) and `@` to insert the content of an entire input (e.g., `@text_to_summarize`). Image and document variables should also be tagged with `$` or `@`. | No |
+| `prompt` | string | A template for the user prompt. Use `$` for inline variables (e.g., `$topic`) and `@` to insert the content of an entire input (e.g., `@text_to_summarize`). Image and document variables should also be tagged with `$` or `@`. Escape with `@@` or `$$` to emit a literal `@` or `$` (e.g., `@@font-face` inside a `<style>` block). | No |
| `structuring_method` | string | The method for generating structured output. Can be `direct` or `preliminary_text`. Defaults to the global configuration. | No |
### LLM Setting Fields
diff --git a/docs/get-started/mthds-language-tutorial.md b/docs/get-started/mthds-language-tutorial.md
index 422e538a3..8c3f48ab2 100644
--- a/docs/get-started/mthds-language-tutorial.md
+++ b/docs/get-started/mthds-language-tutorial.md
@@ -164,6 +164,7 @@ Key concepts:
- **`inputs = { topic = "Text" }`** — declares what the pipe expects as input
- **`$topic`** — references an input variable in the prompt (as opposed to `@variable` which references data from working memory)
+- **`@@` and `$$`** — write a literal `@` or `$` without triggering interpolation. Use `@@font-face` or `@@media` inside `<style>` blocks, `$$10` for a literal dollar amount before a word, and so on. The escape is per-occurrence.
- **`-i inputs.json`** — provides input data at runtime
## Step 4: Structured Outputs
diff --git a/pipelex/builder/pipe/pipe_compose_spec.py b/pipelex/builder/pipe/pipe_compose_spec.py
index e7a121a7b..fe7e39354 100644
--- a/pipelex/builder/pipe/pipe_compose_spec.py
+++ b/pipelex/builder/pipe/pipe_compose_spec.py
@@ -79,10 +79,17 @@ class PipeComposeSpec(PipeSpec):
**Template mode** (for Text/Html output):
- Renders a template to produce formatted text
- Use Pipelex pre-processor syntax:
- - `@variable` renders an entire object with all attributes auto-formatted
+ - `@variable` renders an entire object with all attributes auto-formatted —
+ **must be alone on its own line** (leading/trailing whitespace is allowed
+ and preserved). Inline `@variable` raises a load-time `TemplateSigilSyntaxError`.
- `$variable.field` for inline field access (e.g., "Order #$order.id")
- Only use `{{ variable.field }}` for isolated single-field access
- - NEVER manually list all attributes - use `@variable` instead
+ - Escape with `@@` or `$$` to emit a literal `@` or `$` without interpolation
+ (e.g., `$$10` for a literal dollar amount before a word). Inline CSS at-rules
+ like `@media`, `@font-face`, `@keyframes`, and code decorators like `@deprecated`
+ already pass through silently — they only need `@@` if their keyword happens to
+ match one of this pipe's declared inputs.
+ - NEVER manually list all attributes - use `@variable` (on its own line) instead
**Construct mode** (for StructuredContent output):
- Assembles a structured object from working memory variables
@@ -101,7 +108,7 @@ class PipeComposeSpec(PipeSpec):
default=None,
description=(
"Template string using Pipelex pre-processor syntax: "
- "use @variable to render entire objects with auto-formatting, "
+ "use @variable (alone on its own line) to render entire objects with auto-formatting, "
"$variable.field for inline access. "
"NEVER manually list all attributes of an object - use @variable instead."
),
diff --git a/pipelex/cogt/templating/template_blueprint.py b/pipelex/cogt/templating/template_blueprint.py
index d63bb164d..a737dc2d2 100644
--- a/pipelex/cogt/templating/template_blueprint.py
+++ b/pipelex/cogt/templating/template_blueprint.py
@@ -3,6 +3,7 @@ from typing import Any
from pydantic import BaseModel, Field, model_validator
from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.tools.jinja2.jinja2_errors import Jinja2TemplateSyntaxError
@@ -21,7 +22,12 @@ class TemplateBlueprint(BaseModel):
@model_validator(mode="after")
def validate_template(self) -> "TemplateBlueprint":
try:
- check_jinja2_parsing(template_source=self.template, template_category=self.category)
+ preprocessed = preprocess_template(self.template)
+ except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in TemplateBlueprint: {exc}"
+ raise ValueError(msg) from exc
+ try:
+ check_jinja2_parsing(template_source=preprocessed, template_category=self.category)
except Jinja2TemplateSyntaxError as exc:
msg = f"Could not parse template for TemplateBlueprint: {exc}"
raise ValueError(msg) from exc
diff --git a/pipelex/cogt/templating/template_errors.py b/pipelex/cogt/templating/template_errors.py
new file mode 100644
index 000000000..2a32980db
--- /dev/null
+++ b/pipelex/cogt/templating/template_errors.py
@@ -0,0 +1,10 @@
+from pipelex.system.exceptions import ToolError
+
+
+class TemplateSigilSyntaxError(ToolError):
+ """Raised when a template contains a Pipelex sigil shape that violates the strict
+ line-bounded `@` rule.
+
+ The error message includes the 1-based line number, the offending sigil span, and a
+ migration hint pointing the author at `$var` (inline) or `@@` (literal `@`).
+ """
diff --git a/pipelex/cogt/templating/template_preprocessor.py b/pipelex/cogt/templating/template_preprocessor.py
index e2a1c2c3e..a808b7c29 100644
--- a/pipelex/cogt/templating/template_preprocessor.py
+++ b/pipelex/cogt/templating/template_preprocessor.py
@@ -1,96 +1,200 @@
import re
from re import Match
-# def _detect_non_existent_filters(template_str: str) -> None:
-# """Check a template string for non-existent Jinja2 filters.
-
-# Args:
-# template_str: The template string to check
-
-# Raises:
-# TemplateSyntaxError: If any non-allowed filters are found
-
-# """
-# # Pattern to match Jinja2 filter syntax: {{ variable|filter() }} or {{ variable|filter(param) }}
-# # This handles:
-# # - {{ variable|filter }}
-# # - {{ variable|filter() }}
-# # - {{ variable|filter(param) }}
-# # - {{ variable|filter(param1, param2) }}
-# filter_pattern = r"\{\{\s*[^|}]+\|\s*([a-zA-Z0-9_]+)(?:\([^)]*\))?\s*\}\}"
-# matches = re.finditer(filter_pattern, template_str)
-
-# invalid_filters: list[str] = []
-# for match in matches:
-# filter_name = match.group(1)
-# if filter_name not in ALLOWED_FILTERS:
-# invalid_filters.append(filter_name)
-
-# if invalid_filters:
-# msg = f"Invalid Jinja2 filters found: {invalid_filters}. Only the following filters are allowed: {ALLOWED_FILTERS}"
-# raise TemplateSyntaxError(msg)
-
-
-# Handle @variable patterns
-def replace_at_variable(match: Match[str]) -> str:
- variable: str = match.group(1)
- if variable.endswith("."):
- # trailing dot can't be in a variable name so it must be a punctuation in the template sentence, so we remove it
- variable = variable[:-1]
- return f'{{{{ {variable}|tag("{variable}") }}}}.'
- return f'{{{{ {variable}|tag("{variable}") }}}}'
-
-
-# Handle @?variable patterns (optional insertion)
-def replace_optional_at_variable(match: Match[str]) -> str:
- variable: str = match.group(1)
- if variable.endswith("."):
- # trailing dot can't be in a variable name so it must be a punctuation in the template sentence, so we remove it
- variable = variable[:-1]
- return f'{{% if {variable} %}}{{{{ {variable}|tag("{variable}") }}}}{{% endif %}}.'
- return f'{{% if {variable} %}}{{{{ {variable}|tag("{variable}") }}}}{{% endif %}}'
-
-
-# Handle $variable patterns
-def replace_dollar_variable(match: Match[str]) -> str:
- variable: str = match.group(1)
- if variable.endswith("."):
- # trailing dot can't be in a variable name so it must be a punctuation in the template sentence, so we remove it
- variable = variable[:-1]
- return f"{{{{ {variable}|format() }}}}."
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
+from pipelex.tools.misc.string_utils import get_root_from_dotted_path
+from pipelex.types import StrEnum
+
+
+class _Sigil(StrEnum):
+ """Recognized sigil prefixes. Defined as a `StrEnum` so the `match`/`case` over sigils is
+ exhaustiveness-checked by the linter — adding a new sigil to the regex without updating the
+ dispatcher (or vice versa) fails CI rather than silently misrouting.
+ """
+
+ AT = "@"
+ AT_OPTIONAL = "@?"
+
+
+# Line-bounded `@` / `@?` sigil.
+#
+# The line-bounded form is the only valid shape for `@`/`@?` — the `tag()` rewriter wraps the
+# value in a block-shaped envelope, so an inline shape would produce nonsensical output. Leading
+# and trailing whitespace on the line is captured and preserved so templates embedded in indented
+# YAML/TOML blocks render in the same column as the surrounding text. Input is normalized to
+# `\n` line endings up-front (see `preprocess_template`), so this pattern only needs to handle
+# `\n`-separated lines.
+#
+# Identifier shape: first char must be a letter or underscore (not a digit); dotted access
+# supported; segments are non-empty and start with letter or underscore.
+#
+# The `[ \t]` whitespace class is intentionally ASCII-only. Non-ASCII whitespace (NBSP,
+# EM SPACE, etc. — usually from rich-text copy-paste) is not recognized as indentation;
+# the validator (`_validate_at_sigil_alone_on_line`) surfaces a targeted error when this
+# trips up a declared input rather than the generic "must appear alone on its own line".
+_AT_SIGIL_PATTERN = re.compile(
+ r"^([ \t]*)(@\??)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)([ \t]*)$",
+ re.MULTILINE,
+)
+
+# Inline `$` sigil — keeps its inline contract. The word-boundary lookbehind `(?<!\w)` mirrors
+# the `@` candidate pattern's left guard: `$` adjacent to a word character on the left passes
+# through silently (so prose like `micro$oft` or `user$host.com` does not produce mid-word
+# substitution). The strict segmented identifier `[a-zA-Z_]...(?:\.[a-zA-Z_]...)*` rules out a
+# leading digit (so `$10` is unaffected without a separate `(?![0-9])` arm) and consecutive dots
+# (so `$name..` matches just `name`, leaving both trailing dots as literal punctuation outside
+# the match — no invalid Jinja). The trailing lookaheads block word-character continuation and
+# shell-style code constructs on the same line (`$foo "..."`, `$foo 'bar'`, `$foo {y}`,
+# `$foo (parens)`). The horizontal-whitespace class `[ \t]+` (one-or-more, not zero-or-more)
+# keeps the guard same-line *and* requires a space before the opener: zero-space adjacency
+# to `'` / `"` / `{` / `(` reads as natural prose (possessives like `$user's data`, parenthetical
+# `$user(note)`, adjacent quoting `$user"x"`) and interpolates. Zero-space `$` + opener with no
+# identifier in between (`$(...)`, `${...}`, `$"..."`) is still blocked because the identifier
+# capture in this same pattern fails — the lookahead only matters when an identifier did match.
+# The `[ \t]+` class is also intentionally ASCII-only — non-ASCII whitespace (NBSP / EM SPACE)
+# adjacent to an opener reads as opaque text, so `$foo<NBSP>"bar"` interpolates `$foo`.
+_DOLLAR_SIGIL_PATTERN = re.compile(
+ r"(?<!\w)(\$)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)(?![a-zA-Z0-9_])(?![ \t]+[({\"'])",
+)
+
+# Candidate-sigil detector for the validator: any unescaped `@`/`@?` at a non-word boundary
+# followed immediately by an identifier shape. Used only to surface errors; never substitutes.
+_AT_CANDIDATE_PATTERN = re.compile(
+ r"(?<!\w)(@\??)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)",
+)
+
+# Sentinels for `@@` / `$$` escapes. Replaced before the validator and regex pass, and restored
+# after, so escaped characters never reach the validator and never trip the strict rule. The NUL
+# bytes make collision with realistic template content extremely unlikely.
+_AT_ESCAPE_SENTINEL = "\x00PIPELEX_AT_ESCAPE\x00"
+_DOLLAR_ESCAPE_SENTINEL = "\x00PIPELEX_DOLLAR_ESCAPE\x00"
+
+
+def _replace_at_sigil(match: Match[str]) -> str:
+ leading: str = match.group(1)
+ sigil = _Sigil(match.group(2))
+ variable: str = match.group(3)
+ trailing: str = match.group(4)
+ match sigil:
+ case _Sigil.AT_OPTIONAL:
+ rendered = f'{{% if {variable} %}}{{{{ {variable}|tag("{variable}") }}}}{{% endif %}}'
+ case _Sigil.AT:
+ rendered = f'{{{{ {variable}|tag("{variable}") }}}}'
+ return f"{leading}{rendered}{trailing}"
+
+
+def _replace_dollar_sigil(match: Match[str]) -> str:
+ variable: str = match.group(2)
return f"{{{{ {variable}|format() }}}}"
-def preprocess_template(template: str) -> str:
- """Preprocess a template string to interpret our syntax patterns and convert them to Jinja2 syntax.
- Also, detect the use of non-existent filters.
+def _validate_at_sigil_alone_on_line(template: str, declared_inputs: set[str]) -> None:
+ r"""Scan for `@`/`@?` sigil candidates that are not alone on their own line and raise
+ when the candidate's root identifier is one of the surrounding pipe's declared inputs.
+
+ Inputs are post-`@@`-escape (so `@@` cases are already sentinel-replaced and don't trip the
+ check). Word-adjacent `@` (emails, prose hashtags) is excluded by the `(?<!\w)` lookbehind
+ on the candidate pattern. Inline candidates whose root identifier is not in `declared_inputs`
+ pass through silently — they're CSS at-rules, code decorators, or other false positives the
+ validator can't distinguish from typos without the inputs context.
+ """
+ for line_index, line in enumerate(template.split("\n"), start=1):
+ if "@" not in line:
+ continue
+ if _AT_SIGIL_PATTERN.fullmatch(line):
+ continue
+ stripped = line.strip()
+ if _AT_SIGIL_PATTERN.fullmatch(stripped):
+ padding_candidate = _AT_CANDIDATE_PATTERN.search(stripped)
+ if padding_candidate is not None:
+ padding_identifier = padding_candidate.group(2)
+ if get_root_from_dotted_path(padding_identifier) in declared_inputs:
+ padding_sigil = padding_candidate.group(1)
+ msg = (
+ f"`{padding_sigil}{padding_identifier}` on line {line_index} is padded with "
+ f"non-ASCII whitespace (e.g. NBSP, EM SPACE — often from rich-text "
+ f"copy-paste). Only ASCII space/tab is recognized as line indentation. "
+ f"Replace non-ASCII whitespace with regular spaces, or escape with `@@` if "
+ f"you intend a literal `@`."
+ )
+ raise TemplateSigilSyntaxError(msg)
+ for candidate in _AT_CANDIDATE_PATTERN.finditer(line):
+ sigil = candidate.group(1)
+ identifier = candidate.group(2)
+ root_identifier = get_root_from_dotted_path(identifier)
+ if root_identifier not in declared_inputs:
+ continue
+ msg = (
+ f"Inline `{sigil}{identifier}` is not allowed on line {line_index}: "
+ f"the `{sigil}` sigil produces tag-wrapped block content and must appear alone on "
+ f"its own line. "
+ f"Did you mean `${identifier}` (inline value), or move `{sigil}{identifier}` onto "
+ f"its own line? "
+ f"Escape with `@@` if you intend a literal `@`."
+ )
+ raise TemplateSigilSyntaxError(msg)
+
+
+def _normalize_and_escape(template: str) -> str:
+ """Normalize line endings and replace `@@`/`$$` escapes with sentinels."""
+ normalized = template.replace("\r\n", "\n").replace("\r", "\n")
+ return normalized.replace("@@", _AT_ESCAPE_SENTINEL).replace("$$", _DOLLAR_ESCAPE_SENTINEL)
+
+
+def validate_template_sigils(template: str, declared_inputs: set[str]) -> None:
+ r"""Raise `TemplateSigilSyntaxError` when an inline `@`/`@?` candidate's root identifier
+ matches one of the pipe's declared inputs.
+
+ The check is narrow on purpose: shapes like inline `@media` (CSS at-rules) or `@deprecated`
+ (Python/Java decorators) are common in HTML/CSS templates, so raising on every inline `@`
+ would be hostile. By gating on `declared_inputs`, the validator only fires on identifiers
+ the author actually plans to use — i.e. the "real typo" cases.
+ """
+ prepared = _normalize_and_escape(template)
+ _validate_at_sigil_alone_on_line(prepared, declared_inputs)
+
+
+def rewrite_template_sigils(template: str) -> str:
+ r"""Apply the sigil rewrites without validation.
+
+ Substitutes `$` inline first, then `@`/`@?` line-bounded. Order is structurally safe
+ in either direction: the `$` code-shape lookahead `(?![ \t]*[({"'])` is horizontal-only,
+ so it cannot cross a `\n` to reach the `{` introduced by the `@` pass (which only
+ substitutes alone-on-line, always preceded by a newline). `$`-first is chosen defensively
+ — it remains correct if the `$` lookahead is ever loosened to `\s*`.
+
+ Use this at render time, when the template has already been validated at load time —
+ there's no point re-running the validator.
"""
- # _detect_non_existent_filters(template_str=template)
+ prepared = _normalize_and_escape(template)
+ prepared = _DOLLAR_SIGIL_PATTERN.sub(_replace_dollar_sigil, prepared)
+ prepared = _AT_SIGIL_PATTERN.sub(_replace_at_sigil, prepared)
+ return prepared.replace(_AT_ESCAPE_SENTINEL, "@").replace(_DOLLAR_ESCAPE_SENTINEL, "$")
- processed_template = template
- changes_made = False
- # TODO: allow escape patterns
+def preprocess_template(template: str, *, declared_inputs: set[str] | None = None) -> str:
+ r"""Preprocess a template string to convert our sigil syntax patterns into Jinja2 syntax.
- # Replace @?variable patterns (optional insertion) - must come before @variable
- new_template = re.sub(r"@\?(?![0-9])([a-zA-Z0-9_.]+)", replace_optional_at_variable, processed_template)
- if new_template != processed_template:
- changes_made = True
- processed_template = new_template
+ Recognized sigils:
- # Replace @variable patterns
- new_template = re.sub(r"@(?![0-9])([a-zA-Z0-9_.]+)", replace_at_variable, processed_template)
- if new_template != processed_template:
- changes_made = True
- processed_template = new_template
+ - ``@var`` (alone on its own line) → ``{{ var|tag("var") }}``
+ - ``@?var`` (alone on its own line) → ``{% if var %}{{ var|tag("var") }}{% endif %}``
+ - ``$var`` (inline) → ``{{ var|format() }}``
- # Replace $variable patterns
- new_template = re.sub(r"\$(?![0-9])([a-zA-Z0-9_.]+)", replace_dollar_variable, processed_template)
- if new_template != processed_template:
- changes_made = True
- processed_template = new_template
+ Inline ``@var`` / ``@?var`` shapes are rejected at load time with `TemplateSigilSyntaxError`
+ **only when** the candidate identifier's root segment is in ``declared_inputs`` — that's the
+ "real typo" gate. When ``declared_inputs`` is ``None`` (the default), the validator is
+ skipped entirely, so callers without inputs context (the base ``TemplateBlueprint`` model
+ validator, discovery passes in ``ConstructBlueprint``) don't raise on inline shapes.
- if changes_made:
- pass
+ Authors can opt out per occurrence with the explicit escapes ``@@`` (→ literal ``@``) and
+ ``$$`` (→ literal ``$``).
- return processed_template
+ Line endings (``\r\n``, ``\r``) are normalized to ``\n`` up-front so the line-bounded ``@``
+ rule works the same for Windows / classic-Mac authored templates as for Unix ones. The
+ rendered output uses ``\n``-only line endings; downstream Jinja rendering is
+ line-ending-insensitive.
+ """
+ if declared_inputs is not None:
+ validate_template_sigils(template, declared_inputs)
+ return rewrite_template_sigils(template)
diff --git a/pipelex/cogt/templating/template_rendering.py b/pipelex/cogt/templating/template_rendering.py
index 459405c05..5ab99a81b 100644
--- a/pipelex/cogt/templating/template_rendering.py
+++ b/pipelex/cogt/templating/template_rendering.py
@@ -2,7 +2,7 @@ from collections.abc import Callable
from typing import Any
from pipelex.cogt.templating.template_category import TemplateCategory
-from pipelex.cogt.templating.template_preprocessor import preprocess_template
+from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigils
from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async
@@ -14,7 +14,7 @@ async def render_template(
templating_style: TemplatingStyle | None = None,
finalize: Callable[[Any], Any] | None = None,
) -> str:
- template_source = preprocess_template(template)
+ template_source = rewrite_template_sigils(template)
return await render_jinja2_async(
template_source=template_source,
diff --git a/pipelex/graph/reactflow/standalone_assets.py b/pipelex/graph/reactflow/standalone_assets.py
index 52a287706..84e5eba80 100644
--- a/pipelex/graph/reactflow/standalone_assets.py
+++ b/pipelex/graph/reactflow/standalone_assets.py
@@ -24,12 +24,12 @@ class CDNAsset(BaseModel):
crossorigin: Literal["anonymous", "use-credentials"] = "anonymous"
-MTHDS_UI_VERSION = "0.6.3"
+MTHDS_UI_VERSION = "0.6.4"
ELKJS_VERSION = "0.11.1"
MTHDS_UI_JS = CDNAsset(
url=f"https://cdn.jsdelivr.net/npm/@pipelex/mthds-ui@{MTHDS_UI_VERSION}/dist/standalone/graph-viewer.js",
- integrity="sha384-BS9SD/K440VwYZxJCMuOi3g0FVlFz9ugiivYvkVpRDPFRo9FMc6IXQl9EM22VCSP",
+ integrity="sha384-Ji9Rm7swvsWO7j8GL/y4AgRIkpPFLnWb8BokurqkzDxzTy0pTaasYLCNJyMCilqY",
)
MTHDS_UI_CSS = CDNAsset(
diff --git a/pipelex/pipe_operators/compose/construct_blueprint.py b/pipelex/pipe_operators/compose/construct_blueprint.py
index 373f2e275..87f25dbb2 100644
--- a/pipelex/pipe_operators/compose/construct_blueprint.py
+++ b/pipelex/pipe_operators/compose/construct_blueprint.py
@@ -13,6 +13,7 @@ from typing import Any, cast
from pydantic import BaseModel, ConfigDict, SerializationInfo, SerializerFunctionWrapHandler, field_validator, model_serializer, model_validator
from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.pipe_operators.compose.exceptions import ConstructFieldBlueprintTypeError, ConstructFieldBlueprintValueError
from pipelex.tools.jinja2.jinja2_errors import Jinja2DetectVariablesError
@@ -244,7 +245,11 @@ class ConstructBlueprint(BaseModel):
case ConstructFieldMethod.TEMPLATE:
if field_blueprint.template:
# Use the same approach as template mode: preprocess then detect variables
- preprocessed = preprocess_template(field_blueprint.template)
+ try:
+ preprocessed = preprocess_template(field_blueprint.template)
+ except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in construct template: {exc}"
+ raise ValueError(msg) from exc
try:
template_vars = detect_jinja2_required_variables(
template_category=TemplateCategory.BASIC,
diff --git a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
index 5ba0d5769..701f129d1 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
@@ -5,6 +5,7 @@ from typing_extensions import override
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.cogt.templating.templating_style import TemplatingStyle
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
@@ -101,7 +102,12 @@ class PipeComposeBlueprint(PipeBlueprint):
if self.template_source is None:
return
- preprocessed_template = preprocess_template(self.template_source)
+ declared_inputs: set[str] = set(self.inputs.keys()) if self.inputs else set()
+ try:
+ preprocessed_template = preprocess_template(self.template_source, declared_inputs=declared_inputs)
+ except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in PipeCompose template: {exc}"
+ raise ValueError(msg) from exc
try:
check_jinja2_parsing(
template_source=preprocessed_template,
diff --git a/pipelex/pipe_operators/compose/pipe_compose_factory.py b/pipelex/pipe_operators/compose/pipe_compose_factory.py
index bb1b9812a..b456ce36c 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_factory.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_factory.py
@@ -2,6 +2,7 @@ from typing import Any
from typing_extensions import override
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.pipe_factory import PipeFactoryProtocol
@@ -62,7 +63,11 @@ class PipeComposeFactory(PipeFactoryProtocol[PipeComposeBlueprint, PipeCompose])
msg = "Template source is required for template mode"
raise PipeComposeFactoryError(msg)
- preprocessed_template = preprocess_template(template_source)
+ try:
+ preprocessed_template = preprocess_template(template_source, declared_inputs=set(inputs.variables))
+ except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in PipeCompose template: {exc}"
+ raise PipeComposeFactoryError(msg) from exc
try:
check_jinja2_parsing(
template_source=preprocessed_template,
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
index 9d56c32a6..f685e0403 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py
@@ -6,6 +6,7 @@ from typing_extensions import override
from pipelex.cogt.img_gen.img_gen_job_components import AspectRatio, Background
from pipelex.cogt.img_gen.img_gen_setting import ImgGenModelChoice
from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
from pipelex.tools.jinja2.jinja2_errors import Jinja2TemplateSyntaxError
@@ -34,7 +35,12 @@ class PipeImgGenBlueprint(PipeBlueprint):
def validate_inputs(self):
# Get all required variables from prompt
template_category = TemplateCategory.IMG_GEN_PROMPT
- preprocessed_template = preprocess_template(self.prompt)
+ declared_inputs: set[str] = set(self.inputs.keys()) if self.inputs else set()
+ try:
+ preprocessed_template = preprocess_template(self.prompt, declared_inputs=declared_inputs)
+ except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in PipeImgGen prompt: {exc}"
+ raise ValueError(msg) from exc
try:
check_jinja2_parsing(
template_source=preprocessed_template,
@@ -55,8 +61,7 @@ class PipeImgGenBlueprint(PipeBlueprint):
required_variables.add(root)
# Check that all required variables are in inputs
- input_names: set[str] = set(self.inputs.keys()) if self.inputs else set()
- missing_variables: set[str] = required_variables - input_names
+ missing_variables: set[str] = required_variables - declared_inputs
if missing_variables:
missing_vars_str = ", ".join(sorted(missing_variables))
diff --git a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
index 6bce7ee17..1b00cdd4a 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
@@ -4,6 +4,7 @@ from typing_extensions import override
from pipelex.cogt.llm.llm_setting import LLMModelChoice
from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
from pipelex.core.pipes.validation import is_input_used_by_variables, is_variable_satisfied_by_inputs
@@ -35,8 +36,14 @@ class PipeLLMBlueprint(PipeBlueprint):
# Get all required variable paths from prompt and system_prompt (full dotted paths)
required_variable_paths: set[str] = set()
+ declared_inputs: set[str] = set(self.inputs.keys()) if self.inputs else set()
+
if self.prompt:
- preprocessed_template = preprocess_template(self.prompt)
+ try:
+ preprocessed_template = preprocess_template(self.prompt, declared_inputs=declared_inputs)
+ except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in PipeLLM prompt: {exc}"
+ raise ValueError(msg) from exc
try:
required_variable_paths.update(
detect_jinja2_required_variables(
@@ -49,7 +56,11 @@ class PipeLLMBlueprint(PipeBlueprint):
raise ValueError(msg) from exc
if self.system_prompt:
- preprocessed_system_template = preprocess_template(self.system_prompt)
+ try:
+ preprocessed_system_template = preprocess_template(self.system_prompt, declared_inputs=declared_inputs)
+ except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in PipeLLM system_prompt: {exc}"
+ raise ValueError(msg) from exc
try:
required_variable_paths.update(
detect_jinja2_required_variables(
@@ -69,13 +80,11 @@ class PipeLLMBlueprint(PipeBlueprint):
if not var.startswith("_") and get_root_from_dotted_path(var) not in {"preliminary_text", "place_holder"}
}
- input_names: set[str] = set(self.inputs.keys()) if self.inputs else set()
-
# Find variables used in prompts but not satisfied by any input
- missing_inputs = {var_path for var_path in filtered_variable_paths if not is_variable_satisfied_by_inputs(var_path, input_names)}
+ missing_inputs = {var_path for var_path in filtered_variable_paths if not is_variable_satisfied_by_inputs(var_path, declared_inputs)}
# Find inputs declared but not used by any variable path
- unused_inputs = {input_name for input_name in input_names if not is_input_used_by_variables(input_name, filtered_variable_paths)}
+ unused_inputs = {input_name for input_name in declared_inputs if not is_input_used_by_variables(input_name, filtered_variable_paths)}
if missing_inputs:
missing_vars_str = ", ".join(sorted(missing_inputs))
diff --git a/pipelex/pipe_operators/llm/template_document_analyzer.py b/pipelex/pipe_operators/llm/template_document_analyzer.py
index 753a0a8c0..49359e686 100644
--- a/pipelex/pipe_operators/llm/template_document_analyzer.py
+++ b/pipelex/pipe_operators/llm/template_document_analyzer.py
@@ -45,7 +45,7 @@ class TemplateDocumentAnalyzer:
List of DocumentReference objects describing how to extract documents
"""
# Preprocess template (convert @variable, $variable syntax)
- preprocessed = preprocess_template(template_source)
+ preprocessed = preprocess_template(template_source, declared_inputs=set(input_specs.keys()))
# Parse template to get variable references with filters
variable_refs = detect_jinja2_variable_references(
diff --git a/pipelex/pipe_operators/search/pipe_search_blueprint.py b/pipelex/pipe_operators/search/pipe_search_blueprint.py
index 173d4354a..01e81c87b 100644
--- a/pipelex/pipe_operators/search/pipe_search_blueprint.py
+++ b/pipelex/pipe_operators/search/pipe_search_blueprint.py
@@ -6,6 +6,7 @@ from typing_extensions import override
from pipelex.cogt.search.search_setting import SearchModelChoice
from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.core.pipes.pipe_blueprint import PipeBlueprint
from pipelex.tools.jinja2.jinja2_errors import Jinja2TemplateSyntaxError
@@ -39,7 +40,12 @@ class PipeSearchBlueprint(PipeBlueprint):
@override
def validate_inputs(self):
template_category = TemplateCategory.BASIC
- preprocessed_template = preprocess_template(self.prompt)
+ declared_inputs: set[str] = set(self.inputs.keys()) if self.inputs else set()
+ try:
+ preprocessed_template = preprocess_template(self.prompt, declared_inputs=declared_inputs)
+ except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in PipeSearch prompt: {exc}"
+ raise ValueError(msg) from exc
try:
check_jinja2_parsing(
template_source=preprocessed_template,
@@ -59,8 +65,7 @@ class PipeSearchBlueprint(PipeBlueprint):
if not root.startswith("_"):
required_variables.add(root)
- input_names: set[str] = set(self.inputs.keys()) if self.inputs else set()
- missing_variables: set[str] = required_variables - input_names
+ missing_variables: set[str] = required_variables - declared_inputs
if missing_variables:
missing_vars_str = ", ".join(sorted(missing_variables))
diff --git a/pipelex/pipe_operators/shared/template_image_analyzer.py b/pipelex/pipe_operators/shared/template_image_analyzer.py
index 1dd64d49a..109ac1ec5 100644
--- a/pipelex/pipe_operators/shared/template_image_analyzer.py
+++ b/pipelex/pipe_operators/shared/template_image_analyzer.py
@@ -61,7 +61,7 @@ class TemplateImageAnalyzer:
WithImagesFilterError: If | with_images is used on a type without nested images
"""
# Preprocess template (convert @variable, $variable syntax)
- preprocessed = preprocess_template(template_source)
+ preprocessed = preprocess_template(template_source, declared_inputs=set(input_specs.keys()))
# Parse template to get variable references with filters
variable_refs = detect_jinja2_variable_references(
@@ -158,9 +158,10 @@ class TemplateImageAnalyzer:
UnusedInputError: If any declared input is never referenced
"""
referenced_roots: set[str] = set()
+ declared_inputs = set(input_specs.keys())
for template_source in template_sources:
- preprocessed = preprocess_template(template_source)
+ preprocessed = preprocess_template(template_source, declared_inputs=declared_inputs)
variable_refs = detect_jinja2_variable_references(
template_category=template_category,
template_source=preprocessed,
@@ -169,7 +170,6 @@ class TemplateImageAnalyzer:
root_var = get_root_from_dotted_path(var_ref.path)
referenced_roots.add(root_var)
- declared_inputs = set(input_specs.keys())
unused_inputs = declared_inputs - referenced_roots
if unused_inputs:
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_3branch.mthds b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_3branch.mthds
index 9037ee6b1..aeea60d76 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_3branch.mthds
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_3branch.mthds
@@ -47,7 +47,7 @@ description = "Analyze the tone of the text"
inputs = { input_text = "Text" }
output = "Pg3ToneResult"
model = "$testing-text"
-prompt = "Describe the tone of: @input_text.text"
+prompt = "Describe the tone of: $input_text.text"
[pipe.pg3_analyze_length]
type = "PipeLLM"
@@ -55,7 +55,7 @@ description = "Analyze the length of the text"
inputs = { input_text = "Text" }
output = "Pg3LengthResult"
model = "$testing-text"
-prompt = "Describe the length characteristics of: @input_text.text"
+prompt = "Describe the length characteristics of: $input_text.text"
[pipe.pg3_analyze_style]
type = "PipeLLM"
@@ -63,7 +63,7 @@ description = "Analyze the writing style of the text"
inputs = { input_text = "Text" }
output = "Pg3StyleResult"
model = "$testing-text"
-prompt = "Describe the writing style of: @input_text.text"
+prompt = "Describe the writing style of: $input_text.text"
[pipe.pg3_refine_tone]
type = "PipeLLM"
@@ -71,7 +71,7 @@ description = "Refine the tone analysis"
inputs = { tone_result = "Pg3ToneResult" }
output = "Text"
model = "$testing-text"
-prompt = "Refine and elaborate on this tone analysis: @tone_result.text"
+prompt = "Refine and elaborate on this tone analysis: $tone_result.text"
[pipe.pg3_refine_length]
type = "PipeLLM"
@@ -79,4 +79,4 @@ description = "Refine the length analysis"
inputs = { length_result = "Pg3LengthResult" }
output = "Text"
model = "$testing-text"
-prompt = "Refine and elaborate on this length analysis: @length_result.text"
+prompt = "Refine and elaborate on this length analysis: $length_result.text"
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_add_each.mthds b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_add_each.mthds
index 6c0edbe85..c4db2eebb 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_add_each.mthds
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_add_each.mthds
@@ -37,7 +37,7 @@ description = "Generate a short one-sentence summary"
inputs = { input_text = "Text" }
output = "ShortSummary"
model = "$testing-text"
-prompt = "Summarize in one sentence: @input_text.text"
+prompt = "Summarize in one sentence: $input_text.text"
[pipe.summarize_detailed]
type = "PipeLLM"
@@ -45,7 +45,7 @@ description = "Generate a detailed summary"
inputs = { input_text = "Text" }
output = "DetailedSummary"
model = "$testing-text"
-prompt = "Write a detailed summary of: @input_text.text"
+prompt = "Write a detailed summary of: $input_text.text"
[pipe.combine_summaries]
type = "PipeLLM"
@@ -55,5 +55,5 @@ output = "Text"
model = "$testing-text"
prompt = """Combine these two summaries into a final result:
-Short: @short_summary.text
-Detailed: @detailed_summary.text"""
+Short: $short_summary.text
+Detailed: $detailed_summary.text"""
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_combined.mthds b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_combined.mthds
index 9c976d3d1..10b227417 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_combined.mthds
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/parallel_graph_combined.mthds
@@ -41,7 +41,7 @@ description = "Analyze the tone of the text"
inputs = { input_text = "Text" }
output = "PgcToneResult"
model = "$testing-text"
-prompt = "Describe the tone of: @input_text.text"
+prompt = "Describe the tone of: $input_text.text"
[pipe.pgc_analyze_length]
type = "PipeLLM"
@@ -49,7 +49,7 @@ description = "Analyze the length of the text"
inputs = { input_text = "Text" }
output = "PgcLengthResult"
model = "$testing-text"
-prompt = "Describe the length characteristics of: @input_text.text"
+prompt = "Describe the length characteristics of: $input_text.text"
[pipe.pgc_summarize_combined]
type = "PipeLLM"
@@ -57,4 +57,4 @@ description = "Summarize the combined parallel analysis result"
inputs = { pgc_combined_result = "PgcCombinedResult" }
output = "Text"
model = "$testing-text"
-prompt = "Summarize the following analysis: @pgc_combined_result"
+prompt = "Summarize the following analysis: $pgc_combined_result"
diff --git a/tests/integration/pipelex/libraries/test_load_from_crate.py b/tests/integration/pipelex/libraries/test_load_from_crate.py
index a0ad212e9..0b9116ed3 100644
--- a/tests/integration/pipelex/libraries/test_load_from_crate.py
+++ b/tests/integration/pipelex/libraries/test_load_from_crate.py
@@ -21,7 +21,7 @@ description = "Compute a score"
inputs = { data = "Text" }
output = "ScoreResult"
model = "$quick-reasoning"
-prompt = "Compute score from @data"
+prompt = "Compute score from $data"
"""
ANALYTICS_MTHDS = """\
@@ -37,7 +37,7 @@ description = "Analyze data"
inputs = { data = "Text" }
output = "AnalyticsResult"
model = "$quick-reasoning"
-prompt = "Analyze @data"
+prompt = "Analyze $data"
"""
diff --git a/tests/integration/pipelex/libraries/test_pipe_namespace.py b/tests/integration/pipelex/libraries/test_pipe_namespace.py
index 26d26cb80..d68efe9ca 100644
--- a/tests/integration/pipelex/libraries/test_pipe_namespace.py
+++ b/tests/integration/pipelex/libraries/test_pipe_namespace.py
@@ -23,7 +23,7 @@ description = "Process scoring data"
inputs = { data = "Text" }
output = "ScoreResult"
model = "$quick-reasoning"
-prompt = "Process scoring from @data"
+prompt = "Process scoring from $data"
"""
ANALYTICS_MTHDS = """\
@@ -39,7 +39,7 @@ description = "Process analytics data"
inputs = { data = "Text" }
output = "AnalyticsResult"
model = "$quick-reasoning"
-prompt = "Process analytics from @data"
+prompt = "Process analytics from $data"
"""
SCORING_CORE_MTHDS = """\
@@ -52,7 +52,7 @@ description = "Compute a score"
inputs = { data = "Text" }
output = "Text"
model = "$quick-reasoning"
-prompt = "Compute score from @data"
+prompt = "Compute score from $data"
"""
SCORING_ADVANCED_MTHDS = """\
@@ -65,7 +65,7 @@ description = "Compute a weighted score"
inputs = { data = "Text" }
output = "Text"
model = "$quick-reasoning"
-prompt = "Compute weighted score from @data"
+prompt = "Compute weighted score from $data"
"""
SCORING_DUPLICATE_MTHDS = """\
@@ -78,7 +78,7 @@ description = "Duplicate compute score"
inputs = { data = "Text" }
output = "Text"
model = "$quick-reasoning"
-prompt = "Duplicate compute score from @data"
+prompt = "Duplicate compute score from $data"
"""
SCORING_CONCEPT_A_MTHDS = """\
@@ -94,7 +94,7 @@ description = "Compute a score"
inputs = { data = "Text" }
output = "ScoreResult"
model = "$quick-reasoning"
-prompt = "Compute score from @data"
+prompt = "Compute score from $data"
"""
SCORING_CONCEPT_B_MTHDS = """\
@@ -110,7 +110,7 @@ description = "Compute a weighted score"
inputs = { data = "Text" }
output = "ScoreResult"
model = "$quick-reasoning"
-prompt = "Compute weighted score from @data"
+prompt = "Compute weighted score from $data"
"""
SINGLE_DOMAIN_MTHDS = """\
@@ -126,7 +126,7 @@ description = "Compute a score"
inputs = { data = "Text" }
output = "ScoreResult"
model = "$quick-reasoning"
-prompt = "Compute score from @data"
+prompt = "Compute score from $data"
"""
diff --git a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/cross_domain_concept_refs.mthds b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/cross_domain_concept_refs.mthds
index 9bb48a50a..a54d56163 100644
--- a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/cross_domain_concept_refs.mthds
+++ b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/cross_domain_concept_refs.mthds
@@ -8,4 +8,4 @@ description = "Analyze a non-compete clause from the legal.contracts domain"
inputs = { clause = "legal.contracts.NonCompeteClause" }
output = "Text"
model = "$quick-reasoning"
-prompt = "Analyze @clause"
+prompt = "Analyze $clause"
diff --git a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_deep.mthds b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_deep.mthds
index a9ff74254..fad80de3d 100644
--- a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_deep.mthds
+++ b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_deep.mthds
@@ -11,4 +11,4 @@ description = "Analyze a shareholder agreement"
inputs = { agreement = "ShareholderAgreement" }
output = "Text"
model = "$quick-reasoning"
-prompt = "Analyze @agreement"
+prompt = "Analyze $agreement"
diff --git a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_nested.mthds b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_nested.mthds
index cc267f7ce..93470de65 100644
--- a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_nested.mthds
+++ b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_nested.mthds
@@ -12,4 +12,4 @@ description = "Summarize a contract"
inputs = { clause = "NonCompeteClause" }
output = "ContractSummary"
model = "$quick-reasoning"
-prompt = "Summarize @clause"
+prompt = "Summarize $clause"
diff --git a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_single.mthds b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_single.mthds
index 1c6a89e6e..e71192b73 100644
--- a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_single.mthds
+++ b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/hierarchical_domain_single.mthds
@@ -11,4 +11,4 @@ description = "Extract a clause from a contract"
inputs = { contract = "Text" }
output = "ContractClause"
model = "$quick-reasoning"
-prompt = "Extract the clause from @contract"
+prompt = "Extract the clause from $contract"
diff --git a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/scoring.mthds b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/scoring.mthds
index 545b3614a..65d2cf92c 100644
--- a/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/scoring.mthds
+++ b/tests/integration/pipelex/phase1_hierarchical_domains/valid_fixtures/scoring.mthds
@@ -11,4 +11,4 @@ description = "Compute a weighted score"
inputs = { data = "Text" }
output = "WeightedScore"
model = "$quick-reasoning"
-prompt = "Compute score from @data"
+prompt = "Compute score from $data"
diff --git a/tests/integration/pipelex/pipeline/test_load_concepts_only.py b/tests/integration/pipelex/pipeline/test_load_concepts_only.py
index 8d8e79850..bcda4b196 100644
--- a/tests/integration/pipelex/pipeline/test_load_concepts_only.py
+++ b/tests/integration/pipelex/pipeline/test_load_concepts_only.py
@@ -61,7 +61,7 @@ type = "PipeLLM"
description = "Generate a topic"
inputs = { subject = "Text" }
output = "Topic"
-prompt = "Generate a topic about @subject"
+prompt = "Generate a topic about $subject"
"""
with tempfile.TemporaryDirectory() as tmp_dir:
@@ -306,7 +306,7 @@ type = "PipeLLM"
description = "A pipe that should be skipped"
inputs = { subject = "Text" }
output = "Result"
-prompt = "Generate a result about @subject"
+prompt = "Generate a result about $subject"
"""
with tempfile.TemporaryDirectory() as tmp_dir:
diff --git a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_list_output_bug.py b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_list_output_bug.py
index ffb44e92f..ddb13b06f 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_list_output_bug.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_sequence/test_pipe_sequence_list_output_bug.py
@@ -56,7 +56,7 @@ description = "Generate multiple items"
inputs = { topic = "Text" }
output = "Item[]"
model = "$testing-text"
-prompt = "Generate 3 items about: @topic"
+prompt = "Generate 3 items about: $topic"
# PipeLLM that processes a single item
[pipe.process_item]
@@ -65,7 +65,7 @@ description = "Process a single item"
inputs = { item = "Item" }
output = "ProcessedItem"
model = "$testing-text"
-prompt = "Process this item: @item"
+prompt = "Process this item: $item"
"""
@@ -192,7 +192,7 @@ description = "Generates employee profiles"
inputs = { nb_employees = "Number" }
output = "Employee[]"
model = "$testing-text"
-prompt = "Generate @nb_employees employees"
+prompt = "Generate $nb_employees employees"
# Inner sequence - THIS IS WHERE THE BUG OCCURS
[pipe.generate_employee_report]
@@ -213,7 +213,7 @@ description = "Generates multiple expenses for an employee"
inputs = { employee = "Employee" }
output = "Expense[]"
model = "$testing-text"
-prompt = "Generate expenses for: @employee"
+prompt = "Generate expenses for: $employee"
# Process single expense
[pipe.process_expense]
@@ -222,7 +222,7 @@ description = "Process a single expense"
inputs = { expense = "Expense" }
output = "ProcessedExpense"
model = "$testing-text"
-prompt = "Process expense: @expense"
+prompt = "Process expense: $expense"
# Compose final report
[pipe.compose_report]
@@ -231,7 +231,7 @@ description = "Compose the final report"
inputs = { employee = "Employee", processed_expenses = "ProcessedExpense[]" }
output = "EmployeeReport"
model = "$testing-text"
-prompt = "Create report for @employee with @processed_expenses"
+prompt = "Create report for $employee with $processed_expenses"
"""
diff --git a/tests/integration/pipelex/pipes/img_gen_prompt_inputs/test_img_gen_prompt_image_extraction.py b/tests/integration/pipelex/pipes/img_gen_prompt_inputs/test_img_gen_prompt_image_extraction.py
index d2cc6e7b9..bd8a556c3 100644
--- a/tests/integration/pipelex/pipes/img_gen_prompt_inputs/test_img_gen_prompt_image_extraction.py
+++ b/tests/integration/pipelex/pipes/img_gen_prompt_inputs/test_img_gen_prompt_image_extraction.py
@@ -149,7 +149,7 @@ class TestImgGenPromptImageExtraction:
description="Test at dotted path image in img_gen prompt",
inputs={"page.page_view": "Image", "page": "Page"},
output="Image",
- prompt="Edit this image: @page.page_view",
+ prompt="Edit this image:\[email protected]_view",
)
pipe = PipeFactory[PipeImgGen].make_from_blueprint(
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_document_references_factory_level.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_document_references_factory_level.py
index a5cf6bb63..e35c12fc3 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_document_references_factory_level.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_document_references_factory_level.py
@@ -20,7 +20,7 @@ class TestDocumentReferencesFactoryLevel:
description="Test DIRECT document reference",
inputs={"document": "Document"},
output="Text",
- prompt="Analyze: @document",
+ prompt="Analyze: $document",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
@@ -66,7 +66,7 @@ class TestDocumentReferencesFactoryLevel:
description="Test mixed references",
inputs={"doc": "Document", "image": "Image"},
output="Text",
- prompt="Document: @doc\nImage: @image",
+ prompt="Document:\n@doc\nImage:\n@image",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
@@ -93,7 +93,7 @@ class TestDocumentReferencesFactoryLevel:
description="Test no document reference for text",
inputs={"text": "Text"},
output="Text",
- prompt="Process: @text",
+ prompt="Process: $text",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_references_factory_level.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_references_factory_level.py
index 7af437d2d..1c133c5c3 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_references_factory_level.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_image_references_factory_level.py
@@ -20,7 +20,7 @@ class TestImageReferencesFactoryLevel:
description="Test DIRECT reference",
inputs={"image": "Image"},
output="Text",
- prompt="Describe: @image",
+ prompt="Describe: $image",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
@@ -66,7 +66,7 @@ class TestImageReferencesFactoryLevel:
description="Test no reference without filter",
inputs={"page": "Page"},
output="Text",
- prompt="Describe the page: @page",
+ prompt="Describe the page: $page",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_extraction.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_extraction.py
index 8253d6ac9..5672c07b5 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_extraction.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_extraction.py
@@ -103,7 +103,7 @@ class TestPromptDocumentExtraction:
description="Test images and documents",
inputs={"doc": "Document", "image": "Image"},
output="Text",
- prompt="Document: @doc\nImage: @image",
+ prompt="Document:\n@doc\nImage:\n@image",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_token_substitution.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_token_substitution.py
index 4a9a9e19e..284d18cb3 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_token_substitution.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_document_token_substitution.py
@@ -29,7 +29,7 @@ class TestPromptDocumentTokenSubstitution:
description="Test document token substitution",
inputs={"document": "Document"},
output="Text",
- prompt="Analyze this document: @document",
+ prompt="Analyze this document: $document",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_image_extraction.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_image_extraction.py
index e880ccc50..1bf45c0c4 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_image_extraction.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_image_extraction.py
@@ -328,7 +328,7 @@ class TestPromptImageExtraction:
description="Test direct nested image reference",
inputs={"page.page_view": "Image", "page": "Page"},
output="Text",
- prompt="Describe this image: @page.page_view",
+ prompt="Describe this image: $page.page_view",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
@@ -481,7 +481,7 @@ class TestPromptImageExtraction:
description="Test @image",
inputs={"image": "Image"},
output="Text",
- prompt="Content: @image",
+ prompt="Content:\n@image",
),
)
@@ -546,7 +546,7 @@ class TestPromptImageExtraction:
description="Test @images list",
inputs={"images": "Image[]"},
output="Text",
- prompt="Here are the images: @images",
+ prompt="Here are the images:\n@images",
),
)
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_text_token_substitution.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_text_token_substitution.py
index 203bfa81a..c17ce88a3 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_text_token_substitution.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_prompt_text_token_substitution.py
@@ -29,7 +29,7 @@ class TestPromptTextTokenSubstitution:
description="Test token substitution",
inputs={"image": "Image"},
output="Text",
- prompt="Describe this image: @image",
+ prompt="Describe this image: $image",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_refined_concept_references.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_refined_concept_references.py
index 098d12b39..2550d6d8c 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_refined_concept_references.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_refined_concept_references.py
@@ -33,7 +33,7 @@ class TestRefinedConceptReferences:
description="Test refined Image concept",
inputs={"photo": "refined_concepts_test.Photo"},
output="Text",
- prompt="Describe this photo: @photo",
+ prompt="Describe this photo: $photo",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
@@ -56,7 +56,7 @@ class TestRefinedConceptReferences:
description="Test refined Document concept",
inputs={"report": "refined_concepts_test.Report"},
output="Text",
- prompt="Summarize this report: @report",
+ prompt="Summarize this report: $report",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
@@ -80,7 +80,7 @@ class TestRefinedConceptReferences:
description="Test refined Image extraction",
inputs={"photo": "refined_concepts_test.Photo"},
output="Text",
- prompt="Describe: @photo",
+ prompt="Describe: $photo",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
@@ -117,7 +117,7 @@ class TestRefinedConceptReferences:
description="Test refined Document extraction",
inputs={"report": "refined_concepts_test.Report"},
output="Text",
- prompt="Summarize: @report",
+ prompt="Summarize: $report",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_system_prompt_references.py b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_system_prompt_references.py
index d1159e353..1a0ed450f 100644
--- a/tests/integration/pipelex/pipes/llm_prompt_inputs/test_system_prompt_references.py
+++ b/tests/integration/pipelex/pipes/llm_prompt_inputs/test_system_prompt_references.py
@@ -31,7 +31,7 @@ class TestSystemPromptReferences:
description="Test system prompt image reference",
inputs={"image": "Image"},
output="Text",
- system_prompt="Context image: @image",
+ system_prompt="Context image: $image",
prompt="Describe what you see",
)
@@ -81,7 +81,7 @@ class TestSystemPromptReferences:
description="Test system prompt document reference",
inputs={"document": "Document"},
output="Text",
- system_prompt="Reference document: @document",
+ system_prompt="Reference document: $document",
prompt="Summarize the document",
)
@@ -132,7 +132,7 @@ class TestSystemPromptReferences:
description="Test system prompt image extraction",
inputs={"image": "Image"},
output="Text",
- system_prompt="Context: @image",
+ system_prompt="Context: $image",
prompt="Describe what you see",
)
@@ -171,7 +171,7 @@ class TestSystemPromptReferences:
description="Test system prompt document extraction",
inputs={"document": "Document"},
output="Text",
- system_prompt="Context: @document",
+ system_prompt="Context: $document",
prompt="Summarize",
)
@@ -213,8 +213,8 @@ class TestSystemPromptReferences:
description="Test global image numbering",
inputs={"system_image": "Image", "user_image": "Image"},
output="Text",
- system_prompt="System context: @system_image",
- prompt="User query with: @user_image",
+ system_prompt="System context: $system_image",
+ prompt="User query with: $user_image",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
@@ -264,8 +264,8 @@ class TestSystemPromptReferences:
description="Test global document numbering",
inputs={"system_doc": "Document", "user_doc": "Document"},
output="Text",
- system_prompt="System context: @system_doc",
- prompt="User query with: @user_doc",
+ system_prompt="System context: $system_doc",
+ prompt="User query with: $user_doc",
)
pipe_llm = PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/integration/pipelex/pipes/test_bracket_notation_operators/test_bracket_notation_operators.py b/tests/integration/pipelex/pipes/test_bracket_notation_operators/test_bracket_notation_operators.py
index 67ebb6382..5b53acf0f 100644
--- a/tests/integration/pipelex/pipes/test_bracket_notation_operators/test_bracket_notation_operators.py
+++ b/tests/integration/pipelex/pipes/test_bracket_notation_operators/test_bracket_notation_operators.py
@@ -78,7 +78,7 @@ class TestBracketNotationInOperators:
description="Process multiple documents",
inputs={"documents": f"{NativeConceptCode.TEXT}[]", "query": NativeConceptCode.TEXT},
output=NativeConceptCode.TEXT,
- prompt="Summarize @documents based on $query",
+ prompt="Summarize $documents based on $query",
)
pipe = PipeFactory[PipeLLM].make_from_blueprint(
diff --git a/tests/integration/pipelex/temporal/library_crate/conflict_concept_alpha.mthds b/tests/integration/pipelex/temporal/library_crate/conflict_concept_alpha.mthds
index 5143d125d..1ab24701a 100644
--- a/tests/integration/pipelex/temporal/library_crate/conflict_concept_alpha.mthds
+++ b/tests/integration/pipelex/temporal/library_crate/conflict_concept_alpha.mthds
@@ -33,6 +33,6 @@ output = "Text"
model = "$testing-text"
prompt = """
Summarize this result:
-Score: @alpha_result.score
-Label: @alpha_result.label
+Score: $alpha_result.score
+Label: $alpha_result.label
"""
diff --git a/tests/integration/pipelex/temporal/library_crate/conflict_concept_beta.mthds b/tests/integration/pipelex/temporal/library_crate/conflict_concept_beta.mthds
index 2d653dfa8..5ca4141b8 100644
--- a/tests/integration/pipelex/temporal/library_crate/conflict_concept_beta.mthds
+++ b/tests/integration/pipelex/temporal/library_crate/conflict_concept_beta.mthds
@@ -34,7 +34,7 @@ output = "Text"
model = "$testing-text"
prompt = """
Summarize this result:
-Value: @beta_result.value
-Confidence: @beta_result.confidence
-Valid: @beta_result.is_valid
+Value: $beta_result.value
+Confidence: $beta_result.confidence
+Valid: $beta_result.is_valid
"""
diff --git a/tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds b/tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds
index faa018fdc..2a137826f 100644
--- a/tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds
+++ b/tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds
@@ -33,6 +33,6 @@ output = "Text"
model = "$testing-text"
prompt = """
Summarize this greeting:
-Message: @greeting_result.message
-Language: @greeting_result.language
+Message: $greeting_result.message
+Language: $greeting_result.language
"""
diff --git a/tests/integration/pipelex/temporal/library_crate/multi_concept_alpha.mthds b/tests/integration/pipelex/temporal/library_crate/multi_concept_alpha.mthds
index dc78cd768..73dbe4304 100644
--- a/tests/integration/pipelex/temporal/library_crate/multi_concept_alpha.mthds
+++ b/tests/integration/pipelex/temporal/library_crate/multi_concept_alpha.mthds
@@ -41,8 +41,8 @@ output = "Summary"
model = "$testing-text"
prompt = """
Create a summary for this person:
-Name: @profile_result.name
-Age: @profile_result.age
+Name: $profile_result.name
+Age: $profile_result.age
Respond with a headline and body.
"""
@@ -55,6 +55,6 @@ output = "Text"
model = "$testing-text"
prompt = """
Format this summary as plain text:
-Headline: @summary_result.headline
-Body: @summary_result.body
+Headline: $summary_result.headline
+Body: $summary_result.body
"""
diff --git a/tests/integration/pipelex/temporal/library_crate/multi_concept_beta.mthds b/tests/integration/pipelex/temporal/library_crate/multi_concept_beta.mthds
index da3f45a0c..f5204839c 100644
--- a/tests/integration/pipelex/temporal/library_crate/multi_concept_beta.mthds
+++ b/tests/integration/pipelex/temporal/library_crate/multi_concept_beta.mthds
@@ -41,9 +41,9 @@ output = "Summary"
model = "$testing-text"
prompt = """
Create a one-line summary for this employee:
-Title: @profile_result.title
-Department: @profile_result.department
-Level: @profile_result.level
+Title: $profile_result.title
+Department: $profile_result.department
+Level: $profile_result.level
"""
[pipe.multi_beta_finalize]
diff --git a/tests/integration/pipelex/temporal/library_crate/temporal_batch.mthds b/tests/integration/pipelex/temporal/library_crate/temporal_batch.mthds
index 0c805be4d..27ca9f726 100644
--- a/tests/integration/pipelex/temporal/library_crate/temporal_batch.mthds
+++ b/tests/integration/pipelex/temporal/library_crate/temporal_batch.mthds
@@ -37,4 +37,4 @@ description = "Write a short note about a topic"
inputs = { topic = "Topic" }
output = "TopicNote"
model = "$testing-text"
-prompt = "Write one sentence about: @topic"
+prompt = "Write one sentence about: $topic"
diff --git a/tests/integration/pipelex/temporal/library_crate/temporal_combined.mthds b/tests/integration/pipelex/temporal/library_crate/temporal_combined.mthds
index db8f473c3..d3240f73a 100644
--- a/tests/integration/pipelex/temporal/library_crate/temporal_combined.mthds
+++ b/tests/integration/pipelex/temporal/library_crate/temporal_combined.mthds
@@ -71,6 +71,6 @@ output = "QualityReport"
model = "$testing-text"
prompt = """
Create a quality report from:
-Part A: @part_a
-Part B: @part_b
+Part A: $part_a
+Part B: $part_b
"""
diff --git a/tests/integration/pipelex/temporal/library_crate/temporal_parallel.mthds b/tests/integration/pipelex/temporal/library_crate/temporal_parallel.mthds
index c84ee14c5..2d140014a 100644
--- a/tests/integration/pipelex/temporal/library_crate/temporal_parallel.mthds
+++ b/tests/integration/pipelex/temporal/library_crate/temporal_parallel.mthds
@@ -47,6 +47,6 @@ output = "Text"
model = "$testing-text"
prompt = """
Combine these results:
-Tone: @tone_result
-Length: @length_result
+Tone: $tone_result
+Length: $length_result
"""
diff --git a/tests/unit/pipelex/builder/operations/test_data.py b/tests/unit/pipelex/builder/operations/test_data.py
index 1d19bbb01..e90d99bd6 100644
--- a/tests/unit/pipelex/builder/operations/test_data.py
+++ b/tests/unit/pipelex/builder/operations/test_data.py
@@ -10,5 +10,5 @@ class PipeOpsTestData:
"model": "$writing-creative",
"inputs": {"text": "Text"},
"output": "Text",
- "prompt": "Write about @text",
+ "prompt": "Write about $text",
}
diff --git a/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py b/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
index bb4de57bc..8dcfb7e8f 100644
--- a/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
+++ b/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
@@ -118,10 +118,10 @@ class TestParsePipeSpec:
def test_prompt_template_alias_for_llm(self) -> None:
"""`prompt_template` alone is promoted to `prompt` for PipeLLM."""
spec = {key: val for key, val in _BASE_LLM.items() if key != "prompt"}
- spec["prompt_template"] = "Write about @text"
+ spec["prompt_template"] = "Write about $text"
result = parse_pipe_spec("PipeLLM", spec)
assert isinstance(result, PipeLLMSpec)
- assert result.prompt == "Write about @text"
+ assert result.prompt == "Write about $text"
def test_canonical_prompt_takes_precedence_over_alias(self) -> None:
"""When both `prompt` and `prompt_template` are present, canonical wins and alias is dropped."""
@@ -267,7 +267,7 @@ class TestParsePipeSpec:
"model": "$writing-creative",
"inputs": {"text": "Text"},
"output": "Text",
- "prompt": "Write about @text",
+ "prompt": "Write about $text",
}
snapshot = dict(original)
parse_pipe_spec("PipeLLM", original)
@@ -324,7 +324,7 @@ class TestParsePipeSpec:
"description": "Search the web",
"inputs": {"query_text": "Text"},
"output": "Text",
- "prompt": "Search for @query_text",
+ "prompt": "Search for $query_text",
},
PipeSearchSpec,
),
diff --git a/tests/unit/pipelex/builder/operations/test_pipe_spec_to_toml.py b/tests/unit/pipelex/builder/operations/test_pipe_spec_to_toml.py
index a934fcc4c..b0aab9d57 100644
--- a/tests/unit/pipelex/builder/operations/test_pipe_spec_to_toml.py
+++ b/tests/unit/pipelex/builder/operations/test_pipe_spec_to_toml.py
@@ -47,7 +47,7 @@ class TestPipeSpecToToml:
spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM})
toml = pipe_spec_to_toml(spec)
assert "prompt" in toml
- assert "Write about @text" in toml
+ assert "Write about $text" in toml
def test_llm_no_inputs_omits_inputs(self) -> None:
empty_inputs: dict[str, str] = {}
@@ -171,7 +171,7 @@ class TestPipeSpecToToml:
"inputs": {"query_text": "Text"},
"output": "Text",
"model": "$search-model",
- "prompt": "Search for @query_text",
+ "prompt": "Search for $query_text",
"from_date": "2024-01-01",
"to_date": "2024-12-31",
"include_domains": ["example.com", "docs.example.com"],
@@ -181,7 +181,7 @@ class TestPipeSpecToToml:
)
toml = pipe_spec_to_toml(spec)
assert 'model = "$search-model"' in toml
- assert "Search for @query_text" in toml
+ assert "Search for $query_text" in toml
assert 'from_date = "2024-01-01"' in toml
assert 'to_date = "2024-12-31"' in toml
assert "example.com" in toml
@@ -191,10 +191,10 @@ class TestPipeSpecToToml:
def test_search_minimal(self) -> None:
spec = parse_pipe_spec(
"PipeSearch",
- {"pipe_code": "web_search", "description": "Search", "inputs": {"query_text": "Text"}, "output": "Text", "prompt": "Find @query_text"},
+ {"pipe_code": "web_search", "description": "Search", "inputs": {"query_text": "Text"}, "output": "Text", "prompt": "Find $query_text"},
)
toml = pipe_spec_to_toml(spec)
- assert "Find @query_text" in toml
+ assert "Find $query_text" in toml
assert "from_date" not in toml
assert "to_date" not in toml
assert "include_domains" not in toml
@@ -338,13 +338,13 @@ class TestPipeSpecToToml:
"inputs": {"name": "native.Text"},
"output": "native.Text",
"target_format": "markdown",
- "template": "Hello @name!",
+ "template": "Hello $name!",
},
)
toml = pipe_spec_to_toml(spec)
assert 'type = "PipeCompose"' in toml
assert 'target_format = "markdown"' in toml
- assert 'template = "Hello @name!"' in toml
+ assert 'template = "Hello $name!"' in toml
def test_compose_no_construct_in_template_mode(self) -> None:
spec = parse_pipe_spec(
@@ -355,7 +355,7 @@ class TestPipeSpecToToml:
"inputs": {"name": "native.Text"},
"output": "native.Text",
"target_format": "markdown",
- "template": "Hello @name!",
+ "template": "Hello $name!",
},
)
toml = pipe_spec_to_toml(spec)
diff --git a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_compose/test_pipe_compose_to_toml.py b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_compose/test_pipe_compose_to_toml.py
index dcf7a27a1..cc5506006 100644
--- a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_compose/test_pipe_compose_to_toml.py
+++ b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_compose/test_pipe_compose_to_toml.py
@@ -48,7 +48,7 @@ class _TomlTestCases:
"inputs": {"name": "native.Text"},
"output": "native.Text",
"target_format": "markdown",
- "template": "Hello @name!",
+ "template": "Hello $name!",
},
)
@@ -106,6 +106,6 @@ class TestPipeComposeToToml:
result = pipe_spec_to_toml(pipe_spec)
assert 'target_format = "markdown"' in result
- assert 'template = "Hello @name!"' in result
+ assert 'template = "Hello $name!"' in result
# Construct section should NOT appear
assert "construct" not in result.split("template")[0] # no construct key before template
diff --git a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_data.py b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_data.py
index 4d643ee4d..84ed642a4 100644
--- a/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_data.py
+++ b/tests/unit/pipelex/builder/pipe/pipe_operator/pipe_llm/test_data.py
@@ -115,7 +115,7 @@ class PipeLLMTestCases:
inputs={"data": "Data"},
output="Analysis",
system_prompt="You are a data analyst",
- prompt="Analyze: @data",
+ prompt="Analyze: $data",
model="$retrieval",
),
PipeLLMBlueprint(
@@ -124,7 +124,7 @@ class PipeLLMTestCases:
description="Generate with system prompt",
inputs={"data": "Data"},
system_prompt="You are a data analyst",
- prompt="Analyze: @data",
+ prompt="Analyze: $data",
output="Analysis",
model="$retrieval",
),
diff --git a/tests/unit/pipelex/cli/test_pipe_cmd.py b/tests/unit/pipelex/cli/test_pipe_cmd.py
index 14f09f498..1fc762809 100644
--- a/tests/unit/pipelex/cli/test_pipe_cmd.py
+++ b/tests/unit/pipelex/cli/test_pipe_cmd.py
@@ -26,7 +26,7 @@ class TestCliPipeCmd:
"model": "$writing-creative",
"inputs": {"text": "Text"},
"output": "Text",
- "prompt": "Write about @text",
+ "prompt": "Write about $text",
}
# -- pipe_type alias in JSON (handled by pipe_cmd, not parse_pipe_spec) --
@@ -40,7 +40,7 @@ class TestCliPipeCmd:
"model": "$writing-creative",
"inputs": {"text": "Text"},
"output": "Text",
- "prompt": "Write about @text",
+ "prompt": "Write about $text",
}
pipe_type = spec.pop("type")
result = parse_pipe_spec(pipe_type, spec)
@@ -96,7 +96,7 @@ class TestCliPipeCmd:
def test_toml_contains_prompt(self) -> None:
spec = parse_pipe_spec("PipeLLM", {**self._BASE_LLM})
toml = _pipe_spec_to_toml(spec)
- assert 'prompt = "Write about @text"' in toml
+ assert 'prompt = "Write about $text"' in toml
def test_sequence_toml_has_steps(self) -> None:
spec = parse_pipe_spec(
@@ -125,7 +125,7 @@ class TestCliPipeCmd:
"description": "No model specified",
"inputs": {"text": "Text"},
"output": "Text",
- "prompt": "Write about @text",
+ "prompt": "Write about $text",
},
)
toml = _pipe_spec_to_toml(spec)
@@ -141,7 +141,7 @@ class TestCliPipeCmd:
"model": "$writing-creative",
"inputs": {"idea": "Text"},
"output": {"type": "ImgGenPrompt"},
- "prompt": "Generate a creative image prompt based on @idea",
+ "prompt": "Generate a creative image prompt based on $idea",
}
result = parse_pipe_spec("PipeLLM", spec)
assert result.model == "$writing-creative" # type: ignore[attr-defined]
@@ -155,7 +155,7 @@ class TestCliPipeCmd:
"model": "$writing-creative",
"inputs": {"idea": "Text"},
"output": {"type": "ImgGenPrompt"},
- "prompt": "Generate a creative image prompt based on @idea",
+ "prompt": "Generate a creative image prompt based on $idea",
}
result = parse_pipe_spec("PipeLLM", spec)
toml = _pipe_spec_to_toml(result)
diff --git a/tests/unit/pipelex/cogt/templating/test_template_pipeline.py b/tests/unit/pipelex/cogt/templating/test_template_pipeline.py
index 5363053d2..7ef87089b 100644
--- a/tests/unit/pipelex/cogt/templating/test_template_pipeline.py
+++ b/tests/unit/pipelex/cogt/templating/test_template_pipeline.py
@@ -9,6 +9,7 @@ from typing import ClassVar
import pytest
from pipelex.cogt.templating.template_category import TemplateCategory
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
@@ -17,33 +18,44 @@ class TestData:
"""Test data for template pipeline integration tests."""
# (topic, raw_template, expected_jinja2, expected_variables)
+ # @-sigils must be alone on their line (strict rule). Inline shapes are covered by
+ # AT_VARIABLE_PIPELINE_ERRORS below.
AT_VARIABLE_PIPELINE: ClassVar[list[tuple[str, str, str, set[str]]]] = [
(
- "single_at_variable",
- "Hello @name",
- 'Hello {{ name|tag("name") }}',
+ "single_at_variable_alone",
+ "@name",
+ '{{ name|tag("name") }}',
{"name"},
),
(
- "multiple_at_variables",
- "@first and @second",
- '{{ first|tag("first") }} and {{ second|tag("second") }}',
+ "multiple_at_variables_on_lines",
+ "@first\n@second",
+ '{{ first|tag("first") }}\n{{ second|tag("second") }}',
{"first", "second"},
),
(
- "at_variable_with_trailing_dot",
- "The value is @amount.",
- 'The value is {{ amount|tag("amount") }}.',
+ "at_variable_alone_with_surrounding_lines",
+ "Header\n@amount\nFooter",
+ 'Header\n{{ amount|tag("amount") }}\nFooter',
{"amount"},
),
(
- "nested_at_variable",
- "User: @user.profile.name",
- 'User: {{ user.profile.name|tag("user.profile.name") }}',
+ "nested_at_variable_alone",
+ "@user.profile.name",
+ '{{ user.profile.name|tag("user.profile.name") }}',
{"user.profile.name"},
),
]
+ # Inline @-sigils that violate the strict rule when the root identifier is a declared
+ # input of the surrounding pipe. (topic, raw_template, root_identifier)
+ AT_VARIABLE_PIPELINE_ERRORS: ClassVar[list[tuple[str, str, str]]] = [
+ ("single_at_variable_inline", "Hello @name", "name"),
+ ("multiple_at_variables_inline", "@first and @second", "first"),
+ ("at_variable_with_trailing_dot_inline", "The value is @amount.", "amount"),
+ ("nested_at_variable_inline", "User: @user.profile.name", "user"),
+ ]
+
DOLLAR_VARIABLE_PIPELINE: ClassVar[list[tuple[str, str, str, set[str]]]] = [
(
"single_dollar_variable",
@@ -71,17 +83,18 @@ class TestData:
),
]
+ # @? sigils must be alone on their line (strict rule).
OPTIONAL_VARIABLE_PIPELINE: ClassVar[list[tuple[str, str, str, set[str]]]] = [
(
- "single_optional_variable",
- "Optional: @?optional_field",
- 'Optional: {% if optional_field %}{{ optional_field|tag("optional_field") }}{% endif %}',
+ "single_optional_variable_alone",
+ "@?optional_field",
+ '{% if optional_field %}{{ optional_field|tag("optional_field") }}{% endif %}',
{"optional_field"},
),
(
- "optional_with_trailing_dot",
- "Notes: @?notes.",
- 'Notes: {% if notes %}{{ notes|tag("notes") }}{% endif %}.',
+ "optional_with_surrounding_lines",
+ "Notes:\n@?notes\nDone.",
+ 'Notes:\n{% if notes %}{{ notes|tag("notes") }}{% endif %}\nDone.',
{"notes"},
),
(
@@ -125,7 +138,8 @@ Generated by: {{ author_name|format() }}""",
),
]
- # Real-world complex templates
+ # Real-world complex templates — every @-sigil sits alone on its own line.
+ # Inline values use $-sigils.
REAL_WORLD_TEMPLATES: ClassVar[list[tuple[str, str, set[str]]]] = [
(
"gantt_chart_analysis",
@@ -143,7 +157,8 @@ Here is the name of the task you have to extract the dates for:
),
(
"invoice_extraction_prompt",
- """Extract employee information from this invoice text: @invoice_text.
+ """Extract employee information from this invoice text:
+@invoice_text
The company name is: $company_name
@@ -169,21 +184,25 @@ Please provide:
2. Action items if any
3. Any risks or concerns
-Output format: @output_format""",
+Output format:
+@output_format""",
{"document_content", "context_info", "reference_documents", "output_format"},
),
(
"image_generation_prompt",
"""Generate an image with the following characteristics:
-Subject: @subject_description
+Subject:
+@subject_description
Style: $art_style
-Mood: @mood
+Mood:
+@mood
@?additional_details
Camera angle: $camera_angle
-Lighting: @lighting_type""",
+Lighting:
+@lighting_type""",
{
"subject_description",
"art_style",
@@ -195,10 +214,12 @@ Lighting: @lighting_type""",
),
(
"code_review_prompt",
- """Review the following code: @code_snippet.
+ """Review the following code:
+@code_snippet
Programming language: $language
-Code purpose: @purpose
+Code purpose:
+@purpose
@?coding_standards
@@ -232,7 +253,8 @@ Expected output format: $output_format""",
---
Author: $author_name
Date: $document_date
-Version: @version_info""",
+Version:
+@version_info""",
{
"document_title",
"introduction_text",
@@ -270,8 +292,8 @@ Version: @version_info""",
),
(
"version_and_at_variable",
- "Version @1.0 with @release_notes",
- 'Version @1.0 with {{ release_notes|tag("release_notes") }}',
+ "Version @1.0 with $release_notes",
+ "Version @1.0 with {{ release_notes|format() }}",
{"release_notes"},
),
]
@@ -303,6 +325,19 @@ class TestTemplatePipelineIntegration:
)
assert variables == expected_variables, f"Variable detection failed for topic: {topic}"
+ @pytest.mark.parametrize(
+ ("topic", "raw_template", "root_identifier"),
+ TestData.AT_VARIABLE_PIPELINE_ERRORS,
+ )
+ def test_at_variable_pipeline_raises_when_inline(self, topic: str, raw_template: str, root_identifier: str):
+ """Inline @-sigils whose root identifier is a declared input violate the strict
+ line-bounded rule and raise. The `root_identifier` from the parametrized case is
+ passed as `declared_inputs` to activate the gate.
+ """
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(raw_template, declared_inputs={root_identifier})
+ assert "line " in str(exc_info.value), f"Missing line number in error for topic: {topic}"
+
@pytest.mark.parametrize(
("topic", "raw_template", "expected_jinja2", "expected_variables"),
TestData.DOLLAR_VARIABLE_PIPELINE,
@@ -446,14 +481,18 @@ class TestTemplatePipelineIntegration:
"""Test a template with both Jinja2 and custom syntax."""
raw_template = """Hello {{ existing_var }}!
Your topic is: $topic
-Additional info: @info
-Optional: @?optional_data"""
+Additional info:
+@info
+Optional:
+@?optional_data"""
processed = preprocess_template(raw_template)
expected = """Hello {{ existing_var }}!
Your topic is: {{ topic|format() }}
-Additional info: {{ info|tag("info") }}
-Optional: {% if optional_data %}{{ optional_data|tag("optional_data") }}{% endif %}"""
+Additional info:
+{{ info|tag("info") }}
+Optional:
+{% if optional_data %}{{ optional_data|tag("optional_data") }}{% endif %}"""
assert processed == expected
variables = detect_jinja2_required_variables(
@@ -475,13 +514,17 @@ Optional: {% if optional_data %}{{ optional_data|tag("optional_data") }}{% endif
def test_pipeline_across_template_categories(self, template_category: TemplateCategory):
"""Test the pipeline works across different template categories."""
raw_template = """Title: $title
-Content: @content
-Optional: @?optional"""
+Content:
+@content
+Optional:
+@?optional"""
processed = preprocess_template(raw_template)
expected = """Title: {{ title|format() }}
-Content: {{ content|tag("content") }}
-Optional: {% if optional %}{{ optional|tag("optional") }}{% endif %}"""
+Content:
+{{ content|tag("content") }}
+Optional:
+{% if optional %}{{ optional|tag("optional") }}{% endif %}"""
assert processed == expected
variables = detect_jinja2_required_variables(
@@ -538,12 +581,18 @@ Date: $generation_date
assert variables == expected_vars
def test_variable_used_multiple_times(self):
- """Test that a variable used multiple times is detected only once."""
+ """Test that a variable used multiple times is detected only once.
+
+ Under the strict rule, the `@`/`@?` forms must each sit alone on their line; the
+ inline shape is the `$` form.
+ """
raw_template = """
-@name appears here.
-And @name appears again.
+@name
+And here again:
+@name
Also $name as dollar variable.
-And @?name as optional.
+And as optional:
+@?name
"""
processed = preprocess_template(raw_template)
variables = detect_jinja2_required_variables(
@@ -554,11 +603,13 @@ And @?name as optional.
assert variables == {"name"}
def test_deeply_nested_variable_names(self):
- """Test variables with deep dot notation."""
+ """Test variables with deep dot notation. @-sigils sit alone on their line."""
raw_template = """
-User info: @user.profile.settings.preferences.theme
+User info:
Config: $app.config.database.connection.host
-Optional: @?system.logs.archive.old.entries
+Optional:
+@?system.logs.archive.old.entries
"""
processed = preprocess_template(raw_template)
variables = detect_jinja2_required_variables(
diff --git a/tests/unit/pipelex/cogt/templating/test_template_preprocessor.py b/tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
index e2fd2ab3d..bcd7b6b48 100644
--- a/tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
+++ b/tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
@@ -1,4 +1,7 @@
+import pytest
+
from pipelex import pretty_print
+from pipelex.cogt.templating.template_errors import TemplateSigilSyntaxError
from pipelex.cogt.templating.template_preprocessor import preprocess_template
@@ -75,9 +78,9 @@ Optional notes:
def test_optional_pattern_priority(self):
"""Test that @? pattern is processed before @ pattern."""
# This ensures @? doesn't get matched as @ followed by ?
- template = "@?optional @required"
+ template = "@?optional\n@required"
result = preprocess_template(template)
- expected = '{% if optional %}{{ optional|tag("optional") }}{% endif %} {{ required|tag("required") }}'
+ expected = '{% if optional %}{{ optional|tag("optional") }}{% endif %}\n{{ required|tag("required") }}'
assert result == expected
def test_dollar_amounts_not_processed(self):
@@ -112,35 +115,30 @@ Optional notes:
assert result == template
def test_mixed_at_patterns_with_numbers(self):
- """Test mixing @ patterns with numbers and valid variables."""
- template = "Version @1.0, build @?2.3.4, and @valid_var with @?optional_var"
+ """Test mixing @ patterns with numbers and valid variables.
+
+ `@1.0` / `@?2.3.4` aren't candidate sigils (digit after `@`), so they pass through.
+ The legitimate variables go on their own lines per the strict rule.
+ """
+ template = "Version @1.0, build @?2.3.4\n@valid_var\n@?optional_var"
result = preprocess_template(template)
expected = (
- "Version @1.0, build @?2.3.4, and "
- '{{ valid_var|tag("valid_var") }} with '
- '{% if optional_var %}{{ optional_var|tag("optional_var") }}{% endif %}'
+ 'Version @1.0, build @?2.3.4\n{{ valid_var|tag("valid_var") }}\n{% if optional_var %}{{ optional_var|tag("optional_var") }}{% endif %}'
)
assert result == expected
- def test_at_variable_with_trailing_dot(self):
- """Test @variable pattern with trailing dot (punctuation)."""
- template = "Extract employee information from this invoice text: @invoice_text."
- result = preprocess_template(template)
- expected = 'Extract employee information from this invoice text: {{ invoice_text|tag("invoice_text") }}.'
- assert result == expected
-
- def test_optional_at_variable_with_trailing_dot(self):
- """Test @?variable pattern with trailing dot (punctuation)."""
- template = "Optional information: @?optional_data."
+ def test_dollar_variable_with_trailing_dot_in_sentence(self):
+ """Inline $variable with trailing dot — $ keeps its inline contract."""
+ template = "Extract employee information from this invoice text: $invoice_text."
result = preprocess_template(template)
- expected = 'Optional information: {% if optional_data %}{{ optional_data|tag("optional_data") }}{% endif %}.'
+ expected = "Extract employee information from this invoice text: {{ invoice_text|format() }}."
assert result == expected
- def test_multiple_at_variables_with_trailing_dots(self):
- """Test multiple @variable patterns with trailing dots."""
- template = "Extract all articles from this invoice text: @invoice_text. Process the items: @item_list."
+ def test_multiple_dollar_variables_with_trailing_dots(self):
+ """Inline $variable patterns with trailing dots — $ keeps its inline contract."""
+ template = "Extract all articles from this invoice text: $invoice_text. Process the items: $item_list."
result = preprocess_template(template)
- expected = """Extract all articles from this invoice text: {{ invoice_text|tag("invoice_text") }}. Process the items: {{ item_list|tag("item_list") }}.""" # noqa: E501
+ expected = "Extract all articles from this invoice text: {{ invoice_text|format() }}. Process the items: {{ item_list|format() }}."
pretty_print(result, title="result")
pretty_print(expected, title="expected")
@@ -178,8 +176,13 @@ Here is the name of the task you have to extract the dates for:
assert result == expected
def test_invoice_extraction_template(self):
- """Test real-world invoice extraction template."""
- template = """Extract employee information from this invoice text: @invoice_text.
+ """Test real-world invoice extraction template.
+
+ The block-shaped invoice body goes on its own line (`@invoice_text`); the inline
+ company name uses `$company_name`.
+ """
+ template = """Extract employee information from this invoice text:
+@invoice_text
The company name is: $company_name
@@ -191,7 +194,8 @@ Please extract the following fields:
@?additional_instructions"""
result = preprocess_template(template)
- expected = """Extract employee information from this invoice text: {{ invoice_text|tag("invoice_text") }}.
+ expected = """Extract employee information from this invoice text:
+{{ invoice_text|tag("invoice_text") }}
The company name is: {{ company_name|format() }}
@@ -208,71 +212,64 @@ Please extract the following fields:
# Edge cases with punctuation and special characters
# =========================================================================
- def test_variable_followed_by_comma(self):
- """Test variable followed by comma."""
- template = "Values: @first, @second, and @third"
- result = preprocess_template(template)
- expected = 'Values: {{ first|tag("first") }}, {{ second|tag("second") }}, and {{ third|tag("third") }}'
- assert result == expected
-
- def test_variable_followed_by_colon(self):
- """Test variable followed by colon."""
- template = "@label: the value is @value"
+ def test_dollar_variable_followed_by_comma(self):
+ """Inline $variable followed by comma — $ keeps its inline contract."""
+ template = "Values: $first, $second, and $third"
result = preprocess_template(template)
- expected = '{{ label|tag("label") }}: the value is {{ value|tag("value") }}'
+ expected = "Values: {{ first|format() }}, {{ second|format() }}, and {{ third|format() }}"
assert result == expected
- def test_variable_followed_by_semicolon(self):
- """Test variable followed by semicolon."""
- template = "First: @first; Second: @second"
+ def test_dollar_variable_followed_by_colon(self):
+ """Inline $variable followed by colon."""
+ template = "$label: the value is $value"
result = preprocess_template(template)
- expected = 'First: {{ first|tag("first") }}; Second: {{ second|tag("second") }}'
+ expected = "{{ label|format() }}: the value is {{ value|format() }}"
assert result == expected
- def test_variable_in_parentheses(self):
- """Test variable inside parentheses."""
- template = "The value (@value) is important"
+ def test_dollar_variable_followed_by_semicolon(self):
+ """Inline $variable followed by semicolon."""
+ template = "First: $first; Second: $second"
result = preprocess_template(template)
- expected = 'The value ({{ value|tag("value") }}) is important'
+ expected = "First: {{ first|format() }}; Second: {{ second|format() }}"
assert result == expected
- def test_variable_in_brackets(self):
- """Test variable inside square brackets."""
- template = "Array element [$index] = @element"
+ def test_dollar_variable_in_brackets(self):
+ """Inline $variable inside square brackets and surrounding context."""
+ template = "Array element [$index] = $element"
result = preprocess_template(template)
- expected = 'Array element [{{ index|format() }}] = {{ element|tag("element") }}'
+ expected = "Array element [{{ index|format() }}] = {{ element|format() }}"
assert result == expected
- def test_variable_followed_by_question_mark(self):
- """Test variable followed by question mark (but not @? pattern)."""
- template = "Is @value correct?"
+ def test_dollar_variable_followed_by_question_mark(self):
+ """Inline $variable followed by question mark."""
+ template = "Is $value correct?"
result = preprocess_template(template)
- expected = 'Is {{ value|tag("value") }} correct?'
+ expected = "Is {{ value|format() }} correct?"
assert result == expected
- def test_variable_followed_by_exclamation(self):
- """Test variable followed by exclamation mark."""
- template = "Hello @name!"
+ def test_dollar_variable_followed_by_exclamation(self):
+ """Inline $variable followed by exclamation mark."""
+ template = "Hello $name!"
result = preprocess_template(template)
- expected = 'Hello {{ name|tag("name") }}!'
+ expected = "Hello {{ name|format() }}!"
assert result == expected
# =========================================================================
# Variables at different positions
# =========================================================================
- def test_variable_at_start_of_line(self):
- """Test variable at the start of a line."""
- template = "@start_var is at the beginning"
+ def test_dollar_variable_at_start_of_line(self):
+ """Inline $variable at the start of a line."""
+ template = "$start_var is at the beginning"
result = preprocess_template(template)
- expected = '{{ start_var|tag("start_var") }} is at the beginning'
+ expected = "{{ start_var|format() }} is at the beginning"
assert result == expected
- def test_variable_at_end_of_line(self):
- """Test variable at the end of a line (no trailing punctuation)."""
- template = "The value is @end_var"
+ def test_dollar_variable_at_end_of_line(self):
+ """Inline $variable at the end of a line (no trailing punctuation)."""
+ template = "The value is $end_var"
result = preprocess_template(template)
- expected = 'The value is {{ end_var|tag("end_var") }}'
+ expected = "The value is {{ end_var|format() }}"
assert result == expected
def test_variable_alone_on_line(self):
@@ -286,11 +283,11 @@ Line after"""
Line after"""
assert result == expected
- def test_back_to_back_at_variables(self):
- """Test multiple @ variables back to back with space."""
- template = "@first @second @third"
+ def test_back_to_back_at_variables_alone_on_lines(self):
+ """Multiple @ variables back to back on consecutive lines (each alone on line)."""
+ template = "@first\n@second\n@third"
result = preprocess_template(template)
- expected = '{{ first|tag("first") }} {{ second|tag("second") }} {{ third|tag("third") }}'
+ expected = '{{ first|tag("first") }}\n{{ second|tag("second") }}\n{{ third|tag("third") }}'
assert result == expected
def test_back_to_back_dollar_variables(self):
@@ -329,11 +326,11 @@ Line after"""
# Variable names with underscores
# =========================================================================
- def test_variable_with_leading_underscore(self):
- """Test variable name starting with underscore."""
- template = "@_private_var and $_another_private"
+ def test_dollar_variable_with_leading_underscore(self):
+ """Inline $variable names starting with underscore."""
+ template = "$_private_var and $_another_private"
result = preprocess_template(template)
- expected = '{{ _private_var|tag("_private_var") }} and {{ _another_private|format() }}'
+ expected = "{{ _private_var|format() }} and {{ _another_private|format() }}"
assert result == expected
def test_variable_with_multiple_underscores(self):
@@ -350,29 +347,71 @@ Line after"""
expected = '{{ trailing_|tag("trailing_") }}'
assert result == expected
+ @pytest.mark.parametrize(
+ ("template", "expected"),
+ [
+ ("value is $_ here", "value is {{ _|format() }} here"),
+ ("@_", '{{ _|tag("_") }}'),
+ ("@?_", '{% if _ %}{{ _|tag("_") }}{% endif %}'),
+ ],
+ ids=["inline_dollar_bare_underscore", "alone_at_bare_underscore", "alone_optional_at_bare_underscore"],
+ )
+ def test_bare_underscore_is_a_valid_identifier(self, template: str, expected: str):
+ """The identifier shape `[a-zA-Z_][a-zA-Z0-9_]*` allows a single `_`, so `$_`, `@_`,
+ and `@?_` are valid sigils and rewrite. The `*` quantifier on the trailing chars
+ makes this a real code path — lock it in so a future tightening of the identifier
+ regex catches it.
+ """
+ assert preprocess_template(template) == expected
+
# =========================================================================
# Mixed scenarios
# =========================================================================
- def test_all_pattern_types_in_one_line(self):
- """Test all three pattern types in a single line."""
- template = "$dollar_var @at_var @?optional_var"
+ def test_all_pattern_types_across_lines(self):
+ """Inline $ + line-bounded @ + line-bounded @? all in one template."""
+ template = "$dollar_var\n@at_var\n@?optional_var"
result = preprocess_template(template)
- expected = '{{ dollar_var|format() }} {{ at_var|tag("at_var") }} {% if optional_var %}{{ optional_var|tag("optional_var") }}{% endif %}'
+ expected = '{{ dollar_var|format() }}\n{{ at_var|tag("at_var") }}\n{% if optional_var %}{{ optional_var|tag("optional_var") }}{% endif %}'
assert result == expected
- def test_nested_with_trailing_dot_in_complex_sentence(self):
- """Test nested variable with trailing dot in complex context."""
- template = "The user's preference is @user.settings.theme. Please apply it."
+ def test_nested_dollar_with_trailing_dot_in_complex_sentence(self):
+ """Nested $variable with trailing dot in complex context."""
+ template = "The user's preference is $user.settings.theme. Please apply it."
result = preprocess_template(template)
- expected = 'The user\'s preference is {{ user.settings.theme|tag("user.settings.theme") }}. Please apply it.'
+ expected = "The user's preference is {{ user.settings.theme|format() }}. Please apply it."
assert result == expected
- def test_variable_adjacent_to_newline(self):
- """Test variable immediately before newline."""
- template = "First: @first\nSecond: @second"
+ @pytest.mark.parametrize(
+ ("template", "expected"),
+ [
+ (
+ "Summarize $user's data",
+ "Summarize {{ user|format() }}'s data",
+ ),
+ (
+ "It's $user's preference, not $admin's.",
+ "It's {{ user|format() }}'s preference, not {{ admin|format() }}'s.",
+ ),
+ (
+ "Apply $user.profile.theme's variant to the page.",
+ "Apply {{ user.profile.theme|format() }}'s variant to the page.",
+ ),
+ ],
+ ids=["single_possessive", "two_possessives", "dotted_path_possessive"],
+ )
+ def test_dollar_sigil_interpolates_through_possessive_apostrophe(self, template: str, expected: str):
+ """`$var's` (possessive) must interpolate `$var` — the zero-space adjacency to `'`
+ is natural prose, not a shell-style `$foo 'arg'` construct (which requires a space
+ before the quote and stays blocked).
+ """
+ assert preprocess_template(template) == expected
+
+ def test_dollar_variable_adjacent_to_newline(self):
+ """Inline $variable immediately before newline."""
+ template = "First: $first\nSecond: $second"
result = preprocess_template(template)
- expected = 'First: {{ first|tag("first") }}\nSecond: {{ second|tag("second") }}'
+ expected = "First: {{ first|format() }}\nSecond: {{ second|format() }}"
assert result == expected
def test_empty_template(self):
@@ -395,12 +434,12 @@ Line after"""
assert result == expected
def test_multiple_optional_variables_in_sequence(self):
- """Test multiple optional variables in sequence."""
- template = "@?first @?second @?third"
+ """Multiple @? optional variables on consecutive lines (each alone on line)."""
+ template = "@?first\n@?second\n@?third"
result = preprocess_template(template)
expected = (
- '{% if first %}{{ first|tag("first") }}{% endif %} '
- '{% if second %}{{ second|tag("second") }}{% endif %} '
+ '{% if first %}{{ first|tag("first") }}{% endif %}\n'
+ '{% if second %}{{ second|tag("second") }}{% endif %}\n'
'{% if third %}{{ third|tag("third") }}{% endif %}'
)
assert result == expected
@@ -409,18 +448,11 @@ Line after"""
# Edge cases with @ symbol in non-variable contexts
# =========================================================================
- def test_email_address_partially_processed(self):
- """Test that email-like patterns are partially processed (after @).
-
- The regex pattern [a-zA-Z0-9_.] matches 'example.com' as a single variable
- name since dots are allowed in variable names.
- """
- # Note: [email protected] will match 'domain.ext' as variable after @
+ def test_email_address_pass_through(self):
+ """Email addresses must not be rewritten — the lookbehind on @ prevents it."""
template = "Contact: [email protected]"
result = preprocess_template(template)
- # After @ we have example.com which matches entirely as variable name
- expected = 'Contact: someone{{ example.com|tag("example.com") }}'
- assert result == expected
+ assert result == template
def test_at_sign_alone(self):
"""Test @ sign alone (not followed by valid variable name char)."""
@@ -430,8 +462,915 @@ Line after"""
assert result == expected
def test_dollar_sign_alone(self):
- """Test $ sign alone (not followed by valid variable name char)."""
- template = "Cost is $ for @item"
+ """Test $ sign alone (not followed by valid variable name char) with inline $variable."""
+ template = "Cost is $ for $item"
+ result = preprocess_template(template)
+ expected = "Cost is $ for {{ item|format() }}"
+ assert result == expected
+
+ # =========================================================================
+ # CSS at-rule strict-rule violations — each raises (escape with `@@` to opt out).
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ ("template", "expected_sigil_and_identifier"),
+ [
+ ("@media (max-width: 820px) { color: red; }", "@media"),
+ ("@supports (display: grid) { color: red; }", "@supports"),
+ ('@import "reset.css";', "@import"),
+ ('@import url("reset.css");', "@import"),
+ ('@charset "UTF-8";', "@charset"),
+ ('@namespace svg "http://www.w3.org/2000/svg";', "@namespace"),
+ ("@keyframes spin { from { opacity: 0; } to { opacity: 1; } }", "@keyframes"),
+ ("@page { margin: 1in; }", "@page"),
+ ("@layer reset { color: red; }", "@layer"),
+ ("@container (width > 400px) { color: red; }", "@container"),
+ ('@font-face { font-family: "X"; }', "@font"),
+ ],
+ ids=[
+ "media",
+ "supports",
+ "import_string",
+ "import_url",
+ "charset",
+ "namespace",
+ "keyframes",
+ "page",
+ "layer_named",
+ "container",
+ "font_face",
+ ],
+ )
+ def test_css_at_rule_raises_when_keyword_is_declared_input(self, template: str, expected_sigil_and_identifier: str):
+ """CSS at-rules are inline `@` candidates — when the at-rule keyword (`media`,
+ `keyframes`, ...) is a declared input of the surrounding pipe, the validator treats
+ it as a real typo and raises. Authors escape with `@@` to opt out (see companion
+ `*_escaped_pass_through` tests).
+ """
+ identifier = expected_sigil_and_identifier.lstrip("@")
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={identifier})
+ error_message = str(exc_info.value)
+ assert "line 1" in error_message
+ assert expected_sigil_and_identifier in error_message
+
+ def test_css_namespace_escaped_pass_through(self):
+ """Author workaround for @namespace: escape with @@namespace."""
+ template = '@@namespace svg "http://www.w3.org/2000/svg";'
+ result = preprocess_template(template)
+ expected = '@namespace svg "http://www.w3.org/2000/svg";'
+ assert result == expected
+
+ def test_css_font_face_escaped_pass_through(self):
+ """Author workaround for @font-face: escape with @@font-face."""
+ template = '@@font-face { font-family: "X"; }'
+ result = preprocess_template(template)
+ expected = '@font-face { font-family: "X"; }'
+ assert result == expected
+
+ def test_full_style_block_raises_when_keyword_is_declared_input(self):
+ """When `media` is a declared input of the pipe, an inline `@media` at-rule in a
+ <style> block is treated as a real typo and raises.
+ """
+ template = """<style>
+ .page { padding: 32px; }
+ @media (max-width: 820px) {
+ .page { padding: 24px; }
+ }
+ @supports (display: grid) {
+ .grid { display: grid; }
+ }
+</style>"""
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={"media"})
+ error_message = str(exc_info.value)
+ assert "line 3" in error_message
+ assert "@media" in error_message
+ assert "@@" in error_message # escape hint must be present
+
+ def test_full_style_block_escaped_pass_through(self):
+ """Authors escape every CSS at-rule in a <style> block with `@@` to opt out of
+ strict-rule enforcement; the doubled sigils restore to literal `@` and nothing
+ is rewritten as a Pipelex sigil.
+ """
+ template = """<style>
+ .page { padding: 32px; }
+ @@media (max-width: 820px) {
+ .page { padding: 24px; }
+ }
+ @@supports (display: grid) {
+ .grid { display: grid; }
+ }
+</style>"""
+ expected = """<style>
+ .page { padding: 32px; }
+ @media (max-width: 820px) {
+ .page { padding: 24px; }
+ }
+ @supports (display: grid) {
+ .grid { display: grid; }
+ }
+</style>"""
+ assert preprocess_template(template) == expected
+
+ # =========================================================================
+ # Email / word-adjacent @ pass-through (heuristic lookbehind)
+ # =========================================================================
+
+ def test_email_in_sentence_pass_through(self):
+ """Email address embedded in a sentence must not be rewritten."""
+ template = "Contact us at [email protected] for help."
+ result = preprocess_template(template)
+ assert result == template
+
+ def test_word_adjacent_at_pass_through(self):
+ """@ preceded by a word character (email-like) must not be rewritten."""
+ template = "Send to [email protected] immediately."
+ result = preprocess_template(template)
+ assert result == template
+
+ # =========================================================================
+ # Code-like punctuation regression guards (already pass today, locked in by lookahead)
+ # =========================================================================
+
+ def test_jquery_call_pass_through(self):
+ """jQuery-style $("...") call must not be rewritten."""
+ template = '$("body").addClass("x")'
+ result = preprocess_template(template)
+ assert result == template
+
+ def test_bash_subshell_pass_through(self):
+ """Bash subshell $(...) must not be rewritten."""
+ template = "result=$(date +%s)"
+ result = preprocess_template(template)
+ assert result == template
+
+ def test_dollar_brace_pass_through(self):
+ """Shell ${VAR} must not be rewritten."""
+ template = "Use ${PATH} for the path."
+ result = preprocess_template(template)
+ assert result == template
+
+ # =========================================================================
+ # Code-shape lookahead must not leak across newlines.
+ # The trailing `(?![ \t]*[({\"'])` guard is same-line only: it blocks inline
+ # constructs like `$foo(...)` but must NOT suppress `$var` when the *next*
+ # line happens to start with `{`, `(`, `"`, or `'`.
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ ("template", "expected"),
+ [
+ (
+ "Value: $price\n{{ extra }}",
+ "Value: {{ price|format() }}\n{{ extra }}",
+ ),
+ (
+ "foo: $name\n'hello'",
+ "foo: {{ name|format() }}\n'hello'",
+ ),
+ (
+ "Hello $user\n (parens)",
+ "Hello {{ user|format() }}\n (parens)",
+ ),
+ (
+ 'Hello $user\n "quoted"',
+ 'Hello {{ user|format() }}\n "quoted"',
+ ),
+ (
+ "first $a\nsecond $b\n{ braces }",
+ "first {{ a|format() }}\nsecond {{ b|format() }}\n{ braces }",
+ ),
+ ],
+ ids=[
+ "next_line_jinja_brace",
+ "next_line_single_quote",
+ "next_line_paren",
+ "next_line_double_quote",
+ "two_dollars_then_brace_line",
+ ],
+ )
+ def test_dollar_at_eol_before_code_shape_opener_on_next_line(self, template: str, expected: str):
+ """`$var` ending a line must still be rewritten when the following line
+ starts with a code-shape opener. The same-line code-shape guard must not
+ leak across the newline.
+ """
+ assert preprocess_template(template) == expected
+
+ @pytest.mark.parametrize(
+ ("template", "expected"),
+ [
+ ("result is $value)", "result is {{ value|format() }})"),
+ ("items: $list]", "items: {{ list|format() }}]"),
+ ("end of $section}", "end of {{ section|format() }}}"),
+ ],
+ ids=[
+ "closing_paren",
+ "closing_bracket",
+ "closing_brace",
+ ],
+ )
+ def test_dollar_followed_by_closing_delimiter_rewrites(self, template: str, expected: str):
+ """Closing delimiters (`)`, `]`, `}`) are not code-shape openers. `$var`
+ immediately before them must rewrite — they are natural punctuation
+ closing a parenthetical phrase, not a function call or string.
+ """
+ assert preprocess_template(template) == expected
+
+ # =========================================================================
+ # Unicode whitespace contract — both sigil patterns recognize ASCII space/tab
+ # only. NBSP (U+00A0), EM SPACE (U+2003) and friends are treated as opaque
+ # text, not whitespace. These tests lock in that intentional contract.
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ ("template", "expected"),
+ [
+ ('$foo\xa0"bar"', '{{ foo|format() }}\xa0"bar"'),
+ ('$foo "bar"', '{{ foo|format() }} "bar"'),
+ ("$foo\xa0'bar'", "{{ foo|format() }}\xa0'bar'"),
+ ],
+ ids=["nbsp_before_dquote", "em_space_before_dquote", "nbsp_before_squote"],
+ )
+ def test_dollar_code_shape_guard_is_ascii_whitespace_only(self, template: str, expected: str):
+ r"""The `$` trailing code-shape guard `(?![ \t]+[({\"'])` matches ASCII space/tab only.
+ Non-ASCII whitespace (NBSP, EM SPACE) is not treated as a separator, so
+ `$foo<NBSP>"bar"` interpolates `$foo` — consistent with natural-prose interpretation
+ of non-ASCII whitespace as opaque text.
+ """
+ assert preprocess_template(template) == expected
+
+ @pytest.mark.parametrize(
+ "template",
+ [
+ "\xa0@var\n",
+ "@var\xa0\n",
+ " @var\n",
+ ],
+ ids=["nbsp_leading", "nbsp_trailing", "em_space_leading"],
+ )
+ def test_at_sigil_line_bounded_pattern_is_ascii_whitespace_only(self, template: str):
+ """`_AT_SIGIL_PATTERN` accepts ASCII space/tab only for leading/trailing whitespace.
+ Lines padded with non-ASCII whitespace are NOT recognized as line-bounded `@var`
+ and pass through unchanged (no rewrite, no error when `declared_inputs is None`).
+ """
+ assert preprocess_template(template) == template
+
+ def test_at_validator_flags_non_ascii_whitespace_indentation(self):
+ """When `@var` is alone on a line but padded with non-ASCII whitespace (e.g. NBSP
+ from rich-text copy-paste) and `var` is a declared input, the validator must emit
+ a clear error pointing at the whitespace problem — not the misleading "must appear
+ alone on its own line" message (the line IS alone, just padded with non-ASCII
+ whitespace).
+ """
+ template = "\xa0@var\xa0"
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={"var"})
+ error_message = str(exc_info.value)
+ assert "non-ASCII whitespace" in error_message
+ assert "@var" in error_message
+ assert "line 1" in error_message
+
+ # =========================================================================
+ # Escape sequences: @@ → literal @, $$ → literal $
+ # =========================================================================
+
+ def test_double_at_escapes_to_literal_at(self):
+ """@@media must collapse to literal @media with no interpolation."""
+ template = "@@media (max-width: 820px) { color: red; }"
+ result = preprocess_template(template)
+ expected = "@media (max-width: 820px) { color: red; }"
+ assert result == expected
+
+ def test_double_at_makes_at_var_literal(self):
+ """@@var must collapse to literal @var (no {{ ... }} interpolation)."""
+ template = "Use @@var here."
result = preprocess_template(template)
- expected = 'Cost is $ for {{ item|tag("item") }}'
+ expected = "Use @var here."
assert result == expected
+
+ def test_double_dollar_escapes_to_literal_dollar(self):
+ """$$10 must collapse to literal $10."""
+ template = "Cost is $$10."
+ result = preprocess_template(template)
+ expected = "Cost is $10."
+ assert result == expected
+
+ def test_double_dollar_makes_dollar_var_literal(self):
+ """$$var must collapse to literal $var (no interpolation)."""
+ template = "Use $$var here."
+ result = preprocess_template(template)
+ expected = "Use $var here."
+ assert result == expected
+
+ def test_escape_does_not_consume_legit_variable(self):
+ """Escape on one token must not affect a legitimate variable later in the string."""
+ template = "@@media is literal, but $width is a variable."
+ result = preprocess_template(template)
+ expected = "@media is literal, but {{ width|format() }} is a variable."
+ assert result == expected
+
+ def test_triple_at_raises_when_var_is_declared_input(self):
+ """`@@@var` post-sentinel becomes literal `@` + `@var`; the `@var` is no longer alone
+ on its line (the sentinel-substituted `@` sits in front of it). When `var` is a
+ declared input, the validator treats this as a real typo and raises. Authors who
+ want literal `@` followed by an interpolated `@var` must move the variable onto its
+ own line.
+ """
+ template = "@@@var"
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={"var"})
+ error_message = str(exc_info.value)
+ assert "@var" in error_message
+ assert "line 1" in error_message
+
+ def test_quadruple_at_is_two_escapes(self):
+ """@@@@var → @@var — two non-overlapping escapes, no interpolation."""
+ template = "@@@@var"
+ result = preprocess_template(template)
+ expected = "@@var"
+ assert result == expected
+
+ def test_triple_dollar_is_literal_dollar_plus_interpolated_var(self):
+ """`$$$var` is left-to-right `$$` (escape → literal `$`) + `$var` (interpolated).
+ Parallels the `@@@var` semantics — `str.replace` finds non-overlapping `$$` first,
+ leaving a single `$` next to the identifier which the `$` rewriter then picks up.
+ """
+ template = "Line $$$var here"
+ result = preprocess_template(template)
+ expected = "Line ${{ var|format() }} here"
+ assert result == expected
+
+ def test_double_dollar_alone_on_line_is_literal_dollar(self):
+ """`$$` on its own line collapses to a literal `$` — the sentinel-then-restore
+ pipeline does not produce a stray sigil or a spurious rewrite.
+ """
+ template = "Line 1\n$$\nLine 2"
+ result = preprocess_template(template)
+ expected = "Line 1\n$\nLine 2"
+ assert result == expected
+
+ def test_escape_inside_style_block(self):
+ """@@font-face inside a <style> block restores to literal @font-face."""
+ template = '<style>@@font-face { font-family: "X"; }</style>'
+ result = preprocess_template(template)
+ expected = '<style>@font-face { font-family: "X"; }</style>'
+ assert result == expected
+
+ # =========================================================================
+ # Broader CSS class (hyphenated names / dash arguments): each raises under the
+ # strict line-bounded `@` rule; authors escape with `@@`.
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ ("template", "expected_sigil_and_identifier"),
+ [
+ ("@property --my-color { syntax: '<color>'; inherits: false; }", "@property"),
+ ("@counter-style thumbs { system: cyclic; }", "@counter"),
+ ("@color-profile --swop5c { src: url('x.icc'); }", "@color"),
+ ("@view-transition { navigation: auto; }", "@view"),
+ ],
+ ids=["property", "counter-style", "color-profile", "view-transition"],
+ )
+ def test_css_dash_at_rule_raises_when_keyword_is_declared_input(self, template: str, expected_sigil_and_identifier: str):
+ """At-rules with hyphenated names or dash arguments raise when the at-rule's leading
+ identifier (the part before the hyphen) is a declared input of the pipe. The validator
+ captures only the leading `@` + identifier (it stops at the hyphen boundary, just like
+ the rewriter), and the diagnostic still names the right line and migration hint.
+ """
+ identifier = expected_sigil_and_identifier.lstrip("@")
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={identifier})
+ error_message = str(exc_info.value)
+ assert "line 1" in error_message
+ assert expected_sigil_and_identifier in error_message
+
+ def test_css_dash_at_rule_escape_workaround(self):
+ """`@@property --my-color { ... }` proves the documented workaround for the
+ hyphenated/dash-arg CSS class.
+ """
+ template = "@@property --my-color { syntax: '<color>'; inherits: false; }"
+ result = preprocess_template(template)
+ expected = "@property --my-color { syntax: '<color>'; inherits: false; }"
+ assert result == expected
+
+ # =========================================================================
+ # Strict line-bounded `@` sigil contract — alone-on-line success cases
+ # (Phase 2 contract: `@var` and `@?var` are valid only when alone on their line.
+ # Leading and trailing whitespace is preserved through the rewrite so templates
+ # embedded in indented YAML/TOML blocks survive a round-trip.)
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ ("template", "expected"),
+ [
+ ("@var", '{{ var|tag("var") }}'),
+ ("@?var", '{% if var %}{{ var|tag("var") }}{% endif %}'),
+ ("@user.profile.bio", '{{ user.profile.bio|tag("user.profile.bio") }}'),
+ ("@_private_var", '{{ _private_var|tag("_private_var") }}'),
+ (" @indented_var", ' {{ indented_var|tag("indented_var") }}'),
+ ("@var\t", '{{ var|tag("var") }}\t'),
+ (
+ "\t@?indented_optional",
+ '\t{% if indented_optional %}{{ indented_optional|tag("indented_optional") }}{% endif %}',
+ ),
+ (
+ "Line before\n @middle\nLine after",
+ 'Line before\n {{ middle|tag("middle") }}\nLine after',
+ ),
+ ],
+ ids=[
+ "bare_at_var",
+ "bare_optional_at_var",
+ "dotted_at_var",
+ "underscore_prefixed_at_var",
+ "indented_at_var",
+ "trailing_tab_at_var",
+ "tab_indented_optional_at_var",
+ "indented_at_var_in_block",
+ ],
+ )
+ def test_strict_line_at_sigil_success(self, template: str, expected: str):
+ """Alone-on-line @ / @? sigils (with optional leading/trailing whitespace)
+ rewrite correctly; whitespace is preserved.
+ """
+ assert preprocess_template(template) == expected
+
+ @pytest.mark.parametrize(
+ ("template", "expected"),
+ [
+ (
+ "Header\r\n@payload\r\nFooter",
+ 'Header\n{{ payload|tag("payload") }}\nFooter',
+ ),
+ (
+ "@only_var\r\n",
+ '{{ only_var|tag("only_var") }}\n',
+ ),
+ (
+ "Old Mac\r@payload\rEnd",
+ 'Old Mac\n{{ payload|tag("payload") }}\nEnd',
+ ),
+ ],
+ ids=["crlf_surrounded", "crlf_terminated", "cr_only_old_mac"],
+ )
+ def test_strict_line_at_sigil_handles_crlf_and_cr_line_endings(self, template: str, expected: str):
+ r"""Lines terminated with `\r\n` (Windows) or `\r` (classic Mac) must not be misread as
+ inline candidates. Line endings are normalized to `\n` at the top of the preprocessor,
+ so the alone-on-line sigil rewrites correctly and the validator does not raise. The
+ normalized `\n`-only output is what downstream Jinja rendering sees.
+ """
+ assert preprocess_template(template) == expected
+
+ # =========================================================================
+ # Strict line-bounded `@` sigil contract — error cases (raises)
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ ("template", "expected_line", "expected_sigil", "expected_identifier"),
+ [
+ # Inline mid-sentence
+ ("Extract from @invoice_text. Done.", 1, "@", "invoice_text"),
+ # Inline trailing punctuation
+ ("@var.", 1, "@", "var"),
+ ("@var,", 1, "@", "var"),
+ ("@var!", 1, "@", "var"),
+ ("@var?", 1, "@", "var"),
+ ("@var;", 1, "@", "var"),
+ ("@var:", 1, "@", "var"),
+ # Inline parenthetical / bracketed
+ ("(@var)", 1, "@", "var"),
+ ("[@var]", 1, "@", "var"),
+ # Multiple sigils per line
+ ("@a @b", 1, "@", "a"),
+ ("@a $b", 1, "@", "a"),
+ ("$b @a", 1, "@", "a"),
+ # Word-adjacent (space before — not email)
+ ("Word @var", 1, "@", "var"),
+ ("@var Word", 1, "@", "var"),
+ # Optional sigil inline
+ ("Hello @?notes", 1, "@?", "notes"),
+ # CSS at-rules — no longer pass-through
+ ("@media (max-width: 820px) {", 1, "@", "media"),
+ ('@font-face { font-family: "X"; }', 1, "@", "font"),
+ ('@import url("reset.css");', 1, "@", "import"),
+ ("@keyframes spin { from { opacity: 0; } }", 1, "@", "keyframes"),
+ # Code constructs (`@Override` alone on its line IS a valid sigil — authors who want
+ # a literal Java/Python decorator must escape with `@@Override`. Only the inline
+ # shape `@deprecated def foo():` raises.)
+ ("@deprecated def foo():", 1, "@", "deprecated"),
+ # Multi-line: first error reported, with correct 1-based line number
+ ("OK line\nbroken @var line\nanother line", 2, "@", "var"),
+ ],
+ )
+ def test_strict_line_at_sigil_raises(
+ self,
+ template: str,
+ expected_line: int,
+ expected_sigil: str,
+ expected_identifier: str,
+ ):
+ """Inline / non-alone @ or @? sigils raise TemplateSigilSyntaxError with a
+ message that names the line, the offending span, and a migration hint —
+ but only when the candidate's root identifier is a declared input of the pipe.
+ Each parametrized case passes the identifier as `declared_inputs` to lock in
+ the strict-rule behavior.
+ """
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={expected_identifier})
+ error_message = str(exc_info.value)
+ offending_span = f"{expected_sigil}{expected_identifier}"
+ # Line number must be present and correctly 1-based
+ assert f"line {expected_line}" in error_message
+ # Offending span (sigil + identifier) must be quoted somewhere in the message
+ assert offending_span in error_message
+ # Migration hints — both alternatives must be visible to the author
+ assert f"${expected_identifier}" in error_message # inline-value migration
+ assert "@@" in error_message # literal-escape hint
+
+ # =========================================================================
+ # Word-adjacent `@` is not a candidate sigil — silent pass-through
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ "template",
+ [
+ "Send to [email protected] immediately.",
+ "prefix@suffix",
+ "Contact us at [email protected] for help.",
+ ],
+ ids=[
+ "bare_email",
+ "domain_email",
+ "email_in_sentence",
+ "letters_around_at",
+ "email_in_help_sentence",
+ ],
+ )
+ def test_word_adjacent_at_silent_pass_through(self, template: str):
+ """`@` preceded by a word character (emails, prose hashtags) is not a candidate
+ sigil and passes through silently — never raises, never rewrites.
+ """
+ assert preprocess_template(template) == template
+
+ # =========================================================================
+ # Word-adjacent `$` is not a candidate sigil — silent pass-through
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ "template",
+ [
+ "micro$oft is a company",
+ "user$host.com",
+ "P@ssw$rd123",
+ "a$b$c",
+ ],
+ ids=[
+ "mid_word_letters",
+ "mid_word_with_dot",
+ "mid_word_after_at",
+ "back_to_back_mid_word",
+ ],
+ )
+ def test_word_adjacent_dollar_pass_through(self, template: str):
+ """`$` preceded by a word character must not be rewritten — the word-boundary
+ lookbehind on the `$` arm prevents mid-word substitution.
+ """
+ assert preprocess_template(template) == template
+
+ def test_dollar_consecutive_dots_pass_through(self):
+ """`$name..` must render `{{ name|format() }}..` — the strict segmented
+ identifier stops at `name`; both trailing dots stay outside the match as
+ literal punctuation (no invalid Jinja produced).
+ """
+ template = "$name.."
+ result = preprocess_template(template)
+ expected = "{{ name|format() }}.."
+ assert result == expected
+
+ # =========================================================================
+ # Declared-inputs gating — inline `@<ident>` only raises when `<ident>` is a
+ # declared input of the pipe; CSS at-rules and code decorators pass through
+ # silently when they don't collide with a declared input.
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ "template",
+ [
+ "@media (max-width: 820px) { color: red; }",
+ '@import "reset.css";',
+ "@keyframes spin { from { opacity: 0; } }",
+ '@font-face { font-family: "X"; }',
+ "@deprecated def foo():",
+ "Use @Override in Java decorators.",
+ "<style>@media (max-width: 820px) { color: red; }</style>",
+ ],
+ ids=[
+ "css_media",
+ "css_import",
+ "css_keyframes",
+ "css_font_face",
+ "python_decorator",
+ "java_decorator_inline",
+ "css_inside_html",
+ ],
+ )
+ def test_inline_at_passes_through_when_declared_inputs_omitted(self, template: str):
+ """Without a `declared_inputs` kwarg, the validator is skipped — inline `@<ident>`
+ candidates pass through silently. This is the default for callers that don't have
+ an inputs context (base TemplateBlueprint, ConstructBlueprint discovery).
+ """
+ assert preprocess_template(template) == template
+
+ @pytest.mark.parametrize(
+ "template",
+ [
+ "@media (max-width: 820px) { color: red; }",
+ '@import "reset.css";',
+ "@keyframes spin { from { opacity: 0; } }",
+ '@font-face { font-family: "X"; }',
+ "@deprecated def foo():",
+ "Use @Override in Java decorators.",
+ ],
+ ids=[
+ "css_media",
+ "css_import",
+ "css_keyframes",
+ "css_font_face",
+ "python_decorator",
+ "java_decorator_inline",
+ ],
+ )
+ def test_inline_at_passes_through_when_declared_inputs_empty(self, template: str):
+ """With `declared_inputs=set()`, no candidate can match — inline `@<ident>` passes
+ through silently. Mirrors a pipe that declares no inputs at all.
+ """
+ assert preprocess_template(template, declared_inputs=set()) == template
+
+ @pytest.mark.parametrize(
+ "template",
+ [
+ "@media (max-width: 820px) { color: red; }",
+ '@import "reset.css";',
+ "@deprecated def foo():",
+ "Use @Override in Java decorators.",
+ ],
+ ids=["css_media", "css_import", "python_decorator", "java_decorator_inline"],
+ )
+ def test_inline_at_passes_through_when_no_input_matches(self, template: str):
+ """With `declared_inputs={"other_var"}`, no candidate's root matches — inline
+ `@<ident>` passes through silently.
+ """
+ assert preprocess_template(template, declared_inputs={"other_var"}) == template
+
+ def test_inline_at_raises_when_root_is_declared_input(self):
+ """When the inline candidate's root identifier matches a declared input, the
+ validator raises with the migration hint (the existing typo-catching behavior).
+ """
+ template = "Extract from @invoice_text. Done."
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={"invoice_text"})
+ error_message = str(exc_info.value)
+ assert "line 1" in error_message
+ assert "@invoice_text" in error_message
+ assert "$invoice_text" in error_message # inline migration hint
+ assert "@@" in error_message # literal-escape hint
+
+ def test_inline_at_with_dotted_path_raises_when_root_is_declared_input(self):
+ """The gate matches on the root segment of a dotted identifier — `@user.profile.bio`
+ with `declared_inputs={"user"}` raises (root `user` matches).
+ """
+ template = "Inline @user.profile.bio reference"
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={"user"})
+ error_message = str(exc_info.value)
+ assert "@user.profile.bio" in error_message
+
+ def test_inline_at_with_dotted_path_passes_when_only_inner_segment_declared(self):
+ """The gate is on the root segment only — `@user.profile.bio` with
+ `declared_inputs={"profile"}` passes through (root `user` is not declared).
+ """
+ template = "Inline @user.profile.bio reference"
+ assert preprocess_template(template, declared_inputs={"profile"}) == template
+
+ @pytest.mark.parametrize(
+ ("template", "declared_inputs", "expected_match"),
+ [
+ (
+ "<style>@media (max-width: 768px) { color: @user.color; }</style>",
+ {"user"},
+ "@user.color",
+ ),
+ (
+ "@font-face { src: @logo.url; }",
+ {"logo"},
+ "@logo.url",
+ ),
+ (
+ "@deprecated and also @invoice_text inline",
+ {"invoice_text"},
+ "@invoice_text",
+ ),
+ ],
+ ids=["media_then_user", "fontface_then_logo", "decorator_then_input"],
+ )
+ def test_inline_at_raises_on_later_candidate_when_earlier_candidate_is_not_input(
+ self,
+ template: str,
+ declared_inputs: set[str],
+ expected_match: str,
+ ):
+ """A non-input `@xxx` (CSS at-rule or decorator) earlier on the line must not
+ mask a later declared-input `@<ident>` collision. The validator must inspect
+ every candidate on the line, not just the first one.
+ """
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs=declared_inputs)
+ error_message = str(exc_info.value)
+ assert expected_match in error_message
+
+ @pytest.mark.parametrize(
+ ("template", "expected", "declared_inputs"),
+ [
+ ("@invoice_text", '{{ invoice_text|tag("invoice_text") }}', set[str]()),
+ ("@invoice_text", '{{ invoice_text|tag("invoice_text") }}', {"invoice_text"}),
+ ("@invoice_text", '{{ invoice_text|tag("invoice_text") }}', {"other_var"}),
+ (
+ "@?optional_field",
+ '{% if optional_field %}{{ optional_field|tag("optional_field") }}{% endif %}',
+ {"optional_field"},
+ ),
+ ],
+ ids=[
+ "empty_inputs",
+ "input_matches",
+ "input_does_not_match",
+ "optional_with_match",
+ ],
+ )
+ def test_alone_on_line_rewrites_regardless_of_declared_inputs(self, template: str, expected: str, declared_inputs: set[str]):
+ """The line-bounded rewriter is inputs-agnostic: `@var` alone on its own line
+ rewrites under any `declared_inputs` value. Only the inline-candidate validator
+ is gated.
+ """
+ assert preprocess_template(template, declared_inputs=declared_inputs) == expected
+
+ def test_validator_skips_non_declared_candidates_then_raises_on_declared_one(self):
+ """When a line contains multiple inline `@` candidates, the validator must
+ iterate past non-declared ones (e.g. CSS at-rules) and raise only when it
+ reaches a candidate whose root identifier is a declared input.
+ """
+ template = "@media (max-width: 820px) { color: red; } @invoice_text inline here"
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={"invoice_text"})
+ error_message = str(exc_info.value)
+ assert "@invoice_text" in error_message
+ assert "@media" not in error_message
+ assert "line 1" in error_message
+
+ def test_at_var_with_trailing_dot_falls_through_to_inline_validator(self):
+ r"""`@var.` on its own line is NOT matched by the line-bounded `@` pattern (the
+ trailing dot breaks `^([ \t]*)(@\??)<ident>([ \t]*)$`), so it falls through to
+ the inline-candidate validator. When `var` is in `declared_inputs`, the validator
+ raises — locking in the "pattern misses → validator catches" fall-through. Without
+ `declared_inputs`, the same input passes through unchanged.
+ """
+ template = "@var."
+ # Without declared_inputs: validator skipped, line-bounded pattern misses, pass-through.
+ assert preprocess_template(template) == template
+ # With declared_inputs={"var"}: inline validator raises.
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={"var"})
+ error_message = str(exc_info.value)
+ assert "@var" in error_message
+ assert "line 1" in error_message
+
+ # =========================================================================
+ # Adjacent `@` and `$` sigils on the same line
+ # =========================================================================
+
+ @pytest.mark.parametrize(
+ ("template", "expected"),
+ [
+ ("@$foo", "@{{ foo|format() }}"),
+ ("@?$foo", "@?{{ foo|format() }}"),
+ ("hello@$world", "hello@{{ world|format() }}"),
+ ("prefix @$bar suffix", "prefix @{{ bar|format() }} suffix"),
+ ],
+ ids=[
+ "at_then_dollar_bare",
+ "optional_at_then_dollar_bare",
+ "word_at_then_dollar",
+ "at_then_dollar_in_sentence",
+ ],
+ )
+ def test_at_then_dollar_adjacency_rewrites_inline_dollar(self, template: str, expected: str):
+ """`@` (or `@?`) followed immediately by `$<ident>` is not a candidate (the next
+ char isn't an identifier start), but the `$<ident>` rewrites because the preceding
+ `@` / `?` is not a word character — the `$` lookbehind passes.
+ """
+ assert preprocess_template(template) == expected
+
+ @pytest.mark.parametrize(
+ ("template", "expected_sigil", "expected_identifier"),
+ [
+ ("$@foo", "@", "foo"),
+ ("$@?foo", "@?", "foo"),
+ ("$@invoice_text.", "@", "invoice_text"),
+ ],
+ ids=[
+ "dollar_then_at_bare",
+ "dollar_then_optional_at_bare",
+ "dollar_then_at_with_trailing_dot",
+ ],
+ )
+ def test_dollar_then_at_adjacency_raises_when_at_ident_is_declared(
+ self,
+ template: str,
+ expected_sigil: str,
+ expected_identifier: str,
+ ):
+ """`$@<ident>` / `$@?<ident>`: the leading `$` has no identifier so it doesn't
+ substitute, but the `@`/`@?` candidate fires because `$` is non-word. The line
+ isn't alone-on-line, so the validator raises when the identifier is declared.
+ """
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={expected_identifier})
+ error_message = str(exc_info.value)
+ assert f"{expected_sigil}{expected_identifier}" in error_message
+ assert f"${expected_identifier}" in error_message
+ assert "@@" in error_message
+ assert "line 1" in error_message
+
+ @pytest.mark.parametrize(
+ "template",
+ ["$@foo", "$@?foo", "$@invoice_text."],
+ ids=[
+ "dollar_then_at_bare",
+ "dollar_then_optional_at_bare",
+ "dollar_then_at_with_trailing_dot",
+ ],
+ )
+ def test_dollar_then_at_adjacency_passes_through_when_not_declared(self, template: str):
+ """Same `$@<ident>` shape with no `declared_inputs` → silent pass-through. The
+ validator is skipped and the rewriter finds no match for either sigil.
+ """
+ assert preprocess_template(template) == template
+
+ @pytest.mark.parametrize(
+ ("template", "expected_identifier"),
+ [
+ ("@world$", "world"),
+ ("@invoice_text$", "invoice_text"),
+ ],
+ ids=["at_ident_trailing_dollar", "at_long_ident_trailing_dollar"],
+ )
+ def test_at_ident_with_trailing_dollar_raises_when_declared(
+ self,
+ template: str,
+ expected_identifier: str,
+ ):
+ """`@<ident>$` — `@<ident>` is an inline candidate; the trailing `$` keeps the
+ line from matching the alone-on-line pattern. Raises when the identifier is a
+ declared input.
+ """
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template(template, declared_inputs={expected_identifier})
+ error_message = str(exc_info.value)
+ assert f"@{expected_identifier}" in error_message
+ assert f"${expected_identifier}" in error_message
+ assert "@@" in error_message
+ assert "line 1" in error_message
+
+ @pytest.mark.parametrize(
+ "template",
+ ["@world$", "@invoice_text$"],
+ ids=["at_ident_trailing_dollar", "at_long_ident_trailing_dollar"],
+ )
+ def test_at_ident_with_trailing_dollar_passes_through_when_not_declared(self, template: str):
+ """Same `@<ident>$` shape with no `declared_inputs` → silent pass-through."""
+ assert preprocess_template(template) == template
+
+ def test_escaped_at_then_dollar_rewrites_inline_dollar(self):
+ """`@@$foo` — `@@` becomes literal `@` (via sentinel), and `$foo` still rewrites
+ because the sentinel boundary is non-word so the `$` lookbehind passes.
+ """
+ assert preprocess_template("@@$foo") == "@{{ foo|format() }}"
+
+ def test_escaped_dollar_then_at_still_raises_when_declared(self):
+ """`$$@foo` — `$$` becomes a sentinel, but `@foo` is still an inline candidate
+ after the sentinel boundary, so the validator raises when `foo` is declared.
+ """
+ with pytest.raises(TemplateSigilSyntaxError) as exc_info:
+ preprocess_template("$$@foo", declared_inputs={"foo"})
+ error_message = str(exc_info.value)
+ assert "@foo" in error_message
+ assert "$foo" in error_message
+ assert "@@" in error_message
+ assert "line 1" in error_message
+
+ def test_escaped_dollar_then_at_passes_through_when_not_declared(self):
+ """`$$@foo` without `declared_inputs` → `$@foo` (sentinel restored, no validation)."""
+ assert preprocess_template("$$@foo") == "$@foo"
diff --git a/tests/unit/pipelex/core/bundles/test_data_pipe_sorter.py b/tests/unit/pipelex/core/bundles/test_data_pipe_sorter.py
index 3dae376d5..7d0bbd728 100644
--- a/tests/unit/pipelex/core/bundles/test_data_pipe_sorter.py
+++ b/tests/unit/pipelex/core/bundles/test_data_pipe_sorter.py
@@ -176,19 +176,19 @@ class PipeSorterTestCases:
description="Analyzes the input photo to understand visual elements, composition, mood, etc.",
inputs={"input_photo": "Image"},
output="ImageAnalysis",
- prompt="Analyze this image: @input_photo",
+ prompt="Analyze this image: $input_photo",
),
"define_opposite_concept": PipeLLMBlueprint(
description="Determines what constitutes the opposite for the analyzed image",
inputs={"image_analysis": "ImageAnalysis"},
output="OppositeDefinition",
- prompt="Define opposite for: @image_analysis",
+ prompt="Define opposite for: $image_analysis",
),
"generate_image_prompt": PipeLLMBlueprint(
description="Crafts a detailed image generation prompt from the opposite definition",
inputs={"opposite_definition": "OppositeDefinition"},
output="ImagePrompt",
- prompt="Generate prompt from: @opposite_definition",
+ prompt="Generate prompt from: $opposite_definition",
),
"generate_opposite_image": PipeImgGenBlueprint(
description="Generates the opposite image using AI",
@@ -257,37 +257,37 @@ class PipeSorterTestCases:
description="Prepare the data",
inputs={"input": "Text"},
output="Text",
- prompt="Prepare: @input",
+ prompt="Prepare: $input",
),
"validate_data": PipeLLMBlueprint(
description="Validate the prepared data",
inputs={"prepared_data": "Text"},
output="Text",
- prompt="Validate: @prepared_data",
+ prompt="Validate: $prepared_data",
),
"process_small": PipeLLMBlueprint(
description="Process small items",
inputs={"item": "Text"},
output="Text",
- prompt="Process small: @item",
+ prompt="Process small: $item",
),
"process_large": PipeLLMBlueprint(
description="Process large items",
inputs={"item": "Text"},
output="Text",
- prompt="Process large: @item",
+ prompt="Process large: $item",
),
"process_default": PipeLLMBlueprint(
description="Default processing",
inputs={"item": "Text"},
output="Text",
- prompt="Process default: @item",
+ prompt="Process default: $item",
),
"final_process": PipeLLMBlueprint(
description="Final processing step",
inputs={"processed": "Text"},
output="Text",
- prompt="Final process: @processed",
+ prompt="Final process: $processed",
),
}
# Expected order: main_pipeline first, then following step order
diff --git a/tests/unit/pipelex/core/bundles/test_pipelex_bundle_blueprint_concept_validation.py b/tests/unit/pipelex/core/bundles/test_pipelex_bundle_blueprint_concept_validation.py
index ff7d847a4..6c35ce7ad 100644
--- a/tests/unit/pipelex/core/bundles/test_pipelex_bundle_blueprint_concept_validation.py
+++ b/tests/unit/pipelex/core/bundles/test_pipelex_bundle_blueprint_concept_validation.py
@@ -40,7 +40,7 @@ class TestPipelexBundleBlueprintConceptValidation:
description="Test pipe",
inputs={"data": "Text", "image": "Image"},
output="Text",
- prompt="Process @data and @image",
+ prompt="Process $data and $image",
),
},
)
@@ -76,7 +76,7 @@ class TestPipelexBundleBlueprintConceptValidation:
description="Test pipe",
inputs={"data": "InputData"},
output="Text",
- prompt="Process @data",
+ prompt="Process $data",
),
},
)
@@ -110,7 +110,7 @@ class TestPipelexBundleBlueprintConceptValidation:
description="Test pipe",
inputs={"external_data": "other_domain.ExternalConcept"},
output="Text",
- prompt="Process @external_data",
+ prompt="Process $external_data",
),
},
)
@@ -144,7 +144,7 @@ class TestPipelexBundleBlueprintConceptValidation:
description="Test pipe",
inputs={"items": "Item[]"},
output="Text[3]",
- prompt="Process @items",
+ prompt="Process $items",
),
},
)
@@ -255,7 +255,7 @@ class TestPipelexBundleBlueprintConceptValidation:
description="Test pipe",
inputs={"score": "scoring.WeightedScore"},
output="Text",
- prompt="Process @score",
+ prompt="Process $score",
),
},
)
@@ -316,7 +316,7 @@ class TestPipelexBundleBlueprintConceptValidation:
description="Test pipe",
inputs={"data": "UndeclaredInput"},
output="Text",
- prompt="Process @data",
+ prompt="Process $data",
),
},
)
@@ -426,7 +426,7 @@ class TestPipelexBundleBlueprintConceptValidation:
description="Test pipe",
inputs={"items": "UndeclaredItem[]"},
output="Text",
- prompt="Process @items",
+ prompt="Process $items",
),
},
)
@@ -447,7 +447,7 @@ class TestPipelexBundleBlueprintConceptValidation:
description="Test pipe",
inputs={"input1": "Undeclared1", "input2": "Undeclared2"},
output="Undeclared3",
- prompt="Process @input1 and @input2",
+ prompt="Process $input1 and $input2",
),
},
)
diff --git a/tests/unit/pipelex/core/concepts/test_special_args_concept.py b/tests/unit/pipelex/core/concepts/test_special_args_concept.py
index ebac92b9f..f390c62c5 100644
--- a/tests/unit/pipelex/core/concepts/test_special_args_concept.py
+++ b/tests/unit/pipelex/core/concepts/test_special_args_concept.py
@@ -64,7 +64,7 @@ class TestSpecialArgsConcept:
description="A pipe that reads the content",
inputs={"my_input": "ContentConcept"},
output="native.Text",
- prompt="read the content, @my_input.content",
+ prompt="read the content, $my_input.content",
)
# Make a PipeLLM using PipeFactory
diff --git a/tests/unit/pipelex/core/test_data/complex/multi_feature.py b/tests/unit/pipelex/core/test_data/complex/multi_feature.py
index 8930658ae..c51a1ef8b 100644
--- a/tests/unit/pipelex/core/test_data/complex/multi_feature.py
+++ b/tests/unit/pipelex/core/test_data/complex/multi_feature.py
@@ -17,7 +17,7 @@ type = "PipeLLM"
description = "Generate content"
inputs = { data = "InputData" }
output = "ProcessedData"
-prompt = "Process this data: @data"
+prompt = "Process this data: $data"
[pipe.sequence_pipe]
type = "PipeSequence"
@@ -42,7 +42,7 @@ steps = [
description="Generate content",
inputs={"data": "InputData"},
output="ProcessedData",
- prompt="Process this data: @data",
+ prompt="Process this data: $data",
),
"sequence_pipe": PipeSequenceBlueprint(
type="PipeSequence",
diff --git a/tests/unit/pipelex/core/test_data/pipes/operators/llm/pipe_llm.py b/tests/unit/pipelex/core/test_data/pipes/operators/llm/pipe_llm.py
index fe8ea6cde..010026b48 100644
--- a/tests/unit/pipelex/core/test_data/pipes/operators/llm/pipe_llm.py
+++ b/tests/unit/pipelex/core/test_data/pipes/operators/llm/pipe_llm.py
@@ -243,7 +243,7 @@ description = "Analysis with dynamic system prompt"
inputs = { expertise_level = "Text", content = "Text" }
output = "Text"
system_prompt = "You are an expert with $expertise_level level knowledge"
-prompt = "Analyze this content: @content"
+prompt = "Analyze this content: $content"
""",
PipelexBundleBlueprint(
domain="test_pipes",
@@ -255,7 +255,7 @@ prompt = "Analyze this content: @content"
inputs={"expertise_level": "Text", "content": "Text"},
output=NativeConceptCode.TEXT,
system_prompt="You are an expert with $expertise_level level knowledge",
- prompt="Analyze this content: @content",
+ prompt="Analyze this content: $content",
),
},
),
@@ -275,7 +275,7 @@ type = "PipeLLM"
description = "Extract structured person information"
inputs = { text = "Text[1]" }
output = "PersonInfo"
-prompt = "Extract person information from this text: @text"
+prompt = "Extract person information from this text: $text"
""",
PipelexBundleBlueprint(
domain="test_pipes",
@@ -287,7 +287,7 @@ prompt = "Extract person information from this text: @text"
description="Extract structured person information",
inputs={"text": "Text[1]"},
output="PersonInfo",
- prompt="Extract person information from this text: @text",
+ prompt="Extract person information from this text: $text",
),
},
),
@@ -310,7 +310,8 @@ output = "DocumentSummary"
prompt = """
Analyze these documents based on the query: $query
-Documents: @documents
+Documents:
+@documents
"""
''',
PipelexBundleBlueprint(
@@ -328,7 +329,8 @@ Documents: @documents
output="DocumentSummary",
prompt="""Analyze these documents based on the query: $query
-Documents: @documents
+Documents:
+@documents
""",
),
},
diff --git a/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py b/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py
index dc10eaa74..932e6e17e 100644
--- a/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py
+++ b/tests/unit/pipelex/pipe_controllers/condition/test_pipe_condition_needed_inputs.py
@@ -87,7 +87,7 @@ class TestPipeConditionNeededInputs:
description="Pipe A",
inputs={"doc_input": document_concept.concept_ref},
output=analysis_concept.concept_ref,
- prompt="Analyze: @doc_input",
+ prompt="Analyze: $doc_input",
)
pipe_a = PipeFactory[PipeLLM].make_from_blueprint(
domain_code=domain_code,
@@ -101,7 +101,7 @@ class TestPipeConditionNeededInputs:
description="Pipe B",
inputs={"other_doc": document_concept.concept_ref},
output=analysis_concept.concept_ref,
- prompt="Summarize: @other_doc",
+ prompt="Summarize: $other_doc",
)
pipe_b = PipeFactory[PipeLLM].make_from_blueprint(
domain_code=domain_code,
@@ -168,7 +168,7 @@ class TestPipeConditionNeededInputs:
description="Pipe with list input",
inputs={"items": f"{item_concept.concept_ref}[]"}, # List multiplicity
output=result_concept.concept_ref,
- prompt="Process items: @items",
+ prompt="Process items: $items",
)
pipe_with_list = PipeFactory[PipeLLM].make_from_blueprint(
domain_code=domain_code,
@@ -243,7 +243,7 @@ class TestPipeConditionOutputValidation:
description="Pipe A",
inputs={"input_a": input_concept.concept_ref},
output=output_concept.concept_ref,
- prompt="Process A: @input_a",
+ prompt="Process A: $input_a",
),
concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
)
@@ -256,7 +256,7 @@ class TestPipeConditionOutputValidation:
description="Pipe B",
inputs={"input_b": input_concept.concept_ref},
output=output_concept.concept_ref,
- prompt="Process B: @input_b",
+ prompt="Process B: $input_b",
),
concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
)
@@ -312,7 +312,7 @@ class TestPipeConditionOutputValidation:
description="Pipe A",
inputs={"input_a": input_concept.concept_ref},
output=output_concept.concept_ref,
- prompt="Process A: @input_a",
+ prompt="Process A: $input_a",
),
concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
)
@@ -325,7 +325,7 @@ class TestPipeConditionOutputValidation:
description="Pipe B",
inputs={"input_b": input_concept.concept_ref},
output=output_concept.concept_ref,
- prompt="Process B: @input_b",
+ prompt="Process B: $input_b",
),
concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
)
@@ -384,7 +384,7 @@ class TestPipeConditionOutputValidation:
description="Pipe A",
inputs={"input_a": input_concept.concept_ref},
output=output_concept.concept_ref,
- prompt="Process A: @input_a",
+ prompt="Process A: $input_a",
),
concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
)
@@ -447,7 +447,7 @@ class TestPipeConditionOutputValidation:
description="Pipe A",
inputs={"input_a": input_concept.concept_ref},
output=output_a.concept_ref,
- prompt="Process A: @input_a",
+ prompt="Process A: $input_a",
),
concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
)
@@ -460,7 +460,7 @@ class TestPipeConditionOutputValidation:
description="Pipe B",
inputs={"input_b": input_concept.concept_ref},
output=output_b.concept_ref,
- prompt="Process B: @input_b",
+ prompt="Process B: $input_b",
),
concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
)
@@ -520,7 +520,7 @@ class TestPipeConditionOutputValidation:
description="Pipe A",
inputs={"input_a": input_concept.concept_ref},
output=output_a.concept_ref,
- prompt="Process A: @input_a",
+ prompt="Process A: $input_a",
),
concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
)
@@ -533,7 +533,7 @@ class TestPipeConditionOutputValidation:
description="Pipe B",
inputs={"input_b": input_concept.concept_ref},
output=output_b.concept_ref,
- prompt="Process B: @input_b",
+ prompt="Process B: $input_b",
),
concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
)
@@ -597,7 +597,7 @@ class TestPipeConditionOutputValidation:
description="Pipe A",
inputs={"input_a": input_concept.concept_ref},
output=output_a.concept_ref,
- prompt="Process A: @input_a",
+ prompt="Process A: $input_a",
),
concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
)
@@ -610,7 +610,7 @@ class TestPipeConditionOutputValidation:
description="Pipe B",
inputs={"input_b": input_concept.concept_ref},
output=output_b.concept_ref,
- prompt="Process B: @input_b",
+ prompt="Process B: $input_b",
),
concept_codes_from_the_same_domain=[input_concept.code, output_a.code, output_b.code],
)
@@ -732,7 +732,7 @@ class TestPipeConditionSpecialOutcomes:
description="Process pipe",
inputs={"doc": input_concept.concept_ref},
output=output_concept.concept_ref,
- prompt="Process: @doc",
+ prompt="Process: $doc",
),
concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
)
@@ -795,7 +795,7 @@ class TestPipeConditionSpecialOutcomes:
description="Success pipe",
inputs={"data": input_concept.concept_ref},
output=output_concept.concept_ref,
- prompt="Process: @data",
+ prompt="Process: $data",
),
concept_codes_from_the_same_domain=[input_concept.code, output_concept.code],
)
diff --git a/tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py b/tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py
index 1f8135438..f6d00573c 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_compose/test_structured_content_composer.py
@@ -802,7 +802,7 @@ class TestStructuredContentComposerRuntimeParams:
blueprint = ConstructBlueprint.make_from_raw(
{
"title": "Financial Report",
- "generated_summary": {"template": "Summary for $fiscal_year Q$quarter"},
+ "generated_summary": {"template": "Summary for $fiscal_year, quarter $quarter"},
}
)
@@ -817,7 +817,7 @@ class TestStructuredContentComposerRuntimeParams:
assert isinstance(result, ReportWithRuntimeParams)
assert result.title == "Financial Report"
assert "2025" in result.generated_summary
- assert "Q1" in result.generated_summary
+ assert "quarter 1" in result.generated_summary
async def test_template_field_combines_all_context_sources(self, working_memory_with_deal: WorkingMemory):
"""Test that template fields can access all context sources together.
diff --git a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_factory.py b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_factory.py
index 7e11b8a92..f5cf3c45f 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_factory.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_factory.py
@@ -23,7 +23,7 @@ class TestPipeImgGenFactoryImageReferences:
description="Test image in positive prompt",
inputs={"source_image": "Image"},
output="Image",
- prompt="Edit this image: @source_image",
+ prompt="Edit this image:\n@source_image",
negative_prompt=None,
)
@@ -55,7 +55,7 @@ class TestPipeImgGenFactoryImageReferences:
inputs={"avoid_image": "Image"},
output="Image",
prompt="Generate a beautiful landscape",
- negative_prompt="Avoid features from: @avoid_image",
+ negative_prompt="Avoid features from:\n@avoid_image",
)
pipe = PipeFactory[PipeImgGen].make_from_blueprint(
@@ -82,8 +82,8 @@ class TestPipeImgGenFactoryImageReferences:
description="Test images in both prompts",
inputs={"style_ref": "Image", "avoid_ref": "Image"},
output="Image",
- prompt="Apply style from: @style_ref",
- negative_prompt="Avoid style from: @avoid_ref",
+ prompt="Apply style from:\n@style_ref",
+ negative_prompt="Avoid style from:\n@avoid_ref",
)
pipe = PipeFactory[PipeImgGen].make_from_blueprint(
@@ -110,8 +110,8 @@ class TestPipeImgGenFactoryImageReferences:
description="Test same image in both prompts",
inputs={"shared_image": "Image"},
output="Image",
- prompt="Apply style from: @shared_image",
- negative_prompt="But avoid these aspects: @shared_image",
+ prompt="Apply style from:\n@shared_image",
+ negative_prompt="But avoid these aspects:\n@shared_image",
)
pipe = PipeFactory[PipeImgGen].make_from_blueprint(
@@ -138,7 +138,7 @@ class TestPipeImgGenFactoryImageReferences:
inputs={"avoid_images": "Image[]"},
output="Image",
prompt="Generate a beautiful landscape",
- negative_prompt="Avoid features from: @avoid_images",
+ negative_prompt="Avoid features from:\n@avoid_images",
)
pipe = PipeFactory[PipeImgGen].make_from_blueprint(
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/data.py b/tests/unit/pipelex/pipe_operators/pipe_llm/data.py
index abd738367..704056b11 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/data.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/data.py
@@ -13,7 +13,7 @@ class PipeLLMInputTestCases:
description="Test case: valid_text_input",
inputs={"user_text": "native.Text"},
output="native.Text",
- prompt="Process this text: @user_text",
+ prompt="Process this text: $user_text",
),
)
@@ -23,7 +23,7 @@ class PipeLLMInputTestCases:
description="Test case: valid_image_input",
inputs={"user_image": "native.Image"},
output="native.Text",
- prompt="Describe this image: @user_image",
+ prompt="Describe this image: $user_image",
),
)
@@ -33,7 +33,7 @@ class PipeLLMInputTestCases:
description="Test case: valid_two_inputs",
inputs={"text_input": "native.Text", "another_text": "native.Text"},
output="native.Text",
- prompt="Compare @text_input with @another_text",
+ prompt="Compare $text_input with $another_text",
),
)
@@ -43,7 +43,7 @@ class PipeLLMInputTestCases:
description="Test case: valid_text_and_image",
inputs={"user_text": "native.Text", "user_image": "native.Image"},
output="native.Text",
- prompt="Analyze this text: @user_text with the image: @user_image",
+ prompt="Analyze this text: $user_text with the image: $user_image",
),
)
@@ -53,7 +53,7 @@ class PipeLLMInputTestCases:
description="Test case: image_mentioned_in_prompt",
inputs={"user_image": "native.Image"},
output="native.Text",
- prompt="Describe @user_image",
+ prompt="Describe $user_image",
),
)
@@ -63,7 +63,7 @@ class PipeLLMInputTestCases:
description="Test case: text_and_image_both_in_prompt",
inputs={"user_text": "native.Text", "user_image": "native.Image"},
output="native.Text",
- prompt="Analyze @user_text and describe @user_image",
+ prompt="Analyze $user_text and describe $user_image",
),
)
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py
index 5d436771b..2c7191222 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_llm_prompt_blueprint.py
@@ -33,7 +33,7 @@ Output: "MARKETING_BUSINESS_PROCESSED"
def test_required_variables_returns_root_names_for_dotted_paths_in_system_prompt(self):
"""Test that dotted paths in system_prompt are converted to root names."""
system_prompt_template = """
-You are processing documents for @organization.name in @organization.region.
+You are processing documents for $organization.name in $organization.region.
"""
blueprint = LLMPromptBlueprint(
system_prompt_blueprint=TemplateBlueprint(
@@ -52,7 +52,7 @@ You are processing documents for @organization.name in @organization.region.
def test_required_variables_returns_root_names_for_both_prompts(self):
"""Test that both prompt and system_prompt dotted paths are converted to root names."""
prompt_template = "@request.content"
- system_prompt_template = "Context: @context.metadata.source"
+ system_prompt_template = "Context: $context.metadata.source"
blueprint = LLMPromptBlueprint(
prompt_blueprint=TemplateBlueprint(
@@ -77,8 +77,8 @@ You are processing documents for @organization.name in @organization.region.
def test_required_variables_handles_mix_of_root_and_dotted_paths(self):
"""Test that both root variables and dotted paths are handled correctly."""
prompt_template = """
-Process @simple_var and @complex_object.nested.value
-Also use @another_object.field
+Process $simple_var and $complex_object.nested.value
+Also use $another_object.field
"""
blueprint = LLMPromptBlueprint(
prompt_blueprint=TemplateBlueprint(
@@ -102,7 +102,7 @@ Also use @another_object.field
def test_required_variables_deduplicates_same_root(self):
"""Test that multiple dotted paths with same root are deduplicated."""
prompt_template = """
-Use @user.name and @user.email and @user.address.city
+Use $user.name and $user.email and $user.address.city
"""
blueprint = LLMPromptBlueprint(
prompt_blueprint=TemplateBlueprint(
@@ -118,7 +118,7 @@ Use @user.name and @user.email and @user.address.city
def test_required_variables_excludes_internal_variables(self):
"""Test that internal variables starting with _ are excluded."""
- prompt_template = "@public_var and @_internal_var.field"
+ prompt_template = "$public_var and $_internal_var.field"
blueprint = LLMPromptBlueprint(
prompt_blueprint=TemplateBlueprint(
@@ -134,7 +134,7 @@ Use @user.name and @user.email and @user.address.city
def test_required_variables_excludes_special_variables(self):
"""Test that special variables preliminary_text and place_holder are excluded."""
- prompt_template = "@data and @preliminary_text and @place_holder"
+ prompt_template = "$data and $preliminary_text and $place_holder"
blueprint = LLMPromptBlueprint(
prompt_blueprint=TemplateBlueprint(
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py
index dcc7c1869..3ea1bc0fb 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py
@@ -11,7 +11,7 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs={"input_one": "native.Text", "input_two": "native.Text"},
output="native.Text",
- prompt="Process @input_one and @input_two",
+ prompt="Process $input_one and $input_two",
)
assert blueprint.nb_inputs == 2
assert set(blueprint.input_names) == {"input_one", "input_two"}
@@ -22,7 +22,7 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs={"context": "native.Text"},
output="native.Text",
- system_prompt="Use this context: @context",
+ system_prompt="Use this context: $context",
prompt="Generate a response",
)
assert blueprint.nb_inputs == 1
@@ -34,8 +34,8 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs={"context": "native.Text", "query": "native.Text"},
output="native.Text",
- system_prompt="Context: @context",
- prompt="Answer this query: @query",
+ system_prompt="Context: $context",
+ prompt="Answer this query: $query",
)
assert blueprint.nb_inputs == 2
assert set(blueprint.input_names) == {"context", "query"}
@@ -68,7 +68,7 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs={"input_one": "native.Text", "input_two": "native.Text"},
output="native.Text",
- prompt="Process @input_one, @input_two, and @input_three",
+ prompt="Process $input_one, $input_two, and $input_three",
)
error_msg = str(exc_info.value)
assert "Missing input variable(s):" in error_msg
@@ -82,7 +82,7 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs={"input_one": "native.Text"},
output="native.Text",
- prompt="Process @input_one, @input_two, and @input_three",
+ prompt="Process $input_one, $input_two, and $input_three",
)
error_msg = str(exc_info.value)
assert "Missing input variable(s):" in error_msg
@@ -96,8 +96,8 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs={"query": "native.Text"},
output="native.Text",
- system_prompt="Use context: @context",
- prompt="Answer: @query",
+ system_prompt="Use context: $context",
+ prompt="Answer: $query",
)
error_msg = str(exc_info.value)
assert "Missing input variable(s):" in error_msg
@@ -110,7 +110,7 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs={},
output="native.Text",
- prompt="Process @data",
+ prompt="Process $data",
)
error_msg = str(exc_info.value)
assert "Missing input variable(s):" in error_msg or "data" in error_msg
@@ -121,7 +121,7 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs=None,
output="native.Text",
- prompt="Use internal variable @_internal_var",
+ prompt="Use internal variable $_internal_var",
)
# Should not raise error even though _internal_var is not in inputs
assert blueprint.inputs is None
@@ -132,7 +132,109 @@ class TestPipeLLMBlueprint:
description="lorem ipsum",
inputs=None,
output="native.Text",
- prompt="Use @preliminary_text and @place_holder",
+ prompt="Use $preliminary_text and $place_holder",
)
# Should not raise error even though these special variables are not in inputs
assert blueprint.inputs is None
+
+ # =========================================================================
+ # Strict line-bounded `@` sigil contract — surfaces through pydantic validation
+ # =========================================================================
+
+ def test_validate_inputs_raises_for_inline_at_sigil_in_prompt(self):
+ """Inline `@var` in the prompt surfaces as a pydantic validation failure
+ whose message names the offending span, the line number, and both migration
+ hints (`$var` for inline, `@@` for literal).
+ """
+ with pytest.raises(ValueError, match="@invoice_text") as exc_info:
+ PipeLLMBlueprint(
+ description="lorem ipsum",
+ inputs={"invoice_text": "native.Text"},
+ output="native.Text",
+ prompt="Extract from @invoice_text. Done.",
+ )
+ error_msg = str(exc_info.value)
+ assert "@invoice_text" in error_msg
+ assert "$invoice_text" in error_msg
+ assert "@@" in error_msg
+ assert "line 1" in error_msg
+
+ def test_validate_inputs_raises_for_inline_at_sigil_in_system_prompt(self):
+ """Inline `@var` in the system_prompt also surfaces with the strict-rule
+ diagnostic — both prompt fields are validated.
+ """
+ with pytest.raises(ValueError, match="@context") as exc_info:
+ PipeLLMBlueprint(
+ description="lorem ipsum",
+ inputs={"context": "native.Text"},
+ output="native.Text",
+ system_prompt="Hello @context!",
+ prompt="Generate a response",
+ )
+ error_msg = str(exc_info.value)
+ assert "@context" in error_msg
+ assert "$context" in error_msg
+ assert "@@" in error_msg
+ assert "line 1" in error_msg
+
+ def test_validate_inputs_raises_with_correct_line_for_multiline_prompt(self):
+ """Line number in the diagnostic is 1-based and accurate for multi-line prompts."""
+ with pytest.raises(ValueError, match="line 2") as exc_info:
+ PipeLLMBlueprint(
+ description="lorem ipsum",
+ inputs={"data": "native.Text"},
+ output="native.Text",
+ prompt="Header line\nBody with inline @data\nFooter line",
+ )
+ error_msg = str(exc_info.value)
+ assert "line 2" in error_msg
+ assert "@data" in error_msg
+
+ # =========================================================================
+ # Declared-inputs gating — inline `@<ident>` only raises when `<ident>` is a
+ # declared input of the PipeLLM. CSS at-rules and code decorators pass through
+ # silently when they don't collide with a declared input.
+ # =========================================================================
+
+ def test_inline_css_at_rule_passes_when_keyword_not_declared(self):
+ """`<style>@media (...) { ... }</style>` inside a PipeCompose-like prompt loads
+ cleanly when `media` is not a declared input. The page input still needs
+ a Jinja2 reference for the validator to count it as used, so the prompt also
+ renders `$page` inline.
+ """
+ blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
+ inputs={"page": "native.Text"},
+ output="native.Text",
+ prompt="<style>@media (max-width: 820px) { color: red; }</style>\nFor $page",
+ )
+ assert blueprint.input_names == ["page"]
+
+ def test_inline_at_raises_when_input_collides_with_at_rule_keyword(self):
+ """When a declared input happens to share a name with a CSS at-rule keyword
+ (e.g. `media`), the validator treats inline `@media` as a real typo and raises.
+ Authors can opt out with `@@media`.
+ """
+ with pytest.raises(ValueError, match="@media") as exc_info:
+ PipeLLMBlueprint(
+ description="lorem ipsum",
+ inputs={"media": "native.Text"},
+ output="native.Text",
+ prompt="<style>@media (max-width: 820px) { color: red; }</style>\nFor $media",
+ )
+ error_msg = str(exc_info.value)
+ assert "@media" in error_msg
+ assert "$media" in error_msg # inline migration hint
+ assert "@@" in error_msg # literal-escape hint
+
+ def test_inline_python_decorator_passes_through(self):
+ """Inline `@deprecated` (Python decorator shape) in a prompt loads cleanly when
+ `deprecated` is not a declared input.
+ """
+ blueprint = PipeLLMBlueprint(
+ description="lorem ipsum",
+ inputs={"code": "native.Text"},
+ output="native.Text",
+ prompt="Review this code with @deprecated def foo(): pass\nCode: $code",
+ )
+ assert blueprint.input_names == ["code"]
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_dynamic_output.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_dynamic_output.py
index e69a939f5..846abbbbc 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_dynamic_output.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_dynamic_output.py
@@ -32,7 +32,7 @@ def _make_pipe(domain_code: str, pipe_code: str, output: str) -> PipeLLM:
description="dynamic-output test pipe",
inputs={"user_text": "native.Text"},
output=output,
- prompt="Process @user_text",
+ prompt="Process $user_text",
)
return PipeFactory[PipeLLM].make_from_blueprint(
domain_code=domain_code,
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_document_analyzer.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_document_analyzer.py
index d85384744..ffd1fcc72 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_document_analyzer.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_document_analyzer.py
@@ -19,7 +19,7 @@ class TestTemplateDocumentAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateDocumentAnalyzer.analyze_template_for_documents(
- template_source="Analyze this document: @document",
+ template_source="Analyze this document:\n@document",
input_specs={"document": "Document"},
domain_code="test_pipes",
)
@@ -47,7 +47,7 @@ class TestTemplateDocumentAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateDocumentAnalyzer.analyze_template_for_documents(
- template_source="Compare @doc_a with @doc_b",
+ template_source="Compare:\n@doc_a\nwith:\n@doc_b",
input_specs={"doc_a": "Document", "doc_b": "Document"},
domain_code="test_pipes",
)
@@ -67,7 +67,7 @@ class TestTemplateDocumentAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateDocumentAnalyzer.analyze_template_for_documents(
- template_source="Process this: @text",
+ template_source="Process this:\n@text",
input_specs={"text": "Text"},
domain_code="test_pipes",
)
@@ -79,7 +79,7 @@ class TestTemplateDocumentAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateDocumentAnalyzer.analyze_template_for_documents(
- template_source="Look at: @image",
+ template_source="Look at:\n@image",
input_specs={"image": "Image"},
domain_code="test_pipes",
)
@@ -91,7 +91,7 @@ class TestTemplateDocumentAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateDocumentAnalyzer.analyze_template_for_documents(
- template_source="Hello @name, your age is @age",
+ template_source="Hello $name, your age is $age",
input_specs={"name": "Text", "age": "Text"},
domain_code="test_pipes",
)
@@ -120,7 +120,7 @@ class TestTemplateDocumentAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateDocumentAnalyzer.analyze_template_for_documents(
- template_source="Analyze: @report",
+ template_source="Analyze:\n@report",
input_specs={"report": "Document"},
domain_code="test_pipes",
)
@@ -151,7 +151,7 @@ class TestTemplateDocumentAnalyzer:
# This analyzer should only return document references
result = TemplateDocumentAnalyzer.analyze_template_for_documents(
- template_source="Document: @doc, Image: @image",
+ template_source="Document:\n@doc\nImage:\n@image",
input_specs={"doc": "Document", "image": "Image"},
domain_code="test_pipes",
)
@@ -166,7 +166,7 @@ class TestTemplateDocumentAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateDocumentAnalyzer.analyze_template_for_documents(
- template_source="Document: @doc, Other: @other",
+ template_source="Document:\n@doc\nOther:\n@other",
input_specs={"doc": "Document", "other": "Text"},
domain_code="test_pipes",
)
diff --git a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py
index 813a55963..031463542 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py
@@ -25,7 +25,7 @@ class TestTemplateImageAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateImageAnalyzer.analyze_template_for_images(
- template_source="Describe this image: @image",
+ template_source="Describe this image:\n@image",
input_specs={"image": "Image"},
domain_code="test_pipes",
)
@@ -40,7 +40,7 @@ class TestTemplateImageAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateImageAnalyzer.analyze_template_for_images(
- template_source="Look at this: @page.page_view",
+ template_source="Look at this:\[email protected]_view",
input_specs={"page": "Page"},
domain_code="test_pipes",
)
@@ -68,7 +68,7 @@ class TestTemplateImageAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateImageAnalyzer.analyze_template_for_images(
- template_source="Compare @image_a with @image_b",
+ template_source="Compare:\n@image_a\nwith:\n@image_b",
input_specs={"image_a": "Image", "image_b": "Image"},
domain_code="test_pipes",
)
@@ -124,7 +124,7 @@ class TestTemplateImageAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateImageAnalyzer.analyze_template_for_images(
- template_source="Describe the page: @page",
+ template_source="Describe the page:\n@page",
input_specs={"page": "Page"},
domain_code="test_pipes",
)
@@ -137,7 +137,7 @@ class TestTemplateImageAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateImageAnalyzer.analyze_template_for_images(
- template_source="Process this: @text",
+ template_source="Process this:\n@text",
input_specs={"text": "Text"},
domain_code="test_pipes",
)
@@ -149,7 +149,7 @@ class TestTemplateImageAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateImageAnalyzer.analyze_template_for_images(
- template_source="Hello @name, your age is @age",
+ template_source="Hello $name, your age is $age",
input_specs={"name": "Text", "age": "Text"},
domain_code="test_pipes",
)
@@ -178,7 +178,7 @@ class TestTemplateImageAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateImageAnalyzer.analyze_template_for_images(
- template_source="Look at: @portrait",
+ template_source="Look at:\n@portrait",
input_specs={"portrait": "Image"},
domain_code="test_pipes",
)
@@ -234,7 +234,7 @@ class TestTemplateImageAnalyzer:
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
result = TemplateImageAnalyzer.analyze_template_for_images(
- template_source="Compare @extra_photo with {{ page | with_images }}",
+ template_source="Compare:\n@extra_photo\nwith {{ page | with_images }}",
input_specs={"extra_photo": "Image", "page": "Page"},
domain_code="test_pipes",
)
@@ -253,7 +253,7 @@ class TestValidateUnusedInputs:
# Should not raise
TemplateImageAnalyzer.validate_unused_inputs(
- template_sources=["Process @name and @age"],
+ template_sources=["Process $name and $age"],
input_specs={"name": "Text", "age": "Text"},
)
@@ -263,7 +263,7 @@ class TestValidateUnusedInputs:
with pytest.raises(UnusedInputError, match="unused_var"):
TemplateImageAnalyzer.validate_unused_inputs(
- template_sources=["Process @name"],
+ template_sources=["Process $name"],
input_specs={"name": "Text", "unused_var": "Text"},
)
@@ -273,7 +273,7 @@ class TestValidateUnusedInputs:
# name in first, age in second - both should pass
TemplateImageAnalyzer.validate_unused_inputs(
- template_sources=["Hello @name", "You are @age years old"],
+ template_sources=["Hello $name", "You are $age years old"],
input_specs={"name": "Text", "age": "Text"},
)
@@ -283,6 +283,6 @@ class TestValidateUnusedInputs:
# page.page_view should count page as used
TemplateImageAnalyzer.validate_unused_inputs(
- template_sources=["Look at @page.page_view"],
+ template_sources=["Look at $page.page_view"],
input_specs={"page": "Page"},
)
diff --git a/wip/template-preprocessor-css-collision.md b/wip/template-preprocessor-css-collision.md
new file mode 100644
index 000000000..65a467c84
--- /dev/null
+++ b/wip/template-preprocessor-css-collision.md
@@ -0,0 +1,147 @@
+# Template preprocessor — sigil collision with CSS, emails, and code
+
+## Context
+
+The template preprocessor at `pipelex/cogt/templating/template_preprocessor.py` rewrites three sigils into Jinja2 before rendering:
+
+- `@var` → `{{ var|tag("var") }}` (regex `r"@(?![0-9])([a-zA-Z0-9_.]+)"`)
+- `@?var` → optional insertion (`{% if var %}…{% endif %}`)
+- `$var` → `{{ var|format() }}`
+
+There is no escape mechanism today — only a `# TODO: allow escape patterns` comment. This produces silent breakage in any template whose source text legitimately contains an `@` or `$` followed by a word.
+
+## Observed failure
+
+PipeCompose templates that embed HTML/CSS in a `<style>` block break on CSS at-rules. Example from the wild:
+
+```html
+<style>
+ /* … */
+ @media (max-width: 820px) {
+ .fashion-project-page { padding: 24px; }
+ /* … */
+ }
+</style>
+```
+
+The preprocessor rewrites `@media` as a template variable. The downstream Jinja2 render then fails or produces garbage. Authoring agents currently work around this by deleting responsive blocks — losing functionality the template was meant to express.
+
+## The problem is wider than CSS
+
+The exact same regex misfires on:
+
+- **CSS at-rules**: `@media`, `@import`, `@keyframes`, `@font-face`, `@supports`, `@charset`, `@namespace`, `@page`, `@property`, `@layer`, `@container`, `@scope`, … plus everything CSS adds in the future.
+- **Email addresses** in body text: `[email protected]` → captures `example.com` as a variable (already documented in `test_email_address_partially_processed`).
+- **Code-block content in LLM prompts**: Python decorators (`@property`, `@staticmethod`, `@classmethod`), cron specs (`@daily`), social handles (`@username`).
+- **`$` has the symmetric problem**: bash vars in code blocks (`$PATH`), jQuery (`$(...)`), LaTeX math (`$…$`).
+
+Any solution scoped narrowly to CSS will be reopened the first time an agent generates an HTML template with an email address or a Python snippet.
+
+## Strategies considered
+
+### 1. Reserved CSS keyword list
+
+Maintain a static set of CSS at-rule names that the preprocessor leaves alone.
+
+- **Pros**: zero LLM cognitive overhead for the common case.
+- **Cons**: CSS-specific hack baked into a domain-agnostic templating layer; the list rots as CSS evolves; doesn't help emails / decorators / cron / handles; quietly reserves common words like `media`, `import`, `page`, `layer`, `property` as unusable variable names via `@var` syntax.
+
+### 2. Explicit escape (`@@` → literal `@`, `$$` → literal `$`)
+
+Add a Razor-style escape so authors can opt out of preprocessing on any `@` or `$`.
+
+- **Pros**: principled, generic, predictable; covers every present and future collision (CSS, emails, handles, decorators).
+- **Cons**: paste-existing-CSS-as-is doesn't "just work" — every at-rule needs `@@`. LLMs generating templates need to know the rule (prompt/doc burden).
+
+### 3. Smarter regex heuristics
+
+Refine the regex so it doesn't match the problematic shapes in the first place:
+
+- **`(?<!\w)` lookbehind before each sigil** — skips when the `@` or `$` is preceded by a word character. Kills emails: in `[email protected]`, the `@` is preceded by `r`, so it's skipped.
+- **`(?!\s*[({"'])` lookahead after the captured identifier** — skips when the identifier is followed by `(`, `"`, `'`, or `{` (with optional whitespace). Kills CSS at-rules: `@media (…)`, `@supports (…)`, `@import "…"`, `@charset "…"`, `@keyframes name {…}`, `@font-face {…}`, `@page {…}`, `@layer name {…}`, etc.
+
+Template variables in Pipelex are essentially never followed by `(` / `"` / `'` / `{`. The user confirmed that the only conceivable counter-example `@var (note)` does not occur in practice: `@var` is used for tagged block insertion, so wrapping the inserted block in a parenthetical immediately after would not make semantic sense.
+
+- **Pros**: zero burden on authors, no reserved names, no list to maintain, fixes CSS *and* emails in one stroke.
+- **Cons**: heuristic — there may be residual edge cases we haven't anticipated, which is why we want an escape too.
+
+### 4. Context-aware skipping (don't preprocess inside `<style>` / fenced code blocks)
+
+Parse the template enough to identify "code-like" regions and skip preprocessing inside them.
+
+- **Pros**: bulletproof inside the protected context.
+- **Cons**: real parsing complexity; doesn't help emails in body text; easy to get wrong (nested blocks, malformed HTML). Overkill.
+
+### 5. Stricter syntax (`@{var}`)
+
+Require a delimiter around the variable name.
+
+- **Pros**: cleanest theoretically.
+- **Cons**: breaking change across the entire MTHDS surface, churns every existing `.mthds` file, gives up the ergonomic appeal of bare `@var`. Not justified by the problem.
+
+## Decision
+
+Adopt **Strategy 3 (heuristic regex tightening) + Strategy 2 (explicit escape)**. Skip the rest.
+
+### Heuristic regex tightening (primary fix)
+
+Apply to all three sigils (`@`, `@?`, `$`):
+
+1. Add a `(?<!\w)` lookbehind in front of the sigil.
+2. Add a `(?!\s*[({"'])` lookahead immediately after the captured identifier.
+
+This silently fixes CSS at-rules, email addresses, and most code-block cases — with no author intervention, no reserved names, and no maintenance burden.
+
+### Explicit escape (safety net)
+
+1. Treat `@@` as a literal `@` (consumed during preprocessing).
+2. Treat `$$` as a literal `$` (consumed during preprocessing).
+3. The escape must be applied **after** sigil substitution so that `@@var` produces a literal `@var` and not a Jinja2 expression, but **before** Jinja2 receives the template.
+
+Heuristics fail silently; the escape gives authors a clean, explicit opt-out for any residual case the heuristic can't predict.
+
+### What we explicitly do not do
+
+- No reserved CSS keyword list.
+- No context-aware HTML parsing.
+- No breaking syntax migration.
+
+## Rationale for combining both layers
+
+- The heuristic alone makes the common case work for authors and LLMs without anyone having to know about escaping.
+- The escape alone forces every author and every prompt to learn the rule, and breaks paste-existing-CSS workflows.
+- Together, they cover the realistic surface: the heuristic handles the cases we can predict; the escape handles the cases we can't.
+
+## Scope of the change
+
+The preprocessor is shared across LLM prompts, PipeCompose templates, ImgGen prompts, and template document analyzers — all the call sites in:
+
+- `pipelex/pipe_operators/llm/pipe_llm_blueprint.py`
+- `pipelex/pipe_operators/llm/template_document_analyzer.py`
+- `pipelex/pipe_operators/compose/construct_blueprint.py`
+- `pipelex/pipe_operators/compose/pipe_compose_blueprint.py`
+- `pipelex/pipe_operators/compose/pipe_compose_factory.py`
+- `pipelex/pipe_operators/shared/template_image_analyzer.py`
+- `pipelex/pipe_operators/search/pipe_search_blueprint.py`
+- `pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py`
+- `pipelex/cogt/templating/template_blueprint.py`
+
+A single change to `preprocess_template` covers all of them.
+
+## Backward compatibility
+
+- The `(?!\s*[({"'])` lookahead changes the meaning of templates that currently match `@var (...)` or `$var "...`". The user confirmed `@var (…)` is not a real pattern (tagged blocks make a trailing parenthetical nonsensical). For `$` the same reasoning applies — `$var` is value formatting; a trailing parenthesized phrase is also unidiomatic.
+- The `(?<!\w)` lookbehind changes templates where `@var` immediately follows a word character. Today such templates already produce surprising results (see the email test); tightening here is a behavior fix, not a regression.
+- `@@` and `$$` are not currently meaningful in templates, so consuming them as escapes is a pure addition.
+
+A workspace-wide grep over existing `.mthds` files should confirm zero collisions before merge.
+
+## Documentation follow-ups (out of scope of this change, tracked separately)
+
+- Update agent-facing MTHDS authoring guidance to mention `@@` and `$$` escapes.
+- Add a short "writing templates with code/HTML inside" section to the docs.
+- Update the existing `test_email_address_partially_processed` semantics: emails should now pass through cleanly.
+
+## Open questions
+
+None blocking. The user confirmed the `@var (…)` edge case is not real, which removes the only material concern with the heuristic.
diff --git a/wip/template-preprocessor-line-bounded-at.md b/wip/template-preprocessor-line-bounded-at.md
new file mode 100644
index 000000000..11197ccfd
--- /dev/null
+++ b/wip/template-preprocessor-line-bounded-at.md
@@ -0,0 +1,341 @@
+# Template preprocessor — strict line-bounded `@` sigil (TDD plan)
+
+## Status: Open. Supersedes `wip/template-preprocessor-residual-edge-cases.md`. Adapts from the current state of `fix/Template-preprocessor-footguns` (the CSS / email / escape work shipped on this branch — that work stays; this plan strips the now-unnecessary heuristics on `@` and replaces them with a strict line-bounded rule + a load-time validator).
+
+## Why this design (one paragraph)
+
+`@var` produces `<var>...</var>` (a block-shaped envelope via the `tag()` filter). `$var` produces inline `format()` output. The existing collisions (`@media`, `@import`, `@font-face`, `[email protected]`, `@status. Amount (USD).`, `@var {{ jinja }}`, …) are all symptoms of letting `@` do inline duty when its rendered shape is fundamentally block-level. Restricting `@` to "alone on its own line" aligns syntax with semantics, makes the regex trivial, and turns silent pass-through (the current footgun) into a loud, actionable error.
+
+## Quick start (cold session)
+
+Working directory: `/Users/lchoquel/repos/Pipelex/pipelex` (the `pipelex/` runtime repo inside the multi-repo workspace at `/Users/lchoquel/repos/Pipelex/`).
+
+Read in this order:
+
+1. This file.
+2. `pipelex/cogt/templating/template_preprocessor.py` — current implementation (~100 lines, post-CSS-collision fix).
+3. `pipelex/cogt/templating/template_blueprint.py` — where `TemplateBlueprint` runs its pydantic `validate_template` hook; the new sigil validator hooks in alongside the existing Jinja2 syntax check.
+4. `pipelex/pipe_operators/llm/pipe_llm_blueprint.py:33-62` — example of the existing `preprocess_template + detect_jinja2_required_variables` pattern in a blueprint's `validate_inputs`; the new exception flows through this surface.
+5. `tests/unit/pipelex/cogt/templating/test_template_preprocessor.py` — single `TestTemplatePreprocessor` class with ~80 tests; many existing tests use inline `@var` and will be rewritten or repurposed.
+6. `wip/template-preprocessor-residual-edge-cases.md` — obsolete under the new rule for the `@` cases; the `$` residuals listed there are explicit non-goals here (see §Out of scope).
+
+Project conventions (from `pipelex/CLAUDE.md`):
+
+- One `TestClass` per test module. Keep everything inside `TestTemplatePreprocessor`.
+- pytest-mock, never `unittest.mock`.
+- `make agent-check` after code changes (Ruff + pyright + mypy + plxt).
+- Targeted test: `.venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`.
+- Full impacted run: see the source-to-test mapping in `pipelex/tests/CLAUDE.md` — `pipelex/cogt/` touches `tests/unit/pipelex/cogt/ tests/integration/pipelex/cogt/`, and the `pipe_operators` blueprints touch `tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/`.
+
+## Target behavior
+
+### `@` and `@?` — line-bounded only
+
+An `@var` or `@?var` sigil is recognized **only** when it is the entire content of a line (leading/trailing whitespace allowed). Anything else containing a candidate sigil shape is an error at load time.
+
+```text
+✓ @invoice_text → {{ invoice_text|tag("invoice_text") }}
+✓ @?notes → {% if notes %}{{ notes|tag("notes") }}{% endif %}
+✓ @user.profile.bio → {{ user.profile.bio|tag("user.profile.bio") }}
+
+✗ Extract from @invoice_text. → ERROR: inline @invoice_text (line 1). Use $invoice_text for inline, or move @invoice_text onto its own line.
+✗ Hello @name! → ERROR: inline @name (line 1). …
+✗ @var $other_var → ERROR: @var is not alone on its line (line 1). …
+✗ The value (@value) is … → ERROR: inline @value (line 1). …
+```
+
+Identifier shape (unchanged in spirit, tightened slightly): `[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*`. First char must be a letter or underscore (not a digit); dotted access supported; no trailing dot in the capture.
+
+### `$` — unchanged
+
+`$var` keeps its current inline behavior, lookaheads, and `(?![0-9])` digit guard. Known `$` residuals (`$name {{ jinja }}` not rewriting, `$user. info()` not rewriting) are explicit non-goals here — see §Out of scope.
+
+### `@@` and `$$` escapes — unchanged
+
+`@@` → literal `@`, `$$` → literal `$`. The sentinel substitution runs before validation and before the regex pass, so escaped occurrences never reach the validator and never trip the strict rule. Authors with literal CSS at-rules (`@@media`, `@@font-face`) or literal dollar amounts (`$$10`) escape with the doubled sigil.
+
+### Candidate sigil definition (the validator's scope)
+
+The validator does **not** flag every `@` in the template. It flags only "candidate sigils" — shapes that look like a malformed `@`/`@?` interpolation:
+
+- `@` (or `@?`) **not** preceded by a word character (post-`@@`-escape).
+- Followed immediately (no whitespace) by an identifier-shape capture.
+- On a line that is not solely that sigil + optional whitespace.
+
+This means:
+
+- `[email protected]` — `@` preceded by `e` (word char) → not a candidate → silently passes through. (Matches the current lookbehind protection.)
+- `@Override`, `@deprecated` in a code block at line start — IS a candidate (line-start `@` + identifier) → error if not alone. Authors escape with `@@Override` if they want literal.
+- `@media (max-width: 820px) {` — IS a candidate → error if not alone. Authors escape with `@@media`.
+- `@ media` (space after `@`) — not a candidate (no identifier immediately after `@`) → silently passes through.
+
+The validator's error message must include:
+
+- The line number (1-based).
+- The offending span (the `@` and the identifier).
+- A concrete migration hint: "Did you mean `$var` (inline) or move `@var` onto its own line? Escape with `@@` for a literal `@`."
+
+## Target code
+
+### Preprocessor (`pipelex/cogt/templating/template_preprocessor.py`)
+
+Replace `_SIGIL_PATTERN` (the unified alternation) with two patterns:
+
+```python
+# Line-bounded @ / @? sigil — must be alone on its own line.
+_AT_SIGIL_PATTERN = re.compile(
+ r"^[ \t]*(@\??)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)[ \t]*$",
+ re.MULTILINE,
+)
+
+# Inline $ sigil — current heuristics, unchanged in scope (digit guard + identifier-class boundary
+# + code/CSS-shape lookahead). The `@` arm is gone from this pattern entirely.
+_DOLLAR_SIGIL_PATTERN = re.compile(
+ r"(\$)(?![0-9])([a-zA-Z0-9_.]+)(?![a-zA-Z0-9_.])(?!\s*[({\"'])",
+)
+
+# Candidate-sigil detector for the validator: any unescaped @ at non-word boundary, followed by
+# an identifier shape. Used only to surface errors; never substitutes.
+_AT_CANDIDATE_PATTERN = re.compile(
+ r"(?<!\w)(@\??)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)",
+)
+```
+
+`_replace_sigil` collapses to two arms (no more `_Sigil.AT` vs `_Sigil.AT_OPTIONAL` ambiguity in shared code) but the `_Sigil` enum stays — used by both `@` and `$` callbacks.
+
+Trailing-dot handling stays in the `$` callback (where it still matters for prose like `$amount.`). It can be dropped from the `@` callback because the line-bounded regex cannot capture a trailing dot — the identifier class no longer includes `.` at segment boundaries.
+
+`preprocess_template` flow:
+
+```python
+def preprocess_template(template: str) -> str:
+ # 1. Escape sentinels first — @@ and $$ disappear before validation and substitution.
+ processed = template.replace("@@", _AT_ESCAPE_SENTINEL).replace("$$", _DOLLAR_ESCAPE_SENTINEL)
+
+ # 2. Validate: any candidate @-sigil that is not alone on its line is an error.
+ _validate_at_sigil_alone_on_line(processed)
+
+ # 3. Substitute: @ line-bounded first, then $ inline. (Two passes are safe — @ output occupies
+ # whole lines, so the $ pattern's lookahead never sees @-introduced braces.)
+ processed = _AT_SIGIL_PATTERN.sub(_replace_at_sigil, processed)
+ processed = _DOLLAR_SIGIL_PATTERN.sub(_replace_dollar_sigil, processed)
+
+ # 4. Restore sentinels.
+ return processed.replace(_AT_ESCAPE_SENTINEL, "@").replace(_DOLLAR_ESCAPE_SENTINEL, "$")
+```
+
+### New exception (`pipelex/cogt/templating/template_errors.py`, new module)
+
+```python
+from pipelex.system.exceptions import ToolError
+
+
+class TemplateSigilSyntaxError(ToolError):
+ """Raised when a template contains a sigil shape that violates the strict @-line rule.
+
+ The error message includes the line number, the offending span, and a migration hint.
+ """
+```
+
+Placed alongside the other templating utilities, not under `tools/jinja2/`, because this is about Pipelex sigils, not about Jinja2 itself. Mirrors the `Jinja2TemplateSyntaxError` pattern in shape and ergonomics.
+
+### Validator (`pipelex/cogt/templating/template_preprocessor.py`)
+
+```python
+def _validate_at_sigil_alone_on_line(template: str) -> None:
+ """Scan for candidate `@` / `@?` sigils that are not alone on their own line and raise.
+
+ Inputs are post-`@@`-escape (so `@@` cases are already replaced by sentinels and don't trip
+ the check). Word-adjacent `@` (emails, prose hashtags) is excluded by the `(?<!\w)`
+ lookbehind on the candidate pattern.
+ """
+ for line_index, line in enumerate(template.split("\n"), start=1):
+ if "@" not in line:
+ continue
+ if _AT_SIGIL_PATTERN.fullmatch(line):
+ continue
+ candidate = _AT_CANDIDATE_PATTERN.search(line)
+ if candidate is None:
+ continue
+ sigil = candidate.group(1)
+ identifier = candidate.group(2)
+ msg = (
+ f"Inline `{sigil}{identifier}` is not allowed on line {line_index}: "
+ f"the `{sigil}` sigil produces tag-wrapped block content and must appear alone on "
+ f"its own line. "
+ f"Did you mean `${identifier}` (inline value), or move `{sigil}{identifier}` onto "
+ f"its own line? "
+ f"Escape with `@@` if you intend a literal `@`."
+ )
+ raise TemplateSigilSyntaxError(msg)
+```
+
+Loop semantics: report the first offending line, not all of them. Authors fix one, re-run, fix the next — cheaper to read than a bulk dump. (Worth confirming with the user before locking — see §Open decisions.)
+
+### Blueprint integration
+
+The existing `validate_inputs` methods in each pipe blueprint already call `preprocess_template(self.prompt)`. They need to catch `TemplateSigilSyntaxError` and re-raise with pipe-specific context, mirroring how they handle `Jinja2DetectVariablesError`:
+
+```python
+try:
+ preprocessed_template = preprocess_template(self.prompt)
+except TemplateSigilSyntaxError as exc:
+ msg = f"Template sigil error in PipeLLM prompt: {exc}"
+ raise ValueError(msg) from exc
+```
+
+Same surface in `pipe_compose_blueprint.py`, `pipe_compose_factory.py`, `pipe_img_gen_blueprint.py`, `pipe_search_blueprint.py`, `pipe_compose/construct_blueprint.py`. And `TemplateBlueprint.validate_template` gets the same treatment.
+
+The `ValueError` wrapping is what pydantic surfaces in its validation error report — same path as the existing template-parsing errors. LSP / `plxt check` already render these cleanly.
+
+## Test migration framing
+
+Many tests in `test_template_preprocessor.py` exercise inline `@var` shapes that were valid under the heuristic and are invalid under the strict rule. They split into three buckets:
+
+1. **Generic-variable tests that just happen to use `@`.** Example: `test_variable_followed_by_comma` (`"Values: @first, @second, and @third"`). The point is "a sigil followed by punctuation works"; switching to `$first, $second` keeps the intent and matches the actual semantic (inline value). Rewrite the input to use `$`.
+
+2. **Tests that specifically validated the old `@`-can-be-inline contract.** Example: `test_at_variable_with_trailing_dot`, `test_back_to_back_at_variables`, `test_variable_in_parentheses`. Convert to `pytest.raises(TemplateSigilSyntaxError)` (or via a parametrized error-shape test) — these are the new contract tests.
+
+3. **Tests of `$` behavior, escape behavior, or `@` alone on a line.** Untouched. Example: `test_dollar_amounts_not_processed`, `test_double_at_escapes_to_literal_at`, `test_at_variable_pattern` (already uses `@expense\n@invoices`), `test_optional_at_variable_pattern` (uses `@?optional_field` on its own line), `test_variable_alone_on_line`, all CSS pass-through tests.
+
+The residual-rewrite tests (`test_css_namespace_residual_rewritten`, `test_css_font_face_residual_rewritten`, `test_css_dash_residual_rewritten`) get deleted — the residuals don't exist under the new rule. The companion escape tests (`test_css_namespace_escaped_pass_through`, `test_css_font_face_escaped_pass_through`, `test_css_dash_residual_escape_workaround`) stay — `@@` still works.
+
+CSS pass-through tests (`test_css_media_query_pass_through`, `test_css_supports_pass_through`, etc.) need a behavior change: today they assert the input passes through unchanged. Under the new rule, they assert the input **raises** `TemplateSigilSyntaxError`. The intent ("CSS at-rules are not sigils") is the same; the enforcement is now strict, not heuristic.
+
+Email pass-through tests (`test_email_address_pass_through`, `test_email_in_sentence_pass_through`, `test_word_adjacent_at_pass_through`) stay as pass-through — emails have a word char before `@`, so they're not candidate sigils and don't trip the validator.
+
+## Phases
+
+### Phase 1 — Replace the residuals doc and lock the plan
+
+- [x] Write this plan doc (`wip/template-preprocessor-line-bounded-at.md`).
+- [ ] Update `TODOS.md` so the next person opening the repo sees a single pointer to this file. The "Status: Complete" header from the prior CSS-collision work stays as history; a new "Next phase" section at the top points here.
+- [ ] Mark `wip/template-preprocessor-residual-edge-cases.md` as superseded (one-line note at the top pointing to this file). Don't delete it yet — it's still useful as history for the `$` residuals, which remain open.
+
+### Phase 2 — TDD red: new tests for the strict contract
+
+All new tests inside `TestTemplatePreprocessor`. Don't open a second class.
+
+- [x] **Strict-line success cases** (parametrized, all alone-on-line forms): `@var`, `@?var`, `@user.profile.bio`, `@_private_var`, ` @indented_var`, `@var\t` (trailing tab). Each rewrites correctly.
+- [x] **Strict-line error cases** (parametrized, all raising `TemplateSigilSyntaxError` with the expected message components — line number, offending span, migration hint):
+ - Inline mid-sentence: `Extract from @invoice_text. Done.`
+ - Inline trailing punctuation: `@var.`, `@var,`, `@var!`, `@var?`, `@var;`, `@var:`
+ - Inline parenthetical: `(@var)`, `[@var]`
+ - Multiple sigils per line: `@a @b`, `@a $b`, `$b @a`
+ - Word-adjacent (but not email — preceded by space): `Word @var`, `@var Word`
+ - CSS at-rules: `@media (max-width: 820px) {`, `@font-face { font-family: "X"; }`, `@import url("reset.css");`, `@keyframes spin { from {…} }`
+ - Code constructs: `@Override`, `@deprecated def foo():`
+- [x] **Word-adjacent silent pass-through** (parametrized): `[email protected]`, `[email protected]`, `Send to [email protected] immediately.`, `prefix@suffix`. Each passes through unchanged with no error.
+- [x] **Escape cases unchanged**: existing `test_double_at_*`, `test_quadruple_at_is_two_escapes`, `test_escape_does_not_consume_legit_variable`, `test_escape_inside_style_block`. All still green. (Note: `test_triple_at_is_escape_plus_variable` survives Phase 2 untouched but is destined for Phase 3 conversion to `pytest.raises` — `@@@var` post-sentinel resolves to `<sentinel>@var`, which is no longer alone-on-line under the strict rule.)
+- [x] **Full style block now raises**: rewrote `test_full_style_block_pass_through` → `test_full_style_block_raises_under_strict_rule` (expects `TemplateSigilSyntaxError`) and added companion `test_full_style_block_escaped_pass_through` using `@@media` / `@@supports`.
+- [x] **Blueprint integration tests**: added three tests in `tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py` (note: actual dir is `pipe_llm/`, not `llm/`) — prompt-field, system_prompt-field, and multi-line line-number variants — each asserting pydantic surfaces `@var`, `$var` (migration), `@@` (escape), and `line N`.
+- [x] Run the suite. Confirmed: 23 red in preprocessor + 3 red in blueprint = 26 expected failures; 93 + 11 = 104 untouched tests still green.
+
+**Checkpoint A — DONE.** Phase 2 left the repo in a clean red state. Notes for whoever picks up Phase 3+:
+
+1. **Whitespace preservation deviation from §Target code.** The Phase 2 success-case tests assert that leading and trailing whitespace on indented alone-on-line forms is **preserved** (` @indented_var` → ` {{ indented_var|tag("indented_var") }}`, `@var\t` → `{{ var|tag("var") }}\t`). The plan's literal regex `r"^[ \t]*(@\??)(ident)[ \t]*$"` would consume the whitespace into the match and the `re.sub` callback would drop it. Phase 4 must use capture groups for leading/trailing whitespace and re-emit them in `_replace_at_sigil`, e.g.:
+
+ ```python
+ _AT_SIGIL_PATTERN = re.compile(
+ r"^([ \t]*)(@\??)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)([ \t]*)$",
+ re.MULTILINE,
+ )
+ # callback: f"{leading}{rendered}{trailing}"
+ ```
+
+ This decision keeps templates embedded in indented YAML/TOML blocks rendering in the same column as the surrounding text. If you'd rather have whitespace eaten, flip the tests in `test_strict_line_at_sigil_success` (cases `indented_at_var`, `trailing_tab_at_var`, `tab_indented_optional_at_var`, `indented_at_var_in_block`) and drop the capture groups.
+
+2. **Skeleton-only `template_errors.py`.** `TemplateSigilSyntaxError(ToolError)` exists with no behavior. Phase 4 adds `_validate_at_sigil_alone_on_line` in `template_preprocessor.py` and the validator is what makes the red tests go green.
+
+3. **Phase 1 housekeeping still open.** Phase 1's checklist had two unticked items (TODOS.md pointer; superseded note on `wip/template-preprocessor-residual-edge-cases.md`). Those are still open. Pick them up before Phase 3 or fold them into Phase 6's docs work.
+
+4. **Targeted test commands for resuming work.**
+
+ ```bash
+ .venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
+ .venv/bin/pytest -q tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py
+ ```
+
+ Expected at start of Phase 3: 23 red + 3 red. After Phase 3 rewrite: many more red (legacy inline-`@` tests converted to `pytest.raises`). After Phase 4 implementation: all green.
+
+### Phase 3 — TDD red: rewrite the inline-`@` tests
+
+This is the meaty migration. Each test gets sorted into one of the three buckets in §Test migration framing.
+
+- [ ] Walk every test in `test_template_preprocessor.py` (and `test_template_pipeline.py`). For each that uses inline `@var`:
+ - Bucket 1 (generic, switch to `$`): rewrite input from `@var` to `$var`, rewrite expected from `{{ var|tag(...) }}` to `{{ var|format() }}`.
+ - Bucket 2 (specifically asserts `@` inline): convert to `pytest.raises(TemplateSigilSyntaxError)` (or fold into the parametrized error-cases test added in Phase 2 and delete the standalone test).
+ - Bucket 3 (already alone-on-line, or about `$`/escapes): no change.
+- [ ] Delete `test_css_*_residual_rewritten` and `test_css_dash_residual_rewritten` — residuals don't exist under the new rule.
+- [ ] Rewrite the CSS pass-through tests (`test_css_media_query_pass_through` etc.) to expect `TemplateSigilSyntaxError`. Keep the escape companions as pass-through assertions.
+- [ ] Run the suite. State: even more red.
+
+### Phase 4 — Implementation (green)
+
+- [ ] Add `pipelex/cogt/templating/template_errors.py` with `TemplateSigilSyntaxError(ToolError)`.
+- [ ] In `template_preprocessor.py`:
+ - [ ] Replace `_SIGIL_PATTERN` with `_AT_SIGIL_PATTERN`, `_DOLLAR_SIGIL_PATTERN`, `_AT_CANDIDATE_PATTERN` (see §Target code).
+ - [ ] Split `_replace_sigil` into `_replace_at_sigil` and `_replace_dollar_sigil`. Drop trailing-dot handling from the `@` callback; keep it in the `$` callback.
+ - [ ] Add `_validate_at_sigil_alone_on_line` (see §Target code).
+ - [ ] Rewrite `preprocess_template` to: escape → validate → AT pass → DOLLAR pass → restore.
+- [ ] Update the docstring at the top of `template_preprocessor.py` to describe the strict rule and the candidate-sigil validator. Strip the long comment block describing the heuristic alternatives — it's no longer applicable.
+- [ ] In each pipe blueprint that calls `preprocess_template` (`pipe_llm_blueprint.py`, `pipe_compose_blueprint.py`, `pipe_compose_factory.py`, `pipe_img_gen_blueprint.py`, `pipe_search_blueprint.py`, `compose/construct_blueprint.py`, `shared/template_image_analyzer.py`, `template_document_analyzer.py`): wrap the `preprocess_template` call in `try/except TemplateSigilSyntaxError` and re-raise as `ValueError` with pipe-specific context. Mirror the existing `Jinja2DetectVariablesError` pattern.
+- [ ] Update `TemplateBlueprint.validate_template` to call `preprocess_template` and catch the new exception.
+- [ ] Run the suite. Expected: all Phase 2 + Phase 3 tests now green; legacy tests still green.
+
+**Checkpoint B**: Phase 4 done when `make agent-check` is clean and the targeted test run (`tests/unit/pipelex/cogt/ tests/unit/pipelex/pipe_operators/`) is green.
+
+### Phase 5 — Workspace sanity check
+
+Look for any `.mthds` file in the workspace that would now fail validation.
+
+- [ ] From the workspace root (`/Users/lchoquel/repos/Pipelex/`), run:
+
+ ```bash
+ # Inline @-sigil candidates — anything @var that's not on its own line:
+ grep -rEn '(^|[^[:alnum:]_])@\??[a-zA-Z_][a-zA-Z0-9_.]*' --include="*.mthds" . | \
+ grep -vE '^[^:]+:[0-9]+:[[:space:]]*@\??[a-zA-Z_][a-zA-Z0-9_.]*[[:space:]]*$' | \
+ head -50
+
+ # Existing @@ / $$ usages (already correct):
+ grep -rEn '@@|\$\$' --include="*.mthds" . | head -50
+ ```
+- [ ] For each hit, decide: migrate to `$var` (inline), reshape onto its own line, or escape with `@@` (literal `@`). Document the migration list in this file under a new "Workspace migration" section.
+- [ ] If hits exist in `methods/`, `pipelex-cookbook/`, `test-bed/`, or fixture-shipped `.mthds`, write the migrations as part of this branch. If hits exist in `mthds-plugins/` (the marketplace plugin), STOP and flag to the user — that repo isn't ours to touch from here.
+
+### Phase 6 — Authoring docs + CHANGELOG
+
+- [ ] Update `CHANGELOG.md` under `[Unreleased]`:
+ - Replace the prior `### Fixed` entry for CSS collision with a `### Changed` (breaking) entry describing the new strict rule.
+ - Keep the `### Added` entry for `@@` / `$$` escapes — still accurate.
+ - Add a short migration note: "Inline `@var` is now a load-time error. Use `$var` for inline values, keep `@var` alone on its own line, or escape with `@@` for a literal `@`."
+- [ ] Update MTHDS authoring guidance to reflect the strict rule. Likely targets:
+ - `pipelex/builder/` prompts and any in-repo authoring docs.
+ - The MTHDS spec / `mthds-language-tutorial.md` (in the `mthds/` workspace repo) — **only if** the user explicitly opts in to a cross-repo doc change. Per the workspace rule, default is to leave the spec doc edits to a separate PR.
+- [ ] Update any IDE-side documentation (vscode-pipelex sees this via plxt — if plxt's diagnostics output changes, note it).
+
+### Phase 7 — Lint + full tests
+
+- [ ] `make agent-check` — Pyright, Ruff, Mypy, plxt all clean.
+- [ ] Targeted: `.venv/bin/pytest -n auto -m "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api" -o log_level=WARNING --tb=short -q tests/unit/pipelex/cogt/ tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/`
+- [ ] `make agent-test` — full suite green.
+
+**Checkpoint C**: Ready to ship via `/release`.
+
+## Open decisions to confirm before Phase 4
+
+These are small enough that I'll make a default call and proceed; flag any objections before locking in.
+
+1. **Validator reports first error, not all errors.** Default: yes (cheaper to read; matches Jinja2 syntax error behavior). Alternative: accumulate all sigil errors per template and raise once with a list — only worth it if templates regularly have many errors at once, which is unlikely.
+2. **Indented `@var` allowed.** Default: yes — `^[ \t]*@var[ \t]*$` permits leading indentation. Useful for templates embedded in YAML strings or indented blocks. Trailing whitespace too (forgiving on author trailing spaces). Alternative: zero indentation only — stricter but probably too aggressive for indented YAML / TOML embeddings.
+3. **Trailing-dot handling stays on `$`.** Default: yes — `$amount.` → `{{ amount|format() }}.` still works (existing behavior). The `@` callback drops the trailing-dot logic because the line-bounded regex can't capture one.
+4. **No accumulation across blueprints.** Default: each blueprint's `validate_inputs` raises the first sigil error it hits, even if the same .mthds file has more in other prompts (system_prompt, sub-templates). Pydantic's accumulation handles cross-field collection at the model level — the per-call raise is fine.
+
+## Out of scope / explicit non-goals
+
+- **`$` residuals from `wip/template-preprocessor-residual-edge-cases.md`.** `$name {{ jinja }}` not rewriting and `$user. info()` not rewriting are real but separate. They affect `$`, which keeps its inline contract. If we tackle them, it's a follow-up PR.
+- **Reserved-keyword list for CSS at-rules.** Not needed — the strict rule means CSS pass-through is by accident-free design (CSS at-rules always have content after them, so they're always inline candidates, so they always raise unless escaped).
+- **Auto-rewriting `@var` to `$var` in a migration tool.** If the workspace sanity check turns up enough hits that manual migration is painful, we could write a one-shot `plxt fix-sigils` command. Not in scope for this branch.
+- **HTML/`<style>`-aware parsing of templates.** Templates remain plain strings to the preprocessor.
+- **Changing the `tag()` / `format()` filter shapes.** Out of scope; this work is purely about which sigil sources rewrite into which Jinja form.
+- **Spec doc updates in the cross-repo `mthds/` repo.** Per the workspace plugin rule, default is to leave spec edits for a separate PR initiated from that repo.
diff --git a/wip/template-preprocessor-residual-edge-cases.md b/wip/template-preprocessor-residual-edge-cases.md
new file mode 100644
index 000000000..0179ad119
--- /dev/null
+++ b/wip/template-preprocessor-residual-edge-cases.md
@@ -0,0 +1,280 @@
+# Template preprocessor — residual edge cases (deferred)
+
+## Status: Superseded for the `@` cases by `wip/template-preprocessor-line-bounded-at.md` (2026-05-13). The strict line-bounded `@` rule eliminates Residual 1 and Residual 2 below — both are about inline `@var` shapes that are no longer valid under the new contract. The `$` variants of the same issues (`$name {{ jinja }}` not rewriting, `$user. info()` not rewriting) remain open and are explicit non-goals of the line-bounded plan; this doc stays as the reference if/when those `$` residuals are tackled in a follow-up PR.
+
+## Original status (historical): Open. Two false-negatives observed during PR review of `fix/Template-preprocessor-footguns` (2026-05-13). Not blocking — the CSS / email / code collisions that motivated the original fix all work. These are subtle shapes that the heuristic still silently passes through without interpolation.
+
+## Quick start (cold session)
+
+Working directory: `/Users/lchoquel/repos/Pipelex/pipelex`.
+
+Read in this order:
+
+1. This file.
+2. `wip/template-preprocessor-css-collision.md` — original design rationale (Strategy 2 + Strategy 3 from there shipped; this doc adds two more residuals on top).
+3. `pipelex/cogt/templating/template_preprocessor.py` — ~85 lines, the file being changed.
+4. `tests/unit/pipelex/cogt/templating/test_template_preprocessor.py` — the test file being extended (single `TestTemplatePreprocessor` class, 80 tests today).
+
+Project conventions (from `pipelex/CLAUDE.md`):
+
+- One `TestClass` per test module. New tests go inside `TestTemplatePreprocessor`.
+- pytest-mock, never `unittest.mock`. Neither residual needs mocking.
+- `make agent-check` after changes (Ruff + pyright + mypy + plxt).
+- Targeted test: `.venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`.
+
+## Current state of the regex (post-CSS-collision fix)
+
+`pipelex/cogt/templating/template_preprocessor.py:55-58`:
+
+```python
+_SIGIL_PATTERN = re.compile(
+ r"(?:(?<!\w)(@\??)|(\$))(?![0-9])([a-zA-Z0-9_.]+)(?![a-zA-Z0-9_.])"
+ r"(?!\s*(?:[({\"']|[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))))"
+)
+```
+
+Three parts that matter here:
+
+- **Identifier class** `[a-zA-Z0-9_.]+` — greedy, includes trailing dots; stripped in the dispatcher (`_replace_sigil`) when the captured name ends with `.`.
+- **Direct opener arm** `[({\"']` — blocks `@var (...)`, `@var "..."`, `@var '...'`, `@var {`.
+- **Inner-word arm** `[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))` — blocks one word + `(` or single `{` (the `\{(?!\{)` is the Jinja-aware part: `{{` is allowed).
+
+Both residuals below stem from quirks of these three pieces.
+
+---
+
+## Residual 1 — `@var {{ jinja }}` / `$var {{ jinja }}` not rewritten
+
+### Symptom
+
+```python
+preprocess_template("Hello @name {{ greeting }}")
+# 'Hello @name {{ greeting }}' ← @name NOT rewritten (expected: {{ name|tag("name") }})
+
+preprocess_template("Hello $name {{ greeting }}")
+# 'Hello $name {{ greeting }}' ← same problem on the $ arm
+```
+
+### Root cause
+
+The **inner-word arm** uses `\{(?!\{)` so it allows `{{` (it only blocks a single `{` that isn't part of Jinja's `{{`). The **direct opener arm** doesn't — `[({\"']` matches any single `{`, including the first `{` of `{{`.
+
+So `@name {{` walks the direct arm:
+
+- `\s*` matches the space.
+- `[({\"']` tries `{` — matches. Direct arm fires.
+- Negative lookahead fails → `@name` is not matched.
+
+The inner-word arm and the direct arm are inconsistent: the design comment on `pipelex/cogt/templating/template_preprocessor.py:38-41` explicitly says `@var with {{ ... }}` should remain interpolated. Today it doesn't.
+
+### Fix sketch
+
+Split the `{` case out of the direct arm and reuse the `\{(?!\{)` trick:
+
+```python
+_SIGIL_PATTERN = re.compile(
+ r"(?:(?<!\w)(@\??)|(\$))(?![0-9])([a-zA-Z0-9_.]+)(?![a-zA-Z0-9_.])"
+ r"(?!\s*(?:[(\"']|\{(?!\{)|[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))))"
+)
+```
+
+The change is `[({\"']` → `[(\"']|\{(?!\{)`. After the fix:
+
+- `@var (...)` — `(` matches the bracket class. ✓ still blocked.
+- `@var "..."`, `@var '...'` — same. ✓ still blocked.
+- `@var {` — `\{(?!\{)` matches (single `{`). ✓ still blocked.
+- `@page { margin }` — same as above. ✓ still blocked.
+- `@var {{ jinja }}` — `\{(?!\{)` fails because next char is `{`. Direct arm doesn't fire. Inner-word arm starts with `[a-zA-Z]` — `{` not in class, fails. Whole lookahead doesn't fire. `@var` IS rewritten. ✓ fixed.
+
+### Tests to add (red phase, inside `TestTemplatePreprocessor`)
+
+```python
+def test_at_var_then_jinja_open_rewrites(self):
+ """`@var {{ jinja }}` must rewrite @var — the direct-opener arm must be Jinja-aware."""
+ template = "Hello @name {{ greeting }}"
+ result = preprocess_template(template)
+ expected = 'Hello {{ name|tag("name") }} {{ greeting }}'
+ assert result == expected
+
+def test_dollar_var_then_jinja_open_rewrites(self):
+ """`$var {{ jinja }}` must rewrite $var — same fix as the @ arm."""
+ template = "Hello $name {{ greeting }}"
+ result = preprocess_template(template)
+ expected = "Hello {{ name|format() }} {{ greeting }}"
+ assert result == expected
+```
+
+Also add a regression guard so `@var {` (single brace, not Jinja) stays blocked:
+
+```python
+def test_at_var_then_single_brace_pass_through(self):
+ """`@var {` (single brace, not Jinja) is still a code-shape opener — must NOT rewrite."""
+ template = "Try @var { but not jinja"
+ result = preprocess_template(template)
+ assert result == template
+```
+
+### Open question for the implementer
+
+Is `@var {` (single brace) ever a legit Pipelex template construct? Probably not — the design doc says template variables aren't followed by `("'{` in practice. Keep the single-`{` block as-is; only `{{` becomes safe.
+
+---
+
+## Residual 2 — `@var.` (trailing dot) + ` Word (` not rewritten
+
+### Symptom
+
+```python
+preprocess_template("The transaction was @status. Amount (USD).")
+# 'The transaction was @status. Amount (USD).' ← @status NOT rewritten
+
+preprocess_template("Reply @user. info()")
+# 'Reply @user. info()' ← @user NOT rewritten
+```
+
+Realistic shape: a sentence-ending sigil followed by a new sentence that contains a parenthetical (very common in prose-heavy LLM prompts).
+
+### Root cause
+
+Two interacting design choices:
+
+1. **Identifier class `[a-zA-Z0-9_.]+` includes `.`**, so the greedy match consumes the trailing dot — the dispatcher then strips it as sentence punctuation. This was the cheapest way to support both `@user.profile` (dotted access) and `@user.` (sentence end).
+
+2. **Backtracking is locked out by `(?![a-zA-Z0-9_.])`** — the post-identifier check. The greedy match captures `status.`; if the lookahead fails, the engine tries `status` (no dot), but `(?![a-zA-Z0-9_.])` then fails because the next char is `.`. No shorter match works.
+
+Concrete walk for `@status. Amount (USD)`:
+
+- Identifier matches `status.` (greedy with dot).
+- `(?![a-zA-Z0-9_.])` passes (next char is `S`).
+- Inner-word arm: `\s*` consumes ` `, `[a-zA-Z][\w-]*` matches `Amount`, `\s*` consumes ` `, `(?:[(]|\{(?!\{))` matches `(`. Inner-word fires.
+- Whole match rejected. Backtrack to `status` fails (next is `.`).
+- Final: `@status.` passes through unchanged.
+
+### Fix sketch (cleaner option)
+
+Make the identifier class NOT include the trailing dot, and rely on dotted-access via a structured pattern:
+
+```python
+_SIGIL_PATTERN = re.compile(
+ r"(?:(?<!\w)(@\??)|(\$))(?![0-9])([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*)(?![a-zA-Z0-9_.])"
+ r"(?!\s*(?:[({\"']|[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))))"
+)
+```
+
+Identifier change: `[a-zA-Z0-9_.]+` → `[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*` (segments separated by single dots, no trailing dot allowed in the capture).
+
+After this change:
+
+- `@invoice_text.` — identifier captures `invoice_text` (no dot). The `.` is now text after the match, emitted literally by the surrounding template engine. Output: `{{ invoice_text|tag("invoice_text") }}.` — same as today.
+- `@user.profile.bio` — identifier captures `user.profile.bio` via `(?:\.[a-zA-Z0-9_]+)*`. Same as today.
+- `@status. Amount (USD)` — identifier captures `status`. The lookahead sees `. Amount (USD)`:
+ - Direct arm: `\s*` zero, then `[({\"']` — `.` not in set, fails.
+ - Inner-word arm: `\s*` zero, then `[a-zA-Z]` — `.` not in class, fails.
+ - Lookahead doesn't fire. `@status` IS rewritten. ✓ fixed.
+
+### Bonus: dispatcher simplification
+
+If the identifier never has a trailing dot, the `trailing_dot` strip in `_replace_sigil` (`pipelex/cogt/templating/template_preprocessor.py:74-79`) becomes dead code. Delete it:
+
+```python
+def _replace_sigil(match: Match[str]) -> str:
+ sigil = _Sigil(match.group(1) or match.group(2))
+ variable: str = match.group(3)
+ match sigil:
+ case _Sigil.AT_OPTIONAL:
+ return f'{{% if {variable} %}}{{{{ {variable}|tag("{variable}") }}}}{{% endif %}}'
+ case _Sigil.AT:
+ return f'{{{{ {variable}|tag("{variable}") }}}}'
+ case _Sigil.DOLLAR:
+ return f"{{{{ {variable}|format() }}}}"
+```
+
+### Tests to add
+
+Drop or rewrite the existing trailing-dot tests — their assertions still hold after the fix (the dot is emitted via the surrounding text instead of the dispatcher), but make sure they continue to pass:
+
+- `test_dollar_variable_with_trailing_dot`
+- `test_at_variable_with_trailing_dot`
+- `test_optional_at_variable_with_trailing_dot`
+- `test_multiple_at_variables_with_trailing_dots`
+- `test_nested_with_trailing_dot_in_complex_sentence`
+
+Add the new red-phase tests for the residual:
+
+```python
+def test_at_var_trailing_dot_then_word_paren_rewrites(self):
+ """`@var. Word (extra)` must rewrite @var — sentence-ending sigil followed by a new
+ sentence with a parenthetical is a realistic prose shape.
+ """
+ template = "The transaction was @status. Amount (USD)."
+ result = preprocess_template(template)
+ expected = 'The transaction was {{ status|tag("status") }}. Amount (USD).'
+ assert result == expected
+
+def test_dollar_var_trailing_dot_then_word_paren_rewrites(self):
+ template = "Reply $user. info()"
+ result = preprocess_template(template)
+ expected = "Reply {{ user|format() }}. info()"
+ assert result == expected
+
+def test_optional_at_var_trailing_dot_then_word_paren_rewrites(self):
+ template = "Optional @?notes. See (next page)."
+ result = preprocess_template(template)
+ expected = 'Optional {% if notes %}{{ notes|tag("notes") }}{% endif %}. See (next page).'
+ assert result == expected
+```
+
+### Risks / things to double-check
+
+- **`@..foo` and similar malformed identifiers**: today, `[a-zA-Z0-9_.]+` matches `..foo` (greedy). After the fix, identifier must start with `[a-zA-Z0-9_]`, so `@.foo` fails to match — `@` stays literal. This is a behavior change for malformed input but seems harmless (no test covers it; nobody writes `@.foo`).
+- **`@user.profile.`** (dotted access + trailing dot): today captures `user.profile.` and strips the dot → `{{ user.profile|tag("user.profile") }}.`. After the fix: captures `user.profile`, dot is text → same output. Verify with a parametrized test.
+- **Inner-word arm interaction with the new identifier**: the inner-word arm is independent of the identifier class change. Existing tests for `@keyframes spin {`, `@layer reset {`, `@import url(...)` should be untouched. Re-run the full module.
+
+---
+
+## Suggested TDD plan
+
+Both fixes are independent — land them in separate PRs or sequentially in one branch.
+
+### Phase 1 — Residual 1 (Jinja `{{` in direct arm)
+
+1. Add the three tests above (red).
+2. Apply the regex change `[({\"']` → `[(\"']|\{(?!\{)`.
+3. Re-run targeted tests — all green.
+4. `make agent-check`.
+
+### Phase 2 — Residual 2 (trailing dot + word + paren)
+
+1. Add the three new red-phase tests.
+2. Apply identifier change `[a-zA-Z0-9_.]+` → `[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*`.
+3. Delete the `trailing_dot` block from `_replace_sigil`.
+4. Re-run all 80+ existing tests — every trailing-dot test should still pass because the dot survives as literal text.
+5. `make agent-check`.
+
+### Phase 3 — Workspace sanity check
+
+Same as the original fix's Phase 4: grep `.mthds` files in `/Users/lchoquel/repos/Pipelex/` for shapes that would behave differently under the new rules. Specifically:
+
+```bash
+# Mixed-Jinja templates that may now interpolate where they didn't:
+grep -rn '@[a-zA-Z_][a-zA-Z_0-9.]*[[:space:]]*{{' --include="*.mthds" . | head -50
+grep -rn '\$[a-zA-Z_][a-zA-Z_0-9.]*[[:space:]]*{{' --include="*.mthds" . | head -50
+
+# Sentence-ending sigils followed by parentheticals:
+grep -rn '@[a-zA-Z_][a-zA-Z_0-9.]*\.[[:space:]][A-Z][a-zA-Z]*[[:space:]]*[(]' --include="*.mthds" . | head -50
+```
+
+Decide per hit: accept (intended fix), document, or revert.
+
+### Phase 4 — CHANGELOG + docs
+
+Single `Fixed` entry under `[Unreleased]`. Cross-link to this doc. No new public API; no need to update `mthds-language-tutorial.md` or `pipe_compose_spec.py` (the escape mechanism is unchanged).
+
+---
+
+## Out of scope
+
+- No new escape mechanism beyond `@@` / `$$`.
+- No reserved-keyword list.
+- No HTML/CSS-aware parsing.
+- No changes to the call sites of `preprocess_template` — all benefit transparently.