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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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 pipeEach 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