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 PR #759 review issues and add spec vs blueprint guidance

Louis Choquel8f2f5189e8fa
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e07cfa61a..571b40434 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
### Changed
-- Reporganize documentation site architecture and navigation.
+- Reorganize documentation site architecture and navigation.
- Add SEO meta descriptions to all doc pages.
- Redesign README: lead with value, collapse details.
diff --git a/CLAUDE.md b/CLAUDE.md
index 77d30461a..d96e829a3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -259,6 +259,13 @@ This document outlines the core coding standards, best practices, and quality co
## Standards related to developing the Pipelex codebase
+### Spec vs Blueprint Architecture
+
+- **Blueprints** (`pipelex/pipe_operators/`, `pipelex/pipe_controllers/`, `pipelex/core/`) are the MTHDS language reference — what `.mthds` files parse into.
+- **Specs** (`pipelex/builder/pipe/`) are a convenience authoring format for AI agents. Each spec has `to_blueprint()` that transforms it into the corresponding blueprint. Spec-level fields may differ from blueprint-level fields.
+
+When adding validation or fields, decide which layer they belong to. Language rules go on blueprints; authoring convenience goes on specs. See `pipelex/builder/CLAUDE.md` for details.
+
### Main config
- The main config model is defined using `ConfigModel` classes, derived from `pydantic BaseModel`
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index b6d05112b..cff5522a7 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -70,3 +70,12 @@ To widen the sidebar you must override **two** things:
- Do NOT treat `docs/robots.txt` as the production robots policy — the authoritative one is `ROOT_ROBOTS_TXT` in the Makefile
- When changing URL paths, update BOTH `mkdocs.yml` `redirect_maps` AND `docs/404.html` JS rewrite rules
- Always add `mkdocs-redirects` to CI pip install when `redirect_maps` exist
+
+## Spec vs Blueprint in Documentation
+
+The `docs/building-methods/` section documents the MTHDS language — what users write in `.mthds` files. This corresponds to the **blueprint** layer, NOT the spec layer.
+
+- **Blueprints** define the MTHDS language — what `.mthds` files parse into via `PipelexInterpreter`.
+- **Specs** (in `pipelex/builder/pipe/`) are a simplified authoring format for AI agents with convenience fields that get transformed into blueprint fields via `to_blueprint()`. Specs are NOT the language definition.
+
+Documentation under `docs/building-methods/` must describe blueprint-level fields, not spec-level convenience fields. For example, `PipeComposeSpec.target_format` is a spec convenience — the MTHDS language uses `category` + `templating_style` on the `TemplateBlueprint` instead.
diff --git a/docs/building-methods/pipes/pipe-operators/PipeCompose.md b/docs/building-methods/pipes/pipe-operators/PipeCompose.md
index 65b84de83..61f485f39 100644
--- a/docs/building-methods/pipes/pipe-operators/PipeCompose.md
+++ b/docs/building-methods/pipes/pipe-operators/PipeCompose.md
@@ -17,10 +17,10 @@ Template mode uses [Jinja2 templates](https://jinja.palletsprojects.com/) to dyn
`PipeCompose` takes all the data currently in the `WorkingMemory` and uses it as the context for rendering a Jinja2 template. The resulting text is then saved back to the working memory as a new `Text` or `Html` output.
-<!-- target_format is a pipelex convenience field (PipeComposeSpec in pipe_compose_spec.py),
- transformed to TemplateBlueprint at build time. The MTHDS standard uses category +
- templating_style.text_format, but pipelex exposes target_format as a simpler authoring form. -->
-The public authoring form uses a top-level `template` field plus a required `target_format`.
+Template mode supports two syntax variants:
+
+- **Simple**: `template = "Hello $name"` — an inline string, defaults to `basic` category
+- **Rich**: A `[pipe.name.template]` section with `template`, `category`, and optionally `templating_style`
### Template Context
@@ -28,16 +28,21 @@ The Jinja2 template has access to all the "stuffs" currently in the working memo
### Template Mode Configuration
-| Parameter | Type | Description | Required |
-| --------------- | --------------- | --------------------------------------------------------------------------- | -------- |
-| `type` | string | The type of the pipe: `PipeCompose` | Yes |
-| `description` | string | A description of the operation | Yes |
-| `inputs` | table | Input variables needed for the template | Yes |
-| `output` | string | The concept for the output | No |
-| `template` | string | An inline Jinja2 template string | Yes* |
-| `target_format` | string | Output rendering target, such as `plain`, `markdown`, `html`, `json`, or `mermaid` | Yes* |
+| Parameter | Type | Description | Required |
+| --------------- | ----------------- | --------------------------------------------------------------------------- | -------- |
+| `type` | string | The type of the pipe: `PipeCompose` | Yes |
+| `description` | string | A description of the operation | Yes |
+| `inputs` | table | Input variables needed for the template | Yes |
+| `output` | string | The concept for the output | No |
+| `template` | string or section | An inline template string, or a `[pipe.name.template]` section (see below) | Yes* |
+
+*Template mode requires `template`. When using the rich form (`[pipe.name.template]` section), the following sub-fields are available:
-*Template mode requires both `template` and `target_format`.
+| Sub-field | Type | Description | Required |
+|--------------------|--------|----------------------------------------------------------------------------------|----------|
+| `template` | string | The Jinja2 template string | Yes |
+| `category` | string | Template category: `basic`, `markdown`, `html`, `mermaid` | Yes |
+| `templating_style` | table | Style options: `{ tag_style = "...", text_format = "..." }` | No |
### Template Mode Examples
@@ -49,11 +54,32 @@ type = "PipeCompose"
description = "Compose a greeting message"
inputs = { user = "User" }
output = "Text"
-target_format = "plain"
template = "Hello $user.name, welcome to our platform!"
```
-**HTML template:**
+**Markdown template with category:**
+
+```toml
+[pipe.compose_report]
+type = "PipeCompose"
+description = "Format data as a markdown report"
+inputs = { summary = "Text", items = "Item[]" }
+output = "Text"
+
+[pipe.compose_report.template]
+category = "markdown"
+template = """
+# Report
+
+$summary
+
+{% for item in items %}
+- {{ item.name }}: {{ item.value }}
+{% endfor %}
+"""
+```
+
+**HTML template with templating style:**
```toml
[pipe.format_html_report]
@@ -61,7 +87,10 @@ type = "PipeCompose"
description = "Format data as HTML"
inputs = { summary = "Text", items = "Item[]" }
output = "Html"
-target_format = "html"
+
+[pipe.format_html_report.template]
+category = "html"
+templating_style = { tag_style = "xml", text_format = "html" }
template = """
<h1>Report</h1>
<p>{{ summary }}</p>
diff --git a/docs/cookbook/advisory-board.md b/docs/cookbook/advisory-board.md
index 6f51c09fb..f6828e563 100644
--- a/docs/cookbook/advisory-board.md
+++ b/docs/cookbook/advisory-board.md
@@ -34,8 +34,7 @@ output = "presentation.MarkdownReport"
steps = [
{ pipe = "classify_business_problem", result = "business_problem" },
{ pipe = "select_advisory_boards", result = "selected_advisory_boards" },
- { pipe = "consult_board", batch_over = "selected_advisory_boards",
- batch_as = "advisory_board", result = "board_consultations" },
+ { pipe = "consult_board", batch_over = "selected_advisory_boards", batch_as = "advisory_board", result = "board_consultations" },
{ pipe = "analyze_board_responses", result = "response_analysis" },
{ pipe = "generate_strategic_report", result = "strategic_report" },
{ pipe = "present_as_markdown", result = "strategic_report_markdown" },
diff --git a/pipelex/builder/CLAUDE.md b/pipelex/builder/CLAUDE.md
index 315230f35..65a463978 100644
--- a/pipelex/builder/CLAUDE.md
+++ b/pipelex/builder/CLAUDE.md
@@ -60,6 +60,17 @@ All specs are Pydantic models (`StructuredContent` base). Two categories of pipe
Each spec has `to_blueprint()` which converts it to the core framework's blueprint type. This separation keeps user-facing specs independent from internal execution types.
+## Critical: PipeSpecs and ConceptSpecs Are NOT the MTHDS Language
+
+PipeSpec and ConceptSpec subclasses in this directory are a **convenience authoring format** for AI agents and builders. They are NOT the ground truth of the MTHDS standard.
+
+The ground truth is the **blueprint** layer:
+
+- **Blueprints** (`pipelex/pipe_operators/`, `pipelex/pipe_controllers/`, `pipelex/core/`) define the actual MTHDS language. They are what `.mthds` files parse into via `PipelexInterpreter.make_pipelex_bundle_blueprint()`.
+- **Specs** are transformed into blueprints via `to_blueprint()` and then discarded. Spec-level fields (e.g., `PipeComposeSpec.target_format`) may not exist on the corresponding blueprint (e.g., `PipeComposeBlueprint` uses `TemplateBlueprint` with `category` + `templating_style` instead).
+
+When reviewing or modifying code: do not assume that a validation rule on a PipeSpec subclass reflects a rule of the MTHDS language. Check the corresponding blueprint class.
+
`PipeSpecUnion` is a `Field(discriminator="type")` union of all pipe spec types.
## Multiplicity Notation