Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
Fix/dry run array change 3 to 2 (#1017)
Thomas Hebrard4131264d18fd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 00407dbad..155195698 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,7 @@### Changed+- **Dry-run mock lists shrink from 3 to 2 items:** When a pipe input is declared as a list without a fixed size, the dry-run mock now fabricates 2 items instead of 3. Cuts dry-run work on list inputs without changing correctness.- **Repo lint validates `.mthds` files against the locally generated MTHDS schema:** `plxt lint` in this repo now uses `derived/mthds_schema.json` (regenerated automatically by the lint make targets) instead of the released schema bundled with plxt, so language-surface additions like `size` are lintable here before they propagate to a plxt release.### Fixed@@ -25,9 +26,9 @@### Highlights- **Orchestration plugin SPI** — Pipelex opens its execution path to pluggable orchestrators: the orchestrator that runs a job is now chosen per call by an open `orchestration_mode` token, with the core shipping an in-process `direct` orchestrator and the contract ready for plugins to supply distributed backends.- - **Orchestration plugin contract (`orchestration_mode` + `DeliveryMode`)**: The contract is built on two independent axes — an open `orchestration_mode` token (which orchestrator runs the job — `direct` in core, other modes supplied by plugins) and a closed `DeliveryMode` enum (the wait-semantics axis — `BLOCKING` / `FIRE_AND_FORGET`). An orchestrator plugin implements `OrchestratorProtocol.run` with a required `delivery: DeliveryMode` keyword and declares a `supports_fire_and_forget: bool` capability; the orchestrator registries are keyed by the `orchestration_mode` token. `PipelexPipeRunInput` carries `orchestration_mode` + `delivery`.- - **Orchestrator-dispatched `/validate`**: A new per-call bundle-validator seam (`BundleValidatorProtocol` / `BundleValidatorRegistry`) makes `/validate` dispatch by `orchestration_mode` the way `/start` runs a pipe — `direct` validates in-process, distributed modes dispatch the job to a worker — with a byte-identical verdict across backends. The core `direct` plugin registers an in-process `DirectBundleValidator`.- - **Honest fire-and-forget delivery**: A fire-and-forget `/start` request is honored only when the resolved orchestrator can do genuine async; an orchestrator that cannot (e.g. the in-process `direct` mode) returns a 4xx rather than running the job to completion and falsely acking.+ - **Orchestration plugin contract (`orchestration_mode` + `DeliveryMode`)**: The contract is built on two independent axes — an open `orchestration_mode` token (which orchestrator runs the job — `direct` in core, other modes supplied by plugins) and a closed `DeliveryMode` enum (the wait-semantics axis — `BLOCKING` / `FIRE_AND_FORGET`). An orchestrator plugin implements `OrchestratorProtocol.run` with a required `delivery: DeliveryMode` keyword and declares a `supports_fire_and_forget: bool` capability; the orchestrator registries are keyed by the `orchestration_mode` token. `PipelexPipeRunInput` carries `orchestration_mode` + `delivery`.+ - **Orchestrator-dispatched `/validate`**: A new per-call bundle-validator seam (`BundleValidatorProtocol` / `BundleValidatorRegistry`) makes `/validate` dispatch by `orchestration_mode` the way `/start` runs a pipe — `direct` validates in-process, distributed modes dispatch the job to a worker — with a byte-identical verdict across backends. The core `direct` plugin registers an in-process `DirectBundleValidator`.+ - **Honest fire-and-forget delivery**: A fire-and-forget `/start` request is honored only when the resolved orchestrator can do genuine async; an orchestrator that cannot (e.g. the in-process `direct` mode) returns a 4xx rather than running the job to completion and falsely acking.### Added@@ -88,23 +89,24 @@### Highlights- **Structured validation errors** — validation failures now return a typed, per-error `validation_errors[]` on the error wire instead of a bare `detail` string, with the same shape across the HTTP API and the agent CLI.- - **Structured `validation_errors` on the error wire**: `ErrorReport` gains a typed `validation_errors: list[ValidationErrorItem] | None` field. `ValidateBundleError.to_error_report()` flattens its per-error data onto it via a single shared builder (`pipelex/pipeline/validation_errors.py`), so the structured error report an HTTP API surfaces carries machine-mappable per-error diagnostics — `category`, `message`, identity fields, and a `source` (declaring file) for cross-file mapping — instead of only a `detail` string. The closed `ValidationErrorCategory` set is `blueprint_validation` / `pipe_factory` / `pipe_validation` / `dry_run`; a **residual dry-run failure** (`DryRunError` / `PipeRunError`, no structured locator) is projected as one `dry_run` item **only when no categorized error has data**, so an invalid verdict always carries a non-empty `validation_errors[]` (the structured-info invariant) rather than a bare message. The same builder feeds the agent CLI's `validation_errors` JSON array, so the CLI and API structured shapes cannot drift. The list is surfaced under STRICT disclosure (`_STRICT_KEPT_FIELDS`) because it describes the caller's own submitted bundle, not server internals.- - **Changed — agent CLI `validation_errors` shape**: the `validate` commands' error envelope now omits null-valued keys per entry (`exclude_none`) and gains the previously-dropped `source`, `field_name`, and `concept_code` fields. Entries are guaranteed to carry `category` and `message`; all other keys are present only when populated, so consumers must treat them as optional rather than assume a fixed key set.- - **Per-content `source` on the in-memory validate path**: `PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_source=...)` and `validate_bundle(mthds_sources=...)` let a caller attach a logical source to each in-memory bundle string, threaded into `blueprint.source`. A sourceless `mthds_contents` submission previously produced `source=None`, breaking cross-file diagnostics; a host (e.g. an HTTP API) can now pass per-item sources so the structured `validation_errors` carry a real owning file. The on-disk CLI path is unchanged (it already records real file paths).- - **`dry_run` validation category**: `ValidationErrorCategory` gains a `dry_run` value. A dry-run residual failure that previously produced a bare-message `ValidateBundleError` with an empty `validation_errors[]` now surfaces one structured `dry_run` item carrying the message (graph-level, so typically no `source`) — closing the structured-info gap that drove consumers to fabricate a category.+ - **Structured `validation_errors` on the error wire**: `ErrorReport` gains a typed `validation_errors: list[ValidationErrorItem] | None` field. `ValidateBundleError.to_error_report()` flattens its per-error data onto it via a single shared builder (`pipelex/pipeline/validation_errors.py`), so the structured error report an HTTP API surfaces carries machine-mappable per-error diagnostics — `category`, `message`, identity fields, and a `source` (declaring file) for cross-file mapping — instead of only a `detail` string. The closed `ValidationErrorCategory` set is `blueprint_validation` / `pipe_factory` / `pipe_validation` / `dry_run`; a **residual dry-run failure** (`DryRunError` / `PipeRunError`, no structured locator) is projected as one `dry_run` item **only when no categorized error has data**, so an invalid verdict always carries a non-empty `validation_errors[]` (the structured-info invariant) rather than a bare message. The same builder feeds the agent CLI's `validation_errors` JSON array, so the CLI and API structured shapes cannot drift. The list is surfaced under STRICT disclosure (`_STRICT_KEPT_FIELDS`) because it describes the caller's own submitted bundle, not server internals.+ - **Changed — agent CLI `validation_errors` shape**: the `validate` commands' error envelope now omits null-valued keys per entry (`exclude_none`) and gains the previously-dropped `source`, `field_name`, and `concept_code` fields. Entries are guaranteed to carry `category` and `message`; all other keys are present only when populated, so consumers must treat them as optional rather than assume a fixed key set.+ - **Per-content `source` on the in-memory validate path**: `PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_source=...)` and `validate_bundle(mthds_sources=...)` let a caller attach a logical source to each in-memory bundle string, threaded into `blueprint.source`. A sourceless `mthds_contents` submission previously produced `source=None`, breaking cross-file diagnostics; a host (e.g. an HTTP API) can now pass per-item sources so the structured `validation_errors` carry a real owning file. The on-disk CLI path is unchanged (it already records real file paths).+ - **`dry_run` validation category**: `ValidationErrorCategory` gains a `dry_run` value. A dry-run residual failure that previously produced a bare-message `ValidateBundleError` with an empty `validation_errors[]` now surfaces one structured `dry_run` item carrying the message (graph-level, so typically no `source`) — closing the structured-info gap that drove consumers to fabricate a category.- **Keyword-only argument enforcement** — a mechanical guard enforces the keyword-only argument convention across `pipelex/`, end to end — local autofix through the CI gate.- - **Keyword-only AST guard**: A custom AST-based linter (`pipelex-dev check-keyword-only` / `make cko`) that mechanically enforces the keyword-only argument convention across `pipelex/`, wired into `make check` and `make agent-check`.- - **Keyword-only auto-fix**: A non-gating `--fix` mode (`pipelex-dev check-keyword-only --fix` / `make fix-keyword-only` / `make fko`) that rewrites every mechanically-fixable violation by inserting a bare `*` as far left as possible (after `self`/`cls`), re-parsing each rewrite before writing and reporting the shapes it can't fix mechanically. It runs early in `make agent-check`; the read-only check still runs last and owns the pass/fail gate.- - **Claude Code hook**: A `PostToolUse` bash hook (`.claude/hooks/check-keyword-only.sh`) that runs the guard on edited files for immediate blocking feedback to AI agents.- - **CI integration**: A dedicated `lint-keyword-only` job in the GitHub Actions linting workflow to block non-compliant signatures from merging.- - **Convention documentation**: New `docs/contribute/keyword-only-arguments.md`, plus updates to `CLAUDE.md` and `AGENTS.md` establishing the keyword-only convention as a standing rule.+ - **Keyword-only AST guard**: A custom AST-based linter (`pipelex-dev check-keyword-only` / `make cko`) that mechanically enforces the keyword-only argument convention across `pipelex/`, wired into `make check` and `make agent-check`.+ - **Keyword-only auto-fix**: A non-gating `--fix` mode (`pipelex-dev check-keyword-only --fix` / `make fix-keyword-only` / `make fko`) that rewrites every mechanically-fixable violation by inserting a bare `*` as far left as possible (after `self`/`cls`), re-parsing each rewrite before writing and reporting the shapes it can't fix mechanically. It runs early in `make agent-check`; the read-only check still runs last and owns the pass/fail gate.+ - **Claude Code hook**: A `PostToolUse` bash hook (`.claude/hooks/check-keyword-only.sh`) that runs the guard on edited files for immediate blocking feedback to AI agents.+ - **CI integration**: A dedicated `lint-keyword-only` job in the GitHub Actions linting workflow to block non-compliant signatures from merging.+ - **Convention documentation**: New `docs/contribute/keyword-only-arguments.md`, plus updates to `CLAUDE.md` and `AGENTS.md` establishing the keyword-only convention as a standing rule.### Added- **`is_valid` on the canonical validation report**: `PipelexValidationReport` gains `is_valid: Literal[True] = True`, the always-true discriminant of the valid arm of the hosted `/validate` response union (mirrored by pipelex-api's `InvalidReport`'s `Literal[False]`). It sits beside `is_runnable`: a sound bundle may still be not-yet-runnable.- **Offline CLI unit tests**: Coverage for the pipelex-internal logic behind the CLI commands — `doctor` diagnostics, `run` execution and its sync wrapper, the `build` codegen cores, the readiness gate, `show`/`which`, and the gateway/telemetry/signature error handlers (the spec'd CLI interface stays owned by the conformance suite).- **Offline inference & runtime unit tests**: Coverage for layers that can break without a provider — structured-output↔instructor mode mapping, model-deck reference checks, the image-gen argument and worker-routing factories, gateway request-shaping and extract parsing, the Mistral factory, the local observer sink, the output renderer, builder spec validation / `to_blueprint()`, the pipeline runner's error paths, the TOML config-sync engine, and the storage config validators.+### Changed- **[BREAKING] Keyword-only public API**: Top-level public surfaces now require keyword arguments after the first parameter. A caller passing a second-or-later argument positionally must switch to keyword form — affected methods include `Pipelex.make(integration_mode, *, ...)`, `Pipelex.setup(integration_mode, *, ...)`, and `PipelexHub.setup_config(config_cls, *, ...)`. Downstream consumers to check: `pipelex-api`, `pipelex-worker`, `n8n-nodes-pipelex`, cookbook, starter.@@ -129,12 +131,12 @@- **Qualified same-domain pipe references resolve across files**: a controller referencing a sibling-file pipe by qualified name (`research.find_key_findings`) is now deferred to the merged library like bare references; a reference no file declares is still rejected at load.- **Concepts-only loading validates concept references**: the `pipelex structures` / `load_concepts_only` path now runs the cross-file concept-reference check (batching sibling files into one pass) instead of silently accepting a structure field pointing at an undeclared concept.- **Multi-file dependency packages reconcile signatures with their definitions**: a dependency package split into a `PipeSignature` header plus its concrete sibling now goes through the same additive merge instead of colliding on the duplicate code and dropping one declaration by load order.-- **OpenAI image moderation mapping was inverted**: `is_moderated=true` sent the *less* restrictive `moderation="low"` and `false` sent `"auto"` — the mapping now matches the flag (enabled → `"auto"`, disabled → `"low"`). `ImgGenSetting.is_moderated` also defaults to `None`, so workers omit the parameter and the provider's own default applies (which also stops force-disabling FAL's `enable_safety_checker`).+- **OpenAI image moderation mapping was inverted**: `is_moderated=true` sent the _less_ restrictive `moderation="low"` and `false` sent `"auto"` — the mapping now matches the flag (enabled → `"auto"`, disabled → `"low"`). `ImgGenSetting.is_moderated` also defaults to `None`, so workers omit the parameter and the provider's own default applies (which also stops force-disabling FAL's `enable_safety_checker`).- **Storage config validation now covers every provider and requires a real `{hash}` slot**: the `uri_format` check is enforced uniformly across local / in-memory / S3 / GCP — every placeholder must be a plain supported `{name}`, a `{hash}` slot is required (GCP previously accepted the bare substring `hash`, silently overwriting every stored object), and buckets must set a positive `signed_urls_lifespan_seconds`. A misconfigured format now fails fast at Pipelex boot instead of at the first content store.- **Mistral chat requests now send the system message before the user message**: `make_simple_messages` previously appended it after the user message, contradicting its own docstring and the OpenAI-typed sibling.- **String concept values in bundle specs are constructible again**: a bare string in the `ConceptSpec | str` union now validates (no longer crashing the `mode="before"` validator) and passes through to the blueprint as the concept's description instead of into `structure`, where the loader rejected it.- **LocalObserver JSONL records always carry the true lifecycle event name**: a payload's own `event_type` key can no longer overwrite the event name in the written record, which had broken event-type filtering for JSONL consumers.-- **Tests under `tests/**/build/` are no longer silently skipped**: pytest's default `norecursedirs` includes `build`, so the whole `tests/unit/pipelex/cli/commands/build/` tree was never collected; the config now overrides `norecursedirs` and sets `testpaths = ["tests"]`.+- **Tests under `tests/**/build/`are no longer silently skipped**: pytest's default`norecursedirs`includes`build`, so the whole `tests/unit/pipelex/cli/commands/build/`tree was never collected; the config now overrides`norecursedirs`and sets`testpaths = ["tests"]`.- **`Anything`-output option numbering is now deterministic**: the output renderer sorts a `PipeCondition`'s possible outputs by pipe code instead of iterating a set, so `output_option_N` / `schema_option_N` numbering is stable across runs.- **Documentation examples**: Updated code snippets in `docs/under-the-hood/` to match the new keyword-only signatures.- **Test mock assertions**: Migrated mock assertions from `.call_args.args` to `.call_args.kwargs` to reflect keyword-only calls.@@ -156,6 +158,7 @@- **`--dry-run` now mocks at the cogt leaf instead of swapping out the operators.** `run_mode` rides a new `CogtRunParams` carrier (derived from `PipeRunParams.run_mode`, stamped on every cogt assignment), so a DRY run mocks **inside** the inference leaf at zero AI cost, with no API keys and no storage IO (the img/extract DRY branches sit above the store step). `ContentGeneratorDry` is deleted: operators no longer swap generators (the base operator's dry path simply reuses the live path), and the in-process validation scopes pass an inline `ContentGenerator`. Object mocks are now schema-built; classes with exotic format constraints should declare `examples`/`mock_format` (a re-validation failure surfaces as a typed `DryRunObjectFidelityError`, and a deterministic mock-build failure as the new `DryRunMockBuildError`).- **Unified dry run — `--mock-inference` removed (breaking).** There is now exactly one non-live run mode: `--dry-run`. The mock-inference mode is retired; its capability — non-zero synthetic usage so the cost report renders — survives as an **internal** `is_mock_usage` sub-flag of DRY on `CogtRunParams` (replacing `is_mock_inference`; setting it on a LIVE run is a validation error). It is exposed on the Python surface (`PipelexMTHDSProtocol` / `execute` / `prepare_pipe_job` via `is_mock_usage=...`) and as a hidden test-only CLI trigger, deliberately undocumented. Dry-run leaf coverage was already uniform across every operator, so `MockInferenceUnsupportedError` and its img-gen/extract/search guards are deleted; `MockInferenceObjectFidelityError` is renamed `DryRunObjectFidelityError` (mock-built objects are DRY-only now); the `mock_inference` usage sentinel is renamed `mock_usage`.- **Keyless boot (`needs_inference=False`) now forces every run to DRY instead of installing a mock generator.** Generator selection is purely backend-keyed; the forced-DRY flag is consumed at `PipeRunParamsFactory.make_run_params` — the single writer of `run_mode` — so every execution entry point is covered, including the runtime bridge.+### Removed- **`dry_run_config.apply_to_jinja2_rendering`** config key: it was dead — PipeCompose renders templates directly and the jinja2 parse check survives in the templating leaf's DRY branch. Remove it from your `.pipelex/pipelex.toml` override if present (config is strict and will reject the unknown key).diff --git a/pipelex/core/memory/working_memory_factory.py b/pipelex/core/memory/working_memory_factory.pyindex b09395d07..3361f93a0 100644--- a/pipelex/core/memory/working_memory_factory.py+++ b/pipelex/core/memory/working_memory_factory.py@@ -231,8 +231,7 @@ class WorkingMemoryFactory(BaseModel):)if isinstance(typed_named_stuff_spec.multiplicity, bool):- # TODO: make this configurable or use existing config variable- nb_stuffs = 3+ nb_stuffs = 2else:nb_stuffs = typed_named_stuff_spec.multiplicity