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.
feat(core): Native YesNo and Date concepts + Smart Inputs (#1028)
Louis Choquelde69c95ed957
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0a470bc11..be38746cd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,28 @@# Changelog+### Added+- **Smart Inputs (signature-driven input shaping):** Inputs are now interpreted top-down against the pipe's declared input signature rather than bottom-up from their shape alone.+ - Bare values (strings, numbers, booleans, dicts, lists) are automatically shaped into the declared concept (e.g., a bare string becomes a `legal.Question`, not a generic `native.Text`).+ - Lists shape element-wise into the declared item concept; single values auto-wrap into lists where required, and empty lists are now legal.+ - Bare URLs/paths for `Image` or `Document` inputs are resolved relative to the inputs file's directory.+ - Declared structured lists (e.g., `Person[]`) accept a direct path to a `.csv` file by signature, without requiring an envelope.+- **Native `YesNo` concept:** Built-in concept (backed by `YesNoContent`) for boolean judgments. Requires a strict boolean, renders as `yes`/`no` in downstream prompts, and can be read via `pipe_output.main_stuff_as_yes_no.yes_no`.+- **Native `Date` concept:** Built-in concept (backed by `DateContent`) for calendar dates. Requires a `datetime.date` and accepts an optional `datetime.time`. Preserves source precision (never forcing the LLM to fabricate a time of day) and retains UTC offsets verbatim.+- **Comprehensive input error handling:** A suite of typed errors for input shaping failures (`WrongScalarKindError`, `ListWhereSingularError`, `MultiplicityCountMismatchError`, `StructureValidationError`, `UnknownInputNameError`) that provide clear hints and render the expected JSON shape.+- **CLI `--explicit` flag:** Added `--explicit` to `pipelex build inputs` and `pipelex-agent inputs` to generate the legacy `{"concept", "content"}` envelope templates.++### Changed+- (Breaking) **Input templates default to "light" shape:** `pipelex build inputs` and `pipelex-agent inputs` now generate light templates by default, outputting the bare values expected by the signature rather than the verbose `{"concept", "content"}` envelopes. TOML templates include the declared concept as a `# concept: ...` comment.+- (Breaking) **Structure-field `type = "date"` behavior:** A `date` field now generates a `datetime.date` (JSON schema `format: date`), preventing LLMs from hallucinating times for calendar dates. A new `type = "datetime"` field handles full timestamps (`format: date-time`), and default-value validation now rejects a `datetime` default on a `date` field.+- (Breaking) **Strict input validation:** Undeclared input names are now a hard error (previously silently ignored), and top-level `null` values are rejected—absence must be expressed by omitting the key.+- (Breaking) **Explicit envelope validation:** The `{"concept", "content"}` escape hatch is now compatibility-checked against the pipe's declared signature; incompatible concepts raise a typed error.+- (Breaking) **TOML date/time handling:** TOML date and datetime literals are natively supported and map directly to the `Date` concept. Only bare time-of-day literals are rejected (via the renamed `InputsTimeOnlyNotSupportedError`), since a time alone has no date to attach to.+- **Documentation overhaul:** Updated `provide-inputs.md`, `executing-pipelines.md`, and `native-concepts.md` for the Smart Inputs paradigm, leading with the bare-value approach and demoting the envelope format to an escape hatch.++### Fixed+- **Silent mistyping of inputs:** Providing a bare string for a refined text concept (e.g., `legal.Question`) no longer silently degrades the type to a generic `native.Text`; the declared concept type is now retained.+- **TOML inline table formatting:** Light templates now use inline tables for structured values, preventing trailing scalars from being swallowed into `[sections]`.+## [v0.38.0] - 2026-07-06### Highlightsdiff --git a/docs/building-methods/concepts/inline-structures.md b/docs/building-methods/concepts/inline-structures.mdindex 5d6c4c2f7..b6e73409e 100644--- a/docs/building-methods/concepts/inline-structures.md+++ b/docs/building-methods/concepts/inline-structures.md@@ -115,14 +115,25 @@ tax_rate = { type = "number", description = "Tax rate as decimal", default_value### date-Date and datetime values. Pipelex handles date parsing automatically.+A calendar date, no time of day. Generates a `datetime.date` field (JSON schema `format: date`). Use it for issue dates, due dates, dates of birth — anything you'd write as `2026-07-07`.```toml[concept.Event.structure]-event_date = { type = "date", description = "Event date and time" }-created_at = { type = "date", description = "Creation timestamp" }+event_date = { type = "date", description = "The date of the event" }```+### datetime++A timestamp — a date *and* a time of day. Generates a `datetime.datetime` field (JSON schema `format: date-time`). Use it only when the time genuinely matters; a plain calendar date should be `date`, so the LLM is never forced to fabricate a time.++```toml+[concept.Event.structure]+created_at = { type = "datetime", description = "Creation timestamp" }+```++!!! note "Field type vs the native `Date` concept"+ A structure field's `date` / `datetime` type is a plain machine type — you pick one up front. If a field should keep *document fidelity* (a time only when the source states one), model it as `type = "concept", concept_ref = "Date"` instead: the native `Date` concept carries a required date plus an optional time.+### listArrays/lists of items. **Must specify `item_type`** to indicate what the list contains.@@ -266,6 +277,7 @@ Given the Invoice example from above, Pipelex generates:```python# generated/finance__invoice.py+from datetime import datefrom pydantic import Fieldfrom pipelex.core.stuffs.structured_content import StructuredContentfrom .finance__customer import Customer@@ -275,7 +287,7 @@ class Invoice(StructuredContent):"""A commercial document issued by a seller to a buyer"""invoice_number: str = Field(description="The unique invoice identifier")- issue_date: datetime = Field(..., description="The date the invoice was issued")+ issue_date: date = Field(..., description="The date the invoice was issued")customer: Customer = Field(..., description="The customer for this invoice")line_items: list[LineItem] = Field(..., description="List of line items")total_amount: float = Field(..., description="The total invoice amount")@@ -287,7 +299,7 @@ You can then import and use these classes with full type safety.**Inline structures are the recommended approach for most use cases.** They support:-- ✅ All basic field types (text, integer, number, boolean, date, list, dict)+- ✅ All basic field types (text, integer, number, boolean, date, datetime, list, dict)- ✅ Nested concepts and complex relationships- ✅ Choice fields (enums)- ✅ Required/optional fields with defaultsdiff --git a/docs/building-methods/concepts/native-concepts.md b/docs/building-methods/concepts/native-concepts.mdindex 87ebb5209..bac1a4df1 100644--- a/docs/building-methods/concepts/native-concepts.md+++ b/docs/building-methods/concepts/native-concepts.md@@ -30,6 +30,8 @@ Here are all the native concepts you can use out of the box:| `Document` | A document (PDF, DOCX, PPTX, web page) | `DocumentContent` || `TextAndImages` | Text with its associated images | `TextAndImagesContent` || `Number` | A number | `NumberContent` |+| `YesNo` | The answer to a yes/no question | `YesNoContent` |+| `Date` | A calendar date, optionally with a time of day | `DateContent` || `Page` | A document page with text, images, and optional page view | `PageContent` || `Dynamic` | A dynamic concept that adapts to context | `DynamicContent` || `JSON` | A JSON object | `JSONContent` |@@ -109,6 +111,55 @@ class NumberContent(StuffContent):**Use for:** Counts, calculations, metrics, scores.+### YesNoContent++Represents the answer to a yes/no question — a single boolean verdict:++```python+class YesNoContent(StuffContent):+ yes_no: bool+```++Renders as `yes` or `no` when injected into a prompt. Especially handy as a `PipeLLM` output for judgments — `output = "YesNo"` makes the model return a typed boolean instead of free text answering "yes"/"no":++```toml+[pipe.judge_is_urgent]+type = "PipeLLM"+description = "Decide whether a message is urgent"+inputs = { message = "Text" }+output = "YesNo"+prompt = "Is the following message urgent? Answer yes or no.\n\n$message"+```++Read the verdict from a Python caller via `pipe_output.main_stuff_as_yes_no.yes_no`.++**Use for:** Yes/no judgments, boolean classifications, presence/absence checks, pass/fail verdicts.++### DateContent++Represents a calendar date, as precise as its source states — a required `date` plus an optional time of day:++```python+class DateContent(StuffContent):+ date: datetime.date+ time: datetime.time | None = None+```++The time is present only when the source states one — the concept never invents a time, so an LLM extracting "delivery by March 15" produces a date with no time, while a ticket's "7 Jul 2026, 15:40" keeps the time (and its UTC offset, when stated). It renders as ISO 8601 truncated to the stated precision (`2026-07-07`, or `2026-07-07T15:40:00+02:00`) when injected into a prompt. As a `PipeLLM` output, `output = "Date"` makes the model return the two-field structure:++```toml+[pipe.extract_departure]+type = "PipeLLM"+description = "Extract the scheduled departure from a ticket"+inputs = { ticket = "Ticket" }+output = "Date"+prompt = "Extract the scheduled departure from this ticket: $ticket"+```++As a pipeline input, a top-level TOML date or datetime literal maps to `Date` directly (`departure = 2026-07-07T15:40:00+02:00`); read it from a Python caller via `pipe_output.main_stuff_as_date`.++**Use for:** Issue dates, due dates, dates of birth, departures, effective/termination dates — any date found on a document. For a date value without any date attached (a bare time of day), degrade to `Text`.+### TextAndImagesContentCombines text with one or more images:diff --git a/docs/building-methods/pipes/csv-input-and-output.md b/docs/building-methods/pipes/csv-input-and-output.mdindex 50b79179a..142bb83b9 100644--- a/docs/building-methods/pipes/csv-input-and-output.md+++ b/docs/building-methods/pipes/csv-input-and-output.md@@ -44,6 +44,17 @@ Reference the file from `inputs.json` with a `url` whose path ends in a tabular}```+!!! tip "When the input is a declared list, just give the path"+ If the pipe declares the input as a structured list (`people = "Person[]"`), you can skip the envelope entirely and provide the tabular path directly — Pipelex reads it against the declared row concept. Both forms below are equivalent, and a relative path resolves against the inputs file's directory (see [Providing Inputs](provide-inputs.md)):++ ```json+ { "people": "people.csv" }+ ```++ ```json+ { "people": { "url": "people.csv" } }+ ```+Given a `people.csv`:```csvdiff --git a/docs/building-methods/pipes/executing-pipelines.md b/docs/building-methods/pipes/executing-pipelines.mdindex 3c4ad4e76..6d9c7db1a 100644--- a/docs/building-methods/pipes/executing-pipelines.md+++ b/docs/building-methods/pipes/executing-pipelines.md@@ -24,7 +24,7 @@ pipelex run bundle path/to/my_bundle.mthds --inputs inputs.json```!!! tip "Preparing Inputs"- You can generate an input template with `pipelex build inputs bundle path/to/my_bundle.mthds`, which creates a `results/inputs.json` file with the required input structure.+ You can generate an input template with `pipelex build inputs bundle path/to/my_bundle.mthds`, which writes an `inputs.json` next to the bundle (in the bundle's own directory) with the required input structure — the light, signature-driven values ready to fill in. See [Build Inputs](../../tools/cli/build/inputs.md).### Using Python@@ -39,11 +39,9 @@ runner = PipelexMTHDSProtocol(bundle_uri="path/to/my_bundle.mthds",)response = await runner.execute(+ # Provide values directly — each is interpreted against the pipe's declared input signature.inputs={- "my_input": {- "concept": "Text",- "content": "Hello world",- },+ "my_input": "Hello world",},)pipe_output = response.pipe_output@@ -117,10 +115,7 @@ runner = PipelexMTHDSProtocol()response = await runner.execute(pipe_code="description_to_tagline",inputs={- "description": {- "concept": "ProductDescription",- "content": "EcoClean Pro is a revolutionary biodegradable cleaning solution that removes 99.9% of germs while being completely safe for children and pets. Made from plant-based ingredients.",- },+ "description": "EcoClean Pro is a revolutionary biodegradable cleaning solution that removes 99.9% of germs while being completely safe for children and pets. Made from plant-based ingredients.",},)pipe_output = response.pipe_output@@ -136,10 +131,7 @@ runner = PipelexMTHDSProtocol(response = await runner.execute(pipe_code="description_to_tagline",inputs={- "description": {- "concept": "ProductDescription",- "content": "...",- },+ "description": "...",},)pipe_output = response.pipe_output@@ -156,10 +148,7 @@ runner = PipelexMTHDSProtocol(response = await runner.execute(pipe_code="description_to_tagline",inputs={- "description": {- "concept": "ProductDescription",- "content": "...",- },+ "description": "...",},)pipe_output = response.pipe_output@@ -203,10 +192,7 @@ runner = PipelexMTHDSProtocol()response = await runner.execute(mthds_contents=[my_pipe_content],inputs={- "description": {- "concept": "ProductDescription",- "content": "EcoClean Pro is a revolutionary biodegradable cleaning solution that removes 99.9% of germs while being completely safe for children and pets. Made from plant-based ingredients.",- },+ "description": "EcoClean Pro is a revolutionary biodegradable cleaning solution that removes 99.9% of germs while being completely safe for children and pets. Made from plant-based ingredients.",},)pipe_output = response.pipe_outputdiff --git a/docs/building-methods/pipes/pipe-output.md b/docs/building-methods/pipes/pipe-output.mdindex 9c196d5c2..c19e4a219 100644--- a/docs/building-methods/pipes/pipe-output.md+++ b/docs/building-methods/pipes/pipe-output.md@@ -156,6 +156,14 @@ number = pipe_output.main_stuff_as_numberThis works only if the main_stuff is (or refines) a `NumberContent` concept.+**`main_stuff_as_yes_no`** - Returns `YesNoContent` object:++```python+verdict = pipe_output.main_stuff_as_yes_no.yes_no # a bool+```++This works only if the main_stuff is (or refines) a `YesNoContent` concept.+**`main_stuff_as_html`** - Returns `HtmlContent` object:```pythondiff --git a/docs/building-methods/pipes/provide-inputs.md b/docs/building-methods/pipes/provide-inputs.mdindex dc8c9e372..f8240ce52 100644--- a/docs/building-methods/pipes/provide-inputs.md+++ b/docs/building-methods/pipes/provide-inputs.md@@ -1,672 +1,229 @@----description: "Prepare and format pipeline inputs for Pipelex using the CLI, Python API, or Client. Generate input templates and pass data to your methods."+description: "Provide inputs to Pipelex pipelines from the CLI, Python API, or Client. Just provide the values — Pipelex interprets them against the pipe's declared input signature."---# Providing Inputs to Pipelines-When running Pipelex pipelines, you need to provide input data that matches what your pipeline expects. This guide explains how to prepare and format inputs, whether you're using the CLI, Python API, or Pipelex Client.+Every pipe declares what it needs: an `inputs` signature mapping each variable name to a concept (and, for lists, a multiplicity). When you run a pipe, **you just provide the values** — Pipelex interprets each one *top-down against that declared signature*, so a bare string becomes the declared concept (a `legal.Question`, not a generic `native.Text`), a bare number satisfies a numeric input, and a plain object validates against a structured concept.-## Preparing Inputs with the CLI+This is the fast path. There is also an explicit `{"concept": ..., "content": ...}` escape hatch for the rare cases where you need to override or disambiguate the concept — it still works, and it is now compatibility-checked against the declaration. Both are covered below.-The Pipelex CLI can generate a template JSON file with all the required inputs for your pipeline:+## See what a pipe expects++Generate a template that mirrors the pipe's signature:```bashpipelex build inputs bundle path/to/my_pipe.mthds```-This creates a `results/inputs.json` file with the structure needed for your pipeline. You can then fill in the values and use it with:+This writes `inputs.json` (add `--format toml` for TOML) with an example value per input, shaped exactly the way the pipe expects them. Fill in the values and run:```bash-pipelex run bundle path/to/my_pipe.mthds --inputs results/inputs.json+pipelex run bundle path/to/my_pipe.mthds --inputs inputs.json```-See more about the options of the CLI [here](../../tools/cli/index.md).--!!! tip "Starting Point for Input Structure"- Use `pipelex build inputs` to quickly understand what inputs your pipeline expects and generate a template to fill in. Add `--format toml` to get a TOML template instead of JSON.--## Input Files: JSON or TOML--When you pass an inputs file to `--inputs` (or drop a default inputs file next to a bundle), Pipelex accepts **both JSON and TOML**, discriminated by the file extension — a `.toml` suffix is parsed as TOML, everything else as JSON. Both formats produce the same input dictionary, so every PipelineInputs shape below applies to either. TOML's multi-line strings make text-heavy inputs much easier to author.+For a pipe declaring `question = "Question"`, `priority = "Priority"`, `invoice = "Invoice"`, and `tags = "Tag[]"`, the template is the **light** shape — the values themselves, not envelopes:-The JSON and TOML examples below are equivalent:--**JSON:**```json{- "instructions": "Focus on payment terms.",+ "question": "text_value",+ "priority": 1,"invoice": {- "concept": "accounting.Invoice",- "content": {- "invoice_number": "INV-001",- "amount": 1250.00- }- }-}-```--**TOML:**-```toml-instructions = "Focus on payment terms."--[invoice]-concept = "accounting.Invoice"--[invoice.content]-invoice_number = "INV-001"-amount = 1250.00-```--!!! warning "TOML datetimes are not supported yet"- A bare TOML datetime/date/time literal (e.g. `date = 2025-10-20`) is rejected with an explicit error — quote it as a string (`date = "2025-10-20"`) in the meantime.--The rest of this guide shows inputs in JSON (and Python) form; translate any of them to TOML with the same structure. See the [run CLI reference](../../tools/cli/run.md#input-file-formats) for the extension rule and auto-detection behavior.--## Understanding PipelineInputs Format--The `inputs` parameter uses **PipelineInputs** format - a smart, flexible way to provide data to your pipelines. Instead of forcing you into a rigid structure, PipelineInputs intelligently interprets your data based on how you provide it.--!!! tip "Working with Lists"- When providing multiple items as input (lists) or expecting multiple outputs, understanding multiplicity is essential. See [Understanding Multiplicity](understanding-multiplicity.md) for a comprehensive guide on how Pipelex handles single items versus collections.--### TL;DR: How Input Formatting Works--**Case 1: Direct Content** - Provide the value directly (simplest)--- 1.1: String → `"my text"`-- 1.2: List of strings → `["text1", "text2"]`-- 1.3: StructuredContent object → `MyClass(arg1="value")`-- 1.4: List of StuffContent objects → `[MyClass(...), MyClass(...)]`-- 1.5: ListContent of StuffContent objects → `ListContent(items=[MyClass(...), MyClass(...)])`--**Case 2: Explicit Format** - Use `{"concept": "...", "content": "..."}` for control--- 2.1: String with concept → `{"concept": "Text", "content": "my text"}`-- 2.2: List of strings with concept → `{"concept": "Text", "content": ["text1", "text2"]}`-- 2.3: StructuredContent object with concept → `{"concept": "Invoice", "content": InvoiceObject}`-- 2.4: List of StructuredContent objects with concept → `{"concept": "Invoice", "content": [...]}`-- 2.5: Dictionary (structured data) → `{"concept": "Invoice", "content": {"field": "value"}}`-- 2.6: List of dictionaries → `{"concept": "Invoice", "content": [{...}, {...}]}`--!!! tip "Pro Tip for Text Inputs"- For text inputs specifically, skip the verbose format. Just provide the string directly: `"text": "Hello"` instead of `"text": {"concept": "Text", "content": "Hello"}`-------## Case 1: Direct Content Format--When you provide content directly (without the `concept` key), Pipelex intelligently infers the type.--### 1.1: Simple String (Text)--The simplest case - just provide a string directly:--**JSON Format:**-```json-{- "my_text": "my text"-}-```--**Python Format:**-```python-inputs = {- "my_text": "my text"-}-```--**Result:** Automatically becomes `TextContent` with concept `native.Text`--### 1.2: List of Strings (Text List)--Provide multiple text items as a list:--**JSON Format:**-```json-{- "my_texts": ["my text1", "my text2", "my text3"]-}-```--**Python Format:**-```python-inputs = {- "my_texts": ["my text1", "my text2", "my text3"]-}-```--**Result:** Becomes a `ListContent` containing multiple `TextContent` items--**Note:** The concept must be compatible with `native.Text` or an error will be raised.--### 1.3: StructuredContent Object--Provide a structured object directly (for Python clients):--```python-from my_project.domain.domain_struct import MyConcept, MySubClass--inputs = {- "invoice_data": MyConcept(- arg1="arg1",- arg2=1,- arg3=MySubClass(arg4="arg4")- )-}-```--**What is StructuredContent?**--- `StructuredContent` is the base class for user-defined data structures in Pipelex-- You create your own classes by inheriting from `StructuredContent`-- These classes are defined in your project's Python files-- Learn more: [Python StructuredContent Classes](../concepts/python-classes.md)--**Concept Resolution:**--- The system searches all available domains for a concept matching the class name-- If multiple concepts with the same name exist in different domains → **Error**: Must specify domain code-- If no concept is found → **Error**--### 1.4: List of StuffContent Objects--Provide multiple content objects in a plain Python list:--```python-inputs = {- "invoice_list": [- MyConcept(arg1="arg1", arg2=1, arg3=MySubClass(arg4="arg4")),- MyConcept(arg1="arg1_2", arg2=2, arg3=MySubClass(arg4="arg4_2"))- ]+ "invoice_number": "invoice_number_value",+ "amount": 0.0+ },+ "tags": ["text_value"]}```-**What it accepts:**--- Lists of `StructuredContent` objects (user-defined classes)-- Lists of native content objects (`TextContent`, `ImageContent`, etc.)--**Requirements:**--- All items must be of the same type-- Concept resolution follows the same rules as 1.3-- Creates a new `ListContent` wrapper internally--### 1.5: ListContent of StuffContent Objects--Provide an existing `ListContent` wrapper object (Python clients):+The TOML template carries the declared concept for each key as a comment, so you can see what you are filling in (JSON has no comments — use `--explicit` there to see concepts):-```python-from pipelex.core.stuffs.list_content import ListContent--inputs = {- "invoice_list": ListContent(items=[- MyConcept(arg1="arg1", arg2=1, arg3=MySubClass(arg4="arg4")),- MyConcept(arg1="arg1_2", arg2=2, arg3=MySubClass(arg4="arg4_2"))- ])-}+```toml+# concept: my_domain.Question+question = "text_value"+# concept: my_domain.Priority+priority = 1+# concept: my_domain.Invoice+invoice = {invoice_number = "invoice_number_value", amount = 0.0}+# concept: my_domain.Tag[]+tags = ["text_value"]```-**Key Difference from Case 1.4:**--- Case 1.4: Plain Python list `[item1, item2]` → **Creates** a new `ListContent` wrapper-- Case 1.5: Already wrapped `ListContent(items=[item1, item2])` → **Uses** the wrapper directly--**Why Case 1.5 is Separate from Case 1.3:**+!!! tip "Prefer the light template"+ The light values are exactly what the runner accepts, so a template you generate and fill in runs as-is. Add `--explicit` to `build inputs` if you want the ceremonial `{concept, content}` envelope form instead (see [the escape hatch](#the-explicit-format-escape-hatch)).-- `StructuredContent` and `ListContent` are **sibling classes** (both inherit from `StuffContent`)-- Case 1.3 handles user-defined structured data classes-- Case 1.5 handles list container wrappers-- They're at the same inheritance level, not parent-child+## Providing values by concept type-**Requirements:**+Match the value to the input's declared concept. The declared concept is applied automatically — you never repeat it in the value.-- All items within the `ListContent` must be `StuffContent` objects-- All items must be of the same type-- The `ListContent` cannot be empty-- Concept is inferred from the first item's class name (not from "ListContent")+| Declared concept refines… | Provide | Example |+| --- | --- | --- |+| `Text` | a string | `"What are the fees?"` |+| `Number` | a number (not a boolean) | `42` or `3.14` |+| `YesNo` | a boolean | `true` / `false` |+| `Date` | an extended ISO 8601 date/datetime string (or a TOML date literal) | `"2026-09-01"` |+| `Image` / `Document` | a URL or file path | `"photo.jpg"`, `"https://…/a.pdf"` |+| a structured concept | an object | `{"name": "Alice", "age": 30}` |------## Case 2: Explicit Format (Concept and Content)--Use the explicit format `{"concept": "...", "content": "..."}` when you need precise control over concept selection or when working with domain-specific concepts.--### 2.1: Explicit String Input--**JSON Format:**```json{- "text": {- "concept": "Text",- "content": "my text"+ "question": "What are the late-payment fees?",+ "priority": 3,+ "is_urgent": true,+ "hearing": "2026-09-01",+ "contract": "contracts/nda.pdf",+ "client": {+ "name": "Acme Corp",+ "country": "France"}}```-**Python Format:**-```python-inputs = {- "text": {- "concept": "Text",- "content": "my text"- }-}-```--**Concept Options:**+Each value is typed as the **declared** concept — `question` becomes a `legal.Question`, not a bare `native.Text` — so downstream steps see the concept the pipe was designed around.-- `"Text"` or `"native.Text"` for native text-- Any custom concept that is strictly compatible with `native.Text`+!!! note "Numbers vs. booleans"+ A boolean is never read as a number, even though `true`/`false` look numeric to some languages. Provide `true`/`false` only for a `YesNo`-refining input; provide `42` for a `Number`-refining one.-### 2.2: Explicit List of Strings+!!! note "Concepts the signature can't shape"+ A handful of concepts carry no single expected value shape — `Dynamic`, `Anything`, and the container/structural natives (`Html`, `JSON`, `Page`, `TextAndImages`, `SearchResult`, `Composite`). For an input declared as one of these, the signature can't guide interpretation, so the value is read by its own shape (a bare string becomes `native.Text`, and so on). Use the explicit format if you need a specific concept there.-**JSON Format:**-```json-{- "documents": {- "concept": "Text",- "content": ["text1", "text2", "text3"]- }-}-```--**Result:** `ListContent` with multiple `TextContent` items+## Lists and multiplicity-### 2.3: Structured Object with Concept+When an input is declared multiple (`Tag[]`, or a fixed count `Tag[3]`), provide a JSON/TOML list — each element is shaped element-wise into the declared item concept:-**JSON Format:**```json{- "invoice_data": {- "concept": "Invoice",- "content": {- "invoice_number": "INV-001",- "amount": 1250.00,- "date": "2025-10-20"- }- }-}-```--**Python Format:**-```python-inputs = {- "invoice_data": {- "concept": "Invoice",- "content": {- "invoice_number": "INV-001",- "amount": 1250.00,- "date": "2025-10-20"- }- }+ "tags": ["billing", "urgent", "enterprise"]}```-**Concept Resolution with Search Domain Codes:**+- A **single** value auto-wraps into a one-item list, so `"tags": "urgent"` is accepted for a `Tag[]` input.+- An **empty** list is legal and produces an empty collection.+- A fixed count `Tag[3]` validates the number of items — too few or too many is a clear error.+- Providing a list where the signature declares a **single** value is a clear error (Pipelex won't silently pick one).-When you specify a concept name without a domain code prefix:+See [Understanding Multiplicity](understanding-multiplicity.md) for the full model of single items versus collections.-- ✅ If the concept exists in only one domain → Automatically found-- ❌ If the concept exists in multiple domains → **Error**: "Multiple concepts found. Please specify domain code as 'domain_code.Concept'"-- ❌ If the concept doesn't exist → **Error**: "Concept not found"+### Tabular data for a structured list-**Using Domain code prefix:**+A declared structured list (e.g. `people = "Person[]"`) also accepts a path to a `.csv`/tabular file — each row becomes one item:```json{- "concept": "accounting.Invoice"+ "people": "team.csv"}```-This explicitly tells Pipelex to use the `Invoice` concept from the `accounting` domain.+The columns map to the concept's fields. See [CSV Input & Output](csv-input-and-output.md).-### 2.4: List of Structured Objects+## Files and relative paths-**JSON Format:**-```json-{- "invoices": {- "concept": "Invoice",- "content": [- {- "invoice_number": "INV-001",- "amount": 1250.00- },- {- "invoice_number": "INV-002",- "amount": 890.00- }- ]- }-}-```--**Result:** `ListContent` with multiple structured content items--### 2.5: Dictionary Content+For `Image`/`Document` inputs, a **relative** path is resolved against the **inputs file's** directory (a leading `~` expands to your home directory; absolute paths, `http(s)://`, and storage URIs are used as-is). So an `inputs.json` sitting next to a `contracts/` folder can say `"contract": "contracts/nda.pdf"` and it resolves correctly regardless of where you launch the command.-Provide structured data as a dictionary:--**JSON Format:**-```json-{- "person": {- "concept": "PersonInfo",- "content": {- "arg1": "something",- "arg2": 1,- "arg3": {- "arg4": "something else"- }- }- }-}-```+Tabular references use the same relative-path resolution, but v1 reads local tabular files only. A `.csv` path must resolve to a local file; download remote or storage-hosted tables before referencing them.-The system will:+Callers that don't load from a file — the Python API and the hosted client — should pass absolute URLs or storage URIs, since there is no inputs-file directory to resolve against.-1. Find the concept structure (with domain code resolution as explained above)-2. Validate the dictionary against the concept's structure-3. Create the appropriate content object+## The explicit format (escape hatch)-### 2.6: List of Dictionaries+The explicit envelope `{"concept": "...", "content": ...}` gives you direct control over which concept a value is interpreted as. It is now **compatibility-checked**: the concept you name must be compatible with the input's declared concept, otherwise the run fails with a clear error.-**JSON Format:**```json{- "people": {- "concept": "PersonInfo",- "content": [- {- "arg1": "something",- "arg2": 1,- "arg3": {"arg4": "something else"}- },- {- "arg1": "something else",- "arg2": 2,- "arg3": {"arg4": "something else else"}- }- ]+ "question": {+ "concept": "legal.Question",+ "content": "What are the fees?"}}```-### Using DictStuff Instances (Python Clients Only)--For Python clients, you can also pass `DictStuff` instances instead of plain dicts:--```python-from pipelex.client import PipelexClient-from pipelex.core.stuffs.stuff import DictStuff--client = PipelexClient(api_token="YOUR_API_KEY")--# Using DictStuff instance with dict content-response = await client.execute(- pipe_code="process_invoice",- inputs={- "invoice": DictStuff(- concept="accounting.Invoice",- content={- "invoice_number": "INV-001",- "amount": 1250.00,- "date": "2025-10-20"- }- )- }-)--# Using DictStuff instance with list of dicts-response = await client.execute(- pipe_code="process_invoices",- inputs={- "invoices": DictStuff(- concept="accounting.Invoice",- content=[- {"invoice_number": "INV-001", "amount": 1250.00},- {"invoice_number": "INV-002", "amount": 890.00}- ]- )- }-)-```-------## Search Domains Explained--When you reference a concept by name (like `"Invoice"` or `"PersonInfo"`), Pipelex needs to find it in your loaded domains.--### Automatic Search--```json-{- "concept": "Invoice"-}-```--**What happens:**--1. Pipelex searches all available domains for a concept named `"Invoice"`-2. If found in **exactly one domain** → ✅ Uses that concept-3. If found in **multiple domains** → ❌ Error: "Ambiguous concept"-4. If **not found** → ❌ Error: "Concept not found"+Reach for it when:-### Explicit Domain Specification+- **You want a more-specific concept than the signature declares.** If an input is declared `native.Text` but you have a `legal.Question`, name it explicitly — a compatible, more-specific concept wins.+- **A concept name is ambiguous.** When you reference a concept by bare name and it exists in multiple domains, prefix the domain: `"accounting.Invoice"` instead of `"Invoice"`.+- **You are passing a Python object** (see below).-To avoid ambiguity, specify the domain code explicitly:+Generate the envelope template with `pipelex build inputs … --explicit`:```json{- "concept": "accounting.Invoice"+ "question": {"concept": "my_domain.Question", "content": {"text": "text_value"}},+ "priority": {"concept": "my_domain.Priority", "content": {"number": 1}},+ "invoice": {"concept": "my_domain.Invoice", "content": {"invoice_number": "invoice_number_value", "amount": 0.0}},+ "tags": {"concept": "my_domain.Tag", "content": [{"text": "text_value"}]}}```-**Format:** `"domain_code.ConceptName"`+### Concept name resolution-This tells Pipelex exactly which concept to use, bypassing the search.+Inside an explicit envelope, the `concept` you write is resolved against your loaded domains:-### Best Practices+- A bare name (`"Invoice"`) found in exactly one domain is used directly.+- A bare name found in **multiple** domains is an error — prefix the domain (`"accounting.Invoice"`).+- A name found in **no** domain is an error.-- Use simple names (`"Invoice"`) when you have unique concept names across domains-- Use domain-prefixed names (`"accounting.Invoice"`) when:- - You have concepts with the same name in different domains- - You want to be explicit about which concept to use- - You're building APIs that need to be unambiguous+Domain-prefixed names (`"domain_code.ConceptName"`) bypass the search and are always unambiguous.------## Common Input Patterns--### Pattern 1: Simple Text Input--```python-inputs = {- "story": "Once upon a time...",-}-```+## Python API and client-### Pattern 2: Native Content Types (PDF, Image)+From Python, the same light values work — and you can additionally pass already-built content objects:```pythonfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.image_content import ImageContentinputs = {- "document": DocumentContent(url="invoice.pdf"),- "photo": ImageContent(url="photo.jpg"),-}-```--### Pattern 3: Custom Concepts with Explicit Format--```python-inputs = {- "gantt_chart_image": {- "concept": "gantt.GanttChartImage",- "content": ImageContent(url="gantt.png"),- }-}-```--### Pattern 4: Structured Data--```python-inputs = {- "character": {- "concept": "story.Character",- "content": {- "name": "Alice",- "age": 30,- "description": "A brave explorer"- }- }-}-```--### Pattern 5: Multiple Inputs with Mixed Formats--```python-from pipelex.core.stuffs.text_content import load_text_from_path--inputs = {- # Simple string- "client_instructions": "Focus on payment terms",-- # String loaded from file- "contract_text": load_text_from_path("contract.txt"),-- # Explicit concept format- "question": {- "concept": "legal.Question",- "content": "What are the fees?",- },-}-```-------## Complete Examples--### Example 1: Using JSON Inputs (CLI)--```json-{- "text": "Analyze this contract for risks.",- "category": {- "concept": "Category",- "content": {- "name": "legal",- "priority": "high"- }- },- "options": ["option1", "option2", "option3"],- "invoice": {- "concept": "accounting.Invoice",- "content": {- "invoice_number": "INV-001",- "amount": 1250.00- }- }-}-```--### Example 2: Using Python Inputs--```python-from pipelex.core.stuffs.image_content import ImageContent--inputs = {- # Direct string (Case 1.1)+ # Light values, shaped against the signature"topic": "A robot learning to love",-- # Native content type (Case 1.3)+ "priority": 3,++ # Native content objects (typed directly)"photo": ImageContent(url="photo.jpg"),-- # Explicit format with custom concept (Case 2.3)+ "contract": DocumentContent(url="nda.pdf"),++ # Explicit envelope with a custom concept"draft_tweet": {"concept": "social.DraftTweet",- "content": "Check out this amazing framework!",+ "content": "Check out this framework!",},-- # List of strings (Case 1.2)- "keywords": ["AI", "automation", "future"],}```----+A list of content objects (`[MyConcept(...), MyConcept(...)]`) or an already-wrapped `ListContent(items=[...])` is accepted for a declared-multiple input; a `DictStuff(concept=..., content=...)` is the object form of the explicit envelope. All are compatibility-checked against the declaration.-## Troubleshooting+!!! note "Bare numbers and booleans from strictly-typed Python"+ A bare number or boolean (`"priority": 3`) is accepted at runtime, but the `PipelineInputs` protocol type does not yet admit bare scalars, so a strict static type-checker may flag it until that type is widened. If your codebase runs a type-checker, type the inputs dict as `dict[str, Any]`, or pass the value through the explicit envelope (`{"concept": "...", "content": 3}`).-### Error: "Concept not found"+## Unknown input names are rejected-If you see an error about a concept not being found, use the explicit format:+If you provide a name the pipe does not declare, the run fails with an error that lists the declared names. This catches typos and stale inputs files early, rather than silently ignoring the extra value.-```python-# ❌ Won't work if MyType is a custom concept-inputs = {"data": my_value}--# ✅ Use explicit format-inputs = {- "data": {- "concept": "domain.MyType",- "content": my_value,- }-}+```text+Input 'invoce' is not declared by this pipe. Declared inputs: 'question', 'priority', 'invoice', 'tags'.```-### Error: "Type mismatch"--Make sure the content type matches what your concept expects:--```python-# ❌ Wrong: passing a string when concept expects structured data-inputs = {- "character": {- "concept": "story.Character",- "content": "Alice", # Should be a Character instance or dict- }-}--# ✅ Correct: pass the right type-inputs = {- "character": {- "concept": "story.Character",- "content": {"name": "Alice", "age": 30, "description": "..."},- }-}-```+## What can go wrong-### Error: "Ambiguous concept"+When a value cannot be shaped against its declared concept, Pipelex raises a typed error that names the input, the declared concept, what you provided, and the **expected shape**. Common cases:-When a concept name exists in multiple domains, specify the domain code:+- **Wrong kind** — a string where a number is declared, a list where a single value is declared, an object where a scalar is declared.+- **Count mismatch** — the wrong number of items for a fixed-count `X[N]` input.+- **Structure validation** — an object missing a required field of a structured concept.+- **Incompatible explicit concept** — an envelope naming a concept that is not compatible with the declaration.+- **Null value** — a top-level `null`; absence is expressed by *omitting* the key, not by providing `null`. (An input declared optional with `?` may simply be left out — see [Understanding Optionality](understanding-optionality.md).)-```python-# ❌ Ambiguous if "Invoice" exists in multiple domains-inputs = {- "invoice": {- "concept": "Invoice",- "content": {...}- }-}+## Input files: JSON or TOML-# ✅ Specify the domain code-inputs = {- "invoice": {- "concept": "accounting.Invoice",- "content": {...}- }-}-```+An inputs file is a dictionary of input names to values, accepted as **both JSON and TOML**, discriminated by file extension (`.toml` → TOML, everything else → JSON). Both produce the same dictionary, so every shape above applies to either. TOML's multi-line strings (`"""…"""`) make text-heavy inputs far easier to author, and a top-level TOML date/datetime literal (`hearing = 2026-09-01`) maps directly to the native [`Date`](../concepts/native-concepts.md) concept.----+See the [run CLI reference](../../tools/cli/run.md#input-file-formats) for the extension rule, auto-detection, and TOML details.## Related Documentation-- [Executing Pipelines](./executing-pipelines.md) - Learn how to run pipelines with these inputs-- [Define Your Concepts](../concepts/define_your_concepts.md) - Understand concepts and their role-- [Understanding Multiplicity](understanding-multiplicity.md) - Working with single items vs. lists-- [Inline Structures](../concepts/inline-structures.md) - Create structured data types with inline syntax-- [Python StructuredContent Classes](../concepts/python-classes.md) - Advanced structured data with Python+- [Executing Pipelines](./executing-pipelines.md) — run pipelines with these inputs+- [Understanding Multiplicity](understanding-multiplicity.md) — single items vs. lists+- [Understanding Optionality](understanding-optionality.md) — optional (`?`) inputs+- [CSV Input & Output](csv-input-and-output.md) — tabular inputs and outputs+- [Native Concepts](../concepts/native-concepts.md) — the built-in concept families+- [Define Your Concepts](../concepts/define_your_concepts.md) — concepts and their role+- [Build Inputs (CLI)](../../tools/cli/build/inputs.md) — generate an inputs templatediff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.mdindex c10832d09..76405856c 100644--- a/docs/errors/authoring-and-language.md+++ b/docs/errors/authoring-and-language.md@@ -21,12 +21,18 @@ own page. Classes are grouped by subsystem.- [`ConceptStringError`](concept-string-error.md) — Concept string- [`ConceptStructureGeneratorError`](concept-structure-generator-error.md) — Concept structure generator- [`ConceptStructureValidationError`](concept-structure-validation-error.md) — Concept structure validation+- [`DateContentError`](date-content-error.md) — Date content- [`DomainCodeError`](domain-code-error.md) — Domain code- [`DomainFactoryError`](domain-factory-error.md) — Domain factory+- [`ExplicitConceptIncompatibleError`](explicit-concept-incompatible-error.md) — Explicit concept incompatible+- [`InputShapingError`](input-shaping-error.md) — Input shaping- [`InputStuffSpecNotFoundError`](input-stuff-spec-not-found-error.md) — Input stuff spec not found- [`InputStuffSpecsError`](input-stuff-specs-error.md) — Input stuff specs- [`InputStuffSpecsFactoryError`](input-stuff-specs-factory-error.md) — Input stuff specs factory+- [`ListWhereSingularError`](list-where-singular-error.md) — List where singular+- [`MultiplicityCountMismatchError`](multiplicity-count-mismatch-error.md) — Multiplicity count mismatch- [`NativeConceptDefinitionError`](native-concept-definition-error.md) — Native concept definition+- [`NullInputError`](null-input-error.md) — Null input- [`OptionalValueAbsentError`](optional-value-absent-error.md) — Optional value absent- [`PipeFactoryError`](pipe-factory-error.md) — Pipe factory- [`PipeInputError`](pipe-input-error.md) — Pipe input@@ -35,6 +41,7 @@ own page. Classes are grouped by subsystem.- [`PipeRunInputsError`](pipe-run-inputs-error.md) — Pipe run inputs- [`PipelexInterpreterError`](pipelex-interpreter-error.md) — Pipelex interpreter- [`StructureClassError`](structure-class-error.md) — Structure class+- [`StructureValidationError`](structure-validation-error.md) — Structure validation- [`StuffArtefactError`](stuff-artefact-error.md) — Stuff artefact- [`StuffArtefactReservedFieldError`](stuff-artefact-reserved-field-error.md) — Stuff artefact reserved field- [`StuffContentFactoryError`](stuff-content-factory-error.md) — Stuff content factory@@ -44,6 +51,7 @@ own page. Classes are grouped by subsystem.- [`StuffFactoryError`](stuff-factory-error.md) — Stuff factory- [`StuffSpecError`](stuff-spec-error.md) — Stuff spec- [`StuffSpecFactoryError`](stuff-spec-factory-error.md) — Stuff spec factory+- [`UnknownInputNameError`](unknown-input-name-error.md) — Unknown input name- [`WorkingMemoryConsistencyError`](working-memory-consistency-error.md) — Working memory consistency- [`WorkingMemoryError`](working-memory-error.md) — Working memory- [`WorkingMemoryFactoryError`](working-memory-factory-error.md) — Working memory factory@@ -51,6 +59,7 @@ own page. Classes are grouped by subsystem.- [`WorkingMemoryStuffNotFoundError`](working-memory-stuff-not-found-error.md) — Working memory stuff not found- [`WorkingMemoryTypeError`](working-memory-type-error.md) — Working memory type- [`WorkingMemoryVariableError`](working-memory-variable-error.md) — Working memory variable+- [`WrongScalarKindError`](wrong-scalar-kind-error.md) — Wrong scalar kind## Pipe operatorsdiff --git a/docs/errors/date-content-error.md b/docs/errors/date-content-error.mdnew file mode 100644index 000000000..2f0abb959--- /dev/null+++ b/docs/errors/date-content-error.md@@ -0,0 +1,21 @@+---+title: "Date content"+description: "Reference for the `DateContentError` Pipelex error class."+---++<!-- pipelex:generated -->++# Date content++Raised when a DateContent operation needs a time of day the value does not carry.++| Field | Value |+|---|---|+| `error_type` | `DateContentError` |+| `title` | Date content |+| `type_uri` | `https://docs.pipelex.com/latest/errors/date-content-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.stuffs.exceptions` |+| Parent class | [`StuffError`](stuff-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/duplicate-secrets-provider-error.md b/docs/errors/duplicate-secrets-provider-error.mdnew file mode 100644index 000000000..ca444a02b--- /dev/null+++ b/docs/errors/duplicate-secrets-provider-error.md@@ -0,0 +1,21 @@+---+title: "Duplicate secrets provider"+description: "Reference for the `DuplicateSecretsProviderError` Pipelex error class."+---++<!-- pipelex:generated -->++# Duplicate secrets provider++Two plugins registered a secrets provider for the same method.++| Field | Value |+|---|---|+| `error_type` | `DuplicateSecretsProviderError` |+| `title` | Duplicate secrets provider |+| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-secrets-provider-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/duplicate-storage-provider-error.md b/docs/errors/duplicate-storage-provider-error.mdnew file mode 100644index 000000000..11cd5a477--- /dev/null+++ b/docs/errors/duplicate-storage-provider-error.md@@ -0,0 +1,21 @@+---+title: "Duplicate storage provider"+description: "Reference for the `DuplicateStorageProviderError` Pipelex error class."+---++<!-- pipelex:generated -->++# Duplicate storage provider++Two plugins registered a storage provider for the same method.++| Field | Value |+|---|---|+| `error_type` | `DuplicateStorageProviderError` |+| `title` | Duplicate storage provider |+| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-storage-provider-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/explicit-concept-incompatible-error.md b/docs/errors/explicit-concept-incompatible-error.mdnew file mode 100644index 000000000..5e59fbe62--- /dev/null+++ b/docs/errors/explicit-concept-incompatible-error.md@@ -0,0 +1,21 @@+---+title: "Explicit concept incompatible"+description: "Reference for the `ExplicitConceptIncompatibleError` Pipelex error class."+---++<!-- pipelex:generated -->++# Explicit concept incompatible++An explicit envelope/object names a concept incompatible with the declared one (D6).++| Field | Value |+|---|---|+| `error_type` | `ExplicitConceptIncompatibleError` |+| `title` | Explicit concept incompatible |+| `type_uri` | `https://docs.pipelex.com/latest/errors/explicit-concept-incompatible-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.memory.exceptions` |+| Parent class | [`InputShapingError`](input-shaping-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/inference-and-providers.md b/docs/errors/inference-and-providers.mdindex fbab6bfc0..cc5adc3ad 100644--- a/docs/errors/inference-and-providers.md+++ b/docs/errors/inference-and-providers.md@@ -90,6 +90,8 @@ own page. Classes are grouped by subsystem.- [`DuplicateInferenceBackendError`](duplicate-inference-backend-error.md) — Duplicate inference backend- [`DuplicateModelListerError`](duplicate-model-lister-error.md) — Duplicate model lister- [`DuplicateOrchestratorError`](duplicate-orchestrator-error.md) — Duplicate orchestrator+- [`DuplicateSecretsProviderError`](duplicate-secrets-provider-error.md) — Duplicate secrets provider+- [`DuplicateStorageProviderError`](duplicate-storage-provider-error.md) — Duplicate storage provider- [`GatewayCredentialsError`](gateway-credentials-error.md) — Gateway credentials- [`GatewayDeckError`](gateway-deck-error.md) — Gateway deck- [`GatewayError`](gateway-error.md) — Gateway@@ -111,6 +113,8 @@ own page. Classes are grouped by subsystem.- [`PortkeyError`](portkey-error.md) — Portkey- [`PortkeyFactoryError`](portkey-factory-error.md) — Portkey factory- [`UnknownBootOrchestratorError`](unknown-boot-orchestrator-error.md) — Unknown boot orchestrator+- [`UnknownSecretsMethodError`](unknown-secrets-method-error.md) — Unknown secrets method+- [`UnknownStorageMethodError`](unknown-storage-method-error.md) — Unknown storage method- [`VertexAIConfigError`](vertex-ai-config-error.md) — VertexAI configuration error- [`VertexAICredentialsError`](vertex-ai-credentials-error.md) — VertexAI credentials errordiff --git a/docs/errors/input-shaping-error.md b/docs/errors/input-shaping-error.mdnew file mode 100644index 000000000..85d89c0f7--- /dev/null+++ b/docs/errors/input-shaping-error.md@@ -0,0 +1,21 @@+---+title: "Input shaping"+description: "Reference for the `InputShapingError` Pipelex error class."+---++<!-- pipelex:generated -->++# Input shaping++Base for signature-driven input-shaping failures (Smart Inputs, D4).++| Field | Value |+|---|---|+| `error_type` | `InputShapingError` |+| `title` | Input shaping |+| `type_uri` | `https://docs.pipelex.com/latest/errors/input-shaping-error/` |+| `error_domain` | `input` |+| Defined in | `pipelex.core.memory.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/inputs-datetime-not-supported-error.md b/docs/errors/inputs-datetime-not-supported-error.mddeleted file mode 100644index 6b51fe450..000000000--- a/docs/errors/inputs-datetime-not-supported-error.md+++ /dev/null@@ -1,22 +0,0 @@-----title: "Inputs datetime not supported"-description: "Reference for the `InputsDatetimeNotSupportedError` Pipelex error class."------<!-- pipelex:generated -->--# Inputs datetime not supported--Raised when a loaded inputs file carries a TOML datetime/date/time value.--| Field | Value |-|---|---|-| `error_type` | `InputsDatetimeNotSupportedError` |-| `title` | Inputs datetime not supported |-| `type_uri` | `https://docs.pipelex.com/latest/errors/inputs-datetime-not-supported-error/` |-| `error_domain` | `input` |-| Defined in | `pipelex.cli.commands.run.exceptions` |-| Parent class | [`PipelexError`](pipelex-error.md) |-| `user_action` | `change_input` — Quote the datetime as a string in the inputs file (e.g. "2026-07-06"); native TOML datetime inputs are not supported yet |--[Back to Error Reference](index.md)diff --git a/docs/errors/inputs-time-only-not-supported-error.md b/docs/errors/inputs-time-only-not-supported-error.mdnew file mode 100644index 000000000..6bb72a31f--- /dev/null+++ b/docs/errors/inputs-time-only-not-supported-error.md@@ -0,0 +1,22 @@+---+title: "Inputs time only not supported"+description: "Reference for the `InputsTimeOnlyNotSupportedError` Pipelex error class."+---++<!-- pipelex:generated -->++# Inputs time only not supported++Raised when a loaded inputs file carries a bare TOML time-of-day value.++| Field | Value |+|---|---|+| `error_type` | `InputsTimeOnlyNotSupportedError` |+| `title` | Inputs time only not supported |+| `type_uri` | `https://docs.pipelex.com/latest/errors/inputs-time-only-not-supported-error/` |+| `error_domain` | `input` |+| Defined in | `pipelex.cli.commands.run.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |+| `user_action` | `change_input` — A time of day alone has no date to attach to. Include the date (e.g. 2026-07-06T12:00:00), or quote the value as a string |++[Back to Error Reference](index.md)diff --git a/docs/errors/list-where-singular-error.md b/docs/errors/list-where-singular-error.mdnew file mode 100644index 000000000..180c53cd0--- /dev/null+++ b/docs/errors/list-where-singular-error.md@@ -0,0 +1,21 @@+---+title: "List where singular"+description: "Reference for the `ListWhereSingularError` Pipelex error class."+---++<!-- pipelex:generated -->++# List where singular++A list was provided where the signature declares a single value (D2).++| Field | Value |+|---|---|+| `error_type` | `ListWhereSingularError` |+| `title` | List where singular |+| `type_uri` | `https://docs.pipelex.com/latest/errors/list-where-singular-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.memory.exceptions` |+| Parent class | [`InputShapingError`](input-shaping-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/multiplicity-count-mismatch-error.md b/docs/errors/multiplicity-count-mismatch-error.mdnew file mode 100644index 000000000..0f26fd7c0--- /dev/null+++ b/docs/errors/multiplicity-count-mismatch-error.md@@ -0,0 +1,21 @@+---+title: "Multiplicity count mismatch"+description: "Reference for the `MultiplicityCountMismatchError` Pipelex error class."+---++<!-- pipelex:generated -->++# Multiplicity count mismatch++A fixed-count list input received the wrong number of items (D2).++| Field | Value |+|---|---|+| `error_type` | `MultiplicityCountMismatchError` |+| `title` | Multiplicity count mismatch |+| `type_uri` | `https://docs.pipelex.com/latest/errors/multiplicity-count-mismatch-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.memory.exceptions` |+| Parent class | [`InputShapingError`](input-shaping-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/null-input-error.md b/docs/errors/null-input-error.mdnew file mode 100644index 000000000..04989ef1d--- /dev/null+++ b/docs/errors/null-input-error.md@@ -0,0 +1,21 @@+---+title: "Null input"+description: "Reference for the `NullInputError` Pipelex error class."+---++<!-- pipelex:generated -->++# Null input++A provided input value is ``null`` at the top level (D9).++| Field | Value |+|---|---|+| `error_type` | `NullInputError` |+| `title` | Null input |+| `type_uri` | `https://docs.pipelex.com/latest/errors/null-input-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.memory.exceptions` |+| Parent class | [`InputShapingError`](input-shaping-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.mdindex d09722b64..87827cdd0 100644--- a/docs/errors/platform-and-tooling.md+++ b/docs/errors/platform-and-tooling.md@@ -88,7 +88,7 @@ own page. Classes are grouped by subsystem.## CLI- [`AmbiguousInputsFilesError`](ambiguous-inputs-files-error.md) — Ambiguous inputs files-- [`InputsDatetimeNotSupportedError`](inputs-datetime-not-supported-error.md) — Inputs datetime not supported+- [`InputsTimeOnlyNotSupportedError`](inputs-time-only-not-supported-error.md) — Inputs time only not supported- [`PipelexCLIError`](pipelex-cli-error.md) — Pipelex CLI- [`ReadinessCheckError`](readiness-check-error.md) — Readiness checkdiff --git a/docs/errors/structure-validation-error.md b/docs/errors/structure-validation-error.mdnew file mode 100644index 000000000..80778cfc3--- /dev/null+++ b/docs/errors/structure-validation-error.md@@ -0,0 +1,21 @@+---+title: "Structure validation"+description: "Reference for the `StructureValidationError` Pipelex error class."+---++<!-- pipelex:generated -->++# Structure validation++A provided value failed to validate against the declared concept's structure (D4/D5).++| Field | Value |+|---|---|+| `error_type` | `StructureValidationError` |+| `title` | Structure validation |+| `type_uri` | `https://docs.pipelex.com/latest/errors/structure-validation-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.memory.exceptions` |+| Parent class | [`InputShapingError`](input-shaping-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/unknown-input-name-error.md b/docs/errors/unknown-input-name-error.mdnew file mode 100644index 000000000..4114e726f--- /dev/null+++ b/docs/errors/unknown-input-name-error.md@@ -0,0 +1,21 @@+---+title: "Unknown input name"+description: "Reference for the `UnknownInputNameError` Pipelex error class."+---++<!-- pipelex:generated -->++# Unknown input name++A provided input name is not declared by the pipe's signature (D8).++| Field | Value |+|---|---|+| `error_type` | `UnknownInputNameError` |+| `title` | Unknown input name |+| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-input-name-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.memory.exceptions` |+| Parent class | [`InputShapingError`](input-shaping-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/unknown-secrets-method-error.md b/docs/errors/unknown-secrets-method-error.mdnew file mode 100644index 000000000..68da6b2df--- /dev/null+++ b/docs/errors/unknown-secrets-method-error.md@@ -0,0 +1,21 @@+---+title: "Unknown secrets method"+description: "Reference for the `UnknownSecretsMethodError` Pipelex error class."+---++<!-- pipelex:generated -->++# Unknown secrets method++A configured secrets method has no registered provider factory.++| Field | Value |+|---|---|+| `error_type` | `UnknownSecretsMethodError` |+| `title` | Unknown secrets method |+| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-secrets-method-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/unknown-storage-method-error.md b/docs/errors/unknown-storage-method-error.mdnew file mode 100644index 000000000..2ca2c0f20--- /dev/null+++ b/docs/errors/unknown-storage-method-error.md@@ -0,0 +1,21 @@+---+title: "Unknown storage method"+description: "Reference for the `UnknownStorageMethodError` Pipelex error class."+---++<!-- pipelex:generated -->++# Unknown storage method++A configured storage method has no registered provider factory.++| Field | Value |+|---|---|+| `error_type` | `UnknownStorageMethodError` |+| `title` | Unknown storage method |+| `type_uri` | `https://docs.pipelex.com/latest/errors/unknown-storage-method-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.plugins.exceptions` |+| Parent class | [`PluginError`](plugin-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/wrong-scalar-kind-error.md b/docs/errors/wrong-scalar-kind-error.mdnew file mode 100644index 000000000..5ce95b3fa--- /dev/null+++ b/docs/errors/wrong-scalar-kind-error.md@@ -0,0 +1,21 @@+---+title: "Wrong scalar kind"+description: "Reference for the `WrongScalarKindError` Pipelex error class."+---++<!-- pipelex:generated -->++# Wrong scalar kind++A provided bare value has the wrong JSON kind for the declared concept (D5).++| Field | Value |+|---|---|+| `error_type` | `WrongScalarKindError` |+| `title` | Wrong scalar kind |+| `type_uri` | `https://docs.pipelex.com/latest/errors/wrong-scalar-kind-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.core.memory.exceptions` |+| Parent class | [`InputShapingError`](input-shaping-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex ff54158b6..f68c41527 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -81,7 +81,7 @@ For `bundle`, additional options are available:### Inputs-Generate an example inputs template for a pipe, bundle, or method.+Generate an example inputs template for a pipe, bundle, or method. By default the template is the **light** signature-driven shape (bare values matching the pipe's declared concepts), which is exactly what `run` accepts; `--explicit` emits the ceremonial `{concept, content}` envelope form instead.```bashpipelex-agent inputs pipe <PIPE_CODE> [OPTIONS]@@ -93,12 +93,16 @@ pipelex-agent inputs method <NAME> [OPTIONS]- `--library-dir`, `-L` - Additional library directory- `--format` - Template serialization: `json` (default) or `toml`+- `--explicit` - Emit the ceremonial `{concept, content}` envelope form instead of the light valuesFor `bundle` and `method`, use `--pipe` to target a specific pipe.!!! note "`inputs --format` is `json|toml`, not `markdown|json`"Unlike `run`/`validate`, the `inputs` command's `--format` selects the **template serialization**, not a presentation style. `json` (the default) emits the structured JSON success envelope; `toml` prints the raw TOML template straight to stdout (a pipe with no inputs prints a TOML comment line, which loads back as an empty dict). This mirrors the raw-TOML output of the `concept` and `pipe` commands. `inputs` has no `--error-format` — its errors stay JSON.+!!! note "`--explicit` and concept hints"+ The light `--format toml` template carries the declared concept for each key as a `# concept: ...` comment; the light `--format json` template (the default) cannot (JSON has no comments), so pass `--explicit` when you want the concept written out inline. The JSON success envelope shape (`success` / `pipe_code` / `inputs`) is unchanged — only the `inputs` payload flips between the light values and the envelope form.+### Flat CommandsThese commands do not have subcommands:diff --git a/docs/tools/cli/build/inputs.md b/docs/tools/cli/build/inputs.mdindex 4443c2640..f78827ded 100644--- a/docs/tools/cli/build/inputs.md+++ b/docs/tools/cli/build/inputs.md@@ -6,6 +6,8 @@ description: "Generate an example inputs template (JSON or TOML) for any pipeGenerate an example inputs template for a pipe, showing the expected input structure based on the pipe's input types. The template is emitted as JSON by default, or as TOML with `--format toml`.+By default the template is the **light** shape — the values themselves, matching the pipe's declared signature (a bare string for a `Text`-refining input, a bare number for a `Number`-refining one, an object for a structured concept). This is exactly what [`pipelex run`](../run.md) accepts, so a template you generate and fill in runs as-is. Pass `--explicit` to emit the ceremonial `{concept, content}` envelope form instead. See [Providing Inputs](../../../building-methods/pipes/provide-inputs.md) for the full model.+## Usage### By pipe code@@ -23,6 +25,7 @@ pipelex build inputs pipe <PIPE_CODE> [OPTIONS]- `--library-dir`, `-L` - Directory to search for pipe definitions. Can be specified multiple times.- `--output`, `-o` - Path to save the generated inputs file (defaults to `results/`, filename `inputs.json` or `inputs.toml` depending on `--format`)- `--format` - Template format: `json` (default) or `toml`+- `--explicit` - Emit the ceremonial `{concept, content}` envelope form instead of the light values### From a bundle@@ -40,6 +43,7 @@ pipelex build inputs bundle <PATH> [OPTIONS]- `--library-dir`, `-L` - Directory to search for pipe definitions. Can be specified multiple times.- `--output`, `-o` - Path to save the generated inputs file (defaults to the bundle's directory, filename `inputs.json` or `inputs.toml` depending on `--format`)- `--format` - Template format: `json` (default) or `toml`+- `--explicit` - Emit the ceremonial `{concept, content}` envelope form instead of the light values### From an installed method@@ -57,6 +61,7 @@ pipelex build inputs method <NAME> [OPTIONS]- `--library-dir`, `-L` - Directory to search for pipe definitions. Can be specified multiple times.- `--output`, `-o` - Path to save the generated inputs file (filename `inputs.json` or `inputs.toml` depending on `--format`)- `--format` - Template format: `json` (default) or `toml`+- `--explicit` - Emit the ceremonial `{concept, content}` envelope form instead of the light values## Examples@@ -104,72 +109,94 @@ pipelex build inputs bundle my_bundle.mthds --format tomlWhen `--format toml` is selected and no explicit `--output` is given, the default filename becomes `inputs.toml` (instead of `inputs.json`).+**Generate the explicit envelope form instead of the light values:**++```bash+pipelex build inputs bundle my_bundle.mthds --explicit+```+## Output FormatThe generated file contains all inputs required by the pipe, with example values based on each input's concept type. Both formats carry the same structure — [`pipelex run`](../run.md#input-file-formats) accepts either.+### Light form (default)++The default template is the light shape: each value is what the pipe's signature expects, with no `{concept, content}` envelope. For a pipe declaring a `Text`-refining `question`, a `Number`-refining `priority`, a structured `invoice`, and a `Text`-refining list `tags = "Tag[]"`:+**JSON (`--format json`, default):**```json{- "text_input": {- "concept": "native.Text",- "content": {- "text": "text_value"- }+ "question": "text_value",+ "priority": 1,+ "invoice": {+ "invoice_number": "invoice_number_value",+ "amount": 0.0},- "document_input": {- "concept": "native.Document",- "content": {- "url": "url_value"- }- }+ "tags": ["text_value"]}```-**TOML (`--format toml`):**+**TOML (`--format toml`):** the light TOML template uses inline tables so top-level scalars and structured values coexist, and carries the declared concept for each key as a comment (a declared-multiple input is tagged `[]`):```toml-[text_input]-concept = "native.Text"--[text_input.content]-text = "text_value"--[document_input]-concept = "native.Document"--[document_input.content]-url = "url_value"+# concept: my_domain.Question+question = "text_value"+# concept: my_domain.Priority+priority = 1+# concept: my_domain.Invoice+invoice = {invoice_number = "invoice_number_value", amount = 0.0}+# concept: my_domain.Tag[]+tags = ["text_value"]```-### Multiplicity Support+### Explicit envelope form (`--explicit`)-When an input has multiplicity (accepts multiple items), the content is wrapped in a list:+Pass `--explicit` to reproduce the ceremonial `{concept, content}` envelope for every input — useful when you want the concept written out inline (JSON has no comments), or when authoring an input meant for the explicit escape hatch:```json{- "documents": {- "concept": "native.Document",- "content": [- {- "url": "url_value"- }- ]+ "question": {+ "concept": "my_domain.Question",+ "content": {"text": "text_value"}+ },+ "priority": {+ "concept": "my_domain.Priority",+ "content": {"number": 1}+ },+ "invoice": {+ "concept": "my_domain.Invoice",+ "content": {"invoice_number": "invoice_number_value", "amount": 0.0}+ },+ "tags": {+ "concept": "my_domain.Tag",+ "content": [{"text": "text_value"}]}}```-In TOML, the same list of items uses the array-of-tables syntax:+In TOML, `--explicit` renders the all-tables layout; a multiple input keeps a single `[key]` envelope whose `content` is an array-of-tables (`[[key.content]]`):```toml-[documents]-concept = "native.Document"+[question]+concept = "my_domain.Question"++[question.content]+text = "text_value"-[[documents.content]]-url = "url_value"+# ... priority and invoice tables omitted ...++[tags]+concept = "my_domain.Tag"++[[tags.content]]+text = "text_value"```+### Multiplicity++When an input is declared multiple (`Tag[]`), the light form wraps the example value in a list (`["text_value"]`); the explicit form keeps a single `{concept, content}` envelope whose `content` is the list (not an array of separate envelopes). Either way, [`pipelex run`](../run.md) accepts the filled-in template.+## Use Cases- **Understanding pipe requirements** - Quickly see what inputs a pipe expectsdiff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.mdindex 802829c2d..edab93618 100644--- a/docs/tools/cli/run.md+++ b/docs/tools/cli/run.md@@ -156,7 +156,7 @@ pipelex run method invoice_extractor --inputs invoice_data.json## Input File Formats-An inputs file is a dictionary whose keys are input variable names. Pipelex accepts **both JSON and TOML**, discriminated by the file extension:+An inputs file is a dictionary whose keys are input variable names, and each value is interpreted **against the pipe's declared signature** — so you provide the values directly (a string, a number, an object) and Pipelex types them as the declared concept. See [Providing Inputs](../../building-methods/pipes/provide-inputs.md) for the full model, including the explicit `{concept, content}` escape hatch. Pipelex accepts **both JSON and TOML**, discriminated by the file extension:- A `.toml` suffix is parsed as TOML.- Every other value — `.json`, no extension, anything else — is parsed as JSON.@@ -169,37 +169,37 @@ Both formats produce the same input dictionary for the value types they share, s### JSON+Provide each value directly — a string, a number, an object — and it is typed as the input's declared concept:+```json{- "input_variable": "simple string value",- "another_input": {- "concept": "domain_code.ConceptName",- "content": { "field": "value" }- }+ "instructions": "simple string value",+ "priority": 3,+ "client": { "name": "Acme Corp", "country": "France" }}```+To override or disambiguate a concept, wrap a value in the explicit `{concept, content}` envelope (`{"concept": "domain_code.ConceptName", "content": {...}}`) — see [Providing Inputs](../../building-methods/pipes/provide-inputs.md#the-explicit-format-escape-hatch).+### TOMLThe same inputs in TOML. TOML's multi-line strings (`"""..."""`) make text-heavy inputs far more pleasant to author than escaped JSON:```toml-input_variable = "simple string value"-instructions = """Focus on payment terms.Flag anything that looks unusual."""-[another_input]-concept = "domain_code.ConceptName"+priority = 3-[another_input.content]-field = "value"+[client]+name = "Acme Corp"+country = "France"```-!!! warning "TOML datetimes are not supported yet"- TOML parses bare datetime/date/time literals (e.g. `when = 2026-07-06`) into typed objects that have no JSON equivalent and no native concept yet, so the loader rejects them with an explicit error. Quote such values as strings (`when = "2026-07-06"`) in the meantime.+!!! tip "TOML date and datetime literals are native `Date` inputs"+ A top-level TOML date or datetime literal (e.g. `hearing = 2026-09-01` or `departure = 2026-07-07T15:40:00+02:00`) maps directly to the native [`Date`](../../building-methods/concepts/native-concepts.md) concept — the offset is kept when stated. A bare *time-of-day* literal (`opening = 09:00:00`) is still rejected: a time alone has no date to attach to, so include the date or quote it as a string.### Auto-detection and ambiguitydiff --git a/pipelex/builder/concept/concept_spec.py b/pipelex/builder/concept/concept_spec.pyindex e617fd365..8fa0fb1bd 100644--- a/pipelex/builder/concept/concept_spec.py+++ b/pipelex/builder/concept/concept_spec.py@@ -1,4 +1,4 @@-from datetime import datetime+from datetime import date, datetimefrom enum import StrEnumfrom typing import Any, Self, cast@@ -25,6 +25,7 @@ class ConceptStructureSpecFieldType(StrEnum):BOOLEAN = "boolean"NUMBER = "number"DATE = "date"+ DATETIME = "datetime"CONCEPT = "concept"LIST = "list"@@ -38,6 +39,7 @@ class ConceptStructureSpecFieldType(StrEnum):| ConceptStructureSpecFieldType.BOOLEAN| ConceptStructureSpecFieldType.NUMBER| ConceptStructureSpecFieldType.DATE+ | ConceptStructureSpecFieldType.DATETIME| ConceptStructureSpecFieldType.CONCEPT| ConceptStructureSpecFieldType.LIST):@@ -131,6 +133,7 @@ class ConceptStructureSpec(StructuredContent):| ConceptStructureSpecFieldType.BOOLEAN| ConceptStructureSpecFieldType.NUMBER| ConceptStructureSpecFieldType.DATE+ | ConceptStructureSpecFieldType.DATETIME):pass@@ -155,6 +158,7 @@ class ConceptStructureSpec(StructuredContent):case (ConceptStructureSpecFieldType.BOOLEAN| ConceptStructureSpecFieldType.DATE+ | ConceptStructureSpecFieldType.DATETIME| ConceptStructureSpecFieldType.CONCEPT| ConceptStructureSpecFieldType.LIST):@@ -186,8 +190,13 @@ class ConceptStructureSpec(StructuredContent):if not isinstance(self.default_value, (int, float)):self._raise_type_mismatch_error("number (int or float)", actual_type_name=type(self.default_value).__name__)case ConceptStructureSpecFieldType.DATE:- if not isinstance(self.default_value, datetime):+ # A calendar date, not a datetime: datetime is a subclass of date, so reject it explicitly+ # (a datetime default would carry a time the `date` field silently drops).+ if not isinstance(self.default_value, date) or isinstance(self.default_value, datetime):self._raise_type_mismatch_error("date", actual_type_name=type(self.default_value).__name__)+ case ConceptStructureSpecFieldType.DATETIME:+ if not isinstance(self.default_value, datetime):+ self._raise_type_mismatch_error("datetime", actual_type_name=type(self.default_value).__name__)case ConceptStructureSpecFieldType.CONCEPT:# CONCEPT type cannot have default values, this is already validated in validate_structure_blueprintpass@@ -351,6 +360,7 @@ class ConceptSpec(StructuredContent):| ConceptStructureSpecFieldType.BOOLEAN| ConceptStructureSpecFieldType.NUMBER| ConceptStructureSpecFieldType.DATE+ | ConceptStructureSpecFieldType.DATETIME):return field_spec.typediff --git a/pipelex/builder/operations/inputs_ops.py b/pipelex/builder/operations/inputs_ops.pyindex ed729711e..ac009ecc3 100644--- a/pipelex/builder/operations/inputs_ops.py+++ b/pipelex/builder/operations/inputs_ops.py@@ -5,7 +5,7 @@ from __future__ import annotationsimport jsonfrom typing import TYPE_CHECKING, Any-from pipelex.core.pipes.inputs.input_renderer import render_inputs+from pipelex.core.pipes.inputs.input_renderer import build_concept_comments, render_inputsfrom pipelex.core.pipes.pipe_factory import PipeFactoryfrom pipelex.hub import (get_library_manager,@@ -26,6 +26,7 @@ async def build_inputs_for_pipe(mthds_contents: list[str] | None = None,bundle_path: Path | None = None,library_dirs: list[Path] | None = None,+ explicit: bool = False,) -> dict[str, Any]:"""Generate example input JSON for a pipe.@@ -37,6 +38,7 @@ async def build_inputs_for_pipe(mthds_contents: List of raw .mthds contents to parse and load.bundle_path: Path to the bundle file (.mthds).library_dirs: List of library directories to search for pipe definitions.+ explicit: When True, emit the ceremonial envelope form; when False (default), the light shape.Returns:Dictionary with inputs suitable for JSON serialization.@@ -82,11 +84,15 @@ async def build_inputs_for_pipe(raise ValueError(msg)the_pipe = get_required_pipe(pipe_code=pipe_code)- inputs_json_str = render_inputs(the_pipe, indent=2)+ inputs_json_str = render_inputs(the_pipe, indent=2, explicit=explicit)inputs_dict = json.loads(inputs_json_str)+ # concept_comments is internal plumbing for the light-TOML emitter (stripped before the JSON+ # envelope is printed); it lets the agent-CLI TOML surface carry the same `# concept:` hints+ # the human `build inputs --format toml` does.return {"success": True,"pipe_code": pipe_code,"inputs": inputs_dict,+ "concept_comments": build_concept_comments(the_pipe.inputs),}diff --git a/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py b/pipelex/cli/agent_cli/commands/inputs/_inputs_core.pyindex b6d43b202..c81f4ebe7 100644--- a/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py+++ b/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py@@ -2,7 +2,7 @@from __future__ import annotations-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKING, Any, castfrom pipelex.builder.operations.inputs_ops import build_inputs_for_pipefrom pipelex.cli.agent_cli.commands.agent_output import agent_success@@ -17,6 +17,7 @@ async def inputs_core(*,bundle_path: Path | None = None,library_dirs: list[Path] | None = None,+ explicit: bool = False,) -> dict[str, Any]:"""Core logic for generating input JSON for a pipe.@@ -24,6 +25,7 @@ async def inputs_core(pipe_code: The pipe code to generate inputs for.bundle_path: Path to the bundle file (.mthds).library_dirs: List of library directories to search for pipe definitions.+ explicit: When True, emit the ceremonial envelope form; when False (default), the light shape.Returns:Dictionary with inputs suitable for JSON serialization.@@ -36,25 +38,35 @@ async def inputs_core(pipe_code=pipe_code,bundle_path=bundle_path,library_dirs=library_dirs,+ explicit=explicit,)-def emit_inputs_result(result: dict[str, Any], *, template_format: InputsTemplateFormat) -> None:+def emit_inputs_result(result: dict[str, Any], *, template_format: InputsTemplateFormat, explicit: bool = False) -> None:"""Emit an inputs-generation result in the requested template format.JSON keeps the structured success envelope; TOML prints the raw template tostdout, in the same spirit as the ``concept``/``pipe`` raw-TOML passthrough- commands.+ commands. The default light template needs the inline-table layout (``light=True``) so a+ bare scalar declared after a structured value stays valid TOML, and carries the declared+ concept as a ``# concept: ...`` comment per key (same hints the human ``build inputs --format+ toml`` writes); ``--explicit`` restores the all-tables envelope layout.++ ``concept_comments`` is internal plumbing: it is stripped here so the JSON envelope stays the+ plain ``success``/``pipe_code``/``inputs`` shape and is only consumed by the light-TOML path.Args:- result: The inputs-generation result (``success``/``pipe_code``/``inputs``).+ result: The inputs-generation result (``success``/``pipe_code``/``inputs`` + internal+ ``concept_comments``).template_format: The requested inputs template format.+ explicit: Whether ``result["inputs"]`` is the envelope form (True) or the light form (False)."""+ concept_comments = cast("dict[str, str] | None", result.pop("concept_comments", None))match template_format:case InputsTemplateFormat.JSON:agent_success(result)case InputsTemplateFormat.TOML:- toml_content = serialize_inputs_template_to_toml(result["inputs"])+ toml_content = serialize_inputs_template_to_toml(result["inputs"], light=not explicit, concept_comments=concept_comments)print(toml_content, end="" if toml_content.endswith("\n") else "\n")diff --git a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.pyindex dabad130d..1229b0c95 100644--- a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py@@ -38,6 +38,10 @@ def inputs_bundle_cmd(InputsTemplateFormat,typer.Option("--format", help="Inputs template format: 'json' for the JSON result envelope (default), 'toml' for raw TOML on stdout"),] = InputsTemplateFormat.JSON,+ explicit: Annotated[+ bool,+ typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),+ ] = False,) -> None:"""Generate an example inputs template from a bundle file (.mthds) or pipeline directory.@@ -50,6 +54,7 @@ def inputs_bundle_cmd(pipelex-agent inputs bundle pipeline_01/pipelex-agent inputs bundle pipeline_01/ --pipe my_pipepipelex-agent inputs bundle pipeline_01/ --format toml+ pipelex-agent inputs bundle pipeline_01/ --explicit"""bundle_path: str | None = Nonetarget_path = Path(path)@@ -93,8 +98,8 @@ def inputs_bundle_cmd(make_pipelex_for_agent_cli(library_dirs=library_dirs, needs_inference=False, needs_model_specs=True)try:- result = asyncio.run(inputs_core(pipe_code=pipe_code, bundle_path=Path(bundle_path), library_dirs=library_dirs)) # type: ignore[arg-type]- emit_inputs_result(result, template_format=template_format)+ result = asyncio.run(inputs_core(pipe_code=pipe_code, bundle_path=Path(bundle_path), library_dirs=library_dirs, explicit=explicit)) # type: ignore[arg-type]+ emit_inputs_result(result, template_format=template_format, explicit=explicit)except FileNotFoundError as exc:agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)diff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.pyindex 6ac0baffb..8c5f1061f 100644--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py@@ -37,6 +37,10 @@ def inputs_method_cmd(InputsTemplateFormat,typer.Option("--format", help="Inputs template format: 'json' for the JSON result envelope (default), 'toml' for raw TOML on stdout"),] = InputsTemplateFormat.JSON,+ explicit: Annotated[+ bool,+ typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),+ ] = False,) -> None:"""Generate an example inputs template for an installed method.@@ -48,6 +52,7 @@ def inputs_method_cmd(pipelex-agent inputs method my-methodpipelex-agent inputs method my-method --pipe custom_pipepipelex-agent inputs method my-method --format toml+ pipelex-agent inputs method my-method --explicit"""pipe_code, method_library_dirs, method = resolve_method_target(method_name=name,@@ -66,8 +71,8 @@ def inputs_method_cmd(make_pipelex_for_agent_cli(library_dirs=library_dirs_paths, needs_inference=False, needs_model_specs=True)try:- result = asyncio.run(inputs_core(pipe_code=pipe_code, bundle_path=bundle_path, library_dirs=library_dirs_paths))- emit_inputs_result(result, template_format=template_format)+ result = asyncio.run(inputs_core(pipe_code=pipe_code, bundle_path=bundle_path, library_dirs=library_dirs_paths, explicit=explicit))+ emit_inputs_result(result, template_format=template_format, explicit=explicit)except FileNotFoundError as exc:agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)diff --git a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.pyindex fa9e5d9e1..f222e810a 100644--- a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py@@ -34,6 +34,10 @@ def inputs_pipe_cmd(InputsTemplateFormat,typer.Option("--format", help="Inputs template format: 'json' for the JSON result envelope (default), 'toml' for raw TOML on stdout"),] = InputsTemplateFormat.JSON,+ explicit: Annotated[+ bool,+ typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),+ ] = False,) -> None:"""Generate an example inputs template for a pipe by code.@@ -44,6 +48,7 @@ def inputs_pipe_cmd(pipelex-agent inputs pipe my_pipepipelex-agent inputs pipe my_pipe -L ./my_pipespipelex-agent inputs pipe my_pipe --format toml+ pipelex-agent inputs pipe my_pipe --explicit"""# Helpful error if the user passes a path instead of a pipe codetarget_path = Path(pipe_code)@@ -73,8 +78,8 @@ def inputs_pipe_cmd(make_pipelex_for_agent_cli(library_dirs=library_dirs, needs_inference=False, needs_model_specs=True)try:- result = asyncio.run(inputs_core(pipe_code=pipe_code, bundle_path=None, library_dirs=library_dirs))- emit_inputs_result(result, template_format=template_format)+ result = asyncio.run(inputs_core(pipe_code=pipe_code, bundle_path=None, library_dirs=library_dirs, explicit=explicit))+ emit_inputs_result(result, template_format=template_format, explicit=explicit)except FileNotFoundError as exc:agent_error(f"File not found: {exc}", error_type="FileNotFoundError", cause=exc)diff --git a/pipelex/cli/agent_cli/commands/run/_run_core.py b/pipelex/cli/agent_cli/commands/run/_run_core.pyindex 6a9e8ccc7..0e211c802 100644--- a/pipelex/cli/agent_cli/commands/run/_run_core.py+++ b/pipelex/cli/agent_cli/commands/run/_run_core.py@@ -32,6 +32,7 @@ async def run_pipeline_core(graph: bool = False,costs: bool = True,with_memory: bool = False,+ inputs_base_dir: Path | None = None,) -> dict[str, Any]:"""Core logic for running a pipeline and returning JSON-serializable output.@@ -47,6 +48,8 @@ async def run_pipeline_core(costs: Whether to emit usage (cost) tracing events. Default True.with_memory: Whether to include full working memory in output (True) orreturn compact concept JSON only (False, default).+ inputs_base_dir: Directory bare relative file paths in ``inputs`` resolve against (Smart+ Inputs D3) — the inputs file's parent when file-loaded, else ``None``.Returns:Dictionary with execution results suitable for JSON serialization.@@ -67,6 +70,7 @@ async def run_pipeline_core(pipe_run_mode=pipe_run_mode,execution_config=execution_config,library_dirs=library_dirs,+ inputs_base_dir=inputs_base_dir,)response = await runner.execute(pipe_code=pipe_code,diff --git a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py b/pipelex/cli/agent_cli/commands/run/bundle_cmd.pyindex 2a618defd..a8c2685cc 100644--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py@@ -156,7 +156,8 @@ def run_bundle_cmd(agent_error(f"Failed to parse bundle '{bundle_path}': {exc}", error_type=type(exc).__name__, cause=exc)# Load inputs: --inputs flag takes priority, then stdin fallback, then auto-detected- pipeline_inputs: dict[str, Any] | None = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True, auto_inputs_dir=auto_inputs_dir)+ parsed_inputs = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True, auto_inputs_dir=auto_inputs_dir)+ pipeline_inputs: dict[str, Any] | None = parsed_inputs.pipeline_inputsrunner_type: RunnerType = ctx.obj["runner"]@@ -210,6 +211,7 @@ def run_bundle_cmd(graph=graph,costs=costs,with_memory=with_memory,+ inputs_base_dir=parsed_inputs.inputs_base_dir,))agent_success_formatted(diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.pyindex 12f04f0b5..0cdc4b291 100644--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py@@ -116,7 +116,8 @@ def run_method_cmd(effective_inputs = resolve_inputs_arg_against_dir(inputs, base_dir=Path(method_library_dirs[0]))# Load inputs: --inputs flag takes priority, then stdin fallback- pipeline_inputs: dict[str, Any] | None = parse_cli_inputs(inputs_arg=effective_inputs, stdin_fallback=True)+ parsed_inputs = parse_cli_inputs(inputs_arg=effective_inputs, stdin_fallback=True)+ pipeline_inputs: dict[str, Any] | None = parsed_inputs.pipeline_inputsrunner_type: RunnerType = ctx.obj["runner"]@@ -170,6 +171,7 @@ def run_method_cmd(graph=graph,costs=costs,with_memory=with_memory,+ inputs_base_dir=parsed_inputs.inputs_base_dir,))agent_success_formatted(diff --git a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py b/pipelex/cli/agent_cli/commands/run/pipe_cmd.pyindex 99d89b9d4..31ce470e6 100644--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py@@ -110,7 +110,8 @@ def run_pipe_cmd(library_dir = [*export_dirs, *library_dir]# Load inputs: --inputs flag takes priority, then stdin fallback- pipeline_inputs: dict[str, Any] | None = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True)+ parsed_inputs = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True)+ pipeline_inputs: dict[str, Any] | None = parsed_inputs.pipeline_inputsrunner_type: RunnerType = ctx.obj["runner"]@@ -161,6 +162,7 @@ def run_pipe_cmd(graph=graph,costs=costs,with_memory=with_memory,+ inputs_base_dir=parsed_inputs.inputs_base_dir,))agent_success_formatted(diff --git a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py b/pipelex/cli/agent_cli/commands/run/stdin_resolver.pyindex 3254cf892..0b0f7724a 100644--- a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py+++ b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py@@ -5,18 +5,32 @@ from __future__ import annotationsimport jsonimport sysfrom pathlib import Path-from typing import Any, cast+from typing import Any, NamedTuple, castfrom pipelex.cli.agent_cli.commands.agent_output import agent_errorfrom pipelex.cli.commands.run._inputs_file_loader import find_default_inputs_file, load_inputs_dict_from_pathfrom pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_paths-from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, InputsDatetimeNotSupportedError+from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, InputsTimeOnlyNotSupportedErrorfrom pipelex.tools.misc.exceptions import JsonTypeError, TomlErrorWORKING_MEMORY_KEY = "working_memory"MAIN_STUFF_KEY = "main_stuff"+class ParsedCliInputs(NamedTuple):+ """Parsed CLI inputs plus the directory bare relative file paths resolve against (Smart Inputs D3).++ ``inputs_base_dir`` is the inputs file's parent when inputs were file-loaded (``--inputs <file>``+ or an auto-detected default file), else ``None`` — an inline-JSON, stdin, or no-inputs caller+ has no file to anchor relative paths to. It rides to the runner so the shaper can resolve bare+ relative file-ish / CSV strings (whose declared concept the signature-blind CLI cannot see).+ ``pipeline_inputs`` is ``None`` when no inputs were supplied.+ """++ pipeline_inputs: dict[str, Any] | None+ inputs_base_dir: Path | None++def _extract_concept_code(concept_data: Any) -> str:"""Extract a concept code string from a concept data value.@@ -119,7 +133,7 @@ def parse_cli_inputs(*,stdin_fallback: bool = True,auto_inputs_dir: Path | None = None,-) -> dict[str, Any] | None:+) -> ParsedCliInputs:"""Parse pipeline inputs from CLI --inputs argument, stdin, or an auto-detected directory.Resolution order:@@ -129,7 +143,7 @@ def parse_cli_inputs(read JSON from stdin and resolve envelope format if present.3. If ``auto_inputs_dir`` is provided: probe it for a default inputs file(``inputs.json`` / ``inputs.toml``) and parse it (lowest-priority fallback).- 4. Otherwise return None (no inputs).+ 4. Otherwise return an empty result (no inputs).The auto-detect probe — including its ``inputs.json``/``inputs.toml`` ambiguityrule — runs only here, in step 3, so it can never pre-empt higher-priority@@ -144,7 +158,9 @@ def parse_cli_inputs(``inputs_arg`` and stdin are absent.Returns:- Parsed inputs dict, or None if no inputs are available.+ A :class:`ParsedCliInputs` — the parsed inputs dict (``None`` if no inputs are available)+ plus the inputs file's directory (``None`` for inline JSON, stdin, or no inputs), so a+ file-loaded caller can hand it to the runner as ``inputs_base_dir`` for D3 path resolution."""if inputs_arg is not None:return _parse_inputs_arg(inputs_arg)@@ -152,7 +168,8 @@ def parse_cli_inputs(if stdin_fallback and not sys.stdin.isatty():stdin_inputs = _read_stdin_inputs()if stdin_inputs is not None:- return stdin_inputs+ # Piped stdin has no anchoring file — relative paths keep the CWD contract.+ return ParsedCliInputs(pipeline_inputs=stdin_inputs, inputs_base_dir=None)if auto_inputs_dir is not None:try:@@ -162,44 +179,45 @@ def parse_cli_inputs(if auto_inputs_file is not None:return _parse_inputs_arg(str(auto_inputs_file))- return None+ return ParsedCliInputs(pipeline_inputs=None, inputs_base_dir=None)-def _parse_inputs_arg(inputs_arg: str) -> dict[str, Any] | None:+def _parse_inputs_arg(inputs_arg: str) -> ParsedCliInputs:"""Parse the --inputs argument as inline JSON or file path.Args:inputs_arg: The --inputs CLI argument value.Returns:- Parsed inputs dict, or None if empty.+ A :class:`ParsedCliInputs` — inline JSON carries no base dir; a file path carries its+ parent directory so bare relative file-ish / CSV inputs resolve against it (D3)."""if inputs_arg.startswith("{"):try:result: dict[str, Any] = json.loads(inputs_arg)- return resultexcept json.JSONDecodeError as exc:agent_error(f"Failed to parse inline JSON inputs: {exc}", error_type="JSONDecodeError", cause=exc)- else:- try:- # expanduser so a quoted / `=`-form `~/inputs.json` resolves to the home dir, not a- # literal `~` component (unquoted `~` is shell-expanded, but the quoted/`=` forms are not).- inputs_path = Path(inputs_arg).expanduser()- loaded = load_inputs_dict_from_path(inputs_path)- # Resolve relative url paths against the inputs file's parent directory- base_dir = inputs_path.parent.resolve()- return resolve_inputs_paths(loaded, base_dir=base_dir)- except FileNotFoundError as exc:- agent_error(f"Input file not found: {inputs_arg}", error_type="FileNotFoundError", cause=exc)- except json.JSONDecodeError as exc:- agent_error(f"Input file contains invalid JSON: {inputs_arg}: {exc}", error_type="JSONDecodeError", cause=exc)- except JsonTypeError as exc:- agent_error(f"Input file must be a valid JSON dictionary: {inputs_arg}", error_type="JsonTypeError", cause=exc)- except TomlError as exc:- agent_error(exc.message, error_type="TomlError", cause=exc)- except InputsDatetimeNotSupportedError as exc:- agent_error(exc.message, error_type="InputsDatetimeNotSupportedError", cause=exc)- return None+ return ParsedCliInputs(pipeline_inputs=result, inputs_base_dir=None)+ try:+ # expanduser so a quoted / `=`-form `~/inputs.json` resolves to the home dir, not a+ # literal `~` component (unquoted `~` is shell-expanded, but the quoted/`=` forms are not).+ inputs_path = Path(inputs_arg).expanduser()+ loaded = load_inputs_dict_from_path(inputs_path)+ # Resolve relative url paths against the inputs file's parent directory. The same directory+ # rides to the runner as inputs_base_dir so the shaper can resolve bare relative file-ish /+ # CSV strings (whose declared concept the signature-blind CLI cannot see).+ base_dir = inputs_path.parent.resolve()+ return ParsedCliInputs(pipeline_inputs=resolve_inputs_paths(loaded, base_dir=base_dir), inputs_base_dir=base_dir)+ except FileNotFoundError as exc:+ agent_error(f"Input file not found: {inputs_arg}", error_type="FileNotFoundError", cause=exc)+ except json.JSONDecodeError as exc:+ agent_error(f"Input file contains invalid JSON: {inputs_arg}: {exc}", error_type="JSONDecodeError", cause=exc)+ except JsonTypeError as exc:+ agent_error(f"Input file must be a valid JSON dictionary: {inputs_arg}", error_type="JsonTypeError", cause=exc)+ except TomlError as exc:+ agent_error(exc.message, error_type="TomlError", cause=exc)+ except InputsTimeOnlyNotSupportedError as exc:+ agent_error(exc.message, error_type="InputsTimeOnlyNotSupportedError", cause=exc)def _read_stdin_inputs() -> dict[str, Any] | None:diff --git a/pipelex/cli/commands/build/inputs/_inputs_core.py b/pipelex/cli/commands/build/inputs/_inputs_core.pyindex b76f0acce..c92dc7ebc 100644--- a/pipelex/cli/commands/build/inputs/_inputs_core.py+++ b/pipelex/cli/commands/build/inputs/_inputs_core.py@@ -39,6 +39,7 @@ async def _generate_inputs_core(output_path: Path | None = None,library_dir: list[str] | None = None,template_format: InputsTemplateFormat = InputsTemplateFormat.JSON,+ explicit: bool = False,) -> None:"""Core logic for generating an inputs template file for a pipe."""# Set up library so pipes can be found@@ -91,10 +92,10 @@ async def _generate_inputs_core(try:match template_format:case InputsTemplateFormat.JSON:- inputs_template_str = render_inputs(the_pipe, indent=2)+ inputs_template_str = render_inputs(the_pipe, indent=2, explicit=explicit)default_file_name = DEFAULT_INPUTS_FILE_NAMEcase InputsTemplateFormat.TOML:- inputs_template_str = render_inputs_toml(the_pipe)+ inputs_template_str = render_inputs_toml(the_pipe, explicit=explicit)default_file_name = DEFAULT_INPUTS_TOML_FILE_NAMEexcept NoInputsRequiredError as exc:typer.secho(str(exc), fg=typer.colors.YELLOW)@@ -129,6 +130,7 @@ def execute_generate_inputs(output_path: Path | None,library_dir: list[str] | None = None,template_format: InputsTemplateFormat = InputsTemplateFormat.JSON,+ explicit: bool = False,telemetry_command_label: str = f"{COMMAND} {SUB_COMMAND_INPUTS}",) -> None:"""Synchronous entry point wrapping the async inputs generation with Pipelex setup/teardown."""@@ -149,6 +151,7 @@ def execute_generate_inputs(output_path=output_path,library_dir=library_dir,template_format=template_format,+ explicit=explicit,))diff --git a/pipelex/cli/commands/build/inputs/bundle_cmd.py b/pipelex/cli/commands/build/inputs/bundle_cmd.pyindex bbf65e4c3..9ab5ff3ea 100644--- a/pipelex/cli/commands/build/inputs/bundle_cmd.py+++ b/pipelex/cli/commands/build/inputs/bundle_cmd.py@@ -36,6 +36,10 @@ def build_inputs_bundle_cmd(InputsTemplateFormat,typer.Option("--format", help="Format of the generated inputs template (json or toml)"),] = InputsTemplateFormat.JSON,+ explicit: Annotated[+ bool,+ typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),+ ] = False,) -> None:"""Generate an example inputs template from a bundle file or pipeline directory.@@ -45,6 +49,7 @@ def build_inputs_bundle_cmd(pipelex build inputs bundle my_bundle.mthds --pipe my_pipepipelex build inputs bundle pipeline_01/ --output custom_inputs.jsonpipelex build inputs bundle pipeline_01/ --format toml+ pipelex build inputs bundle pipeline_01/ --explicit"""target_path = Path(path)bundle_path: Path@@ -102,4 +107,5 @@ def build_inputs_bundle_cmd(output_path=output_path_path,library_dir=library_dir,template_format=template_format,+ explicit=explicit,)diff --git a/pipelex/cli/commands/build/inputs/method_cmd.py b/pipelex/cli/commands/build/inputs/method_cmd.pyindex bbbf7ab24..5a7d0a53f 100644--- a/pipelex/cli/commands/build/inputs/method_cmd.py+++ b/pipelex/cli/commands/build/inputs/method_cmd.py@@ -36,6 +36,10 @@ def build_inputs_method_cmd(InputsTemplateFormat,typer.Option("--format", help="Format of the generated inputs template (json or toml)"),] = InputsTemplateFormat.JSON,+ explicit: Annotated[+ bool,+ typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),+ ] = False,) -> None:"""Generate an example inputs template for an installed method.@@ -44,6 +48,7 @@ def build_inputs_method_cmd(pipelex build inputs method my-method --pipe custom_pipepipelex build inputs method my-method --output custom_inputs.jsonpipelex build inputs method my-method --format toml+ pipelex build inputs method my-method --explicit"""pipe_code, method_library_dirs, _ = resolve_method_target(method_name=name,@@ -73,4 +78,5 @@ def build_inputs_method_cmd(output_path=output_path_path,library_dir=effective_library_dir,template_format=template_format,+ explicit=explicit,)diff --git a/pipelex/cli/commands/build/inputs/pipe_cmd.py b/pipelex/cli/commands/build/inputs/pipe_cmd.pyindex 593fae70e..4ac82731c 100644--- a/pipelex/cli/commands/build/inputs/pipe_cmd.py+++ b/pipelex/cli/commands/build/inputs/pipe_cmd.py@@ -30,6 +30,10 @@ def build_inputs_pipe_cmd(InputsTemplateFormat,typer.Option("--format", help="Format of the generated inputs template (json or toml)"),] = InputsTemplateFormat.JSON,+ explicit: Annotated[+ bool,+ typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),+ ] = False,) -> None:"""Generate an example inputs template for a pipe by code.@@ -38,6 +42,7 @@ def build_inputs_pipe_cmd(pipelex build inputs pipe my_pipe -L ./my_library/pipelex build inputs pipe my_pipe --output custom_inputs.jsonpipelex build inputs pipe my_pipe --format toml+ pipelex build inputs pipe my_pipe --explicit"""output_path_path = Path(output_path) if output_path else None@@ -47,4 +52,5 @@ def build_inputs_pipe_cmd(output_path=output_path_path,library_dir=library_dir,template_format=template_format,+ explicit=explicit,)diff --git a/pipelex/cli/commands/run/_inputs_file_loader.py b/pipelex/cli/commands/run/_inputs_file_loader.pyindex cbc8fb5c5..b4e4edf5c 100644--- a/pipelex/cli/commands/run/_inputs_file_loader.py+++ b/pipelex/cli/commands/run/_inputs_file_loader.py@@ -15,7 +15,8 @@ from pathlib import Pathfrom typing import Any, castfrom pipelex.builder.conventions import DEFAULT_INPUTS_FILE_NAME, DEFAULT_INPUTS_TOML_FILE_NAME-from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, InputsDatetimeNotSupportedError+from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, InputsTimeOnlyNotSupportedError+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.tools.misc.json_utils import load_json_dict_from_pathfrom pipelex.tools.misc.toml_utils import load_toml_from_path@@ -30,23 +31,25 @@ def load_inputs_dict_from_path(path: Path) -> dict[str, Any]:parser; every other suffix (including none) is parsed as JSON.Returns:- The loaded inputs dictionary.+ The loaded inputs dictionary. Any top-level TOML date/datetime literal is+ converted to a ``DateContent`` (which enters the pipeline-inputs seam as a+ bare content instance); nested date/datetime values are left in place for+ the envelope/structure factory arms to consume.Raises:FileNotFoundError: If the file does not exist.TomlError: If a ``.toml`` file has invalid TOML syntax.json.JSONDecodeError: If a JSON file has invalid JSON syntax.JsonTypeError: If a JSON file does not hold a dictionary.- InputsDatetimeNotSupportedError: If a loaded value is a TOML- datetime/date/time instance (no native concept support yet).+ InputsTimeOnlyNotSupportedError: If a loaded value is a bare TOML+ time-of-day (which has no date to attach to and no native concept)."""inputs_dict: dict[str, Any]if path.suffix.lower() == TOML_SUFFIX:inputs_dict = load_toml_from_path(path)else:inputs_dict = load_json_dict_from_path(path)- _assert_no_datetime_values(inputs_dict, source_path=path, key_path="")- return inputs_dict+ return _convert_temporal_inputs(inputs_dict, source_path=path)def resolve_inputs_arg_against_dir(inputs_arg: str | None, *, base_dir: Path) -> str | None:@@ -108,33 +111,68 @@ def find_default_inputs_file(directory: Path) -> Path | None:return None-def _assert_no_datetime_values(value: Any, *, source_path: Path, key_path: str) -> None:- """Recursively reject datetime/date/time instances in a loaded inputs value.+def _convert_temporal_inputs(inputs_dict: dict[str, Any], *, source_path: Path) -> dict[str, Any]:+ """Map TOML temporal literals to native ``Date`` inputs, rejecting bare times.- Only TOML can produce such values (JSON has no datetime type), but the walk- is format-agnostic and harmless to run on both.+ Only TOML can produce temporal Python objects (JSON has no temporal type), but the+ walk is format-agnostic and harmless on JSON (which yields none).++ - A **top-level** ``datetime.datetime`` / ``datetime.date`` becomes a ``DateContent``+ (a datetime keeps its time and offset; a bare date has ``time=None``). It then enters+ the pipeline-inputs seam as a bare content instance, inferred as ``native.Date``.+ - A ``datetime.time`` **anywhere** in the tree is rejected: a time of day alone has no+ date to attach to and no native concept.+ - A **nested** date/datetime (inside an envelope's ``content`` or a structured dict) is+ left in place for the factory arms and pydantic validation to consume.++ Args:+ inputs_dict: The loaded top-level inputs dictionary.+ source_path: The inputs file the values were loaded from, for the error message.++ Returns:+ A new dict with top-level temporal literals converted.++ Raises:+ InputsTimeOnlyNotSupportedError: On the first bare time-of-day value found.+ """+ converted: dict[str, Any] = {}+ for key, value in inputs_dict.items():+ _reject_time_of_day(value, source_path=source_path, key_path=str(key))+ if isinstance(value, datetime.datetime):+ converted[key] = DateContent(date=value.date(), time=value.timetz())+ elif isinstance(value, datetime.date):+ converted[key] = DateContent(date=value)+ else:+ converted[key] = value+ return converted+++def _reject_time_of_day(value: Any, *, source_path: Path, key_path: str) -> None:+ """Recursively reject bare ``datetime.time`` values; leave date/datetime alone.Args:value: The loaded value to inspect (dict, list, scalar, ...).source_path: The inputs file the value was loaded from, for the error message.- key_path: Dotted/indexed path to ``value`` inside the inputs dict, empty at the root.+ key_path: Dotted/indexed path to ``value`` inside the inputs dict.Raises:- InputsDatetimeNotSupportedError: On the first datetime-typed value found.+ InputsTimeOnlyNotSupportedError: On the first ``datetime.time`` value found."""- if isinstance(value, (datetime.datetime, datetime.date, datetime.time)):+ # datetime is a subclass of date and neither is a time, so this only fires on a bare time-of-day.+ if isinstance(value, datetime.time):located = f" at '{key_path}'" if key_path else ""msg = (- f"Inputs file '{source_path}' holds a TOML datetime value{located} ({value!r}). "- "TOML datetime inputs are not supported yet: quote the value as a string in the meantime."+ f"Inputs file '{source_path}' holds a bare TOML time-of-day{located} ({value!r}). "+ "A time of day alone has no date to attach to: include the date (e.g. 2026-07-06T12:00:00) "+ "or quote the value as a string.")- raise InputsDatetimeNotSupportedError(msg)+ raise InputsTimeOnlyNotSupportedError(msg)if isinstance(value, dict):value_dict = cast("dict[str, Any]", value)for key, sub_value in value_dict.items():sub_key_path = f"{key_path}.{key}" if key_path else str(key)- _assert_no_datetime_values(sub_value, source_path=source_path, key_path=sub_key_path)+ _reject_time_of_day(sub_value, source_path=source_path, key_path=sub_key_path)elif isinstance(value, list):value_list = cast("list[Any]", value)for index_item, sub_value in enumerate(value_list):- _assert_no_datetime_values(sub_value, source_path=source_path, key_path=f"{key_path}[{index_item}]")+ _reject_time_of_day(sub_value, source_path=source_path, key_path=f"{key_path}[{index_item}]")diff --git a/pipelex/cli/commands/run/_inputs_path_resolver.py b/pipelex/cli/commands/run/_inputs_path_resolver.pyindex b212e9f98..c8ec89d98 100644--- a/pipelex/cli/commands/run/_inputs_path_resolver.py+++ b/pipelex/cli/commands/run/_inputs_path_resolver.py@@ -9,37 +9,12 @@ relative local paths.from __future__ import annotations-from pathlib import Path-from typing import Any, cast+from typing import TYPE_CHECKING, Any, cast-from pipelex.tools.uri.resolved_uri import ResolvedLocalPath-from pipelex.tools.uri.uri_resolver import resolve_uri+from pipelex.tools.uri.uri_resolver import resolve_local_path_reference--def is_relative_local_path(uri: str) -> bool:- """Check whether *uri* is a relative local file path.-- Uses :func:`resolve_uri` to classify the URI. Returns ``True`` only when- the URI resolves to a :class:`ResolvedLocalPath` **and** the path is not- absolute.-- Args:- uri: The URI string to check.-- Returns:- ``True`` if *uri* is a relative local path, ``False`` otherwise.- """- resolved = resolve_uri(uri)- if not isinstance(resolved, ResolvedLocalPath):- return False- if "://" in resolved.path:- # An unrecognized scheme (``s3://``, ``gs://``, …) slips through ``resolve_uri`` as a- # ResolvedLocalPath but is NOT a local file path; do not rewrite it relative to base_dir- # (that would mangle ``s3://bucket/x`` into ``<base_dir>/s3:/bucket/x`` and defeat the- # downstream remote-url guards). Mirrors the same ``"://"`` stopgap in the CSV input hook;- # both go away once ``resolve_uri`` classifies schemes (tools/uri follow-up).- return False- return not Path(resolved.path).is_absolute()+if TYPE_CHECKING:+ from pathlib import Pathdef resolve_url_in_value(value: Any, *, base_dir: Path) -> Any:@@ -59,8 +34,10 @@ def resolve_url_in_value(value: Any, *, base_dir: Path) -> Any:value_dict = cast("dict[str, Any]", value)result: dict[str, Any] = {}for key, val in value_dict.items():- if key == "url" and isinstance(val, str) and is_relative_local_path(val):- result[key] = str(base_dir / val)+ if key == "url" and isinstance(val, str):+ # Expand a leading `~`, then resolve a still-relative path against base_dir; an+ # absolute/remote/scheme url is returned unchanged (as the else-branch did before).+ result[key] = resolve_local_path_reference(val, base_dir=base_dir)else:result[key] = resolve_url_in_value(val, base_dir=base_dir)return resultdiff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.pyindex bd4a00a76..cad9e14d5 100644--- a/pipelex/cli/commands/run/_run_core.py+++ b/pipelex/cli/commands/run/_run_core.py@@ -13,7 +13,7 @@ from pipelex.base_exceptions import PipelexErrorfrom pipelex.cli.cli_factory import make_pipelex_for_clifrom pipelex.cli.commands.run._inputs_file_loader import load_inputs_dict_from_pathfrom pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_paths-from pipelex.cli.commands.run.exceptions import InputsDatetimeNotSupportedError+from pipelex.cli.commands.run.exceptions import InputsTimeOnlyNotSupportedErrorfrom pipelex.cli.error_handlers import (ErrorContext,handle_model_availability_error,@@ -143,6 +143,9 @@ async def _execute_run(# Load inputs if providedpipeline_inputs = None+ # Directory bare relative file paths resolve against (Smart Inputs D3). Set only when inputs are+ # file-loaded (its parent); None for inline JSON — an inline caller has no file to anchor to.+ inputs_base_dir: Path | None = Noneif inputs:if inputs.startswith("{"):try:@@ -157,9 +160,11 @@ async def _execute_run(# literal `~` component (unquoted `~` is shell-expanded, but the quoted/`=` forms are not).inputs_path = Path(inputs).expanduser()pipeline_inputs = load_inputs_dict_from_path(inputs_path)- # Resolve relative url paths against the inputs file's parent directory- base_dir = inputs_path.parent.resolve()- pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=base_dir)+ # Resolve relative url paths against the inputs file's parent directory. The same+ # directory is threaded to the runner as inputs_base_dir so the shaper can resolve+ # bare relative file-ish / CSV strings (whose declared concept the CLI cannot see).+ inputs_base_dir = inputs_path.parent.resolve()+ pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=inputs_base_dir)typer.echo(f"Loaded inputs from: {inputs}")except FileNotFoundError as file_not_found_exc:print_traceback_if_requested(get_console())@@ -177,10 +182,10 @@ async def _execute_run(print_traceback_if_requested(get_console())typer.secho(f"Failed to parse input file: {toml_error_exc.message}", fg=typer.colors.RED, err=True)raise typer.Exit(1) from toml_error_exc- except InputsDatetimeNotSupportedError as datetime_exc:+ except InputsTimeOnlyNotSupportedError as time_only_exc:print_traceback_if_requested(get_console())- typer.secho(f"Failed to load input file: {datetime_exc.message}", fg=typer.colors.RED, err=True)- raise typer.Exit(1) from datetime_exc+ typer.secho(f"Failed to load input file: {time_only_exc.message}", fg=typer.colors.RED, err=True)+ raise typer.Exit(1) from time_only_exc# Determine pipe run modepipe_run_mode = PipeRunMode.DRY if dry_run else None@@ -200,6 +205,7 @@ async def _execute_run(is_mock_usage=mock_usage,execution_config=execution_config,library_dirs=library_dir,+ inputs_base_dir=inputs_base_dir,)response = await runner.execute(pipe_code=pipe_code,diff --git a/pipelex/cli/commands/run/exceptions.py b/pipelex/cli/commands/run/exceptions.pyindex 16d5966fb..86ad92a7c 100644--- a/pipelex/cli/commands/run/exceptions.py+++ b/pipelex/cli/commands/run/exceptions.py@@ -4,18 +4,20 @@ from pipelex.base_exceptions import ErrorDomain, PipelexErrorfrom pipelex.cogt.inference.error_classification import UserAction, UserActionKind-class InputsDatetimeNotSupportedError(PipelexError):- """Raised when a loaded inputs file carries a TOML datetime/date/time value.+class InputsTimeOnlyNotSupportedError(PipelexError):+ """Raised when a loaded inputs file carries a bare TOML time-of-day value.- TOML parses datetimes into Python objects that have no JSON equivalent and no- native concept yet, so the inputs loader rejects them until DATETIME concept- support lands.+ TOML date and datetime literals now map to the native ``Date`` concept, but a+ time of day alone has no date to attach to and no native concept, so the inputs+ loader rejects it. (Date/datetime values are accepted; only bare times are not.)"""error_domain = ErrorDomain.INPUTuser_action = UserAction(kind=UserActionKind.CHANGE_INPUT,- detail='Quote the datetime as a string in the inputs file (e.g. "2026-07-06"); native TOML datetime inputs are not supported yet',+ # The example is an unquoted TOML datetime literal (which maps to Date); quoting it would make it+ # a string (Text), i.e. the "or quote as a string" fallback — the opposite of "include the date".+ detail="A time of day alone has no date to attach to. Include the date (e.g. 2026-07-06T12:00:00), or quote the value as a string",)# The message describes a fault in the caller's own inputs file — caller-facing copy._authors_caller_facing_message = Truediff --git a/pipelex/core/concepts/concept_factory.py b/pipelex/core/concepts/concept_factory.pyindex 488f9ba97..a4f73d1cd 100644--- a/pipelex/core/concepts/concept_factory.py+++ b/pipelex/core/concepts/concept_factory.py@@ -147,6 +147,20 @@ class ConceptFactory:description="A number",structure_class_name=structure_class_name,)+ case NativeConceptCode.YES_NO:+ return Concept(+ code=native_concept_code,+ domain_code=SpecialDomain.NATIVE,+ description="The answer to a yes/no question",+ structure_class_name=structure_class_name,+ )+ case NativeConceptCode.DATE:+ return Concept(+ code=native_concept_code,+ domain_code=SpecialDomain.NATIVE,+ description="A calendar date, optionally with a time of day — as precise as its source states.",+ structure_class_name=structure_class_name,+ )case NativeConceptCode.PAGE:return Concept(code=native_concept_code,diff --git a/pipelex/core/concepts/concept_representation_generator.py b/pipelex/core/concepts/concept_representation_generator.pyindex bdd4a7556..361cb0ad6 100644--- a/pipelex/core/concepts/concept_representation_generator.py+++ b/pipelex/core/concepts/concept_representation_generator.py@@ -4,6 +4,7 @@ This module provides recursive generation of example representations for conceptIt supports two output formats: JSON (dict) and Python (class instantiation strings)."""+import datetimeimport inspectimport randomimport types@@ -310,6 +311,14 @@ class ConceptRepresentationGenerator:return 0.0elif actual_type is bool:return False+ elif actual_type is datetime.datetime:+ # ISO example that DateContent (and a `type = "datetime"` structure field) accepts,+ # so the `build inputs` -> `run` round-trip holds.+ return "2026-01-01T12:00:00"+ elif actual_type is datetime.date:+ return "2026-01-01"+ elif actual_type is datetime.time:+ return "12:00:00"else:# Handle union types like int | float (used by NumberContent)origin = get_origin(actual_type)diff --git a/pipelex/core/concepts/concept_structure_blueprint.py b/pipelex/core/concepts/concept_structure_blueprint.pyindex 909729ef8..224f456d0 100644--- a/pipelex/core/concepts/concept_structure_blueprint.py+++ b/pipelex/core/concepts/concept_structure_blueprint.py@@ -1,4 +1,4 @@-from datetime import datetime+from datetime import date, datetimefrom enum import StrEnumfrom typing import Any, Self@@ -42,6 +42,7 @@ class ConceptStructureBlueprintFieldType(StrEnum):BOOLEAN = "boolean"NUMBER = "number"DATE = "date"+ DATETIME = "datetime"CONCEPT = "concept"@@ -61,8 +62,6 @@ class ConceptStructureBlueprint(BaseModel):default_value: Any | None = Nonerequired: bool = Field(default=False)- # TODO: date translator for default_value-@field_validator("concept_ref", mode="before")@classmethoddef validate_concept_ref(cls, concept_ref: str | None) -> str | None:@@ -125,6 +124,7 @@ class ConceptStructureBlueprint(BaseModel):| ConceptStructureBlueprintFieldType.BOOLEAN| ConceptStructureBlueprintFieldType.NUMBER| ConceptStructureBlueprintFieldType.DATE+ | ConceptStructureBlueprintFieldType.DATETIME| None):pass@@ -178,8 +178,13 @@ class ConceptStructureBlueprint(BaseModel):if not isinstance(self.default_value, dict):self._raise_type_mismatch_error("dict", actual_type_name=type(self.default_value).__name__)case ConceptStructureBlueprintFieldType.DATE:- if not isinstance(self.default_value, datetime):+ # A calendar date, not a datetime: datetime is a subclass of date, so reject it explicitly+ # (a datetime default would carry a time the `date` field silently drops).+ if not isinstance(self.default_value, date) or isinstance(self.default_value, datetime):self._raise_type_mismatch_error("date", actual_type_name=type(self.default_value).__name__)+ case ConceptStructureBlueprintFieldType.DATETIME:+ if not isinstance(self.default_value, datetime):+ self._raise_type_mismatch_error("datetime", actual_type_name=type(self.default_value).__name__)case ConceptStructureBlueprintFieldType.CONCEPT:# CONCEPT type cannot have default values, this is already validated in validate_structure_blueprint# This case is here for exhaustivenessdiff --git a/pipelex/core/concepts/native/concept_native.py b/pipelex/core/concepts/native/concept_native.pyindex 544f5a4e0..338b2f193 100644--- a/pipelex/core/concepts/native/concept_native.py+++ b/pipelex/core/concepts/native/concept_native.py@@ -5,6 +5,7 @@ from pipelex.core.concepts.validation import is_concept_ref_or_code_validfrom pipelex.core.domains.domain import SpecialDomainfrom pipelex.core.qualified_ref import QualifiedReffrom pipelex.core.stuffs.composite_content import CompositeContent+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.dynamic_content import DynamicContentfrom pipelex.core.stuffs.html_content import HtmlContent@@ -15,6 +16,7 @@ from pipelex.core.stuffs.page_content import PageContentfrom pipelex.core.stuffs.search_result_content import SearchResultContentfrom pipelex.core.stuffs.text_and_images_content import TextAndImagesContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentclass NativeConceptCode(StrEnum):@@ -25,6 +27,8 @@ class NativeConceptCode(StrEnum):HTML = "Html"TEXT_AND_IMAGES = "TextAndImages"NUMBER = "Number"+ YES_NO = "YesNo"+ DATE = "Date"PAGE = "Page"JSON = "JSON"SEARCH_RESULT = "SearchResult"@@ -49,6 +53,8 @@ class NativeConceptCode(StrEnum):| NativeConceptCode.HTML| NativeConceptCode.TEXT_AND_IMAGES| NativeConceptCode.NUMBER+ | NativeConceptCode.YES_NO+ | NativeConceptCode.DATE| NativeConceptCode.PAGE| NativeConceptCode.JSON| NativeConceptCode.SEARCH_RESULT@@ -86,6 +92,10 @@ class NativeConceptCode(StrEnum):return TextAndImagesContentcase NativeConceptCode.NUMBER:return NumberContent+ case NativeConceptCode.YES_NO:+ return YesNoContent+ case NativeConceptCode.DATE:+ return DateContentcase NativeConceptCode.PAGE:return PageContentcase NativeConceptCode.JSON:@@ -145,6 +155,8 @@ class NativeConceptCode(StrEnum):| NativeConceptCode.HTML| NativeConceptCode.TEXT_AND_IMAGES| NativeConceptCode.NUMBER+ | NativeConceptCode.YES_NO+ | NativeConceptCode.DATE| NativeConceptCode.PAGE| NativeConceptCode.ANYTHING| NativeConceptCode.JSON@@ -168,6 +180,8 @@ class NativeConceptCode(StrEnum):| NativeConceptCode.HTML| NativeConceptCode.TEXT_AND_IMAGES| NativeConceptCode.NUMBER+ | NativeConceptCode.YES_NO+ | NativeConceptCode.DATE| NativeConceptCode.PAGE| NativeConceptCode.ANYTHING| NativeConceptCode.JSONdiff --git a/pipelex/core/concepts/structure_generation/generator.py b/pipelex/core/concepts/structure_generation/generator.pyindex 3769be52a..87dfa0dfa 100644--- a/pipelex/core/concepts/structure_generation/generator.py+++ b/pipelex/core/concepts/structure_generation/generator.py@@ -1,8 +1,8 @@import astimport textwrap-from datetime import datetime+from datetime import date, datetimefrom enum import Enum-from typing import Any, List, Literal, Optional+from typing import Any, List, Literal, Optional, castfrom kajson.class_registry_abstract import ClassRegistryAbstractfrom pydantic import Field@@ -206,6 +206,29 @@ class StructureGenerator:"""Format default value for Python code, ensuring strings use double quotes."""if isinstance(value, str):return self._escape_string_for_python(value)+ # `repr()` module-qualifies temporal values ("datetime.datetime(...)"/"datetime.date(...)"),+ # but the generated code imports the bare classes ("from datetime import date/datetime"), so+ # the qualified form raises AttributeError at eval. Rebuild via fromisoformat() — a lossless,+ # offset-preserving round-trip that uses those imported bare names. (datetime is a date subclass.)+ if isinstance(value, datetime):+ return f'datetime.fromisoformat("{value.isoformat()}")'+ if isinstance(value, date):+ return f'date.fromisoformat("{value.isoformat()}")'+ if isinstance(value, list):+ value_list = cast("list[Any]", value)+ formatted_items = [self._format_default_value(item) for item in value_list]+ return f"[{', '.join(formatted_items)}]"+ if isinstance(value, tuple):+ value_tuple = cast("tuple[Any, ...]", value)+ formatted_items = [self._format_default_value(item) for item in value_tuple]+ trailing_comma = "," if len(formatted_items) == 1 else ""+ return f"({', '.join(formatted_items)}{trailing_comma})"+ if isinstance(value, dict):+ value_dict = cast("dict[Any, Any]", value)+ formatted_items = [+ f"{self._format_default_value(dict_key)}: {self._format_default_value(dict_value)}" for dict_key, dict_value in value_dict.items()+ ]+ return f"{{{', '.join(formatted_items)}}}"return repr(value)def _format_class_docstring(self, docstring: str, *, indent: str = " ") -> str:@@ -373,6 +396,9 @@ class StructureGenerator:case ConceptStructureBlueprintFieldType.BOOLEAN:return "bool"case ConceptStructureBlueprintFieldType.DATE:+ self.imports.add("from datetime import date")+ return "date"+ case ConceptStructureBlueprintFieldType.DATETIME:self.imports.add("from datetime import datetime")return "datetime"case ConceptStructureBlueprintFieldType.CONCEPT:@@ -401,6 +427,7 @@ class StructureGenerator:| ConceptStructureBlueprintFieldType.INTEGER| ConceptStructureBlueprintFieldType.BOOLEAN| ConceptStructureBlueprintFieldType.DATE+ | ConceptStructureBlueprintFieldType.DATETIME| ConceptStructureBlueprintFieldType.LIST):# Create a temporary blueprint for the item type@@ -567,6 +594,9 @@ class StructureGenerator:case ConceptStructureBlueprintFieldType.BOOLEAN:return "bool"case ConceptStructureBlueprintFieldType.DATE:+ self.imports.add("from datetime import date")+ return "date"+ case ConceptStructureBlueprintFieldType.DATETIME:self.imports.add("from datetime import datetime")return "datetime"case ConceptStructureBlueprintFieldType.CONCEPT:@@ -624,6 +654,7 @@ class StructureGenerator:exec_globals: dict[str, Any] = {"__builtins__": __builtins__,# Provide these directly as they're used in generated code but not imported from pipelex+ "date": date,"datetime": datetime,"Enum": Enum,"Optional": Optional,diff --git a/pipelex/core/memory/exceptions.py b/pipelex/core/memory/exceptions.pyindex b8cf09795..18352aaf6 100644--- a/pipelex/core/memory/exceptions.py+++ b/pipelex/core/memory/exceptions.py@@ -1,4 +1,5 @@-from pipelex.base_exceptions import PipelexError+from pipelex.base_exceptions import ErrorDomain, PipelexError+from pipelex.cogt.inference.error_classification import UserAction, UserActionKindfrom pipelex.tools.misc.exceptions import ContextProviderError@@ -31,3 +32,187 @@ class WorkingMemoryStuffNotFoundError(WorkingMemoryVariableError):super().__init__(message, variable_name)self.pipe_code = pipe_codeself.concept_code = concept_code+++class InputShapingError(PipelexError):+ """Base for signature-driven input-shaping failures (Smart Inputs, D4).++ Every subclass describes a fault in the *caller's own* provided inputs — the input name,+ the declared concept, what was provided, and the expected shape rendered from the pipe's+ signature. ``error_domain = INPUT`` (the caller can fix it) and ``_authors_caller_facing_message``+ (the copy names only the caller's inputs and method, so it survives STRICT disclosure).++ Each subclass sets a per-instance ``user_action`` (advice tailored to the specific failure)+ rather than a class-level one, because the actionable fix differs per failure mode.+ """++ error_domain = ErrorDomain.INPUT+ _authors_caller_facing_message = True++ def __init__(self, message: str, *, variable_name: str, user_action: UserAction | None = None):+ self.variable_name = variable_name+ if user_action is not None:+ self.user_action = user_action+ super().__init__(message)+++class WrongScalarKindError(InputShapingError):+ """A provided bare value has the wrong JSON kind for the declared concept (D5).++ E.g. a string for a Number-refining input, a boolean for a Text input. No cross-type parsing+ is attempted — JSON already distinguishes scalars — so the mismatch is a hard error.+ """++ @classmethod+ def make(+ cls,+ *,+ variable_name: str,+ declared_concept_ref: str,+ expected_kind: str,+ provided_description: str,+ expected_shape: str,+ ) -> "WrongScalarKindError":+ message = (+ f"Input '{variable_name}' declares concept '{declared_concept_ref}', which expects {expected_kind}, "+ f"but you provided {provided_description}.\nExpected shape:\n{expected_shape}"+ )+ user_action = UserAction(kind=UserActionKind.CHANGE_INPUT, detail=f"Provide {expected_kind} for input '{variable_name}'.")+ return cls(message, variable_name=variable_name, user_action=user_action)+++class ListWhereSingularError(InputShapingError):+ """A list was provided where the signature declares a single value (D2)."""++ @classmethod+ def make(+ cls,+ *,+ variable_name: str,+ declared_concept_ref: str,+ provided_description: str,+ expected_shape: str,+ ) -> "ListWhereSingularError":+ message = (+ f"Input '{variable_name}' declares a single '{declared_concept_ref}', but you provided {provided_description}. "+ f"A list where a single value is declared is ambiguous.\nExpected shape:\n{expected_shape}"+ )+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail=f"Provide a single value for input '{variable_name}', or declare it as a list ('{declared_concept_ref}[]') in the method.",+ )+ return cls(message, variable_name=variable_name, user_action=user_action)+++class MultiplicityCountMismatchError(InputShapingError):+ """A fixed-count list input received the wrong number of items (D2)."""++ @classmethod+ def make(+ cls,+ *,+ variable_name: str,+ declared_concept_ref: str,+ expected_count: int,+ provided_count: int,+ expected_shape: str,+ ) -> "MultiplicityCountMismatchError":+ message = (+ f"Input '{variable_name}' declares exactly {expected_count} items of '{declared_concept_ref}' "+ f"('{declared_concept_ref}[{expected_count}]'), but you provided {provided_count}.\nExpected shape:\n{expected_shape}"+ )+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail=f"Provide exactly {expected_count} items for input '{variable_name}'.",+ )+ return cls(message, variable_name=variable_name, user_action=user_action)+++class StructureValidationError(InputShapingError):+ """A provided value failed to validate against the declared concept's structure (D4/D5).++ Covers a structured-concept dict missing a required field, a malformed ``{"url": ...}`` for a+ file concept, a non-ISO string for a Date concept — any value that is the right JSON kind but+ does not build into the declared content class.+ """++ @classmethod+ def make(+ cls,+ *,+ variable_name: str,+ declared_concept_ref: str,+ reason: str,+ expected_shape: str,+ ) -> "StructureValidationError":+ message = f"Input '{variable_name}' could not be built as '{declared_concept_ref}': {reason}\nExpected shape:\n{expected_shape}"+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail=f"Fix input '{variable_name}' so it matches the expected shape for '{declared_concept_ref}'.",+ )+ return cls(message, variable_name=variable_name, user_action=user_action)+++class ExplicitConceptIncompatibleError(InputShapingError):+ """An explicit envelope/object names a concept incompatible with the declared one (D6).++ The escape-hatch ``{"concept": C, "content": ...}`` (and a directly-provided ``StuffContent``)+ is now checked: ``C`` must be compatible with — refine or equal — the declared concept.+ """++ @classmethod+ def make(+ cls,+ *,+ variable_name: str,+ declared_concept_ref: str,+ provided_concept_ref: str,+ expected_shape: str,+ ) -> "ExplicitConceptIncompatibleError":+ message = (+ f"Input '{variable_name}' declares concept '{declared_concept_ref}', but you provided a value typed as "+ f"'{provided_concept_ref}', which is not compatible with it.\nExpected shape:\n{expected_shape}"+ )+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail=f"Provide a '{declared_concept_ref}' (or a concept that refines it) for input '{variable_name}'.",+ )+ return cls(message, variable_name=variable_name, user_action=user_action)+++class UnknownInputNameError(InputShapingError):+ """A provided input name is not declared by the pipe's signature (D8).++ With a signature in hand, an unknown name is a typo detector: the run fails loudly and lists+ the declared names, instead of silently carrying an input that is never read.+ """++ @classmethod+ def make(cls, *, variable_name: str, declared_names: list[str]) -> "UnknownInputNameError":+ declared_display = ", ".join(f"'{name}'" for name in declared_names) if declared_names else "(none)"+ message = f"Input '{variable_name}' is not declared by this pipe. Declared inputs: {declared_display}."+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail=f"Remove input '{variable_name}' or rename it to one of the declared inputs: {declared_display}.",+ )+ return cls(message, variable_name=variable_name, user_action=user_action)+++class NullInputError(InputShapingError):+ """A provided input value is ``null`` at the top level (D9).++ Absence is expressed by *omitting* the key (Optionals), never by a null value, so a top-level+ null is a hard error rather than a silently-dropped or mis-shaped input.+ """++ @classmethod+ def make(cls, *, variable_name: str, declared_concept_ref: str, expected_shape: str) -> "NullInputError":+ message = (+ f"Input '{variable_name}' (declared '{declared_concept_ref}') was provided as null. "+ f"Absence is expressed by omitting the key, not by a null value.\nExpected shape:\n{expected_shape}"+ )+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail=f"Provide a value for input '{variable_name}', or omit the key entirely if the input is optional.",+ )+ return cls(message, variable_name=variable_name, user_action=user_action)diff --git a/pipelex/core/memory/input_shaper.py b/pipelex/core/memory/input_shaper.pynew file mode 100644index 000000000..5158e03b0--- /dev/null+++ b/pipelex/core/memory/input_shaper.py@@ -0,0 +1,589 @@+"""Signature-driven input shaping (Smart Inputs).++The ``InputShaper`` interprets each provided input *top-down against the pipe's declared+signature* instead of bottom-up from the value's shape alone. A bare string becomes the declared+concept (a ``legal.Question``, not ``native.Text``); a bare number satisfies a ``Number``-refining+input; a bare dict validates against a structured concept; a JSON list shapes element-wise into+``ListContent[declared]``; the ``{"concept", "content"}`` envelope stays as a compat-checked escape+hatch.++This module is the top-down *dispatch*: the actual content building reuses the existing primitives+(``StuffContentFactory`` / ``ConceptLibrary.is_compatible`` / the bottom-up ``StuffFactory``). The+new code decides which arm each value takes; it does not invent new content builders.++See ``wip/inputs/smart-inputs-design.md`` (D1-D11) for the full rationale.+"""++import datetime+import json+from enum import StrEnum+from pathlib import Path+from typing import Any, cast++from mthds.protocol.pipeline_inputs import PipelineInputs, StuffContentOrData+from pydantic import ValidationError++from pipelex.base_exceptions import PipelexUnexpectedError+from pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.concept_representation_generator import ConceptRepresentationFormat+from pipelex.core.concepts.exceptions import ConceptValueError+from pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.memory.exceptions import (+ ExplicitConceptIncompatibleError,+ ListWhereSingularError,+ MultiplicityCountMismatchError,+ NullInputError,+ StructureValidationError,+ UnknownInputNameError,+ WrongScalarKindError,+)+from pipelex.core.memory.working_memory import WorkingMemory+from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs+from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec+from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity+from pipelex.core.stuffs.exceptions import StuffContentFactoryError+from pipelex.core.stuffs.list_content import ListContent+from pipelex.core.stuffs.structured_content import StructuredContent+from pipelex.core.stuffs.stuff import DictStuff, Stuff+from pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.core.stuffs.stuff_content_factory import StuffContentFactory+from pipelex.core.stuffs.stuff_factory import StuffFactory+from pipelex.hub import get_concept_library, get_native_concept+from pipelex.tools.uri.uri_resolver import resolve_local_path_reference+++class InputKind(StrEnum):+ """Which interpretation arm a declared input concept takes (D5).++ Resolved once per input from the *declared concept's* nature. ``DYNAMIC`` is the bottom-up+ fallback used for ``Dynamic`` / ``Anything`` and the out-of-matrix natives (Html, JSON, Page,+ TextAndImages, SearchResult, Composite) — the signature genuinely does not know how to shape+ them, so today's shape-driven ``StuffFactory`` path handles the whole value.+ """++ TEXT = "text"+ NUMBER = "number"+ YES_NO = "yes_no"+ DATE = "date"+ IMAGE = "image"+ DOCUMENT = "document"+ STRUCTURED = "structured"+ DYNAMIC = "dynamic"++ @property+ def is_structured(self) -> bool:+ """Whether this kind dispatches values top-down against a structured (non-native) concept."""+ match self:+ case InputKind.STRUCTURED:+ return True+ case InputKind.TEXT | InputKind.NUMBER | InputKind.YES_NO | InputKind.DATE | InputKind.IMAGE | InputKind.DOCUMENT | InputKind.DYNAMIC:+ return False+++class InputShaper:+ """Turn a caller's provided inputs into a ``WorkingMemory``, interpreted against the signature."""++ @classmethod+ def shape(+ cls,+ pipeline_inputs: PipelineInputs,+ *,+ input_specs: InputStuffSpecs,+ search_domain_codes: list[str] | None = None,+ inputs_base_dir: Path | None = None,+ ) -> WorkingMemory:+ """Shape every provided input against its declared ``StuffSpec`` and return a WorkingMemory.++ Args:+ pipeline_inputs: The caller-provided inputs (name -> value/envelope/object).+ input_specs: The entry pipe's declared inputs (name -> StuffSpec).+ search_domain_codes: Domain codes used to resolve envelope/object concepts.+ inputs_base_dir: Directory that bare *relative local* file paths resolve against (D3) —+ the inputs file's parent when the inputs were loaded from a file (threaded from the+ CLI). ``None`` (in-process / inline-JSON callers) leaves relative paths untouched+ (the CWD contract). Only bare strings in the file-ish and CSV arms are resolved; the+ ``{"url": ...}`` dict form is owned by the CLI's url-key walk.++ Raises:+ UnknownInputNameError: a provided name is not declared (D8).+ InputShapingError subclasses: a provided value cannot be shaped (D4).+ """+ cls._check_input_names(pipeline_inputs, input_specs=input_specs)+ working_memory = WorkingMemory(root={})+ for variable_name, value in pipeline_inputs.items():+ stuff_spec = input_specs.get_required_stuff_spec(variable_name=variable_name)+ stuff = cls._shape_one(+ value,+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ search_domain_codes=search_domain_codes,+ inputs_base_dir=inputs_base_dir,+ )+ working_memory.add_new_stuff(name=variable_name, stuff=stuff)+ return working_memory++ @classmethod+ def _check_input_names(cls, pipeline_inputs: PipelineInputs, *, input_specs: InputStuffSpecs) -> None:+ """Reject any provided name absent from the signature, up front (D8)."""+ declared_names = input_specs.declared_names+ declared_set = set(declared_names)+ for variable_name in pipeline_inputs:+ if variable_name not in declared_set:+ raise UnknownInputNameError.make(variable_name=variable_name, declared_names=declared_names)++ @classmethod+ def _shape_one(+ cls,+ value: Any,+ *,+ stuff_spec: StuffSpec,+ variable_name: str,+ search_domain_codes: list[str] | None,+ inputs_base_dir: Path | None,+ ) -> Stuff:+ declared_concept = stuff_spec.concept++ # (D6) Explicit forms — a {"concept", "content"} envelope, a DictStuff, or a directly-provided+ # StuffContent/ListContent object — build bottom-up as today, then get compat-checked.+ if cls._is_explicit(value):+ return cls._shape_explicit(+ value,+ declared_concept=declared_concept,+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ search_domain_codes=search_domain_codes,+ )++ # (D9) A top-level null is never a value — absence is expressed by omitting the key.+ if value is None:+ raise NullInputError.make(+ variable_name=variable_name,+ declared_concept_ref=declared_concept.concept_ref,+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )++ # (D5) Bare value: dispatch on the declared concept's nature.+ input_kind = cls.resolve_input_kind(declared_concept)+ match input_kind:+ case InputKind.DYNAMIC:+ # The signature genuinely does not know how to shape this — hand the whole raw value+ # to the bottom-up factory (today's behavior, including its own list handling).+ return StuffFactory.make_stuff_from_stuff_content_or_data(+ stuff_content_or_data=value,+ name=variable_name,+ search_domain_codes=search_domain_codes,+ )+ case InputKind.TEXT | InputKind.NUMBER | InputKind.YES_NO | InputKind.DATE | InputKind.IMAGE | InputKind.DOCUMENT | InputKind.STRUCTURED:+ content = cls._shape_with_multiplicity(+ value,+ stuff_spec=stuff_spec,+ input_kind=input_kind,+ variable_name=variable_name,+ search_domain_codes=search_domain_codes,+ inputs_base_dir=inputs_base_dir,+ )+ return StuffFactory.make_stuff(concept=declared_concept, content=content, name=variable_name)++ @classmethod+ def resolve_input_kind(cls, concept: Concept) -> InputKind:+ """Map a declared concept to its interpretation arm via ordered strict-compatibility checks (D5).++ ``strict=True`` means refinement / structural-equivalence only — a concept refining ``Number``+ matches ``NUMBER`` but an unrelated concept that merely shares a field does not.+ """+ if NativeConceptCode.is_dynamic_concept(concept_code=concept.code):+ return InputKind.DYNAMIC++ concept_library = get_concept_library()+ ordered_natives: list[tuple[NativeConceptCode, InputKind]] = [+ (NativeConceptCode.YES_NO, InputKind.YES_NO),+ (NativeConceptCode.DATE, InputKind.DATE),+ (NativeConceptCode.NUMBER, InputKind.NUMBER),+ (NativeConceptCode.IMAGE, InputKind.IMAGE),+ (NativeConceptCode.DOCUMENT, InputKind.DOCUMENT),+ (NativeConceptCode.TEXT, InputKind.TEXT),+ ]+ for native_code, input_kind in ordered_natives:+ wanted_concept = get_native_concept(native_concept=native_code)+ if concept_library.is_compatible(tested_concept=concept, wanted_concept=wanted_concept, strict=True):+ return input_kind++ # A user (non-native) concept whose structure is StructuredContent dispatches its dict+ # top-down. Everything else — the out-of-matrix natives (Html/JSON/Page/TextAndImages/+ # SearchResult/Composite/Anything) and any concept whose class is unregistered — falls back+ # to bottom-up building.+ if not Concept.is_native_concept(concept=concept):+ try:+ structure_class = concept.get_structure_class()+ except ConceptValueError:+ return InputKind.DYNAMIC+ if issubclass(structure_class, StructuredContent):+ return InputKind.STRUCTURED+ return InputKind.DYNAMIC++ @classmethod+ def _peel_multiplicity(cls, multiplicity: VariableMultiplicity | None) -> tuple[bool, int | None]:+ """Peel a declared multiplicity into ``(is_list, fixed_count)`` (D2).++ ``VariableMultiplicity`` is ``None | bool | int``; parsing only ever yields ``None`` (single),+ ``True`` (``X[]`` variable list), or an ``int N>=1`` (``X[N]`` fixed count). A genuine int is a+ fixed-count list, ``True`` a variable list, ``None`` singular. ``bool`` is a subclass of ``int``,+ so the int check must exclude it explicitly.+ """+ fixed_count = multiplicity if isinstance(multiplicity, int) and not isinstance(multiplicity, bool) else None+ is_list = multiplicity is True or fixed_count is not None+ return is_list, fixed_count++ @classmethod+ def _shape_with_multiplicity(+ cls,+ value: Any,+ *,+ stuff_spec: StuffSpec,+ input_kind: InputKind,+ variable_name: str,+ search_domain_codes: list[str] | None,+ inputs_base_dir: Path | None,+ ) -> StuffContent:+ """Peel the declared multiplicity (D2), then build the item content(s)."""+ is_list, fixed_count = cls._peel_multiplicity(stuff_spec.multiplicity)++ # (D11) A declared structured LIST input accepts a table reference — a bare tabular path+ # string or the exact {"url": <tabular path>} wrapper — read row-wise into the declared+ # concept, tried BEFORE element-wise shaping so the bare string is not misread as one item.+ if is_list and input_kind.is_structured:+ csv_list_content = cls._try_shape_csv(value, stuff_spec=stuff_spec, variable_name=variable_name, inputs_base_dir=inputs_base_dir)+ if csv_list_content is not None:+ if fixed_count is not None and len(csv_list_content.items) != fixed_count:+ raise MultiplicityCountMismatchError.make(+ variable_name=variable_name,+ declared_concept_ref=stuff_spec.concept.concept_ref,+ expected_count=fixed_count,+ provided_count=len(csv_list_content.items),+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )+ return csv_list_content++ if is_list:+ return cls._shape_list(+ value,+ stuff_spec=stuff_spec,+ input_kind=input_kind,+ variable_name=variable_name,+ fixed_count=fixed_count,+ search_domain_codes=search_domain_codes,+ inputs_base_dir=inputs_base_dir,+ )++ # Singular (multiplicity is None). A list here is ambiguous — hard error (D2).+ if isinstance(value, list):+ raise ListWhereSingularError.make(+ variable_name=variable_name,+ declared_concept_ref=stuff_spec.concept.concept_ref,+ provided_description=cls._describe_value(value),+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )+ return cls._build_item_content(+ value,+ input_kind=input_kind,+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ search_domain_codes=search_domain_codes,+ inputs_base_dir=inputs_base_dir,+ )++ @classmethod+ def _try_shape_csv(+ cls,+ value: Any,+ *,+ stuff_spec: StuffSpec,+ variable_name: str,+ inputs_base_dir: Path | None,+ ) -> ListContent[StuffContent] | None:+ """Detect and read a table reference for a declared structured list input (D11).++ Only a bare string or the exact single-key ``{"url": <str>}`` wrapper is a candidate; the+ tabular-suffix / local-only gates live in ``StuffFactory.try_make_csv_list_content``, which+ returns ``None`` for a non-tabular reference so the caller falls through to normal+ element-wise shaping (a record dict with sibling keys stays a record). A bare relative+ path resolves against ``inputs_base_dir`` first, like the file-ish arm (D3).+ """+ url: str+ if isinstance(value, str):+ url = value+ elif isinstance(value, dict):+ value_dict = cast("dict[Any, Any]", value)+ url_candidate = value_dict.get("url")+ if set(value_dict.keys()) != {"url"} or not isinstance(url_candidate, str):+ return None+ url = url_candidate+ else:+ return None+ url = cls._resolve_local_path(url, inputs_base_dir=inputs_base_dir)+ return StuffFactory.try_make_csv_list_content(stuff_spec.concept, content={"url": url}, name=variable_name)++ @classmethod+ def _resolve_local_path(cls, url: str, *, inputs_base_dir: Path | None) -> str:+ """Resolve a bare local path against the inputs file's directory (D3).++ A leading ``~`` expands to the user's home first (so ``~/photo.jpg`` is an absolute home+ path, never joined onto ``inputs_base_dir``); a still-relative path then resolves against the+ base dir. Shared with the CLI's url-key walk via ``resolve_local_path_reference``.+ """+ return resolve_local_path_reference(url, base_dir=inputs_base_dir)++ @classmethod+ def _shape_list(+ cls,+ value: Any,+ *,+ stuff_spec: StuffSpec,+ input_kind: InputKind,+ variable_name: str,+ fixed_count: int | None,+ search_domain_codes: list[str] | None,+ inputs_base_dir: Path | None,+ ) -> ListContent[StuffContent]:+ """Shape a declared-multiple input element-wise into a ListContent (D2)."""+ # A single bare value auto-wraps into a one-item list; an empty list stays empty (legal).+ item_values: list[Any] = cast("list[Any]", value) if isinstance(value, list) else [value]+ if fixed_count is not None and len(item_values) != fixed_count:+ raise MultiplicityCountMismatchError.make(+ variable_name=variable_name,+ declared_concept_ref=stuff_spec.concept.concept_ref,+ expected_count=fixed_count,+ provided_count=len(item_values),+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )+ items = [+ cls._build_item_content(+ item_value,+ input_kind=input_kind,+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ search_domain_codes=search_domain_codes,+ inputs_base_dir=inputs_base_dir,+ )+ for item_value in item_values+ ]+ return ListContent(items=items)++ @classmethod+ def _build_item_content(+ cls,+ value: Any,+ *,+ input_kind: InputKind,+ stuff_spec: StuffSpec,+ variable_name: str,+ search_domain_codes: list[str] | None,+ inputs_base_dir: Path | None,+ ) -> StuffContent:+ """Build one item's ``StuffContent`` from a value, dispatched on the declared kind (D5).++ A list item that is itself an already-built ``StuffContent`` keeps today's behavior — it is+ built bottom-up (its concept inferred from its class) and D6-compat-checked against the+ declared item concept — so a ``list[StuffContent]`` (e.g. ``[Question(...), Question(...)]``)+ shapes just like the wrapped ``ListContent`` object form. Every other item is a bare value:+ each arm converts it into the canonical shape the declared concept's structure class expects,+ then delegates to ``StuffContentFactory`` so a refining subclass is honored.+ """+ concept = stuff_spec.concept+ if isinstance(value, StuffContent):+ built = StuffFactory.make_stuff_from_stuff_content_or_data(+ stuff_content_or_data=value, name=variable_name, search_domain_codes=search_domain_codes+ )+ if not get_concept_library().is_compatible(tested_concept=built.concept, wanted_concept=concept):+ raise ExplicitConceptIncompatibleError.make(+ variable_name=variable_name,+ declared_concept_ref=concept.concept_ref,+ provided_concept_ref=built.concept.concept_ref,+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )+ return built.content+ match input_kind:+ case InputKind.TEXT:+ if not isinstance(value, str):+ raise cls._wrong_kind(stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="a string (text)", value=value)+ return cls._make_content(concept, value={"text": value}, stuff_spec=stuff_spec, variable_name=variable_name)+ case InputKind.NUMBER:+ # bool is a subclass of int — exclude it explicitly so a boolean never becomes a number.+ if isinstance(value, bool) or not isinstance(value, (int, float)):+ raise cls._wrong_kind(stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="a number", value=value)+ return cls._make_content(concept, value={"number": value}, stuff_spec=stuff_spec, variable_name=variable_name)+ case InputKind.YES_NO:+ if not isinstance(value, bool):+ raise cls._wrong_kind(stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="a boolean (true/false)", value=value)+ return cls._make_content(concept, value=value, stuff_spec=stuff_spec, variable_name=variable_name)+ case InputKind.DATE:+ if not isinstance(value, (datetime.date, str)):+ raise cls._wrong_kind(+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ expected_kind="an ISO date/datetime string or a date object",+ value=value,+ )+ return cls._make_content(concept, value=value, stuff_spec=stuff_spec, variable_name=variable_name)+ case InputKind.IMAGE | InputKind.DOCUMENT:+ canonical: dict[str, Any]+ if isinstance(value, str):+ # (D3) A bare relative local path resolves against the inputs file's directory;+ # the {"url": ...} dict form is left to the CLI's signature-blind url-key walk.+ canonical = {"url": cls._resolve_local_path(value, inputs_base_dir=inputs_base_dir)}+ elif isinstance(value, dict):+ canonical = cast("dict[str, Any]", value)+ else:+ raise cls._wrong_kind(+ stuff_spec=stuff_spec,+ variable_name=variable_name,+ expected_kind='a URL/path string or a {"url": ...} object',+ value=value,+ )+ return cls._make_content(concept, value=canonical, stuff_spec=stuff_spec, variable_name=variable_name)+ case InputKind.STRUCTURED:+ if not isinstance(value, dict):+ raise cls._wrong_kind(+ stuff_spec=stuff_spec, variable_name=variable_name, expected_kind="an object (structured value)", value=value+ )+ return cls._make_content(concept, value=cast("dict[str, Any]", value), stuff_spec=stuff_spec, variable_name=variable_name)+ case InputKind.DYNAMIC:+ # Unreachable: DYNAMIC short-circuits in `_shape_one` before multiplicity peeling.+ # Kept so the match over InputKind stays exhaustive.+ msg = f"Input '{variable_name}': DYNAMIC kind must be handled by the bottom-up fallback, not per-item shaping."+ raise PipelexUnexpectedError(msg)++ @classmethod+ def _make_content(+ cls,+ concept: Concept,+ *,+ value: dict[str, Any] | str | bool | datetime.date,+ stuff_spec: StuffSpec,+ variable_name: str,+ ) -> StuffContent:+ """Delegate to ``StuffContentFactory``, wrapping a build failure as a D4 structure error."""+ try:+ return StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=value)+ except (ValidationError, StuffContentFactoryError) as exc:+ raise StructureValidationError.make(+ variable_name=variable_name,+ declared_concept_ref=concept.concept_ref,+ reason=str(exc),+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ ) from exc++ @classmethod+ def _shape_explicit(+ cls,+ value: Any,+ *,+ declared_concept: Concept,+ stuff_spec: StuffSpec,+ variable_name: str,+ search_domain_codes: list[str] | None,+ ) -> Stuff:+ """Build an explicit form bottom-up, then compat-check the built concept against declared (D6).++ The envelope ``{"concept": C, "content": ...}``, a ``DictStuff``, and a directly-provided+ ``StuffContent``/``ListContent`` all name (or infer) their own concept. ``StuffFactory`` builds+ them exactly as today — so the explicit, possibly more-specific concept is preserved — and the+ one new rule is: that concept must be compatible with the declared one, else a D4 error.+ """+ stuff = StuffFactory.make_stuff_from_stuff_content_or_data(+ stuff_content_or_data=cast("StuffContentOrData", value),+ name=variable_name,+ search_domain_codes=search_domain_codes,+ )+ if not get_concept_library().is_compatible(tested_concept=stuff.concept, wanted_concept=declared_concept):+ raise ExplicitConceptIncompatibleError.make(+ variable_name=variable_name,+ declared_concept_ref=declared_concept.concept_ref,+ provided_concept_ref=stuff.concept.concept_ref,+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )+ if NativeConceptCode.is_dynamic_concept(concept_code=declared_concept.code):+ # Match the bare-value Dynamic path: the signature cannot guide list-vs-single shape here.+ return stuff+ cls._reconcile_explicit_multiplicity(stuff, stuff_spec=stuff_spec, variable_name=variable_name)+ return stuff++ @classmethod+ def _reconcile_explicit_multiplicity(cls, stuff: Stuff, *, stuff_spec: StuffSpec, variable_name: str) -> None:+ """Enforce the unambiguous D2 shape rules on an explicit form (D6 governs only its concept).++ An explicit form whose built content is a ``ListContent`` must not fill a singular slot, and must+ match a declared fixed count — the same list-vs-singular and ``[N]``-count rules the bare-value+ path enforces in ``_shape_with_multiplicity``. Without this, a caller handing an explicit+ ``ListContent`` (or an envelope whose ``content`` is a list) to a singular-declared input would+ have it *silently* stored into the singular slot. The singular-under-``[]`` auto-wrap question is+ deliberately left to the caller's literal form (see ``wip/inputs/input-shaper-multiplicity-gaps.md``):+ an explicit singular is taken as given, not auto-wrapped.+ """+ content = stuff.content+ if not isinstance(content, ListContent):+ return+ list_content = cast("ListContent[StuffContent]", content)+ is_list, fixed_count = cls._peel_multiplicity(stuff_spec.multiplicity)+ if not is_list:+ raise ListWhereSingularError.make(+ variable_name=variable_name,+ declared_concept_ref=stuff_spec.concept.concept_ref,+ provided_description=f"a list of {len(list_content.items)} item(s)",+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )+ if fixed_count is not None and len(list_content.items) != fixed_count:+ raise MultiplicityCountMismatchError.make(+ variable_name=variable_name,+ declared_concept_ref=stuff_spec.concept.concept_ref,+ expected_count=fixed_count,+ provided_count=len(list_content.items),+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )++ @classmethod+ def _is_explicit(cls, value: Any) -> bool:+ """Whether a value is an explicit form: a ``{"concept", "content"}`` envelope, a ``DictStuff``,+ or an already-built ``StuffContent``/``ListContent`` object (D6).++ A dict whose keys are *exactly* ``{"concept", "content"}`` is always read as an envelope — even+ if a declared structured concept happens to have fields by those names (the deterministic+ collision rule; the escape hatch for that pathological structure is a nested envelope).+ """+ if isinstance(value, (DictStuff, StuffContent)):+ return True+ return isinstance(value, dict) and set(cast("dict[Any, Any]", value).keys()) == {"concept", "content"}++ @classmethod+ def _wrong_kind(cls, *, stuff_spec: StuffSpec, variable_name: str, expected_kind: str, value: Any) -> WrongScalarKindError:+ return WrongScalarKindError.make(+ variable_name=variable_name,+ declared_concept_ref=stuff_spec.concept.concept_ref,+ expected_kind=expected_kind,+ provided_description=cls._describe_value(value),+ expected_shape=cls._render_expected_shape(stuff_spec=stuff_spec),+ )++ @classmethod+ def _render_expected_shape(cls, *, stuff_spec: StuffSpec) -> str:+ """Render the expected input shape from the signature, reused verbatim in D4 error hints."""+ return json.dumps(stuff_spec.render_stuff_spec(ConceptRepresentationFormat.JSON), ensure_ascii=False)++ @classmethod+ def _describe_value(cls, value: Any) -> str:+ """A short human description of a provided value, for error messages."""+ # bool before int: bool is a subclass of int.+ if value is None:+ return "null"+ if isinstance(value, bool):+ return f"a boolean ({str(value).lower()})"+ if isinstance(value, str):+ return f'a string ("{value[:40]}")'+ if isinstance(value, (int, float)):+ return f"a number ({value})"+ if isinstance(value, list):+ return f"a list of {len(cast('list[Any]', value))} item(s)"+ if isinstance(value, dict):+ keys = sorted(str(key) for key in cast("dict[Any, Any]", value))+ return f"an object with keys [{', '.join(keys)}]"+ return f"a value of type {type(value).__name__}"diff --git a/pipelex/core/memory/working_memory.py b/pipelex/core/memory/working_memory.pyindex 9206a02d9..af773a953 100644--- a/pipelex/core/memory/working_memory.py+++ b/pipelex/core/memory/working_memory.py@@ -14,6 +14,7 @@ from pipelex.core.memory.exceptions import (WorkingMemoryTypeError,)from pipelex.core.stuffs.composite_content import CompositeContent+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.html_content import HtmlContentfrom pipelex.core.stuffs.image_content import ImageContent@@ -25,6 +26,7 @@ from pipelex.core.stuffs.stuff_artefact import StuffArtefactfrom pipelex.core.stuffs.stuff_content import StuffContent, StuffContentTypefrom pipelex.core.stuffs.text_and_images_content import TextAndImagesContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentfrom pipelex.tools.misc.context_provider_abstract import ContextProviderAbstractMAIN_STUFF_NAME = "main_stuff"@@ -484,6 +486,14 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):"""Get stuff content as NumberContent if applicable."""return self.get_stuff(name=name).as_number+ def get_stuff_as_yes_no(self, name: str) -> YesNoContent:+ """Get stuff content as YesNoContent if applicable."""+ return self.get_stuff(name=name).as_yes_no++ def get_stuff_as_date(self, name: str) -> DateContent:+ """Get stuff content as DateContent if applicable."""+ return self.get_stuff(name=name).as_date+def get_stuff_as_html(self, name: str) -> HtmlContent:"""Get stuff content as HtmlContent if applicable."""return self.get_stuff(name=name).as_html@@ -530,6 +540,16 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):"""Get main stuff content as NumberContent if applicable."""return self.get_stuff_as_number(name=MAIN_STUFF_NAME)+ @property+ def main_stuff_as_yes_no(self) -> YesNoContent:+ """Get main stuff content as YesNoContent if applicable."""+ return self.get_stuff_as_yes_no(name=MAIN_STUFF_NAME)++ @property+ def main_stuff_as_date(self) -> DateContent:+ """Get main stuff content as DateContent if applicable."""+ return self.get_stuff_as_date(name=MAIN_STUFF_NAME)+@propertydef main_stuff_as_html(self) -> HtmlContent:"""Get main stuff content as HtmlContent if applicable."""diff --git a/pipelex/core/memory/working_memory_factory.py b/pipelex/core/memory/working_memory_factory.pyindex 3361f93a0..2db7bba6f 100644--- a/pipelex/core/memory/working_memory_factory.py+++ b/pipelex/core/memory/working_memory_factory.py@@ -1,3 +1,5 @@+from pathlib import Path+import shortuuidfrom mthds.protocol.pipeline_inputs import PipelineInputsfrom polyfactory.exceptions import FactoryException@@ -7,6 +9,7 @@ from pipelex import logfrom pipelex.cogt.content_generation.dry_mock import stamp_mock_main_coordinationfrom pipelex.cogt.content_generation.dry_run_factory import DryRunFactoryfrom pipelex.core.memory.exceptions import WorkingMemoryFactoryError+from pipelex.core.memory.input_shaper import InputShaperfrom pipelex.core.memory.working_memory import MAIN_STUFF_NAME, StuffDict, WorkingMemoryfrom pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs, NamedStuffSpec, TypedNamedStuffSpecfrom pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec@@ -69,18 +72,40 @@ class WorkingMemoryFactory(BaseModel):cls,pipeline_inputs: PipelineInputs,*,+ input_specs: InputStuffSpecs | None = None,search_domain_codes: list[str] | None = None,+ inputs_base_dir: Path | None = None,) -> WorkingMemory:"""Create a WorkingMemory from a pipeline inputs dictionary.+ When ``input_specs`` is provided (the entry pipe's declared inputs), each value is+ interpreted **top-down against its declared concept** by the :class:`InputShaper` (Smart+ Inputs): a bare string becomes the declared concept, a bare number/dict/list is shaped to+ it, the ``{concept, content}`` envelope is compat-checked, and an undeclared name is a hard+ error (D8). When ``input_specs`` is ``None`` (no signature available), each value is shaped+ **bottom-up** from its own shape alone — today's behavior, unchanged.+Args:pipeline_inputs: Dictionary in the format from API serialization+ input_specs: The entry pipe's declared inputs; ``None`` disables signature-driven shapingsearch_domain_codes: List of domain codes to search for concepts+ inputs_base_dir: Directory that bare *relative local* file paths resolve against (D3);+ the inputs file's parent when inputs were file-loaded by a CLI. ``None`` for API/SDK+ and in-process callers (they pass absolute urls / storage uris). Only consulted by+ the shaper's file-ish / CSV arms.Returns:WorkingMemory object reconstructed from the implicit format"""+ if input_specs is not None:+ return InputShaper.shape(+ pipeline_inputs,+ input_specs=input_specs,+ search_domain_codes=search_domain_codes,+ inputs_base_dir=inputs_base_dir,+ )+working_memory = cls.make_empty()for stuff_key, stuff_content_or_data in pipeline_inputs.items():diff --git a/pipelex/core/pipes/inputs/input_renderer.py b/pipelex/core/pipes/inputs/input_renderer.pyindex dc38e2d4b..1bf055fd2 100644--- a/pipelex/core/pipes/inputs/input_renderer.py+++ b/pipelex/core/pipes/inputs/input_renderer.py@@ -1,10 +1,12 @@import jsonfrom enum import StrEnum-from typing import Any+from typing import Any, castimport tomlkit+from pipelex.core.memory.input_shaper import InputKind, InputShaperfrom pipelex.core.pipes.inputs.exceptions import NoInputsRequiredError+from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecsfrom pipelex.core.pipes.pipe_abstract import PipeAbstract@@ -15,11 +17,18 @@ class InputsTemplateFormat(StrEnum):TOML = "toml"-def build_inputs_template(the_pipe: PipeAbstract) -> dict[str, Any]:+def build_inputs_template(the_pipe: PipeAbstract, *, explicit: bool = False) -> dict[str, Any]:"""Build the inputs template dict for a pipe.+ By default the template is the *light*, signature-driven shape (D11): example values shaped like+ what smart inputs accepts — a bare string for a Text-refining input, a bare number for a+ Number-refining one, the content dict for a structured one, a bare URL for a file-ish one, and+ the same wrapped in a list for a declared-multiple input. With ``explicit=True`` the ceremonial+ ``{"concept", "content"}`` envelope form is kept.+Args:the_pipe: The pipe to build the inputs template for+ explicit: When True, keep the envelope form; when False (default), emit the light shape.Returns:Dictionary mapping each input variable to its generated example value@@ -31,15 +40,19 @@ def build_inputs_template(the_pipe: PipeAbstract) -> dict[str, Any]:msg = f"No inputs required for pipe '{the_pipe.code}'."raise NoInputsRequiredError(msg)- return the_pipe.inputs.build_inputs_template()+ envelope_template = the_pipe.inputs.build_inputs_template()+ if explicit:+ return envelope_template+ return _delighten_template(envelope_template, input_specs=the_pipe.inputs)-def render_inputs(the_pipe: PipeAbstract, *, indent: int = 2) -> str:+def render_inputs(the_pipe: PipeAbstract, *, indent: int = 2, explicit: bool = False) -> str:"""Render a JSON representation of the pipe's inputs.Args:the_pipe: The pipe to render inputs forindent: Number of spaces for indentation (default: 2)+ explicit: When True, keep the envelope form; when False (default), emit the light shape.Returns:Formatted JSON string with the inputs representation@@ -47,14 +60,18 @@ def render_inputs(the_pipe: PipeAbstract, *, indent: int = 2) -> str:Raises:NoInputsRequiredError: If the pipe has no inputs"""- return json.dumps(build_inputs_template(the_pipe), indent=indent, ensure_ascii=False)+ return json.dumps(build_inputs_template(the_pipe, explicit=explicit), indent=indent, ensure_ascii=False)-def render_inputs_toml(the_pipe: PipeAbstract) -> str:+def render_inputs_toml(the_pipe: PipeAbstract, *, explicit: bool = False) -> str:"""Render a TOML representation of the pipe's inputs.+ In the default light mode each top-level key carries the declared concept as a ``# concept: ...``+ comment (TOML has comments; JSON does not — one reason ``--explicit`` stays around).+Args:the_pipe: The pipe to render inputs for+ explicit: When True, keep the envelope form; when False (default), emit the light shape.Returns:TOML string with the inputs representation@@ -62,24 +79,119 @@ def render_inputs_toml(the_pipe: PipeAbstract) -> str:Raises:NoInputsRequiredError: If the pipe has no inputs"""- return serialize_inputs_template_to_toml(build_inputs_template(the_pipe))---def serialize_inputs_template_to_toml(template: dict[str, Any]) -> str:+ template = build_inputs_template(the_pipe, explicit=explicit)+ if explicit:+ return serialize_inputs_template_to_toml(template)+ return serialize_inputs_template_to_toml(template, light=True, concept_comments=build_concept_comments(the_pipe.inputs))+++def serialize_inputs_template_to_toml(+ template: dict[str, Any],+ *,+ light: bool = False,+ concept_comments: dict[str, str] | None = None,+) -> str:"""Serialize an inputs template dict to a TOML string.- TOML has no null: a None placeholder is substituted with an empty string- so the key stays visible in the template (omitting it would hide the field- from the user filling the template in).+ TOML has no null: a None placeholder is substituted with an empty string so the key stays visible+ in the template (omitting it would hide the field from the user filling the template in).++ Envelope templates (``light=False``) are all-tables, so the plain ``tomlkit.dumps`` layout is+ both valid and unchanged. Light templates interleave bare top-level scalars with structured+ values, so they are laid out with **inline tables** — everything stays at the top level, which+ keeps declaration order and lets a trailing scalar avoid being swallowed into a ``[section]`` — and+ each key may carry a ``# concept: ...`` comment.Args:template: The inputs template dict (variable name -> example value)+ light: When True, use the inline-table layout that a light template requires.+ concept_comments: Optional per-key comment text (without the leading ``# ``), only used in+ light mode.Returns:TOML string of the template"""sanitized = _substitute_none_values(template)- return tomlkit.dumps(sanitized) # pyright: ignore[reportUnknownMemberType]+ if not light:+ return tomlkit.dumps(sanitized) # pyright: ignore[reportUnknownMemberType]++ document = tomlkit.document()+ comments = concept_comments or {}+ for key, value in sanitized.items():+ comment_text = comments.get(key)+ if comment_text:+ document.add(tomlkit.comment(comment_text))+ document[key] = _to_toml_value(value)+ return tomlkit.dumps(document) # pyright: ignore[reportUnknownMemberType]+++def _delighten_template(envelope_template: dict[str, Any], *, input_specs: InputStuffSpecs) -> dict[str, Any]:+ """Transform every envelope entry into its light value, dispatched on the declared concept's kind."""+ light_template: dict[str, Any] = {}+ for variable_name, entry in envelope_template.items():+ stuff_spec = input_specs.get_required_stuff_spec(variable_name=variable_name)+ kind = InputShaper.resolve_input_kind(stuff_spec.concept)+ light_template[variable_name] = _delighten_entry(entry, kind=kind)+ return light_template+++def _delighten_entry(entry: dict[str, Any], *, kind: InputKind) -> Any:+ """Turn one envelope entry (``{"concept", "content"}``) into the light value the shaper accepts.++ Mirrors the shaper's arms (see ``input_shaper.py``): a scalar unwraps to its single content+ field, a structured value keeps its content dict, and a Dynamic / out-of-matrix value keeps the+ whole envelope — the signature genuinely can't shape it, so bottom-up building still needs it.+ """+ match kind:+ case InputKind.DYNAMIC:+ return entry+ case InputKind.STRUCTURED:+ return entry["content"]+ case InputKind.TEXT | InputKind.NUMBER | InputKind.YES_NO | InputKind.DATE | InputKind.IMAGE | InputKind.DOCUMENT:+ return _unwrap_scalar_content(entry["content"], envelope=entry)+++def _unwrap_scalar_content(content: Any, *, envelope: dict[str, Any]) -> Any:+ """Unwrap a scalar input's content to its bare field value (element-wise for a list).++ Each scalar content is a single-field dict (``{"text": ...}`` / ``{"number": ...}`` / ``{"url":+ ...}`` / ``{"date": ...}`` / ``{"yes_no": ...}``) — the bare value the shaper re-wraps. A content+ that is not a single-field dict (a refining scalar with extra required fields, which the shaper+ can't build from a bare value anyway) can't be delightened losslessly, so the whole envelope is+ kept for that input, so the template still runs.+ """+ items: list[Any] = cast("list[Any]", content) if isinstance(content, list) else [content]+ unwrapped: list[Any] = []+ for item in items:+ if isinstance(item, dict) and len(cast("dict[str, Any]", item)) == 1:+ unwrapped.append(next(iter(cast("dict[str, Any]", item).values())))+ else:+ return envelope+ return unwrapped if isinstance(content, list) else unwrapped[0]+++def build_concept_comments(input_specs: InputStuffSpecs) -> dict[str, str]:+ """Build the per-input ``concept: <ref>`` comment map (declared concept + multiplicity/presence).++ Shared by both the human ``render_inputs_toml`` and the agent-CLI TOML path so a light TOML+ template carries the same concept hints on either surface.+ """+ return {variable_name: f"concept: {stuff_spec.to_bundle_representation()}" for variable_name, stuff_spec in input_specs.root.items()}+++def _to_toml_value(value: Any) -> Any:+ """Convert a light template value into an order-preserving TOML value (dicts become inline tables)."""+ if isinstance(value, dict):+ inline_table = tomlkit.inline_table()+ for key, sub_value in cast("dict[str, Any]", value).items():+ inline_table[key] = _to_toml_value(sub_value)+ return inline_table+ if isinstance(value, list):+ array = tomlkit.array()+ for item in cast("list[Any]", value):+ array.append(_to_toml_value(item)) # pyright: ignore[reportUnknownMemberType]+ return array+ return valuedef _substitute_none_values(value: Any) -> Any:diff --git a/pipelex/core/pipes/pipe_output.py b/pipelex/core/pipes/pipe_output.pyindex 3df55d2a0..4fd4275d3 100644--- a/pipelex/core/pipes/pipe_output.py+++ b/pipelex/core/pipes/pipe_output.py@@ -4,6 +4,7 @@ from mthds.protocol.pipe_output import PipeOutputAbstractfrom pydantic import Fieldfrom pipelex.core.memory.working_memory import WorkingMemory+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.html_content import HtmlContentfrom pipelex.core.stuffs.image_content import ImageContentfrom pipelex.core.stuffs.list_content import ListContent@@ -13,6 +14,7 @@ from pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.stuff_content import StuffContentTypefrom pipelex.core.stuffs.text_and_images_content import TextAndImagesContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentfrom pipelex.graph.graphspec import GraphSpecfrom pipelex.pipeline.pipeline_models import SpecialPipelineIdfrom pipelex.reporting.reporting_types import AnyTokensUsage@@ -78,6 +80,16 @@ class PipeOutput(PipeOutputAbstract[WorkingMemory]):"""Get main stuff content as NumberContent if applicable."""return self.working_memory.main_stuff_as_number+ @property+ def main_stuff_as_yes_no(self) -> YesNoContent:+ """Get main stuff content as YesNoContent if applicable."""+ return self.working_memory.main_stuff_as_yes_no++ @property+ def main_stuff_as_date(self) -> DateContent:+ """Get main stuff content as DateContent if applicable."""+ return self.working_memory.main_stuff_as_date+@propertydef main_stuff_as_html(self) -> HtmlContent:"""Get main stuff content as HtmlContent if applicable."""diff --git a/pipelex/core/registry_models.py b/pipelex/core/registry_models.pyindex a1e34a8b8..382820321 100644--- a/pipelex/core/registry_models.py+++ b/pipelex/core/registry_models.py@@ -3,6 +3,7 @@ from typing import Any, ClassVarfrom pipelex.core.pipes.pipe_abstract import PipeAbstractTypefrom pipelex.core.pipes.pipe_factory import PipeFactoryProtocolfrom pipelex.core.stuffs.composite_content import CompositeContent+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.dynamic_content import DynamicContentfrom pipelex.core.stuffs.html_content import HtmlContent@@ -17,6 +18,7 @@ from pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.text_and_images_content import TextAndImagesContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentfrom pipelex.pipe_controllers.batch.pipe_batch import PipeBatchfrom pipelex.pipe_controllers.batch.pipe_batch_factory import PipeBatchFactoryfrom pipelex.pipe_controllers.condition.pipe_condition import PipeCondition@@ -92,6 +94,8 @@ class CoreRegistryModels(RegistryModels):STUFF: ClassVar[list[ModelType]] = [TextContent,NumberContent,+ YesNoContent,+ DateContent,ImageContent,Stuff,StuffContent,diff --git a/pipelex/core/stuffs/date_content.py b/pipelex/core/stuffs/date_content.pynew file mode 100644index 000000000..fe1dbad36--- /dev/null+++ b/pipelex/core/stuffs/date_content.py@@ -0,0 +1,119 @@+import datetime+import json+from typing import Any++from pydantic import Field, ValidationInfo, field_validator+from rich.json import JSON+from typing_extensions import override++from pipelex.core.stuffs.exceptions import DateContentError+from pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.tools.misc.pretty import PrettyPrintable+++def _is_numeric_string(text: str) -> bool:+ """Whether a string is purely a number (an epoch), so it must never be read as a date/time.++ Every legitimate ISO date/time string carries a '-', ':', 'T', or space separator, so ``float()``+ raises on it; only a bare number parses — including the signed / decimal / exponent forms+ (``-86400``, ``86400.0``, ``8.64e4``) that a plain ``.isdigit()`` check lets slip past (DT6).+ """+ try:+ float(text.strip())+ except ValueError:+ return False+ return True+++class DateContent(StuffContent):+ """A calendar date, optionally with a time of day — as precise as its source states.++ The optional ``time`` carries the UTC offset on its ``tzinfo`` when the source states one+ (fidelity, not normalization). Invalid states are unrepresentable by construction: no time+ without a date, no offset without a time.+ """++ date: datetime.date = Field(description="The calendar date, in ISO 8601 (e.g. 2026-07-07). Always required.")+ time: datetime.time | None = Field(+ default=None,+ description=(+ "The time of day, in ISO 8601 (e.g. 15:40:00, or 15:40:00+02:00 with a UTC offset). "+ "Include it only when the source states a time — never invent a time. "+ "Keep the UTC offset exactly when the source states one."+ ),+ )++ @field_validator("date", "time", mode="before")+ @classmethod+ def _reject_lax_temporal(cls, value: Any, info: ValidationInfo) -> Any:+ # Close pydantic's lax-mode coercions that would silently produce wrong temporal data — all+ # raise ValueError so pydantic wraps them into a ValidationError the input/factory path catches+ # (a raw TypeError would escape model_validate uncaught):+ # - a bare int/float, or any purely-numeric string, is read as epoch seconds; a real ISO+ # date/time always carries a '-'/':'/ 'T'/space separator, so a numeric string is only ever+ # an epoch (DT6).+ # - a datetime on the `date` field is silently truncated to the date, dropping its time and+ # UTC offset — exactly the fidelity loss DT3 forbids ("no silent midnight").+ if isinstance(value, datetime.datetime):+ msg = "A Date's `date` field takes a calendar date, not a datetime; put the time and offset in `time` instead."+ raise ValueError(msg) # noqa: TRY004 — must be ValueError so pydantic wraps it into a ValidationError+ if isinstance(value, (int, float)) or (isinstance(value, str) and _is_numeric_string(value)): # bool is an int subclass+ msg = "A Date's date/time must be an ISO 8601 string or a date/time object, never a number (no epoch-seconds)."+ raise ValueError(msg)+ # A datetime-shaped STRING on the `date` field would be truncated to the calendar date (silently+ # so at midnight), dropping the stated time and offset — the same DT3 loss as a datetime object.+ # The `time` field legitimately carries ':' (e.g. "15:40:00"), so this narrows to `date`.+ if info.field_name == "date" and isinstance(value, str) and ("T" in value or ":" in value):+ msg = (+ "A Date's `date` field takes a calendar date alone; a string carrying a time "+ "(e.g. '2026-07-07T00:00:00') would drop it — put the time and offset in `time` instead."+ )+ raise ValueError(msg)+ return value++ def _iso(self) -> str:+ """ISO 8601 of exactly the stored precision: date alone, or date + time (with offset if present)."""+ if self.time is None:+ return self.date.isoformat()+ return f"{self.date.isoformat()}T{self.time.isoformat()}"++ def to_datetime(self) -> datetime.datetime:+ """Combine date and time into a ``datetime.datetime``.++ Raises:+ DateContentError: when there is no time of day — converting would invent one, which+ this concept refuses to do (a silent midnight is exactly the fabrication DT2 forbids).+ """+ if self.time is None:+ msg = "This Date has no time of day, so it cannot be converted to a datetime without inventing one."+ raise DateContentError(msg)+ return datetime.datetime.combine(self.date, self.time)++ @property+ @override+ def short_desc(self) -> str:+ if self.time is None:+ return f"a date ({self._iso()})"+ return f"a date and time ({self._iso()})"++ @override+ def rendered_plain(self) -> str:+ return self._iso()++ @override+ def rendered_html(self) -> str:+ return self._iso()++ @override+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:+ return self._iso()++ @override+ def rendered_json(self) -> str:+ return json.dumps({"date": self.date.isoformat(), "time": self.time.isoformat() if self.time is not None else None})++ @override+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:+ # The base renders smart_dump() (real date/time objects, which stdlib json can't serialize);+ # render the ISO two-field JSON instead so pretty_print of a Date does not crash.+ return JSON(self.rendered_json())diff --git a/pipelex/core/stuffs/exceptions.py b/pipelex/core/stuffs/exceptions.pyindex 4d79fd956..41a4a7132 100644--- a/pipelex/core/stuffs/exceptions.py+++ b/pipelex/core/stuffs/exceptions.py@@ -28,6 +28,18 @@ class StuffContentTypeError(StuffError):super().__init__(message)+class DateContentError(StuffError):+ """Raised when a DateContent operation needs a time of day the value does not carry.++ The only such operation today is ``to_datetime()`` on a date-only value: converting it+ would invent a time, which the Date concept refuses to do (no silent midnight).+ """++ # The message describes the caller's own data (a date-only Date has no time to convert) and carries+ # no server internals, so it must survive STRICT disclosure — like OptionalValueAbsentError.+ _authors_caller_facing_message = True++class StuffContentValidationError(StuffError):"""Raised when content validation fails during type conversion."""diff --git a/pipelex/core/stuffs/html_rendering.py b/pipelex/core/stuffs/html_rendering.pyindex 1e2531875..de86a4652 100644--- a/pipelex/core/stuffs/html_rendering.py+++ b/pipelex/core/stuffs/html_rendering.py@@ -1,5 +1,5 @@import html as html_module-from datetime import date, datetime+from datetime import date, datetime, timefrom enum import Enumfrom typing import Any, cast@@ -21,7 +21,7 @@ def render_value_html(value: Any) -> str:- int: renders as string- float: renders as string- Enum: renders the enum value- - datetime/date: renders in ISO format+ - datetime/date/time: renders in ISO format- list/tuple: renders as <ul> list- dict: renders as <dl> definition list- Other: escapes string representation@@ -56,6 +56,9 @@ def render_value_html(value: Any) -> str:case date():return html_module.escape(value.isoformat())+ case time():+ return html_module.escape(value.isoformat())+case list() | tuple():list_value = cast("list[Any]", value)if len(list_value) == 0:diff --git a/pipelex/core/stuffs/stuff.py b/pipelex/core/stuffs/stuff.pyindex 769a5e4e7..f11a4b35c 100644--- a/pipelex/core/stuffs/stuff.py+++ b/pipelex/core/stuffs/stuff.py@@ -9,6 +9,7 @@ from typing_extensions import overridefrom pipelex import logfrom pipelex.core.concepts.concept import Concept+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.exceptions import StuffContentTypeError, StuffContentValidationErrorfrom pipelex.core.stuffs.html_content import HtmlContent@@ -20,6 +21,7 @@ from pipelex.core.stuffs.stuff_artefact import StuffArtefactfrom pipelex.core.stuffs.stuff_content import StuffContent, StuffContentTypefrom pipelex.core.stuffs.text_and_images_content import TextAndImagesContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentfrom pipelex.tools.misc.pretty import PrettyPrintable, PrettyRenderablefrom pipelex.tools.misc.string_utils import pascal_case_to_snake_casefrom pipelex.tools.typing.pydantic_utils import CustomBaseModel, format_pydantic_validation_error@@ -92,6 +94,14 @@ class Stuff(PrettyRenderable, CustomBaseModel, StuffAbstract[Concept, StuffContedef is_number(self) -> bool:return isinstance(self.content, NumberContent)+ @property+ def is_yes_no(self) -> bool:+ return isinstance(self.content, YesNoContent)++ @property+ def is_date(self) -> bool:+ return isinstance(self.content, DateContent)+def content_as(self, content_type: type[StuffContentType]) -> StuffContentType:"""Get content with proper typing if it's of the expected type."""return self.verify_content_type(self.content, content_type=content_type)@@ -219,6 +229,16 @@ class Stuff(PrettyRenderable, CustomBaseModel, StuffAbstract[Concept, StuffConte"""Get content as NumberContent if applicable."""return self.content_as(content_type=NumberContent)+ @property+ def as_yes_no(self) -> YesNoContent:+ """Get content as YesNoContent if applicable."""+ return self.content_as(content_type=YesNoContent)++ @property+ def as_date(self) -> DateContent:+ """Get content as DateContent if applicable."""+ return self.content_as(content_type=DateContent)+@propertydef as_html(self) -> HtmlContent:"""Get content as HtmlContent if applicable."""diff --git a/pipelex/core/stuffs/stuff_content_factory.py b/pipelex/core/stuffs/stuff_content_factory.pyindex c7514976d..5c0ca5d03 100644--- a/pipelex/core/stuffs/stuff_content_factory.py+++ b/pipelex/core/stuffs/stuff_content_factory.py@@ -1,21 +1,67 @@+import datetime+import refrom typing import Anyfrom pipelex.core.concepts.concept import Concept+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.exceptions import StuffContentFactoryErrorfrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentfrom pipelex.hub import get_class_registryclass StuffContentFactory:@classmethod- def make_content_from_value(cls, stuff_content_subclass: type[StuffContent], *, value: dict[str, Any] | str) -> StuffContent:+ def make_content_from_value(+ cls, stuff_content_subclass: type[StuffContent], *, value: dict[str, Any] | str | bool | datetime.date+ ) -> StuffContent:+ # bool must be handled ahead of any future int handling (bool is a subclass of int) and before model_validate,+ # which rejects a bare bool. Covers native YesNoContent and the subclasses generated for concepts refining YesNo.+ if isinstance(value, bool) and issubclass(stuff_content_subclass, YesNoContent):+ return stuff_content_subclass(yes_no=value)if isinstance(value, str) and stuff_content_subclass == TextContent:return TextContent(text=value)+ # A date/datetime object or an ISO string under a Date-family class builds via the split constructor;+ # a dict ({"date","time"}) still rides model_validate below. Covers native Date and concepts refining it.+ if issubclass(stuff_content_subclass, DateContent) and isinstance(value, (datetime.date, str)):+ return cls._make_date_content(stuff_content_subclass, value=value)return stuff_content_subclass.model_validate(obj=value)@classmethod- def make_stuff_content_from_concept_required(cls, concept: Concept, *, value: dict[str, Any] | str) -> StuffContent:+ def _make_date_content(cls, date_subclass: type[DateContent], *, value: datetime.date | str) -> DateContent:+ """Build a DateContent (or refining subclass) from a date/datetime object or a strict ISO string."""+ if isinstance(value, datetime.datetime):+ return date_subclass(date=value.date(), time=value.timetz())+ if isinstance(value, datetime.date):+ return date_subclass(date=value)+ the_date, the_time = cls._parse_iso_temporal(value)+ return date_subclass(date=the_date, time=the_time)++ @classmethod+ def _parse_iso_temporal(cls, value: str) -> tuple[datetime.date, datetime.time | None]:+ """Parse a strict *extended* ISO 8601 date or datetime, date-first so a bare date never fabricates a midnight time."""+ # Require the date component to be extended-calendar YYYY-MM-DD (optionally followed by a T/space time+ # part, which fromisoformat then validates precisely). date.fromisoformat / datetime.fromisoformat (3.11+)+ # also accept the basic "YYYYMMDD" / "YYYYMMDDTHHMMSS" forms and ISO week-dates ("2026-W27-2"), which would+ # silently normalize a non-extended input into a DateContent — and let an all-digit epoch string slip past+ # DateContent's own no-epoch-seconds guard. Pin extended-only (also subsumes the old all-digit reject).+ if not re.fullmatch(r"\d{4}-\d{2}-\d{2}([Tt ].*)?", value.strip()):+ msg = f"Date input '{value}' is not an extended ISO 8601 date or datetime (e.g. '2026-07-07' or '2026-07-07T15:40:00+02:00')."+ raise StuffContentFactoryError(msg)+ try:+ return datetime.date.fromisoformat(value), None+ except ValueError:+ pass+ try:+ parsed = datetime.datetime.fromisoformat(value)+ except ValueError as exc:+ msg = f"Date input '{value}' is not an ISO 8601 date or datetime (e.g. '2026-07-07' or '2026-07-07T15:40:00+02:00')."+ raise StuffContentFactoryError(msg) from exc+ return parsed.date(), parsed.timetz()++ @classmethod+ def make_stuff_content_from_concept_required(cls, concept: Concept, *, value: dict[str, Any] | str | bool | datetime.date) -> StuffContent:"""Create StuffContent from concept code, requiring the concept to be linked to a class in the registry.Raises StuffContentFactoryError if no registry class is found."""diff --git a/pipelex/core/stuffs/stuff_factory.py b/pipelex/core/stuffs/stuff_factory.pyindex 3190d6933..113c4d5a7 100644--- a/pipelex/core/stuffs/stuff_factory.py+++ b/pipelex/core/stuffs/stuff_factory.py@@ -1,3 +1,4 @@+import datetimefrom pathlib import Pathfrom typing import Any, castfrom urllib.parse import urlsplit, urlunsplit@@ -143,6 +144,20 @@ class StuffFactory:name: str | None,code: str | None,) -> Stuff | None:+ """Wrap :meth:`try_make_csv_list_content` into a ``Stuff`` (Case 2.5 envelope path)."""+ list_content = cls.try_make_csv_list_content(concept, content=content, name=name)+ if list_content is None:+ return None+ return cls.make_stuff(concept=concept, content=list_content, name=name, code=code)++ @classmethod+ def try_make_csv_list_content(+ cls,+ concept: Concept,+ *,+ content: dict[str, Any],+ name: str | None,+ ) -> ListContent[StuffContent] | None:"""Build a ``ListContent[row-concept]`` from a ``{"url": "...csv"}`` input reference.Detection is gated to the explicit wrapper shape — ``content`` must be *exactly*@@ -150,10 +165,14 @@ class StuffFactory:becomes one instance of the concept's structure class, so one CSV yields one``ListContent`` (the concept names the *row* type). Returns ``None`` for an ordinaryrecord dict — no ``url`` key, sibling keys alongside ``url``, a non-tabular suffix, or a- native concept — so the caller falls through to normal Case 2.5 dict handling. The- single-key gate keeps a real record that merely *has* a ``url`` field (e.g.- ``{"label": "Home", "url": "report.csv"}``) from being silently reduced to a table with- its sibling keys dropped.+ native concept — so the caller falls through to normal dict handling. The single-key gate+ keeps a real record that merely *has* a ``url`` field (e.g. ``{"label": "Home", "url":+ "report.csv"}``) from being silently reduced to a table with its sibling keys dropped.++ Shared by the bottom-up factory (Case 2.5 envelope) and the top-down ``InputShaper``+ (a bare tabular path / bare ``{"url": ...}`` under a declared structured list, Smart Inputs+ D11). The shaper resolves a relative path against the inputs-file dir before calling in, so+ this method's own gates operate on an already-resolved url.v1 reads LOCAL paths only: a tabular-suffixed remote ``url`` (``http(s)``/``s3``/``gs``/``pipelex-storage``) is rejected with a clear ``CsvError`` rather than opened as a local path.@@ -222,8 +241,7 @@ class StuffFactory:# caller-fixable input problem, not a raw ValueError that escapes into core/runner.msg = f"CSV input for stuff '{name}': concept '{concept.concept_ref}' has no registered structure class to read CSV rows into."raise CsvError(msg) from exc- list_content = list_content_from_csv(Path(resolved.path), row_model=row_model)- return cls.make_stuff(concept=concept, content=list_content, name=name, code=code)+ return list_content_from_csv(Path(resolved.path), row_model=row_model)@classmethoddef make_stuff_from_stuff_content_or_data(@@ -249,6 +267,9 @@ class StuffFactory:Case 2: Dict with 'concept' AND 'content' keys (can be plain dict or DictStuff instance)2.1/2.1b: {"concept": "Text"/"native.Text", "content": str} → TextContent with Text concept2.1c: {"concept": "domain.Concept", "content": str} → TextContent with that concept (if compatible)+ 2.1d: {"concept": "YesNo"/"domain.Concept", "content": bool} → YesNoContent (if YesNo-compatible)+ 2.1e: {"concept": "Date"/"domain.Concept", "content": date/datetime obj} → DateContent (if Date-compatible)+ 2.1f: {"concept": "Date"/"domain.Concept", "content": ISO str} → DateContent (if Date-compatible, checked after Text)2.2/2.2b: {"concept": "...", "content": list[str]} → ListContent[TextContent]2.3: {"concept": "...", "content": StuffContent} → Use the StuffContent2.4: {"concept": "...", "content": list[StuffContent]} → ListContent[StuffContent]@@ -465,6 +486,24 @@ class StuffFactory:)raise StuffFactoryError(msg) from exc+ # Case 2.1d: content is a bool → YesNoContent for a YesNo-compatible concept.+ # Checked BEFORE the str/int-ish arms (bool is a subclass of int) so a boolean never falls through to+ # the final "unexpected type" error. No string coercion: "yes"/"no" strings take the str path and fail there.+ if isinstance(content, bool):+ yes_no_concept = get_native_concept(native_concept=NativeConceptCode.YES_NO)+ if concept_library.is_compatible(tested_concept=concept, wanted_concept=yes_no_concept, strict=True):+ return cls.make_stuff(+ concept=concept,+ content=StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=content),+ name=name,+ code=code,+ )+ msg = (+ f"Trying to create a Stuff '{name}' in the inputs of your pipe, from a dict that should represent a StuffContentOrData "+ f"but the concept of name '{concept_ref}' is not compatible with native concept 'native.YesNo' (the content is a boolean)"+ )+ raise StuffFactoryError(msg)+# Case 2.1: content is a stringif isinstance(content, str):# Check if concept is strictly compatible with Text (refinement = strict compatibility)@@ -476,9 +515,37 @@ class StuffFactory:name=name,code=code,)+ # Case 2.1f: a strict-ISO date/datetime string under a Date-compatible concept builds a DateContent+ # (routed through the concept resolver so a refining subclass is honored, like the YesNo arm).+ date_concept = get_native_concept(native_concept=NativeConceptCode.DATE)+ if concept_library.is_compatible(tested_concept=concept, wanted_concept=date_concept, strict=True):+ return cls.make_stuff(+ concept=concept,+ content=StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=content),+ name=name,+ code=code,+ )+ msg = (+ f"Trying to create a Stuff '{name}' in the inputs of your pipe, from a dict that should represent a StuffContentOrData "+ f"but the concept of name '{concept_ref}' is not compatible with native concept 'native.Text' or 'native.Date'"+ )+ raise StuffFactoryError(msg)++ # Case 2.1e: content is a bare date/datetime object (a TOML temporal literal used as envelope content)+ # → DateContent for a Date-compatible concept. isinstance(date) covers datetime (its subclass); a bare+ # time never reaches here — the inputs loader rejects it, and a time is not a date anyway.+ if isinstance(content, datetime.date):+ date_concept = get_native_concept(native_concept=NativeConceptCode.DATE)+ if concept_library.is_compatible(tested_concept=concept, wanted_concept=date_concept, strict=True):+ return cls.make_stuff(+ concept=concept,+ content=StuffContentFactory.make_stuff_content_from_concept_required(concept=concept, value=content),+ name=name,+ code=code,+ )msg = (f"Trying to create a Stuff '{name}' in the inputs of your pipe, from a dict that should represent a StuffContentOrData "- f"but the concept of name '{concept_ref}' is not compatible with native concept 'native.Text'"+ f"but the concept of name '{concept_ref}' is not compatible with native concept 'native.Date' (the content is a date/datetime)")raise StuffFactoryError(msg)diff --git a/pipelex/core/stuffs/yes_no_content.py b/pipelex/core/stuffs/yes_no_content.pynew file mode 100644index 000000000..0fa5ab11d--- /dev/null+++ b/pipelex/core/stuffs/yes_no_content.py@@ -0,0 +1,34 @@+import json++from pydantic import Field+from typing_extensions import override++from pipelex.core.stuffs.stuff_content import StuffContent+++class YesNoContent(StuffContent):+ # strict=True keeps the concept a genuine boolean: pydantic's default lax mode would coerce+ # "yes"/"true"/"1"/0/1 into a bool on the dict-content path (model_validate), silently bypassing+ # the no-cross-kind-coercion contract the scalar envelope arm enforces. Only a real bool is accepted.+ yes_no: bool = Field(description="Whether the answer is yes (true) or no (false).", strict=True)++ @property+ @override+ def short_desc(self) -> str:+ return f"a yes/no answer ({'yes' if self.yes_no else 'no'})"++ @override+ def rendered_plain(self) -> str:+ return "yes" if self.yes_no else "no"++ @override+ def rendered_html(self) -> str:+ return "yes" if self.yes_no else "no"++ @override+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:+ return "yes" if self.yes_no else "no"++ @override+ def rendered_json(self) -> str:+ return json.dumps({"yes_no": self.yes_no})diff --git a/pipelex/pipeline/execution_seams.py b/pipelex/pipeline/execution_seams.pyindex 2d1a400d0..94f302740 100644--- a/pipelex/pipeline/execution_seams.py+++ b/pipelex/pipeline/execution_seams.py@@ -169,6 +169,7 @@ async def prepare_pipe_job(dynamic_output_concept_ref: str | None = None,request_id: str | None = None,is_mock_usage: bool = False,+ inputs_base_dir: Path | None = None,) -> PipeJob:"""Build a :class:`PipeJob` for ``pipe`` against an already-open library.@@ -195,9 +196,14 @@ async def prepare_pipe_job(if isinstance(inputs, WorkingMemory):working_memory = inputselse:+ # Thread the pipe's declared inputs so each value is shaped top-down against the+ # signature (Smart Inputs). `pipe.inputs` is the method-boundary contract — the same+ # source the Optionals pass reads below — not the aggregated `needed_inputs()`.working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=inputs,+ input_specs=pipe.inputs,search_domain_codes=search_domain_codes,+ inputs_base_dir=inputs_base_dir,)# If mock inputs is enabled, generate mock data for missing required inputs.diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.pyindex f2b75fa6d..8caf32cf0 100644--- a/pipelex/pipeline/pipeline_run_setup.py+++ b/pipelex/pipeline/pipeline_run_setup.py@@ -1,3 +1,4 @@+from pathlib import Pathfrom typing import TYPE_CHECKINGfrom mthds.protocol.pipeline_inputs import PipelineInputs@@ -58,6 +59,7 @@ async def pipeline_run_setup(user_id: str | None = None,pipeline_run_id: str | None = None,request_id: str | None = None,+ inputs_base_dir: Path | None = None,) -> tuple[PipeJob, str, str]:"""Set up a pipeline for execution.@@ -129,6 +131,11 @@ async def pipeline_run_setup(``ErrorReport`` back to its originating request). Threaded onto:class:`pipelex.pipeline.job_metadata.JobMetadata.request_id` so itcrosses the Temporal serialization boundary intact.+ inputs_base_dir:+ Directory that bare *relative local* file paths in ``inputs`` resolve against (Smart+ Inputs D3) — the inputs file's parent when a CLI file-loaded the inputs. ``None`` for+ API/SDK callers (they pass absolute urls / storage uris). Only the shaper's file-ish /+ CSV arms consult it.Returns:-------@@ -278,6 +285,7 @@ async def pipeline_run_setup(output_multiplicity=output_multiplicity,dynamic_output_concept_ref=dynamic_output_concept_ref,request_id=request_id,+ inputs_base_dir=inputs_base_dir,)properties = {diff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.pyindex 48a37b032..b7a80d180 100644--- a/pipelex/pipeline/runner.py+++ b/pipelex/pipeline/runner.py@@ -117,6 +117,7 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):user_id: str | None = None,execution_config: PipelineExecutionConfig | None = None,pipe_run: PipeRunProtocol | None = None,+ inputs_base_dir: Path | None = None,):self.library_id = library_idself.library_dirs = library_dirs@@ -127,6 +128,9 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):self.user_id = user_idself.execution_config = execution_configself._pipe_run = pipe_run+ # Directory that bare relative local file paths in `inputs` resolve against (Smart Inputs+ # D3). Set by a CLI to the inputs file's parent; None for API/SDK callers (absolute urls).+ self.inputs_base_dir = inputs_base_dirself._running_tasks: dict[str, asyncio.Task[PipeOutput]] = {}@override@@ -222,6 +226,7 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):is_mock_usage=self.is_mock_usage,search_domain_codes=self.search_domain_codes,user_id=self.user_id,+ inputs_base_dir=self.inputs_base_dir,)effective_pipe_run = self._pipe_run or get_pipe_run()pipe_output = await effective_pipe_run.run(pipe_job, delivery_assignment=delivery_assignment)diff --git a/pipelex/tools/uri/uri_resolver.py b/pipelex/tools/uri/uri_resolver.pyindex ccbaca78c..86163e983 100644--- a/pipelex/tools/uri/uri_resolver.py+++ b/pipelex/tools/uri/uri_resolver.py@@ -55,6 +55,56 @@ def describe_uri(uri: str) -> str:return resolved_uri.kind.desc+def is_relative_local_path(uri: str) -> bool:+ """Check whether *uri* is a relative local file path.++ Uses :func:`resolve_uri` to classify the URI. Returns ``True`` only when+ the URI resolves to a :class:`ResolvedLocalPath` **and** the path is not+ absolute.++ Args:+ uri: The URI string to check.++ Returns:+ ``True`` if *uri* is a relative local path, ``False`` otherwise.+ """+ resolved = resolve_uri(uri)+ if not isinstance(resolved, ResolvedLocalPath):+ return False+ if "://" in resolved.path:+ # An unrecognized scheme (``s3://``, ``gs://``, …) slips through ``resolve_uri`` as a+ # ResolvedLocalPath but is NOT a local file path; do not treat it as relative+ # (that would let a caller mangle ``s3://bucket/x`` into ``<base_dir>/s3:/bucket/x`` and+ # defeat the downstream remote-url guards). Mirrors the same ``"://"`` stopgap in the CSV+ # input hook; both go away once ``resolve_uri`` classifies schemes (tools/uri follow-up).+ return False+ return not Path(resolved.path).is_absolute()+++def resolve_local_path_reference(uri: str, *, base_dir: Path | None) -> str:+ """Expand a leading ``~`` to the user's home, then resolve a still-relative local path against+ *base_dir* (D3).++ ``~/photo.jpg`` → ``<home>/photo.jpg`` (absolute — never joined onto *base_dir*); a genuine+ relative local path → ``<base_dir>/<path>`` when *base_dir* is given, else unchanged (the CWD+ contract); an absolute path or any remote/scheme URI → unchanged. Mirrors the CLI's expanduser of+ the inputs-file arg itself (``_inputs_file_loader``/``_run_core``/``stdin_resolver``), extended to+ the file-ish input *values* — the shaper's file/CSV arms and the CLI's url-key walk share it.++ Args:+ uri: The path/URL reference to resolve (a bare input value or a ``{"url": ...}`` value).+ base_dir: Directory that a still-relative local path resolves against; ``None`` leaves a+ relative path untouched (in-process / inline-JSON callers keep the CWD contract).++ Returns:+ The resolved reference string.+ """+ expanded = str(Path(uri).expanduser()) if uri.startswith("~") else uri+ if base_dir is not None and is_relative_local_path(expanded):+ return str(base_dir / expanded)+ return expanded++def resolve_uri(uri: str) -> ResolvedUri:"""Resolve a URI string to its typed representation.diff --git a/tests/e2e/pipelex/cli/test_date_inputs_run.py b/tests/e2e/pipelex/cli/test_date_inputs_run.pynew file mode 100644index 000000000..2ed734ae1--- /dev/null+++ b/tests/e2e/pipelex/cli/test_date_inputs_run.py@@ -0,0 +1,62 @@+"""E2E test for native Date pipeline inputs via the ``pipelex run`` CLI.++One ``gha_disabled`` subprocess check exercises the real binary: a dry run fed an+``inputs.toml`` whose value is a bare TOML offset-datetime literal must load the TOML,+convert the top-level temporal literal into a ``DateContent`` (offset preserved), infer+``native.Date`` from the class name, and complete.++The subprocess test inherits the ambient environment (it needs a working ``.pipelex``+config to boot) and runs with ``cwd`` set to a tmp dir so on-disk side effects stay+out of the source tree.+"""++from __future__ import annotations++import os+import shutil+import subprocess # noqa: S404 — invokes the real pipelex binary for E2E coverage+from pathlib import Path++import pytest++REPO_ROOT = Path(__file__).resolve().parents[4]+PIPELEX_BIN = REPO_ROOT / ".venv" / "bin" / "pipelex"+BUNDLE_SRC = REPO_ROOT / "tests" / "e2e" / "pipelex" / "pipes" / "date" / "date_departure"++# A bare top-level TOML offset-datetime literal — the loader converts it into a native Date input.+INPUTS_TOML = "departure = 2026-07-07T15:40:00+02:00\n"+++class TestDateInputsRun:+ @pytest.mark.gha_disabled+ def test_date_toml_literal_input_dry_run(self, tmp_path: Path) -> None:+ staged = tmp_path / "date_departure"+ shutil.copytree(BUNDLE_SRC, staged)+ inputs_toml = staged / "inputs.toml"+ inputs_toml.write_text(INPUTS_TOML, encoding="utf-8")++ result = subprocess.run( # noqa: S603+ [+ str(PIPELEX_BIN),+ "run",+ "pipe",+ "describe_departure",+ "-L",+ str(staged),+ "--inputs",+ str(inputs_toml),+ "--dry-run",+ "--no-save-working-memory",+ "--no-save-main-stuff",+ "--no-graph",+ ],+ cwd=str(tmp_path),+ env=os.environ.copy(),+ capture_output=True,+ text=True,+ check=False,+ timeout=180,+ )+ assert result.returncode == 0, f"Date-TOML-literal-inputs dry run must succeed.\nstdout={result.stdout!r}\nstderr={result.stderr!r}"+ assert "Loaded inputs from" in result.stdout+ assert "inputs.toml" in result.stdoutdiff --git a/tests/e2e/pipelex/cli/test_toml_inputs_build.py b/tests/e2e/pipelex/cli/test_toml_inputs_build.pyindex 4006bf5d1..06f02020f 100644--- a/tests/e2e/pipelex/cli/test_toml_inputs_build.py+++ b/tests/e2e/pipelex/cli/test_toml_inputs_build.py@@ -1,16 +1,20 @@"""E2E test for TOML inputs-template generation via the ``pipelex build inputs`` CLI.-One ``gha_disabled`` subprocess check exercises the real binary end to end: ``build-inputs bundle --format toml`` must write an ``inputs.toml`` next to the bundle (the-TOML default filename), and that generated template must feed a ``run --dry-run``-straight back — the full generate→load round trip across both CLI surfaces. The-staged bundle is the same ``csv_demo`` fixture used by the CSV e2e tests; its-``inputs.json`` is removed from the staged copy so the follow-up run cannot fall back-to the JSON twin.--The subprocess calls inherit the ambient environment (they need a working-``.pipelex`` config to boot) and run with ``cwd`` set to a tmp dir so on-disk side-effects stay out of the source tree.+Two ``gha_disabled`` subprocess checks exercise the real binary end to end. ``build inputs bundle+--format toml`` writes an ``inputs.toml`` next to the bundle (the TOML default filename), and that+generated template must feed a ``run --dry-run`` straight back — the full generate→load round trip+across both CLI surfaces:++- **Default (light, D11).** The template is the light signature-driven shape — bare values, a+ ``# concept: ...`` comment per key, structured values as inline tables — and it dry-runs.+- **``--explicit``.** The ceremonial ``{concept, content}`` envelope form is restored (all-tables+ layout), and it dry-runs too.++The staged bundle is the same ``csv_demo`` fixture used by the CSV e2e tests; its ``inputs.json`` is+removed from the staged copy so the follow-up run cannot fall back to the JSON twin.++The subprocess calls inherit the ambient environment (they need a working ``.pipelex`` config to+boot) and run with ``cwd`` set to a tmp dir so on-disk side effects stay out of the source tree."""from __future__ import annotations@@ -30,12 +34,15 @@ BUNDLE_SRC = REPO_ROOT / "tests" / "integration" / "pipelex" / "csv" / "csv_democlass TestTomlInputsBuild:- @pytest.mark.gha_disabled- def test_build_inputs_toml_then_dry_run(self, tmp_path: Path) -> None:+ def _stage(self, tmp_path: Path) -> Path:+ """Copy the csv_demo bundle to a tmp dir and drop its inputs.json (no JSON fallback)."""staged = tmp_path / "csv_demo"shutil.copytree(BUNDLE_SRC, staged)(staged / "inputs.json").unlink()+ return staged+ def _build(self, staged: Path, tmp_path: Path, *, extra_args: list[str]) -> None:+ """Run ``build inputs bundle --format toml`` (plus extra args) on the staged bundle."""build_result = subprocess.run( # noqa: S603[str(PIPELEX_BIN),@@ -47,6 +54,7 @@ class TestTomlInputsBuild:"summarize_people","--format","toml",+ *extra_args,],cwd=str(tmp_path),env=os.environ.copy(),@@ -57,15 +65,8 @@ class TestTomlInputsBuild:)assert build_result.returncode == 0, f"TOML template generation must succeed.\nstdout={build_result.stdout!r}\nstderr={build_result.stderr!r}"- inputs_toml = staged / "inputs.toml"- assert inputs_toml.is_file(), "The TOML default filename must be inputs.toml next to the bundle"- template = tomli.loads(inputs_toml.read_text(encoding="utf-8"))- assert template["people"]["concept"] == "csv_demo.Person"- person_items = template["people"]["content"]- assert isinstance(person_items, list), "Person[] multiplicity must wrap content in a list"- first_person = cast("dict[str, Any]", person_items[0])- assert {"name", "job", "country", "birth_year"} <= set(first_person.keys())-+ def _dry_run(self, staged: Path, tmp_path: Path, inputs_toml: Path) -> None:+ """Feed the generated inputs.toml straight into ``run --dry-run`` — the round trip."""run_result = subprocess.run( # noqa: S603[str(PIPELEX_BIN),@@ -92,3 +93,40 @@ class TestTomlInputsBuild:f"Dry run fed the generated inputs.toml must succeed.\nstdout={run_result.stdout!r}\nstderr={run_result.stderr!r}")assert "inputs.toml" in run_result.stdout++ @pytest.mark.gha_disabled+ def test_build_inputs_toml_light_default_then_dry_run(self, tmp_path: Path) -> None:+ """The default TOML template is the light shape (bare values + concept comment) and it dry-runs."""+ staged = self._stage(tmp_path)+ self._build(staged, tmp_path, extra_args=[])++ inputs_toml = staged / "inputs.toml"+ assert inputs_toml.is_file(), "The TOML default filename must be inputs.toml next to the bundle"+ raw = inputs_toml.read_text(encoding="utf-8")+ assert "# concept: csv_demo.Person[]" in raw, "Light TOML must carry the declared concept as a comment"++ template = tomli.loads(raw)+ person_items = template["people"]+ assert isinstance(person_items, list), "Person[] light form must be a bare list of person dicts"+ first_person = cast("dict[str, Any]", person_items[0])+ assert "concept" not in first_person, "The light form must not carry the envelope 'concept' key"+ assert {"name", "job", "country", "birth_year"} <= set(first_person.keys())++ self._dry_run(staged, tmp_path, inputs_toml)++ @pytest.mark.gha_disabled+ def test_build_inputs_toml_explicit_then_dry_run(self, tmp_path: Path) -> None:+ """--explicit restores the ceremonial envelope template, and it dry-runs too."""+ staged = self._stage(tmp_path)+ self._build(staged, tmp_path, extra_args=["--explicit"])++ inputs_toml = staged / "inputs.toml"+ assert inputs_toml.is_file()+ template = tomli.loads(inputs_toml.read_text(encoding="utf-8"))+ assert template["people"]["concept"] == "csv_demo.Person"+ person_items = template["people"]["content"]+ assert isinstance(person_items, list), "Person[] multiplicity must wrap content in a list"+ first_person = cast("dict[str, Any]", person_items[0])+ assert {"name", "job", "country", "birth_year"} <= set(first_person.keys())++ self._dry_run(staged, tmp_path, inputs_toml)diff --git a/tests/e2e/pipelex/cli/test_yes_no_inputs_run.py b/tests/e2e/pipelex/cli/test_yes_no_inputs_run.pynew file mode 100644index 000000000..ce6f89e3e--- /dev/null+++ b/tests/e2e/pipelex/cli/test_yes_no_inputs_run.py@@ -0,0 +1,64 @@+"""E2E test for a native YesNo pipeline input via the ``pipelex run`` CLI.++One ``gha_disabled`` subprocess check exercises the real binary: a dry run fed an+``inputs.toml`` whose value is the envelope form for a YesNo input+(``{concept = "YesNo", content = true}``) must load the TOML, shape the bool into+``YesNoContent`` through the factory's YesNo arm, and complete.++The subprocess test inherits the ambient environment (it needs a working ``.pipelex``+config to boot) and runs with ``cwd`` set to a tmp dir so on-disk side effects stay+out of the source tree.+"""++from __future__ import annotations++import os+import shutil+import subprocess # noqa: S404 — invokes the real pipelex binary for E2E coverage+from pathlib import Path++import pytest++REPO_ROOT = Path(__file__).resolve().parents[4]+PIPELEX_BIN = REPO_ROOT / ".venv" / "bin" / "pipelex"+BUNDLE_SRC = REPO_ROOT / "tests" / "e2e" / "pipelex" / "pipes" / "yes_no" / "yes_no_judgment"++INPUTS_TOML = """[verdict]+concept = "YesNo"+content = true+"""+++class TestYesNoInputsRun:+ @pytest.mark.gha_disabled+ def test_yes_no_envelope_input_dry_run(self, tmp_path: Path) -> None:+ staged = tmp_path / "yes_no_judgment"+ shutil.copytree(BUNDLE_SRC, staged)+ inputs_toml = staged / "inputs.toml"+ inputs_toml.write_text(INPUTS_TOML, encoding="utf-8")++ result = subprocess.run( # noqa: S603+ [+ str(PIPELEX_BIN),+ "run",+ "pipe",+ "explain_verdict",+ "-L",+ str(staged),+ "--inputs",+ str(inputs_toml),+ "--dry-run",+ "--no-save-working-memory",+ "--no-save-main-stuff",+ "--no-graph",+ ],+ cwd=str(tmp_path),+ env=os.environ.copy(),+ capture_output=True,+ text=True,+ check=False,+ timeout=180,+ )+ assert result.returncode == 0, f"YesNo-envelope-inputs dry run must succeed.\nstdout={result.stdout!r}\nstderr={result.stderr!r}"+ assert "Loaded inputs from" in result.stdout+ assert "inputs.toml" in result.stdoutdiff --git a/tests/e2e/pipelex/pipes/date/date_departure/date_departure.mthds b/tests/e2e/pipelex/pipes/date/date_departure/date_departure.mthdsnew file mode 100644index 000000000..b27f81e81--- /dev/null+++ b/tests/e2e/pipelex/pipes/date/date_departure/date_departure.mthds@@ -0,0 +1,23 @@+domain = "date_demo"+description = "Native Date as a pipeline input fed by TOML date/datetime literals"+main_pipe = "describe_departure"++[pipe.describe_departure]+type = "PipeLLM"+description = "Writes a one-line note about a departure date"+inputs = { departure = "Date" }+output = "Text"+prompt = """+The scheduled departure is: $departure++Write one sentence noting the departure.+"""++[pipe.extract_departure]+type = "PipeLLM"+description = "Extracts the departure date from a ticket"+inputs = { ticket = "Text" }+output = "Date"+prompt = """+Extract the scheduled departure from this ticket: $ticket+"""diff --git a/tests/e2e/pipelex/pipes/date/test_date_dry_run.py b/tests/e2e/pipelex/pipes/date/test_date_dry_run.pynew file mode 100644index 000000000..c54e21430--- /dev/null+++ b/tests/e2e/pipelex/pipes/date/test_date_dry_run.py@@ -0,0 +1,45 @@+"""Dry-run coverage for native Date from a `.mthds` file.++Two shapes, both keyless (dry mode mocks only the cogt leaf and rides the live render path):+- Date as a PipeLLM output — the object path mocks a `DateContent` via polyfactory (which+ synthesizes `date`/`time` natively).+- Date as a pipeline input (fed as a `DateContent`) — it renders inline in the downstream prompt.+"""++import datetime+from pathlib import Path++import pytest++from pipelex.core.stuffs.date_content import DateContent+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipeline.pipeline_response import RunState+from pipelex.pipeline.runner import PipelexMTHDSProtocol++_FIXTURE_DIR = Path(__file__).parent / "date_departure"++[email protected](loop_scope="class")+class TestDateDryRun:+ async def test_dry_run_date_output_produces_mock_date(self):+ """A PipeLLM whose output is Date completes in dry mode with a mocked DateContent."""+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)++ response = await runner.execute(pipe_code="extract_departure", inputs={"ticket": "Flight AF123, departure 7 Jul 2026 15:40"})++ assert response.state == RunState.COMPLETED+ assert response.pipe_output.main_stuff.is_date+ assert isinstance(response.pipe_output.main_stuff_as_date.date, datetime.date)++ async def test_dry_run_date_input_flows_through(self):+ """A Date pipeline input renders into the downstream prompt and the run completes."""+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)++ departure = DateContent(date=datetime.date(2026, 7, 7), time=datetime.time(15, 40, tzinfo=datetime.timezone(datetime.timedelta(hours=2))))+ response = await runner.execute(pipe_code="describe_departure", inputs={"departure": departure})++ assert response.state == RunState.COMPLETED+ departure_stuff = response.pipe_output.working_memory.get_stuff("departure")+ assert departure_stuff.is_date+ assert departure_stuff.as_date.time is not None+ assert response.pipe_output.main_stuff.as_text.textdiff --git a/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/a.pdf b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/a.pdfnew file mode 100644index 000000000..17f057506--- /dev/null+++ b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/a.pdf@@ -0,0 +1,5 @@+%PDF-1.4+1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj+2 0 obj<</Type/Pages/Kids[]/Count 0>>endobj+trailer<</Root 1 0 R>>+%%EOFdiff --git a/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/b.pdf b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/b.pdfnew file mode 100644index 000000000..17f057506--- /dev/null+++ b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/b.pdf@@ -0,0 +1,5 @@+%PDF-1.4+1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj+2 0 obj<</Type/Pages/Kids[]/Count 0>>endobj+trailer<</Root 1 0 R>>+%%EOFdiff --git a/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/people.csv b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/people.csvnew file mode 100644index 000000000..2e10eec6c--- /dev/null+++ b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/people.csv@@ -0,0 +1,3 @@+name,job+Ada Lovelace,Mathematician+Grace Hopper,Computer Scientistdiff --git a/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/photo.jpg b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/photo.jpgnew file mode 100644index 000000000..f5eb6b971Binary files /dev/null and b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/photo.jpg differdiff --git a/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/smart_inputs_files.mthds b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/smart_inputs_files.mthdsnew file mode 100644index 000000000..47af7be33--- /dev/null+++ b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_files/smart_inputs_files.mthds@@ -0,0 +1,35 @@+domain = "smart_inputs_files_demo"+description = "Bare file-path and CSV inputs shaped top-down against the declared signature (Smart Inputs, Phase 3)"+main_pipe = "review_case"++[concept.Photo]+description = "A photo attached to the case"+refines = "Image"++[concept.Exhibit]+description = "A supporting exhibit document"+refines = "Document"++[concept.Person]+description = "A person involved in the case"++[concept.Person.structure]+name = { type = "text", description = "The person's name", required = true }+job = { type = "text", description = "The person's job", required = true }++[pipe.review_case]+type = "PipeLLM"+description = "Review a case given a photo, exhibit documents and the people involved"+inputs = { photo = "Photo", exhibits = "Exhibit[]", people = "Person[]" }+output = "Text"+prompt = """+Photo: $photo++Exhibits:+$exhibits++People involved:+@people++Write a one-line review of the case.+"""diff --git a/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_triage/smart_inputs_triage.mthds b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_triage/smart_inputs_triage.mthdsnew file mode 100644index 000000000..5882dd033--- /dev/null+++ b/tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_triage/smart_inputs_triage.mthds@@ -0,0 +1,37 @@+domain = "smart_inputs_demo"+description = "Bare caller values shaped top-down against the declared signature (Smart Inputs, Phase 2)"+main_pipe = "triage_case"++[concept.Question]+description = "A question posed to the triage desk"+refines = "Text"++[concept.Priority]+description = "A numeric priority score"+refines = "Number"++[concept.Tag]+description = "A short routing label"+refines = "Text"++[concept.Invoice]+description = "An invoice attached to the case"++[concept.Invoice.structure]+invoice_number = { type = "text", description = "The invoice number", required = true }+amount = { type = "number", description = "The invoice amount", required = true }++[pipe.triage_case]+type = "PipeLLM"+description = "Triage a case given a bare question, priority, invoice and tags"+inputs = { question = "Question", priority = "Priority", invoice = "Invoice", tags = "Tag[]" }+output = "Text"+prompt = """+Question: $question+Priority: $priority+Invoice number: {{ invoice.invoice_number }} for {{ invoice.amount }}+Tags:+@tags++Write a one-line triage summary.+"""diff --git a/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_dry_run.py b/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_dry_run.pynew file mode 100644index 000000000..8b414fabc--- /dev/null+++ b/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_dry_run.py@@ -0,0 +1,125 @@+"""End-to-end coverage for signature-driven input shaping (Smart Inputs, Phase 2).++The seam is now live: a caller's *bare* values are interpreted top-down against the entry+pipe's declared signature. A bare string becomes the declared `Question` (not `native.Text`),+a bare number the declared `Priority`, a bare dict the declared `Invoice`, a list of bare+strings a `Tag[]`. The two failure modes the phase turns on — a wrong scalar kind (D4) and an+undeclared input name (D8) — surface as loud shaping errors.++All keyless (dry mode mocks only the cogt leaf and rides the live render + shaping path). The+`inputs` dicts are typed `dict[str, Any]` on purpose: the runtime admits the bare scalars the+narrow `PipelineInputs` alias does not (D10 widening is release-gated), which is exactly the+shape a real caller sends.+"""++from pathlib import Path+from typing import TYPE_CHECKING, Any, cast++import pytest++from pipelex.core.memory.exceptions import UnknownInputNameError, WrongScalarKindError+from pipelex.core.stuffs.list_content import ListContent+from pipelex.core.stuffs.number_content import NumberContent+from pipelex.core.stuffs.structured_content import StructuredContent+from pipelex.core.stuffs.text_content import TextContent+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipeline.pipeline_response import RunState+from pipelex.pipeline.runner import PipelexMTHDSProtocol++if TYPE_CHECKING:+ from pipelex.core.stuffs.stuff_content import StuffContent++_FIXTURE_DIR = Path(__file__).parent / "smart_inputs_triage"++[email protected](loop_scope="class")+class TestSmartInputsDryRun:+ async def test_bare_values_shape_to_declared_concepts(self):+ """Bare string/number/dict/list inputs each carry the DECLARED concept, not native.Text."""+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)++ inputs: dict[str, Any] = {+ "question": "What are the late fees?",+ "priority": 3,+ "invoice": {"invoice_number": "INV-042", "amount": 1250.0},+ "tags": ["urgent", "billing"],+ }+ response = await runner.execute(pipe_code="triage_case", inputs=inputs)++ assert response.state == RunState.COMPLETED+ working_memory = response.pipe_output.working_memory++ question_stuff = working_memory.get_stuff("question")+ assert question_stuff.concept.concept_ref == "smart_inputs_demo.Question"+ assert isinstance(question_stuff.content, TextContent)+ assert question_stuff.content.text == "What are the late fees?"++ priority_stuff = working_memory.get_stuff("priority")+ assert priority_stuff.concept.concept_ref == "smart_inputs_demo.Priority"+ assert isinstance(priority_stuff.content, NumberContent)+ assert priority_stuff.content.number == 3++ invoice_stuff = working_memory.get_stuff("invoice")+ assert invoice_stuff.concept.concept_ref == "smart_inputs_demo.Invoice"+ assert isinstance(invoice_stuff.content, StructuredContent)+ assert invoice_stuff.content.model_dump() == {"invoice_number": "INV-042", "amount": 1250.0}++ tags_stuff = working_memory.get_stuff("tags")+ assert tags_stuff.concept.concept_ref == "smart_inputs_demo.Tag"+ tags_content: StuffContent = tags_stuff.content+ assert isinstance(tags_content, ListContent)+ tags_list = cast("ListContent[StuffContent]", tags_content)+ tag_items = [item.text for item in tags_list.items if isinstance(item, TextContent)]+ assert tag_items == ["urgent", "billing"]++ async def test_empty_list_input_builds_empty_list_content(self):+ """An empty list for a declared `Tag[]` input is legal: an empty ListContent, run completes."""+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)++ inputs: dict[str, Any] = {+ "question": "Any blockers?",+ "priority": 1,+ "invoice": {"invoice_number": "INV-000", "amount": 0.0},+ "tags": [],+ }+ response = await runner.execute(pipe_code="triage_case", inputs=inputs)++ assert response.state == RunState.COMPLETED+ tags_stuff = response.pipe_output.working_memory.get_stuff("tags")+ assert tags_stuff.concept.concept_ref == "smart_inputs_demo.Tag"+ tags_content: StuffContent = tags_stuff.content+ assert isinstance(tags_content, ListContent)+ tags_list = cast("ListContent[StuffContent]", tags_content)+ assert tags_list.items == []++ async def test_wrong_scalar_kind_raises_shaping_error(self):+ """A string for the Number-refining `priority` is a loud D4 shaping error naming the input."""+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)++ inputs: dict[str, Any] = {+ "question": "What are the late fees?",+ "priority": "high",+ "invoice": {"invoice_number": "INV-042", "amount": 1250.0},+ "tags": ["urgent"],+ }+ with pytest.raises(WrongScalarKindError, match="expects a number") as exc_info:+ await runner.execute(pipe_code="triage_case", inputs=inputs)+ message = str(exc_info.value)+ assert "'priority'" in message+ assert "Expected shape:" in message++ async def test_unknown_input_name_raises(self):+ """An undeclared input name (a typo) is a hard D8 error listing the declared names."""+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)++ inputs: dict[str, Any] = {+ "quesion": "typo'd input name",+ "priority": 3,+ "invoice": {"invoice_number": "INV-042", "amount": 1250.0},+ "tags": ["urgent"],+ }+ with pytest.raises(UnknownInputNameError, match="not declared") as exc_info:+ await runner.execute(pipe_code="triage_case", inputs=inputs)+ message = str(exc_info.value)+ assert "'quesion'" in message+ assert "'question'" in messagediff --git a/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_files_dry_run.py b/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_files_dry_run.pynew file mode 100644index 000000000..7dd5a1d97--- /dev/null+++ b/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_files_dry_run.py@@ -0,0 +1,118 @@+"""End-to-end coverage for file-ish Smart Inputs (Phase 3, D3 + D11).++Through the real runner (dry mode), a bare relative path for a declared `Photo` (Image-refining)+input resolves against `inputs_base_dir` — the seam value the CLI derives from the inputs file's+parent directory — and builds an `ImageContent`; a list of bare paths shapes element-wise into+`ListContent[Exhibit]`; and a bare CSV path under a declared `Person[]` reads the table into+`ListContent[Person]` with no envelope. The `{"url": ...}` dict form (what the CLI's url-key walk+delivers: an absolute url) lands on the same resolved result as the bare form.+"""++from pathlib import Path+from typing import TYPE_CHECKING, Any, cast++import pytest++from pipelex.config import get_config+from pipelex.core.stuffs.document_content import DocumentContent+from pipelex.core.stuffs.image_content import ImageContent+from pipelex.core.stuffs.list_content import ListContent+from pipelex.core.stuffs.structured_content import StructuredContent+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipeline.pipeline_response import RunState+from pipelex.pipeline.runner import PipelexMTHDSProtocol++if TYPE_CHECKING:+ from pipelex.core.stuffs.stuff_content import StuffContent+ from pipelex.system.configuration.configs import PipelineExecutionConfig++_FIXTURE_DIR = Path(__file__).parent / "smart_inputs_files"+++def _no_normalize_config() -> "PipelineExecutionConfig":+ """Execution config with data-url→storage normalization off, so the shaper's D3-resolved local+ path stays a filesystem path (normalization would otherwise rewrite it to a pipelex-storage URI+ — a legitimate downstream step, but it would obscure exactly the resolution this test pins).+ """+ return get_config().pipelex.pipeline_execution_config.model_copy(update={"is_normalize_data_urls_to_storage": False})++[email protected](loop_scope="class")+class TestSmartInputsFilesDryRun:+ async def test_bare_paths_and_csv_resolve_and_shape(self):+ """Bare relative file paths resolve against inputs_base_dir; a bare CSV reads into Person[]."""+ runner = PipelexMTHDSProtocol(+ library_dirs=[str(_FIXTURE_DIR)],+ pipe_run_mode=PipeRunMode.DRY,+ inputs_base_dir=_FIXTURE_DIR,+ execution_config=_no_normalize_config(),+ )+ inputs: dict[str, Any] = {+ "photo": "photo.jpg",+ "exhibits": ["a.pdf", "b.pdf"],+ "people": "people.csv",+ }+ response = await runner.execute(pipe_code="review_case", inputs=inputs)++ assert response.state == RunState.COMPLETED+ working_memory = response.pipe_output.working_memory++ photo_stuff = working_memory.get_stuff("photo")+ assert photo_stuff.concept.concept_ref == "smart_inputs_files_demo.Photo"+ assert isinstance(photo_stuff.content, ImageContent)+ assert photo_stuff.content.url == str(_FIXTURE_DIR / "photo.jpg")++ exhibits_stuff = working_memory.get_stuff("exhibits")+ assert exhibits_stuff.concept.concept_ref == "smart_inputs_files_demo.Exhibit"+ exhibits_content: StuffContent = exhibits_stuff.content+ assert isinstance(exhibits_content, ListContent)+ exhibit_urls = [item.url for item in cast("ListContent[StuffContent]", exhibits_content).items if isinstance(item, DocumentContent)]+ assert exhibit_urls == [str(_FIXTURE_DIR / "a.pdf"), str(_FIXTURE_DIR / "b.pdf")]++ people_stuff = working_memory.get_stuff("people")+ assert people_stuff.concept.concept_ref == "smart_inputs_files_demo.Person"+ people_content: StuffContent = people_stuff.content+ assert isinstance(people_content, ListContent)+ people_items = cast("ListContent[StuffContent]", people_content).items+ assert len(people_items) == 2+ assert all(isinstance(item, StructuredContent) for item in people_items)+ assert [item.model_dump() for item in people_items] == [+ {"name": "Ada Lovelace", "job": "Mathematician"},+ {"name": "Grace Hopper", "job": "Computer Scientist"},+ ]++ async def test_url_dict_form_matches_bare_form(self):+ """The {"url": <absolute>} dict form (post CLI url-key walk) equals the bare-path result."""+ runner = PipelexMTHDSProtocol(+ library_dirs=[str(_FIXTURE_DIR)],+ pipe_run_mode=PipeRunMode.DRY,+ inputs_base_dir=_FIXTURE_DIR,+ execution_config=_no_normalize_config(),+ )+ inputs: dict[str, Any] = {+ "photo": {"url": str(_FIXTURE_DIR / "photo.jpg")},+ "exhibits": ["a.pdf"],+ "people": {"url": str(_FIXTURE_DIR / "people.csv")},+ }+ response = await runner.execute(pipe_code="review_case", inputs=inputs)++ assert response.state == RunState.COMPLETED+ working_memory = response.pipe_output.working_memory++ photo_stuff = working_memory.get_stuff("photo")+ assert photo_stuff.concept.concept_ref == "smart_inputs_files_demo.Photo"+ assert isinstance(photo_stuff.content, ImageContent)+ assert photo_stuff.content.url == str(_FIXTURE_DIR / "photo.jpg")++ exhibits_stuff = working_memory.get_stuff("exhibits")+ assert exhibits_stuff.concept.concept_ref == "smart_inputs_files_demo.Exhibit"+ exhibits_content: StuffContent = exhibits_stuff.content+ assert isinstance(exhibits_content, ListContent)+ exhibit_urls = [item.url for item in cast("ListContent[StuffContent]", exhibits_content).items if isinstance(item, DocumentContent)]+ assert exhibit_urls == [str(_FIXTURE_DIR / "a.pdf")]++ people_stuff = working_memory.get_stuff("people")+ assert people_stuff.concept.concept_ref == "smart_inputs_files_demo.Person"+ people_content: StuffContent = people_stuff.content+ assert isinstance(people_content, ListContent)+ assert len(cast("ListContent[StuffContent]", people_content).items) == 2diff --git a/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_light_roundtrip.py b/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_light_roundtrip.pynew file mode 100644index 000000000..8d5a93037--- /dev/null+++ b/tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_light_roundtrip.py@@ -0,0 +1,64 @@+"""Round-trip: a light default JSON template generated by ``build inputs`` feeds ``run --dry-run``.++The D11 flip is only useful if the light template it produces is actually runnable — the bug the+Date ``/review`` caught was a template that would not ``run``. Here the light template is generated+from the entry pipe's signature (``render_inputs`` with the light default), then fed straight into a+dry run of that same pipe. It must complete, and every bare value must shape to its declared concept+just as a hand-written light inputs file would.++The TOML twin of this round trip (through the real binary) lives in+``tests/e2e/pipelex/cli/test_toml_inputs_build.py``.+"""++from __future__ import annotations++import json+from pathlib import Path+from typing import TYPE_CHECKING, Any++import pytest++from pipelex.core.pipes.inputs.input_renderer import render_inputs+from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe, set_current_library+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipeline.pipeline_response import RunState+from pipelex.pipeline.runner import PipelexMTHDSProtocol+from pipelex.pipeline.validate_bundle import validate_bundle++if TYPE_CHECKING:+ from collections.abc import Callable++_FIXTURE_DIR = Path(__file__).parent / "smart_inputs_triage"+_BUNDLE = _FIXTURE_DIR / "smart_inputs_triage.mthds"+++def _teardown_validation_library(outer_library_id: str) -> None:+ validation_library_id = get_current_library_id_or_none()+ if validation_library_id is not None and validation_library_id != outer_library_id:+ set_current_library(library_id=outer_library_id)+ get_library_manager().teardown(library_id=validation_library_id)+ clear_current_library()++[email protected](loop_scope="class")+class TestSmartInputsLightRoundTrip:+ async def test_generated_light_template_dry_runs(self, load_empty_library: Callable[[], str]) -> None:+ """Render the light default template, then dry-run the pipe with it — it completes and shapes correctly."""+ outer_library_id = load_empty_library()+ try:+ await validate_bundle(mthds_file_path=_BUNDLE)+ the_pipe = get_required_pipe(pipe_code="smart_inputs_demo.triage_case")+ light_inputs: dict[str, Any] = json.loads(render_inputs(the_pipe))+ finally:+ _teardown_validation_library(outer_library_id)++ # A fresh runner loads its own library from the fixture dir and shapes the generated values.+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)+ response = await runner.execute(pipe_code="triage_case", inputs=light_inputs)++ assert response.state == RunState.COMPLETED+ working_memory = response.pipe_output.working_memory+ assert working_memory.get_stuff("question").concept.concept_ref == "smart_inputs_demo.Question"+ assert working_memory.get_stuff("priority").concept.concept_ref == "smart_inputs_demo.Priority"+ assert working_memory.get_stuff("invoice").concept.concept_ref == "smart_inputs_demo.Invoice"+ assert working_memory.get_stuff("tags").concept.concept_ref == "smart_inputs_demo.Tag"diff --git a/tests/e2e/pipelex/pipes/yes_no/test_yes_no_dry_run.py b/tests/e2e/pipelex/pipes/yes_no/test_yes_no_dry_run.pynew file mode 100644index 000000000..4850a184a--- /dev/null+++ b/tests/e2e/pipelex/pipes/yes_no/test_yes_no_dry_run.py@@ -0,0 +1,44 @@+"""Dry-run coverage for native YesNo from a `.mthds` file.++Two shapes, both keyless (dry mode mocks only the cogt leaf and rides the live render path):+- YesNo as a PipeLLM output — the object path mocks a `YesNoContent` via polyfactory.+- YesNo as a pipeline input in the envelope form (`{"concept": "YesNo", "content": bool}`) — the+ bool flows through the factory's YesNo arm and renders inline in the downstream prompt.+"""++from pathlib import Path++import pytest++from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipeline.pipeline_response import RunState+from pipelex.pipeline.runner import PipelexMTHDSProtocol++_FIXTURE_DIR = Path(__file__).parent / "yes_no_judgment"++[email protected](loop_scope="class")+class TestYesNoDryRun:+ async def test_dry_run_yes_no_output_produces_mock_verdict(self):+ """A PipeLLM whose output is YesNo completes in dry mode with a mocked YesNoContent verdict."""+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)++ response = await runner.execute(pipe_code="judge_is_urgent", inputs={"message": "The server is on fire"})++ assert response.state == RunState.COMPLETED+ assert response.pipe_output.main_stuff.is_yes_no+ # The mocked value is a genuine bool.+ assert isinstance(response.pipe_output.main_stuff_as_yes_no.yes_no, bool)++ async def test_dry_run_yes_no_envelope_input_flows_through(self):+ """A YesNo pipeline input in the envelope form is shaped into YesNoContent and rides into the render context."""+ runner = PipelexMTHDSProtocol(library_dirs=[str(_FIXTURE_DIR)], pipe_run_mode=PipeRunMode.DRY)++ response = await runner.execute(pipe_code="explain_verdict", inputs={"verdict": {"concept": "YesNo", "content": True}})++ assert response.state == RunState.COMPLETED+ verdict_stuff = response.pipe_output.working_memory.get_stuff("verdict")+ assert verdict_stuff.is_yes_no+ assert verdict_stuff.as_yes_no.yes_no is True+ # The downstream Text output was produced (the guarded render completed).+ assert response.pipe_output.main_stuff.as_text.textdiff --git a/tests/e2e/pipelex/pipes/yes_no/yes_no_judgment/yes_no_judgment.mthds b/tests/e2e/pipelex/pipes/yes_no/yes_no_judgment/yes_no_judgment.mthdsnew file mode 100644index 000000000..5085946ec--- /dev/null+++ b/tests/e2e/pipelex/pipes/yes_no/yes_no_judgment/yes_no_judgment.mthds@@ -0,0 +1,25 @@+domain = "yes_no_demo"+description = "Native YesNo as a PipeLLM output (a judgment) and as a pipeline input"+main_pipe = "judge_is_urgent"++[pipe.judge_is_urgent]+type = "PipeLLM"+description = "Decides whether a message is urgent, answering yes or no"+inputs = { message = "Text" }+output = "YesNo"+prompt = """+Is the following message urgent? Answer yes or no.++$message+"""++[pipe.explain_verdict]+type = "PipeLLM"+description = "Writes a one-line justification for a yes/no verdict"+inputs = { verdict = "YesNo" }+output = "Text"+prompt = """+The verdict is: $verdict++Explain in one sentence why that verdict makes sense.+"""diff --git a/tests/integration/pipelex/cli/agent_cli/test_run_error_chain.py b/tests/integration/pipelex/cli/agent_cli/test_run_error_chain.pyindex 55e7d0ae7..cc81b5837 100644--- a/tests/integration/pipelex/cli/agent_cli/test_run_error_chain.py+++ b/tests/integration/pipelex/cli/agent_cli/test_run_error_chain.py@@ -23,6 +23,7 @@ from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.pipe_cmd import run_pipe_cmd+from pipelex.cli.agent_cli.commands.run.stdin_resolver import ParsedCliInputsfrom pipelex.cogt.content_generation.content_generator import ContentGeneratorfrom pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionErrorfrom pipelex.tools.log.log_levels import LogLevel@@ -47,7 +48,7 @@ class TestRunErrorChain:mocker.patch(f"{RUN_PIPE_MODULE}.make_pipelex_for_agent_cli")mocker.patch(f"{RUN_PIPE_MODULE}.Pipelex.teardown_if_needed")mocker.patch(f"{RUN_PIPE_MODULE}.resolve_pipe_from_exports", return_value=[])- mocker.patch(f"{RUN_PIPE_MODULE}.parse_cli_inputs", return_value=None)+ mocker.patch(f"{RUN_PIPE_MODULE}.parse_cli_inputs", return_value=ParsedCliInputs(pipeline_inputs=None, inputs_base_dir=None))transient_error = LLMCompletionError(WORKER_ERROR_MESSAGE, error_category=InferenceErrorCategory.TRANSIENT)# model_handle / backend_name are declared on CogtError; a real worker fills them atdiff --git a/tests/integration/pipelex/core/memory/test_working_memory_factory.py b/tests/integration/pipelex/core/memory/test_working_memory_factory.pyindex f39fade81..a6222dc47 100644--- a/tests/integration/pipelex/core/memory/test_working_memory_factory.py+++ b/tests/integration/pipelex/core/memory/test_working_memory_factory.py@@ -1,11 +1,15 @@-from typing import TYPE_CHECKING, Callable+from typing import TYPE_CHECKING, Any, Callablefrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.working_memory_factory import WorkingMemoryFactory+from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs+from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpecfrom pipelex.core.stuffs.image_content import ImageContent+from pipelex.core.stuffs.number_content import NumberContentfrom pipelex.core.stuffs.page_content import PageContentfrom pipelex.core.stuffs.text_and_images_content import TextAndImagesContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.hub import get_native_conceptfrom tests.cases.images import ImageTestCasesif TYPE_CHECKING:@@ -141,3 +145,34 @@ class TestWorkingMemoryFactory:text2_stuff = working_memory.root["text2"]assert isinstance(text2_stuff.content, TextContent)assert text2_stuff.content.text == "Second text"++ def test_without_specs_stays_bottom_up(self, load_empty_library: Callable[[], None]):+ """Smart Inputs regression: with no signature (`input_specs=None`), shaping is bypassed and+ the bottom-up behavior is unchanged — a bare string still becomes native.Text.+ """+ load_empty_library()+ # A bare string is narrower than the PipelineInputs alias formally admits, but flows at runtime.+ pipeline_inputs: dict[str, Any] = {"greeting": "hello"}++ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs, input_specs=None)++ stuff = working_memory.root["greeting"]+ assert stuff.concept.code == NativeConceptCode.TEXT+ assert isinstance(stuff.content, TextContent)+ assert stuff.content.text == "hello"++ def test_with_specs_shapes_bare_int_to_declared_number(self, load_empty_library: Callable[[], None]):+ """A bare int reaches the shaper at runtime despite the narrow PipelineInputs alias (D10 is+ release-gated) and is typed as the declared Number concept — the seam's runtime-reachability pin.+ """+ load_empty_library()+ number_concept = get_native_concept(native_concept=NativeConceptCode.NUMBER)+ input_specs = InputStuffSpecs(root={"count": StuffSpec(concept=number_concept)})+ pipeline_inputs: dict[str, Any] = {"count": 42}++ working_memory = WorkingMemoryFactory.make_from_pipeline_inputs(pipeline_inputs=pipeline_inputs, input_specs=input_specs)++ stuff = working_memory.root["count"]+ assert stuff.concept.code == NativeConceptCode.NUMBER+ assert isinstance(stuff.content, NumberContent)+ assert stuff.content.number == 42diff --git a/tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py b/tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.pynew file mode 100644index 000000000..2a0403c45--- /dev/null+++ b/tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py@@ -0,0 +1,117 @@+"""Golden coverage for the light (signature-driven) inputs template — the real end-to-end path.++Unlike the pure-transform unit test, this loads the actual Smart-Inputs fixture bundles so the real+``resolve_input_kind`` runs against a loaded concept library. It pins:++- the light JSON default for a mixed-signature pipe (bare string / bare number / structured dict /+ list of bare strings, and file-ish URL strings / structured-list),+- the light TOML default carrying a ``# concept: ...`` comment per key and loading back to the same+ light dict, and+- ``--explicit`` reproducing the ceremonial ``{concept, content}`` envelope template.++Both formats compose with the same ``explicit`` switch.+"""++from __future__ import annotations++import json+from pathlib import Path+from typing import TYPE_CHECKING, Any, cast++import pytest+import tomli++from pipelex.core.pipes.inputs.input_renderer import render_inputs, render_inputs_toml+from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_pipe, set_current_library+from pipelex.pipeline.validate_bundle import validate_bundle++if TYPE_CHECKING:+ from collections.abc import Callable++_TRIAGE = Path(__file__).parents[4] / "e2e" / "pipelex" / "pipes" / "smart_inputs" / "smart_inputs_triage" / "smart_inputs_triage.mthds"+_FILES = Path(__file__).parents[4] / "e2e" / "pipelex" / "pipes" / "smart_inputs" / "smart_inputs_files" / "smart_inputs_files.mthds"+++def _teardown_validation_library(outer_library_id: str) -> None:+ """Tear down the library `validate_bundle` left open on success, restoring the outer one."""+ validation_library_id = get_current_library_id_or_none()+ if validation_library_id is not None and validation_library_id != outer_library_id:+ set_current_library(library_id=outer_library_id)+ get_library_manager().teardown(library_id=validation_library_id)+ clear_current_library()++[email protected](loop_scope="class")+class TestInputRendererLightGolden:+ async def _load_pipe(self, bundle_path: Path, *, pipe_ref: str, load_empty_library: Callable[[], str]) -> tuple[Any, str]:+ outer_library_id = load_empty_library()+ await validate_bundle(mthds_file_path=bundle_path)+ the_pipe = get_required_pipe(pipe_code=pipe_ref)+ return the_pipe, outer_library_id++ async def test_triage_light_json_default(self, load_empty_library: Callable[[], str]) -> None:+ """The default JSON template is the light shape: bare string/number, structured dict, list of bare strings."""+ the_pipe, outer_library_id = await self._load_pipe(_TRIAGE, pipe_ref="smart_inputs_demo.triage_case", load_empty_library=load_empty_library)+ try:+ light = json.loads(render_inputs(the_pipe))+ finally:+ _teardown_validation_library(outer_library_id)++ assert light == {+ "question": "text_value",+ "priority": 1,+ "invoice": {"invoice_number": "invoice_number_value", "amount": 0.0},+ "tags": ["text_value"],+ }++ async def test_triage_light_toml_carries_concept_comments(self, load_empty_library: Callable[[], str]) -> None:+ """The default TOML template carries the declared concept as a comment and loads back to the light dict."""+ the_pipe, outer_library_id = await self._load_pipe(_TRIAGE, pipe_ref="smart_inputs_demo.triage_case", load_empty_library=load_empty_library)+ try:+ toml_str = render_inputs_toml(the_pipe)+ finally:+ _teardown_validation_library(outer_library_id)++ assert "# concept: smart_inputs_demo.Question" in toml_str+ assert "# concept: smart_inputs_demo.Priority" in toml_str+ assert "# concept: smart_inputs_demo.Tag[]" in toml_str+ assert tomli.loads(toml_str) == {+ "question": "text_value",+ "priority": 1,+ "invoice": {"invoice_number": "invoice_number_value", "amount": 0.0},+ "tags": ["text_value"],+ }++ async def test_triage_explicit_reproduces_envelope(self, load_empty_library: Callable[[], str]) -> None:+ """--explicit reproduces the ceremonial {concept, content} envelope, in both JSON and TOML."""+ the_pipe, outer_library_id = await self._load_pipe(_TRIAGE, pipe_ref="smart_inputs_demo.triage_case", load_empty_library=load_empty_library)+ try:+ envelope = json.loads(render_inputs(the_pipe, explicit=True))+ envelope_toml = tomli.loads(render_inputs_toml(the_pipe, explicit=True))+ finally:+ _teardown_validation_library(outer_library_id)++ assert envelope["question"] == {"concept": "smart_inputs_demo.Question", "content": {"text": "text_value"}}+ assert envelope["priority"] == {"concept": "smart_inputs_demo.Priority", "content": {"number": 1}}+ assert envelope["tags"] == {"concept": "smart_inputs_demo.Tag", "content": [{"text": "text_value"}]}+ assert envelope_toml == envelope++ async def test_files_light_json_file_ish_and_structured_list(self, load_empty_library: Callable[[], str]) -> None:+ """File-ish inputs become bare URL strings; a structured list becomes a bare list of dicts."""+ the_pipe, outer_library_id = await self._load_pipe(+ _FILES, pipe_ref="smart_inputs_files_demo.review_case", load_empty_library=load_empty_library+ )+ try:+ light = json.loads(render_inputs(the_pipe))+ finally:+ _teardown_validation_library(outer_library_id)++ photo = light["photo"]+ assert isinstance(photo, str)+ assert photo.startswith("https://")+ exhibits = cast("list[Any]", light["exhibits"])+ assert len(exhibits) == 1+ first_exhibit = exhibits[0]+ assert isinstance(first_exhibit, str)+ assert first_exhibit.startswith("https://")+ assert light["people"] == [{"name": "name_value", "job": "job_value"}]diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.pynew file mode 100644index 000000000..a2c4d7e0b--- /dev/null+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_date_output_path.py@@ -0,0 +1,70 @@+"""Phase 3 verification: a PipeLLM whose output is native Date takes the object path.++`Date` is not Text-compatible, so PipeLLM's output dispatch (`pipe_llm.py`) must route it down the+object path — handing `DateContent` (whose `model_json_schema()` carries the LLM-facing anti-fabrication+field descriptions, a contract not a decoration) to the content generator's `make_object`, never the+text path (`make_llm_text`). A spy on the generator pins both the path selection and the exact class+whose schema is handed down. Runs in DRY mode: the leaf mock short-circuits inside `make_object`, so no+provider is ever called (hence no inference marker).+"""++from typing import Any, Callable++import pytest+from pytest_mock import MockerFixture++from pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.pipes.pipe_factory import PipeFactory+from pipelex.core.stuffs.date_content import DateContent+from pipelex.hub import get_content_generator, get_pipe_library, get_pipe_router+from pipelex.pipe_operators.llm.pipe_llm import PipeLLM+from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint+from pipelex.pipe_run.pipe_job_factory import PipeJobFactory+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory+from pipelex.pipeline.job_metadata import JobMetadata++[email protected](loop_scope="class")+class TestPipeLLMDateOutputPath:+ async def test_date_output_takes_object_path_with_field_descriptions(+ self,+ job_metadata: JobMetadata,+ mocker: MockerFixture,+ load_empty_library: Callable[[], str],+ ) -> None:+ """`output = "Date"` calls make_object with DateContent whose schema carries both field descriptions."""+ load_empty_library()+ content_generator = get_content_generator()+ make_object_spy = mocker.spy(content_generator, "make_object")++ pipe = PipeFactory[PipeLLM].make_from_blueprint(+ domain_code="generic",+ pipe_code="adhoc_date_output_path",+ blueprint=PipeLLMBlueprint(+ description="Extract the scheduled departure from a ticket",+ output=NativeConceptCode.DATE,+ prompt="Extract the scheduled departure from this ticket.",+ ),+ )+ get_pipe_library().add_new_pipe(pipe)++ pipe_job = PipeJobFactory.make_pipe_job(+ pipe=pipe,+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY),+ job_metadata=job_metadata,+ )+ pipe_output = await get_pipe_router().run(pipe_job=pipe_job)++ # Object path: make_object was called (the text path would have called make_llm_text instead).+ make_object_spy.assert_called_once()+ object_class: Any = make_object_spy.call_args.kwargs["object_class"]+ assert object_class is DateContent++ # The schema handed to generation carries both LLM-facing field descriptions (contract, not decoration).+ schema = object_class.model_json_schema()+ assert schema["properties"]["date"]["description"]+ assert schema["properties"]["time"]["description"]++ # And the produced value is a Date, not text.+ assert pipe_output.main_stuff.is_datediff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.pynew file mode 100644index 000000000..b5dfca262--- /dev/null+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py@@ -0,0 +1,69 @@+"""Phase 3 verification: a PipeLLM whose output is native YesNo takes the object path.++`YesNo` is not Text-compatible, so PipeLLM's output dispatch (`pipe_llm.py`) must route it down the+object path — handing `YesNoContent` (whose `model_json_schema()` carries the LLM-facing field+description, a contract not a decoration) to the content generator's `make_object`, never the text+path (`make_llm_text`). A spy on the generator pins both the path selection and the exact class whose+schema is handed down. Runs in DRY mode: the leaf mock short-circuits inside `make_object`, so no+provider is ever called (hence no inference marker).+"""++from typing import Any, Callable++import pytest+from pytest_mock import MockerFixture++from pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.pipes.pipe_factory import PipeFactory+from pipelex.core.stuffs.yes_no_content import YesNoContent+from pipelex.hub import get_content_generator, get_pipe_library, get_pipe_router+from pipelex.pipe_operators.llm.pipe_llm import PipeLLM+from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint+from pipelex.pipe_run.pipe_job_factory import PipeJobFactory+from pipelex.pipe_run.pipe_run_mode import PipeRunMode+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory+from pipelex.pipeline.job_metadata import JobMetadata++[email protected](loop_scope="class")+class TestPipeLLMYesNoOutputPath:+ async def test_yes_no_output_takes_object_path_with_field_description(+ self,+ job_metadata: JobMetadata,+ mocker: MockerFixture,+ load_empty_library: Callable[[], str],+ ) -> None:+ """`output = "YesNo"` calls make_object with YesNoContent whose schema carries the field description."""+ load_empty_library()+ content_generator = get_content_generator()+ make_object_spy = mocker.spy(content_generator, "make_object")++ pipe = PipeFactory[PipeLLM].make_from_blueprint(+ domain_code="generic",+ pipe_code="adhoc_yes_no_output_path",+ blueprint=PipeLLMBlueprint(+ description="Decide whether a message is urgent, answering yes or no",+ output=NativeConceptCode.YES_NO,+ prompt="Is the following message urgent? Answer yes or no.",+ ),+ )+ get_pipe_library().add_new_pipe(pipe)++ pipe_job = PipeJobFactory.make_pipe_job(+ pipe=pipe,+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY),+ job_metadata=job_metadata,+ )+ pipe_output = await get_pipe_router().run(pipe_job=pipe_job)++ # Object path: make_object was called (the text path would have called make_llm_text instead).+ make_object_spy.assert_called_once()+ object_class: Any = make_object_spy.call_args.kwargs["object_class"]+ assert object_class is YesNoContent++ # The schema handed to generation carries the LLM-facing field description (contract, not decoration).+ schema = object_class.model_json_schema()+ assert schema["properties"]["yes_no"]["description"]++ # And the produced verdict is a YesNo, not text.+ assert pipe_output.main_stuff.is_yes_nodiff --git a/tests/unit/pipelex/builder/concept/test_concept_structure_spec_validation.py b/tests/unit/pipelex/builder/concept/test_concept_structure_spec_validation.pyindex 6aa27079d..2c687b116 100644--- a/tests/unit/pipelex/builder/concept/test_concept_structure_spec_validation.py+++ b/tests/unit/pipelex/builder/concept/test_concept_structure_spec_validation.py@@ -1,3 +1,5 @@+from datetime import date, datetime+import pytestfrom pydantic import ValidationError@@ -57,6 +59,31 @@ class TestConceptStructureSpecValidation:assert "concept_ref" in error_strassert "type is 'concept'" in error_str+ def test_date_spec_accepts_date_rejects_datetime(self):+ """A spec `date` field accepts a calendar date and rejects a datetime (mirrors the blueprint layer)."""+ spec = ConceptStructureSpec(+ the_field_name="issued_on", description="Issue date", type=ConceptStructureSpecFieldType.DATE, default_value=date(2026, 7, 7)+ )+ assert spec.to_blueprint().type == ConceptStructureBlueprintFieldType.DATE++ with pytest.raises(ValidationError, match="default_value type mismatch: expected date"):+ ConceptStructureSpec(+ the_field_name="issued_on",+ description="Issue date",+ type=ConceptStructureSpecFieldType.DATE,+ default_value=datetime(2026, 7, 7, 15, 40),+ )++ def test_datetime_spec_type_and_to_blueprint(self):+ """A spec `datetime` field accepts a timestamp default and maps to the blueprint DATETIME type."""+ spec = ConceptStructureSpec(+ the_field_name="recorded_at",+ description="Record timestamp",+ type=ConceptStructureSpecFieldType.DATETIME,+ default_value=datetime(2026, 7, 7, 15, 40),+ )+ assert spec.to_blueprint().type == ConceptStructureBlueprintFieldType.DATETIME+def test_to_blueprint_concept_type(self):"""Test to_blueprint() conversion for CONCEPT type."""spec = ConceptStructureSpec(diff --git a/tests/unit/pipelex/builder/operations/test_inputs_ops.py b/tests/unit/pipelex/builder/operations/test_inputs_ops.pyindex a6f1a0ade..309db68bb 100644--- a/tests/unit/pipelex/builder/operations/test_inputs_ops.py+++ b/tests/unit/pipelex/builder/operations/test_inputs_ops.py@@ -30,7 +30,9 @@ class TestBuildInputsForPipe:"set_current_library": mocker.patch(f"{MODULE}.set_current_library"),"resolve_library_dirs": mocker.patch(f"{MODULE}.resolve_library_dirs", return_value=([], "defaults")),"validate_bundle": mocker.patch(f"{MODULE}.validate_bundle", new=mocker.AsyncMock(return_value=validate_result)),- "get_required_pipe": mocker.patch(f"{MODULE}.get_required_pipe", return_value=SimpleNamespace(code="bundle_main")),+ "get_required_pipe": mocker.patch(+ f"{MODULE}.get_required_pipe", return_value=SimpleNamespace(code="bundle_main", inputs=SimpleNamespace(root={}))+ ),"render_inputs": mocker.patch(f"{MODULE}.render_inputs", return_value='{\n "topic": "your topic"\n}'),}@@ -143,9 +145,10 @@ class TestBuildInputsForPipe:result = asyncio.run(build_inputs_for_pipe(pipe_code="my_pipe"))the_pipe = ops_mocks["get_required_pipe"].return_value- ops_mocks["render_inputs"].assert_called_once_with(the_pipe, indent=2)+ ops_mocks["render_inputs"].assert_called_once_with(the_pipe, indent=2, explicit=False)assert result == {"success": True,"pipe_code": "my_pipe","inputs": {"topic": "your topic"},+ "concept_comments": {},}diff --git a/tests/unit/pipelex/cli/agent_cli/test_error_format_independent.py b/tests/unit/pipelex/cli/agent_cli/test_error_format_independent.pyindex d57ce6d0c..93a1f595f 100644--- a/tests/unit/pipelex/cli/agent_cli/test_error_format_independent.py+++ b/tests/unit/pipelex/cli/agent_cli/test_error_format_independent.py@@ -9,6 +9,7 @@ from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.pipe_cmd import run_pipe_cmd+from pipelex.cli.agent_cli.commands.run.stdin_resolver import ParsedCliInputsif TYPE_CHECKING:from pytest_mock import MockerFixture@@ -22,7 +23,7 @@ class TestErrorFormatIndependent:mocker.patch(f"{RUN_PIPE_MODULE}.make_pipelex_for_agent_cli")mocker.patch(f"{RUN_PIPE_MODULE}.Pipelex.teardown_if_needed")mocker.patch(f"{RUN_PIPE_MODULE}.resolve_pipe_from_exports", return_value=[])- mocker.patch(f"{RUN_PIPE_MODULE}.parse_cli_inputs", return_value=None)+ mocker.patch(f"{RUN_PIPE_MODULE}.parse_cli_inputs", return_value=ParsedCliInputs(pipeline_inputs=None, inputs_base_dir=None))mocker.patch(f"{RUN_PIPE_MODULE}.run_pipeline_core", new=mocker.AsyncMock(return_value=result))ctx = mocker.MagicMock()ctx.obj = {"runner": RunnerType.PIPELEX}diff --git a/tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py b/tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.pyindex 63eaf11e7..5151a2834 100644--- a/tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py+++ b/tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Anyimport tomli+from pipelex.cli.agent_cli.commands.inputs._inputs_core import emit_inputs_result # noqa: PLC2701from pipelex.cli.agent_cli.commands.inputs.pipe_cmd import inputs_pipe_cmdfrom pipelex.core.pipes.inputs.exceptions import NoInputsRequiredErrorfrom pipelex.core.pipes.inputs.input_renderer import InputsTemplateFormat@@ -76,3 +77,34 @@ class TestAgentInputsTemplateFormatToml:assert envelope["success"] is Trueassert envelope["inputs"] == {}assert "No inputs required" in envelope["message"]++ def test_light_toml_carries_concept_comments(self, capsys: pytest.CaptureFixture[str]) -> None:+ """The agent-CLI TOML surface carries the same `# concept:` hints the human build inputs does."""+ result: dict[str, Any] = {+ "success": True,+ "pipe_code": "demo.my_pipe",+ "inputs": {"question": "text_value", "invoice": {"invoice_number": "INV-1"}},+ "concept_comments": {"question": "concept: demo.Question", "invoice": "concept: demo.Invoice"},+ }++ emit_inputs_result(result, template_format=InputsTemplateFormat.TOML)++ out = capsys.readouterr().out+ assert "# concept: demo.Question" in out+ assert "# concept: demo.Invoice" in out+ assert tomli.loads(out) == {"question": "text_value", "invoice": {"invoice_number": "INV-1"}}++ def test_json_mode_strips_internal_concept_comments(self, capsys: pytest.CaptureFixture[str]) -> None:+ """concept_comments is internal plumbing — it must not leak into the JSON envelope."""+ result: dict[str, Any] = {+ "success": True,+ "pipe_code": "demo.my_pipe",+ "inputs": {"question": "text_value"},+ "concept_comments": {"question": "concept: demo.Question"},+ }++ emit_inputs_result(result, template_format=InputsTemplateFormat.JSON)++ envelope = json.loads(capsys.readouterr().out)+ assert "concept_comments" not in envelope+ assert envelope["inputs"] == {"question": "text_value"}diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_core_inputs_base_dir.py b/tests/unit/pipelex/cli/agent_cli/test_run_core_inputs_base_dir.pynew file mode 100644index 000000000..e8ea50a26--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/test_run_core_inputs_base_dir.py@@ -0,0 +1,61 @@+"""Wiring tests: the agent CLI's local run core forwards ``inputs_base_dir`` to the runner+constructor (D3), so bare relative file paths in a loaded inputs file resolve against the+file's directory inside the shaper.+"""++from __future__ import annotations++import asyncio+from typing import TYPE_CHECKING, Any++import pytest++from pipelex.base_exceptions import PipelexError+from pipelex.cli.agent_cli.commands.run._run_core import run_pipeline_core # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture++RUN_CORE_MODULE = "pipelex.cli.agent_cli.commands.run._run_core"+++class TestRunCoreInputsBaseDir:+ @pytest.fixture+ def config_mock(self, mocker: MockerFixture) -> Any:+ fake_config = mocker.MagicMock()+ fake_config.pipelex.pipeline_execution_config.with_execution_overrides.return_value = mocker.MagicMock()+ mocker.patch(f"{RUN_CORE_MODULE}.get_config", return_value=fake_config)+ return fake_config++ def _mock_runner_class(self, mocker: MockerFixture) -> Any:+ """Patch the protocol runner; execute() raises so the test stops right after construction."""+ runner_mock = mocker.MagicMock()+ runner_mock.execute = mocker.AsyncMock(side_effect=PipelexError("stop after construction"))+ return mocker.patch(f"{RUN_CORE_MODULE}.PipelexMTHDSProtocol", return_value=runner_mock)++ @pytest.mark.usefixtures("config_mock")+ def test_inputs_base_dir_forwarded_to_runner(self, mocker: MockerFixture, tmp_path: Path) -> None:+ runner_class_mock = self._mock_runner_class(mocker)++ with pytest.raises(PipelexError, match="stop after construction"):+ asyncio.run(+ run_pipeline_core(+ "some_pipe",+ inputs={"photo": "photo.jpg"},+ dry_run=True,+ inputs_base_dir=tmp_path,+ )+ )++ assert runner_class_mock.call_args.kwargs["inputs_base_dir"] == tmp_path++ @pytest.mark.usefixtures("config_mock")+ def test_inputs_base_dir_defaults_to_none(self, mocker: MockerFixture) -> None:+ runner_class_mock = self._mock_runner_class(mocker)++ with pytest.raises(PipelexError, match="stop after construction"):+ asyncio.run(run_pipeline_core("some_pipe", inputs={"topic": "cats"}, dry_run=True))++ assert runner_class_mock.call_args.kwargs["inputs_base_dir"] is Nonediff --git a/tests/unit/pipelex/cli/agent_cli/test_run_format.py b/tests/unit/pipelex/cli/agent_cli/test_run_format.pyindex d865355ea..d8cb01474 100644--- a/tests/unit/pipelex/cli/agent_cli/test_run_format.py+++ b/tests/unit/pipelex/cli/agent_cli/test_run_format.py@@ -10,6 +10,7 @@ from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.pipe_cmd import run_pipe_cmd+from pipelex.cli.agent_cli.commands.run.stdin_resolver import ParsedCliInputsif TYPE_CHECKING:from pytest_mock import MockerFixture@@ -25,7 +26,7 @@ class TestRunFormat:mocker.patch(f"{RUN_PIPE_MODULE}.make_pipelex_for_agent_cli")mocker.patch(f"{RUN_PIPE_MODULE}.Pipelex.teardown_if_needed")mocker.patch(f"{RUN_PIPE_MODULE}.resolve_pipe_from_exports", return_value=[])- mocker.patch(f"{RUN_PIPE_MODULE}.parse_cli_inputs", return_value=None)+ mocker.patch(f"{RUN_PIPE_MODULE}.parse_cli_inputs", return_value=ParsedCliInputs(pipeline_inputs=None, inputs_base_dir=None))mocker.patch(f"{RUN_PIPE_MODULE}.run_pipeline_core", new=mocker.AsyncMock(return_value=result))ctx = mocker.MagicMock()ctx.obj = {"runner": RunnerType.PIPELEX}diff --git a/tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.py b/tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.pyindex 259927726..6445648f8 100644--- a/tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.py+++ b/tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.py@@ -2,13 +2,15 @@from __future__ import annotations+import datetimeimport jsonfrom typing import TYPE_CHECKINGimport pytestfrom pipelex.cli.commands.run._inputs_file_loader import load_inputs_dict_from_path # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]-from pipelex.cli.commands.run.exceptions import InputsDatetimeNotSupportedError+from pipelex.cli.commands.run.exceptions import InputsTimeOnlyNotSupportedError+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.tools.misc.exceptions import JsonTypeError, TomlErrorif TYPE_CHECKING:@@ -81,43 +83,69 @@ class TestInputsFileLoader:with pytest.raises(FileNotFoundError):load_inputs_dict_from_path(tmp_path / "absent.json")- @pytest.mark.parametrize(- "toml_value",- [- "2026-07-06T12:30:00Z",- "2026-07-06T12:30:00",- "2026-07-06",- "12:30:00",- ],- ids=["offset_datetime", "local_datetime", "local_date", "local_time"],- )- def test_datetime_rejected_at_top_level(self, tmp_path: Path, toml_value: str) -> None:- """Every TOML datetime flavor is rejected with the not-supported error."""+ def test_top_level_local_date_becomes_date_content(self, tmp_path: Path) -> None:+ """A top-level TOML local date maps to a date-only DateContent."""inputs_file = tmp_path / "inputs.toml"- inputs_file.write_text(f"deadline = {toml_value}\n", encoding="utf-8")+ inputs_file.write_text("hearing = 2026-09-01\n", encoding="utf-8")- with pytest.raises(InputsDatetimeNotSupportedError) as exc_info:+ loaded = load_inputs_dict_from_path(inputs_file)++ assert loaded["hearing"] == DateContent(date=datetime.date(2026, 9, 1))+ assert loaded["hearing"].time is None++ def test_top_level_local_datetime_becomes_naive_date_content(self, tmp_path: Path) -> None:+ """A top-level TOML local datetime maps to a DateContent with a naive time (no invented offset)."""+ inputs_file = tmp_path / "inputs.toml"+ inputs_file.write_text("start = 2026-07-07T09:00:00\n", encoding="utf-8")++ loaded = load_inputs_dict_from_path(inputs_file)++ content = loaded["start"]+ assert isinstance(content, DateContent)+ assert content.date == datetime.date(2026, 7, 7)+ assert content.time is not None+ assert content.time == datetime.time(9, 0)+ assert content.time.tzinfo is None++ def test_top_level_offset_datetime_preserves_offset(self, tmp_path: Path) -> None:+ """A top-level TOML offset datetime maps to a DateContent whose time keeps the stated UTC offset."""+ inputs_file = tmp_path / "inputs.toml"+ inputs_file.write_text("departure = 2026-07-07T15:40:00+02:00\n", encoding="utf-8")++ loaded = load_inputs_dict_from_path(inputs_file)++ content = loaded["departure"]+ assert isinstance(content, DateContent)+ assert content.time is not None+ assert content.time.utcoffset() == datetime.timedelta(hours=2)++ def test_top_level_local_time_rejected(self, tmp_path: Path) -> None:+ """A bare TOML time-of-day is still rejected — it has no date to attach to."""+ inputs_file = tmp_path / "inputs.toml"+ inputs_file.write_text("opening = 09:00:00\n", encoding="utf-8")++ with pytest.raises(InputsTimeOnlyNotSupportedError) as exc_info:load_inputs_dict_from_path(inputs_file)- assert "not supported yet" in exc_info.value.message- assert "deadline" in exc_info.value.message+ assert "opening" in exc_info.value.message+ assert "time of day alone" in exc_info.value.message- def test_datetime_rejected_nested(self, tmp_path: Path) -> None:- """A datetime nested dict-in-list-in-dict is rejected, with its key path in the message."""+ def test_nested_time_rejected_with_key_path(self, tmp_path: Path) -> None:+ """A time-of-day nested in an envelope's content is rejected, with its key path in the message."""inputs_file = tmp_path / "inputs.toml"inputs_file.write_text(- '[record]\nconcept = "Event"\n[[record.entries]]\nlabel = "kickoff"\nwhen = 2026-07-06T09:00:00Z\n',+ '[record]\nconcept = "Event"\n[[record.entries]]\nlabel = "kickoff"\nat = 09:00:00\n',encoding="utf-8",)- with pytest.raises(InputsDatetimeNotSupportedError) as exc_info:+ with pytest.raises(InputsTimeOnlyNotSupportedError) as exc_info:load_inputs_dict_from_path(inputs_file)- assert "record.entries[0].when" in exc_info.value.message+ assert "record.entries[0].at" in exc_info.value.message- def test_datetime_message_suggests_quoting(self, tmp_path: Path) -> None:- """The rejection message tells the user to quote the value as a string meanwhile."""+ def test_nested_datetime_left_in_place(self, tmp_path: Path) -> None:+ """A date/datetime nested in an envelope's content is left for the factory/pydantic to consume."""inputs_file = tmp_path / "inputs.toml"- inputs_file.write_text("deadline = 2026-07-06\n", encoding="utf-8")+ inputs_file.write_text('[due]\nconcept = "billing.DueDate"\ncontent = 2026-08-06\n', encoding="utf-8")- with pytest.raises(InputsDatetimeNotSupportedError) as exc_info:- load_inputs_dict_from_path(inputs_file)- assert "quote the value as a string" in exc_info.value.message+ loaded = load_inputs_dict_from_path(inputs_file)++ assert loaded["due"]["content"] == datetime.date(2026, 8, 6)diff --git a/tests/unit/pipelex/cli/test_inputs_path_resolver.py b/tests/unit/pipelex/cli/test_inputs_path_resolver.pyindex 866fb528e..ebd63c798 100644--- a/tests/unit/pipelex/cli/test_inputs_path_resolver.py+++ b/tests/unit/pipelex/cli/test_inputs_path_resolver.py@@ -7,7 +7,8 @@ from typing import Any, ClassVarimport pytest-from pipelex.cli.commands.run._inputs_path_resolver import is_relative_local_path, resolve_inputs_paths, resolve_url_in_value # noqa: PLC2701+from pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_paths, resolve_url_in_value # noqa: PLC2701+from pipelex.tools.uri.uri_resolver import is_relative_local_pathclass _IsRelativeLocalPathCases:@@ -231,6 +232,11 @@ class TestInputsPathResolver:assert resolve_url_in_value(42, base_dir=Path("/base")) == 42assert resolve_url_in_value(None, base_dir=Path("/base")) is None+ def test_resolve_url_in_value_tilde_expands_to_home(self) -> None:+ """A ~-prefixed url is home-anchored: it expands to home, never joined onto base_dir."""+ resolved = resolve_url_in_value({"url": "~/photo.jpg"}, base_dir=Path("/base"))+ assert resolved == {"url": str(Path("~/photo.jpg").expanduser())}+# ---- resolve_inputs_paths ----@pytest.mark.parametrize(diff --git a/tests/unit/pipelex/cli/test_run_core_execution.py b/tests/unit/pipelex/cli/test_run_core_execution.pyindex 806ce1a44..4e2b3f973 100644--- a/tests/unit/pipelex/cli/test_run_core_execution.py+++ b/tests/unit/pipelex/cli/test_run_core_execution.py@@ -229,6 +229,30 @@ class TestRunCoreExecution:execute_kwargs = runner_class_mock.return_value.execute.call_args.kwargsassert execute_kwargs["inputs"] == {"topic": "dogs", "resolved": True}+ @pytest.mark.usefixtures("config_mock", "console")+ def test_file_inputs_thread_base_dir_to_runner(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """File-loaded inputs hand the file's parent dir to the runner as inputs_base_dir (D3)."""+ inputs_file = tmp_path / "inputs.json"+ inputs_file.write_text(json.dumps({"photo": "photo.jpg"}), encoding="utf-8")+ pipe_output = self._make_pipe_output(mocker)+ runner_class_mock = self._mock_runner(mocker, pipe_output)++ _run_async(_call_execute_run(inputs=str(inputs_file)))++ ctor_kwargs = runner_class_mock.call_args.kwargs+ assert ctor_kwargs["inputs_base_dir"] == tmp_path.resolve()++ @pytest.mark.usefixtures("config_mock", "console")+ def test_inline_json_inputs_have_no_base_dir(self, mocker: MockerFixture) -> None:+ """Inline JSON inputs come from no file — the runner gets inputs_base_dir=None."""+ pipe_output = self._make_pipe_output(mocker)+ runner_class_mock = self._mock_runner(mocker, pipe_output)++ _run_async(_call_execute_run(inputs='{"topic": "cats"}'))++ ctor_kwargs = runner_class_mock.call_args.kwargs+ assert ctor_kwargs["inputs_base_dir"] is None+@pytest.mark.usefixtures("console")def test_non_dict_input_file_exits(self, tmp_path: Path) -> None:"""An input file holding a JSON list (not a dict) is rejected."""@@ -271,15 +295,22 @@ class TestRunCoreExecution:assert exc_info.value.exit_code == 1@pytest.mark.usefixtures("console")- def test_toml_datetime_input_file_exits(self, tmp_path: Path) -> None:- """A .toml inputs file holding a TOML datetime is rejected (not supported yet)."""+ def test_toml_time_only_input_file_exits(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """A .toml inputs file holding a bare TOML time-of-day is rejected during loading.++ Top-level date/datetime literals are now accepted (converted to a native Date); only a bare+ time-of-day has no date to attach to, so the loader raises InputsTimeOnlyNotSupportedError,+ surfaced as a clean exit 1 before any runner is constructed. Asserting the "Failed to load+ input file" framing pins that the exit comes from that catch site, not a downstream failure.+ """inputs_file = tmp_path / "inputs.toml"- inputs_file.write_text("deadline = 2026-07-06T12:00:00Z\n", encoding="utf-8")+ inputs_file.write_text("deadline = 12:00:00\n", encoding="utf-8")with pytest.raises(typer.Exit) as exc_info:_run_async(_call_execute_run(inputs=str(inputs_file)))assert exc_info.value.exit_code == 1+ assert "Failed to load input file" in capsys.readouterr().err@pytest.mark.usefixtures("console")def test_invalid_json_input_file_exits(self, tmp_path: Path) -> None:diff --git a/tests/unit/pipelex/cli/test_stdin_resolver.py b/tests/unit/pipelex/cli/test_stdin_resolver.pyindex 3c964b56b..0fb1f21be 100644--- a/tests/unit/pipelex/cli/test_stdin_resolver.py+++ b/tests/unit/pipelex/cli/test_stdin_resolver.py@@ -195,6 +195,40 @@ class TestStdinResolver:assert "bad_no_concept" not in resultassert "bad_no_content" not in result+ # -------------------------------------------------------------------------+ # parse_cli_inputs() base-dir contract (D3): the inputs file's parent travels+ # with the parsed dict so the shaper can resolve bare relative file paths.+ # -------------------------------------------------------------------------++ def test_parse_file_inputs_carries_base_dir(self, tmp_path: Path) -> None:+ """File-loaded inputs carry the file's parent directory as inputs_base_dir."""+ json_file = tmp_path / "inputs.json"+ json_file.write_text('{"photo": "photo.jpg"}', encoding="utf-8")+ result = parse_cli_inputs(inputs_arg=str(json_file))+ assert result.pipeline_inputs == {"photo": "photo.jpg"}+ assert result.inputs_base_dir == tmp_path.resolve()++ def test_parse_inline_json_has_no_base_dir(self) -> None:+ """Inline JSON comes from no file — inputs_base_dir is None."""+ result = parse_cli_inputs(inputs_arg='{"text": "hello"}')+ assert result.pipeline_inputs == {"text": "hello"}+ assert result.inputs_base_dir is None++ def test_parse_stdin_inputs_have_no_base_dir(self, monkeypatch: pytest.MonkeyPatch) -> None:+ """Piped stdin comes from no file — inputs_base_dir is None."""+ monkeypatch.setattr("sys.stdin", io.StringIO(json.dumps({"text": "from stdin"})))+ result = parse_cli_inputs(inputs_arg=None)+ assert result.pipeline_inputs == {"text": "from stdin"}+ assert result.inputs_base_dir is None++ def test_parse_auto_detected_inputs_carry_base_dir(self, tmp_path: Path) -> None:+ """An auto-detected default inputs file carries its directory as inputs_base_dir."""+ (tmp_path / "inputs.json").write_text('{"photo": "photo.jpg"}', encoding="utf-8")+ # stdin_fallback=False so the auto-detect branch is reached deterministically (no stdin probe).+ result = parse_cli_inputs(inputs_arg=None, stdin_fallback=False, auto_inputs_dir=tmp_path)+ assert result.pipeline_inputs == {"photo": "photo.jpg"}+ assert result.inputs_base_dir == tmp_path.resolve()+# -------------------------------------------------------------------------# parse_cli_inputs() tests# -------------------------------------------------------------------------@@ -202,14 +236,14 @@ class TestStdinResolver:def test_inputs_inline_json(self) -> None:"""--inputs with inline JSON string is parsed correctly."""result = parse_cli_inputs(inputs_arg='{"text": "hello"}')- assert result == {"text": "hello"}+ assert result.pipeline_inputs == {"text": "hello"}def test_inputs_file_path(self, tmp_path: Any) -> None:"""--inputs with a file path loads JSON from the file."""json_file = tmp_path / "inputs.json"json_file.write_text('{"key": "value"}')result = parse_cli_inputs(inputs_arg=str(json_file))- assert result == {"key": "value"}+ assert result.pipeline_inputs == {"key": "value"}def test_inputs_tilde_path_is_expanded(self, tmp_path: Any, monkeypatch: pytest.MonkeyPatch) -> None:"""A quoted / `=`-form `~/inputs.json` (tilde not shell-expanded) resolves to the home dir.@@ -220,13 +254,13 @@ class TestStdinResolver:monkeypatch.setenv("HOME", str(tmp_path))(tmp_path / "inputs.json").write_text('{"tilde": "expanded"}')result = parse_cli_inputs(inputs_arg="~/inputs.json", stdin_fallback=False)- assert result == {"tilde": "expanded"}+ assert result.pipeline_inputs == {"tilde": "expanded"}def test_inputs_wins_over_stdin(self, monkeypatch: pytest.MonkeyPatch) -> None:"""When --inputs is provided, stdin is ignored."""monkeypatch.setattr("sys.stdin", io.StringIO('{"from_stdin": true}'))result = parse_cli_inputs(inputs_arg='{"from_arg": true}')- assert result == {"from_arg": True}+ assert result.pipeline_inputs == {"from_arg": True}def test_stdin_fallback_not_tty(self, monkeypatch: pytest.MonkeyPatch) -> None:"""When inputs_arg is None and stdin is not a TTY, reads from stdin."""@@ -235,7 +269,7 @@ class TestStdinResolver:mock_stdin.isatty = lambda: False # type: ignore[assignment]monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None)- assert result == {"text": "from stdin"}+ assert result.pipeline_inputs == {"text": "from stdin"}def test_stdin_tty_returns_none(self, monkeypatch: pytest.MonkeyPatch) -> None:"""When stdin is a TTY, returns None (no read attempted)."""@@ -243,7 +277,7 @@ class TestStdinResolver:mock_stdin.isatty = lambda: True # type: ignore[assignment]monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None)- assert result is None+ assert result.pipeline_inputs is Nonedef test_stdin_fallback_disabled(self, monkeypatch: pytest.MonkeyPatch) -> None:"""When stdin_fallback=False, returns None even if stdin has data."""@@ -251,7 +285,7 @@ class TestStdinResolver:mock_stdin.isatty = lambda: False # type: ignore[assignment]monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None, stdin_fallback=False)- assert result is None+ assert result.pipeline_inputs is Nonedef test_stdin_empty(self, monkeypatch: pytest.MonkeyPatch) -> None:"""Empty stdin returns None."""@@ -259,7 +293,7 @@ class TestStdinResolver:mock_stdin.isatty = lambda: False # type: ignore[assignment]monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None)- assert result is None+ assert result.pipeline_inputs is Nonedef test_stdin_invalid_json(self, monkeypatch: pytest.MonkeyPatch) -> None:"""Invalid JSON on stdin triggers agent_error (typer.Exit)."""@@ -287,9 +321,9 @@ class TestStdinResolver:mock_stdin.isatty = lambda: False # type: ignore[assignment]monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None)- assert result is not None- assert "contract_text" in result- assert result["contract_text"]["concept"] == "Text"+ assert result.pipeline_inputs is not None+ assert "contract_text" in result.pipeline_inputs+ assert result.pipeline_inputs["contract_text"]["concept"] == "Text"def test_inputs_inline_invalid_json(self) -> None:"""Invalid inline JSON in --inputs triggers agent_error."""@@ -314,7 +348,7 @@ class TestStdinResolver:result = parse_cli_inputs(inputs_arg=str(toml_file))- assert result == {"contract_text": {"concept": "Text", "content": "First line.\nSecond line.\n"}}+ assert result.pipeline_inputs == {"contract_text": {"concept": "Text", "content": "First line.\nSecond line.\n"}}def test_inputs_toml_syntax_error_envelope(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:"""Invalid TOML in a .toml inputs file emits a TomlError envelope with input domain."""@@ -331,21 +365,21 @@ class TestStdinResolver:assert envelope["error_domain"] == "input"assert "hint" in envelope- def test_inputs_toml_datetime_error_envelope(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:- """A TOML datetime input emits the not-supported envelope with the quote-as-string hint."""+ def test_inputs_toml_time_only_error_envelope(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """A bare TOML time-of-day input emits the time-only-not-supported envelope with the include-a-date hint."""set_agent_cli_error_format(CliOutputFormat.JSON)toml_file = tmp_path / "inputs.toml"- toml_file.write_text("deadline = 2026-07-06T12:00:00Z\n", encoding="utf-8")+ toml_file.write_text("opening = 09:00:00\n", encoding="utf-8")with pytest.raises(typer.Exit) as exc_info:parse_cli_inputs(inputs_arg=str(toml_file))assert exc_info.value.exit_code == 1envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "InputsDatetimeNotSupportedError"+ assert envelope["error_type"] == "InputsTimeOnlyNotSupportedError"assert envelope["error_domain"] == "input"- assert "deadline" in envelope["message"]- assert "Quote the datetime as a string" in envelope["hint"]+ assert "opening" in envelope["message"]+ assert "no date to attach to" in envelope["hint"]def test_inputs_json_syntax_error_envelope(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:"""Invalid JSON in a .json inputs file emits a JSONDecodeError envelope (not a raw traceback)."""@@ -375,7 +409,7 @@ class TestStdinResolver:monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None, auto_inputs_dir=tmp_path)- assert result == {"from_stdin": True}+ assert result.pipeline_inputs == {"from_stdin": True}def test_explicit_inputs_beats_stdin_and_auto(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any) -> None:"""When inputs_arg, stdin, and auto_inputs_dir are all set, inputs_arg wins."""@@ -391,7 +425,7 @@ class TestStdinResolver:inputs_arg='{"from_arg": true}',auto_inputs_dir=tmp_path,)- assert result == {"from_arg": True}+ assert result.pipeline_inputs == {"from_arg": True}def test_empty_stdin_falls_back_to_auto_inputs_path(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any) -> None:"""When stdin is non-TTY but empty and auto_inputs_dir is set, the auto-detected file is used."""@@ -403,7 +437,7 @@ class TestStdinResolver:monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None, auto_inputs_dir=tmp_path)- assert result == {"from_auto": True}+ assert result.pipeline_inputs == {"from_auto": True}def test_auto_detected_path_used_when_no_stdin(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any) -> None:"""When stdin is a TTY and auto_inputs_dir is set, the auto-detected file is used."""@@ -415,7 +449,7 @@ class TestStdinResolver:monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None, auto_inputs_dir=tmp_path)- assert result == {"from_auto": True}+ assert result.pipeline_inputs == {"from_auto": True}def test_stdin_beats_ambiguous_auto_dir(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any) -> None:"""Piped stdin outranks auto-detect, so an ambiguous dir (both files) does NOT raise."""@@ -428,7 +462,7 @@ class TestStdinResolver:monkeypatch.setattr("sys.stdin", mock_stdin)result = parse_cli_inputs(inputs_arg=None, auto_inputs_dir=tmp_path)- assert result == {"from_stdin": True}+ assert result.pipeline_inputs == {"from_stdin": True}def test_ambiguous_auto_dir_raises_when_no_stdin(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any, capsys: pytest.CaptureFixture[str]diff --git a/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_blueprint.py b/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_blueprint.pyindex 8d7aac636..77bb6fef3 100644--- a/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_blueprint.py+++ b/tests/unit/pipelex/core/concepts/concept_blueprint/test_concept_blueprint.py@@ -1,5 +1,7 @@"""Tests for ConceptStructureBlueprint validation logic."""+from datetime import date, datetime+import pytestfrom pydantic import ValidationError@@ -96,6 +98,32 @@ class TestConceptStructureBlueprintValidation:default_value="not a dict",)+ def test_date_and_datetime_default_values(self):+ """A `date` field accepts a calendar date; a `datetime` field accepts a timestamp."""+ date_blueprint = ConceptStructureBlueprint(+ description="A date field", type=ConceptStructureBlueprintFieldType.DATE, default_value=date(2026, 7, 7)+ )+ assert date_blueprint.default_value == date(2026, 7, 7)++ datetime_blueprint = ConceptStructureBlueprint(+ description="A datetime field", type=ConceptStructureBlueprintFieldType.DATETIME, default_value=datetime(2026, 7, 7, 15, 40)+ )+ assert datetime_blueprint.default_value == datetime(2026, 7, 7, 15, 40)++ def test_date_field_rejects_datetime_default(self):+ """A `date` field rejects a datetime default — a datetime carries a time the field would silently drop."""+ with pytest.raises(ValidationError, match="default_value type mismatch: expected date"):+ ConceptStructureBlueprint(+ description="A date field", type=ConceptStructureBlueprintFieldType.DATE, default_value=datetime(2026, 7, 7, 15, 40)+ )++ def test_datetime_field_rejects_non_datetime_default(self):+ """A `datetime` field rejects a non-datetime default (e.g. a bare date or a string)."""+ with pytest.raises(ValidationError, match="default_value type mismatch: expected datetime"):+ ConceptStructureBlueprint(+ description="A datetime field", type=ConceptStructureBlueprintFieldType.DATETIME, default_value=date(2026, 7, 7)+ )+def test_missing_type_with_default_value(self):"""Test that missing type when default_value is provided (except for choices) is caught."""# Missing type with default_value (no choices) - this will trigger the "type is None (array)" validation firstdiff --git a/tests/unit/pipelex/core/concepts/concept_factory/test_date_refinement.py b/tests/unit/pipelex/core/concepts/concept_factory/test_date_refinement.pynew file mode 100644index 000000000..6098c4baf--- /dev/null+++ b/tests/unit/pipelex/core/concepts/concept_factory/test_date_refinement.py@@ -0,0 +1,23 @@+from pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.stuffs.date_content import DateContent+++class TestDateRefinement:+ """A domain concept refining native Date resolves DateContent via the generic machinery."""++ def test_refining_date_resolves_date_content(self):+ """`refines = "Date"` builds a concept whose structure class inherits from DateContent."""+ concept = ConceptFactory.make_from_blueprint(+ domain_code="billing",+ concept_code="DueDate",+ blueprint_or_string_description=ConceptBlueprint(description="The date payment is due", refines="Date"),+ )++ structure_class = concept.get_structure_class()+ assert issubclass(structure_class, DateContent)++ native_date = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DATE)+ assert Concept.are_concept_compatible(concept_1=concept, concept_2=native_date, strict=True)diff --git a/tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.py b/tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.pynew file mode 100644index 000000000..1e61feca2--- /dev/null+++ b/tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.py@@ -0,0 +1,23 @@+from pipelex.core.concepts.concept import Concept+from pipelex.core.concepts.concept_blueprint import ConceptBlueprint+from pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.stuffs.yes_no_content import YesNoContent+++class TestYesNoRefinement:+ """A domain concept refining native YesNo resolves YesNoContent via the generic machinery."""++ def test_refining_yes_no_resolves_yes_no_content(self):+ """`refines = "YesNo"` builds a concept whose structure class inherits from YesNoContent."""+ concept = ConceptFactory.make_from_blueprint(+ domain_code="urgency",+ concept_code="IsUrgent",+ blueprint_or_string_description=ConceptBlueprint(description="Whether the item is urgent", refines="YesNo"),+ )++ structure_class = concept.get_structure_class()+ assert issubclass(structure_class, YesNoContent)++ native_yes_no = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.YES_NO)+ assert Concept.are_concept_compatible(concept_1=concept, concept_2=native_yes_no, strict=True)diff --git a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator.py b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator.pyindex 5a5347cbf..947f2f67d 100644--- a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator.py+++ b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator.py@@ -1,3 +1,6 @@+from datetime import date, datetime, timedelta, timezone+from typing import cast+import pytestfrom pipelex.core.concepts.concept_structure_blueprint import ConceptStructureBlueprint, ConceptStructureBlueprintFieldType@@ -383,6 +386,140 @@ class TypeMappingTest(StructuredContent):assert result == expected_codeassert issubclass(generated_class, StructuredContent)+ def test_date_field_maps_to_calendar_date(self):+ """`type = "date"` generates a `datetime.date` field (JSON schema `format: date`), no time."""+ structure_blueprint = {+ "issued_on": ConceptStructureBlueprint(description="Issue date", type=ConceptStructureBlueprintFieldType.DATE, required=True),+ }++ result, generated_class = StructureGenerator().generate_from_structure_blueprint(+ class_name="DateFieldTest", structure_blueprint=structure_blueprint+ )++ assert "from datetime import date" in result+ assert 'issued_on: date = Field(..., description="Issue date")' in result+ assert cast("type[StructuredContent]", generated_class).model_json_schema()["properties"]["issued_on"]["format"] == "date"++ def test_datetime_field_maps_to_timestamp(self):+ """`type = "datetime"` generates a `datetime.datetime` field (JSON schema `format: date-time`)."""+ structure_blueprint = {+ "recorded_at": ConceptStructureBlueprint(description="Record timestamp", type=ConceptStructureBlueprintFieldType.DATETIME, required=True),+ }++ result, generated_class = StructureGenerator().generate_from_structure_blueprint(+ class_name="DatetimeFieldTest", structure_blueprint=structure_blueprint+ )++ assert "from datetime import datetime" in result+ assert 'recorded_at: datetime = Field(..., description="Record timestamp")' in result+ assert cast("type[StructuredContent]", generated_class).model_json_schema()["properties"]["recorded_at"]["format"] == "date-time"++ def test_date_field_with_default_round_trips(self):+ """A `type = "date"` field with a date default generates code that evaluates.++ `repr(date(...))` is module-qualified (`datetime.date(...)`), but the generated code imports+ the bare `date` class, so the default must be emitted un-prefixed or the class body raises at eval.+ """+ structure_blueprint = {+ "issued_on": ConceptStructureBlueprint(+ description="Issue date", type=ConceptStructureBlueprintFieldType.DATE, default_value=date(2026, 7, 7)+ ),+ }++ result, generated_class = StructureGenerator().generate_from_structure_blueprint(+ class_name="DateDefaultTest", structure_blueprint=structure_blueprint+ )++ assert "datetime.date(" not in result+ assert cast("type[StructuredContent]", generated_class).model_fields["issued_on"].default == date(2026, 7, 7)++ def test_datetime_field_with_offset_default_round_trips(self):+ """A `type = "datetime"` field with an offset-aware datetime default evaluates and keeps the offset."""+ offset_default = datetime(2026, 7, 7, 15, 40, tzinfo=timezone(timedelta(hours=2)))+ structure_blueprint = {+ "recorded_at": ConceptStructureBlueprint(+ description="Record timestamp", type=ConceptStructureBlueprintFieldType.DATETIME, default_value=offset_default+ ),+ }++ result, generated_class = StructureGenerator().generate_from_structure_blueprint(+ class_name="DatetimeDefaultTest", structure_blueprint=structure_blueprint+ )++ assert "datetime.datetime(" not in result+ assert cast("type[StructuredContent]", generated_class).model_fields["recorded_at"].default == offset_default++ def test_list_of_date_field_maps_to_list_of_calendar_date(self):+ """`type = "list", item_type = "date"` generates a `List[date]` field with the bare-class import, and exec-validates."""+ structure_blueprint = {+ "deadlines": ConceptStructureBlueprint(+ description="Deadlines", type=ConceptStructureBlueprintFieldType.LIST, item_type="date", required=True+ ),+ }++ result, generated_class = StructureGenerator().generate_from_structure_blueprint(+ class_name="DateListTest", structure_blueprint=structure_blueprint+ )++ assert "from datetime import date" in result+ assert 'deadlines: List[date] = Field(..., description="Deadlines")' in result+ assert issubclass(cast("type[StructuredContent]", generated_class), StructuredContent)++ def test_list_of_datetime_field_maps_to_list_of_timestamp(self):+ """`type = "list", item_type = "datetime"` generates a `List[datetime]` field with the bare-class import, and exec-validates."""+ structure_blueprint = {+ "logged_at": ConceptStructureBlueprint(+ description="Log timestamps", type=ConceptStructureBlueprintFieldType.LIST, item_type="datetime", required=True+ ),+ }++ result, generated_class = StructureGenerator().generate_from_structure_blueprint(+ class_name="DatetimeListTest", structure_blueprint=structure_blueprint+ )++ assert "from datetime import datetime" in result+ assert 'logged_at: List[datetime] = Field(..., description="Log timestamps")' in result+ assert issubclass(cast("type[StructuredContent]", generated_class), StructuredContent)++ def test_list_of_datetime_field_with_default_round_trips(self):+ """List defaults containing datetimes are recursively formatted with generated imports."""+ offset_default = datetime(2026, 7, 7, 15, 40, tzinfo=timezone(timedelta(hours=2)))+ structure_blueprint = {+ "logged_at": ConceptStructureBlueprint(+ description="Log timestamps",+ type=ConceptStructureBlueprintFieldType.LIST,+ item_type="datetime",+ default_value=[offset_default],+ ),+ }++ result, generated_class = StructureGenerator().generate_from_structure_blueprint(+ class_name="DatetimeListDefaultTest", structure_blueprint=structure_blueprint+ )++ assert "datetime.datetime(" not in result+ assert cast("type[StructuredContent]", generated_class).model_fields["logged_at"].default == [offset_default]++ def test_dict_of_date_field_with_default_round_trips(self):+ """Dict defaults containing dates are recursively formatted with generated imports."""+ date_default = date(2026, 7, 7)+ structure_blueprint = {+ "deadlines_by_name": ConceptStructureBlueprint(+ description="Deadlines",+ type=ConceptStructureBlueprintFieldType.DICT,+ key_type="str",+ value_type="date",+ default_value={"ship": date_default},+ ),+ }++ result, generated_class = StructureGenerator().generate_from_structure_blueprint(+ class_name="DateDictDefaultTest", structure_blueprint=structure_blueprint+ )++ assert "datetime.date(" not in result+ assert cast("type[StructuredContent]", generated_class).model_fields["deadlines_by_name"].default == {"ship": date_default}+def test_required_vs_optional_fields(self):"""Test that fields can be marked as required vs optional."""structure_blueprint = {@@ -698,7 +835,7 @@ If you want to customize this structure:To regenerate: pipelex build structures <target_directory>"""-from datetime import datetime+from datetime import datefrom enum import Enumfrom pipelex.core.stuffs.structured_content import StructuredContentfrom pydantic import Field@@ -710,7 +847,7 @@ class PersonInfo(StructuredContent):name: str = Field(..., description="The name of the person")age: float = Field(..., description="The age of the person")- birthdate: datetime = Field(..., description="The birthdate of the person")+ birthdate: date = Field(..., description="The birthdate of the person")'''assert result == expected_codediff --git a/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py b/tests/unit/pipelex/core/concepts/test_concept_representation_generator.pyindex a5d2ca4a0..bc3ab54d9 100644--- a/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py+++ b/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py@@ -1,5 +1,6 @@"""Unit tests for ConceptRepresentationGenerator."""+import datetimefrom enum import StrEnumfrom pydantic import Field@@ -144,6 +145,31 @@ class TestGenerateFieldValueBasicTypes:assert isinstance(result, (int, float)), f"Expected int or float, got {type(result)}: {result}"assert result == 1+ def test_date_field_is_valid_iso_date(self) -> None:+ """A datetime.date field generates a real ISO date, not a 'field_date' placeholder."""+ generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)+ result = generator.generate_field_value(datetime.date, field_name="issued_on")+ assert isinstance(result, str)+ assert datetime.date.fromisoformat(result) is not None+ # Extended ISO (YYYY-MM-DD), not the compact all-digit form DateContent rejects.+ assert "-" in result, f"Expected extended ISO date (YYYY-MM-DD), got: {result}"++ def test_datetime_field_is_valid_iso_datetime(self) -> None:+ """A datetime.datetime field generates a real ISO datetime, not a placeholder."""+ generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)+ result = generator.generate_field_value(datetime.datetime, field_name="recorded_at")+ assert isinstance(result, str)+ assert datetime.datetime.fromisoformat(result) is not None+ # A real datetime carries the time component — a date-only string would also parse here.+ assert "T" in result, f"Expected an ISO datetime with a time component, got: {result}"++ def test_time_field_is_valid_iso_time(self) -> None:+ """A datetime.time field generates a real ISO time, not a placeholder."""+ generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)+ result = generator.generate_field_value(datetime.time, field_name="opens_at")+ assert isinstance(result, str)+ assert datetime.time.fromisoformat(result) is not None+def test_float_or_int_union_field(self) -> None:"""Float | int union field generates a numeric value (1), not a string placeholder."""generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)@@ -613,3 +639,45 @@ class TestNumberContentRepresentation:assert isinstance(result, str)assert "number=1" in result, f"Expected 'number=1' in result, got: {result}"assert "number_int" not in result, f"Should not contain string placeholder: {result}"+++# =============================================================================+# Tests for DateContent (native Date concept)+# =============================================================================+++class TestDateContentRepresentation:+ """Test that DateContent generates a round-trippable ISO date example.++ DateContent has a required 'date: datetime.date' field. With include_optional=False (the+ `pipelex build inputs` path), only that field is emitted, and its example must parse back+ into a DateContent so the `build inputs` -> `run` round-trip holds (not a 'date_date' placeholder).+ """++ def test_date_content_json_representation_round_trips(self) -> None:+ """The JSON template for a Date input parses back into a DateContent."""+ from pipelex.core.stuffs.date_content import DateContent # noqa: PLC0415++ generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)+ result = generator.generate_representation("native.Date", structure_class=DateContent, include_optional=False)++ content = result["content"]+ assert isinstance(content, dict)+ assert "date" in content+ # include_optional=False omits the optional `time`: the build-inputs template must never+ # fabricate a time (the Date concept's source-precision contract).+ assert "time" not in content+ # The emitted example must be a real ISO date the DateContent accepts (round-trip).+ rebuilt = DateContent.model_validate(content)+ assert isinstance(rebuilt.date, datetime.date)++ def test_date_content_python_representation_has_no_placeholder(self) -> None:+ """The Python template for a Date input carries no 'date_date' placeholder."""+ from pipelex.core.stuffs.date_content import DateContent # noqa: PLC0415++ generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)+ result = generator.generate_representation("native.Date", structure_class=DateContent, include_optional=False)++ content = result["content"]+ assert isinstance(content, str)+ assert "date_date" not in content, f"Should not contain string placeholder: {content}"diff --git a/tests/unit/pipelex/core/memory/input_shaper/conftest.py b/tests/unit/pipelex/core/memory/input_shaper/conftest.pynew file mode 100644index 000000000..e2f235a94--- /dev/null+++ b/tests/unit/pipelex/core/memory/input_shaper/conftest.py@@ -0,0 +1,49 @@+"""Shared setup for the InputShaper unit tests.++Registers the test concepts (and their structure classes) into the current library so every test+class in this directory can shape inputs against a known signature.+"""++from collections.abc import Generator+from pathlib import Path+from typing import Callable++import pytest++from pipelex.core.concepts.concept_factory import ConceptFactory+from pipelex.core.stuffs.structured_content import StructuredContent+from pipelex.hub import get_class_registry, get_concept_library+from pipelex.system.registries.class_registry_utils import ClassRegistryUtils+from tests.unit.pipelex.core.memory.input_shaper.data import CONCEPT_DEFS, CONCEPT_REFS, REFINING_CLASSES, SHAPER_TEST_DOMAIN++[email protected](scope="class", autouse=True)+def shaper_library(load_test_library: Callable[[list[Path]], None]) -> Generator[None, None, None]:+ load_test_library([Path(__file__).parent])++ # Structured concepts' classes are picked up from data.py; the native refinements are not+ # StructuredContent subclasses, so register them explicitly (mirrors the generated subclass).+ ClassRegistryUtils.register_classes_in_file(+ file_path=Path(__file__).parent / "data.py",+ base_class=StructuredContent,+ is_include_imported=False,+ )+ class_registry = get_class_registry()+ for refining_class in REFINING_CLASSES:+ class_registry.register_class(class_type=refining_class)++ concept_library = get_concept_library()+ for concept_code, structure_class_name, refines in CONCEPT_DEFS:+ concept_library.add_new_concept(+ concept=ConceptFactory.make(+ concept_code=concept_code,+ domain_code=SHAPER_TEST_DOMAIN,+ description=f"Test concept {concept_code} for InputShaper unit tests",+ structure_class_name=structure_class_name,+ refines=refines,+ )+ )++ yield++ concept_library.remove_concepts_by_concept_refs(concept_refs=CONCEPT_REFS)diff --git a/tests/unit/pipelex/core/memory/input_shaper/data.py b/tests/unit/pipelex/core/memory/input_shaper/data.pynew file mode 100644index 000000000..e45bc794b--- /dev/null+++ b/tests/unit/pipelex/core/memory/input_shaper/data.py@@ -0,0 +1,102 @@+"""Shared fixtures data for the InputShaper unit tests.++Defines a small library of concepts covering each D5 arm — Text/Number/YesNo/Date/Image/Document+refinements plus structured concepts — and a helper to build an ``InputStuffSpecs`` fixture from a+list of ``(variable_name, concept_ref, multiplicity)`` entries resolved against the current library.+"""++from pydantic import Field++from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs+from pipelex.core.pipes.stuff_spec.stuff_spec import StuffSpec+from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity+from pipelex.core.stuffs.date_content import DateContent+from pipelex.core.stuffs.document_content import DocumentContent+from pipelex.core.stuffs.image_content import ImageContent+from pipelex.core.stuffs.number_content import NumberContent+from pipelex.core.stuffs.structured_content import StructuredContent+from pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContent++SHAPER_TEST_DOMAIN = "shaper_test"+++class Question(TextContent):+ """Refines native Text — mirrors the subclass the refinement machinery generates for `refines = "Text"`."""+++class Priority(NumberContent):+ """Refines native Number — the subclass generated for `refines = "Number"`."""+++class Verdict(YesNoContent):+ """Refines native YesNo."""+++class Deadline(DateContent):+ """Refines native Date."""+++class Photo(ImageContent):+ """Refines native Image."""+++class Exhibit(DocumentContent):+ """Refines native Document."""+++# Structured test concepts carry a `Shaper`-prefixed name so their registration in the by-name+# global class registry can never be shadowed by an identically-named StructuredContent from another+# test suite (e.g. an integration test's `Person`/`Invoice`). The concept code matches the class name+# (the bottom-up factory maps a prebuilt StuffContent to its concept by class name), so both are+# prefixed; the `shaper_test.<Code>` refs used in the tests are `shaper_test.Shaper<Name>`.+class ShaperInvoice(StructuredContent):+ invoice_number: str = Field(description="The invoice number")+ amount: float = Field(description="The invoice amount")+++class ShaperPerson(StructuredContent):+ name: str = Field(description="The person's name")+++class ShaperWeird(StructuredContent):+ """A pathological structure whose fields are literally `concept` and `content` (collision-rule test)."""++ concept: str = Field(description="A field named concept")+ content: str = Field(description="A field named content")+++# Non-StructuredContent refinements — registered explicitly (the refinement machinery would register+# a subclass like these for a `refines = "<native>"` concept).+REFINING_CLASSES = [Question, Priority, Verdict, Deadline, Photo, Exhibit]++# (concept_code, structure_class_name, refines) for every test concept.+CONCEPT_DEFS: list[tuple[str, str, str | None]] = [+ ("Question", "Question", "native.Text"),+ ("Priority", "Priority", "native.Number"),+ ("Verdict", "Verdict", "native.YesNo"),+ ("Deadline", "Deadline", "native.Date"),+ ("Photo", "Photo", "native.Image"),+ ("Exhibit", "Exhibit", "native.Document"),+ ("ShaperInvoice", "ShaperInvoice", None),+ ("ShaperPerson", "ShaperPerson", None),+ ("ShaperWeird", "ShaperWeird", None),+]++CONCEPT_REFS: list[str] = [f"{SHAPER_TEST_DOMAIN}.{concept_code}" for concept_code, _, _ in CONCEPT_DEFS]+++def build_input_specs(entries: list[tuple[str, str, VariableMultiplicity | None]]) -> InputStuffSpecs:+ """Build an ``InputStuffSpecs`` from ``(variable_name, concept_ref, multiplicity)`` entries.++ Concepts are resolved against the current concept library, so this must run after the+ ``shaper_library`` fixture has registered the test concepts.+ """+ from pipelex.hub import get_concept_library # noqa: PLC0415++ library = get_concept_library()+ root: dict[str, StuffSpec] = {}+ for variable_name, concept_ref, multiplicity in entries:+ concept = library.get_required_concept(concept_ref=concept_ref)+ root[variable_name] = StuffSpec(concept=concept, multiplicity=multiplicity)+ return InputStuffSpecs(root=root)diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py b/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.pynew file mode 100644index 000000000..c9bffda83--- /dev/null+++ b/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py@@ -0,0 +1,98 @@+"""Unit tests for CSV-by-signature (D11 compounding): a bare tabular path — or the exact+``{"url": <tabular path>}`` wrapper — under a declared structured list input (``Person[]``)+reads the table into a ``ListContent[declared]`` with no envelope. Detection is conservative:+non-tabular values, singular declarations, and record dicts with sibling keys all fall through+to the normal shaping arms.+"""++from pathlib import Path+from typing import Any, cast++import pytest++from pipelex.core.memory.exceptions import MultiplicityCountMismatchError, StructureValidationError, WrongScalarKindError+from pipelex.core.memory.input_shaper import InputShaper+from pipelex.core.stuffs.list_content import ListContent+from pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.tools.tabular.exceptions import CsvError+from tests.unit.pipelex.core.memory.input_shaper.data import ShaperPerson, build_input_specs++PEOPLE_CSV_CONTENT = "name\nAda Lovelace\nGrace Hopper\n"+++class TestInputShaperCsvBySignature:+ @pytest.fixture+ def people_csv(self, tmp_path: Path) -> Path:+ csv_path = tmp_path / "people.csv"+ csv_path.write_text(PEOPLE_CSV_CONTENT, encoding="utf-8")+ return csv_path++ def _assert_people_list(self, working_memory_stuff_content: StuffContent) -> None:+ assert isinstance(working_memory_stuff_content, ListContent)+ items = cast("ListContent[StuffContent]", working_memory_stuff_content).items+ assert [item.name for item in items if isinstance(item, ShaperPerson)] == ["Ada Lovelace", "Grace Hopper"]++ def test_bare_csv_path_under_declared_list(self, people_csv: Path):+ """A bare absolute CSV path under `ShaperPerson[]` reads rows into ListContent[ShaperPerson]."""+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])+ working_memory = InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs)++ people_stuff = working_memory.get_stuff("people")+ assert people_stuff.concept.concept_ref == "shaper_test.ShaperPerson"+ self._assert_people_list(people_stuff.content)++ def test_url_dict_csv_under_declared_list(self, people_csv: Path):+ """The exact {"url": <csv>} wrapper under `ShaperPerson[]` reads the same table — no envelope."""+ value: dict[str, Any] = {"url": str(people_csv)}+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])+ working_memory = InputShaper.shape({"people": value}, input_specs=input_specs)++ people_stuff = working_memory.get_stuff("people")+ assert people_stuff.concept.concept_ref == "shaper_test.ShaperPerson"+ self._assert_people_list(people_stuff.content)++ @pytest.mark.usefixtures("people_csv")+ def test_relative_csv_resolves_against_base_dir(self, tmp_path: Path):+ """A bare relative CSV path resolves against inputs_base_dir before the table is read."""+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])+ working_memory = InputShaper.shape({"people": "people.csv"}, input_specs=input_specs, inputs_base_dir=tmp_path)++ self._assert_people_list(working_memory.get_stuff("people").content)++ def test_fixed_count_matching_rows(self, people_csv: Path):+ """A `ShaperPerson[2]` input accepts a two-row CSV."""+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", 2)])+ working_memory = InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs)++ self._assert_people_list(working_memory.get_stuff("people").content)++ def test_fixed_count_mismatch_raises(self, people_csv: Path):+ """A `ShaperPerson[3]` input rejects a two-row CSV with the D2 count-mismatch error."""+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", 3)])+ with pytest.raises(MultiplicityCountMismatchError, match="'people'"):+ InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs)++ def test_csv_under_singular_is_wrong_scalar_kind(self, people_csv: Path):+ """A CSV names a TABLE; under a singular `ShaperPerson` a bare path is a wrong-kind error."""+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", None)])+ with pytest.raises(WrongScalarKindError, match="'people'"):+ InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs)++ def test_non_tabular_string_falls_through(self):+ """A bare non-tabular string under `ShaperPerson[]` is NOT hijacked as a table — normal D5 error."""+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])+ with pytest.raises(WrongScalarKindError, match="'people'"):+ InputShaper.shape({"people": "people.txt"}, input_specs=input_specs)++ def test_url_dict_with_sibling_keys_stays_record(self, people_csv: Path):+ """A record dict that merely HAS a url field is not a table ref — validated as a record."""+ value: dict[str, Any] = {"url": str(people_csv), "label": "roster"}+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])+ with pytest.raises(StructureValidationError, match="'people'"):+ InputShaper.shape({"people": value}, input_specs=input_specs)++ def test_remote_csv_url_raises_csv_error(self):+ """A remote tabular url is rejected loudly (local paths only in v1), not read or ignored."""+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])+ with pytest.raises(CsvError, match="local file paths only"):+ InputShaper.shape({"people": "https://example.com/people.csv"}, input_specs=input_specs)diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_errors.py b/tests/unit/pipelex/core/memory/input_shaper/test_errors.pynew file mode 100644index 000000000..884c63f6f--- /dev/null+++ b/tests/unit/pipelex/core/memory/input_shaper/test_errors.py@@ -0,0 +1,85 @@+from typing import Any++import pytest++from pipelex import log+from pipelex.core.memory.exceptions import (+ ExplicitConceptIncompatibleError,+ InputShapingError,+ ListWhereSingularError,+ MultiplicityCountMismatchError,+ NullInputError,+ StructureValidationError,+ UnknownInputNameError,+ WrongScalarKindError,+)+from pipelex.core.memory.input_shaper import InputShaper+from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity+from tests.unit.pipelex.core.memory.input_shaper.data import build_input_specs++# (test_name, concept_ref, multiplicity, provided_value, expected_exception, error_match)+# Every case here is a D4 shaping error whose message carries the rendered expected-shape template+# (asserted unconditionally below). The D8 unknown-name error, which carries no shape, is tested separately.+ERROR_CASES: list[tuple[str, str, VariableMultiplicity | None, Any, type[InputShapingError], str]] = [+ # D5 wrong scalar kind — no cross-type parse: "42" stays a string, never a number.+ ("wrong-str-for-number", "shaper_test.Priority", None, "42", WrongScalarKindError, "expects a number"),+ ("wrong-int-for-text", "native.Text", None, 5, WrongScalarKindError, "expects a string"),+ ("wrong-bool-for-text", "native.Text", None, True, WrongScalarKindError, "expects a string"),+ # D9 bool never leaks into the Number arm (bool is a subclass of int).+ ("wrong-bool-for-number", "shaper_test.Priority", None, True, WrongScalarKindError, "expects a number"),+ # D9 a top-level null is a hard error (absence = omit the key).+ ("null-top-level", "native.Text", None, None, NullInputError, "null"),+ # D2 a list where a singular is declared is ambiguous.+ ("list-where-singular", "shaper_test.Question", None, ["a", "b"], ListWhereSingularError, "single"),+ # D2 fixed-count mismatch — too few, and a single value for [2].+ ("count-mismatch-list-too-few", "shaper_test.Question", 2, ["a"], MultiplicityCountMismatchError, "exactly 2"),+ ("count-mismatch-single-for-two", "shaper_test.Question", 2, "solo", MultiplicityCountMismatchError, "exactly 2"),+ # D4 structure validation — a missing required field surfaces as a shaping error.+ ("structure-missing-field", "shaper_test.ShaperInvoice", None, {"invoice_number": "INV-1"}, StructureValidationError, "could not be built"),+ # D4 a non-ISO date string is the right kind but an invalid value.+ ("non-iso-date", "shaper_test.Deadline", None, "March 7, 2026", StructureValidationError, "ISO 8601"),+ # D6 an explicit envelope naming an incompatible concept.+ (+ "explicit-incompatible",+ "shaper_test.Priority",+ None,+ {"concept": "shaper_test.Question", "content": "hi"},+ ExplicitConceptIncompatibleError,+ "not compatible",+ ),+]+++class TestInputShaperErrors:+ @pytest.mark.parametrize(+ ("test_name", "concept_ref", "multiplicity", "provided_value", "expected_exception", "error_match"),+ ERROR_CASES,+ )+ def test_error_case(+ self,+ test_name: str,+ concept_ref: str,+ multiplicity: VariableMultiplicity | None,+ provided_value: Any,+ expected_exception: type[InputShapingError],+ error_match: str,+ ) -> None:+ log.info(f"Testing error case: {test_name}")+ input_specs = build_input_specs([("my_input", concept_ref, multiplicity)])++ with pytest.raises(expected_exception, match=error_match) as exc_info:+ InputShaper.shape({"my_input": provided_value}, input_specs=input_specs)++ # D4 mandates the rendered expected-shape template appears in every shaping-error message.+ assert "Expected shape:" in str(exc_info.value), f"Missing rendered shape for {test_name}"++ def test_unknown_input_name_is_error(self) -> None:+ """D8: a provided name absent from the signature is a hard error that lists the declared names."""+ input_specs = build_input_specs([("question", "native.Text", None)])++ with pytest.raises(UnknownInputNameError, match="not declared") as exc_info:+ InputShaper.shape({"quesion": "typo"}, input_specs=input_specs)++ message = str(exc_info.value)+ assert "'question'" in message, "Unknown-name error should list the declared inputs"+ assert "'quesion'" in message, "Unknown-name error should name the offending input"diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py b/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.pynew file mode 100644index 000000000..b5f4de506--- /dev/null+++ b/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py@@ -0,0 +1,136 @@+import pytest++from pipelex import log, pretty_print+from pipelex.core.memory.exceptions import (+ ExplicitConceptIncompatibleError,+ ListWhereSingularError,+ MultiplicityCountMismatchError,+)+from pipelex.core.memory.input_shaper import InputShaper+from pipelex.core.stuffs.list_content import ListContent+from pipelex.core.stuffs.text_content import TextContent+from tests.unit.pipelex.core.memory.input_shaper.data import Question, ShaperInvoice, ShaperWeird, build_input_specs+++class TestInputShaperExplicitForms:+ def test_envelope_structured_compatible(self) -> None:+ """D6: the {concept, content} envelope still works and is now compat-checked against the signature."""+ input_specs = build_input_specs([("invoice", "shaper_test.ShaperInvoice", None)])+ provided = {"concept": "shaper_test.ShaperInvoice", "content": {"invoice_number": "INV-001", "amount": 1250.0}}++ working_memory = InputShaper.shape({"invoice": provided}, input_specs=input_specs)++ stuff = working_memory.root["invoice"]+ pretty_print(stuff, title="envelope structured")+ assert stuff.concept.concept_ref == "shaper_test.ShaperInvoice"+ assert stuff.content == ShaperInvoice(invoice_number="INV-001", amount=1250.0)++ def test_envelope_refining_concept_wins(self) -> None:+ """D6: when the envelope names a concept that refines the declared one, the more specific concept wins."""+ input_specs = build_input_specs([("answer", "native.Text", None)])+ provided = {"concept": "shaper_test.Question", "content": "What are the fees?"}++ working_memory = InputShaper.shape({"answer": provided}, input_specs=input_specs)++ stuff = working_memory.root["answer"]+ pretty_print(stuff, title="envelope refining wins")+ # The declared lower bound is native.Text, but the caller volunteered the more specific Question.+ assert stuff.concept.concept_ref == "shaper_test.Question"+ assert stuff.content == TextContent(text="What are the fees?")++ def test_prebuilt_stuff_content_object(self) -> None:+ """D6: a directly-provided StuffContent keeps today's behavior, plus the compat check."""+ input_specs = build_input_specs([("invoice", "shaper_test.ShaperInvoice", None)])+ provided = ShaperInvoice(invoice_number="INV-002", amount=99.0)++ working_memory = InputShaper.shape({"invoice": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])++ stuff = working_memory.root["invoice"]+ pretty_print(stuff, title="prebuilt object")+ assert stuff.concept.concept_ref == "shaper_test.ShaperInvoice"+ assert stuff.content == ShaperInvoice(invoice_number="INV-002", amount=99.0)++ def test_list_of_prebuilt_stuff_content_items(self) -> None:+ """D6: a bare list of already-built StuffContent items (Case 1.4) shapes element-wise, no regression.++ Each item keeps today's behavior — concept inferred from its class, then compat-checked — so a+ Python-API caller passing typed content in a list works exactly like the wrapped ListContent form.+ """+ input_specs = build_input_specs([("questions", "shaper_test.Question", True)])+ provided = [Question(text="a"), Question(text="b")]++ working_memory = InputShaper.shape({"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])++ stuff = working_memory.root["questions"]+ pretty_print(stuff, title="list of prebuilt StuffContent")+ assert stuff.concept.concept_ref == "shaper_test.Question"+ assert stuff.content == ListContent(items=[Question(text="a"), Question(text="b")])++ def test_list_of_prebuilt_incompatible_item_raises(self) -> None:+ """D6: an already-built item whose concept is incompatible with the declared item concept is a D4 error."""+ input_specs = build_input_specs([("priorities", "shaper_test.Priority", True)])+ provided = [Question(text="a")]++ with pytest.raises(ExplicitConceptIncompatibleError, match="not compatible"):+ InputShaper.shape({"priorities": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])++ def test_explicit_list_into_singular_raises(self) -> None:+ """D2: an explicit ListContent (or envelope-with-list) must not fill a singular-declared slot.++ Without the reconcile in `_shape_explicit`, this list would be *silently* stored into the+ singular slot (the D6 compat check alone never looks at multiplicity).+ """+ input_specs = build_input_specs([("question", "shaper_test.Question", None)])+ provided: ListContent[Question] = ListContent(items=[Question(text="a"), Question(text="b")])++ with pytest.raises(ListWhereSingularError, match="declares a single"):+ InputShaper.shape({"question": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])++ def test_explicit_list_wrong_fixed_count_raises(self) -> None:+ """D2: an explicit ListContent whose length differs from a declared [N] count is a D4 error."""+ input_specs = build_input_specs([("questions", "shaper_test.Question", 2)])+ provided: ListContent[Question] = ListContent(items=[Question(text="only-one")])++ with pytest.raises(MultiplicityCountMismatchError, match="exactly 2 items"):+ InputShaper.shape({"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])++ def test_explicit_list_into_list_slot_ok(self) -> None:+ """D2/D6: an explicit ListContent whose length matches a declared list slot shapes cleanly."""+ input_specs = build_input_specs([("questions", "shaper_test.Question", True)])+ provided: ListContent[Question] = ListContent(items=[Question(text="a"), Question(text="b")])++ working_memory = InputShaper.shape({"questions": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])++ stuff = working_memory.root["questions"]+ pretty_print(stuff, title="explicit list into list slot")+ assert stuff.concept.concept_ref == "shaper_test.Question"+ assert stuff.content == ListContent(items=[Question(text="a"), Question(text="b")])++ def test_explicit_list_content_into_dynamic_slot_ok(self) -> None:+ """D5/D6: a Dynamic slot keeps bottom-up list behavior for prebuilt ListContent."""+ input_specs = build_input_specs([("payload", "native.Dynamic", None)])+ provided: ListContent[Question] = ListContent(items=[Question(text="a"), Question(text="b")])++ working_memory = InputShaper.shape({"payload": provided}, input_specs=input_specs, search_domain_codes=["shaper_test"])++ stuff = working_memory.root["payload"]+ pretty_print(stuff, title="explicit list into Dynamic slot")+ assert stuff.concept.concept_ref == "shaper_test.Question"+ assert stuff.content == ListContent(items=[Question(text="a"), Question(text="b")])++ def test_envelope_collision_rule_nested_escape_hatch(self) -> None:+ """D6: a dict with exactly {concept, content} is ALWAYS an envelope, even for a structure with those fields.++ The escape hatch for a structure literally named with `concept`/`content` fields is the nested+ envelope: the inner content dict carries the real field values.+ """+ log.info("Testing the {concept, content} collision rule")+ input_specs = build_input_specs([("weird", "shaper_test.ShaperWeird", None)])+ provided = {"concept": "shaper_test.ShaperWeird", "content": {"concept": "x", "content": "y"}}++ working_memory = InputShaper.shape({"weird": provided}, input_specs=input_specs)++ stuff = working_memory.root["weird"]+ pretty_print(stuff, title="collision rule")+ assert stuff.concept.concept_ref == "shaper_test.ShaperWeird"+ assert stuff.content == ShaperWeird(concept="x", content="y")diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_file_paths.py b/tests/unit/pipelex/core/memory/input_shaper/test_file_paths.pynew file mode 100644index 000000000..5a2d9123f--- /dev/null+++ b/tests/unit/pipelex/core/memory/input_shaper/test_file_paths.py@@ -0,0 +1,107 @@+"""Unit tests for the shaper's D3 file-path arm: bare relative local paths for Image/Document-+refining inputs resolve against ``inputs_base_dir`` (the inputs file's parent, threaded from the+CLI). Absolute paths, remote/scheme URLs, and the ``{"url": ...}`` dict form (owned by the CLI's+signature-blind url-key walk) are never rewritten.+"""++from pathlib import Path+from typing import TYPE_CHECKING, Any, cast++import pytest++from pipelex.core.memory.input_shaper import InputShaper+from pipelex.core.stuffs.list_content import ListContent+from tests.unit.pipelex.core.memory.input_shaper.data import Exhibit, Photo, build_input_specs++if TYPE_CHECKING:+ from pipelex.core.stuffs.stuff_content import StuffContent+++class TestInputShaperFilePaths:+ def test_bare_relative_path_resolves_against_base_dir(self, tmp_path: Path):+ """A bare relative path for an Image-refining input becomes the base_dir-resolved path."""+ input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])+ working_memory = InputShaper.shape({"photo": "photo.jpg"}, input_specs=input_specs, inputs_base_dir=tmp_path)++ photo_stuff = working_memory.get_stuff("photo")+ assert photo_stuff.concept.concept_ref == "shaper_test.Photo"+ assert isinstance(photo_stuff.content, Photo)+ assert photo_stuff.content.url == str(tmp_path / "photo.jpg")++ def test_bare_absolute_path_untouched(self, tmp_path: Path):+ """An absolute path is never rewritten, base_dir or not."""+ absolute_path = str(tmp_path / "elsewhere" / "photo.jpg")+ input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])+ working_memory = InputShaper.shape({"photo": absolute_path}, input_specs=input_specs, inputs_base_dir=tmp_path)++ photo_stuff = working_memory.get_stuff("photo")+ assert isinstance(photo_stuff.content, Photo)+ assert photo_stuff.content.url == absolute_path++ def test_bare_relative_path_without_base_dir_untouched(self):+ """No base_dir (in-process / inline-JSON callers): a relative path keeps today's CWD contract."""+ input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])+ working_memory = InputShaper.shape({"photo": "photo.jpg"}, input_specs=input_specs)++ photo_stuff = working_memory.get_stuff("photo")+ assert isinstance(photo_stuff.content, Photo)+ assert photo_stuff.content.url == "photo.jpg"++ @pytest.mark.parametrize(+ "url_value",+ [+ "https://example.com/photo.jpg",+ "s3://bucket/photo.jpg",+ "data:image/png;base64,iVBORw0KGgo=",+ "pipelex-storage://objects/photo.jpg",+ ],+ )+ def test_remote_and_scheme_urls_untouched(self, tmp_path: Path, url_value: str):+ """Remote URLs and scheme-qualified URIs are not local paths — never rewritten."""+ input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])+ working_memory = InputShaper.shape({"photo": url_value}, input_specs=input_specs, inputs_base_dir=tmp_path)++ photo_stuff = working_memory.get_stuff("photo")+ assert isinstance(photo_stuff.content, Photo)+ assert photo_stuff.content.url == url_value++ def test_list_items_resolve_element_wise(self, tmp_path: Path):+ """Each bare relative item of a Document[] input resolves; absolute items stay untouched."""+ absolute_path = str(tmp_path / "other" / "b.pdf")+ input_specs = build_input_specs([("exhibits", "shaper_test.Exhibit", True)])+ working_memory = InputShaper.shape({"exhibits": ["a.pdf", absolute_path]}, input_specs=input_specs, inputs_base_dir=tmp_path)++ exhibits_stuff = working_memory.get_stuff("exhibits")+ assert exhibits_stuff.concept.concept_ref == "shaper_test.Exhibit"+ exhibits_content: StuffContent = exhibits_stuff.content+ assert isinstance(exhibits_content, ListContent)+ items = cast("ListContent[StuffContent]", exhibits_content).items+ assert [item.url for item in items if isinstance(item, Exhibit)] == [str(tmp_path / "a.pdf"), absolute_path]++ def test_url_dict_form_not_reresolved_by_shaper(self, tmp_path: Path):+ """The {"url": ...} dict form is owned by the CLI's url-key walk — the shaper leaves it as-is."""+ value: dict[str, Any] = {"url": "photo.jpg"}+ input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])+ working_memory = InputShaper.shape({"photo": value}, input_specs=input_specs, inputs_base_dir=tmp_path)++ photo_stuff = working_memory.get_stuff("photo")+ assert isinstance(photo_stuff.content, Photo)+ assert photo_stuff.content.url == "photo.jpg"++ def test_bare_tilde_path_expands_to_home_not_base_dir(self, tmp_path: Path):+ """A ~-prefixed path is home-anchored: it expands to the home dir, never joined onto base_dir."""+ input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])+ working_memory = InputShaper.shape({"photo": "~/photo.jpg"}, input_specs=input_specs, inputs_base_dir=tmp_path)++ photo_stuff = working_memory.get_stuff("photo")+ assert isinstance(photo_stuff.content, Photo)+ assert photo_stuff.content.url == str(Path("~/photo.jpg").expanduser())++ def test_bare_tilde_path_expands_without_base_dir(self):+ """No base_dir: a ~-prefixed path still expands to home (~ is home-anchored, not CWD-relative)."""+ input_specs = build_input_specs([("photo", "shaper_test.Photo", None)])+ working_memory = InputShaper.shape({"photo": "~/photo.jpg"}, input_specs=input_specs)++ photo_stuff = working_memory.get_stuff("photo")+ assert isinstance(photo_stuff.content, Photo)+ assert photo_stuff.content.url == str(Path("~/photo.jpg").expanduser())diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_multiplicity.py b/tests/unit/pipelex/core/memory/input_shaper/test_multiplicity.pynew file mode 100644index 000000000..244561feb--- /dev/null+++ b/tests/unit/pipelex/core/memory/input_shaper/test_multiplicity.py@@ -0,0 +1,114 @@+import datetime+from typing import Any++import pytest++from pipelex import log, pretty_print+from pipelex.core.memory.input_shaper import InputShaper+from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity+from pipelex.core.stuffs.list_content import ListContent+from pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.core.stuffs.text_content import TextContent+from tests.unit.pipelex.core.memory.input_shaper.data import Deadline, Question, ShaperPerson, build_input_specs++# (test_name, concept_ref, multiplicity, provided_value, expected_concept_ref, expected_list_content)+MULTIPLICITY_CASES: list[tuple[str, str, VariableMultiplicity | None, Any, str, ListContent[StuffContent]]] = [+ # Variable list, element-wise shaping into ListContent[declared].+ (+ "variable-list-refining",+ "shaper_test.Question",+ True,+ ["a", "b"],+ "shaper_test.Question",+ ListContent(items=[Question(text="a"), Question(text="b")]),+ ),+ (+ "variable-list-native-text",+ "native.Text",+ True,+ ["a", "b"],+ "native.Text",+ ListContent(items=[TextContent(text="a"), TextContent(text="b")]),+ ),+ # A single bare value auto-wraps into a one-item list (D2).+ (+ "variable-list-auto-wrap-single",+ "shaper_test.Question",+ True,+ "solo",+ "shaper_test.Question",+ ListContent(items=[Question(text="solo")]),+ ),+ # An empty list is legal and yields an empty ListContent typed with the declared item concept (D2).+ (+ "variable-list-empty",+ "shaper_test.Question",+ True,+ [],+ "shaper_test.Question",+ ListContent(items=[]),+ ),+ # Fixed count [N] validates the count; a single value satisfies [1].+ (+ "fixed-count-two",+ "shaper_test.Question",+ 2,+ ["a", "b"],+ "shaper_test.Question",+ ListContent(items=[Question(text="a"), Question(text="b")]),+ ),+ (+ "fixed-count-one-single",+ "shaper_test.Question",+ 1,+ "solo",+ "shaper_test.Question",+ ListContent(items=[Question(text="solo")]),+ ),+ # A list of dicts shapes element-wise into a structured list, no envelope.+ (+ "variable-list-of-dicts",+ "shaper_test.ShaperPerson",+ True,+ [{"name": "Alice"}, {"name": "Bob"}],+ "shaper_test.ShaperPerson",+ ListContent(items=[ShaperPerson(name="Alice"), ShaperPerson(name="Bob")]),+ ),+ # A top-level list of bare date objects (e.g. a TOML `deadlines = [2026-01-01, 2026-02-02]` array+ # the loader leaves untouched) shapes element-wise into ListContent[DateContent] under a declared+ # Date-refining `[]` input — the case `case1-bare-date-arm-gap.md` deferred, now closed by the shaper.+ (+ "variable-list-of-date-objects",+ "shaper_test.Deadline",+ True,+ [datetime.date(2026, 1, 1), datetime.date(2026, 2, 2)],+ "shaper_test.Deadline",+ ListContent(items=[Deadline(date=datetime.date(2026, 1, 1)), Deadline(date=datetime.date(2026, 2, 2))]),+ ),+]+++class TestInputShaperMultiplicity:+ @pytest.mark.parametrize(+ ("test_name", "concept_ref", "multiplicity", "provided_value", "expected_concept_ref", "expected_list_content"),+ MULTIPLICITY_CASES,+ )+ def test_multiplicity_case(+ self,+ test_name: str,+ concept_ref: str,+ multiplicity: VariableMultiplicity | None,+ provided_value: Any,+ expected_concept_ref: str,+ expected_list_content: ListContent[StuffContent],+ ) -> None:+ log.info(f"Testing multiplicity case: {test_name}")+ input_specs = build_input_specs([("my_input", concept_ref, multiplicity)])++ working_memory = InputShaper.shape({"my_input": provided_value}, input_specs=input_specs)++ stuff = working_memory.root["my_input"]+ pretty_print(stuff, title=f"Result for {test_name}")+ assert stuff.concept.concept_ref == expected_concept_ref, f"Wrong concept for {test_name}"+ # Equality subsumes the type check: a ListContent never equals a non-ListContent content.+ assert stuff.content == expected_list_content, f"Wrong list content for {test_name}"diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_scalar_arms.py b/tests/unit/pipelex/core/memory/input_shaper/test_scalar_arms.pynew file mode 100644index 000000000..79e081bc8--- /dev/null+++ b/tests/unit/pipelex/core/memory/input_shaper/test_scalar_arms.py@@ -0,0 +1,80 @@+import datetime+from typing import Any++import pytest++from pipelex import log, pretty_print+from pipelex.core.memory.input_shaper import InputShaper+from pipelex.core.stuffs.date_content import DateContent+from pipelex.core.stuffs.image_content import ImageContent+from pipelex.core.stuffs.number_content import NumberContent+from pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContent+from tests.unit.pipelex.core.memory.input_shaper.data import (+ Deadline,+ Exhibit,+ Photo,+ Priority,+ Question,+ ShaperInvoice,+ Verdict,+ build_input_specs,+)++# (test_name, concept_ref, provided_value, expected_concept_ref, expected_content)+SCALAR_ARM_CASES: list[tuple[str, str, Any, str, StuffContent]] = [+ # D5 Text-refining: a bare string becomes the DECLARED concept, typed as its refining subclass.+ ("text-native", "native.Text", "hello", "native.Text", TextContent(text="hello")),+ ("text-refining", "shaper_test.Question", "What are the fees?", "shaper_test.Question", Question(text="What are the fees?")),+ # D5 Number-refining: int and float accepted (bool excluded, see errors).+ ("number-native-int", "native.Number", 3, "native.Number", NumberContent(number=3)),+ ("number-native-float", "native.Number", 3.5, "native.Number", NumberContent(number=3.5)),+ ("number-refining", "shaper_test.Priority", 3, "shaper_test.Priority", Priority(number=3)),+ # D5 YesNo-refining: a bare boolean.+ ("yesno-native-true", "native.YesNo", True, "native.YesNo", YesNoContent(yes_no=True)),+ ("yesno-refining-false", "shaper_test.Verdict", False, "shaper_test.Verdict", Verdict(yes_no=False)),+ # D5 Date-refining: an ISO string or a date object.+ ("date-native-iso", "native.Date", "2026-07-07", "native.Date", DateContent(date=datetime.date(2026, 7, 7))),+ ("date-refining-obj", "shaper_test.Deadline", datetime.date(2026, 8, 6), "shaper_test.Deadline", Deadline(date=datetime.date(2026, 8, 6))),+ # D3/D5 Image/Document-refining: a bare string (URL/path) or a {"url": ...} dict.+ ("image-refining-str", "shaper_test.Photo", "photo.jpg", "shaper_test.Photo", Photo(url="photo.jpg")),+ ("image-native-dict", "native.Image", {"url": "pic.png"}, "native.Image", ImageContent(url="pic.png")),+ ("document-refining-str", "shaper_test.Exhibit", "doc.pdf", "shaper_test.Exhibit", Exhibit(url="doc.pdf")),+ # D5 Structured: a bare dict validated by pydantic against the declared structure class.+ (+ "structured-dict",+ "shaper_test.ShaperInvoice",+ {"invoice_number": "INV-001", "amount": 1250.0},+ "shaper_test.ShaperInvoice",+ ShaperInvoice(invoice_number="INV-001", amount=1250.0),+ ),+ # D5 Dynamic/Anything/out-of-matrix natives: bottom-up passthrough (today's behavior).+ ("dynamic-str-bottom-up", "native.Dynamic", "hi", "native.Text", TextContent(text="hi")),+ ("anything-str-bottom-up", "native.Anything", "hi", "native.Text", TextContent(text="hi")),+ ("html-out-of-matrix-bottom-up", "native.Html", "hi", "native.Text", TextContent(text="hi")),+]+++class TestInputShaperScalarArms:+ @pytest.mark.parametrize(+ ("test_name", "concept_ref", "provided_value", "expected_concept_ref", "expected_content"),+ SCALAR_ARM_CASES,+ )+ def test_scalar_arm(+ self,+ test_name: str,+ concept_ref: str,+ provided_value: Any,+ expected_concept_ref: str,+ expected_content: StuffContent,+ ) -> None:+ log.info(f"Testing scalar arm case: {test_name}")+ input_specs = build_input_specs([("my_input", concept_ref, None)])++ working_memory = InputShaper.shape({"my_input": provided_value}, input_specs=input_specs)++ stuff = working_memory.root["my_input"]+ pretty_print(stuff, title=f"Result for {test_name}")+ assert stuff.concept.concept_ref == expected_concept_ref, f"Wrong concept for {test_name}"+ assert stuff.content == expected_content, f"Wrong content for {test_name}"diff --git a/tests/unit/pipelex/core/pipes/test_input_renderer_light.py b/tests/unit/pipelex/core/pipes/test_input_renderer_light.pynew file mode 100644index 000000000..32214f71d--- /dev/null+++ b/tests/unit/pipelex/core/pipes/test_input_renderer_light.py@@ -0,0 +1,126 @@+"""Unit tests for the light (signature-driven) inputs-template transform and its TOML serializer.++These cover the pure pieces of the D11 flip in isolation — no library, no concept resolution:++- ``_delighten_entry`` turns one envelope entry (``{"concept", "content"}``) into the light value+ the shaper accepts, dispatched on the input's already-resolved ``InputKind`` (a scalar unwraps to+ its bare field, a structured value keeps its content dict, a dynamic value keeps the whole+ envelope because bottom-up shaping still needs it).+- ``serialize_inputs_template_to_toml(..., light=True)`` lays a light template out with inline+ tables (so a bare scalar declared after a structured value stays at the top level and the document+ is valid TOML) and attaches ``# concept: ...`` comments.++The end-to-end path (real ``resolve_input_kind`` against a loaded bundle) is covered by the golden+integration test.+"""++from __future__ import annotations++from typing import Any++import tomli++from pipelex.core.memory.input_shaper import InputKind+from pipelex.core.pipes.inputs.input_renderer import (+ _delighten_entry, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+ serialize_inputs_template_to_toml,+)+++class TestInputRendererLight:+ def test_text_scalar_unwraps_to_bare_string(self) -> None:+ """A Text-refining input's ``{"text": ...}`` content becomes the bare string."""+ entry = {"concept": "demo.Question", "content": {"text": "text_value"}}+ assert _delighten_entry(entry, kind=InputKind.TEXT) == "text_value"++ def test_number_scalar_unwraps_to_bare_number(self) -> None:+ """A Number-refining input's ``{"number": ...}`` content becomes the bare number."""+ entry = {"concept": "demo.Priority", "content": {"number": 1}}+ assert _delighten_entry(entry, kind=InputKind.NUMBER) == 1++ def test_yes_no_scalar_unwraps_to_bare_bool(self) -> None:+ """A YesNo-refining input's ``{"yes_no": ...}`` content becomes the bare boolean."""+ entry = {"concept": "demo.Flag", "content": {"yes_no": False}}+ assert _delighten_entry(entry, kind=InputKind.YES_NO) is False++ def test_date_scalar_unwraps_to_bare_iso_string(self) -> None:+ """A Date-refining input's ``{"date": ...}`` content becomes the bare ISO string."""+ entry = {"concept": "demo.When", "content": {"date": "2026-01-01"}}+ assert _delighten_entry(entry, kind=InputKind.DATE) == "2026-01-01"++ def test_image_scalar_unwraps_to_bare_url(self) -> None:+ """An Image-refining input's ``{"url": ...}`` content becomes the bare URL string."""+ entry = {"concept": "demo.Photo", "content": {"url": "https://example.invalid/p.jpg"}}+ assert _delighten_entry(entry, kind=InputKind.IMAGE) == "https://example.invalid/p.jpg"++ def test_document_scalar_unwraps_to_bare_url(self) -> None:+ """A Document-refining input's ``{"url": ...}`` content becomes the bare URL string."""+ entry = {"concept": "demo.Exhibit", "content": {"url": "https://example.invalid/d.pdf"}}+ assert _delighten_entry(entry, kind=InputKind.DOCUMENT) == "https://example.invalid/d.pdf"++ def test_structured_keeps_content_dict(self) -> None:+ """A structured input keeps its content dict verbatim (no envelope, no unwrap)."""+ entry = {"concept": "demo.Invoice", "content": {"invoice_number": "INV-1", "amount": 0.0}}+ assert _delighten_entry(entry, kind=InputKind.STRUCTURED) == {"invoice_number": "INV-1", "amount": 0.0}++ def test_structured_multiple_keeps_list_of_dicts(self) -> None:+ """A structured list input keeps its ``[content]`` list verbatim."""+ entry: dict[str, Any] = {"concept": "demo.Person", "content": [{"name": "name_value", "job": "job_value"}]}+ assert _delighten_entry(entry, kind=InputKind.STRUCTURED) == [{"name": "name_value", "job": "job_value"}]++ def test_scalar_multiple_unwraps_element_wise(self) -> None:+ """A scalar list input unwraps every item to its bare field value."""+ entry: dict[str, Any] = {"concept": "demo.Tag", "content": [{"text": "t1"}, {"text": "t2"}]}+ assert _delighten_entry(entry, kind=InputKind.TEXT) == ["t1", "t2"]++ def test_scalar_empty_list_stays_empty(self) -> None:+ """A scalar list input with an empty content list stays an empty list."""+ entry: dict[str, Any] = {"concept": "demo.Tag", "content": []}+ assert _delighten_entry(entry, kind=InputKind.TEXT) == []++ def test_dynamic_keeps_the_whole_envelope(self) -> None:+ """A Dynamic/out-of-matrix input keeps the ceremonial envelope: bottom-up shaping needs it."""+ entry = {"concept": "native.Anything", "content": {"whatever": "value"}}+ assert _delighten_entry(entry, kind=InputKind.DYNAMIC) == entry++ def test_scalar_with_extra_required_fields_falls_back_to_envelope(self) -> None:+ """A scalar whose content is not a single field can't be delightened losslessly — keep the envelope."""+ entry = {"concept": "demo.Weird", "content": {"text": "t", "extra": "x"}}+ assert _delighten_entry(entry, kind=InputKind.TEXT) == entry++ def test_light_toml_round_trips_and_keeps_declaration_order(self) -> None:+ """A light template with a bare scalar declared AFTER a structured value stays valid TOML.++ The structured value is emitted as an inline table so the trailing scalar is not swallowed+ into a ``[section]`` — the whole document loads back equal to the light template.+ """+ template: dict[str, Any] = {+ "question": "text_value",+ "invoice": {"invoice_number": "INV-1", "amount": 0.0},+ "priority": 1,+ "tags": ["a", "b"],+ "people": [{"name": "name_value", "job": "job_value"}],+ }+ toml_str = serialize_inputs_template_to_toml(template, light=True)++ assert tomli.loads(toml_str) == template++ def test_light_toml_attaches_concept_comments(self) -> None:+ """Light TOML carries the declared concept as a ``# concept: ...`` comment above each key."""+ template: dict[str, Any] = {"question": "text_value", "invoice": {"invoice_number": "INV-1"}}+ comments = {"question": "concept: demo.Question", "invoice": "concept: demo.Invoice"}++ toml_str = serialize_inputs_template_to_toml(template, light=True, concept_comments=comments)++ assert "# concept: demo.Question" in toml_str+ assert "# concept: demo.Invoice" in toml_str+ assert tomli.loads(toml_str) == template++ def test_explicit_toml_default_keeps_section_layout(self) -> None:+ """Without light=True the serializer is unchanged: envelope entries render as sections and round-trip."""+ template: dict[str, Any] = {"question": {"concept": "demo.Question", "content": {"text": "text_value"}}}++ toml_str = serialize_inputs_template_to_toml(template)++ assert "[question]" in toml_str+ assert tomli.loads(toml_str) == templatediff --git a/tests/unit/pipelex/core/stuffs/data.py b/tests/unit/pipelex/core/stuffs/data.pyindex fbde471ca..8a83f3c85 100644--- a/tests/unit/pipelex/core/stuffs/data.py+++ b/tests/unit/pipelex/core/stuffs/data.py@@ -1,3 +1,4 @@+import datetimefrom typing import ClassVarfrom markupsafe import escape@@ -7,6 +8,7 @@ from pydantic import Fieldfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.domains.domain import SpecialDomain+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.html_content import HtmlContentfrom pipelex.core.stuffs.image_content import ImageContent@@ -16,6 +18,7 @@ from pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.core.stuffs.stuff import DictStuff, Stufffrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentfrom pipelex.urls import URLs@@ -36,6 +39,14 @@ class AnotherConcept(StructuredContent):value: int = Field(description="Value field")+class UrgencyFlag(YesNoContent):+ """A structure refining native YesNo — mirrors the subclass the refinement machinery generates for `refines = "YesNo"`."""+++class DueDate(DateContent):+ """A structure refining native Date — mirrors the subclass the refinement machinery generates for `refines = "Date"`."""++TEST_CASES: list[tuple[str, StuffContentOrData | DictStuff, str | None, str, Stuff]] = [# Case 1.1: Content is a string(@@ -477,6 +488,174 @@ TEST_CASES: list[tuple[str, StuffContentOrData | DictStuff, str | None, str, Stu),),),+ # Case 2.11: Envelope with bool content under native YesNo (true)+ (+ "case-2.11-yes-no-native-bool-true",+ {"concept": "YesNo", "content": True},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.YES_NO),+ content=YesNoContent(yes_no=True),+ ),+ ),+ # Case 2.12: Envelope with bool content under native YesNo (false, native prefix)+ (+ "case-2.12-yes-no-native-bool-false",+ {"concept": "native.YesNo", "content": False},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.YES_NO),+ content=YesNoContent(yes_no=False),+ ),+ ),+ # Case 2.13: Envelope with bool content under a concept refining YesNo — keeps its own concept ref, content is the refining subclass+ (+ "case-2.13-yes-no-refining-concept-bool",+ {"concept": "test_domain.UrgencyFlag", "content": False},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_code="stuff_code",+ stuff_name="stuff_name",+ concept=ConceptFactory.make(+ domain_code="test_domain",+ concept_code="UrgencyFlag",+ description="Test concept for unit tests",+ structure_class_name="UrgencyFlag",+ refines="native.YesNo",+ ),+ content=UrgencyFlag(yes_no=False),+ ),+ ),+ # Case 2.14: Envelope with the explicit dict form for YesNo still works+ (+ "case-2.14-yes-no-dict-form",+ {"concept": "YesNo", "content": {"yes_no": True}},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.YES_NO),+ content=YesNoContent(yes_no=True),+ ),+ ),+ # Case 1.3-yes-no: Direct YesNoContent instance (no concept key) infers native YesNo from the class name+ (+ "case-1.3-yes-no-content-instance",+ YesNoContent(yes_no=True),+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.YES_NO),+ content=YesNoContent(yes_no=True),+ ),+ ),+ # Case 2.1f: Envelope with an ISO date-only string under native Date+ (+ "case-2.15-date-native-iso-date-string",+ {"concept": "Date", "content": "2026-07-07"},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DATE),+ content=DateContent(date=datetime.date(2026, 7, 7)),+ ),+ ),+ # Case 2.1f: Envelope with an ISO offset-datetime string (native prefix) → offset preserved+ (+ "case-2.16-date-native-iso-datetime-offset",+ {"concept": "native.Date", "content": "2026-07-07T15:40:00+02:00"},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DATE),+ content=DateContent(date=datetime.date(2026, 7, 7), time=datetime.time(15, 40, tzinfo=datetime.timezone(datetime.timedelta(hours=2)))),+ ),+ ),+ # Case 2.1e: Envelope with a bare date object under native Date+ (+ "case-2.17-date-native-date-object",+ {"concept": "Date", "content": datetime.date(2026, 8, 6)},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DATE),+ content=DateContent(date=datetime.date(2026, 8, 6)),+ ),+ ),+ # Case 2.1e: Envelope with a bare datetime object → split into date + time+ (+ "case-2.18-date-native-datetime-object",+ {"concept": "Date", "content": datetime.datetime(2026, 7, 7, 9, 0)},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DATE),+ content=DateContent(date=datetime.date(2026, 7, 7), time=datetime.time(9, 0)),+ ),+ ),+ # Case 2.1e: Envelope with a date object under a concept refining Date — keeps its own ref, content is the refining subclass+ (+ "case-2.19-date-refining-concept-date-object",+ {"concept": "test_domain.DueDate", "content": datetime.date(2026, 8, 6)},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_code="stuff_code",+ stuff_name="stuff_name",+ concept=ConceptFactory.make(+ domain_code="test_domain",+ concept_code="DueDate",+ description="Test concept for unit tests",+ structure_class_name="DueDate",+ refines="native.Date",+ ),+ content=DueDate(date=datetime.date(2026, 8, 6)),+ ),+ ),+ # Case 2.5: Envelope with the explicit dict form for Date still works+ (+ "case-2.20-date-dict-form",+ {"concept": "Date", "content": {"date": "2026-07-07", "time": "15:40:00"}},+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DATE),+ content=DateContent(date=datetime.date(2026, 7, 7), time=datetime.time(15, 40)),+ ),+ ),+ # Case 1.3: Direct DateContent instance (no concept key) infers native Date from the class name+ (+ "case-1.3-date-content-instance",+ DateContent(date=datetime.date(2026, 7, 7)),+ "stuff_name",+ "stuff_code",+ Stuff(+ stuff_name="stuff_name",+ stuff_code="stuff_code",+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DATE),+ content=DateContent(date=datetime.date(2026, 7, 7)),+ ),+ ),]@@ -685,6 +864,46 @@ ERROR_TEST_CASES: list[tuple[str, StuffContentOrData | DictStuff, str | None, stException,"not compatible",),+ # Bool content under a concept that is not YesNo-compatible - should fail, naming native.YesNo+ (+ "error-bool-for-non-yes-no-concept",+ {"concept": "test_domain.MyConcept", "content": True},+ "stuff_name",+ "stuff_code",+ ["test_domain"],+ Exception,+ "native.YesNo",+ ),+ # String content under a YesNo concept - no string coercion, so it fails (YesNo is not Text-compatible)+ (+ "error-string-for-yes-no-concept",+ {"concept": "YesNo", "content": "yes"},+ "stuff_name",+ "stuff_code",+ None,+ Exception,+ "not compatible",+ ),+ # Date object under a concept that is not Date-compatible - should fail, naming native.Date+ (+ "error-date-object-for-non-date-concept",+ {"concept": "test_domain.MyConcept", "content": datetime.date(2026, 7, 7)},+ "stuff_name",+ "stuff_code",+ ["test_domain"],+ Exception,+ "native.Date",+ ),+ # Non-ISO string under a Date concept - strict ISO only, so it fails+ (+ "error-non-iso-string-for-date-concept",+ {"concept": "Date", "content": "March 7, 2026"},+ "stuff_name",+ "stuff_code",+ None,+ Exception,+ "ISO 8601",+ ),]diff --git a/tests/unit/pipelex/core/stuffs/date_content/test_data.py b/tests/unit/pipelex/core/stuffs/date_content/test_data.pynew file mode 100644index 000000000..cbbe886c1--- /dev/null+++ b/tests/unit/pipelex/core/stuffs/date_content/test_data.py@@ -0,0 +1,38 @@+import datetime+from typing import Any, ClassVar+++class TestData:+ OFFSET_PLUS_2 = datetime.timezone(datetime.timedelta(hours=2))++ # Sample values in the three precision states+ SAMPLE_DATE = datetime.date(2026, 7, 7)+ SAMPLE_TIME_NAIVE = datetime.time(15, 40, 0)+ SAMPLE_TIME_OFFSET = datetime.time(15, 40, 0, tzinfo=OFFSET_PLUS_2)++ # Expected smart_dump (python mode keeps real objects — relevant to transport)+ EXPECTED_SMART_DUMP_DATE_ONLY: ClassVar[dict[str, Any]] = {"date": SAMPLE_DATE, "time": None}+ EXPECTED_SMART_DUMP_WITH_TIME: ClassVar[dict[str, Any]] = {"date": SAMPLE_DATE, "time": SAMPLE_TIME_NAIVE}++ # Expected ISO renders (rendered_plain / markdown / html are identical — truncated to stated precision)+ EXPECTED_ISO_DATE_ONLY = "2026-07-07"+ EXPECTED_ISO_NAIVE = "2026-07-07T15:40:00"+ EXPECTED_ISO_OFFSET = "2026-07-07T15:40:00+02:00"++ # Expected rendered_json (two-field form)+ EXPECTED_JSON_DATE_ONLY = '{"date": "2026-07-07", "time": null}'+ EXPECTED_JSON_NAIVE = '{"date": "2026-07-07", "time": "15:40:00"}'+ EXPECTED_JSON_OFFSET = '{"date": "2026-07-07", "time": "15:40:00+02:00"}'++ # Expected short_desc+ EXPECTED_SHORT_DESC_DATE_ONLY = "a date (2026-07-07)"+ EXPECTED_SHORT_DESC_NAIVE = "a date and time (2026-07-07T15:40:00)"+ EXPECTED_SHORT_DESC_OFFSET = "a date and time (2026-07-07T15:40:00+02:00)"++ # The field descriptions are the LLM-facing generation contract (DT2 anti-fabrication instruction).+ EXPECTED_DATE_FIELD_DESCRIPTION = "The calendar date, in ISO 8601 (e.g. 2026-07-07). Always required."+ EXPECTED_TIME_FIELD_DESCRIPTION = (+ "The time of day, in ISO 8601 (e.g. 15:40:00, or 15:40:00+02:00 with a UTC offset). "+ "Include it only when the source states a time — never invent a time. "+ "Keep the UTC offset exactly when the source states one."+ )diff --git a/tests/unit/pipelex/core/stuffs/date_content/test_date_content_renders.py b/tests/unit/pipelex/core/stuffs/date_content/test_date_content_renders.pynew file mode 100644index 000000000..f6aa607bf--- /dev/null+++ b/tests/unit/pipelex/core/stuffs/date_content/test_date_content_renders.py@@ -0,0 +1,181 @@+import datetime++import pytest+from pydantic import ValidationError++from pipelex.core.stuffs.date_content import DateContent+from pipelex.core.stuffs.exceptions import DateContentError+from tests.unit.pipelex.core.stuffs.date_content.test_data import TestData+++class TestDateContentRenders:+ """Tests for DateContent construction, validation, render matrix, short_desc, and to_datetime."""++ def test_construction_date_only(self):+ content = DateContent(date=TestData.SAMPLE_DATE)+ assert content.date == TestData.SAMPLE_DATE+ assert content.time is None++ def test_construction_date_and_naive_time(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_NAIVE)+ assert content.date == TestData.SAMPLE_DATE+ assert content.time is not None+ assert content.time == TestData.SAMPLE_TIME_NAIVE+ assert content.time.tzinfo is None++ def test_construction_date_and_offset_time(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET)+ assert content.date == TestData.SAMPLE_DATE+ assert content.time is not None+ # `time.__eq__` compares hour/minute/second/microsecond AND tzinfo/offset, so this pins the full value.+ assert content.time == TestData.SAMPLE_TIME_OFFSET+ assert content.time.utcoffset() == datetime.timedelta(hours=2)++ def test_parses_iso_date_string(self):+ """The date field accepts a strict ISO date string (dict-content / JSON-wire road)."""+ content = DateContent.model_validate({"date": "2026-07-07"})+ assert content.date == TestData.SAMPLE_DATE+ assert content.time is None++ def test_parses_iso_time_with_offset_string(self):+ content = DateContent.model_validate({"date": "2026-07-07", "time": "15:40:00+02:00"})+ assert content.time is not None+ assert content.time.utcoffset() == datetime.timedelta(hours=2)++ def test_rejects_int_on_time_field(self):+ """A bare int must not coerce into the time field as seconds-of-day (no epoch-seconds; DT6)."""+ with pytest.raises(ValidationError):+ DateContent.model_validate({"date": "2026-07-07", "time": 56400})++ def test_rejects_int_on_date_field(self):+ """A bare int must not coerce into the date field (no epoch interpretation)."""+ with pytest.raises(ValidationError):+ DateContent.model_validate({"date": 1720000000})++ def test_rejects_numeric_string_epoch(self):+ """An all-digit string is an epoch, never an ISO date (which carries '-'), so it must be rejected."""+ with pytest.raises(ValidationError):+ DateContent.model_validate({"date": "1704067200"})++ def test_rejects_datetime_on_date_field(self):+ """A datetime on the date field would silently drop its time and offset — reject it (DT3 fidelity)."""+ with pytest.raises(ValidationError):+ DateContent.model_validate({"date": datetime.datetime(2026, 7, 7, 0, 0, tzinfo=TestData.OFFSET_PLUS_2)})++ def test_rejects_datetime_on_time_field(self):+ """The guard runs on both fields: a datetime on the time field must be rejected too, not lax-coerced."""+ with pytest.raises(ValidationError):+ DateContent.model_validate({"date": "2026-07-07", "time": datetime.datetime(2026, 7, 7, 15, 40, tzinfo=TestData.OFFSET_PLUS_2)})++ def test_rejects_numeric_string_on_time_field(self):+ """An all-digit string on the time field is an epoch, never an ISO time (which carries ':') — reject it (DT6)."""+ with pytest.raises(ValidationError):+ DateContent.model_validate({"date": "2026-07-07", "time": "56400"})++ @pytest.mark.parametrize(+ "date_string",+ [+ "2026-07-07T00:00:00", # midnight datetime string — pydantic would silently truncate to date-only+ "2026-07-07T00:00:00+00:00", # midnight with offset — time and offset silently dropped+ "2026-07-07 00:00:00", # space-separated midnight+ "2026-07-07T12:30:00", # non-midnight — pydantic already rejects; locked as a regression guard+ ],+ )+ def test_rejects_datetime_string_on_date_field(self, date_string: str):+ """A datetime-shaped string on the date field drops its time (silently at midnight) — reject it (DT3)."""+ with pytest.raises(ValidationError):+ DateContent.model_validate({"date": date_string})++ @pytest.mark.parametrize(+ "epoch_string",+ ["-86400", "86400.0", "0.0", "-0", "8.64e4", "-8.64e4"],+ )+ def test_rejects_signed_or_decimal_epoch_string_on_date_field(self, epoch_string: str):+ """A signed/decimal/exponent numeric string is still an epoch, never an ISO date — reject it (DT6).++ The unsigned all-digit case is covered by test_rejects_numeric_string_epoch; these day-aligned+ epochs slipped past the old `.isdigit()` guard because a sign/decimal/exponent is not a digit.+ """+ with pytest.raises(ValidationError):+ DateContent.model_validate({"date": epoch_string})++ def test_accepts_naive_iso_time_string(self):+ """A naive ISO time string on the time field must still be accepted (the DT3 date-field guard must not over-reject)."""+ content = DateContent.model_validate({"date": "2026-07-07", "time": "15:40:00"})+ assert content.time is not None+ assert content.time == TestData.SAMPLE_TIME_NAIVE+ assert content.time.tzinfo is None++ def test_rendered_plain_date_only(self):+ content = DateContent(date=TestData.SAMPLE_DATE)+ assert content.rendered_plain() == TestData.EXPECTED_ISO_DATE_ONLY++ def test_rendered_plain_naive(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_NAIVE)+ assert content.rendered_plain() == TestData.EXPECTED_ISO_NAIVE++ def test_rendered_plain_offset(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET)+ assert content.rendered_plain() == TestData.EXPECTED_ISO_OFFSET++ def test_rendered_markdown_offset(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET)+ assert content.rendered_markdown() == TestData.EXPECTED_ISO_OFFSET++ def test_rendered_html_offset(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET)+ assert content.rendered_html() == TestData.EXPECTED_ISO_OFFSET++ def test_rendered_json_date_only(self):+ content = DateContent(date=TestData.SAMPLE_DATE)+ assert content.rendered_json() == TestData.EXPECTED_JSON_DATE_ONLY++ def test_rendered_json_naive(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_NAIVE)+ assert content.rendered_json() == TestData.EXPECTED_JSON_NAIVE++ def test_rendered_json_offset(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET)+ assert content.rendered_json() == TestData.EXPECTED_JSON_OFFSET++ def test_rendered_for_prompt_offset(self):+ """A Date input rendered into a prompt is the ISO form (the plain render)."""+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET)+ assert content.rendered_for_prompt() == TestData.EXPECTED_ISO_OFFSET++ def test_short_desc_date_only(self):+ content = DateContent(date=TestData.SAMPLE_DATE)+ assert content.short_desc == TestData.EXPECTED_SHORT_DESC_DATE_ONLY++ def test_short_desc_naive(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_NAIVE)+ assert content.short_desc == TestData.EXPECTED_SHORT_DESC_NAIVE++ def test_short_desc_offset(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET)+ assert content.short_desc == TestData.EXPECTED_SHORT_DESC_OFFSET++ def test_to_datetime_with_time(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET)+ result = content.to_datetime()+ assert result == datetime.datetime(2026, 7, 7, 15, 40, 0, tzinfo=TestData.OFFSET_PLUS_2)++ def test_to_datetime_without_time_raises(self):+ """Date-only to_datetime raises rather than inventing a midnight (DT2: no silent midnight)."""+ content = DateContent(date=TestData.SAMPLE_DATE)+ with pytest.raises(DateContentError):+ content.to_datetime()++ def test_rendered_pretty_does_not_crash(self):+ """The base rendered_pretty feeds smart_dump()'s real date objects to stdlib json and crashes;+ DateContent overrides it to render the ISO form. Guard against a regression to the base path.+ """+ from pipelex.tools.misc.pretty import pretty_print # noqa: PLC0415 — local import keeps the render dep test-local++ pretty_print(DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET))++ def test_model_json_schema_carries_field_descriptions(self):+ """Both field descriptions are the contract handed to the LLM in the generation schema."""+ schema = DateContent.model_json_schema()+ assert schema["properties"]["date"]["description"] == TestData.EXPECTED_DATE_FIELD_DESCRIPTION+ assert schema["properties"]["time"]["description"] == TestData.EXPECTED_TIME_FIELD_DESCRIPTIONdiff --git a/tests/unit/pipelex/core/stuffs/date_content/test_date_content_serialization.py b/tests/unit/pipelex/core/stuffs/date_content/test_date_content_serialization.pynew file mode 100644index 000000000..f4343d271--- /dev/null+++ b/tests/unit/pipelex/core/stuffs/date_content/test_date_content_serialization.py@@ -0,0 +1,45 @@+import datetime++from kajson import kajson++from pipelex.core.stuffs.date_content import DateContent+from pipelex.hub import get_class_registry+from tests.unit.pipelex.core.stuffs.date_content.test_data import TestData+++class TestDateContentSerialization:+ """kajson round-trip is the distributed-execution safety net.++ A content class that fails payload decode inside a Temporal workflow does not fail loudly —+ it hangs (converter exceptions retry forever). So each precision state must round-trip to a+ TYPED-equal object (real date/time/tzinfo, not string forms), and resolve by class name.+ """++ def _round_trip(self, content: DateContent) -> DateContent:+ restored = kajson.loads(kajson.dumps(content))+ assert isinstance(restored, DateContent)+ return restored++ def test_registry_resolves_by_name(self):+ registry = get_class_registry()+ if not registry.has_class(name="DateContent"):+ registry.register_class(DateContent)+ assert registry.get_class(name="DateContent") is DateContent++ def test_round_trip_date_only(self):+ restored = self._round_trip(DateContent(date=TestData.SAMPLE_DATE))+ assert restored.date == TestData.SAMPLE_DATE+ assert isinstance(restored.date, datetime.date)+ assert restored.time is None++ def test_round_trip_naive_time(self):+ restored = self._round_trip(DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_NAIVE))+ assert restored.time == TestData.SAMPLE_TIME_NAIVE+ assert isinstance(restored.time, datetime.time)+ assert restored.time.tzinfo is None++ def test_round_trip_offset_time_preserves_offset(self):+ restored = self._round_trip(DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_OFFSET))+ assert restored.time is not None+ assert restored.time.utcoffset() == datetime.timedelta(hours=2)+ assert restored.time == TestData.SAMPLE_TIME_OFFSETdiff --git a/tests/unit/pipelex/core/stuffs/date_content/test_date_content_smart_dump.py b/tests/unit/pipelex/core/stuffs/date_content/test_date_content_smart_dump.pynew file mode 100644index 000000000..9e9d505e7--- /dev/null+++ b/tests/unit/pipelex/core/stuffs/date_content/test_date_content_smart_dump.py@@ -0,0 +1,17 @@+from pipelex.core.stuffs.date_content import DateContent+from tests.unit.pipelex.core.stuffs.date_content.test_data import TestData+++class TestDateContentSmartDump:+ """smart_dump keeps real date/time objects (python mode) — the shape that rides dump_for_transport."""++ def test_smart_dump_date_only(self):+ content = DateContent(date=TestData.SAMPLE_DATE)+ result = content.smart_dump()+ assert result == TestData.EXPECTED_SMART_DUMP_DATE_ONLY+ assert isinstance(result, dict)++ def test_smart_dump_with_time(self):+ content = DateContent(date=TestData.SAMPLE_DATE, time=TestData.SAMPLE_TIME_NAIVE)+ result = content.smart_dump()+ assert result == TestData.EXPECTED_SMART_DUMP_WITH_TIMEdiff --git a/tests/unit/pipelex/core/stuffs/test_stuff_content_factory.py b/tests/unit/pipelex/core/stuffs/test_stuff_content_factory.pyindex ef387685b..38fe1b639 100644--- a/tests/unit/pipelex/core/stuffs/test_stuff_content_factory.py+++ b/tests/unit/pipelex/core/stuffs/test_stuff_content_factory.py@@ -1,3 +1,4 @@+import datetimefrom pathlib import Pathfrom typing import Any, Callable, ClassVar@@ -7,9 +8,12 @@ from pipelex import logfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.domains.domain import SpecialDomain+from pipelex.core.stuffs.date_content import DateContent+from pipelex.core.stuffs.exceptions import StuffContentFactoryErrorfrom pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.core.stuffs.stuff_factory import StuffContentFactoryfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentclass TestCases:@@ -76,6 +80,95 @@ class TestStuffContentFactory:assert result.title == "Test Title"assert result.description == "Test Description"+ def test_make_content_from_value_yes_no_bool(self):+ """A bool value builds YesNoContent directly (not via model_validate, which rejects a bare bool)."""+ result = StuffContentFactory.make_content_from_value(stuff_content_subclass=YesNoContent, value=True)++ assert isinstance(result, YesNoContent)+ assert result.yes_no is True++ def test_make_content_from_value_yes_no_refining_subclass_bool(self):+ """A bool value builds a YesNo-refining subclass directly (the issubclass arm covers generated refinement classes)."""++ class MockUrgencyFlag(YesNoContent):+ pass++ result = StuffContentFactory.make_content_from_value(stuff_content_subclass=MockUrgencyFlag, value=False)++ assert isinstance(result, MockUrgencyFlag)+ assert result.yes_no is False++ def test_make_content_from_value_date_from_date_object(self):+ """A date object builds a date-only DateContent."""+ result = StuffContentFactory.make_content_from_value(stuff_content_subclass=DateContent, value=datetime.date(2026, 7, 7))++ assert isinstance(result, DateContent)+ assert result.date == datetime.date(2026, 7, 7)+ assert result.time is None++ def test_make_content_from_value_date_from_datetime_object_splits(self):+ """A datetime object splits into date + time, preserving the UTC offset."""+ offset = datetime.timezone(datetime.timedelta(hours=2))+ result = StuffContentFactory.make_content_from_value(+ stuff_content_subclass=DateContent, value=datetime.datetime(2026, 7, 7, 15, 40, tzinfo=offset)+ )++ assert isinstance(result, DateContent)+ assert result.date == datetime.date(2026, 7, 7)+ assert result.time is not None+ assert result.time.utcoffset() == datetime.timedelta(hours=2)++ def test_make_content_from_value_date_from_iso_date_string(self):+ """A date-only ISO string never fabricates a time (parsed date-first)."""+ result = StuffContentFactory.make_content_from_value(stuff_content_subclass=DateContent, value="2026-07-07")++ assert isinstance(result, DateContent)+ assert result.date == datetime.date(2026, 7, 7)+ assert result.time is None++ def test_make_content_from_value_date_from_iso_datetime_string(self):+ """A datetime ISO string parses into date + time with the offset kept."""+ result = StuffContentFactory.make_content_from_value(stuff_content_subclass=DateContent, value="2026-07-07T15:40:00+02:00")++ assert isinstance(result, DateContent)+ assert result.date == datetime.date(2026, 7, 7)+ assert result.time is not None+ assert result.time.utcoffset() == datetime.timedelta(hours=2)++ def test_make_content_from_value_date_refining_subclass(self):+ """A date object builds a Date-refining subclass directly (the issubclass arm covers generated refinement classes)."""++ class MockDueDate(DateContent):+ pass++ result = StuffContentFactory.make_content_from_value(stuff_content_subclass=MockDueDate, value=datetime.date(2026, 8, 6))++ assert isinstance(result, MockDueDate)+ assert result.date == datetime.date(2026, 8, 6)++ def test_make_content_from_value_date_rejects_non_iso_string(self):+ """A non-ISO string under a Date class is rejected (strict ISO, no loose formats)."""+ with pytest.raises(StuffContentFactoryError):+ StuffContentFactory.make_content_from_value(stuff_content_subclass=DateContent, value="March 7, 2026")++ def test_make_content_from_value_date_rejects_all_digit_string(self):+ """An all-digit string (basic-ISO/epoch-ambiguous) is rejected here too, matching DateContent's own guard."""+ with pytest.raises(StuffContentFactoryError):+ StuffContentFactory.make_content_from_value(stuff_content_subclass=DateContent, value="20260707")++ @pytest.mark.parametrize(+ "date_string",+ [+ "20260707T154000", # compact/basic datetime — fromisoformat accepts it, but it is not extended ISO+ "2026-W27-2", # ISO week-date — fromisoformat silently normalizes it to a calendar date+ "20260707", # compact/basic date (regression-lock: was already rejected by the all-digit guard)+ ],+ )+ def test_make_content_from_value_date_rejects_non_extended_iso(self, date_string: str):+ """Only extended-calendar ISO (YYYY-MM-DD[...]) is accepted; compact/basic and week-date forms are rejected (strict, no loose forms)."""+ with pytest.raises(StuffContentFactoryError):+ StuffContentFactory.make_content_from_value(stuff_content_subclass=DateContent, value=date_string)+def test_make_stuffcontent_from_concept_code_required_text_content(self):"""Test required method with native.Text concept (should work)."""result = StuffContentFactory.make_stuff_content_from_concept_required(diff --git a/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py b/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.pyindex e25d6e628..d88b5c4d0 100644--- a/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py+++ b/tests/unit/pipelex/core/stuffs/test_stuff_factory_implicit_memory.py@@ -9,9 +9,9 @@ from pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.stuff_factory import StuffFactory-from pipelex.hub import get_concept_library+from pipelex.hub import get_class_registry, get_concept_libraryfrom pipelex.system.registries.class_registry_utils import ClassRegistryUtils-from tests.unit.pipelex.core.stuffs.data import ERROR_TEST_CASES, SEARCH_DOMAIN_TEST_CASES, TEST_CASES+from tests.unit.pipelex.core.stuffs.data import ERROR_TEST_CASES, SEARCH_DOMAIN_TEST_CASES, TEST_CASES, DueDate, UrgencyFlag@pytest.fixture(scope="class")@@ -23,6 +23,10 @@ def setup_test_concept(load_test_library: Callable[[list[Path]], None]):base_class=StructuredContent,is_include_imported=False,)+ # UrgencyFlag/DueDate refine YesNo/Date (StuffContent, not StructuredContent), so register them explicitly —+ # this mirrors the subclass the refinement machinery registers for a `refines = "YesNo"`/`refines = "Date"` concept.+ get_class_registry().register_class(class_type=UrgencyFlag)+ get_class_registry().register_class(class_type=DueDate)# Create and register the test conceptconcept_library = get_concept_library()@@ -56,11 +60,37 @@ def setup_test_concept(load_test_library: Callable[[list[Path]], None]):)concept_library.add_new_concept(concept=concept_another)+ # Create a concept that refines native.YesNo (for the bool-envelope refining case)+ concept_urgency_flag = ConceptFactory.make(+ domain_code="test_domain",+ concept_code="UrgencyFlag",+ description="Test concept for unit tests",+ structure_class_name="UrgencyFlag",+ refines="native.YesNo",+ )+ concept_library.add_new_concept(concept=concept_urgency_flag)++ # Create a concept that refines native.Date (for the date-envelope refining case)+ concept_due_date = ConceptFactory.make(+ domain_code="test_domain",+ concept_code="DueDate",+ description="Test concept for unit tests",+ structure_class_name="DueDate",+ refines="native.Date",+ )+ concept_library.add_new_concept(concept=concept_due_date)+yield concept# Cleanup after testconcept_library.remove_concepts_by_concept_refs(- concept_refs=["test_domain.MyConcept", "test_domain.MyConceptNotNativeText", "test_domain.AnotherConcept"]+ concept_refs=[+ "test_domain.MyConcept",+ "test_domain.MyConceptNotNativeText",+ "test_domain.AnotherConcept",+ "test_domain.UrgencyFlag",+ "test_domain.DueDate",+ ])diff --git a/tests/unit/pipelex/core/stuffs/yes_no_content/test_data.py b/tests/unit/pipelex/core/stuffs/yes_no_content/test_data.pynew file mode 100644index 000000000..b36cefa3e--- /dev/null+++ b/tests/unit/pipelex/core/stuffs/yes_no_content/test_data.py@@ -0,0 +1,30 @@+from typing import Any, ClassVar+++class TestData:+ # Input content+ SAMPLE_TRUE = True+ SAMPLE_FALSE = False++ # Expected outputs for smart_dump+ EXPECTED_SMART_DUMP_TRUE: ClassVar[dict[str, Any]] = {"yes_no": True}+ EXPECTED_SMART_DUMP_FALSE: ClassVar[dict[str, Any]] = {"yes_no": False}++ # Expected outputs for render methods+ EXPECTED_RENDERED_PLAIN_TRUE = "yes"+ EXPECTED_RENDERED_PLAIN_FALSE = "no"+ EXPECTED_RENDERED_MARKDOWN_TRUE = "yes"+ EXPECTED_RENDERED_MARKDOWN_FALSE = "no"+ EXPECTED_RENDERED_HTML_TRUE = "yes"+ EXPECTED_RENDERED_HTML_FALSE = "no"+ EXPECTED_RENDERED_JSON_TRUE = '{"yes_no": true}'+ EXPECTED_RENDERED_JSON_FALSE = '{"yes_no": false}'+ EXPECTED_RENDERED_FOR_PROMPT_TRUE = "yes"+ EXPECTED_RENDERED_FOR_PROMPT_FALSE = "no"++ # Expected short_desc+ EXPECTED_SHORT_DESC_TRUE = "a yes/no answer (yes)"+ EXPECTED_SHORT_DESC_FALSE = "a yes/no answer (no)"++ # The field description is the LLM-facing generation contract.+ EXPECTED_FIELD_DESCRIPTION = "Whether the answer is yes (true) or no (false)."diff --git a/tests/unit/pipelex/core/stuffs/yes_no_content/test_yes_no_content_renders.py b/tests/unit/pipelex/core/stuffs/yes_no_content/test_yes_no_content_renders.pynew file mode 100644index 000000000..7f462eacd--- /dev/null+++ b/tests/unit/pipelex/core/stuffs/yes_no_content/test_yes_no_content_renders.py@@ -0,0 +1,104 @@+import pytest+from pydantic import ValidationError++from pipelex.core.stuffs.yes_no_content import YesNoContent+from tests.unit.pipelex.core.stuffs.yes_no_content.test_data import TestData+++class TestYesNoContentRenders:+ """Tests for YesNoContent render methods and descriptors."""++ def test_construction_true(self):+ """Verify construction from yes_no=True keeps a genuine bool."""+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ assert content.yes_no is True++ def test_construction_false(self):+ """Verify construction from yes_no=False keeps a genuine bool."""+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ assert content.yes_no is False++ def test_rejects_non_bool_int(self):+ """An arbitrary int (not 0/1) must not coerce into the bool field."""+ with pytest.raises(ValidationError):+ YesNoContent.model_validate({"yes_no": 2})++ def test_rejects_coercible_string(self):+ """A yes/no-ish string must not coerce into the bool field (strict validation).++ Without strict validation pydantic would silently turn ``"yes"`` into ``True`` on the+ dict-content path (``{"concept": "YesNo", "content": {"yes_no": "yes"}}``), bypassing the+ no-cross-kind-coercion contract the scalar envelope arm enforces.+ """+ with pytest.raises(ValidationError):+ YesNoContent.model_validate({"yes_no": "yes"})++ def test_rejects_coercible_int(self):+ """The ints 0/1 must not coerce into the bool field (strict validation)."""+ with pytest.raises(ValidationError):+ YesNoContent.model_validate({"yes_no": 1})++ def test_rendered_plain_true(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ assert content.rendered_plain() == TestData.EXPECTED_RENDERED_PLAIN_TRUE++ def test_rendered_plain_false(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ assert content.rendered_plain() == TestData.EXPECTED_RENDERED_PLAIN_FALSE++ def test_rendered_markdown_true(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ assert content.rendered_markdown() == TestData.EXPECTED_RENDERED_MARKDOWN_TRUE++ def test_rendered_markdown_false(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ assert content.rendered_markdown() == TestData.EXPECTED_RENDERED_MARKDOWN_FALSE++ def test_rendered_html_true(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ assert content.rendered_html() == TestData.EXPECTED_RENDERED_HTML_TRUE++ def test_rendered_html_false(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ assert content.rendered_html() == TestData.EXPECTED_RENDERED_HTML_FALSE++ def test_rendered_json_true(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ assert content.rendered_json() == TestData.EXPECTED_RENDERED_JSON_TRUE++ def test_rendered_json_false(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ assert content.rendered_json() == TestData.EXPECTED_RENDERED_JSON_FALSE++ def test_rendered_for_prompt_true(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ assert content.rendered_for_prompt() == TestData.EXPECTED_RENDERED_FOR_PROMPT_TRUE++ def test_rendered_for_prompt_false(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ assert content.rendered_for_prompt() == TestData.EXPECTED_RENDERED_FOR_PROMPT_FALSE++ def test_short_desc_true(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ assert content.short_desc == TestData.EXPECTED_SHORT_DESC_TRUE++ def test_short_desc_false(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ assert content.short_desc == TestData.EXPECTED_SHORT_DESC_FALSE++ def test_model_json_schema_carries_field_description(self):+ """The field description is the contract handed to the LLM in the generation schema."""+ schema = YesNoContent.model_json_schema()+ assert schema["properties"]["yes_no"]["description"] == TestData.EXPECTED_FIELD_DESCRIPTION++ @pytest.mark.asyncio+ async def test_rendered_plain_async_true(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ result = await content.rendered_plain_async()+ assert result == TestData.EXPECTED_RENDERED_PLAIN_TRUE++ @pytest.mark.asyncio+ async def test_rendered_json_async_false(self):+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ result = await content.rendered_json_async()+ assert result == TestData.EXPECTED_RENDERED_JSON_FALSEdiff --git a/tests/unit/pipelex/core/stuffs/yes_no_content/test_yes_no_content_smart_dump.py b/tests/unit/pipelex/core/stuffs/yes_no_content/test_yes_no_content_smart_dump.pynew file mode 100644index 000000000..54f798808--- /dev/null+++ b/tests/unit/pipelex/core/stuffs/yes_no_content/test_yes_no_content_smart_dump.py@@ -0,0 +1,20 @@+from pipelex.core.stuffs.yes_no_content import YesNoContent+from tests.unit.pipelex.core.stuffs.yes_no_content.test_data import TestData+++class TestYesNoContentSmartDump:+ """Tests for YesNoContent.smart_dump() method."""++ def test_smart_dump_true(self):+ """Verify smart_dump returns a dict for a true value."""+ content = YesNoContent(yes_no=TestData.SAMPLE_TRUE)+ result = content.smart_dump()+ assert result == TestData.EXPECTED_SMART_DUMP_TRUE+ assert isinstance(result, dict)++ def test_smart_dump_false(self):+ """Verify smart_dump returns a dict for a false value."""+ content = YesNoContent(yes_no=TestData.SAMPLE_FALSE)+ result = content.smart_dump()+ assert result == TestData.EXPECTED_SMART_DUMP_FALSE+ assert isinstance(result, dict)diff --git a/tests/unit/pipelex/exceptions/test_class_level_metadata.py b/tests/unit/pipelex/exceptions/test_class_level_metadata.pyindex 1c1dc3ae8..88b6850ec 100644--- a/tests/unit/pipelex/exceptions/test_class_level_metadata.py+++ b/tests/unit/pipelex/exceptions/test_class_level_metadata.py@@ -17,6 +17,7 @@ from pipelex.cogt.exceptions import (SdkTypeError,)from pipelex.core.interpreter.exceptions import PipelexInterpreterError+from pipelex.core.stuffs.exceptions import DateContentErrorfrom pipelex.pipe_run.pipe_run_mode import PipeRunModefrom pipelex.pipeline.exceptions import PipeExecutionError, PipelineExecutionError, ValidateBundleErrorfrom pipelex.plugins.exceptions import UnknownSecretsMethodError, UnknownStorageMethodError@@ -105,6 +106,7 @@ class TestClassLevelMetadata:("csv", CsvError("boom"), True),("unknown_storage_method", UnknownStorageMethodError(method="bogus", registered_methods=["local", "s3"]), True),("unknown_secrets_method", UnknownSecretsMethodError(method="bogus", registered_methods=["env"]), True),+ ("date_content", DateContentError("boom"), True),("config", PipelexConfigError("boom"), False),("pipe_execution", PipeExecutionError("boom"), False),("cogt", CogtError("boom"), False),diff --git a/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py b/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.pyindex 0416f3525..d79bd1117 100644--- a/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py+++ b/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py@@ -1,3 +1,5 @@+import datetime+import jsonfrom typing import Any, castimport pytest@@ -6,10 +8,12 @@ from pipelex.core.concepts.concept import Conceptfrom pipelex.core.domains.domain import SpecialDomainfrom pipelex.core.memory.absence import AbsenceKind, AbsenceRecordfrom pipelex.core.memory.working_memory import WorkingMemory+from pipelex.core.stuffs.date_content import DateContentfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.core.stuffs.number_content import NumberContentfrom pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.text_content import TextContent+from pipelex.core.stuffs.yes_no_content import YesNoContentfrom pipelex.hub import get_class_registryfrom pipelex.pipe_run.exceptions import PipeJobErrorfrom pipelex.runtime_bridge.primitives.hydration import (@@ -38,6 +42,26 @@ def _make_text_stuff(name: str, text: str) -> Stuff:)+def _make_yes_no_concept() -> Concept:+ """Build a native YesNo concept for testing."""+ return Concept(+ code="YesNo",+ domain_code=SpecialDomain.NATIVE,+ description="The answer to a yes/no question",+ structure_class_name="YesNoContent",+ )+++def _make_date_concept() -> Concept:+ """Build a native Date concept for testing."""+ return Concept(+ code="Date",+ domain_code=SpecialDomain.NATIVE,+ description="A calendar date, optionally with a time of day — as precise as its source states.",+ structure_class_name="DateContent",+ )++class TestHydrateWorkingMemory:@pytest.fixture(autouse=True)def _register_content_classes(self) -> None:@@ -47,6 +71,10 @@ class TestHydrateWorkingMemory:registry.register_class(TextContent)if not registry.has_class(name="NumberContent"):registry.register_class(NumberContent)+ if not registry.has_class(name="YesNoContent"):+ registry.register_class(YesNoContent)+ if not registry.has_class(name="DateContent"):+ registry.register_class(DateContent)def test_hydrate_with_native_text(self) -> None:"""A raw dict containing TextContent stuff hydrates to typed TextContent."""@@ -62,6 +90,116 @@ class TestHydrateWorkingMemory:assert stuff.content.text == "Hello, world!"assert stuff.stuff_name == "greeting"+ def test_hydrate_with_yes_no(self) -> None:+ """A YesNo stuff survives the dump/hydrate round-trip as typed YesNoContent.++ Cheap insurance against the distributed decode failure mode: a content class that+ fails payload decode inside a Temporal workflow retries forever (a hang, not an error).+ """+ working_memory = WorkingMemory()+ working_memory.root["verdict"] = Stuff(+ stuff_code="test",+ stuff_name="verdict",+ concept=_make_yes_no_concept(),+ content=YesNoContent(yes_no=True),+ )++ raw = working_memory.dump_for_transport()+ hydrated = hydrate_working_memory(raw)++ stuff = hydrated.root["verdict"]+ assert isinstance(stuff.content, YesNoContent)+ assert stuff.content.yes_no is True++ def test_hydrate_yes_no_in_list(self) -> None:+ """A ListContent of YesNoContent survives the dump/hydrate round-trip."""+ working_memory = WorkingMemory()+ working_memory.root["verdicts"] = Stuff(+ stuff_code="test",+ stuff_name="verdicts",+ concept=_make_yes_no_concept(),+ content=ListContent(items=[YesNoContent(yes_no=True), YesNoContent(yes_no=False)]),+ )++ raw = working_memory.dump_for_transport()+ hydrated = hydrate_working_memory(raw)++ content = hydrated.root["verdicts"].content+ assert isinstance(content, ListContent)+ list_content = cast("ListContent[YesNoContent]", content)+ assert [item.yes_no for item in list_content.items] == [True, False]++ def test_hydrate_date_with_offset_preserved(self) -> None:+ """A Date stuff with an offset-carrying time survives the transport round-trip, offset intact.++ Transport dumps in pydantic python mode, so real date/time objects sit in the dict; hydration+ goes back through model_validate (the kajson road). A decode failure here would hang a workflow.+ """+ working_memory = WorkingMemory()+ offset = datetime.timezone(datetime.timedelta(hours=2))+ working_memory.root["departure"] = Stuff(+ stuff_code="test",+ stuff_name="departure",+ concept=_make_date_concept(),+ content=DateContent(date=datetime.date(2026, 7, 7), time=datetime.time(15, 40, tzinfo=offset)),+ )++ hydrated = hydrate_working_memory(working_memory.dump_for_transport())++ stuff = hydrated.root["departure"]+ assert isinstance(stuff.content, DateContent)+ assert stuff.content.date == datetime.date(2026, 7, 7)+ assert stuff.content.time is not None+ assert stuff.content.time.utcoffset() == datetime.timedelta(hours=2)++ def test_hydrate_date_in_list(self) -> None:+ """A ListContent of DateContent survives the round-trip via the __pipelex_class__ marker path."""+ working_memory = WorkingMemory()+ working_memory.root["dates"] = Stuff(+ stuff_code="test",+ stuff_name="dates",+ concept=_make_date_concept(),+ content=ListContent(+ items=[+ DateContent(date=datetime.date(2026, 7, 7)),+ DateContent(date=datetime.date(2026, 8, 6), time=datetime.time(9, 0)),+ ]+ ),+ )++ hydrated = hydrate_working_memory(working_memory.dump_for_transport())++ content = hydrated.root["dates"].content+ assert isinstance(content, ListContent)+ list_content = cast("ListContent[DateContent]", content)+ assert [item.date for item in list_content.items] == [datetime.date(2026, 7, 7), datetime.date(2026, 8, 6)]+ assert list_content.items[0].time is None+ assert list_content.items[1].time == datetime.time(9, 0)++ def test_hydrate_date_from_iso_string_wire(self) -> None:+ """The ISO-string road: a json-mode transport dict (dates/times become ISO strings, as a+ non-kajson wire such as pydantic json-mode or a FastAPI encoder delivers them) must still+ hydrate — model_validate parses the ISO strings back to typed objects, offset preserved.+ """+ working_memory = WorkingMemory()+ offset = datetime.timezone(datetime.timedelta(hours=2))+ working_memory.root["departure"] = Stuff(+ stuff_code="test",+ stuff_name="departure",+ concept=_make_date_concept(),+ content=DateContent(date=datetime.date(2026, 7, 7), time=datetime.time(15, 40, tzinfo=offset)),+ )++ # Force every value through JSON so real date/time objects become ISO strings on the wire.+ raw = json.loads(json.dumps(working_memory.dump_for_transport(), default=str))+ hydrated = hydrate_working_memory(raw)++ stuff = hydrated.root["departure"]+ assert isinstance(stuff.content, DateContent)+ assert stuff.content.date == datetime.date(2026, 7, 7)+ assert stuff.content.time is not None+ assert stuff.content.time.utcoffset() == datetime.timedelta(hours=2)+def test_hydrate_empty(self) -> None:"""An empty WorkingMemory raw dict hydrates to empty WorkingMemory."""working_memory = WorkingMemory()diff --git a/wip/inputs/README.md b/wip/inputs/README.mdnew file mode 100644index 000000000..18f90acd7--- /dev/null+++ b/wip/inputs/README.md@@ -0,0 +1,57 @@+# Inputs track — roadmap and reading guide++This folder holds the design and as-built records for the **Smart Inputs** feature and its two prerequisite native-concept tracks (`YesNo`, `Date`). **Start here on a cold session.**++## Current state (2026-07-08)++The whole inputs track is **code-complete** on `feature/Smart-inputs-phase5` (worktree `_smart`), tip `86f358f97`, based on main at v0.38.0 (includes TOML inputs #1022 + Optionals phase 1 #1021). The branch carries all three tracks; the per-phase branches (`feature/Smart-inputs-phase2/3/5`) are checkpoint snapshots.++- **`YesNo` native concept — ✅ DONE.** As-built: `yesno-implementation-plan.md`.+- **`Date` native concept — ✅ DONE.** PR **#1029** (`feature/native-date`) merged into the track. As-built: `datetime-implementation-plan.md`.+- **Smart Inputs — signature-driven input shaping — ✅ DONE.** All phases 1–5 landed (design D1–D11). As-built: `smart-inputs-implementation-plan.md` (the archived phased plan + per-checkpoint state + micro-decisions log).++PR **#1028** (`feature/Smart-inputs` → `dev`) is the track PR — retitled to cover YesNo + Date + Smart Inputs. Its head still points at an earlier phase tip; **advance its head to the track tip (all phases) before merging**, or the diff will misrepresent what ships.++## What shipped: Smart Inputs++Caller-provided inputs are now interpreted **top-down against the pipe's declared signature** instead of bottom-up from their shape alone. A bare string becomes the *declared* concept (a `legal.Question`, not a generic `native.Text`); a bare number/boolean/date satisfies a `Number`/`YesNo`/`Date`-refining input; a bare URL/path a declared `Image`/`Document` (relative paths resolved against the inputs-file dir); a plain object validates against a structured concept; a list shapes element-wise into `ListContent[declared]` (auto-wrap single, empty legal, `[N]` count-checked); a declared structured list accepts a `.csv` path by signature. The `{concept, content}` envelope stays as a compat-checked escape hatch. Unknown input names now error (D8, the one narrowing). `build inputs` / `pipelex-agent inputs` default to the **light** template, with `--explicit` for the envelope form (D11).++The mechanism: one shaper (`pipelex/core/memory/input_shaper.py`, `InputShaper`) wired into the single seam `WorkingMemoryFactory.make_from_pipeline_inputs(input_specs=…)` that `prepare_pipe_job` feeds `pipe.inputs` — so all surfaces (validate / real-run / dry-run, CLI / Python API / hosted runner) shape through one place. Full rationale + per-phase history in `smart-inputs-implementation-plan.md`.++## What remains: one release cut, one downstream cross-repo wave++Shared across YesNo + Date + Smart Inputs, done **per-release, not per-feature**:++- **D10 protocol widening** — `mthds/protocol/pipeline_inputs.py` `StuffContentOrData` widens to admit bare scalars / lists-of-dicts / empty lists ("any JSON value | StuffContent forms"), with the interpretation semantics spec'd MTHDS-side. Release-gated (Optionals/TOML-inputs de-gate pattern). Runtime already works; this is type-honesty for typed SDK/API callers.+- **Downstream mirrors** — `mthds-python` + `mthds-js` `PipelineInputs` types, conformance rows, JSON-schema copies (`mthds-schema-sync` skill), MTHDS spec native-concept + inputs-format sections.+- **Authoring-guidance surfaces** — `mthds-plugins` skills (`mthds-inputs`, `mthds-build`), `vscode-pipelex` completion lists, and the `ConceptSpec.refines` native-list hint (derive from `NativeConceptCode` — see `refines-hint-native-list-drift.md`).+- **Off critical path** — LLM-assisted input adaptation (design §8, opt-in); the shared YesNo/Date scalar-native LLM-output ergonomics.++## Deferred notes — Phase-5 triage outcomes (2026-07-08)++Each deferred note was re-verified against the landed shaper and given an outcome:++- **Resolved by the shaper** — `case1-bare-date-arm-gap.md` (a top-level date-literal array now builds `ListContent[DateContent]` on the signature path; pinned) and `bare-file-path-cli-resolution-gap.md` (Phase-3 D3: bare Image/Document paths resolve against the inputs-file dir).+- **Partially closed** — `input-shaper-multiplicity-gaps.md`: the finalize review re-found Gap A as a *silent* behavior (an explicit `ListContent` stored into a singular slot), so the **unambiguous half of Gap A is now fixed** (`_shape_explicit` rejects list-into-singular and enforces the `[N]` count on explicit lists for shaped concepts, while preserving `native.Dynamic` bottom-up fallback; pinned by new `test_explicit_forms.py` cases). Gap A's auto-wrap sub-question and the broader Gap B (`DYNAMIC` multiplicity peeling for `Dynamic[]`/`Anything[N]`) stay deferred as the genuine tradeoffs.+- **Re-deferred, reasoning refreshed** — `scalar-envelope-arm-asymmetry.md` (bare path now builds the refining subclass; only the *envelope* escape hatch keeps the base-`TextContent` asymmetry, and closing it means surgery on a shared bottom-up factory arm for near-zero gain); `loader-vs-factory-date-split-duplication.md` (the shaper did not collapse the CLI-format loader — different layers).+- **Decided leave-it** — `d4-hint-still-envelope.md` (the D4 error hint keeps rendering the envelope shape; option 1, it is a valid unambiguous fallback and making it light is a layer/cycle refactor unjustified by a fallback string).+- **Still out of scope (structure-field codegen / URI-tools / release-wave authoring)** — `container-default-temporal-codegen-gap.md`, `structure-field-fidelity-guard.md` (both structure-field codegen, untouched by Smart Inputs), `uri-scheme-classification-stopgap.md` (a `tools/uri` `resolve_uri` refactor; no live bug, tested), `refines-hint-native-list-drift.md` (the release-wave authoring-guidance sweep).++## Documents++**Design (source of truth for decisions):**++- `smart-inputs-design.md` — the approved Smart Inputs design: problem, shape at a glance, decisions D1–D11, non-goals, §9 surfaces checklist.+- `datetime-design.md` — the approved Date-track design (DT1–DT8).++**Implementation plans / as-built records:**++- `smart-inputs-implementation-plan.md` — the Smart Inputs phased plan + as-built (all phases done): cold-start code map, verified mechanism facts, per-checkpoint state lines, micro-decisions log, and per-phase review rounds.+- `yesno-implementation-plan.md` — YesNo phased plan + as-built.+- `datetime-implementation-plan.md` — Date phased plan + as-built, incl. the bot rounds and the gstack `/review` finalize.++**Archived:**++- `yesno-pr-reviewers-guide.md` — the former YesNo PR reading guide. Historical.++**Deferred design notes** (triage outcomes above): `case1-bare-date-arm-gap.md`, `bare-file-path-cli-resolution-gap.md`, `scalar-envelope-arm-asymmetry.md`, `loader-vs-factory-date-split-duplication.md`, `input-shaper-multiplicity-gaps.md`, `d4-hint-still-envelope.md`, `container-default-temporal-codegen-gap.md`, `structure-field-fidelity-guard.md`, `uri-scheme-classification-stopgap.md`, `refines-hint-native-list-drift.md`.diff --git a/wip/inputs/bare-file-path-cli-resolution-gap.md b/wip/inputs/bare-file-path-cli-resolution-gap.mdnew file mode 100644index 000000000..b09bfb13b--- /dev/null+++ b/wip/inputs/bare-file-path-cli-resolution-gap.md@@ -0,0 +1,34 @@+# RESOLVED (Phase 3): bare Image/Document path strings now resolve against the inputs-file dir++**Status:** **RESOLVED in Smart Inputs Phase 3 (2026-07-07).** The fix landed as the Phase-3 D3 arm — see `TODOS.md` Phase 3 + the "Phase 3" micro-decisions. Surfaced by the PR #1030 bot review, 2026-07-07 ([Codex thread](https://github.com/Pipelex/pipelex/pull/1030#discussion_r3538032585), [cubic thread](https://github.com/Pipelex/pipelex/pull/1030#discussion_r3538053292) — the two unresolved threads on `execution_seams.py`). **Both threads are now answerable + resolvable.**++## How it was fixed (differs from the recommendation below)++The chosen mechanism was **thread `inputs_base_dir` into the shaper**, NOT making the CLI resolver signature-aware (the recommendation in the section below). At implementation the signature-aware-CLI-resolver route proved worse on three counts: it would force pipe/library resolution BEFORE the runner call in `_run_core.py`, duplicate the shaper's concept-nature detection in the CLI, and fail to cover the CSV-relative-path case (splitting resolution across two places). Instead: the human CLI (`_run_core.py`) and agent CLI (`parse_cli_inputs` → `ParsedCliInputs` NamedTuple) capture the inputs file's parent dir and hand it to the runner ctor (`inputs_base_dir`); it threads through `pipeline_run_setup` → `prepare_pipe_job` → `make_from_pipeline_inputs` → `InputShaper.shape`, and the shaper's Image/Document arm (and CSV arm) resolve bare relative local paths against it via `is_relative_local_path` (promoted to `pipelex/tools/uri/uri_resolver.py`). API/SDK/in-process callers pass `inputs_base_dir=None` and keep absolute-url semantics. The bare form and the `{"url": …}` form now land on the same resolved result (pinned by the e2e).++The original deferral rationale and the (rejected) recommendation are kept below for the historical record.++---++## What the reviewers flagged (verified — the mechanism is real)++With Phase 2 shaping live, a bare string for a declared `Image`/`Document`-family input is shaped into `ImageContent(url=<raw string>)` / `DocumentContent(url=<raw string>)` (the `InputKind.IMAGE | InputKind.DOCUMENT` arm in `pipelex/core/memory/input_shaper.py` does `{"url": value}` → `_make_content`). But the CLI inputs-file path resolver `resolve_url_in_value` (`pipelex/cli/commands/run/_inputs_path_resolver.py`) rewrites relative local paths **only under dict keys literally named `"url"`**, and it runs on the raw parsed dict *before* the pipe signature exists (`_run_core.py` and the agent CLI's `stdin_resolver.py`, base_dir = inputs file's parent).++Net effect: for an inputs file outside the CWD, `{"contract": "docs/a.pdf"}` for a `Document` input stays unresolved and is later read relative to the process CWD — while the explicit `{"url": "docs/a.pdf"}` form IS resolved against the inputs-file dir. Phase 2 made the two forms diverge.++## Why deferred, not fixed in Phase 2++- **It is a known, scheduled gap, not a regression.** `TODOS.md` names it three times: the cold-start "Path resolution today (D3/D7)" fact, the "D3 path-resolution seam" gap (with the recommended fix), and Phase 3's **first task** ("Settle the D3 path-resolution mechanism"). `smart-inputs-design.md` §D3 defers the same question to implementation time. Phase 3 is the immediate next work on this branch.+- **No previously-working path regresses.** Explicit `{"url": …}`, absolute paths, and storage URIs all resolve exactly as before. Only the *new* bare-string convenience is half-wired.+- **The common failure is loud, not silent.** An unresolved relative path raises `FileNotFoundError` at extraction. The "reads the wrong file" case requires a same-named file to also exist under the CWD — a narrow footgun.+- Building the fix now would pull Phase 3 scope forward and duplicate its tests-first sequencing.++## Interim guard → considered and NOT added++The bots' alternative — gate bare *relative local* paths for Image/Document (typed shaping error pointing at absolute paths or `{"url": …}`) until Phase 3 — was considered and rejected: it is churn Phase 3 immediately rips out, for a low-severity window whose common failure mode is already loud.++## The fix (Phase 3, D3 — already planned)++Make the CLI resolver signature-aware: resolve the pipe first, then pass its `InputStuffSpecs` into `resolve_inputs_paths` so bare relative strings whose declared concept is Image/Document-family get resolved against the inputs-file dir *alongside* `"url"` keys — keeping path resolution a CLI concern (API/SDK callers pass absolute URLs / storage URIs; no base_dir leaks into core). Tests first, per the Phase 3 checklist: the e2e must pin both the bare form and the `{"url": …}` form to the same resolved result, driven through the CLI file-load path (the current smart_inputs e2e passes in-process dicts, which never hit `resolve_inputs_paths`).++When Phase 3 lands, answer + resolve the two open PR #1030 threads.diff --git a/wip/inputs/case1-bare-date-arm-gap.md b/wip/inputs/case1-bare-date-arm-gap.mdnew file mode 100644index 000000000..d9146733e--- /dev/null+++ b/wip/inputs/case1-bare-date-arm-gap.md@@ -0,0 +1,26 @@+# RESOLVED (Smart Inputs): a top-level array of date literals now builds `ListContent[DateContent]`++**Status:** **RESOLVED in Smart Inputs (2026-07-08, Phase-5 triage).** The signature-driven shaper closes the one real gap this note held (a top-level TOML date array). The historical framing is kept below for the record.++## What was flagged (Date-track PR review, 2026-07-07)++`StuffFactory.make_stuff_from_stuff_content_or_data` Case 1 (a value passed directly, not wrapped in a `{concept, content}` envelope) has arms for a bare `StuffContent` (1.3) and for `list[str]` / `list[StuffContent]` (1.2/1.4), but **no arm for a bare `datetime.date`/`datetime.datetime` object, nor for a `list[datetime.date]`**. The Date arm was only added to Case 2 (the envelope). So a bare date object or a date array reaching Case 1 falls through to an "unexpected type" / "Cannot create Stuff from list of ..." error.++## Bare scalar date → still DISMISSED (impossible on any real path)++A bare top-level `datetime.date`/`datetime.datetime` cannot reach Case 1:++- **CLI path:** the inputs-file loader's `_convert_temporal_inputs` (`_inputs_file_loader.py`) converts every **top-level** scalar date/datetime literal into a `DateContent` *before* the value reaches the seam. It therefore arrives as a `StuffContent` and is handled by Case 1.3 — never as a bare date.+- **API/protocol path:** the `StuffContentOrData` union (in mthds-python, `mthds/protocol/pipeline_inputs.py`) does **not** admit bare `datetime` objects. A well-typed caller cannot pass one.++Adding a bare-scalar-date arm to Case 1 would be a dead branch guarding a scenario no real caller produces. Not added.++## Top-level `list[datetime.date]` → RESOLVED by the shaper++The loader converts only top-level **scalar** temporal literals, so a top-level TOML array of date literals (e.g. `deadlines = [2026-01-01, 2026-02-02]`) is left as a `list[datetime.date]` and reaches the pipeline-inputs seam. With Smart Inputs live, that seam is `InputShaper.shape` (signature-driven), not the bottom-up factory: under a declared Date-refining `[]` input the list flows through `_shape_with_multiplicity` → `_shape_list` → the `InputKind.DATE` arm of `_build_item_content` (which accepts a `datetime.date`/`datetime.datetime` element and builds the declared `DateContent` subclass). The result is a `ListContent[DateContent]` typed with the declared concept — exactly what D2 + the shaper's Date arm promise. No Case-1.4 arm was added to the bottom-up factory; the fix is the top-down layer the note anticipated.++Pinned by `tests/unit/pipelex/core/memory/input_shaper/test_multiplicity.py::TestInputShaperMultiplicity` (the `variable-list-of-date-objects` case).++## Residual (unchanged, out of the shaper's scope)++The *no-signature* bottom-up path (`WorkingMemoryFactory.make_from_pipeline_inputs(..., input_specs=None)` → `StuffFactory` directly) still has no Case-1.4 date arm, so a `list[datetime.date]` reaching the factory without a signature still errors cleanly. That is correct: Smart Inputs shapes only when a signature is present, and the signature is what makes a date array interpretable. The broader protocol widening for sequences of scalars (design D10) rides the release wave regardless.diff --git a/wip/inputs/container-default-temporal-codegen-gap.md b/wip/inputs/container-default-temporal-codegen-gap.mdnew file mode 100644index 000000000..a4d71e60d--- /dev/null+++ b/wip/inputs/container-default-temporal-codegen-gap.md@@ -0,0 +1,28 @@+# Deferred: temporal defaults inside a list/dict structure-field default aren't codegen-safe++**Status:** deferred design note — no code change. Surfaced during the Date-track PR #1029 adversarial review, 2026-07-07.++## What the reviewer flagged++DT8 taught `StructureGenerator._format_default_value` to render a **scalar** temporal default as `date.fromisoformat("…")` / `datetime.fromisoformat("…")` — because `repr()` module-qualifies a temporal object (`datetime.date(2026, 7, 7)`), and the generated code imports the *bare* classes (`from datetime import date, datetime`) with `exec_globals` binding `datetime` to the datetime *class*. Under those globals, `datetime.date(2026, 7, 7)` resolves to the `datetime.date` method descriptor and raises `TypeError` at exec.++The scalar fix does not recurse into containers. A `date`/`datetime` object nested inside a **list or dict default** falls through to the `repr()` branch, so the same module-qualified form is emitted and the generated class body raises at exec.++## Reachability — real but narrow++Confirmed reachable through a hand-written `.mthds` concept structure field:++- The core `ConceptStructureBlueprint._validate_default_value_type` LIST arm only checks `isinstance(self.default_value, list)` — it does **not** validate element types. So `{type = "list", item_type = "date", default = [2026-07-07]}` passes blueprint validation. (The spec layer forbids list/dict defaults, but the blueprint layer — the one the generator consumes — does not.)+- The list default then reaches `_format_default_value([date(2026, 7, 7)])`, which is neither `str` nor a scalar `date`/`datetime`, so it hits `repr(...)` → `"[datetime.date(2026, 7, 7)]"` → cryptic `TypeError` (`descriptor 'date' for 'datetime.datetime' objects doesn't apply to a 'int' object`) at concept-build time, on otherwise-valid MTHDS input.++## Why deferred, not fixed in the Date track++- **Not a regression.** The container `repr()`-qualification bug pre-dates DT8: before DT8, a `type = "date"` scalar *and* a list-of-date default both hit `repr()` and broke. DT8 fixed the scalar case; the container case was already broken and stays broken.+- **Errors, does not silently corrupt.** It fails loudly at concept build, so no wrong data ships.+- **The fix is a design choice, not a mechanical patch.** Two reasonable shapes: (a) make `_format_default_value` recurse into list/dict/tuple and emit `fromisoformat(...)` per temporal element; or (b) reject container defaults containing temporal objects at blueprint validation with a clear message (turning the cryptic exec error into a proper `default_value type mismatch`). (b) is smaller and arguably the better guard; (a) is more complete. Deciding belongs with whoever revisits structure-field defaults, not bolted onto the Date track.++## Follow-up to consider++When structure-field default handling is next touched (Smart Inputs, or a dedicated codegen pass), pick (a) or (b) above. If (a), share the temporal-formatting helper the scalar branch already uses. Related notes: `case1-bare-date-arm-gap.md`, `loader-vs-factory-date-split-duplication.md`, `structure-field-fidelity-guard.md`.++No action needed inside the Date track.diff --git a/wip/inputs/d4-hint-still-envelope.md b/wip/inputs/d4-hint-still-envelope.mdnew file mode 100644index 000000000..7189aa0f1--- /dev/null+++ b/wip/inputs/d4-hint-still-envelope.md@@ -0,0 +1,25 @@+# D4 shaping-error hint still renders the envelope shape (not the light shape)++Status: **deferred tradeoff, surfaced during Smart Inputs Phase 4 (2026-07-07).** Not a bug; a consistency question for Phase 5 triage.++## What++Phase 4 flipped the generated inputs template (`build inputs` / `pipelex-agent inputs`) to the **light** signature-driven shape by default (bare values), with the `{concept, content}` envelope behind `--explicit`.++But the D4 shaping-error hint — the "Expected shape:" line every `InputShapingError` renders via `InputShaper._render_expected_shape` → `stuff_spec.render_stuff_spec(ConceptRepresentationFormat.JSON)` — still emits the **envelope** form. So a caller who provides a bare (light) value that fails to shape sees an *envelope*-shaped hint, while the template they generated was light. Mild inconsistency: "you gave me a bare string but here's a `{concept, content}` object" reads slightly off now that bare is the blessed default.++## Why it wasn't fixed in Phase 4++Making the hint light would mean the **shaper** producing the light form. The light transform lives in `input_renderer` (`pipelex/core/pipes/inputs/`), which imports `InputShaper` (`pipelex/core/memory/`). Having the shaper call back into `input_renderer` to render a light hint would be a layer inversion / import cycle (input_renderer → input_shaper today; the reverse would close the loop). The delighten transform would have to move to a neutral home the shaper can import, or be duplicated — both bigger than the Phase-4 surface warranted, and none of the Phase 1–3 e2e error tests pin the exact hint shape (they assert only `"Expected shape:" in message`), so nothing forces the change.++## Options for Phase 5 triage++1. **Leave it.** The envelope hint is unambiguous and always valid input; arguably it's the *most* explicit thing to show someone who just failed to provide a value. Cheapest.+2. **Make the hint light.** Move the delighten transform (`_delighten_entry` + `_unwrap_scalar_content`) to a home both `input_shaper` and `input_renderer` import (e.g. alongside `resolve_input_kind`), then have `_render_expected_shape` render the light form. Consistent with the template, but a real refactor + a layer decision.+3. **Show both.** Hint renders the light form as the primary "provide this" and mentions the envelope escape hatch. More words, most helpful.++Recommendation: **option 1 (leave it) unless a Phase-5 doc pass or user feedback shows the envelope hint actively confuses.** The light template is the teaching surface; the error hint is a fallback and being explicit there is defensible.++## Phase-5 triage (Smart Inputs, 2026-07-08) — DECIDED: leave it (option 1)++Settled on **option 1**. The envelope form the hint shows is always valid input and unambiguous — the most explicit "here is a shape that will work" you can hand someone who just failed to provide a value; it is a fallback surface, not the teaching surface (the light template is). Option 2 (make the hint light) still carries the layer/cycle cost described above — the delighten transform lives in `input_renderer`, which imports `input_shaper`, so having the shaper render a light hint means moving that transform to a shared home or duplicating it, a real refactor unjustified by a fallback string. Nothing in the shipped docs pass leans on the hint being light, and no evidence it confuses. Reopen only if user feedback shows the envelope hint actively misleads now that bare is the blessed default.diff --git a/wip/inputs/datetime-design.md b/wip/inputs/datetime-design.mdnew file mode 100644index 000000000..528fdd4c5--- /dev/null+++ b/wip/inputs/datetime-design.md@@ -0,0 +1,137 @@+# Datetime track — a native `Date` concept: design proposal++Status: **design approved — all decisions DT1–DT8 approved by Louis 2026-07-07**. Companion track to `YesNo` (smart-inputs-design.md §D9), step 2 of the execution order in this folder's `README.md`. Time-boxed and abandonable by design: every decision below is severable, and the whole track can stop at any point without blocking YesNo or Smart Inputs. Implementation plan: `datetime-implementation-plan.md`.++## 1. What this must deliver, and the bar it must clear++Three concrete jobs:++- **Retire the TOML rejection.** Since TOML inputs (#1022), TOML's native date/datetime/time literals are rejected wholesale by `InputsDatetimeNotSupportedError` (`pipelex/cli/commands/run/_inputs_file_loader.py:111`) with "quote it as a string in the meantime". The meantime ends here.+- **Give the native family a temporal concept.** Dates are arguably the most common typed value on the documents Pipelex methods read — contracts (effective date, termination date), invoices (issue date, due date), tickets (departure), certificates (date of birth). Today authors model them as `Text` or as a `date` structure field; there is no concept-level citizen.+- **Ready the Smart Inputs matrix row.** The D5 interpretation matrix gains a temporal row when this lands (purely additive).++The bar, per Pipelex's identity: the concept must read like something found *on a document*, not in a type system — non-tech authors write `output = "Date"` the way they'd label a column in a spreadsheet. And it must be LLM-native: an agent reading the concept must know instantly what to write, and a PipeLLM constrained to produce it must never be *forced by the schema* to state more than the source document states.++## 2. The central question: one concept or three?++TOML distinguishes four temporal literals (offset date-time, local date-time, local date, local time); Python/pydantic/JSON-Schema split the family into `date`, `time`, `date-time`. The programming answer is therefore "three concepts". We propose the document answer instead: **one**.++**The document test.** Walk the documents Pipelex is built for. A contract says "Effective Date: March 1, 2026". An invoice says "Due date: 2026-08-06". A plane ticket says "Departure: 7 Jul 2026, 15:40". A meeting invite says "Date & time: July 7 at 3:00 PM CET". In plain speech every one of these is *a date* — sometimes with a time, sometimes without. Nobody reading a ticket says "the departure datetime". A time alone, unmoored from any date ("opening hours: 9:00"), is comparatively rare and is not the same kind of thing — it's a recurring time-of-day, not a point in history.++**The LLM-fidelity test — the decisive argument.** Suppose we shipped separate `Date` and `Datetime` concepts. The author of an extraction pipe must now *predict the precision of documents they haven't seen*. Declare `output = "Datetime"` and the document says "delivery by March 15": constrained generation forces the model to fabricate a time — you get `2026-03-15T00:00:00`, hallucinated precision that propagates downstream looking exactly like real data. Declare `Date` and the document carries a full timestamp: the time is silently discarded. Both failure modes are structural — no prompt engineering fixes a schema that demands more (or less) than the source states. A single concept with an *optional* time component makes both failure modes unrepresentable: the LLM states the date, adds the time only when the source has one, and the output's precision *is* the document's precision.++**Precedents from user-friendly systems** (same lineage as the YesNo naming research): Notion's property is "Date" and optionally includes a time; Google Calendar events have a date and optionally a time (all-day vs timed — same model); Airtable's "Date" field has an "include time" toggle; Access says "Date/Time" as one type. The tools built for non-programmers converged on exactly this shape: one thing called a date, time optional.++**Rejected alternatives:**++- **Three natives (`Date`, `Time`, `Datetime`)** — maximal fidelity to TOML/stdlib, but two of the three earn almost nothing on real documents, the native family is precious real estate (every agent holds the whole list in mind), and the author-must-predict-precision trap remains.+- **Two natives (`Date` + `Datetime`)** — the conventional programming compromise; still has the fabricated-midnight trap, still forces a choice the author can't reliably make, and "Datetime" is database lingo on a surface that speaks contract-and-invoice.+- **One native named `Datetime` with required time** — the name fails the plain-language test and the required time fails the fidelity test.+- **One native, time always optional, named `Date`** — **proposed.**++What we give up: time-of-day alone has no native home (TOML local-time literals stay rejected, with a narrowed message — see DT5). If demand materializes, a `Time` native can be added later without disturbing anything decided here.++## 3. The shape at a glance++```toml+[concept.DueDate]+description = "The date payment is due"+refines = "Date"++[concept.Departure]+description = "The scheduled departure of the flight"+refines = "Date"++[pipe.extract_departure]+type = "PipeLLM"+description = "Extract the departure from the ticket"+inputs = { ticket = "Ticket" }+output = "Departure"+prompt = """Extract the scheduled departure from this ticket: @ticket"""+```++The LLM sees a schema with a required `date` and an optional `time`, each field description telling it to state only what the source states. From a ticket it produces `{"date": "2026-07-07", "time": "15:40:00"}`; from "delivery by March 15" it produces `{"date": "2026-03-15", "time": null}` — no fabricated midnight.++On the inputs side, TOML literals just work:++```toml+# inputs.toml+hearing_date = 2026-09-01 # a Date — date only+departure = 2026-07-07T15:40:00+02:00 # a Date — with time and offset, faithfully kept+```++## 4. Proposed decisions++### DT1 — One native concept, named `Date`++`NativeConceptCode.DATE = "Date"`, concept ref `native.Date`, description: *"A calendar date, optionally with a time of day — as precise as its source states."* One new native, not two or three (§2). The track keeps its colloquial "Datetime" name in the roadmap; the concept an author sees is `Date`.++Breaking consequence (native codes are reserved): a bundle declaring its own `[concept.Date]` becomes an error. Workspace grep (pipelex, cookbook, methods, test-bed) finds no such concept today. Changelog: breaking.++### DT2 — Content shape: `DateContent` with `date` + optional `time`++```python+class DateContent(StuffContent):+ date: datetime.date+ time: datetime.time | None = None+```++Follows the `NumberContent.number` field-naming pattern. The UTC offset, when the source states one, rides on the `time` field's `tzinfo` — pydantic parses and serializes `"15:40:00+02:00"` natively. This makes the invalid states unrepresentable by construction: no time without a date, no offset without a time (a calendar date alone has no meaningful offset). Field descriptions on the class carry the anti-fabrication instruction ("include the time only when the source states one — never invent a time"), which flows into `model_json_schema()` and is therefore inherited by every refining concept's LLM generation for free.++Helpers kept minimal for core scope: a `to_datetime()` method for Python consumers that need a `datetime.datetime` (behavior when `time is None` — raise vs midnight-default — settled at implementation-plan time; leaning raise, so nobody gets a silent midnight). No comparison/arithmetic surface (non-goal).++### DT3 — Timezone policy: fidelity, not normalization++The concept stores **what the source states — never more, never less**. Offset present in the source → preserved verbatim; absent → naive time, and nothing downstream invents one. No normalization to UTC at the concept level: converting timezones is a *computation*, i.e. a pipe's job, not a data type's. Offsets only, no named-timezone (IANA) support: names require DST arithmetic and a tz database, and the sources we read (ISO strings, TOML literals) carry offsets, not names. "3 PM Paris time" extracts as a naive 15:00 plus whatever the prompt asks for — resolving it to an offset is an explicit pipe step if a method needs it. The naive-vs-aware question dissolves: both are valid states of the same concept, distinguished by what the document said.++### DT4 — Rendering: ISO 8601, truncated to stated precision++`rendered_plain` / `rendered_markdown` / `rendered_html` render the ISO 8601 form of exactly what is stored: `2026-07-07`, `2026-07-07T15:40:00`, `2026-07-07T15:40:00+02:00`. ISO is locale-free, unambiguous, and the temporal notation LLMs know best — this is what a prompt sees when a `Date` input is inserted via `@var`/`$var`. `rendered_json` mirrors the two-field structure (`{"date": ..., "time": ...}`). `short_desc`: "a date (2026-07-07)" / "a date and time (2026-07-07T15:40:00+02:00)". Structured concepts already render embedded dates as ISO (`html_rendering.py:53`), so this is consistent with existing behavior. Human/locale-friendly formatting ("July 7, 2026") is presentation, deliberately left to Jinja filters or downstream renderers — never the concept's job.++### DT5 — Inputs behavior in core scope (pre-Smart-Inputs)++This track ships before signature-driven shaping, so it extends today's bottom-up rules:++- **TOML date and datetime literals map natively.** `tomllib` yields real `datetime.date` / `datetime.datetime` objects; the loader's rejection walk stops rejecting them. Bottom-up: a bare `datetime.date`/`datetime.datetime` value becomes a `native.Date` stuff (mirror of "bare string becomes `native.Text`") — `StuffFactory` gains the arm, `StuffContentFactory.make_content_from_value` gains the `DateContent` special cases (date object, datetime object, ISO string, `{"date","time"}` dict).+- **TOML local-time literals stay rejected**, with a narrowed error: a time without a date is not a `Date`. The error class survives with a scoped-down name/message (detail for the plan; message should say "a time of day alone has no date to attach to — include the date or quote the value as a string").+- **JSON bare strings are NOT sniffed.** A top-level `"2026-07-07"` in `inputs.json` stays `Text` under bottom-up rules — guessing "ISO-looking string means date" is exactly the guessy behavior the Smart Inputs non-goals forbid. JSON callers reach `Date` via the envelope (`{"concept": "Date", "content": "2026-07-07T15:40:00"}`) until Smart Inputs lands, at which point the declared signature does it (DT6).+- **Python API** accepts `datetime.date` / `datetime.datetime` objects directly, same mapping.++### DT6 — The Smart Inputs matrix row (forward note, lands with that feature)++When signature-driven shaping ships, the D5 matrix gains: *Date-refining concept (⊑ `DateContent`)* ← accepted bare values: ISO 8601 `str` (strict — pydantic parsing, no loose formats, no "March 7"), `datetime.date` / `datetime.datetime` objects (TOML/Python), `{"date": ..., "time": ...}` dict. Explicitly rejected: `int`/`float` (no epoch-seconds interpretation — pydantic's lenient number-to-datetime coercion must be disabled, the temporal cousin of the bool-is-not-int guard in D9). ISO-string acceptance here is not cross-type parsing in the forbidden sense: JSON has no temporal type, the string is the only possible carrier, and the declared signature is what disambiguates — the same logic that lets D3 read bare strings as URLs for file concepts.++### DT7 — LLM output: rides the object path day one; ergonomics deferred with YesNo's++`PipeLLM` with a non-Text output already ships the content class's `model_json_schema()` to the LLM (`assignment_models.py:95`), so `output = "Date"` works from day one: the model sees `{date: string/format=date, time: string/format=time | null}` plus the DT2 field descriptions. No special generation path in core scope. Whether scalar-wrapper natives deserve a leaner generation form (the cousin-of-maybe-wrapper question) is already parked as the YesNo LLM-output-ergonomics follow-up — `Date` joins that same follow-up rather than opening its own. Note: `Date` has an easier ride than `YesNo` here, because its object form is genuinely two fields, not a wrapped scalar.++### DT8 — Fix the `date` structure-field misnomer (severable adjacent cleanup)++Discovered while grounding this design: the structure-field type `date` (`ConceptStructureBlueprintFieldType.DATE`) maps to Python `datetime.datetime` (`structure_generation/generator.py:375`), whose JSON schema is `format: date-time`. So **every cookbook extraction with a `type = "date"` field (invoice dates, DPE dates) already forces the LLM to fabricate a time of day today** — the field-level version of the exact hallucination this design eliminates at concept level. Proposed fix, aligned with the no-backward-compat principle: field type `date` maps to `datetime.date` (what the name says), and a new field type `datetime` maps to `datetime.datetime` for the rare field that genuinely wants a timestamp. Touches the generator's two mapping sites, the blueprint default-value validator (`concept_structure_blueprint.py:180` currently checks `isinstance(..., datetime)`), the line-64 TODO, schema regen, and docs (`inline-structures.md`). Breaking for any method that relied on `date` fields carrying time — workspace usages all name calendar dates and would *improve*. Severable: ships as its own commit in the same wave, and dropping it doesn't dent DT1–DT7. An alternative field-level design — making `date` fields carry the DT2 composite — is rejected: structure fields are plain machine types by design; a field wanting document-fidelity semantics can be `type = "concept", concept_ref = "Date"`.++## 5. Non-goals++- **No `Time` native.** Time-of-day alone (opening hours) has no native home; degrade to Text or a structure field. Add later if real demand appears.+- **No partial dates.** "March 2026", "Q3" are not representable — the precision floor is a full calendar date. Anything fuzzier is `Text` or a domain-structured concept (the EDTF rabbit hole stays closed).+- **No durations or relative dates.** "Net 30 days", "next Tuesday" are different concepts (a future `Duration` native is imaginable; not now).+- **No named timezones, no DST math, no normalization** (DT3).+- **No locale rendering** (DT4) and **no comparison/arithmetic surface** on the concept.++## 6. Core-scope surfaces checklist (for the implementation plan)++- `pipelex/core/concepts/native/concept_native.py` — `DATE = "Date"` + arms in the four exhaustive matches (`structure_class`, `is_composite`, `is_text_concept`, `is_dynamic_concept`).+- New `pipelex/core/stuffs/date_content.py` — `DateContent` per DT2/DT4.+- `pipelex/core/registry_models.py` — register `DateContent` in `CoreRegistryModels.STUFF`.+- `pipelex/core/concepts/concept_factory.py` — `case NativeConceptCode.DATE:` arm with the DT1 description.+- `pipelex/core/stuffs/stuff_factory.py` + `stuff_content_factory.py` — bottom-up arms per DT5.+- `pipelex/cli/commands/run/_inputs_file_loader.py` + `run/exceptions.py` — narrow the rejection to time-only per DT5; update both catch sites' expectations; regen error pages (`make gep`).+- Dry-run mock filling — verify the mock path in `working_memory_factory.py` can synthesize a `Date` (likely free via the registry; confirm at plan time).+- DT8 (severable): `concept_structure_blueprint.py`, `structure_generation/generator.py`, docs.+- Schema regen (`pipelex-dev generate-mthds-schema`) — note the native ref itself doesn't change the schema shape; DT8 does (field-type enum).+- Docs: `docs/building-methods/concepts/native-concepts.md` table entry; inputs docs mention of TOML literals; `inline-structures.md` if DT8 ships.+- Tests: content-class unit tests (render matrix, offset round-trip), inputs-loader tests replacing the four-flavor rejection parametrization (date ✓, local datetime ✓, offset datetime ✓, local time ✗ narrowed), e2e `.mthds` with TOML date inputs, LLM-output smoke via existing structured-gen harness.+- Downstream wave (per-release, shared with YesNo/Smart Inputs): MTHDS spec native table (`mthds/docs/language/concepts.md`, `spec/mthds-format.md`), schema sync, mthds-python/mthds-js mirrors, conformance, skills, editor tooling completion lists.++## 7. Abandonability check++The README's standby clause holds. DT1–DT4 are one enum value, one small class, one factory arm — the irreducible core. DT5 is the payoff (retires the shipped error) but degrades gracefully if dropped (the error simply keeps telling users to quote strings). DT6 belongs to Smart Inputs anyway. DT7 costs nothing. DT8 is explicitly severable. If the composite-content semantics (optional time, offset-on-time) turn out to fight the machinery anywhere — mock filling, kajson round-trips, schema emission — the track stops, nothing else on the train is blocked, and this document records where it stopped and why.diff --git a/wip/inputs/datetime-implementation-plan.md b/wip/inputs/datetime-implementation-plan.mdnew file mode 100644index 000000000..641f58d2b--- /dev/null+++ b/wip/inputs/datetime-implementation-plan.md@@ -0,0 +1,154 @@+# Datetime track — the native `Date` concept (as-built)++Status: **COMPLETE 2026-07-07.** All phases shipped, gates green. Design: `datetime-design.md` (approved, DT1–DT8). Based on main at v0.38.0. Track order (`README.md`): YesNo → **Datetime (this doc)** → Smart Inputs, one release wave. This doc is now the as-built record and the PR reviewer's guide; the phase-by-phase log and checkpoint states below capture exactly what landed and why.++## ⏩ Session handoff — resume here (cold start)++**Where the code lives.** The Date work is its own branch `feature/native-date` (NOT `feature/Smart-inputs`), tip **`c32c7595d`**. It is stacked: `feature/native-date` = the YesNo tip (`772c628c6`, = `origin/feature/Smart-inputs`) + the 6 Date phase commits (`0b6d201bb` → `2d7b3d503`) + the plan-doc rewrite (`dd3db9026`) + two bot-review fix commits (`978698b5c`, `c32c7595d`). Local `feature/Smart-inputs` was reset back to `origin` so it carries only YesNo. Everything is pushed.++**The PR.** **#1029** "Add native Date concept", base **`feature/Smart-inputs`** (so the diff is Date-only), head `feature/native-date`. It is **stacked on the still-open YesNo PR #1028** (base `dev`, head `feature/Smart-inputs`, still OPEN). ➜ **When #1028 merges to `dev`, retarget #1029 to `dev`** (GitHub usually auto-retargets on base-branch merge; verify).++**What's done.** All 5 phases + DT8 (checkpoints 1–4 below). Two bot-review rounds fully arbitrated and **all threads resolved (0 open)**:++- Round 1 (on `978698b5c`): fixed two real DT8-adjacent generator bugs (`build inputs` emitted an unparseable `"date_date"` placeholder for a Date input; temporal `default_value` rendered as module-qualified `datetime.datetime(...)` → `AttributeError` at eval) + three tightenings; dismissed the impossible bare-scalar Case-1 claim (no dead branch), deferred the real list-array gap to `case1-bare-date-arm-gap.md`.+- Round 2 (on `c32c7595d`): three test-oracle tightenings + one doc sigil fix (`@ticket` → `$ticket`, which the sigil validator rejects inline when the id is a declared input).++**CI.** Green on `978698b5c` across py3.11–3.14 tests + typechecks + both bot *checks* (Greptile pass, cubic pass). `c32c7595d` (test-only + one doc line) pushed after; **re-verify its CI went green** on resume.++**What remains (the goal loop's tail).** The finalize gstack `/review` **has now been run** (2026-07-07, Opus 4.8, testing + maintainability + adversarial-red-team fan-out with pointer-only context). It found one real defect the PR introduced and applied it plus low-risk polish; see the "gstack /review finalize round" subsection below. Only thing genuinely left: **retarget #1029 → `dev` once YesNo #1028 merges** (GitHub usually auto-retargets on base merge; verify). The optional bot re-trigger on the later commits was skipped as low-value (round-2/3 changes are test + doc + comment only; bots were already happy on `978698b5c`).++**Constraints (kept for any future sub-agent):** clean solid software, no over-engineering, don't guard impossible scenarios; on any doubt, defer as a new `.md` under `wip/inputs/`. For `/code-review` fan-outs specifically: pointer-only context (a commit SHA / diff / working-tree files), never the plan or rationale.++**Deferred notes (open):** `wip/inputs/case1-bare-date-arm-gap.md`, `scalar-envelope-arm-asymmetry.md`, `loader-vs-factory-date-split-duplication.md`, `container-default-temporal-codegen-gap.md`, `structure-field-fidelity-guard.md`; shared YesNo/Date LLM-output ergonomics; the release-wave cross-repo sweep (see the bottom section).++## As-built summary — for PR reviewers++**What shipped:** one new native concept `Date` — *"A calendar date, optionally with a time of day — as precise as its source states."* Content class `DateContent(date: datetime.date, time: datetime.time | None)`: a required calendar date plus an *optional* time (its UTC offset kept verbatim on the `time`'s tzinfo). The whole point is document-fidelity: an LLM producing a `Date` states the time only when the source does — no fabricated midnights — and the output's precision *is* the document's. See `datetime-design.md` §2 for the one-vs-three-concepts rationale.++**Where to look, by concern (all one commit per phase):**++- **Concept core** (`0b6d201bb`): `pipelex/core/stuffs/date_content.py` (the class + a `field_validator` that closes pydantic's lax temporal coercions — see the guard note below), `NativeConceptCode.DATE` wired into the four exhaustive enum matches + factory + registry, Number/YesNo-style accessors (`Stuff.is_date`/`as_date`, `WorkingMemory`/`PipeOutput.main_stuff_as_date`), a `datetime.time` arm in `html_rendering.py`. Tests pin the render matrix, the kajson + transport-hydration round-trips (offset preserved — the distributed-decode safety net), and `refines = "Date"`.+- **Inputs** (`3ca1068f9`): the inputs-file loader converts a **top-level** TOML date/datetime literal to a `DateContent` (it then rides the existing case-1.3 seam as a bare content instance — no mthds-python protocol change); a bare *time-of-day* anywhere is rejected (`InputsTimeOnlyNotSupportedError`, renamed from the wholesale `InputsDatetimeNotSupportedError`); nested date/datetime are left for the factory/pydantic. `StuffContentFactory` / `StuffFactory` gain Date arms (envelope + bare object + strict-ISO string, parsed **date-first** so a date-only string never fabricates a time). `DateContent.rendered_pretty` is overridden (the base crashed on real date objects). e2e bundle under `tests/e2e/pipelex/pipes/date/`.+- **LLM output** (`b735ebce8`): a test pins that `output = "Date"` takes the object path with `DateContent`'s schema (both field descriptions) — no new generation machinery (DT7 defers ergonomics to the shared YesNo/Date follow-up).+- **DT8 — the severable field-type fix** (`6dd17e452`): structure-field `type = "date"` used to generate `datetime.datetime` (forcing a fabricated time on every extracted date); now `date` → `datetime.date` and a new `type = "datetime"` → `datetime.datetime`. Mirrored across the blueprint layer (`concept_structure_blueprint.py`, `generator.py`) **and** the spec/authoring layer (`concept_spec.py`); default-value validation splits (a `date` field rejects a datetime default). Docs + breaking changelog entry.+- **Docs/wrap** (`2d7b3d503`): `native-concepts.md`, `provide-inputs.md`, CHANGELOG, bookkeeping.++**The one guard worth understanding** (`date_content.py` `_reject_lax_temporal`): pydantic's lax mode would silently corrupt data against the concept's own fidelity contract — a bare `int`/`float` or an **all-digit string** read as epoch seconds, and a `datetime` on the `date` field silently truncated (dropping its time + offset). The validator rejects all three (raising `ValueError` so pydantic wraps it into a `ValidationError` the input path catches). The factory's ISO parser rejects all-digit strings too, for consistency.++**Deferred (nothing lost):** `wip/inputs/scalar-envelope-arm-asymmetry.md` and `wip/inputs/loader-vs-factory-date-split-duplication.md` (design tradeoffs to resolve when Smart Inputs unifies the input paths); the shared YesNo/Date LLM-output-ergonomics follow-up; and the per-release cross-repo sweep (schema copies, MTHDS spec tables, mthds-python/mthds-js mirrors, conformance, skills, cookbook `type = "date"` regen). See "Deferred to the release-wave sweep" at the bottom.++How the log below reads: each phase is checked off, and each CHECKPOINT's "state" line records what landed, the commit, decisions taken, and anything that fought back.++## 0. Cold-start context — read this first++**What ships:** one new native concept `Date` — "A calendar date, optionally with a time of day — as precise as its source states." Content = required `datetime.date` + optional `datetime.time` (UTC offset rides on the time's `tzinfo`). Rationale, rejected alternatives (one-vs-three), timezone policy, rendering, and non-goals are all in `datetime-design.md` — do not relitigate them here.++**Key mechanism facts** (verified 2026-07-07, line numbers approximate):++- **Adding a native concept** = enum value in `NativeConceptCode` (`pipelex/core/concepts/native/concept_native.py:20`) + arms in its exhaustive matches (`structure_class`, `is_composite`, `is_text_concept`, `is_dynamic_concept`) + a `case` in `ConceptFactory.make_native_concept` (`pipelex/core/concepts/concept_factory.py:98`) + content-class registration in `CoreRegistryModels.STUFF` (`pipelex/core/registry_models.py:92`). The library auto-loads natives from the enum (`concept_library.py:63`); reference validation and class-name lookups iterate the enum, so they pick the new value up automatically. Exhaustive `match/case` style means pyright walks you to every remaining site — no `case _` anywhere.+- **The content-class precedent** is `NumberContent` (`pipelex/core/stuffs/number_content.py`): one file per class in `pipelex/core/stuffs/`, overriding `short_desc`, `rendered_plain`, `rendered_html`, `rendered_markdown`, `rendered_json`. `structure_class_name` is auto-derived as `f"{enum_value}Content"` → the class MUST be named `DateContent`.+- **Bottom-up input dispatch** lives in `StuffFactory.make_stuff_from_stuff_content_or_data` (`pipelex/core/stuffs/stuff_factory.py:229`). Case 1.3 (bare `StuffContent` instance) infers the concept generically from the class name (`DateContent` → `native.Date`) — **works with zero code change** once the enum value exists. Case 2 (envelope): 2.1 str-content currently *requires* Text-compatibility (`stuff_factory.py:470`) — must learn the Date-compatible arm; content being a bare `datetime.date`/`datetime.datetime` object (TOML envelope) has no arm today and lands in the fallthrough.+- **`StuffContentFactory.make_content_from_value`** (`pipelex/core/stuffs/stuff_content_factory.py:12`) is where value→content conversion happens (special case: str + `TextContent`). Signature is typed `value: dict[str, Any] | str` — widens for temporal values.+- **Cross-repo gotcha:** `StuffContentOrData` / `PipelineInputs` live in the **mthds-python** package (`mthds/protocol/pipeline_inputs.py`, a pinned dependency — NOT in this repo). The union admits `str | Sequence[str] | StuffContentAbstract | Sequence[StuffContentAbstract] | dict[str, Any]` — bare `datetime` objects are NOT admitted. **Core-scope answer: don't touch the protocol.** The CLI loader converts TOML temporal literals into `DateContent` instances (admitted via case 1.3) before they hit the seam; datetime objects *nested inside* envelope/structured dicts pass fine (`dict[str, Any]`). Protocol widening to bare scalars rides Smart Inputs D10 with the rest of the downstream wave.+- **The error being retired:** `InputsDatetimeNotSupportedError` (`pipelex/cli/commands/run/exceptions.py:7`), raised by the recursive walk `_assert_no_datetime_values` (`pipelex/cli/commands/run/_inputs_file_loader.py:111`), caught at `_run_core.py:180` and `agent_cli/commands/run/stdin_resolver.py:200`. Tests: `tests/unit/pipelex/cli/commands/run/test_inputs_file_loader.py:99` (parametrized over the TOML temporal literal flavors) and `tests/unit/pipelex/cli/test_stdin_resolver.py:345`.+- **Already free, verify only:** LLM structured output ships `model_json_schema()` of the content class (`pipe_llm.py:249` dispatch, object path via `assignment_models.py:95`) — `output = "Date"` works day one, and DT2's field descriptions carry the anti-fabrication instruction into the schema. Dry-run mocks use polyfactory (`WorkingMemoryFactory.make_mock_content`, `working_memory_factory.py:174`), which synthesizes `date`/`time` natively. JSON cleaning already ISO-serializes all temporal types (`tools/misc/json_utils.py:58`). Structured-content HTML rendering ISO-renders `datetime`/`date` (`core/stuffs/html_rendering.py:53`) — check whether a `datetime.time` arm is missing.+- **Internal JSON serialization (kajson) — verified equipped, must be round-trip-tested.** Two different "JSON"s coexist and must not be confused. (a) The *inputs file* surface (`inputs.json`) is plain stdlib JSON — no kajson, no class metadata; bare ISO strings stay Text there until Smart Inputs (DT5's no-sniffing rule stands). (b) The *internal wire* is kajson (`../kajson` repo): `kajson/kajson.py` registers stock encoder/decoder pairs for the whole temporal family — `datetime.date`, `datetime.datetime`, `datetime.time`, fixed-offset `datetime.timezone`, `ZoneInfo`, `timedelta` — with offset-hardened wire handling for exactly DT2's subtle case (a bare `time` carrying a fixed-offset tzinfo; kajson's own comments note a ZoneInfo on a bare time destroys the offset, reinforcing DT3's offsets-only policy). So `DateContent` needs **no kajson changes** — but the round-trip must be pinned by tests because of the distributed stakes: per the Temporal work, a content class that fails payload *decode* inside a workflow does not fail loudly, it **hangs** (converter exceptions retry forever). The cross-process path: `WorkingMemory.dump_for_transport()` (`working_memory.py:551`) dumps in pydantic *python mode* — real `date`/`time` objects sit in the transport dict (its "JSON-safe" docstring is only true for kajson-or-pydantic-aware wires, not stdlib `json.dumps`) — then hydration goes `hydrate_working_memory` → `hydrate_content` → `model_validate` (`runtime_bridge/primitives/hydration.py:141`), which accepts both real temporal objects (kajson road) and ISO strings (pydantic json-mode road). Existing test module to extend: `tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py`.+- **DT8 sites** (severable field-type fix): `ConceptStructureBlueprintFieldType.DATE` (`concept_structure_blueprint.py:44`) maps to Python `datetime.datetime` in the structure generator (`structure_generation/generator.py:375` and `:569`); default-value validator checks `isinstance(..., datetime)` (`concept_structure_blueprint.py:180`); stale TODO at `:64`. Docs using `type = "date"`: `docs/building-methods/concepts/inline-structures.md`, `define_your_concepts.md` (+ cookbook pages, cross-repo).++**House rules that bite here:** TDD (tests first, red→green); keyword-only args (bare `*` after the subject — `make cko` gates); error classes only in `exceptions.py` modules; no `case _` in enum matches; `make agent-check` after code changes; `make agent-test` before wrapping a session; `make tb` for a quick boot check; `make gep` regenerates error pages; no hardcoded counts in docs/comments; changelog entries under `[Unreleased]`.++## Phase 1 — Concept core (DT1–DT4)++Tests first, then make them green:++- [x] **Tests** in `tests/unit/pipelex/core/stuffs/date_content/` (split per the neighbouring `yes_no_content/` layout — one TestClass per module: `test_date_content_renders.py`, `test_date_content_smart_dump.py`, `test_date_content_serialization.py`, shared `test_data.py`): construction (date-only; date + naive time; date + offset time); ISO-string parsing on the dict path; the render matrix — `rendered_plain`/`rendered_markdown`/`rendered_html` give truncated ISO 8601 (`2026-07-07`, `2026-07-07T15:40:00`, `2026-07-07T15:40:00+02:00`), `rendered_json` gives the two-field form; `short_desc` distinguishes "a date (...)" vs "a date and time (...)"; `to_datetime()` on the with-time case and the raise on the no-time case; `model_json_schema()` contains both field descriptions.+- [x] **Serialization round-trip tests**: `kajson.dumps` → `kajson.loads` in each precision state, typed equality + class-registry resolution by name (`test_date_content_serialization.py`). Cross-process transport road added to `test_hydration.py`: a `Date` stuff, one inside a `ListContent` (marker path), offset preserved end-to-end, plus the ISO-string road (json-serialized transport dict → hydrate).+- [x] **`DateContent`** in `pipelex/core/stuffs/date_content.py`: `date: datetime.date` (required), `time: datetime.time | None = None`, `Field(description=...)` on both (DT2 anti-fabrication), `rendered_*` + `short_desc` (DT4), `to_datetime()`. Added a `field_validator("date","time", mode="before")` that rejects `int`/`float` — empirically the `time` field lax-coerces a bare int to seconds-of-day, so the DT6 no-epoch-seconds guard belongs on the class (raises `TypeError`, pydantic wraps to `ValidationError`).+- [x] **Enum + matches:** `DATE = "Date"` + arms in `structure_class`, `is_composite`, `is_text_concept`, `is_dynamic_concept` (pyright walked to each).+- [x] **Factory arm** with the DT1 description.+- [x] **Registry:** `DateContent` in `CoreRegistryModels.STUFF`.+- [x] **`html_rendering.py`:** added an explicit `case time():` ISO arm (was landing in the `case _:` fallback).+- [x] Number-mirrored accessors: `Stuff.is_date`/`as_date`, `WorkingMemory.get_stuff_as_date`/`main_stuff_as_date`, `PipeOutput.main_stuff_as_date`.+- [x] `make tb`, `make agent-check` (all green), targeted pytest green.++### CHECKPOINT 1 — concept exists and boots++State: **reached 2026-07-07.** `DateContent` exists, boots, round-trips through kajson and the transport hydration path with the offset preserved. `make agent-check` green (pyright 0 / mypy Success / ruff / plxt / cko), `make tb` green, full `make agent-test` green. Micro-decision settled: `to_datetime()` with `time is None` **raises** `DateContentError` (new class in `stuffs/exceptions.py`) — no silent midnight. Extra vs the original checklist: the DT6 lax-coercion guard was pulled forward into the content class, and the Number/YesNo-style typed accessors were added for family consistency. A fanned-out code review surfaced (and this checkpoint fixed) the full set of pydantic lax-coercion leaks the guard must close — see the micro-decision below.++## Phase 2 — Inputs (DT5): TOML literals in, rejection narrowed++- [x] **Tests first.** Reworked `test_inputs_file_loader.py`: rejection narrowed to bare time-of-day (top-level and nested); new cases assert top-level local date → date-only `DateContent`, local datetime → naive `DateContent`, offset datetime → offset preserved, and that a nested date/datetime is left in place. Factory unit tests in `test_stuff_content_factory.py` (date obj, datetime obj split, ISO date-only never fabricates a time, ISO datetime with offset, refining subclass, non-ISO rejected) and `data.py`/`test_stuff_factory_implicit_memory.py` envelope cases (2.15–2.20 + case 1.3, refining `DueDate`, error cases naming `native.Date` / `ISO 8601`). Updated `test_stdin_resolver.py`.+- [x] **`StuffContentFactory.make_content_from_value`:** widened `value` typing (`… | datetime.date`) and added a `DateContent` arm + `_make_date_content` / `_parse_iso_temporal` helpers — date obj; datetime obj split via `.date()`+`.timetz()` (offset kept); ISO `str` parsed **date-first** so a bare date never fabricates a midnight; dict rides `model_validate`.+- [x] **`StuffFactory` case 2 (envelope):** case 2.1e — a bare `datetime.date`/`datetime.datetime` routes through the resolved concept's content class (Date-compatible only, else a typed error naming `native.Date`); case 2.1f — a str under a Date-compatible (non-Text) concept builds `DateContent` from the ISO string; the str-arm error message now names both `native.Text` and `native.Date`. Case-list docstring updated.+- [x] **Loader** (`_inputs_file_loader.py`): replaced `_assert_no_datetime_values` with `_convert_temporal_inputs` — top-level date/datetime → `DateContent` (enters the seam as case 1.3), `_reject_time_of_day` rejects a bare time anywhere, nested date/datetime left in place. Docstrings updated.+- [x] **Error class:** renamed `InputsDatetimeNotSupportedError` → `InputsTimeOnlyNotSupportedError` (message: a time of day alone has no date to attach to — include the date or quote as a string). Updated docstring, `user_action`, both catch sites (`_run_core.py`, `stdin_resolver.py` incl. its `error_type` string), regenerated error pages (`make gep`).+- [x] **e2e:** new `tests/e2e/pipelex/pipes/date/date_departure/` bundle (Date input pipe + Date output pipe), `test_date_inputs_run.py` (`gha_disabled` subprocess feeding a TOML offset-datetime literal, offset preserved through the loader), `test_date_dry_run.py` (Date output mocked by polyfactory; Date input flows through).+- [x] **Dry-run mock check:** polyfactory synthesizes `DateContent` with no generator quirks — no fixes needed.+- [x] `make agent-check` (all green); targeted sweep 2058 passed.++### CHECKPOINT 2 — TOML temporal literals run end-to-end++State: **reached 2026-07-07.** Error class settled: `InputsTimeOnlyNotSupportedError`. No protocol-typing friction at the seam — the loader converting top-level literals to `DateContent` means they ride case 1.3 (a `StuffContentAbstract`, already admitted by `StuffContentOrData`), so **no mthds-python change was needed** (as §0 predicted). Notable finds fixed this checkpoint: (1) a `datetime.datetime.fromisoformat` on a date-only string fabricates a midnight, so the ISO parser must try `date.fromisoformat` first; (2) `pretty_print` of a `DateContent` crashed — the base `rendered_pretty` feeds `smart_dump()`'s real date objects to stdlib json — fixed by overriding `rendered_pretty` to render the ISO form (any displayed Date output would otherwise crash). `make gep` also surfaced a pre-existing, unrelated doc gap (the v0.38.0 storage/secrets provider error pages were never committed) — left out of scope; only the Date/time-only error pages are staged here. Fanned-out review round: fixed one real bug — the ISO parser's `date.fromisoformat` accepts the basic `YYYYMMDD` form, which let an all-digit epoch-looking string slip past `DateContent`'s no-epoch-seconds guard (now rejected in `_parse_iso_temporal` too, with a test). One duplication finding (the date/datetime split written in both the loader and the factory) deferred as a design tradeoff — see `wip/inputs/loader-vs-factory-date-split-duplication.md`.++## Phase 3 — LLM output verification (DT7)++- [ ] Locate how `output = "Number"` is covered in PipeLLM tests and mirror for `Date`: assert the object path is selected (not the Text path) and the schema handed to content generation is `DateContent`'s with both field descriptions.+- [ ] Optional, non-gating: one live-gateway smoke of an extraction that should produce date-only vs date+time (manual; not CI).++No new generation machinery: the leaner scalar-native generation form is explicitly deferred to the YesNo LLM-output-ergonomics follow-up (design DT7).++## Phase 4 — DT8: fix the `date` structure-field misnomer (severable — may be dropped without touching Phases 1–3)++- [x] **Tests first:** generator tests assert `type = "date"` emits `datetime.date` (schema `format: date`) and `type = "datetime"` emits `datetime.datetime` (`format: date-time`); blueprint tests assert default-value validation (date accepts a date and rejects a datetime; datetime requires one). Updated the pre-existing normalization test (`birthdate` now `date`).+- [x] `ConceptStructureBlueprintFieldType`: added `DATETIME = "datetime"`; pyright walked the exhaustive matches (blueprint validation arm, `_validate_default_value_type`, both generator mapping sites, the list-item recursive group).+- [x] `DATE` arms flip to `datetime.date` (generator import + `exec_globals` gain `date`; default-value check now `isinstance(date) and not isinstance(datetime)`); stale line-64 TODO removed (default-value type is validated).+- [x] Docs: `inline-structures.md` — split the `date` section into `date` (calendar date, `format: date`) and `datetime` (timestamp, `format: date-time`), added the field-type-vs-`Date`-concept note, fixed the generated-code example. `define_your_concepts.md`'s `issue_date` example is already a calendar date (correct post-DT8), detail lives on the linked page.+- [x] Regenerated the MTHDS schema (via `make agent-check`) — the `datetime` field-type enum lands in the gitignored `derived/mthds_schema.json`; downstream copies sync in the release wave.+- [x] Changelog: breaking `### Changed` entry — `date` fields no longer carry a time, `datetime` field type added. No in-repo `.mthds` uses `type = "date"`; cookbook improvements are noted for the cross-repo sweep (not edited here).++### CHECKPOINT 3 — DT8 landed or consciously dropped++State: **LANDED 2026-07-07.** DT8 shipped (not dropped). `type = "date"` → `datetime.date` (`format: date`), new `type = "datetime"` → `datetime.datetime` (`format: date-time`), default-value validation split accordingly, docs + breaking changelog entry in place. `make agent-check` green. Design decision honored: the DATE default-value check rejects a datetime (`isinstance(date) and not isinstance(datetime)`) — a datetime default would carry a time the `date` field silently drops, the exact fabrication DT8 exists to prevent. Stale line-64 TODO (`# TODO: date translator for default_value`) removed — defaults are validated as real date/datetime objects, no translator. Fanned-out review round: the flip left the **spec layer** (`pipelex/builder/concept/concept_spec.py`, the AI-authoring convenience format that mirrors blueprints via `to_blueprint()`) out of step — a reachable break where a spec `type = "date"` with a calendar-date default would fail. Mirrored the same change there (added spec `DATETIME`, flipped the DATE default-value check, walked pyright to every spec match site) with tests, since leaving the authoring path broken is not a complete DT8. Note for the release-wave sweep: cookbook `type = "date"` extractions (invoice/DPE) improve for free but must be re-generated; the downstream schema copies (mthds/vscode-pipelex/mthds-ui) pick up the new field-type enum.++## Phase 5 — Docs, changelog, wrap++- [x] `docs/building-methods/concepts/native-concepts.md`: `Date` table row + a `DateContent` section (date + optional time, fidelity note, `output = "Date"` example, `main_stuff_as_date` reader), mirroring Number/YesNo.+- [x] Inputs docs: `provide-inputs.md` warning box flipped to a tip — TOML date/datetime literals are native `Date` inputs, bare time-of-day is the remaining unsupported case (kept surgical; full rewrite rides Smart Inputs).+- [x] `CHANGELOG.md` under `[Unreleased]`: added native `Date` concept (pitch + TOML literal support + reserved-code breaking note); breaking `### Changed` for the narrowed inputs rejection (`InputsTimeOnlyNotSupportedError`); DT8 breaking entry already landed in Phase 4.+- [x] Track bookkeeping: `wip/inputs/README.md` (Datetime step → done, next = Smart Inputs) and this plan's checkpoint states updated.+- [x] Full gates: `make agent-check` + `make agent-test`.++### CHECKPOINT 4 — track complete, hand off to the next train car++State: **track complete 2026-07-07.** The native `Date` concept ships end to end on `feature/Smart-inputs` (Phases 1–4, commits `0b6d201bb` → `6dd17e452`, plus this Phase 5 docs/wrap commit). All gates green. Deferred (in `wip/inputs/`): the scalar-envelope arm asymmetry and the loader-vs-factory date-split duplication (both design tradeoffs to resolve when Smart Inputs unifies the input paths); the shared YesNo/Date LLM-output-ergonomics follow-up; and the release-wave cross-repo sweep (schema copies, MTHDS spec tables, mthds-python/mthds-js mirrors, conformance, skills, cookbook `type = "date"` regen). Next train car: the Smart Inputs step (`smart-inputs-design.md`).++### PR round — #1029 (stacked on YesNo #1028), bot-review pass++The Date work went out as its own PR **#1029**, based on `feature/Smart-inputs` so the diff is Date-only (retargets to `dev` once YesNo #1028 merges). CI green across py3.11–3.14 + both bot *checks* pass. Greptile + cubic + Codex posted inline findings; a fanned-out arbitration pass verified each against the code and fixed the genuine wins, dismissed one impossible-scenario claim, and deferred one out-of-scope gap:++- **Two real generator bugs, both DT8-adjacent, fixed:** (1) `build inputs` emitted an unparseable placeholder (`"date_date"`) for a `Date` input because `ConceptRepresentationGenerator._generate_basic_value` had no temporal branch — the `build inputs` → `run` round-trip was broken; added `datetime.date`/`datetime`/`time` → ISO-example branches. (2) `StructureGenerator._format_default_value` rendered a temporal default via `repr()` → module-qualified `datetime.datetime(...)`, but generated code imports the *bare* classes (`from datetime import date, datetime`), so eval raised `AttributeError`; now emits `datetime.fromisoformat(...)`/`date.fromisoformat(...)` (offset-preserving, uses the imported bare names; `exec_globals` already carries both). The `date`-with-default case was pre-existing and is fixed too. Both pinned by round-trip tests.+- **Three low-risk tightenings:** the ISO-datetime factory test now also asserts the *date* component; `native-concepts.md` says "top-level" TOML literal (matching `provide-inputs.md`); the `InputsTimeOnlyNotSupportedError` hint unquotes its datetime example (a quoted value is a TOML string → Text, the opposite of "include the date") — error page regenerated via `make gep`.+- **One dismissed, one deferred:** a claimed missing bare-`datetime.date` arm in `StuffFactory` Case 1 is unreachable (the loader pre-converts top-level scalars to `DateContent`; the `StuffContentOrData` protocol union admits no bare datetimes) — no dead branch added. The one real gap it surfaced — a top-level TOML *array* of date literals errors cleanly instead of building `ListContent[DateContent]` — is unsupported-by-design list surface, deferred to Smart Inputs; captured in `wip/inputs/case1-bare-date-arm-gap.md`. No changelog entry: A/B are fixes inside the still-`[Unreleased]` Date feature, never shipped.++### gstack `/review` finalize round — 2026-07-07++The plan's finalize step ran: gstack `/review` (Opus 4.8) with a testing + maintainability + adversarial-red-team fan-out, each given pointer-only context (branch + base, computes its own diff — no plan/rationale, so the eyes stay independent). Scope check CLEAN; CI verified fully green; my own critical pass (SQL/race/shell/LLM-trust/enum-completeness) clean — enum consumers are all specific-value lookups or generic enum iterations that pick up `DATE` automatically, and the DT8 `exec()` codegen path is injection-safe (validated temporal objects → `.isoformat()` can't inject). One real defect + low-risk polish applied, two design tradeoffs deferred:++- **Real defect fixed — a stale, self-contradicting test.** `tests/unit/pipelex/cli/test_run_core_execution.py::test_toml_datetime_input_file_exits` asserted the *old* rejection behavior (a top-level TOML datetime → exit 1) that Phase 2 reversed (it's now converted to a `DateContent`). Untouched by the diff, it mocked no runner and passed only because execution failed 1 for an unrelated downstream reason — false coverage, and a docstring documenting the opposite of shipped behavior. Phase 2 had updated `test_inputs_file_loader.py` + `test_stdin_resolver.py` but this CLI-level test slipped. Repurposed to a bare time-of-day (`deadline = 12:00:00`) — the one temporal literal the loader still rejects — so it now exercises the real `InputsTimeOnlyNotSupportedError` catch site, and asserts the `"Failed to load input file"` framing to pin that the exit comes from that path (not a downstream failure). Renamed → `test_toml_time_only_input_file_exits`.+- **Polish.** Dropped a misleading parenthetical in `concept_representation_generator.py` (the temporal example arms are `is`-identity checks, not `isinstance`, so the "checked before date: datetime is a date subclass" ordering rationale was wrong/misleading). Added the two untested `_reject_lax_temporal` arms on the `time` field (datetime-on-time, all-digit-string-on-time — only the int arm was pinned). Added generator tests for `type = "list", item_type = "date"`/`"datetime"` (the DT8 list-item mapping was untested).+- **Deferred (design tradeoffs, per the "defer on doubt" rule):** `container-default-temporal-codegen-gap.md` (the DT8 scalar `fromisoformat` fix doesn't recurse into list/dict defaults — narrow, pre-existing, errors not silent) and `structure-field-fidelity-guard.md` (generated `date`/`datetime` structure fields don't carry the native `DateContent` anti-fabrication guard — likely an intentional non-goal, but the decision is now recorded). The red-team's third finding (top-level date-list gap) was already the existing `case1-bare-date-arm-gap.md` deferral — confirming that call. No changelog entry: all fixes are inside the still-`[Unreleased]` Date feature.++## Deferred to the release-wave sweep (NOT this plan's scope — listed so nothing is lost)++Shared per-release wave with YesNo + Smart Inputs (see `README.md`): MTHDS spec native-concepts tables (`mthds/docs/language/concepts.md`, `mthds/docs/spec/mthds-format.md`); schema-copy sync via the `mthds-schema-sync` skill; `mthds-python` protocol widening for bare temporal scalars (rides Smart Inputs D10) + any native-list mirrors; `mthds-js` mirrors; conformance rows; `mthds-plugins` skills (`mthds-inputs`, `mthds-build`); editor tooling completion lists (vscode-pipelex). Plus the YesNo/Date shared follow-up: LLM-output ergonomics for scalar natives.++`pipelex-temporal` (private plugin repo): **no code change expected** — its codec serializes the `dump_for_transport` dict via kajson and binds classes through the registry, so `DateContent` flows in with the pipelex version-pin bump. At pin-bump time, add a `Date` case to its converter round-trip tests anyway: the failure mode over there is a hang, not an error, so coverage is cheap insurance.++## Micro-decisions log++- `to_datetime()` with `time is None`: **settled RAISE** (`DateContentError`, in `pipelex/core/stuffs/exceptions.py`) — a silent midnight is exactly the fabrication DT2 forbids.+- Final narrowed-error class name: **settled `InputsTimeOnlyNotSupportedError`** (Phase 2).+- ISO string parsing order: **settled date-first** — `datetime.fromisoformat` accepts a date-only string and fabricates a midnight, so `date.fromisoformat` is tried first; a bare time string fails both and correctly errors.+- `DateContent.rendered_pretty`: **settled override** — the base feeds `smart_dump()`'s real date/time objects to Rich's stdlib-json encoder and crashes; DateContent renders the ISO two-field JSON instead.+- DT6 lax-coercion guard placement: **settled ON THE CONTENT CLASS** (Phase 1, not Phase 2) — the guard is a class invariant, not just an input-boundary concern, because the dict-content envelope path reaches `model_validate` directly. One `field_validator("date","time", mode="before")` closes every verified pydantic lax leak: bare `int`/`float` (pydantic natively rejects on `date`, but lax-coerces `int`→`time` as seconds-of-day), an **all-digit string** (read as epoch — a real ISO date/time always carries `-`/`:`, so an all-digit string is only ever an epoch), and a **`datetime` on the `date` field** (silently truncated to the date, dropping its time + UTC offset — the exact fidelity loss DT3 forbids). Raises `ValueError` (not `TypeError`) so pydantic wraps it into a `ValidationError` the input path catches — a raw `TypeError` escapes `model_validate` uncaught.+- Note for Phase 4 (DT8): the older custom `type = "date"` structure-field path (`structure_generation/generator.py`) has the same unguarded epoch-int coercion — same bug class, addressed when DT8 flips that field type.diff --git a/wip/inputs/input-shaper-multiplicity-gaps.md b/wip/inputs/input-shaper-multiplicity-gaps.mdnew file mode 100644index 000000000..dff931cc1--- /dev/null+++ b/wip/inputs/input-shaper-multiplicity-gaps.md@@ -0,0 +1,54 @@+# Deferred: `InputShaper` multiplicity gaps in the explicit and Dynamic arms++**Status:** deferred design note — no code change. Surfaced during the PR #1028 adversarial review (cubic), 2026-07-07. The `InputShaper` is **Phase-1 dormant** — landed with its full unit-test suite but not yet wired into any run (commit `d72101174`, "not yet wired"); wiring is the D7/Phase-2 job of the upcoming `smart-inputs-implementation-plan`. Both gaps below are therefore latent (no runtime impact today) and belong to that phase, which reworks exactly this multiplicity handling.++## Gap A — `_shape_explicit` bypasses declared multiplicity (D2)++`InputShaper._shape_explicit` (`pipelex/core/memory/input_shaper.py`) builds the explicit form bottom-up and does exactly one check — concept compatibility (`get_concept_library().is_compatible(...)`). It never consults `stuff_spec.multiplicity`. Because `_is_explicit` treats any `StuffContent` — and `ListContent` **is** a `StuffContent` — as explicit, three shape mismatches slip through unchecked, contradicting the D2 invariants the *non-explicit* path enforces in `_shape_with_multiplicity`:++- **singular declared + explicit `ListContent`** (or an envelope whose `content` is a list) → a list is stored into a singular slot, though D2 makes "list where singular is declared" a hard error;+- **`[N]` declared + explicit `ListContent` of the wrong length** → the count is never validated;+- **`[]` declared + explicit singular object** → stored as singular, where the non-explicit arm would auto-wrap.++D6 (`smart-inputs-design.md`) governs only *concept* compatibility ("explicit wins when compatible"); it says nothing about multiplicity, and D2 states the list-vs-singular hard error unconditionally. So this is a genuine gap, not a D6 carve-out. **No test asserts either behavior** — `test_explicit_forms.py`'s "multiple" cases pass a bare Python `list` (which is *not* explicit and takes the `_shape_list` path), so the explicit-arm × multiplicity interaction is untested.++**Proposed fix (from the review):** after the compat check in `_shape_explicit`, reconcile the built content's shape against `stuff_spec.multiplicity` using the same rules `_shape_with_multiplicity` applies — reject a `ListContent` against a singular spec (`ListWhereSingularError`), enforce the `[N]` count on a `ListContent` (`MultiplicityCountMismatchError`), reusing the existing error factories so the rendered-shape hint stays consistent.++**Open design question:** the single-vs-`[]` auto-wrap policy for explicit forms — should an explicit singular object under a declared-multiple `[]` input auto-wrap into a one-item `ListContent` (as the bare-value arm does), or is an explicit form taken literally? Decide this when wiring, not by bolting a rule onto the current arm.++## Gap B — the `DYNAMIC` arm skips multiplicity peeling++In `_shape_one`, the `InputKind.DYNAMIC` case returns `StuffFactory.make_stuff_from_stuff_content_or_data(value)` and short-circuits **before** `_shape_with_multiplicity`. `resolve_input_kind` maps `Dynamic`/`Anything`, the out-of-matrix natives, and unregistered structures to `DYNAMIC` keyed on the *concept* only; `stuff_spec.multiplicity` is never consulted for them. So for a declared `native.Dynamic[]` / `native.Anything[N]`:++- **empty list** → the bottom-up factory raises "Cannot create Stuff from empty list" instead of D2's legal empty `ListContent` — a concrete divergence from the Smart Inputs contract;+- **fixed `[N]`** → no count check;+- **single → list auto-wrap** → not applied.++This is **partly by design**: D5 says Dynamic/Anything "fall back to today's bottom-up rules (the signature genuinely doesn't know)," and the code comment frames handing the whole raw value (including its own list handling) to the factory as deliberate for *item building*. But D2 frames multiplicity as a *prior* peeling step orthogonal to concept nature ("after D2's multiplicity peeling, dispatch on the declared concept's nature"). Under that reading the DYNAMIC arm should still peel multiplicity (honor `[]`, `[N]`, auto-wrap) and defer only *per-item building* to bottom-up. Practical severity is low — declaring Dynamic/Anything *with* an explicit multiplicity is an unusual signature — but the empty-list case is an observable contradiction with D2.++**Proposed resolution:** either (1) move the multiplicity peel ahead of the kind dispatch so the DYNAMIC arm routes lists through `_shape_list` with per-item bottom-up building (empty→empty `ListContent`, `[N]` count-checked, single auto-wrapped), deferring only per-item concept inference to `StuffFactory`; or (2) if the full fallback is intended, add a one-line design note + a pinning test so "Dynamic ignores declared multiplicity" is a documented decision rather than an accident.++## Follow-up++Resolve both when the `smart-inputs-implementation-plan` wires `InputShaper` (D7) — that phase must decide the D2 multiplicity semantics holistically, and these two arms are exactly where it lands. Add pinning tests for whichever contract is chosen (today `Dynamic[]` + `[]` reproduces the bottom-up "Cannot create Stuff from empty list" error, demonstrating Gap B). Related notes: `scalar-envelope-arm-asymmetry.md`, `case1-bare-date-arm-gap.md`.++No action needed on the PR #1028 merge — the shaper is dormant.++## Phase-5 triage (Smart Inputs, 2026-07-08) — Gap A unambiguous half CLOSED; auto-wrap + Gap B RE-DEFERRED++The Phase-5 finalize doc-accuracy review independently re-found **Gap A** and framed it as a silent behavior: a caller handing an explicit `ListContent` (or an envelope whose `content` is a list) to a singular-declared input had it *silently stored* into the singular slot, contradicting D2's unconditional list-where-singular error. That is exactly the reopen trigger this note recorded, so the **unambiguous half of Gap A is now fixed**:++- `InputShaper._shape_explicit` now calls `_reconcile_explicit_multiplicity` after the D6 compat check: an explicit form whose built content is a `ListContent` raises `ListWhereSingularError` against a singular slot, and `MultiplicityCountMismatchError` against a declared `[N]` of the wrong length — reusing the existing error factories, so the rendered-shape hints stay consistent. The multiplicity peel is shared with the bare-value path via a new `_peel_multiplicity` helper (no duplicated classification). Pinned by `test_explicit_forms.py` (`test_explicit_list_into_singular_raises`, `test_explicit_list_wrong_fixed_count_raises`, `test_explicit_list_into_list_slot_ok`).++**Still deferred (the genuine tradeoffs, not the bug):**++- **Gap A's auto-wrap sub-question.** An *explicit singular* under a declared `[]`/`[N]` is still taken literally (stored as given), not auto-wrapped into a one-item list the way the bare-value path does. Whether an explicit form should auto-wrap or be literal is the open design question the note flags — left to the holistic D2-multiplicity pass. `_reconcile_explicit_multiplicity` only fires on `ListContent` content, so this direction is untouched.+- **Gap B — the `DYNAMIC` arm skips multiplicity peeling.** `_shape_one`'s `InputKind.DYNAMIC` case still short-circuits to the bottom-up factory before `_shape_with_multiplicity`, so a declared `Dynamic[]`/`Anything[N]` doesn't peel multiplicity (empty-list diverges from D2's empty `ListContent`, no `[N]` check, no auto-wrap). D5 explicitly says Dynamic/Anything "fall back to today's bottom-up rules," and declaring Dynamic *with* a multiplicity is unusual; the empty-list case raises a clean error, not silent corruption. Re-deferred as a documented decision to the holistic D2-multiplicity pass (which must also settle the auto-wrap question above).++## PR #1033 follow-up (2026-07-08) — Dynamic explicit-list regression CLOSED; broader Gap B still deferred++The Phase-5 reconcile introduced a narrower regression: a singular `native.Dynamic` input still accepted a raw Python list through the bottom-up `InputKind.DYNAMIC` path, but rejected an already-built `ListContent` because `_shape_explicit` ran the new list-into-singular guard after the D6 compat check. That over-applied D2 to a slot where D5 says the signature cannot guide shape.++`InputShaper._shape_explicit` now returns immediately after compatibility when the declared concept is exactly `native.Dynamic`, matching the bare-value Dynamic fallback. Pinned by `test_explicit_list_content_into_dynamic_slot_ok`.++This does **not** resolve the broader Gap B above: declared `Dynamic[]`/`Anything[N]` still do not peel multiplicity, and the empty-list/count/auto-wrap semantics remain deferred to the holistic D2 pass.diff --git a/wip/inputs/loader-vs-factory-date-split-duplication.md b/wip/inputs/loader-vs-factory-date-split-duplication.mdnew file mode 100644index 000000000..54167984d--- /dev/null+++ b/wip/inputs/loader-vs-factory-date-split-duplication.md@@ -0,0 +1,45 @@+# Deferred: the date/datetime→DateContent split is written twice (loader + factory)++**Status:** deferred design note — no code change. Surfaced during the Phase 2 (Date inputs) code review, 2026-07-07.++## What++Two places turn a Python `datetime.date`/`datetime.datetime` object into a `DateContent`, with the same two-line split:++- `pipelex/cli/commands/run/_inputs_file_loader.py` → `_convert_temporal_inputs` (top-level TOML literals):++ ```python+ if isinstance(value, datetime.datetime):+ converted[key] = DateContent(date=value.date(), time=value.timetz())+ elif isinstance(value, datetime.date):+ converted[key] = DateContent(date=value)+ ```++- `pipelex/core/stuffs/stuff_content_factory.py` → `_make_date_content` (envelope / concept-resolved values):++ ```python+ if isinstance(value, datetime.datetime):+ return date_subclass(date=value.date(), time=value.timetz())+ if isinstance(value, datetime.date):+ return date_subclass(date=value)+ ```++The reviewer's suggestion was to have the loader call `StuffContentFactory.make_content_from_value(stuff_content_subclass=DateContent, value=value)` and delete its inline split.++## Why it is deferred (not applied)++It is a genuine design tradeoff, not a clear win:++- **Different layers, different responsibilities.** The loader is a *format-level* step (CLI, `pipelex/cli/…`) that maps a bare top-level TOML literal to the base `native.Date` content — it knows nothing about concepts. `_make_date_content` is a *concept-level* step that builds the concept's (possibly refining) `structure_class`. They happen to share a two-line split; they are not the same operation.+- **The reuse introduces a cross-layer dependency.** The loader currently imports only `DateContent`. Routing through `StuffContentFactory` couples the CLI loader to the core factory (and its `hub`/registry import surface) to save two lines of stable, trivial logic.+- **Low drift risk.** The split (`date=v.date(), time=v.timetz()` for a datetime; `date=v` for a date) is fixed by `datetime`'s own API; it is not the kind of logic that evolves.++## Follow-up to consider (Smart Inputs)++When Smart Inputs (D5/D10) unifies the bottom-up input paths into a shared `input_shaper`, the loader's top-level conversion and the factory's per-concept shaping likely collapse into one interpretation matrix. Resolve the duplication there — by unifying the layer, not by bolting a cross-layer call onto the current two hand-written arms.++No action needed inside the Date track.++## Phase-5 triage (Smart Inputs, 2026-07-08) — RE-DEFERRED++Smart Inputs landed the shaper, but it did **not** collapse this split — and the reason is instructive, not an oversight. The loader (`_convert_temporal_inputs`) runs **before** the pipeline-inputs seam, at the CLI-format layer: it turns a top-level TOML date/datetime *literal* into a `DateContent` while the file is being parsed, with no view of the pipe or its concepts. The shaper runs **at** the seam, top-down against the declared concept. They are genuinely different steps at different layers — the loader's early conversion is what lets a bare TOML date reach the seam as a `StuffContent` (so it takes the shaper's already-built-`StuffContent` path rather than a bare-date arm). Collapsing them would mean either moving concept-aware shaping up into the format loader (wrong layer — the loader has no signature) or deferring the loader's literal conversion down into the shaper (which would still leave the no-signature bottom-up path needing its own conversion). The two-line `date=v.date(), time=v.timetz()` split is fixed by `datetime`'s own API (near-zero drift risk), so the original deferral rationale — different responsibilities, cross-layer-coupling cost, low drift — stands unchanged. Re-deferred to a dedicated `tools`/loader pass if the loader is ever restructured; not worth cross-layer coupling now.diff --git a/wip/inputs/refines-hint-native-list-drift.md b/wip/inputs/refines-hint-native-list-drift.mdnew file mode 100644index 000000000..824b69b9b--- /dev/null+++ b/wip/inputs/refines-hint-native-list-drift.md@@ -0,0 +1,24 @@+# Deferred: `refines` authoring-hint native-concept list drifts from `NativeConceptCode`++**Status:** deferred follow-up — no code change in the YesNo track. Surfaced during the final gstack `/review` of PR #1028 (native `YesNo`), 2026-07-07.++## What++`pipelex/builder/concept/concept_spec.py` — the `ConceptSpec.refines` field hardcodes a list of native concepts in two places:++- the field `description` (~line 250): `"(Text, Html, Image, Document, Number, Page, TextAndImages, JSON, Anything, Dynamic)"`+- the field `examples` (~line 253): `["Text", "Html", "Image", "Document", "Number", "Page", "TextAndImages", "JSON"]`++Both lists are **already non-exhaustive** against `NativeConceptCode`: they omit `SearchResult` and `Composite` today, and now also omit the new `YesNo`.++## Why it does not block the YesNo PR++This is the builder **spec** layer — a convenience authoring format surfaced to LLM agents, explicitly *not* the MTHDS language (see `pipelex/builder/CLAUDE.md`). The list is an LLM-facing authoring hint only. Runtime is unaffected: `refines = "YesNo"` validates and resolves `YesNoContent` (proven by `tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.py`). Because pyright can't see string literals, the exhaustive-`match/case` discipline that guarantees every other new-native-code site was updated does not reach this hardcoded string.++## Why defer rather than spot-patch++Appending just `"YesNo"` would be a partial fix that leaves `SearchResult` and `Composite` still missing — it papers over a systemic drift rather than resolving it, and picking which subset to add is a judgment call, not a clear-cut fix. This is the same class of authoring-guidance surface (skills, editor completion lists) the YesNo plan already defers to the shared release-wave sweep.++## The real fix (release-wave / Smart Inputs authoring-guidance sweep)++Either complete the list (`YesNo`, `SearchResult`, `Composite`) **or** — better — derive it from `NativeConceptCode` at model-definition time so it can never drift again. Do this once, in the release-wave sweep, alongside the other authoring-guidance surfaces (`mthds-plugins` skills, `vscode-pipelex` completion lists), not as a per-native-concept patch.diff --git a/wip/inputs/scalar-envelope-arm-asymmetry.md b/wip/inputs/scalar-envelope-arm-asymmetry.mdnew file mode 100644index 000000000..d06094f87--- /dev/null+++ b/wip/inputs/scalar-envelope-arm-asymmetry.md@@ -0,0 +1,37 @@+# Deferred: scalar-envelope arm asymmetry (bool preserves subclass, str flattens to Text)++**Status:** deferred design note — no code change. Surfaced during the Phase 2 (YesNo envelope inputs) code review, 2026-07-07.++## What++`StuffFactory.make_stuff_from_stuff_content_or_data` handles the envelope form `{"concept": ..., "content": <scalar>}` with two adjacent scalar arms that treat a *refining* concept differently:++- **Case 2.1d (bool → YesNo)** routes through `StuffContentFactory.make_stuff_content_from_concept_required`, which resolves the concept's `structure_class_name`. For a concept refining `YesNo` (e.g. a generated `urgency__IsUrgent` subclass of `YesNoContent`), this **preserves the refining subclass** — the produced content is an instance of that subclass, not the base `YesNoContent`.+- **Case 2.1 (str → Text)** constructs a base `TextContent` directly, **flattening to base** regardless of the concept's own `structure_class_name`.++So the same "scalar under a refining concept" pattern yields a subclass for bool and a base class for str.++## Why it is deliberate (not a bug)++The asymmetry is intentional and tested (see Checkpoint 2 note in `yesno-implementation-plan.md`):++- `YesNo` refinements **do** generate a registered `StuffContent` subclass, and `subclass.model_validate(True)` fails while `subclass(yes_no=value)` works — so routing bool via the concept resolver is the only construction path that honors the refinement.+- `Text`'s historical behavior flattens string content to base `TextContent`; changing that is out of scope for the YesNo track and would be a behavior change to an unrelated, long-standing path.+- The no-coercion pin holds either way: a `"yes"`/`"no"` string under a YesNo concept still takes the str arm and errors as not-Text-compatible.++## Follow-up to consider (Smart Inputs generalization)++When Smart Inputs (D5/D10) generalizes these scalar-envelope arms into the shared `input_shaper.py`, revisit whether the str arm should also preserve a refining concept's `structure_class_name` instead of flattening to base `TextContent`. If the two scalar arms are unified under one interpretation matrix, this asymmetry should be resolved by design rather than left as two hand-written arms with divergent behavior.++No action needed inside the YesNo track.++## Phase-5 triage (Smart Inputs, 2026-07-08) — RE-DEFERRED, narrowed++The shaper landed, and it **half-closes** this: the **bare** path — now the blessed default (a plain `"my question"` under a `legal.Question` input) — builds the refining subclass, because `InputShaper._build_item_content`'s TEXT arm wraps the value into the structure class's canonical dict and routes through `StuffContentFactory.make_stuff_content_from_concept_required`, which honors `Question`. So the everyday case is correct.++The asymmetry now survives **only on the envelope escape hatch**: `{"concept": "legal.Question", "content": "text"}` still routes through `InputShaper._shape_explicit` → `StuffFactory.make_stuff_from_stuff_content_or_data` Case 2.1, which builds a base `TextContent` (concept kept, content not the subclass). Re-deferred rather than fixed because:++- **Blast radius.** Closing it means changing `StuffFactory` Case 2.1's str→Text arm (a long-standing bottom-up path used well outside the shaper) or bolting a shaper-local post-build rewrite onto `_shape_explicit` — neither is the clean "unify under one matrix" the note imagined; both are surgery on the escape hatch for a case the blessed path already gets right.+- **Near-zero practical impact.** A pure Text *refinement* adds no fields over `TextContent` (both carry `text`), so a base `TextContent` with concept `legal.Question` renders and validates identically to `Question(text=...)` for the common refinement; the subclass identity only matters to downstream code doing `isinstance`/subclass-field access on a Text refinement, which is rare.++Real fix, when the bottom-up scalar-envelope arms are next revisited: make `StuffFactory` Case 2.1 resolve the concept's `structure_class_name` like the bool (2.1d) arm does, so both scalar-envelope arms preserve the refining subclass. Not worth pulling into the Smart Inputs finalize.diff --git a/wip/inputs/smart-inputs-design.md b/wip/inputs/smart-inputs-design.mdnew file mode 100644index 000000000..9aa7bcb79--- /dev/null+++ b/wip/inputs/smart-inputs-design.md@@ -0,0 +1,198 @@+# Smart Inputs — signature-driven input shaping: design++Status: **design approved — all decisions D1–D11 decided with Louis** (D1–D4 on 2026-07-06, D5–D11 approved 2026-07-07 with two amendments: the D9 resolution via a native `YesNo` concept as a companion track, and the D11 template-generation `--explicit` flag). Branch `feature/Smart-inputs` (worktree `_smart`), based on main at v0.38.0 (includes TOML inputs #1022 and Optionals phase 1 #1021). Execution order across the whole track (YesNo → Datetime → Smart Inputs, one release) is in this folder's `README.md`. No implementation plan yet — that comes next.++## 1. The problem++When you run a pipeline, the expected shape of every input is already known: the pipe declares `inputs = { question = "legal.Question", priority = "scoring.Priority", cvs = "native.Document[]" }`, and that declaration is parsed into an `InputStuffSpecs` (name → `StuffSpec{concept, multiplicity, presence}`) before any input data is read. Yet the inputs file must be *self-describing*: anything beyond a bare string or list of strings needs the `{"concept": "...", "content": ...}` envelope, repeating type information the runtime already has.++The root cause is architectural, and it is one line wide. Every surface — CLI (JSON/TOML file, inline JSON), Python API, hosted runner — funnels inputs through a single chokepoint: `WorkingMemoryFactory.make_from_pipeline_inputs` → `StuffFactory.make_stuff_from_stuff_content_or_data` (`pipelex/core/stuffs/stuff_factory.py:229`). The call site, `prepare_pipe_job` (`pipelex/pipeline/execution_seams.py:198`), **holds the resolved `pipe` object — `pipe.inputs` is the full signature — and never passes it down.** Interpretation is bottom-up, from the value's shape alone:++| You provide | Declared input | What happens today |+|---|---|---|+| `"What are the fees?"` | `legal.Question` (refines Text) | **Silent mistype.** Becomes a `native.Text` stuff, not a `Question`. Runs anyway (`validate_before_run` checks presence only) — the graph, provenance, and concept-driven branching see the wrong type. |+| `42` | `scoring.Priority` (refines Number) | **Hard error.** `int`/`float` aren't even in the `StuffContentOrData` protocol type. |+| `{"invoice_number": "INV-001", "amount": 1250.0}` | `accounting.Invoice` (structured) | **Hard error** demanding the envelope: "does not have a 'concept' key". |+| `[{"name": "Alice"}, {"name": "Bob"}]` | `crm.Person[]` | **Hard error** (list of dicts unsupported without envelope). |+| `[]` | `contracts.Clause[]` | **Hard error** ("cannot create Stuff from empty list") — even though the signature names the item concept. |++So today's behavior is a mix of hard errors (numbers, dicts) and silent type erosion (strings for refined concepts). Both stem from the same signature-blindness.++The mental-model statement of the fix: **inputs are arguments to a typed function; the signature is the type annotation; the call site should not repeat the types.** Today's inputs file is a serialization of working memory (self-describing, mirror-of-internal-shape). It should instead be *values*, interpreted top-down against the declared signature — with the explicit envelope remaining as the escape hatch, not the default ceremony.++Everything the fix needs already exists as primitives: `ConceptLibrary.is_compatible` (refinement/subsumption, `pipelex/libraries/concept/concept_library.py:98`), `Concept.get_structure_class()` (concept → pydantic model, `pipelex/core/concepts/concept.py:174`), `StuffContentFactory.make_content_from_value` (structure class + str/dict → typed content, `pipelex/core/stuffs/stuff_content_factory.py:12`), and `InputStuffSpecs` itself (`pipelex/core/pipes/inputs/input_stuff_specs.py`). They have just never been composed at the right seam.++## 2. The shape at a glance++Given this method:++```toml+[concept.Question]+description = "A question about a legal document"+refines = "Text"++[concept.Priority]+description = "A priority level from 1 to 5"+refines = "Number"++[concept.Invoice]+description = "An invoice"+structure = { invoice_number = "text", amount = "number" }++[pipe.analyze_case]+inputs = { question = "Question", priority = "Priority", invoice = "Invoice", exhibits = "native.Document[]" }+output = "CaseAnalysis"+```++Today's `inputs.json`:++```json+{+ "question": {"concept": "legal.Question", "content": "What are the fees?"},+ "priority": {"concept": "legal.Priority", "content": {"number": 3}},+ "invoice": {"concept": "legal.Invoice", "content": {"invoice_number": "INV-001", "amount": 1250.0}},+ "exhibits": {"concept": "native.Document", "content": [{"url": "exhibit-a.pdf"}]}+}+```++With smart inputs:++```json+{+ "question": "What are the fees?",+ "priority": 3,+ "invoice": {"invoice_number": "INV-001", "amount": 1250.0},+ "exhibits": ["exhibit-a.pdf"]+}+```++Every value is interpreted against the declared spec: the string becomes a *`Question`* (the declared concept, correctly typed — not `native.Text`), the number a `Priority`, the dict validates against `Invoice`'s structure class, and the list satisfies `Document[]` element-wise with each string read as a URL/path. The envelope form still works everywhere and is now additionally *checked* against the declaration.++## 3. Options considered for where the smartness lives++- **A. Signature-driven shaping at the core seam (chosen).** Thread `pipe.inputs` into working-memory construction; interpret each provided value against its declared `StuffSpec`. One chokepoint, so every surface benefits at once; fixes both the hard errors and the silent mistyping; strictly widens what is accepted.+- **B. CLI-layer preprocessing.** Shape the loose file into canonical envelope form inside the CLI before core sees it. Rejected: API/client/SDK users get nothing, the logic duplicates per surface, and the CLI would re-do signature resolution the runtime performs anyway. The smartness would sit on the wrong side of the funnel.+- **C. Retype-after-build (promotion pass).** Keep bottom-up building, then promote each Stuff's concept to the declared concept when compatible. Rejected as a standalone: bare numbers and dicts explode before promotion ever runs. Retyping is a sub-mechanism of A, not an alternative.+- **D. LLM-assisted adaptation.** When deterministic shaping fails (a dict whose fields *almost* match the structure, a CSV with different column names), optionally run a mapping step — Pipelex eating its own dog food. Deferred to a later phase as an explicit opt-in (see §8); v1 smartness must be deterministic and predictable.++## 4. Decisions taken (D1–D4, with Louis, 2026-07-06)++### D1 — Activation: always-on, all surfaces, no flag++Signature-driven interpretation is the default behavior wherever a signature exists — CLI file/inline inputs, Python API `execute(inputs=dict)`, hosted runner. No `--smart-inputs` flag, no config knob. Rationale: it strictly widens the accepted input space; the only behavioral change to previously-working inputs is *better typing* (bare strings now typed as the declared concept instead of `native.Text`), which is a fix, not a regression. Consistent with the no-backward-compat principle. Alternatives rejected: opt-in flag (splits docs into two modes, adds ceremony), CLI-only (see option B above).++Out of scope of the flag question: inputs passed as an already-built `WorkingMemory` bypass shaping entirely (they are already typed).++### D2 — Multiplicity: auto-wrap singles, element-wise shaping, empty lists legal++When the declared spec has multiplicity (`X[]` or `X[N]`):++- A JSON list shapes **element-wise**: each item is interpreted against the item concept (strings, numbers, dicts — same rules as singulars), producing a `ListContent` typed with the declared concept.+- A **single bare value auto-wraps** into a one-item list. Generous, matches the feature's spirit. Fixed-count `[N]` still validates the count — a single value only satisfies `[1]`.+- An **empty list is legal** and produces an empty `ListContent` typed with the declared item concept. (Today it's an error because there is nothing to infer from; the signature removes the ambiguity. This also aligns with Optionals D4: emptiness is the plural "nothing".)+- Conversely, a list provided where a singular is declared is a **hard error** (we can't guess which item was meant).++### D3 — File-ish native concepts: a bare string is a URL/path++When the declared concept resolves to a file-carrying native content class (Image, Document, and any concept refining them), a bare string is read as a URL/path: `"photo": "photo.jpg"` satisfies an `Image` input. Unambiguous because these concepts don't refine Text — there is no collision with text interpretation; the signature is what disambiguates. The existing `{"url": ...}` dict form keeps working (and is itself now shaped by the signature, no envelope needed). The CLI's relative-path resolution (`resolve_inputs_paths`) must learn to resolve these bare strings too — today it only walks `"url"` keys; it needs the signature to know which bare strings are paths (see D7, seams).++### D4 — Failure mode: hard error with a rendered template hint++When a provided value cannot be shaped to the declared concept — wrong scalar kind, dict failing structure validation, list where singular is declared, envelope naming an incompatible concept — the run fails with a typed error that names the input, the declared concept ref, what was provided, and **renders the expected shape** by reusing the template machinery (`InputStuffSpecs.build_inputs_template` / `StuffSpec.render_stuff_spec`). No fallback to bottom-up inference on failure: predictability beats forgiveness, and the silent-mistyping path must not survive through a back door. New error classes go in the relevant `exceptions.py` with class-level `error_domain`/`user_action` so docs pages, `type_uri`s, and RFC 7807 rendering come free.++## 5. Decisions D5–D11 (approved 2026-07-07)++### D5 — The interpretation matrix (the core of the mechanism)++For each provided input with a declared `StuffSpec` (after D2's multiplicity peeling), dispatch on the *declared concept's* nature, not the value's shape:++| Declared concept resolves to | Accepted bare values | Result |+|---|---|---|+| Text-refining (structure class ⊑ `TextContent`) | `str` | Declared concept's structure class instantiated with the text — the Stuff is typed as the *declared* concept |+| Number-refining (⊑ `NumberContent`) | `int`, `float` (NOT `bool` — see D9) | Same, `number` field set |+| Image/Document-refining | `str` (URL/path, D3) or `{"url": ...}`-style dict | Native content class from url |+| Structured (⊑ `StructuredContent`) | `dict` | `structure_class.model_validate(dict)` — pydantic does the real validation |+| `Dynamic` / `Anything` | anything | Fall back to today's bottom-up rules (the signature genuinely doesn't know) |+| YesNo-refining (future, D9 companion track) | `true` / `false` | Typed yes/no content — this row activates when the native `YesNo` concept lands |++Cross-kind mismatches are D4 errors: a string for a Number-refining concept is an error, not a parse attempt (`"42"` stays a string — no coercion across JSON types; JSON already distinguishes). Python-object inputs (`StuffContent` instances, `ListContent`) keep today's behavior, plus the D6 compatibility check.++### D6 — Explicit forms are checked, and explicit wins when compatible++The envelope `{"concept": C, "content": ...}` and direct `StuffContent` objects remain fully supported. Two changes:++- **New check:** the provided/inferred concept must be compatible with the declared concept (`ConceptLibrary.is_compatible(tested=provided, wanted=declared)`), else D4 error. Today there is NO such check — you can feed any envelope concept to any input and nothing notices until something downstream misbehaves. This closes the other half of the silent-mistyping hole.+- **Explicit wins when compatible:** if the caller names a concept that *refines* the declared one (passes `sales.UrgentQuestion` where `legal.Question` is declared... when compatible), the provided, more specific concept is kept on the Stuff. The caller is volunteering information; the signature only sets the lower bound.++Envelope-shape collision rule: a dict whose keys are exactly `{"concept", "content"}` is always read as an envelope, even if the declared structured concept happens to have fields named `concept` and `content`. The escape hatch for that (pathological) structure is the envelope itself: `{"concept": "x.That", "content": {"concept": ..., "content": ...}}`. One deterministic rule, no sniffing.++### D7 — Where the shaper lives (code seams)++- New module `pipelex/core/memory/input_shaper.py` (name open — see §7): a pure function/class taking `(pipeline_inputs, input_specs: InputStuffSpecs, search_domain_codes)` → `WorkingMemory`, built on the existing `StuffContentFactory` / `is_compatible` primitives.+- `WorkingMemoryFactory.make_from_pipeline_inputs` gains an `input_specs: InputStuffSpecs | None = None` parameter; `None` keeps today's bottom-up path (callers that genuinely have no signature).+- `prepare_pipe_job` (`execution_seams.py:198`) passes `pipe.inputs` — the boundary contract, same choice the Optionals code made in the omitted-optional pass right below (`execution_seams.py:226`), NOT `needed_inputs()` (whose aggregation carries children's markers).+- The signature to shape against is the **entry pipe's** declaration only; sub-pipe inputs flow through working memory internally and are never re-shaped.+- CLI relative-path resolution (`_inputs_path_resolver.py`) currently rewrites relative `"url"` values before the library is loaded. With D3, bare strings for file concepts also need resolving — simplest is to move/duplicate path resolution after pipe resolution, or resolve lazily at shaping time by threading the base dir. To be settled at implementation-plan time.++### D8 — Unknown input names are errors++With a signature in hand, a provided name absent from `pipe.inputs` is a **typo detector**: error naming the unknown input and listing the declared ones. Today extras are silently carried in working memory and never read. Risk to weigh: any workflow deliberately over-providing inputs (shared inputs file across several pipes of a bundle?) would break — if that pattern matters, downgrade to a warning. Leaning error (loud beats silent), flagging explicitly because it is the one place smart inputs *narrows* accepted behavior.++### D9 — Booleans: an error today, a native `YesNo` concept as a companion track++There is no boolean native concept today (natives: Text, Number, Image, Document, HTML, TextAndImages, Page, JSON, SearchResult, Dynamic, Anything, Composite), so within Smart Inputs a bare `true` at the top level of an input has no declared target it can satisfy — D4 error mentioning that booleans live inside structured concepts (the structure-field level already has a `boolean` field type). Guards that hold regardless: Python `bool` is a subclass of `int`, so the Number arm must explicitly exclude `bool` before accepting ints; `null` at the top level is an error too — absence is expressed by *omitting* the key (Optionals), not by null.++**Resolution (decided 2026-07-07): the gap is real and gets fixed by a native `YesNo` concept, shipped as its own companion track** (same pattern as the planned DATETIME native concept from the TOML-inputs track — a native concept touches LLM structured output, rendering, schema regen, the MTHDS spec and downstream mirrors, not just inputs). LLM pipelines constantly produce yes/no judgments ("does this contract contain a penalty clause?"), and today authors hack them as `Text` answering "yes"/"no" or a single-field structure.++Naming: **`YesNo`**, chosen over Boolean (geeky), TrueFalse, Logical, Truth, and Checkbox. Precedents from user-friendly language history: Microsoft Access named its boolean field type literally "Yes/No"; Excel calls TRUE/FALSE "logical values" (the Logical function category); Inform 7 calls the type a "truth state"; Airtable/Notion/Salesforce say "Checkbox" (names the widget, not the meaning). `YesNo` reads as "the answer to a yes/no question" — exactly what these values are in LLM pipelines (`output = "YesNo"`), fits the plain-noun native family, and the PascalCase compound follows the TextAndImages precedent.++When `YesNo` lands, the D5 matrix gains a row (YesNo-refining concept + JSON `true`/`false` → typed content) and this D9 error arm narrows to genuinely-unshapeable scalars. Open questions parked for that track: the content class field name (`YesNoContent` following the `NumberContent.number` pattern), rendered_plain as "yes"/"no", whether the lowercase `boolean` structure-field type gains a friendlier alias for consistency, and how PipeLLM generates a `YesNo` output.++### D10 — Protocol widening (MTHDS-brand surface)++`StuffContentOrData` / `PipelineInputs` live in `mthds/protocol/pipeline_inputs.py` — MTHDS-brand, spec territory. The type must widen to admit scalars, lists of dicts, and empty lists; honestly it converges toward "any JSON value | StuffContent forms". The interpretation semantics (this design's matrix) should be spec'd on the MTHDS side (docs/specs + the mthds repo), since signature-driven reading is a property of the protocol's inputs format, not a Pipelex quirk — no `pipelex_` naming anywhere wire-visible. Downstream mirrors (mthds-python, mthds-js `PipelineInputs` types, conformance rows, JSON schema if any) sweep after the pipelex release, same de-gate pattern as Optionals/TOML-inputs.++### D11 — Interactions with adjacent features++- **Optionals:** unchanged. An omitted `?` input still becomes a not-provided absence record; shaping only applies to *provided* values. Presence markers don't affect the interpretation matrix.+- **Mock inputs (dry run):** unchanged; mock filling happens after user-input shaping, on whatever is still missing.+- **CSV tabular inputs:** today the `{"url": "*.csv"}` → `ListContent[rows]` detection requires the envelope (it needs a concept). With shaping, the declared concept powers it: `"people": "people.csv"` (bare string, D3-style) or `"people": {"url": "people.csv"}` under a declared `csv_demo.Person[]` can trigger the CSV reader with no envelope. Nice compounding win; needs the multiplicity-declared arm to try tabular detection before the "string for structured concept" error.+- **TOML inputs (#1022):** nothing format-specific — both parsers produce the same dict; shaping happens downstream of parsing. TOML templates (`--format toml`) simplify identically.+- **Template generation (`pipelex build inputs`):** the **default becomes the light, signature-driven shape** — example *values* shaped like what smart inputs accepts — and the fully ceremonial envelope shape stays available behind a flag (decided 2026-07-07; proposed spelling `--explicit`, matching the docs' "Explicit Format" vocabulary; composes with the existing `--format json|toml`). This flips the default template from "here is the required ceremony" to "here are the values to fill in". One thing the envelope template teaches that the light one loses is *which concept each input expects* — in TOML mode the light template can carry that as comments (`# concept: legal.Question`); JSON has no comments, which is another reason to keep the `--explicit` form around.++## 6. What this deliberately does not do (non-goals)++- **No cross-type parsing.** `"42"` for a Number input is an error; JSON already distinguishes scalars. Smart means signature-driven, not guessy.+- **No LLM in the loop** (v1). See §8.+- **No fuzzy field matching** on structured dicts — pydantic validation semantics as-is (missing required field = error). Field-level aliasing/mapping is exactly where option D would start.+- **No change to outputs** or to how working memory serializes — this is strictly the input boundary.++## 7. Naming++Candidates discussed for the feature name and the mechanism term:++- **Smart Inputs** — feature/marketing name (branch already votes for it). Docs headline: "Smart Inputs — just provide the values."+- **Signature-driven input shaping** — the mechanism term for spec/docs prose; "shaping" says values are molded to a declared shape.+- Also considered: implicit inputs (sounds magic), loose inputs (sounds sloppy), natural inputs, call-site inference (accurate but jargon).++Internal name proposal: `InputShaper` (module `input_shaper.py`). Open to taste.++## 8. Later-phase candidates (design now, ship later)++- **LLM-assisted adaptation (option D).** Opt-in (`--adapt` or similar): when deterministic shaping fails, run a small mapping pipe to convert the provided value into the declared structure (field renaming, unit conversion, free text → structured). Requires clear provenance ("this input was AI-adapted") and probably a dry-run preview. Powerful for agent-facing flows and the webapp uploader.+- **Cross-input file references.** `"contract": "contract.txt"` for a Text-refining input — reading bare strings as *file paths to text* is tempting but ambiguous (is the string the content or a path?). Unlike D3, Text refinements collide head-on with literal strings. Any design here needs an explicit marker (e.g. `{"path": ...}`) rather than sniffing. Parked.+- **Defaults / coalescing.** Input-level defaults belong to the Optionals phase-2 `??` track (see `wip/optionals/optionals-design.md` §15), not here — noted only because both features touch "what happens when the caller provides less".++## 9. Surfaces impacted (checklist for the future plan)++- `pipelex/core/stuffs/stuff_factory.py`, `stuff_content_factory.py` — shaping primitives; keep bottom-up path for the no-signature/Dynamic fallback.+- New `pipelex/core/memory/input_shaper.py` (or similar) + `WorkingMemoryFactory.make_from_pipeline_inputs(input_specs=...)`.+- `pipelex/pipeline/execution_seams.py` `prepare_pipe_job` — pass `pipe.inputs`.+- `pipelex/cli/commands/run/_inputs_path_resolver.py` — bare-string path resolution for file concepts (D3/D7).+- New error classes in the relevant `exceptions.py` + regenerated error pages (`make gep`).+- `pipelex/core/pipes/inputs/input_renderer.py` + `pipelex build inputs` / `pipelex-agent inputs` CLIs — light templates by default, `--explicit` flag for the envelope form, concept comments in TOML mode (D11).+- Companion track (separate design): native `YesNo` concept (D9) — NativeConceptCode entry, content class, structure-generator mapping, LLM output support, schema regen + mthds spec + downstream mirrors.+- Protocol: `mthds` `pipeline_inputs.py` widening + spec section; downstream mirrors gated on release (D10).+- Docs: `docs/building-methods/pipes/provide-inputs.md` rewrite (it shrinks dramatically), `docs/tools/cli/run.md`, `build/inputs.md`, agent CLI docs.+- Tests: unit (shaping matrix, one test class per arm), e2e (bare-values inputs file through `pipelex run`), error-message snapshots for D4.+- Skills: `mthds-inputs` skill (mthds-plugins) — post-release sweep with the rest of the cross-repo wave.diff --git a/wip/inputs/smart-inputs-implementation-plan.md b/wip/inputs/smart-inputs-implementation-plan.mdnew file mode 100644index 000000000..9ee3c6bf5--- /dev/null+++ b/wip/inputs/smart-inputs-implementation-plan.md@@ -0,0 +1,224 @@+# Smart Inputs — signature-driven input shaping: implementation plan++Status: **COMPLETE — all phases 1–5 done, checkpoints cleared (as-built record, 2026-07-08).** Design home: `wip/inputs/smart-inputs-design.md` (**approved** — decisions D1–D11 settled). Branch `feature/Smart-inputs-phase5`, worktree `_smart`, based on main at v0.38.0 (TOML inputs #1022 + Optionals phase 1 #1021). Both native-concept prerequisites — `YesNo` (#1028) and `Date` (#1029) — landed first on this branch; Smart Inputs is the final track car, shipping in the same release wave. Remaining work is the shared release-cut cross-repo wave (D10 protocol widening + downstream mirrors), tracked in `wip/inputs/README.md`, **not** this plan. The only checkpoint step not run is the **user-gated finalize gstack `/review`** (CHECKPOINT 5).++How to use this doc: work the phases in order, check boxes as you go, and at each **CHECKPOINT** run the checkpoint protocol (below) and fill in the "state" line so the next session cold-starts from here. This file is the active working plan (mirrors how YesNo/Date used the repo-root `TODOS.md`); on completion it gets archived to `wip/inputs/smart-inputs-implementation-plan.md` as the as-built record.++---++## Checkpoint protocol — every CHECKPOINT is a HARD STOP++At each checkpoint the executing agent **must stop** and do all three, in order:++1. **Verify progress.** Run the gates for the phase: `make agent-check` (ruff/plxt/pyright-0/mypy-Success/cko), targeted pytest on the phase's new modules, and — at the phase's end — `make tb` (boot) and `make agent-test` (full suite). A checkpoint is not "reached" until its gates are green. Commit the phase as one commit; record the SHA.+2. **Gather cold-start context.** Update this file: check the phase's boxes, fill the CHECKPOINT "state" line (what landed, commit SHA, decisions taken, anything that fought back), and append any new settled decision to the micro-decisions log. If a doubt or tradeoff surfaced, capture it as a new `wip/inputs/<name>.md` note rather than silently deciding (the "defer on doubt" rule the Date track used). The goal: a fresh session can resume from this file with zero lost context.+3. **Fan out a code review.** Spawn a **Sonnet-5 sub-agent** running the `/code-review` skill (or the `pr-review-toolkit:code-reviewer` agent) over **only this phase's changes**. **Pointer-only context** — hand it the phase's commit SHA, `git diff <phase-base>..HEAD`, or the working-tree files, and nothing else: **never** the plan, the design rationale, the decision letters, or your own conclusions. The reviewer's eyes must stay independent. Goal per the brief: *clean solid software, not over-engineering* — no impossible-scenario guards, smallest correct surface. Triage its findings: apply genuine wins, dismiss the unreachable, and defer design-tradeoff findings as `wip/inputs/<name>.md` notes. Record the round in the state line.++The **final** checkpoint (Phase 5) additionally runs the heavier **gstack `/review`** (Opus fan-out: testing + maintainability + adversarial-red-team, each pointer-only) as the finalize pass — **user-gated, never launch it unprompted** (it is billed).++---++## 0. Cold-start context — read this first++**What ships:** the inputs a caller provides are interpreted **top-down against the pipe's declared signature** instead of bottom-up from their shape alone. A bare string becomes the *declared* concept (a `legal.Question`, not `native.Text`); a bare number satisfies a `Number`-refining input; a bare dict validates against a structured concept; a JSON list shapes element-wise into `ListContent[declared]`; the `{concept, content}` envelope stays as an escape hatch and is now *compat-checked*. Full problem statement, the shape-at-a-glance example, and D1–D11 with rationale are in `smart-inputs-design.md` — do not relitigate. The plan starts from design **§9 "Surfaces impacted"**.++**The mechanism in one sentence:** every surface (CLI file/inline, Python API, hosted runner) funnels inputs through one chokepoint that is signature-blind today; thread the signature into it and dispatch each value on the *declared concept's nature*.++**Key mechanism facts** (re-verified against the worktree 2026-07-07 — line numbers approximate, re-grep each symbol before citing):++- **The chokepoint.** `StuffFactory.make_stuff_from_stuff_content_or_data` (`pipelex/core/stuffs/stuff_factory.py:230`) shapes each value bottom-up. Its Case 1 (direct: str→Text, list[str]→Text list, `StuffContent`/`ListContent` passthrough, list[StuffContent]) and Case 2 (envelope `{concept, content}` — arms 2.1/2.1d bool→YesNo/2.1e·f date/2.3 StuffContent/2.5 dict/2.6 list) are the behavior Smart Inputs makes top-down. The terminal `Unexpected type for content value` is `:654`. **No signature is consulted anywhere in it.** YesNo/Date already added compat-checked scalar-envelope arms here (2.1d/2.1e/2.1f) — Smart Inputs generalizes that pattern.+- **The single seam to wire.** `make_from_pipeline_inputs` (`pipelex/core/memory/working_memory_factory.py:68`) has **exactly one caller**: `prepare_pipe_job` (`pipelex/pipeline/execution_seams.py:198`). That function already holds `pipe.inputs` and already reads `pipe.inputs.named_stuff_specs` a few lines down for the Optionals pass (`:226`). `prepare_pipe_job` is itself the single funnel for **all** surfaces — called by `bundle_validator.py` (validate/dry-run), `pipeline_run_setup.py` (real runs), and `dry_run_in_process.py`. Wiring the signature into that one `make_from_pipeline_inputs` call ⇒ D1 (all surfaces) for free.+- **`pipe.inputs` is an `InputStuffSpecs`** (`pipelex/core/pipes/pipe_abstract.py:95`, `= Field(default_factory=InputStuffSpecs)`). `InputStuffSpecs` (`pipelex/core/pipes/inputs/input_stuff_specs.py:38`) is a `RootModel[dict[str, StuffSpec]]`; useful members already present: `.root`, `.named_stuff_specs`, `.declared_names`, `.required_names`, `.is_variable_existing(name)`, `.get_required_stuff_spec(name)`, `.build_inputs_template()`, `.render_inputs()`. Each `StuffSpec` (`pipelex/core/pipes/stuff_spec/stuff_spec.py:10`) = `concept: Concept` + `multiplicity: VariableMultiplicity | None` + `presence: PresenceMarker`, with `.is_multiple()` and `.render_stuff_spec(fmt)`.+- **Multiplicity encoding (D2).** `VariableMultiplicity = bool | int` (a **type alias**, not a class, `pipelex/core/pipes/variable_multiplicity.py:10`): `None` = single, `True` = `X[]` (variable list), `int N` = `X[N]` (fixed count). `PresenceMarker(StrEnum)` = PLAIN/OPTIONAL/FORCE with `.is_optional`. Peel multiplicity first, then dispatch the item.+- **Concept-nature detection (D5).** There is **no** single "which native family does this concept refine" helper. The only tool is `ConceptLibrary.is_compatible(tested_concept, *, wanted_concept, strict=True)` (`pipelex/libraries/concept/concept_library.py:97`) called once per candidate native — exactly what `stuff_factory.py` does today for Text/YesNo/Date (`:477/:494/:504/:522`). `strict=True` = refinement/structural-equivalence only (no field-subset fallback). The 14 native codes (`NativeConceptCode`, `pipelex/core/concepts/native/concept_native.py:22`): Dynamic, Text, Image, Document, Html, TextAndImages, Number, YesNo, Date, Page, JSON, SearchResult, Anything, Composite. `Concept.get_structure_class()` (`pipelex/core/concepts/concept.py:174`) → the content class; a concept is "structured" when that class ⊑ `StructuredContent` and is not a native. `are_concept_compatible` special-cases Dynamic.+- **Building primitives (reuse, don't reinvent).** `StuffContentFactory.make_content_from_value(subclass, *, value)` and `make_stuff_content_from_concept_required(concept, *, value)` (`pipelex/core/stuffs/stuff_content_factory.py:14/:59`) already turn a str/bool/date/dict into typed content honoring refining subclasses. `make_stuff_content_from_concept_with_fallback` falls back to `TextContent` when unregistered. The shaper composes these + `is_compatible` — the new code is the *top-down dispatch*, not new content builders.+- **Protocol is runtime-unvalidated (D10 is release-gated, NOT a blocker).** `PipelineInputs` / `StuffContentOrData` (`mthds/protocol/pipeline_inputs.py`, in the **mthds-python** pinned dep) is a bare `TypeAlias` (`dict[str, StuffContentOrData]`), **verified**: no pydantic model, no runtime validation. So a bare `int`/`float`/`bool` in the inputs dict **flows straight to the shaper at runtime** even though the static type doesn't admit it. Core-scope Smart Inputs shapes bare scalars *before* this seam and works day one; the D10 widening only makes the type honest for typed SDK/API callers + downstream mirrors, and rides the release wave (Optionals/TOML-inputs precedent).+- **Path resolution today (D3/D7).** `resolve_inputs_paths(inputs_dict, *, base_dir)` → `resolve_url_in_value` (`pipelex/cli/commands/run/_inputs_path_resolver.py:75/:45`) recursively rewrites relative paths **only under keys literally named `"url"`** — it has **no** view of the pipe/signature. Called at `_run_core.py:162` and `stdin_resolver.py:191` (base_dir = inputs file's parent). D3 needs bare strings for Image/Document-family concepts resolved too; that needs the signature (Phase 3 settles where).+- **CSV compounding (D11).** `_try_make_csv_list_stuff(concept, *, content, name, code)` (`stuff_factory.py:138`, called from Case 2.5 `:555`) fires when `content` is exactly `{"url": "<tabular-path>"}` under a **non-native** concept → `ListContent[row-concept]` via `concept.get_structure_class()`. With shaping, `"people": "people.csv"` (bare, D3) or `{"url": "people.csv"}` under a declared `Person[]` can trigger it with no envelope.+- **D8 has no home today.** Nothing compares provided input names to `pipe.inputs`; `make_from_pipeline_inputs` blindly `add_new_stuff`s every key, and `execution_seams.py:210`'s `provided_names` is used only to subtract from mock-fill. `InputStuffSpecs.is_variable_existing` / `.declared_names` are the predicates a D8 check uses. The shaper is the natural home (it holds both the provided dict and the specs).+- **Template rendering today (D11).** `input_renderer.py` (`build_inputs_template`, `render_inputs`, `render_inputs_toml`, `serialize_inputs_template_to_toml` via tomlkit) → `InputStuffSpecs.build_inputs_template()` → per-spec `render_stuff_spec(JSON)` → `Concept.render_concept_representation(is_multiple=)` → `ConceptRepresentationGenerator._generate_basic_value` (`pipelex/core/concepts/concept_representation_generator.py:294`, has the temporal branch). Today this emits the **envelope** form; D11 flips the default to bare values. CLI entrypoints: `pipelex build inputs` = `pipelex/cli/commands/build/inputs/pipe_cmd.py` + `_inputs_core.py` (format switch `:92`); `pipelex-agent inputs` = `pipelex/cli/agent_cli/commands/inputs/{pipe_cmd,_inputs_core}.py` + `builder/operations/inputs_ops.py:build_inputs_for_pipe`. Both already carry `--format json|toml` (`InputsTemplateFormat`).+- **Error homes (D4).** New shaping errors belong in `pipelex/core/memory/exceptions.py` (the shaper's package). The precedent to copy is `pipelex/cli/commands/run/exceptions.py::InputsTimeOnlyNotSupportedError`: class-level `error_domain = ErrorDomain.INPUT`, `user_action = UserAction(kind=UserActionKind.CHANGE_INPUT, detail=…)`, `_authors_caller_facing_message = True`. `OptionalValueAbsentError` (`pipelex/core/pipes/inputs/exceptions.py`) is the other in-tree example. Every error class subclasses `PipelexError`; run `make gep` after adding/renaming.++**Test + e2e layout** (extend these, don't invent new trees): unit — `tests/unit/pipelex/core/stuffs/test_stuff_content_factory.py`, `test_stuff_factory_implicit_memory.py` + its `data.py` (the case table YesNo/Date extended), `tests/unit/pipelex/core/memory/` (working-memory tests); new shaper tests go in `tests/unit/pipelex/core/memory/input_shaper/` (one TestClass per module, mirroring `stuffs/date_content/`). e2e — `tests/e2e/pipelex/pipes/<feature>/<bundle>/<bundle>.mthds` + a `test_*.py` (precedents: `tests/e2e/pipelex/pipes/{date,yes_no}/`).++**House rules that bite here:** TDD (tests first, red→green); keyword-only args (bare `*` after the subject — `make cko` gates, plus a PostToolUse hook at edit time); error classes only in `exceptions.py` modules; exhaustive `match/case` over enums, **never** `case _`; `make agent-check` after code changes; `make agent-test` before wrapping a session (`make atd` if it hangs); `make tb` for a quick boot check; `make gep` regenerates error pages; no hardcoded counts in docs/comments; changelog entries under `[Unreleased]`; docs updated in the same change (§ "Documentation" in CLAUDE.md).++---++## Gaps surfaced while planning — confirm defaults (recommendations given, loop not blocked)++The design settled D1–D11; three corners it doesn't spell out. Recommended defaults let execution proceed; flag to Louis if any feels wrong.++- **Out-of-matrix natives.** D5's matrix names Text / Number / Image·Document / Structured / Dynamic·Anything / YesNo / Date. It is silent on a declared input concept refining **Html, JSON, Page, TextAndImages, SearchResult, Composite**. **Recommendation:** treat these like Dynamic — *no* new top-down arm; fall back to today's bottom-up `StuffFactory` for that single input (preserves current behavior, widens nothing, breaks nothing). Revisit per-native only if a real need appears. Confirm.+- **D3 path-resolution seam.** Where do bare strings for Image/Document concepts get relative-path-resolved, given the current resolver is signature-blind and pre-core? **Recommendation:** make the CLI resolver signature-aware — pass the resolved pipe's `InputStuffSpecs` into `resolve_inputs_paths` so it resolves bare strings whose declared concept is Image/Document-family *in addition to* `"url"` keys — keeping path resolution a CLI concern (API/SDK callers pass absolute URLs/storage URIs, no base_dir). Settle the exact mechanism as Phase 3's first task (it hinges on pipe-resolution ordering in `_run_core.py`).+- **D8 severity.** Design leans **error** on unknown input names but flags the shared-inputs-file-across-pipes risk. **Recommendation:** error (loud beats silent), with a message that lists the declared names — the one place Smart Inputs narrows behavior. Confirm; downgrade to a warning only if a real over-provisioning workflow surfaces.++---++## Phase 1 — The `InputShaper` core (D5 matrix, D2 multiplicity, D6 compat, D8 names, D4 errors)++Build the shaper as a **pure, fully unit-tested unit that is not yet wired** into any run. It reuses the existing primitives (`StuffContentFactory`, `is_compatible`, and delegates Dynamic/out-of-matrix/already-built values to the current `StuffFactory`); the new code is the top-down dispatch. Tests construct `InputStuffSpecs` fixtures directly — no seam needed.++- [x] **Tests first (red→green).** New `tests/unit/pipelex/core/memory/input_shaper/` (one TestClass per module + shared `data.py`): one arm per D5 row — Text-refining ← str; Number-refining ← int/float and **rejects bool** (the `bool ⊑ int` trap) and rejects `"42"` (no cross-type parse); YesNo-refining ← bool; Date-refining ← date/datetime obj + ISO str; Image/Document-refining ← bare str + `{"url":…}` dict; Structured ← dict (pydantic validates; missing-required-field → D4); Dynamic/Anything ← bottom-up passthrough. D2: list shapes element-wise into `ListContent[declared]`; single bare value auto-wraps; empty list → empty `ListContent[declared]`; `X[N]` count-checked (single satisfies `[1]`, not `[2]`); list-under-singular → D4. D6: envelope `{concept, content}` compat-checked, explicit-refining-concept wins, incompatible → D4; the exact-two-keys collision rule. D8: unknown provided name → error listing declared names. D9 guards: top-level `null`/`None` → D4 (absence = omit key); bool never leaks into the Number arm. Each failure asserts the rendered expected-shape template appears in the message. **DONE**: 4 test modules (`test_scalar_arms.py`, `test_multiplicity.py`, `test_explicit_forms.py`, `test_errors.py`) + `conftest.py` (autouse class-scoped library setup) + `data.py` (refining/structured content classes + `build_input_specs` helper), 39 tests, all green.+- [x] **New module `pipelex/core/memory/input_shaper.py`** — `InputShaper.shape(pipeline_inputs, *, input_specs: InputStuffSpecs, search_domain_codes) -> WorkingMemory`. Internal `resolve_input_kind(concept) -> InputKind` (new `StrEnum`: TEXT/NUMBER/YES_NO/DATE/IMAGE/DOCUMENT/STRUCTURED/DYNAMIC) composed from ordered `is_compatible(concept, get_native_concept(X), strict=True)` checks + the structured/dynamic fallback. Per-input algorithm: D8 name check (batch, first) → look up spec → explicit-form arm (D6 compat, post-hoc) → D9 null guard → D5 kind dispatch (DYNAMIC short-circuits to bottom-up before multiplicity peel) → D2 multiplicity peel → build `Stuff` typed as the declared (or compatible-more-specific) concept. Delegate Dynamic / out-of-matrix natives / explicit forms to `StuffFactory.make_stuff_from_stuff_content_or_data`.+- [x] **New error classes in `pipelex/core/memory/exceptions.py`** (D4) — `InputShapingError` base + `WrongScalarKindError`, `ListWhereSingularError`, `MultiplicityCountMismatchError`, `StructureValidationError`, `ExplicitConceptIncompatibleError`, `UnknownInputNameError`, `NullInputError`. `error_domain = ErrorDomain.INPUT`, `_authors_caller_facing_message = True`; base carries a per-instance `user_action` (advice differs per failure). Each `make(...)` names the input, the declared concept ref, what was provided, and **renders the expected shape** via `stuff_spec.render_stuff_spec(JSON)`. `make gep` ran (new pages written).+- [x] `make agent-check` green (pyright 0 / mypy Success / cko PASSED); targeted pytest on the new modules green (39); `make tb` green (9); core memory/stuffs/concepts suite green (855).++### CHECKPOINT 1 — the shaper exists, is unit-green, and is NOT yet wired++Run the checkpoint protocol (verify · cold-start update · Sonnet-5 `/code-review` fan-out, pointer-only). This is the largest reviewable unit and the one most prone to over-engineering — the review's mandate is *smallest correct surface*.++State: **REACHED (2026-07-07).** The `InputShaper` core exists, is unit-green (41 tests), and is NOT wired into any run (pure; Phase 2 wires the seam). Gates: `make agent-check` fully green (pyright 0 / mypy Success / cko PASSED), `make tb` green (9), core memory/stuffs/concepts suite green (855). Cold-start micro-decisions appended below. Committed as the single Phase-1 commit on `feature/Smart-inputs` (message `feat(core): Smart Inputs Phase 1 — the InputShaper core (not yet wired)`; find via `git log --grep "Smart Inputs Phase 1"`).++**Review round 1** — Sonnet-5 `pr-review-toolkit:code-reviewer`, pointer-only (working-tree diff, no plan/design/rationale). One **Critical** + two Minor. Triage:++- **Critical (APPLIED).** A bare Python `list` of already-built `StuffContent` items (e.g. `[Question(text="a"), Question(text="b")]` for a declared `Question[]` — the documented `StuffContentOrData` Case-1.4 form, handled bottom-up today) crashed in per-item shaping (`_build_item_content` only accepted bare scalars/dicts) → `WrongScalarKindError`. Genuine regression vs today's behavior / D1's "no regression, only better typing". **Fix:** `_build_item_content` now handles a `StuffContent` item by building it bottom-up (concept inferred from its class) + D6 compat-check against the declared item concept, mirroring the wrapped-`ListContent` path; `search_domain_codes` threaded down `_shape_with_multiplicity`/`_shape_list`/`_build_item_content`. This preserves D2 for the singular case (list-where-singular still errors) and fixed-count checks. Two regression tests added (`test_list_of_prebuilt_stuff_content_items`, `test_list_of_prebuilt_incompatible_item_raises`).+- **Minor (no change).** The `InputKind.DYNAMIC` arm in `_build_item_content`'s match is dead but a justified exhaustive-match guard (repo forbids `case _`); reviewer agreed.+- **Minor (APPLIED).** `test_errors.py`'s `expects_rendered_shape` column was always `True` (dead flexibility) → dropped; the rendered-shape assertion is now unconditional.++No design-tradeoff findings to defer. The one pre-existing asymmetry the shaper does not close (envelope escape hatch still builds plain `TextContent` for a Text-refining concept via `StuffFactory` Case 2.1c, while the bare path builds the refining subclass) is already tracked in `wip/inputs/scalar-envelope-arm-asymmetry.md` for Phase 5 triage.++---++## Phase 2 — Wire the seam: top-down shaping goes live on all surfaces (D7, D1, D8)++The behavior-change phase. Small and contained (one factory param, one call site), but this is where real runs start interpreting values top-down — the riskiest integration point, hence its own checkpoint.++- [x] **Tests first.** e2e: a **bare-values inputs file** through the runner in `--dry-run`, asserting each Stuff carries the **declared** concept (not `native.Text`). Error tests for a D4 mismatch and a D8 unknown name. A regression test pinning that a **no-signature** caller (`input_specs=None`) still gets today's bottom-up behavior. A test that a bare `int` survives to the shaper despite the narrow `PipelineInputs` alias (runtime-reachability pin). **DONE**: e2e bundle `tests/e2e/pipelex/pipes/smart_inputs/smart_inputs_triage/` + `test_smart_inputs_dry_run.py` (4 cases: bare-values→declared concepts, empty-list→empty ListContent, wrong-scalar-kind→`WrongScalarKindError`, unknown-name→`UnknownInputNameError`); 2 integration pins added to `test_working_memory_factory.py`. Used `PipelexMTHDSProtocol.execute(...)` (the date/yes_no pattern) rather than shelling the CLI — same seam.+- [x] **`WorkingMemoryFactory.make_from_pipeline_inputs`** gains `input_specs: InputStuffSpecs | None = None`: `None` → today's bottom-up loop (unchanged); present → delegate to `InputShaper.shape(...)`. **DONE** (top-level `InputShaper` import — no cycle).+- [x] **`prepare_pipe_job`** passes `input_specs=pipe.inputs` — the method-boundary contract. **DONE**. Confirmed exactly one production caller of `make_from_pipeline_inputs` (the seam); all other callers are tests that stay on the `input_specs=None` bottom-up path. Validator / real-run / dry-run all inherit shaping through `prepare_pipe_job`.+- [x] **D8 goes live**: unknown provided names now error. **DONE** — and the full suite proved **zero** in-tree fixture relied on silently-ignored extra inputs (no fixture loosening needed).+- [x] `make agent-check` (pyright 0 / mypy Success / cko PASSED) + full `make agent-test` green. **The only full-suite failures were the 3 pre-existing Phase-1 InputShaper isolation failures — now FIXED here** (see state line); no shaping-caused fallout across the suite.++### CHECKPOINT 2 — top-down shaping is live end-to-end++Run the checkpoint protocol. Emphasize in the cold-start update: any existing-test fallout and how it was resolved (a genuine behavior fix vs a test that encoded the old bottom-up mistyping). Sonnet-5 `/code-review`, pointer-only.++State: **REACHED (2026-07-07).** Top-down shaping is live on all surfaces through the one seam. Wiring: `make_from_pipeline_inputs(input_specs=…)` delegates to `InputShaper.shape` when specs are present (else bottom-up, verbatim); `prepare_pipe_job` passes `input_specs=pipe.inputs`. D8 is live. Committed as the single Phase-2 commit `7fe279d51` (`feat(core): Smart Inputs Phase 2 — top-down shaping goes live on all surfaces`). Gates: `make agent-check` green (pyright 0 / mypy Success / cko PASSED), full `make agent-test` **green**.++**Existing-test fallout: NONE of the behavior kind.** Turning D8 live perturbed zero in-tree fixtures — no bundle relied on silently-ignored extra inputs, so no fixture was loosened. The only full-suite red was the **3 pre-existing Phase-1 InputShaper isolation failures** (bare class-name collision in the shared kajson class registry: an integration test's `Person(role)`/`Invoice` silently overwrote the shaper's), which are **fixed here** by `Shaper`-prefixing the shaper test's structured class **and** concept codes (they must match — the bottom-up factory infers a prebuilt `StuffContent`'s concept from its class name). Proven deterministic by running the colliding integration suite + shaper unit suite in one process (`-n0`) → all green. This supersedes the "pre-existing full-suite fail" note in the project memory.++**Review round 1** — Sonnet-5 `pr-review-toolkit:code-reviewer`, pointer-only (commit SHA + diff, no plan/design/rationale). **Correctness-clean, zero findings.** It independently confirmed the two failure modes this phase could have had: (a) controller pipes — `PipeAbstract.generic_validate_inputs_with_library` (`pipe_abstract.py`, `@final`) enforces exact name-set equality between `self.inputs` and `needed_inputs().declared_names` at library-load time, so the D8 check on `pipe.inputs` can never diverge from what a controller actually needs (validates the `pipe.inputs`-not-`needed_inputs()` choice); (b) the new e2e fixture's inline `[concept.Invoice.structure]` registers under a **domain-qualified** class name (`smart_inputs_demo__Invoice` via `make_qualified_structure_class_name`), not bare `Invoice`, so it does not reintroduce the collision the rename fixes. Nothing to apply, nothing to defer.++---++## Phase 3 — File-ish concepts (D3/D7) + CSV-by-signature (D11 compounding)++- [x] **Settle the D3 path-resolution mechanism** (first task — decide, then implement). **DECIDED: thread `inputs_base_dir` into the shaper** (the plan's second option), NOT the signature-aware CLI resolver. Rationale below. Base_dir is a `Path | None` optional param, `None` for API/SDK/in-process callers; the shaper is the ONE place that both knows each input's declared-concept nature and does the building, so it resolves file-ish AND CSV relative paths in one spot with no concept-nature detection duplicated into the CLI and no pipe-resolution reordering in `_run_core.py`.+- [x] **Tests first.** Unit: `test_file_paths.py` (bare relative→base_dir-resolved, absolute/remote/scheme untouched, no-base_dir→CWD contract, list element-wise, `{"url":…}` dict left to CLI walk) + `test_csv_by_signature.py` (bare + exact `{"url":…}` under `ShaperPerson[]`, relative+base_dir, fixed-count ok/mismatch, singular→wrong-kind, non-tabular fall-through, sibling-keys stays record, remote→CsvError). E2e: `smart_inputs_files` bundle + `test_smart_inputs_files_dry_run.py` (bare photo/exhibits/csv resolve; `{"url":…}` form matches bare; normalization disabled so the resolved path is assertable). CLI wiring: `parse_cli_inputs` base-dir contract in `test_stdin_resolver.py`, human-CLI `inputs_base_dir` in `test_run_core_execution.py`, agent-CLI in `test_run_core_inputs_base_dir.py`.+- [x] Implement the D3 bare-string→url/path arm (shaper Image/Document dispatch resolves via `_resolve_local_path`) + CSV detection (`_try_shape_csv` ahead of element-wise shaping, reusing extracted `StuffFactory.try_make_csv_list_content`); threaded `inputs_base_dir` shaper→factory→`prepare_pipe_job`→`pipeline_run_setup`→runner ctor→both CLIs.+- [x] `make agent-check` green (pyright 0 / mypy Success / cko PASSED); targeted e2e green; `make tb` green (9); full `make agent-test` green.++### CHECKPOINT 3 — file-ish inputs and CSV-by-signature work++Run the checkpoint protocol. Sonnet-5 `/code-review`, pointer-only.++State: **REACHED (2026-07-07).** Bare file-ish strings (Image/Document-refining) and bare CSV references (under a declared structured `X[]`) now shape top-down with no envelope, and relative paths resolve against the inputs file's directory. **D3 mechanism = `inputs_base_dir` threaded into the shaper** (settled — see the first checkbox + micro-decisions; the signature-aware-CLI-resolver alternative was rejected because it would split path resolution across two places, duplicate the shaper's concept-nature detection in the CLI, and force pipe-resolution reordering in `_run_core.py`). `is_relative_local_path` moved from the CLI resolver to `pipelex/tools/uri/uri_resolver.py` (shared, no re-export). `StuffFactory._try_make_csv_list_stuff` split into a public content-returning `try_make_csv_list_content` (shaper + Case-2.5 both call it; Case 2.5 behavior byte-identical). Agent-CLI `parse_cli_inputs` now returns a `ParsedCliInputs` NamedTuple (`pipeline_inputs` + `inputs_base_dir`) — the file-load branch carries the parent dir; inline-JSON / stdin carry `None`. Both PR #1030 threads (Codex + cubic on the bare-file-path gap) are now answerable+resolvable. Gates: `make agent-check` fully green, `make tb` green (9), full `make agent-test` **green**. Micro-decisions appended below. Commit: single Phase-3 commit `d73d1aa3c` (`feat(core): Smart Inputs Phase 3 — file-ish inputs (D3) + CSV-by-signature (D11)`).++**Review round 1** — Sonnet-5 `pr-review-toolkit:code-reviewer`, pointer-only (commit `d73d1aa3c` + diff, no plan/design/rationale). **Correctness-clean, zero findings.** It traced the full `inputs_base_dir` chain, verified the CLI-level `resolve_inputs_paths` (`"url"`-key walk) and shaper-level `_resolve_local_path` (bare strings) are non-overlapping + idempotent on absolute paths (no double-resolution), re-ran ruff/pyright/mypy/cko + the new unit + e2e tests, and confirmed the `StuffFactory` split is byte-identical (all Case-2.5 gates still exercised). It named two **intentional** boundaries (not bugs, not new — both pre-existing or documented): (a) the `--runner api` path doesn't get D3 base_dir resolution (deliberate — API callers pass absolute urls; captured in the micro-decisions), and (b) a bare CSV path *list-wrapped* (`["people.csv"]`) under `Person[]` is a loud `WrongScalarKindError` rather than CSV-detected (CSV detection runs on the value the caller wrote, before the multiplicity auto-wrap; clear non-silent failure). Nothing to apply, nothing to defer.++---++## Phase 4 — Template generation flips to the light shape (D11)++The default `pipelex build inputs` / `pipelex-agent inputs` template becomes the **light, signature-driven values** (example values shaped like what the shaper accepts); the ceremonial envelope form moves behind an **`--explicit`** flag, composing with the existing `--format json|toml`. TOML light templates carry the declared concept as a comment (`# concept: legal.Question`); JSON can't (no comments), which is itself a reason to keep `--explicit`.++- [x] **Tests first.** Golden-template tests: light JSON + light TOML (with concept comments) for a mixed-signature pipe; `--explicit` reproduces today's envelope template; both compose with `--format`. **Round-trip test** (the bug the Date `/review` caught — a template that won't `run` is worthless): `build inputs` (light default) → `run --dry-run` succeeds against the same pipe. **DONE**: unit `tests/unit/pipelex/core/pipes/test_input_renderer_light.py` (delighten arms + light-TOML inline-table/comment/ordering, mocked kind — no library); integration golden `tests/integration/pipelex/core/pipes/test_input_renderer_light_golden.py` (real triage+files bundles, real `resolve_input_kind` — light JSON, light TOML+comments, `--explicit` reproduces envelope, both formats compose); round-trips — in-process `tests/e2e/pipelex/pipes/smart_inputs/test_smart_inputs_light_roundtrip.py` (render light JSON → dry-run COMPLETED + declared concepts) and real-binary `tests/e2e/pipelex/cli/test_toml_inputs_build.py` (rewritten: light-default TOML → dry-run **and** `--explicit` TOML → dry-run).+- [x] Implement: light-vs-explicit switch. **Mechanism = a post-hoc delighten transform in `input_renderer` (NOT threading a flag through `Concept.render_concept_representation` / `render_stuff_spec` / `InputStuffSpecs.build_inputs_template`).** Those stay the single-purpose envelope generator (outputs/schema/runner-code still use them unchanged); `input_renderer.build_inputs_template(explicit=…)` builds the envelope then unwraps it per declared-concept kind via `InputShaper.resolve_input_kind` (single source of truth, no duplicated classification). `--explicit` added to `build inputs` (pipe/bundle/method + `_inputs_core`) and `pipelex-agent inputs` (pipe/bundle/method + `_inputs_core` + `inputs_ops`). TOML concept comments + inline-table layout via `serialize_inputs_template_to_toml(light=True, concept_comments=…)`.+- [x] `make agent-check` green (pyright 0 / mypy Success / cko PASSED); targeted tests green; `make tb` green (9); full `make agent-test` **green**.++### CHECKPOINT 4 — templates default to light, `--explicit` restores the envelope++Run the checkpoint protocol. Sonnet-5 `/code-review`, pointer-only.++State: **REACHED (2026-07-07).** `pipelex build inputs` / `pipelex-agent inputs` now emit the **light** signature-driven template by default (bare string for Text-refining, bare number for Number-refining, content dict for structured, bare URL for file-ish, all wrapped in a list for declared-multiple); the ceremonial `{concept, content}` envelope moved behind **`--explicit`**, composing with `--format json|toml`. Light TOML uses **inline tables** (so a bare scalar declared after a structured value stays valid TOML — the ordering footgun) and carries the declared concept as a `# concept: <ref>` comment per key **on both CLI surfaces** (human file + agent stream — see review round 1). **D3-style file-ish inputs and structured-lists round-trip** (verified real-binary + in-process). Gates: `make agent-check` fully green, `make tb` green (9), full `make agent-test` **green** (re-run green after the review fix). Commit: single Phase-4 commit **`4f7ce32e7`** (`feat(core): Smart Inputs Phase 4 — template generation flips to the light shape (D11)`; the review fix was amended into it — SHA supersedes the pre-review `86d547311`). Micro-decisions appended below.++**Review round 1** — Sonnet-5 `pr-review-toolkit:code-reviewer`, pointer-only (commit + diff, no plan/design/rationale). One **Important** finding + confirmation the rest is clean. Triage:++- **Important (APPLIED).** `pipelex-agent inputs --format toml` silently dropped the `# concept:` comments that the human `build inputs --format toml` writes — one surface got concept hints, the parallel surface didn't, with no test catching it (the agent-TOML test mocked `inputs_core`, and the golden test called `render_inputs_toml` directly, never the agent emit path). This reversed my earlier Phase-4 "deliberate asymmetry" micro-decision (format-follows-consumer): consistency between two documented-parallel surfaces wins, and an agent reading the TOML genuinely benefits from the hints. **Fix:** promoted `_concept_comments` → public `build_concept_comments`; `build_inputs_for_pipe` now returns a `concept_comments` map in its result; `emit_inputs_result` **pops** it (so the JSON envelope stays the plain `success`/`pipe_code`/`inputs` shape — no contract change, respecting the design's "JSON has no comments → use `--explicit`" stance) and passes it to the light-TOML serializer. Two new tests cover it (agent TOML carries comments; JSON strips the internal key). Verified real-binary. `test_inputs_ops` fixture/assertion updated for the new result key.+- **No correctness/round-trip/over-engineering findings.** The reviewer traced every delighten arm against the shaper's actual re-wrap, confirmed inline-table TOML validity + ordering, no import cycle, and the extra-required-fields envelope fallback. It flagged one pre-existing quirk (fixed-count `X[N]` always renders one example item) as **out of scope** — present at parent `d73d1aa3c`, in the unchanged shared envelope generator. Not deferred as new (already how the generator works).+- One doubt captured mid-implementation as a deferred note: `wip/inputs/d4-hint-still-envelope.md` (the D4 shaping-error "Expected shape:" hint still renders the envelope while templates default to light — recommendation: leave-it; a layer/cycle concern to weigh in Phase 5).++---++## Phase 5 — Docs, changelog, deferred-notes triage, wrap + finalize review++- [x] **Docs.** Rewrite `docs/building-methods/pipes/provide-inputs.md` (it shrinks dramatically — "just provide the values", envelope demoted to the escape hatch); update `docs/tools/cli/run.md`, `build/inputs.md`, and the agent-CLI inputs docs for the light-template default + `--explicit`.+- [x] **Triage the deferred notes Smart Inputs was meant to unify** — for each, apply-and-delete or re-defer with a reason: `scalar-envelope-arm-asymmetry.md` (str arm should now preserve a refining concept's subclass, like the bool arm — unify in the shaper); `loader-vs-factory-date-split-duplication.md` (the top-level-literal conversion and per-concept shaping collapse into the shaper's Date arm); `case1-bare-date-arm-gap.md` (a top-level array of date literals should now build `ListContent[DateContent]` via D2 + the shaper); `d4-hint-still-envelope.md` (Phase-4: the shaping-error "Expected shape:" hint still renders the envelope while templates default to light — recommendation there is leave-it unless it confuses); note `container-default-temporal-codegen-gap.md`, `structure-field-fidelity-guard.md`, `refines-hint-native-list-drift.md` as still-out-of-scope (structure-field codegen / release-wave authoring sweep) unless naturally touched.+- [x] **Changelog** under `[Unreleased]`: Smart Inputs — signature-driven input shaping (bare values accepted, declared-concept typing, envelope compat-checked, unknown-name detection). Breaking where it narrows (D8). No `wip/` mentions.+- [x] **Bookkeeping.** Update `wip/inputs/README.md` (Smart Inputs → done; the track's remaining work is the one release-cut cross-repo wave) and archive this file to `wip/inputs/smart-inputs-implementation-plan.md`.+- [x] Full `make agent-check` + `make agent-test` green.++### CHECKPOINT 5 — track complete; finalize review++Run the checkpoint protocol, **plus** the finalize **gstack `/review`** (Opus fan-out: testing + maintainability + adversarial-red-team, each pointer-only) — **user-gated: do not launch it unprompted.** Then the track is ready for the release wave.++State: **REACHED (2026-07-08).** Smart Inputs track complete. **Docs** rewritten around the light "just provide the values" model — `provide-inputs.md` shrank dramatically (envelope demoted to a compat-checked escape hatch), with `build/inputs.md`, `run.md`, the agent-CLI `inputs` docs, and the adjacent `executing-pipelines.md` / `csv-input-and-output.md` updated for the light default + `--explicit`; two **pre-existing** doc bugs fixed in passing (`run.md`'s stale "TOML datetimes not supported" warning now that Date shipped; `executing-pipelines.md`'s wrong `results/inputs.json` claim for `build inputs bundle`). **Deferred-notes triage** done — `case1-bare-date-arm-gap` **resolved by the shaper** (pinned), the rest re-deferred / leave-it with refreshed reasoning; full rollup in `wip/inputs/README.md`. **Changelog**: Smart Inputs umbrella entry under `[Unreleased] → Added` + the template-default flip under `Changed` (breaking narrowings noted). Gates: `make agent-check` green (pyright 0 / mypy Success / cko PASSED), full `make agent-test` **green** (re-run green after the review fix). This file is archived to `wip/inputs/smart-inputs-implementation-plan.md` as the as-built record.++**Review round 1** — independent Sonnet-5 doc-accuracy review, pointer-only (working-tree diff + the shaper/CLI/loader source to verify against; no plan / design / rationale). It confirmed the light templates are byte-accurate and every flag / default / error-message matches the code, and surfaced **one genuine silent-failure**: an explicit `ListContent` (or envelope-with-list) handed to a **singular**-declared input was *silently* stored into the singular slot — a D2 violation on the escape-hatch path (Gap A of `input-shaper-multiplicity-gaps.md`). That was exactly the reopen trigger the deferred note recorded, so I **applied the unambiguous half**: `_shape_explicit` now reconciles a built `ListContent` against multiplicity (`ListWhereSingularError` / `MultiplicityCountMismatchError`) via a shared new `_peel_multiplicity` helper, pinned by three new `test_explicit_forms.py` cases; PR #1033 later added the `native.Dynamic` carve-out so this guard does not overrule the bottom-up Dynamic fallback. The auto-wrap sub-question and the broader Dynamic-arm gap (Gap B) stay deferred as the genuine tradeoffs. All other findings were doc-accuracy fixes (the structurally-wrong TOML `--explicit` fragment, the "array of envelope items" mischaracterization, example keys dropped from the unknown-name / explicit examples, a bare-scalar-in-typed-Python caveat for the not-yet-widened protocol type, and `run.md` reframed light-first) — applied. Gates re-run green after the fix.++**Finalize gstack `/review` (Opus fan-out): NOT run — user-gated.** Awaiting the user's go-ahead; then the track is ready for the release wave (D10 protocol widening + the cross-repo mirrors, per `wip/inputs/README.md`).++---++## Deferred / release-wave sweep — NOT this plan's scope (listed so nothing is lost)++Shared per-release wave with YesNo + Date (see `wip/inputs/README.md`), done once, not per-feature:++- **D10 protocol widening** — `mthds/protocol/pipeline_inputs.py` `StuffContentOrData` widens to admit bare scalars / lists-of-dicts / empty lists (converges to "any JSON value | StuffContent forms"), with the interpretation semantics spec'd MTHDS-side (`docs/specs/` + the `mthds` repo). Release-gated (Optionals/TOML-inputs de-gate pattern). Runtime already works; this is type-honesty for typed callers.+- **Downstream mirrors** — `mthds-python` + `mthds-js` `PipelineInputs` types, conformance rows, JSON schema copies (`mthds-schema-sync` skill), MTHDS spec native-concept + inputs-format sections.+- **Authoring-guidance surfaces** — `mthds-plugins` skills (`mthds-inputs`, `mthds-build`), `vscode-pipelex` completion lists, and the `ConceptSpec.refines` native-list hint (derive from `NativeConceptCode` — `refines-hint-native-list-drift.md`).+- **Off critical path** — LLM-assisted input adaptation (design §8, opt-in); the shared YesNo/Date scalar-native LLM-output ergonomics.++---++## Micro-decisions log++_(append settled decisions here as phases land — mirrors the Date/YesNo plans)_++- Shaper location & shape: **module `pipelex/core/memory/input_shaper.py`, class `InputShaper`** (design D7). Reuses `StuffContentFactory` / `is_compatible` / the existing `StuffFactory` fallback — the new code is only the top-down dispatch.+- Concept-nature resolution: **a local `resolve_input_kind(concept) -> InputKind` in the shaper**, composed from ordered `is_compatible(…, strict=True)` checks (no in-tree "which family" helper exists to reuse).+- D8 home: **the shaper** (holds both provided dict and specs). Severity **error** by default (see Gaps).+- D10: **not a blocker** — `PipelineInputs` is a runtime-unvalidated `TypeAlias`, so bare scalars reach the shaper at runtime; the widening is release-gated type-honesty.+- Out-of-matrix natives (Html/JSON/Page/TextAndImages/SearchResult/Composite): **bottom-up fallback** (see Gaps — confirm).+- D3 path resolution: **signature-aware CLI resolver** recommended; exact mechanism settled as Phase 3's first task (see Gaps).++**Phase 1 (2026-07-07) — settled while building the shaper:**++- **Explicit forms unified into one post-hoc-compat path.** Envelope `{concept, content}` dict, `DictStuff`, and directly-provided `StuffContent`/`ListContent` all route to one `_shape_explicit`: build via `StuffFactory.make_stuff_from_stuff_content_or_data` (today's behavior, so the explicit — possibly more-specific — concept wins), then `is_compatible(tested=built.concept, wanted=declared)`; incompatible → D4 `ExplicitConceptIncompatibleError`. Chosen over pre-resolving the envelope's concept ref because `DictStuff.concept` may be a `DictConcept` object, not a str — pre-resolution was fragile. Trade-off: an envelope naming a concept that is *both* incompatible *and* unbuildable surfaces StuffFactory's build error first (not D4); the buildable-but-incompatible case (the interesting one) gives D4. Acceptable.+- **Scalar building via canonical-dict-wrap — zero changes to `StuffContentFactory`.** Each arm wraps the bare value into the structure class's canonical field dict (`{"text": v}` / `{"number": v}` / `{"url": v}`; date/str and bool passed through directly since `make_content_from_value` already honors those), then calls `StuffContentFactory.make_stuff_content_from_concept_required(concept, value=…)`. This makes a Text/Number-**refining** subclass build correctly (e.g. `Question(text=…)`, `Priority(number=…)`) without touching `make_content_from_value` (whose str-arm still uses `== TextContent`, not `issubclass`). Consequence: the `scalar-envelope-arm-asymmetry.md` note stays deferred — the shaper's **bare** path now builds the refining subclass, but the **envelope** escape hatch still delegates to `StuffFactory` Case 2.1c which builds a plain `TextContent` (concept kept, content not the subclass). Flag for Phase 5 triage.+- **`value` typed `Any` inside the shaper.** The public `shape(pipeline_inputs: PipelineInputs, …)` keeps the declared contract, but internal value params are `Any` because the runtime admits bare `int`/`float`/`bool`/`None`/list-of-dicts that the narrow `PipelineInputs`/`StuffContentOrData` alias does not (D10 widening is release-gated). This is what lets the D9 null guard and the Number/scalar arms be reachable without pyright flagging them unreachable.+- **`InputKind` keeps a `DYNAMIC` member; the per-item builder has one guarded unreachable branch.** `_shape_one` short-circuits `DYNAMIC` to the bottom-up factory before multiplicity peeling, so `_build_item_content` never sees `DYNAMIC` — but its `match` over `InputKind` stays exhaustive (house rule: no `case _`) with a `DYNAMIC` arm that raises `PipelexUnexpectedError`. Justified exhaustive-match guard, not an impossible-input guard on caller data.+- **`resolve_input_kind` order:** `is_dynamic_concept` short-circuit → ordered strict `is_compatible` against YesNo, Date, Number, Image, Document, Text (mutually exclusive natives, order safe) → non-native `StructuredContent` subclass → `STRUCTURED`; else `DYNAMIC` (covers out-of-matrix natives Html/JSON/Page/TextAndImages/SearchResult/Composite/Anything and any unregistered class, via a `ConceptValueError` catch).++**Phase 2 (2026-07-07) — settled while wiring the seam:**++- **One seam, `pipe.inputs` (not `needed_inputs()`).** `make_from_pipeline_inputs` gained `input_specs: InputStuffSpecs | None = None`; `prepare_pipe_job` passes `input_specs=pipe.inputs` — the method-boundary contract, matching the Optionals pass. `make_from_pipeline_inputs` has exactly one production caller (the seam); every other caller is a test that omits `input_specs` and keeps the bottom-up loop. So wiring that one call gives D1 (all surfaces: validate / real-run / dry-run) for free. `None` → today's bottom-up loop verbatim (regression-pinned); present → `InputShaper.shape`. `InputShaper` is a top-level import in `working_memory_factory` — no cycle (its closure never re-imports `working_memory_factory`).+- **D8 broke nothing.** Turning unknown-name detection live caused **zero** fallout across the full suite — no in-tree bundle/fixture relied on silently-ignored extra inputs. The design's "loud beats silent" default holds without any fixture loosening.+- **Envelope-CSV through the runner stays green.** The CSV full-pipeline e2e feeds the `{"concept": "csv_demo.Person", "content": {"url": "…csv"}}` **envelope**, which routes through `_shape_explicit` → bottom-up `StuffFactory` (today's CSV codec) → concept compat-check. Bare-`{"url": …}`-under-`Person[]` CSV (no envelope) is the Phase-3 arm; Phase 2 does not touch it, so no CSV regression.+- **Shaping errors reach the caller raw.** `prepare_pipe_job` runs under `pipeline_run_setup`'s `try/finally` (no wrapping `except`), and `runner.execute`'s `except PipelexError` re-raises when `pipe_job is None` (setup-time failure) — so a D4/D8 `InputShapingError` surfaces to the caller unwrapped (the e2e error tests assert on the raw class + message).+- **Phase-1 test-isolation bug fixed here (was the only full-suite red).** The shaper's structured test concepts (`Invoice`/`Person`/`Weird`) collided by **bare class name** in the shared, name-keyed class registry with an integration test's `Person(role)`/`Invoice` (first-registration-wins → the wrong class shadowed the shaper's, failing 3 tests only under the full suite). Fix: `Shaper`-prefix both the class name **and** the concept code (they must match — the bottom-up factory maps a prebuilt `StuffContent` to its concept by class name; concept codes are domain-qualified so they never collide, only the class-registry name did). Proven by running the colliding integration suite + shaper unit suite in one process (`-n0`) → all green. **Supersedes the memory note's "pre-existing full-suite fail" — that is now resolved.**++**Phase 3 (2026-07-07) — settled while adding file-ish + CSV-by-signature:**++- **D3 mechanism = `inputs_base_dir` threaded into the shaper (NOT the signature-aware CLI resolver).** The plan offered two options; chose threading a `Path | None` base_dir through the seam (`InputShaper.shape` → `make_from_pipeline_inputs` → `prepare_pipe_job` → `pipeline_run_setup` → runner ctor → both CLIs), `None` for API/SDK/in-process callers. Rejected the CLI-resolver-signature-aware alternative (which the gap doc had *recommended*) for three concrete reasons discovered at implementation: (1) it would force the CLI to resolve the pipe / load the library BEFORE the runner call just to see `pipe.inputs` — a real reordering in `_run_core.py`; (2) it would duplicate the shaper's `resolve_input_kind` concept-nature detection inside the CLI (which native family is Image/Document?) — drift risk; (3) it does **not** naturally cover the CSV-relative-path case (CSV rows aren't Image/Document), so path resolution would end up split across two places. Threading base_dir into the shaper keeps ONE resolution point that covers both D3 and D11. This is *not* "base_dir leaking into core" in the harmful sense — it is an optional param the shaper's file-ish/CSV arms consult; the resolution helper (`is_relative_local_path` + `base_dir / url`) lives in the shaper (core/memory), which already owns the building.+- **`is_relative_local_path` promoted to `pipelex/tools/uri/uri_resolver.py`.** It was a private helper in the CLI's `_inputs_path_resolver.py`; the shaper needs the same predicate, so it moved to the shared uri module (no re-export; both the CLI resolver and the shaper import it directly). Behavior byte-identical (same `://`-scheme stopgap for `s3://`/`gs://`).+- **CSV builder extracted, not duplicated.** `StuffFactory._try_make_csv_list_stuff` (returns a `Stuff`, Case-2.5 envelope path) split into a public `try_make_csv_list_content(concept, *, content, name) -> ListContent | None` (returns the *content*), with `_try_make_csv_list_stuff` now a thin `make_stuff` wrapper. The shaper's `_try_shape_csv` calls the content version. Case 2.5 behavior is byte-identical (same detection gates, same `CsvError` redaction). The shaper resolves a relative CSV path against `inputs_base_dir` BEFORE calling in, so the factory's own local-only gates operate on an already-resolved path.+- **CSV detection lives in the multiplicity peel, before element-wise shaping.** `_shape_with_multiplicity` now peels `(is_list, fixed_count)` once up front (cleaner than the old two-branch int/bool dance — and it dodged a pyright `reportUnnecessaryIsInstance` that surfaced once `multiplicity` was narrowed non-None). For a structured LIST input it tries CSV first; a bare tabular string or exact `{"url": <tabular>}` becomes `ListContent[row]`, and `fixed_count` is re-checked against the row count (→ `MultiplicityCountMismatchError`). A non-tabular / sibling-keyed / singular value returns `None` from `_try_shape_csv` and falls through to normal shaping (so `people.txt` under `Person[]` → `WrongScalarKindError`, a CSV under singular `Person` → `WrongScalarKindError`). Added `InputKind.is_structured` (exhaustive `match`, no `case _`) as the gate.+- **`parse_cli_inputs` now returns `ParsedCliInputs` (NamedTuple), never a bare dict.** `(pipeline_inputs: dict | None, inputs_base_dir: Path | None)`. The file-load branch (and auto-detected default file) carries the file's parent dir; inline-JSON and stdin carry `None` (no anchoring file → CWD contract preserved). NamedTuple is the right shape per standards (small fixed record, never serialized, in-process CLI→runner only). Blast radius: the three run command callers (`pipe_cmd`/`bundle_cmd`/`method_cmd`) read `.pipeline_inputs` + thread `.inputs_base_dir` into `run_pipeline_core`→runner ctor; the API-runner path ignores base_dir (API callers pass absolute urls); ~20 existing `test_stdin_resolver` assertions rewrote `result ==`→`result.pipeline_inputs ==`; three mocks that returned `None` for `parse_cli_inputs` became `ParsedCliInputs(None, None)`.+- **e2e disables data-url→storage normalization to assert the resolved path.** `is_normalize_data_urls_to_storage` is on in the test env; after the shaper resolves a bare relative Image path to an absolute filesystem path, normalization rewrites it to a `pipelex-storage://…` URI (a legitimate downstream step). The e2e builds an execution_config with normalization off so the assertion can pin the exact D3-resolved filesystem path — the resolution is what this phase must prove, not the normalization.++**Phase 4 (2026-07-07) — settled while flipping template generation to the light shape:**++- **Mechanism = post-hoc delighten transform at the `input_renderer` layer, NOT a flag threaded through `Concept.render_concept_representation`.** The plan proposed threading an `explicit` bool through the whole render chain (`build_inputs_template` / `render_stuff_spec` / `render_concept_representation`) and gating the envelope wrapping there. Rejected for a cleaner design discovered at implementation: `render_concept_representation` / `render_stuff_spec` / `InputStuffSpecs.build_inputs_template` are **shared** by outputs, JSON-schema, and runner-code generation — the light/explicit choice is an *input-template presentation* concern that has no business in those general-purpose methods. So they stay untouched (single-purpose envelope generators), and `input_renderer.build_inputs_template(explicit=…)` builds the envelope as today, then — when light — unwraps each entry per the declared concept's kind. Smaller blast radius (only `input_renderer` + the two CLIs + `inputs_ops`), cleaner separation, and still DRY: the unwrap reuses `InputShaper.resolve_input_kind` (the single source of truth from Phase 1), it does **not** duplicate concept-nature classification. Import is top-level (`input_renderer` → `input_shaper`); no cycle (nothing in the shaper's closure imports `input_renderer`; `make tb` green).+- **The delighten arms mirror the shaper's arms exactly (round-trip guarantee).** `_delighten_entry(entry, *, kind)`: DYNAMIC → keep the whole envelope (bottom-up shaping genuinely needs it — a bare value for an out-of-matrix native like Html would be mis-built); STRUCTURED → the content dict verbatim (`dict` or `[dict]` for a list); scalar (TEXT/NUMBER/YES_NO/DATE/IMAGE/DOCUMENT) → unwrap the single content field element-wise. Because the generator (`include_optional=False`) emits exactly one required field for every scalar native (`{text}`/`{number}`/`{url}`/`{date}`/`{yes_no}`), and the shaper re-wraps that same bare value, the light template is exactly what the shaper accepts. A scalar content that is *not* a single-field dict (a refining scalar with extra required fields — which the shaper can't build from a bare value anyway) **keeps its envelope** so the template still runs (the `_unwrap_scalar_content` fallback). `match` over `InputKind` is exhaustive (no `case _`).+- **Light TOML uses inline tables to dodge the ordering footgun.** Envelope templates are all-tables, so `tomlkit.dumps` (today's path, `light=False`) is order-safe and unchanged — existing TOML tests pass verbatim. But a **light** template interleaves bare top-level scalars with structured values; a `[section]` table emitted before a trailing bare scalar would swallow that scalar. So `serialize_inputs_template_to_toml(light=True)` renders every dict/list value as an **inline table / array-of-inline-tables** (`_to_toml_value`), keeping everything at the top level in declaration order, and attaches the `# concept: <bundle_representation>` comment (with `[]`/`?`/`!` suffixes) per key via a `tomlkit.document()`. Multi-line strings are a non-issue: the generator only emits single-line `{field}_value` placeholders, so no inline-table newline hazard in practice.+- **Agent-CLI TOML carries concept comments too (settled via review round 1 — my first cut had it NOT, that asymmetry was reversed).** Both `pipelex build inputs --format toml` and `pipelex-agent inputs --format toml` now emit the `# concept:` comment per key. My initial "format-follows-consumer" argument for dropping them on the agent stream was weaker than plain consistency between two documented-parallel surfaces (and an agent reading the TOML benefits from the hints). Implementation: `build_concept_comments` (public in `input_renderer`) is called by both `render_inputs_toml` (human) and `build_inputs_for_pipe` (agent, returns the map in its result under `concept_comments`); `emit_inputs_result` **pops** that map before the JSON `agent_success` so the **agent-CLI JSON contract is unchanged** (plain `success`/`pipe_code`/`inputs`, `inputs` flipped envelope→light) and passes it to the light-TOML serializer. The JSON-stays-pure choice respects the design's stance ("JSON has no comments → `--explicit` teaches concepts"); the sidecar map is internal plumbing, never emitted as JSON.+- **`build_inputs_for_pipe(explicit=False)` default = light everywhere.** The agent CLI's `inputs` result field is now the light template by default (verified real-binary). The module-level `input_renderer.{build_inputs_template,render_inputs,render_inputs_toml}` all default `explicit=False` (they are input-template-specific; the envelope-producing method `InputStuffSpecs.build_inputs_template()` is what they wrap and is untouched). Existing-test fallout was minimal: `test_inputs_ops::test_happy_path_return_shape` call-arg assertion (`render_inputs(..., explicit=False)`) and the `test_toml_inputs_build` e2e (rewritten to assert the light default + a new `--explicit` case) — both genuine behavior updates, not test-encoded-old-mistakes.++**Phase 5 (2026-07-08) — settled while finalizing (docs / triage / review):**++- **Docs lead with the light model; the bottom-up Case 1.x/2.x enumeration is dropped as the user-facing frame.** `provide-inputs.md` was rewritten top-down ("provide the values that match the signature"), with the `{concept, content}` envelope demoted to a compat-checked escape-hatch section. The old Case 1.1–2.6 catalogue was the `StuffContentOrData` *protocol* contract — still true underneath (Dynamic + explicit forms use it), but no longer the teaching surface. Search-domain concept-name resolution moved *under* the escape hatch, because a bare light value takes its concept from the signature — there is no name to resolve on the fast path.+- **Gap A's unambiguous half was fixed (not deferred), triggered by the finalize review.** The pointer-only doc-accuracy review re-found the explicit-`ListContent`-into-singular *silent store* as a D2 violation — exactly the reopen criterion `input-shaper-multiplicity-gaps.md` had recorded. So `_shape_explicit` now reconciles a built `ListContent` against `stuff_spec.multiplicity` (reject list-into-singular for shaped concepts; enforce the `[N]` count), and the multiplicity peel was extracted to a shared `_peel_multiplicity` so the explicit reconcile and the bare-value path use one classification (no duplication). PR #1033 added the `native.Dynamic` carve-out so explicit `ListContent` preserves the same bottom-up fallback as raw lists in Dynamic slots. The auto-wrap sub-question (explicit singular under `[]`) and the broader Gap B (`DYNAMIC` multiplicity peeling for `Dynamic[]`/`Anything[N]`) stay deferred as the genuine design tradeoffs.+- **Pre-existing doc bugs fixed in-scope** (CLAUDE.md "flag and fix existing bugs"): `run.md`'s stale "TOML datetimes are not supported yet" warning (Date shipped on this branch), and `executing-pipelines.md`'s claim that `build inputs bundle` writes `results/inputs.json` (it writes next to the bundle; the `results/` default is the `build inputs pipe` behavior).+- **Bare scalars from strictly-typed Python get a caveat, not a silent overclaim.** The `PipelineInputs` / `StuffContentOrData` alias is not yet widened for bare `int`/`float`/`bool` (D10, release-gated), so a strict type-checker flags `"priority": 3`. The Python-API doc notes this (use `dict[str, Any]` or the envelope) rather than pretending it type-checks today.diff --git a/wip/inputs/smart-inputs-pr1028-explainer.html b/wip/inputs/smart-inputs-pr1028-explainer.htmlnew file mode 100644index 000000000..542206cf1--- /dev/null+++ b/wip/inputs/smart-inputs-pr1028-explainer.html@@ -0,0 +1,968 @@+<!doctype html>+<html lang="en">+<head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <title>PR 1028 - Native YesNo, Native Date, and Smart Inputs</title>+ <style>+ :root {+ --ink: #151923;+ --muted: #5d6678;+ --faint: #eef1f6;+ --panel: #ffffff;+ --panel-soft: #f8fafc;+ --line: #d9dee8;+ --blue: #2458d3;+ --green: #147557;+ --amber: #8a5a00;+ --red: #b42318;+ --code-bg: #101623;+ --code-ink: #e8eefc;+ --shadow: 0 12px 36px rgba(16, 24, 40, 0.09);+ }++ * {+ box-sizing: border-box;+ }++ body {+ margin: 0;+ color: var(--ink);+ background:+ linear-gradient(180deg, #f4f7fb 0%, #ffffff 42%),+ #ffffff;+ font-family:+ Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",+ sans-serif;+ line-height: 1.5;+ }++ a {+ color: var(--blue);+ text-decoration: none;+ font-weight: 650;+ }++ a:hover {+ text-decoration: underline;+ }++ .shell {+ width: min(1180px, calc(100vw - 36px));+ margin: 0 auto;+ }++ header {+ padding: 44px 0 26px;+ }++ .eyebrow {+ margin: 0 0 10px;+ color: var(--green);+ font-size: 0.78rem;+ font-weight: 800;+ letter-spacing: 0.08em;+ text-transform: uppercase;+ }++ h1 {+ max-width: 920px;+ margin: 0;+ font-size: clamp(2.1rem, 5vw, 4.7rem);+ line-height: 0.96;+ letter-spacing: 0;+ }++ .subtitle {+ max-width: 820px;+ margin: 18px 0 0;+ color: var(--muted);+ font-size: 1.15rem;+ }++ .meta {+ display: flex;+ flex-wrap: wrap;+ gap: 10px;+ margin-top: 22px;+ }++ .pill {+ display: inline-flex;+ align-items: center;+ gap: 7px;+ min-height: 32px;+ padding: 6px 10px;+ border: 1px solid var(--line);+ border-radius: 999px;+ background: rgba(255, 255, 255, 0.76);+ color: #323b4c;+ font-size: 0.88rem;+ font-weight: 650;+ }++ .hero-grid {+ display: grid;+ grid-template-columns: 1.1fr 0.9fr;+ gap: 22px;+ align-items: stretch;+ margin: 22px 0 34px;+ }++ .panel {+ border: 1px solid var(--line);+ border-radius: 8px;+ background: var(--panel);+ box-shadow: var(--shadow);+ }++ .panel-pad {+ padding: 22px;+ }++ .tldr {+ border-left: 5px solid var(--green);+ }++ .tldr h2,+ section h2 {+ margin: 0 0 12px;+ font-size: 1.36rem;+ letter-spacing: 0;+ }++ .tldr p {+ margin: 0;+ font-size: 1.1rem;+ }++ .tldr strong {+ color: var(--green);+ }++ .stats {+ display: grid;+ grid-template-columns: repeat(2, minmax(0, 1fr));+ gap: 10px;+ height: 100%;+ }++ .stat {+ padding: 16px;+ border: 1px solid var(--line);+ border-radius: 8px;+ background: var(--panel-soft);+ }++ .stat b {+ display: block;+ margin-bottom: 4px;+ font-size: 1.45rem;+ line-height: 1;+ }++ .stat span {+ color: var(--muted);+ font-size: 0.92rem;+ }++ section {+ margin: 36px 0;+ }++ .section-lead {+ max-width: 820px;+ margin: 0 0 16px;+ color: var(--muted);+ }++ .before-after {+ display: grid;+ grid-template-columns: repeat(3, minmax(0, 1fr));+ gap: 16px;+ }++ .before-after .side {+ border: 1px solid var(--line);+ border-radius: 8px;+ overflow: hidden;+ background: var(--panel);+ }++ .side h3 {+ display: flex;+ align-items: center;+ justify-content: space-between;+ gap: 10px;+ margin: 0;+ padding: 14px 16px;+ border-bottom: 1px solid var(--line);+ background: #f9fafc;+ font-size: 1.02rem;+ }++ .side.before h3 {+ color: var(--red);+ }++ .side.after h3 {+ color: var(--green);+ }++ .side-body {+ padding: 16px;+ }++ .plain-list {+ margin: 0;+ padding-left: 20px;+ }++ .plain-list li {+ margin: 7px 0;+ }++ .value-grid {+ display: grid;+ grid-template-columns: repeat(3, minmax(0, 1fr));+ gap: 14px;+ }++ .value-card {+ border: 1px solid var(--line);+ border-radius: 8px;+ background: var(--panel);+ padding: 18px;+ }++ .value-card h3 {+ margin: 0 0 8px;+ font-size: 1.05rem;+ }++ .value-card p {+ margin: 0;+ color: var(--muted);+ }++ .two-col {+ display: grid;+ grid-template-columns: 1fr 1fr;+ gap: 16px;+ align-items: start;+ }++ .diagram-card {+ border: 1px solid var(--line);+ border-radius: 8px;+ background: var(--panel);+ padding: 18px;+ overflow: auto;+ }++ .diagram-card h3 {+ margin: 0 0 12px;+ font-size: 1rem;+ }++ .flow-svg {+ width: 100%;+ min-width: 540px;+ height: auto;+ display: block;+ }++ .mermaid {+ margin: 0;+ padding: 0;+ color: var(--ink);+ background: transparent;+ font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;+ font-size: 0.88rem;+ white-space: pre;+ }++ pre {+ margin: 12px 0 0;+ overflow: auto;+ border-radius: 8px;+ background: var(--code-bg);+ color: var(--code-ink);+ font-size: 0.84rem;+ line-height: 1.48;+ }++ code {+ font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;+ }++ pre code {+ display: block;+ padding: 15px;+ }++ .diff .add {+ color: #7ee2a8;+ }++ .diff .del {+ color: #ff9b9b;+ }++ .diff .file {+ color: #99b8ff;+ }++ .diff .ctx {+ color: #b9c4d8;+ }++ .table-wrap {+ overflow: auto;+ border: 1px solid var(--line);+ border-radius: 8px;+ background: var(--panel);+ }++ table {+ width: 100%;+ min-width: 760px;+ border-collapse: collapse;+ font-size: 0.94rem;+ }++ th,+ td {+ padding: 12px 14px;+ border-bottom: 1px solid var(--line);+ text-align: left;+ vertical-align: top;+ }++ th {+ background: #f7f9fc;+ color: #333b4c;+ font-size: 0.78rem;+ letter-spacing: 0.06em;+ text-transform: uppercase;+ }++ tr:last-child td {+ border-bottom: 0;+ }++ .tag {+ display: inline-block;+ padding: 2px 8px;+ border-radius: 999px;+ background: #e8f2ff;+ color: #1a4bb8;+ font-size: 0.78rem;+ font-weight: 700;+ white-space: nowrap;+ }++ .tag.green {+ background: #e7f6ef;+ color: var(--green);+ }++ .tag.amber {+ background: #fff2d8;+ color: var(--amber);+ }++ details {+ border: 1px solid var(--line);+ border-radius: 8px;+ background: var(--panel);+ margin: 12px 0;+ overflow: hidden;+ }++ summary {+ cursor: pointer;+ padding: 14px 16px;+ background: #f8fafc;+ font-weight: 760;+ }++ details > div {+ padding: 0 16px 16px;+ }++ .callout {+ border: 1px solid #c9ddff;+ border-left: 5px solid var(--blue);+ border-radius: 8px;+ background: #f3f7ff;+ padding: 16px;+ }++ .callout p {+ margin: 0;+ }++ .link-list {+ display: grid;+ grid-template-columns: repeat(2, minmax(0, 1fr));+ gap: 10px;+ }++ .link-card {+ border: 1px solid var(--line);+ border-radius: 8px;+ background: var(--panel);+ padding: 14px;+ }++ .link-card span {+ display: block;+ margin-top: 4px;+ color: var(--muted);+ font-size: 0.9rem;+ }++ footer {+ margin: 48px 0 34px;+ padding-top: 18px;+ border-top: 1px solid var(--line);+ color: var(--muted);+ font-size: 0.9rem;+ }++ @media (max-width: 900px) {+ .hero-grid,+ .before-after,+ .value-grid,+ .two-col,+ .link-list {+ grid-template-columns: 1fr;+ }++ .stats {+ grid-template-columns: 1fr 1fr;+ }+ }++ @media (max-width: 560px) {+ .shell {+ width: min(100vw - 24px, 1180px);+ }++ header {+ padding-top: 26px;+ }++ .stats {+ grid-template-columns: 1fr;+ }++ .panel-pad {+ padding: 16px;+ }+ }+ </style>+</head>+<body>+ <header>+ <div class="shell">+ <p class="eyebrow">PR 1028 explainer</p>+ <h1>Smart Inputs: from protocol envelopes to plain business values.</h1>+ <p class="subtitle">+ Before this PR, users had to feed Pipelex inputs in Pipelex's internal shape. After this PR, they provide the values they already have, and the pipe signature turns those values into typed working memory.+ </p>+ <div class="meta">+ <span class="pill">Branch: <code>feature/Smart-inputs</code></span>+ <span class="pill">Base: <code>dev</code></span>+ <span class="pill">Scope: native concepts + runner/CLI/API input seam</span>+ <span class="pill">Generated: 2026-07-08</span>+ </div>+ </div>+ </header>++ <main class="shell">+ <div class="hero-grid">+ <section class="panel panel-pad tldr" aria-labelledby="tldr-title">+ <h2 id="tldr-title">TL;DR</h2>+ <p>+ <strong>Before Smart Inputs:</strong> a caller had to know the ceremony: concept envelopes, content field names, file wrappers, and list shapes. <strong>After Smart Inputs:</strong> a caller gives Pipelex ordinary values like <code>"contract.pdf"</code>, <code>true</code>, <code>2026-07-07</code>, or rows from <code>people.csv</code>; Pipelex reads the declared signature, builds the right typed data, and fails loudly when the value cannot match the contract.+ </p>+ </section>++ <aside class="stats" aria-label="PR scope stats">+ <div class="stat">+ <b>Plain</b>+ <span>callers now provide business values, not Pipelex protocol envelopes</span>+ </div>+ <div class="stat">+ <b>1</b>+ <span>shared Smart Inputs seam across CLI, Python API, and hosted runner</span>+ </div>+ <div class="stat">+ <b>Typed</b>+ <span>values become declared concepts such as <code>Question</code>, <code>YesNo</code>, <code>Date</code>, <code>Document</code>, and structured rows</span>+ </div>+ <div class="stat">+ <b>Safer</b>+ <span>unknown names, bad scalar kinds, wrong list counts, nulls, and incompatible envelopes are typed errors</span>+ </div>+ </aside>+ </div>++ <section aria-labelledby="exec-before-after">+ <h2 id="exec-before-after">Before / After For Executives</h2>+ <p class="section-lead">+ The business change is simple: users now fill in the values they actually have. Pipelex owns the typing, validation, file resolution, and exact rendering.+ </p>++ <div class="before-after">+ <div class="side before">+ <h3>Before <span class="tag amber">protocol-shaped</span></h3>+ <div class="side-body">+ <ul class="plain-list">+ <li>Users had to understand Pipelex envelopes: <code>{"concept", "content"}</code>.</li>+ <li>A yes/no judgment could come back as text that callers had to parse.</li>+ <li>A calendar date could be forced into a datetime, quietly inventing midnight.</li>+ <li>Input names not declared by the pipe could be ignored silently.</li>+ <li>Generated templates did not look like the values accepted by <code>pipelex run</code>.</li>+ </ul>+ <pre><code>{+ "question": {+ "concept": "legal.Question",+ "content": { "text": "Does this contract include a penalty clause?" }+ },+ "verdict": {+ "concept": "YesNo",+ "content": { "yes_no": true }+ },+ "signed_on": {+ "concept": "Date",+ "content": { "date": "2026-07-07" }+ }+}</code></pre>+ </div>+ </div>++ <div class="side after">+ <h3>After JSON <span class="tag green">value-shaped</span></h3>+ <div class="side-body">+ <ul class="plain-list">+ <li>Users provide plain values; the pipe signature supplies the meaning.</li>+ <li><code>YesNo</code> is a real boolean concept with prompt rendering as <code>yes</code> or <code>no</code>.</li>+ <li><code>Date</code> stores a date and only stores time when the source states one.</li>+ <li>Unknown inputs, incompatible envelopes, nulls, wrong scalar kinds, and bad list counts fail with typed errors.</li>+ <li>The generated light template is the template you can fill and run.</li>+ </ul>+ <pre><code>{+ "question": "Does this contract include a penalty clause?",+ "verdict": true,+ "signed_on": "2026-07-07",+ "contract": "contract.pdf"+}</code></pre>+ </div>+ </div>++ <div class="side after">+ <h3>After TOML <span class="tag green">value-shaped</span></h3>+ <div class="side-body">+ <ul class="plain-list">+ <li>Same Smart Inputs model as JSON.</li>+ <li>TOML keeps the shape compact for editable input files.</li>+ <li>Date literals can stay native TOML dates.</li>+ <li>The file path stays a plain string.</li>+ </ul>+ <pre><code>question = "Does this contract include a penalty clause?"+verdict = true+signed_on = 2026-07-07+contract = "contract.pdf"</code></pre>+ </div>+ </div>+ </div>+ </section>++ <section aria-labelledby="what-built">+ <h2 id="what-built">What We Built</h2>+ <div class="value-grid">+ <article class="value-card">+ <h3>Native <code>YesNo</code></h3>+ <p>+ A built-in native concept backed by <code>YesNoContent</code>. It carries one strict boolean, renders as <code>yes</code>/<code>no</code>, and supports refinements like any other native concept.+ </p>+ </article>+ <article class="value-card">+ <h3>Native <code>Date</code></h3>+ <p>+ A built-in native concept backed by <code>DateContent</code>. It preserves source precision: date-only stays date-only; time and offset appear only when the source states them.+ </p>+ </article>+ <article class="value-card">+ <h3>Smart Inputs</h3>+ <p>+ A new <code>InputShaper</code> interprets caller input from the declared pipe signature, not from raw value shape alone. One seam covers CLI files, inline inputs, Python callers, and hosted runs.+ </p>+ </article>+ </div>+ </section>++ <section aria-labelledby="architecture">+ <h2 id="architecture">Architecture</h2>+ <p class="section-lead">+ The key decision: shaping is a runtime boundary concern, not a CLI feature. The CLI passes the inputs file base directory when it has one; the shared shaper decides how each value maps to the declared concept.+ </p>++ <div class="two-col">+ <div class="diagram-card">+ <h3>Smart Inputs flow (Mermaid)</h3>+ <pre class="mermaid">flowchart LR+ Caller["Caller input"]+ Surface["CLI / Python API / hosted runner"]+ Specs["Entry pipe input signature"]+ Shaper["InputShaper"]+ WM["WorkingMemory"]+ Pipe["Pipe execution"]++ Caller -- "plain values or explicit envelope" --> Surface+ Specs -- "declared concept, multiplicity, presence" --> Shaper+ Surface -- "PipelineInputs + optional inputs_base_dir" --> Shaper+ Shaper -- "typed Stuff / ListContent / errors" --> WM+ WM -- "rendered into prompts and operators" --> Pipe</pre>+ </div>++ <div class="diagram-card">+ <h3>Concept dispatch map (SVG)</h3>+ <svg class="flow-svg" viewBox="0 0 900 420" role="img" aria-labelledby="svg-title svg-desc">+ <title id="svg-title">Smart Inputs dispatch map</title>+ <desc id="svg-desc">A signature dispatch map from declared concepts to expected caller shapes.</desc>+ <defs>+ <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">+ <path d="M0,0 L0,6 L9,3 z" fill="#2458d3" />+ </marker>+ </defs>+ <rect x="24" y="28" width="210" height="60" rx="8" fill="#f3f7ff" stroke="#b7c9f7" />+ <text x="129" y="54" text-anchor="middle" font-size="17" font-weight="700" fill="#151923">Declared input</text>+ <text x="129" y="76" text-anchor="middle" font-size="13" fill="#5d6678">from pipe signature</text>++ <rect x="334" y="28" width="230" height="60" rx="8" fill="#eefaf4" stroke="#addcc8" />+ <text x="449" y="54" text-anchor="middle" font-size="17" font-weight="700" fill="#151923">InputShaper</text>+ <text x="449" y="76" text-anchor="middle" font-size="13" fill="#5d6678">one shared dispatch point</text>++ <rect x="666" y="28" width="210" height="60" rx="8" fill="#fff8eb" stroke="#f0ce8d" />+ <text x="771" y="54" text-anchor="middle" font-size="17" font-weight="700" fill="#151923">Typed Stuff</text>+ <text x="771" y="76" text-anchor="middle" font-size="13" fill="#5d6678">or typed shaping error</text>++ <line x1="234" y1="58" x2="334" y2="58" stroke="#2458d3" stroke-width="2.4" marker-end="url(#arrow)" />+ <line x1="564" y1="58" x2="666" y2="58" stroke="#2458d3" stroke-width="2.4" marker-end="url(#arrow)" />++ <g font-size="14" fill="#151923">+ <rect x="60" y="142" width="190" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="155" y="170" text-anchor="middle">Text-refining</text>+ <line x1="250" y1="164" x2="366" y2="164" stroke="#2458d3" stroke-width="2" marker-end="url(#arrow)" />+ <rect x="366" y="142" width="190" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="461" y="170" text-anchor="middle">bare string</text>+ <line x1="556" y1="164" x2="672" y2="164" stroke="#2458d3" stroke-width="2" marker-end="url(#arrow)" />+ <rect x="672" y="142" width="168" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="756" y="170" text-anchor="middle">declared concept</text>++ <rect x="60" y="205" width="190" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="155" y="233" text-anchor="middle">YesNo-refining</text>+ <line x1="250" y1="227" x2="366" y2="227" stroke="#2458d3" stroke-width="2" marker-end="url(#arrow)" />+ <rect x="366" y="205" width="190" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="461" y="233" text-anchor="middle">bare boolean</text>+ <line x1="556" y1="227" x2="672" y2="227" stroke="#2458d3" stroke-width="2" marker-end="url(#arrow)" />+ <rect x="672" y="205" width="168" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="756" y="233" text-anchor="middle">YesNoContent</text>++ <rect x="60" y="268" width="190" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="155" y="296" text-anchor="middle">Date-refining</text>+ <line x1="250" y1="290" x2="366" y2="290" stroke="#2458d3" stroke-width="2" marker-end="url(#arrow)" />+ <rect x="366" y="268" width="190" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="461" y="296" text-anchor="middle">ISO date or TOML date</text>+ <line x1="556" y1="290" x2="672" y2="290" stroke="#2458d3" stroke-width="2" marker-end="url(#arrow)" />+ <rect x="672" y="268" width="168" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="756" y="296" text-anchor="middle">DateContent</text>++ <rect x="60" y="331" width="190" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="155" y="359" text-anchor="middle">Document[] structure</text>+ <line x1="250" y1="353" x2="366" y2="353" stroke="#2458d3" stroke-width="2" marker-end="url(#arrow)" />+ <rect x="366" y="331" width="190" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="461" y="359" text-anchor="middle">path / CSV / list</text>+ <line x1="556" y1="353" x2="672" y2="353" stroke="#2458d3" stroke-width="2" marker-end="url(#arrow)" />+ <rect x="672" y="331" width="168" height="44" rx="8" fill="#ffffff" stroke="#d9dee8" />+ <text x="756" y="359" text-anchor="middle">ListContent</text>+ </g>+ </svg>+ </div>+ </div>+ </section>++ <section aria-labelledby="developer-impact">+ <h2 id="developer-impact">Developer Impact</h2>+ <div class="table-wrap">+ <table>+ <thead>+ <tr>+ <th>Area</th>+ <th>What changed</th>+ <th>Why co-developers should care</th>+ </tr>+ </thead>+ <tbody>+ <tr>+ <td><span class="tag green">Native data</span></td>+ <td><code>NativeConceptCode</code> now includes <code>YesNo</code> and <code>Date</code>, with corresponding content classes and rendering.</td>+ <td>No more local string conventions for two common extraction/judgment outputs.</td>+ </tr>+ <tr>+ <td><span class="tag green">Input shaping</span></td>+ <td><code>InputShaper</code> maps bare values to the declared concept, checks envelopes, applies multiplicity rules, and raises typed errors.</td>+ <td>Every surface gets the same behavior. A CLI fix is not stranded in the CLI.</td>+ </tr>+ <tr>+ <td><span class="tag">Files and tables</span></td>+ <td>Relative file-ish strings resolve against the inputs file directory; declared structured lists can accept a CSV path by signature.</td>+ <td>Common user artifacts, like <code>contract.pdf</code> and <code>people.csv</code>, become first-class inputs without wrappers.</td>+ </tr>+ <tr>+ <td><span class="tag">Templates</span></td>+ <td><code>build inputs</code> and <code>pipelex-agent inputs</code> default to the light shape; <code>--explicit</code> keeps the old envelope.</td>+ <td>Generated examples now teach the recommended model and round-trip into <code>run</code>.</td>+ </tr>+ <tr>+ <td><span class="tag amber">Breaking edge</span></td>+ <td><code>YesNo</code> and <code>Date</code> are reserved native concept codes; unknown inputs and top-level nulls are hard errors.</td>+ <td>Breakage is intentional: it removes silent wrong work and makes author mistakes visible at the boundary.</td>+ </tr>+ </tbody>+ </table>+ </div>+ </section>++ <section aria-labelledby="runtime-story">+ <h2 id="runtime-story">One Seam, All Surfaces</h2>+ <p class="section-lead">+ The implementation deliberately routes the behavior through working-memory construction. That keeps CLI, Python, agent CLI, and hosted runner behavior aligned.+ </p>++ <div class="callout">+ <p>+ The old bottom-up path remains when no signature is available. When a signature exists, Smart Inputs is opt-in by data: pass <code>input_specs</code> and the same <code>PipelineInputs</code> are shaped top-down.+ </p>+ </div>++ <pre><code>caller values + entry pipe signature+ -> WorkingMemoryFactory.make_from_pipeline_inputs(..., input_specs=...)+ -> InputShaper.shape(...)+ -> WorkingMemory full of typed Stuff+ -> normal pipe execution</code></pre>+ </section>++ <section aria-labelledby="critical-diff">+ <h2 id="critical-diff">Minimal Critical Diff</h2>+ <p class="section-lead">+ These are not exhaustive patches. They are the few lines that explain the architecture and product behavior.+ </p>++ <details open>+ <summary>1. Native concepts become first-class</summary>+ <div>+ <pre class="diff"><code><span class="file">pipelex/core/concepts/native/concept_native.py</span>+<span class="ctx"> class NativeConceptCode(StrEnum):</span>+<span class="add">+ YES_NO = "YesNo"</span>+<span class="add">+ DATE = "Date"</span>++<span class="ctx"> def structure_class(self) -> type[StuffContent]:</span>+<span class="add">+ case NativeConceptCode.YES_NO:</span>+<span class="add">+ return YesNoContent</span>+<span class="add">+ case NativeConceptCode.DATE:</span>+<span class="add">+ return DateContent</span></code></pre>+ </div>+ </details>++ <details>+ <summary>2. Date refuses fidelity loss</summary>+ <div>+ <pre class="diff"><code><span class="file">pipelex/core/stuffs/date_content.py</span>+<span class="add">+class DateContent(StuffContent):</span>+<span class="add">+ date: datetime.date</span>+<span class="add">+ time: datetime.time | None = None</span>++<span class="add">+ def to_datetime(self) -> datetime.datetime:</span>+<span class="add">+ if self.time is None:</span>+<span class="add">+ msg = "This Date has no time of day, so it cannot be converted to a datetime without inventing one."</span>+<span class="add">+ raise DateContentError(msg)</span>+<span class="add">+ return datetime.datetime.combine(self.date, self.time)</span></code></pre>+ </div>+ </details>++ <details>+ <summary>3. The shared seam calls the shaper when the signature is available</summary>+ <div>+ <pre class="diff"><code><span class="file">pipelex/core/memory/working_memory_factory.py</span>+<span class="ctx"> def make_from_pipeline_inputs(</span>+<span class="ctx"> pipeline_inputs: PipelineInputs,</span>+<span class="add">+ *,</span>+<span class="add">+ input_specs: InputStuffSpecs | None = None,</span>+<span class="add">+ inputs_base_dir: Path | None = None,</span>+<span class="ctx"> ) -> WorkingMemory:</span>+<span class="add">+ if input_specs is not None:</span>+<span class="add">+ return InputShaper.shape(</span>+<span class="add">+ pipeline_inputs,</span>+<span class="add">+ input_specs=input_specs,</span>+<span class="add">+ search_domain_codes=search_domain_codes,</span>+<span class="add">+ inputs_base_dir=inputs_base_dir,</span>+<span class="add">+ )</span></code></pre>+ </div>+ </details>++ <details>+ <summary>4. Top-down dispatch replaces shape guessing</summary>+ <div>+ <pre class="diff"><code><span class="file">pipelex/core/memory/input_shaper.py</span>+<span class="add">+input_kind = cls.resolve_input_kind(declared_concept)</span>+<span class="add">+match input_kind:</span>+<span class="add">+ case InputKind.TEXT:</span>+<span class="add">+ return cls._make_content(concept, value={"text": value}, ...)</span>+<span class="add">+ case InputKind.NUMBER:</span>+<span class="add">+ if isinstance(value, bool) or not isinstance(value, (int, float)):</span>+<span class="add">+ raise cls._wrong_kind(...)</span>+<span class="add">+ return cls._make_content(concept, value={"number": value}, ...)</span>+<span class="add">+ case InputKind.YES_NO:</span>+<span class="add">+ return cls._make_content(concept, value=value, ...)</span>+<span class="add">+ case InputKind.DATE:</span>+<span class="add">+ return cls._make_content(concept, value=value, ...)</span>+<span class="add">+ case InputKind.IMAGE | InputKind.DOCUMENT:</span>+<span class="add">+ canonical = {"url": cls._resolve_local_path(value, inputs_base_dir=inputs_base_dir)}</span>+<span class="add">+ case InputKind.STRUCTURED:</span>+<span class="add">+ return cls._make_content(concept, value=value, ...)</span></code></pre>+ </div>+ </details>++ <details>+ <summary>5. Generated templates flip to the light shape</summary>+ <div>+ <pre class="diff"><code><span class="file">pipelex/core/pipes/inputs/input_renderer.py</span>+<span class="del">-def build_inputs_template(the_pipe: PipeAbstract) -> dict[str, Any]:</span>+<span class="add">+def build_inputs_template(the_pipe: PipeAbstract, *, explicit: bool = False) -> dict[str, Any]:</span>+<span class="add">+ envelope_template = the_pipe.inputs.build_inputs_template()</span>+<span class="add">+ if explicit:</span>+<span class="add">+ return envelope_template</span>+<span class="add">+ return _delighten_template(envelope_template, input_specs=the_pipe.inputs)</span>++<span class="add">+def _delighten_entry(entry: dict[str, Any], *, kind: InputKind) -> Any:</span>+<span class="add">+ match kind:</span>+<span class="add">+ case InputKind.DYNAMIC:</span>+<span class="add">+ return entry</span>+<span class="add">+ case InputKind.STRUCTURED:</span>+<span class="add">+ return entry["content"]</span>+<span class="add">+ case InputKind.TEXT | InputKind.NUMBER | InputKind.YES_NO | InputKind.DATE | InputKind.IMAGE | InputKind.DOCUMENT:</span>+<span class="add">+ return _unwrap_scalar_content(entry["content"], envelope=entry)</span></code></pre>+ </div>+ </details>+ </section>++ <section aria-labelledby="quality">+ <h2 id="quality">Quality Net</h2>+ <p class="section-lead">+ The PR is not just a parser shortcut. The test surface follows the feature across native content, shaping arms, CLI loading, template generation, runner wiring, and dry-run E2E behavior.+ </p>++ <div class="table-wrap">+ <table>+ <thead>+ <tr>+ <th>Risk</th>+ <th>Guard</th>+ <th>Examples in this PR</th>+ </tr>+ </thead>+ <tbody>+ <tr>+ <td>LLM returns "yes" text instead of typed output</td>+ <td>Object output path verifies <code>YesNoContent</code> schema and result type.</td>+ <td><code>test_pipe_llm_yes_no_output_path.py</code>, <code>test_yes_no_dry_run.py</code></td>+ </tr>+ <tr>+ <td>Date-only value silently becomes midnight</td>+ <td><code>DateContent</code> rejects datetime-on-date and raises if callers ask for datetime without a time.</td>+ <td><code>test_date_content_renders.py</code>, <code>test_pipe_llm_date_output_path.py</code></td>+ </tr>+ <tr>+ <td>Bare values shape to the wrong concept</td>+ <td>Scalar arm tests assert declared concept retention for text, number, yes/no, date, image/document, and structured values.</td>+ <td><code>test_scalar_arms.py</code>, <code>test_explicit_forms.py</code>, <code>test_errors.py</code></td>+ </tr>+ <tr>+ <td>Generated template does not run</td>+ <td>Light template round-trip tests generate inputs, feed them back into a run, and keep <code>--explicit</code> as a compatibility path.</td>+ <td><code>test_input_renderer_light.py</code>, <code>test_input_renderer_light_golden.py</code>, <code>test_smart_inputs_light_roundtrip.py</code></td>+ </tr>+ <tr>+ <td>File inputs work in one surface but not another</td>+ <td><code>inputs_base_dir</code> is threaded through the runner and tested from CLI file loading into shaping.</td>+ <td><code>test_file_paths.py</code>, <code>test_csv_by_signature.py</code>, <code>test_run_core_inputs_base_dir.py</code></td>+ </tr>+ </tbody>+ </table>+ </div>+ </section>++ <section aria-labelledby="migration">+ <h2 id="migration">Migration Notes</h2>+ <p class="section-lead">+ These breaking changes are the cost of making wrong inputs visible instead of silently tolerated.+ </p>+ <ul class="plain-list">+ <li><code>YesNo</code> and <code>Date</code> are now reserved native concept codes. Bundles declaring concepts with those exact codes now error.</li>+ <li>Unknown input names are hard errors with the declared names listed.</li>+ <li>Top-level <code>null</code> is rejected. Omit the key to express absence.</li>+ <li>TOML date and datetime literals now map to <code>Date</code>; bare time-of-day values remain invalid.</li>+ <li>Structure field <code>type = "date"</code> now means <code>datetime.date</code>. Use <code>type = "datetime"</code> for a timestamp.</li>+ <li><code>build inputs</code> defaults to the light template. Use <code>--explicit</code> when you want the old envelope form.</li>+ </ul>+ </section>++ <section aria-labelledby="links">+ <h2 id="links">Related PRs</h2>+ <p class="section-lead">+ All related PRs found for this work are in this repository. No cross-repo PR was required for the changelog scope covered here.+ </p>+ <div class="link-list">+ <div class="link-card">+ <a href="https://github.com/Pipelex/pipelex/pull/1028">#1028 - Native YesNo and Date concepts + Smart Inputs</a>+ <span>Open umbrella PR against <code>dev</code>.</span>+ </div>+ <div class="link-card">+ <a href="https://github.com/Pipelex/pipelex/pull/1029">#1029 - Add native Date concept</a>+ <span>Merged into <code>feature/Smart-inputs</code>.</span>+ </div>+ <div class="link-card">+ <a href="https://github.com/Pipelex/pipelex/pull/1030">#1030 - Smart Inputs Phase 2</a>+ <span>Top-down shaping goes live on all surfaces.</span>+ </div>+ <div class="link-card">+ <a href="https://github.com/Pipelex/pipelex/pull/1032">#1032 - Smart Inputs Phase 3 + 4</a>+ <span>File-ish inputs, CSV-by-signature, and light templates.</span>+ </div>+ <div class="link-card">+ <a href="https://github.com/Pipelex/pipelex/pull/1033">#1033 - Smart Inputs Phase 5</a>+ <span>Light-model docs, changelog, and explicit-form multiplicity guard.</span>+ </div>+ </div>+ </section>++ <footer>+ <p>+ Source basis: <code>CHANGELOG.md</code> lines 5-17, diff against <code>origin/dev</code>, and GitHub PR metadata queried on 2026-07-08.+ </p>+ </footer>+ </main>++ <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>+ <script>+ if (window.mermaid) {+ window.mermaid.initialize({ startOnLoad: true, securityLevel: "strict", theme: "default" });+ }+ </script>+</body>+</html>diff --git a/wip/inputs/structure-field-fidelity-guard.md b/wip/inputs/structure-field-fidelity-guard.mdnew file mode 100644index 000000000..abac9ac00--- /dev/null+++ b/wip/inputs/structure-field-fidelity-guard.md@@ -0,0 +1,30 @@+# Deferred: `date`/`datetime` structure fields don't carry the native Date fidelity guard++**Status:** deferred design note — no code change. Surfaced during the Date-track PR #1029 adversarial review, 2026-07-07.++## What the reviewer flagged++The native `Date` concept is deliberately fidelity-strict: `DateContent._reject_lax_temporal` closes pydantic's lax-mode coercions that would silently corrupt data — a bare `int`/`float` or an all-digit string read as epoch seconds (DT6), a `datetime` on the `date` field truncated to drop its time and offset (DT3), no invented midnight (DT2).++DT8's severable field-type fix (`type = "date"` → `datetime.date`, `type = "datetime"` → `datetime.datetime`) generates **plain** pydantic `date`/`datetime` fields on user-defined structure classes. Those generated fields have **no** equivalent guard, so pydantic's lax coercion applies there:++- a `date` string into a `datetime` structure field silently becomes a midnight `datetime` (an invented time),+- a midnight-epoch int into a `date` structure field silently becomes that calendar date.++So the fidelity guarantees the native concept enforces are not enforced on user structure fields.++## Why this is a decision, not obviously a bug++- **Different surfaces, different contracts.** The native `Date` concept exists specifically to enforce document-fidelity. A user-defined structure field of `type = "date"` is an ordinary pydantic field on an arbitrary model — a more permissive surface. DT8's scope was the *type misnomer* (a `date` field should not force a time), explicitly **not** porting the native concept's anti-fabrication guard to every generated temporal field.+- **Porting the guard is broad and opinionated.** Making all generated `date`/`datetime` fields strict would change how every extraction into such a field behaves and could break pipelines that today rely on lax coercion (e.g. an LLM emitting a date string into a `datetime` field). That is a runtime-behavior change with a wide blast radius, not a local fix.++## Follow-up to consider++Decide, when structure-field temporal handling is revisited, whether to:++1. Leave structure fields permissive (document that only the native `Date` concept is fidelity-strict) — the likely intended non-goal; or+2. Emit a shared before-validator (or use pydantic strict / `Annotated` types) on generated `date`/`datetime` fields mirroring `DateContent._reject_lax_temporal`, so the native concept and structure fields behave consistently.++If (2), factor `_reject_lax_temporal` into a reusable validator so the two surfaces cannot drift. Related notes: `container-default-temporal-codegen-gap.md`.++No action needed inside the Date track.diff --git a/wip/inputs/uri-scheme-classification-stopgap.md b/wip/inputs/uri-scheme-classification-stopgap.mdnew file mode 100644index 000000000..6f3b2bfbb--- /dev/null+++ b/wip/inputs/uri-scheme-classification-stopgap.md@@ -0,0 +1,26 @@+# Deferred: the duplicated `"://"` scheme stopgap (make `resolve_uri` classify unknown schemes)++**Status:** deferred design tradeoff — **no live bug**, fully tested. Surfaced by the PR #1032 cubic-dev-ai review ([thread](https://github.com/Pipelex/pipelex/pull/1032) on `stuff_factory.py`). The acknowledgment already lived in a code comment; this note promotes it so the follow-up isn't lost.++## What the reviewer flagged (verified — the duplication is real)++`resolve_uri` (`pipelex/tools/uri/uri_resolver.py`) only recognizes `data:` / `pipelex-storage://` / `file://` / `http(s)://`; **everything else falls into `ResolvedLocalPath`**. So an unrecognized scheme like `s3://bucket/x.csv` or `gs://bucket/x.csv` arrives as a `ResolvedLocalPath` whose `.path` still contains `"://"`. Two independent sites bolt on the same `"://"` check to compensate — treat such a value as *not* a genuine local path:++- `uri_resolver.py` → `is_relative_local_path()`: `if "://" in resolved.path: return False` — so a scheme-like value is never rewritten as relative (it would otherwise be mangled into `<base_dir>/s3:/bucket/x`). Shared by the shaper's file/CSV arms (via `resolve_local_path_reference`) and the CLI url-key walk (`_inputs_path_resolver`).+- `stuff_factory.py` → `try_make_csv_list_content()`: `if not isinstance(resolved, ResolvedLocalPath) or "://" in resolved.path:` — the CSV local-only guard, raising a redacted `CsvError` for a remote/scheme url. Shared by the bottom-up factory (Case 2.5 envelope) and the top-down `InputShaper._try_shape_csv`.++The existing code already names this a stopgap (`uri_resolver.py`, in `is_relative_local_path`'s body): *"Mirrors the same `"://"` stopgap in the CSV input hook; both go away once `resolve_uri` classifies schemes (tools/uri follow-up)."*++## Why this is deferred, not fixed now++- **No live bug.** All sites behave identically today; `s3://` / `gs://` are correctly left-untouched / rejected, with coverage at `tests/unit/pipelex/core/memory/input_shaper/test_file_paths.py` (remote/scheme params), `tests/unit/pipelex/cli/test_inputs_path_resolver.py` (`S3_URL`, `GS_URL`), and `tests/integration/pipelex/csv/test_csv_input_detection.py`.+- **The reviewer's "top-down vs bottom-up CSV flows drift apart" framing is imprecise.** Both CSV flows converge on the *same* line in `try_make_csv_list_content`, so CSV scheme-rejection is not duplicated between them. The real duplication is the CSV guard vs. the relative-path resolver — two sites, not two CSV flows.+- **The proper fix broadens the URI-classification contract** — out of this PR's scope (it's Smart Inputs D3/D11, not a URI-tools refactor). Per the project's "defer design tradeoffs, don't reflexively apply" convention, it waits for a deliberate `tools/uri` pass.+- The drift risk is modest-but-real: if someone tightened one site (e.g. switched to `urlsplit().scheme`) without the other, they'd diverge — but the tests above guard against silent divergence.++## The fix (when `tools/uri` is next touched)++- **Proper (root cause):** make `resolve_uri` classify unknown schemes — add a `ResolvedUnknownScheme` / `UriKind` variant in `pipelex/tools/uri/resolved_uri.py` and update every exhaustive `match ResolvedUri` (`extract_filename_from_uri`, `describe_uri`, `make_base64_url_from_any_uri`). Then both `"://"` band-aids delete: `is_relative_local_path` and the CSV guard branch on the typed variant instead.+- **Partial (if a smaller step is wanted first):** extract `path_has_unrecognized_scheme(path) -> bool` in `tools/uri` and call it from both sites — consolidates the two checks into one place but keeps the heuristic.++Prefer the proper fix; the partial one only removes the duplication, not the stopgap.diff --git a/wip/inputs/yesno-implementation-plan.md b/wip/inputs/yesno-implementation-plan.mdnew file mode 100644index 000000000..a8cd4cdad--- /dev/null+++ b/wip/inputs/yesno-implementation-plan.md@@ -0,0 +1,102 @@+# YesNo track — implementation plan for the native `YesNo` concept++Status: **plan written 2026-07-07, implementation not started**. Design home: `smart-inputs-design.md` §D9 (**approved** — there is no separate YesNo design doc; naming, rationale, and rejected alternatives all live in D9). Branch `feature/Smart-inputs`, worktree `_smart`, based on main at v0.38.0. Track order (`README.md`): **YesNo (this plan)** → Datetime → Smart Inputs, one release wave. YesNo holds the train.++How to use this doc: work the phases in order, check boxes as you go, and at each CHECKPOINT update the "state" line under it (what landed, commit hashes, open questions) so the next session cold-starts from here.++## 0. Cold-start context — read this first++**What ships:** one new native concept `YesNo` — the answer to a yes/no question. Content = a single required `bool`. LLM pipelines constantly produce yes/no judgments ("does this contract contain a penalty clause?") and today authors hack them as `Text` answering "yes"/"no" or a single-field structure. The name is settled (chosen over Boolean/TrueFalse/Logical/Truth/Checkbox — Access's "Yes/No" field-type precedent; PascalCase compound follows `TextAndImages`) — do not relitigate; see D9.++**Core scope** (per `README.md`): enum entry, content class, structure-class mapping, schema regen (a verification, see below), MTHDS spec entry (drafted here, merged in the release wave). **Deliberately excluded:** the LLM-output ergonomics (a leaner scalar-native generation form — follow-up shared with the Date track, off the critical path) and bare-scalar input shaping (`"is_urgent": true` at the top level of an inputs file — that is the Smart Inputs D5 matrix row, which activates when Smart Inputs lands; this plan only makes the *envelope* form work).++**Key mechanism facts** (verified 2026-07-07 against the worktree; line numbers approximate):++- **Adding a native concept** = enum value `YES_NO = "YesNo"` in `NativeConceptCode` (`pipelex/core/concepts/native/concept_native.py:20`) + arms in its exhaustive matches — `structure_class` (`:74`), `is_composite` (`:39`, False group), `is_text_concept` (`:132`, False group), `is_dynamic_concept` (`:157`, False group) — + a `case` in `ConceptFactory.make_native_concept` (`pipelex/core/concepts/concept_factory.py:98`) + content-class registration in `CoreRegistryModels.STUFF` (`pipelex/core/registry_models.py:92`). The library auto-loads natives from the enum; reference validation and class-name lookups iterate the enum, so they pick the new value up automatically. Exhaustive `match/case` style (never `case _`) means pyright walks you to every remaining site.+- **`structure_class_name` is auto-derived** as `f"{enum_value}Content"` → the class MUST be named `YesNoContent`, and the concept ref is `native.YesNo`. The class-name→concept inference in `StuffFactory` cases 1.3/1.5 splits on `"Content"` and feeds the prefix back through the enum — `YesNoContent` → `native.YesNo` works with zero code change once the enum value exists.+- **The content-class precedent** is `NumberContent` (`pipelex/core/stuffs/number_content.py`): one file per class in `pipelex/core/stuffs/`, overriding `short_desc`, `rendered_plain`, `rendered_html`, `rendered_markdown`, `rendered_json`. Test precedent: `tests/unit/pipelex/core/stuffs/number_content/` (renders + smart_dump modules).+- **The accessor family precedent** (Number's convenience surface, to mirror): `Stuff.is_number` (`pipelex/core/stuffs/stuff.py:92`) and `Stuff.as_number` (`:218`), `WorkingMemory.get_stuff_as_number` (`pipelex/core/memory/working_memory.py:483`) and `main_stuff_as_number` (`:529`), `PipeOutput.main_stuff_as_number` (`pipelex/core/pipes/pipe_output.py:77`).+- **LLM output works day one, verify only:** PipeLLM dispatch (`pipe_llm.py:249`) sends Text-compatible single outputs down the text path and everything else down the object path with `model_json_schema()` of the structure class — `YesNo` is not Text-compatible, so `output = "YesNo"` takes the object path automatically, and the `Field(description=...)` on the bool field lands in the schema handed to the LLM (contract, not decoration). The structure-prompt machinery already handles `bool` fields (`concept_representation_generator.py:311`). Dry-run mocks use polyfactory, which synthesizes `bool` natively.+- **Serialization is trivially safe but gets one cheap test:** `bool` is JSON-native — no kajson encoder work, unlike Date. Still pin one transport round-trip (`dump_for_transport` → `hydrate_working_memory`, `tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py`) because the distributed failure mode is a hang, not an error (a content class that fails payload decode inside a Temporal workflow retries forever).+- **Inputs today:** an envelope `{"concept": "YesNo", "content": true}` falls through `StuffFactory.make_stuff_from_stuff_content_or_data` case 2 to the terminal `Unexpected type for content value: <class 'bool'>` (`stuff_factory.py:603`) — no bool arm exists. `StuffContentFactory.make_content_from_value` (`stuff_content_factory.py:12`) is typed `value: dict[str, Any] | str` and special-cases str+`TextContent`; it widens for bool. The dict-content envelope `{"concept": "YesNo", "content": {"yes_no": true}}` works day one via `model_validate` (case 2.5). The case 2.1 str-content guard (`stuff_factory.py:470`) only admits Text-compatible concepts — a string `"yes"` for a YesNo concept errors there, and **stays** an error (no cross-kind coercion, same policy as Smart Inputs D5 and Datetime DT5).+- **Cross-repo gotcha:** `StuffContentOrData` / `PipelineInputs` live in the **mthds-python** package (`mthds/protocol/pipeline_inputs.py`, a pinned dependency — NOT in this repo). The union does NOT admit bare `bool` — top-level `true` in an inputs file stays impossible until the Smart Inputs D10 protocol widening (release wave). Envelope dicts are `dict[str, Any]`, so bool content *inside* an envelope passes typing today; bools nested in structured dicts already work. **Core-scope answer: don't touch the protocol.**+- **Schema regen is a verification, not a change:** `pipelex/language/mthds_schema_generator.py` does not enumerate native concept codes, so adding `YesNo` should produce a no-diff regen. Only the boolean-field-type-alias micro-decision (below), if taken, would alter the schema.+- **Python gotcha:** `bool` is a subclass of `int`. No int arms exist in the envelope dispatch today, but any bool arm must be written to hold if one ever appears (check bool BEFORE int) — this is also the guard Smart Inputs D9 mandates for its Number arm. pydantic v2 lax mode would accept `"yes"`/`"true"`/`1` for a `bool` field via `model_validate` on the dict-content path; **the field is declared `strict=True`** so that leniency is closed and only a real `bool` validates (post-review hardening — both PR bots flagged the lax dict-content path as a coercion bypass; see the CHECKPOINT 3 procedure note).++**House rules that bite here:** TDD (tests first, red→green); keyword-only args (bare `*` after the subject — `make cko` gates); error classes only in `exceptions.py` modules; no `case _` in enum matches; `make agent-check` after code changes; `make agent-test` before wrapping a session; `make tb` for a quick boot check; no hardcoded counts in docs/comments; changelog entries under `[Unreleased]`.++## Phase 1 — Concept core++Tests first, then make them green:++- [x] **Tests** in `tests/unit/pipelex/core/stuffs/yes_no_content/` (mirror the `number_content/` module split): construction from `yes_no=True`/`False`; the render matrix — `rendered_plain`/`rendered_markdown`/`rendered_html` give `yes`/`no` (per the rendering micro-decision below), `rendered_json` gives `{"yes_no": true}`; `short_desc` (e.g. "a yes/no answer (yes)"); `smart_dump`; `model_json_schema()` contains the field description (the LLM-facing contract); pydantic does NOT accept an `int` where the bool is expected in strict construction paths (pin the `bool`-vs-`int` boundary).+- [x] **Transport round-trip test:** extend `tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py` with a `YesNo` stuff (and one inside a `ListContent`) through `dump_for_transport` → `hydrate_working_memory` — cheap insurance against the Temporal hang-not-fail decode failure mode.+- [x] **`YesNoContent`** in new `pipelex/core/stuffs/yes_no_content.py`: `yes_no: bool` with `Field(description=...)` (wording micro-decision — it is what the LLM reads in the generation schema), `rendered_*` overrides + `short_desc` following the `NumberContent` template.+- [x] **Enum + matches:** `YES_NO = "YesNo"` in `NativeConceptCode` + arms in `structure_class` (→ `YesNoContent`), `is_composite` (False group), `is_text_concept` (False group), `is_dynamic_concept` (False group). Let pyright surface any other exhaustive match over the enum.+- [x] **Factory arm** in `ConceptFactory.make_native_concept`: description per the micro-decision (proposed: "The answer to a yes/no question").+- [x] **Registry:** add `YesNoContent` to `CoreRegistryModels.STUFF`.+- [x] **Accessors** mirroring Number's: `Stuff.is_yes_no` + `Stuff.as_yes_no`, `WorkingMemory.get_stuff_as_yes_no` + `main_stuff_as_yes_no`, `PipeOutput.main_stuff_as_yes_no` — this is how a Python-API caller reads the verdict (`pipe_output.main_stuff_as_yes_no().yes_no`).+- [x] **Refinement sanity test:** a bundle declaring `[concept.IsUrgent]` with `refines = "YesNo"` validates, and the refining concept resolves `YesNoContent` as its structure class (the machinery is generic — this pins it).+- [x] `make tb` (boot + registry load), `make agent-check`, targeted pytest on the new test modules.++### CHECKPOINT 1 — concept exists and boots++State: **reached 2026-07-07.** All Phase 1 tasks landed and gates are green (`make tb`, `make agent-check` — ruff/plxt/pyright 0-errors/mypy Success/cko; targeted pytest on the new modules all pass). Schema regen ran inside `agent-check` (no unexpected diff — confirms §0: the generator doesn't enumerate native codes).++Files touched: new `pipelex/core/stuffs/yes_no_content.py`; enum+matches in `concept_native.py`; factory arm in `concept_factory.py`; registry in `registry_models.py`; accessors in `stuff.py` / `working_memory.py` / `pipe_output.py`. Tests: new `tests/unit/pipelex/core/stuffs/yes_no_content/` (renders + smart_dump + test_data), new `tests/unit/pipelex/core/concepts/concept_factory/test_yes_no_refinement.py`, extended `test_hydration.py`.++Settled micro-decisions: field name `yes_no: bool` (declared `strict=True` — see the post-review hardening note in §0); renders `yes`/`no` for plain/markdown/html, `rendered_json` → `{"yes_no": true}`; field description "Whether the answer is yes (true) or no (false)."; native concept description "The answer to a yes/no question"; `short_desc` = "a yes/no answer (yes)"/"(no)". Nothing fought back — the class-name→concept inference and refinement machinery are fully generic (no changes needed there). Boundary tests pin `yes_no` = 2, `"yes"`, and 1 → ValidationError (strict rejects all non-bool, closing the dict-content coercion path).++## Phase 2 — Inputs: envelope viability++Scope guard: bare `true` at the top level of an inputs file (JSON or TOML) **stays an error** until Smart Inputs D5 — do not widen the mthds-python protocol here (that's D10, release wave). This phase only makes the explicit envelope usable so `YesNo` inputs exist at all pre-Smart-Inputs.++- [x] **Tests first** (extended `tests/unit/pipelex/core/stuffs/test_stuff_content_factory.py` + the stuff-factory input tests via `data.py`): envelope `{"concept": "YesNo", "content": true/false}` → `YesNoContent` with concept `native.YesNo`; a refining concept (`{"concept": "test_domain.UrgencyFlag", "content": false}`) keeps its own concept ref and builds the refining subclass; bool content for a concept NOT YesNo-compatible → typed error naming `native.YesNo`; the dict-content form still works; string content `"yes"` for a YesNo concept still errors (no-coercion policy); direct `YesNoContent` instance at top level (case 1.3) infers `native.YesNo`. Confirmed RED (6 fail on the "unexpected type for content value: bool" fall-through) then GREEN.+- [x] **`StuffContentFactory.make_content_from_value`:** widened `value` typing to `dict | str | bool` and added the arm — `isinstance(value, bool) and issubclass(stuff_content_subclass, YesNoContent)` → `stuff_content_subclass(yes_no=value)`, placed first (bool ⊑ int) and ahead of `model_validate` (which rejects a bare bool). Also widened `make_stuff_content_from_concept_required`'s `value` typing.+- [x] **`StuffFactory` case 2 (envelope):** added case 2.1d — `isinstance(content, bool)` checked FIRST among the content-type arms (defensive vs future int handling); strict `is_compatible` vs native YesNo (mirrors the Text arm) → content via `make_stuff_content_from_concept_required` (honors refining subclasses, unlike the Text arm's flatten-to-base); else a `StuffFactoryError` naming the concept and "native.YesNo (the content is a boolean)". Case-list docstring updated with 2.1d.+- [x] **Dry-run check:** new fixture bundle `tests/e2e/pipelex/pipes/yes_no/yes_no_judgment/` (PipeLLM `judge_is_urgent` outputs YesNo; PipeLLM `explain_verdict` takes a YesNo input). `test_yes_no_dry_run.py` — both complete in DRY mode: output mocks a `YesNoContent` via polyfactory (no generator quirks surfaced), envelope input flows through and renders inline. No fixes needed.+- [x] **e2e:** `tests/e2e/pipelex/cli/test_yes_no_inputs_run.py` (`gha_disabled` subprocess) — `pipelex run pipe explain_verdict --inputs inputs.toml --dry-run` with the envelope form (`concept = "YesNo"`, `content = true`) succeeds; TOML scalar `true` loads via the shared inputs loader (no datetime rejection) into the envelope dict.+- [x] `make agent-check` (ruff/plxt/pyright 0-errors/mypy Success/cko all green).++### CHECKPOINT 2 — YesNo flows through inputs (envelope) and dry run++State: **reached 2026-07-07.** All Phase 2 tasks landed and `make agent-check` is green. No dispatch-ordering surprises: bool is not str/StuffContent/dict/list, so the new arm slots in cleanly; placed bool-first among Case-2 arms defensively (bool ⊑ int). The Case 2.1 (str) error message needed NO update — a `"yes"` string under a YesNo concept still errors there ("not compatible with native concept 'native.Text'"), which is exactly the no-coercion behavior we wanted, so it doubles as the policy pin. Key design decision: the bool arm routes through `make_stuff_content_from_concept_required` (resolving `structure_class_name`) rather than constructing base `YesNoContent` directly like the Text arm — this honors the generated refinement subclass (`urgency__IsUrgent`), which `model_validate(True)` would reject but `subclass(yes_no=...)` builds fine. Files touched: `stuff_content_factory.py`, `stuff_factory.py`; tests `test_stuff_content_factory.py`, `data.py`, `test_stuff_factory_implicit_memory.py` (fixture registers a `UrgencyFlag(YesNoContent)` refining concept), new `tests/e2e/pipelex/pipes/yes_no/` bundle + dry-run test, new `tests/e2e/pipelex/cli/test_yes_no_inputs_run.py`. Scope guard intact: bare top-level `true` still errors (mthds-python `StuffContentOrData` untouched); only the envelope form works.++## Phase 3 — LLM output verification++- [x] New `tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_yes_no_output_path.py`: a DRY-mode PipeLLM with `output = NativeConceptCode.YES_NO` is run through the router while `content_generator.make_object` is spied. Asserts the **object path** is selected (`make_object` called once — the text path calls `make_llm_text` instead), the `object_class` handed down is exactly `YesNoContent`, that class's `model_json_schema()` carries the field description (the LLM-facing contract), and the produced verdict `is_yes_no`. Markerless (pure DRY — the leaf mock short-circuits inside `make_object`, no provider called), booted on `load_empty_library` (native concepts only, no bundle). This pins the dispatch: if someone made `YesNo` Text-compatible, the object path would not be taken and the test fails loudly.+- [ ] Optional, non-gating: one live-gateway smoke of a judgment pipe (`output = "YesNo"`) — manual, not CI.++No new generation machinery: the leaner scalar-native generation form is explicitly deferred to the shared YesNo/Date LLM-output-ergonomics follow-up (D9, off the critical path).++## Phase 4 — Docs, schema, changelog, wrap++- [x] **Settled the boolean-alias micro-decision** (D9 parked it here): **NO alias.** The lowercase `boolean` structure-field type keeps one spelling; a friendlier `yes_no` alias would be a two-spellings drift magnet, and the concept-level brand is `YesNo`. Consequence: nothing to do at the field-type/schema level — the schema-regen step stays a no-op as predicted.+- [x] `docs/building-methods/concepts/native-concepts.md`: added the `YesNo` table row + a `YesNoContent` section (bool field, `yes`/`no` rendering, `output = "YesNo"` PipeLLM example, `main_stuff_as_yes_no.yes_no` reader), mirroring `NumberContent`.+- [x] `docs/building-methods/pipes/pipe-output.md`: added the `main_stuff_as_yes_no` accessor entry alongside the other `main_stuff_as_*` accessors.+- [x] Schema regen: `.venv/bin/pipelex-dev generate-mthds-schema` runs inside `make agent-check` — **no diff**, confirming §0's prediction that the generator doesn't enumerate native codes.+- [x] **MTHDS spec entry** (cross-repo): added the `YesNo` native-concept rows + field listing to the `mthds/` sibling repo (`docs/language/concepts.md`, `docs/spec/mthds-format.md`) on side branch `feature/native-yes-no-concept` (commit `0f55a58`, not pushed — merge vehicle is the release wave). The mthds repo was restored to `dev` afterward.+- [x] `CHANGELOG.md` under a fresh `[Unreleased]` section (v0.38.0 was the prior top entry): added native `YesNo` concept — typed yes/no answers for LLM judgments (`output = "YesNo"`) + envelope input support; breaking — `YesNo` is now a reserved native code.+- [x] Track bookkeeping: updated `wip/inputs/README.md` (YesNo → done, next = Datetime plan) and this plan's checkpoint states.+- [x] Full gates: `make agent-check` + `make agent-test`.++### CHECKPOINT 3 — track complete, hand off to the next train car++State: **reached 2026-07-07.** All four phases committed on `feature/Smart-inputs` (pushed): Phase 1 `9f6db3765` → Phase 2 `4d1961c75` → Phase 3 `2971bf970` → Phase 4 `efe8c99da`, + `TODOS.md` reviewer's guide `92dfef141`. Full `make agent-check` + `make agent-test` green; each phase cleared a context-free Sonnet-5 `/code-review` (all correctness-clean). **PR #1028 → `dev` opened**; CI green across py3.11–3.14 (tests + typecheck + lint). **Review-bot round:** greptile (P1) + cubic (P2) both flagged the same single issue — the `yes_no` field's lax pydantic validation let the dict-content path coerce `"yes"`/`0`/`1` into a bool, bypassing the no-coercion contract. Verified valid and safe for every legitimate path, applied `strict=True` with red→green pins (`a03a88b2c`). MTHDS spec rows drafted on sibling `mthds` side branch `feature/native-yes-no-concept` (`0f55a58`, not pushed — release wave). Deferred design note: `scalar-envelope-arm-asymmetry.md`. Remaining before merge: re-trigger the bots, then a final gstack `/review` pass.++## Deferred to the release-wave sweep / follow-ups (NOT this plan's scope — listed so nothing is lost)++Shared per-release wave with Datetime + Smart Inputs (see `README.md`): the Smart Inputs D5 matrix row (bare `true`/`false` against a YesNo-declared input) and D10 protocol widening (`mthds-python` `StuffContentOrData`); schema-copy sync via the `mthds-schema-sync` skill; MTHDS spec merge (drafted in Phase 4); `mthds-js` mirrors; conformance rows; `mthds-plugins` skills (`mthds-inputs`, `mthds-build`); vscode-pipelex completion lists; the `ConceptSpec.refines` authoring-hint native list (drifts from `NativeConceptCode` — derive it from the enum during this sweep; see `refines-hint-native-list-drift.md`).++Follow-up off the critical path (shared with Date): **LLM-output ergonomics for scalar natives** — how PipeLLM produces a `YesNo`/`Date` more leanly than the generic object path (cousin of the Optionals maybe-wrapper).++`pipelex-temporal` (private plugin repo): no code change expected — `bool` is JSON-native and the codec binds classes through the registry. At pin-bump time, add a `YesNo` case to its converter round-trip tests anyway (the failure mode over there is a hang, not an error; coverage is cheap insurance).++## Micro-decisions log++- Content field name: **SETTLED `yes_no: bool`** (the `NumberContent.number` pattern — field named after the enum value). Alternatives considered: `answer`, `value`, `is_yes`.+- Renderings: **SETTLED `yes`/`no`** for plain/markdown/html (reads naturally when injected into downstream prompts; D9's wording); `rendered_json` keeps the raw `{"yes_no": true}`.+- Field description wording (the LLM generation contract): **SETTLED** "Whether the answer is yes (true) or no (false)."+- Native concept description (factory arm): **SETTLED** "The answer to a yes/no question" (D9's own phrasing).+- `boolean` structure-field-type alias: **SETTLED — NO alias** (one way to spell a thing; the concept-level brand is `YesNo`, the field-type primitive stays `boolean`). Keeps the schema-regen a no-op.+- Envelope string forms (`"content": "yes"`): **rejected** — no cross-kind coercion, consistent with Smart Inputs D5 and Datetime DT5. Not open; recorded so nobody reopens it casually.diff --git a/wip/inputs/yesno-pr-reviewers-guide.md b/wip/inputs/yesno-pr-reviewers-guide.mdnew file mode 100644index 000000000..7617afb0f--- /dev/null+++ b/wip/inputs/yesno-pr-reviewers-guide.md@@ -0,0 +1,39 @@+# PR reviewer's guide — native `YesNo` concept++> **Archived 2026-07-07.** This was the repo-root `TODOS.md` reviewer's guide for the YesNo PR (#1028). YesNo and Date have both landed on `feature/Smart-inputs` (Date via PR #1029, merged), so this guide is now historical. The durable as-built record is `yesno-implementation-plan.md`; the live track roadmap is `README.md`. Kept for the PR-reading narrative only.++This branch (`feature/Smart-inputs`) adds a new built-in native concept **`YesNo`** — the answer to a yes/no question, backed by a single required `bool`. LLM pipelines constantly produce yes/no judgments ("does this contract contain a penalty clause?"); today authors hack them as `Text` answering "yes"/"no" or a one-field structure. `YesNo` makes that a typed first-class concept.++**What is shippable in this PR:** the `YesNo` concept and its input/output plumbing (the diff below). Everything under `wip/inputs/` is planning/design for the broader *Smart Inputs* track (of which `YesNo` is the first of three native-concept prerequisites) — those docs are not implemented here and are not release-facing. Read `wip/inputs/README.md` for the track roadmap and `wip/inputs/yesno-implementation-plan.md` for the phased plan this PR executed (checkboxes + checkpoint state lines record the as-built).++## How to review this++The change is small and purely **additive** — it adds one native code and the arms an exhaustive-match tree requires, plus one factory arm for boolean envelope inputs. No existing behavior changes. Suggested reading order:++1. **`pipelex/core/stuffs/yes_no_content.py`** — the content class. `yes_no: bool` with a `Field(description=...)` (the LLM-facing generation contract), `rendered_*` overrides → `yes`/`no` for plain/markdown/html, `rendered_json` → `{"yes_no": true}`, `short_desc`. Mirrors `NumberContent`.+2. **`pipelex/core/concepts/native/concept_native.py`** + **`concept_factory.py`** + **`registry_models.py`** — the enum value `YES_NO = "YesNo"`, its arms in the exhaustive matches (`structure_class`, `is_composite`, `is_text_concept`, `is_dynamic_concept` — all in the "not composite / not text / not dynamic" groups), the factory arm ("The answer to a yes/no question"), and the `YesNoContent` registration. `structure_class_name` auto-derives to `YesNoContent`, so class-name→concept inference works with no extra code.+3. **Accessors** — `Stuff.is_yes_no` / `as_yes_no`, `WorkingMemory.get_stuff_as_yes_no` / `main_stuff_as_yes_no`, `PipeOutput.main_stuff_as_yes_no`. These faithfully mirror the `Number` accessor family layer-for-layer; `main_stuff_as_yes_no.yes_no` is how a Python caller reads a verdict.+4. **Envelope inputs** — `stuff_content_factory.py` + `stuff_factory.py`. A pipeline input in the envelope form `{"concept": "YesNo", "content": true}` (JSON or TOML) is shaped into a `YesNoContent`. The bool arm is checked **before** any int handling (`bool` ⊑ `int`) and before `model_validate` (which rejects a bare bool), and it routes through the concept resolver so a concept that `refines = "YesNo"` keeps its **own generated subclass** (which `model_validate(True)` would reject but `subclass(yes_no=...)` builds). A bool for a non-YesNo-compatible concept raises a typed error naming `native.YesNo`.++## Test coverage++- **Unit** — `yes_no_content/` (renders + smart_dump + schema-carries-description + the `bool`-vs-`int` boundary); `concept_factory/test_yes_no_refinement.py` (a `refines = "YesNo"` concept resolves `YesNoContent` — the machinery is generic); `test_stuff_content_factory.py` + `data.py` + `test_stuff_factory_implicit_memory.py` (envelope factory arm, refining-subclass preservation, no-coercion pin); `runtime_bridge/.../test_hydration.py` (transport round-trip — cheap insurance against the Temporal decode-hang failure mode, since `bool` is JSON-native).+- **Integration** — `pipe_llm/test_pipe_llm_yes_no_output_path.py` pins that `output = "YesNo"` takes the LLM **object path** (not the text path): a DRY run spies `content_generator.make_object` and asserts it is called with `object_class=YesNoContent` whose schema carries the field description. Fails loudly if someone ever makes `YesNo` Text-compatible.+- **E2E** — `pipes/yes_no/` dry-run bundle (`judge_is_urgent` outputs YesNo; `explain_verdict` takes a YesNo input) + `cli/test_yes_no_inputs_run.py` (subprocess: `pipelex run … --inputs inputs.toml --dry-run` with `content = true`).++## Scope guards (deliberate, not omissions)++- **Bare top-level `true`/`false` in an inputs file stays an error.** Only the *envelope* form works here. Bare-scalar input shaping (`"is_urgent": true` at the top level) is the Smart Inputs D5 matrix row, which activates when Smart Inputs lands. The `mthds/protocol/pipeline_inputs.py` `StuffContentOrData` union (in the external `mthds` package) is **untouched** — widening it to admit bare `bool` is the D10 protocol change, deferred to the release wave.+- **No string→bool coercion.** A `"yes"` string under a YesNo concept still errors (it takes the str path and fails as not-Text-compatible). Consistent with Smart Inputs D5 and the Datetime track.+- **No new LLM-generation machinery.** `output = "YesNo"` works day one via the existing object path; a leaner scalar-native generation form is an explicit follow-up shared with the Date track, off the critical path.+- **`boolean` field-type alias: settled NO.** The lowercase `boolean` structure-field primitive keeps one spelling; the concept-level brand is `YesNo`. Consequence: the MTHDS JSON Schema regen is a **no-diff** (the generator doesn't enumerate native codes).++## Cross-repo (release-wave, not in this PR)++- **MTHDS spec:** the `YesNo` native-concept rows + field listing are drafted in the sibling **`mthds`** repo (`docs/language/concepts.md`, `docs/spec/mthds-format.md`) on side branch `feature/native-yes-no-concept` (not pushed). Merge vehicle is the shared release wave.+- **Deferred to the per-release downstream sweep:** schema-copy sync (`mthds-schema-sync` skill), `mthds-js`/`mthds-python` mirrors, conformance rows, skills, editor completion lists — all shared with the Datetime + Smart Inputs tracks per `wip/inputs/README.md`.+- **`pipelex-temporal`** (private plugin): no code change expected (`bool` is JSON-native, classes bind via the registry); add a `YesNo` converter round-trip test at pin-bump time as cheap insurance.++## Breaking change++`YesNo` is now a reserved native concept code — a bundle declaring `[concept.YesNo]` errors. Noted in the CHANGELOG `[Unreleased]` section.