Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Execution-errors-integration · L-260925-dd5b5c (#1276)

Louis Choquela7924f62ce59
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 204eb8ffe..83bb9f7b7 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:2ac30bcfcf3e7d174db15b59fa2df4e9cb64c5c6a2c64f1d9e8bef415a4efd8f"
-reviewed_by = "Claude (Opus 5.5)"
-reviewed_at = "2026-09-25T12:48:43Z"
-rationale = "Merge of origin/feature/Log-sink-seam (carrying dev's releases v0.61.0 through v0.65.0) into feature/Log-redaction. Against the parent the only trigger change is this branch's doctor_cmd.py arm that keeps an installed sink which failed during the replay of the held records, and the checks.log_sink row in pipelex/cli/agent_cli/CLAUDE.md carries that fourth case in the merged tree. Against this branch's previous head the only trigger change is the parent's check_model_cmd.py argument-help example moving from the retired @best-claude alias to @best-gpt, and neither docs/tools/cli/ nor the agent-CLI contract doc quotes that example or any retired deck alias (a grep for best-claude, best-gemini and best-mistral over both targets finds nothing). docs/tools/cli/agent-cli.md describes the doctor command by its flags and formats only, so nothing there is stale. The ack file's merge spliced the parent's header onto this branch's trigger snapshot, so this re-ack records the merged tree as reviewed as a whole. No doc change needed."
+digest = "sha256:904da72bdd9e3c4c1be10d5a10d7dbdeb3027b8b7a8fba9d40f6bdc1649f4d23"
+reviewed_by = "Louis Choquel"
+reviewed_at = "2026-09-26T23:58:30Z"
+rationale = "The sprint's pipelex stacks each acked cli-docs for their own changes (the unsafe-fix label and validate hint, dry-run items and parse items, the run-path verdict and factory refusals, root-fault run errors, and the model panel of pipelex run giving a caller-fault model error's change_model next step before its local-deck remedy); their docs/tools/cli and agent_cli/CLAUDE.md edits were merged side by side in the integration's conflict resolutions. docs/tools/cli/ does not describe the model panel's tip, which docs/errors/model-not-found-error.md documents, and the merge introduced no new CLI surface. No further doc change needed."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -12,7 +12,7 @@ rationale = "Merge of origin/feature/Log-sink-seam (carrying dev's releases v0.6
"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py" = "blob:cb8338c09a7b5dee6088551c156d69dab613213a"
"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:49b8bab889d8673e7d4f1d683efe0928e43914b9"
-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:3dc0283ef1daee4e17183b01f8a5c9d92f2688af"
+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:fd1f2d70111fa8f09cc2536e5ac8be70f87f243f"
"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:30339c5d91048f4e67312d5691ed9a65d57472e0"
"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:91589e517509248a4639a37e82f46a69538f8071"
"pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
@@ -29,9 +29,9 @@ rationale = "Merge of origin/feature/Log-sink-seam (carrying dev's releases v0.6
"pipelex/cli/agent_cli/commands/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:d37826d96099028a1ad5dbc5cbf8ce0cfdb01e30"
"pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:7e19284687b334c684fb03381a8d9d20af1aa152"
-"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:43ac0fe0887f5f31144df4e4973a1ab1d0dec166"
-"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:582c3dbf1c8199f1f79856ffcc536c7e1226d21c"
-"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:a5cf89c89d5e2e84cc7b817ec184e8dc9e92b781"
+"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:fcff51a97ae081a4fb40273dd6ec85c521179993"
+"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:025f52a0d9703ea8dbe30f2a466f925eaed03ae9"
+"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:d109d3103b2ad851d281a9ef1a91e2822e92926e"
"pipelex/cli/agent_cli/commands/lint_cmd.py" = "blob:91ad9cb4d618ba4c0b7da366cde2f74f38d350df"
"pipelex/cli/agent_cli/commands/migrate_cmd.py" = "blob:ce733b78df03e65c3c8a10d46b27b57c05ec054c"
"pipelex/cli/agent_cli/commands/models_cmd.py" = "blob:dde4c246a28eba9f54cd582f0b171c9c26194be8"
@@ -39,19 +39,19 @@ rationale = "Merge of origin/feature/Log-sink-seam (carrying dev's releases v0.6
"pipelex/cli/agent_cli/commands/plxt_passthrough.py" = "blob:a1c530d110482485ce462f199b9e79fac29f8896"
"pipelex/cli/agent_cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/run/_output_helpers.py" = "blob:40ed1700e0d5e86d7696eadd7f9887baeb8059f6"
-"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:3721f0e9288fc7611917839ab303418a983a6883"
+"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:32f973c5c754b23016f3e708ab3235856e8bc5f4"
"pipelex/cli/agent_cli/commands/run/_run_core_api.py" = "blob:78a27e0ba91e6bbf99c11caedb29ad4cf20ac78b"
"pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d"
-"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:daf6207146c0ea41fe34bb272ed51350208af790"
-"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:f61145e5706f2b36134aafe844653ae6d719be8c"
-"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:df5e7f80a328932ffde901eda8d0585d009678ad"
+"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:75ba7ca72660b3a2712c749d16880e64f27f21ce"
+"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:88b358831184dd9c0ba6f9cb2b62e29aa1b10f83"
+"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:65d8aa4bcf87abbb36207afaa047164cc53a4e4e"
"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:c7c7d7495508f1c4e5a46eba336a4ab1694ebcf7"
"pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:df07de7f203f57041907e080bc5fd80f9f593301"
+"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:96d0f9f178739dd5a2e659cb392760b8a2bbcb32"
"pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86"
-"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:27cc2c0b0a7fb5d3a232c6c3ce44663572e14260"
-"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:794914167c13975bc0cdff7b301a8268ff1b79b6"
-"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:2f7dce6a1d3d9987aa14146bac79d6b0e7e985e1"
+"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:b3f17f88fc74d02abf8a167af69f4275a8e8c6c8"
+"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:cf841e73d6af1a7e90d5ddfadaad012928f1a3ba"
+"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:b5aae81bc47ed8de23a13755b2c8c2418b4b8b9a"
"pipelex/cli/bundle_target_resolution.py" = "blob:8dccc50b700b877968ed1b2c1c3652ab1c32e956"
"pipelex/cli/cli_factory.py" = "blob:1f859ab3b995e1a67e5fdc812a168d56c338e970"
"pipelex/cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
@@ -84,8 +84,8 @@ rationale = "Merge of origin/feature/Log-sink-seam (carrying dev's releases v0.6
"pipelex/cli/commands/crate_loading.py" = "blob:3d7d651931ecf1a15a3e2d72411b3212b55d74ef"
"pipelex/cli/commands/doctor_cmd.py" = "blob:26db32ff20d1c064bc421093825a05e980c9b770"
"pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:5ce264f5b0ab4ff4172f4d8789450916947f5c0e"
-"pipelex/cli/commands/fix/_fix_core.py" = "blob:8f6a187a0fb42c498629b177753d81620800b0da"
+"pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:d39c0df92b95567f74881deb01f8c1b3119fc8ef"
+"pipelex/cli/commands/fix/_fix_core.py" = "blob:dac7056fcaf50210c910e4cad1ba14328b7f8adc"
"pipelex/cli/commands/fix/app.py" = "blob:6f019930e8e3e0043ee46d87493ba4602eb33a76"
"pipelex/cli/commands/fix/bundle_cmd.py" = "blob:427364cc453957dfe0cec879f019050329c13b3c"
"pipelex/cli/commands/graph_cmd.py" = "blob:d54737af7efc9ab9bbf3f978050d017af0e27a41"
@@ -111,7 +111,7 @@ rationale = "Merge of origin/feature/Log-sink-seam (carrying dev's releases v0.6
"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:dde781f846968b667a0acfb4b3e3cea01cef7049"
"pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab"
-"pipelex/cli/commands/run/_run_core.py" = "blob:21658e84a1f23be0ce12801bfdb17268c37f797f"
+"pipelex/cli/commands/run/_run_core.py" = "blob:5d654266156eac27505530d83cea2a55bc1c5e75"
"pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148"
"pipelex/cli/commands/run/bundle_cmd.py" = "blob:cb420bf4879c863d64c5e20ed535c42732b720a2"
"pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"
@@ -120,14 +120,14 @@ rationale = "Merge of origin/feature/Log-sink-seam (carrying dev's releases v0.6
"pipelex/cli/commands/show_cmd.py" = "blob:9492c9af966877f694ca61f7b1db3d151a1ddf56"
"pipelex/cli/commands/update_cmd.py" = "blob:06100ec3b9d6c66ca89a8c1536aa27983ae409ca"
"pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/commands/validate/_validate_core.py" = "blob:3294c9c716ac616a89213c7356d38a8eff62da40"
+"pipelex/cli/commands/validate/_validate_core.py" = "blob:237c57bd815b6fa75e1fee28069f75ec6c5b7726"
"pipelex/cli/commands/validate/app.py" = "blob:309061423af13f2f6c496a024306ad696af567ab"
"pipelex/cli/commands/validate/bundle_cmd.py" = "blob:1fbf3e0cf695db39101c83160a724df6468988e9"
"pipelex/cli/commands/validate/method_cmd.py" = "blob:f12ee233fc985d04a4512f1fef6b9ea02a1b9644"
"pipelex/cli/commands/validate/pipe_cmd.py" = "blob:d67267571559006459628180f2c8b216ba7fee31"
"pipelex/cli/commands/which_cmd.py" = "blob:68661d4bab22e2c4dab183d59bd9f2c6dd573472"
"pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"
-"pipelex/cli/error_handlers.py" = "blob:41f33d7eae4d583f380f3ec34637733b0ca9d840"
+"pipelex/cli/error_handlers.py" = "blob:4b97a9c89d9b2532f0a9d1406baad130fc4d56f7"
"pipelex/cli/exceptions.py" = "blob:1d51c3a53ddd3f6cf8de566fa2ade3fa75ab7a3a"
"pipelex/cli/installed_methods.py" = "blob:09197f47baf8d7251d28d148a0544b4a23ee7365"
"pipelex/cli/method_resolver.py" = "blob:1230dde5f89ac28bbdcbcbbd0c1d485c71803caf"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc8e7ba28..a43a6599c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,34 @@
# Changelog
+## [Unreleased]
+
+### Added
+
+- **An unknown model is a located `unknown_model` validation item**: a pipe whose model field names a handle, alias, preset or waterfall the model deck does not define now validates to an invalid verdict with one `pipe_validation` item of the new closed `error_type` `unknown_model`, carrying the `pipe_code`, `domain_code`, `source`, `field_name`, the `field_path` of the reference (`pipe.<code>.model`, or `pipe.<code>.model_to_structure`), and the new optional item fields `model_reference` (the reference as written), `model_type` and `suggestions` (the deck's close matches of the same kind, also kept in the message). Every pipe type that names a model gives the same item, where `PipeExtract` and `PipeSearch` used to give an `unknown_validation_error` whose message was a Python repr, and with exactly one suggestion the item carries an unsafe `rename-model` fix, which `pipelex fix bundle` never applies on its own because a fuzzy match can name a different model. The MTHDS Test Corpus gains the `invalid_unknown_model` entry covering the new `error.unknown_model` tag.
+- **An unsafe suggested fix says so wherever it is printed**: the per-error line of `pipelex validate`, of `pipelex fix`'s remaining errors and of every `pipelex-agent` Markdown rendering, the `rendered_markdown` shared with `/validate` included, reads `💡 Suggested fix (unsafe, confirm before applying):` for a fix whose `safety` is `unsafe`, while a safe fix keeps the plain `💡 Suggested fix:` line, so a person or an agent can tell which fixes to check before making them by hand.
+- **Validation items carry the positions and declared concepts the parser knew**: a TOML syntax error's item carries the 1-based `line` and `column` the parser stopped at, as new optional item fields, and an `unresolved_concept` item carries `declared_concepts`, the bare codes of the concepts the validated bundle declares in its domain, so an editor can anchor the diagnostic and an author sees what the reference could have named.
+
+### Changed
+
+- **Every refusal raised while loading a bundle is a validation verdict (Breaking)**: validation turns any refusal of the caller's input that has no arm of its own into an invalid verdict with one item, keeping the refusal's message only when it is caller-facing and otherwise its title, while a configuration or runtime fault still propagates as no verdict. A refusal raised while a pipe is built leaves the library load as the new `PipeLoadRefusalError`, naming the pipe, its domain and its file with the original as its cause, and gives a `pipe_validation` item located there; any other gives a `blueprint_validation` item. `pipelex validate bundle` no longer prints a traceback for an unknown model, `pipelex-agent validate bundle` answers it with `is_valid: false` and exit 1 instead of the no-verdict envelope and exit 2, and the in-process validator behind `/validate` returns it as an invalid verdict instead of raising.
+- **`PipeOperatorModelChoiceError` is the located unknown-model refusal (Breaking)**: it is now raised whenever a pipe naming an unknown model is built, with a message naming the pipe and the field; it is `input`-domained and caller-facing, carries `domain_code`, `field_name`, `suggestions` and `source`, and its `model_choice` is the reference as written. The agent CLI's hint for it points at `check-model` rather than `doctor`.
+- **A `PipeParallel` branch whose multiplicity differs from its field's is refused with the fix to make**: when the combine of the branch results refuses a list branch fed into a single field, or a single branch fed into a list field, the refusal now names the parallel, the branch, the result and the field, and says to declare the field with the branch's multiplicity or to make the branch produce the field's, instead of reporting a Python validation error about `ListContent`. The dry run of `pipelex validate` and `pipelex-agent validate` carry it in their `dry_run` item, and a run reports it as a `StuffFactoryError` in the `input` domain, so a hosted runner under STRICT disclosure answers a 422 whose message and `change_input` next step name the change, where it answered `An internal error occurred.`.
+- **The invalid-bundle verdict's next step points at its items**: `ValidateBundleError`'s user action, the `💡 Tip:` of `pipelex validate` and the `hint` of `pipelex-agent`'s JSON, now reads "Edit the bundle as each validation error says: apply its suggested fix where it has one, after confirming an unsafe one" instead of "Check the validation_errors array for specific issues".
+- **A run refuses an invalid bundle with the validation verdict (Breaking)**: a run loads its bundle before any pipe runs, and a bundle that load refuses now raises `ValidateBundleError` with the same located `validation_errors` validating it gives, which a hosted run route answers as an HTTP 422 that keeps them under STRICT disclosure, instead of the raw class of whichever check refused it (a 500 for a misspelled concept or a wiring mismatch, a 422 without items for a TOML fault, a `runtime` `PipeExecutionError` for a check inside a pipe's validator, a `PipeOperatorModelChoiceError` for an unknown model); an unknown entry pipe still raises its `PipeNotFoundError`. `pipelex run` prints the grouped panel `pipelex validate` prints, `pipelex-agent run` and any other agent error envelope caused by such a verdict carry its `validation_errors`, and the runner's new `library_dirs_are_callers` option, which both CLIs set, gives a refusal in the caller's own library directories the same verdict while a host's directories still load untranslated.
+- **A pipe factory's refusal is a located validation item**: `PipeLLMFactoryError`, `PipeComposeFactoryError`, `PipeExtractFactoryError`, `PipeConditionFactoryError` and `PipeParallelFactoryError` are now `input`-domained and caller-facing, so a `PipeExtract` whose input is neither an image nor a document validates to a `pipe_validation` item on that pipe and its file, whose message names the input and says to redeclare it, where it used to escape every validator as no verdict; a `PipeLLM` whose prompt or inherited system prompt does not parse is refused with the line of that prompt it fails at and no longer quotes any of the prompt, which may be a host's; the builder's `validate_ops.validate_pipe` and `validate_all` also answer a refusal raised while they load libraries or dry-run a pipe with the `ValidateBundleError` verdict instead of the raw error. `pipelex-agent validate pipe --all` now keeps the file on an item raised while its libraries load, where it used to lose it because the refusal was translated only after the failed library was torn down.
+- **`pipelex validate pipe` and `pipelex validate --all` render a refusal as an invalid bundle**: a pipe whose dry run fails, and a refusal of the libraries while they load, now print the grouped invalid-bundle output and exit 1 instead of a traceback; `pipelex-agent validate pipe` and `--all` answer a load-time refusal with the invalid-verdict envelope.
+- **A failing dry run is one located item per failing pipe (Breaking)**: validation reports a dry-run failure as one `dry_run` item per failing pipe, with the error type `DryRunError` and the `pipe_code`, `domain_code` and `source` of the innermost pipe that failed and is not allowed to fail (when submitted content is validated beside a host's library directories, the `source` only for that content's own pipes, never a file of the host's own library directories), where it used to report one item holding a Python repr of the sweep's records, once more for every controller the failure passed through. The item keeps the failure's own message only when that message is caller-facing and otherwise names the failure's title, so a configuration or storage failure met during a dry run no longer reaches a hosted caller through the verdict; `pipelex validate` lists the items under `Dry Run Errors:`, `pipelex-agent validate pipe` and `validate pipe --all` answer a failing dry run with the invalid-verdict envelope and its items instead of a `DryRunError` envelope with none, and the agent `inputs` commands drop their `dry_run_error` key. In Python, `ValidateBundleError` takes `dry_run_failures` in place of `dry_run_error_message`, and `DryRunError` carries `failures`.
+- **A run failure reports its root fault, located at the failing pipe (Breaking)**: the report of a `PipelineExecutionError`, and of the `PipeRouterError` under it, now carries the `error_type`, `title`, `type_uri`, caller-facing flag and own message of the root fault, the innermost Pipelex error on the cause chain, with the message prefixed by the failing pipe and its path (`Pipe 'summarize' failed (two_steps → summarize): …`), and the exception's `pipe_code` and `pipe_stack` name that pipe instead of the entry pipe. A bridge's sentence no longer reaches the report, a report recovered from a remote worker is taken as it is, so a run reports the same failure in process, through the in-process orchestrator or on a worker, and the fallback action names the failing pipe instead of saying `Check pipe_stack to identify which pipe failed`. A consumer branching on `error_type == "PipelineExecutionError"` branches on the root fault's type instead, as [the error model](under-the-hood/error-model.md#run-failures-the-root-fault-located) describes.
+- **The pipe router locates every failure (Breaking)**: `PipeRouterProtocol.run()` now re-raises any failure of its pipe as a `PipeRouterError` chained to it, where it used to let everything but a `CogtError` through, and a failure already located by an inner router rises untouched. An exception that is not a Pipelex error becomes a `PipelexUnexpectedError` whose message names its class, and a host router overrides the new `_as_pipelex_failure()` hook to convert its transport's failures or let a control-flow exception through. Code that caught a pipe's own error class from `get_pipe_router().run()` catches `PipeRouterError` and reads its `__cause__`.
+- **`ModelNotFoundError`'s message states the fact only**: a handle missing from the model deck reads `Model handle '<handle>' was not found in the model deck.`, without the local-deck advice it used to carry into every surface, hosted runs included. `pipelex run` now renders the model panel for a run failure, naming the failing pipe, the model and the pipe stack, and the panel's tip carries that advice.
+- **The agent CLI's run errors name the root fault**: `pipelex-agent run` reports a failed run's `pipe_code` and `pipe_stack` at the failing pipe, and its `cause_type` and `cause_message` are the root fault's instead of the wrapper right under the run error.
+
+### Fixed
+
+- **Every validation error reaches the reader**: an error the blueprint categorizer does not know, such as a misspelled field, is its own `blueprint_validation` item without an `error_type`, carrying its `source`, `pipe_code` and `field_path`, where it used to vanish whenever another item existed and surface only once that one was fixed; and `format_pydantic_validation_error` renders every error it is given, listing the kinds without a heading of their own under "Other validation errors" whatever else is present.
+- **A validation verdict names no path on the host**: an item located inside a package the method depends on by address, and a duplicate declaration inside that package, now name the bundle by the package's address and its path inside the package (`github.com/acme/harbour-methods/tides/notices/tide_notices.mthds`) instead of the directory the host installed it in, on every surface; and when submitted content is validated or run beside a host's own library directories, an item located in one of their files carries no `source` or `field_path` naming it and a message that named such a file, or the module one of their Python files was imported as, reads `<host library file>`, so STRICT disclosure no longer hands a hosted caller a path on the server. A bundle validated from a file keeps the full paths of its own library directories, and so does content validated against directories that are the caller's: `validate_bundle` and `validate_bundles_in_process` take `library_dirs_are_callers`, which `PipelexMTHDSProtocol.validate` now passes as its `execute` does.
+- **A run that fails on the caller's own method reads its reason under STRICT disclosure**: a `PipeParallel` whose branch results do not fit its output, a pipe started without a required input, a `PipeCondition` whose expression renders nothing, whose outcome is `fail` or whose chosen pipe misses inputs, and a step naming in an inline setting a model the deck neither defines nor names now report the `input` domain, so an HTTP surface answers 422 instead of 500, a message STRICT disclosure keeps instead of `An internal error occurred.`, and a next step: for the model, a `change_model` action naming the model as the method wrote it and the type of model its pipe needs, which the model panel of `pipelex run` follows with its local-deck advice. A `PipeCondition`'s dry-run refusals, among them an expression rendering nothing and every outcome mapped to `fail`, now give a `dry_run` item carrying their reason instead of the title `Pipe run`, and name the missing pipes or the line an unparsable expression fails at instead of printing the outcome map or the expression; a `fail` outcome's message names the pipe and no longer the value its expression rendered. A model that the deck itself names but does not serve stays a redacted `config` error. The new `PipelexError.as_caller_fault()` is how a raise site classifies one error of a class whose other instances are not the caller's fault, as [the error model](under-the-hood/error-model.md#classified-where-it-is-raised) describes.
+
## [v0.66.1] - 2026-09-26
### Added
diff --git a/docs/building-methods/pipes/pipe-controllers/PipeCondition.md b/docs/building-methods/pipes/pipe-controllers/PipeCondition.md
index 34ca78fd2..164110092 100644
--- a/docs/building-methods/pipes/pipe-controllers/PipeCondition.md
+++ b/docs/building-methods/pipes/pipe-controllers/PipeCondition.md
@@ -15,6 +15,8 @@ The `PipeCondition` controller adds branching logic to your pipelines. It evalua
3. **Use Default**: If the key is not found in `outcomes`, the `default_outcome` is used.
4. **Execute Chosen Pipe**: The chosen pipe is then executed. It receives the exact same `WorkingMemory` and inputs that were passed to the `PipeCondition` operator. The output of the chosen pipe becomes the output of the `PipeCondition` itself.
+When the expression renders nothing, no outcome can be chosen and the pipe fails with `Conditional expression returned no result`, naming the pipe. That refusal and the others a condition makes are faults in your method, each reported with its reason and a next step. In a run, an expression that renders nothing, a `fail` outcome and a chosen pipe whose inputs are missing fail the run, which a hosted run answers with HTTP 422. In the dry run of `pipelex validate`, which runs every branch instead of choosing one, an expression that renders nothing over the mock inputs and a condition whose every outcome is `fail` give a `dry_run` item.
+
## Configuration
`PipeCondition` is configured in your pipeline's `.mthds` file.
@@ -144,7 +146,7 @@ Process this unknown document type...
Beside pipe names, an outcome (or the `default_outcome`) can be one of two special outcomes:
-- **`fail`**: the run fails loudly with an error naming the pipe and the evaluated expression. Use it to make "this should never happen" branches explicit.
+- **`fail`**: the run fails loudly with an error naming the pipe. Use it to make "this should never happen" branches explicit. The failure is a refusal written into your method, so a hosted run answers it with HTTP 422 and keeps its message, with a next step, under STRICT disclosure. The message leaves out the value the expression rendered, which the run's execution graph keeps: that value can be text of a condition a host's library declared.
- **`continue`**: the condition declares that it produced **no output**. The runtime records an absence for the declared output (with the evaluated expression as the reason) and the run continues as a success — the rest of the working memory is unchanged.
Because `continue` resolves the declared output as absent, a `continue`-reachable condition (any outcome mapped to `continue`, or `default_outcome = "continue"`) **must declare its output optional** — `output = "Constraint?"`. Validation enforces this statically (`optional_output_required`), so the no-output path is always visible to the type system. The same visibility rule applies at the condition's boundary: if a mapped outcome pipe declares an optional output, the condition must declare `?` too (`optional_not_handled`).
diff --git a/docs/building-methods/pipes/pipe-controllers/PipeParallel.md b/docs/building-methods/pipes/pipe-controllers/PipeParallel.md
index 93f0caac3..380f6cf4c 100644
--- a/docs/building-methods/pipes/pipe-controllers/PipeParallel.md
+++ b/docs/building-methods/pipes/pipe-controllers/PipeParallel.md
@@ -32,6 +32,14 @@ A branch result may legitimately be **absent** at run time: the branch pipe decl
- **Structured output, non-required field**: the absence is absorbed as the field's default (`null` unless the field declares another default).
- **Structured output, required field**: this is rejected **statically** at validation time (`optional_branch_required_field`) — a required field cannot be fed by a maybe-absent branch. Make the field non-required, or sink the absence upstream with a `?` input on the branch path.
+### A branch and its field must agree on multiplicity
+
+A branch that produces a list, such as a `PipeBatch` whose output is `Idea[]`, fills a field that holds a list, and a branch that produces one item fills a field that holds one item. When they disagree, the combine refuses the branch results, in the dry run of `pipelex validate` as in a run, and the refusal names the branch, its result and the field, and says which of the two to change; when the branch's multiplicity comes from its own `nb_output`, `multiple_output` or `batch_over` in `branches`, the refusal names that setting instead of the pipe's output. The advice is given only when the branch's concept fits the field, and whatever else the combine refused is reported beside it. The refusal is a fault in your method, so a hosted run answers it with HTTP 422 and keeps its message under STRICT disclosure, with the change to make as its next step:
+
+```text
+PipeParallel 'analyze_topics' cannot combine its branch results into its output 'TopicReview'. Branch 'draft_ideas' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'TopicReview' holds a single item. Declare the field as a list in the structure of 'TopicReview', with type 'list', item_type 'concept' and item_concept_ref 'Idea', or make branch 'draft_ideas' output a single 'Idea'.
+```
+
## Configuration
`PipeParallel` is configured in your pipeline's `.mthds` file.
diff --git a/docs/contribute/mthds-test-corpus.md b/docs/contribute/mthds-test-corpus.md
index b8e114d89..45aca9517 100644
--- a/docs/contribute/mthds-test-corpus.md
+++ b/docs/contribute/mthds-test-corpus.md
@@ -48,7 +48,7 @@ An entry directory holds either exactly one `.mthds` file, or several with a `bu
]
```
-4. **Name no model.** Presets and aliases are resolved by the validation engine, not only at run time, so an entry pinning one fails validation outright on any consumer whose deck does not define it — which turns an entry about a language feature into an entry about model selection. Leave the choice to each consumer's deck.
+4. **Name no model.** Presets and aliases are resolved by the validation engine, not only at run time, so an entry pinning one fails validation outright on any consumer whose deck does not define it — which turns an entry about a language feature into an entry about model selection. Leave the choice to each consumer's deck. The one entry that names a model is `invalid_unknown_model`, whose defect is exactly that: it names a handle no deck defines, so it fails with `unknown_model` on every consumer.
5. **Validate it locally** — against the local runtime, never the hosted API, which lags it:
diff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.md
index 6b20b8107..2e89f551a 100644
--- a/docs/errors/authoring-and-language.md
+++ b/docs/errors/authoring-and-language.md
@@ -42,6 +42,7 @@ own page. Classes are grouped by subsystem.
- [`PipeFactoryError`](pipe-factory-error.md) — Pipe factory
- [`PipeInputError`](pipe-input-error.md) — Pipe input
- [`PipeInputsFactoryError`](pipe-inputs-factory-error.md) — Pipe inputs factory
+- [`PipeLoadRefusalError`](pipe-load-refusal-error.md) — Pipe load refusal
- [`PipeOperatorModelChoiceError`](pipe-operator-model-choice-error.md) — Pipe operator model choice
- [`PipeRunError`](pipe-run-error.md) — Pipe run
- [`PipeRunInputsError`](pipe-run-inputs-error.md) — Pipe run inputs
diff --git a/docs/errors/dry-run-error.md b/docs/errors/dry-run-error.md
index af0919cc1..239101b17 100644
--- a/docs/errors/dry-run-error.md
+++ b/docs/errors/dry-run-error.md
@@ -7,7 +7,7 @@ description: "Reference for the `DryRunError` Pipelex error class."
# Dry run
-Raised when a dry run fails due to missing inputs or other validation issues.
+Raised when a dry run fails. The validation sweep raises it with one failure per pipe whose dry run failed, located at the innermost failing pipe that is not allowed to fail, so a controller that failed because a pipe it runs failed is reported once, at that pipe. Bundle validation reports each failure as its own ``dry_run`` item, with the error type ``DryRunError``, the pipe's code, domain and source, and a message that keeps the failure's own text only when that text is caller-facing and otherwise names the failure's title.
| Field | Value |
|---|---|
diff --git a/docs/errors/model-choice-not-found-error.md b/docs/errors/model-choice-not-found-error.md
index 39179d80d..2e5851019 100644
--- a/docs/errors/model-choice-not-found-error.md
+++ b/docs/errors/model-choice-not-found-error.md
@@ -7,7 +7,7 @@ description: "Reference for the `ModelChoiceNotFoundError` Pipelex error class."
# Model choice not found
-Error raised when a model choice cannot be found in the model deck.
+Raised when a model reference names a handle, alias, preset or waterfall the model deck does not define: by the deck check a pipe runs when it is built, and by the deck when a run resolves a reference. When a pipe is built, the pipe operator raises it again as a ``PipeOperatorModelChoiceError`` located on the pipe and the field, so a bundle naming an unknown model is an invalid validation verdict (error type ``unknown_model``), never a failure of the validator.
| Field | Value |
|---|---|
diff --git a/docs/errors/model-not-found-error.md b/docs/errors/model-not-found-error.md
index 02571c58b..73bf40725 100644
--- a/docs/errors/model-not-found-error.md
+++ b/docs/errors/model-not-found-error.md
@@ -3,10 +3,21 @@ title: "Model not found"
description: "Reference for the `ModelNotFoundError` Pipelex error class."
---
-<!-- pipelex:generated -->
+<!-- pipelex:authored -->
# Model not found
+A model the run needs is not available: either the model handle is not in the model deck, or the provider answered that the model does not exist (HTTP 404). The provider case raises one of the subclasses per inference kind.
+
+A handle missing from the model deck is reported with the fact alone, `Model handle 'x' was not found in the model deck.`, because the message reaches every surface a run failure reaches, a hosted run's stored error included. When the model belongs to a pipe of a run, the run's report is this error's, located: `Pipe 'summarize' failed (two_steps → summarize): Model handle 'x' was not found in the model deck.`
+
+Whose fault it is depends on who named the model:
+
+- **The caller's**, when the deck neither defines the reference nor names it in any of its own entries. Only the method being run can have named it, in an inline model setting such as `model = { model = "gpt-5.1", temperature = 0.2 }`, which the check at load does not look into. A model the deck serves only as another type, such as an LLM named in an image-generation setting, counts as undefined here, since the lookup of this type refuses it, unless one of the deck's own entries for this type names it. The error is then in the `input` domain, so an HTTP surface answers 422, and its message survives STRICT disclosure together with its next step, a `change_model` action naming the reference as the method wrote it and the type of model its pipe needs, never the type the deck serves it as: `Change the model 'gpt-5.1' to an LLM the model deck serves.` It is the same mistake that `ModelChoiceNotFoundError` reports at load for a reference written as a string, except for a model of another type, which the check at load does not tell apart and which therefore surfaces only here.
+- **The deployment's**, when the deck itself names the reference but cannot serve it: a preset, an alias target, a waterfall fallback or a default whose backend is not enabled. The domain is then `config`, the answer is 500, and the message is redacted under STRICT disclosure.
+
+When you run a method locally with `pipelex run`, the CLI renders a panel naming the pipe, the model and the pipe stack. For a reference only the method names, its tip gives the `change_model` next step first, then the remedy for a local setup, since a local deck can be what lacks the model; for a reference the deck names, it gives that remedy alone: your local model deck may be out of date, so delete the files under `.pipelex/inference/deck/` and run `pipelex init inference` to regenerate them, then check that the handle routes to an enabled backend you hold credentials for.
+
| Field | Value |
|---|---|
| `error_type` | `ModelNotFoundError` |
diff --git a/docs/errors/pipe-compose-factory-error.md b/docs/errors/pipe-compose-factory-error.md
index 966924c21..9d28ef8df 100644
--- a/docs/errors/pipe-compose-factory-error.md
+++ b/docs/errors/pipe-compose-factory-error.md
@@ -7,12 +7,14 @@ description: "Reference for the `PipeComposeFactoryError` Pipelex error class."
# Pipe compose factory
+Raised when a ``PipeCompose`` has no template in template mode, or its template does not parse.
+
| Field | Value |
|---|---|
| `error_type` | `PipeComposeFactoryError` |
| `title` | Pipe compose factory |
| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-compose-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
+| `error_domain` | `input` |
| Defined in | `pipelex.pipe_operators.compose.exceptions` |
| Parent class | [`PipeComposeError`](pipe-compose-error.md) |
diff --git a/docs/errors/pipe-condition-factory-error.md b/docs/errors/pipe-condition-factory-error.md
index f50953eaa..3db09611a 100644
--- a/docs/errors/pipe-condition-factory-error.md
+++ b/docs/errors/pipe-condition-factory-error.md
@@ -7,12 +7,14 @@ description: "Reference for the `PipeConditionFactoryError` Pipelex error class.
# Pipe condition factory
+Raised when a ``PipeCondition`` declares neither ``expression_template`` nor ``expression``.
+
| Field | Value |
|---|---|
| `error_type` | `PipeConditionFactoryError` |
| `title` | Pipe condition factory |
| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-condition-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
+| `error_domain` | `input` |
| Defined in | `pipelex.pipe_controllers.condition.exceptions` |
| Parent class | [`PipelexError`](pipelex-error.md) |
diff --git a/docs/errors/pipe-extract-factory-error.md b/docs/errors/pipe-extract-factory-error.md
index 67b0e87ee..2020930f6 100644
--- a/docs/errors/pipe-extract-factory-error.md
+++ b/docs/errors/pipe-extract-factory-error.md
@@ -7,12 +7,14 @@ description: "Reference for the `PipeExtractFactoryError` Pipelex error class."
# Pipe extract factory
+Raised when a ``PipeExtract``'s input is neither an image nor a document.
+
| Field | Value |
|---|---|
| `error_type` | `PipeExtractFactoryError` |
| `title` | Pipe extract factory |
| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-extract-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
+| `error_domain` | `input` |
| Defined in | `pipelex.pipe_operators.extract.exceptions` |
| Parent class | [`PipelexError`](pipelex-error.md) |
diff --git a/docs/errors/pipe-llm-factory-error.md b/docs/errors/pipe-llm-factory-error.md
index e7a28b502..840258f57 100644
--- a/docs/errors/pipe-llm-factory-error.md
+++ b/docs/errors/pipe-llm-factory-error.md
@@ -7,12 +7,14 @@ description: "Reference for the `PipeLLMFactoryError` Pipelex error class."
# Pipe LLM factory
+Raised when a ``PipeLLM``'s prompt template, or the system prompt it declares or inherits from its domain, does not parse.
+
| Field | Value |
|---|---|
| `error_type` | `PipeLLMFactoryError` |
| `title` | Pipe LLM factory |
| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-llm-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
+| `error_domain` | `input` |
| Defined in | `pipelex.pipe_operators.llm.exceptions` |
| Parent class | [`PipelexError`](pipelex-error.md) |
diff --git a/docs/errors/pipe-load-refusal-error.md b/docs/errors/pipe-load-refusal-error.md
new file mode 100644
index 000000000..9cf0eb867
--- /dev/null
+++ b/docs/errors/pipe-load-refusal-error.md
@@ -0,0 +1,21 @@
+---
+title: "Pipe load refusal"
+description: "Reference for the `PipeLoadRefusalError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Pipe load refusal
+
+Raised by the library load when building one pipe of a bundle raises a refusal of the caller's input that carries no locator of its own. It names the pipe and its file, and bundle validation reports it as an invalid verdict.
+
+| Field | Value |
+|---|---|
+| `error_type` | `PipeLoadRefusalError` |
+| `title` | Pipe load refusal |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-load-refusal-error/` |
+| `error_domain` | `input` |
+| Defined in | `pipelex.core.pipes.exceptions` |
+| Parent class | [`PipelexError`](pipelex-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/pipe-operator-model-choice-error.md b/docs/errors/pipe-operator-model-choice-error.md
index 1c99cc1c2..75e3611a6 100644
--- a/docs/errors/pipe-operator-model-choice-error.md
+++ b/docs/errors/pipe-operator-model-choice-error.md
@@ -7,12 +7,14 @@ description: "Reference for the `PipeOperatorModelChoiceError` Pipelex error cla
# Pipe operator model choice
+Raised by a pipe operator (``PipeLLM``, ``PipeStructure``, ``PipeImgGen``, ``PipeExtract``, ``PipeSearch``) when it is built from its blueprint and a model field names a model the model deck does not define. Bundle validation reports it as an invalid verdict whose item has the error type ``unknown_model``, and a run, which loads its bundle before any pipe runs, refuses the bundle with that same verdict.
+
| Field | Value |
|---|---|
| `error_type` | `PipeOperatorModelChoiceError` |
| `title` | Pipe operator model choice |
| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-operator-model-choice-error/` |
-| `error_domain` | _(inherited from parent)_ |
+| `error_domain` | `input` |
| Defined in | `pipelex.core.pipes.exceptions` |
| Parent class | [`PipelexError`](pipelex-error.md) |
diff --git a/docs/errors/pipe-parallel-factory-error.md b/docs/errors/pipe-parallel-factory-error.md
index 04847290b..685a602be 100644
--- a/docs/errors/pipe-parallel-factory-error.md
+++ b/docs/errors/pipe-parallel-factory-error.md
@@ -7,12 +7,14 @@ description: "Reference for the `PipeParallelFactoryError` Pipelex error class."
# Pipe parallel factory
+Raised when a ``PipeParallel`` branch names no ``result``.
+
| Field | Value |
|---|---|
| `error_type` | `PipeParallelFactoryError` |
| `title` | Pipe parallel factory |
| `type_uri` | `https://docs.pipelex.com/latest/errors/pipe-parallel-factory-error/` |
-| `error_domain` | _(inherited from parent)_ |
+| `error_domain` | `input` |
| Defined in | `pipelex.pipe_controllers.parallel.exceptions` |
| Parent class | [`PipelexError`](pipelex-error.md) |
diff --git a/docs/errors/pipe-router-error.md b/docs/errors/pipe-router-error.md
index cc67ef7b2..e0735e8eb 100644
--- a/docs/errors/pipe-router-error.md
+++ b/docs/errors/pipe-router-error.md
@@ -3,10 +3,16 @@ title: "Pipe router"
description: "Reference for the `PipeRouterError` Pipelex error class."
---
-<!-- pipelex:generated -->
+<!-- pipelex:authored -->
# Pipe router
+A pipe failed while running: the failure, located at the pipe where it happened.
+
+The pipe router raises it around every failure of the pipe it runs, chained to that failure, with the pipe's code (`pipe_code`) and a snapshot of its path from the entry pipe (`pipe_stack`). A failure that already carries one rises untouched through the routers of the pipe controllers above it, so the location is always the innermost one. An exception that is not a Pipelex error is first turned into a [`PipelexUnexpectedError`](pipelex-unexpected-error.md) whose message names its class.
+
+Like [`PipelineExecutionError`](pipeline-execution-error.md), which wraps it when the run fails, it reports its **root fault** rather than itself: the `error_type`, `title`, `type_uri` and caller-facing flag are the root fault's, and the message is the root fault's own, prefixed with `Pipe '<code>' failed (<path>): `. The classification comes from the cause chain. See [the error model](../under-the-hood/error-model.md#run-failures-the-root-fault-located) for the full rules.
+
| Field | Value |
|---|---|
| `error_type` | `PipeRouterError` |
diff --git a/docs/errors/pipe-run-inputs-error.md b/docs/errors/pipe-run-inputs-error.md
index 626ddf45a..9e0221e07 100644
--- a/docs/errors/pipe-run-inputs-error.md
+++ b/docs/errors/pipe-run-inputs-error.md
@@ -3,10 +3,16 @@ title: "Pipe run inputs"
description: "Reference for the `PipeRunInputsError` Pipelex error class."
---
-<!-- pipelex:generated -->
+<!-- pipelex:authored -->
# Pipe run inputs
+A pipe could not get the inputs it needs to run.
+
+When a pipe starts without a required input, the caller's request or the caller's method left it out: `Live run of PipeSequence 'flow': missing required inputs: topic.` That error is in the `input` domain, so an HTTP surface answers 422, its message survives STRICT disclosure, and its next step names the inputs to provide.
+
+An input whose resource the pipe cannot use (a local file that does not exist) raises it too, but that message names the path as resolved on the host running the method, so it carries no domain and is redacted under STRICT disclosure, as it is when raised from any other place.
+
| Field | Value |
|---|---|
| `error_type` | `PipeRunInputsError` |
diff --git a/docs/errors/pipeline-execution-error.md b/docs/errors/pipeline-execution-error.md
index 42805ae2f..242b75d4c 100644
--- a/docs/errors/pipeline-execution-error.md
+++ b/docs/errors/pipeline-execution-error.md
@@ -3,11 +3,26 @@ title: "Pipeline execution"
description: "Reference for the `PipelineExecutionError` Pipelex error class."
---
-<!-- pipelex:generated -->
+<!-- pipelex:authored -->
# Pipeline execution
-Wraps any failure that occurred while running a pipeline.
+Wraps any failure that occurred while running a pipeline, reported as its root fault.
+
+The runner raises it around every failure that happens once a run has started, so a host catches one class whatever went wrong. You will rarely see `PipelineExecutionError` as the `error_type` of a report, though: the report names what actually went wrong.
+
+## What the report says
+
+The report of a `PipelineExecutionError` is the report of its **root fault**, the innermost Pipelex error on its cause chain, located at the pipe that failed:
+
+- `error_type`, `title` and `type_uri` are the root fault's. A run whose model was not found reports [`ModelNotFoundError`](model-not-found-error.md), and a run whose parallel branch could not be combined reports `StuffFactoryError`.
+- `message` is the root fault's own message, prefixed with the failing pipe and its path from the entry pipe: `Pipe 'summarize' failed (two_steps → summarize): Model handle 'x' was not found in the model deck.` When the entry pipe itself failed, the path is left out: `Pipe 'flow' failed: …`.
+- Whether the message is caller-facing is the root fault's call, so under STRICT disclosure a caller-facing root keeps its located message and any other is redacted.
+- `error_category`, `retryable`, `model` and `provider` come from the cause chain. `error_domain` does too, with `runtime` as a floor. When nothing on the chain advises an action, `user_action` falls back to `The run failed in pipe '<code>': the message gives the cause.`
+
+A pipe that raised something that is not a Pipelex error is reported as [`PipelexUnexpectedError`](pipelex-unexpected-error.md), whose message names the original exception's class.
+
+The exception itself carries the location structurally: `pipe_code` is the pipe that failed and `pipe_stack` its path from the entry pipe. When the failure was never located, because it happened outside any pipe, or because it arrived from a remote worker as a report that already names its pipe, `pipe_code` is the entry pipe and `pipe_stack` is empty, and the report is taken as it is. A run therefore gives the same report whether it ran in process or on a remote worker.
| Field | Value |
|---|---|
diff --git a/docs/errors/stuff-factory-error.md b/docs/errors/stuff-factory-error.md
index dfdb61d45..cb84f0053 100644
--- a/docs/errors/stuff-factory-error.md
+++ b/docs/errors/stuff-factory-error.md
@@ -3,10 +3,18 @@ title: "Stuff factory"
description: "Reference for the `StuffFactoryError` Pipelex error class."
---
-<!-- pipelex:generated -->
+<!-- pipelex:authored -->
# Stuff factory
+A stuff could not be built from the content given for its concept. It is raised from many places, and whose fault it is depends on the place.
+
+When a `PipeParallel` combines its branch results into its declared output, a mismatch is the caller's fault: which branch feeds which field, what each branch produces and whether it produces a list are all written in the caller's method. A branch declared `Idea[]` feeding a field that holds one `Idea`, a branch concept its field does not accept, or a required field no branch feeds, all fail there. That error is in the `input` domain, so an HTTP surface answers 422, its message survives STRICT disclosure, and its next step says to change the method. The run's report locates it at the parallel: ``Pipe 'analyze' failed (flow → analyze): Error combining stuffs for concept Report, stuff named `report`: …``, followed by the validation errors of the fields.
+
+When the mismatch is a branch whose multiplicity differs from its field's, a list branch feeding a single field or the reverse, the parallel raises a second `StuffFactoryError` from the combine's, which restates the refusal with the change to make, and its next step is that change. A run failure reports its root fault, and of two faults of the same class the outer one, so every surface, a hosted caller under STRICT disclosure included, reads the restatement: `Pipe 'analyze' failed (flow → analyze): PipeParallel 'analyze' cannot combine its branch results into its output 'Report'. Branch 'gen_ideas' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'Report' holds a single item. …`. When the combine also refused a field the multiplicity does not explain, the restatement keeps its report after `The combine also reported:`.
+
+Raised from any other place, it carries no domain and its message is redacted under STRICT disclosure.
+
| Field | Value |
|---|---|
| `error_type` | `StuffFactoryError` |
diff --git a/docs/errors/validate-bundle-error.md b/docs/errors/validate-bundle-error.md
index cf8de68eb..792f2d3ff 100644
--- a/docs/errors/validate-bundle-error.md
+++ b/docs/errors/validate-bundle-error.md
@@ -7,7 +7,7 @@ description: "Reference for the `ValidateBundleError` Pipelex error class."
# Validate bundle
-Raised when bundle validation fails.
+Raised when a bundle is refused while it is loaded or validated: the invalid verdict, carrying one structured item per refusal in ``validation_errors``. Every refusal of the bundle itself becomes one — every parser error, categorized or not, the factory and pipe-validation errors, one ``dry_run`` item per pipe whose dry run failed, an unknown model (``unknown_model``) and any other refusal of the caller's input — each keeping the locators its raise site had, such as a TOML syntax error's ``line`` and ``column`` and an unresolved concept's ``declared_concepts``, while a failure of the tool or its environment propagates as a no-verdict fault instead. A run raises it too, when the bundle it was given is refused while it loads, before any pipe runs: the same verdict, with the same items, that validating the bundle gives.
| Field | Value |
|---|---|
@@ -17,6 +17,6 @@ Raised when bundle validation fails.
| `error_domain` | `input` |
| Defined in | `pipelex.pipeline.exceptions` |
| Parent class | [`PipelexError`](pipelex-error.md) |
-| `user_action` | `change_input` — Check the validation_errors array for specific issues |
+| `user_action` | `change_input` — Edit the bundle as each validation error says: apply its suggested fix where it has one, after confirming an unsafe one |
[Back to Error Reference](index.md)
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index 89d51ded5..50d9ec810 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -46,6 +46,8 @@ pipelex-agent run method <NAME> [OPTIONS]
For `bundle` and `method`, use `--pipe` to target a specific pipe.
+A run refuses an invalid bundle while loading it, before any pipe runs, with exit code `1` and an error envelope whose `error_type` is `ValidateBundleError` and whose `validation_errors` array holds the items `validate` gives for that bundle, each with its pipe, its field and its suggested fix when it has one. A refusal found while loading a library directory you pass with `-L` (or the bundle's own directory) is reported the same way, its items naming their file in `source`; a bundle file run on its own is loaded from its text, so the items of a refusal found while loading it carry no `source`, while a bundle that does not parse when `run bundle` looks for its `main_pipe` (no `--pipe`) names its file. In markdown, the items render as the same grouped prose `validate` prints.
+
!!! note "Stdin inputs stay JSON"
The agent CLI can also read inputs from stdin (a flat dict or a `working_memory` envelope). Stdin inputs are **JSON-only** — the extension-based TOML discrimination applies to `--inputs` file paths only. Like the main CLI, `run bundle <dir>` auto-detects `inputs.json` / `inputs.toml` when `--inputs` is omitted, erroring if both exist. In a `working_memory` envelope each stuff must name its concept as the ref string; anything else there — the full concept object an older runtime dumped, for instance — is refused under `"error_type": "StdinEnvelopeShapeError"`, which is the label for an envelope that parsed as JSON but does not hold the shape the contract asks for, as distinct from the `JSONDecodeError` that means the JSON itself did not parse.
@@ -79,6 +81,9 @@ For `bundle`, additional options are available:
On a successful run, the envelope also carries `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), each namespaced by `pipe_ref` (`domain.code`). In JSON it is a `pending_signatures` array, in markdown a "Pending signatures" section. A top-down build reads it to see exactly which headers remain to implement. The envelope also carries a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown states the runnability verdict in plain English — runnable when complete, NOT yet runnable above the "Pending signatures" section otherwise. `validate bundle`, `validate method`, and `validate pipe --all` carry them and gate on them: without `--allow-signatures`, the command exits non-zero when `is_runnable` is false. Bare `validate pipe <code>` omits them, and a `--pipe` slice surfaces them for information without gating.
+!!! note "Every refusal of the bundle is an invalid verdict"
+ A refusal of your input raised while the bundle is loaded or validated is answered with the invalid-verdict envelope — `is_valid: false` and a `validation_errors` array — and exit code `1`, never the no-verdict envelope and exit code `2`, which is kept for failures of the tool or its environment. A pipe whose dry run fails gives one `dry_run` item per failing pipe, with `error_type: DryRunError`, the `pipe_code`, `domain_code` and `source` of the innermost pipe that failed and is not allowed to fail (its `source` whenever the pipe is in your files; a validator of submitted content beside a host's library directories names only that content's files), and a message that keeps the failure's own text only when it is caller-facing, on `validate bundle`, `validate pipe <code>` and `validate pipe --all` alike; a controller that failed because a pipe it runs failed is reported once, at that pipe. Every error found while parsing is its own item, so a misspelled field is reported beside the categorized errors as an item without an `error_type`, carrying its `pipe_code`, `source` and `field_path`. A TOML syntax error's item carries its 1-based `line` and `column`, and an `unresolved_concept` item lists the concepts the validated bundle declares in its domain in `declared_concepts`. A pipe naming a model the model deck does not define gives one `pipe_validation` item with `error_type: unknown_model`, carrying `pipe_code`, `domain_code`, `source`, `field_path` (`pipe.<code>.model`), `model_reference` (the reference as written), `model_type` and `suggestions` (the deck's close matches), plus a `rename-model` `suggested_fix` when there is exactly one suggestion. That fix's `safety` is `unsafe`, because a close name can still be a different model: `fix bundle` never applies it, and the Markdown labels it `💡 Suggested fix (unsafe, confirm before applying):` where a safe fix reads `💡 Suggested fix:`. Any other refusal of your input with no code of its own gives one item without an `error_type`, located on its pipe when it was raised while that pipe was built. A pipe factory's refusal, such as a `PipeExtract` whose input is neither an image nor a document, is one of these items, located on its pipe. See [Error Model](../../under-the-hood/error-model.md#validation_errors-structured-bundle-validation-diagnostics).
+
!!! note "Advisory warnings on validate"
Whole-bundle and whole-library validate surfaces (`validate bundle`, `validate method`, `validate pipe --all`) also carry a `warnings` array — advisory optionality lints on a VALID bundle that never flip the verdict or the exit code. Each entry has the **same shape as a validation error item** (`category`, `error_type`, `pipe_code`, `domain_code`, `variable_names`, `message`) — this is a different shape from the `init`/`doctor` setup `warnings` (`{type, message}`) documented under Output Contract below. Three families ride the array, always in this order: the useless-`!` lint (`optional_force_redundant`), a `!` (force) input whose slot is guaranteed present in every analyzed flow, so the assertion can never fire; the vacuous-presence lint (`input_presence_vacuous`), an entry-pipe input that must be supplied but whose concept declares no required field, so the empty object satisfies it and a caller cannot tell what to fill in (see [Understanding Optionality](../../building-methods/pipes/understanding-optionality.md)); and the [intent-hint](../../building-methods/concepts/intent-hints.md) lints (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`). Every whole-bundle validate channel — this CLI, the bare CLI, the builder ops and the protocol validation report — assembles them from one composition point, so which advisories you see does not depend on which command you typed. Hint findings are bounded per site: a site naming many undefined keys reports the first few and then how many more there were, and a long authored key or value is elided in the message. In markdown, warnings render as a "Warnings" section. The array is empty when there is nothing to report; `validate pipe` omits it (no flow context to lint in). `validate bundle`/`validate method` with `--pipe` keep it, and it stays bundle-wide there — the slice narrows the dry run, not the validation.
@@ -191,6 +196,8 @@ Do not confuse this setup-warning shape with the `warnings` array on the `valida
For the structured commands, exactly one such object is written to stderr per failure, so the stream parses as a single JSON document.
+**A failed run** (`run pipe`, `run bundle`, `run method`) reports `"error_type": "PipelineExecutionError"` and adds four fields: `pipe_code` and `pipe_stack` name the pipe that failed and its path from the entry pipe, and `cause_type` and `cause_message` give the class and own message of the root fault, the innermost Pipelex error behind the failure. The `message` is that root fault's message prefixed with the failing pipe and its path (`Pipe 'summarize' failed (two_steps → summarize): …`), and the classification fields are the root fault's, so branch on `cause_type` to tell, say, a model that is not available from a failure to combine a parallel's results.
+
**`migration`** — a configuration error (`"error_domain": "config"`) carries an extra `migration` object when, and only when, a scan of this machine's configuration directories found something. Its presence says the migration history has something to report about these files; **`would_write` says whether a command repairs them.** The object holds `remedy` (the command that fixes what can be fixed), `would_write` (whether running it would rewrite any of these files), `needs_attention` (whether something there is a person's decision rather than the tool's), and `plans` — one per file, in the same shape [`pipelex-agent migrate`](migrate.md) emits under its own `plans` key. On `would_write: true` the loop is `pipelex-agent migrate --dry-run --format json`, show the user what would change, then `--yes`. On `would_write: false` there is nothing to run: the plans carry a path no ledger entry explains, or an entry blocked before anything applied, and the command would visit the files, write nothing and leave the same error standing — so read the plans and correct what they name. Never answer either one by re-initializing a configuration file — that discards every setting the migration would have kept.
`TelemetryConfigValidationError` carries it too, on the same terms: absent means the `telemetry.toml` is wrong and the fields the message names are what to correct, present with `would_write: true` means it is old, and present with `would_write: false` means it is both reported on and unrepairable by the command.
diff --git a/docs/tools/cli/fix.md b/docs/tools/cli/fix.md
index ee000c4fa..5c171b715 100644
--- a/docs/tools/cli/fix.md
+++ b/docs/tools/cli/fix.md
@@ -10,7 +10,7 @@ Apply deterministic, safe fixes to a bundle and re-validate until it is valid.
pipelex fix bundle ... # Fix a bundle file or directory in place
```
-When `pipelex validate` reports errors that have a deterministic fix, each one carries a `💡 Suggested fix:` line and the output ends with the exact `pipelex fix bundle` command to run. The fix command runs a validate → apply safe fixes → re-validate loop until the bundle is valid, out of fixes, or the iteration cap is reached — and names every change it makes.
+When `pipelex validate` reports errors that have a deterministic safe fix, each one carries a `💡 Suggested fix:` line and the output ends with the exact `pipelex fix bundle` command to run. The fix command runs a validate → apply safe fixes → re-validate loop until the bundle is valid, out of fixes, or the iteration cap is reached — and names every change it makes.
## Fix Bundle
@@ -60,7 +60,7 @@ pipelex fix bundle my_bundle.mthds --select match-sequence-output
## What Gets Fixed
-Only fixes classified as SAFE are applied — deterministic corrections derived from the structured validation errors, never from guesswork. Errors without a safe deterministic fix are left in place and reported as remaining errors. The available fix rule codes (for `--select`/`--ignore`) are listed in the error message when you pass an unknown code.
+Only fixes classified as SAFE are applied — deterministic corrections derived from the structured validation errors, never from guesswork. Errors without a safe deterministic fix are left in place and reported as remaining errors. An unsafe fix, such as `rename-model` for a model name the deck only nearly matches, still shows on its error, labelled `💡 Suggested fix (unsafe, confirm before applying):`, for you to check and apply by hand, and is not a code `--select` or `--ignore` accepts. The available fix rule codes (for `--select`/`--ignore`) are listed in the error message when you pass an unknown code.
## Related Documentation
diff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.md
index 30005f341..2aa89d1c6 100644
--- a/docs/tools/cli/run.md
+++ b/docs/tools/cli/run.md
@@ -228,6 +228,10 @@ They are the same artifacts a validation report returns under those names, keyed
A run whose main output resolves as a recorded absence (an optional `?` output that produced nothing — e.g. a `PipeCondition` `continue` outcome, or a skipped producer) is a **successful** run. The CLI prints the absence with its reason, and `--save-main-stuff` writes an explicit absence artifact instead of a value dump: `main_stuff.json` is `{"absent": true, ...}` with the absence record, and `main_stuff.md` is a human-readable summary including the provenance chain (no HTML render or interactive viewer is produced — there is nothing to view). `--save-csv` fails with an explicit error and a non-zero exit code, the same way it does for any main output that is not a flat list — there is no tabular value to save.
+## An Invalid Bundle
+
+A run loads its bundle before any pipe runs, and refuses an invalid one there, before spending anything. The refusal is reported the way [`pipelex validate`](validate.md) reports the same bundle: the grouped invalid-bundle panel, with one located item per refusal (its pipe, its field, its message and its suggested fix when it has one), and exit code `1`. A bundle file run on its own is loaded from its text, so the items of a refusal found while loading it name no file, and the panel names the bundle instead; a bundle that does not parse when `run bundle` looks for its `main_pipe` (no `--pipe`) names its file on the item too. That holds whether the parse or the load refuses the bundle, and for a refusal found while loading a library directory you pass with `-L` (or the bundle's own directory, for `run bundle <dir>`). When the items carry automatic fixes, the panel names the `pipelex fix bundle` command that applies them.
+
## Related Documentation
- [Executing Pipelines](../../building-methods/pipes/executing-pipelines.md)
diff --git a/docs/tools/cli/validate.md b/docs/tools/cli/validate.md
index ab68a21e7..091f4baab 100644
--- a/docs/tools/cli/validate.md
+++ b/docs/tools/cli/validate.md
@@ -122,14 +122,38 @@ pipelex validate method invoice_extractor
pipelex validate method invoice_extractor --pipe extract_amounts
```
+## An Invalid Bundle Is a Verdict
+
+Every refusal of your method raised while it is loaded or validated is reported as an invalid bundle: the grouped `❌ Bundle validation failed` output naming each error's pipe, domain, field and file, with exit code `1`. Exit code `2` is kept for the cases where no verdict could be produced — bad arguments, a target that does not resolve, or a failure of Pipelex or its environment. This holds on every subcommand: `validate pipe` and `validate --all` render a pipe whose dry run fails the same way `validate bundle` does, where they used to print a traceback. A failing dry run is listed under `Dry Run Errors:` with one entry per failing pipe, naming the innermost pipe that failed and is not allowed to fail rather than every controller around it, and every error found while parsing gets its own entry, so a misspelled field is reported beside the other errors instead of after they are fixed. A few refusals raised while a pipe is built do not classify themselves as a fault of your method yet, and those still stop validation without a verdict.
+
+A pipe that names a model your model deck does not define is the most common case. It is reported as an `Unknown Model` error on that pipe, with the path of the field that names it (`pipe.<code>.model`, or `pipe.<code>.model_to_structure` for the model a `PipeLLM` structures its output with) and the deck's close matches:
+
+```text
+Pipe Validation Errors:
+
+1. Unknown Model
+ Pipe: write_tide_note
+ Domain: tide_tables
+ Field: model
+ → Pipe 'write_tide_note' (PipeLLM), field 'model': Alias 'best-sonet' was not found in the model deck
+
+Did you mean: @best-gpt
+ 💡 Suggested fix (unsafe, confirm before applying): Replace model '@best-sonet' of pipe 'write_tide_note' with '@best-gpt', its one close match in the model deck
+ └─ Path: pipe.write_tide_note.model
+```
+
+When the deck offers exactly one close match, as here, the error carries a suggested fix naming it. The fix is marked unsafe, its line says so, and `pipelex fix bundle` does not apply it on its own: the match is a guess from the spelling, and a close name can be a different model, with its own provider, cost and behaviour, so check it before you write it. With several matches, choosing among them is yours; `pipelex-agent check-model <name> -t <type>` and `pipelex-agent models -t <type>` list what the deck defines.
+
## Suggested Fixes
-When a validation error has a deterministic safe fix, the error output includes a `💡 Suggested fix:` line describing the change, and the report ends with the exact command to apply every suggested fix automatically:
+When a validation error has a deterministic fix, the error output includes a `💡 Suggested fix` line describing the change. A safe fix reads `💡 Suggested fix:`, and when at least one safe fix targets a file the command may write, the report ends with the exact command that applies those fixes automatically:
```text
💡 1 of these errors can be fixed automatically — run: pipelex fix bundle my_pipeline.mthds
```
+An unsafe fix reads `💡 Suggested fix (unsafe, confirm before applying):`. It is a likely correction that could still be wrong, such as a model name the deck only nearly matches, so `pipelex fix bundle` never applies it and the footer does not count it: check the change, then make it by hand. `pipelex-agent` prints the same labels in its Markdown, and its JSON carries each fix's `safety` as `safe` or `unsafe`.
+
See [Fix Commands](fix.md) for `pipelex fix bundle`, including the `--diff` preview.
## Advisory Warnings
@@ -148,6 +172,7 @@ All validation commands check:
- Syntax correctness of `.mthds` files
- Concept and pipe definitions are valid
+- Every model a pipe names is defined in your model deck
- Input/output connections are correct
- All referenced pipes and concepts exist
- Dry-run execution succeeds without errors, which implies the logic is correct and the pipe can be run
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index b600fe3e5..aa13a9e0f 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -34,8 +34,8 @@ An error rises through a series of layers. Each layer has exactly one job.
|-------|------|--------------------------|
| **5 — CLI entry points** | `pipelex` / `pipelex-agent` commands | Catch, format for human (Rich) / agent (JSON·MD) / HTTP |
| **4 — CLI factories** | `cli_factory.py`, `agent_cli_factory.py` | Catch setup errors, route to handlers |
-| **3 — Pipeline runner** | `PipelexMTHDSProtocol.execute()` | Catch + wrap as `PipelineExecutionError` |
-| **2 — Pipe router / operators** | `PipeRouter`, pipe operators | Catch + wrap with pipe context (`pipe_code`, `pipe_stack`) |
+| **3 — Pipeline runner** | `PipelexMTHDSProtocol.execute()` | Catch + wrap as `PipelineExecutionError`, which reports the located root fault |
+| **2 — Pipe router / operators** | `PipeRouter`, pipe operators | Catch + locate every failure as a `PipeRouterError` (`pipe_code`, `pipe_stack`); a foreign exception first becomes a `PipelexUnexpectedError` |
| **1 — Workers / SDK calls** | `pipelex/providers/*/` | **Catch the SDK exception → classify → raise `CogtError`** |
| **0 — Third-party SDKs** | OpenAI, Anthropic, Google, … | Raise raw, untyped provider exceptions |
@@ -76,20 +76,32 @@ The guard against that is a committed snapshot of the full `(error_type, title,
A bundle-validation failure (`ValidateBundleError`) aggregates per-error data across stages and projects it onto `validation_errors` as a list of typed `ValidationErrorItem`s, so the structured error report an HTTP API surfaces carries machine-mappable diagnostics (not just a single `detail` string). Each item's `category` is one of the **closed** `ValidationErrorCategory` set:
-- `blueprint_validation` — interpreter / blueprint-validation faults. A blueprint-stage `PipeValidationError` raised *inside* a pydantic model validator (e.g. the PipeBatch `input_item_name` == `input_list_name` collision, or the SubPipe `batch_over` == `batch_as` collision — both `batch_item_name_collision`) is wrapped by pydantic as a `value_error`; the blueprint categorizer unwraps it (`ctx["error"]`) so the item keeps its structured `error_type` and `pipe_code` / `domain_code` locators instead of degrading to the no-`error_type` residual. The item stays in `blueprint_validation` (not `pipe_validation`) because the fault genuinely surfaced at the parse boundary, before any pipe was instantiated — only the `error_type` is recovered, not the stage. This category also serves as the **last-resort residual**: a parse-level failure (a TOML-syntax error, an empty blueprint, a bundle-elaborator failure) is raised with only a message and no categorized data, so when *nothing else* produced an item the builder projects that message as one `blueprint_validation` item (no `error_type`, no `source` — the bundle could not become a blueprint at all).
+- `blueprint_validation` — interpreter / blueprint-validation faults. A blueprint-stage `PipeValidationError` raised *inside* a pydantic model validator (e.g. the PipeBatch `input_item_name` == `input_list_name` collision, or the SubPipe `batch_over` == `batch_as` collision — both `batch_item_name_collision`) is wrapped by pydantic as a `value_error`; the blueprint categorizer unwraps it (`ctx["error"]`) so the item keeps its structured `error_type` and `pipe_code` / `domain_code` locators. The item stays in `blueprint_validation` (not `pipe_validation`) because the fault genuinely surfaced at the parse boundary, before any pipe was instantiated — only the `error_type` is recovered, not the stage. This category also serves as the **last-resort residual**: a parse-level failure (an empty blueprint, a bundle-elaborator failure) is raised with only a message and no categorized data, so when *nothing else* produced an item the builder projects that message as one `blueprint_validation` item (no `error_type`, no `source` — the bundle could not become a blueprint at all). A TOML syntax error is its own item of this category, with no `error_type`, carrying the `source` and the 1-based `line` and `column` the parser stopped at.
- `pipe_factory` — pipe-factory failures (e.g. a missing concept).
- `pipe_validation` — pipe/concept validation (missing input variable, type mismatch).
-- `dry_run` — the **residual** dry-run failure (`DryRunError` / `PipeRunError`) with no structured locator. It is projected as one message-only item **only when no categorized error has data**. It is graph-level, so it typically carries **no `source`**.
+- `dry_run` — one item per pipe whose dry run failed, with the `error_type` `DryRunError`, the pipe's bare `pipe_code`, its `domain_code` and, when the library knows it, its `source`.
-Together the two residuals make the **structured-info invariant total**: every invalid verdict carries a non-empty `validation_errors[]`, never a bare message. The builder tries the channels in order — categorized data, then the `dry_run` residual (the more specific channel), then the `blueprint_validation` fallback — and emits exactly one residual only when no earlier channel produced an item.
+**Every error is an item, and none hides another.** Every pydantic error the parser meets becomes its own item: categorized when the blueprint categorizer knows it, and otherwise an uncategorized `blueprint_validation` item with no `error_type`, carrying its `source`, the `pipe_code` its location names and its `field_path`, the bundle-root path of the failing field with pydantic's own elements left out (`pipe.summarize.promtp`, not `pipe.summarize.PipeLLM.promtp`). A misspelled field beside an undeclared prompt variable therefore gives two items, where the typo used to vanish until the variable was fixed. The only error left out is the union-branch noise of a concept declared as `ConceptBlueprint | str`, whose table branch already reports the fault. The same holds inside every message `format_pydantic_validation_error` builds: the kinds it lists get their own heading, and every other kind is rendered under "Other validation errors", whatever else is present.
-Besides `category` and `message`, each item carries whatever identity fields its stage produced — `error_type`, `pipe_code`, `concept_code`, `domain_code`, `field_path`, `field_name`, `variable_names`, `missing_concept_code`, `declared_concepts`, and a `source` (the declaring file path, or the per-content source the in-memory load path was given) that hands a consumer the owning file for cross-file diagnostic placement. When the error has a deterministic remedy, the item also carries a [`suggested_fix`](#suggested_fix-structured-deterministic-fixes).
+**A dry-run failure is one located item per failing pipe.** The dry-run sweep (`BundleValidator` in `pipelex/pipeline/bundle_validator.py`) runs each pipe through its own in-process router, which notes the first pipe each failure leaves: the innermost pipe that failed. A controller that failed because a pipe it runs failed is therefore reported at that pipe, and once, even when both were swept; validating the controller alone still reports the inner pipe. A pipe listed in `allowed_to_fail_pipes` is never where a failure is reported: a failure met there is reported at the innermost pipe around it that is not allowed to fail, the one whose failure is unexpected. When the bundle is validated from submitted content beside a host's library directories, as the hosted validator does, the item carries that pipe's `source` only when the pipe belongs to that content: a pipe loaded from the host's own library directories is named by its code and domain, never by its file on the host. A bundle validated from a file on the caller's own disk names every pipe's file, a sibling file of the same method included, and so does submitted content validated beside directories that are the caller's own (`library_dirs_are_callers`). The sweep raises one `DryRunError` whose `failures` hold one `DryRunFailureErrorData` per failing pipe, and the cascade turns each into its own `dry_run` item. The item's message names the pipe and carries the failure's own text only when the failure's root fault, the one a run failure reports (the innermost `PipelexError` on its cause chain, the walk stopping at the first exception that is not one, and of two errors of the same class the outer one, which restates the inner with a remedy), authored that text as caller-facing copy, and otherwise the fault's title, because the verdict is kept verbatim under STRICT disclosure and would otherwise carry a configuration or storage failure's internals to a hosted caller. A failure the runtime has not classified as the caller's therefore reads `Pipe '<code>' failed its dry run: <title>`, the fault's title in place of its message. The sweep reports every failing pipe this way, whatever raised the failure.
+
+The **structured-info invariant is total**: every invalid verdict carries a non-empty `validation_errors[]`, never a bare message. The builder emits the categorized items and the `dry_run` items, then the `blueprint_validation` fallback only when nothing else produced an item.
+
+Besides `category` and `message`, each item carries whatever identity fields its stage produced — `error_type`, `pipe_code`, `concept_code`, `domain_code`, `field_path`, `field_name`, `variable_names`, `missing_concept_code`, `declared_concepts` (on an `unresolved_concept` item, the bare codes of the concepts the validated bundle declares in the domain the reference was looked up in, native concepts excluded, and never those a library loaded before it, which may be a host's own), the TOML position `line` and `column`, the unknown-model locators `model_reference`, `model_type` and `suggestions`, and a `source` (the declaring file path, or the per-content source the in-memory load path was given) that hands a consumer the owning file for cross-file diagnostic placement. When the error has a deterministic remedy, the item also carries a [`suggested_fix`](#suggested_fix-structured-deterministic-fixes).
+
+**A verdict names no path on the host.** An item and the verdict's message are kept verbatim under STRICT disclosure, so neither names where the host keeps a file. A bundle of a package the method depends on by address is named by the package's address and the bundle's path inside the package, such as `github.com/acme/harbour-methods/tides/notices/tide_notices.mthds`, never by the directory the host installed the package in: that is the `source` of an item located inside the dependency and the file a duplicate declaration inside it names, on every surface, a local one included. When submitted content is validated or run, the library directories loaded beside it are the host's (installed libraries, the defaults, `PIPELEXPATH`) unless the caller says they are its own, so the verdict names none of their files: an item located in one carries no `source`, nor a `field_path` naming it, and is found by its `pipe_code` and `domain_code`, and a message that named one, or named the module a Python file of theirs was imported as (two `@pipe_func` functions of the same name, for instance), reads `<host library file>` in its place (`withholding_host_library_files` in `pipelex/pipeline/validate_bundle_translation.py`). A name only counts standing on its own, never inside a longer one, and a source the caller submitted is never withheld. A bundle validated from a file on the caller's own disk, and content validated or run against library directories that are the caller's (`library_dirs_are_callers`, an option of `validate_bundle`, of the in-process validator and of the local runtime `PipelexMTHDSProtocol`, whose `validate` and `execute` both read it), keep the full path of every file, since there the directories are the caller's own. `pipelex fix bundle --diff` leaves a dependency's address-named source as it is.
+
+**Every refusal of the bundle is a verdict.** A validator answers either a verdict — valid, or invalid with located items — or *no verdict could be produced*, which is reserved for a failure of the tool or its environment. So a refusal raised while loading or validating a bundle becomes an item, never a no-verdict fault. After its class-specific arms, the shared cascade (`translate_to_validate_bundle_error` in `pipelex/pipeline/validate_bundle_translation.py`) turns any other `PipelexError` whose report is `input`-domained into a verdict with one item: `pipe_validation`, with the `pipe_code`, `domain_code` and `source`, when the library load located it on the pipe it was building, and `blueprint_validation` otherwise. That item carries no `error_type`, since a refusal with a closed code has an arm of its own. It keeps the refusal's message only when the refusal authored that message as caller-facing copy, and otherwise names the refusal's title, because the verdict as a whole is kept verbatim under STRICT disclosure. The location comes from the load loop in `LibraryManager.load_from_crate`, the one place that holds a pipe's code, domain and file when building it fails: it raises such a refusal again as a `PipeLoadRefusalError` naming the pipe and the file, `from` the original. A `config` or `runtime` fault, an unclassified one, a `SecurityError`, a `PipeNotFoundError` (which has its own not-found handler) and anything that is not a `PipelexError` still propagate as no verdict. The rule therefore reaches exactly the refusals whose class declares the `input` domain. The pipe factories' refusals do: `PipeLLMFactoryError`, `PipeComposeFactoryError`, `PipeExtractFactoryError`, `PipeConditionFactoryError` and `PipeParallelFactoryError` are raised only while a pipe is built, about its own blueprint, so each is `input`-domained and caller-facing, and a `PipeExtract` whose input is neither an image nor a document validates to one item on that pipe, saying which input to redeclare. `PipeImgGenFactoryError` is not among them: it is raised while an image-generation pipe runs, not while it is built.
+
+**The unknown model is the worked example.** A pipe whose model field names a handle, an alias, a preset or a waterfall the model deck does not define is refused when the pipe is built: the operator's deck check raises `ModelChoiceNotFoundError`, and the operator raises it again as a `PipeOperatorModelChoiceError` located on the pipe and on the field, to which the load adds the file. Every pipe type that names a model (`PipeLLM`, `PipeStructure`, `PipeImgGen`, `PipeExtract`, `PipeSearch`) does this through the same `PipeOperator.locating_model_choice` wrapper, so each gives the same item: `category: pipe_validation`, `error_type: unknown_model`, the `pipe_code`, `domain_code` and `source`, the `field_name` and a `field_path` of `pipe.<code>.model` (`pipe.<code>.model_to_structure` for a `PipeLLM`'s structuring model), the `model_reference` exactly as written, the `model_type` (`llm`, `text_extractor`, `img_gen` or `search`), and the deck's `suggestions` of the same kind, each spelled as a reference the field accepts. The suggestions stay in the item's `message` too, for consumers that keep only the message. When the deck offers exactly one suggestion, the item carries an `unsafe` `rename-model` fix, a `remap_value` of the field from the reference as written to that suggestion. It is unsafe because the suggestion is a fuzzy match over the deck's names, which can be a different model altogether, so `pipelex fix bundle` never applies it on its own; an author or an agent applies it deliberately. An inline setting table (`model = { model = "…", temperature = 0.2 }`) is not looked up in the deck, so it is not refused here. On a run the same refusal stops the bundle before any pipe runs, as the same `unknown_model` item (see the next paragraph).
+
+**A run refuses an invalid bundle with the same verdict.** A run loads its bundle before any pipe runs, and the run path's `acquire_library` performs that load inside the same `translate_to_validate_bundle_error`, so a bundle the load refuses raises the `ValidateBundleError` with exactly the items validating it gives, before any inference is spent. `ValidateBundleError` is `input`-domained and caller-facing, so a hosted run route answers it as a 422 whose `validation_errors` STRICT disclosure keeps, where each refusal used to reach the host in its raw class: a misspelled concept as a `ConceptLibraryError` answered 500, a wiring mismatch as a `PipeValidationError` answered by the catch-all 500, a TOML fault as a 422 with no items, and a check firing inside a pipe's pydantic validator as a `runtime` `PipeExecutionError` reading "Input validation failed". The translation's own exceptions hold on this path too: an unknown entry pipe still raises its `PipeNotFoundError`, and a fault of the tool or its environment still propagates as itself. Two things differ from the validate path, both about whose files are loaded. The run path threads no source of its own onto its contents, so their items carry no `source`, even on a local run of a bundle file. A package the bundle depends on by address is loaded from the host's install directory within the same translation, as it is on the in-memory validate path, and a refusal inside it names the package by its address, never that directory. And the library directories load translated only when they are the caller's own, as on a local CLI run (`library_dirs_are_callers`); a host's directories (installed libraries, a temporary directory of shipped Python) load untranslated, because a fault there is not the caller's to fix. The local `pipelex run` renders the verdict with the grouped panel `pipelex validate` prints, and `pipelex-agent run` copies its `validation_errors` into the error envelope.
**Signatures are never an error.** An unimplemented `PipeSignature` reached during validation is a *runnability fact*, not a validation failure: the validator no longer raises on it. The assembled library's outstanding signatures ride the validation report's `pending_signatures`, and `is_runnable = not pending_signatures`. `allow_signatures` is a sweep-mechanics flag only (whether signature pipes are mock-run and listed in `validated_pipes`) — it does not change the verdict, so strict ≡ lenient in the report body. The "is this a failure?" decision moves to the consumer: the CLI exits non-zero on `not is_runnable` unless `--allow-signatures`; the HTTP caller reads `is_runnable`. (The **execute/run** path is different: running a stub still raises `PipeSignatureNotExecutableError`.)
**Host-wiring guards are programmer errors, not content verdicts.** `validate_bundle`'s "provide exactly one of `mthds_contents` / `mthds_file_path`" guard and `resolve_crate_from_contents`'s `mthds_sources`-length-mismatch guard raise `PipelexUnexpectedError` (→ 500, redacted under STRICT), not `ValidateBundleError` — a caller wiring bug must not be reported as if the submitted bundle were invalid. The empty-`mthds_contents` guard stays caller-facing (it can legitimately reflect an end user submitting no bundles).
-`ValidationErrorItem` and the builder are the single source of truth across surfaces: `build_validation_error_items()` (`pipelex/pipeline/validation_errors.py`) is called by both `ValidateBundleError.to_error_report()` (the API path) and the agent CLI's `extract_validation_errors()` (the CLI JSON envelope), so the two structured shapes cannot drift. The item lives in `pipelex/base_exceptions.py` alongside `ErrorReport` — not next to the source error-data models — because `ErrorReport` references it as a typed field and the root exceptions module must not import the `pipelex.core` error modules.
+`ValidationErrorItem` and the builder are the single source of truth across surfaces: `build_validation_error_items()` (`pipelex/pipeline/validation_errors.py`) is reached through `ValidateBundleError.validation_error_items()`, which `ValidateBundleError.to_error_report()` (the API path), the agent CLI's `extract_validation_errors()` (the CLI JSON envelope) and `pipelex fix` all call, so the structured shapes cannot drift. `pipelex-agent validate pipe` and `validate --all` dry-run through the same cascade, so a failing dry run there is the same invalid verdict with the same items as on `validate bundle`. The item lives in `pipelex/base_exceptions.py` alongside `ErrorReport` — not next to the source error-data models — because `ErrorReport` references it as a typed field and the root exceptions module must not import the `pipelex.core` error modules.
#### The `error_type` registry — the closed vocabulary of faults
@@ -97,7 +109,7 @@ An item's `error_type` names the fault it reports, and that vocabulary is closed
The registry is the union of the enums validation already reports through, never a second list beside them — "reports through", not "raises", because the advisory members ride `warnings` and are never raised as an exception at all: `PipeValidationErrorType` and `PipeFactoryErrorType` are the two stage vocabularies, `ValidationResidualErrorType` names the one residual channel with no stage enum of its own, and `HintLintErrorType` carries the intent-hint lints (which attach to concepts and structure fields too, so the pipe enum is the wrong home for them). A member added to any of them is in the registry the moment it is declared. `ValidationErrorItem.error_type` is typed against their union, so an unregistered string cannot be constructed or parsed onto an item — which is what makes the enumeration *closed* rather than merely documented, and what publishes the vocabulary into the OpenAPI schema `pipelex-api` serves for `/validate`.
-Two spellings live in that one vocabulary, deliberately. The stage enums are snake_case codes (`missing_input_variable`); the dry-run residual is `DryRunError`, the name of the exception that produced it, because that residual is raised as an error object rather than classified into a code. Normalizing it would be a wire break across every consumer that pins the string, and it would buy nothing — the enumeration is closed either way.
+Two spellings live in that one vocabulary, deliberately. The stage enums are snake_case codes (`missing_input_variable`); the dry-run items' code is `DryRunError`, the name of the exception that produced them, because a dry-run failure is raised as an error object rather than classified into a code. Normalizing it would be a wire break across every consumer that pins the string, and it would buy nothing — the enumeration is closed either way.
Membership means a value is *reachable on the wire*, not that it is a useful thing to exercise. Several members are advisory-only — `optional_force_redundant`, `input_presence_vacuous`, and the three `hint_*` lints — riding `warnings` and never an invalid verdict, and the two `unknown_*` fallbacks fire on states no author can ask for. A consumer building coverage over the registry excludes those on its own side with a stated reason, rather than pruning them from the runtime truth here — which is what the [MTHDS Test Corpus](../contribute/mthds-test-corpus.md) vocabulary generator already does, excluding each with its reason as it generates the `error.*` namespace from this registry.
@@ -119,7 +131,7 @@ When a validation error has a deterministic remedy, its `ValidationErrorItem` ca
- `fix_code` — the kebab-case rule id (e.g. `match-sequence-output`). The planner's `KNOWN_FIX_CODES` set is the validation set for user-facing rule filters (`--select` / `--ignore`); an unknown code is rejected loudly, never lenient-ignored, because a typo'd filter selects *behavior*.
- `description` — human-readable statement of the change.
-- `safety` — `safe` fixes may be auto-applied; `unsafe` ones require explicit opt-in.
+- `safety` — `safe` fixes may be auto-applied; `unsafe` ones need a person's or an agent's confirmation, and `pipelex fix bundle` never applies them. Every prose rendering labels an unsafe fix `💡 Suggested fix (unsafe, confirm before applying):` where a safe one reads `💡 Suggested fix:`, through the one `suggested_fix_label` in `pipelex/pipeline/validation_render.py`.
- `source` — the file the ops target, when known (multi-file libraries). An applier must only apply ops to the file they target.
- `ops[]` — the fix itself, as **semantic TOML patch ops** addressed by table path (`FixOpKind`: `set_key`, `ensure_table`, `delete_key`, `delete_table`, `rename_table_key`, `move_key`, `remap_value`; each op's `table_path` follows the same conventions as the items' `field_path`). The ops are the machine contract; any rendered diff or `💡 Suggested fix:` line is presentation.
@@ -182,7 +194,7 @@ class InferenceErrorCategory(StrEnum):
### ErrorDomain
-Defined in `pipelex/base_exceptions.py`. Set as a class-level attribute on the exception, drives HTTP status.
+Defined in `pipelex/base_exceptions.py`. Set as a class-level attribute on the exception, or on one error by the site that raises it (see [Classified where it is raised](#classified-where-it-is-raised)), drives HTTP status.
| Domain | Meaning | HTTP status | Who can fix it |
|--------|---------|-------------|----------------|
@@ -210,6 +222,27 @@ own_domain = self.error_category.error_domain if self.error_category is not None
The consequence worth knowing at the HTTP boundary: a **content-classified inference failure answers 422, not 500** — a content-policy refusal, a malformed prompt image, a bad prompt parameter are all properties of material the caller submitted. Everything else keeps the status it already had; only the report became truthful about why.
+#### Classified where it is raised
+
+Most classes state whose fault they are in their body: an `error_domain`, and `_authors_caller_facing_message = True` when their message is copy written for the caller, which STRICT disclosure then keeps instead of replacing it with `An internal error occurred.`. Every instance of such a class is the same kind of fault. A few classes are raised both for faults in the caller's own method or inputs and for faults that are not the caller's, so they cannot state it. For those, the site that raises the error and knows calls `as_caller_fault()` on it: the report then carries the `input` domain, so an HTTP surface answers 422, a caller-facing message, and the next step the raise site passes, if any.
+
+```python
+raise PipeRunInputsError(message=msg, run_mode=run_mode, pipe_code=pipe_code).as_caller_fault(
+ user_action=UserAction(kind=UserActionKind.CHANGE_INPUT, detail="Provide the missing required inputs of 'flow': topic."),
+)
+```
+
+The raise site vouches for the message: it names only the caller's own method and data (pipe codes, concept codes, variable names, the values the caller sent), never a path on the host, a secret or the text of a foreign exception. As with the class-level flag, a plain wrapper raised from the error inherits its domain but not its caller-facing flag, since the wrapper's message is its own; the located wrappers of a run failure report their root fault, so they carry both.
+
+| Raise site | Error | Why it is the caller's fault |
+|------------|-------|------------------------------|
+| A `PipeParallel` combining its branch results into its output | `StuffFactoryError` | The method sets which branch feeds which field, what each branch produces and whether it produces a list. A branch whose multiplicity differs from its field's is restated by a second `StuffFactoryError` raised from the combine's, whose next step names the multiplicity to change, and which the run reports as its root fault |
+| A pipe checking that its required inputs are present | `PipeRunInputsError` | The request, or an earlier step of the method, left the input out |
+| A `PipeCondition` whose expression renders nothing, whose outcome is `fail`, whose chosen pipe misses inputs, or, in a dry run, whose expression does not parse, whose outcomes name no pipe or whose every outcome is `fail` | `PipeRunError` | The method writes the expression and the outcomes, and the run's data it renders is the caller's; the messages name only the pipes and the input names, never the expression's text or the value it rendered, either of which may be a host library's |
+| A model lookup for a reference the deck neither defines nor names in any of its own entries | `ModelNotFoundError` | Only an inline model setting of the method can have named it, so the next step is a `CHANGE_MODEL` action naming the reference as the method wrote it and the type of model the lookup needs; a reference the deck names but cannot serve stays `config` and redacted, with no next step of its own |
+
+Some failures stay unclassified on purpose, each with a sentence at its raise site saying why: a model output that does not fit its structure, which depends on what the model produced; a `PipeFunc` crash, whose exception text can carry anything the process holds; an input resource the pipe cannot use, whose message names the path as resolved on the host; a template that fails to render, where the same failure can come from the template or from the data; and a working-memory miss, since a step naming a variable nothing produces is refused when the bundle loads.
+
---
## Worker Classification
@@ -386,13 +419,38 @@ def _enrich_error_report_from_cause(self, report: ErrorReport) -> ErrorReport:
)
```
-A wrapper keeps its own `error_type` and `message` but inherits every classification field it does not set itself.
+A wrapper keeps its own `error_type` and `message` but inherits every classification field it does not set itself. The two wrappers of a run failure go further, and report their root fault instead of themselves: see [Run Failures: the Root Fault, Located](#run-failures-the-root-fault-located).
!!! warning "Overrides must call the enrichment helper"
A `to_error_report()` override on a subclass **must** end with `self._enrich_error_report_from_cause(report)`. Otherwise that subclass becomes a black hole that drops the cause's classification. A cyclic-`__cause__` guard ensures a malformed chain can never turn error reporting into a `RecursionError`.
---
+## Run Failures: the Root Fault, Located
+
+When a pipe fails during a run, the error a surface receives sits under several wrappers: the pipe router's `PipeRouterError`, maybe a runtime bridge's `PipelexBridgeDispatchError`, and the runner's `PipelineExecutionError`. None of them is what went wrong, and a report reading `PipelineExecutionError` with a bridge's sentence for a message tells the reader nothing. So the two located wrappers, `PipeRouterError` and `PipelineExecutionError`, report the **root fault**, the innermost `PipelexError` on the cause chain, and only add where it happened (`pipelex/pipe_run/located_failure.py`). The walk stops at the first exception that is not a `PipelexError`, whose stand-in is then the fault, and an error raised from one of its own class (a remedy or an item index added to the same fault) counts as the outer one.
+
+**Locating.** `PipeRouterProtocol.run()` catches every failure of the pipe it runs and re-raises it as a `PipeRouterError` chained to it, with the pipe's code and a snapshot of its stack taken where it failed. A failure that already carries a `PipeRouterError` rises untouched through the routers of the controllers above, so the innermost location is the one reported. An exception that is not a `PipelexError` first becomes a `PipelexUnexpectedError` whose message names its class (`KeyError: 'boom'`); it is never caller-facing, and a dry run that sorts its own failures from programming bugs (the bundle validator's sweep, the validate surfaces' graph step) finds the foreign exception behind it with `find_foreign_fault()` and lets it propagate rather than report it as the bundle's failure. A host router whose transport raises its own failures overrides the `_as_pipelex_failure()` hook, and returns `None` for a control-flow exception such as a cancellation, which then propagates as it is. For a transport failure carrying a recovered report, the far side packs the root fault's own report, never a located one: when it packs that report alone, the hook returns a `PipelexError` carrying it and the router locates it at the pipe it ran; when it packs the location it found as well, the hook returns a `PipeRouterError` rebuilt over that report with `make_located()`, which the router raises untouched, so the report reads exactly as the local run's. The runner wraps any failure of the run into a `PipelineExecutionError` with `make_for_run_failure()`, which takes the location from the innermost `PipeRouterError` on the chain (`find_failure_location()`), never from the live stack, which has unwound by then.
+
+**The report.** Both wrappers build the same report from the same root fault (`find_root_fault()`):
+
+| Field | Taken from |
+|-------|------------|
+| `error_type`, `title`, `type_uri` | The root fault |
+| `message` | The root fault's own message, prefixed with the failing pipe and its path |
+| `caller_facing_message`, `validation_errors`, `migration` | The root fault |
+| `error_category`, `retryable`, `model`, `provider`, `provider_metadata` | The cause-chain enrichment |
+| `error_domain` | The cause-chain enrichment, with a `runtime` floor |
+| `user_action` | The cause-chain enrichment or, when nothing on the chain advises an action, a fallback naming the failing pipe |
+
+The message reads `Pipe 'summarize' failed (two_steps → summarize): Model handle 'x' was not found in the model deck.` for a nested pipe, and `Pipe 'flow' failed: …` for the entry pipe. Pipe codes are the caller's own names, so the located message is caller-facing exactly when the root fault's message is, and STRICT disclosure keeps it exactly then. `ErrorReport` has no location field, so the location rides the message; `PipeRouterError` and `PipelineExecutionError` carry it structurally as `pipe_code` and `pipe_stack`.
+
+**A recovered report is taken as it is.** A distributed submitter receives a report that was already located on the worker. When it raises that report inside a `PipelexError` whose `to_error_report()` returns it, and no `PipeRouterError` sits on the submitter's own chain, the runner's `PipelineExecutionError` reports it verbatim: its `pipe_code` is the entry pipe, its `pipe_stack` is empty, and the message is not located a second time. A located report must never reach a router this way, since the router would locate it again: that is why a host router's transport packs the root fault's own report. A bridge's own sentence (`Pipe execution failed in DIRECT mode …`) appears in neither the report nor the message, so a run gives the same report whether it ran in process, through the in-process orchestrator or on a remote worker.
+
+**Where the remedy goes.** A root fault's message states the fact and nothing else, because it reaches every surface, a hosted run's stored error included. Advice that only a local reader can act on belongs to the local CLI: `pipelex run` renders the model panel of a `PipeOperatorModelAvailabilityError` found anywhere on the chain, and the panel's tip is where the local model deck remedy lives.
+
+---
+
## Crossing a Distributed Worker Boundary
The error model is built to survive serialization. Because `ErrorReport` round-trips through `to_dict()` / `from_dict()`, a failure that happens on a remote worker can reach the submitting process with its full classification intact — not just a message string.
@@ -437,7 +495,7 @@ The `validate` surface — both the bare `pipelex validate {bundle,method,pipe}`
**The verdict lives in the structured `is_valid` field, not the exit code.** The exit code is a convenience signal for naive shell/CI/Makefile use (`set -e`, `cmd && next`, `if cmd; then`); machine consumers (hooks, the Codex hook, runners) MUST read `is_valid` (and `error_domain`) from the JSON for their block/warn decisions rather than branching on the exit code. Decoupling the verdict from the exit code is what keeps any future exit-code change non-breaking. The 1-vs-2 split is also additive for flat consumers: both stay non-zero, so anything that only tests zero-vs-non-zero is unaffected.
-Implementation: the agent CLI threads `exit_code` through `agent_error(...)` (`agent_output.py`, default 1); the validate commands pass `exit_code=2` at every no-verdict site and keep the default 1 on the `ValidateBundleError` arm and the signature gate. The bare CLI sets the code directly via `typer.Exit(...)` in `cli/commands/validate/*` and via the `exit_code` parameter on `handle_model_choice_error` / `handle_model_availability_error` in `cli/error_handlers.py`. Shared boot handlers (`make_pipelex_for_cli`'s gateway/inference/telemetry/model-deck-preset paths) stay exit 1 — they are shared across `run`/`build`/`validate` and out of the validate-policy scope.
+Implementation: the agent CLI threads `exit_code` through `agent_error(...)` (`agent_output.py`, default 1); the validate commands pass `exit_code=2` at every no-verdict site and keep the default 1 on the `ValidateBundleError` arm and the signature gate. The bare CLI sets the code directly via `typer.Exit(...)` in `cli/commands/validate/*` and via the `exit_code` parameter on `handle_model_availability_error` in `cli/error_handlers.py`. Every refusal of the bundle is a negative verdict on both CLIs: `validate bundle` and `validate method` validate through the shared cascade, and `validate pipe` and `validate --all` load their libraries through it too, so an unknown model or any other load-time refusal exits 1 with the invalid-bundle output rather than a traceback or the no-verdict exit 2. The bare `validate pipe` and `validate --all` also run their dry run through it, so a pipe whose dry run fails is rendered like any other invalid bundle; the agent CLI answers that failure with its `DryRunError` envelope, `is_valid: false` and exit 1. Shared boot handlers (`make_pipelex_for_cli`'s gateway/inference/telemetry/model-deck-preset paths) stay exit 1 — they are shared across `run`/`build`/`validate` and out of the validate-policy scope.
### API
@@ -462,7 +520,7 @@ A downstream FastAPI exception handler calls `ErrorReport.http_status` and is a
flowchart TB
SDK["Layer 0 — SDK exception<br/>(openai.RateLimitError)"]
W["Layer 1 — Worker classifies<br/>is_quota_exhaustion_*() → CogtError<br/>+ InferenceErrorCategory + ProviderErrorMetadata"]
- WRAP["Layers 2-3 — Wrappers<br/>PipeRouterError → PipelineExecutionError<br/>(attach pipe context)"]
+ WRAP["Layers 2-3 — Wrappers<br/>PipeRouterError → PipelineExecutionError<br/>(locate the root fault)"]
REPORT["ErrorReport<br/>via to_error_report() + cause-chain enrichment"]
SDK -->|"raise ... from exc"| W
@@ -507,11 +565,11 @@ Exception
│ │ ├── LLMModelNotFoundError / ImgGenModelNotFoundError
│ │ └── ExtractModelNotFoundError / SearchModelNotFoundError
│ └── ... (see worker classification) ...
- ├── PipelineExecutionError pipeline/exceptions.py — error_domain = RUNTIME, but only as a floor
+ ├── PipelineExecutionError pipeline/exceptions.py — reports its located root fault, RUNTIME only as a floor
└── ... (one exceptions.py per package) ...
```
-`PipelineExecutionError`'s `RUNTIME` is deliberately a *floor*, applied only when the cause chain surfaced no domain — so a `CONTENT`-categorized inference failure now reaches the HTTP boundary as `INPUT` / 422 through every wrapping layer instead of being flattened to the wrapper's generic 500.
+`PipelineExecutionError`'s `RUNTIME` is deliberately a *floor*, applied only when the cause chain surfaced no domain — so a `CONTENT`-categorized inference failure now reaches the HTTP boundary as `INPUT` / 422 through every wrapping layer instead of being flattened to the wrapper's generic 500. Its identity and message are its root fault's (see [Run Failures: the Root Fault, Located](#run-failures-the-root-fault-located)).
### Factory-time vs Runtime
@@ -534,6 +592,9 @@ The "outcome" exceptions (`LLMCompletionError`, `ImgGenGenerationError`, `Extrac
report = exc.to_error_report() # enriched from the __cause__ chain
payload = report.to_dict() # None-free dict for serialization
+# Classify one error as the caller's own fault, where it is raised
+raise SomeError(msg).as_caller_fault(user_action=user_action) # input domain, caller-facing
+
# Consume a report
report.http_status # 422 / 429 / 500
report.user_action_detail() # free-form advice text, or None
@@ -578,8 +639,12 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| Local file extractor raises a builtin (docling, pypdfium2) | `ValueError` / `RuntimeError` / `FileNotFoundError` → `CONTENT` → `error_domain = INPUT` → **HTTP 422**; `OSError` → `TRANSIENT` (see `_LOCAL_EXTRACT_BY_TYPE_NAME`) |
| LLM returns schema-mismatched JSON | `instructor` re-asks; if exhausted → `UNKNOWN` → no `error_domain` asserted → HTTP 500 |
| Connection dropped mid-request | `AMBIGUOUS` → non-retryable (outcome unknown); `error_domain = RUNTIME` |
+| A step names, in an inline model setting, a model the deck neither defines nor names | `ModelNotFoundError`, classified by the lookup as the caller's: `error_domain = INPUT` → **HTTP 422**, caller-facing under STRICT, with a `CHANGE_MODEL` next step naming the model as the method wrote it and the type of model the step needs. A model the deck itself names but does not serve (a preset or alias on a backend that is not enabled) keeps `CONFIG` → HTTP 500, redacted |
+| A `PipeParallel` cannot combine its branch results, or a pipe starts without a required input | The caller's own method or request: `error_domain = INPUT` → **HTTP 422**, caller-facing under STRICT, with a `CHANGE_INPUT` next step |
| Unknown or ambiguous entry `pipe_code` (a CLI argument, a run request's field, the `--pipe` / `pipe_ref` slice selector of bundle validation) | `EntryPipeNotFoundError` / `EntryPipeAmbiguousError` → `UserAction(CHANGE_INPUT)`; `error_domain = INPUT` → **HTTP 422**, and caller-facing under STRICT. The in-body lookups (`get_optional_pipe` / `get_required_pipe`) keep raising the undomained `PipeNotFoundError` / `PipeLibraryError`: a ref written inside a bundle is not the caller's input |
| Wrapper exception (no own category) | Inherits cause's classification via enrichment — including the domain the cause derived |
+| A pipe fails during a run | `PipeRouterError` → `PipelineExecutionError`, both reporting the root fault's `error_type` and its own message prefixed with `Pipe '<code>' failed (<path>): `; the classification comes from the chain |
+| A pipe raises a non-Pipelex exception | Located as a `PipelexUnexpectedError` whose message names the original class; redacted under STRICT |
| Failure on a distributed worker | `ErrorReport` recovered from the transport's serialized details — same classification as local |
| Worker exception with no `ErrorReport` | Synthesized fallback report — `error_domain = RUNTIME` |
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index af3b714d5..853b28475 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -1,6 +1,6 @@
from collections.abc import Iterator
from enum import StrEnum
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Self
from pydantic import BaseModel, ConfigDict, Field
from typing_extensions import override
@@ -62,14 +62,17 @@ INTERNAL_ERROR_PLACEHOLDER = "An internal error occurred."
# it is kept here — not by the caller-facing branch's bespoke logic — so the
# decision lives in this one allowlist.
#
-# Caveat — ``validation_errors[].source``: on the *in-memory* validate path
-# ``source`` is the caller-supplied logical source (e.g. ``api://bundle-0.mthds``),
-# which is the hosted/STRICT case and safe to surface. On the *on-disk* path it
-# is a real server filesystem path, and STRICT does NOT redact it (consistent
-# with ``DisclosureMode`` being a classification-projection, not a path-leak
-# shield — see its docstring). A hosted surface that validates from disk should
-# therefore use the in-memory path with logical sources rather than rely on STRICT
-# to scrub the path.
+# Caveat — ``validation_errors[].source``: on the *in-memory* validate and run
+# paths ``source`` is the caller-supplied logical source (e.g. ``api://bundle-0.mthds``),
+# which is the hosted/STRICT case and safe to surface; a bundle of an address-based
+# dependency is named by the package's address and its path inside the package, and
+# a file of the host's own library directories is withheld from the verdict, source
+# and messages alike (``withholding_host_library_files``). On the *on-disk* path a
+# ``source`` is a real server filesystem path, and STRICT does NOT redact it
+# (consistent with ``DisclosureMode`` being a classification-projection, not a
+# path-leak shield — see its docstring). A hosted surface that validates from disk
+# should therefore use the in-memory path with logical sources rather than rely on
+# STRICT to scrub the path.
#
# ``migration`` is NOT surfaced, and the contrast with ``validation_errors`` is
# the whole reason: a pending configuration migration describes the *host's* own
@@ -133,7 +136,9 @@ class DisclosureMode(StrEnum):
``message`` and ``user_action``. The flag is set by error classes whose
message is genuinely caller-facing copy — text describing the *caller's
own* input, e.g. ``MthdsParserError`` (a ``.mthds`` syntax error)
- or ``ValidateBundleError`` (a failed bundle validation).
+ or ``ValidateBundleError`` (a failed bundle validation) — or, for a
+ class raised both for the caller's faults and for others, by the raise
+ site that knows, through :meth:`PipelexError.as_caller_fault`.
- Every other report has its ``message`` replaced with a generic
placeholder and its ``user_action`` dropped, keeping only the stable
identifiers (``error_type``, ``error_domain``, ``error_category``,
@@ -263,10 +268,8 @@ class ValidationErrorCategory(StrEnum):
Mirrors the categorized error-data lists aggregated by ``ValidateBundleError``:
blueprint validation (from the interpreter), pipe-factory failures (e.g. a
missing concept), pipe/concept validation (e.g. a missing input variable
- or a type mismatch), and the ``dry_run`` residual — a dry-run failure with no
- structured locator (graph-level), carried as a single message-only item so an
- invalid verdict always surfaces a non-empty ``validation_errors[]`` (the
- structured-info invariant) instead of a bare ``detail``.
+ or a type mismatch), and ``dry_run`` — one item per pipe whose dry run failed,
+ located at the innermost failing pipe.
"""
BLUEPRINT_VALIDATION = "blueprint_validation"
@@ -331,6 +334,17 @@ class ValidationErrorItem(BaseModel):
missing_concept_code: str | None = None
missing_pipe_code: str | None = None
declared_concepts: list[str] | None = None
+ # The 1-based position a TOML syntax error was found at, carried by the parse-level residual so an
+ # editor can anchor the diagnostic. Optional and additive, like ``declared_concepts``.
+ line: int | None = None
+ column: int | None = None
+ # The unknown-model locators, carried by an ``unknown_model`` item: the model reference exactly as
+ # the author wrote it, the model type the field takes (``llm``, ``text_extractor``, ``img_gen``,
+ # ``search``), and the deck's close matches of the same kind, each spelled as a reference the field
+ # accepts. Optional and additive, like ``declared_concepts``: every other item serializes unchanged.
+ model_reference: str | None = None
+ model_type: str | None = None
+ suggestions: list[str] | None = None
# Structured, deterministic fix for this error, when the fix planner derived one from the
# enriched error data. Optional and additive: non-fixable items serialize unchanged under
# ``exclude_none``.
@@ -418,7 +432,8 @@ class ErrorReport(BaseModel):
provider: str | None = None
provider_metadata: ProviderErrorMetadata | None = None
# True when ``message`` was authored as caller-facing copy — set at report
- # construction from ``PipelexError._authors_caller_facing_message``. STRICT
+ # construction from ``PipelexError._authors_caller_facing_message``, or from
+ # the raise site's :meth:`PipelexError.as_caller_fault`. STRICT
# disclosure keys its ``message`` passthrough on this flag (see
# :class:`DisclosureMode`). Defaults to False so an unflagged report — and
# any payload that predates the field — is redacted, never leaked.
@@ -612,6 +627,9 @@ class PipelexError(Exception):
# (Contrast ``_declared_title`` / ``_declared_type_uri``, which ``title()`` /
# ``type_uri()`` deliberately read via ``cls.__dict__`` to bypass inheritance.)
_authors_caller_facing_message: ClassVar[bool] = False
+ # The per-instance counterpart of ``_authors_caller_facing_message``, set only by
+ # :meth:`as_caller_fault`, for a class whose instances are not all the caller's fault.
+ _raised_as_caller_fault: bool = False
@classmethod
def title(cls) -> str:
@@ -659,6 +677,34 @@ class PipelexError(Exception):
super().__init__(message)
self.message = message
+ def as_caller_fault(self, *, user_action: UserAction | None = None) -> Self:
+ """Classify this error, where it is raised, as a fault in the caller's own method or inputs.
+
+ Its report then carries the ``INPUT`` domain, so an HTTP surface answers 422, and a
+ caller-facing ``message``, which STRICT disclosure keeps (see :class:`DisclosureMode`): the
+ two facts a class declares with ``error_domain = ErrorDomain.INPUT`` and
+ ``_authors_caller_facing_message = True``. It serves a class raised both for the caller's
+ faults and for faults that are not the caller's, which therefore cannot declare them: the
+ raise site that knows says so there, for this one error. A plain wrapper raised from this
+ error inherits the ``INPUT`` domain through the cause chain, but never the caller-facing
+ flag, since its own message is not this one.
+
+ The raise site vouches for the message: it names only the caller's own method and data
+ (pipe codes, concept codes, variable names, the values the caller sent), never a server
+ path, a secret, or the text of an exception that is not a Pipelex error.
+
+ Args:
+ user_action: The next step for the caller, when the raise site can name one.
+
+ Returns:
+ This error, so that the raise site reads ``raise SomeError(msg).as_caller_fault()``.
+ """
+ self.error_domain = ErrorDomain.INPUT
+ self._raised_as_caller_fault = True
+ if user_action is not None:
+ self.user_action = user_action
+ return self
+
def to_error_report(self) -> ErrorReport:
"""Return a structured error report, enriched from the ``__cause__`` chain.
@@ -683,7 +729,7 @@ class PipelexError(Exception):
type_uri=type(self).type_uri(),
error_domain=self.error_domain,
user_action=self.user_action,
- caller_facing_message=self._authors_caller_facing_message,
+ caller_facing_message=self._authors_caller_facing_message or self._raised_as_caller_fault,
)
return self._enrich_error_report_from_cause(report)
diff --git a/pipelex/builder/operations/validate_ops.py b/pipelex/builder/operations/validate_ops.py
index e4cba9c45..e8de72386 100644
--- a/pipelex/builder/operations/validate_ops.py
+++ b/pipelex/builder/operations/validate_ops.py
@@ -15,7 +15,9 @@ from pipelex.interpreter_hub import (
from pipelex.pipeline.advisory_warnings import collect_advisory_warnings
from pipelex.pipeline.blueprint_selection import collect_entry_pipe_refs
from pipelex.pipeline.bundle_validator import BundleValidator
+from pipelex.pipeline.execution_seams import acquire_library
from pipelex.pipeline.validate_bundle import build_validated_pipes, validate_bundle
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
if TYPE_CHECKING:
from pathlib import Path
@@ -36,16 +38,31 @@ async def validate_all(
Raises:
ValidateBundleError: If validation fails.
"""
- # acquire_and_validate opens a fresh library, loads the resolved dirs, sweeps every loaded pipe,
- # and tears the library down — the standalone validate-all lifecycle (D6).
- dry_run_results = await BundleValidator().acquire_and_validate(
+ # The standalone validate-all lifecycle (D6), spelled out rather than through
+ # BundleValidator.acquire_and_validate so that a refusal is translated while the validated library
+ # is still current: the translation reads the library's pipe sources to locate an item, and a
+ # failure of the teardown itself must stay the fault it is rather than become a verdict. A refusal
+ # of the libraries while they load (the caller's own directories) or of a pipe's dry run is the
+ # invalid verdict, through the shared bundle-loading cascade, as on `pipelex validate --all`.
+ prev_library_id = get_current_library_id_or_none()
+ acquired_id, _ = acquire_library(
+ library_id="",
library_dirs=[str(library_dir) for library_dir in library_dirs] if library_dirs else None,
+ library_dirs_are_callers=True,
)
+ try:
+ with translate_to_validate_bundle_error():
+ dry_run_results = await BundleValidator().validate_current_library()
+ finally:
+ if prev_library_id is not None:
+ set_current_library(library_id=prev_library_id)
+ else:
+ clear_current_library()
+ get_library_manager().teardown(library_id=acquired_id)
# No `pending_signatures` here by design: it is a per-bundle, top-down-build nudge ("which headers
# are still unimplemented in this bundle"), surfaced only by `validate bundle`. The validate-all
- # sweep is a whole-library check, not a build step — and `acquire_and_validate` tears its library
- # down before returning, so the set could not be computed post-hoc without reshaping a shared method.
+ # sweep is a whole-library check, not a build step, so it makes no runnability claim to back.
return {
"success": True,
"is_valid": True,
@@ -149,11 +166,16 @@ async def validate_pipe(
set_current_library(library_id=library_id)
effective_dirs, _ = resolve_library_dirs(library_dirs)
+ # A refusal of the libraries while they load, or of the pipe's dry run, is the invalid verdict,
+ # through the shared bundle-loading cascade, as on `pipelex validate pipe`. The lookup between
+ # them stays outside it: a code that names no pipe, or several, is an unresolvable target.
if effective_dirs:
- library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
+ with translate_to_validate_bundle_error():
+ library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
the_pipe = get_required_entry_pipe(pipe_code=pipe_code)
- dry_run_results = await BundleValidator().validate_pipes(pipes=[the_pipe], library_id=library_id)
+ with translate_to_validate_bundle_error():
+ dry_run_results = await BundleValidator().validate_pipes(pipes=[the_pipe], library_id=library_id)
return {
"success": True,
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index 882d93a14..a73800e60 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -22,7 +22,7 @@ Markdown structure per command:
- `fix`: `# Fix applied - bundle is valid` after one or more fixes, `# Bundle already valid` when the loop had nothing to apply, or `# Bundle valid but not runnable` when pending `PipeSignature` placeholders remain. The JSON success envelope carries `is_valid`, `bundle_path`, `iterations`, `fixes_applied`, `files_written`, `remaining_errors`, and, on successful validation, `pending_signatures` plus `is_runnable`. Whole-bundle fix runs are strict by default: they emit the success envelope but exit 1 on `not is_runnable` unless `--allow-signatures` is passed. A still-invalid verdict exits 1 via `FixBundleError` on stderr with the same structured result fields plus any `bail_reason`.
- `migrate`: `# Configuration migration`, the mode (applied / dry run) and verdict, the directories walked, a files-walked/changed/written count, then one `## <path>` section per file that is not clean listing the entries applied, the entries blocked with their reason and guidance, and any unexplained paths. Paths, operation kinds and ledger-supplied values only — no value read from the user's file is ever rendered, in either format.
- `init`: `# Pipelex initialized` with target directory, enabled backends, and routing profile.
-- error path: `# Error: <error_type>`, the message, the hint as a `> 💡` callout, and a `## Details` section. `error_source` (internal stack frames) is omitted from markdown — it remains in the JSON envelope (`--error-format json`) for programmatic consumers.
+- error path: `# Error: <error_type>`, the message, the hint as a `> 💡` callout, the `validation_errors` items (when the cause's report carries any) as the same grouped prose `validate` prints, and a `## Details` section. `error_source` (internal stack frames) is omitted from markdown — it remains in the JSON envelope (`--error-format json`) for programmatic consumers.
## Companion: Agent Skills
@@ -102,10 +102,12 @@ commands/
## Key Patterns
- **Output contract**: Commands with `--format` emit success via `agent_success_formatted(result, markdown_renderer, output_format)` — JSON or a markdown renderer per the explicit `output_format` argument. `agent_error(message, error_type, cause)` dispatches JSON or markdown by reading the `_agent_cli_error_format` ContextVar, which each `--format`-aware command sets via `set_agent_cli_error_format(error_format or output_format)` at function entry. Exceptions that print directly to stdout: `fmt`/`lint` (plxt passthrough), `concept`/`pipe` (raw TOML). Markdown renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (lifted to the non-CLI `pipelex/pipeline/validation_render.py` so `pipelex-api` can import it without CLI/Typer deps), `format_fix_markdown` (non-CLI `pipelex/pipeline/fixes/fix_render.py`), `_format_init_markdown` (`init_cmd.py`).
-- **Error classification**: Each error carries a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. `agent_error()` reads them **report-first**: a `PipelexError` cause's `to_error_report()` wins, and the `AGENT_ERROR_HINTS` / `AGENT_ERROR_DOMAINS` dicts in `agent_output.py` are the fallback for error types that cannot self-describe (builtins, third-party classes, synthetic `error_type` labels). Two ways a class self-describes, and both bar it from the dicts: a class-level `error_domain` / `user_action`, **or** — for the `CogtError` family — an `error_category`, from which `InferenceErrorCategory.error_domain` derives the domain (so `CONTENT` inference failures report `input`, and a dict entry for such a class would be unreachable). `tests/unit/pipelex/cli/test_agent_output_drift.py` enforces both. Because the read is report-first, the `error_type` an arm passes must name the class that actually failed — `type(exc).__name__`, not the base class the `except` caught. A hardcoded label detaches the reported class from the domain and hint riding the same envelope from the cause's report, so a consumer reading `error_type` is told one class produced a classification only another declares; the `validate pipe` / `validate bundle` not-found arms did exactly that until the entry-shaped lookups gained their own INPUT-domain classes. A synthetic label is still legitimate where there is no exception class to name, and that is what the dicts key on. When a derived domain is wrong for a class, declare an explicit `error_domain` on the class — `ModelChoiceNotFoundError` does, because a mistyped model reference is the caller's to fix even though the category is `CONFIGURATION`. The `error_domain` also drives the HTTP-status mapping for downstream APIs — see `error_domain_to_http_status()` in `pipelex/base_exceptions.py` and [Error Model](../../../docs/under-the-hood/error-model.md).
+- **Error classification**: Each error carries a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. `agent_error()` reads them **report-first**: a `PipelexError` cause's `to_error_report()` wins, and the `AGENT_ERROR_HINTS` / `AGENT_ERROR_DOMAINS` dicts in `agent_output.py` are the fallback for error types that cannot self-describe (builtins, third-party classes, synthetic `error_type` labels). Two ways a class self-describes, and both bar it from the dicts: a class-level `error_domain` / `user_action`, **or** — for the `CogtError` family — an `error_category`, from which `InferenceErrorCategory.error_domain` derives the domain (so `CONTENT` inference failures report `input`, and a dict entry for such a class would be unreachable). `tests/unit/pipelex/cli/test_agent_output_drift.py` enforces both. Because the read is report-first, the `error_type` an arm passes must name the class that actually failed — `type(exc).__name__`, not the base class the `except` caught. A hardcoded label detaches the reported class from the domain and hint riding the same envelope from the cause's report, so a consumer reading `error_type` is told one class produced a classification only another declares; the `validate pipe` / `validate bundle` not-found arms did exactly that until the entry-shaped lookups gained their own INPUT-domain classes. A synthetic label is still legitimate where there is no exception class to name, and that is what the dicts key on. The run arms are the one deliberate exception: they pass `PipelineExecutionError`, the one class a run failure arrives as, and `run_failure_fields()` adds `pipe_code` / `pipe_stack` (the failing pipe and its path) and `cause_type` / `cause_message` (the root fault's, found with `find_root_fault()`, never the router wrapper right under the run error); the classification and the located message come from the run error's report, which is its root fault's. When a derived domain is wrong for a class, declare an explicit `error_domain` on the class — `ModelChoiceNotFoundError` does, because a mistyped model reference is the caller's to fix even though the category is `CONFIGURATION`. The `error_domain` also drives the HTTP-status mapping for downstream APIs — see `error_domain_to_http_status()` in `pipelex/base_exceptions.py` and [Error Model](../../../docs/under-the-hood/error-model.md).
- **The `migration` field on a configuration error**: A `PipelexConfigError` carries one when a scan of this machine's configuration directories found something — and only then, so its presence is the test for whether the migration history has anything to say. Whether a command *repairs* it is the separate `would_write` field: true means the configuration is *old*, and the loop is `pipelex-agent migrate --dry-run --format json`, show the user, then `--yes`; false means the block is a diagnosis its `plans` carry and the command would rewrite nothing, so branching on presence alone sends an agent to a run with nothing to do. Its `plans` are the same shape that command emits under its own `plans` key. `error_domain` stays `config`: a domain the hook specification does not know routes to BLOCK, which would stop an agent instead of telling it what to run. See `docs/migration-ledger.md` → "Reporting a stale configuration on a validation error".
- **Init**: All commands that need Pipelex use `make_pipelex_for_agent_cli(library_dirs)`. It catches init errors and routes them through `agent_error()`.
- **Async core**: Run and validate are async — commands use `asyncio.run()`.
- **File convention**: Generated outputs go to `mthds-wip/` with incremental naming (`pipeline_01/`, `pipeline_02/`). Exception: `run method` on a fetched target (a method address or GitHub URL) anchors its run outputs in `results/` under the caller's CWD via `run_pipeline_core`'s `output_dir_override` — the fetched clone is an ephemeral temp dir deleted at process exit, so bundle-adjacent outputs would be lost.
+- **Validate refusals are verdicts**: the `validate` commands run their library load inside `translate_to_validate_bundle_error` (`pipelex/pipeline/validate_bundle_translation.py`), so every input-domained refusal raised while loading a bundle, the unknown model (`PipeOperatorModelChoiceError`, an `unknown_model` item) included, reaches the command as a `ValidateBundleError` and leaves with the invalid-verdict envelope and exit 1. No `validate` command keeps an arm of its own for a model-choice error; exit 2 stays for a failure of the tool or its environment (config, runtime, security).
+- **Run refusals are verdicts too**: a run loads its bundle inside the same translation (`acquire_library`), so an invalid bundle leaves `run pipe` / `run bundle` / `run method` as a `ValidateBundleError` with exit 1, through the generic `agent_error` arm, and `_assemble_error_payload` copies the report's `validation_errors` into the envelope for any cause that carries them. `run_pipeline_core` sets `library_dirs_are_callers=True`, so a refusal in a `-L` directory (or the bundle's own directory) is the same verdict; `run bundle`'s own parse of a bundle without `--pipe` goes through the translation too. So no `run` command keeps an arm of its own for a model-choice error either: an unknown model reaches it as the verdict's `unknown_model` item.
- **Method-reference failures**: the `run`/`validate`/`inputs` method commands call `resolve_method_target(..., raise_ref_errors=True)` and shape the typed `MethodRefError` subclasses into `agent_error(...)` themselves (validate uses `exit_code=2`, its no-verdict convention) — the human CLI's red-text rendering stays in `resolve_method_target`'s default arm.
- **TOML handling**: Uses `tomlkit` (not `tomllib`) to preserve formatting and inline tables.
diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.py
index 3dc0283ef..fd1f2d701 100644
--- a/pipelex/cli/agent_cli/commands/agent_output.py
+++ b/pipelex/cli/agent_cli/commands/agent_output.py
@@ -29,8 +29,8 @@ from typing import Any, NoReturn, cast
import typer
from pipelex.base_exceptions import PipelexError, ValidationErrorItem, iter_cause_chain
-from pipelex.pipeline.exceptions import ValidateBundleError
-from pipelex.pipeline.validation_errors import build_validation_error_items
+from pipelex.pipe_run.located_failure import find_root_fault
+from pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleError
from pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes, format_validation_error_items_markdown
from pipelex.tools.misc.json_utils import clean_json_dumps
@@ -104,13 +104,17 @@ def get_agent_cli_error_format() -> CliOutputFormat:
# drift test — a dead entry is exactly the rot it exists to prevent. When the
# derived domain is not the one this CLI wants, fix it on the class (declare an
# explicit error_domain, as ModelChoiceNotFoundError does), never here.
+# An unknown model is the author's input fault, whether it is raised bare by the deck check or located
+# on its pipe: the next step is to correct the reference, not to diagnose the installation.
+_UNKNOWN_MODEL_HINT = (
+ "Check model name for typos. Use 'pipelex-agent check-model <name> -t <type>' "
+ "to validate or 'pipelex-agent models -t <type>' to list available models."
+)
+
AGENT_ERROR_HINTS: dict[str, str] = {
# Model/routing errors
- "ModelChoiceNotFoundError": (
- "Check model name for typos. Use 'pipelex-agent check-model <name> -t <type>' "
- "to validate or 'pipelex-agent models -t <type>' to list available models."
- ),
- "PipeOperatorModelChoiceError": "Run 'pipelex-agent doctor' to check available models and routing configuration",
+ "ModelChoiceNotFoundError": _UNKNOWN_MODEL_HINT,
+ "PipeOperatorModelChoiceError": _UNKNOWN_MODEL_HINT,
"PipeOperatorModelAvailabilityError": "Run 'pipelex-agent doctor' to check available models and verify API keys",
"ModelDeckPresetValidatonError": (
"Run 'pipelex-agent doctor' to check model configuration. "
@@ -210,7 +214,6 @@ AGENT_ERROR_DOMAINS: dict[str, str] = {
"CodegenLockError": "input",
# config = environment/config changes needed
"ClientAuthenticationError": "config",
- "PipeOperatorModelChoiceError": "config",
"PipeOperatorModelAvailabilityError": "config",
"BinaryNotFoundError": "config",
"InitConfigError": "config",
@@ -261,6 +264,11 @@ def _assemble_error_payload(message: str, *, error_type: str, cause: BaseExcepti
wrong, and the loop it opens is ``pipelex-agent migrate --dry-run --format json`` followed by
``--yes``. Emitted only when the report carries one, so branching on its presence is the
whole test.
+
+ ``validation_errors`` comes from the report as well, whenever it carries any: a command that
+ refuses an invalid bundle (a run refused before any pipe ran, for one) hands the agent the same
+ located items ``validate`` gives, each with its pipe, its field and its fix, rather than only the
+ summary sentence. They are the items :func:`extract_validation_errors` projects, dumped the same way.
"""
error_json: dict[str, Any] = {
"error": True,
@@ -287,6 +295,8 @@ def _assemble_error_payload(message: str, *, error_type: str, cause: BaseExcepti
report_extras["provider"] = report.provider
if report.migration is not None:
report_extras["migration"] = report.migration.model_dump(mode="json")
+ if report.validation_errors:
+ report_extras["validation_errors"] = [item.model_dump(mode="json", exclude_none=True) for item in report.validation_errors]
# hint: report-first, fallback to lookup dict
hint = report_hint or AGENT_ERROR_HINTS.get(error_type)
@@ -325,17 +335,26 @@ def _assemble_error_payload(message: str, *, error_type: str, cause: BaseExcepti
# ``error_source`` is dropped from markdown — it's internal stack frames that
# don't help an LLM fix a `.mthds` file. The field stays in the JSON envelope
# for programmatic consumers.
-_MARKDOWN_RESERVED_KEYS: frozenset[str] = frozenset({"error", "error_type", "message", "hint", "error_source"})
+_MARKDOWN_RESERVED_KEYS: frozenset[str] = frozenset({"error", "error_type", "message", "hint", "error_source", "validation_errors"})
def _render_error_markdown(payload: dict[str, Any]) -> str:
- """Render an assembled error payload as agent-readable markdown."""
+ """Render an assembled error payload as agent-readable markdown.
+
+ ``validation_errors`` render as the same grouped prose ``validate`` prints, rather than as a JSON
+ dump under Details, so an agent reads a refused run's items the way it reads an invalid verdict's.
+ """
lines: list[str] = [f"# Error: {payload['error_type']}", "", str(payload["message"])]
hint = payload.get("hint")
if hint:
lines += ["", f"> 💡 **Hint:** {hint}"]
+ validation_errors = payload.get("validation_errors")
+ if isinstance(validation_errors, list) and validation_errors:
+ items = [ValidationErrorItem.model_validate(item) for item in cast("list[dict[str, Any]]", validation_errors)]
+ lines += ["", format_validation_error_items_markdown(items)]
+
detail_keys = [key for key in payload if key not in _MARKDOWN_RESERVED_KEYS]
if detail_keys:
lines += ["", "## Details", ""]
@@ -454,22 +473,46 @@ def agent_success_formatted(
print(markdown_renderer(result))
+def run_failure_fields(*, error: PipelineExecutionError) -> dict[str, Any]:
+ """The fields an agent reads off a failed run, beside the report-derived ones.
+
+ ``pipe_code`` and ``pipe_stack`` name the pipe that failed and its path from the entry pipe.
+ ``cause_type`` and ``cause_message`` are the root fault's identity and its own message, not
+ those of the wrapper right under the ``PipelineExecutionError``, which is the pipe router's or
+ a bridge's and says nothing about what went wrong.
+ """
+ fields: dict[str, Any] = {
+ "pipe_code": error.pipe_code,
+ "pipe_stack": error.pipe_stack,
+ }
+ cause = error.__cause__
+ if cause is None:
+ return fields
+ root_fault = find_root_fault(error=cause)
+ if root_fault is None:
+ fields["cause_type"] = type(cause).__name__
+ fields["cause_message"] = str(cause)
+ else:
+ root_report = root_fault.to_error_report()
+ fields["cause_type"] = root_report.error_type
+ fields["cause_message"] = root_report.message
+ return fields
+
+
def extract_validation_errors(exc: ValidateBundleError) -> list[dict[str, Any]]:
"""Project a ``ValidateBundleError`` into the CLI ``validation_errors`` JSON array.
- Thin adapter over the shared ``build_validation_error_items`` builder — the
+ Thin adapter over ``ValidateBundleError.validation_error_items`` — the shared builder,
same one feeding the API 422's ``ErrorReport.validation_errors`` — so the CLI
and API structured shapes can never drift. Each typed item is dumped to a
plain dict with unset fields dropped (``exclude_none``), matching the
machine-first agent-CLI envelope; the entries carry ``category``,
``error_type``, ``message``, and whatever identity / ``source`` fields the
- underlying error populated. Two residuals make the invariant total: a dry-run
- failure with no structured locator becomes one ``dry_run``-category item, and
- a parse-level failure (TOML syntax, an empty blueprint, a bundle elaborator)
- that carries only a message becomes one ``blueprint_validation`` residual
- (``fallback_message=exc.message``). So the envelope's ``validation_errors[]``
- is non-empty on every invalid verdict (the structured-info invariant) — never
- a bare message.
+ underlying error populated. Each pipe whose dry run failed becomes its own
+ located ``dry_run`` item, and a parse-level failure that carries only a
+ message becomes one ``blueprint_validation`` residual. So the envelope's
+ ``validation_errors[]`` is non-empty on every invalid verdict (the
+ structured-info invariant) — never a bare message.
Args:
exc: The ValidateBundleError to extract errors from.
@@ -477,14 +520,7 @@ def extract_validation_errors(exc: ValidateBundleError) -> list[dict[str, Any]]:
Returns:
List of dicts, each with at minimum ``category`` and ``message``.
"""
- items = build_validation_error_items(
- blueprint_errors=exc.pipelex_bundle_blueprint_validation_errors,
- factory_errors=exc.pipe_factory_errors,
- pipe_validation_errors=exc.pipe_validation_error_data,
- dry_run_error_message=exc.dry_run_error_message,
- fallback_message=exc.message,
- )
- return [item.model_dump(mode="json", exclude_none=True) for item in items]
+ return [item.model_dump(mode="json", exclude_none=True) for item in exc.validation_error_items()]
def _render_validate_bundle_markdown(
@@ -506,7 +542,7 @@ def _render_validate_bundle_markdown(
# A hint needs an action behind it (disease E): when items carry a suggested fix, name the exact
# fix command — same predicate and command shape as the human footer — instead of the boilerplate
- # "check the validation_errors array" hint that the JSON envelope keeps.
+ # class-level hint that the JSON envelope keeps.
fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs)
if fixable_count:
fix_command = build_fix_command(
diff --git a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
index 43ac0fe08..fcff51a97 100644
--- a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
@@ -105,11 +105,8 @@ def inputs_bundle_cmd(
agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)
except ValidateBundleError as exc:
- validation_errors = extract_validation_errors(exc)
- extra: dict[str, Any] = {"validation_errors": validation_errors}
- if exc.dry_run_error_message:
- extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, error_type="ValidateBundleError", cause=exc, **extra)
+ # A failing dry run rides validation_errors as one located dry_run item per failing pipe.
+ agent_error(exc.message, error_type="ValidateBundleError", cause=exc, validation_errors=extract_validation_errors(exc))
except NoInputsRequiredError as exc:
emit_no_inputs_result(pipe_code=pipe_code, message=str(exc), template_format=template_format)
diff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
index 582c3dbf1..025f52a0d 100644
--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
@@ -86,11 +86,8 @@ def inputs_method_cmd(
agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)
except ValidateBundleError as exc:
- validation_errors = extract_validation_errors(exc)
- extra: dict[str, Any] = {"validation_errors": validation_errors}
- if exc.dry_run_error_message:
- extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, error_type="ValidateBundleError", cause=exc, **extra)
+ # A failing dry run rides validation_errors as one located dry_run item per failing pipe.
+ agent_error(exc.message, error_type="ValidateBundleError", cause=exc, validation_errors=extract_validation_errors(exc))
except NoInputsRequiredError as exc:
emit_no_inputs_result(pipe_code=pipe_code, message=str(exc), template_format=template_format)
diff --git a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
index a5cf89c89..d109d3103 100644
--- a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
@@ -85,11 +85,8 @@ def inputs_pipe_cmd(
agent_error(f"File not found: {exc}", error_type="FileNotFoundError", cause=exc)
except ValidateBundleError as exc:
- validation_errors = extract_validation_errors(exc)
- extra: dict[str, Any] = {"validation_errors": validation_errors}
- if exc.dry_run_error_message:
- extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, error_type="ValidateBundleError", cause=exc, **extra)
+ # A failing dry run rides validation_errors as one located dry_run item per failing pipe.
+ agent_error(exc.message, error_type="ValidateBundleError", cause=exc, validation_errors=extract_validation_errors(exc))
except NoInputsRequiredError as exc:
# Not really an error - just a pipe with no inputs
diff --git a/pipelex/cli/agent_cli/commands/run/_run_core.py b/pipelex/cli/agent_cli/commands/run/_run_core.py
index 3721f0e92..32f973c5c 100644
--- a/pipelex/cli/agent_cli/commands/run/_run_core.py
+++ b/pipelex/cli/agent_cli/commands/run/_run_core.py
@@ -74,6 +74,8 @@ async def run_pipeline_core(
Dictionary with execution results suitable for JSON serialization.
Raises:
+ ValidateBundleError: If the bundle is refused while it loads, before any pipe runs; it carries
+ the same located ``validation_errors`` validating the bundle gives.
PipelineExecutionError: If the pipeline execution fails.
"""
pipe_run_mode = PipeRunMode.DRY if dry_run else None
@@ -96,6 +98,8 @@ async def run_pipeline_core(
execution_config=execution_config,
library_dirs=library_dirs,
inputs_base_dir=inputs_base_dir,
+ # The directories a CLI loads are the caller's own: a refusal there is their invalid bundle.
+ library_dirs_are_callers=True,
)
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.py
index daf620714..75ba7ca72 100644
--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py
@@ -12,18 +12,23 @@ from mthds.runners.types import RunnerType
from pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME
from pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli
-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success_formatted, set_agent_cli_error_format
+from pipelex.cli.agent_cli.commands.agent_output import (
+ CliOutputFormat,
+ agent_error,
+ agent_success_formatted,
+ run_failure_fields,
+ set_agent_cli_error_format,
+)
from pipelex.cli.agent_cli.commands.run._output_helpers import format_run_markdown
from pipelex.cli.agent_cli.commands.run._run_core import run_pipeline_core
from pipelex.cli.agent_cli.commands.run._run_core_api import run_pipeline_core_api
from pipelex.cli.agent_cli.commands.run.stdin_resolver import parse_cli_inputs
-from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
-from pipelex.mthds_parsing.exceptions import MthdsParserError
from pipelex.mthds_parsing.helpers import MTHDS_EXTENSION, is_pipelex_file
from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import Pipelex
-from pipelex.pipeline.exceptions import PipelineExecutionError
+from pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleError
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
def run_bundle_cmd(
@@ -140,7 +145,10 @@ def run_bundle_cmd(
try:
mthds_content = Path(bundle_path).read_text(encoding="utf-8")
if not pipe_code:
- bundle_blueprint = MthdsParser.make_pipelex_bundle_blueprint(mthds_content=mthds_content)
+ # A bundle that does not parse is the invalid verdict, with the items `validate` gives,
+ # as it is when the run refuses it while loading.
+ with translate_to_validate_bundle_error():
+ bundle_blueprint = MthdsParser.make_pipelex_bundle_blueprint(mthds_content=mthds_content, mthds_source=bundle_path)
main_pipe_code = bundle_blueprint.main_pipe
if not main_pipe_code:
agent_error(
@@ -152,8 +160,8 @@ def run_bundle_cmd(
agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)
except (OSError, UnicodeDecodeError) as exc:
agent_error(f"Failed to read bundle file '{bundle_path}': {exc}", error_type=type(exc).__name__, cause=exc)
- except MthdsParserError as exc:
- agent_error(f"Failed to parse bundle '{bundle_path}': {exc}", error_type=type(exc).__name__, cause=exc)
+ except ValidateBundleError as exc:
+ agent_error(f"Failed to parse bundle '{bundle_path}': {exc.message}", error_type="ValidateBundleError", cause=exc)
# Load inputs: --inputs flag takes priority, then stdin fallback, then auto-detected
parsed_inputs = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True, auto_inputs_dir=auto_inputs_dir)
@@ -219,24 +227,7 @@ def run_bundle_cmd(
)
except PipelineExecutionError as exc:
- extra_fields: dict[str, Any] = {
- "pipe_code": exc.pipe_code,
- "pipe_stack": exc.pipe_stack,
- }
- if exc.__cause__:
- extra_fields["cause_type"] = type(exc.__cause__).__name__
- extra_fields["cause_message"] = str(exc.__cause__)
- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **extra_fields)
-
- except PipeOperatorModelChoiceError as exc:
- agent_error(
- exc.message,
- error_type="PipeOperatorModelChoiceError",
- cause=exc,
- pipe_code=exc.pipe_code,
- model_type=str(exc.model_type),
- model_choice=str(exc.model_choice),
- )
+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))
except PipeOperatorModelAvailabilityError as exc:
availability_extra: dict[str, Any] = {
diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.py
index f61145e57..88b358831 100644
--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py
@@ -11,14 +11,19 @@ import typer
from mthds.runners.types import RunnerType
from pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli
-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success_formatted, set_agent_cli_error_format
+from pipelex.cli.agent_cli.commands.agent_output import (
+ CliOutputFormat,
+ agent_error,
+ agent_success_formatted,
+ run_failure_fields,
+ set_agent_cli_error_format,
+)
from pipelex.cli.agent_cli.commands.run._output_helpers import format_run_markdown
from pipelex.cli.agent_cli.commands.run._run_core import run_pipeline_core
from pipelex.cli.agent_cli.commands.run._run_core_api import run_pipeline_core_api
from pipelex.cli.agent_cli.commands.run.stdin_resolver import parse_cli_inputs
from pipelex.cli.commands.run._inputs_file_loader import resolve_inputs_arg_against_dir
from pipelex.cli.method_resolver import method_output_base_dir, resolve_method_target
-from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.methods.exceptions import MethodRefError
from pipelex.mthds_parsing.helpers import MTHDS_EXTENSION
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
@@ -194,24 +199,7 @@ def run_method_cmd(
)
except PipelineExecutionError as exc:
- extra_fields: dict[str, Any] = {
- "pipe_code": exc.pipe_code,
- "pipe_stack": exc.pipe_stack,
- }
- if exc.__cause__:
- extra_fields["cause_type"] = type(exc.__cause__).__name__
- extra_fields["cause_message"] = str(exc.__cause__)
- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **extra_fields)
-
- except PipeOperatorModelChoiceError as exc:
- agent_error(
- exc.message,
- error_type="PipeOperatorModelChoiceError",
- cause=exc,
- pipe_code=exc.pipe_code,
- model_type=str(exc.model_type),
- model_choice=str(exc.model_choice),
- )
+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))
except PipeOperatorModelAvailabilityError as exc:
availability_extra: dict[str, Any] = {
diff --git a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
index df5e7f80a..65d8aa4bc 100644
--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
@@ -11,13 +11,18 @@ import typer
from mthds.runners.types import RunnerType
from pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli
-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success_formatted, set_agent_cli_error_format
+from pipelex.cli.agent_cli.commands.agent_output import (
+ CliOutputFormat,
+ agent_error,
+ agent_success_formatted,
+ run_failure_fields,
+ set_agent_cli_error_format,
+)
from pipelex.cli.agent_cli.commands.run._output_helpers import format_run_markdown
from pipelex.cli.agent_cli.commands.run._run_core import run_pipeline_core
from pipelex.cli.agent_cli.commands.run._run_core_api import run_pipeline_core_api
from pipelex.cli.agent_cli.commands.run.stdin_resolver import parse_cli_inputs
from pipelex.cli.method_resolver import resolve_pipe_from_exports
-from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.mthds_parsing.helpers import MTHDS_EXTENSION, is_pipelex_file
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import Pipelex
@@ -170,24 +175,7 @@ def run_pipe_cmd(
)
except PipelineExecutionError as exc:
- extra_fields: dict[str, Any] = {
- "pipe_code": exc.pipe_code,
- "pipe_stack": exc.pipe_stack,
- }
- if exc.__cause__:
- extra_fields["cause_type"] = type(exc.__cause__).__name__
- extra_fields["cause_message"] = str(exc.__cause__)
- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **extra_fields)
-
- except PipeOperatorModelChoiceError as exc:
- agent_error(
- exc.message,
- error_type="PipeOperatorModelChoiceError",
- cause=exc,
- pipe_code=exc.pipe_code,
- model_type=str(exc.model_type),
- model_choice=str(exc.model_choice),
- )
+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))
except PipeOperatorModelAvailabilityError as exc:
availability_extra: dict[str, Any] = {
diff --git a/pipelex/cli/agent_cli/commands/validate/_validate_core.py b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
index df07de7f2..96d0f9f17 100644
--- a/pipelex/cli/agent_cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
@@ -18,6 +18,7 @@ from pipelex.pipeline.blueprint_selection import collect_entry_pipe_refs
from pipelex.pipeline.bundle_validator import BundleValidator
from pipelex.pipeline.execution_seams import acquire_library
from pipelex.pipeline.validate_bundle import build_pending_signatures, build_validated_pipes, validate_bundle
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
if TYPE_CHECKING:
from pathlib import Path
@@ -42,14 +43,25 @@ async def validate_all_core(*, library_dirs: list[Path] | None = None, allow_sig
# signatures and must read the LIBRARY-WIDE pending set BEFORE teardown — acquire_and_validate
# returns only the per-pipe status map and tears the library down before we could compute it.
prev_library_id = get_current_library_id_or_none()
+ # A refusal of the libraries while loading them is the invalid verdict, through the shared
+ # bundle-loading cascade, as on `validate bundle`. The directories are the caller's own, so
+ # acquire_library translates their load itself, while the library is still current: the translation
+ # reads the library's pipe sources to locate an item, and a translation around the call would run
+ # only after acquire_library had torn the failed library down, leaving the item without its file.
+ # The sweep below stays untranslated on purpose: a failing dry run is answered as the DryRunError it
+ # is, as on `validate pipe`.
acquired_id, _ = acquire_library(
library_id="",
library_dirs=[str(library_dir) for library_dir in library_dirs] if library_dirs else None,
+ library_dirs_are_callers=True,
)
try:
# acquire_library left the freshly-acquired library current, so the inner sweep targets it
# (it filters signatures in strict mode itself). The returned map is keyed by namespaced pipe_ref.
- dry_run_results = await BundleValidator().validate_current_library(allow_signatures=allow_signatures)
+ # A pipe whose dry run fails is the invalid verdict, one located dry_run item per failing pipe,
+ # through the same cascade and item builder as `validate bundle`.
+ with translate_to_validate_bundle_error():
+ dry_run_results = await BundleValidator().validate_current_library(allow_signatures=allow_signatures)
# pending_signatures is the library-wide set of still-unimplemented forward declarations;
# is_runnable = not pending. `validate all` now makes a strict runnability claim (the consumer
@@ -156,10 +168,16 @@ async def validate_pipe_core(
effective_dirs, _ = resolve_library_dirs(library_dirs)
if effective_dirs:
- library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
+ # A refusal of the libraries while loading them is the invalid verdict, through the shared
+ # bundle-loading cascade, as on `validate bundle`.
+ with translate_to_validate_bundle_error():
+ library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
+ # The entry-pipe lookup stays outside the cascade: a code naming no pipe is no verdict. A pipe whose
+ # dry run fails is the invalid verdict, one located dry_run item per failing pipe, as on `validate bundle`.
the_pipe = get_required_entry_pipe(pipe_code=pipe_code)
- dry_run_results = await BundleValidator().validate_pipes(pipes=[the_pipe], library_id=library_id, allow_signatures=allow_signatures)
+ with translate_to_validate_bundle_error():
+ dry_run_results = await BundleValidator().validate_pipes(pipes=[the_pipe], library_id=library_id, allow_signatures=allow_signatures)
return {
"success": True,
diff --git a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
index 27cc2c0b0..b3f17f88f 100644
--- a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
@@ -12,6 +12,7 @@ from pipelex.cli.agent_cli.commands.agent_output import (
agent_error,
agent_error_validate_bundle,
agent_success_formatted,
+ run_failure_fields,
set_agent_cli_error_format,
)
from pipelex.cli.agent_cli.commands.bundle_path_resolver import resolve_bundle_target
@@ -19,7 +20,6 @@ from pipelex.cli.agent_cli.commands.validate._validate_core import (
validate_bundle_core,
validate_pipe_in_bundle_core,
)
-from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.graph.graph_rendering import GraphFormat
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.mthds_parsing.exceptions import MthdsParserError
@@ -126,14 +126,13 @@ def validate_bundle_cmd(
)
result.update(graph_result)
except PipelineExecutionError as exc:
- graph_extra: dict[str, Any] = {
- "pipe_code": exc.pipe_code,
- "pipe_stack": exc.pipe_stack,
- }
- if exc.__cause__:
- graph_extra["cause_type"] = type(exc.__cause__).__name__
- graph_extra["cause_message"] = str(exc.__cause__)
- agent_error(f"Graph generation failed: {exc.message}", error_type="PipelineExecutionError", cause=exc, exit_code=2, **graph_extra)
+ agent_error(
+ f"Graph generation failed: {exc.message}",
+ error_type="PipelineExecutionError",
+ cause=exc,
+ exit_code=2,
+ **run_failure_fields(error=exc),
+ )
except MthdsParserError as exc:
agent_error(f"Graph generation failed: {exc}", error_type=type(exc).__name__, cause=exc, exit_code=2)
except typer.Exit:
@@ -155,14 +154,13 @@ def validate_bundle_cmd(
)
result.update(view_result)
except PipelineExecutionError as exc:
- view_extra: dict[str, Any] = {
- "pipe_code": exc.pipe_code,
- "pipe_stack": exc.pipe_stack,
- }
- if exc.__cause__:
- view_extra["cause_type"] = type(exc.__cause__).__name__
- view_extra["cause_message"] = str(exc.__cause__)
- agent_error(f"View generation failed: {exc.message}", error_type="PipelineExecutionError", cause=exc, exit_code=2, **view_extra)
+ agent_error(
+ f"View generation failed: {exc.message}",
+ error_type="PipelineExecutionError",
+ cause=exc,
+ exit_code=2,
+ **run_failure_fields(error=exc),
+ )
except MthdsParserError as exc:
agent_error(f"View generation failed: {exc}", error_type=type(exc).__name__, cause=exc, exit_code=2)
except typer.Exit:
@@ -200,17 +198,6 @@ def validate_bundle_cmd(
# footer. Signatures never reach here (they are a runnability fact, gated above).
agent_error_validate_bundle(exc, bundle_path=Path(bundle_path), library_dirs=library_dirs, allow_signatures=allow_signatures)
- except PipeOperatorModelChoiceError as exc:
- agent_error(
- exc.message,
- error_type="PipeOperatorModelChoiceError",
- cause=exc,
- exit_code=2,
- pipe_code=exc.pipe_code,
- model_type=str(exc.model_type),
- model_choice=str(exc.model_choice),
- )
-
except PipeOperatorModelAvailabilityError as exc:
availability_extra: dict[str, Any] = {
"pipe_code": exc.pipe_code,
diff --git a/pipelex/cli/agent_cli/commands/validate/method_cmd.py b/pipelex/cli/agent_cli/commands/validate/method_cmd.py
index 794914167..cf841e73d 100644
--- a/pipelex/cli/agent_cli/commands/validate/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/method_cmd.py
@@ -21,7 +21,6 @@ from pipelex.cli.agent_cli.commands.validate._validate_core import (
validate_pipe_in_bundle_core,
)
from pipelex.cli.method_resolver import resolve_method_target
-from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.methods.exceptions import MethodRefError
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import Pipelex
@@ -129,17 +128,6 @@ def validate_method_cmd(
# structured envelope; markdown renders the items as prose with a fix-aware footer.
agent_error_validate_bundle(exc, bundle_path=bundle_path, library_dirs=library_dirs_paths, allow_signatures=allow_signatures)
- except PipeOperatorModelChoiceError as exc:
- agent_error(
- exc.message,
- error_type="PipeOperatorModelChoiceError",
- cause=exc,
- exit_code=2,
- pipe_code=exc.pipe_code,
- model_type=str(exc.model_type),
- model_choice=str(exc.model_choice),
- )
-
except PipeOperatorModelAvailabilityError as exc:
availability_extra: dict[str, Any] = {
"pipe_code": exc.pipe_code,
diff --git a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
index 2f7dce6a1..b5aae81bc 100644
--- a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
@@ -19,11 +19,9 @@ from pipelex.cli.agent_cli.commands.validate._validate_core import (
validate_pipe_core,
)
from pipelex.cli.method_resolver import resolve_pipe_from_exports
-from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.mthds_parsing.helpers import MTHDS_EXTENSION, is_pipelex_file
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
-from pipelex.pipe_run.exceptions import DryRunError
from pipelex.pipelex import Pipelex
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validation_render import format_validate_markdown
@@ -94,8 +92,8 @@ def validate_pipe_cmd(
except ValidateBundleError as exc:
# Invalid verdict: structured failure envelope. validation_errors[] is the shared builder's
- # output (a residual dry-run failure rides one dry_run item). Signatures are a runnability
- # fact (pending_signatures + the gate above), not an error, so they never reach this arm.
+ # output (a failing dry run rides one located dry_run item per failing pipe). Signatures are a
+ # runnability fact (pending_signatures + the gate above), not an error, so they never reach this arm.
agent_error(
exc.message,
error_type="ValidateBundleError",
@@ -104,17 +102,6 @@ def validate_pipe_cmd(
validation_errors=extract_validation_errors(exc),
)
- except PipeOperatorModelChoiceError as exc:
- agent_error(
- exc.message,
- error_type="PipeOperatorModelChoiceError",
- cause=exc,
- pipe_code=exc.pipe_code,
- model_type=str(exc.model_type),
- model_choice=str(exc.model_choice),
- exit_code=2,
- )
-
except PipeOperatorModelAvailabilityError as exc:
agent_error(
str(exc),
@@ -125,12 +112,6 @@ def validate_pipe_cmd(
exit_code=2,
)
- except DryRunError as exc:
- # A dry-run failure is a produced NEGATIVE VERDICT (a pipe is invalid) — exit 1, NOT the
- # catch-all's no-verdict 2. `validate --all` sweeps via validate_current_library, which
- # raises DryRunError directly (not wrapped in ValidateBundleError as the bundle path is).
- agent_error(str(exc), error_type="DryRunError", cause=exc, is_valid=False, exit_code=1)
-
except typer.Exit:
# The runnability gate raises typer.Exit(1) after emitting the success envelope; let it
# propagate (exit code) rather than be reshaped into an agent_error by the broad handler below.
@@ -195,7 +176,7 @@ def validate_pipe_cmd(
except ValidateBundleError as exc:
# Invalid verdict (see the --all arm): structured failure envelope; validation_errors[] is the
- # shared builder's output (a residual dry-run failure rides one dry_run item).
+ # shared builder's output (a failing dry run rides one located dry_run item per failing pipe).
agent_error(
exc.message,
error_type="ValidateBundleError",
@@ -204,17 +185,6 @@ def validate_pipe_cmd(
validation_errors=extract_validation_errors(exc),
)
- except PipeOperatorModelChoiceError as exc:
- agent_error(
- exc.message,
- error_type="PipeOperatorModelChoiceError",
- cause=exc,
- pipe_code=exc.pipe_code,
- model_type=str(exc.model_type),
- model_choice=str(exc.model_choice),
- exit_code=2,
- )
-
except PipeOperatorModelAvailabilityError as exc:
availability_extra: dict[str, Any] = {
"pipe_code": exc.pipe_code,
@@ -226,12 +196,6 @@ def validate_pipe_cmd(
availability_extra["pipe_stack"] = exc.pipe_stack
agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra, exit_code=2)
- except DryRunError as exc:
- # A dry-run failure is a produced NEGATIVE VERDICT (the pipe is invalid) — exit 1, NOT the
- # catch-all's no-verdict 2. validate_pipe_core sweeps via validate_pipes, which raises
- # DryRunError directly (not wrapped in ValidateBundleError as the bundle path is).
- agent_error(str(exc), error_type="DryRunError", cause=exc, is_valid=False, exit_code=1)
-
except typer.Exit:
raise
diff --git a/pipelex/cli/commands/fix/_diff_sandbox.py b/pipelex/cli/commands/fix/_diff_sandbox.py
index 5ce264f5b..d39c0df92 100644
--- a/pipelex/cli/commands/fix/_diff_sandbox.py
+++ b/pipelex/cli/commands/fix/_diff_sandbox.py
@@ -67,7 +67,10 @@ class PreviewSandbox(NamedTuple):
def to_original(self, path_str: str) -> str:
"""Map a sandbox file path back to the original it mirrors.
- Paths outside the sandbox (ambient-resolved files) pass through resolved-as-is.
+ Absolute paths outside the sandbox (ambient-resolved files) pass through resolved-as-is. Every path the
+ sandbox mirrors is absolute, so a relative name outside it passes through exactly as given: it is either
+ a file relative to the working directory, which the preview shares, or not a path at all, such as a
+ dependency's bundle named by its package's address, which resolving would turn into a made-up file.
"""
resolved = Path(path_str).resolve()
entry_copy, entry_original = self.entry_mapping
@@ -76,6 +79,8 @@ class PreviewSandbox(NamedTuple):
for copy_root, original_root in self.dir_mappings:
if resolved.is_relative_to(copy_root):
return str(original_root / resolved.relative_to(copy_root))
+ if not Path(path_str).is_absolute():
+ return path_str
return str(resolved)
diff --git a/pipelex/cli/commands/fix/_fix_core.py b/pipelex/cli/commands/fix/_fix_core.py
index 8f6a187a0..dac7056fc 100644
--- a/pipelex/cli/commands/fix/_fix_core.py
+++ b/pipelex/cli/commands/fix/_fix_core.py
@@ -124,10 +124,10 @@ def _render_fix_result(*, console: Console, result: FixBundleResult, bundle_path
console.print("[bold cyan]Remaining errors:[/bold cyan]\n")
display_validation_error_items(console=console, items=result.remaining_errors)
- # A remaining error can still carry a 💡 suggested-fix line — dropped by --select/--ignore,
+ # A remaining error can still carry a safe 💡 suggested-fix line — dropped by --select/--ignore,
# left outside the write scope, or unconverged when the loop bailed. Claiming "no safe fix"
# there contradicts the line just printed, so only say it when nothing fixable remains.
- if any(item.suggested_fix is not None for item in result.remaining_errors):
+ if any(item.suggested_fix is not None and item.suggested_fix.safety.is_safe for item in result.remaining_errors):
console.print(
"[bold green]💡 Tip:[/bold green] Some remaining errors above still show a suggested fix that was not applied — "
"they were skipped by --select/--ignore, fell outside the write scope, or the loop stopped early (see the reason above). "
diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.py
index 21658e84a..5d6542661 100644
--- a/pipelex/cli/commands/run/_run_core.py
+++ b/pipelex/cli/commands/run/_run_core.py
@@ -15,8 +15,10 @@ from pipelex.cli.commands.run._inputs_file_loader import load_inputs_dict_from_p
from pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_paths
from pipelex.cli.error_handlers import (
ErrorContext,
+ handle_dedicated_failure_panel,
handle_model_availability_error,
handle_model_choice_error,
+ handle_validate_bundle_error,
print_traceback_if_requested,
)
from pipelex.config import get_config
@@ -28,13 +30,13 @@ from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_viewer import render_stuff_viewer
from pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dir
from pipelex.interpreter_hub import clear_current_library, get_concept_library, get_library_manager
-from pipelex.mthds_parsing.exceptions import MthdsParserError
from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipelex import Pipelex
-from pipelex.pipeline.exceptions import PipelineExecutionError
+from pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleError
from pipelex.pipeline.execution_seams import acquire_library
from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
from pipelex.reporting.cost_report_renderer import render_cost_report_for_output
from pipelex.runtime_hub import get_console, get_telemetry_manager
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -143,6 +145,11 @@ async def _execute_run(
typer.secho(f"Failed to --save-csv: {exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from exc
+ # An invalid bundle is refused with the grouped panel `validate` prints, whichever step refuses it:
+ # the parse below, or the load at the start of the run.
+ bundle_file_path = Path(bundle_path) if bundle_path else None
+ library_dir_paths = [Path(one_library_dir) for one_library_dir in library_dir] if library_dir else None
+
mthds_content: str | None = None
if bundle_path:
try:
@@ -150,7 +157,8 @@ async def _execute_run(
# Use lightweight parsing to extract main_pipe without full validation
# Full validation happens later during execute
if not pipe_code:
- bundle_blueprint = MthdsParser.make_pipelex_bundle_blueprint(mthds_content=mthds_content)
+ with translate_to_validate_bundle_error():
+ bundle_blueprint = MthdsParser.make_pipelex_bundle_blueprint(mthds_content=mthds_content, mthds_source=bundle_path)
main_pipe_code = bundle_blueprint.main_pipe
if not main_pipe_code:
msg = (
@@ -164,10 +172,8 @@ async def _execute_run(
print_traceback_if_requested(console=get_console())
typer.secho(f"Failed to load bundle '{bundle_path}': {exc}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from exc
- except MthdsParserError as exc:
- print_traceback_if_requested(console=get_console())
- typer.secho(f"Failed to parse bundle '{bundle_path}': {exc}", fg=typer.colors.RED, err=True)
- raise typer.Exit(1) from exc
+ except ValidateBundleError as exc:
+ handle_validate_bundle_error(exc, bundle_path=bundle_file_path, library_dirs=library_dir_paths)
elif not pipe_code:
typer.secho("Failed to run: no pipe code specified", fg=typer.colors.RED, err=True)
raise typer.Exit(1)
@@ -233,6 +239,8 @@ async def _execute_run(
execution_config=execution_config,
library_dirs=library_dir,
inputs_base_dir=inputs_base_dir,
+ # The directories a CLI loads are the caller's own: a refusal there is their invalid bundle.
+ library_dirs_are_callers=True,
)
response = await runner.execute(
pipe_code=pipe_code,
@@ -241,9 +249,17 @@ async def _execute_run(
dynamic_output_concept_ref=dynamic_output_concept_ref,
)
pipe_output = response.pipe_output
+ except ValidateBundleError as exc:
+ # The run refused the bundle while loading it, before any pipe ran.
+ handle_validate_bundle_error(exc, bundle_path=bundle_file_path, library_dirs=library_dir_paths)
except PipelineExecutionError as exc:
+ # A failure whose cause has a dedicated panel (a model that is not available, a model choice
+ # that cannot be read) renders it: the panel names the pipe that failed, the model and the stack.
+ handle_dedicated_failure_panel(error=exc, context=ErrorContext.PIPE_RUN)
print_traceback_if_requested(console=get_console())
- typer.secho(f"Failed to execute pipeline '{exc.pipe_code}': {exc}", fg=typer.colors.RED, err=True)
+ # The message names the pipe that failed and its path; the pipeline named first is the entry pipe.
+ entry_pipe_code = exc.pipe_stack[0] if exc.pipe_stack else exc.pipe_code
+ typer.secho(f"Failed to execute pipeline '{entry_pipe_code}': {exc.message}", fg=typer.colors.RED, err=True)
raise typer.Exit(1) from exc
except PipelexError as exc:
print_traceback_if_requested(console=get_console())
diff --git a/pipelex/cli/commands/validate/_validate_core.py b/pipelex/cli/commands/validate/_validate_core.py
index 3294c9c71..237c57bd8 100644
--- a/pipelex/cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/commands/validate/_validate_core.py
@@ -11,10 +11,8 @@ from pipelex.cli.cli_factory import make_pipelex_for_cli
from pipelex.cli.error_handlers import (
ErrorContext,
handle_model_availability_error,
- handle_model_choice_error,
handle_validate_bundle_error,
)
-from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.interpreter_hub import (
get_library_manager,
get_pipe_library,
@@ -33,6 +31,7 @@ from pipelex.pipeline.bundle_validator import BundleValidator
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.execution_seams import load_libraries_and_activate
from pipelex.pipeline.validate_bundle import build_pending_signatures, validate_bundle
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
from pipelex.runtime_hub import get_console, get_telemetry_manager
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
@@ -80,7 +79,10 @@ def do_validate_all_libraries_and_dry_run(*, library_dirs: list[Path] | None = N
# Single public composer for the open/set/load ceremony — leaves the library loaded and
# current for the sweep below, owning the standard 3-tier dir resolution and load-failure
# teardown. No teardown on success here: the caller (validate_pipe_cmd) owns Pipelex teardown.
- load_libraries_and_activate(library_dirs)
+ # The shared bundle-loading cascade turns a refusal of the libraries into the invalid
+ # verdict (exit 1) rendered below, exactly as `validate bundle` does.
+ with translate_to_validate_bundle_error():
+ load_libraries_and_activate(library_dirs)
# The pipe list is needed only to render the "Validating N" line; validate_current_library
# re-derives its own sweep candidates from the current library (validate_pipes excludes
@@ -92,8 +94,10 @@ def do_validate_all_libraries_and_dry_run(*, library_dirs: list[Path] | None = N
typer.echo(f"Validating {count_with_noun(count=len(pipes), singular='pipe')} from: {dirs_str}")
# validate_current_library owns the static wiring pass and the single PIPE_DRY_RUN telemetry
- # event — sweeping the library we just loaded, without teardown.
- asyncio.run(BundleValidator().validate_current_library(allow_signatures=allow_signatures))
+ # event — sweeping the library we just loaded, without teardown. A pipe whose dry run fails
+ # raises DryRunError, which the cascade turns into the same invalid verdict.
+ with translate_to_validate_bundle_error():
+ asyncio.run(BundleValidator().validate_current_library(allow_signatures=allow_signatures))
# Advisory lints over the whole loaded library (the optionality lint's cross-flow
# aggregation needs every flow) — printed even when the signature gate below exits
@@ -120,10 +124,12 @@ def do_validate_all_libraries_and_dry_run(*, library_dirs: list[Path] | None = N
typer.echo(
f"Setup sequence passed OK, config and pipelines are validated.{_format_signatures_summary_suffix(signature_count=signature_count)}"
)
+ except ValidateBundleError as bundle_error:
+ # A produced negative verdict (exit 1): a refusal of the libraries while loading them, an unknown
+ # model among them, or a pipe whose dry run fails — rendered like any other invalid bundle.
+ handle_validate_bundle_error(bundle_error, library_dirs=library_dirs, allow_signatures=allow_signatures)
except PipeOperatorModelAvailabilityError as exc:
handle_model_availability_error(exc, context=ErrorContext.VALIDATION, exit_code=2)
- except PipeOperatorModelChoiceError as exc:
- handle_model_choice_error(exc, context=ErrorContext.VALIDATION, exit_code=2)
async def _validate_pipe_or_bundle(
@@ -177,19 +183,28 @@ async def _validate_pipe_or_bundle(
set_current_library(library_id=library_id)
effective_dirs, _ = resolve_library_dirs(library_dirs)
- if effective_dirs:
- library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
+ try:
+ # The load and the dry run go through the shared bundle-loading cascade, so a refusal of the
+ # libraries and a pipe whose dry run fails are invalid verdicts (exit 1) rendered like any
+ # other invalid bundle. The entry-pipe lookup between them stays outside it: a code that names
+ # no pipe, or several, is an unresolvable target — no verdict, handled by execute_validate.
+ if effective_dirs:
+ with translate_to_validate_bundle_error():
+ library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
- pipe = get_required_entry_pipe(pipe_code=pipe_code)
- typer.echo(f"Validating pipe '{pipe_code}'...")
- # Signatures are never an error (D-B): a single-pipe validation reaching a PipeSignature
- # dry-runs trivially (the placeholder mints a mock). validate pipe makes no library-wide
- # runnability claim — pending_signatures is a bundle-surface fact — so there is no gate here.
- await BundleValidator().validate_pipes(
- pipes=[pipe],
- library_id=library_id,
- allow_signatures=allow_signatures,
- )
+ pipe = get_required_entry_pipe(pipe_code=pipe_code)
+ typer.echo(f"Validating pipe '{pipe_code}'...")
+ # Signatures are never an error (D-B): a single-pipe validation reaching a PipeSignature
+ # dry-runs trivially (the placeholder mints a mock). validate pipe makes no library-wide
+ # runnability claim — pending_signatures is a bundle-surface fact — so there is no gate here.
+ with translate_to_validate_bundle_error():
+ await BundleValidator().validate_pipes(
+ pipes=[pipe],
+ library_id=library_id,
+ allow_signatures=allow_signatures,
+ )
+ except ValidateBundleError as bundle_error:
+ handle_validate_bundle_error(bundle_error, library_dirs=library_dirs, allow_signatures=allow_signatures)
signature_count = len(collect_signature_refs(pipe=pipe))
typer.secho(
f"Successfully validated pipe '{pipe_code}'{_format_signatures_summary_suffix(signature_count=signature_count)}",
@@ -258,8 +273,6 @@ def execute_validate(
err=True,
)
raise typer.Exit(2) from exc
- except PipeOperatorModelChoiceError as exc:
- handle_model_choice_error(exc, context=ErrorContext.VALIDATION, exit_code=2)
except PipeOperatorModelAvailabilityError as exc:
handle_model_availability_error(exc, context=ErrorContext.VALIDATION, exit_code=2)
finally:
diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.py
index 41f33d7ea..4b97a9c89 100644
--- a/pipelex/cli/error_handlers.py
+++ b/pipelex/cli/error_handlers.py
@@ -9,12 +9,12 @@ from rich.console import Console
from rich.markup import escape
from rich.traceback import Traceback
-from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem, error_domain_is_input, iter_cause_chain
from pipelex.cogt.exceptions import GatewayUnknownModelError, ModelDeckPresetValidatonError
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipeline.exceptions import ValidateBundleError
-from pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes
+from pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes, suggested_fix_label, validation_item_title
from pipelex.runtime_hub import get_console
from pipelex.system.pipelex_service.exceptions import (
GatewayApiKeyMissingError,
@@ -124,8 +124,9 @@ def handle_model_choice_error(exc: PipeOperatorModelChoiceError, *, context: Err
Args:
exc: The model choice error exception
context: Context for the error message
- exit_code: Process exit code. The validate surface passes 2 (a no-verdict
- setup/config error per its 0/1/2 policy); other contexts keep the default 1.
+ exit_code: Process exit code; the default is 1. The validate surface never reaches
+ this handler: an unknown model is an invalid verdict there, rendered by
+ :func:`handle_validate_bundle_error`.
"""
console = get_console()
print_traceback_if_requested(console=console)
@@ -157,8 +158,9 @@ def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *,
Args:
exc: The model availability error exception
context: Context for the error message
- exit_code: Process exit code. The validate surface passes 2 (a no-verdict
- setup/config error per its 0/1/2 policy); other contexts keep the default 1.
+ exit_code: Process exit code. The validate surface passes 2: a model the deck defines
+ but no enabled backend serves is a setup fault of this machine, so no verdict, unlike
+ an unknown model, which is an invalid verdict there. Other contexts keep the default 1.
"""
console = get_console()
print_traceback_if_requested(console=console)
@@ -173,9 +175,27 @@ def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *,
if len(exc.pipe_stack) > 1:
stack_str = " [dim]→[/dim] ".join([f"[yellow]{escape(stacked_pipe)}[/yellow]" for stacked_pipe in exc.pipe_stack])
fields.append(("Pipe Stack", stack_str))
- tip = report.user_action_detail() or (
- f"Check your model configuration in .pipelex/inference/ or specify a different model in the '{exc.pipe_code}' pipe."
+ # The local-deck remedy is given here and nowhere else: the model error's own message reaches
+ # every surface, hosted ones included, whose readers have no local deck to refresh.
+ local_deck_remedy = (
+ "Your local model deck may be out of date: new aliases and presets are added to Pipelex over time, and existing "
+ "'.pipelex/inference/deck/*.toml' files are not refreshed automatically. To pick up the latest definitions, delete "
+ "your local deck files under '.pipelex/inference/deck/' (or the whole '.pipelex/inference/' directory) and run "
+ "'pipelex init inference' to regenerate them.\n"
+ "If that does not resolve it, make sure the handle is defined in one of '.pipelex/inference/deck/*.toml', that the "
+ "backend it routes to (see '.pipelex/inference/routing_profiles.toml') is enabled in '.pipelex/inference/backends.toml', "
+ "and that you have the necessary credentials"
)
+ user_action_detail = report.user_action_detail()
+ tip: str
+ if user_action_detail is None:
+ tip = f"{local_deck_remedy}, or specify a different model in the '{exc.pipe_code}' pipe."
+ elif error_domain_is_input(report.error_domain):
+ # The method named a model no entry of the deck names, and the lookup's next step is to
+ # change it. A local deck can also be what lacks that model, so the local remedy follows.
+ tip = f"{user_action_detail}\n{local_deck_remedy}."
+ else:
+ tip = user_action_detail
display_error_panel(
console=console,
title=f"{context} failed because a model wasn't available",
@@ -190,6 +210,21 @@ def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *,
raise typer.Exit(exit_code) from exc
+def handle_dedicated_failure_panel(*, error: BaseException, context: ErrorContext) -> None:
+ """Render the dedicated panel of the first error on `error`'s cause chain that has one, and exit.
+
+ A run failure reaches the CLI as a `PipelineExecutionError` around the located failure, so a
+ handler written for the model errors never matches it directly: this walks the cause chain for
+ them, and the panel then names the pipe that failed, the model and the stack. Returns without
+ printing anything when no error on the chain has a dedicated panel.
+ """
+ for node in iter_cause_chain(error):
+ if isinstance(node, PipeOperatorModelAvailabilityError):
+ handle_model_availability_error(node, context=context)
+ if isinstance(node, PipeOperatorModelChoiceError):
+ handle_model_choice_error(node, context=context)
+
+
def handle_model_deck_preset_error(exc: ModelDeckPresetValidatonError, *, context: ErrorContext) -> NoReturn:
"""Handle and display ModelDeckPresetValidatonError with formatted output.
@@ -254,13 +289,12 @@ def _validation_category_header(category: ValidationErrorCategory) -> str:
case ValidationErrorCategory.PIPE_VALIDATION:
return "Pipe Validation Errors:"
case ValidationErrorCategory.DRY_RUN:
- return "Dry Run Error:"
+ return "Dry Run Errors:"
def _display_validation_error_item(*, console: Console, item: ValidationErrorItem, error_index: int) -> None:
"""Render one structured validation-error item: title, identity fields, message, fix, locators."""
- error_type_display = item.error_type.replace("_", " ").title() if item.error_type else "Validation Error"
- console.print(f"[bold yellow]{error_index}. {error_type_display}[/bold yellow]")
+ console.print(f"[bold yellow]{error_index}. {escape(validation_item_title(item=item))}[/bold yellow]")
if item.pipe_code:
console.print(f" [cyan]Pipe:[/cyan] [yellow]{escape(item.pipe_code)}[/yellow]")
@@ -284,7 +318,11 @@ def _display_validation_error_item(*, console: Console, item: ValidationErrorIte
console.print(f" [cyan]→[/cyan] {escape(item.message)}")
if item.suggested_fix is not None:
- console.print(f" [green]💡 Suggested fix:[/green] {escape(item.suggested_fix.description)}")
+ # The words carry the safety, so the colour only echoes them: an unsafe fix is yellow because
+ # it needs the reader's confirmation, a safe one green because `pipelex fix bundle` applies it.
+ fix_style = "green" if item.suggested_fix.safety.is_safe else "yellow"
+ fix_label = escape(suggested_fix_label(fix=item.suggested_fix))
+ console.print(f" [{fix_style}]💡 {fix_label}:[/{fix_style}] {escape(item.suggested_fix.description)}")
if item.field_path:
console.print(f" [dim]└─ Path: {escape(item.field_path)}[/dim]")
@@ -311,15 +349,10 @@ def display_validation_error_items(*, console: Console, items: list[ValidationEr
if not category_items:
continue
console.print(f"[bold cyan]{_validation_category_header(category)}[/bold cyan]\n")
- match category:
- case ValidationErrorCategory.DRY_RUN:
- # The dry-run residual is a single graph-level message with no identity fields —
- # keep its historical plain rendering rather than a numbered item.
- for item in category_items:
- console.print(f"[yellow]{escape(item.message)}[/yellow]\n")
- case ValidationErrorCategory.BLUEPRINT_VALIDATION | ValidationErrorCategory.PIPE_FACTORY | ValidationErrorCategory.PIPE_VALIDATION:
- for error_index, item in enumerate(category_items, 1):
- _display_validation_error_item(console=console, item=item, error_index=error_index)
+ # Every category, dry run included, renders numbered items: a dry-run item is located on its
+ # failing pipe like any other, so it names the pipe, the domain and the source.
+ for error_index, item in enumerate(category_items, 1):
+ _display_validation_error_item(console=console, item=item, error_index=error_index)
def handle_validate_bundle_error(
@@ -351,13 +384,6 @@ def handle_validate_bundle_error(
display_validation_error_items(console=console, items=items)
- # The shared items builder projects the dry-run channel only when it is the sole failure
- # channel (the wire's structured-info invariant); the human surface keeps printing it
- # alongside categorized errors so no diagnostic is lost.
- if exc.dry_run_error_message and not any(item.category.is_dry_run for item in items):
- console.print("[bold cyan]Dry Run Error:[/bold cyan]\n")
- console.print(f"[yellow]{escape(exc.dry_run_error_message)}[/yellow]\n")
-
# A hint needs an action behind it: when fixes exist, the actionable footer replaces the
# generic tip (two stacked 💡 tips would be noise).
fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs) if bundle_path is not None else 0
diff --git a/pipelex/cogt/exceptions.py b/pipelex/cogt/exceptions.py
index 9505560d0..468e2ec44 100644
--- a/pipelex/cogt/exceptions.py
+++ b/pipelex/cogt/exceptions.py
@@ -195,7 +195,11 @@ class SdkTypeError(CogtError):
class ModelChoiceNotFoundError(CogtError):
- """Error raised when a model choice cannot be found in the model deck.
+ """Raised when a model reference names a handle, alias, preset or waterfall the model deck does not define:
+ by the deck check a pipe runs when it is built, and by the deck when a run resolves a reference. When a
+ pipe is built, the pipe operator raises it again as a ``PipeOperatorModelChoiceError`` located on the pipe
+ and the field, so a bundle naming an unknown model is an invalid validation verdict (error type
+ ``unknown_model``), never a failure of the validator.
Includes available options and migration hints in error message.
"""
diff --git a/pipelex/cogt/model_backends/model_type.py b/pipelex/cogt/model_backends/model_type.py
index c75a84b5a..299e42077 100644
--- a/pipelex/cogt/model_backends/model_type.py
+++ b/pipelex/cogt/model_backends/model_type.py
@@ -6,3 +6,16 @@ class ModelType(StrEnum):
TEXT_EXTRACTOR = "text_extractor"
IMG_GEN = "img_gen"
SEARCH = "search"
+
+ @property
+ def indefinite_description(self) -> str:
+ """The kind of model this type is, in prose with its indefinite article, for advice such as a next step."""
+ match self:
+ case ModelType.LLM:
+ return "an LLM"
+ case ModelType.TEXT_EXTRACTOR:
+ return "a text-extraction model"
+ case ModelType.IMG_GEN:
+ return "an image-generation model"
+ case ModelType.SEARCH:
+ return "a search model"
diff --git a/pipelex/cogt/models/model_deck.py b/pipelex/cogt/models/model_deck.py
index 17b16bf69..9da4fe308 100644
--- a/pipelex/cogt/models/model_deck.py
+++ b/pipelex/cogt/models/model_deck.py
@@ -17,6 +17,7 @@ from pipelex.cogt.exceptions import (
from pipelex.cogt.extract.extract_setting import ExtractModelChoice, ExtractSetting
from pipelex.cogt.img_gen.img_gen_job_components import Quality
from pipelex.cogt.img_gen.img_gen_setting import ImgGenModelChoice, ImgGenSetting
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.cogt.llm.llm_setting import (
LLMModelChoice,
LLMSetting,
@@ -832,23 +833,106 @@ class ModelDeck(ConfigModel):
aliases, waterfalls = self.get_aliases_and_waterfalls_for_type(model_type)
return model_handle in self.inference_models or model_handle in aliases or model_handle in waterfalls
+ def _is_deck_model_reference(self, *, model_handle: str, model_type: ModelType) -> bool:
+ """Whether this deck defines the model reference `model_handle` or names it in one of its own entries.
+
+ Every setting the deck hands out names a reference the deck defines (a model it serves, an
+ alias, a waterfall) or one its own entries name (a preset's model, an alias's target, a
+ waterfall's fallback, a default or override written as a setting). A reference that is
+ neither can only have reached a model lookup from outside the deck, from a model setting
+ written inline in the method being run.
+ """
+ aliases, waterfalls = self.get_aliases_and_waterfalls_for_type(model_type)
+ ref: ModelReference | None
+ try:
+ ref = ModelReference.parse(model_handle)
+ except ModelReferenceParseError:
+ # A value no reference parses from can still be the deck's own: a default or an
+ # override written as a setting table is not parsed when the deck loads.
+ ref = None
+ if ref is not None:
+ match ref.kind:
+ case ModelReferenceKind.HANDLE:
+ # A model served as another type is not defined for this lookup, which refuses it.
+ served_model = self.inference_models.get(ref.name)
+ if served_model is not None and served_model.model_type != model_type:
+ served_model = None
+ if served_model is not None or ref.name in aliases or ref.name in waterfalls:
+ return True
+ case ModelReferenceKind.ALIAS:
+ if ref.name in aliases:
+ return True
+ case ModelReferenceKind.WATERFALL:
+ if ref.name in waterfalls:
+ return True
+ case ModelReferenceKind.PRESET:
+ # A preset is never a model a lookup can serve, whether or not the deck defines it.
+ pass
+
+ named_references: set[str] = set(aliases.values())
+ for fallback_list in waterfalls.values():
+ named_references.update(fallback_list)
+ deck_settings: list[LLMSetting | ExtractSetting | ImgGenSetting | SearchSetting]
+ deck_choices: list[LLMModelChoice | ExtractModelChoice | ImgGenModelChoice | SearchModelChoice | None]
+ match model_type:
+ case ModelType.LLM:
+ deck_settings = list(self.llm_presets.values())
+ deck_choices = [
+ self.llm_choice_defaults.for_text,
+ self.llm_choice_defaults.for_object,
+ self.llm_choice_overrides.for_text,
+ self.llm_choice_overrides.for_object,
+ ]
+ case ModelType.TEXT_EXTRACTOR:
+ deck_settings = list(self.extract_presets.values())
+ deck_choices = [self.extract_choice_default]
+ case ModelType.IMG_GEN:
+ deck_settings = list(self.img_gen_presets.values())
+ deck_choices = [self.img_gen_choice_default]
+ case ModelType.SEARCH:
+ deck_settings = list(self.search_presets.values())
+ deck_choices = [self.search_choice_default]
+ named_references.update(deck_setting.model for deck_setting in deck_settings)
+ for deck_choice in deck_choices:
+ if isinstance(deck_choice, (LLMSetting, ExtractSetting, ImgGenSetting, SearchSetting)):
+ named_references.add(deck_choice.model)
+ elif isinstance(deck_choice, ModelReference):
+ match deck_choice.kind:
+ case ModelReferenceKind.HANDLE:
+ # A default or override written as a handle reaches the lookup by its name,
+ # whatever prefix spells it.
+ named_references.add(deck_choice.name)
+ case ModelReferenceKind.ALIAS | ModelReferenceKind.WATERFALL | ModelReferenceKind.PRESET:
+ # These reach the lookup as a name the deck defines or names above: an
+ # alias's target, a waterfall's own name or members, a preset's model.
+ pass
+ return model_handle in named_references
+
def get_required_inference_model(self, model_handle: str, *, model_type: ModelType) -> InferenceModelSpec:
inference_model = self.get_optional_inference_model(model_handle=model_handle, model_type=model_type)
if inference_model is None:
- msg = (
- f"Model handle '{model_handle}' was not found in the model deck.\n"
- "The most likely cause is that your local model deck is out of date: new aliases and presets are added to Pipelex "
- "over time and existing '.pipelex/inference/deck/*.toml' files are not automatically refreshed (yet). "
- "To pick up the latest definitions, delete your local deck files under '.pipelex/inference/deck/' "
- "(or the whole '.pipelex/inference/' directory) and run 'pipelex init inference' to regenerate them.\n"
- "If that doesn't resolve it: make sure the handle is defined in one of '.pipelex/inference/deck/*.toml', "
- "that the backend it routes to (see '.pipelex/inference/routing_profiles.toml') is enabled in "
- "'.pipelex/inference/backends.toml', and that you have the necessary credentials. "
- "Learn more about the inference backend system in the Pipelex documentation: "
- f"{URLs.backend_provider_docs}"
- )
-
- raise ModelNotFoundError(message=msg, model_handle=model_handle)
+ # The message states the fact and nothing else: it reaches every surface a run failure
+ # reaches, a hosted run's stored error included, whose reader has no local deck. The
+ # remedy for a stale local deck is the local CLI's to give, in its model panel.
+ msg = f"Model handle '{model_handle}' was not found in the model deck."
+ model_not_found_error = ModelNotFoundError(message=msg, model_handle=model_handle)
+ if not self._is_deck_model_reference(model_handle=model_handle, model_type=model_type):
+ # The deck neither defines this reference for this type nor names it anywhere, so the
+ # method being run named it, in an inline model setting the load-time check does not
+ # look into, or as a model the deck serves as another type, which that check does not
+ # tell apart: the caller's fault, which that check reports as
+ # `ModelChoiceNotFoundError` for a reference it sees. The message and the next step
+ # name nothing but the caller's own reference, as the method wrote it, and the type
+ # its pipe asked for, never the type the deck serves it as. A reference the deck
+ # itself names but cannot serve (a preset or an alias target on a backend that is not
+ # enabled) stays the deployment's fault, and stays redacted, with no next step.
+ model_not_found_error.as_caller_fault(
+ user_action=UserAction(
+ kind=UserActionKind.CHANGE_MODEL,
+ detail=f"Change the model '{model_handle}' to {model_type.indefinite_description} the model deck serves.",
+ )
+ )
+ raise model_not_found_error
if model_handle not in self.inference_models:
log.verbose(f"Model handle '{model_handle}' is an alias which resolves to '{inference_model.name}'")
return inference_model
diff --git a/pipelex/core/exceptions.py b/pipelex/core/exceptions.py
index 2743f8703..ddbaae9af 100644
--- a/pipelex/core/exceptions.py
+++ b/pipelex/core/exceptions.py
@@ -46,6 +46,19 @@ class PipelexBundleBlueprintValidationErrorData(BaseModel):
message: str
variable_names: list[str] | None = None
+ # The bundle-root dot path of the failing field, set on an error the categorizer does not know,
+ # so the item keeps the location its pydantic ``loc`` named (``pipe.<code>.<field>``).
+ field_path: str | None = None
+
+ # The 1-based position where a TOML syntax error was found, in the file ``source`` names or in
+ # the submitted content when there is none.
+ line: int | None = None
+ column: int | None = None
+
+ # The bare codes of the concepts the validated bundle declares in ``domain_code``, set on an
+ # ``unresolved_concept`` error so the author sees what the reference could have named.
+ declared_concepts: list[str] | None = None
+
# The namespace-stripped bare code for a strippable same-domain over-qualified pipe code
# (``strip-namespace`` enrichment). Present only when the fix planner can act; ``pipe_code``
# discriminates the two raise sites — set to the offending dotted code for a declaration-key
@@ -77,8 +90,12 @@ class PipesAndConceptValidationErrorData(BaseModel):
field_name: str | None = Field(default=None, description="Specific field that failed")
# === Error Classification ===
- error_type: PipeValidationErrorType = Field(
- description="Type of pipe/concept validation error",
+ # ``None`` for a refusal no closed code fits: a load-time refusal located on a pipe but carrying no
+ # code of its own (the general arm of the bundle-loading cascade), exactly as the parse-level
+ # residual carries none rather than a code that would claim to know which fault occurred.
+ error_type: PipeValidationErrorType | None = Field(
+ default=None,
+ description="Type of pipe/concept validation error, or None when no closed code fits the refusal",
)
# === Error Details ===
@@ -88,6 +105,12 @@ class PipesAndConceptValidationErrorData(BaseModel):
# === Variable names for input/output errors ===
variable_names: list[str] | None = Field(default=None, description="Variable names (for input errors)")
+ # === Declared concepts (for unresolved_concept errors) ===
+ declared_concepts: list[str] | None = Field(
+ default=None,
+ description="The bare codes of the concepts the validated bundle declares in the domain the reference was looked up in",
+ )
+
# === Enriched expected value (for output-mismatch errors) ===
expected_output_ref: str | None = Field(
default=None,
@@ -105,3 +128,27 @@ class PipesAndConceptValidationErrorData(BaseModel):
description="The pipe's currently declared inputs mapping, rendered like expected_inputs, "
"so a fix planner can diff the two without file access",
)
+
+ # === Unknown-model locators (for unknown_model errors) ===
+ model_reference: str | None = Field(default=None, description="The model reference exactly as the author wrote it")
+ model_type: str | None = Field(default=None, description="The model type the field takes (llm, text_extractor, img_gen, search)")
+ suggestions: list[str] | None = Field(
+ default=None,
+ description="The deck's close matches of the same kind, each spelled as a reference the field accepts",
+ )
+
+
+class DryRunFailureErrorData(BaseModel):
+ """Structured error data for one pipe whose dry run failed.
+
+ The dry-run sweep records one per failing pipe, located at the innermost pipe that failed: a
+ failure that makes an enclosing controller fail for the same cause is kept once, at the pipe
+ where it happened. ``message`` is built from that pipe's own failure under the disclosure rule
+ for an item built from a raised error: the failure's own message when it is caller-facing, its
+ title otherwise, because the verdict that carries it is caller-facing as a whole.
+ """
+
+ pipe_code: str | None = Field(default=None, description="Bare code of the pipe whose dry run failed")
+ domain_code: str | None = Field(default=None, description="Domain of the pipe whose dry run failed")
+ source: str | None = Field(default=None, description="Source file of the pipe, when the library knows it")
+ message: str = Field(description="The pipe's own failure, as the disclosure rule allows it")
diff --git a/pipelex/core/memory/exceptions.py b/pipelex/core/memory/exceptions.py
index 18352aaf6..41399939a 100644
--- a/pipelex/core/memory/exceptions.py
+++ b/pipelex/core/memory/exceptions.py
@@ -28,6 +28,9 @@ class WorkingMemoryStuffAttributeNotFoundError(WorkingMemoryVariableError):
class WorkingMemoryStuffNotFoundError(WorkingMemoryVariableError):
+ # Not classified as the caller's fault: a step that names a variable nothing produces, a batch
+ # over one included, is refused when the bundle loads, so a miss at run time is the runtime's own
+ # bookkeeping going wrong, not a mistake in the caller's method.
def __init__(self, message: str, variable_name: str, pipe_code: str | None = None, concept_code: str | None = None):
super().__init__(message, variable_name)
self.pipe_code = pipe_code
diff --git a/pipelex/core/pipes/exceptions.py b/pipelex/core/pipes/exceptions.py
index 77121f70b..4d459cb64 100644
--- a/pipelex/core/pipes/exceptions.py
+++ b/pipelex/core/pipes/exceptions.py
@@ -1,11 +1,6 @@
-from typing_extensions import override
-
-from pipelex.base_exceptions import PipelexError
-from pipelex.cogt.extract.extract_setting import ExtractModelChoice
-from pipelex.cogt.img_gen.img_gen_setting import ImgGenModelChoice
-from pipelex.cogt.llm.llm_setting import LLMModelChoice
+from pipelex.base_exceptions import ErrorDomain, PipelexError
+from pipelex.cogt.exceptions import ModelChoiceNotFoundError
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.cogt.models.model_reference import ModelReference
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.validation_error_types import PipeFactoryErrorType, PipeValidationErrorType
@@ -61,41 +56,117 @@ class PipeRunError(PipelexError):
class PipeOperatorModelChoiceError(PipelexError):
+ """Raised by a pipe operator (``PipeLLM``, ``PipeStructure``, ``PipeImgGen``, ``PipeExtract``, ``PipeSearch``)
+ when it is built from its blueprint and a model field names a model the model deck does not define.
+ Bundle validation reports it as an invalid verdict whose item has the error type ``unknown_model``,
+ and a run, which loads its bundle before any pipe runs, refuses the bundle with that same verdict.
+
+ The pipe operator raises it from the ``ModelChoiceNotFoundError`` its deck check raised, located on
+ the pipe (its code, type and domain) and on the field (``model``, or ``model_to_structure`` on a
+ ``PipeLLM``), and the library load adds the file the pipe is declared in. Every pipe type that names
+ a model raises this same error, so every one of them gives the same verdict item.
+
+ The message names the pipe and the field, then keeps the deck check's sentence and its suggestions,
+ so it is caller-facing copy: it names only the caller's own model reference and the deck's public
+ handles, and it must reach a hosted caller under STRICT disclosure.
+ """
+
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
+
def __init__(
self,
message: str,
+ *,
pipe_type: str,
pipe_code: str,
+ domain_code: str,
+ field_name: str,
model_type: ModelType,
- model_choice: LLMModelChoice | ExtractModelChoice | ImgGenModelChoice,
+ model_choice: str,
+ suggestions: list[str] | None = None,
+ source: str | None = None,
):
self.pipe_type = pipe_type
self.pipe_code = pipe_code
+ self.domain_code = domain_code
+ self.field_name = field_name
self.model_type = model_type
+ # The reference exactly as the author wrote it (``gpt-5.1``, ``@best-sonet``, ``$writting-factual``).
self.model_choice = model_choice
+ # The deck's close matches of the same kind, each spelled as a reference the field accepts.
+ self.suggestions = suggestions or []
+ # The file declaring the pipe. The operator does not know it — pipes carry no source — so the
+ # library load fills it from the crate's source map before the error leaves the load loop.
+ self.source = source
super().__init__(message)
- def desc(self) -> str:
- msg = f"{self.message}"
- msg += f" • pipe='{self.pipe_code}' ({self.pipe_type})"
- msg += f" • model_type='{self.model_type}'"
-
- # Extract the choice identifier from the model_choice union type
- if isinstance(self.model_choice, str):
- # It's a raw string (shouldn't happen but handle it)
- msg += f" • choice='{self.model_choice}'"
- elif isinstance(self.model_choice, ModelReference):
- # It's a ModelReference with kind and name
- msg += f" • choice='{self.model_choice.raw}' ({self.model_choice.kind})"
- else:
- # It's a Setting object with a model field and optional desc()
- msg += f" • choice={self.model_choice.desc()}"
+ @classmethod
+ def make_from_model_choice_not_found(
+ cls,
+ *,
+ model_choice_error: ModelChoiceNotFoundError,
+ pipe_type: str,
+ pipe_code: str,
+ domain_code: str,
+ field_name: str,
+ ) -> "PipeOperatorModelChoiceError":
+ """Locate the deck check's refusal on the pipe and the field that named the model."""
+ message = f"Pipe '{pipe_code}' ({pipe_type}), field '{field_name}': {model_choice_error.message}"
+ return cls(
+ message,
+ pipe_type=pipe_type,
+ pipe_code=pipe_code,
+ domain_code=domain_code,
+ field_name=field_name,
+ model_type=model_choice_error.model_type,
+ model_choice=model_choice_error.model_choice,
+ suggestions=list(model_choice_error.suggestions),
+ )
+
+
+class PipeLoadRefusalError(PipelexError):
+ """Raised by the library load when building one pipe of a bundle raises a refusal of the caller's input
+ that carries no locator of its own. It names the pipe and its file, and bundle validation reports it
+ as an invalid verdict.
+
+ The load raises it ``from`` the refusal, so the original stays the ``__cause__``. Bundle validation
+ turns it into one ``pipe_validation`` item carrying the pipe code, the domain and the source, with no
+ ``error_type``, since the refusal has no closed code. Only an ``input``-domained refusal is wrapped: a
+ fault of the configuration or of the runtime keeps its own identity and stays a no-verdict fault.
+
+ Its message is built only from caller-facing material, the caller's own pipe code and either the
+ refusal's message, when that message is caller-facing, or the refusal's title, so it is kept under
+ STRICT disclosure.
+ """
- return msg
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
+
+ def __init__(self, message: str, *, pipe_code: str, domain_code: str, source: str | None):
+ self.pipe_code = pipe_code
+ self.domain_code = domain_code
+ self.source = source
+ super().__init__(message)
- @override
- def __str__(self) -> str:
- return self.desc()
+ @classmethod
+ def make_from_refusal(cls, *, refusal: PipelexError, pipe_code: str, domain_code: str, source: str | None) -> "PipeLoadRefusalError":
+ """Locate a refusal on the pipe being built, keeping its message only when it is caller-facing."""
+ message = f"Pipe '{pipe_code}' could not be loaded: {caller_facing_refusal_text(refusal=refusal)}"
+ return cls(message, pipe_code=pipe_code, domain_code=domain_code, source=source)
+
+
+def caller_facing_refusal_text(*, refusal: PipelexError) -> str:
+ """The refusal's message when it was authored as caller-facing copy, otherwise its title.
+
+ A validation verdict is caller-facing as a whole — ``ValidateBundleError`` keeps its message under
+ STRICT disclosure — so text taken from a refusal onto a verdict item must be caller-facing too: a
+ refusal whose message is internal is named by its title, which is always public.
+ """
+ report = refusal.to_error_report()
+ if report.caller_facing_message:
+ return report.message
+ return report.title
class PipeValidationError(ValueError):
diff --git a/pipelex/libraries/concept_reference_validation.py b/pipelex/libraries/concept_reference_validation.py
index 4c91793f0..04dbd4c4a 100644
--- a/pipelex/libraries/concept_reference_validation.py
+++ b/pipelex/libraries/concept_reference_validation.py
@@ -26,6 +26,20 @@ def _split_concept_ref_context(context: str) -> tuple[str | None, str | None, st
return None, None, context
+def _declared_concept_codes(*, domain_code: str, concept_refs: set[str]) -> list[str]:
+ """The bare codes of the concepts among ``concept_refs`` declared in ``domain_code`` itself, sorted.
+
+ A ref belongs to the domain when the domain is its whole prefix: ``legal.X`` is in ``legal``, while
+ ``legal.contracts.X`` is in ``legal.contracts``. Native and cross-package refs never match.
+ """
+ domain_prefix = f"{domain_code}."
+ return sorted(
+ concept_ref.removeprefix(domain_prefix)
+ for concept_ref in concept_refs
+ if concept_ref.startswith(domain_prefix) and "." not in concept_ref.removeprefix(domain_prefix)
+ )
+
+
def validate_concept_references_in_blueprints(
blueprints: list[PipelexBundleBlueprint],
*,
@@ -66,6 +80,10 @@ def validate_concept_references_in_blueprints(
native_codes = {native.value for native in NativeConceptCode.values_list()}
undeclared: list[str] = []
+ # Each unresolved item lists what its domain declares in this batch, the concepts the reference could
+ # have named in the files submitted. Never the concepts a prior batch loaded: those may come from a
+ # host's own library directories, which a caller's verdict must not enumerate. Computed once per domain.
+ declared_concepts_by_domain: dict[str, list[str]] = {}
# Pipe-owned references (a pipe input/output) and concept-owned references (a concept's
# `refines` or a structure field's `concept_ref`) are categorized differently: a pipe-owned
# miss is a `pipe_validation` item, a concept-owned miss is a `blueprint_validation` item
@@ -96,6 +114,11 @@ def validate_concept_references_in_blueprints(
undeclared.append(f"'{concept_ref_or_code}' in {context} is not declared in domain '{domain_code}' (source: '{source or 'unknown'}')")
owning_pipe_code, owning_concept_code, field_name = _split_concept_ref_context(context)
item_message = f"Concept '{concept_ref_or_code}' in {context} is not declared in domain '{domain_code}' and is not native."
+ if domain_code not in declared_concepts_by_domain:
+ declared_concepts_by_domain[domain_code] = _declared_concept_codes(
+ domain_code=domain_code, concept_refs=batch_declared_concept_refs
+ )
+ declared_concepts = declared_concepts_by_domain[domain_code]
if owning_pipe_code is not None:
# Pipe-owned reference → pipe_validation, locating the referencing pipe, the
# missing concept (concept_code), and the field that holds the reference.
@@ -107,6 +130,7 @@ def validate_concept_references_in_blueprints(
pipe_code=owning_pipe_code,
concept_code=concept_ref_or_code,
field_name=field_name,
+ declared_concepts=declared_concepts,
message=item_message,
field_path=context,
)
@@ -123,6 +147,7 @@ def validate_concept_references_in_blueprints(
domain_code=domain_code,
source=source,
concept_code=owning_concept_code or concept_ref_or_code,
+ declared_concepts=declared_concepts,
message=item_message,
)
)
diff --git a/pipelex/libraries/crate_normalization.py b/pipelex/libraries/crate_normalization.py
index f3a47dd4d..100aeeada 100644
--- a/pipelex/libraries/crate_normalization.py
+++ b/pipelex/libraries/crate_normalization.py
@@ -99,6 +99,7 @@ def normalize_crate(crate: LibraryCrate, *, mthds_version: str) -> LibraryCrate:
pipes=pipes,
domains=crate.domains,
source_map=crate.source_map,
+ elaboration_metadata=crate.elaboration_metadata,
fingerprint=fingerprint,
)
diff --git a/pipelex/libraries/library_crate.py b/pipelex/libraries/library_crate.py
index 5f50c186a..bde4ab2d2 100644
--- a/pipelex/libraries/library_crate.py
+++ b/pipelex/libraries/library_crate.py
@@ -5,7 +5,7 @@ from pydantic import BaseModel, ConfigDict, Field
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.domains.domain_blueprint import DomainBlueprint
-from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipeBlueprintUnion
+from pipelex.mthds_parsing.pipelex_bundle_blueprint import ElaborationMetadata, PipeBlueprintUnion
class LibraryCrate(BaseModel):
@@ -35,6 +35,11 @@ class LibraryCrate(BaseModel):
source_map: dict[str, str] = Field(default_factory=dict)
"""concept_ref or pipe_ref -> source file path (for error reporting)"""
+ elaboration_metadata: dict[str, ElaborationMetadata] = Field(default_factory=dict)
+ """pipe_ref -> how the bundle elaborator generated that synthetic pipe (the helpers of a
+ ``preliminary_text`` PipeLLM), so a refusal raised while building a helper is reported on the pipe
+ and the field the author wrote. Like ``source_map``, it is excluded from the fingerprint."""
+
python_sources: dict[str, str] = Field(default_factory=dict)
"""relpath (within the library dir) -> Python source text, captured WITHOUT importing.
diff --git a/pipelex/libraries/library_crate_factory.py b/pipelex/libraries/library_crate_factory.py
index b69b216d0..f4bc74986 100644
--- a/pipelex/libraries/library_crate_factory.py
+++ b/pipelex/libraries/library_crate_factory.py
@@ -8,7 +8,7 @@ from pipelex.libraries.contract_match import contracts_match
from pipelex.libraries.domain.domain_metadata_merge import merge_domain_metadata_field
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.libraries.pipe.exceptions import PipeLibraryError
-from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipeBlueprintUnion, PipelexBundleBlueprint
+from pipelex.mthds_parsing.pipelex_bundle_blueprint import ElaborationMetadata, PipeBlueprintUnion, PipelexBundleBlueprint
from pipelex.pipe_machinery.pipe_factory import PipeFactory
if TYPE_CHECKING:
@@ -60,6 +60,7 @@ class LibraryCrateFactory:
pipes: dict[str, PipeBlueprintUnion] = {}
domains: dict[str, DomainBlueprint] = {}
source_map: dict[str, str] = {}
+ elaboration_metadata: dict[str, ElaborationMetadata] = {}
for blueprint in blueprints:
domain_code = blueprint.domain
@@ -141,10 +142,17 @@ class LibraryCrateFactory:
source_map[pipe_ref] = winner.source
else:
source_map.pop(pipe_ref, None)
+ if winner.blueprint is pipe_blueprint:
+ cls._track_elaboration(
+ elaboration_metadata=elaboration_metadata, pipe_ref=pipe_ref, elaboration=blueprint.get_elaboration_for(pipe_code)
+ )
continue
pipes[pipe_ref] = pipe_blueprint
if source:
source_map[pipe_ref] = source
+ cls._track_elaboration(
+ elaboration_metadata=elaboration_metadata, pipe_ref=pipe_ref, elaboration=blueprint.get_elaboration_for(pipe_code)
+ )
# Concept-reference validation is NOT done here: this factory performs a world-agnostic
# structural merge. Same-domain concept references resolve against the live library (which
@@ -156,10 +164,19 @@ class LibraryCrateFactory:
pipes=pipes,
domains=domains,
source_map=source_map,
+ elaboration_metadata=elaboration_metadata,
python_sources=python_sources or {},
fingerprint=fingerprint,
)
+ @staticmethod
+ def _track_elaboration(*, elaboration_metadata: dict[str, ElaborationMetadata], pipe_ref: str, elaboration: ElaborationMetadata | None) -> None:
+ """Keep the elaboration side-table on the declaration that won ``pipe_ref``, like ``source_map``."""
+ if elaboration is None:
+ elaboration_metadata.pop(pipe_ref, None)
+ else:
+ elaboration_metadata[pipe_ref] = elaboration
+
@classmethod
def _reconcile_pipe_collision(
cls,
diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.py
index f10b74e9f..e564c66ee 100644
--- a/pipelex/libraries/library_manager.py
+++ b/pipelex/libraries/library_manager.py
@@ -1,5 +1,6 @@
import uuid
-from contextlib import ExitStack
+from collections.abc import Generator
+from contextlib import ExitStack, contextmanager
from graphlib import CycleError, TopologicalSorter
from pathlib import Path
from typing import TYPE_CHECKING
@@ -15,12 +16,15 @@ from typing_extensions import override
import pipelex.builder as builder_pkg # package import — used for __file__ path
from pipelex import log
+from pipelex.base_exceptions import PipelexError, SecurityError, error_domain_is_input
+from pipelex.cogt.exceptions import ModelChoiceNotFoundError
from pipelex.config import is_pipe_func_sandbox_hosted
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.domains.domain_blueprint import DomainBlueprint
from pipelex.core.domains.domain_factory import DomainFactory
+from pipelex.core.pipes.exceptions import PipeLoadRefusalError, PipeOperatorModelChoiceError
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.validation import report_validation_error
@@ -47,7 +51,7 @@ from pipelex.methods.fetch_on_miss import resolve_address_based_method
from pipelex.mthds_parsing.exceptions import MthdsParserError
from pipelex.mthds_parsing.handle_pipe_errors import categorize_pipe_validation_error
from pipelex.mthds_parsing.parser import MthdsParser
-from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
+from pipelex.mthds_parsing.pipelex_bundle_blueprint import ElaborationMetadata, PipelexBundleBlueprint, StepRole
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.runtime_hub import get_class_registry
@@ -99,6 +103,95 @@ def _find_methods_dirs_from_blueprints(blueprints: list[PipelexBundleBlueprint])
return result
+def _dependency_bundle_source(*, package_address: str, package_root: Path, mthds_path: Path) -> str:
+ """Name a dependency's bundle by the package's address and the bundle's path inside the package.
+
+ The name is the bundle's ``source``, which rides every item a refusal inside the package gives, the
+ files a duplicate declaration names included, and a verdict is caller-facing: where the host installed
+ the package is the host's own path, which a hosted caller must never read. A bundle found outside the
+ package root, which discovery does not produce, is named by its file name alone rather than by its path.
+ """
+ for candidate_root in (package_root, package_root.resolve()):
+ for candidate_path in (mthds_path, mthds_path.resolve()):
+ if candidate_path.is_relative_to(candidate_root):
+ return f"{package_address}/{candidate_path.relative_to(candidate_root).as_posix()}"
+ return f"{package_address}/{mthds_path.name}"
+
+
+def _authored_model_field(*, step_role: StepRole) -> str:
+ """The field of the authored ``preliminary_text`` PipeLLM whose model a synthetic helper was given."""
+ match step_role:
+ case StepRole.DRAFT_TEXT:
+ return "model"
+ case StepRole.STRUCTURE:
+ return "model_to_structure"
+
+
+def _relocate_on_authored_pipe(
+ *, model_choice_error: PipeOperatorModelChoiceError, elaboration: ElaborationMetadata, domain_code: str
+) -> PipeOperatorModelChoiceError:
+ """Move an unknown model refused on a synthetic helper onto the authored pipe and field it came from."""
+ cause = model_choice_error.__cause__
+ if not isinstance(cause, ModelChoiceNotFoundError):
+ return model_choice_error
+ relocated = PipeOperatorModelChoiceError.make_from_model_choice_not_found(
+ model_choice_error=cause,
+ pipe_type="PipeLLM",
+ pipe_code=elaboration.parent_pipe_code,
+ domain_code=domain_code,
+ field_name=_authored_model_field(step_role=elaboration.step_role),
+ )
+ relocated.source = model_choice_error.source
+ return relocated
+
+
+@contextmanager
+def _locating_pipe_build_refusals(
+ *, pipe_code: str, domain_code: str, source: str | None, elaboration: ElaborationMetadata | None
+) -> Generator[None, None, None]:
+ """Let a refusal raised while building one pipe leave the load loop located on that pipe and its file.
+
+ The loop is the one place that holds the pipe's code, its domain and the file it is declared in at
+ the moment a build fails: pipes carry no source, and the pipe-source map is filled only after a
+ pipe is built. So the location is attached here, and bundle validation reads it off the refusal:
+
+ - An unknown model is already located on its pipe and field by the operator
+ (``PipeOperatorModelChoiceError``); the loop adds the file and lets it go on under its own class,
+ which the validate and run paths turn into its ``unknown_model`` verdict item and the build
+ surfaces render with their dedicated panel.
+ - Any other refusal of the caller's input (an ``input``-domained ``PipelexError``) is raised again
+ as a ``PipeLoadRefusalError`` naming the pipe and the file, ``from`` the original.
+ - Everything else leaves untouched: a configuration or runtime fault keeps its identity and stays a
+ no-verdict fault, a security refusal is never absorbed into a verdict, a library error keeps the
+ structured items its own arm forwards, and pydantic's ``ValidationError`` and the
+ ``PipeValidationError`` family (not ``PipelexError``s) keep their categorizers.
+
+ A synthetic helper the bundle elaborator generated (the ``<code>__draft_text`` and ``<code>__structure``
+ pipes of a ``preliminary_text`` PipeLLM) is not in the author's file, so its refusal is located on
+ the authored pipe instead, and an unknown model on the authored field the helper's model came from.
+ """
+ try:
+ yield
+ except PipeOperatorModelChoiceError as model_choice_error:
+ if model_choice_error.source is None:
+ model_choice_error.source = source
+ if elaboration is None:
+ raise
+ relocated = _relocate_on_authored_pipe(model_choice_error=model_choice_error, elaboration=elaboration, domain_code=domain_code)
+ if relocated is model_choice_error:
+ raise
+ raise relocated from model_choice_error
+ except (SecurityError, LibraryError):
+ raise
+ except PipelexError as refusal:
+ if not error_domain_is_input(refusal.to_error_report().error_domain):
+ raise
+ authored_pipe_code = elaboration.parent_pipe_code if elaboration is not None else pipe_code
+ raise PipeLoadRefusalError.make_from_refusal(
+ refusal=refusal, pipe_code=authored_pipe_code, domain_code=domain_code, source=source
+ ) from refusal
+
+
class LibraryManager(LibraryManagerAbstract):
def __init__(self):
# UNTITLED library is the fallback library for all others
@@ -536,16 +629,19 @@ class LibraryManager(LibraryManagerAbstract):
concept_codes_for_domain = domain_concept_codes.get(domain_code, [])
- pipe = PipeFactory[PipeAbstract].make_from_blueprint(
- domain_code=domain_code,
- pipe_code=pipe_code,
- blueprint=pipe_blueprint,
- concept_codes_from_the_same_domain=concept_codes_for_domain,
- )
+ source = crate.source_map.get(pipe_ref)
+ with _locating_pipe_build_refusals(
+ pipe_code=pipe_code, domain_code=domain_code, source=source, elaboration=crate.elaboration_metadata.get(pipe_ref)
+ ):
+ pipe = PipeFactory[PipeAbstract].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code=pipe_code,
+ blueprint=pipe_blueprint,
+ concept_codes_from_the_same_domain=concept_codes_for_domain,
+ )
all_pipes.append(pipe)
# Track source file for this pipe (used by get_pipe_source)
- source = crate.source_map.get(pipe_ref)
if source:
self._pipe_source_maps.setdefault(library_id, {})[pipe_ref] = source
@@ -993,6 +1089,7 @@ class LibraryManager(LibraryManagerAbstract):
self._load_single_dependency(
library=library,
resolved_dep=resolved_dep,
+ package_address=resolved_dep.address,
)
# Wire concept resolver after all deps are loaded so cross-package
@@ -1004,6 +1101,7 @@ class LibraryManager(LibraryManagerAbstract):
library: Library,
*,
resolved_dep: ResolvedDependency,
+ package_address: str,
) -> None:
"""Load a single resolved dependency into an isolated child library.
@@ -1011,9 +1109,14 @@ class LibraryManager(LibraryManagerAbstract):
into it, registers it in library.dependency_libraries, and adds aliased
entries to the main library for backward-compatible cross-package lookups.
+ Each bundle's ``source`` is ``<package_address>/<path inside the package>``, never the file's
+ path on the host (see ``_dependency_bundle_source``), so a refusal inside the dependency names it
+ that way on every surface.
+
Args:
library: The main library to load into
resolved_dep: The resolved dependency info
+ package_address: The dependency's address as a reference names it, without any ``@<tag>``
"""
alias = resolved_dep.alias
@@ -1022,7 +1125,9 @@ class LibraryManager(LibraryManagerAbstract):
for mthds_path in resolved_dep.mthds_files:
try:
blueprint = MthdsParser.make_pipelex_bundle_blueprint(bundle_path=mthds_path)
- blueprint.source = str(mthds_path)
+ blueprint.source = _dependency_bundle_source(
+ package_address=package_address, package_root=resolved_dep.package_root, mthds_path=mthds_path
+ )
except (FileNotFoundError, MthdsParserError) as exc:
log.warning(f"Could not parse dependency '{alias}' bundle '{mthds_path}': {exc}")
continue
@@ -1142,12 +1247,20 @@ class LibraryManager(LibraryManagerAbstract):
if has_exports and pipe_code not in all_exported:
continue
try:
- pipe = PipeFactory[PipeAbstract].make_from_blueprint(
- domain_code=domain_code,
+ # The same location the main load path attaches, so a dependency pipe's refusal
+ # names the dependency's own file.
+ with _locating_pipe_build_refusals(
pipe_code=pipe_code,
- blueprint=pipe_blueprint,
- concept_codes_from_the_same_domain=domain_concept_codes.get(domain_code, []),
- )
+ domain_code=domain_code,
+ source=crate.source_map.get(pipe_ref),
+ elaboration=crate.elaboration_metadata.get(pipe_ref),
+ ):
+ pipe = PipeFactory[PipeAbstract].make_from_blueprint(
+ domain_code=domain_code,
+ pipe_code=pipe_code,
+ blueprint=pipe_blueprint,
+ concept_codes_from_the_same_domain=domain_concept_codes.get(domain_code, []),
+ )
child_library.pipe_library.add_new_pipe(pipe=pipe)
except ValidationError as exc:
log.warning(f"Could not load dependency '{alias}' pipe '{pipe_code}': {exc}")
@@ -1261,6 +1374,8 @@ class LibraryManager(LibraryManagerAbstract):
self._load_single_dependency(
library=library,
resolved_dep=resolved_dep,
+ # The address the lookup matched (the manifest's address and the method's name), never a tag.
+ package_address=f"{installed.manifest.address}/{installed.name}",
)
def _remove_pipes_from_blueprint(self, blueprint: PipelexBundleBlueprint) -> None:
diff --git a/pipelex/mthds_parsing/handle_pipe_errors.py b/pipelex/mthds_parsing/handle_pipe_errors.py
index 79181d3ae..f3b389e5b 100644
--- a/pipelex/mthds_parsing/handle_pipe_errors.py
+++ b/pipelex/mthds_parsing/handle_pipe_errors.py
@@ -5,7 +5,7 @@ from pydantic import ValidationError
from pydantic_core import ErrorDetails
from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeFactoryError, PipeValidationError
+from pipelex.core.pipes.exceptions import PipeFactoryError, PipeOperatorModelChoiceError, PipeValidationError
from pipelex.validation_error_types import PipeValidationErrorType
@@ -235,3 +235,34 @@ def categorize_pipe_factory_error(
declared_concepts=factory_error.declared_concepts,
message=factory_error.message,
)
+
+
+def categorize_pipe_operator_model_choice_error(
+ *,
+ model_choice_error: PipeOperatorModelChoiceError,
+) -> PipesAndConceptValidationErrorData:
+ """Categorize an unknown model into the ``unknown_model`` error data, located on its pipe and field.
+
+ The ``field_path`` addresses the reference in the bundle (``pipe.<code>.model``, or
+ ``pipe.<code>.model_to_structure`` on a ``PipeLLM``). The reference as written, the model type and
+ the deck's suggestions ride as their own fields, and the suggestions stay in the message too, for
+ the consumers that keep only an item's message.
+
+ Args:
+ model_choice_error: The located unknown-model refusal a pipe operator raised when it was built.
+
+ Returns:
+ PipesAndConceptValidationErrorData with the unknown-model locators populated
+ """
+ return PipesAndConceptValidationErrorData(
+ error_type=PipeValidationErrorType.UNKNOWN_MODEL,
+ domain_code=model_choice_error.domain_code,
+ source=model_choice_error.source,
+ pipe_code=model_choice_error.pipe_code,
+ field_name=model_choice_error.field_name,
+ field_path=f"pipe.{model_choice_error.pipe_code}.{model_choice_error.field_name}",
+ message=model_choice_error.message,
+ model_reference=model_choice_error.model_choice,
+ model_type=model_choice_error.model_type,
+ suggestions=list(model_choice_error.suggestions),
+ )
diff --git a/pipelex/mthds_parsing/parser.py b/pipelex/mthds_parsing/parser.py
index bc2c05357..bcf467105 100644
--- a/pipelex/mthds_parsing/parser.py
+++ b/pipelex/mthds_parsing/parser.py
@@ -61,6 +61,9 @@ class MthdsParser(BaseModel):
PipelexBundleBlueprintValidationErrorData(
source=source,
message=msg,
+ # tomli counts both from 1, as the item's locators do.
+ line=exc.lineno,
+ column=exc.colno,
)
],
) from exc
@@ -76,6 +79,8 @@ class MthdsParser(BaseModel):
pipelex_bundle_blueprint = PipelexBundleBlueprint.model_validate(blueprint_dict)
except ValidationError as exc:
# TODO: Move this to the validate_bundle function
+ # Every error becomes an item, categorized or not, so none hides another; only a concept's
+ # union-branch noise is left out, its table branch reporting the same fault.
blueprint_validation_errors: list[PipelexBundleBlueprintValidationErrorData] = []
for error in exc.errors():
diff --git a/pipelex/mthds_parsing/validation_error_categorizer.py b/pipelex/mthds_parsing/validation_error_categorizer.py
index 56821488a..4d24dfa65 100644
--- a/pipelex/mthds_parsing/validation_error_categorizer.py
+++ b/pipelex/mthds_parsing/validation_error_categorizer.py
@@ -1,7 +1,8 @@
import re
-from typing import Any, cast
+from typing import Any, cast, get_args
from pydantic_core import ErrorDetails
+from pydantic_core.core_schema import CoreSchemaType
from pipelex import log
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData
@@ -11,6 +12,7 @@ from pipelex.mthds_parsing.exceptions import (
)
from pipelex.mthds_parsing.handle_pipe_errors import extract_wrapped_pipe_validation_error
from pipelex.mthds_parsing.helpers import ValidationErrorScope, get_error_scope
+from pipelex.pipe_machinery.pipe_blueprint import PIPE_SIGNATURE_TYPE_TAG, PipeType
from pipelex.validation_error_types import PipeValidationErrorType
PIPELEX_BUNDLE_BLUEPRINT_DOMAIN_FIELD = "domain"
@@ -27,6 +29,20 @@ PIPELEX_BUNDLE_BLUEPRINT_PIPE_FIELD = "pipe"
_MISSING_PIPE_TYPE_MARKER = "has no `type` but declares"
_EXPLICIT_SIGNATURE_TAG_MARKER = "is no longer a pipe type"
+# The tags of the union a `[pipe.<code>]` section validates through. Pydantic names the tag it routed to in
+# an error's location (`pipe.<code>.PipeLLM.<field>`), but the tag is not a field of the bundle.
+_PIPE_UNION_TAGS = frozenset([*PipeType.value_list(), PIPE_SIGNATURE_TYPE_TAG])
+
+# Pydantic's own schema tags that contain a hyphen ("function-after", "tagged-union"...). A key an author
+# writes may contain one too ("prompt-template"), so a hyphen alone does not make a location element pydantic's.
+_PYDANTIC_HYPHENATED_SCHEMA_TAGS = frozenset(tag for tag in get_args(CoreSchemaType) if "-" in tag)
+
+# The pydantic error type of a key the model does not define, whose location ends with the key as written.
+_PYDANTIC_EXTRA_FORBIDDEN_ERROR_TYPE = "extra_forbidden"
+
+# The prefix pydantic puts before the message of a ``ValueError`` a validator raised.
+_PYDANTIC_VALUE_ERROR_PREFIX = "Value error, "
+
def _extract_wrapped_native_concept_redeclaration_error(error: ErrorDetails) -> NativeConceptRedeclarationError | None:
"""Extract a ``NativeConceptRedeclarationError`` wrapped by pydantic, or ``None``.
@@ -238,8 +254,9 @@ def _is_pydantic_internal_loc_element(element: str) -> bool:
internal type discriminators (e.g. "ConceptBlueprint", "dict[str,union[str,function-after]]",
"function-after", "str"). We filter out the internal ones to build cleaner error paths.
"""
- # Elements containing brackets or hyphens are pydantic type names (e.g. "dict[str,...]", "function-after")
- if "[" in element or "-" in element:
+ # Elements containing brackets are pydantic type names (e.g. "dict[str,...]"), and so are its hyphenated
+ # schema tags (e.g. "function-after"); a hyphenated key the author wrote is kept.
+ if "[" in element or element in _PYDANTIC_HYPHENATED_SCHEMA_TAGS:
return True
# Builtin type names and pydantic model class names used as union discriminators
return element in {"str", "int", "float", "bool", "list", "dict", "set", "tuple", "none", "ConceptBlueprint"}
@@ -290,22 +307,75 @@ def _categorize_concept_validation_error(
)
+def _bundle_field_path(*, loc: tuple[int | str, ...], ends_with_authored_key: bool) -> str | None:
+ """The dot path from the bundle root that a pydantic ``loc`` names, without pydantic's own elements.
+
+ A pipe section validates through a union tagged by its ``type``, so pydantic puts the tag in the
+ location (``pipe.summarize.PipeLLM.promtp``); the tag and pydantic's type discriminators are
+ dropped, leaving the path the author would follow in the file (``pipe.summarize.promtp``). When the
+ location ends with a key the author wrote (``ends_with_authored_key``), that key is kept whatever it
+ looks like, since a key named ``str`` is still the key to fix.
+ """
+ parts = [str(part) for part in loc]
+ if len(parts) >= 3 and parts[0] == PIPELEX_BUNDLE_BLUEPRINT_PIPE_FIELD and parts[2] in _PIPE_UNION_TAGS:
+ del parts[2]
+ authored_key = parts.pop() if ends_with_authored_key and parts else None
+ clean_parts = [part for part in parts if not _is_pydantic_internal_loc_element(part)]
+ if authored_key is not None:
+ clean_parts.append(authored_key)
+ return ".".join(clean_parts) or None
+
+
+def _make_uncategorized_blueprint_error(
+ *,
+ error: ErrorDetails,
+ domain: str | None,
+ source: str | None,
+ pipe_code: str | None,
+) -> PipelexBundleBlueprintValidationErrorData:
+ """Keep an error no categorizer knows as an item of its own, with the locators its location gives.
+
+ It carries no ``error_type``: no closed code identifies the fault, as for the parse-level residual.
+ It keeps the ``source`` the parser seeded, the pipe its location names and the ``field_path``, so an
+ error such as a misspelled field reaches the author beside the errors that are categorized, rather
+ than only once those are fixed.
+ """
+ field_path = _bundle_field_path(loc=error["loc"], ends_with_authored_key=error["type"] == _PYDANTIC_EXTRA_FORBIDDEN_ERROR_TYPE)
+ message = error["msg"].removeprefix(_PYDANTIC_VALUE_ERROR_PREFIX)
+ return PipelexBundleBlueprintValidationErrorData(
+ domain_code=domain,
+ source=source,
+ pipe_code=pipe_code,
+ field_path=field_path,
+ message=f"Validation error at '{field_path}': {message}" if field_path else message,
+ )
+
+
def categorize_blueprint_validation_error(
error: ErrorDetails,
*,
blueprint_dict: dict[str, Any],
) -> PipelexBundleBlueprintValidationErrorData | None:
- """Categorize a BLUEPRINT validation error and create structured error data or return None if the error cannot be categorized.
+ """Categorize a BLUEPRINT validation error into structured error data.
+
+ An error no categorizer knows is kept as an uncategorized item (no ``error_type``) located by its
+ source, pipe and field path, so every error of a bundle becomes an item. ``None`` is returned only
+ for the union-branch noise of a concept declared as ``ConceptBlueprint | str``, whose table branch
+ already reports the fault.
Args:
error: Pydantic error from PipelexBundleBlueprint.model_validate()
blueprint_dict: The blueprint dict being validated (for context extraction)
Returns:
- PipelexBundleBlueprintValidationErrorData with all relevant fields populated, or None if error cannot be categorized
+ PipelexBundleBlueprintValidationErrorData with all relevant fields populated, or None for concept union noise
"""
- domain = cast("str | None", blueprint_dict.get(PIPELEX_BUNDLE_BLUEPRINT_DOMAIN_FIELD)) if blueprint_dict else None
- source = cast("str | None", blueprint_dict.get(PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD)) if blueprint_dict else None
+ # Read off the raw dict, whose values are whatever the author wrote: a `domain = 123` is itself one of
+ # the errors being categorized, so a value that is not a string locates nothing.
+ raw_domain = blueprint_dict.get(PIPELEX_BUNDLE_BLUEPRINT_DOMAIN_FIELD) if blueprint_dict else None
+ raw_source = blueprint_dict.get(PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD) if blueprint_dict else None
+ domain = raw_domain if isinstance(raw_domain, str) else None
+ source = raw_source if isinstance(raw_source, str) else None
loc = error["loc"]
message = error["msg"]
@@ -448,7 +518,6 @@ def categorize_blueprint_validation_error(
if syntax_error:
return syntax_error
- # If we couldn't categorize the error, log a warning
- log.warning(f"Pipelex bundle blueprint validation error that is not categorized: {error_scope} - {source} - {domain}")
-
- return None
+ # No categorizer knows it: keep it as an item of its own, never dropped because another item exists.
+ log.verbose(f"Pipelex bundle blueprint validation error that is not categorized: {error_scope} - {source} - {domain}")
+ return _make_uncategorized_blueprint_error(error=error, domain=domain, source=source, pipe_code=pipe_code)
diff --git a/pipelex/pipe_controllers/condition/exceptions.py b/pipelex/pipe_controllers/condition/exceptions.py
index e1d4f7cf3..d1358166f 100644
--- a/pipelex/pipe_controllers/condition/exceptions.py
+++ b/pipelex/pipe_controllers/condition/exceptions.py
@@ -1,5 +1,13 @@
-from pipelex.base_exceptions import PipelexError
+from pipelex.base_exceptions import ErrorDomain, PipelexError
class PipeConditionFactoryError(PipelexError):
- pass
+ """Raised when a ``PipeCondition`` declares neither ``expression_template`` nor ``expression``.
+
+ Raised only while the pipe is built from its blueprint, about that blueprint, so it is the author's to fix
+ (``input``) and bundle validation reports it as an item located on the pipe. Its messages name only the
+ author's own pipe, concepts and template text, so they are caller-facing copy kept under STRICT disclosure.
+ """
+
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
diff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.py
index 02c7f3d10..9ef4826f7 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition.py
@@ -1,8 +1,10 @@
from typing import TYPE_CHECKING, Any, Literal
+from jinja2 import TemplateSyntaxError
from typing_extensions import override
from pipelex import log
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.cogt.templating.template_rendering import render_template
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
@@ -236,11 +238,21 @@ class PipeCondition(PipeController):
context=working_memory.generate_context(),
)
if not evaluated_expression or evaluated_expression == "None":
+ # The expression is the caller's own method, rendered over their run's data: when it renders
+ # nothing, no outcome can be chosen, and the method is theirs to fix. The message names only the pipe.
error_msg = f"PipeCondition '{self.code}': Conditional expression returned no result"
raise PipeRunError(
pipe_code=self.code,
message=error_msg,
run_mode=pipe_run_params.run_mode,
+ ).as_caller_fault(
+ user_action=UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail=(
+ f"Change the expression of PipeCondition '{self.code}' so that it always renders a value: "
+ "the name of one of its outcomes, or any other value, which takes the default outcome."
+ ),
+ )
)
@override
@@ -313,8 +325,19 @@ class PipeCondition(PipeController):
if SpecialOutcome.is_fail(outcome):
self._register_execution_data(job_metadata=job_metadata, execution_data=execution_data_dict)
- msg = f"PipeCondition '{self.code}' failed with outcome: {outcome}. Evaluated expression: {evaluated_expression}"
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)
+ # The caller's method maps this outcome to 'fail' on purpose, a refusal of the run it was given. The
+ # message names only the pipe: the value the expression rendered can be literal text of the expression,
+ # or an outcome key, of a condition a host library declared. The execution data above keeps that value.
+ msg = f"PipeCondition '{self.code}' failed with outcome: {outcome}."
+ raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code).as_caller_fault(
+ user_action=UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail=(
+ f"PipeCondition '{self.code}' refuses this run on purpose: change the inputs so that its expression "
+ "selects another outcome, or map that outcome to a pipe or to 'continue'."
+ ),
+ )
+ )
chosen_pipe = get_required_pipe(pipe_code=outcome)
@@ -334,11 +357,16 @@ class PipeCondition(PipeController):
# (skip / run / force). Only a name with neither a value nor a record is a hard miss.
missing_names = working_memory.list_missing_names(names=required_stuff_names)
if missing_names:
- pipe_condition_path = [*pipe_run_params.pipe_layers, self.code]
- pipe_condition_path_str = ".".join(pipe_condition_path)
- error_details = f"PipeCondition '{pipe_condition_path_str}', required_variables: {required_variables}, missing: '{missing_names[0]}'"
- msg = f"Some required stuff(s) not found: {error_details}"
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)
+ # The caller's request or an earlier step of their method left out what the chosen pipe needs. The
+ # message names only the pipes and the input names.
+ missing_names_str = ", ".join(missing_names)
+ msg = f"PipeCondition '{self.code}' chose pipe '{outcome}', whose required inputs are missing: {missing_names_str}."
+ raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code).as_caller_fault(
+ user_action=UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail=f"Provide the missing required inputs of '{outcome}', which PipeCondition '{self.code}' chose: {missing_names_str}.",
+ )
+ )
pipe_output = await get_pipe_router().run(
pipe_job=PipeJobFactory.make_pipe_job(
@@ -373,11 +401,18 @@ class PipeCondition(PipeController):
log.verbose(f"Expression template is valid, requires variables: {required_variables}")
except Jinja2DetectVariablesError as exc:
log.error(f"Dry run failed: could not detect required variables from expression template: {exc}")
- msg = (
- f"Dry run failed for pipe '{self.code}' (PipeCondition): could not detect required variables "
- f"from expression template: {exc}\nTemplate:\n'{self.expression}'"
- )
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
+ # The expression is the caller's own method. The message quotes neither the expression nor the parser's
+ # diagnosis, which names the token it stopped at: the condition may be a host library's, whose text
+ # must not reach the caller. The line locates the fault. It is raised from the parser's own error,
+ # past the `Jinja2DetectVariablesError` that quotes the expression: a run failure reports the innermost
+ # Pipelex error on its chain (`find_root_fault`), which must be this refusal.
+ msg = f"Dry run failed for pipe '{self.code}' (PipeCondition): its expression {_describe_expression_parse_failure(error=exc)}."
+ raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code).as_caller_fault(
+ user_action=UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail=f"Fix the expression of PipeCondition '{self.code}' so that it parses as a Jinja2 expression.",
+ )
+ ) from exc.__cause__
# Validate that all values in the outcomes map (appart from special outcomes) do exist as pipe codes
all_pipe_codes = set(self.outcome_map.values())
@@ -385,14 +420,18 @@ class PipeCondition(PipeController):
all_pipe_codes.add(self.default_outcome)
all_pipe_codes -= set(SpecialOutcome.value_list())
- missing_pipes = [pipe_code for pipe_code in all_pipe_codes if not get_optional_pipe(pipe_code=pipe_code)]
+ missing_pipes = sorted(pipe_code for pipe_code in all_pipe_codes if not get_optional_pipe(pipe_code=pipe_code))
if missing_pipes:
- msg = (
- f"Dry run failed for PipeCondition '{self.code}': missing pipes: {', '.join(missing_pipes)}. "
- f"Pipe map: {self.outcome_map}, default: {self.default_outcome}"
+ # The caller's method names these pipes in its outcomes. The message names only the pipe codes.
+ missing_pipes_str = ", ".join(missing_pipes)
+ msg = f"Dry run failed for PipeCondition '{self.code}': its outcomes name pipes that do not exist: {missing_pipes_str}."
+ raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code).as_caller_fault(
+ user_action=UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail=f"Declare the pipes {missing_pipes_str}, or change the outcomes of PipeCondition '{self.code}' to name existing pipes.",
+ )
)
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)
# Here, it should launch the dry run of all the pipes in the outcomes map.
# pipe_dependencies() is a set, and every branch dry-runs into the SAME
@@ -423,11 +462,17 @@ class PipeCondition(PipeController):
# fail at runtime.
if not self.pipe_dependencies():
if not self._continue_reachable:
+ # The caller's method maps every outcome to 'fail'. The message names only the pipe.
msg = (
f"PipeCondition '{self.code}' maps every outcome (and the default) to 'fail': "
f"every live run of this pipe raises. Map at least one outcome to a pipe or to 'continue'."
)
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)
+ raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code).as_caller_fault(
+ user_action=UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail=f"Map at least one outcome of PipeCondition '{self.code}' to a pipe or to 'continue'.",
+ )
+ )
self._record_declared_absent_output(
working_memory=working_memory,
output_name=output_name,
@@ -444,3 +489,18 @@ class PipeCondition(PipeController):
producing_pipe=self.code,
)
working_memory.record_new_main_absence(record)
+
+
+def _describe_expression_parse_failure(*, error: Jinja2DetectVariablesError) -> str:
+ """Say where a condition's expression fails to parse, in words that owe nothing to the expression.
+
+ Every layer between Jinja2 and the condition puts the expression in its message, and Jinja2's own
+ diagnosis quotes the token it stopped at, so no text of the error can be passed on. The parser's line,
+ counted within the expression, is what locates the fault.
+ """
+ cause: BaseException | None = error.__cause__
+ while cause is not None:
+ if isinstance(cause, TemplateSyntaxError):
+ return f"does not parse at line {cause.lineno} of that expression"
+ cause = cause.__cause__
+ return "does not parse"
diff --git a/pipelex/pipe_controllers/parallel/exceptions.py b/pipelex/pipe_controllers/parallel/exceptions.py
index 8428cf8b2..8aea0e2b8 100644
--- a/pipelex/pipe_controllers/parallel/exceptions.py
+++ b/pipelex/pipe_controllers/parallel/exceptions.py
@@ -1,5 +1,13 @@
-from pipelex.base_exceptions import PipelexError
+from pipelex.base_exceptions import ErrorDomain, PipelexError
class PipeParallelFactoryError(PipelexError):
- pass
+ """Raised when a ``PipeParallel`` branch names no ``result``.
+
+ Raised only while the pipe is built from its blueprint, about that blueprint, so it is the author's to fix
+ (``input``) and bundle validation reports it as an item located on the pipe. Its messages name only the
+ author's own pipe, concepts and template text, so they are caller-facing copy kept under STRICT disclosure.
+ """
+
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel.py b/pipelex/pipe_controllers/parallel/pipe_parallel.py
index 9d2221797..0be3d86e6 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel.py
@@ -1,11 +1,13 @@
import asyncio
import builtins
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, get_origin
-from pydantic import field_validator
+from pydantic import ValidationError, field_validator
from typing_extensions import override
from pipelex import log
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
+from pipelex.core.concepts.annotation_shapes import list_item_annotation, strip_optional
from pipelex.core.concepts.concept import Concept
from pipelex.core.concepts.exceptions import ConceptValueError
from pipelex.core.concepts.native.concept_native import NativeConceptCode
@@ -16,7 +18,10 @@ from pipelex.core.pipes.inputs.exceptions import InputStuffSpecNotFoundError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactory
from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.composite_content import CompositeContent
+from pipelex.core.stuffs.exceptions import StuffFactoryError
+from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.graph.graph_tracer_manager import GraphTracerManager
@@ -519,12 +524,49 @@ class PipeParallel(PipeController):
# Always combine the branch outputs into the declared output concept and stamp it as main stuff:
# a pipe run always resolves its declared output — the combine is the parallel's value arm.
- combined_output_stuff = StuffFactory.combine_stuffs(
- concept=self.output.concept,
- stuff_contents=output_stuff_contents,
- name=output_name,
- code=final_stuff_code,
- )
+ try:
+ combined_output_stuff = StuffFactory.combine_stuffs(
+ concept=self.output.concept,
+ stuff_contents=output_stuff_contents,
+ name=output_name,
+ code=final_stuff_code,
+ )
+ except StuffFactoryError as exc:
+ # The combine validates the branch results against this parallel's declared output, and
+ # the caller's method sets both: which branch feeds which field, what each branch
+ # produces and whether it produces a list. A mismatch (a list branch feeding a single
+ # field, a concept its field does not accept, a required field no branch feeds) is the
+ # caller's to fix, and the message names only the output concept, the result name and
+ # the combined fields' validation errors.
+ # The output concept as the author writes it in this bundle, in the next step as in the restatement below.
+ output_concept_ref = self._concept_ref_for_message(concept=self.output.concept, package_alias=None)
+ method_next_step = (
+ f"Change the method so that each branch of PipeParallel '{self.code}' produces what the field of "
+ f"'{output_concept_ref}' it feeds expects, a list only where that field is a list, "
+ "and so that every required field is fed by a branch."
+ )
+ # When the refusal is a branch whose multiplicity differs from its field's, say which one to change;
+ # any other refusal leaves as it came, flagged as the caller's fault.
+ next_steps = self._multiplicity_next_steps(structure_class=structure_class, output_stuffs=output_stuffs)
+ if not next_steps:
+ exc.as_caller_fault(user_action=UserAction(kind=UserActionKind.CHANGE_INPUT, detail=method_next_step))
+ raise
+ lead = f"PipeParallel '{self.code}' cannot combine its branch results into its output '{output_concept_ref}'."
+ message_parts = [lead, *next_steps.values()]
+ next_step_parts = list(next_steps.values())
+ # Keep what the combine said about every other field it refused, so a second fault is not hidden
+ # behind the multiplicity one, and keep the general next step for it.
+ refused_fields = _refused_field_names(exc=exc)
+ if refused_fields is None or refused_fields - next_steps.keys():
+ message_parts.append(f"The combine also reported: {exc.message}")
+ next_step_parts.append(method_next_step)
+ # A StuffFactoryError raised from the combine's own: a run failure is reported as its root fault, and
+ # of two faults of the same class on the chain the outer one, which restates the inner with a remedy,
+ # is that root (see `pipe_run.located_failure.find_root_fault`), so every surface reports this one.
+ # It is the caller's fault like the refusal it restates, with the multiplicity change as its next step.
+ raise StuffFactoryError(" ".join(message_parts)).as_caller_fault(
+ user_action=UserAction(kind=UserActionKind.CHANGE_INPUT, detail=" ".join(next_step_parts))
+ ) from exc
working_memory.set_new_main_stuff(
stuff=combined_output_stuff,
name=output_name,
@@ -602,6 +644,108 @@ class PipeParallel(PipeController):
library_crate=library_crate,
)
+ def _multiplicity_next_steps(self, *, structure_class: builtins.type[StuffContent], output_stuffs: "dict[str, Stuff]") -> dict[str, str]:
+ """Say, for each branch whose result and field differ only in multiplicity, which one to change.
+
+ Called only after ``StuffFactory.combine_stuffs`` has refused the combination, to explain that
+ refusal: it refuses nothing itself. Returns one sentence per result name it can explain.
+
+ A branch result is a list when its content is a ``ListContent``. A field holds a list when its
+ annotation, an ``X | None`` peeled, is a ``list[...]`` of content classes, and holds one item when it
+ is any other content class. Every other field, a primitive list, a Python-authored ``ListContent``,
+ a union or a dict, gets no sentence, and neither does a branch whose concept has no structure class
+ or does not fit the field's item class: changing a multiplicity would not make those combine.
+
+ The sentences quote with single quotes only: the dry run carries them inside a representation that
+ would escape every single quote of a message that also held a double one.
+ """
+ if issubclass(structure_class, CompositeContent):
+ return {}
+ output_concept_ref = self._concept_ref_for_message(concept=self.output.concept, package_alias=None)
+ next_steps: dict[str, str] = {}
+ for sub_pipe in self.parallel_sub_pipes:
+ result_name = sub_pipe.output_name
+ if not result_name or result_name not in output_stuffs or result_name not in structure_class.model_fields:
+ continue
+ field_annotation, _ = strip_optional(annotation=structure_class.model_fields[result_name].annotation)
+ field_item_class: Any
+ is_field_plural: bool
+ if get_origin(field_annotation) is list:
+ is_field_plural = True
+ field_item_class = list_item_annotation(annotation=field_annotation)
+ elif isinstance(field_annotation, type) and issubclass(field_annotation, ListContent):
+ # A Python-authored ListContent field: its item class is not read here, so whether a
+ # multiplicity change would make the branch fit cannot be told, and no advice is given.
+ continue
+ elif isinstance(field_annotation, type) and issubclass(field_annotation, StuffContent):
+ is_field_plural = False
+ field_item_class = field_annotation
+ else:
+ continue
+ branch_stuff = output_stuffs[result_name]
+ is_branch_plural = branch_stuff.is_list
+ if is_branch_plural == is_field_plural:
+ continue
+ # The advice is given only when the branch's concept fits the field's item class, so a field
+ # whose items are not concept contents (a primitive list, a Python-authored ListContent) gets none.
+ if not isinstance(field_item_class, type) or not issubclass(field_item_class, StuffContent):
+ continue
+ if not branch_stuff.concept.declares_a_structure_class:
+ continue
+ branch_item_class = get_concept_library().get_structure_class(concept=branch_stuff.concept)
+ if not issubclass(branch_item_class, field_item_class):
+ continue
+ package_alias = (
+ QualifiedRef.split_cross_package_ref(sub_pipe.pipe_code).alias if QualifiedRef.has_cross_package_prefix(sub_pipe.pipe_code) else None
+ )
+ item_concept_ref = self._concept_ref_for_message(concept=branch_stuff.concept, package_alias=package_alias)
+ branch_ref = self._pipe_ref_for_message(pipe_ref=sub_pipe.pipe_code)
+ # A multiplicity set on the branch itself (nb_output, multiple_output, batch_over) overrides the
+ # pipe's declared output, so the branch alternative names that setting rather than the pipe's output.
+ branch_alternative: str
+ if sub_pipe.output_multiplicity is not None or sub_pipe.batch_params is not None:
+ branch_alternative = (
+ f"or change the nb_output, multiple_output or batch_over that branch '{branch_ref}' sets in the parallel's branches"
+ )
+ elif is_branch_plural:
+ branch_alternative = f"or make branch '{branch_ref}' output a single '{item_concept_ref}'"
+ else:
+ branch_alternative = f"or make branch '{branch_ref}' output '{item_concept_ref}[]'"
+ if is_branch_plural:
+ next_steps[result_name] = (
+ f"Branch '{branch_ref}' gives result '{result_name}' as a list, '{item_concept_ref}[]', but field "
+ f"'{result_name}' of '{output_concept_ref}' holds a single item. Declare the field as a list in the structure "
+ f"of '{output_concept_ref}', with type 'list', item_type 'concept' and item_concept_ref '{item_concept_ref}', "
+ f"{branch_alternative}."
+ )
+ else:
+ next_steps[result_name] = (
+ f"Branch '{branch_ref}' gives result '{result_name}' as a single '{item_concept_ref}', but field "
+ f"'{result_name}' of '{output_concept_ref}' holds a list. Declare the field as a single concept in the "
+ f"structure of '{output_concept_ref}', with type 'concept' and concept_ref '{item_concept_ref}', "
+ f"{branch_alternative}."
+ )
+ return next_steps
+
+ def _pipe_ref_for_message(self, *, pipe_ref: str) -> str:
+ """A branch pipe as the author writes it in this parallel's bundle: its bare code in the parallel's own
+ domain, its full ref otherwise.
+ """
+ own_domain_prefix = f"{self.domain_code}."
+ if pipe_ref.startswith(own_domain_prefix):
+ return pipe_ref.removeprefix(own_domain_prefix)
+ return pipe_ref
+
+ def _concept_ref_for_message(self, *, concept: Concept, package_alias: str | None) -> str:
+ """A concept as the author writes it in this parallel's bundle: its bare code in the parallel's own
+ domain, its ref behind the package alias when it comes from a dependency, its full ref otherwise.
+ """
+ if concept.domain_code == self.domain_code:
+ return concept.code
+ if package_alias is not None and not Concept.is_native_concept(concept):
+ return f"{package_alias}->{concept.concept_ref}"
+ return concept.concept_ref
+
def _register_branch_outputs_with_graph_tracer(
self,
*,
@@ -685,3 +829,19 @@ class PipeParallel(PipeController):
self, *, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
+
+
+def _refused_field_names(*, exc: StuffFactoryError) -> set[str] | None:
+ """The top-level fields the combine's pydantic validation refused, or ``None`` when its cause says nothing."""
+ cause = exc.__cause__
+ if not isinstance(cause, ValidationError):
+ return None
+ refused_fields: set[str] = set()
+ for error_details in cause.errors():
+ location = error_details["loc"]
+ if not location:
+ # A refusal of the whole structure (a model-level validator) belongs to no field, so it can
+ # never be explained by a field's multiplicity: report the combine's own message beside it.
+ return None
+ refused_fields.add(str(location[0]))
+ return refused_fields
diff --git a/pipelex/pipe_machinery/pipe_abstract.py b/pipelex/pipe_machinery/pipe_abstract.py
index 8db607a4e..dae189dfa 100644
--- a/pipelex/pipe_machinery/pipe_abstract.py
+++ b/pipelex/pipe_machinery/pipe_abstract.py
@@ -9,6 +9,7 @@ from opentelemetry.trace import NonRecordingSpan, Span, SpanContext, SpanKind, S
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
from pipelex import log
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.core.concepts.concept import Concept
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
@@ -492,11 +493,19 @@ class PipeAbstract(ABC, BaseModel):
]
if optional_input_names:
msg += f" These optional inputs may be omitted: {', '.join(optional_input_names)}."
+ # Whether the caller left the inputs out of the request or an earlier step of their
+ # method did not produce them, the fault is in the caller's own request or method, and
+ # the message names only the pipe and its input names.
raise PipeRunInputsError(
message=msg,
run_mode=pipe_run_params.run_mode,
pipe_code=self.code,
missing_inputs=presence_scan.missing_names,
+ ).as_caller_fault(
+ user_action=UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail=f"Provide the missing required inputs of '{self.code}': {', '.join(presence_scan.missing_names)}.",
+ )
)
# The pipe is about to be lifted (skipped): per-pipe validation and resource checks are
@@ -514,6 +523,9 @@ class PipeAbstract(ABC, BaseModel):
try:
stuff.content.validate_resources()
except ValueError as exc:
+ # Not classified as the caller's fault, although the resource is the
+ # caller's: the check's message names the path as resolved on this host,
+ # which STRICT disclosure must not show, as `PipelineInputContentError`'s.
msg = f"Input '{variable_name}' of pipe '{self.code}' references an invalid resource: {exc}"
raise PipeRunInputsError(
message=msg,
diff --git a/pipelex/pipe_operators/compose/exceptions.py b/pipelex/pipe_operators/compose/exceptions.py
index e0b07f88c..02184c07d 100644
--- a/pipelex/pipe_operators/compose/exceptions.py
+++ b/pipelex/pipe_operators/compose/exceptions.py
@@ -1,4 +1,4 @@
-from pipelex.base_exceptions import PipelexError
+from pipelex.base_exceptions import ErrorDomain, PipelexError
class PipeComposeError(PipelexError):
@@ -6,7 +6,15 @@ class PipeComposeError(PipelexError):
class PipeComposeFactoryError(PipeComposeError):
- pass
+ """Raised when a ``PipeCompose`` has no template in template mode, or its template does not parse.
+
+ Raised only while the pipe is built from its blueprint, about that blueprint, so it is the author's to fix
+ (``input``) and bundle validation reports it as an item located on the pipe. Its messages name only the
+ author's own pipe, concepts and template text, so they are caller-facing copy kept under STRICT disclosure.
+ """
+
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
class ConstructFieldBlueprintTypeError(PipeComposeError, TypeError):
diff --git a/pipelex/pipe_operators/extract/exceptions.py b/pipelex/pipe_operators/extract/exceptions.py
index 4a0e9d670..6820db284 100644
--- a/pipelex/pipe_operators/extract/exceptions.py
+++ b/pipelex/pipe_operators/extract/exceptions.py
@@ -1,5 +1,13 @@
-from pipelex.base_exceptions import PipelexError
+from pipelex.base_exceptions import ErrorDomain, PipelexError
class PipeExtractFactoryError(PipelexError):
- pass
+ """Raised when a ``PipeExtract``'s input is neither an image nor a document.
+
+ Raised only while the pipe is built from its blueprint, about that blueprint, so it is the author's to fix
+ (``input``) and bundle validation reports it as an item located on the pipe. Its messages name only the
+ author's own pipe, concepts and template text, so they are caller-facing copy kept under STRICT disclosure.
+ """
+
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
diff --git a/pipelex/pipe_operators/extract/pipe_extract.py b/pipelex/pipe_operators/extract/pipe_extract.py
index 771c415b0..2583e3bb1 100644
--- a/pipelex/pipe_operators/extract/pipe_extract.py
+++ b/pipelex/pipe_operators/extract/pipe_extract.py
@@ -3,7 +3,6 @@ from typing import Any, Literal
from pydantic import model_validator
from typing_extensions import Self, override
-from pipelex.cogt.exceptions import ModelChoiceNotFoundError
from pipelex.cogt.extract.extract_input import ExtractInput
from pipelex.cogt.extract.extract_setting import ExtractModelChoice
from pipelex.cogt.models.model_deck_check import check_extract_choice_with_deck
@@ -55,11 +54,8 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
@override
def validate_inputs_static(self):
if self.extract_choice:
- try:
+ with self.locating_model_choice(field_name="model"):
check_extract_choice_with_deck(extract_choice=self.extract_choice)
- except ModelChoiceNotFoundError as exc:
- msg = f"Extract choice '{self.extract_choice}' was not found in the model deck"
- raise ValueError(msg) from exc
@override
def validate_inputs_with_library(self):
diff --git a/pipelex/pipe_operators/extract/pipe_extract_factory.py b/pipelex/pipe_operators/extract/pipe_extract_factory.py
index 0a38c2632..5ff2f6195 100644
--- a/pipelex/pipe_operators/extract/pipe_extract_factory.py
+++ b/pipelex/pipe_operators/extract/pipe_extract_factory.py
@@ -49,9 +49,10 @@ class PipeExtractFactory(PipeFactoryProtocol[PipeExtractBlueprint, PipeExtract])
document_stuff_name = input_name
else:
msg = (
- f"The input concept {input_requirement.concept.concept_ref} is not compatible "
- f"with the required concept {get_native_concept(native_concept=NativeConceptCode.IMAGE).concept_ref} or "
- f"{get_native_concept(native_concept=NativeConceptCode.DOCUMENT).concept_ref}"
+ f"The input '{input_name}' of PipeExtract '{pipe_code}' is a {input_requirement.concept.concept_ref}, "
+ f"which is not compatible with the required concept {get_native_concept(native_concept=NativeConceptCode.IMAGE).concept_ref} or "
+ f"{get_native_concept(native_concept=NativeConceptCode.DOCUMENT).concept_ref}. "
+ "Declare this input as an Image or a Document, or as a concept that refines one of them."
)
raise PipeExtractFactoryError(msg)
diff --git a/pipelex/pipe_operators/func/pipe_func.py b/pipelex/pipe_operators/func/pipe_func.py
index 50469254c..3e9e79ceb 100644
--- a/pipelex/pipe_operators/func/pipe_func.py
+++ b/pipelex/pipe_operators/func/pipe_func.py
@@ -226,6 +226,9 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
f" Inputs:\n{inputs_desc}\n\n"
f" Error: {type(exc).__name__}: {exc}"
)
+ # Not classified as the caller's fault: the function's own exception text can carry
+ # whatever the process holds (a path, a setting, a secret), so it stays redacted under
+ # STRICT disclosure.
raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
the_content = execution_result.content
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen.py b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
index 5506162c2..a63669305 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
@@ -65,7 +65,8 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
@override
def validate_inputs_static(self):
if self.img_gen_choice:
- check_img_gen_choice_with_deck(img_gen_choice=self.img_gen_choice)
+ with self.locating_model_choice(field_name="model"):
+ check_img_gen_choice_with_deck(img_gen_choice=self.img_gen_choice)
self._validate_param_support_against_model_rules()
# Guard-lint (D7): every reference to a declared-optional input must be guarded.
diff --git a/pipelex/pipe_operators/llm/exceptions.py b/pipelex/pipe_operators/llm/exceptions.py
index 3c1e19fa1..28bd6b179 100644
--- a/pipelex/pipe_operators/llm/exceptions.py
+++ b/pipelex/pipe_operators/llm/exceptions.py
@@ -1,5 +1,13 @@
-from pipelex.base_exceptions import PipelexError
+from pipelex.base_exceptions import ErrorDomain, PipelexError
class PipeLLMFactoryError(PipelexError):
- pass
+ """Raised when a ``PipeLLM``'s prompt template, or the system prompt it declares or inherits from its domain, does not parse.
+
+ Raised only while the pipe is built from its blueprint, about that blueprint, so it is the author's to fix
+ (``input``) and bundle validation reports it as an item located on the pipe. Its messages name only the
+ author's own pipe, concepts and template text, so they are caller-facing copy kept under STRICT disclosure.
+ """
+
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index dd7d72929..6da8a4343 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -8,6 +8,7 @@ from pipelex.base_exceptions import iter_cause_chain
from pipelex.cogt.exceptions import LLMCompletionError
from pipelex.cogt.llm.llm_setting import LLMModelChoice, LLMSetting, LLMSettingChoices
from pipelex.cogt.models.model_deck_check import check_llm_choice_with_deck
+from pipelex.cogt.models.model_reference import ModelReference
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.domains.domain import SpecialDomain
@@ -62,8 +63,14 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
@override
def validate_inputs_static(self):
if self.llm_choices:
- for llm_choice_ref in self.llm_choices.list_choice_references():
- check_llm_choice_with_deck(llm_choice=llm_choice_ref)
+ # Checked field by field, in declaration order, so a refusal names the field the author wrote
+ # the reference in: `for_text` comes from the blueprint's `model`, `for_object` from its
+ # `model_to_structure`. An inline setting table is not a reference and is not looked up.
+ for field_name, llm_choice in (("model", self.llm_choices.for_text), ("model_to_structure", self.llm_choices.for_object)):
+ if not isinstance(llm_choice, ModelReference):
+ continue
+ with self.locating_model_choice(field_name=field_name):
+ check_llm_choice_with_deck(llm_choice=llm_choice)
needed_inputs = self.needed_inputs()
required_variable_paths = self.required_variables()
@@ -269,6 +276,9 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
msg = f"Error generating text with LLM {location}: {error_details}"
raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
except ValidationError as exc:
+ # Not classified as the caller's fault, here or on the object path below, where an
+ # output the model could not fit to the structure surfaces as `LLMCompletionError`:
+ # whether a model's output fits depends on what the model produced this time.
location = self._format_error_location(pipe_run_params=pipe_run_params)
error_details = format_pydantic_validation_error(exc)
msg = f"Error generating text content in PipeLLM {location}: {error_details}"
diff --git a/pipelex/pipe_operators/llm/pipe_llm_factory.py b/pipelex/pipe_operators/llm/pipe_llm_factory.py
index c457a6411..b30807bca 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_factory.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_factory.py
@@ -1,5 +1,6 @@
from typing import Any
+import jinja2
from pydantic import ValidationError
from typing_extensions import override
@@ -16,11 +17,28 @@ from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipe_operators.llm.template_document_analyzer import TemplateDocumentAnalyzer
from pipelex.pipe_operators.shared.template_image_analyzer import TemplateImageAnalyzer
-from pipelex.tools.jinja2.exceptions import Jinja2TemplateSyntaxError
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
+def _describe_template_syntax_error(*, validation_error: ValidationError) -> str:
+ """Say where a prompt fails to parse, in words that owe nothing to the prompt.
+
+ A ``PipeLLMFactoryError`` is caller-facing, and the prompt it is about may not be the caller's: a pipe
+ with no system prompt of its own inherits its domain's, which a host's library may have declared.
+ Every layer between Jinja2 and this factory appends the template source to its message, and Jinja2's
+ own diagnosis quotes the token it stopped at (an unknown tag's name, an unexpected word), so no text
+ of the error can be passed on. The parser's line, counted within the prompt, is what locates the fault.
+ """
+ for error_details in validation_error.errors():
+ cause: BaseException | None = error_details.get("ctx", {}).get("error")
+ while cause is not None:
+ if isinstance(cause, jinja2.exceptions.TemplateSyntaxError):
+ return f"it does not parse at line {cause.lineno} of that prompt"
+ cause = cause.__cause__
+ return "it does not parse"
+
+
class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):
@classmethod
@override
@@ -48,9 +66,11 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):
category=TemplateCategory.LLM_PROMPT,
)
except ValidationError as exc:
+ # The system prompt is the pipe's own, or else its domain's: name the one that failed.
+ prompt_owner = "system prompt" if blueprint.system_prompt else f"system prompt of domain '{domain_code}', which it inherits,"
error_msg = (
- f"Template syntax error in system prompt for pipe '{pipe_code}'"
- f"in domain '{domain_code}': {exc}. Template source:\n{blueprint.system_prompt}"
+ f"Template syntax error in the {prompt_owner} for pipe '{pipe_code}' "
+ f"in domain '{domain_code}': {_describe_template_syntax_error(validation_error=exc)}."
)
raise PipeLLMFactoryError(error_msg) from exc
@@ -61,11 +81,10 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):
template=blueprint.prompt,
category=TemplateCategory.LLM_PROMPT,
)
- except Jinja2TemplateSyntaxError as exc:
- error_msg = (
- f"Template syntax error in user prompt for pipe '{pipe_code}' in domain '{domain_code}': "
- f"{exc}. Template source:\n{blueprint.prompt}"
- )
+ except ValidationError as exc:
+ # `TemplateBlueprint` reports a template that does not parse as a pydantic validation error.
+ diagnosis = _describe_template_syntax_error(validation_error=exc)
+ error_msg = f"Template syntax error in the prompt for pipe '{pipe_code}' in domain '{domain_code}': {diagnosis}."
raise PipeLLMFactoryError(error_msg) from exc
# Template analyzers read the slot grammar only, so they get the concept-spec projection.
diff --git a/pipelex/pipe_operators/pipe_operator.py b/pipelex/pipe_operators/pipe_operator.py
index e91c956e8..9d37febf9 100644
--- a/pipelex/pipe_operators/pipe_operator.py
+++ b/pipelex/pipe_operators/pipe_operator.py
@@ -1,10 +1,13 @@
from abc import abstractmethod
+from collections.abc import Generator
+from contextlib import contextmanager
from typing import TYPE_CHECKING, Generic, Literal, TypeVar, final
from typing_extensions import override
-from pipelex.cogt.exceptions import ModelNotFoundError, ModelWaterfallError
+from pipelex.cogt.exceptions import ModelChoiceNotFoundError, ModelNotFoundError, ModelWaterfallError
from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
@@ -26,6 +29,28 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
def class_name(self) -> str:
return self.__class__.__name__
+ @final
+ @contextmanager
+ def locating_model_choice(self, *, field_name: str) -> Generator[None, None, None]:
+ """Run a model deck check, raising its refusal located on this pipe and on the field that names the model.
+
+ Every operator that names a model checks it against the deck when it is built, through this one
+ wrapper, so an unknown model gives the same located ``PipeOperatorModelChoiceError`` whatever the
+ pipe type — which bundle validation turns into one ``unknown_model`` item. ``field_name`` is the
+ blueprint field the reference was written in (``model``, or ``model_to_structure`` on a
+ ``PipeLLM``), the key a fix rewrites.
+ """
+ try:
+ yield
+ except ModelChoiceNotFoundError as model_choice_error:
+ raise PipeOperatorModelChoiceError.make_from_model_choice_not_found(
+ model_choice_error=model_choice_error,
+ pipe_type=self.class_name,
+ pipe_code=self.code,
+ domain_code=self.domain_code,
+ field_name=field_name,
+ ) from model_choice_error
+
@final
@override
async def _live_run_pipe(
diff --git a/pipelex/pipe_operators/search/pipe_search.py b/pipelex/pipe_operators/search/pipe_search.py
index 050f439f1..219446bfa 100644
--- a/pipelex/pipe_operators/search/pipe_search.py
+++ b/pipelex/pipe_operators/search/pipe_search.py
@@ -3,7 +3,6 @@ from typing import TYPE_CHECKING, Any, Literal
from typing_extensions import override
from pipelex import log
-from pipelex.cogt.exceptions import ModelChoiceNotFoundError
from pipelex.cogt.models.model_deck_check import check_search_choice_with_deck
from pipelex.cogt.search.search_setting import SearchModelChoice
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
@@ -51,11 +50,8 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
@override
def validate_inputs_static(self):
if self.search_choice:
- try:
+ with self.locating_model_choice(field_name="model"):
check_search_choice_with_deck(search_choice=self.search_choice)
- except ModelChoiceNotFoundError as exc:
- msg = f"Search choice '{self.search_choice}' was not found in the model deck"
- raise ValueError(msg) from exc
# Guard-lint (D7): every reference to a declared-optional input must be guarded.
lint_optional_input_guards(
diff --git a/pipelex/pipe_operators/structure/pipe_structure.py b/pipelex/pipe_operators/structure/pipe_structure.py
index 599b60fef..322d34e56 100644
--- a/pipelex/pipe_operators/structure/pipe_structure.py
+++ b/pipelex/pipe_operators/structure/pipe_structure.py
@@ -55,7 +55,8 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
@override
def validate_inputs_static(self):
if self.llm_choice is not None and not isinstance(self.llm_choice, LLMSetting):
- check_llm_choice_with_deck(llm_choice=self.llm_choice)
+ with self.locating_model_choice(field_name="model"):
+ check_llm_choice_with_deck(llm_choice=self.llm_choice)
@override
def validate_inputs_with_library(self):
diff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.py
index 4b07d29bb..35381835f 100644
--- a/pipelex/pipe_run/dry_run_in_process.py
+++ b/pipelex/pipe_run/dry_run_in_process.py
@@ -21,6 +21,7 @@ from pipelex.interpreter_hub import get_library_manager, scoped_pipe_router
from pipelex.observer.observer_protocol import ObserverNoOp
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipe_run.exceptions import DryRunGraphNotProducedError
+from pipelex.pipe_run.located_failure import find_foreign_fault
from pipelex.pipe_run.pipe_router import PipeRouter
from pipelex.pipe_run.pipe_run import PipeRun
from pipelex.pipeline.execution_seams import prepare_pipe_job
@@ -64,6 +65,11 @@ async def best_effort_graph_spec(*, pipe_ref: str | None, library_id: str | None
pipe = get_library_manager().get_library(library_id=library_id).pipe_library.get_required_entry_pipe(pipe_code=pipe_ref)
return await dry_run_pipe_in_process(pipe=pipe, library_id=library_id)
except (PipelexError, FactoryException, ValueError) as graph_error:
+ # A foreign exception a pipe raised reaches here located as a PipelexError by the router:
+ # it is a programming bug, not a dry-run domain failure, so it propagates.
+ foreign_fault = find_foreign_fault(error=graph_error)
+ if foreign_fault is not None and not isinstance(foreign_fault, (FactoryException, ValueError)):
+ raise
log.warning(
f"{log_context}: graph dry-run of '{pipe_ref}' did not produce a graph "
f"({type(graph_error).__name__}: {graph_error}); returning validation result without graph_spec"
diff --git a/pipelex/pipe_run/exceptions.py b/pipelex/pipe_run/exceptions.py
index 9090d9e0f..4e1f803da 100644
--- a/pipelex/pipe_run/exceptions.py
+++ b/pipelex/pipe_run/exceptions.py
@@ -1,4 +1,10 @@
-from pipelex.base_exceptions import ErrorDomain, PipelexError
+from typing import Self
+
+from typing_extensions import override
+
+from pipelex.base_exceptions import ErrorDomain, ErrorReport, PipelexError, iter_cause_chain
+from pipelex.core.exceptions import DryRunFailureErrorData
+from pipelex.pipe_run.located_failure import build_located_failure_report, locate_failure_message
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -66,7 +72,19 @@ class StorageDeliveryError(DeliveryError):
class DryRunError(PipelexError):
- """Raised when a dry run fails due to missing inputs or other validation issues."""
+ """Raised when a dry run fails. The validation sweep raises it with one failure per pipe whose dry run
+ failed, located at the innermost failing pipe that is not allowed to fail, so a controller that failed
+ because a pipe it runs failed is reported once, at that pipe. Bundle validation reports each failure as its own ``dry_run``
+ item, with the error type ``DryRunError``, the pipe's code, domain and source, and a message that
+ keeps the failure's own text only when that text is caller-facing and otherwise names the failure's
+ title.
+
+ Raised elsewhere it may carry no failures, and validation then reports it as one item.
+ """
+
+ def __init__(self, message: str, *, failures: list[DryRunFailureErrorData] | None = None):
+ self.failures = failures or []
+ super().__init__(message)
class DryRunGraphNotProducedError(DryRunError):
@@ -81,6 +99,16 @@ class DryRunGraphNotProducedError(DryRunError):
class PipeRouterError(PipelexError):
+ """A pipe failed while running: the failure, located at the pipe where it happened.
+
+ The pipe router raises it around every failure of the pipe it runs, chained to the failure,
+ with the pipe's code and a snapshot of its stack taken where it failed. A failure that already
+ carries one keeps it as it rises through the routers of the controllers above, so the innermost
+ location is the one reported. Its report is its root fault's, located (see
+ `pipelex.pipe_run.located_failure`): a run whose pipe raised `StuffFactoryError` reports
+ `StuffFactoryError`, with a message naming the pipe and its path, never `PipeRouterError`.
+ """
+
def __init__(
self,
message: str,
@@ -96,3 +124,48 @@ class PipeRouterError(PipelexError):
self.pipe_stack = list(pipe_stack) # snapshot: the live stack unwinds after this error is raised
self.missing_inputs = missing_inputs
super().__init__(message)
+
+ @classmethod
+ def make_located(
+ cls,
+ *,
+ failure: PipelexError,
+ run_mode: PipeRunMode,
+ pipe_code: str,
+ output_name: str | None,
+ pipe_stack: list[str],
+ ) -> Self:
+ """Locate `failure` at `pipe_code`; the caller raises the result `from failure`."""
+ return cls(
+ message=locate_failure_message(failure=failure, pipe_code=pipe_code, pipe_stack=pipe_stack),
+ run_mode=run_mode,
+ pipe_code=pipe_code,
+ output_name=output_name,
+ pipe_stack=pipe_stack,
+ )
+
+ @override
+ def to_error_report(self) -> ErrorReport:
+ return build_located_failure_report(
+ wrapper=self,
+ own_report=super().to_error_report(),
+ pipe_code=self.pipe_code,
+ pipe_stack=self.pipe_stack,
+ )
+
+
+def find_failure_location(*, error: BaseException) -> PipeRouterError | None:
+ """Return the innermost `PipeRouterError` on `error`'s cause chain, `error` itself included.
+
+ It names the pipe where the failure happened and that pipe's stack snapshot; `None` means the
+ failure was never located, because it happened outside any routed pipe run. Like the root-fault
+ walk, it stops at the first exception that is not a `PipelexError`: a foreign exception raised
+ from an earlier located failure is a new failure, which the router locates where it happened.
+ """
+ location: PipeRouterError | None = None
+ for node in iter_cause_chain(error):
+ if not isinstance(node, PipelexError):
+ break
+ if isinstance(node, PipeRouterError):
+ location = node
+ return location
diff --git a/pipelex/pipe_run/located_failure.py b/pipelex/pipe_run/located_failure.py
new file mode 100644
index 000000000..c7248b944
--- /dev/null
+++ b/pipelex/pipe_run/located_failure.py
@@ -0,0 +1,162 @@
+"""A run failure, reported as its root fault at the pipe where it happened.
+
+When a pipe fails during a run, the error that reaches a surface sits under several wrappers: the
+pipe router's `PipeRouterError`, which knows the failing pipe and its stack, maybe a runtime bridge's
+`PipelexBridgeDispatchError`, and the runner's `PipelineExecutionError`. None of them is what went
+wrong. The report of such a failure is therefore built from its **root fault**, the innermost
+`PipelexError` of the cause chain, and only located by the wrappers:
+
+- the root fault stops at a foreign exception, whose stand-in is the fault, and an error raised from
+ one of its own class counts as the outer, more contextual one (see `find_root_fault`);
+- the identity (`error_type`, `title`, `type_uri`) is the root fault's, and so are its caller-facing
+ flag, its `validation_errors` and its `migration`;
+- the message names the failing pipe and its path from the entry pipe, then gives the root fault's
+ own message unaltered. Pipe codes are the caller's own names, so the message is caller-facing
+ exactly when the root fault's is;
+- the classification is the cause-chain enrichment's, floored at `runtime`, and when nothing on the
+ chain carries a user action, the fallback names the failing pipe.
+
+`ErrorReport` has no location field, so the location rides the message until the error contract
+gives it one. A root fault whose report was recovered across a transport boundary (a report
+carried by a `PipelexError`, the way a distributed worker's submitter carries it) is taken as it is:
+at the runner, with no location on the chain, it is reported unchanged, and a host router packs
+the root fault's own report with its location rather than a located report (see
+`PipeRouterProtocol._as_pipelex_failure`), so nothing is located twice.
+"""
+
+from pydantic import ValidationError
+
+from pipelex.base_exceptions import ErrorDomain, ErrorReport, PipelexError, PipelexUnexpectedError, iter_cause_chain
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
+from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
+
+# Joins the pipe codes of a failure's path from the entry pipe down to the pipe that failed.
+PIPE_PATH_SEPARATOR = " → "
+
+
+def find_root_fault(*, error: BaseException) -> PipelexError | None:
+ """Return the innermost `PipelexError` on `error`'s cause chain, `error` itself included.
+
+ That is the error that knows what went wrong: every `PipelexError` above it on the chain is a
+ wrapper that located it or carried it across a boundary. Two exceptions to "innermost": the walk
+ stops at the first exception that is not a `PipelexError`, since what caused a foreign exception
+ is that code's own affair and the `PipelexUnexpectedError` standing in for it is the fault; and
+ a `PipelexError` raised from one of its own class restates that fault with more context (an
+ item index, a remedy), so the outer one is kept. `None` when the chain starts with no
+ `PipelexError`.
+ """
+ root_fault: PipelexError | None = None
+ for node in iter_cause_chain(error):
+ if not isinstance(node, PipelexError):
+ break
+ if root_fault is not None and type(node) is type(root_fault):
+ continue
+ root_fault = node
+ return root_fault
+
+
+def find_foreign_fault(*, error: BaseException) -> BaseException | None:
+ """Return the non-Pipelex exception a run failure stands in for, or `None`.
+
+ That is the cause of a root fault that is a `PipelexUnexpectedError` standing in for a foreign
+ exception, the way the pipe router wraps one. A surface that sorts failures into its own domain
+ failures and programming bugs uses it to let the bugs propagate rather than report them as
+ the caller's.
+ """
+ root_fault = find_root_fault(error=error)
+ if not isinstance(root_fault, PipelexUnexpectedError):
+ return None
+ foreign_fault = root_fault.__cause__
+ if foreign_fault is None or isinstance(foreign_fault, PipelexError):
+ return None
+ return foreign_fault
+
+
+def compose_located_message(*, pipe_code: str, pipe_stack: list[str], message: str) -> str:
+ """Prefix `message` with the pipe that failed and, when it is nested, its path from the entry pipe.
+
+ An empty `pipe_stack` means the location is unknown, and the message is returned as it is.
+ """
+ if not pipe_stack:
+ return message
+ if len(pipe_stack) == 1:
+ return f"Pipe '{pipe_code}' failed: {message}"
+ return f"Pipe '{pipe_code}' failed ({PIPE_PATH_SEPARATOR.join(pipe_stack)}): {message}"
+
+
+def locate_failure_message(*, failure: PipelexError, pipe_code: str, pipe_stack: list[str]) -> str:
+ """The message a located wrapper of `failure` carries: its root fault's own message, located."""
+ root_fault = find_root_fault(error=failure) or failure
+ return compose_located_message(pipe_code=pipe_code, pipe_stack=pipe_stack, message=root_fault.to_error_report().message)
+
+
+def make_unexpected_failure(*, error: Exception) -> PipelexUnexpectedError:
+ """Stand a `PipelexUnexpectedError` in for an exception that is not a `PipelexError`.
+
+ Its message names the original class, and it is chained to the original so its traceback
+ survives. It is never caller-facing: a foreign exception's text can carry anything, a server
+ path or a secret included. A pydantic `ValidationError` keeps the readable rendering the runner
+ gives one.
+ """
+ detail = format_pydantic_validation_error(error) if isinstance(error, ValidationError) else (str(error) or repr(error))
+ unexpected_error = PipelexUnexpectedError(f"{type(error).__name__}: {detail}")
+ unexpected_error.__cause__ = error
+ unexpected_error.__suppress_context__ = True
+ return unexpected_error
+
+
+def _fallback_user_action(*, pipe_code: str, pipe_stack: list[str]) -> UserAction:
+ if pipe_stack:
+ detail = f"The run failed in pipe '{pipe_code}': the message gives the cause."
+ else:
+ detail = f"The run of '{pipe_code}' failed: the message gives the cause."
+ return UserAction(kind=UserActionKind.UNKNOWN, detail=detail)
+
+
+def _find_root_fault_below(*, wrapper: PipelexError) -> PipelexError | None:
+ """The root fault under `wrapper`, or `None` when it wraps no `PipelexError` or its chain loops back to it."""
+ cause = wrapper.__cause__
+ if cause is None:
+ return None
+ # A cyclic chain that reaches the wrapper again would make the root fault's report recurse
+ # into the wrapper's: report the wrapper as itself instead, as the base enrichment does.
+ if any(node is wrapper for node in iter_cause_chain(cause)):
+ return None
+ return find_root_fault(error=cause)
+
+
+def build_located_failure_report(
+ *,
+ wrapper: PipelexError,
+ own_report: ErrorReport,
+ pipe_code: str,
+ pipe_stack: list[str],
+) -> ErrorReport:
+ """Build the report of a located run failure from its root fault.
+
+ Args:
+ wrapper: The located wrapper whose report this is (a `PipeRouterError` or a
+ `PipelineExecutionError`).
+ own_report: The wrapper's own report, as `PipelexError.to_error_report` builds it: its own
+ identity, and the classification enriched from its cause chain.
+ pipe_code: The pipe that failed.
+ pipe_stack: That pipe's path from the entry pipe, ending with it. Empty when the location is
+ unknown, in which case the message is the root fault's, unlocated.
+
+ Returns:
+ The root fault's report, with the located message and the chain's classification.
+ """
+ root_fault = _find_root_fault_below(wrapper=wrapper)
+ identity_report = root_fault.to_error_report() if root_fault is not None else own_report
+ return identity_report.model_copy(
+ update={
+ "message": compose_located_message(pipe_code=pipe_code, pipe_stack=pipe_stack, message=identity_report.message),
+ "error_category": own_report.error_category,
+ "error_domain": own_report.error_domain or ErrorDomain.RUNTIME,
+ "retryable": own_report.retryable,
+ "user_action": own_report.user_action or _fallback_user_action(pipe_code=pipe_code, pipe_stack=pipe_stack),
+ "model": own_report.model,
+ "provider": own_report.provider,
+ "provider_metadata": own_report.provider_metadata,
+ }
+ )
diff --git a/pipelex/pipe_run/pipe_router_protocol.py b/pipelex/pipe_run/pipe_router_protocol.py
index bfccf8aa1..a0e735e41 100644
--- a/pipelex/pipe_run/pipe_router_protocol.py
+++ b/pipelex/pipe_run/pipe_router_protocol.py
@@ -1,11 +1,11 @@
from abc import abstractmethod
from typing import Protocol
-from pipelex.cogt.exceptions import CogtError
-from pipelex.core.pipes.exceptions import PipeRunError
+from pipelex.base_exceptions import PipelexError
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.observer.observer_protocol import ObserverProtocol, PayloadKey, PayloadType
-from pipelex.pipe_run.exceptions import PipeRouterError
+from pipelex.pipe_run.exceptions import PipeRouterError, find_failure_location
+from pipelex.pipe_run.located_failure import make_unexpected_failure
from pipelex.pipe_run.pipe_job import PipeJob
@@ -56,28 +56,65 @@ class PipeRouterProtocol(Protocol):
try:
pipe_output = await self._run_pipe_job(pipe_job)
- except (CogtError, PipeRunError) as exc:
+ except Exception as exc:
+ # Case (2), unbounded code: a pipe's run reaches user functions, plugin routers and
+ # provider SDKs. Nothing is swallowed: every failure is re-raised, located.
+ #
# Direct (non-Temporal) execution is a single pipeline-level attempt — there is no
- # retry here. This handler is error propagation, not retry: a PipeRunError wraps into
- # PipeRouterError (preserving the pipe location context); a raw CogtError is re-raised
- # as-is so its cause chain is preserved. Resilience is the Temporal track's job.
+ # retry here. This handler is error propagation, not retry, and it is the one place a
+ # pipe's failure gets its location: whatever the pipe's run raised leaves as a
+ # PipeRouterError naming this pipe and its stack, chained to the failure, whose report
+ # is the failure's root fault. Resilience is the Temporal track's job.
await self._after_failing_run(pipe_job, error=exc)
- if isinstance(exc, PipeRunError):
- raise PipeRouterError(
- message=exc.message,
- run_mode=pipe_job.pipe_run_params.run_mode,
- pipe_code=pipe_job.pipe.code,
- output_name=pipe_job.output_name,
- # run_pipe() has already popped the failed pipe's own frame; re-append
- # its code so the reported stack still ends with the pipe that failed.
- pipe_stack=[*pipe_job.pipe_run_params.pipe_stack, pipe_job.pipe.code],
- ) from exc
- raise
+ if find_failure_location(error=exc) is not None:
+ # A router below already located it: the innermost location is the one reported.
+ raise
+ failure = self._as_pipelex_failure(error=exc)
+ if failure is None:
+ raise
+ if find_failure_location(error=failure) is not None:
+ # The host rebuilt the location its transport carried: it is not located again, and the
+ # chain it built down to the recovered report is kept (a `from exc` would cut it off).
+ raise failure from failure.__cause__
+ raise PipeRouterError.make_located(
+ failure=failure,
+ run_mode=pipe_job.pipe_run_params.run_mode,
+ pipe_code=pipe_job.pipe.code,
+ output_name=pipe_job.output_name,
+ # run_pipe() has already popped the failed pipe's own frame; re-append
+ # its code so the reported stack still ends with the pipe that failed.
+ pipe_stack=[*pipe_job.pipe_run_params.pipe_stack, pipe_job.pipe.code],
+ ) from failure
await self._after_successful_run(pipe_job, pipe_output=pipe_output)
return pipe_output
+ def _as_pipelex_failure(self, *, error: Exception) -> PipelexError | None:
+ """Return the `PipelexError` this router locates for `error`, or `None` to let `error` through untouched.
+
+ A `PipelexError` stands for itself, and that includes one carrying a report recovered
+ across a transport boundary, whose report then becomes the located failure's root fault.
+ Any other exception is foreign to Pipelex: it is wrapped into a `PipelexUnexpectedError`
+ that names its class and is never caller-facing, so it no longer escapes the runner raw.
+
+ A host router overrides this for the exceptions its own transport raises, and returns `None`
+ for a control-flow exception its runtime must see unchanged, such as a cancellation. A
+ transport failure carrying a recovered report is converted according to what the far side
+ packed, which must never be a report that is already located, since this router would
+ locate it again:
+
+ - the root fault's own report alone (`find_root_fault(...).to_error_report()`): return a
+ `PipelexError` carrying it, and this router locates it at the pipe it ran;
+ - that report together with the location the far side found (`find_failure_location(...)`,
+ its `pipe_code` and `pipe_stack`): return `PipeRouterError.make_located(...)` over a
+ `PipelexError` carrying the report, chained to it. It already names its pipe, so this
+ router raises it untouched, and the report reads exactly as the local run's.
+ """
+ if isinstance(error, PipelexError):
+ return error
+ return make_unexpected_failure(error=error)
+
async def run_batch_branch(
self,
pipe_job: PipeJob,
diff --git a/pipelex/pipeline/bundle_validator.py b/pipelex/pipeline/bundle_validator.py
index b83c8ef73..59dbf35cc 100644
--- a/pipelex/pipeline/bundle_validator.py
+++ b/pipelex/pipeline/bundle_validator.py
@@ -27,16 +27,21 @@ activity later (D5).
"""
import time
+from contextvars import ContextVar
from enum import StrEnum
from typing import TYPE_CHECKING
from polyfactory.exceptions import FactoryException
from pydantic import BaseModel, ValidationError
+from typing_extensions import override
from pipelex import log
from pipelex.base_exceptions import PipelexError
from pipelex.cogt.content_generation.content_generator import ContentGenerator
from pipelex.config import get_config
+from pipelex.core.exceptions import DryRunFailureErrorData
+from pipelex.core.pipes.exceptions import caller_facing_refusal_text
+from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.interpreter_hub import (
clear_current_library,
get_current_library,
@@ -50,6 +55,8 @@ from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.observer.observer_protocol import ObserverNoOp
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipe_run.exceptions import DryRunError
+from pipelex.pipe_run.located_failure import find_foreign_fault, find_root_fault
+from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_router import PipeRouter
from pipelex.pipe_run.pipe_run import PipeRun
from pipelex.pipeline.execution_seams import acquire_library, prepare_pipe_job
@@ -96,6 +103,95 @@ class DryRunOutput(BaseModel):
pipe_ref: str
status: DryRunStatus
error_message: str | None = None
+ # On a FAILURE, the failure located at the innermost pipe that failed and is not allowed to fail,
+ # which is this pipe or one
+ # it runs, with a message the disclosure rule allows onto a verdict item.
+ failure: DryRunFailureErrorData | None = None
+
+
+# The foreign shapes a dry run can fail with (pydantic and polyfactory, while mock data is built) carry no
+# caller-facing flag, so their item names what failed rather than repeating their text.
+_MOCK_DATA_FAILURE_TEXT = "The dry run could not generate mock data for this pipe"
+
+
+class _FailingPipeRecorder:
+ """The pipes that failed during one pipe's dry run, each with the exception it left with.
+
+ A pipe the configuration allows to fail is never where a failure happened: its failure is tolerated,
+ so the failure is noted at the next pipe outward, the innermost one that is not.
+ """
+
+ def __init__(self, *, tolerated_pipe_refs: frozenset[str]) -> None:
+ self._tolerated_pipe_refs = tolerated_pipe_refs
+ self._failures: list[tuple[BaseException, PipeAbstract]] = []
+
+ def record(self, *, error: BaseException, pipe: PipeAbstract) -> None:
+ """Remember ``pipe`` as where ``error`` happened, unless a pipe it ran already failed with it or it may fail."""
+ if pipe.pipe_ref in self._tolerated_pipe_refs:
+ return
+ if self.find_failing_pipe(error=error) is None:
+ self._failures.append((error, pipe))
+
+ def find_failing_pipe(self, *, error: BaseException) -> PipeAbstract | None:
+ """The innermost pipe not allowed to fail that failed with ``error`` or with an error on its cause or context chain."""
+ failing_pipes = {id(recorded_error): pipe for recorded_error, pipe in self._failures}
+ seen: set[int] = set()
+ stack: list[BaseException] = [error]
+ while stack:
+ current = stack.pop()
+ if id(current) in seen:
+ continue
+ seen.add(id(current))
+ failing_pipe = failing_pipes.get(id(current))
+ if failing_pipe is not None:
+ return failing_pipe
+ for linked in (current.__cause__, current.__context__):
+ if linked is not None:
+ stack.append(linked)
+ return None
+
+
+# Scoped to one pipe's dry run by ``BundleValidator._classify_pipe``. A context variable rather than router
+# state, so the asyncio tasks a controller's fan-out spawns inherit it, and so concurrent sweeps never mix.
+_failing_pipe_recorder: ContextVar[_FailingPipeRecorder | None] = ContextVar("dry_run_failing_pipe_recorder", default=None)
+
+
+class _DryRunSweepRouter(PipeRouter):
+ """The sweep's in-process router: it runs pipes as ``PipeRouter`` does, and notes where each failure happened.
+
+ Every pipe a dry run reaches, the swept pipe and each sub-pipe a controller dispatches, goes through
+ this router, so the first pipe a failure leaves is the innermost one that failed (a pipe allowed to fail
+ aside, see `_FailingPipeRecorder`). The sweep reports
+ the failure there, once, rather than once more for every controller it made fail on its way out.
+ """
+
+ @override
+ async def run(self, pipe_job: PipeJob) -> PipeOutput:
+ try:
+ return await super().run(pipe_job)
+ except (PipelexError, ValidationError, FactoryException) as exc:
+ # The failures the sweep classifies (see `BundleValidator._run_and_classify`); anything else
+ # escapes the sweep unclassified, so there is no failure of it to locate.
+ recorder = _failing_pipe_recorder.get()
+ if recorder is not None:
+ recorder.record(error=exc, pipe=pipe_job.pipe)
+ raise
+
+
+def _dry_run_failure_text(*, error: Exception) -> str:
+ """The text a dry-run failure puts on its verdict item: the failure's own message only when it is caller-facing.
+
+ The text is its root fault's, the innermost ``PipelexError`` on the cause chain, since a wrapper
+ around it neither knows more nor authors caller-facing copy of its own; of two faults of the same
+ class the outer one, which restates the inner with more context, is the root, as a run failure's
+ report takes it (see ``find_root_fault``). A message that is not
+ caller-facing is replaced by the fault's title, because the verdict is caller-facing as a whole
+ and would otherwise carry a configuration or storage failure's internals past STRICT disclosure.
+ """
+ root_fault = find_root_fault(error=error)
+ if root_fault is None:
+ return _MOCK_DATA_FAILURE_TEXT
+ return caller_facing_refusal_text(refusal=root_fault)
class BundleValidator:
@@ -107,8 +203,9 @@ class BundleValidator:
# Keep the router instance (don't discard it inside PipeRun): the sweep installs it as the active
# router via scoped_pipe_router (see validate_pipes) so nested controller sub-pipes — which
# dispatch through get_pipe_router() — resolve THIS in-process router instead of the hub default.
- # Mirrors runtime_bridge.direct_orchestrator.DirectOrchestrator.execute.
- self._pipe_router = PipeRouter(observer=ObserverNoOp())
+ # Mirrors runtime_bridge.direct_orchestrator.DirectOrchestrator.execute. Being the sweep's own
+ # router, it also notes the innermost pipe each failure left (see `_DryRunSweepRouter`).
+ self._pipe_router = _DryRunSweepRouter(observer=ObserverNoOp())
self._pipe_run: PipeRunProtocol = PipeRun(pipe_router=self._pipe_router)
async def acquire_and_validate(
@@ -179,6 +276,7 @@ class BundleValidator:
library_id: str,
allow_signatures: bool = False,
caller_identity: CallerIdentity | None = None,
+ source_pipe_refs: frozenset[str] | None = None,
) -> dict[str, DryRunOutput]:
"""Classify each pipe ``SUCCESS / FAILURE / SKIPPED`` against an already-open library.
@@ -208,6 +306,13 @@ class BundleValidator:
caller is already in scope, and with none — a local CLI sweep — the dry runs state
``DRY_RUN_USER_ID`` and the event goes out under the fallback, as before.
+ ``source_pipe_refs`` names the pipes whose file a located failure may carry as its ``source``:
+ a validator of submitted content beside a host's library directories passes that content's
+ pipes, so a failure located at a pipe loaded from those directories never names a file on the
+ host. ``None`` lets every failure carry its pipe's file, as a local sweep of one's own library
+ does, and as submitted content validated beside directories that are the caller's own
+ (``library_dirs_are_callers``) does.
+
Returns the per-pipe status map (carrying allowed failures + skips). Raises ``DryRunError``
on ≥1 unexpected failure.
"""
@@ -217,6 +322,7 @@ class BundleValidator:
library_id=library_id,
allow_signatures=allow_signatures,
caller_identity=effective_caller_identity,
+ source_pipe_refs=source_pipe_refs,
)
async def _validate_pipes_for_caller(
@@ -226,6 +332,7 @@ class BundleValidator:
library_id: str,
allow_signatures: bool,
caller_identity: CallerIdentity | None,
+ source_pipe_refs: frozenset[str] | None,
) -> dict[str, DryRunOutput]:
"""The body of :meth:`validate_pipes`, run inside the caller's scope."""
start_time = time.time()
@@ -296,6 +403,7 @@ class BundleValidator:
execution_config=execution_config,
dry_run_pipeline_id=dry_run_pipeline_id,
caller_identity=caller_identity,
+ source_pipe_refs=source_pipe_refs,
)
# 4. Aggregate + report.
@@ -309,6 +417,7 @@ class BundleValidator:
execution_config: PipelineExecutionConfig,
dry_run_pipeline_id: str,
caller_identity: CallerIdentity | None,
+ source_pipe_refs: frozenset[str] | None,
) -> DryRunOutput:
"""Build the mock job and run the pipe DRY through the direct primitive; classify the outcome.
@@ -322,7 +431,39 @@ class BundleValidator:
that caller — the pipe run opens its caller scope from it — and ``DRY_RUN_USER_ID`` only
when the sweep belongs to nobody. It stores nothing either way: ``storage_scope`` stays
``DRY_RUN_STORAGE_SCOPE``.
+
+ A FAILURE carries its ``failure``, located at the innermost pipe that failed and is not allowed to
+ fail: the sweep's router notes where each failure happened, so a controller failing because a pipe
+ it runs failed reports that pipe, and ``_aggregate`` keeps the failure once. A failure met at a pipe
+ allowed to fail is reported at the pipe around it that is not, the one whose failure is unexpected.
"""
+ recorder = _FailingPipeRecorder(tolerated_pipe_refs=frozenset(get_config().inference.dry_run.allowed_to_fail_pipes))
+ recorder_token = _failing_pipe_recorder.set(recorder)
+ try:
+ return await self._run_and_classify(
+ pipe=pipe,
+ library_id=library_id,
+ execution_config=execution_config,
+ dry_run_pipeline_id=dry_run_pipeline_id,
+ caller_identity=caller_identity,
+ recorder=recorder,
+ source_pipe_refs=source_pipe_refs,
+ )
+ finally:
+ _failing_pipe_recorder.reset(recorder_token)
+
+ async def _run_and_classify(
+ self,
+ *,
+ pipe: PipeAbstract,
+ library_id: str,
+ execution_config: PipelineExecutionConfig,
+ dry_run_pipeline_id: str,
+ caller_identity: CallerIdentity | None,
+ recorder: _FailingPipeRecorder,
+ source_pipe_refs: frozenset[str] | None,
+ ) -> DryRunOutput:
+ """The body of :meth:`_classify_pipe`, run while ``recorder`` notes where failures happen."""
try:
pipe_job = await prepare_pipe_job(
pipe=pipe,
@@ -343,6 +484,11 @@ class BundleValidator:
)
await self._pipe_run.run(pipe_job)
except (PipelexError, ValidationError, FactoryException) as exc:
+ # A foreign exception a pipe raised arrives located as a PipelexError by the router: it
+ # is a programming bug, never the bundle's failure, and its text is never the caller's.
+ foreign_fault = find_foreign_fault(error=exc)
+ if foreign_fault is not None and not isinstance(foreign_fault, (ValidationError, FactoryException)):
+ raise
# SKIPPED = a cross-package unresolved dependency. Routing through PipeRun.run no longer
# surfaces a bare PipeNotFoundError: the run layer re-raises the original and the router may
# wrap it (PipeNotFoundError is a PipelexError, so the base catch reaches it). Walk the whole
@@ -353,7 +499,24 @@ class BundleValidator:
return DryRunOutput(pipe_code=pipe.code, pipe_ref=pipe.pipe_ref, status=DryRunStatus.SKIPPED, error_message=error_message)
formatted_error = format_pydantic_validation_error(exc) if isinstance(exc, ValidationError) else str(exc)
error_message = f"Dry run failed for pipe '{pipe.pipe_ref}': {formatted_error}"
- return DryRunOutput(pipe_code=pipe.code, pipe_ref=pipe.pipe_ref, status=DryRunStatus.FAILURE, error_message=error_message)
+ # A failure raised outside any routed pipe run (the mock-input build) is the swept pipe's own.
+ failing_pipe = recorder.find_failing_pipe(error=exc) or pipe
+ # Only a pipe of the content under validation names its file: one loaded from a host's own
+ # library directories would put a path on the host into a caller's verdict.
+ failing_pipe_source: str | None = None
+ if source_pipe_refs is None or failing_pipe.pipe_ref in source_pipe_refs:
+ failing_pipe_source = get_library_manager().get_pipe_source(failing_pipe.pipe_ref)
+ failure = DryRunFailureErrorData(
+ pipe_code=failing_pipe.code,
+ domain_code=failing_pipe.domain_code,
+ # Compatibility boundary: injected managers written against the previous protocol may still
+ # return ``Path``. Normalize before assigning to the string-only model.
+ source=str(failing_pipe_source) if failing_pipe_source is not None else None,
+ message=f"Pipe '{failing_pipe.code}' failed its dry run: {_dry_run_failure_text(error=exc)}",
+ )
+ return DryRunOutput(
+ pipe_code=pipe.code, pipe_ref=pipe.pipe_ref, status=DryRunStatus.FAILURE, error_message=error_message, failure=failure
+ )
log.verbose(f"✅ Pipe '{pipe.pipe_ref}' dry run completed successfully")
return DryRunOutput(pipe_code=pipe.code, pipe_ref=pipe.pipe_ref, status=DryRunStatus.SUCCESS)
@@ -362,7 +525,8 @@ class BundleValidator:
"""Tally outcomes; raise one ``DryRunError`` listing **every** unexpected failure, else return.
A single ``allowed_to_fail`` match on the namespaced ``pipe_ref`` (the dict key). Collect-all,
- not first-failure-abort: every non-allowed failure is reported in one error.
+ not first-failure-abort: every non-allowed failure is reported in one error, as one located
+ failure per failing pipe (see :meth:`_located_failures`).
"""
allowed_to_fail_pipes = get_config().inference.dry_run.allowed_to_fail_pipes
@@ -389,11 +553,35 @@ class BundleValidator:
f"{skipped_count} skipped, {len(allowed_to_fail_pipes)} allowed to fail, in {time.time() - start_time:.2f} seconds",
)
if unexpected_failures:
- details = "\n".join(f"'{pipe_ref}': {results[pipe_ref]}" for pipe_ref in unexpected_failures)
- msg = f"Dry run failed with {len(unexpected_failures)} unexpected pipe failure(s):\n{details}"
- raise DryRunError(msg)
+ failures = cls._located_failures(unexpected_failures=unexpected_failures)
+ details = "\n".join(f"- {failure.message}" for failure in failures)
+ msg = f"Dry run failed for {len(failures)} pipe(s):\n{details}"
+ raise DryRunError(msg, failures=failures)
return results
+ @classmethod
+ def _located_failures(cls, *, unexpected_failures: dict[str, DryRunOutput]) -> list[DryRunFailureErrorData]:
+ """One failure per failing pipe, in sweep order.
+
+ Each failure is located at the innermost pipe that failed and is not allowed to fail, so a controller that failed because
+ a pipe it runs failed carries that pipe's failure; the failures are then kept once per pipe.
+ When a pipe's failure reaches the list both through its own dry run and through a controller's,
+ its own is kept, since it names the failure as that pipe met it. The pipe is the key rather than
+ the message, because one fault's message differs with the run that met it (the output name a
+ controller gives the pipe appears in it), and keying on it would report that fault twice.
+ """
+ failures_by_pipe_ref: dict[str, DryRunFailureErrorData] = {}
+ for swept_pipe_ref, dry_run_output in unexpected_failures.items():
+ failure = dry_run_output.failure or DryRunFailureErrorData(
+ pipe_code=dry_run_output.pipe_code,
+ message=f"Pipe '{dry_run_output.pipe_code}' failed its dry run",
+ )
+ failing_pipe_ref = f"{failure.domain_code}.{failure.pipe_code}" if failure.domain_code else swept_pipe_ref
+ is_own_failure = failing_pipe_ref == swept_pipe_ref
+ if failing_pipe_ref not in failures_by_pipe_ref or is_own_failure:
+ failures_by_pipe_ref[failing_pipe_ref] = failure
+ return list(failures_by_pipe_ref.values())
+
@classmethod
def _root_cause_is(cls, *, exc: BaseException, exc_type: type[BaseException]) -> bool:
"""Return True if ``exc`` itself, or any link in its ``__cause__`` / ``__context__`` chain, is ``exc_type``.
diff --git a/pipelex/pipeline/exceptions.py b/pipelex/pipeline/exceptions.py
index f0bf271f7..6054932af 100644
--- a/pipelex/pipeline/exceptions.py
+++ b/pipelex/pipeline/exceptions.py
@@ -1,8 +1,19 @@
+import re
+from collections.abc import Collection
+from typing import NamedTuple, Self, TypeVar
+
from typing_extensions import override
-from pipelex.base_exceptions import ErrorDomain, ErrorReport, PipelexError, PipelexUnexpectedError
+from pipelex.base_exceptions import ErrorDomain, ErrorReport, PipelexError, PipelexUnexpectedError, ValidationErrorItem
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
-from pipelex.core.exceptions import PipeFactoryErrorData, PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
+from pipelex.core.exceptions import (
+ DryRunFailureErrorData,
+ PipeFactoryErrorData,
+ PipelexBundleBlueprintValidationErrorData,
+ PipesAndConceptValidationErrorData,
+)
+from pipelex.pipe_run.exceptions import find_failure_location
+from pipelex.pipe_run.located_failure import build_located_failure_report, locate_failure_message
from pipelex.pipeline.validation_errors import build_validation_error_items
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -12,13 +23,22 @@ class PipeExecutionError(PipelexError):
class PipelineExecutionError(PipelexError):
- """Wraps any failure that occurred while running a pipeline.
-
- Being a pure wrapper, it has no authoritative classification of its own:
- ``to_error_report()`` inherits ``error_domain`` / ``user_action`` from the
- wrapped ``__cause__`` chain (so a categorized ``CogtError`` keeps its
- ``WAIT_AND_RETRY`` / ``CHECK_BILLING`` action), and only falls back to a
- generic RUNTIME / UNKNOWN classification when the cause chain surfaces none.
+ """Wraps any failure that occurred while running a pipeline, reported as its root fault.
+
+ The runner raises it around every failure that happens once the run's job exists, so a host
+ catches one class whatever went wrong. Its ``pipe_code`` and ``pipe_stack`` name the pipe where
+ the failure happened and its path from the entry pipe, taken from the innermost location on the
+ cause chain (the ``PipeRouterError`` of the pipe that failed). When the failure was never located
+ (it happened outside any routed pipe run, or it crossed a transport boundary as a report that
+ already names its pipe), ``pipe_code`` is the entry pipe and ``pipe_stack`` is empty.
+
+ Its report is not its own. ``to_error_report()`` takes the identity (``error_type``, ``title``,
+ ``type_uri``), the message and the caller-facing flag of the root fault, the innermost
+ ``PipelexError`` on the cause chain, or the report such an error recovered across a transport
+ boundary; the message is prefixed with the failing pipe and its path. The classification is
+ inherited from the cause chain (so a categorized ``CogtError`` keeps its ``WAIT_AND_RETRY`` /
+ ``CHECK_BILLING`` action), with a ``RUNTIME`` floor and, when nothing on the chain advises an
+ action, a fallback that names the failing pipe. See ``pipelex.pipe_run.located_failure``.
"""
def __init__(
@@ -35,17 +55,44 @@ class PipelineExecutionError(PipelexError):
self.pipe_stack = list(pipe_stack) # snapshot: the live stack unwinds after this error is raised
super().__init__(message)
+ @classmethod
+ def make_for_run_failure(
+ cls,
+ *,
+ failure: PipelexError,
+ run_mode: PipeRunMode,
+ entry_pipe_code: str,
+ output_name: str | None,
+ ) -> Self:
+ """Wrap a run's `failure`, located where it happened; the caller raises the result `from failure`.
+
+ The location is the innermost ``PipeRouterError`` on the failure's cause chain, never the
+ live pipe stack, which has unwound by the time the runner sees the failure.
+ """
+ location = find_failure_location(error=failure)
+ pipe_code: str
+ pipe_stack: list[str]
+ if location is None:
+ pipe_code = entry_pipe_code
+ pipe_stack = []
+ else:
+ pipe_code = location.pipe_code
+ pipe_stack = location.pipe_stack
+ return cls(
+ message=locate_failure_message(failure=failure, pipe_code=pipe_code, pipe_stack=pipe_stack),
+ run_mode=run_mode,
+ pipe_code=pipe_code,
+ output_name=output_name,
+ pipe_stack=pipe_stack,
+ )
+
@override
def to_error_report(self) -> ErrorReport:
- # The report is first enriched from the __cause__ chain; the generic
- # RUNTIME / UNKNOWN values are only a floor, applied when the cause
- # surfaced nothing — never overriding a categorized cause action.
- report = super().to_error_report()
- return report.model_copy(
- update={
- "error_domain": report.error_domain or ErrorDomain.RUNTIME,
- "user_action": report.user_action or UserAction(kind=UserActionKind.UNKNOWN, detail="Check pipe_stack to identify which pipe failed"),
- }
+ return build_located_failure_report(
+ wrapper=self,
+ own_report=super().to_error_report(),
+ pipe_code=self.pipe_code,
+ pipe_stack=self.pipe_stack,
)
@@ -77,7 +124,7 @@ def _summarize_bundle_validation_message(
blueprint_errors: list[PipelexBundleBlueprintValidationErrorData],
factory_errors: list[PipeFactoryErrorData],
pipe_validation_errors: list[PipesAndConceptValidationErrorData],
- dry_run_error_message: str | None,
+ dry_run_failures: list[DryRunFailureErrorData],
raw_message: str,
) -> str:
"""Compose a clean, author-facing top-line summary of a bundle-validation failure (disease C).
@@ -95,14 +142,13 @@ def _summarize_bundle_validation_message(
failure (TOML syntax, an empty blueprint, a bundle elaborator) whose raw message is the
authoritative description and the sole diagnostic. Reads only the ``message`` field off each
error-data model — no fix planning — so it is cheap enough to run in ``__init__``. Ordering
- mirrors ``build_validation_error_items`` (blueprint → factory → pipe/concept → dry-run residual)
- so the "first" message is the same item the structured surfaces list first.
+ mirrors ``build_validation_error_items`` (blueprint → factory → pipe/concept → dry run) so the
+ "first" message is the same item the structured surfaces list first.
"""
item_messages = [error.message for error in blueprint_errors]
item_messages += [error.message for error in factory_errors]
item_messages += [error.message for error in pipe_validation_errors]
- if not item_messages and dry_run_error_message:
- item_messages = [dry_run_error_message]
+ item_messages += [failure.message for failure in dry_run_failures]
if not item_messages:
return raw_message
first_message = item_messages[0]
@@ -111,15 +157,73 @@ def _summarize_bundle_validation_message(
return f"{len(item_messages)} validation errors (first: {first_message})"
+# The error-data models that carry a ``source`` beside their ``message``.
+_SourcedErrorData = TypeVar(
+ "_SourcedErrorData", PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData, DryRunFailureErrorData
+)
+
+# A withheld name counts only standing on its own: not preceded by a character that could continue a path, a URI
+# or an identifier, and not followed by one. So a host file spelled ``notices.mthds`` is not found inside the
+# caller's ``api://notices.mthds`` or a dependency's ``tide_notices.mthds``.
+_NAME_START_GUARD = r"(?<![\w.\-/\\:])"
+_NAME_END_GUARD = r"(?![\w.\-/\\])"
+
+
+class _FileWithholding(NamedTuple):
+ """The names a verdict must not carry, and what a message reads in their place."""
+
+ names: frozenset[str]
+ pattern: re.Pattern[str]
+ placeholder: str
+
+ @classmethod
+ def make_from_names(cls, *, names: Collection[str], placeholder: str) -> "_FileWithholding":
+ if not names:
+ # Nothing to withhold: a pattern that never matches, where an empty alternation would match everywhere.
+ return cls(names=frozenset(), pattern=re.compile(r"(?!)"), placeholder=placeholder)
+ # Longest first, so a name that extends another is replaced whole.
+ alternatives = "|".join(re.escape(name) for name in sorted(set(names), key=len, reverse=True))
+ pattern = re.compile(f"{_NAME_START_GUARD}(?:{alternatives}){_NAME_END_GUARD}")
+ return cls(names=frozenset(names), pattern=pattern, placeholder=placeholder)
+
+ def withheld_text(self, *, text: str) -> str:
+ return self.pattern.sub(lambda _match: self.placeholder, text)
+
+ def withheld_errors(self, *, errors: list[_SourcedErrorData]) -> list[_SourcedErrorData]:
+ """The error data without a withheld name as its ``source``, its ``field_path`` or in its ``message``.
+
+ A pipe-validation error located from the pipe-source map carries its file as its ``field_path`` too
+ (``categorize_pipe_validation_with_libraries_error``), so a withheld file leaves that field empty.
+ """
+ withheld: list[_SourcedErrorData] = []
+ for error in errors:
+ update: dict[str, str | None] = {
+ "source": None if error.source in self.names else error.source,
+ "message": self.withheld_text(text=error.message),
+ }
+ if isinstance(error, PipesAndConceptValidationErrorData) and error.field_path in self.names:
+ update["field_path"] = ""
+ withheld.append(error.model_copy(update=update))
+ return withheld
+
+
class ValidateBundleError(PipelexError):
- """Raised when bundle validation fails.
+ """Raised when a bundle is refused while it is loaded or validated: the invalid verdict, carrying one
+ structured item per refusal in ``validation_errors``. Every refusal of the bundle itself becomes one —
+ every parser error, categorized or not, the factory and pipe-validation errors, one ``dry_run`` item
+ per pipe whose dry run failed, an unknown model (``unknown_model``) and any other refusal of the
+ caller's input — each keeping the locators its raise site had, such as a TOML syntax error's ``line``
+ and ``column`` and an unresolved concept's ``declared_concepts``, while a failure of the tool or its
+ environment propagates as a no-verdict fault instead. A run raises it too, when the bundle it was given
+ is refused while it loads, before any pipe runs: the same verdict, with the same items, that validating
+ the bundle gives.
This error aggregates validation errors from different stages:
- Blueprint validation errors (from interpreter)
- Pipe factory errors (from PipeFactoryError exceptions, e.g., missing concepts)
- Pipe validation errors (from PipeValidationError exceptions)
- Pipe/Concept instantiation errors (from Pydantic ValidationError during factory instantiation)
- - Dry run errors (the residual message, projected as one ``dry_run`` item by the shared builder)
+ - Dry run failures (one per failing pipe, each projected as its own ``dry_run`` item)
Signatures are **never** an error (D-B): an unimplemented ``PipeSignature`` reached during
validation is a runnability fact (reported library-wide via the report's ``pending_signatures``
@@ -131,7 +235,9 @@ class ValidateBundleError(PipelexError):
error_domain = ErrorDomain.INPUT
user_action = UserAction(
kind=UserActionKind.CHANGE_INPUT,
- detail="Check the validation_errors array for specific issues",
+ # The next step points at the items' own: each item says what is wrong and where, and carries a
+ # suggested fix when one can be derived, so the top level says to follow them rather than to go read them.
+ detail="Edit the bundle as each validation error says: apply its suggested fix where it has one, after confirming an unsafe one",
)
# Bundle-validation messages describe faults in the caller's own bundle —
# caller-facing copy, kept verbatim under STRICT disclosure.
@@ -144,7 +250,7 @@ class ValidateBundleError(PipelexError):
pipe_factory_errors: list[PipeFactoryErrorData] | None = None,
pipe_validation_errors: list[PipesAndConceptValidationErrorData] | None = None,
pipe_concept_instantiation_errors: list[PipesAndConceptValidationErrorData] | None = None,
- dry_run_error_message: str | None = None,
+ dry_run_failures: list[DryRunFailureErrorData] | None = None,
):
self.pipelex_bundle_blueprint_validation_errors = pipelex_bundle_blueprint_validation_errors or []
self.pipe_factory_errors = pipe_factory_errors or []
@@ -154,7 +260,8 @@ class ValidateBundleError(PipelexError):
# TODO: Currently not caught, but structure is prepared for future implementation
self.pipe_concept_instantiation_errors = pipe_concept_instantiation_errors or []
- self.dry_run_error_message = dry_run_error_message
+ # One located failure per pipe whose dry run failed (see ``BundleValidator``).
+ self.dry_run_failures = dry_run_failures or []
# Disease C: the top-line ``message`` is often a leaky ``str(pydantic ValidationError)``
# (``Value errors: '<field>': Value error, …``). Replace it at the source with a clean
@@ -168,11 +275,42 @@ class ValidateBundleError(PipelexError):
blueprint_errors=self.pipelex_bundle_blueprint_validation_errors,
factory_errors=self.pipe_factory_errors,
pipe_validation_errors=self.pipe_validation_error_data,
- dry_run_error_message=self.dry_run_error_message,
+ dry_run_failures=self.dry_run_failures,
raw_message=message,
)
)
+ def withholding_files(self, *, withheld_files: Collection[str], placeholder: str) -> "ValidateBundleError":
+ """This verdict with the given files taken out of every channel that could name them.
+
+ An item whose ``source`` is one of ``withheld_files`` carries no ``source``, an item whose ``field_path``
+ is one carries none either, and every message, the
+ items' and the verdict's own, reads ``placeholder`` where it named one of them standing on its own,
+ never inside a longer name. Everything else is kept, the items' locators included, so it is the same
+ answer about the same bundle. Every channel the constructor takes is carried here: a channel added to
+ it must be added here too, which ``test_validate_bundle_error_withholding`` pins. A validator of
+ submitted content uses it to keep the files of the host's own library directories, paths on the host,
+ out of a verdict that STRICT disclosure hands the caller verbatim.
+
+ Args:
+ withheld_files: Every spelling of every file the verdict must not name.
+ placeholder: What a message reads where it named one of them.
+
+ Returns:
+ A new verdict; this one is left as it is.
+ """
+ withholding = _FileWithholding.make_from_names(names=withheld_files, placeholder=placeholder)
+ return ValidateBundleError(
+ message=withholding.withheld_text(text=self.message),
+ pipelex_bundle_blueprint_validation_errors=withholding.withheld_errors(errors=self.pipelex_bundle_blueprint_validation_errors),
+ pipe_factory_errors=[
+ error.model_copy(update={"message": withholding.withheld_text(text=error.message)}) for error in self.pipe_factory_errors
+ ],
+ pipe_validation_errors=withholding.withheld_errors(errors=self.pipe_validation_errors),
+ pipe_concept_instantiation_errors=withholding.withheld_errors(errors=self.pipe_concept_instantiation_errors),
+ dry_run_failures=withholding.withheld_errors(errors=self.dry_run_failures),
+ )
+
@property
def pipe_validation_error_data(self) -> list[PipesAndConceptValidationErrorData]:
"""Backwards compatibility: combine pipe validation and instantiation errors.
@@ -182,40 +320,42 @@ class ValidateBundleError(PipelexError):
# TODO: refactor so we don't need this anymore?
return self.pipe_validation_errors + self.pipe_concept_instantiation_errors
- @override
- def to_error_report(self) -> ErrorReport:
- """Attach the structured ``validation_errors`` list onto the base report.
-
- ``super().to_error_report()`` builds the report and enriches it from the
- ``__cause__`` chain; this override then attaches the per-error structured
- list — the same items the agent CLI emits, via the shared
- ``build_validation_error_items`` builder — so the API 422 problem
- document carries machine-mappable diagnostics. The list is set to
- ``None`` when empty so it drops out of the ``exclude_none`` wire
- projection (and the round-trip stays identical to a plain report).
-
- The pipe-validation arm uses :attr:`pipe_validation_error_data` (pipe
- validation **plus** pipe/concept instantiation errors) so the
- instantiation category is not silently dropped from the wire. The
- ``dry_run_error_message`` channel is a single message, not per-error data
- with identity fields, so the shared builder projects it as one
- ``dry_run``-category item **only** when no categorized error has data.
- Finally ``fallback_message=self.message`` is passed so a parse-level
- failure (TOML syntax, an empty blueprint, a bundle elaborator) — which
- carries only a message — still surfaces one ``blueprint_validation``
- residual item. Together these make the structured-info invariant
+ def validation_error_items(self) -> list[ValidationErrorItem]:
+ """Project every channel this verdict carries into typed wire items, via the shared builder.
+
+ The one projection behind the API report (:meth:`to_error_report`), the agent CLI's
+ ``validation_errors`` array and ``pipelex fix``, so no surface can drop a channel another
+ keeps. The pipe-validation arm uses :attr:`pipe_validation_error_data` (pipe validation
+ **plus** pipe/concept instantiation errors) so the instantiation category is not silently
+ dropped. Each dry-run failure becomes its own located ``dry_run`` item. Finally
+ ``fallback_message=self.message`` is passed so a parse-level failure (TOML syntax, an empty
+ blueprint, a bundle elaborator) — which carries only a message — still surfaces one
+ ``blueprint_validation`` residual item. Together these make the structured-info invariant
**total**: an invalid verdict never rides a bare ``detail`` with an empty
``validation_errors[]``.
"""
- report = super().to_error_report()
- validation_error_items = build_validation_error_items(
+ return build_validation_error_items(
blueprint_errors=self.pipelex_bundle_blueprint_validation_errors,
factory_errors=self.pipe_factory_errors,
pipe_validation_errors=self.pipe_validation_error_data,
- dry_run_error_message=self.dry_run_error_message,
+ dry_run_failures=self.dry_run_failures,
fallback_message=self.message,
)
- return report.model_copy(update={"validation_errors": validation_error_items or None})
+
+ @override
+ def to_error_report(self) -> ErrorReport:
+ """Attach the structured ``validation_errors`` list onto the base report.
+
+ ``super().to_error_report()`` builds the report and enriches it from the
+ ``__cause__`` chain; this override then attaches the per-error structured
+ list from :meth:`validation_error_items` — the same items the agent CLI
+ emits — so the API problem document carries machine-mappable diagnostics.
+ The list is set to ``None`` when empty so it drops out of the
+ ``exclude_none`` wire projection (and the round-trip stays identical to a
+ plain report).
+ """
+ report = super().to_error_report()
+ return report.model_copy(update={"validation_errors": self.validation_error_items() or None})
class PipeIOContractError(PipelexError):
diff --git a/pipelex/pipeline/execution_seams.py b/pipelex/pipeline/execution_seams.py
index 65ad67641..508c161af 100644
--- a/pipelex/pipeline/execution_seams.py
+++ b/pipelex/pipeline/execution_seams.py
@@ -7,10 +7,11 @@ Two pure-ish building blocks composed by both the single-run wrapper
- :func:`acquire_library` — set the current library, open it, and load
directories + blueprints into it. Owns its own load-failure teardown (open,
then load under a ``try``; on failure restore the caller's outer
- current-library and tear the just-opened library down). Returns the
- ``library_id`` plus the bundle's qualified ``main_pipe`` (when an
- ``mthds_contents`` bundle declares one), leaving pipe resolution to the
- caller.
+ current-library and tear the just-opened library down). A refusal of the
+ bundle while it loads is the ``ValidateBundleError`` verdict, as on the
+ validate path. Returns the ``library_id`` plus the bundle's qualified
+ ``main_pipe`` (when an ``mthds_contents`` bundle declares one), leaving pipe
+ resolution to the caller.
- :func:`prepare_pipe_job` — build a :class:`PipeJob` against an already-open
library: working memory (user inputs, mock inputs, data-url normalization),
run params, job metadata, and the library crate. **Pure**: no pipeline-manager
@@ -19,6 +20,7 @@ Two pure-ish building blocks composed by both the single-run wrapper
"""
from collections.abc import Sequence
+from contextlib import AbstractContextManager, nullcontext
from pathlib import Path
from typing import TYPE_CHECKING
@@ -45,6 +47,7 @@ from pipelex.pipe_run.pipe_run_params import VariableMultiplicity
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.pipeline.blueprint_selection import select_primary_blueprint
from pipelex.pipeline.input_normalizer import normalize_data_urls_to_storage
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error, withholding_host_library_files
from pipelex.system.configuration.configs import PipelineExecutionConfig
from pipelex.system.job_metadata import JobMetadata, OtelContext, RunMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -63,6 +66,7 @@ def acquire_library(
library_dirs: list[str] | None = None,
mthds_contents: list[str] | None = None,
bundle_uris: list[str] | None = None,
+ library_dirs_are_callers: bool = False,
) -> tuple[str, str | None]:
"""Set the current library, open it, and load dirs + blueprints into it.
@@ -72,6 +76,25 @@ def acquire_library(
down before re-raising — so a failed load never leaks a ``Library``. On
success the library is left open and current for the caller to use.
+ **A refusal of the bundle is the validation verdict.** The parse of ``mthds_contents`` and their
+ load run inside ``translate_to_validate_bundle_error``, the one translation the validate path
+ uses, so a run on an invalid bundle is refused before any pipe runs with the ``ValidateBundleError``
+ and the same located ``validation_errors`` validating that bundle gives, instead of the raw class
+ of whichever check refused it. What the translation leaves raw stays raw: a fault of the tool or
+ its environment, a security refusal, and a ``PipeNotFoundError``. No source is threaded onto the
+ contents here, so their items carry none: a hosted run request names no file, and giving a
+ blueprint a source also changes where its address-based dependencies are searched for. A package
+ the bundle depends on by address still loads from its install directory inside this translation,
+ exactly as on the in-memory validate path, and its refusals name its bundles by the package's
+ address and their path inside it, never by that directory. Beside a host's library directories,
+ the verdict names none of their files either (``withholding_host_library_files``).
+
+ ``library_dirs_are_callers`` says whose ``library_dirs`` are. On a local run they are the
+ caller's own (a CLI's ``-L``, the directory of the bundle being run), so a refusal while loading
+ them is the caller's invalid bundle too, reported as ``validate`` reports it. On a host they are
+ the host's (installed libraries, a temporary directory of shipped Python): a fault there is not
+ the caller's to fix and its paths are not the caller's to read, so by default they load untranslated.
+
Returns the ``library_id`` and the bundle's qualified ``main_pipe`` ref
(``domain.pipe_code``) when an ``mthds_contents`` bundle declares one, else
``None``. Pipe resolution is the caller's responsibility.
@@ -91,31 +114,40 @@ def acquire_library(
log.verbose(f"Loading libraries from {len(effective_dirs)} directory(ies) ({source_label}):")
for index_dir, dir_path in enumerate(effective_dirs):
log.verbose(f" [{index_dir + 1}] {dir_path}")
- library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
+ library_dirs_translation: AbstractContextManager[None] = (
+ translate_to_validate_bundle_error() if library_dirs_are_callers else nullcontext()
+ )
+ with library_dirs_translation:
+ library_manager.load_libraries(library_id=library_id, library_dirs=effective_dirs)
else:
log.verbose(f"No library directories to load ({source_label})")
qualified_main_pipe: str | None = None
if mthds_contents:
- all_blueprints = [MthdsParser.make_pipelex_bundle_blueprint(mthds_content=content) for content in mthds_contents]
-
- # Filter out blueprints whose URIs are already loaded (e.g. via PIPELEXPATH).
- blueprints_to_load: list[PipelexBundleBlueprint] = list(all_blueprints)
- if bundle_uris:
- current_library = library_manager.get_library(library_id=library_id)
- blueprints_to_load = []
- for blueprint, uri in zip(all_blueprints, bundle_uris, strict=True):
- try:
- resolved_uri = Path(uri).resolve()
- except (OSError, RuntimeError):
- resolved_uri = Path(uri)
- if resolved_uri in current_library.loaded_mthds_paths:
- log.verbose(f"Bundle '{uri}' already loaded from library directories, skipping")
- else:
- blueprints_to_load.append(blueprint)
-
- if blueprints_to_load:
- library_manager.load_from_blueprints(library_id=library_id, blueprints=blueprints_to_load)
+ # Beside a host's library directories, the verdict names none of their files, which are paths on the host.
+ host_library_withholding: AbstractContextManager[None] = (
+ nullcontext() if library_dirs_are_callers else withholding_host_library_files(library_dirs=effective_dirs)
+ )
+ with host_library_withholding, translate_to_validate_bundle_error():
+ all_blueprints = [MthdsParser.make_pipelex_bundle_blueprint(mthds_content=content) for content in mthds_contents]
+
+ # Filter out blueprints whose URIs are already loaded (e.g. via PIPELEXPATH).
+ blueprints_to_load: list[PipelexBundleBlueprint] = list(all_blueprints)
+ if bundle_uris:
+ current_library = library_manager.get_library(library_id=library_id)
+ blueprints_to_load = []
+ for blueprint, uri in zip(all_blueprints, bundle_uris, strict=True):
+ try:
+ resolved_uri = Path(uri).resolve()
+ except (OSError, RuntimeError):
+ resolved_uri = Path(uri)
+ if resolved_uri in current_library.loaded_mthds_paths:
+ log.verbose(f"Bundle '{uri}' already loaded from library directories, skipping")
+ else:
+ blueprints_to_load.append(blueprint)
+
+ if blueprints_to_load:
+ library_manager.load_from_blueprints(library_id=library_id, blueprints=blueprints_to_load)
# Qualify main_pipe with domain to avoid ambiguity when multiple domains define pipes with
# the same code — via the one shared selection rule (first declaring main_pipe, else first).
diff --git a/pipelex/pipeline/fixes/fix_loop.py b/pipelex/pipeline/fixes/fix_loop.py
index 2e00f9f80..305a8a43e 100644
--- a/pipelex/pipeline/fixes/fix_loop.py
+++ b/pipelex/pipeline/fixes/fix_loop.py
@@ -46,7 +46,6 @@ from pipelex.pipeline.fixes.file_transaction import (
read_file_snapshot,
)
from pipelex.pipeline.validate_bundle import validate_bundle
-from pipelex.pipeline.validation_errors import build_validation_error_items
from pipelex.suggested_fix import DeleteKeyOp, DeleteTableOp, EnsureTableOp, FixOp, MoveKeyOp, RemapValueOp, RenameTableKeyOp, SetKeyOp, SuggestedFix
from pipelex.tools.misc.exceptions import TomlError
from pipelex.tools.misc.toml_utils import load_toml_from_path
@@ -102,13 +101,7 @@ def _fix_fingerprint(fix: SuggestedFix) -> str:
def _validation_error_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:
"""Project the error's categorized lists into wire items — same channels as ``to_error_report``."""
- return build_validation_error_items(
- blueprint_errors=exc.pipelex_bundle_blueprint_validation_errors,
- factory_errors=exc.pipe_factory_errors,
- pipe_validation_errors=exc.pipe_validation_error_data,
- dry_run_error_message=exc.dry_run_error_message,
- fallback_message=exc.message,
- )
+ return exc.validation_error_items()
def _pending_signatures_from_validation_result(validation_result: Any) -> list[str]:
diff --git a/pipelex/pipeline/fixes/fix_render.py b/pipelex/pipeline/fixes/fix_render.py
index 7fa4dcfd5..8e71267e6 100644
--- a/pipelex/pipeline/fixes/fix_render.py
+++ b/pipelex/pipeline/fixes/fix_render.py
@@ -106,10 +106,10 @@ def format_fix_still_invalid_markdown(result: FixBundleResult, *, bundle_path: s
if result.remaining_errors:
lines += ["", format_validation_error_items_markdown(result.remaining_errors)]
- # A remaining error can still carry a 💡 suggested-fix line — dropped by --select/--ignore, left
+ # A remaining error can still carry a safe 💡 suggested-fix line — dropped by --select/--ignore, left
# outside the write scope, or unconverged when the loop bailed. Claiming "no safe fix" there would
# contradict the line just printed, so only say it when nothing fixable remains (mirrors the human tip).
- if any(item.suggested_fix is not None for item in result.remaining_errors):
+ if any(item.suggested_fix is not None and item.suggested_fix.safety.is_safe for item in result.remaining_errors):
lines += [
"",
(
diff --git a/pipelex/pipeline/fixes/planner.py b/pipelex/pipeline/fixes/planner.py
index a2dafb981..1f179667e 100644
--- a/pipelex/pipeline/fixes/planner.py
+++ b/pipelex/pipeline/fixes/planner.py
@@ -6,16 +6,19 @@ of the validation report — CLI, API, MCP — sees fixes with zero extra plumbi
"""
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
-from pipelex.suggested_fix import DeleteKeyOp, EnsureTableOp, FixOp, FixSafety, RenameTableKeyOp, SetKeyOp, SuggestedFix
+from pipelex.suggested_fix import DeleteKeyOp, EnsureTableOp, FixOp, FixSafety, RemapValueOp, RenameTableKeyOp, SetKeyOp, SuggestedFix
MATCH_SEQUENCE_OUTPUT_FIX_CODE = "match-sequence-output"
SYNC_CONTROLLER_INPUTS_FIX_CODE = "sync-controller-inputs"
STRIP_NATIVE_CONCEPT_REDECL_FIX_CODE = "strip-native-concept-redecl"
STRIP_NAMESPACE_FIX_CODE = "strip-namespace"
+RENAME_MODEL_FIX_CODE = "rename-model"
-# Every fix-rule code the planner can emit — the validation set for user-facing rule filters
-# (``--select`` / ``--ignore``). A new rule constant above must be added here; the CLI rejects
-# codes outside this set loudly (a typo'd filter selects *behavior*, so lenient-ignore is wrong).
+# The codes `pipelex fix bundle --select/--ignore` accept: every SAFE rule the fix loop can apply. A new
+# SAFE rule constant above must be added here; the CLI rejects codes outside this set loudly (a typo'd
+# filter selects *behavior*, so lenient-ignore is wrong). An UNSAFE rule stays out: the loop never applies
+# it, so accepting it in `--select` would promise a fix the command then silently skips. `rename-model`
+# is the one such rule today.
KNOWN_FIX_CODES: frozenset[str] = frozenset(
{
MATCH_SEQUENCE_OUTPUT_FIX_CODE,
@@ -33,13 +36,52 @@ def plan_fix_for_pipe_validation_error(error_data: PipesAndConceptValidationErro
the correct value — so the same error types raised elsewhere (PipeParallel / PipeCondition /
operator pipes) carry no enrichment and are suppressed here structurally.
"""
+ if error_data.error_type is None:
+ return None
if error_data.error_type.is_inadequate_output:
return _plan_match_sequence_output(error_data)
if error_data.error_type.is_controller_input_drift:
return _plan_sync_controller_inputs(error_data)
+ if error_data.error_type.is_unknown_model:
+ return _plan_rename_model(error_data=error_data)
return None
+def _plan_rename_model(*, error_data: PipesAndConceptValidationErrorData) -> SuggestedFix | None:
+ """``rename-model``: an ``unknown_model`` whose deck offers exactly one close match of the same kind
+ becomes a ``remap_value`` of the pipe's model field, from the reference as written to that match.
+
+ A single match is the only case with one candidate correction; with several, choosing among them is
+ the author's call, and with none there is nothing to write. The remap names the reference as written,
+ so the op rewrites the field only while it still holds that exact value and leaves a field the
+ author has since edited alone.
+
+ The fix is ``UNSAFE``: the match is a fuzzy guess (a similarity cutoff over the deck's names), so a
+ single match can still be a different model, with its own provider, cost and behaviour, and a wrong
+ sigil the author meant is not weighed against it. It rides the item for an author or an agent to
+ apply deliberately, and ``pipelex fix bundle`` never applies it on its own.
+ """
+ if error_data.pipe_code is None or error_data.field_name is None or error_data.model_reference is None:
+ return None
+ if error_data.suggestions is None or len(error_data.suggestions) != 1:
+ return None
+ suggestion = error_data.suggestions[0]
+ description = f"Replace model '{error_data.model_reference}' of pipe '{error_data.pipe_code}' with '{suggestion}'"
+ return SuggestedFix(
+ fix_code=RENAME_MODEL_FIX_CODE,
+ description=f"{description}, its one close match in the model deck",
+ safety=FixSafety.UNSAFE,
+ source=error_data.source,
+ ops=[
+ RemapValueOp(
+ table_path=["pipe", error_data.pipe_code],
+ key=error_data.field_name,
+ mapping={error_data.model_reference: suggestion},
+ ),
+ ],
+ )
+
+
def _plan_match_sequence_output(error_data: PipesAndConceptValidationErrorData) -> SuggestedFix | None:
"""``match-sequence-output``: an ``INADEQUATE_OUTPUT_*`` carrying the enriched
``expected_output_ref`` becomes a ``set_key`` of the pipe's ``output``.
diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.py
index eeeff0367..ba002d36f 100644
--- a/pipelex/pipeline/pipeline_run_setup.py
+++ b/pipelex/pipeline/pipeline_run_setup.py
@@ -62,6 +62,7 @@ async def pipeline_run_setup(
pipeline_run_id: str | None = None,
request_id: str | None = None,
inputs_base_dir: Path | None = None,
+ library_dirs_are_callers: bool = False,
) -> tuple[PipeJob, str, str]:
"""Set up a pipeline for execution.
@@ -149,6 +150,11 @@ async def pipeline_run_setup(
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.
+ library_dirs_are_callers:
+ Whether ``library_dirs`` are the caller's own, as on a local CLI run, so a refusal while
+ loading them is the caller's invalid bundle. ``False`` (a host's own directories) loads them
+ untranslated. The ``mthds_contents`` are always the caller's: a refusal while loading them is
+ always the ``ValidateBundleError`` verdict. See :func:`acquire_library`.
Returns:
-------
@@ -156,6 +162,12 @@ async def pipeline_run_setup(
A tuple containing the pipe job ready for execution, the pipeline run ID,
and the library ID.
+ Raises:
+ -------
+ ValidateBundleError
+ The bundle was refused while it loaded, before any pipe ran: the same verdict, with the same
+ located ``validation_errors``, that validating the bundle gives.
+
"""
# NO `user_id or DEFAULT_USER_ID` HERE, DELIBERATELY.
#
@@ -255,6 +267,7 @@ async def pipeline_run_setup(
library_dirs=library_dirs,
mthds_contents=mthds_contents,
bundle_uris=bundle_uris,
+ library_dirs_are_callers=library_dirs_are_callers,
)
library_acquired = True
diff --git a/pipelex/pipeline/resolve_bundle.py b/pipelex/pipeline/resolve_bundle.py
index bccaa2d36..b8b90ca58 100644
--- a/pipelex/pipeline/resolve_bundle.py
+++ b/pipelex/pipeline/resolve_bundle.py
@@ -24,7 +24,7 @@ from pipelex.libraries.library_crate import LibraryCrate
from pipelex.libraries.pipe.exceptions import PipeLibraryError
from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
-from pipelex.pipeline.validate_bundle import translate_to_validate_bundle_error
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
def resolve_crate_from_contents(*, mthds_contents: list[str], mthds_sources: Sequence[str | None] | None = None) -> LibraryCrate:
diff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.py
index c6aee5f5d..fb1be9e42 100644
--- a/pipelex/pipeline/runner.py
+++ b/pipelex/pipeline/runner.py
@@ -26,7 +26,6 @@ from pipelex.interpreter_hub import (
get_pipeline_manager,
set_current_library,
)
-from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipeline.exceptions import PipeExecutionError, PipelineExecutionError
from pipelex.pipeline.pipeline_response import PipelexRunResultExecute, PipelexRunResultStart, RunState
from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
@@ -127,9 +126,14 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):
execution_config: PipelineExecutionConfig | None = None,
pipe_run: PipeRunProtocol | None = None,
inputs_base_dir: Path | None = None,
+ # Whose `library_dirs` are: the caller's own on a local CLI run, so a refusal while loading
+ # them is the caller's invalid bundle; a host's own otherwise, loaded untranslated. See
+ # `acquire_library`.
+ library_dirs_are_callers: bool = False,
):
self.library_id = library_id
self.library_dirs = library_dirs
+ self.library_dirs_are_callers = library_dirs_are_callers
self.bundle_uris = bundle_uris
self.pipe_run_mode = pipe_run_mode
self.is_mock_usage = is_mock_usage
@@ -249,35 +253,13 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):
storage_scope=self.storage_scope,
extras=self.extras,
inputs_base_dir=self.inputs_base_dir,
+ library_dirs_are_callers=self.library_dirs_are_callers,
)
effective_pipe_run = self._pipe_run or get_pipe_run()
pipe_output = await effective_pipe_run.run(pipe_job, delivery_assignment=delivery_assignment)
- except PipeRouterError as exc:
- # PipeRouterError can only be raised by get_pipe_run().run(), so pipe_job is guaranteed to exist
- assert pipe_job is not None # for type checker
- properties = {
- EventProperty.PIPELINE_RUN_ID: pipeline_run_id,
- EventProperty.PIPE_TYPE: pipe_job.pipe.pipe_type,
- EventProperty.PIPELINE_OUTCOME: Outcome.FAILURE,
- }
- get_telemetry_manager().track_event(
- event_name=EventName.PIPELINE_COMPLETE,
- properties=properties,
- run_metadata=pipe_job.job_metadata.run_metadata,
- )
- raise PipelineExecutionError(
- message=exc.message,
- run_mode=pipe_job.pipe_run_params.run_mode,
- pipe_code=pipe_job.pipe.code,
- output_name=pipe_job.output_name,
- # The live pipe_stack has fully unwound by now; PipeRouterError carries the
- # snapshot taken where the failure occurred.
- pipe_stack=exc.pipe_stack,
- ) from exc
except PipelexError as exc:
- # Catch other Pipelex errors that bypass the router's PipeRunError handling
- # (e.g., PipeRunInputsError raised directly from pipe_abstract.py)
- # If pipe_job is None, the error occurred during pipeline_run_setup before pipe_job was created
+ # If pipe_job is None, the error occurred during pipeline_run_setup, before the job existed:
+ # it is not a run failure, and it propagates untouched.
if pipe_job is None:
raise
properties = {
@@ -290,12 +272,15 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):
properties=properties,
run_metadata=pipe_job.job_metadata.run_metadata,
)
- raise PipelineExecutionError(
- message=exc.message,
+ # Every failure of the run, whether a pipe's (located by its router as a PipeRouterError)
+ # or one raised around the pipes (a bridge, a delivery), wrapped into the one class hosts
+ # catch. The location comes from the failure's cause chain: the live pipe_stack has
+ # fully unwound by now.
+ raise PipelineExecutionError.make_for_run_failure(
+ failure=exc,
run_mode=pipe_job.pipe_run_params.run_mode,
- pipe_code=pipe_job.pipe.code,
+ entry_pipe_code=pipe_job.pipe.code,
output_name=pipe_job.output_name,
- pipe_stack=pipe_job.pipe_run_params.pipe_stack,
) from exc
except ValidationError as exc:
formatted_error = format_pydantic_validation_error(exc)
@@ -455,6 +440,8 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):
graph_pipe_code=graph_pipe_code,
log_context="Protocol validate",
caller_identity=self.caller_identity,
+ # The same ownership a run of this runtime reads: the caller's own directories keep their paths.
+ library_dirs_are_callers=self.library_dirs_are_callers,
)
@override
diff --git a/pipelex/pipeline/validate_bundle.py b/pipelex/pipeline/validate_bundle.py
index ef99249ad..c3e7a9477 100644
--- a/pipelex/pipeline/validate_bundle.py
+++ b/pipelex/pipeline/validate_bundle.py
@@ -1,10 +1,9 @@
import asyncio
-from collections.abc import Generator
-from contextlib import contextmanager
+from contextlib import AbstractContextManager, nullcontext
from pathlib import Path
from typing import Sequence
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel
# TypedDict from typing_extensions, not typing: pydantic rejects typing.TypedDict as a model
# field on Python < 3.12, and ValidatedPipeEntry is a field of PipelexValidationReport.
@@ -12,9 +11,7 @@ from typing_extensions import TypedDict
from pipelex import log
from pipelex.base_exceptions import PipelexUnexpectedError
-from pipelex.core.pipes.exceptions import PipeFactoryError, PipeRunError, PipeValidationError
from pipelex.core.qualified_ref import QualifiedRef
-from pipelex.core.validation import report_validation_error
from pipelex.interpreter_hub import (
clear_current_library,
get_current_library_id_or_none,
@@ -22,23 +19,15 @@ from pipelex.interpreter_hub import (
resolve_library_dirs,
set_current_library,
)
-from pipelex.libraries.exceptions import LibraryError, LibraryLoadingError
from pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs
-from pipelex.libraries.pipe.exceptions import EntryPipeNotFoundError, PipeNotFoundError
-from pipelex.mthds_parsing.exceptions import MthdsParserError
-from pipelex.mthds_parsing.handle_pipe_errors import (
- categorize_pipe_factory_error,
- categorize_pipe_validation_error,
- categorize_pipe_validation_with_libraries_error,
-)
+from pipelex.libraries.pipe.exceptions import EntryPipeNotFoundError
from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
-from pipelex.pipe_run.exceptions import DryRunError
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunOutput, DryRunStatus
from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error, withholding_host_library_files
from pipelex.system.caller_identity import CallerIdentity
-from pipelex.system.registries.exceptions import FuncRegistryError
class ValidateBundleResult(BaseModel):
@@ -92,122 +81,6 @@ def build_pending_signatures(pipes_by_ref: dict[str, PipeAbstract]) -> list[str]
return sorted(pipe.pipe_ref for ref_key, pipe in pipes_by_ref.items() if pipe.is_signature and not QualifiedRef.has_cross_package_prefix(ref_key))
-def _backfill_pipe_error_source(pipe_error: PipeValidationError) -> None:
- """Backfill ``file_path`` on a pipe-channel error from the library manager's pipe-source map.
-
- Raise sites (``PipeAbstract`` input checks, ``PipeSequence`` output checks) don't know their
- file — pipes deliberately carry no source; provenance lives in the crate's ``source_map``,
- mirrored into the current library's source map during load, *before* ``validate_library``
- runs. Intercepting once at this catch boundary covers every raise site, present and future.
-
- Lookup is by the full ``domain.pipe_code`` ref only — never the bare-code suffix fallback
- (under the strict own-domain resolution rule, a bare-code suffix match would guess a file
- where the qualified ref did not resolve). A miss leaves ``file_path`` as ``None``: the fix stays source-less and
- falls under the conservative single-file rule, which is the safe direction.
- """
- if pipe_error.file_path is not None:
- return
- if pipe_error.domain_code is None or pipe_error.pipe_code is None:
- return
- source = get_library_manager().get_pipe_source(f"{pipe_error.domain_code}.{pipe_error.pipe_code}")
- if source is not None:
- # Compatibility boundary: injected managers written against the previous protocol may
- # still return ``Path``. Normalize before assigning to the string-only error model.
- pipe_error.file_path = str(source)
-
-
-@contextmanager
-def translate_to_validate_bundle_error() -> Generator[None, None, None]:
- """Translate the bundle-loading exception surface into a single ``ValidateBundleError``.
-
- Single source of truth for the bundle-loading error cascade, shared by the
- bundle-loading entry points: ``validate_bundle``, ``validate_bundles_from_directory``,
- and ``pipelex.pipeline.resolve_bundle.resolve_crate_from_contents``.
- A ``MthdsParserError`` becomes a ``ValidateBundleError`` carrying the
- blueprint validation errors, a ``PipeFactoryError`` carries the categorized
- factory error, etc. Sharing one source of truth means a new handler only
- needs to be added once.
- """
- try:
- yield
- except MthdsParserError as parser_error:
- raise ValidateBundleError(
- message=parser_error.message,
- pipelex_bundle_blueprint_validation_errors=parser_error.validation_errors,
- ) from parser_error
- except PipeFactoryError as factory_error:
- factory_error_data = categorize_pipe_factory_error(factory_error=factory_error)
- raise ValidateBundleError(
- message=f"Pipe factory error: {factory_error}",
- pipe_factory_errors=[factory_error_data],
- ) from factory_error
- # Cascade order: ``except PipeValidationError`` must precede
- # ``except ValidationError``. Their sibling-under-``ValueError``
- # relationship (``PipeValidationError(ValueError)``, not a subclass of
- # ``pydantic.ValidationError``) is pinned by
- # ``tests/unit/pipelex/pipeline/test_validate_bundle_helper.py``.
- except PipeValidationError as pipe_error:
- _backfill_pipe_error_source(pipe_error)
- pipe_error_data = categorize_pipe_validation_with_libraries_error(pipe_error=pipe_error)
- raise ValidateBundleError(
- message=f"Pipe validation failed: {pipe_error}",
- pipe_validation_errors=[pipe_error_data],
- ) from pipe_error
- except ValidationError as validation_error:
- pipe_validation_errors = categorize_pipe_validation_error(validation_error=validation_error)
- validation_error_msg = report_validation_error(validation_error=validation_error).message
- msg = f"Could not load blueprints because of: {validation_error_msg}"
- raise ValidateBundleError(
- message=msg,
- pipe_validation_errors=pipe_validation_errors,
- ) from validation_error
- except PipeNotFoundError:
- # The base class on purpose: the slice miss raised by ``_pipes_to_dry_run`` is the
- # INPUT-domained ``EntryPipeNotFoundError`` subclass, and this arm must let it through raw,
- # domain and all. PipeNotFoundError is a PipeLibraryError (hence a LibraryError), but it is
- # NOT a bundle merge/load failure: it means a requested --pipe slice names a pipe absent from
- # the bundle. It has its own dedicated CLI handler (execute_validate's
- # `except PipeNotFoundError`), so it must propagate raw rather than be folded into a
- # ValidateBundleError by the arm below.
- raise
- except LibraryError as library_error:
- # Library merge / load failures that are NOT pydantic ValidationErrors: undeclared
- # cross-file concept references (ConceptLibraryError), signature/concrete contract
- # mismatches and duplicate concept/pipe refs (ConceptLibraryError / PipeLibraryError), and
- # the structured LibraryLoadingError aggregate (concept cycles, reserved-domain
- # violations, factory failures). Surface them as a clean ValidateBundleError instead of a
- # raw traceback. LibraryLoadingError carries blueprint- and pipe/concept-validation errors;
- # forward them so the CLI renders the same structured detail it does for the other arms.
- if isinstance(library_error, LibraryLoadingError):
- blueprint_validation_errors = library_error.blueprint_validation_errors
- pipe_concept_validation_errors = library_error.pipe_concept_validation_errors
- else:
- blueprint_validation_errors = None
- pipe_concept_validation_errors = None
- raise ValidateBundleError(
- message=library_error.message,
- pipelex_bundle_blueprint_validation_errors=blueprint_validation_errors,
- pipe_validation_errors=pipe_concept_validation_errors,
- ) from library_error
- except FuncRegistryError as func_registry_error:
- # A duplicate @pipe_func name across the scanned library dirs. Raised while loading the
- # library, so it lands here rather than on the PipeFunc field validator's ValueError path.
- # It is caller-fixable input (rename one with @pipe_func(name=...)), so it must produce a
- # verdict — `is_valid: false` — not the "no verdict could be produced" exit 2 / 5xx an
- # untranslated error would give.
- raise ValidateBundleError(message=func_registry_error.message) from func_registry_error
- except PipeRunError as pipe_run_error:
- raise ValidateBundleError(
- message=pipe_run_error.message,
- dry_run_error_message=pipe_run_error.message,
- ) from pipe_run_error
- except DryRunError as dry_run_error:
- raise ValidateBundleError(
- message=dry_run_error.message,
- dry_run_error_message=dry_run_error.message,
- ) from dry_run_error
-
-
def _pipes_to_dry_run(loaded_pipes: list[PipeAbstract], *, dry_run_pipe_codes: list[str] | None) -> list[PipeAbstract]:
"""Select which loaded pipes to dry-run.
@@ -249,12 +122,20 @@ async def validate_bundle(
allow_signatures: bool = False,
dry_run_pipe_codes: list[str] | None = None,
caller_identity: CallerIdentity | None = None,
+ library_dirs_are_callers: bool = False,
) -> ValidateBundleResult:
"""Load one bundle into a fresh library and dry-run its pipes.
``caller_identity`` is who asked for the validation, when the host knows it; the dry-run
sweep is attributed to that caller (see ``BundleValidator.validate_pipes``). ``None``
inherits the caller already in scope, and with none the sweep belongs to nobody.
+
+ ``library_dirs_are_callers`` says whose library directories are loaded beside submitted
+ ``mthds_contents``, as it does on the run path (``acquire_library``). By default they are a
+ host's, so the verdict names none of their files (``withholding_host_library_files``); a
+ caller validating content against its own directories passes True and keeps every path. A
+ bundle file is validated on the caller's own disk, among the caller's own directories, and
+ keeps every path whatever this says.
"""
provided_params = sum(
[
@@ -301,8 +182,17 @@ async def validate_bundle(
loaded_pipes: list[PipeAbstract] | None = None
loaded_blueprints: list[PipelexBundleBlueprint] | None = None
+ # Beside submitted content, a host's library directories are withheld from the verdict: their files are paths
+ # on the host. The caller's own directories, and every directory of a bundle file, keep their paths.
+ host_library_withholding: AbstractContextManager[None]
+ if mthds_contents is not None and not library_dirs_are_callers:
+ host_library_withholding = withholding_host_library_files(
+ library_dirs=effective_dirs, caller_sources=[source for source in mthds_sources or [] if source is not None]
+ )
+ else:
+ host_library_withholding = nullcontext()
await asyncio.sleep(0) # Yield to event loop (keeps function async-compatible)
- with translate_to_validate_bundle_error():
+ with host_library_withholding, translate_to_validate_bundle_error():
if effective_dirs:
log.verbose(f"Loading libraries from {len(effective_dirs)} directory(ies) ({source_label}) for validation")
library_manager.load_libraries(
@@ -323,6 +213,10 @@ async def validate_bundle(
library_id=library_id,
allow_signatures=allow_signatures,
caller_identity=caller_identity,
+ # Submitted content beside a host's library directories: only its own pipes name their file,
+ # never a pipe of the host's directories, which would put a path on the host into the
+ # caller's verdict. Beside the caller's own directories, every failure names its file.
+ source_pipe_refs=None if library_dirs_are_callers else frozenset(pipe.pipe_ref for pipe in loaded_pipes),
)
result = ValidateBundleResult(
blueprints=loaded_blueprints,
@@ -351,6 +245,9 @@ async def validate_bundle(
library_id=library_id,
allow_signatures=allow_signatures,
caller_identity=caller_identity,
+ # A file on the caller's own disk: every failure names its file, a sibling file of the
+ # same method included, since the library directories are the caller's own too.
+ source_pipe_refs=None,
)
result = ValidateBundleResult(
blueprints=loaded_blueprints,
diff --git a/pipelex/pipeline/validate_bundle_translation.py b/pipelex/pipeline/validate_bundle_translation.py
new file mode 100644
index 000000000..0f5d5b9ce
--- /dev/null
+++ b/pipelex/pipeline/validate_bundle_translation.py
@@ -0,0 +1,297 @@
+"""The one translation of a bundle's load-time refusals into the ``ValidateBundleError`` verdict.
+
+Every surface that loads a bundle and must answer with a verdict wraps its load in
+:func:`translate_to_validate_bundle_error`: ``validate_bundle`` and ``validate_bundles_from_directory``,
+``resolve_crate_from_contents``, the library loads of the ``validate`` commands, and the run path's
+``acquire_library``, so a run refuses an invalid bundle with the same located items ``validate`` gives.
+It lives in its own module, rather than beside ``validate_bundle``, because the run path's seams sit
+below the validation service in the import graph (``validate_bundle`` → ``bundle_validator`` →
+``execution_seams``), and both must reach the same translation.
+"""
+
+from collections.abc import Collection, Generator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from pipelex.base_exceptions import PipelexError, SecurityError, error_domain_is_input
+from pipelex.config import get_config
+from pipelex.core.exceptions import DryRunFailureErrorData, PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
+from pipelex.core.pipes.exceptions import (
+ PipeFactoryError,
+ PipeLoadRefusalError,
+ PipeOperatorModelChoiceError,
+ PipeRunError,
+ PipeValidationError,
+ caller_facing_refusal_text,
+)
+from pipelex.core.validation import report_validation_error
+from pipelex.interpreter_hub import get_library_manager
+from pipelex.libraries.exceptions import LibraryError, LibraryLoadingError
+from pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs
+from pipelex.libraries.pipe.exceptions import PipeNotFoundError
+from pipelex.mthds_parsing.exceptions import MthdsParserError
+from pipelex.mthds_parsing.handle_pipe_errors import (
+ categorize_pipe_factory_error,
+ categorize_pipe_operator_model_choice_error,
+ categorize_pipe_validation_error,
+ categorize_pipe_validation_with_libraries_error,
+)
+from pipelex.pipe_run.exceptions import DryRunError
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.system.registries.exceptions import FuncRegistryError
+from pipelex.tools.misc.file_utils import find_files_in_dir
+from pipelex.tools.typing.module_inspector import convert_file_path_to_module_path
+
+# What a verdict's message reads where it named a file of the host's own library directories.
+HOST_LIBRARY_FILE_PLACEHOLDER = "<host library file>"
+
+
+def _backfill_pipe_error_source(pipe_error: PipeValidationError) -> None:
+ """Backfill ``file_path`` on a pipe-channel error from the library manager's pipe-source map.
+
+ Raise sites (``PipeAbstract`` input checks, ``PipeSequence`` output checks) don't know their
+ file — pipes deliberately carry no source; provenance lives in the crate's ``source_map``,
+ mirrored into the current library's source map during load, *before* ``validate_library``
+ runs. Intercepting once at this catch boundary covers every raise site, present and future.
+
+ Lookup is by the full ``domain.pipe_code`` ref only — never the bare-code suffix fallback
+ (under the strict own-domain resolution rule, a bare-code suffix match would guess a file
+ where the qualified ref did not resolve). A miss leaves ``file_path`` as ``None``: the fix stays source-less and
+ falls under the conservative single-file rule, which is the safe direction.
+ """
+ if pipe_error.file_path is not None:
+ return
+ if pipe_error.domain_code is None or pipe_error.pipe_code is None:
+ return
+ source = get_library_manager().get_pipe_source(f"{pipe_error.domain_code}.{pipe_error.pipe_code}")
+ if source is not None:
+ # Compatibility boundary: injected managers written against the previous protocol may
+ # still return ``Path``. Normalize before assigning to the string-only error model.
+ pipe_error.file_path = str(source)
+
+
+@contextmanager
+def translate_to_validate_bundle_error() -> Generator[None, None, None]:
+ """Translate the bundle-loading exception surface into a single ``ValidateBundleError``.
+
+ Single source of truth for the bundle-loading error cascade, shared by the
+ bundle-loading entry points: ``validate_bundle``, ``validate_bundles_from_directory``,
+ ``pipelex.pipeline.resolve_bundle.resolve_crate_from_contents``, the library loads and
+ dry-run sweeps of the ``validate pipe`` / ``validate --all`` commands, and the run path's
+ ``pipelex.pipeline.execution_seams.acquire_library``, so running an invalid bundle is refused with
+ the same items validating it gives.
+ A ``MthdsParserError`` becomes a ``ValidateBundleError`` carrying the
+ blueprint validation errors, a ``PipeFactoryError`` carries the categorized
+ factory error, etc. Sharing one source of truth means a new handler only
+ needs to be added once.
+
+ **Every refusal of the bundle is a verdict.** After the class-specific arms, a final arm turns any
+ other ``PipelexError`` whose report is ``input``-domained (the caller's fault) into a verdict with one
+ item, so a refusal nobody wrote an arm for still reaches the author as an invalid bundle rather than
+ as a crash or a no-verdict fault. Only a failure of the tool or its environment — a ``config`` or
+ ``runtime`` fault, an unclassified one, anything that is not a ``PipelexError`` — propagates as
+ no verdict, along with the refusals that must keep their own class: ``PipeNotFoundError`` (its
+ dedicated not-found handler), a ``SecurityError`` (never absorbed by a domain handler), and a
+ ``ValidateBundleError`` already produced (never re-wrapped).
+ """
+ try:
+ yield
+ except MthdsParserError as parser_error:
+ raise ValidateBundleError(
+ message=parser_error.message,
+ pipelex_bundle_blueprint_validation_errors=parser_error.validation_errors,
+ ) from parser_error
+ except PipeFactoryError as factory_error:
+ factory_error_data = categorize_pipe_factory_error(factory_error=factory_error)
+ raise ValidateBundleError(
+ message=f"Pipe factory error: {factory_error}",
+ pipe_factory_errors=[factory_error_data],
+ ) from factory_error
+ # Cascade order: ``except PipeValidationError`` must precede
+ # ``except ValidationError``. Their sibling-under-``ValueError``
+ # relationship (``PipeValidationError(ValueError)``, not a subclass of
+ # ``pydantic.ValidationError``) is pinned by
+ # ``tests/unit/pipelex/pipeline/test_validate_bundle_helper.py``.
+ except PipeValidationError as pipe_error:
+ _backfill_pipe_error_source(pipe_error)
+ pipe_error_data = categorize_pipe_validation_with_libraries_error(pipe_error=pipe_error)
+ raise ValidateBundleError(
+ message=f"Pipe validation failed: {pipe_error}",
+ pipe_validation_errors=[pipe_error_data],
+ ) from pipe_error
+ except ValidationError as validation_error:
+ pipe_validation_errors = categorize_pipe_validation_error(validation_error=validation_error)
+ validation_error_msg = report_validation_error(validation_error=validation_error).message
+ msg = f"Could not load blueprints because of: {validation_error_msg}"
+ raise ValidateBundleError(
+ message=msg,
+ pipe_validation_errors=pipe_validation_errors,
+ ) from validation_error
+ except PipeNotFoundError:
+ # The base class on purpose: the slice miss raised by ``_pipes_to_dry_run`` is the
+ # INPUT-domained ``EntryPipeNotFoundError`` subclass, and this arm must let it through raw,
+ # domain and all. PipeNotFoundError is a PipeLibraryError (hence a LibraryError), but it is
+ # NOT a bundle merge/load failure: it means a requested --pipe slice names a pipe absent from
+ # the bundle. It has its own dedicated CLI handler (execute_validate's
+ # `except PipeNotFoundError`), so it must propagate raw rather than be folded into a
+ # ValidateBundleError by the arm below.
+ raise
+ except LibraryError as library_error:
+ # Library merge / load failures that are NOT pydantic ValidationErrors: undeclared
+ # cross-file concept references (ConceptLibraryError), signature/concrete contract
+ # mismatches and duplicate concept/pipe refs (ConceptLibraryError / PipeLibraryError), and
+ # the structured LibraryLoadingError aggregate (concept cycles, reserved-domain
+ # violations, factory failures). Surface them as a clean ValidateBundleError instead of a
+ # raw traceback. LibraryLoadingError carries blueprint- and pipe/concept-validation errors;
+ # forward them so the CLI renders the same structured detail it does for the other arms.
+ if isinstance(library_error, LibraryLoadingError):
+ blueprint_validation_errors = library_error.blueprint_validation_errors
+ pipe_concept_validation_errors = library_error.pipe_concept_validation_errors
+ else:
+ blueprint_validation_errors = None
+ pipe_concept_validation_errors = None
+ raise ValidateBundleError(
+ message=library_error.message,
+ pipelex_bundle_blueprint_validation_errors=blueprint_validation_errors,
+ pipe_validation_errors=pipe_concept_validation_errors,
+ ) from library_error
+ except FuncRegistryError as func_registry_error:
+ # A duplicate @pipe_func name across the scanned library dirs. Raised while loading the
+ # library, so it lands here rather than on the PipeFunc field validator's ValueError path.
+ # It is caller-fixable input (rename one with @pipe_func(name=...)), so it must produce a
+ # verdict — `is_valid: false` — not the "no verdict could be produced" exit 2 / 5xx an
+ # untranslated error would give.
+ raise ValidateBundleError(message=func_registry_error.message) from func_registry_error
+ except PipeRunError as pipe_run_error:
+ # A pipe run failing outside the sweep's per-pipe classification: one dry-run item on its pipe,
+ # whose text follows the disclosure rule, since the verdict carries it past STRICT disclosure.
+ failure_text = caller_facing_refusal_text(refusal=pipe_run_error)
+ raise ValidateBundleError(
+ message=failure_text,
+ dry_run_failures=[
+ DryRunFailureErrorData(
+ pipe_code=pipe_run_error.pipe_code,
+ message=f"Pipe '{pipe_run_error.pipe_code}' failed its dry run: {failure_text}",
+ )
+ ],
+ ) from pipe_run_error
+ except DryRunError as dry_run_error:
+ # The sweep's failures, one per failing pipe, located at the innermost pipe that failed. A
+ # DryRunError raised elsewhere carries none, and becomes one item under the disclosure rule.
+ raise ValidateBundleError(
+ message=dry_run_error.message,
+ dry_run_failures=dry_run_error.failures or [DryRunFailureErrorData(message=caller_facing_refusal_text(refusal=dry_run_error))],
+ ) from dry_run_error
+ except PipeOperatorModelChoiceError as model_choice_error:
+ # A pipe names a model its deck does not define: the operator located it on the pipe and the
+ # field, and the library load added the file, so it becomes one `unknown_model` item carrying
+ # the reference as written, the model type and the deck's suggestions.
+ raise ValidateBundleError(
+ message=model_choice_error.message,
+ pipe_validation_errors=[categorize_pipe_operator_model_choice_error(model_choice_error=model_choice_error)],
+ ) from model_choice_error
+ except (ValidateBundleError, SecurityError):
+ # Both are PipelexErrors the general arm below would otherwise catch. A verdict already produced
+ # (e.g. by a nested load) passes through as it is: re-wrapping it would flatten its items into one.
+ # A security refusal is never absorbed into a domain answer, verdict included.
+ raise
+ except PipelexError as refusal:
+ verdict = _make_refusal_verdict(refusal=refusal)
+ if verdict is None:
+ raise
+ raise verdict from refusal
+
+
+def _make_refusal_verdict(*, refusal: PipelexError) -> ValidateBundleError | None:
+ """The one-item verdict for a refusal of the caller's input that has no arm of its own, else ``None``.
+
+ ``None`` — no verdict — unless the refusal's report is ``input``-domained: a ``config`` or ``runtime``
+ fault, or an unclassified one, is a failure of the tool or its environment, which the validator must
+ not report as the bundle's fault. The item is ``pipe_validation`` when the library load located the
+ refusal on the pipe it was building (``PipeLoadRefusalError``, with the pipe's code, domain and file),
+ and ``blueprint_validation`` otherwise. It carries no ``error_type``: a refusal with a closed code
+ has its own arm above, and naming one here would claim a diagnosis the refusal does not make.
+
+ The item's text is the refusal's message only when that message was authored as caller-facing copy,
+ and otherwise its title: the verdict is caller-facing as a whole and is kept verbatim under STRICT
+ disclosure, so internal text must not ride it past the redaction it would otherwise get.
+ """
+ if not error_domain_is_input(refusal.to_error_report().error_domain):
+ return None
+ message = caller_facing_refusal_text(refusal=refusal)
+ if isinstance(refusal, PipeLoadRefusalError):
+ return ValidateBundleError(
+ message=message,
+ pipe_validation_errors=[
+ PipesAndConceptValidationErrorData(
+ pipe_code=refusal.pipe_code,
+ domain_code=refusal.domain_code,
+ source=refusal.source,
+ message=message,
+ field_path="",
+ )
+ ],
+ )
+ return ValidateBundleError(
+ message=message,
+ pipelex_bundle_blueprint_validation_errors=[PipelexBundleBlueprintValidationErrorData(message=message)],
+ )
+
+
+@contextmanager
+def withholding_host_library_files(*, library_dirs: Sequence[Path], caller_sources: Collection[str] = ()) -> Generator[None, None, None]:
+ """Keep the files of a host's own library directories out of the verdict the block raises.
+
+ A verdict is caller-facing as a whole, and STRICT disclosure hands its message and its items to the caller
+ verbatim, so it must not name a path on the host. When submitted content is validated or run, the library
+ directories loaded beside it are the host's (installed libraries, the defaults, ``PIPELEXPATH``), and an item
+ located in one of their files would name that file, as would a message about it, such as a duplicate
+ declaration, a load that failed, or two ``@pipe_func`` functions of the same name, which the registry names by
+ a module name spelled from the file's absolute path. Around such a load, a ``ValidateBundleError`` leaves this
+ block with every one of those names taken out: the item carries no ``source``, still located by its pipe and
+ domain, and a message reads ``HOST_LIBRARY_FILE_PLACEHOLDER`` where it named one. The names are the ones the
+ load gives: each bundle file in the spelling it gives a bundle's ``source`` and resolved, and each Python file's
+ module name. A name the caller submitted as a content's source (``caller_sources``) is the caller's own and is
+ never withheld, even where a host file is spelled the same.
+
+ A bundle validated from a file on the caller's own disk, or validated or run with library directories that
+ are the caller's, keeps every path: there the directories are the caller's to read. A package the content
+ depends on by address never needs this, since its bundles are named by the package's address at load.
+ """
+ try:
+ yield
+ except ValidateBundleError as verdict:
+ host_library_names = _host_library_names(library_dirs=library_dirs) - set(caller_sources)
+ if not host_library_names:
+ raise
+ withheld_verdict = verdict.withholding_files(withheld_files=host_library_names, placeholder=HOST_LIBRARY_FILE_PLACEHOLDER)
+ # The withheld verdict takes this one's place over the same cause, so its report inherits the same
+ # classification and the unwithheld verdict is not left on the chain beside it.
+ raise withheld_verdict from verdict.__cause__
+
+
+def _host_library_names(*, library_dirs: Sequence[Path]) -> set[str]:
+ """Every name the library load gives a file of ``library_dirs``.
+
+ A bundle file is named as listed, which is the ``source`` the load gives it, and resolved; a Python file by
+ the module name the function registry imports it under, which is spelled from its resolved path.
+ """
+ names: set[str] = set()
+ for library_file in get_pipelex_mthds_files_from_dirs(set(library_dirs)):
+ names.add(str(library_file))
+ try:
+ names.add(str(library_file.resolve()))
+ except (OSError, RuntimeError):
+ # The load names such a file by its listed spelling only (see ``LibraryManager.load_libraries``).
+ continue
+ for library_dir in library_dirs:
+ if not library_dir.is_dir():
+ continue
+ for python_file in find_files_in_dir(dir_path=library_dir, pattern="*.py", excluded_dirs=list(get_config().interpreter.scan.excluded_dirs)):
+ try:
+ names.add(convert_file_path_to_module_path(python_file))
+ except (OSError, RuntimeError):
+ continue
+ return names
diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.py
index 2cd5013de..c111312e8 100644
--- a/pipelex/pipeline/validate_in_process.py
+++ b/pipelex/pipeline/validate_in_process.py
@@ -50,6 +50,7 @@ async def validate_bundles_in_process(
graph_pipe_code: str | None = None,
log_context: str = "validate",
caller_identity: CallerIdentity | None = None,
+ library_dirs_are_callers: bool = False,
) -> PipelexValidationReport:
"""Parse, validate, and dry-run MTHDS bundles in-process; assemble the canonical report.
@@ -78,6 +79,9 @@ async def validate_bundles_in_process(
ambient caller for the whole pass — the sweep's telemetry event and every dry run,
the graph arm's included — so none of it falls back to the telemetry stream's
configured id. ``None`` inherits the caller already in scope, if any.
+ library_dirs_are_callers: Whether ``library_dirs`` are the caller's own, whose files the
+ verdict may name; by default they are a host's, whose files it withholds (see
+ ``validate_bundle``).
Returns:
PipelexValidationReport with the structural artifacts of a valid bundle.
@@ -93,6 +97,7 @@ async def validate_bundles_in_process(
allow_signatures=allow_signatures,
graph_pipe_code=graph_pipe_code,
log_context=log_context,
+ library_dirs_are_callers=library_dirs_are_callers,
)
@@ -104,6 +109,7 @@ async def _validate_bundles_in_scope(
allow_signatures: bool,
graph_pipe_code: str | None,
log_context: str,
+ library_dirs_are_callers: bool,
) -> PipelexValidationReport:
"""The body of :func:`validate_bundles_in_process`, run inside the caller's scope."""
# `validate_bundle` deliberately leaves its validation library OPEN and current on
@@ -128,6 +134,7 @@ async def _validate_bundles_in_scope(
mthds_sources=mthds_sources,
library_dirs=library_dirs,
allow_signatures=allow_signatures,
+ library_dirs_are_callers=library_dirs_are_callers,
)
# Capture the validation library id ONCE, right after validate_bundle leaves it
# current — the graph arm and the finally must target the SAME library even if
diff --git a/pipelex/pipeline/validation_errors.py b/pipelex/pipeline/validation_errors.py
index c5939e1d1..cad41828c 100644
--- a/pipelex/pipeline/validation_errors.py
+++ b/pipelex/pipeline/validation_errors.py
@@ -5,18 +5,23 @@ structured-error surfaces:
- the agent CLI's ``validation_errors`` JSON array (via
``pipelex.cli.agent_cli.commands.agent_output.extract_validation_errors``), and
-- the API 422's ``ErrorReport.validation_errors`` (via
+- the API report's ``ErrorReport.validation_errors`` (via
``ValidateBundleError.to_error_report``).
-Both call this one builder, so the CLI and API structured shapes cannot drift.
-It takes the three categorized error-data lists directly rather than a
-``ValidateBundleError`` instance — that keeps the dependency one-directional
+Both reach it through ``ValidateBundleError.validation_error_items``, so the CLI
+and API structured shapes cannot drift. It takes the error-data lists directly
+rather than a ``ValidateBundleError`` instance — that keeps the dependency one-directional
(``pipelex.pipeline.exceptions`` imports this module, never the reverse) so there
is no import cycle.
"""
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
-from pipelex.core.exceptions import PipeFactoryErrorData, PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
+from pipelex.core.exceptions import (
+ DryRunFailureErrorData,
+ PipeFactoryErrorData,
+ PipelexBundleBlueprintValidationErrorData,
+ PipesAndConceptValidationErrorData,
+)
from pipelex.pipeline.fixes.planner import plan_fix_for_blueprint_validation_error, plan_fix_for_pipe_validation_error
from pipelex.validation_error_types import ValidationResidualErrorType
@@ -26,56 +31,45 @@ def build_validation_error_items(
blueprint_errors: list[PipelexBundleBlueprintValidationErrorData],
factory_errors: list[PipeFactoryErrorData],
pipe_validation_errors: list[PipesAndConceptValidationErrorData],
- dry_run_error_message: str | None = None,
+ dry_run_failures: list[DryRunFailureErrorData] | None = None,
fallback_message: str | None = None,
) -> list[ValidationErrorItem]:
"""Flatten a bundle-validation error's categorized lists into typed items.
- Covers the three populated error-data sources a ``ValidateBundleError``
- aggregates — blueprint validation, pipe-factory, and pipe/concept validation
- — tagging each item with its :class:`ValidationErrorCategory`. Empty
+ Covers the four error-data sources a ``ValidateBundleError`` aggregates —
+ blueprint validation, pipe-factory, pipe/concept validation and the dry-run
+ failures — tagging each item with its :class:`ValidationErrorCategory`. Empty
collections collapse to ``None`` so they drop out of the ``exclude_none``
wire projection. The ``source`` (declaring file path) rides whenever the
underlying error-data model carries it, so a consumer can map each error to
its owning file.
- Two residual safety nets make the structured-info invariant **total** — an
+ Every dry-run failure becomes its own :class:`ValidationErrorCategory.DRY_RUN`
+ item, located at the pipe whose dry run failed (its ``pipe_code``,
+ ``domain_code`` and ``source``), with the ``DryRunError`` code the dry-run
+ items have always carried.
+
+ One residual safety net makes the structured-info invariant **total** — an
invalid verdict never rides a bare ``detail`` with an empty
- ``validation_errors[]``:
-
- - The ``dry_run`` residual: a dry-run failure (``DryRunError`` /
- ``PipeRunError``) surfaces only a single message, not per-error data with
- identity fields. When it is the *only* failure channel (no categorized
- error has data), it becomes one :class:`ValidationErrorCategory.DRY_RUN`
- item carrying that message.
- - The ``fallback_message`` residual: a parse-level failure (a TOML-syntax
- error, an empty blueprint, a bundle-elaborator failure) surfaces only the
- error's top-level message, with no categorized data and no dry-run channel.
- When *nothing else* produced an item, it becomes one
- :class:`ValidationErrorCategory.BLUEPRINT_VALIDATION` item carrying that
- message — the bundle could not be turned into a blueprint at all.
-
- Both residuals are graph/parse-level (the builder has no file context), so
- they carry no ``source``. They are ordered ``dry_run`` then
- ``fallback_message`` (most-specific channel first): a dry-run failure that
- also passes a fallback message must still surface its ``dry_run`` item, and
- the ``not items`` guard on each block guarantees only one residual fires.
+ ``validation_errors[]``: a parse-level failure that surfaces only the error's
+ top-level message (an empty blueprint, a bundle-elaborator failure) becomes,
+ when *nothing else* produced an item, one
+ :class:`ValidationErrorCategory.BLUEPRINT_VALIDATION` item carrying
+ ``fallback_message``, with no ``source`` since the builder has no file context.
Args:
blueprint_errors: Interpreter / blueprint-validation error data.
factory_errors: Pipe-factory error data (e.g. a missing concept).
pipe_validation_errors: Pipe/concept validation error data.
- dry_run_error_message: The residual dry-run failure message, if any. Only
- projected as a ``dry_run`` item when no categorized error has data.
+ dry_run_failures: One located failure per pipe whose dry run failed.
fallback_message: The error's caller-facing message, used as the
last-resort residual. Only projected as a ``blueprint_validation``
- item when no categorized error and no dry-run residual produced one.
+ item when no other channel produced one.
Returns:
One :class:`ValidationErrorItem` per underlying error, in the order
- blueprint → factory → pipe/concept validation, then the ``dry_run`` or
- (last-resort) ``fallback_message`` residual when it is the sole failure
- channel.
+ blueprint → factory → pipe/concept validation → dry run, then the
+ (last-resort) ``fallback_message`` residual when nothing else produced one.
"""
items: list[ValidationErrorItem] = []
@@ -88,7 +82,11 @@ def build_validation_error_items(
concept_code=blueprint_error.concept_code,
domain_code=blueprint_error.domain_code,
source=blueprint_error.source,
+ field_path=blueprint_error.field_path,
variable_names=blueprint_error.variable_names or None,
+ declared_concepts=blueprint_error.declared_concepts or None,
+ line=blueprint_error.line,
+ column=blueprint_error.column,
message=blueprint_error.message,
suggested_fix=plan_fix_for_blueprint_validation_error(blueprint_error),
)
@@ -120,31 +118,36 @@ def build_validation_error_items(
field_path=pipe_error.field_path or None,
field_name=pipe_error.field_name,
variable_names=pipe_error.variable_names or None,
+ declared_concepts=pipe_error.declared_concepts or None,
+ model_reference=pipe_error.model_reference,
+ model_type=pipe_error.model_type,
+ suggestions=pipe_error.suggestions or None,
message=pipe_error.message,
suggested_fix=plan_fix_for_pipe_validation_error(pipe_error),
)
)
- # The dry-run residual is the structured-info safety net: emit it only when no categorized
- # error carries data, so an invalid verdict driven solely by a dry-run failure still surfaces
- # a non-empty validation_errors[] instead of a bare detail. Graph-level → no source.
- if not items and dry_run_error_message:
+ # One located item per failing pipe: the sweep already reduced a failure that made enclosing
+ # controllers fail to the innermost pipe, and built each message under the disclosure rule.
+ for dry_run_failure in dry_run_failures or []:
items.append(
ValidationErrorItem(
category=ValidationErrorCategory.DRY_RUN,
error_type=ValidationResidualErrorType.DRY_RUN_ERROR,
- message=dry_run_error_message,
+ pipe_code=dry_run_failure.pipe_code,
+ domain_code=dry_run_failure.domain_code,
+ source=dry_run_failure.source,
+ message=dry_run_failure.message,
)
)
- # Last-resort residual: a parse-level failure (TOML syntax, an empty blueprint, a bundle
- # elaborator failure) surfaces only a top-level message — no categorized data and no dry-run
- # channel. Emit one BLUEPRINT_VALIDATION item carrying that message so an invalid verdict is
- # NEVER a bare detail with an empty validation_errors[] — the structured-info invariant, now
- # total. The bundle could not be turned into a blueprint at all, so blueprint_validation is the
- # right bucket; parse-level → no source, and error_type stays None (the message is
- # authoritative and the residual fires for several distinct underlying errors). Ordered after
- # the dry_run residual (the more specific channel); the `not items` guard fires only one.
+ # Last-resort residual: a parse-level failure (an empty blueprint, a bundle elaborator failure)
+ # surfaces only a top-level message — no categorized data and no dry-run channel. Emit one
+ # BLUEPRINT_VALIDATION item carrying that message so an invalid verdict is NEVER a bare detail
+ # with an empty validation_errors[] — the structured-info invariant, now total. The bundle could
+ # not be turned into a blueprint at all, so blueprint_validation is the right bucket; parse-level
+ # → no source, and error_type stays None (the message is authoritative and the residual fires for
+ # several distinct underlying errors).
if not items and fallback_message:
items.append(
ValidationErrorItem(
diff --git a/pipelex/pipeline/validation_render.py b/pipelex/pipeline/validation_render.py
index e73a95bb5..9ad99ea38 100644
--- a/pipelex/pipeline/validation_render.py
+++ b/pipelex/pipeline/validation_render.py
@@ -33,7 +33,8 @@ from typing import Any, cast
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
from pipelex.interpreter_hub import resolve_library_dirs
from pipelex.pipeline.fixes.applicability import is_safe_fix_for_load_scope, is_target_in_write_scope
-from pipelex.tools.misc.string_utils import count_with_noun
+from pipelex.suggested_fix import FixSafety, SuggestedFix
+from pipelex.tools.misc.string_utils import count_with_noun, pascal_case_to_sentence
def format_validate_markdown(result: dict[str, Any]) -> str:
@@ -160,6 +161,21 @@ def render_invalid_validation_markdown(report: dict[str, Any]) -> str:
return "\n".join(lines).rstrip()
+def validation_item_title(*, item: ValidationErrorItem) -> str:
+ """The heading of one validation item: its ``error_type`` in words, or ``Validation Error`` without one.
+
+ Shared by the human panel and the markdown so both name an item alike. The stage codes are
+ snake_case (``unknown_model`` → ``Unknown Model``); the dry-run code is an exception's name
+ (``DryRunError`` → ``Dry Run Error``).
+ """
+ if not item.error_type:
+ return "Validation Error"
+ error_type = str(item.error_type)
+ if "_" in error_type or error_type.islower():
+ return error_type.replace("_", " ").title()
+ return pascal_case_to_sentence(error_type).title()
+
+
def _markdown_category_header(category: ValidationErrorCategory) -> str:
"""The section heading for one validation-error category — markdown sibling of the human header."""
match category:
@@ -170,7 +186,24 @@ def _markdown_category_header(category: ValidationErrorCategory) -> str:
case ValidationErrorCategory.PIPE_VALIDATION:
return "Pipe validation errors"
case ValidationErrorCategory.DRY_RUN:
- return "Dry run error"
+ return "Dry run errors"
+
+
+def suggested_fix_label(*, fix: SuggestedFix) -> str:
+ """The label a rendered suggested fix opens with, saying whether it may be applied without asking.
+
+ A safe fix is a plain ``Suggested fix``: ``pipelex fix bundle`` applies it on its own. An unsafe
+ one, such as ``rename-model``, whose close match by name can still be a different model, says it is
+ unsafe and needs confirming, because ``pipelex fix bundle`` never applies it and the person or agent
+ reading the line decides. The word is the wire's own ``safety`` value, the one the TypeScript clients
+ show. Shared by the human panel (``cli/error_handlers.py``) and the markdown prose here, so every
+ surface labels a fix the same way.
+ """
+ match fix.safety:
+ case FixSafety.SAFE:
+ return "Suggested fix"
+ case FixSafety.UNSAFE:
+ return "Suggested fix (unsafe, confirm before applying)"
def _render_error_item_markdown(item: ValidationErrorItem, *, index: int) -> list[str]:
@@ -179,8 +212,7 @@ def _render_error_item_markdown(item: ValidationErrorItem, *, index: int) -> lis
Markdown sibling of the human ``_display_validation_error_item`` — same fields in the same
order, emitting ``**bold**`` / backticks instead of Rich markup.
"""
- title = item.error_type.replace("_", " ").title() if item.error_type else "Validation Error"
- lines: list[str] = [f"{index}. **{title}**"]
+ lines: list[str] = [f"{index}. **{validation_item_title(item=item)}**"]
if item.pipe_code:
lines.append(f" - Pipe: `{item.pipe_code}`")
if item.concept_code:
@@ -201,7 +233,7 @@ def _render_error_item_markdown(item: ValidationErrorItem, *, index: int) -> lis
lines.append(f" - Variables: {variables}")
lines.append(f" - {item.message}")
if item.suggested_fix is not None:
- lines.append(f" - 💡 Suggested fix: {item.suggested_fix.description}")
+ lines.append(f" - 💡 {suggested_fix_label(fix=item.suggested_fix)}: {item.suggested_fix.description}")
if item.field_path:
lines.append(f" - Path: `{item.field_path}`")
if item.source:
@@ -225,7 +257,7 @@ def format_validation_error_items_markdown(items: list[ValidationErrorItem]) ->
Returns:
A markdown string: one ``## <Category>`` section per populated category, each holding
- numbered prose items (the ``dry_run`` residual keeps its plain single-message rendering).
+ numbered prose items (one per failing pipe in the ``dry_run`` section).
"""
items_by_category: dict[ValidationErrorCategory, list[ValidationErrorItem]] = {}
for item in items:
@@ -239,16 +271,11 @@ def format_validation_error_items_markdown(items: list[ValidationErrorItem]) ->
if lines:
lines.append("")
lines += [f"## {_markdown_category_header(category)}", ""]
- match category:
- case ValidationErrorCategory.DRY_RUN:
- # The dry-run residual is a single graph-level message with no identity fields —
- # keep its plain rendering rather than a numbered item, mirroring the human surface.
- for item in category_items:
- lines.append(item.message)
- case ValidationErrorCategory.BLUEPRINT_VALIDATION | ValidationErrorCategory.PIPE_FACTORY | ValidationErrorCategory.PIPE_VALIDATION:
- for error_index, item in enumerate(category_items, 1):
- lines += _render_error_item_markdown(item, index=error_index)
- lines.append("")
+ # Every category, dry run included, renders numbered items: a dry-run item is located on its
+ # failing pipe like any other, so it names the pipe, the domain and the source.
+ for error_index, item in enumerate(category_items, 1):
+ lines += _render_error_item_markdown(item, index=error_index)
+ lines.append("")
return "\n".join(lines).rstrip()
diff --git a/pipelex/suggested_fix.py b/pipelex/suggested_fix.py
index be12a2ec2..acacb9263 100644
--- a/pipelex/suggested_fix.py
+++ b/pipelex/suggested_fix.py
@@ -63,7 +63,9 @@ class FixOpKind(StrEnum):
class FixSafety(StrEnum):
- """Whether a fix is safe to auto-apply (SAFE) or requires explicit opt-in (UNSAFE)."""
+ """Whether a fix is safe to auto-apply (SAFE), or a likely correction that needs a person's or an agent's
+ confirmation (UNSAFE), which ``pipelex fix bundle`` never applies.
+ """
SAFE = "safe"
UNSAFE = "unsafe"
diff --git a/pipelex/test_extras/mthds_corpus/entries/invalid_unknown_model/bundle.mthds b/pipelex/test_extras/mthds_corpus/entries/invalid_unknown_model/bundle.mthds
new file mode 100644
index 000000000..9431b0e51
--- /dev/null
+++ b/pipelex/test_extras/mthds_corpus/entries/invalid_unknown_model/bundle.mthds
@@ -0,0 +1,12 @@
+domain = "tide_tables"
+description = "Write the note telling harbour users when the tide turns"
+main_pipe = "write_tide_note"
+
+# The model named here is one no model deck defines, so the pipe is refused when it is built.
+[pipe.write_tide_note]
+type = "PipeLLM"
+description = "Write the tide note for the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text"
+model = "no-such-model-handle"
+prompt = "Write a short note for the harbour board from these tide times: $tide_times"
diff --git a/pipelex/test_extras/mthds_corpus/entries/invalid_unknown_model/entry.toml b/pipelex/test_extras/mthds_corpus/entries/invalid_unknown_model/entry.toml
new file mode 100644
index 000000000..51f0889ac
--- /dev/null
+++ b/pipelex/test_extras/mthds_corpus/entries/invalid_unknown_model/entry.toml
@@ -0,0 +1,12 @@
+name = "invalid_unknown_model"
+description = "A harbour tide note whose writing pipe names a model that no model deck defines"
+
+validity = "invalid"
+tier = "static"
+granularity = "focused"
+
+covers = [
+ "error.unknown_model",
+]
+
+expected_error = "unknown_model"
diff --git a/pipelex/test_extras/mthds_corpus/vocabulary.toml b/pipelex/test_extras/mthds_corpus/vocabulary.toml
index 441b1b637..06d179290 100644
--- a/pipelex/test_extras/mthds_corpus/vocabulary.toml
+++ b/pipelex/test_extras/mthds_corpus/vocabulary.toml
@@ -177,6 +177,10 @@ fails_at = "runtime"
code = "unresolved_pipe_dependency"
fails_at = "runtime"
+[error.unknown_model]
+code = "unknown_model"
+fails_at = "runtime"
+
[error.unknown_validation_error]
code = "unknown_validation_error"
excluded = "The generic fallback for a validation failure that matched no specific code. Reaching it on purpose would mean authoring a bundle that breaks in a way the categorizer does not recognize — which is a state to fix in the runtime, not to pin in a corpus entry that would then have to be rewritten the moment the fault gets a code of its own."
diff --git a/pipelex/tools/jinja2/exceptions.py b/pipelex/tools/jinja2/exceptions.py
index 794788aa4..c8ebaf832 100644
--- a/pipelex/tools/jinja2/exceptions.py
+++ b/pipelex/tools/jinja2/exceptions.py
@@ -6,6 +6,11 @@ class Jinja2TemplateSyntaxError(ToolError):
class Jinja2TemplateRenderError(ToolError):
+ # Not classified as the caller's fault, although a run reaches it with the caller's own template:
+ # a failure of that template can come from the template (a reference or an expression its values
+ # never support, which validation's dry run also refuses) or from this run's data (a value that is
+ # absent or shaped otherwise this time), and nothing where it is raised tells the two apart. The
+ # same render also serves Pipelex's own templates, whose source a caller must not read.
pass
diff --git a/pipelex/tools/typing/pydantic_utils.py b/pipelex/tools/typing/pydantic_utils.py
index f55d959db..e2846f7e7 100644
--- a/pipelex/tools/typing/pydantic_utils.py
+++ b/pipelex/tools/typing/pydantic_utils.py
@@ -57,11 +57,23 @@ class PydanticValidationErrorAnalysis(BaseModel):
literal_errors: list[str]
union_tag_errors: list[str]
model_type_errors: list[str]
+ other_errors: list[str]
+
+
+# The error kinds the analysis lists under a heading of its own; every other kind is listed under
+# "Other validation errors", so no error is left out of the message because another kind is present.
+_LISTED_ERROR_KINDS = frozenset(
+ {"missing", "extra_forbidden", "type_error", "value_error", "enum", "literal_error", "union_tag_not_found", "model_type"}
+)
def analyze_pydantic_validation_error(exc: ValidationError) -> PydanticValidationErrorAnalysis:
"""Analyze a Pydantic ValidationError into a readable string with detailed error information.
+ Every error is rendered: the kinds it lists get their own heading, and all the others (an
+ ``int_parsing`` or ``string_type`` error, say) are rendered under "Other validation errors",
+ whatever else is present.
+
Args:
exc: The Pydantic ValidationError exception
@@ -123,11 +135,14 @@ def analyze_pydantic_validation_error(exc: ValidationError) -> PydanticValidatio
if model_type_errors:
error_msg += f"\n\nModel type errors: {', '.join(model_type_errors)}"
- # If none of the specific error types were found, add the raw error messages
- if not any([missing_fields, extra_fields, type_errors, value_errors, enum_errors, literal_errors, union_tag_errors, model_type_errors]):
+ # Every kind without a heading of its own, rendered whatever else is present.
+ other_errors = [
+ f"{'.'.join(map(str, err['loc']))}: {err['type']}: {err['msg']}" for err in exc.errors() if err["type"] not in _LISTED_ERROR_KINDS
+ ]
+ if other_errors:
error_msg += "\n\nOther validation errors:"
- for err in exc.errors():
- error_msg += f"\n{'.'.join(map(str, err['loc']))}: {err['type']}: {err['msg']}"
+ for other_error in other_errors:
+ error_msg += f"\n{other_error}"
return PydanticValidationErrorAnalysis(
error_msg=error_msg,
@@ -139,6 +154,7 @@ def analyze_pydantic_validation_error(exc: ValidationError) -> PydanticValidatio
literal_errors=literal_errors,
union_tag_errors=union_tag_errors,
model_type_errors=model_type_errors,
+ other_errors=other_errors,
)
@@ -218,6 +234,7 @@ def format_pydantic_validation_error_for_agent(exc: ValidationError) -> tuple[st
"literal_errors": analysis.literal_errors,
"union_tag_errors": analysis.union_tag_errors,
"model_type_errors": analysis.model_type_errors,
+ "other_errors": analysis.other_errors,
}
categories = {key: value for key, value in all_categories.items() if value}
@@ -257,6 +274,8 @@ def format_pydantic_validation_error_for_agent(exc: ValidationError) -> tuple[st
category_summaries.append(f"union tag errors: {', '.join(analysis.union_tag_errors)}")
if analysis.model_type_errors:
category_summaries.append(f"model type errors: {', '.join(analysis.model_type_errors)}")
+ if analysis.other_errors:
+ category_summaries.append(f"other errors: {', '.join(analysis.other_errors)}")
error_word = "error" if error_count == 1 else "errors"
if category_summaries:
diff --git a/pipelex/validation_error_types.py b/pipelex/validation_error_types.py
index 69a4b64a8..94e116da1 100644
--- a/pipelex/validation_error_types.py
+++ b/pipelex/validation_error_types.py
@@ -91,6 +91,11 @@ class PipeValidationErrorType(StrEnum):
UNRESOLVED_CONCEPT = "unresolved_concept"
UNRESOLVED_PIPE_DEPENDENCY = "unresolved_pipe_dependency"
+ # A pipe's model field names a handle, alias, preset or waterfall its model deck does not define,
+ # refused when the pipe is built. The item carries the field's path, the reference as written, the
+ # model type and the deck's close matches, so the author can pick one.
+ UNKNOWN_MODEL = "unknown_model"
+
# Generic fallback for unexpected validation errors
UNKNOWN_VALIDATION_ERROR = "unknown_validation_error"
@@ -123,6 +128,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_MODEL
| PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
):
return False
@@ -153,6 +159,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_MODEL
| PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
):
return False
@@ -190,6 +197,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_MODEL
| PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
):
return False
@@ -221,6 +229,7 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_MODEL
| PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
):
return False
@@ -257,6 +266,39 @@ class PipeValidationErrorType(StrEnum):
| PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
| PipeValidationErrorType.UNRESOLVED_CONCEPT
| PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
+ | PipeValidationErrorType.UNKNOWN_MODEL
+ | PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
+ ):
+ return False
+
+ @property
+ def is_unknown_model(self) -> bool:
+ """True for the unknown-model refusal, which the fix planner renames when the deck offers one close match."""
+ match self:
+ case PipeValidationErrorType.UNKNOWN_MODEL:
+ return True
+ case (
+ PipeValidationErrorType.MISSING_INPUT_VARIABLE
+ | PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE
+ | PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH
+ | PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT
+ | PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY
+ | PipeValidationErrorType.CIRCULAR_DEPENDENCY_ERROR
+ | PipeValidationErrorType.LLM_OUTPUT_CANNOT_BE_IMAGE
+ | PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX
+ | PipeValidationErrorType.UNKNOWN_PIPE_TYPE
+ | PipeValidationErrorType.MISSING_PIPE_TYPE
+ | PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION
+ | PipeValidationErrorType.OPTIONAL_MARKER_INVALID
+ | PipeValidationErrorType.OPTIONAL_NOT_HANDLED
+ | PipeValidationErrorType.OPTIONAL_OUTPUT_REQUIRED
+ | PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED
+ | PipeValidationErrorType.OPTIONAL_BRANCH_REQUIRED_FIELD
+ | PipeValidationErrorType.OPTIONAL_FORCE_REDUNDANT
+ | PipeValidationErrorType.INPUT_PRESENCE_VACUOUS
+ | PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION
+ | PipeValidationErrorType.UNRESOLVED_CONCEPT
+ | PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY
| PipeValidationErrorType.UNKNOWN_VALIDATION_ERROR
):
return False
@@ -275,18 +317,18 @@ class PipeFactoryErrorType(StrEnum):
class ValidationResidualErrorType(StrEnum):
- """The ``error_type`` of a validation residual — a failure with no stage-level error data.
-
- A residual is what the wire projection emits when a bundle failed but no categorized
- validation stage produced structured data to report. There is exactly one residual that names
- itself: a dry-run failure surfaces a single message from a raised ``DryRunError`` / ``PipeRunError``,
- so the item is tagged with that exception's own class name.
-
- The other residual — the parse-level one, for a bundle that could not be turned into a
- blueprint at all (a TOML-syntax error, an empty blueprint, an elaborator failure) — carries no
- ``error_type`` and therefore no member here. That is not an omission: it fires for several
- distinct underlying errors, and inventing one code for all of them would tell a consumer it
- knows which fault occurred when it does not. Its message is the authoritative diagnostic.
+ """The ``error_type`` of a failure no validation stage classifies into a code.
+
+ There is exactly one that names itself: a dry-run failure is raised as an error object, a
+ ``DryRunError`` carrying one located failure per pipe whose dry run failed, so each of its items is
+ tagged with that exception's own class name.
+
+ The items no code identifies — the parse-level residual, for a bundle that could not be turned
+ into a blueprint at all (a TOML-syntax error, an empty blueprint, an elaborator failure), and a
+ pydantic error no categorizer knows — carry no ``error_type`` and therefore no member here. That
+ is not an omission: they stand for many distinct underlying errors, and inventing one code for all
+ of them would tell a consumer it knows which fault occurred when it does not. Their message is the
+ authoritative diagnostic.
"""
DRY_RUN_ERROR = "DryRunError"
diff --git a/subject_grants.toml b/subject_grants.toml
index a69a4fa5b..8794935c5 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -4680,10 +4680,6 @@ rationale = "Factory from source: builds the result from the pipe output; single
param = "extra"
rationale = "Derivation: extracts from the extra mapping; single operand."
-["pipelex/pipeline/validate_bundle.py::_backfill_pipe_error_source"]
-param = "pipe_error"
-rationale = "Verb-object: backfills the pipe error in place; single operand."
-
["pipelex/pipeline/validate_bundle.py::_pipes_to_dry_run"]
param = "loaded_pipes"
rationale = "Verb-object: selects among the loaded pipes; the requested codes stay keyword."
@@ -4704,6 +4700,10 @@ rationale = "Verb-object: validates the bundle file at the path; options stay ke
param = "directory"
rationale = "Verb-object: validates bundles from the directory; options stay keyword."
+["pipelex/pipeline/validate_bundle_translation.py::_backfill_pipe_error_source"]
+param = "pipe_error"
+rationale = "Verb-object: backfills the pipe error in place; single operand."
+
["pipelex/pipeline/validation_render.py::_markdown_category_header"]
param = "category"
rationale = "Noun-named derivation: the header text for the category; single operand."
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 34d857991..87aafe4d1 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -227,6 +227,7 @@ PipeInputsFactoryError | Pipe inputs factory | https://docs.pipelex.com/latest/e
PipeJobError | Pipe job | https://docs.pipelex.com/latest/errors/pipe-job-error/
PipeLLMFactoryError | Pipe LLM factory | https://docs.pipelex.com/latest/errors/pipe-llm-factory-error/
PipeLibraryError | Pipe library | https://docs.pipelex.com/latest/errors/pipe-library-error/
+PipeLoadRefusalError | Pipe load refusal | https://docs.pipelex.com/latest/errors/pipe-load-refusal-error/
PipeLoadingError | Pipe loading | https://docs.pipelex.com/latest/errors/pipe-loading-error/
PipeNotFoundError | Pipe not found | https://docs.pipelex.com/latest/errors/pipe-not-found-error/
PipeOperatorModelAvailabilityError | Pipe operator model availability | https://docs.pipelex.com/latest/errors/pipe-operator-model-availability-error/
diff --git a/tests/e2e/pipelex/pipes/optionals/test_guarded_condition_mthds.py b/tests/e2e/pipelex/pipes/optionals/test_guarded_condition_mthds.py
index 826a51cd2..590ef6702 100644
--- a/tests/e2e/pipelex/pipes/optionals/test_guarded_condition_mthds.py
+++ b/tests/e2e/pipelex/pipes/optionals/test_guarded_condition_mthds.py
@@ -8,11 +8,12 @@ from pathlib import Path
import pytest
-from pipelex.base_exceptions import PipelexError
from pipelex.core.memory.absence import AbsenceKind
+from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.pipeline_response import RunState
from pipelex.pipeline.runner import PipelexMTHDSProtocol
from pipelex.system.registries.func_registry_utils import FuncRegistryUtils
+from pipelex.validation_error_types import PipeValidationErrorType
_FIXTURE_DIR = Path(__file__).parent / "guarded_condition"
_BUNDLE_PATH = _FIXTURE_DIR / "guarded_condition.mthds"
@@ -64,11 +65,13 @@ class TestGuardedConditionExpression:
FuncRegistryUtils.register_funcs_in_folder(folder_path=_FIXTURE_DIR)
runner = PipelexMTHDSProtocol()
- with pytest.raises(PipelexError) as exc_info:
+ with pytest.raises(ValidateBundleError) as exc_info:
await runner.execute(mthds_contents=[unguarded_text], inputs={})
- # The load-time guard lint (OPTIONAL_INPUT_UNGUARDED) is raised inside a pydantic validator,
- # so it surfaces wrapped in a PipeExecutionError → pydantic ValidationError rather than on the
- # __cause__ chain. Match its distinctive verdict text: the missing-function error (the wrong
- # reason this control used to pass for) never contains "unguarded".
- assert "'flag' unguarded" in str(exc_info.value)
+ # The load-time guard lint (OPTIONAL_INPUT_UNGUARDED) is raised inside a pydantic validator, and
+ # the run refuses the bundle with the verdict validating it gives: its item names the lint, so
+ # the missing-function error (the wrong reason this control used to pass for) cannot pass it.
+ items = exc_info.value.to_error_report().validation_errors or []
+ unguarded_items = [item for item in items if item.error_type == PipeValidationErrorType.OPTIONAL_INPUT_UNGUARDED]
+ assert unguarded_items, f"expected an optional_input_unguarded item, got {items!r}"
+ assert "'flag'" in unguarded_items[0].message
diff --git a/tests/e2e/test_signature_validation_mthds.py b/tests/e2e/test_signature_validation_mthds.py
index 007a9efc9..8134ae33b 100644
--- a/tests/e2e/test_signature_validation_mthds.py
+++ b/tests/e2e/test_signature_validation_mthds.py
@@ -5,6 +5,7 @@ from pathlib import Path
import pytest
from pipelex.core.stuffs.text_content import TextContent
+from pipelex.pipe_run.located_failure import find_root_fault
from pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableError
from pipelex.pipeline.bundle_validator import DryRunStatus
from pipelex.pipeline.exceptions import PipelineExecutionError
@@ -84,6 +85,8 @@ class TestSignatureValidationE2E:
pipe_code="summarize_doc",
inputs={"doc": TextContent(text="A document to summarize.")},
)
- cause = exc_info.value.__cause__
- assert isinstance(cause, PipeSignatureNotExecutableError)
- assert cause.pipe_ref.endswith("summarize_doc")
+ # The signature's refusal is the run failure's root fault, under the router's location.
+ root_fault = find_root_fault(error=exc_info.value)
+ assert isinstance(root_fault, PipeSignatureNotExecutableError)
+ assert root_fault.pipe_ref.endswith("summarize_doc")
+ assert exc_info.value.to_error_report().error_type == "PipeSignatureNotExecutableError"
diff --git a/tests/integration/pipelex/builder/operations/test_factory_refusal_verdicts.py b/tests/integration/pipelex/builder/operations/test_factory_refusal_verdicts.py
new file mode 100644
index 000000000..7a0100854
--- /dev/null
+++ b/tests/integration/pipelex/builder/operations/test_factory_refusal_verdicts.py
@@ -0,0 +1,228 @@
+"""Pin: a pipe factory's refusal, and a refusal raised while the builder's validate ops load libraries, is a verdict.
+
+A pipe factory refuses a blueprint it cannot build, such as a ``PipeExtract`` whose input is neither an
+image nor a document. Its error classes declared no domain, so the validation translation did not
+recognise them and they escaped every validator raw. They are now the author's input, caller-facing, so
+the refusal validates to one item located on the pipe and its file, carrying the next step. The builder's
+``validate_ops.validate_pipe`` and ``validate_all`` loaded libraries outside the translation, so a refusal
+there escaped raw too; they now answer it with the same verdict. The agent CLI's ``validate_all_core``
+translated its load only after the failed library was torn down, so its items lost their file; they keep it now.
+"""
+
+from pathlib import Path
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import DisclosureMode, ErrorDomain, PipelexError, ValidationErrorCategory, ValidationErrorItem
+from pipelex.builder.operations.validate_ops import validate_all, validate_pipe
+from pipelex.cli.agent_cli.commands.validate._validate_core import validate_all_core
+from pipelex.core.pipes.exceptions import PipeLoadRefusalError
+from pipelex.interpreter_hub import get_library_manager
+from pipelex.libraries.exceptions import LibraryError
+from pipelex.libraries.pipe.exceptions import EntryPipeAmbiguousError
+from pipelex.pipe_controllers.condition.exceptions import PipeConditionFactoryError
+from pipelex.pipe_controllers.parallel.exceptions import PipeParallelFactoryError
+from pipelex.pipe_operators.compose.exceptions import PipeComposeFactoryError
+from pipelex.pipe_operators.extract.exceptions import PipeExtractFactoryError
+from pipelex.pipe_operators.llm.exceptions import PipeLLMFactoryError
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle import validate_bundle
+
+_DOMAIN = "almanac_reading"
+
+_TEXT_INPUT_EXTRACT_BUNDLE = f"""
+domain = "{_DOMAIN}"
+description = "Read the pages of a tide almanac"
+main_pipe = "read_almanac_pages"
+
+[pipe.read_almanac_pages]
+type = "PipeExtract"
+description = "Read each page of the tide almanac"
+inputs = {{ almanac_text = "Text" }}
+output = "Page[]"
+"""
+
+_SEQUENCE_OUTPUT_MISMATCH_BUNDLE = f"""
+domain = "{_DOMAIN}"
+description = "Read the pages of a tide almanac"
+
+[pipe.summarize_almanac]
+type = "PipeSequence"
+description = "Summarize the tide almanac"
+inputs = {{ almanac_text = "Text" }}
+output = "Text[]"
+steps = [{{ pipe = "write_summary", result = "summary" }}]
+
+[pipe.write_summary]
+type = "PipeLLM"
+description = "Write the summary of the tide almanac"
+inputs = {{ almanac_text = "Text" }}
+output = "Text"
+prompt = "Summarize this tide almanac: $almanac_text"
+"""
+
+_INHERITED_SYSTEM_PROMPT_BUNDLE = """
+domain = "almanac_notes"
+description = "Write notes about a tide almanac"
+system_prompt = "You write for {% if %} harbour users."
+
+[pipe.write_note]
+type = "PipeLLM"
+description = "Write a note about the tide almanac"
+inputs = { almanac_text = "Text" }
+output = "Text"
+prompt = "Write a note about this tide almanac: $almanac_text"
+"""
+
+
+def _write_named_pipe_bundle(*, directory: Path, domain_code: str) -> None:
+ content = f"""
+domain = "{domain_code}"
+description = "Write notes for the harbour board"
+
+[pipe.write_note]
+type = "PipeLLM"
+description = "Write a note for the harbour board"
+inputs = {{ tide_times = "Text" }}
+output = "Text"
+prompt = "Write a note from these tide times: $tide_times"
+"""
+ (directory / f"{domain_code}.mthds").write_text(content, encoding="utf-8")
+
+
+_NEXT_STEP = "Declare this input as an Image or a Document, or as a concept that refines one of them."
+
+_FACTORY_REFUSAL_CLASSES: list[type[PipelexError]] = [
+ PipeLLMFactoryError,
+ PipeComposeFactoryError,
+ PipeExtractFactoryError,
+ PipeConditionFactoryError,
+ PipeParallelFactoryError,
+]
+
+
+def _write_bundle(*, directory: Path, content: str = _TEXT_INPUT_EXTRACT_BUNDLE) -> Path:
+ bundle_path = directory / "bundle.mthds"
+ bundle_path.write_text(content, encoding="utf-8")
+ return bundle_path
+
+
+def _assert_located_extract_item(*, items: list[ValidationErrorItem], bundle_path: Path) -> None:
+ (item,) = items
+ assert item.category == ValidationErrorCategory.PIPE_VALIDATION
+ assert item.pipe_code == "read_almanac_pages"
+ assert item.domain_code == _DOMAIN
+ assert item.source == str(bundle_path)
+ assert "The input 'almanac_text' of PipeExtract 'read_almanac_pages' is a native.Text" in item.message
+ assert _NEXT_STEP in item.message
+
+
[email protected](loop_scope="class")
+class TestFactoryRefusalVerdicts:
+ @pytest.mark.parametrize("error_class", _FACTORY_REFUSAL_CLASSES, ids=[error_class.__name__ for error_class in _FACTORY_REFUSAL_CLASSES])
+ async def test_factory_refusal_is_the_authors_caller_facing_input(self, error_class: type[PipelexError]) -> None:
+ report = error_class("The pipe cannot be built from this blueprint.").to_error_report()
+
+ assert report.error_domain == ErrorDomain.INPUT
+ assert report.caller_facing_message
+ assert report.http_status == 422
+
+ async def test_validate_bundle_locates_the_extract_refusal_with_its_next_step(self, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[tmp_path])
+
+ assert isinstance(raised.value.__cause__, PipeLoadRefusalError)
+ assert isinstance(raised.value.__cause__.__cause__, PipeExtractFactoryError)
+ report = raised.value.to_error_report()
+ _assert_located_extract_item(items=report.validation_errors or [], bundle_path=bundle_path)
+ (strict_item,) = report.to_dict(disclosure_mode=DisclosureMode.STRICT)["validation_errors"]
+ assert _NEXT_STEP in strict_item["message"]
+
+ async def test_validate_ops_validate_pipe_answers_a_load_refusal_with_the_verdict(self, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_pipe("read_almanac_pages", library_dirs=[tmp_path])
+
+ _assert_located_extract_item(items=raised.value.to_error_report().validation_errors or [], bundle_path=bundle_path)
+
+ async def test_validate_ops_validate_all_answers_a_load_refusal_with_the_verdict(self, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_all(library_dirs=[tmp_path])
+
+ _assert_located_extract_item(items=raised.value.to_error_report().validation_errors or [], bundle_path=bundle_path)
+
+ async def test_validate_ops_validate_all_locates_a_wiring_refusal_on_its_file(self, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=_SEQUENCE_OUTPUT_MISMATCH_BUNDLE)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_all(library_dirs=[tmp_path])
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert item.pipe_code == "summarize_almanac"
+ assert item.source == str(bundle_path)
+
+ async def test_agent_validate_all_locates_a_wiring_refusal_on_its_file(self, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=_SEQUENCE_OUTPUT_MISMATCH_BUNDLE)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_all_core(library_dirs=[tmp_path])
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert item.pipe_code == "summarize_almanac"
+ assert item.source == str(bundle_path)
+
+ async def test_validate_ops_validate_all_lets_a_teardown_fault_propagate(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ _write_bundle(directory=tmp_path, content=_SEQUENCE_OUTPUT_MISMATCH_BUNDLE.replace('output = "Text[]"', 'output = "Text"'))
+ library_manager = get_library_manager()
+ real_teardown = library_manager.teardown
+ fault = LibraryError("the library could not be torn down")
+
+ def _teardown_then_fail(*, library_id: str) -> None:
+ real_teardown(library_id=library_id)
+ raise fault
+
+ mocker.patch.object(library_manager, "teardown", side_effect=_teardown_then_fail)
+
+ with pytest.raises(LibraryError) as raised:
+ await validate_all(library_dirs=[tmp_path])
+
+ assert raised.value is fault
+
+ async def test_validate_ops_validate_pipe_keeps_an_ambiguous_code_out_of_the_verdict(self, tmp_path: Path) -> None:
+ _write_named_pipe_bundle(directory=tmp_path, domain_code="harbour_notes")
+ _write_named_pipe_bundle(directory=tmp_path, domain_code="quay_notes")
+
+ with pytest.raises(EntryPipeAmbiguousError):
+ await validate_pipe("write_note", library_dirs=[tmp_path])
+
+ async def test_an_inherited_system_prompt_refusal_quotes_no_token_of_it(self, tmp_path: Path) -> None:
+ content = _INHERITED_SYSTEM_PROMPT_BUNDLE.replace("You write for {% if %} harbour users.", "You write for {% quay_ledger %} harbour users.")
+ bundle_path = _write_bundle(directory=tmp_path, content=content)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[tmp_path])
+
+ # Jinja2's diagnosis names the unknown tag; the verdict must not.
+ strict_report = raised.value.to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert "quay_ledger" not in str(strict_report)
+
+ async def test_an_inherited_system_prompt_refusal_names_the_domain(self, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=_INHERITED_SYSTEM_PROMPT_BUNDLE)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[tmp_path])
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert item.pipe_code == "write_note"
+ assert item.source == str(bundle_path)
+ assert "system prompt of domain 'almanac_notes', which it inherits, for pipe 'write_note' in domain" in item.message
+ assert item.message.endswith("it does not parse at line 1 of that prompt.")
+ # The inherited prompt may be a host's, so its text never rides the caller-facing verdict.
+ strict_report = raised.value.to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert "harbour users" not in str(strict_report)
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.py
index cc81b5837..21b4341d6 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
@@ -93,6 +93,11 @@ class TestRunErrorChain:
assert payload["model"] == WORKER_MODEL
assert payload["provider"] == WORKER_PROVIDER
assert payload["pipe_code"] == "greet"
+ assert payload["pipe_stack"] == ["greet"]
+ # The cause fields name the root fault, not the router wrapper right under the run error.
+ assert payload["cause_type"] == "LLMCompletionError"
+ assert payload["cause_message"] == WORKER_ERROR_MESSAGE
+ assert payload["message"] == f"Pipe 'greet' failed: {WORKER_ERROR_MESSAGE}"
# error_source is the cause chain, outermost first: runner -> router -> pipe operator -> worker.
error_source: list[str] = payload["error_source"]
diff --git a/tests/integration/pipelex/cli/test_agent_validate_pipe_dry_run_items.py b/tests/integration/pipelex/cli/test_agent_validate_pipe_dry_run_items.py
new file mode 100644
index 000000000..ea6577020
--- /dev/null
+++ b/tests/integration/pipelex/cli/test_agent_validate_pipe_dry_run_items.py
@@ -0,0 +1,68 @@
+"""Pin: ``pipelex-agent validate pipe`` and ``validate --all`` answer a failing dry run with its located item.
+
+They go through the same bundle-loading cascade and item builder as ``validate bundle``, so a pipe whose
+dry run fails is an invalid verdict (``is_valid: false``, exit 1) carrying one ``dry_run`` item for the
+innermost failing pipe, where they used to answer it with no ``validation_errors`` at all. Validating the
+sequence that runs the failing parallel reports the parallel, once.
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+import typer
+from pytest_mock import MockerFixture
+
+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format
+from pipelex.cli.agent_cli.commands.validate.pipe_cmd import validate_pipe_cmd as agent_validate_pipe_cmd
+from tests.integration.pipelex.test_data import ValidationDetailBundles
+
+_PIPE_CMD_MODULE = "pipelex.cli.agent_cli.commands.validate.pipe_cmd"
+
+
+def library_dir(tmp_path: Path) -> Path:
+ (tmp_path / "bundle.mthds").write_text(ValidationDetailBundles.NESTED_PARALLEL_MISMATCH, encoding="utf-8")
+ return tmp_path
+
+
+class TestAgentValidatePipeDryRunItems:
+ @pytest.mark.parametrize(
+ ("pipe_code", "validate_all"),
+ [("analyze_topic", False), ("run_workshop", False), (None, True)],
+ ids=["failing_pipe", "enclosing_pipe", "all"],
+ )
+ def test_a_failing_dry_run_is_an_invalid_verdict_with_the_located_item(
+ self,
+ mocker: MockerFixture,
+ capsys: pytest.CaptureFixture[str],
+ library_dir: Path,
+ pipe_code: str | None,
+ validate_all: bool,
+ ) -> None:
+ mocker.patch(f"{_PIPE_CMD_MODULE}.make_pipelex_for_agent_cli")
+ mocker.patch(f"{_PIPE_CMD_MODULE}.Pipelex.teardown_if_needed")
+ mocker.patch(f"{_PIPE_CMD_MODULE}.resolve_pipe_from_exports", return_value=[])
+ try:
+ with pytest.raises(typer.Exit) as exc_info:
+ agent_validate_pipe_cmd(
+ pipe_code=pipe_code,
+ validate_all=validate_all,
+ library_dir=[str(library_dir)],
+ output_format=CliOutputFormat.JSON,
+ )
+ finally:
+ set_agent_cli_error_format(CliOutputFormat.JSON)
+
+ assert exc_info.value.exit_code == 1
+ envelope: dict[str, Any] = json.loads(capsys.readouterr().err)
+ assert envelope["is_valid"] is False
+ assert envelope["error_type"] == "ValidateBundleError"
+ (item,) = envelope["validation_errors"]
+ assert item["category"] == "dry_run"
+ assert item["error_type"] == "DryRunError"
+ assert item["pipe_code"] == "analyze_topic"
+ assert item["domain_code"] == ValidationDetailBundles.DOMAIN
+ assert item["source"] == str(library_dir / "bundle.mthds")
+ assert not any(marker in item["message"] for marker in ValidationDetailBundles.RECORD_REPR_MARKERS)
diff --git a/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py b/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py
new file mode 100644
index 000000000..ec3e8b458
--- /dev/null
+++ b/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py
@@ -0,0 +1,176 @@
+"""Pin: the local run commands report an invalid bundle the way ``validate`` does.
+
+A run refuses an invalid bundle while loading it, before any pipe runs, with the ``ValidateBundleError``
+verdict. These tests drive the real run cores on a bundle whose pipe names a misspelled concept:
+
+- ``pipelex run bundle`` prints the grouped invalid-bundle panel ``validate`` prints, with the located
+ item, and exits 1 — whether the bundle is run from its directory (loaded as a library directory) or as
+ a file, and whether the parse or the load refuses it. It used to print one line, ``Failed to execute
+ pipeline '<pipe>': Could not load blueprints from [...] because of: …``.
+- ``pipelex-agent run bundle`` copies the verdict's ``validation_errors`` into its error envelope, and its
+ markdown error renders them as the same grouped prose ``validate`` prints.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any, cast
+
+import pytest
+import typer
+from mthds.runners.types import RunnerType
+from rich.console import Console
+
+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format
+from pipelex.cli.agent_cli.commands.run.bundle_cmd import run_bundle_cmd as agent_run_bundle_cmd
+from pipelex.cli.commands.run._run_core import _execute_run # pyright: ignore[reportPrivateUsage]
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+_MISSPELLED_CONCEPT_BUNDLE = """
+domain = "harbour_notices"
+description = "Write notices for the harbour board"
+main_pipe = "write_tide_notice"
+
+[concept.TideNotice]
+description = "A notice telling harbour users when the tide turns"
+
+[pipe.write_tide_notice]
+type = "PipeLLM"
+description = "Write the tide notice for the harbour board"
+inputs = { tide_times = "Text" }
+output = "TideNotise"
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+_TOML_SYNTAX_ERROR_BUNDLE = """
+domain = "harbour_notices
+main_pipe = "write_tide_notice"
+"""
+
+
+def console(mocker: MockerFixture) -> Console:
+ """A recording console patched into the error handlers, so the panel can be read back."""
+ recorded_console = Console(width=200, record=True, color_system=None)
+ mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)
+ return recorded_console
+
+
+def _write_bundle(*, directory: Path, content: str) -> Path:
+ bundle_path = directory / "bundle.mthds"
+ bundle_path.write_text(content, encoding="utf-8")
+ return bundle_path
+
+
+def _run_bundle(*, bundle_path: Path, library_dir: list[str] | None) -> None:
+ asyncio.run(
+ _execute_run(
+ pipe_code=None,
+ bundle_path=str(bundle_path),
+ inputs=None,
+ save_working_memory=False,
+ working_memory_path=None,
+ save_main_stuff=False,
+ no_pretty_print=True,
+ graph=False,
+ graph_full_data=None,
+ output_dir=str(bundle_path.parent / "outputs"),
+ dry_run=True,
+ mock_usage=False,
+ mock_inputs=True,
+ library_dir=library_dir,
+ costs=False,
+ )
+ )
+
+
+def _run_agent_bundle(*, bundle_path: Path, output_format: CliOutputFormat) -> None:
+ context = cast("typer.Context", SimpleNamespace(obj={"runner": RunnerType.PIPELEX}))
+ try:
+ agent_run_bundle_cmd(
+ ctx=context,
+ path=str(bundle_path.parent),
+ pipe=None,
+ inputs=None,
+ dry_run=True,
+ mock_inputs=True,
+ graph=False,
+ costs=False,
+ library_dir=None,
+ with_memory=False,
+ output_format=output_format,
+ error_format=None,
+ )
+ finally:
+ set_agent_cli_error_format(CliOutputFormat.JSON)
+
+
+class TestRunBundleVerdictCli:
+ @pytest.mark.parametrize("from_directory", [True, False], ids=["directory", "file"])
+ def test_run_bundle_renders_the_invalid_bundle_panel(self, console: Console, tmp_path: Path, from_directory: bool) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=_MISSPELLED_CONCEPT_BUNDLE)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ _run_bundle(bundle_path=bundle_path, library_dir=[str(tmp_path)] if from_directory else None)
+
+ assert exc_info.value.exit_code == 1
+ output = console.export_text()
+ assert "Bundle validation failed" in output
+ assert "Pipe Validation Errors:" in output
+ assert "Concept 'TideNotise' in pipe.write_tide_notice.output is not declared" in output
+ assert "Could not load blueprints from" not in output
+ assert "Traceback" not in output
+
+ def test_run_bundle_renders_a_bundle_that_does_not_parse_as_an_invalid_bundle(self, console: Console, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=_TOML_SYNTAX_ERROR_BUNDLE)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ _run_bundle(bundle_path=bundle_path, library_dir=None)
+
+ assert exc_info.value.exit_code == 1
+ output = console.export_text()
+ assert "Bundle validation failed" in output
+ assert "TOML syntax error at line 2" in output
+
+ def test_agent_run_bundle_carries_the_validation_errors(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:
+ mocker.patch("pipelex.cli.agent_cli.commands.run.bundle_cmd.make_pipelex_for_agent_cli")
+ mocker.patch("pipelex.cli.agent_cli.commands.run.bundle_cmd.Pipelex.teardown_if_needed")
+ bundle_path = _write_bundle(directory=tmp_path, content=_MISSPELLED_CONCEPT_BUNDLE)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ _run_agent_bundle(bundle_path=bundle_path, output_format=CliOutputFormat.JSON)
+
+ assert exc_info.value.exit_code == 1
+ envelope: dict[str, Any] = json.loads(capsys.readouterr().err)
+ assert envelope["error_type"] == "ValidateBundleError"
+ assert envelope["error_domain"] == "input"
+ concept_items = [item for item in envelope["validation_errors"] if item.get("error_type") == "unresolved_concept"]
+ assert concept_items, f"expected an unresolved_concept item, got {envelope['validation_errors']!r}"
+ (item,) = concept_items
+ assert item["pipe_code"] == "write_tide_notice"
+ assert item["concept_code"] == "TideNotise"
+ assert item["field_path"] == "pipe.write_tide_notice.output"
+ assert item["source"] == str(bundle_path)
+
+ def test_agent_run_bundle_markdown_renders_the_items_as_prose(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path
+ ) -> None:
+ mocker.patch("pipelex.cli.agent_cli.commands.run.bundle_cmd.make_pipelex_for_agent_cli")
+ mocker.patch("pipelex.cli.agent_cli.commands.run.bundle_cmd.Pipelex.teardown_if_needed")
+ bundle_path = _write_bundle(directory=tmp_path, content=_MISSPELLED_CONCEPT_BUNDLE)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ _run_agent_bundle(bundle_path=bundle_path, output_format=CliOutputFormat.MARKDOWN)
+
+ assert exc_info.value.exit_code == 1
+ markdown = capsys.readouterr().err
+ assert markdown.startswith("# Error: ValidateBundleError")
+ assert "## Pipe validation errors" in markdown
+ assert "Concept 'TideNotise' in pipe.write_tide_notice.output is not declared" in markdown
+ assert '"validation_errors"' not in markdown
diff --git a/tests/integration/pipelex/cli/test_run_located_failure_panel.py b/tests/integration/pipelex/cli/test_run_located_failure_panel.py
new file mode 100644
index 000000000..bef36affb
--- /dev/null
+++ b/tests/integration/pipelex/cli/test_run_located_failure_panel.py
@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+import typer
+from rich.console import Console
+
+from pipelex.cli.commands.run._run_core import _execute_run # pyright: ignore[reportPrivateUsage]
+from tests.integration.pipelex.pipeline.test_data import LocatedRunFailureTestData
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+
[email protected](loop_scope="class")
+class TestRunLocatedFailurePanel:
+ async def test_unserved_model_renders_the_model_panel_at_the_failing_step(
+ self,
+ mocker: MockerFixture,
+ tmp_path: Path,
+ capsys: pytest.CaptureFixture[str],
+ ) -> None:
+ """`pipelex run` on the model example renders the model panel naming the failing step, its next step, and the local-deck tip there only."""
+ console = Console(width=400, record=True, color_system=None)
+ mocker.patch("pipelex.cli.error_handlers.get_console", return_value=console)
+ mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=console)
+ bundle_path = tmp_path / "located_failure_model.mthds"
+ bundle_path.write_text(LocatedRunFailureTestData.MODEL_MTHDS, encoding="utf-8")
+
+ with pytest.raises(typer.Exit) as exit_info:
+ await _execute_run(
+ pipe_code="two_steps",
+ bundle_path=str(bundle_path),
+ inputs='{"topic": "cats"}',
+ save_working_memory=False,
+ working_memory_path=None,
+ save_main_stuff=False,
+ no_pretty_print=True,
+ graph=False,
+ graph_full_data=None,
+ output_dir=str(tmp_path / "outputs"),
+ dry_run=False,
+ mock_usage=False,
+ mock_inputs=False,
+ library_dir=None,
+ )
+
+ assert exit_info.value.exit_code == 1
+ panel = console.export_text()
+ assert "Pipe run failed because a model wasn't available" in panel
+ assert "Pipe: 'summarize' (PipeLLM)" in panel
+ assert f"Model: '{LocatedRunFailureTestData.UNSERVED_MODEL_HANDLE}'" in panel
+ assert "Pipe Stack: two_steps → summarize" in panel
+ assert f"Error: Model handle '{LocatedRunFailureTestData.UNSERVED_MODEL_HANDLE}' was not found in the model deck." in panel
+ # The step names a model no entry of the deck names: the tip gives the caller's next step first,
+ # then the local-deck remedy, which lives in the panel's tip and nowhere in the error's own message.
+ assert f"💡 Tip: Change the model '{LocatedRunFailureTestData.UNSERVED_MODEL_HANDLE}' to an LLM the model deck serves." in panel
+ assert "Your local model deck may be out of date" in panel
+ assert "run 'pipelex init inference'" in panel
+ # The one-line fallback naming the entry pipe is not printed.
+ assert "Failed to execute pipeline" not in capsys.readouterr().err
diff --git a/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py b/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py
new file mode 100644
index 000000000..2c9a00a4f
--- /dev/null
+++ b/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py
@@ -0,0 +1,176 @@
+"""Pin: the local CLIs answer a load-time refusal and a failing dry run as a negative verdict (exit 1).
+
+On the validate surface exit 1 is a produced negative verdict and exit 2 is "no verdict could be
+produced". These tests drive the real validation engine through the command cores:
+
+- ``pipelex validate bundle`` on a bundle naming an unknown model prints the grouped invalid-bundle
+ panel with the ``unknown_model`` item and exits 1, with no traceback;
+- ``pipelex-agent validate bundle`` on the same bundle emits its invalid-verdict envelope
+ (``is_valid: false`` and the item) and exits 1, where it used to answer the no-verdict envelope with
+ exit 2;
+- ``pipelex validate pipe <code>`` on a pipe whose dry run fails, and ``pipelex validate --all`` on the
+ same library, print the invalid-bundle panel and exit 1, where they used to print a traceback;
+- ``pipelex validate pipe <code>`` on a library naming an unknown model exits 1 with the item.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import TYPE_CHECKING
+
+import pytest
+import typer
+from rich.console import Console
+
+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format
+from pipelex.cli.agent_cli.commands.validate.bundle_cmd import validate_bundle_cmd as agent_validate_bundle_cmd
+from pipelex.cli.commands.validate._validate_core import (
+ _validate_pipe_or_bundle, # pyright: ignore[reportPrivateUsage]
+ do_validate_all_libraries_and_dry_run,
+)
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.test_extras.mthds_corpus.loader import get_entry
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+_UNKNOWN_MODEL_BUNDLE = """
+domain = "tide_tables"
+description = "Write the note telling harbour users when the tide turns"
+main_pipe = "write_tide_note"
+
+[pipe.write_tide_note]
+type = "PipeLLM"
+description = "Write the tide note for the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text"
+model = "gpt-5.1"
+prompt = "Write a short note for the harbour board from these tide times: $tide_times"
+"""
+
+# The corpus's dry-run residual: a PipeCondition whose rule renders to nothing, so its dry run fails.
+_DRY_RUN_FAILURE_ENTRY = "invalid_dry_run_residual"
+_DRY_RUN_FAILURE_PIPE = "route_parcel"
+
+
+def console(mocker: MockerFixture) -> Console:
+ """A recording console patched into the error handlers, so the panel can be read back."""
+ recorded_console = Console(width=200, record=True, color_system=None)
+ mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)
+ return recorded_console
+
+
+def restore_current_library() -> Iterator[None]:
+ """The pipe and --all paths leave their library open and current (the command's teardown owns it)."""
+ outer_library_id = get_current_library_id_or_none()
+ yield
+ current_library_id = get_current_library_id_or_none()
+ if current_library_id is not None and current_library_id != outer_library_id:
+ get_library_manager().teardown(library_id=current_library_id)
+ if outer_library_id is not None:
+ set_current_library(library_id=outer_library_id)
+ else:
+ clear_current_library()
+
+
+def unknown_model_bundle(tmp_path: Path) -> Path:
+ bundle_path = tmp_path / "bundle.mthds"
+ bundle_path.write_text(_UNKNOWN_MODEL_BUNDLE, encoding="utf-8")
+ return bundle_path
+
+
+class TestValidateLoadRefusalsCli:
+ def test_bare_validate_bundle_renders_the_unknown_model_as_an_invalid_bundle(self, console: Console, unknown_model_bundle: Path) -> None:
+ with pytest.raises(typer.Exit) as exc_info:
+ asyncio.run(_validate_pipe_or_bundle(bundle_path=unknown_model_bundle, library_dirs=[unknown_model_bundle.parent]))
+
+ assert exc_info.value.exit_code == 1
+ output = console.export_text()
+ assert "Bundle validation failed" in output
+ assert "Pipe Validation Errors:" in output
+ assert "Unknown Model" in output
+ assert "Model handle 'gpt-5.1' was not found in the model deck" in output
+ assert "Path: pipe.write_tide_note.model" in output
+ assert "Traceback" not in output
+
+ def test_agent_validate_bundle_emits_the_invalid_verdict_envelope(
+ self,
+ mocker: MockerFixture,
+ capsys: pytest.CaptureFixture[str],
+ unknown_model_bundle: Path,
+ ) -> None:
+ mocker.patch("pipelex.cli.agent_cli.commands.validate.bundle_cmd.make_pipelex_for_agent_cli")
+ mocker.patch("pipelex.cli.agent_cli.commands.validate.bundle_cmd.Pipelex.teardown_if_needed")
+ try:
+ with pytest.raises(typer.Exit) as exc_info:
+ agent_validate_bundle_cmd(
+ path=str(unknown_model_bundle),
+ library_dir=[str(unknown_model_bundle.parent)],
+ output_format=CliOutputFormat.JSON,
+ )
+ finally:
+ set_agent_cli_error_format(CliOutputFormat.JSON)
+
+ assert exc_info.value.exit_code == 1
+ envelope = json.loads(capsys.readouterr().err)
+ assert envelope["is_valid"] is False
+ assert envelope["error_type"] == "ValidateBundleError"
+ assert envelope["error_domain"] == "input"
+ (item,) = envelope["validation_errors"]
+ assert item["category"] == "pipe_validation"
+ assert item["error_type"] == "unknown_model"
+ assert item["pipe_code"] == "write_tide_note"
+ assert item["domain_code"] == "tide_tables"
+ assert item["source"] == str(unknown_model_bundle)
+ assert item["field_path"] == "pipe.write_tide_note.model"
+ assert item["model_reference"] == "gpt-5.1"
+ assert item["model_type"] == "llm"
+ assert item["suggestions"]
+
+ @pytest.mark.usefixtures("restore_current_library")
+ def test_bare_validate_pipe_renders_a_failing_dry_run_as_an_invalid_bundle(self, console: Console) -> None:
+ entry = get_entry(name=_DRY_RUN_FAILURE_ENTRY)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ asyncio.run(_validate_pipe_or_bundle(pipe_code=_DRY_RUN_FAILURE_PIPE, library_dirs=[entry.directory]))
+
+ assert exc_info.value.exit_code == 1
+ output = console.export_text()
+ assert "Bundle validation failed" in output
+ assert "Dry Run Errors:" in output
+ assert f"Pipe: {_DRY_RUN_FAILURE_PIPE}" in output
+ assert "Traceback" not in output
+
+ @pytest.mark.usefixtures("restore_current_library")
+ def test_bare_validate_all_renders_a_failing_dry_run_as_an_invalid_bundle(self, console: Console) -> None:
+ entry = get_entry(name=_DRY_RUN_FAILURE_ENTRY)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ do_validate_all_libraries_and_dry_run(library_dirs=[entry.directory])
+
+ assert exc_info.value.exit_code == 1
+ output = console.export_text()
+ assert "Bundle validation failed" in output
+ assert "Dry Run Errors:" in output
+ assert f"Pipe: {_DRY_RUN_FAILURE_PIPE}" in output
+ assert "Traceback" not in output
+
+ @pytest.mark.usefixtures("restore_current_library")
+ def test_bare_validate_pipe_renders_an_unknown_model_in_the_library_as_an_invalid_bundle(
+ self, console: Console, unknown_model_bundle: Path
+ ) -> None:
+ with pytest.raises(typer.Exit) as exc_info:
+ asyncio.run(_validate_pipe_or_bundle(pipe_code="write_tide_note", library_dirs=[unknown_model_bundle.parent]))
+
+ assert exc_info.value.exit_code == 1
+ output = console.export_text()
+ assert "Unknown Model" in output
+ assert "Path: pipe.write_tide_note.model" in output
+ assert "Traceback" not in output
diff --git a/tests/integration/pipelex/cli/test_validate_parallel_multiplicity_next_step.py b/tests/integration/pipelex/cli/test_validate_parallel_multiplicity_next_step.py
new file mode 100644
index 000000000..a5bd12e34
--- /dev/null
+++ b/tests/integration/pipelex/cli/test_validate_parallel_multiplicity_next_step.py
@@ -0,0 +1,288 @@
+"""Pin: a `PipeParallel` whose branch and field differ in multiplicity is refused with its next step.
+
+The combine of the branch results is the existing check, reached in the dry run of validate; it stays as
+it is. What these tests pin is what the refusal carries: the branch, the result, the field and which of
+the two multiplicities to change, on ``pipelex validate bundle`` and in ``pipelex-agent validate bundle``'s
+JSON, and a top-level next step that sends the reader to the items instead of to "the array".
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import TYPE_CHECKING
+
+import pytest
+import typer
+from rich.console import Console
+
+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format
+from pipelex.cli.agent_cli.commands.validate.bundle_cmd import validate_bundle_cmd as agent_validate_bundle_cmd
+from pipelex.cli.commands.validate._validate_core import _validate_pipe_or_bundle # pyright: ignore[reportPrivateUsage]
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle import validate_bundle
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+# A list branch fed into a single field: `draft_ideas` gives `Idea[]` for the result `ideas`, while the
+# field `ideas` of `TopicReview` holds one `Idea`. Every pipe is a PipeCompose or a controller.
+_LIST_BRANCH_INTO_SINGLE_FIELD = """
+domain = "brainstorm"
+description = "A parallel feeding a list branch into a single field"
+main_pipe = "analyze_topics"
+
+[concept.Topic]
+description = "A topic to explore"
+refines = "Text"
+
+[concept.Idea]
+description = "One idea about a topic"
+refines = "Text"
+
+[concept.Overview]
+description = "A one-line overview"
+refines = "Text"
+
+[concept.TopicReview]
+description = "Ideas and an overview"
+
+[concept.TopicReview.structure]
+ideas = { type = "concept", concept_ref = "Idea", description = "The ideas", required = true }
+overview = { type = "concept", concept_ref = "Overview", description = "The overview", required = true }
+
+[pipe.analyze_topics]
+type = "PipeParallel"
+description = "Draft the ideas and the overview at the same time"
+inputs = { topics = "Topic[]" }
+output = "TopicReview"
+branches = [
+ { pipe = "draft_ideas", result = "ideas" },
+ { pipe = "write_overview", result = "overview" },
+]
+
+[pipe.draft_ideas]
+type = "PipeBatch"
+description = "Draft one idea per topic"
+inputs = { topics = "Topic[]" }
+output = "Idea[]"
+branch_pipe_code = "draft_idea"
+input_list_name = "topics"
+input_item_name = "topic"
+
+[pipe.draft_idea]
+type = "PipeCompose"
+description = "Draft one idea about a topic"
+inputs = { topic = "Topic" }
+output = "Idea"
+template = "An idea worth exploring about $topic"
+
+[pipe.write_overview]
+type = "PipeCompose"
+description = "Write a one-line overview"
+output = "Overview"
+template = "One idea per topic."
+"""
+
+# The reverse: `draft_idea` gives one `Idea` for the result `ideas`, while the field holds a list.
+_SINGLE_BRANCH_INTO_LIST_FIELD = """
+domain = "brainstorm"
+description = "A parallel feeding a single branch into a list field"
+main_pipe = "analyze_topic"
+
+[concept.Idea]
+description = "One idea about a topic"
+refines = "Text"
+
+[concept.Overview]
+description = "A one-line overview"
+refines = "Text"
+
+[concept.TopicReview]
+description = "Ideas and an overview"
+
+[concept.TopicReview.structure]
+ideas = { type = "list", item_type = "concept", item_concept_ref = "Idea", description = "The ideas", required = true }
+overview = { type = "concept", concept_ref = "Overview", description = "The overview", required = true }
+
+[pipe.analyze_topic]
+type = "PipeParallel"
+description = "Draft the idea and the overview at the same time"
+inputs = { topic = "Text" }
+output = "TopicReview"
+branches = [
+ { pipe = "draft_idea", result = "ideas" },
+ { pipe = "write_overview", result = "overview" },
+]
+
+[pipe.draft_idea]
+type = "PipeCompose"
+description = "Draft one idea about the topic"
+inputs = { topic = "Text" }
+output = "Idea"
+template = "An idea worth exploring about $topic"
+
+[pipe.write_overview]
+type = "PipeCompose"
+description = "Write a one-line overview"
+output = "Overview"
+template = "One idea."
+"""
+
+# The list comes from the branch itself: `draft_idea` declares one `Idea`, but the branch batches it over
+# the topics, so the next step names that branch setting rather than the pipe's declared output.
+_BATCHED_BRANCH_INTO_SINGLE_FIELD = _LIST_BRANCH_INTO_SINGLE_FIELD.replace(
+ '{ pipe = "draft_ideas", result = "ideas" }',
+ '{ pipe = "draft_idea", result = "ideas", batch_over = "topics", batch_as = "topic" }',
+)
+
+_BATCHED_INTO_SINGLE_NEXT_STEP = (
+ "Branch 'draft_idea' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'TopicReview' holds a single item. "
+ "Declare the field as a list in the structure of 'TopicReview', with type 'list', item_type 'concept' and item_concept_ref 'Idea', "
+ "or change the nb_output, multiple_output or batch_over that branch 'draft_idea' sets in the parallel's branches."
+)
+
+# Two faults in one combine: the ideas are a multiplicity mismatch, while the overview field receives a
+# list of `Idea`, a concept that does not fit `Overview` whatever its multiplicity. Only the first gets a
+# multiplicity next step, and the combine's own report is kept for the second.
+_TWO_FAULTS_IN_ONE_COMBINE = _LIST_BRANCH_INTO_SINGLE_FIELD.replace(
+ '{ pipe = "write_overview", result = "overview" }',
+ '{ pipe = "draft_ideas", result = "overview" }',
+)
+
+# No advice where a multiplicity change would not make the branch fit: a single `Text` into a list of
+# plain strings, whose items are not concept contents, and an `Anything[]` branch, whose concept has no
+# structure class to compare. The combine's own refusal reaches the verdict instead.
+_TEXT_INTO_PRIMITIVE_LIST_FIELD = _SINGLE_BRANCH_INTO_LIST_FIELD.replace(
+ 'ideas = { type = "list", item_type = "concept", item_concept_ref = "Idea", description = "The ideas", required = true }',
+ 'ideas = { type = "list", item_type = "text", description = "The ideas", required = true }',
+)
+
+_ANYTHING_LIST_INTO_SINGLE_FIELD = _LIST_BRANCH_INTO_SINGLE_FIELD.replace('output = "Idea[]"', 'output = "Anything[]"')
+
+_LIST_INTO_SINGLE_NEXT_STEP = (
+ "Branch 'draft_ideas' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'TopicReview' holds a single item. "
+ "Declare the field as a list in the structure of 'TopicReview', with type 'list', item_type 'concept' and item_concept_ref 'Idea', "
+ "or make branch 'draft_ideas' output a single 'Idea'."
+)
+
+_SINGLE_INTO_LIST_NEXT_STEP = (
+ "Branch 'draft_idea' gives result 'ideas' as a single 'Idea', but field 'ideas' of 'TopicReview' holds a list. "
+ "Declare the field as a single concept in the structure of 'TopicReview', with type 'concept' and concept_ref 'Idea', "
+ "or make branch 'draft_idea' output 'Idea[]'."
+)
+
+_TOP_LEVEL_NEXT_STEP = "Edit the bundle as each validation error says"
+
+
+def _write_bundle(*, directory: Path, content: str) -> Path:
+ bundle_path = directory / "bundle.mthds"
+ bundle_path.write_text(content, encoding="utf-8")
+ return bundle_path
+
+
+def console(mocker: MockerFixture) -> Console:
+ """A recording console patched into the error handlers, so the panel can be read back."""
+ recorded_console = Console(width=400, record=True, color_system=None)
+ mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)
+ return recorded_console
+
+
+class TestValidateParallelMultiplicityNextStep:
+ @pytest.mark.parametrize(
+ ("bundle_content", "expected_next_step"),
+ [
+ (_LIST_BRANCH_INTO_SINGLE_FIELD, _LIST_INTO_SINGLE_NEXT_STEP),
+ (_SINGLE_BRANCH_INTO_LIST_FIELD, _SINGLE_INTO_LIST_NEXT_STEP),
+ (_BATCHED_BRANCH_INTO_SINGLE_FIELD, _BATCHED_INTO_SINGLE_NEXT_STEP),
+ ],
+ ids=["list_branch_into_single_field", "single_branch_into_list_field", "batched_branch_into_single_field"],
+ )
+ def test_bare_validate_bundle_names_the_multiplicity_to_change(
+ self, console: Console, tmp_path: Path, bundle_content: str, expected_next_step: str
+ ) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=bundle_content)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ asyncio.run(_validate_pipe_or_bundle(bundle_path=bundle_path, library_dirs=[bundle_path.parent]))
+
+ assert exc_info.value.exit_code == 1
+ # The console wraps long lines; the words, not the line breaks, are what the reader gets.
+ output = " ".join(console.export_text().split())
+ assert "Bundle validation failed" in output
+ assert expected_next_step in output
+ assert f"💡 Tip: {_TOP_LEVEL_NEXT_STEP}" in output
+ assert "Check the validation_errors array" not in output
+ assert "Traceback" not in output
+
+ def test_a_concept_mismatch_keeps_the_combine_report(self, tmp_path: Path) -> None:
+ """A branch whose concept does not fit its field gets no multiplicity advice, and its refusal is not hidden."""
+ bundle_path = _write_bundle(directory=tmp_path, content=_TWO_FAULTS_IN_ONE_COMBINE)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ asyncio.run(validate_bundle(mthds_file_path=bundle_path, library_dirs=[bundle_path.parent]))
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert _LIST_INTO_SINGLE_NEXT_STEP in item.message
+ assert "gives result 'overview'" not in item.message
+ assert "The combine also reported: Error combining stuffs for concept TopicReview" in item.message
+
+ @pytest.mark.parametrize(
+ "bundle_content",
+ [_TEXT_INTO_PRIMITIVE_LIST_FIELD, _ANYTHING_LIST_INTO_SINGLE_FIELD],
+ ids=["text_into_primitive_list_field", "anything_list_into_single_field"],
+ )
+ def test_no_multiplicity_advice_where_it_would_not_help(self, tmp_path: Path, bundle_content: str) -> None:
+ """The verdict carries the combine's own refusal, never a multiplicity change that could not make it combine."""
+ bundle_path = _write_bundle(directory=tmp_path, content=bundle_content)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ asyncio.run(validate_bundle(mthds_file_path=bundle_path, library_dirs=[bundle_path.parent]))
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert "Error combining stuffs for concept TopicReview" in item.message
+ assert "cannot combine its branch results" not in item.message
+
+ def test_agent_validate_bundle_json_carries_the_next_step(
+ self,
+ mocker: MockerFixture,
+ capsys: pytest.CaptureFixture[str],
+ tmp_path: Path,
+ ) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=_LIST_BRANCH_INTO_SINGLE_FIELD)
+ mocker.patch("pipelex.cli.agent_cli.commands.validate.bundle_cmd.make_pipelex_for_agent_cli")
+ mocker.patch("pipelex.cli.agent_cli.commands.validate.bundle_cmd.Pipelex.teardown_if_needed")
+ try:
+ with pytest.raises(typer.Exit) as exc_info:
+ agent_validate_bundle_cmd(
+ path=str(bundle_path),
+ library_dir=[str(bundle_path.parent)],
+ output_format=CliOutputFormat.JSON,
+ )
+ finally:
+ set_agent_cli_error_format(CliOutputFormat.JSON)
+
+ assert exc_info.value.exit_code == 1
+ envelope = json.loads(capsys.readouterr().err)
+ assert envelope["is_valid"] is False
+ assert envelope["error_domain"] == "input"
+ assert envelope["hint"].startswith(_TOP_LEVEL_NEXT_STEP)
+ (item,) = envelope["validation_errors"]
+ assert item["category"] == "dry_run"
+ assert "PipeParallel 'analyze_topics' cannot combine its branch results into its output 'TopicReview'." in item["message"]
+ assert _LIST_INTO_SINGLE_NEXT_STEP in item["message"]
+
+ def test_the_verdict_report_carries_both_next_steps(self, tmp_path: Path) -> None:
+ """The report every surface draws from: the item names the fix, the top level points at the items."""
+ bundle_path = _write_bundle(directory=tmp_path, content=_LIST_BRANCH_INTO_SINGLE_FIELD)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ asyncio.run(validate_bundle(mthds_file_path=bundle_path, library_dirs=[bundle_path.parent]))
+
+ report = raised.value.to_error_report()
+ assert (report.user_action_detail() or "").startswith(_TOP_LEVEL_NEXT_STEP)
+ (item,) = report.validation_errors or []
+ assert _LIST_INTO_SINGLE_NEXT_STEP in item.message
diff --git a/tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py b/tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py
index 7101c6c74..41986adee 100644
--- a/tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py
+++ b/tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py
@@ -57,9 +57,8 @@ class TestErrorReportLocalFullChain:
await get_pipe_router().run(pipe_job=failing_pipe_job_local)
# The classification fields — the parity target. error_type / message
- # legitimately differ from the Temporal arm (PipeRouterError vs
- # WorkflowExecutionError; PipeLLM wraps the leaf message), so they are
- # not asserted here.
+ # are not part of this pair (the local report names the root fault,
+ # located at the failing pipe), so they are not asserted here.
report = exc_info.value.to_error_report()
assert report.error_category == ErrorReportParityTestData.FAILURE_CATEGORY
assert report.retryable == ErrorReportParityTestData.EXPECTED_RETRYABLE
diff --git a/tests/integration/pipelex/error_handling/test_search_error_report_local_full_chain.py b/tests/integration/pipelex/error_handling/test_search_error_report_local_full_chain.py
index d6e5df118..6736de4a4 100644
--- a/tests/integration/pipelex/error_handling/test_search_error_report_local_full_chain.py
+++ b/tests/integration/pipelex/error_handling/test_search_error_report_local_full_chain.py
@@ -7,8 +7,9 @@ mocked to fail, and asserts the resulting ``ErrorReport`` carries the full class
This is the baseline the Temporal full-chain test
(``tests/integration/pipelex/temporal/test_workflow_search_error_report_full_chain.py``) must match.
Both arms assert the same ``SearchErrorReportParityTestData`` constants, so local / Temporal parity holds
-by construction. The search operator does not wrap the leaf error (unlike PipeLLM), so a raw
-``SearchJobFailureError`` (a ``CogtError``) propagates and the ``PipeRouter`` re-raises it as-is.
+by construction. The search operator does not wrap the leaf error (unlike PipeLLM), so the
+``PipeRouter`` locates the raw ``SearchJobFailureError`` (a ``CogtError``) itself, and the report
+carries its identity.
"""
from collections.abc import Generator
@@ -19,6 +20,7 @@ from pytest_mock import MockerFixture
from pipelex.cogt.content_generation.content_generator import ContentGenerator
from pipelex.cogt.exceptions import SearchJobFailureError
from pipelex.interpreter_hub import get_pipe_router
+from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.system.pipe_run_mode import PipeRunMode
from tests.integration.pipelex.error_handling.test_data import SearchErrorReportParityTestData
@@ -43,18 +45,20 @@ class TestSearchErrorReportLocalFullChain:
mocker: MockerFixture,
failing_search_pipe_job_local: PipeJob,
) -> None:
- """Local execution surfaces the worker failure as a classified ``SearchJobFailureError``."""
+ """Local execution surfaces the worker failure, located, with the ``SearchJobFailureError``'s classification."""
mocker.patch.object(
ContentGenerator,
"make_search_sourced_answer",
side_effect=SearchErrorReportParityTestData.make_failing_search_error(),
)
- with pytest.raises(SearchJobFailureError) as exc_info:
+ with pytest.raises(PipeRouterError) as exc_info:
await get_pipe_router().run(pipe_job=failing_search_pipe_job_local)
+ assert isinstance(exc_info.value.__cause__, SearchJobFailureError)
# The classification fields — the parity target.
report = exc_info.value.to_error_report()
+ assert report.error_type == "SearchJobFailureError"
assert report.error_category == SearchErrorReportParityTestData.FAILURE_CATEGORY
assert report.retryable == SearchErrorReportParityTestData.EXPECTED_RETRYABLE
assert report.model == SearchErrorReportParityTestData.FAILURE_MODEL
diff --git a/tests/integration/pipelex/pipeline/test_condition_method_faults.py b/tests/integration/pipelex/pipeline/test_condition_method_faults.py
new file mode 100644
index 000000000..5f2ab91c1
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_condition_method_faults.py
@@ -0,0 +1,124 @@
+"""Pin: a `PipeCondition`'s own refusals are the caller's faults, and their reason reaches every surface.
+
+The condition's expression and outcomes are the caller's own method, so when it refuses a run, the refusal
+is the caller's to fix: its message names the pipe and the reason, locally and under STRICT disclosure, where
+it used to be an unclassified `PipeRunError` that a validation verdict named by its title, "Pipe run", and a
+hosted run answered with `An internal error occurred.`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode, ValidationErrorCategory
+from pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleError
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validate_bundle import validate_bundle
+from tests.integration.pipelex.pipeline.test_data import ConditionMethodFaultsTestData
+
+_EMPTY_EXPRESSION_REASON = "PipeCondition 'route_parcel': Conditional expression returned no result"
+_EMPTY_EXPRESSION_NEXT_STEP = (
+ "Change the expression of PipeCondition 'route_parcel' so that it always renders a value: "
+ "the name of one of its outcomes, or any other value, which takes the default outcome."
+)
+_ALL_FAIL_REASON = (
+ "PipeCondition 'route_parcel' maps every outcome (and the default) to 'fail': every live run of this pipe raises. "
+ "Map at least one outcome to a pipe or to 'continue'."
+)
+
+
+def _routing_bundle(*, inputs: str, expression: str, outcomes: str, default_outcome: str) -> str:
+ return (
+ ConditionMethodFaultsTestData.ROUTING_MTHDS.replace(ConditionMethodFaultsTestData.INPUTS_SLOT, inputs)
+ .replace(ConditionMethodFaultsTestData.EXPRESSION_SLOT, expression)
+ .replace(ConditionMethodFaultsTestData.OUTCOMES_SLOT, outcomes)
+ .replace(ConditionMethodFaultsTestData.DEFAULT_OUTCOME_SLOT, default_outcome)
+ )
+
+
+_EMPTY_EXPRESSION_BUNDLE = _routing_bundle(
+ inputs=ConditionMethodFaultsTestData.PARCEL_INPUT,
+ expression="''",
+ outcomes=ConditionMethodFaultsTestData.LANE_OUTCOMES,
+ default_outcome="send_standard",
+)
+_ALL_FAIL_BUNDLE = _routing_bundle(
+ inputs=ConditionMethodFaultsTestData.LANE_INPUT,
+ expression="lane",
+ outcomes=ConditionMethodFaultsTestData.ALL_FAIL_OUTCOMES,
+ default_outcome="fail",
+)
+_LANE_BUNDLE = _routing_bundle(
+ inputs=ConditionMethodFaultsTestData.PARCEL_AND_LANE_INPUTS,
+ expression="lane",
+ outcomes=ConditionMethodFaultsTestData.LANE_OUTCOMES,
+ default_outcome="send_standard",
+)
+
+
+async def _verdict(*, bundle: str) -> ValidateBundleError:
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[bundle])
+ return exc_info.value
+
+
+async def _failed_run(*, bundle: str, inputs: dict[str, Any]) -> PipelineExecutionError:
+ with pytest.raises(PipelineExecutionError) as exc_info:
+ await PipelexMTHDSProtocol().execute(pipe_code="route_parcel", mthds_contents=[bundle], inputs=inputs)
+ return exc_info.value
+
+
[email protected](loop_scope="class")
+class TestConditionMethodFaults:
+ @pytest.mark.parametrize(
+ ("bundle", "reason"),
+ [
+ (_EMPTY_EXPRESSION_BUNDLE, _EMPTY_EXPRESSION_REASON),
+ (_ALL_FAIL_BUNDLE, _ALL_FAIL_REASON),
+ ],
+ ids=["expression_renders_nothing", "every_outcome_fails"],
+ )
+ async def test_a_dry_run_refusal_is_an_item_with_its_reason(self, bundle: str, reason: str) -> None:
+ """The verdict item names the pipe and the reason, locally and in the STRICT payload, never the title "Pipe run"."""
+ verdict = await _verdict(bundle=bundle)
+
+ (item,) = verdict.to_error_report().validation_errors or []
+ assert item.category == ValidationErrorCategory.DRY_RUN
+ assert item.pipe_code == "route_parcel"
+ assert item.message == f"Pipe 'route_parcel' failed its dry run: {reason}"
+
+ strict_payload = verdict.to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+ (strict_item,) = strict_payload["validation_errors"]
+ assert strict_item["message"] == f"Pipe 'route_parcel' failed its dry run: {reason}"
+
+ async def test_an_expression_that_renders_nothing_is_the_callers_fault_under_strict(self) -> None:
+ """A run whose condition expression renders nothing: HTTP 422, the reason at the condition, and the next step."""
+ error = await _failed_run(bundle=_EMPTY_EXPRESSION_BUNDLE, inputs={"parcel": "a box of books"})
+
+ document = error.to_error_report().to_problem_document(disclosure_mode=DisclosureMode.STRICT)
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert document["error_type"] == "PipeRunError"
+ assert document["detail"] == f"Pipe 'route_parcel' failed: {_EMPTY_EXPRESSION_REASON}"
+ assert document["user_action"] == {"kind": "change_input", "detail": _EMPTY_EXPRESSION_NEXT_STEP}
+
+ async def test_a_fail_outcome_is_the_callers_fault_under_strict(self) -> None:
+ """A run whose lane the method maps to 'fail': HTTP 422, naming the pipe, never the value its expression rendered."""
+ error = await _failed_run(bundle=_LANE_BUNDLE, inputs={"parcel": "a box of books", "lane": "reject"})
+
+ document = error.to_error_report().to_problem_document(disclosure_mode=DisclosureMode.STRICT)
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert document["error_type"] == "PipeRunError"
+ assert document["detail"] != INTERNAL_ERROR_PLACEHOLDER
+ # The rendered value can be text of a condition a host library declared, so no message carries it.
+ assert document["detail"] == "Pipe 'route_parcel' failed: PipeCondition 'route_parcel' failed with outcome: fail."
+ assert document["user_action"] == {
+ "kind": "change_input",
+ "detail": (
+ "PipeCondition 'route_parcel' refuses this run on purpose: change the inputs so that its expression "
+ "selects another outcome, or map that outcome to a pipe or to 'continue'."
+ ),
+ }
diff --git a/tests/integration/pipelex/pipeline/test_data.py b/tests/integration/pipelex/pipeline/test_data.py
new file mode 100644
index 000000000..591476cf1
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_data.py
@@ -0,0 +1,301 @@
+from typing import ClassVar
+
+
+class LocatedRunFailureTestData:
+ """Bundles whose runs fail at a nested pipe, one per way a run failure is located."""
+
+ UNSERVED_MODEL_HANDLE: ClassVar[str] = "located-failure-unserved-model"
+
+ # A sequence whose second step names a model the deck does not serve. The inline setting table
+ # passes the static check, so the run fails at the model lookup, before any provider is called.
+ MODEL_MTHDS: ClassVar[str] = """
+domain = "located_failure_model"
+description = "A sequence whose second step names a model the deck does not serve"
+
+[pipe.two_steps]
+type = "PipeSequence"
+description = "Restate the topic, then summarize it"
+inputs = { topic = "Text" }
+output = "Text"
+steps = [
+ { pipe = "restate", result = "restated" },
+ { pipe = "summarize", result = "summary" },
+]
+
+[pipe.restate]
+type = "PipeCompose"
+description = "Restate the topic"
+inputs = { topic = "Text" }
+output = "Text"
+template = "About {{ topic }}"
+
+[pipe.summarize]
+type = "PipeLLM"
+description = "Summarize with a model the deck does not serve"
+inputs = { restated = "Text" }
+output = "Text"
+model = { model = "located-failure-unserved-model", temperature = 0.2 }
+prompt = "Summarize $restated"
+"""
+
+ # A parallel nested in a sequence, whose plural branch feeds a single field of the combined
+ # output: the combine fails, in the live run and in the dry run alike.
+ PARALLEL_MTHDS: ClassVar[str] = """
+domain = "located_failure_parallel"
+description = "A parallel whose plural branch feeds a single field, nested in a sequence"
+
+[concept.Idea]
+description = "An idea"
+
+[concept.Idea.structure]
+title = { type = "text", description = "The idea's title", required = true }
+
+[concept.Summary]
+description = "A summary"
+
+[concept.Summary.structure]
+text = { type = "text", description = "The summary", required = true }
+
+[concept.Report]
+description = "A report"
+
+[concept.Report.structure]
+ideas = { type = "concept", concept_ref = "located_failure_parallel.Idea", description = "The ideas", required = true }
+summary = { type = "concept", concept_ref = "located_failure_parallel.Summary", description = "The summary", required = true }
+
+[pipe.flow]
+type = "PipeSequence"
+description = "Analyze the topic"
+inputs = { topic = "Text" }
+output = "Report"
+steps = [{ pipe = "analyze", result = "report" }]
+
+[pipe.analyze]
+type = "PipeParallel"
+description = "Generate ideas and a summary, combined into a report"
+inputs = { topic = "Text" }
+output = "Report"
+branches = [
+ { pipe = "gen_ideas", result = "ideas" },
+ { pipe = "summarize", result = "summary" },
+]
+
+[pipe.gen_ideas]
+type = "PipeLLM"
+description = "Generate ideas"
+inputs = { topic = "Text" }
+output = "Idea[]"
+prompt = "Give ideas about $topic"
+
+[pipe.summarize]
+type = "PipeLLM"
+description = "Summarize"
+inputs = { topic = "Text" }
+output = "Summary"
+prompt = "Summarize $topic"
+"""
+
+ # A step force-unwraps ('!') an optional input the caller left out: a caller-facing failure.
+ FORCE_MTHDS: ClassVar[str] = """
+domain = "located_failure_force"
+description = "A sequence whose step force-unwraps an optional input the caller left out"
+
+[pipe.force_flow]
+type = "PipeSequence"
+description = "Echo an optional clause, asserted present inside"
+inputs = { clause = "Text?" }
+output = "Text"
+steps = [{ pipe = "force_echo", result = "echoed" }]
+
+[pipe.force_echo]
+type = "PipeCompose"
+description = "Echo the clause, which must be present"
+inputs = { clause = "Text!" }
+output = "Text"
+template = "Clause: {{ clause }}"
+"""
+
+
+class StrictMethodFaultsTestData:
+ """Bundles whose runs fail on a fault in the caller's own method, and on faults that are not the caller's."""
+
+ # A sequence whose first step needs an input the caller may leave out of the request.
+ MISSING_INPUT_MTHDS: ClassVar[str] = """
+domain = "strict_faults_missing_input"
+description = "A sequence that greets a name the caller must provide"
+
+[pipe.greet_flow]
+type = "PipeSequence"
+description = "Greet the name"
+inputs = { name = "Text" }
+output = "Text"
+steps = [{ pipe = "greet", result = "greeting" }]
+
+[pipe.greet]
+type = "PipeCompose"
+description = "Greet the name"
+inputs = { name = "Text" }
+output = "Text"
+template = "Hello {{ name }}"
+"""
+
+ # A parallel nested in a sequence, whose single `Idea` branch feeds a field holding a list of plain
+ # texts: the combine refuses it, and no multiplicity change would make it fit, since the field's
+ # items are not concept contents. Every pipe is a PipeCompose or a controller.
+ PARALLEL_NO_MULTIPLICITY_MTHDS: ClassVar[str] = """
+domain = "strict_faults_parallel"
+description = "A parallel whose single branch feeds a list of plain texts, nested in a sequence"
+
+[concept.Idea]
+description = "One idea"
+refines = "Text"
+
+[concept.Overview]
+description = "A one-line overview"
+refines = "Text"
+
+[concept.Review]
+description = "Ideas and an overview"
+
+[concept.Review.structure]
+ideas = { type = "list", item_type = "text", description = "The ideas", required = true }
+overview = { type = "concept", concept_ref = "strict_faults_parallel.Overview", description = "The overview", required = true }
+
+[pipe.flow]
+type = "PipeSequence"
+description = "Review the topic"
+inputs = { topic = "Text" }
+output = "Review"
+steps = [{ pipe = "analyze", result = "review" }]
+
+[pipe.analyze]
+type = "PipeParallel"
+description = "Draft an idea and an overview at the same time"
+inputs = { topic = "Text" }
+output = "Review"
+branches = [
+ { pipe = "draft_idea", result = "ideas" },
+ { pipe = "write_overview", result = "overview" },
+]
+
+[pipe.draft_idea]
+type = "PipeCompose"
+description = "Draft one idea about the topic"
+inputs = { topic = "Text" }
+output = "Idea"
+template = "An idea about $topic"
+
+[pipe.write_overview]
+type = "PipeCompose"
+description = "Write a one-line overview"
+output = "Overview"
+template = "One idea."
+"""
+
+ DECK_PRESET: ClassVar[str] = "strict-faults-deck-preset"
+ DECK_ALIAS: ClassVar[str] = "strict-faults-deck-alias"
+ # A handle the deck's own preset and alias name, which the test profile does not serve.
+ DECK_NAMED_UNSERVED_HANDLE: ClassVar[str] = "strict-faults-deck-named-unserved"
+
+ # Replaced by the model reference a test names the step's model with.
+ MODEL_REFERENCE_SLOT: ClassVar[str] = "<model-reference>"
+
+ # A step that names its model through a preset or an alias of the deck: the deck names the model.
+ DECK_NAMED_MODEL_MTHDS: ClassVar[str] = """
+domain = "strict_faults_deck_model"
+description = "A step whose model the deck names but does not serve"
+
+[pipe.summarize_flow]
+type = "PipeSequence"
+description = "Summarize the topic"
+inputs = { topic = "Text" }
+output = "Text"
+steps = [{ pipe = "summarize", result = "summary" }]
+
+[pipe.summarize]
+type = "PipeLLM"
+description = "Summarize with a model the deck names but does not serve"
+inputs = { topic = "Text" }
+output = "Text"
+model = "<model-reference>"
+prompt = "Summarize $topic"
+"""
+
+ # A step with a structured output, whose model output the test makes unfit for its structure.
+ STRUCTURED_OUTPUT_MTHDS: ClassVar[str] = """
+domain = "strict_faults_structured_output"
+description = "A step whose structured output the model could not fit"
+
+[concept.Verdict]
+description = "A verdict on a claim"
+
+[concept.Verdict.structure]
+label = { type = "text", description = "The verdict's label", required = true }
+
+[pipe.judge_flow]
+type = "PipeSequence"
+description = "Judge the claim"
+inputs = { claim = "Text" }
+output = "Verdict"
+steps = [{ pipe = "judge", result = "verdict" }]
+
+[pipe.judge]
+type = "PipeLLM"
+description = "Judge the claim"
+inputs = { claim = "Text" }
+output = "Verdict"
+prompt = "Judge this claim: $claim"
+"""
+
+
+class ConditionMethodFaultsTestData:
+ """Bundles whose `PipeCondition` refuses the run on a fault in the caller's own method."""
+
+ # Replaced by the inputs, the expression, the outcomes and the default outcome each case gives the condition.
+ INPUTS_SLOT: ClassVar[str] = "<inputs>"
+ EXPRESSION_SLOT: ClassVar[str] = "<expression>"
+ OUTCOMES_SLOT: ClassVar[str] = "<outcomes>"
+ DEFAULT_OUTCOME_SLOT: ClassVar[str] = "<default-outcome>"
+
+ # A condition routing a parcel between two lanes, whose expression each case sets.
+ ROUTING_MTHDS: ClassVar[str] = """
+domain = "condition_faults_routing"
+description = "Send a parcel down the lane the request names"
+main_pipe = "route_parcel"
+
+[concept]
+Parcel = "A parcel waiting at the sorting bench"
+
+[pipe.route_parcel]
+type = "PipeCondition"
+description = "Choose the lane a parcel goes down"
+inputs = <inputs>
+output = "Parcel"
+expression = "<expression>"
+outcomes = <outcomes>
+default_outcome = "<default-outcome>"
+
+[pipe.send_express]
+type = "PipeCompose"
+description = "Note the parcel onto the express lane"
+inputs = { parcel = "Parcel" }
+output = "Parcel"
+template = "Express: $parcel"
+
+[pipe.send_standard]
+type = "PipeCompose"
+description = "Note the parcel onto the standard lane"
+inputs = { parcel = "Parcel" }
+output = "Parcel"
+template = "Standard: $parcel"
+"""
+
+ # What the condition reads: the parcel its lanes note, and the lane its expression reads.
+ PARCEL_AND_LANE_INPUTS: ClassVar[str] = '{ parcel = "Parcel", lane = "Text" }'
+ PARCEL_INPUT: ClassVar[str] = '{ parcel = "Parcel" }'
+ LANE_INPUT: ClassVar[str] = '{ lane = "Text" }'
+
+ # Two lanes, and a lane the method refuses on purpose.
+ LANE_OUTCOMES: ClassVar[str] = '{ express = "send_express", standard = "send_standard", reject = "fail" }'
+ # Every outcome, and the default, refuse the run.
+ ALL_FAIL_OUTCOMES: ClassVar[str] = '{ reject = "fail" }'
diff --git a/tests/integration/pipelex/pipeline/test_located_run_failure.py b/tests/integration/pipelex/pipeline/test_located_run_failure.py
new file mode 100644
index 000000000..0cf47dff4
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_located_run_failure.py
@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from typing_extensions import override
+
+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode, ErrorReport, PipelexError
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
+from pipelex.config import get_config
+from pipelex.pipe_run.exceptions import PipeRouterError, find_failure_location
+from pipelex.pipe_run.pipe_router import PipeRouter
+from pipelex.pipe_run.pipe_run import PipeRun
+from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol
+from pipelex.pipeline.exceptions import PipelineExecutionError
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.runtime_bridge.direct_orchestrator import DirectOrchestrator
+from pipelex.runtime_bridge.exceptions import PipelexBridgeDispatchError
+from pipelex.system.pipe_run_mode import PipeRunMode
+from tests.integration.pipelex.pipeline.test_data import LocatedRunFailureTestData
+
+if TYPE_CHECKING:
+ from pipelex.core.pipes.pipe_output import PipeOutput
+ from pipelex.pipe_run.delivery_assignment import DeliveryAssignment
+ from pipelex.pipe_run.pipe_job import PipeJob
+ from pipelex.system.configuration.configs import PipelineExecutionConfig
+
+
+def _dry_mock_config() -> PipelineExecutionConfig:
+ return get_config().interpreter.pipeline_execution.with_execution_overrides(
+ generate_graph=False,
+ mock_inputs=True,
+ )
+
+
+class _DirectOrchestratorPipeRun(PipeRunProtocol):
+ """Dispatch through the in-process orchestrator, as the API runner's `/execute` does in `direct` mode."""
+
+ @override
+ async def run(self, pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:
+ await DirectOrchestrator().execute(pipe_job=pipe_job, delivery_assignment=delivery_assignment)
+ msg = "This adapter only serves failing runs."
+ raise AssertionError(msg)
+
+
+class _RecoveredReportError(PipelexError):
+ """Carries a report recovered across a transport boundary, as a distributed submitter does."""
+
+ def __init__(self, message: str, *, error_report: ErrorReport):
+ super().__init__(message)
+ self.error_report = error_report
+
+ @override
+ def to_error_report(self) -> ErrorReport:
+ return self.error_report
+
+
+class _RecoveredReportPipeRun(PipeRunProtocol):
+ """Fail the way a distributed orchestrator does: its bridge sentence around a recovered report."""
+
+ def __init__(self, *, recovered_report: ErrorReport):
+ self._recovered_report = recovered_report
+
+ @override
+ async def run(self, pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:
+ recovered = _RecoveredReportError(self._recovered_report.message, error_report=self._recovered_report)
+ msg = f"Pipe execution failed in temporal blocking delivery for pipe '{pipe_job.pipe.code}': {recovered}"
+ raise PipelexBridgeDispatchError(msg) from recovered
+
+
+class _ForeignFailureRouter(PipeRouter):
+ """A router whose pipe raises an exception that is not a PipelexError."""
+
+ @override
+ async def _run_pipe_job(self, pipe_job: PipeJob) -> PipeOutput:
+ msg = "boom from a pipe"
+ raise KeyError(msg)
+
+
[email protected](loop_scope="class")
+class TestLocatedRunFailure:
+ async def _run_parallel_failure(self, *, pipe_run: PipeRunProtocol | None = None) -> PipelineExecutionError:
+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=_dry_mock_config(), pipe_run=pipe_run)
+ with pytest.raises(PipelineExecutionError) as exc_info:
+ await runner.execute(pipe_code="flow", mthds_contents=[LocatedRunFailureTestData.PARALLEL_MTHDS])
+ return exc_info.value
+
+ async def test_unserved_model_is_reported_at_the_failing_step(self) -> None:
+ """The model example: the failing step, its path and the model error's own identity and sentence."""
+ runner = PipelexMTHDSProtocol()
+ with pytest.raises(PipelineExecutionError) as exc_info:
+ await runner.execute(pipe_code="two_steps", mthds_contents=[LocatedRunFailureTestData.MODEL_MTHDS], inputs={"topic": "cats"})
+ error = exc_info.value
+
+ assert error.pipe_code == "summarize"
+ assert error.pipe_stack == ["two_steps", "summarize"]
+
+ report = error.to_error_report()
+ assert report.error_type == "ModelNotFoundError"
+ assert report.title == "Model not found"
+ assert report.type_uri.endswith("/model-not-found-error/")
+ unserved_handle = LocatedRunFailureTestData.UNSERVED_MODEL_HANDLE
+ assert report.message == f"Pipe 'summarize' failed (two_steps → summarize): Model handle '{unserved_handle}' was not found in the model deck."
+ # The local-deck remedy is the local CLI's to give: the message reaches hosted readers too.
+ assert ".pipelex/inference" not in report.message
+ assert "pipelex init" not in report.message
+ assert report.model == LocatedRunFailureTestData.UNSERVED_MODEL_HANDLE
+ # The model lookup advises changing the model the step names, so no fallback is needed.
+ assert report.user_action == UserAction(
+ kind=UserActionKind.CHANGE_MODEL,
+ detail=f"Change the model '{unserved_handle}' to an LLM the model deck serves.",
+ )
+
+ # The step names the model in an inline setting, and no entry of the deck names it: the
+ # caller's own fault, whose message STRICT disclosure keeps.
+ strict_payload = report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert strict_payload["message"] == report.message
+ assert strict_payload["error_domain"] == "input"
+ assert strict_payload["error_type"] == "ModelNotFoundError"
+ assert strict_payload["user_action"] == {
+ "kind": "change_model",
+ "detail": f"Change the model '{unserved_handle}' to an LLM the model deck serves.",
+ }
+
+ async def test_parallel_combine_failure_is_reported_at_the_nested_parallel(self) -> None:
+ """The multiplicity example: the parallel nested in the sequence, with the combine's own identity and message."""
+ error = await self._run_parallel_failure()
+
+ assert error.pipe_code == "analyze"
+ assert error.pipe_stack == ["flow", "analyze"]
+
+ report = error.to_error_report()
+ assert report.error_type == "StuffFactoryError"
+ # The combine's refusal restated with its multiplicity remedy, a StuffFactoryError raised from the
+ # combine's own, is the root fault: of two faults of the same class, the outer one.
+ assert report.message.startswith(
+ "Pipe 'analyze' failed (flow → analyze): PipeParallel 'analyze' cannot combine its branch results into its output 'Report'."
+ )
+ assert "Branch 'gen_ideas' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'Report' holds a single item." in report.message
+ # The multiplicity next step, since a mismatched combine is the caller's to fix.
+ assert report.user_action is not None
+ assert report.user_action.detail.startswith("Branch 'gen_ideas' gives result 'ideas' as a list")
+
+ async def test_caller_facing_root_keeps_its_message_under_strict(self) -> None:
+ """A caller-facing root fault keeps its own message, located, under STRICT."""
+ runner = PipelexMTHDSProtocol()
+ with pytest.raises(PipelineExecutionError) as exc_info:
+ await runner.execute(pipe_code="force_flow", mthds_contents=[LocatedRunFailureTestData.FORCE_MTHDS], inputs={})
+ error = exc_info.value
+
+ assert error.pipe_code == "force_echo"
+ assert error.pipe_stack == ["force_flow", "force_echo"]
+
+ report = error.to_error_report()
+ assert report.error_type == "OptionalValueAbsentError"
+ assert report.caller_facing_message is True
+ strict_payload = report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert strict_payload["message"] == report.message
+ assert strict_payload["message"].startswith("Pipe 'force_echo' failed (force_flow → force_echo): ")
+ assert "clause" in strict_payload["message"]
+
+ async def test_in_process_orchestrator_adds_nothing(self) -> None:
+ """Through the in-process bridge, the report and the location are the direct run's; the bridge's sentence is in neither."""
+ direct_error = await self._run_parallel_failure()
+ bridged_error = await self._run_parallel_failure(pipe_run=_DirectOrchestratorPipeRun())
+
+ assert isinstance(bridged_error.__cause__, PipelexBridgeDispatchError)
+ assert bridged_error.pipe_code == direct_error.pipe_code
+ assert bridged_error.pipe_stack == direct_error.pipe_stack
+ assert bridged_error.message == direct_error.message
+ assert bridged_error.to_error_report() == direct_error.to_error_report()
+ assert "DIRECT mode" not in bridged_error.to_error_report().message
+
+ async def test_recovered_report_adds_nothing(self) -> None:
+ """A report recovered across a transport boundary, as the hosted run stores it, reads as the direct run's."""
+ direct_error = await self._run_parallel_failure()
+ location = find_failure_location(error=direct_error)
+ assert isinstance(location, PipeRouterError)
+ # What a distributed worker's run root stores: the located router error's report.
+ recovered_report = location.to_error_report()
+
+ bridged_error = await self._run_parallel_failure(pipe_run=_RecoveredReportPipeRun(recovered_report=recovered_report))
+
+ assert bridged_error.to_error_report() == direct_error.to_error_report()
+ assert "temporal blocking delivery" not in bridged_error.to_error_report().message
+ assert "temporal blocking delivery" not in bridged_error.message
+
+ async def test_foreign_exception_is_located_as_unexpected_error(self) -> None:
+ """A non-PipelexError raised in a pipe's run comes out located, as a PipelexUnexpectedError naming its class."""
+ error = await self._run_parallel_failure(pipe_run=PipeRun(pipe_router=_ForeignFailureRouter()))
+
+ assert error.pipe_code == "flow"
+ assert error.pipe_stack == ["flow"]
+ report = error.to_error_report()
+ assert report.error_type == "PipelexUnexpectedError"
+ assert report.message == "Pipe 'flow' failed: KeyError: 'boom from a pipe'"
+ assert report.caller_facing_message is False
+ assert report.to_dict(disclosure_mode=DisclosureMode.STRICT)["message"] == INTERNAL_ERROR_PLACEHOLDER
diff --git a/tests/integration/pipelex/pipeline/test_run_path_bundle_verdict.py b/tests/integration/pipelex/pipeline/test_run_path_bundle_verdict.py
new file mode 100644
index 000000000..9b48fdd05
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_run_path_bundle_verdict.py
@@ -0,0 +1,233 @@
+"""Pin: the run path refuses an invalid bundle with the verdict ``validate`` gives for it.
+
+A run loads its bundle before any pipe runs, and that load already refuses an invalid method. These tests
+pin that the refusal reaches the caller the way validating the same bundle reports it: a
+``ValidateBundleError`` carrying the same located ``validation_errors`` items, whose STRICT projection is
+an HTTP 422 that keeps them. Before, each refusal reached a host in the raw class of whichever check
+made it: a misspelled concept as a ``ConceptLibraryError`` answered 500, a wiring mismatch as a
+``PipeValidationError`` (a ``ValueError``) answered by the catch-all 500, a TOML fault as a 422 with no
+items, and a check firing inside a pipe's pydantic validator as a ``runtime`` ``PipeExecutionError``
+reading "Input validation failed".
+
+- **Parity.** For each bundle, ``pipeline_run_setup`` raises the verdict with exactly the items
+ ``validate_bundle`` produces, and the STRICT projection is a 422 carrying them.
+- **The model-validator case.** The runner's ``execute`` answers it with the verdict, not with the
+ ``runtime`` input-validation failure.
+- **The unknown entry pipe** is not a bundle fault: it still raises its own ``PipeNotFoundError``.
+- **Whose library directories.** A local caller's directories are theirs, so a refusal while loading
+ them is the verdict too, located on their file; a host's directories load untranslated by default.
+"""
+
+from pathlib import Path
+from typing import Any, NamedTuple
+
+import pytest
+
+from pipelex.base_exceptions import DisclosureMode
+from pipelex.config import get_config
+from pipelex.libraries.exceptions import LibraryError
+from pipelex.libraries.pipe.exceptions import PipeNotFoundError
+from pipelex.pipeline.exceptions import PipeExecutionError, ValidateBundleError
+from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.system.configuration.configs import PipelineExecutionConfig
+from pipelex.system.pipe_run_mode import PipeRunMode
+from pipelex.validation_error_types import PipeValidationErrorType
+
+_MISSPELLED_CONCEPT_BUNDLE = """
+domain = "harbour_notices"
+description = "Write notices for the harbour board"
+main_pipe = "write_tide_notice"
+
+[concept.TideNotice]
+description = "A notice telling harbour users when the tide turns"
+
+[pipe.write_tide_notice]
+type = "PipeLLM"
+description = "Write the tide notice for the harbour board"
+inputs = { tide_times = "Text" }
+output = "TideNotise"
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+_SEQUENCE_OUTPUT_MISMATCH_BUNDLE = """
+domain = "harbour_notices"
+description = "Write notices for the harbour board"
+main_pipe = "prepare_notices"
+
+[pipe.prepare_notices]
+type = "PipeSequence"
+description = "Prepare the notices for the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text[]"
+steps = [{ pipe = "write_tide_notice", result = "tide_notice" }]
+
+[pipe.write_tide_notice]
+type = "PipeLLM"
+description = "Write the tide notice for the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text"
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+_TOML_SYNTAX_ERROR_BUNDLE = """
+domain = "harbour_notices
+description = "Write notices for the harbour board"
+"""
+
+# A field value the blueprint schema refuses and no categorizer names: the item carries no error_type.
+_UNCATEGORIZED_BLUEPRINT_FAULT_BUNDLE = """
+domain = "harbour_notices"
+description = "Draw the harbour board"
+main_pipe = "draw_harbour_board"
+
+[pipe.draw_harbour_board]
+type = "PipeImgGen"
+description = "Draw the painted harbour board"
+output = "Image"
+prompt = "A painted wooden harbour board announcing the tide times"
+aspect_ratio = "7:3"
+"""
+
+# A check that fires inside a pipe's pydantic validator while the pipe is built: the function a
+# PipeFunc names is not registered.
+_MODEL_VALIDATOR_FAULT_BUNDLE = """
+domain = "harbour_notices"
+description = "Format notices for the harbour board"
+main_pipe = "format_tide_notice"
+
+[pipe.format_tide_notice]
+type = "PipeFunc"
+description = "Format the tide notice for the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text"
+function_name = "format_harbour_tide_notice_nowhere_registered"
+"""
+
+_VALID_BUNDLE = """
+domain = "harbour_notices"
+description = "Write notices for the harbour board"
+main_pipe = "write_tide_notice"
+
+[pipe.write_tide_notice]
+type = "PipeLLM"
+description = "Write the tide notice for the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text"
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+
+class _InvalidBundleCase(NamedTuple):
+ case_id: str
+ bundle: str
+
+
+_INVALID_BUNDLE_CASES: list[_InvalidBundleCase] = [
+ _InvalidBundleCase(case_id="misspelled_concept", bundle=_MISSPELLED_CONCEPT_BUNDLE),
+ _InvalidBundleCase(case_id="sequence_output_mismatch", bundle=_SEQUENCE_OUTPUT_MISMATCH_BUNDLE),
+ _InvalidBundleCase(case_id="toml_syntax_error", bundle=_TOML_SYNTAX_ERROR_BUNDLE),
+ _InvalidBundleCase(case_id="uncategorized_blueprint_fault", bundle=_UNCATEGORIZED_BLUEPRINT_FAULT_BUNDLE),
+ _InvalidBundleCase(case_id="model_validator_fault", bundle=_MODEL_VALIDATOR_FAULT_BUNDLE),
+]
+
+
+def _execution_config() -> PipelineExecutionConfig:
+ return get_config().interpreter.pipeline_execution.with_execution_overrides(generate_graph=False, generate_usage=False, mock_inputs=True)
+
+
+async def _validate_verdict(*, bundle: str) -> ValidateBundleError:
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_contents=[bundle])
+ return raised.value
+
+
+async def _run_setup(**kwargs: Any) -> None:
+ await pipeline_run_setup(
+ storage_scope="test/scope",
+ user_id="test-user",
+ execution_config=_execution_config(),
+ pipe_run_mode=PipeRunMode.DRY,
+ **kwargs,
+ )
+
+
+def _strict_items(verdict: ValidateBundleError) -> list[dict[str, Any]]:
+ strict_payload = verdict.to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+ strict_items: list[dict[str, Any]] = strict_payload["validation_errors"]
+ return strict_items
+
+
[email protected](loop_scope="class")
+class TestRunPathBundleVerdict:
+ @pytest.mark.parametrize("case", _INVALID_BUNDLE_CASES, ids=[case.case_id for case in _INVALID_BUNDLE_CASES])
+ async def test_run_setup_refuses_with_the_validate_verdict(self, case: _InvalidBundleCase) -> None:
+ validate_verdict = await _validate_verdict(bundle=case.bundle)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await _run_setup(mthds_contents=[case.bundle])
+
+ run_report = raised.value.to_error_report()
+ validate_items = validate_verdict.to_error_report().validation_errors
+ assert validate_items, "the validate path gives at least one item for an invalid bundle"
+ assert run_report.validation_errors == validate_items
+ assert run_report.http_status == 422
+ strict_payload = run_report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert strict_payload["error_type"] == "ValidateBundleError"
+ assert strict_payload["error_domain"] == "input"
+ assert _strict_items(raised.value) == _strict_items(validate_verdict)
+
+ async def test_misspelled_concept_is_located_on_the_pipe_and_the_field(self) -> None:
+ with pytest.raises(ValidateBundleError) as raised:
+ await _run_setup(mthds_contents=[_MISSPELLED_CONCEPT_BUNDLE])
+
+ items = raised.value.to_error_report().validation_errors or []
+ (item,) = items
+ assert item.error_type == PipeValidationErrorType.UNRESOLVED_CONCEPT
+ assert item.pipe_code == "write_tide_notice"
+ assert item.concept_code == "TideNotise"
+ assert item.field_path == "pipe.write_tide_notice.output"
+ # The run request names no file, so the item carries no source — never a host path.
+ assert item.source is None
+
+ async def test_execute_answers_a_model_validator_fault_with_the_verdict(self) -> None:
+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=_execution_config())
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await runner.execute(mthds_contents=[_MODEL_VALIDATOR_FAULT_BUNDLE])
+
+ assert not isinstance(raised.value, PipeExecutionError)
+ items = raised.value.to_error_report().validation_errors or []
+ assert any("format_harbour_tide_notice_nowhere_registered" in item.message for item in items)
+
+ async def test_unknown_entry_pipe_keeps_its_own_class(self) -> None:
+ with pytest.raises(PipeNotFoundError) as raised:
+ await _run_setup(mthds_contents=[_VALID_BUNDLE], pipe_code="write_harbour_poem")
+
+ assert not isinstance(raised.value, ValidateBundleError)
+
+ async def test_a_callers_library_dir_refusal_is_the_verdict_located_on_their_file(self, tmp_path: Path) -> None:
+ bundle_path = tmp_path / "bundle.mthds"
+ bundle_path.write_text(_MISSPELLED_CONCEPT_BUNDLE, encoding="utf-8")
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await _run_setup(library_dirs=[str(tmp_path)], pipe_code="write_tide_notice", library_dirs_are_callers=True)
+
+ items = raised.value.to_error_report().validation_errors or []
+ concept_items = [item for item in items if item.error_type == PipeValidationErrorType.UNRESOLVED_CONCEPT]
+ assert concept_items, f"expected an unresolved_concept item, got {items!r}"
+ assert all(item.pipe_code == "write_tide_notice" for item in concept_items)
+ # Validating the same file with the same library directory gives the same items.
+ with pytest.raises(ValidateBundleError) as validated:
+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[tmp_path])
+ assert items == validated.value.to_error_report().validation_errors
+
+ async def test_a_hosts_library_dir_refusal_loads_untranslated_by_default(self, tmp_path: Path) -> None:
+ bundle_path = tmp_path / "bundle.mthds"
+ bundle_path.write_text(_MISSPELLED_CONCEPT_BUNDLE, encoding="utf-8")
+
+ with pytest.raises(LibraryError) as raised:
+ await _run_setup(library_dirs=[str(tmp_path)], pipe_code="write_tide_notice")
+
+ assert not isinstance(raised.value, ValidateBundleError)
diff --git a/tests/integration/pipelex/pipeline/test_strict_method_faults.py b/tests/integration/pipelex/pipeline/test_strict_method_faults.py
new file mode 100644
index 000000000..a6d24d404
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_strict_method_faults.py
@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode
+from pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionError
+from pipelex.cogt.llm.llm_setting import LLMSetting
+from pipelex.config import get_config
+from pipelex.pipeline.exceptions import PipelineExecutionError
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.runtime_hub import get_model_deck
+from pipelex.system.pipe_run_mode import PipeRunMode
+from tests.integration.pipelex.pipeline.test_data import LocatedRunFailureTestData, StrictMethodFaultsTestData
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+
+def _strict_problem_document(error: PipelineExecutionError) -> dict[str, Any]:
+ """The body a hosted runner answers with: the run failure's report, projected under STRICT disclosure."""
+ return error.to_error_report().to_problem_document(disclosure_mode=DisclosureMode.STRICT)
+
+
+async def _run_failing(
+ *,
+ pipe_code: str,
+ mthds_content: str,
+ inputs: dict[str, Any],
+ pipe_run_mode: PipeRunMode = PipeRunMode.LIVE,
+) -> PipelineExecutionError:
+ if pipe_run_mode.is_dry:
+ execution_config = get_config().interpreter.pipeline_execution.with_execution_overrides(generate_graph=False, mock_inputs=True)
+ runner = PipelexMTHDSProtocol(pipe_run_mode=pipe_run_mode, execution_config=execution_config)
+ else:
+ runner = PipelexMTHDSProtocol()
+ with pytest.raises(PipelineExecutionError) as exc_info:
+ await runner.execute(pipe_code=pipe_code, mthds_contents=[mthds_content], inputs=inputs)
+ return exc_info.value
+
+
[email protected](loop_scope="class")
+class TestStrictMethodFaults:
+ async def test_parallel_combine_mismatch_is_the_callers_fault(self) -> None:
+ """A branch declared `Idea[]` feeding a single field: HTTP 422, the input domain, and the combine's reason at `analyze`."""
+ error = await _run_failing(
+ pipe_code="flow",
+ mthds_content=LocatedRunFailureTestData.PARALLEL_MTHDS,
+ inputs={},
+ pipe_run_mode=PipeRunMode.DRY,
+ )
+
+ document = _strict_problem_document(error)
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert document["error_type"] == "StuffFactoryError"
+ assert document["detail"] != INTERNAL_ERROR_PLACEHOLDER
+ # The multiplicity next step (the combine's refusal restated with its remedy) is what a STRICT caller reads.
+ assert document["detail"].startswith(
+ "Pipe 'analyze' failed (flow → analyze): PipeParallel 'analyze' cannot combine its branch results into its output 'Report'."
+ )
+ next_step = "Branch 'gen_ideas' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'Report' holds a single item."
+ assert next_step in document["detail"]
+ assert document["user_action"]["kind"] == "change_input"
+ assert document["user_action"]["detail"].startswith(next_step)
+ assert "make branch 'gen_ideas' output a single 'Idea'" in document["user_action"]["detail"]
+
+ async def test_parallel_combine_refusal_no_multiplicity_explains_is_the_callers_fault(self) -> None:
+ """A single `Idea` branch feeding a list of plain texts: no multiplicity to change, the combine's own refusal at 422."""
+ error = await _run_failing(
+ pipe_code="flow",
+ mthds_content=StrictMethodFaultsTestData.PARALLEL_NO_MULTIPLICITY_MTHDS,
+ inputs={},
+ pipe_run_mode=PipeRunMode.DRY,
+ )
+
+ document = _strict_problem_document(error)
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert document["error_type"] == "StuffFactoryError"
+ # The combine's own refusal, kept under STRICT, with no multiplicity advice that could not make it fit.
+ assert document["detail"].startswith("Pipe 'analyze' failed (flow → analyze): Error combining stuffs for concept Review")
+ assert "cannot combine its branch results" not in document["detail"]
+ assert "gives result" not in document["detail"]
+ assert document["user_action"] == {
+ "kind": "change_input",
+ "detail": (
+ "Change the method so that each branch of PipeParallel 'analyze' produces what the field of "
+ "'Review' it feeds expects, a list only where that field is a list, "
+ "and so that every required field is fed by a branch."
+ ),
+ }
+
+ async def test_missing_required_input_is_the_callers_fault(self) -> None:
+ """A run missing a required input: HTTP 422, with a message and a next step naming the input."""
+ error = await _run_failing(pipe_code="greet_flow", mthds_content=StrictMethodFaultsTestData.MISSING_INPUT_MTHDS, inputs={})
+
+ document = _strict_problem_document(error)
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert document["error_type"] == "PipeRunInputsError"
+ assert document["detail"] == "Pipe 'greet_flow' failed: Live run of PipeSequence 'greet_flow': missing required inputs: name."
+ assert document["user_action"] == {"kind": "change_input", "detail": "Provide the missing required inputs of 'greet_flow': name."}
+
+ async def test_model_only_the_method_names_is_the_callers_fault(self) -> None:
+ """A step naming, in an inline setting, a model no entry of the deck names: HTTP 422, its reason, and a next step naming the model."""
+ error = await _run_failing(
+ pipe_code="two_steps",
+ mthds_content=LocatedRunFailureTestData.MODEL_MTHDS,
+ inputs={"topic": "cats"},
+ )
+
+ document = _strict_problem_document(error)
+ unserved_handle = LocatedRunFailureTestData.UNSERVED_MODEL_HANDLE
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert document["error_type"] == "ModelNotFoundError"
+ assert (
+ document["detail"]
+ == f"Pipe 'summarize' failed (two_steps → summarize): Model handle '{unserved_handle}' was not found in the model deck."
+ )
+ assert document["user_action"] == {"kind": "change_model", "detail": f"Change the model '{unserved_handle}' to an LLM the model deck serves."}
+ # Provider and model attribution never reach a STRICT caller, whoever's fault it is.
+ assert "model" not in document
+
+ @pytest.mark.parametrize(
+ ("_topic", "model_reference"),
+ [
+ ("preset", f"${StrictMethodFaultsTestData.DECK_PRESET}"),
+ ("alias", f"@{StrictMethodFaultsTestData.DECK_ALIAS}"),
+ ],
+ )
+ async def test_model_the_deck_names_but_does_not_serve_stays_redacted(self, mocker: MockerFixture, _topic: str, model_reference: str) -> None:
+ """A model a preset or an alias of the deck names, which the deployment does not serve, is not the caller's fault."""
+ model_deck = get_model_deck()
+ unserved_handle = StrictMethodFaultsTestData.DECK_NAMED_UNSERVED_HANDLE
+ mocker.patch.dict(model_deck.llm_presets, {StrictMethodFaultsTestData.DECK_PRESET: LLMSetting(model=unserved_handle, temperature=0.2)})
+ mocker.patch.dict(model_deck.llm_aliases, {StrictMethodFaultsTestData.DECK_ALIAS: unserved_handle})
+ mthds_content = StrictMethodFaultsTestData.DECK_NAMED_MODEL_MTHDS.replace(StrictMethodFaultsTestData.MODEL_REFERENCE_SLOT, model_reference)
+
+ error = await _run_failing(pipe_code="summarize_flow", mthds_content=mthds_content, inputs={"topic": "cats"})
+
+ assert error.pipe_code == "summarize"
+ report = error.to_error_report()
+ assert (
+ report.message
+ == f"Pipe 'summarize' failed (summarize_flow → summarize): Model handle '{unserved_handle}' was not found in the model deck."
+ )
+ document = _strict_problem_document(error)
+ assert document["status"] == 500
+ assert document["error_domain"] == "config"
+ assert document["error_type"] == "ModelNotFoundError"
+ assert document["detail"] == INTERNAL_ERROR_PLACEHOLDER
+ assert "user_action" not in document
+
+ async def test_model_output_that_does_not_fit_its_structure_stays_redacted(self, mocker: MockerFixture) -> None:
+ """A model output the structure refuses, after the re-asks, is data-dependent: not flagged caller-facing."""
+ unfit_output_error = LLMCompletionError(
+ "Structured generation via 'instructor' failed trying to generate schema: Verdict with error: 1 validation error",
+ error_category=InferenceErrorCategory.UNKNOWN,
+ )
+ fake_content_generator = mocker.MagicMock()
+ fake_content_generator.make_object = mocker.AsyncMock(side_effect=unfit_output_error)
+ mocker.patch("pipelex.kernel.llm_ops.get_content_generator", return_value=fake_content_generator)
+
+ error = await _run_failing(
+ pipe_code="judge_flow",
+ mthds_content=StrictMethodFaultsTestData.STRUCTURED_OUTPUT_MTHDS,
+ inputs={"claim": "The sky is green."},
+ )
+
+ assert error.pipe_code == "judge"
+ report = error.to_error_report()
+ assert report.error_type == "LLMCompletionError"
+ assert report.caller_facing_message is False
+ document = _strict_problem_document(error)
+ assert document["status"] == 500
+ assert document["error_domain"] == "runtime"
+ assert document["detail"] == INTERNAL_ERROR_PLACEHOLDER
diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_load_refusals.py b/tests/integration/pipelex/pipeline/test_validate_bundle_load_refusals.py
new file mode 100644
index 000000000..75a1e8e49
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_load_refusals.py
@@ -0,0 +1,372 @@
+"""Pin: every refusal raised while loading a bundle is a verdict item, never a no-verdict fault.
+
+A bundle validator answers either a verdict (valid, or invalid with located items) or "no verdict could
+be produced", which is reserved for a failure of the tool or its environment. These tests load real
+bundles through ``validate_bundle`` and pin the verdict each refusal produces:
+
+- **The unknown model, per pipe type and per reference kind.** A pipe whose model field names a handle,
+ an alias or a preset the deck does not define validates to one ``pipe_validation`` item with the
+ closed ``error_type`` ``unknown_model``, carrying the pipe, the domain, the source file, the field
+ path, the reference as written, the model type and the deck's suggestions, and a ``rename-model`` fix
+ when the deck offers exactly one suggestion. Every pipe type that names a model gives the same item
+ (``PipeExtract`` and ``PipeSearch`` used to turn it into an ``unknown_validation_error`` whose message
+ was a Python repr).
+- **The general arm.** Any other ``input``-domained refusal raised while building a pipe validates to one
+ item located on the pipe and its file, keeping its message only when it is caller-facing; a
+ ``config``-domained fault raised at the same place still propagates as no verdict.
+- **The run path.** Setting up a run on the unknown-model bundle refuses it with the same verdict, its
+ item naming the pipe, whose STRICT projection is still an HTTP 422 carrying the deck check's sentence.
+
+The deck is the test session's own, so the suggestion lists are read off it rather than pinned in
+full, except for the one-suggestion alias whose rename fix is the point of its case.
+"""
+
+from pathlib import Path
+from typing import ClassVar, NamedTuple
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import DisclosureMode, ErrorDomain, PipelexError, ValidationErrorCategory, ValidationErrorItem
+from pipelex.config import get_config
+from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.fixes.planner import RENAME_MODEL_FIX_CODE
+from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.suggested_fix import RemapValueOp
+from pipelex.system.pipe_run_mode import PipeRunMode
+from pipelex.validation_error_types import PipeValidationErrorType
+
+_DOMAIN = "tide_tables"
+
+
+def _llm_bundle(*, model_line: str) -> str:
+ return f"""
+domain = "{_DOMAIN}"
+description = "Write the note telling harbour users when the tide turns"
+main_pipe = "write_tide_note"
+
+[pipe.write_tide_note]
+type = "PipeLLM"
+description = "Write the tide note for the harbour board"
+inputs = {{ tide_times = "Text" }}
+output = "Text"
+{model_line}
+prompt = "Write a short note for the harbour board from these tide times: $tide_times"
+"""
+
+
+_IMG_GEN_BUNDLE = f"""
+domain = "{_DOMAIN}"
+description = "Draw the board announcing the tide times"
+main_pipe = "draw_tide_board"
+
+[pipe.draw_tide_board]
+type = "PipeImgGen"
+description = "Draw the painted board announcing the tide times"
+output = "Image"
+model = "nano-banana-9"
+prompt = "A painted wooden harbour board announcing the tide times, morning light"
+"""
+
+_EXTRACT_BUNDLE = f"""
+domain = "{_DOMAIN}"
+description = "Read the pages of a printed tide almanac"
+main_pipe = "read_almanac_pages"
+
+[pipe.read_almanac_pages]
+type = "PipeExtract"
+description = "Read each page of a scanned tide almanac"
+inputs = {{ almanac_scan = "Document" }}
+output = "Page[]"
+model = "@default-extrct"
+"""
+
+_SEARCH_BUNDLE = f"""
+domain = "{_DOMAIN}"
+description = "Look up the tide times of a harbour"
+main_pipe = "look_up_tides"
+
+[pipe.look_up_tides]
+type = "PipeSearch"
+description = "Look up today's tide times for the harbour"
+inputs = {{ harbour_name = "Text" }}
+output = "SearchResult"
+model = "@default-serch"
+prompt = "What are today's tide times at $harbour_name?"
+"""
+
+
+class _UnknownModelCase(NamedTuple):
+ case_id: str
+ bundle: str
+ pipe_code: str
+ field_name: str
+ model_reference: str
+ model_type: str
+ model_sentence: str
+
+
+_UNKNOWN_MODEL_CASES: list[_UnknownModelCase] = [
+ _UnknownModelCase(
+ case_id="llm_handle",
+ bundle=_llm_bundle(model_line='model = "gpt-5.1"'),
+ pipe_code="write_tide_note",
+ field_name="model",
+ model_reference="gpt-5.1",
+ model_type="llm",
+ model_sentence="Model handle 'gpt-5.1' was not found in the model deck",
+ ),
+ _UnknownModelCase(
+ case_id="llm_alias",
+ bundle=_llm_bundle(model_line='model = "@best-sonet"'),
+ pipe_code="write_tide_note",
+ field_name="model",
+ model_reference="@best-sonet",
+ model_type="llm",
+ model_sentence="Alias 'best-sonet' was not found in the model deck",
+ ),
+ _UnknownModelCase(
+ case_id="llm_preset",
+ bundle=_llm_bundle(model_line='model = "$writting-factual"'),
+ pipe_code="write_tide_note",
+ field_name="model",
+ model_reference="$writting-factual",
+ model_type="llm",
+ model_sentence="LLM preset 'writting-factual' was not found in the model deck",
+ ),
+ _UnknownModelCase(
+ case_id="llm_model_to_structure",
+ bundle=_llm_bundle(model_line='model_to_structure = "@best-sonet"'),
+ pipe_code="write_tide_note",
+ field_name="model_to_structure",
+ model_reference="@best-sonet",
+ model_type="llm",
+ model_sentence="Alias 'best-sonet' was not found in the model deck",
+ ),
+ _UnknownModelCase(
+ case_id="img_gen_handle",
+ bundle=_IMG_GEN_BUNDLE,
+ pipe_code="draw_tide_board",
+ field_name="model",
+ model_reference="nano-banana-9",
+ model_type="img_gen",
+ model_sentence="Model handle 'nano-banana-9' was not found in the model deck",
+ ),
+ _UnknownModelCase(
+ case_id="extract_alias",
+ bundle=_EXTRACT_BUNDLE,
+ pipe_code="read_almanac_pages",
+ field_name="model",
+ model_reference="@default-extrct",
+ model_type="text_extractor",
+ model_sentence="Alias 'default-extrct' was not found in the model deck",
+ ),
+ _UnknownModelCase(
+ case_id="search_alias",
+ bundle=_SEARCH_BUNDLE,
+ pipe_code="look_up_tides",
+ field_name="model",
+ model_reference="@default-serch",
+ model_type="search",
+ model_sentence="Alias 'default-serch' was not found in the model deck",
+ ),
+]
+
+
+def _preliminary_text_bundle(*, model_line: str) -> str:
+ """A PipeLLM the elaborator splits into ``extract_tide__draft_text`` and ``extract_tide__structure`` helpers."""
+ return f"""
+domain = "{_DOMAIN}"
+description = "Read the tide fact the harbour board publishes"
+main_pipe = "extract_tide"
+
+[concept.TideFact]
+description = "When the tide turns at one harbour"
+
+[concept.TideFact.structure]
+harbour = {{ type = "text", description = "The harbour's name", required = true }}
+
+[pipe.extract_tide]
+type = "PipeLLM"
+description = "Extract the tide fact from the harbour board's notice"
+inputs = {{ tide_times = "Text" }}
+output = "TideFact"
+structuring_method = "preliminary_text"
+{model_line}
+prompt = "Extract the tide fact from this notice: $tide_times"
+"""
+
+
+def _write_bundle(*, directory: Path, content: str) -> Path:
+ bundle_path = directory / "bundle.mthds"
+ bundle_path.write_text(content, encoding="utf-8")
+ return bundle_path
+
+
+async def _single_item(*, bundle_path: Path) -> ValidationErrorItem:
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[bundle_path.parent])
+ items = raised.value.to_error_report().validation_errors or []
+ assert len(items) == 1, f"expected exactly one item, got {items!r}"
+ return items[0]
+
+
+class _CallerFacingRefusalError(PipelexError):
+ """An input refusal whose message was authored for the caller — stands in for any future one."""
+
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
+
+
+class _InternalInputRefusalError(PipelexError):
+ """An input refusal whose message is internal text the verdict must not carry."""
+
+ error_domain = ErrorDomain.INPUT
+ _declared_title: ClassVar[str | None] = "Harbour board refusal"
+
+
+class _ConfigFaultError(PipelexError):
+ """A fault of the environment, which is no verdict about the bundle."""
+
+ error_domain = ErrorDomain.CONFIG
+
+
[email protected](loop_scope="class")
+class TestValidateBundleLoadRefusals:
+ @pytest.mark.parametrize("case", _UNKNOWN_MODEL_CASES, ids=[case.case_id for case in _UNKNOWN_MODEL_CASES])
+ async def test_unknown_model_is_one_located_unknown_model_item(self, case: _UnknownModelCase, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=case.bundle)
+
+ item = await _single_item(bundle_path=bundle_path)
+
+ assert item.category == ValidationErrorCategory.PIPE_VALIDATION
+ assert item.error_type == PipeValidationErrorType.UNKNOWN_MODEL
+ assert item.pipe_code == case.pipe_code
+ assert item.domain_code == _DOMAIN
+ assert item.source == str(bundle_path)
+ assert item.field_name == case.field_name
+ assert item.field_path == f"pipe.{case.pipe_code}.{case.field_name}"
+ assert item.model_reference == case.model_reference
+ assert item.model_type == case.model_type
+ assert case.model_sentence in item.message
+ assert f"Pipe '{case.pipe_code}'" in item.message
+ # The suggestions ride as a list and stay in the message, for the consumers that keep only it.
+ assert item.suggestions, f"the deck offers no close match for {case.model_reference!r}"
+ for suggestion in item.suggestions:
+ assert suggestion in item.message
+
+ async def test_one_suggestion_carries_a_rename_fix(self, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=_llm_bundle(model_line='model = "@best-sonet"'))
+
+ item = await _single_item(bundle_path=bundle_path)
+
+ assert item.suggestions == ["@best-gpt"]
+ fix = item.suggested_fix
+ assert fix is not None
+ assert fix.fix_code == RENAME_MODEL_FIX_CODE
+ assert not fix.safety.is_safe, "a fuzzy match is never auto-applied"
+ assert fix.source == str(bundle_path)
+ assert fix.ops == [RemapValueOp(table_path=["pipe", "write_tide_note"], key="model", mapping={"@best-sonet": "@best-gpt"})]
+
+ @pytest.mark.parametrize(
+ ("model_line", "field_name"),
+ [
+ ('model = "@best-sonet"', "model"),
+ ('model_to_structure = "@best-sonet"', "model_to_structure"),
+ ],
+ ids=["draft_text_helper", "structure_helper"],
+ )
+ async def test_preliminary_text_helper_refusal_is_located_on_the_authored_pipe(self, tmp_path: Path, model_line: str, field_name: str) -> None:
+ """The elaborator's helper pipes are not in the author's file, so the item and its fix name the authored pipe and field."""
+ bundle_path = _write_bundle(directory=tmp_path, content=_preliminary_text_bundle(model_line=model_line))
+
+ item = await _single_item(bundle_path=bundle_path)
+
+ assert item.error_type == PipeValidationErrorType.UNKNOWN_MODEL
+ assert item.pipe_code == "extract_tide"
+ assert item.field_name == field_name
+ assert item.field_path == f"pipe.extract_tide.{field_name}"
+ assert item.source == str(bundle_path)
+ assert item.message.startswith(f"Pipe 'extract_tide' (PipeLLM), field '{field_name}': ")
+ fix = item.suggested_fix
+ assert fix is not None
+ assert fix.ops == [RemapValueOp(table_path=["pipe", "extract_tide"], key=field_name, mapping={"@best-sonet": "@best-gpt"})]
+
+ async def test_several_suggestions_carry_no_fix(self, tmp_path: Path) -> None:
+ bundle_path = _write_bundle(directory=tmp_path, content=_llm_bundle(model_line='model = "$writting-factual"'))
+
+ item = await _single_item(bundle_path=bundle_path)
+
+ assert item.suggestions is not None
+ assert len(item.suggestions) > 1
+ assert item.suggested_fix is None
+
+ async def test_caller_facing_input_refusal_at_load_is_a_located_item(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ mocker.patch(
+ "pipelex.pipe_operators.llm.pipe_llm.check_llm_choice_with_deck",
+ side_effect=_CallerFacingRefusalError("The harbour board cannot show tides this far upriver."),
+ )
+ bundle_path = _write_bundle(directory=tmp_path, content=_llm_bundle(model_line='model = "@best-gpt"'))
+
+ item = await _single_item(bundle_path=bundle_path)
+
+ assert item.category == ValidationErrorCategory.PIPE_VALIDATION
+ assert item.error_type is None
+ assert item.pipe_code == "write_tide_note"
+ assert item.domain_code == _DOMAIN
+ assert item.source == str(bundle_path)
+ assert "The harbour board cannot show tides this far upriver." in item.message
+
+ async def test_internal_input_refusal_carries_its_title_not_its_message(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ mocker.patch(
+ "pipelex.pipe_operators.llm.pipe_llm.check_llm_choice_with_deck",
+ side_effect=_InternalInputRefusalError("internal detail: registry slot 7 is stale"),
+ )
+ bundle_path = _write_bundle(directory=tmp_path, content=_llm_bundle(model_line='model = "@best-gpt"'))
+
+ item = await _single_item(bundle_path=bundle_path)
+
+ assert item.pipe_code == "write_tide_note"
+ assert item.source == str(bundle_path)
+ assert "Harbour board refusal" in item.message
+ assert "registry slot 7" not in item.message
+
+ async def test_config_fault_at_load_stays_no_verdict(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ fault = _ConfigFaultError("the model deck could not be read")
+ mocker.patch("pipelex.pipe_operators.llm.pipe_llm.check_llm_choice_with_deck", side_effect=fault)
+ bundle_path = _write_bundle(directory=tmp_path, content=_llm_bundle(model_line='model = "@best-gpt"'))
+
+ with pytest.raises(_ConfigFaultError) as raised:
+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[bundle_path.parent])
+
+ assert raised.value is fault
+
+ async def test_run_setup_refuses_the_unknown_model_naming_the_pipe(self) -> None:
+ execution_config = get_config().interpreter.pipeline_execution.with_execution_overrides(generate_graph=False, mock_inputs=True)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await pipeline_run_setup(
+ storage_scope="test/scope",
+ user_id="test-user",
+ execution_config=execution_config,
+ mthds_contents=[_llm_bundle(model_line='model = "gpt-5.1"')],
+ pipe_code="write_tide_note",
+ pipe_run_mode=PipeRunMode.DRY,
+ )
+
+ assert isinstance(raised.value.__cause__, PipeOperatorModelChoiceError)
+ report = raised.value.to_error_report()
+ (item,) = report.validation_errors or []
+ assert item.error_type == PipeValidationErrorType.UNKNOWN_MODEL
+ assert item.pipe_code == "write_tide_note"
+ assert item.field_name == "model"
+ assert report.http_status == 422
+ strict_payload = report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert strict_payload["error_type"] == "ValidateBundleError"
+ assert strict_payload["error_domain"] == "input"
+ assert "Pipe 'write_tide_note'" in strict_payload["message"]
+ assert "Model handle 'gpt-5.1' was not found in the model deck" in strict_payload["message"]
+ (strict_item,) = strict_payload["validation_errors"]
+ assert strict_item["error_type"] == "unknown_model"
diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py
index b129cbb36..c0d8f303e 100644
--- a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py
+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py
@@ -25,9 +25,9 @@ from pytest_mock import MockerFixture
from pipelex.base_exceptions import PipelexUnexpectedError, ValidationErrorCategory, ValidationErrorItem
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.pipeline.exceptions import ValidateBundleError
-from pipelex.pipeline.validate_bundle import (
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.pipeline.validate_bundle_translation import (
_backfill_pipe_error_source, # pyright: ignore[reportPrivateUsage]
- validate_bundle,
)
from pipelex.validation_error_types import PipeValidationErrorType
@@ -150,7 +150,7 @@ class TestValidateBundleSourceThreading:
source_path = tmp_path / "legacy.mthds"
manager = mocker.Mock()
manager.get_pipe_source.return_value = source_path
- mocker.patch("pipelex.pipeline.validate_bundle.get_library_manager", return_value=manager)
+ mocker.patch("pipelex.pipeline.validate_bundle_translation.get_library_manager", return_value=manager)
pipe_error = PipeValidationError(message="invalid", domain_code="demo", pipe_code="broken")
_backfill_pipe_error_source(pipe_error)
diff --git a/tests/integration/pipelex/pipeline/test_validation_detail_kept.py b/tests/integration/pipelex/pipeline/test_validation_detail_kept.py
new file mode 100644
index 000000000..3853b3403
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_validation_detail_kept.py
@@ -0,0 +1,179 @@
+"""Pin: every validation error reaches the reader, with the locators the raise site had.
+
+Validation used to lose detail before the verdict was built. These tests load real bundles through
+``validate_bundle`` and pin what the verdict now keeps:
+
+- **Every error is an item.** A misspelled field (pydantic's ``extra_forbidden``, which no categorizer
+ knows) beside an undeclared prompt variable gives two items, the typo as an uncategorized
+ ``blueprint_validation`` item carrying its source, its pipe and its field path.
+- **One located item per failing dry-run pipe.** A ``PipeParallel`` whose plural branch feeds a single
+ field fails its combine; nested in a ``PipeSequence``, the failure used to reach the reader as one
+ item holding a Python repr of the sweep's records, once for each level of nesting. It is now one
+ ``dry_run`` item for the innermost failing pipe, carrying its code, domain and source, whose text
+ follows the disclosure rule: the failure's own message only when it is caller-facing.
+- **The positions the parser knew.** A TOML syntax error's item carries its 1-based line and column, and
+ an unresolved concept's item lists the concepts its domain declares.
+"""
+
+from pathlib import Path
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.cogt.inference.error_classification import UserAction
+from pipelex.core.stuffs.exceptions import StuffFactoryError
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.validation_error_types import PipeValidationErrorType
+from tests.integration.pipelex.test_data import ValidationDetailBundles
+
+
+def _keep_unclassified(self: StuffFactoryError, *, user_action: UserAction | None = None) -> StuffFactoryError:
+ """Stands in for ``as_caller_fault``, leaving the error unclassified."""
+ del user_action
+ return self
+
+
+async def _validation_items(*, bundle: str, dry_run_pipe_codes: list[str] | None = None) -> list[ValidationErrorItem]:
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[bundle], mthds_sources=[ValidationDetailBundles.SOURCE], dry_run_pipe_codes=dry_run_pipe_codes)
+ return list(exc_info.value.to_error_report().validation_errors or [])
+
+
+class TestValidationDetailKept:
+ @pytest.mark.asyncio
+ async def test_an_uncategorized_error_is_kept_beside_a_categorized_one(self) -> None:
+ items = await _validation_items(bundle=ValidationDetailBundles.TYPO_BESIDE_UNDECLARED_VARIABLE)
+
+ assert len(items) == 2
+ typo_item = next(item for item in items if item.error_type is None)
+ assert typo_item.category == ValidationErrorCategory.BLUEPRINT_VALIDATION
+ assert typo_item.pipe_code == "summarize_notes"
+ assert typo_item.domain_code == ValidationDetailBundles.DOMAIN
+ assert typo_item.source == ValidationDetailBundles.SOURCE
+ assert typo_item.field_path == "pipe.summarize_notes.promtp"
+ assert typo_item.message == "Validation error at 'pipe.summarize_notes.promtp': Extra inputs are not permitted"
+
+ variable_item = next(item for item in items if item.error_type is not None)
+ assert variable_item.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE
+ assert variable_item.pipe_code == "translate_notes"
+ assert variable_item.variable_names == ["language"]
+
+ @pytest.mark.asyncio
+ async def test_a_nested_dry_run_failure_is_one_item_at_the_innermost_pipe(self) -> None:
+ # The combine's refusal is the caller's own method fault, restated with its multiplicity next step
+ # and classified caller-facing at its raise site, so the item carries that restatement.
+ items = await _validation_items(bundle=ValidationDetailBundles.NESTED_PARALLEL_MISMATCH)
+
+ (item,) = items
+ assert item.category == ValidationErrorCategory.DRY_RUN
+ assert item.error_type == "DryRunError"
+ assert item.pipe_code == "analyze_topic"
+ assert item.domain_code == ValidationDetailBundles.DOMAIN
+ assert item.source == ValidationDetailBundles.SOURCE
+ assert item.message.startswith(
+ "Pipe 'analyze_topic' failed its dry run: PipeParallel 'analyze_topic' cannot combine its branch results into its output 'IdeaReport'."
+ )
+ assert "Branch 'propose_ideas' gives result 'ideas' as a list, 'Idea[]'" in item.message
+ assert not any(marker in item.message for marker in ValidationDetailBundles.RECORD_REPR_MARKERS)
+
+ @pytest.mark.asyncio
+ async def test_a_dry_run_failure_that_is_not_caller_facing_names_its_title(self, mocker: MockerFixture) -> None:
+ # The combine classifies its refusal as the caller's fault; with that classification withheld, the
+ # same failure is not caller-facing, and the item names its title.
+ mocker.patch.object(StuffFactoryError, "as_caller_fault", new=_keep_unclassified)
+
+ items = await _validation_items(bundle=ValidationDetailBundles.NESTED_PARALLEL_MISMATCH)
+
+ (item,) = items
+ assert item.pipe_code == "analyze_topic"
+ assert item.message == f"Pipe 'analyze_topic' failed its dry run: {StuffFactoryError.title()}"
+
+ @pytest.mark.asyncio
+ async def test_the_enclosing_pipe_alone_reports_the_innermost_failing_pipe(self) -> None:
+ # Only the sequence is dry-run, and its failure is reported where it happened: at the parallel.
+ items = await _validation_items(bundle=ValidationDetailBundles.NESTED_PARALLEL_MISMATCH, dry_run_pipe_codes=["run_workshop"])
+
+ (item,) = items
+ assert item.category == ValidationErrorCategory.DRY_RUN
+ assert item.pipe_code == "analyze_topic"
+ assert item.domain_code == ValidationDetailBundles.DOMAIN
+
+ @pytest.mark.asyncio
+ async def test_a_toml_syntax_error_carries_its_line_and_column(self) -> None:
+ (item,) = await _validation_items(bundle=ValidationDetailBundles.TOML_SYNTAX_ERROR)
+
+ assert item.category == ValidationErrorCategory.BLUEPRINT_VALIDATION
+ assert item.error_type is None
+ assert item.source == ValidationDetailBundles.SOURCE
+ assert item.line == 2
+ assert item.column == 38
+
+ @pytest.mark.asyncio
+ async def test_an_unresolved_concept_lists_the_concepts_its_domain_declares(self) -> None:
+ (item,) = await _validation_items(bundle=ValidationDetailBundles.UNRESOLVED_CONCEPT)
+
+ assert item.error_type == PipeValidationErrorType.UNRESOLVED_CONCEPT
+ assert item.concept_code == "IdeaRanking"
+ assert item.declared_concepts == ["Idea", "IdeaSummary"]
+
+ @pytest.mark.asyncio
+ async def test_a_failure_in_a_library_pipe_never_names_the_host_file(self, tmp_path: Path) -> None:
+ """A pipe loaded from the host's library directories is located, but its file on the host stays out of the verdict."""
+ library_dir = tmp_path / "host_library"
+ library_dir.mkdir()
+ (library_dir / "idea_board.mthds").write_text(ValidationDetailBundles.NESTED_PARALLEL_MISMATCH, encoding="utf-8")
+
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(
+ mthds_contents=[ValidationDetailBundles.CALLER_OF_LIBRARY_PARALLEL],
+ mthds_sources=[ValidationDetailBundles.CALLER_SOURCE],
+ library_dirs=[library_dir],
+ )
+
+ (item,) = exc_info.value.to_error_report().validation_errors or []
+ assert item.category == ValidationErrorCategory.DRY_RUN
+ assert (item.pipe_code, item.domain_code) == ("analyze_topic", ValidationDetailBundles.DOMAIN)
+ assert item.source is None
+ assert str(tmp_path) not in item.message
+
+ @pytest.mark.asyncio
+ async def test_a_failure_in_the_callers_own_library_pipe_names_its_file(self, tmp_path: Path) -> None:
+ """Submitted content validated beside directories that are the caller's own: the failing library pipe keeps its file."""
+ library_dir = tmp_path / "caller_library"
+ library_dir.mkdir()
+ library_file = library_dir / "idea_board.mthds"
+ library_file.write_text(ValidationDetailBundles.NESTED_PARALLEL_MISMATCH, encoding="utf-8")
+
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(
+ mthds_contents=[ValidationDetailBundles.CALLER_OF_LIBRARY_PARALLEL],
+ mthds_sources=[ValidationDetailBundles.CALLER_SOURCE],
+ library_dirs=[library_dir],
+ library_dirs_are_callers=True,
+ )
+
+ (item,) = exc_info.value.to_error_report().validation_errors or []
+ assert item.category == ValidationErrorCategory.DRY_RUN
+ assert (item.pipe_code, item.domain_code) == ("analyze_topic", ValidationDetailBundles.DOMAIN)
+ assert item.source is not None
+ assert Path(item.source).resolve() == library_file.resolve()
+
+ @pytest.mark.asyncio
+ async def test_a_failure_in_a_sibling_file_of_a_local_method_names_that_file(self, tmp_path: Path) -> None:
+ """Validated from a file on the caller's own disk, a failure in a sibling file of the method keeps that file."""
+ method_dir = tmp_path / "method"
+ method_dir.mkdir()
+ entry_file = method_dir / "main.mthds"
+ entry_file.write_text(ValidationDetailBundles.CALLER_OF_LIBRARY_PARALLEL, encoding="utf-8")
+ sibling_file = method_dir / "idea_board.mthds"
+ sibling_file.write_text(ValidationDetailBundles.NESTED_PARALLEL_MISMATCH, encoding="utf-8")
+
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_file_path=entry_file, library_dirs=[method_dir])
+
+ (item,) = exc_info.value.to_error_report().validation_errors or []
+ assert (item.pipe_code, item.domain_code) == ("analyze_topic", ValidationDetailBundles.DOMAIN)
+ assert item.source is not None
+ assert Path(item.source).resolve() == sibling_file.resolve()
diff --git a/tests/integration/pipelex/pipeline/test_verdict_names_no_host_path.py b/tests/integration/pipelex/pipeline/test_verdict_names_no_host_path.py
new file mode 100644
index 000000000..976a8d5c9
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_verdict_names_no_host_path.py
@@ -0,0 +1,400 @@
+"""Pin: a verdict a STRICT caller reads names no path on the host.
+
+Every validation item is caller-facing, and STRICT disclosure keeps the items and the verdict's message
+verbatim, so neither may carry a path on the host, in an item's ``source`` or in any message. Two origins
+used to put one there:
+
+- **An address-based dependency.** A package the bundle depends on by address is installed on the host,
+ and its bundles were named by their install path. They are named by the package's address and the
+ bundle's path inside the package instead, on every surface: the ``source`` of an item located inside the
+ dependency, and the files a duplicate declaration inside it names.
+- **The host's own library directories.** When submitted content is validated, the library directories
+ loaded beside it are the host's: an item located in one of their files carries no ``source``, and a message
+ naming one of their files names ``<host library file>`` instead. A run loads a host's directories
+ untranslated, so their refusal is no verdict at all, and STRICT redacts it.
+
+A bundle validated from a file keeps the full paths of its library directories: there they are the caller's, as
+they are for a runtime told its library directories are the caller's own (``library_dirs_are_callers``).
+"""
+
+import json
+from pathlib import Path
+from typing import Any, NamedTuple
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import DisclosureMode, PipelexError, ValidationErrorItem
+from pipelex.config import get_config
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.pipeline.validate_bundle_translation import HOST_LIBRARY_FILE_PLACEHOLDER
+from pipelex.system.pipe_run_mode import PipeRunMode
+from pipelex.system.registries.func_registry import func_registry
+from pipelex.validation_error_types import PipeValidationErrorType
+
+_DEPENDENCY_ADDRESS = "github.com/acme-tests/harbour-methods/tides"
+
+_DEPENDENCY_MANIFEST = """
+[package]
+name = "tides"
+address = "github.com/acme-tests/harbour-methods"
+version = "0.1.0"
+description = "Tide notices for the harbour board, a package the tests depend on by address"
+
+[exports.tides]
+pipes = ["write_tide_notice"]
+"""
+
+_NOTICE_PIPE = """
+[pipe.write_tide_notice]
+type = "PipeLLM"
+description = "Write the tide notice for the harbour board"
+inputs = {{ tide_times = "Text" }}
+output = "Text"
+{model_line}
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+# A dependency bundle naming a model the deck does not define: the load refuses it with an item located
+# on the dependency's pipe and file.
+_DEPENDENCY_UNKNOWN_MODEL_BUNDLE = """
+domain = "tides"
+description = "Write tide notices for the harbour board"
+""" + _NOTICE_PIPE.format(model_line='model = "@best-sonet"')
+
+_DEPENDENCY_NOTICE_BUNDLE = """
+domain = "tides"
+description = "Write tide notices for the harbour board"
+""" + _NOTICE_PIPE.format(model_line="")
+
+# The caller's bundle, which runs the dependency's pipe by the package's address.
+_CALLER_BUNDLE = f"""
+domain = "harbour_notices"
+description = "Post notices on the harbour board"
+main_pipe = "post_tide_notice"
+
+[pipe.post_tide_notice]
+type = "PipeSequence"
+description = "Post the tide notice on the harbour board"
+inputs = {{ tide_times = "Text" }}
+output = "Text"
+steps = [{{ pipe = "{_DEPENDENCY_ADDRESS}->tides.write_tide_notice", result = "tide_notice" }}]
+"""
+
+_VALID_CALLER_BUNDLE = """
+domain = "harbour_notices"
+description = "Post notices on the harbour board"
+main_pipe = "write_board_notice"
+
+[pipe.write_board_notice]
+type = "PipeLLM"
+description = "Write the notice for the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text"
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+# A library bundle whose pipe outputs a concept its domain never declares.
+_MISSPELLED_CONCEPT_LIBRARY_BUNDLE = """
+domain = "harbour_board"
+description = "Notices of the harbour board"
+
+[concept.BoardNotice]
+description = "A notice pinned on the harbour board"
+
+[pipe.pin_board_notice]
+type = "PipeLLM"
+description = "Write a notice to pin on the harbour board"
+inputs = { tide_times = "Text" }
+output = "BoardNotise"
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+# A library sequence declaring an output its last step does not produce: refused while the library is validated,
+# located on the sequence from the pipe-source map.
+_OUTPUT_MISMATCH_LIBRARY_BUNDLE = """
+domain = "harbour_board"
+description = "Notices of the harbour board"
+
+[pipe.post_board_notice]
+type = "PipeSequence"
+description = "Post a notice on the harbour board"
+inputs = { tide_times = "Text" }
+output = "Image"
+steps = [{ pipe = "write_board_notice", result = "board_notice" }]
+
+[pipe.write_board_notice]
+type = "PipeLLM"
+description = "Write a notice for the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text"
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+_BOARD_NOTICE_PIPE_BUNDLE = """
+domain = "harbour_board"
+description = "Notices of the harbour board"
+
+[pipe.pin_board_notice]
+type = "PipeLLM"
+description = "Write a notice to pin on the harbour board"
+inputs = { tide_times = "Text" }
+output = "Text"
+prompt = "Write a short notice for the harbour board from these tide times: $tide_times"
+"""
+
+
+# Two host library files registering a PipeFunc under the same name: the registry refuses the second, naming
+# both by the module names it imported them under, which it spells from their absolute paths.
+_HOST_PIPE_FUNC_NAME = "format_harbour_tide_board_for_host_path_test"
+
+_HOST_PIPE_FUNC_MODULE = f"""
+from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.system.registries.func_registry import pipe_func
+
+
+@pipe_func()
+async def {_HOST_PIPE_FUNC_NAME}(working_memory: WorkingMemory) -> TextContent:
+ return TextContent(text="{{flavor}}")
+"""
+
+
+def _execution_config() -> Any:
+ return get_config().interpreter.pipeline_execution.with_execution_overrides(generate_graph=False, generate_usage=False, mock_inputs=True)
+
+
+async def _run_setup(**kwargs: Any) -> None:
+ await pipeline_run_setup(
+ storage_scope="test/scope",
+ user_id="test-user",
+ execution_config=_execution_config(),
+ pipe_run_mode=PipeRunMode.DRY,
+ **kwargs,
+ )
+
+
+def _write(*, path: Path, content: str) -> Path:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(content, encoding="utf-8")
+ return path
+
+
+def _host_path_markers(tmp_path: Path) -> list[str]:
+ """The spellings of the test's directory on this host, any of which in a payload is a host path."""
+ return sorted({str(tmp_path), str(tmp_path.resolve())})
+
+
+def _strict_payload(verdict: ValidateBundleError) -> dict[str, Any]:
+ return verdict.to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+
+
+def _assert_names_no_host_path(*, payload: dict[str, Any], tmp_path: Path) -> None:
+ serialized = json.dumps(payload)
+ for marker in _host_path_markers(tmp_path):
+ assert marker not in serialized, f"the STRICT payload names a path on the host ({marker}): {serialized}"
+
+
+class _Surface(NamedTuple):
+ surface_id: str
+ description: str
+
+
+_SURFACES = [
+ _Surface(surface_id="validate_contents", description="validating submitted content"),
+ _Surface(surface_id="validate_contents_beside_host_library", description="validating submitted content beside a host's library"),
+ _Surface(surface_id="validate_file", description="validating a bundle file"),
+ _Surface(surface_id="run_contents", description="running submitted content"),
+ _Surface(surface_id="run_contents_beside_host_library", description="running submitted content beside a host's library"),
+]
+
+
[email protected](name="installed_methods_dir")
+def installed_methods_dir_fixture(tmp_path: Path, mocker: MockerFixture) -> Path:
+ """Install methods in the test's own directory only, never in the machine's ones."""
+ project_methods_dir = tmp_path / "host" / "installed-methods"
+ project_methods_dir.mkdir(parents=True)
+ mocker.patch("pipelex.cli.installed_methods.GLOBAL_METHODS_DIR", tmp_path / "host" / "global-methods")
+ mocker.patch("pipelex.cli.installed_methods.PROJECT_METHODS_DIR", project_methods_dir)
+ return project_methods_dir
+
+
+def _install_dependency(*, methods_dir: Path, bundles: dict[str, str]) -> Path:
+ package_dir = methods_dir / "tides"
+ _write(path=package_dir / "METHODS.toml", content=_DEPENDENCY_MANIFEST)
+ for path_in_package, content in bundles.items():
+ _write(path=package_dir / path_in_package, content=content)
+ return package_dir
+
+
+def _valid_host_library(*, tmp_path: Path) -> Path:
+ host_library_dir = tmp_path / "host" / "library"
+ _write(path=host_library_dir / "harbour_board.mthds", content=_BOARD_NOTICE_PIPE_BUNDLE)
+ return host_library_dir
+
+
+async def _load_on(*, surface: _Surface, caller_bundle: str, tmp_path: Path) -> None:
+ match surface.surface_id:
+ case "validate_contents":
+ await validate_bundle(mthds_contents=[caller_bundle])
+ case "validate_contents_beside_host_library":
+ await validate_bundle(mthds_contents=[caller_bundle], library_dirs=[_valid_host_library(tmp_path=tmp_path)])
+ case "validate_file":
+ caller_file = _write(path=tmp_path / "caller" / "harbour_notices.mthds", content=caller_bundle)
+ await validate_bundle(mthds_file_path=caller_file)
+ case "run_contents":
+ await _run_setup(mthds_contents=[caller_bundle])
+ case "run_contents_beside_host_library":
+ await _run_setup(mthds_contents=[caller_bundle], library_dirs=[str(_valid_host_library(tmp_path=tmp_path))])
+ case _:
+ pytest.fail(f"unknown surface {surface.surface_id}")
+
+
+async def _verdict_on(*, surface: _Surface, caller_bundle: str, tmp_path: Path) -> ValidateBundleError:
+ with pytest.raises(ValidateBundleError) as raised:
+ await _load_on(surface=surface, caller_bundle=caller_bundle, tmp_path=tmp_path)
+ return raised.value
+
+
[email protected](loop_scope="class")
+class TestVerdictNamesNoHostPath:
+ @pytest.mark.parametrize("surface", _SURFACES, ids=[surface.surface_id for surface in _SURFACES])
+ async def test_a_dependency_refusal_is_located_by_the_packages_address(
+ self, surface: _Surface, installed_methods_dir: Path, tmp_path: Path
+ ) -> None:
+ _install_dependency(methods_dir=installed_methods_dir, bundles={"notices/tide_notices.mthds": _DEPENDENCY_UNKNOWN_MODEL_BUNDLE})
+
+ verdict = await _verdict_on(surface=surface, caller_bundle=_CALLER_BUNDLE, tmp_path=tmp_path)
+
+ items = verdict.to_error_report().validation_errors or []
+ (item,) = [item for item in items if item.error_type == PipeValidationErrorType.UNKNOWN_MODEL]
+ assert item.pipe_code == "write_tide_notice"
+ # The package's address, then the bundle's path inside the package: never where the host installed it.
+ assert item.source == f"{_DEPENDENCY_ADDRESS}/notices/tide_notices.mthds", surface.description
+ _assert_names_no_host_path(payload=_strict_payload(verdict), tmp_path=tmp_path)
+
+ @pytest.mark.parametrize("surface", _SURFACES, ids=[surface.surface_id for surface in _SURFACES])
+ async def test_a_duplicate_declaration_in_a_dependency_names_its_files_by_address(
+ self, surface: _Surface, installed_methods_dir: Path, tmp_path: Path
+ ) -> None:
+ _install_dependency(
+ methods_dir=installed_methods_dir,
+ bundles={"notices/tide_notices.mthds": _DEPENDENCY_NOTICE_BUNDLE, "notices/tide_notices_copy.mthds": _DEPENDENCY_NOTICE_BUNDLE},
+ )
+
+ verdict = await _verdict_on(surface=surface, caller_bundle=_CALLER_BUNDLE, tmp_path=tmp_path)
+
+ items: list[ValidationErrorItem] = verdict.to_error_report().validation_errors or []
+ (item,) = items
+ assert f"'{_DEPENDENCY_ADDRESS}/notices/tide_notices.mthds'" in item.message, surface.description
+ assert f"'{_DEPENDENCY_ADDRESS}/notices/tide_notices_copy.mthds'" in item.message, surface.description
+ _assert_names_no_host_path(payload=_strict_payload(verdict), tmp_path=tmp_path)
+
+ async def test_a_host_library_item_carries_no_source_on_submitted_content(self, tmp_path: Path) -> None:
+ host_library_dir = tmp_path / "host" / "library"
+ _write(path=host_library_dir / "harbour_board.mthds", content=_MISSPELLED_CONCEPT_LIBRARY_BUNDLE)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_contents=[_VALID_CALLER_BUNDLE], library_dirs=[host_library_dir])
+
+ items = raised.value.to_error_report().validation_errors or []
+ concept_items = [item for item in items if item.error_type == PipeValidationErrorType.UNRESOLVED_CONCEPT]
+ assert concept_items, f"expected an unresolved_concept item, got {items!r}"
+ assert all(item.pipe_code == "pin_board_notice" for item in concept_items)
+ # Located by its pipe and domain, never by its file on the host.
+ assert all(item.source is None for item in items)
+ _assert_names_no_host_path(payload=_strict_payload(raised.value), tmp_path=tmp_path)
+
+ async def test_a_host_library_pipe_located_from_its_source_names_no_host_file(self, tmp_path: Path) -> None:
+ host_library_dir = tmp_path / "host" / "library"
+ _write(path=host_library_dir / "harbour_board.mthds", content=_OUTPUT_MISMATCH_LIBRARY_BUNDLE)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_contents=[_VALID_CALLER_BUNDLE], library_dirs=[host_library_dir])
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert item.pipe_code == "post_board_notice"
+ assert item.source is None
+ assert item.field_path is None
+ _assert_names_no_host_path(payload=_strict_payload(raised.value), tmp_path=tmp_path)
+
+ async def test_a_host_library_message_names_no_host_file_on_submitted_content(self, tmp_path: Path) -> None:
+ host_library_dir = tmp_path / "host" / "library"
+ _write(path=host_library_dir / "harbour_board.mthds", content=_BOARD_NOTICE_PIPE_BUNDLE)
+ _write(path=host_library_dir / "harbour_board_copy.mthds", content=_BOARD_NOTICE_PIPE_BUNDLE)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_contents=[_VALID_CALLER_BUNDLE], library_dirs=[host_library_dir])
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert "harbour_board.pin_board_notice" in item.message
+ assert item.message.count(HOST_LIBRARY_FILE_PLACEHOLDER) >= 2
+ _assert_names_no_host_path(payload=_strict_payload(raised.value), tmp_path=tmp_path)
+
+ async def test_a_run_answers_a_host_library_refusal_without_a_host_path(self, tmp_path: Path) -> None:
+ host_library_dir = tmp_path / "host" / "library"
+ _write(path=host_library_dir / "harbour_board.mthds", content=_MISSPELLED_CONCEPT_LIBRARY_BUNDLE)
+
+ with pytest.raises(PipelexError) as raised:
+ await _run_setup(mthds_contents=[_VALID_CALLER_BUNDLE], library_dirs=[str(host_library_dir)])
+
+ assert not isinstance(raised.value, ValidateBundleError), "a host's library directories load untranslated on a run"
+ strict_payload = raised.value.to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert "validation_errors" not in strict_payload
+ _assert_names_no_host_path(payload=strict_payload, tmp_path=tmp_path)
+
+ async def test_a_bundle_file_keeps_the_paths_of_its_library_directories(self, tmp_path: Path) -> None:
+ library_dir = tmp_path / "caller" / "library"
+ library_file = _write(path=library_dir / "harbour_board.mthds", content=_MISSPELLED_CONCEPT_LIBRARY_BUNDLE)
+ caller_file = _write(path=tmp_path / "caller" / "harbour_notices.mthds", content=_VALID_CALLER_BUNDLE)
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_file_path=caller_file, library_dirs=[library_dir])
+
+ items = raised.value.to_error_report().validation_errors or []
+ concept_items = [item for item in items if item.error_type == PipeValidationErrorType.UNRESOLVED_CONCEPT]
+ assert concept_items, f"expected an unresolved_concept item, got {items!r}"
+ assert all(item.source == str(library_file) for item in concept_items)
+
+ async def test_a_host_library_pipe_func_collision_names_no_host_module(self, tmp_path: Path) -> None:
+ host_library_dir = tmp_path / "host" / "library"
+ _write(path=host_library_dir / "board_formatting.py", content=_HOST_PIPE_FUNC_MODULE.format(flavor="board"))
+ _write(path=host_library_dir / "notice_formatting.py", content=_HOST_PIPE_FUNC_MODULE.format(flavor="notice"))
+
+ try:
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_contents=[_VALID_CALLER_BUNDLE], library_dirs=[host_library_dir])
+ finally:
+ if func_registry.has_function(_HOST_PIPE_FUNC_NAME):
+ func_registry.unregister_function_by_name(_HOST_PIPE_FUNC_NAME)
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert _HOST_PIPE_FUNC_NAME in item.message
+ assert item.message.count(HOST_LIBRARY_FILE_PLACEHOLDER) == 2
+ strict_payload = _strict_payload(raised.value)
+ _assert_names_no_host_path(payload=strict_payload, tmp_path=tmp_path)
+ # The module names are the host paths spelled with underscores.
+ assert "host_library_board_formatting" not in json.dumps(strict_payload)
+
+ @pytest.mark.parametrize("library_dirs_are_callers", [False, True], ids=["hosts_library", "callers_library"])
+ async def test_a_runtime_validates_content_against_the_library_it_is_told_is_whose(self, library_dirs_are_callers: bool, tmp_path: Path) -> None:
+ library_dir = tmp_path / "library"
+ library_file = _write(path=library_dir / "harbour_board.mthds", content=_MISSPELLED_CONCEPT_LIBRARY_BUNDLE)
+ runtime = PipelexMTHDSProtocol(
+ library_dirs=[str(library_dir)],
+ library_dirs_are_callers=library_dirs_are_callers,
+ pipe_run_mode=PipeRunMode.DRY,
+ execution_config=_execution_config(),
+ )
+
+ with pytest.raises(ValidateBundleError) as raised:
+ await runtime.validate([_VALID_CALLER_BUNDLE])
+
+ items = raised.value.to_error_report().validation_errors or []
+ concept_items = [item for item in items if item.error_type == PipeValidationErrorType.UNRESOLVED_CONCEPT]
+ assert concept_items, f"expected an unresolved_concept item, got {items!r}"
+ expected_source = str(library_file) if library_dirs_are_callers else None
+ assert all(item.source == expected_source for item in concept_items)
diff --git a/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_method_faults.py b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_method_faults.py
new file mode 100644
index 000000000..7f0c5f5a6
--- /dev/null
+++ b/tests/integration/pipelex/pipes/controller/pipe_condition/test_pipe_condition_method_faults.py
@@ -0,0 +1,149 @@
+"""Pin: the refusals a `PipeCondition` raises behind its bundle's load checks are the caller's faults too.
+
+A bundle's load refuses an outcome naming no pipe, an expression that does not parse and a chosen pipe's
+undeclared input before any condition runs, so a run of a loaded bundle does not reach these raise sites:
+the tests call the condition's run arms directly. Each refusal is classified as the caller's fault, keeps
+its message under STRICT disclosure with a next step, and quotes no text of the condition, which may be a
+host library's.
+"""
+
+from pathlib import Path
+from typing import Any, Callable
+
+import pytest
+
+from pipelex.base_exceptions import DisclosureMode
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.domains.domain import SpecialDomain
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.core.pipes.exceptions import PipeRunError
+from pipelex.pipe_controllers.condition.pipe_condition import PipeCondition
+from pipelex.pipe_controllers.condition.pipe_condition_blueprint import PipeConditionBlueprint
+from pipelex.pipe_machinery.pipe_factory import PipeFactory
+from pipelex.pipe_run.located_failure import find_root_fault
+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+_TEXT = f"{SpecialDomain.NATIVE}.{NativeConceptCode.TEXT}"
+_CONDITION_LIBRARY = Path("tests/integration/pipelex/pipes/controller/pipe_condition")
+
+
+def _make_condition(*, pipe_code: str, expression_template: str, outcomes: dict[str, str], default_outcome: str) -> PipeCondition:
+ blueprint = PipeConditionBlueprint(
+ description="A condition whose run arms the test calls directly",
+ inputs={"input_text": _TEXT},
+ output=_TEXT,
+ expression_template=expression_template,
+ outcomes=outcomes,
+ default_outcome=default_outcome,
+ )
+ return PipeFactory[PipeCondition].make_from_blueprint(domain_code="test_integration", pipe_code=pipe_code, blueprint=blueprint)
+
+
+def _strict_problem_document(error: PipeRunError) -> dict[str, Any]:
+ return error.to_error_report().to_problem_document(disclosure_mode=DisclosureMode.STRICT)
+
+
[email protected](loop_scope="class")
+class TestPipeConditionMethodFaults:
+ async def test_a_chosen_pipe_missing_its_inputs_is_the_callers_fault(
+ self, job_metadata: JobMetadata, load_test_library: Callable[[list[Path]], None]
+ ) -> None:
+ load_test_library([_CONDITION_LIBRARY])
+ pipe_condition = _make_condition(
+ pipe_code="length_gate",
+ expression_template="long",
+ outcomes={"long": "test_integration2.capitalize_long_text"},
+ default_outcome="test_integration2.add_prefix_short_text",
+ )
+
+ with pytest.raises(PipeRunError) as exc_info:
+ await pipe_condition._live_run_controller_pipe( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ job_metadata=job_metadata,
+ working_memory=WorkingMemoryFactory.make_empty(),
+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.LIVE),
+ )
+
+ document = _strict_problem_document(exc_info.value)
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert document["detail"] == (
+ "PipeCondition 'length_gate' chose pipe 'test_integration2.capitalize_long_text', whose required inputs are missing: input_text."
+ )
+ assert document["user_action"] == {
+ "kind": "change_input",
+ "detail": (
+ "Provide the missing required inputs of 'test_integration2.capitalize_long_text', which PipeCondition 'length_gate' chose: "
+ "input_text."
+ ),
+ }
+
+ async def test_an_expression_that_does_not_parse_names_its_line_only(
+ self, job_metadata: JobMetadata, load_test_library: Callable[[list[Path]], None]
+ ) -> None:
+ """The refusal names the line the expression fails at, never a token of it or of the parser's diagnosis."""
+ load_test_library([_CONDITION_LIBRARY])
+ pipe_condition = _make_condition(
+ pipe_code="parse_gate",
+ expression_template="{{ input_text.text }}",
+ outcomes={"long": "test_integration2.capitalize_long_text"},
+ default_outcome="test_integration2.add_prefix_short_text",
+ ).model_copy(update={"expression": "{{ input_text.text }}\n{% frobnicate_the_parcel %}"})
+
+ with pytest.raises(PipeRunError) as exc_info:
+ await pipe_condition._dry_run_controller_pipe( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ job_metadata=job_metadata,
+ working_memory=WorkingMemoryFactory.make_empty(),
+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY),
+ )
+
+ # The refusal is the root fault a run and a dry-run verdict report, not the parser error that quotes the expression.
+ assert find_root_fault(error=exc_info.value) is exc_info.value
+ document = _strict_problem_document(exc_info.value)
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert (
+ document["detail"] == "Dry run failed for pipe 'parse_gate' (PipeCondition): its expression does not parse at line 2 of that expression."
+ )
+ assert "frobnicate_the_parcel" not in document["detail"]
+ assert "input_text" not in document["detail"]
+ assert document["user_action"] == {
+ "kind": "change_input",
+ "detail": "Fix the expression of PipeCondition 'parse_gate' so that it parses as a Jinja2 expression.",
+ }
+
+ async def test_outcomes_naming_no_pipe_are_the_callers_fault(
+ self, job_metadata: JobMetadata, load_test_library: Callable[[list[Path]], None]
+ ) -> None:
+ """The refusal names the missing pipes, sorted, and no longer prints the outcome map."""
+ load_test_library([_CONDITION_LIBRARY])
+ pipe_condition = _make_condition(
+ pipe_code="route_gate",
+ expression_template="{{ input_text.text }}",
+ outcomes={"rush_lane": "test_integration.send_rush", "slow_lane": "test_integration.send_by_barge"},
+ default_outcome="test_integration.send_by_barge",
+ )
+
+ with pytest.raises(PipeRunError) as exc_info:
+ await pipe_condition._dry_run_controller_pipe( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ job_metadata=job_metadata,
+ working_memory=WorkingMemoryFactory.make_empty(),
+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=PipeRunMode.DRY),
+ )
+
+ document = _strict_problem_document(exc_info.value)
+ assert document["status"] == 422
+ assert document["error_domain"] == "input"
+ assert document["detail"] == (
+ "Dry run failed for PipeCondition 'route_gate': its outcomes name pipes that do not exist: "
+ "test_integration.send_by_barge, test_integration.send_rush."
+ )
+ assert "rush_lane" not in document["detail"]
+ assert document["user_action"] == {
+ "kind": "change_input",
+ "detail": (
+ "Declare the pipes test_integration.send_by_barge, test_integration.send_rush, "
+ "or change the outcomes of PipeCondition 'route_gate' to name existing pipes."
+ ),
+ }
diff --git a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_output_validation.py b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_output_validation.py
index c67aeff4d..9b1bb707f 100644
--- a/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_output_validation.py
+++ b/tests/integration/pipelex/pipes/controller/pipe_parallel/test_pipe_parallel_output_validation.py
@@ -3,13 +3,14 @@
The declared output must be `Composite` or a structured concept whose fields are compatible with
the branch result names (required fields ⊆ result names; result names ⊆ declared fields). This is
enforced at library validation time so `/validate` surfaces it as an author-time error instead of
-a runtime combine failure.
+a runtime combine failure, and a run refuses the bundle with the same verdict while loading it.
"""
import pytest
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.interpreter_hub import clear_current_library, get_library_manager
+from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.execution_seams import acquire_library
_BUNDLE_HEADER = """
@@ -174,8 +175,9 @@ class TestPipeParallelOutputValidation:
],
)
def test_rejected_outputs(self, test_id: str, mthds_content: str, expected_fragment: str):
- with pytest.raises(PipeValidationError) as exc_info:
+ with pytest.raises(ValidateBundleError) as exc_info:
acquire_library(library_id=f"pv_reject_{test_id}", mthds_contents=[mthds_content])
+ assert isinstance(exc_info.value.__cause__, PipeValidationError)
assert expected_fragment in str(exc_info.value)
def test_a_one_count_plural_branch_is_type_checked(self):
@@ -185,6 +187,7 @@ class TestPipeParallelOutputValidation:
declaration alone let an incompatible singular result pass `/validate` and fail later in
`StuffFactory.combine_stuffs`.
"""
- with pytest.raises(PipeValidationError) as exc_info:
+ with pytest.raises(ValidateBundleError) as exc_info:
acquire_library(library_id="pv_reject_one_count_plural_branch", mthds_contents=[_BUNDLE_HEADER + _ONE_COUNT_PLURAL_BRANCH])
+ assert isinstance(exc_info.value.__cause__, PipeValidationError)
assert "tone_result" in str(exc_info.value)
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
index a28f9908a..f10800d69 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_native_scalar_conversions.py
@@ -33,6 +33,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.compose.exceptions import PipeComposeError
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
+from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata
@@ -280,5 +281,8 @@ class TestPipeComposeNativeScalarConversions:
pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=pipe_run_mode),
)
- with pytest.raises(PipeComposeError, match="time of day"):
+ # The router locates the failure at the pipe that raised it, chained to the failure.
+ with pytest.raises(PipeRouterError) as exc_info:
await get_pipe_router().run(pipe_job=pipe_job)
+ assert isinstance(exc_info.value.__cause__, PipeComposeError)
+ assert "time of day" in exc_info.value.__cause__.message
diff --git a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured_compatibility.py b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured_compatibility.py
index 68c7d8972..4d4d5f2b1 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured_compatibility.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_compose_structured/test_pipe_compose_structured_compatibility.py
@@ -22,6 +22,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.compose.exceptions import PipeComposeError
from pipelex.pipe_operators.compose.pipe_compose import PipeCompose
from pipelex.pipe_operators.compose.pipe_compose_blueprint import PipeComposeBlueprint
+from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata
@@ -319,5 +320,8 @@ class TestPipeComposeStructuredCompatibility:
)
# The composition should fail because Location cannot be converted to Person
- with pytest.raises(PipeComposeError, match="Cannot convert"):
+ # The router locates the failure at the pipe that raised it, chained to the failure.
+ with pytest.raises(PipeRouterError) as exc_info:
await get_pipe_router().run(pipe_job=pipe_job)
+ assert isinstance(exc_info.value.__cause__, PipeComposeError)
+ assert "Cannot convert" in exc_info.value.__cause__.message
diff --git a/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract_model_not_found_reroute.py b/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract_model_not_found_reroute.py
index b54725cc7..0da2ed847 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract_model_not_found_reroute.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_extract/test_pipe_extract_model_not_found_reroute.py
@@ -15,6 +15,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_operators.extract.pipe_extract import PipeExtract
from pipelex.pipe_operators.extract.pipe_extract_blueprint import PipeExtractBlueprint
+from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata
@@ -69,10 +70,13 @@ class TestPipeExtractModelNotFoundReroute:
),
)
- with pytest.raises(PipeOperatorModelAvailabilityError) as exc_info:
+ # The router locates the failure at the pipe that raised it, chained to the availability error.
+ with pytest.raises(PipeRouterError) as exc_info:
await get_pipe_router().run(pipe_job=pipe_job)
+ assert exc_info.value.pipe_code == pipe.code
- availability_error = exc_info.value
+ availability_error = exc_info.value.__cause__
+ assert isinstance(availability_error, PipeOperatorModelAvailabilityError)
assert availability_error.model_handle == "extract-not-a-real-model"
assert availability_error.fallback_list is None
assert availability_error.pipe_type == "PipeExtract"
diff --git a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_model_not_found_reroute.py b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_model_not_found_reroute.py
index 5bd731431..348293463 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_model_not_found_reroute.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_model_not_found_reroute.py
@@ -11,6 +11,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_operators.img_gen.pipe_img_gen import PipeImgGen
from pipelex.pipe_operators.img_gen.pipe_img_gen_blueprint import PipeImgGenBlueprint
+from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata
@@ -58,10 +59,13 @@ class TestPipeImgGenModelNotFoundReroute:
job_metadata=job_metadata,
)
- with pytest.raises(PipeOperatorModelAvailabilityError) as exc_info:
+ # The router locates the failure at the pipe that raised it, chained to the availability error.
+ with pytest.raises(PipeRouterError) as exc_info:
await get_pipe_router().run(pipe_job=pipe_job)
+ assert exc_info.value.pipe_code == pipe.code
- availability_error = exc_info.value
+ availability_error = exc_info.value.__cause__
+ assert isinstance(availability_error, PipeOperatorModelAvailabilityError)
assert availability_error.model_handle == "sd-not-a-real-model"
assert availability_error.fallback_list is None
assert availability_error.pipe_type == "PipeImgGen"
diff --git a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_run.py b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_run.py
index 8b29271bd..f7501d8ec 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_run.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_run.py
@@ -11,7 +11,7 @@ from pipelex.interpreter_hub import get_pipe_router
from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.img_gen.pipe_img_gen import PipeImgGen
from pipelex.pipe_operators.img_gen.pipe_img_gen_blueprint import PipeImgGenBlueprint
-from pipelex.pipe_run.exceptions import PipeRunParamsError
+from pipelex.pipe_run.exceptions import PipeRouterError, PipeRunParamsError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata
@@ -152,7 +152,10 @@ class TestPipeImgGenRun:
pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=pipe_run_mode),
job_metadata=job_metadata,
)
- with pytest.raises(PipeRunParamsError, match="Cannot guess how many images"):
+ # The router locates the failure at the pipe that raised it, chained to the failure.
+ with pytest.raises(PipeRouterError) as exc_info:
await get_pipe_router().run(
pipe_job=pipe_job,
)
+ assert isinstance(exc_info.value.__cause__, PipeRunParamsError)
+ assert "Cannot guess how many images" in exc_info.value.__cause__.message
diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_model_not_found_reroute.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_model_not_found_reroute.py
index 5222775cd..00ba847f9 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_model_not_found_reroute.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_model_not_found_reroute.py
@@ -12,6 +12,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
+from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata
@@ -28,7 +29,8 @@ class TestPipeLLMModelNotFoundReroute:
) -> None:
"""A provider 404 raised as LLMModelNotFoundError from the content generator escapes PipeLLM's
`except LLMCompletionError`, reaches `except ModelNotFoundError` in PipeOperator._live_run_pipe,
- and surfaces from the router as PipeOperatorModelAvailabilityError carrying the model_handle.
+ and surfaces from the router as a PipeRouterError located at the pipe, chained to the
+ PipeOperatorModelAvailabilityError carrying the model_handle.
"""
load_test_library([Path("tests/integration/pipelex/pipes/operator/pipe_llm")])
@@ -59,10 +61,13 @@ class TestPipeLLMModelNotFoundReroute:
job_metadata=job_metadata,
)
- with pytest.raises(PipeOperatorModelAvailabilityError) as exc_info:
+ # The router locates the failure at the pipe that raised it, chained to the availability error.
+ with pytest.raises(PipeRouterError) as exc_info:
await get_pipe_router().run(pipe_job=pipe_job)
+ assert exc_info.value.pipe_code == pipe.code
- availability_error = exc_info.value
+ availability_error = exc_info.value.__cause__
+ assert isinstance(availability_error, PipeOperatorModelAvailabilityError)
assert availability_error.model_handle == "gpt-not-a-real-model"
assert availability_error.fallback_list is None
assert availability_error.pipe_type == "PipeLLM"
diff --git a/tests/integration/pipelex/pipes/operator/pipe_search/test_pipe_search_model_not_found_reroute.py b/tests/integration/pipelex/pipes/operator/pipe_search/test_pipe_search_model_not_found_reroute.py
index aaa950cbd..a25c50ece 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_search/test_pipe_search_model_not_found_reroute.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_search/test_pipe_search_model_not_found_reroute.py
@@ -11,6 +11,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
from pipelex.pipe_operators.search.pipe_search import PipeSearch
from pipelex.pipe_operators.search.pipe_search_blueprint import PipeSearchBlueprint
+from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata
@@ -61,10 +62,13 @@ class TestPipeSearchModelNotFoundReroute:
job_metadata=job_metadata,
)
- with pytest.raises(PipeOperatorModelAvailabilityError) as exc_info:
+ # The router locates the failure at the pipe that raised it, chained to the availability error.
+ with pytest.raises(PipeRouterError) as exc_info:
await get_pipe_router().run(pipe_job=pipe_job)
+ assert exc_info.value.pipe_code == pipe.code
- availability_error = exc_info.value
+ availability_error = exc_info.value.__cause__
+ assert isinstance(availability_error, PipeOperatorModelAvailabilityError)
assert availability_error.model_handle == "search-not-a-real-model"
assert availability_error.fallback_list is None
assert availability_error.pipe_type == "PipeSearch"
diff --git a/tests/integration/pipelex/pipes/test_pipe_running_variants.py b/tests/integration/pipelex/pipes/test_pipe_running_variants.py
index 0f7d2bf33..1f30bb7da 100644
--- a/tests/integration/pipelex/pipes/test_pipe_running_variants.py
+++ b/tests/integration/pipelex/pipes/test_pipe_running_variants.py
@@ -8,6 +8,7 @@ from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity
from pipelex.core.stuffs.stuff import Stuff
from pipelex.interpreter_hub import get_pipe_router, get_required_entry_pipe
+from pipelex.pipe_run.located_failure import find_root_fault
from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.pipeline.exceptions import PipeStackOverflowError
@@ -110,7 +111,8 @@ class TestPipeRunningVariants:
):
load_test_library([Path("tests/integration/pipelex/pipes/pipelines")])
log.verbose(f"This pipe '{pipe_code}' is supposed to cause an error of type: {exception.__name__}")
- with pytest.raises(PipeStackOverflowError) as exc:
+ # The router locates the overflow at the pipe whose frame did not fit, chained to it.
+ with pytest.raises(exception) as exc:
await get_pipe_router().run(
pipe_job=PipeJobFactory.make_pipe_job(
pipe=get_required_entry_pipe(pipe_code=pipe_code),
@@ -122,4 +124,5 @@ class TestPipeRunningVariants:
),
)
pretty_print(exc.value, title="exception")
+ assert isinstance(find_root_fault(error=exc.value), PipeStackOverflowError)
assert expected_error_message in str(exc.value)
diff --git a/tests/integration/pipelex/test_data.py b/tests/integration/pipelex/test_data.py
index 08fe32e29..7bfef6520 100644
--- a/tests/integration/pipelex/test_data.py
+++ b/tests/integration/pipelex/test_data.py
@@ -413,3 +413,137 @@ Extract information from the following text:
("Nested unions complex", NESTED_UNIONS_COMPLEX, "ConceptWithNestedUnions"),
("Nested unions mixed", NESTED_UNIONS_MIXED, "ConceptWithNestedUnions"),
]
+
+
+class ValidationDetailBundles:
+ """Bundles whose validation used to lose detail before the verdict reached the reader."""
+
+ DOMAIN = "idea_board"
+ SOURCE = "idea_board.mthds"
+
+ # A misspelled field (`promtp`, which no categorizer knows) in one pipe, an undeclared prompt variable
+ # (`$language`) in another: two errors, each its own item.
+ TYPO_BESIDE_UNDECLARED_VARIABLE = """
+domain = "idea_board"
+description = "Summarize and translate the notes pinned on the idea board"
+main_pipe = "summarize_notes"
+
+[pipe.summarize_notes]
+type = "PipeLLM"
+description = "Summarize the notes pinned on the board"
+inputs = { notes = "Text" }
+output = "Text"
+promtp = "Summarize these notes"
+prompt = "Summarize these notes for the weekly meeting: $notes"
+
+[pipe.translate_notes]
+type = "PipeLLM"
+description = "Translate the notes for the visiting team"
+inputs = { notes = "Text" }
+output = "Text"
+prompt = "Translate these notes into $language: $notes"
+"""
+
+ # The parallel `analyze_topic` combines a plural branch (`Idea[]`) into the single field `ideas` of
+ # `IdeaReport`, so its dry run fails at the combine. The sequence `run_workshop` runs it as its second
+ # step, so its own dry run fails for the same cause.
+ NESTED_PARALLEL_MISMATCH = """
+domain = "idea_board"
+description = "Run a small ideation workshop on a topic"
+main_pipe = "run_workshop"
+
+[concept]
+Idea = "One idea proposed during the workshop"
+IdeaSummary = "A short summary of the workshop's direction"
+
+[concept.IdeaReport]
+description = "The workshop's report: its ideas and its summary"
+
+[concept.IdeaReport.structure]
+ideas = { type = "concept", concept_ref = "Idea", description = "The ideas", required = true }
+summary = { type = "concept", concept_ref = "IdeaSummary", description = "The summary", required = true }
+
+[pipe.run_workshop]
+type = "PipeSequence"
+description = "Frame the topic, then analyze it"
+inputs = { topic = "Text" }
+output = "IdeaReport"
+steps = [
+ { pipe = "frame_topic", result = "framed_topic" },
+ { pipe = "analyze_topic", result = "report" },
+]
+
+[pipe.frame_topic]
+type = "PipeLLM"
+description = "Restate the topic as a question for the workshop"
+inputs = { topic = "Text" }
+output = "Text"
+prompt = "Restate this topic as one open question: $topic"
+
+[pipe.propose_ideas]
+type = "PipeLLM"
+description = "Propose ideas on the framed topic"
+inputs = { framed_topic = "Text" }
+output = "Idea[]"
+prompt = "Propose ideas answering: $framed_topic"
+
+[pipe.summarize_direction]
+type = "PipeLLM"
+description = "Summarize the direction the ideas take"
+inputs = { framed_topic = "Text" }
+output = "IdeaSummary"
+prompt = "Summarize the direction a workshop on this question should take: $framed_topic"
+
+[pipe.analyze_topic]
+type = "PipeParallel"
+description = "Propose ideas and summarize the direction at once"
+inputs = { framed_topic = "Text" }
+output = "IdeaReport"
+branches = [
+ { pipe = "propose_ideas", result = "ideas" },
+ { pipe = "summarize_direction", result = "summary" },
+]
+"""
+
+ # The string opened on line 2 is never closed: the parser stops at the line's end, column 38.
+ TOML_SYNTAX_ERROR = """domain = "idea_board"
+description = "An unterminated string
+"""
+
+ # `IdeaRanking` is declared nowhere, while the domain declares `Idea` and `IdeaSummary`.
+ UNRESOLVED_CONCEPT = """
+domain = "idea_board"
+description = "Rank the ideas pinned on the board"
+
+[concept]
+Idea = "One idea pinned on the board"
+IdeaSummary = "A short summary of the board"
+
+[pipe.rank_ideas]
+type = "PipeLLM"
+description = "Rank the ideas pinned on the board"
+inputs = { notes = "Text" }
+output = "IdeaRanking"
+prompt = "Rank the ideas in these notes: $notes"
+"""
+
+ # What a dry-run item must never carry again: the sweep's internal record, dumped as a Python repr.
+ RECORD_REPR_MARKERS: ClassVar[tuple[str, ...]] = ("pipe_ref=", "status=", "DryRunStatus", "error_message=")
+
+ # A caller's bundle whose sequence runs the failing parallel from a library directory the host loads.
+ # ``NESTED_PARALLEL_MISMATCH`` stands in for that library: its ``analyze_topic`` fails its dry run.
+ CALLER_OF_LIBRARY_PARALLEL = """
+domain = "workshop"
+description = "A caller's bundle that runs the library's analysis"
+main_pipe = "run_library_analysis"
+
+[pipe.run_library_analysis]
+type = "PipeSequence"
+description = "Analyze the framed topic with the library's pipe"
+inputs = { framed_topic = "Text" }
+output = "idea_board.IdeaReport"
+steps = [
+ { pipe = "idea_board.analyze_topic", result = "report" },
+]
+"""
+ CALLER_SOURCE = "api://bundle-0.mthds"
diff --git a/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py b/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
index 58e932311..74a477e4b 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
@@ -46,6 +46,25 @@ def _fixable_item(*, source: Path) -> ValidationErrorItem:
)
+def _unsafe_fixable_item(*, source: Path) -> ValidationErrorItem:
+ return ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_VALIDATION,
+ error_type=PipeValidationErrorType.UNKNOWN_MODEL,
+ pipe_code="write_tide_note",
+ domain_code="tide_tables",
+ source=str(source),
+ field_name="model",
+ message="Pipe 'write_tide_note' (PipeLLM), field 'model': Alias 'best-sonet' was not found in the model deck",
+ suggested_fix=SuggestedFix(
+ fix_code="rename-model",
+ description="Replace model '@best-sonet' of pipe 'write_tide_note' with '@best-gpt', its one close match in the model deck",
+ safety=FixSafety.UNSAFE,
+ source=str(source),
+ ops=[],
+ ),
+ )
+
+
class TestValidateBundleErrorFormat:
@pytest.fixture(autouse=True)
def _reset_error_format(self) -> Iterator[None]:
@@ -72,6 +91,23 @@ class TestValidateBundleErrorFormat:
assert "Check the validation_errors array" not in markdown
assert f"💡 1 of these errors can be fixed automatically — run: `pipelex-agent fix bundle {bundle_path} -L {tmp_path / 'libs'}`" in markdown
+ def test_markdown_says_an_unsafe_fix_needs_confirmation(self, tmp_path: Path) -> None:
+ """A safe fix keeps the plain 💡 line; an unsafe one says it is unsafe, and the footer counts only the safe one."""
+ bundle_path = tmp_path / "bundle.mthds"
+ markdown = _render_validate_bundle_markdown(
+ [_fixable_item(source=bundle_path), _unsafe_fixable_item(source=bundle_path)],
+ bundle_path=bundle_path,
+ library_dirs=None,
+ allow_signatures=False,
+ )
+
+ assert " - 💡 Suggested fix: Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step" in markdown
+ assert (
+ " - 💡 Suggested fix (unsafe, confirm before applying): Replace model '@best-sonet' of pipe 'write_tide_note' with '@best-gpt'"
+ ) in markdown
+ assert "💡 Suggested fix: Replace model" not in markdown
+ assert "💡 1 of these errors can be fixed automatically" in markdown
+
def test_markdown_no_fix_footer_when_nothing_fixable(self, tmp_path: Path) -> None:
"""With no suggested fix, the footer points at the messages instead of naming a fix command."""
item = ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="something is wrong")
@@ -111,6 +147,9 @@ class TestValidateBundleErrorFormat:
assert parsed["error_type"] == "ValidateBundleError"
assert parsed["is_valid"] is False
assert parsed["bundle_path"] == str(bundle_path)
- # The message-only residual makes the structured-info invariant total; the hint stays the JSON boilerplate.
+ # The message-only residual makes the structured-info invariant total; the hint is the class-level next step.
assert parsed["validation_errors"] == [{"category": "blueprint_validation", "message": "no details"}]
- assert parsed["hint"] == "Check the validation_errors array for specific issues"
+ assert (
+ parsed["hint"]
+ == "Edit the bundle as each validation error says: apply its suggested fix where it has one, after confirming an unsafe one"
+ )
diff --git a/tests/unit/pipelex/cli/commands/fix/test_diff_sandbox.py b/tests/unit/pipelex/cli/commands/fix/test_diff_sandbox.py
index 4495976a4..636b24189 100644
--- a/tests/unit/pipelex/cli/commands/fix/test_diff_sandbox.py
+++ b/tests/unit/pipelex/cli/commands/fix/test_diff_sandbox.py
@@ -130,6 +130,16 @@ class TestDiffSandbox:
assert sandbox.to_original(str(ambient_file)) == str(ambient_file.resolve())
+ def test_a_dependency_bundle_named_by_its_address_passes_through_as_given(self, tmp_path: Path) -> None:
+ """A name that is not a path, like a dependency's bundle named by its package's address, is never resolved into a file."""
+ entry = tmp_path / "bundle.mthds"
+ entry.write_text('domain = "demo"\n', encoding="utf-8")
+ dependency_bundle = "github.com/acme/harbour-methods/tides/notices/tide_notices.mthds"
+
+ sandbox = mirror_bundle_for_preview(entry, library_dirs=None, sandbox_root=self._sandbox_root(tmp_path))
+
+ assert sandbox.to_original(dependency_bundle) == dependency_bundle
+
def test_copy_uses_loader_exclusions(self, tmp_path: Path) -> None:
bundle_dir = tmp_path / "bundle"
bundle_dir.mkdir()
diff --git a/tests/unit/pipelex/cli/test_agent_output.py b/tests/unit/pipelex/cli/test_agent_output.py
index e7799afb1..863f5135e 100644
--- a/tests/unit/pipelex/cli/test_agent_output.py
+++ b/tests/unit/pipelex/cli/test_agent_output.py
@@ -23,6 +23,7 @@ from pipelex.cli.agent_cli.commands.agent_output import (
consume_setup_warnings,
extract_validation_errors,
record_setup_warning,
+ run_failure_fields,
set_agent_cli_error_format,
)
from pipelex.cogt.exceptions import (
@@ -34,7 +35,9 @@ from pipelex.cogt.exceptions import (
)
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipe_run.exceptions import PipeRouterError
+from pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleError
+from pipelex.system.pipe_run_mode import PipeRunMode
if TYPE_CHECKING:
from collections.abc import Iterator
@@ -187,6 +190,25 @@ class TestAgentOutput:
assert parsed["error"] is True
assert parsed["failed_at"] == "2026-02-09T14:00:00"
+ def test_run_failure_fields_name_the_location_and_the_root_fault(self) -> None:
+ """A failed run's fields carry the failing pipe, its path, and the root fault's identity and own message."""
+ root_fault = CogtError(message="rate limited", error_category=InferenceErrorCategory.TRANSIENT)
+ located = PipeRouterError.make_located(
+ failure=root_fault, run_mode=PipeRunMode.LIVE, pipe_code="summarize", output_name=None, pipe_stack=["two_steps", "summarize"]
+ )
+ located.__cause__ = root_fault
+ run_failure = PipelineExecutionError.make_for_run_failure(
+ failure=located, run_mode=PipeRunMode.LIVE, entry_pipe_code="two_steps", output_name=None
+ )
+ run_failure.__cause__ = located
+
+ assert run_failure_fields(error=run_failure) == {
+ "pipe_code": "summarize",
+ "pipe_stack": ["two_steps", "summarize"],
+ "cause_type": "CogtError",
+ "cause_message": "rate limited",
+ }
+
def test_extract_validation_errors_message_only(self) -> None:
"""A message-only error yields one ``blueprint_validation`` residual — the structured-info invariant is total.
@@ -369,7 +391,7 @@ class TestAgentOutput:
"""
# An error_type in AGENT_ERROR_DOMAINS that is NOT a CogtError subclass, so no derived
# domain can pre-empt the lookup.
- error_type = "PipeOperatorModelChoiceError"
+ error_type = "PipeOperatorModelAvailabilityError"
assert error_type in AGENT_ERROR_DOMAINS, "precondition: error_type must be in AGENT_ERROR_DOMAINS"
cause = CogtError("model not found", error_category=InferenceErrorCategory.UNKNOWN)
diff --git a/tests/unit/pipelex/cli/test_error_handlers.py b/tests/unit/pipelex/cli/test_error_handlers.py
index b70fd9bd2..b054aeb45 100644
--- a/tests/unit/pipelex/cli/test_error_handlers.py
+++ b/tests/unit/pipelex/cli/test_error_handlers.py
@@ -37,6 +37,8 @@ class TestErrorHandlers:
message="model 'gpt-5' not found",
pipe_type="llm_text",
pipe_code="my_pipe",
+ domain_code="my_domain",
+ field_name="model",
model_type=ModelType.LLM,
model_choice="gpt-5",
)
diff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.py
index 0f467c3b0..700ceae3e 100644
--- a/tests/unit/pipelex/cli/test_error_handlers_more.py
+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py
@@ -31,7 +31,7 @@ from pipelex.cli.error_handlers import (
from pipelex.cogt.exceptions import GatewayUnknownModelError, ModelDeckPresetValidatonError
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
+from pipelex.core.exceptions import DryRunFailureErrorData, PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
from pipelex.core.validation import MIGRATE_COMMAND
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.system.pipelex_service.exceptions import (
@@ -168,7 +168,14 @@ class TestErrorHandlersExtended:
message="validation failed",
pipelex_bundle_blueprint_validation_errors=[blueprint_error],
pipe_validation_errors=[pipe_error],
- dry_run_error_message="dry run exploded",
+ dry_run_failures=[
+ DryRunFailureErrorData(
+ pipe_code="third_pipe",
+ domain_code="demo",
+ source="bundle.mthds",
+ message="Pipe 'third_pipe' failed its dry run: dry run exploded",
+ )
+ ],
)
with pytest.raises(typer.Exit) as exc_info:
@@ -186,8 +193,10 @@ class TestErrorHandlersExtended:
assert "Inadequate Output Concept" in output
assert "Field: output" in output
assert "└─ Path: pipes.other_pipe.output" in output
- assert "Dry Run Error:" in output
- assert "dry run exploded" in output
+ assert "Dry Run Errors:" in output
+ assert "1. Dry Run Error" in output
+ assert "Pipe: third_pipe" in output
+ assert "Pipe 'third_pipe' failed its dry run: dry run exploded" in output
def test_handle_validate_bundle_error_minimal_renders_fallback_residual(self, console: Console) -> None:
"""A message-only error renders the fallback residual item, so the message is never lost.
diff --git a/tests/unit/pipelex/cli/test_error_handlers_snapshot.py b/tests/unit/pipelex/cli/test_error_handlers_snapshot.py
index 2e01f4682..cdc239b32 100644
--- a/tests/unit/pipelex/cli/test_error_handlers_snapshot.py
+++ b/tests/unit/pipelex/cli/test_error_handlers_snapshot.py
@@ -51,8 +51,17 @@ EXPECTED_MODEL_AVAILABILITY_PANEL = (
"\n"
"Error: model not available\n"
"\n"
- "💡 Tip: Check your model configuration in .pipelex/inference/ or specify a \n"
- "different model in the 'my_pipe' pipe.\n"
+ "💡 Tip: Your local model deck may be out of date: new aliases and presets are \n"
+ "added to Pipelex over time, and existing '.pipelex/inference/deck/*.toml' files \n"
+ "are not refreshed automatically. To pick up the latest definitions, delete your \n"
+ "local deck files under '.pipelex/inference/deck/' (or the whole \n"
+ "'.pipelex/inference/' directory) and run 'pipelex init inference' to regenerate \n"
+ "them.\n"
+ "If that does not resolve it, make sure the handle is defined in one of \n"
+ "'.pipelex/inference/deck/*.toml', that the backend it routes to (see \n"
+ "'.pipelex/inference/routing_profiles.toml') is enabled in \n"
+ "'.pipelex/inference/backends.toml', and that you have the necessary credentials,\n"
+ "or specify a different model in the 'my_pipe' pipe.\n"
"Learn more about the inference backend system: \n"
"https://docs.pipelex.com/latest/setup/configure-ai-providers/\n"
"Join our Discord for help: https://go.pipelex.com/discord\n"
@@ -78,6 +87,8 @@ class TestErrorHandlersSnapshot:
message="model 'gpt-5' not found",
pipe_type="llm_text",
pipe_code="my_pipe",
+ domain_code="my_domain",
+ field_name="model",
model_type=ModelType.LLM,
model_choice="gpt-5",
)
diff --git a/tests/unit/pipelex/cli/test_run_core_wrapper.py b/tests/unit/pipelex/cli/test_run_core_wrapper.py
index 4877b5856..e659649ba 100644
--- a/tests/unit/pipelex/cli/test_run_core_wrapper.py
+++ b/tests/unit/pipelex/cli/test_run_core_wrapper.py
@@ -95,6 +95,8 @@ class TestExecuteRunWrapper:
message="model 'gpt-5' not found",
pipe_type="llm_text",
pipe_code="test_pipe",
+ domain_code="my_domain",
+ field_name="model",
model_type=ModelType.LLM,
model_choice="gpt-5",
)
diff --git a/tests/unit/pipelex/cli/test_validate_exit_codes.py b/tests/unit/pipelex/cli/test_validate_exit_codes.py
index f123dc1c5..2bfe9d837 100644
--- a/tests/unit/pipelex/cli/test_validate_exit_codes.py
+++ b/tests/unit/pipelex/cli/test_validate_exit_codes.py
@@ -24,8 +24,8 @@ from pipelex.cli.agent_cli.commands.validate.bundle_cmd import validate_bundle_c
from pipelex.cli.agent_cli.commands.validate.pipe_cmd import validate_pipe_cmd as agent_validate_pipe_cmd
from pipelex.cli.commands.validate.bundle_cmd import validate_bundle_cmd as bare_validate_bundle_cmd
from pipelex.cli.commands.validate.pipe_cmd import validate_pipe_cmd as bare_validate_pipe_cmd
+from pipelex.core.exceptions import DryRunFailureErrorData
from pipelex.libraries.pipe.exceptions import PipeLibraryError
-from pipelex.pipe_run.exceptions import DryRunError
from pipelex.pipeline.exceptions import ValidateBundleError
if TYPE_CHECKING:
@@ -35,6 +35,16 @@ if TYPE_CHECKING:
AGENT_BUNDLE_MODULE = "pipelex.cli.agent_cli.commands.validate.bundle_cmd"
AGENT_PIPE_MODULE = "pipelex.cli.agent_cli.commands.validate.pipe_cmd"
+
+
+def _make_dry_run_verdict() -> ValidateBundleError:
+ """The verdict the cascade makes of a failing dry run: one located dry_run item for the failing pipe."""
+ return ValidateBundleError(
+ "pipe dry-run failed",
+ dry_run_failures=[DryRunFailureErrorData(pipe_code="my_pipe", domain_code="test", message="Pipe 'my_pipe' failed its dry run: Pipe run")],
+ )
+
+
BARE_VALIDATE_CORE = "pipelex.cli.commands.validate._validate_core"
@@ -156,7 +166,9 @@ class TestValidateExitCodes:
self._patch_boot(mocker)
mocker.patch(
f"{AGENT_BUNDLE_MODULE}.validate_bundle_core",
- new=mocker.AsyncMock(side_effect=ValidateBundleError("Bundle is invalid", dry_run_error_message="boom")),
+ new=mocker.AsyncMock(
+ side_effect=ValidateBundleError("Bundle is invalid", dry_run_failures=[DryRunFailureErrorData(pipe_code="my_pipe", message="boom")])
+ ),
)
with pytest.raises(typer.Exit) as exc_info:
agent_validate_bundle_cmd(path=str(self._bundle_file(tmp_path)), output_format=CliOutputFormat.JSON)
@@ -223,20 +235,20 @@ class TestValidateExitCodes:
mocker.patch(f"{AGENT_PIPE_MODULE}.Pipelex.teardown_if_needed")
def test_agent_validate_all_dry_run_failure_is_negative_verdict_exit_1(self, mocker: MockerFixture) -> None:
- # `validate --all` sweeps via validate_all_core → validate_current_library, which raises
- # DryRunError directly. A dry-run failure is a produced negative verdict → exit 1, NOT the
+ # `validate --all` sweeps through the bundle-loading cascade, which turns the sweep's DryRunError
+ # into the invalid verdict (one located dry_run item per failing pipe) → exit 1, NOT the
# catch-all's no-verdict 2.
self._patch_pipe_boot(mocker)
- mocker.patch(f"{AGENT_PIPE_MODULE}.validate_all_core", new=mocker.AsyncMock(side_effect=DryRunError("pipe dry-run failed")))
+ mocker.patch(f"{AGENT_PIPE_MODULE}.validate_all_core", new=mocker.AsyncMock(side_effect=_make_dry_run_verdict()))
with pytest.raises(typer.Exit) as exc_info:
agent_validate_pipe_cmd(pipe_code=None, validate_all=True, output_format=CliOutputFormat.JSON)
assert exc_info.value.exit_code == 1
def test_agent_validate_pipe_dry_run_failure_is_negative_verdict_exit_1(self, mocker: MockerFixture) -> None:
- # Single-pipe validate_pipe_core sweeps via validate_pipes, which raises DryRunError directly.
+ # Single-pipe validate_pipe_core sweeps through the same cascade.
self._patch_pipe_boot(mocker)
mocker.patch(f"{AGENT_PIPE_MODULE}.resolve_pipe_from_exports", new=mocker.Mock(return_value=[]))
- mocker.patch(f"{AGENT_PIPE_MODULE}.validate_pipe_core", new=mocker.AsyncMock(side_effect=DryRunError("pipe dry-run failed")))
+ mocker.patch(f"{AGENT_PIPE_MODULE}.validate_pipe_core", new=mocker.AsyncMock(side_effect=_make_dry_run_verdict()))
with pytest.raises(typer.Exit) as exc_info:
agent_validate_pipe_cmd(pipe_code="my_pipe", output_format=CliOutputFormat.JSON)
assert exc_info.value.exit_code == 1
diff --git a/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py
index 173886e2d..4246d63e9 100644
--- a/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py
+++ b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py
@@ -17,7 +17,7 @@ import typer
from rich.console import Console
from pipelex.cli.error_handlers import handle_validate_bundle_error
-from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData
+from pipelex.core.exceptions import DryRunFailureErrorData, PipeFactoryErrorData, PipesAndConceptValidationErrorData
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.validation_error_types import PipeFactoryErrorType, PipeValidationErrorType
@@ -38,6 +38,21 @@ def _fixable_pipe_error(*, source: str | None = None) -> PipesAndConceptValidati
)
+def _unsafe_fixable_pipe_error() -> PipesAndConceptValidationErrorData:
+ """An ``unknown_model`` with one close match — the planner derives the UNSAFE ``rename-model`` from it."""
+ return PipesAndConceptValidationErrorData(
+ error_type=PipeValidationErrorType.UNKNOWN_MODEL,
+ domain_code="tide_tables",
+ pipe_code="write_tide_note",
+ field_name="model",
+ message="Alias 'best-sonet' was not found in the model deck",
+ field_path="pipe.write_tide_note.model",
+ model_reference="@best-sonet",
+ model_type="llm",
+ suggestions=["@best-gpt"],
+ )
+
+
def _non_fixable_pipe_error() -> PipesAndConceptValidationErrorData:
"""The same error type without the enrichment — structurally suppressed by the planner."""
return PipesAndConceptValidationErrorData(
@@ -141,6 +156,37 @@ class TestValidateSuggestedFixRendering:
assert "can be fixed automatically" not in output
assert "💡 Tip:" in output
+ def test_unsafe_fix_says_it_needs_confirmation_and_is_not_counted(self, console: Console) -> None:
+ """A safe fix keeps the plain line; an unsafe one says so, and the automatic-fix footer counts only the safe one."""
+ exc = ValidateBundleError(
+ message="validation failed",
+ pipe_validation_errors=[_fixable_pipe_error(), _unsafe_fixable_pipe_error()],
+ )
+
+ with pytest.raises(typer.Exit):
+ handle_validate_bundle_error(exc, bundle_path=Path("methods/demo.mthds"))
+
+ output = console.export_text()
+ assert "💡 Suggested fix: Set output of pipe 'list_ideas' to 'Idea[]' to match its last step" in output
+ assert (
+ "💡 Suggested fix (unsafe, confirm before applying): Replace model '@best-sonet' of pipe 'write_tide_note' with '@best-gpt'"
+ ) in output
+ assert "💡 Suggested fix: Replace model" not in output
+ assert "1 of these errors can be fixed automatically" in output
+
+ def test_only_unsafe_fix_keeps_generic_tip(self, console: Console) -> None:
+ """An unsafe fix is never applied by `pipelex fix bundle`, so it alone offers no fix command."""
+ exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_unsafe_fixable_pipe_error()])
+
+ with pytest.raises(typer.Exit):
+ handle_validate_bundle_error(exc, bundle_path=Path("methods/demo.mthds"))
+
+ output = console.export_text()
+ assert "💡 Suggested fix (unsafe, confirm before applying): Replace model '@best-sonet'" in output
+ assert "can be fixed automatically" not in output
+ assert "pipelex fix bundle" not in output
+ assert "💡 Tip:" in output
+
def test_fixable_count_sums_only_fixable_items(self, console: Console) -> None:
exc = ValidateBundleError(
message="validation failed",
@@ -175,17 +221,20 @@ class TestValidateSuggestedFixRendering:
assert "concept 'MissingConcept' is not declared in domain 'demo'" in output
assert "Declared Concepts: Idea, Report" in output
- def test_dry_run_message_stays_visible_alongside_categorized_errors(self, console: Console) -> None:
- """The wire builder suppresses the dry-run residual when categorized errors exist; the human surface keeps it."""
+ def test_dry_run_items_stay_visible_alongside_categorized_errors(self, console: Console) -> None:
+ """A dry-run item renders beside the categorized errors, located on its pipe."""
exc = ValidateBundleError(
message="validation failed",
pipe_validation_errors=[_non_fixable_pipe_error()],
- dry_run_error_message="dry run exploded",
+ dry_run_failures=[
+ DryRunFailureErrorData(pipe_code="third_pipe", domain_code="demo", message="Pipe 'third_pipe' failed its dry run: exploded")
+ ],
)
with pytest.raises(typer.Exit):
handle_validate_bundle_error(exc, bundle_path=Path("methods/demo.mthds"))
output = console.export_text()
- assert "Dry Run Error:" in output
- assert "dry run exploded" in output
+ assert "Dry Run Errors:" in output
+ assert "Pipe: third_pipe" in output
+ assert "Pipe 'third_pipe' failed its dry run: exploded" in output
diff --git a/tests/unit/pipelex/cogt/models/test_model_deck_unknown_reference.py b/tests/unit/pipelex/cogt/models/test_model_deck_unknown_reference.py
new file mode 100644
index 000000000..fa63a2129
--- /dev/null
+++ b/tests/unit/pipelex/cogt/models/test_model_deck_unknown_reference.py
@@ -0,0 +1,151 @@
+import pytest
+
+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode, ErrorReport
+from pipelex.cogt.config_cogt import ModelDeckConfig
+from pipelex.cogt.exceptions import ModelNotFoundError
+from pipelex.cogt.extract.extract_setting import ExtractSetting
+from pipelex.cogt.img_gen.img_gen_job_components import Quality
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
+from pipelex.cogt.llm.llm_setting import LLMSetting, LLMSettingChoices, LLMSettingChoicesDefaults
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
+from pipelex.cogt.model_backends.model_type import ModelType
+from pipelex.cogt.models.model_deck import ModelDeck
+from pipelex.cogt.usage.cost_category import CostCategory
+from pipelex.system.runtime import ProblemReaction
+
+
+def _make_deck() -> ModelDeck:
+ """A deck serving one model, whose own entries name several models it does not serve."""
+ served_model = InferenceModelSpec(
+ backend_name="test_backend",
+ name="served-model",
+ sdk="test_sdk",
+ model_type=ModelType.LLM,
+ model_id="test_model_served",
+ costs={CostCategory.INPUT: 0.001, CostCategory.OUTPUT: 0.002},
+ thinking_mode=ThinkingMode.NONE,
+ max_tokens=1000,
+ max_prompt_images=None,
+ )
+ return ModelDeck(
+ inference_models={"served-model": served_model},
+ llm_default_temperature=0.7,
+ llm_aliases={"deck-alias": "deck-alias-target", "served-alias": "served-model"},
+ llm_waterfalls={"deck-waterfall": ["deck-waterfall-member", "served-model"]},
+ llm_presets={"deck-preset": LLMSetting(model="deck-preset-model", temperature=0.3)},
+ llm_choice_defaults=LLMSettingChoicesDefaults(
+ default_temperature=0.7,
+ for_text=LLMSetting(model="deck-default-text", temperature=0.7),
+ for_object="$deck-preset",
+ ),
+ # A setting table is not parsed when the deck loads, so it can hold a value no reference parses from.
+ llm_choice_overrides=LLMSettingChoices(
+ for_text=LLMSetting(model="@", temperature=0.1),
+ for_object=LLMSetting(model="deck-override-object", temperature=0.1),
+ ),
+ extract_aliases={},
+ extract_waterfalls={},
+ extract_presets={"deck-extract-preset": ExtractSetting(model="deck-extract-preset-model")},
+ extract_choice_default="$deck-extract-preset",
+ img_gen_default_quality=Quality.MEDIUM,
+ img_gen_aliases={},
+ img_gen_waterfalls={},
+ img_gen_presets={},
+ # A handle spelled with its prefix reaches the lookup by its bare name.
+ img_gen_choice_default="handle:deck-img-gen-default",
+ search_aliases={},
+ search_waterfalls={},
+ search_presets={},
+ # A plain reference to a model the deck serves as another type.
+ search_choice_default="served-model",
+ model_deck_config=ModelDeckConfig(is_model_fallback_enabled=True, missing_presets_reaction=ProblemReaction.NONE),
+ )
+
+
+def _raise_not_found(*, model_handle: str, model_type: ModelType) -> ModelNotFoundError:
+ with pytest.raises(ModelNotFoundError) as exc_info:
+ _make_deck().get_required_inference_model(model_handle, model_type=model_type)
+ return exc_info.value
+
+
+class TestModelDeckUnknownReference:
+ @pytest.mark.parametrize(
+ ("_topic", "model_handle", "model_type", "needed_model"),
+ [
+ ("handle", "method-only-model", ModelType.LLM, "an LLM"),
+ ("alias", "@method-only-alias", ModelType.LLM, "an LLM"),
+ ("waterfall", "~method-only-waterfall", ModelType.LLM, "an LLM"),
+ ("preset_used_as_a_model", "$deck-preset", ModelType.LLM, "an LLM"),
+ ("extract_handle", "method-only-extractor", ModelType.TEXT_EXTRACTOR, "a text-extraction model"),
+ ("search_handle", "method-only-search", ModelType.SEARCH, "a search model"),
+ # An LLM preset names it, but no image-generation entry does.
+ ("img_gen_handle", "deck-preset-model", ModelType.IMG_GEN, "an image-generation model"),
+ # The deck serves it, but as an LLM, which an image-generation lookup refuses.
+ ("served_handle_of_another_type", "served-model", ModelType.IMG_GEN, "an image-generation model"),
+ ],
+ )
+ def test_a_reference_only_the_method_names_is_the_callers_fault(
+ self,
+ _topic: str,
+ model_handle: str,
+ model_type: ModelType,
+ needed_model: str,
+ ) -> None:
+ """A reference the deck neither defines nor names came from the method: input domain, and caller-facing."""
+ report = _raise_not_found(model_handle=model_handle, model_type=model_type).to_error_report()
+
+ assert report.error_type == "ModelNotFoundError"
+ assert report.message == f"Model handle '{model_handle}' was not found in the model deck."
+ assert report.error_domain == "input"
+ assert report.caller_facing_message is True
+ assert report.http_status == 422
+ # The category still says the setup is wrong for the call; the domain says whose it is.
+ assert report.error_category == "configuration"
+ # The next step names the reference as the method wrote it and the type its lookup asked for,
+ # and nothing of the deck: not even the type the deck serves a model of another type as.
+ expected_detail = f"Change the model '{model_handle}' to {needed_model} the model deck serves."
+ assert report.user_action == UserAction(kind=UserActionKind.CHANGE_MODEL, detail=expected_detail)
+ strict_payload = report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert strict_payload["message"] == report.message
+ assert strict_payload["user_action"] == {"kind": "change_model", "detail": expected_detail}
+
+ @pytest.mark.parametrize(
+ ("_topic", "model_handle", "model_type"),
+ [
+ ("preset_model", "deck-preset-model", ModelType.LLM),
+ ("alias_target", "deck-alias-target", ModelType.LLM),
+ ("defined_alias", "@deck-alias", ModelType.LLM),
+ ("waterfall_member", "deck-waterfall-member", ModelType.LLM),
+ ("default_setting", "deck-default-text", ModelType.LLM),
+ ("override_setting", "deck-override-object", ModelType.LLM),
+ ("unparsable_setting_model", "@", ModelType.LLM),
+ ("plain_reference_default", "deck-img-gen-default", ModelType.IMG_GEN),
+ ("plain_reference_default_of_another_type", "served-model", ModelType.SEARCH),
+ ("extract_preset_model", "deck-extract-preset-model", ModelType.TEXT_EXTRACTOR),
+ ],
+ )
+ def test_a_reference_the_deck_names_is_the_deployments_fault(self, _topic: str, model_handle: str, model_type: ModelType) -> None:
+ """A reference the deck itself defines or names but does not serve stays config-domain and redacted."""
+ report = _raise_not_found(model_handle=model_handle, model_type=model_type).to_error_report()
+
+ assert report.error_type == "ModelNotFoundError"
+ assert report.error_domain == "config"
+ assert report.caller_facing_message is False
+ assert report.http_status == 500
+ # The caller cannot fix what the deck names, so no next step is theirs to read.
+ assert report.user_action is None
+ strict_payload = report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert strict_payload["message"] == INTERNAL_ERROR_PLACEHOLDER
+ assert "user_action" not in strict_payload
+
+ def test_the_classification_rides_the_worker_to_runner_hop(self) -> None:
+ """On a hosted run the lookup fails on a worker: the report is packed VERBOSE there and projected STRICT on the runner."""
+ packed = _raise_not_found(model_handle="method-only-model", model_type=ModelType.LLM).to_error_report().to_dict()
+ recovered = ErrorReport.from_dict(packed)
+
+ assert recovered.caller_facing_message is True
+ payload = recovered.to_problem_document(disclosure_mode=DisclosureMode.STRICT)
+ assert payload["status"] == 422
+ assert payload["detail"] == "Model handle 'method-only-model' was not found in the model deck."
+ assert payload["user_action"] == {"kind": "change_model", "detail": "Change the model 'method-only-model' to an LLM the model deck serves."}
diff --git a/tests/unit/pipelex/exceptions/test_as_caller_fault.py b/tests/unit/pipelex/exceptions/test_as_caller_fault.py
new file mode 100644
index 000000000..f03be6140
--- /dev/null
+++ b/tests/unit/pipelex/exceptions/test_as_caller_fault.py
@@ -0,0 +1,69 @@
+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode, ErrorDomain, PipelexError
+from pipelex.cogt.exceptions import InferenceErrorCategory, ModelNotFoundError
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
+from pipelex.core.stuffs.exceptions import StuffFactoryError
+from pipelex.pipe_run.exceptions import PipeRouterError
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+
+class TestAsCallerFault:
+ def test_classifies_this_error_only(self) -> None:
+ """The raise site's classification applies to its own error, never to the class or to another instance."""
+ caller_fault = StuffFactoryError("Error combining stuffs for concept Report").as_caller_fault()
+ other = StuffFactoryError("A factory refusal that is not the caller's")
+
+ caller_report = caller_fault.to_error_report()
+ assert caller_report.error_domain == ErrorDomain.INPUT
+ assert caller_report.caller_facing_message is True
+ assert caller_report.http_status == 422
+
+ other_report = other.to_error_report()
+ assert other_report.error_domain is None
+ assert other_report.caller_facing_message is False
+ assert StuffFactoryError.error_domain is None
+
+ def test_strict_disclosure_keeps_the_message_and_the_user_action(self) -> None:
+ """A caller fault reads its own message and next step under STRICT, instead of the placeholder."""
+ user_action = UserAction(kind=UserActionKind.CHANGE_INPUT, detail="Provide the input 'topic'.")
+ error = StuffFactoryError("Input 'topic' is missing").as_caller_fault(user_action=user_action)
+
+ payload = error.to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert payload["message"] == "Input 'topic' is missing"
+ assert payload["user_action"] == {"kind": "change_input", "detail": "Provide the input 'topic'."}
+
+ def test_wins_over_a_domain_the_category_derives(self) -> None:
+ """On a `CogtError`, the raise site's domain wins over the one its category derives."""
+ error = ModelNotFoundError(message="Model handle 'x' was not found in the model deck.", model_handle="x").as_caller_fault()
+
+ report = error.to_error_report()
+ assert error.error_category is InferenceErrorCategory.CONFIGURATION
+ assert report.error_category == "configuration"
+ assert report.error_domain == ErrorDomain.INPUT
+ assert report.caller_facing_message is True
+
+ def test_a_wrapper_inherits_the_domain_but_never_the_caller_facing_flag(self) -> None:
+ """The flag records who wrote the message: a plain wrapper's own message stays redacted."""
+ cause = StuffFactoryError("Error combining stuffs for concept Report").as_caller_fault()
+ wrapper = PipelexError("An internal sentence about the cause")
+ wrapper.__cause__ = cause
+
+ report = wrapper.to_error_report()
+ assert report.error_domain == ErrorDomain.INPUT
+ assert report.caller_facing_message is False
+ assert report.to_dict(disclosure_mode=DisclosureMode.STRICT)["message"] == INTERNAL_ERROR_PLACEHOLDER
+
+ def test_a_located_wrapper_reports_the_caller_fault_it_locates(self) -> None:
+ """The pipe router's location takes the root fault's flag, so the located message survives STRICT."""
+ cause = StuffFactoryError("Error combining stuffs for concept Report").as_caller_fault()
+ located = PipeRouterError.make_located(
+ failure=cause,
+ run_mode=PipeRunMode.LIVE,
+ pipe_code="analyze",
+ output_name=None,
+ pipe_stack=["flow", "analyze"],
+ )
+ located.__cause__ = cause
+
+ payload = located.to_error_report().to_problem_document(disclosure_mode=DisclosureMode.STRICT)
+ assert payload["status"] == 422
+ assert payload["detail"] == "Pipe 'analyze' failed (flow → analyze): Error combining stuffs for concept Report"
diff --git a/tests/unit/pipelex/exceptions/test_class_level_metadata.py b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
index 14b82044f..091779a71 100644
--- a/tests/unit/pipelex/exceptions/test_class_level_metadata.py
+++ b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
@@ -77,8 +77,12 @@ class TestClassLevelMetadata:
@pytest.mark.parametrize(
("_topic", "exc", "expected_detail"),
[
- ("pipeline_execution", _PIPELINE_EXEC_ERROR, "Check pipe_stack to identify which pipe failed"),
- ("validate_bundle", ValidateBundleError("boom"), "Check the validation_errors array for specific issues"),
+ ("pipeline_execution", _PIPELINE_EXEC_ERROR, "The run of 'some_pipe' failed: the message gives the cause."),
+ (
+ "validate_bundle",
+ ValidateBundleError("boom"),
+ "Edit the bundle as each validation error says: apply its suggested fix where it has one, after confirming an unsafe one",
+ ),
(
"entry_pipe_not_found",
EntryPipeNotFoundError("boom"),
diff --git a/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py b/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
index 84d25b8ac..d1c8f6717 100644
--- a/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
+++ b/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
@@ -76,10 +76,10 @@ class TestWrapperErrorEnrichment:
assert report.error_category == InferenceErrorCategory.CONTENT
def test_falls_back_to_runtime_unknown_without_cause(self) -> None:
- """With no PipelexError cause, PipelineExecutionError reports the generic RUNTIME / UNKNOWN floor."""
+ """With no PipelexError cause, PipelineExecutionError reports the RUNTIME floor and a fallback naming the failing pipe."""
report = _make_pipeline_execution_error(cause=None).to_error_report()
assert report.error_domain == ErrorDomain.RUNTIME
assert report.user_action is not None
assert report.user_action.kind == UserActionKind.UNKNOWN
- assert report.user_action.detail == "Check pipe_stack to identify which pipe failed"
+ assert report.user_action.detail == "The run failed in pipe 'some_pipe': the message gives the cause."
diff --git a/tests/unit/pipelex/libraries/test_concept_reference_validation.py b/tests/unit/pipelex/libraries/test_concept_reference_validation.py
index d7e7f19cf..d6b087ac9 100644
--- a/tests/unit/pipelex/libraries/test_concept_reference_validation.py
+++ b/tests/unit/pipelex/libraries/test_concept_reference_validation.py
@@ -335,3 +335,26 @@ class TestConceptReferenceValidation:
assert "DeclaredConcept2" in message
assert "Native concepts" in message
assert "Text" in message
+
+ def test_declared_concepts_list_the_validated_bundle_only(self):
+ """An unresolved item lists what the validated bundle declares, never what an earlier load brought in.
+
+ The concepts already loaded may come from a host's own library directories, which a caller's
+ verdict must not enumerate, even in the caller's own domain.
+ """
+ bundle = PipelexBundleBlueprint(
+ domain="test_domain",
+ description="Test bundle",
+ concept={"DeclaredConcept": "A declared concept"},
+ pipe={
+ "my_pipe": PipeLLMBlueprint(
+ description="Test pipe",
+ output="UndeclaredConcept",
+ prompt="Generate",
+ ),
+ },
+ )
+ with pytest.raises(ConceptLibraryError) as exc_info:
+ validate_concept_references_in_blueprints(blueprints=[bundle], already_loaded_concept_refs={"test_domain.HostPrivatePlan"})
+ (unresolved_item,) = exc_info.value.pipe_concept_validation_errors
+ assert unresolved_item.declared_concepts == ["DeclaredConcept"]
diff --git a/tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py b/tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py
index dd1a6eb11..3313dd7ff 100644
--- a/tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py
+++ b/tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py
@@ -111,6 +111,7 @@ class TestDependencyMultiFileReconciliation:
manager = LibraryManager()
manager._load_single_dependency( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
library=library,
+ package_address="github.com/org/summary-dep",
resolved_dep=self._build_resolved_dep(
tmp_path=tmp_path,
file_contents=[("header.mthds", DEP_HEADER_MTHDS), ("definition.mthds", DEP_CONCRETE_MTHDS)],
@@ -139,6 +140,7 @@ class TestDependencyMultiFileReconciliation:
manager = LibraryManager()
manager._load_single_dependency( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
library=library,
+ package_address="github.com/org/summary-dep",
resolved_dep=self._build_resolved_dep(
tmp_path=tmp_path,
file_contents=[("header.mthds", DEP_TYPELESS_HEADER_MTHDS), ("definition.mthds", DEP_CONCRETE_MTHDS)],
@@ -164,6 +166,7 @@ class TestDependencyMultiFileReconciliation:
with pytest.raises(PipeLibraryError):
manager._load_single_dependency( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
library=library,
+ package_address="github.com/org/summary-dep",
resolved_dep=self._build_resolved_dep(
tmp_path=tmp_path,
file_contents=[("def_a.mthds", DEP_CONCRETE_MTHDS), ("def_b.mthds", DEP_CONCRETE_DUP_MTHDS)],
diff --git a/tests/unit/pipelex/libraries/test_dependency_pipe_build_refusals.py b/tests/unit/pipelex/libraries/test_dependency_pipe_build_refusals.py
new file mode 100644
index 000000000..63a638e0c
--- /dev/null
+++ b/tests/unit/pipelex/libraries/test_dependency_pipe_build_refusals.py
@@ -0,0 +1,113 @@
+from pathlib import Path
+
+import pytest
+from mthds.package.dependency_resolver import ResolvedDependency
+from mthds.package.manifest.schema import MethodsManifest
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import ErrorDomain, PipelexError
+from pipelex.core.pipes.exceptions import PipeLoadRefusalError, PipeOperatorModelChoiceError
+from pipelex.interpreter_hub import get_library_manager
+from pipelex.libraries.library_factory import LibraryFactory
+from pipelex.libraries.library_manager import LibraryManager
+
+_DEP_DOMAIN = "harbour_dep"
+
+_SCORE_PIPE = """
+[pipe.score_tide]
+type = "PipeLLM"
+description = "Score how favourable the tide is for leaving harbour"
+inputs = {{ tide_times = "Text" }}
+output = "Text"
+{model_line}
+prompt = "Score how favourable these tide times are for leaving harbour: $tide_times"
+"""
+
+_PRELIMINARY_TEXT_PIPE = """
+[concept.TideFact]
+description = "When the tide turns at one harbour"
+
+[concept.TideFact.structure]
+harbour = { type = "text", description = "The harbour's name", required = true }
+
+[pipe.extract_tide]
+type = "PipeLLM"
+description = "Extract the tide fact from the harbour board's notice"
+inputs = { tide_times = "Text" }
+output = "TideFact"
+structuring_method = "preliminary_text"
+model_to_structure = "@best-sonet"
+prompt = "Extract the tide fact from this notice: $tide_times"
+"""
+
+
+def _dep_bundle(*, pipes: str) -> str:
+ return f'domain = "{_DEP_DOMAIN}"\ndescription = "A dependency package the harbour board publishes"\n{pipes}'
+
+
+class _InternalInputRefusalError(PipelexError):
+ error_domain = ErrorDomain.INPUT
+
+
+class TestDependencyPipeBuildRefusals:
+ def _load_dependency(self, *, mocker: MockerFixture, tmp_path: Path, bundle: str) -> Path:
+ """Load one dependency package through ``_load_single_dependency``, returning its bundle file."""
+ mthds_file = tmp_path / "harbour_dep.mthds"
+ mthds_file.write_text(bundle, encoding="utf-8")
+ resolved_dep = ResolvedDependency(
+ alias="harbour_dep",
+ address="github.com/harbour-board/harbour-dep",
+ manifest=MethodsManifest(address="github.com/harbour-board/harbour-dep", version="1.0.0", description="A dependency package"),
+ package_root=tmp_path,
+ mthds_files=[mthds_file],
+ exported_pipe_codes=None,
+ )
+ library = LibraryFactory.make_empty()
+ mocker.patch.object(get_library_manager(), "get_current_library", return_value=library)
+ LibraryManager()._load_single_dependency( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ library=library,
+ package_address="github.com/harbour-board/harbour-dep",
+ resolved_dep=resolved_dep,
+ )
+ return mthds_file
+
+ def test_unknown_model_in_a_dependency_pipe_names_the_dependency_file(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ """A dependency pipe is built outside the main load loop, and its refusal still carries the file it is declared in."""
+ bundle = _dep_bundle(pipes=_SCORE_PIPE.format(model_line='model = "@best-sonet"'))
+
+ with pytest.raises(PipeOperatorModelChoiceError) as raised:
+ self._load_dependency(mocker=mocker, tmp_path=tmp_path, bundle=bundle)
+
+ refusal = raised.value
+ assert refusal.pipe_code == "score_tide"
+ assert refusal.domain_code == _DEP_DOMAIN
+ assert refusal.field_name == "model"
+ assert refusal.model_choice == "@best-sonet"
+ assert refusal.source == "github.com/harbour-board/harbour-dep/harbour_dep.mthds"
+
+ def test_unknown_model_in_a_dependency_helper_names_the_authored_pipe(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ """A ``preliminary_text`` helper of a dependency pipe is reported on the pipe and field its author wrote."""
+ with pytest.raises(PipeOperatorModelChoiceError) as raised:
+ self._load_dependency(mocker=mocker, tmp_path=tmp_path, bundle=_dep_bundle(pipes=_PRELIMINARY_TEXT_PIPE))
+
+ refusal = raised.value
+ assert refusal.pipe_code == "extract_tide"
+ assert refusal.field_name == "model_to_structure"
+ assert refusal.source == "github.com/harbour-board/harbour-dep/harbour_dep.mthds"
+
+ def test_other_input_refusal_in_a_dependency_pipe_is_located(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ """Any other refusal of the caller's input raised while building a dependency pipe is located on that pipe and file."""
+ mocker.patch(
+ "pipelex.pipe_operators.llm.pipe_llm.check_llm_choice_with_deck",
+ side_effect=_InternalInputRefusalError("internal detail: registry slot 7 is stale"),
+ )
+ bundle = _dep_bundle(pipes=_SCORE_PIPE.format(model_line='model = "@best-gpt"'))
+
+ with pytest.raises(PipeLoadRefusalError) as raised:
+ self._load_dependency(mocker=mocker, tmp_path=tmp_path, bundle=bundle)
+
+ refusal = raised.value
+ assert refusal.pipe_code == "score_tide"
+ assert refusal.domain_code == _DEP_DOMAIN
+ assert refusal.source == "github.com/harbour-board/harbour-dep/harbour_dep.mthds"
+ assert isinstance(refusal.__cause__, _InternalInputRefusalError)
diff --git a/tests/unit/pipelex/libraries/test_dependency_preliminary_text_export.py b/tests/unit/pipelex/libraries/test_dependency_preliminary_text_export.py
index 511233e3e..a6f287b05 100644
--- a/tests/unit/pipelex/libraries/test_dependency_preliminary_text_export.py
+++ b/tests/unit/pipelex/libraries/test_dependency_preliminary_text_export.py
@@ -75,6 +75,7 @@ class TestDependencyPreliminaryTextExport:
manager = LibraryManager()
manager._load_single_dependency( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
library=library,
+ package_address="github.com/org/review-dep",
resolved_dep=self._build_resolved_dep(tmp_path=tmp_path, exported={"make_review"}),
)
@@ -101,6 +102,7 @@ class TestDependencyPreliminaryTextExport:
manager = LibraryManager()
manager._load_single_dependency( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
library=library,
+ package_address="github.com/org/review-dep",
resolved_dep=self._build_resolved_dep(tmp_path=tmp_path, exported=set()),
)
diff --git a/tests/unit/pipelex/libraries/test_dependency_ref_qualification.py b/tests/unit/pipelex/libraries/test_dependency_ref_qualification.py
index 6a4aa6ff1..e5b8242cc 100644
--- a/tests/unit/pipelex/libraries/test_dependency_ref_qualification.py
+++ b/tests/unit/pipelex/libraries/test_dependency_ref_qualification.py
@@ -74,6 +74,7 @@ class TestDependencyRefQualification:
manager = LibraryManager()
manager._load_single_dependency( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
library=library,
+ package_address="github.com/org/charts-dep",
resolved_dep=ResolvedDependency(
alias="charts_dep",
address="github.com/org/charts-dep",
diff --git a/tests/unit/pipelex/libraries/test_mthds_version_warning.py b/tests/unit/pipelex/libraries/test_mthds_version_warning.py
index 0178952f8..3ca294edc 100644
--- a/tests/unit/pipelex/libraries/test_mthds_version_warning.py
+++ b/tests/unit/pipelex/libraries/test_mthds_version_warning.py
@@ -84,6 +84,7 @@ class TestMthdsVersionWarning:
manager._load_single_dependency( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
library=library,
+ package_address="github.com/org/dep-pkg",
resolved_dep=resolved_dep,
)
diff --git a/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py b/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py
index b843a6857..e079cfe74 100644
--- a/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py
+++ b/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py
@@ -46,6 +46,28 @@ steps = [
]
"""
+# A misspelled field (`promtp`, pydantic's `extra_forbidden`, which no categorizer knows) in one pipe and
+# an undeclared prompt variable in another.
+_TYPO_BESIDE_UNDECLARED_VARIABLE_MTHDS = """
+domain = "notes"
+description = "Summarize and translate notes"
+
+[pipe.summarize_notes]
+type = "PipeLLM"
+description = "Summarize the notes"
+inputs = { notes = "Text" }
+output = "Text"
+promtp = "Summarize these notes"
+prompt = "Summarize these notes: $notes"
+
+[pipe.translate_notes]
+type = "PipeLLM"
+description = "Translate the notes"
+inputs = { notes = "Text" }
+output = "Text"
+prompt = "Translate these notes into $language: $notes"
+"""
+
class TestBlueprintValidationErrorCategorizer:
@pytest.mark.parametrize(
@@ -89,3 +111,50 @@ class TestBlueprintValidationErrorCategorizer:
# The recovered message is the PipeValidationError's own clean text, not pydantic's
# "Value error, " prefixed wrapper.
assert not item.message.startswith("Value error"), f"Expected the unwrapped clean message, got: {item.message!r}"
+
+ def test_an_uncategorized_error_is_kept_beside_a_categorized_one(self) -> None:
+ """An error no categorizer knows is an item of its own, located by its source, pipe and field path."""
+ with pytest.raises(MthdsParserError) as exc_info:
+ MthdsParser.make_pipelex_bundle_blueprint(mthds_content=_TYPO_BESIDE_UNDECLARED_VARIABLE_MTHDS, mthds_source="notes.mthds")
+
+ errors = exc_info.value.validation_errors
+ assert len(errors) == 2
+ typo_error = next(error for error in errors if error.error_type is None)
+ assert typo_error.pipe_code == "summarize_notes"
+ assert typo_error.domain_code == "notes"
+ assert typo_error.source == "notes.mthds"
+ # The union tag pydantic routed through (`PipeLLM`) is not a field of the bundle.
+ assert typo_error.field_path == "pipe.summarize_notes.promtp"
+ assert typo_error.message == "Validation error at 'pipe.summarize_notes.promtp': Extra inputs are not permitted"
+ assert any(error.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE for error in errors)
+
+ @pytest.mark.parametrize("misspelled_key", ["prompt-template", "str"])
+ def test_a_misspelled_key_is_named_whatever_it_looks_like(self, misspelled_key: str) -> None:
+ """A key the author wrote stays in the field path even when it looks like one of pydantic's own elements."""
+ mthds_content = _TYPO_BESIDE_UNDECLARED_VARIABLE_MTHDS.replace("promtp = ", f"{misspelled_key} = ")
+ with pytest.raises(MthdsParserError) as exc_info:
+ MthdsParser.make_pipelex_bundle_blueprint(mthds_content=mthds_content, mthds_source="notes.mthds")
+
+ typo_error = next(error for error in exc_info.value.validation_errors if error.error_type is None)
+ assert typo_error.field_path == f"pipe.summarize_notes.{misspelled_key}"
+ assert typo_error.message == f"Validation error at 'pipe.summarize_notes.{misspelled_key}': Extra inputs are not permitted"
+
+ def test_a_domain_that_is_not_a_string_locates_nothing(self) -> None:
+ """The raw dict holds what the author wrote: a `domain = 123` is an error, never a locator."""
+ with pytest.raises(MthdsParserError) as exc_info:
+ MthdsParser.make_pipelex_bundle_blueprint(mthds_content='domain = 123\ndescription = "d"\n', mthds_source="numbers.mthds")
+
+ (domain_error,) = exc_info.value.validation_errors
+ assert domain_error.error_type is None
+ assert domain_error.domain_code is None
+ assert domain_error.source == "numbers.mthds"
+ assert domain_error.field_path == "domain"
+
+ def test_a_toml_syntax_error_carries_its_line_and_column(self) -> None:
+ """Tomli counts both from 1, as the item's locators do."""
+ with pytest.raises(MthdsParserError) as exc_info:
+ MthdsParser.make_pipelex_bundle_blueprint(mthds_content='domain = "notes"\ndescription = "unterminated\n', mthds_source="notes.mthds")
+
+ (syntax_error,) = exc_info.value.validation_errors
+ assert (syntax_error.line, syntax_error.column) == (2, 28)
+ assert syntax_error.source == "notes.mthds"
diff --git a/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_combine_refusal.py b/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_combine_refusal.py
new file mode 100644
index 000000000..a955d816c
--- /dev/null
+++ b/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_combine_refusal.py
@@ -0,0 +1,46 @@
+from typing import Any
+
+import pytest
+from pydantic import BaseModel, ValidationError, model_validator
+
+from pipelex.core.stuffs.exceptions import StuffFactoryError
+from pipelex.pipe_controllers.parallel.pipe_parallel import _refused_field_names # pyright: ignore[reportPrivateUsage]
+
+
+class _FieldRefusal(BaseModel):
+ ideas: int
+ overview: int
+
+
+class _WholeStructureRefusal(BaseModel):
+ ideas: int
+
+ @model_validator(mode="before")
+ @classmethod
+ def refuse_everything(cls, data: Any) -> Any:
+ msg = f"the structure refuses this combination: {data!r}"
+ raise ValueError(msg)
+
+
+def _combine_refusal(*, model_class: type[BaseModel], obj: dict[str, Any]) -> StuffFactoryError:
+ try:
+ model_class.model_validate(obj)
+ except ValidationError as exc:
+ refusal = StuffFactoryError("Error combining stuffs")
+ refusal.__cause__ = exc
+ return refusal
+ pytest.fail("the model accepted what it was expected to refuse")
+
+
+class TestPipeParallelCombineRefusal:
+ def test_field_refusals_are_named(self) -> None:
+ refusal = _combine_refusal(model_class=_FieldRefusal, obj={"ideas": "many", "overview": "short"})
+ assert _refused_field_names(exc=refusal) == {"ideas", "overview"}
+
+ def test_a_refusal_of_the_whole_structure_is_unclassified(self) -> None:
+ """A model-level refusal belongs to no field, so no multiplicity sentence can explain it."""
+ refusal = _combine_refusal(model_class=_WholeStructureRefusal, obj={"ideas": 1})
+ assert _refused_field_names(exc=refusal) is None
+
+ def test_a_refusal_without_a_pydantic_cause_is_unclassified(self) -> None:
+ assert _refused_field_names(exc=StuffFactoryError("Error combining stuffs")) is None
diff --git a/tests/unit/pipelex/pipe_run/test_located_failure.py b/tests/unit/pipelex/pipe_run/test_located_failure.py
new file mode 100644
index 000000000..642884bde
--- /dev/null
+++ b/tests/unit/pipelex/pipe_run/test_located_failure.py
@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import pytest
+from typing_extensions import override
+
+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode, ErrorDomain, ErrorReport, PipelexError
+from pipelex.cogt.exceptions import CogtError, InferenceErrorCategory
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
+from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
+from pipelex.core.pipes.inputs.exceptions import OptionalValueAbsentError
+from pipelex.pipe_run.exceptions import PipeRouterError, find_failure_location
+from pipelex.pipe_run.located_failure import compose_located_message, find_foreign_fault, find_root_fault, make_unexpected_failure
+from pipelex.pipeline.exceptions import PipelineExecutionError
+from pipelex.runtime_bridge.exceptions import PipelexBridgeDispatchError
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+
+class _RecoveredReportError(PipelexError):
+ """Carries a report recovered across a transport boundary, and reports it as it is."""
+
+ def __init__(self, message: str, *, error_report: ErrorReport):
+ super().__init__(message)
+ self.error_report = error_report
+
+ @override
+ def to_error_report(self) -> ErrorReport:
+ return self.error_report
+
+
+def _locate(failure: PipelexError, *, pipe_stack: list[str]) -> PipeRouterError:
+ located = PipeRouterError.make_located(
+ failure=failure,
+ run_mode=PipeRunMode.LIVE,
+ pipe_code=pipe_stack[-1],
+ output_name=None,
+ pipe_stack=pipe_stack,
+ )
+ located.__cause__ = failure
+ return located
+
+
+def _wrap_in_runner(failure: PipelexError, *, entry_pipe_code: str) -> PipelineExecutionError:
+ wrapped = PipelineExecutionError.make_for_run_failure(
+ failure=failure,
+ run_mode=PipeRunMode.LIVE,
+ entry_pipe_code=entry_pipe_code,
+ output_name=None,
+ )
+ wrapped.__cause__ = failure
+ return wrapped
+
+
+def _make_absence_error() -> OptionalValueAbsentError:
+ return OptionalValueAbsentError.make(
+ run_mode=PipeRunMode.LIVE,
+ pipe_code="force_echo",
+ variable_name="clause",
+ concept_ref="native.Text",
+ absence_record=AbsenceRecord(variable_name="clause", kind=AbsenceKind.NOT_PROVIDED, reason="not provided by the caller"),
+ )
+
+
+class TestLocatedFailureReport:
+ @pytest.mark.parametrize(
+ ("pipe_stack", "expected_message"),
+ [
+ (["two_steps", "summarize"], "Pipe 'summarize' failed (two_steps → summarize): boom"),
+ (["summarize"], "Pipe 'summarize' failed: boom"),
+ ([], "boom"),
+ ],
+ )
+ def test_compose_located_message(self, pipe_stack: list[str], expected_message: str) -> None:
+ """A nested pipe names its path, an entry pipe does not, and an unknown location leaves the message alone."""
+ assert compose_located_message(pipe_code="summarize", pipe_stack=pipe_stack, message="boom") == expected_message
+
+ def test_foreign_fault_is_found_only_behind_a_stand_in(self) -> None:
+ """The foreign exception a located PipelexUnexpectedError stands in for is found; a Pipelex root fault has none."""
+ foreign_fault = KeyError("boom")
+ located_foreign = _locate(make_unexpected_failure(error=foreign_fault), pipe_stack=["flow", "analyze"])
+ located_pipelex = _locate(PipelexError("combine failed"), pipe_stack=["flow", "analyze"])
+
+ assert find_foreign_fault(error=_wrap_in_runner(located_foreign, entry_pipe_code="flow")) is foreign_fault
+ assert find_foreign_fault(error=located_pipelex) is None
+
+ def test_a_foreign_exception_ends_the_walk(self) -> None:
+ """A foreign exception raised from an older PipelexError: its stand-in is the root fault, not the older error."""
+ older_error = PipelexError("older failure")
+ foreign_fault = KeyError("boom")
+ foreign_fault.__cause__ = older_error
+ unexpected_failure = make_unexpected_failure(error=foreign_fault)
+ located = _locate(unexpected_failure, pipe_stack=["flow"])
+
+ assert find_root_fault(error=located) is unexpected_failure
+ assert find_foreign_fault(error=located) is foreign_fault
+ assert located.to_error_report().error_type == "PipelexUnexpectedError"
+
+ def test_a_same_class_rethrow_keeps_its_added_context(self) -> None:
+ """An error raised from one of its own class restates the fault with context: the outer one is reported."""
+ low_level = CogtError(message="size out of range", error_category=InferenceErrorCategory.CONTENT)
+ with_remedy = CogtError(message="Size tier '4k' is not satisfiable: use '1k' or '2k'", error_category=InferenceErrorCategory.CONTENT)
+ with_remedy.__cause__ = low_level
+ located = _locate(with_remedy, pipe_stack=["flow", "draw"])
+
+ assert find_root_fault(error=located) is with_remedy
+ assert located.to_error_report().message == "Pipe 'draw' failed (flow → draw): Size tier '4k' is not satisfiable: use '1k' or '2k'"
+
+ def test_identity_and_message_are_the_root_faults(self) -> None:
+ """Through the router, a bridge and the runner, the report is the root fault's, located once."""
+ root_fault = CogtError(message="rate limited", error_category=InferenceErrorCategory.TRANSIENT)
+ located = _locate(root_fault, pipe_stack=["flow", "analyze", "gen_ideas"])
+ bridge_error = PipelexBridgeDispatchError(f"Pipe execution failed in DIRECT mode for pipe 'flow': {located}")
+ bridge_error.__cause__ = located
+ run_failure = _wrap_in_runner(bridge_error, entry_pipe_code="flow")
+
+ assert find_root_fault(error=run_failure) is root_fault
+ assert find_failure_location(error=run_failure) is located
+ assert run_failure.pipe_code == "gen_ideas"
+ assert run_failure.pipe_stack == ["flow", "analyze", "gen_ideas"]
+
+ report = run_failure.to_error_report()
+ assert report.error_type == "CogtError"
+ assert report.title == CogtError.title()
+ assert report.type_uri == CogtError.type_uri()
+ assert report.message == "Pipe 'gen_ideas' failed (flow → analyze → gen_ideas): rate limited"
+ assert run_failure.message == report.message
+ # Classification inherited from the chain, untouched by the floor.
+ assert report.error_category == InferenceErrorCategory.TRANSIENT
+ assert report.retryable is True
+ assert report == located.to_error_report()
+
+ def test_caller_facing_flag_is_the_root_faults(self) -> None:
+ """A caller-facing root keeps its located message under STRICT; the wrapper grants nothing of its own."""
+ report = _wrap_in_runner(
+ _locate(_make_absence_error(), pipe_stack=["force_flow", "force_echo"]), entry_pipe_code="force_flow"
+ ).to_error_report()
+
+ assert report.caller_facing_message is True
+ strict_payload = report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert strict_payload["message"] == report.message
+ assert strict_payload["message"].startswith("Pipe 'force_echo' failed (force_flow → force_echo): ")
+ assert strict_payload["user_action"]["kind"] == UserActionKind.CHANGE_INPUT
+
+ def test_a_bridge_sentence_is_never_caller_facing(self) -> None:
+ """A bridge error with no PipelexError under it reports as itself, and stays redacted under STRICT."""
+ bridge_error = PipelexBridgeDispatchError("Pipe execution failed in DIRECT mode for pipe 'flow': internal detail")
+ report = _wrap_in_runner(bridge_error, entry_pipe_code="flow").to_error_report()
+
+ assert report.error_type == "PipelexBridgeDispatchError"
+ assert report.caller_facing_message is False
+ assert report.to_dict(disclosure_mode=DisclosureMode.STRICT)["message"] == INTERNAL_ERROR_PLACEHOLDER
+
+ def test_floor_and_fallback_apply_only_when_the_chain_is_silent(self) -> None:
+ """No domain and no action on the chain: RUNTIME, and a fallback naming the failing pipe."""
+ report = _locate(PipelexError("combine failed"), pipe_stack=["flow", "analyze"]).to_error_report()
+
+ assert report.error_domain == ErrorDomain.RUNTIME
+ assert report.user_action == UserAction(kind=UserActionKind.UNKNOWN, detail="The run failed in pipe 'analyze': the message gives the cause.")
+
+ def test_a_categorized_action_is_kept(self) -> None:
+ root_fault = CogtError(
+ message="quota exceeded",
+ error_category=InferenceErrorCategory.CAPACITY,
+ user_action=UserAction(kind=UserActionKind.CHECK_BILLING, detail="Check your billing"),
+ )
+ report = _locate(root_fault, pipe_stack=["flow"]).to_error_report()
+
+ assert report.user_action == UserAction(kind=UserActionKind.CHECK_BILLING, detail="Check your billing")
+
+ def test_a_recovered_report_is_taken_as_it_is(self) -> None:
+ """A report recovered across a boundary already names its pipe: the runner does not locate it again."""
+ recovered_report = _locate(PipelexError("combine failed"), pipe_stack=["flow", "analyze"]).to_error_report()
+ recovered = _RecoveredReportError(recovered_report.message, error_report=recovered_report)
+ bridge_error = PipelexBridgeDispatchError(f"Pipe execution failed in temporal blocking delivery for pipe 'flow': {recovered}")
+ bridge_error.__cause__ = recovered
+ run_failure = _wrap_in_runner(bridge_error, entry_pipe_code="flow")
+
+ assert run_failure.pipe_code == "flow"
+ assert run_failure.pipe_stack == []
+ assert run_failure.message == recovered_report.message
+ assert run_failure.to_error_report() == recovered_report
+
+ def test_a_recovered_leaf_report_is_located_by_the_router(self) -> None:
+ """A PipelexError carrying a leaf's recovered report is located with the leaf's identity."""
+ leaf_report = CogtError(message="model refused", error_category=InferenceErrorCategory.CONFIGURATION).to_error_report()
+ report = _locate(_RecoveredReportError(leaf_report.message, error_report=leaf_report), pipe_stack=["flow", "summarize"]).to_error_report()
+
+ assert report.error_type == "CogtError"
+ assert report.message == "Pipe 'summarize' failed (flow → summarize): model refused"
+ assert report.error_domain == ErrorDomain.CONFIG
+
+ def test_a_cyclic_chain_reports_the_wrapper_as_itself(self) -> None:
+ """A chain that loops back to the wrapper cannot make the report recurse."""
+ root_fault = PipelexError("combine failed")
+ located = _locate(root_fault, pipe_stack=["flow"])
+ root_fault.__cause__ = located
+
+ report = located.to_error_report()
+
+ assert report.error_type == "PipeRouterError"
+ assert report.message.endswith("combine failed")
diff --git a/tests/unit/pipelex/pipe_run/test_pipe_router_run.py b/tests/unit/pipelex/pipe_run/test_pipe_router_run.py
index 25a038419..0fe4ed330 100644
--- a/tests/unit/pipelex/pipe_run/test_pipe_router_run.py
+++ b/tests/unit/pipelex/pipe_run/test_pipe_router_run.py
@@ -1,11 +1,14 @@
from typing import TYPE_CHECKING, cast
import pytest
+from pydantic import BaseModel, ValidationError
from typing_extensions import override
+from pipelex.base_exceptions import ErrorReport, PipelexError, PipelexUnexpectedError
from pipelex.cogt.exceptions import CogtError, InferenceErrorCategory
from pipelex.core.pipes.exceptions import PipeRunError
from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.core.stuffs.exceptions import StuffFactoryError
from pipelex.observer.observer_protocol import ObserverNoOp
from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.pipe_run.pipe_job import PipeJob
@@ -13,6 +16,7 @@ from pipelex.pipe_run.pipe_router_protocol import PipeRouterProtocol
from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
from pipelex.system.job_metadata import JobMetadata, RunMetadata
from pipelex.system.pipe_run_mode import PipeRunMode
+from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
if TYPE_CHECKING:
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
@@ -38,6 +42,53 @@ class _StubPipeRouter(PipeRouterProtocol):
raise self._error
+class _PassThroughRouter(_StubPipeRouter):
+ """A host router that lets its runtime's RuntimeError through, as one does for a cancellation."""
+
+ @override
+ def _as_pipelex_failure(self, *, error: Exception) -> PipelexError | None:
+ if isinstance(error, RuntimeError):
+ return None
+ return super()._as_pipelex_failure(error=error)
+
+
+class _RecoveredReportCarrierError(PipelexError):
+ """Carries a root fault's report recovered across a transport boundary."""
+
+ def __init__(self, message: str, *, error_report: ErrorReport):
+ super().__init__(message)
+ self.error_report = error_report
+
+ @override
+ def to_error_report(self) -> ErrorReport:
+ return self.error_report
+
+
+class _RelocatingHostRouter(_StubPipeRouter):
+ """A host router whose transport packed the root fault's report and the location found on the far side."""
+
+ def __init__(self, error: Exception, *, packed_report: ErrorReport, packed_pipe_code: str, packed_pipe_stack: list[str]):
+ super().__init__(error=error)
+ self._packed_report = packed_report
+ self._packed_pipe_code = packed_pipe_code
+ self._packed_pipe_stack = packed_pipe_stack
+
+ @override
+ def _as_pipelex_failure(self, *, error: Exception) -> PipelexError | None:
+ carrier = _RecoveredReportCarrierError(self._packed_report.message, error_report=self._packed_report)
+ located = PipeRouterError.make_located(
+ failure=carrier, run_mode=PipeRunMode.LIVE, pipe_code=self._packed_pipe_code, output_name=None, pipe_stack=self._packed_pipe_stack
+ )
+ located.__cause__ = carrier
+ return located
+
+
+class _MiniPayload(BaseModel):
+ """Minimal model used to capture a genuine pydantic ValidationError."""
+
+ count: int
+
+
def _make_pipe_job() -> PipeJob:
return PipeJob.model_construct(
pipe=cast("PipeAbstract", _StubPipe()),
@@ -56,14 +107,17 @@ class TestPipeRouterRun:
"""Direct execution is a single pipeline-level attempt: a transient CogtError is not retried.
Pins the "direct = single attempt" contract against a future re-introduction of a retry loop.
+ The error leaves located at the pipe, chained to the CogtError, and still reports as it.
"""
error = CogtError(message="rate limited", error_category=InferenceErrorCategory.TRANSIENT)
router = _StubPipeRouter(error=error)
- with pytest.raises(CogtError) as exc_info:
+ with pytest.raises(PipeRouterError) as exc_info:
await router.run(_make_pipe_job())
- assert exc_info.value is error
+ assert exc_info.value.__cause__ is error
+ assert exc_info.value.to_error_report().error_type == "CogtError"
+ assert exc_info.value.to_error_report().retryable is True
assert router.call_count == 1
async def test_pipe_run_error_wraps_as_pipe_router_error(self) -> None:
@@ -82,3 +136,116 @@ class TestPipeRouterRun:
assert exc_info.value.pipe_code == "stub_pipe"
assert exc_info.value.pipe_stack == ["stub_pipe"]
assert router.call_count == 1
+
+ async def test_any_pipelex_error_is_located_with_its_own_report(self) -> None:
+ """A PipelexError that is neither a CogtError nor a PipeRunError is located too, and reports as itself."""
+ stuff_error = StuffFactoryError("Error combining stuffs")
+ router = _StubPipeRouter(error=stuff_error)
+
+ with pytest.raises(PipeRouterError) as exc_info:
+ await router.run(_make_pipe_job())
+
+ located = exc_info.value
+ assert located.__cause__ is stuff_error
+ assert located.pipe_code == "stub_pipe"
+ assert located.pipe_stack == ["stub_pipe"]
+ assert located.message == "Pipe 'stub_pipe' failed: Error combining stuffs"
+ report = located.to_error_report()
+ assert report.error_type == "StuffFactoryError"
+ assert report.message == "Pipe 'stub_pipe' failed: Error combining stuffs"
+
+ async def test_foreign_exception_is_located_as_unexpected_error(self) -> None:
+ """A non-PipelexError is wrapped into a PipelexUnexpectedError naming its class, never caller-facing."""
+ foreign_error = ValueError("unexpected value")
+ router = _StubPipeRouter(error=foreign_error)
+
+ with pytest.raises(PipeRouterError) as exc_info:
+ await router.run(_make_pipe_job())
+
+ unexpected = exc_info.value.__cause__
+ assert isinstance(unexpected, PipelexUnexpectedError)
+ assert unexpected.__cause__ is foreign_error
+ assert unexpected.message == "ValueError: unexpected value"
+ report = exc_info.value.to_error_report()
+ assert report.error_type == "PipelexUnexpectedError"
+ assert report.message == "Pipe 'stub_pipe' failed: ValueError: unexpected value"
+ assert report.caller_facing_message is False
+
+ async def test_pydantic_validation_error_keeps_its_readable_rendering(self) -> None:
+ """A pydantic ValidationError is named and rendered the way the runner renders one."""
+ with pytest.raises(ValidationError) as validation_info:
+ _MiniPayload(count="not-a-number") # pyright: ignore[reportArgumentType]
+ router = _StubPipeRouter(error=validation_info.value)
+
+ with pytest.raises(PipeRouterError) as exc_info:
+ await router.run(_make_pipe_job())
+
+ unexpected = exc_info.value.__cause__
+ assert isinstance(unexpected, PipelexUnexpectedError)
+ assert unexpected.message == f"ValidationError: {format_pydantic_validation_error(validation_info.value)}"
+
+ async def test_already_located_failure_keeps_the_innermost_location(self) -> None:
+ """A failure a router below already located passes through untouched: the innermost location wins."""
+ inner_failure = PipeRouterError(
+ message="Pipe 'inner' failed (outer → inner): boom",
+ run_mode=PipeRunMode.LIVE,
+ pipe_code="inner",
+ output_name=None,
+ pipe_stack=["outer", "inner"],
+ )
+ router = _StubPipeRouter(error=inner_failure)
+
+ with pytest.raises(PipeRouterError) as exc_info:
+ await router.run(_make_pipe_job())
+
+ assert exc_info.value is inner_failure
+
+ async def test_a_host_router_rebuilding_the_far_location_is_not_located_again(self) -> None:
+ """A located failure the hook rebuilds from a packed report and location passes through, located once."""
+ root_report = CogtError(message="rate limited", error_category=InferenceErrorCategory.TRANSIENT).to_error_report()
+ router = _RelocatingHostRouter(
+ error=RuntimeError("child workflow failed"),
+ packed_report=root_report,
+ packed_pipe_code="leaf",
+ packed_pipe_stack=["flow", "ctrl", "leaf"],
+ )
+
+ with pytest.raises(PipeRouterError) as exc_info:
+ await router.run(_make_pipe_job())
+
+ assert exc_info.value.pipe_code == "leaf"
+ assert isinstance(exc_info.value.__cause__, _RecoveredReportCarrierError)
+ report = exc_info.value.to_error_report()
+ assert report.error_type == "CogtError"
+ assert report.message == "Pipe 'leaf' failed (flow → ctrl → leaf): rate limited"
+
+ async def test_a_foreign_exception_raised_from_an_older_location_is_located_here(self) -> None:
+ """A foreign exception raised from an earlier located failure is a new failure: converted and located at this pipe."""
+ older_location = PipeRouterError(
+ message="Pipe 'older_pipe' failed: combine failed",
+ run_mode=PipeRunMode.LIVE,
+ pipe_code="older_pipe",
+ output_name=None,
+ pipe_stack=["older_pipe"],
+ )
+ foreign_failure = KeyError("new failure")
+ foreign_failure.__cause__ = older_location
+ router = _StubPipeRouter(error=foreign_failure)
+
+ with pytest.raises(PipeRouterError) as exc_info:
+ await router.run(_make_pipe_job())
+
+ assert exc_info.value.pipe_code == _StubPipe.code
+ assert isinstance(exc_info.value.__cause__, PipelexUnexpectedError)
+ assert exc_info.value.__cause__.__cause__ is foreign_failure
+ assert exc_info.value.to_error_report().error_type == "PipelexUnexpectedError"
+
+ async def test_a_host_router_can_let_a_failure_through(self) -> None:
+ """A host router whose hook answers None sees its transport's exception propagate unchanged."""
+ control_flow_error = RuntimeError("cancelled by the host runtime")
+ router = _PassThroughRouter(error=control_flow_error)
+
+ with pytest.raises(RuntimeError) as exc_info:
+ await router.run(_make_pipe_job())
+
+ assert exc_info.value is control_flow_error
diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py b/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py
index 999946ed6..d925ec66a 100644
--- a/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py
+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_planner.py
@@ -11,8 +11,8 @@ raise sites only), ``expected_inputs``/``declared_inputs`` for ``sync-controller
import pytest
from pipelex.core.exceptions import PipesAndConceptValidationErrorData
-from pipelex.pipeline.fixes.planner import plan_fix_for_pipe_validation_error
-from pipelex.suggested_fix import DeleteKeyOp, EnsureTableOp, FixSafety, SetKeyOp
+from pipelex.pipeline.fixes.planner import KNOWN_FIX_CODES, RENAME_MODEL_FIX_CODE, plan_fix_for_pipe_validation_error
+from pipelex.suggested_fix import DeleteKeyOp, EnsureTableOp, FixSafety, RemapValueOp, SetKeyOp
from pipelex.validation_error_types import PipeValidationErrorType
# The inputs table of the pipe every input-drift case below is built around.
@@ -57,6 +57,26 @@ def _input_drift_error_data(
)
+def _unknown_model_error_data(
+ *,
+ suggestions: list[str] | None,
+ field_name: str | None = "model",
+ model_reference: str | None = "@best-sonet",
+) -> PipesAndConceptValidationErrorData:
+ return PipesAndConceptValidationErrorData(
+ error_type=PipeValidationErrorType.UNKNOWN_MODEL,
+ domain_code="tide_tables",
+ source="main.mthds",
+ pipe_code="write_tide_note",
+ field_name=field_name,
+ message="unknown model",
+ field_path="pipe.write_tide_note.model",
+ model_reference=model_reference,
+ model_type="llm",
+ suggestions=suggestions,
+ )
+
+
class TestFixPlanner:
def test_concept_mismatch_yields_match_sequence_output_fix(self) -> None:
"""An enriched INADEQUATE_OUTPUT_CONCEPT yields a SAFE set_key fix on the pipe's output."""
@@ -189,3 +209,34 @@ class TestFixPlanner:
"""Without a pipe locator there is no TOML table to patch → no fix."""
fix = plan_fix_for_pipe_validation_error(_input_drift_error_data(pipe_code=None, expected_inputs={"text": "Text"}, declared_inputs={}))
assert fix is None
+
+ def test_unknown_model_with_one_suggestion_yields_rename_model_fix(self) -> None:
+ """One close match in the deck is the one obvious correction: remap the field from the reference as written."""
+ fix = plan_fix_for_pipe_validation_error(_unknown_model_error_data(suggestions=["@best-gpt"]))
+ assert fix is not None
+ assert fix.fix_code == RENAME_MODEL_FIX_CODE
+ assert fix.safety == FixSafety.UNSAFE
+ assert RENAME_MODEL_FIX_CODE not in KNOWN_FIX_CODES, "an unsafe code is never selectable: the fix loop would skip it"
+ assert fix.source == "main.mthds"
+ assert fix.ops == [RemapValueOp(table_path=["pipe", "write_tide_note"], key="model", mapping={"@best-sonet": "@best-gpt"})]
+ assert "'@best-sonet'" in fix.description
+ assert "'@best-gpt'" in fix.description
+
+ def test_unknown_model_fix_rewrites_the_field_that_named_it(self) -> None:
+ fix = plan_fix_for_pipe_validation_error(_unknown_model_error_data(suggestions=["@best-gpt"], field_name="model_to_structure"))
+ assert fix is not None
+ assert fix.ops == [RemapValueOp(table_path=["pipe", "write_tide_note"], key="model_to_structure", mapping={"@best-sonet": "@best-gpt"})]
+
+ @pytest.mark.parametrize("suggestions", [None, [], ["$writing-factual", "$writing-creative"]])
+ def test_unknown_model_without_exactly_one_suggestion_yields_none(self, suggestions: list[str] | None) -> None:
+ """No match leaves nothing to write, and several leave the choice to the author."""
+ assert plan_fix_for_pipe_validation_error(_unknown_model_error_data(suggestions=suggestions)) is None
+
+ def test_unknown_model_without_its_locators_yields_none(self) -> None:
+ assert plan_fix_for_pipe_validation_error(_unknown_model_error_data(suggestions=["@best-gpt"], field_name=None)) is None
+ assert plan_fix_for_pipe_validation_error(_unknown_model_error_data(suggestions=["@best-gpt"], model_reference=None)) is None
+
+ def test_uncoded_pipe_error_yields_none(self) -> None:
+ """A located refusal with no closed code (the cascade's general arm) has no fix to plan."""
+ error_data = PipesAndConceptValidationErrorData(pipe_code="write_tide_note", message="refused", field_path="")
+ assert plan_fix_for_pipe_validation_error(error_data) is None
diff --git a/tests/unit/pipelex/pipeline/test_bundle_validator.py b/tests/unit/pipelex/pipeline/test_bundle_validator.py
index 8aefbfb00..5a86abf75 100644
--- a/tests/unit/pipelex/pipeline/test_bundle_validator.py
+++ b/tests/unit/pipelex/pipeline/test_bundle_validator.py
@@ -17,7 +17,8 @@ from pytest_mock import MockerFixture
from pipelex.base_exceptions import PipelexError
from pipelex.core.pipes.exceptions import PipeRunError
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
-from pipelex.pipe_run.exceptions import DryRunError
+from pipelex.pipe_run.exceptions import DryRunError, PipeRouterError
+from pipelex.pipe_run.located_failure import make_unexpected_failure
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus
from pipelex.system.caller_identity import CallerIdentity, get_current_caller_identity, scoped_caller_identity
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -27,11 +28,17 @@ from pipelex.system.telemetry.events import EventName, EventProperty
_CALLER = CallerIdentity(user_id="caller-7", extras={"organization": "org_caller"})
+def _failing_refs(dry_run_error: DryRunError) -> list[str]:
+ """The ``domain.code`` refs of the pipes a ``DryRunError`` reports as failing, in order."""
+ return [f"{failure.domain_code}.{failure.pipe_code}" for failure in dry_run_error.failures]
+
+
class TestBundleValidator:
def _make_pipe(self, mocker: MockerFixture, *, code: str, pipe_ref: str, is_signature: bool = False):
pipe = mocker.MagicMock()
pipe.code = code
pipe.pipe_ref = pipe_ref
+ pipe.domain_code = pipe_ref.rsplit(".", maxsplit=1)[0]
pipe.is_signature = is_signature
pipe.pipe_dependencies.return_value = set()
pipe.validate_with_libraries.return_value = None
@@ -123,7 +130,7 @@ class TestBundleValidator:
with pytest.raises(DryRunError) as exc_info:
await validator.validate_pipes([pipe], library_id="lib-1")
- assert "dom.allowed_pipe" in str(exc_info.value)
+ assert _failing_refs(exc_info.value) == ["dom.allowed_pipe"]
@pytest.mark.asyncio
async def test_unexpected_validation_error_raises_dry_run_error(self, mocker: MockerFixture) -> None:
@@ -141,7 +148,7 @@ class TestBundleValidator:
with pytest.raises(DryRunError) as exc_info:
await validator.validate_pipes([pipe], library_id="lib-1")
- assert "dom.bad_pipe" in str(exc_info.value)
+ assert _failing_refs(exc_info.value) == ["dom.bad_pipe"]
@pytest.mark.asyncio
async def test_widening_non_dependency_error_does_not_abort_remaining_pipes(self, mocker: MockerFixture) -> None:
@@ -158,8 +165,7 @@ class TestBundleValidator:
# The second pipe ran (no abort) — both were executed before the aggregate raise.
assert pipe_run.run.call_count == 2
- assert "dom.boom_pipe" in str(exc_info.value)
- assert "dom.ok_pipe" not in str(exc_info.value)
+ assert _failing_refs(exc_info.value) == ["dom.boom_pipe"]
@pytest.mark.asyncio
async def test_collect_all_unexpected_failures_reported(self, mocker: MockerFixture) -> None:
@@ -172,9 +178,7 @@ class TestBundleValidator:
with pytest.raises(DryRunError) as exc_info:
await validator.validate_pipes([pipe_a, pipe_b], library_id="lib-1")
- message = str(exc_info.value)
- assert "dom.a_pipe" in message
- assert "dom.b_pipe" in message
+ assert _failing_refs(exc_info.value) == ["dom.a_pipe", "dom.b_pipe"]
@pytest.mark.asyncio
async def test_strict_mode_excludes_signature_pipes_from_sweep(self, mocker: MockerFixture) -> None:
@@ -201,6 +205,23 @@ class TestBundleValidator:
assert results["dom.sig_pipe"].status.is_success
prepare_mock.assert_called_once()
+ @pytest.mark.asyncio
+ async def test_foreign_exception_located_by_the_router_propagates(self, mocker: MockerFixture) -> None:
+ """A programming bug a pipe raised, located by the router, is not recorded as the bundle's failure."""
+ validator, _telemetry, _prepare, pipe_run = self._patch_env(mocker)
+ unexpected_failure = make_unexpected_failure(error=KeyError("foo"))
+ located = PipeRouterError.make_located(
+ failure=unexpected_failure, run_mode=PipeRunMode.DRY, pipe_code="buggy_pipe", output_name=None, pipe_stack=["buggy_pipe"]
+ )
+ located.__cause__ = unexpected_failure
+ pipe_run.run = mocker.AsyncMock(side_effect=located)
+ pipe = self._make_pipe(mocker, code="buggy_pipe", pipe_ref="dom.buggy_pipe")
+
+ with pytest.raises(PipeRouterError) as exc_info:
+ await validator.validate_pipes([pipe], library_id="lib-1")
+
+ assert exc_info.value is located
+
@pytest.mark.asyncio
async def test_wiring_error_propagates(self, mocker: MockerFixture) -> None:
# The static wiring pass runs first and can raise (real validate_with_libraries raises
diff --git a/tests/unit/pipelex/pipeline/test_dry_run_failure_location.py b/tests/unit/pipelex/pipeline/test_dry_run_failure_location.py
new file mode 100644
index 000000000..19c02fda0
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_dry_run_failure_location.py
@@ -0,0 +1,184 @@
+from pathlib import Path
+from typing import ClassVar
+
+import pytest
+from polyfactory.exceptions import FactoryException
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import ErrorDomain, PipelexError
+from pipelex.core.exceptions import DryRunFailureErrorData
+from pipelex.core.pipes.exceptions import PipeRunError
+from pipelex.pipe_run.exceptions import DryRunError, PipeRouterError
+from pipelex.pipeline.bundle_validator import (
+ BundleValidator,
+ DryRunOutput,
+ DryRunStatus,
+ _DryRunSweepRouter, # pyright: ignore[reportPrivateUsage]
+ _failing_pipe_recorder, # pyright: ignore[reportPrivateUsage]
+ _FailingPipeRecorder, # pyright: ignore[reportPrivateUsage]
+)
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+
+class _CallerFacingMethodFaultError(PipelexError):
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message: ClassVar[bool] = True
+
+
+class _StorageFaultError(PipelexError):
+ error_domain = ErrorDomain.CONFIG
+
+
+class TestDryRunFailureLocation:
+ def _make_pipe(self, mocker: MockerFixture, *, pipe_ref: str):
+ domain_code, code = pipe_ref.rsplit(".", maxsplit=1)
+ pipe = mocker.MagicMock()
+ pipe.code = code
+ pipe.domain_code = domain_code
+ pipe.pipe_ref = pipe_ref
+ return pipe
+
+ def test_the_innermost_failing_pipe_is_found_through_the_cause_chain(self, mocker: MockerFixture) -> None:
+ """A controller failing because a pipe it ran failed is attributed to that pipe, however it was wrapped."""
+ inner_pipe = self._make_pipe(mocker, pipe_ref="board.analyze_topic")
+ outer_pipe = self._make_pipe(mocker, pipe_ref="board.run_workshop")
+ inner_error = _CallerFacingMethodFaultError("the combine failed")
+ outer_error = PipeRouterError(message="the step failed", run_mode=PipeRunMode.DRY, pipe_code="run_workshop", output_name=None, pipe_stack=[])
+ outer_error.__cause__ = inner_error
+
+ recorder = _FailingPipeRecorder(tolerated_pipe_refs=frozenset())
+ recorder.record(error=inner_error, pipe=inner_pipe)
+ recorder.record(error=outer_error, pipe=outer_pipe)
+
+ assert recorder.find_failing_pipe(error=outer_error) is inner_pipe
+ assert recorder.find_failing_pipe(error=_CallerFacingMethodFaultError("unrelated")) is None
+
+ def test_a_failure_at_a_pipe_allowed_to_fail_is_noted_at_the_next_pipe_outward(self, mocker: MockerFixture) -> None:
+ """However deep the controllers, a tolerated pipe's failure is noted once, at the innermost pipe that may not fail."""
+ tolerated_pipe = self._make_pipe(mocker, pipe_ref="board.analyze_topic")
+ middle_pipe = self._make_pipe(mocker, pipe_ref="board.run_workshop")
+ outer_pipe = self._make_pipe(mocker, pipe_ref="board.host_workshop")
+ inner_error = _CallerFacingMethodFaultError("the combine failed")
+ middle_error = PipeRouterError(message="the step failed", run_mode=PipeRunMode.DRY, pipe_code="run_workshop", output_name=None, pipe_stack=[])
+ middle_error.__cause__ = inner_error
+
+ recorder = _FailingPipeRecorder(tolerated_pipe_refs=frozenset(["board.analyze_topic"]))
+ recorder.record(error=inner_error, pipe=tolerated_pipe)
+ recorder.record(error=middle_error, pipe=middle_pipe)
+ recorder.record(error=middle_error, pipe=outer_pipe)
+
+ assert recorder.find_failing_pipe(error=middle_error) is middle_pipe
+ assert recorder.find_failing_pipe(error=inner_error) is None
+
+ @pytest.mark.asyncio
+ async def test_the_sweep_router_notes_the_pipe_a_failure_left(self, mocker: MockerFixture) -> None:
+ pipe = self._make_pipe(mocker, pipe_ref="board.analyze_topic")
+ failure = _CallerFacingMethodFaultError("the combine failed")
+ mocker.patch.object(_DryRunSweepRouter, "_run_pipe_job", side_effect=failure)
+ pipe_job = mocker.MagicMock()
+ pipe_job.pipe = pipe
+ recorder = _FailingPipeRecorder(tolerated_pipe_refs=frozenset())
+ token = _failing_pipe_recorder.set(recorder)
+ try:
+ # The router locates every failure of its pipe as a PipeRouterError chained to it.
+ with pytest.raises(PipeRouterError) as raised:
+ await _DryRunSweepRouter().run(pipe_job)
+ finally:
+ _failing_pipe_recorder.reset(token)
+
+ assert raised.value.__cause__ is failure
+ assert recorder.find_failing_pipe(error=raised.value) is pipe
+
+ @pytest.mark.parametrize(
+ ("error", "expected_text"),
+ [
+ (_CallerFacingMethodFaultError("branch 'ideas' is plural"), "branch 'ideas' is plural"),
+ (_StorageFaultError("bucket s3://internal-bucket refused the write"), _StorageFaultError.title()),
+ (PipeRunError(message="expression rendered nothing", run_mode=PipeRunMode.DRY, pipe_code="route"), PipeRunError.title()),
+ (FactoryException("polyfactory internals"), "The dry run could not generate mock data for this pipe"),
+ ],
+ ids=["caller_facing", "config_fault", "not_caller_facing", "foreign"],
+ )
+ @pytest.mark.asyncio
+ async def test_a_failure_keeps_its_text_only_when_it_is_caller_facing(self, mocker: MockerFixture, error: Exception, expected_text: str) -> None:
+ mocker.patch("pipelex.pipeline.bundle_validator.get_telemetry_manager")
+ mocker.patch("pipelex.pipeline.bundle_validator.get_config").return_value.inference.dry_run.allowed_to_fail_pipes = ["board.analyze_topic"]
+ mocker.patch("pipelex.pipeline.bundle_validator.prepare_pipe_job")
+ pipe_run = mocker.MagicMock()
+ pipe_run.run = mocker.AsyncMock(side_effect=error)
+ mocker.patch("pipelex.pipeline.bundle_validator.PipeRun", return_value=pipe_run)
+ pipe = self._make_pipe(mocker, pipe_ref="board.analyze_topic")
+ pipe.is_signature = False
+
+ results = await BundleValidator().validate_pipes([pipe], library_id="lib-1")
+
+ failure = results["board.analyze_topic"].failure
+ assert failure is not None
+ assert (failure.pipe_code, failure.domain_code) == ("analyze_topic", "board")
+ assert failure.message == f"Pipe 'analyze_topic' failed its dry run: {expected_text}"
+
+ def test_a_failure_reached_through_a_controller_is_kept_once_its_own_preferred(self) -> None:
+ inner_failure_via_outer = DryRunFailureErrorData(pipe_code="analyze_topic", domain_code="board", message="via the sequence")
+ inner_failure_own = DryRunFailureErrorData(pipe_code="analyze_topic", domain_code="board", message="its own")
+ other_failure = DryRunFailureErrorData(pipe_code="publish", domain_code="board", message="publish failed")
+ unexpected_failures = {
+ "board.run_workshop": DryRunOutput(
+ pipe_code="run_workshop", pipe_ref="board.run_workshop", status=DryRunStatus.FAILURE, failure=inner_failure_via_outer
+ ),
+ "board.publish": DryRunOutput(pipe_code="publish", pipe_ref="board.publish", status=DryRunStatus.FAILURE, failure=other_failure),
+ "board.analyze_topic": DryRunOutput(
+ pipe_code="analyze_topic", pipe_ref="board.analyze_topic", status=DryRunStatus.FAILURE, failure=inner_failure_own
+ ),
+ }
+
+ failures = BundleValidator._located_failures( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ unexpected_failures=unexpected_failures
+ )
+
+ assert failures == [inner_failure_own, other_failure]
+
+ @pytest.mark.asyncio
+ async def test_a_failure_met_at_a_pipe_allowed_to_fail_stays_on_the_swept_pipe(self, mocker: MockerFixture) -> None:
+ """The tolerated pipe is not the failure: the swept pipe that failed because of it is."""
+ mocker.patch("pipelex.pipeline.bundle_validator.get_telemetry_manager")
+ mocker.patch("pipelex.pipeline.bundle_validator.get_config").return_value.inference.dry_run.allowed_to_fail_pipes = ["board.analyze_topic"]
+ mocker.patch("pipelex.pipeline.bundle_validator.prepare_pipe_job")
+ inner_pipe = self._make_pipe(mocker, pipe_ref="board.analyze_topic")
+ failure = _CallerFacingMethodFaultError("the combine failed")
+
+ def _fail_inside_the_inner_pipe(_pipe_job: object) -> None:
+ recorder = _failing_pipe_recorder.get()
+ assert recorder is not None
+ recorder.record(error=failure, pipe=inner_pipe)
+ raise failure
+
+ pipe_run = mocker.MagicMock()
+ pipe_run.run = mocker.AsyncMock(side_effect=_fail_inside_the_inner_pipe)
+ mocker.patch("pipelex.pipeline.bundle_validator.PipeRun", return_value=pipe_run)
+ outer_pipe = self._make_pipe(mocker, pipe_ref="board.run_workshop")
+ outer_pipe.is_signature = False
+
+ with pytest.raises(DryRunError) as exc_info:
+ await BundleValidator().validate_pipes([outer_pipe], library_id="lib-1")
+
+ (located_failure,) = exc_info.value.failures
+ assert (located_failure.pipe_code, located_failure.domain_code) == ("run_workshop", "board")
+
+ @pytest.mark.asyncio
+ async def test_a_source_the_library_manager_gives_as_a_path_is_kept_as_text(self, mocker: MockerFixture) -> None:
+ """Injected managers written against the previous protocol may still return ``Path``."""
+ mocker.patch("pipelex.pipeline.bundle_validator.get_telemetry_manager")
+ mocker.patch("pipelex.pipeline.bundle_validator.get_config").return_value.inference.dry_run.allowed_to_fail_pipes = ["board.analyze_topic"]
+ mocker.patch("pipelex.pipeline.bundle_validator.prepare_pipe_job")
+ mocker.patch("pipelex.pipeline.bundle_validator.get_library_manager").return_value.get_pipe_source.return_value = Path("board.mthds")
+ pipe_run = mocker.MagicMock()
+ pipe_run.run = mocker.AsyncMock(side_effect=_CallerFacingMethodFaultError("the combine failed"))
+ mocker.patch("pipelex.pipeline.bundle_validator.PipeRun", return_value=pipe_run)
+ pipe = self._make_pipe(mocker, pipe_ref="board.analyze_topic")
+ pipe.is_signature = False
+
+ results = await BundleValidator().validate_pipes([pipe], library_id="lib-1")
+
+ failure = results["board.analyze_topic"].failure
+ assert failure is not None
+ assert failure.source == "board.mthds"
diff --git a/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py b/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py
new file mode 100644
index 000000000..719119620
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py
@@ -0,0 +1,133 @@
+from typing import ClassVar
+
+import pytest
+
+from pipelex.base_exceptions import ErrorDomain, PipelexError, SecurityError, ValidationErrorCategory, ValidationErrorItem
+from pipelex.cogt.model_backends.model_type import ModelType
+from pipelex.core.exceptions import DryRunFailureErrorData
+from pipelex.core.pipes.exceptions import PipeLoadRefusalError, PipeOperatorModelChoiceError
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
+from pipelex.validation_error_types import PipeValidationErrorType
+
+
+class _CallerFacingInputRefusalError(PipelexError):
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
+
+
+class _InternalInputRefusalError(PipelexError):
+ error_domain = ErrorDomain.INPUT
+ _declared_title: ClassVar[str | None] = "Harbour board refusal"
+
+
+class _RuntimeFaultError(PipelexError):
+ error_domain = ErrorDomain.RUNTIME
+
+
+class _UnclassifiedFaultError(PipelexError):
+ pass
+
+
+class _InputSecurityRefusalError(SecurityError):
+ error_domain = ErrorDomain.INPUT
+ _authors_caller_facing_message = True
+
+
+def _verdict_items(refusal: BaseException) -> tuple[ValidateBundleError, list[ValidationErrorItem]]:
+ with pytest.raises(ValidateBundleError) as raised, translate_to_validate_bundle_error():
+ raise refusal
+ verdict = raised.value
+ assert verdict.__cause__ is refusal
+ return verdict, list(verdict.to_error_report().validation_errors or [])
+
+
+class TestRefusalVerdictArms:
+ def test_unlocated_caller_facing_input_refusal_is_one_blueprint_item_keeping_its_message(self) -> None:
+ verdict, items = _verdict_items(_CallerFacingInputRefusalError("The tide table names a harbour that does not exist."))
+
+ assert items == [
+ ValidationErrorItem(
+ category=ValidationErrorCategory.BLUEPRINT_VALIDATION,
+ message="The tide table names a harbour that does not exist.",
+ )
+ ]
+ assert verdict.message == "The tide table names a harbour that does not exist."
+
+ def test_non_caller_facing_input_refusal_is_named_by_its_title(self) -> None:
+ _, items = _verdict_items(_InternalInputRefusalError("internal detail: registry slot 7 is stale"))
+
+ assert [item.message for item in items] == ["Harbour board refusal"]
+
+ def test_located_refusal_is_one_pipe_item_with_pipe_domain_and_source(self) -> None:
+ cause = _InternalInputRefusalError("internal detail: registry slot 7 is stale")
+ located = PipeLoadRefusalError.make_from_refusal(refusal=cause, pipe_code="write_tide_note", domain_code="tide_tables", source="tides.mthds")
+
+ _, items = _verdict_items(located)
+
+ assert items == [
+ ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_VALIDATION,
+ pipe_code="write_tide_note",
+ domain_code="tide_tables",
+ source="tides.mthds",
+ message="Pipe 'write_tide_note' could not be loaded: Harbour board refusal",
+ )
+ ]
+
+ def test_unknown_model_is_one_unknown_model_item(self) -> None:
+ refusal = PipeOperatorModelChoiceError(
+ "Pipe 'write_tide_note' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck",
+ pipe_type="PipeLLM",
+ pipe_code="write_tide_note",
+ domain_code="tide_tables",
+ field_name="model",
+ model_type=ModelType.LLM,
+ model_choice="gpt-5.1",
+ suggestions=["gpt-5.5", "gpt-5.4"],
+ source="tides.mthds",
+ )
+
+ _, items = _verdict_items(refusal)
+
+ assert items == [
+ ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_VALIDATION,
+ error_type=PipeValidationErrorType.UNKNOWN_MODEL,
+ pipe_code="write_tide_note",
+ domain_code="tide_tables",
+ source="tides.mthds",
+ field_path="pipe.write_tide_note.model",
+ field_name="model",
+ model_reference="gpt-5.1",
+ model_type="llm",
+ suggestions=["gpt-5.5", "gpt-5.4"],
+ message="Pipe 'write_tide_note' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck",
+ )
+ ]
+
+ @pytest.mark.parametrize(
+ "fault",
+ [
+ _RuntimeFaultError("the worker lost its connection"),
+ _UnclassifiedFaultError("something nobody classified"),
+ _InputSecurityRefusalError("a fetch was blocked"),
+ ],
+ ids=["runtime", "unclassified", "security"],
+ )
+ def test_no_verdict_faults_propagate_unchanged(self, fault: PipelexError) -> None:
+ """A failure of the tool or its environment, and a security refusal, are never reported as the bundle's fault."""
+ with pytest.raises(type(fault)) as raised, translate_to_validate_bundle_error():
+ raise fault
+ assert raised.value is fault
+
+ def test_a_produced_verdict_passes_through_unwrapped(self) -> None:
+ verdict = ValidateBundleError(
+ message="already a verdict",
+ dry_run_failures=[DryRunFailureErrorData(pipe_code="route_parcel", message="the round has no lane")],
+ )
+
+ with pytest.raises(ValidateBundleError) as raised, translate_to_validate_bundle_error():
+ raise verdict
+
+ assert raised.value is verdict
diff --git a/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py b/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py
index 2af52fa0a..842c9f417 100644
--- a/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py
+++ b/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py
@@ -93,6 +93,10 @@ class TestRunnerExecuteErrorPaths:
"""A PipelexError raised by the pipe run AFTER setup resolved the job is wrapped
into a PipelineExecutionError carrying the job's identity, and a FAILURE
telemetry event fires.
+
+ The failure was never located by a router, so the error names the entry pipe with an
+ empty stack — never the live stack, which has unwound by the time the runner sees it —
+ and its message is the failure's own.
"""
env = self._patch_env(mocker)
original = PipeExecutionError("boom from pipe")
@@ -109,7 +113,7 @@ class TestRunnerExecuteErrorPaths:
assert wrapped.pipe_code == "echo_pipe"
assert wrapped.output_name == "topic_out"
assert wrapped.run_mode == PipeRunMode.DRY
- assert wrapped.pipe_stack == ["root_pipe", "echo_pipe"]
+ assert wrapped.pipe_stack == []
assert wrapped.__cause__ is original
# The failure event is attributed to the run, not to the process: `run_metadata`
# is the job's own, which is what carries the caller's user id and groups.
diff --git a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
index f085f0516..cd9242e99 100644
--- a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
+++ b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
@@ -79,9 +79,9 @@ class TestRunnerValidatePlumbing:
)
async def test_library_dirs_converted_to_paths_and_allow_signatures_passthrough(self, mocker: MockerFixture) -> None:
- """Constructor library_dirs strings reach validate_bundle as Path objects; allow_signatures forwarded verbatim."""
+ """Constructor library_dirs strings reach validate_bundle as Path objects; allow_signatures and their ownership forwarded verbatim."""
env = self._patch_env(mocker, library_ids=[None, "val-lib"])
- runner = PipelexMTHDSProtocol(library_dirs=["dir_alpha", "nested/dir_beta"])
+ runner = PipelexMTHDSProtocol(library_dirs=["dir_alpha", "nested/dir_beta"], library_dirs_are_callers=True)
await runner.validate(mthds_contents=["bundle-content"], allow_signatures=True)
@@ -90,10 +90,11 @@ class TestRunnerValidatePlumbing:
mthds_sources=None,
library_dirs=[Path("dir_alpha"), Path("nested/dir_beta")],
allow_signatures=True,
+ library_dirs_are_callers=True,
)
async def test_no_library_dirs_passes_none_and_strict_default(self, mocker: MockerFixture) -> None:
- """Without constructor library_dirs, validate_bundle receives None and the strict default."""
+ """Without constructor library_dirs, validate_bundle receives None, the strict default and a host's directories."""
env = self._patch_env(mocker, library_ids=[None, "val-lib"])
runner = PipelexMTHDSProtocol()
@@ -104,6 +105,7 @@ class TestRunnerValidatePlumbing:
mthds_sources=None,
library_dirs=None,
allow_signatures=False,
+ library_dirs_are_callers=False,
)
async def test_validation_runs_with_the_protocols_caller_in_scope(self, mocker: MockerFixture) -> None:
diff --git a/tests/unit/pipelex/pipeline/test_validate_bundle_error_withholding.py b/tests/unit/pipelex/pipeline/test_validate_bundle_error_withholding.py
new file mode 100644
index 000000000..3c77986f1
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_validate_bundle_error_withholding.py
@@ -0,0 +1,108 @@
+import inspect
+from pathlib import Path
+
+import pytest
+
+from pipelex.core.exceptions import (
+ DryRunFailureErrorData,
+ PipeFactoryErrorData,
+ PipelexBundleBlueprintValidationErrorData,
+ PipesAndConceptValidationErrorData,
+)
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle_translation import HOST_LIBRARY_FILE_PLACEHOLDER, withholding_host_library_files
+from pipelex.validation_error_types import PipeFactoryErrorType
+
+_HOST_FILE = "/srv/pipelex/host-library/harbour_board.mthds"
+
+# Every channel ``ValidateBundleError`` takes. ``withholding_files`` rebuilds the verdict channel by channel, so a
+# channel added to the constructor and not carried there would be silently dropped from every withheld verdict.
+_CHANNELS = {
+ "message",
+ "pipelex_bundle_blueprint_validation_errors",
+ "pipe_factory_errors",
+ "pipe_validation_errors",
+ "pipe_concept_instantiation_errors",
+ "dry_run_failures",
+}
+
+
+def _mentioning_the_host_file(*, label: str) -> str:
+ return f"{label} in '{_HOST_FILE}'"
+
+
+class TestValidateBundleErrorWithholding:
+ def test_every_channel_of_the_verdict_is_carried(self) -> None:
+ constructor_channels = set(inspect.signature(ValidateBundleError.__init__).parameters) - {"self"}
+ assert constructor_channels == _CHANNELS, "a channel added to ValidateBundleError must be carried by withholding_files too"
+
+ def test_every_channel_names_no_withheld_file(self) -> None:
+ verdict = ValidateBundleError(
+ message=_mentioning_the_host_file(label="raw"),
+ pipelex_bundle_blueprint_validation_errors=[
+ PipelexBundleBlueprintValidationErrorData(message=_mentioning_the_host_file(label="blueprint"), source=_HOST_FILE)
+ ],
+ pipe_factory_errors=[
+ PipeFactoryErrorData(error_type=PipeFactoryErrorType.UNKNOWN_FACTORY_ERROR, message=_mentioning_the_host_file(label="factory"))
+ ],
+ pipe_validation_errors=[
+ # Located from the pipe-source map, a pipe-validation error carries its file as its field path too.
+ PipesAndConceptValidationErrorData(message=_mentioning_the_host_file(label="pipe"), source=_HOST_FILE, field_path=_HOST_FILE)
+ ],
+ pipe_concept_instantiation_errors=[
+ PipesAndConceptValidationErrorData(
+ message=_mentioning_the_host_file(label="instantiation"), source="api://bundle-0.mthds", field_path=""
+ )
+ ],
+ dry_run_failures=[DryRunFailureErrorData(pipe_code="post_notice", message=_mentioning_the_host_file(label="dry run"), source=_HOST_FILE)],
+ )
+
+ withheld = verdict.withholding_files(withheld_files={_HOST_FILE}, placeholder=HOST_LIBRARY_FILE_PLACEHOLDER)
+
+ items = withheld.to_error_report().validation_errors or []
+ assert [item.message for item in items] == [
+ f"blueprint in '{HOST_LIBRARY_FILE_PLACEHOLDER}'",
+ f"factory in '{HOST_LIBRARY_FILE_PLACEHOLDER}'",
+ f"pipe in '{HOST_LIBRARY_FILE_PLACEHOLDER}'",
+ f"instantiation in '{HOST_LIBRARY_FILE_PLACEHOLDER}'",
+ f"dry run in '{HOST_LIBRARY_FILE_PLACEHOLDER}'",
+ ]
+ # A withheld file's source is dropped; any other source is the same answer as before.
+ assert [item.source for item in items] == [None, None, None, "api://bundle-0.mthds", None]
+ assert [item.field_path for item in items] == [None, None, None, None, None]
+ assert _HOST_FILE not in withheld.message
+
+ def test_a_withheld_name_counts_only_standing_on_its_own(self) -> None:
+ # A host library directory listed relatively names its files relatively, so a host file's name can be the
+ # tail of the caller's own names, which are left alone.
+ verdict = ValidateBundleError(message="Could not load 'harbour_board.mthds' beside 'api://harbour_board.mthds' and 'old_harbour_board.mthds'")
+
+ withheld = verdict.withholding_files(withheld_files={"harbour_board.mthds"}, placeholder=HOST_LIBRARY_FILE_PLACEHOLDER)
+
+ assert (
+ withheld.message == f"Could not load '{HOST_LIBRARY_FILE_PLACEHOLDER}' beside 'api://harbour_board.mthds' and 'old_harbour_board.mthds'"
+ )
+
+ def test_nothing_to_withhold_leaves_the_verdict_as_it_reads(self) -> None:
+ verdict = ValidateBundleError(message="Pipe 'post_notice' could not be loaded")
+
+ withheld = verdict.withholding_files(withheld_files=set(), placeholder=HOST_LIBRARY_FILE_PLACEHOLDER)
+
+ assert withheld.message == "Pipe 'post_notice' could not be loaded"
+
+ def test_a_callers_source_spelled_like_a_host_file_is_kept(self, tmp_path: Path) -> None:
+ host_library_file = tmp_path / "harbour_board.mthds"
+ host_library_file.write_text('domain = "harbour_board"\ndescription = "Notices of the harbour board"\n', encoding="utf-8")
+ callers_source = str(host_library_file)
+ verdict = ValidateBundleError(
+ message="Pipe 'post_notice' could not be loaded",
+ pipe_validation_errors=[
+ PipesAndConceptValidationErrorData(message="Pipe 'post_notice' could not be loaded", source=callers_source, field_path="")
+ ],
+ )
+
+ with pytest.raises(ValidateBundleError) as raised, withholding_host_library_files(library_dirs=[tmp_path], caller_sources=[callers_source]):
+ raise verdict
+
+ (item,) = raised.value.to_error_report().validation_errors or []
+ assert item.source == callers_source
diff --git a/tests/unit/pipelex/pipeline/test_validation_errors.py b/tests/unit/pipelex/pipeline/test_validation_errors.py
index 24e8a796e..a132d73ec 100644
--- a/tests/unit/pipelex/pipeline/test_validation_errors.py
+++ b/tests/unit/pipelex/pipeline/test_validation_errors.py
@@ -12,7 +12,12 @@ import json
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
from pipelex.cli.agent_cli.commands.agent_output import extract_validation_errors
-from pipelex.core.exceptions import PipeFactoryErrorData, PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
+from pipelex.core.exceptions import (
+ DryRunFailureErrorData,
+ PipeFactoryErrorData,
+ PipelexBundleBlueprintValidationErrorData,
+ PipesAndConceptValidationErrorData,
+)
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validation_errors import build_validation_error_items
from pipelex.suggested_fix import DeleteKeyOp, RenameTableKeyOp, SetKeyOp
@@ -25,9 +30,8 @@ def _build_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:
The pipe-validation arm uses ``pipe_validation_error_data`` (pipe validation **plus**
pipe/concept instantiation errors) — the same combined accessor both real call sites
(``ValidateBundleError.to_error_report`` and the CLI ``extract_validation_errors``) pass.
- The residual channels (``dry_run_error_message`` / ``fallback_message``) are intentionally
- omitted here so these tests pin the categorized projection in isolation; the residual behavior
- has its own dedicated tests below.
+ The dry-run failures and the ``fallback_message`` residual are intentionally omitted here so these
+ tests pin the categorized projection in isolation; they have their own dedicated tests below.
"""
return build_validation_error_items(
blueprint_errors=exc.pipelex_bundle_blueprint_validation_errors,
@@ -122,26 +126,27 @@ class TestBuildValidationErrorItems:
"""A ValidateBundleError with no categorized lists builds an empty list."""
assert _build_items(ValidateBundleError(message="no details")) == []
- def test_dry_run_residual_becomes_single_dry_run_item(self) -> None:
- """A residual dry-run failure (no categorized data) yields one ``dry_run`` item — the structured-info invariant.
-
- This is the case that previously produced a bare-message error with an empty
- ``validation_errors[]``; it now carries the message as a ``dry_run``-category item.
- It is graph-level, so it has no ``source``.
- """
+ def test_each_dry_run_failure_becomes_a_located_dry_run_item(self) -> None:
+ """Each pipe whose dry run failed yields its own ``dry_run`` item, located on that pipe."""
items = build_validation_error_items(
blueprint_errors=[],
factory_errors=[],
pipe_validation_errors=[],
- dry_run_error_message="Dry run failed: residual error",
+ dry_run_failures=[
+ DryRunFailureErrorData(
+ pipe_code="analyze", domain_code="probe", source="probe.mthds", message="Pipe 'analyze' failed its dry run: x"
+ ),
+ DryRunFailureErrorData(pipe_code="publish", domain_code="probe", message="Pipe 'publish' failed its dry run: y"),
+ ],
)
- assert [item.category for item in items] == [ValidationErrorCategory.DRY_RUN]
- assert items[0].message == "Dry run failed: residual error"
- assert items[0].error_type == "DryRunError"
- assert items[0].source is None
-
- def test_dry_run_residual_suppressed_when_categorized_data_present(self) -> None:
- """When a categorized error carries data, the dry-run residual is NOT added — the categorized items win."""
+ assert [item.category for item in items] == [ValidationErrorCategory.DRY_RUN, ValidationErrorCategory.DRY_RUN]
+ assert all(item.error_type == "DryRunError" for item in items)
+ assert (items[0].pipe_code, items[0].domain_code, items[0].source) == ("analyze", "probe", "probe.mthds")
+ assert items[0].message == "Pipe 'analyze' failed its dry run: x"
+ assert (items[1].pipe_code, items[1].source) == ("publish", None)
+
+ def test_dry_run_items_ride_beside_categorized_items(self) -> None:
+ """A dry-run failure is kept beside a categorized error: no channel hides another."""
items = build_validation_error_items(
blueprint_errors=[],
factory_errors=[
@@ -153,15 +158,19 @@ class TestBuildValidationErrorItems:
),
],
pipe_validation_errors=[],
- dry_run_error_message="should be ignored",
+ dry_run_failures=[DryRunFailureErrorData(pipe_code="pipe_y", domain_code="dom", message="Pipe 'pipe_y' failed its dry run: z")],
)
- assert [item.category for item in items] == [ValidationErrorCategory.PIPE_FACTORY]
-
- def test_to_error_report_projects_dry_run_residual(self) -> None:
- """A ``ValidateBundleError`` carrying only ``dry_run_error_message`` surfaces one ``dry_run`` item on the report."""
- report = ValidateBundleError(message="Dry run failed", dry_run_error_message="Dry run failed: residual error").to_error_report()
+ assert [item.category for item in items] == [ValidationErrorCategory.PIPE_FACTORY, ValidationErrorCategory.DRY_RUN]
+
+ def test_to_error_report_projects_dry_run_failures(self) -> None:
+ """A ``ValidateBundleError`` carrying dry-run failures surfaces one ``dry_run`` item per failure on the report."""
+ report = ValidateBundleError(
+ message="Dry run failed",
+ dry_run_failures=[DryRunFailureErrorData(pipe_code="analyze", domain_code="probe", message="Pipe 'analyze' failed its dry run: x")],
+ ).to_error_report()
assert report.validation_errors is not None
assert [item.category for item in report.validation_errors] == [ValidationErrorCategory.DRY_RUN]
+ assert report.message == "Pipe 'analyze' failed its dry run: x"
def test_fallback_message_residual_becomes_single_blueprint_item(self) -> None:
"""A parse-level failure (only a message, no categorized data) yields one ``blueprint_validation`` item.
@@ -182,13 +191,13 @@ class TestBuildValidationErrorItems:
assert items[0].error_type is None
assert items[0].source is None
- def test_dry_run_residual_wins_over_fallback_message(self) -> None:
- """When both residual channels are available, the more-specific ``dry_run`` item wins (ordering)."""
+ def test_dry_run_items_win_over_fallback_message(self) -> None:
+ """The fallback residual is a last resort: a dry-run item leaves it unused."""
items = build_validation_error_items(
blueprint_errors=[],
factory_errors=[],
pipe_validation_errors=[],
- dry_run_error_message="Dry run failed: residual error",
+ dry_run_failures=[DryRunFailureErrorData(pipe_code="analyze", message="Pipe 'analyze' failed its dry run: x")],
fallback_message="should not be used",
)
assert [item.category for item in items] == [ValidationErrorCategory.DRY_RUN]
diff --git a/tests/unit/pipelex/pipeline/test_validation_render.py b/tests/unit/pipelex/pipeline/test_validation_render.py
index 599d14db4..684404fdb 100644
--- a/tests/unit/pipelex/pipeline/test_validation_render.py
+++ b/tests/unit/pipelex/pipeline/test_validation_render.py
@@ -11,6 +11,7 @@ from pipelex.pipeline.validation_render import (
format_validate_markdown,
format_validation_error_items_markdown,
render_invalid_validation_markdown,
+ suggested_fix_label,
)
from pipelex.suggested_fix import FixSafety, SuggestedFix
from pipelex.validation_error_types import PipeValidationErrorType, ValidationResidualErrorType
@@ -194,6 +195,52 @@ class TestValidationRender:
assert "## Dry run error" in markdown
assert "Dry run failed: boom." in markdown
+ def test_suggested_fix_label_says_when_a_fix_is_unsafe(self):
+ """A safe fix is a plain `Suggested fix`; an unsafe one says it is unsafe and needs confirming."""
+ safe_fix = SuggestedFix(fix_code="match-sequence-output", description="d", safety=FixSafety.SAFE, ops=[])
+ unsafe_fix = SuggestedFix(fix_code="rename-model", description="d", safety=FixSafety.UNSAFE, ops=[])
+
+ assert suggested_fix_label(fix=safe_fix) == "Suggested fix"
+ assert suggested_fix_label(fix=unsafe_fix) == "Suggested fix (unsafe, confirm before applying)"
+
+ def test_invalid_report_markdown_marks_an_unsafe_fix(self):
+ """The hosted `rendered_markdown` path labels an unsafe wire fix, next to a safe one left plain."""
+ report: dict[str, Any] = {
+ "is_valid": False,
+ "message": "MTHDS validation found errors",
+ "validation_errors": [
+ {
+ "category": "pipe_validation",
+ "error_type": "inadequate_output_multiplicity",
+ "message": "Output mismatch.",
+ "pipe_code": "summarize",
+ "suggested_fix": {
+ "fix_code": "match-sequence-output",
+ "description": "Set output of pipe 'summarize' to 'Contract'",
+ "safety": "safe",
+ "ops": [],
+ },
+ },
+ {
+ "category": "pipe_validation",
+ "error_type": "unknown_model",
+ "message": "Model handle 'gpt-5.1' was not found in the model deck",
+ "pipe_code": "write",
+ "suggested_fix": {
+ "fix_code": "rename-model",
+ "description": "Replace model 'gpt-5.1' of pipe 'write' with 'gpt-5', its one close match in the model deck",
+ "safety": "unsafe",
+ "ops": [],
+ },
+ },
+ ],
+ }
+
+ markdown = render_invalid_validation_markdown(report)
+
+ assert " - 💡 Suggested fix: Set output of pipe 'summarize' to 'Contract'" in markdown
+ assert " - 💡 Suggested fix (unsafe, confirm before applying): Replace model 'gpt-5.1' of pipe 'write' with 'gpt-5'" in markdown
+
def test_build_fix_command_echoes_library_dirs_and_signatures(self):
"""`build_fix_command` shell-joins the executable, path, each `-L` dir, and `--allow-signatures`."""
command = build_fix_command(
diff --git a/tests/unit/pipelex/tools/typing/test_format_pydantic_validation_error.py b/tests/unit/pipelex/tools/typing/test_format_pydantic_validation_error.py
index 98bc305b4..25a91e25c 100644
--- a/tests/unit/pipelex/tools/typing/test_format_pydantic_validation_error.py
+++ b/tests/unit/pipelex/tools/typing/test_format_pydantic_validation_error.py
@@ -129,3 +129,20 @@ class TestFormatPydanticValidationError:
assert "bad_tone" in formatted
assert "'length'" in formatted
assert "bad_length" in formatted
+
+ def test_every_error_is_rendered_beside_the_listed_kinds(self) -> None:
+ """An error kind without a heading of its own is rendered even when a listed kind is present."""
+
+ class Mixed(BaseModel):
+ a: int
+ b: str
+ c: int
+
+ with pytest.raises(ValidationError) as exc:
+ Mixed.model_validate({"a": "notanint", "b": 3})
+
+ formatted = format_pydantic_validation_error(exc.value)
+ assert "Missing required fields: 'c'" in formatted
+ assert "Other validation errors:" in formatted
+ assert "a: int_parsing: Input should be a valid integer" in formatted
+ assert "b: string_type: Input should be a valid string" in formatted