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.
Complete PipeCompose docs after code audit
Louis Choquel9a3b8d5303ce
diff --git a/docs/building-methods/pipes/csv-input-and-output.md b/docs/building-methods/pipes/csv-input-and-output.mdindex f76dc0ac0..af2b07758 100644--- a/docs/building-methods/pipes/csv-input-and-output.md+++ b/docs/building-methods/pipes/csv-input-and-output.md@@ -124,6 +124,34 @@ output = "PersonSummary[]"branch_pipe_code = "summarize_person"input_list_name = "people"input_item_name = "person"++[pipe.summarize_person]+type = "PipeSequence"+description = "Summarize one person"+inputs = { person = "Person" }+output = "PersonSummary"+steps = [+ { pipe = "write_persona", result = "persona" },+ { pipe = "assemble_summary", result = "summary_row" },+]++[pipe.write_persona]+type = "PipeLLM"+description = "Write a one-sentence persona for the person"+inputs = { person = "Person" }+output = "Text"+prompt = "Write a one-sentence persona summary for $person."++[pipe.assemble_summary]+type = "PipeCompose"+description = "Assemble the summary row from selected input fields plus the persona sentence"+inputs = { person = "Person", persona = "Text" }+output = "PersonSummary"++[pipe.assemble_summary.construct]+name = { from = "person.name" }+country = { from = "person.country" }+summary = { from = "persona" }``````bashdiff --git a/docs/building-methods/pipes/pipe-operators/PipeCompose.md b/docs/building-methods/pipes/pipe-operators/PipeCompose.mdindex a26803c06..d00d2f48b 100644--- a/docs/building-methods/pipes/pipe-operators/PipeCompose.md+++ b/docs/building-methods/pipes/pipe-operators/PipeCompose.md@@ -9,13 +9,15 @@ The `PipeCompose` operator composes data from your pipeline's working memory int1. **Template mode**: Render templates to produce `Text`-like output2. **Construct mode**: Build structured objects by mapping fields from inputs+In both modes, `PipeCompose` produces a single output stuff: the `output` concept cannot carry multiplicity (`output = "Report[]"` is rejected at validation).+## Template ModeTemplate mode uses [Jinja2 templates](https://jinja.palletsprojects.com/) to dynamically generate text by combining data from working memory. This is ideal for creating formatted reports, HTML content, or constructing complex, multi-part prompts for LLMs.### How Template Mode Works-`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.+`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. In template mode, the `output` concept must refine the native `Text` or `Html` concept — use construct mode for structured outputs.Template mode supports two syntax variants:@@ -135,7 +137,24 @@ Each field in the `[pipe.name.construct]` section can use one of these methods:|--------|--------|-------------|| Reference | `{ from = "input.field" }` | Copy value from input variable or nested field || Template | `{ template = "text with $var" }` | Generate string using template interpolation |-| Fixed | `"value"` or `123` or `true` | Use a static value directly |+| Fixed | `"value"`, `123`, `true`, or `["a", "b"]` | Use a static value directly (scalars and lists) |+| Nested | a table with sub-fields (no `from`/`template` key) | Recursively compose a nested structured object |++A nested construct is written as a table whose keys are the sub-object's own field names — each sub-field uses any of the four methods, recursively:++```toml+[pipe.assemble_invoice.construct]+customer = { name = { from = "order.customer_name" }, tier = "standard" }+```++A `from` reference also accepts one modifier, `list_to_dict_keyed_by`: when the target field is a dict, it converts the referenced list into a dict keyed by the named attribute of each item:++```toml+[pipe.index_products.construct]+products_by_sku = { from = "products", list_to_dict_keyed_by = "sku" }+```++The referenced value must be a list, and every item must carry the key attribute with a string value — otherwise the composer raises an error.### Copying Whole Inputs Into Native Fields@@ -150,10 +169,13 @@ Conversion matrix:| `YesNo` | `type = "boolean"` | the boolean || `Date` | `type = "date"` | the date || `Text[]` | `type = "list"`, `item_type = "text"` | the list of strings |+| `Number[]` | `type = "list"`, `item_type = "number"` | the list of numbers |+| `YesNo[]` | `type = "list"`, `item_type = "boolean"` | the list of booleans |+| `Date[]` | `type = "list"`, `item_type = "date"` | the list of dates |When the target field expects a content object rather than a native value (e.g. a field typed with a concept), the object is kept as-is — the conversion only fires when the field expects the native type.-One fidelity guard: a `Date` stuff that carries a time of day cannot be copied into a bare `date` field — that would silently drop the time and its UTC offset, so the composer raises an error instead. Target a `Date`-typed field to keep the full timestamp.+One fidelity guard: a `Date` stuff that carries a time of day cannot be copied into a bare `date` field — that would silently drop the time and its UTC offset, so the composer raises an error instead. Target a `Date`-typed field to keep the full timestamp. The same guard applies per item when copying a `Date[]` into a list of `date` items.Worked example — assembling a report from whole stuffs produced by earlier steps:diff --git a/docs/building-methods/pipes/pipe-operators/index.md b/docs/building-methods/pipes/pipe-operators/index.mdindex 8763c41d5..c32e6a2ef 100644--- a/docs/building-methods/pipes/pipe-operators/index.md+++ b/docs/building-methods/pipes/pipe-operators/index.md@@ -21,14 +21,14 @@ Here are the primary pipe operators available in Pipelex:- [**`PipeImgGen`**](./PipeImgGen.md): Generates images from a text prompt using models like GPT Image, Flux, or other image generation models.- [**`PipeSearch`**](./PipeSearch.md): Searches the web using a configurable search provider and returns structured results with an answer and source citations.- [**`PipeFunc`**](./PipeFunc.md): An escape hatch that allows you to execute any custom Python function, giving you maximum flexibility.-- [**`PipeCompose`**](./PipeCompose.md): Renders a Jinja2 template using data from the working memory, perfect for creating formatted reports or complex prompts.+- [**`PipeCompose`**](./PipeCompose.md): Composes outputs deterministically from working memory — renders Jinja2 templates for formatted reports or complex prompts, or constructs structured objects by mapping fields from inputs, without an LLM.## OverviewPipelex provides the following pipe operators:- `PipeLLM`: For LLM-based text generation and processing-- `PipeCompose`: For rendering Jinja2 templates from working memory data+- `PipeCompose`: For composing text (Jinja2 templates) or structured objects (construct mode) from working memory data- `PipeExtract`: For optical character recognition and document processing- `PipeFunc`: For executing custom functions- `PipeImgGen`: For AI-powered image generation@@ -47,6 +47,17 @@ Core operator for LLM-based text generation and processing.- System prompt customization- LLM configuration+## PipeCompose++Composes outputs deterministically from working memory, without an LLM.++### Key Features++- Template mode: Jinja2 rendering to Text or Html outputs+- Construct mode: structured objects assembled by field mapping+- Field methods: references, templates, fixed values, nested constructs+- Native wrapper unwrapping when copying whole inputs into native fields+## PipeExtractProcesses images and PDFs using Optical Character Recognition, and fetches and extracts content from web pages.diff --git a/docs/under-the-hood/architecture-overview.md b/docs/under-the-hood/architecture-overview.mdindex 0fbd67167..66fe12205 100644--- a/docs/under-the-hood/architecture-overview.md+++ b/docs/under-the-hood/architecture-overview.md@@ -43,7 +43,7 @@ Operators perform concrete actions:- **PipeExtract** - Extract content from documents (OCR, parsing)- **PipeImgGen** - Generate images- **PipeFunc** - Execute custom Python functions-- **PipeCompose** - Compose content from templates+- **PipeCompose** - Compose content from templates or construct structured objects- **PipeSearch** - Search the web for information### Core Domaindiff --git a/docs/under-the-hood/dry-run-mock-generation.md b/docs/under-the-hood/dry-run-mock-generation.mdindex 4134707b8..23829a997 100644--- a/docs/under-the-hood/dry-run-mock-generation.md+++ b/docs/under-the-hood/dry-run-mock-generation.md@@ -53,7 +53,7 @@ A dry run does not swap in a special content generator: `run_mode=DRY` rides `Co| `pipelex validate` | `BundleValidator.validate_pipes()` | `WorkingMemoryFactory.make_mock_inputs()` || `PipeLLM` output in dry mode | `dry_llm_gen_object()` / `dry_llm_gen_object_list()` (cogt leaf, `dry_mock.py`) | `DryRunFactory` via the schema-reconstructed class || `PipeFunc` output in dry mode | `WorkingMemoryFactory.make_mock_content()` | `DryRunFactory` (with explicit field constraints) |-| `PipeCompose` in dry mode | `StructuredContentComposer.compose()` | Uses resolved values from working memory (no mocks) |+| `PipeCompose` in dry mode | `StructuredContentComposer.compose()` | Uses resolved values from working memory; falls back to a `DryRunFactory` mock of the output class only when a value error hits under mock inputs |---@@ -247,6 +247,8 @@ async def compose(self) -> StuffContent:In dry run mode, the working memory already contains properly formatted mock values (generated by `WorkingMemoryFactory`), so validation typically succeeds.+There is one fallback: when composition fails with a `StructuredContentComposerValueError` (e.g. a dotted path that mock data cannot resolve, such as a field on a description-only concept) *and* the run uses mock inputs, `PipeCompose` builds a `DryRunFactory` mock of the output class instead of failing. Type-incompatibility and validation errors still raise, and with real inputs (e.g. `pipelex validate`) unresolvable paths raise too — those are genuine bugs, not mock artifacts.+---## Behavior Matrix